lo2589/deepseek-harness-media

Provider 快速配置 — 一个 dsh 动态插件

中文版 | English

插件源码就在本仓库中：plugin/ 存放动态插件形式（host.js = Host 半部分，client.js = Client 半部分，manifest.json = 可还原定义）；dsh-provider-quick-config/ 是正式可安装的 npm 包（Host 通过 dsh.bundle，Web UI 通过 dsh.client）——对 deepseek-harness 源码零改动（仓库中受跟踪的文件未显示任何修改；它与云端 origin/master 逐字节一致）。

截图

Provider 面板截图

使用此插件的两种方式

| | 动态插件（快速/开发） | 正式安装（推荐，永久） |
|---|---|---|
| 安装 | 在会话中执行 cordis_define + 批准 Run 卡片 | 将 npm 包安装到 web profile |
| 生命周期 | 仅当前 harness 进程——重启后丢失 | 重启后依然存在，永久 |
| 通信 | harness.handle / host.call（沙箱 RPC） | 标准 wire（connection.api：settings / credentials / llm） |
| 源码 | plugin/ | dsh-provider-quick-config/ |

正式安装（本机已完成）

该包已构建、打包（dsh-provider-quick-config-0.5.4.tgz）并安装到 web profile：

cd /path/to/deepseek-harness
pack the package (in dsh-provider-quick-config/): npm pack
node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add \
file:/path/to/dsh-provider-quick-config/dsh-provider-quick-config-0.5.4.tgz
cd ~/.dsh/profiles/web && pnpm install   # only needed when the tarball path changed

dsh plugin add 会在 profile 中运行 pnpm add，并在包声明了 dsh.bundle.patch 时将该包追加到 dsh.profile.bundles。验证：

cat ~/.dsh/profiles/web/package.json
dsh.profile.bundles should include "dsh-provider-quick-config"

然后重启 dsh web（例如 deepseek.sh restart）——Host 半部分会从 profile bundle 挂载，dsh-client-modules 会在 /plugins/dsh-provider-quick-config/client.js 提供 Web 半部分。重启后：+ 按钮会出现在 Send 旁边（不再需要逐会话批准）。

代码更改后更新：提升版本号，重新打包，dsh plugin --profile web add file:….tgz（或更新依赖 spec + pnpm install），重启。
卸载：dsh plugin --profile web remove dsh-provider-quick-config，重启。

在 DeepSeek Harness Web GUI 中 Send 按钮旁边的一个 + 按钮。点击它即可配置模型 provider，无需手动修改配置文件：

- 列出每个已配置的 provider 路由（llm-pi-ai.providers.），包括凭证状态以及每个路由所提供的模型。
- 一键厂商预设：智谱 GLM、MiniMax、OpenAI GPT、Anthropic Claude、本地模型（Ollama）——endpoint / protocol / thinkingFormat / 模型列表均已预填。
- 模型选择器：按供应商提供快捷模型芯片（点击即可选择/取消选择），以及自由格式行（id / ctx / max）——例如，点击 MiniMax-M3 芯片即可将 MiniMax 切换为 M3，无需编辑 JSON。
- 保存时自动校验模型名称（ping）：保存前，插件会查询端点的 GET /models 并进行比较（不区分大小写/连字符）。不存在的模型（例如输入 glm4.6v 而不是 GLM-4.6）会报红色错误并阻止保存。不支持列表功能的端点会被跳过并正常保存。
- 自动加载本地模型：选择 Ollama 预设后会立即请求 GET /models 并填充表单（每条自定义路由上也有“获取模型”按钮）。
- 自动同步本地模型（syncModels）：标记为 syncModels: true 的路由（Ollama 预设默认开启，表单中有开关，列表中有徽章）会每 60 秒在后台与其端点的 GET /models 进行比较；当端点列表发生变化时（例如你 ollama pull 了一个新模型），插件会自动将新列表写回 settings.yaml，下拉菜单随之更新——无需手动编辑。端点顺序优先，已配置模型的容量会被保留。已端到端验证。
- 每个供应商支持多个 API 密钥：再次添加同一供应商时，路由键会自动编号（glm → glm2 → glm3…），显示名称会加上 · 号N。
- 媒体展示（🎞）：一个常驻右侧面板，会扫描当前会话的历史记录，并显示对话中提到的每个媒体文件——图片（PNG/JPEG/WebP/GIF/AVIF/BMP/SVG/ICO）、视频、录音。SVG 可在  中原生渲染。文件从会话的工作目录解析，并带有文件名搜索回退（文本引用中缺少路径前缀的文件，例如 tiile-20260815/x.mp4 实际位于 outputs/tiile-20260815/ 下，仍可被找到）。条目按对话轮次分组（“第 1 轮”、“第 2 轮”…）。媒体数据绝不会进入模型上下文——仅用于显示。每个条目都可以将其路径插入到编辑器中（inputActions.setDraft），光栅图片还可以额外作为附件插入。该面板还会自动扫描 /.uploads/（SVG/通用上传）和 /.screenshots/（截图库），因此写入这些位置的文件会自动出现，并分组到单独的“上传库”和“截图库”轮次中。

媒体展示面板
- SVG 上传 + 插入路径：上传按钮接受 .svg（PNG/JPEG/WebP/GIF 仍作为图片附件处理）。SVG 文件会通过新的 save-media 端点保存到 /.uploads/，并将路径以 name 的形式追加到编辑器中——发送后即可内联显示，且该 SVG 会出现在媒体展示中（也可以从文件系统拖拽或粘贴到 /.uploads/ 中，使其出现在展示中）。
- 截图 📷：通过 getDisplayMedia 捕获屏幕，将 PNG 保存到 /.screenshots/（媒体展示库文件夹，已被 gitignore 忽略），并将返回的路径写入编辑器——由你决定是否发送。保存的截图会自动出现在展示库中。

- 自定义 OpenAI 兼容提供商（任意网关 / 自托管服务器），可手写 api、baseURL、thinkingFormat 和模型列表。
- 编辑 / 删除现有路由；设置或更新 API 密钥。

工作原理（无需修改 harness 代码——纯配置文件，热重载）

该插件不会自创配置存储；它驱动 harness 已提供的两个接缝：

| 操作 | 写入位置 | 效果 |
|---|---|---|
| 添加 / 编辑 / 删除路由 | $DSH_HOME/settings.yaml 中的 llm-pi-ai.providers | settings mutate → 文件持久化 → llm-pi-ai 适配器的 watcher 重新注册——在下次请求时实时生效 |
| 保存 / 更新 API 密钥 | $DSH_HOME/.credentials.yaml（0600） | credentials set → 文件被监视，热重载 |

该插件仅存储凭据引用（环境变量名）；密钥值直接写入 .credentials.yaml，绝不会返回 GUI。

路由写入通过 settings.mutate 进行，它会根据 llm-pi-ai 命名空间 schema + assertServiceable 进行校验：错误的协议、空的 baseURL 或无效的模型都会在写入时被拒绝——损坏的路由永远无法被存储。

安装 / 运行

1. 在本会话中批准 Run 卡片（单次勾选即可；双重勾选会自动运行未来版本）。
2. 刷新页面——+ 会出现在编辑器的工具栏中，位于模型选择器 / 发送按钮旁边。
3. 点击 + → Add Provider → 选择预设或自定义 → 填写表单 → 保存。

官方 Settings → Models 页面仍可同时使用；此插件是输入框旁的快捷入口。

进程重启后恢复插件

动态插件仅存在于进程内存中：重启 dsh web 会移除 pprov-1。从本仓库恢复（源文件永远不会消失）：

1. code.host ← plugin/host.js 的完整内容
2. code.client ← plugin/client.js 的完整内容
3. 使用 cordis_define 重新定义（kind: "new"，idPrefix: "pprov"；从 plugin/manifest.json 复制 name / purpose），然后 cordis_run。

你的配置（~/.dsh/settings.yaml + .credentials.yaml）不受影响，因此路由会立即重新出现。

表单字段

| 字段 | 说明 |
|---|---|
| 路由键 | 唯一 id（providers 字典的键）；任意值，保存后不可更改。每个供应商可有多个键（glm1 / glm2 …） |
| 显示名称 | 显示在模型选择器中；默认为路由键 |
| 凭据引用 | 环境变量名，例如 GLM_API_KEY；每次请求时通过 credentials 解析 |
| API 密钥 | 可选。已填写 → 写入 .credentials.yaml；留空 → 保留现有值 / 依赖环境变量 |
| API 协议 | 自定义路由需选择其一：openai-completions / openai-responses / anthropic-messages |
| BaseURL | 自定义路由必填 |
| thinkingFormat | openai-completions 的推理字段方言：openai / deepseek / openrouter / together / zai / qwen / string-thinking / ant-ling。当端点 URL 无法识别时手动指定（MiniMax → deepseek，Zhipu → zai） |
| Models | 自定义路由需 ≥1 个：[{ "id": "…", "contextWindow": 131072, "maxTokens": 32768 }] |

踩坑记录（血泪教训）

- Ollama 仍然需要密钥：OpenAI 兼容实现总会发送 Authorization 头，所以给它任意非空占位符即可（例如 local）。
- 目录路由不需要模型列表：只需 key + 凭据；端点/协议/模型均继承自 pi-ai 目录。手写路由需显式声明模型。
- .credentials.yaml 很严格：必须是扁平的 name: value 映射；根必须是映射，值必须是非空字符串，重复键会导致整个文件在启动时失败。
- ⚠️ 切勿在 settings.yaml 中使用 YAML 锚点（&anchor / anchor）：settings 服务保存时采用保留节点的合并方式；一旦某次保存替换了锚点的所有者（例如 glm 的 models: &glm_models），剩余的 glm_models 别名就会悬空，整个文档将无法序列化，报错 Unresolved alias (the anchor must be set before the alias)——本插件和官方 Settings → Models 页面都会中招。请显式写出共享模型列表（或先让插件/我帮你把文件展平）。
- 环境变量是启动时的快照：启动后再 export 不起作用，除非重启；请改用本插件的 key 字段（会写入 .credentials.yaml）。
- apiKeyEnv 已设置但无法解析 → MISSING_CREDENTIAL；它不会回退到环境中恰好存在的其他密钥。
- Safari 屏幕捕获权限（📷 按钮无反应 / 选择器从不弹出）：Safari 的屏幕共享权限位于 Safari 自身内部，而非系统设置中。修复方法：Safari → 菜单栏 Safari → 设置…（⌘,）→ 网站标签页 → 左侧列表中的 屏幕共享（或“屏幕录制”）→ 找到你的主机（127.0.0.1: 或你使用的域名）→ 将其从 拒绝 改为 询问（或 允许）→ 完全退出 Safari（⌘Q）并重新打开（仅刷新是不够的——WebKit bug 253024 会使该故障在重新加载后仍然持续）。同时确认系统设置 → 隐私与安全性 → 屏幕录制中已勾选 Safari。如果你曾经点击过“不允许”，而它再也不询问：该决定会按站点被记住——回到 Safari → 设置 → 网站 → 屏幕共享，找到该站点，并 完全删除该行（移除，而不只是切换状态），或将其设置为 询问；然后退出 Safari（⌘Q）并重新打开——选择器提示会再次出现。如果仍然失败，请改用系统截图：⌘⇧4 然后粘贴（⌘V）到输入框中（编辑器原生支持粘贴图片）。
- 已经发送过请求的会话会在其日志中保留所记录的模型；如果默认模型指向已删除的提供方，选择器会要求你重新选择。

技术说明（面向插件维护者）

- Host 半部分（harness.handle RPC，全部通过 ctx.settings / ctx.credentials / ctx.llm）：
- providers.list → 已配置的路由 + 凭据状态 + pi-ai 目录 + 协议/方言枚举
- providers.save / providers.remove → 操作在 Client 侧构建并通过网络传输到达；Host 仅将其转发给 settings.mutate('llm-pi-ai', ops, revision)
- providers.discover → ctx.llm.discoverModels('llm-pi-ai', { baseURL, api, apiKey })
- providers.ping → 同样的发现流程，然后根据列表验证每个模型 id（规范化后）
- credentials.set / credentials.unset
- ⚠️ vm-sandbox realm 陷阱：动态 Host 代码运行在 node:vm realm 中，因此任何对象字面量都不是 host-realm 的普通对象——将其传递给会检查 isPlainObject 的服务（如 settings.mutate / settings.update）会抛出 ops must be {op:'set'|'unset', path}。任何用于此类服务的结构化数据都必须在 Client 侧构建，并通过 host.call JSON 网络传输（网络解码后的值是 host-realm 的）；Host 仅负责转发。返回值没有问题——该防护会重新物化它们。
- Client 半部分：+ 按钮注册在 conversation.input.right（发送按钮之前的工具行）；面板注册在 conversation.input.overlay（编辑器的浮动锚点）；所有颜色均使用 --dsw- 主题变量。
- 写入会携带 expectedRevision；并发编辑会引发 SETTINGS_CONFLICT，客户端会重新读取并重试一次。

仓库布局

DeepSeek-Harness-provider/
├── README.md          # 本文件（英文）
├── README.zh.md       # 中文版
├── plugin/
│   ├── host.js        # Host 半部分源码（code.host 主体）
│   ├── client.js      # Client 半部分源码（code.client 主体）
│   └── manifest.json  # 可恢复定义（name/purpose/code）
└── .gitignore