dsh-routing-suite 安装与调优: 路由预设、验证和回滚

dsh-routing-suite 不是一个让模型“突然变聪明”的按钮。它做的是另一件事：根据任务类型调整 Agent 的工作方式。新建功能偏执行，维护、修复和审查偏分析，描述不清的任务留给模型自行判断。对已经在用 DeepSeek Harness 的人，这种路由能减少“该先检查却直接改”“该动手却一直规划”的错位。

但它也是典型的高级插件：会碰 profile、bundle、Agent preset 和运行时注入器。装错目录时，预设不会出现；重复写 loader id 时，DSH 可能直接启动失败；上游快速更新时，今天可用的安装链也可能在下一版变化。本文给的是一条有验证门槛的实操路径。任何一步不通过，都应该停在当前阶段，不要继续把插件装进常用 profile。

先给结论：当前适合把它放进隔离的 web-lab 或测试 profile，验证通过后再迁到日常 web。DeepSeek Harness 官方仍把自身标为 developer preview，并明确提示会出现破坏性变更。路由套装的仓库也把兼容范围写成 >=0.1.0-rc.6 <0.2.0。这两个边界都不能省略。

先理解三个组件

很多安装失败来自把“插件”和“预设”当成同一种东西。dsh-routing-suite 实际包含三层：

dsh-super-injector 是运行时管理层。它提供 dev_* 工具，用于注入、热重载、状态检查和卸载。
router-standard 是 Agent preset。它保留 Standard 的工具面，再按首个真实任务选择行为带。
router-spec 是更偏分析和计划的实验预设。它不是默认选择，也不适合所有实现任务。

Bundle 由 DSH 的插件装配机制加载；preset 则由 Agent preset 发现机制从 .agent-presets 目录读取。只装 bundle 不复制 preset，界面里不会出现 Router Standard。只复制 preset 不装注入器，路由可见性、自检和运行时管理能力又不完整。

如果你还不熟悉 Harness 的插件分层，先读站内的 DeepSeek Harness 插件管理器介绍、Cordis 内核与 AgentOS 结构和 DeepSeek Harness 开发指南。它们能补齐 profile、插件和 MCP 的基本关系。

安装前先做四项检查

1. 不在常用 profile 上首装

路由套装会改变提示词装配和阶段推进。第一次直接装进长期会话所在的 profile，出现问题时很难判断是模型、会话历史还是插件导致。更安全的做法是复制一个测试 profile，或者至少先备份 .dsh。

PowerShell 示例：

$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$source = Join-Path $HOME ".dsh"
$backup = Join-Path $HOME ".dsh-backup-$stamp"
Copy-Item $source $backup -Recurse
Write-Host "Backup: $backup"

备份必须在安装前完成。不要只备份 cordis.patch.yml，因为 bundle 清单、preset 和注入器注册表分布在不同目录。

2. 核对 Node、DSH 和 profile

node --version
dsh --version
dsh --profile web --dump-config

仓库声明 Node.js 至少为 22。--dump-config 的意义不是“看起来能跑”，而是确认你准备修改的 profile 正是当前 Web UI 使用的 profile。常见错误是插件装进 web，实际服务却用另一个 profile 启动。

3. 检查现有 loader id

打开 ~/.dsh/profiles/web/cordis.patch.yml，搜索 dsh-super-injector。同一个 id 只能出现一次。不要把官方装配、手工 patch 和旧版注入器三种方法混在一起。

4. 先读仓库状态，不盲信一行命令

本文写作时核对了仓库当前提交。node preset/router.test.mjs 的 26 个测试全部通过；node preset/router.integration.test.mjs 有 24 个测试，其中 23 个通过，1 个阶段推进断言失败。失败点是使用开发工具后阶段从 1 跳到 2，而用例期望仍为 1。

另外，仓库根目录声明的入口是 injector/lib/index.js，但当前 checkout 没有这个构建产物；npm pack --dry-run --ignore-scripts 列出的包也没有该入口和路由 preset。它不等于所有安装方式都会失败，但足以说明：当前不能把“一行安装命令返回 0”当作完成证据。你必须继续做 preset 布局、工具注册和行为验证。

推荐安装路径：clone 后运行安装脚本

仓库提供的 install.ps1 会依次处理注入器、两个 preset 和目录自检。相比只执行根目录的一行插件命令，这条路径更容易看清哪一层失败。

git clone https://github.com/yjh051108/dsh-routing-suite.git
Set-Location dsh-routing-suite
& (Join-Path (Get-Location) 'install.ps1')

脚本会尝试构建缺失的 injector/lib，然后把 router-standard 和 router-spec 分别复制到：

~/.dsh/.agent-presets/router-standard
~/.dsh/.agent-presets/router-spec

关键点是“平铺”。每个预设目录的第一层必须直接存在 agent.cordis.yml。下面这种多套一层的结构不会被 DSH 发现：

~/.dsh/.agent-presets/preset/router-standard/agent.cordis.yml

正确结构是：

~/.dsh/.agent-presets/router-standard/agent.cordis.yml

如果自动构建注入器失败，仓库建议改用 dsh-super-injector 的预构建 Release 包。不要在缺少 injector/lib/index.js 的情况下手写一个空 loader 行继续启动。

手动安装时只做两件事

自动脚本失败后，手动路径也应保持简单：先装注入器，再复制 preset。

$injector = Join-Path (Get-Location) 'injector'
dsh plugin --profile web add $injector

$presetRoot = Join-Path (Join-Path $HOME '.dsh') '.agent-presets'
$presetSource = Join-Path (Get-Location) 'preset'
Copy-Item -Recurse (Join-Path $presetSource 'router-standard') (Join-Path $presetRoot 'router-standard')
Copy-Item -Recurse (Join-Path $presetSource 'router-spec') (Join-Path $presetRoot 'router-spec')

复制前如果目标目录已存在，先比较内容，不要直接覆盖。旧版本的 agent.cordis.yml 与新版本的 bootstrap 文件混在一起，会产生比“完全没装”更难排查的半升级状态。

重启后的验证顺序

第一关：装配树能生成

dsh --profile web --dump-config

如果这里报 YAML、duplicate loader entry 或 entry not found，不要启动 Web 服务。先修配置。装配树是静态门槛，过不了就没有继续测试的意义。

第二关：注入器自检

启动测试 profile 后，新建空会话，依次调用：

dev_plugin_status
dev_self_test

dev_plugin_status 应显示注入器 active。dev_self_test 的八项检查都应通过。输出里的 [EXPECTED] 代表节流或坏代码预检被正确拦截，不是失败。

第三关：preset 是否真正可见

在新会话的模式菜单里确认存在 Router Standard 和 Router Spec。旧会话不适合验证首轮路由，因为路由需要捕获第一个真实用户任务。每种模式都必须用全新会话测试。

第四关：用三组任务做行为验证

不要问模型“路由生效了吗”，要给它可观察任务。

执行型：创建一个最小静态页面，并运行检查。 预期偏 react 行为。
维护型：先定位测试失败原因，只修根因并复跑。 预期偏 spec 行为。
模糊型：看看这个项目还能怎么改善。 预期进入 weak，由模型内部判断。

再用 dev_router_status 查看当前模式和阶段。不要只看最终答案是否顺眼；要检查第一轮是否正确分类、工具是否完整、计划模式边界是否保留、完成后是否停止继续发散。

Router Standard 与 Router Spec 怎么选

Router Standard 是日常默认候选。它按任务选择行为带，同时保留 Standard 的工具面。创建、实现、生成倾向执行；修复、诊断、审查和迁移倾向先检查。

Router Spec 更适合高风险维护、复杂迁移和需要明确规格的工作。它不应成为所有任务的默认值。小改动也强行走重规划，会把节奏拖慢。

一个实用规则是：

可逆、局部、结果容易验证的任务，用 Router Standard。
涉及数据迁移、权限边界、公开接口或跨模块契约的任务，用 Router Spec。
需求本身还没有收敛时，先保持 weak，不要为了“高级”强行指定模式。

想比较其他 Agent 的任务拆解方式，可以结合 AI Agent 工作流实战、Agent 上下文压缩修复和 AI 编程进阶工作流讨论一起看。路由的价值不是提示词更长，而是把任务类型、工具行为和验收门槛对齐。

三个常见故障

启动报 duplicate loader entry id

这是同一个 loader id 被写了两次。仓库提供了独立修复脚本：

$repairScript = Join-Path (Join-Path (Join-Path (Get-Location) 'injector') 'scripts') 'fix-patch.mjs'
node $repairScript --check
node $repairScript --profile web

先运行 --check。确认问题后再修复。脚本会备份原文件。不要用文本替换工具直接删除所有同名行，因为可能把有效配置一起删掉。

模式菜单没有 Router Standard

优先检查目录层级和文件名：

$dshHome = Join-Path $HOME '.dsh'
$presetRoot = Join-Path $dshHome '.agent-presets'
$presetFile = Join-Path (Join-Path $presetRoot 'router-standard') 'agent.cordis.yml'
Test-Path $presetFile

结果为 false 时，说明 preset 没有平铺到正确位置。结果为 true 但菜单仍没有时，确认重启的是同一个 DSH home 和 profile。

dev_* 工具不存在

检查 bundle 是否装进正确 profile、注入器构建产物是否存在、Web 服务是否完成重启。如果你使用了不同的 DSH_HOME，不要只查看默认的 ~/.dsh。

插件系统本身出现问题时，可参考 DeepSeek Harness 部署故障记录、DSH CLI 使用说明和 DeepSeek Provider 配置指南。

回滚必须能独立完成

回滚时先移除官方 bundle，再处理 preset 和遗留 patch：

dsh plugin --profile web remove @yjh051108/dsh-super-injector

$presetRoot = Join-Path (Join-Path $HOME '.dsh') '.agent-presets'
Remove-Item (Join-Path $presetRoot 'router-standard') -Recurse -Force
Remove-Item (Join-Path $presetRoot 'router-spec') -Recurse -Force

然后检查 cordis.patch.yml 是否还留有 dsh-super-injector 的 disabled 或重复行。重启后确认 dev_* 工具和两个 Router 模式都消失。最后再决定是否删除运行时注入注册表。不要在服务运行时直接删整个 .dsh。

安全边界

路由插件不是权限系统。它能引导 Agent 先检查或直接执行，但不能替代沙箱、审批和凭据隔离。即使 Router Spec 倾向谨慎，Agent 仍可能拥有文件、命令和网络工具。高风险任务必须继续使用真实权限边界。

建议同时阅读 AI Agent 最高权限风险、Agent 误赋全权限事故和 MCP 安全护栏 Conduct。提示词能改善行为，不能把不安全的执行环境变安全。

FAQ

可以直接装进生产 profile 吗？

不建议。当前仓库集成测试仍有一个阶段推进用例失败，根包产物也需要额外核对。先用测试 profile 验证，再决定是否迁移。

安装后每个旧会话都会自动路由吗？

不要这样假设。首轮分类依赖第一个真实用户任务，验证应使用新会话。旧会话还可能带有旧模式和阶段状态。

Router Standard 会减少工具吗？

仓库的设计目标是保留完整工具面，再按阶段给出行为引导。但运行时可见工具仍取决于 DSH 版本、profile 和权限配置，必须用 dev_router_status 与实际工具列表确认。

为什么不推荐只手改 cordis.patch.yml？

手工 patch 很容易产生重复 id、错误顶层结构和包解析失败。它只应作为底层救援方案，不是首选安装方式。

一手资料

dsh-routing-suite 的价值在于把 Agent 行为从“凭感觉切模式”变成可检查的路由流程。它当前也有清楚的工程风险。把备份、测试 profile、装配树、自检和回滚都做完，才算真正安装成功。