@ppdocs/mcp 2.1.0 → 2.3.0

package/dist/cli.js

@@ -4,6 +4,11 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+/** 生成随机用户名 (8位字母数字) */
+function generateUser() {
+    const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
+    return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
+}
 function parseArgs(args) {
     const opts = { port: 20001, api: 'localhost' };
     for (let i = 0; i < args.length; i++) {
@@ -14,6 +19,9 @@ function parseArgs(args) {
         else if (arg === '-k' || arg === '--key') {
             opts.key = args[++i];
         }
+        else if (arg === '-u' || arg === '--user') {
+            opts.user = args[++i];
+        }
         else if (arg === '--port') {
             opts.port = parseInt(args[++i], 10);
         }
@@ -23,6 +31,9 @@ function parseArgs(args) {
     }
     if (!opts.project || !opts.key)
         return null;
+    // 如果没设置 user，自动生成
+    if (!opts.user)
+        opts.user = generateUser();
     return opts;
 }
 function showHelp() {
@@ -38,11 +49,13 @@ Usage:
 Options:
   -p, --project  Project ID (required)
   -k, --key      API key (required)
+  -u, --user     User name for logs (optional, auto-generated if not set)
   --port         API port (default: 20001)
   --api          API host (default: localhost)
 
 Example:
   npx @ppdocs/mcp init -p myproject -k abc123xyz
+  npx @ppdocs/mcp init -p myproject -k abc123xyz -u alice
 `);
 }
 export function runCli(args) {
@@ -70,6 +83,7 @@ function initProject(opts) {
         api: `http://${opts.api}:${opts.port}`,
         projectId: opts.project,
         key: opts.key,
+        user: opts.user,
     };
     const ppdocsPath = path.join(cwd, '.ppdocs');
     fs.writeFileSync(ppdocsPath, JSON.stringify(ppdocsConfig, null, 2));
@@ -96,6 +110,7 @@ function initProject(opts) {
     console.log(`✅ Created ${mcpPath}`);
     console.log(`
 🎉 Done! ppdocs MCP configured for project: ${opts.project}
+   User: ${opts.user}
 
 Restart Claude Code to use ppdocs knowledge graph.
 `);

package/dist/config.d.ts

@@ -5,6 +5,7 @@
 export interface PpdocsConfig {
     apiUrl: string;
     projectId: string;
+    user: string;
 }
 /**
  * 加载配置 (优先级: 环境变量 > .ppdocs 文件)

package/dist/config.js

@@ -4,6 +4,11 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+/** 生成随机用户名 (8位字母数字) */
+function generateUser() {
+    const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
+    return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
+}
 /**
  * 从 .ppdocs 文件读取配置
  */
@@ -22,6 +27,7 @@ function readPpdocsFile() {
         return {
             apiUrl: `${config.api}/api/${config.projectId}/${config.key}`,
             projectId: config.projectId,
+            user: config.user || generateUser(),
         };
     }
     catch {
@@ -38,7 +44,8 @@ function readEnvConfig() {
     // URL 格式: http://localhost:20001/api/{projectId}/{password}
     const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
     const projectId = match?.[1] || 'unknown';
-    return { apiUrl, projectId };
+    const user = process.env.PPDOCS_USER || generateUser();
+    return { apiUrl, projectId, user };
 }
 /**
  * 加载配置 (优先级: 环境变量 > .ppdocs 文件)

package/dist/index.js

@@ -21,11 +21,11 @@ if (args.length > 0 && runCli(args)) {
 async function main() {
     const config = loadConfig();
     initClient(config.apiUrl);
-    const server = new McpServer({ name: `ppdocs [${config.projectId}]`, version: '2.1.0' }, { capabilities: { tools: {} } });
-    registerTools(server, config.projectId);
+    const server = new McpServer({ name: `ppdocs [${config.projectId}]`, version: '2.3.0' }, { capabilities: { tools: {} } });
+    registerTools(server, config.projectId, config.user);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`ppdocs MCP v2.1 | project: ${config.projectId}`);
+    console.error(`ppdocs MCP v2.3 | project: ${config.projectId} | user: ${config.user}`);
 }
 main().catch((err) => {
     console.error('Fatal error:', err);

package/dist/storage/httpClient.d.ts

@@ -4,7 +4,7 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
-import type { NodeData, SearchResult, PathResult, BugfixRecord } from './types.js';
+import type { NodeData, SearchResult, PathResult, BugfixRecord, Task, TaskSummary, TaskLogType, TaskExperience } from './types.js';
 export declare class PpdocsApiClient {
     private baseUrl;
     constructor(apiUrl: string);
@@ -35,6 +35,16 @@ export declare class PpdocsApiClient {
         solution: string;
         impact?: string;
     }): Promise<BugfixRecord | null>;
+    listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
+    getTask(taskId: string): Promise<Task | null>;
+    createTask(task: {
+        title: string;
+        description: string;
+        goals: string[];
+        related_nodes?: string[];
+    }, creator: string): Promise<Task>;
+    addTaskLog(taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
+    completeTask(taskId: string, experience: TaskExperience): Promise<Task | null>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function listNodes(_projectId: string): Promise<NodeData[]>;
@@ -63,3 +73,20 @@ export declare function addBugfix(_projectId: string, nodeId: string, bugfix: {
     solution: string;
     impact?: string;
 }): Promise<BugfixRecord | null>;
+export declare function listTasks(_projectId: string, status?: 'active' | 'archived'): Promise<TaskSummary[]>;
+export declare function getTask(_projectId: string, taskId: string): Promise<Task | null>;
+export declare function createTask(_projectId: string, task: {
+    title: string;
+    description: string;
+    goals: string[];
+    related_nodes?: string[];
+}, 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 interface LogEntry {
+    user: string;
+    action: string;
+    target: string;
+    node_id?: string;
+}
+export declare function appendLog(_projectId: string, entry: LogEntry): Promise<void>;

package/dist/storage/httpClient.js

@@ -159,6 +159,57 @@ export class PpdocsApiClient {
         });
         return updated ? newBugfix : null;
     }
+    // ============ 任务管理 ============
+    async listTasks(status) {
+        const query = status ? `?status=${status}` : '';
+        return this.request(`/tasks${query}`);
+    }
+    async getTask(taskId) {
+        try {
+            return await this.request(`/tasks/${taskId}`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async createTask(task, creator) {
+        const now = new Date().toISOString();
+        const payload = {
+            title: task.title,
+            creator,
+            detail: {
+                description: task.description,
+                goals: task.goals,
+                related_nodes: task.related_nodes || []
+            }
+        };
+        return this.request('/tasks', {
+            method: 'POST',
+            body: JSON.stringify(payload)
+        });
+    }
+    async addTaskLog(taskId, logType, content) {
+        try {
+            return await this.request(`/tasks/${taskId}/logs`, {
+                method: 'POST',
+                body: JSON.stringify({ log_type: logType, content })
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    async completeTask(taskId, experience) {
+        try {
+            return await this.request(`/tasks/${taskId}/complete`, {
+                method: 'POST',
+                body: JSON.stringify(experience)
+            });
+        }
+        catch {
+            return null;
+        }
+    }
 }
 // ============ 模块级 API (兼容现有 tools/index.ts) ============
 let client = null;
@@ -205,3 +256,31 @@ export async function getRelations(_projectId, nodeId) {
 export async function addBugfix(_projectId, nodeId, bugfix) {
     return getClient().addBugfix(nodeId, bugfix);
 }
+// ============ 任务管理 ============
+export async function listTasks(_projectId, status) {
+    return getClient().listTasks(status);
+}
+export async function getTask(_projectId, taskId) {
+    return getClient().getTask(taskId);
+}
+export async function createTask(_projectId, task, creator) {
+    return getClient().createTask(task, creator);
+}
+export async function addTaskLog(_projectId, taskId, logType, content) {
+    return getClient().addTaskLog(taskId, logType, content);
+}
+export async function completeTask(_projectId, taskId, experience) {
+    return getClient().completeTask(taskId, experience);
+}
+export async function appendLog(_projectId, entry) {
+    try {
+        await getClient()['request']('/logs', {
+            method: 'POST',
+            body: JSON.stringify(entry)
+        });
+        console.error(`[LOG] ${entry.action}: ${entry.target}`);
+    }
+    catch (err) {
+        console.error(`[LOG ERROR] Failed to append log:`, err);
+    }
+}

package/dist/storage/types.d.ts

@@ -71,3 +71,46 @@ export interface PathResult {
     path: NodeData[];
     edges: Edge[];
 }
+export type TaskLogType = 'progress' | 'issue' | 'solution' | 'reference';
+export interface TaskLog {
+    time: string;
+    log_type: TaskLogType;
+    content: string;
+}
+export interface TaskReference {
+    title: string;
+    url?: string;
+}
+export interface TaskExperience {
+    summary: string;
+    difficulties: string[];
+    solutions: string[];
+    references: TaskReference[];
+}
+export interface TaskDetail {
+    description: string;
+    goals: string[];
+    related_nodes: string[];
+}
+export interface Task {
+    id: string;
+    title: string;
+    status: 'active' | 'archived';
+    creator: string;
+    project_id: string;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+    detail: TaskDetail;
+    logs: TaskLog[];
+    experience?: TaskExperience;
+}
+export interface TaskSummary {
+    id: string;
+    title: string;
+    status: string;
+    creator: string;
+    created_at: string;
+    updated_at: string;
+    last_log?: string;
+}

package/dist/tools/index.d.ts

@@ -1,2 +1,2 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerTools(server: McpServer, projectId: string): void;
+export declare function registerTools(server: McpServer, projectId: string, user: string): void;

package/dist/tools/index.js

@@ -1,69 +1,64 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
-export function registerTools(server, projectId) {
+export function registerTools(server, projectId, user) {
+    // 日志辅助函数
+    const log = (action, target, nodeId) => {
+        storage.appendLog(projectId, { user, action, target, node_id: nodeId });
+    };
     // 1. 创建节点
-    server.tool('kg_create_node', '创建新节点', {
+    server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍', {
         title: z.string().describe('节点标题'),
         type: z.enum(['logic', 'data', 'intro']).describe('节点类型'),
-        description: z.string().describe(`节点描述(Markdown格式)。要求使用可视化元素：
-
-1. **流程图用Mermaid**:
-\`\`\`mermaid
-graph LR
-  A[输入] --> B{判断} --> C[输出]
-\`\`\`
-
-2. **接口用表格**:
-| 参数 | 类型 | 说明 |
-|-----|------|-----|
-| id | string | 唯一标识 |
-
-3. **禁止纯文字堆砌**`),
-        signature: z.string().optional().describe('方法签名(用于自动关联,默认=title)'),
-        x: z.number().optional().describe('X坐标'),
-        y: z.number().optional().describe('Y坐标'),
-        tags: z.array(z.string()).optional().describe('标签列表'),
+        description: z.string().describe('Markdown描述(用Mermaid流程图+表格,禁止纯文字)'),
+        signature: z.string().optional().describe('唯一签名(用于依赖匹配,默认=title)'),
+        tags: z.array(z.string()).optional().describe('分类标签'),
         dependencies: z.array(z.object({
-            name: z.string().describe('依赖名称(匹配其他节点signature)'),
+            name: z.string().describe('目标节点的signature'),
             description: z.string().describe('依赖说明')
-        })).optional().describe('依赖列表(自动渲染连线)')
+        })).optional().describe('依赖列表(自动生成连线)')
     }, async (args) => {
         const node = await storage.createNode(projectId, {
             title: args.title,
             type: args.type,
             status: 'incomplete',
             description: args.description || '',
-            x: args.x, // undefined 时由 fileStorage 自动布局
-            y: args.y,
+            x: 0, // 服务端自动布局
+            y: 0,
             locked: false,
             signature: args.signature || args.title,
-            categories: args.tags || [], // API 参数名保持 tags，内部存储为 categories
+            categories: args.tags || [],
             dependencies: args.dependencies || []
         });
+        log('create_node', args.title, node.id);
         return { content: [{ type: 'text', text: JSON.stringify(node, null, 2) }] };
     });
     // 2. 删除节点
     server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
+        const node = await storage.getNode(projectId, args.nodeId);
         const success = await storage.deleteNode(projectId, args.nodeId);
+        if (success)
+            log('delete_node', node?.title || args.nodeId, args.nodeId);
         return { content: [{ type: 'text', text: success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)' }] };
     });
     // 3. 更新节点
-    server.tool('kg_update_node', '更新节点(锁定节点不可更新)', {
+    server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)', {
         nodeId: z.string().describe('节点ID'),
         title: z.string().optional().describe('新标题'),
-        signature: z.string().optional().describe('新方法签名(用于自动关联)'),
-        description: z.string().optional().describe('新描述(Markdown格式，用Mermaid流程图+表格，禁止纯文字)'),
-        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional(),
-        tags: z.array(z.string()).optional(),
+        signature: z.string().optional().describe('新签名'),
+        description: z.string().optional().describe('新描述(Markdown)'),
+        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional().describe('状态'),
+        tags: z.array(z.string()).optional().describe('分类标签'),
         dependencies: z.array(z.object({
-            name: z.string().describe('依赖名称'),
-            description: z.string().describe('依赖说明')
+            name: z.string(),
+            description: z.string()
         })).optional().describe('依赖列表')
     }, async (args) => {
         const { nodeId, tags, ...rest } = args;
         // API 参数 tags 转换为内部字段 categories
         const updates = tags !== undefined ? { ...rest, categories: tags } : rest;
         const node = await storage.updateNode(projectId, nodeId, updates);
+        if (node)
+            log('update_node', node.title, nodeId);
         return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)' }] };
     });
     // 4. 锁定/解锁节点
@@ -72,12 +67,14 @@ graph LR
         locked: z.boolean().describe('true=锁定, false=解锁')
     }, async (args) => {
         const node = await storage.lockNode(projectId, args.nodeId, args.locked);
+        if (node)
+            log(args.locked ? 'lock_node' : 'unlock_node', node.title, args.nodeId);
         return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '操作失败' }] };
     });
     // 5. 搜索节点
-    server.tool('kg_search', '多关键词搜索节点(OR逻辑),按权重排序(title:3>tags:2.5>signature:2>desc:1)', {
-        keywords: z.array(z.string()).describe('搜索关键词列表'),
-        limit: z.number().optional().describe('返回数量限制(默认20)')
+    server.tool('kg_search', '关键词搜索节点,按相关度排序返回', {
+        keywords: z.array(z.string()).describe('关键词列表(OR逻辑)'),
+        limit: z.number().optional().describe('返回数量(默认20)')
     }, async (args) => {
         const results = await storage.searchNodes(projectId, args.keywords, args.limit);
         const output = results.map(r => ({
@@ -87,9 +84,9 @@ graph LR
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
     // 6. 路径查找
-    server.tool('kg_find_path', '查找两个节点之间的逻辑流路径,返回中间所有节点和边', {
-        startId: z.string().describe('起始节点ID'),
-        endId: z.string().describe('目标节点ID')
+    server.tool('kg_find_path', '查找两节点间的依赖路径', {
+        startId: z.string().describe('起点节点ID'),
+        endId: z.string().describe('终点节点ID')
     }, async (args) => {
         const result = await storage.findPath(projectId, args.startId, args.endId);
         if (!result)
@@ -102,13 +99,13 @@ graph LR
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
     // 7. 列出所有节点
-    server.tool('kg_list_nodes', '列出当前项目所有节点(返回id,title,type,status,locked)', {}, async () => {
+    server.tool('kg_list_nodes', '列出项目全部节点概览', {}, async () => {
         const nodes = await storage.listNodes(projectId);
         const output = nodes.map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status, locked: n.locked }));
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
     // 8. 查找孤立节点
-    server.tool('kg_find_orphans', '查找孤立节点（没有任何连线的节点）', {}, async () => {
+    server.tool('kg_find_orphans', '查找无连线的孤立节点(用于清理)', {}, async () => {
         const orphans = await storage.findOrphans(projectId);
         if (orphans.length === 0) {
             return { content: [{ type: 'text', text: '没有孤立节点' }] };
@@ -116,7 +113,7 @@ graph LR
         return { content: [{ type: 'text', text: JSON.stringify(orphans, null, 2) }] };
     });
     // 9. 查询节点关系网
-    server.tool('kg_get_relations', '查询节点关系网（所有直接连接的节点及其介绍）', {
+    server.tool('kg_get_relations', '获取节点的上下游关系(谁依赖它/它依赖谁)', {
         nodeId: z.string().describe('节点ID')
     }, async (args) => {
         const relations = await storage.getRelations(projectId, args.nodeId);
@@ -132,18 +129,82 @@ graph LR
         };
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
-    // 10. 添加错误修复记录
-    server.tool('kg_add_bugfix', '添加错误修复记录到节点(自动生成ID和时间戳)', {
-        nodeId: z.string().describe('节点ID'),
-        issue: z.string().describe('问题描述'),
-        solution: z.string().describe('解决方案'),
-        impact: z.string().optional().describe('影响范围')
+    // ===================== 任务管理工具 =====================
+    // 10. 创建任务
+    server.tool('task_create', '创建开发任务,记录目标和关联节点', {
+        title: z.string().describe('任务标题'),
+        description: z.string().describe('任务描述(Markdown)'),
+        goals: z.array(z.string()).optional().describe('目标清单'),
+        related_nodes: z.array(z.string()).optional().describe('关联节点ID')
+    }, async (args) => {
+        const task = await storage.createTask(projectId, {
+            title: args.title,
+            description: args.description,
+            goals: args.goals || [],
+            related_nodes: args.related_nodes
+        }, user);
+        log('create_task', args.title, task.id);
+        return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+    });
+    // 11. 列出任务
+    server.tool('task_list', '列出任务(active=进行中,archived=已归档)', {
+        status: z.enum(['active', 'archived']).optional().describe('状态筛选')
+    }, async (args) => {
+        const tasks = await storage.listTasks(projectId, args.status);
+        const output = tasks.map(t => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            creator: t.creator,
+            created_at: t.created_at,
+            last_log: t.last_log
+        }));
+        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+    });
+    // 12. 获取任务详情
+    server.tool('task_get', '获取任务完整信息(含全部日志)', {
+        taskId: z.string().describe('任务ID')
+    }, async (args) => {
+        const task = await storage.getTask(projectId, args.taskId);
+        if (!task) {
+            return { content: [{ type: 'text', text: '任务不存在' }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+    });
+    // 13. 添加任务日志
+    server.tool('task_add_log', '记录任务进展/问题/方案/参考', {
+        taskId: z.string().describe('任务ID'),
+        log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型'),
+        content: z.string().describe('日志内容(Markdown)')
     }, async (args) => {
-        const bugfix = await storage.addBugfix(projectId, args.nodeId, {
-            issue: args.issue,
-            solution: args.solution,
-            impact: args.impact
+        const task = await storage.addTaskLog(projectId, args.taskId, args.log_type, args.content);
+        if (!task) {
+            return { content: [{ type: 'text', text: '添加失败(任务不存在或已归档)' }] };
+        }
+        log('add_task_log', `${args.log_type}: ${args.content.slice(0, 50)}...`, args.taskId);
+        return { content: [{ type: 'text', text: `日志已添加，任务共有 ${task.logs.length} 条日志` }] };
+    });
+    // 14. 完成任务
+    server.tool('task_complete', '完成任务并归档,填写经验总结', {
+        taskId: z.string().describe('任务ID'),
+        summary: z.string().describe('经验总结(Markdown)'),
+        difficulties: z.array(z.string()).optional().describe('遇到的困难'),
+        solutions: z.array(z.string()).optional().describe('解决方案'),
+        references: z.array(z.object({
+            title: z.string(),
+            url: z.string().optional()
+        })).optional().describe('参考资料')
+    }, async (args) => {
+        const task = await storage.completeTask(projectId, args.taskId, {
+            summary: args.summary,
+            difficulties: args.difficulties || [],
+            solutions: args.solutions || [],
+            references: args.references || []
         });
-        return { content: [{ type: 'text', text: bugfix ? JSON.stringify(bugfix, null, 2) : '添加失败(节点不存在或已锁定)' }] };
+        if (!task) {
+            return { content: [{ type: 'text', text: '完成失败(任务不存在或已归档)' }] };
+        }
+        log('complete_task', task.title, args.taskId);
+        return { content: [{ type: 'text', text: `任务已完成归档: ${task.title}` }] };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
     "url": "https://github.com/ppdocs/ppdocs"
   },
   "license": "MIT",
-  "files": ["dist", "README.md"],
+  "files": ["dist", "templates", "README.md"],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "proper-lockfile": "^4.1.2",

package/templates/AGENT.md

@@ -0,0 +1,30 @@
+# AGENT.md - ppdocs Knowledge Graph Agent
+
+> TODO: 完善此提示词内容
+
+## Role
+
+你是一个项目知识管理助手，负责与 ppdocs 知识图谱交互。
+
+## 核心原则
+
+1. **知识优先**: 修改代码前先查询知识库
+2. **同步更新**: 代码变更后更新对应知识节点
+3. **结构化记录**: 使用 Mermaid 流程图 + 表格
+
+## 可用工具
+
+- `kg_search` - 搜索知识节点
+- `kg_create_node` - 创建新节点
+- `kg_update_node` - 更新节点
+- `kg_get_relations` - 查询节点关系
+
+## 工作流程
+
+```
+查询知识库 → 分析现状 → 执行任务 → 更新知识库
+```
+
+---
+
+*此文件由 `npx @ppdocs/mcp init --agent` 生成*

package/templates/README.md

@@ -0,0 +1,57 @@
+# MCP Templates
+
+此目录包含 `npx @ppdocs/mcp init` 安装时使用的模板文件。
+
+## 文件说明
+
+| 文件 | 用途 | 安装参数 | 目标路径 |
+|-----|------|---------|---------|
+| `AGENT.md` | Codex/通用 Agent 提示词 | `--agent` | `./AGENT.md` |
+| `claude-hooks.json` | Claude Code hooks 配置 | `--hooks` | `.claude/settings.local.json` |
+
+## 安装命令
+
+```bash
+# 基础安装 (只生成 .ppdocs + .mcp.json)
+npx @ppdocs/mcp init -p <projectId> -k <key>
+
+# 安装 + Claude hooks
+npx @ppdocs/mcp init -p <projectId> -k <key> --hooks
+
+# 安装 + AGENT.md
+npx @ppdocs/mcp init -p <projectId> -k <key> --agent
+
+# 完整安装 (全部文件)
+npx @ppdocs/mcp init -p <projectId> -k <key> --all
+```
+
+## 配置合并逻辑
+
+### Claude Hooks (`--hooks`)
+
+安装时会**合并**到 `.claude/settings.local.json`：
+- 如果文件不存在：创建新文件
+- 如果文件存在：保留用户配置，只追加/更新 hooks 部分
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "command": "cat path/to/prompt.md"
+      }
+    ]
+  }
+}
+```
+
+### AGENT.md (`--agent`)
+
+直接复制到项目根目录，如已存在会提示是否覆盖。
+
+## TODO
+
+- [ ] 完善 AGENT.md 提示词内容
+- [ ] 完善 claude-hooks.json 工作流配置
+- [ ] 更新 CLI 支持 --hooks/--agent/--all 参数

package/templates/claude-hooks.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/schema/settings.json",
+  "_comment": "TODO: 完善 hooks 配置",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "command": "echo '## ppdocs Knowledge Graph\\n请结合知识库进行分析和开发'"
+      }
+    ]
+  }
+}