@ppdocs/mcp 3.2.36 → 3.2.38

package/README.md

@@ -8,6 +8,8 @@
 
 ppdocs MCP 是一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，让 Claude 能够在对话中构建和查询项目知识图谱。
 
+当前 MCP 采用 `flowchart-first` 模型：节点、关系、绑定文件、任务关联和节点文档统一收敛到 `kg_flowchart(action:"...")`，不再维护独立的 `kg_doc` / `kg_search` / `kg_create_node` 一组旧接口。
+
 ```
 ┌─────────────┐     MCP      ┌─────────────┐    HTTP    ┌─────────────┐
 │  Claude AI  │ ──────────── │ @ppdocs/mcp │ ────────── │ ppdocs 桌面 │
@@ -105,28 +107,55 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ## 工具列表
 
-### 知识图谱工具
+### 核心工具
 
 | 工具 | 说明 |
 |------|------|
-| `kg_create_node` | 创建知识节点 |
-| `kg_update_node` | 更新节点内容 |
-| `kg_delete_node` | 删除节点 |
-| `kg_lock_node` | 锁定节点 (AI 只能锁定，解锁需前端手动) |
-| `kg_list_nodes` | 列出节点 (支持 status/edges 过滤，maxEdges=0 查孤立节点) |
-| `kg_search` | 关键词搜索 |
-| `kg_find_path` | 查找依赖路径 |
-| `kg_get_relations` | 获取节点关系 |
+| `kg_init` | 初始化项目连接与上下文 |
+| `kg_status` | 查看项目仪表盘与流程图概况 |
+| `kg_flowchart` | 统一的知识图谱入口，负责查询、更新、关系分析 |
+| `kg_workflow` | Markdown 文档工作流管理 |
+| `kg_task` | 任务管理 |
+| `kg_files` | 项目文件读写/上传下载 |
+| `kg_discuss` | 讨论区 |
+| `kg_meeting` | 多 AI 协作会议 |
+| `code_scan` | 代码扫描 |
+| `code_smart_context` | 获取符号的智能上下文 |
+| `code_full_path` | 获取两个符号之间的全路径 |
+
+### `kg_flowchart` actions
+
+| action | 说明 |
+|------|------|
+| `list` | 列出所有流程图 |
+| `get` | 获取指定流程图的节点与连线 |
+| `search` | 按关键词搜索节点、节点文档与绑定资源 |
+| `get_relations` | 查看某节点的入边/出边关系 |
+| `find_path` | 查找两个节点之间的有向路径 |
+| `get_node` | 获取节点详情、关联层级、绑定资源与文档 |
+| `update_node` | 更新节点信息并追加节点文档版本 |
+| `delete_node` | 删除节点 |
+| `batch_add` | 批量新增节点与连线 |
+| `bind` / `unbind` | 绑定或解绑文件、目录、文档、任务 |
+| `orphans` | 检查孤立参考文档 |
+| `health` | 查看节点健康度 |
+| `create_chart` | 创建子图并绑定到父节点 |
+| `delete_chart` | 删除子图 |
+
+### 常用示例
 
-### 任务管理工具
+```bash
+# 搜索相关节点
+kg_flowchart(action:"search", query:"flowchart storage")
 
-| 工具 | 说明 |
-|------|------|
-| `task_create` | 创建开发任务 |
-| `task_list` | 列出任务 |
-| `task_get` | 获取任务详情 |
-| `task_add_log` | 添加进度日志 |
-| `task_complete` | 完成任务并归档 |
+# 查看节点详情
+kg_flowchart(action:"get_node", chartId:"main", nodeId:"n_storage", expand:2, includeDoc:true, includeFiles:true)
+
+# 追加节点文档
+kg_flowchart(action:"update_node", chartId:"main", nodeId:"n_storage",
+  docSummary:"补充存储层职责",
+  docContent:"## 职责\n...\n## 关键流程\n...")
+```
 
 ---
 
@@ -178,18 +207,15 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ## 更新日志
 
-### v2.6.9
-- ✨ `kg_list_nodes` 支持 status/minEdges/maxEdges 过滤
-- 🗑️ 移除 `kg_find_orphans` (用 `kg_list_nodes(maxEdges: 0)` 替代)
+### v3.2.36
+- 统一为 `flowchart-first` MCP 接口模型
+- `kg_flowchart` 新增 `search` / `get_relations` / `find_path`
+- 文档与模板改为使用 `kg_flowchart(action:"...")`，不再引用旧 `kg_doc` / `kg_search` 等独立接口
 
 ### v2.5.0
-- ✨ 新增 CLI init 命令，自动安装工作流模板
-- ✨ 支持 Codex 模式 (--codex)
-- 📦 构建时自动复制模板
-
-### v2.4.0
-- 🛡️ `kg_lock_node` 只能锁定，解锁需前端手动操作
-- ⚡ 后端自动记录操作日志
+- 新增 CLI init 命令，自动安装工作流模板
+- 支持 Codex 模式 (`--codex`)
+- 构建时自动复制模板
 
 ### v2.3.0
 - 新增任务管理功能

package/dist/cli.js

@@ -392,11 +392,12 @@ function generateMcpPermissions() {
         'kg_status',
         // 知识管理
         'kg_projects',
-        'kg_rules',
+        'kg_workflow',
         // 工作流
         'kg_task',
         'kg_files',
         'kg_discuss',
+        'kg_ref',
         // 流程图
         'kg_flowchart',
         // 协作

package/dist/storage/httpClient.d.ts

@@ -4,19 +4,31 @@
  *
  * API URL 格式: http://localhost:20099/api/:projectId/:password/...
  */
-import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, RuleMeta } from './types.js';
+import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, WorkflowSummary, WorkflowDoc, WorkflowSelector, Reference } from './types.js';
 export declare class PpdocsApiClient {
     private baseUrl;
     private serverUrl;
     constructor(apiUrl: string);
     private request;
-    getRulesApi(ruleType: string): Promise<string[]>;
-    saveRulesApi(ruleType: string, rules: string[]): Promise<boolean>;
-    getRulesMeta(): Promise<Record<string, RuleMeta>>;
-    saveRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
-    crossGetRulesMeta(target: string): Promise<Record<string, RuleMeta>>;
-    getGlobalRulesMeta(): Promise<Record<string, RuleMeta>>;
-    saveGlobalRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
+    listWorkflows(scope?: 'all' | 'global' | 'project'): Promise<WorkflowSummary[]>;
+    getWorkflow(workflowId: string, scope?: 'all' | 'global' | 'project'): Promise<WorkflowDoc | null>;
+    getWorkflowBatch(selectors: WorkflowSelector[]): Promise<WorkflowDoc[]>;
+    saveWorkflow(workflowId: string, input: {
+        scope: 'global' | 'project';
+        title: string;
+        description: string;
+        system: string;
+        keywords: string[];
+        minHits: number;
+        always: boolean;
+        content: string;
+    }): Promise<WorkflowDoc>;
+    deleteWorkflow(workflowId: string, scope: 'global' | 'project'): Promise<boolean>;
+    listReferences(): Promise<Reference[]>;
+    getReference(refId: string): Promise<Reference | null>;
+    saveReference(reference: Reference): Promise<boolean>;
+    deleteReference(refId: string): Promise<boolean>;
+    readReferenceFile(path: string): Promise<string>;
     listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
     getTask(taskId: string, mode?: 'smart' | 'full'): Promise<Task | null>;
     createTask(task: {
@@ -46,8 +58,6 @@ export declare class PpdocsApiClient {
         description: string;
         updatedAt: string;
     }[]>;
-    /** 跨项目: 获取规则 */
-    crossGetRules(target: string, ruleType: string): Promise<string[]>;
     /** 列出项目文件 */
     listFiles(dir?: string): Promise<FileInfo[]>;
     /** 读取项目文件 */
@@ -95,6 +105,10 @@ export declare class PpdocsApiClient {
     discussionReply(id: string, sender: string, content: string, msgSummary?: string, newSummary?: string): Promise<boolean>;
     /** 完成讨论 (公开路由, 标记为 completed) */
     discussionComplete(id: string): Promise<boolean>;
+    /** 归档关闭讨论 (需项目认证) */
+    discussionClose(id: string, conclusion: string): Promise<{
+        archived_path?: string;
+    }>;
     /** 删除讨论 (公开路由) */
     discussionDelete(id: string): Promise<boolean>;
     /** 列出公共文件 */

package/dist/storage/httpClient.js

@@ -99,75 +99,64 @@ export class PpdocsApiClient {
             clearTimeout(timeout);
         }
     }
-    // ============ 规则 API ============
-    async getRulesApi(ruleType) {
-        try {
-            return await this.request(`/rules/${ruleType}`);
-        }
-        catch {
-            return [];
-        }
+    // ============ 工作流 API ============
+    async listWorkflows(scope) {
+        const query = scope ? `?scope=${scope}` : '';
+        return this.request(`/workflows${query}`);
     }
-    async saveRulesApi(ruleType, rules) {
+    async getWorkflow(workflowId, scope) {
         try {
-            await this.request(`/rules/${ruleType}`, {
-                method: 'PUT',
-                body: JSON.stringify(rules)
-            });
-            return true;
+            const query = scope ? `?scope=${scope}` : '';
+            return await this.request(`/workflows/${encodeURIComponent(workflowId)}${query}`);
         }
         catch {
-            return false;
+            return null;
         }
     }
-    async getRulesMeta() {
-        try {
-            return await this.request('/rules-meta');
-        }
-        catch {
-            return {};
-        }
+    async getWorkflowBatch(selectors) {
+        return this.request('/workflows/batch', {
+            method: 'POST',
+            body: JSON.stringify(selectors),
+        });
     }
-    async saveRulesMeta(meta) {
-        try {
-            await this.request('/rules-meta', {
-                method: 'PUT',
-                body: JSON.stringify(meta)
-            });
-            return true;
-        }
-        catch {
-            return false;
-        }
+    async saveWorkflow(workflowId, input) {
+        return this.request(`/workflows/${encodeURIComponent(workflowId)}`, {
+            method: 'PUT',
+            body: JSON.stringify(input),
+        });
     }
-    async crossGetRulesMeta(target) {
-        try {
-            return await this.request(`/cross/${encodeURIComponent(target)}/rules-meta`);
-        }
-        catch {
-            return {};
-        }
+    async deleteWorkflow(workflowId, scope) {
+        return this.request(`/workflows/${encodeURIComponent(workflowId)}?scope=${scope}`, {
+            method: 'DELETE',
+        });
     }
-    async getGlobalRulesMeta() {
-        try {
-            return await this.request('/global-rules-meta');
-        }
-        catch {
-            return {};
-        }
+    // ============ 外部参考 API ============
+    async listReferences() {
+        return this.request('/refs');
     }
-    async saveGlobalRulesMeta(meta) {
+    async getReference(refId) {
         try {
-            await this.request('/global-rules-meta', {
-                method: 'PUT',
-                body: JSON.stringify(meta)
-            });
-            return true;
+            return await this.request(`/refs/${encodeURIComponent(refId)}`);
         }
         catch {
-            return false;
+            return null;
         }
     }
+    async saveReference(reference) {
+        await this.request(`/refs/${encodeURIComponent(reference.id)}`, {
+            method: 'PUT',
+            body: JSON.stringify(reference),
+        });
+        return true;
+    }
+    async deleteReference(refId) {
+        return this.request(`/refs/${encodeURIComponent(refId)}`, {
+            method: 'DELETE',
+        });
+    }
+    async readReferenceFile(path) {
+        return this.request(`/refs/files/${cleanPath(path)}`);
+    }
     // ============ 任务管理 ============
     async listTasks(status) {
         const query = status ? `?status=${status}` : '';
@@ -285,15 +274,6 @@ export class PpdocsApiClient {
     async crossListProjects() {
         return this.request('/cross/projects');
     }
-    /** 跨项目: 获取规则 */
-    async crossGetRules(target, ruleType) {
-        try {
-            return await this.request(`/cross/${encodeURIComponent(target)}/rules/${ruleType}`);
-        }
-        catch {
-            return [];
-        }
-    }
     // ============ 项目文件访问 ============
     /** 列出项目文件 */
     async listFiles(dir) {
@@ -466,6 +446,13 @@ export class PpdocsApiClient {
             method: 'POST',
         });
     }
+    /** 归档关闭讨论 (需项目认证) */
+    async discussionClose(id, conclusion) {
+        return this.request(`/discussions/${encodeURIComponent(id)}/close`, {
+            method: 'POST',
+            body: JSON.stringify({ conclusion }),
+        });
+    }
     /** 删除讨论 (公开路由) */
     async discussionDelete(id) {
         return this.publicRequest(`/api/discussions/${encodeURIComponent(id)}`, {

package/dist/storage/types.d.ts

@@ -4,6 +4,48 @@ export interface RuleMeta {
     min_hits: number;
     always?: boolean;
 }
+export interface WorkflowSummary {
+    id: string;
+    scope: 'global' | 'project';
+    title: string;
+    description: string;
+    system: string;
+    keywords: string[];
+    minHits: number;
+    always: boolean;
+    updatedAt: string;
+}
+export interface WorkflowDoc extends WorkflowSummary {
+    content: string;
+}
+export interface WorkflowSelector {
+    id: string;
+    scope?: 'global' | 'project';
+}
+export interface ReferenceLink {
+    url: string;
+    label: string;
+}
+export interface ReferenceFile {
+    name: string;
+    path: string;
+}
+export interface AdoptedNode {
+    chartId: string;
+    nodeId: string;
+    nodeLabel: string;
+}
+export interface Reference {
+    id: string;
+    title: string;
+    summary: string;
+    links: ReferenceLink[];
+    files: ReferenceFile[];
+    scripts: ReferenceFile[];
+    adoptedBy: AdoptedNode[];
+    createdAt: string;
+    updatedAt: string;
+}
 export interface FileInfo {
     name: string;
     path: string;

package/dist/tools/analyzer.d.ts

@@ -2,7 +2,7 @@
  * 代码分析引擎工具 (3个)
  * code_scan, code_smart_context, code_full_path
  *
- * code_smart_context: 代码+KG文档全关联 (含影响范围)
+ * code_smart_context: 代码+KG文档/工作流全关联 (含影响范围)
  * code_full_path: 两点间代码链路+共享KG文档
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

package/dist/tools/analyzer.js

@@ -2,7 +2,7 @@
  * 代码分析引擎工具 (3个)
  * code_scan, code_smart_context, code_full_path
  *
- * code_smart_context: 代码+KG文档全关联 (含影响范围)
+ * code_smart_context: 代码+KG文档/工作流全关联 (含影响范围)
  * code_full_path: 两点间代码链路+共享KG文档
  */
 import { z } from 'zod';
@@ -33,7 +33,7 @@ export function registerAnalyzerTools(server, ctx) {
         ].join('\n'));
     }));
     // ===== code_smart_context: 代码+文档全关联上下文 =====
-    server.tool('code_smart_context', '🔍 代码+文档全关联上下文 — 输入一个函数名,一次调用返回:代码依赖、关联文档、匹配规则、活跃任务、影响范围摘要。需先运行 code_scan', {
+    server.tool('code_smart_context', '🔍 代码+文档全关联上下文 — 输入一个函数名,一次调用返回:代码依赖、关联文档、匹配工作流、活跃任务、影响范围摘要。需先运行 code_scan', {
         projectPath: z.string().optional().describe('项目源码的绝对路径(不传则自动解析)'),
         symbolName: z.string().describe('要查询的符号名称(如"handleLogin", "AuthService")'),
     }, async (args) => safeTool(async () => {
@@ -75,11 +75,12 @@ export function registerAnalyzerTools(server, ctx) {
             }
             lines.push('');
         }
-        // 匹配规则
-        if (smartCtx.matchedRules.length > 0) {
-            lines.push(`### 📏 匹配规则 (${smartCtx.matchedRules.length})`);
-            for (const rule of smartCtx.matchedRules) {
-                lines.push(`  [${rule.ruleType}] ${rule.content.substring(0, 100)}`);
+        // 匹配工作流
+        if (smartCtx.matchedWorkflows.length > 0) {
+            lines.push(`### 📘 匹配工作流 (${smartCtx.matchedWorkflows.length})`);
+            for (const workflow of smartCtx.matchedWorkflows) {
+                const desc = workflow.description ? ` — ${workflow.description}` : '';
+                lines.push(`  [${workflow.scope}/${workflow.system || 'general'}] ${workflow.title}${desc}`);
             }
             lines.push('');
         }

package/dist/tools/discussion.js

@@ -233,13 +233,9 @@ export function registerDiscussionTools(server, ctx) {
                 if (brief && !isInitiator(brief, me, myPid)) {
                     return wrap(`🔒 无权限: 仅发起人 (${brief.initiator}) 可归档讨论\n你的身份: ${me}`);
                 }
-                // 先追加结案总结
-                try {
-                    await client().discussionReply(decoded.id, me, `📋 结案总结:\n\n${decoded.conclusion}`, '结案总结');
-                }
-                catch { /* 忽略回复失败 */ }
-                await client().discussionComplete(decoded.id);
-                return wrap(`✅ 讨论已结案 (ID: ${decoded.id})\n📋 ${decoded.conclusion}`);
+                const result = await client().discussionClose(decoded.id, decoded.conclusion);
+                const archivePath = result?.archived_path ? `\n📦 已归档: ${result.archived_path}` : '';
+                return wrap(`✅ 讨论已结案并归档 (ID: ${decoded.id})\n📋 ${decoded.conclusion}${archivePath}`);
             }
             case 'delete': {
                 if (!decoded.id)