@ppdocs/mcp 2.3.0 → 2.5.0

package/README.md

@@ -0,0 +1,201 @@
+# @ppdocs/mcp
+
+> Knowledge Graph MCP Server for Claude - 让 Claude 拥有项目知识图谱记忆
+
+[![npm version](https://badge.fury.io/js/%40ppdocs%2Fmcp.svg)](https://www.npmjs.com/package/@ppdocs/mcp)
+
+## 概述
+
+ppdocs MCP 是一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，让 Claude 能够在对话中构建和查询项目知识图谱。
+
+```
+┌─────────────┐     MCP      ┌─────────────┐    HTTP    ┌─────────────┐
+│  Claude AI  │ ──────────── │ @ppdocs/mcp │ ────────── │ ppdocs 桌面 │
+└─────────────┘              └─────────────┘            └──────┬──────┘
+                                                               │
+                                                        ┌──────▼──────┐
+                                                        │  知识图谱    │
+                                                        │  文件存储    │
+                                                        └─────────────┘
+```
+
+### 核心功能
+
+| 功能 | 描述 |
+|------|------|
+| 📊 **知识图谱** | 创建、更新、删除、搜索节点 |
+| 🔗 **依赖追踪** | 自动计算节点间的依赖关系 |
+| 📝 **任务管理** | 记录开发任务、进度日志、经验总结 |
+| 🔍 **智能搜索** | 多关键词搜索，按相关度排序 |
+| 🛤️ **路径分析** | 查找两节点间的依赖路径 |
+
+---
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+npm install -g @ppdocs/mcp
+```
+
+### 2. 初始化项目
+
+```bash
+npx @ppdocs/mcp init -p <项目ID> -k <密钥>
+```
+
+这会自动：
+- 创建 `.ppdocs` 配置文件
+- 创建 `.mcp.json` MCP 配置
+- 安装工作流模板到 `.claude/`
+
+### 3. 配置 Claude Desktop
+
+在 Claude Desktop 配置文件中添加：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ppdocs": {
+      "command": "npx",
+      "args": ["-y", "@ppdocs/mcp"],
+      "env": {
+        "PPDOCS_API_URL": "http://localhost:20001/api/项目ID/密码"
+      }
+    }
+  }
+}
+```
+
+### 4. 获取 API URL
+
+1. 打开 ppdocs 桌面应用
+2. 选择一个项目 → 点击设置图标
+3. 复制 **MCP 连接地址**
+
+---
+
+## CLI 命令
+
+```bash
+# 初始化 (Claude Code 模式)
+npx @ppdocs/mcp init -p <projectId> -k <key>
+
+# 初始化 (Codex 模式 - 生成 AGENTS.md)
+npx @ppdocs/mcp init -p <projectId> -k <key> --codex
+
+# 选项
+-p, --project  项目 ID (必填)
+-k, --key      API 密钥 (必填)
+-u, --user     用户名 (可选，自动生成)
+--port         API 端口 (默认: 20001)
+--api          API 主机 (默认: localhost)
+--codex        Codex 模式
+```
+
+---
+
+## 工具列表
+
+### 知识图谱工具
+
+| 工具 | 说明 |
+|------|------|
+| `kg_create_node` | 创建知识节点 |
+| `kg_update_node` | 更新节点内容 |
+| `kg_delete_node` | 删除节点 |
+| `kg_lock_node` | 锁定节点 (AI 只能锁定，解锁需前端手动) |
+| `kg_list_nodes` | 列出所有节点 |
+| `kg_search` | 关键词搜索 |
+| `kg_find_path` | 查找依赖路径 |
+| `kg_find_orphans` | 查找孤立节点 |
+| `kg_get_relations` | 获取节点关系 |
+
+### 任务管理工具
+
+| 工具 | 说明 |
+|------|------|
+| `task_create` | 创建开发任务 |
+| `task_list` | 列出任务 |
+| `task_get` | 获取任务详情 |
+| `task_add_log` | 添加进度日志 |
+| `task_complete` | 完成任务并归档 |
+
+---
+
+## 节点类型
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| `logic` | 逻辑/函数 | 算法、处理流程、API 接口 |
+| `data` | 数据结构 | 数据库表、配置、状态定义 |
+| `intro` | 概念介绍 | 架构说明、设计决策、术语解释 |
+
+## 节点状态
+
+| 状态 | 说明 |
+|------|------|
+| `incomplete` | 未完成 (默认) |
+| `complete` | 已完成 |
+| `fixing` | 修复中 |
+| `refactoring` | 重构中 |
+| `deprecated` | 已废弃 |
+
+---
+
+## 环境变量
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `PPDOCS_API_URL` | API 完整地址 | `http://localhost:20001/api/myproject/abc123` |
+| `PPDOCS_PROJECT` | 项目 ID | `myproject` |
+| `PPDOCS_KEY` | 访问密钥 | `abc123` |
+| `PPDOCS_USER` | 用户名 | `developer` |
+
+---
+
+## 常见问题
+
+**Q: 连接失败怎么办？**
+
+1. 确保 ppdocs 桌面应用正在运行
+2. 检查端口是否正确 (默认 20001)
+3. 验证 API URL 格式
+
+**Q: 节点无法删除？**
+
+- 节点被锁定 → 在 ppdocs 桌面应用中手动解锁
+- 是根节点 → 根节点不可删除
+
+---
+
+## 更新日志
+
+### v2.5.0
+- ✨ 新增 CLI init 命令，自动安装工作流模板
+- ✨ 支持 Codex 模式 (--codex)
+- 📦 构建时自动复制模板
+
+### v2.4.0
+- 🛡️ `kg_lock_node` 只能锁定，解锁需前端手动操作
+- ⚡ 后端自动记录操作日志
+
+### v2.3.0
+- 新增任务管理功能
+- 添加文件锁防止并发写入
+
+---
+
+## 许可证
+
+MIT License
+
+## 相关链接
+
+- [ppdocs 桌面应用](https://github.com/ppdocs/ppdocs)
+- [MCP 协议文档](https://modelcontextprotocol.io/)
+- [问题反馈](https://github.com/ppdocs/ppdocs/issues)

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 /**
  * ppdocs MCP CLI
- * 命令: init - 初始化项目配置
+ * 命令: init - 初始化项目配置 + 安装工作流模板
  */
 export declare function runCli(args: string[]): boolean;

package/dist/cli.js

@@ -1,16 +1,19 @@
 /**
  * ppdocs MCP CLI
- * 命令: init - 初始化项目配置
+ * 命令: init - 初始化项目配置 + 安装工作流模板
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
 /** 生成随机用户名 (8位字母数字) */
 function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
     return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
 }
 function parseArgs(args) {
-    const opts = { port: 20001, api: 'localhost' };
+    const opts = { port: 20001, api: 'localhost', codex: false };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '-p' || arg === '--project') {
@@ -28,10 +31,12 @@ function parseArgs(args) {
         else if (arg === '--api') {
             opts.api = args[++i];
         }
+        else if (arg === '--codex') {
+            opts.codex = true;
+        }
     }
     if (!opts.project || !opts.key)
         return null;
-    // 如果没设置 user，自动生成
     if (!opts.user)
         opts.user = generateUser();
     return opts;
@@ -41,7 +46,7 @@ function showHelp() {
 ppdocs MCP CLI
 
 Commands:
-  init    Initialize ppdocs config in current directory
+  init    Initialize ppdocs config + install workflow templates
 
 Usage:
   npx @ppdocs/mcp init -p <projectId> -k <key> [options]
@@ -49,13 +54,14 @@ Usage:
 Options:
   -p, --project  Project ID (required)
   -k, --key      API key (required)
-  -u, --user     User name for logs (optional, auto-generated if not set)
+  -u, --user     User name for logs (optional, auto-generated)
   --port         API port (default: 20001)
   --api          API host (default: localhost)
+  --codex        Codex mode: generate AGENTS.md instead of .claude/
 
 Example:
   npx @ppdocs/mcp init -p myproject -k abc123xyz
-  npx @ppdocs/mcp init -p myproject -k abc123xyz -u alice
+  npx @ppdocs/mcp init -p myproject -k abc123xyz --codex
 `);
 }
 export function runCli(args) {
@@ -108,6 +114,13 @@ function initProject(opts) {
     };
     fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2));
     console.log(`✅ Created ${mcpPath}`);
+    // Install workflow templates
+    if (opts.codex) {
+        installCodexTemplates(cwd);
+    }
+    else {
+        installClaudeTemplates(cwd);
+    }
     console.log(`
 🎉 Done! ppdocs MCP configured for project: ${opts.project}
    User: ${opts.user}
@@ -115,3 +128,69 @@ function initProject(opts) {
 Restart Claude Code to use ppdocs knowledge graph.
 `);
 }
+/** 递归复制目录 */
+function copyDirRecursive(src, dest) {
+    if (!fs.existsSync(src))
+        return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/** 安装 Claude Code 模板 */
+function installClaudeTemplates(cwd) {
+    const claudeDir = path.join(cwd, '.claude');
+    // 1. 复制 commands/pp/
+    const srcCommands = path.join(TEMPLATES_DIR, 'commands', 'pp');
+    const destCommands = path.join(claudeDir, 'commands', 'pp');
+    if (fs.existsSync(srcCommands)) {
+        copyDirRecursive(srcCommands, destCommands);
+        console.log(`✅ Installed .claude/commands/pp/`);
+    }
+    // 2. 复制 hooks/
+    const srcHooks = path.join(TEMPLATES_DIR, 'hooks');
+    const destHooks = path.join(claudeDir, 'hooks');
+    if (fs.existsSync(srcHooks)) {
+        copyDirRecursive(srcHooks, destHooks);
+        console.log(`✅ Installed .claude/hooks/`);
+    }
+    // 3. 合并 settings.local.json hooks 配置
+    const settingsHooksPath = path.join(TEMPLATES_DIR, 'settings-hooks.json');
+    const settingsLocalPath = path.join(claudeDir, 'settings.local.json');
+    if (fs.existsSync(settingsHooksPath)) {
+        let existingSettings = {};
+        if (fs.existsSync(settingsLocalPath)) {
+            try {
+                existingSettings = JSON.parse(fs.readFileSync(settingsLocalPath, 'utf-8'));
+            }
+            catch { /* ignore */ }
+        }
+        const hooksConfig = JSON.parse(fs.readFileSync(settingsHooksPath, 'utf-8'));
+        const mergedSettings = {
+            ...existingSettings,
+            hooks: hooksConfig.hooks
+        };
+        fs.mkdirSync(claudeDir, { recursive: true });
+        fs.writeFileSync(settingsLocalPath, JSON.stringify(mergedSettings, null, 2));
+        console.log(`✅ Configured .claude/settings.local.json hooks`);
+    }
+}
+/** 安装 Codex 模板 (生成 AGENTS.md) */
+function installCodexTemplates(cwd) {
+    const srcPrompt = path.join(TEMPLATES_DIR, 'hooks', 'SystemPrompt.md');
+    const destAgents = path.join(cwd, 'AGENTS.md');
+    if (fs.existsSync(srcPrompt)) {
+        fs.copyFileSync(srcPrompt, destAgents);
+        console.log(`✅ Created AGENTS.md (Codex mode)`);
+    }
+    else {
+        console.log(`⚠️  SystemPrompt.md template not found`);
+    }
+}

package/dist/storage/httpClient.d.ts

@@ -83,10 +83,3 @@ export declare function createTask(_projectId: string, task: {
 }, creator: string): Promise<Task>;
 export declare function addTaskLog(_projectId: string, taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
 export declare function completeTask(_projectId: string, taskId: string, experience: TaskExperience): Promise<Task | null>;
-export interface LogEntry {
-    user: string;
-    action: string;
-    target: string;
-    node_id?: string;
-}
-export declare function appendLog(_projectId: string, entry: LogEntry): Promise<void>;

package/dist/storage/httpClient.js

@@ -14,22 +14,36 @@ export class PpdocsApiClient {
     // ============ HTTP 请求工具 ============
     async request(path, options = {}) {
         const url = `${this.baseUrl}${path}`;
-        const response = await fetch(url, {
-            ...options,
-            headers: {
-                'Content-Type': 'application/json',
-                ...options.headers
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10000); // 10秒超时
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...options.headers
+                }
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: response.statusText }));
+                throw new Error(error.error || `HTTP ${response.status}`);
             }
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: response.statusText }));
-            throw new Error(error.error || `HTTP ${response.status}`);
+            const json = await response.json();
+            if (!json.success) {
+                throw new Error(json.error || 'Unknown error');
+            }
+            return json.data;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error('Request timeout (10s)');
+            }
+            throw err;
         }
-        const json = await response.json();
-        if (!json.success) {
-            throw new Error(json.error || 'Unknown error');
+        finally {
+            clearTimeout(timeout);
         }
-        return json.data;
     }
     // ============ 节点操作 ============
     async listNodes() {
@@ -272,15 +286,3 @@ export async function addTaskLog(_projectId, taskId, logType, content) {
 export async function completeTask(_projectId, taskId, experience) {
     return getClient().completeTask(taskId, experience);
 }
-export async function appendLog(_projectId, entry) {
-    try {
-        await getClient()['request']('/logs', {
-            method: 'POST',
-            body: JSON.stringify(entry)
-        });
-        console.error(`[LOG] ${entry.action}: ${entry.target}`);
-    }
-    catch (err) {
-        console.error(`[LOG ERROR] Failed to append log:`, err);
-    }
-}

package/dist/storage/types.d.ts

@@ -6,7 +6,7 @@ export interface Edge {
     auto?: boolean;
 }
 export type NodeType = 'logic' | 'data' | 'intro';
-export type NodeStatus = 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated' | 'locked';
+export type NodeStatus = 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated';
 export interface DataRef {
     type: string;
     description: string;

package/dist/tools/index.d.ts

@@ -1,2 +1,2 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerTools(server: McpServer, projectId: string, user: string): void;
+export declare function registerTools(server: McpServer, projectId: string, _user: string): void;

package/dist/tools/index.js

@@ -1,10 +1,6 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
-export function registerTools(server, projectId, user) {
-    // 日志辅助函数
-    const log = (action, target, nodeId) => {
-        storage.appendLog(projectId, { user, action, target, node_id: nodeId });
-    };
+export function registerTools(server, projectId, _user) {
     // 1. 创建节点
     server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍', {
         title: z.string().describe('节点标题'),
@@ -29,15 +25,11 @@ export function registerTools(server, projectId, user) {
             categories: args.tags || [],
             dependencies: args.dependencies || []
         });
-        log('create_node', args.title, node.id);
         return { content: [{ type: 'text', text: JSON.stringify(node, null, 2) }] };
     });
     // 2. 删除节点
     server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
-        const node = await storage.getNode(projectId, args.nodeId);
         const success = await storage.deleteNode(projectId, args.nodeId);
-        if (success)
-            log('delete_node', node?.title || args.nodeId, args.nodeId);
         return { content: [{ type: 'text', text: success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)' }] };
     });
     // 3. 更新节点
@@ -57,18 +49,13 @@ export function registerTools(server, projectId, user) {
         // API 参数 tags 转换为内部字段 categories
         const updates = tags !== undefined ? { ...rest, categories: tags } : rest;
         const node = await storage.updateNode(projectId, nodeId, updates);
-        if (node)
-            log('update_node', node.title, nodeId);
         return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)' }] };
     });
-    // 4. 锁定/解锁节点
-    server.tool('kg_lock_node', '锁定/解锁节点(锁定后只能读取)', {
-        nodeId: z.string().describe('节点ID'),
-        locked: z.boolean().describe('true=锁定, false=解锁')
+    // 4. 锁定节点 (只能锁定，解锁需用户在前端手动操作)
+    server.tool('kg_lock_node', '锁定节点(锁定后只能读取，解锁需用户在前端手动操作)', {
+        nodeId: z.string().describe('节点ID')
     }, async (args) => {
-        const node = await storage.lockNode(projectId, args.nodeId, args.locked);
-        if (node)
-            log(args.locked ? 'lock_node' : 'unlock_node', node.title, args.nodeId);
+        const node = await storage.lockNode(projectId, args.nodeId, true); // 强制锁定
         return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '操作失败' }] };
     });
     // 5. 搜索节点
@@ -142,8 +129,7 @@ export function registerTools(server, projectId, user) {
             description: args.description,
             goals: args.goals || [],
             related_nodes: args.related_nodes
-        }, user);
-        log('create_task', args.title, task.id);
+        }, _user);
         return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
     });
     // 11. 列出任务
@@ -181,7 +167,6 @@ export function registerTools(server, projectId, user) {
         if (!task) {
             return { content: [{ type: 'text', text: '添加失败(任务不存在或已归档)' }] };
         }
-        log('add_task_log', `${args.log_type}: ${args.content.slice(0, 50)}...`, args.taskId);
         return { content: [{ type: 'text', text: `日志已添加，任务共有 ${task.logs.length} 条日志` }] };
     });
     // 14. 完成任务
@@ -204,7 +189,6 @@ export function registerTools(server, projectId, user) {
         if (!task) {
             return { content: [{ type: 'text', text: '完成失败(任务不存在或已归档)' }] };
         }
-        log('complete_task', task.title, args.taskId);
         return { content: [{ type: 'text', text: `任务已完成归档: ${task.title}` }] };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
     "ppdocs-mcp": "dist/index.js"
   },
   "scripts": {
+    "prebuild": "node scripts/copy-templates.js",
     "build": "tsc",
     "start": "node dist/index.js"
   },

package/templates/commands/init.md

@@ -0,0 +1,106 @@
+---
+description: 初始化知识图谱：100%扫描代码库，为每个模块创建完整的图表化知识节点
+---
+
+# /init 项目初始化
+
+执行 `task_create("项目初始化: [项目名]")` → 递归扫描全部代码文件 → 逐文件审查创建节点 → 每处理5个文件调用 `task_add_log(progress)` 同步进度 → 全部完成后 `task_complete` 输出统计报告
+
+## 扫描规则
+
+**100%覆盖**: 递归遍历项目所有目录，不遗漏任何代码文件
+
+**忽略目录**: node_modules, dist, build, .git, .next, .nuxt, target, __pycache__
+
+**忽略文件**: .env*, *.lock, *.log, *.min.js, *.map, 图片(png/jpg/svg/ico), 字体(ttf/woff)
+
+**扫描顺序**: ①入口(main/index/App/lib.rs) → ②配置(package.json/tsconfig/Cargo.toml) → ③核心目录按字母序
+
+## 节点字段规范
+
+每个节点必须填写以下字段，不可遗漏：
+
+| 字段 | 必填 | 说明 |
+|:---|:---|:---|
+| title | ✅ | 格式 `[模块]:[文件名] 中文描述`，如 `Auth:login 用户登录处理` |
+| type | ✅ | `logic`(函数/组件/流程) `data`(类型/接口/结构) `intro`(架构/概念/说明) |
+| status | ✅ | 初始化统一设为 `incomplete`，待用户确认后改 `complete` |
+| signature | ✅ | 用于依赖匹配的唯一标识：函数名/类名/组件名/模块路径 |
+| categories | ✅ | 从17种分类中选择: ui/function/class/library/reusable/snippet/data/logic/api/config/util/service/model/constant/type/hook/middleware |
+| description | ✅ | **必须包含Mermaid流程图+表格**，禁止纯文字，详见下方模板 |
+| dataInput | 函数必填 | `{type: "类型定义", description: "参数说明"}` |
+| dataOutput | 函数必填 | `{type: "返回类型", description: "返回值说明"}` |
+| dependencies | ✅ | 依赖的其他模块 `[{name: "目标signature", description: "依赖原因"}]`，无依赖填空数组 |
+| relatedFiles | ✅ | 关联的源文件路径数组，如 `["src/services/auth.ts"]` |
+
+## description 模板
+
+### logic节点 (函数/组件/Hook)
+```markdown
+```mermaid
+flowchart LR
+    A[入口/触发] --> B{条件判断}
+    B -->|成功| C[核心处理]
+    B -->|失败| D[错误处理]
+    C --> E[返回结果]
+```
+
+| 接口 | 类型 | 说明 |
+|:---|:---|:---|
+| Input | `ParamType` | 参数描述 |
+| Output | `ReturnType` | 返回值描述 |
+
+**核心逻辑**: 一句话描述函数职责
+```
+
+### data节点 (类型/接口/枚举)
+```markdown
+```mermaid
+classDiagram
+    class TypeName {
+        +fieldType field1
+        +fieldType field2
+    }
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|:---|:---|:---|:---|
+| field1 | string | ✅ | 字段用途 |
+| field2 | number | ❌ | 字段用途 |
+```
+
+### intro节点 (架构/模块说明)
+```markdown
+```mermaid
+flowchart TB
+    subgraph 模块名[模块职责]
+        A --> B --> C
+    end
+```
+
+**职责**: 模块核心功能描述
+**关键依赖**: 列出核心依赖模块
+```
+
+## 进度同步
+
+每处理5个文件或完成1个目录后，调用 `task_add_log("progress", "已处理: [文件列表], 创建节点: N个")`
+
+## 完成输出
+
+`task_complete` 时输出完整统计：
+
+```markdown
+| 统计项 | 数量 |
+|:---|:---|
+| 扫描文件 | N |
+| 创建节点 | N |
+| 依赖关系 | N |
+
+| 目录 | 文件数 | 节点数 | 覆盖率 |
+|:---|:---|:---|:---|
+| src/components | 12 | 12 | 100% |
+| src/services | 8 | 8 | 100% |
+
+**待人工补充**: [列出复杂度高需要人工完善description的节点]
+```

package/templates/commands/pp/init.md

@@ -0,0 +1,106 @@
+---
+description: 初始化知识图谱：100%扫描代码库，为每个模块创建完整的图表化知识节点
+---
+
+# /init 项目初始化
+
+执行 `task_create("项目初始化: [项目名]")` → 递归扫描全部代码文件 → 逐文件审查创建节点 → 每处理5个文件调用 `task_add_log(progress)` 同步进度 → 全部完成后 `task_complete` 输出统计报告
+
+## 扫描规则
+
+**100%覆盖**: 递归遍历项目所有目录，不遗漏任何代码文件
+
+**忽略目录**: node_modules, dist, build, .git, .next, .nuxt, target, __pycache__
+
+**忽略文件**: .env*, *.lock, *.log, *.min.js, *.map, 图片(png/jpg/svg/ico), 字体(ttf/woff)
+
+**扫描顺序**: ①入口(main/index/App/lib.rs) → ②配置(package.json/tsconfig/Cargo.toml) → ③核心目录按字母序
+
+## 节点字段规范
+
+每个节点必须填写以下字段，不可遗漏：
+
+| 字段 | 必填 | 说明 |
+|:---|:---|:---|
+| title | ✅ | 格式 `[模块]:[文件名] 中文描述`，如 `Auth:login 用户登录处理` |
+| type | ✅ | `logic`(函数/组件/流程) `data`(类型/接口/结构) `intro`(架构/概念/说明) |
+| status | ✅ | 初始化统一设为 `incomplete`，待用户确认后改 `complete` |
+| signature | ✅ | 用于依赖匹配的唯一标识：函数名/类名/组件名/模块路径 |
+| categories | ✅ | 从17种分类中选择: ui/function/class/library/reusable/snippet/data/logic/api/config/util/service/model/constant/type/hook/middleware |
+| description | ✅ | **必须包含Mermaid流程图+表格**，禁止纯文字，详见下方模板 |
+| dataInput | 函数必填 | `{type: "类型定义", description: "参数说明"}` |
+| dataOutput | 函数必填 | `{type: "返回类型", description: "返回值说明"}` |
+| dependencies | ✅ | 依赖的其他模块 `[{name: "目标signature", description: "依赖原因"}]`，无依赖填空数组 |
+| relatedFiles | ✅ | 关联的源文件路径数组，如 `["src/services/auth.ts"]` |
+
+## description 模板
+
+### logic节点 (函数/组件/Hook)
+```markdown
+```mermaid
+flowchart LR
+    A[入口/触发] --> B{条件判断}
+    B -->|成功| C[核心处理]
+    B -->|失败| D[错误处理]
+    C --> E[返回结果]
+```
+
+| 接口 | 类型 | 说明 |
+|:---|:---|:---|
+| Input | `ParamType` | 参数描述 |
+| Output | `ReturnType` | 返回值描述 |
+
+**核心逻辑**: 一句话描述函数职责
+```
+
+### data节点 (类型/接口/枚举)
+```markdown
+```mermaid
+classDiagram
+    class TypeName {
+        +fieldType field1
+        +fieldType field2
+    }
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|:---|:---|:---|:---|
+| field1 | string | ✅ | 字段用途 |
+| field2 | number | ❌ | 字段用途 |
+```
+
+### intro节点 (架构/模块说明)
+```markdown
+```mermaid
+flowchart TB
+    subgraph 模块名[模块职责]
+        A --> B --> C
+    end
+```
+
+**职责**: 模块核心功能描述
+**关键依赖**: 列出核心依赖模块
+```
+
+## 进度同步
+
+每处理5个文件或完成1个目录后，调用 `task_add_log("progress", "已处理: [文件列表], 创建节点: N个")`
+
+## 完成输出
+
+`task_complete` 时输出完整统计：
+
+```markdown
+| 统计项 | 数量 |
+|:---|:---|
+| 扫描文件 | N |
+| 创建节点 | N |
+| 依赖关系 | N |
+
+| 目录 | 文件数 | 节点数 | 覆盖率 |
+|:---|:---|:---|:---|
+| src/components | 12 | 12 | 100% |
+| src/services | 8 | 8 | 100% |
+
+**待人工补充**: [列出复杂度高需要人工完善description的节点]
+```

package/templates/commands/pp/review.md

@@ -0,0 +1,60 @@
+---
+description: 全维度智能代码审查：架构、逻辑、规范与冗余治理
+argument-hint: "[all|recent]"
+---
+
+# Role
+你是一位拥有10年以上经验的资深软件架构师和代码审查专家。你的目标是确保代码库保持“整洁架构（Clean Architecture）”标准，具备高可维护性、高性能和安全性。
+
+# Input Context
+根据参数 `$ARGUMENTS` 确定审查范围：
+- **recent**: 仅审查最近修改的文件（基于 git diff 上下文或文件最后修改时间）。
+- **all** (默认): 递归审查整个项目的所有代码文件。
+
+# Workflow
+请严格按照以下维度对代码进行深度扫描，并输出审查报告：
+
+## 1. 🧹 冗余与废弃物清理 (Redundancy Cleanup)
+- **重复代码 (DRY原则)**: 识别雷同的代码块，特别是跨文件复制粘贴的逻辑。
+- **僵尸代码**: 标记未使用的变量、函数、类导入（Imports）以及无法到达的代码分支（Dead Code）。
+- **注释清理**: 移除被注释掉的旧代码块，移除无意义的冗余注释。
+
+## 2. 🔄 版本一致性与冲突 (Version Control)
+- **混合代码检测**: 严查新旧API混用情况，确保同一功能仅使用最新版本的实现方式。
+- **冲突标记**: 扫描是否存在未解决的 Git 合并冲突标记（如 `<<<<<<< HEAD`）。
+- **废弃特性**: 识别并建议替换已标记为 Deprecated 的方法或库。
+
+## 3. 🧩 模块化与复用 (Modularity & Reusability)
+- **组件封装**: 检查UI代码，凡是出现相似结构超过2次的地方，必须建议封装为独立组件。
+- **工具函数提取**: 将通用的逻辑处理（如日期格式化、数据校验）建议提取到 `/utils` 或 `/hooks` 目录。
+- **单一职责 (SRP)**: 确保每个函数/类只做一件事，避免“上帝类（God Class）”。
+
+## 4. 🧠 逻辑与健壮性 (Logic & Robustness)
+- **流程分析**: 模拟代码执行路径，检查逻辑闭环。
+- **边界情况**: 重点审查空指针（Null/Undefined）、数组越界、除以零等异常情况。
+- **错误处理**: 检查是否缺少必要的 `try-catch` 块或错误回退（Fallback）机制。
+
+## 5. 📦 依赖与环境 (Dependencies)
+- **依赖瘦身**: 识别 `package.json` 或 `requirements.txt` 中声明但未使用的库。
+- **版本健康**: (如果可能) 提示过旧的依赖版本，建议升级到稳定版。
+
+## 6. 🎨 代码风格与文件结构 (Style & Structure)
+- **可读性**: 变量/函数命名应具备语义化（Self-documenting），避免使用 `a`, `b`, `temp` 等模糊命名。
+- **文件拆分**: 对于超过 300 行的代码文件，强制建议按功能拆分到子目录中。
+- **目录规范**: 建议按功能模块（Feature-based）或类型（Type-based）对文件进行分组归档。
+
+## 7. 📚 知识同步 (Knowledge Sync)
+- **一致性检查**: 尝试将当前代码逻辑与知识库（Knowledge Graph/MCP）中的定义进行比对。
+- **异常处理**: 如果未检测到知识库MCP连接，请忽略此步骤，不要报错，仅需在报告末尾标注“*知识库未连接，跳过同步检查*”。
+
+# Output Format
+请以 Markdown 格式输出审查报告，包含以下部分：
+
+1.  **审查摘要**: 简述扫描了哪些文件，总体评分（1-10分）。
+2.  **问题详情 (按严重程度排序)**:
+    -   🔴 **[Critical]**: 逻辑错误、版本冲突、安全隐患。
+    -   🟡 **[Warning]**: 冗余代码、未使用变量、复杂的函数。
+    -   🔵 **[Suggestion]**: 命名优化、目录结构调整、注释建议。
+3.  **重构建议**: 针对重点问题，提供 *Before* vs *After* 的代码对比示例。
+
+---

package/templates/commands/pp/sync.md

@@ -0,0 +1,110 @@
+# 代码同步知识图谱 (通用)
+
+**参数**: `$ARGUMENTS` = `init` | `diff` | `check`
+
+---
+
+## Phase 1: 项目探测
+
+**自动识别技术栈**:
+```
+检测文件 → 技术栈推断
+├─ package.json     → Node/React/Vue (读 dependencies 确认框架)
+├─ Cargo.toml       → Rust
+├─ go.mod           → Go
+├─ pom.xml          → Java/Maven
+├─ requirements.txt → Python
+└─ src-tauri/       → Tauri 混合应用
+```
+
+**动态架构分析**:
+1. 读取入口配置文件，识别 `src/` 等源码目录
+2. Glob 扫描，按目录层级聚类
+3. 输出架构树，让用户确认模块划分
+
+---
+
+## Phase 2: 架构设计 (交互式)
+
+**输出格式** (等待用户确认/调整):
+```
+┌─ 📁 推断架构 ──────────────────────┐
+│ [intro] 项目根: {项目名}           │
+│ ├─ [intro] {模块A}: {路径A}        │
+│ ├─ [intro] {模块B}: {路径B}        │
+│ └─ [data]  共享类型: **/types.*    │
+└────────────────────────────────────┘
+用户可调整模块名称和层级，回复 OK 继续
+```
+
+---
+
+## Phase 3: 节点生成规则
+
+**通用映射** (根据文件用途自动分类):
+
+| 识别模式 | type | signature 格式 | tags 推断 |
+|:---|:---|:---|:---|
+| `页面/路由` (pages/views/routes) | logic | `Page:{名称}` | `[ui, page]` |
+| `组件` (components) | logic | `Comp:{名称}` | `[ui, component]` |
+| `Hook/Composable` (use*.ts/use*.js) | logic | `{名称}()` | `[hook]` |
+| `服务层` (services/api) | logic | `Svc:{名称}` | `[service, api]` |
+| `存储层` (store/storage) | logic | `Store:{名称}` | `[storage]` |
+| `工具函数` (utils/helpers/lib) | logic | `{函数名}()` | `[util, reusable]` |
+| `类型定义` (types/interfaces/models) | data | `Type:{名称}` | `[type]` |
+| `配置` (config/*.json/yaml) | intro | `Config:{名称}` | `[config]` |
+| `Rust mod` (*.rs) | logic | `{mod}::{fn}` | `[rust]` |
+| `Go pkg` (*.go) | logic | `{pkg}.{Func}` | `[go]` |
+
+**description 提取**:
+```markdown
+## 职责
+[读取文件注释/JSDoc/docstring，无则根据代码推断]
+
+## 核心逻辑
+[提取 export 的函数/类，列出关键方法]
+
+## 依赖
+[解析 import/require/use 语句，匹配已有节点]
+```
+
+---
+
+## Phase 4: 执行同步
+
+```
+┌──────────┐  kg_list_nodes  ┌──────────┐  匹配signature  ┌──────────┐
+│ 扫描文件  │ ─────────────▶ │ 查已有节点 │ ─────────────▶ │ 差异对比  │
+└──────────┘                 └──────────┘                 └────┬─────┘
+                                                               │
+     ┌─────────────────────────────────────────────────────────┘
+     │ 新文件 → kg_create_node
+     │ 已存在且内容变化 → kg_update_node
+     │ 已存在且无变化 → 跳过
+     ▼
+┌──────────────────────────────────────────────────────────┐
+│ 进度: [X/N] ✅ path/file.ts → NodeTitle (created/updated)│
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 5: 覆盖率报告
+
+```
+┌─────────────────────────────────────┐
+│ 📊 同步完成                         │
+│ 文件: XX | ✅新增: X | 🔄更新: X     │
+│ ❌ 未覆盖: [列表]                    │
+│ 📈 覆盖率: XX.X%                    │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 约束
+
+1. **批量限制**: 每轮 ≤10 文件
+2. **顺序优先级**: types → utils → services → components → pages
+3. **去重**: 写入前 `kg_search` 检查 signature 冲突
+4. **依赖推断**: 仅关联已存在节点的 signature

package/templates/hooks/SystemPrompt.md

@@ -0,0 +1,87 @@
+---
+description: 全周期智能开发：图表化沟通、知识库驱动、用户确认制
+role: 资深全栈架构师 & 知识库维护者
+---
+
+# 核心原则
+1. **沟通优先**: 图表化自然语言沟通，编码前不生成代码，只描述抽象逻辑
+2. **知识驱动**: 任何修改必须先查知识库(理论)再看代码(实际)，双重验证
+3. **用户确认**: 方案展示、执行、完成均需用户明确确认
+4. **经验沉淀**: 踩坑必记录，通过必总结，知识库持续进化
+
+# 图表化沟通规范
+与用户交流使用 **Mermaid图表 + 表格**，禁止大段文字，仅执行阶段输出代码。
+
+# 工作流程
+
+## ⓪ 启动检查
+调用 `task_list(status: "active")`，若有未完成任务，展示列表询问：**继续** / **放弃归档** / **新建**
+
+## ① 需求理解
+任何不确定点必须向用户提问。使用 `kg_search` 查找相关节点理解项目，展示理解结果等用户确认。
+
+## ② 双重分析
+| 阶段 | 工具 | 目的 |
+|:---|:---|:---|
+| 知识库 | `kg_search` `kg_get_relations` | 理解设计意图、依赖关系 |
+| 代码 | 读取文件 | 验证实际实现、发现偏差 |
+
+## ③ 方案制定与展示
+创建任务 `task_create`，**必须向用户展示以下对比内容**：
+
+### 变更对比表 (必须)
+| 文件/模块 | 当前状态 | 改动后 | 变更说明 |
+|:---|:---|:---|:---|
+| src/auth.ts | Session认证 | JWT认证 | 无状态，易扩展 |
+| src/store.ts | 无 | 新增TokenStore | 管理令牌刷新 |
+
+### 逻辑流程对比 (必须)
+```mermaid
+flowchart LR
+    subgraph 当前
+        A1[登录] --> B1[创建Session] --> C1[存Cookie]
+    end
+    subgraph 改动后
+        A2[登录] --> B2[签发JWT] --> C2[存LocalStorage]
+        C2 --> D2[自动刷新]
+    end
+```
+
+### 影响范围
+| 类型 | 内容 |
+|:---|:---|
+| 修改文件 | `auth.ts`, `api.ts` |
+| 新增文件 | `tokenStore.ts` |
+| 删除文件 | `sessionManager.ts` |
+| 依赖变更 | 新增 `jsonwebtoken` |
+
+### 风险评估
+| 风险点 | 等级 | 应对措施 |
+|:---|:---|:---|
+| Token泄露 | 中 | HttpOnly + 短过期 |
+
+**模拟验证**: 脑中推演流程图，检查死逻辑/边界遗漏，无误后展示
+
+## ④ 用户确认
+展示完整方案后，等待用户回复 **"确认"/"OK"** 才执行。用户可提修改意见迭代方案。
+
+## ⑤ 执行编码
+遵守：复用已有组件、物理删除旧代码、单文件≤150行。每完成子任务 `task_add_log(progress)`
+
+## ⑥ 测试验证
+提供测试命令协助验证。**不通过时**：
+1. `task_add_log(issue)` 记录失败原因
+2. `task_add_log(solution)` 记录修复方案
+3. 知识库记录避免重复踩坑
+
+## ⑦ 任务完成
+测试通过后等用户确认 **"验收通过"**，然后：
+1. `kg_update_node` / `kg_create_node` 更新知识库
+2. `task_complete` 填写：难点、解决方案、参考资料
+
+# 禁止事项
+- 未经确认擅自修改代码
+- 跳过知识库直接改代码
+- 沟通时输出大段代码
+- 方案不展示对比图表
+- 任务未完成开始新任务

package/templates/settings-hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "type \".claude\\hooks\\SystemPrompt.md\""
+          }
+        ]
+      }
+    ]
+  }
+}