dsh-advisor

dsh plugin --profile web add dsh-advisor

dsh-advisor

[English](README.md) | [中文](README.zh.md)




一个移植 omp「advisor」子系统的独立 dsh（DeepSeek Harness）插件组合包：一个按会话运行的独立评审模型，观察主会话 transcript，用显式配置的模型（provider 与 model 均为必填）评审每个已完成的 stepped turn，并把按严重度排序的建议（nit / concern / blocker）注入回会话。每个已完成的 turn 之后，它还可以预测你的下一提示，并以一键采纳的建议提示条显示在 web composer 下方（仅 web GUI）。两个能力面都不会污染主循环，也不会递归地评审自己。

仅作建议。 advisor 从不批准或否决主 agent 的动作，也绝不会像主 agent 那样发出命令。每条送达的消息都是自我描述的 advisory 内容；一个行为异常的评审者会被端到端约束（emission guard、immuneTurns 冷却、failure policy），因此它永远不会卡住或污染主循环。

两个 dsh 前端均可用：web profile（侧边栏 → 插件 → dsh-advisor → Advisor 卡片）与 dsh-tui 终端 profile（/advisor + /advisor config）。

快速开始

安装

Web / Desktop（「插件」页）

在 dsh web 客户端或桌面端，打开侧边栏的「插件」页，点「添加插件」，填入包名 dsh-advisor，点「安装」，再点「立即启用」。

dsh CLI

dsh plugin --profile web add dsh-advisor      # web profile（设置 → Advisor 卡片）
dsh plugin --profile dsh-tui add dsh-advisor  # dsh-tui 终端 profile

dsh plugin --profile web update dsh-advisor@latest   # 更新 —— 同一个 --profile 参数指定目标

同一个插件、两个前端——区别只在 --profile 参数。钉版本：加 @<version>（如 dsh-advisor@0.1.0）。registry 安装拉取的是已发布的 tarball，自带构建产物（lib/ + cordis.patch.yml）——目标机无需构建；运行时依赖（@deepseek-ai/cordis、@deepseek-ai/schemastery 与 @deepseek-ai/dsh-* peers）经 dsh 安装的扁平 profile module fallback 解析——无需额外安装步骤。registry / git / tarball / 本地目录变体（本地目录从已构建 checkout 安装：dsh plugin --profile web add . 或 dsh plugin --profile dsh-tui add .）、web Settings 暴露、卸载与 --dump-config 验证 → [docs/install.zh.md](docs/install.zh.md)。

配置

编辑 profile 补丁层（~/.dsh/profiles/<profile>/cordis.patch.yml）里 advisor 行的 config。九个字段全部是 schema-volatile 的 live 字段（dsh ≥ 0.1.7-rc.1）：web 卡片与 TUI /settings 屏幕写入的就是这同一份 entry config——持久化在 profile 补丁层，无需重挂载即生效。（pre-0.1.7 的 $DSH_HOME/settings.yaml advisor: 分节已不存在：dsh 会在首次启动时把它导入活跃 profile 一次，并将该文件改名为 .imported。）

破坏性变更（2026-09-26）：enabled 配置键已移除。 宿主 UI 中插件行的启用/停用开关就是总开关——插件行在运行即启用，无需任何配置键。存量 profile 若仍携带 enabled: 行继续正常工作：该行会被静默忽略（接受但剥离，永不读取、永不回写——2026-09-27 裁决，无需手工删除）；该键已废弃，写入路径不再持久化它。

# ~/.dsh/profiles/<profile>/cordis.patch.yml —— advisor 行的 config
- id: advisor
  config:
    provider: deepseek-official  # 必填（非空）
    model: deepseek-flash        # 必填（非空）；网关未开放 V41 路由时回退 deepseek-v4-flash（或其它 V4 id）
    systemPrompt: ""             # 可选；"" = 内置评审 prompt
    immuneTurns: 3               # 整数 ≥ 0，默认 3 —— 打断性送达后的冷却步数
    maxDeltaMessages: 60         # 整数 ≥ 0，默认 60 —— delta 窗口；0 = 无上限
    proseFallback: false         # 布尔，默认 false —— 无 JSON 帧时将散文回复作为 nit note 投递（opt-in）
    reasoningEffort: ""          # 可选；缺省/"" = 自动 —— 所选模型声明的最小思考权重（取值：该模型声明的 effort id）
    nextPrompt: true             # 布尔，默认 true —— 每个已完成 turn 后预测下一提示，并以提示条形式显示在 web composer 下方（仅 web GUI）
    defaultEnabled: true         # 布尔，默认 true —— 新会话默认开启；false = 按会话手动启用（用 /advisor on）

provider 与 model 为必填：任一缺失或为空是一个硬门禁——advisor 不会发起任何模型调用，并报告带原因的禁用状态（disabled-with-reason）；未知配置键会被拒绝。

没有模型侧 token 预算（2026-10-18 用户裁决）：OpenAI 兼容 API 上 max_tokens 把 reasoning 与正文一并计入，思考型模型下旧 maxTokens 预算会间歇性耗尽、正文为空（空回复 → EMPTY_RESPONSE → 静默丢 delta）。advisor 调用现在完全不发送 maxTokens；输出由抽取侧 ADVISOR_NOTE_MAX_CHARS（768 字符）封顶，延迟由 60s 调用 deadline 约束。存量 profile 里残留的 maxTokens: 行与已移除的 enabled 键同样被静默容忍并剥离。

若 advisor 已启用、runtime 状态正常却从不说话，请运行 /advisor status：非零的 Dropped: 行会指明类别——empty（空回复）表示模型返回了完成但无正文的响应；unparsed（无帧散文）表示正文不含 JSON 帧的回复被丢弃（开启 proseFallback，将清理后的散文作为低严重级 note 投递；JSON 帧始终优先）。详见 [docs/configuration.md](docs/configuration.md)。

同一组键可在三个配置面读取与编辑（只有一份存储——上面的 advisor entry config；各处使用同一个硬门禁，宿主侧门禁始终是所有路径上的最后防线；仅 web 可用的预测键刻意不进入 /advisor config 回读与 TUI 分节——它仅属于 web 配置面）：

1. 插件行 config —— profile 补丁层（~/.dsh/profiles/<profile>/cordis.patch.yml）。配置就存放在这里。

2. dsh web 的「插件」页 —— dsh-advisor 组合包自己的页面 —— Advisor 卡片（bundle key dsh-advisor），一个平铺的设置表单（页面标题/描述来自插件 locale 元数据），含只列出系统内已配置 provider 及其模型的 provider/model 选择框与可选字段。保存写入 advisor entry 的 config（经 config editor 落入 profile 补丁层），运行中的会话立即生效，无需重启。卡片要求 dsh web 构建的 shell 声明了 plugins.bundle.config 卡片 slot（dsh ≥ 0.1.7-rc.1）并能加载 dsh.client 声明包；它通过官方 GatewayService RPC 通道读写该配置（/api/advisor/get + /api/advisor/set），不受 settings 暴露白名单门控。卡片还会在必填字段为空时阻止保存。

3. /advisor 指令 —— 按会话且临时：翻转的是会话级 override、并为会话钉住评审模型，从不修改持久化配置（见[验证](#验证)）。

在 dsh-tui profile 中，七个键可在 TUI /settings 屏幕编辑：运行 dsh --profile dsh-tui、打开 /settings，编辑 Advisor 分节（provider / model / immuneTurns / maxDeltaMessages / proseFallback / defaultEnabled / reasoningEffort（留空 = 自动），每项均带中英文标签与提示）。编辑先暂存，保存时经 revision 栅栏保护的 settings.mutate 写入 web 卡片所写的同一份 advisor entry config，并 live 重应用、无需重启。systemPrompt 不是 TUI 字段（TUI text 控件为单行；多行 prompt 会被截断）——请经 web 卡片或 profile 补丁层编辑。该分节要求 dsh-tui ≥ v0.8.0（随 v0.8.0+ 组合包的 dsh-tui-settings-sections 行提供）；旧版 dsh-tui 会干净地 no-op，profile 补丁层仍是编辑路径。/advisor config 仍是只读回读，seam 挂载时其编辑提示指向 /settings 屏幕。保存行为与 web 卡片不同：TUI seam 没有跨字段校验，一次保存可能把空 provider/model 写入——显式模型门禁会在运行时把它解析为 disabled-with-reason（可见于 /advisor status 与 /advisor config）；web 卡片则会直接阻止这样的保存。完整参考 → [docs/configuration.md](docs/configuration.md)。

验证

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

安装并在插件页打开组件行的启用开关（row 开关即总开关）后，在会话内用 /advisor 指令控制它（组合了 command registry 时可用）：

/advisor            to

…(truncated)