hiwork-knowledge 0.1.1 → 0.2.0

package/lib/prompt.js

@@ -0,0 +1,31 @@
+/**
+ * 知识库相关的系统提示词片段与工具使用指引。
+ *
+ * 为什么需要这段：DSH 自带的能力只覆盖工作区（`grep`/`glob`）与公网（`web_search`），
+ * 企业文档既不在工作区、也不该走公网。模型不知道有企业知识库时，会直接回答"我查不到"
+ * 或者凭常识编。片段的作用是**告诉它先去查**，以及别把「配置问题导致的 0 命中」当成
+ * 「企业没有这个资料」。
+ *
+ * 引用格式是**强制**的（`CITATION_RULE`）：知识库的答案是给同事看的，没有出处的答案在
+ * 内部场景里等于不可用——用户没法核对，也没法顺着找原文。格式刻意对齐聊天卡片展示的
+ * 信息（文档标题 + 段号），两者能直接对上。
+ */
+/** 系统提示词段落名（稳定值，便于用户按名字关闭）。 */
+export const KNOWLEDGE_PROMPT_NAME = 'hiwork-knowledge';
+/** 排序权重：排在通用工作区规则之后、具体业务插件之前。 */
+export const KNOWLEDGE_PROMPT_ORDER = 62;
+/** 引用格式：与聊天卡片展示的「文档标题 · 段号」一致，用户据此核对原文。 */
+export const CITATION_RULE = '引用出处时必须写成 `依据：<文档标题> · 第 N 段`（照抄检索结果里的标题与段号，不要改写标题）；' +
+    '一条结论有多个依据就逐条列在同一行、用「；」分隔；没有检索到依据就不要给结论。';
+export const KNOWLEDGE_PROMPT_TEXT = [
+    '企业知识库（WeKnora）已接入桌面端，涉及公司制度、产品资料、内部文档的问题，先查知识库再回答：',
+    '- `knowledge_list_bases` 列出可见知识库；不确定范围时先调它；',
+    '- `knowledge_search` 返回原文片段（含文档标题与段号），是主要入口；',
+    '- `knowledge_read_document` 读某篇文档的上下文；',
+    '- `knowledge_ask` 把问题整体交给知识库问答链路，返回带引用的结论（慢，适合综述型问题）。',
+    CITATION_RULE,
+    '知识库检索「返回 0 条」可能是后端检索配置问题（未绑 rerank 模型，或重排阈值过高把相关片段整体滤掉），',
+    '遇到时如实说明并建议检查，不要据此断定公司没有相关规定，也不要凭常识补答案。',
+].join('\n');
+/** 工具说明里引用的行为约束（测试会断言它出现在工具描述中）。 */
+export const KNOWLEDGE_TOOL_GUIDE = '知识库检索返回 0 条时，如实说明情况，不要凭常识作答；引用结论必须附出处。';

package/lib/protocol.js

@@ -0,0 +1,139 @@
+/**
+ * `/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 { KnowledgeError } from './types.js';
+/** 频道名；客户端 `runtime.ts` 里有一份字面量副本，由测试锁定一致。 */
+export const KNOWLEDGE_RPC_CHANNEL = '/hiwork-knowledge';
+export const KNOWLEDGE_RPC_ENDPOINTS = ['snapshot', 'config-save', 'config-test', 'docs', 'document', 'search'];
+export function isKnowledgeRpcEndpoint(value) {
+    return KNOWLEDGE_RPC_ENDPOINTS.includes(value);
+}
+/** 把 Host 的结构投影成线上视图（剥掉凭据与分数）。 */
+export function toBaseView(base) {
+    return {
+        id: base.id,
+        name: base.name,
+        description: base.description,
+        documentCount: base.documentCount,
+        chunkCount: base.chunkCount,
+        updatedAt: base.updatedAt,
+    };
+}
+export function toDocView(doc) {
+    return {
+        id: doc.id,
+        title: doc.title,
+        fileName: doc.fileName,
+        fileType: doc.fileType,
+        fileSize: doc.fileSize,
+        parseStatus: doc.parseStatus,
+        enableStatus: doc.enableStatus,
+        summaryStatus: doc.summaryStatus,
+        folderPath: doc.folderPath,
+        createdAt: doc.createdAt,
+    };
+}
+export function toDocumentView(document) {
+    return {
+        knowledgeId: document.knowledgeId,
+        title: document.title,
+        chunkTotal: document.chunkTotal,
+        page: document.page,
+        pageSize: document.pageSize,
+        truncated: document.truncated,
+        chunks: document.chunks.map(chunk => ({
+            index: chunk.index,
+            type: chunk.type,
+            content: chunk.content,
+            truncated: chunk.truncated,
+        })),
+    };
+}
+export function toHitView(hit, maxChunkChars) {
+    const truncated = hit.content.length > maxChunkChars;
+    return {
+        chunkId: hit.chunkId,
+        knowledgeId: hit.knowledgeId,
+        knowledgeTitle: hit.knowledgeTitle,
+        fileName: hit.fileName,
+        chunkIndex: hit.chunkIndex,
+        chunkType: hit.chunkType,
+        content: truncated ? hit.content.slice(0, maxChunkChars) : hit.content,
+        truncated,
+    };
+}
+const optionalSessionId = z.string().trim().min(1).optional();
+export const snapshotRequestSchema = z.object({ sessionId: optionalSessionId }).strict();
+/** 设置补丁：字段全部可选，但**不接受 schema 之外任何字段**（尤其是不允许未知键）。 */
+export const configSaveRequestSchema = z
+    .object({
+    sessionId: optionalSessionId,
+    patch: z
+        .object({
+        baseUrl: z.string().optional(),
+        apiKey: z.string().optional(),
+        tenantId: z.string().optional(),
+        defaultBaseIds: z.array(z.string()).optional(),
+        maxResults: z.number().int().optional(),
+        maxChunkChars: z.number().int().optional(),
+        agentId: z.string().optional(),
+        chatModelId: z.string().optional(),
+    })
+        .strict(),
+})
+    .strict();
+export const configTestRequestSchema = z.object({ sessionId: optionalSessionId }).strict();
+/**
+ * 页码上限 500：翻到第 500 页还没找到想看的内容，说明该换个检索词而不是继续翻，
+ * 而一个不带上限的 `page` 能让 `(page-1)*pageSize` 溢出成负索引。
+ */
+export const documentRequestSchema = z
+    .object({
+    sessionId: optionalSessionId,
+    knowledgeId: z.string().trim().min(1),
+    page: z.number().int().min(1).max(500).optional(),
+})
+    .strict();
+export const docsRequestSchema = z.object({ sessionId: optionalSessionId, baseId: z.string().trim().min(1) }).strict();
+export const searchRequestSchema = z
+    .object({ sessionId: optionalSessionId, query: z.string().trim().min(1), baseId: z.string().trim().min(1).optional() })
+    .strict();
+/** 任意异常 → 稳定 `{ code, message }`；未知异常降级为 `internal`。 */
+export function toRpcErrorValue(error, aborted = false) {
+    if (aborted)
+        return { code: 'cancelled', message: '知识库请求已取消。' };
+    if (error instanceof KnowledgeError)
+        return { code: error.code, message: error.message };
+    if (error instanceof z.ZodError) {
+        const issue = error.issues[0];
+        const path = issue?.path.join('.') ?? '';
+        return {
+            code: 'bad-request',
+            message: path === '' ? (issue?.message ?? '请求参数不合法。') : `${path}: ${issue?.message ?? '不合法'}`,
+            details: { issues: error.issues.map(item => ({ path: item.path.join('.'), message: item.message })) },
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { code: 'internal', message: message === '' ? '知识库服务暂时不可用。' : message };
+}
+/** 解信封（客户端用；同样只认 `{ ok, value | error }`）。 */
+export function unwrapRpcResult(value) {
+    if (typeof value !== 'object' || value === null || !('ok' in value)) {
+        throw new Error('知识库主机返回了无效响应。');
+    }
+    const result = value;
+    if (result.ok === true && 'value' in result)
+        return result.value;
+    if (result.ok === false && 'error' in result) {
+        throw new Error(result.error?.message ?? '知识库请求失败。');
+    }
+    throw new Error('知识库主机返回了无效响应。');
+}

package/lib/rpc.js

@@ -0,0 +1,103 @@
+/**
+ * `/hiwork-knowledge` loopback RPC 的 Host 实现。
+ *
+ * 规则：
+ *  - 只注册一个频道，endpoint 白名单来自 `protocol.ts`，未知 endpoint 直接 `bad-request`；
+ *  - 每个 payload 先过 `.strict()` schema：客户端**无法**通过 RPC 提交凭据或分数；
+ *  - `snapshot` 永不抛错：列库失败时把原因放进 `lastError`（视图要能把"没配 Key"
+ *    和"后端挂了"分开显示），其余端点校验失败即返回稳定错误；
+ *  - `config-test` 才跑自检（会真实打后端 + 探针检索），避免每次打开页面都打穿后端。
+ */
+import { KnowledgeError } from './types.js';
+import { KNOWLEDGE_RPC_CHANNEL, configSaveRequestSchema, configTestRequestSchema, docsRequestSchema, documentRequestSchema, isKnowledgeRpcEndpoint, searchRequestSchema, snapshotRequestSchema, toBaseView, toDocView, toDocumentView, toHitView, toRpcErrorValue, } from './protocol.js';
+function ok(value) {
+    return { ok: true, value };
+}
+/** 组装快照：凭据视图 + 知识库列表 + （可选）上次自检结果。 */
+export async function buildSnapshot(service, signal, selfCheck = null) {
+    const config = service.getConfigView();
+    let bases = [];
+    let lastError = null;
+    if (!config.hasApiKey) {
+        lastError = '尚未配置 WeKnora API Key：请在下方填写后点「测试连接」。';
+    }
+    else {
+        try {
+            bases = (await service.listBases(signal)).map(toBaseView);
+        }
+        catch (error) {
+            lastError = error instanceof KnowledgeError ? error.message : String(error);
+        }
+    }
+    return {
+        config,
+        selfCheck,
+        bases,
+        lastError,
+        serverNow: new Date().toISOString(),
+    };
+}
+export function registerKnowledgeRpc(ctx, service) {
+    const handler = async (endpoint, rawPayload, signal) => {
+        try {
+            if (!isKnowledgeRpcEndpoint(endpoint)) {
+                throw new KnowledgeError('bad-request', `未知的知识库端点 '${endpoint}'`);
+            }
+            switch (endpoint) {
+                case 'snapshot': {
+                    snapshotRequestSchema.parse(rawPayload);
+                    return ok(await buildSnapshot(service, signal));
+                }
+                case 'config-save': {
+                    const payload = configSaveRequestSchema.parse(rawPayload);
+                    const config = await service.saveConfig(payload.patch);
+                    const value = { config };
+                    return ok(value);
+                }
+                case 'config-test': {
+                    configTestRequestSchema.parse(rawPayload);
+                    const selfCheck = await service.selfCheck(signal);
+                    const value = { selfCheck };
+                    return ok(value);
+                }
+                case 'docs': {
+                    const payload = docsRequestSchema.parse(rawPayload);
+                    const docs = await service.listDocs(payload.baseId, signal);
+                    const value = { baseId: payload.baseId, docs: docs.map(toDocView) };
+                    return ok(value);
+                }
+                case 'document': {
+                    const payload = documentRequestSchema.parse(rawPayload);
+                    const document = await service.readDocument(payload.knowledgeId, payload.page === undefined ? {} : { page: payload.page }, signal);
+                    const value = { document: toDocumentView(document) };
+                    return ok(value);
+                }
+                case 'search': {
+                    const payload = searchRequestSchema.parse(rawPayload);
+                    const maxChunkChars = service.effectiveConfig().maxChunkChars;
+                    const hits = await service.search(payload.query, payload.baseId === undefined ? {} : { baseIds: [payload.baseId] }, signal);
+                    const value = {
+                        query: payload.query,
+                        hits: hits.map(hit => toHitView(hit, maxChunkChars)),
+                    };
+                    return ok(value);
+                }
+            }
+            throw new KnowledgeError('bad-request', `未知的知识库端点 '${endpoint}'`);
+        }
+        catch (error) {
+            const failure = toRpcErrorValue(error, signal.aborted);
+            // DSH Connection 的响应信封要求 error.details 是对象；协议里它是可选的，
+            // 这里补空对象，避免客户端 SDK 的 schema 校验拒绝整个响应。
+            const value = failure.details === undefined ? { ...failure, details: {} } : failure;
+            if (value.code === 'internal') {
+                ctx.logger.warn(`hiwork-knowledge: RPC '${endpoint}' 失败：${value.message}`);
+            }
+            return { ok: false, error: value };
+        }
+    };
+    const remove = ctx.connection.rpc.handle(KNOWLEDGE_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => {
+        await remove();
+    };
+}

package/lib/service.js

@@ -0,0 +1,344 @@
+/**
+ * Host 侧知识库服务：凭据解析、WeKnora 调用、自检。
+ *
+ * 不变量：
+ *  - **凭据只在这里落地**：读取（存储域 / 环境变量 / bundle 默认）与使用（拼请求头）都在
+ *    Host 半边，Web 半边只看得到 `hasApiKey` 这类布尔；
+ *  - 出网客户端按「有效配置」缓存，配置一变（保存设置）立刻重建，避免用旧 Key 打后端；
+ *  - 自检分两层：**连接**（认证 + 列库）与**检索健康**（探针词是否命中、分数是否像重排分）。
+ *    后者是必须的——实测未绑重排模型时后端会"静默给错结果"（任意查询返回同一分块、
+ *    分数恒为 RRF 值），HTTP 层完全看不出来；
+ *  - 所有对外方法都接受 `AbortSignal` 并把它透传到出网调用。
+ */
+import { DEFAULT_BASE_URL, DEFAULT_KNOWLEDGE_CONFIG, KNOWLEDGE_DOMAIN_VERSION, KNOWLEDGE_SETTINGS_KEY, KnowledgeError, RRF_SCORE_CEILING, SELF_CHECK_BASE_LIMIT, knowledgeDomainSpec, knowledgeSettingsRecordSchema, normalizeBaseUrl, } from './types.js';
+import { createWeKnoraClient, } from './weknora.js';
+const API_KEY_ENV_NAMES = ['HIWORK_KNOWLEDGE_API_KEY', 'WEKNORA_API_KEY'];
+const BASE_URL_ENV_NAMES = ['HIWORK_KNOWLEDGE_BASE_URL', 'WEKNORA_BASE_URL'];
+/** 读取环境变量中的凭据（开发/CI 便利；存储域里的设置优先级更高）。 */
+function envApiKey(env) {
+    for (const name of API_KEY_ENV_NAMES) {
+        const value = env[name];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value.trim();
+    }
+    return '';
+}
+function envBaseUrl(env) {
+    for (const name of BASE_URL_ENV_NAMES) {
+        const value = env[name];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value.trim();
+    }
+    return '';
+}
+/** 把用户补丁合并进当前配置，并校验（非法输入抛 `bad-request`）。 */
+export function mergeConfig(current, patch) {
+    const next = {
+        ...current,
+        ...patch,
+        baseUrl: patch.baseUrl === undefined ? current.baseUrl : normalizeBaseUrl(patch.baseUrl),
+    };
+    const parsed = knowledgeSettingsRecordSchema.shape.config.safeParse(next);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const path = issue?.path.join('.') ?? '';
+        const message = issue?.message ?? '字段不合法';
+        throw new KnowledgeError('bad-request', `配置不合法：${path === '' ? message : `${path} ${message}`}`);
+    }
+    return parsed.data;
+}
+/** 把片段截断到 `maxChunkChars`，并显式报告是否截断（不静默丢内容）。 */
+export function clipContent(content, limit) {
+    if (content.length <= limit)
+        return { text: content, truncated: false };
+    return { text: content.slice(0, limit), truncated: true };
+}
+/** 知识库服务。 */
+export class KnowledgeService {
+    ctx;
+    domain;
+    stored;
+    bundleDefault = { ...DEFAULT_KNOWLEDGE_CONFIG };
+    cached;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** 打开存储域并读回已保存的设置。 */
+    static async open(ctx, bundleDefault) {
+        const service = new KnowledgeService(ctx);
+        service.bundleDefault = mergeConfig({ ...DEFAULT_KNOWLEDGE_CONFIG }, bundleDefault ?? {});
+        service.domain = await ctx.storageDomain.open(knowledgeDomainSpec);
+        const table = service.domain.table('settings');
+        const record = table.get(KNOWLEDGE_SETTINGS_KEY);
+        if (record !== undefined) {
+            const parsed = knowledgeSettingsRecordSchema.safeParse(record);
+            if (parsed.success)
+                service.stored = parsed.data.config;
+            else
+                ctx.logger.warn('hiwork-knowledge: 已保存的设置不符合当前 schema，已忽略并回落到默认值。');
+        }
+        return service;
+    }
+    async dispose() {
+        const domain = this.domain;
+        this.domain = undefined;
+        this.cached = undefined;
+        await domain?.close().catch(() => undefined);
+    }
+    /** 有效凭据来源（存储域 > 环境变量 > 默认空）。 */
+    apiKeySource() {
+        if (this.stored !== undefined && this.stored.apiKey !== '')
+            return 'settings';
+        if (envApiKey(process.env) !== '')
+            return 'env';
+        return 'none';
+    }
+    /** 有效配置（含明文 Key，仅 Host 内部使用）。 */
+    effectiveConfig() {
+        const base = {
+            ...DEFAULT_KNOWLEDGE_CONFIG,
+            ...this.bundleDefault,
+            ...(this.stored ?? {}),
+        };
+        if (base.apiKey === '') {
+            const fromEnv = envApiKey(process.env);
+            if (fromEnv !== '')
+                base.apiKey = fromEnv;
+        }
+        if (base.baseUrl === DEFAULT_BASE_URL) {
+            const fromEnv = envBaseUrl(process.env);
+            if (fromEnv !== '')
+                base.baseUrl = normalizeBaseUrl(fromEnv);
+        }
+        return base;
+    }
+    /** 设置页视图：剥掉凭据明文。 */
+    getConfigView() {
+        const config = this.effectiveConfig();
+        return {
+            baseUrl: config.baseUrl,
+            tenantId: config.tenantId,
+            hasApiKey: config.apiKey !== '',
+            apiKeySource: this.apiKeySource(),
+            defaultBaseIds: [...config.defaultBaseIds],
+            maxResults: config.maxResults,
+            maxChunkChars: config.maxChunkChars,
+            agentId: config.agentId,
+            chatModelId: config.chatModelId,
+        };
+    }
+    /**
+     * 保存设置补丁。
+     *
+     * 空字符串 = 显式清空；`undefined` = 保持原值。写盘后立刻丢弃缓存的客户端。
+     */
+    async saveConfig(patch) {
+        const domain = this.requireDomain();
+        const base = this.effectiveConfig();
+        const next = mergeConfig(base, patch);
+        await domain.table('settings').put(KNOWLEDGE_SETTINGS_KEY, {
+            version: KNOWLEDGE_DOMAIN_VERSION,
+            config: next,
+        });
+        this.stored = next;
+        this.cached = undefined;
+        return this.getConfigView();
+    }
+    /** 出网客户端（按有效配置缓存）。 */
+    client() {
+        const config = this.effectiveConfig();
+        const key = JSON.stringify([config.baseUrl, config.apiKey, config.tenantId, config.requestTimeoutMs, config.chatTimeoutMs, config.chatModelId]);
+        if (this.cached !== undefined && this.cached.key === key)
+            return this.cached.client;
+        const client = createWeKnoraClient(config);
+        this.cached = { key, client };
+        return client;
+    }
+    /** 需要凭据的调用统一先过这道门；没配 Key 时给出可执行的提示。 */
+    requireCredentials() {
+        const config = this.effectiveConfig();
+        if (config.apiKey === '') {
+            throw new KnowledgeError('misconfigured', '尚未配置 WeKnora API Key，请在「设置 → 知识库」里填写后重试。');
+        }
+        return this.client();
+    }
+    requireDomain() {
+        if (this.domain === undefined)
+            throw new KnowledgeError('internal', '知识库存储域尚未打开。');
+        return this.domain;
+    }
+    listBases(signal) {
+        return this.requireCredentials().listBases(signal);
+    }
+    listDocs(baseId, signal) {
+        return this.requireCredentials().listDocs(baseId, signal);
+    }
+    async search(query, scope = {}, signal) {
+        const config = this.effectiveConfig();
+        const client = this.requireCredentials();
+        const trimmed = query.trim();
+        if (trimmed === '')
+            throw new KnowledgeError('bad-request', '检索词不能为空。');
+        const baseIds = scope.baseIds === undefined || scope.baseIds.length === 0 ? config.defaultBaseIds : scope.baseIds;
+        const resolved = baseIds.length > 0 ? baseIds : (await client.listBases(signal)).map(base => base.id);
+        if (resolved.length === 0) {
+            throw new KnowledgeError('bad-request', '没有可检索的知识库：请先在后端建库，或在设置里指定默认范围。');
+        }
+        return client.search(trimmed, { baseIds: resolved, ...(scope.knowledgeIds === undefined ? {} : { knowledgeIds: scope.knowledgeIds }) }, signal);
+    }
+    /** 读一篇文档：分块 + 标题，按 `chunkIndex` 顺序拼装并分页。 */
+    async readDocument(knowledgeId, options = {}, signal) {
+        const client = this.requireCredentials();
+        const config = this.effectiveConfig();
+        const [doc, chunks] = await Promise.all([
+            client.getDoc(knowledgeId, signal),
+            client.chunks(knowledgeId, signal),
+        ]);
+        if (doc === null && chunks.length === 0) {
+            throw new KnowledgeError('not-found', `未找到文档 ${knowledgeId}，或它不属于当前凭据可见的知识库。`);
+        }
+        const ordered = [...chunks].sort((left, right) => (left.chunkIndex ?? 0) - (right.chunkIndex ?? 0));
+        const pageSize = Math.max(1, options.pageSize ?? 20);
+        const page = Math.max(1, options.page ?? 1);
+        const start = (page - 1) * pageSize;
+        const slice = ordered.slice(start, start + pageSize);
+        const items = slice.map(chunk => {
+            const clipped = clipContent(chunk.content, config.maxChunkChars);
+            return { index: chunk.chunkIndex, type: chunk.chunkType, content: clipped.text, truncated: clipped.truncated };
+        });
+        return {
+            knowledgeId,
+            title: doc?.title ?? ordered[0]?.knowledgeTitle ?? knowledgeId,
+            chunkTotal: ordered.length,
+            page,
+            pageSize,
+            truncated: ordered.length > start + slice.length || items.some(item => item.truncated),
+            chunks: items,
+        };
+    }
+    /** 问答：固定走 `/knowledge-chat` + 自建 Agent（内置 agent 缺 model_id，必失败）。 */
+    async ask(query, scope = {}, signal) {
+        const config = this.effectiveConfig();
+        const client = this.requireCredentials();
+        const trimmed = query.trim();
+        if (trimmed === '')
+            throw new KnowledgeError('bad-request', '问题不能为空。');
+        if (config.agentId === '') {
+            throw new KnowledgeError('misconfigured', '尚未配置问答 Agent：内置 Agent 的 model_id 为空会被后端拒绝，请先在 WeKnora 里建一个「快速问答」类型的自建 Agent 并把 ID 填进设置。');
+        }
+        // 实测：不显式给知识库范围时，问答链路常常检索不到任何材料（回答会变成
+        // "我没有检索到相关内容"）。所以与检索一致：范围为空时自行展开可见知识库列表。
+        let baseIds = scope.baseIds === undefined || scope.baseIds.length === 0 ? config.defaultBaseIds : scope.baseIds;
+        if (baseIds.length === 0)
+            baseIds = (await client.listBases(signal)).map(base => base.id);
+        return baseIds.length === 0 ? client.ask(trimmed, {}, signal) : client.ask(trimmed, { baseIds }, signal);
+    }
+    /**
+     * 自检：连接 + 检索健康 + 问答可用性。
+     *
+     * 检索健康探针用「第一个可见知识库的第一篇文档标题」当查询词——它一定命中自己，
+     * 因此「命中 0 条」只可能是配置问题（未绑重排 / 模型 id 失效），不是数据问题。
+     */
+    async selfCheck(signal) {
+        const items = [];
+        const config = this.effectiveConfig();
+        const checkedAt = new Date().toISOString();
+        if (config.apiKey === '') {
+            items.push({ code: 'missing-key', ok: false, level: 'error', message: '尚未配置 API Key：请在「设置 → 知识库」填写。' });
+            return { ok: false, level: 'error', items, baseCount: 0, checkedAt };
+        }
+        let bases = [];
+        try {
+            bases = await this.client().listBases(signal);
+            items.push({ code: 'connection', ok: true, level: 'info', message: `已连接 ${normalizeBaseUrl(config.baseUrl)}，可见 ${bases.length} 个知识库。` });
+        }
+        catch (error) {
+            const failure = error instanceof KnowledgeError ? error : new KnowledgeError('internal', String(error));
+            items.push({ code: failure.code, ok: false, level: 'error', message: failure.message });
+            return { ok: false, level: 'error', items, baseCount: 0, checkedAt };
+        }
+        if (bases.length === 0) {
+            items.push({ code: 'empty-bases', ok: false, level: 'warn', message: '当前凭据看不到任何知识库：先在后端建库并上传文档。' });
+            return { ok: false, level: 'warn', items, baseCount: 0, checkedAt };
+        }
+        // 检索健康：用文档标题做探针。
+        let probeDone = false;
+        for (const base of bases.slice(0, SELF_CHECK_BASE_LIMIT)) {
+            let docs = [];
+            try {
+                docs = await this.client().listDocs(base.id, signal);
+            }
+            catch {
+                continue;
+            }
+            const title = docs[0]?.title ?? '';
+            if (title === '')
+                continue;
+            try {
+                const hits = await this.client().search(title, { baseIds: [base.id] }, signal);
+                probeDone = true;
+                if (hits.length === 0) {
+                    items.push({
+                        code: 'probe-miss',
+                        ok: false,
+                        level: 'warn',
+                        message: `探针检索（知识库「${base.name}」内的文档标题）返回 0 条：请到 WeKnora「设置 → 检索设置」确认已绑定 rerank 模型，且模型未被删除重建（重建会换 ID）。`,
+                    });
+                }
+                else {
+                    const top = Math.max(...hits.map(hit => hit.score ?? 0));
+                    if (top < RRF_SCORE_CEILING) {
+                        items.push({
+                            code: 'rerank-missing',
+                            ok: false,
+                            level: 'warn',
+                            message: `检索最高分 ${top.toFixed(4)} 落在 RRF 区间（<${RRF_SCORE_CEILING}）：说明租户检索配置未绑 rerank 模型，结果可能不相关（实测未绑时任意查询都返回同一分块）。`,
+                        });
+                    }
+                    else {
+                        items.push({
+                            code: 'retrieval',
+                            ok: true,
+                            level: 'info',
+                            message: `检索探针正常：命中 ${hits.length} 条，最高分 ${top.toFixed(4)}。`,
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                const failure = error instanceof KnowledgeError ? error : new KnowledgeError('internal', String(error));
+                items.push({ code: failure.code, ok: false, level: 'error', message: `检索探针失败：${failure.message}` });
+            }
+            break;
+        }
+        if (!probeDone) {
+            items.push({
+                code: 'probe-skipped',
+                ok: false,
+                level: 'warn',
+                message: '前几个知识库里没有可用的文档，无法验证检索质量：先上传一篇文档再自检。',
+            });
+        }
+        if (config.agentId === '') {
+            items.push({
+                code: 'ask-unconfigured',
+                ok: false,
+                level: 'warn',
+                message: '未配置问答 Agent：knowledge_ask 暂不可用（内置 Agent 会被后端拒绝）。',
+            });
+        }
+        else {
+            items.push({ code: 'ask', ok: true, level: 'info', message: `问答 Agent 已配置：${config.agentId}。` });
+        }
+        const level = items.some(item => item.level === 'error')
+            ? 'error'
+            : items.some(item => item.level === 'warn')
+                ? 'warn'
+                : 'ok';
+        return { ok: level === 'ok', level, items, baseCount: bases.length, checkedAt };
+    }
+}
+/** 单测/自检用：注入自定义出网的临时客户端工厂。 */
+export function clientForTest(config, transport) {
+    return createWeKnoraClient(config, transport);
+}

package/lib/tool-names.js

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