# @apolenkov/dsh-provider-proxy 中文文档
规范地址：https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/
版本：0\.3\.0
npm 元数据更新时间：2026-10-30T07:15:15.151Z
中文译文更新时间：2026-11-06T19:13:54.788Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40apolenkov/dsh-provider-proxy
原文对照：https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/?lang=original
项目主页：https://github.com/apolenkov/dsh-provider-proxy#readme
源码仓库：https://github.com/apolenkov/dsh-provider-proxy
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：128 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：undici ^8\.11\.2，@deepseek-ai/schemastery ^3\.18\.5
- 首次发布：2026-10-22T12:47:50.531Z
- 最新版本发布：2026-10-30T07:15:15.005Z
- 近 30 天下载量：2436（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）
## 中文简介
DeepSeek Harness 的提供商和模式外代理线路
## 安装
```sh
npm install @apolenkov/dsh-provider-proxy
```
也可以使用：`pnpm add @apolenkov/dsh-provider-proxy`、`yarn add @apolenkov/dsh-provider-proxy`、`bun add @apolenkov/dsh-provider-proxy`
## README
# dsh-provider-proxy
[](https://github.com/apolenkov/dsh-provider-proxy/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@apolenkov/dsh-provider-proxy) [](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/LICENSE) [](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/package.json) [](https://github.com/deepseek-ai/deepseek-harness) [](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/#readme-%E5%BC%80%E5%8F%91)
[English](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/README.md) · [Русский](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/README.ru.md) · **中文**
为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供按提供商与按模型 ID 的出站代理路由。
DeepSeek Harness 每个进程只应用**一条**代理策略（`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` / `ALL_PROXY`）。本插件在其之上叠加两条路由轴 — 按提供商主机、按模型 ID — 可在设置页中配置，无需改 YAML（除非你愿意）。
```mermaid
flowchart LR
A["ctx.llm.stream
{provider, model}"] --> B["llm/stream 瀑布
AsyncLocalStorage 存根"]
B --> C["适配器 → fetch"]
C --> D["RoutingDispatcher"]
D -->|命中模型规则| E["direct / proxy / inherit"]
D -->|命中主机规则| E
D -->|回环地址| F["始终直连"]
D -->|无匹配| G["进程策略
env + NO_PROXY"]
```
- **主机轴**（`providers`）：匹配请求 URL 的主机 — 精确、子域、可选 `host:port`。作用于进程内每个 `fetch()`（模型、网页搜索、MCP）。
- **模型轴**（`models`）：匹配发出该请求的模型调用的 `provider`/`model`。支持精确 ID、以 `*` 结尾的前缀，以及可选的提供商绑定。
- **优先级**：带绑定的精确模型 → 精确模型 → 带绑定的前缀 → 前缀 → 提供商主机规则 → `default`（`inherit` 或 `direct`）。
## 安装
前提：带插件管理器的 DSH 配置（Desktop 应用与 `dsh web` 均可）。
**从 npm 安装**（推荐）：
```sh
dsh plugin --profile add @apolenkov/dsh-provider-proxy
```
**从 git 安装**（按发布标签，不经过注册表）：
```sh
dsh plugin --profile add git+https://github.com/apolenkov/dsh-provider-proxy.git#v0.2.0
```
安装后重启 DSH。插件会插入 `provider-proxy` 行；路由配置保存在该行中。
> npm 说明：包名是 `@apolenkov/dsh-provider-proxy`。不带作用域的 `dsh-provider-proxy` 属于注册表上的另一个无关包，请勿执行 `pnpm add dsh-provider-proxy`。
## 配置
### 在界面中（推荐）
打开侧边栏的 **Settings（设置）→ 代理路由**，或 **Plugins → dsh-provider-proxy → Configure**。两处是同一个编辑器：
- **默认路由**（`inherit` 或 `direct`）；
- **提供商规则**：名称、主机（逗号或换行分隔）、代理（`inherit` / `direct` / 自定义 `http(s)://` URL）；
- **模型规则**：模型 ID（精确或以 `*` 结尾的前缀）、可选的提供商绑定、代理。
修改先在本地暂存，点击**保存**后才写入，并带版本校验：若配置在别处已改动，保存会被拒绝而不是静默覆盖。表单不会被清空写入；离开页面会丢弃暂存修改。
### 在 YAML 中
在配置文件的 `cordis.patch.yml` 里添加或修改该行（HMR 实时生效，无需重启）：
```yaml
- id: provider-proxy
name: "@apolenkov/dsh-provider-proxy"
config:
default: inherit
providers:
corp:
hosts: ["llm.internal.example"]
proxy: direct
opencode-go:
hosts: ["opencode.ai"]
proxy: "http://127.0.0.1:1301"
models:
"muse-spark-1.3-contributor":
provider: opencode-go
proxy: "http://127.0.0.1:1301"
"longcat-*": inherit
```
无效条目会拒绝整份配置（fail-closed）：插件记录原因、保留原有路由，绝不会只应用一半。
### 代理取值
| 取值 | 含义 |
| --- | --- |
| `inherit` | 使用启动器的进程代理策略（env + `NO_PROXY`）。 |
| `direct` | 直连源站，忽略进程策略。 |
| `http(s)://…` | 经该代理转发（`ProxyAgent`）。不支持 SOCKS 与 PAC。 |
界面还会拒绝带凭据的代理 URL — 不要把密码写进配置文件。
## Muse Spark 示例
把单个模型放到专用代理上，其余流量保持启动器策略：
```yaml
- id: provider-proxy
name: "@apolenkov/dsh-provider-proxy"
config:
default: inherit
models:
"muse-spark-1.3-contributor":
provider: opencode-go
proxy: "http://127.0.0.1:1291"
```
见 [`examples/models-muse-spark.yaml`](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/examples/models-muse-spark.yaml)（已脱敏：仅回环地址、无凭据）。
## 演示
在临时配置中用回环代理录制：打开设置页、添加 Muse Spark 规则、触发并修正校验错误、保存，最后展示 Settings 中的页面。单帧见 [`assets/screenshots/en/`](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/assets/screenshots/en/)。
## 验证是否生效
插件把最近一次应用结果（不含机密）写入 `$DSH_HOME/provider-proxy/state.json`：
```json
{
"appliedAt": "2026-10-22T07:59:22Z",
"pid": 42120,
"status": "active",
"routes": "muse-spark-1.3-contributor→http://127.0.0.1:1301, llm.internal.example→direct, default→inherit"
}
```
可用“死代理”验证规则确实生效：把规则指向 `http://127.0.0.1:9`，请求应以 `ECONNREFUSED 127.0.0.1:9` 失败而不是到达目标 — 之后恢复正常代理。
## 限制
- WebSocket 传输不保证经过 undici 调度器；需要严格路由时请使用 `http(s)`。
- `web_fetch` 通过启动器自身的策略固定地址，可能绕过这些规则；模型流量已被覆盖。
- 模型规则只在 `llm/stream` 内生效；网页搜索与 MCP 走主机轴。
- 模型规则不会作用于同一主机上的非模型流量；主机规则永不覆盖 `localhost` / 回环。
- 带凭据的代理 URL 会被传输层接受，但界面会拒绝；建议使用无凭据的代理端点。
## 开发
```sh
pnpm install --ignore-scripts
pnpm test # node:test，44 个测试：匹配、优先级、ALS 隔离、出口、装配、表单逻辑
pnpm check # 清单 + 机密 + 市场索引 + 完整测试
```
见 [CONTRIBUTING.md](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/CONTRIBUTING.md)、[CODE\_OF\_CONDUCT.md](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/CODE_OF_CONDUCT.md)，以及 [docs/](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/docs/)（架构、配置参考、UI、发布清单、市场、排障、术语表）。
## 市场
DSH 市场索引（format 1）见 [`market/dsh-market.json`](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/market/dsh-market.json)，由 `pnpm release:market` 依据清单与发布提交生成；插件已带 `dsh-plugin` 话题，社区目录 [dsh.market](https://dsh.market/) 会自动收录。
## 许可
MIT — 见 [LICENSE](https://npmcn.com/package/%40apolenkov/dsh-provider-proxy/LICENSE)。DeepSeek Harness 属于 DeepSeek 的独立项目；本插件为社区作品，与其无隶属或背书关系。
## 常见问题
### @apolenkov/dsh-provider-proxy 是什么？
DeepSeek Harness 的提供商和模式外代理线路
### 如何安装 @apolenkov/dsh-provider-proxy？
在项目目录运行 npm install @apolenkov/dsh-provider-proxy，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：undici（^8\.11\.2）、@deepseek-ai/schemastery（^3\.18\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @apolenkov/dsh-provider-proxy 支持 TypeScript 吗？
该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apolenkov\_\_dsh-provider-proxy 是否存在。
### @apolenkov/dsh-provider-proxy 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @apolenkov/dsh-provider-proxy 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @apolenkov/dsh-provider-proxy 可以商用吗？
@apolenkov/dsh-provider-proxy 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @apolenkov/dsh-provider-proxy 的下载量有多少？
根据 npm 官方下载统计，@apolenkov/dsh-provider-proxy 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,436 次，日均约 81 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @apolenkov/dsh-provider-proxy 还在维护吗？
最新版本 0\.3\.0 发布于 2026/10/30（8 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。