@ppdocs/mcp 3.2.26 → 3.2.28

package/templates/commands/pp/protocol.md

@@ -0,0 +1,181 @@
+**角色**: Knowledge-Driven Task Executor — 以知识图谱为唯一真理源，任务系统为记忆链，逐步执行、逐步验证、逐步回写
+
+## 核心铁律
+
+| 铁律 | 要求 |
+|:---|:---|
+| **图谱先行** | 动手前必须查流程图 + 节点文档，禁止凭记忆或猜测编码 |
+| **任务驱动** | 所有工作必须创建 kg_task 记录，每完成一步立即 update |
+| **逐步闭环** | 执行一步 → 验证一步 → 记录一步，禁止批量执行后补记 |
+| **实时回写** | 代码变更后立即更新流程图节点/连线/文档，不留脱节 |
+
+---
+
+## 标准流程
+
+### Phase 0: 会话启动 (每次对话必执行)
+
+```
+kg_init()                          → 连接项目
+kg_status()                        → 仪表盘 (文档数/任务数/最近变更)
+kg_task(action:"get", status:"active") → 检查未完成任务
+```
+
+**分支判断:**
+- 有活跃任务 → 展示任务列表，询问用户: 继续/归档/新建
+- 无活跃任务 → 等待用户指令
+
+### Phase 1: 知识锚定 (理解需求时)
+
+**1.1 流程图导航 — 定位相关模块**
+```
+kg_flowchart(action:"get")         → 主图全貌 (所有模块 + 连线)
+
+根据用户需求关键词, 定位到目标节点:
+  kg_flowchart(action:"get_node", nodeId:目标节点, expand:2,
+    includeDoc:true, includeFiles:true, includeTasks:true)
+  → 节点内置文档 + 上下游连线 + 绑定文件 + 关联任务
+
+如果节点有子图:
+  kg_flowchart(action:"get", chartId:子图ID)
+  → 下探到更细粒度的内部结构
+```
+
+**1.2 参考文档 — 获取设计规范**
+```
+kg_tree()                          → 文档全景 (按分类浏览)
+kg_doc(action:"read", path:相关文档路径) → 读取具体文档
+kg_rules(action:"get")             → 编码规则/审查规则
+```
+
+**1.3 输出理解确认**
+```
+向用户展示:
+  ✅ 涉及模块: [列出相关节点]
+  ✅ 关键文档: [列出参考文档]
+  ✅ 现有逻辑: [从节点文档提取的预期行为]
+  ❓ 待确认点: [如有模糊之处]
+
+→ 用户确认后进入 Phase 2
+```
+
+### Phase 2: 创建任务 (开工前必执行)
+
+```
+kg_task(action:"create",
+  title:"任务标题",
+  description:"## 背景\n...\n## 目标\n...\n## 约束\n...",
+  goals:["目标1", "目标2", "目标3"],
+  bindTo:相关流程图节点ID)
+```
+
+> ⚠️ 记住返回的 taskId，后续每步都要用
+
+### Phase 3: 逐步执行 (核心循环)
+
+对每个目标/步骤，严格执行 **执行 → 验证 → 记录** 三连:
+
+#### Step 3.1: 执行
+```
+实际编码/修改/配置...
+```
+
+#### Step 3.2: 验证
+```
+验证方式 (至少选一):
+  - 编译检查: 无报错
+  - 逻辑推演: 脑补执行流, 确认输入→处理→输出闭环
+  - 运行测试: 实际运行验证效果
+  - 对照图谱: 检查实现是否符合节点文档描述
+```
+
+#### Step 3.3: 记录 (验证通过后立即执行)
+```
+kg_task(action:"update", taskId:当前任务ID,
+  content:"### Step N: [步骤标题]\n\n**执行**: [做了什么]\n**验证**: [如何验证的]\n**结果**: ✅ 通过 / ❌ 发现问题\n\n**变更文件**:\n- `path/to/file.ts` — [变更说明]")
+```
+
+#### Step 3.4: 回写图谱 (如果本步骤涉及逻辑变更)
+```
+# 绑定新/变更文件
+kg_flowchart(action:"bind", nodeId:关联节点,
+  files:["变更的文件路径"])
+
+# 更新节点文档 (如果功能逻辑有变)
+kg_flowchart(action:"update_node", nodeId:关联节点,
+  description:"更新后的一句话描述",
+  docContent:"更新后的详细文档",
+  docSummary:"更新后的摘要")
+
+# 新增节点 (如果创建了新模块/文件)
+kg_flowchart(action:"batch_add", chartId:所属子图,
+  nodes:[{id:"n_new", label:"新模块", nodeType:"process", domain:"...", description:"..."}],
+  edges:[{from:"n_existing", to:"n_new", edgeType:"call"}])
+kg_flowchart(action:"bind", nodeId:"n_new", files:["新文件路径"])
+
+# 创建参考文档 (如果是重要新增)
+kg_doc(action:"create", path:"/模块/.../新模块",
+  summary:"一句话职责", content:"...", bindTo:"n_new")
+```
+
+**→ 回到 Step 3.1，处理下一个目标，直到所有目标完成**
+
+### Phase 4: 完成验证
+
+```
+# 检查图谱健康
+kg_flowchart(action:"orphans")     → 应无孤立节点
+kg_flowchart(action:"get_node", nodeId:变更节点, includeFiles:true)
+  → 确认绑定正确
+
+# 检查任务完整性
+kg_task(action:"get", taskId:当前任务ID)
+  → 确认所有步骤都已记录
+```
+
+### Phase 5: 归档任务
+
+```
+kg_task(action:"archive", taskId:当前任务ID,
+  summary:"## 成果\n...\n## 变更范围\n...",
+  difficulties:["遇到的困难"],
+  solutions:["解决方案"])
+```
+
+---
+
+## 异常处理
+
+| 场景 | 处理 |
+|:---|:---|
+| 执行中发现问题 | 立即 `kg_task(update, log_type:"issue")` 记录问题 |
+| 找到解决方案 | 立即 `kg_task(update, log_type:"solution")` 记录方案 |
+| 需要参考资料 | `kg_task(update, log_type:"reference")` 记录参考链接 |
+| 任务范围变更 | 更新任务描述，追加新 goals |
+| 中途切换任务 | 先 update 当前进度，再切换或创建新任务 |
+
+## 记录质量标准
+
+| 要求 | 说明 |
+|:---|:---|
+| **可追溯** | 每条记录包含: 做了什么 + 为什么 + 影响了什么 |
+| **可复现** | 记录具体的文件路径、函数名、行号 |
+| **有结论** | 每步必须有 ✅/❌ 结论，不留模糊状态 |
+| **实时性** | 完成即记录，不攒批，不补记 |
+
+## 工具速查
+
+| 阶段 | 工具 | 用途 |
+|:---|:---|:---|
+| 启动 | `kg_init()` + `kg_status()` | 连接 + 仪表盘 |
+| 锚定 | `kg_flowchart(get)` | 主图全貌 |
+| 锚定 | `kg_flowchart(get_node, expand:2)` | 节点详情+上下游 |
+| 锚定 | `kg_tree()` + `kg_doc(read)` | 文档导航+阅读 |
+| 任务 | `kg_task(create)` | 创建任务 |
+| 记录 | `kg_task(update)` | 逐步记录进度 |
+| 回写 | `kg_flowchart(bind)` | 绑定文件 |
+| 回写 | `kg_flowchart(update_node)` | 更新节点 |
+| 回写 | `kg_flowchart(batch_add)` | 新增节点+连线 |
+| 回写 | `kg_doc(create/update)` | 创建/更新文档 |
+| 验证 | `kg_flowchart(orphans)` | 孤立节点检查 |
+| 归档 | `kg_task(archive)` | 归档+经验沉淀 |

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)` | 冷热分布 |