# 知识库驱动开发 — 团队 SOP

> 本文档面向所有团队成员，描述如何使用 Cursor 的知识库工作流进行开发。

## 一、知识库是什么

**可验证真相 = 知识库（`knowledge/`）+ 仓库代码**：行为以代码为准；知识库用中文记录当前系统入口、业务域与工程平台，须与代码保持同步：

| 入口 | 路径 | 面向角色 | 回答什么 |
|------|------|---------|---------|
| 知识地图 | `knowledge/知识地图.md` | 产品/全员 | 系统有哪些业务域与入口？ |
| 业务域 | `knowledge/业务域/**` | 产品/开发 | 业务现状、流程、接口、数据如何组织？ |
| 工程平台 | `knowledge/工程平台/**` | 开发/架构 | 跨业务域的平台能力与工程规则是什么？ |
| LLM 总索引 | `knowledge/index.md` | 所有角色 | 先定位知识地图、领域 index 或工程平台 index |

旧结构已迁移完成，新流程只使用知识地图、业务域、工程平台、OKF index、变更/进行中、变更/归档。存量旧入口用 `/kb-okf-migrate`。

**链接与图谱（必读）**：`knowledge/` 内部互指**仅** `[[wikilink]]`；外部 URL 用 Markdown 链接。概念文件强制 `related`、`depends_on`（可为空数组）与「相关」段；可选 `status`/`supersedes`/`keywords`；`index.md` 列表用 wikilink。archive/sync 写时演化与贡献分见 [kb-knowledge-evolve.md](references/kb-knowledge-evolve.md)。细则：[kb-graph.md](references/kb-graph.md)、[kb-okf.md](references/kb-okf.md)。

知识库始终力求反映**与代码一致的当前现状**，不是变更历史。每次功能完成后必须归档更新并对照代码核对。

## 二、CodeGraph 接入

KB 流程现在把 CodeGraph 作为代码事实入口：知识库负责解释业务现状，CodeGraph 负责快速核对真实实现、调用链和影响面。

**环境准备**（一次性）：

1. 业务仓 `--scope project` 安装 `kb-workflow` → `/kb-init` bootstrap（底层即 `kb-bootstrap.mjs`）。
2. **Bootstrap 硬门禁**：除 `/kb-init` 与纯上游反馈（`/kb-feedback`、`/kb-session-retro`）及源码进化类（`/kb-evolve-setup`、`/kb-evolve`、`/kb-evomap-setup`）及配置类（`/kb-deepseek-search-setup`、`/kb-cursor-setup`、`/kb-figma-setup`）外，所有 `/kb-*` 开始前须通过 `kb-bootstrap-check.mjs`（检查 `kb.project.json`、`knowledge/`、`knowledge/index.md`、`.kb/kb-manifest.schema.json`）；未通过则停止，禁止 `mkdir` 绕过。机器探测：`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`。
3. 编辑 `kb.project.json` 的 `codeRoots`，在项目根执行 CodeGraph 索引：

```bash
npx -y @colbymchenry/codegraph@0.9.3 init
npx -y @colbymchenry/codegraph@0.9.3 index
```

4. **按当前宿主复制项目级 MCP 示例**（bootstrap 不自动写入；**禁止**无脑双写）：从 `${PI_KB_ROOT}/bootstrap/examples/mcp/` 只拷当前宿主对应文件（Claude Code / 其他 → 根 `.mcp.json`；Cursor → `.cursor/mcp.json`）。双 IDE 须用户明示才补另一份；已有文件则合并 `codegraph` 条目。细则见 `references/kb-codegraph.md` §一。
5. 使项目级 MCP 生效：Cursor **Developer: Reload Window**；Claude Code / 其他重启会话或按宿主要求重载 MCP。

安装见仓库 `docs/CLAUDE_MARKETPLACE.md` §六。

**门禁口径**（细则见 `references/kb-codegraph.md` §二）：

- **硬门禁**（须 CodeGraph 可用）：`/kb-design`、`/kb-plan`、`/kb-apply`、`/kb-revise-apply`、`/kb-review`、`/kb-archive`、`/kb-explore`、`/kb-query`、`/kb-sync`、`/kb-verify-issue`。
- **禁止 CodeGraph**：`/kb-propose`（业务 PRD 澄清与落盘，外部登记可选；详见 `kb-workflow/references/kb-external-sync.md`）。
- **警告级**：`/kb-check`、`/kb-health`（索引不可用记警告，不阻断只读校验）。

**各阶段用法**：

- `/kb-query`、`/kb-explore`：知识库不足或怀疑过时时，先用 `codegraph_explore` 查实现，再补读具体文件。
- `/kb-design`：必须产出业务流程 Mermaid 图与改动对照表；技术影响、参考实现、分层落点、知识库影响优先来自 CodeGraph。
- `/kb-plan`、`/kb-apply`：任务的上下文文件、依赖图和冲突文件优先通过 CodeGraph 影响面确定。
- `/kb-review`、`/kb-archive`、`/kb-sync`：评审范围、知识库同步和代码映射核对必须结合 CodeGraph 调用链或影响面。
- CodeGraph 不替代需求澄清、manifest 状态、两级索引规则或用户确认；硬门禁阶段索引不可用时先报告阻断，再用只读文件检索兜底。

## 三、命令速查

所有命令在 Cursor 中通过 `/kb-<命令名>` 调用（如 `/kb-propose`）。

### 查询类（随时可用）

| 命令 | 用途 | 输入 | 产出 |
|------|------|------|------|
| `/kb-explore <问题>` | 开放探索，自由思考 | 任意问题 | 洞察、方向、分析 |
| `/kb-query <关键词>` | 精确检索，定位知识 | 关键词或问题 | 答案 + 来源引用 |
| `/kb-check <中文名称>` | 只读校验流程状态、OKF 与图谱合规 | 可选变更名称 | 阻断项、警告项、建议下一步 |

**区别**：explore 是好奇心驱动的自由探索；query 按“两级 index”检索：`knowledge/index.md` → 领域/平台 `index.md` → 具体知识文件。

### 开发流程类（按顺序执行）

```
propose → design → plan → apply → review → test → archive（含 commit+push + 可选 external sync）
  提案      设计    分解    实现    评审    验证说明   归档（迁移+提交+通知）
```

| 命令 | 用途 | 输入 | 产出文件 |
|------|------|------|---------|
| `/kb-lite <中文名称>` | **默认新建入口**（轻量小改） | 中文名称 + 简短说明 | `00-manifest.json` + `05-summary.md` |
| `/kb-propose <中文名称>` | 标准流 / 完整 PRD（升级条件或用户明示） | 中文名称 + 需求描述 | `01-proposal.md` + 可选 `external` |
| `/kb-design <中文名称>` | 设计实现方案 | 变更名称 | `02-design.md`（含业务流程图 + 改动标注） |
| `/kb-plan <中文名称>` | 分解原子任务 | 变更名称 | `03-tasks.md` |
| `/kb-apply <中文名称>` | 调度子 agent 执行；标准流全部通过后同会话强制 review→可执行 test | 变更名称 | 代码变更；串联 `04`/`06` |
| `/kb-review <中文名称>` | 代码评审；通过后下一步 `/kb-test` | 变更名称 | `04-review.md` |
| `/kb-test <中文名称>` | 可执行验收 + 写 `06`（失败不标 tested） | 变更名称 | `06-automation-test.md` |
| `/kb-archive <中文名称>` | 归档、commit+push、可选 external sync | 变更名称 | `05-summary.md` + 知识库更新 + git push |
| `/kb-archive-purge` | 按 retention 批清归档目录（可选运维） | 可选参数见命令 | 硬删过期归档 + `归档/.tombstones/` 留痕 |
| `/kb-repair <中文名称>` | 修复中断/漂移后的状态清单 | 变更名称 | 仅修 manifest/摘要/清单 |
| `/kb-commit <中文名称>` | 单独提交（recovery） | 可选变更名称 | 白名单 commit + push |

`/kb-check` 可在任意阶段前运行。尤其是归档和提交前，必须用它确认 manifest（含 **JSON Schema 机器校验** `kb-manifest-validate.mjs`）、评审闭环、知识库更新清单、两级 index、OKF/图谱合规（`kb-okf-check.mjs`）和提交白名单没有阻断项。校验优先基于 `00-manifest.json`、文件存在性、`05-summary.md` 清单、`knowledge/index.md` 引用、概念 frontmatter 关系字段与 git 候选文件做机器可判定检查，不把结论留成主观判断。

### 状态红线

- 每个变更目录必须有 `00-manifest.json`。遇到历史目录缺失时，先补建最小 manifest，再继续任何 `/kb-*` 流程。
- `manifest.files` 是归档、校验、提交的首要文件白名单，必须与 `05-summary.md` 的「实际变更」和「知识库更新清单」同轮同步；漂移时停止推进。
- 归档后的状态只能是 `archived` 或 `archived_with_debt`。如果评审未通过且团队没有明确接受债务，不进入归档与提交。
- **标准流 archive/check**：必须有 `04-review.md` 且无 `reviews[].status = open`；**不强制**存在 `06-automation-test.md` 文件。
- 评审问题必须闭环到 `reviews[]`：`open` 不可归档；修复后写 `fixed`；明确接受债务写 `accepted_debt` 并归档为 `archived_with_debt`；误报写 `false_positive` 和原因。
- 业务域/工程平台叶子文件新增、删除、重命名时先更新所属 index；只有领域/平台入口变化、index 引用失效或总入口失真时才同步 `knowledge/index.md`；`knowledge/变更/归档/` 变化不触发索引。
- `/kb-test` 默认**尝试执行** `03`/`auto_test`/明示命令并写 `06`；**执行失败 ≠ `stage=tested`**；`/kb-apply` 不写测试脚手架；`/kb-test` **允许**在 `auto_test/` 补 Playwright/契约（追溯 `03`），**禁止** unit 脚手架；同批内 **ui>contract>unit**；也不默认全量静态检查。
- **`flow=lite` 豁免** apply 后自动 review + 可执行 test；记录型 lite 不要求 `04`/`06`。

### 维护类

| 命令 | 用途 | 输入 | 产出 |
|------|------|------|------|
| `/kb-sync` | 全量/增量同步知识库 | 可选层级参数 | 更新后的知识文件 |
| `/kb-index` | 维护两级 OKF index | `总索引` / `业务域/<领域>` / `工程平台` | 更新后的总索引或局部 `index.md` |
| `/kb-okf-migrate` | 存量 knowledge 迁移为 OKF + wikilink | `dry-run` / `apply` | frontmatter、`index.md`、`log.md`、内链改 wikilink、补 `related`/`depends_on` 与 `## 相关` |

`/kb-check` 属于只读闸门，不修改文件；发现问题后再选择 `/kb-review`、`/kb-index`、`/kb-archive`、`/kb-okf-migrate` 等命令处理。
`/kb-repair` 只用于中断或漂移后的恢复，允许修 `00-manifest.json`、`05-summary.md` 清单、归档位置说明，不允许改业务代码或补实际功能。

## 四、标准开发流程

### 场景 A：新功能开发

```
步骤 1: 提案（业务 PRD）
  /kb-propose 红包功能
  → 产出: 01-proposal.md、可选外部 PRD 链接与任务记录

步骤 2: 设计
  /kb-design 红包功能
  → 产出: knowledge/变更/进行中/<时间戳>-红包功能/02-design.md（含业务流程图 + 改动对照表）

步骤 3: 分解任务
  /kb-plan 红包功能
  → 产出: knowledge/变更/进行中/<时间戳>-红包功能/03-tasks.md
  → 生成依赖图，确定哪些任务可并行

步骤 4: 实现
  /kb-apply 红包功能
  → 按依赖图调度子 agent 并行执行
  → 每轮完成后验收标准检查 + manifest 状态回写
  → 全部通过后：stage=applied → validate → 同会话强制 /kb-review → 通过后再强制可执行 /kb-test

步骤 5: 评审（标准流强制；通常由 apply 同会话串联）
  /kb-review 红包功能
  → 按风险选择 focused-review / full-review
  → 产出: knowledge/变更/进行中/<时间戳>-红包功能/04-review.md
  → 如果未通过，将 open 问题转为 T-FIX-* 修复任务，修复后重新 review；不得直接 archive
  → 通过后进入步骤 6（/kb-test），不是直接归档

步骤 6: 可执行验收（标准流强制；通常由 apply/review 同会话串联）
  /kb-test 红包功能
  → 默认尝试执行 03/auto_test/明示命令；分层 ui>contract>unit；写 06-automation-test.md
  → 执行失败不得写 stage=tested；允许 auto_test 补 Playwright/契约，禁 unit 脚手架

步骤 6.5: 状态校验
  /kb-check 红包功能
  → 只读检查 manifest、须有 04 且无 open、知识库更新清单、OKF index 与合规
  → 不强制要求 06 文件存在；有阻断项时先处理，不进入归档

步骤 7: 归档
  /kb-archive 红包功能
  → 更新知识地图、业务域或工程平台知识文件
  → 产出: knowledge/变更/归档/<时间戳>-红包功能/05-summary.md
  → 白名单 commit + push
  → 可选外部 sync（若 integrations 已启用）

步骤 8（可选运维）: 归档批清
  /kb-archive-purge
  → 达到 retention 后批清过期归档目录；硬删后保留 归档/.tombstones/ 供查重与审计
```

### 场景 A-1：轻量小改

```
/kb-lite 文案微调
→ 适用于文案、样式、局部 bug 等低风险变更
→ 记录型 lite 可一步完成实现、05-summary、manifest.files、归档迁移
→ 若涉及接口、数据、安全、资金或跨端契约，升级到标准流程
```

轻量流程的上限：
- 用户一句话无法说明变更和验收，需要 PRD 或多轮澄清时，升级标准流程。
- 涉及多个模块、跨端协作、proto、数据库、权限、资金、事务语义时，升级标准流程。
- 需要 `02-design.md` 或 `03-tasks.md` 才能讲清楚实现边界时，升级标准流程。
- **lite 豁免** apply 后自动 review + 可执行 test；记录型 lite 不要求五角评审与 `04`/`06`；知识同步型 lite 先更新所属领域/平台 index；只有入口变化或 index 引用失效时才更新 `knowledge/index.md`。

### 场景 B：快速了解系统

```
# 想知道系统整体能做什么
/kb-explore 系统有哪些功能？

# 想知道某个模块的接口
/kb-query 礼物系统接口

# 想知道某个数据表的结构
/kb-query user_wallets 表结构
```

### 场景 C：排查问题

```
# 先查知识库了解相关模块
/kb-query 送礼扣款流程

# 深入探索问题
/kb-explore 送礼时余额扣减失败可能的原因

# 确认知识库是否最新
/kb-sync
```

### 场景 D：知识库维护

```
# 代码有较大变更，同步知识库
/kb-sync 礼物接口     # 只同步相关业务域接口说明
/kb-sync             # 全量同步

# 知识文件结构有变化，重建索引
/kb-index 总索引
/kb-index 业务域/礼物
/kb-index 工程平台

# 存量 Markdown 内链或缺关系字段
/kb-okf-migrate      # 先 dry-run；apply 后改 wikilink、补 related/depends_on 与 ## 相关

# 怀疑孤儿节点、断链或 frontmatter 与正文关系不一致
/kb-health
/kb-check            # 只读校验 OKF/图谱（`kb-okf-check.mjs` 已落地；细则见 kb-graph.md）

# 归档目录过多时可选运维批清（默认仍保留；硬删后留 tombstone）
/kb-archive-purge
```

### 场景 E：归档或提交前自检

```
# 归档（含 commit+push + 可选 external sync，一步完成）
/kb-archive 红包功能

# 若 archive 在 commit 前中断，可单独补提交
/kb-check 红包功能
/kb-commit 红包功能
```

## 五、变更目录结构

每个变更（propose 开始）都会在 `knowledge/变更/进行中/` 下创建目录：

```
knowledge/变更/进行中/<YYYYMMDDHHMMSS>-<中文名称>/
├── 00-manifest.json        # 机器可读状态
├── 01-proposal.md          # /kb-propose 产出
├── 02-design.md            # /kb-design 产出（含业务流程图 + 改动对照表）
├── 03-tasks.md             # /kb-plan 产出
├── 04-review.md            # /kb-review 产出
├── 05-summary.md           # /kb-archive 或 /kb-lite 产出
├── 06-automation-test.md   # /kb-test 产出（标准流强制跑 test；archive 不强制保留该文件）
├── 07-prd-revisions.md     # /kb-revise 可选产出
└── 08-verify-issue.md      # /kb-verify-issue 可选产出（验收打回问题报告）
```

**命名约束**：目录名格式为 `<YYYYMMDDHHMMSS>-<中文名称>`，`YYYYMMDDHHMMSS` 为 Asia/Shanghai 下 shell `date +%Y%m%d%H%M%S` 的 14 位结果（见 [references/kb-change-directory-id.md](references/kb-change-directory-id.md)）；中文名称部分禁止 kebab-case、camelCase 或纯英文命名。

归档后目录移动到：

```
knowledge/变更/归档/<YYYYMMDDHHMMSS>-<中文名称>/
```

## 六、知识库更新追踪

变更对知识库的影响在三个阶段逐步精确化：

```
propose 阶段 → 粗略评估（哪些知识文件受影响）
    ↓
design 阶段 → 精确计划（必须更新 / 可能更新 / 不需要更新）
    ↓
archive 阶段 → 最终执行（对比实际代码变更，逐文件更新）
```

archive 会读取 propose 和 design 中记录的影响清单，不需要重新推理。

## 七、约定

1. **中文编写**：所有知识文件、变更文档使用中文
2. **每文件 <= 3000 字符**：超限时拆分为多个文件
3. **知识库 = 最新现状**：不保留变更历史，只写最新内容
4. **manifest 记录状态**：任务、评审、Rev 是否完成，以 `00-manifest.json` 为准
5. **manifest 记录文件**：`files[]` 记录本次变更涉及的代码、知识文件、变更目录文件、所属 index，以及必要时的 `knowledge/index.md`，提交时只从白名单暂存
6. **不做额外扩散**：只更新清单中标记的文件
7. **归档后默认保留变更目录**：作为历史记录默认不删；达到 retention 后可通过 `/kb-archive-purge` 批清；硬删后保留 `归档/.tombstones/` 供查重与审计
8. **两级 index 与 wikilink**：总索引只定位领域/平台入口，叶子文件由各目录 `index.md` 维护（wikilink 列表）；概念文件须含 YAML `type`、`related`、`depends_on` 与「相关」段；可选时效字段；写时建链/邻接回写与 `.kb/knowledge-utility.json` 贡献分见 [kb-knowledge-evolve.md](references/kb-knowledge-evolve.md)；结构性变更写同目录 `log.md`（见 [kb-okf.md](references/kb-okf.md)、[kb-graph.md](references/kb-graph.md)）
9. **有条件归档必须机器化**：人类可读文档可以解释债务，但 manifest 必须写 `archived_with_debt`，并在 `reviews[]` 或 `05-summary.md` 中列清债务
10. **只读校验先行**：状态不确定、准备归档或准备提交时，先运行 `/kb-check`；有阻断项时不得继续下一阶段
11. **提交禁止全量默认**：`/kb-commit` 不得默认提交“当前全部改动”；发现未归属改动必须停止并让用户确认

## 八、插件升级（团队必读）

插件包版本以仓库根 [CHANGELOG.md](../../../../CHANGELOG.md) 为准（与业务仓流程进化 `workflow_version` 不同）。

### 升级步骤

1. 阅读 CHANGELOG **最新一节**的「变更摘要 / 影响范围 / 业务仓动作」。
2. 执行：

```bash
claude plugin marketplace update doger-kb-plugins
claude plugin update kb-workflow@doger-kb-plugins --scope project
```

3. Cursor：**Developer: Reload Window**。
4. **破坏性升级**：若 CHANGELOG **最新一节**「影响范围」中**任一**对象标注 `是否 breaking = 是`，必须按该节「业务仓动作」执行（例如 0.4.0 OKF → `/kb-okf-migrate`；0.5.0 wikilink/图谱字段迁移等），完成后用 `/kb-check` 或 `kb-okf-check.mjs` 确认。
5. **非 breaking** 版本：通常仅需步骤 2～3；仍应阅读最新一节摘要与影响范围。

**不要写死某一插件版本号**：历史破坏性升级见 [docs/changelog/](../../../../docs/changelog/) 或根 CHANGELOG「更早版本」表；团队与业务仓升级时**始终以根 CHANGELOG 最新一节为准**。

维护者发版检查清单：[docs/RELEASE.md](../../../../docs/RELEASE.md)。

## 九、常见问题

**Q: 什么时候用 explore，什么时候用 query？**
A: explore 适合「我不确定我想了解什么」的场景，会自由思考发散；query 适合「我知道我要找什么」的场景，会沿两级 index 精确检索。

**Q: 必须走完 propose → design → plan → apply 全流程吗？**
A: 不必。小改动（修 bug、改文案、样式微调）走 `/kb-lite`。新功能、重构、跨端契约或高风险路径走完整流程。

**Q: 子 agent 执行失败了怎么办？**
A: `/kb-apply` 会自动重试一次（附带错误信息）。二次失败后停止，由你决定是否继续。可以修复问题后重新运行 apply。

**Q: apply/review/archive/commit 中断后怎么办？**
A: 先用 `/kb-check <中文名称>` 只读定位漂移。如果只是 manifest、`files[]`、`05-summary.md` 清单或归档位置不一致，用 `/kb-repair <中文名称>` 修状态；如果是业务实现或知识库正文缺失，回到对应流程补齐。

**Q: review 未通过怎么办？**
A: 先把 `open` 问题转成 `T-FIX-*` 或 `T-Rev*-FIX-*` 修复任务，用 `/kb-apply` 或 `/kb-revise-apply` 修复，再重新 `/kb-review`。不能只在文档里写“后续处理”。

**Q: 什么时候运行 `/kb-check`？**
A: 状态不确定、归档前、提交前都运行。它只读检查，不修改文件，也不执行全量 analyze 或测试。升级插件后也可用它确认 OKF 与图谱合规。

**Q: 插件更新后 knowledge 报缺 type / 旧入口名 / Markdown 内链？**
A: 先读 CHANGELOG 影响范围，再跑 `/kb-okf-migrate`（dry-run → apply），最后 `/kb-check`。图谱字段与 wikilink 细则见 [kb-graph.md](references/kb-graph.md)。

**Q: 知识库和代码不一致了怎么办？**
A: 运行 `/kb-sync` 重新同步。日常开发中，每次功能完成后用 `/kb-archive` 归档可以保持一致。

**Q: 可以手动编辑知识文件吗？**
A: 可以。编辑叶子知识文件后先确认所属 index 是否仍准确，并保留 YAML `type`、`related`、`depends_on` 与「相关」段（wikilink 与 frontmatter 一致）；新增/删除/重命名文件时运行 `/kb-index 业务域/<领域>` 或 `/kb-index 工程平台`，只有入口变化时再更新总索引；结构性变更追加同目录 `log.md`。内部链接只用 `[[wikilink]]`。