hiwork-core 0.0.10 → 0.0.16

package/lib/managed-skills.js

@@ -0,0 +1,446 @@
+/**
+ * `/hiwork-managed-skills` loopback RPC 的 Host 实现：管理员下发的技能清单 + 按需取回的包体字节。
+ *
+ * 契约见 ai-hub 的 spec `docs/superpowers/specs/2026-09-17-skill-distribution-design.md` §4.5
+ * （Host 半边），清单字段见 §4.1、包体端点见 §4.2。本文件是 `src/managed-mcp.ts` 同一副骨架的
+ * **第二条链**——技能比 MCP 短一整段（没有服务端调用 ⇒ 没有凭证、没有断言、没有 mint/revoke），
+ * 所以刻意**不把 MCP 独有的东西搬过来**：端点少一个（`assertion`），也没有任何票据。
+ *
+ * 与 MCP 的实质差异有两处（第二处见 {@link ManagedSkillsStore.bindSession}，那里写了为什么**不许**
+ * 为了「两半对齐」改回去）：
+ *  - `package` 会把**大字节**交给客户端（ZIP 的 base64），因此它是全频道唯一的带大小闸的端点
+ *    ——spec §8 R8 说得很清楚，这是唯一一条把大字节经 Host 搬进客户端的路径；
+ *  - 内存清单**按会话绑定**：缓存只属于产生它的那个会话，登出 / 换账号后绝不再吐出去。
+ *
+ * 与 MCP 逐字同款的两条铁律：
+ *  - **网关会话 cookie 绝不离开 Host**：cookie 只在 `resolveSession()` 内部出现，客户端拿到的
+ *    是清单与包体字节（经 loopback RPC 以 base64 过去），浏览器侧永远拿不到包体，也零 fetch；
+ *  - **拉清单失败绝不清空上一次成功的清单**：客户端只有在拿到一份「成功拉到的清单」时才允许
+ *    删除本地受管技能（spec §6 的唯一安全不变量），所以失败必须返回「保留旧值 + 标注失败原因」，
+ *    否则一次网络抖动就会让员工端把自己装好的技能删干净。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link ManagedSkillsRpcContext} 端口，便于单测直接伪造。
+ */
+import { GatewayError, } from "./ai-router-client.js";
+/** RPC 频道；必须与 client 半边 `src/client/managed-skills.ts` 的 `MANAGED_SKILLS_CHANNEL` 一致（由测试锁定）。 */
+export const MANAGED_SKILLS_RPC_CHANNEL = '/hiwork-managed-skills';
+/**
+ * 端点白名单。
+ *
+ * `snapshot` 是「你现在有什么」（有缓存就直接给，冷启动才拉一次），`refresh` 是「现在去拉一次」，
+ * `package` 是「把某一条的包体给我」。分三个端点的理由与 MCP 同款：客户端的同步策略（启动 /
+ * 30 分钟 / 打开能力中心且 >5min stale / 手动「立即同步」）由它自己定，Host 不该替它决定
+ * 什么时候必须联网；而 `package` 必须**按需单独取**——同步一轮只搬「真要装/更新」的那几条，
+ * 一轮带全等于每次同步都把所有技能包拉一遍（spec §4.6 的 `needsPackage` 就是这个形状）。
+ */
+export const MANAGED_SKILLS_RPC_ENDPOINTS = ['snapshot', 'refresh', 'package'];
+/**
+ * Host 侧后台预热间隔：30 分钟（与客户端同步节奏同量级）。
+ * 它**不是**权威节奏——只为让客户端首次 `snapshot` 不必等一次网络往返。
+ */
+export const MANAGED_SKILLS_REFRESH_INTERVAL_MS = 30 * 60_000;
+/**
+ * 包体上限：4 MiB（spec §2 的冻结决策）。ai-hub 侧的常量叫 `MAX_MANAGED_ARCHIVE_BYTES`，
+ * 两仓各自定格同一个数值、不是同一份代码；这里**不是**「与客户端同值」的那类约定
+ * （spec §5.4 第 5 步特地警告过：别把客户端 32 MiB 的浏览器上传门槛误当成本条）。
+ *
+ * 它拦的不是「服务端超发」（服务端入库与服务时各拦一次），而是**不让超大字节经 loopback RPC
+ * 搬进客户端**：base64 之后约 5.3 MiB 的字符串，是这条通道上唯一一次大对象传输（spec §8 R8）。
+ */
+export const MAX_MANAGED_SKILL_ARCHIVE_BYTES = 4 * 1024 * 1024;
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export class ManagedSkillsRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ManagedSkillsRequestError';
+    }
+}
+/**
+ * 各稳定错误码的用户可见文案（网关 message 含实现细节时用它兜底）。
+ * 只列本频道**真会收到**的 code：技能链路没有 `NO_KEY_ASSIGNED` 那一档
+ * （分技能与分 Key 是两件事，见 `getMySkillAssignments` 的注释）。
+ */
+const MANAGED_SKILLS_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: '登录状态已过期，请重新登录',
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    SKILL_ASSIGNMENT_GONE: '这条分配已失效，稍后同步会重新核对',
+    SKILL_DISTRIBUTION_DISABLED: '本部署未启用技能下发，请联系管理员',
+};
+/** 通用失败文案：不暴露任何网关细节。 */
+export const MANAGED_SKILLS_GENERIC_FAILURE_MESSAGE = '技能清单暂时无法获取，请稍后重试';
+/** 未登录 / 会话失效的统一文案（与用量、每日一句、MCP 清单几个频道同口径）。 */
+export const MANAGED_SKILLS_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+/** 收到超上限包体时的失败 code（服务端超发 / 契约被改大时才会走到）。 */
+export const MANAGED_SKILLS_PACKAGE_TOO_LARGE_CODE = 'SKILL_PACKAGE_TOO_LARGE';
+/** 超上限包体的文案：给员工一句可行动的话（找管理员），而不是一个数字。 */
+export const MANAGED_SKILLS_PACKAGE_TOO_LARGE_MESSAGE = '这个技能包超过了大小上限，暂时装不上，请联系管理员';
+/**
+ * 网关 message 消毒（与 `usage-rpc.ts` 的 `displayGatewayMessage` 同实现，MCP 那半逐字同款）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的中文业务文案）
+ * 原样保留。code 不受影响，始终原样透传。
+ */
+export function displayManagedSkillsMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return MANAGED_SKILLS_MESSAGE_FALLBACK[code] ?? MANAGED_SKILLS_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 MANAGED_SKILLS_MESSAGE_FALLBACK[code] ?? MANAGED_SKILLS_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+/**
+ * `package` 的 assignmentId 形状：只放行 uuid 用的字符集与长度（1–64）。
+ *
+ * 与 `managed-mcp.ts` 的同名常量**逐字相同但不是同一个**（那个没导出，也不该为了共用而改样板文件）：
+ * 这是全频道唯一一处客户端可控输入，卡在 Host 比卡在网关早——一个带空格 / 换行 / 百分号的串
+ * 没有任何合法来源（服务端的 assignment id 是 uuid），直接 `bad-request`。
+ */
+const ASSIGNMENT_ID_PATTERN = /^[0-9a-fA-F-]{1,64}$/;
+/**
+ * payload 校验：`snapshot` / `refresh` 只放行空对象，`package` 只放行 `{ assignmentId }`；
+ * 其余字段 / 类型不符一律 `bad-request`。
+ */
+export function parseManagedSkillsPayload(endpoint, raw) {
+    if (raw === undefined || raw === null) {
+        if (endpoint === 'package')
+            throw new ManagedSkillsRequestError('bad-request', '取技能包请求缺少 assignmentId。');
+        return {};
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ManagedSkillsRequestError('bad-request', '技能清单请求参数不合法。');
+    }
+    const record = raw;
+    const keys = Object.keys(record);
+    if (endpoint !== 'package') {
+        // snapshot / refresh 无任何入参：出现任何字段都是客户端实现缺陷。
+        if (keys.length > 0)
+            throw new ManagedSkillsRequestError('bad-request', `技能清单请求包含未知字段 '${keys[0]}'。`);
+        return {};
+    }
+    for (const key of keys) {
+        if (key !== 'assignmentId')
+            throw new ManagedSkillsRequestError('bad-request', `取技能包请求包含未知字段 '${key}'。`);
+    }
+    const rawId = record['assignmentId'];
+    if (typeof rawId !== 'string' || !ASSIGNMENT_ID_PATTERN.test(rawId.trim())) {
+        throw new ManagedSkillsRequestError('bad-request', '取技能包请求的 assignmentId 不合法。');
+    }
+    return { assignmentId: rawId.trim() };
+}
+/** 是否为白名单端点。 */
+export function isManagedSkillsRpcEndpoint(endpoint) {
+    return MANAGED_SKILLS_RPC_ENDPOINTS.includes(endpoint);
+}
+/** 非空字符串或 undefined（清单里一个字段坏了不该让整条清单失败）。 */
+function textOrUndefined(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * 把网关响应里的一条分配规范化成 {@link ManagedSkillAssignment}。
+ *
+ * **结构不完整就整条丢弃**：缺了 `assignmentId` / `skillName` / `contentSha256` 的条目根本装不了
+ * ——前两个是落盘坐标，第三个是「要不要装、装对了没有」的唯一判据（少了它，客户端会拿到一个
+ * 每次都比不上的哈希，症状是「永远装不上」而不是「这次没拉到」）。丢弃时记一条日志，因为
+ * 服务端数据问题的证据在 Host 侧，客户端看不到网关响应。
+ *
+ * **其余字段不做白名单过滤**：`description` / `version` / `slug` 都是展示用的，认不认识不属于
+ * Host 的判断（技能包格式只有一种，没有 MCP 那种「transport / auth.kind 认不认识」的开放维度）。
+ */
+function normalizeAssignment(raw, log) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const assignmentId = textOrUndefined(record['assignmentId']);
+    const skillName = textOrUndefined(record['skillName']);
+    const contentSha256 = textOrUndefined(record['contentSha256']);
+    if (assignmentId === undefined || skillName === undefined || contentSha256 === undefined) {
+        log?.('hiwork-core: 技能清单里有一条结构不完整的分配，已跳过');
+        return undefined;
+    }
+    const revision = record['revision'];
+    const sizeBytes = record['sizeBytes'];
+    return {
+        assignmentId,
+        revision: typeof revision === 'number' && Number.isFinite(revision) ? revision : 0,
+        slug: textOrUndefined(record['slug']) ?? skillName,
+        displayName: textOrUndefined(record['displayName']) ?? skillName,
+        skillName,
+        description: textOrUndefined(record['description']) ?? '',
+        contentSha256,
+        sizeBytes: typeof sizeBytes === 'number' && Number.isFinite(sizeBytes) ? sizeBytes : 0,
+        version: textOrUndefined(record['version']) ?? '',
+        updatedAt: textOrUndefined(record['updatedAt']) ?? '',
+    };
+}
+/** 任意异常 → 可展示的失败（网关 code 透传，message 消毒；其余收敛为通用失败）。 */
+function failureOf(error) {
+    if (error instanceof ManagedSkillsRequestError)
+        return { code: error.code, message: error.message, details: {} };
+    if (error instanceof GatewayError) {
+        return { code: error.code, message: displayManagedSkillsMessage(error.code, error.message), details: {} };
+    }
+    return { code: 'internal', message: MANAGED_SKILLS_GENERIC_FAILURE_MESSAGE, details: {} };
+}
+/** 会话 cookie 规范化：空串与 undefined 同义（都是「当前没有会话」），与 `resolveSession` 的口径一致。 */
+function normalizeSession(sessionCookie) {
+    return sessionCookie === undefined || sessionCookie === '' ? undefined : sessionCookie;
+}
+/**
+ * 清单缓存：**只有成功响应才覆写**，失败只记原因；且缓存**按会话绑定**（见 {@link bindSession}）。
+ *
+ * 「成功」的判据里含**响应形状**：200 但响应不是「带数组 `assignments` 的对象」按**取数失败**
+ * 处理（见 {@link ManagedSkillsStore.fetchOnce}）——那种响应是中间层给的，不是服务端说「你没有
+ * 技能」，把它当成空清单会让客户端把本地受管技能全删。
+ *
+ * 进程内的（不落盘）是有意的：清单是「服务端此刻认什么」的投影，跨重启的旧清单没有任何价值
+ * ——重启后客户端会立刻同步一次，拿到新的比拿到旧的更安全；而且**绝不落盘**这条还保证了
+ * 「本地磁盘上不存在一份可能被误当成事实的旧清单」（受管记录归 hiwork-capabilities 的
+ * `hiwork_skills` 域，见 spec §4.3）。
+ */
+export class ManagedSkillsStore {
+    deps;
+    now;
+    cached;
+    lastError;
+    /** 产生 `cached` 的那个会话 cookie（只在内存里）。会话绑定的全部依据就是它。 */
+    cachedSession;
+    /**
+     * 在飞请求连同它所用的会话一起记账：并发合并**只允许发生在同一会话内**。
+     * 合并跨会话等于把 A 那次拉取的结果交给 B——`refresh` 是客户端唯一被允许用来删本地技能的那条
+     * 路（spec §6 的唯一安全不变量），这条缝不能留。
+     */
+    inFlight;
+    constructor(deps, now = () => Date.now()) {
+        this.deps = deps;
+        this.now = now;
+    }
+    /**
+     * 当前缓存（同步读，不发请求）。从没成功过返回 undefined；
+     * 最近一次失败会以 `stale + lastError` 标注在上一次成功的结果上。
+     *
+     * ⚠️ **本方法不做会话绑定**——它是 spec §4.5 冻结的同步读，而当前会话只能异步解析（见
+     * {@link peekForCurrentSession}），同步函数里根本判不了「这份缓存还算不算我的」。
+     * 所以模块内唯一的正确用法是：先 `await store.peekForCurrentSession()`，再（或由它内部）`peek()`。
+     * 直接调 `peek()` 只适合诊断与测试断言内存状态。
+     */
+    peek() {
+        if (this.cached === undefined)
+            return undefined;
+        return this.lastError === undefined
+            ? this.cached
+            : { ...this.cached, stale: true, lastError: this.lastError };
+    }
+    /**
+     * 「当前会话下的缓存」= 解析当前会话 → 剪枝 → {@link peek}。
+     *
+     * 为什么比对写在**这里**而不是 `peek()` 里：`peek()` 是 spec §4.5 冻结的**同步**接口，而
+     * 「当前是谁」只有 `deps.resolveSession()` 异步拿得到。两者凑不到一个函数里，于是分工只能是
+     * 「async 的一侧先绑会话，sync 的 `peek()` 再读」。这是本文件里唯一一处 async 前置步骤，
+     * 端点实现（`handleManagedSkillsEndpoint`）必须走它、不许绕过。
+     */
+    async peekForCurrentSession() {
+        this.bindSession(normalizeSession(await this.deps.resolveSession()));
+        return this.peek();
+    }
+    /**
+     * 会话绑定：缓存只属于产生它的那个会话；当前会话不是它（含**当前没有会话**）→ 立刻丢弃。
+     *
+     * 这是刻意与 `src/managed-mcp.ts` **不同**的一处，**不许**为了「两半对齐」改回去：
+     *  - 技能这半的 {@link clear} 是 spec §4.5 冻结要求提供的接口，却**没有任何调用方**——端点白名单
+     *    只有 `snapshot`/`refresh`/`package`，客户端够不到 Host 的内存，Host 自己也没有登出钩子；
+     *    而「靠一个没人调的钩子保证安全」正是**已经失败过一次**的做法（MCP 那条链路里同样的
+     *    `clear()` 也悬着），不能把安全不变量挂在它上面。
+     *  - 绑会话**自带**：不依赖任何调用方、不依赖谁记得清缓存，且方向更严——登出后（当前会话为空）
+     *    与换账号后都不会再吐出上一个人的清单。更严在这里恒等于更安全。
+     *
+     * 它也**不**触碰「失败不覆写缓存」那条铁律：剪枝的触发条件是**会话变了**，不是「这一次拉取
+     * 失败了」。失败路径仍然原样保留本会话上一次成功的清单（`stale + lastError`）。
+     */
+    bindSession(current) {
+        if (current === this.cachedSession)
+            return;
+        this.cached = undefined;
+        this.cachedSession = undefined;
+        // 失败记录也是**按会话的**：换了人（或登出）之后，上一个人的 lastError 与这一份都不该
+        // 继续挂在账上——否则新的 `snapshot` 会把别人的失败当作自己的「最近一次失败」展示。
+        this.lastError = undefined;
+    }
+    /**
+     * 去网关拉一次清单并更新缓存。失败时抛异常，且**本会话的缓存原样保留**。
+     *
+     * 并发调用合并成一次请求：后台预热与客户端手动同步撞在一起时不必打两遍网关。
+     * 合并**只在同一会话内**——两个会话合并到一起，就等于把 A 的结果发给 B。
+     */
+    async load() {
+        const session = normalizeSession(await this.deps.resolveSession());
+        const inFlight = this.inFlight;
+        if (inFlight !== undefined && inFlight.session === session)
+            return await inFlight.task;
+        const task = this.fetchOnce(session);
+        this.inFlight = { session, task };
+        try {
+            return await task;
+        }
+        finally {
+            // 只有自己那次还在账上才清：更晚发起的（另一个会话的）请求不该被这一笔收尾抹掉。
+            if (this.inFlight?.task === task)
+                this.inFlight = undefined;
+        }
+    }
+    /**
+     * 清空内存清单（登出 / 换账号调用）。
+     *
+     * ⚠️ **当前没有任何调用方**：这是 spec §4.5 冻结要求提供的接口（客户端半边的同名方法有调用方，
+     * Host 这半没有），而它的用途已经被**会话绑定**覆盖——缓存按会话剪枝，登出 / 换账号后再也吐不出
+     * 上一个人的清单（见 {@link bindSession}）。保留它是为了不改冻结接口；真要删得先改 spec §4.5。
+     * 冻结接口里的成员不要悄悄删掉，哪怕它暂时是死的。
+     */
+    clear() {
+        this.cached = undefined;
+        this.lastError = undefined;
+        this.cachedSession = undefined;
+    }
+    async fetchOnce(sessionCookie) {
+        try {
+            if (sessionCookie === undefined) {
+                throw new GatewayError('SESSION_EXPIRED', MANAGED_SKILLS_SESSION_EXPIRED_MESSAGE);
+            }
+            const gateway = this.deps.gateway();
+            if (gateway === undefined) {
+                throw new GatewayError('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+            }
+            const view = await gateway.getMySkillAssignments(sessionCookie);
+            // 200 + 能解析的 JSON，但**不是「带数组 assignments 的对象」**⇒ 按取数失败处理，绝不
+            // 当成「成功拉到的空清单」。这类响应只可能来自夹在中间的层（反代维护页 / SSO 门户 /
+            // 任何在 200 上回自己那份 JSON 的东西）——服务端这条端点的 200 形状是冻结契约（spec §4.1）。
+            // 读成空清单就是灾难：客户端据此把本地受管技能**全删**（spec §6 的唯一安全不变量）。
+            // 逐条 `normalizeAssignment` 的容错不在此列（丢一条坏**条目**是收紧方向），这里丢的是整份响应。
+            if (typeof view !== 'object' || view === null || !Array.isArray(view.assignments)) {
+                this.deps.log?.('hiwork-core: 技能清单响应不是带 assignments 数组的对象（可能的中间层），按取数失败处理');
+                throw new GatewayError('GATEWAY_UNREACHABLE', MANAGED_SKILLS_GENERIC_FAILURE_MESSAGE);
+            }
+            const assignments = [];
+            for (const item of view.assignments) {
+                const normalized = normalizeAssignment(item, this.deps.log);
+                if (normalized !== undefined)
+                    assignments.push(normalized);
+            }
+            const snapshot = {
+                revision: typeof view.revision === 'number' && Number.isFinite(view.revision) ? view.revision : 0,
+                fetchedAt: new Date(this.now()).toISOString(),
+                assignments,
+                stale: false,
+            };
+            // 成功才覆写，并**连同产生它的会话**一起记账：会话绑定（bindSession）之后要靠这一行。
+            // 迟到的写回（旧会话的请求在换账号之后才返回）不构成漏洞：它只会把 cachedSession 记回旧会话，
+            // 而任何一次读取都要先过 bindSession——不匹配就当场丢弃，永远到不了调用方手里。
+            this.cached = snapshot;
+            this.cachedSession = sessionCookie;
+            this.lastError = undefined;
+            return snapshot;
+        }
+        catch (error) {
+            this.lastError = failureOf(error);
+            throw error;
+        }
+    }
+}
+/** 取消判定（用函数包一层，避免 TS 把属性窄化固化到 `await` 之后）。 */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export async function handleManagedSkillsEndpoint(endpoint, rawPayload, deps, store, signal) {
+    try {
+        if (isAborted(signal))
+            return failure('cancelled', '技能清单请求已取消。');
+        if (!isManagedSkillsRpcEndpoint(endpoint)) {
+            throw new ManagedSkillsRequestError('bad-request', `未知的技能清单端点 '${endpoint}'`);
+        }
+        const payload = parseManagedSkillsPayload(endpoint, rawPayload);
+        if (endpoint === 'package') {
+            const assignmentId = payload.assignmentId;
+            if (assignmentId === undefined)
+                throw new ManagedSkillsRequestError('bad-request', '取技能包请求缺少 assignmentId。');
+            // 包体**不进缓存**：它是一条分配的内容，不是「服务端此刻认什么」；缓存下来等于把
+            // 每次同步装过的所有技能包都钉在 Host 内存里（base64 后每条约 5 MiB）。
+            return await handlePackage(assignmentId, deps, signal);
+        }
+        // snapshot：有缓存就直接给（可能是 stale），冷启动才走一次网络。
+        // 注意这里**没有**直接用 `store.peek()`：spec §4.5 的 `peek()` 是同步读、拿不到当前会话，
+        // 而缓存必须按会话绑定（登出 / 换账号后不许再吐出上一个人的清单），所以走 async 前置
+        // `peekForCurrentSession()`——它先解析当前 cookie 做一次同步剪枝，再返回缓存。两个端点都走它，
+        // 于是 `refresh` 也会顺手剪掉已经不匹配的缓存（拉失败时也不会留着别人的旧清单）。
+        const cached = await store.peekForCurrentSession();
+        if (endpoint === 'snapshot' && cached !== undefined)
+            return { ok: true, value: cached };
+        return { ok: true, value: await store.load() };
+    }
+    catch (error) {
+        deps.log?.(`hiwork-core: 技能清单 RPC '${endpoint}' 失败（${error instanceof Error ? error.name : typeof error}）`);
+        return { ok: false, error: failureOf(error) };
+    }
+}
+/**
+ * `package`：把某一条分配的 ZIP 字节 base64 后交给客户端。
+ *
+ * 分工：**只有 Host 拿得到字节**（会话 cookie 在这里，且绝不外流），客户端拿到的是 base64
+ * 字符串，由它自己解码、自己算 sha256 与清单里的 `contentSha256` 比对（spec §6 的完整性那一行）。
+ * 校验失败的那条不落盘、报 `failed`，旧版本照常可用。
+ */
+async function handlePackage(assignmentId, deps, signal) {
+    const sessionCookie = await deps.resolveSession();
+    if (sessionCookie === undefined || sessionCookie === '') {
+        return failure('SESSION_EXPIRED', MANAGED_SKILLS_SESSION_EXPIRED_MESSAGE);
+    }
+    const gateway = deps.gateway();
+    if (gateway === undefined) {
+        return failure('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+    }
+    if (isAborted(signal))
+        return failure('cancelled', '技能清单请求已取消。');
+    const pkg = await gateway.getMySkillPackage(sessionCookie, assignmentId);
+    const bytes = pkg?.bytes;
+    const skillName = textOrUndefined(pkg?.skillName);
+    const contentSha256 = textOrUndefined(pkg?.contentSha256);
+    // 一个空包体或没有身份的包体都不是技能包：在 Host 就拦住，别让它变成客户端那边一次
+    // 看不懂的「哈希对不上」。这两种情况只可能来自服务端数据问题，所以收敛成通用失败。
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0 || skillName === undefined || contentSha256 === undefined) {
+        deps.log?.('hiwork-core: 取技能包收到无效响应（缺 skillName / contentSha256 或空包体）');
+        return failure('internal', MANAGED_SKILLS_GENERIC_FAILURE_MESSAGE);
+    }
+    // 大小闸：base64 之后约 5.3 MiB，是本频道唯一一次大对象传输（spec §8 R8）。
+    if (bytes.byteLength > MAX_MANAGED_SKILL_ARCHIVE_BYTES) {
+        deps.log?.('hiwork-core: 技能包超过大小上限，已拒绝搬运');
+        return failure(MANAGED_SKILLS_PACKAGE_TOO_LARGE_CODE, MANAGED_SKILLS_PACKAGE_TOO_LARGE_MESSAGE);
+    }
+    return {
+        ok: true,
+        value: {
+            assignmentId,
+            skillName,
+            contentSha256,
+            // Host 半边只跑在 Node 侧（`tsconfig.build.json` 排除 `src/client/**`，client bundle
+            // 不 import 本文件），所以直接用 Buffer；客户端那半边的解码在 Task 11 的文件里。
+            archiveBase64: Buffer.from(bytes).toString('base64'),
+        },
+    };
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * 注册 `/hiwork-managed-skills` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export function registerManagedSkillsRpc(ctx, deps, store) {
+    const handler = (endpoint, payload, signal) => handleManagedSkillsEndpoint(endpoint, payload, deps, store, signal);
+    const remove = ctx.connection.rpc.handle(MANAGED_SKILLS_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => { await remove(); };
+}

package/lib/office-credentials.js

@@ -0,0 +1,113 @@
+/**
+ * 网关集中下发的 OnlyOffice 集成凭据（host 侧 cordis 服务 `hiworkOfficeCredentials`）。
+ *
+ * 背景：hiwork-office 插件原先要求每台终端在设置里手工粘贴 Document Server 的 JWT
+ * 密钥——密钥靠人肉传播（聊天记录/文档里转发）、轮换无通道、谁在用无法审计
+ * （2026-09-16 查证：DS 侧密钥只是部署机 `.env` 里的一行 `JWT_SECRET`，没有任何管理
+ * 能力）。本模块把「密钥从哪来」收敛到网关：hiwork-office 的 Host 半边按登录态经本
+ * 服务取 `{ documentServerUrl, jwtSecret }`，终端零配置。
+ *
+ * 设计要点（与 `src/managed-mcp.ts` / `src/daily-rpc.ts` 同构）：
+ *  - **网关会话 cookie 绝不离开 Host**：只在 `resolveSession()` 内部出现；
+ *  - **本模块不缓存**：调用方（hiwork-office）按自己的 TTL 决定何时取——密钥轮换后
+ *    它的下一次拉取自然拿到新值，不存在两层缓存互相打架；
+ *  - **失败不抛异常**，返回稳定 `{ ok: false, code, message }`：message 经消毒，
+ *    不含 baseURL / HTTP 状态码等实现细节，可直接展示给用户；
+ *  - 服务经 `ctx.provide` 提供给同进程的其他插件，hiwork-office 用 `ctx.get` 探测
+ *    （老 core 上它是 undefined，插件回退本地手工配置——独立安装场景）。
+ *
+ * 这是「密钥下发」的 MVP（方案一）：密钥仍随登录态落到终端，但不再靠人肉传播。
+ * 后续演进（方案二：网关代签）不改变本服务的**形状**——消费方拿到的仍是一份
+ * 可用的集成配置，只是内容可能从共享密钥换成短期凭证，两端无需改结构。
+ *
+ * 本模块不 import cordis 运行时：provide 走结构化的 {@link OfficeCredentialsContext}
+ * 端口，调用方（index.ts）传真实 ctx；单测直接伪造。
+ */
+import { GatewayError } from "./ai-router-client.js";
+/** cordis 服务名（hiwork-office 的 Host 半边按此名探测）。 */
+export const OFFICE_CREDENTIALS_SERVICE = 'hiworkOfficeCredentials';
+/** 各稳定错误码的用户可见文案（网关 message 含实现细节时用它兜底）。 */
+const OFFICE_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: '登录状态已过期，请重新登录',
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    OFFICE_NOT_CONFIGURED: '本部署尚未配置 HiWork Office 文档办公集成，请联系管理员',
+};
+/** 通用失败文案：不暴露任何网关细节。 */
+export const OFFICE_CREDENTIALS_GENERIC_FAILURE_MESSAGE = 'HiWork Office 集成配置暂时无法获取，请稍后重试';
+/** 未登录 / 会话失效的统一文案（与用量、每日一句、MCP 三个频道同口径）。 */
+export const OFFICE_CREDENTIALS_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+/**
+ * 网关 message 消毒（与 `usage-rpc.ts` 的 `displayGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export function displayOfficeGatewayMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return OFFICE_MESSAGE_FALLBACK[code] ?? OFFICE_CREDENTIALS_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_MESSAGE_FALLBACK[code] ?? OFFICE_CREDENTIALS_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+/**
+ * 凭据取数（无缓存；缓存策略是消费方的事）。
+ */
+export class OfficeCredentialsBroker {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async resolve() {
+        try {
+            const sessionCookie = await this.deps.resolveSession();
+            if (sessionCookie === undefined || sessionCookie === '') {
+                return { ok: false, code: 'SESSION_EXPIRED', message: OFFICE_CREDENTIALS_SESSION_EXPIRED_MESSAGE };
+            }
+            const gateway = this.deps.gateway();
+            if (gateway === undefined) {
+                return {
+                    ok: false,
+                    code: 'GATEWAY_UNREACHABLE',
+                    message: '网关地址未配置，请先在「网关模型」里完成登录',
+                };
+            }
+            const view = await gateway.getMyOfficeConfig(sessionCookie);
+            const documentServerUrl = typeof view?.documentServerUrl === 'string' ? view.documentServerUrl.trim() : '';
+            const jwtSecret = typeof view?.jwtSecret === 'string' ? view.jwtSecret.trim() : '';
+            if (documentServerUrl === '' || jwtSecret === '') {
+                // 网关 200 却缺字段 = 契约破坏：按「不可用」处理，绝不把半份配置交给终端。
+                this.deps.log?.('hiwork-core: 网关返回的 office-config 不完整（缺 documentServerUrl 或 jwtSecret）');
+                return { ok: false, code: 'GATEWAY_UNREACHABLE', message: OFFICE_CREDENTIALS_GENERIC_FAILURE_MESSAGE };
+            }
+            return {
+                ok: true,
+                value: {
+                    documentServerUrl,
+                    jwtSecret,
+                    fetchedAt: (this.deps.now?.() ?? new Date()).toISOString(),
+                    relayEnabled: view?.relayEnabled === true,
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof GatewayError) {
+                // code 原样透传（稳定契约），message 消毒后再交给消费方。
+                return { ok: false, code: error.code, message: displayOfficeGatewayMessage(error.code, error.message) };
+            }
+            this.deps.log?.(`hiwork-core: HiWork Office 凭据获取失败（${error instanceof Error ? error.name : typeof error}）`);
+            return { ok: false, code: 'internal', message: OFFICE_CREDENTIALS_GENERIC_FAILURE_MESSAGE };
+        }
+    }
+}
+/**
+ * 提供 host 侧服务 `hiworkOfficeCredentials`；返回 disposer（交给 `ctx.effect` 管理
+ * 生命周期，插件卸载时服务随 fiber 一并注销）。
+ */
+export function provideOfficeCredentials(ctx, deps) {
+    const service = new OfficeCredentialsBroker(deps);
+    const dispose = ctx.provide(OFFICE_CREDENTIALS_SERVICE, service);
+    return typeof dispose === 'function' ? dispose : () => { };
+}