teamai-cli 0.16.9 → 0.17.0

package/skills/team-wiki-codebase/references/methodology/phase0-collection.md

@@ -0,0 +1,54 @@
+# Phase 0: 源材料采集与预处理
+
+## 仓库发现与分类
+
+从入口仓库出发，递归发现所有相关仓库：
+
+1. **依赖分析**: 解析项目依赖文件（如 `requirements.txt`, `package.json`, `pom.xml`, `Cargo.toml`, `go.mod` 等，按检测到的语言选择）
+2. **配置引用**: 解析流程编排配置中引用的模块名 → 仓库映射
+3. **RPC 服务发现**: 从服务注册配置提取服务名 → 仓库映射
+4. **按架构层级分类**: API接入层 / 流程引擎层 / 服务执行层 / 资源调度层 / 数据适配层 / 基础执行层
+5. **标记核心度**: 根据代码行数、被依赖数、Handler 数量计算优先级
+
+## 关键文件提取清单
+
+| 文件类型 | 匹配模式 | 提取目的 |
+|---------|---------|---------|
+| **入口文件** | `main.py`, `main.go`, `cmd/*/main.go`, `app.ts` | 服务启动方式和初始化流程 |
+| **路由/Handler** | `handler.*`, `router.*`, `controller.*` | API 接口和消息处理入口 |
+| **配置文件** | `*config*.*`, `conf/`, `*.yaml`, `*.toml` | 流程编排、参数配置 |
+| **Proto/IDL** | `*.proto`, `*.thrift`, `*schema*` | RPC 接口契约和数据结构 |
+| **数据库操作** | `*db*.*`, `*dao*.*`, `*model*.*`, `*repository*.*` | 数据模型和表结构 |
+| **常量/错误码** | `*const*`, `*error*`, `*code*`, `*enum*` | 错误码体系和业务常量 |
+| **测试文件** | `*_test.*`, `test_*.*` | 预期行为和边界条件 |
+
+## 构建代码知识图谱
+
+在正式生成文档前，构建代码知识图谱作为中间表示：
+
+**节点类型**: `[Service]` / `[Handler]` / `[Config]` / `[Table]` / `[Queue]` / `[API]` / `[ErrorCode]`
+
+**边类型**: `[CALLS]`(同步RPC/HTTP) / `[PUBLISHES]`(异步MQ) / `[CONSUMES]`(MQ消费) / `[READS]`(DB读) / `[WRITES]`(DB写) / `[CONFIGURES]`(配置驱动) / `[MAPS_TO]`(产品→代码)
+
+**构建方法**（按可用性排序）:
+1. **`team-wiki compile code --extract ast,heuristic --write`** — Tree-sitter 结构边（**TS/JS/Python/Go** 等）+ 多语言 heuristic 事实页
+2. Grep + Read（Agent K1/K2）— 补充动态路由、配置驱动调用
+3. 解析编排配置 → 模块→命令映射
+4. 解析 Proto/IDL/DDL → 数据结构和表关系（结构化文件，可精确解析）
+5. MQ 拓扑推断 → Exchange/Topic/Queue/Routing Key
+6. API 映射 → 外部 API 名称 → 内部 Handler 入口
+
+> `code-ast` 对相对 import 可产出 `DEPENDS_ON` 边；包级/动态调用仍可能遗漏，标 `[UNVERIFIED]` 或 `AMBIGUOUS`。
+> 能力 ID 与边优先级见插件内 `GRAPH-CAPABILITIES.md`。
+
+## 输入源优先级
+
+| 优先级 | 输入源 | 具体内容 | 产出文档类型 |
+|--------|--------|---------|------------|
+| **P0 必须** | 代码仓库 | 目录结构、入口文件、配置、Proto | Type-1,4 |
+| **P0 必须** | 流程编排配置 | workflow_config / 状态机 | Type-1,4,5 |
+| **P0 必须** | 产品 API 文档 | 接口参数、错误码 | Type-5,6 |
+| **P1 重要** | 数据库 Schema | DDL、表结构 | Type-4 |
+| **P1 重要** | 产品使用文档 | 使用限制、FAQ | Type-6,8a |
+| **P2 增强** | Git 历史 | Commit/MR 记录 | Type-8b |
+| **P2 增强** | 故障记录 | 事故报告 | Type-8d |

package/skills/team-wiki-codebase/references/methodology/phase1-reverse-engineering.md

@@ -0,0 +1,89 @@
+# Phase 1: 架构逆向工程 — 从代码到架构认知
+
+## 1. 自底向上分层法
+
+```
+Step 1: 识别"叶子节点" — 直接操作基础设施
+  ├── 数据库操作 (MySQL/PostgreSQL/Redis/MongoDB)
+  ├── 消息队列操作 (RabbitMQ/Kafka/RocketMQ)
+  ├── 外部系统调用 (第三方 API / 底层驱动)
+  └── 文件/对象存储操作 (S3/OSS/COS)
+
+Step 2: 识别"中间节点" — 编排和路由
+  ├── 消息路由框架 (消费者路由分发)
+  ├── 任务调度器 (定时任务/延迟任务)
+  ├── 流程编排引擎 (Workflow/Saga/状态机)
+  └── 资源调度器 (负载均衡/资源分配)
+
+Step 3: 识别"根节点" — 外部入口
+  ├── API 网关 / HTTP Handler / gRPC Server
+  ├── 定时任务入口 (Cron/Scheduler)
+  └── 事件监听入口 (Webhook/EventBus)
+
+Step 4: 按调用方向分层
+  外部入口 → 流程编排 → 服务执行 → 资源调度 → 数据操作 → 基础设施
+```
+
+### 分层判定规则
+
+| 判定特征 | 所属层级 | 典型代码模式 |
+|---------|---------|-------------|
+| HTTP/gRPC Server 启动 | API 接入层 | `http.ListenAndServe()`, `grpc.NewServer()` |
+| 参数校验 + 鉴权 + 限流 | API 接入层 | `validate()`, `auth()`, `rateLimit()` |
+| 流程步骤配置和状态机 | 流程引擎层 | `workflow_config`, `state_machine` |
+| MQ 消费 + Handler 路由 | 服务执行层 | `channel.consume()`, `handler.dispatch()` |
+| 调度算法 (Filter/Score) | 资源调度层 | `filter()`, `score()`, `schedule()` |
+| DB CRUD + 缓存操作 | 数据适配层 | `db.query()`, `redis.get()` |
+| 底层系统调用/驱动 | 基础执行层 | `exec()`, `syscall.*`, `driver.*` |
+
+## 2. 三层穿透追踪法（核心方法论）
+
+对任何用户可见 API 操作，完成三层穿透追踪：
+
+```
+Layer 1: API 入口层
+  ├── 定位 Handler 函数
+  ├── 提取参数校验逻辑
+  ├── 识别硬编码默认值和白名单
+  └── 确定下游调用方式 (同步RPC / 异步MQ)
+
+Layer 2: 流程编排层
+  ├── 查找流程配置 (workflow_config / saga_config)
+  ├── 解析步骤序列 (步骤名/执行模块/回滚模块/超时/重试)
+  ├── 标注每步的执行模块和回滚模块
+  └── 确定步骤间的数据传递方式
+
+Layer 3: 服务执行层
+  ├── 追踪每个步骤的具体 Handler 实现
+  ├── 识别数据库操作和状态变更
+  ├── 标注外部系统调用
+  └── 确定最终执行结果的回调路径
+
+输出: 完整调用链时序图 + 状态流转图 + 数据流向图
+```
+
+### 调用链文档化标准格式
+
+```
+[API名称](代码入口: {仓库}/{路径}/{文件})
+  → 参数校验 + 鉴权限流
+  → [前置检查]: {检查内容}
+  → RPC/MQ → [编排层] ({配置文件}: {操作名})
+    → [服务层] ({配置文件}: {flow_name})
+      → [{步骤1模块}] {步骤1命令} ({具体说明})
+      → [{步骤2模块}] {步骤2命令} ({具体说明})
+      → ...
+      → 回调 [编排层]
+```
+
+## 3. 组件关系矩阵
+
+构建 N×N 关系矩阵，标注通信方式：
+
+| 调用方 ↓ / 被调方 → | 组件A | 组件B | 组件C |
+|---------------------|-------|-------|-------|
+| **组件A** | — | RPC | MQ |
+| **组件B** | — | — | DB |
+| **组件C** | RPC | MQ | — |
+
+标注: `RPC`(同步) / `MQ`(异步) / `DB`(共享数据库) / `—`(无直接通信)

package/skills/team-wiki-codebase/references/methodology/phase2-document-types.md

@@ -0,0 +1,341 @@
+# Phase 2: 九大文档类型生成规范与模板
+
+## Type-1: 技术架构总览
+
+**规模**: ~200KB | **数量**: 1 份
+
+### 必备章节
+
+```
+读者导航指南 (按角色推荐阅读路径)
+知识库检索路由指引 (AI 专用，4条分流规则+4级优先级)
+1. 架构概述 (30秒快速理解表、整体架构图ASCII、组件关系矩阵)
+2. 三维架构视图 (逻辑/数据/部署)
+3. 核心链路 ⭐ (每条核心API的完整时序图+调用链)
+4. 核心组件详解 (每组件概述+表格)
+5. 配置管理与服务发现
+6. 数据模型与存储架构 ⭐
+7. 高可用与技术架构
+8. 架构演进与设计决策
+9. AI 研发知识库规范 ⭐ (元数据QA/全局状态机/MQ拓扑/调度引擎/跨层追踪)
+附录: 代码仓库/术语表/代码入口索引/错误码
+```
+
+### 生成规则
+- T1-R01: 必须包含读者导航指南
+- T1-R02: 必须包含 AI 检索路由规则
+- T1-R03: 核心链路必须有时序图
+- T1-R04: 组件表必须包含代码仓库列
+- T1-R05: 术语表必须包含内外部映射
+- T1-R06: 必须有 AI 专用第 9 章
+- T1-R07: 架构图使用 ASCII Art
+
+---
+
+## Type-2: 业务架构文档
+
+**规模**: ~70KB | **数量**: 1 份
+
+```
+1. 产品能力矩阵 (能力域/子能力/对应API/计费影响)
+2. 计费模型详解 (模式对比/状态机/退费续费规则)
+3. 核心实体生命周期 (完整状态机/各状态允许操作/互斥规则)
+4. 核心业务流程 (用户视角时序图+前置条件+异常处理)
+5. 产品规格体系 (命名规则/规格与底层资源映射)
+```
+
+---
+
+## Type-3: 部署架构文档
+
+**规模**: ~40KB | **数量**: 1 份
+
+```
+1. 分层部署架构图
+2. 服务部署矩阵 (服务名/部署方式/实例数/资源配置/依赖)
+3. 环境配置 (生产/测试/差异对照)
+4. 部署流程与变更管理
+```
+
+---
+
+## Type-4: 组件设计文档（核心产出）
+
+**规模**: 20~100KB/份 | **数量**: N 份（每组件一份）
+
+### 标准模板
+
+```
+# {组件名} 内部设计说明
+<!-- search-anchor: 组件名, 别名, 核心关键词 -->
+> 项目名称 / 版本 / 代码仓库 / 代码规模
+> 在整体架构中的位置: [📘 链接到主架构文档]
+
+## 🤖 AI 快速理解要点
+（10 维度结构化摘要，详细定义见 [phase3-ai-enhancement.md §1](phase3-ai-enhancement.md)）
+
+## 📋 项目概述 (核心职责+在架构中的位置)
+## 🏗️ 架构设计 (ASCII架构图+核心子模块，函数签名)
+## 📊 数据模型 (SQL DDL带注释+数据流向图)
+## 🔌 接口设计 (对外接口表+对内接口+错误码)
+## ⚙️ 核心流程 (时序图+步骤说明+异常处理)
+## 🔧 配置说明 (配置项/默认值/说明/影响范围)
+## 📈 监控与告警
+## 🐛 常见问题与排障
+```
+
+### 生成规则
+- T4-R01: 必须有 AI 快速理解表
+- T4-R02: 必须有双向链接到主架构文档
+- T4-R03: 核心函数必须列出签名
+- T4-R04: SQL DDL 必须包含注释
+- T4-R05: 配置项必须标注影响范围
+- T4-R06: 架构图使用 ASCII Art
+- T4-R07: 代码入口必须精确到函数名
+
+### 从代码生成的步骤
+
+> 详细执行规范见 `references/agents/kb-doc-generator.md`，此处仅列概要：
+> 1. 代码结构扫描（Glob → Grep → Read 三步法，按语言自适应）
+> 2. 信息提取（10 维度：核心职责/架构层级/上下游/代码入口/核心机制/数据流向/技术栈/数据模型/配置项/定时任务）
+> 3. 文档组装（按上述模板章节顺序）
+> 4. 自校验（准确性统计 + 接口对账）
+
+---
+
+## Type-5: 产品-代码映射（桥梁文档）
+
+### 每个核心 API 一节
+
+```
+### N.1 用户意图 (一句话)
+### N.2 产品约束 (约束项/约束值/影响组件/校验位置)
+### N.3 用户可见状态流转 (ASCII图+内部状态映射)
+### N.4 内部调用链路 (标准格式精确到代码文件)
+### N.5 写代码时必须考虑的 (硬性约束编号列表)
+### N.6 错误码与内部异常映射 (外部码/内部组件/含义)
+```
+
+### 生成规则
+- T5-R01: 约束表必须标注"影响的组件"和"校验位置"
+- T5-R02: 调用链必须精确到代码文件路径
+- T5-R03: 状态流转必须标注内部状态码映射
+- T5-R04: "写代码时必须考虑的"是强制章节
+- T5-R05: 错误码映射必须包含内部组件归属
+
+### 桥梁文档生成方法（3 Step）
+
+**Step 1: 提取产品约束** — 从产品文档中提取所有影响代码实现的约束：
+
+```
+扫描维度:
+├── 数量限制 (批量上限、配额、最大值)
+├── 类型约束 (枚举值、互斥关系)
+├── 状态前置条件 (操作前资源必须处于什么状态)
+├── 计费规则 (不同计费模式的差异处理)
+├── 安全约束 (鉴权、加密、脱敏)
+└── 兼容性约束 (类型兼容、版本兼容、地域限制)
+```
+
+**Step 2: 映射到代码位置** — 对每个产品约束，追踪到代码中的具体校验位置：
+
+```
+产品约束: "{API名} 批量上限 N"
+  ↓ 追踪
+代码位置: {API网关组件} → {文件路径} → validate_params()
+  ↓ 确认
+校验方式: if len(resource_ids) > N: raise InvalidParameterValue
+```
+
+**Step 3: 构建映射表** — 将上述信息组装为标准的产品-代码映射表（见 Type-5 模板）。
+
+**桥梁文档质量标准**:
+
+| 质量维度 | 标准 | 检查方法 |
+|---------|------|---------|
+| **完整性** | 所有核心 API 都有映射 | 对照 API 列表逐一检查 |
+| **精确性** | 代码路径精确到文件和函数 | 实际打开代码验证 |
+| **一致性** | 约束值与产品文档一致 | 交叉比对产品文档 |
+| **时效性** | 与最新代码版本同步 | 定期 diff 检查 |
+
+---
+
+## Type-6: 产品规则速查表
+
+```
+## N. {规则类别}
+| 规则 | 约束值 | 影响的组件 | 校验位置 | 来源文档 |
+
+## 状态与操作互斥规则
+| 当前状态 | 允许的操作 | 禁止的操作 |
+```
+
+- T6-R01: 每条规则必须标注"影响的组件"
+- T6-R02: 约束值必须是精确数字
+- T6-R03: 必须有"来源文档"列
+- T6-R04: 状态互斥规则必须是完整矩阵
+
+---
+
+## Type-7: 业务开发规范 SOP
+
+```
+1. 为什么需要标准代码模板 (野生代码问题)
+2. 核心规约 (绝不向外暴露底层错误/Context一传到底/参数前置校验)
+3. 标准 Handler 代码模板 (可直接复制，标注"AI 编码铁律")
+4. 错误码映射对照表 (场景描述用AI思考逻辑/推荐错误码/Message)
+5. AI 评审 CheckList (可机器校验)
+```
+
+- T7-R01: 代码模板必须可直接复制运行
+- T7-R02: 每个关键注释标注"AI 编码铁律"
+- T7-R03: 错误码表用"AI的思考逻辑"作为场景描述
+
+---
+
+## Type-8: 知识增强文档
+
+### Type-8a: 产品知识文库
+标注 `type: bridge`，表格对比易混淆概念，含"代码传参示例"和"架构与业务影响"列。
+
+### Type-8b: 反模式与踩坑指南
+五段式：**触发场景→错误表现→根因分析→正确做法→关联组件**
+概览表标注编号/分类/严重程度(P0致命/P1严重/P2重要)/关联组件。
+
+### Type-8c: RPC 接口契约
+struct 定义含序列化 Tag + 必填/选填标注 + AI 编码契约要求。
+
+### Type-8d: 排障案例记录 (Memorix)
+结构：问题现象→排查过程(Step N)→根因定位→修复方案→经验总结→关联文档。
+
+---
+
+## Type-9: 图谱文档集（Graph RAG）
+
+**规模**: 10~30KB/份 | **数量**: 5~10 份 | **目录**: `graph/`
+
+> 将散落在 N 份组件文档中的**跨组件关系信息**抽取为结构化索引，解决 RAG 检索在关系查询场景下的"信息分散"问题。
+
+### 图谱文档类型清单
+
+| 编号 | 文档名 | 核心内容 | 解决的检索痛点 |
+|------|--------|---------|--------------|
+| G1 | 组件依赖关系矩阵 | N×N 通信矩阵 + 正向/反向依赖索引 + 外部服务依赖 | "谁依赖 X？" 需遍历所有文档 |
+| G2 | 组件调用链路全景 | 核心 API 端到端链路 + 读写分离机制 + **完整状态机流转图** + 操作-状态约束矩阵 | "API 经过哪些模块？" 信息分散 |
+| G3 | 数据流与存储依赖图 | 存储依赖矩阵 + MQ 队列拓扑 + 缓存策略 | "数据存在哪里？" |
+| G4 | 错误码组件映射表 | 错误码段分配 + 外部→内部映射 | "错误码是哪个模块的？" |
+| G5 | 跨组件交互场景手册 | ≥10 个场景的 mermaid 时序图 + 异常处理 | "配额检查怎么做的？" |
+| G6 | 知识图谱三元组 | (S, P, O) 三元组 + 多跳依赖路径索引 | "A 间接依赖谁？" |
+| G7 | 架构风险与影响面分析 | 爆炸半径 + 聚类分析 + 关键路径/瓶颈 | "X 挂了影响多大？" |
+| G8 | **核心配置参数索引** | 分层配置项→行为影响映射 + 变更影响面速查 | "怎么修改 XX 配置？" |
+| G9 | **业务规则约束矩阵** | 操作前置条件 + 硬件/迁移/计费约束 + AI 推理决策树 | "能不能做 XX？" |
+
+### 图谱文档生成规则
+
+- T9-R01: 每份图谱文档必须有 `🤖 AI 快速理解要点` 表
+- T9-R02: 每份图谱文档必须有 `<!-- search-anchor: ... -->` 锚点
+- T9-R03: 图谱目录必须有 `README.md` 索引，含"按问题类型查找"表和"检索路由规则建议"
+- T9-R04: 状态机必须使用 mermaid `stateDiagram-v2` 格式
+- T9-R05: 约束决策树必须使用 mermaid `graph TD` 格式
+- T9-R06: 操作-状态约束必须是 ✅/❌ 矩阵格式
+- T9-R07: 配置参数必须标注"影响行为"、"变更风险"(🟢低/🟡中/🔴高)、"生效方式"(热生效/需重启)
+- T9-R08: 业务规则约束必须包含 AI 推理检查流程（mermaid 流程图）
+- T9-R09: 三元组必须遵循 (Subject, Predicate, Object) 标准格式
+- T9-R10: 图谱文档**不替代**组件文档，而是提供**关系视角的结构化索引**
+
+### 图谱文档生成方法
+
+**Step 1: 关系抽取** — 从 N 份组件文档中提取跨组件关系：
+
+```
+扫描维度:
+├── 调用关系 (A calls B, 协议, 场景)
+├── 数据依赖 (A reads/writes B, 数据内容)
+├── 消息拓扑 (A publishes_to/consumes_from Queue)
+├── 状态流转 (操作 → 起始状态 → 中间状态 → 终态)
+├── 约束条件 (操作 → 前置条件 → 硬件/计费/配额约束)
+├── 配置映射 (配置项 → 影响行为 → 变更风险)
+└── 错误码归属 (错误码段 → 组件 → 排查方向)
+```
+
+**Step 2: 结构化建模** — 将抽取的关系转化为标准格式：
+
+```
+关系矩阵 → N×N 表格
+调用链路 → 端到端文本链路 + mermaid 时序图
+状态机 → mermaid stateDiagram-v2
+约束规则 → 决策树(mermaid graph TD) + 汇总表
+配置索引 → 分层表格(配置项/默认值/影响行为/变更风险/生效方式)
+三元组 → (Subject, Predicate, Object, Protocol, Scenario) 表格
+```
+
+**Step 3: 索引织网** — 建立图谱文档间的交叉引用和检索路由：
+
+```
+README.md:
+├── 文档目录表 (文件/大小/核心内容)
+├── 按问题类型查找表 (问题类型/示例/查找文档)
+└── 检索路由规则建议 (关键词→优先检索文档)
+```
+
+### 关键模板
+
+#### 状态机流转图模板
+
+```markdown
+## 实例状态机完整流转图
+
+### 核心状态流转图
+​```mermaid
+stateDiagram-v2
+    [*] --> PENDING: CreateAction
+    PENDING --> RUNNING: 创建成功 (flag: 2→1)
+    RUNNING --> STOPPING: StopAction (flag: 1→8)
+    STOPPING --> STOPPED: 关机成功 (flag: 8→3)
+    ...
+​```
+
+### 操作-状态约束速查矩阵
+| 操作 \ 当前状态 | RUNNING | STOPPED | PENDING | ... |
+|---------------|:-------:|:-------:|:-------:|:---:|
+| **Start** | ❌ | ✅ | ❌ | ... |
+| **Stop** | ✅ | ❌ | ❌ | ... |
+```
+
+#### 业务规则约束矩阵模板
+
+```markdown
+## 操作前置条件矩阵
+| 操作 | 状态要求 | 硬件约束 | 计费约束 | 配额约束 | 其他约束 |
+
+## 迁移约束决策树
+​```mermaid
+graph TD
+    A[迁移请求] --> B{硬件约束1?}
+    B -->|是| C["❌ 禁止"]
+    B -->|否| D{硬件约束2?}
+    ...
+​```
+
+## AI 推理规则速查
+​```mermaid
+graph TD
+    A["用户问：能否执行 XX？"] --> B["Step 1: 状态检查"]
+    B --> B1{"查操作-状态约束矩阵"}
+    B1 -->|❌| Z1["不能，状态不支持"]
+    B1 -->|✅| C["Step 2: 类型检查"]
+    ...
+​```
+```
+
+#### 配置参数索引模板
+
+```markdown
+## {组件层}配置参数
+| 配置项 | 默认值 | 影响行为 | 变更风险 | 生效方式 |
+|--------|--------|---------|---------|---------|
+| `config.key` | value | 描述 | 🟢低/🟡中/🔴高 | 热生效/需重启 |
+
+## 配置变更影响面速查
+| 变更类型 | 影响范围 | 生效方式 | 回滚策略 | 变更风险 |
+```

package/skills/team-wiki-codebase/references/methodology/phase3-ai-enhancement.md

@@ -0,0 +1,164 @@
+# Phase 3: AI-Native 增强 — 让知识库对 AI 可理解
+
+## 1. AI 快速理解表（每份组件文档必备）
+
+RAG 检索返回的 chunk 通常是文档片段。AI 快速理解表确保无论检索到文档哪个部分，AI 都能在表头获得组件全局上下文。
+
+```markdown
+## 🤖 AI 快速理解要点
+
+| 维度 | 关键信息 |
+|------|---------|
+| **核心职责** | {一句话，不超过 30 字} |
+| **架构层级** | {所属层级} → {在层级中的角色} |
+| **上游组件** | {组件名(通信方式)} |
+| **下游组件** | {组件名(通信方式)} |
+| **代码入口** | {入口文件} → {核心函数} |
+| **核心机制** | {最重要的 1-2 个技术机制} |
+| **互斥控制** | {并发控制方式} |
+| **数据流向** | {从哪来 → 经过什么 → 到哪去} |
+| **技术栈** | {语言 + 框架 + 中间件} |
+| **定时任务** | {N 个定时任务（简述核心任务）} |
+```
+
+规则：
+- 每个维度必须是**具体的**，不能泛泛描述
+- "代码入口"精确到 `文件名 → 函数名`
+- "上下游组件"必须标注通信方式 (RPC/MQ/DB)
+- 表格放在文档最前面（紧跟标题之后）
+
+## 2. 检索路由规则（主架构文档必备）
+
+防止 RAG 检索内外部文档"串台"：
+
+```markdown
+## 知识库检索路由指引（AI 专用）
+
+### 文档分类总览
+| 分类 | 目录位置 | 文档数量 | 内容性质 |
+| 【内部·桥梁】产品-代码映射 | ... | N 份 | 核心API意图→约束→链路 |
+| 【内部】组件设计文档 | ... | N 份 | 架构设计、代码入口 |
+| 【外部】产品 API 文档 | ... | N 份 | 官网 API 参考 |
+
+### 检索路由规则
+规则 1 — 内部架构优先: 涉及组件名/内部概念 → 仅检索内部文档
+规则 2 — 外部文档适用: 涉及 API 参数/产品限制 → 检索外部文档
+规则 3 — 混合查询: 同时涉及 → 优先内部，辅以外部
+规则 4 — 写代码前先查约束: 必须先检索桥梁文档
+
+### 文档优先级
+| 一级（核心） | 产品-代码映射 + 规则速查表 | 写代码前必查 |
+| 二级（架构） | 组件设计文档 + 主架构文档 | 理解内部实现 |
+| 三级（业务） | 业务架构 + 核心链路 | 理解业务流程 |
+| 四级（备查） | 外部 API 原始文档 | 仅在上述不能回答时 |
+```
+
+## 3. Search Anchor（语义检索锚点）
+
+每份文档标题下方添加：
+
+```html
+<!-- search-anchor: 关键词1, 关键词2, 同义词, 英文术语, 中文术语 -->
+```
+
+- 包含: 中文名、英文名、缩写、同义词、常见搜索词
+- 数量: 5~15 个
+- 示例: `<!-- search-anchor: RPC契约, Schema, 接口契约, Protobuf, IDL -->`
+
+## 4. 双向链接织网
+
+```markdown
+# 组件文档 → 主架构文档
+> 在整体架构中的位置: [📘 主架构文档 - 4.5 {组件名}](./主架构文档.md#45-组件名)
+
+# 主架构文档 → 组件文档
+详见 [{组件名}设计说明](./XX_{组件名}设计说明.md)
+
+# 桥梁文档 → 组件文档
+| [{组件名}](./XX_{组件名}设计说明.md) | 入参校验层 |
+```
+
+织网规则：
+1. 每份组件文档 ≥ 1 个链接指向主架构文档
+2. 主架构文档每个组件提及处有链接指向组件文档
+3. 桥梁文档中提到的每个组件有链接
+4. 反模式文档的"关联组件"有链接
+
+## 5. QA 对生成（AI 元数据层）
+
+在主架构文档 AI 专用章节预置高频 QA 对（10~20 个）：
+
+```markdown
+- **Q: 核心实体的状态机是如何定义的？**
+  A: 见 `3.7 实体完整状态机` 及 `9.2.1 全局状态一致性映射表`。
+
+- **Q: 流程步骤配置在哪里？异常如何补偿回滚？**
+  A: 采用 N 级编排。宏观流程在 {配置文件1}，细粒度步骤在 {配置文件2}。
+
+- **Q: 消息队列的拓扑和路由规则？**
+  A: 见 `9.3.1 MQ 路由拓扑`。核心 Exchange/Topic 包括 {列表}。
+
+- **Q: 资源互斥（加锁）规范？**
+  A: 见 `9.4.4 分布式锁与幂等规范`。使用 {锁方案}。
+```
+
+每个 A 必须包含具体的章节/文档引用。
+
+## 6. 图谱文档 AI 增强规范
+
+图谱文档是 AI-Native 知识库的**关系索引层**，专门解决 RAG 在"跨组件关系查询"场景下的检索失败问题。
+
+### 6.1 图谱文档 README 必备结构
+
+```markdown
+# 图谱文档集 (Graph RAG)
+## 与主文档体系的关系 (三层定位表)
+## 文档目录 (文件/大小/核心内容)
+## 按问题类型查找 (问题类型/示例/查找文档)
+## 检索路由规则建议 (关键词→优先检索文档)
+## 维护说明
+```
+
+### 6.2 图谱文档 AI 快速理解表
+
+每份图谱文档必须在标题后紧跟：
+
+```markdown
+## 🤖 AI 快速理解要点
+| 维度 | 关键信息 |
+|------|---------|
+| **文档定位** | {一句话定位} |
+| **核心价值** | {AI 用这份文档能做什么} |
+| **覆盖范围** | {覆盖了哪些实体/关系} |
+| **使用场景** | {典型问题示例} |
+| **与状态机的关系** | {如适用：状态机解决X，本文档解决Y} |
+```
+
+### 6.3 AI 推理规则嵌入
+
+对于约束类图谱文档，必须嵌入 AI 推理决策流程：
+
+```markdown
+## AI 推理规则速查
+> AI 判断"某操作能否执行"时，按以下优先级逐层检查：
+
+1. **状态检查** → 查操作-状态约束矩阵
+2. **类型检查** → 查特殊实例类型约束汇总
+3. **硬件检查** → 查硬件约束详表
+4. **计费检查** → 查计费约束详表
+5. **配额检查** → 查产品规则速查表
+6. **互斥检查** → 是否有进行中的操作
+```
+
+### 6.4 配置变更检查清单
+
+对于配置类图谱文档，AI 回答"怎么修改 XX 配置"时必须同时告知：
+
+```
+1. 配置文件位置 — 在哪个文件/仓库中
+2. 影响范围 — 全地域还是单地域/单机
+3. 生效方式 — 热生效还是需要重启
+4. 回滚策略 — 如何快速回滚
+5. 变更风险 — 🟢低 / 🟡中 / 🔴高
+6. 灰度建议 — 是否需要灰度发布
+```