teamai-cli 0.16.8 → 0.17.0

package/skills/team-wiki-codebase/references/agents/graph-rag-agent.md

@@ -0,0 +1,344 @@
+# Graph RAG Agent
+
+## 职责
+
+从已生成的知识库组件文档中抽取跨组件关系信息，生成结构化图谱文档集（G1~G9），解决 RAG 检索在"跨组件关系查询"场景下的信息分散问题。
+
+**此 Agent 在 Phase K3 中被主 Agent 单次串行启动。**
+
+## 输入包
+
+```
+all_kb_docs_dir:  知识库输出根目录（包含所有 Type-1~8 文档）
+architecture_map: _review/k1-architecture-map.md 完整内容
+doc_list:         _review/k2-doc-list.md（文档清单）
+project_name:     项目名称（用于文档命名）
+output_dir:       图谱文档输出目录（<all_kb_docs_dir>/graph/）
+methodology_file: references/methodology/phase2-document-types.md §Type-9 内容
+```
+
+## 执行步骤
+
+### Step 1：关系抽取
+
+扫描 `all_kb_docs_dir` 下所有组件文档（Type-4），从 AI 快速理解表和正文中提取：
+
+```
+扫描维度:
+├── 调用关系 (上游组件→本组件, 本组件→下游组件, 通信方式)
+├── 存储依赖 (读写了哪些 DB/Redis/MQ)
+├── 消息拓扑 (发布/消费的 Exchange/Topic/Queue/RoutingKey)
+├── 状态流转 (操作→起始状态→中间状态→终态, 状态字段值)
+├── 约束条件 (操作→前置状态要求→硬件约束→计费约束→配额)
+├── 配置映射 (配置项→影响行为→变更风险)
+└── 错误码归属 (错误码段→组件→排查方向)
+```
+
+**置信度三态标注**（每条关系/三元组必须标注，不得省略）：
+
+| 标签 | 含义 | 来源依据 | 置信度分值 |
+|------|------|---------|-----------|
+| `EXTRACTED` | 组件文档中明确描述的关系（如"上游组件: Aurora(RPC)"）| 代码/文档显式记录 | 1.0 |
+| `INFERRED` | 合理推断的关系（如架构图中隐含的依赖链）| 结构性证据 + 合理推断 | 0.6~0.9 |
+| `AMBIGUOUS` | 存在不确定性的关系，需人工确认 | 弱证据或相互矛盾 | 0.1~0.3 |
+
+> ⚠️ **禁止用 0.5 作为默认分值**。每条关系都要独立评估：有直接代码引用的 INFERRED 用 0.8~0.9，仅靠命名推断的用 0.6~0.7，真正模糊的才用 AMBIGUOUS。
+
+构建中间数据结构（内存，不写文件）：
+- `relations[]`：(from, to, protocol, scenario, **confidence: EXTRACTED|INFERRED|AMBIGUOUS**, **confidence_score: 0.1~1.0**)
+- `state_transitions[]`：(entity, from_state, to_state, trigger_op, state_field_value, **confidence**, **confidence_score**)
+- `constraints[]`：(operation, state_req, hardware_req, billing_req, quota_req, **confidence**, **confidence_score**)
+- `config_items[]`：(key, default, component, behavior, change_risk, effect_mode)
+- `error_codes[]`：(code_range, component, meaning, debug_direction)
+- `triples[]`：(subject, predicate, object, protocol, scenario, **confidence: EXTRACTED|INFERRED|AMBIGUOUS**, **confidence_score: 0.1~1.0**)
+
+### Step 2：逐份生成图谱文档
+
+按顺序生成 G1~G9（串行，每份完成后立即 Write）：
+
+---
+
+#### G1：组件依赖关系矩阵
+
+```markdown
+# {project_name} 组件依赖关系矩阵
+<!-- search-anchor: 组件依赖, 依赖矩阵, 通信方式, 调用关系 -->
+## 🤖 AI 快速理解要点
+| 文档定位 | 解决"谁依赖 X？X 依赖谁？"的检索问题 |
+| 核心价值 | N×N 通信矩阵 + 正向/反向依赖索引 |
+| 使用场景 | 变更影响评估、服务依赖梳理、架构重构规划 |
+
+## N×N 组件通信矩阵
+（行：调用方，列：被调方，值：`RPC`/`MQ`/`DB`/`—`，括号内标注置信度标签）
+示例：`RPC[E]` = EXTRACTED，`MQ[I:0.8]` = INFERRED 0.8，`RPC[A]` = AMBIGUOUS
+
+## 正向依赖索引（A 依赖谁）
+| 组件 | 依赖组件 | 通信方式 | 置信度 | 典型场景 |
+
+## 反向依赖索引（谁依赖 A）
+| 组件 | 被依赖来自 | 通信方式 | 置信度 | 典型场景 |
+
+## 外部服务依赖
+| 外部服务 | 被哪些组件依赖 | 通信方式 | 置信度 | 降级策略 |
+
+## 置信度统计
+| 标签 | 条数 | 说明 |
+|------|------|------|
+| EXTRACTED | N | 来自代码/文档直接描述 |
+| INFERRED | N | 合理推断，标注分值 0.6~0.9 |
+| AMBIGUOUS | N | 不确定，需人工确认 |
+```
+
+---
+
+#### G2：组件调用链路全景 + 状态机
+
+```markdown
+# {project_name} 组件调用链路全景与状态机
+<!-- search-anchor: 调用链路, 状态机, 端到端链路, API链路 -->
+## 🤖 AI 快速理解要点
+| 文档定位 | 解决"API X 经过哪些模块？实体状态如何流转？"的检索问题 |
+| 核心价值 | 核心API端到端链路 + 完整状态机 + 操作-状态约束矩阵 |
+
+## 核心 API 端到端调用链路
+（对每个核心 API，用标准调用链格式 + mermaid 时序图）
+
+## 核心实体完整状态机
+（mermaid stateDiagram-v2，标注状态字段值和触发操作）
+
+## 操作-状态约束速查矩阵
+| 操作 \ 当前状态 | 状态A | 状态B | ... |
+（✅ 允许 / ❌ 禁止 / ⚠️ 有条件）
+
+## AI 状态判断推理规则
+（mermaid graph TD 决策树）
+```
+
+---
+
+#### G3：数据流与存储依赖图
+
+```markdown
+# {project_name} 数据流与存储依赖图
+<!-- search-anchor: 数据流, 存储依赖, MQ拓扑, 缓存 -->
+## 存储系统依赖矩阵
+| 组件 | MySQL | Redis | MQ | 对象存储 | 其他 |
+
+## MQ 队列拓扑
+| Exchange/Topic | Routing Key | 生产者 | 消费者 | 消息含义 |
+
+## 缓存策略矩阵
+| 组件 | 缓存键模式 | 过期时间 | 失效策略 |
+```
+
+---
+
+#### G4：错误码组件映射表
+
+```markdown
+# {project_name} 错误码组件映射表
+<!-- search-anchor: 错误码, 错误映射, InvalidParameter -->
+## 错误码段分配
+| 错误码范围/前缀 | 归属组件 | 含义范围 |
+
+## 外部→内部错误码映射
+| 外部错误码 | 内部组件 | 内部含义 | 排查方向 |
+```
+
+---
+
+#### G5：跨组件交互场景手册
+
+对每个核心业务场景，生成：
+```markdown
+## 场景N：{场景名称}
+<!-- 典型场景：创建/删除/修改资源、配额检查、计费、状态变更等 -->
+```mermaid
+sequenceDiagram
+    actor User
+    participant A as {组件A}
+    participant B as {组件B}
+    ...
+```
+**正常流程**：步骤描述
+**异常处理**：各异常分支
+```
+
+要求：≥10 个场景，覆盖主要写操作和关键读操作。
+
+---
+
+#### G6：知识图谱三元组
+
+```markdown
+# {project_name} 知识图谱三元组
+<!-- search-anchor: 知识图谱, 三元组, 多跳推理 -->
+
+## Ontology 定义
+### 实体类型: Service, Handler, Config, Table, Queue, API, ErrorCode
+### 关系类型: CALLS, PUBLISHES, CONSUMES, READS, WRITES, CONFIGURES, MAPS_TO
+
+## 显式三元组（≥100条）
+| Subject | Predicate | Object | Protocol/Scenario | Confidence | Score |
+
+> 每条三元组的 Confidence 必须是 `EXTRACTED` / `INFERRED` / `AMBIGUOUS`，Score 不得省略，不得用 0.5 作默认值。
+
+## 多跳依赖路径索引
+| 查询模式 | 路径示例 |
+| "A 最终写入哪些表？" | A→(CALLS)→B→(WRITES)→Table |
+
+## 反向可达索引
+| 目标节点 | 可达路径 |
+```
+
+---
+
+#### G7：架构风险与影响面分析
+
+```markdown
+# {project_name} 架构风险与影响面分析
+<!-- search-anchor: 架构风险, 爆炸半径, 影响面 -->
+## 组件风险等级总表
+| 组件 | 风险等级 | 爆炸半径 | 备注 |
+（🔴高/🟡中/🟢低）
+
+## 关键组件爆炸半径分析（≥3个高风险组件）
+组件 X 故障时的影响链路分析
+
+## 关键路径与瓶颈识别
+## 聚类分析（哪些组件形成强耦合簇）
+## 变更风险评估矩阵
+```
+
+---
+
+#### G8：核心配置参数索引
+
+```markdown
+# {project_name} 核心配置参数索引
+<!-- search-anchor: 配置参数, 配置索引, 配置变更 -->
+## 分层配置架构图（mermaid）
+
+## 各层配置参数表
+| 配置项 | 所属组件 | 默认值 | 影响行为 | 变更风险 | 生效方式 |
+（变更风险: 🟢低/🟡中/🔴高；生效方式: 热生效/需重启）
+
+## 配置变更影响面速查
+| 变更类型 | 影响范围 | 生效方式 | 回滚策略 |
+
+## AI 回答"怎么修改 XX 配置"时必须同时告知：
+1. 配置文件位置
+2. 影响范围
+3. 生效方式
+4. 回滚策略
+5. 变更风险
+6. 是否需要灰度
+```
+
+---
+
+#### G9：业务规则约束矩阵
+
+```markdown
+# {project_name} 业务规则约束矩阵
+<!-- search-anchor: 业务规则, 约束矩阵, 操作约束, AI推理 -->
+## 操作前置条件矩阵
+| 操作 | 状态要求 | 硬件约束 | 计费约束 | 配额约束 | 其他约束 |
+
+## 约束决策树（mermaid graph TD）
+（覆盖主要操作的多层约束检查流程）
+
+## 特殊实例类型约束汇总
+| 实例/资源类型 | 限制操作 | 原因 |
+（✅允许 / ❌禁止 / ⚠️有条件）
+
+## AI 推理规则速查
+（mermaid 流程图：AI 判断"某操作能否执行"时的逐层检查顺序）
+```
+
+---
+
+### Step 3：生成图谱目录 README
+
+写入 `{output_dir}/README.md`：
+```markdown
+# {project_name} 图谱文档集 (Graph RAG)
+<!-- search-anchor: 图谱文档, Graph RAG, 关系索引 -->
+
+## 与主文档体系的关系
+（图谱文档不替代组件文档，而是提供关系视角的结构化索引）
+
+## 文档目录
+| 文件 | 大小 | 核心内容 |
+
+## 按问题类型查找
+| 问题类型 | 示例问题 | 查找文档 |
+| 依赖关系 | "谁依赖 X？" | G1 组件依赖关系矩阵 |
+| 调用链路 | "API X 经过哪些模块？" | G2 调用链路全景 |
+| 数据位置 | "数据存在哪里？" | G3 数据流与存储依赖图 |
+| 错误排查 | "错误码 XXX 是哪个模块的？" | G4 错误码组件映射表 |
+| 场景手册 | "配额检查的完整流程？" | G5 跨组件交互场景手册 |
+| 多跳推理 | "A 间接依赖谁？" | G6 知识图谱三元组 |
+| 风险评估 | "X 挂了影响多大？" | G7 架构风险与影响面 |
+| 配置修改 | "怎么修改 XX 配置？" | G8 核心配置参数索引 |
+| 操作约束 | "能不能做 XX？" | G9 业务规则约束矩阵 |
+
+## 检索路由规则建议
+（关键词 → 优先检索文档）
+
+## 维护说明
+（组件文档更新后需同步更新图谱文档的时机和范围）
+```
+
+### Step 4：返回摘要
+
+```
+Graph RAG 生成完成：
+生成文档: G1~G9 共 9 份 + README
+  - G1_组件依赖关系矩阵.md: {N}KB，{N}个组件，{N}条关系
+      置信度: EXTRACTED {N} / INFERRED {N} / AMBIGUOUS {N}
+  - G2_组件调用链路全景.md: {N}KB，{N}条调用链，状态机{N}个状态
+  - G3_数据流与存储依赖图.md: {N}KB
+  - G4_错误码组件映射表.md: {N}KB，{N}段错误码
+  - G5_跨组件交互场景手册.md: {N}KB，{N}个场景时序图
+  - G6_知识图谱三元组.md: {N}KB，{N}条三元组
+      置信度: EXTRACTED {N} / INFERRED {N} / AMBIGUOUS {N}
+  - G7_架构风险与影响面分析.md: {N}KB
+  - G8_核心配置参数索引.md: {N}KB，{N}个配置项
+  - G9_业务规则约束矩阵.md: {N}KB
+AMBIGUOUS 条目汇总（需人工确认）: {N} 处
+  - 示例: "Aurora→Compute 通信方式不确定（文档未明确）[A:0.2]"
+发现问题: {问题 或 "无"}
+
+⚠️ 主 Agent 请注意：Graph RAG 完成后，请立即执行 Phase K3 Step 3（跨文档一致性校验）。
+```
+
+## 输出
+
+```
+<output_dir>/README.md
+<output_dir>/G1_{project_name}组件依赖关系矩阵.md
+<output_dir>/G2_{project_name}组件调用链路全景.md
+<output_dir>/G3_{project_name}数据流与存储依赖图.md
+<output_dir>/G4_{project_name}错误码组件映射表.md
+<output_dir>/G5_{project_name}跨组件交互场景手册.md
+<output_dir>/G6_{project_name}知识图谱三元组.md
+<output_dir>/G7_{project_name}架构风险与影响面分析.md
+<output_dir>/G8_{project_name}核心配置参数索引.md
+<output_dir>/G9_{project_name}业务规则约束矩阵.md
+返回摘要字符串
+```
+
+## 约束
+
+- **关系抽取以组件文档为唯一来源**：不直接读原始代码，防止与 Phase K2 产出不一致
+- **置信度三态强制**：每条关系/三元组必须标注 `EXTRACTED`/`INFERRED`/`AMBIGUOUS`，不得省略
+- **禁止用 0.5 作置信度默认值**：每条关系独立评估分值；INFERRED 直接结构证据 0.8~0.9，命名推断 0.6~0.7，弱证据 0.4~0.5；AMBIGUOUS 用 0.1~0.3
+- **禁止凭空发明关系**：若组件文档无依据，宁可标 AMBIGUOUS 也不捏造 EXTRACTED
+- **每份图谱文档必须有 AI 快速理解要点表**
+- **每份图谱文档必须有 search-anchor**
+- **图谱文档不替代组件文档**：只提供关系视角的结构化索引
+- **状态机必须使用 mermaid stateDiagram-v2**
+- **约束决策树必须使用 mermaid graph TD**
+- **三元组必须遵循 (Subject, Predicate, Object, Confidence, Score) 格式**
+- **操作-状态约束必须是 ✅/❌/⚠️ 矩阵格式**

package/skills/team-wiki-codebase/references/agents/kb-doc-generator.md

@@ -0,0 +1,323 @@
+# 知识库文档生成 Agent
+
+## 职责
+
+为指定批次的组件/文档类型生成知识库文档，严格遵循九大文档类型规范，确保代码可回溯、AI 快速理解表完整、双向链接织网。
+
+**此 Agent 在 Phase K2 中被主 Agent 逐批启动，支持并行子 Agent 分发模式。**
+
+## 输入包
+
+```
+component_list:   本批次待生成的组件名或文档类型列表
+                  例如: ["Aurora", "Frame", "CCDB", "Dispatcher"] 或 ["Type-1", "Type-2", "Type-3"]
+architecture_map: _review/k1-architecture-map.md 完整内容
+repos:            仓库列表（[{name, path, language}]），替代旧的 project_root
+service_map:      服务名→仓库映射表（用于跨仓库追踪调用链）
+output_dir:       知识库输出根目录
+project_name:     项目名称（用于文档命名，如 "CVM"）
+product_docs_dir: 产品文档目录（可为空，空则跳过产品约束提取）
+methodology_dir:  references/methodology/ 目录路径
+completed_docs:   已完成的文档列表（断点恢复时跳过）
+parallel_mode:    true | false（默认 true；Type-4 组件文档并行，Type-1~3/5~8 串行）
+```
+
+## 执行步骤
+
+### Step 0：加载方法论
+
+读取 `{methodology_dir}/phase2-document-types.md`，加载对应文档类型的模板和生成规则。
+
+### Step 1：断点检查
+
+检查 `completed_docs` 列表，从 `component_list` 中移除已完成项，得到 `pending_list`。
+
+若 `pending_list` 为空，直接返回"全部已完成"摘要，不做任何操作。
+
+### Step 2：分发策略决策
+
+```
+IF component_list 全为 Type-4 组件文档 AND parallel_mode = true:
+  → 并行模式（Step 2A）
+ELSE（Type-1/2/3/5/6/7/8 或 parallel_mode = false）:
+  → 串行模式（Step 2B）
+```
+
+### Step 2A：并行模式（Type-4 组件文档）
+
+**MANDATORY：必须使用 Agent tool，禁止一个个顺序处理。**
+
+**Step 2A-1：分块**
+
+将 `pending_list` 分成若干块，每块 **3~5 个组件**（组件文档较大，不超过 5 个避免上下文溢出）。
+- 优先把同一架构层的组件放同一块（减少跨层代码读取竞争）
+- 已完成的跳过（断点恢复）
+
+**Step 2A-2：同一条消息并发启动所有子 Agent**
+
+**在同一次回复中发出所有 Agent tool 调用**。这是并行的唯一方式——分开多次调用则退化为串行。
+
+示例（3块并发）：
+```
+[Agent tool call 1: chunk ["Aurora", "Frame"], subagent_type="general-purpose"]
+[Agent tool call 2: chunk ["CCDB", "VSResource"], subagent_type="general-purpose"]
+[Agent tool call 3: chunk ["Dispatcher", "Compute"], subagent_type="general-purpose"]
+```
+
+每个子 Agent 接收以下 prompt（替换 CHUNK_COMPONENTS、CHUNK_NUM、TOTAL_CHUNKS）：
+
+```
+你是 team-wiki-codebase 的组件文档生成子 Agent。
+为以下组件生成知识库文档（chunk CHUNK_NUM / TOTAL_CHUNKS）：
+CHUNK_COMPONENTS
+
+架构参考（精简版，仅含本 chunk 相关组件及其直接上下游）：
+RELEVANT_COMPONENTS_TABLE
+（格式：| 组件名 | 架构层级 | 所属仓库 | 语言 | 上游 | 下游 | 入口文件 |）
+
+服务映射表（用于跨仓库追踪）：
+SERVICE_MAP_RELEVANT_ENTRIES
+
+项目信息：
+- repos: REPO_LIST（仅列路径，不列详情）
+- output_dir: OUTPUT_DIR
+- project_name: PROJECT_NAME
+- product_docs_dir: PRODUCT_DOCS_DIR（空则跳过产品约束）
+
+方法论路径: METHODOLOGY_DIR/phase2-document-types.md
+
+对每个组件执行：
+1. 使用 Glob→Grep→Read 三步法扫描代码（参见 kb-doc-generator.md §Step 2：代码结构扫描规范）
+2. 提取：核心职责/架构层级/上下游/代码入口/核心机制/数据流向/技术栈/数据模型/配置项
+3. 生成符合 Type-4 模板的文档，Write 到 OUTPUT_DIR/XX_组件名设计说明.md
+4. 自校验（见下方 Checklist）
+5. 将完成的组件名写入 OUTPUT_DIR/../_review/_chunk_done_CHUNK_NUM.txt（每行一个）
+
+自校验 Checklist（每份文档生成后）：
+- [ ] AI 快速理解表 10 维度全部填写且具体（非泛泛描述）？
+- [ ] "代码入口"精确到函数名（不是仅文件名）？
+- [ ] search-anchor 有 5~15 个关键词？
+- [ ] 包含指向主架构文档的双向链接？
+- [ ] 无法回溯的内容已标注 [UNVERIFIED]？
+- [ ] 无空占位章节？
+
+[UNVERIFIED] 超过 20% → 文档顶部加 ⚠️ 低可信度警告。
+
+无法生成的组件写入 OUTPUT_DIR/../_review/_chunk_failed_CHUNK_NUM.txt 并注明原因。
+```
+
+**Step 2A-3：等待并收集结果**
+
+等待所有子 Agent 完成后：
+- 检查 `_chunk_done_N.txt` 文件确认完成情况
+- 若某块 `_chunk_done_N.txt` 不存在，打印警告：`chunk N 可能未完成，检查子 Agent 是否以 general-purpose 类型运行`
+- 若超过半数块失败，停止并告知用户重新运行
+- 将所有已完成组件合并到 `progress.json` 的 `kb_progress.components_done`
+- 清理临时文件：`rm -f _review/_chunk_done_*.txt _review/_chunk_failed_*.txt`
+
+### Step 2B：串行模式（Type-1~3/5~8）
+
+对 `pending_list` 中每个文档类型**顺序执行**（这些文档类型相互依赖，必须串行）：
+
+#### 2B-1：代码结构扫描规范
+
+使用 `Glob → Grep → Read` 三步法（**按组件所属仓库的语言自适应**）：
+
+```
+1. Glob：找到组件对应仓库的入口文件（按语言选择模式）
+   Go:         main.go / cmd/*/main.go
+   Python:     main.py / app.py / manage.py / wsgi.py
+   Java:       *Application.java / *Bootstrap.java / src/main/java/**/Main*.java
+   TypeScript: app.ts / index.ts / main.ts / server.ts
+   Rust:       main.rs / src/main.rs
+   
+2. Grep：定位核心 Handler/Router（按语言+框架选择模式）
+   Go:         grep -rn 'func.*Handler\|\.GET\|\.POST\|router\.\|@handler' <dir>
+   Python:     grep -rn '@app\.\|@router\.\|def.*view\|APIRouter\|include_router' <dir>
+   Java:       grep -rn '@RestController\|@Controller\|@Service\|@GetMapping\|@PostMapping\|@RequestMapping' <dir>
+   TypeScript: grep -rn 'app\.get\|app\.post\|router\.\|@Get\|@Post\|@Controller' <dir>
+   Rust:       grep -rn '\.route\|\.get\|\.post\|#\[get\|#\[post\|async fn' <dir>
+
+   ⚠️ 排除测试文件：--exclude='*_test.*' --exclude='test_*' --exclude='*_mock.*'
+   
+3. Read：读取核心文件（按 architecture_map 中的目录价值分级）
+   - ⭐⭐⭐ 必读：业务逻辑层、核心配置文件、DDL
+   - ⭐⭐ 参考：服务上下文初始化、配置文件
+   - ⭐ 可跳过：纯绑定层（通常只是参数透传）
+   - ✗ 禁止：自动生成文件（*.pb.go, *_gen.go, *_generated.*, node_modules/, target/, build/）
+```
+
+提取信息（**全部必须有代码文件:行号引用，不得推断**）：
+- 核心职责（一句话，≤30字）
+- 架构层级和上下游组件（通信方式：RPC/MQ/DB）
+- 代码入口（文件名 → 核心函数名）
+- 核心机制（最重要的1~2个技术机制）
+- 数据流向（从哪来 → 经过什么 → 到哪去）
+- 技术栈（语言 + 框架 + 中间件）
+- 数据模型（涉及的表名 + DDL 关键字段）
+- 核心流程（时序图所需的步骤）
+- 配置项（配置键 + 默认值 + 影响范围）
+- 定时任务（如有）
+- 监控指标（如有）
+
+无法从代码中找到的内容标注 `[UNVERIFIED]`，不得推断。
+
+#### 2B-2：产品文档提取（Type-5/6/7，或有 product_docs_dir 时）
+
+若 `product_docs_dir` 非空：
+```
+扫描维度（来自 phase2-document-types.md §Type-5 桥梁文档生成方法）：
+├── 数量限制（批量上限、配额、最大值）
+├── 类型约束（枚举值、互斥关系）
+├── 状态前置条件
+├── 计费规则
+├── 安全约束
+└── 兼容性约束
+```
+
+将每个产品约束追踪到代码校验位置（`if len() > N` 的具体文件:行号）。
+
+#### 2B-3：文档生成
+
+按照 `phase2-document-types.md` 中对应类型的模板生成文档。
+
+**Type-4 组件文档必须包含（按顺序）**：
+
+```markdown
+# {组件名} 内部设计说明
+<!-- search-anchor: {中文名}, {英文名}, {缩写}, {同义词}, {常见搜索词} -->
+> 项目: {project_name} | 代码仓库: {仓库URL} | 架构层级: {层级}
+> 在整体架构中的位置: [📘 {project_name} 技术架构 - 4.X {组件名}](./{project_name} 技术架构.md#4x-组件名)
+
+## 🤖 AI 快速理解要点
+| 维度 | 关键信息 |
+|------|---------|
+| **核心职责** | {≤30字，具体} |
+| **架构层级** | {层级名} → {角色} |
+| **上游组件** | {组件A(RPC)}, {组件B(MQ)} |
+| **下游组件** | {组件C(RPC)}, {组件D(DB)} |
+| **代码入口** | `{文件名}` → `{核心函数名}()` |
+| **核心机制** | {机制1}；{机制2} |
+| **互斥控制** | {并发控制方式，如"分布式锁 key: xx"} |
+| **数据流向** | {来源} → {处理} → {去向} |
+| **技术栈** | {语言} + {框架} + {中间件} |
+| **定时任务** | {N个定时任务，或"无"} |
+
+## 📋 项目概述
+（核心职责编号列表 + ASCII 架构定位图）
+
+## 🏗️ 架构设计
+（ASCII 架构图 + 核心子模块说明 + 核心函数签名）
+
+## 📊 数据模型
+（SQL DDL 含注释 + 数据流向图）
+
+## 🔌 接口设计
+（对外/对内接口表 + 错误码定义）
+
+## ⚙️ 核心流程
+（mermaid 时序图 + 步骤说明 + 异常处理）
+
+## 🔧 配置说明
+（配置项 / 默认值 / 说明 / 影响范围）
+
+## 📈 监控与告警
+
+## 🐛 常见问题与排障
+
+## 📝 文档更新记录
+### v1.0 ({日期})
+- ✅ **新增**: 初始版本
+> 代码基准：{commit_sha} ({tag})
+```
+
+**所有文档 Write 到 `output_dir` 下，禁止先在对话中打印完整内容再写文件。**
+
+### Step 3：自校验（准确性验证 + 接口对账）
+
+每份文档生成后执行，**不得跳过**：
+
+**结构完整性**：
+- [ ] AI 快速理解表 10 个维度全部填写，且每个维度都是具体信息（不是"见下文"）？
+- [ ] "代码入口"精确到函数名（`文件名:行号 → 函数名()`）？
+- [ ] search-anchor 有 5~15 个关键词，包含中英文名和同义词？
+- [ ] 包含指向主架构文档的双向链接？
+- [ ] 无空占位章节（没有内容的章节直接删除）？
+
+**接口对账**（仅对 architecture_map 中接口校验类型 ≠ NONE 的组件执行）：
+
+从 `_review/interface-inventory.json` 读取该组件的扫描基准数 `scanned`，统计文档中实际记录的接口数 `documented`：
+
+```
+HTTP 类型：  统计文档 ## 接口设计 节中列出的路由数
+MQ 类型：    统计文档中明确记录的 Topic/Queue/Exchange 数
+RPC 类型：   统计文档中列出的 RPC Method 数
+```
+
+计算差异：`gap = scanned - documented`
+
+处理规则：
+- `gap = 0`        → ✅ 接口覆盖完整
+- `0 < gap ≤ 20%`  → ⚠️ 少量缺口，在文档末尾加 `<!-- INTERFACE_GAP: 疑似遗漏 N 个接口 -->`
+- `gap > 20%`      → ❌ 标记 `[INTERFACE_GAP]`，在摘要中注明，建议补充后重跑
+
+更新 `progress.json` 中该组件的 `interface_coverage.documented` 字段。
+
+**准确性统计**（每份文档单独统计，返回给主 Agent 汇总）：
+```
+统计方法：
+  total_claims = 业务规则条数 + 核心流程步骤数 + 接口描述条数 + 配置项条数
+  verified     = 其中有 file:line 引用的条数
+  unverified   = 标注了 [UNVERIFIED] 的条数
+  ratio        = unverified / total_claims
+```
+
+处理规则：
+- `ratio > 20%` → 文档顶部加 `⚠️ 低可信度警告：{unverified}/{total_claims} 项无法回溯到代码`
+- `ratio > 40%` → 摘要中标记 **[HIGH_UNVERIFIED]**，建议人工重点确认
+
+### Step 4：返回摘要
+
+返回给主 Agent（主 Agent 将数据累加到 progress.json 的 `accuracy_stats` 和 `interface_coverage`）：
+
+```
+批次完成摘要:
+读取文件: {N} 个（估计 token 消耗: ~{N}k）
+生成文档: {N} 份
+
+准确性统计:
+  总声明数: {N} | 已验证: {N} | [UNVERIFIED]: {N} ({X}%)
+
+接口对账（仅有接口的组件）:
+  ComponentA [HTTP]: 文档 {M} / 基准 {N} = {X}%  ✅/⚠️/❌
+  ComponentB [MQ]:   文档 {M} / 基准 {N} = {X}%  ✅/⚠️/❌
+
+逐文档明细:
+  - {组件名}设计说明.md: {N}KB，声明{N}条，[UNVERIFIED]{N}条({X}%)  [HIGH_UNVERIFIED/INTERFACE_GAP 如适用]
+
+跳过（已完成）: {N} 份
+发现问题: {问题描述 或 "无"}
+```
+
+## 输出
+
+```
+<output_dir>/XX_{组件名}设计说明.md  ← Type-4 组件文档
+<output_dir>/{project_name} 技术架构.md  ← Type-1（如本批次包含）
+<output_dir>/{project_name} 业务架构.md  ← Type-2
+<output_dir>/{project_name} 部署架构.md  ← Type-3
+<output_dir>/XX_{project_name}核心API产品代码映射.md  ← Type-5
+<output_dir>/XX_{project_name}产品规则速查表.md  ← Type-6
+<output_dir>/XX_{project_name}业务开发规范SOP.md  ← Type-7
+<output_dir>/{知识增强文档}.md  ← Type-8
+返回摘要字符串
+```
+
+## 约束
+
+- **代码为真**：所有描述必须有代码文件引用，不可验证内容必须标注 `[UNVERIFIED]`
+- **模板强制**：生成每类文件前必须先读取对应章节的模板
+- **严禁空文档**：没有实质内容则不创建文件
+- **严禁冗余输出**：直接 Write 文件，不在对话中打印完整内容
+- **命名规范**：组件文档用 `XX_{组件名}设计说明.md`，XX 按依赖链顺序分配（底层组件编号小）
+- **API 未提供时**：Type-5/6 可跳过产品约束映射，将约束值标注为 `[PRODUCT_DOC_MISSING]`