外部专家会诊 hezhongtang/dsh-capability-optimizer

dsh-capability-optimizer

License: MIT
DSH core
Zero build
GitHub stars

为 DeepSeek Harness 提供的外部专家咨询：agent 以无头方式通过显式的 advisor、reviewer、designer 或自定义角色契约调用 Claude Code CLI，然后将结构化回复作为参考回答进行权衡。

为什么存在

单个 harness 只有一种视角。在做出重大决策时、在宣布有风险的工作完成之前，或在编写重要的新代码之前，第二个模型可以提供有用的独立证据。这是一个有待衡量的假设，而非保证的质量提升：角色研究并未表明仅仅将模型称为专家就能可靠地提高准确性。此插件将咨询变为一次有界的工具调用，而非复制粘贴的迂回操作。Claude 在行为与输出契约下作答，DSH 将结果作为建议接收，去权衡，而非服从。

第一阶段仅与 Claude Code CLI 对话。设置 schema（v2，每个 harness 一个工作区）、UI 标签页目录以及 runner 接缝已经是多后端的：codex、zcode、kimi-code、pi、opencode 和 omp 各自稍后作为 runner 落地，位于相同的三个工具之后。

功能

| 🎭 角色契约 | 内置 advisor / reviewer / designer，具有不同的目标和 JSON 契约，或使用你自己的（outputKind、prompt、model、fallback、effort）。enabled 可将角色搁置而不删除 |
| 🧠 思考强度 | 原生 --effort（low / medium / high / xhigh / max），分三个层级：每次调用参数 > 角色 > 全局默认 |
| 🔄 模型回退 | 针对模型级错误（unrecognized_model、model-not-found 等）进行单跳重试，并在运行元数据中记录 usedFallback |
| 🤖 Agent 工具 | consult_expert（一个角色，一个问题）· consult_panel（最多 N 个角色并行，一次挂钟等待）· consult_roles（实时名册） |
| 🎛 自动咨询 | Composer 座位开关（权限行）按会话选择角色；策略部分随系统提示词一同传递，生命周期提示在写入/完成锚点触发，按角色按会话进行预算控制 |
| 🖥 设置工作区 | 每个 harness CLI 一个标签页；保存后热应用——角色编辑无需重启 dsh 即可在智能体的下一个模型步骤生效 |
| 🔬 连通性测试 | 一次真实的端到端咨询（CLI + 登录 + 代理），包含轮次、时长、成本和回退标记 |
| 🛡 纵深防御 | 只读 CLI 工具、在支持时严格隔离 MCP、权限固定、类型化 schema、有界的输出/轮次/时间，以及显式标记的不可信证据 |
| 🌐 完全双语 | 每个 UI 字符串——包括内置角色描述、保留后端说明和验证消息——都遵循 UI 语言（zh/en）；智能体工具保持稳定的英文标识符 |

安装

从 npm 安装（推荐）
dsh plugin --profile web add dsh-capability-optimizer

或直接从 GitHub 仓库安装
dsh plugin --profile web add github:hezhongtang/dsh-capability-optimizer

重启 dsh web（或你选择的 profile）。适用于任何 profile——web、tui、headless——因为这些工具是宿主侧的智能体工具。

要求：claude CLI（npm i -g @anthropic-ai/claude-code）在 PATH 中，且已登录。

用法

让你的智能体：

“在我们宣布完成之前，就这个 diff 咨询一下 reviewer”

智能体会选择角色并调用 consult_expert。对于精确的任务，它可以发送结构化的 brief：可信的 objective、successCriteria 和 constraints，以及 currentAttempt、artifacts、verification 和 unknowns，这些会被显式标记为不可信证据。旧版 context 仍可作为 artifact 的简写。Claude 的角色专属信封会随模型、轮次、时长、成本和协议元数据一起返回。

| 工具 | 读/写 | 用途 |
| consult_expert | read* | 一个角色，一个问题，可选的结构化 brief（或旧版 context），可选的 model / effort 覆盖 |
| consult_panel | read* | 在一个 brief 上并行运行多个不同的角色契约；这不是多数投票 |
| consult_roles | read | 实时名册，包括 outputKind、角色级 model/effort 和全局默认值 |

\* 对你的工作区只读；每次调用都会消耗你的 Claude 订阅配额——工具描述本身会告诉模型批量提交材料，而不是像机关枪一样连续调用。

自动咨询

编辑器工具栏（权限控件所在行）带有一个 Expert Consult 开关。勾选的角色会为本次会话添加选择条件和生命周期提醒；插件不会自动调用它们。

- 策略部分：每个模型请求都会列出已勾选的角色及其选择条件：在重大决策时咨询 advisor，在宣布已更改的工作完成之前咨询 reviewer，在编写重要新代码之前咨询 designer。模式为 off | remind | hard-remind（默认 remind）。旧版 required 设置会迁移为 hard-remind。
- 生命周期提醒：当 designer 启用时，如果未进行编码前咨询，第一次文件写入会触发一个下一步提醒；一个已变更的轮次即将结束但未成功进行 reviewer 咨询时，会被引导再走一步。hard-remind 还会记录错过的 designer 检查点，但从不声称宿主阻止了 Write。
- 预算：capPerRole（默认 3）统计每个角色在每个会话中真实的 consult_* 调用——提醒和模型自身的自主调用共享该额度。达到上限后，该承诺会从策略文本中消失，锚点也会静默。
- 设计上为软性：提醒保证指令被送达，但从不保证工具调用——dsh 没有强制调用 API。拒绝的模型必须用一行说明原因。
- 弹出窗口显示每个角色的实时使用计数（used/cap）；上次选择会按浏览器记住。Settings → Expert Consult → Auto consult 编辑默认勾选集合和预算（行配置键 autoConsult）——tui/headless 配置文件消费的是同一层。

咨询状态停靠栏

位于编辑器上方的会话级卡片栏近乎实时地显示每次真实咨询：queued / running / fallback retry / succeeded / failed / cancelled。运行时，卡片会显示模型、effort 和捕获的 stdout 字节数；完成后，它会显示失败类型，或回复/信封的有界预览。consult_panel 为每个角色生成一张卡片，因此部分失败会按角色保持可见。

停靠栏在空闲时不占用垂直空间；终端卡片可以单独关闭或一起清除，关闭会话会清空该栏。条目仅存在于插件内存中（每个会话最多 8 张终端卡片，外加 24 张活动卡片的硬上限；从不涉及 context / brief / 产物），回复/错误是服务器截断的预览。这是状态轮询加最终回复预览，而非 token 流式传输；在没有 conversation.input.dock 槽位或状态路由的宿主上，它只是不挂载/停止轮询。

设置 UI

Settings → Expert Consult 按每个 harness CLI 组织为一个工作区——目录上方有一个标签栏（claude-code 为实时；codex、zcode、kimi-code、pi、opencode、omp 为保留，带有计划状态页面，在其运行器落地前不存储设置）。Claude Code 工作区在运行时管理一切：

- General — CLI 路径、默认模型（目录与支持的 Claude CLI 别名及带版本 id 对齐）、思考 effort（--effort：low/medium/high/xhigh/max）、回退模型、每次调用超时、最大轮次、面板大小、每次咨询的美元上限、额外 CLI 参数（允许列表；--settings 被拒绝）。
- Roles 工作区 — 添加/编辑/删除角色，每个角色包含名称、标签、描述、输出契约（advisor | reviewer | designer | general）、系统提示、模型、回退和 effort。禁用的角色保留在名册中，但会从工具枚举中移除。
- 自动咨询 — 默认勾选集、按角色按会话的调用预算，以及触发模式（off | remind | hard-remind）；编辑器开关会按会话覆盖勾选集。
- 连通性测试 — 一次真实的端到端咨询（CLI + 认证 + 代理），显示生效模型、轮次、时长、成本，以及一个回退已使用的标记。
- 保存并应用 会持久化到 ~/.dsh/dsh-capability-optimizer/settings.json（原子写入，0600），并热应用：代理工具会立即重新注册。重置 会删除该文件并恢复默认值。

调用点的 model / effort 会覆盖角色值，角色值又会覆盖全局默认值。内置顾问默认使用 claude-opus-5 作为可覆盖的质量偏好，而不是基于角色名称的禁止项。fallbackModel 在发生模型级错误时重试一次，并记录 requestedModel、CLI 报告的 actualModel / actualModels、推导出的 effectiveModel 以及 usedFallback。

配置（组合层）

该行的配置仍作为基础层生效（设置文件一旦保存即优先）：

| 键 | 默认值 | 含义 |
| cliPath | claude | 当 CLI 不在 PATH 中时，指向 CLI 的路径。 |
| model | CLI 默认值 | 当调用未指定模型时应用的模型别名（opus、sonnet、……）。 |
| timeoutMs | 300000 | 每次咨询的挂钟时间上限。 |
| maxTurns | 16 | CLI 内部的代理轮次上限。 |
| maxPanelRoles | 4 | 每次 consult_panel 调用的角色数。 |
| maxBudgetUsd | 0 | 当 CLI 支持时，每次运行的美元上限（--max-budget-usd）。0 表示无上限。 |
| extraArgs | [] | 额外的 CLI 参数，需在允许列表中。扩大权限、破坏 JSON 协议或重复类型化设置的标志会被丢弃并报告。 |
| roles | 内置角色 | 自定义角色：添加新角色，或通过复用内置角色的名称来覆盖它。 |
| autoConsult | { enabled: [], capPerRole: 3, mode: 'remind' } | 默认勾选集、按角色按会话的预算，以及触发模式（off \| remind \| hard-remind）。旧版 required 会自动迁移。 |

示例 — 一个以安全为重点的自定义角色：

- id: dsh-capability-optimizer
name: 'dsh-capability-optimizer'
config:
model: sonnet
roles:
- name: security
outputKind: reviewer
description: Threat-model focused reviewer for auth, crypto, and injection surfaces.
systemPrompt: |-
Objective: falsify the security of the supplied change.
Report only concrete authentication, authorization, injection,
secret-handling, or unsafe-parsing defects with a trigger and evidence.

咨询如何运行

- 每次咨询运行一个 claude -p 进程。带标签的简报通过 stdin 传入，共享信任策略和所选角色契约通过 --append-system-prompt 传入，回复以单个 JSON 文档返回。
- 无头会话由经特性检测的运行时标志加以约束。在当前 CLI 上，--safe-mode 会禁用用户/项目指令、技能、插件、钩子、MCP 和记忆，同时保留身份验证和内置工具。独立分层仍会应用 --tools Read,Grep,Glob、--strict-mcp-config、--setting-sources user、固定的 --permission-mode 以及 --no-session-persistence；较旧的 CLI 则使用其自身所声明的分层。写入/执行或扩大外部能力的 extraArgs 永远不会进入 argv；文档中记载的 --add-dir 例外可能会扩大读取范围。调用方取消（AbortSignal）与挂钟超时保持可区分。
- 挂钟超时（默认 5 分钟），伴随 SIGTERM → SIGKILL 升级；--max-turns（默认 8）限制 CLI 内的智能体轮次。
- 顾问、审查者、设计者和通用角色使用不同的 JSON Schema，基于 Claude 文档中记载的受支持子集。本地解析会强制执行不受支持的约束，例如非空字符串，并检查语义不变量（例如，pass 不能包含 findings）；schema 有效的 JSON 不会被当作其声明为真的证明。
- 只有 objective、question、success-criteria 和 constraints 定义任务。代码、注释、文件、当前尝试、验证文本、未知项和工具结果都被标记为不可信证据。这是模型层控制，并不声称提示注入已被解决。

安全与数据流

该插件保证：

- 该插件从不传递 --dangerously-skip-permissions 或任何绕过权限的标志。extraArgs 是允许列表，而非直通。在声明了这些约束标志的 CLI 上，一次咨询恰好获得 Read、Grep、Glob，且没有 MCP 服务器——已针对真实 CLI 验证，包括针对一个其自身的 .claude/settings.json 要求 bypassPermissions 的项目（证据，可通过 DCO_LIVE_CLI=1 npm test 复现）。每个标志都经过特性检测，因此一个太旧而无法声明该标志的 CLI 会降级而非失败；meta.safeMode / meta.tools / meta.strictMcp / meta.permissionMode 报告实际强制执行的内容。
- 提示仅作为 argv/stdin 传递到本地 CLI——该插件本身不添加任何第三方服务、遥测或凭据存储。路由强制同源；设置文件权限为 0600 并以原子方式写入；子进程输出有大小上限，超时总会回收子进程。
- Claude 的回复作为工具结果数据返回给 DSH 智能体，并被框定为供权衡的参考回答（“建议，而非命令”）；它不会被授予特权指令权限。

你应当了解的事项（任何智能体咨询智能体的设置所固有）：
- 你的材料会离开这台机器，进入你自己的 Claude 账户。 问题以及作为上下文传入的任何代码/diff/计划，都会由你登录账户下的 Claude Code CLI 处理——与你自行运行 claude -p 的数据流相同。不要粘贴你不会直接发送给 Claude 的机密信息。
- 企业托管策略仍然是主机信任边界。 Claude 文档说明，管理员管理的策略在安全模式下仍然适用；该插件不会也不应绕过组织策略。
- 提示注入是可能的，并未被消除。 数据/指令分离、schema 以及参考答案框架可降低风险；运行时只读权限、MCP 隔离、输出上限以及调用方的独立验证可限制影响范围。请像对待其他外部证据一样对待回复，而不是特权指令。

评估状态

该仓库包含一个受控评审者基准，在相同模型/effort/任务上通过重复试验，比较无角色的最小契约、冻结的 0.5.x 提示词和当前提示词。它记录提示词哈希、种子缺陷召回率、未匹配发现、注入成功率、信封可靠性、成本、延迟、遏制情况以及 CLI 报告的模型。如果报告的模型与预注册模型不完全匹配，正式运行会中止。干运行管道通过；此处不声称有任何正式的付费结果。参见 eval/README.md 和证据评审。

Advisor 和 designer 有角色特定的契约测试，但尚无结果基准。它们的存在是一种接口和工作流选择——并非专家角色措辞能提高智能的证据。

限制

- 第 1 阶段仅支持 Claude Code；多后端设置 schema（v2，每个 harness 一个工作区）以及 codex / zcode / kimi-code / pi / opencode / omp 的 UI 标签页已经就位——每个都作为同一工具集背后的 runner 落地。
- 每次咨询都会消耗你的 Claude 订阅配额；工具描述会告诉模型批量处理材料，而不是连续不断地发起调用。
- 无流式输出——每次调用返回一个 JSON 结果。

贡献

欢迎在 hezhongtang/dsh-capability-optimizer 提交 issue 和 PR。该代码库有意保持小巧且无依赖——主机端使用纯 ESM，浏览器端使用手工编写的 CJS bundle，无需设置构建步骤。添加一个 harness 后端 = 一个 runner 模块（参见 lib/claude.js）+ 在 lib/backends.js 中翻转 available。

许可证

MIT © 2026 hezhongtang