# VAULT.md

本文档定义 Knowledge Vault 的工作规则。它优先服务人的长期检索，其次服务 Codex 的维护自动化。

## 1. Vault 定位

Knowledge Vault 是个人知识管理与写作工程体系中的长期层。它负责保存“值得长期留存、可被重新发现、可被重新加工”的材料，以及本仓库执行知识加工时需要遵守的本地运行规则。

它不是：

- Writing Workbench：新文章创作、评审、润色、发布闭环应进入写作工作台。
- CCPE System：Agent、Skill、Runtime、Model Card、Model Index 等 AI 认知资产工程应进入 CCPE System。
- Delivery Systems：客户项目或外部可部署系统应独立管理。

## 2. 目录职责

| 目录 | 职责 | 典型内容 |
| --- | --- | --- |
| `diary/` | 日常输入与临时想法 | 按年份保存日记、零散想法、随手记录 |
| `discussions/` | 讨论归档 | 历史文章讨论、Agent 交流、技术讨论、创意讨论、项目思考 |
| `sayings/` | 短句与表达资产 | 年度 sayings、金句、表达片段及 metadata |
| `rules/` | 面向人的模型与规则文档 | APTC、写作风格、认知模型、销售模型、教育模型 |
| `prompts/` | 提示词归档 | CCPE 历史提示词、写作提示词、评审提示词、metadata 提示词、legacy |
| `sources/` | 来源材料 | Deep Research、读书笔记、摘抄、网页原文、参考资料 |
| `work/` | 工作归档 | 内部项目、客户项目、敏感本地资料 |
| `indexes/` | 人和 Codex 共用索引 | 文章、模型、提示词、来源、项目索引 |
| `templates/` | 文档模板 | 模型文档、衍生模型、来源笔记、讨论归档、saying metadata |
| `skills/` | 知识加工能力运行层 | 调用治理、上下文治理、能力 runbook、调用模板、Knowledge 侧能力规格 |

## 3. 层级与命名

约定：

- 一级目录固定为英文系统目录。
- 二级目录优先使用英文分类名。
- 三级目录及以下可以使用中文可读目录名。

示例：

```text
rules/
  marketing-sales/
    APTC模型/
      APTC模型.md
      APTC模型-直播.md
      APTC模型-船长适配.md
```

这样可以同时满足系统稳定性和人的阅读习惯。

## 4. `rules/` 规则

`rules/` 下保存 Human Model Document。它面向人解释模型，而不是面向 Agent 调用。

一个模型族可以包含：

- 基模文档
- 衍生模型文档
- 版本说明
- 适用场景说明
- 与 CCPE Model Card 的链接说明

版本规则：

- 最高版本不一定最好。
- 多版本可以并存。
- 索引中应说明每个版本的适用场景、状态和关系。
- 不应为了“整洁”删除仍有参考价值的旧版本。

## 5. `prompts/` 规则

`prompts/` 是提示词档案，不等同于 CCPE System。

推荐目标分类：

```text
prompts/
  ccpe/
  article-writers/
  reviewers/
  metadata/
  legacy/
```

迁移旧目录时先建立映射和索引，再按文件夹移动。不要在没有清单的情况下散点移动单文件。

## 6. `discussions/` 规则

`discussions/` 保存过程记录，不承担正式文章生产流。

`discussions/` 可以包含仍在持续更新的会话记录文件。例如当前会话如果通过 VS Code 持续维护在某个 Markdown 文件中，该文件仍属于过程归档，不需要迁出到 Writing Workbench。

当前认可的讨论分类包括：

- `historical-article-discussions/`
- `historical-agent-building/`
- `model-extraction/`
- `project-thinking/`
- `committees/`
- `agents/`
- `creative/`
- `technology/`
- `training/`

其中 `agents/` 用于保存与个人 Agent 交流的过程；`creative/` 用于音乐、图片、视频等创意讨论；`technology/` 用于技术相关讨论。

## 7. `skills/` 规则

`skills/` 是 Knowledge Vault 的本地知识加工能力层。它保存“在本仓库中如何运行能力”的规则，而不是保存 CCPE canonical 资产。

它可以包含：

- 调用治理规则，例如 `invocation-policy.md`。
- 上下文治理规则，例如 `context-management-policy.md`。
- 面向具体知识加工能力的 runbook、context strategy、invocation contract。
- invocation、prompt-to-send、skill-execution-record、thread handoff 等模板。
- 本地脚本或代码型加工能力的运行说明。

它不应包含：

- CCPE System 中的 canonical Agent / Skill / Runtime 全文副本，除非 prompt-to-send 明确需要粘贴。
- 某次具体任务的大量运行日志。
- 某次具体任务的 source-map、topic-map、routing-log、topic docs 或 audit。
- 文章生产流水线。

具体任务的运行记录应放在对应工作目录，例如：

```text
discussions/viewpoint-development/{date}-{topic}/
  invocations/
  handoff/
  audits/
```

公共层只保留可复用规则和模板。若 CCPE 规则不足以真实调用 participant，必须暂停并记录阻塞状态，不能模拟正式 Agent 输出。

## 8. `sources/` 规则

`sources/` 合并旧的 sources 和 notes 职责。它保存外部材料和对材料的初步处理。

推荐分类：

```text
sources/
  deep-research/
  reading-notes/
  excerpts/
  clipped-articles/
  web-archives/
  references/
```

当来源材料被提炼为模型、文章或项目资产时，应在对应索引中建立回链，而不是复制多份。

## 9. 索引维护

`indexes/` 由 Codex 按需维护。人工不需要每次新增文件都手动更新。

触发条件：

- 新增一个模型族或重要版本。
- 批量迁移一个目录。
- 从旧库导入一批材料。
- 某个项目阶段完成，需要归档。
- 需要从文章、讨论或来源材料中提炼模型关系。
- 新增或调整公共知识加工能力。

索引原则：

- 优先记录关系，不追求全量复写。
- 标记状态和适用场景。
- 对版本关系给出明确说明。
- 对迁移中的旧目录保留过渡说明。

`skills/` 的公共能力发现入口是：

```text
indexes/skill-index.md
```

## 10. 迁移规则

迁移按文件夹进行，不做零散手工搬运。

标准步骤：

1. 扫描目录规模和文件类型。
2. 生成迁移清单。
3. 标出源路径、目标路径、迁移理由和风险。
4. 用户确认。
5. 执行移动。
6. 更新相关索引。
7. 检查 Git diff。

本仓库已接入 Git。大规模迁移前仍应尽量保持单次变更边界清晰。