mcp server

Guarded-Multi-Model-Development-Pipeline

Guarded multi-model development workflow with independent review, deterministic checks, recovery, and human release boundaries.

yuyukosama2004/Guarded-Multi-Model-Development-Pipelinecommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 29, 2026

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。