@ppdocs/mcp 2.7.2 → 2.8.0

package/dist/storage/httpClient.d.ts

@@ -4,29 +4,26 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
-import type { NodeData, Task, TaskSummary, TaskLogType, TaskExperience } from './types.js';
-export interface ListNodesFilter {
-    status?: 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated';
-    minEdges?: number;
-    maxEdges?: number;
+import type { DocData, DocNode, DocSearchResult, Task, TaskSummary, TaskLogType, TaskExperience } from './types.js';
+interface TreeNode {
+    path: string;
+    name: string;
+    summary?: string;
+    isDir: boolean;
+    children?: TreeNode[];
 }
 export declare class PpdocsApiClient {
     private baseUrl;
     constructor(apiUrl: string);
     private request;
-    listNodes(filter?: ListNodesFilter): Promise<NodeData[]>;
-    getNode(nodeId: string): Promise<NodeData | null>;
-    createNode(node: Partial<NodeData>): Promise<NodeData>;
-    updateNode(nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
-    updateRoot(updates: {
-        title?: string;
-        description?: string;
-        userStyles?: string[];
-        testRules?: string[];
-        reviewRules?: string[];
-        codeStyle?: string[];
-    }): Promise<NodeData | null>;
-    deleteNode(nodeId: string): Promise<boolean>;
+    listDocs(): Promise<DocNode[]>;
+    getDoc(docPath: string): Promise<DocData | null>;
+    createDoc(docPath: string, doc: Partial<DocData>): Promise<DocData>;
+    updateDoc(docPath: string, updates: Partial<DocData>): Promise<DocData | null>;
+    deleteDoc(docPath: string): Promise<boolean>;
+    searchDocs(keywords: string[], limit?: number): Promise<DocSearchResult[]>;
+    /** 获取目录树结构 */
+    getTree(): Promise<TreeNode[]>;
     getRulesApi(ruleType: string): Promise<string[]>;
     saveRulesApi(ruleType: string, rules: string[]): Promise<boolean>;
     listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
@@ -40,19 +37,13 @@ export declare class PpdocsApiClient {
     completeTask(taskId: string, experience: TaskExperience): Promise<Task | null>;
 }
 export declare function initClient(apiUrl: string): void;
-export declare function listNodes(_projectId: string, filter?: ListNodesFilter): Promise<NodeData[]>;
-export declare function getNode(_projectId: string, nodeId: string): Promise<NodeData | null>;
-export declare function createNode(_projectId: string, node: Partial<NodeData>): Promise<NodeData>;
-export declare function updateNode(_projectId: string, nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
-export declare function updateRoot(_projectId: string, updates: {
-    title?: string;
-    description?: string;
-    userStyles?: string[];
-    testRules?: string[];
-    reviewRules?: string[];
-    codeStyle?: string[];
-}): Promise<NodeData | null>;
-export declare function deleteNode(_projectId: string, nodeId: string): Promise<boolean>;
+export declare function listDocs(_projectId: string): Promise<DocNode[]>;
+export declare function getDoc(_projectId: string, docPath: string): Promise<DocData | null>;
+export declare function createDoc(_projectId: string, docPath: string, doc: Partial<DocData>): Promise<DocData>;
+export declare function updateDoc(_projectId: string, docPath: string, updates: Partial<DocData>): Promise<DocData | null>;
+export declare function deleteDoc(_projectId: string, docPath: string): Promise<boolean>;
+export declare function searchDocs(_projectId: string, keywords: string[], limit?: number): Promise<DocSearchResult[]>;
+export declare function getTree(_projectId: string): Promise<TreeNode[]>;
 export declare function getRules(_projectId: string, ruleType: string): Promise<string[]>;
 export declare function saveRules(_projectId: string, ruleType: string, rules: string[]): Promise<boolean>;
 export declare function listTasks(_projectId: string, status?: 'active' | 'archived'): Promise<TaskSummary[]>;
@@ -64,3 +55,4 @@ export declare function createTask(_projectId: string, task: {
 }, creator: string): Promise<Task>;
 export declare function addTaskLog(_projectId: string, taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
 export declare function completeTask(_projectId: string, taskId: string, experience: TaskExperience): Promise<Task | null>;
+export type { TreeNode };

package/dist/storage/httpClient.js

@@ -4,58 +4,38 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
-// ============ 智能定位算法 ============
-const SMART_NODE_GAP = 180;
-const SMART_SEARCH_RADIUS = 10;
-/**
- * 计算新节点的智能位置 (关联中心 + 螺旋搜索空位)
- */
-function computeSmartPosition(deps, nodes) {
-    // 1. 找关联节点
-    const related = [];
-    if (deps && deps.length > 0) {
-        const depNames = deps.map(d => d.name.toLowerCase());
-        nodes.forEach(n => {
-            if (n.signature && depNames.some(name => n.signature.toLowerCase().startsWith(name))) {
-                related.push(n);
-            }
-        });
-    }
-    // 2. 计算中心点
-    let cx, cy;
-    if (related.length > 0) {
-        cx = related.reduce((s, n) => s + n.x, 0) / related.length;
-        cy = related.reduce((s, n) => s + n.y, 0) / related.length + SMART_NODE_GAP;
-    }
-    else {
-        const root = nodes.find(n => n.isOrigin);
-        cx = root?.x ?? 0;
-        cy = (root?.y ?? 0) + SMART_NODE_GAP;
-    }
-    // 3. 碰撞检测
-    const collides = (x, y) => nodes.some(n => Math.abs(n.x - x) < SMART_NODE_GAP && Math.abs(n.y - y) < SMART_NODE_GAP * 0.6);
-    if (!collides(cx, cy))
-        return { x: Math.round(cx), y: Math.round(cy) };
-    // 4. 螺旋搜索
-    const dirs = [[1, 0], [0, 1], [-1, 0], [0, -1]];
-    let x = cx, y = cy, step = 1, dir = 0, steps = 0, turns = 0;
-    for (let i = 0; i < SMART_SEARCH_RADIUS * SMART_SEARCH_RADIUS * 4; i++) {
-        x += dirs[dir][0] * SMART_NODE_GAP;
-        y += dirs[dir][1] * SMART_NODE_GAP * 0.6;
-        steps++;
-        if (!collides(x, y))
-            return { x: Math.round(x), y: Math.round(y) };
-        if (steps >= step) {
-            steps = 0;
-            dir = (dir + 1) % 4;
-            if (++turns >= 2) {
-                turns = 0;
-                step++;
-            }
+/** 从扁平文档列表构建目录树 */
+function buildTree(docs) {
+    const root = [];
+    const pathMap = new Map();
+    // 按路径深度排序，确保父目录先处理
+    const sorted = [...docs].sort((a, b) => {
+        const depthA = (a.path.match(/\//g) || []).length;
+        const depthB = (b.path.match(/\//g) || []).length;
+        return depthA - depthB;
+    });
+    for (const doc of sorted) {
+        const node = {
+            path: doc.path,
+            name: doc.name,
+            summary: doc.summary,
+            isDir: doc.isDir,
+            children: doc.isDir ? [] : undefined
+        };
+        // 找父路径
+        const lastSlash = doc.path.lastIndexOf('/');
+        const parentPath = lastSlash > 0 ? doc.path.substring(0, lastSlash) : '';
+        if (parentPath && pathMap.has(parentPath)) {
+            pathMap.get(parentPath).children.push(node);
+        }
+        else {
+            root.push(node);
+        }
+        if (doc.isDir) {
+            pathMap.set(doc.path, node);
         }
     }
-    const maxX = Math.max(...nodes.map(n => n.x), 0);
-    return { x: Math.round(maxX + SMART_NODE_GAP), y: Math.round(cy) };
+    return root;
 }
 // API 客户端类
 export class PpdocsApiClient {
@@ -98,91 +78,51 @@ export class PpdocsApiClient {
             clearTimeout(timeout);
         }
     }
-    // ============ 节点操作 ============
-    async listNodes(filter) {
-        const nodes = await this.request('/nodes');
-        if (!filter)
-            return nodes;
-        // 计算每个节点的连接数 (入边+出边)
-        const edgeCounts = new Map();
-        nodes.forEach(n => edgeCounts.set(n.id, 0));
-        nodes.forEach(n => {
-            (n.dependencies || []).forEach(dep => {
-                // 出边: 当前节点依赖别人
-                edgeCounts.set(n.id, (edgeCounts.get(n.id) || 0) + 1);
-                // 入边: 被依赖的节点 (按 signature 匹配)
-                const target = nodes.find(t => t.signature?.toLowerCase() === dep.name.toLowerCase());
-                if (target)
-                    edgeCounts.set(target.id, (edgeCounts.get(target.id) || 0) + 1);
-            });
-        });
-        // 过滤
-        return nodes.filter(n => {
-            if (filter.status && n.status !== filter.status)
-                return false;
-            const edges = edgeCounts.get(n.id) || 0;
-            if (filter.minEdges !== undefined && edges < filter.minEdges)
-                return false;
-            if (filter.maxEdges !== undefined && edges > filter.maxEdges)
-                return false;
-            return true;
-        });
+    // ============ 文档操作 ============
+    async listDocs() {
+        return this.request('/docs');
     }
-    async getNode(nodeId) {
+    async getDoc(docPath) {
         try {
-            return await this.request(`/nodes/${nodeId}`);
+            // 移除开头的斜杠，API 路径会自动处理
+            const cleanPath = docPath.replace(/^\//, '');
+            return await this.request(`/docs/${cleanPath}`);
         }
         catch {
             return null;
         }
     }
-    async createNode(node) {
-        // 智能定位: 计算新节点位置
-        let x = node.x ?? 0;
-        let y = node.y ?? 0;
-        // 如果未指定位置，自动计算
-        if (node.x === undefined && node.y === undefined) {
-            const existingNodes = await this.listNodes();
-            const pos = computeSmartPosition(node.dependencies, existingNodes);
-            x = pos.x;
-            y = pos.y;
-        }
+    async createDoc(docPath, doc) {
+        const cleanPath = docPath.replace(/^\//, '');
         const payload = {
-            id: '', // 服务端自动生成
-            title: node.title || '',
-            type: node.type || 'logic',
-            status: node.status || 'incomplete',
-            x,
-            y,
-            locked: false,
-            signature: node.signature || node.title || '',
-            categories: node.categories || [],
-            description: node.description || '',
-            dependencies: node.dependencies || [],
-            relatedFiles: node.relatedFiles || [],
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-            lastAccessedAt: new Date().toISOString(),
-            versions: [],
-            bugfixes: []
+            summary: doc.summary || '',
+            content: doc.content || '',
+            versions: doc.versions || [{
+                    version: 0.1,
+                    date: new Date().toISOString(),
+                    changes: '初始创建'
+                }],
+            bugfixes: doc.bugfixes || []
         };
-        return this.request('/nodes', {
+        return this.request(`/docs/${cleanPath}`, {
             method: 'POST',
             body: JSON.stringify(payload)
         });
     }
-    async updateNode(nodeId, updates) {
-        // 先获取现有节点，合并更新
-        const existing = await this.getNode(nodeId);
-        if (!existing)
-            return null;
-        const payload = {
-            ...existing,
-            ...updates,
-            updatedAt: new Date().toISOString()
-        };
+    async updateDoc(docPath, updates) {
         try {
-            return await this.request(`/nodes/${nodeId}`, {
+            const cleanPath = docPath.replace(/^\//, '');
+            // 先获取现有文档
+            const existing = await this.getDoc(docPath);
+            if (!existing)
+                return null;
+            const payload = {
+                summary: updates.summary ?? existing.summary,
+                content: updates.content ?? existing.content,
+                versions: updates.versions ?? existing.versions,
+                bugfixes: updates.bugfixes ?? existing.bugfixes
+            };
+            return await this.request(`/docs/${cleanPath}`, {
                 method: 'PUT',
                 body: JSON.stringify(payload)
             });
@@ -191,47 +131,28 @@ export class PpdocsApiClient {
             return null;
         }
     }
-    async updateRoot(updates) {
-        // 专用根节点更新，支持所有规则字段
-        const root = await this.getNode('root');
-        if (!root)
-            return null;
-        if (root.locked)
-            return null; // 锁定时拒绝
-        // 构建更新载荷 (只传入有值的字段)
-        const payload = { updatedAt: new Date().toISOString() };
-        if (updates.title !== undefined)
-            payload.title = updates.title;
-        if (updates.description !== undefined)
-            payload.description = updates.description;
-        if (updates.userStyles !== undefined)
-            payload.userStyles = updates.userStyles;
-        if (updates.testRules !== undefined)
-            payload.testRules = updates.testRules;
-        if (updates.reviewRules !== undefined)
-            payload.reviewRules = updates.reviewRules;
-        if (updates.codeStyle !== undefined)
-            payload.codeStyle = updates.codeStyle;
-        try {
-            return await this.request('/nodes/root', {
-                method: 'PUT',
-                body: JSON.stringify({ ...root, ...payload })
-            });
-        }
-        catch {
-            return null;
-        }
-    }
-    async deleteNode(nodeId) {
+    async deleteDoc(docPath) {
         try {
-            await this.request(`/nodes/${nodeId}`, { method: 'DELETE' });
+            const cleanPath = docPath.replace(/^\//, '');
+            await this.request(`/docs/${cleanPath}`, { method: 'DELETE' });
             return true;
         }
         catch {
             return false;
         }
     }
-    // ============ 规则 API (独立文件存储) ============
+    async searchDocs(keywords, limit = 20) {
+        return this.request('/docs/search', {
+            method: 'POST',
+            body: JSON.stringify({ keywords, limit })
+        });
+    }
+    /** 获取目录树结构 */
+    async getTree() {
+        const docs = await this.listDocs();
+        return buildTree(docs);
+    }
+    // ============ 规则 API ============
     async getRulesApi(ruleType) {
         try {
             return await this.request(`/rules/${ruleType}`);
@@ -303,7 +224,7 @@ export class PpdocsApiClient {
         }
     }
 }
-// ============ 模块级 API (兼容现有 tools/index.ts) ============
+// ============ 模块级 API ============
 let client = null;
 export function initClient(apiUrl) {
     client = new PpdocsApiClient(apiUrl);
@@ -314,26 +235,29 @@ function getClient() {
     }
     return client;
 }
-// 导出与 fileStorage 相同的函数签名
-export async function listNodes(_projectId, filter) {
-    return getClient().listNodes(filter);
+// ============ 文档管理 ============
+export async function listDocs(_projectId) {
+    return getClient().listDocs();
+}
+export async function getDoc(_projectId, docPath) {
+    return getClient().getDoc(docPath);
 }
-export async function getNode(_projectId, nodeId) {
-    return getClient().getNode(nodeId);
+export async function createDoc(_projectId, docPath, doc) {
+    return getClient().createDoc(docPath, doc);
 }
-export async function createNode(_projectId, node) {
-    return getClient().createNode(node);
+export async function updateDoc(_projectId, docPath, updates) {
+    return getClient().updateDoc(docPath, updates);
 }
-export async function updateNode(_projectId, nodeId, updates) {
-    return getClient().updateNode(nodeId, updates);
+export async function deleteDoc(_projectId, docPath) {
+    return getClient().deleteDoc(docPath);
 }
-export async function updateRoot(_projectId, updates) {
-    return getClient().updateRoot(updates);
+export async function searchDocs(_projectId, keywords, limit) {
+    return getClient().searchDocs(keywords, limit);
 }
-export async function deleteNode(_projectId, nodeId) {
-    return getClient().deleteNode(nodeId);
+export async function getTree(_projectId) {
+    return getClient().getTree();
 }
-// ============ 规则管理 (独立文件存储) ============
+// ============ 规则管理 ============
 export async function getRules(_projectId, ruleType) {
     return getClient().getRulesApi(ruleType);
 }

package/dist/storage/types.d.ts

@@ -1,80 +1,48 @@
-export type EdgeType = 'contains' | 'uses' | 'extends' | 'implements';
-export interface Edge {
-    source: string;
-    target: string;
-    type: EdgeType;
-    auto?: boolean;
-}
-export type NodeType = 'logic' | 'data' | 'intro';
-export type NodeStatus = 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated';
-export interface DataRef {
-    type: string;
-    description: string;
-    formatPath?: string;
-}
-export interface Dependency {
-    name: string;
-    description: string;
-    nodePath?: string;
-}
+/** 版本记录 */
 export interface VersionRecord {
     version: number;
     date: string;
     changes: string;
 }
+/** 错误修复记录 */
 export interface BugfixRecord {
-    id: string;
     date: string;
     issue: string;
     solution: string;
-    impact?: string;
 }
-export interface NodeData {
-    id: string;
-    title: string;
-    type: NodeType;
-    status: NodeStatus;
-    x: number;
-    y: number;
-    locked: boolean;
-    isOrigin?: boolean;
-    signature: string;
-    categories: string[];
+/** 文档数据 (4个核心字段) */
+export interface DocData {
+    summary: string;
+    content: string;
+    versions: VersionRecord[];
+    bugfixes: BugfixRecord[];
+}
+/** 文档节点 (含路径信息，用于列表展示) */
+export interface DocNode {
     path: string;
-    description: string;
-    summary?: string;
-    dataInput?: DataRef;
-    dataOutput?: DataRef;
-    dependencies: Dependency[];
-    relatedFiles?: string[];
-    userStyles?: string[];
-    testRules?: string[];
-    reviewRules?: string[];
-    codeStyle?: string[];
-    unitTests?: string[];
-    createdAt?: string;
-    updatedAt?: string;
-    lastAccessedAt?: string;
-    lastSyncAt?: string;
-    versions?: VersionRecord[];
-    bugfixes?: BugfixRecord[];
+    name: string;
+    summary: string;
+    isDir: boolean;
+}
+/** 文档搜索结果 */
+export interface DocSearchResult {
+    path: string;
+    name: string;
+    summary: string;
+    score: number;
 }
 export interface ProjectMeta {
     projectId: string;
     projectName: string;
     updatedAt: string;
-    edges: Edge[];
+    password?: string;
 }
 export interface Project {
     id: string;
     name: string;
+    description?: string;
     updatedAt: string;
 }
-export interface SearchResult {
-    node: NodeData;
-    score: number;
-    matches: string[];
-}
 export type TaskLogType = 'progress' | 'issue' | 'solution' | 'reference';
 export interface TaskLog {
     time: string;

package/dist/storage/types.js

@@ -1,2 +1,2 @@
-// 知识图谱类型定义 - 与 UI 和 Tauri 后端保持同步
+// ppdocs - 文档类型定义 (简化版)
 export {};

package/dist/tools/helpers.d.ts

@@ -1,8 +1,7 @@
 /**
  * MCP 工具辅助函数
- * 提取自 index.ts，避免重复代码
  */
-import type { NodeData } from '../storage/types.js';
+import type { DocData } from '../storage/types.js';
 /**
  * 包装返回结果为 MCP 格式
  */
@@ -13,26 +12,22 @@ export declare function wrap(text: string): {
     }[];
 };
 /**
- * 格式化节点为 Markdown 输出
+ * 格式化文档为 Markdown 输出
  */
-export declare function formatNodeMarkdown(node: NodeData): string[];
+export declare function formatDocMarkdown(doc: DocData, path: string): string[];
 interface TreeNode {
+    path: string;
     name: string;
-    type: 'folder' | 'node';
-    nodeId?: string;
-    status?: string;
+    summary?: string;
+    isDir: boolean;
     children?: TreeNode[];
 }
-/**
- * 构建目录树结构
- */
-export declare function buildDirectoryTree(nodes: NodeData[]): TreeNode;
 /**
  * 格式化树为文本
  */
-export declare function formatTreeText(tree: TreeNode): string;
+export declare function formatTreeText(tree: TreeNode[]): string;
 /**
- * 统计树中的节点数
+ * 统计树中的文档数
  */
-export declare function countTreeNodes(tree: TreeNode): number;
+export declare function countTreeDocs(tree: TreeNode[]): number;
 export {};

package/dist/tools/helpers.js

@@ -1,6 +1,5 @@
 /**
  * MCP 工具辅助函数
- * 提取自 index.ts，避免重复代码
  */
 // ==================== 通用包装 ====================
 /**
@@ -9,149 +8,74 @@
 export function wrap(text) {
     return { content: [{ type: 'text', text }] };
 }
-// ==================== 节点格式化 ====================
+// ==================== 文档格式化 ====================
 /**
- * 格式化节点为 Markdown 输出
+ * 格式化文档为 Markdown 输出
  */
-export function formatNodeMarkdown(node) {
+export function formatDocMarkdown(doc, path) {
     const lines = [];
-    // 基础信息
-    lines.push(`## ${node.title}\n`);
-    if (node.summary) {
-        lines.push(`> ${node.summary}\n`);
+    const name = path.split('/').pop() || path;
+    // 标题和简介
+    lines.push(`## ${name}\n`);
+    if (doc.summary) {
+        lines.push(`> ${doc.summary}\n`);
     }
-    lines.push('**基础信息**');
-    lines.push(`| 字段 | 值 |`);
-    lines.push(`|:---|:---|`);
-    lines.push(`| ID | ${node.id} |`);
-    lines.push(`| 类型 | ${node.type} |`);
-    lines.push(`| 状态 | ${node.status} |`);
-    lines.push(`| 签名 | ${node.signature} |`);
-    if (node.categories && node.categories.length > 0) {
-        lines.push(`| 标签 | ${node.categories.join(', ')} |`);
-    }
-    lines.push('');
-    // 关联文件
-    if (node.relatedFiles && node.relatedFiles.length > 0) {
-        lines.push('**关联文件**');
-        node.relatedFiles.forEach((f) => lines.push(`- ${f}`));
-        lines.push('');
-    }
-    // 依赖关系
-    if (node.dependencies && node.dependencies.length > 0) {
-        lines.push('**依赖关系**');
-        node.dependencies.forEach((d) => lines.push(`- ${d.name}: ${d.description}`));
-        lines.push('');
-    }
-    // 描述内容
-    if (node.description) {
-        lines.push('**描述内容**');
-        lines.push(node.description);
+    // 内容
+    if (doc.content) {
+        lines.push('**内容**');
+        lines.push(doc.content);
         lines.push('');
     }
     // 更新历史
-    if (node.versions && node.versions.length > 0) {
+    if (doc.versions && doc.versions.length > 0) {
         lines.push('**更新历史**');
         lines.push('| 版本 | 日期 | 变更 |');
         lines.push('|:---|:---|:---|');
-        node.versions.forEach((v) => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
+        doc.versions.forEach((v) => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
         lines.push('');
     }
     // 修复历史
-    if (node.bugfixes && node.bugfixes.length > 0) {
+    if (doc.bugfixes && doc.bugfixes.length > 0) {
         lines.push('**修复历史**');
-        lines.push('| ID | 日期 | 问题 | 方案 |');
-        lines.push('|:---|:---|:---|:---|');
-        node.bugfixes.forEach((b) => lines.push(`| ${b.id} | ${b.date} | ${b.issue} | ${b.solution} |`));
+        lines.push('| 日期 | 问题 | 方案 |');
+        lines.push('|:---|:---|:---|');
+        doc.bugfixes.forEach((b) => lines.push(`| ${b.date} | ${b.issue} | ${b.solution} |`));
         lines.push('');
     }
     return lines;
 }
-/**
- * 构建目录树结构
- */
-export function buildDirectoryTree(nodes) {
-    const root = { name: '/', type: 'folder', children: [] };
-    // 过滤掉根节点
-    const docNodes = nodes.filter(n => !n.isOrigin && n.id !== 'root');
-    for (const node of docNodes) {
-        const pathSegments = (node.path || '').split('/').filter(Boolean);
-        let current = root;
-        // 遍历路径段，创建目录结构
-        for (const segment of pathSegments) {
-            if (!current.children)
-                current.children = [];
-            let child = current.children.find(c => c.name === segment && c.type === 'folder');
-            if (!child) {
-                child = { name: segment, type: 'folder', children: [] };
-                current.children.push(child);
-            }
-            current = child;
-        }
-        // 添加节点
-        if (!current.children)
-            current.children = [];
-        current.children.push({
-            name: node.title,
-            type: 'node',
-            nodeId: node.id,
-            status: node.status
-        });
-    }
-    // 递归排序 (目录在前，节点在后)
-    sortTree(root);
-    return root;
-}
-function sortTree(node) {
-    if (!node.children)
-        return;
-    node.children.sort((a, b) => {
-        if (a.type === 'folder' && b.type !== 'folder')
-            return -1;
-        if (a.type !== 'folder' && b.type === 'folder')
-            return 1;
-        return a.name.localeCompare(b.name, 'zh-CN');
-    });
-    for (const child of node.children) {
-        if (child.type === 'folder')
-            sortTree(child);
-    }
-}
 /**
  * 格式化树为文本
  */
 export function formatTreeText(tree) {
-    function format(node, prefix = '', isLast = true) {
+    function format(nodes, prefix = '') {
         const lines = [];
-        const connector = isLast ? '└── ' : '├── ';
-        const childPrefix = isLast ? '    ' : '│   ';
-        if (node.name !== '/') {
-            const icon = node.type === 'folder' ? '📁' : '📄';
-            const status = node.status ? ` [${node.status}]` : '';
-            lines.push(`${prefix}${connector}${icon} ${node.name}${status}`);
-        }
-        if (node.children) {
-            for (let i = 0; i < node.children.length; i++) {
-                const child = node.children[i];
-                const childIsLast = i === node.children.length - 1;
-                const newPrefix = node.name === '/' ? '' : prefix + childPrefix;
-                lines.push(...format(child, newPrefix, childIsLast));
+        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 countTreeNodes(tree) {
+export function countTreeDocs(tree) {
     let count = 0;
-    function traverse(node) {
-        if (node.type === 'node')
-            count++;
-        if (node.children) {
-            node.children.forEach(traverse);
+    function traverse(nodes) {
+        for (const node of nodes) {
+            if (!node.isDir)
+                count++;
+            if (node.children)
+                traverse(node.children);
         }
     }
     traverse(tree);

package/dist/tools/index.js

@@ -1,105 +1,75 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
 import { decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
-// 向量搜索已迁移至 Tauri 后端，通过 HTTP API 调用
-import { wrap, formatNodeMarkdown, buildDirectoryTree, formatTreeText, countTreeNodes } from './helpers.js';
+import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs } from './helpers.js';
 export function registerTools(server, projectId, _user) {
-    // 1. 创建节点
-    server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍。⚠️ tags至少提供3个分类标签', {
-        title: z.string().describe('节点标题'),
-        type: z.enum(['logic', 'data', 'intro']).describe('节点类型(logic/data/intro)'),
-        description: z.string().describe('Markdown描述(用Mermaid流程图+表格,禁止纯文字)'),
-        path: z.string().min(1).describe('目录路径(必填,如"/前端/组件")'),
-        tags: z.array(z.string()).min(3).describe('⚠️ 分类标签(必填,至少3个)'),
-        signature: z.string().optional().describe('唯一签名(用于依赖匹配,默认=title)'),
-        summary: z.string().optional().describe('一句话简介(显示在标题下方)'),
-        dependencies: z.array(z.object({
-            name: z.string().describe('目标节点的signature'),
-            description: z.string().describe('依赖说明')
-        })).optional().describe('依赖列表(自动生成连线)'),
-        relatedFiles: z.array(z.string()).optional().describe('关联的源文件路径数组，如 ["src/auth.ts"]')
+    // ===================== 文档管理 =====================
+    // 1. 创建文档
+    server.tool('kg_create_node', '创建知识文档。使用目录路径分类，文件名作为文档名', {
+        path: z.string().min(1).describe('完整文档路径(如"/前端/组件/Modal")'),
+        summary: z.string().optional().describe('一句话简介'),
+        content: z.string().describe('Markdown内容')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
-        const node = await storage.createNode(projectId, {
-            title: decoded.title,
-            type: decoded.type,
-            status: 'incomplete',
-            description: decoded.description || '',
+        const doc = await storage.createDoc(projectId, decoded.path, {
             summary: decoded.summary || '',
-            // x, y 不传递，由 httpClient 智能计算位置
-            locked: false,
-            signature: decoded.signature || decoded.title,
-            categories: decoded.tags,
-            path: decoded.path,
-            dependencies: decoded.dependencies || [],
-            relatedFiles: decoded.relatedFiles || []
+            content: decoded.content,
+            versions: [{
+                    version: 0.1,
+                    date: new Date().toISOString(),
+                    changes: '初始创建'
+                }],
+            bugfixes: []
         });
-        // 向量索引由 Tauri 后端自动维护，MCP 不再手动更新
-        return wrap(JSON.stringify(node, null, 2));
+        return wrap(`✅ 文档已创建: ${decoded.path}\n\n${JSON.stringify(doc, null, 2)}`);
     });
-    // 2. 删除节点
-    server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
-        const success = await storage.deleteNode(projectId, args.nodeId);
-        // 向量索引由 Tauri 后端自动维护，MCP 不再手动删除
-        return wrap(success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
+    // 2. 删除文档
+    server.tool('kg_delete_node', '删除文档(根文档不可删除)', { nodeId: z.string().describe('文档路径') }, async (args) => {
+        const success = await storage.deleteDoc(projectId, args.nodeId);
+        return wrap(success ? '删除成功' : '删除失败(文档不存在或是根文档)');
     });
-    // 3. 更新节点
-    server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)。⚠️ 更新tags时至少提供3个分类标签', {
-        nodeId: z.string().describe('节点ID'),
-        title: z.string().optional().describe('新标题'),
-        signature: z.string().optional().describe('新签名'),
-        description: z.string().optional().describe('新描述(Markdown)'),
-        summary: z.string().optional().describe('一句话简介(显示在标题下方)'),
-        path: z.string().optional().describe('目录路径(如"/前端/组件")'),
-        x: z.number().optional().describe('X坐标'),
-        y: z.number().optional().describe('Y坐标'),
-        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional().describe('状态'),
-        tags: z.array(z.string()).min(3).optional().describe('⚠️ 分类标签(更新时至少3个)'),
-        dependencies: z.array(z.object({
-            name: z.string(),
-            description: z.string()
-        })).optional().describe('依赖列表'),
-        relatedFiles: z.array(z.string()).optional().describe('关联的源文件路径数组'),
+    // 3. 更新文档
+    server.tool('kg_update_node', '更新文档内容', {
+        nodeId: z.string().describe('文档路径'),
+        summary: z.string().optional().describe('一句话简介'),
+        content: z.string().optional().describe('Markdown内容'),
         versions: z.array(z.object({
             version: z.number(),
             date: z.string(),
             changes: z.string()
-        })).optional().describe('版本记录(0.1起始,AI控制递增)'),
+        })).optional().describe('版本记录'),
         bugfixes: z.array(z.object({
-            id: z.string(),
             date: z.string(),
             issue: z.string(),
-            solution: z.string(),
-            impact: z.string().optional()
-        })).optional().describe('修复记录'),
-        lastSyncAt: z.string().optional().describe('代码↔图谱最后同步时间(ISO时间戳)')
+            solution: z.string()
+        })).optional().describe('修复记录')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
-        const { nodeId, tags, relatedFiles, versions, bugfixes, path, lastSyncAt, ...rest } = decoded;
-        // 根节点必须使用 kg_update_root 更新
-        if (nodeId === 'root') {
-            return wrap('❌ 根节点请使用 kg_update_root 方法更新');
+        const { nodeId, summary, content, versions, bugfixes } = decoded;
+        // 根文档必须使用 kg_update_root 更新
+        if (nodeId === '/' || nodeId === '_root') {
+            return wrap('❌ 根文档请使用 kg_update_root 方法更新');
+        }
+        // 获取现有文档
+        const existing = await storage.getDoc(projectId, nodeId);
+        if (!existing) {
+            return wrap('更新失败(文档不存在)');
         }
-        // API 参数转换
-        let updates = { ...rest };
-        if (tags !== undefined)
-            updates.categories = tags;
-        if (relatedFiles !== undefined)
-            updates.relatedFiles = relatedFiles;
+        // 构建更新内容
+        const updates = {};
+        if (summary !== undefined)
+            updates.summary = summary;
+        if (content !== undefined)
+            updates.content = content;
         if (versions !== undefined)
             updates.versions = versions;
         if (bugfixes !== undefined)
             updates.bugfixes = bugfixes;
-        if (path !== undefined)
-            updates.path = path;
-        if (lastSyncAt !== undefined)
-            updates.lastSyncAt = lastSyncAt;
-        const node = await storage.updateNode(projectId, nodeId, updates);
-        // 向量索引由 Tauri 后端自动维护，MCP 不再手动更新
-        return wrap(node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)');
+        const doc = await storage.updateDoc(projectId, nodeId, updates);
+        return wrap(doc ? JSON.stringify(doc, null, 2) : '更新失败');
     });
-    // 3.5 更新根节点 (项目介绍)
-    server.tool('kg_update_root', '更新项目介绍(根节点描述，锁定时不可更新)', {
+    // 3.5 更新根文档 (项目介绍)
+    server.tool('kg_update_root', '更新项目介绍(根文档)', {
         title: z.string().optional().describe('项目标题'),
         description: z.string().optional().describe('项目介绍(Markdown)')
     }, async (args) => {
@@ -107,13 +77,19 @@ export function registerTools(server, projectId, _user) {
         if (decoded.title === undefined && decoded.description === undefined) {
             return wrap('❌ 请至少提供 title 或 description');
         }
-        const node = await storage.updateRoot(projectId, {
-            title: decoded.title,
-            description: decoded.description
-        });
-        return wrap(node ? '✅ 项目介绍已更新' : '更新失败(根节点已锁定)');
+        const existing = await storage.getDoc(projectId, '/');
+        if (!existing) {
+            return wrap('更新失败(根文档不存在)');
+        }
+        const updates = {};
+        if (decoded.title !== undefined)
+            updates.summary = decoded.title;
+        if (decoded.description !== undefined)
+            updates.content = decoded.description;
+        const doc = await storage.updateDoc(projectId, '/', updates);
+        return wrap(doc ? '✅ 项目介绍已更新' : '更新失败');
     });
-    // 3.6 获取项目规则 (独立方法，按需调用)
+    // 3.6 获取项目规则
     server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)', {
         ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests']).optional()
             .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则。不传则返回全部')
@@ -125,7 +101,7 @@ export function registerTools(server, projectId, _user) {
         }
         return { content: [{ type: 'text', text: rules }] };
     });
-    // 3.7 保存项目规则 (独立存储)
+    // 3.7 保存项目规则
     server.tool('kg_save_rules', '保存单个类型的项目规则(独立文件存储)', {
         ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests'])
             .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则'),
@@ -138,26 +114,28 @@ export function registerTools(server, projectId, _user) {
         }
         return wrap(`✅ ${RULE_TYPE_LABELS[decoded.ruleType]}已保存 (${decoded.rules.length} 条)`);
     });
-    // 5. 读取单个节点详情
-    server.tool('kg_read_node', '读取单个节点的完整内容(描述、关联文件、依赖、历史记录)', {
-        nodeId: z.string().describe('节点ID')
+    // 5. 读取单个文档详情
+    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)', {
+        nodeId: z.string().describe('文档路径')
     }, async (args) => {
-        const node = await storage.getNode(projectId, args.nodeId);
-        if (!node) {
-            return wrap('节点不存在');
+        const doc = await storage.getDoc(projectId, args.nodeId);
+        if (!doc) {
+            return wrap('文档不存在');
         }
-        // 格式化节点基础信息
-        const lines = formatNodeMarkdown(node);
+        // 格式化文档
+        const lines = formatDocMarkdown(doc, args.nodeId);
         return wrap(lines.join('\n'));
     });
     // 10. 获取知识库树状图
     server.tool('kg_get_tree', '获取知识库的目录树结构(按 path 分组)', {}, async () => {
         try {
-            const nodes = await storage.listNodes(projectId);
-            const tree = buildDirectoryTree(nodes);
-            const treeText = formatTreeText(tree);
-            const nodeCount = countTreeNodes(tree);
-            return wrap(`共 ${nodeCount} 个节点\n\n${treeText}`);
+            const tree = await storage.getTree(projectId);
+            if (tree && tree.length > 0) {
+                const treeText = formatTreeText(tree);
+                const docCount = countTreeDocs(tree);
+                return wrap(`共 ${docCount} 个文档\n\n${treeText}`);
+            }
+            return wrap('知识库为空');
         }
         catch (e) {
             return wrap(JSON.stringify({
@@ -182,7 +160,7 @@ export function registerTools(server, projectId, _user) {
         }, _user);
         return wrap(JSON.stringify(task, null, 2));
     });
-    // 8. 读取任务 (按名字搜索，支持当前/历史)
+    // 8. 读取任务
     server.tool('task_get', '读取任务详情(按名字搜索，支持当前任务和历史任务)', {
         title: z.string().describe('任务名称(模糊匹配)'),
         status: z.enum(['active', 'archived', 'all']).optional().describe('状态筛选: active=进行中, archived=已归档, all=全部(默认)')
@@ -221,7 +199,7 @@ export function registerTools(server, projectId, _user) {
         }));
         return wrap(`找到 ${matched.length} 个匹配任务:\n${JSON.stringify(list, null, 2)}\n\n请提供更精确的任务名称`);
     });
-    // 9. 更新任务 (添加日志)
+    // 9. 更新任务
     server.tool('task_update', '更新任务(添加进展日志)', {
         taskId: z.string().describe('任务ID'),
         log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型: progress=进展, issue=问题, solution=方案, reference=参考'),

package/package.json

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