多模态辅助模型套件 CarlMarkswx/deepseek-multimodel

DeepSeek Multimodel —— 辅助模型统一插件套件

为 DeepSeek Harness 提供统一的“辅助模型”体系：视觉（图片分析）与图像生成合并在一个设置页里管理，每个能力槽位独立绑定自己的提供方——Harness LLM 路由（经适配器派发）、自定义 OpenAI 兼容端点、或关闭；未来可扩展视频生成等新模态。

CI
npm
License: MIT

这是由社区维护的非官方插件，不隶属于或代表 DeepSeek。套件发布到 npm，并通过 DeepSeek Harness 自带的 dsh plugin 命令安装；GitHub 源码安装保留给开发者和离线场景。

✨ 功能特性

- 🧩 统一设置页 —— 设置 → 辅助模型：能力槽位列表 + 自定义提供方池（对标 Hermes 的辅助模型页）
- 🔗 真正的 Harness 路由复用 —— 视觉槽位可直接绑定“模型”页已添加的 Harness 提供方：调用经 ctx.llm 适配器派发，协议、端点、凭据、错误归一化与重试事实全部由适配器负责，本套件不重建 HTTP 客户端
- 🛠️ 自定义提供方池 —— OpenAI 兼容的 /chat/completions（视觉）与 /images/generations / /images/edits（图像生成）端点，支持独立密钥存储、环境变量引用、自定义请求头、固定尺寸、一键探测模型目录与测试连接
- 🔢 类型化能力绑定 —— 每个能力槽位独立选择 harness-llm（视觉）/ custom-openai / disabled，模型 pin 不受目录约束（目录仅作建议）
- 👁️ inspect_image —— 视觉纪律提示词 + 证据台账（PASS/FAIL/UNCERTAIN），磁盘图片先落持久附件存储再进模型请求
- 🖼️ generate_image —— 对话内缩略图预览 + 可点击存档路径 + 上游故障明确转告；禁用时与视觉一致整体隐藏（工具 + 提示词一起消失）
- 🧱 能力注册表 —— 新增模态（如视频生成）= 新增 capability 包，向 ctx.auxiliary 注册元数据并订阅自己的绑定快照，核心包与设置页零改动
- 🌍 中英文双语 设置界面

📋 环境要求

| 依赖 | 版本 |
| DeepSeek Harness | 0.1.1-rc.2（Developer Preview；后续 Harness 版本将单独验证） |
| 操作系统 | Windows / macOS / Linux |
| Node.js | ≥ 22.19 |
| pnpm | ≥ 11 |

🏗️ 架构

packages/
├── auxiliary/
│ ├── aux-core/ # @carlmarkswx/dsh-aux-core —— ctx.auxiliary：能力元数据注册表 + │ │ # auxiliary 设置命名空间 + 绑定解析 + 快照通知 │ └── ui-aux-settings/ # 统一设置页（host: /auxiliary/* 同源路由；browser: 槽位列表 + 池） ├── vision/ │ ├── vision-service/ # ctx.vision 注册表与派发 │ ├── tool-vision/ # inspect_image + VisionToolController（activate/deactivate） │ └── vision-aux/ # capability 插件：HarnessVisionProvider（ctx.llm 路径） │ # + OpenAIVisionProvider（自定义端点）+ 自有 activation ├── imagen/ │ ├── imagen-service/ # ctx.imagen 注册表与派发 │ ├── tool-imagen/ # generate_image + ImagenToolController（activate/deactivate） │ ├── imagen-aux/ # capability 插件：OpenAI 图像 provider + 自有 activation │ └── ui-imagen/ # generate_image 工具行 + /imagen/attachment 同源路由 └── distribution/ └── suite/ # @carlmarkswx/dsh-multimodel —— npm 用户安装单元

auxiliary 命名空间形状（类型化绑定）：

auxiliary:
customProviders: [ { id, name, apiUrl, apiKeyEnv, models[], defaultModel, enabled, headers[], defaultWidth, defaultHeight } ]
providerSecrets: # 独立密钥存储（role: secret，不随池数组替换丢失） my-vlm: sk-... bindings: # 能力槽位绑定（record —— 新模态零 schema 改动）
vision: { mode: harness-llm | custom-openai | disabled, ref: , model: "" }
imagen: { mode: custom-openai | disabled, ref: , model: "" }
capabilityOptions: # 能力专属选项（如 imagen 提示词长度上限）
imagen: { promptLimitEnabled: true, promptLimit: 2000 }

关键设计：

- Harness 路由经适配器派发：视觉的 harness-llm 绑定通过 ctx.llm.stream({provider, model, messages}) 调用，图片先经附件服务转为持久 ImageBlock 引用；适配器拥有协议、端点与凭据，本套件不读其他插件的 settings、不维护端点表
- 能力自有生命周期：aux-core 只解析绑定并推送快照（watchCapability，指纹去重）；各 capability 插件在自己的 fiber 中 reconcile——一个 activation disposer 同时拥有 provider 注册、服务开关与工具面，禁用即整体释放
- 绑定解析单一出口：resolveBinding(capabilityId, binding, ...) 返回按 transport 判别的绑定（harness-llm 无端点/凭据字段；custom-openai 携带端点与惰性密钥），各能力包只负责把它变成自己的 provider 实例
- 凭据惰性解析：自定义提供方的密钥在每次请求时解析（providerSecrets → 显式 apiKeyEnv），密钥轮换经指纹触发 provider 重建
- registry 扩展契约：ctx.vision / ctx.imagen 是多 provider 注册表——第三方插件可在运行时 register() 自己的 provider（无需设置页参与，按名派发）

🚀 安装

npm / Harness 直装（推荐）

这里的 dsh plugin add 和 Harness 插件安装机制是同一件事。--profile 不能省略：请把 web 换成你实际使用的 profile 名称。

已全局安装 dsh CLI
dsh plugin --profile web add @carlmarkswx/dsh-multimodel

没有全局命令时
npx @deepseek-ai/dsh plugin --profile web add @carlmarkswx/dsh-multimodel

套件包会从 npm 自动带入 9 个内部插件依赖，并通过 dsh.bundle 写入同一个 profile；用户不需要逐包安装。安装完成后重启 Harness，打开 设置 → 辅助模型。

更新和卸载：

dsh plugin --profile web update @carlmarkswx/dsh-multimodel
dsh plugin --profile web remove @carlmarkswx/dsh-multimodel

当前 DeepSeek Harness 仍是 Developer Preview。本版锁定并验证 0.1.1-rc.2；Harness 升级后若出现 peer dependency 或配置兼容错误，请先保留报错信息并提交 issue。

从 GitHub 源码安装（开发 / 离线备用）

源码安装需要完整的 DeepSeek Harness 源码检出，并且已在 Harness 目录执行过 pnpm install；安装器会复用其构建工具链。

git clone --depth 1 https://github.com/CarlMarkswx/deepseek-multimodel.git
cd deepseek-multimodel
node install-to-harness.cjs

Windows 用户也可以在克隆完成后直接双击仓库根目录的 一键安装.cmd。脚本会检查 Node.js、自动寻找 DeepSeek Harness；找到一个时直接安装，找到多个时显示编号供选择，并在结束后保留窗口显示结果。

不使用 Git 的用户可以从 GitHub Releases 下载 ZIP，完整解压后运行同一入口。安装完成后请保留该目录且不要移动它：当前 Harness profile 使用 link: 依赖引用这里的插件包。若确实要移动，请在新位置重新运行安装器。

命令行安装与 Windows 一键脚本执行的是同一个入口：

推荐：零参数一条龙安装。自动寻找 DeepSeek Harness；找到多个时列出并让用户选择。
node install-to-harness.cjs

无交互环境或希望固定目标时，也可设置一次环境变量或显式传入路径： Windows: set DEEPSEEK_HARNESS_PATH=D:\Tools\DeepSeek Harness macOS / Linux: export DEEPSEEK_HARNESS_PATH=~/code/deepseek-harness
node install-to-harness.cjs "D:\Tools\DeepSeek Harness"

一条龙 = 三个独立脚本按序组合（也可单独调用）：

1. scripts/migrate-legacy.cjs —— 一次性：旧 vision / imagen 设置段 → auxiliary 类型化绑定（备份 settings.yaml.bak），卸载旧插件；成功后可整脚本删除
2. scripts/dev-bootstrap.cjs —— 开发者：把构建工具链以链接方式接入本仓库 node_modules（不向 harness 检出复制任何文件）并构建全部内部包
3. scripts/install-suite.cjs —— 产品安装：一次 dsh plugin --profile web add packages/distribution/suite，内部包以普通依赖随行，--dump-config 验证组合配置；旧版逐包安装的 bundle 层会被自动清理

常用形态：

bash
node scripts/dev-bootstrap.cjs # 自动探测；只接线 + 构建，不动 profile
node scripts/install-suite.cjs --profile headless # 装入其它 profile
node scripts/install-suite.cjs --skip-build # 跳过构建，复用 lib/ 产物
node scripts/install-suite.cjs --uninstall # 卸载（一次 remove）
兼容旧入口：install-to-harness.cjs --build-only/--uninstall/--skip-* 仍然可用

构建/测试入口：pnpm build / pnpm test / pnpm clean（根递归执行；.bin 垫片由 dev-bootstrap 的 wire-bins 生成）。

然后启动 DeepSeek Harness（你平时的启动方式即可），打开 设置 → 辅助模型。

卸载： bash
node install-to-harness.cjs --uninstall

⚙️ 配置

打开 设置 → 辅助模型：

1. 能力槽位：视觉 / 图像生成各一行，显示当前生效绑定（“Harness 路由 · provider / model”）：
- [更改] → Harness LLM 路由（仅视觉；协议/凭据在“模型”页管理）/ 自定义提供方（从共享池选）/ 禁用
- 模型 pin 是可输入组合框：目录作建议，也可直接输入目录外 ID
- 图像生成槽位附带提示词长度上限开关
2. 自定义提供方池：OpenAI 兼容端点的共享池（添加/编辑/删除，探测模型目录、测试连接、独立密钥存储——已存密钥留空保持不变）

💬 使用

帮我看看 D:\photos\glasses.png 里的眼镜是什么品牌 # inspect_image（视觉）画一张日落海滩的照片，胶片质感 # generate_image（图像生成）先画一张……再用 inspect_image 检查是否符合要求 # 生成 + 视觉验证闭环

生成的图片双份持久化：Harness 附件存储（对话内预览）+ ~/DeepSeek-Imagen-Images/（可用 IMAGEN_OUTPUT_DIR 改目录；扩展名按实际格式）。

🔌 扩展新模态（如视频生成）

1. 新建 packages/video/video-service（ctx.video 注册表，继承 ProviderRegistryService）
2. 新建 packages/video/tool-video（generate_video 工具，controller 形态：activate/deactivate）
3. 新建 packages/video/video-aux（capability 插件）：ctx.auxiliary.registerCapability({ id, title, modes }) + ctx.auxiliary.watchCapability(id, reconcile)——在自己的 activation disposer 里同时挂载 provider、服务开关与工具面
4. 把三行 insert 加进 packages/distribution/suite/cordis.patch.yml，在 scripts/lib.cjs 的 PLUGIN_PACKAGES 注册构建项

设置页槽位与绑定 schema 自动生效（record 键控，零核心改动）。异步长任务（视频生成耗时）可接入 harness jobs 服务（v1 未实现，工具内直接 await 即可）。

⚠️ 已知限制

- 测试覆盖：aux-core（解析/归一化）、vision-aux（两种 provider）、imagen-aux、imagen-service 有单测；工具与 UI 行为依赖端到端验证
- 自定义提供方的 API Key 以 secret 角色存储于 ~/.dsh/settings.yaml 的 providerSecrets（不回传浏览器 wire；Harness 路由密钥完全由“模型”页/credentials 服务管理，本套件不经手）
- GitHub 源码安装使用 link: 依赖，源码目录不能随意移动；npm 安装使用预构建的 registry 包，不依赖本仓库或 Harness 源码检出
- 预览路由面向本机回环部署；若将 Harness 暴露到局域网，请自行评估风险

🔄 更新插件

npm 安装用户运行：
bash
dsh plugin --profile web update @carlmarkswx/dsh-multimodel

GitHub 安装用户在本仓库目录中运行： bash
git pull --ff-only
node install-to-harness.cjs

修改本仓库源码后，重跑 node install-to-harness.cjs（或 scripts/dev-bootstrap.cjs 后重启）即可——安装器会再次自动定位；迁移幂等跳过，构建幂等重装。

📄 许可证

MIT