dsh-llm-proxy
dsh 插件：SYSTEM proxy + LLM 分流代理。通过一个进程级 undici 路由 Dispatcher，
把 LLM 流量按配置列表分流到指定代理，其余流量走系统代理（启动环境变量），都没配则直连。
优先级语义
LLM 列表命中 > SYSTEM proxy（env 语义）> 直连
- 请求 origin 命中
llmProxy 列表条目 → 走该条目指定的代理（undici ProxyAgent）
- 未命中 → 走共享的 undici
EnvHttpProxyAgent，它自己处理
HTTPS_PROXY / HTTP_PROXY / ALL_PROXY / NO_PROXY
（大小写均兼容）——即标准 env 代理语义
- SYSTEM 也未配置 → 直连
环境变量只读不写：插件不会修改 process.env.HTTP_PROXY——对已启动进程无意义。
安装
# 方式一：作为 npm 插件加入 profile
dsh plugin add @aiwayds/dsh-llm-proxy # 或在 settings.yaml 的 plugins 里声明
# 方式二：手动 patch 挂载（本包自带 cordis.patch.yml）
# 在 profile 的 bundles 中插入：
# - id: dsh-llm-proxy
# name: '@aiwayds/dsh-llm-proxy'
要求 dsh >= 0.1.5-rc.2 — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。不再支持 alpha 线。
⚠️ 最低宿主要求：0.2.0 起本插件声明 inject: ['skills']，要求宿主 dsh 提供 skills
服务（@deepseek-ai/dsh-skill 0.1.1-rc 系列+）。无该服务的旧宿主上，本插件（含代理
路由功能）不会加载。
发布状态：本包已发布到 npm（0.2.0，自带内置 skill），方式一
dsh plugin add @aiwayds/dsh-llm-proxy 即可直接用。
卸载
dsh plugin --profile <profile> remove @aiwayds/dsh-llm-proxy
宿主自动清理：profile 清单里的 dsh.profile.bundles 条目被摘除，本包的 patch 层随之卸下。
插件自身不在磁盘上留下任何状态——不写任何文件，环境变量只读不写；进程级 undici/fetch 全局接管的拆除是对称且经过测试的（test/dispose.test.mjs 覆盖 dispose 后 globals 还原与 HMR 窗口），dispose 干净。
会留存的只有手动安装的 skill（见上文 Skill 一节），需手工删除：
rm ~/.dsh/skills/dsh-llm-proxy-config # 手动拷贝/软链的副本
rm -r ~/.agents/skills/dsh-llm-proxy-config # npx skills add 装出的条目
Skill（内置使用指南）
本仓库自带一个 dsh skill（skills/dsh-llm-proxy-config/SKILL.md）：面向 agent 的配置 + 排障
使用指南，frontmatter description 内嵌触发词（dsh 代理、HTTP 代理、LLM 分流、llmProxy、
407、CONNECT 挂起、SOCKS、NODE_USE_ENV_PROXY 等），进入每会话模型目录用于路由。三种获取方式：
-
随插件自动注册（零操作）：通过 npm 包或 bundle（cordis.patch.yml）挂载本插件后，
skill 随插件 apply() 自动注册——进入每会话 skill 目录（<available_skills>，
frontmatter description 供模型路由），/dsh-llm-proxy 手势可直接调出指南（已实测可用）。
-
GitHub 安装（不装插件，只要 skill）：
npx skills add fan56/dsh-llm-proxy # 安装到 ~/.agents/skills/
-
手动：git clone 本仓库后，把 skills/dsh-llm-proxy-config/ 拷贝或软链到 ~/.dsh/skills/：
git clone https://github.com/fan56/dsh-llm-proxy.git
ln -s "$(pwd)/dsh-llm-proxy/skills/dsh-llm-proxy-config" ~/.dsh/skills/dsh-llm-proxy-config
⚠️ 铁律：本包的 @deepseek-ai/* 只声明在 peerDependencies
（devDependencies 保留供本地构建）。请勿把它们挪进 dependencies——那会装出第二份
cordis 闭包，导致双实例崩溃（详见 dsh 生态 link-dsh-closure 机制）。
配置入口（settings.yaml 命名空间段）
dsh 插件的用户配置唯一入口是 settings.yaml 里按插件 id 命名的命名空间段。本插件通过
@deepseek-ai/dsh-settings（要求 >=0.1.5-rc.2）settings provider 的
installSection 注册了 dsh-llm-proxy 命名空间
（与 harness 内置插件 llm-deepseek 的 llm-deepseek: 段同机制），所以请在
~/.dsh/settings.yaml 写：
dsh-llm-proxy:
enabled: true # 总开关，默认 true；false 时完全不动全局
systemMode: env # 'env'（默认，读环境变量）| 'off'（全部直连，仅 llmProxy 生效）
llmProxy: # 匹配列表，按顺序首条命中生效
- match: "api.deepseek.org" # 域名精确匹配（含任意端口）
proxy: "http://127.0.0.1:7890"
- match: "*.volces.com" # 通配：volces.com 本身 + 任意子域
proxy: "http://127.0.0.1:7891"
- match: "https://api.openai.com" # 完整 origin 精确匹配（大小写不敏感）
proxy: "http://127.0.0.1:7892"
要点：
- 顶层键必须是
dsh-llm-proxy:（与插件 id 一致）。写其他键（如 llm-proxy:）不会
被读到，静默失效。
- 编辑 settings.yaml 热生效：settings provider 发布变更后，插件会拆掉旧 router、按新
配置重建，无需重启。
- bundle entry config（
cordis.patch.yml insert 行的 config:）作为 base 层仍然有效；
settings.yaml 段覆盖其上的同名键。
- 未挂载 settings 服务的宿主自动回退到 entry config，插件照常工作。
match 规则
| 写法 | 含义 |
|---|
api.example.com | host 精确匹配，任意端口都算命中 |
api.example.com:8443 | host + 显式端口必须相等（https 默认 443 / http 默认 80 会补全比较） |
*.example.com | example.com 本身及任意层级子域 |
https://api.example.com | 完整 origin 精确匹配（scheme 也要一致） |
匹配全部大小写不敏感、纯词法比较（无 DNS/IO）。IDN 域名在匹配前统一归一化为 punycode
（中文.com 与 xn--fiq228c.com 两种写法等价，pattern 和 origin 两侧对称处理）。
实现为纯函数（src/match.ts），有完整单测。
proxy 协议限制
undici ProxyAgent 只支持 http:// 与 https:// 上游代理。
socks5:// 等 schema 在启动校验时直接报错（fail-fast），README 明说：SOCKS 不支持。
实现要点
- service start 时创建自定义 undici 路由 Dispatcher 并
setGlobalDispatcher(router)；
router 的 dispatch() 按 origin 分流：命中 → 该条的 ProxyAgent（按 URL 缓存复用）；
未命中 → 共享 EnvHttpProxyAgent（或 systemMode: off 时直连 Agent）。
- 照抄 pi-src 生产模板的防御细节：
undici.install?.() 防 Node 内建 fetch 与 npm undici 版本偏斜 bug
（Node 26 bundled fetch 经 npm undici dispatcher 不解压导致 response.json()
失败）；用 pristine/owned 双守卫只在未被替换时 install。- undici Client 中途断流会发裸
error 事件导致 unhandled crash——对本插件创建的
每个 dispatcher 挂 EventEmitter 级 error 兜底 listener（与 pi-src
http-dispatcher.ts 同款机制，覆盖进程内所有由本插件创建的 dispatcher）。
- HMR 重载窗口闭环：接管状态（原始 dispatcher/fetch + 活跃层列表）存放在
Symbol.for 共享槽位，跨模块副本可见。cordis Group.update 先 create 后 remove、
vendor HMR 先 re-import 后 dispose——新版 apply 可能发生在旧版 dispose 之前；
dispose 只摘除自己那一层，把 globals 还给最近的存活层，绝不打掉别人的路由器。
- dispose（cordis effect 语义）时非阻塞拆除：先把 globals 还回去（新请求立即不再
进入旧 router），再后台 fire-and-forget 地
close() 排空在途请求——长 LLM 流式响应
不会拖住热重载。
- proxy URL 中可能出现的 userinfo 凭证（
user:pass@host）在日志/error message 里一律
脱敏为 ***@host。
- 与
NODE_USE_ENV_PROXY 官方姿势的关系：本插件是等价替代——无需该变量、无需重启，
对新请求即时生效，且额外提供 LLM 分流能力。
手动 e2e 验证（CI 无网，不做真实请求测试）
# 1. 配一个本地回显代理（如 clash/mihomo 的 mixed-port 7890）
export HTTPS_PROXY=http://127.0.0.1:7890
# 2. settings.yaml 配 dsh-llm-proxy 段，把某个 API 域名指到另一端口
# 3. 启动 dsh 后发起对话，观察代理访问日志：
# - llmProxy 命中域名的请求出现在该条代理日志里
# - 其他外网请求出现在 7890 日志里
# 4. unset HTTPS_PROXY 重启 → 只有 llmProxy 命中的流量走代理，其余直连
开发
npm run build # tsc -> lib/
npm run check # tsc --noEmit
npm test # node --test（match / router 探针分流 / config 边界 / skill 注册 /
# dispose 对称性 / e2e 全链路：apply → 全局 fetch 分流 → dispose 恢复 + HMR 窗口回归）
