@ppdocs/mcp 3.1.10 → 3.2.0

package/dist/agent.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * PPDocs Agent V2 — 多项目管理入口
+ * 功能: Web Config UI + 多 SyncBeacon + 持久后台运行
+ */
+export {};

package/dist/agent.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * PPDocs Agent V2 — 多项目管理入口
+ * 功能: Web Config UI + 多 SyncBeacon + 持久后台运行
+ */
+import { startWebServer, loadAgentConfig, setAgentState, setProjectStatus } from './web/server.js';
+import { initClient } from './storage/httpClient.js';
+import { SyncBeacon } from './sync/beacon.js';
+const DEFAULT_WEB_PORT = 20010;
+// 多项目 SyncBeacon 管理
+const beacons = new Map();
+async function main() {
+    console.log('📡 PPDocs Agent V2 starting...\n');
+    // 解析端口参数
+    let webPort = DEFAULT_WEB_PORT;
+    const args = process.argv.slice(2);
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--port' && args[i + 1]) {
+            webPort = parseInt(args[i + 1], 10) || DEFAULT_WEB_PORT;
+        }
+    }
+    // 加载配置
+    const config = loadAgentConfig();
+    if (config) {
+        webPort = config.webPort || webPort;
+        console.log(`📋 主机: ${config.host}:${config.port}`);
+        console.log(`📂 已绑定 ${config.projects.length} 个项目`);
+        // 测试主机连接
+        try {
+            const resp = await fetch(`http://${config.host}:${config.port}/health`);
+            setAgentState({ hostConnected: resp.ok });
+            if (resp.ok)
+                console.log('✅ 主机连接正常');
+        }
+        catch {
+            setAgentState({ hostConnected: false });
+            console.log('⚠️  主机不可达，将在后台重试');
+        }
+        // 为每个项目启动同步
+        for (const proj of config.projects) {
+            await startProjectSync(config, proj);
+        }
+    }
+    else {
+        console.log('⚙️  首次运行，请在浏览器中完成配置');
+    }
+    // 注册回调
+    setAgentState({
+        onBind: async (project) => {
+            const cfg = loadAgentConfig();
+            if (cfg)
+                await startProjectSync(cfg, project);
+        },
+        onUnbind: (remoteId) => {
+            stopProjectSync(remoteId);
+        },
+    });
+    // 启动 Web Server
+    startWebServer(webPort);
+    // 首次运行自动打开浏览器
+    if (!config) {
+        const url = `http://localhost:${webPort}`;
+        try {
+            const { exec } = await import('child_process');
+            const cmd = process.platform === 'win32' ? `start ${url}`
+                : process.platform === 'darwin' ? `open ${url}` : `xdg-open ${url}`;
+            exec(cmd);
+        }
+        catch { /* ignore */ }
+    }
+}
+async function startProjectSync(config, proj) {
+    const { host, port } = config;
+    const { remote, localDir, sync } = proj;
+    // 初始化该项目的 HTTP 连接 (验证)
+    const apiUrl = `http://${host}:${port}/api/${remote.id}/${remote.password}`;
+    try {
+        const resp = await fetch(`${apiUrl}/docs`);
+        if (resp.ok) {
+            const data = await resp.json();
+            const docCount = data.data?.length || 0;
+            setProjectStatus(remote.id, { connected: true, syncStatus: '已连接', docCount });
+            console.log(`  ✅ ${remote.name}: 已连接 (${docCount} 文档)`);
+        }
+        else {
+            setProjectStatus(remote.id, { connected: false, syncStatus: '连接失败' });
+            console.log(`  ❌ ${remote.name}: 连接失败`);
+            return;
+        }
+    }
+    catch (e) {
+        setProjectStatus(remote.id, { connected: false, syncStatus: `错误: ${e}` });
+        return;
+    }
+    // 启动 SyncBeacon
+    if (localDir && sync?.enabled) {
+        stopProjectSync(remote.id); // 先停旧的
+        // 需要临时给 httpClient 设置对应项目的 API URL
+        initClient(apiUrl);
+        const beacon = new SyncBeacon(localDir, remote.id, (sync.intervalSec || 15) * 1000);
+        beacon.start();
+        beacons.set(remote.id, beacon);
+        setProjectStatus(remote.id, { syncStatus: '同步中', lastSync: new Date() });
+        console.log(`  📂 ${remote.name}: 文件同步已启动`);
+    }
+}
+function stopProjectSync(remoteId) {
+    const beacon = beacons.get(remoteId);
+    if (beacon) {
+        beacon.stop();
+        beacons.delete(remoteId);
+        console.log(`  🛑 停止同步: ${remoteId}`);
+    }
+}
+// 优雅退出
+process.on('SIGINT', () => {
+    console.log('\n🛑 Agent 正在关闭...');
+    for (const [, beacon] of beacons)
+        beacon.stop();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    for (const [, beacon] of beacons)
+        beacon.stop();
+    process.exit(0);
+});
+main().catch(e => {
+    console.error('❌ Agent 启动失败:', e);
+    process.exit(1);
+});

package/dist/cli.js

@@ -90,6 +90,7 @@ ppdocs MCP CLI
 
 Commands:
   init    Initialize ppdocs config + install workflow templates
+  agent   Start PPDocs Agent (Web UI + File Sync)
 
 Usage:
   npx @ppdocs/mcp init -p <projectId> -k <key> [options]
@@ -126,6 +127,14 @@ export function runCli(args) {
         });
         return true;
     }
+    if (cmd === 'agent') {
+        // 动态导入 Agent 入口
+        import('./agent.js').catch(e => {
+            console.error(`❌ Agent failed: ${e}`);
+            process.exit(1);
+        });
+        return true;
+    }
     if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
         showHelp();
         return true;

package/dist/config.d.ts

@@ -6,7 +6,7 @@ export interface PpdocsConfig {
     apiUrl: string;
     projectId: string;
     user: string;
-    source: 'env' | 'file' | 'discover' | 'auth';
+    source: 'env' | 'file' | 'auth';
     /** 原始连接参数 (discover/auth 填充, 供持久化使用) */
     connection?: {
         host: string;

package/dist/config.js

@@ -48,38 +48,6 @@ async function findLocalServer() {
     }
     return null;
 }
-// ============ 自动发现 ============
-async function autoDiscoverConfig(server) {
-    const cwd = process.cwd().replace(/\\/g, '/').toLowerCase();
-    try {
-        const res = await fetch(`${server.base}/api/projects`, { signal: AbortSignal.timeout(2000) });
-        if (!res.ok)
-            return null;
-        const { data: projects } = await res.json();
-        if (!Array.isArray(projects))
-            return null;
-        const match = projects.find((p) => p.projectPath && cwd.startsWith(p.projectPath.replace(/\\/g, '/').toLowerCase()));
-        if (!match)
-            return null;
-        const metaRes = await fetch(`${server.base}/api/projects/${match.id}/meta`, { signal: AbortSignal.timeout(2000) });
-        if (!metaRes.ok)
-            return null;
-        const { data: meta } = await metaRes.json();
-        if (!meta?.password)
-            return null;
-        console.error(`[AutoDiscovery] 匹配项目: ${match.name} (${match.id})`);
-        return {
-            apiUrl: `${server.base}/api/${match.id}/${meta.password}`,
-            projectId: match.id,
-            user: `auto-${generateUser().slice(0, 4)}`,
-            source: 'discover',
-            connection: { host: server.host, port: server.port, password: meta.password },
-        };
-    }
-    catch {
-        return null;
-    }
-}
 // ============ 授权请求 ============
 async function requestAuthConfig(server) {
     try {
@@ -154,19 +122,15 @@ export async function loadConfig() {
     const fileConfig = readPpdocsFile();
     if (fileConfig)
         return fileConfig;
-    // 3-4. 需要服务器 → 只扫一次
+    // 3. 扫描本地服务器 → 请求桌面端授权
     const server = await findLocalServer();
     if (server) {
-        const discoverConfig = await autoDiscoverConfig(server);
-        if (discoverConfig)
-            return discoverConfig;
         const authConfig = await requestAuthConfig(server);
         if (authConfig)
             return authConfig;
     }
-    // 5. 全部失败
-    console.error('ERROR: ppdocs config not found');
-    console.error('  Option 1: npx @ppdocs/mcp init -p <projectId> -k <key>');
-    console.error('  Option 2: Ensure ppdocs desktop app is running');
+    // 全部失败
+    console.error('ERROR: ppdocs 配置未找到');
+    console.error('  请确保 ppdocs 桌面端正在运行，或手动配置 PPDOCS_API_URL 环境变量');
     process.exit(1);
 }

package/dist/index.js

@@ -28,7 +28,7 @@ if (args.length > 0 && runCli(args)) {
 async function main() {
     const config = await loadConfig();
     // 自动持久化: 发现/授权后写入 .ppdocs + 安装模板
-    if ((config.source === 'discover' || config.source === 'auth') && config.connection) {
+    if (config.source === 'auth' && config.connection) {
         try {
             writePpdocsFile(config);
             setupProjectFiles(process.cwd(), config.apiUrl);

package/dist/storage/discussion.d.ts

@@ -0,0 +1,33 @@
+export interface DiscussionMessage {
+    id: string;
+    sender: string;
+    content: string;
+    timestamp: string;
+}
+export interface DiscussionTopic {
+    id: string;
+    title: string;
+    initiator: string;
+    participants: string[];
+    summary: string;
+    status: 'active' | 'completed';
+    created_at: string;
+    updated_at: string;
+    messages: DiscussionMessage[];
+}
+export declare class DiscussionManager {
+    private static getFilePath;
+    private static readAll;
+    private static writeAll;
+    static listActive(): Omit<DiscussionTopic, 'messages'>[];
+    static readByIds(ids: string[]): DiscussionTopic[];
+    static create(title: string, initiator: string, participants: string[], content: string): string;
+    static reply(id: string, sender: string, content: string, newSummary?: string): boolean;
+    static getAndRemove(id: string): DiscussionTopic | null;
+    /** 按ID删除讨论（不归档，直接删除） */
+    static delete(id: string): boolean;
+    /** 清理过期讨论（默认7天不活跃） */
+    static cleanExpired(days?: number): number;
+    /** 获取活跃讨论数量 */
+    static activeCount(): number;
+}

package/dist/storage/discussion.js

@@ -0,0 +1,116 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+export class DiscussionManager {
+    static getFilePath() {
+        const dir = path.join(os.homedir(), '.ppdocs');
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        return path.join(dir, 'discussions.json');
+    }
+    static readAll() {
+        try {
+            const file = this.getFilePath();
+            if (!fs.existsSync(file))
+                return [];
+            return JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    static writeAll(data) {
+        fs.writeFileSync(this.getFilePath(), JSON.stringify(data, null, 2), 'utf-8');
+    }
+    static listActive() {
+        return this.readAll()
+            .filter(t => t.status === 'active')
+            .map(({ messages, ...rest }) => rest);
+    }
+    static readByIds(ids) {
+        return this.readAll().filter(t => ids.includes(t.id));
+    }
+    static create(title, initiator, participants, content) {
+        const id = `req_${Math.random().toString(36).substring(2, 9)}`;
+        const now = new Date().toISOString();
+        // 确保发起方始终在参与列表中
+        const allParticipants = participants.includes(initiator) ? [...participants] : [initiator, ...participants];
+        const topic = {
+            id,
+            title,
+            initiator,
+            participants: allParticipants,
+            summary: "等待各方回复中...",
+            status: 'active',
+            created_at: now,
+            updated_at: now,
+            messages: [{
+                    id: `msg_${Math.random().toString(36).substring(2, 9)}`,
+                    sender: initiator,
+                    content,
+                    timestamp: now
+                }]
+        };
+        const all = this.readAll();
+        all.push(topic);
+        this.writeAll(all);
+        return id;
+    }
+    static reply(id, sender, content, newSummary) {
+        const all = this.readAll();
+        const topic = all.find(t => t.id === id);
+        if (!topic || topic.status !== 'active')
+            return false;
+        const now = new Date().toISOString();
+        topic.messages.push({
+            id: `msg_${Math.random().toString(36).substring(2, 9)}`,
+            sender,
+            content,
+            timestamp: now
+        });
+        topic.updated_at = now;
+        if (newSummary) {
+            topic.summary = newSummary;
+        }
+        // Auto add to participants if not exists
+        if (!topic.participants.includes(sender)) {
+            topic.participants.push(sender);
+        }
+        this.writeAll(all);
+        return true;
+    }
+    static getAndRemove(id) {
+        const all = this.readAll();
+        const index = all.findIndex(t => t.id === id);
+        if (index === -1)
+            return null;
+        const topic = all.splice(index, 1)[0];
+        this.writeAll(all);
+        return topic;
+    }
+    /** 按ID删除讨论（不归档，直接删除） */
+    static delete(id) {
+        const all = this.readAll();
+        const index = all.findIndex(t => t.id === id);
+        if (index === -1)
+            return false;
+        all.splice(index, 1);
+        this.writeAll(all);
+        return true;
+    }
+    /** 清理过期讨论（默认7天不活跃） */
+    static cleanExpired(days = 7) {
+        const all = this.readAll();
+        const cutoff = Date.now() - days * 86400000;
+        const before = all.length;
+        const filtered = all.filter(t => new Date(t.updated_at).getTime() > cutoff);
+        if (filtered.length < before) {
+            this.writeAll(filtered);
+        }
+        return before - filtered.length;
+    }
+    /** 获取活跃讨论数量 */
+    static activeCount() {
+        return this.readAll().filter(t => t.status === 'active').length;
+    }
+}

package/dist/storage/httpClient.d.ts

@@ -96,6 +96,14 @@ export declare class PpdocsApiClient {
         localPath: string;
         fileCount: number;
     }>;
+    /** 扫描项目代码, 构建/更新索引 */
+    analyzerScan(projectPath: string, force?: boolean): Promise<unknown>;
+    /** 查询代码符号 (模糊匹配) */
+    analyzerQuery(projectPath: string, query: string): Promise<unknown>;
+    /** 分层影响分析 (BFS 递归, 可指定深度) */
+    analyzerImpactTree(projectPath: string, symbolName: string, depth?: number): Promise<unknown>;
+    /** 获取文件 360° 上下文 */
+    analyzerContext(projectPath: string, filePath: string): Promise<unknown>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function getClient(): PpdocsApiClient;

package/dist/storage/httpClient.js

@@ -480,6 +480,35 @@ export class PpdocsApiClient {
     async crossDownload(target, remotePath, localPath) {
         return fetchAndExtractZip(`${this.baseUrl}/cross/${encodeURIComponent(target)}/files-download/${cleanPath(remotePath)}`, localPath);
     }
+    // ============ 代码分析引擎 ============
+    /** 扫描项目代码, 构建/更新索引 */
+    async analyzerScan(projectPath, force = false) {
+        return this.request('/analyzer/scan', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, force }),
+        });
+    }
+    /** 查询代码符号 (模糊匹配) */
+    async analyzerQuery(projectPath, query) {
+        return this.request('/analyzer/query', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, query }),
+        });
+    }
+    /** 分层影响分析 (BFS 递归, 可指定深度) */
+    async analyzerImpactTree(projectPath, symbolName, depth = 2) {
+        return this.request('/analyzer/impact-tree', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, symbol_name: symbolName, depth }),
+        });
+    }
+    /** 获取文件 360° 上下文 */
+    async analyzerContext(projectPath, filePath) {
+        return this.request('/analyzer/context', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, file_path: filePath }),
+        });
+    }
 }
 // ============ 模块级 API ============
 let client = null;

package/dist/tools/analyzer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 代码分析引擎工具 (4个)
+ * code_scan, code_query, code_impact, code_context
+ *
+ * 让 AI Agent 通过 MCP 工具直接查询代码结构、依赖关系和影响范围
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAnalyzerTools(server: McpServer, projectId: string): void;

package/dist/tools/analyzer.js

@@ -0,0 +1,136 @@
+/**
+ * 代码分析引擎工具 (4个)
+ * code_scan, code_query, code_impact, code_context
+ *
+ * 让 AI Agent 通过 MCP 工具直接查询代码结构、依赖关系和影响范围
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { wrap, safeTool } from './shared.js';
+// 符号图标
+const SYMBOL_ICONS = {
+    function: '𝑓', class: '𝐂', method: '𝑚', interface: '𝐈',
+    type_alias: '𝐓', enum: '𝐄', struct: '𝐒', trait: '⚡',
+    constant: '𝐊', variable: '𝑣',
+};
+const SEVERITY_ICONS = {
+    critical: '🔴', warning: '🟡', info: '🟢',
+};
+export function registerAnalyzerTools(server, projectId) {
+    const client = () => getClient();
+    // ===== code_scan: 扫描项目代码 =====
+    server.tool('code_scan', '📡 扫描项目代码, 构建索引。返回文件数、符号数、语言统计。★首次使用 code_query/code_impact/code_context 前必须先执行★', {
+        projectPath: z.string().describe('项目源码的绝对路径(如"D:/projects/myapp")'),
+        force: z.boolean().optional().describe('是否强制全量重建(默认false, 增量更新)'),
+    }, async (args) => safeTool(async () => {
+        const result = await client().analyzerScan(args.projectPath, args.force ?? false);
+        return wrap([
+            `✅ 代码扫描完成`,
+            ``,
+            `📊 索引摘要:`,
+            `- 文件数: ${result.fileCount}`,
+            `- 符号数: ${result.symbolCount}`,
+            `- 语言: ${result.languages.join(', ')}`,
+            `- 索引时间: ${result.indexedAt}`,
+        ].join('\n'));
+    }));
+    // ===== code_query: 搜索代码符号 =====
+    server.tool('code_query', '🔤 搜索代码符号(函数/类/方法/接口/类型)。返回匹配列表+文件路径+行号。定位代码位置的最快方式。需先运行 code_scan', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        query: z.string().describe('搜索关键词(函数名/类名/方法名等)'),
+    }, async (args) => safeTool(async () => {
+        const results = await client().analyzerQuery(args.projectPath, args.query);
+        if (!results || results.length === 0) {
+            return wrap(`未找到匹配 "${args.query}" 的符号。请确认已运行 code_scan`);
+        }
+        const lines = results.map(r => {
+            const icon = SYMBOL_ICONS[r.symbol.kind] || '?';
+            const exp = r.symbol.exported ? ' [export]' : '';
+            const parent = r.symbol.parent ? ` ◀ ${r.symbol.parent}` : '';
+            return `  ${icon} ${r.symbol.name}${parent}${exp}  →  ${r.filePath}:${r.symbol.lineStart}`;
+        });
+        return wrap([
+            `🔤 找到 ${results.length} 个匹配符号:`,
+            ``,
+            ...lines,
+        ].join('\n'));
+    }));
+    // ===== code_impact: 分层影响分析 =====
+    server.tool('code_impact', '💥 爆炸半径分析 ★修改代码前必查★ 分析修改一个函数/类/类型会影响多少文件。BFS分层输出: L1🔴直接引用=必须检查, L2🟡间接引用=建议检查, L3🟢传递引用=注意。修改任何公共接口、函数签名、类型定义前务必先运行!', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        symbolName: z.string().describe('要分析的符号名称(如"AuthService", "handleLogin")'),
+        depth: z.number().optional().describe('分析深度层级(1-5, 默认2)。1=仅直接引用, 3=深度追踪'),
+    }, async (args) => safeTool(async () => {
+        const result = await client().analyzerImpactTree(args.projectPath, args.symbolName, args.depth ?? 2);
+        if (!result) {
+            return wrap(`未找到符号 "${args.symbolName}"。请确认名称正确且已运行 code_scan`);
+        }
+        if (result.levels.length === 0) {
+            return wrap(`✅ "${args.symbolName}" 没有被其他文件引用, 修改安全`);
+        }
+        // 生成分层树形输出
+        const lines = [
+            `🎯 ${result.symbolName} (${result.symbolKind})`,
+            `📍 定义: ${result.definedIn}:${result.lineStart}`,
+            ``,
+            `📊 ${result.summary}`,
+            ``,
+        ];
+        for (const level of result.levels) {
+            const icon = SEVERITY_ICONS[level.severity] || '⚪';
+            const label = level.depth === 1 ? '直接引用 (必须检查)' :
+                level.depth === 2 ? '间接引用 (建议检查)' :
+                    '传递引用 (注意)';
+            lines.push(`### ${icon} L${level.depth} ${label} (${level.count}个)`);
+            for (const entry of level.entries) {
+                lines.push(`  ${entry.filePath}:${entry.line}  [${entry.refKind}]  ${entry.context}`);
+            }
+            lines.push('');
+        }
+        return wrap(lines.join('\n'));
+    }));
+    // ===== code_context: 文件360°上下文 =====
+    server.tool('code_context', '🔍 文件360°上下文 — 定义了什么符号、导入了什么、被谁引用。修改文件前使用, 快速了解所有依赖关系, 避免遗漏', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        filePath: z.string().describe('目标文件的相对路径(如"src/services/auth.ts")'),
+    }, async (args) => safeTool(async () => {
+        const ctx = await client().analyzerContext(args.projectPath, args.filePath);
+        if (!ctx) {
+            return wrap(`未找到文件 "${args.filePath}"。请确认路径正确, 路径格式为相对路径(如 src/main.ts)`);
+        }
+        const lines = [
+            `📄 ${ctx.filePath}`,
+            `语言: ${ctx.language} | ${ctx.linesTotal} 行`,
+            ``,
+        ];
+        // 定义的符号
+        if (ctx.symbolsDefined.length > 0) {
+            lines.push(`### 🔤 定义的符号 (${ctx.symbolsDefined.length})`);
+            for (const sym of ctx.symbolsDefined) {
+                const icon = SYMBOL_ICONS[sym.kind] || '?';
+                const exp = sym.exported ? ' [export]' : '';
+                lines.push(`  ${icon} ${sym.name}${exp}  L${sym.lineStart}-L${sym.lineEnd}`);
+            }
+            lines.push('');
+        }
+        // 导入
+        if (ctx.imports.length > 0) {
+            lines.push(`### 📥 导入 (${ctx.imports.length})`);
+            for (const imp of ctx.imports) {
+                const specs = imp.specifiers.length > 0 ? `{ ${imp.specifiers.join(', ')} }` : '*';
+                lines.push(`  → ${imp.source}  ${specs}  L${imp.line}`);
+            }
+            lines.push('');
+        }
+        // 被谁引用
+        if (ctx.importedBy.length > 0) {
+            lines.push(`### 📤 被引用 (${ctx.importedBy.length})`);
+            for (const by of ctx.importedBy) {
+                const specs = by.specifiers.length > 0 ? `{ ${by.specifiers.join(', ')} }` : '';
+                lines.push(`  ← ${by.filePath}  ${specs}`);
+            }
+            lines.push('');
+        }
+        return wrap(lines.join('\n'));
+    }));
+}

package/dist/tools/discussion.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 💬 kg_discuss (6→1)
+ * 合并: kg_discussion_list, kg_discussion_read, kg_discussion_create,
+ *       kg_discussion_reply, kg_discussion_close_and_archive, kg_discussion_delete
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDiscussionTools(server: McpServer, projectId: string): void;