mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
docs: package and repository READMEs
This commit is contained in:
zeyu.fz
@@ -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 提示）。
|
||||
@@ -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 <name> remove bailian-kb-bundle
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
# dsh-tool-bailian-kb
|
||||
|
||||
百炼知识库的 dsh 插件本体：在 `ctx.tools` 注册三个模型工具，并在 skills 服务可用时注册管理面 skill。
|
||||
|
||||
## Config
|
||||
|
||||
| 字段 | 类型 | 默认 | 语义 |
|
||||
|---|---|---|---|
|
||||
| `workspaceId` | string | **必填** | 百炼工作空间 id；API host 为 workspace 子域名 `https://<workspaceId>.<endpointHost>` |
|
||||
| `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` 是客户端截断：请求体不含该参数，服务端返回条数由检索服务配置决定，截断只影响进入模型上下文的量。
|
||||
Reference in New Issue
Block a user