dsh-plugins/dsh-auxiliary

Banner

dsh-auxiliary

DeepSeek Harness 的辅助模型——为视觉、压缩、审查、子代理、标题和图像生成提供专用模型路由、工具和系统指导，而不触及主对话模型。

DSH Plugin

dsh-auxiliary 是一个 DeepSeek Harness 插件，它在 harness 的 LLM 接缝（ctx.llm）之上叠加辅助模型能力。它从不替换主对话模型：每个功能都是一条独立、可选的路由，仅在其自身狭窄的调用类别中生效，因此你可以为昂贵或专门的工作（视觉、压缩摘要、审批审查、委派的子代理、会话标题、图像生成）分配自己的廉价或强大的模型。

功能概览

| 功能 | 作用 | 配置位置 |
| --- | --- | --- |
| 视觉理解 | inspect_image 工具：读取本地图像并向视觉模型提问 | 模型页面 → 辅助模型 → 视觉理解 |
| 图像交接 | 聊天图像通过 describe_image 在纯文本主模型下得以保留 | 视觉理解卡片 → 图像交接 |
| 上下文压缩 | 摘要（purpose: 'compaction'）使用专用模型 | 辅助模型 → 上下文压缩 |
| 压缩引擎 （可选） | 用显式压缩提示词替换压缩后端 | 配置中的 engine.enabled |
| 审批模型 | 来自 @dsh-plugin/dsh-approve-for-me 的审查使用专用模型 | 辅助模型 → 审批模型 |
| 子代理模型 | 委派的子代理使用专用模型 | 辅助模型 → 子代理模型 |
| 标题模型 | 会话标题（purpose: 'session-title'）使用专用模型 | 辅助模型 → 标题模型 |
| 图像生成模型 | generate_image 工具：通过 OpenAI 兼容的图像 API 创建图像 | 辅助模型 → 图像生成模型 |
| 模型能力标记 | 你自己 llm-pi-ai 模型上的复选框：允许图像输入 / 允许图像生成 | 模型页面 → 提供商 → 自定义设置 → 模型 |
所有路由都在 设置 → 辅助模型 中配置（插件自带该设置区块），保存后立即生效——无需重启，也无需重建对话。

安装

复制下面的代码块，粘贴给你的 DSH 智能体（即此 Web GUI 中的助手）。智能体会替你完成安装和验证——无需手动操作 npm 或编辑配置文件：

Install the @dsh-plugin/dsh-auxiliary plugin into the profile I specify (or ask me if I didn't name one). The npm package name is @dsh-plugin/dsh-auxiliary; use the GitHub source github:dsh-plugins/dsh-auxiliary, or file: for local development.

Steps:
1. Add the plugin dependency: dsh plugin --profile  add @dsh-plugin/dsh-auxiliary (or the equivalent plugin-manager command for my profile). Since 0.4.1 the package is a bundle plugin (declares dsh.bundle.patch), so dsh plugin add also appends it to dsh.profile.bundles automatically — no manual cordis.patch.yml insert needed.
2. The package declares a prepack build script. If pnpm fails with ERR_PNPM_IGNORED_BUILDS, approve the build in the profile's pnpm-workspace.yaml (allowBuilds) and retry the add.
3. If this profile previously loaded the plugin through a manual insert row in cordis.patch.yml (pre-0.4.1 style), REMOVE that row — the bundle layer now mounts the plugin, and keeping both would mount it twice.
4. Verify node_modules/@dsh-plugin/dsh-auxiliary holds a built lib/ directory (at least lib/index.js and lib/client.js). If the build artifacts are missing, run npm run build in the plugin directory and re-add.
5. Do not start the profile — install and verify only, then report what you changed.

然后在 Web UI 中打开 设置 → 辅助模型 来配置路由，并在 设置 → 模型 中标记你想使用的模型。

功能详解

视觉理解与 inspect_image

先在 模型 页面配置一个提供商/模型，然后在 视觉理解 下选择该组合（保存为 vision.provider + vision.model）。tool.enabled 独立控制是否注册 inspect_image 工具。

vision:
provider: anvilcraft-ai     # any registered provider route
model: mimo-v2.5            # a vision-capable model on that provider
tool:
enabled: true               # register the inspect_image tool
maxImageBytes: 10485760     # per-file size cap
timeoutMs: 120000           # cooperative tool-call budget

启用后，让智能体对主机可读的路径运行 inspect_image：

Use inspect_image to analyze screenshots/error.png

该工具通过 ctx.attachments 接缝提交文件，并询问所选的视觉模型，返回文本答案（可选择在 vision.maxTokens 处截断）。支持 PNG、JPEG、WebP 和 GIF。
模型能力标记：对于用户配置的 llm-pi-ai 模型，模型设置中的 允许图像输入 复选框会写入其规范的 input 声明（勾选时为 [text, image]，清除时为 [text]）。inspect_image 和主聊天编辑器读取的是同一个能力事实。该声明无法为纯文本模型添加视觉能力——仅当上游端点实际接受图像时才勾选它。

图像交接（主模型为纯文本时的聊天图像）

当 图像交接（vision.handoff，默认开启）启用并选择了视觉路由时，图像传递以原生优先，并对未声明图像支持的路由安全回退：

1. 当交接处于活动状态时，ctx.llm.resolveModelInfo 上的运行时包装器会为纯文本主路由声明图像输入，从而使图像准入预检通过（模型目录和每模型复选框不受影响，因为它们直接读取设置文档）。配置的辅助视觉路由永远不会被夸大，因此 inspect_image/describe_image 仍会拒绝错误选择的纯文本视觉模型。
2. 对于每个包含图像的请求，官方 llm/stream 瀑布流上的监听器会通过原始能力解析器检查该确切请求的提供商/模型。具备图像能力的路由会原样接收原始的 ImageBlock。纯文本路由和未声明模态的路由会接收持久文本引用，例如 [image: {"attachmentId":…,"mediaType":…}]；工具结果中的嵌套图像也会被重写。
3. 系统提示会告诉纯文本主模型使用引用中的确切 JSON 调用 describe_image；该工具读取存储的附件字节，询问选定的视觉模型，并返回文本描述。

该重写是不可变的且请求局部的，因此并发的原生流和回退流不会相互影响；中止、错误、迭代器提前关闭和插件处置都会保留宿主流语义。引用是纯文本，因此可以在重启、分叉和重放后继续存在。两个接缝都在插件侧；不修改任何核心包。禁用 vision.handoff 可恢复原始的准入和流行为。

对具备视觉能力的主模型跳过注入

当 主模型支持图像时跳过（vision.skipWhenMainModelSupportsImage，默认关闭）启用时，主模型声明了图像输入的会话不会获得 inspect_image/describe_image 工具 schema，也不会获得视觉提示部分——模型会原生读取附加图像。此现有选项使用公共的通用提示组装上下文以及宿主的原始 resolveModelInfo（在交接包装器之前捕获）；工具仍保持注册状态，因此进行中或重放的调用仍会执行。
这与 image handoff 对 llm/stream 路由的精确检查有意分开。若要对每次尝试实现精确的 Auto / Always / Disabled 工具与提示词可见性，需要 Harness 核心将准备好的请求路由/能力连同请求生命周期的工具限制契约一并发布给提示词组装。该契约不属于已发布的公共 API，因此这个仅限插件的改动不会添加无效设置，也不依赖私有的 agent-loop 类型。

已发布的 llm/stream 契约还将 agent-loop 请求内容描述为只读。因此，本版本保留了插件原有的兼容性垫片，但使其具备能力感知且并发安全；完全一等公民的交接应随后跟进一个由核心拥有、会话记录的图像引用投影/准入钩子，这样插件就不必重新分发被重写的循环请求。

上下文压缩

每次摘要调用都携带官方的 GenerateOptions.purpose: 'compaction'。插件安装一个 llm/stream waterfall 监听器，将这些调用重新路由到配置的模型对：

compact:
enabled: true
provider: deepseek-official  # e.g. a cheap, fast summarizer
model: deepseek-chat

该监听器始终安装，并且在配置完整路由之前是纯直通。只有 purpose: 'compaction' 调用会被重新路由；主会话及其他所有调用类别均不受影响。

压缩引擎 （可选）：engine.enabled: true 会用 BasicCompactionEngine 子类替换原生的压缩后端，该子类通过显式的上下文压缩指令驱动摘要（参见 engine.compressPrompt）。它复用 compact 路由，不增加第三条模型路由。它与 @deepseek-ai/dsh-compaction-basic 互斥——插件会检测冲突并跳过该引擎，同时发出警告。

压缩阈值：Context compaction 卡片提供一个滑块以及一个精确的百分比输入（17%–99%）。保存阈值还会启用压缩引擎并写入 engine.thresholdRatio，因此一旦上下文使用率达到该百分比，压缩就会自动触发；阈值必须保持在保留比率（engine.retainRatio，默认 16%）之上。引擎会在每次压力检查前刷新策略，因此保存后无需重启。

审批模型（@dsh-plugin/dsh-approve-for-me 对接）

@dsh-plugin/dsh-approve-for-me 添加了 codex 风格的自动审批；在 review 模式下，一个轻量级审查模型会决定每个审批提示。Approval model 卡片为审查指定一个专用模型：

approve:
enabled: true
provider: anvilcraft-ai
model: mimo-v2.5

1. llm/stream waterfall 上的监听器通过其公共契约识别审查调用——用户消息中固定的 >>> APPROVAL REQUEST START 标记、无 sessionId，以及 temperature: 0——并将其重新路由到 approve.provider / approve.model。
2. 关于该调用的其他一切（策略、转录、超时、重试、回退）仍由 approve-for-me 拥有；只有模型路由被替换，且该判定永远不会进入会话历史。

仅当启用并配置了完整路由时，路由才会激活；未安装该插件时不会有任何审查调用，因此监听器处于惰性状态。需要 approve-for-me 的 mode: review 以及 approve-for-me 或 strict-review 权限预设。优先选择廉价、快速的模型。

设置页面会检测安装情况：该插件通过可选的 webServer 服务在 /dsh-auxiliary/state 提供一个只读 JSON 端点（{"approvePluginInstalled": true|false}），并且当实时 permissionPresets 表中缺少这些预设时，卡片会显示“插件未安装”提示并禁用编辑。该端点为本地回环，不返回任何敏感数据，并且在无头配置中不存在。

子代理模型

subagent:
enabled: true
provider: anvilcraft-ai
model: deepseek-chat

子代理默认继承其父代理的路由。启用此功能并配置完整路由后，每个被委派的子代理——一次性 spawn/fork 运行以及可继续的子代理，包括冷恢复的子代理——都会被路由到所选的一对。该插件监听 agent/created，并且对于委派深度 > 0 的代理，会在该代理自己的作用域上下文中安装一个 agent/request 瀑布监听器；返回一个替换用的 LlmCallConfig 是该循环官方的“切换”契约，因此更改后的头部快照会像任何其他模型切换一样被记录。远程提供方（ACP）从不注册进程本地代理，其子代理会继续继承父代理路由。优先选择廉价、快速的模型以控制委派成本。无需外部插件。

标题模型

title:
enabled: true
provider: anvilcraft-ai
model: deepseek-chat

会话标题由 dsh-session-title-llm 提供方发出，它有自己的部署级 provider/model 配置。启用此功能后，每个 purpose: 'session-title' 调用都会被重新路由到所选的一对，而提供方自身的配置和主会话路由保持不变。识别使用官方的 GenerateOptions.purpose 标记，因此它不会与代理循环、压缩或审批调用发生冲突。与压缩路由器一样，该监听器始终处于安装状态，并在配置完整路由之前一直放行。

图像生成模型和 generate_image

imagegen:
enabled: true
provider: lanqin-gpt          # 一个 OpenAI 兼容的提供方路由
model: gpt-image-2

harness LLM 接缝只支持文本，因此图像生成会直接与提供方的 OpenAI 兼容 images API 通信。启用此功能并配置完整路由后：

1. 注册 generate_image 工具，并且系统提示词部分会告知主模型在用户要求生成、绘制或创建图片时调用它。
2. 该工具从解析后的 llm-pi-ai 设置中读取提供方的 baseURL，并通过 harness 凭据接缝（ctx.credentials.resolve —— env/file/user-env 层）解析 apiKeyEnv，然后以 {model, prompt, size, n} 调用 POST {baseURL}/images/generations。
3. 返回的图像（base64 或 URL）会写入工作目录下（.dsh/generated/），并返回文件路径；主模型可以用 inspect_image 验证它们。

模型能力标记：选择器只列出标记了 Allow image generation 的模型——在模型的设置中勾选该复选框（它会将 imageGeneration: true 写入 llm-pi-ai 命名空间的原始用户区段）。只标记那些上游端点确实能生成图像的模型。

工作原理

该插件构建在标准 DSH 扩展点之上（参见插件开发指南）。harness 核心中的任何内容都未被修改。

┌─────────────────────────── Web settings ───────────────────────────┐
│ Settings → Auxiliary Models (settings.section slot)                │
│   └─ Feature cards: vision · compact · approve · subagent ·        │
│      title · imagegen  →  saveAuxFeature → namespace user section  │
│ Settings → Models (DOM injection via MutationObserver)             │
│   └─ Model catalog rows: Allow image input / Allow image           │
│      generation checkboxes → raw user section of llm-pi-ai         │
└────────────────────────────────────────────────────────────────────┘
│ reads (namespace.user / settings.get)
▼
┌─────────────────────────── Host plugin ────────────────────────────┐
│ config.ts: schemastery schema + resolvePluginConfig (paired checks)│
│ reconcile(): register/dispose per feature on config change        │
│                                                                     │
│  llm/stream waterfall listeners (purpose-keyed rerouting)          │
│    ├─ compact router   ← purpose: 'compaction'                     │
│    ├─ title router     ← purpose: 'session-title'                  │
│    └─ approve router   ← marker contract (no sessionId, temp 0)    │
│  agent/request waterfall on scoped child ctx (subagent router)     │
│  tools: inspect_image (vision) · describe_image (handoff)          │
│         generate_image (imagegen)  + systemPrompt.section(...)     │
│  resolveModelInfo wrapper + image→text-reference swap (handoff)    │
│  /dsh-auxiliary/state endpoint (approve plugin detection)          │
└────────────────────────────────────────────────────────────────────┘

1. 按用途键控的模型路由

所有文本路由都共享同一种模式：一次性安装一个 llm/stream waterfall 监听器（始终处于活动状态），检查调用，然后要么原样放行，要么使用冻结的替换配置重新进入接缝：
- 识别使用稳定的官方标记——GenerateOptions.purpose（'compaction' / 'session-title'）或审批调用的公开契约——因此每个路由器只能匹配其自身的调用类别。
- 重路由调用 deepFreeze({...options, provider, model}) 并重新进入 ctx.llm.stream()；provider/model 的替换是唯一的变化，因此超时、重试和回退仍由 harness 掌控。
- 循环保护：替换项携带相同的路由标记；对配置进行相等性检查可防止路由器匹配其自身的重入。
- 惰性：在完整路由存在之前，监听器是纯直通——之后启用该功能无需重新安装，禁用它除了移除监听器外无需任何清理。

2. 工具与系统引导

工具通过 ctx.tools.register(defineTool(...)) 注册，并通过 ctx.systemPrompt.section(...) 向模型公布：

- inspect_image —— 视觉理解：文件路径 + 可选问题 → 附件接缝 → 视觉路由 → 文本答案。
- describe_image —— 交接：从聊天中的 [image: …] 引用读取 JSON，并通过视觉路由作答。
- generate_image —— 图像生成：提示词（+size/n）→ 提供商图像 API（凭据接缝）→ .dsh/generated/ 下的 PNG 文件 → 路径。

每个工具仅在其功能启用且路由完整时才会注册（协调模式），因此模型永远不会看到无法使用的工具。

3. 设置集成与模型目录

该插件注册了自己的设置命名空间（dsh-auxiliary），并带有 schemastery schema；设置页面通过 settings.update(...) 写入，而 installSettingsSection 使插件解析后的视图保持同步。有两个细节很重要：

- 原始 vs 解析后：llm-pi-ai 命名空间中的模型行由 z.object schema 验证，该 schema 会从解析后的视图中剥离未知键，但不会抛出异常——因此像 imageGeneration 这样的非 schema 字段会保留在原始用户区段中。必须看到此类字段的读取通过 namespace.user（原始）进行；路由读取使用 settings.get()（解析后）。
- DOM 注入：模型目录页面由 harness 客户端拥有，因此插件观察 DOM（MutationObserver），并将 Allow image input / Allow image generation 复选框追加到每个用户拥有的模型行展开后的高级区域中。这些复选框从原始用户区段初始化；更改会保留在浏览器中，直到该提供商卡片关闭（在页面的 Apply 之后），然后写回原始用户区段，因此它们不会与页面自身的修订检查发生竞态。图像生成选择器将目录过滤为仅显示已标记的模型。

4. 凭据，而非明文环境变量
apiKeyEnv 值是 credential-ref，因此图像生成工具通过 ctx.credentials.resolve(credentialRef(...)) 解析密钥——harness 凭证接缝覆盖了 env/file/user-env 层，并在每次调用时重新解析（更改后的密钥无需重启即可到达下一次调用）。绝不使用 process.env。

5. 一切都能实时重新配置

每个功能都由一对 reconcile() + disposer 拥有：每次设置变更时，插件都会重新解析配置，并精确注册或释放那些条件发生变化的部件。在 Web UI 中保存路由会立即生效。

配置

所有字段均为可选；显示的是默认值。

- name: '@dsh-plugin/dsh-auxiliary'
config:
vision:
maxTokens: 2048                      # inspect_image output cap (provider/model written by the settings page)
handoff: true                        # text-only main models may reference chat images via describe_image
skipWhenMainModelSupportsImage: false # image-capable main models get no vision tools/prompt injected
tool:
enabled: true                        # register the inspect_image tool
maxImageBytes: 10485760              # per-file size cap
timeoutMs: 120000                    # cooperative tool-call budget
compact:
enabled: false                       # reroute compaction summaries to an auxiliary model
provider: ""                         # e.g. deepseek-official (a registered provider route id)
model: ""                            # e.g. deepseek-chat (a model id on that provider)
approve:
enabled: false                       # give @dsh-plugin/dsh-approve-for-me's reviews a dedicated model
provider: ""                         # e.g. deepseek-official (a registered provider route id)
model: ""                            # e.g. deepseek-chat (a model id on that provider)
subagent:
enabled: false                       # route delegated subagents to a dedicated model
provider: ""                         # e.g. deepseek-official
model: ""                            # e.g. deepseek-chat
title:
enabled: false                       # route session-title calls to a dedicated model
provider: ""                         # e.g. deepseek-official
model: ""                            # e.g. deepseek-chat
imagegen:
enabled: false                       # register generate_image with a dedicated image model
provider: ""                         # e.g. lanqin-gpt (an OpenAI-compatible provider route)
model: ""                            # e.g. gpt-image-2 (marked Allow image generation)
engine:
enabled: false                       # optional compression engine (mutually exclusive with dsh-compaction-basic)
thresholdRatio: 0.8
retainRatio: 0.16
maxTokens: 8192
compactionRetries: 1
maxOverflowRetries: 1
auto: true
compressPrompt: "..."                # 自定义压缩指令

设置页面：辅助模型

辅助模型设置页面

该插件附带一个 Web 设置部分（设置 → 辅助模型）。
先在 模型 页面配置提供商和模型，然后使用
此处的功能卡片：每张卡片都有自己的启用开关和提供商/模型
选择器。选择器会将当前所有可用的模型一起呈现，按提供商分组（图像生成卡片仅列出标记为 允许图像生成 的模型）。已保存但暂时不在目录中的路由会被保留，且绝不会被自动替换。

在目录中标记模型

对于用户配置的 llm-pi-ai 模型，请在
设置 → 模型 → 提供商 → 自定义设置 → 模型 → 模型
设置 下打开其模型设置：

- 允许图像输入 会写入规范的 input 声明（勾选时为 [text,
image]，清除时为 [text]）——由 inspect_image
和主聊天编辑器使用。仅当上游端点确实
接受图像时才启用。
- 允许图像生成 会写入 imageGeneration: true —— 这一标记
使该模型可在 图像生成模型 卡片中被选择。仅当上游端点确实生成图像时才启用。

这些复选框会被注入到每个用户拥有的 llm-pi-ai 模型行中，位于
与 上下文窗口 和 最大输出 token 数
字段相同的容量展开区域内，因此在该行折叠区域展开之前它们不会碍事。你在自定义提供商创建卡片中
添加 的模型也会获得可用的复选框；
在没有模型 id 的情况下添加的行会在该折叠区域内显示两个复选框均被禁用，直到输入 id；编辑现有模型 id 时，会将其已保存的
能力标记带到新的 id。更改后的标记会先在浏览器中记录，
并在页面保存提供商设置（应用）后写入，因此你可以同时编辑其他模型字段和图像能力，
而不会触发页面自身的“设置已在别处更改”修订冲突。无法携带这些标记的行会解释原因，而不是保持沉默：
DeepSeek-official（或任何非 pi-ai 适配器）行会显示一条通知，说明这些标记仅适用于 llm-pi-ai；而尚未保存到用户部分的
pi-ai 目录行则会提示先保存该模型。

同一折叠区域还会显示 thinking-level 配置：一个列表
用于添加/删除级别（仅限 off、minimal、low、medium、high、xhigh、
max），一个铅笔按钮可批量编辑诸如 [low, high, max] 的文本，并在任何条目无效时
拒绝整个输入，而默认 thinking 下拉菜单
仅提供列表中存在的级别。新模型以空列表
且无默认值开始。这些会读写官方模型 reasoningEfforts
字段（级别 → 同名 wire token，off → null）以及提供商级别的
reasoning 默认值——这正是 pi-ai 用来判断模型是否为
推理模型，并渲染作曲家的推理强度选择器，因此这个编辑器只是官方机制的创作界面，不拥有插件自有的存储。更改仍然只在提供者卡片 Apply 关闭后写入，因此它们永远不会与页面的修订检查发生竞争。

之前的版本将级别存储在插件自有的字段中（thinkingLevels
/ defaultThinkingLevel）；升级后的第一次保存会将它们迁移到
官方字段并删除旧字段。

注意事项

- 路由功能只重新路由它们自己的调用类别（purpose:
'compaction' / purpose: 'session-title' / 审批审查契约）；
主会话路由永远不会被触及。
- engine.enabled: true 替换原版压缩后端；不要同时加载
@deepseek-ai/dsh-compaction-basic。插件会检测到
冲突并跳过引擎，同时发出警告。
- 视觉工具参数：path（绝对路径或工作区相对路径）和可选的
question。支持的格式：PNG、JPEG、WebP、GIF。
- generate_image 参数：prompt（必填），可选的 size 和 n
（大多数提供者只接受 n: 1）。

开发
bash
npm install          # installs dependencies (typescript, @deepseek-ai/* peers)
npm run typecheck    # tsc --noEmit
npm test             # builds and runs the Node regression tests
npm run build        # emits lib/

许可证

LGPL-3.0