maestro-flow 0.5.2 → 0.5.31

package/dist/src/graph/kg/surface/hook-injector.d.ts

@@ -0,0 +1,33 @@
+export interface InjectionResult {
+    inject: boolean;
+    content?: string;
+    reason?: string;
+}
+/**
+ * 统一 hook 注入 — 替代现有 5 个 hook
+ *
+ * 现有 hook:
+ *   keyword-spec-injector  (UserPromptSubmit)
+ *   spec-injector          (PreToolUse:Agent)
+ *   kg-context-injector    (PreToolUse:Agent)
+ *   domain-injector        (集成在 keyword-spec-injector)
+ *   wiki-role-loader       (集成在 spec-injector)
+ *
+ * 统一后:
+ *   kg-unified-injector    (UserPromptSubmit + PreToolUse:Agent)
+ *     → 单次 KG 查询
+ *     → 按 source_type 分组组装 sections
+ *     → context budget 统一管控
+ *     → 输出 <maestro-context> 包含所有层
+ *
+ * D5.2: 灰度切换 — 通过 toggle 控制启用/禁用
+ * D5.3: 共存互斥 — 当统一 hook 活跃时, 旧 hook 自动让步
+ */
+export declare function evaluateUnifiedInjection(prompt: string, agentType: string | null, // null = UserPromptSubmit, string = PreToolUse:Agent
+projectPath: string, sessionId: string): Promise<InjectionResult>;
+/**
+ * 供旧 hook 调用 — 检测统一注入器是否活跃
+ * 如果活跃, 旧 hook 应返回 { inject: false, reason: 'deferred-to-unified' }
+ */
+export declare function isUnifiedInjectorActive(projectPath: string): boolean;
+//# sourceMappingURL=hook-injector.d.ts.map

package/dist/src/graph/kg/surface/hook-injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-injector.d.ts","sourceRoot":"","sources":["../../../../../src/graph/kg/surface/hook-injector.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAAG,IAAI,EAAG,qDAAqD;AAChF,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CA+D1B;AAmFD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAEpE"}

package/dist/src/graph/kg/surface/hook-injector.js

@@ -0,0 +1,172 @@
+// src/graph/kg/surface/hook-injector.ts — 统一 Hook 注入器
+// 参考: plan-maestrograph.md R7 — 替代现有 5 个 hook 的单一注入器
+// D5.2: 灰度切换 + D5.3: CodeGraph 共存互斥
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { getKgDatabasePath } from '../db/connection.js';
+const esmRequire = createRequire(import.meta.url);
+import { buildContext, getAgentCategories } from '../query/context-builder.js';
+import { precheckKg } from './mcp-tools.js';
+// ---------------------------------------------------------------------------
+// 统一注入入口
+// ---------------------------------------------------------------------------
+/**
+ * 统一 hook 注入 — 替代现有 5 个 hook
+ *
+ * 现有 hook:
+ *   keyword-spec-injector  (UserPromptSubmit)
+ *   spec-injector          (PreToolUse:Agent)
+ *   kg-context-injector    (PreToolUse:Agent)
+ *   domain-injector        (集成在 keyword-spec-injector)
+ *   wiki-role-loader       (集成在 spec-injector)
+ *
+ * 统一后:
+ *   kg-unified-injector    (UserPromptSubmit + PreToolUse:Agent)
+ *     → 单次 KG 查询
+ *     → 按 source_type 分组组装 sections
+ *     → context budget 统一管控
+ *     → 输出 <maestro-context> 包含所有层
+ *
+ * D5.2: 灰度切换 — 通过 toggle 控制启用/禁用
+ * D5.3: 共存互斥 — 当统一 hook 活跃时, 旧 hook 自动让步
+ */
+export async function evaluateUnifiedInjection(prompt, agentType, // null = UserPromptSubmit, string = PreToolUse:Agent
+projectPath, sessionId) {
+    // D5.3: 互斥检测 — 检查旧 hook 是否应该让步
+    if (!isUnifiedInjectorEnabled(projectPath)) {
+        return { inject: false, reason: 'unified-injector-disabled' };
+    }
+    // Precheck — D4.4 降级策略
+    const check = precheckKg(projectPath);
+    if (check.status === 'uninitialized') {
+        // 降级到旧 hook (如果可用)
+        return { inject: false, reason: 'kg-uninitialized' };
+    }
+    // D6.3: 快速损坏检测
+    if (!quickHealthCheck(projectPath)) {
+        return { inject: false, reason: 'kg-corrupted' };
+    }
+    try {
+        const { MaestroGraph } = await import('../engine.js');
+        const mg = await MaestroGraph.open(projectPath);
+        let context;
+        try {
+            const queries = mg.getQueryBuilder();
+            context = buildContext(queries, prompt, {
+                expandDepth: 1,
+                agentType: agentType ?? undefined,
+            });
+            if (agentType) {
+                const categories = getAgentCategories(agentType);
+                if (categories.length > 0) {
+                    const roleSpecs = queries.searchKnowledgeFTS(agentType, {
+                        limit: 5,
+                        sourceTypes: ['spec'], // eslint-disable-line @typescript-eslint/no-explicit-any
+                    });
+                    if (roleSpecs.length > 0) {
+                        context.sections.push({
+                            label: `role-specs[${categories.join(',')}]`,
+                            lines: roleSpecs.map(s => `[spec:${s.category}] ${s.name}: ${s.definition.substring(0, 200)}`),
+                            sourceType: 'spec',
+                            relevance: 5,
+                        });
+                    }
+                }
+            }
+        }
+        finally {
+            mg.close();
+        }
+        if (context.sections.length === 0) {
+            return { inject: false, reason: 'no-relevant-context' };
+        }
+        return { inject: true, content: formatMaestroContext(context) };
+    }
+    catch (err) {
+        if (process.env.DEBUG) {
+            console.warn('[MaestroGraph] Unified injection error:', err);
+        }
+        return { inject: false, reason: `error: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+// ---------------------------------------------------------------------------
+// 格式化输出 — <maestro-context> 包
+// ---------------------------------------------------------------------------
+function formatMaestroContext(context) {
+    const lines = ['<maestro-context>'];
+    for (const section of context.sections) {
+        lines.push(`  <section label="${section.label}">`);
+        for (const line of section.lines) {
+            lines.push(`    ${line}`);
+        }
+        lines.push('  </section>');
+    }
+    lines.push(`  <!-- ${context.summary.codeSymbols + context.summary.domainTerms + context.summary.specRules + context.summary.knowhowDocs} nodes, ${context.totalChars} chars -->`);
+    lines.push('</maestro-context>');
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// D5.2: 灰度切换
+// ---------------------------------------------------------------------------
+/**
+ * 检查统一注入器是否启用
+ * 优先级: 环境变量 > hooks config > 默认启用
+ */
+function isUnifiedInjectorEnabled(projectPath) {
+    // 环境变量覆盖
+    if (process.env.MAESTRO_KG_UNIFIED_INJECTOR === 'false')
+        return false;
+    if (process.env.MAESTRO_KG_UNIFIED_INJECTOR === 'true')
+        return true;
+    // 检查 .workflow/hooks.json toggle
+    try {
+        const hooksPath = resolve(projectPath, '.workflow', 'hooks.json');
+        if (existsSync(hooksPath)) {
+            const config = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+            if (config.toggles?.kgUnifiedInjector === false)
+                return false;
+        }
+    }
+    catch { /* ignore */ }
+    // 默认启用 (当 maestro.db 存在时)
+    return existsSync(getKgDatabasePath(projectPath));
+}
+// ---------------------------------------------------------------------------
+// D6.3: 快速损坏检测 (< 50ms)
+// ---------------------------------------------------------------------------
+const _healthCache = new Map();
+const HEALTH_CACHE_TTL = 60_000; // 60 秒
+function quickHealthCheck(projectPath) {
+    const now = Date.now();
+    const cacheKey = projectPath;
+    const cached = _healthCache.get(cacheKey);
+    if (cached && now - cached.ts < HEALTH_CACHE_TTL) {
+        return cached.ok;
+    }
+    try {
+        const Database = esmRequire('better-sqlite3');
+        const dbPath = getKgDatabasePath(projectPath);
+        const db = new Database(dbPath, { readonly: true });
+        const qc = db.prepare('PRAGMA quick_check(1)').get();
+        const ok = qc && qc.quick_check === 'ok';
+        db.close();
+        _healthCache.set(cacheKey, { ts: now, ok: Boolean(ok) });
+        return Boolean(ok);
+    }
+    catch {
+        _healthCache.set(cacheKey, { ts: now, ok: false });
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// D5.3: 旧 hook 互斥检测
+// ---------------------------------------------------------------------------
+/**
+ * 供旧 hook 调用 — 检测统一注入器是否活跃
+ * 如果活跃, 旧 hook 应返回 { inject: false, reason: 'deferred-to-unified' }
+ */
+export function isUnifiedInjectorActive(projectPath) {
+    return isUnifiedInjectorEnabled(projectPath) && existsSync(getKgDatabasePath(projectPath));
+}
+//# sourceMappingURL=hook-injector.js.map

package/dist/src/graph/kg/surface/hook-injector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-injector.js","sourceRoot":"","sources":["../../../../../src/graph/kg/surface/hook-injector.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/kg/surface/index.d.ts

@@ -0,0 +1,6 @@
+export { registerKgCommands } from './cli.js';
+export { KG_MCP_TOOLS, handleMcpTool, precheckKg } from './mcp-tools.js';
+export type { McpToolDef, KgPrecheck, KgStatus } from './mcp-tools.js';
+export { evaluateUnifiedInjection, isUnifiedInjectorActive } from './hook-injector.js';
+export type { InjectionResult } from './hook-injector.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/graph/kg/surface/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/graph/kg/surface/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACzE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACvF,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/graph/kg/surface/index.js

@@ -0,0 +1,5 @@
+// src/graph/kg/surface/index.ts — 对外接口导出
+export { registerKgCommands } from './cli.js';
+export { KG_MCP_TOOLS, handleMcpTool, precheckKg } from './mcp-tools.js';
+export { evaluateUnifiedInjection, isUnifiedInjectorActive } from './hook-injector.js';
+//# sourceMappingURL=index.js.map

package/dist/src/graph/kg/surface/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/graph/kg/surface/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AAEzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/graph/kg/surface/mcp-tools.d.ts

@@ -0,0 +1,20 @@
+export interface McpToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const KG_MCP_TOOLS: McpToolDef[];
+export type KgStatus = 'ready' | 'stale' | 'uninitialized';
+export interface KgPrecheck {
+    status: KgStatus;
+    message: string;
+}
+export declare function precheckKg(projectPath: string): KgPrecheck;
+export declare function handleMcpTool(toolName: string, input: Record<string, unknown>, projectPath: string): Promise<{
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: boolean;
+}>;
+//# sourceMappingURL=mcp-tools.d.ts.map

package/dist/src/graph/kg/surface/mcp-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.d.ts","sourceRoot":"","sources":["../../../../../src/graph/kg/surface/mcp-tools.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,eAAO,MAAM,YAAY,EAAE,UAAU,EA4GpC,CAAC;AAMF,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,eAAe,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAS1D;AAMD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAwI/E"}

package/dist/src/graph/kg/surface/mcp-tools.js

@@ -0,0 +1,253 @@
+// src/graph/kg/surface/mcp-tools.ts — MCP Tool 定义
+// 参考: plan-maestrograph.md Gap C1 — 9 个 MCP 工具
+import { MaestroGraph } from '../engine.js';
+import { bfs, getCallers, getCallees, getImpactRadius, traceCallChain } from '../query/traversal.js';
+import { buildContext } from '../query/context-builder.js';
+import { getKgDatabasePath } from '../db/connection.js';
+import { existsSync } from 'node:fs';
+export const KG_MCP_TOOLS = [
+    {
+        name: 'maestro_kg_search',
+        description: 'Search across code symbols, domain terms, spec rules, and knowledge docs',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                sourceTypes: { type: 'array', items: { type: 'string' }, description: 'Filter by source type' },
+                nodeKinds: { type: 'array', items: { type: 'string' }, description: 'Filter by node kind' },
+                limit: { type: 'number', description: 'Max results', default: 20 },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'maestro_kg_context',
+        description: 'Get full context for a node including related code, specs, and domain knowledge',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                nodeId: { type: 'string', description: 'Node ID' },
+                depth: { type: 'number', description: 'Graph traversal depth', default: 1 },
+                includeCode: { type: 'boolean', description: 'Include source code', default: true },
+            },
+            required: ['nodeId'],
+        },
+    },
+    {
+        name: 'maestro_kg_explore',
+        description: 'Explore the unified knowledge graph for a task or question',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Natural language question' },
+                projectPath: { type: 'string', description: 'Project root path' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'maestro_kg_trace',
+        description: 'Trace call chain: A→B→C→D complete path',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                startSymbol: { type: 'string', description: 'Start symbol ID' },
+                endSymbol: { type: 'string', description: 'End symbol ID (optional)' },
+                maxDepth: { type: 'number', description: 'Max depth', default: 5 },
+                edgeKinds: { type: 'array', items: { type: 'string' }, description: 'Edge kind filter' },
+            },
+            required: ['startSymbol'],
+        },
+    },
+    {
+        name: 'maestro_kg_callers',
+        description: 'Find who calls this function (incoming calls edges)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: { type: 'string', description: 'Symbol ID' },
+                depth: { type: 'number', description: 'Recursive depth', default: 1 },
+                limit: { type: 'number', description: 'Max results' },
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'maestro_kg_callees',
+        description: 'Find what this function calls (outgoing calls edges)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: { type: 'string', description: 'Symbol ID' },
+                depth: { type: 'number', description: 'Recursive depth', default: 1 },
+                limit: { type: 'number', description: 'Max results' },
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'maestro_kg_impact',
+        description: 'Change impact analysis: what downstream is affected by modifying X',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: { type: 'string', description: 'Symbol being modified' },
+                maxDepth: { type: 'number', description: 'Impact propagation depth', default: 3 },
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'maestro_kg_files',
+        description: 'List indexed files with optional filters',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                language: { type: 'string', description: 'Filter by language' },
+                pattern: { type: 'string', description: 'Glob filter' },
+            },
+        },
+    },
+    {
+        name: 'maestro_kg_status',
+        description: 'Index status: node/edge/file counts, DB size, last update',
+        inputSchema: { type: 'object', properties: {} },
+    },
+];
+export function precheckKg(projectPath) {
+    const dbPath = getKgDatabasePath(projectPath);
+    if (!existsSync(dbPath)) {
+        return {
+            status: 'uninitialized',
+            message: 'MaestroGraph not initialized. Run: maestro kg init',
+        };
+    }
+    return { status: 'ready', message: '' };
+}
+// ---------------------------------------------------------------------------
+// MCP Tool Handler — 统一分发
+// ---------------------------------------------------------------------------
+export async function handleMcpTool(toolName, input, projectPath) {
+    const check = precheckKg(projectPath);
+    if (check.status === 'uninitialized' && toolName !== 'maestro_kg_status') {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `${check.message}\n\nQuick start:\n  1. maestro kg init\n  2. maestro kg sync\n  3. Re-call this tool`,
+                }],
+            isError: false,
+        };
+    }
+    try {
+        const mg = await MaestroGraph.open(projectPath);
+        try {
+            const queries = mg.getQueryBuilder();
+            const safeInt = (v, def, max) => Math.min(Math.max(1, typeof v === 'number' ? v : def), max);
+            const safeStr = (v, def) => typeof v === 'string' ? v.slice(0, 10_000) : def;
+            let result;
+            switch (toolName) {
+                case 'maestro_kg_search': {
+                    const searchOutput = mg.searchUnified(safeStr(input.query, ''), {
+                        sourceTypes: input.sourceTypes, // eslint-disable-line @typescript-eslint/no-explicit-any
+                        limit: safeInt(input.limit, 20, 100),
+                    });
+                    result = { results: searchOutput.directMatches.map(r => ({
+                            id: r.node.id, kind: r.node.kind, name: r.node.name, sourceType: r.node.sourceType,
+                            definition: r.node.definition.substring(0, 300),
+                            filePath: r.node.filePath, startLine: r.node.startLine, score: r.score,
+                        })), summary: searchOutput.summary };
+                    break;
+                }
+                case 'maestro_kg_context': {
+                    const nodeId = safeStr(input.nodeId, '');
+                    const node = mg.getNode(nodeId);
+                    if (!node) {
+                        result = { error: `Node not found: ${nodeId}` };
+                    }
+                    else {
+                        const traversal = bfs(queries, nodeId, {
+                            maxDepth: safeInt(input.depth, 1, 5),
+                            maxNodes: 50,
+                        });
+                        result = {
+                            node: { id: node.id, kind: node.kind, name: node.name, sourceType: node.sourceType, definition: node.definition },
+                            related: [...traversal.nodes.values()].filter(n => n.id !== nodeId).map(n => ({
+                                id: n.id, kind: n.kind, name: n.name, sourceType: n.sourceType,
+                            })),
+                            edges: traversal.edges.map(e => ({ source: e.source, target: e.target, kind: e.kind })),
+                        };
+                    }
+                    break;
+                }
+                case 'maestro_kg_explore': {
+                    const context = buildContext(queries, safeStr(input.query, ''), { expandDepth: 2 });
+                    result = {
+                        query: input.query,
+                        sections: context.sections.map(s => ({ label: s.label, lines: s.lines })),
+                        summary: context.summary,
+                    };
+                    break;
+                }
+                case 'maestro_kg_trace': {
+                    const traceResult = traceCallChain(queries, safeStr(input.startSymbol, ''), {
+                        maxDepth: safeInt(input.maxDepth, 5, 10),
+                        edgeKinds: input.edgeKinds,
+                    });
+                    result = {
+                        nodes: [...traceResult.nodes.values()].map(n => ({ id: n.id, kind: n.kind, name: n.name })),
+                        edges: traceResult.edges.map(e => ({ source: e.source, target: e.target, kind: e.kind })),
+                    };
+                    break;
+                }
+                case 'maestro_kg_callers': {
+                    const callerResults = getCallers(queries, safeStr(input.symbol, ''), safeInt(input.depth, 1, 5));
+                    result = callerResults.map(c => ({
+                        id: c.node.id, kind: c.node.kind, name: c.node.name, edgeKind: c.edge.kind,
+                    }));
+                    break;
+                }
+                case 'maestro_kg_callees': {
+                    const calleeResults = getCallees(queries, safeStr(input.symbol, ''), safeInt(input.depth, 1, 5));
+                    result = calleeResults.map(c => ({
+                        id: c.node.id, kind: c.node.kind, name: c.node.name, edgeKind: c.edge.kind,
+                    }));
+                    break;
+                }
+                case 'maestro_kg_impact': {
+                    const impactResult = getImpactRadius(queries, safeStr(input.symbol, ''), safeInt(input.maxDepth, 3, 10));
+                    result = {
+                        nodeCount: impactResult.nodes.size,
+                        edgeCount: impactResult.edges.length,
+                        nodes: [...impactResult.nodes.values()].map(n => ({ id: n.id, kind: n.kind, name: n.name })),
+                    };
+                    break;
+                }
+                case 'maestro_kg_files': {
+                    const stats = mg.getStats();
+                    result = { fileCount: stats.fileCount, filesByLanguage: {} };
+                    break;
+                }
+                case 'maestro_kg_status': {
+                    result = mg.getStats();
+                    break;
+                }
+                default:
+                    result = { error: `Unknown tool: ${toolName}` };
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                isError: false,
+            };
+        }
+        finally {
+            mg.close();
+        }
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=mcp-tools.js.map

package/dist/src/graph/kg/surface/mcp-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.js","sourceRoot":"","sources":["../../../../../src/graph/kg/surface/mcp-tools.ts"],"names":[],"mappings":"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"}

package/dist/src/graph/kg/sync/incremental-sync.d.ts

@@ -0,0 +1,24 @@
+import type { MaestroGraph } from '../engine.js';
+import type { SyncResult, SourceType } from '../db/types.js';
+export declare class FileLock {
+    private lockPath;
+    constructor(lockPath: string);
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+}
+export interface IncrementalSyncOptions {
+    /** 全量重建 */
+    full?: boolean;
+    /** 只同步指定源 */
+    sources?: SourceType[];
+    /** 变更文件列表 (增量模式) */
+    changedFiles?: string[];
+}
+/**
+ * 增量同步入口 — 协调知识源和代码源的同步
+ *
+ * D2.4: 知识源 (domain/spec/knowhow) 高优先级同步, 代码源异步后台
+ */
+export declare function runIncrementalSync(mg: MaestroGraph, projectPath: string, options?: IncrementalSyncOptions): Promise<SyncResult[]>;
+export declare function computeFileHash(filePath: string): string;
+export declare function hasFileChanged(filePath: string, storedHash: string): boolean;
+//# sourceMappingURL=incremental-sync.d.ts.map

package/dist/src/graph/kg/sync/incremental-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental-sync.d.ts","sourceRoot":"","sources":["../../../../../src/graph/kg/sync/incremental-sync.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAM7D,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAItB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAyBpD;AAMD,MAAM,WAAW,sBAAsB;IACrC,WAAW;IACX,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa;IACb,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,YAAY,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,UAAU,EAAE,CAAC,CAMvB;AAMD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAG5E"}

package/dist/src/graph/kg/sync/incremental-sync.js

@@ -0,0 +1,71 @@
+// src/graph/kg/sync/incremental-sync.ts — 增量同步
+// 参考: plan-maestrograph.md D2.4 同步优先级调度 + D1.4 FileLock
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// FileLock — D1.4: SQLite 跨进程写锁保护
+// ---------------------------------------------------------------------------
+export class FileLock {
+    lockPath;
+    constructor(lockPath) {
+        this.lockPath = lockPath;
+    }
+    async withLock(fn) {
+        // 简化版: 使用文件锁标记
+        // 生产环境应使用 proper file-lock (如 proper-lockfile)
+        const lockId = `${process.pid}-${Date.now()}`;
+        // 写锁文件
+        const { writeFileSync, unlinkSync } = await import('node:fs');
+        try {
+            writeFileSync(this.lockPath, lockId, { flag: 'wx' }); // 排他创建
+        }
+        catch {
+            // 锁已存在, 等待并重试
+            await new Promise(resolve => setTimeout(resolve, 100));
+            try {
+                writeFileSync(this.lockPath, lockId, { flag: 'wx' });
+            }
+            catch {
+                throw new Error('Could not acquire lock: ' + this.lockPath);
+            }
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            try {
+                unlinkSync(this.lockPath);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/**
+ * 增量同步入口 — 协调知识源和代码源的同步
+ *
+ * D2.4: 知识源 (domain/spec/knowhow) 高优先级同步, 代码源异步后台
+ */
+export async function runIncrementalSync(mg, projectPath, options) {
+    const { syncKnowledgeGraph } = await import('../extraction/orchestrator.js');
+    return syncKnowledgeGraph(projectPath, {
+        full: options?.full,
+        sources: options?.sources,
+    });
+}
+// ---------------------------------------------------------------------------
+// File hash diff — 检测文件变更
+// ---------------------------------------------------------------------------
+export function computeFileHash(filePath) {
+    try {
+        const content = readFileSync(filePath);
+        return createHash('sha256').update(content).digest('hex').substring(0, 16);
+    }
+    catch {
+        return '';
+    }
+}
+export function hasFileChanged(filePath, storedHash) {
+    const currentHash = computeFileHash(filePath);
+    return currentHash !== storedHash;
+}
+//# sourceMappingURL=incremental-sync.js.map

package/dist/src/graph/kg/sync/incremental-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental-sync.js","sourceRoot":"","sources":["../../../../../src/graph/kg/sync/incremental-sync.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,wDAAwD;AAExD,OAAO,EAAc,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAE9E,MAAM,OAAO,QAAQ;IACX,QAAQ,CAAS;IAEzB,YAAY,QAAgB;QAC1B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,QAAQ,CAAI,EAAoB;QACpC,eAAe;QACf,+CAA+C;QAC/C,MAAM,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAE9C,OAAO;QACP,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;YACd,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YACvD,IAAI,CAAC;gBACH,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACvD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC;gBAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;CACF;AAeD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,EAAgB,EAChB,WAAmB,EACnB,OAAgC;IAEhC,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;IAC7E,OAAO,kBAAkB,CAAC,WAAW,EAAE;QACrC,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,OAAO,EAAE,OAAO,EAAE,OAAO;KAC1B,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACvC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,UAAkB;IACjE,MAAM,WAAW,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC9C,OAAO,WAAW,KAAK,UAAU,CAAC;AACpC,CAAC"}