hiwork-core 0.0.11 → 0.0.17

package/README.md

@@ -130,6 +130,12 @@ ctx.inject(['hiworkFeatureCenter'], (scope) => {
 - [src/client/feature-center.ts](src/client/feature-center.ts)：侧栏菜单注入 + 中央区 takeover。
 - [src/client/contracts.ts](src/client/contracts.ts)：业务插件可见的 client 面与服务名。
 - [src/orchestration.ts](src/orchestration.ts)：登录后模型供给编排（拉 Key、写路由、热重载）。
+- [src/office-credentials.ts](src/office-credentials.ts)：OnlyOffice 集成凭据的 host 侧服务
+  （`hiworkOfficeCredentials`）——hiwork-office 按登录态经它取 Document Server 地址与共享
+  JWT 密钥（网关 `GET /api/me/office-config`），终端零配置；网关会话 cookie 不出 Host。
+- [src/office-relay.ts](src/office-relay.ts)：文档中继的 host 侧服务（`hiworkOfficeRelay`）——
+  跨 NAT 的在线编辑：插件把文档暂存到 DS 能访问的服务器侧（上传/轮询/取回/关闭），
+  用户侧不再需要入向可达性；同样只在 Host 持 cookie、失败用稳定信封。
 - [src/default-model.ts](src/default-model.ts)：供给成功后校正 `agent-default-model`（默认模型落点）。
 - [src/client/login-gate.tsx](src/client/login-gate.tsx)：全屏登录门禁页。
 - [src/client/section.tsx](src/client/section.tsx)：设置页「AI Router 网关」卡片。

package/lib/ai-router-client.js

@@ -21,6 +21,41 @@ const ME_DAILY_QUOTE_RANDOM_PATH = '/api/me/daily-quote/random';
  */
 const ME_MCP_ASSIGNMENTS_PATH = '/api/me/mcp-assignments';
 const ME_MCP_ASSERTIONS_PATH = '/api/me/mcp-assertions';
+/**
+ * 技能分发的自助端点（管理员在 ai-hub 登记技能、下发给全员或某人后，员工端从这里拉清单与包体）。
+ * 与 MCP 那两条同款：都在网关 `/api/me` 会话组下，鉴权是 `SessionAuth`（只读 Cookie）。
+ *
+ * 契约见 ai-hub 的 spec `docs/superpowers/specs/2026-09-17-skill-distribution-design.md`
+ * §4.1（清单）/ §4.2（包体）。技能链路比 MCP 短一整段：**没有任何凭据**——清单里只有元数据，
+ * 包体是纯文件字节，不存在换令牌那一跳，所以也没有断言 / JWKS 相关端点。
+ *
+ * 清单与包体分成两条路径是刻意的（§4.1）：清单必须小到能每 30 分钟拉一次、能随手打进日志比对，
+ * 包体则只在真要装/更新时才取（`package` 是唯一搬大字节的那条，见 src/managed-skills.ts）。
+ */
+const ME_SKILL_ASSIGNMENTS_PATH = '/api/me/skill-assignments';
+const ME_SKILL_PACKAGES_PATH = '/api/me/skill-packages';
+/**
+ * 工作台应用清单的自助端点：管理员在网关管理端登记并分配给当前账号的应用，一条 GET 全量下发。
+ *
+ * 契约见 spec `docs/superpowers/specs/2026-09-17-hiwork-workbench-design.md` §4.1（本仓是消费方，
+ * 权威定义在 ai-gateway 侧）。与 MCP / 技能那两组同款：网关 `/api/me` 会话组、`SessionAuth`
+ * 只读 Cookie、响应里**没有任何令牌**（应用后端怎么鉴权由网关代理时附身份头决定，客户端不见凭证）。
+ *
+ * 与前面几组不同的一处：**本端点会回 404**——网关没配置工作台时这条路由压根不注册
+ * （spec §10 的降级矩阵），所以 404 在 {@link AiRouterClient.getMyWorkbenchApps} 里有独立语义。
+ */
+const ME_WORKBENCH_APPS_PATH = '/api/me/workbench-apps';
+/**
+ * 文档办公（OnlyOffice）集成下发：网关集中持有共享 JWT 密钥，员工端经登录态拉取。
+ * 与 MCP 清单同理，本端点只看会话——没有被分配虚拟 Key 的账号照样拿得到。
+ */
+const ME_OFFICE_CONFIG_PATH = '/api/me/office-config';
+/**
+ * 文档中继（跨 NAT 的在线编辑）：桌面端上传 / 轮询 / 取回 / 关闭。
+ * 四条都在网关 `/api/me` 会话组下；DS 侧的那两条（拉文档、回调）由网关直接对 DS 签发，
+ * 桌面端永远不接触。
+ */
+const ME_OFFICE_RELAY_DOCUMENTS_PATH = '/api/me/office-relay/documents';
 /** 授权请求默认值：桌面端 client_id 与自定义协议回调地址（网关侧精确匹配）。 */
 const DEFAULT_CLIENT_ID = 'hiwork-desktop';
 const DEFAULT_REDIRECT_URI = 'hiwork://auth/callback';
@@ -233,6 +268,109 @@ export class AiRouterClient {
             throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
         return await parseMeJson(res);
     }
+    /**
+     * POST /api/me/office-relay/documents：上传文档字节到中继。
+     *
+     * 文件名走 `X-Office-Document-Name` 头（HTTP 头只能带 ASCII，用 encodeURIComponent
+     * 编码；网关侧 PathUnescape 解码）。状态码映射成稳定 code，供插件层给用户文案。
+     */
+    async createOfficeRelayDocument(sessionCookie, name, bytes, mode) {
+        const res = await this.requestOrUnreachable(ME_OFFICE_RELAY_DOCUMENTS_PATH, {
+            method: 'POST',
+            sessionCookie,
+            rawBody: bytes,
+            headers: {
+                'content-type': 'application/octet-stream',
+                'x-office-document-name': encodeURIComponent(name),
+                // 打开模式只影响网关侧的 document key 变体（view / edit 不能共用 DS 会话）
+                ...(mode === undefined ? {} : { 'x-office-document-mode': mode }),
+            },
+        });
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        if (res.status === 404) {
+            throw new GatewayError('RELAY_DISABLED', '本部署未启用文档中继，请联系管理员', 404);
+        }
+        if (res.status === 413)
+            throw new GatewayError('RELAY_TOO_LARGE', '文档超过在线编辑的大小上限', 413);
+        if (res.status === 415)
+            throw new GatewayError('RELAY_EXTENSION', '该文档类型不支持在线编辑', 415);
+        if (res.status === 429)
+            throw new GatewayError('RELAY_QUOTA', '同时打开的编辑会话过多，请稍后再试', 429);
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        return await parseMeJson(res);
+    }
+    /** GET /api/me/office-relay/documents/:id：轮询状态。 */
+    async getOfficeRelayStatus(sessionCookie, id) {
+        const res = await this.requestOrUnreachable(`${ME_OFFICE_RELAY_DOCUMENTS_PATH}/${encodeURIComponent(id)}`, {
+            method: 'GET',
+            sessionCookie,
+        });
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        if (res.status === 404)
+            throw new GatewayError('RELAY_DISABLED', '本部署未启用文档中继，请联系管理员', 404);
+        if (res.status === 410)
+            throw new GatewayError('RELAY_EXPIRED', '编辑会话已过期，请重新打开文档', 410);
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        return await parseMeJson(res);
+    }
+    /**
+     * GET /api/me/office-relay/documents/:id/content[?v=N]：取回当前版本字节。
+     * 204 表示"你手里的版本已是最新"（不是错误）。
+     */
+    async getOfficeRelayContent(sessionCookie, id, revision) {
+        const query = revision === undefined ? '' : `?v=${revision}`;
+        const res = await this.requestOrUnreachable(`${ME_OFFICE_RELAY_DOCUMENTS_PATH}/${encodeURIComponent(id)}/content${query}`, { method: 'GET', sessionCookie });
+        if (res.status === 204) {
+            return { notModified: true, revision: revision ?? 0 };
+        }
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        if (res.status === 404)
+            throw new GatewayError('RELAY_DISABLED', '本部署未启用文档中继，请联系管理员', 404);
+        if (res.status === 410)
+            throw new GatewayError('RELAY_EXPIRED', '编辑会话已过期，请重新打开文档', 410);
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        // 版本号以轮询到的状态为准；这里回 -1 让调用方用 status 的值覆盖
+        return { notModified: false, revision: -1, bytes };
+    }
+    /** DELETE /api/me/office-relay/documents/:id：关闭会话（幂等）。 */
+    async closeOfficeRelayDocument(sessionCookie, id) {
+        const res = await this.requestOrUnreachable(`${ME_OFFICE_RELAY_DOCUMENTS_PATH}/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            sessionCookie,
+        });
+        if (res.status === 204 || res.status === 404 || res.status === 410)
+            return; // 幂等：没了也算关掉
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+    }
+    /**
+     * GET /api/me/office-config：本部署 OnlyOffice 集成（Document Server 地址 + 共享 JWT 密钥）。
+     *
+     * 与 {@link getMyMcpAssignments} 同样的理由不复用 `getMeJson`：那条路径把 403 映射成
+     * `NO_KEY_ASSIGNED`，而本端点只看会话（分集成配置与分 Key 是两件事）。503 是
+     * 「部署未配置」的稳定信号，单独映射——消费方（hiwork-office）据此提示联系管理员
+     * 并回退本地手工配置，而不是报一句含糊的「网关不可达」。
+     */
+    async getMyOfficeConfig(sessionCookie) {
+        const res = await this.requestOrUnreachable(ME_OFFICE_CONFIG_PATH, { method: 'GET', sessionCookie });
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        if (res.status === 503) {
+            throw new GatewayError('OFFICE_NOT_CONFIGURED', '本部署尚未配置 HiWork Office 文档办公集成，请联系管理员', 503);
+        }
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        return await parseMeJson(res);
+    }
     /**
      * POST /api/me/mcp-assertions：为某条分配签一张 120 秒断言。
      *
@@ -263,6 +401,118 @@ export class AiRouterClient {
             throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
         return await parseMeJson(res);
     }
+    /**
+     * 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`）——那里才决定「这一份算不算成功拉到的清单」。
+     */
+    async getMySkillAssignments(sessionCookie) {
+        const res = await this.requestOrUnreachable(ME_SKILL_ASSIGNMENTS_PATH, { method: 'GET', sessionCookie });
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        // 403 / 404 / 503 / 5xx / 反代错误页一律「网关不可达」：见方法注释里的逐条理由。
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        return await parseMeJson(res);
+    }
+    /**
+     * 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，浏览器侧永远拿不到字节。
+     */
+    async getMySkillPackage(sessionCookie, assignmentId) {
+        const res = await this.requestOrUnreachable(`${ME_SKILL_PACKAGES_PATH}/${encodeURIComponent(assignmentId)}`, { method: 'GET', sessionCookie });
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        // 这条分配不在这个账号名下（已被撤销 / 从未属于它）：客户端据此停止重试，并把这句话显示出来。
+        // 它**不是**删除本地受管技能的依据（见方法注释末段）。
+        if (res.status === 404) {
+            throw new GatewayError('SKILL_ASSIGNMENT_GONE', '这条分配已失效，稍后同步会重新核对', 404);
+        }
+        // 部署未启用技能下发：与 MCP 的 503 同款单独映射，别混进「网关不可达」。
+        // ⚠️ 当前没有生产者（见方法注释末段的事实核对）：这一支是保留下来的防御性映射。
+        if (res.status === 503) {
+            throw new GatewayError('SKILL_DISTRIBUTION_DISABLED', '本部署未启用技能下发，请联系管理员', 503);
+        }
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        return {
+            skillName: res.headers.get('x-hiwork-skill-name') ?? '',
+            contentSha256: res.headers.get('x-hiwork-content-sha256') ?? '',
+            bytes: new Uint8Array(await res.arrayBuffer()),
+        };
+    }
+    /**
+     * 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`），
+     * 那里才决定「这一份算不算成功拉到的清单」。
+     */
+    async getMyWorkbenchApps(sessionCookie) {
+        const res = await this.requestOrUnreachable(ME_WORKBENCH_APPS_PATH, { method: 'GET', sessionCookie });
+        if (res.status === 401)
+            throw new GatewayError('SESSION_EXPIRED', '网关会话已过期，请重新登录', 401);
+        if (res.status === 404)
+            throw new GatewayError('WORKBENCH_DISABLED', '本部署未启用工作台，请联系管理员', 404);
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        return await parseMeJson(res);
+    }
     /**
      * /api/me 自助端点的 GET 公共路径：网络异常 → GATEWAY_UNREACHABLE，
      * 401/403/400 映射为稳定 code，响应体非 JSON 时不把原文带进异常。
@@ -306,7 +556,11 @@ export class AiRouterClient {
             headers,
             signal: AbortSignal.timeout(this.timeoutMs),
         };
-        if (opts.body !== undefined)
+        // Uint8Array 作为 BodyInit 需要 ArrayBuffer 视图（TS DOM 类型要求）
+        if (opts.rawBody !== undefined) {
+            init.body = opts.rawBody.buffer.slice(opts.rawBody.byteOffset, opts.rawBody.byteOffset + opts.rawBody.byteLength);
+        }
+        else if (opts.body !== undefined)
             init.body = JSON.stringify(opts.body);
         return fetch(`${this.baseURL}${path}`, init);
     }