前言¶
在 DeepSeek Harness（DSH）里选模型，通常要自己在配置里维护 provider、路由和模型清单。若模型实际跑在 Tailscale Aperture 这类统一网关上，网关会随部署变化增删模型、各模型支持的 HTTP 端点也不相同，手工对齐既慢也容易漏。
社区插件 dsh-aperture（维护者 he0119，npm 包名 dsh-aperture，当前版本 0.4.1，MIT 许可证）面向这一类部署：向 Aperture 拉取模型列表，按模型实际应答的端点注册成 DSH 内的 provider 路由，让模型直接出现在选择器里。装好插件后，多数场景只需填一个 Aperture 实例地址。
这是什么¶
dsh-aperture 属于 DSH 社区目录中的「模型推理」类插件，目录页：https://www.skillhub.cn/plugins/he0119/dsh-aperture，源码：https://github.com/he0119/dsh-aperture。
它不做推理本身，只做发现与注册：请求 GET {baseUrl}/v1/models，根据每个模型返回的 supported_endpoints，把能走 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 的模型挂到三条路由上；仅提供 Gemini 原生 generateContent 等端点的模型不会进入选择器，插件配置页会说明原因。
认证方面，Aperture 依赖 Tailscale 网络身份。插件默认在请求上带占位凭据（如 authorization: Bearer dsh-aperture），以便 pi-ai 发出请求，并非真实 API 密钥；需要真密钥时可配置 apiKeyEnv 指向凭据 seam。
核心功能¶
下面是可以从 README 与实现说明中核对的能力摘要。
- 自动发现：从配置的
baseUrl读取网关模型清单，并按supported_endpoints分流到三种协议路由。 - 三条 provider 路由：默认前缀为
aperture，路由键分别为aperture-openai-chat-completions、aperture-openai-responses、aperture-anthropic-messages；选择器里显示为Aperture (OpenAI Chat Completions)等名称（可由routePrefix调整前缀）。 - 元数据补全：默认从
https://models.dev/models.json补容量、输入类型等；可用modelAliases映射网关 id 与 models.dev id，用models逐条覆盖或补充未在网关上列出的模型。 - Web 配置：在 插件 → dsh-aperture 编辑实例地址、注册开关与「立刻刷新」；在 设置 → 模型 按路由行编辑逐模型覆盖。headless profile 无插件页，但仍可发现、注册，改配置文件即可。
- 只探测不注册：
sync: false或关闭注册开关时只探测、不注册；关闭注册时会把本插件已注册的三条路由撤下。
插件以当前 DSH 进程权限运行；安装前应自行查看源码与许可证，并只从信任的源安装。
安装与启用¶
前提：Node ^22.19.0 或 ≥24.0.0（与官方 DSH 一致），以及可访问的 Aperture 实例。
1. 安装插件¶
推荐用 npm 发布产物（含编译好的 lib/，无需授权构建脚本）：
npx @deepseek-ai/dsh plugin --profile web add dsh-aperture
也可从 git 锁 commit，或添加本地路径；git 安装在 pnpm ≥10 下首次可能因构建脚本被拒绝，需按 README 在 profile 的 pnpm-workspace.yaml 中为 dsh-aperture 配置 allowBuilds 后重试。
2. 配置 Aperture 地址¶
在 profile 补丁文档中为插件命名空间 aperture 填写 baseUrl：
# ~/.dsh/profiles/web/cordis.patch.yml
- id: aperture
config:
baseUrl: https://ai.example.ts.net
末尾 /v1 会被去掉；空 baseUrl 表示休眠（不探测、不注册）。也可在 Web 插件页「实例地址」填写同一字段，保存后写入同一文件。补丁层为整行替换，未写的键回落 schema 缺省值。
3. 重启 DSH¶
bundle 变化不会热加载。重启前可用下面命令确认组合配置里出现 # == dsh-aperture 层：
npx @deepseek-ai/dsh --profile web --dump-config
4. 确认¶
模型选择器里应出现路由名 Aperture 下的各条目。若从 git 安装遇到 peer dependencies 警告，README 说明属预期：Cordis 相关依赖由 DSH 自带解析。
典型用法¶
最小配置¶
只填网关地址即可开始同步（sync 默认为 true）：
- id: aperture
config:
baseUrl: https://ai.example.ts.net
别名与手工补模型¶
网关 id 与 models.dev 不一致时，用 modelAliases；网关上未列出但确认能在 OpenAI 兼容端点使用的模型，可在 models 里显式添加：
- id: aperture
config:
baseUrl: https://ai.example.ts.net
models:
- id: gemini-2.5-pro
api: openai-completions
- id: deepseek-v4-pro
reasoningEfforts: { off: disabled, minimal: minimal, low: low, medium: medium, high: high, max: max }
modelAliases:
deepseek-flash: deepseek/deepseek-v4-flash
k3: moonshotai/kimi-k3
界面操作要点¶
- 立刻刷新：不写设置，直接重跑发现与注册，结果展示在插件页。
- 模型页：按路由行保存覆盖；容量可写
1M、100K（十进制，1M= 1000000）；留空表示不覆盖、回落发现值与目录。 - 注册开关关闭：只探测，并撤下本插件注册的三条路由，不影响其他适配器注册的同名路由。
更细的界面与路由行为见仓库内 docs/internals.md。
适用场景与注意¶
适合谁：已在 Tailscale 上部署 Aperture、希望在 DSH Web 或 agent 里统一选网关模型、又不想手写 llm-pi-ai.providers 的开发者。
协议边界：只接入上述三种 OpenAI/Anthropic 兼容路由；纯 Gemini 原生端点的模型需换端点或另寻适配方式。Aperture 返回的 404 提示里通常会写明应使用的端点类型。
升级与冲突：从 0.2 及更早版本升级时，旧插件可能把路由写在 llm-pi-ai.providers 下且键名与现版不同，需自行清理过期项，避免选择器里重复模型。若提示某路由键已被其他适配器占用，按页面提示删改对应配置，或调整本插件的 routePrefix。
配置优先级：除 profile 补丁外，还可能存在更高优先级的 cordis.patch.yml；若保存未生效，检查是否被上层覆盖。
安全：插件会访问你配置的 baseUrl 并向 DSH 注册路由；从 git 安装并授权 allowBuilds 等于允许该包在 agent 沙箱外执行安装脚本，仅应对信任源码授权。
结尾¶
dsh-aperture 把「网关上有哪些模型、各自走哪条 API」这件事交给自动发现，把 DSH 侧的工作量收成一条 baseUrl 和可选的逐模型覆盖。若你正在用 Aperture 聚合内网或 Tailnet 上的模型，可以在社区目录查看条目说明，并在 GitHub 阅读完整 README 与 FAQ。
