From dbf83c3e165febfd1842a1e0bc3a1c5f1351542c Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Mon, 17 Aug 2026 15:21:41 +0800 Subject: [PATCH] =?UTF-8?q?refactor(tool-bailian-kb):=20=E5=90=88=E5=B9=B6?= =?UTF-8?q?=20bundle=20=E5=8A=9F=E8=83=BD=E5=88=B0=E6=8F=92=E4=BB=B6?= =?UTF-8?q?=E5=8C=85=E5=B9=B6=E7=AE=80=E5=8C=96=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 移除独立的 bundle 包及其配置文件和说明文档 - 将原 bundle 的 patch 配置迁移到插件包内的 cordis.patch.yml - 在插件包 package.json 中声明 dsh.bundle.patch 指向新 patch 文件 - 更新 README，说明插件包即是 bundle，简化安装和本地联调流程 - 调整文档中插件名及卸载命令，统一使用 dsh-tool-bailian-kb - 修正仓库结构描述，将包称为目录，更准确反映当前结构 - 改进配置解析链和 Web UI 配置页的说明，突出用户层设置及覆盖机制 --- README.md | 14 ++-- packages/bundle/README.md | 65 ------------------- packages/bundle/package.json | 13 ---- packages/tool-bailian-kb/README.md | 51 ++++++++++++++- .../cordis.patch.yml | 0 packages/tool-bailian-kb/package.json | 3 +- pnpm-lock.yaml | 6 -- 7 files changed, 58 insertions(+), 94 deletions(-) delete mode 100644 packages/bundle/README.md delete mode 100644 packages/bundle/package.json rename packages/{bundle => tool-bailian-kb}/cordis.patch.yml (100%) diff --git a/README.md b/README.md index 50a50cc..50c7167 100644 --- a/README.md +++ b/README.md @@ -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 监听。 diff --git a/packages/bundle/README.md b/packages/bundle/README.md deleted file mode 100644 index c5476c4..0000000 --- a/packages/bundle/README.md +++ /dev/null @@ -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 remove bailian-kb-dsh dsh-tool-bailian-kb -``` diff --git a/packages/bundle/package.json b/packages/bundle/package.json deleted file mode 100644 index 58dc7dc..0000000 --- a/packages/bundle/package.json +++ /dev/null @@ -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:^" } -} diff --git a/packages/tool-bailian-kb/README.md b/packages/tool-bailian-kb/README.md index 7fd5b84..ab33bad 100644 --- a/packages/tool-bailian-kb/README.md +++ b/packages/tool-bailian-kb/README.md @@ -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 diff --git a/packages/bundle/cordis.patch.yml b/packages/tool-bailian-kb/cordis.patch.yml similarity index 100% rename from packages/bundle/cordis.patch.yml rename to packages/tool-bailian-kb/cordis.patch.yml diff --git a/packages/tool-bailian-kb/package.json b/packages/tool-bailian-kb/package.json index 0069895..6193c0e 100644 --- a/packages/tool-bailian-kb/package.json +++ b/packages/tool-bailian-kb/package.json @@ -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", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c5904e7..921bc32 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -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':