---
name: kb-workflow
description: 知识库驱动的开发工作流（主 Agent 识别意图/编排流程，所有文件修改由子 Agent 执行）。通过 /kb-sync、/kb-propose、/kb-design、/kb-okf-migrate、/kb-revise、/kb-revise-apply、/kb-test、/kb-archive、/kb-archive-purge、/kb-verify-issue、/kb-repair、/kb-feedback、/kb-session-retro、/kb-evolve 等流程驱动；**知识库与代码共同构成可验证真相**（行为以代码为准，知识库为检索与协作主载体）。OKF `index.md` 提供 LLM 检索入口。
---

**可验证真相 = 知识库（`knowledge/`）+ 仓库代码**：可执行行为、边界与契约以**代码**为准；知识库用中文梳理现状、意图与模块关系，须与代码**持续对齐**，供产品角色与开发角色检索与协作。`knowledge/` 参考 OKF 布局（`index.md`、`type` 等），内部链接与关系图谱见 [references/kb-graph.md](references/kb-graph.md)；OKF 映射见 [references/kb-okf.md](references/kb-okf.md)。

## 知识库结构

```
knowledge/
├── 知识地图.md        # 整体功能地图与业务域入口（YAML type: KnowledgeMap）
├── index.md           # OKF 总入口（okf_version），只列地图、领域 index、工程平台 index
├── AGENTS.md          # 内容结构 SSOT（type: AgentsSpec）
├── 业务域/
│   └── <中文领域>/
│       ├── index.md         # 本领域局部索引（无 frontmatter）
│       ├── log.md           # 可选；结构性变更日志
│       ├── 01-概览.md       # 模块总图（须含 YAML type）
│       ├── 02-<子模块>.md   # 编号子模块文件（十段式）
│       ├── 0N-<子模块>.md
│       └── <中文子目录>/    # 特大领域可再分组，子目录内仍为编号子模块+十段式并维护 index.md
├── 工程平台/
│   ├── index.md       # 工程平台入口索引：只列平台分区
│   └── <中文平台分区>/  # 平台分区：index + 01-概览 + 编号子模块（与业务域同结构）
└── 变更/
    ├── 进行中/<YYYYMMDDHHMMSS>-<中文名称>/
    └── 归档/<YYYYMMDDHHMMSS>-<中文名称>/
```

机器约束文件：业务仓 `.kb/kb-manifest.schema.json`（插件包内 `schema/kb-manifest.schema.json`）。所有 `00-manifest.json` 至少应通过该 schema 的结构校验，再进入阶段判断。

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

## 链接与图谱（检索原则）

1. **内部仅 wikilink**：`knowledge/` 互指只用 `[[path/note]]` 或 `[[note|显示名]]`；**禁止** `[标题](相对路径.md)` 内链。
2. **外部仅 Markdown 链接**：`http`/`https` URL 用标准 Markdown 链接。
3. **概念 frontmatter**：非保留名文件强制 `related`、`depends_on`（`string[]`，字段必须存在，可为 `[]`）；wikilink 目标无括号。Schema：`schema/kb-concept-frontmatter.schema.json`。
4. **正文 `## 相关`**：子模块为「十一、相关」；概览为「十一、相关」；顶级概念为文末 `## 相关`；段内 wikilink ⊇ `related` ∪ `depends_on`。
5. **回链与孤儿**：出链目标须可被 index/概览/`related` 发现；禁止长期无入边孤儿（根与各域 `index.md` 除外）。
6. **`index.md` 列表**：`* [[wikilink]] - description` 格式。细则唯一出处：[references/kb-graph.md](references/kb-graph.md)。

## 索引分层（两级 index）

- `knowledge/index.md` 是**总入口**，只列 `knowledge/知识地图.md`、`knowledge/业务域/<领域>/index.md`、`knowledge/工程平台/index.md`，不得展开全部叶子知识文件。
- 每个 `knowledge/业务域/<领域>/index.md` 是**领域局部索引**，维护本领域文件清单、职责边界、推荐阅读路径；新增、删除、重命名领域内知识文件时优先更新所属 index。
- `knowledge/工程平台/index.md` 是**平台入口索引**，只维护 `knowledge/工程平台/<中文平台分区>/index.md` 入口；由分区 `index.md` 维护叶子文件清单。
- 查询路径固定为：`index.md` → 领域 `index.md` / 工程平台 `index.md` → 分区 `index.md` → 具体知识文件。
- 归档只在新增/删除/重命名目录入口、领域 index 失真、工程平台 index 失真、总入口失真时更新总索引；普通业务文件正文变化只更新所属 index，若 index 仍准确则无需更新总索引。

## 业务域分区规则

> 知识文件**内容结构以 [`knowledge/AGENTS.md`](../../bootstrap/knowledge/AGENTS.md) 为准**：业务域按「领域 `index.md` + `01-概览` + 编号子模块文件（十段式）」组织；不再按角色分文件（`客户端流程.md`/`接口.md`/`数据.md` 等）。本节只规定分区与索引口径。OKF 参考布局与图谱字段见 [kb-okf.md](references/kb-okf.md)、[kb-graph.md](references/kb-graph.md)。

- 业务域目录由 `01-概览.md`（模块总图）与 `02..0N-<子模块>.md`（编号子模块，十段式）构成；客户端流程、接口、数据等作为子模块文件内的段落，跨子模块聚合视图写进 `01-概览`。
- 当单文件超过 3000 字符、或一个子模块本身包含 3 个以上独立主题时，拆成更多编号子模块文件；仍嫌庞大时才拆到领域中文子目录。
- 子目录名称必须中文、语义稳定；子目录内文件**仍遵循编号 + 十段式**。
- 每个子目录必须有 `index.md`，维护该子目录职责边界、推荐阅读路径和文件清单；子目录内新增、删除、重命名文件时先更新子目录 index。
- `knowledge/业务域/<领域>/index.md` 只维护领域入口、`01-概览` 与子目录/子模块入口，不得堆叠子目录叶子文件。
- `knowledge/index.md` 始终只引用 `knowledge/业务域/<领域>/index.md`，不得引用领域子目录 index 或子模块文件。
- 概念文件必须含 YAML `type`、`related`、`depends_on` 与「相关」段；`index.md` 用 wikilink 列表；结构性变更追加同目录 `log.md`，禁止正文「变更记录」段。

## 工程平台分区规则

> 知识文件**内容结构以 [`knowledge/AGENTS.md`](../../bootstrap/knowledge/AGENTS.md) 为准**：工程平台分区与业务域采用同一套 `index.md` + `01-概览` + 编号子模块（十段式）组织；禁止分区内无编号的 `README.md`、`00-README.md`、`概览.md` 等旧命名。

- 工程平台按中文平台分区维护；除根 `index.md` / `log.md` 外，不在 `knowledge/工程平台/` 根目录继续新增平台叶子文件。
- 平台分区示例：`Flutter客户端/`、`Rust服务端/`、`Quasar管理后台/`、`QuasarH5/`、`官方网站/`、`Proto协议/`；分区名称必须中文、语义稳定。
- 每个分区必须有 `index.md`，维护该分区职责边界、推荐阅读路径和文件清单；分区内新增、删除、重命名文件时先更新分区 `index.md`。
- `knowledge/工程平台/index.md` 只维护各分区 `index.md` 入口，不得堆叠分区叶子文件。
- `knowledge/index.md` 始终只引用 `knowledge/工程平台/index.md`，不得引用工程平台分区 index 叶子展开或叶子文件。

## 核心原则

1. **知识库须与代码现状对齐**：每次归档后必须同步更新知识库；若文档与代码不一致，以实现为准并回写知识库（或修正代码），避免「文档冒充真相」
2. **优先查阅**：每个阶段先读知识库，不足时必须结合代码核对
3. **每文件 <= 3000 字**：保持精炼，避免冗余
4. **中文编写**：所有知识文件使用中文
5. **两级索引优先检索**：知识文件变更后先维护所属领域 `index.md` 或平台分区 `index.md`；仅目录入口或 index 引用失真时运行 `/kb-index` 更新总索引；精确查询使用 `/kb-query`
6. **主 Agent 不直接写文件**：见下文「编排与子 Agent」；文档、知识库、代码、索引、提交状态等所有写入均由子 Agent 执行，主 Agent 只负责澄清、拆解、调度、审核、汇总与失败重派。
7. **变更状态机器可读**：每个变更目录必须维护 `00-manifest.json`，记录流程类型、阶段、任务/评审/Rev 状态与涉及文件；Markdown 负责说明，manifest 负责状态。`manifest.files` 是提交、归档、校验的首要文件白名单，必须覆盖代码文件、知识文件、变更目录文件和知识 index。
8. **新建默认 lite**：低风险、小范围、无需跨端契约变更的事项走 `/kb-lite`，**禁止**默认拉完整八步。仅用户明示标准流/完整 PRD，或命中 lite 升级表（契约/DDL/资金/权限/事务，或量化分 ≥3）时升 `/kb-propose`。机器路由：`scripts/kb-stage-next.mjs`（`--intent new` 或 `--change-dir`）。lite 再细分为「记录型」和「知识同步型」：只影响局部实现且不改变现状知识时，允许一轮完成实现、`05-summary.md`、manifest、归档；影响知识地图、业务域或工程平台时才触发知识库合并与 index 判断。
9. **历史目录先补状态**：任何 `/kb-*` 命令发现匹配的变更目录缺少 `00-manifest.json` 时，第一步必须由子 Agent 补建最小 manifest，再继续后续流程；不得只靠 Markdown 推断状态。
10. **索引更新不留待办**：归档、同步或手动维护导致领域/平台 index 引用失效、目录入口新增/删除/重命名，或总入口失真时，本轮必须更新所属 index，并按需触发 `/kb-index` 更新总索引，不能只提示“以后运行”。
11. **验收导向分层**：`/kb-test` 默认尝试执行 `03`/`auto_test`/明示命令并写 `06`；**执行失败不得标 `stage=tested`**。补自动化时按 **UI E2E（Playwright 等）> 契约/集成 > 单元（仅执行已有）**；**允许**在 `auto_test/` 补 Playwright/契约脚本（追溯 `03`），**禁止**新建单元测试脚手架或默认全量静态检查。标准流 apply 全部通过后强制 review→test（见 `/kb-apply`）；`flow=lite` 豁免该自动链。
12. **只读闸门优先**：阶段切换前若状态、知识库更新范围或 index 覆盖不确定，先运行 `/kb-check` 做只读校验；有阻断项时不得进入下一阶段，除非用户明确要求跳过并接受风险。`/kb-check` 必须优先做机器可判定检查：manifest 字段、文件存在性、知识库更新清单、两级 index 引用、OKF/图谱合规、提交白名单，不把校验留成主观判断。
13. **双轨状态同轮同步**：凡更新 `tasks[]`、`reviews[]`、`revisions[]`、`files[]`、归档状态或债务结论，必须在同一轮同步对应 Markdown 摘要；发现 manifest 与 Markdown 冲突时先停止阶段推进，用 `/kb-check` 只读报告冲突，不靠人工猜测继续执行。若只需修复状态/清单漂移，使用 `/kb-repair <中文名称>`，禁止夹带业务逻辑修改。发生子 Agent 失败重派、或 `/kb-check` 阻断修复后推进时，由当轮**写入型**子 Agent 在 `manifest.metrics` 顺带累加（如 `redispatch`、`check_blocked`）；只读命令（`/kb-check`、`/kb-health`、`/kb-query` 等）不写盘。
14. **归档去噪**：`knowledge/变更/归档/` 只保存变更证据，不进入总索引和局部 index 的日常检索主体；归档时应把仍然生效的结论合并到知识地图、业务域或工程平台，历史过程默认可保留在变更目录（批清口径见原则 20）。
15. **目录迁移只用 mv**：`/kb-archive` 与 `/kb-verify-issue` 必须用 shell `mv` 整目录迁移；禁止 `cp`/复制后在源侧留副本；迁移后 shell 门禁校验（细则 [references/kb-archive-migrate.md](references/kb-archive-migrate.md)）。半迁移用 `/kb-repair` 清理。
16. **周期健康巡检**：当知识库长期未同步、多个变更连续归档、或怀疑 index/manifest/Markdown/OKF/图谱漂移时，运行 `/kb-health` 做只读巡检；health 只发现衰减和重复，不代替 `/kb-check` 的单变更闸门。
17. **流程自身可进化（Pi）**：流程摩擦用 `/kb-feedback` 或会话回顾 `/kb-session-retro` 提 Gitee Issue；改流程仅在源码仓经 `/kb-evolve`（可先 `/kb-evolve-setup`）；可选 `/kb-evomap-setup` 开启网络路径（默认关闭）；详见 [references/kb-feedback-gitee.md](references/kb-feedback-gitee.md)、[references/kb-evomap.md](references/kb-evomap.md)。
18. **OKF 参考布局与图谱**：非保留名概念文件须有 YAML `type`、`related`、`depends_on` 与「相关」段；可选 `status`/`supersedes`/`keywords`；入口为 `index.md`（wikilink 列表）；内部仅 wikilink；结构性变更写 `log.md`。存量用 `/kb-okf-migrate`。细则 [kb-okf.md](references/kb-okf.md)、[kb-graph.md](references/kb-graph.md)、[kb-knowledge-evolve.md](references/kb-knowledge-evolve.md)。
19. **精简实现（Ponytail 口径）**：design/plan/apply/review/archive 阶段对**业务代码**注入 YAGNI 六阶梯与 `ponytail:` 债务留痕；不得为省代码删减 `01`/`02`/`03` 业务语义、安全与数据正确性；细则见 [references/kb-ponytail.md](references/kb-ponytail.md)。
20. **归档默认可保留、批清走 purge**：归档后变更目录默认保留；达到 retention 后由 `/kb-archive-purge`（脚本 `scripts/kb-archive-purge.mjs`）批清；硬删后保留 `归档/.tombstones/`，不得无痕硬删。
21. **图谱写时演化与贡献分（Pi）**：archive/sync 合并知识时强制 **构笔记 → 建链 → 邻接回写**（可选用 `status`/`supersedes`/`keywords`）；检索用 `.kb/knowledge-utility.json` 贡献分软排序并降权 `superseded`；成功路径 `bump`、误导 `penalize`。细则 [references/kb-knowledge-evolve.md](references/kb-knowledge-evolve.md)、[kb-graph.md](references/kb-graph.md) §3.1。

## Bootstrap 门禁

- **硬门禁**：除下列豁免外，所有 `/kb-*` 开始前须通过机器探测：`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`。
- **豁免（不跑门禁 / 未初始化也可执行）**：`/kb-init`；纯上游反馈类 `/kb-feedback`、`/kb-session-retro`；源码进化类 `/kb-evolve-setup`、`/kb-evolve`、`/kb-evomap-setup`；DeepSeek Search 配置 `/kb-deepseek-search-setup`；Cursor 配置 `/kb-cursor-setup`；Figma 配置 `/kb-figma-setup`。
- 检查项：`kb.project.json`（可解析）、`knowledge/`、`knowledge/index.md`、`.kb/kb-manifest.schema.json`。
- 未通过则**立即停止**，指引 `/kb-init`（或直接跑 `kb-bootstrap.mjs`）；禁止用 `mkdir -p knowledge/...` 绕过。

## CodeGraph 接入规范

- CodeGraph 是 KB 流程的代码事实入口；凡涉及「代码现状、调用链、影响面、类似实现、依赖图、评审范围、知识库与代码一致性」的步骤，必须优先使用 CodeGraph，再按需读取具体文件。
- **默认工具**：`codegraph_explore`（摸底 + 源码 + 调用路径 + blast radius）；**已废弃** `codegraph_context`。精确影响面再用 `impact` / `callers` / `callees`。
- **项目级 MCP**：按当前宿主只写一份（Claude/其他 → 根 `.mcp.json`；Cursor → `.cursor/mcp.json`；禁止无脑双写；双 IDE 须用户明示）；示例见 `${PI_KB_ROOT}/bootstrap/examples/mcp/`（含 `CODEGRAPH_MCP_TOOLS`），bootstrap 不自动写入；launcher 可选 `${PI_KB_ROOT}/scripts/codegraph-mcp.cjs`。细则见 `references/kb-codegraph.md` §一。
- **门禁**：`design` / `plan` / `apply` / `revise-apply` / `review` / `archive` / `explore` / `query` / `sync` / `verify-issue` 为硬门禁（须 CodeGraph **可用**：宿主 `codegraph_*`、bridge `pi__codegraph_*`、或 CLI 等价路径**任一**；至少 explore）；`propose` 禁止 CodeGraph；`check` / `health` 为警告级。机器探测：`node "${PI_KB_ROOT}/scripts/kb-codegraph-check.mjs" --target "$(pwd)"`（索引可用 ≠ 工具名已暴露）。
- 索引门禁通过后若 MCP/bridge 未暴露：尝试 CLI，勿空转 blocked；仅 CLI/文件兜底须声明「未完成 MCP CodeGraph 核对」。细则见 [references/kb-codegraph.md](references/kb-codegraph.md) §2.2。
- `01-proposal.md`（业务 PRD）不使用 CodeGraph；`02`～`05` 产物的技术影响、影响面、评审范围与代码现状核对优先来自 CodeGraph 与知识库。
- 派发只读或实现子 Agent 时，prompt 须写清实际可调用名（`codegraph_explore` 或 `pi__codegraph_explore` 等），先 explore 再按需读文件；不得用大范围 grep/read 循环代替 CodeGraph。
- MCP 配置、门禁、LLM 操作规范与 01～05 各产物写入细则见 [references/kb-codegraph.md](references/kb-codegraph.md)。

## DeepSeek Search（Pi）

> **Pi 口径**：本包已 bundled `pi-deepseek-search`（工具 `web_search`）。配置与最佳实践见 [references/kb-deepseek-search.md](references/kb-deepseek-search.md)。

- **配置**：`/login` 选 DeepSeek，或 `export DEEPSEEK_API_KEY=...`；无 Key 时扩展不注册工具。引导：`/kb-deepseek-search-setup`。
- **分工**：仓内代码 → CodeGraph；业务语义 → knowledge；仓外/时效 → `web_search`。冲突时以仓内为准，外网须带 Sources 链接。
- **子 Agent**：派发 scribe/inspector/builder/reviewer/librarian 时 `tools` 已含 `web_search`；prompt 须要求具体 query、优先官方域名、落盘标注外部参考。
- **不阻断**：搜索失败只声明「未完成外网核对」，不替代 CodeGraph 硬门禁。


## Cursor Agent（Pi）

> **Pi 口径**：在 Pi 中使用 Cursor 模型/Agent 须业务仓配套安装 `pi-cursor-sdk`（**不** bundled，因 `@cursor/sdk` 含按平台二进制）。配置与最佳实践见 [references/kb-cursor-sdk.md](references/kb-cursor-sdk.md)。

- **安装**：业务仓 `pi install npm:pi-cursor-sdk -l --approve`，然后 `/reload`。引导：`/kb-cursor-setup`。
- **凭证**：`/login` 选 Cursor，或 `export CURSOR_API_KEY=...`（不复用 Desktop/CLI 登录态）。
- **选用**：`pi --approve --model cursor/composer-2-5` 或会话内 `/model`。
- **与 MCP**：Pi `.pi/mcp.json` 与 Cursor `.cursor/mcp.json` 两套；bridge 可将 Pi 工具以 `pi__*` 暴露给 Cursor。


## Figma Remote MCP（Pi）

> **Pi 口径**：本包已 bundled `pi-figma-remote-auth`（配合 `pi-mcp-adapter`）+ `/figma-oauth-sync`（session_start 自动导入密钥环）。配置与最佳实践见 [references/kb-figma-remote.md](references/kb-figma-remote.md)。

- **配置**：`/figma-remote-auth setup --project` → `/figma-remote-auth login` → `/figma-oauth-sync` → `/mcp reconnect figma`。引导：`/kb-figma-setup`。
- **为何 sync**：社区包只写明文 `mcp-oauth/figma/`；适配器读 OS 密钥环 / sha256 遗留路径。只 login 常仍 needs auth。
- **与提案闸门**：`/kb-propose` 的有无设计图 / `figma_url` 仍按产品闸门；读帧/组件走 Figma MCP。
- **清理**：业务仓可移除单独的 `npm:pi-figma-remote-auth` 与项目内重复的 figma-oauth-sync 扩展（装本包即自带）。


## Ponytail 精简实现（KB 集成）

- 蒸馏自开源 [ponytail](https://github.com/DietrichGebert/ponytail) 的 YAGNI / 删法优先思想；**不**整包复制其 rules/hooks，不与 KB lite/standard 路由混用档位。
- `/kb-design`、`/kb-plan`：方案与任务分解阶段防过度设计；`/kb-apply`：实现子 Agent 必遵六阶梯；`/kb-review`：full-review 增 Agent #6 精简轴（默认不阻断 archive）；`/kb-archive`：`05-summary` §3.1 harvest `ponytail:` 技术债。
- 阶段细则、注释约定、评审标签与 AGENTS 冲突消解见 [references/kb-ponytail.md](references/kb-ponytail.md)。

## 状态与归档判定

**`00-manifest.json` 最小字段**

```json
{
  "name": "<中文名称>",
  "flow": "standard|lite",
  "stage": "proposed|designed|planned|applying|applied|applied_audited|reviewed|review_failed|tested|archived|archived_with_debt|acceptance_reopened",
  "tasks": [],
  "reviews": [],
  "revisions": [],
  "files": [
    {
      "path": "<相对仓库根目录路径>",
      "kind": "code|knowledge|change_doc|index|config|test|other",
      "source": "apply|review|test|archive|lite|repair",
      "status": "planned|changed|archived|removed"
    }
  ],
  "updated_at": "<ISO-8601>",
  "workflow_version": "<按 kb-workflow-version.md 解析当前版本>"
}
```

`workflow_version` 取创建目录时的当前流程版本，**按** [`references/kb-workflow-version.md`](references/kb-workflow-version.md) shell 解析写入（勿硬编码占位版本号）。bootstrap 骨架仓尚无进化日志目录时，**首跑 `/kb-evolve` 前可省略**该字段。

**补建规则**

- 标准目录缺失 manifest：从现有 `01`～`07` 文件反推 `flow = "standard"`、当前最高阶段和任务 ID；无法判断的任务状态写 `"unknown"` 并在后续命令中澄清。
- 轻量目录缺失 manifest：若只有 `05-summary.md` 或低风险记录，写 `flow = "lite"`；否则升级为标准流程补齐。
- **新建**变更目录（`/kb-propose`、`/kb-lite`）在业务仓已有进化日志时**必须**包含 `workflow_version`（按 [`kb-workflow-version.md`](references/kb-workflow-version.md) 解析）；bootstrap 后尚未 `/kb-evolve` 时可省略；**历史**目录补建 manifest **可不写**此字段。
- 补建只记录当前可证事实，不为了通过流程虚构 `done`、`reviewed` 或 `archived`。

**归档状态只能三选一**

| manifest.stage | 含义 | 是否可提交 |
|---|---|---|
| `applied_audited` | apply 全通过 + 范围对账 ok；待评审 | 可以开始 review |
| `archived` | 任务完成、评审无阻断、知识库已同步 | 可以 |
| `archived_with_debt` | 团队明确接受遗留债务，债务已写入 `reviews[]` 或 `05-summary.md` | 可以，但提交说明/总结须说明债务 |
| `review_failed` / 其他阶段 | 存在阻断或流程未完成 | 不应归档提交 |

Markdown 中不得只写“有条件归档”而不更新 manifest；所有条件必须落到 `reviews[]`、`tasks[]` 或 `05-summary.md` 的明确条目。

**`manifest.files` 口径**

- `files[].path` 必须使用仓库根目录相对路径，禁止写模糊目录如“当前全部改动”。
- 代码实现完成后写入实际代码/配置文件；归档时补齐变更目录、知识地图/业务域/工程平台、所属领域/平台 `README.md`，仅总入口触发条件成立时补 `knowledge/index.md`；修复评审时追加修复文件并保留原文件记录。
- `05-summary.md` 的「实际变更」和「知识库更新清单」必须能与 `manifest.files` 对上；不一致时停止归档、提交。
- `/kb-commit` 只能从 `manifest.files`、`05-summary.md` 知识库清单、实际变更目录三部分合成暂存白名单，不能默认提交工作区全部改动。

**manifest 字段合法值**

- `files[].source`: `apply|review|test|archive|lite|repair`
- `files[].kind`: `code|knowledge|change_doc|index|config|test|other`
- `external.task_type`: `需求|Bug`（中文）

**评审问题状态**

`reviews[].status` 只允许四种值：

| status | 含义 | 后续动作 |
|---|---|---|
| `open` | 真实问题，尚未处理 | 不得归档为完成；修复后回写为 `fixed`，或由用户接受为债务 |
| `fixed` | 已按评审意见修复 | 需记录修复文件或关联任务 ID |
| `accepted_debt` | 用户/团队明确接受的遗留债务 | 只能归档为 `archived_with_debt` |
| `false_positive` | 复核后确认误报 | 需写明误报原因 |

评审发现的问题应优先转成修复任务：小问题可追加到当前任务验收标准；跨文件或影响设计的问题必须追加为新的 `T-FIX-{n}` 或 `T-Rev{n}-FIX-{m}`，再由 `/kb-apply` 或 `/kb-revise-apply` 定向修复。

## 意图识别与流程路由

- 用户表达需求、新功能、变更、实现、评审、验证、归档、提交等意图时，主 Agent 应主动识别并选择对应 `/kb-*` 流程，不要求用户必须说出命令名。
- 若意图不清，主 Agent 先问最关键的澄清问题；澄清完成后再调度子 Agent 执行实际落盘。
- 写 PRD / 需求文档 → **`/kb-propose`**（无 `/prd-creator`）；小改动 → `/kb-lite`；**外部登记/通知为可选**（由业务仓 `kb.project.json` → `integrations` 决定；未启用时仍须 `01` + manifest）；启用时见 [references/kb-external-sync.md](references/kb-external-sync.md)（回写细则见同目录 `kb-external-writeback.md`，若存在）；方案设计 → `/kb-design`；任务拆解 → `/kb-plan`；实现 → `/kb-apply`（标准流全部通过后强制 review→可执行 test）；已定稿后的 PRD 变更 → `/kb-revise`；变更实现 → `/kb-revise-apply`；评审 → `/kb-review`（通过后 `/kb-test`）；可执行验收 → `/kb-test`；归档 → `/kb-archive`；归档批清（可选运维）→ `/kb-archive-purge`；**产品验收反馈 → `/kb-verify-issue`**；状态/清单修复 → `/kb-repair`；知识库健康巡检 → `/kb-health`；提交 → `/kb-commit`。
- 状态不确定、准备进入下一阶段、归档或提交前自检 → `/kb-check`。
- 用户抱怨**流程本身**（步骤繁琐、口径歧义、规则与环境漂移）→ `/kb-feedback`；本会话多次摩擦/收工复盘 → `/kb-session-retro`（自动开 Issue）；要改包 → `/kb-evolve-setup` 后源码仓 `/kb-evolve`（不得在业务仓/npm 副本直接改流程文件）；要网络最佳路径 → `/kb-evomap-setup`（默认关闭）。

### 路由量化（降低口径分歧）

为减少“lite 还是 standard”反复争论，默认使用以下打分：

| 判定项 | 命中记分 |
|---|---|
| 涉及 proto / HTTP / gRPC 契约变化 | +3 |
| 涉及数据库结构、资金、权限、事务语义 | +3 |
| 涉及跨端联动（Flutter/Rust/Quasar 至少两端） | +2 |
| 需要新增或重排知识地图、业务域、工程平台多处知识文件 | +2 |
| 需求边界不清，需要 2 个以上关键追问 | +1 |

- 总分 `>= 3`：直接走标准流程（`/kb-propose` 起步）。
- 总分 `<= 2`：优先走 `/kb-lite`。
- 命中前两项任意一条时，不走 lite（硬闸门）。

### 紧急修复快车道（hotfix-lite）

用于线上阻断类问题，目标是在不牺牲追溯的前提下缩短路径：

1. 走 `/kb-lite <中文名称>`，manifest 标记 `flow = "lite"` 并在 `05-summary.md` 顶部注明 `hotfix-lite`。
2. 允许先实现后补全“知识库更新”小节，但必须同一轮补齐，不能跨轮留待办。
3. 若修复过程中发现触发硬闸门（契约/数据/权限/资金/事务），立即升级标准流程。
4. hotfix-lite 结束后直接归档；后续需要扩展时，再基于同名议题开标准流程变更目录。

## 编排与子 Agent（全链路默认）

**角色分工**

- **主 Agent**：识别用户意图并路由到对应 `/kb-*` 流程；与用户澄清；拆解原子工作项；调度、审核、合并意图与结构；汇总结果；失败时重派子 Agent。**主 Agent 不直接写任何文件**。
- **子 Agent**：通过 Cursor **`Task` 工具**启动；每个子任务一份 prompt，**单一交付物**（例如：文件列表 + 风险三条、某一节的 Markdown 草案、单条 `T{n}` 任务全文、单轮代码实现）。凡涉及文档、知识库、代码、索引、提交状态更新等写入，均由子 Agent 执行。

**阶段推进（必遵）**

- 标准流 `propose → design → plan → apply → review → test`：阶段成功完成后**默认同会话串联下一跳**；禁止仅为礼貌确认拦停（问「下一步是否 design/plan/apply？」）。
- 仅产品/风险决策、硬门禁失败、或用户明示暂停时才 interview；「完成功能」类指令按默认序列直接推进。

**并行**

- 无相互依赖的子任务**同一轮并行**派发多个 `Task`（例如多模块影响面、五角评审、按业务域/工程平台分片读知识库）。
- 有依赖的（如必须先有接口定义再写调用方）按拓扑分轮调度。

**`subagent_type` 与 KB 工种（建议，以当前可用工具为准）**

KB 工种定义见 [references/kb-agent-roles.md](references/kb-agent-roles.md)。`/kb-orchestrator` 时 **默认** `Task(kb-admin)` 委派整段编排（[`agents/kb-admin.md`](../../agents/kb-admin.md)），admin 按 stage 派工种、不写盘；仅用户明确要求 inline 时主 Agent 扮演 kb-admin（**仍须** Task 派 builder/scribe 等工种）。单步 `/kb-*` 时主 Agent 直接派对应工种，prompt 引用 command + 工种章节。

- **常见误读**：把「inline 扮演 admin」理解成「调度员自己执行写盘/改代码」——**禁止**；inline 仅指不 spawn 嵌套 kb-admin 子会话，所有写入仍由工种子 Agent 经 `Task` 执行。

| 类型 / 工种 | 典型用途 |
|------|----------|
| **kb-admin** | `/kb-orchestrator` 调度（**Task 默认**委派整段编排；inline 仅用户明确要求时；**仍须** Task 派 builder/scribe 等工种） |
| **kb-scribe** | 变更文档、反馈登记 — [`agents/kb-scribe.md`](../../agents/kb-scribe.md) |
| **kb-builder** | 按 `03` 实现代码 — [`agents/kb-builder.md`](../../agents/kb-builder.md) |
| **kb-reviewer** | `04-review.md` — [`agents/kb-reviewer.md`](../../agents/kb-reviewer.md) |
| **kb-recorder** | 可执行验收 + `06`/`08` — [`agents/kb-recorder.md`](../../agents/kb-recorder.md) |
| **kb-librarian** | sync/archive 知识合并 — [`agents/kb-librarian.md`](../../agents/kb-librarian.md) |
| **kb-release** | commit/push/迁移/外部 sync — [`agents/kb-release.md`](../../agents/kb-release.md) |
| **kb-inspector** | 只读 query/explore/health — [`agents/kb-inspector.md`](../../agents/kb-inspector.md) |
| `generalPurpose` | **fallback**：环境无对应 `kb-*` subagent 时，prompt 须声明工种 + agents 文件链接 |
| `best-of-n-runner` | 隔离试验或并行实现候选 |
| `bugbot` | 可选作 kb-reviewer 一角（full-review） |

**并行写入约束**

- 同一轮并行任务默认不得写同一个文件；若确需修改同一文件，必须拆成串行轮次，或使用隔离工作区完成后由单一子 Agent 合并。
- `03-tasks.md` 的每个任务必须列出「实现范围」与「可能冲突文件」；调度前先按文件集合分组，冲突文件只允许一个写入者。
- `00-manifest.json` 是状态唯一入口，**始终**计入同文件冲突；并行 builder **禁止**各自写盘，轮末由单一 `kb-scribe`/合并 Task 串行合并 `tasks[]`；任务完成、评审关闭、Rev 实现状态变更后，必须同步更新 manifest。

**交付物格式（子 → 主）**

- 子 Agent 默认用**条列、表格、小节标题**回报，便于主 Agent 审核和组织 `01`～`07` 或知识库内容；需要落盘时，由主 Agent 明确目标路径与写入范围，再派发子 Agent 执行写入。

**目录 AGENTS.md 沉淀（实现类子 Agent 必遵）**

- 主 Agent 派发**实现类**子 Agent（`/kb-apply`、`/kb-revise-apply`、`/kb-lite` 实现步骤等）时，prompt **必须**要求收尾沉淀。
- 子 Agent 任务验收通过后，总结本次犯错经验，将可复用规矩写入**本次改动涉及目录**的 `AGENTS.md`（最贴近改动文件的目录；无则新建）。
- 内容 = **高度总结的规矩**（做什么/不做什么、常见坑、目录强绑定约定）；**禁止**流水账式记录单次变更或带日期的「评审沉淀」章节。
- 细则见 [references/kb-agents-precipitation.md](references/kb-agents-precipitation.md)。

**子 Agent 回写校验（外部同步相关命令必遵）**

- 子 Agent 回报「已写 manifest / 外部同步已完成」后，主 Agent / orchestrator 必须用 **shell 读磁盘**（如 `cat …/00-manifest.json`）确认对应字段（`external.registry_record_id`、`notified_events`、本轮 `notified`），**不得**仅凭 IDE Read 工具或子 Agent 口头成功就重派或自行补跑外部 API。
- 外部同步幂等：磁盘已有 `external.registry_record_id` 登记、`notified_events` 已含 `"completed"`、或本轮验收 `notified === true` 时，**禁止**重复登记或重复发通知。
- 事件契约：[references/kb-external-sync.md](references/kb-external-sync.md)；provider 回写见同目录 `kb-external-writeback.md`（若存在）。

**实现类命令**

- `/kb-apply`、`/kb-revise-apply`：**每个 `03` 原子任务对应一次（或一轮内并行多次）**子 Agent 实现，主 Agent 负责解析依赖图、组批、验收；并行组 builder 只回报状态，`00-manifest.json` 由单一子 Agent（优先 kb-scribe）轮末写回；细则见各命令文件。

## 命令速查

| 命令 | 阶段 | 产出 | 角色 |
|------|------|------|------|
| `/kb-init` | 初始化 | `knowledge/` 骨架 + `.kb/` schema + `kb.project.json` | 维护者 |
| `/kb-sync` | 同步 | 更新后的知识库 | 维护者 |
| `/kb-check` | 校验 | 只读一致性报告 | 所有角色 |
| `/kb-okf-migrate` | OKF 迁移 | dry-run 报告或 apply 后的 OKF 布局 + wikilink/图谱字段 | 维护者 |
| `/kb-index` | 索引 | 总索引 + 领域/平台局部 index | 维护者 |
| `/kb-explore` | 探索 | 问题理解和方向 | 产品/开发 |
| `/kb-query` | 检索 | 精确知识检索 | 所有角色 |
| `/kb-lite <中文名称>` | 轻量变更 | `01-proposal.md`（轻量说明）+ `00-manifest.json` + `05-summary.md`；**可选** `manifest.external` | 开发 |
| `/kb-propose <中文名称>` | 业务 PRD | 01-proposal.md（产品 PRD）+ manifest；**可选** external 登记 | 产品/开发 |
| `/kb-design <中文名称>` | 设计 | 02-design.md（业务流程图 + 改动对照表 + 实现方案） | 开发 |
| `/kb-revise <中文名称>` | 需求变更（文档） | 追问直至澄清；仅更新 07 + 01/02/03，**不写代码** | 产品/开发 |
| `/kb-revise-apply <中文名称>` | 需求变更（代码） | 仅实现 07 本轮关联的 03 任务 | 开发 |
| `/kb-plan <中文名称>` | 任务分解 | 03-tasks.md 原子任务列表 + 依赖图 | 开发 |
| `/kb-apply <中文名称>` | 实现 | 代码变更；标准流全部通过后**对账 → 范围审计 →**同会话强制 review→可执行 test（lite 豁免） | 开发 |
| `/kb-review <中文名称>` | 评审 | 04-review.md；通过后下一步 `/kb-test`（非直接 archive） | 开发 |
| `/kb-test <中文名称>` | 可执行验收 | 分层执行 ui>contract>unit + `06-automation-test.md`；失败不标 tested | 开发 |
| `/kb-archive <中文名称>` | 归档 | 更新后的知识库 + 05-summary.md + **commit+push**；**可选** external sync（步骤 10）；标准流须有 04 且无 open，不强制 06 文件 | 维护者 |
| `/kb-archive-purge` | 归档批清 | 按 retention 硬删过期归档目录；保留 `归档/.tombstones/` 供查重与审计 | 维护者 |
| `/kb-verify-issue <中文名称>` | 验收反馈 | 校验→归档回退进行中→归因→问题报告；**可选** 表格/群通知 | 产品/维护者 |
| `/kb-orchestrator` | 总编排 | 串联 propose→…→archive（external sync 按配置） | 主 Agent |
| `/kb-repair <中文名称>` | 恢复 | 只修 manifest/清单/摘要漂移 | 维护者 |
| `/kb-health` | 巡检 | 知识库衰减、重复、失效引用与漂移报告 | 维护者 |
| `/kb-feedback <描述>` | 流程反馈 | Gitee Issue（pi-kb-feedback）；不写本地反馈目录 | 所有角色 |
| `/kb-session-retro` | 会话回顾 | 总结本会话失败/摩擦 → 自动 Gitee Issue | 所有角色 |
| `/kb-evolve [Issue号\|主题]` | 流程进化 | 仅源码仓；拉 Issue → 改包 → docs/evolution → MR；可选 EvoMap | 贡献者/维护者 |
| `/kb-evolve-setup` | 本地进化环境 | 克隆/fork 源码、业务仓改挂本地路径、拉分支 | 贡献者 |
| `/kb-evomap-setup` | EvoMap 开关 | 注册/claim/enable（默认关闭）；网络最佳路径 | 贡献者 |
| `/kb-deepseek-search-setup` | DeepSeek Search | 配置 `web_search`（DeepSeek Key）；实践见 kb-deepseek-search.md | 所有角色 |
| `/kb-cursor-setup` | Cursor Agent | 业务仓装 `pi-cursor-sdk` + Cursor API Key；实践见 kb-cursor-sdk.md | 所有角色 |
| `/kb-figma-setup` | Figma Remote MCP | bundled `pi-figma-remote-auth` setup/login；实践见 kb-figma-remote.md | 所有角色 |
| `/kb-commit <中文名称>` | 提交 | 白名单 commit + **默认 push** | 维护者 |

## 流程反馈与进化（闭环）

> **Pi 口径（与 Claude Code 本地 FB 模型解耦）**：完整说明见 [references/kb-feedback-gitee.md](references/kb-feedback-gitee.md)；可选 EvoMap 见 [references/kb-evomap.md](references/kb-evomap.md)。

```
业务仓 /kb-feedback 或 /kb-session-retro → Gitee Issue（label pi-kb-feedback）
→（可选）/kb-evolve-setup 拉源码 + 本地路径安装
→（可选）/kb-evomap-setup 开启网络进化（默认关闭）
→ 源码仓 /kb-evolve → docs/evolution 留痕 → MR → master
→（若 EvoMap publish 开启且用户确认）回传 Gene/Capsule
→ 维护者合入后 publish → 业务仓 pi update
```

- 业务仓**禁止**写 `knowledge/.../反馈/`；**禁止**在 npm 副本上 `/kb-evolve`。
- `/kb-session-retro`：会话级总结失败经验并对可改进项**自动**开 Issue；扩展在 `/new` 前若检测到摩擦会确认后自动注入。
- `/kb-evolve` 仅 pi-kb **git 源码检出**；机器探测：`node "$PI_KB_ROOT/scripts/kb-evolve-setup.mjs" --check`。
- EvoMap **默认关闭**；开启：`/kb-evomap-setup`（`kb-evomap.mjs`）。
- 细则以 `prompts/kb-feedback.md`、`prompts/kb-session-retro.md`、`prompts/kb-evolve.md`、`prompts/kb-evolve-setup.md`、`prompts/kb-evomap-setup.md` 为准。


## 流程分级

| 等级 | 适用场景 | 最小产物 | 后续要求 |
|---|---|---|---|
| 超轻记录型 lite | 纯文案、样式、日志、注释或单点无行为变化修正 | `01`（轻量说明）+ `00-manifest.json` + 极简 `05-summary.md`；可选 `external` | 可同轮 optional 登记、实现并归档 |
| 记录型 lite | 局部 bug 或小行为修正，知识库现状无需变化 | `01` + `00-manifest.json` + `05-summary.md`；可选 `external` | 可同轮 optional 登记、实现并归档 |
| 知识同步型 lite | 小改但会改变一处当前生效知识 | `01` + `00-manifest.json` + `05-summary.md` + 目标知识文件；可选 `external` | optional 登记后实现；归档前更新知识文件 |
| hotfix-lite | 线上阻断的小范围紧急修复 | `01` + `00-manifest.json` + `05-summary.md`（标注 hotfix-lite）；可选 `external` | 允许一轮直通 optional 登记、实现与归档 |
| 标准流程 | 新功能、跨端契约、数据/权限/资金/事务、需正式 PRD | `01` 业务 PRD（propose）+ `02` 设计起 `01`～`07` + 可选 `external` | propose 可选 external 登记；知识库影响在 `02` |

**知识库影响快速判定**：

| 代码变化 | 默认影响（业务域内落到对应子模块文件的相应段，跨子模块聚合落 `01-概览`） |
|---|---|
| `doger_proto/` | 相关子模块文件「5、接口」「6、数据」段；必须重新生成相关代码 |
| `rust_server/src/endpoints/`、HTTP/gRPC 入参出参 | 相关子模块文件「5、接口」「3、服务端规则」段 |
| `rust_server/src/services/`、跨模块调用链 | 相关子模块「3、服务端规则」与 `01-概览` 架构/依赖；跨域复用能力补工程平台 |
| `rust_server/src/infrastructure/`、数据库模型、缓存、队列 | 相关子模块「6、数据」「7、非功能与可观测」段；跨域基础设施补工程平台 |
| `vkk_client_flutter/lib/` 用户可见功能 | 相关子模块「1、能力范围」「4、客户端流程」段与 `01-概览`；端工程通用规则补工程平台 |
| `quasar/src/` 管理后台功能 | 后台相关子模块「4、客户端流程」段与 `01-概览`；后台工程通用规则补工程平台 |
| 纯样式、局部文案、日志、无行为变化的内部修正 | 默认不更新知识地图/业务域/工程平台，但须在 `05-summary.md` 写明原因 |

**两级索引更新触发条件**：

- 业务域内知识文件新增、删除、重命名时，先更新 `knowledge/业务域/<领域>/index.md`；普通正文变化仅在 README 一句话用途、职责边界或阅读路径失真时更新 README。
- 工程平台分区新增、删除、重命名时，先更新 `knowledge/工程平台/index.md`；工程平台分区内文件新增、删除、重命名时，先更新 `knowledge/工程平台/<中文平台分区>/index.md`，并仅在平台入口失真时更新根 README。
- 工程平台主题触发分区规则时，必须同轮完成文件迁移、分区 index、平台根 index 与 `manifest.files` 更新；不得只留下“后续拆分”待办。
- 仅当新增/删除/重命名 `knowledge/业务域/<领域>/index.md`、`knowledge/工程平台/index.md`、`knowledge/知识地图.md` 入口，或总入口引用失效/摘要失真时，更新 `knowledge/index.md`。
- `knowledge/变更/归档/` 的新增、移动、重命名不触发总索引或局部 index；归档目录只是证据，不进入日常检索主体。
- 只修改变更目录 `00`～`08` 且未影响当前知识时，不运行 `/kb-index`，但需要在 `05-summary.md` 写明两级索引无需更新原因。

## 标准开发流程

```
propose → design → plan → apply → review → test → archive（含 commit+push；external sync 按配置）
  提案      设计    分解    实现    评审    可执行验收    归档（迁移+提交+通知）
                    │         └─ 标准流全部通过后同会话强制 ──┘
                                                          │
                                  产品验收反馈问题 ◄───────┘
                                  /kb-verify-issue（归档回退进行中 + 归因 + 可选 external 回写）
                                  ├─ 代码问题 → 重新打开 → /kb-apply、/kb-revise-apply → 再 archive
                                  └─ 需求问题 → 已关闭-产品 → /kb-revise（如需调整）
```

**阶段准入**

- `design` / `plan` / `apply` / `review` / `test` / `archive` / `commit` 前：如 manifest、任务状态、知识库更新范围或索引覆盖有疑问，先运行 `/kb-check <中文名称>`；校验阻断项未解决时不进入下一阶段。
- `apply` 前：`03-tasks.md` 必须存在，manifest 中任务状态不能全为 `unknown`；无法反推的历史任务先补状态再实现。
- `apply` 后（`flow=standard`）：全部任务通过 → `stage=applied` → manifest validate → **强制** `/kb-review` → 通过后 **强制** 可执行 `/kb-test`；不得跳过直达 archive。`flow=lite` 豁免。
- `review` 前：必须有代码 diff 或明确的最近提交范围；评审结论必须同步到 manifest。
- `review` 后：若存在 `reviews[].status = "open"`，必须修复、接受债务或标记误报并说明原因；不得只在 `04-review.md` 写“后续处理”。通过后下一步为 `/kb-test`，非直接 archive。
- `test`：默认可执行；分层 ui>contract>unit；失败不写 `stage=tested`；允许 `auto_test/` 补 Playwright/契约，禁 unit 脚手架。
- `archive` / `check`（标准流）：必须有 `04-review.md` 且无 `open`；**不强制** `06` 文件存在。若 `04` 未通过，必须修复后重评，或由用户/团队明确接受债务并写入 `archived_with_debt`。
- `archive` 内顺序：`mv` 迁移（核心原则 15）→ commit+push → **若启用 integrations** 则 external sync 步骤 10（细则见 [references/kb-external-sync.md](references/kb-external-sync.md)、`kb-external-writeback.md` 若存在）；orchestrator 不得跳过或颠倒。
- 独立 `commit`：仅用于 archive 中断恢复；`/kb-archive` 正常收尾已含 commit+push，无需再跑 `/kb-commit`。

**中断恢复口径**：

- `apply` / `review` / `archive` / `commit` 中断后，先运行 `/kb-check <中文名称>` 的只读口径定位：manifest 阶段、`files[]`、Markdown 摘要、知识库清单、两级索引引用、git 暂存范围是否漂移。
- 只存在状态、文件清单、摘要勾选、归档位置等元数据漂移时，使用 `/kb-repair <中文名称>` 修复；该命令禁止改业务代码。
- 若漂移涉及真实实现缺口、评审未闭环或知识库内容缺失，回到对应 `/kb-apply`、`/kb-review`、`/kb-archive`，不要用 repair 冒充完成。

**轻量开发流程**

适用于：文案/样式/局部 bug/小范围配置调整，且不新增 proto 契约、不改数据库结构、不引入跨端协作。

```
lite（可选 external 登记）→ archive（含 commit+push；可选 external sync）
小改+可选登记              归档+可选群通知
```

若 `/kb-lite` 执行中发现涉及跨端契约、数据结构、权限/资金/事务等高风险路径，必须升级为标准流程，从 `/kb-propose` 重新进入。

**轻量流程上限**

- 默认修改范围不超过少量文件，且不改变稳定接口、持久化数据、计费/权限/事务语义。
- 一旦需要写 `02-design.md` 或 `03-tasks.md` 才能讲清楚，就不再使用 lite。
- lite 仍必须产出 `01-proposal.md`（轻量说明）、`00-manifest.json`、`05-summary.md`；**若启用 integrations.registry** 则还须 `manifest.external`；“太小不用记录”不成立。记录型 lite 可由同一轮子 Agent 完成 optional external 登记、实现、`05-summary.md`、`manifest.files` 与归档迁移，不要求 `02`～`04` 或 `06`，也不要求五角评审；**豁免**标准流 apply 后自动 review+可执行 test。

**PRD 在实现后多次变更**：`/kb-revise`（澄清 + **仅文档**）→ 可选 `/kb-plan` → **`/kb-revise-apply`（仅本轮代码）** → `review` / `test` → …；可循环多轮。全量任务仍用 `/kb-apply`。

### 典型场景速查

四个典型场景：**A 新功能开发**（`/kb-propose` → … → `/kb-apply` 后强制 `/kb-review` → `/kb-test` → `/kb-archive`）、**B 快速了解系统**（`/kb-explore`、`/kb-query`）、**C 排查问题**（`/kb-query` → `/kb-explore` → `/kb-sync`）、**D 已实现后产品 PRD 多次变更**（`/kb-revise` → `/kb-revise-apply` → review/test → archive）。各场景步骤、原则与推荐命令序列细则见 [references/kb-scenarios.md](references/kb-scenarios.md) 与 [SOP.md](SOP.md) 场景 A。

## 变更目录结构

### 在途变更（进行中目录）

```
knowledge/变更/进行中/<YYYYMMDDHHMMSS>-<中文名称>/
├── 00-manifest.json   # 机器可读状态：流程类型、阶段、任务/评审/Rev 状态、涉及文件
├── 01-proposal.md    # /kb-propose 产出（业务 PRD，非技术方案）
├── 02-design.md      # /kb-design 产出（业务流程图 + 改动对照表）
├── 03-tasks.md       # /kb-plan 产出
├── 04-review.md      # /kb-review 产出
├── 05-summary.md     # /kb-archive 产出
├── 06-automation-test.md   # /kb-test 产出（标准流强制跑 test；archive/check 不强制该文件存在；禁止长日志与敏感信息）
├── 07-prd-revisions.md     # 可选：/kb-revise 产出（履历表；含每轮「关联 03 任务」供 /kb-revise-apply 解析）
└── 08-verify-issue.md      # 可选：/kb-verify-issue 产出（验收打回问题报告与归因）
```

**变更文档命名规范**：
- 必须按 kb-flow 产出优先级添加两位数字前缀，保持目录排序即流程顺序；`00-manifest.json` 固定为机器状态文件，不替代任何 Markdown 说明。
- 标准顺序固定为：`00-manifest.json` → `01-proposal.md` → `02-design.md` → `03-tasks.md` → `04-review.md` → `05-summary.md`；验收记录可增加 `06-automation-test.md`（不改变前五步编号语义）；**需求多轮迭代**可增加 `07-prd-revisions.md`；**验收打回**可增加 `08-verify-issue.md`（不改变 01～06 的语义）。
- 新建、读取、归档变更文档时使用带序号文件名，新增产物必须使用带序号命名。

### 已归档变更（归档目录）

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

**命名约束**：
- 目录名格式：`<YYYYMMDDHHMMSS>-<中文名称>`，`YYYYMMDDHHMMSS` 为 **14 位数字**（年月日时分秒，无分隔符）
- **新建目录时**（`/kb-propose`、`/kb-lite` 等）：子 Agent **必须**在 shell 执行 `KB_CHANGE_ID="$(TZ=Asia/Shanghai date +%Y%m%d%H%M%S)"` 后再 `mkdir`；禁止脑填、占位整点或非当前时刻前缀。细则见 [references/kb-change-directory-id.md](references/kb-change-directory-id.md)
- 同一中文议题已存在 `进行中/` 或 `归档/` 目录时，不得再建第二个前缀目录
- 归档后从 `knowledge/变更/进行中/` **`mv` 移动**到 `knowledge/变更/归档/`（口径以核心原则 15 为准）

## 约定

1. **中文编写**：所有知识文件、变更文档使用中文
2. **每文件 <= 3000 字符**：超限时拆分为多个文件
3. **知识库叙述 = 与代码一致的「当前生效」说明**：知识地图、业务域、工程平台与 01～03 正文只写**当前生效**内容，并以代码验证为准；**同一变更议题**下的 PRD 多轮差异用 `07-prd-revisions.md` 按轮次追加（属于变更目录内履历，不替代当前知识文件职责）
4. **不做额外扩散**：只更新清单中标记的文件
5. **归档后 mv 至归档目录**：已归档变更迁移到 `knowledge/变更/归档/`，口径以核心原则 15 为准；目录默认可保留，批清走 `/kb-archive-purge` + tombstone（核心原则 14、20）
6. **OKF 与图谱**：概念文件 YAML `type`、`related`、`depends_on`；内部 wikilink；入口 `index.md`；结构性变更写 `log.md`；细则 [references/kb-okf.md](references/kb-okf.md)、[references/kb-graph.md](references/kb-graph.md)

## 验收记录文档（06）与 Agent 输出

- 执行 `/kb-test` 或维护 `06-automation-test.md` 时：默认**尝试执行**可执行项，再落盘策略/追溯/执行记录；**验收视角** = 范围与层级（**ui / contract / unit / other**；补写时 ui>contract>unit）、前置与数据、期望与失败判责、**与 03-tasks 的可追溯矩阵**、未自动化项及原因、`skipped-duplicate`、副作用与清理。
- **失败不标 tested**：可执行项失败时不得写 `manifest.stage=tested`。
- **控制输出**：用户可见回复只给**摘要**（通过/失败、阻断项少量条列、环境一句话）；不把完整终端日志粘进聊天；`06-automation-test.md` 仅用**表格与短句**，执行记录**一行一次**。
- 完整规范以 **`commands/kb-test.md`** 为准；工种边界见 [references/kb-agent-roles.md](references/kb-agent-roles.md)。