Multi-Agent Codex + Claude Code Workflow

项目案例、设计取舍与后续更新：execute42 / Guarded Agent Pipeline

一个本地、可审计的研发流水线：

Codex Desktop + Skill
→ TypeScript MCP Server
→ Claude Code / DeepSeek V4 Pro 实现与最多两次修复
→ 外部 PowerShell 确定性验证
→ Codex 审查、必要时接管和最终准入

流水线不会安装、升级或覆盖你的 Codex、Claude Code、DeepSeek 路由配置。它只调用现有配置，并在外部可信目录保存状态和证据。

当前实现版本: v0.4B verification shadow。v0.3 围绕输入瘦身、缓存友好和审查可靠性收尾；v0.4A 快线已把 TypeScript state/task control core 和 job lifecycle metadata 进一步收束到 MCP 层；v0.4B Task D 已把 prompt-context 接入 DeepSeek implement/fix 调用路径的诊断 telemetry，Task E 已让 review bundle 暴露任务包边界和补丁成熟度信号，Task F 已新增 verification shadow 和 final approval readiness 观察信号。所有可信验证路由、最终批准闸门和人工 push 边界仍保持不变。

下一阶段计划: v0.4B 的三个原始问题闭环已完成第一轮落地。后续若继续推进 TypeScript 迁移，应只在 verification/final approval 已有 shadow 证据基础上扩展默认路径；PowerShell 继续保留为 recovery fallback。manual_push_only=true 继续保持，流水线不会自动执行真实 git push。

当前里程碑：Milestone 10 / v0.4B Task F 已完成。个人全局 Plugin、Skill 和 14 工具的本地 STDIO MCP Server 已可用，Codex Desktop 可通过 mcp__multi_agent_workflow 命名空间调用；PowerShell 继续作为可信后端和故障恢复入口。v0.4 计划书和历史实施/改进计划属于本地开发文档，统一放在 local-dev-docs/，该目录被 .gitignore 忽略，不随远端发布。

当前可用能力

通过 Codex Desktop 自然语言触发 Plugin 和 Skill；
TypeScript/Node.js MCP Server 暴露 14 个类型化工具；
workflow_get_task_status 的只读状态组合已抽出到 TypeScript 边界，新增 state/task control service 覆盖状态图、状态校验、JSON 边界和 HEAD/worktree 信号；
长任务使用持久化 Job，支持查询、取消、超时、进程树清理和异常中断恢复；TypeScript job lifecycle 会保留失败/超时终态日志路径，并避免中断逻辑覆盖已终止 Job；
创建独立任务分支和 Git worktree；
在 worktree 外保存可信 STATE.json、模型输出和日志；
Codex 只读规划并生成经过 Schema 校验的 PLAN.json；
Claude Code 调用已配置的 DeepSeek V4 Pro 实施计划；
每个任务固定复用一个 Claude Code 执行会话，首次实现使用 --session-id，后续修复使用 --resume；
从临时 debug 日志验证实际 dispatch 模型；
隔离 GitHub Token、SSH Agent 和 Git Credential Manager；
对 DeepSeek 返回结果执行外部 JSON Schema 校验；
按冻结配置运行构建、测试、Lint、类型检查和扫描命令；
记录退出码、超时、HEAD 和日志 SHA-256；
拦截常见危险 Git 命令；
导入 Codex Desktop 计划和风险分级审查；
生成 Desktop 交接材料；
在审查包中摘要证据清单，并标记 desktop handoff 来源；
安全复用当前的 DESKTOP_HANDOFF.json，减少重复生成审查包时的 PowerShell 开销；
在 FIXING_CODEX 时生成 CODEX_TAKEOVER_HANDOFF.json，供 Codex Desktop 接管修复；
在 status/review bundle 中输出 advisory verification_shadow，摘要 VERIFY/TARGETED/FINAL verification artifact、失败检查 ID、日志数量和 HEAD stale 信号；
在 FINAL_REVIEW_CODEX 的 review bundle 中输出 advisory final_approval_shadow_readiness，提前暴露 final verification 缺失、stale、未通过、review 缺失和 dirty worktree 等 gate 前置阻塞 token；
执行确定性最终批准闸门。

尚未完整实现：

FIXING_CODEX 后的 Codex 自动编码脚本；当前已实现结构化接管交接，实际编码仍由 Codex Desktop 执行；
TypeScript 默认控制面尚未完整覆盖 task entry、验证编排和 final approval；这些属于后续 v0.4 迁移范围；
自动或真实 git push → 不在当前计划内。

v0.3 phase 1

TypeScript prompt-context 模块：稳定前缀构建、路径占位符规范化（<REPO>、<WORKTREE>、<TASK_DIR>、<CONTROL_DIR>）、上下文预算策略分类、prompt cache 友好遥测和指纹生成；
此阶段不重写 PowerShell 状态机、最终批准、验证路由或手动 push 边界；更大的 TypeScript 控制面迁移进入 v0.4 范围。

v0.3 phase 2

可选的、schema 支持的 task_slice 和 patch_self_check 对象已添加到 IMPLEMENTATION、FIX_RESULT 和 FIX_PLAN 模式中，定义了任务切片边界和补丁成熟度信号（完整/部分/未成熟/需 Codex 接管）的可重用词汇；
DeepSeek 实现器和修复器提示词要求未来输出显式报告补丁成熟度、修改文件、超出切片范围的文件、未运行的测试、脆性/不稳定断言风险、乱码注释风险、生成文件同步状态、部分工作项、剩余风险详情以及接管建议；
Codex 审查策略要求审查者检查 task_slice/patch_self_check 数据，并与实际差异和验证证据进行交叉验证；缺失或可疑的自检数据将被标记为审查关注点；
不会将 DeepSeek 自检视为可信验证证据，也不会更改可信状态转换、验证路由或最终审批闸门。

v0.3 phase 3

workflow_get_review_bundle 新增咨询性瘦身元数据：review_relevant_files（普通审查输入）、summarized_files（已归类为低价值生成/大体积文件的摘要）和 review_input_summary（聚合计数）；
分类基于保守的路径模式：dist/**、node_modules/**、lockfiles、*.log 和二进制/压缩文件扩展名归类为需摘要；源文件、模式定义、测试和文档文件归类为审查相关；
顺序为确定性排序（按规范化路径字母排序），与新元数据同时保持现有 changed_files 和 diff_path 格式不变；
分类仅为咨询性质 —— 不替代受信的 PowerShell 状态、验证或批准边界；
审查者应将其用作优先级提示，而非受信证据。summarized_files 中的文件仍可能含有值得审查的内容。

v0.3 phase 4

workflow_get_task_status 和 workflow_get_review_bundle 在存在 EVIDENCE_MANIFEST.json 时返回有界的 evidence_manifest_summary；
摘要只暴露任务、HEAD、验证状态、工作树清洁度、文件数量、日志数量和哈希等审查有用信息；
证据清单读取是只读、防御式的，清单缺失或损坏不会破坏原有状态查询和审查包生成。

v0.3 phase 5

workflow_get_review_bundle 可在安全条件满足时复用已有 DESKTOP_HANDOFF.json，减少重复调用 New-DesktopHandoff.ps1；
缓存复用必须同时满足：存在验证 HEAD、缓存是 JSON 对象、缓存 head_sha 匹配验证 HEAD、当前 worktree HEAD 仍匹配、当前 worktree clean；
缓存缺失、损坏、过期、无验证锚点、当前 worktree dirty 或 HEAD 分叉时，仍回退到原有 PowerShell 生成路径；
新增 desktop_handoff_source 字段，值为 cached、generated 或 takeover，为增量元数据，不改变原有审批边界；
FIXING_CODEX 接管路径保持独立，不调用普通 desktop handoff。

v0.3 maintenance

修复 Import-DesktopFixPlan.ps1 和 Invoke-TargetedFixVerification.ps1 对多文件 Git 输出的处理；
git diff --name-only 和 git ls-files --others 的多行输出会先拆成独立路径，再进入原有 exact allowed_files 校验；
不引入 glob、目录前缀或宽松匹配，仍然只允许 FIX_PLAN 显式列出的规范化路径；
Pester 覆盖多文件允许、缺失路径拒绝、定点验证提交多个允许文件以及拒绝额外未授权文件。

v0.4 fast-track core / v0.4B Task D-F

v0.4 从原先的重型 parity/shadow 迁移收缩为激进快线：先直接迁一层 TypeScript 控制面，再用边界测试和 deterministic verification 兜底；
已新增 TypeScript state/task control service，覆盖合法状态图、状态/转换校验、安全读取 task.json / STATE.json、结构化错误、HEAD/base/worktree clean 信号，以及中文路径、空格路径、坏 JSON、缺文件、dirty worktree、HEAD mismatch 测试；
已强化 TypeScript job lifecycle metadata，失败/超时终态会保留 stdout/stderr 日志路径，interruptJob 不再覆盖已终止 Job，并补充 timeout、failure、completion、orphaned CANCEL_REQUESTED 和 terminal guard 测试；
v0.4B Task D 已新增 prompt-telemetry-cli 和 PowerShell Invoke-PromptTelemetry 桥接，DeepSeek implement/fix 阶段会在 evidence 目录写入诊断性 prompt telemetry，记录 stable prefix fingerprint、section counts、dynamic approximate tokens、total approximate tokens 和 placeholder keys；
prompt telemetry 只用于观察 prompt cache 友好度，不作为可信验证、审批或计费证据；CLI 不存在或失败时写入 error artifact，DeepSeek 阶段继续执行；
v0.4B Task E 已在 workflow_get_review_bundle 中新增 advisory task_package_summary 和 patch_maturity_summary，突出 allowed/forbidden files、non-goals、acceptance criteria、非空验证类别，以及缺失 patch_self_check、out-of-slice、generated artifact sync、脆弱断言、乱码注释、tests_not_run 和 partial work 等补丁成熟度信号；
Task E 字段仍是 advisory metadata，不作为可信验证、审批或 push 证据；fix 后优先读取 FIX_RESULT.json，避免旧 IMPLEMENTATION 成熟度覆盖最新修复结果；
v0.4B Task F 已新增 verification_shadow 和 final_approval_shadow_readiness，用 TypeScript 只读摘要 verification artifact、失败 ID、日志引用、HEAD stale、final review 前置阻塞 token；targeted verification 适配 Invoke-TargetedFixVerification.ps1 的真实合同，优先使用 commit_sha / head_after、all_passed 和 command-N/check-N 失败 ID；
Task F 字段仍是 advisory metadata，不替代 Invoke-ProjectVerification.ps1、Invoke-FinalCandidateVerification.ps1 或 Invoke-FinalApproval.ps1；final gate 仍只由 PowerShell deterministic gate 产生 PUSH_APPROVED / PUSH_REJECTED；
MCP 测试覆盖从 9 个测试文件 / 283 个测试提升到 10 个测试文件 / 432 个测试；PowerShell/Pester 回归提升到 125/125；
PowerShell 仍是 verification/final approval 的可信后端和 recovery fallback；
后续若继续推进 TypeScript 默认化，应以 Task F 的 shadow/readiness 信号为依据逐步扩展 verification 编排；final approval gate 只做 mirror/shadow，确认等价后再讨论默认化；
v0.4 仍不开放自动 git push，不改变 14 个 MCP tool 的公开名称，也不让 DeepSeek 自检替代外部验证。

当前版本通过 PowerShell 脚本支持：

创建任务、自动运行到验证、审查导入和修复分流；
DeepSeek 修复器：两个自定义修复周期 + 高风险管理确认 + 限制性文件修复；
定点验证（仅 FIX_PLAN 命令）和仅允许文件的本地提交；
DeepSeek 修复周期用尽后自动进入 FIXING_CODEX，并生成可信接管交接；实际 Codex 编码仍由 Desktop 接管；
最终候选完整验证；失败检查生成 FINAL_VERIFY:<index>:<check-name> 供下一份 FIX_PLAN 引用；
最终独立审批闸门。

完整测试套件仅保留给最终合并候选，不在 DeepSeek 修复周期运行。

DeepSeek 会话保存在任务的外部可信控制目录 CLAUDE_EXECUTOR_SESSION.json 中。Claude Code 子进程每阶段结束后仍会退出，但会话记录可恢复；后续修复只发送新增 FIX_PLAN 和验证摘要，不重复发送整份需求、计划和实现上下文。这样既保留超时和进程清理能力，也能稳定利用提示缓存。

Codex Plugin、Skill 与 MCP（里程碑 8）

本仓库包含一个 Codex Plugin 源包，位于 plugins/multi-agent-workflow/。该插件提供一个名为 multi-agent-workflow 的 Skill，供 Codex Desktop 发现和加载。

插件结构

plugins/multi-agent-workflow/
  .codex-plugin/plugin.json          # 插件清单
  .mcp.json                          # 本地 STDIO MCP 配置
  mcp/
    src/                             # TypeScript MCP 源码
    dist/server.js                   # 可分发的单文件入口
  skills/multi-agent-workflow/
    SKILL.md                         # Skill 定义与工作流说明
    agents/openai.yaml               # Agent 元数据与默认提示词
    references/
      workflow-states.md             # 全部 17 个任务状态及转换规则
      review-policy.md               # 风险分级审查策略
      recovery.md                    # 按状态恢复流程

当前状态（里程碑 10 / v0.4 fast-track core）

Skill 源包可验证 — 安装后 Codex Desktop 可发现流水线能力和编排指令。
MCP Server 已实现 — TypeScript/Node.js STDIO MCP server 提供 14 个类型化工具，包含异步 Job 管理、进程树取消和超时、启动中断恢复、状态图辅助和 job 终态日志元数据保留。所有工具通过白名单 PowerShell 脚本与后端交互；PowerShell 保留为文档化恢复路径。
Codex Desktop MCP 暴露已验证 — 插件 MCP server 使用 multi_agent_workflow 作为 server id，工具在 Codex 中显示为 mcp__multi_agent_workflow.workflow_*。.mcp.json 必须为本地 STDIO server 配置明确 cwd，否则 node ./mcp/dist/server.js 可能不在插件目录下启动，导致 Codex 只能看到 server 启动完成但无法列出工具。
个人全局插件已验证 — 当前开发机已安装并启用 multi-agent-workflow@personal 0.1.0+codex.20260623140715。

使用方式

安装或更新插件后，重启 Codex Desktop 或新建线程，然后直接输入：

“使用 multi-agent-workflow 实现这个需求”
“恢复 TASK-... 并告诉我安全的下一步”
“只读审查这个流水线任务”

正常流程由 Codex Desktop 调用 MCP 工具完成环境预检、任务创建、计划提交、DeepSeek 实现、验证、审查、修复和最终建议。开始实现前仍需用户确认计划；真实 git push 始终保留为人工操作。

14 个工具包括：

workflow_preflight                    workflow_create_task
workflow_submit_plan                  workflow_start_implementation
workflow_start_verification           workflow_get_job
workflow_cancel_job                   workflow_get_task_status
workflow_get_review_bundle            workflow_submit_review
workflow_triage_reviews               workflow_submit_final_recommendation
workflow_submit_fix_plan              workflow_start_fix

在 Codex Desktop 中验证插件是否正确暴露时，可以搜索或调用：

mcp__multi_agent_workflow.workflow_preflight

若 workflow_* 没有出现，先检查 codex mcp get multi_agent_workflow 是否显示正确的 cwd，再重启 Codex Desktop 或新建线程让工具目录重新加载。MCP 不可用时，可按照 Skill 的 recovery 文档切换到受控 PowerShell 命令。

本机适配结果

2026-06-23 已实测环境：

Codex CLI：0.111.0
Claude Code：2.1.177
Node.js：20.20.2
DeepSeek 实际 dispatch：deepseek-v4-pro[1m]
PowerShell：Windows PowerShell 5.1 兼容
MCP STDIO：成功发现 14 个工具，workflow_preflight.ready=true

2026-06-28 v0.4B Task F 当前验证：

MCP 单元测试：10 个测试文件、432 个测试
PowerShell/Pester 流水线测试：125/125
最终候选验证：build、unit_test、integration_test、typecheck、secrets_scan 全部通过

当前 Codex CLI 无法运行用户配置中的 gpt-5.5，所以项目级临时覆盖为 gpt-5.4。升级 Codex CLI 后可在 .agent-pipeline/config/pipeline.defaults.json 中调整或清空 codex_model_override。

DeepSeek Anthropic 兼容接口在 Claude Code 原生 --json-schema 模式下会超时，因此默认采用：

提示词要求 JSON
→ Claude 外层 JSON 的 result
→ 本地提取 JSON 对象
→ 外部 Schema 严格验证

Codex 仍使用原生 --output-schema。

1. 检查运行时

powershell -NoProfile -ExecutionPolicy Bypass `
  -File ".agent-pipeline\scripts\Test-AgentRuntime.ps1"

输出中的 ready 应为 true。检查不会输出密钥内容。

2. 准备需求

创建一个 Markdown 文件，例如：

D:\需求\REQUIREMENT.md

写清楚目标、不可修改范围和验收条件。

3. 配置目标项目验证命令

可以直接编辑本仓库的默认模板，也可以为每个目标项目准备独立 JSON，并在创建任务时通过 -ProjectCommandsPath 传入。

示例：

{
  "schema_version": "2.0",
  "commands": {
    "build": ["npm run build"],
    "unit_test": ["npm test"],
    "integration_test": [],
    "lint": ["npm run lint"],
    "typecheck": ["npx tsc --noEmit"],
    "security": [],
    "secrets_scan": []
  },
  "required": {
    "build": true,
    "unit_test": true,
    "integration_test": false,
    "lint": true,
    "typecheck": true,
    "security": false,
    "secrets_scan": false
  },
  "timeouts_seconds": {
    "build": 900,
    "unit_test": 1800,
    "integration_test": 1800,
    "lint": 900,
    "typecheck": 900,
    "security": 1200,
    "secrets_scan": 1200
  }
}

必需类别没有配置命令时，验证会失败关闭。

4. 创建任务

目标仓库必须已有至少一个提交。

$task = powershell -NoProfile -ExecutionPolicy Bypass `
  -File ".agent-pipeline\scripts\New-AgentTask.ps1" `
  -RepositoryPath "D:\项目\目标项目" `
  -RequirementFile "D:\需求\REQUIREMENT.md" `
  -ProjectCommandsPath "D:\需求\project.commands.json" `
  -BaseRef "origin/main" `
  -RiskLevel "medium" `
  -Title "任务标题" |
  ConvertFrom-Json

$task.control_path
$task.worktree_path

脚本会创建：

agent/TASK-... 任务分支；
目标仓库外的任务 worktree；
%LOCALAPPDATA%\AgentPipeline\... 下的可信任务目录；
冻结后的需求、配置、状态和证据目录。

5. 自动运行到验证阶段

模型调用会产生费用。Codex 规划在高推理档位下可能需要数分钟。

powershell -NoProfile -ExecutionPolicy Bypass `
  -File ".agent-pipeline\scripts\Invoke-AgentTaskToVerification.ps1" `
  -TaskDirectory $task.control_path

成功输出示例：

{
  "status": "ready_for_review",
  "all_required_passed": true,
  "current_state": "VERIFYING"
}

可信任务目录中会生成：

PLAN.json
IMPLEMENTATION.json
VERIFY_SUMMARY.json
RUNTIME_CHECK.json
evidence/codex-architect.*
evidence/deepseek-implementer.*
evidence/deepseek-model-verification.json
各验证命令日志

单独运行某个阶段

# Codex 规划
powershell -NoProfile -ExecutionPolicy Bypass `
  -File ".agent-pipeline\scripts\Invoke-CodexArchitect.ps1" `
  -TaskDirectory $task.control_path

# DeepSeek 实现
powershell -NoProfile -ExecutionPolicy Bypass `
  -File ".agent-pipeline\scripts\Invoke-DeepSeekImplementer.ps1" `
  -TaskDirectory $task.control_path

# 确定性验证
powershell -NoProfile -ExecutionPolicy Bypass `
  -File ".agent-pipeline\scripts\Invoke-ProjectVerification.ps1" `
  -TaskDirectory $task.control_path

测试

# MCP 构建、测试和类型检查
npm --prefix "plugins/multi-agent-workflow/mcp" run build
npm --prefix "plugins/multi-agent-workflow/mcp" test
npm --prefix "plugins/multi-agent-workflow/mcp" run typecheck

# 完整 PowerShell 流水线测试
powershell -NoProfile -ExecutionPolicy Bypass `
  -File ".agent-pipeline\tests\Run-Tests.ps1"

完整测试套件仅在准备合并的最终候选 HEAD 上运行；普通开发和修复阶段优先运行受影响的专项检查。

安全边界

Agent 只能写任务 worktree；
可信控制目录位于 worktree 外；
模型声明不算测试证据；
Git 凭据从 Agent 和验证子进程环境中剥离；
Claude Hook 是辅助防线，不是唯一边界；
manual_push_only=true 是有意设计的安全边界 — 不是缺失的功能。所有 git push 操作必须由人工在流水线外执行，流水线本身不会暴露任何 push 工具或自动化 push 路径。此边界同时体现在 pipeline.defaults.json 配置、MCP 工具白名单（缺少 push 工具）、Codex Desktop Skill 说明（最终步骤仅展示手动命令）以及 PowerShell 后端（Invoke-FinalApproval.ps1 输出 PUSH_APPROVED 后由人工执行）。
当前版本不会执行 git push。

Name		Name	Last commit message	Last commit date
.agent-pipeline		.agent-pipeline
.codex		.codex
plugins/multi-agent-workflow		plugins/multi-agent-workflow
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Navigation Menu

Repository files navigation

Multi-Agent Codex + Claude Code Workflow

当前可用能力

v0.3 phase 1

v0.3 phase 2

v0.3 phase 3

v0.3 phase 4

v0.3 phase 5

v0.3 maintenance

v0.4 fast-track core / v0.4B Task D-F

Codex Plugin、Skill 与 MCP（里程碑 8）

插件结构

当前状态（里程碑 10 / v0.4 fast-track core）

使用方式

本机适配结果

1. 检查运行时

2. 准备需求

3. 配置目标项目验证命令

4. 创建任务

5. 自动运行到验证阶段

单独运行某个阶段

测试

安全边界

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Multi-Agent Codex + Claude Code Workflow

当前可用能力

v0.3 phase 1

v0.3 phase 2

v0.3 phase 3

v0.3 phase 4

v0.3 phase 5

v0.3 maintenance

v0.4 fast-track core / v0.4B Task D-F

Codex Plugin、Skill 与 MCP（里程碑 8）

插件结构

当前状态（里程碑 10 / v0.4 fast-track core）

使用方式

本机适配结果

1. 检查运行时

2. 准备需求

3. 配置目标项目验证命令

4. 创建任务

5. 自动运行到验证阶段

单独运行某个阶段

测试

安全边界

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages