前言¶

在使用 DeepSeek Harness（DSH）进行智能体开发时，管理模型与查看会话配额是常见需求。对于接入阿里云百炼（Bailian / DashScope / Model Studio）的开发者，手动在配置中维护模型列表既繁琐又容易遗漏。本文介绍 dsh-bailian-catalog 插件，它将百炼的模型目录集成到 DSH 的设置面板中，并显示当前会话的上下文配额使用情况。

插件定位¶

dsh-bailian-catalog 是一个 DSH 插件，由 kennethfan 维护，分类为「模型推理」。它通过 DSH 的 Web GUI 提供以下能力：

• 在设置页面的「百炼模型」区域列出当前 API 密钥可访问的所有百炼模型；
• 将任意模型添加或移除到 Bailian 提供商路由中；
• 显示当前活跃会话的上下文配额（上下文窗口、已用 token、剩余预算及进度条）。

核心功能¶

1. 设置面板¶

插件在 DSH 设置页新增一个名为「百炼模型」的区域，提供：

• 模型总数、探测的端点地址、刷新时间；
• 搜索功能；
• 按模型家族折叠；
• 一键复制模型 ID。

2. 添加/移除模型¶

列表的每一行都有一个「Add」按钮。点击后，插件将模型写入 llm-pi-ai 的 providers.bailian.models 配置项，随后该模型会出现在模型选择器中。再次点击同一按钮可将其移除。

3. 会话上下文配额¶

插件读取当前活跃会话的信息，展示：

• 上下文窗口大小；
• 已用 token 数；
• 剩余预算；
• 配额使用进度条。

配额状态分为「足够」「接近上限」和「耗尽」三种。这里的配额指上下文预算，而非账户余额：百炼的 sk- 密钥没有公开的余额或配额端点，账户余额需通过阿里云 BSS OpenAPI 获取，因此插件以会话上下文窗口作为配额参考。

4. Agent 工具¶

插件暴露了一个 Agent 工具 bailian_list_models，可在任何会话中调用。该工具支持：

• query：子串过滤；
• family：精确的家族过滤；
• vendor：精确的厂商（命名空间）过滤。

分组逻辑¶

百炼的模型 ID 不总是包含 owner/ 前缀（作者端点中 178 个模型里有 105 个不带该前缀），按前缀分组会导致大量模型归入同一类。插件采用「家族」分组：根据 ID 模式（如 qwen*、glm*、deepseek* 等）映射到中文名称（通义千问、智谱、DeepSeek 等），并将 owner/ 前缀作为次要的命名空间值。在作者的端点上，该分组方式将 175 个模型映射到 12 个家族。

工作原理¶

插件分为宿主端（index.js）和浏览器端（client.js）两部分。

宿主端通过 credentials 服务读取 BAILIAN_API_KEY（优先从凭证存储，再回退到环境变量），该密钥仅驻留于宿主内存，不会发送到浏览器或写入磁盘。它通过官方的 llm.discoverModels() 路径枚举模型，发起 GET {baseURL}/models 请求，并在请求头中携带 Authorization: Bearer。配额数据通过读取最近活跃的会话，调用 tokenMeter.measure() 计算已用 token，再从 session.requestContext() 获取模型与窗口信息；若窗口未知，则回退到 llm.resolveModelInfo()。

添加/移除操作通过 settings.mutate() 执行，采用结构化的配置补丁写入方式，而非直接编辑 YAML 文本。

浏览器端使用手写的 ModuleLoader 打包，无构建步骤，仅依赖 DSH 提供的 react。它注册了一个 ID 为 bailian-catalog 的设置区段（顺序 12），并从同源端点渲染界面。

API 端点¶

插件提供以下端点：

• GET /api/bailian-catalog/list：返回模型列表，并标记哪些 ID 已在路由中；
• GET /api/bailian-catalog/usage：返回当前会话的模型、已用 token 与上下文窗口；
• POST /api/bailian-catalog/add：接收 { id }，幂等操作，若 ID 已存在则返回 already；
• POST /api/bailian-catalog/remove：接收 { id }，从路由中移除该模型。

首次调用 settings.mutate 写入配置时，插件会补全 schema 默认值（如 input: []、compat: { chatTemplateKwargs: {}, chatTemplateArgs: {} }），这些值在语义上是中性的，但会增加少量文件行数。

配置方式¶

插件默认探测 Bailian 的 MaaS 网关（llm-pi-ai 在当前配置中使用的端点），公共端点也可用（测试时两者返回相同结构）。如需覆盖探测端点，可在 cordis.patch.yml 中添加如下行：

- insert:
    - id: bailian-catalog
      name: 'dsh-bailian-catalog'
      config:
        baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1

自定义家族规则¶

通过 families 配置项可添加自定义的家族规则，这些规则在插件内置规则之前匹配。规则格式如下：

- id: bailian-catalog
  name: 'dsh-bailian-catalog'
  config:
    families:
      - pattern: '^gui-plus$'   # 大小写不敏感的正则
        family: GUI
      - pattern: '^sre-gpu'
        family: 运维

规则先对完整模型 ID 进行匹配，再对叶子名称（/ 后的部分）进行匹配，与内置表的行为一致。无效输入（如错误的正则、缺失的 pattern 或 family、非数组格式的 families）会被跳过，并在设置面板中显示警告，内置规则继续生效。

安装与启用¶

从 GitHub 安装：

dsh plugin --profile <profile> add github:kennethfan/dsh-bailian-catalog

从本地检出目录安装：

dsh plugin --profile <profile> add link:/path/to/dsh-bailian-catalog

安装后，宿主端路由需要重启 dsh 进程才能生效，浏览器端在页面刷新后出现。

注意事项¶

• 插件仅列出当前 API 密钥可访问的模型，而非百炼的完整公开目录（作者的端点返回约 178 个模型）；
• 插件仅做查询与配置写入，不执行推理，因此列表反映端点声明的状态；
• 插件仅绑定到 127.0.0.1，仅可通过本地访问；
• 使用前请检查源码与许可证（MIT）。

适用场景¶

适合需要频繁管理百炼模型路由、希望集中查看会话上下文配额的 DSH 用户。开发者可在设置页快速浏览与筛选模型，并通过工具或 UI 将模型加入/移除路由。

结语¶

dsh-bailian-catalog 将百炼模型目录与配额信息集成到 DSH 设置页，为模型推理流程提供了一站式的管理与监控能力。更多细节与源码，可参考项目主页。

参考资料¶

• GitHub 仓库：https://github.com/kennethfan/dsh-bailian-catalog
• 插件目录页：https://www.skillhub.cn/plugins/kennethfan/dsh-bailian-catalog