@ppdocs/mcp 3.2.27 → 3.2.28

package/dist/cli.js

@@ -525,6 +525,7 @@ function installCursorTemplates(cwd, apiUrl, user) {
 // ========================================================================
 /** 工作流版本映射表: 模板文件名 → { 工作流命令名, 描述 } */
 const WORKFLOW_MAP = {
+    'protocol.md': { name: 'pp-task', desc: '知识驱动任务协议 — 图谱先查→任务追踪→逐步验证→实时回写' },
     'init.md': { name: 'pp-init', desc: 'System Genesis Architect - 从文件系统提取秩序，构建知识图谱，重点识别**复用性资产**' },
     'sync.md': { name: 'pp-sync', desc: 'Knowledge Graph Deep-Sync Protocol' },
     'review.md': { name: 'pp-shencha', desc: '审查任务成果' },
@@ -536,7 +537,7 @@ const WORKFLOW_MAP = {
     'SynchronizationProtocol.md': { name: 'pp-syncpro', desc: 'Knowledge Graph Quick-Sync Protocol' },
 };
 /** 已废弃的旧版工作流文件名 (从早期 COMMAND_MAP 残留, 安装时自动清理) */
-const LEGACY_WORKFLOW_NAMES = ['pp-fenxi.md', 'pp-task.md', 'pp-review.md'];
+const LEGACY_WORKFLOW_NAMES = ['pp-fenxi.md', 'pp-review.md'];
 /**
  * 通用工作流安装: 删除旧版 → 写入最新版到 .agents/workflows/
  * 全平台共享: Antigravity / Claude Code / Cursor / Codex / Kiro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "3.2.27",
+  "version": "3.2.28",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",

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)` | 归档+经验沉淀 |