@ppdocs/mcp 3.1.2 → 3.1.4

package/README.md

@@ -47,8 +47,12 @@ npx @ppdocs/mcp init -p <项目ID> -k <密钥>
 
 这会自动：
 - 创建 `.ppdocs` 配置文件
-- 创建 `.mcp.json` MCP 配置
-- 安装工作流模板到 `.claude/`
+- 检测工作区 IDE 配置目录，自动安装对应模板：
+  - `.claude/` → Claude Code 工作流模板 + MCP 权限
+  - `.cursor/` → Cursor MCP 配置 + .cursorrules
+  - `.gemini/` → Antigravity MCP 配置 + AGENTS.md
+  - `.kiro/` → Kiro MCP 配置 + Agent 规则
+- 自动检测并注册 CLI MCP (claude/codex/gemini)
 
 ### 3. 配置 Claude Desktop
 

package/dist/cli.js

@@ -7,6 +7,7 @@ import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import { generateUser } from './config.js';
+import { PpdocsApiClient } from './storage/httpClient.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
 function parseArgs(args) {
@@ -62,6 +63,20 @@ function parseArgs(args) {
         else if (arg === '--codex') {
             opts.codex = true;
         }
+        else if (arg === '--from') {
+            if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+                console.error('Error: --from requires a project ID');
+                return null;
+            }
+            opts.from = args[++i];
+        }
+        else if (arg === '--sync') {
+            if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+                console.error('Error: --sync requires a project ID');
+                return null;
+            }
+            opts.sync = args[++i];
+        }
     }
     if (!opts.project || !opts.key)
         return null;
@@ -86,10 +101,14 @@ Options:
   --port         API port (default: 20001)
   --api          API host (default: localhost)
   --codex        Codex mode: generate AGENTS.md instead of .claude/
+  --from <id>    Pull IDE configs from a template project
+  --sync <id>    Sync knowledge base docs from a source project to ./docs/ppdocs/
 
 Example:
   npx @ppdocs/mcp init -p myproject -k abc123xyz
   npx @ppdocs/mcp init -p myproject -k abc123xyz --codex
+  npx @ppdocs/mcp init -p myproject -k abc123xyz --from _templates
+  npx @ppdocs/mcp init -p myproject -k abc123xyz --sync shared-rules
 `);
 }
 export function runCli(args) {
@@ -101,7 +120,10 @@ export function runCli(args) {
             showHelp();
             process.exit(1);
         }
-        initProject(opts);
+        initProject(opts).catch(e => {
+            console.error(`❌ Init failed: ${e}`);
+            process.exit(1);
+        });
         return true;
     }
     if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
@@ -110,7 +132,7 @@ export function runCli(args) {
     }
     return false; // Not a CLI command, run as MCP server
 }
-function initProject(opts) {
+async function initProject(opts) {
     const cwd = process.cwd();
     const apiUrl = `http://${opts.api}:${opts.port}/api/${opts.project}/${opts.key}`;
     // Create .ppdocs config
@@ -131,19 +153,48 @@ function initProject(opts) {
     }
     fs.writeFileSync(ppdocsPath, JSON.stringify(ppdocsConfig, null, 2));
     console.log(`✅ Created ${ppdocsPath}`);
-    // Install workflow templates
-    if (opts.codex) {
-        installCodexTemplates(cwd);
-    }
-    else {
+    // Install workflow templates based on IDE detection
+    const detectedIdes = detectIDEs(cwd);
+    let hasIdeDir = false;
+    if (detectedIdes.includes('claude')) {
         installClaudeTemplates(cwd);
+        hasIdeDir = true;
+    }
+    if (detectedIdes.includes('cursor')) {
+        installCursorTemplates(cwd);
+        hasIdeDir = true;
+    }
+    if (detectedIdes.includes('antigravity')) {
+        installAntigravityTemplates(cwd);
+        hasIdeDir = true;
+    }
+    if (detectedIdes.includes('kiro')) {
+        installKiroTemplates(cwd);
+        hasIdeDir = true;
+    }
+    // Fallback behavior: if no specific IDE config directories found
+    if (!hasIdeDir) {
+        if (opts.codex) {
+            installCodexTemplates(cwd);
+        }
+        else {
+            installClaudeTemplates(cwd); // Default to Claude templates
+        }
     }
     // 自动检测并注册 MCP
     const registered = autoRegisterMcp(apiUrl, opts.user);
-    // 如果没有检测到任何 AI CLI，创建 .mcp.json 作为备用
-    if (!registered) {
+    // 如果没有检测到任何 AI CLI，并且也没有检测到配置文件夹，创建 .mcp.json 作为备用
+    if (!registered && !hasIdeDir) {
         createMcpJson(cwd);
     }
+    // --from: 从模板项目拉取 IDE 配置文件
+    if (opts.from) {
+        await pullTemplateProject(cwd, apiUrl, opts.from);
+    }
+    // --sync: 从源项目同步知识库文档到本地
+    if (opts.sync) {
+        await syncKnowledgeBase(cwd, apiUrl, opts.sync);
+    }
     console.log(`
 🎉 Done! ppdocs MCP configured for project: ${opts.project}
    User: ${opts.user}
@@ -151,6 +202,65 @@ function initProject(opts) {
 Restart your AI tool to use ppdocs knowledge graph.
 `);
 }
+/** 从模板项目拉取 IDE 配置到当前项目目录 */
+async function pullTemplateProject(cwd, apiUrl, templateId) {
+    console.log(`📦 Pulling IDE configs from template project: ${templateId}...`);
+    try {
+        const client = new PpdocsApiClient(apiUrl);
+        const files = await client.crossListFiles(templateId);
+        if (files.length === 0) {
+            console.log(`⚠️  Template project "${templateId}" has no files (upload files via the desktop app first)`);
+            return;
+        }
+        const result = await client.crossDownload(templateId, '/', cwd);
+        console.log(`✅ Pulled ${result.fileCount} files from template project "${templateId}"`);
+    }
+    catch (e) {
+        console.log(`⚠️  Failed to pull from template project: ${e}`);
+    }
+}
+/** 从源项目同步知识库文档到本地 ./docs/ppdocs/ */
+async function syncKnowledgeBase(cwd, apiUrl, sourceId) {
+    console.log(`📚 Syncing knowledge base from project: ${sourceId}...`);
+    try {
+        const client = new PpdocsApiClient(apiUrl);
+        const docs = await client.crossListDocs(sourceId);
+        const docNodes = docs.filter(d => !d.isDir);
+        if (docNodes.length === 0) {
+            console.log(`⚠️  Project "${sourceId}" has no knowledge base documents`);
+            return;
+        }
+        const docsDir = path.join(cwd, 'docs', 'ppdocs', sourceId);
+        fs.mkdirSync(docsDir, { recursive: true });
+        let synced = 0;
+        for (const node of docNodes) {
+            const doc = await client.crossGetDoc(sourceId, node.path);
+            if (!doc)
+                continue;
+            // 将文档路径转为本地文件路径 (e.g. "/前端/组件/Modal" → "前端/组件/Modal.md")
+            const safePath = node.path.replace(/^\//, '').replace(/[<>:"|?*]/g, '_');
+            const localFile = path.join(docsDir, `${safePath}.md`);
+            const localDir = path.dirname(localFile);
+            if (!fs.existsSync(localDir)) {
+                fs.mkdirSync(localDir, { recursive: true });
+            }
+            // 生成 Markdown 文件内容
+            const content = [
+                `# ${node.name}`,
+                '',
+                doc.summary ? `> ${doc.summary}` : '',
+                '',
+                doc.content || '',
+            ].filter(Boolean).join('\n');
+            fs.writeFileSync(localFile, content, 'utf-8');
+            synced++;
+        }
+        console.log(`✅ Synced ${synced} documents from "${sourceId}" to docs/ppdocs/${sourceId}/`);
+    }
+    catch (e) {
+        console.log(`⚠️  Failed to sync knowledge base: ${e}`);
+    }
+}
 /** 检测命令是否存在 */
 function commandExists(cmd) {
     try {
@@ -233,9 +343,8 @@ function autoRegisterMcp(apiUrl, user) {
     console.log(`✅ Registered MCP for: ${detected.join(', ')}`);
     return true;
 }
-/** 创建 .mcp.json (手动配置备用) */
-function createMcpJson(cwd) {
-    const mcpPath = path.join(cwd, '.mcp.json');
+/** 在指定路径创建或更新 mcp.json 配置 */
+function createMcpConfigAt(mcpPath, autoCreatedTemplate) {
     let mcpConfig = {};
     if (fs.existsSync(mcpPath)) {
         try {
@@ -248,14 +357,23 @@ function createMcpJson(cwd) {
     // Windows 需要 cmd /c 包装才能执行 npx
     const isWindows = process.platform === 'win32';
     const ppdocsServer = isWindows
-        ? { command: 'cmd', args: ['/c', 'npx', '@ppdocs/mcp@latest'] }
-        : { command: 'npx', args: ['@ppdocs/mcp@latest'] };
+        ? { command: 'cmd', args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'] }
+        : { command: 'npx', args: ['-y', '@ppdocs/mcp@latest'] };
     mcpConfig.mcpServers = {
         ...(mcpConfig.mcpServers || {}),
-        ppdocs: ppdocsServer,
+        "ppdocs-kg": ppdocsServer,
     };
+    // 确保父目录存在
+    const parentDir = path.dirname(mcpPath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
     fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2));
-    console.log(`✅ Created ${mcpPath}`);
+    console.log(`✅ Configured MCP in ${mcpPath}`);
+}
+/** 创建 .mcp.json (手动配置备用) */
+function createMcpJson(cwd) {
+    createMcpConfigAt(path.join(cwd, '.mcp.json'));
 }
 /** 递归复制目录 */
 function copyDirRecursive(src, dest) {
@@ -363,13 +481,65 @@ function installClaudeTemplates(cwd) {
 }
 /** 安装 Codex 模板 (生成 AGENTS.md) */
 function installCodexTemplates(cwd) {
+    generateAgentsMd(cwd);
+}
+/** 生成 AGENTS.md 工具函数 (去重) */
+function generateAgentsMd(cwd) {
     const srcPrompt = path.join(TEMPLATES_DIR, 'hooks', 'SystemPrompt.md');
     const destAgents = path.join(cwd, 'AGENTS.md');
-    if (fs.existsSync(srcPrompt)) {
+    if (fs.existsSync(srcPrompt) && !fs.existsSync(destAgents)) {
         fs.copyFileSync(srcPrompt, destAgents);
-        console.log(`✅ Created AGENTS.md (Codex mode)`);
+        console.log(`✅ Created AGENTS.md`);
     }
-    else {
+    else if (!fs.existsSync(srcPrompt)) {
         console.log(`⚠️  SystemPrompt.md template not found`);
     }
 }
+/** 安装 Cursor 模板 */
+function installCursorTemplates(cwd) {
+    // 1. 生成 Cursor MCP 配置
+    createMcpConfigAt(path.join(cwd, '.cursor', 'mcp.json'));
+    // 2. 生成 .cursorrules 提示词
+    const srcRules = path.join(TEMPLATES_DIR, 'cursorrules.md');
+    const destRules = path.join(cwd, '.cursorrules');
+    if (fs.existsSync(srcRules) && !fs.existsSync(destRules)) {
+        fs.copyFileSync(srcRules, destRules);
+        console.log(`✅ Created .cursorrules`);
+    }
+}
+/** 安装 Antigravity (Gemini IDE) 模板 */
+function installAntigravityTemplates(cwd) {
+    // 1. 填充 .gemini/settings.json
+    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'));
+    // 2. 生成 AGENTS.md
+    generateAgentsMd(cwd);
+}
+/** 安装 Kiro 模板 */
+function installKiroTemplates(cwd) {
+    // 1. 生成 Kiro MCP 配置
+    createMcpConfigAt(path.join(cwd, '.kiro', 'settings', 'mcp.json'));
+    // 2. 生成 Kiro Agent 规则
+    const kiroRulesDir = path.join(cwd, '.kiro', 'rules');
+    if (!fs.existsSync(kiroRulesDir)) {
+        fs.mkdirSync(kiroRulesDir, { recursive: true });
+    }
+    const srcRules = path.join(TEMPLATES_DIR, 'kiro-rules', 'ppdocs.md');
+    const destRules = path.join(kiroRulesDir, 'ppdocs.md');
+    if (fs.existsSync(srcRules) && !fs.existsSync(destRules)) {
+        fs.copyFileSync(srcRules, destRules);
+        console.log(`✅ Created .kiro/rules/ppdocs.md`);
+    }
+}
+/** 检测当前工作区包含的 IDE */
+function detectIDEs(cwd) {
+    const ides = [];
+    if (fs.existsSync(path.join(cwd, '.claude')))
+        ides.push('claude');
+    if (fs.existsSync(path.join(cwd, '.cursor')))
+        ides.push('cursor');
+    if (fs.existsSync(path.join(cwd, '.gemini')))
+        ides.push('antigravity');
+    if (fs.existsSync(path.join(cwd, '.kiro')))
+        ides.push('kiro');
+    return ides;
+}

package/dist/tools/index.js

@@ -407,6 +407,65 @@ export function registerTools(server, projectId, _user) {
         const lines = docs.map(d => `- ${d.path} (${d.status || '已完成'}): ${d.summary || '无简介'}`);
         return wrap(`找到 ${docs.length} 个文档:\n\n${lines.join('\n')}`);
     });
+    // 12. 跨项目复制文档到当前项目
+    server.tool('kg_copy_node', '从其他项目复制文档到当前项目。支持单个或批量复制，可指定新路径。用于跨项目协作：拉取别的项目的知识文档到当前项目', {
+        sourceProject: z.string().describe('源项目ID或名称(从kg_list_projects获取)'),
+        sourcePath: z.union([z.string(), z.array(z.string())]).describe('源文档路径(单个或数组，如"/架构/数据流"或["/架构/数据流","/MCP/tools"])'),
+        targetPath: z.string().optional().describe('目标路径前缀(如"/参考/项目B")。不填则保持原路径'),
+    }, async (args) => {
+        const decoded = decodeObjectStrings(args);
+        const paths = Array.isArray(decoded.sourcePath) ? decoded.sourcePath : [decoded.sourcePath];
+        const results = [];
+        for (const srcPath of paths) {
+            try {
+                // 从源项目读取文档
+                const doc = await storage.crossGetDoc(decoded.sourceProject, srcPath);
+                if (!doc) {
+                    results.push({ path: srcPath, success: false, error: '源文档不存在' });
+                    continue;
+                }
+                // 计算目标路径
+                const destPath = decoded.targetPath
+                    ? `${decoded.targetPath.replace(/\/$/, '')}${srcPath}`
+                    : srcPath;
+                // 检查目标是否已存在
+                const existing = await storage.getDoc(projectId, destPath);
+                if (existing) {
+                    // 已存在则更新
+                    await storage.updateDoc(projectId, destPath, {
+                        summary: doc.summary,
+                        content: doc.content,
+                    });
+                    results.push({ path: destPath, success: true });
+                }
+                else {
+                    // 不存在则创建
+                    await storage.createDoc(projectId, destPath, {
+                        summary: doc.summary,
+                        content: doc.content,
+                        status: doc.status,
+                    });
+                    results.push({ path: destPath, success: true });
+                }
+            }
+            catch (e) {
+                results.push({ path: srcPath, success: false, error: String(e) });
+            }
+        }
+        const successCount = results.filter(r => r.success).length;
+        const failedItems = results.filter(r => !r.success);
+        if (paths.length === 1) {
+            if (results[0].success) {
+                return wrap(`✅ 已复制文档: ${results[0].path}\n\n来源: [${decoded.sourceProject}] ${paths[0]}`);
+            }
+            return wrap(`❌ 复制失败: ${results[0].error}`);
+        }
+        let msg = `✅ 批量复制完成: ${successCount}/${paths.length} 成功`;
+        if (failedItems.length > 0) {
+            msg += `\n❌ 失败:\n${failedItems.map(f => `  - ${f.path}: ${f.error}`).join('\n')}`;
+        }
+        return wrap(msg);
+    });
     // ===================== 任务管理 =====================
     // 7. 创建任务
     server.tool('task_create', '创建开发任务', {

package/package.json

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

package/templates/README.md

@@ -10,6 +10,8 @@
 | `hooks/SystemPrompt.md` | 系统提示词模板 | `.claude/hooks/SystemPrompt.md` |
 | `commands/pp/` | Claude Code 自定义命令 | `.claude/commands/pp/` |
 | `AGENT.md` | Codex/通用 Agent 提示词 | `./AGENTS.md` |
+| `cursorrules.md` | Cursor IDE 提示词 | `.cursorrules` |
+| `kiro-rules/ppdocs.md` | Kiro IDE Agent 规则 | `.kiro/rules/ppdocs.md` |
 
 ## 安装命令
 
@@ -23,15 +25,19 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ## 安装流程
 
-### 默认模式 (Claude Code)
+### 自动检测模式 (默认)
 
-1. 生成 `.ppdocs` 配置文件 (api/projectId/key)
-2. 复制 `templates/commands/pp/` → `.claude/commands/pp/`
-3. 复制 `templates/hooks/` → `.claude/hooks/`
-4. 动态生成 hooks 配置 → 合并到 `.claude/settings.json`
-5. 自动检测并注册 MCP
+CLI 通过 `detectIDEs()` 扫描项目目录，自动为检测到的 IDE 安装对应模板：
 
-### Codex 模式
+| 检测目录 | 安装动作 |
+|---------|--------|
+| `.claude/` | 复制 commands/pp/ + hooks/ → `.claude/`，生成 settings.json |
+| `.cursor/` | 生成 `.cursor/mcp.json` + `.cursorrules` |
+| `.gemini/` | 填充 `.gemini/settings.json` + 生成 `AGENTS.md` |
+| `.kiro/` | 生成 `.kiro/settings/mcp.json` + `.kiro/rules/ppdocs.md` |
+| 未检测到 | Fallback: Claude 模板 (默认) 或 `--codex` 走 Codex 模板 |
+
+### Codex 模式 (--codex)
 
 1. 生成 `.ppdocs` 配置文件
 2. 复制 `templates/hooks/SystemPrompt.md` → `./AGENTS.md`

package/templates/cursorrules.md

@@ -0,0 +1,102 @@
+你是严谨的软件架构师，围绕**用户知识图谱软件**工作，确保每个变动有据可查，每次成功沉淀为知识节点。
+
+## 核心宪法
+| 原则 | 要求 |
+|:---|:---|
+| **知识图谱中心** | 方案制定前检索图谱+代码双重验证；任务结束提示沉淀至图谱 |
+| **任务驱动开发** | 复杂任务必须 `task_create`；过程记录 `task_add_log`；完成 `task_complete` |
+| **规则引用** | 编码前读 `codeStyle`；测试前读 `testRules`；审查前读 `reviewRules` |
+| **绝对真实性** | 禁用 faker/模拟数据，必须真实环境验证 |
+| **沟通可视化** | 禁纯文字/Mermaid代码；强制 ASCII流程图 + Markdown表格 |
+| **极简模块化** | 拆解为原子函数，清理注释旧代码/Debug日志 |
+
+---
+
+## 任务生命周期
+```
+task_create → task_add_log(progress/issue/solution/reference) → task_complete
+```
+| 日志类型 | 用途 | 示例 |
+|:---|:---|:---|
+| `progress` | 阶段进度 | "完成Step2逻辑设计" |
+| `issue` | 遇到问题 | "API返回格式不一致" |
+| `solution` | 解决方案 | "添加数据转换层" |
+| `reference` | 参考资料 | "参考 xxx 文档" |
+
+---
+
+## 标准流程 (SOP)
+
+### Step 1: 分析与澄清
+1. 接收需求，识别意图
+2. `kg_search` 检索现有节点/历史坑点 (读取 bugfixes)
+3. `kg_get_rules()` 获取项目规则
+4. 有歧义则列选项供用户选择
+
+**输出**: 需求确认清单 (表格)
+
+### Step 2: 逻辑设计
+1. 结合图谱+代码设计方案
+2. `kg_get_rules(ruleType:"codeStyle")` 确认编码规范
+3. 检查现有复用函数，拒绝重复建设
+4. 大型任务: `task_create`
+
+**输出**: ASCII流程图 + 对比表 + 子任务列表
+**里程碑**: 等待用户确认 (不写代码)
+
+### Step 3: 模块化编码
+**前置**: 用户确认方案
+1. `task_add_log(progress, "开始编码")`
+2. 优先编写/更新工具函数，再业务组装
+3. 遵循 codeStyle 规则
+4. 清理现场，无残留代码
+
+**输出**: 结构清晰的代码
+
+### Step 4: 真实验证
+1. `kg_get_rules(ruleType:"testRules")` 获取测试规则
+2. 在 `tests/` 对应目录创建测试
+3. 真实环境运行，验证输出
+4. 失败时: `task_add_log(issue, "xxx失败")` → 回溯Step2
+
+**严禁**: "测试环境所以失败"借口
+
+### Step 5: 审查与沉淀
+1. `kg_get_rules(ruleType:"reviewRules")` 获取审查规则
+2. 审查目录结构/代码简洁度
+3. 发现BUG → `kg_update_node` 写入 bugfixes
+4. 新逻辑 → `kg_create_node` 或 `kg_update_node` (追加 versions)
+5. `task_complete({summary, difficulties, solutions, references})`
+
+**输出**: 交付确认 + 图谱更新清单
+
+---
+
+## 异常处理
+| 场景 | 反应 |
+|:---|:---|
+| Step4 测试失败 | 停止 → 分析日志 → task_add_log(issue) → 回溯Step2 → 修正 → 重测 |
+| 发现历史BUG | 读取节点 bugfixes 参考历史方案 |
+| 重复造轮子 | 终止 → 指出现有实现 → 要求复用 |
+
+---
+
+## 沟通协议
+**逻辑流程图 (ASCII)**:
+```
++----------+     +----------+     +----------+
+| Input    | --> | Logic A  | --> | Output   |
+| (KG DB)  |     | (func)   |     | (Result) |
++----------+     +----+-----+     +----------+
+                      |
+                 +----v-----+
+                 | Logic B  |
+                 | (error)  |
+                 +----------+
+```
+
+**对比表**:
+| 维度 | As-Is | To-Be | 风险 |
+|:---|:---|:---|:---|
+| 复用 | 重复造轮子 | 调用utils | 无 |
+| 结构 | 混杂views | 迁移services | 需改引用 |

package/templates/kiro-rules/ppdocs.md

@@ -0,0 +1,102 @@
+你是严谨的软件架构师，围绕**用户知识图谱软件**工作，确保每个变动有据可查，每次成功沉淀为知识节点。
+
+## 核心宪法
+| 原则 | 要求 |
+|:---|:---|
+| **知识图谱中心** | 方案制定前检索图谱+代码双重验证；任务结束提示沉淀至图谱 |
+| **任务驱动开发** | 复杂任务必须 `task_create`；过程记录 `task_add_log`；完成 `task_complete` |
+| **规则引用** | 编码前读 `codeStyle`；测试前读 `testRules`；审查前读 `reviewRules` |
+| **绝对真实性** | 禁用 faker/模拟数据，必须真实环境验证 |
+| **沟通可视化** | 禁纯文字/Mermaid代码；强制 ASCII流程图 + Markdown表格 |
+| **极简模块化** | 拆解为原子函数，清理注释旧代码/Debug日志 |
+
+---
+
+## 任务生命周期
+```
+task_create → task_add_log(progress/issue/solution/reference) → task_complete
+```
+| 日志类型 | 用途 | 示例 |
+|:---|:---|:---|
+| `progress` | 阶段进度 | "完成Step2逻辑设计" |
+| `issue` | 遇到问题 | "API返回格式不一致" |
+| `solution` | 解决方案 | "添加数据转换层" |
+| `reference` | 参考资料 | "参考 xxx 文档" |
+
+---
+
+## 标准流程 (SOP)
+
+### Step 1: 分析与澄清
+1. 接收需求，识别意图
+2. `kg_search` 检索现有节点/历史坑点 (读取 bugfixes)
+3. `kg_get_rules()` 获取项目规则
+4. 有歧义则列选项供用户选择
+
+**输出**: 需求确认清单 (表格)
+
+### Step 2: 逻辑设计
+1. 结合图谱+代码设计方案
+2. `kg_get_rules(ruleType:"codeStyle")` 确认编码规范
+3. 检查现有复用函数，拒绝重复建设
+4. 大型任务: `task_create`
+
+**输出**: ASCII流程图 + 对比表 + 子任务列表
+**里程碑**: 等待用户确认 (不写代码)
+
+### Step 3: 模块化编码
+**前置**: 用户确认方案
+1. `task_add_log(progress, "开始编码")`
+2. 优先编写/更新工具函数，再业务组装
+3. 遵循 codeStyle 规则
+4. 清理现场，无残留代码
+
+**输出**: 结构清晰的代码
+
+### Step 4: 真实验证
+1. `kg_get_rules(ruleType:"testRules")` 获取测试规则
+2. 在 `tests/` 对应目录创建测试
+3. 真实环境运行，验证输出
+4. 失败时: `task_add_log(issue, "xxx失败")` → 回溯Step2
+
+**严禁**: "测试环境所以失败"借口
+
+### Step 5: 审查与沉淀
+1. `kg_get_rules(ruleType:"reviewRules")` 获取审查规则
+2. 审查目录结构/代码简洁度
+3. 发现BUG → `kg_update_node` 写入 bugfixes
+4. 新逻辑 → `kg_create_node` 或 `kg_update_node` (追加 versions)
+5. `task_complete({summary, difficulties, solutions, references})`
+
+**输出**: 交付确认 + 图谱更新清单
+
+---
+
+## 异常处理
+| 场景 | 反应 |
+|:---|:---|
+| Step4 测试失败 | 停止 → 分析日志 → task_add_log(issue) → 回溯Step2 → 修正 → 重测 |
+| 发现历史BUG | 读取节点 bugfixes 参考历史方案 |
+| 重复造轮子 | 终止 → 指出现有实现 → 要求复用 |
+
+---
+
+## 沟通协议
+**逻辑流程图 (ASCII)**:
+```
++----------+     +----------+     +----------+
+| Input    | --> | Logic A  | --> | Output   |
+| (KG DB)  |     | (func)   |     | (Result) |
++----------+     +----+-----+     +----------+
+                      |
+                 +----v-----+
+                 | Logic B  |
+                 | (error)  |
+                 +----------+
+```
+
+**对比表**:
+| 维度 | As-Is | To-Be | 风险 |
+|:---|:---|:---|:---|
+| 复用 | 重复造轮子 | 调用utils | 无 |
+| 结构 | 混杂views | 迁移services | 需改引用 |