@ppdocs/mcp 3.9.0 → 3.10.0

package/dist/cli.js

@@ -6,7 +6,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 import { generateUser } from './config.js';
 import { PpdocsApiClient } from './storage/httpClient.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -259,25 +259,33 @@ function execSilent(cmd) {
 function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     const detected = [];
     const serverName = 'ppdocs-kg';
-    const addCmd = `-- npx -y @ppdocs/mcp@latest`;
     const envPairs = [
         `PPDOCS_API_URL=${apiUrl}`,
         `PPDOCS_USER=${user}`,
         `PPDOCS_PROJECT_ROOT=${cwd}`,
     ];
-    const claudeEnvArgs = envPairs.map((pair) => `-e ${JSON.stringify(pair)}`).join(' ');
-    const codexEnvArgs = envPairs.map((pair) => `--env ${JSON.stringify(pair)}`).join(' ');
+    /** 用 spawnSync + args 数组注册 MCP，避免 Windows cmd.exe 引号解析问题 */
+    function mcpAdd(cli, envFlag) {
+        const args = ['mcp', 'add'];
+        for (const pair of envPairs) {
+            args.push(envFlag, pair);
+        }
+        args.push(serverName, '--', 'npx', '-y', '@ppdocs/mcp@latest');
+        const result = spawnSync(cli, args, { stdio: 'inherit', shell: true });
+        if (result.status !== 0)
+            throw new Error(`${cli} mcp add failed`);
+    }
     // Claude CLI
     if (commandExists('claude')) {
         detected.push('Claude');
         try {
             execSilent(`claude mcp remove ${serverName}`);
-            execSync(`claude mcp add ${claudeEnvArgs} ${serverName} ${addCmd}`, { stdio: 'inherit' });
+            mcpAdd('claude', '-e');
         }
         catch {
             try {
                 execSilent(`claude mcp remove ${serverName}`);
-                execSync(`claude mcp add ${claudeEnvArgs} ${serverName} ${addCmd}`, { stdio: 'inherit' });
+                mcpAdd('claude', '-e');
             }
             catch {
                 console.log(`⚠️  Claude MCP registration failed`);
@@ -289,7 +297,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
         detected.push('Codex');
         try {
             execSilent(`codex mcp remove ${serverName}`);
-            execSync(`codex mcp add ${codexEnvArgs} ${serverName} ${addCmd}`, { stdio: 'inherit' });
+            mcpAdd('codex', '--env');
         }
         catch {
             console.log(`⚠️  Codex MCP registration failed`);

package/dist/config.d.ts

@@ -12,4 +12,5 @@ export interface PpdocsConfig {
 export declare const PPDOCS_CONFIG_FILE = ".ppdocs";
 /** 生成随机用户名 */
 export declare function generateUser(): string;
+export declare function generateAgentId(): string;
 export declare function loadConfig(): Promise<PpdocsConfig | null>;

package/dist/config.js

@@ -10,6 +10,20 @@ export function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
     return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
 }
+/**
+ * 生成唯一 agentId (每个 MCP 进程实例一个)
+ * 格式: "a-{4位随机}" — 简短且足够区分同机多实例
+ * 进程级单例: 同一进程内多次调用返回相同值
+ */
+let _cachedAgentId = null;
+export function generateAgentId() {
+    if (!_cachedAgentId) {
+        const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
+        const rand = Array.from({ length: 4 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
+        _cachedAgentId = `a-${rand}`;
+    }
+    return _cachedAgentId;
+}
 // ============ 配置读取 ============
 function readEnvConfig() {
     const apiUrl = process.env.PPDOCS_API_URL;
@@ -20,7 +34,7 @@ function readEnvConfig() {
         apiUrl,
         projectId: match?.[1] || 'unknown',
         user: process.env.PPDOCS_USER || generateUser(),
-        agentId: process.env.PPDOCS_AGENT_ID || 'default',
+        agentId: process.env.PPDOCS_AGENT_ID || generateAgentId(),
         source: 'env',
     };
 }
@@ -49,7 +63,7 @@ function readPpdocsFile() {
         const c = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
         if (!c.api || !c.projectId || !c.key)
             return null;
-        return { apiUrl: `${c.api}/api/${c.projectId}/${c.key}`, projectId: c.projectId, user: c.user || generateUser(), agentId: c.agentId || process.env.PPDOCS_AGENT_ID || 'default', source: 'file' };
+        return { apiUrl: `${c.api}/api/${c.projectId}/${c.key}`, projectId: c.projectId, user: c.user || generateUser(), agentId: c.agentId || process.env.PPDOCS_AGENT_ID || generateAgentId(), source: 'file' };
     }
     catch {
         return null;

package/dist/index.js

@@ -14,7 +14,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { registerTools } from './tools/index.js';
 import { initClient } from './storage/httpClient.js';
 import { runCli } from './cli.js';
-import { loadConfig } from './config.js';
+import { loadConfig, generateAgentId } from './config.js';
 // 从 package.json 读取版本号
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -39,7 +39,7 @@ async function main() {
     }
     const projectId = config?.projectId || 'pending';
     const user = config?.user || 'agent';
-    const agentId = config?.agentId || process.env.PPDOCS_AGENT_ID || 'default';
+    const agentId = config?.agentId || process.env.PPDOCS_AGENT_ID || generateAgentId();
     const server = new McpServer({ name: `ppdocs [${projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
     registerTools(server, projectId, user, agentId, (newProjectId, newApiUrl) => {
         console.error(`[kg_init] 项目已切换: ${newProjectId}`);

package/dist/tools/discussion.js

@@ -15,9 +15,7 @@ import { getClient } from '../storage/httpClient.js';
 import { decodeObjectStrings } from '../utils.js';
 import { wrap, safeTool } from './shared.js';
 function sender(ctx) {
-    return ctx.agentId && ctx.agentId !== 'default'
-        ? `${ctx.projectId}:${ctx.user}:${ctx.agentId}`
-        : `${ctx.projectId}:${ctx.user}`;
+    return `${ctx.projectId}:${ctx.user}:${ctx.agentId}`;
 }
 /** 提取 sender 中的 projectId */
 function senderProjectId(senderStr) {

package/dist/tools/flowchart.js

@@ -380,6 +380,9 @@ export function registerFlowchartTools(server, _ctx) {
                 if (chart.parentChart) {
                     lines.push(`parent: ${chart.parentChart}${chart.parentNode ? `/${chart.parentNode}` : ''}`);
                 }
+                if (chart.projectBrief) {
+                    lines.push('', chart.projectBrief);
+                }
                 // Mermaid 流程图
                 lines.push('', '```mermaid', 'graph TD');
                 // 节点声明

package/dist/tools/init.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { z } from 'zod';
 import { initClient } from '../storage/httpClient.js';
+import { generateAgentId } from '../config.js';
 import { wrap, safeTool } from './shared.js';
 // 当前会话的 API URL (用于幂等检查)
 let currentApiUrl = null;
@@ -74,7 +75,8 @@ export function registerInitTool(server, ctx, onProjectChange) {
         // 4. 更新共享上下文 — 所有工具立刻获得新 projectId
         ctx.projectId = config.projectId;
         ctx.user = config.user;
-        ctx.agentId = process.env.PPDOCS_AGENT_ID || 'default';
+        // agentId: 优先环境变量 > 保留当前值(进程启动时已生成)
+        ctx.agentId = process.env.PPDOCS_AGENT_ID || ctx.agentId || generateAgentId();
         // 5. 通知主进程
         onProjectChange(config.projectId, config.apiUrl);
         return wrap(`✅ 项目上下文已初始化\n\n` +

package/dist/tools/kg_status.d.ts

@@ -1,5 +1,6 @@
 /**
  * 📊 kg_status — 项目速览仪表盘
+ * 一次调用返回项目全貌：摘要、核心模块、活跃任务、快速导航
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';

package/dist/tools/kg_status.js

@@ -1,32 +1,56 @@
 /**
  * 📊 kg_status — 项目速览仪表盘
+ * 一次调用返回项目全貌：摘要、核心模块、活跃任务、快速导航
  */
 import { getClient } from '../storage/httpClient.js';
 import { wrap, safeTool } from './shared.js';
 export function registerStatusTool(server, ctx) {
     const client = () => getClient();
     server.tool('kg_status', '📊 项目速览仪表盘 — 一键了解项目健康。返回: 流程图节点数、活跃任务数、最近变更。每次对话开始建议首先调用', {}, async () => safeTool(async () => {
-        const [charts, activeTasks, discussions] = await Promise.all([
+        const [charts, activeTasks, discussions, mainChart] = await Promise.all([
             client().listFlowcharts(),
             client().listTasks('active'),
             client().discussionList().catch(() => []),
+            client().getFlowchart('main').catch(() => null),
         ]);
         const nodeCount = charts.reduce((sum, c) => sum + (c.nodeCount || 0), 0);
         const activeDiscussions = discussions.filter((d) => d.status === 'active');
         const lines = [
-            `📊 项目速览 [${ctx.projectId}]`,
-            `🆔 身份: ${ctx.user}${ctx.agentId !== 'default' ? ':' + ctx.agentId : ''}`,
-            ``,
-            `🔀 流程图: ${charts.length} 张 | 📦 节点: ${nodeCount} 个`,
-            `📝 活跃任务: ${activeTasks.length} 个`,
-            `📨 活跃讨论: ${activeDiscussions.length} 个`,
+            `# 项目速览 [${ctx.projectId}]`,
+            `身份: ${ctx.user}:${ctx.agentId}`,
         ];
+        // --- Project Brief ---
+        if (mainChart?.projectBrief) {
+            lines.push('', '## 项目简介', mainChart.projectBrief);
+        }
+        // --- 核心模块 (从 main 图提取) ---
+        if (mainChart?.nodes && mainChart.nodes.length > 0) {
+            lines.push('', '## 核心模块');
+            for (const node of mainChart.nodes) {
+                const badges = [];
+                if (node.subFlowchart)
+                    badges.push(`▶${node.subFlowchart}`);
+                const fileCount = (node.boundFiles?.length ?? 0) + (node.boundDirs?.length ?? 0);
+                if (fileCount > 0)
+                    badges.push(`files=${fileCount}`);
+                const docCount = node.docEntries?.length ?? 0;
+                if (docCount > 0)
+                    badges.push(`docs=${docCount}`);
+                const suffix = badges.length > 0 ? ` [${badges.join(' ')}]` : '';
+                const desc = node.description ? ` — ${node.description.slice(0, 80)}` : '';
+                lines.push(`- **${node.label}** \`${node.id}\`${desc}${suffix}`);
+            }
+        }
+        // --- 当前状态 ---
+        lines.push('', '## 当前状态', `- 流程图: ${charts.length} 张 | 节点: ${nodeCount} 个`, `- 活跃任务: ${activeTasks.length} 个`, `- 活跃讨论: ${activeDiscussions.length} 个`);
         if (activeTasks.length > 0) {
-            lines.push(``, `🔧 进行中的任务:`);
+            lines.push('', '### 进行中的任务');
             for (const t of activeTasks.slice(0, 5)) {
-                lines.push(`  - ${t.title} (${t.id})`);
+                lines.push(`- ${t.title} (\`${t.id}\`)`);
             }
         }
+        // --- 快速导航 ---
+        lines.push('', '## 快速导航', '- `kg_flowchart(get, "main")` — 查看完整架构图', '- `kg_flowchart(get_node, "节点ID", expand:2)` — 深入某个模块', '- `kg_workflow()` — 查看可用工作流', '- `kg_task(get)` — 查看活跃任务详情');
         return wrap(lines.join('\n'));
     }));
 }

package/dist/tools/shared.d.ts

@@ -9,7 +9,7 @@ export interface McpContext {
     agentId: string;
 }
 /** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
-export declare function createContext(projectId: string, user: string, agentId?: string): McpContext;
+export declare function createContext(projectId: string, user: string, agentId: string): McpContext;
 export declare function wrap(text: string): {
     content: {
         type: "text";

package/dist/tools/shared.js

@@ -3,7 +3,7 @@
  * 合并原 helpers.ts + 新增 safeTool / withCross 模式
  */
 /** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
-export function createContext(projectId, user, agentId = 'default') {
+export function createContext(projectId, user, agentId) {
     return { projectId, user, agentId };
 }
 // ==================== MCP 返回包装 ====================

package/package.json

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

package/templates/AGENT.md

@@ -1,64 +1,105 @@
-????????????**????**????????**????**????????????????????????
-
-## 0. ????
-
-```text
-kg_init()                 -> optional fallback when auto-connect is missing
-kg_status()               -> ???????
-kg_task(action:"get")     -> ?? active ??
-kg_discuss(action:"list") -> ???????
-```
-
-## 1. ????????
-
-- ??: `kg_flowchart(action:"list|get|get_node|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart")`
-- ??: `kg_workflow()` / `kg_workflow(id:"...")` / `kg_workflow(action:"save|delete")`
-- ??: `kg_task(action:"create|get|update|archive|delete")`
-- ??: `kg_files(action:"list|read|upload|download|public_*")`
-- ??: `kg_ref(action:"list|get|save|delete|read_file")`
-- ??/??: `kg_discuss(...)`, `kg_meeting(...)`
-- ????: `code_scan()`, `code_smart_context(symbolName)`, `code_full_path(symbolA, symbolB)`
-- ????: ?????????????????????????????? fallback????????????
-
-## 2. ?????
-
-### Step 1: ????
-1. ?? `kg_flowchart(get)` ????????? `kg_workflow()` ?????
-2. ???????? `kg_flowchart(get_node, expand:2, includeDoc:true, includeFiles:true)`?
-3. ????? `subFlowchart`???????????????
-4. ??????????? `code_scan()`??? `code_smart_context` / `code_full_path`?
-5. ??????????????????????????
-
-### Step 2: ????
-1. ?????: `kg_task(create, title, goals, bindTo)`?
-2. ??? ASCII ????????????????
-3. ?????????????
-
-### Step 3: ????
-1. ????????????????
-2. ?????????????? `kg_task(update, log_type:"progress")` ???????
-3. ?????? `issue`??????? `solution`????????
-
-### Step 4: ????
-| ?? | ???? |
-|:---|:---|
-| ?????? | `kg_flowchart(bind, nodeId, files:[...])` |
-| ???? | `kg_flowchart(update_node, nodeId, description, docSummary, docContent)` |
-| ?????? | `kg_flowchart(batch_add)` + `bind` + `update_node(docSummary, docContent)` |
-| ?????? | `kg_flowchart(create_chart)`???????????? |
-| ??/???? | ?? `kg_files(upload/read/list/download)` ??????? `kg_flowchart(bind, files:[...])` |
-| ???? | ?? `kg_flowchart(update_node, docSummary, docContent)` ??? `docEntries` |
-
-## 3. ????
-
-- ?????????? -> ??????????
-- ???????/???? -> ??????????????????
-- ??????????????????JSON?????? fallback ???
-- ???? -> ??????????
-
-## 4. ????
-
-- ??????? ASCII ????
-- ???????? Markdown ???
-- ?????????????????????
-- ?????? / ????????????
+# ppdocs 知识图谱 — AI 协作规范
+
+本项目使用 ppdocs 知识图谱系统管理项目知识。你拥有一组 MCP 工具来访问项目的架构图谱、文档、任务和代码分析能力。
+
+## 首次对话启动
+
+每次新对话开始时，按以下顺序获取项目上下文：
+
+```
+1. kg_status()              → 项目概况（含架构摘要、活跃任务、核心模块列表）
+2. kg_flowchart(get, "main") → 需要深入时查看完整架构图
+3. kg_workflow()             → 查看可用的标准工作流
+4. kg_task(get)              → 查看活跃任务详情
+```
+
+通常只需第 1 步就能获得足够的项目上下文开始工作。
+
+## 工具速查
+
+### 理解项目
+| 工具 | 用途 |
+|:---|:---|
+| `kg_status()` | 一键获取项目全貌（推荐首选） |
+| `kg_flowchart(get, chartId)` | 查看某张流程图的完整结构 |
+| `kg_flowchart(get_node, nodeId, expand:2)` | 深入某个模块，含文档和绑定文件 |
+| `kg_flowchart(search, query)` | 按关键词搜索流程图节点 |
+| `kg_doc(search, query)` | 搜索节点内嵌文档 |
+| `code_smart_context(symbolName)` | 获取代码符号的依赖和关联文档 |
+| `code_full_path(symbolA, symbolB)` | 查找两个符号之间的关联路径 |
+
+### 执行任务
+| 工具 | 用途 |
+|:---|:---|
+| `kg_task(create, title, goals, bindTo)` | 开始新任务（绑定到流程图节点） |
+| `kg_task(update, content, log_type)` | 记录进度/问题/方案（每步都要记录） |
+| `kg_task(archive, summary, solutions)` | 完成任务并归档经验 |
+| `kg_workflow(id)` | 获取标准工作流指导（如有匹配的工作流） |
+
+### 回写知识
+| 工具 | 用途 |
+|:---|:---|
+| `kg_flowchart(update_node, nodeId, docSummary, docContent)` | 更新节点文档 |
+| `kg_flowchart(bind, nodeId, files:[...])` | 绑定源码文件到节点 |
+| `kg_flowchart(batch_add, nodes, edges)` | 新增模块时批量创建节点 |
+| `kg_flowchart(create_chart)` | 为复杂模块创建子流程图 |
+
+### 协作与文件
+| 工具 | 用途 |
+|:---|:---|
+| `kg_discuss(create/reply/list)` | 跨 AI 实例讨论 |
+| `kg_meeting(join/post/status)` | 多 AI 协作会议 |
+| `kg_files(list/read/download)` | 项目文件管理 |
+| `kg_ref(list/get/save)` | 外部参考资料管理 |
+
+## 核心原则
+
+1. **先查图谱再看代码** — 在 grep/搜索代码之前，先用 `kg_flowchart(search)` 或 `kg_doc(search)` 查找相关节点，通常能直接定位到关键文件和逻辑说明，减少 80% 的盲目搜索。
+
+2. **每完成一步就 update task** — 使用 `kg_task(update)` 记录每个阶段的进展，遇到问题用 `log_type:"issue"` 记录，找到方案用 `log_type:"solution"` 记录。
+
+3. **改完代码必须回写图谱** — 修改了代码后，检查对应的流程图节点文档是否需要更新。新增文件要 `bind`，逻辑变更要 `update_node` 的 docContent。
+
+4. **子图递归探索** — 节点如果有 `subFlowchart` 字段，说明它有更细粒度的子流程图。理解细节时要递归下探。
+
+## 节点文档模板
+
+创建或更新节点 `docContent` 时，推荐使用以下结构：
+
+```markdown
+## 职责
+一句话说清本模块的核心职责。
+
+## 输入 / 输出
+- 输入: 进入本模块的数据或请求
+- 输出: 本模块产出的数据或响应
+
+## 核心逻辑
+1. 步骤一
+2. 步骤二
+3. ...（3-7 步为宜）
+
+## 边界条件
+- 它不负责什么（明确排除）
+- 错误处理策略
+
+## 关键文件
+- path/to/main.go — 主逻辑
+- path/to/helper.go — 辅助函数
+```
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|:---|:---|
+| API 超时/网络错误 | 重试一次，仍失败则告知用户 |
+| JSON 解析失败 | fallback 到纯文本输出 |
+| 找不到节点 | 用 `kg_flowchart(search)` 模糊搜索 |
+| 工具调用失败 | 检查参数格式，确保 JSON 数组/对象格式正确 |
+
+## 输出格式
+
+- 逻辑说明用 ASCII 流程图
+- 对比分析用 Markdown 表格
+- 代码引用注明文件路径和行号
+- 方案说明要简洁，避免不必要的冗余

package/templates/cursorrules.md

@@ -1,64 +1,105 @@
-????????????**????**????????**????**????????????????????????
-
-## 0. ????
-
-```text
-kg_init()                 -> optional fallback when auto-connect is missing
-kg_status()               -> ???????
-kg_task(action:"get")     -> ?? active ??
-kg_discuss(action:"list") -> ???????
-```
-
-## 1. ????????
-
-- ??: `kg_flowchart(action:"list|get|get_node|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart")`
-- ??: `kg_workflow()` / `kg_workflow(id:"...")` / `kg_workflow(action:"save|delete")`
-- ??: `kg_task(action:"create|get|update|archive|delete")`
-- ??: `kg_files(action:"list|read|upload|download|public_*")`
-- ??: `kg_ref(action:"list|get|save|delete|read_file")`
-- ??/??: `kg_discuss(...)`, `kg_meeting(...)`
-- ????: `code_scan()`, `code_smart_context(symbolName)`, `code_full_path(symbolA, symbolB)`
-- ????: ?????????????????????????????? fallback????????????
-
-## 2. ?????
-
-### Step 1: ????
-1. ?? `kg_flowchart(get)` ????????? `kg_workflow()` ?????
-2. ???????? `kg_flowchart(get_node, expand:2, includeDoc:true, includeFiles:true)`?
-3. ????? `subFlowchart`???????????????
-4. ??????????? `code_scan()`??? `code_smart_context` / `code_full_path`?
-5. ??????????????????????????
-
-### Step 2: ????
-1. ?????: `kg_task(create, title, goals, bindTo)`?
-2. ??? ASCII ????????????????
-3. ?????????????
-
-### Step 3: ????
-1. ????????????????
-2. ?????????????? `kg_task(update, log_type:"progress")` ???????
-3. ?????? `issue`??????? `solution`????????
-
-### Step 4: ????
-| ?? | ???? |
-|:---|:---|
-| ?????? | `kg_flowchart(bind, nodeId, files:[...])` |
-| ???? | `kg_flowchart(update_node, nodeId, description, docSummary, docContent)` |
-| ?????? | `kg_flowchart(batch_add)` + `bind` + `update_node(docSummary, docContent)` |
-| ?????? | `kg_flowchart(create_chart)`???????????? |
-| ??/???? | ?? `kg_files(upload/read/list/download)` ??????? `kg_flowchart(bind, files:[...])` |
-| ???? | ?? `kg_flowchart(update_node, docSummary, docContent)` ??? `docEntries` |
-
-## 3. ????
-
-- ?????????? -> ??????????
-- ???????/???? -> ??????????????????
-- ??????????????????JSON?????? fallback ???
-- ???? -> ??????????
-
-## 4. ????
-
-- ??????? ASCII ????
-- ???????? Markdown ???
-- ?????????????????????
-- ?????? / ????????????
+# ppdocs 知识图谱 — AI 协作规范
+
+本项目使用 ppdocs 知识图谱系统管理项目知识。你拥有一组 MCP 工具来访问项目的架构图谱、文档、任务和代码分析能力。
+
+## 首次对话启动
+
+每次新对话开始时，按以下顺序获取项目上下文：
+
+```
+1. kg_status()              → 项目概况（含架构摘要、活跃任务、核心模块列表）
+2. kg_flowchart(get, "main") → 需要深入时查看完整架构图
+3. kg_workflow()             → 查看可用的标准工作流
+4. kg_task(get)              → 查看活跃任务详情
+```
+
+通常只需第 1 步就能获得足够的项目上下文开始工作。
+
+## 工具速查
+
+### 理解项目
+| 工具 | 用途 |
+|:---|:---|
+| `kg_status()` | 一键获取项目全貌（推荐首选） |
+| `kg_flowchart(get, chartId)` | 查看某张流程图的完整结构 |
+| `kg_flowchart(get_node, nodeId, expand:2)` | 深入某个模块，含文档和绑定文件 |
+| `kg_flowchart(search, query)` | 按关键词搜索流程图节点 |
+| `kg_doc(search, query)` | 搜索节点内嵌文档 |
+| `code_smart_context(symbolName)` | 获取代码符号的依赖和关联文档 |
+| `code_full_path(symbolA, symbolB)` | 查找两个符号之间的关联路径 |
+
+### 执行任务
+| 工具 | 用途 |
+|:---|:---|
+| `kg_task(create, title, goals, bindTo)` | 开始新任务（绑定到流程图节点） |
+| `kg_task(update, content, log_type)` | 记录进度/问题/方案（每步都要记录） |
+| `kg_task(archive, summary, solutions)` | 完成任务并归档经验 |
+| `kg_workflow(id)` | 获取标准工作流指导（如有匹配的工作流） |
+
+### 回写知识
+| 工具 | 用途 |
+|:---|:---|
+| `kg_flowchart(update_node, nodeId, docSummary, docContent)` | 更新节点文档 |
+| `kg_flowchart(bind, nodeId, files:[...])` | 绑定源码文件到节点 |
+| `kg_flowchart(batch_add, nodes, edges)` | 新增模块时批量创建节点 |
+| `kg_flowchart(create_chart)` | 为复杂模块创建子流程图 |
+
+### 协作与文件
+| 工具 | 用途 |
+|:---|:---|
+| `kg_discuss(create/reply/list)` | 跨 AI 实例讨论 |
+| `kg_meeting(join/post/status)` | 多 AI 协作会议 |
+| `kg_files(list/read/download)` | 项目文件管理 |
+| `kg_ref(list/get/save)` | 外部参考资料管理 |
+
+## 核心原则
+
+1. **先查图谱再看代码** — 在 grep/搜索代码之前，先用 `kg_flowchart(search)` 或 `kg_doc(search)` 查找相关节点，通常能直接定位到关键文件和逻辑说明，减少 80% 的盲目搜索。
+
+2. **每完成一步就 update task** — 使用 `kg_task(update)` 记录每个阶段的进展，遇到问题用 `log_type:"issue"` 记录，找到方案用 `log_type:"solution"` 记录。
+
+3. **改完代码必须回写图谱** — 修改了代码后，检查对应的流程图节点文档是否需要更新。新增文件要 `bind`，逻辑变更要 `update_node` 的 docContent。
+
+4. **子图递归探索** — 节点如果有 `subFlowchart` 字段，说明它有更细粒度的子流程图。理解细节时要递归下探。
+
+## 节点文档模板
+
+创建或更新节点 `docContent` 时，推荐使用以下结构：
+
+```markdown
+## 职责
+一句话说清本模块的核心职责。
+
+## 输入 / 输出
+- 输入: 进入本模块的数据或请求
+- 输出: 本模块产出的数据或响应
+
+## 核心逻辑
+1. 步骤一
+2. 步骤二
+3. ...（3-7 步为宜）
+
+## 边界条件
+- 它不负责什么（明确排除）
+- 错误处理策略
+
+## 关键文件
+- path/to/main.go — 主逻辑
+- path/to/helper.go — 辅助函数
+```
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|:---|:---|
+| API 超时/网络错误 | 重试一次，仍失败则告知用户 |
+| JSON 解析失败 | fallback 到纯文本输出 |
+| 找不到节点 | 用 `kg_flowchart(search)` 模糊搜索 |
+| 工具调用失败 | 检查参数格式，确保 JSON 数组/对象格式正确 |
+
+## 输出格式
+
+- 逻辑说明用 ASCII 流程图
+- 对比分析用 Markdown 表格
+- 代码引用注明文件路径和行号
+- 方案说明要简洁，避免不必要的冗余

package/templates/kiro-rules/ppdocs.md

@@ -1,64 +1,105 @@
-????????????**????**????????**????**????????????????????????
-
-## 0. ????
-
-```text
-kg_init()                 -> optional fallback when auto-connect is missing
-kg_status()               -> ???????
-kg_task(action:"get")     -> ?? active ??
-kg_discuss(action:"list") -> ???????
-```
-
-## 1. ????????
-
-- ??: `kg_flowchart(action:"list|get|get_node|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart")`
-- ??: `kg_workflow()` / `kg_workflow(id:"...")` / `kg_workflow(action:"save|delete")`
-- ??: `kg_task(action:"create|get|update|archive|delete")`
-- ??: `kg_files(action:"list|read|upload|download|public_*")`
-- ??: `kg_ref(action:"list|get|save|delete|read_file")`
-- ??/??: `kg_discuss(...)`, `kg_meeting(...)`
-- ????: `code_scan()`, `code_smart_context(symbolName)`, `code_full_path(symbolA, symbolB)`
-- ????: ?????????????????????????????? fallback????????????
-
-## 2. ?????
-
-### Step 1: ????
-1. ?? `kg_flowchart(get)` ????????? `kg_workflow()` ?????
-2. ???????? `kg_flowchart(get_node, expand:2, includeDoc:true, includeFiles:true)`?
-3. ????? `subFlowchart`???????????????
-4. ??????????? `code_scan()`??? `code_smart_context` / `code_full_path`?
-5. ??????????????????????????
-
-### Step 2: ????
-1. ?????: `kg_task(create, title, goals, bindTo)`?
-2. ??? ASCII ????????????????
-3. ?????????????
-
-### Step 3: ????
-1. ????????????????
-2. ?????????????? `kg_task(update, log_type:"progress")` ???????
-3. ?????? `issue`??????? `solution`????????
-
-### Step 4: ????
-| ?? | ???? |
-|:---|:---|
-| ?????? | `kg_flowchart(bind, nodeId, files:[...])` |
-| ???? | `kg_flowchart(update_node, nodeId, description, docSummary, docContent)` |
-| ?????? | `kg_flowchart(batch_add)` + `bind` + `update_node(docSummary, docContent)` |
-| ?????? | `kg_flowchart(create_chart)`???????????? |
-| ??/???? | ?? `kg_files(upload/read/list/download)` ??????? `kg_flowchart(bind, files:[...])` |
-| ???? | ?? `kg_flowchart(update_node, docSummary, docContent)` ??? `docEntries` |
-
-## 3. ????
-
-- ?????????? -> ??????????
-- ???????/???? -> ??????????????????
-- ??????????????????JSON?????? fallback ???
-- ???? -> ??????????
-
-## 4. ????
-
-- ??????? ASCII ????
-- ???????? Markdown ???
-- ?????????????????????
-- ?????? / ????????????
+# ppdocs 知识图谱 — AI 协作规范
+
+本项目使用 ppdocs 知识图谱系统管理项目知识。你拥有一组 MCP 工具来访问项目的架构图谱、文档、任务和代码分析能力。
+
+## 首次对话启动
+
+每次新对话开始时，按以下顺序获取项目上下文：
+
+```
+1. kg_status()              → 项目概况（含架构摘要、活跃任务、核心模块列表）
+2. kg_flowchart(get, "main") → 需要深入时查看完整架构图
+3. kg_workflow()             → 查看可用的标准工作流
+4. kg_task(get)              → 查看活跃任务详情
+```
+
+通常只需第 1 步就能获得足够的项目上下文开始工作。
+
+## 工具速查
+
+### 理解项目
+| 工具 | 用途 |
+|:---|:---|
+| `kg_status()` | 一键获取项目全貌（推荐首选） |
+| `kg_flowchart(get, chartId)` | 查看某张流程图的完整结构 |
+| `kg_flowchart(get_node, nodeId, expand:2)` | 深入某个模块，含文档和绑定文件 |
+| `kg_flowchart(search, query)` | 按关键词搜索流程图节点 |
+| `kg_doc(search, query)` | 搜索节点内嵌文档 |
+| `code_smart_context(symbolName)` | 获取代码符号的依赖和关联文档 |
+| `code_full_path(symbolA, symbolB)` | 查找两个符号之间的关联路径 |
+
+### 执行任务
+| 工具 | 用途 |
+|:---|:---|
+| `kg_task(create, title, goals, bindTo)` | 开始新任务（绑定到流程图节点） |
+| `kg_task(update, content, log_type)` | 记录进度/问题/方案（每步都要记录） |
+| `kg_task(archive, summary, solutions)` | 完成任务并归档经验 |
+| `kg_workflow(id)` | 获取标准工作流指导（如有匹配的工作流） |
+
+### 回写知识
+| 工具 | 用途 |
+|:---|:---|
+| `kg_flowchart(update_node, nodeId, docSummary, docContent)` | 更新节点文档 |
+| `kg_flowchart(bind, nodeId, files:[...])` | 绑定源码文件到节点 |
+| `kg_flowchart(batch_add, nodes, edges)` | 新增模块时批量创建节点 |
+| `kg_flowchart(create_chart)` | 为复杂模块创建子流程图 |
+
+### 协作与文件
+| 工具 | 用途 |
+|:---|:---|
+| `kg_discuss(create/reply/list)` | 跨 AI 实例讨论 |
+| `kg_meeting(join/post/status)` | 多 AI 协作会议 |
+| `kg_files(list/read/download)` | 项目文件管理 |
+| `kg_ref(list/get/save)` | 外部参考资料管理 |
+
+## 核心原则
+
+1. **先查图谱再看代码** — 在 grep/搜索代码之前，先用 `kg_flowchart(search)` 或 `kg_doc(search)` 查找相关节点，通常能直接定位到关键文件和逻辑说明，减少 80% 的盲目搜索。
+
+2. **每完成一步就 update task** — 使用 `kg_task(update)` 记录每个阶段的进展，遇到问题用 `log_type:"issue"` 记录，找到方案用 `log_type:"solution"` 记录。
+
+3. **改完代码必须回写图谱** — 修改了代码后，检查对应的流程图节点文档是否需要更新。新增文件要 `bind`，逻辑变更要 `update_node` 的 docContent。
+
+4. **子图递归探索** — 节点如果有 `subFlowchart` 字段，说明它有更细粒度的子流程图。理解细节时要递归下探。
+
+## 节点文档模板
+
+创建或更新节点 `docContent` 时，推荐使用以下结构：
+
+```markdown
+## 职责
+一句话说清本模块的核心职责。
+
+## 输入 / 输出
+- 输入: 进入本模块的数据或请求
+- 输出: 本模块产出的数据或响应
+
+## 核心逻辑
+1. 步骤一
+2. 步骤二
+3. ...（3-7 步为宜）
+
+## 边界条件
+- 它不负责什么（明确排除）
+- 错误处理策略
+
+## 关键文件
+- path/to/main.go — 主逻辑
+- path/to/helper.go — 辅助函数
+```
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|:---|:---|
+| API 超时/网络错误 | 重试一次，仍失败则告知用户 |
+| JSON 解析失败 | fallback 到纯文本输出 |
+| 找不到节点 | 用 `kg_flowchart(search)` 模糊搜索 |
+| 工具调用失败 | 检查参数格式，确保 JSON 数组/对象格式正确 |
+
+## 输出格式
+
+- 逻辑说明用 ASCII 流程图
+- 对比分析用 Markdown 表格
+- 代码引用注明文件路径和行号
+- 方案说明要简洁，避免不必要的冗余