阿里云百炼模型源 doitian/dsh-provider-aliyun

@doitian/dsh-provider-aliyun

把阿里云 DashScope（百炼） 接入 DeepSeek Harness，作为模型服务商。

插件注册一条服务商路由 aliyun，并且完全拥有它——端点、凭据引用、协议、模型目录，全都归它管。目录是活的：路由会去问配置好的端点提供哪些模型（GET {baseURL}/models），所以阿里云明天发布的模型，不用发新版本就能选到。包里还带一份兜底列表，覆盖第一次拉取列表之前的空窗期，同时补上列表里不公开的容量信息。

provider: aliyun
model: qwen3.8-max

为什么要做成插件，而不是写一段配置

兼容 OpenAI 的服务商确实可以只靠配置加进 DSH——在 llm-pi-ai 的 providers 下声明一条路由，再手写模型列表。这样能跑，但模型列表从此就永远躺在你的配置档里：Qwen 每发一个新版本都得手动改一次；而且配置档补丁会整体替换某个条目的 config，以后谁也没法往里面合并模型。

这个包走的是另一条路。它在 LLM 接缝上注册自己的路由，把目录当数据发出去：

| | 纯配置路由 | 本插件 |
| 模型列表从哪来 | 你的 cordis.patch.yml | 端点，随时间推移重新读取 |
| 阿里云新上线的模型怎么加 | 改配置档 | 什么都不用做——下次拉列表就有了 |
| 没人列过的模型，容量信息从哪来 | 你自己写 | 兜底 id 自带，其余用保守默认值 |
| 配置档补丁能盖掉它吗 | — | 不能 |
| 你的配置档要写什么 | 整个服务商配置块 | 什么都不用写，或者只写 baseURL |

代价也说清楚：插件依赖适配器的内部结构和它使用的发现约定（见工作原理），纯配置路由没有这个负担。

环境要求

- DeepSeek Harness 0.2.0-rc.2，并带上 @deepseek-ai/dsh-base bundle——本插件注册的 LLM 接缝由它挂载。
- 阿里云 DashScope / 百炼的 API key。
- 端点要能响应 GET {baseURL}/models。 工作区主机和公网的兼容模式端点都行；不响应的部署也能用——路由只会公布兜底目录，你也可以在配置里用 models 手动列模型。
- 不要通过 llm-pi-ai 配置 aliyun 路由。 两个适配器不能声明同一条路由：配置档里还配着这条路由时挂载本插件，会报 configurable provider "aliyun" is already declared。先从配置档补丁里删掉那个配置块——这正是本插件存在的意义。

安装

桌面应用。 侧边栏 Plugins → 安装 @doitian/dsh-provider-aliyun。新装的 bundle 默认启用。

其他配置档。 dsh plugin 会把参数转发给配置档目录里的 pnpm：

dsh plugin --profile <name> add @doitian/dsh-provider-aliyun
然后确认 bundle 已经被选中——直接 add 只会装上依赖，不会把它加进配置档 package.json 里的 dsh.profile.bundles：

{
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@doitian/dsh-provider-aliyun"]
}
}
}

dsh plugin 命令行会拒绝 desktop 配置档（profile "desktop" is managed exclusively by the Electron application）；这种配置档请改用 Plugins 页面。

配置 API key

路由要存在，什么都不用做；这个包里、任何配置档补丁里都不存 key。路由每次请求时解析一个凭据引用：

apiKeyEnv: ALIYUN_API_KEY # the default

把它存到 $DSH_HOME/.credentials.yaml 的 refs: 下面：

refs:
ALIYUN_API_KEY: sk-…

凭据存储会监视这个文件，一有改动就重新加载，所以 DSH 运行期间新增的 key 会在下一次请求时生效——下一次拉取模型列表时也生效，而正是这一步把兜底目录换成端点自己的目录。或者在启动 DSH 的环境里导出 ALIYUN_API_KEY；这一层优先于文件，并会显示为只读。在 key 解析出来之前，选中 Aliyun 模型会立刻失败并报 MISSING_CREDENTIAL，不会发起任何网络 I/O。

Models 页面没有这一行的输入框。 配置界面只为 llm-deepseek 和 llm-pi-ai 两个命名空间渲染按服务商划分的编辑器；这个插件自己的命名空间只显示这一行、缺凭据的小圆点，以及一句提示，说其他字段在 cordis.patch.yml 里。这提示没错——key 就写在上面的文件里，而那个存储也正是这个页面在编辑它管得到的路由时写入的地方。

端点

| 区域 | 端点 |
| 中国大陆，公共（默认） | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 国际 | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
| 百炼 workspace | https://llm-<workspace-id>.<region>.maas.aliyuncs.com/compatible-mode/v1 |

workspace 端点是控制台按 workspace 分配的主机名；key 往往就是针对某个 workspace 签发的，而 workspace id 是你自己的，所以它只能来自配置：

- id: llm-aliyun
name: '@doitian/dsh-provider-aliyun'
config:
baseURL: https://llm-<workspace-id>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

端点和 key 要来自同一个产品：workspace key 不能和公共 compatible-mode 端点混用，而 Token Plan 的 key 属于 token-plan.<region>.maas.aliyuncs.com。

模型

路由对外公布端点提供什么。挂载时——以及每次模型列表过期或存入凭据时——插件会调用 GET {baseURL}/models，按端点自己的顺序采用找到的 id。在过滤器允许的范围内，成员资格跟着这份列表走，删除也算：Aliyun 下线的模型不用发新版本就选不到了，新上线的模型也同样自动出现。
列表不会做三件事，以及实际会发生什么：

| | 行为 |
| 容量 | 列表只披露 id，不披露上下文窗口。回退目录中列出的 id 保留其书面事实；其他所有 id 都获得保守的默认值（discovery.contextWindow、discovery.maxTokens、discovery.input），因为 harness 在压缩历史时信任 contextWindow，而一个通用数字胜过编造出来的精确数字。 |
| 失败 | 读取失败不会改变任何东西：最后一次成功的列表继续生效，在第一次成功之前则由回退目录生效。没有列出任何内容的列表算作失败 —— {"data":[]} 说明不了端点提供什么服务。 |
| 延迟 | 只有读取模型列表会等待端点，而且只等待 discovery.waitMs。其他所有读取只是安排一次刷新，所以在缓慢获取期间打开的选择器显示的是已知内容。 |

随附的回退列表有三个模型：qwen3.8-max、deepseek-v4.1-flash、glm-5.3。它同时也是元数据表，这就是全部诀窍 —— 这里任何值得命名的东西都会用上你的数字。

列表是目录，不是聊天菜单。 工作区端点会返回账户能访问的一切 —— 在这个插件开发所针对的工作区上，有 262 个条目，涵盖语音合成、语音识别、图像生成、嵌入、重排序器、实时双工模型，以及一直到 qwen-7b-chat 的每一代旧模型。列表披露 id、object、created 和 owned_by，所以一个 id 是什么根本无法从列表中读出。决定它的是另外两样东西，默认值两者都用：配置中的名称模式，以及随附的元数据快照，后者直接说明一个模型是否读写文本。在那个端点上，三种模式的结果是：

| discovery.filter | 公布数量 | 什么让一个 id 通过 |
| chat（默认） | 262 个中的 79 个 | include 模式，或者快照知道它是聊天模型 |
| patterns | 262 个中的 44 个 | 仅 include 模式 —— 更严格的选择器 |
| all | 262 个中的 175 个 | 列表列出的所有内容，减去 exclude |

模型事实

列表不携带容量信息，而 harness 在决定压缩历史时信任 contextWindow，所以事实来自 lib/metadata.json：models.dev 的 alibaba-cn 和 alibaba 服务商的生成快照，提交在这里，因此运行时没有任何东西依赖第三方。它覆盖 98 个模型，包含真实的上下文窗口、输出上限、接受的模态，以及模型能否思考 —— qwen3.8-max 为 1M/131072，qwen3-vl-plus 为 262144/32768 并支持图像输入，还有 kimi-k3、glm-5.3 等等。

npm run generate:metadata # refresh lib/metadata.json from models.dev
优先级是固定的，最权威的排在最前：models 里的条目完全按写法使用，然后是快照，最后是下面的保守默认值。成员资格始终由端点说了算——快照只接纳端点实际列出的模型，而比快照更新的模型只要匹配上某个模式就照样对外公布，只是用默认数值。重新生成快照属于普通的代码改动：如果快照和随包发布的目录对同一个模型的说法不一致，npm test 就会失败。

升级时请对照你的端点核实容量。 contextWindow 写错是最要命的故障。

发现配置

- id: llm-aliyun
name: '@doitian/dsh-provider-aliyun'
config:
discovery:
enabled: true # false pins the route to models
filter: chat # chat | patterns | all, as the table above
include: # chat families to keep, as case-insensitive regular expressions
- '^qwen3\.8-(max|flash|omni-flash)$'
exclude: # dropped in every mode, even when a pattern matched
- '-realtime$'
ttlMs: 600000 # how long a listing stays fresh; 0 asks on every read
waitMs: 2000 # longest a model list waits for a cold listing
timeoutMs: 15000 # idle bound on one listing request
contextWindow: 131072 # capacity for an id neither models nor the snapshot names
maxTokens: 32768
input: [text]

有两条规则，保证过滤器不会藏起你点名要的东西。models 里点名的 id 无论模式和快照怎么说都会公布——点名一个模型，比这两者中任何一个都更有分量；而编译不过的模式会被忽略并给出警告，不会让挂载失败。include 和 exclude 会替换随包发布的默认值，所以要保留哪些就从 lib/catalog.js 里复制过来。exclude 也是裁剪快照所接纳内容的手段，比如 - '^siliconflow/' 可以去掉某个厂商给已按规范列出的模型起的别名。

注意发现的模型在模态上会拿到什么：快照发布什么就是什么，其余一律用 discovery.input。两个来源都不认识的模型按纯文本公布，因为列表和猜测都没说它接受图像；在 models 里点名它就能把这件事定下来。

尝试失败后，端点会被搁置一分钟，这样不可达的主机就不会让每次读取都变慢；存储或轮换密钥会立即重试。

固定目录

models 既决定回退成员资格，也决定元数据，而配置档可以替换它，不必分叉：

- id: llm-aliyun
name: '@doitian/dsh-provider-aliyun'
config:
models:
- id: qwen3.8-max
name: Qwen3.8 Max
contextWindow: 1000000
maxTokens: 131072
input: [text, image]
reasoning: true
thinkingLevelMap: { low: low, medium: medium, high: high }
discovery.enabled: false 时，这份列表就是全部路由。

思考

阿里云用布尔值 enable_thinking 打开思考，而不是 reasoning-effort 字段，后者正是 compat.thinkingFormat: 'qwen' 发送的内容；supportsReasoningEffort: false 让 effort 值不上线，因为该端点会拒绝它。选中的级别仍然驱动这个布尔值，所以 off 确实会关闭思考。

每个目录条目上的 thinkingLevelMap 声明模型提供哪些级别，以及每个级别的线上拼写。未列出的级别不提供；off 默认提供，除非它在映射中被点名。

回退条目未命名的已发现模型被声明为非推理：级别映射是对模型的断言，声称它可能不具备的思考能力，会提供端点可能拒绝的级别。在 models 中命名该模型，给它级别。

卸载

从 dsh.profile.bundles 中移除它（或在 Plugins 页面删除该行），然后：

dsh plugin --profile <name> remove @doitian/dsh-provider-aliyun

$DSH_HOME/.credentials.yaml 中的凭据保持不动。

工作原理

package.json 声明一个 bundle 补丁：

{ "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }

补丁插入本包自己的插件条目：

- insert:
- id: llm-aliyun
name: '@doitian/dsh-provider-aliyun'

挂载时，lib/index.js 在 LLM 接缝上注册三样东西：带适配器的 aliyun 路由、可配置服务商目录条目——也就是 Models 页面上的那一行，不是 API-key 字段（见配置 API key）——以及针对该条目设置命名空间的模型发现 offer，这样配置界面就能用草稿凭据查询这条路由的端点。

适配器是 PiAiAdapter，由 @deepseek-ai/dsh-llm-pi-ai 导出。它负责最难的部分——把 harness 历史转成 pi-ai 上下文、把 pi-ai 事件转成 harness 流块、图像预算、重放元数据、空闲看门狗——复用它，才让这个包保持为一份目录加几十行代码，而不是第二份适配器实现。

对外公布的目录如何变化。 lib/discovery.js 读取端点的列表并持有一个 ids 数组；lib/models.js 把它与回退条目合并；lib/adapter.js 替换适配器按身份记忆其快照所用的配置档映射。已在进行的操作保留它启动时的快照，下一次读取看到新目录——这也是刷新从不打断流的原因。harness 的会话目录每次读取都会按服务商调用 listModels()，所以选择器显示该路由当时公布的内容。只有 listModels 会等待冷列表，而这个等待放在一个两行的子类里，而不是重新实现适配器。
维护这个插件，有一件事必须知道。 PiAiAdapter 由路由的已解析配置档驱动，而它的包并不把这个结构导出为类型；lib/adapter.js 复刻了它，并记录它必须携带的每个字段。模型元数据不从配置档读取——它来自根据目录构建的 pi-ai 模型描述符，这也是目录能放在这里的原因。DSH 升级后如果开始读取新的配置档字段，这个插件就会坏掉。test/adapter.test.mjs 拿真正发布的适配器去跑工厂，所以这种断裂会表现为测试失败，而不是某个人配置档里一条坏掉的路由。发现契约是第二道这样的接缝：LlmModelDiscoveryRequest、registerModelDiscovery，以及每个服务商 HTTP 请求都必须满足的 attributionHeaders() 要求。

引擎锁定到 harness 自带的 pi-ai：依赖是 ^0.87.1，正好解析到 harness 安装的 0.87.1，所以两边共用同一份副本。

Development

npm install
npm run validate # manifest, patch wiring, fallback catalog, discovery defaults
npm test # drives the real PiAiAdapter, the merge, and the listing state machine

scripts/validate.mjs 能抓住那些本来会静默失败的问题：tarball 漏掉补丁、补丁写错包名、模型 id 重复、容量不是整数、pi-ai 会读成「什么都没提供」的等级映射、以及某个发现默认值会产出一个适配器无法调度的模型。

npm test 需要装好 peer 包——这正是重点，因为它跑的是真适配器，不是桩。真实请求不在范围内：那需要真 key 和真 endpoint。发现逻辑用注入的 fetch 测试，所以覆盖到的是请求周边的每一个决策——它读取的结构、失败时留下什么、以及一次读取最多能等多久。

拿构建产物对着桌面应用测试

npm run link:desktop # point the desktop profile at this checkout, then verify the copy
npm run probe # what the picker will show, read from the live endpoint

然后重启 DSH：插件模块只在启动时加载一次，加载器不会监视它们。

link:desktop 之所以存在，是因为本地依赖并不是工作区的实时视图。pnpm 把 file: 包硬链接进配置档，所以一次替换文件的编辑——git checkout，或任何原子保存的编辑器——会让已安装的副本停留在旧的字节上，而单纯的 install、--force 或 update 都不会重新链接它（「Already up to date」，哪怕目录已被删除）。重新添加依赖才能强制重新解析，脚本会逐字节校验结果，而不是假设它成功了。
用这种方式测试时，有两件事要有预期。Plugins 页面可能把依赖改回 registry 范围——这是正常的包安装，link:desktop 会把它切回来。而已发布的 release 是更持久的替代方案：应用会像安装其他插件一样安装它，不涉及任何本地内容。

发布

发布使用 npm trusted publishing（OIDC），由 .github/workflows/publish.yml 执行。任何地方都没有 npm token：没有 NODE_AUTH_TOKEN，没有 NPM_TOKEN，没有 secret。工作流声明 id-token: write 并运行 npm publish，后者用这个 OIDC 身份换取短期发布 token。

一次性设置，以包所有者的身份操作。npm 11.6 或更高版本可以从命令行创建 publisher——和网站表单是同一个操作，只是不用表单：

npm login # as doitian

npm trust github @doitian/dsh-provider-aliyun \
--file publish.yml \
--repo doitian/dsh-provider-aliyun \
--allow-publish

--allow-publish 是必需的：它授予 CREATE_PACKAGE 权限，没有它或 --allow-stage-publish，命令会拒绝执行。省略 --repo 时，它会从 package.json 推断 owner/repo，两者不一致时会警告，要求 2FA，并提示输入 OTP。先加上 --dry-run，看看它究竟会创建什么，而不实际提交。

绕过 2FA 的 token 做不了这一步。 npm 正在淘汰绕过 2FA 的 token，而且这个限制是不对称的：这类 token 仍然可以发布，但 registry 会拒绝它做 publisher 管理，报错如下

Granular access tokens that bypass two-factor authentication may not perform this action.

所以引导发布可以来自绕过 token，而附加 publisher 需要交互式 npm login 会话或网站表单。读回配置也会因同样的原因被拒绝，因此发布本身就是实际的检验。

账号的双因素认证不会影响工作流。 发布任务用 OIDC token 认证，所以不涉及一次性密码，在 npm 账号上启用 2FA 也不会破坏发布——v0.1.1 正是这样发布的。2FA 真正限制的是上面那次性的 publisher 设置：启用了 2FA 的账号可以运行 npm trust，而绕过 2FA 的 token 在这一步会被拒绝。从终端手动发布是现在唯一会要求 OTP 的流程。

--environment 被有意省略，与发布任务一致，后者没有声明 environment:。

如果 registry 报告包不存在，那么 trusted publisher 无法附加到尚不存在的名称上：先手动发布一次 0.1.0，然后运行上面的命令，让工作流接管之后每一次发布。

然后发布：

npm version patch # or skip it when the version is already committed in package.json
git push --follow-tags
gh release create v0.1.1 --generate-notes

npm version 一步写入版本、提交并打标签。当你想要的版本
如果发布已经手动提交了——某个功能发布自己把 minor 提上去了——那就给这个提交打标签：git tag v0.2.0 && git push --follow-tags，然后为它创建 release。

发布任务要求 release 标签与 package.json 匹配（v0.1.1 ↔ 0.1.1），并在上传前重新跑一遍校验和测试。

编辑工作流时有两个坑：

- pnpm publish 在这里不管用。 它不做 OIDC 交换。用 npm publish。
- 推送 .github/workflows/ 需要 workflow token scope。 没有这个 scope 的 OAuth token 推工作流文件会被拒，尽管它能推其他所有东西；用 gh auth refresh -h github.com -s workflow 加上这个 scope，或者改用 SSH remote，它不受 scope 限制。

License

MIT