@ppdocs/mcp 2.6.23 → 2.6.25

package/dist/storage/types.d.ts

@@ -51,9 +51,11 @@ export interface NodeData {
     testRules?: string[];
     reviewRules?: string[];
     codeStyle?: string[];
+    unitTests?: string[];
     createdAt?: string;
     updatedAt?: string;
     lastAccessedAt?: string;
+    lastSyncAt?: string;
     versions?: VersionRecord[];
     bugfixes?: BugfixRecord[];
 }

package/dist/tools/index.js

@@ -64,17 +64,18 @@ export function registerTools(server, projectId, _user) {
             version: z.number(),
             date: z.string(),
             changes: z.string()
-        })).optional().describe('版本记录'),
+        })).optional().describe('版本记录(0.1起始,AI控制递增)'),
         bugfixes: z.array(z.object({
             id: z.string(),
             date: z.string(),
             issue: z.string(),
             solution: z.string(),
             impact: z.string().optional()
-        })).optional().describe('修复记录')
+        })).optional().describe('修复记录'),
+        lastSyncAt: z.string().optional().describe('代码↔图谱最后同步时间(ISO时间戳)')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
-        const { nodeId, tags, relatedFiles, versions, bugfixes, path, ...rest } = decoded;
+        const { nodeId, tags, relatedFiles, versions, bugfixes, path, lastSyncAt, ...rest } = decoded;
         // 根节点必须使用 kg_update_root 更新
         if (nodeId === 'root') {
             return wrap(projectId, '❌ 根节点请使用 kg_update_root 方法更新');
@@ -91,6 +92,8 @@ export function registerTools(server, projectId, _user) {
             updates.bugfixes = bugfixes;
         if (path !== undefined)
             updates.path = path;
+        if (lastSyncAt !== undefined)
+            updates.lastSyncAt = lastSyncAt;
         const node = await storage.updateNode(projectId, nodeId, updates);
         return wrap(projectId, node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
     });
@@ -142,8 +145,8 @@ export function registerTools(server, projectId, _user) {
         return wrap(projectId, node ? JSON.stringify(node, null, 2) : '操作失败');
     });
     // 5. 搜索节点
-    server.tool('kg_search', '关键词搜索节点,按命中率排序返回', {
-        keywords: z.array(z.string()).describe('关键词列表(OR逻辑)'),
+    server.tool('kg_search', '关键词搜索节点,按命中率排序返回。空白关键词[""]返回全部节点', {
+        keywords: z.array(z.string()).describe('关键词列表(OR逻辑),空白[""]返回全部'),
         limit: z.number().optional().describe('返回数量(默认10)')
     }, async (args) => {
         const results = await storage.searchNodes(projectId, args.keywords, args.limit || 10);
@@ -158,6 +161,18 @@ export function registerTools(server, projectId, _user) {
         const json = JSON.stringify(output, null, 2);
         return wrap(projectId, `${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情`);
     });
+    // 5.5 列出所有标签
+    server.tool('kg_list_tags', '获取所有节点使用过的标签列表(去重)', {}, async () => {
+        const nodes = await storage.listNodes(projectId);
+        const tagSet = new Set();
+        for (const node of nodes) {
+            if (node.categories && Array.isArray(node.categories)) {
+                node.categories.forEach(cat => tagSet.add(cat));
+            }
+        }
+        const tags = Array.from(tagSet).sort();
+        return wrap(projectId, JSON.stringify({ total: tags.length, tags }, null, 2));
+    });
     // 6. 路径查找
     server.tool('kg_find_path', '查找两节点间的依赖路径', {
         startId: z.string().describe('起点节点ID'),

package/package.json

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

package/templates/commands/pp/sync.md

@@ -6,7 +6,9 @@
 | **代码即真理** | 代码与图谱冲突时以 Git 状态为准，强制覆写；禁止保留幽灵节点 |
 | **拓扑优先** | Types → Utils → Services → UI，底层未建不创建上层 |
 | **引用强约束** | relatedFiles 精确锚定物理路径；signature 为代码唯一标识符 |
-| **版本追踪** | 重要变更时自动追加 versions 记录 |
+| **版本追踪** | 版本号以 0.1 起始，每次同步有变动必须更新版本号 (AI控制递增) |
+| **版本一致性** | 同步完成后更新 lastSyncAt，用于检测代码↔图谱是否同步 |
+| **标签完整性** | 每节点 ≥3 个分类标签，标签由AI管理 |
 
 ---
 
@@ -19,19 +21,32 @@
 
 ---
 
-## 标准流程
+## 标准流程 (5步)
 
-### Step 1: 任务初始化 + 变更检测
+### Step 1: 变更检测
 ```
 task_create({ title:"KG同步", goals:["检测变更","更新节点","验证覆盖"], related_nodes:["root"] })
 
 recent模式: git diff --name-only HEAD~3
 all模式: Glob src/**/*.{ts,tsx}
+
+⭐ kg_search([""]) 一次获取全部现有节点 (替代逐个search)
+```
+
+**版本一致性检测** ⭐新增:
 ```
+对每个有 relatedFiles 的节点:
+1. 获取文件 mtime (通过 Bash stat 或 fs.statSync)
+2. 对比节点的 lastSyncAt
+3. mtime > lastSyncAt → 标记为 [OUTDATED] 需同步
+4. lastSyncAt 不存在 → 标记为 [UNTRACKED] 从未同步
+```
+
 **输出变更清单**:
 ```
 ├─ 🟢 [NEW] src/services/Payment.ts (待创建)
 ├─ 🟡 [MOD] src/utils/format.ts (待更新)
+├─ 🟠 [OUTDATED] src/hooks/useAuth.ts (代码已改，图谱未同步)
 └─ 🔴 [DEL] src/legacy/old.ts (待废弃)
 ```
 等待用户确认 `OK`
@@ -39,13 +54,21 @@ all模式: Glob src/**/*.{ts,tsx}
 ### Step 2: 依赖解析 + 拓扑排序
 解析 import 语句 → 构建依赖树 → 拓扑排序确保底层先处理
 
+### Step 2.5: 标签完整性预检 ⭐新增
+```
+kg_list_tags() → 获取现有标签词库 (91个标签)
+检查待处理节点:
+  - 标签 < 3 → 自动补全建议
+  - 使用现有标签词库保持一致性
+```
+
 ### Step 3: 原子化执行
 对每个文件:
 ```
 1. 读取源码 → 提取 signature/imports/comments
-2. kg_search(signature) → 检测现有节点
+2. 从 Step1 缓存查找现有节点 (无需再次kg_search)
 3. 执行写入:
-   - NEW: kg_create_node (全字段 + relatedFiles)
+   - NEW: kg_create_node (全字段 + relatedFiles + ⚠️tags≥3)
    - MOD: kg_update_node (变动字段 + 追加 versions)
    - DEL: kg_update_node(status:"deprecated") 或 kg_delete_node
 4. 每5个文件: task_add_log(progress, "已处理 N/M")
@@ -58,20 +81,43 @@ all模式: Glob src/**/*.{ts,tsx}
 kg_update_node({
   nodeId: "xxx",
   description: "新描述",
+  lastSyncAt: new Date().toISOString(),  // ⭐ 更新同步时间戳
   versions: [...现有versions, {
-    version: 现有max+1,
+    version: 上一版本 + 0.1,  // ⭐ 0.1起始，AI控制递增
     date: "ISO时间",
     changes: "本次变更摘要"
   }]
 })
 ```
 
-### Step 4: 校验 + 交付
+**代码版本注释** (源码文件头部):
+```typescript
+// @version 0.1
+// 或 JSDoc 格式
+/**
+ * @version 0.1
+ */
 ```
-1. 统计覆盖率
+
+**同步时间戳规则** ⭐新增:
+```
+NEW: kg_create_node 后自动设置 lastSyncAt = now
+MOD: kg_update_node 时必须传 lastSyncAt = now
+OUTDATED: 仅更新 lastSyncAt (无需改 description/versions)
+```
+
+### Step 4: 关系校验 ⭐优化
+```
+1. kg_read_node(nodeId, depth=1) 批量校验上下游关系
 2. kg_list_nodes({maxEdges:0}) 检查孤立节点
 3. 检查断链 (dependencies 指向不存在的 signature)
-4. task_complete({
+```
+
+### Step 5: 交付报告 ⭐增强
+```
+1. 统计覆盖率
+2. kg_list_tags() 输出标签分布
+3. task_complete({
      summary: "同步完成...",
      difficulties: ["遇到的困难"],
      solutions: ["采用的方案"],
@@ -87,19 +133,36 @@ kg_update_node({
 | 更新节点 | 12 | ✅ |
 | 废弃节点 | 1 | ⚠️ |
 | 版本追加 | 8 | ✅ |
+| 标签补全 | 5 | ✅ |
+| 同步时间戳更新 | 15 | ✅ |
+| 版本一致率 | 100% | 🟢 |
 | 覆盖率 | 98.5% | 🟢 |
+| 标签总数 | 91 | 📊 |
 
 建议: git add . && git commit -m "chore: sync kg"
 ```
 
 ---
 
+## MCP 工具速查 ⭐新增
+
+| 工具 | 用途 | 示例 |
+|:---|:---|:---|
+| `kg_search([""])` | 获取全部节点 | 变更检测时一次拉取 |
+| `kg_list_tags` | 标签词库 | 保持标签一致性 |
+| `kg_read_node(id, depth=1)` | 含关系的详情 | 校验上下游 |
+| `kg_list_nodes({maxEdges:0})` | 孤立节点 | 发现断链 |
+| `kg_list_nodes` | 含summary列表 | 覆盖率报告 |
+
+---
+
 ## 异常处理
 | 场景 | 反应 |
 |:---|:---|
 | git status 不干净 | 警告 + 询问是否强制继续 |
 | kg_search 返回多个同名节点 | 暂停，列出候选请求人工绑定 |
 | 文件解析失败 | task_add_log(issue) + 标记 Skipped，不中断队列 |
+| 标签不足3个 | 自动从词库补全，记录日志 |
 
 ---
 
@@ -110,3 +173,6 @@ kg_update_node({
 | 文件路径 | relatedFiles | 相对项目根 (如 `src/utils/auth.ts`) |
 | export 函数/类 | signature | 标识符名 (如 `AuthService`) |
 | JSDoc/Comments | description | 优先注释，无则代码生成摘要 |
+| 功能分类 | tags | ≥3个，使用 kg_list_tags 词库 |
+| 同步时间 | lastSyncAt | 每次同步完成时设为当前 ISO 时间戳 |
+| `// @version 0.1` | versions[].version | 代码文件头注释，0.1起始 |