@ppdocs/mcp 3.9.1 → 3.12.0

package/dist/tools/pitfalls.js

@@ -0,0 +1,190 @@
+/**
+ * 💡 kg_pitfall — 踩坑经验管理
+ * 记录项目中遇到的问题、根因和解决方案，避免重复踩坑
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { decodeObjectStrings } from '../utils.js';
+import { safeTool, wrap } from './shared.js';
+const SEVERITY_ICONS = {
+    critical: '🔴',
+    warning: '🟡',
+    info: '🔵',
+};
+const STATUS_ICONS = {
+    open: '🔓',
+    resolved: '✅',
+    recurring: '🔄',
+};
+export function registerPitfallTools(server) {
+    const client = () => getClient();
+    server.tool('kg_pitfall', '💡 踩坑经验 — 记录和查询项目中的踩坑经验，避免重复踩坑。\n' +
+        '遇到问题时用 create 记录现象和根因，找到方案后用 resolve 标记解决。\n' +
+        '下次遇到类似问题先 search 查历史经验。\n' +
+        'actions: create|get|update|search|resolve|list|delete', {
+        action: z.enum(['create', 'get', 'update', 'search', 'resolve', 'list', 'delete'])
+            .describe('操作类型'),
+        id: z.string().optional().describe('踩坑经验 ID (get/update/resolve/delete)'),
+        title: z.string().optional().describe('标题 (create)'),
+        category: z.string().optional().describe('分类: protocol/concurrency/config/logic/ui/other (create/update/search)'),
+        symptom: z.string().optional().describe('现象描述 Markdown (create/update)'),
+        root_cause: z.string().optional().describe('根因分析 Markdown (create/update)'),
+        solution: z.string().optional().describe('解决方案 Markdown (create/update/resolve)'),
+        prevention: z.string().optional().describe('预防措施 (create/update)'),
+        severity: z.string().optional().describe('严重程度: critical/warning/info (create/update)'),
+        related_nodes: z.array(z.string()).optional().describe('关联流程图节点 ID 列表 (create/update)'),
+        source_task: z.string().optional().describe('来源任务 ID (create)'),
+        tags: z.array(z.string()).optional().describe('标签列表 (create/update)'),
+        query: z.string().optional().describe('搜索关键词 (search)'),
+        status: z.string().optional().describe('状态过滤: open/resolved/recurring (search/list)'),
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        switch (decoded.action) {
+            case 'list': {
+                const pitfalls = decoded.status || decoded.category
+                    ? await client().searchPitfalls('', decoded.status, decoded.category)
+                    : await client().listPitfalls();
+                if (pitfalls.length === 0)
+                    return wrap('当前没有踩坑经验记录');
+                const lines = [
+                    `💡 踩坑经验 (${pitfalls.length})`,
+                    '',
+                    '| 状态 | 严重 | 标题 | 分类 | 标签 | 更新 |',
+                    '|:-----|:-----|:-----|:-----|:-----|:-----|',
+                ];
+                for (const p of pitfalls) {
+                    const statusIcon = STATUS_ICONS[p.status] || p.status;
+                    const sevIcon = SEVERITY_ICONS[p.severity] || p.severity;
+                    const tags = p.tags.length > 0 ? p.tags.join(',') : '-';
+                    const date = p.updated_at.substring(0, 10);
+                    lines.push(`| ${statusIcon} | ${sevIcon} | ${p.title} | ${p.category} | ${tags} | ${date} |`);
+                }
+                return wrap(lines.join('\n'));
+            }
+            case 'get': {
+                if (!decoded.id)
+                    return wrap('❌ get 需要 id');
+                const p = await client().getPitfall(decoded.id);
+                if (!p)
+                    return wrap(`未找到踩坑经验: ${decoded.id}`);
+                const sevIcon = SEVERITY_ICONS[p.severity] || p.severity;
+                const statusIcon = STATUS_ICONS[p.status] || p.status;
+                const lines = [
+                    `# ${sevIcon} ${p.title}`,
+                    '',
+                    `| 字段 | 值 |`,
+                    `|:---|:---|`,
+                    `| ID | ${p.id} |`,
+                    `| 状态 | ${statusIcon} ${p.status} |`,
+                    `| 严重程度 | ${sevIcon} ${p.severity} |`,
+                    `| 分类 | ${p.category} |`,
+                    `| 标签 | ${p.tags.join(', ') || '-'} |`,
+                    `| 关联节点 | ${p.related_nodes.join(', ') || '-'} |`,
+                ];
+                if (p.source_task)
+                    lines.push(`| 来源任务 | ${p.source_task} |`);
+                lines.push(`| 创建 | ${p.created_at.substring(0, 19)} |`);
+                lines.push(`| 更新 | ${p.updated_at.substring(0, 19)} |`);
+                if (p.resolved_at)
+                    lines.push(`| 解决 | ${p.resolved_at.substring(0, 19)} |`);
+                if (p.symptom) {
+                    lines.push('', '## 现象', '', p.symptom);
+                }
+                if (p.root_cause) {
+                    lines.push('', '## 根因', '', p.root_cause);
+                }
+                if (p.solution) {
+                    lines.push('', '## 解决方案', '', p.solution);
+                }
+                if (p.prevention) {
+                    lines.push('', '## 预防措施', '', p.prevention);
+                }
+                return wrap(lines.join('\n'));
+            }
+            case 'create': {
+                if (!decoded.title)
+                    return wrap('❌ create 需要 title');
+                const pitfall = await client().createPitfall({
+                    title: decoded.title,
+                    category: decoded.category,
+                    symptom: decoded.symptom,
+                    root_cause: decoded.root_cause,
+                    solution: decoded.solution,
+                    prevention: decoded.prevention,
+                    severity: decoded.severity,
+                    related_nodes: decoded.related_nodes,
+                    source_task: decoded.source_task,
+                    tags: decoded.tags,
+                });
+                return wrap(`✅ 踩坑经验已创建\n\n- ID: ${pitfall.id}\n- 标题: ${pitfall.title}\n- 分类: ${pitfall.category}\n- 严重程度: ${pitfall.severity}`);
+            }
+            case 'update': {
+                if (!decoded.id)
+                    return wrap('❌ update 需要 id');
+                const existing = await client().getPitfall(decoded.id);
+                if (!existing)
+                    return wrap(`❌ 未找到踩坑经验: ${decoded.id}`);
+                const updated = {
+                    ...existing,
+                    ...(decoded.title && { title: decoded.title }),
+                    ...(decoded.category && { category: decoded.category }),
+                    ...(decoded.symptom && { symptom: decoded.symptom }),
+                    ...(decoded.root_cause && { root_cause: decoded.root_cause }),
+                    ...(decoded.solution && { solution: decoded.solution }),
+                    ...(decoded.prevention && { prevention: decoded.prevention }),
+                    ...(decoded.severity && { severity: decoded.severity }),
+                    ...(decoded.related_nodes && { related_nodes: decoded.related_nodes }),
+                    ...(decoded.tags && { tags: decoded.tags }),
+                    updated_at: new Date().toISOString(),
+                };
+                await client().savePitfall(updated);
+                return wrap(`✅ 踩坑经验已更新 (${decoded.id})`);
+            }
+            case 'resolve': {
+                if (!decoded.id)
+                    return wrap('❌ resolve 需要 id');
+                const existing = await client().getPitfall(decoded.id);
+                if (!existing)
+                    return wrap(`❌ 未找到踩坑经验: ${decoded.id}`);
+                const now = new Date().toISOString();
+                const resolved = {
+                    ...existing,
+                    status: 'resolved',
+                    resolved_at: now,
+                    updated_at: now,
+                    ...(decoded.solution && { solution: decoded.solution }),
+                    ...(decoded.prevention && { prevention: decoded.prevention }),
+                };
+                await client().savePitfall(resolved);
+                return wrap(`✅ 踩坑经验已标记为解决 (${decoded.id})`);
+            }
+            case 'search': {
+                const query = decoded.query || '';
+                const results = await client().searchPitfalls(query, decoded.status, decoded.category);
+                if (results.length === 0)
+                    return wrap(`未找到匹配的踩坑经验 (搜索: "${query}")`);
+                const lines = [
+                    `💡 搜索结果: "${query}" (${results.length} 条)`,
+                    '',
+                    '| 状态 | 严重 | 标题 | 分类 | ID |',
+                    '|:-----|:-----|:-----|:-----|:---|',
+                ];
+                for (const p of results) {
+                    const statusIcon = STATUS_ICONS[p.status] || p.status;
+                    const sevIcon = SEVERITY_ICONS[p.severity] || p.severity;
+                    lines.push(`| ${statusIcon} | ${sevIcon} | ${p.title} | ${p.category} | ${p.id} |`);
+                }
+                lines.push('', '> 用 `kg_pitfall(get, id:"xxx")` 查看详情');
+                return wrap(lines.join('\n'));
+            }
+            case 'delete': {
+                if (!decoded.id)
+                    return wrap('❌ delete 需要 id');
+                const ok = await client().deletePitfall(decoded.id);
+                return wrap(ok ? `✅ 踩坑经验已删除 (${decoded.id})` : `ℹ️ 未找到踩坑经验 (${decoded.id})`);
+            }
+            default:
+                return wrap(`❌ 未知 action: ${decoded.action}`);
+        }
+    }));
+}

package/dist/tools/refs.js

@@ -2,6 +2,13 @@ import { z } from 'zod';
 import { getClient } from '../storage/httpClient.js';
 import { decodeObjectStrings } from '../utils.js';
 import { safeTool, wrap } from './shared.js';
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1048576)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1048576).toFixed(1)} MB`;
+}
 const linkSchema = z.object({
     url: z.string(),
     label: z.string(),
@@ -19,8 +26,10 @@ export function registerReferenceTools(server) {
     const client = () => getClient();
     server.tool('kg_ref', '📎 外部参考 — 管理项目引用的第三方资料、链接、脚本和样例文件。\n' +
         '涉及参考资料时主动调用：list 查看已有 → get 读详情 → read_file 读附件内容 → save 新增。\n' +
-        'actions: list|get|save|delete|read_file', {
-        action: z.enum(['list', 'get', 'save', 'delete', 'read_file']).describe('操作类型'),
+        '★ fetch: 输入URL自动拉取网页内容到本地，生成解析报告，支持持续更新（refetch）。\n' +
+        '★ import_file: 导入本地文件内容到参考系统（自动保存内容副本+版本追踪）。\n' +
+        'actions: list|get|save|delete|read_file|fetch|refetch|import_file|reimport', {
+        action: z.enum(['list', 'get', 'save', 'delete', 'read_file', 'fetch', 'refetch', 'import_file', 'reimport']).describe('操作类型'),
         id: z.string().optional().describe('参考 ID'),
         title: z.string().optional().describe('参考标题 (save)'),
         summary: z.string().optional().describe('Markdown 总结 (save)'),
@@ -28,7 +37,8 @@ export function registerReferenceTools(server) {
         files: z.array(fileSchema).optional().describe('参考文件 (save)'),
         scripts: z.array(fileSchema).optional().describe('解析脚本 (save)'),
         adoptedBy: z.array(adoptedNodeSchema).optional().describe('已采用该参考的节点 (save)'),
-        path: z.string().optional().describe('参考文件路径 (read_file)'),
+        path: z.string().optional().describe('参考文件路径 (read_file/import_file)'),
+        url: z.string().optional().describe('要拉取的文档 URL (fetch/refetch)'),
     }, async (args) => safeTool(async () => {
         const decoded = decodeObjectStrings(args);
         switch (decoded.action) {
@@ -39,11 +49,12 @@ export function registerReferenceTools(server) {
                 const lines = [
                     `📎 外部参考 (${refs.length})`,
                     '',
-                    '| ID | 标题 | 链接 | 文件 | 已采用 |',
-                    '|:---|:---|---:|---:|---:|',
+                    '| ID | 标题 | 链接 | 文件 | 拉取 | 已采用 |',
+                    '|:---|:---|---:|---:|---:|---:|',
                 ];
                 for (const ref of refs) {
-                    lines.push(`| ${ref.id} | ${ref.title} | ${ref.links.length} | ${ref.files.length} | ${ref.adoptedBy.length} |`);
+                    const fetchCount = ref.fetchHistory?.length || 0;
+                    lines.push(`| ${ref.id} | ${ref.title} | ${ref.links.length} | ${ref.files.length} | ${fetchCount} | ${ref.adoptedBy.length} |`);
                 }
                 return wrap(lines.join('\n'));
             }
@@ -61,9 +72,17 @@ export function registerReferenceTools(server) {
                     `- Files: ${ref.files.length}`,
                     `- Scripts: ${ref.scripts.length}`,
                     `- AdoptedBy: ${ref.adoptedBy.length}`,
-                    '',
-                    ref.summary || '(无摘要)',
                 ];
+                if (ref.sourceUrl) {
+                    lines.push(`- SourceURL: ${ref.sourceUrl}`);
+                }
+                if (ref.fetchHistory && ref.fetchHistory.length > 0) {
+                    lines.push(`- FetchCount: ${ref.fetchHistory.length} 次`);
+                    lines.push(`- LastFetch: ${ref.fetchHistory[ref.fetchHistory.length - 1].fetchedAt}`);
+                }
+                lines.push(`- Created: ${ref.createdAt}`);
+                lines.push(`- Updated: ${ref.updatedAt}`);
+                lines.push('', ref.summary || '(无摘要)');
                 if (ref.links.length > 0) {
                     lines.push('', '## Links');
                     for (const link of ref.links) {
@@ -82,6 +101,20 @@ export function registerReferenceTools(server) {
                         lines.push(`- ${script.name}: ${script.path}`);
                     }
                 }
+                if (ref.fetchHistory && ref.fetchHistory.length > 0) {
+                    lines.push('', '## Fetch History');
+                    lines.push('| # | 时间 | 标题 | 大小 | 文件 |');
+                    lines.push('|:--|:-----|:-----|-----:|:-----|');
+                    ref.fetchHistory.forEach((h, i) => {
+                        lines.push(`| ${i + 1} | ${h.fetchedAt.substring(0, 19)} | ${h.title} | ${formatBytes(h.contentLength)} | ${h.contentFile} |`);
+                    });
+                }
+                if (ref.adoptedBy.length > 0) {
+                    lines.push('', '## AdoptedBy');
+                    for (const node of ref.adoptedBy) {
+                        lines.push(`- ${node.nodeLabel} [${node.chartId}/${node.nodeId}]`);
+                    }
+                }
                 return wrap(lines.join('\n'));
             }
             case 'save': {
@@ -121,6 +154,113 @@ export function registerReferenceTools(server) {
                 const content = await client().readReferenceFile(decoded.path);
                 return wrap(content);
             }
+            case 'fetch': {
+                if (!decoded.url)
+                    return wrap('❌ fetch 需要 url (要拉取的文档地址)');
+                const result = await client().fetchRefUrl(decoded.url, decoded.id);
+                const lines = [
+                    `✅ 文档已拉取并保存`,
+                    '',
+                    `| 字段 | 值 |`,
+                    `|:---|:---|`,
+                    `| 参考 ID | ${result.refId} |`,
+                    `| 标题 | ${result.title} |`,
+                    `| 内容文件 | ${result.contentFile} |`,
+                    `| 内容大小 | ${formatBytes(result.contentLength)} |`,
+                    `| 累计拉取 | ${result.fetchCount} 次 |`,
+                    '',
+                    '### 内容预览',
+                    '',
+                    result.contentPreview.substring(0, 500),
+                    '',
+                    `> 💡 用 \`kg_ref(get, id:"${result.refId}")\` 查看完整详情`,
+                    `> 💡 用 \`kg_ref(read_file, path:"${result.contentFile}")\` 读取完整内容`,
+                    `> 💡 用 \`kg_ref(refetch, id:"${result.refId}")\` 重新拉取最新版本`,
+                ];
+                return wrap(lines.join('\n'));
+            }
+            case 'refetch': {
+                if (!decoded.id)
+                    return wrap('❌ refetch 需要 id (参考 ID)');
+                const ref = await client().getReference(decoded.id);
+                if (!ref)
+                    return wrap(`❌ 未找到参考: ${decoded.id}`);
+                const refetchUrl = decoded.url || ref.sourceUrl;
+                if (!refetchUrl)
+                    return wrap(`❌ 参考 ${decoded.id} 没有 sourceUrl，请提供 url 参数`);
+                const result = await client().fetchRefUrl(refetchUrl, decoded.id);
+                const lines = [
+                    `✅ 文档已重新拉取 (第 ${result.fetchCount} 次)`,
+                    '',
+                    `| 字段 | 值 |`,
+                    `|:---|:---|`,
+                    `| 参考 ID | ${result.refId} |`,
+                    `| 标题 | ${result.title} |`,
+                    `| 新内容文件 | ${result.contentFile} |`,
+                    `| 内容大小 | ${formatBytes(result.contentLength)} |`,
+                    '',
+                    '### 内容预览',
+                    '',
+                    result.contentPreview.substring(0, 300),
+                ];
+                return wrap(lines.join('\n'));
+            }
+            case 'import_file': {
+                if (!decoded.id)
+                    return wrap('❌ import_file 需要 id (参考 ID)');
+                if (!decoded.path)
+                    return wrap('❌ import_file 需要 path (本地文件路径)');
+                const result = await client().importLocalFile(decoded.id, decoded.path);
+                const lines = [
+                    `✅ 文件内容已导入参考系统`,
+                    '',
+                    `| 字段 | 值 |`,
+                    `|:---|:---|`,
+                    `| 参考 ID | ${result.refId} |`,
+                    `| 源文件 | ${result.sourcePath} |`,
+                    `| 存储文件 | ${result.storedFile} |`,
+                    `| 内容大小 | ${formatBytes(result.contentLength)} |`,
+                    `| 累计导入 | ${result.importCount} 次 |`,
+                    '',
+                    '### 内容预览',
+                    '',
+                    result.contentPreview.substring(0, 300),
+                    '',
+                    `> 💡 用 \`kg_ref(read_file, path:"${result.storedFile}")\` 读取完整内容`,
+                    `> 💡 用 \`kg_ref(reimport, id:"${result.refId}", path:"${result.sourcePath}")\` 重新导入最新版本`,
+                ];
+                return wrap(lines.join('\n'));
+            }
+            case 'reimport': {
+                if (!decoded.id)
+                    return wrap('❌ reimport 需要 id (参考 ID)');
+                const ref = await client().getReference(decoded.id);
+                if (!ref)
+                    return wrap(`❌ 未找到参考: ${decoded.id}`);
+                // 获取源文件路径: 优先使用参数中的 path, 否则取最后一次导入的源路径
+                const reimportPath = decoded.path ||
+                    (ref.fileImportHistory && ref.fileImportHistory.length > 0
+                        ? ref.fileImportHistory[ref.fileImportHistory.length - 1].sourcePath
+                        : null);
+                if (!reimportPath)
+                    return wrap(`❌ 参考 ${decoded.id} 没有导入历史，请提供 path 参数`);
+                const result = await client().importLocalFile(decoded.id, reimportPath);
+                const lines = [
+                    `✅ 文件已重新导入 (第 ${result.importCount} 次)`,
+                    '',
+                    `| 字段 | 值 |`,
+                    `|:---|:---|`,
+                    `| 参考 ID | ${result.refId} |`,
+                    `| 源文件 | ${result.sourcePath} |`,
+                    `| 新存储文件 | ${result.storedFile} |`,
+                    `| 内容大小 | ${formatBytes(result.contentLength)} |`,
+                    '',
+                    '### 内容预览',
+                    '',
+                    result.contentPreview.substring(0, 300),
+                ];
+                return wrap(lines.join('\n'));
+            }
             default:
                 return wrap(`❌ 未知 action: ${decoded.action}`);
         }

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/dist/tools/tasks.js

@@ -8,7 +8,8 @@ import { decodeObjectStrings } from '../utils.js';
 import { wrap, safeTool } from './shared.js';
 export function registerTaskTools(server, ctx) {
     const client = () => getClient();
-    server.tool('kg_task', '📝 任务记录 — action: create(创建,建议bindTo关联节点)|get(查询)|update(追加进度)|archive(归档)|delete(删除)。⚠️ 每完成一个步骤必须立即update!', {
+    server.tool('kg_task', '📝 任务记录 — action: create(创建,建议bindTo关联节点)|get(查询)|update(追加进度)|archive(归档)|delete(删除)。⚠️ 每完成一个步骤必须立即update!\n' +
+        '★ 涉及逻辑变更的任务，创建后必须先执行 design-first 工作流（kg_workflow(id:"design-first")），在流程图中完成设计并验证后才能编码。', {
         action: z.enum(['create', 'get', 'update', 'archive', 'delete'])
             .describe('操作类型'),
         title: z.string().optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "3.9.1",
+  "version": "3.12.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 表格
+- 代码引用注明文件路径和行号
+- 方案说明要简洁，避免不必要的冗余