前言¶
在 DeepSeek Harness（DSH）里走外部模型，常见做法是自己在 profile 里改 llm-pi-ai 路由、维护 baseURL 和 API Key，还要处理 profile 补丁把整条 providers 盖掉、出站地址与设置页脱节等问题。API3D（api3d.cn）是面向 OpenAI 兼容协议的中转网关；若你已经在该站点开号、只想在 DSH 里稳定选模型对话，手工改配置的成本偏高。
下面介绍社区插件 dsh-api3d（维护者 ptb-xiaou）：把 API3D 接成 DSH 里的一条 pi-ai 路由，站点地址、密钥和出站兼容开关集中在插件设置页，并提供密钥与模型向导。分类为「模型推理」；仓库 ptb-xiaou/dsh-api3d，npm 包 dsh-api3d@0.2.8，MIT 许可证。
这是什么¶
一句话：把 API3D 变成 DSH 可选的模型路由，配置在 UI，路由在解析期按导入的模型目录装配。
插件不自研 LlmAdapter，仍由官方 pi-ai 适配器发请求；插件负责让请求被中转站接受（出站围栏改写 baseURL、可选 UA/直连/工具 schema 兼容等）。默认站点写在 lib/site.js，装上后基础地址预填 https://api3d.cn/v1，属于「零配置可用」的骨架：路由存活、凭据、设置卡、向导已打通；余额、用量、计费、健康探测在 README 中标明为预留接缝。
未导入任何模型时，插件不声明 provider（避免 pi-ai 校验「空路由」报错）。向导导入模型后，路由与模型选择器同步出现，无需再改 YAML。
核心功能¶
设置与向导¶
装好后侧边栏「插件」下多一行 API3D：
- 填 API Key（基础地址已预填），点「确认并查询模型」；无密钥时可从面板链接在系统浏览器打开 api3d.cn 注册页。
- 宿主对
GET {baseURL}/models拉取站点在售模型列表。 - 勾选模型并「导入所选模型」；可为每行调整输入类型、上下文、最大输出、推理档位等能力字段。
密钥在失焦时以 api3d-…cdef 形式打码显示；支持最近 5 把密钥的下拉复用（真实值不出宿主进程，由 POST /api/api3d.keys 等接口配合序号回传）。历史记在 $DSH_HOME/.credentials.yaml 的 API3D_API_KEY_HISTORY（默认引用名与 API3D_API_KEY 同文件）。
路由与出站¶
- 解析期监听
internal/config，在 profile 补丁「一层深合并」挤掉插件路由时，用插件设置算出的routeValue把带导入目录的api3d路由写回 loader。 - 路由
baseURL使用保留域哨兵upstream.api3d.invalid，出站围栏改为设置里的真实地址；并可选：替换 User-Agent、直连绕过进程代理、补required: []、静默重试、402 额度错误提示等。
升级¶
自 0.2.8 起，组合包详情页在「卸载」左侧提供「升级到 x.y.z」（有新版本时可点）；link: 或开发目录安装时按钮不可点。升级后需重启 DSH 生效。
安装与启用¶
装进某个 profile 后必须重启 DSH（插件行属于 boot graph，热载不生效）。示例 profile 为 web，可按你的实际 profile 替换。
npm（推荐，当前 latest 为 0.2.8）：
dsh plugin --profile web add dsh-api3d
GitHub 直装（仓库 lib/ 为成品，无构建步骤）：
dsh plugin --profile web add github:ptb-xiaou/dsh-api3d
指定 tarball：
dsh plugin --profile web add https://registry.npmjs.org/dsh-api3d/-/dsh-api3d-0.2.8.tgz
add 会把包写入该 profile 的 package.json（dsh.profile.bundles 与 dependencies）。启动日志在未导入模型时一般为「尚未导入模型 → 暂不声明 api3d 路由」；导入后为「路由 api3d → https://api3d.cn/v1，模型目录 N 个」。
本包 peerDependencies 仅声明 @deepseek-ai/cordis / @deepseek-ai/schemastery，不在 DSH 主版本兼容闸门内；大版本升级后若异常，需自行对照 issue。运行环境要求 Node >=22（见 package.json）。
典型用法¶
经过上面的安装与重启：
- 打开侧边栏 插件 → API3D（首次且无导入模型时会自动弹出向导）。
- 确认基础地址为
https://api3d.cn/v1，填入 API Key，查询并勾选要用的模型，导入。 - 在 DSH 模型选择器中使用 API3D 分组下的模型进行对话。
维护者可用脚本探测模型目录与设置 diff：
npm run probe-models
（需在插件开发目录、并具备有效 key 与配置上下文。）
适用场景与注意¶
适合： 已在 API3D 开号、希望在 DSH 桌面/Web profile 里用向导维护模型目录，且需要出站兼容（代理/WAF/严格上游）的用户。
注意：
- 宿主半在 DSH 进程内运行，不受工作区沙箱限制，并会接触 API Key；安装前请阅读
lib/index.js与许可证（MIT，衍生说明见 NOTICE）。 - 插件是单站骨架；换站点需改
lib/site.js中的身份常量（包名、provider 名、默认地址等），属于 fork 场景而非设置页切换。 - 社区目录页 skillhub.cn/plugins/ptb-xiaou/dsh-api3d 与 GitHub 仓库并列分发信息；目录站点为社区生态入口，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-api3d 把 API3D 中转站收成 DSH 里可配置的一条 pi-ai 路由：密钥与模型在向导里导入，出站细节在设置页开关，避免手改 profile 却被补丁层回滚。进一步了解实现与设计取舍见仓库 README；安装可从 npm 或 GitHub 直装，版本以 Releases v0.2.8 与 npm dsh-api3d 为准。
- 目录页：https://www.skillhub.cn/plugins/ptb-xiaou/dsh-api3d
- GitHub：https://github.com/ptb-xiaou/dsh-api3d
