hiwork-core 0.0.30 → 0.0.37

package/lib/types/image-rpc.d.ts

@@ -0,0 +1,142 @@
+/**
+ * `/hiwork-image` loopback RPC 的 Host 实现（浏览器半边 ⇄ 生图的唯一通道）。
+ *
+ * 设计要点（与 `src/voice-rpc.ts` / `src/daily-rpc.ts` 完全同构）：
+ *  - 只注册**一个** channel，五个 endpoint 的白名单在 {@link IMAGE_RPC_ENDPOINTS}，未知
+ *    endpoint 直接 `bad-request`；一个能力一个频道，`list`/`fetch`/`save` 与
+ *    `status`/`generate` 共用它（与 managed-mcp 的 snapshot/refresh/assertion 同款）；
+ *  - payload 严格校验：每个 endpoint 只放行它声明的字段与类型，任何其它字段一律
+ *    `bad-request`（拼错字段的失败方式必须是响的，不是静默用默认值）；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方只拿到端点结果，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - 网关 `GatewayError` 的稳定 code 原样透传，message 先经
+ *    {@link displayImageGatewayMessage} 消毒——baseURL / HTTP 状态码这类实现细节不进 UI；
+ *  - 其余异常收敛为通用失败（code `internal`），Host 只记日志、不把堆栈或原始消息交给客户端。
+ *
+ * 两处**与 voice 不同**的语义，都写在这里免得后来的人「对齐」掉：
+ *  1. `status` 的失败**不是错误信封**——网关故障时回落 {@link IMAGE_FALLBACK_CONFIG}
+ *     （`enabled:false`）。理由与语音逐字相同：这条端点回答的是「该不该显示生图能力」，
+ *     网关挂了就报红字，只会让一个本来就没有的功能显得像坏了；
+ *  2. `fetch` 有**体积闸**：超过 {@link MAX_IMAGE_BYTES} 直接拒绝（`IMAGE_TOO_LARGE`），
+ *     不把巨图塞进 loopback RPC 信封（语音那条的大对象在**上行**，本条的在下行）。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link ImageRpcContext} 端口，便于单测伪造。
+ */
+import { type GatewayImageConfig } from './ai-router-client.ts';
+import { type ImageGatewayPort, type ImageWorkspacePort } from './imagegen.ts';
+/** RPC 频道；必须与 client 半边 `src/client/images-data.ts` 的 `IMAGE_CHANNEL` 一致（由测试锁定）。 */
+export declare const IMAGE_RPC_CHANNEL = "/hiwork-image";
+/** 端点白名单：生图（`status`/`generate`）与「我的图片」画廊页（`list`/`fetch`/`save`）。 */
+export declare const IMAGE_RPC_ENDPOINTS: readonly ["status", "generate", "list", "fetch", "save"];
+export type ImageRpcEndpoint = (typeof IMAGE_RPC_ENDPOINTS)[number];
+/** 画廊页 `list` 的分页缺省与上限（Host 侧夹紧：网关的 page_size 是它自己的缺省）。 */
+export declare const IMAGE_LIST_DEFAULT_PAGE = 1;
+export declare const IMAGE_LIST_DEFAULT_PAGE_SIZE = 20;
+export declare const IMAGE_LIST_MAX_PAGE_SIZE = 100;
+/**
+ * 端点入参（一次性把所有端点的可放行字段列在这里，解析函数按 endpoint 取子集）。
+ *
+ * `save` 的 `prompt` 是**有意的增量**：设计 §6.5 冻结的入参是 `{ id, workspaceId? }`，
+ * 但文件名规则要求「slug 来自该记录的 prompt」——记录本体在网关，而 `save` 只拿到 id，
+ * 于是把页面手里**已经有**的那条 prompt 顺带传上来（页面没传就用 `image` 兜底）。
+ */
+export interface ImageRpcPayload {
+    prompt?: string | undefined;
+    size?: string | undefined;
+    page?: number | undefined;
+    pageSize?: number | undefined;
+    id?: number | undefined;
+    workspaceId?: string | undefined;
+}
+/** 客户端可安全展示的失败。 */
+export interface ImageRpcFailure {
+    code: string;
+    message: string;
+    /** DSH Connection 信封要求 `details` 是对象；协议层没有额外细节时补空对象。 */
+    details: object;
+}
+/** 端点结果信封（与 DSH Connection 的 `ConnectionRpcResult` 同形）。 */
+export type ImageRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: ImageRpcFailure;
+};
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export declare class ImageRequestError extends Error {
+    readonly code: 'bad-request';
+    constructor(code: 'bad-request', message: string);
+}
+/** Host 侧 RPC 依赖的最小上下文（结构兼容 cordis Context，便于单测伪造）。 */
+export interface ImageRpcConnection {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+            authority: 'loopback';
+        }): () => Promise<void> | void;
+    };
+}
+export interface ImageRpcContext {
+    readonly connection: ImageRpcConnection;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关客户端 + 工作区（画廊页 `save` 用）。
+ * 形状就是 `src/imagegen.ts` 的 {@link ImagegenDeps} 再加一个 `workspaces`。
+ */
+export interface ImageRpcDeps {
+    /**
+     * 解析网关会话 cookie。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用，绝不出现在 RPC 响应里。**
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关客户端；baseURL 未配置时返回 undefined。 */
+    gateway(): ImageGatewayPort | undefined;
+    /** 工作区注册表读取面（画廊页 `save` 的 `workspaceId` → 目录路径）。 */
+    workspaces?: ImageWorkspacePort | undefined;
+    /** `image-config` 读取器（带 ≤5 分钟缓存）；缺省直接读网关。 */
+    imageConfig?: ((sessionCookie: string) => Promise<GatewayImageConfig | undefined>) | undefined;
+    /** 时钟（测试注入）。 */
+    now?: (() => Date) | undefined;
+    /** Host 日志出口（只记事件与错误类型，不记会话值、不记 base64）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 各稳定错误码的用户可见文案（与卡片侧 `IMAGE_ERROR_TEXT` 逐字对齐）。 */
+export { IMAGE_GENERIC_FAILURE_MESSAGE, IMAGE_MESSAGE_FALLBACK, IMAGE_SESSION_EXPIRED_MESSAGE, displayImageGatewayMessage, } from './imagegen.ts';
+/**
+ * `status` 端点读不到配置时的回落值（**成功信封**，见模块头注释第 1 条）：
+ * 能力消失，而不是弹一条用户看不懂的错误。
+ */
+export declare const IMAGE_FALLBACK_CONFIG: GatewayImageConfig;
+/**
+ * 网关 message 消毒 / 错误码兜底文案都从 `imagegen.ts` 再导出（那里是唯一实现，
+ * 因为工具的失败收敛与这里的信封都要用它，而反向 import 会成环）。
+ *
+ * 为什么还要 `export`：`/hiwork-image` 的消费方（以及 spec §6.7 点名的用例）拿的是
+ * **频道模块**的公开面——消毒规则属于这条频道的契约，不该逼调用方去 import 服务层。
+ */
+/** 是否为白名单端点。 */
+export declare function isImageRpcEndpoint(endpoint: string): endpoint is ImageRpcEndpoint;
+/**
+ * payload 校验：每个 endpoint 只放行它声明的字段，其余字段 / 类型不符一律 `bad-request`。
+ *
+ * 缺省 / null 一律等价于空对象（页面挂载时 `status` 的调用就是 `{}` 或不带 payload）。
+ * **不在这里做业务校验**（prompt 长度、size 枚举由网关与 `imagegen.ts` 负责）——
+ * 这里只做协议形状，越早失败越便宜，但重复实现一遍业务规则只会多一处漂移。
+ */
+export declare function parseImagePayload(endpoint: ImageRpcEndpoint, raw: unknown): ImageRpcPayload;
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ *
+ * `status` 走 {@link readImageConfigSafe} 的**降级**分支：网关故障 → 成功信封里的
+ * `enabled:false`。「没有会话」「网关地址未配置」两条**不是**降级——那时还没有任何功能
+ * 状态可言，照常回错误信封。
+ */
+export declare function handleImageEndpoint(endpoint: string, rawPayload: unknown, deps: ImageRpcDeps, signal?: AbortSignal): Promise<ImageRpcResult<unknown>>;
+/**
+ * 注册 `/hiwork-image` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export declare function registerImageRpc(ctx: ImageRpcContext, deps: ImageRpcDeps): () => Promise<void>;

package/lib/types/imagegen.d.ts

@@ -0,0 +1,241 @@
+import { type GatewayImageConfig, type GatewayImageFile, type GatewayImageGenerateResult, type GatewayImageRow, type GatewayImagesView } from './ai-router-client.ts';
+/**
+ * 允许的尺寸三值。**跨仓冻结契约**（与网关 `image.default_size` 的枚举、Agent 工具 schema
+ * 逐项一致）：`defineTool` 在注册期就把 schema 冻死，没法让枚举跟着 `image-config` 走。
+ */
+export declare const IMAGE_SIZES: readonly ["1024x1024", "1024x1536", "1536x1024"];
+export type ImageSize = (typeof IMAGE_SIZES)[number];
+/** 尺寸缺省值（网关 `image-config` 读不到时的兜底）。 */
+export declare const IMAGE_DEFAULT_SIZE: ImageSize;
+/** 工作区里存放生成图的目录名（设计 §6.2：`<会话工作区>/图片/`）。 */
+export declare const IMAGE_DIR_NAME = "\u56FE\u7247";
+/**
+ * 单张图上限 20 MiB（与桌面端附件上限同值）。`fetch` 端点超过它直接拒绝——
+ * 绝不把几十 MB 的 base64 塞进 loopback RPC 信封。
+ */
+export declare const MAX_IMAGE_BYTES: number;
+/** 本次调用用的工作区根取不到时的兜底（无会话上下文的画廊页 `save` 也用它）。 */
+export declare const IMAGE_FALLBACK_WORKSPACE: string;
+/** `image-config` 的 Host 侧缓存时长（设计 §6.3：≤5 分钟）。 */
+export declare const IMAGE_CONFIG_CACHE_TTL_MS: number;
+/** 落盘成功的一张图。`path` 是**绝对路径**，落在会话工作区内。 */
+export interface GeneratedImageFile {
+    path: string;
+    mimeType: string;
+    byteSize: number;
+    revisedPrompt?: string;
+}
+/** 生图成功：图片已写进工作区。 */
+export interface ImageGenerateSuccess {
+    ok: true;
+    files: GeneratedImageFile[];
+    prompt: string;
+    model: string;
+    /** 网关回显的实际尺寸（仅用于展示/日志）。 */
+    size: string;
+    generationMs: number;
+}
+/**
+ * 生图失败。`code` 直接透传网关的 `IMAGE_*`（卡片按 code 分文案，设计 §6.6）。
+ *
+ * 写盘失败也走这一支（`code: 'write-failed'`）：上游已经计费、图片已经生成，
+ * 只把 `files` 置空并把上游信息带上，让卡片说「图片已生成但没能保存到工作区」——
+ * **不让员工以为白花了钱**。
+ */
+export interface ImageGenerateFailure {
+    ok: false;
+    code: string;
+    message: string;
+    files: readonly GeneratedImageFile[];
+    prompt?: string;
+    model?: string;
+    size?: string;
+    generationMs?: number;
+}
+export type GenerateOutcome = ImageGenerateSuccess | ImageGenerateFailure;
+/** 画廊页 `save` 的结果：工作区/写盘这类**业务**失败用 `{ok:false, code, reason}`（设计 §6.5）。 */
+export type SaveImageOutcome = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    code: 'IMAGE_WORKSPACE_NOT_FOUND' | 'IMAGE_SAVE_FAILED';
+    reason: string;
+};
+/**
+ * 网关客户端的生图子集：只声明本模块真正调用的方法（结构兼容 `AiRouterClient` 实例），
+ * 单测因此不需要伪造整个客户端。**四**个方法——「存到工作区」不是网关端点，
+ * 它就是本模块的 {@link saveImageToWorkspace}（取本体 + 写盘）。
+ */
+export interface ImageGatewayPort {
+    getMyImageConfig(sessionCookie: string): Promise<GatewayImageConfig>;
+    generateImage(sessionCookie: string, req: {
+        prompt: string;
+        size?: string;
+        quality?: string;
+    }, keyId?: string, timeoutMs?: number): Promise<GatewayImageGenerateResult>;
+    getMyImages(sessionCookie: string, req: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<GatewayImagesView>;
+    fetchMyImage(sessionCookie: string, id: number): Promise<GatewayImageFile>;
+}
+/** 工作区注册表的读取面（画廊页 `save` 的 `workspaceId` → 目录路径）。 */
+export interface ImageWorkspacePort {
+    /** 取不到该 id 时返回 undefined（页面据此显示原因，而不是落进别的工作区）。 */
+    resolveWorkspacePath(workspaceId: string): string | undefined;
+}
+/** Host 侧生图依赖：会话 + 网关 + 工作区 + 日志。 */
+export interface ImagegenDeps {
+    /**
+     * 解析网关会话 cookie。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用，绝不出现在响应里。**
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关客户端；baseURL 未配置时返回 undefined。 */
+    gateway(): ImageGatewayPort | undefined;
+    /**
+     * 工作区根（**本次调用**的会话工作区，由工具侧从 `exec.agent.session.header.cwd` 取）。
+     * 缺省回落 {@link IMAGE_FALLBACK_WORKSPACE}。`request.workspaceRoot` 优先于它。
+     */
+    workspaceRoot?: string | undefined;
+    /**
+     * `image-config` 读取器（Host 侧缓存 ≤5 分钟）。缺省直接读网关、失败即 undefined
+     * （尺寸拿不到就落 {@link IMAGE_DEFAULT_SIZE}，不让配置读取失败挡住生图）。
+     */
+    imageConfig?: ((sessionCookie: string) => Promise<GatewayImageConfig | undefined>) | undefined;
+    /** 工作区注册表读取面（画廊页 `save` 用）。 */
+    workspaces?: ImageWorkspacePort | undefined;
+    /** 时钟（测试注入；缺省 `new Date()`）。 */
+    now?: (() => Date) | undefined;
+    /** Host 日志出口（只记元数据：尺寸 / 耗时 / 字节数 / 错误类型）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 一次生图请求。`size` / `quality` 缺省由 Host / 网关补默认值。 */
+export interface ImageGenerateRequest {
+    prompt: string;
+    size?: string | undefined;
+    quality?: string | undefined;
+    /** 本次调用的工作区根（工具侧从会话 cwd 取）；优先于 `deps.workspaceRoot`。 */
+    workspaceRoot?: string | undefined;
+}
+/** 越出工作区的路径（内部异常，映射成 `path-outside-workspace`）。 */
+export declare class ImagePathError extends Error {
+    readonly target: string;
+    constructor(target: string);
+}
+/** 工作区里的图片目录。 */
+export declare function imageDirectory(workspaceRoot: string): string;
+/**
+ * `target` 是否严格落在 `workspaceRoot` 内（`workspaceRoot` 本身不算）。
+ *
+ * 用 `path.relative` 判定而不是字符串前缀：前缀法会被 `/tmp/ws-other` 这种「同前缀的
+ * 兄弟目录」骗过去。两侧都只做 `resolve`（不做 `realpath`）——拼路径与校验用同一套
+ * 拼法，符号链接的归一化是文件路由那边的事（设计 §1.3 路径 ①）。
+ */
+export declare function isInsideWorkspace(workspaceRoot: string, target: string): boolean;
+/**
+ * 拼一张图的落盘绝对路径并做越界校验（**唯一**的拼法，写盘与校验共用它）。
+ * 越界即抛 {@link ImagePathError}。
+ *
+ * **两道都要过**：
+ *  1. 落在工作区根内（设计 §6.2 的前缀校验）；
+ *  2. 落在 `<工作区>/图片/` 内（「只写这个目录」）——`../x.png` 会滑进工作区根，
+ *     虽然没出工作区，但不在约定目录里，同样拒绝。
+ */
+export declare function imageFilePath(workspaceRoot: string, fileName: string): string;
+/**
+ * prompt → 文件名 slug：取前 24 个字符（先 trim，免得名字以 `-` 开头）、非法字符换成 `-`。
+ * 结果为空 / 只剩 `-`（纯标点、纯空白）时用 `image` 兜底。
+ *
+ * 中文与 emoji 是**合法**字符，原样保留（文件系统支持）。
+ */
+export declare function slugFromPrompt(prompt: string): string;
+/** `<yyyyMMdd-HHmmss>`（本地时区，与用户看到的文件时间一致）。 */
+export declare function imageStamp(when: Date): string;
+/**
+ * 扩展名：**按图片自身的格式**取，未知格式落 `png`。
+ *
+ * 刻意的偏离（设计 §6.2 写的是 `<…>.png`）：客户端同源文件路由按**扩展名**定 MIME
+ * （设计 §1.3），一张 JPEG 存成 `.png` 会被当成 PNG 下发。上游常态是 PNG，
+ * 所以正常路径与文档逐字一致，只有非 PNG 才不同。
+ */
+export declare function imageExtension(format: string, mimeType: string): string;
+/**
+ * 写一张图到 `<workspaceRoot>/图片/`：目录只 `mkdir recursive` 一次，同名加 `-2` / `-3` 后缀。
+ *
+ * 用 `flag: 'wx'`（不存在才创建）而不是「先 exists 再写」：两者之间没有 TOCTOU 窗口，
+ * 命名冲突与真正的写盘失败因此能被分开（前者换名字重试，后者如实上报）。
+ *
+ * @returns 写入的**绝对路径**。
+ */
+export declare function writeImageBytes(workspaceRoot: string, baseName: string, extension: string, bytes: Uint8Array): Promise<string>;
+/** 直接读网关配置；**永不抛异常**（读不到返回 undefined，调用方落默认值）。 */
+export declare function readImageConfig(gateway: ImageGatewayPort, sessionCookie: string, log?: ((message: string) => void) | undefined): Promise<GatewayImageConfig | undefined>;
+/**
+ * 包一层 ≤5 分钟缓存的 `image-config` 读取器（设计 §6.3：工具补默认尺寸时读它）。
+ *
+ * 缓存只存**配置**（开关/模型名/尺寸枚举），不存 cookie、不存任何凭据；同一 Host 进程
+ * 只服务一个登录账号，所以缓存不需要按账号分键。
+ *
+ * 但**要按 `key` 分**：`key` 是调用方给的缓存键（生产传 gateway baseURL）——用户在
+ * 「网关模型」里换了地址之后，旧网关的默认尺寸与模型名不该继续生效 5 分钟。
+ * 只保留最近一个键（换地址是罕见操作，为此维护一张有界 LRU 不值）。
+ */
+export declare function createCachedImageConfigReader(options?: {
+    ttlMs?: number;
+    now?: () => number;
+}): (gateway: ImageGatewayPort, sessionCookie: string, log?: ((message: string) => void) | undefined, key?: string) => Promise<GatewayImageConfig | undefined>;
+/** 通用失败文案（未知 code / message 不可用时的兜底）：不暴露任何网关细节。 */
+export declare const IMAGE_GENERIC_FAILURE_MESSAGE = "\u56FE\u7247\u751F\u6210\u670D\u52A1\u6682\u65F6\u4E0D\u53EF\u7528\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/** 未登录 / 会话失效的统一文案（用量、语音、生图三条频道同口径）。 */
+export declare const IMAGE_SESSION_EXPIRED_MESSAGE = "\u767B\u5F55\u72B6\u6001\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55";
+/**
+ * 各稳定错误码的用户可见文案。
+ *
+ * **唯一的事实源**：`generate` 的失败收敛与 `/hiwork-image` 的消毒（`image-rpc.ts` 从这里
+ * 再导出 {@link displayImageGatewayMessage}）都读它。文案与卡片侧
+ * `src/client/image-cards.tsx` 的 `IMAGE_ERROR_TEXT` **逐字对齐**——卡片按 code 分文案，
+ * 这里只是「网关 message 不可用时的兜底」，两处写着同一句话是有意的：
+ * 卡片不依赖 Host 文案，Host 也不依赖卡片（谁先加载都成立）。
+ */
+export declare const IMAGE_MESSAGE_FALLBACK: Record<string, string>;
+/**
+ * 网关 message 消毒（与 `voice-rpc.ts` 的 `displayVoiceGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。**code 不受影响**，始终原样透传。
+ *
+ * 放在 `imagegen.ts` 是因为**两条消费路径都要它**（工具的失败收敛 + RPC 的信封），
+ * 而 `image-rpc.ts` 依赖 `imagegen.ts`（反向 import 会成环）。
+ */
+export declare function displayImageGatewayMessage(code: string, message: unknown): string;
+/**
+ * 生图并写盘（设计 §6.2）。
+ *
+ * 顺序：① prompt 校验 → ② 会话 → ③ 网关 → ④ 尺寸缺省时取 `image-config` 的默认值
+ * → ⑤ 调网关（带 timeoutMs 的那一条，见 `ai-router-client.ts`）→ ⑥ 解码写盘 → ⑦ 组装结果。
+ *
+ * 写盘失败**不回滚**：回 `code: 'write-failed'` + 上游信息（prompt/model/size/generationMs），
+ * `files` 置空。越界路径回 `code: 'path-outside-workspace'`。
+ */
+export declare function generateImageFile(deps: ImagegenDeps, request: ImageGenerateRequest): Promise<GenerateOutcome>;
+/**
+ * 画廊页 `save`（设计 §6.5）：取本体 → 按生图同一套规则落盘 → 回绝对路径。
+ *
+ * 落点是**默认工作区** `~/HiWork/Default`（画廊页是中央页，没有会话上下文）；给了
+ * `workspaceId` 就用注册表里那个工作区的路径，**取不到即拒绝**（绝不落到别处）。
+ *
+ * 文件名沿用 §6.2 的规则，slug 来自该记录的 `prompt`。记录本体在网关，而冻结入参只有
+ * `{ id, workspaceId? }`（页面按契约只传 id），所以这里**尽力**回查一次列表拿 prompt：
+ * 查不到、或第一页里没有这条记录，就用 `image` 兜底——**不为一个文件名把保存变成硬依赖**。
+ *
+ * 失败分两类：网关/会话错误**抛** `GatewayError`（由 RPC 层映射成稳定 code）；
+ * 工作区解析 / 写盘这类业务失败回 `{ok:false, code, reason}`。
+ */
+export declare function saveImageToWorkspace(deps: ImagegenDeps, request: {
+    id: number;
+    workspaceId?: string | undefined;
+    prompt?: string | undefined;
+}): Promise<SaveImageOutcome>;
+/** 画廊页 `list` 的一行（冻结契约 `ImageRow`，设计 §6.5）。 */
+export type ImageRow = GatewayImageRow;

package/lib/types/index.d.ts

@@ -1,12 +1,15 @@
 /**
  * hiwork-core：企业 ai-router 网关登录 + 模型自动加载插件（Host 半边）。
- * 注册 `ai-router` settings 命名空间；卡片写入的请求字段（pendingLogin /
- * refreshRequest / logoutRequest）经 settings.installSection 的 onChange 触发
- * 编排，编排结果回写该命名空间的状态字段（lastLogin / lastError）。
+ *
+ * rc.2 起 dsh-settings 的 seam 重写：不再有 installSection / register —— 配置面改为
+ * 「插件 Config schema 的 `.volatile()` 字段经 configEditor 投影成表单」，settings 命名空间
+ * 就是本插件在 profile 里的 entry id（`ai-router`，见 cordis.patch.yml 的 insert 行，两处必须
+ * 逐字一致）。卡片写入的请求字段（pendingLogin / refreshRequest / logoutRequest）经
+ * `settings/document-updated` 事件触发编排，编排结果回写本 entry 的 volatile 字段。
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import { type SettingsProvider } from '@deepseek-ai/dsh-settings';
+import type SettingsForms from '@deepseek-ai/dsh-settings';
 import { fetchClientPolicy, type ClientPolicy, type LoginMode } from './client-policy.ts';
 import { type CredentialsPort, type DefaultModelPort, type AiRouterStatePort } from './orchestration.ts';
 export declare const name = "hiwork-core";
@@ -14,9 +17,30 @@ export declare const name = "hiwork-core";
  * 必需服务：`connection` 承载设置页「用量与成本」的 loopback RPC 频道
  * （`/hiwork-usage`，见 `src/usage-rpc.ts`）；`web` 承载联网搜索 provider 的注册
  * （`ctx.web.registerSearchProvider`，见 `src/web-search.ts`；dsh-base 基座先于本
- * 插件挂载 dsh-web）；其余三项是既有登录 / 供给依赖。
+ * 插件挂载 dsh-web）；`agents` 是根 Agent 注册表——`image_generate` 工具要挂在根 Agent
+ * 上（`ctx.agents.roots()` / `agent/created`，见 `src/tools.ts`；与 knowledge 的
+ * `inject` 同源）；其余三项是既有登录 / 供给依赖。
  */
 export declare const inject: string[];
+/** 侧栏菜单偏好的解析值（client 侧 `MenuPreferences` 的同一份形状）。 */
+export interface MenuConfigValue {
+    /** 展示顺序（feature id）。 */
+    order: string[];
+    /** 明确显示在侧栏的 id。 */
+    sidebar: string[];
+    /** 明确收进「更多」的 id。 */
+    more: string[];
+    /** 明确隐藏的 id（侧栏与「更多」都不出现）。 */
+    hidden: string[];
+}
+/**
+ * 菜单偏好 schema：四个 id 数组，缺省全空（= 用户从未自定义 → 由 client 按默认规则分组）。
+ *
+ * 这里**不做枚举校验**：合法的 id 集合由「当前装配了哪些 feature」决定，是运行期事实，写死在 host
+ * 的 schema 里会立刻过期（插件装了/卸了都会变）。归一化与清理在 client 侧完成（`normalizeMenuPreferences`），
+ * 未知 id 在渲染时被忽略而不是拒绝写入——否则用户装过一次又卸掉的插件会永久毒化这份偏好。
+ */
+export declare const MenuConfig: z<MenuConfigValue>;
 /** 插件配置 + 运行时状态字段（全部可选；写操作按此 schema 校验）。 */
 export interface Config {
     baseURL?: string;
@@ -79,8 +103,55 @@ export interface Config {
         max_concurrency?: number;
         key_masked?: string;
     }>;
+    /**
+     * 侧栏菜单偏好（rc.2 起并入本 entry；此前是独立的 `hiwork-menu` settings 命名空间，
+     * 而 rc.2 的 settings 只服务「有 profile entry 的 Config」，纯客户端偏好没有自己的 entry
+     * 可挂，遂改挂本 entry 的 volatile 字段。旧值由 `importLegacyMenuSection` 一次性搬迁）。
+     */
+    menu?: MenuConfigValue;
 }
 export declare const Config: z<Config>;
+/**
+ * apply 收到的运行时 config：volatile 字段是稳定引用（schemastery 解析期包装，值为
+ * undefined 时引用依然存在），随 profile 变更被框架原地更新——持有引用、每次现取，
+ * 绝不缓存 `.get()` 的结果。baseURL 仍是普通组合层配置。
+ */
+export type RuntimeConfig = {
+    baseURL?: string;
+} & {
+    [K in Exclude<keyof Config, 'baseURL'>]?: Volatile<Config[K]>;
+};
+/**
+ * settings.mutate 的路径操作（rc.2 的 dsh-settings 不再导出 `SettingsPathOp` 类型，
+ * 这里按其结构本地声明——形状逐字对齐上游 `packages/settings/settings/src/index.ts`）。
+ */
+export type SettingsPathOp = {
+    op: 'set';
+    path: readonly string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: readonly string[];
+};
+/** 失败是否是「事务内写」——调用方据此判断轮询上下文已被 HMR 事务污染（见 apply）。 */
+export declare function isHmrNestedWriteError(error: unknown): boolean;
+/**
+ * 写一个命名空间（= profile entry id）。
+ *
+ * 每次尝试都重读 `describe()` 取最新 revision；可重试错误在截止时间前带退避重试，超时后
+ * 抛出**真实**错误——不降级成「conflicted repeatedly」，免得把根因从日志里抹掉。
+ * 退避上限 1s：命名空间注册与 HMR 事务都在秒级内收敛，重试代价可忽略。
+ *
+ * @param settings - settings 服务。
+ * @param ns - 命名空间（profile entry id）。
+ * @param ops - 路径操作。
+ * @param opts - 重试窗口与退避（单测用来把窗口压到毫秒级）。
+ */
+export declare function writeNamespace(settings: SettingsForms, ns: string, ops: SettingsPathOp[], opts?: {
+    deadlineMs?: number;
+    minBackoffMs?: number;
+    maxBackoffMs?: number;
+}): Promise<void>;
 /** 校正默认模型要用到的 llm 注册表部分（便于单测注入假实现）。 */
 export interface LlmRouteRegistry {
     listProviders(): readonly {
@@ -99,7 +170,7 @@ export interface LlmRouteRegistry {
  * @returns 供编排调用的默认模型端口。
  */
 export declare function createDefaultModelPort(opts: {
-    settings: SettingsProvider;
+    settings: SettingsForms;
     llm: LlmRouteRegistry | undefined;
     log?: (message: string) => void;
 }): DefaultModelPort;
@@ -174,4 +245,14 @@ export declare function projectLoginMode(opts: {
     fetchPolicy?: (input: Parameters<typeof fetchClientPolicy>[0]) => Promise<ClientPolicy | undefined>;
     log?: (message: string) => void;
 }): Promise<LoginMode>;
-export declare function apply(ctx: Context, config: Config): void;
+/**
+ * 把运行时 config 的 volatile 引用解成普通值快照（浅层遍历；只处理本插件 Config 的
+ * 数据形状）。识别 Volatile 引用用鸭子类型：cosmokit 的 createVolatile 返回「只有一
+ * 个字符串键 get 的冻结对象」，本插件 Config 的数据形状里没有任何带 get 方法的成员，
+ * 不会误伤。rc.2 起 cordis 只 re-export Volatile 类型、不导出运行时 isVolatile，
+ * 为避免依赖树外的 cosmokit 直依赖，这里本地判定。
+ *
+ * 导出仅供 tests/plain-value.spec.ts 锁定判定契约（见该文件头），不是对外的插件 API。
+ */
+export declare function plainValue(value: unknown): unknown;
+export declare function apply(ctx: Context, config: RuntimeConfig): void;

package/lib/types/knowledge-config.d.ts

@@ -2,8 +2,18 @@
 export declare const HIWORK_KNOWLEDGE_SERVICE = "hiworkKnowledge";
 /** 网关侧端点（跨仓冻结；与 `/api/me/memory-config` 同一条会话鉴权）。 */
 export declare const ME_KNOWLEDGE_CONFIG_PATH = "/api/me/knowledge-config";
-/** 成功结果的缓存 TTL：5 分钟。 */
+/** 成功结果的缓存 TTL：5 分钟（与网关签发的令牌寿命同量级）。 */
 export declare const KNOWLEDGE_CONFIG_TTL_MS: number;
+/**
+ * **令牌**缓存的提前量：令牌寿命与缓存 TTL 都是 5 分钟时，缓存到期时刻恒晚于令牌 `exp`
+ * （响应到达 = 签发 + 一次往返），那段时间里命中的令牌**必然已过期** → 上游 401 → 插件
+ * 强制刷新一次再重试。留 30 秒余量把这条无谓的 401 往返消掉。
+ *
+ * （配置缓存的 TTL 不需要余量：`base_url`/`api_key` 没有自带寿命。）
+ */
+export declare const KNOWLEDGE_TOKEN_CACHE_MARGIN_MS = 30000;
+/** 令牌缓存的 TTL：比令牌寿命短一点（见上面的理由）。 */
+export declare const KNOWLEDGE_TOKEN_CACHE_TTL_MS: number;
 /** 出网超时（与 `AiRouterClient` 的缺省一致）。 */
 export declare const KNOWLEDGE_CONFIG_TIMEOUT_MS = 10000;
 /**
@@ -27,15 +37,51 @@ export interface HiworkKnowledgeConfigView {
     agentId?: string;
     chatModelId?: string;
     tenantId?: string;
+    /**
+     * 网关下发的**展示**范围（设计 §3.1 的第六个字段 `knowledge_bases`）：去空 ID、按 ID 去重、
+     * 名称 trim。缺省即空数组——**展示字段不是权限依据**，权限依据是 `token()` 面的
+     * `knowledgeBaseIds`（设计 §3.1「展示名称不是权限依据」）。
+     *
+     * 为什么必须带出来：网关（hiwork-admin）确实在下发它（`me_knowledge_handler.go` 的
+     * `knowledge_bases`，同样做了去空/去重/trim），而这里过去只投影五个字段、把它丢了 ——
+     * 结果是插件侧读它的那段兼容代码**永远是死代码**，且宿主没有 token 面时（老 core 形状）
+     * 授权范围只能恒为空。展示与兜底都需要它，所以按视图口径翻成 camelCase 带出来。
+     */
+    knowledgeBases?: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
     reason?: HiworkKnowledgeFailureReason;
     message?: string;
 }
 /** 本服务对宿主的可调用面（只读、永不抛异常）。 */
+export interface HiworkKnowledgeTokenView {
+    ok: boolean;
+    token?: string;
+    audience?: string;
+    knowledgeBaseIds?: string[];
+    /**
+     * 授权范围的展示信息（`token()` 面：**只保留在 ID 范围内的项**，见下方测试）。
+     * 写成只读，与 `HiworkKnowledgeConfigView.knowledgeBases` 同形——两个视图在
+     * `failure()` 返回值上是同一份数据的两种键名，形状不一致会让 token 面的失败返回
+     * 连类型都过不去。
+     */
+    knowledgeBases?: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
+    reason?: HiworkKnowledgeFailureReason;
+    message?: string;
+}
 export interface HiworkKnowledgeService {
-    /** 取当前登录员工的知识库配置；force=true 绕过缓存（设置页「重新获取配置」与 401 自愈）。 */
+    /** 取当前登录员工的知识库配置；force=true 绕过缓存。 */
     config(opts?: {
         force?: boolean;
     }): Promise<HiworkKnowledgeConfigView>;
+    /** 取当前会话的短期知识库 token；仅 Host-to-Host 服务面可见。 */
+    token(opts?: {
+        force?: boolean;
+    }): Promise<HiworkKnowledgeTokenView>;
 }
 /**
  * 网关侧原始响应（**snake_case**，跨仓冻结契约；本文件是唯一读它的地方）。
@@ -73,6 +119,8 @@ export type KnowledgeConfigOutcome = {
 export interface KnowledgeConfigGatewayPort {
     /** 调 `GET /api/me/knowledge-config`，返回 snake_case 原始响应或一个稳定失败原因。 */
     getMyKnowledgeConfig(sessionCookie: string): Promise<KnowledgeConfigOutcome>;
+    /** 为当前会话签发短期知识库令牌；老 core 可省略。 */
+    getMyKnowledgeToken?: (sessionCookie: string) => Promise<unknown>;
 }
 /** Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关出网端口。 */
 export interface KnowledgeConfigDeps {

package/lib/types/tool-names.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 生图工具名的**单一事实源**。
+ *
+ * Web 半边（`src/client/ImageCards.tsx` 的 `tool.call.toolview` keyed 座位）与 Host 注册
+ * 都从这里读同一个常量：keyed 座位**按线上工具名认领**，名字拼错的失败方式是**静默**的
+ * ——卡片永不渲染、通用工具行照常出现，没有任何测试会因为它变红（knowledge 已踩过）。
+ * 所以这里既导出元组，也导出它的元素类型（`Record<ImageToolName, …>` 这种写法能在
+ * 编译期挡住「新增工具忘了补卡片」）。
+ */
+export declare const IMAGE_TOOL_NAMES: readonly ["image_generate"];
+export type ImageToolName = (typeof IMAGE_TOOL_NAMES)[number];