agent-engineer

用途

Agent Engineer 是一个带审批门（approval gate）的元编排器（meta orchestrator）。它假定任务级会话信息与请求信息由基础智能体管理，自身只负责：模式选择、架构文档化、状态存储、验证、执行运行器（runner）生成。适用于 Codex 需要协调编码、研究、docx/pptx/xlsx 文档工作或运营分析等任务时，通过任务编排完成多步骤、多角色、多 CLI 的协作。

主要能力

解析请求，并仅就缺失的事实做补充确认。
按需读取参考文档以决定模式组合：
- references/pattern-catalog.md
- references/architecture-selection.md
- references/domain-routing.md
- references/source-index.md
通过 command -v codex、command -v claude、command -v opencode 检查 CLI 是否安装。
在当前工作目录的 .codex/agent-engineer/architecture.md 中撰写审批方案。
用 scripts/render_architecture.py 渲染 Mermaid 图与审批摘要表。
向用户提交审批方案；在获得明确批准前，不生成也不执行任何执行脚本。
批准后，用 scripts/build_runner.py 生成运行器，用 scripts/run_architecture.py 执行运行器。

使用方式

核心工作流

解析请求，仅补充确认缺失的事实。
按需读取上述参考文档，决定模式组合。
用 command -v codex、command -v claude、command -v opencode 检查安装情况。
在 .codex/agent-engineer/architecture.md 写入审批方案。
用 scripts/render_architecture.py 渲染 Mermaid 与审批摘要表。
向用户提交审批方案。
在获得明确批准前，不生成或执行执行脚本。
批准后，用 scripts/build_runner.py 生成运行器。
批准后，用 scripts/run_architecture.py 执行运行器。

架构撰写要求

architecture.md 是供人工审批的唯一事实来源（single source of truth）。文档末尾必须放置机器可读的 JSON 代码块，执行脚本假定只解析该 JSON 块。

审批方案必须包含：

选定的基础模式与组合方式
分步执行顺序
各步骤或角色使用的 CLI
各步骤或角色使用的模型
并行度
验证策略
重试策略
委派点

JSON 块必须包含以下字段：

version
approval_status
composition
selected_patterns
engines
steps
parallel_policy
retry_policy
validation_policy
delegation_policy

若所选 CLI 未安装，render_architecture.py 的输出中应显示警告。当前环境中 codex 与 claude 通常是候选，opencode 仅在已安装时才可选择。

执行纪律

批准后，运行器必须强制以下不变量：

状态变更只能通过 agent_state.py 进行。
每个步骤开始前后调用 verify_store.py。
验证通过前，任何任务不得转为 done。
超过 retry_policy.max_attempts 时转为 blocked，并请求用户介入。
仅在无 scope 冲突时才启动并行任务。
invoke_agent.py 拒绝审批方案中未包含的 CLI 或模型组合。

脚本说明

scripts/agent_state.py：状态存储的唯一 CRUD 入口。
scripts/verify_store.py：验证事件哈希链、快照重建、枚举、引用完整性、审批门、完成前转移规则。
scripts/render_architecture.py：生成供审批的 Mermaid 与摘要表。
scripts/build_runner.py：从已批准的架构生成运行器目录。
scripts/run_architecture.py：执行生成的运行器，并在每个步骤前后验证存储。
scripts/invoke_agent.py：仅使用已批准的 CLI 与模型组合，标准化调用 codex exec、claude -p、opencode。

路径约定

架构：.codex/agent-engineer/architecture.md
状态存储：.codex/agent-engineer/store/
状态文件：.codex/agent-engineer/store/events.jsonl、.codex/agent-engineer/store/snapshot.json
执行产物：.codex/agent-engineer/runs/<run-id>/

最小操作流程

撰写架构草案时：

分类任务性质。
只选择需要的模式。
为各步骤分配 CLI 与模型。
确定并行度与重试策略。
明确验证命令或验证准备方式。
确认 render_architecture.py 结果后再请求审批。

执行时：

确认 verify_store.py 是否通过。
确认审批状态为 approved。
用 build_runner.py 生成运行器。
准备好验证命令后，执行 run_architecture.py。
失败任务只能按已批准的策略重试。

适用场景

编码、研究、文档工作、运营分析等任务：使用相同的存储结构，仅路由方式不同。
领域相关的推荐模式、工作角色、验证方式，仅通过读取 references/domain-routing.md 决定。
模式选择标准优先参考 references/architecture-selection.md。

限制与不可协商项

不单独存储会话信息与请求全文。
架构必须只记录在 .codex/agent-engineer/architecture.md。
批准前不得执行 build_runner.py 或 run_architecture.py。
状态 JSON 不得直接修改，只能使用 scripts/agent_state.py。
不得即兴创建新的状态操作脚本。
若捆绑脚本缺少所需功能，应在批准后作为技能修订工作单独处理。

暂未提供

关于收费、价格、平台支持范围、具体效果指标等信息，资料中暂未提供。