hiwork-core 0.0.30 → 0.0.37

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

@@ -0,0 +1,127 @@
+/**
+ * 「我的图片」画廊页的客户端取数层：经 `/hiwork-image` loopback RPC 读**既有**的网关
+ * 员工自助端点（`/api/me/images`、`/api/me/images/:id/file`），做信封拆解与形状归一。
+ *
+ * 铁律（与 `usage-data.ts` 同一套）：
+ *  - 客户端**不持有**会话 cookie，也**不直接 fetch 网关**——一切经 `connection.rpc`；
+ *  - **不缓存图片字节**：`fetch` 每次现取、用完即弃（不落 DSH 附件存储、不进会话日志）；
+ *    `save` 只在用户显式点击时写盘（写盘在 Host 半边）；
+ *  - 失败绝**不**降级成空数据：错误带稳定 code，视图把 message 直接显示在行内。
+ *
+ * client bundle 纯度：本文件不 import 任何 `@deepseek-ai/*` 运行时值，也不 import
+ * Host 代码（`ImageRow` 等按结构重声明，字段名与网关 JSON / Host 契约一致）。
+ */
+/**
+ * RPC 频道；必须与 Host `src/image-rpc.ts` 的频道常量一致（冻结契约 `/hiwork-image`）。
+ * 由本文件与 `tests/image-gallery.spec.tsx` 的字面量断言锁定。
+ */
+export declare const IMAGE_CHANNEL = "/hiwork-image";
+/**
+ * 端点白名单（**冻结契约**，与 Host 的 `IMAGE_RPC_ENDPOINTS` 逐字同序）。
+ *
+ * `status` / `generate` 供会话内工具链路（那个链路不经过本文件），画廊页只用后三个：
+ * `list` / `fetch` / `save`。这里整表列出是为了让「一个能力一个频道、端点表只有一处」
+ * 这条约定在客户端也看得见。
+ */
+export declare const IMAGE_RPC_ENDPOINTS: readonly ["status", "generate", "list", "fetch", "save"];
+/** 端点名。 */
+export type ImageEndpoint = (typeof IMAGE_RPC_ENDPOINTS)[number];
+/** 画廊页默认分页（spec §6.5：默认 20）。 */
+export declare const IMAGE_LIST_PAGE_SIZE = 20;
+/** 分页上限（与 Host 侧一致；再大也只是白拉流量）。 */
+export declare const IMAGE_LIST_MAX_PAGE_SIZE = 100;
+/** 拿不到可展示原因时的兜底文案。 */
+export declare const IMAGE_DATA_ERROR_TEXT = "\u56FE\u7247\u8BB0\u5F55\u6682\u65F6\u65E0\u6CD5\u83B7\u53D6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/**
+ * 一条历史记录（**生产形状**：网关 `/api/me/images` 的 item 在补了 `size` 投影之后
+ * 的字段集；`tests/image-gallery.spec.tsx` 的夹具必须按这个形状构造）。
+ */
+export interface ImageRow {
+    readonly id: number;
+    readonly prompt: string;
+    readonly revisedPrompt?: string | undefined;
+    readonly model: string;
+    readonly size: string;
+    readonly format: string;
+    readonly mimeType: string;
+    readonly byteSize: number;
+    readonly generationMs: number;
+    /** RFC3339（网关 `created_at`）。 */
+    readonly createdAt: string;
+}
+/** `list` 端点出参。 */
+export interface ImageListPage {
+    readonly items: readonly ImageRow[];
+    readonly total: number;
+    readonly page: number;
+    readonly pageSize: number;
+}
+/** `fetch` 端点出参（图片本体，base64 无 data URL 前缀）。 */
+export interface ImageBytes {
+    readonly dataBase64: string;
+    readonly mimeType: string;
+    readonly byteSize: number;
+}
+/** 宿主 loopback RPC 调用面（结构兼容 `ctx.connection.rpc`）。 */
+export interface ImageRpcPort {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/** 画廊页消费的最小取数面（便于测试注入假实现）。 */
+export interface ImageDataSource {
+    list(page: number, pageSize?: number): Promise<ImageListPage>;
+    fetch(id: number): Promise<ImageBytes>;
+    save(id: number, workspaceId?: string): Promise<{
+        path: string;
+    }>;
+}
+/** 带稳定 code 的取数错误（message 已由 Host 消毒，可直接展示）。 */
+export declare class ImageRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 解开 DSH Connection 的结果信封（与 `usage-data.ts` 的 `unwrapUsageResult` 同语义）。
+ * 宿主返回 `{ok:true,value}` / `{ok:false,error:{code,message}}`；形状不合法时抛通用失败，
+ * 绝不把未知结构当数据渲染。
+ */
+export declare function unwrapImageResult<T>(value: unknown): T;
+/** 任意异常 → 可展示的 `{code, message}`（传输层异常不暴露原始 message）。 */
+export declare function imageErrorOf(error: unknown): {
+    code: string;
+    message: string;
+};
+/**
+ * 归一 `list` 的返回：字段逐个显式取（**不**把未知结构当数据）。
+ * `content` 的形状由网关决定，这里只保证「视图拿到的一定是生产形状」。
+ */
+export declare function normalizeImageListPage(value: unknown, fallbackPage: number, fallbackPageSize: number): ImageListPage;
+/** 归一 `fetch` 的返回：base64 为空视为失败（空图不是可展示的结果）。 */
+export declare function normalizeImageBytes(value: unknown): ImageBytes;
+/**
+ * `/hiwork-image` 的三个只读/落盘端点（画廊页用）。**无缓存**：每次调用现取。
+ */
+export declare class ImageGallerySource implements ImageDataSource {
+    private readonly rpc;
+    constructor(rpc: ImageRpcPort);
+    /** 分页拉取历史记录（`page` 从 1 开始；`pageSize` 上限 100）。 */
+    list(page?: number, pageSize?: number): Promise<ImageListPage>;
+    /** 取一张图的本体（**点哪张拉哪张**；超 20MiB 由 Host 回 `IMAGE_TOO_LARGE`）。 */
+    fetch(id: number): Promise<ImageBytes>;
+    /** 把一张图存到工作区（缺省落默认工作区，由 Host 决定）。 */
+    save(id: number, workspaceId?: string): Promise<{
+        path: string;
+    }>;
+}
+/**
+ * 图片本体 → data URL（预览用）。**不写盘、不指向本地文件**：字节是本次 `fetch` 的结果，
+ * `<img src>` 里只能是它自己。
+ * @param bytes - `fetch` 的返回。
+ * @returns `data:<mime>;base64,<本体>`。
+ */
+export declare function imageDataUrl(bytes: ImageBytes): string;
+/** 体积展示（1 位小数）；缺失/非法返回 `—` 之外的空串由调用方决定。 */
+export declare function formatImageBytes(bytes: number | undefined): string;
+/** 列表行的提示词摘要（超长截断；空提示词给「（无提示词）」）。 */
+export declare function imagePromptSummary(prompt: string, limit?: number): string;
+/** 记录时间：非法时间串返回空串（视图渲染 `—`）。 */
+export declare function imageTimeLabel(createdAt: string): string;

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。 */