@ppdocs/mcp 2.6.14 → 2.6.16

package/dist/tools/index.js

@@ -103,7 +103,7 @@ export function registerTools(server, projectId, _user) {
         return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(根节点已锁定)');
     });
     // 3.6 获取项目规则 (独立方法，按需调用)
-    server.tool('kg_get_rules', '获取项目规则列表(按需调用，不再自动附加到每个方法返回)', {}, async () => {
+    server.tool('kg_get_rules', '获取项目规则列表(按需调用)', {}, async () => {
         const style = await getRootStyle(projectId);
         if (!style || style.trim() === '') {
             return { content: [{ type: 'text', text: '暂无项目规则' }] };
@@ -175,13 +175,13 @@ export function registerTools(server, projectId, _user) {
             for (const r of relations) {
                 if (r.direction === 'outgoing' && (direction === 'outgoing' || direction === 'both')) {
                     if (!outgoing.some(o => o.id === r.nodeId)) {
-                        outgoing.push({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType, depth: currentDepth });
+                        outgoing.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
                         await fetchRelations(r.nodeId, currentDepth + 1, 'outgoing');
                     }
                 }
                 if (r.direction === 'incoming' && (direction === 'incoming' || direction === 'both')) {
                     if (!incoming.some(i => i.id === r.nodeId)) {
-                        incoming.push({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType, depth: currentDepth });
+                        incoming.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
                         await fetchRelations(r.nodeId, currentDepth + 1, 'incoming');
                     }
                 }
@@ -193,6 +193,65 @@ export function registerTools(server, projectId, _user) {
         }
         return wrap(projectId, JSON.stringify({ outgoing, incoming }, null, 2));
     });
+    // 9. 读取单个节点详情
+    server.tool('kg_read_node', '读取单个节点的完整内容(描述、关联文件、依赖、历史记录)', {
+        nodeId: z.string().describe('节点ID')
+    }, async (args) => {
+        const node = await storage.getNode(projectId, args.nodeId);
+        if (!node) {
+            return wrap(projectId, '节点不存在');
+        }
+        // 构建结构化输出
+        const lines = [];
+        // 基础信息
+        lines.push(`## ${node.title}\n`);
+        lines.push('**基础信息**');
+        lines.push(`| 字段 | 值 |`);
+        lines.push(`|:---|:---|`);
+        lines.push(`| ID | ${node.id} |`);
+        lines.push(`| 类型 | ${node.type} |`);
+        lines.push(`| 状态 | ${node.status} |`);
+        lines.push(`| 签名 | ${node.signature} |`);
+        if (node.categories && node.categories.length > 0) {
+            lines.push(`| 标签 | ${node.categories.join(', ')} |`);
+        }
+        lines.push('');
+        // 关联文件
+        if (node.relatedFiles && node.relatedFiles.length > 0) {
+            lines.push('**关联文件**');
+            node.relatedFiles.forEach(f => lines.push(`- ${f}`));
+            lines.push('');
+        }
+        // 依赖关系
+        if (node.dependencies && node.dependencies.length > 0) {
+            lines.push('**依赖关系**');
+            node.dependencies.forEach(d => lines.push(`- ${d.name}: ${d.description}`));
+            lines.push('');
+        }
+        // 描述内容
+        if (node.description) {
+            lines.push('**描述内容**');
+            lines.push(node.description);
+            lines.push('');
+        }
+        // 更新历史
+        if (node.versions && node.versions.length > 0) {
+            lines.push('**更新历史**');
+            lines.push('| 版本 | 日期 | 变更 |');
+            lines.push('|:---|:---|:---|');
+            node.versions.forEach(v => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
+            lines.push('');
+        }
+        // 修复历史
+        if (node.bugfixes && node.bugfixes.length > 0) {
+            lines.push('**修复历史**');
+            lines.push('| ID | 日期 | 问题 | 方案 |');
+            lines.push('|:---|:---|:---|:---|');
+            node.bugfixes.forEach(b => lines.push(`| ${b.id} | ${b.date} | ${b.issue} | ${b.solution} |`));
+            lines.push('');
+        }
+        return wrap(projectId, lines.join('\n'));
+    });
     // ===================== 任务管理工具 =====================
     // 10. 创建任务
     server.tool('task_create', '创建开发任务,记录目标和关联节点', {

package/package.json

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

package/templates/commands/pp/sync.md

@@ -1,139 +1,82 @@
 ---
-description: 代码同步知识图谱：增量更新节点，保持代码与知识库一致
-argument-hint: "[init|diff|check]"
+description: 代码同步知识图谱：Git变更检测 + 智能节点更新
+argument-hint: "[all|recent|check]"
 ---
 
-# /sync 代码同步
+# /sync 代码同步知识库
 
-执行 `task_create("代码同步")` → 分阶段执行 → 完成后 `task_complete`
+执行 `task_create("代码同步")` 开始，完成后 `task_complete` 归档
 
-**参数**: `init`=全量初始化 | `diff`=仅变更文件 | `check`=检查覆盖率
+**参数**: `all`=全量同步 | `recent`=最近变更(默认) | `check`=检查覆盖率
 
-## Phase 1: 项目探测
+---
+
+## Step 1: 变更检测
 
-**技术栈识别**: package.json→Node/React | Cargo.toml→Rust | go.mod→Go | requirements.txt→Python
-**架构分析**: 读取入口配置 → Glob扫描源码目录 → 按目录聚类 → 输出架构树等用户确认
+**recent模式**: 执行 `git status` + `git diff --name-only HEAD~3` 获取变更文件列表，过滤非代码文件(.md/.json/lock等)
+**all模式**: Glob扫描 `src/**/*.{ts,tsx,rs,go,py}` 获取全部源码，按目录聚类输出架构树等用户确认
 
 ```
-┌─ 推断架构 ────────────────────┐
-│ [intro] 项目根: {名称}        │
-│ ├─ [intro] {模块A}: {路径}    │
-│ ├─ [logic] {模块B}: {路径}    │
-│ └─ [data]  共享类型           │
-└───────────────────────────────┘
+检测结果示例:
+├─ 修改: src/auth.ts, src/utils.ts
+├─ 新增: src/newFeature.ts
+└─ 删除: src/deprecated.ts
 回复 OK 继续
 ```
 
-## Phase 2: 节点生成规则
-
-| 识别模式 | type | signature | categories |
-|:---|:---|:---|:---|
-| pages/views/routes | logic | `Page:{名称}` | `[ui, page]` |
-| components | logic | `Comp:{名称}` | `[ui, component]` |
-| use*.ts (Hook) | logic | `{名称}()` | `[hook]` |
-| services/api | logic | `Svc:{名称}` | `[service, api]` |
-| store/storage | logic | `Store:{名称}` | `[storage]` |
-| utils/helpers | logic | `{函数名}()` | `[util, reusable]` |
-| types/interfaces | data | `Type:{名称}` | `[type]` |
-| config/*.json | intro | `Config:{名称}` | `[config]` |
-| *.rs (Rust) | logic | `{mod}::{fn}` | `[rust]` |
-| *.go (Go) | logic | `{pkg}.{Func}` | `[go]` |
-
-## Phase 3: 字段规范 (MUST 全部填写)
-
-| 字段 | 规则 | 示例 |
-|:---|:---|:---|
-| title | 中文描述 | `用户认证服务` |
-| type | logic/data/intro | `logic` |
-| signature | 唯一标识 | `useAuth()` |
-| categories | 分类数组 | `["hook", "auth"]` |
-| **relatedFiles** | **MUST: 源文件路径数组** | `["src/hooks/useAuth.ts"]` |
-| dependencies | 依赖节点 | `[{name: "xxx", description: "用途"}]` |
-| description | 见下方模板 | |
-
-### relatedFiles 提取规则 (MUST)
-```
-1. 当前处理的文件路径 → relatedFiles[0]
-2. 该文件 import 的本地模块 → relatedFiles[1..n]
-3. NEVER 留空，至少包含当前文件
-```
+## Step 2: 节点匹配
 
-### dependencies 推断规则 (MUST)
-```
-处理每个文件时执行:
-1. 解析 import/require 语句 → 提取本地模块路径
-2. 对每个本地模块:
-   │
-   ├─ 匹配方式1: 路径匹配
-   │   kg_list_nodes → 遍历 relatedFiles 字段
-   │   若模块路径 ∈ 某节点的 relatedFiles → 匹配成功
-   │
-   ├─ 匹配方式2: 签名匹配
-   │   从 import 提取函数名/类名 → 匹配节点 signature
-   │   如: import { useAuth } → 匹配 signature="useAuth()"
-   │
-   └─ 匹配成功 → dependencies.push({
-        name: 目标节点的 signature,
-        description: "用途说明 (从import上下文推断)"
-      })
-
-3. 依赖 description 规则:
-   - Hook: "状态管理" / "数据获取" / "交互逻辑"
-   - Service: "API调用" / "数据服务"
-   - Utils: "工具函数" / "格式化"
-   - Types: "类型定义"
-   - Component: "UI组件" / "子组件"
-```
+对每个变更文件执行: `kg_search(文件名关键词)` → 匹配 relatedFiles 字段 → 确定关联节点
+- 匹配成功 → 标记为"更新"
+- 无匹配 → 标记为"新增"
+- 节点存在但文件已删 → 标记为"清理"
 
-### description 模板
-```markdown
-## 职责
-[读取 JSDoc/docstring，无则根据代码推断]
+## Step 3: 读取分析
 
-## 核心逻辑
-| 导出 | 类型 | 说明 |
-|:---|:---|:---|
-| funcA | function | 功能描述 |
+批量读取变更文件(每轮≤10个)，分析: 导出函数/类型 → import依赖 → 功能职责
 
-## 依赖
-| 模块 | 用途 |
+**节点字段规则**:
+| 字段 | 规则 |
 |:---|:---|
-| xxx | 依赖原因 |
-```
-
-> 注: 输入输出类型通过 dependencies 关联到 data 节点表达，不再使用独立的数据流字段
+| title | 中文模块名 |
+| type | logic(函数/类) / data(类型) / intro(配置/说明) |
+| signature | 唯一标识如 `useAuth()` `AuthService` |
+| categories | 分类标签如 `["hook","auth"]` |
+| relatedFiles | **MUST** 当前文件+import的本地模块路径 |
+| dependencies | 解析import匹配已有节点signature，填写 `{name, description}` |
+| description | 职责+核心逻辑表格+依赖说明 (Markdown) |
 
-## Phase 4: 执行同步
+## Step 4: 执行更新
 
 ```
-扫描文件 → kg_list_nodes → 匹配signature → 差异对比
-                                              │
-    ┌─────────────────────────────────────────┘
-    │ 新文件 → kg_create_node (MUST 填 relatedFiles)
-    │ 内容变化 → kg_update_node
-    │ 无变化 → 跳过
-    ▼
-进度: 每5文件 task_add_log("progress", "[X/N] 已处理: [文件列表]")
+遍历变更文件:
+├─ 新增文件 → kg_create_node (MUST填relatedFiles+dependencies)
+├─ 修改文件 → kg_read_node获取旧内容 → 对比差异 → kg_update_node
+├─ 删除文件 → kg_update_node将status改为deprecated 或 kg_delete_node
+└─ 进度: 每5个文件 task_add_log("progress", "[X/N] 已处理...")
 ```
 
-## Phase 5: 完成报告
+## Step 5: 完成报告
 
 ```
-┌─────────────────────────────────┐
-│ 同步完成                        │
-│ 文件: XX | ✅新增: X | 🔄更新: X │
-│ ❌ 未覆盖: [列表]                │
-│ 覆盖率: XX.X%                   │
-└─────────────────────────────────┘
+┌─ 同步完成 ──────────────────────────┐
+│ 扫描: XX文件 | ✅新增: X | 🔄更新: X │
+│ ⚠️ 未覆盖: [文件列表]               │
+│ 覆盖率: XX.X%                       │
+├─────────────────────────────────────┤
+│ 💡 建议执行 git add . && git commit │
+│    备份本次同步后的代码状态          │
+└─────────────────────────────────────┘
 ```
 
-执行 `task_complete` 归档任务
+执行 `task_complete` 归档，提醒用户 Git 提交备份
+
+---
 
 ## 约束
 
-1. **批量限制**: 每轮 ≤10 文件
-2. **顺序**: types → utils → services → components → pages (底层优先)
-3. **去重**: 写入前 `kg_search(signature)` 检查冲突
-4. **依赖**: MUST 解析 import 匹配已有节点，NEVER 留空
-5. **relatedFiles**: NEVER 留空，至少填当前文件路径
-6. **依赖验证**: 创建节点前检查 dependencies 中的 name 是否存在于知识库
+1. **顺序**: types → utils → services → components → pages (依赖优先)
+2. **去重**: 写入前 `kg_search(signature)` 检查已存在
+3. **依赖**: MUST解析import匹配节点，NEVER留空dependencies
+4. **relatedFiles**: NEVER留空，至少填当前文件路径
+5. **清理**: 已删除文件的节点标记deprecated或删除