hiwork-core 0.0.22 → 0.0.29

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.22",
+  "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"
   }
-}
+}