hyacinth-ai 0.9.6

package/dist/knowledge/indexer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 文件索引器 — 将文本文件导入知识库
+ *
+ * 支持单文件、递归目录导入。可选择性将文件复制到知识库 files/ 目录，
+ * 实现"文件系统为主存储"的设计原则。
+ */
+import type { KnowledgeBase } from './store.js';
+import type { Retriever } from './retriever.js';
+export interface IndexOptions {
+    /** 知识库文件存储目录（文件复制目标）。不传则只索引不复制 */
+    kbFilesDir?: string;
+}
+/**
+ * 索引单个文件。如果是外部路径且指定了 kbFilesDir，会先复制到知识库目录。
+ */
+export declare function indexFile(kb: KnowledgeBase, filePath: string, opts?: IndexOptions): Promise<number>;
+/**
+ * 递归索引目录。跳过隐藏文件/目录。
+ */
+export declare function indexDirectory(kb: KnowledgeBase, dirPath: string, opts?: IndexOptions): Promise<number>;
+/**
+ * 删除与指定文件路径关联的知识库条目。
+ * 传入 kbFilesDir 内的文件路径，Retriever 按 source 查找并删除。
+ */
+export declare function removeFile(retriever: Retriever, filePath: string): boolean;
+/**
+ * 更新已索引的文件（文件内容变更时调用）。
+ * 重新读取文件内容并更新知识库条目。
+ */
+export declare function updateFile(retriever: Retriever, filePath: string): boolean;
+/**
+ * 全量扫描知识库文件目录，确保索引与文件系统一致。
+ * - 新增文件 → 添加索引
+ * - 已删除文件 → 移除索引
+ * - 已有文件保持不变（不重复索引）
+ */
+export declare function syncDirectory(retriever: Retriever, kbFilesDir: string): Promise<{
+    added: number;
+    removed: number;
+}>;
+//# sourceMappingURL=indexer.d.ts.map

package/dist/knowledge/indexer.js

@@ -0,0 +1,186 @@
+/**
+ * 文件索引器 — 将文本文件导入知识库
+ *
+ * 支持单文件、递归目录导入。可选择性将文件复制到知识库 files/ 目录，
+ * 实现"文件系统为主存储"的设计原则。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const TEXT_EXTS = new Set([
+    '.txt', '.md', '.json', '.html', '.htm', '.xml',
+    '.py', '.js', '.ts', '.jsx', '.tsx', '.css', '.scss', '.less',
+    '.c', '.cpp', '.h', '.hpp', '.java', '.go', '.rs', '.rb', '.php',
+    '.sh', '.bat', '.ps1', '.yaml', '.yml', '.toml', '.ini', '.cfg',
+    '.csv', '.log', '.sql', '.r', '.m', '.swift',
+]);
+function isTextFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return TEXT_EXTS.has(ext);
+}
+function readFileContent(filePath) {
+    return fs.readFileSync(filePath, 'utf-8');
+}
+/**
+ * 将文件复制到知识库 files/ 目录，保持文件名唯一。
+ * 如果同名文件已存在，追加 (N) 后缀。
+ * 返回复制后的目标路径。
+ */
+function copyToKbDir(filePath, kbFilesDir) {
+    const base = path.basename(filePath);
+    const ext = path.extname(base);
+    const stem = path.basename(base, ext);
+    let dest = path.join(kbFilesDir, base);
+    let n = 1;
+    while (fs.existsSync(dest)) {
+        dest = path.join(kbFilesDir, `${stem} (${n})${ext}`);
+        n++;
+    }
+    fs.copyFileSync(filePath, dest);
+    return dest;
+}
+/**
+ * 索引单个文件。如果是外部路径且指定了 kbFilesDir，会先复制到知识库目录。
+ */
+export async function indexFile(kb, filePath, opts = {}) {
+    if (!fs.statSync(filePath).isFile())
+        return 0;
+    if (!isTextFile(filePath))
+        return 0;
+    const content = readFileContent(filePath);
+    if (!content.trim())
+        return 0;
+    let sourcePath = filePath;
+    // 如果文件不在 kbFilesDir 内，复制进去
+    if (opts.kbFilesDir && !filePath.startsWith(opts.kbFilesDir)) {
+        sourcePath = copyToKbDir(filePath, opts.kbFilesDir);
+    }
+    const title = path.basename(sourcePath);
+    kb.add(title, content, sourcePath);
+    return 1;
+}
+/**
+ * 递归索引目录。跳过隐藏文件/目录。
+ */
+export async function indexDirectory(kb, dirPath, opts = {}) {
+    let count = 0;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isFile()) {
+            count += await indexFile(kb, fullPath, opts);
+        }
+        else if (entry.isDirectory()) {
+            count += await indexDirectory(kb, fullPath, opts);
+        }
+    }
+    return count;
+}
+// ── 文件变更操作（供 watcher 使用）─────────────────────────────────
+/**
+ * 删除与指定文件路径关联的知识库条目。
+ * 传入 kbFilesDir 内的文件路径，Retriever 按 source 查找并删除。
+ */
+export function removeFile(retriever, filePath) {
+    const doc = retriever.findBySource(filePath);
+    if (!doc)
+        return false;
+    return retriever.remove(doc.id);
+}
+/**
+ * 更新已索引的文件（文件内容变更时调用）。
+ * 重新读取文件内容并更新知识库条目。
+ */
+export function updateFile(retriever, filePath) {
+    if (!fs.existsSync(filePath)) {
+        // 文件被删除 — 移除索引
+        return removeFile(retriever, filePath);
+    }
+    if (!isTextFile(filePath))
+        return false;
+    try {
+        const content = readFileContent(filePath);
+        if (!content.trim())
+            return false;
+        const doc = retriever.findBySource(filePath);
+        if (doc) {
+            return retriever.update(doc.id, {
+                title: path.basename(filePath),
+                content,
+            });
+        }
+        // 新文件 — 添加到索引
+        retriever.add({
+            id: '',
+            title: path.basename(filePath),
+            content,
+            source: filePath,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 全量扫描知识库文件目录，确保索引与文件系统一致。
+ * - 新增文件 → 添加索引
+ * - 已删除文件 → 移除索引
+ * - 已有文件保持不变（不重复索引）
+ */
+export async function syncDirectory(retriever, kbFilesDir) {
+    let added = 0;
+    let removed = 0;
+    if (!fs.existsSync(kbFilesDir)) {
+        fs.mkdirSync(kbFilesDir, { recursive: true });
+        return { added, removed };
+    }
+    // 收集文件系统中的所有文本文件
+    const diskFiles = new Set();
+    function walk(dir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const p = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(p);
+            }
+            else if (entry.isFile() && isTextFile(p)) {
+                diskFiles.add(p);
+            }
+        }
+    }
+    walk(kbFilesDir);
+    // 收集已索引的文件
+    const indexed = retriever.list();
+    const indexedSources = new Map(); // source → id
+    for (const doc of indexed) {
+        if (doc.source)
+            indexedSources.set(doc.source, doc.id);
+    }
+    // 新增：磁盘有但索引没有
+    for (const f of diskFiles) {
+        if (!indexedSources.has(f)) {
+            try {
+                const content = readFileContent(f);
+                if (content.trim()) {
+                    retriever.add({ id: '', title: path.basename(f), content, source: f });
+                    added++;
+                }
+            }
+            catch {
+                // skip unreadable files
+            }
+        }
+    }
+    // 删除：索引有但磁盘没有
+    for (const [source, id] of indexedSources) {
+        if (source && !fs.existsSync(source)) {
+            retriever.remove(id);
+            removed++;
+        }
+    }
+    return { added, removed };
+}
+//# sourceMappingURL=indexer.js.map

package/dist/knowledge/query-preprocessor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 查询预处理器 — 中文查询优化
+ *
+ * 将原始用户输入转为多级查询变体（从精确到宽泛），
+ * 解决"我的同桌是谁"被停用词淹没、FTS5 无法匹配的问题。
+ */
+export interface QueryVariants {
+    raw: string;
+    keywords: string[];
+    variants: string[];
+}
+export declare function preprocessQuery(rawInput: string): QueryVariants;
+//# sourceMappingURL=query-preprocessor.d.ts.map

package/dist/knowledge/query-preprocessor.js

@@ -0,0 +1,63 @@
+/**
+ * 查询预处理器 — 中文查询优化
+ *
+ * 将原始用户输入转为多级查询变体（从精确到宽泛），
+ * 解决"我的同桌是谁"被停用词淹没、FTS5 无法匹配的问题。
+ */
+// ── 中文停用词 ──────────────────────────────────────────────────────
+const STOP_WORDS = new Set([
+    '的', '了', '是', '在', '我', '有', '和', '就', '不', '人', '都',
+    '一', '一个', '上', '也', '很', '到', '说', '要', '去', '你',
+    '会', '着', '没有', '看', '好', '自己', '这', '他', '她', '它',
+    '们', '那', '些', '所', '为', '所以', '因为', '但是', '然而',
+    '可以', '这个', '那个', '什么', '怎么', '哪', '哪里', '谁',
+    '吗', '呢', '吧', '啊', '嘛', '哦', '嗯', '哈', '呀', '哇',
+    '还', '被', '把', '让', '给', '向', '从', '对', '跟', '与',
+    '或', '且', '而', '但', '虽', '虽然', '如果', '即使', '无论',
+    '能', '能够', '可能', '应该', '可以', '需要', '必须', '要',
+    '已', '已经', '将', '正在', '一直', '还是', '只是', '就是',
+    '来', '去', '做', '搞', '弄', '干', '进行', '使用', '通过',
+]);
+export function preprocessQuery(rawInput) {
+    let clean = rawInput.replace(/["*()^~@:]/g, ' ').trim();
+    if (!clean)
+        return { raw: rawInput, keywords: [], variants: [] };
+    const cjkSeq = clean.match(/[一-鿿㐀-䶿]+/g) ?? [];
+    const allCjkWords = cjkSeq.flatMap(seq => segmentCjk(seq));
+    const keywords = allCjkWords.filter(w => !STOP_WORDS.has(w) && w.length >= 1);
+    const variants = [];
+    const seen = new Set();
+    for (const kw of keywords) {
+        if (!seen.has(kw)) {
+            variants.push(kw);
+            seen.add(kw);
+        }
+    }
+    for (let i = 0; i < keywords.length - 1; i++) {
+        const phrase = keywords.slice(i, i + 2).join('');
+        if (!seen.has(phrase) && phrase.length >= 2) {
+            variants.push(phrase);
+            seen.add(phrase);
+        }
+    }
+    if (!seen.has(clean) && clean.length >= 1) {
+        variants.push(clean);
+        seen.add(clean);
+    }
+    if (rawInput !== clean && !seen.has(rawInput)) {
+        variants.push(rawInput);
+    }
+    return { raw: rawInput, keywords, variants };
+}
+function segmentCjk(text) {
+    const words = [];
+    for (let n = 4; n >= 2; n--) {
+        for (let i = 0; i <= text.length - n; i++) {
+            words.push(text.slice(i, i + n));
+        }
+    }
+    for (const ch of text)
+        words.push(ch);
+    return words;
+}
+//# sourceMappingURL=query-preprocessor.js.map

package/dist/knowledge/retriever.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Retriever 接口 — 知识库检索后端抽象
+ *
+ * 将存储/检索操作与具体的检索引擎解耦。
+ * 当前实现：Fts5Retriever（SQLite FTS5 + BM25）
+ * 未来实现：VectorRetriever（本地 embedding）、HybridRetriever（混合）
+ */
+/** 知识库文档 */
+export interface KbDocument {
+    id: string;
+    title: string;
+    source: string;
+    content: string;
+    created_at?: string;
+}
+/** 检索结果 — 含匹配片段高亮 */
+export interface KbSearchResult {
+    title: string;
+    source: string;
+    snippet: string;
+}
+/** 检索后端接口 */
+export interface Retriever {
+    /** 后端名称，用于日志和诊断 */
+    readonly name: string;
+    /** 关键词检索，返回 Top K 结果 */
+    search(query: string, k: number): KbSearchResult[];
+    /** 添加文档，返回文档 ID */
+    add(doc: KbDocument): string;
+    /** 按 ID 删除文档 */
+    remove(id: string): boolean;
+    /** 更新文档（按 ID）。仅更新传入的字段 */
+    update(id: string, fields: Partial<Pick<KbDocument, 'title' | 'content' | 'source'>>): boolean;
+    /** 按 source 路径查找文档 ID（用于文件变更时的去重更新） */
+    findBySource(source: string): {
+        id: string;
+    } | undefined;
+    /** 列出所有文档 */
+    list(): KbDocument[];
+    /** 文档总数 */
+    count(): number;
+    /** 关闭并释放资源 */
+    close(): void;
+}
+//# sourceMappingURL=retriever.d.ts.map

package/dist/knowledge/retriever.js

@@ -0,0 +1,9 @@
+/**
+ * Retriever 接口 — 知识库检索后端抽象
+ *
+ * 将存储/检索操作与具体的检索引擎解耦。
+ * 当前实现：Fts5Retriever（SQLite FTS5 + BM25）
+ * 未来实现：VectorRetriever（本地 embedding）、HybridRetriever（混合）
+ */
+export {};
+//# sourceMappingURL=retriever.js.map

package/dist/knowledge/store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * KnowledgeBase — 知识库状态管理器
+ *
+ * 管理启用状态（/kb on/off、/zone4 on/off）并将存储/检索委托给 Retriever。
+ * 默认使用 Fts5Retriever（SQLite FTS5），未来可切换到向量/混合检索。
+ */
+import type { Retriever, KbDocument, KbSearchResult } from './retriever.js';
+export type { KbDocument as KbDoc, KbSearchResult as KbResult } from './retriever.js';
+export declare class KnowledgeBase {
+    readonly retriever: Retriever;
+    private _enabled;
+    private _zone4Enabled;
+    constructor(dbPathOrRetriever: string | Retriever);
+    get enabled(): boolean;
+    enable(): void;
+    disable(): void;
+    setZone4Enabled(v: boolean): void;
+    get zone4Enabled(): boolean;
+    search(query: string, k?: number): KbSearchResult[];
+    add(title: string, content: string, source?: string): string;
+    remove(id: string): boolean;
+    update(id: string, fields: Partial<Pick<KbDocument, 'title' | 'content' | 'source'>>): boolean;
+    list(): KbDocument[];
+    count(): number;
+    close(): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/knowledge/store.js

@@ -0,0 +1,61 @@
+/**
+ * KnowledgeBase — 知识库状态管理器
+ *
+ * 管理启用状态（/kb on/off、/zone4 on/off）并将存储/检索委托给 Retriever。
+ * 默认使用 Fts5Retriever（SQLite FTS5），未来可切换到向量/混合检索。
+ */
+import { Fts5Retriever } from './fts5-retriever.js';
+export class KnowledgeBase {
+    retriever;
+    _enabled = false;
+    _zone4Enabled = true; // Zone 4 默认开启
+    constructor(dbPathOrRetriever) {
+        if (typeof dbPathOrRetriever === 'string') {
+            this.retriever = new Fts5Retriever(dbPathOrRetriever);
+        }
+        else {
+            this.retriever = dbPathOrRetriever;
+        }
+    }
+    // ── 状态管理 ──────────────────────────────────────────────────────
+    get enabled() {
+        return this._enabled && this._zone4Enabled;
+    }
+    enable() {
+        this._enabled = true;
+    }
+    disable() {
+        this._enabled = false;
+    }
+    setZone4Enabled(v) {
+        this._zone4Enabled = v;
+        if (!v)
+            this._enabled = false;
+    }
+    get zone4Enabled() {
+        return this._zone4Enabled;
+    }
+    // ── 存储/检索委托 ─────────────────────────────────────────────────
+    search(query, k = 5) {
+        return this.retriever.search(query, k);
+    }
+    add(title, content, source = '') {
+        return this.retriever.add({ id: '', title, content, source });
+    }
+    remove(id) {
+        return this.retriever.remove(id);
+    }
+    update(id, fields) {
+        return this.retriever.update(id, fields);
+    }
+    list() {
+        return this.retriever.list();
+    }
+    count() {
+        return this.retriever.count();
+    }
+    close() {
+        this.retriever.close();
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/knowledge/structured-store.d.ts

@@ -0,0 +1,78 @@
+/**
+ * StructuredStore — 结构化知识库存储层
+ *
+ * 核心设计：
+ *   entries 表存储 Agent 提炼后的结构化条目
+ *   tag 子串匹配为主检索（用户输入.includes(tag)）
+ *   FTS5 全文索引为兜底
+ */
+export type EntryCategory = 'api' | 'config' | 'guide' | 'reference' | 'code';
+export interface StructuredEntry {
+    id: string;
+    title: string;
+    tags: string[];
+    category: EntryCategory;
+    content: string;
+    ctx_before: string;
+    ctx_after: string;
+    refs: string[];
+    source: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface TagMatchResult {
+    entry: StructuredEntry;
+    score: number;
+    matchedTags: string[];
+}
+export declare class StructuredStore {
+    private db;
+    constructor(dbPath: string);
+    private initTables;
+    add(entry: {
+        id?: string;
+        title: string;
+        tags: string[];
+        category?: EntryCategory;
+        content: string;
+        ctx_before?: string;
+        ctx_after?: string;
+        refs?: string[];
+        source?: string;
+    }): string;
+    update(id: string, fields: Partial<{
+        title: string;
+        tags: string[];
+        category: EntryCategory;
+        content: string;
+        ctx_before: string;
+        ctx_after: string;
+        refs: string[];
+        source: string;
+    }>): boolean;
+    remove(id: string): boolean;
+    get(id: string): StructuredEntry | undefined;
+    list(category?: EntryCategory): StructuredEntry[];
+    count(): number;
+    /** 获取所有 tag（去重） */
+    getAllTags(): string[];
+    /**
+     * Tag 子串匹配（IDF 加权 + 多 tag 累加）。
+     * - 每个 tag 命中按 IDF 加权（稀有 tag 权重高，常见 tag 权重低）
+     * - 多个 tag 命中则分数累加
+     * - title 匹配额外加分（权重为查询命中的 30%）
+     * 返回按 score 降序排列的结果。
+     */
+    matchByTags(query: string): TagMatchResult[];
+    /** FTS5 全文搜索（兜底） */
+    searchFts(query: string, k?: number): StructuredEntry[];
+    /** refs 链式扩展 */
+    expandRefs(entries: StructuredEntry[]): StructuredEntry[];
+    /** 组合检索：tag 匹配 → FTS5 兜底 → refs 扩展 */
+    search(query: string, maxTotal?: number): TagMatchResult[];
+    /** 将检索结果格式化为 Zone 4 注入文本 */
+    formatResults(results: TagMatchResult[], maxMain?: number, maxRefs?: number): string;
+    private rowToEntry;
+    close(): void;
+}
+//# sourceMappingURL=structured-store.d.ts.map