hiwork-knowledge 0.1.1 → 0.2.0

package/README.md

@@ -1,55 +1,99 @@
 # hiwork-knowledge
 
-HiWork 的**知识库**插件。本阶段只提供入口与占位页：中央内容区出现「知识库」菜单项，
-点开是一句占位文案（此处对接海普知识库相关内容），真正的知识库能力（海普对接、
-检索、索引）后续在 `KnowledgeView` 的占位区域落地。
+HiWork 的**知识库**插件：把腾讯 [WeKnora](https://github.com/Tencent/WeKnora) 接进桌面端。
+
+两个半边，职责分离：
+
+| 半边 | 做什么 |
+| --- | --- |
+| **Host**（`src/*.ts`） | 凭据、出网、Agent 工具、loopback RPC。是唯一事实来源 |
+| **Web**（`src/client/**`） | 中央页浏览（知识库/文档/检索）+ 设置页配置与自检。**不发 HTTP、拿不到凭据** |
 
 - 包名 / bundle id：`hiwork-knowledge`
 - client 插件名：`hiwork-knowledge-client`
-- 中央页 feature：`id = knowledge`，`order = 30`（排在「新会话」与定时任务 20 之后）
+- 中央页 feature：`id = knowledge`，`order = 30`
+- RPC 频道：`/hiwork-knowledge`（端点 `snapshot` / `config-save` / `config-test` / `docs` / `search`）
+- Agent 工具（M0 全部只读）：`knowledge_list_bases`、`knowledge_search`、`knowledge_read_document`、`knowledge_ask`
+- 后端（内网）：`https://hiwork-knowledge.hivery.cn`（部署见该服务器 `~/docker-projects/weknora/DEPLOY-HIWORK.md`）
 
 ## 目录
 
 ```
 src/
-  index.ts                 Host 入口（本阶段只声明插件名 + 启动日志）
+  index.ts                Host 入口：开存储域、挂工具、注册 RPC 与提示词片段
+  service.ts              KnowledgeService：凭据解析 / 出网客户端 / 检索健康自检
+  weknora.ts              WeKnora REST 客户端（超时、SSE、错误归一）
+  tools.ts                4 个 Agent 工具
+  rpc.ts / protocol.ts    /hiwork-knowledge 的 Host 实现与线上契约
+  types.ts                领域类型、默认值、存储域定义（hiwork_knowledge）
+  prompt.ts               系统提示词片段与工具指引
   client/
-    index.ts               Web 入口：注册 feature / 设置页降级
-    KnowledgeView.tsx      知识库页（占位）
-    locales.ts             命名空间 hiwork-knowledge 的 zh/en 词典
-    contracts.ts           宿主 client 能力的结构契约（type-only）
-    styles.ts / styles.css 样式注入
+    index.ts              Web 入口：注册中央 feature + 设置页分区
+    runtime.ts            客户端状态源（Host 快照 + 动作；含传输失败重试一次）
+    KnowledgeView.tsx     中央页：知识库列表 / 文档列表 / 检索片段
+    SettingsSection.tsx   设置页：凭据表单 + 「测试连接」（自检）
+    contracts.ts          宿主 client 能力的结构契约（type-only）
+    locales.ts / styles.* 词典与样式
 scripts/
-  host-build.mjs           Host 产物自包含打包（esbuild）
-  client-build.mjs         Client 产物闭包工厂打包（esbuild）
-tests/                     入口、视图、feature 注册、打包契约
+  host-build.mjs          Host 产物自包含打包（esbuild）
+  client-build.mjs        Client 产物闭包工厂打包（esbuild）
+  live-smoke.{ts,mjs}     联调冒烟（打真实后端）
+tests/                    客户端协议、服务、工具、RPC、入口、视图、打包契约
 ```
 
-## 入口
+## 两个入口（同时存在，不再二选一）
 
-| 项 | 值 |
-| --- | --- |
-| feature id | `knowledge` |
-| order | `30` |
-| 菜单文案 | `知识库`（跟随语言切换，词典键 `view.title`） |
-| 图标 | 内联 SVG（书本），侧栏折叠成图标栏时只显示它 |
-| render | 复用 `KnowledgeView`，不依赖 `FeatureRenderContext` |
+| 入口 | 注册条件 | 用途 |
+| --- | --- | --- |
+| 中央页 feature `knowledge` | 存在 `hiwork-core` 的 `hiworkFeatureCenter` | 浏览：知识库 / 文档 / 检索 |
+| 设置页分区 `settings.section#knowledge` | 始终注册 | 配置：凭据 / 默认范围 / 问答 Agent / 自检 |
 
-注册走 `hiwork-core` 的 `hiworkFeatureCenter` 服务（结构契约见
-`src/client/contracts.ts`，运行时**不** import `hiwork-core`，符合 DSH client
-模块表「feature 插件之间禁止 runtime-import」的约束）。
+> 与 `hiwork-automation` 的策略不同：那边设置页是中央页的降级替身，所以 core 出现后要撤下；
+> 这边设置页承载的是**配置**（浏览面里没有第二处可改），撤掉用户就没法配凭据，因此恒在。
 
-## 独立安装降级
+没有 `hiwork-core` 时插件仍可用：只能配置 + 通过 Agent 工具检索，没有中央页入口。
 
-没有 `hiwork-core` 时（或它尚未加载），本插件注册设置页分区
-`settings.section#knowledge`；`hiwork-core` 后到时立刻撤下该分区并切成中央 feature，
-保证同一功能不会同时出现两个主入口。
+## 聊天会话里的集成（M1）
 
-## client bundle 纯度
+工具卡片与「带进聊天」是**可选增强**：宿主缺哪个能力就少哪块 UI，工具本身照常可用。
 
-`src/client/**` 对 `@deepseek-ai/*` 只允许 `import type`（打包时被擦除），运行时只
-import `react` / `react/jsx-runtime`。`tests/packaging.spec.ts` 会在构建后扫描
-`lib/client.js` 的 `require` 说明符，越界即失败。
+| 座位 / 能力 | 注册条件 | 作用 |
+| --- | --- | --- |
+| `tool.call.toolview`（按**线上工具名** keyed） | 始终注册 | 4 个 `knowledge_*` 工具在聊天里渲染成知识库卡片（文档名 + 段号 + 片段 + 「读全文 / 追问」），不再落回通用工具行 |
+| `sessions`（`ctx.get('sessions')`） | 宿主提供时 | 「追问」把追问句写进**该会话的输入框**；页面「带进聊天」写进当前会话 |
+| 文档正文（`document` RPC 端点） | 始终注册 | 中央页点文档行 → 右栏读全文（分页），消掉「只能搜出片段」 |
+
+三条硬约束（都踩过，见 `src/client/composer.ts` 与 `src/tool-names.ts` 的头注）：
+
+1. **工具名走 `src/tool-names.ts` 单一事实源**。keyed 座位按线上工具名分派，拼错**不抛错**、
+   只是卡片永不渲染——两边各写一份必然漂移。
+2. **放进输入框只能走 `actx.get('conversation').input.for(actx).insertText(...)`**，
+   不能 `conversation.send()`：属性访问会撞 cordis 注入门禁
+   （`cannot get property "conversation" without inject`），而且 `send()` 会立刻发一轮、用户无法反悔。
+   读快照到插入之间**不得有 await**（`draftRev` 是 CAS 票据）。
+3. **动作失败必须看得见**：插入会以「没有打开的会话 / 输入框正忙」被拒，
+   `insertDraftText` 因此返回 `{ok, reason}` 而不是 `void`，卡片与页面把原因显示在行内。
+
+## 凭据与安全边界
+
+- 有效凭据来源优先级：**本机设置 > 环境变量（`HIWORK_KNOWLEDGE_API_KEY` / `WEKNORA_API_KEY`）> 空**
+  （网关下发在 M1 接入，届时插到最前面，见设计文档 §D1）。
+- API Key 只存在于 Host 半边：设置页只能看到 `hasApiKey` 布尔与来源，输入框是 `password`。
+- 落盘位置：DSH 存储域 `hiwork_knowledge` 的 `settings` 表（域名单下划线，见 `types.ts`）。
+- 出网错误信息里回显 WeKnora 的原始理由，但**绝不回显 Key**（`tests/weknora.spec.ts` 有断言）。
+- 一期只发只读能力：Key 用 `role=viewer` + `capabilities=[retrieve, chat, read_agents]`，不下发 `ingest`。
+
+## 检索健康自检（别删这块）
+
+后端的检索会**静默给错结果**，HTTP 层看不出来。`selfCheck()` 因此分两层：
+
+| 断言 | 判据 | 为什么要它 |
+| --- | --- | --- |
+| `connection` | `GET /knowledge-bases` 成功 | 认证/网络是否通 |
+| `retrieval` / `probe-miss` / `rerank-missing` | 用「第一篇文档的标题」做探针检索：0 命中 → `probe-miss`；最高分 < 0.05 → `rerank-missing` | 未绑 rerank 时后端退化成 RRF 排序，**任意查询都返回同一个分块**（实测分数恒为 0.0164；绑好后同一批查询是 0.44–0.62） |
+| `ask` / `ask-unconfigured` | 是否配了自建问答 Agent | 内置 Agent 的 `model_id` 为空，`/agent-chat` 会直接报错 |
+
+「测试连接」按钮会把这几条逐条渲染出来。
 
 ## 命令
 
@@ -59,21 +103,71 @@ import `react` / `react/jsx-runtime`。`tests/packaging.spec.ts` 会在构建后
 | `pnpm build` | 构建 `lib/index.js`（Host）与 `lib/client.js`（Web） |
 | `pnpm test` | Vitest（DOM 用例首行 `// @vitest-environment jsdom`） |
 | `pnpm verify` | typecheck → build → test（提交前跑这个） |
+| `pnpm smoke:live` | 打**真实后端**的联调冒烟（见下） |
+
+## 联调冒烟（真实后端）
+
+```bash
+HIWORK_KNOWLEDGE_API_KEY=sk-... \
+HIWORK_KNOWLEDGE_AGENT_ID=<自建问答 Agent ID> \
+HIWORK_KNOWLEDGE_CHAT_MODEL_ID=<chat 模型 ID> \
+pnpm smoke:live
+```
+
+它会跑：自检 → 列库 → 列文档 → 四个工具（经真实工具定义执行）。任一环节失败以非零码退出。
+可选变量：`HIWORK_KNOWLEDGE_BASE_URL`（默认指向内网部署域名）。
 
 ## 本地试用（不打包桌面端）
 
 ```bash
-pnpm build && pnpm pack        # 产出 hiwork-knowledge-0.1.0.tgz
+pnpm build && pnpm pack        # 产出 hiwork-knowledge-0.2.0.tgz
 ```
 
 在 DSH profile（如 `~/.dsh/profiles/web`）的 `package.json` 里加依赖
-`"hiwork-knowledge": "file:<绝对路径>/hiwork-knowledge-0.1.0.tgz"`，并在
+`"hiwork-knowledge": "file:<绝对路径>/hiwork-knowledge-0.2.0.tgz"`，并在
 `dsh.profile.bundles` 追加 `"hiwork-knowledge"`，然后 `pnpm install --force`
 并重启 `dsh web`（Host 半边变化必须重启，只改 client 时刷新页面即可）。
 
-## 后续
+## 界面样式（改版式前先读）
+
+样式表是 `src/client/styles.css`（纯 CSS，运行时由 `styles.ts` 注入一个 `<style>`），
+词表与 `hiwork-automation` / `hiwork-capabilities` 对齐（view / header / heading /
+toolbar / button / tag / count / card / panel / status / notice / muted），三个插件视觉上
+属于同一家族。**新增类名必须同时在样式表里写规则**，否则浏览器会按默认样式渲染——`<h2>`
+变成 1.5em 粗体（比 16px 的页头还大）、`<ul>` 带出圆点和 40px 左缩进，整页立刻像没写完。
+`tests/styles-coverage.spec.ts` 拿源码和样式表交叉比对，漏写规则会先红。
+
+四条用实测换来的约束（都写在 `styles.css` 文件头，别凭直觉改回去）：
+
+1. **主题里没有 `state-error-tertiary`**（亮暗两套都没有），语义淡底一律用
+   `color-mix(in srgb, <primary> 10%, transparent)`；
+2. **`bg-layer-1/2/3` 在亮色下全是 `#fff`**，拿它当卡片/徽标底等于没有底——白底上要看得见的
+   中性填充用 `bg-module-platform`（亮 `#f5f6f7`）或 `interactive-bg-hover`；
+3. **别把容器的底色 token 再用在它内部的元素上**：左栏导轨铺 `bg-module-platform`，
+   计数徽标一开始也用它，结果徽标在导轨上直接隐形（截图上只剩一个没有容器的裸数字）。
+   徽标因此改成描边式，白色右栏和浅灰导轨上都成立；
+4. **颜色只给异常态**：一份正常的知识库里绝大多数文档都是 `completed`，逐行染绿会把
+   真正要一眼看到的 `failed` 淹掉，所以正常态是「静默徽标 + 状态点」，只有解析中/失败/排队上色。
+
+版式还有两条硬规矩：中央区接管时**页面根不滚**（滚动收进两栏各自的
+`.hiwork-knowledge-scroll`），以及**列表头是标签不是标题**（12px/600 次级色，比 13px/600
+主色的内容标题更小更淡）。
+
+## client bundle 纯度
+
+`src/client/**` 对 `@deepseek-ai/*` 只允许 `import type`（打包时被擦除），运行时只
+import `react` / `react/jsx-runtime`。`tests/packaging.spec.ts` 会在构建后扫描
+`lib/client.js` 的 `require` 说明符，越界即失败；Host 产物则要求**零模块说明符**
+（依赖全部内联，桌面端补种时 profile 的 `node_modules/@deepseek-ai/*` 会被清空）。
+
+## 里程碑
+
+| 阶段 | 内容 | 状态 |
+| --- | --- | --- |
+| M0 | Host：凭据 + 出网客户端 + 4 个只读工具 + 自检；Web：中央页列表 + 设置页 | ✅ 已交付 |
+| M1 | 中央页检索问答（SSE 实时渲染）、右侧栏检索面板、引用卡片、`signed_token` 身份隔离 | 待开工 |
+| M2 | 上传/删除（人工确认门）、重解析、标签、移动、工作区↔知识库、@知识库 | — |
+| M3 | Wiki 浏览与图谱、FAQ、数据源、office 在线预览联动 | — |
 
-- 接海普知识库：在 Host 半边注册检索/索引服务，client 通过 `ctx.connection.rpc` 取数；
-  页面把 `KnowledgeView` 的占位区域替换为真实列表/搜索。
-- 打包进桌面端：在 `hiwork-desktop/src/bundled-plugins.ts` 增加本地 archive 条目
-  （与 `hiwork-automation` 同一 vendor tarball 流程）。
+设计与决策记录：`docs/superpowers/specs/2026-09-18-weknora-integration-design.md`、
+`docs/superpowers/plans/2026-09-18-weknora-m0-plan.md`。

package/cordis.patch.yml

@@ -1,8 +1,25 @@
 # hiwork-knowledge bundle：叠加进 profile 后同时挂载 Host 半边并发布 Web 客户端。
 # 用法：profile 的 package.json 依赖本包，dsh.profile.bundles 追加 "hiwork-knowledge"。
 #
-# 知识库后端（检索/索引）尚未接入，本阶段 Host 半边没有运行预算，只负责让 bundle
-# 能被加载；配置项留空以便后续按需追加。
+# 这里只是**默认值**：真正生效的凭据在桌面端「设置 → 知识库」里（存在 Host 的存储域
+# hiwork_knowledge，优先级高于本文件）。写在这里的 apiKey 会随包分发，**不要填真 Key**。
 - insert:
     - id: hiwork-knowledge
       name: 'hiwork-knowledge'
+      config:
+        # WeKnora 后端地址；缺 /api/v1 时插件会自动补齐。
+        baseUrl: https://hiwork-knowledge.hivery.cn/api/v1
+        # 空间 API Key 留空：由用户在设置页填，或走环境变量 HIWORK_KNOWLEDGE_API_KEY。
+        apiKey: ''
+        # 平台级 Key 才需要（X-Tenant-ID）。
+        tenantId: ''
+        # 默认检索范围（知识库 ID）；留空 = 凭据可见的全部知识库。
+        defaultBaseIds: []
+        # 每次检索返回的条数上限（服务端还受 rerank_threshold 约束）。
+        maxResults: 8
+        # 单条片段字符上限：超过则截断并向模型显式标记 truncated。
+        maxChunkChars: 1200
+        # 问答用的自建 Agent ID；留空时 knowledge_ask 会给出可执行提示（内置 Agent 会被后端拒绝）。
+        agentId: ''
+        # 问答请求体里的 summary_model_id；留空用后端默认。
+        chatModelId: ''