hiwork-core 0.0.30 → 0.0.35

package/lib/types/client/images-page.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 「我的图片」画廊页（中央 feature `id: 'images'`、`order: 60`，**core 自己注册**）。
+ *
+ * 形态（spec §6.5）：**左列表 + 右预览**。
+ *  - 列表：分页（默认 20，「加载更多」追加），每行是提示词摘要 + 尺寸 + 时间 + 大小；
+ *  - 预览：**只有选中某一条才 `fetch` 那张图**（这是「不一次拉几十 MB」的唯一守卫——
+ *    用例里断言未选中时零 `fetch` 调用）；拿回来的字节用 **data URL** 渲染，
+ *    **不写盘、不建指向本地文件的 `<img src>`**；
+ *  - 动作：**「存到工作区」**（成功后行内显示落点路径）与**「复制提示词」**；
+ *    **不做**「再来一张」——画廊是中央 takeover，退到会话才能发消息，跨屏填草稿的收益
+ *    不抵复杂度（列入 M1 评估）。
+ *
+ * 为什么注册在 core 而不是新插件：这两条 RPC 只走 `connection.rpc`（`/hiwork-image`），
+ * 而网关访问必须留在 core 的 Host 半边；本页除了 `connection.rpc` 与 feature 注册表
+ * 之外不依赖任何其它插件。历史读的是**既有**的员工自助端点，与 `image.enabled` 开关
+ * 无关（关开关只关「生成」，不关「查看」）。
+ *
+ * client bundle 纯度：不 import 任何 `@deepseek-ai/*` 运行时值，也不 import Host 代码。
+ */
+import { type ReactElement } from 'react';
+import type { FeatureRegistry, HiWorkFeature } from './feature-registry.ts';
+import { type ImageDataSource } from './images-data.ts';
+/** 中央 feature id（冻结契约）。 */
+export declare const IMAGES_FEATURE_ID = "images";
+/** 中央 feature 排序：跟在 workbench 10 / automation 20 / knowledge 30 / capabilities 40 / office 50 之后。 */
+export declare const IMAGES_FEATURE_ORDER = 60;
+/** 侧栏菜单文案（core 未注册 locale 命名空间，硬编码中文）。 */
+export declare const IMAGES_FEATURE_LABEL = "\u6211\u7684\u56FE\u7247";
+/** 注册段的 effect 标签（诊断用；也是接线守卫的锚点）。 */
+export declare const IMAGES_FEATURE_EFFECT_LABEL = "hiwork-core: images feature";
+/**
+ * 菜单图标：16 网格、`currentColor`、描边 1.2（官方图标集里没有「我的图片」这一格，
+ * 按官方比例自绘，惯例同 hiwork-im / feature-center 的自绘图标）。
+ */
+export declare const IMAGES_FEATURE_ICON = "<svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><rect x=\"1.6\" y=\"2.6\" width=\"12.8\" height=\"10.8\" rx=\"1.8\" stroke=\"currentColor\" stroke-width=\"1.2\"></rect><circle cx=\"5.7\" cy=\"6.3\" r=\"1.05\" fill=\"currentColor\"></circle><path d=\"M2.6 11.4l3.1-2.9c.4-.4 1-.4 1.4 0l2.1 2 1.4-1.3c.4-.4 1-.4 1.4 0l1.4 1.3\" stroke=\"currentColor\" stroke-width=\"1.2\" stroke-linecap=\"round\"></path></svg>";
+/** 空态（spec §6.5 逐字）。 */
+export declare const IMAGES_EMPTY_TEXT = "\u8FD8\u6CA1\u6709\u751F\u6210\u8FC7\u56FE\u7247";
+/** 空态的第二句（告诉用户怎么产生第一张）。 */
+export declare const IMAGES_EMPTY_HINT = "\u5728\u4F1A\u8BDD\u91CC\u8BF4\u300E\u753B\u4E00\u5F20\u2026\u300F\u5C31\u80FD\u751F\u6210";
+/** 加载中。 */
+export declare const IMAGES_LOADING_TEXT = "\u6B63\u5728\u52A0\u8F7D\u56FE\u7247\u8BB0\u5F55\u2026";
+/** 预览区未选中任何一条时的占位。 */
+export declare const IMAGES_PREVIEW_PLACEHOLDER = "\u4ECE\u5DE6\u4FA7\u9009\u4E00\u5F20\u56FE\u7247\u67E5\u770B";
+/** 预览图正在拉取（这是唯一会拉几十 MB 的地方，必须让用户看见）。 */
+export declare const IMAGES_PREVIEW_LOADING_TEXT = "\u6B63\u5728\u52A0\u8F7D\u56FE\u7247\u2026";
+/** `image.enabled=false` 时仍可看历史，但要说明「生成」被关掉了（spec §7.2 V11）。 */
+export declare const IMAGES_DISABLED_NOTE = "\u7BA1\u7406\u5458\u8FD8\u6CA1\u5F00\u542F\u56FE\u7247\u751F\u6210";
+/** 缺失字段的占位符（**不是 0**）。 */
+export declare const IMAGES_MISSING_TEXT = "\u2014";
+/** 动作文案。 */
+export declare const IMAGES_SAVE_TEXT = "\u5B58\u5230\u5DE5\u4F5C\u533A";
+export declare const IMAGES_SAVE_SAVED_PREFIX = "\u5DF2\u4FDD\u5B58\u5230 ";
+export declare const IMAGES_SAVE_RUNNING_TEXT = "\u6B63\u5728\u4FDD\u5B58\u2026";
+export declare const IMAGES_COPY_TEXT = "\u590D\u5236\u63D0\u793A\u8BCD";
+export declare const IMAGES_MORE_TEXT = "\u52A0\u8F7D\u66F4\u591A";
+export declare const IMAGES_RETRY_TEXT = "\u91CD\u8BD5";
+export declare const IMAGES_SAVE_HINT = "\u56FE\u7247\u4F1A\u5B58\u5230\u4F60\u7684\u9ED8\u8BA4\u5DE5\u4F5C\u533A\uFF08~/HiWork/Default\uFF09\u7684\u300C\u56FE\u7247\u300D\u76EE\u5F55\u3002";
+/** 复制反馈（同卡片口径：不可用只把提示切到「复制失败」）。 */
+export declare const IMAGES_COPY_HINTS: {
+    readonly copied: "已复制";
+    readonly failed: "复制失败";
+};
+/** 画廊页属性：只依赖一个窄取数面（测试可注入假实现）。 */
+export interface ImagesPageProps {
+    readonly source: ImageDataSource;
+}
+/**
+ * 「我的图片」画廊页。
+ * @param props - 取数面。
+ * @returns 页面元素。
+ */
+export declare function ImagesPage({ source }: ImagesPageProps): ReactElement;
+/**
+ * 注册所需的上下文面（只需要 `effect`）。
+ *
+ * 为什么写成窄面而不是要求真实 `ClientContext`：注册的**生命周期**才是这条链路的
+ * 不变量——`ctx.effect(() => registry.register(...))` 让注销随插件 fiber 走，插件热替换
+ * 后注册表里不会留下指向旧实例的条目。窄面让这条不变量可以单测（假 scope 记录
+ * factory 并手动触发清理），也不必在测试里拉起整个 cordis。
+ */
+export interface ImagesFeatureScope {
+    /** cordis 的 effect 体**必须**返回 disposer（`SyncEffect` 不含纯 void），与真实 ctx.effect 同形。 */
+    effect(factory: () => () => void, label?: string): unknown;
+}
+/**
+ * 构造 feature 定义（纯函数：测试可直接断言 id / order / label / icon）。
+ * @param source - 画廊取数面。
+ * @returns feature 定义。
+ */
+export declare function imagesFeature(source: ImageDataSource): HiWorkFeature;
+/**
+ * 注册「我的图片」中央页（**用 `ctx.effect` 包住**：disposer 幂等，注销后从注册表消失）。
+ * @param scope - 带 `effect` 的上下文（`apply` 传真实 client ctx）。
+ * @param registry - core 自己的 Feature Center 注册表。
+ * @param source - 画廊取数面（经 `connection.rpc` 指向 `/hiwork-image`）。
+ */
+export declare function installImagesFeature(scope: ImagesFeatureScope, registry: FeatureRegistry, source: ImageDataSource): void;

package/lib/types/client/index.d.ts

@@ -1,7 +1,6 @@
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 export type { FeatureRenderContext, FeatureRegistry, HiWorkFeature } from './feature-registry.ts';
 export type { HiWorkCoreClientFace } from './contracts.ts';
-/** 浏览器插件契约（dsh client module system）。connection 承载 loopback RPC（见 src/client/usage-data.ts）。 */
 export declare const inject: string[];
 /** 挂载网关模型设置 section（一级 tab）与未登录弹窗。 */
 export declare function apply(ctx: ClientContext): void;

package/lib/types/client/login-gate.d.ts

@@ -1,4 +1,4 @@
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { CredentialStorePort } from './controller.ts';
 import type { LoginError } from './types.ts';
 import { type AiRouterCardSettings } from './controller.ts';
@@ -19,4 +19,4 @@ export declare function loginGateVisible(snapshot: {
         };
     } | undefined;
 } | undefined): boolean;
-export declare function mountLoginGate(scope: SettingsScope<AiRouterCardSettings>, storeCredential: CredentialStorePort): () => void;
+export declare function mountLoginGate(form: ConfigForm<AiRouterCardSettings>, storeCredential: CredentialStorePort): () => void;

package/lib/types/client/logo.d.ts

@@ -2,5 +2,10 @@
 export declare const HIWORK_LOGO: string;
 export declare const HIWORK_LOGO_TEXT: string;
 export declare const HIWORK_LOGO_WITH_TEXT: string;
-/** HiWork 产品版本：品牌展示元素，与 hiwork-dsh-ui 的 HIWORK_VERSION 保持一致。 */
-export declare const HIWORK_VERSION = "1.0.4";
+/**
+ * HiWork 产品版本兜底常量：只在**无桌面壳**（纯 web / 浏览器 dev，`/hiwork-app` 频道
+ * 取不到值）时显示——侧栏 brand 行与设置「关于」分区的回退值。桌面端在壳内永远走
+ * RPC 动态取真实版本，本常量不参与；跟随桌面端当前发布线手工维护（2026-09-25 对齐
+ * 1.0.7）。
+ */
+export declare const HIWORK_VERSION = "1.0.7";

package/lib/types/client/menu-preferences.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 侧栏菜单的每用户偏好（settings 命名空间 `hiwork-menu` 的读侧模型与纯函数）。
+ *
+ * 为什么单独一份：菜单适配器（`feature-center.ts`）与设置分区（`menu-section.tsx`）必须按**同一套**
+ * 规则回答「谁在侧栏、谁进『更多』、谁被隐藏、按什么顺序」，规则只允许有一处实现——这里。
+ * 本模块不碰 DOM、不碰 cordis，全部是可单测的纯函数。
+ *
+ * 命名空间字面量 `hiwork-menu` 在 host 半边（`src/index.ts` 的 `MENU_NS`）另有一份：client 半边的
+ * 打包 rootDir 是 `src/client`，不能 import host 模块（与 `ai-router` 同款处理）。两侧一致性由
+ * `tests/menu-namespace.spec.ts` 静态守着，改一处必须改两处。
+ */
+import { type MenuFeature } from './feature-registry.ts';
+/** settings 命名空间（host 侧同名注册；两侧字面量必须逐字一致）。 */
+export declare const HIWORK_MENU_NS = "hiwork-menu";
+/**
+ * 未自定义时侧栏直显的条数上限（不含原生的「新会话」）。
+ *
+ * 达到上限之后，用户没有明确标记的入口一律进「更多」——这正是「以后再装插件也不会把侧栏顶高」
+ * 的机制（新插件的 id 不在偏好里 = 未标记 = 超出上限就走「更多」）。
+ */
+export declare const DEFAULT_SIDEBAR_LIMIT = 5;
+/** 菜单里「更多」那一行的固定 id（与 feature id 同域，但永不来自注册表）。 */
+export declare const MORE_MENU_ITEM_ID = "__hiwork_more__";
+/** 「更多」这一行的文案（hiwork-core 未注册 locale 命名空间，沿用硬编码中文）。 */
+export declare const MORE_MENU_LABEL = "\u66F4\u591A";
+/**
+ * 设置分区与分区标题共用文案。
+ *
+ * `settings.section` 注册的 label 同时是设置弹窗导航按钮的可见文本，`openSettingsSection`
+ * 按它精确匹配跳转（见 `settings-navigation.ts`），改措辞要一起改。
+ */
+export declare const MENU_SECTION_LABEL = "\u4FA7\u680F\u83DC\u5355";
+/** 一个入口的三种去向。 */
+export declare const MENU_PLACEMENTS: readonly ["sidebar", "more", "hidden"];
+export type MenuPlacement = (typeof MENU_PLACEMENTS)[number];
+/**
+ * 一个用户的侧栏菜单偏好（settings 命名空间的解析值）。
+ *
+ * 四个字段都是 `string[]`（feature id），不用三态对象数组：读写都发生在「把某个 id 挪一下」这一个
+ * 动作上，分开存可以直接把「一次移动」写成一次原子 `mutate`，也不怕以后加态。
+ */
+export interface MenuPreferences {
+    /** 展示顺序；未列出的排在后面，按插件注册的 `order`。 */
+    readonly order: readonly string[];
+    /** 用户明确要求显示在侧栏的 id。 */
+    readonly sidebar: readonly string[];
+    /** 用户明确要求收进「更多」的 id。 */
+    readonly more: readonly string[];
+    /** 用户明确要求隐藏的 id（侧栏与「更多」都不出现）。 */
+    readonly hidden: readonly string[];
+}
+/** 空偏好：等价于「用户从未自定义」，分组按 {@link DEFAULT_SIDEBAR_LIMIT} 与注册顺序推导。 */
+export declare const EMPTY_MENU_PREFERENCES: MenuPreferences;
+/** 一次原子写入要落的一个字段操作（结构上与 settings 的 path op 相同，保持本模块无依赖）。 */
+export interface MenuPreferenceOp {
+    readonly op: 'set';
+    readonly path: readonly string[];
+    /** 四个字段都是 id 数组，所以这里能给出比 settings 的 `unknown` 更紧的形状。 */
+    readonly value: readonly string[];
+}
+/** 分组结果：侧栏直显项与「更多」项（均按有效顺序，都不含原生的「新会话」）。 */
+export interface MenuLayout {
+    readonly sidebar: readonly MenuFeature[];
+    readonly more: readonly MenuFeature[];
+}
+/** 当前偏好的可编辑快照（设置分区与菜单共用；`status` 决定控件是否可用）。 */
+export interface MenuPreferencesView {
+    readonly status: 'loading' | 'ready' | 'unavailable';
+    readonly writable: boolean;
+    readonly value: MenuPreferences;
+}
+/**
+ * 把 settings 的解析值归一成偏好。
+ *
+ * 宽容优先：settings 文档可能被外部编辑过（旧版本、手工改过的 JSON、缺字段），这里只取认得的形状，
+ * 剩下的当空——菜单是导航入口，宁可退回默认分组，也不能因为偏好坏了就不出菜单。
+ * @param raw - 命名空间解析值（任意形状）。
+ * @returns 归一后的偏好。
+ */
+export declare function normalizeMenuPreferences(raw: unknown): MenuPreferences;
+/**
+ * 某个入口当前被明确标记的去向。
+ *
+ * 同一 id 同时出现在多个数组时按 `hidden` > `more` > `sidebar` 取舍（正常路径不会产生这种数据，
+ * 这是读侧兜底）。
+ * @param preferences - 偏好。
+ * @param id - feature id。
+ * @returns 明确标记时返回该去向，未标记返回 `undefined`。
+ */
+export declare function placementOf(preferences: MenuPreferences, id: string): MenuPlacement | undefined;
+/**
+ * 有效顺序：用户 `order` 里出现且当前在册的 id（按用户次序），再补上其余在册 id（按注册顺序）。
+ * @param features - 当前菜单条目全集（已注册 feature + 非注册表代理项，结构上都是 {@link MenuFeature}）。
+ * @param preferences - 偏好。
+ * @returns 归一后的 id 序列（长度 = 在册条目数）。
+ */
+export declare function orderedFeatureIds(features: readonly MenuFeature[], preferences: MenuPreferences): string[];
+/**
+ * 按偏好把当前注册的 feature 分成「侧栏直显」与「更多」两组。
+ *
+ * 规则（spec §2，实施期不得另立一套）：
+ *  - `hidden` 的既不进侧栏也不进「更多」（**不占名额**：腾出的位置由后面的入口补上）；
+ *  - 明确标记为侧栏的**永远直显**；
+ *  - 明确标记为「更多」的**永远进更多，并且占掉一个侧栏名额**（`budget -= 1`）——
+ *    这条是「用户在设置页把一项挪进『更多』，侧栏就真的少一行」的实现：不占名额的话，
+ *    腾出的位置会被后面的入口立刻补上，行数不变，用户会看到「点了没反应」；
+ *  - 未标记的按有效顺序填空，填到侧栏凑满 `budget` 为止，其余进「更多」。
+ *
+ * 名额（`budget`）只统计**已注册**的标记项：偏好里残留的未知 id（别的设备装的插件）不该
+ * 在本机吃掉名额。
+ * @param features - 当前菜单条目全集。
+ * @param preferences - 偏好。
+ * @returns 两组（各自保持有效顺序）。
+ */
+export declare function menuLayout(features: readonly MenuFeature[], preferences: MenuPreferences): MenuLayout;
+/**
+ * 设置某个入口的去向（设置分区的一次点击）。
+ *
+ * **只动去向数组，不碰 `order`**：`order` 只由显式排序（拖拽 / 键盘上·下移）写。
+ * 早先这里会顺手把 id 追加进 `order`，后果是「点一下『更多』」会把该项钉到有效顺序首位
+ * （`orderedFeatureIds` 先排 `order` 里的 id）——设置页的列表会毫无理由地重排，实机可见。
+ * @param preferences - 当前偏好。
+ * @param id - feature id。
+ * @param placement - 目标去向。
+ * @returns 新偏好；与该去向已经一致时原样返回（调用方据此跳过写盘）。
+ */
+export declare function setMenuPlacement(preferences: MenuPreferences, id: string, placement: MenuPlacement): MenuPreferences;
+/**
+ * 把某个入口移到有效顺序的第 `targetIndex` 位（拖拽落点与键盘上/下移共用）。
+ *
+ * 只写 `order` 一个字段：去向（侧栏/更多/隐藏）是另一维，排序动作不碰它。
+ * @param preferences - 当前偏好。
+ * @param features - 当前注册的 feature。
+ * @param id - 被移动的 feature id。
+ * @param targetIndex - 目标下标（越界自动收敛到两端）。
+ * @returns 新偏好；位置未变时原样返回。
+ */
+export declare function moveMenuEntry(preferences: MenuPreferences, features: readonly MenuFeature[], id: string, targetIndex: number): MenuPreferences;
+/**
+ * 把某个入口放到另一个入口之前/之后（设置页拖拽落点）。
+ *
+ * 与 {@link moveMenuEntry} 的下标语义区分开：拖拽时用户看到的落点是「在谁的前/后」，
+ * 换算成下标要考虑自身被摘掉后的位移，直接用下标会差一位（拖到目标行下方却落在上方）。
+ * @param preferences - 当前偏好。
+ * @param features - 当前注册的 feature。
+ * @param id - 被拖动的 feature id。
+ * @param targetId - 落点所在的 feature id。
+ * @param position - 落在目标之前还是之后。
+ * @returns 新偏好；结果与当前顺序相同时原样返回。
+ */
+export declare function moveMenuEntryNear(preferences: MenuPreferences, features: readonly MenuFeature[], id: string, targetId: string, position: 'before' | 'after'): MenuPreferences;
+/** 两份偏好的四个字段是否逐项相同（数组按内容比较）。 */
+export declare function sameMenuPreferences(left: MenuPreferences, right: MenuPreferences): boolean;
+/**
+ * 两份偏好之间真正变化的字段（只写变化的那几个）。
+ *
+ * 用 `set` 而不是整段替换：设置分区在弹窗里跑，用户改一项就走一次写盘，没必要把另外三个字段一起
+ * 重写（写盘带着 revision 栅栏，写得越少越不容易撞上并发的自我冲突）。
+ * @param current - 写盘前已知的偏好。
+ * @param next - 目标偏好。
+ * @returns 按字段的路径操作；无变化时为空数组。
+ */
+export declare function menuPreferenceOps(current: MenuPreferences, next: MenuPreferences): MenuPreferenceOp[];

package/lib/types/client/menu-section.d.ts

@@ -0,0 +1,5 @@
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { MenuSectionFace } from './menu-store.ts';
+export type MenuSectionProps = PropsRuntime<'settings.section'> & InjectFace<MenuSectionFace>;
+/** 设置页「侧栏菜单」分区。 */
+export declare function MenuSection(props: MenuSectionProps): import("react").JSX.Element;

package/lib/types/client/menu-store.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 「侧栏菜单」设置分区的状态控制器：把 `ai-router` 配置表单里的菜单偏好（`menu` 字段）
+ * 与 feature 注册表合成一份可渲染状态，并把设置页的动作翻译成一次原子写盘。
+ *
+ * rc.2 起 settings 只服务「有 profile entry 的 Config」，纯客户端偏好的 `hiwork-menu`
+ * 命名空间不复存在——偏好并入 `ai-router` entry 的 `menu` volatile 字段，读写都通过与
+ * 网关卡片**同一个** ConfigForm 实例（configForms 按 entry id 共享控制器，见
+ * `src/client/index.ts`），菜单适配器与设置分区因此天然同源。
+ * 本模块不碰 DOM，可单测。
+ *
+ * 写盘纪律（spec §4）：
+ *  - 只在 `status === 'ready' && writable` 时写；否则动作是 no-op（`menu-section` 已禁用控件）。
+ *  - 一次动作 = 一次 `mutate`，只带真正变化的字段（见 `menuPreferenceOps`，路径带 `menu` 前缀）。
+ *  - 目标去向与当前**生效**去向一致时不写盘：用户在设置页点到已经成立的状态不该产生写入，
+ *    否则「点『侧栏』」会给一项已直显的入口加上显式标记，反而挤掉后面某个入口的名额。
+ */
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { AiRouterCardSettings } from './controller.ts';
+import type { FeatureRegistry, MenuFeature } from './feature-registry.ts';
+import { type MenuPlacement, type MenuPreferences } from './menu-preferences.ts';
+/** 设置页一行：一个入口的当前去向与在列表中的位置。 */
+export interface MenuEntryView {
+    /** feature id（拖拽与写盘都按它定位）。 */
+    readonly id: string;
+    /** 菜单文案（已求值；语言变化由订阅方重建）。 */
+    readonly label: string;
+    /** 插件给的图标（内联 SVG 字符串），与侧栏菜单同源。 */
+    readonly icon: string | undefined;
+    /** **生效**去向（未标记的项也给出推导结果，控件据此显示当前状态）。 */
+    readonly placement: MenuPlacement;
+    /** 用户是否明确标记过（UI 用它区分「你选的」与「默认推导」）。 */
+    readonly marked: boolean;
+    /** 在有效顺序中的下标与总数（键盘移动与 aria-label 用）。 */
+    readonly index: number;
+    readonly total: number;
+}
+/** 设置分区的渲染状态。 */
+export interface MenuSectionState {
+    /** 与 settings 作用域同义：`loading` / `ready` / `unavailable`。 */
+    readonly status: 'loading' | 'ready' | 'unavailable';
+    /** 宿主文档是否接受写入（memory 模式恒 false）。 */
+    readonly writable: boolean;
+    /** 按有效顺序的全部入口（不含原生的「新会话」）。 */
+    readonly entries: readonly MenuEntryView[];
+    /** 侧栏当前直显条数上限（= 默认上限 − 已标记「更多」的个数），UI 用来说明规则。 */
+    readonly limit: number;
+    /** 控件不可用时的原因文案；可用时为 undefined。 */
+    readonly reason: string | undefined;
+}
+/** 设置分区注入面（`settings.section#hiwork-menu`）。 */
+export interface MenuSectionFace {
+    hooks: {
+        menu: SnapshotStore<MenuSectionState>;
+    };
+    actions: {
+        /** 设置某个入口的去向。 */
+        setPlacement(id: string, placement: MenuPlacement): Promise<void>;
+        /** 把某个入口上/下移一格（键盘路径）。 */
+        move(id: string, offset: number): Promise<void>;
+        /** 把某个入口拖到另一个入口之前/之后。 */
+        moveNear(id: string, targetId: string, position: 'before' | 'after'): Promise<void>;
+        /** 恢复默认（清掉全部四个字段，回到默认分组）。 */
+        reset(): Promise<void>;
+    };
+}
+/** 侧栏菜单的设置分区控制器。 */
+export declare class MenuStore {
+    private readonly form;
+    private readonly registry;
+    private readonly additionalFeatures?;
+    private readonly store;
+    private readonly unsubscribe;
+    /**
+     * @param form - `ai-router` entry 的配置表单（与网关卡片同一个共享实例，见 `src/client/index.ts`）。
+     * @param registry - feature 注册表（列表内容与顺序的另一个来源）。
+     * @param additionalFeatures - 追加的非注册表条目（官方「插件」代理项；可用性由调用方判断）。
+     *   缺省时列表只有注册表成员——与旧版行为一致。
+     */
+    constructor(form: ConfigForm<AiRouterCardSettings>, registry: FeatureRegistry, additionalFeatures?: (() => readonly MenuFeature[]) | undefined);
+    /** 当前偏好（未就绪 / 值非法时按「从未自定义」处理）。 */
+    preferences(): MenuPreferences;
+    /** 订阅偏好变化（菜单适配器用；与 `preferences()` 同源）。 */
+    subscribePreferences(listener: () => void): () => void;
+    /** 菜单条目全集（注册表 + 追加的代理项），与侧栏适配器的来源同构。 */
+    private menuFeatures;
+    /** 当前渲染状态。 */
+    view(): MenuSectionState;
+    /** 清掉在这份 store 上的全部订阅（插件卸载时调用）。 */
+    dispose(): void;
+    /** 立即重算渲染状态（追加条目的可用性变化等非表单/注册表来源的变化走这里）。 */
+    refresh(): void;
+    /** 注入面：设置分区组件消费。 */
+    inject(): MenuSectionFace;
+    private setPlacement;
+    private move;
+    private moveNear;
+    private reset;
+    /** 未标记项的生效去向已由 `view()` 给出，这里不再另算一份。 */
+    private write;
+}

package/lib/types/client/styles.d.ts

@@ -130,6 +130,22 @@ export declare const brandCss: string;
  * 由 client 入口 apply() 注入一次（带 id 防重）。
  */
 export declare const interactionCss: string;
+/**
+ * 生图能力的样式（会话内工具卡片 + 「我的图片」画廊页），随本插件一起分发。
+ *
+ * 类名统一 `hiwork-image-*` / `hiwork-images-*` 前缀，颜色全部走 dsh 主题变量
+ * （亮暗自动切换、与设置页分区同一套 token）；只有「放大遮罩」是自带的半透明黑
+ * ——那是浮层，与宿主内部结构无关。
+ *
+ * 注入走 `image-styles.ts` 的 `ensureImagesStyle`，**必须**经 {@link ownStyleTag}
+ * 打归属标记（见下方事故记录）：裸注入会被随后装载的插件认领并连带删除。
+ */
+export declare const imageCardsCss: string;
+/**
+ * 「我的图片」画廊页（中央 feature `images`）的样式：左列表 + 右预览。
+ * 左栏 grid 固定 240–320px、右栏自适应；两栏各自滚动，页面本身不滚。
+ */
+export declare const imagesPageCss: string;
 /**
  * 手写注入的 <style> 必须带 DSH 的归属标记（`data-plugin`）。
  *

package/lib/types/client/types.d.ts

@@ -32,6 +32,15 @@ export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHAB
  * 消费方据此显示「本部署尚未启用工作台」而不是报错。别顺手把两边对齐。
  */
  | 'WORKBENCH_DISABLED'
+/**
+ * 本部署未配置知识库：取配置或取令牌时 503。
+ *
+ * 语义与 `OFFICE_NOT_CONFIGURED` 同族：**部署状态**，不是故障。消费方（hiwork-knowledge）
+ * 据此给出「管理员还没开启知识库」并把状态判成终局——不排重试、不把员工指向「范围未分配」。
+ * 之前 503 一律收敛成 `GATEWAY_UNREACHABLE`，插件把「管理员没配签名私钥」读成「服务暂时不可用」
+ * 并白打约 10 分钟重试，员工看到的还是「管理员尚未分配知识库访问范围」，指向错误的部门。
+ */
+ | 'KNOWLEDGE_NOT_CONFIGURED'
 /** 本部署未启用语音识别（管理员把开关关了）：识别时 503（或 503 无 body code）。 */
  | 'VOICE_DISABLED'
 /** 本部署未配置语音识别上游服务（网关侧没有可用 ASR 配置）：识别时 503。 */

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>;