@ppdocs/mcp 3.2.26 → 3.2.28

package/dist/cli.js

@@ -441,12 +441,15 @@ function generateMcpPermissions() {
 /** 安装 Claude Code 模板 */
 function installClaudeTemplates(cwd) {
     const claudeDir = path.join(cwd, '.claude');
-    // 1. 复制 commands/pp/
+    // 1. 复制 commands/pp/ (先清空旧版，确保安装最新模板)
     const srcCommands = path.join(TEMPLATES_DIR, 'commands', 'pp');
     const destCommands = path.join(claudeDir, 'commands', 'pp');
     if (fs.existsSync(srcCommands)) {
+        if (fs.existsSync(destCommands)) {
+            fs.rmSync(destCommands, { recursive: true });
+        }
         copyDirRecursive(srcCommands, destCommands);
-        console.log(`✅ Installed .claude/commands/pp/`);
+        console.log(`✅ Installed .claude/commands/pp/ (old versions cleaned)`);
     }
     // 2. 复制 hooks/
     const srcHooks = path.join(TEMPLATES_DIR, 'hooks');
@@ -483,10 +486,13 @@ function installClaudeTemplates(cwd) {
     fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2));
     console.log(`✅ Configured .claude/settings.json hooks (${process.platform})`);
     console.log(`✅ Added ${mcpPermissions.length} MCP method permissions`);
+    // 4. 安装工作流到 .agents/workflows/ (全平台通用)
+    installWorkflows(cwd);
 }
-/** 安装 Codex 模板 (生成 AGENTS.md) */
+/** 安装 Codex 模板 (生成 AGENTS.md + 工作流) */
 function installCodexTemplates(cwd) {
     generateAgentsMd(cwd);
+    installWorkflows(cwd);
 }
 /** 生成 AGENTS.md 工具函数 (去重) */
 function generateAgentsMd(cwd) {
@@ -510,64 +516,90 @@ function installCursorTemplates(cwd, apiUrl, user) {
         fs.copyFileSync(srcRules, destRules);
         console.log(`✅ Created .cursorrules`);
     }
+    // 3. 安装工作流到 .agents/workflows/
+    installWorkflows(cwd);
 }
-/** 安装 Antigravity (Gemini IDE) 模板 */
-function installAntigravityTemplates(cwd, apiUrl, user) {
-    // Antigravity 由 gemini CLI 注册 env，文件配置不注入避免冲突
-    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl, { noEnv: true, user });
-    // 2. 生成 AGENTS.md
-    generateAgentsMd(cwd);
-    // 3. 安装斜杠命令 → 全局目录 ~/.gemini/antigravity/global_workflows/
-    //    Antigravity 从此目录读取全局斜杠命令，文件名=命令名，必须有 YAML frontmatter
+// ========================================================================
+//  ★ 通用工作流安装 — 全平台共享 (删旧 + 写新)
+//  所有 IDE 最终都通过此函数安装 .agents/workflows/ 下的工作流文件
+// ========================================================================
+/** 工作流版本映射表: 模板文件名 → { 工作流命令名, 描述 } */
+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: '审查任务成果' },
+    'diagnose.md': { name: 'pp-diagnose', desc: '深度问题诊断' },
+    'execute.md': { name: 'pp-execute', desc: '执行开发任务' },
+    'audit.md': { name: 'pp-audit', desc: '多Agent代码审计' },
+    'discuss.md': { name: 'pp-discuss', desc: '讨论响应与协作' },
+    'Zero_Defec_Genesis.md': { name: 'plan', desc: '零缺陷创生协议' },
+    'SynchronizationProtocol.md': { name: 'pp-syncpro', desc: 'Knowledge Graph Quick-Sync Protocol' },
+};
+/** 已废弃的旧版工作流文件名 (从早期 COMMAND_MAP 残留, 安装时自动清理) */
+const LEGACY_WORKFLOW_NAMES = ['pp-fenxi.md', 'pp-review.md'];
+/**
+ * 通用工作流安装: 删除旧版 → 写入最新版到 .agents/workflows/
+ * 全平台共享: Antigravity / Claude Code / Cursor / Codex / Kiro
+ * @param dirs 额外的安装目标目录 (如 Antigravity 的 global_workflows/)
+ */
+function installWorkflows(cwd, extraDirs = []) {
     const cmdSrcDir = path.join(TEMPLATES_DIR, 'commands', 'pp');
     if (!fs.existsSync(cmdSrcDir))
         return;
-    // Antigravity 全局 workflows 目录
-    const homeDir = process.env.USERPROFILE || process.env.HOME || '';
-    const globalWorkflowDir = path.join(homeDir, '.gemini', 'antigravity', 'global_workflows');
-    if (!fs.existsSync(globalWorkflowDir)) {
-        fs.mkdirSync(globalWorkflowDir, { recursive: true });
-    }
-    // 同时也安装到项目本地 .agents/workflows/ (作为备用)
+    // 项目本地 .agents/workflows/
     const localWorkflowDir = path.join(cwd, '.agents', 'workflows');
     if (!fs.existsSync(localWorkflowDir)) {
         fs.mkdirSync(localWorkflowDir, { recursive: true });
     }
-    // 模板文件名 → { 简短命令名, 中文描述 }
-    const COMMAND_MAP = {
-        'init.md': { name: 'pp-init', desc: '初始化项目知识图谱' },
-        'sync.md': { name: 'pp-sync', desc: '同步代码与知识图谱' },
-        'review.md': { name: 'pp-shencha', desc: '审查任务成果' },
-        'DiagnosticProtocol.md': { name: 'pp-fenxi', desc: '深度分析错误' },
-        'Execution_Task.md': { name: 'pp-task', desc: '执行开发任务' },
-        'Sentinel_4.md': { name: 'pp-audit', desc: '多Agent代码审计' },
-        'SynchronizationProtocol.md': { name: 'pp-syncpro', desc: '知识图谱同步协议' },
-        'Zero_Defec_Genesis.md': { name: 'plan', desc: '零缺陷创生协议' },
-    };
+    // 所有目标目录: 本地 + 额外 (如 global_workflows)
+    const allDirs = [localWorkflowDir, ...extraDirs];
+    // ★ Step 1: 清理 — 收集要清理的文件名 (当前版本 + 废弃名)
+    const targetNames = new Set(Object.values(WORKFLOW_MAP).map(m => `${m.name}.md`));
+    for (const legacy of LEGACY_WORKFLOW_NAMES) {
+        targetNames.add(legacy);
+    }
+    for (const dir of allDirs) {
+        for (const name of targetNames) {
+            const file = path.join(dir, name);
+            if (fs.existsSync(file)) {
+                fs.unlinkSync(file);
+            }
+        }
+    }
+    // ★ Step 2: 安装 — 读取模板, 添加 YAML frontmatter, 写入所有目标目录
     const files = fs.readdirSync(cmdSrcDir).filter(f => f.endsWith('.md'));
     let count = 0;
     for (const file of files) {
-        const mapping = COMMAND_MAP[file];
+        const mapping = WORKFLOW_MAP[file];
         if (!mapping)
-            continue; // 未映射的模板跳过
+            continue;
         const content = fs.readFileSync(path.join(cmdSrcDir, file), 'utf-8');
-        // 生成 Antigravity 格式: YAML frontmatter + 内容
         const workflow = `---\ndescription: ${mapping.desc}\n---\n\n${content}`;
-        // 写入全局目录
-        const globalFile = path.join(globalWorkflowDir, `${mapping.name}.md`);
-        if (!fs.existsSync(globalFile)) {
-            fs.writeFileSync(globalFile, workflow, 'utf-8');
-            count++;
-        }
-        // 同时写入项目本地目录
-        const localFile = path.join(localWorkflowDir, `${mapping.name}.md`);
-        if (!fs.existsSync(localFile)) {
-            fs.writeFileSync(localFile, workflow, 'utf-8');
+        for (const dir of allDirs) {
+            fs.writeFileSync(path.join(dir, `${mapping.name}.md`), workflow, 'utf-8');
         }
+        count++;
     }
     if (count > 0) {
-        console.log(`✅ Installed ${count} slash commands to global_workflows/ (use /plan, /pp-init, /pp-fenxi ...)`);
+        const targets = allDirs.map(d => path.basename(d)).join(' + ');
+        console.log(`✅ Installed ${count} workflows (old versions cleaned) → ${targets}`);
+    }
+}
+/** 安装 Antigravity (Gemini IDE) 模板 */
+function installAntigravityTemplates(cwd, apiUrl, user) {
+    // Antigravity 由 gemini CLI 注册 env，文件配置不注入避免冲突
+    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl, { noEnv: true, user });
+    // 2. 生成 AGENTS.md
+    generateAgentsMd(cwd);
+    // 3. Antigravity 全局 workflows 目录 (额外安装目标)
+    const homeDir = process.env.USERPROFILE || process.env.HOME || '';
+    const globalWorkflowDir = path.join(homeDir, '.gemini', 'antigravity', 'global_workflows');
+    if (!fs.existsSync(globalWorkflowDir)) {
+        fs.mkdirSync(globalWorkflowDir, { recursive: true });
     }
+    // 4. 调用通用安装: .agents/workflows/ + global_workflows/
+    installWorkflows(cwd, [globalWorkflowDir]);
 }
 /** 安装 Kiro 模板 */
 function installKiroTemplates(cwd, apiUrl, user) {
@@ -583,6 +615,8 @@ function installKiroTemplates(cwd, apiUrl, user) {
         fs.copyFileSync(srcRules, destRules);
         console.log(`✅ Created .kiro/rules/ppdocs.md`);
     }
+    // 3. 安装工作流到 .agents/workflows/
+    installWorkflows(cwd);
 }
 /** 检测当前工作区包含的 IDE */
 function detectIDEs(cwd) {

package/dist/tools/flowchart.js

@@ -314,11 +314,14 @@ export function registerFlowchartTools(server, ctx) {
                         if (!isNaN(num))
                             nextVer = Math.round((num + 0.1) * 10) / 10;
                     }
+                    // normalize escaped newlines from AI clients (e.g. "\\n" → actual newline)
+                    const normalizedContent = decoded.docContent.replace(/\\n/g, '\n');
+                    const normalizedSummary = decoded.docSummary.replace(/\\n/g, '\n');
                     docEntries.push({
                         version: `v${nextVer.toFixed(1)}`,
                         date: new Date().toISOString(),
-                        summary: decoded.docSummary,
-                        content: decoded.docContent,
+                        summary: normalizedSummary,
+                        content: normalizedContent,
                     });
                     node.docEntries = docEntries;
                     changes.push(`docEntries(v${nextVer.toFixed(1)})`);

package/package.json

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

package/templates/commands/pp/diagnose.md

@@ -1,82 +1,174 @@
-# 🔍 "Deep-Trace" Diagnostic Protocol (深层溯源诊断协议)
-
-核心理念：**先在宏观地图（图谱）上定位，再在微观战场（代码）上排查，绝不盲目翻看代码。**
-
----
-
-### 1.第一阶段：知识锚定 (Knowledge Anchoring) ⚓️
-🔹 **核心目标**：在动手之前，通过 PPDocs 明确“正确应该是什么样”。
-✏️ **动作**：
-*   **查询图谱**：输入问题关键词，提取标准业务逻辑。
-*   **建立基准**：以图谱中的描述作为“真理标准 (Truth)”。
-× **禁区**：
-*   禁止在未查询图谱前，直接跳入代码库阅读（防止陷入细节泥潭）。
-
-### 2.第二阶段：抽象映射 (Abstract Mapping) 🗺️
-🔹 **核心目标**：利用链式思维 (CoT)，绘制高层级逻辑流。
-✏️ **动作**：
-*   **绘制流程**：忽略实现细节，仅画出模块间的输入/输出流转（数据流）。
-*   **可视化**：生成 ASCII 或 Mermaid 流程图，展示当前链路。
-*   **标记疑点**：在流程图上圈出逻辑可能断裂的节点。
-
-### 3.第三阶段：靶点锁定 (Target Locking) 🎯
-🔹 **核心目标**：将问题范围从“整个项目”缩小到“单一节点”。
-✏️ **动作**：
-*   **定位区域**：确定问题具体发生在 PPDocs 的哪个 `Node`（节点）或 `Edge`（连线）上。
-*   **隔离上下文**：只关注该节点的前置依赖（Pre-requisites）和后置影响（Post-effects）。
-
-### 4.第四阶段：双层取证 (Dual-Layer Forensics) 🕵️
-🔹 **核心目标**：对比“理论（图谱）”与“现实（代码）”的差异。
-✏️ **动作**：
-*   **左眼看图谱**：阅读 PPDocs 中该节点的逻辑定义。
-*   **右眼看代码**：审查该节点对应的实际代码实现。
-*   **寻找裂痕**：
-    *   🔴 **代码错误 (Bug)**：图谱逻辑正确，代码实现错误。
-    *   🟠 **设计缺陷 (Design Flaw)**：代码符合图谱，但结果依然错误（图谱本身逻辑有误）。
-    *   🟡 **文档脱节 (Sync Issue)**：代码逻辑正确且有效，但图谱未记载（需同步）。
-
-### 5.第五阶段：分析结案 (Verdict) 📝
-🔹 **核心目标**：输出可执行的诊断报告。
-✏️ **动作**：
-*   输出标准化的**《问题诊断报告》**。
-*   **流转**：将报告作为输入，传递给 **[任务方案生成工作流]** 进行修复。
-
----
-
-### 📊 诊断逻辑可视化图解 (ASCII)
-
-```text
-       +-------------------------+
-       |   🚨 问题触发 (Issue)    |
-       +------------+------------+
-                    |
-                    v
-       +------------+------------+
-       |  ⚓️ 知识锚定 (PPDocs)   | <--- 获取标准逻辑 (Truth)
-       +------------+------------+
-                    |
-                    v
-           [ 🗺️ 抽象逻辑层 ]
-       +-------------------------+
-       |   Step1 -> Step2 ...    | (绘制链式流程)
-       |           |             |
-       |         [ ? ] <---------+--- 🎯 锁定可疑节点
-       +-----------+-------------+
-                   |
-                   v
-       +-----------+-------------+
-       |  🕵️ 双层取证 (Compare)   |
-       +-----+-------------+-----+
-             |             |
-       (📜 PPDocs) vs (💻 Code)
-             |             |
-             +------+------+
-                    |
-                    v
-            /-------+-------\
-           /    根本原因?    \
-          v                   v
-  +--------------+     +--------------+
-  | 🐛 代码 Bug   |     | 📐 设计/文档错 |
-  | (Fix Code)   |     | (Fix Graph)  |
-  +--------------+     +--------------+
+**角色**: Deep-Trace Diagnostician — 沿流程图逐层下探定位问题，而不是盲目翻代码
+
+核心理念：**先在宏观地图（流程图）上定位，再在微观战场（代码）上排查。**
+
+## 诊断宪法
+
+| 原则 | 要求 |
+|:---|:---|
+| **图谱先行** | 禁止在未查询图谱前直接跳入代码 |
+| **递归下探** | 从 main 逐层进入子图, 直到锁定叶子级嫌疑节点 |
+| **双层取证** | 必须同时对比图谱预期与代码现实, 分类裂痕 |
+| **数据驱动** | 用 code_impact 量化影响范围, 禁止凭感觉判断 |
+
+---
+
+## 标准流程
+
+### Phase 1: 知识锚定
+
+**1.1 建立全景**
+```
+kg_tree()                          → 知识全景图
+kg_flowchart(action:"get")         → 主图结构 (8个模块 + 连线)
+kg_rules(action:"get", ruleType:"errorAnalysis") → 错误分析规则
+```
+
+**1.2 关键词定位模块**
+```
+从问题描述提取关键词, 映射到主图节点:
+
+  "存储/读写/JSON"  → n_storage
+  "页面/组件/白屏"  → n_frontend
+  "MCP/工具/超时"   → n_mcp
+  "路由/API/请求"   → n_entry
+  "文档/搜索/节点"  → n_kg
+  "讨论/会议/协作"  → n_collab
+  "密码/权限/认证"  → n_auth
+  "扫描/符号/索引"  → n_analyzer
+
+无法定位 → 询问用户补充信息
+```
+
+### Phase 2: 递归下探
+
+**从定位到的主图节点开始, 逐层进入子图:**
+```
+Step 1: 主图节点详情
+  kg_flowchart(action:"get_node", nodeId:"n_定位模块", expand:2,
+    includeDoc:true, includeFiles:true)
+  → 节点文档 + 上下游连线 + 绑定文件
+
+Step 2: 进入子图
+  该节点有 subFlowchart?
+  ├─ YES → kg_flowchart(action:"get", chartId:"sub_xxx")
+  │        → 子图内所有节点和连线
+  │        → 根据问题特征, 缩小到子图内某个节点
+  │        → 该子节点还有子图? → 继续下探
+  └─ NO  → 已到代码根基, 进入 Phase 3
+
+Step 3: 输出疑点路径
+  main.n_storage
+    → sub_storage.n_graph_store
+      → sub_graph_store.n_search_docs
+        ← 嫌疑锁定
+```
+
+### Phase 3: 爆炸半径
+
+```
+code_smart_context(嫌疑符号名)
+  → 代码依赖 + 关联文档 + 匹配规则 + 影响范围摘要
+
+code_impact(嫌疑符号名)
+  → L1 直接引用 (必须检查)
+  → L2 间接引用 (建议检查)
+  → L3 传递引用 (注意)
+```
+
+**输出 ASCII 影响范围图**:
+```
+        ┌──────────┐
+        │ 嫌疑函数  │
+        └─────┬────┘
+   L1 直接 ───┤
+              ├→ 调用者A (文件路径)
+              ├→ 调用者B (文件路径)
+   L2 间接 ───┤
+              └→ 调用者C → 调用者D
+```
+
+→ 用户确认嫌疑范围后进入 Phase 4
+
+### Phase 4: 双层取证
+
+**左眼: 图谱真理 (预期行为)**
+```
+kg_flowchart(action:"get_node", nodeId:嫌疑节点,
+  includeDoc:true, fullDoc:true)
+  → 该节点文档中描述的预期逻辑
+```
+
+**右眼: 代码现实 (真实行为)**
+```
+code_context(嫌疑文件路径)    → 文件360°依赖关系
+Read(嫌疑文件)               → 实际源码
+```
+
+**对比分类裂痕**:
+```
+🔴 代码Bug:
+   图谱描述: "search_docs 应返回匹配文档数组"
+   代码实现: 返回了 undefined (缺少 return)
+   → 修复代码
+
+🟠 设计缺陷:
+   图谱描述: "按标题搜索"
+   代码实现: 确实按标题搜索
+   但实际需求: 应支持全文搜索 (图谱本身逻辑不完整)
+   → 修复图谱 + 代码
+
+🟡 文档脱节:
+   代码已添加了缓存逻辑, 运行正确
+   图谱中完全未记载此功能
+   → 同步图谱
+```
+
+### Phase 5: 诊断报告
+
+**5.1 报告结构**
+```
+## 诊断报告
+
+### 定位路径
+main.n_storage → sub_storage.n_graph_store → n_search_docs
+
+### 根因分类
+🔴 代码Bug / 🟠 设计缺陷 / 🟡 文档脱节
+
+### 数据流图
+[搜索请求] → [解析关键词] → [匹配文档] → [返回结果✗]
+                                            ↑ 此处缺少return
+
+### 详细分析
+| 环节 | 输入 | 预期输出 | 实际输出 | 判定 |
+|:---|:---|:---|:---|:---|
+| 解析关键词 | "auth" | ["auth"] | ["auth"] | ✅ |
+| 匹配文档 | ["auth"] | Doc[] | Doc[] | ✅ |
+| 返回结果 | Doc[] | Doc[] | undefined | ❌ |
+
+### 影响范围
+L1: 3个直接调用方受影响
+L2: 2个间接调用方可能受影响
+
+### 修复建议
+1. [具体修复方案]
+2. → 可传递给 /pp:execute 执行
+```
+
+---
+
+## 工具速查
+
+| 阶段 | 工具 | 用途 |
+|:---|:---|:---|
+| 锚定 | `kg_tree()` | 全景鸟瞰 |
+| 锚定 | `kg_flowchart(get)` | 主图结构 |
+| 锚定 | `kg_rules(get)` | 分析规则 |
+| 下探 | `kg_flowchart(get_node, expand:N)` | 节点详情+上下游 |
+| 下探 | `kg_flowchart(get, chartId:子图)` | 进入子图 |
+| 半径 | `code_smart_context(symbol)` | 全关联上下文 |
+| 半径 | `code_impact(symbol)` | 爆炸半径分析 |
+| 取证 | `code_context(file)` | 文件360°依赖 |
+| 取证 | `Read(file)` | 读取源码 |
+| 取证 | `code_path(symbolA, symbolB)` | 两点间调用链 |

package/templates/commands/pp/discuss.md

@@ -28,8 +28,8 @@ kg_discuss({ action: "read", id: "选中ID" })
 
 **并行执行**:
 1. 阅读讨论全部消息, 理解各方立场
-2. `kg_search` 检索相关知识节点, 获取本项目的标准逻辑
-3. `kg_get_rules(ruleType: "codeStyle")` 获取编码规范 (如涉及代码)
+2. `kg_flowchart(action:"get_node", nodeId:相关节点, expand:2)` 获取本项目的标准逻辑
+3. `kg_rules(action:"get", ruleType:"codeStyle")` 获取编码规范 (如涉及代码)
 
 ### Step 4: 分析与回复
 **分析框架**:
@@ -85,6 +85,6 @@ kg_discuss({
 ```
 
 **发起前检查**:
-1. `kg_search` 确认问题确实需要跨项目协商
-2. 明确参与方 (通过 `kg_projects` 查看可用项目)
+1. `kg_tree()` + `kg_flowchart(action:"get_node")` 确认问题确实需要跨项目协商
+2. 明确参与方 (通过 `kg_projects()` 查看可用项目)
 3. 内容包含: 背景、问题、本方方案、期望对方行动