hiwork-core 0.0.24 → 0.0.29

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(); };
+}

package/lib/web-search.js

@@ -0,0 +1,259 @@
+/**
+ * 联网搜索的 DSH `ctx.web` provider（id `hiwork-managed-search`）。
+ *
+ * 背景：DSH 自带 `web_search` 工具（`tool-web`），但官方搜索提供方
+ * `web-search-deepseek` 依赖 `DEEPSEEK_API_KEY`（企业用户没有），本产品在
+ * `cordis.patch.yml` 里停用了它。本模块把「搜索后端」接到 HiWork 网关的统一搜索
+ * 端点上 —— **服务商（百度千帆 / 将来的其他家）凭据只在网关，客户端对服务商无感知**：
+ *
+ * ```
+ * DSH web_search 工具（tool-web，执行时调 ctx.web.search）
+ *    ↑ 本文件（hiwork-core 注册的 WebSearchProvider）
+ * hiwork-admin  POST /api/me/web-search   ← 网关统一搜索（持有上游 Key、可换服务商）
+ * ```
+ *
+ * 形状来源：`src/knowledge-config.ts`（同族先例 —— 「网关出网 + 会话 cookie 留在
+ * Host」的同一套纪律）。与它的结构性差异只有两处：
+ *  ① 消费方是 **DSH 的 `ctx.web` seam**，不是插件侧 host 服务 —— 失败按 DSH 契约
+ *     **抛 `WebError`**（tool-web 把 code 放进工具的结构化错误元数据），而不是返回
+ *     `{ ok: false }`；取消必须映射成 `WEB_ABORTED`（seam 的取消契约）。
+ *  ② 无缓存：每次 `web_search` 都是一次实时搜索，缓存它没有意义。
+ *
+ * 不变量（与 knowledge-config 同口径，不得放宽）：
+ *  - **会话 cookie 与 baseURL 全部留在 Host**：渲染端永远碰不到；本模块不生成、
+ *    不保存任何凭据。
+ *  - **字段名分层只在本文件做**：网关 snake_case（`results[].published_at`，跨仓冻结
+ *    契约）→ DSH camelCase（`WebSearchSource.publishedAt`）。
+ *  - **不造值**：上游没给的 `title` / `snippet` / `publishedAt` 留空 —— DSH 侧对这些
+ *    字段是可选语义，编造会让工具输出假引用。
+ *  - **message 是给员工看的中文**：不含 URL 原文、不含 HTTP 状态码、不含服务商名。
+ *  - **日志只记事件与异常类型名**：不记 query / URL / 响应内容（query 是用户输入，
+ *    与「请求体不进日志」的既有口径一致）。
+ *
+ * 本模块不 import cordis 运行时：provider 走结构化的 {@link WebSearchProviderDeps}
+ * 端口，接线方（index.ts）传真实 ctx 侧依赖；单测直接伪造。
+ */
+import { WebError } from '@deepseek-ai/dsh-web';
+import { PKG_VERSION } from "./version.js";
+/** 本 provider 注册进 `ctx.web` 用的稳定 id（cordis.patch.yml 的 searchProvider pin 与它逐字一致）。 */
+export const HIWORK_SEARCH_PROVIDER_ID = 'hiwork-managed-search';
+/** 网关侧端点（跨仓冻结；会话鉴权与 `/api/me/memory-config` 同一条）。 */
+export const ME_WEB_SEARCH_PATH = '/api/me/web-search';
+/** 出网超时。网关侧自持 10s 上游预算；这里取 12s 留出网关排队的余量，仍远小于 tool-web 的 60s 工具预算。 */
+export const WEB_SEARCH_TIMEOUT_MS = 12_000;
+/**
+ * HiWork 受管搜索 provider。`available()` 恒 true（同步、无网络 —— DSH 契约）：
+ * 会话是否可用要到 `search()` 时才知道，那时按 {@link WebError} 的稳定 code 上报，
+ * 而不是假装「不可用」让 seam 报一个笼统的 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`。
+ */
+export class HiworkSearchProvider {
+    deps;
+    id = HIWORK_SEARCH_PROVIDER_ID;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    available() {
+        return true;
+    }
+    async search(request, signal) {
+        if (signal?.aborted)
+            throw aborted();
+        let sessionCookie;
+        try {
+            sessionCookie = await this.deps.resolveSession();
+        }
+        catch (error) {
+            // 凭据服务读取失败是宿主故障：按 provider 错误上报，不诱导用户重登。
+            this.deps.log?.(`hiwork-core: 联网搜索会话解析失败（${errorName(error)}）`);
+            throw new WebError('联网搜索暂时不可用，请稍后重试', HIWORK_SEARCH_UNREACHABLE, { cause: error });
+        }
+        if (sessionCookie === undefined || sessionCookie === '') {
+            throw new WebError('登录后才能使用联网搜索', HIWORK_SEARCH_UNAUTHENTICATED);
+        }
+        const gateway = this.deps.gateway();
+        // 没有网关地址 = 还没完成登录（baseURL 是登录时写下的），与网络不通同一档。
+        if (gateway === undefined) {
+            throw new WebError('联网搜索暂时不可用，请稍后重试', HIWORK_SEARCH_UNREACHABLE);
+        }
+        const outcome = await gateway.searchWeb(sessionCookie, 
+        // maxResults 是 tool-web 传进来的上限，透传给网关少拉数据（费用按次不按条，
+        // 但少拉条数能压响应体）。seam 仍会在结果侧强制截断，这里只是配合。
+        { query: request.query, ...request.maxResults !== undefined ? { max_results: request.maxResults } : {} }, signal);
+        if (!outcome.ok) {
+            throw outcomeToError(outcome);
+        }
+        const view = projectWebSearch(outcome.body);
+        if (view === undefined) {
+            this.deps.log?.('hiwork-core: 网关返回的 web-search 响应不符合契约（results 缺失或形状不对）');
+            throw new WebError('联网搜索返回了无法解析的结果', 'WEB_PROVIDER_ERROR');
+        }
+        return view;
+    }
+}
+// ---------------------------------------------------------------------------
+// 冻结契约的客户端侧映射：网关错误档 → 稳定 WebError code（tool-web 会透出 code）
+// ---------------------------------------------------------------------------
+/** 未登录 / 会话失效（网关 401，或本地就没有会话）。 */
+export const HIWORK_SEARCH_UNAUTHENTICATED = 'HIWORK_SEARCH_UNAUTHENTICATED';
+/** 管理员还没开启联网搜索（网关 503 SEARCH_DISABLED）。 */
+export const HIWORK_SEARCH_DISABLED = 'HIWORK_SEARCH_DISABLED';
+/** 网关没配上游（网关 503 SEARCH_NOT_CONFIGURED；找运维，不是员工能解决的）。 */
+export const HIWORK_SEARCH_NOT_CONFIGURED = 'HIWORK_SEARCH_NOT_CONFIGURED';
+/** 当日次数用完（网关 429 SEARCH_LIMIT_EXCEEDED）。 */
+export const HIWORK_SEARCH_LIMIT = 'HIWORK_SEARCH_LIMIT';
+/** 网关不可达 / 超时 / 宿主故障（可重试）。 */
+export const HIWORK_SEARCH_UNREACHABLE = 'HIWORK_SEARCH_UNREACHABLE';
+/** 网关代打上游失败（网关 502 SEARCH_UPSTREAM_ERROR；可重试）。 */
+export const HIWORK_SEARCH_UPSTREAM = 'HIWORK_SEARCH_UPSTREAM';
+/** 取消必须按 seam 契约映射成 `WEB_ABORTED`，其余自造 code 消费方都能容忍。 */
+function aborted() {
+    return new WebError('联网搜索已取消', 'WEB_ABORTED');
+}
+/** 传输失败 → WebError：code 分档（消费方按 code 分类文案），message 是给员工看的中文。 */
+function outcomeToError(outcome) {
+    switch (outcome.kind) {
+        case 'aborted':
+            return aborted();
+        case 'network':
+            return new WebError('联网搜索暂时不可用，请稍后重试', HIWORK_SEARCH_UNREACHABLE);
+        case 'invalid':
+            return new WebError('联网搜索返回了无法解析的结果', 'WEB_PROVIDER_ERROR');
+        case 'http':
+            return httpOutcomeToError(outcome.status, outcome.code);
+    }
+}
+/** 非 2xx → WebError：按网关冻结错误码分五档（未知状态兜 provider error）。 */
+function httpOutcomeToError(status, code) {
+    if (status === 401)
+        return new WebError('登录状态已过期，请重新登录', HIWORK_SEARCH_UNAUTHENTICATED);
+    if (code === 'SEARCH_DISABLED')
+        return new WebError('管理员还没开启联网搜索', HIWORK_SEARCH_DISABLED);
+    if (code === 'SEARCH_NOT_CONFIGURED')
+        return new WebError('联网搜索还没有配置好，请联系管理员', HIWORK_SEARCH_NOT_CONFIGURED);
+    if (status === 429 || code === 'SEARCH_LIMIT_EXCEEDED')
+        return new WebError('今天的联网搜索次数已用完，明天再来', HIWORK_SEARCH_LIMIT);
+    if (status === 502 || code === 'SEARCH_UPSTREAM_ERROR')
+        return new WebError('搜索服务暂时不可用，请稍后重试', HIWORK_SEARCH_UPSTREAM);
+    return new WebError('联网搜索暂时不可用，请稍后重试', 'WEB_PROVIDER_ERROR');
+}
+// ---------------------------------------------------------------------------
+// 投影：网关 snake_case → DSH WebSearchResult（全仓唯一做这层转换的地方）
+// ---------------------------------------------------------------------------
+/** 裁掉两侧空白；非字符串或空白串返回 undefined。 */
+function textOrUndefined(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    return text === '' ? undefined : text;
+}
+/**
+ * 响应体 → 归一化结果。
+ *
+ * `results` 缺失或不是数组返回 undefined（契约破坏，调用方报 provider error）；
+ * 单条缺 `url` 的**丢弃**（没法被引用），缺 title/snippet/published_at 的保留其余
+ * 字段（DSH 侧全是可选语义）。`content`（上游网页原文片段）在 snippet 缺席时兜底 ——
+ * 两个都是正文片段，给模型看比给一个空引用强。
+ */
+export function projectWebSearch(body) {
+    const raw = body['results'];
+    if (!Array.isArray(raw))
+        return undefined;
+    const sources = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const record = item;
+        const url = textOrUndefined(record['url']);
+        if (url === undefined)
+            continue;
+        const title = textOrUndefined(record['title']);
+        const snippet = textOrUndefined(record['snippet']) ?? textOrUndefined(record['content']);
+        const publishedAt = textOrUndefined(record['published_at']);
+        sources.push({
+            url,
+            ...title !== undefined ? { title } : {},
+            ...snippet !== undefined ? { snippet } : {},
+            ...publishedAt !== undefined ? { publishedAt } : {},
+        });
+    }
+    // 网关不做答案生成（web_search 端点，不是 chat/completions），content 留空。
+    // 最终 maxResults 截断由 seam 负责，这里恒 truncated: false。
+    return { sources, truncated: false };
+}
+/** 异常类型名（日志只记类型，不记消息，避免把会话相关信息带进日志）。 */
+function errorName(error) {
+    return error instanceof Error ? error.name : typeof error;
+}
+/**
+ * 本端点的出网实现（形状与 `createKnowledgeConfigGateway` 同款：user-agent 带包版本、
+ * 会话 cookie 走 `cookie` 头、外部 signal 与超时经 `AbortSignal.any` 合并）。
+ *
+ * **永不抛异常**：失败收敛成 {@link WebSearchOutcome}。取消（外部 signal 先触发）单独
+ * 分档 —— seam 的取消契约要求它以 `WEB_ABORTED` 上抛，不能被折进「网络故障」。
+ *
+ * `fetchImpl` / `timeoutMs` 仅用于测试注入。
+ */
+export function createWebSearchGateway(baseURL, opts = {}) {
+    const root = baseURL.replace(/\/+$/, '');
+    const timeoutMs = opts.timeoutMs ?? WEB_SEARCH_TIMEOUT_MS;
+    const doFetch = opts.fetchImpl ?? fetch;
+    return {
+        async searchWeb(sessionCookie, body, signal) {
+            const signals = [AbortSignal.timeout(timeoutMs)];
+            if (signal !== undefined)
+                signals.push(signal);
+            const merged = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+            let res;
+            try {
+                res = await doFetch(`${root}${ME_WEB_SEARCH_PATH}`, {
+                    method: 'POST',
+                    headers: {
+                        'user-agent': `hiwork-core/${PKG_VERSION}`,
+                        cookie: sessionCookie,
+                        'content-type': 'application/json',
+                    },
+                    body: JSON.stringify(body),
+                    signal: merged,
+                });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return { ok: false, kind: 'aborted' };
+                // 其余（含超时）一律按网络档；错误原文不进任何返回值。
+                return { ok: false, kind: 'network' };
+            }
+            if (!res.ok) {
+                // 非 2xx 也试着读出冻结错误码（网关的错误体是 {code, message}），读不出就算了：
+                // code 只是分档的辅助，状态码本身已够兜底。
+                let code;
+                try {
+                    const parsed = await res.json();
+                    if (typeof parsed?.code === 'string' && parsed.code !== '')
+                        code = parsed.code;
+                }
+                catch {
+                    // 错误体不是 JSON（反代 5xx 页面等）：状态码兜底。
+                }
+                return { ok: false, kind: 'http', status: res.status, ...code !== undefined ? { code } : {} };
+            }
+            let parsed;
+            try {
+                parsed = await res.json();
+            }
+            catch {
+                return { ok: false, kind: 'invalid' };
+            }
+            if (parsed === null || typeof parsed !== 'object')
+                return { ok: false, kind: 'invalid' };
+            return { ok: true, body: parsed };
+        },
+    };
+}
+/**
+ * 把 provider 注册进 `ctx.web`。注册即挂 fiber（disposer 由 dsh-web 自己挂，见
+ * `WebRuntime.registerProvider`），与 web-search-exa 插件的 apply 同款。
+ * 依赖 `web` 服务在 inject 里声明（dsh-base 基座先于本插件挂载 dsh-web）。
+ */
+export function registerManagedSearchProvider(web, deps) {
+    return web.registerSearchProvider(new HiworkSearchProvider(deps));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiwork-core",
-  "version": "0.0.24",
+  "version": "0.0.29",
   "type": "module",
   "description": "HiWork 企业统一登录与模型自动供给插件（ai-router 网关登录，Web 表单，无 CLI 认证）",
   "license": "UNLICENSED",
@@ -34,7 +34,8 @@
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-api-remotes",
         "@deepseek-ai/dsh-client-ui-primitives",
-        "@deepseek-ai/dsh-client-ui-chat"
+        "@deepseek-ai/dsh-client-ui-chat",
+        "@deepseek-ai/dsh-client-ui-conversation"
       ]
     }
   },
@@ -59,6 +60,7 @@
     "@deepseek-ai/dsh-llm-pi-ai": "0.1.5-rc.1",
     "@deepseek-ai/dsh-settings": "0.1.5-rc.1",
     "@deepseek-ai/dsh-settings-file": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-web": "0.1.5-rc.1",
     "@deepseek-ai/dsh-workspace": "0.1.5-rc.1",
     "@deepseek-ai/schemastery": "3.18.2",
     "@types/node": "^22",
@@ -79,4 +81,4 @@
     "build": "npm run build:host && npm run build:client",
     "test": "vitest run"
   }
-}
+}