@ppdocs/mcp 3.2.35 → 3.2.37

package/dist/tools/docs.js

@@ -1,285 +0,0 @@
-/**
- * 📄 kg_doc (5合1) + 🏗️ kg_tree (2合1)
- * 合并: kg_create_node, kg_delete_node, kg_update_node, kg_read_node, kg_copy_node
- *       kg_get_tree, kg_get_docs_by_status
- */
-import { z } from 'zod';
-import { getClient } from '../storage/httpClient.js';
-import { decodeObjectStrings } from '../utils.js';
-import { wrap, safeTool, crossPrefix, formatDocMarkdown, formatTreeText, countTreeDocs } from './shared.js';
-export function registerDocTools(server, ctx) {
-    const client = () => getClient();
-    // ========== kg_doc: 文档 CRUD 统一入口 ==========
-    server.tool('kg_doc', '📄 参考文档 — action: create(创建,建议bindTo关联节点)|read|update|delete|batch_update|copy。⚠️ 不绑定节点的文档会成为孤岛!', {
-        action: z.enum(['create', 'read', 'update', 'delete', 'batch_update', 'copy'])
-            .describe('操作类型'),
-        path: z.string().optional()
-            .describe('文档路径(如"/前端/组件/Modal")。create/read/update/delete 必填'),
-        content: z.string().optional()
-            .describe('Markdown内容 (create/update)'),
-        summary: z.string().optional()
-            .describe('一句话简介 (create/update)'),
-        status: z.string().optional()
-            .describe('文档状态 (create/update, 默认"已完成")'),
-        versions: z.array(z.object({
-            version: z.number(), date: z.string(), changes: z.string()
-        })).optional().describe('版本记录 (update)'),
-        bugfixes: z.array(z.object({
-            date: z.string(), issue: z.string(), solution: z.string()
-        })).optional().describe('修复记录 (update)'),
-        updates: z.array(z.object({
-            nodeId: z.string().describe('文档路径'),
-            summary: z.string().optional(),
-            content: z.string().optional(),
-            status: z.string().optional(),
-            versions: z.array(z.object({
-                version: z.number(), date: z.string(), changes: z.string()
-            })).optional(),
-            bugfixes: z.array(z.object({
-                date: z.string(), issue: z.string(), solution: z.string()
-            })).optional()
-        })).optional().describe('批量更新数组 (batch_update)'),
-        targetProject: z.string().optional()
-            .describe('跨项目读取时的目标项目ID (read)'),
-        sourceProject: z.string().optional()
-            .describe('复制源项目ID (copy)'),
-        sourcePath: z.union([z.string(), z.array(z.string())]).optional()
-            .describe('复制源路径 (copy, 单个或数组)'),
-        targetPath: z.string().optional()
-            .describe('复制目标路径前缀 (copy)'),
-        bindTo: z.string().optional()
-            .describe('绑定到流程图节点ID (create/update, 如"n_frontend")'),
-        bindChart: z.string().optional()
-            .describe('绑定目标流程图ID (create/update, 默认"main")'),
-    }, async (args) => safeTool(async () => {
-        const d = decodeObjectStrings(args);
-        switch (d.action) {
-            // ---- CREATE ----
-            case 'create': {
-                if (!d.path)
-                    return wrap('❌ create 需要 path');
-                if (!d.content)
-                    return wrap('❌ create 需要 content');
-                const doc = await client().createDoc(d.path, {
-                    summary: d.summary || '',
-                    content: d.content,
-                    versions: [{ version: 0.1, date: new Date().toISOString(), changes: '初始创建' }],
-                    bugfixes: [],
-                    status: d.status || '已完成'
-                });
-                // 绑定到流程图节点
-                let bindMsg = '';
-                if (d.bindTo) {
-                    try {
-                        const chartId = d.bindChart || 'main';
-                        const chart = await client().getFlowchart(chartId);
-                        if (chart) {
-                            const node = chart.nodes?.find((n) => n.id === d.bindTo);
-                            if (node) {
-                                if (!node.boundDocs)
-                                    node.boundDocs = [];
-                                if (!node.boundDocs.includes(d.path)) {
-                                    node.boundDocs.push(d.path);
-                                }
-                                // Save back via PUT (use the existing save method)
-                                chart.id = chartId;
-                                await client().saveFlowchart(chartId, chart);
-                                bindMsg = `\n🔗 已绑定到节点: ${d.bindTo} [${chartId}]`;
-                            }
-                            else {
-                                bindMsg = `\n⚠️ 节点 "${d.bindTo}" 不存在于流程图 "${chartId}"`;
-                            }
-                        }
-                    }
-                    catch {
-                        bindMsg = `\n⚠️ 绑定失败(流程图操作异常)`;
-                    }
-                }
-                // 约束: 未绑定流程图节点 → 强制警告
-                if (!d.bindTo) {
-                    bindMsg = `\n\n⚠️ 【未关联知识锚点】文档未绑定到流程图节点!\n💡 建议: 使用 kg_flowchart(bind, nodeId, docs:["${d.path}"]) 绑定\n📌 孤立文档无法被 AI 通过节点关联发现`;
-                }
-                return wrap(`✅ 文档已创建: ${d.path}${bindMsg}`);
-            }
-            // ---- READ ----
-            case 'read': {
-                if (!d.path)
-                    return wrap('❌ read 需要 path');
-                const doc = d.targetProject
-                    ? await client().crossGetDoc(d.targetProject, d.path)
-                    : await client().getDoc(d.path);
-                if (!doc)
-                    return wrap(d.targetProject ? `文档不存在(项目: ${d.targetProject})` : '文档不存在');
-                const lines = formatDocMarkdown(doc, d.path);
-                return wrap(d.targetProject ? crossPrefix(d.targetProject) + lines.join('\n') : lines.join('\n'));
-            }
-            // ---- UPDATE ----
-            case 'update': {
-                if (!d.path)
-                    return wrap('❌ update 需要 path');
-                if (d.path === '/' || d.path === '_root') {
-                    // 根文档更新
-                    const existing = await client().getDoc('/');
-                    if (!existing)
-                        return wrap('更新失败(根文档不存在)');
-                    const updates = {};
-                    if (d.summary !== undefined)
-                        updates.summary = d.summary;
-                    if (d.content !== undefined)
-                        updates.content = d.content;
-                    const upd = await client().updateDoc('/', updates);
-                    return wrap(upd ? '✅ 项目介绍已更新' : '更新失败');
-                }
-                const existing = await client().getDoc(d.path);
-                if (!existing)
-                    return wrap('更新失败(文档不存在)');
-                const updates = {};
-                if (d.summary !== undefined)
-                    updates.summary = d.summary;
-                if (d.content !== undefined)
-                    updates.content = d.content;
-                if (d.status !== undefined)
-                    updates.status = d.status;
-                if (d.versions !== undefined)
-                    updates.versions = d.versions;
-                if (d.bugfixes !== undefined)
-                    updates.bugfixes = d.bugfixes;
-                const doc = await client().updateDoc(d.path, updates);
-                if (!doc)
-                    return wrap('更新失败');
-                return wrap(`✅ 文档已更新: ${d.path}\n状态: ${doc.status || '已完成'}\n摘要: ${doc.summary || ''}`);
-            }
-            // ---- DELETE ----
-            case 'delete': {
-                if (!d.path)
-                    return wrap('❌ delete 需要 path');
-                const paths = Array.isArray(d.path) ? d.path : [d.path];
-                const results = [];
-                for (const p of paths) {
-                    results.push({ path: p, success: await client().deleteDoc(p) });
-                }
-                if (paths.length === 1) {
-                    return wrap(results[0].success ? '删除成功' : '删除失败(文档不存在或是根文档)');
-                }
-                const ok = results.filter(r => r.success).length;
-                const failed = results.filter(r => !r.success).map(r => r.path);
-                let msg = `✅ 批量删除: ${ok}/${paths.length} 成功`;
-                if (failed.length > 0)
-                    msg += `\n❌ 失败: ${failed.join(', ')}`;
-                return wrap(msg);
-            }
-            // ---- BATCH UPDATE ----
-            case 'batch_update': {
-                if (!d.updates || !Array.isArray(d.updates))
-                    return wrap('❌ batch_update 需要 updates 数组');
-                const results = [];
-                for (const item of d.updates) {
-                    if (item.nodeId === '/' || item.nodeId === '_root') {
-                        results.push({ path: item.nodeId, success: false });
-                        continue;
-                    }
-                    const existing = await client().getDoc(item.nodeId);
-                    if (!existing) {
-                        results.push({ path: item.nodeId, success: false });
-                        continue;
-                    }
-                    const upd = {};
-                    if (item.summary !== undefined)
-                        upd.summary = item.summary;
-                    if (item.content !== undefined)
-                        upd.content = item.content;
-                    if (item.status !== undefined)
-                        upd.status = item.status;
-                    if (item.versions !== undefined)
-                        upd.versions = item.versions;
-                    if (item.bugfixes !== undefined)
-                        upd.bugfixes = item.bugfixes;
-                    const doc = await client().updateDoc(item.nodeId, upd);
-                    results.push({ path: item.nodeId, success: !!doc });
-                }
-                const ok = results.filter(r => r.success).length;
-                const failed = results.filter(r => !r.success).map(r => r.path);
-                let msg = `✅ 批量更新: ${ok}/${d.updates.length} 成功`;
-                if (failed.length > 0)
-                    msg += `\n❌ 失败: ${failed.join(', ')}`;
-                return wrap(msg);
-            }
-            // ---- COPY ----
-            case 'copy': {
-                if (!d.sourceProject)
-                    return wrap('❌ copy 需要 sourceProject');
-                if (!d.sourcePath)
-                    return wrap('❌ copy 需要 sourcePath');
-                const paths = Array.isArray(d.sourcePath) ? d.sourcePath : [d.sourcePath];
-                const results = [];
-                for (const srcPath of paths) {
-                    try {
-                        const doc = await client().crossGetDoc(d.sourceProject, srcPath);
-                        if (!doc) {
-                            results.push({ path: srcPath, success: false, error: '源文档不存在' });
-                            continue;
-                        }
-                        const destPath = d.targetPath
-                            ? `${d.targetPath.replace(/\/$/, '')}${srcPath}`
-                            : srcPath;
-                        const existing = await client().getDoc(destPath);
-                        if (existing) {
-                            await client().updateDoc(destPath, { summary: doc.summary, content: doc.content });
-                        }
-                        else {
-                            await client().createDoc(destPath, { summary: doc.summary, content: doc.content, status: doc.status });
-                        }
-                        results.push({ path: destPath, success: true });
-                    }
-                    catch (e) {
-                        results.push({ path: srcPath, success: false, error: String(e) });
-                    }
-                }
-                const ok = results.filter(r => r.success).length;
-                if (paths.length === 1) {
-                    return wrap(results[0].success
-                        ? `✅ 已复制: ${results[0].path}\n来源: [${d.sourceProject}] ${paths[0]}`
-                        : `❌ 复制失败: ${results[0].error}`);
-                }
-                const failed = results.filter(r => !r.success);
-                let msg = `✅ 批量复制: ${ok}/${paths.length} 成功`;
-                if (failed.length > 0)
-                    msg += `\n❌ 失败:\n${failed.map(f => `  - ${f.path}: ${f.error}`).join('\n')}`;
-                return wrap(msg);
-            }
-            default:
-                return wrap(`❌ 未知 action: ${d.action}`);
-        }
-    }));
-    // ========== kg_tree: 知识全景图 ==========
-    server.tool('kg_tree', '🏗️ 项目知识全景图 ★最快了解项目的方式★ 获取完整知识库目录树(含文档数统计)。传 statusFilter 可筛选特定状态文档。建议任何操作前先调用获取全局视图', {
-        statusFilter: z.array(z.string()).optional()
-            .describe('按状态筛选(如["未完成","待修复"])，不传则展示全景目录树'),
-        targetProject: z.string().optional()
-            .describe('跨项目查看，填目标项目ID或名称'),
-    }, async (args) => safeTool(async () => {
-        // 状态筛选模式
-        if (args.statusFilter && args.statusFilter.length > 0) {
-            const docs = args.targetProject
-                ? await client().crossGetDocsByStatus(args.targetProject, args.statusFilter)
-                : await client().getDocsByStatus(args.statusFilter);
-            if (docs.length === 0) {
-                return wrap(`未找到状态为 [${args.statusFilter.join(', ')}] 的文档${args.targetProject ? `(项目: ${args.targetProject})` : ''}`);
-            }
-            const lines = docs.map(d => `- ${d.path} (${d.status || '已完成'}): ${d.summary || '无简介'}`);
-            const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
-            return wrap(`${prefix}找到 ${docs.length} 个文档:\n\n${lines.join('\n')}`);
-        }
-        // 全景目录树模式
-        const tree = args.targetProject
-            ? await client().crossGetTree(args.targetProject)
-            : await client().getTree();
-        if (!tree || tree.length === 0) {
-            return wrap(args.targetProject ? `知识库为空(项目: ${args.targetProject})` : '知识库为空');
-        }
-        const treeText = formatTreeText(tree);
-        const docCount = countTreeDocs(tree);
-        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
-        return wrap(`${prefix}共 ${docCount} 个文档\n\n${treeText}`);
-    }));
-}

package/dist/tools/helpers.d.ts

@@ -1,37 +0,0 @@
-/**
- * MCP 工具辅助函数
- */
-import type { DocData } from '../storage/types.js';
-/**
- * 包装返回结果为 MCP 格式
- */
-export declare function wrap(text: string): {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-};
-/**
- * 格式化文档为 Markdown 输出
- */
-export declare function formatDocMarkdown(doc: DocData, path: string): string[];
-interface TreeNode {
-    path: string;
-    name: string;
-    summary?: string;
-    isDir: boolean;
-    children?: TreeNode[];
-}
-/**
- * 格式化树为文本
- */
-export declare function formatTreeText(tree: TreeNode[]): string;
-/**
- * 统计树中的文档数
- */
-export declare function countTreeDocs(tree: TreeNode[]): number;
-/**
- * 格式化文件大小
- */
-export declare function formatFileSize(bytes: number): string;
-export {};

package/dist/tools/helpers.js

@@ -1,94 +0,0 @@
-/**
- * MCP 工具辅助函数
- */
-// ==================== 通用包装 ====================
-/**
- * 包装返回结果为 MCP 格式
- */
-export function wrap(text) {
-    return { content: [{ type: 'text', text }] };
-}
-// ==================== 文档格式化 ====================
-/**
- * 格式化文档为 Markdown 输出
- */
-export function formatDocMarkdown(doc, path) {
-    const lines = [];
-    const name = path.split('/').pop() || path;
-    // 标题和简介
-    lines.push(`## ${name}\n`);
-    if (doc.summary) {
-        lines.push(`> ${doc.summary}\n`);
-    }
-    // 内容
-    if (doc.content) {
-        lines.push('**内容**');
-        lines.push(doc.content);
-        lines.push('');
-    }
-    // 更新历史
-    if (doc.versions && doc.versions.length > 0) {
-        lines.push('**更新历史**');
-        lines.push('| 版本 | 日期 | 变更 |');
-        lines.push('|:---|:---|:---|');
-        doc.versions.forEach((v) => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
-        lines.push('');
-    }
-    // 修复历史
-    if (doc.bugfixes && doc.bugfixes.length > 0) {
-        lines.push('**修复历史**');
-        lines.push('| 日期 | 问题 | 方案 |');
-        lines.push('|:---|:---|:---|');
-        doc.bugfixes.forEach((b) => lines.push(`| ${b.date} | ${b.issue} | ${b.solution} |`));
-        lines.push('');
-    }
-    return lines;
-}
-/**
- * 格式化树为文本
- */
-export function formatTreeText(tree) {
-    function format(nodes, prefix = '') {
-        const lines = [];
-        nodes.forEach((node, index) => {
-            const isLast = index === nodes.length - 1;
-            const connector = isLast ? '└── ' : '├── ';
-            const childPrefix = isLast ? '    ' : '│   ';
-            const icon = node.isDir ? '📁' : '📄';
-            const summary = node.summary ? ` # ${node.summary}` : '';
-            lines.push(`${prefix}${connector}${icon} ${node.name}${summary}`);
-            if (node.children && node.children.length > 0) {
-                lines.push(...format(node.children, prefix + childPrefix));
-            }
-        });
-        return lines;
-    }
-    return format(tree).join('\n');
-}
-/**
- * 统计树中的文档数
- */
-export function countTreeDocs(tree) {
-    let count = 0;
-    function traverse(nodes) {
-        for (const node of nodes) {
-            if (!node.isDir)
-                count++;
-            if (node.children)
-                traverse(node.children);
-        }
-    }
-    traverse(tree);
-    return count;
-}
-// ==================== 文件大小格式化 ====================
-/**
- * 格式化文件大小
- */
-export function formatFileSize(bytes) {
-    if (bytes < 1024)
-        return `${bytes} B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-}

package/dist/vector/index.d.ts

@@ -1,56 +0,0 @@
-/**
- * 向量检索服务 - 基于 transformers.js 的语义搜索
- * @version 0.2
- */
-interface VectorConfig {
-    model: string;
-    quantized: boolean;
-}
-/**
- * 获取向量配置 (从 ~/.ppdocs/config/vector.json 读取)
- */
-export declare function getVectorConfig(): VectorConfig;
-interface VectorSearchResult {
-    id: string;
-    title: string;
-    similarity: number;
-}
-/**
- * 获取索引文件路径
- */
-export declare function getIndexPath(projectId: string): string;
-/**
- * 添加或更新节点向量
- */
-export declare function upsertNode(projectId: string, nodeId: string, title: string, description: string, categories?: string[]): Promise<void>;
-/**
- * 删除节点向量
- */
-export declare function removeNode(projectId: string, nodeId: string): Promise<void>;
-/**
- * 向量语义搜索
- */
-export declare function semanticSearch(projectId: string, query: string, limit?: number): Promise<VectorSearchResult[]>;
-/**
- * 批量构建索引 (用于初始化或重建)
- */
-export declare function buildIndex(projectId: string, nodes: Array<{
-    id: string;
-    title: string;
-    description: string;
-    categories?: string[];
-}>): Promise<number>;
-/**
- * 检查索引状态
- */
-export declare function getIndexStats(projectId: string): Promise<{
-    count: number;
-    model: string;
-    dimension: number;
-    loaded: boolean;
-}>;
-/**
- * 预加载模型 (可选, 用于启动时预热)
- */
-export declare function preloadModel(): Promise<void>;
-export {};