Codex Autopilot

Codex Autopilot

基于 tmux + launchd（macOS）的多模型 AI 编程协同系统。

概述

Codex Autopilot 运行一个看门狗循环（watchdog loop），在 tmux 中协调多个 AI 编程会话。其核心特性为 智能任务路由：前端任务（UI、组件、H5）自动路由至 Gemini CLI（支持 1M 上下文窗口，界面设计能力更强），而后端任务（API、数据库、部署）则交由 Codex CLI 处理。该看门狗可检测空闲会话、自动 nudging（轻推）、处理权限提示、从优先级队列中分发任务，并通过 Discord/Telegram 发送通知。

多模型架构

任务依据关键词自动分类并路由至对应模型；当 Gemini 不可用时，前端任务将自动回退至 Codex。

安装

git clone https://github.com/imwyvern/AIWorkFlowSkill.git ~/.autopilot
cd ~/.autopilot
cp config.yaml.example config.yaml
# 使用您的项目路径、Telegram Bot Token 和 Discord 频道信息编辑 config.yaml

依赖项

• macOS（需支持 launchd，用于定时执行）
• tmux —— 用于管理 Codex 窗口的会话复用器
• Codex CLI（codex）—— OpenAI 的编程智能体
• python3 —— 用于状态清理及 PRD 验证脚本
• yq —— YAML 解析器，用于配置文件读取
• jq —— JSON 解析器，用于状态管理
• bash 4+ —— 脚本中使用关联数组所必需

通过 Homebrew 安装依赖：

brew install tmux yq jq

launchd 配置

使用 install.sh 注册 launchd plist：

./install.sh

该操作将创建一个 LaunchAgent，在可配置的时间间隔内运行看门狗进程。

核心组件

watchdog.sh

主循环引擎。每次 tick 执行以下操作：

1. 遍历配置中指定的所有项目对应的 tmux 窗口
2. 通过 codex-status.sh 获取当前 Codex 输出
3. 判定会话状态（活跃 / 空闲 / 卡住）
4. 执行相应动作（nudge、授予权限、从队列分发任务）
5. 实施冷却期限制、每日发送上限与循环检测机制

codex-status.sh

捕获并分析 tmux pane 内容，识别：

• Codex 当前活动状态（working / idle / waiting for permission）
• 需要人工批准的权限提示
• 上下文压缩信号（context compaction signals）
• 错误状态与崩溃情形

tmux-send.sh

向指定 tmux 窗口发送按键或文本，支持：

• 向 Codex 提示符输入文本
• 按 Enter 或其他键以确认权限请求
• 发送后轮询验证是否成功

autopilot-lib.sh

所有脚本共用的函数库，包含：

• Telegram 通知辅助函数
• 文件锁原语（file locking primitives）
• 超时与重试逻辑
• 日志记录工具
• 状态文件读写封装

autopilot-constants.sh

定义全脚本通用的状态常量（例如 STATUS_ACTIVE、STATUS_IDLE、STATUS_PERMISSION）。

task-queue.sh

任务队列管理器，支持：

• 为特定项目入队任务
• 按优先级出队下一个任务
• 跟踪任务状态（pending / running / done / failed）

discord-notify.sh

通过 Webhook 向 Discord 频道发送格式化通知；支持在 config.yaml 中定义的「项目 → 频道」映射路由。

test-agent.sh

内置 CI/CD 模块，每次提交均自动触发。执行测试套件、追踪覆盖率，并在测试失败时 自动入队 bugfix 类任务：

commit → watchdog 检测 → test-agent 执行评估
  ├─ 全部通过 → review 通过 → 对低覆盖率文件入队 coverage 补充任务
  └─ 出现失败 → 解析日志 → 自动入队 "fix(test): ..." 类型的修复任务
       └─ 单文件每小时限 1 次（防止重试循环）

触发时机：

• on_commit_evaluate —— 每次新提交时
• on_review_clean —— 代码审查通过后
• nightly —— 定时全量评估（默认时间 02:30）

覆盖率约束（Coverage ratchet）：
全局覆盖率不得下降；周目标提升 +1%，上限封顶为 90%。

其他脚本

配置说明

编辑 config.yaml（从 config.yaml.example 复制而来）。关键配置节如下：

时间阈值

active_threshold: 120    # 秒 —— Codex 被视为“正在工作”的最短活跃时长
idle_threshold: 360      # 秒 —— Codex 被视为“空闲”，触发 nudging
cooldown: 120            # 同一项目两次发送之间的最小间隔（秒）

安全限制

max_daily_sends_total: 200   # 全局每日最大发送次数
max_daily_sends: 50          # 单个项目每日最大发送次数
max_consecutive_failures: 5  # 连续失败 N 次后暂停该项目
loop_detection_threshold: 3  # 检测重复输出循环的阈值

多项目调度器

scheduler:
  strategy: "round-robin"    # 或 "priority"
  max_sends_per_tick: 1
  inter_project_delay: 5     # 向不同项目发送命令之间的间隔（秒）

项目目录

project_dirs:
  - "~/project-alpha"
  - "~/project-beta"

Gemini 前端任务路由

gemini:
  default_window: "gemini-h5"        # 前端任务默认使用的 tmux 窗口名
  project_windows:
    youxin: "gemini-youxin"          # 按项目定制 Gemini 窗口名

前端任务识别关键词：页面, 组件, 样式, UI, 前端, H5, 小程序, 界面, frontend, component, style, page, layout

Discord 频道路由

discord_channels:
  my-project:
    channel_id: "123456789"
    tmux_window: "my-project"
    project_dir: "/path/to/project"

Telegram 通知

telegram:
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: "YOUR_CHAT_ID"
  status_interval: 1800

使用方法

添加新项目

1. 在命名 tmux 窗口中启动 Codex CLI 会话：

   tmux new-window -t autopilot -n my-project
   # 在新窗口中 cd 至项目目录并运行 codex

2. 将项目路径添加至 config.yaml 的 project_dirs 下

3. （可选）创建 projects/my-project/tasks.yaml 定义任务队列：

   project:
     name: "My Project"
     dir: "~/my-project"
     enabled: true
     priority: 1
   tasks:
     - id: "feature-x"
       name: "Implement feature X"
       prompt: |
         Implement feature X per the spec in docs/feature-x.md

手动操作命令

# 查看所有项目当前状态
./scripts/monitor-all.sh

# 手动 nudging 指定项目
./scripts/auto-nudge.sh my-project

# 向 tmux 窗口发送指令
./scripts/tmux-send.sh my-project "codex exec 'fix the tests'"

# 入队一个后端任务（自动路由至 Codex）
./scripts/task-queue.sh add my-project "Refactor auth module"

# 入队一个前端任务（自动路由至 Gemini）
./scripts/task-queue.sh add my-project "重构登录页面组件" normal --type frontend

# 单次运行看门狗（用于调试）
./scripts/watchdog.sh

Python 版 Autopilot（替代方案）

autopilot.py 提供基于 Python 的替代实现，具备更丰富的状态管理能力：

python3 autopilot.py --once        # 单次执行
python3 autopilot.py --daemon      # 后台守护模式持续运行

目录结构

~/.autopilot/
├── SKILL.md                 # 本文档
├── config.yaml              # 本地配置（不纳入 Git）
├── config.yaml.example      # 配置模板
├── scripts/                 # 所有自动化脚本
├── projects/                # 各项目的任务定义
├── docs/                    # 补充文档
├── code-review/             # 代码审查模板
├── development/             # 开发工作流模板
├── doc-review/              # 文档审查模板
├── doc-writing/             # 文档撰写模板
├── requirement-discovery/   # 需求发现模板
├── testing/                 # 测试模板
├── tests/                   # 测试套件
├── state/                   # 运行时状态（.gitignore）
├── logs/                    # 运行时日志（.gitignore）
├── task-queue/              # 任务队列数据（.gitignore）
└── archive/                 # 已弃用文件