hiwork-core 0.0.24 → 0.0.29

package/lib/knowledge-config.js

@@ -0,0 +1,273 @@
+/**
+ * 知识库配置下发的只读 host 服务（`hiworkKnowledge`）。
+ *
+ * 背景：HiWork 给员工接了一套知识库（WeKnora）。规范是**员工零操作**——知识库的
+ * 服务地址、凭据、问答 Agent ID、chat 模型 ID **全部由网关下发**，插件的设置页
+ * 不得让员工填任何技术字段。本模块是这条链中间的那一环：
+ *
+ * ```
+ * hiwork-admin  GET /api/me/knowledge-config   ← 网关侧（纯读：无 DB、无上游调用）
+ *    ↑ 本文件（hiwork-core，用登录会话调它）
+ * hiwork-knowledge ctx.get('hiworkKnowledge').config()   ← 插件侧
+ * ```
+ *
+ * 形状来源（逐字对照）：`src/memory-config.ts`（同族先例，同样是「网关配置下发的只读
+ * 面」）。与它的差异**只有三处**：
+ *  ① 字段集多 `agentId` / `chatModelId`（问答链路需要）；
+ *  ② 必填判定只看 `base_url` + `api_key`：**缺 agentId / chatModelId 不阻止下发**
+ *     （返回 `''`，检索与浏览仍可用），只有两个必填项缺失才判整份不可用；
+ *  ③ 状态码映射里**保留** `504 → unreachable`，但它是**防御性分类**：本端点不打上游，
+ *     网关不会回 504（网关侧 spec §3 D1/D5），保留这一档是为了将来换实现时不会把
+ *     「上游不可达」误读成 `error`。
+ *
+ * 不变量（与 memory 同口径，不得放宽）：
+ *  - **只读、失败不抛异常**：一律返回 `{ ok: false, reason, message }`，reason 四取值
+ *    `not-configured` / `unauthenticated` / `unreachable` / `error`。失败是**数据**而不是
+ *    异常：插件侧按 `ok` 判断，绝不会因为宿主的一次网络抖动把异常漏进会话。
+ *  - **字段名分层只在本文件做**：网关那层是 **snake_case**（`base_url` / `api_key` /
+ *    `agent_id` / `chat_model_id` / `tenant_id`，跨仓冻结契约），本文件把它转成 camelCase
+ *    的 {@link HiworkKnowledgeConfigView} 再对外暴露——插件侧**永远不感知上游命名**，
+ *    本文件是全仓**唯一**做这层转换的地方。
+ *  - **凭据只在内存里活**：`apiKey` 不写 settings、不写任何 storage、不写任何缓存文件
+ *    （与 `src/memory-config.ts` / `src/office-credentials.ts` 同口径），也**不进任何日志**
+ *    （含调试日志与错误日志）——本模块只记事件与异常**类型名**，绝不记字段值。
+ *  - **5 分钟内存缓存**：命中即不出网；`force: true` 绕过缓存（设置页「重新获取配置」与
+ *    401 自愈走这条）。缓存与**会话 cookie 绑定**：换了登录账号（登出再登入）时旧缓存
+ *    直接失效，绝不把上一个员工的配置发给下一个员工（粘错 = 串号）。
+ *  - **失败不进缓存**：拉不到时下一次调用重新出网——否则一次网关抖动会把员工锁在
+ *    「知识库不可用」里整整一个 TTL。
+ *  - **message 是给非技术员工看的中文**：不含凭据、不含 URL 原文、不含 HTTP 状态码。
+ *
+ * 服务名逐字 `hiworkKnowledge`（插件侧 spec §3 D1 对既有 spec 的一处口径修正：旧文档写的是
+ * 「Knowledge + Credentials」的拼接名，本模块下发的**不只是凭据**（还有 baseUrl、Agent ID、
+ * chat 模型 ID），故不叫 Credentials；源码里不得出现那个旧名，V3 用 grep 守着）。
+ *
+ * 本模块不 import cordis 运行时：provide 走结构化的 {@link KnowledgeConfigContext} 端口，
+ * 调用方（index.ts）传真实 ctx；单测直接伪造。
+ */
+import { PKG_VERSION } from "./version.js";
+/** cordis 服务名（hiwork-knowledge 的 Host 半边按此名 `ctx.get` 探测）。 */
+export const HIWORK_KNOWLEDGE_SERVICE = 'hiworkKnowledge';
+/** 网关侧端点（跨仓冻结；与 `/api/me/memory-config` 同一条会话鉴权）。 */
+export const ME_KNOWLEDGE_CONFIG_PATH = '/api/me/knowledge-config';
+/** 成功结果的缓存 TTL：5 分钟。 */
+export const KNOWLEDGE_CONFIG_TTL_MS = 5 * 60 * 1000;
+/** 出网超时（与 `AiRouterClient` 的缺省一致）。 */
+export const KNOWLEDGE_CONFIG_TIMEOUT_MS = 10_000;
+/**
+ * 失败文案（给非技术员工看的中文；不含凭据、URL 原文、HTTP 状态码）。
+ * 四句与插件侧 spec §4.1 / §5 逐字一致，设置页直接渲染，不得改造。
+ */
+const MESSAGE_NOT_CONFIGURED = '管理员还没开启知识库，请联系管理员开通';
+const MESSAGE_UNAUTHENTICATED = '登录状态已过期，请重新登录';
+const MESSAGE_UNREACHABLE = '知识库服务暂时不可用，请稍后重试';
+const MESSAGE_GENERIC = '知识库配置暂时无法获取，请稍后重试';
+/**
+ * 按 reason 取文案。
+ * 注：`gateway()` 返回 undefined（还没登录完 / baseURL 未配置）与网络不通归同一档
+ * `unreachable`，共用同一句——本 spec 只冻结了四句文案，不另造第五句。
+ */
+function messageFor(reason) {
+    switch (reason) {
+        case 'not-configured': return MESSAGE_NOT_CONFIGURED;
+        case 'unauthenticated': return MESSAGE_UNAUTHENTICATED;
+        case 'unreachable': return MESSAGE_UNREACHABLE;
+        case 'error': return MESSAGE_GENERIC;
+    }
+}
+/** 失败视图（**只带 reason 与 message**，绝不带半个字段）。 */
+function failure(reason, message) {
+    return { ok: false, reason, message: message ?? messageFor(reason) };
+}
+/** 裁掉两侧空白；非字符串或空白串一律视同缺省。 */
+function textOrUndefined(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    return text === '' ? undefined : text;
+}
+/**
+ * snake_case → camelCase 投影（**全仓唯一做这层转换的地方**）。
+ *
+ * 两个必需字段（`base_url` / `api_key`）任一缺失即返回 undefined：网关 200 却缺字段 =
+ * 契约破坏，宁可报「暂时无法获取」，也绝不把半份配置交给终端（半份配置的下场是插件拿
+ * 空地址去打请求，错误信息离真正的原因十万八千里）。
+ *
+ * 三个**非必需**字段（`agent_id` / `chat_model_id` / `tenant_id`）缺失 / 空白 / 形状非法
+ * 一律落成 `''`，**整份仍算下发成功**——检索与浏览不依赖它们，只有问答需要；用「问答
+ * 用不了」冒充「知识库不可用」会把员工引到错误的方向（spec §4.1 投影规则逐字）。
+ *
+ * 同时宽容接受 camelCase 别名（`baseUrl` / `apiKey` / `agentId` / `chatModelId` /
+ * `tenantId`）：两侧落地顺序不同也不炸。**写出永远是 camelCase 视图**——插件侧不感知
+ * 任何一种上游命名。
+ */
+function projectKnowledgeConfig(body) {
+    const baseUrl = textOrUndefined(body['base_url'] ?? body['baseUrl']);
+    const apiKey = textOrUndefined(body['api_key'] ?? body['apiKey']);
+    if (baseUrl === undefined || apiKey === undefined)
+        return undefined;
+    return {
+        ok: true,
+        baseUrl,
+        apiKey,
+        agentId: textOrUndefined(body['agent_id'] ?? body['agentId']) ?? '',
+        chatModelId: textOrUndefined(body['chat_model_id'] ?? body['chatModelId']) ?? '',
+        tenantId: textOrUndefined(body['tenant_id'] ?? body['tenantId']) ?? '',
+    };
+}
+/** 异常类型名（日志只记类型，不记消息，避免把凭据/URL 带进日志）。 */
+function errorName(error) {
+    return error instanceof Error ? error.name : typeof error;
+}
+/**
+ * 把「会抛错的网关实现」的稳定 code 映射成 reason。
+ *
+ * 本模块自带的出网端口（{@link createKnowledgeConfigGateway}）**从不抛错**，这一支是为了
+ * 容忍接线侧传进来的其它实现（例如将来把本端点加进 `AiRouterClient` 后直接复用
+ * `gatewayFor(baseURL)`）：按结构化 `code` 字段判别，不 import 对方的类，也不读 message
+ * （message 里可能带 URL 原文）。
+ */
+function reasonOfErrorCode(error) {
+    const code = error?.code;
+    if (typeof code !== 'string')
+        return undefined;
+    switch (code) {
+        case 'SESSION_EXPIRED': return 'unauthenticated';
+        case 'KNOWLEDGE_NOT_CONFIGURED': return 'not-configured';
+        case 'KNOWLEDGE_UNREACHABLE':
+        case 'GATEWAY_UNREACHABLE': return 'unreachable';
+        default: return undefined;
+    }
+}
+/** 非 200 状态码 → reason（逐字对应契约：401 / 503 / 504 各有确定语义）。 */
+function reasonOfStatus(status) {
+    if (status === 401)
+        return 'unauthenticated';
+    // 网关 503 `KNOWLEDGE_NOT_CONFIGURED`：管理员还没开启知识库（部署状态，不是故障）。
+    if (status === 503)
+        return 'not-configured';
+    // 504：**防御性分类**——本端点不打上游，网关不会回 504；保留它是为了将来换实现时
+    // 不会把「上游不可达」读成 error（语义上 504 就是「够不着」）。
+    if (status === 504)
+        return 'unreachable';
+    return 'error';
+}
+/** 视图投影 + 5 分钟内存缓存（无状态依赖，只有一条内存缓存）。 */
+class KnowledgeConfigProvider {
+    deps;
+    cached;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async config(opts) {
+        const force = opts?.force === true;
+        let sessionCookie;
+        try {
+            sessionCookie = await this.deps.resolveSession();
+        }
+        catch (error) {
+            // 凭据服务读取失败是宿主故障，不是「没登录」：如实报 error，不诱导用户反复重登。
+            this.deps.log?.(`hiwork-core: 知识库配置获取失败（${errorName(error)}）`);
+            return failure('error');
+        }
+        if (sessionCookie === undefined || sessionCookie === '')
+            return failure('unauthenticated');
+        if (!force) {
+            const hit = this.cached;
+            if (hit !== undefined && hit.sessionCookie === sessionCookie && this.now() - hit.at < KNOWLEDGE_CONFIG_TTL_MS) {
+                return hit.view;
+            }
+        }
+        const gateway = this.deps.gateway();
+        // 没有网关地址 = 还没完成登录（baseURL 是登录时写下的），与网络不通归同一档。
+        if (gateway === undefined)
+            return failure('unreachable');
+        let outcome;
+        try {
+            outcome = await gateway.getMyKnowledgeConfig(sessionCookie);
+        }
+        catch (error) {
+            const mapped = reasonOfErrorCode(error);
+            if (mapped !== undefined)
+                return failure(mapped);
+            this.deps.log?.(`hiwork-core: 知识库配置获取失败（${errorName(error)}）`);
+            return failure('error');
+        }
+        if (!outcome.ok) {
+            if (outcome.kind === 'network')
+                return failure('unreachable');
+            if (outcome.kind === 'http')
+                return failure(reasonOfStatus(outcome.status));
+            return failure('error');
+        }
+        const view = projectKnowledgeConfig(outcome.body);
+        if (view === undefined) {
+            // 只记事件与字段名，不记任何值（响应体里带凭据）。
+            this.deps.log?.('hiwork-core: 网关返回的 knowledge-config 不完整（缺 base_url / api_key 之一）');
+            return failure('error');
+        }
+        // 只缓存成功结果：拉不到时下一次调用重新出网（一次抖动不该锁住一个 TTL）。
+        this.cached = { sessionCookie, view, at: this.now() };
+        return view;
+    }
+    now() {
+        return (this.deps.now ?? Date.now)();
+    }
+}
+/**
+ * 提供 host 侧服务 `hiworkKnowledge`；返回 disposer（交给 `ctx.effect` 管理生命周期，
+ * 插件卸载时服务随 fiber 一并注销）。
+ */
+export function provideKnowledgeConfig(ctx, deps) {
+    const service = new KnowledgeConfigProvider(deps);
+    const dispose = ctx.provide(HIWORK_KNOWLEDGE_SERVICE, service);
+    return typeof dispose === 'function' ? dispose : () => { };
+}
+/**
+ * 本端点的出网实现（形状与 `AiRouterClient` 的 `request()` 同款：user-agent 带包版本、
+ * 会话 cookie 走 `cookie` 头、超时用 `AbortSignal.timeout`）。
+ *
+ * **不新造鉴权**：只复用 Host 侧已有的登录会话 cookie（由 `resolveSession` 从凭据库取），
+ * 没有任何密钥/令牌在这一层生成或保存。
+ *
+ * **永不抛异常、绝不回显响应原文**：失败收敛成 {@link KnowledgeConfigOutcome}，日志与
+ * 异常里都不会出现 URL、状态码或响应体——响应体里带的是知识库凭据。
+ *
+ * `fetchImpl` / `timeoutMs` 仅用于测试注入。
+ */
+export function createKnowledgeConfigGateway(baseURL, opts = {}) {
+    const root = baseURL.replace(/\/+$/, '');
+    const timeoutMs = opts.timeoutMs ?? KNOWLEDGE_CONFIG_TIMEOUT_MS;
+    const doFetch = opts.fetchImpl ?? fetch;
+    return {
+        async getMyKnowledgeConfig(sessionCookie) {
+            try {
+                const res = await doFetch(`${root}${ME_KNOWLEDGE_CONFIG_PATH}`, {
+                    method: 'GET',
+                    headers: {
+                        'user-agent': `hiwork-core/${PKG_VERSION}`,
+                        cookie: sessionCookie,
+                    },
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                if (!res.ok)
+                    return { ok: false, kind: 'http', status: res.status };
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    // 非 JSON 响应：只报「不可解析」，不把响应片段带进任何返回值或日志。
+                    return { ok: false, kind: 'invalid' };
+                }
+                if (body === null || typeof body !== 'object')
+                    return { ok: false, kind: 'invalid' };
+                return { ok: true, body };
+            }
+            catch {
+                // 超时（AbortSignal.timeout → TimeoutError）/ 连接失败 / DNS：一律按不可达。
+                return { ok: false, kind: 'network' };
+            }
+        },
+    };
+}

package/lib/pms-client.js

@@ -395,6 +395,10 @@ export class PmsClient {
      * 必须与其余调用逐字相同**（spec §7：统一 10s、令牌只在有身份时发），所以两条路共用这一处，
      * 而不是各抄一份、将来各自漂移。
      *
+     * **重定向自己跟**（`redirect: 'manual'` + {@link redirectTargetOf}）：`fetch` 的默认 `follow` 会把
+     * 重定向后的请求按 fetch 语义**把 POST 改成 GET**，于是请求落在一个只认 POST 的映射上、拿到一个
+     * 「200 + 业务错误信封」，看上去像上游坏了。判据与修法见 {@link PMS_MAX_REDIRECTS}。
+     *
      * @param url - 相对路径（拼 {@link PmsClient.baseURL}）或**绝对 URL**（原样使用）。
      * @param opts - 方法 / 可选 JSON 体 / 可选 Bearer 令牌。
      * @returns 原始 `Response`：状态码由调用方判定，本方法不把任何状态码当成错误。
@@ -413,14 +417,25 @@ export class PmsClient {
             const init = {
                 method: opts.method,
                 headers,
-                signal: AbortSignal.timeout(this.timeoutMs),
+                // 手动跟随：默认的 `follow` 会把重定向后的 POST 降级成 GET（见本方法的抬头）。
+                redirect: 'manual',
             };
             if (opts.body !== undefined)
                 init.body = JSON.stringify(opts.body);
-            return await fetch(isAbsoluteUrl(url) ? url : `${this.baseURL}${url}`, init);
+            // 截止时刻是**整条链**的预算（10s 不是「每跳各给 10s」）。
+            const deadline = Date.now() + this.timeoutMs;
+            let target = isAbsoluteUrl(url) ? url : `${this.baseURL}${url}`;
+            let response = await fetchWithinDeadline(target, init, deadline);
+            for (let hop = 0;; hop += 1) {
+                const next = redirectTargetOf(target, response, hop);
+                if (next === undefined)
+                    return response;
+                target = next;
+                response = await fetchWithinDeadline(target, init, deadline);
+            }
         }
         catch {
-            // DNS / 连接失败 / TLS / 超时（AbortSignal.timeout）——一律「上游不可用」，
+            // DNS / 连接失败 / TLS / 超时（AbortSignal.timeout）/ 超过跳数 —— 一律「上游不可用」，
             // 且**不**把底层异常信息带出去（它可能含内网地址）。
             throw new PmsError('UPSTREAM_UNAVAILABLE', PMS_GENERIC_FAILURE_MESSAGE);
         }
@@ -486,6 +501,83 @@ function isRecord(value) {
 function isAbsoluteUrl(url) {
     return /^https?:\/\//i.test(url);
 }
+/**
+ * 最多跟随的**重定向跳数**（超过即放弃，把最后那个 3xx 原样交给调用方 → 上游不可用）。
+ *
+ * 为什么要有这个上限：重定向跟随是本次加固里唯一一处「会替调用方多发一次请求」的地方，
+ * 上限定小了（2 跳）足以覆盖真实形态（`http://` 登记 → nginx 302 → `https://` 一跳；
+ * 见过的最多是「域名 → 规范域名 → 真实地址」两跳），定大了只会在配错时把断言连打出去。
+ */
+export const PMS_MAX_REDIRECTS = 2;
+/**
+ * 会「原样重发」的重定向状态码：301 / 302 / 307 / 308。
+ *
+ * **303 刻意不在其中**：按 RFC 与 fetch 语义，303 的语义就是「用 GET 去取那个地址」——把它也变成
+ * 「保持 POST 重发」等于替服务端改主意。本层宁可把 303 原样交出去（调用方按上游不可用收敛），
+ * 也不猜服务端想要哪一种。
+ */
+const METHOD_PRESERVING_REDIRECTS = new Set([301, 302, 307, 308]);
+/**
+ * 决定这一跳要不要跟、跟去哪。`undefined` = **到此为止**（把当前这份 `Response` 交给调用方）。
+ *
+ * 背景（生产实测的故障）：平台把服务登记成 `http://pms.hivery.cn/mcp/credential-exchange`，
+ * nginx 回 302 到 https，而 `fetch` 默认跟随时会按 fetch 语义**把 POST 改成 GET**——于是请求落在
+ * 一个只认 `@PostMapping` 的映射上，应用回「200 + `{"code":500}`」信封，桌面端只看到「待办暂时
+ * 拉不到」。所以这里手动跟随，并**保持方法与请求体**。
+ *
+ * 三条闸（都是「宁可不跟」的方向，因为跟着走的那个请求体里装的是**凭据**：mint 的 body 是 120 秒断言）：
+ *  - **状态码**：只有 {@link METHOD_PRESERVING_REDIRECTS} 里的码才跟；
+ *  - **主机名必须相同**（端口与 scheme 可变，见下）：跨主机名跟随等于把断言发给第三方；
+ *  - **禁止 https → http 降级**（http → https 升级允许）：凭据不该因为一次重定向而落到明文上。
+ *
+ * 端口为什么允许变：真实拓扑里「对外 443 / 内网 8080」是常态，主机名才是「我是不是在跟同一个部署
+ * 说话」的边界；scheme 从 http 升到 https（本次的真实形态）跨端口更常见。
+ *
+ * @param current - 本次请求实际打的地址（绝对 URL）。
+ * @param response - 它的响应（只读 `status` 与 `location`）。
+ * @param hop - 已经跟随过几跳（从 0 起）。
+ * @returns 下一跳的绝对地址；不跟时 `undefined`。
+ */
+export function redirectTargetOf(current, response, hop) {
+    if (!METHOD_PRESERVING_REDIRECTS.has(response.status))
+        return undefined;
+    if (hop >= PMS_MAX_REDIRECTS)
+        return undefined;
+    const location = response.headers.get('location');
+    if (location === null || location.trim() === '')
+        return undefined;
+    let from;
+    let next;
+    try {
+        from = new URL(current);
+        // 相对 `Location` 按当前地址解析（HTTP 允许）。
+        next = new URL(location.trim(), current);
+    }
+    catch {
+        return undefined;
+    }
+    if (next.protocol !== 'https:' && next.protocol !== from.protocol)
+        return undefined;
+    if (next.hostname !== from.hostname)
+        return undefined;
+    return next.toString();
+}
+/**
+ * 一次 `fetch`，但超时按**整条链共用的截止时刻**算（含重定向后的那些跳）。
+ *
+ * 为什么不是每跳各给 {@link PmsClientOptions.timeoutMs}：spec §7 冻结的是「统一 10s 超时」，
+ * 而一次取数最多可能走三跳；每跳各给 10s 会把面板的转圈时间变成 30s。
+ *
+ * @param target - 绝对地址。
+ * @param init - 方法 / 头 / 体（**同一个 init 对象复用于每一跳**，方法与体因此天然一致）。
+ * @param deadline - 整条链的截止时刻（epoch ms）。
+ */
+async function fetchWithinDeadline(target, init, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error('pms request deadline exceeded');
+    return await fetch(target, { ...init, signal: AbortSignal.timeout(remaining) });
+}
 /**
  * 兑换响应里的 `expiresAt`（spec §4.1b 的 ISO 串）**原样透传**；缺失 / 不是能解析的时间串时退回兜底时刻。
  *

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

@@ -286,6 +286,23 @@ export interface GatewayRelayContent {
     revision: number;
     bytes?: Uint8Array;
 }
+/**
+ * GET /api/me/voice-config 响应。
+ *
+ * 网关线上的字段是 snake_case `max_audio_seconds`，**在这一层就转成 camelCase**：
+ * Host 频道、浏览器半边与测试都只认 `maxDurationSeconds` 一种写法，免得同一个概念
+ * 在链路里换两次名字。
+ */
+export interface GatewayVoiceConfig {
+    /** 本部署 + 本账号是否可用语音识别（管理员开关）。 */
+    enabled: boolean;
+    /** 单次录音时长上限（秒）：录音端据此自动停录，别让用户录到被网关 413 拒掉。 */
+    maxDurationSeconds: number;
+}
+/** POST /api/me/voice-transcribe 响应：识别出的文本（可能为空串，即「没听到人话」）。 */
+export interface GatewayVoiceTranscription {
+    text: string;
+}
 /**
  * POST /api/me/mcp-assertions 响应：一张 **120 秒**的身份断言（RS256 JWT）+
  * 去哪换令牌。断言本身不是凭据（换不成令牌就是废纸），所以它可以出现在这里；
@@ -627,6 +644,50 @@ export declare class AiRouterClient implements GatewayClient {
      * 那里才决定「这一份算不算成功拉到的清单」。
      */
     getMyWorkbenchApps(sessionCookie: string): Promise<GatewayWorkbenchAppsView>;
+    /**
+     * GET /api/me/voice-config：当前账号的语音识别开关与录音时长上限。
+     *
+     * 与每日一句的 `getMyDailyQuote` 同款，**这两个方法不在 {@link GatewayClient} 接口上**：
+     * 那个接口是编排层的端口，「语音识别」与它无关，加进去只会逼着每处编排层假网关
+     * （tests/orchestration.spec.ts 里一堆）都补两个用不到的桩。频道侧改用结构子集
+     * `VoiceGatewayPort`（见 `src/voice-rpc.ts`），与 usage / daily 三处一致。
+     *
+     * 与 {@link getMyMcpAssignments} 同样的理由**不复用 `getMeJson`**：那条路径把 403 映射成
+     * `NO_KEY_ASSIGNED`（「尚未被分配虚拟 KEY」），而本端点的鉴权只有会话——一个还没被分配
+     * Key 的账号照样应该有语音识别（分能力与分 Key 是两件事）。沿用它的文案会把「没有 Key」
+     * 错报成原因。
+     *
+     * 本端点契约**恒 200**（开关开与关都是 200 + `enabled` 布尔），因此除 401 以外没有任何
+     * 需要单独解释的拒绝语义：403 / 404 / 5xx / 反代错误页一律收敛成 `GATEWAY_UNREACHABLE`。
+     *
+     * 形状收敛（**本层负责**，消费方拿到的永远是一个合法的 {@link GatewayVoiceConfig}）：
+     * 网关线上是 snake_case `max_audio_seconds`，这里转 camelCase；字段缺失 / 类型不符
+     * 按「禁用 + 60 秒」处理——配置读不出来时话筒本就该消失，用一个 undefined 让消费方
+     * 去猜是把形状问题推给下游。真正的「读不到就回落」再往上一层（`src/voice-rpc.ts`）。
+     */
+    getMyVoiceConfig(sessionCookie: string): Promise<GatewayVoiceConfig>;
+    /**
+     * POST /api/me/voice-transcribe：把一段录音（base64）交给网关转发上游做识别。
+     *
+     * 状态码映射与服务端 handler 一一对应，**不许合并**：
+     *  - 401 = 会话过期（唯一一条能让人做点什么——重新登录——的拒绝）；
+     *  - 503 = 网关自己发的「功能不可用」，再按响应体 `code` 细分：
+     *    `VOICE_NOT_CONFIGURED`（部署没配上游）/ `VOICE_DISABLED`（管理员把开关关了）。
+     *    两者给的提示不同（该找管理员配服务 vs 该找管理员开开关）。
+     *    ⚠️ 响应体没有 `code`（非 JSON / 反代错误页）也归 `VOICE_DISABLED`——这条路由的
+     *    503 语义就是「没开」，而**上游故障走 502**（见下），不会伪装成 503；
+     *  - 429 / 413 / 400 = 配额 / 超长 / 请求体不合法，三种不同的事，分开映射（合并后
+     *    客户端只会看到一句「识别失败」，413 的人不知道该录短一点）；
+     *  - 其余（含 502 = 上游出错）→ `VOICE_UPSTREAM`。
+     *
+     * message 一律取网关响应体里的 `message`（网关侧是冻结的中文文案，会直接展示给用户）；
+     * 响应体不是合法 JSON / 缺 message 时退回本地兜底文案。**绝不把上游 / 网关原文回显**：
+     * 读取响应体走 {@link readVoiceError}（解析失败即空对象），与 `parseMeJson` 不回显原文同源。
+     *
+     * 超时**单独放宽到 60s**（见 {@link VOICE_TRANSCRIBE_TIMEOUT_MS}）：这条要上传录音 +
+     * 等上游识别，构造时的 10s 默认值在这里是误报源。
+     */
+    transcribeVoice(sessionCookie: string, audioBase64: string): Promise<GatewayVoiceTranscription>;
     /**
      * /api/me 自助端点的 GET 公共路径：网络异常 → GATEWAY_UNREACHABLE，
      * 401/403/400 映射为稳定 code，响应体非 JSON 时不把原文带进异常。

package/lib/types/client/hero-greeting.d.ts

@@ -1,14 +1,3 @@
-/**
- * hero 问候语轮换（每日卡片的同页组件，自 hiwork-dsh-ui 静态版演化）：
- * 官方口号「探索未至之境 / Into the Unknown」替换为「HiWork，+ 候选池随机一条」，
- * 前缀固定保留，候选每次进入 hero 页时随机切换（排除上一条，不重复）；
- * 同时隐藏鱼形品牌标记与「预览版」徽标。
- *
- * 实现：宿主标题节点用 CSS 归零隐藏，问候语是插件自有（data-hiwork-hero-greeting
- * 标记）的相邻 span，由观察器幂等插入——不搬移/不改写宿主节点，宿主重建 hero 时自动
- * 重挂并换下一条，非 hero 阶段自动清残留。样式 id 改用 hiwork 前缀：本模块已是
- * dsh-ui 静态 ::after 版的超集，两版并存会双份文案。
- */
 /** 问候候选池（前缀 HiWork，之后的部分），措辞逐字保留产品定稿。 */
 export declare const HERO_GREETINGS: readonly string[];
 /** 固定前缀：所有候选共用，轮换的只是后半句。 */

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

@@ -130,3 +130,31 @@ export declare const brandCss: string;
  * 由 client 入口 apply() 注入一次（带 id 防重）。
  */
 export declare const interactionCss: string;
+/**
+ * 手写注入的 <style> 必须带 DSH 的归属标记（`data-plugin`）。
+ *
+ * DSH 的 client module system 用这个属性记账：每装载（materialize）一个插件 bundle，
+ * 就把文档里**所有没有** `data-plugin` 的 <style> 记到当时正在装载的那个插件名下
+ * （`claimStyles`，`dsh-client-modules/src/client/system.ts`）；插件被替换、重建或停用
+ * 时按 `removeOwnedStyles(id)`（同包 `entry-lifecycle.ts`）删掉「记在它名下」的全部
+ * <style>。裸注入的样式会被随后第一个装载的插件顺手认领，再随它被替换/停用而**连带
+ * 删除**，而本插件此刻并没有重新 apply —— 表现就是这部分样式静默消失、只有刷新页面
+ * 才恢复（2026-09-23 实测：hiwork-knowledge 重建后，本插件两个样式表被一起删掉，实测
+ * 归属曾被记到 `@deepseek-ai/dsh-client-ui-deliverables` 名下）。
+ * 标记形态与官方 client bundle 预设一致（`tsdown.client.ts` 的 styleInjectionModule）。
+ */
+export declare const CORE_STYLE_OWNER = "hiwork-core";
+/** 给本插件注入的 <style> 打归属标记；`cssTagId` 沿用官方预设的 `包名/文件名` 形态。 */
+export declare function ownStyleTag(style: HTMLStyleElement, cssTagId: string): void;
+/**
+ * 语音输入（话筒按钮 + 录音浮层）的样式，随本插件一起分发。
+ *
+ * 类名统一 `hiwv-` 前缀，**不引用宿主内部 CSS 变量**：这些浮层元素是 `document.body`
+ * 直挂的，宿主 DOM 结构/变量名跨版本不稳，故自带中性配色 + `prefers-color-scheme` 自适应。
+ * 设置分区（`.hiwv-settings*` / `.hiwv-field` / `.hiwv-help`）**不存在**：配置面在网关
+ * （管理端「语音识别设置」），桌面端没有任何语音相关的设置项。
+ *
+ * 注入走 `voice/voice-styles.ts` 的 `ensureVoiceStyle`，**必须**经 {@link ownStyleTag}
+ * 打归属标记（见上方事故记录）：裸注入会被随后装载的插件认领并连带删除。
+ */
+export declare const voiceCss: string;

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

@@ -31,7 +31,19 @@ export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHAB
  * 收敛成 `GATEWAY_UNREACHABLE`；工作台的 404 是一个明确的功能状态（spec §10 的降级矩阵），
  * 消费方据此显示「本部署尚未启用工作台」而不是报错。别顺手把两边对齐。
  */
- | 'WORKBENCH_DISABLED';
+ | 'WORKBENCH_DISABLED'
+/** 本部署未启用语音识别（管理员把开关关了）：识别时 503（或 503 无 body code）。 */
+ | 'VOICE_DISABLED'
+/** 本部署未配置语音识别上游服务（网关侧没有可用 ASR 配置）：识别时 503。 */
+ | 'VOICE_NOT_CONFIGURED'
+/** 单用户识别频率超限：429。 */
+ | 'VOICE_LIMIT_REACHED'
+/** 录音超过网关允许的大小 / 时长上限：413。 */
+ | 'VOICE_AUDIO_TOO_LARGE'
+/** 录音数据不合法（base64 损坏 / 请求体越界）：400。 */
+ | 'VOICE_BAD_REQUEST'
+/** 上游识别服务出错或网关 502 之类的转发失败：其余非 2xx（含 502）。 */
+ | 'VOICE_UPSTREAM';
 /** 一个稳定的、可安全展示的登录/刷新错误。 */
 export interface LoginError {
     code: LoginErrorCode;

package/lib/types/client/voice/MicButton.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 输入框工具栏的话筒按钮（`conversation.input.right` 槽）。
+ *
+ * 该槽渲染在发送区右组、**模型选择器之前**（宿主 InputBar 的顺序：right → model →
+ * stop/send），正是需求指定的落点。按钮只负责「打开浮层」，识别与插入都在浮层里。
+ *
+ * 一条约定：**不按「本机有没有配豆包密钥」改 tooltip**——D1 之后配置面整体废除，
+ * 能不能用由 `status` 端点说了算，而 `enabled !== true` 时本按钮根本不会被注册
+ * （见 `voice/entry.ts` 的门禁）。
+ */
+import { type ReactElement } from 'react';
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** 组件注入面：打开录音浮层（会话 id 由槽位在渲染时注入，见 entry）。 */
+export interface MicButtonFace {
+    /** 打开浮层；`sessionId` 是槽位注入的会话 id（拿不到为 undefined，插入时退到当前会话）。 */
+    open: (sessionId?: string) => void;
+}
+/** 槽位组件 props：框架标准件 + 注入面（`conversation.input.right` 是 session 作用域 list 槽）。 */
+export type MicButtonProps = PropsRuntime<'conversation.input.right'> & InjectFace<MicButtonFace>;
+/**
+ * 话筒按钮；宿主通过 inject 合成 `open`。
+ * @param props - 槽位 props（只消费注入面的 `open`）。
+ */
+export declare function MicButton({ open }: MicButtonProps): ReactElement;

package/lib/types/client/voice/VoiceOverlay.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 录音浮层：点击话筒后弹出的「正在录音」交互。
+ *
+ * 需求约束：
+ *  - 组件**不能太小**（面板最小 420px、居中、带遮罩）；
+ *  - 必须支持**取消**（ESC / 取消按钮 / 点遮罩），取消即丢弃录音、不写输入框；
+ *  - 「完成」后上传识别，识别文本**填进输入框草稿，不自动发送**；
+ *  - 没听清 / 失败时给出原因与出口（再录一次 / 重试识别 / 复制文本），绝不静默。
+ *
+ * 两条与网关中继相配的约定（设计稿 §5.4 冻结）：
+ *  1. **时长上限来自 `status` RPC**（`{enabled, maxDurationSeconds}`，见 `voice-data.ts`），
+ *     不来自任何本机配置——D1 之后没有「本机密钥配置」这回事了；
+ *  2. **失败文案按网关 code 映射**（{@link voiceErrorMessageOf}），不把 Host 的
+ *     `message` 直出；「重试识别」只在可能自愈的 code 上出现（`status.enabled !== true`
+ *     与网关不可达走同一句「连接语音服务失败，请稍后重试」，本组件只是兜底，
+ *     正常情况下这种状态压根不会注册话筒按钮）。
+ */
+import { type ReactElement } from 'react';
+import type { ComposerInsertResult } from './composer.ts';
+import { type VoiceRuntime } from './voice-data.ts';
+/** 浮层属性（由 `voice/entry.ts` 的浮层控制器组装）。 */
+export interface VoiceOverlayProps {
+    /** 取数面：`status`（时长上限 + 能不能用）与 `transcribe`（WAV base64 → 文本）。 */
+    runtime: VoiceRuntime;
+    /** 关闭浮层（取消或完成后由组件内部调用；React root 的卸载由控制器负责）。 */
+    onClose: () => void;
+    /** 把识别文本写进会话输入框草稿（entry 用 `composer.ts` 的 `insertDraftText` 组装）。 */
+    insertDraft: (text: string) => ComposerInsertResult;
+}
+/**
+ * RMS → 显示电平。语音的裸 RMS 通常只有 0.02~0.2，直接进 `8 + level*46` 的像素映射
+ * 几乎看不出跳动（0.1 的响度只比安静高 4px）；放大 6 倍再钳到 1，正常说话就能打到
+ * 半高以上。导出供测试锁定映射。
+ */
+export declare function rmsToLevel(rms: number): number;
+/** 录音浮层组件（由 `voice/entry.ts` 的 overlay 控制器挂载/卸载）。 */
+export declare function VoiceOverlay(props: VoiceOverlayProps): ReactElement;