modelstudioai__cli/packages/dsh/README.md

bailian-cli-dsh

把阿里云百炼（Model Studio）的能力接入 DeepSeek Harness（dsh）的 profile bundle。

本包提供两项能力：

能力	说明
Bailian 设置页	通用的百炼凭证配置（AK/SK 存入 dsh bl profile + DashScope API Key）+ TokenPlan 用量展示 + 记忆库配置 + 新会话欢迎页
跨会话长期记忆	自动检索注入 + 自动落库，模型可主动 search/add/list。按量计费，默认停用

---

1. 前置条件

• Node ≥ 22.19（dsh 的要求）

• bl（用量展示通过子进程调用 bl console call）

  npm install -g bailian-cli
  

• 阿里云 AK/SK（AccessKey ID + AccessKey Secret）—— 用于控制台鉴权，查询用量信息。在 webui 设置页填入即可，无需环境变量。

• DashScope API Key（sk- 前缀，按量付费）—— 用于记忆库等 DashScope API 调用。在设置页「凭证配置」填入，与 AK/SK 并列为通用凭证。

  获取方式：阿里云控制台 → AccessKey 管理

---

2. 安装到 web profile

npx @deepseek-ai/dsh web 是 dsh --profile web 的别名，配置目录是 ~/.dsh/profiles/web/。

pnpm -F bailian-cli-dsh build   # vp pack（host）+ esbuild（client.bundle.js）
cd packages/dsh && pnpm pack

npx @deepseek-ai/dsh plugin --profile web add /absolute/path/to/bailian-cli-dsh-<version>.tgz

确认 bailian 行都在：

npx @deepseek-ai/dsh --profile web --dump-config | grep -E 'bailian'

启动：

npx @deepseek-ai/dsh web

Web UI 在 http://127.0.0.1:3080。

---

3. Bailian 设置页 + 欢迎页

安装并重启后：

• Settings → Bailian：通用设置页（凭证配置 / TokenPlan 用量 / 记忆库）。
• 新会话欢迎页：每个新会话（blank）在输入框上方显示「百炼 Agent」欢迎页（Tab + 功能卡片），发出第一条消息后自动隐藏。

凭证配置（通用）

1. 在「凭证配置」区填入 AccessKey ID 和 AccessKey Secret
2. 点击 「保存凭证」

Host 会执行 bl auth login --open-api --config dsh，将 AK/SK 和新生成的 access_token 存入 bl 的 dsh 专属 profile。所有后续百炼插件共用此凭证，无需重复配置。

TokenPlan 用量

1. 选择区域和站点
2. 点击 「查询用量」

Host 执行 bl console call --config dsh 调用 3 个个人版控制台接口，返回：

• 用量百分比 —— 5 小时窗口 / 1 周窗口的用量百分比和重置时间
• 套餐信息 —— 套餐类型（基础版/标准版/高级版）、状态、剩余天数、到期时间、自动续费
• 额外用量包 —— Credits 总量、剩余量、生效中数量

凭证解析优先级

凭证保存到 bl 的 dsh profile 后，所有百炼插件通过 --config dsh 读取。行内 config 的 accessKeyId/accessKeySecret 作为兜底（未通过 UI 保存时自动使用）。

行内配置（可选）

如果不想在 UI 里每次输入，可以在 profile 的 cordis.patch.yml 里固化凭证：

- id: bailian-tokenplan-usage
  config:
    # accessKeyId / accessKeySecret: 兜底凭证（未通过 UI 保存时使用）
    # consoleRegion: cn-beijing
    # consoleSite: domestic
    # profile: dsh  # 默认用 dsh 专属 profile

配置后 UI 表单会留空，但点击「查询用量」会使用行内凭证。

---

4. 跨会话长期记忆

默认停用（按量计费）。在 cordis.patch.yml 中设 disabled: false 启用，然后在设置页配置 API Key 和参数。

功能

• 自动检索注入：新会话首轮，用用户消息搜索记忆，将结果注入上下文（autoInject，默认开启）
• 自动落库：每轮结束，将该轮新消息发送到记忆库 add API（autoPersist，默认开启）
• 模型工具：bailian_memory_search（检索）、bailian_memory_add（存储）、bailian_memory_list（浏览）

触发机制

时机	触发方式
新会话首轮	自动检索记忆注入上下文（agent/pre-step 事件）
对话中	模型主动调用 bailian_memory_search/bailian_memory_add
轮次结束	自动落库新消息（agent/turn-stopping 事件）

凭证与配置

• API Key：DashScope 按量付费 Key（sk-），在设置页「凭证配置」填入
• Base URL：默认 https://dashscope.aliyuncs.com/api/v2/apps/memory/
• User ID：记忆归属 ID，默认读系统用户名
• Plan Version：lite（便宜，关闭 rerank）或 pro（开启 rerank，约 50 倍成本）。注意：实际计费由 enable_rerank 控制
• Top K：检索返回数量（1-100，默认 10）
• Memory Library ID：记忆库 ID，留空用默认

计费

• Add：120 QPM
• Search：300 QPM（Lite ¥0.00002/次，Pro ¥0.001/次）
• 总计不超过 3000 QPM

启用

- id: bailian-memory
  disabled: false
  config:
    baseUrl: "https://dashscope.aliyuncs.com/api/v2/apps/memory/"
    planVersion: "lite"
    topK: 10
    autoInject: true
    autoPersist: true

启用后在设置页「记忆库」section 配置 API Key 和参数。

记忆库调用 DashScope memory v2 API（非 bl memory），因为 v2 API 暴露了 min_score、enable_rerank、plan_version、memory_library_id 等参数 bl memory 不支持。

5. 验证

# 配置合成
npx @deepseek-ai/dsh --profile web --dump-config | grep bailian

# bl 就绪
bl auth status

启动后验证：

• 欢迎页：新开一个会话，输入框上方出现「百炼 Agent」欢迎页
• 凭证配置：打开 Settings → Bailian → 填入 AK/SK → 保存凭证
• 用量展示：同页面选择区域 → 查询用量
• 记忆库：启用 bailian-memory 后，同页面配置 API Key

---

6. 常见问题

现象	原因
用量查询报 bl auth login failed	AK/SK 无效或无权限；确认 AK 有百炼控制台访问权限
用量查询报 NotLogined 或 token 过期	bl 的 access token 已过期；Host 会自动通过 AK/SK 刷新，确认 AK/SK 正确
用量查询报 bl console call failed	控制台接口调用失败；检查 region/site 是否匹配你的账号
用量查询报 Workspace.NotAuthorised	bl 用了其他 profile 的旧 access_token；Host 默认用 --config dsh 专属 profile 隔离，首次 login 会生成新 token
工具报找不到 bl	bl 不在 PATH：npm install -g bailian-cli
设置页/欢迎页看不到 Bailian	需重启 dsh web（bundle 在启动时加载）；确认 dump-config 有 bailian-client 行，且 client.bundle.js 为 ModuleLoader 格式
启动报 invalid plugin ... apply	包根 dist/index.mjs 必须导出 apply（no-op 插件）；重新 pnpm build 再装

---

7. 卸载

npx @deepseek-ai/dsh plugin --profile web remove bailian-cli-dsh

---

架构说明

Host 半

• src/tokenplan-usage/index.ts —— 凭证 + TokenPlan 用量。inject: ['subprocess']，所有 bl 命令带 --config dsh 隔离凭证。两个 webServer 路由：
  • POST /bailian/credentials — 保存 AK/SK（bl auth login --open-api --config dsh，生成新 token）
  • POST /bailian/tokenplan/usage — 查询用量（bl console call --config dsh，3 个个人版接口）
• src/memory/index.ts —— 记忆库（默认停用）。直接调 DashScope memory v2 API，注册 tools + auto-inject/persist。路由 /bailian/memory/config、/bailian/memory/status。
• src/index.ts —— 包根 no-op 插件，供 bailian-client 行加载（该行只为了让 client-modules 服务浏览器 bundle）。

路由用 /bailian/* 而非 /api/*：/api 前缀被 dsh 的 RPC 网关（apiProxy）占用，自定义路由会被遮蔽。

调用链路：AK/SK → bl auth login --open-api --config dsh（存入 dsh profile）→ bl console call --config dsh（读 dsh profile token → 控制台网关）→ 个人版 TokenPlan 接口

Client 半（src/client.ts）

• 唯一的浏览器源码，构建为 DSH ModuleLoader 格式（见下）。
• 注册 settings.section（id: bailian，label: Bailian），渲染通用百炼设置页（凭证配置 / TokenPlan 用量 / 记忆库）。
• 注册 conversation.input.dock（id: bailian-welcome）：当 session.blank === true（新会话）渲染「百炼 Agent」欢迎页（Tab + 功能卡片），开始对话后自动隐藏。
• 通过 fetch('/bailian/*') 调 Host 路由。

Client 构建（ModuleLoader 格式）

DSH 浏览器只加载 window.__ModuleLoader__.load({ id, factory }) 格式的 bundle（require('react') 由浏览器 ModuleLoader 提供）。vite-plus 产出裸 ES module，格式不对，所以 client 单独用 esbuild 构建：

• scripts/build-client.mjs —— 把 src/client.ts 构建为 CJS + browser + react external，包上 ModuleLoader banner/footer，输出 client.bundle.js。
• package.json 的 build = vp pack && node scripts/build-client.mjs。
• package.json 的 exports["./client"] 与 dsh.client: { platform: "web" } 指向 client.bundle.js，被 client-modules 扫描并服务。
• cordis.patch.yml 的 bailian-client 行 name 必须是包根（bailian-cli-dsh，无子路径），client-modules 才能 require.resolve("<name>/package.json") 识别 dsh.client。

改 client UI 只需编辑 src/client.ts，pnpm build 自动重新生成 client.bundle.js。

共享模块（src/shared/）

• bl.ts —— bl 子进程调用封装（env 转发、stdout/stderr 收集、JSON 解析）
• credentials.ts —— TokenPlan / 按量付费 Key 分类工具
• http.ts —— DashScope HTTP 客户端

这些模块来自早期版本（vision / image / managed-agent / RAG / memory 工具），已移除工具实现但保留共享逻辑作为参考。