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

package/dist/services/ModelService.js

@@ -0,0 +1,489 @@
+/**
+ * 模型服务：模型清单、图片模型、模型增删改、恢复出厂（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 { DEFAULT_APP_CONFIG, } from "@ai-zen/agents-sdk";
+import { DEFAULT_LANGUAGE, render } from "../i18n/index.js";
+import { HostError } from "../wire/errors.js";
+// ---------------------------------------------------------------------------
+// 文案
+// ---------------------------------------------------------------------------
+/** 一条给人看的事实（码 = 文案键，与素材层同口径：存码不存句子，D8） */
+function text(messageKey, params = {}) {
+    return {
+        code: messageKey,
+        messageKey,
+        params,
+        message: render(DEFAULT_LANGUAGE, messageKey, params),
+    };
+}
+// ---------------------------------------------------------------------------
+// 出厂默认的两条阈值
+// ---------------------------------------------------------------------------
+/**
+ * 新建模型不传阈值时套的默认档（F-F3）。
+ *
+ * 唯一来源是 SDK 出厂配置里各模型的那份 `tokenThresholds`，这里不另写数字：取清单里
+ * **用得最多的那一档**（出厂清单里绝大多数模型的窗口都很大，用的是同一档；只有一个
+ * 200K 窗口的模型例外，那档给新模型既过度保守也说不通）。出厂清单改了，这里跟着改。
+ */
+function factoryDefaultThresholds() {
+    const tally = new Map();
+    for (const model of DEFAULT_APP_CONFIG.models) {
+        const { handoff, guard } = model.tokenThresholds;
+        const key = `${handoff}/${guard}`;
+        const seen = tally.get(key);
+        if (seen)
+            seen.hits += 1;
+        else
+            tally.set(key, { value: { handoff, guard }, hits: 1 });
+    }
+    let winner;
+    for (const candidate of tally.values()) {
+        if (winner === undefined || candidate.hits > winner.hits)
+            winner = candidate;
+    }
+    // 出厂清单为空是 SDK 侧的不变量被破坏；当场报出来，不默默写出一个没有阈值的模型
+    if (winner === undefined)
+        throw new Error("SDK 的出厂配置里没有任何模型，拿不到默认阈值");
+    return { handoff: winner.value.handoff, guard: winner.value.guard };
+}
+// ---------------------------------------------------------------------------
+// 纯函数（配置里那些「查一查」的公共口径，助手服务也用）
+// ---------------------------------------------------------------------------
+/** 按 id 找端点 */
+export function findEndpoint(config, endpointId) {
+    return config.endpoints.find((endpoint) => endpoint.id === endpointId);
+}
+/** 按 id 找模型 */
+export function findModel(config, modelId) {
+    return config.models.find((model) => model.id === modelId);
+}
+/** 按 id 找图片模型 */
+export function findImageModel(config, imageModelId) {
+    return (config.imageModels ?? []).find((model) => model.id === imageModelId);
+}
+/**
+ * 这个模型现在能不能用；能用回 `null`，不能用回一条带原因的事实（F-B5：藏着不如说清楚）。
+ *
+ * 两种用不了的原因都在配置层：端点没了（模型指向一个已删的端点），或端点还没配密钥
+ * （F-A7 的「这个端点配好了没」）。模型自身的字段没有第三种「用不了」的形态。
+ */
+export function modelUnavailableProblem(config, model) {
+    const endpoint = findEndpoint(config, model.endpointId);
+    if (!endpoint) {
+        return text("model.endpointMissing", { model: model.name, id: model.endpointId });
+    }
+    if (endpoint.apiKey.trim() === "") {
+        return text("endpoint.noKey", { endpoint: endpoint.name === "" ? endpoint.id : endpoint.name });
+    }
+    return null;
+}
+/** 模型引用的思考策略（表里没有、或者一条档位都没有，就是这个模型不可调，PRD F-B7） */
+export function reasoningPresetOf(model, presets) {
+    const name = model?.reasoningPreset;
+    if (!name)
+        return undefined;
+    const preset = presets[name];
+    return preset && Object.keys(preset.levels).length > 0 ? preset : undefined;
+}
+/** 这个模型可选的思考档位名（客户端据此渲染「能调哪几档」） */
+export function thinkingLevelsOf(model, presets) {
+    const preset = reasoningPresetOf(model, presets);
+    return preset ? Object.keys(preset.levels) : [];
+}
+/** 两条阈值的合法性：都是正数，且硬线要留出交接的余量（handoff < guard） */
+function assertThresholds(thresholds) {
+    const { handoff, guard } = thresholds;
+    if (!Number.isFinite(handoff) || !Number.isFinite(guard) || handoff <= 0 || guard <= 0) {
+        throw new HostError("invalid_params", {
+            params: { field: "tokenThresholds" },
+            detail: { field: "tokenThresholds", reason: "not_positive", thresholds },
+        });
+    }
+    if (handoff >= guard) {
+        throw new HostError("invalid_params", {
+            params: { field: "tokenThresholds" },
+            detail: { field: "tokenThresholds", reason: "handoff_not_below_guard", thresholds },
+        });
+    }
+}
+/** 必填的字符串参数：空串按「参数不对」处理，不拿它去查配置 */
+function requireText(value, field) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    if (raw === "") {
+        throw new HostError("invalid_params", {
+            params: { field },
+            detail: { field, reason: "empty" },
+        });
+    }
+    return raw;
+}
+// ---------------------------------------------------------------------------
+// 服务
+// ---------------------------------------------------------------------------
+export class ModelService {
+    configManager;
+    agents;
+    constructor(options) {
+        this.configManager = options.configManager;
+        this.agents = options.agents;
+    }
+    /** 读一次配置（写方法都从这里出发，避免「基于旧快照覆盖别人刚写的东西」） */
+    async readConfig() {
+        return await this.configManager.read();
+    }
+    // -------------------------------------------------------------------------
+    // 读
+    // -------------------------------------------------------------------------
+    /**
+     * 模型清单（F-F3）。
+     *
+     * 默认连不可用的也列（F-B5 的口径：藏起来会让人以为它没了），`includeUnavailable: false`
+     * 时才把它们筛掉。
+     */
+    async list(params = {}) {
+        const config = await this.readConfig();
+        const presets = await this.configManager.readReasoningPresets();
+        const models = config.models.map((model) => this.toView(config, model, presets));
+        return {
+            models: params.includeUnavailable === false ? models.filter((model) => model.available) : models,
+        };
+    }
+    /** 图片模型与那个「默认图片模型」（F-F4 / D6） */
+    async listImages() {
+        const config = await this.readConfig();
+        const imageModels = (config.imageModels ?? []).map((model) => toImageModelView(model));
+        return { imageModels, defaultImageModel: config.defaultImageModel ?? null };
+    }
+    // -------------------------------------------------------------------------
+    // 写：文本模型
+    // -------------------------------------------------------------------------
+    /** 新建模型（建出来就是自定义，F-F3） */
+    async create(params) {
+        const input = params.model;
+        const config = await this.readConfig();
+        const id = requireText(input?.id, "model.id");
+        if (findModel(config, id)) {
+            throw new HostError("invalid_params", {
+                params: { field: "model.id" },
+                detail: { field: "model.id", reason: "already_exists", id },
+            });
+        }
+        const presets = await this.configManager.readReasoningPresets();
+        const model = this.buildModel(config, presets, id, input);
+        const next = { ...config, models: [...config.models, model] };
+        await this.configManager.write(next);
+        return { model: this.toView(next, model, presets) };
+    }
+    /** 编辑模型（编辑即转自定义，F-F3 —— 否则下轮初始化会被出厂定义冲回去） */
+    async update(params) {
+        const config = await this.readConfig();
+        const modelId = requireText(params.modelId, "modelId");
+        const existing = findModel(config, modelId);
+        if (!existing) {
+            throw new HostError("not_found", {
+                params: { entity: "model" },
+                detail: { modelId },
+            });
+        }
+        const presets = await this.configManager.readReasoningPresets();
+        const patch = params.patch ?? {};
+        const merged = {
+            ...existing,
+            ...definedOnly({
+                name: patch.name,
+                endpointId: patch.endpointId,
+                modelName: patch.modelName,
+                tokenThresholds: patch.tokenThresholds,
+                defaultParams: patch.defaultParams,
+                reasoningPreset: patch.reasoningPreset,
+                vision: patch.vision,
+                description: patch.description,
+            }),
+            custom: true,
+        };
+        validateModelShape(config, presets, merged);
+        const next = {
+            ...config,
+            models: config.models.map((model) => (model.id === modelId ? merged : model)),
+        };
+        await this.configManager.write(next);
+        return { model: this.toView(next, merged, presets) };
+    }
+    /**
+     * 删除模型（F-F2 / F-F7）。
+     *
+     * 被助手引用时拒删并列出引用者；默认项（兜底模型 / 迁移模型 / 取名模型）指向它时改指或清空
+     * —— 留在配置里指向一个不存在的 id，会在下一次真要跑的时候才炸出来。
+     */
+    async delete(params) {
+        const config = await this.readConfig();
+        const modelId = requireText(params.modelId, "modelId");
+        if (!findModel(config, modelId)) {
+            throw new HostError("not_found", { params: { entity: "model" }, detail: { modelId } });
+        }
+        const references = await this.referencesOf(modelId);
+        if (references.length > 0) {
+            throw new HostError("config_invalid", {
+                messageKey: "config.referenced",
+                params: { count: references.length, names: references.map((item) => item.name).join(", ") },
+                detail: { modelId, references: { referenced: true, items: references } },
+            });
+        }
+        if (params.dryRun === true) {
+            return { removed: false, references: { referenced: false, items: [] } };
+        }
+        const remaining = config.models.filter((model) => model.id !== modelId);
+        const next = {
+            ...config,
+            models: remaining,
+            ...redirectDefaults(config, modelId, remaining),
+        };
+        await this.configManager.write(next);
+        return { removed: true, references: { referenced: false, items: [] } };
+    }
+    /**
+     * 恢复出厂（F-F3：整条替换）。
+     *
+     * 只有出厂清单里有的模型才有「出厂版本」可恢复；用户自建的模型没有，回
+     * `error.notFactoryModel`。恢复之后这一条重新归 SDK 托管（去掉 `custom`），
+     * 所以下次初始化会跟着出厂清单走。
+     */
+    async restoreFactory(params) {
+        const config = await this.readConfig();
+        const modelId = requireText(params.modelId, "modelId");
+        if (!findModel(config, modelId)) {
+            throw new HostError("not_found", { params: { entity: "model" }, detail: { modelId } });
+        }
+        const factory = DEFAULT_APP_CONFIG.models.find((model) => model.id === modelId);
+        if (!factory) {
+            throw new HostError("invalid_params", {
+                messageKey: "error.notFactoryModel",
+                params: { id: modelId },
+                detail: { modelId, reason: "not_a_factory_model" },
+            });
+        }
+        const restored = { ...structuredClone(factory) };
+        const next = {
+            ...config,
+            models: config.models.map((model) => (model.id === modelId ? restored : model)),
+        };
+        await this.configManager.write(next);
+        const presets = await this.configManager.readReasoningPresets();
+        return { model: this.toView(next, restored, presets) };
+    }
+    // -------------------------------------------------------------------------
+    // 写：图片模型
+    // -------------------------------------------------------------------------
+    /** 图片模型的创建与修改（F-F4：同一个方法兼两件事，`id` 在就改、不在就建） */
+    async saveImage(params) {
+        const input = params.imageModel;
+        const config = await this.readConfig();
+        const id = requireText(input?.id, "imageModel.id");
+        requireText(input?.name, "imageModel.name");
+        requireText(input?.modelName, "imageModel.modelName");
+        const endpointId = requireText(input?.endpointId, "imageModel.endpointId");
+        if (!findEndpoint(config, endpointId)) {
+            throw new HostError("invalid_params", {
+                params: { field: "imageModel.endpointId" },
+                detail: { field: "imageModel.endpointId", reason: "endpoint_not_found", endpointId },
+            });
+        }
+        const imageModels = config.imageModels ?? [];
+        const existing = imageModels.find((model) => model.id === id);
+        const saved = {
+            ...(existing ?? {}),
+            ...definedOnly({
+                description: input.description,
+                defaultSize: input.defaultSize,
+                defaultQuality: input.defaultQuality,
+            }),
+            id,
+            name: requireText(input.name, "imageModel.name"),
+            endpointId,
+            modelName: requireText(input.modelName, "imageModel.modelName"),
+            custom: true,
+        };
+        const next = {
+            ...config,
+            imageModels: existing
+                ? imageModels.map((model) => (model.id === id ? saved : model))
+                : [...imageModels, saved],
+        };
+        await this.configManager.write(next);
+        return { imageModel: toImageModelView(saved) };
+    }
+    /** 删除图片模型；它正被「默认图片模型」指着时拒删（F-F4 / F-F7） */
+    async deleteImage(params) {
+        const config = await this.readConfig();
+        const imageModelId = requireText(params.imageModelId, "imageModelId");
+        const imageModels = config.imageModels ?? [];
+        if (!imageModels.some((model) => model.id === imageModelId)) {
+            throw new HostError("not_found", {
+                params: { entity: "image model" },
+                detail: { imageModelId },
+            });
+        }
+        const references = config.defaultImageModel === imageModelId
+            ? {
+                referenced: true,
+                items: [{ kind: "default", id: "defaultImageModel", name: imageModelId }],
+            }
+            : { referenced: false, items: [] };
+        if (references.referenced) {
+            throw new HostError("config_invalid", {
+                messageKey: "config.referenced",
+                params: {
+                    count: references.items.length,
+                    names: references.items.map((item) => item.name).join(", "),
+                },
+                detail: { imageModelId, references },
+            });
+        }
+        if (params.dryRun === true)
+            return { removed: false, references };
+        const next = {
+            ...config,
+            imageModels: imageModels.filter((model) => model.id !== imageModelId),
+        };
+        await this.configManager.write(next);
+        return { removed: true, references };
+    }
+    // -------------------------------------------------------------------------
+    // 视图
+    // -------------------------------------------------------------------------
+    /** 一行模型定义 → 对外形状 */
+    toView(config, model, presets) {
+        const unavailable = modelUnavailableProblem(config, model);
+        return {
+            id: model.id,
+            name: model.name,
+            endpointId: model.endpointId,
+            modelName: model.modelName ?? null,
+            tokenThresholds: {
+                handoff: model.tokenThresholds.handoff,
+                guard: model.tokenThresholds.guard,
+            },
+            defaultParams: model.defaultParams ?? {},
+            reasoningPreset: model.reasoningPreset ?? null,
+            thinkingLevels: thinkingLevelsOf(model, presets),
+            vision: model.vision === true,
+            description: model.description ?? null,
+            custom: model.custom === true,
+            available: unavailable === null,
+            unavailableReason: unavailable,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // 内部
+    // -------------------------------------------------------------------------
+    /** 入参（新建）→ 一条模型定义；校验全在这里，写盘之前就拦下 */
+    buildModel(config, presets, id, input) {
+        const model = {
+            id,
+            name: requireText(input?.name, "model.name"),
+            endpointId: requireText(input?.endpointId, "model.endpointId"),
+            ...definedOnly({
+                modelName: input.modelName,
+                tokenThresholds: input.tokenThresholds,
+                defaultParams: input.defaultParams,
+                reasoningPreset: input.reasoningPreset,
+                vision: input.vision,
+                description: input.description,
+            }),
+            // 阈值：入参给了用入参，省略就套出厂默认（出厂清单里最多人用的那一档）
+            tokenThresholds: input.tokenThresholds ?? factoryDefaultThresholds(),
+            custom: true,
+        };
+        validateModelShape(config, presets, model);
+        return model;
+    }
+    /**
+     * 谁在引用这个模型：读助手定义（一实体一文件，F-G3）。
+     *
+     * 默认项不列在这里：它们会跟着改指或清空（F-F7），是「删完自动收拾」而不是「拦住删除」。
+     */
+    async referencesOf(modelId) {
+        const references = [];
+        const agents = this.agents ? await this.agents.list() : [];
+        for (const agent of agents) {
+            if (agent.modelId === modelId) {
+                references.push({ kind: "agent", id: agent.id, name: agent.name });
+            }
+        }
+        return references;
+    }
+}
+// ---------------------------------------------------------------------------
+// 纯函数
+// ---------------------------------------------------------------------------
+/** 只保留「入参真的给了」的那些字段（`undefined` 表示这次不改它） */
+function definedOnly(input) {
+    const result = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
+/** 一条模型定义的形状校验：端点要在、阈值要合法、引用的思考策略要在表里 */
+function validateModelShape(config, presets, model) {
+    requireText(model.name, "model.name");
+    if (!findEndpoint(config, model.endpointId)) {
+        throw new HostError("invalid_params", {
+            params: { field: "model.endpointId" },
+            detail: { field: "model.endpointId", reason: "endpoint_not_found", endpointId: model.endpointId },
+        });
+    }
+    assertThresholds(model.tokenThresholds);
+    if (model.reasoningPreset !== undefined && !presets[model.reasoningPreset]) {
+        throw new HostError("invalid_params", {
+            params: { field: "model.reasoningPreset" },
+            detail: {
+                field: "model.reasoningPreset",
+                reason: "unknown_preset",
+                preset: model.reasoningPreset,
+                presets: Object.keys(presets),
+            },
+        });
+    }
+}
+/**
+ * 被删模型的默认指望去向（F-F7：自动改指或清空）。
+ *
+ * 口径是「同端点的第一条剩余模型」：换指到别的端点等于把请求发去另一家服务商，那件事该由人决定。
+ * 同一端点没有剩余模型时清空（`null`），让界面显示「还没选」而不是显示一个不存在的 id。
+ */
+function redirectDefaults(config, removedModelId, remaining) {
+    const removed = findModel(config, removedModelId);
+    const replacement = remaining.find((model) => model.endpointId === removed?.endpointId)?.id ?? null;
+    const pick = (current) => current === removedModelId ? (replacement ?? undefined) : current;
+    return {
+        defaultModel: pick(config.defaultModel),
+        defaultMigrationModel: pick(config.defaultMigrationModel),
+        namingModel: pick(config.namingModel),
+    };
+}
+/** 图片模型定义 → 对外形状 */
+function toImageModelView(model) {
+    return {
+        id: model.id,
+        name: model.name,
+        endpointId: model.endpointId,
+        modelName: model.modelName,
+        description: model.description ?? null,
+        defaultSize: model.defaultSize ?? null,
+        defaultQuality: model.defaultQuality ?? null,
+        custom: model.custom === true,
+    };
+}

package/dist/services/NoticeService.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 通知服务：一条**独立通道**（PRD F-I8），它不进消息流。
+ *
+ * 三件事在这里定死：
+ *
+ * 1. **持久化**（PRD L3）：通知落 `notices` 表，重启之后还在；永久通知的消失只有「手动清」
+ *    这一条路径（`notice.dismiss` / `notice.clear`），带持续时间的到点自己消失。
+ * 2. **持续时间的两套单位**（R15）：契约用**秒**（用户语义：「这条提示留 3 秒」），
+ *    库里存**毫秒**（`notices.durationMs`）。换算只有本文件这一处 —— 别处再换一次，
+ *    迟早有一条通知留 3 毫秒或 3 天。
+ * 3. **存码不存句子**（D8 / architecture §6）：库里存的是「码 + 参数」，读出时按**调用方
+ *    给的语言**渲染。语言挂在连接上，一条通知存死一种语言、换个语言连回来就错了。
+ *
+ * 语气三档 `info | warning | error`（R4）：「已保存」这种一秒提示是 `info` + 短 duration，
+ * 不新增 success 档；`warning` / `error` 同时是宿主日志上浮的通道（PRD F-J2）。
+ */
+import type { Language, MessageKey } from "../i18n/index.js";
+import type { ChatEventEmitter } from "../runtime/ChatRunner.js";
+import type { NoticeRepository } from "../storage/NoticeRepository.js";
+import type { NoticeClearParams, NoticeClearResult, NoticeDismissParams, NoticeDismissResult, NoticeLevel, NoticeListParams, NoticeListResult, NoticeView } from "../wire/index.js";
+import type { EventMap, EventName } from "../wire/events.js";
+import type { LocalizedText } from "../wire/states.js";
+/** 造一条通知的入参（内部入口；`notice.*` 三个方法只读 / 只清） */
+export interface NoticeCreateInput {
+    level: NoticeLevel;
+    /**
+     * 文案键，同时作为出网的稳定码（`LocalizedText.code`）。
+     *
+     * 两者合一是有意的：通知的稳定码本来就是「哪句话」这件事，另起一套码只会多一张对照表。
+     */
+    code: MessageKey;
+    params?: Record<string, unknown>;
+    /** 秒；不给或给 `null` 表示永久，直到被手动清掉（PRD L3） */
+    duration?: number | null;
+    /** 与哪段对话有关；不给表示全局通知 */
+    conversationId?: string | null;
+}
+export interface NoticeServiceDeps {
+    notices: NoticeRepository;
+    /** 推 `notice` 事件；不注入就不推（用例、或不需要在线推送的场合） */
+    emit?: ChatEventEmitter;
+    /** 时钟，测试注入用；缺省 `Date.now` */
+    now?: () => number;
+    /** 通知 id 的分配口，测试注入用；缺省 `crypto.randomUUID` */
+    newId?: () => string;
+}
+/** 按语言重渲染一句已存的文案（`messageKey` + `params` 都在 `LocalizedText` 里） */
+export declare function relocalizeText(text: LocalizedText, language: Language): LocalizedText;
+/**
+ * 事件出网前的按连接本地化（`WsHub` 的 `localizeEvent` 注入点）。
+ *
+ * 事件是在产生的现场按缺省语言渲染的，而语言挂在连接上，所以出网前要把 `notice` 与
+ * `question` 这两类载荷里的人话换成这条连接的语言；其余事件没有文案，原样返回。
+ */
+export type EventLocalizer = <E extends EventName>(event: E, payload: EventMap[E], language: Language) => EventMap[E];
+/** 造上面那个本地化器（接线层把它注入 `WsHub` 的 `localizeEvent`） */
+export declare function createEventLocalizer(): EventLocalizer;
+export declare class NoticeService {
+    private readonly notices;
+    private readonly emit?;
+    private readonly now;
+    private readonly newId;
+    constructor(deps: NoticeServiceDeps);
+    /**
+     * 发一条通知（内部入口）。
+     *
+     * 落库 → 推 `notice` 事件 → 返回渲染好的视图。落库在推送之前：推送只对在线连接有意义
+     * （D5：断线即作废），而库里的那条是重连之后还能看到的真相（L3）。
+     */
+    create(input: NoticeCreateInput, language?: Language): Promise<NoticeView>;
+    /**
+     * 日志上浮（PRD F-J2：warn / error 也要上通知栏）。
+     *
+     * 没有持续时间 = 永久：界面上的一闪而过不适合承载「宿主出了什么事」，
+     * 这类通知要留到用户看过并手动清掉。
+     */
+    log(level: Extract<NoticeLevel, "warning" | "error">, summary: string, language?: Language): Promise<NoticeView>;
+    /**
+     * 现在该显示的通知（PRD L3）。
+     *
+     * 先清掉已经到点的（`deleteExpired`），再按「永久 + 还没到点」读一遍：只按时间过滤而不清，
+     * 表会一直涨；只清不按时间过滤，同一毫秒内到点的那条仍会被读出来。
+     */
+    list(params?: NoticeListParams, language?: Language): Promise<NoticeListResult>;
+    /**
+     * 清掉一条（PRD L3：永久通知唯一能消失的方式）。
+     *
+     * 已经不存在时回 `dismissed: false`（这次有没有真的改动库），与 `notice.clear` 的口径一致。
+     */
+    dismiss(params: NoticeDismissParams): Promise<NoticeDismissResult>;
+    /** 清掉一批（不给 `conversationId` 就清全部） */
+    clear(params?: NoticeClearParams): Promise<NoticeClearResult>;
+}