@ppdocs/mcp 3.1.1 → 3.1.3

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/storage/httpClient.d.ts

@@ -104,11 +104,24 @@ export declare function getDocsByStatus(_projectId: string, statusList: string[]
 export declare function getTree(_projectId: string): Promise<TreeNode[]>;
 export declare function getRules(_projectId: string, ruleType: string): Promise<string[]>;
 export declare function saveRules(_projectId: string, ruleType: string, rules: string[]): Promise<boolean>;
+export declare function appendRules(_projectId: string, ruleType: string, newRules: string[]): Promise<{
+    success: boolean;
+    total: number;
+    added: number;
+}>;
 export declare function getRulesMeta(): Promise<Record<string, RuleMeta>>;
 export declare function saveRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
+export declare function mergeRulesMeta(newMeta: Record<string, RuleMeta>): Promise<{
+    success: boolean;
+    total: number;
+}>;
 export declare function crossGetRulesMeta(target: string): Promise<Record<string, RuleMeta>>;
 export declare function getGlobalRulesMeta(): Promise<Record<string, RuleMeta>>;
 export declare function saveGlobalRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
+export declare function mergeGlobalRulesMeta(newMeta: Record<string, RuleMeta>): Promise<{
+    success: boolean;
+    total: number;
+}>;
 export declare function listTasks(_projectId: string, status?: 'active' | 'archived'): Promise<TaskSummary[]>;
 export declare function getTask(_projectId: string, taskId: string): Promise<Task | null>;
 export declare function createTask(_projectId: string, task: {

package/dist/storage/httpClient.js

@@ -508,12 +508,26 @@ export async function getRules(_projectId, ruleType) {
 export async function saveRules(_projectId, ruleType, rules) {
     return getClient().saveRulesApi(ruleType, rules);
 }
+export async function appendRules(_projectId, ruleType, newRules) {
+    const existing = await getClient().getRulesApi(ruleType);
+    const existingSet = new Set(existing.map(r => r.trim()));
+    const toAdd = newRules.filter(r => !existingSet.has(r.trim()));
+    const merged = [...existing, ...toAdd];
+    const success = await getClient().saveRulesApi(ruleType, merged);
+    return { success, total: merged.length, added: toAdd.length };
+}
 export async function getRulesMeta() {
     return getClient().getRulesMeta();
 }
 export async function saveRulesMeta(meta) {
     return getClient().saveRulesMeta(meta);
 }
+export async function mergeRulesMeta(newMeta) {
+    const existing = await getClient().getRulesMeta();
+    const merged = { ...existing, ...newMeta };
+    const success = await getClient().saveRulesMeta(merged);
+    return { success, total: Object.keys(merged).length };
+}
 export async function crossGetRulesMeta(target) {
     return getClient().crossGetRulesMeta(target);
 }
@@ -523,6 +537,12 @@ export async function getGlobalRulesMeta() {
 export async function saveGlobalRulesMeta(meta) {
     return getClient().saveGlobalRulesMeta(meta);
 }
+export async function mergeGlobalRulesMeta(newMeta) {
+    const existing = await getClient().getGlobalRulesMeta();
+    const merged = { ...existing, ...newMeta };
+    const success = await getClient().saveGlobalRulesMeta(merged);
+    return { success, total: Object.keys(merged).length };
+}
 // ============ 任务管理 ============
 export async function listTasks(_projectId, status) {
     return getClient().listTasks(status);

package/dist/tools/index.js

@@ -237,20 +237,20 @@ export function registerTools(server, projectId, _user) {
         }
         return { content: [{ type: 'text', text: rules }] };
     });
-    // 3.7 保存项目规则
-    server.tool('kg_save_rules', '保存单个类型的项目规则(独立文件存储)', {
+    // 3.7 保存项目规则 (自动合并,去重追加)
+    server.tool('kg_save_rules', '保存单个类型的项目规则(自动合并:已有规则保留,新规则去重追加)', {
         ruleType: z.string()
             .describe('规则类型(如 userStyles, codeStyle, reviewRules, testRules, unitTests, 或自定义类型)'),
         rules: z.array(z.string()).describe('规则数组')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
-        const success = await storage.saveRules(projectId, decoded.ruleType, decoded.rules);
-        if (!success) {
+        const result = await storage.appendRules(projectId, decoded.ruleType, decoded.rules);
+        if (!result.success) {
             return wrap('❌ 保存失败');
         }
         const meta = await storage.getRulesMeta();
         const label = meta[decoded.ruleType]?.label || decoded.ruleType;
-        return wrap(`✅ ${label}已保存 (${decoded.rules.length} 条)`);
+        return wrap(`✅ ${label}已保存 (新增${result.added}条, 共${result.total}条)`);
     });
     // 3.8 获取规则触发配置
     server.tool('kg_get_rules_meta', '获取规则触发配置(所有类型的标签、关键词、触发数)。用于查看/编辑 hooks 触发条件', {}, async () => {
@@ -270,8 +270,8 @@ export function registerTools(server, projectId, _user) {
             return wrap(`❌ ${String(e)}`);
         }
     });
-    // 3.9 保存规则触发配置
-    server.tool('kg_save_rules_meta', '保存规则触发配置(标签、关键词、触发数)。支持新增自定义规则类型', {
+    // 3.9 保存规则触发配置 (自动合并)
+    server.tool('kg_save_rules_meta', '保存规则触发配置(自动合并:已有类型更新,新类型创建,其他类型不受影响)', {
         meta: z.record(z.string(), z.object({
             label: z.string().describe('规则显示名称'),
             keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
@@ -281,11 +281,11 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         try {
             const decoded = decodeObjectStrings(args.meta);
-            const success = await storage.saveRulesMeta(decoded);
-            if (!success) {
+            const result = await storage.mergeRulesMeta(decoded);
+            if (!result.success) {
                 return wrap('❌ 保存失败');
             }
-            return wrap(`✅ 规则触发配置已保存 (${Object.keys(decoded).length} 个类型)`);
+            return wrap(`✅ 触发配置已保存 (更新${Object.keys(decoded).length}个类型, 共${result.total}个类型)`);
         }
         catch (e) {
             return wrap(`❌ ${String(e)}`);
@@ -309,8 +309,8 @@ export function registerTools(server, projectId, _user) {
             return wrap(`❌ ${String(e)}`);
         }
     });
-    // 3.11 保存全局默认规则触发配置
-    server.tool('kg_save_global_rules_meta', '保存全局默认规则触发配置(新项目创建时继承此配置)。支持新增自定义规则类型', {
+    // 3.11 保存全局默认规则触发配置 (自动合并)
+    server.tool('kg_save_global_rules_meta', '保存全局默认触发配置(自动合并:已有类型更新,新类型创建,其他类型不受影响)', {
         meta: z.record(z.string(), z.object({
             label: z.string().describe('规则显示名称'),
             keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
@@ -320,11 +320,11 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         try {
             const decoded = decodeObjectStrings(args.meta);
-            const success = await storage.saveGlobalRulesMeta(decoded);
-            if (!success) {
+            const result = await storage.mergeGlobalRulesMeta(decoded);
+            if (!result.success) {
                 return wrap('❌ 保存失败');
             }
-            return wrap(`✅ 全局默认规则触发配置已保存 (${Object.keys(decoded).length} 个类型)`);
+            return wrap(`✅ 全局触发配置已保存 (更新${Object.keys(decoded).length}个类型, 共${result.total}个类型)`);
         }
         catch (e) {
             return wrap(`❌ ${String(e)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "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 | 需改引用 |