Aegis — CC 会话编排

Aegis 通过 HTTP API（端口 9100）或 MCP 工具管理交互式 Claude Code 会话。每个会话在 tmux 中运行 CC，并带有 JSONL 转录解析和双向通信。

前置条件

1. 1. Aegis 服务器正在运行：curl -s http://127.0.0.1:9100/v1/health
2. MCP 已配置（可选，用于原生工具访问）：参见 scripts/setup-mcp.sh
3. 验证健康状态：bash scripts/health-check.sh

核心工作流

创建 → 发送提示 → 轮询状态 → 处理权限 → 读取结果 → 质量门禁 → 清理

步骤 1：创建会话

MCP：create_session(workDir, name?, prompt?)
HTTP：
bash
SID=$(curl -s -X POST http://127.0.0.1:9100/v1/sessions \
-H Content-Type: application/json \
-d {workDir:/path/to/project,name:task-name} \
| jq -r .id)

⚠️ workDir 必须存在于磁盘上，否则创建会静默失败（返回 null id）。

等待 8-10 秒让 CC 启动。检查响应中的 promptDelivery.delivered — 如果为 false，则在 CC 启动后通过 send_message 重新发送。

步骤 2：发送提示

MCP：send_message(sessionId, text)
HTTP：
bash
curl -s -X POST http://127.0.0.1:9100/v1/sessions/$SID/send \
-H Content-Type: application/json \
-d {text:Your task here}

步骤 3：轮询直到空闲

MCP：get_status(sessionId) — 检查 status 字段
HTTP：
bash
STATUS=$(curl -s http://127.0.0.1:9100/v1/sessions/$SID/read | jq -r .status)

步骤 4：处理权限提示

轮询时，对非空闲状态做出响应：

状态	操作
idle	完成 — 读取结果
working

等待（每 5 秒轮询一次） |
| permission_prompt | POST .../approve（信任文件夹、工具使用） |
| bash_approval | POST .../approve 或 POST .../reject |
| plan_mode | POST .../approve（选项 1）或 POST .../escape |
| ask_question | POST .../send 并附上答案 |
| unknown | GET .../pane 获取原始终端输出 |

步骤 5：读取转录

MCP：get_transcript(sessionId)
HTTP：curl -s http://127.0.0.1:9100/v1/sessions/$SID/read

返回 { messages[], status, statusText }。每条消息：{ role, contentType, text, timestamp }。

步骤 6：质量门禁

在接受输出之前，验证：

1. 1. 检查转录中是否有工具错误或失败的断言
2. 运行 tsc --noEmit 并根据需要通过 send_message 构建
3. 确认测试通过（请求 CC 运行它们）
4. 检查常见问题：缺少导入、硬编码值、不完整的实现

步骤 7：清理

MCP：kill_session(sessionId)
HTTP：curl -s -X DELETE http://127.0.0.1:9100/v1/sessions/$SID

始终进行清理 — 空闲会话会消耗 tmux 窗口和内存。

常见模式

实现问题

create_session(workDir=repo, name=impl-#123, prompt=Implement issue #123. Read the issue description first, then write code. Dont explain, just implement. Run tests when done.)
→ 轮询 → 批准权限 → 读取转录 → 验证测试通过 → 清理

审查 PR

create_session(workDir=repo, name=review-PR-456, prompt=Review PR #456. Focus on: security issues, test coverage, API design. Be concise.)
→ 轮询 → 读取转录 → 提取审查评论

修复 CI

create_session(workDir=repo, name=fix-ci, prompt=CI is failing on main. Run the failing test suite, identify the root cause, and fix it. Dont add skip/only annotations.)
→ 轮询 → 批准 bash 命令 → 验证 CI 通过 → 清理

批量任务

并行生成多个会话，然后轮询所有会话：

bash
for task in task-a task-b task-c; do
curl -s -X POST http://127.0.0.1:9100/v1/sessions \
-H Content-Type: application/json \
-d {\workDir\:\$REPO\,\name\:\$task\,\prompt\:\$task description\} \
| jq -r .id >> /tmp/session-ids.txt
done

轮询所有会话直到完成

while read SID; do ... done < /tmp/session-ids.txt

停滞检测与恢复

当会话处于 working 状态超过 5 分钟且转录无变化时，视为停滞。

检测

bash
HASH1=$(curl -s http://127.0.0.1:9100/v1/sessions/$SID/read | jq -r .messages | length)
sleep 30
HASH2=$(curl -s http://127.0.0.1:9100/v1/sessions/$SID/read | jq -r .messages | length)

如果 HASH1 == HASH2 且状态仍为 working，则可能已停滞

恢复选项（按顺序）

1. 1. 轻推 — 发送 send_message(Continue. Whats blocking you?)
2. 中断 — POST .../interrupt 然后重新发送任务
3. 优化 — 发送简化或分解版本的任务
4. 转向 — 终止会话，使用不同方法创建新会话
5. 升级 — 放弃自动化方法，通知人工

故障排除

问题	修复
9100 端口 Connection refused	Aegis 未运行。检查 scripts/health-check.sh
会话卡在 unknown 状态

GET .../pane 获取原始输出。可能需要 POST .../escape | | 权限循环（持续弹出批准） | 可能是 bash 批准。检查转录中的命令。如果不安全则拒绝 | | promptDelivery: failed | CC 尚未启动。等待 10 秒并通过 send_message 重新发送 | | 会话未出现在 list_sessions 中 | 检查 workDir 过滤器。会话可能已被终止 | | 内存使用过高 | 终止空闲会话。使用 list_sessions 查找孤儿会话 |

MCP 工具参考

当 MCP 配置完成后，原生提供 21 个工具：

会话生命周期

工具	描述
createsession	生成新的 CC 会话（workDir, name, prompt）
listsessions

列出会话，按 status/workDir 过滤 |

| get_status | 详细的会话状态 + 健康信息 | | kill_session | 终止会话 + 清理资源 | | batchcreatesessions | 一次生成多个会话 |

通信

工具	描述
sendmessage	向会话发送文本
sendbash

通过 ! 前缀执行 bash |

| send_command | 发送 /slash 命令 | | get_transcript | 读取对话转录 | | capture_pane | 原始终端输出 | | getsessionsummary | 包含消息计数 + 持续时间的摘要 |

权限处理

工具	描述
approvepermission	批准待处理的提示
rejectpermission

拒绝待处理的提示 |

| escape_session | 发送 Escape 键（关闭对话框） | | interrupt_session | 发送 Ctrl+C |

监控

| 工具 | 描述 | |------|-------------| | server_