hiwork-core 0.0.11 → 0.0.17

package/lib/types/plugin-updates-rpc.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `/hiwork-plugin-updates` loopback RPC 的 Host 实现：把**桌面端**的 `desktopPlugins`
+ * （受管插件清单的只读面 + 唯一的回收入口）搬到渲染端够得着的地方。
+ *
+ * 为什么必须有这条 RPC（spec §4.5 的「数据来源」一段）：`desktopPlugins` 是桌面端的
+ * `desktop-bridge.mts` 用 `ctx.provide('desktopPlugins', …)` 提供到 **DSH host** ctx 上的，
+ * 而 hiwork-core 的客户端跑在 **renderer**——两个进程。客户端现有的全部数据层（usage /
+ * session-cost / daily / managed-mcp / managed-skills / managed-workbench / app-version）
+ * 无一例外都经 `ctx.get('connection').rpc` 走 `/hiwork-*` loopback RPC，**没有任何
+ * client→host 的服务直连通道**。而「重启并更新」是个**点击**，它发生在客户端。所以取数与
+ * 触发都得过这条 RPC。
+ *
+ * 骨架照 `src/workbench-bridge.ts`（同 `src/managed-skills.ts` / `src/app-version-rpc.ts`）：
+ * 导出频道名 + 端点白名单（`as const`）+ 结构化 deps 端口（**不 import cordis 运行时**，
+ * 便于单测直接伪造）+ 一个 `register…Rpc(...)` 返回 disposer。
+ *
+ * 三条本频道特有的纪律：
+ *  - ⚠️ **`desktopPlugins` 是可选的**（不变量：依赖必须是可选的）。老桌面端上没有它 —— 那正是
+ *    「新 core + 老桌面端」这条共存路径。拿不到时 `snapshot` 回**成功信封 + `null`**
+ *    （「不可用」**不是错误**，与 `app-version-rpc.ts` 的「桌面端没推过不是错误」同一条口径），
+ *    客户端据此**不渲染任何东西**。抛错会把共存路径变成一条报错日志。
+ *  - ⚠️ **只搬运 `packages` / `revision` / `fetchedAt` 这三样**，**不搬 `held`**（plan T11
+ *    Step 0）。它们三个是真的：落在 `.dsh-pending-updates.json` 里，跨进程可用。`held` /
+ *    `from` / `displayName` 在生产路径上是空的——根因是 `desktop-bridge.mts` 调
+ *    `createDesktopHostServices()` 时**没传 `pluginManifest`**，于是 `desktop-host.ts` 里那条
+ *    `memory = options.pluginManifest?.current()` 恒 `undefined`、`held` 退到 `?? []`。
+ *    那条通道要修得补一条**主进程 → 子进程**的路（新 IPC 信封或 sidecar 文件），而**本 RPC 是
+ *    client→host 的**，它跨的是「renderer↔DSH」，**跨不过「DSH↔主进程」这一层**。所以别「顺手把
+ *    `held` 也传过去」——传过去也永远是空的，只会让下一个读这段的人以为服务端没下发降级项。
+ *  - ⚠️ **`apply` 不是「更新成功」的回执**：它只把触发递下去（`desktopPlugins.applyNow()` →
+ *    `APPLY_PLUGIN_UPDATES_IPC` → 主进程的 `recycleDshForPluginUpdate()`），重启由**主进程**执行、
+ *    客户端那一刻就没了。按钮语义是「已请求重启」。所以返回值是 `{ requested }`，
+ *    **不是** `{ applied: true }`。
+ *
+ * 回收红线（spec §6.1 不变量②）：本文件的 `apply` 是**唯一**允许触发回收的新入口，且只能由
+ * 用户点击到达（客户端只在「重启并更新」按钮的 onClick 里调它）。`snapshot` **绝不触碰**
+ * `applyNow()`——清单拉取、轮询、启动流程都不许触发回收。
+ */
+/** RPC 频道；必须与 client 半边 `src/client/plugin-updates.ts` 的 `PLUGIN_UPDATES_CHANNEL` 一致（由测试锁定）。 */
+export declare const PLUGIN_UPDATES_RPC_CHANNEL = "/hiwork-plugin-updates";
+/**
+ * 端点白名单：只有两个。
+ *
+ * `snapshot` 是「现在有没有待生效的更新」（桌面端读 pending 文件，**不拉清单、不写文件、
+ * 不触发回收**），`apply` 是「现在就去重启并应用」——它只在用户点击时被调用。
+ * 白名单是客户端可用的能力边界，多一项就等于先发布了一个没有实现的承诺。
+ */
+export declare const PLUGIN_UPDATES_RPC_ENDPOINTS: readonly ["snapshot", "apply"];
+export type PluginUpdatesRpcEndpoint = (typeof PLUGIN_UPDATES_RPC_ENDPOINTS)[number];
+/**
+ * 一条待生效的更新（**冻结契约**：与桌面端 `ManagedPluginUpdate` 逐字同形）。
+ *
+ * ⚠️ `from` / `displayName` **不得用于渲染任何东西**（spec §4.3 的 ⚠️）：生产路径上 `from` 恒空串、
+ * `displayName` 退化成包名（`pendingUpdatesFromDisk()`）。保留它们是为了贴合桌面端契约，
+ * 不是因为它们可用——界面只认 `packages.length > 0`。
+ */
+export interface PendingPluginUpdate {
+    packageName: string;
+    displayName: string;
+    from: string;
+    to: string;
+}
+/**
+ * 一次待更新快照。
+ *
+ * `revision` 供提示条去重「关过一次的提示」（spec §4.5）：**服务端没给就是 `null`**，
+ * 客户端把 `null` 当作一个独立的桶（关过它就不再提示，换了值就重新提示）。
+ *
+ * **本对象里没有 `held`**：见文件头第二条纪律。
+ */
+export interface PluginUpdatesSnapshot {
+    packages: PendingPluginUpdate[];
+    /** 桌面端最近一次清单的时刻（epoch ms）；拿不到就是 0。 */
+    fetchedAt: number;
+    /** 清单级版本号；服务端没给就是 `null`。 */
+    revision: number | null;
+}
+/** `snapshot` 端点的响应：`null` = 不可用（老桌面端没有 `desktopPlugins`）。**不是错误**。 */
+export type PluginUpdatesSnapshotValue = PluginUpdatesSnapshot | null;
+/** `apply` 端点的响应：`requested` = 触发是否递下去了（**不是**「更新是否成功」）。 */
+export interface PluginUpdatesApplyValue {
+    requested: boolean;
+}
+/** 客户端可安全展示的失败。 */
+export interface PluginUpdatesFailure {
+    code: string;
+    message: string;
+    /** DSH Connection 信封要求 `details` 是对象；协议层没有额外细节时补空对象。 */
+    details: object;
+}
+/** 端点结果信封（与 DSH Connection 的 `ConnectionRpcResult` 同形）。 */
+export type PluginUpdatesRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: PluginUpdatesFailure;
+};
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export declare class PluginUpdatesRequestError extends Error {
+    readonly code: 'bad-request';
+    constructor(code: 'bad-request', message: string);
+}
+/** Host 侧 RPC 依赖的最小上下文（结构兼容 cordis Context，便于单测伪造）。 */
+export interface PluginUpdatesRpcConnection {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+            authority: 'loopback';
+        }): () => Promise<void> | void;
+    };
+}
+export interface PluginUpdatesRpcContext {
+    readonly connection: PluginUpdatesRpcConnection;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * 桌面端 `desktopPlugins` 服务在本频道里真正用到的那两个成员（结构兼容，便于单测伪造）。
+ *
+ * 返回值一律按 `unknown` 收：它来自**另一个包**在运行时 provide 的对象，本文件不假设它的形状
+ * ——形状由 {@link toSnapshot} 兜底（这正是「不变量：拿不到就当不可用」在取值一侧的落实）。
+ */
+export interface DesktopPluginsPort {
+    /** 待生效的更新；没有待生效项（含只有 `held`）时返回 `undefined`。 */
+    pending(): Promise<unknown>;
+    /** 等价于用户点插件市场的「更新」：立刻回收。**只能由用户点击触发**。 */
+    applyNow(): Promise<unknown>;
+}
+/** Host 侧取数依赖：桌面端的 `desktopPlugins` 服务（老桌面端上没有它）。 */
+export interface PluginUpdatesRpcDeps {
+    /**
+     * 现取 `ctx.get('desktopPlugins')`；拿不到返回 `undefined`（老桌面端）。
+     *
+     * 做成**函数**而不是值：cordis 的服务可能在插件生命周期中途才被 provide / 被撤下，
+     * 一次性取到的值会把「还没 provide」误判成「永远没有」。
+     */
+    desktopPlugins(): DesktopPluginsPort | undefined;
+    /** Host 日志出口（只记事件与错误类型）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 通用失败文案：不暴露任何桌面端细节。 */
+export declare const PLUGIN_UPDATES_GENERIC_FAILURE_MESSAGE = "\u63D2\u4EF6\u66F4\u65B0\u72B6\u6001\u6682\u65F6\u65E0\u6CD5\u83B7\u53D6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/** 是否为白名单端点。 */
+export declare function isPluginUpdatesRpcEndpoint(endpoint: string): endpoint is PluginUpdatesRpcEndpoint;
+/**
+ * payload 校验：两个端点都**只放行空对象**（本频道没有任何入参）。
+ *
+ * 与 workbench / app-version 的空入参分支逐字同款：出现任何字段都是客户端实现缺陷，直接
+ * `bad-request`——一个 `{ force: true }` 被静默忽略，会让调用方以为「强制重启」生效了。
+ */
+export declare function parsePluginUpdatesPayload(endpoint: PluginUpdatesRpcEndpoint, raw: unknown): Record<string, never>;
+/**
+ * 把 `desktopPlugins.pending()` 的返回值规范化成 {@link PluginUpdatesSnapshot}。
+ *
+ * `undefined` / 非对象 → `undefined`（= 没有待生效项，界面不渲染）。**只有降级项（`held` 非空、
+ * `packages` 为空）时同样落成空 `packages`**，由客户端据此不渲染——回退对员工是要解释的事，
+ * 不该混在「更新已就绪」里（spec §4.5）。`held` 本身不搬运，理由见文件头。
+ */
+export declare function toSnapshot(raw: unknown): PluginUpdatesSnapshot | undefined;
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export declare function handlePluginUpdatesEndpoint(endpoint: string, rawPayload: unknown, deps: PluginUpdatesRpcDeps, signal?: AbortSignal): Promise<PluginUpdatesRpcResult<unknown>>;
+/**
+ * 注册 `/hiwork-plugin-updates` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export declare function registerPluginUpdatesRpc(ctx: PluginUpdatesRpcContext, deps: PluginUpdatesRpcDeps): () => Promise<void>;

package/lib/types/workbench-bridge.d.ts

@@ -0,0 +1,259 @@
+/**
+ * `/hiwork-workbench` loopback RPC 的 Host 实现：管理员登记并分配给当前账号的**工作台应用清单**。
+ *
+ * 契约见 spec `docs/superpowers/specs/2026-09-17-hiwork-workbench-design.md` §4.1（清单 JSON）与
+ * §4.5（Host 面）。本文件是 `src/managed-skills.ts` 同一副骨架的**第三条链**，也是三条里最短的一条：
+ * 工作台 M0 只做「看得到货架」，因此
+ *  - 端点只有两个：`snapshot`（你现在有什么）/ `refresh`（现在去拉一次）。**没有 `package` 那一档**
+ *    （清单里没有大字节，一条 GET 全量下发）；
+ *  - **M1 的四个端点（`submit` / `poll` / `cancel` / `materialize`）刻意不在本文件里**：它们要动
+ *    工作区落盘与上传字节，属于任务运行时的范围（plan T5 的「M0 的边界」）。别为了「一次写完」
+ *    顺手加上——那会把 M0 的验收面撑成 M1。
+ *
+ * 与 MCP / 技能逐字同款的三条铁律：
+ *  - **网关会话 cookie 绝不离开 Host**：cookie 只在 `resolveSession()` 内部出现，客户端拿到的是
+ *    清单（经 loopback RPC 过去，里面没有任何令牌）；
+ *  - **拉清单失败绝不清空上一次成功的清单**：失败返回「保留旧值 + 标注失败原因」，于是断网时
+ *    界面还能显示上次成功缓存 + 「可能不是最新」（spec §10 的离线那一行）；
+ *  - **`snapshot` 可能陈旧、只有 `refresh` 的成功返回值可作真相**：下架 / 撤销分配后卡片消失
+ *    只能基于 `refresh` 的返回值判定（spec §4.5）。
+ *
+ * 与技能清单不同的一处：**远端会回 404**（网关没配置工作台时那条路由压根没注册，spec §10），
+ * 它被映射成 `WORKBENCH_DISABLED` 而非「网关不可达」——这是可展示的功能状态，不是故障。
+ *
+ * 演进纪律（spec §4.1）：**未知字段忽略；未知 `executor.kind` / `inputs[].type` 原样透传**。
+ * 本文件的规范化只做「形状兜底 + 已知字段改名（`icon` → `iconUrl`）」，绝不按白名单过滤语义
+ * ——老客户端遇到新 kind 由客户端置灰 + 提示升级（spec D2），Host 不替它做丢弃决策。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link WorkbenchRpcDeps} 端口，便于单测直接伪造。
+ */
+import { type GatewayWorkbenchAppsView } from './ai-router-client.ts';
+/** RPC 频道；必须与 client 半边 `src/client/managed-workbench.ts` 的 `MANAGED_WORKBENCH_CHANNEL` 一致（由测试锁定）。 */
+export declare const WORKBENCH_RPC_CHANNEL = "/hiwork-workbench";
+/**
+ * 端点白名单：M0 只有「拿清单」这一件事的两个入口。
+ *
+ * `snapshot` 是「你现在有什么」（有缓存就直接给，冷启动才拉一次），`refresh` 是「现在去拉一次」。
+ * 分两个端点的理由与 MCP / 技能同款：同步策略（启动 / 超 TTL / 手动刷新）由消费方自己定，
+ * Host 不该替它决定什么时候必须联网。
+ *
+ * ⚠️ `submit` / `poll` / `cancel` / `materialize` 属 M1（spec §4.5），**不许提前登记**：
+ * 白名单是客户端可用的能力边界，多一项就等于先发布了一个没有实现的承诺。
+ */
+export declare const WORKBENCH_RPC_ENDPOINTS: readonly ["snapshot", "refresh"];
+export type WorkbenchRpcEndpoint = (typeof WORKBENCH_RPC_ENDPOINTS)[number];
+/**
+ * Host 侧后台预热间隔：30 分钟（与 MCP / 技能两份同量级）。
+ * 它**不是**权威节奏——只为让客户端首次 `snapshot` 不必等一次网络往返。
+ */
+export declare const WORKBENCH_REFRESH_INTERVAL_MS: number;
+/**
+ * 清单里的一条应用（**冻结契约**，字段名与 spec §4.1 一一对应，改名即破坏跨仓契约）。
+ *
+ * 两处规范化的说明：
+ *  - `iconUrl` 是契约面的名字，网关线名是 `icon`（§4.1 的 JSON）——改名发生在 Host 这一层，
+ *    所以客户端只需要认 `iconUrl` 一个名字；
+ *  - `executor` 与 `inputs[i]` / `outputs[i]` 都带 `& Record<string, unknown>`：**未知键原样透传**。
+ *    `executor.kind` 是开放集合（`link` / `http-task`，二期 `session-task` / `embedded`），
+ *    客户端认不认识由它自己决定，Host 只保证「存在且是字符串」。
+ */
+export interface WorkbenchAppView {
+    code: string;
+    displayName: string;
+    summary: string;
+    iconUrl?: string;
+    category: {
+        code: string;
+        name: string;
+    };
+    tags: string[];
+    featured: boolean;
+    revision: number;
+    /** 未知 kind / 未知键必须原样透传（spec §4.1 的演进纪律）。 */
+    executor: {
+        kind: string;
+        mode?: string;
+    } & Record<string, unknown>;
+    /** `type` 一期只有 `file` / `text` / `number` / `enum` / `boolean`；未知 type 同样透传。 */
+    inputs: ReadonlyArray<{
+        key: string;
+        type: string;
+        label: string;
+        required: boolean;
+    } & Record<string, unknown>>;
+    outputs: ReadonlyArray<{
+        key: string;
+        type: string;
+    } & Record<string, unknown>>;
+    /** `[]` | `['external']` | `['metered']`。 */
+    effects: string[];
+}
+/**
+ * 一份清单快照。
+ *
+ * `stale` 为 true 表示「这是上一次成功的结果，最近一次拉取失败了」——调用方可以照常展示
+ * （离线态），但**不得**用它做出「这个应用已被下架」的判断（那条路只允许走 `refresh` 的成功返回值）。
+ */
+export interface WorkbenchCatalogSnapshot {
+    /** 清单级序号（服务端任何影响清单的写入都 +1），消费方先比它再决定要不要深比对。 */
+    revision: number;
+    /** 本次成功拉取的时刻（ISO 8601）。 */
+    fetchedAt: string;
+    apps: WorkbenchAppView[];
+    stale: boolean;
+    /** 最近一次拉取失败的原因（成功时缺省）。 */
+    lastError?: WorkbenchFailure;
+}
+/** 客户端可安全展示的失败。 */
+export interface WorkbenchFailure {
+    code: string;
+    message: string;
+    /** DSH Connection 信封要求 `details` 是对象；协议层没有额外细节时补空对象。 */
+    details: object;
+}
+/** 端点结果信封（与 DSH Connection 的 `ConnectionRpcResult` 同形）。 */
+export type WorkbenchRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: WorkbenchFailure;
+};
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export declare class WorkbenchRequestError extends Error {
+    readonly code: 'bad-request';
+    constructor(code: 'bad-request', message: string);
+}
+/** Host 侧 RPC 依赖的最小上下文（结构兼容 cordis Context，便于单测伪造）。 */
+export interface WorkbenchRpcConnection {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+            authority: 'loopback';
+        }): () => Promise<void> | void;
+    };
+}
+export interface WorkbenchRpcContext {
+    readonly connection: WorkbenchRpcConnection;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/** 网关客户端的工作台子集：只声明本频道真正调用的方法（结构兼容 `GatewayClient`）。 */
+export interface WorkbenchGatewayPort {
+    getMyWorkbenchApps(sessionCookie: string): Promise<GatewayWorkbenchAppsView>;
+}
+/** Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关客户端。 */
+export interface WorkbenchRpcDeps {
+    /**
+     * 解析网关会话 cookie（`AI_ROUTER_SESSION`）。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用，绝不出现在 RPC 响应里。**
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关客户端；baseURL 未配置时返回 undefined。 */
+    gateway(): WorkbenchGatewayPort | undefined;
+    /** Host 日志出口（只记事件与错误类型，不记会话值）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 通用失败文案：不暴露任何网关细节。 */
+export declare const WORKBENCH_GENERIC_FAILURE_MESSAGE = "\u5DE5\u4F5C\u53F0\u5E94\u7528\u6E05\u5355\u6682\u65F6\u65E0\u6CD5\u83B7\u53D6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/** 未登录 / 会话失效的统一文案（与用量、每日一句、MCP / 技能清单几个频道同口径）。 */
+export declare const WORKBENCH_SESSION_EXPIRED_MESSAGE = "\u767B\u5F55\u72B6\u6001\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55";
+/** 本部署未启用工作台（网关 404）的文案：spec §10 的降级矩阵里这一行要给人可行动的提示。 */
+export declare const WORKBENCH_DISABLED_MESSAGE = "\u672C\u90E8\u7F72\u672A\u542F\u7528\u5DE5\u4F5C\u53F0\uFF0C\u8BF7\u8054\u7CFB\u7BA1\u7406\u5458";
+/** 工作台未启用时的稳定 code（与网关客户端的映射一致，消费方按它走降级文案）。 */
+export declare const WORKBENCH_DISABLED_CODE = "WORKBENCH_DISABLED";
+/**
+ * 网关 message 消毒（与 `usage-rpc.ts` 的 `displayGatewayMessage` 同实现，MCP / 技能那两半逐字同款）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的中文业务文案）
+ * 原样保留。code 不受影响，始终原样透传。
+ */
+export declare function displayWorkbenchMessage(code: string, message: unknown): string;
+/**
+ * payload 校验：两个端点都**只放行空对象**（M0 没有任何入参）。
+ *
+ * 与技能清单的空入参分支逐字同款：出现任何字段都是客户端实现缺陷，直接 `bad-request`
+ * ——一个 `{ code: 'pdf-to-word' }` 被静默忽略，会让调用方以为「按 code 过滤」生效了。
+ */
+export declare function parseWorkbenchPayload(endpoint: WorkbenchRpcEndpoint, raw: unknown): Record<string, never>;
+/** 是否为白名单端点。 */
+export declare function isWorkbenchRpcEndpoint(endpoint: string): endpoint is WorkbenchRpcEndpoint;
+/**
+ * 清单缓存：**只有成功响应才覆写**，失败只记原因；且缓存**按会话绑定**（见 {@link WorkbenchStore.bindSession}）。
+ *
+ * 「成功」的判据里含**响应形状**：200 但响应不是「带数组 `apps` 的对象」按**取数失败**处理
+ * （见 {@link WorkbenchStore.fetchOnce}）——那种响应是中间层给的，不是服务端说「你没有应用」，
+ * 读成空清单会让货架在反代维护页面前清空，用户以为管理员把应用全撤了（spec §10 的离线态本意
+ * 是「显示上次成功缓存 + 可能不是最新」，不是「什么都不显示」）。
+ *
+ * 进程内的（不落盘）是有意的：清单是「服务端此刻认什么」的投影，跨重启的旧清单没有价值
+ * ——重启后消费方会立刻 `warm()` 一次，拿到新的比拿到旧的更安全。
+ */
+export declare class WorkbenchStore {
+    private readonly deps;
+    private readonly now;
+    private cached;
+    private lastError;
+    /** 产生 `cached` 的那个会话 cookie（只在内存里）。会话绑定的全部依据就是它。 */
+    private cachedSession;
+    /**
+     * 在飞请求连同它所用的会话一起记账：并发合并**只允许发生在同一会话内**。
+     * 合并跨会话等于把 A 那次拉取的结果交给 B（登出 / 换账号后货架会显示上一个人的应用）。
+     */
+    private inFlight;
+    constructor(deps: WorkbenchRpcDeps, now?: () => number);
+    /**
+     * 当前缓存（同步读，不发请求）。从没成功过返回 undefined；
+     * 最近一次失败会以 `stale + lastError` 标注在上一次成功的结果上。
+     *
+     * ⚠️ **本方法不做会话绑定**——它是 spec §4.5 冻结的同步读，而当前会话只能异步解析（见
+     * {@link peekForCurrentSession}），同步函数里根本判不了「这份缓存还算不算我的」。
+     * 所以模块内唯一的正确用法是：先 `await store.peekForCurrentSession()`，再（或由它内部）`peek()`。
+     * 直接调 `peek()` 只适合诊断与测试断言内存状态。
+     */
+    peek(): WorkbenchCatalogSnapshot | undefined;
+    /**
+     * 「当前会话下的缓存」= 解析当前会话 → 剪枝 → {@link peek}。
+     *
+     * 与 `src/managed-skills.ts` 的同名方法逐字同款：`peek()` 是 spec §4.5 冻结的**同步**接口，而
+     * 「当前是谁」只有 `deps.resolveSession()` 异步拿得到，于是分工只能是「async 的一侧先绑会话，
+     * sync 的 `peek()` 再读」。端点实现必须走它、不许绕过。
+     */
+    peekForCurrentSession(): Promise<WorkbenchCatalogSnapshot | undefined>;
+    /**
+     * 会话绑定：缓存只属于产生它的那个会话；当前会话不是它（含**当前没有会话**）→ 立刻丢弃。
+     *
+     * 与技能清单那半逐字同款（那里写了为什么**不许**为了「两半对齐」改回 MCP 的写法）：
+     * 绑会话**自带**——不依赖任何调用方、不依赖谁记得清缓存，登出后（当前会话为空）与换账号后
+     * 都不会再吐出上一个人的清单。`clear()` 也没有任何调用方（端点白名单够不到 Host 内存），
+     * 把安全不变量挂在一个没人调的钩子上正是已经失败过一次的做法。
+     *
+     * 它也**不**触碰「失败不覆写缓存」那条铁律：剪枝的触发条件是**会话变了**，不是「这一次拉取
+     * 失败了」。失败路径仍然原样保留本会话上一次成功的清单（`stale + lastError`）。
+     */
+    private bindSession;
+    /**
+     * 去网关拉一次清单并更新缓存。失败时抛异常，且**本会话的缓存原样保留**。
+     *
+     * 并发调用合并成一次请求：后台预热与消费方的手动刷新撞在一起时不必打两遍网关。
+     * 合并**只在同一会话内**——两个会话合并到一起，就等于把 A 的结果发给 B。
+     */
+    load(): Promise<WorkbenchCatalogSnapshot>;
+    /**
+     * 清空内存清单（登出 / 换账号调用）。
+     *
+     * ⚠️ **当前没有任何调用方**：这是 spec §4.5 冻结要求提供的接口（与技能清单那半同款），而它的
+     * 用途已经被**会话绑定**覆盖——缓存按会话剪枝，登出 / 换账号后再也吐不出上一个人的清单。
+     * 保留它是为了不改冻结接口；真要删得先改 spec §4.5。冻结接口里的成员不要悄悄删掉。
+     */
+    clear(): void;
+    private fetchOnce;
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export declare function handleWorkbenchEndpoint(endpoint: string, rawPayload: unknown, deps: WorkbenchRpcDeps, store: WorkbenchStore, signal?: AbortSignal): Promise<WorkbenchRpcResult<unknown>>;
+/**
+ * 注册 `/hiwork-workbench` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export declare function registerWorkbenchRpc(ctx: WorkbenchRpcContext, deps: WorkbenchRpcDeps, store: WorkbenchStore): () => Promise<void>;