hiwork-core 0.0.29 → 0.0.35

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,36 @@ 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[];
+};
 /** 校正默认模型要用到的 llm 注册表部分（便于单测注入假实现）。 */
 export interface LlmRouteRegistry {
     listProviders(): readonly {
@@ -99,7 +151,7 @@ export interface LlmRouteRegistry {
  * @returns 供编排调用的默认模型端口。
  */
 export declare function createDefaultModelPort(opts: {
-    settings: SettingsProvider;
+    settings: SettingsForms;
     llm: LlmRouteRegistry | undefined;
     log?: (message: string) => void;
 }): DefaultModelPort;
@@ -174,4 +226,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];

package/lib/types/tools.d.ts

@@ -0,0 +1,80 @@
+import { type GenerateOutcome } from './imagegen.ts';
+import { IMAGE_TOOL_NAMES } from './tool-names.ts';
+export { IMAGE_TOOL_NAMES };
+/**
+ * 生图工具的单次预算（**工具层护栏**，不是业务判据）。
+ *
+ * 它必须**大于**客户端真正会等的时间，否则工具会先掐断客户端请求，把一次本可成功的
+ * 生图变成工具超时。客户端等待上限 = 网关预算 + 15s（见 `imageGenerateTimeoutMs`），
+ * 而网关预算的合法上界是 600s、读不到配置时走 900s 兜底 ⇒ 工具预算取 960s（16 分钟），
+ * 比两者都高。真正的超时语义由网关的 504 / `IMAGE_TIMEOUT` 表达。
+ *
+ * 实测背景：原值 330s 是按「网关默认 180s」估的，而网关上界 600s、实测单张已到 415s
+ * —— 按那条估算会在合法的慢生图上误报。
+ */
+export declare const IMAGE_TOOL_TIMEOUT_MS = 960000;
+/**
+ * 注册工具所需的最小 Agent 结构端口（不 import DSH agent 运行时）。
+ * 与 knowledge 的 `KnowledgeAgent` 同形：`id` 用于身份判定，`ctx.tools.register` 是落点。
+ */
+export type ImageAgent = {
+    readonly id: string;
+    readonly ctx: {
+        readonly tools: {
+            register(definition: unknown): () => void;
+        };
+    };
+};
+/**
+ * 工具执行期读到的会话/取消面（结构端口，便于单测直接伪造：
+ * `{ agent: { session: { header: { cwd } } }, signal }`）。
+ */
+export interface ImageToolExec {
+    readonly agent?: {
+        readonly session?: {
+            readonly header?: {
+                readonly cwd?: string;
+            };
+        };
+    } | undefined;
+    readonly signal: AbortSignal;
+}
+/** 工具对 Host 生图服务的全部要求（生产由 `src/imagegen.ts` 的 `generateImageFile` 满足）。 */
+export interface ImageToolService {
+    generate(request: {
+        prompt: string;
+        size?: string | undefined;
+        workspaceRoot?: string | undefined;
+    }): Promise<GenerateOutcome>;
+}
+/** 工具的模型可见描述（设计 §6.3 逐字冻结）。 */
+export declare const IMAGE_GENERATE_DESCRIPTION: string;
+/** 卡片数据源（JSON 形态）：与 `GenerateOutcome` 同形，外加给模型读的 `text`。 */
+export interface ImageToolValue {
+    ok: boolean;
+    /** 给模型读的那段话（见 {@link formatImageGenerateText}）。 */
+    text: string;
+    files: Array<{
+        path: string;
+        mimeType: string;
+        byteSize: number;
+        revisedPrompt?: string;
+    }>;
+    prompt?: string;
+    model?: string;
+    size?: string;
+    generationMs?: number;
+    code?: string;
+    message?: string;
+}
+/** 模型可见的那段话（成功：路径 + 尺寸/模型/耗时 + 落盘说明；失败：原因 + 可执行提示）。 */
+export declare function formatImageGenerateText(outcome: GenerateOutcome): string;
+/** `GenerateOutcome` → 工具结果（卡片与模型共用同一份 JSON）。 */
+export declare function toImageToolValue(outcome: GenerateOutcome): ImageToolValue;
+/**
+ * 给一个根 Agent 注册生图工具。
+ * @param service - Host 侧生图服务（生产是 `src/imagegen.ts` 的 `generateImageFile`）。
+ * @param agent - 目标根 Agent。
+ * @returns 注销器（注销全部已注册工具）。
+ */
+export declare function registerImageTools(service: ImageToolService, agent: ImageAgent): () => void;

package/lib/types/user-agent.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 发往网关的 `User-Agent`：`hiwork/<桌面端版本>`。
+ *
+ * 「客户端」在网关侧就是这一条头（请求日志的客户端列、排障时的流量归属），所以它必须报
+ * **产品 + 版本**，而不是插件内部包名。版本号取桌面端版本：这是运维真正关心的维度
+ * （哪一版客户端），插件版本对同一台机器上的所有请求都相同，报它区分不出客户端版本。
+ *
+ * 版本来源的优先级（高 → 低）：
+ *  1. 环境变量 `HIWORK_APP_VERSION`——桌面端拉起 DSH 时注入，**宿主进程一启动就有**；
+ *  2. 桌面端经 IPC 推来的设备信息里的 `appVersion`（见 `src/browser-login.ts`）——
+ *     推送发生在宿主就绪之后，早于它的请求拿不到，所以只作兜底；
+ *  3. 两者都没有（纯 `dsh web` / CLI 场景）——回报插件自身的 `hiwork-core/<插件版本>`，
+ *     不拿插件版本冒充桌面端版本。
+ *
+ * 值一律经 {@link headerSafeVersion} 过滤后再进 header：环境变量与 IPC 都可能带来空串、
+ * 前后空白或换行，而 fetch 遇到非法 header 值会直接抛错——那会让每一次网关请求都失败。
+ */
+/** 桌面端注入自身版本用的环境变量名；两侧契约，改这里必须同步 `hiwork-desktop/src/main.ts`。 */
+export declare const DESKTOP_APP_VERSION_ENV = "HIWORK_APP_VERSION";
+/**
+ * 桌面端版本号。
+ * @param env - 环境变量表；缺省 `process.env`（测试可注入）。
+ * @returns 版本号；环境变量与 IPC 都没有时 undefined。
+ */
+export declare function desktopAppVersion(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * 网关请求的 User-Agent。
+ * @param version - 桌面端版本；缺省按 {@link desktopAppVersion} 解析（测试可注入）。
+ * @returns `hiwork/<桌面端版本>`；拿不到桌面端版本时 `hiwork-core/<插件版本>`。
+ */
+export declare function gatewayUserAgent(version?: string | undefined): string;

package/lib/user-agent.js

@@ -0,0 +1,54 @@
+/**
+ * 发往网关的 `User-Agent`：`hiwork/<桌面端版本>`。
+ *
+ * 「客户端」在网关侧就是这一条头（请求日志的客户端列、排障时的流量归属），所以它必须报
+ * **产品 + 版本**，而不是插件内部包名。版本号取桌面端版本：这是运维真正关心的维度
+ * （哪一版客户端），插件版本对同一台机器上的所有请求都相同，报它区分不出客户端版本。
+ *
+ * 版本来源的优先级（高 → 低）：
+ *  1. 环境变量 `HIWORK_APP_VERSION`——桌面端拉起 DSH 时注入，**宿主进程一启动就有**；
+ *  2. 桌面端经 IPC 推来的设备信息里的 `appVersion`（见 `src/browser-login.ts`）——
+ *     推送发生在宿主就绪之后，早于它的请求拿不到，所以只作兜底；
+ *  3. 两者都没有（纯 `dsh web` / CLI 场景）——回报插件自身的 `hiwork-core/<插件版本>`，
+ *     不拿插件版本冒充桌面端版本。
+ *
+ * 值一律经 {@link headerSafeVersion} 过滤后再进 header：环境变量与 IPC 都可能带来空串、
+ * 前后空白或换行，而 fetch 遇到非法 header 值会直接抛错——那会让每一次网关请求都失败。
+ */
+import { PKG_VERSION } from "./version.js";
+import { pushedAppVersion } from "./browser-login.js";
+/** 桌面端注入自身版本用的环境变量名；两侧契约，改这里必须同步 `hiwork-desktop/src/main.ts`。 */
+export const DESKTOP_APP_VERSION_ENV = 'HIWORK_APP_VERSION';
+/**
+ * 版本号允许的形态：以字母或数字开头，其后只允许 semver 常见字符（`0-9 A-Z a-z . + - _`）。
+ *
+ * **必须是白名单，不能只过滤控制字符**：换成「删掉 `\n` 就放行」的写法时，
+ * `"1.0.7\nX-Injected: evil"` 会被拼成 `hiwork/1.0.7X-Injected: evil` —— 换行没了，
+ * 但被注入的文本原样进了 header，运维在网关看到的是一串看不懂的客户端名。
+ * 版本号本来就不该含空格/冒号，所以「不像版本号就当作没拿到」比「尽量修好它」正确。
+ */
+const versionPattern = /^[0-9A-Za-z][0-9A-Za-z.+_-]*$/;
+/** 版本号安全化：只接受白名单形态；空串、含空白/控制字符/其他标点一律视为「没拿到版本」。 */
+function headerSafeVersion(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return versionPattern.test(trimmed) ? trimmed : undefined;
+}
+/**
+ * 桌面端版本号。
+ * @param env - 环境变量表；缺省 `process.env`（测试可注入）。
+ * @returns 版本号；环境变量与 IPC 都没有时 undefined。
+ */
+export function desktopAppVersion(env = process.env) {
+    return headerSafeVersion(env[DESKTOP_APP_VERSION_ENV]) ?? headerSafeVersion(pushedAppVersion());
+}
+/**
+ * 网关请求的 User-Agent。
+ * @param version - 桌面端版本；缺省按 {@link desktopAppVersion} 解析（测试可注入）。
+ * @returns `hiwork/<桌面端版本>`；拿不到桌面端版本时 `hiwork-core/<插件版本>`。
+ */
+export function gatewayUserAgent(version = desktopAppVersion()) {
+    const safe = headerSafeVersion(version);
+    return safe === undefined ? `hiwork-core/${PKG_VERSION}` : `hiwork/${safe}`;
+}

package/lib/web-search.js

@@ -34,7 +34,7 @@
  * 端口，接线方（index.ts）传真实 ctx 侧依赖；单测直接伪造。
  */
 import { WebError } from '@deepseek-ai/dsh-web';
-import { PKG_VERSION } from "./version.js";
+import { gatewayUserAgent } from "./user-agent.js";
 /** 本 provider 注册进 `ctx.web` 用的稳定 id（cordis.patch.yml 的 searchProvider pin 与它逐字一致）。 */
 export const HIWORK_SEARCH_PROVIDER_ID = 'hiwork-managed-search';
 /** 网关侧端点（跨仓冻结；会话鉴权与 `/api/me/memory-config` 同一条）。 */
@@ -208,7 +208,7 @@ export function createWebSearchGateway(baseURL, opts = {}) {
                 res = await doFetch(`${root}${ME_WEB_SEARCH_PATH}`, {
                     method: 'POST',
                     headers: {
-                        'user-agent': `hiwork-core/${PKG_VERSION}`,
+                        'user-agent': gatewayUserAgent(),
                         cookie: sessionCookie,
                         'content-type': 'application/json',
                     },