# 外挂总知识库落地路线

## 阶段 0：研究和边界冻结

目标：先把“外挂总知识库是什么、不是什么”说清楚。

产物：

- `docs/external-knowledge/README.md`
- `docs/external-knowledge/architecture.md`
- `docs/external-knowledge/initial-content.md`
- `docs/external-knowledge/integration-roadmap.md`

验收：

- 明确项目知识与外挂知识的优先级。
- 明确第一版不依赖 RAG。
- 明确外部知识不可用时不阻塞本地 driver。
- 明确长文档必须通过 catalog 进入查询链路，不进入默认上下文。

## 阶段 1：完整项目 MVP 骨架

目标：创建 `team-wiki/` 独立仓库，并从一开始按完整项目管理，而不是只建文档目录。

任务：

1. 按 `initial-content.md` 创建目录。
2. 创建 `knowledge-catalog.md`、`.knowledge-config.yaml`、`log.md`。
3. 创建 `quality-management/`、`software-engineering/`、`agent-engineering/` 三大知识域。
4. 创建 `schemas/` 和 `scripts/`，至少预留 frontmatter schema 与 lint 脚本入口。
5. 创建 `contributions/pending/`、`contributions/conflicts/`、`reports/` 和 `archive/`。
6. 写入 10-20 条面向 AI 编程质量管理和软件工程的 draft 种子知识。
7. 为每条种子知识补齐 frontmatter。

建议验证：

```powershell
git diff --check
```

后续可增加：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/knowledge/lint-knowledge.ps1
```

## 阶段 2：项目侧外挂配置

目标：让项目能声明外挂知识库位置，但不强依赖。

新增项目文件：

```text
.knowledge-sources.yml
```

最小内容：

```yaml
schema_version: 1
sources:
  project:
    path: docs/knowledge
    required: true
  team:
    path: ../team-wiki
    required: false
    catalogs:
      - knowledge-catalog.md
      - quality-management/catalog.md
      - software-engineering/catalog.md
      - agent-engineering/catalog.md
      - app/catalog.md
query:
  max_catalogs: 4
  max_entries: 8
  prefer_maturity: [proven, verified, draft]
```

任务：

1. 在 Harness 模板中加入 `.knowledge-sources.yml` 示例。
2. 在 `tools/harness/templates/project-task-template.json.runtime.handoff.truth_sources` 中支持 `team_knowledge`。
3. `team_knowledge` 缺失时只输出 warning。
4. 项目画像 `project-profiles/<project-slug>.md` 可选接入，用于过滤不相关知识。
5. 领域扩展 catalog，如 `common/catalog.md`、`app/catalog.md`，只有任务命中对应 AI Coding 控制、平台或发布风险时才读取。

## 阶段 3：Prompt 查询协议

目标：让 Codex 会话知道何时读取外挂知识。

修改点：

- `implement-one-task.md`
- `review-stage1-spec.md`
- `review-stage2-quality.md`
- `failure-triage.md`
- `repair-one-finding.md`
- `worker-role/*`

要求：

1. 先读项目 truth source。
2. 再读项目 `docs/knowledge/knowledge-catalog.md`。
3. 如 `.knowledge-sources.yml` 存在且任务相关，再读外挂 catalog。
4. 只读取少量相关条目。
5. 最终输出 `knowledge_references` 时标记来源：
6. 对 `common/`、`app/` 这类长文档领域扩展，先读 catalog 摘要；只有 AI Coding 生产控制、移动端上线、平台审核、支付、隐私、安全、弱网、灰度回滚或行业专项任务才读取完整规范相关章节。

```markdown
## Knowledge References
- `GUIDELINE-HARNESS-001`: title - source=team - used_in=plan - `../team-wiki/...`
```

## 阶段 4：同步候选任务

目标：把项目知识中可复用的 verified/proven 候选导出到外挂库 pending。

新增可选任务：

```json
{
  "id": "KNOWLEDGE-TEAM-SYNC-001",
  "description": "把项目知识中的跨项目候选导出到外挂总知识库 pending",
  "task_kind": "archive",
  "phase": "archive",
  "gate_profile": "lightweight",
  "required_truth_sources": ["knowledge"],
  "priority": 95,
  "dependencies": ["ARCHIVE-001"],
  "passes": false,
  "context_files": [
    ".knowledge-sources.yml",
    "docs/harness/team-knowledge-sync.md",
    "docs/knowledge/knowledge-catalog.md",
    "docs/knowledge/catalog.md"
  ],
  "owned_paths": [
    "docs/knowledge/"
  ],
  "execution": { "mode": "single" },
  "test_command": "git diff --check",
  "acceptance": [
    "输出 team sync candidates 或说明外挂知识库不可用",
    "没有把 draft 或单次经验直接升级为 proven",
    "冲突只进入 conflict candidate，不覆盖外挂知识主干"
  ]
}
```

如果需要直接写外挂仓库，必须显式把外挂路径纳入 owned paths 或由人工执行同步。

## 阶段 5：最小脚本

建议新增脚本：

```text
scripts/knowledge/
  resolve-sources.ps1
  lint-knowledge.ps1
  export-team-candidates.ps1
  build-agent-index.ps1
```

职责：

- `resolve-sources.ps1`：读取 `.knowledge-sources.yml`，输出可用 catalog 和缺失 source。
- `lint-knowledge.ps1`：检查 frontmatter、catalog、孤儿条目、重复和冲突候选。
- `export-team-candidates.ps1`：把项目 promotion candidates 转成 `contributions/pending/` 条目。
- `build-agent-index.ps1`：生成 `agent-context.md` 或 `llms.txt` 形式的低成本 Agent 查询入口。

脚本边界：

- 不自动删除知识。
- 不静默提升为 `proven`。
- 外挂库不可用时 exit 0 + warning，除非用户显式要求强制同步。

## 阶段 6：RAG 增强

触发条件：

- 外挂知识超过 300 条。
- catalog 筛选已经不足以召回相关内容。
- 已有稳定 frontmatter 和权限边界。

RAG 结构：

```text
Markdown Git repo
  -> index builder
  -> vector store
  -> retrieval candidates
  -> 回到 Markdown source 读取原文
```

RAG 不作为 truth source。它只负责召回候选，最终引用必须指向 Git 中的 Markdown 条目。

## 风险和防线

| 风险 | 防线 |
| --- | --- |
| 外挂知识覆盖项目事实 | 项目 truth source 优先，冲突输出 candidate |
| 知识库膨胀 | catalog-first、query budget、lint |
| 单次经验变全局规则 | draft 默认、proven 需多证据或审批 |
| 外部库不可用阻塞开发 | `required: false`，降级 warning |
| 过时知识误导 Agent | last_referenced、decay、archive |
| 泄露敏感信息 | 禁止 token、cookie、私钥、客户数据入库 |

## 第一轮实施建议

先做以下最小闭环：

1. 创建独立 `team-wiki` 仓库骨架。
2. 按质量管理、软件工程、Agent 工程三大域写入 10-20 条种子知识。
3. 在本项目新增 `.knowledge-sources.yml` 示例。
4. 修改 prompt，让它能按需读取外挂 catalog。
5. 新增 `resolve-sources.ps1` 和 `lint-knowledge.ps1`。
6. 跑一次人工 ARCHIVE，把当前 Harness 的两条 draft 项目知识导出为团队 pending 候选。
7. 将 `docs/external-knowledge/common/catalog.md` 作为通用 AI Coding 生产控制入口，将 `docs/external-knowledge/app/catalog.md` 作为 App 生产可上线领域扩展入口，并保持完整规范为按需读取资料。

这一步完成后，再考虑自动同步和 RAG。
