hyacinth-ai 0.9.6

package/dist/knowledge/structured-store.js

@@ -0,0 +1,280 @@
+/**
+ * StructuredStore — 结构化知识库存储层
+ *
+ * 核心设计：
+ *   entries 表存储 Agent 提炼后的结构化条目
+ *   tag 子串匹配为主检索（用户输入.includes(tag)）
+ *   FTS5 全文索引为兜底
+ */
+import Database from 'better-sqlite3';
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+// ── Store ───────────────────────────────────────────────────────────
+export class StructuredStore {
+    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();
+    }
+    // ── 建表 ────────────────────────────────────────────────────────
+    initTables() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS entries (
+        id          TEXT PRIMARY KEY,
+        title       TEXT NOT NULL,
+        tags        TEXT NOT NULL DEFAULT '[]',
+        category    TEXT NOT NULL DEFAULT 'reference',
+        content     TEXT NOT NULL,
+        ctx_before  TEXT DEFAULT '',
+        ctx_after   TEXT DEFAULT '',
+        refs        TEXT NOT NULL DEFAULT '[]',
+        source      TEXT DEFAULT '',
+        created_at  TEXT DEFAULT (datetime('now')),
+        updated_at  TEXT DEFAULT (datetime('now'))
+      );
+      CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
+        title, content, ctx_before, ctx_after, tags,
+        content=entries,
+        content_rowid=rowid
+      );
+      CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+        INSERT INTO entries_fts(rowid, title, content, ctx_before, ctx_after, tags)
+        VALUES (new.rowid, new.title, new.content, new.ctx_before, new.ctx_after, new.tags);
+      END;
+      CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+        INSERT INTO entries_fts(entries_fts, rowid, title, content, ctx_before, ctx_after, tags)
+        VALUES('delete', old.rowid, old.title, old.content, old.ctx_before, old.ctx_after, old.tags);
+      END;
+      CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+        INSERT INTO entries_fts(entries_fts, rowid, title, content, ctx_before, ctx_after, tags)
+        VALUES('delete', old.rowid, old.title, old.content, old.ctx_before, old.ctx_after, old.tags);
+        INSERT INTO entries_fts(rowid, title, content, ctx_before, ctx_after, tags)
+        VALUES (new.rowid, new.title, new.content, new.ctx_before, new.ctx_after, new.tags);
+      END;
+    `);
+    }
+    // ── CRUD ────────────────────────────────────────────────────────
+    add(entry) {
+        const id = entry.id || crypto.randomUUID();
+        const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        this.db.prepare(`
+      INSERT INTO entries (id, title, tags, category, content, ctx_before, ctx_after, refs, source, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, entry.title, JSON.stringify(entry.tags), entry.category || 'reference', entry.content, entry.ctx_before || '', entry.ctx_after || '', JSON.stringify(entry.refs || []), entry.source || '', now, now);
+        return id;
+    }
+    update(id, fields) {
+        const sets = [];
+        const vals = [];
+        for (const [k, v] of Object.entries(fields)) {
+            if (v !== undefined) {
+                sets.push(`${k} = ?`);
+                vals.push(k === 'tags' || k === 'refs' ? JSON.stringify(v) : v);
+            }
+        }
+        if (sets.length === 0)
+            return false;
+        sets.push("updated_at = datetime('now')");
+        vals.push(id);
+        const r = this.db.prepare(`UPDATE entries SET ${sets.join(', ')} WHERE id = ?`).run(...vals);
+        return r.changes > 0;
+    }
+    remove(id) {
+        const r = this.db.prepare('DELETE FROM entries WHERE id = ?').run(id);
+        return r.changes > 0;
+    }
+    get(id) {
+        const row = this.db.prepare('SELECT * FROM entries WHERE id = ?').get(id);
+        return row ? this.rowToEntry(row) : undefined;
+    }
+    list(category) {
+        if (category) {
+            return this.db.prepare('SELECT * FROM entries WHERE category = ? ORDER BY updated_at DESC').all(category)
+                .map(r => this.rowToEntry(r));
+        }
+        return this.db.prepare('SELECT * FROM entries ORDER BY updated_at DESC').all()
+            .map(r => this.rowToEntry(r));
+    }
+    count() {
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM entries').get();
+        return row.cnt;
+    }
+    /** 获取所有 tag（去重） */
+    getAllTags() {
+        const rows = this.db.prepare('SELECT tags FROM entries').all();
+        const tagSet = new Set();
+        for (const r of rows) {
+            try {
+                const arr = JSON.parse(r.tags);
+                for (const t of arr)
+                    tagSet.add(t);
+            }
+            catch { /* skip malformed */ }
+        }
+        return [...tagSet];
+    }
+    // ── 检索 ────────────────────────────────────────────────────────
+    /**
+     * Tag 子串匹配（IDF 加权 + 多 tag 累加）。
+     * - 每个 tag 命中按 IDF 加权（稀有 tag 权重高，常见 tag 权重低）
+     * - 多个 tag 命中则分数累加
+     * - title 匹配额外加分（权重为查询命中的 30%）
+     * 返回按 score 降序排列的结果。
+     */
+    matchByTags(query) {
+        const entries = this.list();
+        if (entries.length === 0)
+            return [];
+        // 1. 计算每个 tag 的文档频率（DF）和逆文档频率（IDF）
+        const df = new Map();
+        for (const entry of entries) {
+            const seen = new Set();
+            for (const tag of entry.tags) {
+                if (!seen.has(tag)) {
+                    df.set(tag, (df.get(tag) ?? 0) + 1);
+                    seen.add(tag);
+                }
+            }
+        }
+        const N = entries.length;
+        const idf = new Map();
+        for (const [tag, freq] of df) {
+            // IDF 平滑：加一平滑避免 N=freq 时归零，设下限 0.5 保证最小权重
+            idf.set(tag, Math.max(Math.log((N + 1) / (freq + 0.5)), 0.5));
+        }
+        // 2. 打分：IDF 加权 × 基数 10，多 tag 命中累加
+        const results = [];
+        for (const entry of entries) {
+            let score = 0;
+            const matchedTags = [];
+            for (const tag of entry.tags) {
+                if (query.includes(tag)) {
+                    const weight = idf.get(tag) ?? 1;
+                    score += Math.round(10 * weight);
+                    matchedTags.push(tag);
+                }
+            }
+            // title 匹配 → 额外加分（权重为查询命中的 30%）
+            for (const tag of entry.tags) {
+                if (entry.title.includes(tag) && !matchedTags.includes(tag)) {
+                    const weight = idf.get(tag) ?? 1;
+                    score += Math.round(3 * weight);
+                }
+            }
+            if (score > 0) {
+                results.push({ entry, score, matchedTags });
+            }
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results;
+    }
+    /** FTS5 全文搜索（兜底） */
+    searchFts(query, k = 5) {
+        if (!query.trim())
+            return [];
+        const safe = query.replace(/["*()]/g, '').trim();
+        if (!safe)
+            return [];
+        try {
+            const rows = this.db.prepare(`
+        SELECT e.* FROM entries_fts f
+        JOIN entries e ON e.rowid = f.rowid
+        WHERE entries_fts MATCH ?
+        ORDER BY rank
+        LIMIT ?
+      `).all(safe, k);
+            return rows.map(r => this.rowToEntry(r));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** refs 链式扩展 */
+    expandRefs(entries) {
+        const seen = new Set(entries.map(e => e.id));
+        const extras = [];
+        for (const e of entries) {
+            for (const refId of e.refs) {
+                if (seen.has(refId))
+                    continue;
+                const ref = this.get(refId);
+                if (ref) {
+                    extras.push(ref);
+                    seen.add(refId);
+                }
+            }
+        }
+        return extras;
+    }
+    /** 组合检索：tag 匹配 → FTS5 兜底 → refs 扩展 */
+    search(query, maxTotal = 5) {
+        const tagResults = this.matchByTags(query);
+        // score > 0 即可纳入主结果，靠 IDF 排序 + maxTotal 截断保证精度
+        const main = tagResults.filter(r => r.score > 0);
+        if (main.length < 2) {
+            const ftsEntries = this.searchFts(query, maxTotal);
+            const existingIds = new Set(main.map(r => r.entry.id));
+            for (const e of ftsEntries) {
+                if (!existingIds.has(e.id)) {
+                    main.push({ entry: e, score: 5, matchedTags: [] });
+                    existingIds.add(e.id);
+                }
+            }
+        }
+        return main.slice(0, maxTotal);
+    }
+    // ── 格式化 ──────────────────────────────────────────────────────
+    /** 将检索结果格式化为 Zone 4 注入文本 */
+    formatResults(results, maxMain = 3, maxRefs = 2) {
+        if (results.length === 0)
+            return '';
+        const lines = ['── 以下内容来自知识库 ──', ''];
+        const main = results.slice(0, maxMain);
+        const refs = results.slice(maxMain, maxMain + maxRefs);
+        for (const r of main) {
+            const tags = r.matchedTags.length > 0 ? `匹配标签: ${r.matchedTags.join(', ')}` : 'FTS5 匹配';
+            lines.push(`━━ ${r.entry.id} ── [${r.entry.category}] ── ${tags}`);
+            lines.push(r.entry.content);
+            if (r.entry.ctx_before)
+                lines.push(`前置: ${r.entry.ctx_before}`);
+            if (r.entry.ctx_after)
+                lines.push(`后续: ${r.entry.ctx_after}`);
+            if (r.entry.refs.length > 0)
+                lines.push(`关联: ${r.entry.refs.join(', ')}`);
+            lines.push('');
+        }
+        if (refs.length > 0) {
+            lines.push('── 补充（关联条目）──');
+            for (const r of refs) {
+                lines.push(`· ${r.entry.id}: ${r.entry.title} — ${r.entry.content.slice(0, 100)}`);
+            }
+            lines.push('');
+        }
+        lines.push('── 知识库内容结束 ──');
+        return lines.join('\n');
+    }
+    // ── 内部 ────────────────────────────────────────────────────────
+    rowToEntry(row) {
+        return {
+            id: row.id,
+            title: row.title,
+            tags: JSON.parse(row.tags || '[]'),
+            category: row.category || 'reference',
+            content: row.content,
+            ctx_before: row.ctx_before || '',
+            ctx_after: row.ctx_after || '',
+            refs: JSON.parse(row.refs || '[]'),
+            source: row.source || '',
+            created_at: row.created_at || '',
+            updated_at: row.updated_at || '',
+        };
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=structured-store.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * 结构化知识库工具 — 合并为单一 kb_structured 工具，通过 action 参数区分操作。
+ *
+ *   add    — 结构化写入（1-10 条）
+ *   update — 更新条目
+ *   delete — 删除条目
+ *   list   — 列出条目
+ */
+import type { Tool } from '../tools/interface.js';
+import type { StructuredStore } from './structured-store.js';
+export declare function createStructuredTool(store: StructuredStore, enabled: () => boolean): Tool;
+//# sourceMappingURL=structured-tools.d.ts.map

package/dist/knowledge/structured-tools.js

@@ -0,0 +1,151 @@
+/**
+ * 结构化知识库工具 — 合并为单一 kb_structured 工具，通过 action 参数区分操作。
+ *
+ *   add    — 结构化写入（1-10 条）
+ *   update — 更新条目
+ *   delete — 删除条目
+ *   list   — 列出条目
+ */
+function guard(store, enabled) {
+    if (!enabled())
+        return '知识库未开启。请执行 /kb on。';
+    return null;
+}
+export function createStructuredTool(store, enabled) {
+    return {
+        name: 'kb_structured',
+        description: 'Manage structured knowledge entries. Supports 4 actions:\n' +
+            '  "add"    — add 1-10 entries at once. Use english_underscore ids, 2-5 tags, content ≤200 chars.\n' +
+            '  "update" — update an entry by id. Only pass the fields you want to change.\n' +
+            '  "delete" — delete an entry by id.\n' +
+            '  "list"   — list all entries, optionally filtered by category.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['add', 'update', 'delete', 'list'],
+                    description: '操作类型',
+                },
+                // ── add 参数 ──
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string', description: '唯一标识，英文下划线命名' },
+                            title: { type: 'string', description: '条目标题，一句话' },
+                            tags: { type: 'array', items: { type: 'string' }, description: '关键词标签，2-5 个' },
+                            category: { type: 'string', enum: ['api', 'config', 'guide', 'reference', 'code'], description: '分类' },
+                            content: { type: 'string', description: '核心内容，不超过 200 字' },
+                            ctx_before: { type: 'string', description: '前置上下文（可选）' },
+                            ctx_after: { type: 'string', description: '后续关联（可选）' },
+                            refs: { type: 'array', items: { type: 'string' }, description: '关联条目 ID 列表（可选）' },
+                            source: { type: 'string', description: '来源原始文件（可选）' },
+                        },
+                        required: ['id', 'title', 'tags', 'content'],
+                    },
+                    minItems: 1,
+                    maxItems: 10,
+                    description: '条目数组，1-10 条（action=add 时必填）',
+                },
+                // ── update / delete 参数 ──
+                id: { type: 'string', description: '条目 ID（action=update/delete 时必填）' },
+                title: { type: 'string', description: '新标题（action=update 时可选）' },
+                tags: { type: 'array', items: { type: 'string' }, description: '新标签（action=update 时可选）' },
+                category: { type: 'string', enum: ['api', 'config', 'guide', 'reference', 'code'], description: '分类（可选）' },
+                content: { type: 'string', description: '新内容（action=update 时可选）' },
+                ctx_before: { type: 'string', description: '前置上下文（action=update 时可选）' },
+                ctx_after: { type: 'string', description: '后续关联（action=update 时可选）' },
+                refs: { type: 'array', items: { type: 'string' }, description: '关联条目（action=update 时可选）' },
+                source: { type: 'string', description: '来源（action=update 时可选）' },
+            },
+            required: ['action'],
+        },
+        async execute(args) {
+            const blocked = guard(store, enabled);
+            if (blocked)
+                return blocked;
+            const action = args.action;
+            try {
+                switch (action) {
+                    case 'add':
+                        return handleAdd(store, args);
+                    case 'update':
+                        return handleUpdate(store, args);
+                    case 'delete':
+                        return handleDelete(store, args);
+                    case 'list':
+                        return handleList(store, args);
+                    default:
+                        return `Unknown action: "${action}". Supported: add, update, delete, list.`;
+                }
+            }
+            catch (err) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+// ── 各 action 实现 ──────────────────────────────────────────────────────
+function handleAdd(store, args) {
+    const entries = args.entries;
+    if (!entries || !Array.isArray(entries) || entries.length === 0) {
+        return 'Error: entries 数组不能为空，至少提供 1 条。';
+    }
+    let added = 0;
+    const ids = [];
+    for (const e of entries) {
+        store.add({
+            id: e.id,
+            title: e.title,
+            tags: e.tags,
+            category: e.category,
+            content: e.content,
+            ctx_before: e.ctx_before,
+            ctx_after: e.ctx_after,
+            refs: e.refs,
+            source: e.source,
+        });
+        added++;
+        ids.push(e.id);
+    }
+    return `已写入 ${added} 条。ID: ${ids.join(', ')}。当前共 ${store.count()} 条。`;
+}
+function handleUpdate(store, args) {
+    const id = args.id;
+    if (!id)
+        return 'Error: id 是必填项（action=update）。';
+    const existing = store.get(id);
+    if (!existing)
+        return `未找到条目 "${id}"。使用 kb_structured action=list 查看可用 ID。`;
+    const fields = {};
+    for (const k of ['title', 'tags', 'category', 'content', 'ctx_before', 'ctx_after', 'refs', 'source']) {
+        if (args[k] !== undefined)
+            fields[k] = args[k];
+    }
+    const ok = store.update(id, fields);
+    return ok ? `已更新: ${id}` : `更新失败: ${id}`;
+}
+function handleDelete(store, args) {
+    const id = args.id;
+    if (!id)
+        return 'Error: id 是必填项（action=delete）。';
+    const existing = store.get(id);
+    if (!existing)
+        return `未找到条目 "${id}"。`;
+    store.remove(id);
+    return `已删除: "${existing.title || id}"。当前共 ${store.count()} 条。`;
+}
+function handleList(store, args) {
+    const cat = args.category;
+    const entries = store.list(cat);
+    if (entries.length === 0)
+        return '知识库为空。使用 kb_structured action=add 添加条目。';
+    const lines = entries.map(e => {
+        const tags = e.tags.join(', ');
+        return `- \`${e.id}\` [${e.category}] **${e.title}** — ${e.content.slice(0, 80)}${e.content.length > 80 ? '...' : ''} | tags: ${tags}`;
+    });
+    return `共 ${entries.length} 条：\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=structured-tools.js.map

package/dist/knowledge/tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 知识库工具 — 暴露给 LLM 的操作接口
+ *
+ * kb_add    — 导入文件/文件夹
+ * kb_list   — 列出所有已索引文档
+ * kb_delete — 删除指定文档（同时清理 files/ 中的文件）
+ * kb_update — 重新索引（可选路径，不传则全量同步 files/ 目录）
+ *
+ * 所有工具在知识库关闭时统一返回提示，模型无法绕过。
+ */
+import type { Tool } from '../tools/interface.js';
+import type { KnowledgeBase } from './store.js';
+export declare function createKbAddTool(kb: KnowledgeBase, kbFilesDir?: string): Tool;
+export declare function createKbListTool(kb: KnowledgeBase): Tool;
+export declare function createKbDeleteTool(kb: KnowledgeBase, kbFilesDir?: string): Tool;
+export declare function createKbUpdateTool(kb: KnowledgeBase, kbFilesDir?: string): Tool;
+export declare function createKbToggleTool(kb: KnowledgeBase, contextComposer?: {
+    activeConditions: Set<string>;
+}): Tool;
+//# sourceMappingURL=tools.d.ts.map