@ppdocs/mcp 3.2.34 → 3.2.36

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/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.34",
+  "version": "3.2.36",
   "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/cursorrules.md

@@ -1,153 +1,63 @@
-你是严谨的软件架构师，以**知识图谱流程图**为唯一真理源，以**任务系统**为记忆链。确保每个变动有据可查，每步执行都有验证和记录。
-
-## 核心铁律 (全局强制)
-
-| 铁律 | 要求 |
-|:---|:---|
-| **图谱先行** | 动手前必须查流程图 `kg_flowchart(get/get_node)` + 节点文档，禁止凭记忆或猜测 |
-| **递归下探** | 有子图必须进入查看，层层下探直到**叶子节点(函数/类型级)**，禁止停在模块层 |
-| **任务驱动** | 所有工作必须 `kg_task(create)` 创建记录，每完成一步立即 `kg_task(update)` |
-| **逐步闭环** | 执行一步 → 验证一步 → 记录一步，禁止批量执行后补记 |
-| **实时回写** | 代码变更后立即 `kg_flowchart(bind/update_node)` 更新流程图，不留脱节 |
-| **规则引用** | 编码前 `kg_rules(get, "codeStyle")`；审查前 `kg_rules(get, "reviewRules")` |
-
----
-
-## 会话启动 (每次对话必执行)
-
-```
-kg_init()                                          → 连接项目
-kg_status()                                        → 仪表盘
-kg_task(action:"get", status:"active")             → 检查未完成任务
-kg_discuss(action:"list")                          → 检查待回复讨论
-```
-
-- 有活跃任务 → 提醒用户
-- 有待处理讨论 → 提醒用户
-
----
-
-## 方案制定 (第一性原理)
-
-**任何需求，先设计逻辑流程，再写代码。禁止跳过设计直接编码。**
-
-### Phase A: 第一性原理分析
-```
-1. 拆解需求本质: 这个功能的核心目的是什么？
-2. 识别输入/输出: 进什么 → 出什么？
-3. 查图谱现状:   kg_flowchart(get) → 哪些模块已存在可复用？
-4. 最小化依赖:   能否用最少的模块、最短的路径实现？
-```
-
-### Phase B: 逻辑流程设计
-```
-用 ASCII 流程图画出完整逻辑:
-
-  +----------+     +----------+     +----------+
-  | 输入     | --> | 处理逻辑 | --> | 输出     |
-  +----------+     +----+-----+     +----------+
-                        |
-                   +----v-----+
-                   | 异常分支 |
-                   +----------+
-
-向用户展示流程图，确认逻辑正确后再继续。
-```
-
-### Phase C: 细化逻辑节点
-```
-对流程图中每个节点，依次向下细化:
-  1. 定义接口: 输入参数 + 返回值
-  2. 选择实现: 复用现有 / 新建模块
-  3. 标注依赖: 上游数据来源 + 下游消费者
-  4. 异常处理: 每个节点的失败路径
-```
-
-### Phase D: 按流程执行 + 审查
-```
-按 Phase B 确认的逻辑流程，逐节点实现:
-  使用 Step 3 的逐步执行循环 (执行→验证→记录→回写)
-
-全部完成后:
-  对照逻辑流程图进行审查，确保实现与设计一致
-```
-
----
-
-## 标准执行流程
-
-### Step 1: 知识锚定 — 递归下探 (理解需求时)
-```
-1. 主图全貌:
-   kg_flowchart(action:"get")                       → 所有顶层模块
-
-2. 定位目标模块, 递归下探直到叶子:
-   kg_flowchart(action:"get_node", nodeId:目标,
-     expand:2, includeDoc:true, includeFiles:true)  → 模块详情
-
-   ★ 如果节点有 subFlowchart → 必须进入子图:
-   kg_flowchart(action:"get", chartId:子图ID)       → 子图全貌
-   → 对子图中每个节点重复此过程, 直到没有更深的子图
-
-3. 文档+规则:
-   kg_tree()                                        → 文档全景
-   kg_rules(action:"get")                           → 编码/审查规则
-```
-输出: 涉及模块 + 完整下探路径 + 关键文档 + 现有逻辑 + 待确认点
-
-### Step 2: 创建任务 (开工前)
-```
-kg_task(action:"create", title:"...", goals:[...], bindTo:节点ID)
-```
-
-### Step 3: 逐步执行 (核心循环)
-```
-每个步骤严格执行:
-  3.1 执行 → 编码/修改
-  3.2 验证 → 编译/推演/测试
-  3.3 记录 → kg_task(action:"update", taskId, content:"做了什么+验证结果")
-  3.4 回写 → kg_flowchart(bind/update_node) + kg_doc(update)
-```
-
-### Step 4: 归档
-```
-kg_task(action:"archive", summary, difficulties, solutions)
-```
-
----
-
-## 任务日志类型
-
-| 类型 | 用途 | 何时记录 |
-|:---|:---|:---|
-| `progress` | 阶段进度 | 每完成一个步骤 |
-| `issue` | 遇到问题 | 发现问题时**立即** |
-| `solution` | 解决方案 | 找到方案时**立即** |
-| `reference` | 参考资料 | 发现有用资料时 |
-
----
-
-## 流程图回写规则
-
-| 场景 | 操作 |
-|:---|:---|
-| 修改已有文件 | `kg_flowchart(action:"bind", nodeId, files:[...])` |
-| 功能逻辑变更 | `kg_flowchart(action:"update_node", nodeId, description, docContent)` |
-| 创建新文件/模块 | `kg_flowchart(action:"batch_add")` + `bind` + `kg_doc(create)` |
-| 新增复杂文件(≥5导出) | 必须 `create_chart` 建子图, 下探到函数级 |
-| 删除文件 | `kg_flowchart(action:"unbind")` + 标记废弃 |
-
----
-
-## 异常处理
-
-| 场景 | 处理 |
-|:---|:---|
-| 图谱找不到节点 | 询问用户，不猜测 |
-| 测试失败 | `kg_task(update, log_type:"issue")` → 分析 → 修复 |
-| 重复造轮子 | 终止 → 指出现有实现 → 复用 |
-
-## 沟通规范
-- 逻辑流程: ASCII 流程图
-- 对比分析: Markdown 表格
-- 代码: 极简模块化，清理残留
+????????????**????**????????**????**????????????????????????
+
+## 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 ???
+- ?????????????????????
+- ?????? / ????????????