hiwork-core 0.0.22 → 0.0.29

package/lib/types/voice-rpc.d.ts

@@ -0,0 +1,133 @@
+/**
+ * `/hiwork-voice` loopback RPC 的 Host 实现（浏览器侧话筒录音 → 识别文本的唯一入口）。
+ *
+ * 设计要点（与 `src/daily-rpc.ts` / `src/usage-rpc.ts` 完全同构）：
+ *  - 只注册一个 channel，endpoint 白名单在 {@link VOICE_RPC_ENDPOINTS}，未知 endpoint
+ *    直接 `bad-request`；
+ *  - payload 严格校验：`status` 只接受空对象，`transcribe` 只接受 `{ audioBase64: 非空字符串 }`，
+ *    任何其它字段 / 类型不符一律 `bad-request`；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方只拿到端点结果，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - 网关 `GatewayError` 的稳定 code 原样透传，但 message 先经
+ *    {@link displayVoiceGatewayMessage} 消毒——baseURL / HTTP 状态码这类实现细节不进 UI；
+ *  - 其余异常收敛为通用失败（code `internal`），Host 只记日志、不把堆栈或原始消息
+ *    交给客户端。
+ *
+ * 两处**与 daily / usage 不同**的语义，都写在这里免得后来的人「对齐」掉：
+ *  1. `status` 端点的失败**不是错误信封**——网关故障时回落
+ *     `{enabled:false, maxDurationSeconds:60}`（{@link VOICE_FALLBACK_CONFIG}）。
+ *     这条端点的调用频率是「页面挂载一次」，对用户而言它只有一个含义：话筒该不该出现。
+ *     网关挂了就报一个红字，只会让一个本来就没有的功能显得像坏了。
+ *  2. `transcribe` 的入参是**一段 base64 录音**（全链路唯一的大对象，与技能包体同级），
+ *     所以它的载荷校验只走白名单 + 非空，不在 Host 侧做 base64 解码或大小判断——
+ *     那两件事分别由浏览器半边与网关负责（网关超限回 413）。
+ *
+ * 消毒逻辑是**同构复制**而非复用 usage/daily 的导出：兜底文案是用量域 / 每日一句域的，
+ * 复用会让语音识别的失败吐出别的域的文案；且本仓库的频道模块本就各自自带一份同实现，
+ * 保持模块自包含。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link VoiceRpcContext} 端口，
+ * 便于单测直接伪造。
+ */
+import { type GatewayVoiceConfig, type GatewayVoiceTranscription } from './ai-router-client.ts';
+/** RPC 频道；必须与 client 半边 `src/client/voice/voice-data.ts` 的 `VOICE_CHANNEL` 一致（由测试锁定）。 */
+export declare const VOICE_RPC_CHANNEL = "/hiwork-voice";
+/** 端点白名单：`status`（配置）与 `transcribe`（识别）。 */
+export declare const VOICE_RPC_ENDPOINTS: readonly ["status", "transcribe"];
+export type VoiceRpcEndpoint = (typeof VOICE_RPC_ENDPOINTS)[number];
+/** 端点入参：`status` 无入参；`transcribe` 必带非空 `audioBase64`。 */
+export interface VoiceRpcPayload {
+    audioBase64?: string | undefined;
+}
+/** 客户端可安全展示的失败。 */
+export interface VoiceRpcFailure {
+    code: string;
+    message: string;
+    /** DSH Connection 信封要求 `details` 是对象；协议层没有额外细节时补空对象。 */
+    details: object;
+}
+/** 端点结果信封（与 DSH Connection 的 `ConnectionRpcResult` 同形）。 */
+export type VoiceRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: VoiceRpcFailure;
+};
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export declare class VoiceRequestError extends Error {
+    readonly code: 'bad-request';
+    constructor(code: 'bad-request', message: string);
+}
+/** Host 侧 RPC 依赖的最小上下文（结构兼容 cordis Context，便于单测伪造）。 */
+export interface VoiceRpcConnection {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+            authority: 'loopback';
+        }): () => Promise<void> | void;
+    };
+}
+export interface VoiceRpcContext {
+    readonly connection: VoiceRpcConnection;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * 网关客户端的语音子集：只声明本频道真正调用的方法（结构兼容 `GatewayClient` 实例），
+ * 单测因此不需要伪造整个客户端。
+ */
+export interface VoiceGatewayPort {
+    getMyVoiceConfig(sessionCookie: string): Promise<GatewayVoiceConfig>;
+    transcribeVoice(sessionCookie: string, audioBase64: string): Promise<GatewayVoiceTranscription>;
+}
+/** Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关客户端。 */
+export interface VoiceRpcDeps {
+    /**
+     * 解析网关会话 cookie。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用，绝不出现在 RPC 响应里。**
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关客户端；baseURL 未配置时返回 undefined。 */
+    gateway(): VoiceGatewayPort | undefined;
+    /** Host 日志出口（只记事件与错误类型，不记会话值、不记录音内容）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 通用失败文案：不暴露任何网关细节。 */
+export declare const VOICE_GENERIC_FAILURE_MESSAGE = "\u8BED\u97F3\u8BC6\u522B\u6682\u65F6\u65E0\u6CD5\u4F7F\u7528\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/** 未登录 / 会话失效的统一文案（与用量频道的 `SESSION_EXPIRED` 口径一致）。 */
+export declare const VOICE_SESSION_EXPIRED_MESSAGE = "\u767B\u5F55\u72B6\u6001\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55";
+/**
+ * `status` 端点读不到配置时的回落值（**成功信封**，见模块头注释第 1 条）：
+ * 话筒消失，而不是弹一条用户看不懂的错误。
+ */
+export declare const VOICE_FALLBACK_CONFIG: GatewayVoiceConfig;
+/**
+ * 网关 message 消毒（与 `daily-rpc.ts` 的 `displayDailyGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export declare function displayVoiceGatewayMessage(code: string, message: unknown): string;
+/**
+ * payload 校验：`status` 只放行空对象，`transcribe` 只放行 `{ audioBase64: 非空字符串 }`
+ * （纯空白视为空——它不可能是合法录音）；其余字段 / 类型不符一律 `bad-request`。
+ *
+ * **不在这里解析 / 校验 base64 本身**：解码与大小上限分别由浏览器半边与网关负责
+ * （网关超限回 413，映射在 `AiRouterClient.transcribeVoice`），Host 侧只做协议形状。
+ */
+export declare function parseVoicePayload(endpoint: VoiceRpcEndpoint, raw: unknown): VoiceRpcPayload;
+/** 是否为白名单端点。 */
+export declare function isVoiceRpcEndpoint(endpoint: string): endpoint is VoiceRpcEndpoint;
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ *
+ * `status` 走 {@link readVoiceConfig} 的**降级**分支：网关故障 → 成功信封里的
+ * `enabled:false`。「没有会话」「网关地址未配置」两条**不是**降级——那时还没有任何
+ * 功能状态可言（页面本身在登录门后），照常回错误信封。
+ */
+export declare function handleVoiceEndpoint(endpoint: string, rawPayload: unknown, deps: VoiceRpcDeps, signal?: AbortSignal): Promise<VoiceRpcResult<unknown>>;
+/**
+ * 注册 `/hiwork-voice` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export declare function registerVoiceRpc(ctx: VoiceRpcContext, deps: VoiceRpcDeps): () => Promise<void>;

package/lib/types/web-search.d.ts

@@ -0,0 +1,123 @@
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+/** 本 provider 注册进 `ctx.web` 用的稳定 id（cordis.patch.yml 的 searchProvider pin 与它逐字一致）。 */
+export declare const HIWORK_SEARCH_PROVIDER_ID = "hiwork-managed-search";
+/** 网关侧端点（跨仓冻结；会话鉴权与 `/api/me/memory-config` 同一条）。 */
+export declare const ME_WEB_SEARCH_PATH = "/api/me/web-search";
+/** 出网超时。网关侧自持 10s 上游预算；这里取 12s 留出网关排队的余量，仍远小于 tool-web 的 60s 工具预算。 */
+export declare const WEB_SEARCH_TIMEOUT_MS = 12000;
+/**
+ * 网关侧原始响应（**snake_case**，跨仓冻结契约；本文件是唯一读它的地方）。
+ * 仅供类型自证 —— 真正的读取走宽容投影 {@link projectWebSearch}。
+ */
+export interface GatewayWebSearchResponse {
+    query: string;
+    /** 产出结果的服务商（排障线索；本模块不按它分支 —— 换服务商正是要隐藏的变化）。 */
+    provider: string;
+    results: GatewayWebSearchResultItem[];
+}
+export interface GatewayWebSearchResultItem {
+    title?: string;
+    url: string;
+    snippet?: string;
+    content?: string;
+    published_at?: string;
+}
+/**
+ * 传输层结果：失败是数据而不是异常（gateway 端口**从不抛错**）。
+ *  - `kind: 'http'`：拿到了非 2xx；`code` 是网关冻结错误码（body 里有就带上，
+ *    供 provider 分「关闭 / 未配置 / 超限」三档）；
+ *  - `kind: 'aborted'`：调用方取消（seam 的取消契约要求映射回 `WEB_ABORTED`）；
+ *  - `kind: 'network'`：超时 / 连接失败 / DNS；
+ *  - `kind: 'invalid'`：2xx 但响应体不是可用的 JSON 对象（契约破坏）。
+ */
+export type WebSearchOutcome = {
+    readonly ok: true;
+    readonly body: unknown;
+} | {
+    readonly ok: false;
+    readonly kind: 'http';
+    readonly status: number;
+    readonly code?: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'aborted';
+} | {
+    readonly ok: false;
+    readonly kind: 'network';
+} | {
+    readonly ok: false;
+    readonly kind: 'invalid';
+};
+/** 网关客户端的 web-search 子集：只声明本模块真正调用的方法（便于单测打桩）。 */
+export interface WebSearchGatewayPort {
+    searchWeb(sessionCookie: string, body: {
+        query: string;
+        max_results?: number;
+    }, signal?: AbortSignal): Promise<WebSearchOutcome>;
+}
+/** Host 侧依赖：会话解析 + 当前 baseURL 下的网关出网端口。 */
+export interface WebSearchProviderDeps {
+    /**
+     * 解析网关会话 cookie。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部用于出网**，绝不进日志与错误消息。
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关出网端口；baseURL 未配置时返回 undefined。 */
+    gateway(): WebSearchGatewayPort | undefined;
+    /** Host 日志出口（只记事件与异常类型名，不记 query / URL / 响应内容）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/**
+ * HiWork 受管搜索 provider。`available()` 恒 true（同步、无网络 —— DSH 契约）：
+ * 会话是否可用要到 `search()` 时才知道，那时按 {@link WebError} 的稳定 code 上报，
+ * 而不是假装「不可用」让 seam 报一个笼统的 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`。
+ */
+export declare class HiworkSearchProvider implements WebSearchProvider {
+    private readonly deps;
+    readonly id = "hiwork-managed-search";
+    constructor(deps: WebSearchProviderDeps);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+/** 未登录 / 会话失效（网关 401，或本地就没有会话）。 */
+export declare const HIWORK_SEARCH_UNAUTHENTICATED = "HIWORK_SEARCH_UNAUTHENTICATED";
+/** 管理员还没开启联网搜索（网关 503 SEARCH_DISABLED）。 */
+export declare const HIWORK_SEARCH_DISABLED = "HIWORK_SEARCH_DISABLED";
+/** 网关没配上游（网关 503 SEARCH_NOT_CONFIGURED；找运维，不是员工能解决的）。 */
+export declare const HIWORK_SEARCH_NOT_CONFIGURED = "HIWORK_SEARCH_NOT_CONFIGURED";
+/** 当日次数用完（网关 429 SEARCH_LIMIT_EXCEEDED）。 */
+export declare const HIWORK_SEARCH_LIMIT = "HIWORK_SEARCH_LIMIT";
+/** 网关不可达 / 超时 / 宿主故障（可重试）。 */
+export declare const HIWORK_SEARCH_UNREACHABLE = "HIWORK_SEARCH_UNREACHABLE";
+/** 网关代打上游失败（网关 502 SEARCH_UPSTREAM_ERROR；可重试）。 */
+export declare const HIWORK_SEARCH_UPSTREAM = "HIWORK_SEARCH_UPSTREAM";
+/**
+ * 响应体 → 归一化结果。
+ *
+ * `results` 缺失或不是数组返回 undefined（契约破坏，调用方报 provider error）；
+ * 单条缺 `url` 的**丢弃**（没法被引用），缺 title/snippet/published_at 的保留其余
+ * 字段（DSH 侧全是可选语义）。`content`（上游网页原文片段）在 snippet 缺席时兜底 ——
+ * 两个都是正文片段，给模型看比给一个空引用强。
+ */
+export declare function projectWebSearch(body: Record<string, unknown>): WebSearchResult | undefined;
+/**
+ * 本端点的出网实现（形状与 `createKnowledgeConfigGateway` 同款：user-agent 带包版本、
+ * 会话 cookie 走 `cookie` 头、外部 signal 与超时经 `AbortSignal.any` 合并）。
+ *
+ * **永不抛异常**：失败收敛成 {@link WebSearchOutcome}。取消（外部 signal 先触发）单独
+ * 分档 —— seam 的取消契约要求它以 `WEB_ABORTED` 上抛，不能被折进「网络故障」。
+ *
+ * `fetchImpl` / `timeoutMs` 仅用于测试注入。
+ */
+export declare function createWebSearchGateway(baseURL: string, opts?: {
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): WebSearchGatewayPort;
+/**
+ * 把 provider 注册进 `ctx.web`。注册即挂 fiber（disposer 由 dsh-web 自己挂，见
+ * `WebRuntime.registerProvider`），与 web-search-exa 插件的 apply 同款。
+ * 依赖 `web` 服务在 inject 里声明（dsh-base 基座先于本插件挂载 dsh-web）。
+ */
+export declare function registerManagedSearchProvider(web: {
+    registerSearchProvider(provider: WebSearchProvider): () => void;
+}, deps: WebSearchProviderDeps): () => void;

package/lib/voice-rpc.js

@@ -0,0 +1,211 @@
+/**
+ * `/hiwork-voice` loopback RPC 的 Host 实现（浏览器侧话筒录音 → 识别文本的唯一入口）。
+ *
+ * 设计要点（与 `src/daily-rpc.ts` / `src/usage-rpc.ts` 完全同构）：
+ *  - 只注册一个 channel，endpoint 白名单在 {@link VOICE_RPC_ENDPOINTS}，未知 endpoint
+ *    直接 `bad-request`；
+ *  - payload 严格校验：`status` 只接受空对象，`transcribe` 只接受 `{ audioBase64: 非空字符串 }`，
+ *    任何其它字段 / 类型不符一律 `bad-request`；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方只拿到端点结果，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - 网关 `GatewayError` 的稳定 code 原样透传，但 message 先经
+ *    {@link displayVoiceGatewayMessage} 消毒——baseURL / HTTP 状态码这类实现细节不进 UI；
+ *  - 其余异常收敛为通用失败（code `internal`），Host 只记日志、不把堆栈或原始消息
+ *    交给客户端。
+ *
+ * 两处**与 daily / usage 不同**的语义，都写在这里免得后来的人「对齐」掉：
+ *  1. `status` 端点的失败**不是错误信封**——网关故障时回落
+ *     `{enabled:false, maxDurationSeconds:60}`（{@link VOICE_FALLBACK_CONFIG}）。
+ *     这条端点的调用频率是「页面挂载一次」，对用户而言它只有一个含义：话筒该不该出现。
+ *     网关挂了就报一个红字，只会让一个本来就没有的功能显得像坏了。
+ *  2. `transcribe` 的入参是**一段 base64 录音**（全链路唯一的大对象，与技能包体同级），
+ *     所以它的载荷校验只走白名单 + 非空，不在 Host 侧做 base64 解码或大小判断——
+ *     那两件事分别由浏览器半边与网关负责（网关超限回 413）。
+ *
+ * 消毒逻辑是**同构复制**而非复用 usage/daily 的导出：兜底文案是用量域 / 每日一句域的，
+ * 复用会让语音识别的失败吐出别的域的文案；且本仓库的频道模块本就各自自带一份同实现，
+ * 保持模块自包含。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link VoiceRpcContext} 端口，
+ * 便于单测直接伪造。
+ */
+import { GatewayError, } from "./ai-router-client.js";
+/** RPC 频道；必须与 client 半边 `src/client/voice/voice-data.ts` 的 `VOICE_CHANNEL` 一致（由测试锁定）。 */
+export const VOICE_RPC_CHANNEL = '/hiwork-voice';
+/** 端点白名单：`status`（配置）与 `transcribe`（识别）。 */
+export const VOICE_RPC_ENDPOINTS = ['status', 'transcribe'];
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export class VoiceRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'VoiceRequestError';
+    }
+}
+/** 各稳定错误码的用户可见文案（网关 message 含实现细节时用它兜底）。 */
+const VOICE_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: '登录状态已过期，请重新登录',
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    VOICE_DISABLED: '本部署未启用语音识别，请联系管理员',
+    VOICE_NOT_CONFIGURED: '本部署尚未配置语音识别服务，请联系管理员',
+    VOICE_LIMIT_REACHED: '语音识别请求过于频繁，请稍后再试',
+    VOICE_AUDIO_TOO_LARGE: '录音过长，请缩短后重试',
+    VOICE_BAD_REQUEST: '录音数据不合法，请重新录制',
+    VOICE_UPSTREAM: '语音识别服务暂时不可用，请稍后重试',
+    RATE_LIMITED: '请求过于频繁，请稍后再试',
+    AUTH_FAILED: '登录状态异常，请重新登录',
+};
+/** 通用失败文案：不暴露任何网关细节。 */
+export const VOICE_GENERIC_FAILURE_MESSAGE = '语音识别暂时无法使用，请稍后重试';
+/** 未登录 / 会话失效的统一文案（与用量频道的 `SESSION_EXPIRED` 口径一致）。 */
+export const VOICE_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+/**
+ * `status` 端点读不到配置时的回落值（**成功信封**，见模块头注释第 1 条）：
+ * 话筒消失，而不是弹一条用户看不懂的错误。
+ */
+export const VOICE_FALLBACK_CONFIG = { enabled: false, maxDurationSeconds: 60 };
+/**
+ * 网关 message 消毒（与 `daily-rpc.ts` 的 `displayDailyGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export function displayVoiceGatewayMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return VOICE_MESSAGE_FALLBACK[code] ?? VOICE_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 VOICE_MESSAGE_FALLBACK[code] ?? VOICE_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+/**
+ * payload 校验：`status` 只放行空对象，`transcribe` 只放行 `{ audioBase64: 非空字符串 }`
+ * （纯空白视为空——它不可能是合法录音）；其余字段 / 类型不符一律 `bad-request`。
+ *
+ * **不在这里解析 / 校验 base64 本身**：解码与大小上限分别由浏览器半边与网关负责
+ * （网关超限回 413，映射在 `AiRouterClient.transcribeVoice`），Host 侧只做协议形状。
+ */
+export function parseVoicePayload(endpoint, raw) {
+    if (raw === undefined || raw === null) {
+        if (endpoint === 'transcribe')
+            throw new VoiceRequestError('bad-request', '语音识别请求缺少 audioBase64。');
+        return {};
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new VoiceRequestError('bad-request', '语音识别请求参数不合法。');
+    }
+    const record = raw;
+    const keys = Object.keys(record);
+    if (endpoint === 'status') {
+        // status 无任何入参：出现任何字段都是客户端实现缺陷
+        if (keys.length > 0)
+            throw new VoiceRequestError('bad-request', `语音识别请求包含未知字段 '${keys[0]}'。`);
+        return {};
+    }
+    for (const key of keys) {
+        if (key !== 'audioBase64')
+            throw new VoiceRequestError('bad-request', `语音识别请求包含未知字段 '${key}'。`);
+    }
+    const rawAudio = record['audioBase64'];
+    if (typeof rawAudio !== 'string' || rawAudio.trim() === '') {
+        throw new VoiceRequestError('bad-request', '语音识别请求的 audioBase64 必须是非空字符串。');
+    }
+    return { audioBase64: rawAudio };
+}
+/** 是否为白名单端点。 */
+export function isVoiceRpcEndpoint(endpoint) {
+    return VOICE_RPC_ENDPOINTS.includes(endpoint);
+}
+/** 取消判定（用函数包一层，避免 TS 把属性窄化固化到 `await` 之后）。 */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ *
+ * `status` 走 {@link readVoiceConfig} 的**降级**分支：网关故障 → 成功信封里的
+ * `enabled:false`。「没有会话」「网关地址未配置」两条**不是**降级——那时还没有任何
+ * 功能状态可言（页面本身在登录门后），照常回错误信封。
+ */
+export async function handleVoiceEndpoint(endpoint, rawPayload, deps, signal) {
+    try {
+        if (isAborted(signal))
+            return failure('cancelled', '语音识别请求已取消。');
+        if (!isVoiceRpcEndpoint(endpoint)) {
+            throw new VoiceRequestError('bad-request', `未知的语音识别端点 '${endpoint}'`);
+        }
+        const payload = parseVoicePayload(endpoint, rawPayload);
+        const sessionCookie = await deps.resolveSession();
+        if (sessionCookie === undefined || sessionCookie === '') {
+            return failure('SESSION_EXPIRED', VOICE_SESSION_EXPIRED_MESSAGE);
+        }
+        const gateway = deps.gateway();
+        if (gateway === undefined) {
+            return failure('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+        }
+        if (isAborted(signal))
+            return failure('cancelled', '语音识别请求已取消。');
+        if (endpoint === 'status')
+            return { ok: true, value: await readVoiceConfig(gateway, sessionCookie, deps.log) };
+        return { ok: true, value: await transcribe(gateway, sessionCookie, payload) };
+    }
+    catch (error) {
+        if (error instanceof VoiceRequestError)
+            return failure(error.code, error.message);
+        if (error instanceof GatewayError) {
+            // code 原样透传（稳定契约），message 消毒后再给客户端。
+            return failure(error.code, displayVoiceGatewayMessage(error.code, error.message));
+        }
+        deps.log?.(`hiwork-core: 语音识别 RPC '${endpoint}' 失败（${error instanceof Error ? error.name : typeof error}）`);
+        return failure('internal', VOICE_GENERIC_FAILURE_MESSAGE);
+    }
+}
+/**
+ * `status` 端点取数：**读不到配置就让话筒消失**（返回 {@link VOICE_FALLBACK_CONFIG}），
+ * 而不是回错误信封。
+ *
+ * 这条端点会在页面挂载时被调一次，它的唯一用途是「要不要显示话筒」；网关故障、
+ * 会话在途中过期、响应形状不对……对用户而言都只有同一个结论：现在用不了。
+ * 抛错误信封会让一个**默认不存在**的功能冒出红字。所以这里把全部异常咽成禁用配置，
+ * 只留一条 Host 日志（日志里也不带 cookie / 响应原文）。
+ */
+async function readVoiceConfig(gateway, sessionCookie, log) {
+    try {
+        const config = await gateway.getMyVoiceConfig(sessionCookie);
+        // 字段名 / 形状已在网关客户端层收敛（snake_case → camelCase + 缺省兜底），
+        // 这里只把「真值才算开」钉死：undefined / 非布尔一律当关。
+        return {
+            enabled: config.enabled === true,
+            maxDurationSeconds: config.maxDurationSeconds > 0 ? config.maxDurationSeconds : VOICE_FALLBACK_CONFIG.maxDurationSeconds,
+        };
+    }
+    catch (error) {
+        log?.(`hiwork-core: 语音配置读取失败，按禁用回落（${error instanceof Error ? error.name : typeof error}）`);
+        return { ...VOICE_FALLBACK_CONFIG };
+    }
+}
+/** `transcribe` 端点：只回 `{ text }`（网关响应的其余字段不进频道）。 */
+async function transcribe(gateway, sessionCookie, payload) {
+    const audioBase64 = payload.audioBase64;
+    // parseVoicePayload 已保证 transcribe 必带非空 audioBase64；这一支是类型层兜底，
+    // 真走到这里也只抛 VoiceRequestError（由上层信封收敛，不会逃逸）。
+    if (audioBase64 === undefined)
+        throw new VoiceRequestError('bad-request', '语音识别请求缺少 audioBase64。');
+    const result = await gateway.transcribeVoice(sessionCookie, audioBase64);
+    return { text: result.text };
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * 注册 `/hiwork-voice` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export function registerVoiceRpc(ctx, deps) {
+    const handler = (endpoint, payload, signal) => handleVoiceEndpoint(endpoint, payload, deps, signal);
+    const remove = ctx.connection.rpc.handle(VOICE_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => { await remove(); };
+}