dsh-agent-router

使用指南

安装并重启后，在 DSH 的「设置 → Agent 路由」打开配置页。

1. 总览

• 顶部总开关：启用多模型路由（关闭后 route_agent 拒绝调用、统计暂停）
• 宿主面健康面板与徽章（v0.5.0 新增，位于总开关下方）：显示宿主版本、各宿主面健康状态（ok / degraded / missing）与最近宿主诊断事件——宿主升级导致某面不适配时直接可见「哪一面不可用、为什么」，不再是「某功能莫名失灵」而无从排查
• 四个分级分类卡片（v0.4.5 起全部默认折叠），点击标题展开/收起：
  • 预设 Agent（第一张，默认折叠）：按 DSH 预设粒度配置默认模型；预设卡内含生效诊断面板（生效/未生效可观测）
  • 专业 Agent（核心区，默认折叠）：维护自定义专业 agent
  • 多模态账号（默认折叠）：API Key 账号、ChatGPT 订阅登录、子代理（无头 CLI）与账号池
  • 统计信息（默认折叠）：分级用量明细——内含四张二级卡（预设 / 专业 Agent / 账号级 / 全局）
• 分类头实时显示摘要（预设数量、agent 数量、账号数量、调用统计），无需展开即可掌握概况

2. 预设 Agent 默认模型

「预设 Agent」卡片按 DSH 预设（governance / novel-writing 等宿主预设）为粒度配置默认模型：让不同预设的新会话默认落在不同模型上（例如 governance 用强推理模型、写作预设用便宜长文模型），无需每次新建会话手动切换。

• 添加：展开卡片 →「+ 添加预设配置」→ 统一模板内联表单——下拉选择宿主预设（自动列出宿主预设与信任级别；已配置的预设不再出现；损坏的预设标记不可选）→ 主 Agent 默认模型（服务商 + 模型）→ subagent 默认模型（服务商 + 模型，留空 = 继承主 Agent 模型）→ 添加
• 条目管理：每个预设一行摘要（预设 · 主模型 · subagent 模型/继承），点击展开编辑、删除；宿主侧已删除的预设其残留配置会提示「预设已不存在」，可删除清理
• 语义（事件驱动，打开即显示）：
  • 打开即显示：新开（或空白切换）某预设的会话时，对话框模型选择器立即显示该预设配置的默认模型——无需先发消息；空白会话切换预设时实时跟随新预设的配置，切到无配置的预设则回落 DSH 全局默认
  • 首条消息后锚定：发出第一条消息后，会话模型由请求日志锚定（宿主原生行为）——后续配置修改不再影响该会话
  • 手动选择即当前会话生效：会话内手动切换模型 = 宿主原生会话内选择，插件不监听、不干预、不打架
  • 主 Agent 默认模型：仅对空白会话生效——未发过消息（未开启过对话轮）；已运行会话（重启恢复的已产出对话）始终优先，不受配置影响；未设置 = 完全遵循 DSH 现行规则（零行为变化）
  • subagent 默认模型：该预设派生的 subagent 的默认模型；未设置时 subagent 跟随主 Agent 当前实际模型（含会话内手动切换后的模型，不固化为预设配置时的值）；显式指定模型的子代理（如插件专业 agent 委派、workflow 指定模型）不受影响
• 实现机制：模型跟随两个预设事件（agent 创建 / 空白切换），不介入会话过程（无请求流拦截，会话进行中零插件开销）；主会话显示播种借用宿主会话模型选择通路，其附带的全局默认写入立即自动写回恢复（瞬态毫秒级，通常不可感知）——恢复失败时自动重试一次，仍失败则在日志高声告警并提示手动改回原全局默认；多个播种事件并发到达时（宿主不等待事件监听器完成）按内部串行化队列依次执行，并发交错不会污染全局默认的写回恢复
• 已知行为披露：重启后重新打开从未发过消息的空白预设会话，同样会触发显示播种（宿主在恢复会话时也发出 agent 创建事件）——与「打开即显示」语义一致；已发过消息的会话不受影响（日志锚定）。全局默认模型（「设置 → 模型」）在播种成功且恢复正常的情况下保持不变；保存后热生效，无需重启。宿主发出预设事件后不等待播种完成（fire-and-forget）——播种按内部串行化队列依次处理（极小窗口内并发创建的多个会话各自正确播种、全局默认仍恢复正确），但会话创建后到播种完成前的毫秒级窗口内，首个请求可能短暂路由到全局默认模型，显示与实际路由随后自动一致（人手操作通常不可感知）

3. 专业 Agent 配置

每个 agent 卡片默认折叠为一行摘要（名称 / 类型 / 生效模型 / 简要用量），点击展开配置：

• 名称、类型：类型只是执行方式（chat 调远端模型 / agent 委派 DSH 子代理 / cli 无头 CLI 子代理 / image 图片生成 / speech 语音转写），不限制能力；能力标签才是自定义的调度契约（路由与 files 图片分发都按它判定）
• 服务商 / 模型：留空自动复用主 agent 模型；「发现模型」按钮可拉取服务商模型列表一键选用（cli 类型下模型字段作为 CLI 的 -m / --model 参数）
• cli 类型：执行方式切到 cli 后，从「子代理」下拉选择账号区已添加的 CLI 条目作为执行路径（未选择 = 旧形态内嵌命令，提示迁移）。卡片保留登录状态指示、模型覆盖字段（-m / --model，空 = CLI 默认模型）与底部「登录」按钮；命令、参数、登录、拉取模型与统计统一在「多模态账号 → 子代理」维护
• 能力说明：主 agent 据此判断何时调用该 agent
• 高级设置：推理强度、温度、最大输出、轮数、System prompt、工具白名单（agent 类型）；cli 类型高级设置仅保留能力标签与 System prompt（注入任务头部作角色设定）
• 操作：启用开关、保存、测试（cli 类型 = 登录状态检查）、删除；底部显示该 agent 的实时用量与 tokens 分布
• 列表末尾「+」用预设模板快速添加：视觉识别 / 图片生成 / 翻译 / 语音识别 / 视频生成 / 通用子 Agent（模板只是能力起点；Codex/Claude/Gemini 等 CLI 工具不是 agent 类别，而是任意 agent 在 cli 执行方式下可选的子代理路径）
• 对话框图片：启用带 image 能力标签的视觉类专业 agent（chat / agent / cli 类型）后，对话输入框出现「添加图片」按钮——选中图片进入原生附件栏随消息原生发送；图片保留在会话日志中原生显示，插件在 system 层注入路由提示，主 agent 按需调用 route_agent 交给视觉 agent 分析（includeImages 转发最近消息的图片，自动附带主会话最近上下文——截图是对话上下文的一部分，视觉 agent 结合上下文作答）。生成图片以缩略图显示在 route_agent 工具卡片里（点击查看原图），纯文本主模型全程不接触图片字节

4. 多模态账号配置

• API Key 账号：统一配置式添加——服务商 ID（openai / my-gateway / one-api 等）+ 接口类型（openai-completions / openai-responses / anthropic-messages）+ Base URL + API Key（本地部署可留空）+ 模型列表，填好即保存到共享模型列表；官方服务商、第三方中转与本地部署同一条路径
• ChatGPT 订阅登录（一级，正式通道）：ChatGPT 订阅经官方 Codex OAuth 通路一键授权登录（浏览器授权 → 凭据落盘 → 专业 agent 的「OAuth 账号」字段指向它即可调用）；需自行知悉并承担平台服务条款与账号风控风险
• 子代理（无头 CLI）：Codex / Claude Code / Gemini CLI 等 CLI 工具作为账号类条目统一管理——「＋」一键添加（预填命令与参数）或自定义；每卡配置命令/参数/超时/并发、登录状态与一键登录（弹出终端窗口完成 codex login 等并自动刷新）、拉取模型（CLI 无列表命令时回退常见模型清单）与用量统计；专业 Agent 的「执行方式 = cli」时从「子代理」下拉直接引用这些条目。Codex 沙箱参数按平台自适应：macOS/Linux 用 --sandbox workspace-write（产物如图片必须能写入工作区，read-only 会导致任务无法落盘），Windows 用 --sandbox danger-full-access——codex 的 Windows 沙箱实现无法启动 WindowsApps 目录下的 shell（报 CreateProcessAsUserW failed: 5/1920），每条命令都会在执行前失败并触发子代理反复重试、成倍浪费 token，关闭 OS 级沙箱后仍保留审批策略；参数留空即用该默认，自定义参数未显式指定 --sandbox 时也会按平台自动补齐；每次执行宿主都会注入重试纪律（同一失败最多重试 2 次即报告错误结束），避免子代理无限重试卡死任务
• 自定义提供方（＋ 自定义）：未集成的服务商、第三方中转与本地部署（Ollama / One-API / LM Studio 等）——填服务商 ID 与 Base URL 即复用模型添加基座注册到共享模型列表，模型列表留空时保存会自动从端点拉取并写入（拉取失败会提示手工填写模型 id），注册后也可用「发现模型」拉取端点模型；API Key 可留空（免鉴权本地服务）
• 高级扩展（默认折叠）：账号池收进折叠卡片（v0.3.2 起不再提供「OAuth 官方登录 / 粘贴 token」的添加与管理表单——官方 API 不提供 OAuth，该入口已移除）——
  • 账号池：多个已授权账号组成池，按健康优先 / 用量最低 / 轮询自动选号，单账号失败自动切换；agent 的「OAuth 账号」字段可指向池；池内账号行提供「删除账号」入口（删除条目与本机凭据，并从所有池移除引用——与「移除」仅移出本池区分）
  • 未入池的 OAuth 账号：历史配置中未加入任何账号池的 OAuth 账号（含旧版自定义 / 粘贴 token / 未知预设值账号）在折叠区以极简列表呈现，仅提供删除入口（清理凭据与条目）

5. 统计信息

• 四张二级卡（每卡统一三段：总用量 / 每日用量 / 实时 tokens 分布 + 最近调用记录）：
  • 预设统计：按 DSH 预设聚合，主 Agent / subagent 两口径分开计数
  • 专业 Agent 统计：每个专业 agent 一卡，外加「主模型」分组卡（主 agent 含 subagent 经插件通路的用量归组对账）
  • 账号级统计：按真实账号聚合（同一账号的多通路用量归并一卡——含包装路由与宿主官方路由），模型细分表与 tokens 分布展开查看
  • 全局统计：全局调用数 / 失败数 / 入出 tokens 汇总
• 计数口径：账号级调用数 = 请求口径（每次 LLM 请求恰记一条，覆盖全部路由形态）；token / 耗时 / 失败数 = 调用明细口径——插件自有流才有 token，直连 provider 端点无 token 上报时显示 0
• CSV 导出三级（agent / account / preset），一键清空统计，每 2 秒自动刷新

3. 专业 Agent 配置

每个 agent 卡片默认折叠为一行摘要（名称 / 类型 / 生效模型 / 简要用量），点击展开配置：

• 名称、类型：类型只是执行方式（chat 调远端模型 / agent 委派 DSH 子代理 / cli 无头 CLI 子代理 / image 图片生成 / speech 语音转写），不限制能力；能力标签才是自定义的调度契约（路由与 files 图片分发都按它判定）
• 服务商 / 模型：留空自动复用主 agent 模型；「发现模型」按钮可拉取服务商模型列表一键选用（cli 类型下模型字段作为 CLI 的 -m / --model 参数）
• cli 类型：执行方式切到 cli 后，从「子代理」下拉选择账号区已添加的 CLI 条目作为执行路径（未选择 = 旧形态内嵌命令，提示迁移）。卡片保留登录状态指示、模型覆盖字段（-m / --model，空 = CLI 默认模型）与底部「登录」按钮；命令、参数、登录、拉取模型与统计统一在「多模态账号 → 子代理」维护
• 能力说明：主 agent 据此判断何时调用该 agent
• 高级设置：推理强度、温度、最大输出、轮数、System prompt、工具白名单（agent 类型）；cli 类型高级设置仅保留能力标签与 System prompt（注入任务头部作角色设定）
• 操作：启用开关、保存、测试（cli 类型 = 登录状态检查）、删除；底部显示该 agent 的实时用量与 tokens 分布
• 列表末尾「+」用预设模板快速添加：视觉识别 / 图片生成 / 翻译 / 语音识别 / 视频生成 / 通用子 Agent（模板只是能力起点；Codex/Claude/Gemini 等 CLI 工具不是 agent 类别，而是任意 agent 在 cli 执行方式下可选的子代理路径）
• 对话框图片：启用带 image 能力标签的视觉类专业 agent（chat / agent / cli 类型）后，对话输入框出现「添加图片」按钮——选中图片进入原生附件栏随消息原生发送；图片保留在会话日志中原生显示，插件在 system 层注入路由提示，主 agent 按需调用 route_agent 交给视觉 agent 分析（includeImages 转发最近消息的图片，自动附带主会话最近上下文——截图是对话上下文的一部分，视觉 agent 结合上下文作答）。生成图片以缩略图显示在 route_agent 工具卡片里（点击查看原图），纯文本主模型全程不接触图片字节

4. 多模态账号配置

• API Key 账号：统一配置式添加——服务商 ID（openai / my-gateway / one-api 等）+ 接口类型（openai-completions / openai-responses / anthropic-messages）+ Base URL + API Key（本地部署可留空）+ 模型列表，填好即保存到共享模型列表；官方服务商、第三方中转与本地部署同一条路径
• ChatGPT 订阅登录（一级，正式通道）：ChatGPT 订阅经官方 Codex OAuth 通路一键授权登录（浏览器授权 → 凭据落盘 → 专业 agent 的「OAuth 账号」字段指向它即可调用）；需自行知悉并承担平台服务条款与账号风控风险
• 子代理（无头 CLI）：Codex / Claude Code / Gemini CLI 等 CLI 工具作为账号类条目统一管理——「＋」一键添加（预填命令与参数）或自定义；每卡配置命令/参数/超时/并发、登录状态与一键登录（弹出终端窗口完成 codex login 等并自动刷新）、拉取模型（CLI 无列表命令时回退常见模型清单）与用量统计；专业 Agent 的「执行方式 = cli」时从「子代理」下拉直接引用这些条目。Codex 沙箱参数按平台自适应：macOS/Linux 用 --sandbox workspace-write（产物如图片必须能写入工作区，read-only 会导致任务无法落盘），Windows 用 --sandbox danger-full-access——codex 的 Windows 沙箱实现无法启动 WindowsApps 目录下的 shell（报 CreateProcessAsUserW failed: 5/1920），每条命令都会在执行前失败并触发子代理反复重试、成倍浪费 token，关闭 OS 级沙箱后仍保留审批策略；参数留空即用该默认，自定义参数未显式指定 --sandbox 时也会按平台自动补齐；每次执行宿主都会注入重试纪律（同一失败最多重试 2 次即报告错误结束），避免子代理无限重试卡死任务
• 自定义提供方（＋ 自定义）：未集成的服务商、第三方中转与本地部署（Ollama / One-API / LM Studio 等）——填服务商 ID 与 Base URL 即复用模型添加基座注册到共享模型列表，模型列表留空时保存会自动从端点拉取并写入（拉取失败会提示手工填写模型 id），注册后也可用「发现模型」拉取端点模型；API Key 可留空（免鉴权本地服务）
• 高级扩展（默认折叠）：账号池收进折叠卡片（v0.3.2 起不再提供「OAuth 官方登录 / 粘贴 token」的添加与管理表单——官方 API 不提供 OAuth，该入口已移除）——
  • 账号池：多个已授权账号组成池，按健康优先 / 用量最低 / 轮询自动选号，单账号失败自动切换；agent 的「OAuth 账号」字段可指向池；池内账号行提供「删除账号」入口（删除条目与本机凭据，并从所有池移除引用——与「移除」仅移出本池区分）
  • 未入池的 OAuth 账号：历史配置中未加入任何账号池的 OAuth 账号（含旧版自定义 / 粘贴 token / 未知预设值账号）在折叠区以极简列表呈现，仅提供删除入口（清理凭据与条目）