hiwork-knowledge 0.1.0 → 0.2.0

package/lib/types/protocol.d.ts

@@ -0,0 +1,200 @@
+/**
+ * `/hiwork-knowledge` loopback RPC 的线上契约（Host 与 Web 共用）。
+ *
+ * 规则：
+ *  - 客户端只提交"意图"，永远不能提交凭据、分数或服务端状态；
+ *  - 请求一律 `.strict()`：多一个字段就 `bad-request`，避免前端悄悄提交 `apiKey`；
+ *  - **凭据单向**：`KnowledgeConfigView` 只有 `hasApiKey` 布尔，没有任何 Key 片段；
+ *  - 命中结果里的 `score` 不进线上契约——实测它在未绑 rerank 时是 RRF 定值（0.0164），
+ *    展示出来只会误导用户（见设计文档 §3.5 / D5）。
+ */
+import { z } from 'zod';
+import { type KnowledgeErrorCode } from './types.js';
+import type { KnowledgeDocumentContent, SelfCheckResult } from './service.js';
+import type { KnowledgeBaseSummary, KnowledgeDocSummary, KnowledgeHit } from './weknora.js';
+/** 频道名；客户端 `runtime.ts` 里有一份字面量副本，由测试锁定一致。 */
+export declare const KNOWLEDGE_RPC_CHANNEL = "/hiwork-knowledge";
+export declare const KNOWLEDGE_RPC_ENDPOINTS: readonly ["snapshot", "config-save", "config-test", "docs", "document", "search"];
+export type KnowledgeRpcEndpoint = (typeof KNOWLEDGE_RPC_ENDPOINTS)[number];
+export declare function isKnowledgeRpcEndpoint(value: string): value is KnowledgeRpcEndpoint;
+export type KnowledgeRpcErrorCode = KnowledgeErrorCode | 'conflict' | 'transport';
+export interface RpcErrorValue {
+    readonly code: KnowledgeRpcErrorCode;
+    readonly message: string;
+    readonly details?: unknown;
+}
+export type RpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: RpcErrorValue;
+};
+/** 知识库视图（与 Host 的 `KnowledgeBaseSummary` 同形，但不含模型 id）。 */
+export interface KnowledgeBaseView {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly documentCount: number | null;
+    readonly chunkCount: number | null;
+    readonly updatedAt: string;
+}
+export interface KnowledgeDocView {
+    readonly id: string;
+    readonly title: string;
+    readonly fileName: string;
+    readonly fileType: string;
+    readonly fileSize: number | null;
+    readonly parseStatus: string;
+    readonly enableStatus: string;
+    readonly summaryStatus: string;
+    readonly folderPath: string;
+    readonly createdAt: string;
+}
+/** 检索命中视图：**不含 score**（口径见文件头注释）。 */
+export interface KnowledgeHitView {
+    readonly chunkId: string;
+    readonly knowledgeId: string;
+    readonly knowledgeTitle: string;
+    readonly fileName: string;
+    readonly chunkIndex: number | null;
+    readonly chunkType: string;
+    readonly content: string;
+    readonly truncated: boolean;
+}
+/**
+ * 文档正文视图（中央页阅读器用）。
+ *
+ * `truncated` 是**多义**的：既可能是「还有下一页」，也可能是「某段被 `maxChunkChars` 裁了」。
+ * 本插件照抄 Host 的口径（`service.readDocument` 就是这么算的），UI 用 `page`/`chunkTotal`
+ * 自己判断还有没有下一页，避免把「正好整页」误报成「已截断」。
+ */
+export interface KnowledgeDocumentView {
+    readonly knowledgeId: string;
+    readonly title: string;
+    readonly chunkTotal: number;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly truncated: boolean;
+    readonly chunks: readonly {
+        readonly index: number | null;
+        readonly type: string;
+        readonly content: string;
+        readonly truncated: boolean;
+    }[];
+}
+export interface KnowledgeSnapshotView {
+    readonly config: {
+        readonly baseUrl: string;
+        readonly tenantId: string;
+        readonly hasApiKey: boolean;
+        readonly apiKeySource: 'settings' | 'env' | 'none';
+        readonly defaultBaseIds: readonly string[];
+        readonly maxResults: number;
+        readonly maxChunkChars: number;
+        readonly agentId: string;
+        readonly chatModelId: string;
+    };
+    readonly selfCheck: SelfCheckResult | null;
+    readonly bases: readonly KnowledgeBaseView[];
+    /** 拉取知识库列表失败时的原因（凭据缺失/后端不可达），成功为 null。 */
+    readonly lastError: string | null;
+    readonly serverNow: string;
+}
+export interface SnapshotRequest {
+    readonly sessionId?: string;
+}
+export interface ConfigSaveRequest {
+    readonly sessionId?: string;
+    readonly patch: {
+        readonly baseUrl?: string | undefined;
+        readonly apiKey?: string | undefined;
+        readonly tenantId?: string | undefined;
+        readonly defaultBaseIds?: readonly string[] | undefined;
+        readonly maxResults?: number | undefined;
+        readonly maxChunkChars?: number | undefined;
+        readonly agentId?: string | undefined;
+        readonly chatModelId?: string | undefined;
+    };
+}
+export interface ConfigTestRequest {
+    readonly sessionId?: string;
+}
+export interface DocsRequest {
+    readonly sessionId?: string;
+    readonly baseId: string;
+}
+export interface DocumentRequest {
+    readonly sessionId?: string;
+    readonly knowledgeId: string;
+    readonly page?: number | undefined;
+}
+export interface SearchRequest {
+    readonly sessionId?: string;
+    readonly query: string;
+    readonly baseId?: string | undefined;
+}
+export interface ConfigSaveResponse {
+    readonly config: KnowledgeSnapshotView['config'];
+}
+export interface ConfigTestResponse {
+    readonly selfCheck: SelfCheckResult;
+}
+export interface DocsResponse {
+    readonly baseId: string;
+    readonly docs: readonly KnowledgeDocView[];
+}
+export interface DocumentResponse {
+    readonly document: KnowledgeDocumentView;
+}
+export interface SearchResponse {
+    readonly query: string;
+    readonly hits: readonly KnowledgeHitView[];
+}
+/** 把 Host 的结构投影成线上视图（剥掉凭据与分数）。 */
+export declare function toBaseView(base: KnowledgeBaseSummary): KnowledgeBaseView;
+export declare function toDocView(doc: KnowledgeDocSummary): KnowledgeDocView;
+export declare function toDocumentView(document: KnowledgeDocumentContent): KnowledgeDocumentView;
+export declare function toHitView(hit: KnowledgeHit, maxChunkChars: number): KnowledgeHitView;
+export declare const snapshotRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** 设置补丁：字段全部可选，但**不接受 schema 之外任何字段**（尤其是不允许未知键）。 */
+export declare const configSaveRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    patch: z.ZodObject<{
+        baseUrl: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        tenantId: z.ZodOptional<z.ZodString>;
+        defaultBaseIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxResults: z.ZodOptional<z.ZodNumber>;
+        maxChunkChars: z.ZodOptional<z.ZodNumber>;
+        agentId: z.ZodOptional<z.ZodString>;
+        chatModelId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const configTestRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 页码上限 500：翻到第 500 页还没找到想看的内容，说明该换个检索词而不是继续翻，
+ * 而一个不带上限的 `page` 能让 `(page-1)*pageSize` 溢出成负索引。
+ */
+export declare const documentRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    knowledgeId: z.ZodString;
+    page: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const docsRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    baseId: z.ZodString;
+}, z.core.$strict>;
+export declare const searchRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    query: z.ZodString;
+    baseId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** 任意异常 → 稳定 `{ code, message }`；未知异常降级为 `internal`。 */
+export declare function toRpcErrorValue(error: unknown, aborted?: boolean): RpcErrorValue;
+/** 解信封（客户端用；同样只认 `{ ok, value | error }`）。 */
+export declare function unwrapRpcResult<T>(value: unknown): T;

package/lib/types/rpc.d.ts

@@ -0,0 +1,18 @@
+import { type KnowledgeSnapshotView } from './protocol.js';
+import type { KnowledgeService } from './service.js';
+/** Host 侧 RPC 依赖的最小上下文（结构兼容，便于单测伪造）。 */
+export interface KnowledgeRpcContext {
+    readonly logger: {
+        warn(message: string): void;
+    };
+    readonly connection: {
+        rpc: {
+            handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+                authority: 'loopback';
+            }): () => Promise<void> | void;
+        };
+    };
+}
+/** 组装快照：凭据视图 + 知识库列表 + （可选）上次自检结果。 */
+export declare function buildSnapshot(service: KnowledgeService, signal: AbortSignal, selfCheck?: KnowledgeSnapshotView['selfCheck']): Promise<KnowledgeSnapshotView>;
+export declare function registerKnowledgeRpc(ctx: KnowledgeRpcContext, service: KnowledgeService): () => Promise<void>;

package/lib/types/service.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Host 侧知识库服务：凭据解析、WeKnora 调用、自检。
+ *
+ * 不变量：
+ *  - **凭据只在这里落地**：读取（存储域 / 环境变量 / bundle 默认）与使用（拼请求头）都在
+ *    Host 半边，Web 半边只看得到 `hasApiKey` 这类布尔；
+ *  - 出网客户端按「有效配置」缓存，配置一变（保存设置）立刻重建，避免用旧 Key 打后端；
+ *  - 自检分两层：**连接**（认证 + 列库）与**检索健康**（探针词是否命中、分数是否像重排分）。
+ *    后者是必须的——实测未绑重排模型时后端会"静默给错结果"（任意查询返回同一分块、
+ *    分数恒为 RRF 值），HTTP 层完全看不出来；
+ *  - 所有对外方法都接受 `AbortSignal` 并把它透传到出网调用。
+ */
+import { knowledgeDomainSpec, type KnowledgeConfig } from './types.js';
+import { type KnowledgeAnswer, type KnowledgeBaseSummary, type KnowledgeDocSummary, type KnowledgeHit, type WeKnoraClient, type WeKnoraTransport } from './weknora.js';
+/** 存储表端口（结构兼容 `@deepseek-ai/dsh-storage-domain` 的 KvTable）。 */
+export interface KnowledgeStorageTable<T = unknown> {
+    get(key: string): T | undefined;
+    entries(): IterableIterator<[string, T]>;
+    put(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+/** 已打开的存储域端口。 */
+export interface KnowledgeStorageDomain {
+    readonly name: string;
+    table(name: string): KnowledgeStorageTable;
+    close(): Promise<void>;
+}
+/** Host 服务需要的最小上下文端口（不 import cordis 运行时，便于单测伪造）。 */
+export interface KnowledgeHostContext {
+    readonly logger: {
+        warn(message: string): void;
+    };
+    readonly storageDomain: {
+        open(spec: typeof knowledgeDomainSpec): Promise<KnowledgeStorageDomain>;
+    };
+}
+/** 自检单条断言。 */
+export interface SelfCheckItem {
+    readonly code: string;
+    readonly ok: boolean;
+    /** `error` 阻止使用；`warn` 可用但结果可能不准；`info` 仅提示。 */
+    readonly level: 'error' | 'warn' | 'info';
+    readonly message: string;
+}
+/** 自检汇总。 */
+export interface SelfCheckResult {
+    readonly ok: boolean;
+    readonly level: 'ok' | 'warn' | 'error';
+    readonly items: readonly SelfCheckItem[];
+    readonly baseCount: number;
+    readonly checkedAt: string;
+}
+/** 设置页可见的配置投影（**不含 `apiKey` 明文**）。 */
+export interface KnowledgeConfigView {
+    readonly baseUrl: string;
+    readonly tenantId: string;
+    readonly hasApiKey: boolean;
+    /** 凭据来源，便于用户判断"我填的 Key 到底生效没有"。 */
+    readonly apiKeySource: 'settings' | 'env' | 'none';
+    readonly defaultBaseIds: readonly string[];
+    readonly maxResults: number;
+    readonly maxChunkChars: number;
+    readonly agentId: string;
+    readonly chatModelId: string;
+}
+/** 文档正文（阅读器/工具共用）。 */
+export interface KnowledgeDocumentContent {
+    readonly knowledgeId: string;
+    readonly title: string;
+    readonly chunkTotal: number;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly truncated: boolean;
+    readonly chunks: readonly {
+        readonly index: number | null;
+        readonly type: string;
+        readonly content: string;
+        readonly truncated: boolean;
+    }[];
+}
+/** 设置页提交的补丁：只接受 schema 里的字段，全部可选。 */
+export type KnowledgeConfigPatch = Partial<KnowledgeConfig>;
+/** 把用户补丁合并进当前配置，并校验（非法输入抛 `bad-request`）。 */
+export declare function mergeConfig(current: KnowledgeConfig, patch: KnowledgeConfigPatch): KnowledgeConfig;
+/** 把片段截断到 `maxChunkChars`，并显式报告是否截断（不静默丢内容）。 */
+export declare function clipContent(content: string, limit: number): {
+    text: string;
+    truncated: boolean;
+};
+/** 知识库服务。 */
+export declare class KnowledgeService {
+    private readonly ctx;
+    private domain;
+    private stored;
+    private bundleDefault;
+    private cached;
+    private constructor();
+    /** 打开存储域并读回已保存的设置。 */
+    static open(ctx: KnowledgeHostContext, bundleDefault?: KnowledgeConfigPatch): Promise<KnowledgeService>;
+    dispose(): Promise<void>;
+    /** 有效凭据来源（存储域 > 环境变量 > 默认空）。 */
+    apiKeySource(): KnowledgeConfigView['apiKeySource'];
+    /** 有效配置（含明文 Key，仅 Host 内部使用）。 */
+    effectiveConfig(): KnowledgeConfig;
+    /** 设置页视图：剥掉凭据明文。 */
+    getConfigView(): KnowledgeConfigView;
+    /**
+     * 保存设置补丁。
+     *
+     * 空字符串 = 显式清空；`undefined` = 保持原值。写盘后立刻丢弃缓存的客户端。
+     */
+    saveConfig(patch: KnowledgeConfigPatch): Promise<KnowledgeConfigView>;
+    /** 出网客户端（按有效配置缓存）。 */
+    client(): WeKnoraClient;
+    /** 需要凭据的调用统一先过这道门；没配 Key 时给出可执行的提示。 */
+    private requireCredentials;
+    private requireDomain;
+    listBases(signal?: AbortSignal): Promise<readonly KnowledgeBaseSummary[]>;
+    listDocs(baseId: string, signal?: AbortSignal): Promise<readonly KnowledgeDocSummary[]>;
+    search(query: string, scope?: {
+        readonly baseIds?: readonly string[] | undefined;
+        readonly knowledgeIds?: readonly string[] | undefined;
+    }, signal?: AbortSignal): Promise<readonly KnowledgeHit[]>;
+    /** 读一篇文档：分块 + 标题，按 `chunkIndex` 顺序拼装并分页。 */
+    readDocument(knowledgeId: string, options?: {
+        readonly page?: number | undefined;
+        readonly pageSize?: number | undefined;
+    }, signal?: AbortSignal): Promise<KnowledgeDocumentContent>;
+    /** 问答：固定走 `/knowledge-chat` + 自建 Agent（内置 agent 缺 model_id，必失败）。 */
+    ask(query: string, scope?: {
+        readonly baseIds?: readonly string[];
+    }, signal?: AbortSignal): Promise<KnowledgeAnswer>;
+    /**
+     * 自检：连接 + 检索健康 + 问答可用性。
+     *
+     * 检索健康探针用「第一个可见知识库的第一篇文档标题」当查询词——它一定命中自己，
+     * 因此「命中 0 条」只可能是配置问题（未绑重排 / 模型 id 失效），不是数据问题。
+     */
+    selfCheck(signal?: AbortSignal): Promise<SelfCheckResult>;
+}
+/** 单测/自检用：注入自定义出网的临时客户端工厂。 */
+export declare function clientForTest(config: KnowledgeConfig, transport: WeKnoraTransport): WeKnoraClient;

package/lib/types/tool-names.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 知识库工具名（**单一事实源**）。
+ *
+ * Host 半边用它注册工具，Web 半边用它认领 `tool.call.toolview` 的 keyed 座位——
+ * 两边各写一份就会漂移，而 keyed 座位的漂移是**静默**的（拼错不抛错，只是卡片永远不渲染）。
+ *
+ * 本文件零依赖：client bundle 是自包含的，共享模块不能引任何东西进来。
+ */
+/** 4 个只读工具（顺序即注册顺序）。 */
+export declare const KNOWLEDGE_TOOL_NAMES: readonly ["knowledge_list_bases", "knowledge_search", "knowledge_read_document", "knowledge_ask"];
+export type KnowledgeToolName = (typeof KNOWLEDGE_TOOL_NAMES)[number];

package/lib/types/tools.d.ts

@@ -0,0 +1,21 @@
+import { KNOWLEDGE_TOOL_NAMES } from './tool-names.js';
+import type { KnowledgeService } from './service.js';
+export { KNOWLEDGE_TOOL_NAMES };
+/** 注册工具所需的最小 Agent 结构端口（不 import DSH agent 运行时）。 */
+export type KnowledgeAgent = {
+    readonly id: string;
+    readonly ctx: {
+        readonly tools: {
+            register(definition: unknown): () => void;
+        };
+    };
+};
+/**
+ * 给一个根 Agent 注册知识库工具。
+ * @param service - Host 侧知识库服务。
+ * @param agent - 目标根 Agent。
+ * @returns 注销器（注销全部已注册工具）。
+ */
+export declare function registerKnowledgeTools(service: KnowledgeService, agent: KnowledgeAgent): () => void;
+/** 供测试断言：工具说明里必须出现的行为约束。 */
+export declare const KNOWLEDGE_TOOL_GUIDE_TEXT = "\u77E5\u8BC6\u5E93\u68C0\u7D22\u8FD4\u56DE 0 \u6761\u65F6\uFF0C\u5982\u5B9E\u8BF4\u660E\u60C5\u51B5\uFF0C\u4E0D\u8981\u51ED\u5E38\u8BC6\u4F5C\u7B54\uFF1B\u5F15\u7528\u7ED3\u8BBA\u5FC5\u987B\u9644\u51FA\u5904\u3002";

package/lib/types/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `hiwork-knowledge` Host 半边的领域类型、默认值与存储域定义。
+ *
+ * 不变量：
+ *  - 存储域名字必须匹配 `/^[a-z][a-z0-9_]*$/`（不能带连字符），改名等于换一套表；
+ *  - 凭据（`apiKey`）只在 Host 半边流转：落盘在存储域、下发 WeKnora 时只进请求头，
+ *    **绝不进日志、绝不回传给 Web 半边**（`toConfigView` 只回 `hasApiKey` 布尔）；
+ *  - 默认值与本节常量一一对应，`cordis.patch.yml` 的 config 只能收紧、不能放宽
+ *    （例如把 `maxChunkChars` 调大仍受 schema 上限约束）。
+ */
+import { z } from 'zod';
+/** `ctx.storageDomain.open()` 的域标识；必须保持稳定。 */
+export declare const KNOWLEDGE_DOMAIN_NAME = "hiwork_knowledge";
+export declare const KNOWLEDGE_DOMAIN_VERSION = 1;
+/** 设置只有一条记录，键名固定。 */
+export declare const KNOWLEDGE_SETTINGS_KEY = "config";
+/** 默认后端地址：与部署文档里的域名一致（`/api/v1` 会被补齐）。 */
+export declare const DEFAULT_BASE_URL = "https://hiwork-knowledge.hivery.cn/api/v1";
+export declare const DEFAULT_MAX_RESULTS = 8;
+export declare const DEFAULT_MAX_CHUNK_CHARS = 1200;
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+export declare const DEFAULT_CHAT_TIMEOUT_MS = 300000;
+/** 检索结果条数上限（服务端受 `rerank_threshold` 约束，这里只做客户端截断）。 */
+export declare const MAX_RESULTS_CEILING = 50;
+/** 单条片段字符上限。 */
+export declare const MAX_CHUNK_CHARS_CEILING = 8000;
+export declare const MAX_BASE_IDS = 50;
+/**
+ * 「重排未生效」的分数判据。
+ *
+ * 2026-09-18 实测（同一后端、同一知识库）：
+ *  - 租户检索配置绑好 `rerank_model_id` 时，命中分数落在 **0.43–0.59**；
+ *  - 未绑时管线 `Rerank action=skip reason="empty_model_id"`，分数是 RRF 融合值
+ *    **0.0164**（且任意查询都返回同一个分块）。
+ * 因此「最高分 < 0.05」可作为「检索结果未经重排」的稳定信号，用于自检告警。
+ */
+export declare const RRF_SCORE_CEILING = 0.05;
+/** 自检探针最多检查的知识库数（避免一次自检打穿后端）。 */
+export declare const SELF_CHECK_BASE_LIMIT = 3;
+export declare const knowledgeConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodString;
+    apiKey: z.ZodString;
+    tenantId: z.ZodString;
+    defaultBaseIds: z.ZodArray<z.ZodString>;
+    maxResults: z.ZodNumber;
+    maxChunkChars: z.ZodNumber;
+    requestTimeoutMs: z.ZodNumber;
+    chatTimeoutMs: z.ZodNumber;
+    agentId: z.ZodString;
+    chatModelId: z.ZodString;
+}, z.core.$strict>;
+export type KnowledgeConfig = z.infer<typeof knowledgeConfigSchema>;
+/** 默认配置：域名来自部署文档，凭据留空由用户在设置页填。 */
+export declare const DEFAULT_KNOWLEDGE_CONFIG: KnowledgeConfig;
+/**
+ * 把用户输入的地址补齐成 `<origin>/api/v1` 形态。
+ *
+ * 只做补路径与去尾斜杠，不猜测协议（缺协议时由 `fetch` 报错，错误信息里带上原值，
+ * 比 Host 静默拼一个 `https://` 更好排查）。
+ */
+export declare function normalizeBaseUrl(raw: string): string;
+/** 凭据/网络类错误的稳定分类；RPC 与工具都把异常映射成这些码。 */
+export type KnowledgeErrorCode = 'misconfigured' | 'unauthorized' | 'not-found' | 'bad-request' | 'unreachable' | 'timeout' | 'cancelled' | 'internal';
+/** Host 侧统一异常：携带稳定 code 与**不含凭据**的 message。 */
+export declare class KnowledgeError extends Error {
+    readonly code: KnowledgeErrorCode;
+    constructor(code: KnowledgeErrorCode, message: string);
+}
+/** 存储域的一条设置记录（带版本戳，便于将来迁移）。 */
+export declare const knowledgeSettingsRecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    config: z.ZodObject<{
+        baseUrl: z.ZodString;
+        apiKey: z.ZodString;
+        tenantId: z.ZodString;
+        defaultBaseIds: z.ZodArray<z.ZodString>;
+        maxResults: z.ZodNumber;
+        maxChunkChars: z.ZodNumber;
+        requestTimeoutMs: z.ZodNumber;
+        chatTimeoutMs: z.ZodNumber;
+        agentId: z.ZodString;
+        chatModelId: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type KnowledgeSettingsRecord = z.infer<typeof knowledgeSettingsRecordSchema>;
+/** `storageDomain.open()` 的域描述。 */
+export declare const knowledgeDomainSpec: {
+    readonly name: "hiwork_knowledge";
+    readonly version: 1;
+    readonly tables: {
+        readonly settings: {
+            readonly valueSchema: z.ZodObject<{
+                version: z.ZodLiteral<1>;
+                config: z.ZodObject<{
+                    baseUrl: z.ZodString;
+                    apiKey: z.ZodString;
+                    tenantId: z.ZodString;
+                    defaultBaseIds: z.ZodArray<z.ZodString>;
+                    maxResults: z.ZodNumber;
+                    maxChunkChars: z.ZodNumber;
+                    requestTimeoutMs: z.ZodNumber;
+                    chatTimeoutMs: z.ZodNumber;
+                    agentId: z.ZodString;
+                    chatModelId: z.ZodString;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+        };
+    };
+};

package/lib/types/weknora.d.ts

@@ -0,0 +1,112 @@
+/**
+ * WeKnora REST 客户端（Host 半边专用）。
+ *
+ * 设计要点：
+ *  - 只实现 M0 需要的只读端点 + 问答（SSE）；写操作（上传/删除）在 M2 才开；
+ *  - 所有出网调用都带超时：`requestTimeoutMs` 给普通请求，`chatTimeoutMs` 给问答；
+ *  - **实测行为**：后端在出错时**不主动关闭 SSE 流**（连接会一直挂着），
+ *    因此问答循环必须在收到 `response_type=error` 时立刻主动 abort；
+ *  - 解析对形状容错（`data` 既可能是数组也可能是 `{items,total}`），但**不臆造字段**：
+ *    缺字段就是 `undefined`，由上层决定如何展示；
+ *  - 错误一律映射成 `KnowledgeError`，message 里带上 HTTP 状态与 WeKnora 的原始理由，
+ *    但**永不回显 API Key**。
+ */
+import { type KnowledgeConfig } from './types.js';
+/** 知识库摘要（列表页用）。 */
+export interface KnowledgeBaseSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly documentCount: number | null;
+    readonly chunkCount: number | null;
+    readonly embeddingModelId: string;
+    readonly summaryModelId: string;
+    readonly updatedAt: string;
+}
+/** 文档摘要（知识库详情页用）。 */
+export interface KnowledgeDocSummary {
+    readonly id: string;
+    readonly title: string;
+    readonly fileName: string;
+    readonly fileType: string;
+    readonly fileSize: number | null;
+    /** `pending` / `processing` / `finalizing` / `completed` / `failed` / `cancelled`。 */
+    readonly parseStatus: string;
+    /** `enabled` / `disabled`。 */
+    readonly enableStatus: string;
+    /** `none` / `processing` / `completed` / `failed`。 */
+    readonly summaryStatus: string;
+    readonly folderPath: string;
+    readonly createdAt: string;
+}
+/** 一条检索命中。 */
+export interface KnowledgeHit {
+    readonly chunkId: string;
+    readonly content: string;
+    readonly knowledgeId: string;
+    readonly chunkIndex: number | null;
+    readonly knowledgeTitle: string;
+    readonly fileName: string;
+    /** 重排后的分数（未绑 rerank 时是 RRF 值，见 `RRF_SCORE_CEILING`）。 */
+    readonly score: number | null;
+    readonly chunkType: string;
+    readonly startAt: number | null;
+    readonly endAt: number | null;
+}
+/** 问答引用（来自 SSE 的 `references` 帧）。 */
+export interface KnowledgeReference {
+    readonly chunkId: string;
+    readonly content: string;
+    readonly knowledgeId: string;
+    readonly chunkIndex: number | null;
+    readonly knowledgeTitle: string;
+    readonly chunkType: string;
+    readonly startAt: number | null;
+    readonly endAt: number | null;
+}
+/** 问答结果（SSE 收敛成一次性结果）。 */
+export interface KnowledgeAnswer {
+    readonly answer: string;
+    readonly references: readonly KnowledgeReference[];
+    readonly sessionId: string;
+    /** 命中的工具调用名（如 `knowledge_search`），便于向用户解释耗时。 */
+    readonly toolsUsed: readonly string[];
+    readonly elapsedMs: number;
+}
+/** 自检结果。 */
+export interface ProbeResult {
+    readonly ok: boolean;
+    readonly code: string;
+    readonly message: string;
+    readonly baseCount?: number;
+}
+/** 出网端口；单测直接注入假实现，无需起 HTTP 服务。 */
+export interface WeKnoraTransport {
+    (input: string, init: RequestInit): Promise<Response>;
+}
+/** 客户端端口（服务层与工具层都只依赖它）。 */
+export interface WeKnoraClient {
+    listBases(signal?: AbortSignal): Promise<readonly KnowledgeBaseSummary[]>;
+    listDocs(baseId: string, signal?: AbortSignal): Promise<readonly KnowledgeDocSummary[]>;
+    getDoc(knowledgeId: string, signal?: AbortSignal): Promise<KnowledgeDocSummary | null>;
+    chunks(knowledgeId: string, signal?: AbortSignal): Promise<readonly KnowledgeHit[]>;
+    search(query: string, scope: {
+        readonly baseIds?: readonly string[];
+        readonly knowledgeIds?: readonly string[];
+    }, signal?: AbortSignal): Promise<readonly KnowledgeHit[]>;
+    ask(query: string, scope: {
+        readonly baseIds?: readonly string[];
+    }, signal?: AbortSignal): Promise<KnowledgeAnswer>;
+    capabilities(signal?: AbortSignal): Promise<Readonly<Record<string, {
+        supported: boolean;
+        reason?: string;
+    }>>>;
+}
+/**
+ * 创建 WeKnora 客户端。
+ * @param config - 凭据与超时配置（`baseUrl` 会先归一化）。
+ * @param transport - 出网实现；缺省用全局 `fetch`（Node 24 自带）。
+ */
+export declare function createWeKnoraClient(config: KnowledgeConfig, transport?: WeKnoraTransport): WeKnoraClient;
+/** 自检用：不带任何业务查询地探测后端可达性与凭据（`GET /knowledge-bases`）。 */
+export declare function probeConnection(config: KnowledgeConfig, transport?: WeKnoraTransport, signal?: AbortSignal): Promise<ProbeResult>;