hiwork-knowledge 0.1.1 → 0.2.0

package/lib/tools.js

@@ -0,0 +1,244 @@
+/**
+ * Agent 侧知识库工具（M0：全部只读）。
+ *
+ * 规则：
+ *  - 工具只在**挂载它们的根 Agent** 上生效：`exec.agent` 不是本 Agent、
+ *    或 `exec.signal.aborted` 时统一返回 `{ ok: false, code: 'cancelled' }`，不碰后端；
+ *  - 检索/阅读结果按 `maxChunkChars` 截断，并在返回里显式 `truncated: true`
+ *    （**不静默截断**：模型需要知道还有更多内容）；
+ *  - **不返回 `score`**：实测未绑 rerank 时它是 RRF 定值（0.0164），当相关度用会误导模型；
+ *  - `knowledge_ask` 走 WeKnora 自己的问答链路（不是把片段塞给模型自答），
+ *    需要设置里配好自建 Agent，未配置时返回可执行的提示而不是让模型盲目重试；
+ *  - 所有失败都收敛成 `{ ok: false, code, message }`，message 里不含凭据。
+ */
+import { defineTool, } from '@deepseek-ai/dsh-tools';
+import { KNOWLEDGE_TOOL_GUIDE } from './prompt.js';
+import { KNOWLEDGE_TOOL_NAMES } from './tool-names.js';
+import { KnowledgeError } from './types.js';
+// 工具名的单一事实源在 `tool-names.ts`（Web 半边认领 keyed 座位时用的是同一份）。
+export { KNOWLEDGE_TOOL_NAMES };
+const JSON_OUTPUT = {
+    schema: { type: 'json' },
+    render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+};
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    return value;
+}
+function toToolJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function errorMessage(error) {
+    if (error instanceof KnowledgeError)
+        return error.message;
+    return error instanceof Error ? error.message : String(error);
+}
+function failureCode(error) {
+    return error instanceof KnowledgeError ? error.code : 'knowledge_error';
+}
+function failure(signal, error) {
+    if (signal.aborted)
+        return toToolJson({ ok: false, code: 'cancelled' });
+    return toToolJson({ ok: false, code: failureCode(error), message: errorMessage(error) });
+}
+function presentCall(title, kind, rawInput) {
+    return { card: 'generic', title, kind, ...(rawInput === undefined ? {} : { rawInput }) };
+}
+function isExecutingAgent(exec, agent) {
+    if (exec.agent === agent)
+        return true;
+    const value = asRecord(exec.agent);
+    return value['id'] === agent.id;
+}
+/**
+ * 给一个根 Agent 注册知识库工具。
+ * @param service - Host 侧知识库服务。
+ * @param agent - 目标根 Agent。
+ * @returns 注销器（注销全部已注册工具）。
+ */
+export function registerKnowledgeTools(service, agent) {
+    const disposers = [];
+    const register = (definition) => {
+        disposers.push(agent.ctx.tools.register(definition));
+    };
+    const guard = (exec) => isExecutingAgent(exec, agent) && !exec.signal.aborted;
+    try {
+        register(defineTool({
+            name: 'knowledge_list_bases',
+            description: '列出当前凭据可见的企业知识库（名称、ID、文档数）。当不确定该查哪个库时先调用它；' +
+                '知识库名称往往不足以区分用途，需要时应先用它拿到 ID 再限定检索范围。',
+            parameters: {},
+            output: JSON_OUTPUT,
+            async execute(_args, exec) {
+                if (!guard(exec))
+                    return toToolJson({ ok: false, code: 'cancelled' });
+                try {
+                    const bases = await service.listBases(exec.signal);
+                    return toToolJson({
+                        ok: true,
+                        bases: bases.map(base => ({
+                            id: base.id,
+                            name: base.name,
+                            description: base.description,
+                            documentCount: base.documentCount,
+                        })),
+                    });
+                }
+                catch (error) {
+                    return failure(exec.signal, error);
+                }
+            },
+            presentCall: () => presentCall('列出知识库', 'read'),
+        }));
+        register(defineTool({
+            name: 'knowledge_search',
+            description: '在企业知识库里做混合检索，返回**原文片段**（含所属文档标题与 chunk 编号），不做总结。' +
+                '这是查企业资料的主力工具：拿到片段后自己判断，必要时用 knowledge_read_document 读上下文。' +
+                'knowledge_base_ids 省略时检索默认范围（或凭据可见的全部知识库）。',
+            parameters: {
+                query: { type: 'string', required: true, description: '检索词；用业务语言描述你要找的内容。' },
+                knowledge_base_ids: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '限定检索的知识库 ID 列表；省略时用默认范围。',
+                },
+                knowledge_ids: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '进一步限定到具体文档（knowledge_id）列表。',
+                },
+            },
+            output: JSON_OUTPUT,
+            timeoutMs: 60_000,
+            async execute(args, exec) {
+                if (!guard(exec))
+                    return toToolJson({ ok: false, code: 'cancelled' });
+                try {
+                    const hits = await service.search(args.query, {
+                        baseIds: args.knowledge_base_ids,
+                        ...(args.knowledge_ids === undefined ? {} : { knowledgeIds: args.knowledge_ids }),
+                    }, exec.signal);
+                    const limit = service.effectiveConfig().maxChunkChars;
+                    const items = hits.map(hit => {
+                        const truncated = hit.content.length > limit;
+                        return {
+                            knowledgeId: hit.knowledgeId,
+                            chunkId: hit.chunkId,
+                            knowledgeTitle: hit.knowledgeTitle,
+                            fileName: hit.fileName,
+                            chunkIndex: hit.chunkIndex,
+                            chunkType: hit.chunkType,
+                            content: truncated ? hit.content.slice(0, limit) : hit.content,
+                            truncated,
+                        };
+                    });
+                    return toToolJson({
+                        ok: true,
+                        hitCount: items.length,
+                        hits: items,
+                        ...(items.length === 0
+                            ? {
+                                hint: '检索返回 0 条。可能原因：① 后端「检索设置」未绑 rerank 模型（任意查询都会失真）；' +
+                                    '② rerank 模型被删除重建导致配置里的 ID 失效；③ 该知识库确实没有相关内容。' +
+                                    '请把这一情况原样告诉用户，不要凭常识作答。',
+                            }
+                            : {}),
+                    });
+                }
+                catch (error) {
+                    return failure(exec.signal, error);
+                }
+            },
+            presentCall: args => presentCall(`检索知识库：${args.query}`, 'read', args.query),
+        }));
+        register(defineTool({
+            name: 'knowledge_read_document',
+            description: '按 knowledge_id 读取一篇文档的正文（分块拼装、按顺序返回，可分页）。' +
+                '检索只给片段，需要上下文时用它补齐；首页包含文档标题，长文档可以分页翻。',
+            parameters: {
+                knowledge_id: { type: 'string', required: true, description: '文档 ID（来自检索结果）。' },
+                page: { type: 'integer', description: '页码，从 1 开始，默认 1。' },
+                page_size: { type: 'integer', description: '每页分块数，默认 20。' },
+            },
+            output: JSON_OUTPUT,
+            timeoutMs: 60_000,
+            async execute(args, exec) {
+                if (!guard(exec))
+                    return toToolJson({ ok: false, code: 'cancelled' });
+                try {
+                    const doc = await service.readDocument(args.knowledge_id, { page: args.page, pageSize: args.page_size }, exec.signal);
+                    return toToolJson({ ok: true, document: doc });
+                }
+                catch (error) {
+                    return failure(exec.signal, error);
+                }
+            },
+            presentCall: args => presentCall(`读取文档：${args.knowledge_id}`, 'read', args.knowledge_id),
+        }));
+        register(defineTool({
+            name: 'knowledge_ask',
+            description: '把问题**整体交给企业知识库的问答链路**（后端自己做检索与推理），返回带引用的答案。' +
+                '适合跨多篇文档的综述型问题；它会再消耗一次模型调用，较慢，且返回结论而非证据。' +
+                '需要逐条证据时请改用 knowledge_search。',
+            parameters: {
+                query: { type: 'string', required: true, description: '要问的问题。' },
+                knowledge_base_ids: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '限定问答范围的知识库 ID；省略时用默认范围。',
+                },
+            },
+            output: JSON_OUTPUT,
+            timeoutMs: 300_000,
+            async execute(args, exec) {
+                if (!guard(exec))
+                    return toToolJson({ ok: false, code: 'cancelled' });
+                try {
+                    const answer = await service.ask(args.query, args.knowledge_base_ids === undefined ? {} : { baseIds: args.knowledge_base_ids }, exec.signal);
+                    const limit = service.effectiveConfig().maxChunkChars;
+                    return toToolJson({
+                        ok: true,
+                        answer: answer.answer,
+                        sessionId: answer.sessionId,
+                        elapsedMs: answer.elapsedMs,
+                        toolsUsed: answer.toolsUsed,
+                        references: answer.references.map(reference => {
+                            const truncated = reference.content.length > limit;
+                            return {
+                                knowledgeId: reference.knowledgeId,
+                                chunkId: reference.chunkId,
+                                knowledgeTitle: reference.knowledgeTitle,
+                                chunkIndex: reference.chunkIndex,
+                                chunkType: reference.chunkType,
+                                content: truncated ? reference.content.slice(0, limit) : reference.content,
+                                truncated,
+                            };
+                        }),
+                    });
+                }
+                catch (error) {
+                    return failure(exec.signal, error);
+                }
+            },
+            presentCall: args => presentCall(`问知识库：${args.query}`, 'read', args.query),
+        }));
+    }
+    catch (error) {
+        for (const dispose of disposers.splice(0)) {
+            try {
+                dispose();
+            }
+            catch {
+                // 注册中途失败：尽力回滚，不掩盖原始异常。
+            }
+        }
+        throw error;
+    }
+    return () => {
+        for (const dispose of disposers.splice(0))
+            dispose();
+    };
+}
+/** 供测试断言：工具说明里必须出现的行为约束。 */
+export const KNOWLEDGE_TOOL_GUIDE_TEXT = KNOWLEDGE_TOOL_GUIDE;

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

@@ -1,13 +1,27 @@
 /**
- * 知识库页。
+ * 中央页「知识库」（feature id `knowledge` / order 30）。
  *
- * 本阶段只渲染页面骨架 + 一句占位文案：真正的知识库能力（海普对接、检索、索引）
- * 落地后替换 `placeholder` 区域即可，页面外壳、菜单注册与生命周期都不需要改动。
+ * 只读视图：知识库列表 + 文档列表 + 检索片段 + **文档正文**。
+ *  - 数据全部来自 Host 的 loopback RPC（`KnowledgeRuntime`），本组件不发任何 HTTP；
+ *  - 后端不可用时显示 `lastError` 与重试按钮，而不是空白页；
+ *  - 自检告警（如「未绑 rerank」）直接显示在顶部：这类错误在后端是静默的，
+ *    只有显式提示用户，才不会把"结果不准"当成"企业没这个资料"。
+ *
+ * 版式：左栏选知识库、右栏看内容（列表 / 检索结果 / 文档正文三态互斥），检索行钉在右栏顶部。
+ *
+ * 中央区接管时**页面根不滚**，滚动收进两栏各自的 `.hiwork-knowledge-scroll`：在几百篇
+ * 文档里滚到一半想换个库或改检索词，控件还得在手边——而整页滚动会把它们一起带走。
+ * 降级到设置页分区时没有高度约束，那几条「填满剩余高度再裁剪」的规则自然不生效。
+ *
+ * 三个可观察的版式纪律（都有测试盯着，见 `tests/styles-coverage.spec.ts`）：
+ *  1. 原生 `<ul>` 的圆点与 40px 左缩进必须清掉——留着就是「没写样式」的观感；
+ *  2. 区块标题不能是裸 `<h2>`（浏览器默认给 1.5em 粗体，比页头还大，层级直接反过来）；
+ *  3. 组件里出现的每个 `hiwork-knowledge-*` 类名都必须在 `styles.css` 里有规则。
  */
 import { type ReactElement } from 'react';
 import type { KnowledgeViewProps } from './contracts.js';
 /**
- * 知识库占位页。
- * @param props - 翻译函数与可选的关闭回调。
+ * 知识库页（中央内容区）。
+ * @param props - 翻译函数、运行时、可选的关闭回调与会话发送能力。
  */
 export declare function KnowledgeView(props: KnowledgeViewProps): ReactElement;

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

@@ -0,0 +1,42 @@
+/**
+ * 设置页「知识库」分区：凭据与默认范围 + 自检。
+ *
+ * 与中央页的分工：
+ *  - 中央页是**浏览**（列表/文档/检索）；
+ *  - 本分区是**配置**，所以它不会被中央页的注册撤下——没有 core 时也照常可用；
+ *  - 自检（`测试连接`）会真实打后端，并展示逐条结论：连接、探针检索、问答 Agent。
+ *    其中「rerank 未生效」只有靠分数区间才看得出来（后端不会报错），是这块 UI 的主要价值。
+ */
+import { type ReactElement } from 'react';
+import type { KnowledgeSettingsProps } from './contracts.js';
+import type { KnowledgeConfigPatchWire } from './runtime.js';
+/** 把逗号/换行分隔的知识库 ID 串解析成数组。 */
+export declare function parseBaseIds(raw: string): string[];
+/** 表单初值（从 Host 快照投影）。 */
+export interface SettingsForm {
+    baseUrl: string;
+    apiKey: string;
+    tenantId: string;
+    defaultBases: string;
+    maxResults: string;
+    maxChunkChars: string;
+    agentId: string;
+    chatModelId: string;
+}
+/** 依据快照构造表单初值（apiKey 永远留空：Key 不回传）。 */
+export declare function formFromSnapshot(config: {
+    baseUrl: string;
+    tenantId: string;
+    defaultBaseIds: readonly string[];
+    maxResults: number;
+    maxChunkChars: number;
+    agentId: string;
+    chatModelId: string;
+}): SettingsForm;
+/** 表单 → 补丁：只提交变化过的字段；`apiKey` 仅在用户真的输入时才提交。 */
+export declare function patchFromForm(form: SettingsForm, initial: SettingsForm): KnowledgeConfigPatchWire;
+/**
+ * 知识库设置分区。
+ * @param props - 翻译函数、运行时与宿主提供的关闭回调。
+ */
+export declare function KnowledgeSettings(props: KnowledgeSettingsProps): ReactElement;

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

@@ -0,0 +1,26 @@
+/**
+ * 知识库工具调用的**专属卡片**（`tool.call.toolview`，按线上工具名 keyed）。
+ *
+ * 为什么必须有它：M0 起 Agent 就能查知识库了，但调用走的是 shell 的**通用工具行**，
+ * 用户看到的是「它回答了」而不是「它查到了什么」。卡片把检索结果变成可读的凭据：
+ * 文档名 + 段号 + 片段 + 出处，以及「追问」与「在知识库页打开」两个动作。
+ *
+ * 注册是**纯增量**的：keyed 槽位里未认领的键落回通用工具行，我们只认领自己的 4 个工具名。
+ *
+ * 三条实测得来的渲染约束：
+ *  1. `block.argsRaw` 是**原始 JSON 字符串**（running 阶段唯一的可用信息），结果则藏在
+ *     `content[0].text` 里又是一层 JSON —— 解析全在 `tool-result.ts`（纯函数，有单测）；
+ *  2. 结果还没回来时（running）也要渲染：只显示「正在检索知识库 · <查询词>」，否则工具执行
+ *     期间这个位置是空的，用户不知道它在干嘛；
+ *  3. `followUp` 与 `openDocument` 是**可选能力**：宿主没给（或会话作用域解析不到）时不渲染
+ *     对应按钮，而不是渲染一个点了报错的按钮。
+ */
+import { type ReactElement } from 'react';
+import type { KnowledgeToolRowProps } from './contracts.js';
+/**
+ * 一次知识库工具调用的卡片。
+ * @param props - keyed 工具视图的 owner 面 + 本地化座 + 可选动作。
+ */
+export declare function KnowledgeToolRow(props: KnowledgeToolRowProps): ReactElement;
+/** 便于测试断言：卡片只认领这几个工具名。 */
+export declare const KNOWLEDGE_TOOLVIEW_TITLES: Record<string, string>;

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

@@ -0,0 +1,98 @@
+/**
+ * 把一段文本放进**某个会话的输入框**（卡片上的「追问」、页面上的「带进聊天」）。
+ *
+ * 为什么不是 `conversation.send(text)`：那会立刻排一轮对话发出去，用户没有反悔余地；
+ * 而且 `send()` 是**按调用方作用域寻址**的，本插件的 ctx 是 root 作用域，直接调会抛
+ * `conversation.send requires a session scope`。放进草稿既符合「带进聊天」的语义，
+ * 也把「发不发、要不要改」留给用户。
+ *
+ * 三个必须照抄的宿主细节（都来自 `hiwork-capabilities/src/client/composer.ts` 的实测结论）：
+ *  1. **`actx.get('conversation')` 而不是 `actx.conversation`**：后者是属性访问，会撞上
+ *     cordis 的注入门禁（`cannot get property "conversation" without inject`），而本插件
+ *     的顶层 `inject` 里没有 `conversation`（也不该有——那是可选能力）；
+ *  2. **`sessions.scope(id)` 失败时退到 `sessions.binding(id).ctx`**：两条路在不同宿主
+ *     版本上互为兜底，且都要 try/catch——读属性本身就可能抛；
+ *  3. **读快照与插入之间不得有 await**：`draftRev` 是 CAS 票据，中间让出一次事件循环，
+ *     草稿被别人改过就会必然被拒。所以本模块整体是**同步**的。
+ *
+ * 本文件零依赖：bundle 必须自包含。
+ */
+/** 草稿里的引用 chip 占位（结构契约）。 */
+export interface ComposerOccurrence {
+    readonly offset: number;
+    readonly length: number;
+}
+/** 输入机状态里本模块用到的部分（结构契约）。 */
+export interface ComposerInputState {
+    /** 剪贴板投影：chip 展开成各自的 `clipboardText`。 */
+    readonly draft: string;
+    /** 单调递增的编辑器版本号，插入时用作 CAS 票据。 */
+    readonly draftRev: number;
+    /**
+     * 提交相位；旧宿主可能没有这个字段，缺省视为可写。
+     *
+     * 写成 `| undefined`（而不是裸 `?`）是本仓库 tsconfig 的 `exactOptionalPropertyTypes`
+     * 要求：裸可选成员不能显式传 `undefined`，而调用方/测试需要能这么写。
+     */
+    readonly phase?: 'plain' | 'adjudicating' | 'claimed' | 'submitting' | undefined;
+    /** 草稿里的引用 chip，按 offset 升序。 */
+    readonly occurrences?: readonly ComposerOccurrence[] | undefined;
+}
+/** 会话作用域的输入机面（`conversation.input.for(actx)` 的返回值）。 */
+export interface ComposerInsertionTarget {
+    readonly state: {
+        getSnapshot(): ComposerInputState;
+    };
+    /** 把普通文本替换进 pick-time span；旧宿主可能没有这个方法。 */
+    insertText?(text: string, span: {
+        start: number;
+        end: number;
+        draftRev: number;
+    }, keepCompleting?: boolean): boolean;
+}
+/** `actx.get('conversation')` 的最小结构面。 */
+export interface ConversationAccess {
+    readonly input: {
+        for(actx: unknown): ComposerInsertionTarget | undefined;
+    };
+}
+/** `ctx.sessions` 的最小面（`scope` 与 `binding` 互为兜底）。 */
+export interface SessionScopeAccess {
+    scope?(id: string): unknown;
+    binding?(id: string): {
+        ctx?: unknown;
+    } | undefined;
+    list?: {
+        getSnapshot(): {
+            readonly current?: string | undefined;
+        };
+    };
+}
+/** 插入结果。失败一律**返回原因**，不抛、不静默——静默会让按钮看起来是坏的。 */
+export type ComposerInsertResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'no-target' | 'busy' | 'rejected';
+};
+/**
+ * 探测草稿在**坐标投影**里的末尾偏移。
+ *
+ * 用 `occurrences` 而不是 `draft.length`：chip 在坐标里只占 1 个位置，而 `draft` 里是
+ * 展开后的全文。拿错投影会被宿主直接拒掉。
+ * @param state - 输入机快照。
+ * @returns 探测坐标里的草稿末尾偏移。
+ */
+export declare function detectTextLength(state: ComposerInputState): number;
+/**
+ * 把文本追加进某个会话输入框的草稿末尾。
+ *
+ * 落点选**末尾**：`/名字 ` 这类文本由宿主自己的触发器敲在光标处，我们追加在末尾不会
+ * 抢走用户已经写了一半的话；中间同样不得有 await（见文件头第 3 点）。
+ *
+ * @param sessions - `ctx.sessions`；缺失时直接判定没有目标。
+ * @param text - 要追加的文本。
+ * @param sessionId - 槽位注入的会话 id；缺省退到 `sessions.list.current`。
+ * @returns 成功或失败原因。
+ */
+export declare function insertDraftText(sessions: SessionScopeAccess | undefined, text: string, sessionId?: string): ComposerInsertResult;

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

@@ -1,3 +1,4 @@
+import type { ComposerInsertResult, SessionScopeAccess } from './composer.js';
 /**
  * client 半边的**类型专用**宿主契约。
  *
@@ -7,16 +8,74 @@
  *  - 所有成员都按“可选能力”建模：宿主版本差异只会让某块 UI 降级，不会让整页崩掉。
  */
 import type { ComponentType, ReactNode } from 'react';
+import type { KnowledgeRuntime } from './runtime.js';
+/** 宿主 loopback RPC：`rpc.call(channel, endpoint, payload, signal?)`。 */
+export interface ClientRpc {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
 /** `ctx.slots.register` 的注册选项（label 用函数以便跟随语言切换）。 */
 export interface SlotRegisterOptions {
     name: string;
     id?: string;
+    /**
+     * **keyed 槽位的分派键**。`tool.call.toolview` 按**线上工具名**分派：
+     * 未认领的键落回通用工具行，所以为自己的工具注册是纯增量行为（不是接管）；
+     * 拼错不会抛错，只是永远不渲染。
+     */
+    key?: string;
     order?: number;
     locale?: string;
     label?: () => string;
     icon?: string;
-    /** 宿主合成到组件属性上的注入面（本插件用它传 `t`）。 */
-    inject?: () => object;
+    /**
+     * 宿主合成到组件属性上的注入面。
+     *
+     * 参数形状按槽位作用域而异（实测自 shell 自己的注册）：
+     *  - root 作用域槽位：`inject()`；
+     *  - **session 作用域槽位：`inject(sessionId, actions)`** —— 第一个参数是会话 id
+     *    （`tool.call.toolview` 的 scope 就是 `session`，因此卡片能拿到自己所属的会话）；
+     *  - `actions` 是**本注册自己提供的 store** 的动作（不传 store 时为 undefined），
+     *    所以它不是通用的编辑器接口，别拿它当 `setDraft` 用。
+     */
+    inject?: ((...args: never[]) => object) | undefined;
+}
+/** 线上文本块（工具 `render` 产出的内容块；只建模本插件用得到的形状）。 */
+export interface ContentBlockLike {
+    readonly type?: unknown;
+    readonly text?: unknown;
+}
+/**
+ * `tool.call.toolview` 的 `block`：running 或 settled 二选一。
+ *
+ * 形状来自 shell 的 `ToolCallBlock = RunningToolCall | ToolResultNode`（实测）：
+ *  - running 只有 `argsRaw`（**原始 JSON 字符串**），没有 `kind`；
+ *  - settled 带 `kind: 'tool-result'`，结果在 `content: ContentBlock[]` 里，
+ *    并且能用 `call?.argsRaw` 回填调用参数（窗口截断时 `call` 为 null）。
+ * 本插件不改这些字段，只读。
+ */
+export interface ToolCallBlockLike {
+    readonly kind?: 'tool-result' | undefined;
+    readonly callId?: string | undefined;
+    readonly argsRaw?: string | undefined;
+    readonly call?: {
+        readonly name?: unknown;
+        readonly argsRaw?: unknown;
+    } | null | undefined;
+    readonly content?: readonly ContentBlockLike[] | undefined;
+    readonly isError?: boolean | undefined;
+    readonly error?: {
+        readonly name?: unknown;
+        readonly code?: unknown;
+    } | undefined;
+    readonly subCalls?: readonly ToolCallBlockLike[] | undefined;
+}
+/** `tool.call.toolview` 的 owner 面（本插件只消费这几个字段）。 */
+export interface ToolCallOwnerPropsLike {
+    readonly callId?: string | undefined;
+    readonly toolName?: string | undefined;
+    readonly block: ToolCallBlockLike;
+    /** 可选：把这次调用丢进轨迹视图（宿主没提供时不渲染该入口）。 */
+    readonly inspect?: (() => void) | undefined;
 }
 /** 宿主语言服务：注册命名空间词典 + 绑定翻译函数。 */
 export interface ClientLocale {
@@ -37,6 +96,10 @@ export interface ClientSlots {
 /** client 插件拿到的宿主上下文（结构兼容 DSH 0.1.2-rc.1 client Context）。 */
 export interface ClientContext {
     effect(factory: () => void | (() => void), label?: string): void;
+    /** loopback RPC：Web 半边取数与提交意图的唯一通道（不直接访问 WeKnora）。 */
+    connection: {
+        readonly rpc: ClientRpc;
+    };
     locale: ClientLocale;
     slots: ClientSlots;
     /**
@@ -89,12 +152,47 @@ export interface HiWorkFeatureRenderContext {
     readonly openNativeSession: (sessionId: string) => void;
     readonly openNativeHome: () => void;
 }
+/** `ctx.sessions` 的最小面（结构契约见 `./composer.js`）。 */
+export type ClientSessions = SessionScopeAccess;
 /** 翻译函数：`t(key, params)`，未命中时宿主回退到 key 本身。 */
 export type Translate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * 工具卡片（`tool.call.toolview`）的属性。
+ *
+ * `t` 来自注册时的 `locale` 座；`block`/`toolName`/`inspect` 来自 keyed 槽位的 owner 面；
+ * `followUp` / `openDocument` 是本插件自己经 `inject` 注入的**可选能力**——
+ * 宿主或会话作用域解析不到时就不传，卡片会隐藏对应按钮而不是点了报错。
+ */
+export interface KnowledgeToolRowProps extends ToolCallOwnerPropsLike {
+    t: Translate;
+    /** 往这个卡片所属的会话发一条消息（「追问」）。 */
+    /** 把追问写进本会话的输入框；**返回结果**，失败原因由卡片显示在行内。 */
+    followUp?: ((text: string) => ComposerInsertResult) | undefined;
+    /** 在知识库页打开这篇文档。 */
+    openDocument?: ((knowledgeId: string) => void) | undefined;
+}
 /** 知识库页组件属性。 */
 export interface KnowledgeViewProps {
     /** 本插件命名空间（`hiwork-knowledge`）的翻译函数。 */
     t: Translate;
+    /** 客户端运行时（Host 快照 + 动作；视图不直接访问 WeKnora）。 */
+    runtime: KnowledgeRuntime;
     /** 关闭设置面板（降级到设置页分区时由宿主提供）。 */
     closeSettings?: () => void;
+    /**
+     * 把一段文本放进**当前打开**会话的输入框（「带进聊天」）。
+     *
+     * 可选：解析不到会话（没有打开的会话 / 宿主没提供 `sessions`）时不传，
+     * 页面因此不渲染那两个按钮——比渲染一个点了没反应的入口诚实。返回结果而不是抛，
+     * 是为了让页面能把「为什么没放进去」直接显示出来。
+     */
+    putInComposer?: ((text: string) => ComposerInsertResult) | undefined;
+}
+/** 设置页「知识库」分区的组件属性（与中央页共用同一个运行时）。 */
+export interface KnowledgeSettingsProps {
+    t: Translate;
+    runtime: KnowledgeRuntime;
+    /** 宿主提供的关闭回调（不同宿主版本给的键名不同）。 */
+    close?: () => void;
+    closeSettings?: () => void;
 }

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

@@ -0,0 +1,19 @@
+/**
+ * 跨座位的「跳转焦点」：聊天里的卡片要求知识库页打开某篇文档。
+ *
+ * 为什么需要它：中央页是 DOM 接管 + 独立 React 根，卡片在**聊天**里，两者之间没有
+ * 共享的 React 树，插件也不能碰 shell 的 DOM。于是用模块级的一次性信箱传递意图：
+ * 卡片写入 → 调用 `hiworkFeatureCenter.openFeature('knowledge')` 切页 → 页面挂载时取走。
+ *
+ * 取走即清空（consume 语义），所以：
+ *  - 页面重复渲染不会反复跳转；
+ *  - 用户手动切库/返回列表后不会被旧意图拽回去。
+ *
+ * client bundle 纯度：本文件零依赖（连 React 都不 import），可被任何半边引用。
+ */
+/** 登记「下次打开知识库页时请定位到这篇文档」。 */
+export declare function requestDocumentFocus(knowledgeId: string): void;
+/** 取走当前焦点（取走即清空）；没有待处理意图时返回 null。 */
+export declare function consumeDocumentFocus(): string | null;
+/** 是否有待处理意图（只读，不消费；供渲染期判断用）。 */
+export declare function hasDocumentFocus(): boolean;