From acccca9e2f3fe89cfce7262b806babcac7a9b9f9 Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Sat, 15 Aug 2026 18:47:43 +0800 Subject: [PATCH] docs: package and repository READMEs --- README.md | 50 ++++++++++++++++++++++++++++++ packages/bundle/README.md | 36 +++++++++++++++++++++ packages/tool-bailian-kb/README.md | 39 +++++++++++++++++++++++ 3 files changed, 125 insertions(+) create mode 100644 README.md create mode 100644 packages/bundle/README.md create mode 100644 packages/tool-bailian-kb/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8aa61bd --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# bailian-kb-bundle + +阿里云百炼知识库能力的 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件 bundle：三个 API 直连模型工具（`kb_service_list` / `kb_search` / `kb_chat`）+ kscli 管理面 skill。 + +设计文档：deepseek-harness 工作区 `docs/superpowers/specs/2026-08-15-bailian-kb-bundle-design.md`。 + +## 仓库结构 + +| 包 | 职责 | +|---|---| +| [`packages/tool-bailian-kb`](packages/tool-bailian-kb/README.md) | 插件本体：Config、KbClient、三个工具、随包打包的管理 skill | +| [`packages/bundle`](packages/bundle/README.md) | 分发面：`dsh.bundle` 声明 + `cordis.patch.yml` | + +## 安装（dsh 用户） + +```sh +dsh plugin --profile web add bailian-kb-bundle # npm 发布后；本地开发用绝对/相对路径 +``` + +安装后 CLI 自动把 bundle 加入 profile 的层栈，无需手改 YAML。 + +配置写入 `~/.dsh/.env`： + +```sh +BAILIAN_WORKSPACE_ID=ws-xxx # 必填：百炼工作空间 id +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-bundle`。 + +## 开发 + +依赖 dsh 的运行时包（`@deepseek-ai/dsh-tools` 等）以 peerDependencies 声明、由 dsh 安装闭包在运行时提供；开发期通过 `link:` 指向同级的 `../deepseek-harness` checkout（npm registry 尚未发布完整 dsh 闭包）。 + +```sh +pnpm install +pnpm run test # vitest 单元测试 +pnpm run typecheck +pnpm run build # tsc 产出 lib/ +``` + +本地联调：`dsh plugin --profile dev add <本仓库>/packages/bundle`，patch 文件受 HMR 监听。 + +## Known Limitations + +- **无 keyless snapshot / e2e 基建**：首版以单元测试 + 手动集成验收覆盖；snapshot/e2e 依赖 dsh snapshot harness 对 out-of-tree bundle 的支持情况，v0.2 跟进。 +- **kb_chat 执行期无进展显示**：服务端是分钟级 agentic loop，UI 只有 pending → 完成两态；进展会话事件 + Web 渲染器的设计见 spec 附录 A，等真实使用反馈再排期。 +- **服务清单单 scene 上限 100 条**：超出部分靠 `name_filter` 收窄（结果带 truncated 提示）。 diff --git a/packages/bundle/README.md b/packages/bundle/README.md new file mode 100644 index 0000000..66ffd0a --- /dev/null +++ b/packages/bundle/README.md @@ -0,0 +1,36 @@ +# bailian-kb-bundle（分发包） + +dsh bundle 分发面：`package.json` 的 `dsh.bundle.patch` 声明 + [`cordis.patch.yml`](cordis.patch.yml)，向 profile 插入 `tool-bailian-kb` row。 + +## Patch row + +```yaml +- insert: + - id: tool-bailian-kb + name: dsh-tool-bailian-kb + config: + workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID +``` + +`workspaceId` 默认从环境变量读取（`~/.dsh/.env` 写 `BAILIAN_WORKSPACE_ID=ws-xxx` 即可运行）；未设置时插件加载期 fail loud。 + +## 用户覆盖 + +用户 patch 层在本 bundle 之上，按 id 覆盖时**替换整个 config（无 deep-merge），必须连 workspaceId 一起重述**： + +```yaml +# ~/.dsh/cordis.patch.yml 或 profile 的 cordis.patch.yml +- id: tool-bailian-kb + config: + workspaceId: ws-xxx + defaultAgentId: aid-customer-service # 场景固定式部署 + chatTimeoutMs: 600000 +``` + +禁用：`- id: tool-bailian-kb` + `disabled: true`。 + +## 卸载 + +```sh +dsh plugin --profile remove bailian-kb-bundle +``` diff --git a/packages/tool-bailian-kb/README.md b/packages/tool-bailian-kb/README.md new file mode 100644 index 0000000..700ca19 --- /dev/null +++ b/packages/tool-bailian-kb/README.md @@ -0,0 +1,39 @@ +# dsh-tool-bailian-kb + +百炼知识库的 dsh 插件本体：在 `ctx.tools` 注册三个模型工具，并在 skills 服务可用时注册管理面 skill。 + +## Config + +| 字段 | 类型 | 默认 | 语义 | +|---|---|---|---| +| `workspaceId` | string | **必填** | 百炼工作空间 id；API host 为 workspace 子域名 `https://.` | +| `endpointHost` | string | `cn-beijing.maas.aliyuncs.com` | host 后缀，其他 region/私有化时替换 | +| `defaultAgentId` | string? | — | 场景固定式部署绑定的检索服务；**配置后 `agent_id` 参数在注册期变为可选**（加载期静态决定 schema，非运行时 fallback） | +| `agentVersion` | string? | — | `beta`（草稿调试）或已发布版本号；不暴露给模型 | +| `chatTimeoutMs` | number | 300000 | kb_chat 超时；服务端是分钟级 agentic loop | + +凭证：`DASHSCOPE_API_KEY` 走 `ctx.credentials` 引用，每次调用重新解析（热更换生效），未配置时报错并附获取指引。 + +## 工具 + +| 工具 | 参数 | 返回 | +|---|---|---| +| `kb_service_list` | `scene?`（chat\|search，省略查双场景合并）、`name_filter?` | 服务清单（agent_id、名称、scene、status、绑定知识库）+ total + truncated；分页内部消化（单 scene 100 条上限） | +| `kb_search` | `query`、`agent_id`（见 defaultAgentId）、`top_k?`（默认 5，**客户端截断**——服务端无此参数）、`images?` | chunks（text/score/来源）+ total | +| `kb_chat` | `message`、`agent_id` | 完整答案（内部消费 SSE 流缓冲返回）+ request_id | + +## 错误语义 + +- 4xx（除 401/403）：错误信息**附当前服务清单**，模型可一步纠正无效 `agent_id`； +- 凭证缺失：指向 `~/.dsh/.env` / `.credentials.yaml` 配置方式与控制台取 key 页面； +- chat 超时：说明服务端多轮检索特性，建议重试或改用 `kb_search`； +- 服务端错误体截断至 500 字符进入错误信息（优先 `code: message`）。 + +## 管理面 skill + +`skills/bailian-kb-management/SKILL.md` 随包分发，插件通过 `ctx.inject(['skills'])` 在 skills 服务可用时以 `source: 'bundled'` 运行时注册；无 skills 服务的组合（headless 最小装配）不受影响。内容：kscli 安装/鉴权/workspace 解析、建库→上传→部署工作流、agent_id 固定最佳实践。 + +## Known Limitations + +- kb_chat 执行期无进展显示（缓冲式；进展会话事件设计见仓库根 README 与 spec 附录 A）。 +- `top_k` 是客户端截断：请求体不含该参数，服务端返回条数由检索服务配置决定，截断只影响进入模型上下文的量。