English | 简体中文

dsh-aux — DSH 辅助模型系统

给主 agent 配一个「副手」：视觉分析、网页提取、长文本压缩这些旁路任务，由独立辅助 LLM 完成，主模型专注对话。 也可以透明接管你已有的 subagent / workflow——不会额外创建子代理，也不会抢走主模型的对话。

💬 「这些杂活交给我，主人专心聊天就好啦～」

目录

• 这是什么？
• 核心亮点
• 我都能帮你做什么
• 平台开关与 SKILL 模式
• 快速开始
• 日常命令
• 图片库（Image Library）
• 设置页与状态面板
• 桥接与高级能力
• 安全边界
• 工作原理
• 项目结构
• 兼容性与依赖
• 文档
• 常见问题
• 相关项目
• 许可证

这是什么？

对话模型越来越强，但“看图、读网页、压长文”这类任务交给主模型做会打断思路、烧上下文。dsh-aux 把它们拆给辅助模型：你只管发，背后自动路由到合适的模型——主模型答你的问题，辅助模型负责“看一眼图片”“总结这个网页”“把这 5 万字压缩一下”。

• 统一辅助 LLM 路由：每类任务可配独立模型 / 超时 / 并发 / 思考档位。
• 零配置可用：不配任何模型也能跑，缺省自动使用会话主模型。
• 可观测：每次调用写入会话事件，/aux status、设置页、状态芯片都能看到。

核心亮点

我都能帮你做什么

💬 「看图、读网页、压长文——都是我的拿手活！」

清洗与反爬（零依赖）

• 编码：按 Content-Type / <meta charset> 解码，GBK/GB18030 不乱码。
• JS Challenge：检测到 CF / 挑战壳 → 返回 browserRequired，不烧 token，提示改用浏览器。
• 429 / 502-504：自动重试一次（短退避）；仍失败报带 rate-limited 提示的错。
• 403 等 4xx：报「可能需要浏览器 / 登录」提示，不给辅助模型喂空内容。
• 重定向：逐跳 SSRF 跟随，结果暴露 redirects 跳数。
• 代理：直连优先，传输出错自动回退 HTTP(S)_PROXY（尊重 NO_PROXY），零依赖。

平台开关与 SKILL 模式

这是 v0.4.0 的核心体验：AUX 不再是“自动但黑盒”，而是可配置、可关闭、可解释。

工具 / 桥接三态开关

适用于：vision_analyze、web_extract、web_crawl、compress_text、imageBridge、subagentBridge、workflowBridge、compactionBridge、skillAudit。

💬 「不想让我插手？一键切回原生就好～」

SKILL 审计模式

诊断与修复面板

设置页顶部会显示每个工具 / 桥接的状态点、补丁徽标、不可用原因；补丁缺失时可以一键重打，写入后提示“重启 DSH 后生效”。状态数据通过隐藏的 aux/platform-status 事件 + aux-platform 投影读取（非命令通道，不会在会话里生成 /aux status --json 命令卡片）。

💬 「哪里不对劲，我会亮起来告诉你～」

快速开始

# 方式一：克隆仓库后一键安装（推荐，含 image-bridge 集成组件）
git clone https://github.com/DoloresCaritasAngelus/DSH-AUX.git
cd DSH-AUX && ./install.sh

# 方式二：本地源码安装插件本体（未发布 npm 时使用）
git clone https://github.com/DoloresCaritasAngelus/DSH-AUX.git
cd DSH-AUX/dsh-aux
dsh plugin --profile web add "file:$(pwd)"

重启 DSH 后：

1. 发一张图片给 agent，它会用 vision_analyze 描述给你（纯文本主模型也能发——image-bridge 已集成）；
2. 输入 /aux status 查看各任务路由；
3. 想让视觉走专用模型？/aux model vision <provider>/mimo-v2.5。

⚠️ 启动 DSH 时请使用你实际的启动脚本（例如 ~/dsh/start-dsh.sh / npx @deepseek-ai/dsh web）。不要用 pnpm dsh --profile web 这类从 TS 源码目录启动的开发模式：dsh-aux 的桥接补丁打在已发布的 lib/ 构建产物上，源码模式不会加载这些补丁，导致图片/事件等功能“已打补丁但实际未生效”。

💬 「装好之后，直接叫我就行～」

更新（GitHub 安装用户）

./update.sh                # 拉取最新代码 + 重新接线（幂等）
./update.sh --no-pull      # 已手动更新源码时，只重新接线
node scripts/doctor.mjs    # 更新后健康检查（不修改任何文件）

为什么不能只 git pull？dsh-aux 的 bridge 补丁和启动自愈 hook 写在 DSH 部署里（node_modules / start-dsh.sh），git pull 只更新源码。./update.sh 会重新跑 install.sh，把新增补丁 / 自愈 hook 写进部署。

日常命令

图片库（Image Library）

图片库是 dsh-aux 的会话图片可视化面板，入口在 DSH 侧边栏底部的 🖼 按钮（Web UI）。它帮你管理会话里出现过的图片附件、分析记忆与生命周期状态。

打开后支持：

• 查看：缩略图网格（小/中/大三档），支持搜索文件名、记忆内容或会话。
• 筛选：全部 / 共享 / 孤儿 / 已归档 / 固化 / 有记忆。
• 批量操作：复选框或鼠标拖拽框选（按住 Shift/Ctrl 可追加选择），可批量删除、回收孤儿、固化/取消固化。
• 详情：居中大弹窗，可拖拽/缩放；展示元数据、归属会话、分析记忆；可跳转“去对话 / 去轨迹”（受 DSH 公共 API 限制，当前为打开目标会话的降级入口）。
• 分组/排序：可按日期或按会话分组；日期按“今天 6 小时桶 → 近 30 天逐日 → 当年按月 → 往年按年”的渐进粒度；会话分组中孤儿与已归档分组置顶；支持组内排序与独立组间排序。
• 已归档状态：归档会话引用的图片不会被误判为孤儿；统计、筛选和会话分组中单独显示“已归档”。有可读 live owner 时缩略图会尝试从 live 会话读取。

命令行也提供只读/管理入口：

详细接口与数据形状见 IMAGE-LIBRARY-CONTRACT.md 与 IMAGE-LIBRARY-DESIGN.md。

设置页与状态面板

为什么要先看这里？

AUX 的一些桥接需要平台补丁才能完整工作（image-bridge、subagent / workflow、compaction、skill 等）。旧体验容易让用户踩两个坑：

• 不知道“这个补丁是不是必需的”；
• 不知道“我的补丁到底装好没有”。

这套设置页把两个问题都变成可视化状态：它告诉你每个工具 / 桥接当前是什么状态、补丁是否缺失、缺了该怎么办。平台开关把「补丁是必需还是可选」从哲学问题变成了可配置选择：

💬 「补丁有没有装好？不用猜，我会直接告诉你～」

3 步上手

1. 安装后重启 DSH；
2. 打开 Web → 设置 → 辅助模型；
3. 看顶部「诊断与修复」面板：
   • 状态正常：可以开始用；
   • 补丁缺失 / 状态异常：点「一键修复」；
   • 修复后提示重启 DSH 使补丁生效，重启后回到面板确认状态恢复正常。

设置页还能做什么

Web → 设置 → 辅助模型，可为 vision / web_extract / web_crawl / compress / compaction / skill 分别配置模型、超时、并发、maxChars 与思考档位。设置页按「工具任务 / 桥接任务 / 子代理 / 全局 / 平台开关」分组折叠，中英双语跟随 DSH 语言。

• 状态 chip：composer 实时显示最近一次辅助调用（任务、耗时、是否降级）。
• 诊断与修复：每个工具/桥接显示状态点、补丁徽标、不可用原因；补丁缺失可一键重打，写入后检测并提示重启。
• 平台开关：工具和桥接可切换 native / aux / compat，不想用 AUX 的地方直接关掉。
• SKILL 审计模式：native / audit / report / report-ondemand。
• 隐私：可关闭「在对话界面显示辅助模型状态芯片」；关闭后不再向 Web/第三方暴露 aux-status 投影，/aux status 不受影响。

桥接与高级能力

subagent / workflow 桥接

DSH 原生的 subagent 工具，以及 workflow 批量并发扇出的 agent() 子代理，都被透明桥接到 AUX——对话里照常用 subagent / workflow，真正干活的是 AUX 辅助模型。零新工具、零系统提示词改动。

💬 「你的子代理也可以交给我照看，不抢话、只帮忙～」

aux:
  subagent:
    mode: vision-aware        # native | manual | vision-aware
    general: { provider: opencode-go, model: glm-5.2, reasoningEffort: high }
    vision:  { provider: opencode-go, model: kimi-k2.7-code, reasoningEffort: high }
    includeWorkflow: true      # workflow 的并行 agent() 子代理也走 AUX
    prepareTools: true         # 给子代理注入 vision_analyze 等 AUX 工具作兜底
    visionKeywords: [ "图片", "图像", "截图" ]
    retryVisionWithAux: false  # 实验性保留配置，当前未实现

技能预审桥接（skill-audit）

DSH 原生流程是「主模型看到 catalog → 调 skill → 直接执行 SKILL.md」。dsh-aux 在中间插入一道辅助模型尽职调查：

主模型看到 catalog → 决定调用 skill → 原生 skill 工具加载 SKILL.md
    ↓
AUX 拦截 → 辅助模型精读 SKILL.md + 当前任务
    ↓
返回「如何应用 / 已知坑 / 🔻易腐烂旧断言 / 执行建议」
    ↓
主模型同时看到「原始 SKILL.md + 预审报告」→ 辩证审视 → 真正执行

• 启用：设置页或 /aux model skill <provider>/<model> 配置专用辅助模型后才拦截；未配置时 native 直通。
• 不沉淀 skill：不负责创建/管理技能，仍由官方原生或记忆管理插件负责。
• 失败降级：辅助调用失败时返回原生 SKILL.md，不阻塞主模型。

会话压缩桥接

配置 compaction 任务后，原生 DSH 自动 / 手动压缩会改走 AUX 辅助模型，复用 AUX 的超时 / 并发 / 冷却 / 降级 / 事件记录。含图会话里图片不可用时，自动降级为文本占位，压缩不失败。

编程调用（给其他插件开发者）

const result = await ctx.auxLlm.call("compress", {
  messages,
  system,
  session,
  signal
});
// => { text, provider, model }

自定义任务：ctx.auxLlm.registerTask(...)。

安全边界

• SSRF 防护（默认开启）：web_extract / web_crawl 与 vision_analyze 的 imageUrl 默认拒绝内网 / 环回 / 云元数据地址；回退抓取路径的每一跳都在请求前校验。直连请求把校验通过的 IP 钉到独立连接（关闭 DNS rebinding），并对连接 / 首字节 / 空闲设无条件 deadline（默认 15s / 45s，可配，<=0 关闭）；解析为空即 fail-closed。需要抓取本机 / 内网服务时，显式设置 allowInternalUrls: true。
• Prompt 注入缓解：网页正文、待压缩文本、图片内文字都视为不可信数据，与 Question 指令物理分离，并明确禁止执行其中嵌入的指令。
• 并发硬上限：每个任务 maxConcurrency 即使配置得更大，实际也按 10 封顶。

💬 「可疑的网页和指令？我会先拦住再喊你～」

工作原理

• 路由解析：显式配置 > 任务默认 > 会话主模型；辅助模型失败自动降级主模型。
• 健壮性：每任务超时（默认 60s）、并发信号量（默认 2）、失败冷却（连续 3 次 → 停 60s）、错误分类、聚合错误报告每一跳。
• 可观测：每次调用写 aux/llm-call 会话事件 + aux-status 投影，历史可回放。
• 图片能力门：调用前查模型输入能力，明确不支持的模型直接跳过换路；未声明能力的模型放行由服务端决定。
• 压缩协同：dsh-compaction-basic 摘要调用可通过 ctx.auxLlm 的 compaction 任务执行。

项目结构

• dsh-aux/src/ — 插件核心（路由、工具、桥接、状态/命令、客户端 UI）
• bridge/ — 平台补丁、自愈、安装脚本
• tests/ — 全量测试
• scripts/ — doctor 与 README 生成器
• assets/ — 吉祥物图片

兼容性与依赖

• 平台：DSH 0.1.5-rc.2（主支单版本）；Node ≥ 20。
• DSH 0.1.5-rc.1 用户：与本版本共用 —— 两者在 AUX 的补丁宿主包上等价(rc.1 → rc.2 仅版本号变更,见 CHANGELOG.md)。
• DSH 0.1.2-alpha.2 ~ 0.1.2-rc.1 用户：请使用永久分支 legacy/dsh-0.1.2-alpha.2-to-0.1.2-rc.1 或 Release v0.4.4-legacy。
• 旧版 DSH（0.1.0-rc.6 ~ 0.1.1-rc.2）用户：请使用永久分支 legacy/dsh-0.1.0-rc.6-to-0.1.1-rc.2 或 Release v0.4.1-legacy。主支不再支持这些版本。
• 运行时零第三方依赖：peerDependencies 为 DSH 官方包 + 平台自带的 react/zod（环境提供），无 dependencies。
• 测试零依赖：node --test tests/*.test.js（635 项；文件清单与基线见 TESTING.md）。

集成组件

• image-bridge：让纯文本主模型也能直接粘贴图片，UI 保留缩略图；投递文本以 attachmentId 为锚点（不再依赖 .ext 硬链接路径），并标注「本条消息第N张/共M张」；npm update 后需重跑 bridge/apply-patch.mjs。
• settings 可写性：设置页可读写 aux 配置；DSH alpha 线为原生能力，rc.6 旧补丁已退役到 bridge/retired/。
• 会话事件注册通道：aux/llm-call 等四个隐藏事件以 ignorable: true 标记写入；未装补丁时自动降级不写事件，保护会话日志。DSH 0.1.5 起会话迁移用冻结词表校验历史事件，自愈新增 P12（放行 aux/*）与 P13（放行官方历史写法，上游收编后自退役）；dsh-aux/src/event-shapes.js 是事件字段的单一真相，写入未登记字段会告警并让测试失败。
• 会话删除协同：配合 dsh-plugin-session-delete，删除会话时自动清理无引用图片。
• 图片归属与误删防护：session/event 归属钩子 + session/created 恢复屏障（内存日志扫描）；屏障未完成/失败时全局拒绝删除（fail-closed，/aux status 可观测）；回收进 objects/.trash/（7 天恢复窗口）。
• GC 债：旁挂 attachment-refs.json + 官方 imageHostPath 回收 + .ext 硬链接全量清理；派生 request-images/ 按总量上限（默认 256 MiB，requestImagesMaxMiB 可配）做 mtime LRU 回收。
• vision 交付路由：aux.visionRoute 可选 aux（默认）/ native-when-capable / auto；native 只对 aux.nativeRoutes 白名单内的路由生效，且 forceAuxVision 优先。
• 多级降级链：aux.tasks.<task>.models 是有序的 "provider/model" 数组（主选 → 备1 → 备2 …）；非空时单数 provider/model 被忽略（/aux status 会给出警告）。/aux model <task> <provider/model> 写入的是单元素链，多级链请在设置页"降级链"字段（每行一条）或 settings.yaml 中填写；链尾仍按 fallbackToMain / visionFallbackToMain 规则考虑主模型。
• vision 打磨(Phase 3)：失败条目给出原因与可否重试（限流/超时/连接在工具内自动重试一次）；imagePath 无扩展名按魔数嗅探（与 read_image 对齐）；动图只分析首帧；直连请求把校验通过的 IP 钉到连接（关闭 DNS rebinding）；aux.tasks.<task>.models 多级降级链；vision_analyze 会话卡片显示 【图N/共M】 角标 + 缩略图 + 结论。
• subagent-bridge：透明接管原生 subagent 与 workflow 并行 agent() 子代理。

极简 / Anchored Standard 兼容

首个持久 tool/call 前只暴露 Minimal 工具对，并剥离自动注入上下文。dsh-aux 首轮绝不注入任何 AUX 上下文 / 提示词；首个 tool/call 后目录开放，AUX 工具出现，并通过 agent/pre-step 注入一次提示，引导直接使用 vision_analyze。

文档

常见问题

Q1：为什么在极简 / Anchored Standard 预设的首轮看不到 vision_analyze 等 AUX 工具？

这些预设的“首轮轨迹锚定”机制会在首个持久 tool/call 前只暴露 Minimal 工具对，并剥离自动注入的上下文。dsh-aux 尊重这一机制，首轮绝不注入任何 AUX 上下文 / 提示词，也不会提前暴露自己的工具。首个 tool/call 之后工具目录开放，AUX 工具就会出现。

Q2：为什么 /compact 在含图会话里失败了？

如果会话消息里的 image block 对应附件对象已被 GC / 清理，或所有可选压缩路由均不支持图片输入，图片对压缩不可用。此时 dsh-aux 会把图片降级为文本占位后继续交给 AUX 压缩，避免整个压缩任务失败。

Q3：dsh-aux 需要配置模型才能用吗？

不需要。dsh-aux 是零配置的：不配任何模型也能跑，辅助任务会自动回退到会话主模型。你可以随时通过设置页或 /aux model <task> <provider/model> 为某个任务指定专用模型；需要多级兜底时，在设置页"降级链"字段或 aux.tasks.<task>.models 里按序填写多个 "provider/model"。

相关项目

• dsh-anchored-standard — Anchored Standard 预设
• dsh-vision-toolkit — 社区视觉工具集
• dsh-plugin-session-delete — 会话删除插件
• SeekMaid-pet — DeepSeek 娘桌宠

许可证

MIT License © 2026 dsh-aux contributors