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

package/dist/storage/Database.js

@@ -0,0 +1,180 @@
+/**
+ * 数据库门面：对外只有 `all` / `get` / `run` / `tx` / `close` 五个异步方法，内部把每条
+ * 请求变成一条 worker 消息，交给 `dbWorker.ts` 在独立线程里用同步的 `DatabaseSync` 执行。
+ *
+ * 主线程因此完全不碰 SQL 执行：不会阻塞事件循环，也不会有「一个慢查询卡住所有 WebSocket
+ * 连接」这种事。
+ *
+ * 实例由创建者持有并注入给各 Repository（依赖从单根出发），本模块不导出任何模块级单例。
+ */
+import { Worker } from "node:worker_threads";
+/**
+ * worker 入口的文件名：源码直接跑（vitest / 类型剥离）时同目录是 `.ts`，产物里是 `.js`。
+ * 按当前模块自身的扩展名推导，两种运行方式都能找到同一个 worker。
+ */
+function resolveWorkerUrl() {
+    const self = new URL(import.meta.url);
+    const extension = self.pathname.endsWith(".ts") ? ".ts" : ".js";
+    return new URL(`./dbWorker${extension}`, self);
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+function isStatementList(value) {
+    return Array.isArray(value);
+}
+/** 按凭据里的下标把结果对回调用方；下标越界说明凭据不是这一批登记的，直接报错 */
+function pickResult(statement, results) {
+    if (statement.index >= results.length) {
+        throw new Error(`tx 结果缺少第 ${statement.index} 条语句（本批共 ${results.length} 条）`);
+    }
+    return results[statement.index];
+}
+function pickOutcome(plan, results) {
+    if (plan === undefined)
+        return undefined;
+    if (isStatementList(plan))
+        return plan.map((statement) => pickResult(statement, results));
+    return pickResult(plan, results);
+}
+export class Database {
+    dbPath;
+    worker = null;
+    nextId = 1;
+    pending = new Map();
+    closed = false;
+    closing = null;
+    /** @param dbPath SQLite 数据库文件路径 */
+    constructor(dbPath) {
+        this.dbPath = dbPath;
+    }
+    /** 多行查询 */
+    all(sql, params = []) {
+        return this.dispatch({ kind: "all", sql, params });
+    }
+    /** 单行查询；没有命中的行时返回 `undefined` */
+    get(sql, params = []) {
+        return this.dispatch({ kind: "get", sql, params });
+    }
+    /** 写语句（INSERT / UPDATE / DELETE） */
+    run(sql, params = []) {
+        return this.dispatch({ kind: "run", sql, params });
+    }
+    /**
+     * 事务：回调里用 `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]),
+     * ]);
+     * ```
+     *
+     * 回调抛错时还什么都没发出去，等于什么都没写，直接向上抛。
+     */
+    async tx(fn) {
+        this.assertOpen();
+        const batch = [];
+        const register = (kind, sql, params) => {
+            const index = batch.length;
+            batch.push({ kind, sql, params });
+            return { index };
+        };
+        const client = {
+            all: (sql, params = []) => register("all", sql, params),
+            get: (sql, params = []) => register("get", sql, params),
+            run: (sql, params = []) => register("run", sql, params),
+        };
+        const plan = await fn(client);
+        const results = batch.length === 0
+            ? []
+            : (await this.dispatch({ kind: "batch", statements: batch }));
+        return pickOutcome(plan, results);
+    }
+    /**
+     * 关闭：先拒绝所有挂起的请求、把实例标记为已关闭（之后任何调用都直接 reject），
+     * 再请 worker 关库退出；worker 没在超时内退出就强制终止，避免 `close()` 自己悬挂。
+     */
+    close() {
+        this.closing ??= this.doClose();
+        return this.closing;
+    }
+    async doClose() {
+        this.closed = true;
+        const worker = this.worker;
+        this.worker = null;
+        // 关库时仍在排队的请求一律以「已关闭」失败，不让调用方拿到永远不 resolve 的 Promise
+        this.failAll(new Error("Database 已关闭，不再接受调用"));
+        if (!worker)
+            return;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                void worker.terminate().then(() => resolve(), () => resolve());
+            }, 2000);
+            worker.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            try {
+                worker.postMessage({ id: this.nextId++, kind: "close" });
+            }
+            catch {
+                void worker.terminate().then(() => resolve(), () => resolve());
+            }
+        });
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error("Database 已关闭，不再接受调用");
+    }
+    /** 统一执行通道：分配请求 id、挂起 Promise、把消息交给 worker */
+    dispatch(payload) {
+        if (this.closed)
+            return Promise.reject(new Error("Database 已关闭，不再接受调用"));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            try {
+                this.workerHandle().postMessage({ ...payload, id });
+            }
+            catch (error) {
+                // 消息本身没发出去（worker 已终止等），立刻失败，不留悬挂项
+                this.pending.delete(id);
+                reject(toError(error));
+            }
+        });
+    }
+    /** 懒启动：第一次真正要碰数据库时才起 worker */
+    workerHandle() {
+        if (this.worker)
+            return this.worker;
+        const worker = new Worker(resolveWorkerUrl(), {
+            workerData: { dbPath: this.dbPath },
+        });
+        worker.on("message", (response) => this.settle(response));
+        // worker 崩溃 / 退出：把所有挂起请求 reject 掉，否则调用方会一直等下去
+        worker.on("error", (error) => this.failAll(toError(error)));
+        worker.on("exit", () => this.failAll(new Error("SQLite worker 已退出")));
+        this.worker = worker;
+        return worker;
+    }
+    settle(response) {
+        const pending = this.pending.get(response.id);
+        if (!pending)
+            return; // 关闭流程里的回执等，没有对应的等待者
+        this.pending.delete(response.id);
+        if (response.ok)
+            pending.resolve(response.result);
+        else
+            pending.reject(new Error(response.error));
+    }
+    failAll(error) {
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
+        this.worker = null;
+    }
+}

package/dist/storage/MessageRepository.d.ts

@@ -0,0 +1,104 @@
+/**
+ * `messages` 表仓储：消息读写 + 全文检索。
+ *
+ * 三处与别处不同的地方：
+ *
+ * 1. **边流边写**：一轮生成过程中同一条助手消息会被反复写（PRD D15）。`upsert` 按 id
+ *    覆盖正文 / 状态 / omit，但 `seq` 与 `createdAt` 保留第一次写入时的值 —— 否则消息
+ *    会在流式过程中不断「往后跳」。
+ *
+ * 2. **全文检索的分词现实**：FTS5 表用 `tokenize='trigram'`（见 migrations.ts），
+ *    中文子串才搜得到；代价是查询词至少要 3 个字符，少于 3 个字符（典型是两字中文）
+ *    在 trigram 下必然搜不到，这里退化到 `LIKE` 子串匹配。
+ *
+ * 3. **子 Agent 的归属**：`parentToolCallId` 记下这条消息是被哪次工具调用派出去产生的
+ *    （R37）。怎么写入由上层决定，本文件提供按它取回的一段读取路径。
+ *
+ * 4. **`hidden` 的两条读数**：`hidden` 是 core 的 `Message.hidden`，落在 `data` 列的 JSON 里
+ *    （没有单独的列）。给用户看的读取路径（`message.list`、侧栏条数、删除代价）默认把它
+ *    排除；要连它一起取的地方（模型的历史、排查问题）显式传 `includeHidden`。
+ *
+ * FTS 索引的同步交给 `messages` 上的触发器（同样在 migrations.ts 里建），所以本文件
+ * 写消息时只写 `messages` 表，不需要额外维护索引。
+ */
+import type { Database } from "./Database.js";
+import type { MessageSearchHit, MessageSearchScope, MessageUpsertInput, StoredMessage } from "./types.js";
+/** 读消息时的选项 */
+export interface MessageListOptions {
+    /** 连 `hidden` 的消息一起取（默认不取：`hidden` 表示这条不给人看） */
+    includeHidden?: boolean;
+}
+export declare class MessageRepository {
+    private readonly db;
+    constructor(db: Database);
+    /**
+     * 写入或覆盖一条消息。
+     *
+     * 同一条消息（同 id）重复调用即「覆盖最新内容 + 状态」，`seq` / `createdAt` 不变。
+     */
+    upsert(input: MessageUpsertInput): Promise<void>;
+    /**
+     * 批量写入（一轮结束时的「写一次」）：整批放在一个事务里，避免中途断开留下半轮历史。
+     */
+    upsertMany(inputs: MessageUpsertInput[]): Promise<void>;
+    get(id: string): Promise<StoredMessage | undefined>;
+    /**
+     * 按对话取消息（architecture.md A12 的 `message.list` 口径）。
+     *
+     * - 不给 `after`：整段历史，按 `seq` 升序。
+     * - 给了 `after` 且这个 id 存在：**从它本身开始**（含它，内容是最新的）+ 之后全部。
+     *   故意不从它的下一条开始 —— 重连的客户端上次拿到的最后一条可能正是流式中那条，
+     *   它的内容已经变了，得重新拿最新的。
+     * - 给了 `after` 但库里没有这个 id（已删除、或换了库）：退回整段历史。
+     *
+     * 三条都只覆盖**主线**消息：子 Agent 的消息虽然落在同一张表，但它们属于另一次对话
+     * 与另一步执行（`parentToolCallId` 非空），回看走 {@link listByParentToolCallId}，
+     * 不能混进主线历史（否则模型下一轮会把别人的对话当成自己的上下文）。
+     *
+     * 三种情况收敛成一条 SQL：找不到时 `COALESCE` 把下界降成 -1，条件恒真。
+     *
+     * 这里数出来的是**主线**的条数（`parentToolCallId IS NULL` 那一半）：子 Agent 的消息落在同一张
+     * 表、但有非空的 `parentToolCallId`，不在本方法的结果里。同样是「这段对话有多少条消息」，
+     * {@link countByConversation} 数的是表里的全部行（不筛那一列，只筛 `hidden`），所以一段跑过
+     * 子 Agent 的对话，`listByConversation().length` 会小于 `countByConversation()`。
+     *
+     * `hidden` 的消息默认不在结果里（侧栏条数、`message.list` 都用这条默认）。要看的那一侧
+     * （模型的历史、排查）传 `includeHidden`。
+     */
+    listByConversation(conversationId: string, after?: string, options?: MessageListOptions): Promise<StoredMessage[]>;
+    /**
+     * 按父工具调用取子 Agent 的消息（R37 提供的存储能力）。
+     *
+     * 按对话限定范围：工具调用 id 只在它所属的那段对话里有意义。
+     */
+    listByParentToolCallId(conversationId: string, parentToolCallId: string, options?: MessageListOptions): Promise<StoredMessage[]>;
+    /**
+     * 全文搜索（PRD D16：按聊天内容、可只搜一个 Workspace）。
+     *
+     * @param scope 一段对话内 / 一个 Workspace 下 / 不限（`undefined` 由调用方显式传入
+     *              表示不限；本层不替调用方决定「不给条件就搜全库」是不是合理）
+     * @param keyword 查询词：长度 >= 3 走 FTS5 trigram，< 3 走 LIKE 子串
+     * @param limit 上限
+     */
+    search(scope: MessageSearchScope, keyword: string, limit: number): Promise<MessageSearchHit[]>;
+    /**
+     * 硬删一段对话里排在指定消息之后的消息（PRD D24 的撤回）。
+     * `includeSelf` 为真时连那条消息一起删。
+     *
+     * 锚点不在该对话里时 `seq` 子查询为 NULL，条件不成立，一条也不会删。
+     */
+    deleteAfter(conversationId: string, messageId: string, options?: {
+        includeSelf?: boolean;
+    }): Promise<number>;
+    /**
+     * 数一段对话在 `messages` 表里的全部行数（PRD D17 / F-F9 的代价一侧用它）。
+     *
+     * 与 {@link listByConversation} 的差别就在 `parentToolCallId` 这一列：本方法不筛它，所以子 Agent
+     * 的消息也算在内。同一个问题（「这段对话有多少条消息」）于是有两个不同的数，两处的用途不同：
+     * 这里要的是「删掉会让库里少多少行」，那边要的是「主线里能回看多少条」。
+     *
+     * `hidden` 的消息两边都不算：它在界面上从来没出现过，删掉它数进代价里会让用户看到
+     * 一个对不上的数字。
+     */
+    countByConversation(conversationId: string): Promise<number>;
+}

package/dist/storage/MessageRepository.js

@@ -0,0 +1,323 @@
+/**
+ * `messages` 表仓储：消息读写 + 全文检索。
+ *
+ * 三处与别处不同的地方：
+ *
+ * 1. **边流边写**：一轮生成过程中同一条助手消息会被反复写（PRD D15）。`upsert` 按 id
+ *    覆盖正文 / 状态 / omit，但 `seq` 与 `createdAt` 保留第一次写入时的值 —— 否则消息
+ *    会在流式过程中不断「往后跳」。
+ *
+ * 2. **全文检索的分词现实**：FTS5 表用 `tokenize='trigram'`（见 migrations.ts），
+ *    中文子串才搜得到；代价是查询词至少要 3 个字符，少于 3 个字符（典型是两字中文）
+ *    在 trigram 下必然搜不到，这里退化到 `LIKE` 子串匹配。
+ *
+ * 3. **子 Agent 的归属**：`parentToolCallId` 记下这条消息是被哪次工具调用派出去产生的
+ *    （R37）。怎么写入由上层决定，本文件提供按它取回的一段读取路径。
+ *
+ * 4. **`hidden` 的两条读数**：`hidden` 是 core 的 `Message.hidden`，落在 `data` 列的 JSON 里
+ *    （没有单独的列）。给用户看的读取路径（`message.list`、侧栏条数、删除代价）默认把它
+ *    排除；要连它一起取的地方（模型的历史、排查问题）显式传 `includeHidden`。
+ *
+ * FTS 索引的同步交给 `messages` 上的触发器（同样在 migrations.ts 里建），所以本文件
+ * 写消息时只写 `messages` 表，不需要额外维护索引。
+ */
+/** trigram 分词器能匹配的最小查询长度（按字符算，不是字节） */
+const TRIGRAM_MIN_LENGTH = 3;
+/** 搜索结果的片段长度上限 */
+const SNIPPET_LENGTH = 160;
+const COLUMNS = "id, conversationId, seq, role, status, omit, content, data, searchText, parentToolCallId, createdAt, updatedAt";
+/**
+ * 「这条消息给用户看」的条件：`data.hidden` 不为真。
+ *
+ * `hidden` 在 `data` 这列 JSON 里，所以判断要读一次 JSON。`data` 为空或不是合法 JSON 时
+ * 按「不是隐藏」算 —— 一条坏数据不该让整条消息在界面上凭空消失。
+ */
+const VISIBLE_ONLY = `(CASE WHEN json_valid(data) THEN json_extract(data, '$.hidden') ELSE 0 END) IS NOT 1`;
+/**
+ * 写入语句：`seq` 取同对话当前最大值 + 1；同一 id 再写时只覆盖内容类字段。
+ *
+ * `MAX(seq)` 与插入在同一条语句里完成，worker 又是单线程串行执行，所以不会出现两条
+ * 消息抢到同一个 seq（`UNIQUE (conversationId, seq)` 是最后一道防线）。
+ *
+ * `parentToolCallId` 在冲突分支里用 `COALESCE`：流式过程里同一条消息会被反复写，
+ * 不带上这一列的那些写不会把已经记下的归属抹掉。
+ */
+const UPSERT_SQL = `
+  INSERT INTO messages (${COLUMNS})
+  VALUES (
+    ?,
+    ?,
+    (SELECT COALESCE(MAX(seq), 0) + 1 FROM messages WHERE conversationId = ?),
+    ?, ?, ?, ?, ?, ?, ?,
+    ?, ?
+  )
+  ON CONFLICT (id) DO UPDATE SET
+    role             = excluded.role,
+    status           = excluded.status,
+    omit             = excluded.omit,
+    content          = excluded.content,
+    data             = excluded.data,
+    searchText       = excluded.searchText,
+    parentToolCallId = COALESCE(excluded.parentToolCallId, messages.parentToolCallId),
+    updatedAt        = excluded.updatedAt
+`;
+/**
+ * 从消息正文里抽出可检索的纯文本。
+ *
+ * 只取文本段：JSON 结构（工具调用的参数、用量等）不进索引，否则搜 "id"、"type"
+ * 这类词会把所有工具调用消息都捞出来，反而搜不准。
+ */
+function extractSearchText(content) {
+    if (content === null)
+        return "";
+    if (typeof content === "string")
+        return content;
+    const parts = [];
+    for (const section of content) {
+        // 库里的内容是外部写入的 JSON，形状不保证合 core 的类型：非文本段不参与索引
+        if (section.type === "text" && typeof section.text === "string")
+            parts.push(section.text);
+    }
+    return parts.join("\n");
+}
+function toSearchText(content) {
+    return extractSearchText(content).replace(/\s+/g, " ").trim();
+}
+function parseJson(value) {
+    if (value === null)
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        // 库里出现坏 JSON 时不让整条记录读不出来，原样当字符串返回
+        return value;
+    }
+}
+/**
+ * `content` 列的反序列化：core 的 `MessageContent` 就是「字符串，或内容段数组」。
+ *
+ * 两种形状原样返回（R30：不在仓储层重建内容段）；其它情况（空列、坏数据）归为「没有正文」。
+ */
+function toContent(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value;
+    return null;
+}
+function toStoredMessage(row) {
+    const data = parseJson(row.data);
+    return {
+        id: row.id,
+        conversationId: row.conversationId,
+        parentToolCallId: row.parentToolCallId,
+        seq: row.seq,
+        role: row.role,
+        status: row.status,
+        omit: row.omit !== 0,
+        content: toContent(parseJson(row.content)),
+        data: typeof data === "object" && data !== null && !Array.isArray(data)
+            ? data
+            : null,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}
+/** 建 upsert 的绑定参数数组（顺序与 UPSERT_SQL 的占位符一一对应） */
+function upsertParams(input) {
+    const searchText = toSearchText(input.content ?? null);
+    const contentJson = JSON.stringify(input.content ?? null);
+    const dataJson = input.data === undefined || input.data === null ? null : JSON.stringify(input.data);
+    return [
+        input.id,
+        input.conversationId,
+        input.conversationId,
+        input.role,
+        input.status,
+        input.omit ? 1 : 0,
+        contentJson,
+        dataJson,
+        searchText,
+        input.parentToolCallId ?? null,
+        input.createdAt,
+        input.createdAt,
+    ];
+}
+/** FTS5 的查询串：整体加引号当作短语，用户输入里的特殊符号就不会被当成查询语法 */
+function toMatchPhrase(keyword) {
+    return `"${keyword.replace(/"/g, '""')}"`;
+}
+/** LIKE 的通配符转义 */
+function escapeLike(keyword) {
+    return keyword.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+export class MessageRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 写入或覆盖一条消息。
+     *
+     * 同一条消息（同 id）重复调用即「覆盖最新内容 + 状态」，`seq` / `createdAt` 不变。
+     */
+    async upsert(input) {
+        await this.db.run(UPSERT_SQL, upsertParams(input));
+    }
+    /**
+     * 批量写入（一轮结束时的「写一次」）：整批放在一个事务里，避免中途断开留下半轮历史。
+     */
+    async upsertMany(inputs) {
+        if (inputs.length === 0)
+            return;
+        await this.db.tx((tx) => {
+            for (const input of inputs)
+                tx.run(UPSERT_SQL, upsertParams(input));
+        });
+    }
+    async get(id) {
+        const row = await this.db.get(`SELECT ${COLUMNS} FROM messages WHERE id = ?`, [id]);
+        return row ? toStoredMessage(row) : undefined;
+    }
+    /**
+     * 按对话取消息（architecture.md A12 的 `message.list` 口径）。
+     *
+     * - 不给 `after`：整段历史，按 `seq` 升序。
+     * - 给了 `after` 且这个 id 存在：**从它本身开始**（含它，内容是最新的）+ 之后全部。
+     *   故意不从它的下一条开始 —— 重连的客户端上次拿到的最后一条可能正是流式中那条，
+     *   它的内容已经变了，得重新拿最新的。
+     * - 给了 `after` 但库里没有这个 id（已删除、或换了库）：退回整段历史。
+     *
+     * 三条都只覆盖**主线**消息：子 Agent 的消息虽然落在同一张表，但它们属于另一次对话
+     * 与另一步执行（`parentToolCallId` 非空），回看走 {@link listByParentToolCallId}，
+     * 不能混进主线历史（否则模型下一轮会把别人的对话当成自己的上下文）。
+     *
+     * 三种情况收敛成一条 SQL：找不到时 `COALESCE` 把下界降成 -1，条件恒真。
+     *
+     * 这里数出来的是**主线**的条数（`parentToolCallId IS NULL` 那一半）：子 Agent 的消息落在同一张
+     * 表、但有非空的 `parentToolCallId`，不在本方法的结果里。同样是「这段对话有多少条消息」，
+     * {@link countByConversation} 数的是表里的全部行（不筛那一列，只筛 `hidden`），所以一段跑过
+     * 子 Agent 的对话，`listByConversation().length` 会小于 `countByConversation()`。
+     *
+     * `hidden` 的消息默认不在结果里（侧栏条数、`message.list` 都用这条默认）。要看的那一侧
+     * （模型的历史、排查）传 `includeHidden`。
+     */
+    async listByConversation(conversationId, after, options = {}) {
+        const rows = await this.db.all(`SELECT ${COLUMNS} FROM messages
+       WHERE conversationId = ?
+         AND parentToolCallId IS NULL
+         AND (? = 1 OR ${VISIBLE_ONLY})
+         AND (? IS NULL
+              OR seq >= COALESCE(
+                   (SELECT seq FROM messages WHERE id = ? AND conversationId = ?),
+                   -1))
+       ORDER BY seq ASC`, [
+            conversationId,
+            options.includeHidden === true ? 1 : 0,
+            after ?? null,
+            after ?? null,
+            conversationId,
+        ]);
+        return rows.map(toStoredMessage);
+    }
+    /**
+     * 按父工具调用取子 Agent 的消息（R37 提供的存储能力）。
+     *
+     * 按对话限定范围：工具调用 id 只在它所属的那段对话里有意义。
+     */
+    async listByParentToolCallId(conversationId, parentToolCallId, options = {}) {
+        const rows = await this.db.all(`SELECT ${COLUMNS} FROM messages
+       WHERE conversationId = ? AND parentToolCallId = ?
+         AND (? = 1 OR ${VISIBLE_ONLY})
+       ORDER BY seq ASC`, [conversationId, parentToolCallId, options.includeHidden === true ? 1 : 0]);
+        return rows.map(toStoredMessage);
+    }
+    /**
+     * 全文搜索（PRD D16：按聊天内容、可只搜一个 Workspace）。
+     *
+     * @param scope 一段对话内 / 一个 Workspace 下 / 不限（`undefined` 由调用方显式传入
+     *              表示不限；本层不替调用方决定「不给条件就搜全库」是不是合理）
+     * @param keyword 查询词：长度 >= 3 走 FTS5 trigram，< 3 走 LIKE 子串
+     * @param limit 上限
+     */
+    async search(scope, keyword, limit) {
+        const trimmed = keyword.trim();
+        if (trimmed.length === 0)
+            return [];
+        // 片段取命中位置前面 40 个字符开始的一小段；没命中（FTS 命中但整词不在、或极端长词）
+        // 就退回头部一小段。两处都写成 `m.searchText`：FTS 分支里两张表都有 searchText 列，
+        // 不限定会直接报 ambiguous column（歧义列）
+        const snippet = `CASE
+        WHEN instr(m.searchText, ?) > 0
+          THEN substr(m.searchText, max(1, instr(m.searchText, ?) - 40), ${SNIPPET_LENGTH})
+        ELSE substr(m.searchText, 1, ${SNIPPET_LENGTH})
+      END AS snippet`;
+        // trigram 至少要 3 个字符，短查询用它只会得到空结果，直接换 LIKE
+        const useFts = [...trimmed].length >= TRIGRAM_MIN_LENGTH;
+        const conditions = [];
+        const params = [];
+        if (useFts) {
+            conditions.push("messages_fts MATCH ?");
+            params.push(toMatchPhrase(trimmed));
+        }
+        else {
+            conditions.push("m.searchText LIKE ? ESCAPE '\\'");
+            params.push(`%${escapeLike(trimmed)}%`);
+        }
+        if (scope && "conversationId" in scope) {
+            conditions.push("m.conversationId = ?");
+            params.push(scope.conversationId);
+        }
+        else if (scope && "workspaceId" in scope) {
+            conditions.push("c.workspaceId = ?");
+            params.push(scope.workspaceId);
+        }
+        const sql = useFts
+            ? `SELECT m.id, m.conversationId, c.name AS conversationName, c.workspaceId AS workspaceId,
+                m.role, m.createdAt, ${snippet}
+         FROM messages_fts
+         JOIN messages m ON m.rowid = messages_fts.rowid
+         JOIN conversations c ON c.id = m.conversationId
+         WHERE ${conditions.join(" AND ")}
+         ORDER BY m.createdAt DESC, m.seq DESC
+         LIMIT ?`
+            : `SELECT m.id, m.conversationId, c.name AS conversationName, c.workspaceId AS workspaceId,
+                m.role, m.createdAt, ${snippet}
+         FROM messages m
+         JOIN conversations c ON c.id = m.conversationId
+         WHERE ${conditions.join(" AND ")}
+         ORDER BY m.createdAt DESC, m.seq DESC
+         LIMIT ?`;
+        return this.db.all(sql, [trimmed, trimmed, ...params, limit]);
+    }
+    /**
+     * 硬删一段对话里排在指定消息之后的消息（PRD D24 的撤回）。
+     * `includeSelf` 为真时连那条消息一起删。
+     *
+     * 锚点不在该对话里时 `seq` 子查询为 NULL，条件不成立，一条也不会删。
+     */
+    async deleteAfter(conversationId, messageId, options = {}) {
+        const comparison = options.includeSelf ? ">=" : ">";
+        const result = await this.db.run(`DELETE FROM messages
+       WHERE conversationId = ?
+         AND seq ${comparison} (
+           SELECT seq FROM messages WHERE id = ? AND conversationId = ?
+         )`, [conversationId, messageId, conversationId]);
+        return result.changes;
+    }
+    /**
+     * 数一段对话在 `messages` 表里的全部行数（PRD D17 / F-F9 的代价一侧用它）。
+     *
+     * 与 {@link listByConversation} 的差别就在 `parentToolCallId` 这一列：本方法不筛它，所以子 Agent
+     * 的消息也算在内。同一个问题（「这段对话有多少条消息」）于是有两个不同的数，两处的用途不同：
+     * 这里要的是「删掉会让库里少多少行」，那边要的是「主线里能回看多少条」。
+     *
+     * `hidden` 的消息两边都不算：它在界面上从来没出现过，删掉它数进代价里会让用户看到
+     * 一个对不上的数字。
+     */
+    async countByConversation(conversationId) {
+        const row = await this.db.get(`SELECT count(*) AS n FROM messages WHERE conversationId = ? AND ${VISIBLE_ONLY}`, [conversationId]);
+        return row?.n ?? 0;
+    }
+}

package/dist/storage/MetaRepository.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `meta` 表仓储：库自身的元信息（schema 版本、建库时间）。
+ *
+ * 表是单行表（`id` 固定 1）。版本号的推进只能由 `migrations.migrate` 在事务里完成，
+ * 这里只提供读取 —— 否则「结构没改、版本号先动了」这种状态很容易被别的代码造出来。
+ */
+import type { Database } from "./Database.js";
+import type { MetaRow } from "./types.js";
+export declare class MetaRepository {
+    private readonly db;
+    constructor(db: Database);
+    /**
+     * 当前 schema 版本。库里还没有 `meta` 表（全新库）时返回 0，
+     * 让 `migrate` 从第一级开始跑，而不是先抛一个「表不存在」。
+     */
+    getSchemaVersion(): Promise<number>;
+    /** 元信息整行；全新库（表或行还不存在）返回 `undefined` */
+    getState(): Promise<MetaRow | undefined>;
+    /** 表存不存在：全新库还没跑过任何迁移，直接查 `meta` 会报「no such table」 */
+    private hasMetaTable;
+}

package/dist/storage/MetaRepository.js

@@ -0,0 +1,33 @@
+/**
+ * `meta` 表仓储：库自身的元信息（schema 版本、建库时间）。
+ *
+ * 表是单行表（`id` 固定 1）。版本号的推进只能由 `migrations.migrate` 在事务里完成，
+ * 这里只提供读取 —— 否则「结构没改、版本号先动了」这种状态很容易被别的代码造出来。
+ */
+export class MetaRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 当前 schema 版本。库里还没有 `meta` 表（全新库）时返回 0，
+     * 让 `migrate` 从第一级开始跑，而不是先抛一个「表不存在」。
+     */
+    async getSchemaVersion() {
+        if (!(await this.hasMetaTable()))
+            return 0;
+        const row = await this.db.get("SELECT id, schemaVersion, createdAt FROM meta WHERE id = 1");
+        return row?.schemaVersion ?? 0;
+    }
+    /** 元信息整行；全新库（表或行还不存在）返回 `undefined` */
+    async getState() {
+        if (!(await this.hasMetaTable()))
+            return undefined;
+        return this.db.get("SELECT id, schemaVersion, createdAt FROM meta WHERE id = 1");
+    }
+    /** 表存不存在：全新库还没跑过任何迁移，直接查 `meta` 会报「no such table」 */
+    async hasMetaTable() {
+        const row = await this.db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'meta'");
+        return row !== undefined;
+    }
+}