@ppdocs/mcp 3.13.0 → 3.13.1

package/README.md

@@ -64,12 +64,12 @@ npx @ppdocs/mcp init -p <项目ID> -k <密钥>
 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
-{
-  "mcpServers": {
-    "ppdocs": {
-      "command": "npx",
-      "args": ["-y", "@ppdocs/mcp"],
-      "env": {
+{
+  "mcpServers": {
+    "ppdocs-kg": {
+      "command": "npx",
+      "args": ["-y", "@ppdocs/mcp"],
+      "env": {
         "PPDOCS_API_URL": "http://localhost:20001/api/项目ID/密码"
       }
     }
@@ -109,12 +109,11 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ### 核心工具
 
-| 工具 | 说明 |
-|------|------|
-| `kg_init` | 初始化项目连接与上下文 |
-| `kg_status` | 查看项目仪表盘与流程图概况 |
-| `kg_flowchart` | 统一的知识图谱入口，负责查询、更新、关系分析 |
-| `kg_workflow` | Markdown 文档工作流管理 |
+| 工具 | 说明 |
+|------|------|
+| `kg_status` | 查看项目仪表盘与流程图概况 |
+| `kg_flowchart` | 统一的知识图谱入口，负责查询、更新、关系分析 |
+| `kg_workflow` | Markdown 文档工作流管理 |
 | `kg_task` | 任务管理 |
 | `kg_ref` | 外部参考资料（URL拉取、查看、删除） |
 | `code_scan` | 代码扫描 |

package/dist/cli.js

@@ -11,8 +11,26 @@ import { generateUser } from './config.js';
 import { PpdocsApiClient } from './storage/httpClient.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const CANONICAL_MCP_SERVER_NAME = 'ppdocs-kg';
+const LEGACY_MCP_SERVER_PATTERNS = [
+    /^ppdocs$/,
+    /^ppdocs-mcp$/,
+    /^prodocs$/,
+    /^ppdocs-kg-.+$/,
+];
+function isLegacyPpdocsServerName(name) {
+    return name === CANONICAL_MCP_SERVER_NAME || LEGACY_MCP_SERVER_PATTERNS.some(pattern => pattern.test(name));
+}
+function stripLegacyPpdocsServers(mcpServers) {
+    return Object.fromEntries(Object.entries(mcpServers).filter(([name]) => !isLegacyPpdocsServerName(name)));
+}
+function removePpdocsServerAliases(cli) {
+    for (const name of [CANONICAL_MCP_SERVER_NAME, 'ppdocs', 'ppdocs-mcp', 'prodocs']) {
+        execSilent(`${cli} mcp remove ${name}`);
+    }
+}
 function parseArgs(args) {
-    const opts = { port: 20099, api: 'localhost', codex: false };
+    const opts = { port: 20000, api: 'localhost', codex: false };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '-p' || arg === '--project') {
@@ -101,7 +119,7 @@ Options:
   -p, --project  Project ID (required)
   -k, --key      API key (required)
   -u, --user     User name for logs (optional, auto-generated)
-  --port         API port (default: 20099)
+  --port         API port (default: 20000)
   --api          API host (default: localhost)
   --codex        Codex mode: generate AGENTS.md instead of .claude/
   --from <id>    Pull IDE configs from a template project
@@ -255,15 +273,12 @@ function execSilent(cmd) {
     }
     catch { /* ignore */ }
 }
-/** 自动检测 AI CLI 并注册全局 MCP，直接注入项目环境变量实现开箱即用 */
+/** 自动检测 AI CLI 并注册全局 MCP，仅注入项目根目录 hint 以便运行时定位 .ppdocs */
 function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     const detected = [];
     const serverName = 'ppdocs-kg';
-    const envPairs = [
-        `PPDOCS_API_URL=${apiUrl}`,
-        `PPDOCS_USER=${user}`,
-        `PPDOCS_PROJECT_ROOT=${cwd}`,
-    ];
+    // 不再注入 PPDOCS_PROJECT_ROOT — 全局注册时依赖运行时 CWD 自动定位 .ppdocs
+    const envPairs = [];
     /** 用 spawnSync + args 数组注册 MCP，避免 Windows cmd.exe 引号解析问题 */
     function mcpAdd(cli, envFlag) {
         const args = ['mcp', 'add'];
@@ -273,8 +288,14 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
         // macOS/Linux: 必须注入 PATH，否则 Claude Code 启动 MCP 时可能找不到 npx/node
         // (Claude Code 进程的 PATH 通常不含 /opt/homebrew/bin 等 Homebrew/nvm 路径)
         if (process.platform !== 'win32') {
-            const macExtraPaths = '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin';
-            const fullPath = `${process.env.PATH || '/usr/bin:/bin'}:${macExtraPaths}`;
+            const home = process.env.HOME || '';
+            const extraPaths = [
+                '/usr/local/bin', '/opt/homebrew/bin', '/home/linuxbrew/.linuxbrew/bin',
+                `${home}/.local/bin`, // pip/pipx (Linux)
+                `${home}/.nvm/versions/node`, // nvm hint (resolved via process.env.PATH)
+                `${home}/.fnm/aliases/default/bin`, // fnm
+            ].join(':');
+            const fullPath = `${process.env.PATH || '/usr/bin:/bin'}:${extraPaths}`;
             args.push(envFlag, `PATH=${fullPath}`);
         }
         args.push(serverName, '--', 'npx', '-y', '@ppdocs/mcp@latest');
@@ -286,12 +307,12 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     if (commandExists('claude')) {
         detected.push('Claude');
         try {
-            execSilent(`claude mcp remove ${serverName}`);
+            removePpdocsServerAliases('claude');
             mcpAdd('claude', '-e');
         }
         catch {
             try {
-                execSilent(`claude mcp remove ${serverName}`);
+                removePpdocsServerAliases('claude');
                 mcpAdd('claude', '-e');
             }
             catch {
@@ -303,7 +324,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     if (commandExists('codex')) {
         detected.push('Codex');
         try {
-            execSilent(`codex mcp remove ${serverName}`);
+            removePpdocsServerAliases('codex');
             mcpAdd('codex', '--env');
         }
         catch {
@@ -314,7 +335,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     if (commandExists('opencode')) {
         detected.push('OpenCode');
         try {
-            execSilent(`opencode mcp remove ${serverName}`);
+            removePpdocsServerAliases('opencode');
             mcpAdd('opencode', '-e');
         }
         catch {
@@ -346,7 +367,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     console.log(`✅ Registered MCP for: ${detected.join(', ')}`);
     return true;
 }
-/** 在指定路径创建或更新 mcp.json 配置，注入 PPDOCS_* 环境变量实现启动即就绪 */
+/** 在指定路径创建或更新 mcp.json 配置，仅保留 PATH + 可选项目根目录 hint */
 function createMcpConfigAt(mcpPath, apiUrl, options) {
     let mcpConfig = {};
     if (fs.existsSync(mcpPath)) {
@@ -359,25 +380,30 @@ function createMcpConfigAt(mcpPath, apiUrl, options) {
         }
     }
     const isWindows = process.platform === 'win32';
-    const macExtraPaths = '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin';
-    const actualPath = `${process.env.PATH || '/usr/bin:/bin'}:${macExtraPaths}`;
-    // 构建 env: 非 Windows 补 PATH + 注入项目绑定变量
+    const home = process.env.HOME || '';
+    const extraPaths = [
+        '/usr/local/bin', '/opt/homebrew/bin', '/home/linuxbrew/.linuxbrew/bin',
+        `${home}/.local/bin`, // pip/pipx (Linux)
+        `${home}/.nvm/versions/node`, // nvm hint
+        `${home}/.fnm/aliases/default/bin`, // fnm
+    ].join(':');
+    const actualPath = `${process.env.PATH || '/usr/bin:/bin'}:${extraPaths}`;
+    // 构建 env: 非 Windows 补 PATH + 注入项目根目录 hint（如有）
     const env = {};
     if (!isWindows)
         env.PATH = actualPath;
-    if (!options?.noEnv) {
-        env.PPDOCS_API_URL = apiUrl;
-        if (options?.user)
-            env.PPDOCS_USER = options.user;
-        if (options?.projectRoot)
-            env.PPDOCS_PROJECT_ROOT = options.projectRoot;
+    if (!options?.noEnv && options?.projectRoot) {
+        env.PPDOCS_PROJECT_ROOT = options.projectRoot;
     }
     const ppdocsServer = isWindows
         ? { command: 'cmd', args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'], ...(Object.keys(env).length > 0 && { env }) }
         : { command: 'npx', args: ['-y', '@ppdocs/mcp@latest'], env };
+    const existingServers = (mcpConfig.mcpServers && typeof mcpConfig.mcpServers === 'object'
+        ? mcpConfig.mcpServers
+        : {});
     mcpConfig.mcpServers = {
-        ...(mcpConfig.mcpServers || {}),
-        "ppdocs-kg": ppdocsServer,
+        ...stripLegacyPpdocsServers(existingServers),
+        [CANONICAL_MCP_SERVER_NAME]: ppdocsServer,
     };
     // 确保父目录存在
     const parentDir = path.dirname(mcpPath);
@@ -411,7 +437,9 @@ function copyDirRecursive(src, dest) {
 function generateHooksConfig(cwd) {
     // 使用绝对路径，避免 CWD 不一致导致找不到脚本
     const hookPath = path.join(cwd, '.claude', 'hooks', 'hook.py').replace(/\\/g, '/');
-    const command = `python ${hookPath}`;
+    // Linux/macOS 优先使用 python3 (Ubuntu 20.04+ 默认无 python 命令)
+    const pythonCmd = process.platform === 'win32' ? 'python' : 'python3';
+    const command = `${pythonCmd} ${hookPath}`;
     return {
         hooks: {
             UserPromptSubmit: [
@@ -425,29 +453,16 @@ function generateHooksConfig(cwd) {
 /** 生成 MCP 权限配置 (允许全部 ppdocs-kg 工具) */
 function generateMcpPermissions() {
     const mcpMethods = [
-        // 初始化 + 导航
-        'kg_init',
         'kg_status',
-        // 知识管理
-        'kg_projects',
         'kg_workflow',
-        // 工作流
         'kg_task',
-        'kg_files',
-        'kg_discuss',
         'kg_ref',
-        // 流程图
         'kg_flowchart',
-        // 文档查询
-        'kg_doc',
-        // 协作
-        'kg_meeting',
-        // 代码分析
         'code_scan',
         'code_smart_context',
         'code_full_path',
     ];
-    return mcpMethods.map(m => `mcp__ppdocs-kg__${m}`);
+    return mcpMethods.map(m => `mcp__${CANONICAL_MCP_SERVER_NAME}__${m}`);
 }
 /** 安装 Claude Code 模板 */
 function installClaudeTemplates(cwd) {

package/dist/config.d.ts

@@ -1,16 +1,36 @@
 /**
  * ppdocs MCP Config
- * 读取配置: 环境变量 > .ppdocs 文件 > 提示去 Agent WebUI 绑定
+ * 读取配置: 项目根目录 .ppdocs 是唯一正式绑定源
  */
 export interface PpdocsConfig {
     apiUrl: string;
     projectId: string;
     user: string;
     agentId: string;
-    source: 'env' | 'file';
+    source: 'file';
+    configPath: string;
+    projectRoot: string;
+    searchRoot: string;
+    warnings: string[];
 }
 export declare const PPDOCS_CONFIG_FILE = ".ppdocs";
+declare const REQUIRED_BINDING_FIELDS: readonly ["api", "projectId", "key"];
+type RequiredBindingField = typeof REQUIRED_BINDING_FIELDS[number];
+export interface PpdocsBindingDiagnostic {
+    reason: 'not_found' | 'invalid_json' | 'missing_fields';
+    searchRoot: string;
+    hintedProjectRoot?: string;
+    configPath?: string;
+    missingFields?: RequiredBindingField[];
+    warnings: string[];
+}
+export declare class PpdocsBindingError extends Error {
+    diagnostic: PpdocsBindingDiagnostic;
+    constructor(diagnostic: PpdocsBindingDiagnostic);
+}
 /** 生成随机用户名 */
 export declare function generateUser(): string;
 export declare function generateAgentId(): string;
-export declare function loadConfig(): Promise<PpdocsConfig | null>;
+export declare function findPpdocsFile(startDir?: string): string | null;
+export declare function loadConfig(startDir?: string): Promise<PpdocsConfig>;
+export {};

package/dist/config.js

@@ -1,10 +1,19 @@
 /**
  * ppdocs MCP Config
- * 读取配置: 环境变量 > .ppdocs 文件 > 提示去 Agent WebUI 绑定
+ * 读取配置: 项目根目录 .ppdocs 是唯一正式绑定源
  */
 import * as fs from 'fs';
 import * as path from 'path';
 export const PPDOCS_CONFIG_FILE = '.ppdocs';
+const REQUIRED_BINDING_FIELDS = ['api', 'projectId', 'key'];
+export class PpdocsBindingError extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(createBindingErrorMessage(diagnostic));
+        this.name = 'PpdocsBindingError';
+        this.diagnostic = diagnostic;
+    }
+}
 /** 生成随机用户名 */
 export function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
@@ -25,20 +34,44 @@ export function generateAgentId() {
     return _cachedAgentId;
 }
 // ============ 配置读取 ============
-function readEnvConfig() {
-    const apiUrl = process.env.PPDOCS_API_URL;
-    if (!apiUrl)
-        return null;
-    const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
+function buildWarnings() {
+    const warnings = [];
+    if (process.env.PPDOCS_API_URL) {
+        warnings.push('PPDOCS_API_URL is ignored at runtime; .ppdocs is the canonical binding source.');
+    }
+    return warnings;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function normalizeApiBase(api) {
+    return api.replace(/\/+$/, '');
+}
+function createBindingErrorMessage(diagnostic) {
+    switch (diagnostic.reason) {
+        case 'not_found':
+            return `No ${PPDOCS_CONFIG_FILE} binding found from ${diagnostic.searchRoot}`;
+        case 'invalid_json':
+            return `${PPDOCS_CONFIG_FILE} is not valid JSON at ${diagnostic.configPath}`;
+        case 'missing_fields':
+            return `${PPDOCS_CONFIG_FILE} is missing required fields: ${(diagnostic.missingFields || []).join(', ')}`;
+    }
+}
+function resolveSearchRoot(startDir = process.cwd()) {
+    const hintedProjectRoot = process.env.PPDOCS_PROJECT_ROOT?.trim();
+    const candidate = path.resolve(hintedProjectRoot || startDir);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return {
+            searchRoot: path.dirname(candidate),
+            hintedProjectRoot: hintedProjectRoot ? candidate : undefined,
+        };
+    }
     return {
-        apiUrl,
-        projectId: match?.[1] || 'unknown',
-        user: process.env.PPDOCS_USER || generateUser(),
-        agentId: process.env.PPDOCS_AGENT_ID || generateAgentId(),
-        source: 'env',
+        searchRoot: candidate,
+        hintedProjectRoot: hintedProjectRoot ? candidate : undefined,
     };
 }
-function findPpdocsFile(startDir = process.cwd()) {
+export function findPpdocsFile(startDir = process.cwd()) {
     let currentDir = path.resolve(startDir);
     while (true) {
         const configPath = path.join(currentDir, PPDOCS_CONFIG_FILE);
@@ -52,33 +85,58 @@ function findPpdocsFile(startDir = process.cwd()) {
         currentDir = parentDir;
     }
 }
-function readPpdocsFile() {
-    const hintedRoot = process.env.PPDOCS_PROJECT_ROOT;
-    const configPath = hintedRoot
-        ? path.join(path.resolve(hintedRoot), PPDOCS_CONFIG_FILE)
-        : findPpdocsFile();
-    if (!configPath || !fs.existsSync(configPath))
-        return null;
+function parsePpdocsFile(configPath, searchRoot, warnings) {
     try {
-        const c = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-        if (!c.api || !c.projectId || !c.key)
-            return null;
-        return { apiUrl: `${c.api}/api/${c.projectId}/${c.key}`, projectId: c.projectId, user: c.user || generateUser(), agentId: c.agentId || process.env.PPDOCS_AGENT_ID || generateAgentId(), source: 'file' };
+        const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const missingFields = REQUIRED_BINDING_FIELDS.filter((field) => !isNonEmptyString(raw[field]));
+        if (missingFields.length > 0) {
+            throw new PpdocsBindingError({
+                reason: 'missing_fields',
+                searchRoot,
+                configPath,
+                missingFields,
+                warnings,
+            });
+        }
+        const projectRoot = path.dirname(configPath);
+        return {
+            apiUrl: `${normalizeApiBase(raw.api)}/api/${raw.projectId}/${raw.key}`,
+            projectId: raw.projectId,
+            user: isNonEmptyString(raw.user) ? raw.user : generateUser(),
+            agentId: isNonEmptyString(raw.agentId)
+                ? raw.agentId
+                : (process.env.PPDOCS_AGENT_ID || generateAgentId()),
+            source: 'file',
+            configPath,
+            projectRoot,
+            searchRoot,
+            warnings,
+        };
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error instanceof PpdocsBindingError) {
+            throw error;
+        }
+        throw new PpdocsBindingError({
+            reason: 'invalid_json',
+            searchRoot,
+            configPath,
+            warnings,
+        });
     }
 }
 // ============ 入口 ============
-export async function loadConfig() {
-    // 1. 环境变量
-    const envConfig = readEnvConfig();
-    if (envConfig)
-        return envConfig;
-    // 2. .ppdocs 文件 (由 init 命令生成)
-    const fileConfig = readPpdocsFile();
-    if (fileConfig)
-        return fileConfig;
-    // 无配置 → 返回 null，由调用方决定行为 (MCP 模式下等待 kg_init)
-    return null;
+export async function loadConfig(startDir = process.cwd()) {
+    const warnings = buildWarnings();
+    const { searchRoot, hintedProjectRoot } = resolveSearchRoot(startDir);
+    const configPath = findPpdocsFile(searchRoot);
+    if (!configPath) {
+        throw new PpdocsBindingError({
+            reason: 'not_found',
+            searchRoot,
+            hintedProjectRoot,
+            warnings,
+        });
+    }
+    return parsePpdocsFile(configPath, searchRoot, warnings);
 }

package/dist/index.d.ts

@@ -4,6 +4,6 @@
  *
  * 使用方式:
  * 1. CLI 初始化: npx @ppdocs/mcp init -p <projectId> -k <key>
- * 2. MCP 服务: 自动读取 .ppdocs 配置或 PPDOCS_API_URL 环境变量
+ * 2. MCP 服务: 启动时自动读取项目根目录 .ppdocs
  */
 export {};

package/dist/index.js

@@ -4,7 +4,7 @@
  *
  * 使用方式:
  * 1. CLI 初始化: npx @ppdocs/mcp init -p <projectId> -k <key>
- * 2. MCP 服务: 自动读取 .ppdocs 配置或 PPDOCS_API_URL 环境变量
+ * 2. MCP 服务: 启动时自动读取项目根目录 .ppdocs
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -14,7 +14,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { registerTools } from './tools/index.js';
 import { initClient } from './storage/httpClient.js';
 import { runCli } from './cli.js';
-import { loadConfig, generateAgentId } from './config.js';
+import { loadConfig, PpdocsBindingError } from './config.js';
 // 从 package.json 读取版本号
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -64,6 +64,32 @@ async function checkConnectivity(apiUrl) {
         clearTimeout(timer);
     }
 }
+function logBindingSuccess(config) {
+    console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user} | source: ${config.source}`);
+    console.error(`[binding] search root: ${config.searchRoot}`);
+    console.error(`[binding] config file: ${config.configPath}`);
+    console.error(`[binding] project root: ${config.projectRoot}`);
+    for (const warning of config.warnings) {
+        console.error(`[binding] warning: ${warning}`);
+    }
+}
+function logBindingFailure(error) {
+    console.error(`ppdocs MCP v${VERSION} | ❌ startup aborted: ${error.message}`);
+    console.error(`[binding] search root: ${error.diagnostic.searchRoot}`);
+    if (error.diagnostic.hintedProjectRoot) {
+        console.error(`[binding] PPDOCS_PROJECT_ROOT hint: ${error.diagnostic.hintedProjectRoot}`);
+    }
+    if (error.diagnostic.configPath) {
+        console.error(`[binding] config file: ${error.diagnostic.configPath}`);
+    }
+    if (error.diagnostic.missingFields?.length) {
+        console.error(`[binding] missing fields: ${error.diagnostic.missingFields.join(', ')}`);
+    }
+    for (const warning of error.diagnostic.warnings) {
+        console.error(`[binding] warning: ${warning}`);
+    }
+    console.error(`[binding] fix: create a project-root .ppdocs file before starting the MCP server.`);
+}
 // 检查是否为 CLI 命令
 const args = process.argv.slice(2);
 if (args.length > 0) {
@@ -73,24 +99,26 @@ if (args.length > 0) {
 }
 // 运行 MCP 服务
 async function main() {
-    const config = await loadConfig();
-    // 有配置 → 自动初始化 (环境变量 / .ppdocs)
-    if (config) {
-        initClient(config.apiUrl);
-        console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user} | source: ${config.source}`);
-        // 启动时连通性检查 (非阻塞, 3秒超时)
-        checkConnectivity(config.apiUrl).catch(() => { });
+    let config;
+    try {
+        config = await loadConfig();
     }
-    else {
-        console.error(`ppdocs MCP v${VERSION} | ⏳ 等待 kg_init 初始化项目上下文...`);
+    catch (error) {
+        if (error instanceof PpdocsBindingError) {
+            logBindingFailure(error);
+            process.exit(1);
+        }
+        throw error;
     }
-    const projectId = config?.projectId || 'pending';
-    const user = config?.user || 'agent';
-    const agentId = config?.agentId || process.env.PPDOCS_AGENT_ID || generateAgentId();
+    initClient(config.apiUrl);
+    logBindingSuccess(config);
+    // 启动时连通性检查 (非阻塞, 3秒超时)
+    checkConnectivity(config.apiUrl).catch(() => { });
+    const projectId = config.projectId;
+    const user = config.user;
+    const agentId = config.agentId;
     const server = new McpServer({ name: `ppdocs [${projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
-    registerTools(server, projectId, user, agentId, (newProjectId, newApiUrl) => {
-        console.error(`[kg_init] 项目已切换: ${newProjectId}`);
-    });
+    registerTools(server, projectId, user, agentId);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const shutdown = () => { process.exit(0); };

package/dist/retainedCoreMatrix.d.ts

@@ -0,0 +1,19 @@
+export declare const RETAINED_CORE_MATRIX: {
+    readonly retainedTools: {
+        readonly kg_status: true;
+        readonly kg_flowchart: readonly ["list", "get", "search", "get_relations", "find_path", "get_node", "update_node", "delete_node", "batch_add", "bind", "unbind", "orphans", "health", "create_chart", "delete_chart"];
+        readonly kg_workflow: readonly ["list", "get", "save", "delete"];
+        readonly kg_task: readonly ["create", "get", "update", "archive", "delete"];
+        readonly kg_ref: readonly ["list", "get", "fetch", "delete"];
+        readonly code_tools: readonly ["code_scan", "code_smart_context", "code_full_path"];
+    };
+    readonly removed: {
+        readonly tools: readonly ["kg_init", "kg_discuss", "kg_meeting", "kg_files", "kg_projects"];
+        readonly referenceActions: readonly ["save", "read_file", "import_file", "reimport", "refetch-copyin", "copy-in"];
+        readonly clientSurfaces: readonly ["pitfalls"];
+    };
+};
+export type RetainedToolName = keyof typeof RETAINED_CORE_MATRIX.retainedTools;
+export declare function getRetainedActions(tool: Exclude<RetainedToolName, 'kg_status'>): readonly string[];
+export declare function isRemovedTool(tool: string): boolean;
+export declare function isRemovedReferenceAction(action: string): boolean;

package/dist/retainedCoreMatrix.js

@@ -0,0 +1,40 @@
+export const RETAINED_CORE_MATRIX = {
+    retainedTools: {
+        kg_status: true,
+        kg_flowchart: [
+            'list',
+            'get',
+            'search',
+            'get_relations',
+            'find_path',
+            'get_node',
+            'update_node',
+            'delete_node',
+            'batch_add',
+            'bind',
+            'unbind',
+            'orphans',
+            'health',
+            'create_chart',
+            'delete_chart',
+        ],
+        kg_workflow: ['list', 'get', 'save', 'delete'],
+        kg_task: ['create', 'get', 'update', 'archive', 'delete'],
+        kg_ref: ['list', 'get', 'fetch', 'delete'],
+        code_tools: ['code_scan', 'code_smart_context', 'code_full_path'],
+    },
+    removed: {
+        tools: ['kg_init', 'kg_discuss', 'kg_meeting', 'kg_files', 'kg_projects'],
+        referenceActions: ['save', 'read_file', 'import_file', 'reimport', 'refetch-copyin', 'copy-in'],
+        clientSurfaces: ['pitfalls'],
+    },
+};
+export function getRetainedActions(tool) {
+    return RETAINED_CORE_MATRIX.retainedTools[tool];
+}
+export function isRemovedTool(tool) {
+    return RETAINED_CORE_MATRIX.removed.tools.includes(tool);
+}
+export function isRemovedReferenceAction(action) {
+    return RETAINED_CORE_MATRIX.removed.referenceActions.includes(action);
+}

package/dist/storage/httpClient.d.ts

@@ -4,7 +4,7 @@
  *
  * API URL 格式: http://localhost:20099/api/:projectId/:password/...
  */
-import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, WorkflowSummary, WorkflowDoc, WorkflowSelector, Reference, FetchResult, FileImportResult, Pitfall, PitfallSummary } from './types.js';
+import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, WorkflowSummary, WorkflowDoc, WorkflowSelector, Reference, FetchResult } from './types.js';
 export declare class PpdocsApiClient {
     private baseUrl;
     private serverUrl;
@@ -26,32 +26,9 @@ export declare class PpdocsApiClient {
     deleteWorkflow(workflowId: string, scope: 'global' | 'project'): Promise<boolean>;
     listReferences(): Promise<Reference[]>;
     getReference(refId: string): Promise<Reference | null>;
-    saveReference(reference: Reference): Promise<boolean>;
     deleteReference(refId: string): Promise<boolean>;
-    readReferenceFile(path: string): Promise<string>;
-    /** 复制本地文件到参考文件库, 返回相对路径列表 */
-    copyReferenceFiles(paths: string[], targetDir?: string): Promise<string[]>;
     /** 从 URL 拉取文档内容并保存为参考 */
     fetchRefUrl(url: string, refId?: string): Promise<FetchResult>;
-    /** 导入本地文件内容到参考系统 */
-    importLocalFile(refId: string, sourcePath: string): Promise<FileImportResult>;
-    listPitfalls(): Promise<PitfallSummary[]>;
-    getPitfall(pitfallId: string): Promise<Pitfall | null>;
-    createPitfall(input: {
-        title: string;
-        category?: string;
-        symptom?: string;
-        root_cause?: string;
-        solution?: string;
-        prevention?: string;
-        severity?: string;
-        related_nodes?: string[];
-        source_task?: string;
-        tags?: string[];
-    }): Promise<Pitfall>;
-    savePitfall(pitfall: Pitfall): Promise<boolean>;
-    deletePitfall(pitfallId: string): Promise<boolean>;
-    searchPitfalls(query: string, status?: string, category?: string): Promise<PitfallSummary[]>;
     listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
     getTask(taskId: string, mode?: 'smart' | 'full'): Promise<Task | null>;
     createTask(task: {
@@ -74,31 +51,6 @@ export declare class PpdocsApiClient {
     deleteFlowchart(chartId: string): Promise<unknown>;
     getFlowchartOrphans(): Promise<unknown[]>;
     getFlowchartHealth(): Promise<unknown[]>;
-    /** 列出所有可访问的项目 */
-    crossListProjects(): Promise<{
-        id: string;
-        name: string;
-        description: string;
-        updatedAt: string;
-    }[]>;
-    /** 列出项目文件 */
-    listFiles(dir?: string): Promise<FileInfo[]>;
-    /** 读取项目文件 */
-    readFile(filePath: string): Promise<string>;
-    /** 下载项目文件或目录 (zip) → 自动解压到指定目录或 temp 目录 */
-    download(remotePath: string, localPath?: string): Promise<{
-        localPath: string;
-        fileCount: number;
-    }>;
-    /** 跨项目: 列出文件 */
-    crossListFiles(target: string, dir?: string): Promise<FileInfo[]>;
-    /** 跨项目: 读取文件 */
-    crossReadFile(target: string, filePath: string): Promise<string>;
-    /** 跨项目: 下载文件或目录 */
-    crossDownload(target: string, remotePath: string, localPath?: string): Promise<{
-        localPath: string;
-        fileCount: number;
-    }>;
     /** 扫描项目代码, 构建/更新索引 */
     analyzerScan(projectPath: string, force?: boolean): Promise<unknown>;
     /** 智能上下文: 代码+文档+规则+任务全关联 */
@@ -106,26 +58,6 @@ export declare class PpdocsApiClient {
     /** 全关联路径: 两个符号之间的代码+文档路径 */
     analyzerFullPath(projectPath: string, symbolA: string, symbolB: string, maxDepth?: number): Promise<unknown>;
     private publicRequest;
-    /** 列出活跃讨论 (公开路由) */
-    discussionList(): Promise<unknown>;
-    /** 创建讨论 (公开路由) */
-    discussionCreate(title: string, initiator: string, participants: string[], content: string, msgSummary?: string): Promise<{
-        id: string;
-    }>;
-    /** 批量读取讨论 (公开路由, 支持已读追踪) */
-    discussionReadByIds(ids: string[], reader?: string, mode?: string): Promise<unknown>;
-    /** 列出所有讨论 (含历史, 按参与方筛选) */
-    discussionListAll(participant?: string): Promise<unknown>;
-    /** 回复讨论 (公开路由) */
-    discussionReply(id: string, sender: string, content: string, msgSummary?: string, newSummary?: string): Promise<boolean>;
-    /** 完成讨论 (公开路由, 标记为 completed) */
-    discussionComplete(id: string): Promise<boolean>;
-    /** 归档关闭讨论 (需项目认证) */
-    discussionClose(id: string, conclusion: string): Promise<{
-        archived_path?: string;
-    }>;
-    /** 删除讨论 (公开路由) */
-    discussionDelete(id: string): Promise<boolean>;
     /** 列出公共文件 */
     publicFilesList(dir?: string): Promise<FileInfo[]>;
     /** 读取公共文件 (文本) */
@@ -141,12 +73,11 @@ export declare class PpdocsApiClient {
         localPath: string;
         fileCount: number;
     }>;
-    meetingJoin(agentId: string, agentType: string): Promise<unknown>;
-    meetingLeave(agentId: string): Promise<unknown>;
-    meetingPost(agentId: string, content: string, msgType?: string): Promise<unknown>;
-    meetingClaim(agentId: string, filePath: string): Promise<unknown>;
-    meetingRelease(agentId: string, filePath: string): Promise<unknown>;
-    meetingStatus(): Promise<unknown>;
+    crossListFiles(targetProjectId: string): Promise<FileInfo[]>;
+    crossDownload(targetProjectId: string, remotePath: string, localPath?: string): Promise<{
+        localPath: string;
+        fileCount: number;
+    }>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function getClient(): PpdocsApiClient;

package/dist/storage/httpClient.js

@@ -146,28 +146,11 @@ export class PpdocsApiClient {
             return null;
         }
     }
-    async saveReference(reference) {
-        await this.request(`/refs/${encodeURIComponent(reference.id)}`, {
-            method: 'PUT',
-            body: JSON.stringify(reference),
-        });
-        return true;
-    }
     async deleteReference(refId) {
         return this.request(`/refs/${encodeURIComponent(refId)}`, {
             method: 'DELETE',
         });
     }
-    async readReferenceFile(path) {
-        return this.request(`/refs/files/${cleanPath(path)}`);
-    }
-    /** 复制本地文件到参考文件库, 返回相对路径列表 */
-    async copyReferenceFiles(paths, targetDir = '.') {
-        return this.request('/refs/copy-in', {
-            method: 'POST',
-            body: JSON.stringify({ paths, target_dir: targetDir }),
-        });
-    }
     /** 从 URL 拉取文档内容并保存为参考 */
     async fetchRefUrl(url, refId) {
         return this.request('/refs/fetch-url', {
@@ -175,49 +158,6 @@ export class PpdocsApiClient {
             body: JSON.stringify({ url, ref_id: refId }),
         });
     }
-    /** 导入本地文件内容到参考系统 */
-    async importLocalFile(refId, sourcePath) {
-        return this.request('/refs/import-file', {
-            method: 'POST',
-            body: JSON.stringify({ ref_id: refId, source_path: sourcePath }),
-        });
-    }
-    // ============ 踩坑经验 API ============
-    async listPitfalls() {
-        return this.request('/pitfalls');
-    }
-    async getPitfall(pitfallId) {
-        try {
-            return await this.request(`/pitfalls/${encodeURIComponent(pitfallId)}`);
-        }
-        catch {
-            return null;
-        }
-    }
-    async createPitfall(input) {
-        return this.request('/pitfalls', {
-            method: 'POST',
-            body: JSON.stringify(input),
-        });
-    }
-    async savePitfall(pitfall) {
-        await this.request(`/pitfalls/${encodeURIComponent(pitfall.id)}`, {
-            method: 'PUT',
-            body: JSON.stringify(pitfall),
-        });
-        return true;
-    }
-    async deletePitfall(pitfallId) {
-        return this.request(`/pitfalls/${encodeURIComponent(pitfallId)}`, {
-            method: 'DELETE',
-        });
-    }
-    async searchPitfalls(query, status, category) {
-        return this.request('/pitfalls/search', {
-            method: 'POST',
-            body: JSON.stringify({ query, status, category }),
-        });
-    }
     // ============ 任务管理 ============
     async listTasks(status) {
         const query = status ? `?status=${status}` : '';
@@ -330,39 +270,6 @@ export class PpdocsApiClient {
     async getFlowchartHealth() {
         return this.request('/flowcharts/health');
     }
-    // ============ 跨项目只读访问 ============
-    /** 列出所有可访问的项目 */
-    async crossListProjects() {
-        return this.request('/cross/projects');
-    }
-    // ============ 项目文件访问 ============
-    /** 列出项目文件 */
-    async listFiles(dir) {
-        const query = dir ? `?dir=${encodeURIComponent(dir)}` : '';
-        return this.request(`/files${query}`);
-    }
-    /** 读取项目文件 */
-    async readFile(filePath) {
-        return this.request(`/files/${cleanPath(filePath)}`);
-    }
-    /** 下载项目文件或目录 (zip) → 自动解压到指定目录或 temp 目录 */
-    async download(remotePath, localPath) {
-        return fetchAndExtractZip(`${this.baseUrl}/files-download/${cleanPath(remotePath)}`, localPath);
-    }
-    // ============ 跨项目文件访问 (只读) ============
-    /** 跨项目: 列出文件 */
-    async crossListFiles(target, dir) {
-        const query = dir ? `?dir=${encodeURIComponent(dir)}` : '';
-        return this.request(`/cross/${encodeURIComponent(target)}/files${query}`);
-    }
-    /** 跨项目: 读取文件 */
-    async crossReadFile(target, filePath) {
-        return this.request(`/cross/${encodeURIComponent(target)}/files/${cleanPath(filePath)}`);
-    }
-    /** 跨项目: 下载文件或目录 */
-    async crossDownload(target, remotePath, localPath) {
-        return fetchAndExtractZip(`${this.baseUrl}/cross/${encodeURIComponent(target)}/files-download/${cleanPath(remotePath)}`, localPath);
-    }
     // ============ 代码分析引擎 ============
     /** 扫描项目代码, 构建/更新索引 */
     async analyzerScan(projectPath, force = false) {
@@ -400,58 +307,6 @@ export class PpdocsApiClient {
             throw new Error(json.error || 'Unknown error');
         return json.data;
     }
-    // ============ 讨论系统 ============
-    /** 列出活跃讨论 (公开路由) */
-    async discussionList() {
-        return this.publicRequest('/api/discussions');
-    }
-    /** 创建讨论 (公开路由) */
-    async discussionCreate(title, initiator, participants, content, msgSummary) {
-        return this.publicRequest('/api/discussions', {
-            method: 'POST',
-            body: JSON.stringify({ title, initiator, participants, content, msg_summary: msgSummary }),
-        });
-    }
-    /** 批量读取讨论 (公开路由, 支持已读追踪) */
-    async discussionReadByIds(ids, reader, mode) {
-        return this.publicRequest('/api/discussions/read', {
-            method: 'POST',
-            body: JSON.stringify({ ids, reader, mode }),
-        });
-    }
-    /** 列出所有讨论 (含历史, 按参与方筛选) */
-    async discussionListAll(participant) {
-        return this.publicRequest('/api/discussions/all', {
-            method: 'POST',
-            body: JSON.stringify({ participant }),
-        });
-    }
-    /** 回复讨论 (公开路由) */
-    async discussionReply(id, sender, content, msgSummary, newSummary) {
-        return this.publicRequest(`/api/discussions/${encodeURIComponent(id)}/reply`, {
-            method: 'POST',
-            body: JSON.stringify({ sender, content, msg_summary: msgSummary, new_summary: newSummary }),
-        });
-    }
-    /** 完成讨论 (公开路由, 标记为 completed) */
-    async discussionComplete(id) {
-        return this.publicRequest(`/api/discussions/${encodeURIComponent(id)}/complete`, {
-            method: 'POST',
-        });
-    }
-    /** 归档关闭讨论 (需项目认证) */
-    async discussionClose(id, conclusion) {
-        return this.request(`/discussions/${encodeURIComponent(id)}/close`, {
-            method: 'POST',
-            body: JSON.stringify({ conclusion }),
-        });
-    }
-    /** 删除讨论 (公开路由) */
-    async discussionDelete(id) {
-        return this.publicRequest(`/api/discussions/${encodeURIComponent(id)}`, {
-            method: 'DELETE',
-        });
-    }
     // ============ 公共文件池 ============
     /** 列出公共文件 */
     async publicFilesList(dir) {
@@ -486,39 +341,12 @@ export class PpdocsApiClient {
     async publicFilesDownload(remotePath, localPath) {
         return fetchAndExtractZip(`${this.serverUrl}/api/public-files/download/${cleanPath(remotePath)}`, localPath);
     }
-    // ============ 多AI协作会议 ============
-    async meetingJoin(agentId, agentType) {
-        return this.request('/meeting/join', {
-            method: 'POST',
-            body: JSON.stringify({ agent_id: agentId, agent_type: agentType }),
-        });
-    }
-    async meetingLeave(agentId) {
-        return this.request('/meeting/leave', {
-            method: 'POST',
-            body: JSON.stringify({ agent_id: agentId }),
-        });
-    }
-    async meetingPost(agentId, content, msgType = 'status') {
-        return this.request('/meeting/post', {
-            method: 'POST',
-            body: JSON.stringify({ agent_id: agentId, content, msg_type: msgType }),
-        });
-    }
-    async meetingClaim(agentId, filePath) {
-        return this.request('/meeting/claim', {
-            method: 'POST',
-            body: JSON.stringify({ agent_id: agentId, file_path: filePath }),
-        });
-    }
-    async meetingRelease(agentId, filePath) {
-        return this.request('/meeting/release', {
-            method: 'POST',
-            body: JSON.stringify({ agent_id: agentId, file_path: filePath }),
-        });
+    // ============ 跨项目文件 (CLI 模板拉取保留能力) ============
+    async crossListFiles(targetProjectId) {
+        return this.request(`/cross/${encodeURIComponent(targetProjectId)}/files`);
     }
-    async meetingStatus() {
-        return this.request('/meeting/status');
+    async crossDownload(targetProjectId, remotePath, localPath) {
+        return fetchAndExtractZip(`${this.baseUrl}/cross/${encodeURIComponent(targetProjectId)}/files-download/${cleanPath(remotePath)}`, localPath);
     }
 }
 // ============ 模块级 API ============

package/dist/storage/types.d.ts

@@ -73,14 +73,6 @@ export interface FileImportRecord {
     contentPreview: string;
     fileType: string;
 }
-export interface FileImportResult {
-    refId: string;
-    sourcePath: string;
-    storedFile: string;
-    contentLength: number;
-    contentPreview: string;
-    importCount: number;
-}
 export interface FileInfo {
     name: string;
     path: string;
@@ -130,30 +122,3 @@ export interface TaskSummary {
     updated_at: string;
     last_log?: string;
 }
-export interface Pitfall {
-    id: string;
-    title: string;
-    category: string;
-    symptom: string;
-    root_cause: string;
-    solution: string;
-    prevention: string;
-    related_nodes: string[];
-    source_task?: string;
-    severity: string;
-    status: string;
-    tags: string[];
-    created_at: string;
-    updated_at: string;
-    resolved_at?: string;
-}
-export interface PitfallSummary {
-    id: string;
-    title: string;
-    category: string;
-    severity: string;
-    status: string;
-    tags: string[];
-    created_at: string;
-    updated_at: string;
-}

package/dist/tools/index.d.ts

@@ -1,8 +1,7 @@
 /**
  * MCP 工具注册入口
- * 7 个工具, 6 个子模块
+ * 保留工具注册入口
  *
- * kg_init       — 项目初始化
  * kg_status     — 仪表盘
  * kg_flowchart  — 知识图谱核心
  * kg_workflow   — AI 工作流
@@ -11,4 +10,4 @@
  * code_scan/code_smart_context/code_full_path — 代码分析 (可选)
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerTools(server: McpServer, projectId: string, user: string, agentId: string, onProjectChange?: (newProjectId: string, newApiUrl: string) => void): void;
+export declare function registerTools(server: McpServer, projectId: string, user: string, agentId: string): void;

package/dist/tools/index.js

@@ -1,8 +1,7 @@
 /**
  * MCP 工具注册入口
- * 7 个工具, 6 个子模块
+ * 保留工具注册入口
  *
- * kg_init       — 项目初始化
  * kg_status     — 仪表盘
  * kg_flowchart  — 知识图谱核心
  * kg_workflow   — AI 工作流
@@ -11,16 +10,14 @@
  * code_scan/code_smart_context/code_full_path — 代码分析 (可选)
  */
 import { createContext } from './shared.js';
-import { registerInitTool } from './init.js';
 import { registerStatusTool } from './kg_status.js';
 import { registerWorkflowTools } from './workflow.js';
 import { registerTaskTools } from './tasks.js';
 import { registerReferenceTools } from './refs.js';
 import { registerAnalyzerTools } from './analyzer.js';
 import { registerFlowchartTools } from './flowchart.js';
-export function registerTools(server, projectId, user, agentId, onProjectChange) {
+export function registerTools(server, projectId, user, agentId) {
     const ctx = createContext(projectId, user, agentId);
-    registerInitTool(server, ctx, onProjectChange || (() => { }));
     registerStatusTool(server, ctx);
     registerWorkflowTools(server, ctx);
     registerTaskTools(server, ctx);

package/dist/tools/shared.d.ts

@@ -2,13 +2,13 @@
  * MCP 工具共享模块
  * 合并原 helpers.ts + 新增 safeTool / withCross 模式
  */
-/** 运行时可变上下文 — 所有工具通过引用获取最新值 */
+/** MCP 工具共享上下文 */
 export interface McpContext {
     projectId: string;
     user: string;
     agentId: string;
 }
-/** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
+/** 创建共享上下文对象 */
 export declare function createContext(projectId: string, user: string, agentId: string): McpContext;
 export declare function wrap(text: string): {
     content: {

package/dist/tools/shared.js

@@ -2,7 +2,7 @@
  * MCP 工具共享模块
  * 合并原 helpers.ts + 新增 safeTool / withCross 模式
  */
-/** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
+/** 创建共享上下文对象 */
 export function createContext(projectId, user, agentId) {
     return { projectId, user, agentId };
 }

package/package.json

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

package/templates/AGENT.md

@@ -44,13 +44,10 @@
 | `kg_flowchart(batch_add, nodes, edges)` | 新增模块时批量创建节点 |
 | `kg_flowchart(create_chart)` | 为复杂模块创建子流程图 |
 
-### 协作与文件
+### 外部参考
 | 工具 | 用途 |
 |:---|:---|
-| `kg_discuss(create/reply/list)` | 跨 AI 实例讨论 |
-| `kg_meeting(join/post/status)` | 多 AI 协作会议 |
-| `kg_files(list/read/download)` | 项目文件管理 |
-| `kg_ref(list/get/save)` | 外部参考资料管理 |
+| `kg_ref(list|get|fetch|delete)` | 外部参考资料管理 |
 
 ## 核心原则
 

package/templates/commands/pp/init.md

@@ -27,11 +27,12 @@
 
 ### Phase 0: 环境准备
 ```
-kg_init()                   → 仅在自动连接失效时手动兜底
 kg_status()                 → 查看仪表盘 (流程图/任务/状态)
 kg_flowchart(action:"list") → 已有流程图列表
 kg_flowchart(action:"get")  → 主图结构总览
 ```
+若 `kg_status()` 失败，先检查当前项目目录下的 `.ppdocs` 绑定是否存在且可用。
+
 如果已有图谱 → 提示用户选择: 增量补充 or 重建
 
 ### Phase 1: 代码侦察

package/templates/commands/pp/sync.md

@@ -29,11 +29,12 @@
 
 **1.1 获取图谱现状**
 ```
-kg_init()                        → 仅在自动连接失效时手动兜底
 kg_flowchart(action:"list")      → 所有流程图
 kg_flowchart(action:"get")       → 主图节点+连线
 kg_flowchart(action:"search", query:"关键词") → 快速定位相关节点
 ```
+若工具调用失败，先检查当前项目目录下的 `.ppdocs` 绑定是否存在且可用。
+
 
 **1.2 获取代码变更**
 ```

package/templates/cursorrules.md

@@ -44,13 +44,10 @@
 | `kg_flowchart(batch_add, nodes, edges)` | 新增模块时批量创建节点 |
 | `kg_flowchart(create_chart)` | 为复杂模块创建子流程图 |
 
-### 协作与文件
+### 外部参考
 | 工具 | 用途 |
 |:---|:---|
-| `kg_discuss(create/reply/list)` | 跨 AI 实例讨论 |
-| `kg_meeting(join/post/status)` | 多 AI 协作会议 |
-| `kg_files(list/read/download)` | 项目文件管理 |
-| `kg_ref(list/get/save)` | 外部参考资料管理 |
+| `kg_ref(list|get|fetch|delete)` | 外部参考资料管理 |
 
 ## 核心原则
 

package/templates/hooks/SystemPrompt.md

@@ -1,7 +1,7 @@
 你是严谨的软件架构师，围绕**用户知识图谱软件**工作，确保每个变动有据可查，每次成功沉淀为知识节点。
 
 ## 会话启动检查
-每次会话开始时, 执行 `kg_discuss({ action: "list" })` 检查是否有涉及本项目的待回复讨论。如有, 主动提醒用户: "发现 N 条待处理讨论, 是否需要查看?"
+每次会话开始时, 执行 `kg_status()` 获取当前项目总览；如需流程指导，再执行 `kg_workflow()` 查看可用工作流。
 
 ## 核心宪法
 | 原则 | 要求 |

package/templates/kiro-rules/ppdocs.md

@@ -44,13 +44,10 @@
 | `kg_flowchart(batch_add, nodes, edges)` | 新增模块时批量创建节点 |
 | `kg_flowchart(create_chart)` | 为复杂模块创建子流程图 |
 
-### 协作与文件
+### 外部参考
 | 工具 | 用途 |
 |:---|:---|
-| `kg_discuss(create/reply/list)` | 跨 AI 实例讨论 |
-| `kg_meeting(join/post/status)` | 多 AI 协作会议 |
-| `kg_files(list/read/download)` | 项目文件管理 |
-| `kg_ref(list/get/save)` | 外部参考资料管理 |
+| `kg_ref(list|get|fetch|delete)` | 外部参考资料管理 |
 
 ## 核心原则
 

package/dist/tools/init.d.ts

@@ -1,12 +0,0 @@
-/**
- * kg_init 工具 — 项目上下文初始化
- *
- * 解决全局共用 MCP 进程时的多项目隔离问题：
- * - 智能体调用 kg_init 传入 projectPath
- * - MCP 从该路径读取 .ppdocs 配置
- * - 重新初始化 HTTP Client 指向正确项目
- * - 更新共享 McpContext，所有工具自动获取新 projectId
- */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpContext } from './shared.js';
-export declare function registerInitTool(server: McpServer, ctx: McpContext, onProjectChange: (newProjectId: string, newApiUrl: string) => void): void;

package/dist/tools/init.js

@@ -1,89 +0,0 @@
-/**
- * kg_init 工具 — 项目上下文初始化
- *
- * 解决全局共用 MCP 进程时的多项目隔离问题：
- * - 智能体调用 kg_init 传入 projectPath
- * - MCP 从该路径读取 .ppdocs 配置
- * - 重新初始化 HTTP Client 指向正确项目
- * - 更新共享 McpContext，所有工具自动获取新 projectId
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { z } from 'zod';
-import { initClient } from '../storage/httpClient.js';
-import { generateAgentId } from '../config.js';
-import { wrap, safeTool } from './shared.js';
-// 当前会话的 API URL (用于幂等检查)
-let currentApiUrl = null;
-function findPpdocsPathFrom(dir) {
-    let currentDir = path.resolve(dir);
-    while (true) {
-        const configPath = path.join(currentDir, '.ppdocs');
-        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
-            return configPath;
-        }
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir) {
-            return null;
-        }
-        currentDir = parentDir;
-    }
-}
-/** 尝试从指定目录读取 .ppdocs 配置 */
-function readPpdocsFrom(dir) {
-    const configPath = findPpdocsPathFrom(dir);
-    if (!configPath)
-        return null;
-    try {
-        const c = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-        if (!c.api || !c.projectId || !c.key)
-            return null;
-        return {
-            apiUrl: `${c.api}/api/${c.projectId}/${c.key}`,
-            projectId: c.projectId,
-            user: c.user || 'mcp-agent',
-        };
-    }
-    catch {
-        return null;
-    }
-}
-export function registerInitTool(server, ctx, onProjectChange) {
-    server.tool('kg_init', '项目上下文初始化。读取指定目录的 .ppdocs 配置，切换 MCP 连接到对应项目。首次对话必须调用。不传 projectPath 则使用当前工作目录', {
-        projectPath: z.string().optional().describe('项目根目录的绝对路径(含 .ppdocs 文件)，不传则使用 cwd'),
-    }, async ({ projectPath }) => safeTool(async () => {
-        const targetDir = projectPath || process.cwd();
-        // 1. 尝试从目标目录读取 .ppdocs
-        const config = readPpdocsFrom(targetDir);
-        if (!config) {
-            return wrap(`❌ 未在 ${targetDir} 找到 .ppdocs 配置文件\n\n` +
-                `请先在项目目录中运行:\n` +
-                `  npx @ppdocs/mcp init -p <projectId> -k <key>\n\n` +
-                `或通过 WebUI 绑定项目:\n` +
-                `  npx @ppdocs/mcp webui`);
-        }
-        // 2. 幂等检查
-        if (currentApiUrl === config.apiUrl) {
-            return wrap(`✅ 项目上下文已就绪 (无需切换)\n\n` +
-                `📂 项目: ${config.projectId}\n` +
-                `🔗 API: ${config.apiUrl.replace(/\/[^/]+$/, '/***')}\n` +
-                `👤 用户: ${config.user}`);
-        }
-        // 3. 重新初始化 HTTP Client
-        initClient(config.apiUrl);
-        currentApiUrl = config.apiUrl;
-        // 4. 更新共享上下文 — 所有工具立刻获得新 projectId
-        ctx.projectId = config.projectId;
-        ctx.user = config.user;
-        // agentId: 优先环境变量 > 保留当前值(进程启动时已生成)
-        ctx.agentId = process.env.PPDOCS_AGENT_ID || ctx.agentId || generateAgentId();
-        // 5. 通知主进程
-        onProjectChange(config.projectId, config.apiUrl);
-        return wrap(`✅ 项目上下文已初始化\n\n` +
-            `📂 项目: ${config.projectId}\n` +
-            `📁 路径: ${targetDir}\n` +
-            `🔗 API: ${config.apiUrl.replace(/\/[^/]+$/, '/***')}\n` +
-            `👤 用户: ${config.user}\n\n` +
-            `所有后续工具调用将自动连接到此项目。`);
-    }));
-}