dsh-codex-consult：为 DSH 代理提供按需的 Codex 专家意见

前言¶

DeepSeek Harness（DSH）的核心理念是「一切皆插件」。对于需要多模型交叉验证、代码评审与架构决策的场景，仅依赖单一模型家族容易陷入盲区。为 DSH 代理引入一个独立模型作为顾问，是低成本的风险对冲手段。但 naive 的集成往往在模型溯源、长流式响应中断与成本透明度上失败。dsh-codex-consult 插件通过验证模型实际返回、保障长流式响应的完整性、以及持久化调用记录与用量快照，让 DSH 代理可以按需调用 OpenAI Codex CLI 作为顾问。

插件定位¶

dsh-codex-consult 是一个 DSH 模型推理插件，由 Xantares330 维护。它为每个 DSH 代理提供三个工具：codex_consult、codex_quota 与 codex_calls。核心价值是在 DSH 代理工作流中，以低摩擦、可审计的方式调用 Codex CLI 获取第二意见，并确保调用链路可追溯与成本可控。

核心能力¶

插件提供三件工具：

codex_consult：发起 Codex 顾问请求。支持内联证据、验证实际返回的模型与推理强度、在调用前后快照用量、持久化调用日志。
codex_quota：读取 Codex 当前用量快照（5 小时窗口 + 周窗口），无需发起 API 请求。
codex_calls：查看近期顾问调用的状态、模型、耗时、验证结果与标签。

安装与启用¶

插件需要 DeepSeek Harness 的 tools 能力（测试版本 0.2.0-rc.*，@deepseek-ai/dsh-tools >= 0.1.5-rc.2）以及已安装并登录的 Codex CLI。DSH 自带运行时，无需额外安装 Node.js 22+。

A. 安装到指定 DSH 配置文件（本地挂载）¶

# 1. 将包放置在配置文件可解析的位置
$profile = "$env:USERPROFILE\.dsh\profiles\desktop"
New-Item -ItemType Junction -Path "$profile\node_modules\dsh-codex-consult" -Target "D:\path\to\dsh-codex-consult"

# 2. 在配置文件的补丁文件中挂载
#    %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml

- insert:
    - id: codex-consult
      name: dsh-codex-consult

重启 DSH（或重新加载该配置文件），该配置文件下的所有会话即可使用这三个工具。

通过 bundle 安装的包无需手动添加 insert 块；bundle 自带 cordis.patch.yml。

B. 作为 bundle 安装（推荐分发方式）¶

在配置文件的 package.json 中添加依赖与 bundle 列表：

{
  "dependencies": { "dsh-codex-consult": "^0.1.0" },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-codex-consult"]
    }
  }
}

C. 从 npm 安装（发布后）¶

dsh plugin --profile desktop add dsh-codex-consult

配置项¶

所有配置项位于插件节点 codex-consult 下，例如在配置补丁文件中：

- id: codex-consult
  config:
    codexPath: ""                                    # 留空则自动检测
    codexHome: ""                                    # 留空则使用 ~/.codex
    stateDir: ""                                     # 留空则使用 $DSH_HOME/codex-calls
    model: gpt-6-astra
    effort: high
    transport: https                                 # 在代理后推荐使用
    sandbox: read-only
    timeoutSec: 900
    maxAttempts: 3
    loadUserConfig: false
    requireModelVerification: true
    proxyUrl: http://127.0.0.1:7897
    keepCalls: 100
    quota:
      enabled: true
      warnOnly: true
      primaryMaxPercent: 90
      weeklyMaxPercent: 85

常用配置说明：

model / effort：默认为 gpt-6-astra / high；工具级覆盖亦支持。
transport：默认为 native；https 会在代理场景下提供更稳定的长流式传输。
sandbox：默认为 read-only；证据内联到提示，无需写入权限。
requireModelVerification：默认为 true；仅在 Codex 不写 rollout 日志时设为 false。
proxyUrl：留空则继承环境变量；需在代理服务运行时配置。
quota.warnOnly：默认为 true；设为 false 时用量超限将拒绝调用。

典型用法¶

任意 DSH 代理可直接调用工具。典型提示示例：

Review papers/phystwin/docs/06-report.md and the evidence in
research/.../render_metrics_20261021.txt. Are the conclusions supported?

Use codex_consult with evidenceFiles to review my final answer before I send it.

codex_quota          # 在昂贵评审前查看用量
codex_calls {limit:5} # 查看近期顾问调用记录

codex_consult 返回除完整回答外的元信息：

model / effort：请求值；modelVerified：来自 rollout 的验证结果。
elapsedSec、finalChars、token usage。
quotaBefore / quotaAfter（例如 5h 3% · weekly 22%）。
callDir / resultFile：本次调用的持久化记录目录与结果文件。

验证与用量快照机制¶

插件在 Codex 完成调用后，定位到对应线程的 rollout 文件（~/.codex/sessions/YYYY/MM/DD/rollout-*<thread>.jsonl），读取最后的 turn_context 事件，将其 model 与 effort 与请求比对。只有匹配时才标记为 ok（除非关闭验证）。

Codex 在 token_count 事件中记录 rate_limits。插件通过读取近期 rollout 文件获取用量快照，无需发起网络请求，因此 codex_quota 是无成本的。调用前可基于快照判断是否拒绝或警告，调用后记录用量差值。

安全说明¶

默认以 read-only 沙箱运行 Codex；非交互模式下传递 approval_policy="never"，避免等待审批。
证据以文本内联方式注入提示。提示与回答文件保存在调用目录下，可能包含敏感项目数据，需与普通附件同等对待。
插件仅启动用户已配置或安装的 Codex 可执行文件。

故障排查¶

现象	处理
`codex_not_found`	设置 `codexPath` 或 `CODEX_CLI_PATH`
`proxy_unavailable`	启动代理、修正 `proxyUrl` 或取消设置
`effective_model_or_effort_unverified`	检查用量，或在无法获取 rollout 日志时关闭验证
`usage_limit` / `capacity`	等待窗口、降级模型/effort，或使用 `codex_quota` 监控
长调用中断（约 2 分钟）	使用 `transport: https`，HTTPS 提供器会提升流空闲超时
`codex_config` 错误	`loadUserConfig: false` 保持调用隔离；仅在需要用户 MCP 服务器/配置时开启

适用场景与注意事项¶

适合需要多模型交叉验证、代码评审、架构决策与验收判定的 DSH 代理工作流。
插件以当前 DSH 进程的权限运行，安装前建议审查源码与许可证。
目录页与 GitHub 仓库分别提供插件索引与完整文档，社区目录为独立站点，与 DeepSeek/幻方无官方从属关系。

小结¶

dsh-codex-consult 通过在 DSH 代理中嵌入 Codex CLI 顾问能力，实现了可验证、可审计的第二意见流程。从模型溯源到长流式响应保障，再到用量快照与持久化日志，它填补了 naive 集成中的关键缺口。对于追求调用链路透明、成本可控与结果可信度的 DSH 开发者，这是一个务实且可落地的选择。

目录页：https://www.skillhub.cn/plugins/Xantares330/dsh-codex-consult
GitHub：https://github.com/Xantares330/dsh-codex-consult