@ppdocs/mcp 3.2.35 → 3.2.37

package/dist/tools/index.d.ts

@@ -1,10 +1,10 @@
 /**
  * MCP 工具注册入口
- * 14 个工具, 7 个子模块
+ * 12 个工具, 6 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
- * 📊 导航:     kg_status, kg_tree                                (2个)
- * 📚 知识:     kg_doc(参考文档), kg_projects, kg_rules            (3个)
+ * 📊 导航:     kg_status                                         (1个)
+ * 📚 知识:     kg_projects, kg_rules                              (2个)
  * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区)     (3个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)

package/dist/tools/index.js

@@ -1,10 +1,10 @@
 /**
  * MCP 工具注册入口
- * 14 个工具, 7 个子模块
+ * 12 个工具, 6 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
- * 📊 导航:     kg_status, kg_tree                                (2个)
- * 📚 知识:     kg_doc(参考文档), kg_projects, kg_rules            (3个)
+ * 📊 导航:     kg_status                                         (1个)
+ * 📚 知识:     kg_projects, kg_rules                              (2个)
  * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区)     (3个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)
@@ -13,7 +13,6 @@
 import { createContext } from './shared.js';
 import { registerInitTool } from './init.js';
 import { registerStatusTool } from './kg_status.js';
-import { registerDocTools } from './docs.js';
 import { registerProjectTools } from './projects.js';
 import { registerRuleTools } from './rules.js';
 import { registerTaskTools } from './tasks.js';
@@ -23,24 +22,22 @@ import { registerAnalyzerTools } from './analyzer.js';
 import { registerMeetingTools } from './meeting.js';
 import { registerFlowchartTools } from './flowchart.js';
 export function registerTools(server, projectId, user, onProjectChange) {
-    // 创建共享可变上下文 — 所有工具捕获此对象引用
     const ctx = createContext(projectId, user);
-    // 🔗 初始化 (kg_init — 运行时项目切换，更新 ctx)
+    // 🔗 初始化
     registerInitTool(server, ctx, onProjectChange || (() => { }));
-    // 📊 导航 (kg_status + kg_tree在docs中)
+    // 📊 导航
     registerStatusTool(server, ctx);
-    // 📚 知识 (kg_doc + kg_tree + kg_projects + kg_rules)
-    registerDocTools(server, ctx);
+    // 📚 知识
     registerProjectTools(server, ctx);
     registerRuleTools(server, ctx);
-    // 📝 工作流 (kg_task + kg_files + kg_discuss)
+    // 📝 工作流
     registerTaskTools(server, ctx);
     registerFileTools(server);
     registerDiscussionTools(server, ctx);
-    // 🔬 代码分析 (code_scan, code_smart_context, code_full_path)
+    // 🔬 代码分析
     registerAnalyzerTools(server, ctx);
-    // 🏛️ 多AI协作 (kg_meeting)
+    // 🏛️ 多AI协作
     registerMeetingTools(server, ctx);
-    // 🔀 流程图 (kg_flowchart)
+    // 🔀 流程图
     registerFlowchartTools(server, ctx);
 }

package/dist/tools/kg_status.d.ts

@@ -1,5 +1,5 @@
 /**
- * 📊 kg_status — 项目速览仪表盘 (新增)
+ * 📊 kg_status — 项目速览仪表盘
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';

package/dist/tools/kg_status.js

@@ -1,36 +1,22 @@
 /**
- * 📊 kg_status — 项目速览仪表盘 (新增)
+ * 📊 kg_status — 项目速览仪表盘
  */
 import { getClient } from '../storage/httpClient.js';
 import { wrap, safeTool } from './shared.js';
 export function registerStatusTool(server, ctx) {
     const client = () => getClient();
-    server.tool('kg_status', '📊 项目速览仪表盘 — 一键了解项目健康。返回: 文档总数、目录数、活跃任务数、最近变更。每次对话开始建议首先调用', {}, async () => safeTool(async () => {
-        const [docs, activeTasks] = await Promise.all([
-            client().listDocs(),
+    server.tool('kg_status', '📊 项目速览仪表盘 — 一键了解项目健康。返回: 流程图节点数、活跃任务数、最近变更。每次对话开始建议首先调用', {}, async () => safeTool(async () => {
+        const [charts, activeTasks] = await Promise.all([
+            client().listFlowcharts(),
             client().listTasks('active'),
         ]);
-        const dirCount = docs.filter(d => d.isDir).length;
-        const docCount = docs.filter(d => !d.isDir).length;
-        const statusMap = new Map();
-        for (const d of docs) {
-            if (d.isDir)
-                continue;
-            const s = d.status || '已完成';
-            statusMap.set(s, (statusMap.get(s) || 0) + 1);
-        }
+        const nodeCount = charts.reduce((sum, c) => sum + (c.nodeCount || 0), 0);
         const lines = [
             `📊 项目速览 [${ctx.projectId}]`,
             ``,
-            `📄 文档: ${docCount} 个 | 📁 目录: ${dirCount} 个`,
+            `🔀 流程图: ${charts.length} 张 | 📦 节点: ${nodeCount} 个`,
             `📝 活跃任务: ${activeTasks.length} 个`,
         ];
-        if (statusMap.size > 0) {
-            const statusLine = Array.from(statusMap.entries())
-                .map(([s, c]) => `${s}(${c})`)
-                .join(' | ');
-            lines.push(`📋 状态分布: ${statusLine}`);
-        }
         if (activeTasks.length > 0) {
             lines.push(``, `🔧 进行中的任务:`);
             for (const t of activeTasks.slice(0, 5)) {

package/dist/tools/projects.d.ts

@@ -1,7 +1,6 @@
 /**
- * 📋 kg_projects (3→1)
- * 合并: kg_list_projects, kg_update_root → kg_doc 处理
- * 删除: kg_create_project (桌面端操作)
+ * 📋 kg_projects
+ * 列出所有可访问的项目(返回名称和ID)
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';

package/dist/tools/projects.js

@@ -1,7 +1,6 @@
 /**
- * 📋 kg_projects (3→1)
- * 合并: kg_list_projects, kg_update_root → kg_doc 处理
- * 删除: kg_create_project (桌面端操作)
+ * 📋 kg_projects
+ * 列出所有可访问的项目(返回名称和ID)
  */
 import { getClient } from '../storage/httpClient.js';
 import { wrap, safeTool } from './shared.js';

package/dist/tools/rules.d.ts

@@ -1,7 +1,6 @@
 /**
- * 📏 kg_rules (6→1)
- * 合并: kg_get_rules, kg_save_rules, kg_get_rules_meta, kg_save_rules_meta
- * 删除: kg_get_global_rules_meta, kg_save_global_rules_meta (管理员操作)
+ * 📏 kg_rules
+ * 统一规则入口: get | save | get_meta | save_meta | delete
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';

package/dist/tools/rules.js

@@ -1,7 +1,6 @@
 /**
- * 📏 kg_rules (6→1)
- * 合并: kg_get_rules, kg_save_rules, kg_get_rules_meta, kg_save_rules_meta
- * 删除: kg_get_global_rules_meta, kg_save_global_rules_meta (管理员操作)
+ * 📏 kg_rules
+ * 统一规则入口: get | save | get_meta | save_meta | delete
  */
 import { z } from 'zod';
 import { getClient } from '../storage/httpClient.js';

package/dist/tools/shared.d.ts

@@ -2,7 +2,6 @@
  * MCP 工具共享模块
  * 合并原 helpers.ts + 新增 safeTool / withCross 模式
  */
-import type { DocData } from '../storage/types.js';
 /** 运行时可变上下文 — 所有工具通过引用获取最新值 */
 export interface McpContext {
     projectId: string;
@@ -18,15 +17,4 @@ export declare function wrap(text: string): {
 };
 export declare function safeTool(fn: () => Promise<ReturnType<typeof wrap>>): Promise<ReturnType<typeof wrap>>;
 export declare function crossPrefix(target: string): string;
-export declare function formatDocMarkdown(doc: DocData, path: string): string[];
-interface TreeNode {
-    path: string;
-    name: string;
-    summary?: string;
-    isDir: boolean;
-    children?: TreeNode[];
-}
-export declare function formatTreeText(tree: TreeNode[]): string;
-export declare function countTreeDocs(tree: TreeNode[]): number;
 export declare function formatFileSize(bytes: number): string;
-export {};

package/dist/tools/shared.js

@@ -23,65 +23,6 @@ export async function safeTool(fn) {
 export function crossPrefix(target) {
     return `[跨项目: ${target}]\n\n`;
 }
-// ==================== 文档格式化 ====================
-export function formatDocMarkdown(doc, path) {
-    const lines = [];
-    const name = path.split('/').pop() || path;
-    lines.push(`## ${name}\n`);
-    if (doc.summary)
-        lines.push(`> ${doc.summary}\n`);
-    if (doc.content) {
-        lines.push('**内容**');
-        lines.push(doc.content);
-        lines.push('');
-    }
-    if (doc.versions && doc.versions.length > 0) {
-        lines.push('**更新历史**');
-        lines.push('| 版本 | 日期 | 变更 |');
-        lines.push('|:---|:---|:---|');
-        doc.versions.forEach((v) => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
-        lines.push('');
-    }
-    if (doc.bugfixes && doc.bugfixes.length > 0) {
-        lines.push('**修复历史**');
-        lines.push('| 日期 | 问题 | 方案 |');
-        lines.push('|:---|:---|:---|');
-        doc.bugfixes.forEach((b) => lines.push(`| ${b.date} | ${b.issue} | ${b.solution} |`));
-        lines.push('');
-    }
-    return lines;
-}
-export function formatTreeText(tree) {
-    function format(nodes, prefix = '') {
-        const lines = [];
-        nodes.forEach((node, index) => {
-            const isLast = index === nodes.length - 1;
-            const connector = isLast ? '└── ' : '├── ';
-            const childPrefix = isLast ? '    ' : '│   ';
-            const icon = node.isDir ? '📁' : '📄';
-            const summary = node.summary ? ` # ${node.summary}` : '';
-            lines.push(`${prefix}${connector}${icon} ${node.name}${summary}`);
-            if (node.children && node.children.length > 0) {
-                lines.push(...format(node.children, prefix + childPrefix));
-            }
-        });
-        return lines;
-    }
-    return format(tree).join('\n');
-}
-export function countTreeDocs(tree) {
-    let count = 0;
-    function traverse(nodes) {
-        for (const node of nodes) {
-            if (!node.isDir)
-                count++;
-            if (node.children)
-                traverse(node.children);
-        }
-    }
-    traverse(tree);
-    return count;
-}
 // ==================== 文件大小格式化 ====================
 export function formatFileSize(bytes) {
     if (bytes < 1024)

package/package.json

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

package/templates/AGENT.md

@@ -1,38 +1,63 @@
-# ppdocs Knowledge Graph Agent
-
-你是严谨的软件架构师，以**知识图谱流程图**为唯一真理源，以**任务系统**为记忆链。确保每个变动有据可查，每步执行都有验证和记录。
-
-## 核心铁律
-
-| 铁律 | 要求 |
-|:---|:---|
-| **图谱先行** | 动手前必须查流程图 `kg_flowchart(get/get_node)` + 节点文档 |
-| **任务驱动** | 所有工作必须 `kg_task(create)` 创建，每步 `kg_task(update)` 记录 |
-| **逐步闭环** | 执行一步 → 验证一步 → 记录一步 |
-| **实时回写** | 代码变更后立即 `kg_flowchart(bind/update_node)` 更新流程图 |
-
-## 会话启动
-
-```
-kg_init() → kg_status() → kg_task(get, status:"active") → kg_discuss(list)
-```
-
-## 执行流程
-
-1. **知识锚定**: `kg_flowchart(get)` → `get_node(expand:2)` → `kg_tree()` → `kg_rules(get)`
-2. **创建任务**: `kg_task(create, title, goals, bindTo)`
-3. **逐步执行**: 执行 → 验证 → `kg_task(update)` → `kg_flowchart(bind/update_node)`
-4. **归档**: `kg_task(archive, summary, difficulties, solutions)`
-
-## 工作流
-
-| 命令 | 用途 |
-|:---|:---|
-| `/pp-task` | 知识驱动任务协议 |
-| `/pp-init` | 初始化项目知识图谱 |
-| `/pp-sync` | 代码↔知识图谱同步 |
-| `/pp-diagnose` | 深度问题诊断 |
-| `/pp-execute` | 任务极简执行 |
-| `/pp-shencha` | 代码质量审查 |
-| `/pp-audit` | 多Agent严格审计 |
-| `/pp-discuss` | 讨论响应与协作 |
+????????????**????**????????**????**????????????????????????
+
+## 0. ????
+
+```text
+kg_init()                 -> ????
+kg_status()               -> ???????
+kg_task(action:"get")     -> ?? active ??
+kg_discuss(action:"list") -> ???????
+```
+
+## 1. ????????
+
+- ??: `kg_flowchart(action:"list|get|get_node|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart")`
+- ??: `kg_rules(action:"get|save|get_meta|save_meta")`
+- ??: `kg_task(action:"create|get|update|archive|delete")`
+- ??: `kg_files(action:"list|read|upload|download|public_*")`
+- ??/??: `kg_discuss(...)`, `kg_meeting(...)`
+- ????: `code_scan()`, `code_smart_context(symbolName)`, `code_full_path(symbolA, symbolB)`
+- ????: ?????????????????????????????? fallback????????????
+
+## 2. ?????
+
+### Step 1: ????
+1. ?? `kg_flowchart(get)` ????????? `kg_rules(get)` ?????
+2. ???????? `kg_flowchart(get_node, expand:2, includeDoc:true, includeFiles:true)`?
+3. ????? `subFlowchart`???????????????
+4. ??????????? `code_scan()`??? `code_smart_context` / `code_full_path`?
+5. ??????????????????????????
+
+### Step 2: ????
+1. ?????: `kg_task(create, title, goals, bindTo)`?
+2. ??? ASCII ????????????????
+3. ?????????????
+
+### Step 3: ????
+1. ????????????????
+2. ?????????????? `kg_task(update, log_type:"progress")` ???????
+3. ?????? `issue`??????? `solution`????????
+
+### Step 4: ????
+| ?? | ???? |
+|:---|:---|
+| ?????? | `kg_flowchart(bind, nodeId, files:[...])` |
+| ???? | `kg_flowchart(update_node, nodeId, description, docSummary, docContent)` |
+| ?????? | `kg_flowchart(batch_add)` + `bind` + `update_node(docSummary, docContent)` |
+| ?????? | `kg_flowchart(create_chart)`???????????? |
+| ??/???? | ?? `kg_files(upload/read/list/download)` ??????? `kg_flowchart(bind, files:[...])` |
+| ???? | ?? `kg_flowchart(update_node, docSummary, docContent)` ??? `docEntries` |
+
+## 3. ????
+
+- ?????????? -> ??????????
+- ???????/???? -> ??????????????????
+- ??????????????????JSON?????? fallback ???
+- ???? -> ??????????
+
+## 4. ????
+
+- ??????? ASCII ????
+- ???????? Markdown ???
+- ?????????????????????
+- ?????? / ????????????

package/templates/commands/init.md

@@ -4,7 +4,7 @@ description: 初始化知识图谱：100%扫描代码库，为每个模块创建
 
 # /init 项目初始化
 
-执行 `task_create("项目初始化: [项目名]")` → 递归扫描全部代码文件 → 逐文件审查创建节点 → 每处理5个文件调用 `task_add_log(progress)` 同步进度 → 全部完成后 `task_complete` 输出统计报告
+执行 `kg_task(action:"create", title:"项目初始化: [项目名]")` → 递归扫描全部代码文件 → 逐文件审查创建节点 → 每处理5个文件调用 `kg_task(action:"update", log_type:"progress")` 同步进度 → 全部完成后 `kg_task(action:"archive")` 输出统计报告
 
 ## 扫描规则
 
@@ -84,11 +84,11 @@ flowchart TB
 
 ## 进度同步
 
-每处理5个文件或完成1个目录后，调用 `task_add_log("progress", "已处理: [文件列表], 创建节点: N个")`
+每处理5个文件或完成1个目录后，调用 `kg_task(action:"update", log_type:"progress", content:"已处理: [文件列表], 创建节点: N个")`
 
 ## 完成输出
 
-`task_complete` 时输出完整统计：
+`kg_task(action:"archive")` 时输出完整统计：
 
 ```markdown
 | 统计项 | 数量 |

package/templates/commands/pp/diagnose.md

@@ -19,8 +19,8 @@
 
 **1.1 建立全景**
 ```
-kg_tree()                          → 知识全景图
-kg_flowchart(action:"get")         → 主图结构 (8个模块 + 连线)
+kg_flowchart(action:"list")        → 知识图谱列表
+kg_flowchart(action:"get")         → 主图结构 (模块 + 连线)
 kg_rules(action:"get", ruleType:"errorAnalysis") → 错误分析规则
 ```
 
@@ -162,7 +162,7 @@ L2: 2个间接调用方可能受影响
 
 | 阶段 | 工具 | 用途 |
 |:---|:---|:---|
-| 锚定 | `kg_tree()` | 全景鸟瞰 |
+| 锚定 | `kg_flowchart(list/get)` | 全景鸟瞰 |
 | 锚定 | `kg_flowchart(get)` | 主图结构 |
 | 锚定 | `kg_rules(get)` | 分析规则 |
 | 下探 | `kg_flowchart(get_node, expand:N)` | 节点详情+上下游 |

package/templates/commands/pp/init.md

@@ -27,10 +27,10 @@
 
 ### Phase 0: 环境准备
 ```
-kg_init()              → 连接项目上下文
-kg_status()            → 查看仪表盘 (文档数/任务数/状态)
-kg_tree()              → 已有知识全景图
-kg_flowchart(action:"list")  → 已有流程图列表
+kg_init()                   → 连接项目上下文
+kg_status()                 → 查看仪表盘 (流程图/任务/状态)
+kg_flowchart(action:"list") → 已有流程图列表
+kg_flowchart(action:"get")  → 主图结构总览
 ```
 如果已有图谱 → 提示用户选择: 增量补充 or 重建
 
@@ -125,27 +125,18 @@ kg_flowchart(action:"bind", nodeId:"n_graph_store",
   dirs:["src-tauri/src/storage/"])
 ```
 
-**3.2 创建参考文档 (遵循5分类规范)**
+**3.2 写入节点内置文档 (`docEntries`)**
 ```
-文档分类:
-  /模块/后端/存储层      → 对应 n_storage
-  /模块/后端/graph_store → 对应 n_graph_store
-  /模块/前端/FlowchartView → 对应 n_flowchart_view
-  /架构/事件驱动         → 对应架构决策
-  /功能/知识图谱编辑      → 对应用户功能
-
-kg_doc(action:"create",
-  path:"/模块/后端/graph_store",
-  summary:"项目/文档/规则/搜索的核心存储, JSON持久化",
-  content:"## 职责\n...\n## 公开API\n...\n## 文件路径\n...",
-  bindTo:"n_graph_store")
+kg_flowchart(action:"update_node", chartId:"sub_storage", nodeId:"n_graph_store",
+  docSummary:"项目/规则/流程图数据持久化核心",
+  docContent:"## 职责\n...\n## 公开 API\n...\n## 文件路径\n- src-tauri/src/storage/graph_store.rs")
 ```
 
 ### Phase 4: 健康验证
 ```
 kg_flowchart(action:"orphans")    → 孤立节点 (应为0)
 kg_flowchart(action:"health")     → 冷热分布
-kg_tree()                         → 全景确认文档覆盖
+kg_flowchart(action:"get")        → 全景确认节点覆盖与连线
 kg_status()                       → 最终仪表盘
 ```
 

package/templates/commands/pp/sync.md

@@ -7,7 +7,7 @@
 | **代码即真理** | 代码与图谱冲突时以 Git 状态为准, 强制覆写 |
 | **层级感知** | 变更定位到具体子图层级, 逐层向上验证影响链 |
 | **最小变更** | 只更新有差异的节点/文档, 不做无意义的全量覆写 |
-| **创建即关联** | 新增节点必须 bind 源码 + 创建/关联文档, 无孤立资产 |
+| **创建即关联** | 新增节点必须 bind 源码 + 写入节点文档, 无孤立资产 |
 
 ---
 
@@ -30,9 +30,9 @@
 **1.1 获取图谱现状**
 ```
 kg_init()                        → 确保项目连接
-kg_tree()                        → 文档全景
 kg_flowchart(action:"list")      → 所有流程图
 kg_flowchart(action:"get")       → 主图节点+连线
+kg_flowchart(action:"search", query:"关键词") → 快速定位相关节点
 ```
 
 **1.2 获取代码变更**
@@ -106,12 +106,10 @@ all 模式:
 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")
+4. 写入节点文档:
+   kg_flowchart(action:"update_node", chartId:目标子图, nodeId:"n_xxx",
+     docSummary:"一句话职责",
+     docContent:"## 职责\n...\n## 公开API\n...\n## 文件路径\n...")
 ```
 
 **3.2 处理 [MOD] — 更新节点**
@@ -126,8 +124,9 @@ all 模式:
      docSummary:"更新后的摘要")
 
 3. 追加版本记录:
-   kg_doc(action:"update", path:"/模块/.../xxx",
-     versions:[{version:当前+0.1, date:"ISO日期", changes:"变更摘要"}])
+   kg_flowchart(action:"update_node", chartId:目标子图, nodeId:"n_xxx",
+     docSummary:"本次变更摘要",
+     docContent:"更新后的详细文档")
 
 4. 检查连线是否需要更新:
    code_context(filePath) → 新的import列表
@@ -142,7 +141,6 @@ all 模式:
 
 选项B - 彻底删除:
   kg_flowchart(action:"delete_node", nodeId:"n_xxx")
-  kg_doc(action:"delete", path:"/模块/.../xxx")
 ```
 
 **3.4 处理 [DRIFT] — 路径漂移**
@@ -177,7 +175,7 @@ kg_task(action:"update", taskId:"当前任务", log_type:"progress",
 ```
 kg_flowchart(action:"orphans")     → 全局孤立节点 (应为0)
 kg_flowchart(action:"health")      → 冷热分布
-kg_tree()                          → 文档覆盖确认
+kg_flowchart(action:"get")         → 节点覆盖确认
 ```
 
 ### Phase 5: 交付报告