hiwork-core 0.0.10 → 0.0.16

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/types/ai-router-client.d.ts

@@ -209,6 +209,185 @@ export interface GatewayDailyQuoteResponse {
 export interface GatewayDailyQuoteRandomResponse {
     item: GatewayDailyQuoteItem | null;
 }
+/**
+ * 一条下发给当前账号的 MCP 分配（`GET /api/me/mcp-assignments` 的 `assignments[]`）。
+ *
+ * **字段名是跨仓冻结契约**（ai-hub spec §4.1）：四仓（visio-mcp / ai-hub / hiwork-core /
+ * hiwork-capabilities）唯一的接口面，改一个字段名要先改 spec 并同步四仓注释。
+ */
+export interface GatewayMcpAssignment {
+    /** 服务端分配 id：客户端按它派生连接 key（`admin-<assignmentId>`），因此必须稳定。 */
+    assignmentId: string;
+    /** 单条版本号：管理员每次推送 +1，客户端据此判「这条要不要重新落地」。 */
+    revision: number;
+    /** 服务的 slug（ai-hub 侧唯一名，也是断言的 audience）。 */
+    slug: string;
+    displayName: string;
+    /** 服务端权威下发的装载名（工具前缀 `mcp__<serverName>__` 跨版本稳定的锚点）。 */
+    serverName: string;
+    /** `streamable-http | stdio`（与 capabilities 的传输判别联合同源）。 */
+    transport: string;
+    url: string;
+    /** 非凭证的业务请求头；`{}` 表示没有。 */
+    extraHeaders: Record<string, string>;
+    auth: GatewayMcpAssignmentAuth;
+    updatedAt: string;
+}
+/** 取凭证的入口：去哪换（mintUrl）、去哪还（revokeUrl）。`kind` 目前只有 `assertion`。 */
+export interface GatewayMcpAssignmentAuth {
+    kind: string;
+    mintUrl: string;
+    revokeUrl: string;
+}
+/**
+ * GET /api/me/mcp-assignments 响应。
+ * `revision` 是清单级序号（任何会影响清单的写入都 +1），客户端先比它、不同再逐条深比。
+ */
+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）+
+ * 去哪换令牌。断言本身不是凭据（换不成令牌就是废纸），所以它可以出现在这里；
+ * 真正的 per-user 令牌由 MCP 服务在 exchange 时一次性返回，网关与核心都拿不到。
+ */
+export interface GatewayMcpAssertionTicket {
+    assertion: string;
+    mintUrl: string;
+    revokeUrl: string;
+    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 {
     /**
@@ -248,6 +427,26 @@ export interface GatewayClient {
     getMyKeyRecharges(sessionCookie: string, keyId?: string, modelName?: string): Promise<GatewayRecharge[]>;
     /** 网关权威计价：只回金额与生效单价，客户端不做任何算式。 */
     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>;
 }
 /**
@@ -313,6 +512,121 @@ export declare class AiRouterClient implements GatewayClient {
      * `input_tokens` 不含 cache；任何折算与单价计算都在网关侧完成。
      */
     estimateCost(sessionCookie: string, items: GatewayCostEstimateItem[]): Promise<GatewayCostEstimateResponse>;
+    /**
+     * GET /api/me/mcp-assignments：管理员下发给当前账号的 MCP 清单。
+     *
+     * 不复用 {@link getMeJson}：那条路径把 403 映射成 `NO_KEY_ASSIGNED`（「尚未被分配
+     * 虚拟 KEY」），而本端点的鉴权只有会话——一个还没被分配 Key 的账号照样应该有
+     * 清单（分 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 秒断言。
+     *
+     * 三种拒绝各有确定含义（服务端 handler 的 404/409/503），必须分开映射——否则
+     * 客户端只会看到一句「取断言失败」，既分不清「被撤销了」（该卸连接）还是
+     * 「服务停用了」（该重试）还是「部署没配私钥」（找管理员）。
+     */
+    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

@@ -21,6 +21,9 @@
  * 即可（见 `hiwork-automation` 的 `contracts.ts`），运行期只按服务名读取。
  */
 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";
 /**
@@ -38,4 +41,64 @@ export interface HiWorkCoreClientFace {
     readonly openNativeSession: (sessionId: string) => void;
     /** 回到原生「新会话」首页：先退出 takeover，再触发原生新会话动作。 */
     readonly openNativeHome: () => void;
+    /**
+     * 管理员下发的 MCP（连接器域消费，见 `src/client/managed-mcp.ts`）。
+     *
+     * **可选成员**：老版本 hiwork-core 没有这个面、新版本 hiwork-capabilities 遇到它
+     * 时只会看到 `undefined`（能力中心照常工作，只是没有受管连接）；反过来新 core 遇到
+     * 老 capabilities 也只是没人来取。两侧因此不必严格同发一个版本。
+     *
+     * 这一面**只交出清单与短期断言**：换 per-user 令牌是连接器域自己拿断言去 MCP 服务
+     * 做的，核心既不换也不存。
+     */
+    readonly managedMcp?: {
+        /** 本地镜像（同步读，可能是上一次成功的结果）。**不要拿它做删除决策**。 */
+        readonly snapshot: () => ManagedMcpSnapshot | undefined;
+        /** 本地镜像是否陈旧（或从未同步过）。 */
+        readonly isStale: (ttlMs?: number) => boolean;
+        /** 用 Host 的预热缓存拿一份清单（命中缓存时零网络请求）。 */
+        readonly warm: (signal?: AbortSignal) => Promise<ManagedMcpSnapshot>;
+        /** 强制拉一次，返回**刚拉到的**清单；失败抛错。只有它的返回值保证是当下的真相。 */
+        readonly refresh: (signal?: AbortSignal) => Promise<ManagedMcpSnapshot>;
+        /** 取一张 120 秒的身份断言 + 去哪换令牌。 */
+        readonly assertion: (assignmentId: string, signal?: AbortSignal) => Promise<ManagedMcpAssertion>;
+        /** 订阅镜像变化（登出 / 换账号时会被清空）。返回退订函数。 */
+        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;
 }

package/lib/types/client/managed-mcp.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 「管理员下发的 MCP」客户端取数层：经 `/hiwork-managed-mcp` loopback RPC 拿到
+ * 清单与短期断言，交给连接器域（hiwork-capabilities）去换令牌并落地。
+ *
+ * 铁律：
+ *  - 客户端**不持有**会话 cookie，也**不直接 fetch 网关**——一切经 Host 频道；
+ *  - 客户端**不做 exchange、不持有 MCP 令牌**：本层交出去的只有「清单 + 一张刚取的
+ *    断言 + mintUrl」，per-user 令牌只在连接器域内部存在；
+ *  - **只有 {@link ManagedMcpStore.refresh} 成功返回的清单才允许用作删除本地受管连接的
+ *    依据**；{@link ManagedMcpStore.snapshot} 可能与界面展示共享，但它可能是上一次
+ *    成功的结果（服务端刚撤掉的分配还在里面），拿它做删除决策就会把「撤销」误做成
+ *    「没同步上」——反过来，拉取失败时它又是唯一的真相来源，所以两个入口必须分开。
+ *
+ * client bundle 纯度：本文件不 import 任何 `@deepseek-ai/*` 运行时值，也不 import
+ * Host 代码（类型按结构重声明，字段名与契约一致）。
+ */
+/** RPC 频道；必须与 Host `src/managed-mcp.ts` 的 `MANAGED_MCP_RPC_CHANNEL` 一致（由测试锁定）。 */
+export declare const MANAGED_MCP_CHANNEL = "/hiwork-managed-mcp";
+/** 端点白名单；必须与 Host `MANAGED_MCP_RPC_ENDPOINTS` 一致（由测试锁定）。 */
+export declare const MANAGED_MCP_ENDPOINTS: readonly ["snapshot", "refresh", "assertion"];
+export type ManagedMcpEndpoint = (typeof MANAGED_MCP_ENDPOINTS)[number];
+/**
+ * 本地镜像的「陈旧」阈值：5 分钟。
+ * 触发时机里的「打开连接器页且 >5min stale 就同步一次」用它判定——短于它只会让
+ * 用户每次切页都打一遍网关，长于它则界面上的清单明显落后于管理员的推送。
+ */
+export declare const MANAGED_MCP_STALE_MS: number;
+/** 一条分配（对齐 ai-hub spec §4.1 的冻结契约）。 */
+export interface ManagedMcpAssignment {
+    assignmentId: string;
+    revision: number;
+    slug: string;
+    displayName: string;
+    /** 服务端权威下发的装载名：工具前缀 `mcp__<serverName>__` 跨版本稳定的锚点。 */
+    serverName: string;
+    /** `streamable-http | stdio`；认不认识的判断在连接器域（不认识的整条跳过并报冲突）。 */
+    transport: string;
+    url: string;
+    extraHeaders: Record<string, string>;
+    auth: {
+        kind: string;
+        mintUrl: string;
+        revokeUrl: string;
+    };
+    updatedAt: string;
+}
+/** 一份清单快照。`stale` 为 true 表示最近一次拉取失败，展示的是上一次成功的结果。 */
+export interface ManagedMcpSnapshot {
+    revision: number;
+    fetchedAt: string;
+    assignments: ManagedMcpAssignment[];
+    stale: boolean;
+    lastError?: {
+        code: string;
+        message: string;
+    };
+}
+/** 取断言的结果：一张 120 秒的门票 + 去哪换令牌。 */
+export interface ManagedMcpAssertion {
+    assertion: string;
+    mintUrl: string;
+    revokeUrl: string;
+    expiresAt: string;
+    serverName: string;
+}
+/** 宿主 loopback RPC 调用面（结构兼容 `ctx.connection.rpc`）。 */
+export interface ManagedMcpRpcPort {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/** 带稳定 code 的取数错误（message 已由 Host 消毒，可直接展示）。 */
+export declare class ManagedMcpRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 解开 DSH Connection 的结果信封。
+ * 宿主返回 `{ok:true,value}` / `{ok:false,error:{code,message}}`；形状不合法时抛
+ * 通用失败，绝不把未知结构当数据用。
+ */
+export declare function unwrapManagedMcpResult<T>(value: unknown): T;
+/** 任意异常 → 可展示的 `{code, message}`（传输层异常不暴露原始 message）。 */
+export declare function managedMcpErrorOf(error: unknown): {
+    code: string;
+    message: string;
+};
+/**
+ * 受管 MCP 的取数仓库。
+ *
+ * 本地镜像（`snapshot()` 同步读）是有必要的：DSH 的 client 半边在不同插件之间只通过
+ * 这个面同步取状态，而清单本身是异步来的。镜像**只由成功响应覆写**，失败时不改动它。
+ */
+export declare class ManagedMcpStore {
+    private readonly rpc;
+    private current;
+    private readonly listeners;
+    private inFlight;
+    constructor(rpc: ManagedMcpRpcPort);
+    /** 本地镜像（同步）。从没成功同步过返回 undefined。**不要拿它做删除决策**（见文件头）。 */
+    snapshot(): ManagedMcpSnapshot | undefined;
+    /** 本地镜像是否已经陈旧（或从未同步过）。 */
+    isStale(ttlMs?: number, now?: number): boolean;
+    /**
+     * 强制同步一次并返回**刚拉到的**清单。
+     *
+     * 返回值（而不是让人随后去读 `snapshot()`）是刻意的：只有这个返回值保证「这一次
+     * 网络请求成功了」，用它做删除决策才是安全的；读镜像可能读到上一次的结果。
+     * 失败时抛错且**不动镜像**——调用方据此保持现有的连接一条不删。
+     */
+    refresh(signal?: AbortSignal): Promise<ManagedMcpSnapshot>;
+    /**
+     * 取一份清单，**能用 Host 的预热缓存就用**（Host 后台每 30 分钟拉一次）。
+     *
+     * 与 {@link refresh} 的分工：这里是「启动时先把界面填上」的便宜入口——命中缓存时
+     * 一次网络请求都不发；Host 缓存也是冷的才会真的去拉。返回值仍保证是「某一次成功
+     * 拉取的结果」，但**可能比服务端现状旧**（最旧不超过 Host 的上一次成功拉取），
+     * 所以调用方按 `stale` / `isStale()` 判定它够不够权威，不够就再 `refresh()` 一次。
+     */
+    warm(signal?: AbortSignal): Promise<ManagedMcpSnapshot>;
+    /** 取一张新鲜断言（120 秒）。失败抛错；本层不缓存、不换令牌。 */
+    assertion(assignmentId: string, signal?: AbortSignal): Promise<ManagedMcpAssertion>;
+    /** 订阅镜像变化（连接器域据此重渲染 / 重排同步）。返回退订函数。 */
+    subscribe(listener: () => void): () => void;
+    /** 清空镜像（登出 / 换账号：清单是按人的，留着会串号）。 */
+    clear(): void;
+    /**
+     * 并发去重：`warm` 与 `refresh` 撞在一起（启动同步与定时同步常常同拍）时共用一次
+     * 请求，且**共用同一个返回值**——两边对「这一次拉到了什么」的判断必须一致。
+     */
+    private dedupe;
+    /** 采纳一份成功响应：写镜像 + 通知订阅者（失败路径永远不会走到这里）。 */
+    private adopt;
+    private emit;
+}