顾问评审 NexusAgentX/dsh-advisor

dsh-advisor

一个移植 rpiv-advisor 机制的独立 dsh 插件组合包：按 agent 作用域注册零参数 advisor() 工具。主模型需要更强判断力时按需调用 advisor()；插件把完整推导会话历史 + 执行器工具清单转发给单独配置的评审模型，并使用 rpiv 原版 system prompt，返回的 plan / correction / stop signal 自由文本作为 tool result 回到当前回合。

一条命令即可安装：

dsh plugin --profile web add dsh-advisor # <name> = 你的 profile 名

按需调用，绝不自动旁观。 没有逐回合观察器、没有注入的 [advisor:] 消息，也没有按严重度路由的 runtime。主模型始终掌握控制权：它判断需要更强评审时调用 advisor()，并在继续之前消费返回结果。

安装

一条命令的 registry 安装

dsh plugin --profile web add dsh-advisor # <name> = 你的 profile 名

registry 安装拉取的是已发布的 tarball，其中自带构建产物（lib/ + cordis.patch.yml），因此不会运行 prepare 构建，也无需构建放行。运行时依赖（@deepseek-ai/cordis、@deepseek-ai/schemastery 与 @deepseek-ai/dsh- peers）声明为 peerDependencies，由 dsh 安装的扁平 profile module fallback 解析——无需额外安装步骤。需要可复现安装时用 dsh-advisor@0.1.3 钉住精确版本。

本地目录安装（推荐用于开发 / 验证）

pnpm install # 构建组合包（prepare 自建）
dsh plugin --profile web add . # <name> = 你的 profile 名

验证

dsh --profile web --dump-config # 显示带 advisor 配置行的 "# == dsh-advisor" 层
dsh --profile web

tarball 安装与卸载见 docs/install.zh.md。

配置

dsh web Settings（"插件配置"）页上的 Advisor 卡片

advisor 默认关闭。启用后，provider 与 model 为必填：enabled: true 而缺少两者之一是一个硬门禁 —— 任何 agent 都不会注册 advisor 工具，并报告带原因的禁用状态（disabled-with-reason）。未知配置键会被拒绝。

配置在三个配置面之间合成（后一层覆盖前一层；各处使用同一组键）：

1. 插件行 config —— $DSH_HOME/profiles/web/cordis.patch.yml（见下）。这是合成 base。
2. dsh web Settings 页 —— "插件配置"页 —— Advisor 卡片（id advisor，渲染在三张上游卡片 bash / agent-loop / web-search 之后），含 enabled 开关、只列出系统内已配置 provider 及其模型的 provider/model 选择框、由所选模型 catalog 元数据驱动的 reasoning-effort 下拉，以及 system prompt 覆盖。保存写入 advisor settings namespace，覆盖插件行 config 而无需改动它。保存后立即生效，无需重启（运行时 live 读取合成值，当前会话也会同步）。需要当前版本的 dsh web 构建（其 web shell 声明了 settings.plugin.item 卡片 slot 并能加载 dsh.client 声明包）。卡片通过官方 GatewayService RPC 通道读写该命名空间（/api/advisor/get + /api/advisor/set，由宿主的 typertGateway claims——与 dsh 内建 goals 服务同一机制），该通道不受 settings 暴露白名单门控：进程内写入（ctx.settings.update）没有 exposed-namespace 检查。无需也不施加任何宿主补丁。
3. /advisor 指令 —— 按会话且临时：翻转的是会话级 override，从不修改持久化配置（见用法）。

两个持久化配置面共享同一个硬门禁：enabled: true 而 provider/model 为空时绝不发起模型调用（disabled-with-reason）。Settings 页还会在 enabled 且必填字段为空时阻止保存；宿主侧硬门禁始终是所有路径上的最后防线。guidance 与 disabledForModels 是完整配置键，随所有配置面流转；web 卡片当前在编辑卡片暴露字段时会保留它们。

插件行配置：

profiles/web/cordis.patch.yml — profile 的 user patch layer
- id: advisor
config:
enabled: true # 总开关（默认 false） provider: deepseek-official # enabled: true 时必填（非空） model: deepseek-v4-flash # enabled: true 时必填（非空） reasoningEffort: high # 可选；"" = auto（支持时 high） systemPrompt: "" # 可选；"" = rpiv 原版 advisor prompt guidance: # 可选的执行器提示词覆盖 promptSnippet: "开始实质工作前调用 advisor。"
promptGuidelines: ["宣布完成前再调用一次 advisor。"]
disabledForModels: [] # 可选的执行器黑名单；[] = 不屏蔽

| 键 | 类型 / 默认值 | 含义 |
| enabled | bool, false | 总开关。 |
| provider | string, optional | 供应商路由。enabled: true 时必须（非空）。 |
| model | string, optional | 模型 id。enabled: true 时必须（非空）。 |
| reasoningEffort | string, "" | "" = auto（顾问模型支持时使用 high）；或 minimal / low / medium / high / xhigh / max / off。不支持的档位会自动省略。 |
| systemPrompt | string, "" | 覆盖内置的 rpiv 原版 advisor prompt。"" = 内置。 |
| guidance | object, optional | 面向执行器的提示词覆盖：promptSnippet 和/或 promptGuidelines；只采用非空值，否则使用 rpiv 默认文案。 |
| disabledForModels | array, [] | 执行器黑名单。条目为 "provider/model" 或 { model: "provider/model", minEffort?: "minimal|low|medium|high|xhigh|max" }。被屏蔽的执行器看不到 advisor 工具。minEffort 只对分级档位排序——执行器为 off、或档位未设置/未知时永不触发阈值（rpiv fail-soft 契约）。 |

旧的自动评审键 immuneTurns / maxDeltaMessages 为 profile 升级兼容而接受但会被忽略：新机制没有冷却或 transcript 增量窗口。

用法

安装并启用后，每个符合条件的 agent 作用域都会获得 advisor 工具与 rpiv 提示词指南。用 /advisor 指令按会话控制它（组合了 command registry 时可用）：

/advisor 切换本会话的 advisor 工具 /advisor on 为本会话启用 advisor 工具 /advisor off 为本会话禁用 advisor 工具 /advisor status 显示模型、effort、工具可见性及门禁/黑名单原因

/advisor on|off|toggle 是会话级且临时的：它们翻转的是按会话的 override，从不修改持久化配置。启用一个 config 缺少 provider/model 的会话不会安装工具 —— /advisor status（以及 /advisor on 的回复）会显示门禁原因。执行器模型命中 disabledForModels 时同理。

当主模型判断需要评审者时，它调用：

advisor()

返回结果是顾问的自由文本 plan（计划）、correction（纠偏）或 stop signal（停止信号），作为普通 tool result。主模型留在当前回合读取指南并继续 —— 按 rpiv 指南，它会在下一条可见回复中复述关键建议。顾问模型不会被授予工具，也不会直接写入会话 transcript。

工作原理

插件维护 live 解析配置桥，并在 agent 作用域（agent.ctx）接线每个 agent：

1. agent/created 时，若硬门禁通过、会话 override 开启、执行器模型不在 disabledForModels 中，插件向该 agent 注册零参数 advisor 工具，以及 tool:advisor 系统提示词段（promptSnippet + promptGuidelines，默认使用 rpiv 文案）。关闭或被屏蔽的作用域没有任何工具与提示词文本。
2. 执行 advisor() 时，请求按工具清单在前、会话完整推导历史（session.deriveMessages()）在后构建；从尾部剥离正在进行的 advisor() 调用，并保证 user-role 结尾。
3. 副调用使用 ctx.llm.stream，采用单独配置的 provider/model、rpiv 原版 advisor system prompt（或配置的覆盖值）、不传 tools，并做能力门控的 reasoning effort（"" auto → 模型声明时传 high）。
4. 收集到的文本成为 tool result。预期失败 —— 无会话、会话关闭、硬门禁禁用、黑名单命中、调用中止、模型错误、空响应（重试一次）—— 都返回说明文本而非抛出，主模型总能在当前回合作出反应。
5. Settings 变更会 reconcile 所有 live agent（按需安装/卸载作用域工具）；guidance 文本通过 prompt-section provider 实时读取配置。/advisor 只改会话级 override。

限制与路线图

- 没有 Pi TUI 模型选择器 —— dsh 指令处理器只能返回文本，因此模型/effort 选择在 Settings 卡片与插件配置中完成。
- 无 advisor tools —— 评审者只是独立模型调用；它无法自行核验主张（与 rpiv 一致）。
- 无会话内 advisor 面板 —— "插件配置"设置页上的 Advisor 卡片是配置面，不是会话内视图。
- 无 transcript 持久化或成本统计 —— 无可恢复的 advisor 历史或成本可观测性。
- 无 secret 混淆 —— transcript 中的 secrets 可能到达顾问模型；请配置可信的评审模型。
- 不隔离不安全的 advisor 输出 —— 原版提示词只要求给指令性指导；主模型自己的 rpiv 指南要求它把建议当建议，但文本作为 tool output 返回。
- 每次调用都发送完整历史 —— deriveMessages() 是完整当前 surface；原版机制有意没有有界 delta 窗口。

开发

组合包在安装时自行构建：package.json 声明 "prepare": "pnpm build"，因此任何克隆都立即可构建。私有的 @deepseek-ai/* 运行时包只声明为 peerDependencies，开发期从 npm registry 解析（pnpm-workspace.yaml 的 autoInstallPeers: true + 用户级 registry 认证）；无需本地 dsh 源码树或链接农场。

pnpm install # registry deps + prepare 自建
pnpm test # vitest（单元 + 客户端 + 网关/settings 套件）
pnpm typecheck # tsc --noEmit (node) + tsc -p tsconfig.client.json --noEmit + tsc -p tsconfig.spec.json --noEmit
pnpm build # tsc -p tsconfig.build.json emit to lib/ + node scripts/build-client.mjs (client bundle)
pnpm pack # build + produce dsh-advisor-0.1.3.tgz

prepack 运行 pnpm build；prepare 只做构建，因此 pnpm pack 会构建两次（每个生命周期一次）——这是为保持 git 安装可构建而接受的取舍。pnpm build 会先清空 lib/（scripts/clean-lib.mjs），已删除的模块不会残留在 tarball 中。没有 postinstall 步骤：tarball 安装已带构建产物，完全跳过构建。

测试套件覆盖 rpiv-port 配置/门禁/黑名单、上下文裁剪、工具清单缓存、副调用 execute 契约、按 agent 注册、/advisor 指令、settings 桥与网关，以及 web 卡片 store/组件 bundle 契约。

文档

| 文档 | 内容 |
| docs/install.zh.md | 完整安装指南：git / tarball / 本地目录安装、web Settings 暴露、卸载、--dump-config 验证 |
| docs/configuration.md | 配置字段、硬门禁、按 agent 作用域接线、副调用行为、web 卡片行为 |
| docs/consumer-api.md | 包导出、网关服务、客户端入口、/advisor 指令 |
| docs/verification.md | 测试矩阵、typecheck/build 预期、真实环境验证 |

许可证

MIT