@ppdocs/mcp 3.10.0 → 3.12.0

package/dist/cli.js

@@ -90,7 +90,7 @@ function showHelp() {
 ppdocs MCP CLI
 
 Commands:
-  init    Full setup: .ppdocs + templates + MCP registration
+  init    Full setup: .ppdocs + templates + MCP registration (Claude/Codex/OpenCode/Gemini)
   bind    Lightweight: only create .ppdocs (for adding projects to existing MCP)
 
 Usage:
@@ -270,6 +270,13 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
         for (const pair of envPairs) {
             args.push(envFlag, pair);
         }
+        // macOS/Linux: 必须注入 PATH，否则 Claude Code 启动 MCP 时可能找不到 npx/node
+        // (Claude Code 进程的 PATH 通常不含 /opt/homebrew/bin 等 Homebrew/nvm 路径)
+        if (process.platform !== 'win32') {
+            const macExtraPaths = '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin';
+            const fullPath = `${process.env.PATH || '/usr/bin:/bin'}:${macExtraPaths}`;
+            args.push(envFlag, `PATH=${fullPath}`);
+        }
         args.push(serverName, '--', 'npx', '-y', '@ppdocs/mcp@latest');
         const result = spawnSync(cli, args, { stdio: 'inherit', shell: true });
         if (result.status !== 0)
@@ -303,6 +310,24 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
             console.log(`⚠️  Codex MCP registration failed`);
         }
     }
+    // OpenCode CLI (opencode mcp add 支持 -e 环境变量注入)
+    if (commandExists('opencode')) {
+        detected.push('OpenCode');
+        try {
+            execSilent(`opencode mcp remove ${serverName}`);
+            mcpAdd('opencode', '-e');
+        }
+        catch {
+            // fallback: 写入 ~/.opencode/mcp.json
+            try {
+                const opencodeConfig = path.join(os.homedir(), '.opencode', 'mcp.json');
+                createMcpConfigAt(opencodeConfig, apiUrl, { user, projectRoot: cwd });
+            }
+            catch {
+                console.log(`⚠️  OpenCode MCP registration failed`);
+            }
+        }
+    }
     // Gemini CLI (gemini mcp add 不支持 --env，直接写 settings.json)
     if (commandExists('gemini') && !skipGemini) {
         detected.push('Gemini');
@@ -315,7 +340,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
         }
     }
     if (detected.length === 0) {
-        console.log(`ℹ️  No AI CLI detected (claude/codex/gemini), creating .mcp.json for manual config`);
+        console.log(`ℹ️  No AI CLI detected (claude/codex/opencode/gemini), creating .mcp.json for manual config`);
         return false;
     }
     console.log(`✅ Registered MCP for: ${detected.join(', ')}`);

package/dist/index.js

@@ -19,6 +19,51 @@ import { loadConfig, generateAgentId } from './config.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 const VERSION = pkg.version;
+/** 启动时连通性检查 — 非阻塞，3秒超时，结果输出到 stderr 供调试 */
+async function checkConnectivity(apiUrl) {
+    // Node.js 18+ 内置 fetch; 旧版本跳过检查
+    if (typeof globalThis.fetch !== 'function') {
+        console.error(`[connectivity] ⏭️  fetch unavailable (Node.js < 18), skipping connectivity check`);
+        return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    try {
+        const response = await fetch(apiUrl, { signal: controller.signal });
+        if (response.ok) {
+            console.error(`[connectivity] ✅ ppdocs server reachable`);
+        }
+        else {
+            console.error(`[connectivity] ⚠️  ppdocs server responded HTTP ${response.status} — check API key/project ID`);
+        }
+    }
+    catch (err) {
+        const apiHost = apiUrl.replace(/\/api\/.*$/, '');
+        if (err instanceof Error && err.name === 'AbortError') {
+            console.error(`[connectivity] ❌ Connection TIMEOUT (3s) to ${apiHost}`);
+            console.error(`[connectivity]    Possible causes:`);
+            console.error(`[connectivity]    1. ppdocs desktop app is not running on the target machine`);
+            console.error(`[connectivity]    2. Firewall blocking port (check Windows Firewall inbound rules)`);
+            console.error(`[connectivity]    3. IP address changed (re-run init with correct --api)`);
+            console.error(`[connectivity]    4. Not on the same network`);
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('ECONNREFUSED')) {
+                console.error(`[connectivity] ❌ Connection REFUSED to ${apiHost}`);
+                console.error(`[connectivity]    ppdocs desktop app is not running, or port is wrong`);
+            }
+            else {
+                console.error(`[connectivity] ❌ Cannot reach ${apiHost}: ${msg}`);
+            }
+        }
+        console.error(`[connectivity]    API URL: ${apiUrl}`);
+        console.error(`[connectivity]    MCP will still start — tools will fail until server is reachable`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 // 检查是否为 CLI 命令
 const args = process.argv.slice(2);
 if (args.length > 0) {
@@ -32,7 +77,9 @@ async function main() {
     // 有配置 → 自动初始化 (环境变量 / .ppdocs)
     if (config) {
         initClient(config.apiUrl);
-        console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user}`);
+        console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user} | source: ${config.source}`);
+        // 启动时连通性检查 (非阻塞, 3秒超时)
+        checkConnectivity(config.apiUrl).catch(() => { });
     }
     else {
         console.error(`ppdocs MCP v${VERSION} | ⏳ 等待 kg_init 初始化项目上下文...`);

package/dist/storage/httpClient.d.ts

@@ -4,7 +4,7 @@
  *
  * API URL 格式: http://localhost:20099/api/:projectId/:password/...
  */
-import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, WorkflowSummary, WorkflowDoc, WorkflowSelector, Reference } from './types.js';
+import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, WorkflowSummary, WorkflowDoc, WorkflowSelector, Reference, FetchResult, FileImportResult, Pitfall, PitfallSummary } from './types.js';
 export declare class PpdocsApiClient {
     private baseUrl;
     private serverUrl;
@@ -31,6 +31,27 @@ export declare class PpdocsApiClient {
     readReferenceFile(path: string): Promise<string>;
     /** 复制本地文件到参考文件库, 返回相对路径列表 */
     copyReferenceFiles(paths: string[], targetDir?: string): Promise<string[]>;
+    /** 从 URL 拉取文档内容并保存为参考 */
+    fetchRefUrl(url: string, refId?: string): Promise<FetchResult>;
+    /** 导入本地文件内容到参考系统 */
+    importLocalFile(refId: string, sourcePath: string): Promise<FileImportResult>;
+    listPitfalls(): Promise<PitfallSummary[]>;
+    getPitfall(pitfallId: string): Promise<Pitfall | null>;
+    createPitfall(input: {
+        title: string;
+        category?: string;
+        symptom?: string;
+        root_cause?: string;
+        solution?: string;
+        prevention?: string;
+        severity?: string;
+        related_nodes?: string[];
+        source_task?: string;
+        tags?: string[];
+    }): Promise<Pitfall>;
+    savePitfall(pitfall: Pitfall): Promise<boolean>;
+    deletePitfall(pitfallId: string): Promise<boolean>;
+    searchPitfalls(query: string, status?: string, category?: string): Promise<PitfallSummary[]>;
     listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
     getTask(taskId: string, mode?: 'smart' | 'full'): Promise<Task | null>;
     createTask(task: {

package/dist/storage/httpClient.js

@@ -168,6 +168,56 @@ export class PpdocsApiClient {
             body: JSON.stringify({ paths, target_dir: targetDir }),
         });
     }
+    /** 从 URL 拉取文档内容并保存为参考 */
+    async fetchRefUrl(url, refId) {
+        return this.request('/refs/fetch-url', {
+            method: 'POST',
+            body: JSON.stringify({ url, ref_id: refId }),
+        });
+    }
+    /** 导入本地文件内容到参考系统 */
+    async importLocalFile(refId, sourcePath) {
+        return this.request('/refs/import-file', {
+            method: 'POST',
+            body: JSON.stringify({ ref_id: refId, source_path: sourcePath }),
+        });
+    }
+    // ============ 踩坑经验 API ============
+    async listPitfalls() {
+        return this.request('/pitfalls');
+    }
+    async getPitfall(pitfallId) {
+        try {
+            return await this.request(`/pitfalls/${encodeURIComponent(pitfallId)}`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async createPitfall(input) {
+        return this.request('/pitfalls', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async savePitfall(pitfall) {
+        await this.request(`/pitfalls/${encodeURIComponent(pitfall.id)}`, {
+            method: 'PUT',
+            body: JSON.stringify(pitfall),
+        });
+        return true;
+    }
+    async deletePitfall(pitfallId) {
+        return this.request(`/pitfalls/${encodeURIComponent(pitfallId)}`, {
+            method: 'DELETE',
+        });
+    }
+    async searchPitfalls(query, status, category) {
+        return this.request('/pitfalls/search', {
+            method: 'POST',
+            body: JSON.stringify({ query, status, category }),
+        });
+    }
     // ============ 任务管理 ============
     async listTasks(status) {
         const query = status ? `?status=${status}` : '';

package/dist/storage/types.d.ts

@@ -45,6 +45,41 @@ export interface Reference {
     adoptedBy: AdoptedNode[];
     createdAt: string;
     updatedAt: string;
+    sourceUrl?: string;
+    fetchHistory?: FetchRecord[];
+    fileImportHistory?: FileImportRecord[];
+}
+export interface FetchRecord {
+    fetchedAt: string;
+    url: string;
+    title: string;
+    contentFile: string;
+    contentLength: number;
+    contentPreview: string;
+}
+export interface FetchResult {
+    refId: string;
+    title: string;
+    contentFile: string;
+    contentLength: number;
+    contentPreview: string;
+    fetchCount: number;
+}
+export interface FileImportRecord {
+    importedAt: string;
+    sourcePath: string;
+    storedFile: string;
+    contentLength: number;
+    contentPreview: string;
+    fileType: string;
+}
+export interface FileImportResult {
+    refId: string;
+    sourcePath: string;
+    storedFile: string;
+    contentLength: number;
+    contentPreview: string;
+    importCount: number;
 }
 export interface FileInfo {
     name: string;
@@ -95,3 +130,30 @@ export interface TaskSummary {
     updated_at: string;
     last_log?: string;
 }
+export interface Pitfall {
+    id: string;
+    title: string;
+    category: string;
+    symptom: string;
+    root_cause: string;
+    solution: string;
+    prevention: string;
+    related_nodes: string[];
+    source_task?: string;
+    severity: string;
+    status: string;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+    resolved_at?: string;
+}
+export interface PitfallSummary {
+    id: string;
+    title: string;
+    category: string;
+    severity: string;
+    status: string;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+}

package/dist/tools/flowchart.js

@@ -318,6 +318,7 @@ function findDirectedPath(chart, fromId, toId) {
 export function registerFlowchartTools(server, _ctx) {
     const client = () => getClient();
     server.tool('kg_flowchart', '🔀 逻辑流程图 — 项目知识图谱的核心。每个节点代表一个模块/函数/概念，节点可绑定文件、内嵌版本化文档。\n' +
+        '★★ 编码前必须先设计：用 batch_add/update_node 在流程图中设计逻辑并验证每个节点正确后才能编码。执行 kg_workflow(id:"design-first") 查看完整工作流 ★★\n' +
         '⚡ 开始任何任务前必须先查图谱：search 搜关键词 → get_node 看详情 → 有 subFlowchart 则递归下探。\n' +
         '📝 完成修改后必须回写：bind 绑定文件 → update_node 更新描述和文档 → 新模块用 batch_add。\n' +
         'actions: list|get|search|get_relations|find_path|get_node|update_node|delete_node|batch_add|bind|unbind|orphans|health|create_chart|delete_chart', {

package/dist/tools/index.d.ts

@@ -1,11 +1,11 @@
 /**
  * MCP 工具注册入口
- * 14 个工具, 8 个子模块
+ * 15 个工具, 9 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
  * 📊 导航:     kg_status                                         (1个)
  * 📚 知识:     kg_projects, kg_workflow                           (2个)
- * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref (4个)
+ * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref, kg_pitfall (5个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
  * 📘 文档查询: kg_doc(节点文档搜索/阅读/历史)                      (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)

package/dist/tools/index.js

@@ -1,11 +1,11 @@
 /**
  * MCP 工具注册入口
- * 14 个工具, 8 个子模块
+ * 15 个工具, 9 个子模块
  *
  * 🔗 初始化:   kg_init                                           (1个)
  * 📊 导航:     kg_status                                         (1个)
  * 📚 知识:     kg_projects, kg_workflow                           (2个)
- * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref (4个)
+ * 📝 工作流:   kg_task(任务记录), kg_files, kg_discuss(讨论区), kg_ref, kg_pitfall (5个)
  * 🔀 关系核心: kg_flowchart(逻辑流程图 — 关系型知识锚点)           (1个)
  * 📘 文档查询: kg_doc(节点文档搜索/阅读/历史)                      (1个)
  * 🔬 代码分析: code_scan, code_smart_context, code_full_path      (3个)
@@ -20,6 +20,7 @@ import { registerTaskTools } from './tasks.js';
 import { registerFileTools } from './files.js';
 import { registerDiscussionTools } from './discussion.js';
 import { registerReferenceTools } from './refs.js';
+import { registerPitfallTools } from './pitfalls.js';
 import { registerAnalyzerTools } from './analyzer.js';
 import { registerMeetingTools } from './meeting.js';
 import { registerFlowchartTools } from './flowchart.js';
@@ -38,6 +39,7 @@ export function registerTools(server, projectId, user, agentId, onProjectChange)
     registerFileTools(server);
     registerDiscussionTools(server, ctx);
     registerReferenceTools(server);
+    registerPitfallTools(server);
     // 🔬 代码分析
     registerAnalyzerTools(server, ctx);
     // 🏛️ 多AI协作

package/dist/tools/pitfalls.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 💡 kg_pitfall — 踩坑经验管理
+ * 记录项目中遇到的问题、根因和解决方案，避免重复踩坑
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPitfallTools(server: McpServer): void;

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/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.10.0",
+  "version": "3.12.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",