hyacinth-ai 0.9.6

package/dist/hot-reload/skill-watcher.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { loadSkillFile, scanSkillsDir } from '../skills/loader.js';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('hot-reload:skill-watcher');
+/**
+ * 监视 skills 目录（用户级 + 项目级）的 .md 文件变更，自动重新加载 skill
+ *
+ * 监视目录：
+ * - ~/.agent/skills/
+ * - <cwd>/.agent/skills/（如果提供了 cwd）
+ */
+export function watchSkills(deps) {
+    const { skillRegistry, cwd, debounceMs } = deps;
+    const dirs = [];
+    const userSkillsDir = path.join(homedir(), '.agent', 'skills');
+    dirs.push(userSkillsDir);
+    if (cwd) {
+        const projectSkillsDir = path.join(cwd, '.agent', 'skills');
+        dirs.push(projectSkillsDir);
+    }
+    // 先做一次初始扫描
+    for (const dir of dirs) {
+        const loaded = scanSkillsDir(dir, skillRegistry);
+        if (loaded.length > 0) {
+            logger.info(`Loaded ${loaded.length} skill(s) from ${dir}: ${loaded.join(', ')}`);
+            // 为初始扫描到的文件 skill 补注册 ContextSource
+            if (deps.onSkillLoaded) {
+                for (const name of loaded) {
+                    const skill = skillRegistry.get(name);
+                    if (skill)
+                        deps.onSkillLoaded(skill);
+                }
+            }
+        }
+    }
+    const watchers = [];
+    for (const dir of dirs) {
+        try {
+            // 静默跳过，目录不存在时 fs.watch 会抛出异常
+        }
+        catch { /* 忽略 */ }
+        let debounceTimer = null;
+        logger.info(`Watching skills directory: ${dir}`);
+        const watcher = fs.watch(dir, { recursive: false }, (_eventType, filename) => {
+            if (!filename || !filename.endsWith('.md'))
+                return;
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                const filePath = path.join(dir, filename);
+                const skillName = filename.replace(/\.md$/, '');
+                try {
+                    fs.accessSync(filePath);
+                    // 文件存在 → 重新加载
+                    const skill = loadSkillFile(filePath);
+                    if (skill) {
+                        if (skillRegistry.has(skill.name)) {
+                            skillRegistry.unregister(skill.name);
+                        }
+                        skillRegistry.register(skill);
+                        deps.onSkillLoaded?.(skill);
+                        logger.info(`Skill reloaded: ${skill.name} (from ${filename})`);
+                    }
+                }
+                catch {
+                    if (skillRegistry.has(skillName)) {
+                        skillRegistry.unregister(skillName);
+                        logger.info(`Skill unregistered: ${skillName} (file removed)`);
+                    }
+                }
+            }, debounceMs);
+        });
+        watcher.on('error', (err) => {
+            logger.warn(`Skill watcher error on ${dir}: ${err.message}`, { error: err.message });
+        });
+        watchers.push(watcher);
+    }
+    return watchers;
+}
+//# sourceMappingURL=skill-watcher.js.map

package/dist/hot-reload/tool-watcher.d.ts

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import type { ToolRegistry } from '../tools/registry.js';
+export interface ToolWatcherDeps {
+    toolRegistry: ToolRegistry;
+    cwd: string;
+    debounceMs: number;
+}
+/**
+ * 监视 .agent/tools/ 目录，三轨扫描：
+ *
+ *   BasicTool  — flat .js files (dynamic import)
+ *   ModuleTool — subdir dist/index.js
+ *   PythonTool — flat .py files (PythonToolBridge)
+ */
+export declare function watchTools(deps: ToolWatcherDeps): fs.FSWatcher;
+//# sourceMappingURL=tool-watcher.d.ts.map

package/dist/hot-reload/tool-watcher.js

@@ -0,0 +1,168 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createLogger } from '../logging/logger.js';
+import { PythonToolBridge } from '../tools/python-bridge/index.js';
+const logger = createLogger('hot-reload:tool-watcher');
+/**
+ * 监视 .agent/tools/ 目录，三轨扫描：
+ *
+ *   BasicTool  — flat .js files (dynamic import)
+ *   ModuleTool — subdir dist/index.js
+ *   PythonTool — flat .py files (PythonToolBridge)
+ */
+export function watchTools(deps) {
+    const { toolRegistry, cwd, debounceMs } = deps;
+    const toolsDir = path.join(os.homedir(), '.agent', 'tools');
+    try {
+        fs.mkdirSync(toolsDir, { recursive: true });
+    }
+    catch { /* ignore */ }
+    const fileMap = new Map();
+    // 初始扫描不标记 hotAdded — 工具应进入 Zone 2 tool_rules
+    scanAndSync(toolsDir, toolRegistry, fileMap, true);
+    let debounceTimer = null;
+    logger.info(`Watching tools directory: ${toolsDir}`);
+    const watcher = fs.watch(toolsDir, { recursive: true }, (_eventType, filename) => {
+        if (!filename)
+            return;
+        if (!filename.endsWith('.js') && !filename.endsWith('.py'))
+            return;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        // 文件变更触发的重新扫描 — 此时才标记 hotAdded，工具进 Zone 5 session-tools
+        debounceTimer = setTimeout(() => scanAndSync(toolsDir, toolRegistry, fileMap, false), debounceMs);
+    });
+    watcher.on('error', (err) => {
+        logger.warn(`Tool watcher error: ${err.message}`, { error: err.message });
+    });
+    return watcher;
+}
+async function scanAndSync(dir, registry, fileMap, isInitialScan) {
+    const resolved = resolveToolEntries(dir);
+    const currentKeys = new Set(resolved.map((r) => r.trackingKey));
+    for (const entry of resolved) {
+        const knownToolName = fileMap.get(entry.trackingKey);
+        if (knownToolName !== undefined) {
+            // 已跟踪 → 重新加载（文件变更触发的热重载）
+            if (entry.factory) {
+                // Python 工具：不再解析
+                const tool = entry.factory();
+                if (tool) {
+                    registry.unregister(knownToolName);
+                    registry.register(tool);
+                    if (!isInitialScan)
+                        registry.markHotAdded(tool.name);
+                    fileMap.set(entry.trackingKey, tool.name);
+                    logger.info(`Tool reloaded: ${tool.name} (${entry.label})`);
+                }
+            }
+            else {
+                // JS 工具：dynamic import
+                try {
+                    const fileUrl = pathToFileURL(entry.filePath).href;
+                    const imported = await import(`${fileUrl}?t=${Date.now()}`);
+                    const tool = (imported.default ?? imported);
+                    if (tool && typeof tool.name === 'string' && typeof tool.execute === 'function') {
+                        registry.unregister(knownToolName);
+                        registry.register(tool);
+                        if (!isInitialScan)
+                            registry.markHotAdded(tool.name);
+                        fileMap.set(entry.trackingKey, tool.name);
+                        logger.info(`Tool reloaded: ${tool.name} (${entry.label})`);
+                    }
+                }
+                catch (err) {
+                    logger.warn(`Failed to reload tool ${entry.label}: ${err.message}`);
+                }
+            }
+        }
+        else {
+            await loadAndRegister(entry, registry, fileMap, isInitialScan);
+        }
+    }
+    for (const [key, toolName] of fileMap.entries()) {
+        if (!currentKeys.has(key)) {
+            registry.unregister(toolName);
+            fileMap.delete(key);
+            logger.info(`Tool unregistered: ${toolName} (${key})`);
+        }
+    }
+}
+function resolveToolEntries(dir) {
+    const entries = [];
+    let fsEntries;
+    try {
+        fsEntries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return entries;
+    }
+    // ① ModuleTool：子目录的 dist/index.js
+    for (const entry of fsEntries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith('.') || entry.name === 'node_modules')
+            continue;
+        const distIndex = path.join(dir, entry.name, 'dist', 'index.js');
+        try {
+            fs.accessSync(distIndex);
+            entries.push({ trackingKey: entry.name, filePath: distIndex, label: `${entry.name}/dist/index.js` });
+        }
+        catch { /* 无编译产物 */ }
+    }
+    // ② BasicTool：扁平 .js 文件
+    for (const entry of fsEntries) {
+        if (!entry.isFile() || !entry.name.endsWith('.js'))
+            continue;
+        const fp = path.join(dir, entry.name);
+        if (entries.some((e) => e.trackingKey === entry.name.replace(/\.js$/, '')))
+            continue;
+        entries.push({ trackingKey: entry.name, filePath: fp, label: entry.name });
+    }
+    // ③ PythonTool：扁平 .py 文件
+    for (const entry of fsEntries) {
+        if (!entry.isFile() || !entry.name.endsWith('.py'))
+            continue;
+        const fp = path.join(dir, entry.name);
+        const key = `py:${entry.name}`;
+        if (entries.some((e) => e.trackingKey === key))
+            continue;
+        entries.push({
+            trackingKey: key,
+            filePath: fp,
+            label: `${entry.name} (python)`,
+            factory: () => PythonToolBridge.fromFile(fp),
+        });
+    }
+    return entries;
+}
+async function loadAndRegister(entry, registry, fileMap, isInitialScan) {
+    try {
+        let tool;
+        if (entry.factory) {
+            tool = entry.factory();
+        }
+        else {
+            const fileUrl = pathToFileURL(entry.filePath).href;
+            const imported = await import(fileUrl);
+            tool = (imported.default ?? imported);
+        }
+        if (!tool || typeof tool.name !== 'string' || typeof tool.execute !== 'function') {
+            logger.warn(`Tool file ${entry.label} does not export a valid Tool (need name, execute, inputSchema)`);
+            return;
+        }
+        registry.register(tool);
+        // 初始扫描（启动时）不标记 hotAdded → 工具进入 Zone 2 tool_rules
+        // 文件变更触发的扫描才标记 → 工具进入 Zone 5 session-tools
+        if (!isInitialScan)
+            registry.markHotAdded(tool.name);
+        fileMap.set(entry.trackingKey, tool.name);
+        logger.info(`Tool registered: ${tool.name} (${entry.label})`);
+    }
+    catch (err) {
+        logger.warn(`Failed to load tool ${entry.label}: ${err.message}`);
+    }
+}
+//# sourceMappingURL=tool-watcher.js.map

package/dist/hot-reload/workflow-watcher.d.ts

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import type { WorkflowDefinition } from '../workflow/types.js';
+import type { WorkflowRegistry } from '../workflow/registry.js';
+export interface WorkflowWatcherDeps {
+    workflowRegistry: WorkflowRegistry;
+    cwd?: string;
+    debounceMs: number;
+    /** 文件 workflow 加载/重载后的回调，用于补注册 ContextSource 等 */
+    onWorkflowLoaded?: (def: WorkflowDefinition) => void;
+}
+/**
+ * 监视 workflows 目录（用户级 + 项目级）的 .yaml 文件变更，自动重新加载 workflow
+ *
+ * 监视目录：
+ * - ~/.agent/workflows/
+ * - <cwd>/.agent/workflows/（如果提供了 cwd）
+ */
+export declare function watchWorkflows(deps: WorkflowWatcherDeps): fs.FSWatcher[];
+//# sourceMappingURL=workflow-watcher.d.ts.map

package/dist/hot-reload/workflow-watcher.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { loadWorkflowFile, scanWorkflowsDir } from '../workflow/loader.js';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('hot-reload:workflow-watcher');
+/**
+ * 监视 workflows 目录（用户级 + 项目级）的 .yaml 文件变更，自动重新加载 workflow
+ *
+ * 监视目录：
+ * - ~/.agent/workflows/
+ * - <cwd>/.agent/workflows/（如果提供了 cwd）
+ */
+export function watchWorkflows(deps) {
+    const { workflowRegistry, cwd, debounceMs } = deps;
+    const dirs = [];
+    const userWorkflowsDir = path.join(homedir(), '.agent', 'workflows');
+    dirs.push(userWorkflowsDir);
+    if (cwd) {
+        const projectWorkflowsDir = path.join(cwd, '.agent', 'workflows');
+        dirs.push(projectWorkflowsDir);
+    }
+    // 先做一次初始扫描
+    for (const dir of dirs) {
+        const loaded = scanWorkflowsDir(dir, workflowRegistry);
+        if (loaded.length > 0) {
+            logger.info(`Loaded ${loaded.length} workflow(s) from ${dir}: ${loaded.join(', ')}`);
+            // 为初始扫描到的文件 workflow 补注册 ContextSource
+            if (deps.onWorkflowLoaded) {
+                for (const name of loaded) {
+                    const def = workflowRegistry.get(name);
+                    if (def)
+                        deps.onWorkflowLoaded(def);
+                }
+            }
+        }
+    }
+    const watchers = [];
+    for (const dir of dirs) {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        catch { /* 忽略 */ }
+        let debounceTimer = null;
+        logger.info(`Watching workflows directory: ${dir}`);
+        const watcher = fs.watch(dir, { recursive: false }, (_eventType, filename) => {
+            if (!filename || (!filename.endsWith('.yaml') && !filename.endsWith('.yml')))
+                return;
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                const filePath = path.join(dir, filename);
+                const ext = path.extname(filename);
+                const workflowName = filename.slice(0, -ext.length);
+                try {
+                    fs.accessSync(filePath);
+                    // 文件存在 → 重新加载
+                    const def = loadWorkflowFile(filePath);
+                    if (def) {
+                        // 内置名保护区：先 unregister 再 register
+                        if (workflowRegistry.has(def.name)) {
+                            workflowRegistry.unregister(def.name);
+                        }
+                        workflowRegistry.register(def);
+                        deps.onWorkflowLoaded?.(def);
+                        logger.info(`Workflow reloaded: ${def.name} (from ${filename})`);
+                    }
+                }
+                catch {
+                    if (workflowRegistry.has(workflowName)) {
+                        workflowRegistry.unregister(workflowName);
+                        logger.info(`Workflow unregistered: ${workflowName} (file removed)`);
+                    }
+                }
+            }, debounceMs);
+        });
+        watcher.on('error', (err) => {
+            logger.warn(`Workflow watcher error on ${dir}: ${err.message}`, { error: err.message });
+        });
+        watchers.push(watcher);
+    }
+    return watchers;
+}
+//# sourceMappingURL=workflow-watcher.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from './gateway/cli.js';
+import { createLogger } from './logging/logger.js';
+const logger = createLogger('app');
+runCli().catch((err) => logger.error('Unhandled error', err instanceof Error ? err : undefined));
+//# sourceMappingURL=index.js.map

package/dist/knowledge/fts5-retriever.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Fts5Retriever — SQLite FTS5 全文检索实现
+ *
+ * 使用 better-sqlite3 存储文档 + FTS5 虚拟表做 BM25 关键词检索。
+ * 对 CJK 文本自动追加 bigram 到索引内容中，以支持中文搜索。
+ */
+import type { Retriever, KbDocument, KbSearchResult } from './retriever.js';
+export declare class Fts5Retriever implements Retriever {
+    readonly name = "fts5";
+    private db;
+    constructor(dbPath: string);
+    private initTables;
+    /** 迁移旧 schema（bigram 列残留 / 缺少 fts_content 列） */
+    private migrateSchema;
+    search(query: string, k?: number): KbSearchResult[];
+    /** 中文多策略搜索：按变体链降级 */
+    private searchCjk;
+    /** 单次 FTS5 MATCH */
+    private matchQuery;
+    add(doc: KbDocument): string;
+    remove(id: string): boolean;
+    update(id: string, fields: Partial<Pick<KbDocument, 'title' | 'content' | 'source'>>): boolean;
+    findBySource(source: string): {
+        id: string;
+    } | undefined;
+    list(): KbDocument[];
+    count(): number;
+    close(): void;
+}
+//# sourceMappingURL=fts5-retriever.d.ts.map

package/dist/knowledge/fts5-retriever.js

@@ -0,0 +1,223 @@
+/**
+ * Fts5Retriever — SQLite FTS5 全文检索实现
+ *
+ * 使用 better-sqlite3 存储文档 + FTS5 虚拟表做 BM25 关键词检索。
+ * 对 CJK 文本自动追加 bigram 到索引内容中，以支持中文搜索。
+ */
+import Database from 'better-sqlite3';
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { preprocessQuery } from './query-preprocessor.js';
+// ── CJK bigram 分词 ────────────────────────────────────────────────
+const CJK_RE = /[一-鿿㐀-䶿]/;
+/** 将 CJK 文本转为空格分隔的二元组，追加到原文后面供 FTS5 索引 */
+function indexContent(text) {
+    const bigrams = [];
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (CJK_RE.test(ch) && i + 1 < text.length && CJK_RE.test(text[i + 1])) {
+            bigrams.push(ch + text[i + 1]);
+        }
+    }
+    return bigrams.length > 0 ? text + '\n' + bigrams.join(' ') : text;
+}
+/** 将中文查询转为 bigram 格式用于 FTS5 MATCH */
+function bigramQuery(query) {
+    const clean = query.replace(/["*()]/g, '').trim();
+    // 非中文 → 直接返回
+    if (!CJK_RE.test(clean))
+        return clean;
+    // 中文 → 转为 bigram
+    const bigrams = [];
+    for (let i = 0; i < clean.length; i++) {
+        const ch = clean[i];
+        if (CJK_RE.test(ch) && i + 1 < clean.length && CJK_RE.test(clean[i + 1])) {
+            bigrams.push(`"${ch}${clean[i + 1]}"`);
+        }
+    }
+    return bigrams.length > 0 ? bigrams.join(' ') : clean;
+}
+// ── Fts5Retriever ──────────────────────────────────────────────────
+export class Fts5Retriever {
+    name = 'fts5';
+    db;
+    constructor(dbPath) {
+        const dir = path.dirname(dbPath);
+        fs.mkdirSync(dir, { recursive: true });
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.initTables();
+        this.migrateSchema();
+        // 确保 FTS 索引与 docs 表同步
+        this.db.exec("INSERT INTO docs_fts(docs_fts) VALUES('rebuild')");
+    }
+    // ── 建表 ────────────────────────────────────────────────────────
+    initTables() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS docs (
+        id TEXT PRIMARY KEY,
+        title TEXT NOT NULL,
+        source TEXT DEFAULT '',
+        content TEXT NOT NULL,
+        fts_content TEXT NOT NULL DEFAULT '',
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(
+        title, fts_content,
+        content=docs,
+        content_rowid=rowid
+      );
+      CREATE TRIGGER IF NOT EXISTS docs_ai AFTER INSERT ON docs BEGIN
+        INSERT INTO docs_fts(rowid, title, fts_content) VALUES (new.rowid, new.title, new.fts_content);
+      END;
+      CREATE TRIGGER IF NOT EXISTS docs_ad AFTER DELETE ON docs BEGIN
+        INSERT INTO docs_fts(docs_fts, rowid, title, fts_content) VALUES('delete', old.rowid, old.title, old.fts_content);
+      END;
+      CREATE TRIGGER IF NOT EXISTS docs_au AFTER UPDATE ON docs BEGIN
+        INSERT INTO docs_fts(docs_fts, rowid, title, fts_content) VALUES('delete', old.rowid, old.title, old.fts_content);
+        INSERT INTO docs_fts(rowid, title, fts_content) VALUES (new.rowid, new.title, new.fts_content);
+      END;
+    `);
+    }
+    /** 迁移旧 schema（bigram 列残留 / 缺少 fts_content 列） */
+    migrateSchema() {
+        const ftsInfo = this.db.prepare("PRAGMA table_info('docs_fts')").all();
+        const docInfo = this.db.prepare("PRAGMA table_info('docs')").all();
+        const needsFtsRebuild = ftsInfo.some((c) => c.name === 'bigram');
+        const needsFtsColumn = !docInfo.some((c) => c.name === 'fts_content');
+        // 检查 fts_content 是否需要 backfill
+        const emptyCount = this.db.prepare("SELECT COUNT(*) as cnt FROM docs WHERE fts_content = ''").get();
+        const needsBackfill = emptyCount.cnt > 0;
+        if (!needsFtsRebuild && !needsFtsColumn && !needsBackfill)
+            return;
+        // 1. 加 fts_content 列
+        if (needsFtsColumn) {
+            this.db.exec('ALTER TABLE docs ADD COLUMN fts_content TEXT NOT NULL DEFAULT \'\'');
+        }
+        // 2. Backfill fts_content
+        if (needsBackfill) {
+            const docs = this.db.prepare('SELECT rowid, content FROM docs').all();
+            for (const d of docs) {
+                this.db.prepare('UPDATE docs SET fts_content = ? WHERE rowid = ?').run(indexContent(d.content), d.rowid);
+            }
+        }
+        // 3. 删除旧触发器，重建 FTS（如果需要），重建触发器
+        this.db.exec('DROP TRIGGER IF EXISTS docs_ai; DROP TRIGGER IF EXISTS docs_ad; DROP TRIGGER IF EXISTS docs_au;');
+        if (needsFtsRebuild) {
+            this.db.exec('DROP TABLE IF EXISTS docs_fts');
+            this.db.exec('CREATE VIRTUAL TABLE docs_fts USING fts5(title, fts_content, content=docs, content_rowid=rowid)');
+        }
+        this.db.exec(`
+      CREATE TRIGGER docs_ai AFTER INSERT ON docs BEGIN
+        INSERT INTO docs_fts(rowid, title, fts_content) VALUES (new.rowid, new.title, new.fts_content);
+      END;
+      CREATE TRIGGER docs_ad AFTER DELETE ON docs BEGIN
+        INSERT INTO docs_fts(docs_fts, rowid, title, fts_content) VALUES('delete', old.rowid, old.title, old.fts_content);
+      END;
+      CREATE TRIGGER docs_au AFTER UPDATE ON docs BEGIN
+        INSERT INTO docs_fts(docs_fts, rowid, title, fts_content) VALUES('delete', old.rowid, old.title, old.fts_content);
+        INSERT INTO docs_fts(rowid, title, fts_content) VALUES (new.rowid, new.title, new.fts_content);
+      END;
+    `);
+        // 4. 重建 FTS 索引（backfill 或 schema 变更后必须执行）
+        this.db.exec("INSERT INTO docs_fts(docs_fts) VALUES('rebuild')");
+    }
+    // ── 检索 ────────────────────────────────────────────────────────
+    search(query, k = 5) {
+        if (!query.trim())
+            return [];
+        // 中文查询 → 多策略降级
+        if (CJK_RE.test(query)) {
+            return this.searchCjk(query, k);
+        }
+        // 非中文 → 直接 FTS5 关键词
+        return this.matchQuery(query, k);
+    }
+    /** 中文多策略搜索：按变体链降级 */
+    searchCjk(query, k) {
+        const { variants } = preprocessQuery(query);
+        for (const v of variants) {
+            const results = this.matchQuery(v, k);
+            if (results.length > 0)
+                return results;
+        }
+        return [];
+    }
+    /** 单次 FTS5 MATCH */
+    matchQuery(q, k) {
+        const safe = q.replace(/["*()]/g, '').trim();
+        if (!safe)
+            return [];
+        const searchQuery = bigramQuery(safe);
+        const stmt = this.db.prepare(`
+      SELECT d.title, d.source,
+        snippet(docs_fts, 1, '<b>', '</b>', '...', 40) AS snippet
+      FROM docs_fts
+      JOIN docs d ON d.rowid = docs_fts.rowid
+      WHERE docs_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `);
+        try {
+            const raw = stmt.all(searchQuery, k);
+            // 去重（按 title+source）
+            const seen = new Set();
+            return raw.filter(r => {
+                const key = r.title + '|' + r.source;
+                if (seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── CRUD ────────────────────────────────────────────────────────
+    add(doc) {
+        const id = doc.id || crypto.randomUUID();
+        const ftsContent = indexContent(doc.content);
+        this.db.prepare('INSERT INTO docs (id, title, source, content, fts_content) VALUES (?, ?, ?, ?, ?)').run(id, doc.title, doc.source || '', doc.content, ftsContent);
+        return id;
+    }
+    remove(id) {
+        const r = this.db.prepare('DELETE FROM docs WHERE id = ?').run(id);
+        return r.changes > 0;
+    }
+    update(id, fields) {
+        const sets = [];
+        const vals = [];
+        for (const [k, v] of Object.entries(fields)) {
+            if (v !== undefined) {
+                sets.push(`${k} = ?`);
+                vals.push(v);
+            }
+        }
+        // content 更新 → 同步 fts_content
+        if (fields.content !== undefined) {
+            sets.push('fts_content = ?');
+            vals.push(indexContent(fields.content));
+        }
+        if (sets.length === 0)
+            return false;
+        vals.push(id);
+        const r = this.db.prepare(`UPDATE docs SET ${sets.join(', ')} WHERE id = ?`).run(...vals);
+        return r.changes > 0;
+    }
+    findBySource(source) {
+        return this.db.prepare('SELECT id FROM docs WHERE source = ? LIMIT 1').get(source);
+    }
+    list() {
+        return this.db.prepare('SELECT id, title, source, content, created_at FROM docs ORDER BY created_at DESC').all();
+    }
+    count() {
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM docs').get();
+        return row.cnt;
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=fts5-retriever.js.map

package/dist/knowledge/index.d.ts

@@ -0,0 +1,11 @@
+export type { Retriever, KbDocument, KbSearchResult } from './retriever.js';
+export { Fts5Retriever } from './fts5-retriever.js';
+export { KnowledgeBase, type KbDoc, type KbResult } from './store.js';
+export { indexFile, indexDirectory, removeFile, updateFile, syncDirectory } from './indexer.js';
+export type { IndexOptions } from './indexer.js';
+export { KnowledgeWatcher } from './watcher.js';
+export type { WatcherOptions } from './watcher.js';
+export { createKbAddTool, createKbListTool, createKbDeleteTool, createKbUpdateTool, createKbToggleTool } from './tools.js';
+export { StructuredStore, type StructuredEntry, type TagMatchResult, type EntryCategory } from './structured-store.js';
+export { createStructuredTool } from './structured-tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.js

@@ -0,0 +1,14 @@
+// FTS5 实现
+export { Fts5Retriever } from './fts5-retriever.js';
+// 状态管理器（公开 API）
+export { KnowledgeBase } from './store.js';
+// 索引器
+export { indexFile, indexDirectory, removeFile, updateFile, syncDirectory } from './indexer.js';
+// 文件监控
+export { KnowledgeWatcher } from './watcher.js';
+// 工具
+export { createKbAddTool, createKbListTool, createKbDeleteTool, createKbUpdateTool, createKbToggleTool } from './tools.js';
+// 结构化知识库
+export { StructuredStore } from './structured-store.js';
+export { createStructuredTool } from './structured-tools.js';
+//# sourceMappingURL=index.js.map