kui123456789/dsh-codex-workflow

dsh-codex-workflow

DeepSeek Harness 插件，为 Codex 赋予只读的规划/审查角色，而 DSH 仍是唯一的执行者。两个流程共享同一个工作流引擎：

- Codex 主导的桥接（首选）——生成计划的 Codex 任务通过持久化的 SQLite 桥接，将计划发送到确切的实时 DSH 会话；DSH 实现该计划，插件在将裁决返回给原始 DSH 会话之前，会把每一份可读的审计记录追加到同一个 Codex 任务中。
- DSH 主导的工具——DSH 代理可以针对复杂的开发任务自主启动 codex_workflow_start，或者由用户显式请求；实现和审查仍然通过同一个工作流引擎运行。

产品路径中任何地方都不会打开或控制浏览器；不涉及网络监听器、MCP、钩子或技能。浏览器点击仅是开发期的变通手段，不属于插件的一部分。

执行分工（1.0.14）

规划者回合继续使用 Codex App Server/Desktop。审查者回合、桥接回调、对账、规范化以及权限对齐均通过后端 codex exec CLI 运行。可见的 Markdown 审查会被追加到现有的工作流任务中；审计完成后，插件绝不会打开、刷新、导航或聚焦 Codex Desktop。

要求

- DeepSeek Harness 0.1.5-rc.1（最低支持版本；此版本更新了宿主 API 基线）
- Node.js ^22.19.0 或 >=24
- 具有有效 ChatGPT 登录和 App Server 支持的 Codex CLI（由 pnpm doctor 验证）

在 DSH 更新后升级

版本 1.0.14 面向 DSH 0.1.5-rc.1 及更新的兼容 0.1.x 版本。
较旧的 DSH 版本需要较旧的插件版本。源码安装必须使用
pnpm install --frozen-lockfile 刷新其本地依赖并重新构建；
仅升级宿主并不会更新已链接插件的 node_modules。

运行 pnpm host:check，使用安装在 $DSH_HOME/profiles 下的实际 DSH
核心包来加载和卸载已构建的插件。它会检查激活解析时全部八个
工具都存在，并在卸载时消失，使用临时存储和空的代理注册表。它不会重启实时配置文件或
执行模型调用。对于其他安装，请将
DSH_CODEX_HOST_PACKAGE_JSON 设置为其 @deepseek-ai/dsh/package.json 路径。
检查完成后，通过常规的由操作员控制的
DSH 配置文件重启来加载新构建；现有的工作流存储无需迁移。

安装

dsh plugin --profile web add dsh-codex-workflow

安装后重启 DSH web 配置文件。对于开发期间的
源码安装，请将本地项目目录传递给同一命令。

构建与验证

pnpm install
pnpm verify
pnpm doctor
pnpm run lifecycle:accept 针对一个真实的 Codex 登录运行真实的混合验收：Planner 保留在 App Server/Desktop 上，而可见的 Reviewer/reconciliation 轮次通过真实的 codex exec --json resume  - 运行，normalization/alignment 则通过独立的 codex exec --ephemeral --output-schema ... 会话运行。该门禁会记录实际生成的参数（通过 -m 配置的模型、通过 model_reasoning_effort 设置的可见 reviewer 工作量、ephemeral 工作量固定为 low），证明审查内容在原始任务上仍为可读的 Markdown，演练 DSH 主导/bridge/demo-smoke 权限流程，并断言 bridge Desktop 打开器被调用零次。DSH_CODEX_LIFECYCLE_MODEL、DSH_CODEX_LIFECYCLE_EFFORT 和 DSH_CODEX_LIFECYCLE_TIMEOUT_MS 控制真实验收，而不改变运行时默认值。

Codex 主导流程（首选）

从拥有该计划的 Codex 任务中，将其派发到实时 DSH 会话：

1. Find the live DSH session for this workspace
dsh-codex-workflow sessions --cwd $PWD --json

2. Dispatch the plan (payload enters through stdin, never arguments)
$payload = '{"task":"实现搜索功能","planMarkdown":"…","assumptions":[]}'
$payload | dsh-codex-workflow dispatch --cwd $PWD --codex-thread $env:CODEX_THREAD_ID --stdin

bridge 会解析出确切的会话（显式的 --dsh-session 优先；否则 cwd 必须与恰好一个实时会话匹配，存在歧义时会大声失败）。DSH 以插件中继消息的形式接收该计划并实现它。完成后，DSH 调用 codex_workflow_submit；插件以只读方式验证确切存储的 Codex 任务 id，并恢复同一任务以进行可读审计：

Planner/source Codex task --App Server--> readable plan
same visible task --codex exec --json resume--> visible Markdown review/reconciliation
independent CLI session --ephemeral --output-schema--> normalization/alignment JSON

首次成功的审查绑定会将 reviewerThreadId 持久化为与原始 Planner/source 任务相同的值；之后每次审查都会再次恢复它。已包含不同 reviewerThreadId 的旧记录始终优先使用该任务而非 codexThreadId，包括 writer release 和 callback persistence。可见 CLI 在配置时会接收 -m  和 -c model_reasoning_effort=""；模型为空时省略 -m 并使用 CLI 默认值。Active-writer/rate-limit 条件保持可重试，且绝不会创建替代任务。
持久化的工作流历史是人类可读的。 可见的 Planner/Reviewer 轮次从不携带 outputSchema：每次 CLI 审查都是可读的 Markdown（VERDICT / FINDINGS，含严重程度、blocking 和 file:line / TEST GAPS / SUMMARY），使用原始任务的语言。结构化规范化和权限对齐使用独立的 --ephemeral CLI 会话，采用相同的有效模型和 model_reasoning_effort="low"；它们从不使用 resume，从不进入 Desktop 历史，也从不将内部 id 持久化到 plannerThreadId、reviewerThreadId 或 codexThreadId。

每个审查轮次都携带自己的完整上下文——包括 Git。 DSH 主导、bridge 回调、首次审查和重新审查都复用现有的审查提示生成器。CLI stdin 包含工作流身份、原始任务、已批准的计划、PREVIOUS APPLIED REVIEW、当前修复摘要、实现摘要、变更文件、测试结果、有界证据、审查范围以及逐项权限门。Git 工作区需要独立的只读 git status/git diff；非 Git 工作区使用相同的契约，而不发明不同的 Reviewer 策略。

审查权限对齐（1.0.10）。 在可见审查被规范化为结构化裁决后，一个不可见的 ephemeral fork（相同的只读转换机制，低 effort）会根据权限层级检查每个 finding/test gap：1. 可复现的 critical/high 正确性/安全性/数据损坏缺陷（必须携带具体的 file:line + 失败场景证据）> 2. ORIGINAL TASK 及其显式约束（文件范围、精确测试数量、依赖限制、验收方法）> 3. APPROVED PLAN > 4. 先前应用的发现和当前修复摘要 > 5. 通用质量建议。普通的作用域/测试数量/验证方法冲突以计划为准解决：自动化测试、STATIC CHECKS 和 REAL COMMAND 验证都是需求的正式证据——Reviewer 不得再为任务/计划通过真实命令验证的行为要求自动化测试，也不得要求超出任务/计划显式边界的更改（带有可复现证据的 level-1 例外是唯一的覆盖）。Planner 契约与此对应：除非用户显式限制了数量，否则它绝不能将“tests cover A and B”强化为“exactly two tests”。

可见审查从 CLI JSONL 进行契约检查。 调度器提取最后一个完成的 agent_message，要求四个可读的 section 行和原始任务的语言，并且从不接受结构化 ReviewResult 信封作为可见输出。显示违规可以在同一任务上运行一次纠正性的可见 CLI resume。任何完成路径都不会调用 App Server thread/read、thread/fork、resumeThread 或任何 Desktop 导航/刷新 API；Markdown 已由 CLI resume 持久化，用户稍后可以检查该任务。
冲突从不让用户多付一次评审周期，也从不要求 DSH 改代码。 冲突不会覆盖 latestReview、递增 reviewCycles、进入 fixing，也不会发送修复指令。一次协调 CLI 恢复可能会在同一任务上重写完整裁决；其提示词包含针对每个非冲突发现/测试缺口的显式保留清单。确定性多重集检查会在重新对齐前拒绝删除、字段变更、重复计数漂移和无关新增。一次成功的更正作为一个业务周期应用；两次连续未解决的契约冲突会阻塞且不消耗周期。

评审者写者锁语义

在可见的 CLI 评审或协调之前，插件会为选定的可见任务（reviewerThreadId ?? codexThreadId）调用 thread/unsubscribe/写者释放。CLI 完成后，它只执行幂等清理：不重新订阅、不调用 resumeThread、不为展示而读取/分叉任务，也不调用 Desktop 打开器。评审保留在现有任务上；用户在方便时手动打开它。旧版打开器字段保持兼容，但 CLI 审计记录保留 desktopOpenState: "disabled"。

裁决如何返回（自动路径）

codex_workflow_submit 在提交和证据被持久存储后立即返回。随后，由管理器拥有的后端 CLI 评审会将可读的 Markdown 追加到选定的现有任务；短暂的 CLI 规范化/对齐会生成内部结构化结果。插件验证并暂存该裁决，将确定性的 submit_verdict 入队，桥接运行时将结果转发到原始 DSH 会话。CLI 子进程从不自行写入桥接队列。

评审运行期间不会注入周期性进度消息；codex_workflow_status 是按需查看进度的视图。忙碌和速率限制情况仍作为静默后台重试。无效任务 ID、缺少最终代理消息以及终端 CLI 进程失败会作为幂等的 submission_notice 持久化，并恰好唤醒原始 DSH 会话一次，包括在插件重启之后。

通过的裁决会告知 DSH 报告一次并结束回合，而不调用 memory、status、todo、shell 或 workflow 工具。如果终端转发仍让该确切的代理活动保持运行，生命周期守卫会在 terminalRelayTimeoutMs 之后仅取消活动回合，同时保留已排队的收件箱工作。一旦该活动进入空闲，守卫就会解除，因此它无法取消后续的用户回合，并且插件拆除会中止并等待所有待处理的守卫。

规划器工作完成后，受管理的 App Server 仍遵循其空闲宽限期。评审者 CLI 子进程会被单独跟踪，cancel、超时、租约丢失和 stop() 会终止并等待它们；审计完成从不会重新打开或刷新 Desktop。
dsh-codex-workflow respond 仅作为手动/兼容回退——供操作员手动输入裁决，而不是让自动路径收集裁决，或在自动流水线被中断后重新驱动裁决：

$verdict = '{"verdict":"pass","findings":[],"testGaps":[],"summary":"ok"}'
$verdict | dsh-codex-workflow respond --workflow  --codex-thread $env:CODEX_THREAD_ID --submission  --stdin
dsh-codex-workflow status --request  --json

--submission （在 respond 中为可选）将裁决固定到审查所答复的确切提交；若不提供，则仅当工作流没有活动提交时才适用旧有行为。每次 respond 都会经过校验，按请求 id 幂等，并可安全重放——它绝不会绕过证据指纹检查（若工作区自审查以来已发生变化，裁决会被拒绝）。

裁决会在原始 DSH 会话中应用，采用与 DSH 主导流程相同的阻塞/非阻塞/无变化/最大循环策略：阻塞性发现会将 DSH 退回 fixing（然后重新 submit），只有非阻塞性发现会停在 waiting_review_decision 等待用户，而 pass 会完成工作流。如果工作区在提交与裁决之间发生变化，裁决会被拒绝，并要求 DSH 重新 submit 以进行全新审查——旧裁决永远无法通过已更改的代码。

CODEX_THREAD_ID

桥接层从不凭空创造源任务 id。dispatch/respond 会从 CODEX_THREAD_ID 获取 --codex-thread 的默认值，并在其缺失时以可直接粘贴的解释失败。在首次审查时，回调会校验并恢复该 id，将其持久化为工作流的审查任务 id，并在后续循环中复用它。

DSH 主导流程（旧有，兼容）

对于 review_only，首次审计会直接使用
codex exec --json 创建其持久任务；其 thread.started 身份会在转换审查之前被保存。后续审计会恢复该任务，即使第一轮的规范化失败也是如此。无法加载的现有任务仍会失败，而不是被静默替换。这避免了恢复一个没有持久历史的空 App Server 任务。

pnpm review-only:accept 使用临时工作区/存储和夹具 DSH 工具上下文，对真实 CLI 首次任务创建以及同一任务上的修复审查进行演练。它需要本地 Codex 登录；DSH_CODEX_LIFECYCLE_MODEL 可选地固定测试模型。它不会重启正式的 DSH 配置文件。

在 DSH 对话中：

让 Codex 先规划这个改动，我来执行，完成后再让 Codex 审查。

工具：codex_workflow_start、codex_workflow_continue、codex_workflow_review、codex_workflow_review_only、codex_workflow_submit、codex_workflow_decide、codex_workflow_status、codex_workflow_cancel。

自主规划触发
该插件注册了一个 systemPrompt 策略段，让当前 DSH 模型决定用户请求的开发任务是否应在任何实现变更之前启动 Codex 规划。它不会在后台监听器中检查用户消息，也不使用关键词分类器。

- complex（默认）：对多文件/跨层工作、架构/API/数据/持久化/并发/安全/生命周期/迁移/发布变更、需要回归测试且根因不明确的缺陷，以及成熟/稳定/端到端请求自动启动。明确的低风险本地编辑留在 DSH 中。
- always：对每个具有写入意图的开发任务自动启动。
- off：不注入自动触发策略；仍可显式使用工作流工具。

提问、解释、翻译、只读检查/研究以及仅 Git 操作永远不会自动触发。用户指示直接工作、跳过规划或不使用 Codex 始终优先。插件生成的计划/审查/修复/提交消息，以及已经拥有活动工作流的会话，永远不会启动另一个工作流。当复杂性不确定时，DSH 可以只进行决定所需的最少只读检查；一旦匹配，它会简要宣布该决定，并在修改工作区之前恰好调用一次 codex_workflow_start。会话作用域的 SQLite 租约加上活动工作流检查是最终的防竞态保护，因此并发尝试只能创建一个工作流和一个 Planner 任务。

状态机

planning -> waiting_input -> executing -> reviewing -> fixing -> passed
executing/fixing -> codex_workflow_submit (returns immediately) -> queued -> sending -> retrying -> verdict_ready -> received -> applied -> delivered
-> failed (invalid thread, no verdict, invalid identity/schema)
first sending: read-only source validation -> resume source task for review; later sending: resume that same task
verdict_ready: verdict staged in the record; enqueue pending (crash-recoverable)
received:      verdict command queued for application
applied:       outcome persisted (pass | fixing | waiting_review_decision | blocked | refused-if-changed)
delivered:     outcome relayed to the original DSH session
cancelled: terminal — no queue retry, no late verdict, no message may resurrect it

cancelled 在桥接层下也是终态：排队的回调停止重试，迟到的裁决会收到幂等的 cancelled 回执，并且永远不会唤醒 DSH，重复的队列文件或重启也无法重复轮次。当提交处于活动状态时，停止轮次不会要求 DSH 再次提交它。

故障恢复

- 所有多步骤协调状态（租约、桥接队列、工作流记录）都存放在每个存储目录一个的 SQLite 数据库（coord.sqlite）中，由每个 DSH 进程和 CLI 共享。每个不变量都在单个 BEGIN IMMEDIATE 事务中运行；在任何时刻被终止的进程都会干净地回滚，并且 PRAGMA integrity_check 保持干净。
- 日志模式为回滚日志（DELETE），刻意不使用 WAL。 SQLite 版本  applied 移动；冲突的 request id 始终被拒绝；暂存的身份会一直保留直到被应用。
- 投递为 prepare -> relay -> commit：在 relay 之前重新计算工作区指纹，只有在 relay 落地后才（在隔离的 CAS 中）写入 delivered。失效的通过（passes）被报告为 void，绝不报告为 passed；在 commit 之前胜出的取消或新提交永远不会被标记为 delivered。
- 在崩溃重放的情况下，调度投递是恰好一次的：bridgeRequestId 防止重复工作流，确定性的 relay 消息 id（持久化在会话的 agent/inbox/spliced 事件中）防止重复 followup。
- 缺失的活跃会话会以有上限的退避永远重试（绝不进入 dead letter）以处理裁决，并且每次重试都会重新运行指纹检查，因此即使经过长时间离线，过期的通过也会被判定无效。
- Reviewer CLI 调用绑定确切的 DSH 工作区 cwd，并以 --sandbox read-only、approval_policy=never 运行，且不要求 Git 根目录；Git、非 Git 和嵌套仓库工作区使用相同的路径。
- 所选的现有 Codex 任务即为审查任务。活跃的写入者仍可通过有界退避重试；插件绝不会创建替代的可见任务来绕过它。
- 取消会中断确切的活跃 Planner 轮次或 CLI 子进程。提交租约防止过期的 owner 应用更新的审查，并且 stop() 在拆卸完成前等待子进程退出；临时的规范化/对齐 JSON 永远不会成为 latestReview。

存储
工作流记录、租约、桥接队列和实时会话注册表全部存放在同一个 SQLite 数据库中：$DSH_HOME/storages/dsh-codex-workflow/coord.sqlite。除此之外，磁盘上唯一的状态是 bridge/review-schema.json（强制执行的裁决 schema），以及短暂存在的旧版文件队列源目录，这些目录在首次初始化时被导入一次（回执、重试语义和尝试次数均保留）。bridge/sessions.json 已不复存在——实时会话是 coord.sqlite（live_sessions）中的行，带有按所有者划分的租约，因此多进程运行时是合并而非最后写入者胜出，且崩溃运行时的会话会通过 TTL 过期。记录从不包含登录令牌。旧的 JSON 工作流记录以 origin: "dsh" 惰性导入，并保持其原有行为。

运维 CLI

dsh-codex-workflow 同时也是审计/运维接口（所有命令均支持 --json）：

- workflows [--cwd] [--dsh-session] [--phase] — 列出工作流摘要（从不包含负载）。
- show --workflow  — 插件版本以及一个工作流的源/审查任务 id、阶段、提交/回调状态、审查周期、最后错误和证据摘要。在新的计划/桥接工作流中，两个 id 有意标识同一个 Codex 任务；旧工作流可能仍会报告一个不同的 Reviewer id。
- queue [--status ] — 队列/回执/死信行，包含尝试次数、下次重试和最后错误（从不包含命令负载）。
- retry --request  — 重新将 dead-letter 请求或旧版导入的 failed 行加入队列；幂等，并拒绝活动或已完成的行。已取消的回执存储在已完成的 done 行上，且永不重试。
- prune [--older-than ] [--commit] — 默认试运行；--commit 仅移除早于保留窗口的终态回执和已通过/已取消的工作流。活动工作流、未投递的裁决以及失败/阻塞的诊断永远不会成为候选对象。
- help — 用法。

运行 pnpm doctor（完整：需要 Codex CLI + 登录）或 pnpm doctor:offline（CI 安全：仅跳过 codex/登录检查，将其标记为 SKIPPED，仍检查 SQLite/存储/本地路径/构建，--json 供机器使用）。

发布检查

pnpm release:check 是一个可重复的离线门禁：typecheck + 完整测试套件 + build + 离线 doctor（--json，必须通过）+ 一个打包审计（临时 tarball 始终会被清理），该审计断言包仅发布 files 白名单中的内容——不包含测试/夹具、coord.sqlite、DSH_HOME 路径、凭据或临时/审查残留物。CI（.github/workflows/ci.yml）在 Windows 上运行相同的矩阵，使用 Corepack 固定的 pnpm 10 和冻结的 lockfile。

配置

cordis.patch.yml 中的默认值：

- codexCommand：codex
- autoTriggerMode：complex（off | complex | always）
- plannerModel / reviewerModel：空表示当前 Codex 默认值
- plannerEffort / reviewerEffort：high
- maxReviewCycles：3（1–10）
- maxNoChangeReviewRounds：1（1–10）
- reviewDiffMaxBytes：65536（1 KiB–1 MiB）
- bridgePollMs：1000（200 ms–60 s）
- bridgeMaxPayloadBytes：1048576（64 KiB–16 MiB）
- callbackTimeoutMs：600000（10 秒–30 分钟）
- callbackMaxAttempts：3（每轮持久恢复 1–10 次尝试）
- callbackRetryBaseMs：2000（200 毫秒–5 分钟）
- turnTimeoutMs：600000
- idleProcessMs：5000（仅在所有 App Server 工作空闲后启动）
- terminalRelayTimeoutMs：60000（0 表示禁用；最大 10 分钟；仅取消卡住的终端传递中继并保留收件箱工作）
- openCodexDesktopOnReview：兼容性字段；CLI 审计保持 Desktop 自动打开禁用，且从不刷新或聚焦窗口
- desktopOpenRetryBaseMs：2000（200 毫秒–60 秒；初始重试退避）
- desktopOpenRetryMaxMs：60000（1–60 秒；封顶重试退避）

状态存储在 $DSH_HOME/storages/dsh-codex-workflow/coord.sqlite（队列 + 租约 + 工作流 + 实时会话）；bridge/review-schema.json 保存强制执行的裁决模式。记录从不包含登录令牌。

许可证

MIT