hyacinth-ai 0.9.6

package/dist/tools/symbol-references.d.ts

@@ -0,0 +1,5 @@
+export interface ReferenceResult {
+    text: string;
+}
+export declare function autoReferenceCheck(filePath: string, fileContent: string, oldString: string, newString: string): ReferenceResult;
+//# sourceMappingURL=symbol-references.d.ts.map

package/dist/tools/symbol-references.js

@@ -0,0 +1,331 @@
+// ============================================================
+// SymbolReferences — 编辑后自动引用搜索
+// ============================================================
+//
+// edit/write 工具执行成功后自动调用，提取变更涉及的符号名，
+// 在项目内搜索外部引用，追加到工具返回值。
+//
+// 探测项目根目录：被编辑文件向上找 .git → package.json → ... → 退出目录
+// 符号提取：根据文件后缀匹配语言，正则提取声明（函数/类/变量/类型）
+// 未提取到时 fallback：文件内向上回溯最近的外层函数/类
+// ============================================================
+import fs from 'node:fs';
+import path from 'node:path';
+// ── 目录标记（按优先级）──────────────────────────────────────
+const PROJECT_MARKERS = ['.git', 'package.json', 'tsconfig.json', 'go.mod', 'Cargo.toml', 'pyproject.toml', 'Makefile', 'CMakeLists.txt'];
+// ── 排除目录 ─────────────────────────────────────────────────
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', '.next', 'build', '__pycache__',
+    '.venv', 'vendor', 'target', '.turbo', 'coverage', '.nyc_output',
+    'cmake-build-', // CMake build dirs (prefix match below)
+]);
+// ── 通用忽略关键字（所有语言共享）─────────────────────────────
+const BASE_IGNORED = new Set([
+    // 单字母 / 极短
+    'i', 'j', 'k', 'x', 'y', 'z',
+    // 通用编程关键字
+    'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'break', 'continue',
+    'return', 'throw', 'try', 'catch', 'finally', 'new', 'delete',
+    'true', 'false', 'null', 'undefined', 'nil', 'None', 'True', 'False',
+    'import', 'from', 'as', 'async', 'await',
+    'public', 'private', 'protected', 'static', 'readonly', 'abstract',
+    'get', 'set', 'constructor', 'destructor',
+    // 通用变量名
+    'props', 'state', 'ref', 'args', 'result', 'data', 'value', 'error', 'err',
+    'res', 'req', 'item', 'index', 'tmp', 'temp', 'ctx', 'obj', 'self', 'this',
+    'super', 'other', 'key', 'val', 'msg', 'name', 'type', 'size', 'len',
+]);
+const ALL_LANGUAGES = {};
+function defineLang(exts, declPatterns, extraIgnored, skipLinePrefixes) {
+    const config = {
+        srcExts: new Set(exts),
+        declPatterns,
+        extraIgnored: new Set(extraIgnored),
+        skipLinePrefixes,
+    };
+    for (const ext of exts) {
+        ALL_LANGUAGES[ext] = config;
+    }
+}
+// ── TypeScript / JavaScript ───────────────────────────────────
+defineLang(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'], [
+    { pattern: /(?:export\s+)?(?:async\s+)?function\s+(\w+)/g, label: 'fn' },
+    { pattern: /(?:export\s+)?class\s+(\w+)/g, label: 'class' },
+    { pattern: /(?:export\s+)?interface\s+(\w+)/g, label: 'interface' },
+    { pattern: /(?:export\s+)?type\s+(\w+)\s*=/g, label: 'type' },
+    { pattern: /(?:export\s+)?enum\s+(\w+)/g, label: 'enum' },
+    { pattern: /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*[:=]/g, label: 'var' },
+], [
+    'typeof', 'instanceof', 'void', 'default', 'export', 'yield',
+    'implements', 'extends', 'declare', 'namespace', 'module', 'require',
+    'keyof', 'infer', 'is', 'of', 'in',
+    'console', 'log', 'warn', 'error', 'info', 'debug',
+    'map', 'filter', 'reduce', 'forEach', 'push', 'pop', 'shift', 'unshift',
+    'slice', 'splice', 'find', 'some', 'every', 'sort', 'reverse',
+    'join', 'split', 'trim', 'replace', 'match',
+], ['import', '//', '*']);
+// ── Python ────────────────────────────────────────────────────
+defineLang(['.py', '.pyx', '.pxd'], [
+    { pattern: /(?:async\s+)?def\s+(\w+)/g, label: 'fn' },
+    { pattern: /class\s+(\w+)/g, label: 'class' },
+    // 模块级变量赋值（顶格或 0-2 缩进，避免函数内部变量）
+    { pattern: /^ {0,8}(\w+)\s*=\s*(?![=])/gm, label: 'var' },
+], [
+    'pass', 'yield', 'raise', 'with', 'except', 'lambda', 'global',
+    'nonlocal', 'assert', 'del', 'print', 'open', 'range', 'enumerate',
+    'zip', 'len', 'int', 'str', 'float', 'list', 'dict', 'set', 'tuple',
+    'bool', 'type', 'object', 'isinstance', 'hasattr', 'getattr', 'setattr',
+    'super', 'init', 'call', 'repr', 'iter', 'next',
+    '__init__', '__str__', '__repr__', '__call__', '__getitem__', '__setitem__',
+    '__len__', '__iter__', '__next__', '__enter__', '__exit__',
+], ['import', 'from', '#', '"""', "'''"]);
+// ── Go ────────────────────────────────────────────────────────
+defineLang(['.go'], [
+    { pattern: /func\s+(?:\(\w+\s+\*?\w+\)\s+)?(\w+)/g, label: 'fn' },
+    { pattern: /type\s+(\w+)\s+(?:struct|interface)/g, label: 'type' },
+    { pattern: /var\s+(\w+)/g, label: 'var' },
+    { pattern: /const\s+(\w+)/g, label: 'const' },
+], [
+    'func', 'type', 'var', 'const', 'package', 'import', 'go', 'defer',
+    'chan', 'select', 'range', 'fallthrough', 'goto', 'interface', 'struct',
+    'map', 'string', 'int', 'int8', 'int16', 'int32', 'int64',
+    'uint', 'uint8', 'uint16', 'uint32', 'uint64',
+    'float32', 'float64', 'complex64', 'complex128', 'bool', 'byte', 'rune',
+    'error', 'make', 'append', 'copy', 'close', 'delete', 'panic', 'recover',
+    'len', 'cap', 'fmt', 'Println', 'Printf', 'Sprintf', 'Errorf',
+    'main', 'init',
+], ['import', '//', '/*']);
+// ── Rust ──────────────────────────────────────────────────────
+defineLang(['.rs'], [
+    { pattern: /fn\s+(\w+)/g, label: 'fn' },
+    { pattern: /struct\s+(\w+)/g, label: 'struct' },
+    { pattern: /enum\s+(\w+)/g, label: 'enum' },
+    { pattern: /trait\s+(\w+)/g, label: 'trait' },
+    { pattern: /impl\s+(?:\w+\s+for\s+)?(\w+)/g, label: 'impl' },
+    { pattern: /type\s+(\w+)\s*=/g, label: 'type' },
+    { pattern: /(?:pub\s+)?const\s+(\w+)/g, label: 'const' },
+    { pattern: /(?:pub\s+)?static\s+(?:mut\s+)?(\w+)/g, label: 'static' },
+], [
+    'fn', 'struct', 'enum', 'trait', 'impl', 'const', 'static', 'mut',
+    'pub', 'crate', 'mod', 'use', 'where', 'dyn', 'ref', 'move',
+    'u8', 'u16', 'u32', 'u64', 'u128', 'usize',
+    'i8', 'i16', 'i32', 'i64', 'i128', 'isize',
+    'f32', 'f64', 'bool', 'char', 'str', 'String',
+    'Vec', 'Option', 'Result', 'Some', 'None', 'Ok', 'Err',
+    'Box', 'Rc', 'Arc', 'Cell', 'RefCell', 'Mutex',
+    'self', 'Self', 'macro_rules', 'derive', 'clone', 'copy',
+    'println', 'format', 'unwrap', 'expect', 'main',
+], ['use', '//', '/*', '///', '//!']);
+// ── C ─────────────────────────────────────────────────────────
+defineLang(['.c', '.h'], [
+    // 函数声明/定义：返回类型 + 函数名
+    { pattern: /(?:\w+\s+)+(\w+)\s*\([^)]*\)\s*\{?/gm, label: 'fn' },
+    // struct / enum / union 声明
+    { pattern: /(?:typedef\s+)?struct\s+(\w+)/g, label: 'struct' },
+    { pattern: /(?:typedef\s+)?enum\s+(\w+)/g, label: 'enum' },
+    { pattern: /(?:typedef\s+)?union\s+(\w+)/g, label: 'union' },
+    // typedef
+    { pattern: /typedef\s+(?:\w+\s+)+(\w+)\s*;/g, label: 'typedef' },
+    // #define 宏
+    { pattern: /#define\s+(\w+)/g, label: 'define' },
+], [
+    'void', 'char', 'short', 'int', 'long', 'float', 'double',
+    'signed', 'unsigned', 'const', 'volatile', 'register', 'extern',
+    'sizeof', 'typedef', 'struct', 'enum', 'union',
+    'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'break', 'continue',
+    'return', 'goto', 'default', 'NULL',
+    'int8_t', 'int16_t', 'int32_t', 'int64_t',
+    'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t',
+    'size_t', 'ssize_t', 'ptrdiff_t', 'FILE',
+    'printf', 'fprintf', 'sprintf', 'snprintf',
+    'scanf', 'fscanf', 'sscanf',
+    'malloc', 'calloc', 'realloc', 'free',
+    'memcpy', 'memset', 'memmove', 'memcmp',
+    'strcpy', 'strncpy', 'strlen', 'strcmp', 'strncmp',
+    'open', 'close', 'read', 'write', 'main',
+    'assert', 'exit',
+], ['#include', '//', '/*']);
+// ── 项目根目录探测 ───────────────────────────────────────────
+function findProjectRoot(filePath) {
+    let dir = path.dirname(path.resolve(filePath));
+    // 先找 .git
+    let current = dir;
+    while (true) {
+        if (fs.existsSync(path.join(current, '.git'))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // 没 .git 找其他项目标记
+    current = dir;
+    while (true) {
+        for (const marker of PROJECT_MARKERS) {
+            if (fs.existsSync(path.join(current, marker))) {
+                return current;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // 什么都没有，退回文件所在目录
+    return dir;
+}
+// ── 语言检测 ─────────────────────────────────────────────────
+function detectLang(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return ALL_LANGUAGES[ext] ?? null;
+}
+// ── 符号提取 ─────────────────────────────────────────────────
+function extractSymbols(text, lang) {
+    const symbols = new Set();
+    const ignored = lang.extraIgnored;
+    for (const { pattern } of lang.declPatterns) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const name = match[1];
+            if (name.length >= 2 && !BASE_IGNORED.has(name) && !ignored.has(name)) {
+                symbols.add(name);
+            }
+        }
+    }
+    return [...symbols];
+}
+// ── 外层符号回溯 ─────────────────────────────────────────────
+function findEnclosingSymbol(fileContent, searchStr, lang) {
+    const idx = fileContent.indexOf(searchStr);
+    if (idx === -1)
+        return null;
+    const before = fileContent.slice(0, idx).split('\n').reverse();
+    const ignored = lang.extraIgnored;
+    for (const line of before) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // 跳过注释行和 import/use/include
+        if (lang.skipLinePrefixes.some(p => trimmed.startsWith(p)))
+            continue;
+        for (const { pattern } of lang.declPatterns) {
+            pattern.lastIndex = 0;
+            const match = pattern.exec(trimmed);
+            if (match) {
+                const name = match[1];
+                if (name.length >= 2 && !BASE_IGNORED.has(name) && !ignored.has(name)) {
+                    return name;
+                }
+            }
+        }
+    }
+    return null;
+}
+// ── 引用扫描 ─────────────────────────────────────────────────
+function scanReferences(projectRoot, symbols, excludeFile, srcExts, maxFiles) {
+    const results = new Map();
+    const resolvedExclude = path.resolve(excludeFile);
+    let scanned = 0;
+    function walk(dir) {
+        if (scanned >= maxFiles)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (scanned >= maxFiles)
+                return;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                    continue;
+                // CMake build dirs
+                if (entry.name.startsWith('cmake-build-'))
+                    continue;
+                walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (!srcExts.has(ext))
+                    continue;
+                if (path.resolve(fullPath) === resolvedExclude)
+                    continue;
+                scanned++;
+                try {
+                    const content = fs.readFileSync(fullPath, 'utf-8');
+                    for (const sym of symbols) {
+                        if (content.includes(sym)) {
+                            let entry = results.get(sym);
+                            if (!entry) {
+                                entry = { files: [], total: 0 };
+                                results.set(sym, entry);
+                            }
+                            entry.total++;
+                            if (entry.files.length < 8) {
+                                entry.files.push(path.relative(projectRoot, fullPath));
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // 读取失败跳过
+                }
+            }
+        }
+    }
+    walk(projectRoot);
+    return results;
+}
+export function autoReferenceCheck(filePath, fileContent, oldString, newString) {
+    try {
+        // 1. 检测语言
+        const lang = detectLang(filePath);
+        if (!lang)
+            return { text: '' };
+        // 2. 检测项目根目录
+        const projectRoot = findProjectRoot(filePath);
+        // 3. 提取符号：先从改动文本，再 fallback 外层符号
+        const changedText = oldString + '\n' + newString;
+        let symbols = extractSymbols(changedText, lang);
+        if (symbols.length === 0) {
+            const enclosing = findEnclosingSymbol(fileContent, oldString, lang);
+            if (enclosing)
+                symbols = [enclosing];
+        }
+        if (symbols.length === 0)
+            return { text: '' };
+        // 最多 3 个符号
+        symbols = symbols.slice(0, 3);
+        // 4. 扫描引用（只扫描同语言的文件）
+        const refs = scanReferences(projectRoot, symbols, filePath, lang.srcExts, 500);
+        if (refs.size === 0)
+            return { text: '' };
+        // 5. 格式化
+        const lines = ['[References]'];
+        for (const sym of symbols) {
+            const entry = refs.get(sym);
+            if (!entry || entry.total === 0)
+                continue;
+            const fileList = entry.files.join(', ');
+            if (entry.total > entry.files.length) {
+                lines.push(`  ${sym} → ${fileList}, ... (${entry.total} 个引用中还有 ${entry.total - entry.files.length} 个未列出，用 grep 查看全部)`);
+            }
+            else {
+                lines.push(`  ${sym} → ${fileList}`);
+            }
+        }
+        if (lines.length === 1)
+            return { text: '' };
+        return { text: lines.join('\n') };
+    }
+    catch {
+        return { text: '' };
+    }
+}
+//# sourceMappingURL=symbol-references.js.map

package/dist/tools/system-info.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from './interface.js';
+export declare function createSystemInfoTool(): Tool;
+//# sourceMappingURL=system-info.d.ts.map

package/dist/tools/system-info.js

@@ -0,0 +1,55 @@
+import { collectSystemInfo } from '../env/env-collector.js';
+let cachedInfo = null;
+function formatSystemInfo(info, categories) {
+    const all = !categories || categories.length === 0 || categories.includes('all');
+    const want = (k) => all || categories.includes(k);
+    const lines = ['System Environment:'];
+    if (want('os')) {
+        lines.push(`- OS: ${info.os} (${info.arch})`);
+    }
+    if (want('cpu')) {
+        lines.push(`- CPU: ${info.cpuModel} (${info.cpuCores} cores)`);
+    }
+    if (want('memory')) {
+        lines.push(`- Memory: ${info.totalMemoryGB} GB`);
+    }
+    if (want('gpu')) {
+        lines.push(`- GPU: ${info.gpu}`);
+    }
+    if (want('python')) {
+        lines.push(`- Python: ${info.python}`);
+    }
+    if (want('node')) {
+        lines.push(`- Node.js: ${info.nodeVersion}`);
+    }
+    if (want('shell')) {
+        lines.push(`- Shell: ${info.shell}`);
+    }
+    return lines.join('\n');
+}
+export function createSystemInfoTool() {
+    return {
+        name: 'system_info',
+        description: 'Query current system environment: OS, CPU, memory, GPU, Python/Node.js version, shell. Use when writing cross-platform code, tuning performance, or installing dependencies.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                categories: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: ['os', 'cpu', 'memory', 'gpu', 'python', 'node', 'shell', 'all'],
+                    },
+                    description: 'Categories to query. Default: all.',
+                },
+            },
+        },
+        async execute(args) {
+            if (!cachedInfo) {
+                cachedInfo = collectSystemInfo();
+            }
+            return formatSystemInfo(cachedInfo, args.categories);
+        },
+    };
+}
+//# sourceMappingURL=system-info.js.map

package/dist/tools/write.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from './interface.js';
+/**
+ * WriteTool — 创建或覆盖文件
+ *
+ * 参数：
+ * - file_path (必需): 文件的绝对路径
+ * - content (必需): 要写入的文件内容
+ *
+ * 自动创建父目录（如果不存在），返回确认信息（文件路径和行数）
+ */
+export declare class WriteTool implements Tool {
+    readonly name = "write";
+    readonly description = "Create or overwrite a file. Creates parent directories automatically.";
+    readonly companionDescription = "\u5199\u4E1C\u897F\u55BD\u3002";
+    readonly inputSchema: Record<string, unknown>;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=write.d.ts.map

package/dist/tools/write.js

@@ -0,0 +1,118 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { computeDiff } from '../utils/diff.js';
+import { pushDiff } from './diff-channel.js';
+import { getLastReadTime, recordFileWrite } from './file-tracker.js';
+import { runDiagnostics } from './diagnostics.js';
+import { autoReferenceCheck } from './symbol-references.js';
+/**
+ * WriteTool — 创建或覆盖文件
+ *
+ * 参数：
+ * - file_path (必需): 文件的绝对路径
+ * - content (必需): 要写入的文件内容
+ *
+ * 自动创建父目录（如果不存在），返回确认信息（文件路径和行数）
+ */
+export class WriteTool {
+    name = 'write';
+    description = 'Create or overwrite a file. Creates parent directories automatically.';
+    companionDescription = '写东西喽。';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            file_path: {
+                type: 'string',
+                description: 'The absolute path to the file to write',
+            },
+            content: {
+                type: 'string',
+                description: 'The content to write to the file',
+            },
+        },
+        required: ['file_path', 'content'],
+    };
+    async execute(args) {
+        const filePath = (args.file_path || args.path);
+        const content = args.content;
+        if (!filePath) {
+            const received = Object.keys(args).filter(k => args[k] !== undefined && args[k] !== null);
+            const rawJson = JSON.stringify(args);
+            const truncated = rawJson.length > 500 ? rawJson.slice(0, 497) + '...' : rawJson;
+            return `错误：缺少 file_path 参数。已收到参数: ${received.length > 0 ? received.join(', ') : '(无)'}。原始输入: ${truncated}。请使用 file_path 提供目标文件的绝对路径，例如 file_path: "/path/to/file.md"。`;
+        }
+        if (content === undefined || content === null)
+            return '错误：缺少 content 参数。请提供要写入的内容。';
+        // 自动创建父目录
+        const dir = path.dirname(filePath);
+        await fs.mkdir(dir, { recursive: true });
+        // ── Read-before-write 门控 ──
+        let fileExists = false;
+        try {
+            await fs.access(filePath);
+            fileExists = true;
+        }
+        catch { }
+        if (fileExists) {
+            const lastRead = getLastReadTime(filePath);
+            if (lastRead === null) {
+                return 'Error: You must read the file before writing to it. Use the read tool first.';
+            }
+            try {
+                const stat = await fs.stat(filePath);
+                if (stat.mtimeMs > lastRead) {
+                    return 'Error: File has been modified on disk since it was last read. Please re-read it first.';
+                }
+            }
+            catch { }
+        }
+        // 读旧内容（如果文件存在）
+        let oldContent = '';
+        if (fileExists) {
+            try {
+                oldContent = await fs.readFile(filePath, 'utf-8');
+            }
+            catch { }
+        }
+        // 写入文件
+        await fs.writeFile(filePath, content, 'utf-8');
+        // 记录写入（写入后自动更新 readTime = writeTime）
+        recordFileWrite(filePath);
+        // 计算 diff
+        try {
+            pushDiff(filePath, computeDiff(oldContent, content, filePath));
+        }
+        catch { }
+        // 计算行数
+        const lineCount = content.split('\n').length;
+        // 生成内容摘要：前几行 + 总行数，让模型知道自己写了什么
+        const lines = content.split('\n');
+        const previewLines = lines.slice(0, 5);
+        const preview = previewLines.join('\n');
+        const truncated = lines.length > 5;
+        let result = `Successfully wrote to ${filePath} (${lineCount} lines)`;
+        result += `\n--- Content preview ---\n${preview}`;
+        if (truncated) {
+            result += `\n... (${lines.length - 5} more lines)`;
+        }
+        result += `\n--- End preview ---`;
+        // ── 自动诊断：修改后运行类型检查/编译检查 ──
+        try {
+            const diag = await runDiagnostics(process.cwd(), 15000);
+            if (diag)
+                result += '\n\n' + diag;
+        }
+        catch { /* 诊断失败不影响工具返回值 */ }
+        // ── 自动引用搜索：覆盖已有文件时搜索变更符号的引用 ──
+        if (oldContent) {
+            try {
+                const ref = autoReferenceCheck(filePath, oldContent, oldContent, content);
+                if (ref.text)
+                    result += '\n\n' + ref.text;
+            }
+            catch { /* 引用搜索失败不影响工具返回值 */ }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=write.js.map

package/dist/tools/xref/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 交叉引用工具集 — 统一导出入口。
+ *
+ * 三个工具：
+ *   xref_build — 构建索引
+ *   xref_query — 查询索引
+ *   xref_graph — 可视化
+ *
+ * 共享 XrefManager 实例（由 factory.ts 创建并注入到三个工具）。
+ *
+ * 架构：
+ *   factory.ts → new XrefManager() → manager.init(rootDir)
+ *              → new XrefBuildTool(manager)
+ *              → new XrefQueryTool(manager)
+ *              → new XrefGraphTool(manager)
+ *              → toolRegistry.register(...)
+ *
+ * 数据库：~/.agent/cache/xref-<projectKey>.sqlite (better-sqlite3)
+ * 解析器：TypeScript Compiler API + 正则回退
+ */
+export { XrefManager } from './manager.js';
+export { XrefBuildTool } from './xref-build.js';
+export { XrefQueryTool } from './xref-query.js';
+export { XrefGraphTool } from './xref-graph.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/xref/index.js

@@ -0,0 +1,25 @@
+/**
+ * 交叉引用工具集 — 统一导出入口。
+ *
+ * 三个工具：
+ *   xref_build — 构建索引
+ *   xref_query — 查询索引
+ *   xref_graph — 可视化
+ *
+ * 共享 XrefManager 实例（由 factory.ts 创建并注入到三个工具）。
+ *
+ * 架构：
+ *   factory.ts → new XrefManager() → manager.init(rootDir)
+ *              → new XrefBuildTool(manager)
+ *              → new XrefQueryTool(manager)
+ *              → new XrefGraphTool(manager)
+ *              → toolRegistry.register(...)
+ *
+ * 数据库：~/.agent/cache/xref-<projectKey>.sqlite (better-sqlite3)
+ * 解析器：TypeScript Compiler API + 正则回退
+ */
+export { XrefManager } from './manager.js';
+export { XrefBuildTool } from './xref-build.js';
+export { XrefQueryTool } from './xref-query.js';
+export { XrefGraphTool } from './xref-graph.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/xref/manager.d.ts

@@ -0,0 +1,85 @@
+/**
+ * XrefManager — 交叉引用索引管理器。
+ *
+ * 职责：
+ *   - 管理 SQLite 数据库（创建、打开、关闭）
+ *   - build(): 扫描项目、解析源码、存入索引
+ *   - query(): 执行交叉引用查询
+ *   - graph(): 生成可视化输出
+ *   - 增量更新：只重新解析修改过的文件
+ *
+ * 数据库位置：~/.agent/cache/xref-<projectKey>.sqlite
+ *
+ * 上下文注册链路：
+ *   manifest-defaults.ts → 无（工具通过 Tool API 提供，不进入上下文）
+ *   工具注册：factory.ts → toolRegistry.register(new XrefBuildTool(manager))
+ *   数据库：better-sqlite3 → ~/.agent/cache/xref-*.sqlite
+ */
+import type { BuildStats, QueryParams, GraphOptions } from './schema.js';
+export declare class XrefManager {
+    private db;
+    private dbPath;
+    private parserRegistry;
+    private rootDir;
+    /** 初始化数据库（创建 if not exists，运行 schema DDL） */
+    init(rootDir: string): Promise<void>;
+    /** 是否已初始化 */
+    isReady(): boolean;
+    /** 获取索引统计信息 */
+    getStats(): {
+        files: number;
+        symbols: number;
+        refs: number;
+        imports: number;
+        built_at: string | null;
+    } | null;
+    /**
+     * 构建/重建交叉引用索引。
+     * @param changedFiles 可选：只重建这些文件（增量更新）。undefined = 全量重建。
+     * @param dirs        可选：只扫描这些子目录（相对路径）。undefined = 全项目扫描。
+     */
+    build(changedFiles?: string[], dirs?: string[]): Promise<BuildStats>;
+    /**
+     * 执行交叉引用查询。
+     */
+    query(params: QueryParams): string;
+    private queryRefs;
+    private queryDefs;
+    private queryCallers;
+    private queryCallees;
+    private traceCalleesRecursive;
+    private queryDeps;
+    private queryDependents;
+    private queryHierarchy;
+    private queryImpact;
+    private queryTrace;
+    private querySymbolSearch;
+    /**
+     * 生成调用图/依赖图可视化。
+     */
+    graph(options: GraphOptions): string;
+    private graphMermaid;
+    private graphText;
+    private textTreeCallers;
+    private textTreeCallees;
+    private textTreeFileDeps;
+    private graphGraphviz;
+    private collectCallerEdges;
+    private collectCalleeEdges;
+    private collectFileDepsEdges;
+    /**
+     * 扫描项目目录，收集需要解析的源文件。
+     * @param dirs 可选：只扫描这些子目录（相对路径）。undefined = 全项目扫描。
+     */
+    private scanFiles;
+    /** 删除当前项目或指定项目的交叉引用数据库 */
+    deleteDatabase(project?: string): string;
+    private resolvePath;
+    private toRelative;
+    private resolveImportPath;
+    private guessLanguage;
+    private shorten;
+    /** 关闭数据库连接 */
+    close(): void;
+}
+//# sourceMappingURL=manager.d.ts.map