@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.0

package/dist/storage/AssetRepository.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 素材的三张表：`assets`（资源的唯一真相）、`conversation_assets`（谁引用了它）与
+ * `asset_vendor_files`（它的一部分可失效缓存）。
+ *
+ * 三张表的 SQL 放在同一个文件里，是因为它们的生命周期绑在一起，而另外两张都没有独立含义：
+ *
+ *   - `assets` 一行 = 数据根下一份文件 + 它的类型、大小、摘要、像素尺寸。`sha256` 全库唯一：
+ *     同一份字节在整台机器上只有一行、一份磁盘，所以这一行是「这张图是什么」的唯一答案。
+ *     它不记「属于哪段对话」——一张图可以同时被好几段对话引用。
+ *   - `conversation_assets` 一行 = 「某条消息引用了某份素材」。归属与「几张会话引用了它」都从
+ *     这张表算；消息被删（撤回 / 删对话）时关系行跟着级联消失，不需要谁去减计数。
+ *     `assetId` 用 `ON DELETE RESTRICT`：还有引用时素材行在库里删不掉（护栏）。
+ *   - `asset_vendor_files` 一行 = 「这个素材在这个端点上对应厂商的哪个 file_id」。厂商的
+ *     `file_id` 是端点维度资源，所以它只当缓存：删光也能从 `assets` 重建（下次发送时
+ *     重新上传一遍），`ON DELETE CASCADE` 让它跟着素材走。
+ *
+ * 存储层只做 SQL：不判断文件在不在、不上传、不决定「缓存能不能用」，也不判「该不该删字节」
+ * （那是素材服务的事：它按 {@link AssetRepository.countReferences} 的结果决定）。
+ */
+import type { Database } from "./Database.js";
+import type { AssetCreateInput, AssetRow, AssetVendorFileRow, AssetVendorFileUpsertInput, ConversationAssetRow } from "./types.js";
+/** 插入一个素材行的结果：`created` 为 false 说明库里已经有同摘要的那一行（全局去重命中） */
+export interface AssetUpsertOutcome {
+    row: AssetRow;
+    created: boolean;
+}
+/** 一个素材的缓存行分布（`describeVendorFiles` 的出参） */
+export interface AssetVendorFilePresence {
+    /** 这个端点上已经有缓存行 */
+    onEndpoint: boolean;
+    /** 别的端点上有 */
+    elsewhere: boolean;
+}
+export declare class AssetRepository {
+    private readonly db;
+    constructor(db: Database);
+    create(input: AssetCreateInput): Promise<void>;
+    /**
+     * 插入，但「库里已经有同摘要的那一行」时不报错、把既有行返回。
+     *
+     * 两个并发上传撞在一起（同一张图连传两次）时，唯一约束会挡住第二次插入；这时返回先到的那一行，
+     * 让上层把刚写出去的文件删掉即可 —— 而不是抛一个「库里已经有这条」的错误给用户。
+     *
+     * 两条语句走同一个 `tx`（声明式批次）：插入真正生效与否由第一条的结果决定，第二条只负责把
+     * 「现在库里是哪一行」读回来。
+     */
+    upsert(input: AssetCreateInput): Promise<AssetUpsertOutcome>;
+    get(id: string): Promise<AssetRow | undefined>;
+    /** 按内容摘要找：全局去重（`asset.begin` 带 sha256 时走这一条） */
+    findByDigest(sha256: string): Promise<AssetRow | undefined>;
+    /** 一段对话引用的全部素材（同一份素材被这段对话里两条消息引用时只出现一次） */
+    listByConversation(conversationId: string): Promise<AssetRow[]>;
+    /** 一条消息引用的全部素材 */
+    listByMessage(messageId: string): Promise<AssetRow[]>;
+    /**
+     * 记一行「这条消息引用了这份素材」。已经记过（同一 message + asset）时返回 0，
+     * 否则返回 1：消息落库那一刻扫 `content` 里的 `__asset_id` 写行，重复写是常态。
+     */
+    linkAsset(input: ConversationAssetRow): Promise<number>;
+    /** 这份素材被几行引用（含同一段对话里的多条消息） */
+    countReferences(assetId: string): Promise<number>;
+    /** 「几张会话引用了它」：`COUNT(DISTINCT conversationId)` */
+    countConversations(assetId: string): Promise<number>;
+    /** 一份素材被哪些对话引用（「贴到过哪几个项目」） */
+    listConversationIds(assetId: string): Promise<string[]>;
+    /** 一条消息引用了哪些素材 id（撤回要回填输入框时用；关系行随消息级联删除，先读一次） */
+    listAssetIdsByMessage(messageId: string): Promise<string[]>;
+    /** 一段对话引用过哪些素材 id（删对话前先读一次：删完之后关系行就没了） */
+    listAssetIdsByConversation(conversationId: string): Promise<string[]>;
+    delete(id: string): Promise<number>;
+    /**
+     * 归零才删：关系行还在时这条语句删不掉（`NOT EXISTS` 与 `ON DELETE RESTRICT` 是同一件事的
+     * 两道写法，前者让调用方拿到 0 行、后者保证真要删也不会带走别人的引用）。
+     */
+    deleteIfUnreferenced(id: string): Promise<number>;
+    /** 缓存命中：这个素材在这个端点上已经有厂商的 file_id */
+    getVendorFile(assetId: string, endpointId: string): Promise<AssetVendorFileRow | undefined>;
+    /** 写入（或覆盖）一条缓存行：同一对 `(assetId, endpointId)` 只有一行 */
+    upsertVendorFile(input: AssetVendorFileUpsertInput): Promise<void>;
+    /**
+     * 这个素材的缓存行分布：这个端点上有没有、别的端点上有没有。
+     *
+     * 两个事实一次查完，是因为它们要一起看才说得清该走哪条路：这个端点上有就是命中复用，
+     * 只有别的端点上有就是换过端点（不重传、走内联），都没有才上传。
+     */
+    describeVendorFiles(assetId: string, endpointId: string): Promise<AssetVendorFilePresence>;
+}

package/dist/storage/AssetRepository.js

@@ -0,0 +1,180 @@
+/**
+ * 素材的三张表：`assets`（资源的唯一真相）、`conversation_assets`（谁引用了它）与
+ * `asset_vendor_files`（它的一部分可失效缓存）。
+ *
+ * 三张表的 SQL 放在同一个文件里，是因为它们的生命周期绑在一起，而另外两张都没有独立含义：
+ *
+ *   - `assets` 一行 = 数据根下一份文件 + 它的类型、大小、摘要、像素尺寸。`sha256` 全库唯一：
+ *     同一份字节在整台机器上只有一行、一份磁盘，所以这一行是「这张图是什么」的唯一答案。
+ *     它不记「属于哪段对话」——一张图可以同时被好几段对话引用。
+ *   - `conversation_assets` 一行 = 「某条消息引用了某份素材」。归属与「几张会话引用了它」都从
+ *     这张表算；消息被删（撤回 / 删对话）时关系行跟着级联消失，不需要谁去减计数。
+ *     `assetId` 用 `ON DELETE RESTRICT`：还有引用时素材行在库里删不掉（护栏）。
+ *   - `asset_vendor_files` 一行 = 「这个素材在这个端点上对应厂商的哪个 file_id」。厂商的
+ *     `file_id` 是端点维度资源，所以它只当缓存：删光也能从 `assets` 重建（下次发送时
+ *     重新上传一遍），`ON DELETE CASCADE` 让它跟着素材走。
+ *
+ * 存储层只做 SQL：不判断文件在不在、不上传、不决定「缓存能不能用」，也不判「该不该删字节」
+ * （那是素材服务的事：它按 {@link AssetRepository.countReferences} 的结果决定）。
+ */
+const COLUMNS = "id, name, path, mime, bytes, sha256, width, height, createdAt";
+const VENDOR_COLUMNS = "assetId, endpointId, vendorFileId, createdAt";
+export class AssetRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        await this.db.run(`INSERT INTO assets (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+            input.id,
+            input.name ?? null,
+            input.path,
+            input.mime,
+            input.bytes,
+            input.sha256,
+            input.width ?? null,
+            input.height ?? null,
+            input.createdAt,
+        ]);
+    }
+    /**
+     * 插入，但「库里已经有同摘要的那一行」时不报错、把既有行返回。
+     *
+     * 两个并发上传撞在一起（同一张图连传两次）时，唯一约束会挡住第二次插入；这时返回先到的那一行，
+     * 让上层把刚写出去的文件删掉即可 —— 而不是抛一个「库里已经有这条」的错误给用户。
+     *
+     * 两条语句走同一个 `tx`（声明式批次）：插入真正生效与否由第一条的结果决定，第二条只负责把
+     * 「现在库里是哪一行」读回来。
+     */
+    async upsert(input) {
+        const [inserted, found] = await this.db.tx((tx) => [
+            tx.run(`INSERT INTO assets (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (sha256) DO NOTHING`, [
+                input.id,
+                input.name ?? null,
+                input.path,
+                input.mime,
+                input.bytes,
+                input.sha256,
+                input.width ?? null,
+                input.height ?? null,
+                input.createdAt,
+            ]),
+            tx.get(`SELECT ${COLUMNS} FROM assets WHERE sha256 = ?`, [input.sha256]),
+        ]);
+        if (!found) {
+            // 插入没成功又没有既有行：只可能是唯一约束之外的原因被 DO NOTHING 吞掉了，如实报错
+            throw new Error("asset upsert produced no row");
+        }
+        return { row: found, created: inserted.changes > 0 };
+    }
+    async get(id) {
+        return this.db.get(`SELECT ${COLUMNS} FROM assets WHERE id = ?`, [id]);
+    }
+    /** 按内容摘要找：全局去重（`asset.begin` 带 sha256 时走这一条） */
+    async findByDigest(sha256) {
+        return this.db.get(`SELECT ${COLUMNS} FROM assets WHERE sha256 = ?`, [sha256]);
+    }
+    /** 一段对话引用的全部素材（同一份素材被这段对话里两条消息引用时只出现一次） */
+    async listByConversation(conversationId) {
+        return this.db.all(`SELECT DISTINCT ${columnList("a")}
+         FROM assets a
+         JOIN conversation_assets ca ON ca.assetId = a.id
+        WHERE ca.conversationId = ?
+        ORDER BY a.createdAt ASC, a.id ASC`, [conversationId]);
+    }
+    /** 一条消息引用的全部素材 */
+    async listByMessage(messageId) {
+        return this.db.all(`SELECT DISTINCT ${columnList("a")}
+         FROM assets a
+         JOIN conversation_assets ca ON ca.assetId = a.id
+        WHERE ca.messageId = ?
+        ORDER BY a.createdAt ASC, a.id ASC`, [messageId]);
+    }
+    /**
+     * 记一行「这条消息引用了这份素材」。已经记过（同一 message + asset）时返回 0，
+     * 否则返回 1：消息落库那一刻扫 `content` 里的 `__asset_id` 写行，重复写是常态。
+     */
+    async linkAsset(input) {
+        const result = await this.db.run(`INSERT INTO conversation_assets (conversationId, messageId, assetId, createdAt)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (messageId, assetId) DO NOTHING`, [input.conversationId, input.messageId, input.assetId, input.createdAt]);
+        return result.changes;
+    }
+    /** 这份素材被几行引用（含同一段对话里的多条消息） */
+    async countReferences(assetId) {
+        const row = await this.db.get("SELECT COUNT(*) AS n FROM conversation_assets WHERE assetId = ?", [assetId]);
+        return row?.n ?? 0;
+    }
+    /** 「几张会话引用了它」：`COUNT(DISTINCT conversationId)` */
+    async countConversations(assetId) {
+        const row = await this.db.get("SELECT COUNT(DISTINCT conversationId) AS n FROM conversation_assets WHERE assetId = ?", [assetId]);
+        return row?.n ?? 0;
+    }
+    /** 一份素材被哪些对话引用（「贴到过哪几个项目」） */
+    async listConversationIds(assetId) {
+        const rows = await this.db.all(`SELECT DISTINCT conversationId FROM conversation_assets
+        WHERE assetId = ?
+        ORDER BY conversationId ASC`, [assetId]);
+        return rows.map((row) => row.conversationId);
+    }
+    /** 一条消息引用了哪些素材 id（撤回要回填输入框时用；关系行随消息级联删除，先读一次） */
+    async listAssetIdsByMessage(messageId) {
+        const rows = await this.db.all(`SELECT DISTINCT assetId FROM conversation_assets
+        WHERE messageId = ?
+        ORDER BY assetId ASC`, [messageId]);
+        return rows.map((row) => row.assetId);
+    }
+    /** 一段对话引用过哪些素材 id（删对话前先读一次：删完之后关系行就没了） */
+    async listAssetIdsByConversation(conversationId) {
+        const rows = await this.db.all(`SELECT DISTINCT assetId FROM conversation_assets
+        WHERE conversationId = ?
+        ORDER BY assetId ASC`, [conversationId]);
+        return rows.map((row) => row.assetId);
+    }
+    async delete(id) {
+        const result = await this.db.run("DELETE FROM assets WHERE id = ?", [id]);
+        return result.changes;
+    }
+    /**
+     * 归零才删：关系行还在时这条语句删不掉（`NOT EXISTS` 与 `ON DELETE RESTRICT` 是同一件事的
+     * 两道写法，前者让调用方拿到 0 行、后者保证真要删也不会带走别人的引用）。
+     */
+    async deleteIfUnreferenced(id) {
+        const result = await this.db.run(`DELETE FROM assets
+        WHERE id = ?
+          AND NOT EXISTS (SELECT 1 FROM conversation_assets WHERE assetId = ?)`, [id, id]);
+        return result.changes;
+    }
+    // -------------------------------------------------------------------------
+    // 厂商文件 id 的缓存（asset_vendor_files）
+    // -------------------------------------------------------------------------
+    /** 缓存命中：这个素材在这个端点上已经有厂商的 file_id */
+    async getVendorFile(assetId, endpointId) {
+        return this.db.get(`SELECT ${VENDOR_COLUMNS} FROM asset_vendor_files WHERE assetId = ? AND endpointId = ?`, [assetId, endpointId]);
+    }
+    /** 写入（或覆盖）一条缓存行：同一对 `(assetId, endpointId)` 只有一行 */
+    async upsertVendorFile(input) {
+        await this.db.run(`INSERT INTO asset_vendor_files (${VENDOR_COLUMNS}) VALUES (?, ?, ?, ?)
+       ON CONFLICT (assetId, endpointId) DO UPDATE SET
+         vendorFileId = excluded.vendorFileId`, [input.assetId, input.endpointId, input.vendorFileId, input.createdAt]);
+    }
+    /**
+     * 这个素材的缓存行分布：这个端点上有没有、别的端点上有没有。
+     *
+     * 两个事实一次查完，是因为它们要一起看才说得清该走哪条路：这个端点上有就是命中复用，
+     * 只有别的端点上有就是换过端点（不重传、走内联），都没有才上传。
+     */
+    async describeVendorFiles(assetId, endpointId) {
+        const row = await this.db.get(`SELECT
+         EXISTS (SELECT 1 FROM asset_vendor_files WHERE assetId = ? AND endpointId = ?) AS onEndpoint,
+         EXISTS (SELECT 1 FROM asset_vendor_files WHERE assetId = ? AND endpointId <> ?) AS elsewhere`, [assetId, endpointId, assetId, endpointId]);
+        return { onEndpoint: row?.onEndpoint === 1, elsewhere: row?.elsewhere === 1 };
+    }
+}
+/** 给某个表别名拼一份带前缀的列名（join 时不能直接复用裸列名） */
+function columnList(alias) {
+    return COLUMNS.split(",")
+        .map((column) => `${alias}.${column.trim()}`)
+        .join(", ");
+}

package/dist/storage/ConversationRepository.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `conversations` 表仓储：只做 SQL，不含业务判断。
+ *
+ * 排序口径照 PRD D13：置顶优先，其次创建时间倒序。改名、活动、打开都**不**改变顺序，
+ * 所以 `orderBy` 里没有 `updatedAt`。
+ */
+import type { Database } from "./Database.js";
+import type { Conversation, ConversationCreateInput } from "./types.js";
+export declare class ConversationRepository {
+    private readonly db;
+    constructor(db: Database);
+    /**
+     * 新建对话：名字是创建时按时间起的原名，所以 `nameIsAuto` 落 1（R35）。
+     * 用户改名与自动命名各有自己的方法，不从这条路径走。
+     */
+    create(input: ConversationCreateInput): Promise<void>;
+    get(id: string): Promise<Conversation | undefined>;
+    listByWorkspace(workspaceId: string): Promise<Conversation[]>;
+    /** 全部对话（跨 Workspace），排序口径同上 */
+    list(): Promise<Conversation[]>;
+    /**
+     * 用户改名（PRD F-C3）：名字归用户，`nameIsAuto` 置 0（R35）。
+     * 身份与顺序都不受影响（PRD D1 / D13），只记一次修改时间。
+     */
+    renameByUser(id: string, name: string, updatedAt: number): Promise<number>;
+    /**
+     * 自动命名（PRD D2）：写入起好的名字，并把它标成自动起的那一个（`nameIsAuto` = 1）。
+     *
+     * 与用户改名分开成两个方法：两者的差别只在 `nameIsAuto` 这一列，靠调用方选方法来表达
+     * 语义，读侧不必再猜名字是谁改的。
+     */
+    applyAutoName(id: string, name: string, updatedAt: number): Promise<number>;
+    setPinned(id: string, pinned: boolean, updatedAt: number): Promise<number>;
+    /**
+     * 换这段会话的模型，并把思考档位清空。
+     *
+     * 两句合成一条语句是故意的：档位属于模型（同一个档位名在不同模型的策略表里对应不同
+     * 参数），只改 `modelId` 不改档位会留下一个在新模型上说得通、参数却属于旧模型的档位。
+     */
+    setModel(id: string, modelId: string, updatedAt: number): Promise<number>;
+    /** 写这段会话的思考档位；`null` 表示回到「跟随助手定义」 */
+    setThinkingLevel(id: string, thinkingLevel: string | null, updatedAt: number): Promise<number>;
+    /** 只推进修改时间（新增消息等结构变化后调用） */
+    touch(id: string, updatedAt: number): Promise<number>;
+    /** 硬删对话（PRD D17），消息与素材行随之级联删除 */
+    delete(id: string): Promise<number>;
+    /**
+     * 按名字搜索（PRD D16 的「按名称」）。
+     *
+     * 名字搜索不走 FTS：名字短、还要支持只有一两个字的查询，`LIKE` 的子串语义正好对得上，
+     * 也省掉维护第二张 FTS 表。
+     */
+    searchByName(keyword: string, workspaceId: string | undefined, limit: number): Promise<Conversation[]>;
+    countByWorkspace(workspaceId: string): Promise<number>;
+}

package/dist/storage/ConversationRepository.js

@@ -0,0 +1,128 @@
+/**
+ * `conversations` 表仓储：只做 SQL，不含业务判断。
+ *
+ * 排序口径照 PRD D13：置顶优先，其次创建时间倒序。改名、活动、打开都**不**改变顺序，
+ * 所以 `orderBy` 里没有 `updatedAt`。
+ */
+/** 读写路径共用的列清单（顺序与 `toConversation` 的形状一致） */
+const COLUMNS = "id, workspaceId, name, nameIsAuto, pinned, agentId, modelId, thinkingLevel, createdAt, updatedAt";
+/** 列表/搜索统一用这个顺序：置顶在前，再按创建时间倒序（PRD D13） */
+const ORDER_BY = "ORDER BY pinned DESC, createdAt DESC, id DESC";
+function toConversation(row) {
+    return { ...row, pinned: row.pinned !== 0, nameIsAuto: row.nameIsAuto !== 0 };
+}
+/** LIKE 的通配符要转义，否则用户搜 "100%" 会变成任意匹配 */
+function escapeLike(keyword) {
+    return keyword.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+export class ConversationRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 新建对话：名字是创建时按时间起的原名，所以 `nameIsAuto` 落 1（R35）。
+     * 用户改名与自动命名各有自己的方法，不从这条路径走。
+     */
+    async create(input) {
+        const updatedAt = input.updatedAt ?? input.createdAt;
+        await this.db.run(`INSERT INTO conversations (${COLUMNS}) VALUES (?, ?, ?, 1, 0, ?, ?, ?, ?, ?)`, [
+            input.id,
+            input.workspaceId,
+            input.name,
+            input.agentId,
+            input.modelId,
+            input.thinkingLevel ?? null,
+            input.createdAt,
+            updatedAt,
+        ]);
+    }
+    async get(id) {
+        const row = await this.db.get(`SELECT ${COLUMNS} FROM conversations WHERE id = ?`, [id]);
+        return row ? toConversation(row) : undefined;
+    }
+    async listByWorkspace(workspaceId) {
+        const rows = await this.db.all(`SELECT ${COLUMNS} FROM conversations WHERE workspaceId = ? ${ORDER_BY}`, [workspaceId]);
+        return rows.map(toConversation);
+    }
+    /** 全部对话（跨 Workspace），排序口径同上 */
+    async list() {
+        const rows = await this.db.all(`SELECT ${COLUMNS} FROM conversations ${ORDER_BY}`);
+        return rows.map(toConversation);
+    }
+    /**
+     * 用户改名（PRD F-C3）：名字归用户，`nameIsAuto` 置 0（R35）。
+     * 身份与顺序都不受影响（PRD D1 / D13），只记一次修改时间。
+     */
+    async renameByUser(id, name, updatedAt) {
+        const result = await this.db.run("UPDATE conversations SET name = ?, nameIsAuto = 0, updatedAt = ? WHERE id = ?", [name, updatedAt, id]);
+        return result.changes;
+    }
+    /**
+     * 自动命名（PRD D2）：写入起好的名字，并把它标成自动起的那一个（`nameIsAuto` = 1）。
+     *
+     * 与用户改名分开成两个方法：两者的差别只在 `nameIsAuto` 这一列，靠调用方选方法来表达
+     * 语义，读侧不必再猜名字是谁改的。
+     */
+    async applyAutoName(id, name, updatedAt) {
+        const result = await this.db.run("UPDATE conversations SET name = ?, nameIsAuto = 1, updatedAt = ? WHERE id = ?", [name, updatedAt, id]);
+        return result.changes;
+    }
+    async setPinned(id, pinned, updatedAt) {
+        const result = await this.db.run("UPDATE conversations SET pinned = ?, updatedAt = ? WHERE id = ?", [pinned ? 1 : 0, updatedAt, id]);
+        return result.changes;
+    }
+    /**
+     * 换这段会话的模型，并把思考档位清空。
+     *
+     * 两句合成一条语句是故意的：档位属于模型（同一个档位名在不同模型的策略表里对应不同
+     * 参数），只改 `modelId` 不改档位会留下一个在新模型上说得通、参数却属于旧模型的档位。
+     */
+    async setModel(id, modelId, updatedAt) {
+        const result = await this.db.run("UPDATE conversations SET modelId = ?, thinkingLevel = NULL, updatedAt = ? WHERE id = ?", [modelId, updatedAt, id]);
+        return result.changes;
+    }
+    /** 写这段会话的思考档位；`null` 表示回到「跟随助手定义」 */
+    async setThinkingLevel(id, thinkingLevel, updatedAt) {
+        const result = await this.db.run("UPDATE conversations SET thinkingLevel = ?, updatedAt = ? WHERE id = ?", [thinkingLevel, updatedAt, id]);
+        return result.changes;
+    }
+    /** 只推进修改时间（新增消息等结构变化后调用） */
+    async touch(id, updatedAt) {
+        const result = await this.db.run("UPDATE conversations SET updatedAt = ? WHERE id = ?", [
+            updatedAt,
+            id,
+        ]);
+        return result.changes;
+    }
+    /** 硬删对话（PRD D17），消息与素材行随之级联删除 */
+    async delete(id) {
+        const result = await this.db.run("DELETE FROM conversations WHERE id = ?", [id]);
+        return result.changes;
+    }
+    /**
+     * 按名字搜索（PRD D16 的「按名称」）。
+     *
+     * 名字搜索不走 FTS：名字短、还要支持只有一两个字的查询，`LIKE` 的子串语义正好对得上，
+     * 也省掉维护第二张 FTS 表。
+     */
+    async searchByName(keyword, workspaceId, limit) {
+        const pattern = `%${escapeLike(keyword)}%`;
+        if (workspaceId === undefined) {
+            const rows = await this.db.all(`SELECT ${COLUMNS} FROM conversations
+         WHERE name LIKE ? ESCAPE '\\'
+         ${ORDER_BY}
+         LIMIT ?`, [pattern, limit]);
+            return rows.map(toConversation);
+        }
+        const rows = await this.db.all(`SELECT ${COLUMNS} FROM conversations
+       WHERE workspaceId = ? AND name LIKE ? ESCAPE '\\'
+       ${ORDER_BY}
+       LIMIT ?`, [workspaceId, pattern, limit]);
+        return rows.map(toConversation);
+    }
+    async countByWorkspace(workspaceId) {
+        const row = await this.db.get("SELECT count(*) AS n FROM conversations WHERE workspaceId = ?", [workspaceId]);
+        return row?.n ?? 0;
+    }
+}

package/dist/storage/CredentialRepository.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `credentials` 表仓储：凭证的多串管理（PRD L11：可多串、带备注、可单独吊销）。
+ *
+ * 只存 sha256 摘要：明文只存在于生成它的那一层（创建时返回一次给用户），
+ * 存储层既不生成明文、也不还原明文。
+ */
+import type { Database } from "./Database.js";
+import type { CredentialCreateInput, CredentialInfo, CredentialRow } from "./types.js";
+/**
+ * 凭证摘要：sha256 十六进制。
+ *
+ * 上下游都按同一个口径算，所以这函数放在存储层旁边 —— 校验方（接线的鉴权）与写入方
+ * 用同一份实现，不会出现一边加盐一边不加这种对不上的情况。
+ */
+export declare function hashCredential(token: string): string;
+export declare class CredentialRepository {
+    private readonly db;
+    constructor(db: Database);
+    create(input: CredentialCreateInput): Promise<void>;
+    get(id: string): Promise<CredentialRow | undefined>;
+    /** 列出全部凭证（含已吊销的），不含 hash —— 展示层不需要它 */
+    list(): Promise<CredentialInfo[]>;
+    /** 按摘要找一串仍然有效的凭证（鉴权用） */
+    findActiveByHash(hash: string): Promise<CredentialRow | undefined>;
+    /** 吊销（不删行：留着能看出「这串曾经存在过」） */
+    revoke(id: string, revokedAt: number): Promise<number>;
+    countActive(): Promise<number>;
+}

package/dist/storage/CredentialRepository.js

@@ -0,0 +1,47 @@
+/**
+ * `credentials` 表仓储：凭证的多串管理（PRD L11：可多串、带备注、可单独吊销）。
+ *
+ * 只存 sha256 摘要：明文只存在于生成它的那一层（创建时返回一次给用户），
+ * 存储层既不生成明文、也不还原明文。
+ */
+import { createHash } from "node:crypto";
+const COLUMNS = "id, note, hash, createdAt, revokedAt";
+const INFO_COLUMNS = "id, note, createdAt, revokedAt";
+/**
+ * 凭证摘要：sha256 十六进制。
+ *
+ * 上下游都按同一个口径算，所以这函数放在存储层旁边 —— 校验方（接线的鉴权）与写入方
+ * 用同一份实现，不会出现一边加盐一边不加这种对不上的情况。
+ */
+export function hashCredential(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+export class CredentialRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        await this.db.run(`INSERT INTO credentials (${COLUMNS}) VALUES (?, ?, ?, ?, NULL)`, [input.id, input.note, input.hash, input.createdAt]);
+    }
+    async get(id) {
+        return this.db.get(`SELECT ${COLUMNS} FROM credentials WHERE id = ?`, [id]);
+    }
+    /** 列出全部凭证（含已吊销的），不含 hash —— 展示层不需要它 */
+    async list() {
+        return this.db.all(`SELECT ${INFO_COLUMNS} FROM credentials ORDER BY createdAt ASC, id ASC`);
+    }
+    /** 按摘要找一串仍然有效的凭证（鉴权用） */
+    async findActiveByHash(hash) {
+        return this.db.get(`SELECT ${COLUMNS} FROM credentials WHERE hash = ? AND revokedAt IS NULL`, [hash]);
+    }
+    /** 吊销（不删行：留着能看出「这串曾经存在过」） */
+    async revoke(id, revokedAt) {
+        const result = await this.db.run("UPDATE credentials SET revokedAt = ? WHERE id = ? AND revokedAt IS NULL", [revokedAt, id]);
+        return result.changes;
+    }
+    async countActive() {
+        const row = await this.db.get("SELECT count(*) AS n FROM credentials WHERE revokedAt IS NULL");
+        return row?.n ?? 0;
+    }
+}

package/dist/storage/Database.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 数据库门面：对外只有 `all` / `get` / `run` / `tx` / `close` 五个异步方法，内部把每条
+ * 请求变成一条 worker 消息，交给 `dbWorker.ts` 在独立线程里用同步的 `DatabaseSync` 执行。
+ *
+ * 主线程因此完全不碰 SQL 执行：不会阻塞事件循环，也不会有「一个慢查询卡住所有 WebSocket
+ * 连接」这种事。
+ *
+ * 实例由创建者持有并注入给各 Repository（依赖从单根出发），本模块不导出任何模块级单例。
+ */
+import type { SQLInputValue } from "node:sqlite";
+/** 写语句的返回（worker 侧已把 bigint 转成 number，可安全跨线程传输） */
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number;
+}
+/** 事务里一条语句的执行方式：整表读、单行读、写 */
+export type TxKind = "all" | "get" | "run";
+/**
+ * 在 `tx` 回调里登记一条语句后拿到的凭据：批次跑完后靠它把结果从 `tx` 的返回值里取出来。
+ *
+ * `index` 是这条语句在批次里的位置。`output` 只在类型上标记「这条语句会产出什么形状」，
+ * 运行时是 `undefined`，不参与跨线程传输。
+ */
+export interface TxStatement<T> {
+    readonly index: number;
+    readonly output?: T;
+}
+/**
+ * `tx` 回调拿到的客户端：`all` / `get` / `run` 都只是**登记**语句，按登记顺序排进同一批。
+ *
+ * 批次在回调返回后一次性送进 worker，在同一个事务里串行执行；读到的值由回调返回哪几条
+ * 凭据决定（返回凭据数组 → 拿到等长的结果，返回单条凭据 → 拿到单条结果，什么都不返回 →
+ * 只是一批写）。回调自己抛错时批次还没发出去，库里不会有任何改动。
+ */
+export interface TxClient {
+    all<T>(sql: string, params?: SQLInputValue[]): TxStatement<T[]>;
+    get<T>(sql: string, params?: SQLInputValue[]): TxStatement<T | undefined>;
+    run(sql: string, params?: SQLInputValue[]): TxStatement<RunResult>;
+}
+/** 回调能返回的东西：不关心结果、一条语句的凭据、或一组凭据 */
+export type TxPlan = TxStatement<unknown> | readonly TxStatement<unknown>[] | void;
+/** 单条凭据对应结果的类型 */
+export type TxValue<S> = S extends TxStatement<infer R> ? R : never;
+/**
+ * `tx` 的返回值：回调返回一组凭据时是等长的结果元组，返回单条凭据时是那条的结果，
+ * 什么都不返回时是 `void`。
+ */
+export type TxOutcome<S extends TxPlan> = S extends readonly TxStatement<unknown>[] ? {
+    [K in keyof S]: TxValue<S[K]>;
+} : S extends TxStatement<unknown> ? TxValue<S> : void;
+export declare class Database {
+    private readonly dbPath;
+    private worker;
+    private nextId;
+    private readonly pending;
+    private closed;
+    private closing;
+    /** @param dbPath SQLite 数据库文件路径 */
+    constructor(dbPath: string);
+    /** 多行查询 */
+    all<T>(sql: string, params?: SQLInputValue[]): Promise<T[]>;
+    /** 单行查询；没有命中的行时返回 `undefined` */
+    get<T>(sql: string, params?: SQLInputValue[]): Promise<T | undefined>;
+    /** 写语句（INSERT / UPDATE / DELETE） */
+    run(sql: string, params?: SQLInputValue[]): Promise<RunResult>;
+    /**
+     * 事务：回调里用 `client.all` / `get` / `run` 登记语句，回调返回后整批在 worker 里
+     * `BEGIN IMMEDIATE` → 按登记顺序逐条执行 → `COMMIT`，任一条失败就整体 ROLLBACK。
+     *
+     * 回调返回的凭据决定拿回哪些结果，所以「先读后写」是一次往返、一个事务：
+     *
+     * ```ts
+     * const [found, written] = await db.tx((q) => [
+     *   q.get<{ n: number }>("SELECT n FROM t WHERE id = ?", [id]),
+     *   q.run("UPDATE t SET n = n + 1 WHERE id = ?", [id]),
+     * ]);
+     * ```
+     *
+     * 回调抛错时还什么都没发出去，等于什么都没写，直接向上抛。
+     */
+    tx<const S extends TxPlan>(fn: (client: TxClient) => S | Promise<S>): Promise<TxOutcome<S>>;
+    /**
+     * 关闭：先拒绝所有挂起的请求、把实例标记为已关闭（之后任何调用都直接 reject），
+     * 再请 worker 关库退出；worker 没在超时内退出就强制终止，避免 `close()` 自己悬挂。
+     */
+    close(): Promise<void>;
+    private doClose;
+    private assertOpen;
+    /** 统一执行通道：分配请求 id、挂起 Promise、把消息交给 worker */
+    private dispatch;
+    /** 懒启动：第一次真正要碰数据库时才起 worker */
+    private workerHandle;
+    private settle;
+    private failAll;
+}