agent-manager

Agent Manager

用于在 tmux 会话中管理 AI Agent 的员工 Agent 编排系统。一个简单、依赖精简的 CAO 替代方案。

快速入门

# Project-local install path varies by tool. If `.agent/skills/` doesn't exist, try `.claude/skills/`.
# List all agents
python3 .agent/skills/agent-manager/scripts/main.py list
python3 .claude/skills/agent-manager/scripts/main.py list

# (use the same path you chose above for the remaining commands)
# Start dev agent
python3 .agent/skills/agent-manager/scripts/main.py start dev

# Monitor output (live)
python3 .agent/skills/agent-manager/scripts/main.py monitor dev --follow

# Assign task
python3 .agent/skills/agent-manager/scripts/main.py assign dev <<EOF
Fix the login bug in the auth module
EOF

# Stop agent
python3 .agent/skills/agent-manager/scripts/main.py stop dev

命令路径一致性（文档基准）

为与 README.md 和运行手册示例保持一致，请定义一个 CLI 别名，并在会话中重复使用：

# Installed skill path (pick one that exists)
CLI="python3 .agent/skills/agent-manager/scripts/main.py"
# CLI="python3 .claude/skills/agent-manager/scripts/main.py"

# If operating from a cloned repo instead of installed skill:
# CLI="python3 agent-manager/scripts/main.py"

$CLI doctor
$CLI list
$CLI status EMP_0001

核心概念

Agent 配置

Agent 定义在 agents/EMP_*.md 文件中，使用 YAML frontmatter：

---
name: dev
description: Dev Agent (project-agnostic)
working_directory: ${REPO_ROOT}
launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
launcher_args:
  - cp
  - --dangerously-skip-permissions
skills:
  - review-pr
  - bsc-contract-development
---

# DEV AGENT

## Role and Identity
You are the Dev Agent...

字段：

• name：Agent 标识符（dev、qa）
• description：Agent 描述
• enabled：是否可以启动 Agent（默认为 true，设为 false 可禁用）
• working_directory：默认工作目录（支持 ${REPO_ROOT}）
• launcher：完整路径或提供商名称
• launcher_args：启动器参数
• launcher_config：可选的启动器/提供商专属启动配置
• skills：来自 .agent/skills/ 的技能名称数组（可选，启动时注入）
• schedules：计划任务数组（可选，见“计划任务”部分）
• tmux：可选的 tmux 布局元数据（布局 + 目标窗格）

Tmux 会话

每个 Agent 都在独立的 tmux 会话（agent-{name}）中运行：

• 轻松监控：tmux capture-pane -t agent-dev
• 直接交互：tmux attach -t agent-dev
• 清晰隔离：不污染进程

可选：Tmux 布局

你可以自动创建 tmux 布局，并在指定窗格中启动 Agent：

tmux:
  layout:
    split: h
    panes:
      - {}
      - split: v
        panes:
          - {}
          - {}
  target_pane: "1.1"

说明：

• split：h（左右）或 v（上下）。也支持 horizontal/vertical。
• target_pane：由 . 分隔的路径，路径中的 0/1 是布局树的索引。 0 = 左侧/顶部，1 = 右侧/底部。"1.1" 表示右侧 -> 底部。
• 如果设置了 tmux.layout，则必须设置 tmux.target_pane。

启动器类型

完整路径：本地 Claude Code 启动器

launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
launcher_args: ["cp", "--dangerously-skip-permissions"]

提供商名称：CAO 提供商（可选集成）

launcher: droid
launcher_args: []

提供商名称：OpenAI Codex CLI

launcher: codex
launcher_args:
  - --model=gpt-5.2
launcher_config:
  model_instructions_file: ${REPO_ROOT}/agents/EMP_0001/prompt/shade-main-model.md

launcher_config 是通用的配置入口，用于指定启动器/提供商专属的启动配置。每个 CLI 提供商都会将此扁平映射转换为自身的启动标志（对于 Codex，每个条目都会转换为 -c key=value）。

提供商名称：Kimi Code CLI

launcher: kimi
launcher_args:
  - --auto

Kimi Code 提供商说明：恢复会话时使用 --session <id>；目前通过 tmux 粘贴回退方式注入系统提示词；启动时不会注入 MCP 配置。

使用 launcher: codex 时，如果工作区 Agent 配置中没有提供 launcher_config.model_instructions_file 覆盖项，保留的 main Agent 默认使用 agent-manager/.codex/main-codex-model.md 中的捆绑技能提示词。

注意：对于计划任务，agent-manager 会尽力自动关闭 Codex 首次运行/升级时的模型选择提示，以确保 cron 运行不需要交互。

命令

以下所有示例都假设你已在**命令路径一致性（文档基准）**中定义 $CLI。

list - 列出所有 Agent

显示所有已配置的 Agent 及其状态。

$CLI list              # All agents
$CLI list --running    # Only running

输出：

📋 Agents:

✅ Running dev (session: agent-dev)
   Description: Dev Agent (project-agnostic)
   Working Dir: /home/user/repo
   Skills: review-pr, bsc-contract-development

⭕ Stopped qa
   Description: QA Agent in a multi-agent system
   Working Dir: /home/user/repo/projects/CloudBank-feat-invite-code

⛔ Disabled old-dev
   Description: Legacy Dev Agent (deprecated)
   Working Dir: /home/user/repo

start - 启动 Agent

在 tmux 会话中启动 Agent。

$CLI start dev                      # Use default working_dir
$CLI start dev --working-dir /path   # Override working dir

• 如果 Agent 已在运行，则拒绝启动（一个 Agent 对应一个终端）
• 如果 Agent 已禁用（配置中为 enabled: false），则拒绝启动
• 加载技能并作为系统提示词注入
• 会话名称为 agent-{name}

stop - 停止运行中的 Agent

停止（杀死）Agent 的 tmux 会话。

$CLI stop dev

status - 查看 Agent 状态

显示单个 Agent 的运行时快照，包括运行状态、运行时状态，以及最近的心跳标记/事件。

$CLI status dev

monitor - 监控 Agent 输出

查看 Agent 在 tmux 会话中的输出。

$CLI monitor dev              # Last 100 lines
$CLI monitor dev -n 500       # Last 500 lines
$CLI monitor dev --follow     # Live monitoring (Ctrl+C to stop)

send - 向 Agent 发送消息

向正在运行的 Agent 发送消息/命令。

$CLI send dev "Please run tests"
$CLI send dev --no-enter "Draft message only"

默认情况下，send 会立即提交消息（自动发送 Enter）。 使用 --no-enter 可输入内容但不提交。

message - Agent 间协议消息

编写或发送一个最简 Agent 间协议信封，包含三个部分： 必需的 Meta、必需的 Body，以及可选的纯文本 Footer 回复提示。

# Print an envelope to stdout only
$CLI message compose --from EMP_0001 --to EMP_0017 --body "Review PR #123."

# Send a protocol message through tmux
$CLI message send EMP_0017 --from EMP_0001 --body "Review PR #123." --footer "Reply with QA Verdict: PASS/FAIL."

# Send a protocol reply
$CLI message reply --from EMP_0017 --to EMP_0001 --reply-to msg_20260724_153012_ab12cd34 --body "QA Verdict: PASS"

向可能未安装此协议的 Agent 发送消息时，Footer 应仅包含一句话：Read the agent-manager skill's message protocol and reply with reply_to: msg_20260724_153012_ab12cd34.

信封格式：

--- Meta ---
id: msg_20260724_153012_ab12cd34
type: message
from: EMP_0001
to: EMP_0017

--- Body ---
Review PR #123.

--- Footer ---
Reply with QA Verdict: PASS/FAIL.

Meta 有意保持精简：id、type（message 或 reply）、from、to， 以及回复时可选的 reply_to。Body 为纯文本，可以包含多行。 Footer 是可选的，仅限纯文本，且只应用作回复提示。 为确保跨 Agent 兼容性，优先使用一句话的 Footer，引导接收方查看 agent-manager skill，而不是嵌入协议教程。

此协议是无状态的：它不会创建收件箱／发件箱文件、确认消息、重试、 重放记录或线程日志。命令成功仅表示 tmux 发送操作成功；发送方仍需负责确认送达 并进行处理。

assign - 为 Agent 分配任务

为 Agent 分配任务（如果未运行则启动）。

# From stdin
$CLI assign dev <<EOF
🎯 Task: Fix the login bug

1. Reproduce the issue
2. Identify root cause
3. Implement fix
4. Add tests
EOF

# From file
$CLI assign dev --task-file task.md

assign 会自动提交（默认发送 Enter），因此无需手动执行 tmux Enter 步骤。

禁用 Agent

可以临时禁用 Agent，防止其启动（适用于维护、测试或停用）。

禁用 Agent

在 Agent 的 YAML frontmatter 中添加 enabled: false：

---
name: dev
description: Dev Agent (project-agnostic)
enabled: false  # ← Agent cannot be started
working_directory: ${REPO_ROOT}
launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
---

行为

禁用 Agent 后：

• ⛔ list 命令会显示“已禁用”状态
• ⚠️ start 命令会被拒绝并显示错误消息
• schedule sync 会跳过该 Agent 的所有计划
• 不会自动停止正在运行的会话（需手动停止）

重新启用： 设置 enabled: true 或移除此字段（默认值为 true）

使用场景

• 维护：更新配置时临时禁用 Agent
• 测试：测试期间防止计划任务 Agent 运行
• 停用：移除文件前将 Agent 标记为过时

计划调度

可以使用 cron 表达式配置 Agent，使其按计划自动运行。

计划配置

在 Agent 的 YAML frontmatter 中添加 schedules 数组：

---
name: dev
description: Dev Agent
working_directory: ${REPO_ROOT}
launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
launcher_args:
  - cp
  - --dangerously-skip-permissions
skills:
  - bsc-contract-development

schedules:
  - name: daily-standup
    cron: "0 9 * * 1-5"
    task: |
      Review GitHub issues, prioritize today's work
    max_runtime: 30m

  - name: code-review
    cron: "0 14 * * 1-5"
    task_file: ${REPO_ROOT}/tasks/templates/code-review.md
    max_runtime: 2h

  - name: weekly-report
    cron: "0 17 * * 5"
    task: |
      Generate weekly progress report and commit to docs/
    max_runtime: 1h
    enabled: true
---

计划字段：

字段	类型	必填	说明
name	string	✓	唯一的任务标识符
cron	string	✓	Cron 表达式（例如，0 9 * * 1-5）
task	string	△	内联任务描述
task_file	string	△	任务文件路径（支持 ${REPO_ROOT}）
max_runtime	string		最长运行时间（例如，30m、2h、8h）
enabled	bool		默认值：true

注意：必须提供 task 或 task_file。

计划命令

schedule list - 列出所有计划任务

$CLI schedule list

输出：

📅 Scheduled Jobs:

dev (EMP_0001):
  ✓ daily-standup         0 9 * * 1-5          (30m)
  ✓ code-review           0 14 * * 1-5         (2h)
  ✓ weekly-report         0 17 * * 5           (1h)

qa (EMP_0002):
  ✓ nightly-tests         0 2 * * *            (4h)

schedule sync - 将计划同步到 Crontab

将所有 Agent 计划同步到系统 Crontab。

# Preview changes (dry run)
$CLI schedule sync --dry-run

# Apply changes
$CLI schedule sync

这会生成如下 Crontab 条目：

# === agent-manager schedules (auto-generated) ===
# dev (EMP_0001)
# daily-standup
0 9 * * 1-5 cd /path/to/repo && python3 /absolute/path/to/agent-manager/scripts/main.py schedule run dev --job daily-standup >> /tmp/agent-emp-0001-daily-standup.log 2>&1
# === end agent-manager schedules ===

schedule run - 手动运行计划任务

手动触发计划任务（适用于测试）。

$CLI schedule run dev --job daily-standup

# Override timeout
$CLI schedule run dev --job daily-standup --timeout 1h

心跳

心跳是一种特殊的定期任务，会向正在运行的 Agent 发送标准签到消息。与计划任务（每个 Agent 可有多个）不同，每个 Agent 最多只能配置 0 或 1 个心跳。

Heartbeat 配置

在 Agent 的 YAML frontmatter 中添加一个 heartbeat 字典：

---
name: dev
description: Dev Agent
working_directory: ${REPO_ROOT}
launcher: codex
launcher_args:
  - --model=gpt-4.7
  - --dangerously-bypass-approvals-and-sandbox

heartbeat:
  cron: "*/30 * * * *"  # Every 30 minutes
  max_runtime: 5m
  session_mode: auto     # restore | auto | fresh
  mode: normal           # normal (use `timer` for delayed rescue; `full_speed` is legacy)
  dream:
    enabled: true
    idle_after: 1h       # Optional idle-window trigger after normal HEARTBEAT_OK cycles
    max_runtime: 30m
    fixed_windows:       # During these windows heartbeat dispatch sends DREAM.md tasks
      - timezone: Asia/Shanghai
        start: "23:00"
        end: "08:00"
  enabled: true
---

Heartbeat 字段：

字段	类型	必填	描述
cron	string	✓	Cron 表达式（例如，*/30 * * * *）
max_runtime	string		最大运行时间（例如，5m、10m）
session_mode	string		会话策略：restore（默认）、auto（上下文低于 25% 时轮换）、fresh（交接后始终轮换）
mode	string		Heartbeat 触发模式。normal 是唯一的有效路径。full_speed 是已弃用的兼容值，仅用于在 start 期间保留旧版 Codex hook 的清理和回读行为；由计时器驱动的后续操作是受支持的替代方案。
auto_starvation_skip_threshold	int		仅适用于 auto 模式。默认值为 3；设为 0 可禁用连续跳过预检后强制分发的饥饿绕过机制
dream	dict		可选的 Dream 模式策略。idle_after 保留现有的 Heartbeat 后 Dream 计时器行为；fixed_windows 则会在任意已配置的时间窗口生效期间，将 Heartbeat 分发切换为 Dream 任务。
enabled	bool		默认值：true

现在应将 full_speed 视为旧版兼容标记，而不是规范的执行路径。如果仍存在旧版 Codex Stop hook，start 会将其清理；新的延迟后续操作／救援流程应使用 timer。

固定 Dream 时间窗口

当 heartbeat.dream.enabled 为 true，且当前墙上时钟时间处于任意 heartbeat.dream.fixed_windows 规则范围内时，heartbeat run 会发送标准的 Dream 提示词，而不是标准的 Heartbeat 提示词：

Read DREAM.md if it exists ... If nothing worth doing emerges, reply DREAM_OK.

固定时间窗口支持 timezone、start、end、work_days、holidays、 extra_workdays 和 when。支持跨夜时间范围（23:00 → 08:00）。如果省略 work_days，固定 Dream 时间窗口默认适用于一周七天。多个时间窗口采用 OR 规则：第一个生效的时间窗口优先。

Heartbeat 与 Schedules

功能	Heartbeat	Schedules
每个 Agent	0-1 个 Heartbeat	0-N 个 Schedule
任务内容	固定（标准签到）	每个作业自定义
行为	仅检查正在运行的 Agent	必要时启动 Agent
适用场景	定期健康检查	任务自动化

Heartbeat 命令

heartbeat list - 列出所有 Heartbeat 作业

$CLI heartbeat list

输出：

💓 Heartbeats:

dev (EMP_0001):
  ✓ heartbeat           */30 * * * *         (5m session:auto)

heartbeat sync - 将 Heartbeat 同步到 Crontab

Heartbeat 和 Schedule 会一起同步到系统 crontab。

# Preview changes (dry run)
$CLI heartbeat sync --dry-run

# Apply changes
$CLI heartbeat sync

这会生成类似以下内容的 crontab 条目：

# === agent-manager schedules (auto-generated) ===
# dev (EMP_0001)
# heartbeat [HB]
*/30 * * * * cd /path/to/repo && python3 /absolute/path/to/agent-manager/scripts/main.py heartbeat run EMP_0001 >> /path/to/.crontab_logs/agent-emp-0001-heartbeat.log 2>&1
# === end agent-manager schedules ===

heartbeat run - 手动运行 Heartbeat

手动触发 Heartbeat（便于测试）。

$CLI heartbeat run EMP_0001

# Override timeout
$CLI heartbeat run EMP_0001 --timeout 1m

Heartbeat 行为：

• 如果 Agent 已禁用，则跳过
• 如果 Agent 未运行，则跳过（不会启动 Agent）
• 向 Agent 发送标准 Heartbeat 消息
• 可通过 session_mode 选择会话轮换（先交接，然后开启新会话）
• 等待响应（最长等待时间由 max_runtime 指定）
• 在 auto 模式下，过时的待处理 Heartbeat 可通过由计时器支持的恢复路径安排或触发救援

timer - 安排延迟操作

使用 timer 安排不使用 cron 的一次性延迟操作：

# Run one heartbeat in 5 seconds
$CLI timer heartbeat main --delay 5s

# Schedule one heartbeat rescue in 5 seconds
$CLI timer rescue main --delay 5s --timeout 8m --reason auto_pending_heartbeat_rescue

# Run an arbitrary agent-manager command in 5 seconds
$CLI timer command --delay 5s -- heartbeat run main --timeout 8m

# Inspect recent timers
$CLI timer list

每次运行都会将结构化 JSONL 审计事件追加到：

.claude/state/agent-manager/heartbeat-audit/{agent_id}.jsonl

事件字段（为便于观测而标准化）：

• timestamp
• agent_id
• hb_id
• stage（标准阶段名称，默认值为 heartbeat_attempt）
• result（success / failure / pending）
• duration（毫秒，duration_ms 的别名）
• send_status
• ack_status
• duration_ms
• context_left
• failure_type
• session_mode
• reason_code
• attempt
• recovery_action
• reason_code

失败分类（failure_type）包括：

• send_fail
• no_ack
• timeout
• blocked

heartbeat trace - 查询 Heartbeat 审计日志

# Recent events
$CLI heartbeat trace

# Filter by heartbeat id
$CLI heartbeat trace --hb-id 20260209-120001

# Filter by agent + time range (UTC)
$CLI heartbeat trace   --agent EMP_0001   --since 2026-02-09T00:00:00Z   --until 2026-02-10T00:00:00Z

# Output JSON
$CLI heartbeat trace --agent EMP_0001 --json

heartbeat slo - 每日／每周 SLO 摘要

# Daily summary (default)
$CLI heartbeat slo

# Weekly summary for one agent
$CLI heartbeat slo --window weekly --agent EMP_0001

# Explicit time window + JSON
$CLI heartbeat slo   --since 2026-02-01T00:00:00Z   --until 2026-02-08T00:00:00Z   --json

内置 SLO 检查：

• 成功率目标：>= 99%
• 超时率目标：<= 2%
• 恢复 p95 目标：<= 120000ms

独立摘要脚本（指标相同）：

python3 scripts/heartbeat_slo.py --window daily
python3 scripts/heartbeat_slo.py --window weekly --agent EMP_0001 --json

标准心跳消息

心跳会向 Agent 发送此消息：

Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.

如果无需关注，Agent 应回复 HEARTBEAT_OK；否则应根据其 HEARTBEAT.md 文件内容采取行动。

技能集成

Agent 可以引用 .agent/skills/ 中的技能：

skills:
  - review-pr
  - bsc-contract-development
  - cao

Agent 启动时，技能内容会作为系统提示词注入：

## Available Skills

### review-pr
Code review skill for GitHub PRs and local changes...

### bsc-contract-development
Comprehensive BSC smart contract development expertise...

可用技能：

• bsc-contract-development - BSC 智能合约开发
• cao - 命令行 Agent 编排器
• collab-pr-fix-loop - QA→开发→QA PR 迭代
• review-pr - PR 代码审查
• skill-creator - 创建新技能

架构

.agent/skills/agent-manager/
├── SKILL.md                    # This file
├── scripts/
│   ├── main.py                 # CLI entry point
│   ├── heartbeat_slo.py        # Heartbeat SLO summary script
│   ├── agent_config.py         # Agent file parser
│   ├── tmux_helper.py          # Tmux wrapper
│   └── schedule_helper.py      # Crontab management
├── providers/
│   └── __init__.py             # CLI provider configs
└── references/
    └── task_templates.md       # Optional task templates

设计原则

1. 零 CAO 依赖：仅需 tmux + Python
2. 借鉴 Provider 模式：从 CAO 学习，但以简洁方式实现
3. 原生 Tmux：每个 Agent 都在自己的 tmux 会话中
4. YAML Frontmatter：利用现有的 Agent 文件格式
5. 环境变量：处理 ${REPO_ROOT} 展开
6. 一个 Agent，一个终端：拒绝重复启动

与 CAO 的比较

功能	CAO	Agent Manager
依赖项	CAO 服务、uvx、requests	仅 tmux、Python
复杂度	高（HTTP API、Provider）	低（直接使用 tmux）
会话管理	CAO 服务	原生 tmux
监控	HTTP API 调用	原生 tmux
可扩展性	Provider 系统	直接编辑脚本
安装	配置 CAO 服务	无需服务
使用场景	复杂工作流	简单的 Agent 管理

错误处理

• 未安装 tmux：显示清晰的错误信息和安装命令
• 未找到 Agent：列出可用的 Agent
• 已在运行：提示先停止
• 未在运行：提示先启动

运维手册清单

进行运维交接和事件响应时，请使用：

• agent-manager/docs/runbook-checklist.md

其中包括：

• 新成员 30 分钟自检流程
• 心跳无确认故障排查 SOP
• 卡住的会话恢复 SOP
• CI/QA 合并门禁清单和证据模板

高级用法

直接与 Tmux 交互

# Attach to agent session (interactive)
tmux attach -t agent-dev

# Detach from session: Ctrl+b, then d

# Capture output manually
tmux capture-pane -p -t agent-dev -S -100

# List all agent sessions
tmux ls | grep ^agent-

工作流示例

# Morning: Start agents
$CLI start dev
$CLI start qa

# Assign task to dev
$CLI assign dev <<EOF
Implement the user profile feature:
1. Profile update API
2. Profile view component
3. Integration tests
EOF

# Quick runtime snapshot
$CLI status dev

# Monitor progress
$CLI monitor dev --follow

# Send clarification if needed
$CLI send dev "Please add validation for email format"

# After dev completes, assign to QA
$CLI assign qa <<EOF
Review the user profile feature:
- Security check
- Edge cases
- Test coverage
EOF

# Evening: Stop agents
$CLI stop dev
$CLI stop qa