前言¶

在 DeepSeek Harness（DSH）里用专家团（Agency）或 Agent Teams 时，子 agent 默认会继承主 agent 的模型路由。主会话和多个被委派的子代理往往挤在同一 provider 账号的额度队列里，容易出现 summon_experts 长时间无响应、像「卡死」一样的体验。社区插件 dsh-subagent-route-pin（维护者 tkaiz0406）的做法是：主 agent 继续走你原来的路由，被委派的子代理（专家团成员、Agent Teams 成员、单发子代理）走另一条可配置的 provider/model，两条额度队列互不阻塞。下面介绍它的机制、安装方式与使用时要注意的点。

这是什么¶

dsh-subagent-route-pin 是 DSH 的 host+client 插件，分类上属于「模型推理」类能力扩展。它注册包装 provider pinned-account、委托内置 spawn，在创建子 agent 前写入 agentOptions；主 agent 的路由不被改动。插件自带设置页「专家模型」，用下拉选择提供商、模型与推理强度，保存后写回 profile 补丁，下一次委派生效。

适用面按 provider 生效，不按专家名单枚举：只要子 agent 仍通过 config.provider 读路由，agency 里大量内置专家、自定义专家或后续升级新增的专家都会命中同一条钉住的路由。

核心功能¶

路由注入的两条路径¶

1. 单发子代理：走 provider.start()，包装 provider 直接生效。
2. 团队模式成员：不经过 provider.start()；插件在 subagents.startActivation()（当前契约）或旧名 startContinuable() 上挂钩子，把路由填进 request.agentOptions。可用 teamInjection: false 关闭团队注入。

overrideMemberRoute（默认开启）：Agent Teams 会先用 memberLlmProvider / memberModel 填好 agentOptions；若只补「空槽」，成员路由钉不住。开启时钉住的路由优先；关闭则尊重调用方已选路由，只补空槽。

零配置与失败行为¶

未配置路由，或路由指向当前不存在的 provider/model 时，子 agent 继承主 agent 模型，召唤不会因插件而失败（会打警告）。onPinFailure 默认为 fail：你在设置页选过模型却跑不起来时，委派直接报错，并在错误里说明哪条路由失败、原因与改法；设为 inherit 才允许回退。strict: true 会把「无效路由」从警告升级为硬错误。

autoWireAgency（默认开）：挂载时把 profile 里 agency-agents 行的 provider 补成 pinned-account（改前留 .bak-autowire-* 备份）；装完通常不必手改 YAML。

可观测与排障¶

• 每次委派结果写入 ~/.dsh/subagent-route-pin.last-run.json（pinned / failed 及原因）。
• 启动就绪记录：~/.dsh/subagent-route-pin.ready.json（含版本、生效路由 route、来源 routeSource、能力标志 capabilities 等）。
• 能力标志发布为 { teamInjection, enabled, seams, reason }，调用方可读团队注入是否可用、挂在哪条接缝上。
• 可选逐专家覆盖：~/.dsh/subagent-route-pin.json 的 experts 字段，优先级高于设置页。

路由优先级：experts[专家名] → 配置行（设置页 / cordis.patch.yml）→ 设置文件 default；配置行一旦有值，JSON 里的 default 会被盖住（就绪记录里用 settingsDefaultShadowed 标明）。

fallback: true（默认）时，钉住的路由在启动阶段起不来会按 README 表格重试继承路由或成员原路由；流式请求中途的 429/额度错误发生在 start() 返回之后，插件无法兜底。

附带：Agent Teams 本地面板¶

插件提供只读团队状态工具（读磁盘 .agent-teams/<team>/team.json，不连 DSH）。Agent Teams UI 入口仅在当前会话持有运行中团队时出现；面板可在任意项目查看阶段、待批准计划、成员与任务表。示例：

npm run teams -- --scan "D:/你的工作区父目录"
npm run teams:once -- --dir "D:/你的项目"
dsh-team-status --serve --port 7800

安装与启用¶

插件以当前 DSH 进程的权限运行；安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证。dsh plugin 需指定 profile 目录，通常需关闭沙箱或以同一用户在终端直接执行。

官方 README 给出的安装方式如下：

# 从 tarball
dsh plugin --profile desktop add "./dsh-subagent-route-pin-0.8.2.tgz"

# 从 npm（发布后）
dsh plugin --profile desktop add "dsh-subagent-route-pin"

# 从本地目录（开发调试，link 安装）
dsh plugin --profile desktop add "D:\\path\\to\\dsh-subagent-route-pin"

装完后 profile 的 cordis.patch.yml 会新增插件行（包内已自带 patch，一般无需手写）。provider 留空表示不钉路由，子 agent 继承主 agent：

- id: subagent-route-pin
  name: "dsh-subagent-route-pin"
  config:
    providerName: pinned-account
    baseProvider: spawn
    provider: deepseek-account
    model: deepseek-flash
    reasoningEffort: ''
    strict: false
    teamInjection: true
    overrideMemberRoute: true
    fallback: true

运行环境：Node.js >= 22。与 DSH / @deepseek-ai/dsh-tool-subagent 的 peer 范围见仓库兼容矩阵（当前文档写明在 0.2.0-rc.1 至 <0.4.0 区间验证与声明；>=0.4.0 未验证，插件管理器可能标异常）。

典型用法¶

真正要改的两处¶

想把子 agent 分到另一条车道，通常只需：

1. 钉住的路由 —— provider / model 指向账号里真实存在的组合；可在 设置 → 专家模型 点选保存（写回同一配置行）。
2. 专家团行的 provider —— 改为 pinned-account，否则专家不经过本插件。

专家团（agency-agents）¶

@michengai/dsh-agency-agents 默认走 spawn，需把其 provider 指到 pinned-account：

- id: agency-agents
  name: "@michengai/dsh-agency-agents"
  config:
    provider: pinned-account
    # 不要写 maxDepth —— 写了会强制单发阻塞引擎，召唤要等全部跑完

注意：profile patch 对插件 config 是整行替换，改 agency-agents 这一行时要一并保留 enabled、customExperts、enabledTeams 等原字段，否则会被清空。

README 说明：Agent Teams（@nanmicoder/dsh-agent-teams）使用自己的 memberModel / memberLlmProvider；与 agency 是两套路由，插件通过团队钩子与 overrideMemberRoute 处理成员侧，避免与 agency 路径混为一谈。

重启后验证¶

重启 DSH 后，可按 README 检查：

1. 设置 → 专家模型 页面出现，底部有「专家团引擎」提示。
2. 进程控制台（GUI 开发者控制台或终端 stdout）出现五条契约日志，例如 provider "pinned-account" delegates to "spawn"、team-mode hook installed on ctx.subagents.startActivation、capabilities {"teamInjection":"installed",...}、委派时的 team member label=… -> provider/model 等。正常启动日志不落盘到 ~/.dsh/logs/。
3. 本地可执行 npm run verify 或 npm run ready 对照 ~/.dsh/subagent-route-pin.ready.json。

适用场景与注意¶

适合谁：经常在 DSH 里委派专家团或 Agent Teams、希望主会话与子代理使用不同账号或模型、并需要设置页与就绪 JSON 排障的开发者。

注意：

• 插件路由按 provider 生效，不替代 Agent Teams 产品自身的成员模型配置语义；关闭 overrideMemberRoute 或 teamInjection 会改变团队侧行为，需对照 README 失败回退表理解。
• 社区目录 SkillHub 插件页 与 GitHub 为独立生态信息源，与 DeepSeek / 幻方无官方从属关系；安装与配置以仓库 README 为准。
• 当前 package 版本在就绪记录示例中为 0.8.3（tarball 示例文件名含 0.8.2）；升级 DSH 后若契约日志缺行，应优先怀疑上游接口变化，再查额度。

结尾¶

dsh-subagent-route-pin 把「主 agent 一条路由、委派子代理另一条路由」做成可配置、可观测的 DSH 插件：包装 provider、团队接缝注入、设置页与 last-run/ready JSON，并可选团队状态面板。进一步了解与 issue 反馈见 GitHub：tkaiz0406/dsh-subagent-route-pin，目录介绍见 SkillHub。