mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
docs: migrate design spec and implementation plan into this repo
This commit is contained in:
zeyu.fz
@@ -2,7 +2,7 @@
|
||||
|
||||
阿里云百炼知识库能力的 [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`。
|
||||
设计文档：[docs/specs/2026-08-15-bailian-kb-bundle-design.md](docs/specs/2026-08-15-bailian-kb-bundle-design.md) · 实现计划：[docs/plans/2026-08-15-bailian-kb-bundle.md](docs/plans/2026-08-15-bailian-kb-bundle.md)
|
||||
|
||||
## 仓库结构
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,195 @@
|
||||
# 百炼知识库 dsh 插件（out-of-tree bundle）设计
|
||||
|
||||
> 状态：设计已确认并实现（v0.1.0 待真实 API smoke 后打 tag）。
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
为 DeepSeek Harness（dsh）提供阿里云百炼知识库（Knowledge Studio / RAG）垂类能力。经对比 MCP、CLI、API 三种接入通道后确定分层混合架构：
|
||||
|
||||
- **高频检索面走 API 直连原生工具**：结构化 schema、进程内 HTTP、结果可 snapshot、体验可打磨；
|
||||
- **低频管理长尾走 kscli + skill**：`knowledge-studio-cli`（与 `bl knowledge` 同源实现的轻量发行面）覆盖建库/上传/部署等 34 个子命令，渐进式披露，零插件维护成本；
|
||||
- **不做 MCP 通道**：托管 rag MCP 面向不拥有 API/CLI 的第三方宿主，非本方案投入点。
|
||||
|
||||
## 2. 范围
|
||||
|
||||
**做：**
|
||||
|
||||
- 三个模型面工具：`kb_service_list`、`kb_search`、`kb_chat`（API 直连）；
|
||||
- 一个管理面 skill（引导 agent 使用 kscli）；
|
||||
- bundle 分发形态与配置、凭证、错误、测试设计。
|
||||
|
||||
**不做（含理由）：**
|
||||
|
||||
| 项 | 理由 |
|
||||
|---|---|
|
||||
| `retrieve` 工具 | 服务端已弃用（`search` 取代）；新表面不携带 deprecated 能力，避免近义工具混淆 |
|
||||
| MCP 通道 | 见 §1 |
|
||||
| chat 进展流式 UI（模式 4） | 一期用缓冲式 + 期望管理，看真实使用反馈再决定（见 §7 与附录 A） |
|
||||
| `run_in_background` 后台模式 | dsh jobs 机制已备好，出现真实需求再加 |
|
||||
| skills 生态独立分发（B-3） | 一期 skill 随 bundle 注册；跨宿主分发留待后续 |
|
||||
| 运行时 API/CLI fallback | 每个操作固定一条通道；双实现漂移与故障掩盖的代价大于收益 |
|
||||
|
||||
## 3. 总体形态
|
||||
|
||||
独立仓库维护的 **out-of-tree bundle**：`package.json` 声明 `dsh.bundle` 指向 patch 文件，安装进 dsh profile 的 patch 层；不进入 deepseek-harness 主仓库，不改变 modelstudioai/cli 仓库的定位。
|
||||
|
||||
命名：
|
||||
|
||||
- bundle 包：`bailian-kb-bundle`
|
||||
- 插件包：`dsh-tool-bailian-kb`
|
||||
|
||||
仓库为独立 pnpm workspace（目录 `workspace/bailian-kb-bundle`，独立 git 仓库），两包结构：`packages/tool-bailian-kb`（插件本体：Config、client、三个工具、随包打包的 `skills/bailian-kb-management/SKILL.md`）与 `packages/bundle`（分发面：`dsh.bundle` 声明、`cordis.patch.yml`，`dependencies` 含插件包）。拆分依据：patch row 的 bare 插件名必须出现在 bundle 的 `dependencies`，插件包保持纯净（仅 `@deepseek-ai/cordis` peer + dsh 能力包依赖）。
|
||||
|
||||
插件为函数插件形态（`name` / `inject: ['tools']` / `Config` / `apply`），在 `apply(ctx, config)` 中构建共享 API client 并注册三个工具。
|
||||
|
||||
### 3.1 接入与配置流程
|
||||
|
||||
**bundle 侧接入契约**（`@deepseek-ai/dsh-base` 为模板）：
|
||||
|
||||
- `package.json` 声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`，并在 `exports` 暴露 `./cordis.patch.yml`；
|
||||
- `cordis.patch.yml` 用 `insert` 插入插件 row 与 skill 注册 row；row 中的 bare 插件名必须出现在 bundle 自身的 `dependencies`；
|
||||
- 发布到 npm，或直接以 git spec 分发（`github:<org>/<repo>`）。
|
||||
|
||||
**用户安装**：
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web add bailian-kb-bundle
|
||||
```
|
||||
|
||||
CLI 转发 pnpm 将 bundle 装为 profile dependency；安装后自动 reconcile——检测到 `dsh.bundle` 声明即加入 `dsh.profile.bundles` 层栈，无需手改 YAML。boot 层序为 `dsh-base` → … → 本 bundle patch → profile `cordis.patch.yml` → 家目录 `cordis.patch.yml`，用户 patch 层在本 bundle 之上，插入的任何 row 均可被按 id 覆盖或禁用。卸载 `dsh plugin --profile web remove bailian-kb-bundle` 自动收回层栈。
|
||||
|
||||
**配置落点**：用户 patch 是整 config 替换（无 deep-merge），因此 bundle row 的 config 默认从环境读取：
|
||||
|
||||
```yaml
|
||||
config:
|
||||
workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID
|
||||
```
|
||||
|
||||
用户将 `BAILIAN_WORKSPACE_ID` 写入 `~/.dsh/.env` 即可运行（`DASHSCOPE_API_KEY` 放同处或 `.credentials.yaml`）；需要精细控制的部署再以 id-targeted patch 覆盖整个 config。`workspaceId` 缺失时按 §6 在加载期 fail loud，错误信息指向 `.env` 配置方式。验证入口：`dsh --profile web --dump-config` 可见本 bundle 的 row。
|
||||
|
||||
**本地开发迭代**：checkout 内 `dsh plugin --profile dev add .`（相对路径锚定调用目录）；patch 文件受 HMR 监听，编辑后自动 recompose。
|
||||
|
||||
## 4. 模型面工具
|
||||
|
||||
### 4.1 `kb_service_list`
|
||||
|
||||
发现当前 workspace 的检索/问答服务（百炼"检索服务"，即 `agent_id` 的来源）。
|
||||
|
||||
| 参数 | 类型 | 必填 | 语义 |
|
||||
|---|---|---|---|
|
||||
| `scene` | enum `chat` \| `search` | 否 | 省略时插件内部对两个 scene 各查一次并合并；每个条目携带 scene 标记（指明该服务配 `kb_chat` 还是 `kb_search` 使用） |
|
||||
| `name_filter` | string | 否 | 服务名模糊匹配，透传服务端 `agent_name` |
|
||||
|
||||
返回：服务条目数组（`agent_id`、名称、描述、scene、status、绑定的知识库）+ `total`。
|
||||
|
||||
**分页内部消化**：固定 `page_size=100, page_number=1`（服务端上限 100）。`total > 100` 时结果末尾附提示 `listed first 100 of N services; narrow with name_filter`。不向模型暴露翻页参数——模型的导航原语是名字过滤，不是页码。
|
||||
|
||||
**status 不作为参数**：条目携带 `status` 字段，description 提示优先使用 `deployed`；draft 服务仅在 `agentVersion: beta` 的调试部署下可调（部署期概念，不占模型参数面）。
|
||||
|
||||
### 4.2 `kb_search`
|
||||
|
||||
语义检索，返回原始知识片段供 agent 综合与引用。
|
||||
|
||||
| 参数 | 类型 | 必填 | 语义 |
|
||||
|---|---|---|---|
|
||||
| `query` | string | 是 | 检索文本 |
|
||||
| `agent_id` | string | 见 §5 | 检索服务 id（scene=search 的服务）；检索范围与策略（多库加权、路由、重排）由服务端配置决定 |
|
||||
| `top_k` | integer | 否，默认 5 | 返回片段数上限。服务端 search API 无此参数（条数由检索服务配置决定），插件对按 score 降序的 `nodes` 做客户端截断；description 写明该语义 |
|
||||
| `images` | string[] | 否 | 多模态检索的图片 URL |
|
||||
|
||||
返回：chunks 数组（内容 + 来源引用）。
|
||||
|
||||
### 4.3 `kb_chat`
|
||||
|
||||
知识库成品问答。服务端为 agentic loop（分析 → 多轮检索 → 生成），耗时可达分钟级。
|
||||
|
||||
| 参数 | 类型 | 必填 | 语义 |
|
||||
|---|---|---|---|
|
||||
| `message` | string | 是 | 问题 |
|
||||
| `agent_id` | string | 见 §5 | 问答服务 id（scene=chat） |
|
||||
|
||||
返回：完整答案文本（含 API 提供的引用信息时一并返回）。
|
||||
|
||||
### 4.4 description 路由策略
|
||||
|
||||
`kb_search` 与 `kb_chat` 的 description **互相指名分界**，把"该用谁"写成可判断条件而非形容词：
|
||||
|
||||
- `kb_search`：returns raw knowledge chunks with source references；用于需要核实、引用、或与其他上下文结合推理的场景；
|
||||
- `kb_chat`：a complete, domain-tuned answer produced by a specialized RAG pipeline (retrieval + reranking + grounded generation)；知识问答场景通常优于自行检索综合（typically outperforms searching and synthesizing yourself when the question can be answered by the knowledge base alone）；并注明 may take a few minutes。
|
||||
|
||||
## 5. `agent_id` 的三种场景覆盖
|
||||
|
||||
| 场景 | 机制 | 插件成本 |
|
||||
|---|---|---|
|
||||
| 发现式 | `kb_service_list` → 选服务 → search/chat；`agent_id` 缺失或无效时，错误信息直接附当前服务清单，模型一步纠正 | 发现工具 + 错误增强 |
|
||||
| 用户习惯固定 | 宿主 memory / 项目指令记住常用 `agent_id` | 零（skill 写入最佳实践） |
|
||||
| 场景/部署固定 | Config 可选 `defaultAgentId`；配置后注册时将 `agent_id` 参数降为可选，description 注明缺省服务 | 一个可选配置字段 |
|
||||
|
||||
**Schema 形态在加载期由配置静态决定**（未配 `defaultAgentId` 则 `agent_id` 必填），不是运行时 fallback；每个部署只有一条清晰规则，KV cache 前缀与 snapshot 均稳定。与 dsh preset 组合可实现按场景绑定（如客服 preset 固定客服库）。
|
||||
|
||||
## 6. 配置与凭证
|
||||
|
||||
```ts
|
||||
interface Config {
|
||||
/** 百炼工作空间 id。知识库 API 的 host 为 workspace 子域名：`https://<workspaceId>.<endpointHost>`。必填。 */
|
||||
workspaceId: string
|
||||
/** 知识库 API 的 host 后缀。默认 `cn-beijing.maas.aliyuncs.com`；其他 region/私有化部署时替换。 */
|
||||
endpointHost: string
|
||||
/** 场景固定式部署绑定的检索服务 id。可选。 */
|
||||
defaultAgentId?: string
|
||||
/** 调用的服务版本：beta（草稿调试）或已发布版本号。可选，缺省最新发布版。不暴露给模型。 */
|
||||
agentVersion?: string
|
||||
/** kb_chat 超时毫秒数。chat 为分钟级 loop，部署必须可调。默认 300000（5 分钟）。 */
|
||||
chatTimeoutMs: number
|
||||
}
|
||||
```
|
||||
|
||||
- schemastery 校验；缺失/非法配置在**加载期 fail loud**；
|
||||
- API Key 走 `ctx.credentials` 引用（`DASHSCOPE_API_KEY`，env/.env provider），不进 Config、不进会话日志、不被 `--dump-config` 打印；
|
||||
- URL 拼接是 `(endpointHost, workspaceId, path) → endpoint` 的纯函数（`https://${workspaceId}.${endpointHost}${path}`，与 kscli 的 `ragEndpoint` 同构），与请求构造、错误翻译一起收在插件内部的共享 client 中（协议路径为代码常量，不进配置）。
|
||||
|
||||
## 7. 执行语义
|
||||
|
||||
- **`kb_chat` 缓冲式**（与 bash 前台/subagent 同构的仓库惯例：dsh 中没有工具向模型或 UI 中途推流）：`execute` 内部消费完 SSE，一次性返回完整答案。UI 呈现为 `presentCall` pending 卡片 → `presentResult` 完成卡片（`generic` 卡，纯函数、replay-safe）；
|
||||
- **期望管理**：description 与 pending 卡片标题注明 may take a few minutes；
|
||||
- **超时**：`chatTimeoutMs` 显式可配（dsh tool-timeout guard 可另行部署级配置）；
|
||||
- **超长输出**：声明依赖 dsh spill 子系统兜底，插件不自造截断。
|
||||
|
||||
## 8. 管理面 skill
|
||||
|
||||
- SKILL.md 随插件包打包；插件在 skills 服务可用时通过 `ctx.inject(['skills'], …)` 以 `ctx.skills.register()` 运行时注册（`source: 'bundled'`，`resourceBase` 指向包内 skill 目录），无 skills 服务的组合不受影响；工具与 skill 同版本发布，互相引用不漂移；
|
||||
- 内容：kscli 安装引导（`npm install -g knowledge-studio-cli`）、API Key 与 workspace 解析（flag > `BAILIAN_WORKSPACE_ID` > 配置文件）、典型工作流（建库 → 上传 → 等解析 → 部署服务 → 检索验证）、"常用 `agent_id` 写入项目指令/记忆"最佳实践、检索面与管理面的分工说明（search/chat 用原生工具，不走 kscli）；
|
||||
- kscli 未安装时管理操作 fail loud 并给出安装命令；检索面不受影响。
|
||||
|
||||
## 9. 错误处理
|
||||
|
||||
- HTTP 错误翻译为模型可操作的文本：无效 `agent_id` → 附当前服务清单；鉴权失败 → 指向 API Key 获取与配置方式；超时 → 说明 chat 可能耗时并建议重试或改用 search；
|
||||
- 凭证缺失在首次可解析点大声失败，不静默降级；
|
||||
- 服务端非 2xx 的响应体原样摘要进错误信息（截断至安全长度），便于模型与用户诊断。
|
||||
|
||||
## 10. 测试策略
|
||||
|
||||
| 层 | 内容 |
|
||||
|---|---|
|
||||
| 单元测试 | endpoint 拼接、请求体构造（scene 合并、分页内化、`defaultAgentId` 解析）、错误翻译 |
|
||||
| snapshot | mock HTTP fixture 的可重放 keyless snapshot，macOS/Linux 均可回放；覆盖三工具的调用与渲染卡片 |
|
||||
| e2e | 真实 DashScope API，无 `DASHSCOPE_API_KEY` 时自跳过 |
|
||||
|
||||
## 附录 A：预留扩展（已设计方向，未排期）
|
||||
|
||||
- **chat 进展流式（模式 4）**：`execute` 消费 SSE 时 append 工具自有会话事件（如 `bailian/chat-progress`，`ignorable: true`），Web 客户端注册 `ConversationNodeDefinition` 渲染器实时显示；模型面不变（logged ≠ model-visible）。触发条件：真实用户对 chat 等待体验的负反馈；
|
||||
- **后台模式**：`kb_chat` 增加 `run_in_background`，挂 `ctx.jobs`，`job_output` 收取；
|
||||
- **skills 生态分发（B-3）**：以 bundle 仓库的 SKILL.md 为唯一源，发布到 `npx skills add` 生态覆盖其他宿主；
|
||||
- **能力缝升级**：出现第二种传输（如私有化内网网关）时，将共享 client 提为 `ctx.<key>` 服务，按 Service Definition / Provider / Consumer 三角色拆分。
|
||||
|
||||
## 附录 B：关键决策记录
|
||||
|
||||
| 决策 | 结论 | 理由摘要 |
|
||||
|---|---|---|
|
||||
| 接入通道 | API（检索面）+ CLI（管理面），不做 MCP | 频率×能力深度×控制权分层；API/CLI 均为己方资产 |
|
||||
| CLI 选型 | kscli 而非 bl | 同源实现零能力损失；命令面窄、鉴权单一、onboarding 短 |
|
||||
| `retrieve` | 不做 | 已弃用，避免近义工具 |
|
||||
| `kb_chat` 门控 | 不门控，常驻注册 | 服务端 RAG 管线在知识问答场景更专业，description 写明场景让模型路由 |
|
||||
| `agent_id` 归属 | 模型参数 + 发现工具 + 可选 `defaultAgentId` | 检索服务是用户运行时资产，插件与部署配置不应假设 |
|
||||
| chat 流式 | 一期缓冲式 | 仓库惯例（bash/subagent 同构）；进展流式留待反馈 |
|
||||
| 分页 | 内部消化（page_size=100 + 溢出提示） | 模型导航原语是 name 过滤，非页码 |
|
||||
Reference in New Issue
Block a user