zhangqian98/dsh-escalation-advisor

dsh-escalation-advisor

DeepSeek Harness
Release
CI
Node.js
License: MIT

English · 简体中文

一个面向 DeepSeek Harness（DSH）的强模型顾问插件。主 Agent 可以继续使用速度更快、成本更低的模型，在遇到关键设计、连续失败或需要独立复核时，把结构化证据交给另一个 DSH 模型审阅。

Advisor 运行在可见的 DSH 子会话中，不是隐藏的 LLM 请求。你可以在任务树中查看它的完整对话、工具调用、token 用量和最终结论；Advisor 的消息也会像普通消息一样显示在主会话中。

主要能力

- 主模型可以主动调用 consult_advisor 请求独立意见。
- 自动升级模式会在确定性的失败/卡住信号达到阈值后请求 Advisor。
- 持续审阅模式会在自然轮次边界检查新增修改、失败、验证和结论。
- 全局设置和当前会话都可以选择 Advisor 模型及思考等级。
- 当前会话可以单独覆盖模式、等待策略、超时和工具权限。
- Advisor 使用独立的 advisor_verdict 工具提交结构化结论。
- 新咨询创建可续接子会话；显式传入 consultation_id 可以继续同一段 Advisor 对话。
- 主 Agent、普通本地子 Agent 和 Advisor 的权限边界彼此独立，不允许借 Advisor 提权。

安装

从 npm 安装（推荐）

把经过验证的精确版本安装到 Web profile，然后启动或重启 DSH：

dsh plugin --profile web add dsh-escalation-advisor@0.1.0-alpha.29
dsh web

如果你使用的 profile 不是 web，请替换成实际 profile 名，并在启动时继续使用同一个 profile。

从 GitHub 固定版本安装

也可以安装不可变的 GitHub release tag：

dsh plugin --profile web add github:zhangqian98/dsh-escalation-advisor#v0.1.0-alpha.29

不要使用移动的 alpha 标签来代替已经验证的精确版本；DSH prerelease 之间可能存在运行时契约变化。

从本地源码打包安装

开发版本应先构建、检查并生成 tarball，再让 DSH 安装 tarball。不要把源码目录直接链接进生产 profile。

npm ci
npm run check
npm pack
dsh plugin --profile web add ./dsh-escalation-advisor-0.1.0-alpha.29.tgz

兼容性

当前验证过的 DSH 版本：

- 0.1.2-rc.1
- 0.1.5-alpha.2
- 0.1.5-rc.1

开发依赖完整锁定在 0.1.5-alpha.2，CI 使用 Node.js 22.19 和 24。本机安装运行时测试还会把所有 DSH import 指向指定的真实安装版本，验证会话、工具、子 Agent 和 Remote 契约。

DSH 0.1.5-rc.1 的旧会话迁移

0.1.5-rc.1 会把旧 Session 格式迁移到 V3，但它的冻结历史事件清单不认识 Advisor 的四种插件事件。打开包含旧 Advisor 记录的会话前，请先停止 DSH 并备份 profile 与 sessions，然后运行包内维护脚本：

node scripts/patch-dsh-history.mjs /absolute/path/to/@deepseek-ai/dsh/package.json /absolute/path/to/new-backup-directory

脚本只支持精确的 DSH 0.1.5-rc.1，会校验原文件哈希并备份两个 DSH 核心文件，只加入以下四种事件：

- advisor/policy
- advisor/model
- advisor/identity
- advisor/run

其他未知历史事件仍会被拒绝。重新安装 DSH 会覆盖这个本地兼容补丁；更换 DSH 版本前必须重新验证，不能把旧补丁直接套到新版本。

三种模式

| 模式 | 行为 |
| --- | --- |
| manual | 只提供主动咨询工具，不自动调用 |
| escalate | 主动咨询 + 失败/卡住信号达到阈值后自动升级；默认模式 |
| continuous | 主动咨询 + 在自然轮次边界持续审阅新增工作 |

默认覆盖范围：

| 能力 | 主 Agent | 本地子 Agent |
| --- | --- | --- |
| 主动 consult_advisor | 开 | 开 |
| 自动升级 | 开 | 开 |
| 持续审阅 | 开 | 关 |

本地子 Agent 的持续审阅默认关闭，避免一个拥有大量 worker 的任务按 worker 数量放大强模型调用。如果显式开启，本地子 Agent 会等待 Advisor 完成后再结算，防止旧结果先返回父 Agent。

Advisor 子会话自身永远不能再次请求 Advisor，因此不会递归咨询。

模型与思考等级

在 设置 → 插件 → DSH Escalation Advisor 中选择全局默认 Advisor 模型。会话标题栏的 Advisor 面板可以为当前 root 任务树单独覆盖模型与思考等级。

模型选择器复用 DSH 主对话框的原生 ModelSelect、模型目录和能力数据。插件只保存 provider/model/effort 路由，不保存模型凭据，也不会修改主会话自己的模型。

选择“使用全局默认”会删除当前会话的模型覆盖；空思考等级使用该模型的默认值。

可见且可续接的 Advisor 会话

每个新咨询都会在精确的请求者下面创建一个可见、可续接的子会话：

Root
├─ Advisor · manual
└─ Worker A
└─ Advisor · escalation · turn 3

返回结果包含 consultation_id。后续主动咨询可以显式传入这个 ID，在同一个 Advisor 子会话中开始新轮次，从而保留此前上下文；省略 ID 总是创建独立咨询。

consultation_id: "last" 只会解析为当前请求 Agent、当前 root 任务最近一次已经成功交付的主动咨询。失败、仍在运行或自动触发的咨询不会改变它；兄弟 Agent 也不能借 last 访问别人的 Advisor 会话。

自动升级和持续审阅不会偷偷续接旧对话，它们始终创建新的独立咨询。

工具权限

出厂默认允许 Advisor 使用：

read
read_image
glob
grep
advisor_verdict

其中 advisor_verdict 是插件内部强制提供的结果通道，不受可配置工具列表影响。

默认不开放 edit、write、bash、pwsh、Web、浏览器、MCP、数据库及其他未知工具。可以在全局设置或当前会话的 Advisor 面板逐项开启；工具列表默认折叠。

当前 root 会话的配置只是上限。实际 Advisor 工具为：

root Advisor allowlist ∩ 请求者实际可见工具

因此，本地子 Agent 不能通过 Advisor 获得自己原本看不到的工具。

以下能力永久禁止，不可配置开启：

- consult_advisor
- subagent
- subagent_fork
- subagent_control
- workflow
- ralph
- 可信 Cordis 插件配置中声明的同类重命名工具
- capabilityAmplifierTools 中手动标记的自定义/MCP 派生工具

权限有两层执行保障：创建子会话时使用 DSH toolFilter.allow，每次真正执行工具时再由单调 tools.guard 检查原始权限上限、当前 root 策略和请求者当前可见面。提示词不是权限边界。

Advisor 使用原生工具 schema

即使主 Agent 使用 PTC，Advisor 子会话也会把自己的小型工具列表切换为原生 schema。主会话仍保持 PTC，但 Advisor 不再携带庞大的 run_code SDK，能够直接调用 read/glob/grep/advisor_verdict，同时继续受相同权限守卫约束。

输入和 token 控制

Advisor 使用所选模型在 DSH 中声明的上下文窗口和输出默认值。插件不再维护独立的 maxInputBytes 或 maxOutputTokens；旧配置会被忽略。

这不等于把整个主会话发送给 Advisor。case packet 只保留当前任务边界内的结构化证据，并做语义裁剪：

- 触发相关证据通过 validation identity 或 failure fingerprint 精确关联。
- 成功的 run_code 外层记录在已有具体 PTC 子调用时删除。
- 失败或未完成的 run_code 外层只保留短桥接摘要。
- 工具结果只在 tool_activity 保留一份。
- failures 与 validation 通过 call_id 引用活动，不重复命令和输出。
- 无关验证最多保留 3 条失败和 1 条成功。
- 失败列表最多保留 4 条。
- recent_tail 只保留最近的用户/助手对话框架，不重复工具结果，也不回填更早内容。
- 变更路径只从最终保留的活动生成。
- validation_summary 保存裁剪前的总数、成功数、失败数和相关数，不需要携带全部明细。

系统提示还要求 Advisor 优先检查触发相关 call reference，并在可行时把互不依赖的只读工具调用放在同一个模型步骤中，减少重复请求。

等待与超时

默认等待行为：

| 触发方式 | 主 Agent | 本地子 Agent |
| --- | --- | --- |
| 主动咨询 | 等待 | 等待 |
| 自动升级 | 可配置；默认等待 | 强制等待 |
| 持续审阅 | 可配置；默认后台 | 开启后强制等待 |

当前 root 会话可以覆盖自动升级和持续审阅的等待策略：inherit、block、background。面板只显示当前模式真正生效的等待选项。

全局默认咨询超时为 10 分钟，当前会话可以单独覆盖。支持范围为 1 秒到 60 分钟；内部配置字段仍使用毫秒。超时覆盖排队和生成的整个单次尝试，重试会获得新的完整时限。

只要 Advisor 启用了写入、执行或未知效果工具，审阅就会强制等待，并获取 root 任务树的独占工作区租约，避免主 Agent、worker 和 Advisor 同时修改同一工作区。

预算与并发

- maxManualConsultsPerSession：单 Agent 主动咨询上限，默认 -1（无限制）。
- maxAdvisorConsultsPerTask：整个 root 任务树共享上限，默认 -1（无限制）。
- maxConcurrentAdvisorRuns：同一 root 任务树并发 Advisor 数，默认 2。

负数表示无限制，0 表示完全禁止，正数表示明确上限。

排队期间取消、认证配置失败或模型请求尚未开始时会退还预留预算；已经发出模型请求的尝试会计入预算。自动咨询的瞬时失败最多重试一次，只有成功交付的 verdict 才会占用问题去重额度。

自动升级信号

每个 Agent 都有独立的升级跟踪器；worker 的失败不会增加 root 或兄弟 worker 的分数。

当前信号包括：

- 最终工具错误；
- 归一化后相同失败重复出现；
- 进程非零退出；
- 同一目标反复修改但没有成功验证。

取消、权限拒绝、基础设施故障、超时，以及搜索/条件判断中预期的非零结果不会计入“模型卡住”分数。匹配的成功验证只能清除对应失败，不能用无关 lint/test 抹掉其他问题。

每个 Advisor 运行都会记录 root/requester 任务 revision。新用户请求到来后，旧任务的后台结果只保留为 stale 审计记录，不会注入新任务。

验证义务

明确的验证失败还会创建运行时验证义务。升级分数重置、冷却期、预算耗尽、人工纠正或风险处置都不能关闭它；只有同一 scope 中、晚于最新失败、执行期间和之后没有相关修改的匹配成功验证才能关闭。

验证义务目前只保存在运行内存中。DSH 重启后，面板会显示“没有当前运行记录”，不会把空列表解释成全部通过。

Advisor 结果

Advisor 必须调用 advisor_verdict，普通文本不能代替 verdict。只有当子会话以 completed 关闭，并且 verdict 与对应轮次的结束边界一致时，结果才会发布。

结构化结果包含：

{
"severity": "none | nit | concern | blocker",
"disposition": "revise",
"summary": "...",
"diagnosis": "...",
"next_actions": ["..."],
"confidence": 0.9,
"evidence_used": [{ "kind": "file", "reference": "src/example.ts:10" }],
"assumptions": [],
"recommended_next_action": "运行聚焦验证",
"validation_plan": ["运行受影响测试"],
"needs_more_evidence": false,
"changes_made": []
}

none 不会打断主任务；nit 会等待自然的下一步再作为历史可选建议出现；concern 和 blocker 会要求请求者在完成前核验或修正。取消、超时、失败、缺少 verdict 或无法与结束边界对齐的运行不会伪装成成功审阅。

Advisor 消息会作为完整气泡显示在主对话中。标题栏面板的“咨询记录与回注”仍可查看触发来源、状态、模型、token 和历史报告，读取这些信息不会追加 Session 事件或调用模型。

外部子 Agent

本插件自动覆盖参加 DSH Agent/Tool 生命周期的本地 Agent。独立运行的 Codex、Claude Code、ACP 或其他外部 provider 不会自动获得 consult_advisor 和这些生命周期 hook；它们需要单独的桥接实现。

安全说明

- 模型认证由 DSH 管理，插件只保存模型路由 ID。
- 常见凭据格式会在证据进入 Advisor 提示前脱敏。
- 未知工具默认关闭，并按有修改风险处理。
- 权限在执行期再次检查，不依赖模型遵守提示词。
- Advisor 不能扩展 root 策略或请求者的可见工具面。
- Advisor 子会话不能派生新的执行 scope。

开发与打包

npm ci
npm run check
npm run build
npm run pack:check

npm run pack:check 会运行 prepack 构建并输出 npm tarball 清单，用于确认 lib、Web client、Cordis patch、迁移脚本、双语 README、设计文档和许可证都进入包中。

在 PowerShell 中使用本机已安装 DSH 运行兼容套件：

$env:DSH_RUNTIME_PACKAGE_JSON = "$env:APPDATA/npm/node_modules/@deepseek-ai/dsh/package.json"
npx vitest run --config vitest.runtime.config.ts

发布 tag 必须为 v，例如 v0.1.0-alpha.29。Release 工作流会校验 tag 与 package version、运行完整检查、生成 npm tarball、上传到 GitHub Release，并通过 npm Trusted Publishing（OIDC）发布到 npm 的 alpha dist-tag。工作流不保存长期 npm 发布 token。

许可证

MIT