task-orchestrator

任务编排器

使用 tmux + Codex 对多 Agent 构建进行自主编排，并通过自愈监控。

请同时加载 senior-engineering 技能，以遵循工程原则。

安全边界

• 对写入范围重叠的任务，在解决依赖关系前，不要启动并行工作进程。
• 需要人工审核时，不要推送分支、合并工作成果，或凭猜测进行自愈。
• 不要在清单、日志、提示词或 tmux 窗格捕获内容中存储机密。
• 不要无限重试失败的任务；重试次数达到上限后，应停止并报告阻塞原因。

核心概念

1. 任务清单

一个定义所有任务、依赖关系、涉及文件和状态的 JSON 文件。

{
  "project": "project-name",
  "repo": "owner/repo",
  "workdir": "/path/to/worktrees",
  "created": "2026-01-17T00:00:00Z",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": [
    {
      "name": "Phase 1: Critical",
      "tasks": [
        {
          "id": "t1",
          "issue": 1,
          "title": "Fix X",
          "files": ["src/foo.js"],
          "dependsOn": [],
          "status": "pending",
          "worktree": null,
          "tmuxSession": null,
          "startedAt": null,
          "lastProgress": null,
          "completedAt": null,
          "prNumber": null
        }
      ]
    }
  ]
}

2. 依赖规则

• 同一文件 = 顺序执行 — 涉及同一文件的任务必须按顺序运行或合并
• 不同文件 = 并行执行 — 独立任务可以同时运行
• 显式依赖 = 等待 — dependsOn 数组用于强制执行顺序
• 阶段门控 — 当前阶段完成后，才能开始下一阶段

3. 执行模型

• 每个任务都使用自己的 git worktree（隔离分支）
• 每个任务都在自己的 tmux 会话中运行
• 使用 Codex with --yolo 进行自主执行
• 模型：GPT-5.2-codex high（可配置）

---

设置命令

初始化编排

# 1. Create working directory
WORKDIR="${TMPDIR:-/tmp}/orchestrator-$(date +%s)"
mkdir -p "$WORKDIR"

# 2. Clone repo for worktrees
git clone https://github.com/OWNER/REPO.git "$WORKDIR/repo"
cd "$WORKDIR/repo"

# 3. Create tmux socket
SOCKET="$WORKDIR/orchestrator.sock"

# 4. Initialize manifest
cat > "$WORKDIR/manifest.json" << 'EOF'
{
  "project": "PROJECT_NAME",
  "repo": "OWNER/REPO",
  "workdir": "WORKDIR_PATH",
  "socket": "SOCKET_PATH",
  "created": "TIMESTAMP",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": []
}
EOF

分析 GitHub Issues 的依赖关系

# Fetch all open issues
gh issue list --repo OWNER/REPO --state open --json number,title,body,labels > issues.json

# Group by files mentioned in issue body
# Tasks touching same files should serialize

创建 worktree

# For each task, create isolated worktree
cd "$WORKDIR/repo"
git worktree add -b fix/issue-N "$WORKDIR/task-tN" main

启动 Tmux 会话

SOCKET="$WORKDIR/orchestrator.sock"

# Create session for task
tmux -S "$SOCKET" new-session -d -s "task-tN"

# Launch Codex (uses gpt-5.2-codex with reasoning_effort=high from ~/.codex/config.toml)
# Note: Model config is in ~/.codex/config.toml, not CLI flag
tmux -S "$SOCKET" send-keys -t "task-tN" \
  "cd $WORKDIR/task-tN && codex --yolo 'Fix issue #N: DESCRIPTION. Run tests, commit with good message, push to origin.'" Enter

---

监控与自愈

进度检查脚本

#!/bin/bash
# check_progress.sh - Run via heartbeat

WORKDIR="$1"
SOCKET="$WORKDIR/orchestrator.sock"
MANIFEST="$WORKDIR/manifest.json"
STALL_THRESHOLD_MINS=20

check_session() {
  local session="$1"
  local task_id="$2"
  
  # Capture recent output
  local output=$(tmux -S "$SOCKET" capture-pane -p -t "$session" -S -50 2>/dev/null)
  
  # Check for completion indicators
  if echo "$output" | grep -qE "(All tests passed|Successfully pushed|❯ $)"; then
    echo "DONE:$task_id"
    return 0
  fi
  
  # Check for errors
  if echo "$output" | grep -qiE "(error:|failed:|FATAL|panic)"; then
    echo "ERROR:$task_id"
    return 1
  fi
  
  # Check for stall (prompt waiting for input)
  if echo "$output" | grep -qE "(\? |Continue\?|y/n|Press any key)"; then
    echo "STUCK:$task_id:waiting_for_input"
    return 2
  fi
  
  echo "RUNNING:$task_id"
  return 0
}

# Check all active sessions
for session in $(tmux -S "$SOCKET" list-sessions -F "#{session_name}" 2>/dev/null); do
  check_session "$session" "$session"
done

自愈操作

任务卡住时，编排器应：

1. 等待输入 → 发送适当的响应

   tmux -S "$SOCKET" send-keys -t "$session" "y" Enter
   

2. 错误/失败 → 捕获日志、分析问题，并在修复后重试

   # Capture error context
   tmux -S "$SOCKET" capture-pane -p -t "$session" -S -100 > "$WORKDIR/logs/$task_id-error.log"
   
   # Kill and restart with error context
   tmux -S "$SOCKET" kill-session -t "$session"
   tmux -S "$SOCKET" new-session -d -s "$session"
   tmux -S "$SOCKET" send-keys -t "$session" \
     "cd $WORKDIR/$task_id && codex --model gpt-5.2-codex-high --yolo 'Previous attempt failed with: $(cat error.log | tail -20). Fix the issue and retry.'" Enter
   

3. 20 分钟以上没有进展 → 提醒或重启

   # Check git log for recent commits
   cd "$WORKDIR/$task_id"
   LAST_COMMIT=$(git log -1 --format="%ar" 2>/dev/null)
   
   # If no commits in threshold, restart
   

心跳 Cron 设置

# Add to cron (every 15 minutes)
cron action:add job:{
  "label": "orchestrator-heartbeat",
  "schedule": "*/15 * * * *",
  "prompt": "Check orchestration progress at WORKDIR. Read manifest, check all tmux sessions, self-heal any stuck tasks, advance to next phase if current is complete. Do NOT ping human - fix issues yourself."
}

---

工作流：完整编排运行

第 1 步：分析并规划

# 1. Fetch issues
gh issue list --repo OWNER/REPO --state open --json number,title,body > /tmp/issues.json

# 2. Analyze for dependencies (files mentioned, explicit deps)
# Group into phases:
# - Phase 1: Critical/blocking issues (no deps)
# - Phase 2: High priority (may depend on Phase 1)
# - Phase 3: Medium/low (depends on earlier phases)

# 3. Within each phase, identify:
# - Parallel batch: Different files, no deps → run simultaneously
# - Serial batch: Same files or explicit deps → run in order

第 2 步：创建清单

编写 manifest.json，列出所有任务、依赖关系和文件映射。

第 3 步：启动第 1 阶段

# Create worktrees for Phase 1 tasks
for task in phase1_tasks; do
  git worktree add -b "fix/issue-$issue" "$WORKDIR/task-$id" main
done

# Launch tmux sessions
for task in phase1_parallel_batch; do
  tmux -S "$SOCKET" new-session -d -s "task-$id"
  tmux -S "$SOCKET" send-keys -t "task-$id" \
    "cd $WORKDIR/task-$id && codex --model gpt-5.2-codex-high --yolo '$PROMPT'" Enter
done

第 4 步：监控并自愈

每 15 分钟进行一次心跳检查：

1. 轮询所有会话
2. 在清单中更新进度
3. 对卡住的任务进行自愈
4. 第 N 阶段的所有任务完成后 → 启动第 N+1 阶段

第 5 步：创建 PR

# When task completes successfully
cd "$WORKDIR/task-$id"
git push -u origin "fix/issue-$issue"
gh pr create --repo OWNER/REPO \
  --head "fix/issue-$issue" \
  --title "fix: Issue #$issue - $TITLE" \
  --body "Closes #$issue

## Changes
[Auto-generated by Codex orchestrator]

## Testing
- [ ] Unit tests pass
- [ ] Manual verification"

第 6 步：清理

# After all PRs merged or work complete
tmux -S "$SOCKET" kill-server
cd "$WORKDIR/repo"
for task in all_tasks; do
  git worktree remove "$WORKDIR/task-$id" --force
done
rm -rf "$WORKDIR"

---

清单状态值

状态	含义
pending	尚未开始
blocked	正在等待依赖项
running	Codex 会话处于活动状态
stuck	需要干预（自动自愈）
error	失败，需要重试
complete	已完成，可以创建 PR
pr_open	已创建 PR
merged	PR 已合并

---

示例：安全框架编排

{
  "project": "nuri-security-framework",
  "repo": "jdrhyne/nuri-security-framework",
  "phases": [
    {
      "name": "Phase 1: Critical",
      "tasks": [
        {"id": "t1", "issue": 1, "files": ["ceo_root_manager.js"], "dependsOn": []},
        {"id": "t2", "issue": 2, "files": ["ceo_root_manager.js"], "dependsOn": ["t1"]},
        {"id": "t3", "issue": 3, "files": ["workspace_validator.js"], "dependsOn": []}
      ]
    },
    {
      "name": "Phase 2: High",
      "tasks": [
        {"id": "t4", "issue": 4, "files": ["kill_switch.js", "container_executor.js"], "dependsOn": []},
        {"id": "t5", "issue": 5, "files": ["kill_switch.js"], "dependsOn": ["t4"]},
        {"id": "t6", "issue": 6, "files": ["ceo_root_manager.js"], "dependsOn": ["t2"]},
        {"id": "t7", "issue": 7, "files": ["container_executor.js"], "dependsOn": []},
        {"id": "t8", "issue": 8, "files": ["container_executor.js", "egress_proxy.js"], "dependsOn": ["t7"]}
      ]
    }
  ]
}

第 1 阶段的并行执行：

• t1 和 t3 并行运行（涉及不同文件）
• t2 等待 t1（涉及同一文件）

第 2 阶段的并行执行：

• t4、t6、t7 可以同时开始
• t5 等待 t4，t8 等待 t7

---

提示

1. 复杂工作始终使用 GPT-5.2-codex high：--model gpt-5.2-codex-high
2. 提示词要清晰 — 包含 Issue 编号、描述、预期结果和测试说明
3. 原子化提交 — 告知 Codex 在每项逻辑变更后提交
4. 尽早推送 — 推送到远程分支，以免会话中断导致进度丢失
5. 检查点日志 — 定期将 tmux 输出捕获到文件
6. 阶段门控 — 第 N 阶段未 100% 完成前，不要启动第 N+1 阶段
7. 积极自愈 — 卡住超过 10 分钟时，自动介入
8. 浏览器中继限制 — 如果 CDP 自动化受阻，请使用 iframe 批量抓取或手动执行浏览器操作

---

与其他技能集成

• senior-engineering：加载以遵循构建原则和质量门控
• coding-agent：参考 Codex CLI 模式
• github：用于创建 PR 和管理 Issue

---

经验总结（2026-01-17）

Codex 沙箱限制

使用 codex exec --full-auto 时，沙箱：

• 无法访问网络 — git push 会失败，并显示 "Could not resolve host"
• 文件系统受限 — 无法写入 ~/nuri_workspace 等路径

心跳检测改进

心跳应检查以下内容：

1. Shell 提示符处于空闲状态 — 如果 tmux 窗格显示 username@hostname path %，则表示工作进程已完成
2. 尚未推送的提交 — git log @{u}.. --oneline 会显示尚未推送到远程仓库的提交
3. 推送失败 — 在输出中查找 "Could not resolve host"

检测到这些情况后，编排器（而不是工作进程）应：

1. 在沙箱外推送提交
2. 通过 gh pr create 创建 PR
3. 更新清单并发送通知

推荐模式

# In heartbeat, for each task:
cd /tmp/orchestrator-*/task-tN
if tmux capture-pane shows shell prompt; then
  # Worker finished, check for unpushed work
  if git log @{u}.. --oneline | grep -q .; then
    git push -u origin HEAD
    gh pr create --title "$(git log --format=%s -1)" --body "Closes #N" --base main
  fi
fi