hiwork-core 0.0.11 → 0.0.17

package/lib/office-relay.js

@@ -0,0 +1,113 @@
+/**
+ * 文档中继的 host 侧服务 `hiworkOfficeRelay`（设计见 ai-gateway 的
+ * `docs/superpowers/specs/2026-09-16-office-document-relay-design.md` §5）。
+ *
+ * 为什么需要它：在线编辑要求 Document Server 主动回连文档 URL；用户走 VPN / DS 在云上时
+ * 这条路径不通（2026-09-16 现场：DS 拉 http://192.168.16.105:54426 超时）。中继把文档
+ * 暂存到 DS 能访问的服务器侧，桌面端只做出站调用——**用户侧不再需要任何入向可达性**。
+ *
+ * 与 `office-credentials.ts` 同一套形态：
+ *  - **网关会话 cookie 绝不离开 Host**：只在 resolveSession() 内部出现；
+ *  - 失败不抛异常，返回稳定 `{ ok, code, message }`（message 已消毒，可直接展示）；
+ *  - 服务名 `hiworkOfficeRelay`，经 ctx.provide 发布；hiwork-office 用 ctx.get 探测，
+ *    老 core 上没有它 → 插件回落本机模式。
+ *
+ * 本模块不 import cordis 运行时：provide 走结构化的 {@link OfficeRelayContext} 端口。
+ */
+import { GatewayError } from "./ai-router-client.js";
+/** cordis 服务名（hiwork-office 的 Host 半边按此名探测）。 */
+export const OFFICE_RELAY_SERVICE = 'hiworkOfficeRelay';
+/** 各稳定错误码的用户可见文案（网关 message 含实现细节时用它兜底）。 */
+const OFFICE_RELAY_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: '登录状态已过期，请重新登录',
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    RELAY_DISABLED: '本部署未启用文档中继，请联系管理员',
+    RELAY_EXPIRED: '编辑会话已过期，请重新打开文档',
+    RELAY_TOO_LARGE: '文档超过在线编辑的大小上限',
+    RELAY_EXTENSION: '该文档类型不支持在线编辑',
+    RELAY_QUOTA: '同时打开的编辑会话过多，请稍后再试',
+};
+/** 通用失败文案：不暴露任何网关细节。 */
+export const OFFICE_RELAY_GENERIC_FAILURE_MESSAGE = '文档中继暂时不可用，请稍后重试';
+/** 未登录 / 会话失效的统一文案（与其余频道同口径）。 */
+export const OFFICE_RELAY_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+/**
+ * 网关 message 消毒（与 `office-credentials.ts` 同实现，各频道自带一份）。
+ */
+export function displayOfficeRelayMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return OFFICE_RELAY_MESSAGE_FALLBACK[code] ?? OFFICE_RELAY_GENERIC_FAILURE_MESSAGE;
+    const leaksImplementationDetail = /https?:\/\//i.test(text)
+        || /\bHTTP\s*\d{3}\b/i.test(text)
+        || /\bbaseURL\b/i.test(text);
+    if (leaksImplementationDetail)
+        return OFFICE_RELAY_MESSAGE_FALLBACK[code] ?? OFFICE_RELAY_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+/** 凭据取数（无缓存；缓存策略是消费方的事）。 */
+export class OfficeRelayBroker {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async withSession(run) {
+        try {
+            const sessionCookie = await this.deps.resolveSession();
+            if (sessionCookie === undefined || sessionCookie === '') {
+                return { ok: false, code: 'SESSION_EXPIRED', message: OFFICE_RELAY_SESSION_EXPIRED_MESSAGE };
+            }
+            const gateway = this.deps.gateway();
+            if (gateway === undefined) {
+                return { ok: false, code: 'GATEWAY_UNREACHABLE', message: '网关地址未配置，请先在「网关模型」里完成登录' };
+            }
+            return { ok: true, value: await run(sessionCookie, gateway) };
+        }
+        catch (error) {
+            if (error instanceof GatewayError) {
+                return { ok: false, code: error.code, message: displayOfficeRelayMessage(error.code, error.message) };
+            }
+            this.deps.log?.(`hiwork-core: 文档中继调用失败（${error instanceof Error ? error.name : typeof error}）`);
+            return { ok: false, code: 'internal', message: OFFICE_RELAY_GENERIC_FAILURE_MESSAGE };
+        }
+    }
+    async upload(input, signal) {
+        if (signal?.aborted === true)
+            return { ok: false, code: 'cancelled', message: '上传已取消。' };
+        return await this.withSession(async (cookie, gateway) => {
+            const created = await gateway.createOfficeRelayDocument(cookie, input.name, input.bytes, input.mode);
+            return {
+                id: created.id,
+                documentKey: created.documentKey,
+                readUrl: created.readUrl,
+                callbackUrl: created.callbackUrl,
+                expiresAt: created.expiresAt,
+            };
+        });
+    }
+    async status(id, _signal) {
+        return await this.withSession(async (cookie, gateway) => await gateway.getOfficeRelayStatus(cookie, id));
+    }
+    async download(id, revision, _signal) {
+        return await this.withSession(async (cookie, gateway) => {
+            const content = await gateway.getOfficeRelayContent(cookie, id, revision);
+            return content.notModified
+                ? { notModified: true }
+                : { notModified: false, ...(content.bytes === undefined ? {} : { bytes: content.bytes }) };
+        });
+    }
+    async close(id, _signal) {
+        return await this.withSession(async (cookie, gateway) => {
+            await gateway.closeOfficeRelayDocument(cookie, id);
+            return {};
+        });
+    }
+}
+/**
+ * 提供 host 侧服务 `hiworkOfficeRelay`；返回 disposer（交给 `ctx.effect`）。
+ */
+export function provideOfficeRelay(ctx, deps) {
+    const service = new OfficeRelayBroker(deps);
+    const dispose = ctx.provide(OFFICE_RELAY_SERVICE, service);
+    return typeof dispose === 'function' ? dispose : () => { };
+}

package/lib/plugin-updates-rpc.js

@@ -0,0 +1,187 @@
+/**
+ * `/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 const PLUGIN_UPDATES_RPC_CHANNEL = '/hiwork-plugin-updates';
+/**
+ * 端点白名单：只有两个。
+ *
+ * `snapshot` 是「现在有没有待生效的更新」（桌面端读 pending 文件，**不拉清单、不写文件、
+ * 不触发回收**），`apply` 是「现在就去重启并应用」——它只在用户点击时被调用。
+ * 白名单是客户端可用的能力边界，多一项就等于先发布了一个没有实现的承诺。
+ */
+export const PLUGIN_UPDATES_RPC_ENDPOINTS = ['snapshot', 'apply'];
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export class PluginUpdatesRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PluginUpdatesRequestError';
+    }
+}
+/** 通用失败文案：不暴露任何桌面端细节。 */
+export const PLUGIN_UPDATES_GENERIC_FAILURE_MESSAGE = '插件更新状态暂时无法获取，请稍后重试';
+/** 是否为白名单端点。 */
+export function isPluginUpdatesRpcEndpoint(endpoint) {
+    return PLUGIN_UPDATES_RPC_ENDPOINTS.includes(endpoint);
+}
+/** 宽松的记录判定（数组与 null 都不算）。 */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 非空字符串或 undefined。 */
+function textOrUndefined(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/** 取消判定（用函数包一层，避免 TS 把属性窄化固化到 `await` 之后）。 */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+/**
+ * payload 校验：两个端点都**只放行空对象**（本频道没有任何入参）。
+ *
+ * 与 workbench / app-version 的空入参分支逐字同款：出现任何字段都是客户端实现缺陷，直接
+ * `bad-request`——一个 `{ force: true }` 被静默忽略，会让调用方以为「强制重启」生效了。
+ */
+export function parsePluginUpdatesPayload(endpoint, raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new PluginUpdatesRequestError('bad-request', '插件更新请求参数不合法。');
+    }
+    const keys = Object.keys(raw);
+    const first = keys[0];
+    if (first !== undefined) {
+        throw new PluginUpdatesRequestError('bad-request', `插件更新请求包含未知字段 '${first}'。`);
+    }
+    // endpoint 已在调用方过白名单；这里保留参数是为了类型上与其它频道的 parse* 同形。
+    void endpoint;
+    return {};
+}
+/**
+ * 一条更新的规范化：**只在缺 `packageName` 时丢条目**，其余兜底。
+ *
+ * 为什么判据是 `packageName` 而不是「`to` 是不是精确版本」：界面**只**依赖
+ * `packages.length > 0`（spec §4.3 的 ⚠️）。在这里按更严的形状丢条目，等于把一份真的待生效
+ * 更新静默吃掉——用户就再也等不到重启提示了。所以「形状兜底」在此处的方向是**保住计数**：
+ * 只要这条还指得出是哪个包就留下，`to` 缺了就记空串（界面本来也不渲染它）。
+ * 反过来，缺 `packageName` 的条目连「有没有东西要装」都回答不了，留着只会让界面误报。
+ */
+function toPackageUpdate(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const packageName = textOrUndefined(raw['packageName']);
+    if (packageName === undefined)
+        return undefined;
+    return {
+        packageName,
+        displayName: textOrUndefined(raw['displayName']) ?? packageName,
+        from: textOrUndefined(raw['from']) ?? '',
+        to: textOrUndefined(raw['to']) ?? '',
+    };
+}
+/**
+ * 把 `desktopPlugins.pending()` 的返回值规范化成 {@link PluginUpdatesSnapshot}。
+ *
+ * `undefined` / 非对象 → `undefined`（= 没有待生效项，界面不渲染）。**只有降级项（`held` 非空、
+ * `packages` 为空）时同样落成空 `packages`**，由客户端据此不渲染——回退对员工是要解释的事，
+ * 不该混在「更新已就绪」里（spec §4.5）。`held` 本身不搬运，理由见文件头。
+ */
+export function toSnapshot(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const packages = [];
+    for (const item of Array.isArray(raw['packages']) ? raw['packages'] : []) {
+        const normalized = toPackageUpdate(item);
+        if (normalized !== undefined)
+            packages.push(normalized);
+    }
+    const revision = raw['revision'];
+    const fetchedAt = raw['fetchedAt'];
+    return {
+        packages,
+        fetchedAt: typeof fetchedAt === 'number' && Number.isFinite(fetchedAt) ? fetchedAt : 0,
+        revision: typeof revision === 'number' && Number.isFinite(revision) ? revision : null,
+    };
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export async function handlePluginUpdatesEndpoint(endpoint, rawPayload, deps, signal) {
+    try {
+        if (isAborted(signal))
+            return failure('cancelled', '插件更新请求已取消。');
+        if (!isPluginUpdatesRpcEndpoint(endpoint)) {
+            throw new PluginUpdatesRequestError('bad-request', `未知的插件更新端点 '${endpoint}'`);
+        }
+        parsePluginUpdatesPayload(endpoint, rawPayload);
+        const plugins = deps.desktopPlugins();
+        if (endpoint === 'snapshot') {
+            // 「不可用」是**成功信封 + null**，不是错误（老桌面端共存的正常路径，见文件头）。
+            const value = plugins === undefined ? null : toSnapshot(await plugins.pending()) ?? null;
+            return { ok: true, value };
+        }
+        // apply：**唯一**的回收触发点，只在用户点击时到达这里。
+        if (plugins === undefined) {
+            // 不可用时不调 applyNow（没有可调的对象），同样按「不是错误」回执：
+            // `requested: false` 如实告诉客户端「这次请求没有被递下去」。
+            return { ok: true, value: { requested: false } };
+        }
+        await plugins.applyNow();
+        return { ok: true, value: { requested: true } };
+    }
+    catch (error) {
+        if (error instanceof PluginUpdatesRequestError)
+            return failure(error.code, error.message);
+        deps.log?.(`hiwork-core: 插件更新 RPC '${endpoint}' 失败（${error instanceof Error ? error.name : typeof error}）`);
+        return failure('internal', PLUGIN_UPDATES_GENERIC_FAILURE_MESSAGE);
+    }
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * 注册 `/hiwork-plugin-updates` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export function registerPluginUpdatesRpc(ctx, deps) {
+    const handler = (endpoint, payload, signal) => handlePluginUpdatesEndpoint(endpoint, payload, deps, signal);
+    const remove = ctx.connection.rpc.handle(PLUGIN_UPDATES_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => { await remove(); };
+}

package/lib/types/ai-router-client.d.ts

@@ -247,6 +247,45 @@ export interface GatewayMcpAssignmentsView {
     revision: number;
     assignments: GatewayMcpAssignment[];
 }
+/**
+ * GET /api/me/office-config 响应：本部署 OnlyOffice 集成的地址与共享 JWT 密钥。
+ *
+ * `jwtSecret` 是**共享的**一把密钥（Document Server 社区版只有一把），终端拿到它只为
+ * 签编辑器 config / 验保存回调；它只应在 host 侧使用，绝不进浏览器或日志。
+ */
+export interface GatewayOfficeConfig {
+    documentServerUrl: string;
+    jwtSecret: string;
+    /**
+     * 是否启用文档中继（管理员在网关侧的中央开关）。true 时在线编辑走
+     * 「上传 → DS 从签名 URL 拉 → 回调落版本 → 桌面端轮询取回」，不再要求
+     * DS 能回连用户电脑。旧版网关缺省该字段 → 视同 false（自动回落本机模式）。
+     */
+    relayEnabled?: boolean;
+}
+/** POST /api/me/office-relay/documents 响应：DS 侧两条签名 URL。 */
+export interface GatewayRelayDocument {
+    id: string;
+    documentKey: string;
+    readUrl: string;
+    callbackUrl: string;
+    expiresAt: string;
+}
+/** GET /api/me/office-relay/documents/:id 响应。 */
+export interface GatewayRelayStatus {
+    state: string;
+    revision: number;
+    contentSha256: string;
+    sizeBytes: number;
+    expiresAt: string;
+    savedAt: string;
+}
+/** GET …/content 的结果：204 表示客户端手里的版本已是最新。 */
+export interface GatewayRelayContent {
+    notModified: boolean;
+    revision: number;
+    bytes?: Uint8Array;
+}
 /**
  * POST /api/me/mcp-assertions 响应：一张 **120 秒**的身份断言（RS256 JWT）+
  * 去哪换令牌。断言本身不是凭据（换不成令牌就是废纸），所以它可以出现在这里；
@@ -259,6 +298,96 @@ export interface GatewayMcpAssertionTicket {
     expiresAt: string;
     serverName: string;
 }
+/**
+ * GET /api/me/skill-assignments 的一条分配（对齐 ai-hub spec §4.1 的冻结契约）。
+ *
+ * `skillName` 是**服务端权威**下发的装载名，也是受管目录名与模型侧 `/<名>` 的唯一来源；
+ * `contentSha256` 是「要不要重装」的唯一依据（`version` 只是给人看的标签，客户端**不得**
+ * 拿它比大小——它甚至是服务端派生值、库里没有这一列）。
+ */
+export interface GatewaySkillAssignment {
+    assignmentId: string;
+    /** 单条版本号：管理员每次推送 +1。 */
+    revision: number;
+    /** 管理端唯一名（只服务 URL 与展示，不是装载名）。 */
+    slug: string;
+    displayName: string;
+    skillName: string;
+    description: string;
+    contentSha256: string;
+    sizeBytes: number;
+    /** 展示用标签；服务端可缺省，缺省时为空串。 */
+    version: string;
+    updatedAt: string;
+}
+/**
+ * GET /api/me/skill-assignments 响应。**响应体里没有包体**（清单与包体分开两条端点）。
+ * `revision` 是清单级序号（任何影响清单的写入都 +1），客户端先比它、不同再逐条深比。
+ */
+export interface GatewaySkillAssignmentsView {
+    revision: number;
+    assignments: GatewaySkillAssignment[];
+}
+/**
+ * GET /api/me/skill-packages/:assignmentId 的结果：ZIP 原始字节 + 服务端声明的身份。
+ *
+ * `contentSha256` 取自响应头 `X-HiWork-Content-Sha256`，是**入库时算定**的那份哈希
+ * （spec §4.2：服务端只存取、不在响应时重新打包，否则 Go 版本一升级哈希就会漂，
+ * 客户端的内容校验会变成误报）；客户端必须拿它与收到的字节比对后才落盘（spec §6）。
+ */
+export interface GatewaySkillPackage {
+    skillName: string;
+    contentSha256: string;
+    bytes: Uint8Array;
+}
+/**
+ * GET /api/me/workbench-apps 里的一条应用（spec §4.1 的字段，`icon` 是网关侧的线名）。
+ *
+ * 这份声明刻意**宽松**（除 `code` 外全部可选，`executor` / `inputs` / `outputs` 用开放记录）：
+ * 清单是**服务端演进**的，spec §4.1 的演进纪律要求「未知字段忽略、未知 `executor.kind` /
+ * `inputs[].type` 原样透传」。形状判据与逐字段规范化在消费端 `/hiwork-workbench` 的 Host 半边
+ * （`src/workbench-bridge.ts`）——本层只做传输与状态码映射，把 JSON 直接断言成契约类型。
+ */
+export interface GatewayWorkbenchApp {
+    /** 应用唯一标识（管理端唯一名，也是卡片与服务端路径的坐标）。 */
+    code: string;
+    /** 单条版本号：管理员每次改动 +1。 */
+    revision?: number;
+    displayName?: string;
+    summary?: string;
+    /** 图标地址（网关线名就是 `icon`，不是 `iconUrl`；契约面的规范名见 `WorkbenchAppView`）。 */
+    icon?: string;
+    category?: {
+        code?: string;
+        name?: string;
+    };
+    tags?: string[];
+    featured?: boolean;
+    /**
+     * 执行器声明。`kind` 是**开放集合**（一期 `link` / `http-task`，二期 `session-task` /
+     * `embedded`）：客户端遇到不认识的 kind 必须置灰 + 提示升级，绝不崩，所以这里不收敛成联合类型。
+     */
+    executor?: {
+        kind?: string;
+        mode?: string;
+    } & Record<string, unknown>;
+    /** 输入项（形状随 `type` 演进：`accept` / `options` / `default` 只对某些 type 有意义）。 */
+    inputs?: Array<Record<string, unknown>>;
+    outputs?: Array<Record<string, unknown>>;
+    /** `[]` | `['external']` | `['metered']`（只影响确认策略与风险提示，不改变契约形状）。 */
+    effects?: string[];
+}
+/** GET /api/me/workbench-apps 响应（spec §4.1）。 */
+export interface GatewayWorkbenchAppsView {
+    /**
+     * 清单**整体**的契约版本（与 `revision` 不是一回事：前者是契约演进，后者是内容变更）。
+     * 本轮不据此拒收任何响应，原样透传给消费方自行判断。
+     */
+    schemaVersion?: number;
+    /** 清单级序号：服务端任何影响清单的写入都 +1（客户端先比它，不同再逐条深比）。 */
+    revision: number;
+    apps: GatewayWorkbenchApp[];
+}
 /** 网关客户端端口：orchestration 只依赖此接口。 */
 export interface GatewayClient {
     /**
@@ -300,8 +429,24 @@ export interface GatewayClient {
     estimateCost(sessionCookie: string, items: GatewayCostEstimateItem[]): Promise<GatewayCostEstimateResponse>;
     /** 管理员下发给当前账号的 MCP 清单（响应里没有令牌）。 */
     getMyMcpAssignments(sessionCookie: string): Promise<GatewayMcpAssignmentsView>;
+    /** 本部署 OnlyOffice 集成配置（地址 + 共享 JWT 密钥 + 中继开关；部署未配置时 503）。 */
+    getMyOfficeConfig(sessionCookie: string): Promise<GatewayOfficeConfig>;
+    /** 上传文档到中继（原始字节 + 文件名头），拿回 DS 侧签名 URL。 */
+    createOfficeRelayDocument(sessionCookie: string, name: string, bytes: Uint8Array, mode?: 'view' | 'edit'): Promise<GatewayRelayDocument>;
+    /** 轮询中继会话状态（revision 单调递增即"有新版本"）。 */
+    getOfficeRelayStatus(sessionCookie: string, id: string): Promise<GatewayRelayStatus>;
+    /** 取回当前版本字节；`revision` 用于"我手里已是这版"的短路（204）。 */
+    getOfficeRelayContent(sessionCookie: string, id: string, revision?: number): Promise<GatewayRelayContent>;
+    /** 关闭中继会话（立即清理字节）。 */
+    closeOfficeRelayDocument(sessionCookie: string, id: string): Promise<void>;
     /** 为某条分配签一张 120 秒的身份断言（拿它去 MCP 服务换 per-user 令牌）。 */
     issueMyMcpAssertion(sessionCookie: string, assignmentId: string): Promise<GatewayMcpAssertionTicket>;
+    /** 管理员下发给当前账号的技能清单（响应里没有包体——包体走 {@link getMySkillPackage}）。 */
+    getMySkillAssignments(sessionCookie: string): Promise<GatewaySkillAssignmentsView>;
+    /** 取某条分配的技能包体（ZIP 字节 + 服务端声明的 sha256）；分配不存在 404、未启用 503。 */
+    getMySkillPackage(sessionCookie: string, assignmentId: string): Promise<GatewaySkillPackage>;
+    /** 管理员登记并分配给当前账号的工作台应用清单（spec §4.1 的冻结契约；响应里没有令牌）。 */
+    getMyWorkbenchApps(sessionCookie: string): Promise<GatewayWorkbenchAppsView>;
     logout(sessionCookie: string): Promise<void>;
 }
 /**
@@ -375,6 +520,31 @@ export declare class AiRouterClient implements GatewayClient {
      * 清单（分 MCP 与分 Key 是两件事）。沿用它的 403 文案会把「没有 Key」错报成原因。
      */
     getMyMcpAssignments(sessionCookie: string): Promise<GatewayMcpAssignmentsView>;
+    /**
+     * POST /api/me/office-relay/documents：上传文档字节到中继。
+     *
+     * 文件名走 `X-Office-Document-Name` 头（HTTP 头只能带 ASCII，用 encodeURIComponent
+     * 编码；网关侧 PathUnescape 解码）。状态码映射成稳定 code，供插件层给用户文案。
+     */
+    createOfficeRelayDocument(sessionCookie: string, name: string, bytes: Uint8Array, mode?: 'view' | 'edit'): Promise<GatewayRelayDocument>;
+    /** GET /api/me/office-relay/documents/:id：轮询状态。 */
+    getOfficeRelayStatus(sessionCookie: string, id: string): Promise<GatewayRelayStatus>;
+    /**
+     * GET /api/me/office-relay/documents/:id/content[?v=N]：取回当前版本字节。
+     * 204 表示"你手里的版本已是最新"（不是错误）。
+     */
+    getOfficeRelayContent(sessionCookie: string, id: string, revision?: number): Promise<GatewayRelayContent>;
+    /** DELETE /api/me/office-relay/documents/:id：关闭会话（幂等）。 */
+    closeOfficeRelayDocument(sessionCookie: string, id: string): Promise<void>;
+    /**
+     * GET /api/me/office-config：本部署 OnlyOffice 集成（Document Server 地址 + 共享 JWT 密钥）。
+     *
+     * 与 {@link getMyMcpAssignments} 同样的理由不复用 `getMeJson`：那条路径把 403 映射成
+     * `NO_KEY_ASSIGNED`，而本端点只看会话（分集成配置与分 Key 是两件事）。503 是
+     * 「部署未配置」的稳定信号，单独映射——消费方（hiwork-office）据此提示联系管理员
+     * 并回退本地手工配置，而不是报一句含糊的「网关不可达」。
+     */
+    getMyOfficeConfig(sessionCookie: string): Promise<GatewayOfficeConfig>;
     /**
      * POST /api/me/mcp-assertions：为某条分配签一张 120 秒断言。
      *
@@ -383,6 +553,80 @@ export declare class AiRouterClient implements GatewayClient {
      * 「服务停用了」（该重试）还是「部署没配私钥」（找管理员）。
      */
     issueMyMcpAssertion(sessionCookie: string, assignmentId: string): Promise<GatewayMcpAssertionTicket>;
+    /**
+     * GET /api/me/skill-assignments：管理员下发给当前账号的技能清单（spec §4.1）。
+     *
+     * 与 {@link getMyMcpAssignments} 同样的理由不复用 `getMeJson`：那条路径把 403 映射成
+     * `NO_KEY_ASSIGNED`（「尚未被分配虚拟 KEY」），而本端点的鉴权只有会话——一个还没被分配 Key
+     * 的账号照样应该有技能清单（分技能与分 Key 是两件事）。
+     *
+     * **这条路径上只有 401 有独立语义，其余全部收敛成 `GATEWAY_UNREACHABLE`**，理由逐条：
+     *  - 401 = 会话过期/缺失（`middleware` 的会话鉴权）——唯一一条服务端**真的会为这条路由**发出的
+     *    拒绝，也是唯一一条能让人做点什么（重新登录）的；
+     *  - 403 不会出现：这条路由的鉴权只有会话，没有「有没有被分配虚拟 KEY」那一层（正因为如此，
+     *    这里才不能复用 `getMeJson`，那个函数会把 403 读成「没分配 KEY」）；
+     *  - 404 不是这条路由的响应形状：清单**永远**是 200 + 一份数组，某条技能被停用 / 被撤销是
+     *    「不在数组里」，不是 404（`MyAssignments` 逐条过滤，不会为单条抛错）。真收到 404 只可能是
+     *    「路径压根没被路由」——老网关没有这条路由的时候就是这个样子，而它与反代配错无法区分，
+     *    所以诚实读法是网关不可达，不是「管理员把技能全撤了」；
+     *  - 503 不会出现：员工端这条路由**无条件注册**，服务端没有任何「技能下发未启用」的闸
+     *    （`getMySkillPackage` 那条 503 也一样没有生产者，见那里的注释），整份响应由 service
+     *    直接产出；
+     *  - 其余（5xx / 反代错误页 / 维护页）同理：没有可解释的拒绝语义，收敛成网关不可达。
+     *
+     * 形状校验（`assignments` 必须是数组）**不在这里**：本方法只做传输与状态码映射，把 JSON 直接
+     * 断言成契约类型。真正的形状判据在消费端 `/hiwork-managed-skills` 的 Host 半边
+     * （`src/managed-skills.ts` 的 `fetchOnce`）——那里才决定「这一份算不算成功拉到的清单」。
+     */
+    getMySkillAssignments(sessionCookie: string): Promise<GatewaySkillAssignmentsView>;
+    /**
+     * GET /api/me/skill-packages/:assignmentId：取一条分配的包体字节（spec §4.2）。
+     *
+     * **这条路径是「两个端口」里的另一条**，它才有独立的拒绝语义（与服务端 handler 一一对应）：
+     *  - 404 = 这条分配不在这个账号名下（已被撤销 / 从未属于它，`ErrSkillAssignmentNotForUser`
+     *    ——技能被停用 / 分配被停用也走这一条，服务端刻意不区分），
+     *  - 503 = 部署未启用技能下发（**保留的防御性映射：当前没有生产者**，见下）。
+     * 两者必须分开映射，否则客户端只会看到一句「拉包失败」。用途是**别把原因咽下去**：404 让人
+     * 停止重试、把原因显示出来（「这条分配已失效，稍后同步会重新核对」），503 让人知道该找管理员。
+     * ⚠️ 事实核对（spec §4.5）：`SKILL_DISTRIBUTION_DISABLED` 全仓**只有本方法这一个生产方**
+     * （本方法里 503 那一支），而 ai-hub 目前**没有任何**会产生这个 503 的代码——员工端两条路由在
+     * `cmd/server/main.go` 里无条件注册，技能 / 分配被停用在员工端走 404
+     * （`ErrSkillAssignmentNotForUser`）。映射保留是**防御性 + 与 MCP 同形**（那里
+     * `MCP_ASSERTION_DISABLED` 真有生产者：`me_mcp_handler.go` 的 503），别拿它当「会发生的分支」
+     * 去设计行为。
+     * ⚠️ **这两条都只是「失败的原因」，不是删除本地受管技能的依据**：删除的唯一权柄是「成功拉到的
+     * 清单」（spec §6 的唯一安全不变量），由 Host 的清单端点产出。本文件里没有任何一处据 404 或
+     * `contentSha256` 去删本地技能（全仓 `SKILL_ASSIGNMENT_GONE` 只有生产方、类型联合、文案表与
+     * 测试，没有消费方）。
+     * 404 而不泄露「这条分配是否存在」是服务端的选择（§4.2 明确要 404 不要 403）。
+     *
+     * 本调用方从不发 `If-None-Match`（§4.2 说 304 那条是给管理端与 curl 排障用的），所以 304
+     * 不在这条路径上；真收到（反代插话）会落进下面那条 → 网关不可达。
+     *
+     * 包体**只在本函数里短暂存在**：交给 Host 侧频道（src/managed-skills.ts）后立即 base64
+     * 出去，网关会话 cookie 全程不出 Host，浏览器侧永远拿不到字节。
+     */
+    getMySkillPackage(sessionCookie: string, assignmentId: string): Promise<GatewaySkillPackage>;
+    /**
+     * GET /api/me/workbench-apps：管理员登记并分配给当前账号的工作台应用清单（spec §4.1）。
+     *
+     * 与技能清单同款**不复用 `getMeJson`**：那条路径把 403 映射成 `NO_KEY_ASSIGNED`（「尚未被分配
+     * 虚拟 KEY」），而本端点的鉴权只有会话——一个还没被分配 Key 的账号照样应该有工作台。
+     *
+     * 状态码映射（**与技能清单有一处刻意的不同**，理由在下面）：
+     *  - 401 = 会话过期/缺失：唯一一条能让人做点什么（重新登录）的拒绝；
+     *  - **404 = 本部署未启用工作台**：这条路由在网关侧是「有配置才有」的（spec §10 的降级矩阵：
+     *    「网关未配置 workbench → 回 404」），因此 404 不是「应用清单为空」也不是网络故障，
+     *    而是一个可展示的功能状态——客户端据此显示「本部署尚未启用工作台」而不是报错。
+     *    ⚠️ 技能清单那半**刻意**没有这一档（那里 404 只能是路径没被路由，收敛成网关不可达）；
+     *    两边的差别是服务端语义的差别，不是实现风格的差别，别顺手对齐；
+     *  - 其余（403 / 5xx / 反代错误页 / 维护页）一律 `GATEWAY_UNREACHABLE`：没有可解释的拒绝语义。
+     *
+     * 形状校验（`apps` 必须是数组）**不在这里**：本方法只做传输与状态码映射，把 JSON 直接断言成
+     * 契约类型；真正的形状判据在消费端 `/hiwork-workbench` 的 Host 半边（`src/workbench-bridge.ts`），
+     * 那里才决定「这一份算不算成功拉到的清单」。
+     */
+    getMyWorkbenchApps(sessionCookie: string): Promise<GatewayWorkbenchAppsView>;
     /**
      * /api/me 自助端点的 GET 公共路径：网络异常 → GATEWAY_UNREACHABLE，
      * 401/403/400 映射为稳定 code，响应体非 JSON 时不把原文带进异常。

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

@@ -22,6 +22,8 @@
  */
 import type { FeatureRegistry } from './feature-registry.ts';
 import type { ManagedMcpAssertion, ManagedMcpSnapshot } from './managed-mcp.ts';
+import type { ManagedSkillsFace } from './managed-skills.ts';
+import type { ManagedWorkbenchFace } from './managed-workbench.ts';
 /** cordis 服务名：`hiwork-core` 的 client 半边提供，业务插件按名注入。 */
 export declare const HIWORK_FEATURE_CENTER_SERVICE = "hiworkFeatureCenter";
 /**
@@ -63,4 +65,40 @@ export interface HiWorkCoreClientFace {
         /** 订阅镜像变化（登出 / 换账号时会被清空）。返回退订函数。 */
         readonly subscribe: (listener: () => void) => () => void;
     };
+    /**
+     * 管理员下发的技能（技能域消费，见 `src/client/managed-skills.ts`；契约见 ai-hub 的
+     * spec `docs/superpowers/specs/2026-09-17-skill-distribution-design.md` §4.5）。
+     *
+     * **可选成员**（与 `managedMcp` 同款的可选解耦）：新 core 遇到老 capabilities 只是
+     * **没人来取**（能力中心照常工作，只是没有受管技能那一块）；老 core 遇到新 capabilities
+     * 只是**没有这个面**（`face.managedSkills` 为 `undefined`，消费方按「这个部署不支持受管
+     * 技能」降级）。两侧因此不必严格同发一个版本——发布顺序（spec §7）允许 core 先发。
+     *
+     * 这一面**只交出清单与包体字节**：技能链路没有服务端调用、没有凭证，所以既没有断言，
+     * 也没有任何票据；落盘与完整性校验在技能域，核心既不落盘也不解包。
+     *
+     * ⚠️ **`snapshot` 不参与同步**：它可能是上一次成功的结果（管理员刚撤掉的分配还在里面），
+     * 拿它做删除决策就会把「管理员撤销了」误做成「这次没拉到」——删除只允许走 `refresh`
+     * 成功返回的清单（spec §6 的唯一安全不变量，`src/client/managed-mcp.ts:9-12` 同款）。
+     */
+    readonly managedSkills?: ManagedSkillsFace;
+    /**
+     * 管理员登记并分配给当前账号的**工作台应用清单**（工作台域消费，见 `src/client/managed-workbench.ts`；
+     * 契约见 hiwork-workbench 的 spec `docs/superpowers/specs/2026-09-17-hiwork-workbench-design.md`
+     * §4.1 / §4.5）。
+     *
+     * **可选成员**（与 `managedMcp` / `managedSkills` 同款的两级可选语义）：新 core 遇到老
+     * workbench 只是**没人来取**；老 core 遇到新 workbench 只是**没有这个面**
+     * （`face.managedWorkbench` 为 `undefined`，工作台按「本部署尚未启用工作台」降级，spec §10）。
+     * 两侧因此不必严格同发一个版本——发布顺序（spec §11 的硬约束）允许 core 先发。
+     *
+     * **M0 只交出清单**：本面没有 `submit` / `poll` / `cancel` / `materialize`（那是 M1 的任务运行时，
+     * spec §4.5 的完整面在那时才补齐）。工作台消费方据此判断能力：这几个成员不存在，就是
+     * 「这个 core 只能看货架」。
+     *
+     * ⚠️ **`snapshot` 不参与下架决策**：它可能是上一次成功的结果（管理员刚撤掉的条目还在里面），
+     * 拿它做删除决策就会把「管理员撤销了」误做成「这次没拉到」——「这个应用不在了」只允许走
+     * `refresh` 成功返回的清单（spec §4.5 的冻结纪律，`src/client/managed-mcp.ts:9-12` 同款）。
+     */
+    readonly managedWorkbench?: ManagedWorkbenchFace;
 }