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

package/dist/services/QuestionService.js

@@ -0,0 +1,457 @@
+/**
+ * 问题服务：把「要不要交接 / 要不要登记这个目录 / 确认一下」变成**对象**（PRD D22 / F-I9）。
+ *
+ * 一个问题的四件事实都在这里：有 id、有状态、有生命周期、可持久化。多端看到的是同一个
+ * 对象（库里那一行），所以「另一个窗口已经答过了」这件事不需要另开一条同步通道 ——
+ * 第二次拉 `question.list` 就能看到状态变了。
+ *
+ * 三条贯穿本文件的边界：
+ *
+ * 1. **存码不存句子**（D8）：`questions.payload` 里存的是文案键 + 参数 + 候选项的值，
+ *    读出时按调用方给的语言渲染。一条问题存死一种语言，换个连接就错了。
+ * 2. **答完之后接着往下走**（D22）：`answer` 的副作用是宿主自己做掉的 —— 答「自交接 /
+ *    独立摘要」就当场开始交接，客户端不必再发一次 `handoff.start`。
+ * 3. **越线两端都拒绝时问题继续挂着**（D23 / F-D10）：答不下去的那些路径（对话正在跑、
+ *    已经过了硬线而用户选了「就在这段里继续」）都不动这一行状态，所以问题不会被悄悄关掉。
+ *    本文件里没有「自动过期」「答错一次就作废」这类隐式转移。
+ */
+import { randomUUID } from "node:crypto";
+import { DEFAULT_LANGUAGE, hasMessage, render } from "../i18n/index.js";
+import { HostError } from "../wire/errors.js";
+import { QUESTION_KINDS } from "../wire/states.js";
+import { readUsage } from "./MessageService.js";
+/** 交接问题的三个候选值（F-D2：自交接 / 独立摘要 / 不交接） */
+export const HANDOFF_OPTION_SELF = "self";
+export const HANDOFF_OPTION_SUMMARY = "summary";
+export const HANDOFF_OPTION_DECLINE = "decline";
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+/** 缺省挡不挡着对话：问题就是为「停下来问」而造的，默认挡着，除非创建时显式说不管 */
+function defaultBlocking(_kind) {
+    return true;
+}
+/** 一个 JSON 值是不是普通对象（解析库里的列用） */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * 库里那列 JSON → 打字过的载荷。
+ *
+ * 读不出来时给一份「只有码、没有候选」的形状而不是抛错：一行被手改坏的提问不该让整个
+ * `question.list` 打不开，界面上至少能显示 id 与状态。
+ */
+function toStoredPayload(value, fallbackCode) {
+    if (!isRecord(value)) {
+        return {
+            code: fallbackCode,
+            prompt: { messageKey: "question.blocking", params: {} },
+            options: [],
+            blocking: false,
+            data: {},
+        };
+    }
+    const prompt = isRecord(value.prompt) ? value.prompt : {};
+    const options = Array.isArray(value.options) ? value.options : [];
+    return {
+        code: typeof value.code === "string" ? value.code : fallbackCode,
+        prompt: {
+            messageKey: typeof prompt.messageKey === "string" ? prompt.messageKey : "question.blocking",
+            params: isRecord(prompt.params) ? prompt.params : {},
+        },
+        options: options.filter(isRecord).map((option) => ({
+            value: typeof option.value === "string" ? option.value : "",
+            label: isRecord(option.label)
+                ? {
+                    messageKey: typeof option.label.messageKey === "string"
+                        ? option.label.messageKey
+                        : "question.blocking",
+                    params: isRecord(option.label.params) ? option.label.params : {},
+                }
+                : { messageKey: "question.blocking", params: {} },
+            detail: isRecord(option.detail)
+                ? {
+                    messageKey: typeof option.detail.messageKey === "string"
+                        ? option.detail.messageKey
+                        : "question.blocking",
+                    params: isRecord(option.detail.params) ? option.detail.params : {},
+                }
+                : null,
+        })),
+        blocking: value.blocking === true,
+        data: isRecord(value.data) ? value.data : {},
+    };
+}
+/** 库里那列 answer 的 JSON → 打字过的回答 */
+function toStoredAnswer(value) {
+    if (!isRecord(value) || typeof value.value !== "string")
+        return null;
+    return {
+        value: value.value,
+        answeredBy: typeof value.answeredBy === "string" ? value.answeredBy : null,
+    };
+}
+/** 渲染一句话（键认不出来时退回「被这个问题挡住了」那句，至少说明有东西在等回答） */
+function localizeText(code, source, language) {
+    const messageKey = hasMessage(source.messageKey)
+        ? source.messageKey
+        : "question.blocking";
+    return {
+        code,
+        messageKey,
+        params: source.params,
+        message: render(language, messageKey, source.params),
+    };
+}
+/** 一行库记录 → 契约上的问题对象（按给定语言渲染） */
+function toView(question, language) {
+    const payload = toStoredPayload(question.payload, `question.${question.kind}`);
+    const answer = toStoredAnswer(question.answer);
+    const options = payload.options.map((option) => ({
+        value: option.value,
+        label: localizeText(payload.code, option.label, language),
+        detail: option.detail === null ? null : localizeText(payload.code, option.detail, language),
+    }));
+    const view = {
+        id: question.id,
+        conversationId: question.conversationId,
+        kind: question.kind,
+        state: question.state,
+        prompt: localizeText(payload.code, payload.prompt, language),
+        options,
+        answer: answer === null
+            ? null
+            : {
+                value: answer.value,
+                answeredAt: iso(question.answeredAt ?? question.updatedAt),
+                answeredBy: answer.answeredBy,
+            },
+        blocking: payload.blocking,
+        createdAt: iso(question.createdAt),
+        updatedAt: iso(question.updatedAt),
+    };
+    return view;
+}
+export class QuestionService {
+    questions;
+    runs;
+    guard;
+    handoff;
+    emit;
+    now;
+    newId;
+    constructor(deps) {
+        this.questions = deps.questions;
+        this.runs = deps.runs;
+        this.guard = deps.guard;
+        this.handoff = deps.handoff;
+        this.emit = deps.emit;
+        this.now = deps.now ?? Date.now;
+        this.newId = deps.newId ?? randomUUID;
+    }
+    /**
+     * 问一个问题（内部入口）。
+     *
+     * 先落库再推事件：库里那一行是「多端看同一个」的真相（D22），推送只是提醒在线的那几个
+     * 窗口去拉（L5 断线即作废）。
+     */
+    async ask(input, language = DEFAULT_LANGUAGE) {
+        if (!QUESTION_KINDS.includes(input.kind)) {
+            throw new HostError("invalid_params", {
+                params: { field: "kind" },
+                detail: { field: "kind", value: input.kind, kinds: QUESTION_KINDS },
+            });
+        }
+        if (!hasMessage(input.prompt.messageKey)) {
+            throw new HostError("invalid_params", {
+                params: { field: "prompt" },
+                detail: { field: "prompt", reason: "unknown_message_key" },
+            });
+        }
+        if (input.options.length === 0) {
+            throw new HostError("invalid_params", {
+                params: { field: "options" },
+                detail: { field: "options", reason: "empty" },
+            });
+        }
+        const seen = new Set();
+        for (const option of input.options) {
+            if (option.value.trim().length === 0 || seen.has(option.value)) {
+                throw new HostError("invalid_params", {
+                    params: { field: "options" },
+                    detail: { field: "options", reason: "duplicate_or_empty_value", value: option.value },
+                });
+            }
+            seen.add(option.value);
+            if (!hasMessage(option.label.messageKey)) {
+                throw new HostError("invalid_params", {
+                    params: { field: "options" },
+                    detail: { field: "options", reason: "unknown_message_key", value: option.value },
+                });
+            }
+        }
+        const payload = {
+            code: input.code ?? input.prompt.messageKey,
+            prompt: { messageKey: input.prompt.messageKey, params: input.prompt.params ?? {} },
+            options: input.options.map((option) => ({
+                value: option.value,
+                label: { messageKey: option.label.messageKey, params: option.label.params ?? {} },
+                detail: option.detail === undefined || option.detail === null
+                    ? null
+                    : { messageKey: option.detail.messageKey, params: option.detail.params ?? {} },
+            })),
+            blocking: input.blocking ?? defaultBlocking(input.kind),
+            data: input.data ?? {},
+        };
+        const id = this.newId();
+        const createdAt = this.now();
+        await this.questions.create({
+            id,
+            conversationId: input.conversationId,
+            kind: input.kind,
+            payload,
+            state: "pending",
+            createdAt,
+        });
+        const stored = await this.questions.get(id);
+        if (!stored) {
+            throw new HostError("internal", { detail: { reason: "question vanished after insert", id } });
+        }
+        const view = toView(stored, language);
+        this.emit?.("question", { question: view, at: iso(createdAt) });
+        return view;
+    }
+    /**
+     * 到交接线时问「自交接 / 独立摘要 / 不交接」（PRD F-D2 / D22）。
+     *
+     * 触发点在**对话停下之后**：这里只负责把问题摆出来，不参与任何流式过程。
+     * `percent` 是给人看的那个数（用量 / 交接线），数字本身留在库里与状态里。
+     */
+    async askHandoff(input, language = DEFAULT_LANGUAGE) {
+        const percent = input.handoffTokens > 0
+            ? Math.min(999, Math.round((input.promptTokens / input.handoffTokens) * 100))
+            : 100;
+        return await this.ask({
+            conversationId: input.conversationId,
+            kind: "handoff",
+            code: "question.handoff.prompt",
+            prompt: { messageKey: "question.handoff.prompt", params: { percent } },
+            options: [
+                {
+                    value: HANDOFF_OPTION_SELF,
+                    label: { messageKey: "question.handoff.self" },
+                    detail: { messageKey: "question.handoff.selfDetail" },
+                },
+                {
+                    value: HANDOFF_OPTION_SUMMARY,
+                    label: { messageKey: "question.handoff.summary" },
+                    detail: { messageKey: "question.handoff.summaryDetail" },
+                },
+                { value: HANDOFF_OPTION_DECLINE, label: { messageKey: "question.handoff.decline" } },
+            ],
+            blocking: input.blocking ?? true,
+        }, language);
+    }
+    /**
+     * 列出问题（PRD D22：多端看同一个）。
+     *
+     * `conversationId` 可选（R61）：给了就只看那段对话的；不给就看全库（含没挂对话的那些，
+     * 例如「要不要把这个目录登记成项目」）。`state` 两种情况下都生效。
+     */
+    async list(params = {}, language = DEFAULT_LANGUAGE) {
+        const conversationId = typeof params.conversationId === "string" ? params.conversationId.trim() : "";
+        const rows = conversationId.length > 0
+            ? await this.questions.listByConversation(conversationId, params.state)
+            : await this.questions.listAll(params.state);
+        return { questions: rows.map((row) => toView(row, language)) };
+    }
+    /** 这段对话上还挂着、且正在挡着它的那些问题（`conversation.send` 的前置检查用它） */
+    async blockingQuestions(conversationId) {
+        const rows = await this.questions.listByConversation(conversationId, "pending");
+        return rows
+            .map((row) => toView(row, DEFAULT_LANGUAGE))
+            .filter((view) => view.blocking);
+    }
+    /**
+     * 有挡着的问题就拒绝（PRD D23 / F-D10 的「宿主也拒绝」）。
+     *
+     * 只在真有 `blocking` 的问题时抛 `question_pending`，并把那条问题的提问当参数带上：
+     * 用户看到的是「哪个问题在挡着」，不是一句抽象的「还有问题没答」。
+     */
+    async assertSendable(conversationId) {
+        const blocking = await this.blockingQuestions(conversationId);
+        const first = blocking[0];
+        if (!first)
+            return;
+        throw new HostError("question_pending", {
+            params: { question: first.prompt.message },
+            detail: { conversationId, questionId: first.id, kind: first.kind },
+        });
+    }
+    /**
+     * 回答一个问题（PRD D22 / F-I9）。
+     *
+     * 顺序是刻意的：
+     *   1. 已经答过 / 已失效的直接回当前状态（多端同时点，后到的那一端看到的是「已经答了」，
+     *      不重复触发副作用）；
+     *   2. 值不在候选里 → `invalid_params`；
+     *   3. 对话正在跑一轮 → `busy`（D22：交接在对话停下之后触发，不在流式中途）；
+     *   4. 过了硬线又选了「就在这段里继续」 → `context_guard`，**问题继续挂着**（D23）；
+     *   5. 改状态 → 该交接就当场交接。
+     *
+     * 第 3、4 两步都在写状态之前返回，所以「答不下去」不会把问题弄成一个半答的中间态。
+     */
+    async answer(params, context = {}) {
+        const language = context.language ?? DEFAULT_LANGUAGE;
+        const question = await this.requireQuestion(params.questionId);
+        const value = typeof params.value === "string" ? params.value.trim() : "";
+        if (value.length === 0) {
+            throw new HostError("invalid_params", {
+                params: { field: "value" },
+                detail: { field: "value", reason: "empty" },
+            });
+        }
+        const payload = toStoredPayload(question.payload, `question.${question.kind}`);
+        if (question.state !== "pending") {
+            // 已经在别处答过（或已作废）：不报错、不重复触发副作用，回当前状态
+            return { question: toView(question, language), effects: noEffects() };
+        }
+        const chosen = payload.options.find((option) => option.value === value);
+        if (!chosen) {
+            throw new HostError("invalid_params", {
+                params: { field: "value" },
+                detail: { field: "value", value, options: payload.options.map((option) => option.value) },
+            });
+        }
+        const conversationId = question.conversationId;
+        if (this.runs?.isRunning(conversationId) === true) {
+            throw new HostError("busy", {
+                detail: { conversationId, questionId: question.id, reason: "turn_in_flight" },
+            });
+        }
+        const kind = question.kind;
+        const handoffMode = handoffModeOf(kind, value);
+        const continuesHere = kind === "handoff" && handoffMode === null;
+        if (continuesHere && this.guard) {
+            if (await this.guard.overGuard(conversationId)) {
+                // D23：越过硬线，宿主也拒绝；这一行**不动**，问题继续挂着等人处理
+                throw new HostError("context_guard", {
+                    detail: {
+                        conversationId,
+                        questionId: question.id,
+                        reason: "over_guard",
+                        nextStep: "handoff",
+                    },
+                });
+            }
+        }
+        const answeredAt = this.now();
+        const answer = { value, answeredBy: context.answeredBy ?? null };
+        const patch = {
+            state: "answered",
+            answer,
+            answeredAt,
+            updatedAt: answeredAt,
+        };
+        await this.questions.update(question.id, patch);
+        const answeredRow = await this.questions.get(question.id);
+        const view = toView(answeredRow ?? question, language);
+        this.emit?.("question", { question: view, at: iso(answeredAt) });
+        const effects = await this.applyEffects({ kind, value, handoffMode, conversationId, data: payload.data }, language);
+        return { question: view, effects };
+    }
+    /**
+     * 显式取消一个问题（生命周期里的 `cancelled`）。
+     *
+     * 只有调用方明确要关掉时才用（例如对话被删、工作流换了方向）。没有任何自动取消的路径 ——
+     * 越线拒绝之后问题要继续挂着（D23），所以「答不下去」与「关掉它」是两件事。
+     */
+    async cancel(questionId, language = DEFAULT_LANGUAGE) {
+        const question = await this.requireQuestion(questionId);
+        const cancelledAt = this.now();
+        await this.questions.update(question.id, { state: "cancelled", updatedAt: cancelledAt });
+        const row = await this.questions.get(question.id);
+        const view = toView(row ?? question, language);
+        this.emit?.("question", { question: view, at: iso(cancelledAt) });
+        return view;
+    }
+    /**
+     * 答完之后接着往下走：交接（D22）。
+     *
+     * 只在问题已经落成 `answered` 之后才跑：答不下去的那些情况（越线、对话在跑）
+     * 在写状态之前就返回了，所以这里不需要再判断一遍。
+     */
+    async applyEffects(input, language) {
+        if (input.kind !== "handoff" || input.handoffMode === null || !this.handoff) {
+            return noEffects();
+        }
+        try {
+            const started = await this.handoff.start({
+                conversationId: input.conversationId,
+                mode: input.handoffMode,
+                then: "new_conversation",
+            }, language);
+            return { handoffStarted: true, newConversationId: started.newConversationId };
+        }
+        catch (error) {
+            // 用户取消了交接（F-D7：回到交接前，不重试、不报错）：问题已答，只是没有交出文档
+            if (HostError.is(error) && error.code === "handoff_declined") {
+                return noEffects();
+            }
+            throw error;
+        }
+    }
+    async requireQuestion(questionId) {
+        const id = typeof questionId === "string" ? questionId.trim() : "";
+        const row = id.length === 0 ? undefined : await this.questions.get(id);
+        if (!row) {
+            throw new HostError("not_found", {
+                params: { entity: "question" },
+                detail: { questionId },
+            });
+        }
+        return row;
+    }
+}
+/** 没有副作用 */
+function noEffects() {
+    return { handoffStarted: false, newConversationId: null };
+}
+/** 这个候选值要不要交接、用哪种执行者（只有交接问题有这一层语义） */
+function handoffModeOf(kind, value) {
+    if (kind !== "handoff")
+        return null;
+    if (value === HANDOFF_OPTION_SELF)
+        return "self";
+    if (value === HANDOFF_OPTION_SUMMARY)
+        return "summary";
+    return null;
+}
+/**
+ * 按配置与历史算「这段对话是不是已经过了硬线」。
+ *
+ * 硬线跟着模型走（`tokenThresholds.guard`，D27），用量取最近一条带用量的消息：
+ * 与 `conversation.state` 里那份 `ContextState` 是同一个口径（都看 `usage.prompt_tokens`）。
+ */
+export function createConversationGuardProbe(deps) {
+    return {
+        async overGuard(conversationId) {
+            const conversation = await deps.conversations.get(conversationId);
+            if (!conversation)
+                return false;
+            const config = await deps.configManager.read();
+            const model = config.models.find((candidate) => candidate.id === conversation.modelId);
+            const guardThreshold = model?.tokenThresholds.guard ?? 0;
+            if (guardThreshold <= 0)
+                return false;
+            const rows = await deps.messages.listByConversation(conversationId);
+            for (let index = rows.length - 1; index >= 0; index -= 1) {
+                const row = rows[index];
+                const usage = row ? readUsage(row.data) : null;
+                if (usage)
+                    return usage.prompt_tokens >= guardThreshold;
+            }
+            return false;
+        },
+    };
+}

package/dist/services/SearchService.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 搜索服务：按名称找对话、按聊天内容全文找消息，都能按 Workspace 过滤。
+ *
+ * 对应能力编号：F-C6 / D16（名称搜索 + 全文搜索 + 项目过滤；中文分词成本接受）。
+ *
+ * 两条实现上的边界：
+ *   1. 全文检索走 `MessageRepository.search`（FTS5 trigram，短查询它自己退化到 `LIKE`），
+ *      服务层不写 SQL、也不自己分词 —— 分词口径随库一起改。
+ *   2. 对话命中的形状要和侧栏一致（`ConversationSummary`），所以摘要由
+ *      {@link ConversationSummarizer} 注入，服务之间不各自拼一份。
+ */
+import type { ConversationRepository } from "../storage/ConversationRepository.js";
+import type { MessageRepository } from "../storage/MessageRepository.js";
+import type { Conversation } from "../storage/types.js";
+import type { ConversationSummary, SearchConversationsParams, SearchConversationsResult, SearchMessagesParams, SearchMessagesResult } from "../wire/index.js";
+/**
+ * 把一批对话行拼成侧栏摘要；入参顺序即出参顺序。
+ *
+ * 实现由 `ConversationService.summarize` 提供 —— 搜索命中里的对话与侧栏里的同一段对话，
+ * 必须长得一模一样（消息数、是否在跑、有没有问题挂着）。
+ */
+export type ConversationSummarizer = (rows: Conversation[]) => Promise<ConversationSummary[]>;
+/** 搜索服务依赖 */
+export interface SearchServiceDeps {
+    conversations: ConversationRepository;
+    messages: MessageRepository;
+    summarize: ConversationSummarizer;
+}
+export declare class SearchService {
+    private readonly conversationRepo;
+    private readonly messageRepo;
+    private readonly summarize;
+    constructor(deps: SearchServiceDeps);
+    /**
+     * 按名字搜对话（PRD F-C6 / D16）。
+     *
+     * 名字搜索走子串匹配而不是全文索引：名字短，还要能搜到一两个字的查询。空查询直接回空
+     * 结果（用户还没输入完），不当作错误。
+     */
+    conversations(params: SearchConversationsParams): Promise<SearchConversationsResult>;
+    /**
+     * 按聊天内容全文搜消息（PRD F-C6 / D16）。
+     *
+     * 过滤范围：给了 `conversationId` 就搜这一段对话，否则给了 `workspaceId` 就搜这个项目下
+     * 的全部对话，都没给就是不限范围。
+     *
+     * `offset` 由服务层切片：仓储的搜索按相关度/时间排好序后一次取 `offset + limit` 条，
+     * 这里再切掉前 `offset` 条。于是 `total` 在不超过「取数上限」时是准确的条数，超过时是
+     * 一个下界（仓储没有单独的数数入口，见 `docs/plan-questions.md`）。
+     */
+    messages(params: SearchMessagesParams): Promise<SearchMessagesResult>;
+    private scopeOf;
+    private toMessageHit;
+}

package/dist/services/SearchService.js

@@ -0,0 +1,117 @@
+/**
+ * 搜索服务：按名称找对话、按聊天内容全文找消息，都能按 Workspace 过滤。
+ *
+ * 对应能力编号：F-C6 / D16（名称搜索 + 全文搜索 + 项目过滤；中文分词成本接受）。
+ *
+ * 两条实现上的边界：
+ *   1. 全文检索走 `MessageRepository.search`（FTS5 trigram，短查询它自己退化到 `LIKE`），
+ *      服务层不写 SQL、也不自己分词 —— 分词口径随库一起改。
+ *   2. 对话命中的形状要和侧栏一致（`ConversationSummary`），所以摘要由
+ *      {@link ConversationSummarizer} 注入，服务之间不各自拼一份。
+ */
+import { HostError } from "../wire/errors.js";
+import { toCoreRole } from "./MessageService.js";
+/** 一次搜索默认返回多少条 */
+const DEFAULT_LIMIT = 20;
+/** 一次搜索最多返回多少条（再大对界面也没有意义，还会把传输撑起来） */
+const MAX_LIMIT = 100;
+/** 时间戳转 wire 上的 ISO 8601 */
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+/** `limit` 缺省与上限都收在这里，两个方法共用 */
+function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return DEFAULT_LIMIT;
+    return Math.min(Math.max(Math.trunc(limit), 1), MAX_LIMIT);
+}
+/** 名字里命中的那一段（供高亮）：找不到时回查询词本身 */
+function matchedSegment(name, query) {
+    const index = name.toLowerCase().indexOf(query.toLowerCase());
+    return index < 0 ? query : name.slice(index, index + query.length);
+}
+export class SearchService {
+    // 字段名带 `Repo` 后缀：`conversations` / `messages` 已经是方法名（对应 `search.*`）
+    conversationRepo;
+    messageRepo;
+    summarize;
+    constructor(deps) {
+        this.conversationRepo = deps.conversations;
+        this.messageRepo = deps.messages;
+        this.summarize = deps.summarize;
+    }
+    /**
+     * 按名字搜对话（PRD F-C6 / D16）。
+     *
+     * 名字搜索走子串匹配而不是全文索引：名字短，还要能搜到一两个字的查询。空查询直接回空
+     * 结果（用户还没输入完），不当作错误。
+     */
+    async conversations(params) {
+        const query = typeof params.query === "string" ? params.query.trim() : "";
+        if (query.length === 0)
+            return { hits: [] };
+        const rows = await this.conversationRepo.searchByName(query, params.workspaceId, clampLimit(params.limit));
+        const summaries = await this.summarize(rows);
+        if (summaries.length !== rows.length) {
+            throw new HostError("internal", {
+                detail: {
+                    reason: "summarizer returned a different number of rows",
+                    rows: rows.length,
+                    summaries: summaries.length,
+                },
+            });
+        }
+        return {
+            hits: rows.map((row, index) => ({
+                conversation: summaries[index],
+                matchedName: matchedSegment(row.name, query),
+            })),
+        };
+    }
+    /**
+     * 按聊天内容全文搜消息（PRD F-C6 / D16）。
+     *
+     * 过滤范围：给了 `conversationId` 就搜这一段对话，否则给了 `workspaceId` 就搜这个项目下
+     * 的全部对话，都没给就是不限范围。
+     *
+     * `offset` 由服务层切片：仓储的搜索按相关度/时间排好序后一次取 `offset + limit` 条，
+     * 这里再切掉前 `offset` 条。于是 `total` 在不超过「取数上限」时是准确的条数，超过时是
+     * 一个下界（仓储没有单独的数数入口，见 `docs/plan-questions.md`）。
+     */
+    async messages(params) {
+        const query = typeof params.query === "string" ? params.query.trim() : "";
+        if (query.length === 0)
+            return { hits: [], total: 0 };
+        const limit = clampLimit(params.limit);
+        const offset = params.offset === undefined || !Number.isFinite(params.offset)
+            ? 0
+            : Math.max(Math.trunc(params.offset), 0);
+        const scope = this.scopeOf(params);
+        const fetched = await this.messageRepo.search(scope, query, offset + limit);
+        const page = fetched.slice(offset);
+        const capped = fetched.length >= offset + limit;
+        return {
+            hits: page.map((hit) => this.toMessageHit(hit)),
+            total: capped ? offset + limit : fetched.length,
+        };
+    }
+    scopeOf(params) {
+        if (params.conversationId !== undefined && params.conversationId.length > 0) {
+            return { conversationId: params.conversationId };
+        }
+        if (params.workspaceId !== undefined && params.workspaceId.length > 0) {
+            return { workspaceId: params.workspaceId };
+        }
+        return undefined;
+    }
+    toMessageHit(hit) {
+        return {
+            conversationId: hit.conversationId,
+            conversationName: hit.conversationName,
+            messageId: hit.id,
+            role: toCoreRole(hit.role),
+            snippet: hit.snippet,
+            createdAt: iso(hit.createdAt),
+        };
+    }
+}