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

package/dist/services/MessageService.js

@@ -0,0 +1,280 @@
+/**
+ * 消息服务：按对话读消息，以及把库里的一行还原成 core 的消息对象。
+ *
+ * 对应能力编号：A12 / L5（按消息 id 续拉：命中则从它开始且含它自身的最新内容，不命中返回全部）、
+ * F-C6（`around` 定位取窗，供客户端把搜索命中的那条摆到眼前）、F-I7（`toolCallId` 取子 Agent
+ * 自己的消息）、F-D9（会话创建时那条 `hidden` 的 cwd 消息默认不出网）、
+ * R21 / R22（消息原样用 core 的 `AgentNS.Message`，不额外挂时间戳这类外壳字段）。
+ *
+ * `toAgentMessage` 是这个仓库里「存储行 → core 消息」的唯一一份实现：对话服务算用量、判断
+ * 历史里有没有图也要走它，免得同一行在两处被读出两个样子。
+ *
+ * 正文不做转换（R30）：仓储反序列化出来的就是 core 的 `AgentNS.MessageContent`，这里原样
+ * 搬上消息。剩下要做的是把「列里的字符串」收敛成 core 的取值（角色 / 状态 / 结束原因）
+ * 与把 `data` 列的 JSON 逐字段收窄到 core 的类型。
+ */
+import { AgentNS } from "@ai-zen/agents-core";
+import { HostError } from "../wire/errors.js";
+/** 角色取值表：库里的字符串认不出来时归 `Unknown`，不猜 */
+const ROLES = [
+    AgentNS.Role.Unknown,
+    AgentNS.Role.System,
+    AgentNS.Role.User,
+    AgentNS.Role.Assistant,
+    AgentNS.Role.Function,
+    AgentNS.Role.Tool,
+];
+/** 状态取值表（D15：`status` 落盘，读回来要还原成 core 的那一套） */
+const STATUSES = [
+    AgentNS.MessageStatus.Unknown,
+    AgentNS.MessageStatus.Pending,
+    AgentNS.MessageStatus.Completed,
+    AgentNS.MessageStatus.Error,
+    AgentNS.MessageStatus.Aborted,
+    AgentNS.MessageStatus.Writing,
+];
+/** 结束原因取值表 */
+const FINISH_REASONS = [
+    AgentNS.FinishReason.Unknown,
+    AgentNS.FinishReason.Stop,
+    AgentNS.FinishReason.Length,
+    AgentNS.FinishReason.ContentFilter,
+    AgentNS.FinishReason.FunctionCall,
+    AgentNS.FinishReason.ToolCalls,
+];
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/** 可选的消息 id 参数：没给 / 空串一律当「没给」 */
+function idParam(value) {
+    const id = asString(value)?.trim() ?? "";
+    return id.length > 0 ? id : undefined;
+}
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+/** 用量：三个字段都是数字才算数（core 的 `Usage` 只有这三个字段） */
+function asUsage(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const source = value;
+    const prompt = source.prompt_tokens;
+    const completion = source.completion_tokens;
+    const total = source.total_tokens;
+    if (typeof prompt !== "number" || typeof completion !== "number" || typeof total !== "number") {
+        return undefined;
+    }
+    return { prompt_tokens: prompt, completion_tokens: completion, total_tokens: total };
+}
+function asFunctionCall(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const source = value;
+    const call = {};
+    const name = asString(source.name);
+    const args = asString(source.arguments);
+    if (name !== undefined)
+        call.name = name;
+    if (args !== undefined)
+        call.arguments = args;
+    return call;
+}
+/** 工具调用数组：逐项按 core 的字段抄，认不出的字段直接丢（不往消息上塞未知键） */
+function asToolCalls(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const calls = [];
+    for (const item of value) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const source = item;
+        const call = {};
+        if (typeof source.index === "number")
+            call.index = source.index;
+        const id = asString(source.id);
+        const type = asString(source.type);
+        const fn = asFunctionCall(source.function);
+        if (id !== undefined)
+            call.id = id;
+        if (type !== undefined)
+            call.type = type;
+        if (fn !== undefined)
+            call.function = fn;
+        calls.push(call);
+    }
+    return calls;
+}
+/** 库里的角色字符串 → core 的角色；搜索命中项也要用它，故对外导出 */
+export function toCoreRole(value) {
+    return ROLES.includes(value) ? value : AgentNS.Role.Unknown;
+}
+function toStatus(value) {
+    return STATUSES.includes(value)
+        ? value
+        : AgentNS.MessageStatus.Unknown;
+}
+function toFinishReason(value) {
+    return FINISH_REASONS.includes(value)
+        ? value
+        : AgentNS.FinishReason.Unknown;
+}
+/**
+ * 库里一行 → core 的消息对象。
+ *
+ * 正文原样透传（R30）：仓储反序列化出来的就是 core 的 `MessageContent`，逐段重建会把 core
+ * 新增的段类型 / 字段丢掉，也会让同一条消息在不同读取路径上读出两个样子。
+ *
+ * 其余字段名与取值也全部照 core（R21）：`role` / `status` / `finish_reason` 从列里的字符串
+ * 收敛成 core 的取值，`data` 列的 JSON 逐字段收窄，认不出的不往消息上搬。
+ */
+export function toAgentMessage(row) {
+    const data = row.data ?? {};
+    const message = {
+        id: row.id,
+        role: toCoreRole(row.role),
+        status: toStatus(row.status),
+        omit: row.omit,
+    };
+    // `null` 在库里表示「这条消息没有正文」，core 的 `content` 是可选的，所以不搬空值
+    if (row.content !== null)
+        message.content = row.content;
+    const name = asString(data.name);
+    if (name !== undefined)
+        message.name = name;
+    const toolCallId = asString(data.tool_call_id);
+    if (toolCallId !== undefined)
+        message.tool_call_id = toolCallId;
+    const reasoning = asString(data.reasoning_content);
+    if (reasoning !== undefined)
+        message.reasoning_content = reasoning;
+    const toolCalls = asToolCalls(data.tool_calls);
+    if (toolCalls !== undefined)
+        message.tool_calls = toolCalls;
+    const functionCall = asFunctionCall(data.function_call);
+    if (functionCall !== undefined)
+        message.function_call = functionCall;
+    const finishReason = asString(data.finish_reason);
+    if (finishReason !== undefined)
+        message.finish_reason = toFinishReason(finishReason);
+    const usage = asUsage(data.usage);
+    if (usage !== undefined)
+        message.usage = usage;
+    const subAgentUsage = asUsage(data.subAgentUsage);
+    if (subAgentUsage !== undefined)
+        message.subAgentUsage = subAgentUsage;
+    const hidden = asBoolean(data.hidden);
+    if (hidden !== undefined)
+        message.hidden = hidden;
+    return message;
+}
+/** 从消息的其余字段里读最近一次请求的用量；没有就是 `null`（对话服务算上下文占用用） */
+export function readUsage(data) {
+    return asUsage(data?.usage) ?? null;
+}
+/**
+ * `around` 取的窗口条数（PRD F-C6 的定位）。
+ *
+ * `message.list` 没有 `limit`：它一直是「一段对话全给」，`around` 只是把这一段收成一窗，
+ * 40 条足够看够上下文而不会把屏刷满。消费者是桌面端的搜索命中跳转（PLAN W4）。
+ */
+const AROUND_WINDOW = 40;
+/**
+ * 以某条消息为中心取一窗（PRD F-C6 的定位）。
+ *
+ * `rows` 是这段对话（或这个子 Agent）的全部消息、已按先后排序。命中那条一定在窗口里：
+ * 前面先给一半（`floor((size-1)/2)` 条），剩下的额度全给后面；命中靠近两端时窗口自然短一些。
+ * 命中不在 `rows` 里时回 `null` —— 调用方给空页（这条可能刚被撤回/换过库）。
+ */
+function windowAround(rows, around, size) {
+    const index = rows.findIndex((row) => row.id === around);
+    if (index < 0)
+        return null;
+    const before = Math.floor((size - 1) / 2);
+    const start = Math.max(0, index - before);
+    const end = Math.min(rows.length, index + (size - before));
+    return rows.slice(start, end);
+}
+export class MessageService {
+    conversations;
+    messages;
+    drafts;
+    constructor(deps) {
+        this.conversations = deps.conversations;
+        this.messages = deps.messages;
+        this.drafts = deps.drafts;
+    }
+    /**
+     * 读一段对话的消息（architecture A12 / PRD F-C6）。
+     *
+     * - 不给 `after`、也不给 `around`：整段历史；
+     * - 给了 `after` 且该 id 就在这段对话里：**从这条开始**（含它，内容是最新的，可能是流式中那条的
+     *   部分内容）+ 其后全部，并把 `anchor` 报成它；
+     * - 给了 `after` 但这段对话里没有这个 id（已删、或换过库）：退回整段历史，`anchor` 为空 ——
+     *   客户端据此知道这是一次全量；
+     * - 给了 `around`：以这条为中心取 {@link AROUND_WINDOW} 条（命中那条一定在里面），
+     *   `anchor` 报成它；命中不在可见集里时给空页 + 空 `anchor`，**不报错**（消息可能刚被撤回）。
+     *   `around` 与 `after` 同时给时**只认 `around`**：两者是两种取法（一个「从这里往下」、一个
+     *   「围绕这里」），混在一起没有唯一答案。
+     *
+     * `toolCallId` 取某个子 Agent 自己的消息（PRD F-I7）：它按消息落库时记下的
+     * `parentToolCallId` 取（那次委派的工具调用 id），走的是另一条查询 —— 子 Agent 的消息不在
+     * 主线历史里（`listByConversation` 只给主线），所以两个参数同时给时 `after` 只用来定 `anchor`，
+     * 结果集仍是那个子 Agent 的全部消息。`around` 同此：`toolCallId` 决定读哪一段，`around`
+     * 只在那一段里定位。
+     *
+     * `hidden` 的消息（会话创建时那条 cwd 消息、交接摘要）默认不回：core 的这个字段就是
+     * 「这条不给人看」。要看到它们（排查、或客户端显式要）就传 `includeHidden`。
+     */
+    async list(params) {
+        const conversation = await this.requireConversation(params.conversationId);
+        const options = { includeHidden: params.includeHidden === true };
+        const around = idParam(params.around);
+        const after = idParam(params.after);
+        // `around` 优先：它给了就完全不管 `after`（连 `anchor` 也不由 `after` 定）
+        let anchor = null;
+        if (around === undefined && after !== undefined) {
+            const anchorRow = await this.messages.get(after);
+            if (anchorRow && anchorRow.conversationId === conversation.id) {
+                anchor = anchorRow.id;
+            }
+        }
+        const toolCallId = idParam(params.toolCallId);
+        if (toolCallId !== undefined) {
+            const delegated = await this.messages.listByParentToolCallId(conversation.id, toolCallId, options);
+            return this.respond(conversation.id, delegated, anchor, around);
+        }
+        // `around` 要的是「整段之后再取窗」，所以这一跳不带 `after`（带了就只剩后半段）
+        const rows = await this.messages.listByConversation(conversation.id, around === undefined ? after : undefined, options);
+        return this.respond(conversation.id, rows, anchor, around);
+    }
+    /** 把一次读到的行拼成出参；`around` 给了就收成一窗（命中不在里面就是空页） */
+    respond(conversationId, rows, anchor, around) {
+        if (around === undefined) {
+            return { conversationId, anchor, messages: rows.map((row) => toAgentMessage(row)) };
+        }
+        const window = windowAround(rows, around, AROUND_WINDOW);
+        if (window === null) {
+            return { conversationId, anchor: null, messages: [] };
+        }
+        return { conversationId, anchor: around, messages: window.map((row) => toAgentMessage(row)) };
+    }
+    /**
+     * 这段对话存不存在：库里那一行，或者一份还没落库的草稿（R56）。
+     *
+     * 草稿还没有任何消息，所以读它总是得到空集 —— 但它不该被读成「找不到这段对话」：
+     * 客户端刚 `create` 完就会拉一次消息与现场。
+     */
+    async requireConversation(conversationId) {
+        const id = typeof conversationId === "string" ? conversationId.trim() : "";
+        const row = id.length === 0 ? undefined : await this.conversations.get(id);
+        if (row)
+            return row;
+        const draft = id.length === 0 ? undefined : this.drafts?.get(id);
+        if (draft)
+            return draft;
+        throw new HostError("not_found", {
+            params: { entity: "conversation" },
+            detail: { conversationId },
+        });
+    }
+}

package/dist/services/ModelService.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 模型服务：模型清单、图片模型、模型增删改、恢复出厂（F-F3 / F-F4 / F-F7 / D6 / D27）。
+ *
+ * 配置只有一处真相（D21）：`config.json`，读写都经 SDK 的 `ConfigManager`。这个服务不缓存配置，
+ * 每次调用现读现写 —— 配置是几百行的 JSON，读一次比「缓存与磁盘谁更新」的排查便宜得多。
+ *
+ * 两条与产品行为直接相关的口径：
+ *
+ *   - **编辑即转自定义**（F-F3）：改过的模型要打上 `custom: true`，否则 SDK 下次初始化会拿出厂
+ *     定义把它冲回去（`syncManagedModels` 只保留 `custom: true` 的条目）。
+ *   - **删除要算引用**（F-F2 / F-F7）：被助手引用的模型不能删，并且要列出「还有谁指它」；
+ *     默认项指向被删的那个模型时要改指或清空，不留悬空引用。
+ */
+import type { AgentRepository } from "@ai-zen/agents-sdk";
+import type { AppConfig, ConfigManager, Endpoint, ImageModel, Model, ReasoningPreset, ReasoningPresets } from "@ai-zen/agents-sdk";
+import type { ModelCreateParams, ModelCreateResult, ModelDeleteImageParams, ModelDeleteImageResult, ModelDeleteParams, ModelDeleteResult, ModelListImagesResult, ModelListParams, ModelListResult, ModelRestoreFactoryParams, ModelRestoreFactoryResult, ModelSaveImageParams, ModelSaveImageResult, ModelUpdateParams, ModelUpdateResult, ModelView, ProblemFact } from "../wire/index.js";
+/** 模型服务的依赖；由单根组装后注入 */
+export interface ModelServiceOptions {
+    /** 配置唯一入口（SDK） */
+    configManager: ConfigManager;
+    /** 助手定义仓储（`<basePath>/agents/`）：模型被谁引用要读它 */
+    agents?: AgentRepository;
+}
+/** 按 id 找端点 */
+export declare function findEndpoint(config: AppConfig, endpointId: string): Endpoint | undefined;
+/** 按 id 找模型 */
+export declare function findModel(config: AppConfig, modelId: string): Model | undefined;
+/** 按 id 找图片模型 */
+export declare function findImageModel(config: AppConfig, imageModelId: string): ImageModel | undefined;
+/**
+ * 这个模型现在能不能用；能用回 `null`，不能用回一条带原因的事实（F-B5：藏着不如说清楚）。
+ *
+ * 两种用不了的原因都在配置层：端点没了（模型指向一个已删的端点），或端点还没配密钥
+ * （F-A7 的「这个端点配好了没」）。模型自身的字段没有第三种「用不了」的形态。
+ */
+export declare function modelUnavailableProblem(config: AppConfig, model: Model): ProblemFact | null;
+/** 模型引用的思考策略（表里没有、或者一条档位都没有，就是这个模型不可调，PRD F-B7） */
+export declare function reasoningPresetOf(model: Model | undefined, presets: ReasoningPresets): ReasoningPreset | undefined;
+/** 这个模型可选的思考档位名（客户端据此渲染「能调哪几档」） */
+export declare function thinkingLevelsOf(model: Model | undefined, presets: ReasoningPresets): string[];
+export declare class ModelService {
+    private readonly configManager;
+    private readonly agents?;
+    constructor(options: ModelServiceOptions);
+    /** 读一次配置（写方法都从这里出发，避免「基于旧快照覆盖别人刚写的东西」） */
+    readConfig(): Promise<AppConfig>;
+    /**
+     * 模型清单（F-F3）。
+     *
+     * 默认连不可用的也列（F-B5 的口径：藏起来会让人以为它没了），`includeUnavailable: false`
+     * 时才把它们筛掉。
+     */
+    list(params?: ModelListParams): Promise<ModelListResult>;
+    /** 图片模型与那个「默认图片模型」（F-F4 / D6） */
+    listImages(): Promise<ModelListImagesResult>;
+    /** 新建模型（建出来就是自定义，F-F3） */
+    create(params: ModelCreateParams): Promise<ModelCreateResult>;
+    /** 编辑模型（编辑即转自定义，F-F3 —— 否则下轮初始化会被出厂定义冲回去） */
+    update(params: ModelUpdateParams): Promise<ModelUpdateResult>;
+    /**
+     * 删除模型（F-F2 / F-F7）。
+     *
+     * 被助手引用时拒删并列出引用者；默认项（兜底模型 / 迁移模型 / 取名模型）指向它时改指或清空
+     * —— 留在配置里指向一个不存在的 id，会在下一次真要跑的时候才炸出来。
+     */
+    delete(params: ModelDeleteParams): Promise<ModelDeleteResult>;
+    /**
+     * 恢复出厂（F-F3：整条替换）。
+     *
+     * 只有出厂清单里有的模型才有「出厂版本」可恢复；用户自建的模型没有，回
+     * `error.notFactoryModel`。恢复之后这一条重新归 SDK 托管（去掉 `custom`），
+     * 所以下次初始化会跟着出厂清单走。
+     */
+    restoreFactory(params: ModelRestoreFactoryParams): Promise<ModelRestoreFactoryResult>;
+    /** 图片模型的创建与修改（F-F4：同一个方法兼两件事，`id` 在就改、不在就建） */
+    saveImage(params: ModelSaveImageParams): Promise<ModelSaveImageResult>;
+    /** 删除图片模型；它正被「默认图片模型」指着时拒删（F-F4 / F-F7） */
+    deleteImage(params: ModelDeleteImageParams): Promise<ModelDeleteImageResult>;
+    /** 一行模型定义 → 对外形状 */
+    toView(config: AppConfig, model: Model, presets: ReasoningPresets): ModelView;
+    /** 入参（新建）→ 一条模型定义；校验全在这里，写盘之前就拦下 */
+    private buildModel;
+    /**
+     * 谁在引用这个模型：读助手定义（一实体一文件，F-G3）。
+     *
+     * 默认项不列在这里：它们会跟着改指或清空（F-F7），是「删完自动收拾」而不是「拦住删除」。
+     */
+    private referencesOf;
+}