aep-executor

执行器抽象

一套可复用的抽象，用于在隔离的工作区中运行实现工作，不受所用 Agent 宿主（Claude Code、Codex）或可用机制的限制。生命周期技能使用一套统一的操作词汇；本技能会将每项操作映射为各模式对应的具体方案。/aep-launch、/aep-build 和 /aep-autopilot 会将其作为库使用；也可以单独调用，以试运行检测流程（参见单独使用）。

优先使用原生方式： Claude Code 启动时使用原生进程内后台子 Agent（native-bg-subagent，默认方式），或在存在 claude --bg 标志的情况下使用原生后台会话（claude-bg）；Codex 启动时使用原生子 Agent（codex-subagent）或无头执行工作进程（codex-exec）。tmux+cmux 属于 legacy 模式——仅在显式指定（git config aep.executor-backend tmux）或使用通用宿主时选择。所有模式都会在 AEP 创建的 git worktree .feature-workspaces/<ws> 中运行工作进程。

---

其他技能如何使用本技能

技能	用途	操作
/aep-launch	启动实现 Agent，并使其可供审查	detect、spawn、present
/aep-build Phase 5	在正确的执行上下文中启动评估器	detect、spawn_evaluator
/aep-build	在构建过程中提出需要人工决策的事项	gate
/aep-autopilot	以低开销运行定期检查；引导工作区	detect、check、nudge、liveness、gate
/aep-wrap	合并后拆除工作进程和 worktree	teardown
/aep-dispatch	确定交接模式；路由“……with workflow”运行	detect

---

操作契约

每个使用方都会调用这些操作。配方文件提供各模式的实现。

操作	用途
detect()	确定宿主环境 + 原生能力 + 固定配置，选择一种模式
spawn(ws, branch, prompt)	启动绑定到 AEP 工作树的实现 Agent
spawn_evaluator(ws, role)	在该模式的评估上下文中启动评估 Agent（绑定到工作树）；接受可选的、由层级推导出的工作量提示（参见 backends.md）
nudge(ws, msg)	发送执行过程中的指令 (适用于可引导模式；在 claude-bg 下采用拉取方式)
liveness(ws)	Agent 是否正在积极工作？ (特定于模式的信号 + git-diff 佐证)
gate(ws)	呈现工作进程需要人工决策的事项：needs-human.md + 该模式的传输机制，由主 Agent 以中心辐射式方式应答（原地阻塞或设置关卡并暂停）
check(prompt, schema)	在低成本、上下文隔离的 Agent 中运行只读分析提示词；返回其 JSON 结果——保持长期运行的编排器会话上下文精简
monitor(ws)	读取 .dev-workflow/signals/status.json——独立于宿主环境，永不改变
present(ws)	人工审查界面（TaskOutput / claude attach / Codex 线程 / cmux 标签页 / 信号）
teardown(ws)	清理工作进程 + 工作树

monitor() 已经抽象化。 无论使用何种执行器，进度都会在各阶段边界通过信号文件报告。 原生推送通道（SendMessage、send_input）属于加速层——信号文件仍是持久、与宿主环境无关的事实来源。

---

各模式（摘要）

模式	生命周期	选择条件
native-bg-subagent	绑定会话	Claude Code 默认模式 + 长期运行的编排器
claude-bg	绑定 OS	Claude Code，且存在 claude --bg（cron 驱动程序 / 需要绑定 OS）
codex-subagent	绑定会话	使用 Codex，且主线程仍在运行（桌面应用或交互式 CLI）
codex-exec	绑定 OS	Codex + cron 驱动程序，或需要严格隔离
legacy	绑定 OS	显式固定配置（aep.executor-backend tmux），或使用通用宿主环境且带有 tmux
workflow	绑定会话	显式选择加入（“……with workflow”）+ Claude Code（参见 /aep-workflow）
headless	绑定会话	最后的选择

阅读 references/backends.md，了解各模式的机制、检测配方、完整的选择顺序、驱动程序 × 后端兼容性矩阵、人工关卡协议以及孤立进程的重新接管。

---

参考文件

文件	内容	阅读时机
references/backends.md	模式矩阵、检测、选择顺序、驱动兼容性、门控协议、孤立任务重新接管、check()	始终在启动或引导之前阅读
references/claude-native.md	native-bg-subagent（默认）和 claude-bg 配方、--bg 可用性说明	所选模式为 Claude 原生模式时
references/codex-native.md	codex-subagent 和 codex-exec 配方、aep-builder/aep-evaluator 角色 TOML、桌面应用映射	所选模式为 Codex 模式时
references/tmux-session.md	legacy 配方（tmux 启动/提示/存活检测、cmux 标签页阶梯）	固定或选中 legacy 时
references/dogfood-validation.md	dogfood_method() 主机 × 模式检测、e2e_tool()、target_url() 解析	运行 dogfood 验证时（由 /aep-build、/aep-launch、/aep-watch 和 autopilot 合并后守卫调用）

此技能还附带两个探测脚本，因此准确的 bash 命令集中在一处，无需从参考文档中重新输入：

• scripts/detect-backend.sh [--lifetime long|ephemeral] [--opt-in workflow|tmux] [--json] — 主机、执行器命令、原生能力、固定项、呈现界面和选定的 MODE。使用 eval "$(bash scripts/detect-backend.sh)" 调用。
• scripts/spawn-liveness-probe.sh <name> <agent_id> — 每个启动器都会运行的启动后存活探测 （references/backends.md § 启动后存活探测）。

---

独立使用

直接调用时，此技能会报告将会发生什么：

1. 运行 bash scripts/detect-backend.sh（如果此次调用是 cron/launchd 一次性任务，则添加 --lifetime ephemeral——脚本无法探测这一点）。
2. 报告它输出的每个字段，并说明该 MODE 为何胜出：选择顺序中哪些更早的规则未匹配。
3. 如果用户询问“为什么不用 workflow／为什么不用 tmux”，请解释 opt-in／固定项门控条件。

此操作不会启动任何内容——它只是 detect() 的试运行。

---

原理

为什么原生模式优先，而 tmux 是固定的 legacy 模式；为什么 AEP 拥有工作树；为什么会话绑定与操作系统绑定是一个一等维度；为什么人工门控采用中心辐射式结构；以及为什么 autopilot 只驱动可引导模式，相关记录见 docs/decisions/native-first-executor.md、 docs/decisions/host-agnostic-executor.md 和 docs/decisions/remove-claude-team.md。

---

后续步骤

检测/启动后，控制权返回调用技能：

• /aep-launch → 引导内容是启动提示词（原生模式），或已通过 tmux 发送（legacy），随后在工作区中运行 /aep-build
• /aep-autopilot → 恢复其 tick 循环
• /aep-dispatch → 完成交接