hyacinth-ai 0.9.6

package/dist/tools/xref/schema.js

@@ -0,0 +1,68 @@
+/**
+ * 交叉引用索引 — 类型定义与 SQLite Schema。
+ *
+ * 数据模型：
+ *   files   → 已索引的源文件
+ *   symbols → 符号定义（函数/类/接口/变量等）
+ *   refs    → 符号引用（调用/实例化/读取/继承/导入）
+ *   imports → 文件间导入依赖
+ *   meta    → 元数据（构建时间、项目根目录等）
+ */
+// ── SQLite Schema DDL ─────────────────────────────────────────────────
+export const SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS files (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    path TEXT UNIQUE NOT NULL,
+    language TEXT NOT NULL,
+    hash TEXT,
+    last_parsed_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS symbols (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+    line INTEGER NOT NULL,
+    col INTEGER NOT NULL DEFAULT 0,
+    signature TEXT,
+    is_exported INTEGER NOT NULL DEFAULT 0,
+    parent_name TEXT
+);
+
+CREATE TABLE IF NOT EXISTS refs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    symbol_name TEXT NOT NULL,
+    file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+    line INTEGER NOT NULL,
+    col INTEGER NOT NULL DEFAULT 0,
+    kind TEXT NOT NULL,
+    context TEXT,
+    caller_name TEXT
+);
+
+CREATE TABLE IF NOT EXISTS imports (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+    to_file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+    symbols TEXT DEFAULT '[]',
+    import_type TEXT DEFAULT 'static'
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key TEXT PRIMARY KEY,
+    value TEXT
+);
+
+-- 查询加速
+CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file_id);
+CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);
+CREATE INDEX IF NOT EXISTS idx_refs_symbol ON refs(symbol_name);
+CREATE INDEX IF NOT EXISTS idx_refs_file ON refs(file_id);
+CREATE INDEX IF NOT EXISTS idx_refs_kind ON refs(kind);
+CREATE INDEX IF NOT EXISTS idx_refs_caller ON refs(caller_name);
+CREATE INDEX IF NOT EXISTS idx_imports_from ON imports(from_file_id);
+CREATE INDEX IF NOT EXISTS idx_imports_to ON imports(to_file_id);
+`;
+//# sourceMappingURL=schema.js.map

package/dist/tools/xref/ts-parser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TypeScript/JavaScript AST 解析器。
+ *
+ * 使用 TypeScript 编译器 API（ts.createSourceFile + 递归 AST 遍历）
+ * 提取：函数/类/接口/类型/变量定义、调用/实例化/读取引用、导入依赖。
+ *
+ * 注册链：ParserRegistry → TsParser → ts.createSourceFile → AST walk
+ */
+import type { FileParser } from './parser.js';
+import type { ParsedFile } from './schema.js';
+export declare class TsParser implements FileParser {
+    readonly name = "ts-ast";
+    readonly extensions: string[];
+    parseFile(filePath: string): Promise<ParsedFile>;
+    private resolveCallee;
+    private hasExportModifier;
+    private isBuiltin;
+    private emptyResult;
+}
+//# sourceMappingURL=ts-parser.d.ts.map

package/dist/tools/xref/ts-parser.js

@@ -0,0 +1,403 @@
+/**
+ * TypeScript/JavaScript AST 解析器。
+ *
+ * 使用 TypeScript 编译器 API（ts.createSourceFile + 递归 AST 遍历）
+ * 提取：函数/类/接口/类型/变量定义、调用/实例化/读取引用、导入依赖。
+ *
+ * 注册链：ParserRegistry → TsParser → ts.createSourceFile → AST walk
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+// 动态加载 typescript（它是 devDependency，运行时可能不可用）
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let tsModule = null;
+async function loadTs() {
+    if (tsModule)
+        return tsModule;
+    try {
+        tsModule = await import('typescript');
+        return tsModule;
+    }
+    catch {
+        return null;
+    }
+}
+const TS_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+export class TsParser {
+    name = 'ts-ast';
+    extensions = TS_EXTS;
+    async parseFile(filePath) {
+        const ts = await loadTs();
+        if (!ts) {
+            // 回退：TypeScript compiler 不可用，返回空结果
+            return this.emptyResult(filePath, 'typescript');
+        }
+        const content = await fs.readFile(filePath, 'utf-8');
+        const hash = crypto.createHash('md5').update(content).digest('hex').slice(0, 12);
+        const ext = path.extname(filePath).toLowerCase();
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ext === '.tsx' || ext === '.jsx'
+            ? ts.ScriptKind.TSX
+            : ts.ScriptKind.TS);
+        const symbols = [];
+        const refs = [];
+        const imports = [];
+        // 当前遍历所在的函数/方法上下文（用于记录 caller_name）
+        const contextStack = [];
+        // 声明名称集合 — 跳过这些标识符的 read 记录（避免 const x = ... 中的 x 被记为读）
+        const declaredNames = new Set();
+        // 辅助：记录一个引用
+        const recordRef = (name, node, kind) => {
+            if (this.isBuiltin(name) || declaredNames.has(name))
+                return;
+            const pos = ts.getLineAndCharacterOfPosition(sourceFile, node.getStart(sourceFile));
+            const callerName = contextStack.length > 0 ? contextStack[contextStack.length - 1] : undefined;
+            refs.push({
+                symbol_name: name,
+                line: pos.line + 1,
+                col: pos.character,
+                kind,
+                context: node.getText(sourceFile).slice(0, 120),
+                caller_name: callerName,
+            });
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const visit = (node) => {
+            // ── 导入声明 ──
+            if (ts.isImportDeclaration(node)) {
+                const moduleSpecifier = node.moduleSpecifier;
+                if (ts.isStringLiteral(moduleSpecifier)) {
+                    const modulePath = moduleSpecifier.text;
+                    const symbols_list = [];
+                    const importClause = node.importClause;
+                    if (importClause) {
+                        if (importClause.name) {
+                            symbols_list.push(importClause.name.text);
+                        }
+                        if (importClause.namedBindings) {
+                            if (ts.isNamedImports(importClause.namedBindings)) {
+                                for (const el of importClause.namedBindings.elements) {
+                                    symbols_list.push(el.name.text);
+                                }
+                            }
+                            else if (ts.isNamespaceImport(importClause.namedBindings)) {
+                                symbols_list.push(importClause.namedBindings.name.text);
+                            }
+                        }
+                    }
+                    if (modulePath.startsWith('.')) {
+                        imports.push({
+                            to_path: modulePath,
+                            symbols: symbols_list,
+                            import_type: 'static',
+                        });
+                    }
+                }
+            }
+            // ── 函数声明 ──
+            if (ts.isFunctionDeclaration(node) && node.name) {
+                declaredNames.add(node.name.text);
+                const isExported = this.hasExportModifier(node, tsModule);
+                symbols.push({
+                    name: node.name.text,
+                    kind: 'function',
+                    line: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).line + 1,
+                    col: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).character,
+                    signature: node.getText(sourceFile).split('{')[0]?.trim() ?? undefined,
+                    is_exported: isExported,
+                });
+                // 进入函数体上下文
+                contextStack.push(node.name.text);
+                ts.forEachChild(node, visit);
+                contextStack.pop();
+                return; // 已递归处理子节点
+            }
+            // ── 类声明 ──
+            if (ts.isClassDeclaration(node) && node.name) {
+                declaredNames.add(node.name.text);
+                const isExported = this.hasExportModifier(node, tsModule);
+                const parentName = node.heritageClauses
+                    ?.flatMap((h) => h.types)
+                    .map((t) => t.expression.getText(sourceFile))
+                    .join(', ') || undefined;
+                symbols.push({
+                    name: node.name.text,
+                    kind: 'class',
+                    line: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).line + 1,
+                    col: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).character,
+                    signature: `class ${node.name.text}${parentName ? ` extends ${parentName}` : ''}`,
+                    is_exported: isExported,
+                });
+                // 记录继承引用
+                if (node.heritageClauses) {
+                    for (const clause of node.heritageClauses) {
+                        for (const type of clause.types) {
+                            const refName = type.expression.getText(sourceFile);
+                            const pos = ts.getLineAndCharacterOfPosition(sourceFile, type.expression.getStart(sourceFile));
+                            refs.push({
+                                symbol_name: refName,
+                                line: pos.line + 1,
+                                col: pos.character,
+                                kind: 'inherit',
+                                context: type.getText(sourceFile),
+                                caller_name: node.name.text,
+                            });
+                        }
+                    }
+                }
+                contextStack.push(node.name.text);
+                ts.forEachChild(node, visit);
+                contextStack.pop();
+                return;
+            }
+            // ── 方法 / 属性声明 ──
+            if (ts.isMethodDeclaration(node) && node.name) {
+                const methodName = ts.isIdentifier(node.name) ? node.name.text : '[computed]';
+                if (methodName !== '[computed]') {
+                    declaredNames.add(methodName);
+                    symbols.push({
+                        name: methodName,
+                        kind: 'method',
+                        line: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).line + 1,
+                        col: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).character,
+                        signature: node.getText(sourceFile).split('{')[0]?.trim() ?? undefined,
+                        is_exported: false,
+                        parent_name: contextStack.length > 0 ? contextStack[contextStack.length - 1] : undefined,
+                    });
+                }
+                contextStack.push(methodName);
+                ts.forEachChild(node, visit);
+                contextStack.pop();
+                return;
+            }
+            // ── 属性声明（类成员变量） ──
+            if (ts.isPropertyDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
+                declaredNames.add(node.name.text);
+                symbols.push({
+                    name: node.name.text,
+                    kind: 'property',
+                    line: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).line + 1,
+                    col: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).character,
+                    is_exported: false,
+                    parent_name: contextStack.length > 0 ? contextStack[contextStack.length - 1] : undefined,
+                });
+            }
+            // ── 变量声明（含箭头函数、函数表达式） ──
+            if (ts.isVariableStatement(node)) {
+                const isExported = this.hasExportModifier(node, tsModule);
+                for (const decl of node.declarationList.declarations) {
+                    if (ts.isIdentifier(decl.name)) {
+                        const varName = decl.name.text;
+                        declaredNames.add(varName);
+                        let kind = 'variable';
+                        if (decl.initializer) {
+                            if (ts.isFunctionExpression(decl.initializer) || ts.isArrowFunction(decl.initializer)) {
+                                kind = 'arrow';
+                            }
+                            else if (ts.isClassExpression(decl.initializer)) {
+                                kind = 'class';
+                            }
+                        }
+                        symbols.push({
+                            name: varName,
+                            kind,
+                            line: ts.getLineAndCharacterOfPosition(sourceFile, decl.name.getStart(sourceFile)).line + 1,
+                            col: ts.getLineAndCharacterOfPosition(sourceFile, decl.name.getStart(sourceFile)).character,
+                            signature: decl.getText(sourceFile).split('=')[0]?.trim() ?? undefined,
+                            is_exported: isExported,
+                        });
+                        // 对箭头函数/函数表达式，进入函数体上下文
+                        if (kind === 'arrow' && decl.initializer) {
+                            contextStack.push(varName);
+                            ts.forEachChild(decl.initializer, visit);
+                            contextStack.pop();
+                            // 跳过默认的递归遍历（避免重复）
+                            // 继续处理其他声明
+                            continue;
+                        }
+                    }
+                }
+            }
+            // ── 接口声明 ──
+            if (ts.isInterfaceDeclaration(node) && node.name) {
+                declaredNames.add(node.name.text);
+                const isExported = this.hasExportModifier(node, tsModule);
+                const extendsList = node.heritageClauses
+                    ?.flatMap((h) => h.types)
+                    .map((t) => t.expression.getText(sourceFile))
+                    .join(', ');
+                symbols.push({
+                    name: node.name.text,
+                    kind: 'interface',
+                    line: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).line + 1,
+                    col: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).character,
+                    signature: `interface ${node.name.text}${extendsList ? ` extends ${extendsList}` : ''}`,
+                    is_exported: isExported,
+                });
+                // 继承引用
+                if (node.heritageClauses) {
+                    for (const clause of node.heritageClauses) {
+                        for (const type of clause.types) {
+                            const refName = type.expression.getText(sourceFile);
+                            const pos = ts.getLineAndCharacterOfPosition(sourceFile, type.expression.getStart(sourceFile));
+                            refs.push({
+                                symbol_name: refName,
+                                line: pos.line + 1,
+                                col: pos.character,
+                                kind: 'inherit',
+                                context: type.getText(sourceFile),
+                                caller_name: node.name.text,
+                            });
+                        }
+                    }
+                }
+                return; // 接口体内没有可执行代码
+            }
+            // ── 类型别名 ──
+            if (ts.isTypeAliasDeclaration(node) && node.name) {
+                declaredNames.add(node.name.text);
+                const isExported = this.hasExportModifier(node, tsModule);
+                symbols.push({
+                    name: node.name.text,
+                    kind: 'type',
+                    line: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).line + 1,
+                    col: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).character,
+                    signature: `type ${node.name.text}`,
+                    is_exported: isExported,
+                });
+                return;
+            }
+            // ── 枚举声明 ──
+            if (ts.isEnumDeclaration(node) && node.name) {
+                declaredNames.add(node.name.text);
+                const isExported = this.hasExportModifier(node, tsModule);
+                symbols.push({
+                    name: node.name.text,
+                    kind: 'enum',
+                    line: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).line + 1,
+                    col: ts.getLineAndCharacterOfPosition(sourceFile, node.name.getStart(sourceFile)).character,
+                    signature: `enum ${node.name.text}`,
+                    is_exported: isExported,
+                });
+                return;
+            }
+            // ── 调用表达式 ──
+            if (ts.isCallExpression(node)) {
+                const callee = this.resolveCallee(node.expression, sourceFile);
+                if (callee && !this.isBuiltin(callee)) {
+                    const pos = ts.getLineAndCharacterOfPosition(sourceFile, node.expression.getStart(sourceFile));
+                    const callerName = contextStack.length > 0 ? contextStack[contextStack.length - 1] : undefined;
+                    refs.push({
+                        symbol_name: callee,
+                        line: pos.line + 1,
+                        col: pos.character,
+                        kind: 'call',
+                        context: node.getText(sourceFile).slice(0, 120),
+                        caller_name: callerName,
+                    });
+                }
+            }
+            // ── new 表达式 ──
+            if (ts.isNewExpression(node) && node.expression) {
+                const callee = ts.isIdentifier(node.expression) ? node.expression.text : undefined;
+                if (callee && !this.isBuiltin(callee)) {
+                    const pos = ts.getLineAndCharacterOfPosition(sourceFile, node.expression.getStart(sourceFile));
+                    refs.push({
+                        symbol_name: callee,
+                        line: pos.line + 1,
+                        col: pos.character,
+                        kind: 'new',
+                        context: node.getText(sourceFile).slice(0, 120),
+                        caller_name: contextStack.length > 0 ? contextStack[contextStack.length - 1] : undefined,
+                    });
+                }
+            }
+            // ── 赋值表达式（写变量）──
+            if (ts.isBinaryExpression(node)) {
+                const op = node.operatorToken?.kind;
+                // = , += , -= , *= , /= 等赋值操作符
+                if (op === ts.SyntaxKind.EqualsToken ||
+                    op === ts.SyntaxKind.PlusEqualsToken ||
+                    op === ts.SyntaxKind.MinusEqualsToken ||
+                    op === ts.SyntaxKind.AsteriskEqualsToken ||
+                    op === ts.SyntaxKind.SlashEqualsToken) {
+                    if (ts.isIdentifier(node.left)) {
+                        recordRef(node.left.text, node, 'write');
+                    }
+                }
+            }
+            // ── 前缀/后缀自增自减（写变量）──
+            if (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) {
+                if (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                    node.operator === ts.SyntaxKind.MinusMinusToken) {
+                    if (ts.isIdentifier(node.operand)) {
+                        recordRef(node.operand.text, node, 'write');
+                    }
+                }
+            }
+            // ── 标识符引用（读变量）──
+            // 放在所有声明/特殊节点处理后，只记录在表达式位置出现的纯标识符
+            if (ts.isIdentifier(node)) {
+                recordRef(node.text, node, 'read');
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        return {
+            path: filePath,
+            language: ext === '.ts' || ext === '.tsx' || ext === '.mts' || ext === '.cts' ? 'typescript' : 'javascript',
+            symbols,
+            refs,
+            imports,
+            hash,
+        };
+    }
+    // ── 辅助方法 ──
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    resolveCallee(expr, _sourceFile) {
+        if (!tsModule)
+            return undefined;
+        if (tsModule.isIdentifier(expr)) {
+            return expr.text;
+        }
+        if (tsModule.isPropertyAccessExpression(expr)) {
+            // obj.method() → method
+            return expr.name.text;
+        }
+        return undefined;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    hasExportModifier(node, tsApi) {
+        if (!tsApi.canHaveModifiers(node))
+            return false;
+        const modifiers = tsApi.getModifiers(node);
+        if (!modifiers)
+            return false;
+        return modifiers.some((m) => m.kind === tsApi.SyntaxKind.ExportKeyword
+            || m.kind === tsApi.SyntaxKind.DefaultKeyword
+            || m.kind === tsApi.SyntaxKind.DeclareKeyword);
+    }
+    isBuiltin(name) {
+        const builtins = new Set([
+            'console', 'require', 'setTimeout', 'setInterval', 'clearTimeout',
+            'clearInterval', 'parseInt', 'parseFloat', 'isNaN', 'isFinite',
+            'JSON', 'Math', 'Object', 'Array', 'String', 'Number', 'Boolean',
+            'Promise', 'Map', 'Set', 'Error', 'Date', 'RegExp', 'Symbol',
+            'Reflect', 'Proxy', 'Buffer', 'process', 'global', 'globalThis',
+            'undefined', 'eval', 'decodeURI', 'encodeURI', 'decodeURIComponent',
+            'encodeURIComponent',
+        ]);
+        return builtins.has(name) || name.startsWith('_') || name.length <= 1;
+    }
+    emptyResult(filePath, language) {
+        return {
+            path: filePath,
+            language,
+            symbols: [],
+            refs: [],
+            imports: [],
+            hash: '',
+        };
+    }
+}
+//# sourceMappingURL=ts-parser.js.map

package/dist/tools/xref/xref-build.d.ts

@@ -0,0 +1,20 @@
+/**
+ * xref_build — 构建/清理交叉引用索引。
+ *
+ * 扫描项目源码，使用 AST 解析器解析，存入 SQLite 索引数据库。
+ * 支持全量构建、增量更新、目录过滤、数据库删除。
+ *
+ * 注册链：
+ *   factory.ts → new XrefBuildTool(manager) → toolRegistry.register()
+ */
+import type { Tool } from '../interface.js';
+import type { XrefManager } from './manager.js';
+export declare class XrefBuildTool implements Tool {
+    readonly name = "xref_build";
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    private manager;
+    constructor(manager: XrefManager);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=xref-build.d.ts.map

package/dist/tools/xref/xref-build.js

@@ -0,0 +1,128 @@
+/**
+ * xref_build — 构建/清理交叉引用索引。
+ *
+ * 扫描项目源码，使用 AST 解析器解析，存入 SQLite 索引数据库。
+ * 支持全量构建、增量更新、目录过滤、数据库删除。
+ *
+ * 注册链：
+ *   factory.ts → new XrefBuildTool(manager) → toolRegistry.register()
+ */
+export class XrefBuildTool {
+    name = 'xref_build';
+    description = 'Build or manage the cross-reference index for the project. ' +
+        'Scans source files with AST parsers and stores symbol definitions, references, ' +
+        'and import dependencies into a SQLite database. ' +
+        'Must be called once before xref_query or xref_graph can be used.\n\n' +
+        'Modes:\n' +
+        '  1. Full build (default): scans all source files in the project\n' +
+        '  2. directory-filtered build: pass "directories" to limit scan to specific dirs\n' +
+        '  3. Incremental update: pass "files" to re-index only changed files\n' +
+        '  4. Clean: pass clean=true to delete the index database (next query will require rebuild)';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            directories: {
+                type: 'string',
+                description: 'Optional JSON array of directory paths (relative to project root) to limit the scan. ' +
+                    'Example: ["src/tools", "src/gateway"]. If omitted, scans the entire project.',
+            },
+            files: {
+                type: 'string',
+                description: 'Optional JSON array of file paths to incrementally re-index. ' +
+                    'If omitted or empty, performs a full rebuild. ' +
+                    'Example: ["src/tools/xref.ts", "src/gateway/factory.ts"]',
+            },
+            clean: {
+                type: 'boolean',
+                description: 'If true, deletes the current project\'s xref index database entirely. ' +
+                    'Use this to reclaim disk space for old projects or force a fresh rebuild. ' +
+                    'No other action is performed when clean is true.',
+            },
+            project: {
+                type: 'string',
+                description: 'Optional project path for "clean" action. ' +
+                    'If provided with clean=true, deletes the xref database for the specified project instead of the current one. ' +
+                    'Can be an absolute path or a project name/key.',
+            },
+        },
+        required: [],
+    };
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    async execute(args) {
+        const clean = args.clean;
+        const project = args.project;
+        // ── clean 模式：删除数据库 ──
+        if (clean) {
+            return this.manager.deleteDatabase(project);
+        }
+        // ── build 模式 ──
+        if (!this.manager.isReady()) {
+            return 'Error: XrefManager not initialized. The session may not have a project directory.';
+        }
+        // 解析 directories 参数
+        const dirsRaw = args.directories;
+        let dirs;
+        if (dirsRaw) {
+            try {
+                dirs = JSON.parse(dirsRaw);
+                if (!Array.isArray(dirs)) {
+                    return 'Error: "directories" must be a JSON array of directory paths.';
+                }
+            }
+            catch {
+                return 'Error: "directories" must be a valid JSON array string.';
+            }
+        }
+        // 解析 files 参数
+        const filesRaw = args.files;
+        let changedFiles;
+        if (filesRaw) {
+            try {
+                changedFiles = JSON.parse(filesRaw);
+                if (!Array.isArray(changedFiles)) {
+                    return 'Error: "files" must be a JSON array of file paths.';
+                }
+            }
+            catch {
+                return 'Error: "files" must be a valid JSON array string.';
+            }
+        }
+        const isIncremental = changedFiles && changedFiles.length > 0;
+        const isFiltered = dirs && dirs.length > 0;
+        let modeLabel;
+        if (isIncremental) {
+            modeLabel = `incremental (${changedFiles.length} files)`;
+        }
+        else if (isFiltered) {
+            modeLabel = `filtered (${dirs.length} dirs: ${dirs.join(', ')})`;
+        }
+        else {
+            modeLabel = 'full';
+        }
+        try {
+            const stats = await this.manager.build(changedFiles, dirs);
+            const lines = [];
+            lines.push(`✅ Cross-reference index built successfully (${modeLabel}).`);
+            lines.push('');
+            lines.push(`  Files indexed:   ${stats.files}`);
+            lines.push(`  Symbols found:   ${stats.symbols}`);
+            lines.push(`  References:      ${stats.refs}`);
+            lines.push(`  Import edges:    ${stats.imports}`);
+            lines.push(`  Duration:        ${stats.duration_ms}ms`);
+            if (Object.keys(stats.language_breakdown).length > 0) {
+                lines.push('  Language breakdown:');
+                for (const [lang, count] of Object.entries(stats.language_breakdown)) {
+                    lines.push(`    ${lang}: ${count} files`);
+                }
+            }
+            return lines.join('\n');
+        }
+        catch (err) {
+            return `Error building index: ${err.message}`;
+        }
+    }
+}
+//# sourceMappingURL=xref-build.js.map

package/dist/tools/xref/xref-graph.d.ts

@@ -0,0 +1,24 @@
+/**
+ * xref_graph — 可视化调用图/依赖图。
+ *
+ * 将交叉引用关系输出为：
+ *   - text:    缩进文本树（├── └── 风格）
+ *   - mermaid: Mermaid.js 流程图（可在 Markdown 中渲染）
+ *   - graphviz: Graphviz DOT 格式
+ *
+ * 需要先运行 xref_build 构建索引。
+ *
+ * 注册链：
+ *   factory.ts → new XrefGraphTool(manager) → toolRegistry.register()
+ */
+import type { Tool } from '../interface.js';
+import type { XrefManager } from './manager.js';
+export declare class XrefGraphTool implements Tool {
+    readonly name = "xref_graph";
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    private manager;
+    constructor(manager: XrefManager);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=xref-graph.d.ts.map