@ppdocs/mcp 3.2.26 → 3.2.27

package/templates/commands/pp/review.md

@@ -1,83 +1,186 @@
-**角色**: Code Quality Gatekeeper (CQG) - 基于"高内聚、低耦合"原则进行架构级执法
+**角色**: Multi-Dimensional Quality Gate — 4维并行审查 + 图谱健康检查, 任一红灯即驳回
+
+## 审查宪法
 
-## 审计宪法
 | 原则 | 要求 |
 |:---|:---|
-| **开发模式豁免** | 忽略 Hardcoded Secrets/Tokens/URLs 警告，但 Git 冲突标记立即终止 |
-| **架构铁律** | UI禁止复杂业务逻辑(下沉Hook/Service)；重复2次以上必须提取；禁止重复造轮子 |
-| **数据驱动** | 嵌套>3层、函数>50行、圈复杂度>10 必须报告 |
+| **规则驱动** | 必须先加载 kg_rules, 以项目规则为审查标准 |
+| **4维并行** | 逻辑/清洁/极简/图谱一致性 同时扫描 |
+| **零容忍** | 任一维度 CRITICAL 即驳回, 不存在"下次再改" |
+| **健康闭环** | 审查必须包含图谱健康检查, 确保知识库同步 |
+
+---
+
+## 问题分级
+
+| 级别 | 定义 | 处理 |
+|:---|:---|:---|
+| 🔴 CRITICAL | 逻辑Bug、Git冲突标记、重复造轮子、UI-业务耦合、代码与图谱矛盾 | 必须修复, 驳回 |
+| 🟡 MAJOR | 函数>50行、嵌套>3层、DRY违规、死代码、图谱未同步、孤立节点 | 建议修复 |
+| 🔵 INFO | 命名优化、TODO残留、目录结构建议 | 可选 |
 
 ---
 
-## 审计流程
+## 标准流程
+
+### Phase 0: 加载审查标准
 
-### Step 0: 加载规则
 ```
-kg_get_rules(ruleType:"reviewRules") → 审查规则
-kg_get_rules(ruleType:"codeStyle") → 编码风格
+kg_rules(action:"get", ruleType:"reviewRules")  → 审查规则
+kg_rules(action:"get", ruleType:"codeStyle")    → 编码风格
+kg_rules(action:"get", ruleType:"errorAnalysis") → 错误分析规则
 ```
-**将获取的规则作为本次审查的补充标准**
+将获取的规则作为本次审查的量化标准。
 
-### Step 1: 卫生检查
-| 检测项 | 处理 |
-|:---|:---|
-| Git 冲突标记 (`<<<<`, `====`) | 🔴 立即终止 |
-| 死代码 (注释块/未引用Import/未使用变量) | 🟡 警告 |
-| 调试残留 (`debugger`语句) | 🟡 移除 |
+**确定审查范围**:
+```
+Bash: git diff --name-only         → 变更文件列表
+Bash: git log --oneline -3         → 近期提交
 
-### Step 2: 架构审计 (重点)
-| 检测项 | 规则 | 级别 |
-|:---|:---|:---|
-| **耦合度** | UI层含复杂if-else计算 → 提取为纯函数 | 🔴 |
-| **重复造轮子** | utils/hooks已有实现 → 禁止重写 | 🔴 |
-| **复用性** | 函数依赖全局变量 → 改为纯函数 | 🟡 |
-| **健壮性** | 缺少 `?.` 导致崩溃风险 | 🟡 |
-| **编码风格** | 对照 codeStyle 规则检查 | 🔵 |
+对每个变更文件:
+  code_context(filePath)           → 文件的符号/依赖/被引用
+  → 确定关联的图谱节点
+```
 
-### Step 3: 知识图谱同步
+### Phase 1: 4维并行审查
+
+#### A. 逻辑审计
 ```
-1. 提取核心实体 (Class/Function)
-2. kg_search 检测是否已有节点
-3. 发现BUG → kg_update_node 写入 bugfixes:
-   {id:"BUG-xxx", date:"ISO", issue:"问题", solution:"方案", impact?:"影响"}
-4. 新实体 → 标记待创建节点
+对每个变更文件:
+  1. 脑补执行流: 不运行代码, 沿调用链推演输入→处理→输出
+  2. 绘制 ASCII 逻辑验证图, 确认变更点形成闭环
+  3. 检查:
+     - 流程是否完全闭环? (有入口必有出口)
+     - 是否存在逻辑断层? (中间环节缺失)
+     - 边界条件是否覆盖? (空值/异常/并发)
+     - 输入验证是否充分? (系统边界处)
 ```
 
----
+#### B. 代码清洁
+```
+检查项:
+  × Git冲突标记 (<<<<<<, ======, >>>>>>)    → 🔴 立即终止
+  × 死代码 (未引用的函数/变量/import)         → 🟡
+  × 调试残留 (debugger, console.log)         → 🟡
+  × 注释掉的旧逻辑 (_v1, _old, _backup)     → 🟡
+  × DRY违规 (重复代码块)                     → 🟡
+  × TODO/FIXME 残留                         → 🔵
+
+检查手段:
+  Grep("<<<<<<")       → 冲突标记
+  Grep("debugger")     → 调试语句
+  Grep("console.log")  → 日志残留
+  Grep("_v1|_old|_backup") → 旧版命名
+```
 
-## 问题分级
+#### C. 极简架构
+```
+对照 codeStyle 规则逐条检查:
+  × 函数超50行                              → 🟡 拆分建议
+  × 嵌套超3层                               → 🟡 扁平化建议
+  × 重复造轮子 (code_query 搜索已有实现)      → 🔴
+  × UI层包含复杂业务逻辑                     → 🔴 下沉到 Hook/Service
+  × 模块间强耦合                             → 🔴
+  × 能一行写完用了多行                        → 🔵
+
+检查手段:
+  code_query(新增函数名)  → 是否已有类似实现?
+  code_impact(变更符号)   → 耦合度评估
+```
 
-| 级别 | 定义 | 处理 |
-|:---|:---|:---|
-| 🔴 CRITICAL | Git冲突、逻辑Bug、重复造轮子、UI-业务耦合 | 必须修复 |
-| 🟡 MAJOR | 嵌套>3层、函数过长、DRY违规、死代码 | 建议修复 |
-| 🔵 INFO | 命名优化、目录结构建议 | 可选优化 |
+#### D. 图谱一致性
+```
+对每个变更涉及的图谱节点:
+  1. code_smart_context(变更符号)
+     → 代码实际的依赖/导出/行为
+
+  2. kg_flowchart(action:"get_node", nodeId:关联节点,
+       includeDoc:true, includeFiles:true)
+     → 图谱记录的描述/连线/文档
+
+  3. 对比:
+     × 代码改了函数签名, 图谱描述未更新?          → 🟡
+     × 代码新增了依赖, 图谱连线未添加?            → 🟡
+     × 代码逻辑与图谱文档明确矛盾?               → 🔴
+     × 新增文件未 bind 到任何节点?               → 🟡
+```
+
+### Phase 2: 图谱健康检查
+
+```
+kg_flowchart(action:"orphans")
+  → 孤立节点列表
+  → 新增代码是否未入图谱?
+
+kg_flowchart(action:"health")
+  → 冷热分布
+  → 有节点长期未查询/更新?
+
+对变更文件检查 bind 状态:
+  kg_flowchart(action:"get_node", nodeId:关联节点, includeFiles:true)
+  → 变更文件是否已绑定?
+  → 未绑定 = 图谱覆盖缺口
+```
+
+### Phase 3: 裁决
+
+```
+汇总 4 维度 + 健康检查的所有 Flag:
+
+任一 🔴 CRITICAL → 驳回
+  → 列出所有问题 + 修复建议
+  → 修复后重新审查
+
+全部通过 → 生成审查报告
+```
 
 ---
 
-## 报告模板
+## 审查报告模板
 
 ```markdown
-### 🛡️ 代码审计报告
+### 审查报告
 
-**概览**: 评分 8/10 | 🔴 2 | 🟡 3 | 🔵 1
+**概览**: 评分 85/100 | 🔴 0 | 🟡 2 | 🔵 1
+**状态**: ✅ 通过 / ❌ 驳回
 
 **应用规则**:
-- reviewRules: [已加载 N 条]
-- codeStyle: [已加载 N 条]
+- reviewRules: 已加载 N 条
+- codeStyle: 已加载 M 条
+
+**逻辑验证图** (A维度):
+[用户输入] → [参数校验] → [业务处理] → [返回结果] ✅ 闭环
+
+| 级别 | 维度 | 位置 | 分类 | 描述 |
+|:---|:---|:---|:---|:---|
+| 🟡 | C极简 | handler.rs:L45 | 函数过长 | 62行, 建议拆分为 parse + execute |
+| 🟡 | D图谱 | useAuth hook | 未同步 | 新增缓存逻辑未记入图谱文档 |
+| 🔵 | B清洁 | utils.ts:L12 | TODO | `// TODO: optimize later` |
+
+**重构建议** (针对MAJOR):
+> handler.rs:L45 函数过长
+> Before: 单个62行函数处理全部逻辑
+> After: 拆分为 parse_request(15行) + execute_action(20行)
+
+**图谱同步建议**:
+- [ ] 节点 n_auth 文档需更新 (新增缓存描述)
+- [ ] 新文件 src/utils/cache.ts 需 bind 到 n_auth
+- [ ] 建议执行 /pp:sync 完成同步
+```
 
-| 级别 | 位置 | 分类 | 描述 |
-|:---|:---|:---|:---|
-| 🔴 | L45 | Reinvention | `formatDate` 已存在于 utils/date.ts |
-| 🔴 | L20-35 | Coupling | UI组件直接处理API数据清洗 |
-| 🟡 | L88 | DRY | 循环逻辑与 UserList.tsx 重复 |
+---
 
-**重构方案**:
-> L20 数据清洗耦合
-Before: `const list = data.map(item => ({...item, price: item.price * 100}))`
-After: `import { transformPrice } from '@/utils/currency'`
+## 工具速查
 
-**KG同步**:
-- [ ] 已为节点 `PaymentGateway` 写入 bugfix 记录
-- [ ] 新实体待创建: `TransformPrice`
-```
+| 阶段 | 工具 | 用途 |
+|:---|:---|:---|
+| 加载 | `kg_rules(get)` | 审查规则/编码风格 |
+| 范围 | `code_context(file)` | 变更文件的依赖 |
+| A逻辑 | 人工推演 + ASCII图 | 逻辑闭环验证 |
+| B清洁 | `Grep(pattern)` | 死代码/调试残留扫描 |
+| C极简 | `code_query(funcName)` | 检查是否已有实现 |
+| C极简 | `code_impact(symbol)` | 耦合度评估 |
+| D图谱 | `code_smart_context(symbol)` | 代码侧全关联 |
+| D图谱 | `kg_flowchart(get_node)` | 图谱侧节点详情 |
+| 健康 | `kg_flowchart(orphans)` | 孤立节点 |
+| 健康 | `kg_flowchart(health)` | 冷热分布 |

package/templates/commands/pp/sync.md

@@ -1,178 +1,229 @@
-**角色**: Knowledge Graph Synchronization Architect (KGSA) - 维护代码与知识图谱的绝对一致性
-
-## 同步宪法
-| 原则 | 要求 |
-|:---|:---|
-| **代码即真理** | 代码与图谱冲突时以 Git 状态为准，强制覆写；禁止保留幽灵节点 |
-| **拓扑优先** | Types → Utils → Services → UI，底层未建不创建上层 |
-| **引用强约束** | relatedFiles 精确锚定物理路径；signature 为代码唯一标识符 |
-| **版本追踪** | 版本号以 0.1 起始，每次同步有变动必须更新版本号 (AI控制递增) |
-| **版本一致性** | 同步完成后更新 lastSyncAt，用于检测代码↔图谱是否同步 |
-| **标签完整性** | 每节点 ≥3 个分类标签，标签由AI管理 |
-
----
-
-## 同步模式
-| 参数 | 行为 |
-|:---|:---|
-| `all` | 全量扫描 `src/**/*.{ts,tsx,py,go,rs}` |
-| `recent` | `git diff --name-only HEAD~N` 增量检测 |
-| `check` | 仅对比不执行 |
-
----
-
-## 标准流程 (5步)
-
-### Step 1: 变更检测
-```
-task_create({ title:"KG同步", goals:["检测变更","更新节点","验证覆盖"], related_nodes:["root"] })
-
-recent模式: git diff --name-only HEAD~3
-all模式: Glob src/**/*.{ts,tsx}
-
-⭐ kg_search([""]) 一次获取全部现有节点 (替代逐个search)
-```
-
-**版本一致性检测** ⭐新增:
-```
-对每个有 relatedFiles 的节点:
-1. 获取文件 mtime (通过 Bash stat 或 fs.statSync)
-2. 对比节点的 lastSyncAt
-3. mtime > lastSyncAt → 标记为 [OUTDATED] 需同步
-4. lastSyncAt 不存在 → 标记为 [UNTRACKED] 从未同步
-```
-
-**输出变更清单**:
-```
-├─ 🟢 [NEW] src/services/Payment.ts (待创建)
-├─ 🟡 [MOD] src/utils/format.ts (待更新)
-├─ 🟠 [OUTDATED] src/hooks/useAuth.ts (代码已改，图谱未同步)
-└─ 🔴 [DEL] src/legacy/old.ts (待废弃)
-```
-等待用户确认 `OK`
-
-### Step 2: 依赖解析 + 拓扑排序
-解析 import 语句 → 构建依赖树 → 拓扑排序确保底层先处理
-
-### Step 2.5: 标签完整性预检 ⭐新增
-```
-kg_list_tags() → 获取现有标签词库 (91个标签)
-检查待处理节点:
-  - 标签 < 3 → 自动补全建议
-  - 使用现有标签词库保持一致性
-```
-
-### Step 3: 原子化执行
-对每个文件:
-```
-1. 读取源码 → 提取 signature/imports/comments
-2. 从 Step1 缓存查找现有节点 (无需再次kg_search)
-3. 执行写入:
-   - NEW: kg_create_node (全字段 + relatedFiles + ⚠️tags≥3)
-   - MOD: kg_update_node (变动字段 + 追加 versions)
-   - DEL: kg_update_node(status:"deprecated") 或 kg_delete_node
-4. 每5个文件: task_add_log(progress, "已处理 N/M")
-5. 遇到问题: task_add_log(issue, "xxx解析失败")
-6. 找到方案: task_add_log(solution, "改用yyy方式")
-```
-
-**版本追加规则** (MOD时自动执行):
-```
-kg_update_node({
-  nodeId: "xxx",
-  description: "新描述",
-  lastSyncAt: new Date().toISOString(),  // ⭐ 更新同步时间戳
-  versions: [...现有versions, {
-    version: 上一版本 + 0.1,  // ⭐ 0.1起始，AI控制递增
-    date: "ISO时间",
-    changes: "本次变更摘要"
-  }]
-})
-```
-
-**代码版本注释** (源码文件头部):
-```typescript
-// @version 0.1
-// 或 JSDoc 格式
-/**
- * @version 0.1
- */
-```
-
-**同步时间戳规则** ⭐新增:
-```
-NEW: kg_create_node 后自动设置 lastSyncAt = now
-MOD: kg_update_node 时必须传 lastSyncAt = now
-OUTDATED: 仅更新 lastSyncAt (无需改 description/versions)
-```
-
-### Step 4: 关系校验 ⭐优化
-```
-1. kg_read_node(nodeId, depth=1) 批量校验上下游关系
-2. kg_list_nodes({maxEdges:0}) 检查孤立节点
-3. 检查断链 (dependencies 指向不存在的 signature)
-```
-
-### Step 5: 交付报告 ⭐增强
-```
-1. 统计覆盖率
-2. kg_list_tags() 输出标签分布
-3. task_complete({
-     summary: "同步完成...",
-     difficulties: ["遇到的困难"],
-     solutions: ["采用的方案"],
-     references: [{title:"参考", url:"..."}]
-   })
-```
-
-**交付报告**:
-```markdown
-| 维度 | 数量 | 状态 |
-|:---|:---|:---|
-| 新增节点 | 3 | ✅ |
-| 更新节点 | 12 | ✅ |
-| 废弃节点 | 1 | ⚠️ |
-| 版本追加 | 8 | ✅ |
-| 标签补全 | 5 | ✅ |
-| 同步时间戳更新 | 15 | ✅ |
-| 版本一致率 | 100% | 🟢 |
-| 覆盖率 | 98.5% | 🟢 |
-| 标签总数 | 91 | 📊 |
-
-建议: git add . && git commit -m "chore: sync kg"
-```
-
----
-
-## MCP 工具速查 ⭐新增
-
-| 工具 | 用途 | 示例 |
-|:---|:---|:---|
-| `kg_search([""])` | 获取全部节点 | 变更检测时一次拉取 |
-| `kg_list_tags` | 标签词库 | 保持标签一致性 |
-| `kg_read_node(id, depth=1)` | 含关系的详情 | 校验上下游 |
-| `kg_list_nodes({maxEdges:0})` | 孤立节点 | 发现断链 |
-| `kg_list_nodes` | 含summary列表 | 覆盖率报告 |
-
----
-
-## 异常处理
-| 场景 | 反应 |
-|:---|:---|
-| git status 不干净 | 警告 + 询问是否强制继续 |
-| kg_search 返回多个同名节点 | 暂停，列出候选请求人工绑定 |
-| 文件解析失败 | task_add_log(issue) + 标记 Skipped，不中断队列 |
-| 标签不足3个 | 自动从词库补全，记录日志 |
-
----
-
-## 字段映射
-| 代码实体 | 图谱字段 | 提取规则 |
-|:---|:---|:---|
-| import 语句 | dependencies | 解析AST，匹配现有 signature |
-| 文件路径 | relatedFiles | 相对项目根 (如 `src/utils/auth.ts`) |
-| export 函数/类 | signature | 标识符名 (如 `AuthService`) |
-| JSDoc/Comments | description | 优先注释，无则代码生成摘要 |
-| 功能分类 | tags | ≥3个，使用 kg_list_tags 词库 |
-| 同步时间 | lastSyncAt | 每次同步完成时设为当前 ISO 时间戳 |
-| `// @version 0.1` | versions[].version | 代码文件头注释，0.1起始 |
+**角色**: Knowledge Graph Synchronization Architect — 维护代码与知识图谱的绝对一致性
+
+## 同步宪法
+
+| 原则 | 要求 |
+|:---|:---|
+| **代码即真理** | 代码与图谱冲突时以 Git 状态为准, 强制覆写 |
+| **层级感知** | 变更定位到具体子图层级, 逐层向上验证影响链 |
+| **最小变更** | 只更新有差异的节点/文档, 不做无意义的全量覆写 |
+| **创建即关联** | 新增节点必须 bind 源码 + 创建/关联文档, 无孤立资产 |
+
+---
+
+## 同步模式
+
+用户触发时选择模式 (或由 AI 根据上下文判断):
+
+| 模式 | 触发 | 扫描范围 |
+|:---|:---|:---|
+| `recent` (默认) | `/pp:sync` 或 `/pp:sync recent` | `git diff --name-only HEAD~3` 近期变更文件 |
+| `all` | `/pp:sync all` | `code_scan(force:true)` 全量重扫 |
+| `check` | `/pp:sync check` | 仅对比, 输出差异报告, 不执行写入 |
+
+---
+
+## 标准流程
+
+### Phase 1: 变更检测
+
+**1.1 获取图谱现状**
+```
+kg_init()                        → 确保项目连接
+kg_tree()                        → 文档全景
+kg_flowchart(action:"list")      → 所有流程图
+kg_flowchart(action:"get")       → 主图节点+连线
+```
+
+**1.2 获取代码变更**
+```
+recent 模式:
+  Bash: git diff --name-only HEAD~3    → 变更文件列表
+  Bash: git log --oneline -5           → 近期提交摘要
+  code_scan()                          → 增量更新索引
+
+all 模式:
+  code_scan(force:true)                → 全量重建索引
+  Glob: src/**/*.{ts,tsx,rs}           → 全部源文件
+```
+
+**1.3 逐文件交叉比对**
+```
+对每个变更文件 (或全量文件):
+  1. code_context(filePath)             → 该文件的符号/依赖/被引用
+  2. kg_flowchart(action:"get", chartId:对应子图) → 图谱中该区域的节点
+  3. 对比:
+     - 文件中有导出, 图谱无节点         → [NEW]
+     - 文件已修改, 图谱节点描述/连线过时  → [MOD]
+     - 图谱节点绑定的文件已删除/移动     → [DEL/DRIFT]
+     - 图谱与代码一致                   → [OK]
+```
+
+**输出变更清单** (等待用户确认):
+```
+├─ 🟢 [NEW]   src/hooks/useTheme.ts       → 需创建节点+文档
+├─ 🟡 [MOD]   src-tauri/src/storage/graph_store.rs → 节点描述需更新
+├─ 🔴 [DEL]   src/legacy/oldHelper.ts     → 节点需废弃/删除
+├─ 🟠 [DRIFT] src/utils/format.ts → moved to src/utils/formatter.ts → 需 unbind+rebind
+└─ ✅ [OK]    src/hooks/useProjectData.ts  → 无变化
+
+统计: NEW 2 | MOD 5 | DEL 1 | DRIFT 1 | OK 15
+```
+→ 用户确认 `OK` 后进入 Phase 2
+
+### Phase 2: 影响链分析
+
+**2.1 定位子图层级**
+```
+对每个 [NEW]/[MOD] 文件:
+  1. 确定它属于哪张子图 (通过目录映射或 bind 记录)
+  2. code_impact(symbolName)    → 该符号的爆炸半径
+     - L1 直接引用 = 必须检查
+     - L2 间接引用 = 建议检查
+  3. 影响是否跨子图? → 标记需要检查的父图连线
+```
+
+**2.2 拓扑排序**
+```
+按依赖关系排序变更:
+  底层变更先处理 (types/store) → 上层后处理 (hooks/components)
+  避免更新上层节点时底层依赖还未就绪
+```
+
+### Phase 3: 原子化执行
+
+**3.1 处理 [NEW] — 新增节点**
+```
+1. 判断深度: 该文件是否需要独立子图?
+   - 导出 ≥5 个符号 → create_chart + batch_add
+   - 导出 <5 个符号 → 在父子图中添加节点
+
+2. 创建节点:
+   kg_flowchart(action:"batch_add", chartId:目标子图,
+     nodes:[{id:"n_xxx", label:"xxx", nodeType:"process", domain:"...", description:"..."}],
+     edges:[{from:"n_xxx", to:"n_依赖", edgeType:"call"}])
+
+3. 绑定源码:
+   kg_flowchart(action:"bind", nodeId:"n_xxx", files:["src/..."])
+
+4. 创建文档 (遵循5分类):
+   kg_doc(action:"create",
+     path:"/模块/前端/xxx",
+     summary:"一句话职责",
+     content:"## 职责\n...\n## 公开API\n...\n## 文件路径\n...",
+     bindTo:"n_xxx")
+```
+
+**3.2 处理 [MOD] — 更新节点**
+```
+1. 读取现有节点:
+   kg_flowchart(action:"get_node", nodeId:"n_xxx", includeDoc:true)
+
+2. 对比差异, 更新变动部分:
+   kg_flowchart(action:"update_node", nodeId:"n_xxx",
+     description:"新的一句话描述",
+     docContent:"更新后的文档内容",
+     docSummary:"更新后的摘要")
+
+3. 追加版本记录:
+   kg_doc(action:"update", path:"/模块/.../xxx",
+     versions:[{version:当前+0.1, date:"ISO日期", changes:"变更摘要"}])
+
+4. 检查连线是否需要更新:
+   code_context(filePath) → 新的import列表
+   对比图谱中现有连线 → 增删连线
+```
+
+**3.3 处理 [DEL] — 废弃/删除**
+```
+选项A - 标记废弃 (推荐):
+  kg_flowchart(action:"update_node", nodeId:"n_xxx", description:"[DEPRECATED] 原描述")
+  kg_flowchart(action:"unbind", nodeId:"n_xxx", files:["已删文件"])
+
+选项B - 彻底删除:
+  kg_flowchart(action:"delete_node", nodeId:"n_xxx")
+  kg_doc(action:"delete", path:"/模块/.../xxx")
+```
+
+**3.4 处理 [DRIFT] — 路径漂移**
+```
+kg_flowchart(action:"unbind", nodeId:"n_xxx", files:["旧路径"])
+kg_flowchart(action:"bind", nodeId:"n_xxx", files:["新路径"])
+```
+
+**进度记录** (每处理5个文件):
+```
+kg_task(action:"update", taskId:"当前任务", log_type:"progress",
+  content:"已处理 N/M | NEW:a MOD:b DEL:c")
+```
+
+### Phase 4: 层级验证
+
+**4.1 子图内部验证**
+```
+对每个受影响的子图:
+  kg_flowchart(action:"orphans", chartId:"sub_xxx")  → 该子图内孤立节点
+  kg_flowchart(action:"get", chartId:"sub_xxx")      → 检查连线完整性
+```
+
+**4.2 跨层验证**
+```
+如果变更影响了跨子图的连线:
+  kg_flowchart(action:"get_node", nodeId:父节点, expand:2)
+  → 验证父子图之间的连线是否仍然正确
+```
+
+**4.3 全局健康检查**
+```
+kg_flowchart(action:"orphans")     → 全局孤立节点 (应为0)
+kg_flowchart(action:"health")      → 冷热分布
+kg_tree()                          → 文档覆盖确认
+```
+
+### Phase 5: 交付报告
+
+```
+| 维度 | 数量 | 状态 |
+|:---|:---|:---|
+| 新增节点 | N | ✅ |
+| 更新节点 | M | ✅ |
+| 废弃/删除 | K | ⚠️/✅ |
+| 路径修复 | P | ✅ |
+| 新增文档 | D | ✅ |
+| 更新文档 | U | ✅ |
+| 新增连线 | E | ✅ |
+| 孤立节点 | 0 | 🟢 |
+| 受影响子图 | S 张 | 🟢 |
+```
+
+如有任务:
+```
+kg_task(action:"archive", taskId:"当前任务",
+  summary:"同步完成...",
+  difficulties:["遇到的问题"],
+  solutions:["解决方案"])
+```
+
+---
+
+## 目录→子图映射规则
+
+| 源码目录 | 子图 | 父节点 |
+|:---|:---|:---|
+| src-tauri/src/storage/ | sub_storage | n_storage |
+| src-tauri/src/models/ | sub_kg (内) | n_kg |
+| src-tauri/src/server/ | sub_entry | n_entry |
+| src-tauri/src/commands/ | sub_entry (内) | n_entry |
+| mcp-server/src/tools/ | sub_mcp | n_mcp |
+| src/components/ | sub_frontend | n_frontend |
+| src/hooks/ | sub_frontend (内) | n_frontend |
+
+## 异常处理
+
+| 场景 | 处理 |
+|:---|:---|
+| git 有未提交变更 | 警告 + 展示 diff, 询问是否继续 |
+| 节点绑定的文件不存在 | 标记 [DRIFT], 搜索新位置, 建议 rebind |
+| 同一符号映射多个节点 | 暂停, 列出候选, 请求用户选择 |
+| code_scan 索引过旧 | 自动 code_scan() 增量更新后重试 |
+| 子图嵌套变更 (新文件导出≥5) | 建议 create_chart 升级为子图 |