refactor(tool-bailian-kb): 合并 bundle 功能到插件包并简化结构

- 移除独立的 bundle 包及其配置文件和说明文档 - 将原 bundle 的 patch 配置迁移到插件包内的 cordis.patch.yml - 在插件包 package.json 中声明 dsh.bundle.patch 指向新 patch 文件 - 更新 README，说明插件包即是 bundle，简化安装和本地联调流程 - 调整文档中插件名及卸载命令，统一使用 dsh-tool-bailian-kb - 修正仓库结构描述，将包称为目录，更准确反映当前结构 - 改进配置解析链和 Web UI 配置页的说明，突出用户层设置及覆盖机制
2026-09-14 19:49:23 +08:00 · 2026-08-17 15:21:41 +08:00
parent cda1e326f3
commit dbf83c3e16
7 changed files with 58 additions and 94 deletions
@@ -6,15 +6,14 @@

 ## 仓库结构

-| 包 | 职责 |
+| 目录 | 职责 |
 |---|---|
-| [`packages/tool-bailian-kb`](packages/tool-bailian-kb/README.md) | 插件本体：Config、KbClient、三个工具、随包打包的管理 skill |
-| [`packages/bundle`](packages/bundle/README.md) | 分发面：`dsh.bundle` 声明 + `cordis.patch.yml` |
+| [`packages/tool-bailian-kb`](packages/tool-bailian-kb/README.md) | 插件包（同时是 dsh bundle）：Config、KbClient、工具、skill、cordis.patch.yml、浏览器端配置页 |

 ## 安装（dsh 用户）

 ```sh
-dsh plugin --profile web add bailian-kb-dsh   # npm 发布后；本地开发用绝对/相对路径
+dsh plugin --profile web add dsh-tool-bailian-kb   # npm 发布后；本地开发用绝对/相对路径
 ```

 安装后 CLI 自动把 bundle 加入 profile 的层栈，无需手改 YAML。
@@ -28,7 +27,7 @@ DASHSCOPE_API_KEY=sk-xxx           # 必填：也可放 ~/.dsh/.credentials.yaml

 验证：`dsh --profile web --dump-config` 应能看到 `tool-bailian-kb` row。缺 `BAILIAN_WORKSPACE_ID` 时加载期直接报错（fail loud），不会静默跳过。

-卸载：`dsh plugin --profile web remove bailian-kb-dsh`。
+卸载：`dsh plugin --profile web remove dsh-tool-bailian-kb`。

 ## 开发

@@ -41,11 +40,10 @@ pnpm run typecheck
 pnpm run build       # tsc 产出 lib/
 ```

-本地联调：`link:` 安装不会把被链接包的依赖装进 profile，需要把 bundle 和插件包**都** add 进去（插件包会报 "declares no dsh.bundle — installed as a plain dependency" 警告，符合预期）；npm 正式安装无此问题：
+本地联调：只需 add 一次（包同时声明 `dsh.bundle` 和插件代码）：

 ```sh
-dsh plugin --profile dev add <本仓库>/packages/bundle
-dsh plugin --profile dev add <本仓库>/packages/tool-bailian-kb   # 仅 link 联调需要
+dsh plugin --profile dev add <本仓库>/packages/tool-bailian-kb
 ```

 patch 文件受 HMR 监听。
@@ -1,65 +0,0 @@
-# bailian-kb-dsh（分发包）
-
-dsh bundle 分发面：`package.json` 的 `dsh.bundle.patch` 声明 + [`cordis.patch.yml`](cordis.patch.yml)，向 profile 插入 `tool-bailian-kb` row，并随包分发浏览器端配置页（`dsh.client` → `lib/client.js`）。
-
-## Patch row
-
-```yaml
- insert:
-    - id: tool-bailian-kb
-      name: dsh-tool-bailian-kb
-      config:
-        workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID
-```
-
-`workspaceId` 只是解析链的一层，不是唯一来源：Config 同时注册为 `bailian-kb` settings namespace，patch entry 作 base 层，设置页/设置文档的用户层叠在其上；都未设置时 per-call 回退到 `BAILIAN_WORKSPACE_ID` credential。同样回退覆盖 `defaultRetrieveAgentId`（`BAILIAN_DEFAULT_RETRIEVE_AGENT_ID`）、`defaultChatAgentId`（`BAILIAN_DEFAULT_CHAT_AGENT_ID`）与 API key（`DASHSCOPE_API_KEY`，无 settings 面）。
-
-## 四个值的解析链
-
-| 值 | 1️⃣ settings 用户层（设置页可编辑、回显） | 2️⃣ entry config（本 patch 或用户覆盖，作 base 层） | 3️⃣ credential（`~/.dsh/.credentials.yaml` / env） | 4️⃣ 都缺失时 |
-|---|---|---|---|---|
-| `DASHSCOPE_API_KEY` | —（无 settings 面） | —（无 config 面） | ✅ | 工具调用报错并引导配置 |
-| `BAILIAN_WORKSPACE_ID` | ✅ `workspaceId` | ✅ `workspaceId` | ✅ | 工具调用报错并引导配置 |
-| `BAILIAN_DEFAULT_RETRIEVE_AGENT_ID` | ✅ `defaultRetrieveAgentId` | ✅ `defaultRetrieveAgentId` | ✅ | `kb_search` 的 `agent_id` 参数变必填（schema 恒 optional，运行时校验） |
-| `BAILIAN_DEFAULT_CHAT_AGENT_ID` | ✅ `defaultChatAgentId` | ✅ `defaultChatAgentId` | ✅ | `kb_chat` 的 `agent_id` 参数变必填（schema 恒 optional，运行时校验） |
-
-行为参数（`endpointHost`/`agentVersion`/`chatTimeoutMs`）在 config/settings 层（设置文档可改，实时生效），见 [tool-bailian-kb README](../tool-bailian-kb/README.md)。
-
-## Web UI 配置页
-
-装进 profile 后，Settings 左侧导航出现“百炼知识库”页（`settings.section` 槽位）：
-
- **DashScope API Key** — write-only（凭据域 wire 结构上无值位，永不回显），`type=password` 遮罩输入草稿，仅显示 configured/来自环境变量 徽标；写 `~/.dsh/.credentials.yaml`
- **Bailian Workspace ID / 默认检索服务 ID / 默认对话服务 ID** — **回显**：读写 `bailian-kb` settings 用户层（设置文档），预填当前解析值；清空保存 = 移除用户层，回退 entry config → credential；每个默认服务 ID 附“清除”按钮（同时 unset settings 用户层与 credential，避免回退链复活旧值）
-
-降级：远程浏览器（非 loopback，settings RPC 不可达）或未组合 settings 服务时，ID 字段退回旧的 write-only credential 控件，页面顶部显示提示。
-
-## 用户覆盖
-
-用户 patch 层在本 bundle 之上，按 id 覆盖时**替换整个 config（无 deep-merge）**，覆盖后的 config 成为 settings namespace 的新 base 层（设置页的用户层仍叠在其上）。`workspaceId`/`defaultRetrieveAgentId`/`defaultChatAgentId` 均为可选，只需重述想显式固定的字段：
-
-```yaml
-# ~/.dsh/cordis.patch.yml 或 profile 的 cordis.patch.yml
- id: tool-bailian-kb
-  config:
-    defaultRetrieveAgentId: aid-search-service   # 检索服务；省略 workspaceId 走 credential
-    defaultChatAgentId: aid-chat-service         # 对话服务
-    chatTimeoutMs: 600000
-```
-
-禁用：`- id: tool-bailian-kb` + `disabled: true`。
-
-## 安装（本地 checkout 链接）
-
-bundle 是 `dsh.bundle` 声明层，真正的插件包 `dsh-tool-bailian-kb` 是它的依赖；`link:` 安装不携带传递依赖，**两个包都要 add**（第二个无 bundle 声明，dsh 会以 plain dependency 装入，CLI 的 warning 即预期行为）：
-
-```sh
-dsh plugin --profile web add /path/to/bailian-kb-dsh/packages/bundle
-dsh plugin --profile web add /path/to/bailian-kb-dsh/packages/tool-bailian-kb
-```
-
-## 卸载
-
-```sh
-dsh plugin --profile <name> remove bailian-kb-dsh dsh-tool-bailian-kb
-```
@@ -1,13 +0,0 @@
-{
-  "name": "bailian-kb-dsh",
-  "version": "0.1.0",
-  "description": "Installable dsh bundle for Bailian knowledge-base tools: kb_service_list, kb_search, kb_chat plus the kscli management skill.",
-  "type": "module",
-  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
-  "exports": {
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": ["cordis.patch.yml"],
-  "dependencies": { "dsh-tool-bailian-kb": "workspace:^" }
-}
@@ -1,6 +1,55 @@
 # dsh-tool-bailian-kb

-百炼知识库的 dsh 插件本体：在 `ctx.tools` 注册两个检索模型工具（kb_search、kb_chat），并在 skills 服务可用时注册管理面 skill。服务发现通过 kscli CLI 完成。
+百炼知识库的 dsh 插件包（同时是 dsh bundle）：在 `ctx.tools` 注册两个检索模型工具（kb_search、kb_chat），并在 skills 服务可用时注册管理面 skill。服务发现通过 kscli CLI 完成。
+
+## Bundle 声明
+
+`package.json` 的 `dsh.bundle.patch` 指向 [`cordis.patch.yml`](cordis.patch.yml)，向 profile 插入插件行：
+
+```yaml
+- insert:
+    - id: tool-bailian-kb
+      name: dsh-tool-bailian-kb
+      config:
+        workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID
+```
+
+`workspaceId` 只是解析链的一层，不是唯一来源：Config 同时注册为 `bailian-kb` settings namespace，patch entry 作 base 层，设置页/设置文档的用户层叠在其上；都未设置时 per-call 回退到 `BAILIAN_WORKSPACE_ID` credential。同样回退覆盖 `defaultRetrieveAgentId`（`BAILIAN_DEFAULT_RETRIEVE_AGENT_ID`）、`defaultChatAgentId`（`BAILIAN_DEFAULT_CHAT_AGENT_ID`）与 API key（`DASHSCOPE_API_KEY`，无 settings 面）。
+
+### 四个值的解析链
+
+| 值 | 1️⃣ settings 用户层（设置页可编辑、回显） | 2️⃣ entry config（本 patch 或用户覆盖，作 base 层） | 3️⃣ credential（`~/.dsh/.credentials.yaml` / env） | 4️⃣ 都缺失时 |
+|---|---|---|---|---|
+| `DASHSCOPE_API_KEY` | —（无 settings 面） | —（无 config 面） | ✅ | 工具调用报错并引导配置 |
+| `BAILIAN_WORKSPACE_ID` | ✅ `workspaceId` | ✅ `workspaceId` | ✅ | 工具调用报错并引导配置 |
+| `BAILIAN_DEFAULT_RETRIEVE_AGENT_ID` | ✅ `defaultRetrieveAgentId` | ✅ `defaultRetrieveAgentId` | ✅ | `kb_search` 的 `agent_id` 参数变必填 |
+| `BAILIAN_DEFAULT_CHAT_AGENT_ID` | ✅ `defaultChatAgentId` | ✅ `defaultChatAgentId` | ✅ | `kb_chat` 的 `agent_id` 参数变必填 |
+
+行为参数（`endpointHost`/`agentVersion`/`chatTimeoutMs`）在 config/settings 层（设置文档可改，实时生效）。
+
+### Web UI 配置页
+
+装进 profile 后，Settings 左侧导航出现“百炼知识库”页（`settings.section` 槽位）：
+
+- **DashScope API Key** — write-only，`type=password` 遮罩输入草稿，仅显示 configured/来自环境变量 徽标；写 `~/.dsh/.credentials.yaml`
+- **Bailian Workspace ID / 默认检索服务 ID / 默认对话服务 ID** — 回显：读写 `bailian-kb` settings 用户层，预填当前解析值；清空保存 = 移除用户层，回退 entry config → credential
+
+降级：远程浏览器（非 loopback，settings RPC 不可达）或未组合 settings 服务时，ID 字段退回旧的 write-only credential 控件，页面顶部显示提示。
+
+### 用户覆盖
+
+用户 patch 层在本 bundle 之上，按 id 覆盖时**替换整个 config（无 deep-merge）**：
+
+```yaml
+# ~/.dsh/cordis.patch.yml 或 profile 的 cordis.patch.yml
+- id: tool-bailian-kb
+  config:
+    defaultRetrieveAgentId: aid-search-service
+    defaultChatAgentId: aid-chat-service
+    chatTimeoutMs: 600000
+```
+
+禁用：`- id: tool-bailian-kb` + `disabled: true`。

 ## Config

@@ -11,6 +11,7 @@
    "./package.json": "./package.json"
  },
  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "inject": [
        "@deepseek-ai/dsh-client-connection",
@@ -22,7 +23,7 @@
      "platform": "web"
    }
  },
-  "files": ["lib", "skills"],
+  "files": ["lib", "skills", "cordis.patch.yml"],
  "scripts": { "build": "tsc -b && tsdown" },
  "peerDependencies": {
    "@deepseek-ai/cordis": "^4.0.1",
@@ -15,12 +15,6 @@ importers:
        specifier: ^3.0.0
        version: 3.2.7(@types/node@22.20.1)(lightningcss@1.33.0)

-  packages/bundle:
-    dependencies:
-      dsh-tool-bailian-kb:
-        specifier: workspace:^
-        version: link:../tool-bailian-kb
-
  packages/tool-bailian-kb:
    devDependencies:
      '@deepseek-ai/cordis':