@ppdocs/mcp 3.10.0 → 3.13.0

package/dist/tools/refs.js

@@ -2,33 +2,19 @@ import { z } from 'zod';
 import { getClient } from '../storage/httpClient.js';
 import { decodeObjectStrings } from '../utils.js';
 import { safeTool, wrap } from './shared.js';
-const linkSchema = z.object({
-    url: z.string(),
-    label: z.string(),
-});
-const fileSchema = z.object({
-    name: z.string(),
-    path: z.string(),
-});
-const adoptedNodeSchema = z.object({
-    chartId: z.string(),
-    nodeId: z.string(),
-    nodeLabel: z.string(),
-});
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1048576)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1048576).toFixed(1)} MB`;
+}
 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('操作类型'),
-        id: z.string().optional().describe('参考 ID'),
-        title: z.string().optional().describe('参考标题 (save)'),
-        summary: z.string().optional().describe('Markdown 总结 (save)'),
-        links: z.array(linkSchema).optional().describe('参考链接 (save)'),
-        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)'),
+    server.tool('kg_ref', '外部参考管理。fetch: 输入URL拉取网页内容到本地持久化。list/get/delete: 管理已有参考。\nactions: list|get|fetch|delete', {
+        action: z.enum(['list', 'get', 'fetch', 'delete']).describe('操作类型'),
+        id: z.string().optional().describe('参考 ID (get/delete/fetch时指定ID则为refetch)'),
+        url: z.string().optional().describe('要拉取的文档 URL (fetch)'),
     }, async (args) => safeTool(async () => {
         const decoded = decodeObjectStrings(args);
         switch (decoded.action) {
@@ -37,19 +23,20 @@ export function registerReferenceTools(server) {
                 if (refs.length === 0)
                     return wrap('当前没有外部参考');
                 const lines = [
-                    `📎 外部参考 (${refs.length})`,
+                    `外部参考 (${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} |`);
                 }
                 return wrap(lines.join('\n'));
             }
             case 'get': {
                 if (!decoded.id)
-                    return wrap('❌ get 需要 id');
+                    return wrap('get 需要 id');
                 const ref = await client().getReference(decoded.id);
                 if (!ref)
                     return wrap(`未找到外部参考: ${decoded.id}`);
@@ -59,11 +46,17 @@ export function registerReferenceTools(server) {
                     `- ID: ${ref.id}`,
                     `- Links: ${ref.links.length}`,
                     `- 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) {
@@ -76,53 +69,66 @@ export function registerReferenceTools(server) {
                         lines.push(`- ${file.name}: ${file.path}`);
                     }
                 }
-                if (ref.scripts.length > 0) {
-                    lines.push('', '## Scripts');
-                    for (const script of ref.scripts) {
-                        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} |`);
+                    });
                 }
                 return wrap(lines.join('\n'));
             }
-            case 'save': {
-                if (!decoded.id)
-                    return wrap('❌ save 需要 id');
-                if (!decoded.title)
-                    return wrap('❌ save 需要 title');
-                const existing = await client().getReference(decoded.id);
-                const now = new Date().toISOString();
-                // 直接传递原始路径给后端, Rust save_reference 会自动:
-                // 1. 检测绝对路径文件
-                // 2. 复制到公共文件池/外部参考/{项目名}/
-                // 3. 复制到 ref-files/ (供 read_file API 读取)
-                // 4. 替换为相对路径保存
-                await client().saveReference({
-                    id: decoded.id,
-                    title: decoded.title,
-                    summary: decoded.summary || existing?.summary || '',
-                    links: decoded.links || existing?.links || [],
-                    files: decoded.files || existing?.files || [],
-                    scripts: decoded.scripts || existing?.scripts || [],
-                    adoptedBy: decoded.adoptedBy || existing?.adoptedBy || [],
-                    createdAt: existing?.createdAt || now,
-                    updatedAt: now,
-                });
-                return wrap(`✅ 外部参考已保存 (${decoded.id})`);
+            case 'fetch': {
+                // 如果提供了 id 但没有 url，视为 refetch（从已有参考的 sourceUrl 重新拉取）
+                if (!decoded.url && decoded.id) {
+                    const ref = await client().getReference(decoded.id);
+                    if (!ref)
+                        return wrap(`未找到参考: ${decoded.id}`);
+                    if (!ref.sourceUrl)
+                        return wrap(`参考 ${decoded.id} 没有 sourceUrl，请提供 url 参数`);
+                    const result = await client().fetchRefUrl(ref.sourceUrl, decoded.id);
+                    return wrap([
+                        `文档已重新拉取 (第 ${result.fetchCount} 次)`,
+                        '',
+                        `| 字段 | 值 |`,
+                        `|:---|:---|`,
+                        `| 参考 ID | ${result.refId} |`,
+                        `| 标题 | ${result.title} |`,
+                        `| 内容大小 | ${formatBytes(result.contentLength)} |`,
+                        '',
+                        '### 内容预览',
+                        '',
+                        result.contentPreview.substring(0, 300),
+                    ].join('\n'));
+                }
+                if (!decoded.url)
+                    return wrap('fetch 需要 url (要拉取的文档地址)');
+                const result = await client().fetchRefUrl(decoded.url, decoded.id);
+                const lines = [
+                    `文档已拉取并保存`,
+                    '',
+                    `| 字段 | 值 |`,
+                    `|:---|:---|`,
+                    `| 参考 ID | ${result.refId} |`,
+                    `| 标题 | ${result.title} |`,
+                    `| 内容大小 | ${formatBytes(result.contentLength)} |`,
+                    `| 累计拉取 | ${result.fetchCount} 次 |`,
+                    '',
+                    '### 内容预览',
+                    '',
+                    result.contentPreview.substring(0, 500),
+                ];
+                return wrap(lines.join('\n'));
             }
             case 'delete': {
                 if (!decoded.id)
-                    return wrap('❌ delete 需要 id');
+                    return wrap('delete 需要 id');
                 const ok = await client().deleteReference(decoded.id);
-                return wrap(ok ? `✅ 外部参考已删除 (${decoded.id})` : `ℹ️ 未找到外部参考 (${decoded.id})`);
-            }
-            case 'read_file': {
-                if (!decoded.path)
-                    return wrap('❌ read_file 需要 path');
-                const content = await client().readReferenceFile(decoded.path);
-                return wrap(content);
+                return wrap(ok ? `外部参考已删除 (${decoded.id})` : `未找到外部参考 (${decoded.id})`);
             }
             default:
-                return wrap(`❌ 未知 action: ${decoded.action}`);
+                return wrap(`未知 action: ${decoded.action}`);
         }
     }));
 }

package/dist/tools/tasks.d.ts

@@ -1,6 +1,5 @@
 /**
- * 📝 kg_task (4→1) — 极简任务管理
- * AI 只需说人话写内容，后端负责所有格式化、分类、时间戳
+ * kg_task — 任务管理
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';

package/dist/tools/tasks.js

@@ -1,6 +1,5 @@
 /**
- * 📝 kg_task (4→1) — 极简任务管理
- * AI 只需说人话写内容，后端负责所有格式化、分类、时间戳
+ * kg_task — 任务管理
  */
 import { z } from 'zod';
 import { getClient } from '../storage/httpClient.js';
@@ -8,7 +7,7 @@ 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(创建)|get(查询)|update(追加进度)|archive(归档)|delete(删除)', {
         action: z.enum(['create', 'get', 'update', 'archive', 'delete'])
             .describe('操作类型'),
         title: z.string().optional()
@@ -26,9 +25,9 @@ export function registerTaskTools(server, ctx) {
         summary: z.string().optional()
             .describe('经验总结Markdown (archive)'),
         difficulties: z.array(z.string()).optional()
-            .describe('遇到的困难 (archive)'),
+            .describe('遇到的困难 (archive, 可选)'),
         solutions: z.array(z.string()).optional()
-            .describe('解决方案 (archive)'),
+            .describe('解决方案 (archive, 可选)'),
         status: z.enum(['active', 'archived', 'all']).optional()
             .describe('状态筛选 (get, 默认active)'),
         bindTo: z.string().optional()
@@ -40,12 +39,10 @@ export function registerTaskTools(server, ctx) {
         switch (decoded.action) {
             case 'create': {
                 if (!decoded.title)
-                    return wrap('❌ create 需要 title');
-                if (!decoded.description)
-                    return wrap('❌ create 需要 description');
+                    return wrap('create 需要 title');
                 const task = await client().createTask({
                     title: decoded.title,
-                    description: decoded.description,
+                    description: decoded.description || '',
                     goals: decoded.goals || []
                 }, ctx.user);
                 // 自动绑定到流程图节点
@@ -63,22 +60,18 @@ export function registerTaskTools(server, ctx) {
                                     node.boundTasks.push(task.id);
                                 }
                                 await client().saveFlowchart(chartId, chart);
-                                bindMsg = `\n🔗 已绑定到节点: ${decoded.bindTo} [${chartId}]`;
+                                bindMsg = `\n已绑定到节点: ${decoded.bindTo} [${chartId}]`;
                             }
                             else {
-                                bindMsg = `\n⚠️ 节点 "${decoded.bindTo}" 不存在于流程图 "${chartId}"`;
+                                bindMsg = `\n节点 "${decoded.bindTo}" 不存在于流程图 "${chartId}"`;
                             }
                         }
                     }
                     catch {
-                        bindMsg = `\n⚠️ 绑定失败`;
+                        bindMsg = `\n绑定失败`;
                     }
                 }
-                // 约束: 未绑定流程图 → 强制警告
-                if (!decoded.bindTo) {
-                    bindMsg = `\n\n⚠️ 【未关联知识锚点】此任务未绑定到任何流程图节点!\n💡 建议: 使用 kg_flowchart(get) 查看节点列表, 然后用 kg_flowchart(bind, nodeId, tasks:["${task.id}"]) 绑定\n📌 不关联的任务会成为孤岛数据, 无法被其他AI发现`;
-                }
-                return wrap(`✅ 任务已创建\nID: ${task.id}\n标题: ${task.title}\n验收标准: ${task.detail.goals.length}条${bindMsg}`);
+                return wrap(`任务已创建\nID: ${task.id}\n标题: ${task.title}\n验收标准: ${task.detail.goals.length}条${bindMsg}`);
             }
             case 'get': {
                 // 无参数 = 列出活跃任务
@@ -96,33 +89,33 @@ export function registerTaskTools(server, ctx) {
                         tasks = await client().listTasks(status);
                     }
                     if (tasks.length === 0)
-                        return wrap(`📋 ${status === 'archived' ? '归档' : '活跃'}任务为空`);
+                        return wrap(`${status === 'archived' ? '归档' : '活跃'}任务为空`);
                     const rows = tasks.map(t => {
-                        const icon = t.status === 'active' ? '🟢' : '⚪';
+                        const icon = t.status === 'active' ? '●' : '○';
                         const date = t.updated_at?.split('T')[0]?.slice(5) || '';
                         const log = (t.last_log || '').substring(0, 40);
                         return `| ${icon} | ${t.title} | ${t.id} | ${date} | ${log} |`;
                     }).join('\n');
-                    return wrap(`📋 共 ${tasks.length} 个任务\n\n| 状态 | 标题 | ID | 更新 | 最近日志 |\n|:-----|:-----|:---|:-----|:---------|\n${rows}`);
+                    return wrap(`共 ${tasks.length} 个任务\n\n| 状态 | 标题 | ID | 更新 | 最近日志 |\n|:-----|:-----|:---|:-----|:---------|\n${rows}`);
                 }
                 // 有 taskId = 获取详情 (结构化摘要)
                 if (decoded.taskId) {
                     const task = await client().getTask(decoded.taskId, 'smart');
                     if (!task)
-                        return wrap('❌ 任务未找到');
+                        return wrap('任务未找到');
                     const lines = [
-                        `📝 ${task.title}`,
+                        `${task.title}`,
                         `ID: ${task.id} | 状态: ${task.status}`,
                         `创建: ${task.created_at?.split('T')[0] || ''}`,
                     ];
                     if (task.detail?.description)
-                        lines.push(`\n📋 ${task.detail.description}`);
+                        lines.push(`\n${task.detail.description}`);
                     if (task.detail?.goals?.length) {
-                        lines.push(`\n🎯 验收标准:`);
+                        lines.push(`\n验收标准:`);
                         task.detail.goals.forEach((g, i) => lines.push(`  ${i + 1}. ☐ ${g}`));
                     }
                     if (task.logs?.length) {
-                        lines.push(`\n📊 进度日志 (${task.logs.length}条, 最近3条):`);
+                        lines.push(`\n进度日志 (${task.logs.length}条, 最近3条):`);
                         for (const log of task.logs.slice(-3)) {
                             lines.push(`  [${log.log_type}] ${log.time?.split('T')[0] || ''}: ${log.content?.substring(0, 120)}`);
                         }
@@ -151,18 +144,18 @@ export function registerTaskTools(server, ctx) {
                     if (!task)
                         return wrap('任务详情获取失败');
                     const lines = [
-                        `📝 ${task.title}`,
+                        `${task.title}`,
                         `ID: ${task.id} | 状态: ${task.status}`,
                         `创建: ${task.created_at?.split('T')[0] || ''}`,
                     ];
                     if (task.detail?.description)
-                        lines.push(`\n📋 ${task.detail.description}`);
+                        lines.push(`\n${task.detail.description}`);
                     if (task.detail?.goals?.length) {
-                        lines.push(`\n🎯 验收标准:`);
+                        lines.push(`\n验收标准:`);
                         task.detail.goals.forEach((g, i) => lines.push(`  ${i + 1}. ☐ ${g}`));
                     }
                     if (task.logs?.length) {
-                        lines.push(`\n📊 进度日志 (${task.logs.length}条, 最近3条):`);
+                        lines.push(`\n进度日志 (${task.logs.length}条, 最近3条):`);
                         for (const log of task.logs.slice(-3)) {
                             lines.push(`  [${log.log_type}] ${log.time?.split('T')[0] || ''}: ${log.content?.substring(0, 120)}`);
                         }
@@ -174,45 +167,38 @@ export function registerTaskTools(server, ctx) {
             }
             case 'update': {
                 if (!decoded.taskId)
-                    return wrap('❌ update 需要 taskId');
+                    return wrap('update 需要 taskId');
                 if (!decoded.content)
-                    return wrap('❌ update 需要 content');
+                    return wrap('update 需要 content');
                 // log_type 可选 — 不传则后端自动检测关键词
                 const task = await client().addTaskLog(decoded.taskId, decoded.content, decoded.log_type);
                 if (!task)
                     return wrap('更新失败(任务不存在或已归档)');
                 const lastLog = task.logs[task.logs.length - 1];
-                // 返回任务摘要 + 验收清单，让 AI 始终知道剩余目标
-                const goalsDisplay = task.detail.goals.length > 0
-                    ? task.detail.goals.map((g, i) => `  ${i + 1}. ☐ ${g}`).join('\n')
-                    : '  (无验收标准)';
-                return wrap(`✅ 进度已记录 [${lastLog?.log_type || 'progress'}]\n` +
-                    `📋 ${task.title} | 日志: ${task.logs.length}条\n` +
-                    `\n🎯 验收标准:\n${goalsDisplay}`);
+                return wrap(`进度已记录 [${lastLog?.log_type || 'progress'}]\n` +
+                    `${task.title} | 日志: ${task.logs.length}条`);
             }
             case 'archive': {
                 if (!decoded.taskId)
-                    return wrap('❌ archive 需要 taskId');
-                if (!decoded.summary)
-                    return wrap('❌ archive 需要 summary');
+                    return wrap('archive 需要 taskId');
                 const task = await client().completeTask(decoded.taskId, {
-                    summary: decoded.summary,
+                    summary: decoded.summary || '任务已完成',
                     difficulties: decoded.difficulties || [],
                     solutions: decoded.solutions || [],
                     references: []
                 });
                 if (!task)
                     return wrap('归档失败(任务不存在或已归档)');
-                return wrap(`✅ 任务已归档: ${task.title}`);
+                return wrap(`任务已归档: ${task.title}`);
             }
             case 'delete': {
                 if (!decoded.taskId)
-                    return wrap('❌ delete 需要 taskId');
+                    return wrap('delete 需要 taskId');
                 const ok = await client().deleteTask(decoded.taskId);
-                return wrap(ok ? `✅ 任务已删除 (ID: ${decoded.taskId})` : '❌ 删除失败(任务不存在)');
+                return wrap(ok ? `任务已删除 (ID: ${decoded.taskId})` : '删除失败(任务不存在)');
             }
             default:
-                return wrap(`❌ 未知 action: ${decoded.action}`);
+                return wrap(`未知 action: ${decoded.action}`);
         }
     }));
 }

package/dist/tools/workflow.js

@@ -4,9 +4,8 @@ import { decodeObjectStrings } from '../utils.js';
 import { safeTool, wrap } from './shared.js';
 export function registerWorkflowTools(server, _ctx) {
     const client = () => getClient();
-    server.tool('kg_workflow', '📘 文档工作流 — AI 的标准操作手册。每个工作流是一份 Markdown 文档，定义了特定场景下 AI 应该遵循的步骤和规范。\n' +
-        '调用方式：空参数=列出所有工作流；传 id=获取工作流正文；save/delete 需显式 action。\n' +
-        '典型用法：拿到任务后先 kg_workflow() 看有无相关工作流，有则 kg_workflow(id:"xxx") 读取并遵循执行。', {
+    server.tool('kg_workflow', '文档工作流。AI 的标准操作手册，每个工作流定义特定场景下应遵循的步骤。空参数=列出全部；传id=获取正文；save/delete需显式action。' +
+        'actions: list|get|save|delete', {
         action: z.enum(['list', 'get', 'save', 'delete']).optional().describe('省略时自动推断：无参数=list，有id=get'),
         id: z.string().optional().describe('工作流 ID'),
         scope: z.enum(['all', 'global', 'project']).optional().describe('范围：all(默认)|global|project'),

package/package.json

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

package/dist/tools/discussion.d.ts

@@ -1,15 +0,0 @@
-/**
- * 💬 kg_discuss (8 actions)
- * 合并: list, read, create, reply, close, delete, complete, history
- * 统一走 HTTP → Rust 后端 (单一写入者)
- * sender 格式: "projectId:user" (如 "p-ca3sgejg:张三")
- *
- * 权限模型:
- *   list/history  — 任何人可列出(全局可见)
- *   create        — 任何人可发起(指定参与项目ID)
- *   read/reply    — 仅讨论组内成员(initiator + participants)
- *   complete/close/delete — 仅发起人
- */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpContext } from './shared.js';
-export declare function registerDiscussionTools(server: McpServer, ctx: McpContext): void;