hiwork-knowledge 0.1.1 → 0.2.0

package/lib/types/client/format.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 页面展示用的纯格式化函数。
+ *
+ * 刻意与 React 和宿主完全解耦：这些映射（状态 → 语义色、字节 → 可读大小、时间 → 短日期）
+ * 是最容易写错又最容易被测试覆盖的部分，放在独立文件里可以直接单测。
+ *
+ * 另一条纪律：**不产生任何硬编码文案**。返回空串表示「这段没有内容，调用方别渲染」，
+ * 而不是返回 'FILE' / '未知' 这类兜底词——可见文案一律走词典（i18n 门禁要求）。
+ */
+/** 徽标语义色（对应样式表里的 `.hiwork-knowledge-tag.is-<tone>`）。 */
+export type TagTone = 'success' | 'info' | 'warning' | 'danger' | 'neutral';
+/**
+ * 解析状态 → 徽标语义色。
+ *
+ * **已完成刻意不着色**：一份正常的知识库里绝大多数文档都是 `completed`，逐行染绿等于
+ * 把颜色变成背景噪声——反而把真正需要一眼看到的 `failed`（红）和解析中（蓝）淹掉。
+ * 所以只给异常态上色，正常态走中性（无填充、淡描边的静默徽标）。这也是 CI/构建列表的
+ * 通行做法：只在出问题时抢注意力。
+ * @param status - 后端原始解析状态。
+ */
+export declare function statusTone(status: string): TagTone;
+/**
+ * 解析状态 → 词典键；未知状态返回 `null`。
+ * @param status - 后端原始解析状态。
+ */
+export declare function parseStatusKey(status: string): string | null;
+/**
+ * 字节数 → 人类可读大小；无效值返回空串。
+ *
+ * `0` 也返回空串：后端把未知大小报成 0，而「0 B 的文档」只会让人怀疑数据出错。
+ * @param bytes - 字节数（后端可能给 null）。
+ */
+export declare function formatSize(bytes: number | null | undefined): string;
+/**
+ * ISO 时间 → `YYYY-MM-DD`；无效值返回空串。
+ *
+ * 刻意不用 `toLocaleDateString`：它的输出随运行环境的语言与时区变化，
+ * 同一份数据在两台机器上会渲染出不同的字符串，让渲染断言变得不可复现。
+ * 秒级精度在这里没有意义（用户看的是「哪天更新的」），所以直接截到日。
+ * @param iso - 后端返回的时间串。
+ */
+export declare function formatDate(iso: string | null | undefined): string;
+/**
+ * 文件类型徽标文字；无法判定时返回空串（调用方退化成通用文件图标）。
+ *
+ * 优先用后端给的 `fileType`，没有则从文件名取扩展名；统一大写并截到 4 个字符，
+ * 这样 32px 的方形徽标里不会溢出（`docx` / `xlsx` 正好 4 个）。
+ * @param fileType - 后端的文件类型字段。
+ * @param fileName - 文件名（兜底取扩展名）。
+ */
+export declare function fileTypeLabel(fileType: string, fileName: string): string;
+/**
+ * 文件类型徽标的色调（对应样式表里的 `.hiwork-knowledge-doc-icon.is-<tone>`）。
+ *
+ * 用颜色名而不是语义名：这里表达的是「这是哪种文件」，不是「成功/失败」，
+ * 借用 success/danger 之类的槽位会让类名与含义对不上。
+ */
+export type IconTone = 'blue' | 'green' | 'amber' | 'red' | 'neutral';
+/**
+ * 文件类型 → 徽标色调；未收录的类型走中性色。
+ *
+ * 键统一用 `fileTypeLabel` 的输出（去掉前导点、大写、截 4 字符），
+ * 两种途径（后端 `fileType` 与文件名扩展名）因此落在同一张表上。
+ * @param fileType - 后端的文件类型字段。
+ * @param fileName - 文件名（兜底取扩展名）。
+ */
+export declare function fileTypeTone(fileType: string, fileName: string): IconTone;
+/**
+ * 用「 · 」拼接元数据段，自动跳过空段。
+ *
+ * 空段不跳过的话，`documentCount` 缺失时会渲染出「 · 3 个分块」这种以分隔符开头的行。
+ * @param parts - 各元数据段（空串 / null / undefined 会被丢弃）。
+ */
+export declare function joinMeta(parts: readonly (string | null | undefined)[]): string;

package/lib/types/client/icons.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 内联 SVG 图标。
+ *
+ * 不引第三方图标库：client bundle 必须自包含（打包扫描不允许运行时 import 外部包），
+ * 而这里只需要 4 个 16px 线性图标。统一 `stroke="currentColor"`，颜色由所在容器的
+ * `color` 决定，因此亮暗主题、选中态、错误态都自动跟随，不需要为图标单独定义颜色。
+ */
+import { type ReactElement } from 'react';
+/** 刷新（页头）。 */
+export declare function IconRefresh(): ReactElement;
+/** 放大镜（检索框）。 */
+export declare function IconSearch(): ReactElement;
+/** 通用文件（未知类型时的兜底）。 */
+export declare function IconFile(): ReactElement;
+/** 告警圆圈（错误 / 警告横幅）。 */
+export declare function IconAlert(): ReactElement;
+/** 空态示意（列表为空时垫在文字上方，避免只有一行灰字悬在空白里）。 */
+export declare function IconInbox(): ReactElement;
+/** 对勾（工具卡片：调用成功）。 */
+export declare function IconCheck(): ReactElement;
+/** 带外链箭头的方框（「在知识库页打开」）。 */
+export declare function IconExternal(): ReactElement;
+/** 对话气泡（「追问」）。 */
+export declare function IconMessage(): ReactElement;
+/** 书本（知识库语义的装饰图标）。 */
+export declare function IconBook(): ReactElement;

package/lib/types/client/index.d.ts

@@ -1,7 +1,26 @@
+/**
+ * `hiwork-knowledge` 的 Web 入口。
+ *
+ * 两个入口，职责不同，**同时存在**：
+ *  1. 中央页 feature（id `knowledge`、order 30）：浏览知识库/文档/检索；
+ *     依赖 `hiwork-core` 的 `hiworkFeatureCenter`，没有 core 时不注册。
+ *  2. 设置页分区 `settings.section#knowledge`：凭据、默认范围、自检。
+ *     这块**不随 core 出现而撤下**——它是配置面，不是浏览面的降级替身
+ *     （M0 起与 hiwork-automation 的"二选一"策略不同，见 README）。
+ *
+ * 数据来自 Host 的 `/hiwork-knowledge` loopback RPC：Web 半边不发任何 HTTP，
+ * 也拿不到凭据（只有 `hasApiKey` 布尔）。
+ *
+ * client bundle 纯度：本文件对 `@deepseek-ai/*` 只做 type-only import
+ * （经 `./contracts.js` 的结构契约），运行时只 import `react` 与本地模块。
+ */
+import { createElement, type ReactElement } from 'react';
 import type { ClientContext } from './contracts.js';
+import { KnowledgeView } from './KnowledgeView.js';
+import { KnowledgeSettings } from './SettingsSection.js';
 /** DSH client 插件名。 */
 export declare const name = "hiwork-knowledge-client";
-/** 必需的 client 服务。 */
+/** 必需的 client 服务（`connection` 提供 loopback RPC）。 */
 export declare const inject: string[];
 /**
  * 挂载 Web 半边。
@@ -9,4 +28,14 @@ export declare const inject: string[];
  */
 export declare function apply(ctx: ClientContext): void;
 /** 便于验收脚本按导出面断言。 */
-export type { KnowledgeViewProps } from './contracts.js';
+export type { KnowledgeSettingsProps, KnowledgeViewProps } from './contracts.js';
+export type { KnowledgeRuntime } from './runtime.js';
+/** 供测试断言注册面（避免测试里硬编码字符串）。 */
+export declare const KNOWLEDGE_CLIENT_REGISTRATION: {
+    readonly featureId: "knowledge";
+    readonly featureOrder: 30;
+    readonly settingsSectionId: "knowledge";
+};
+/** 便于测试断言渲染出的组件类型。 */
+export { KnowledgeView, KnowledgeSettings, createElement as __createElement };
+export type { ReactElement };

package/lib/types/client/locales.d.ts

@@ -5,19 +5,226 @@
  *  - 页面里所有用户可见文案都必须来自这里，组件内不写死中英文；
  *  - `en` 的类型是 `Record<KnowledgeLocaleKey, string>`，少一个键就是编译错误。
  */
-/** 宿主 locale 服务注册时使用的命名空间。 */
 export declare const NS = "hiwork-knowledge";
 export declare const zh: {
-    'view.title': string;
-    'view.subtitle': string;
-    'view.placeholder': string;
-    'view.close': string;
+    readonly 'view.title': "知识库";
+    readonly 'view.subtitle': "企业知识检索与问答（WeKnora）";
+    readonly 'view.close': "关闭设置";
+    readonly 'view.refresh': "刷新";
+    readonly 'state.loading': "正在读取知识库…";
+    readonly 'state.error': "知识库读取失败";
+    readonly 'state.retry': "重试";
+    readonly 'settings.title': "知识库设置";
+    readonly 'settings.subtitle': "凭据保存在本机（Host 半边），不下发给其它插件或网页";
+    readonly 'settings.baseUrl': "后端地址";
+    readonly 'settings.baseUrlHint': "缺 /api/v1 时会自动补齐；默认指向公司内网部署";
+    readonly 'settings.apiKey': "API Key";
+    readonly 'settings.apiKeyPlaceholder': "粘贴空间 API Key（形如 sk-…）";
+    readonly 'settings.apiKeyKeep': "留空则不修改";
+    readonly 'settings.apiKeyConfigured': "已配置";
+    readonly 'settings.apiKeyMissing': "未配置";
+    readonly 'settings.apiKeySource': "凭据来源";
+    readonly 'settings.apiKeySource.settings': "本机设置";
+    readonly 'settings.apiKeySource.env': "环境变量";
+    readonly 'settings.apiKeySource.none': "无";
+    readonly 'settings.tenantId': "空间 ID（平台 Key 才需要）";
+    readonly 'settings.defaultBases': "默认检索范围（知识库 ID，逗号分隔）";
+    readonly 'settings.defaultBasesHint': "留空表示使用凭据可见的全部知识库";
+    readonly 'settings.maxResults': "每次检索条数上限";
+    readonly 'settings.maxChunkChars': "单条片段字符上限";
+    readonly 'settings.agentId': "问答 Agent ID";
+    readonly 'settings.agentIdHint': "必须是自建 Agent（内置 Agent 缺少模型配置，后端会直接拒绝）";
+    readonly 'settings.chatModelId': "问答模型 ID";
+    readonly 'settings.chatModelIdHint': "请求体里的 summary_model_id；留空则用后端默认";
+    readonly 'settings.save': "保存";
+    readonly 'settings.saving': "保存中…";
+    readonly 'settings.saved': "已保存";
+    readonly 'settings.test': "测试连接";
+    readonly 'settings.testing': "正在自检…";
+    readonly 'settings.testNote': "自检会真实调用后端：列库 + 用文档标题做一次探针检索（用于发现「检索未绑 rerank」这类静默错误）";
+    readonly 'selfCheck.ok': "自检通过";
+    readonly 'selfCheck.warn': "自检有告警";
+    readonly 'selfCheck.error': "自检失败";
+    readonly 'selfCheck.baseCount': "可见知识库";
+    readonly 'bases.title': "知识库";
+    readonly 'bases.empty': "当前凭据看不到任何知识库";
+    readonly 'bases.meta.docs': "{count} 篇文档";
+    readonly 'bases.meta.updated': "{value} 更新";
+    readonly 'bases.select': "查看「{name}」的文档";
+    readonly 'docs.title': "文档";
+    readonly 'docs.empty': "这个知识库里还没有文档";
+    readonly 'docs.loading': "正在读取文档…";
+    readonly 'docs.parseStatus': "解析状态";
+    readonly 'docs.scope.all': "全部知识库";
+    readonly 'docs.parse.pending': "排队中";
+    readonly 'docs.parse.processing': "解析中";
+    readonly 'docs.parse.finalizing': "生成摘要中";
+    readonly 'docs.parse.completed': "已就绪";
+    readonly 'docs.parse.failed': "解析失败";
+    readonly 'docs.parse.cancelled': "已取消";
+    readonly 'card.title': "知识库";
+    readonly 'card.search.title': "检索知识库";
+    readonly 'card.ask.title': "问知识库";
+    readonly 'card.read.title': "读取文档";
+    readonly 'card.bases.title': "知识库列表";
+    readonly 'card.running': "进行中…";
+    readonly 'card.runningWith': "正在检索「{subject}」…";
+    readonly 'card.done': "已完成";
+    readonly 'card.hitCount': "{count} 段命中";
+    readonly 'card.noHit': "无命中";
+    readonly 'card.answered': "已给出答案";
+    readonly 'card.answeredWith': "答案 · {count} 条引用";
+    readonly 'card.read.done': "已读取";
+    readonly 'card.read.doneWith': "全文 {count} 段";
+    readonly 'card.bases.count': "{count} 个知识库";
+    readonly 'card.segment': "第 {index} 段";
+    readonly 'card.actionFailed': "没能放进输入框：{reason}";
+    readonly 'card.insertFailed.no-target': "当前没有打开的会话";
+    readonly 'card.insertFailed.busy': "输入框正忙（正在处理上一轮）";
+    readonly 'card.insertFailed.rejected': "输入框拒绝了这次插入";
+    readonly 'card.untitled': "未命名文档";
+    readonly 'card.clipped': "已截断";
+    readonly 'card.open': "在知识库页打开";
+    readonly 'card.followUp': "追问";
+    readonly 'card.followUpPrompt': "请基于企业知识库《{title}》{segment}继续回答，并注明出处。";
+    readonly 'card.more': "展开其余 {count} 段";
+    readonly 'card.collapse': "收起";
+    readonly 'card.inspect': "在轨迹中查看";
+    readonly 'doc.read': "读全文";
+    readonly 'doc.back': "返回列表";
+    readonly 'doc.loading': "正在读取正文…";
+    readonly 'doc.empty': "这篇文档还没有可读的分块";
+    readonly 'doc.chunkTotal': "共 {count} 段";
+    readonly 'doc.page': "第 {page} / {total} 页";
+    readonly 'doc.prev': "上一页";
+    readonly 'doc.next': "下一页";
+    readonly 'doc.bringToChat': "带进聊天";
+    readonly 'doc.chatPrompt': "请基于企业知识库文档《{title}》回答，并注明出处。";
+    readonly 'doc.chatSent': "已放进输入框";
+    readonly 'doc.chatFailed': "没能放进输入框：{reason}";
+    readonly 'doc.chatFailed.no-target': "当前没有打开的会话";
+    readonly 'doc.chatFailed.busy': "输入框正忙（正在处理上一轮）";
+    readonly 'doc.chatFailed.rejected': "输入框拒绝了这次插入";
+    readonly 'doc.chatUnavailable': "当前没有打开的会话";
+    readonly 'doc.bringChunkToChat': "带进聊天";
+    readonly 'doc.chunkChatPrompt': "请基于企业知识库《{title}》{segment}继续回答，并注明出处。";
+    readonly 'search.placeholder': "在知识库里检索…";
+    readonly 'search.button': "检索";
+    readonly 'search.running': "检索中…";
+    readonly 'search.empty': "没有命中。若确认库里有相关内容，请检查后端检索配置：重排模型是否绑定，以及重排阈值（rerank_threshold）是否过高——阈值会把相关但分数偏低的片段整体滤掉。";
+    readonly 'search.hitCount': "命中片段";
+    readonly 'search.truncated': "已截断";
+    readonly 'search.clear': "返回文档列表";
 };
 export declare const en: {
     'view.title': string;
     'view.subtitle': string;
-    'view.placeholder': string;
     'view.close': string;
+    'view.refresh': string;
+    'state.loading': string;
+    'state.error': string;
+    'state.retry': string;
+    'settings.title': string;
+    'settings.subtitle': string;
+    'settings.baseUrl': string;
+    'settings.baseUrlHint': string;
+    'settings.apiKey': string;
+    'settings.apiKeyPlaceholder': string;
+    'settings.apiKeyKeep': string;
+    'settings.apiKeyConfigured': string;
+    'settings.apiKeyMissing': string;
+    'settings.apiKeySource': string;
+    'settings.apiKeySource.settings': string;
+    'settings.apiKeySource.env': string;
+    'settings.apiKeySource.none': string;
+    'settings.tenantId': string;
+    'settings.defaultBases': string;
+    'settings.defaultBasesHint': string;
+    'settings.maxResults': string;
+    'settings.maxChunkChars': string;
+    'settings.agentId': string;
+    'settings.agentIdHint': string;
+    'settings.chatModelId': string;
+    'settings.chatModelIdHint': string;
+    'settings.save': string;
+    'settings.saving': string;
+    'settings.saved': string;
+    'settings.test': string;
+    'settings.testing': string;
+    'settings.testNote': string;
+    'selfCheck.ok': string;
+    'selfCheck.warn': string;
+    'selfCheck.error': string;
+    'selfCheck.baseCount': string;
+    'bases.title': string;
+    'bases.empty': string;
+    'bases.meta.docs': string;
+    'bases.meta.updated': string;
+    'bases.select': string;
+    'docs.title': string;
+    'docs.empty': string;
+    'docs.loading': string;
+    'docs.parseStatus': string;
+    'docs.scope.all': string;
+    'docs.parse.pending': string;
+    'docs.parse.processing': string;
+    'docs.parse.finalizing': string;
+    'docs.parse.completed': string;
+    'docs.parse.failed': string;
+    'docs.parse.cancelled': string;
+    'card.title': string;
+    'card.search.title': string;
+    'card.ask.title': string;
+    'card.read.title': string;
+    'card.bases.title': string;
+    'card.running': string;
+    'card.runningWith': string;
+    'card.done': string;
+    'card.hitCount': string;
+    'card.noHit': string;
+    'card.answered': string;
+    'card.answeredWith': string;
+    'card.read.done': string;
+    'card.read.doneWith': string;
+    'card.bases.count': string;
+    'card.segment': string;
+    'card.actionFailed': string;
+    'card.insertFailed.no-target': string;
+    'card.insertFailed.busy': string;
+    'card.insertFailed.rejected': string;
+    'card.untitled': string;
+    'card.clipped': string;
+    'card.open': string;
+    'card.followUp': string;
+    'card.followUpPrompt': string;
+    'card.more': string;
+    'card.collapse': string;
+    'card.inspect': string;
+    'doc.read': string;
+    'doc.back': string;
+    'doc.loading': string;
+    'doc.empty': string;
+    'doc.chunkTotal': string;
+    'doc.page': string;
+    'doc.prev': string;
+    'doc.next': string;
+    'doc.bringToChat': string;
+    'doc.chatPrompt': string;
+    'doc.chatSent': string;
+    'doc.chatFailed': string;
+    'doc.chatFailed.no-target': string;
+    'doc.chatFailed.busy': string;
+    'doc.chatFailed.rejected': string;
+    'doc.chatUnavailable': string;
+    'doc.bringChunkToChat': string;
+    'doc.chunkChatPrompt': string;
+    'search.placeholder': string;
+    'search.button': string;
+    'search.running': string;
+    'search.empty': string;
+    'search.hitCount': string;
+    'search.truncated': string;
+    'search.clear': string;
 };
 /** 词典键（zh 为基准，en 必须键集一致）。 */
 export type KnowledgeLocaleKey = keyof typeof zh;

package/lib/types/client/runtime.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `hiwork-knowledge` 的客户端状态源。
+ *
+ * 铁律（对齐设计文档 §D4）：
+ *  - 客户端**不持有**凭据、不直接发 HTTP 到 WeKnora；一切数据来自 Host 的 loopback RPC；
+ *  - 传输失败保留上一份成功快照，只把 phase 切到 `error` 并带上消息；
+ *  - `testConnection` 会把自检结果写回快照（`snapshot.selfCheck`），
+ *    因为"检索健康"是配置问题、只有跑一次才知道；
+ *  - 文档列表与检索结果是**视图局部状态**，由调用方自己缓存（不需要全局快照）。
+ *
+ * client bundle 纯度：本文件只 `import type` `../protocol.js`，运行时依赖为零。
+ */
+import type { KnowledgeDocView, KnowledgeDocumentView, KnowledgeHitView, KnowledgeSnapshotView } from '../protocol.js';
+import type { SelfCheckResult } from '../service.js';
+import type { ClientRpc } from './contracts.js';
+/** RPC 频道；必须与 `protocol.ts` 的 `KNOWLEDGE_RPC_CHANNEL` 一致（由测试锁定）。 */
+export declare const KNOWLEDGE_CHANNEL = "/hiwork-knowledge";
+/** 快照请求携带的 Web 作用域标识（Host 据此把设置页当 hostWide 作用域）。 */
+export declare const SETTINGS_SCOPE_SESSION_ID = "settings";
+/** 宿主返回了无法解析的 RPC 信封时的哨兵消息（由视图本地化）。 */
+export declare const RPC_INVALID_RESPONSE = "hiwork-knowledge:invalid-response";
+/** 宿主返回了空错误消息时的哨兵（同样由视图本地化）。 */
+export declare const RPC_REQUEST_FAILED = "hiwork-knowledge:request-failed";
+/** 是否是"连接层"失败（可重试一次）；主动取消不算。 */
+export declare function isTransportError(error: unknown): boolean;
+export interface KnowledgeClientState {
+    readonly phase: 'idle' | 'loading' | 'ready' | 'error';
+    readonly snapshot?: KnowledgeSnapshotView;
+    readonly error?: string;
+    readonly refreshedAt?: number;
+}
+export interface KnowledgeStateSource {
+    getSnapshot(): KnowledgeClientState;
+    /**
+     * 服务端渲染时的快照。`useSyncExternalStore` 在 SSR 下要求提供它，
+     * 缺了会直接抛 `Missing getServerSnapshot`（静态渲染/冒烟测试会命中）。
+     */
+    getServerSnapshot?(): KnowledgeClientState;
+    subscribe(listener: () => void): () => void;
+}
+/** 设置补丁（与 Host 的 `configSaveRequestSchema.patch` 逐字段一致）。 */
+export interface KnowledgeConfigPatchWire {
+    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 KnowledgeRuntime {
+    readonly source: KnowledgeStateSource;
+    refresh(): Promise<void>;
+    saveConfig(patch: KnowledgeConfigPatchWire): Promise<KnowledgeSnapshotView['config']>;
+    testConnection(): Promise<SelfCheckResult>;
+    loadDocs(baseId: string): Promise<readonly KnowledgeDocView[]>;
+    /** 读一篇文档的正文（分页）；「只能搜片段」的解法就在这里。 */
+    loadDocument(knowledgeId: string, page?: number): Promise<KnowledgeDocumentView>;
+    search(query: string, baseId?: string): Promise<readonly KnowledgeHitView[]>;
+}
+/**
+ * 创建知识库运行时。
+ * @param rpc - 宿主 loopback RPC（`ctx.connection.rpc`）。
+ */
+export declare function createKnowledgeRuntime(rpc: ClientRpc): KnowledgeRuntime;

package/lib/types/client/tool-result.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 把一次知识库工具调用（`tool.call.toolview` 收到的 `block`）解析成卡片模型。
+ *
+ * 为什么单独成文件、且不 import React：这是**纯函数**，四种工具各有一套返回形状，
+ * 而工具结果在真机上的形态（`argsRaw` 是原始 JSON 字符串、结果在 `content[].text` 里
+ * 又是一层 JSON）靠读类型定义是看不出来的——它是实测出来的：
+ *
+ *  - `RunningToolCall` 只有 `argsRaw`（**原始 JSON 字符串**，不是对象），没有结果；
+ *  - `ToolResultNode` 有 `kind: 'tool-result'`、`content: ContentBlock[]`、`isError`；
+ *  - 我们的工具声明的是 `output: { schema: { type: 'json' } }` + 一个 `render`，所以
+ *    结果落在 `content[0].text` 里，内容是 `JSON.stringify(value)` 后的字符串；
+ *  - 因此「读结果」= 取 text block → `JSON.parse` → 得到 `{ ok, ... }`。
+ *
+ * 解析**永不抛错**：任何形状不对的输入都退化成「有 args、没有结果」的最小模型，
+ * 卡片渲染成一行标题而不是让 slot 的 error boundary 把整张卡片摘掉。
+ */
+import type { ToolCallBlockLike } from './contracts.js';
+/** 卡片生命周期状态（由 block 自身推导，不查任何实时状态）。 */
+export type ToolCardState = 'running' | 'ok' | 'error' | 'stopped';
+/** 一条检索命中 / 引用。 */
+export interface HitRowView {
+    readonly knowledgeId: string;
+    readonly chunkId: string;
+    readonly knowledgeTitle: string;
+    readonly fileName: string;
+    readonly chunkIndex: number | null;
+    readonly chunkType: string;
+    readonly content: string;
+    readonly truncated: boolean;
+}
+/** 一个知识库。 */
+export interface BaseRowView {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly documentCount: number | null;
+}
+/** 文档正文里的一个分块。 */
+export interface ChunkRowView {
+    readonly index: number | null;
+    readonly chunkType: string;
+    readonly content: string;
+    readonly truncated: boolean;
+}
+/** 四张卡片共用的头部信息。 */
+interface CardCommon {
+    readonly state: ToolCardState;
+    /** 调用参数里的主要文本（检索词 / 问题 / 文档 ID），running 阶段只有它可显示。 */
+    readonly subject: string;
+    /** 失败原因（`isError` 或工具自己返回 `{ ok: false, message }`）。 */
+    readonly error: string | null;
+}
+export interface SearchCard extends CardCommon {
+    readonly kind: 'search';
+    readonly hitCount: number;
+    readonly hits: readonly HitRowView[];
+    /** 工具在「0 条」时给出的可执行提示（配置类原因），有则优先显示。 */
+    readonly hint: string | null;
+}
+export interface AskCard extends CardCommon {
+    readonly kind: 'ask';
+    readonly answer: string;
+    readonly references: readonly HitRowView[];
+    readonly elapsedMs: number | null;
+}
+export interface ReadCard extends CardCommon {
+    readonly kind: 'read';
+    readonly title: string;
+    readonly chunkTotal: number | null;
+    readonly page: number | null;
+    readonly chunks: readonly ChunkRowView[];
+}
+export interface BasesCard extends CardCommon {
+    readonly kind: 'bases';
+    readonly bases: readonly BaseRowView[];
+}
+export interface UnknownCard extends CardCommon {
+    readonly kind: 'unknown';
+}
+export type ToolCardModel = SearchCard | AskCard | ReadCard | BasesCard | UnknownCard;
+/** 卡片一次最多展示多少条命中（多的靠展开，见组件）。 */
+export declare const CARD_HIT_PREVIEW = 3;
+/**
+ * 解析一次工具调用 → 卡片模型。
+ * @param toolName - 线上工具名（决定返回体的形状）。
+ * @param block - `tool.call.toolview` 的 `block`（running 或 settled）。
+ * @returns 卡片模型；未知工具名退化为 `unknown`。
+ */
+export declare function toToolCardModel(toolName: string, block: ToolCallBlockLike): ToolCardModel;
+export {};

package/lib/types/index.d.ts

@@ -1,22 +1,61 @@
 /**
  * `hiwork-knowledge` 的 Host 入口。
  *
- * 知识库后端（索引 / 检索 / 海普对接）尚未落地，本阶段 Host 半边只做两件事：
- *  - 声明插件名，让 profile 的 bundle 能正常加载（没有 Host 半边，client 半边不会发布）；
- *  - 打一条启动日志，方便排查「插件到底装上没有」。
- *
- * 所有贡献都登记在 `ctx.effect` 的清理函数里，卸载幂等。
+ * 职责边界（与设计文档 §D4 一致，Host 是唯一事实来源）：
+ *  - 打开 `KnowledgeService`（存储域 `hiwork_knowledge` + 凭据解析 + 出网客户端）；
+ *  - 给每个**根 Agent** 挂 4 个只读工具（创建时补挂、销毁时摘除）；
+ *  - 注册系统提示词片段与 `/hiwork-knowledge` loopback RPC（Web 半边只读、只提交意图）；
+ *  - 所有贡献都登记在 `ctx.effect` 的清理函数里，清理幂等。
  *
  * 打包注意：桌面端补种插件时会清空 profile 的 `node_modules/@deepseek-ai/*`，
- * 因此 `lib/index.js` 必须自包含；本文件对官方包只做 **type-only** import。
+ * 因此 `lib/index.js` 必须自包含；本文件对官方包只做 **type-only** import
+ * （下面几个 `import type {}` 仅用于加载 Context 声明合并，编译后被完全擦除）。
  */
 import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 /** DSH 插件名（与 `cordis.patch.yml` 的 bundle id 一致）。 */
 export declare const name = "hiwork-knowledge";
-/** 本阶段不依赖任何 Host 服务；接入知识库后端时在此追加。 */
-export declare const inject: readonly string[];
+/** 必需的 Host 服务。 */
+export declare const inject: readonly ["storageDomain", "agents", "tools", "connection"];
+/** bundle 侧可覆盖的默认值（与 `cordis.patch.yml` 的 config 字段一一对应）。 */
+export interface KnowledgeBundleConfig {
+    baseUrl: string;
+    apiKey: string;
+    tenantId: string;
+    defaultBaseIds: string[];
+    maxResults: number;
+    maxChunkChars: number;
+    agentId: string;
+    chatModelId: string;
+}
+/**
+ * 配置 schema：默认值与 `types.ts` 的常量一致。
+ *
+ * 用推断类型而不是 `Schemastery<...>`：cordis 会用**部分**配置调用 schema，
+ * 标注成完整类型会让 `Config({})` 在类型层被拒绝。
+ */
+export declare const Config: z<Schemastery.ObjectS<{
+    baseUrl: z<string, string>;
+    apiKey: z<string, string>;
+    tenantId: z<string, string>;
+    defaultBaseIds: z<string[], string[]>;
+    maxResults: z<number, number>;
+    maxChunkChars: z<number, number>;
+    agentId: z<string, string>;
+    chatModelId: z<string, string>;
+}>, Schemastery.ObjectT<{
+    baseUrl: z<string, string>;
+    apiKey: z<string, string>;
+    tenantId: z<string, string>;
+    defaultBaseIds: z<string[], string[]>;
+    maxResults: z<number, number>;
+    maxChunkChars: z<number, number>;
+    agentId: z<string, string>;
+    chatModelId: z<string, string>;
+}>>;
 /**
  * 挂载 Host 半边。
- * @param ctx - cordis 上下文。
+ * @param ctx - Host 插件上下文（必须提供 `inject` 声明的全部服务）。
+ * @param config - bundle 配置；缺省字段已由 {@link Config} 补齐。
  */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config: KnowledgeBundleConfig): Promise<void>;

package/lib/types/prompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 知识库相关的系统提示词片段与工具使用指引。
+ *
+ * 为什么需要这段：DSH 自带的能力只覆盖工作区（`grep`/`glob`）与公网（`web_search`），
+ * 企业文档既不在工作区、也不该走公网。模型不知道有企业知识库时，会直接回答"我查不到"
+ * 或者凭常识编。片段的作用是**告诉它先去查**，以及别把「配置问题导致的 0 命中」当成
+ * 「企业没有这个资料」。
+ *
+ * 引用格式是**强制**的（`CITATION_RULE`）：知识库的答案是给同事看的，没有出处的答案在
+ * 内部场景里等于不可用——用户没法核对，也没法顺着找原文。格式刻意对齐聊天卡片展示的
+ * 信息（文档标题 + 段号），两者能直接对上。
+ */
+/** 系统提示词段落名（稳定值，便于用户按名字关闭）。 */
+export declare const KNOWLEDGE_PROMPT_NAME = "hiwork-knowledge";
+/** 排序权重：排在通用工作区规则之后、具体业务插件之前。 */
+export declare const KNOWLEDGE_PROMPT_ORDER = 62;
+/** 引用格式：与聊天卡片展示的「文档标题 · 段号」一致，用户据此核对原文。 */
+export declare const CITATION_RULE: string;
+export declare const KNOWLEDGE_PROMPT_TEXT: string;
+/** 工具说明里引用的行为约束（测试会断言它出现在工具描述中）。 */
+export declare const KNOWLEDGE_TOOL_GUIDE = "\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";