6.1 KiB
Swarm State and Lock Protocol
scripts/swarm-state.sh 是 auto-tmux 的最小蜂群状态管理脚本，用于在 tmux 多 AI 协作时记录状态、分配任务、声明锁和汇总报告。
它不依赖数据库、jq 或后台服务，默认把状态写入 /tmp/ai_swarm。需要隔离不同项目时，用 --dir DIR 或环境变量 AUTO_TMUX_SWARM_DIR 指定目录。
文件结构
/tmp/ai_swarm/
├── status.log
├── tasks.tsv
├── locks/
│ └── <name>.lock.d/
│ ├── owner
│ └── created_at
└── results/
└── <task-id>.txt
初始化
skills/auto-tmux/scripts/swarm-state.sh init
指定目录：
skills/auto-tmux/scripts/swarm-state.sh init --dir /tmp/my-ai-swarm
状态日志
写入状态：
skills/auto-tmux/scripts/swarm-state.sh log \
--target "ai-hub:2.1" \
--status START \
--message "开始执行 make test"
查看最近状态：
skills/auto-tmux/scripts/swarm-state.sh status -n 20
状态建议：
| 状态 | 含义 |
|---|---|
START |
开始任务 |
DONE |
完成任务 |
BLOCKED |
阻塞，等待依赖、输入或权限 |
FAIL |
任务失败，需要 commander 处理 |
WAIT |
等待依赖、输入或门禁 |
ERROR |
出现错误 |
HELP |
请求帮助 |
SKIP |
跳过，已有其他 worker 处理 |
LOCK |
获取锁 |
UNLOCK |
释放锁 |
任务管理
新增任务：
skills/auto-tmux/scripts/swarm-state.sh task-add --id task-001 --text "检查 README 链接"
从文本文件批量导入任务：
cat > /tmp/tasks.txt <<'EOF'
- 检查 README 链接
- 运行 make test
- 汇总风险和下一步
EOF
skills/auto-tmux/scripts/swarm-state.sh task-import --file /tmp/tasks.txt --prefix batch
task-import 会跳过空行和 # 注释行，自动去掉行首 - 或 * ，并生成 batch-001 这类任务 ID。
声明任务依赖：
skills/auto-tmux/scripts/swarm-state.sh task-depend --id batch-002 --blocked-by batch-001
skills/auto-tmux/scripts/swarm-state.sh task-ready
task-ready 只列出状态为 TODO 且所有依赖都已经 DONE 的任务，适合 commander 给空闲 worker 分配下一步。
认领任务：
skills/auto-tmux/scripts/swarm-state.sh task-claim --id task-001 --owner "ai-hub:2.1"
领取下一条 TODO 任务：
skills/auto-tmux/scripts/swarm-state.sh task-next --owner "ai-hub:2.1"
task-next 会跳过依赖尚未完成的 TODO 任务；它与 task-ready 使用同一套 blocked-by 判断。
完成任务：
skills/auto-tmux/scripts/swarm-state.sh task-done \
--id task-001 \
--owner "ai-hub:2.1" \
--result "make test passed"
标记阻塞：
skills/auto-tmux/scripts/swarm-state.sh task-block \
--id task-001 \
--owner "ai-hub:2.1" \
--reason "等待用户确认 API key 配置"
标记失败：
skills/auto-tmux/scripts/swarm-state.sh task-fail \
--id task-001 \
--owner "ai-hub:2.1" \
--reason "make test failed"
查看任务：
skills/auto-tmux/scripts/swarm-state.sh task-list
skills/auto-tmux/scripts/swarm-state.sh task-list --status FAIL
skills/auto-tmux/scripts/swarm-state.sh task-list --owner "ai-hub:2.1"
重开失败或阻塞任务：
skills/auto-tmux/scripts/swarm-state.sh task-reopen \
--id task-001 \
--owner "ai-hub:2.1" \
--reason "修复依赖后重新执行"
task-reopen 会把任务状态改回 TODO，同时在状态日志中记录 REOPEN。
校验状态一致性：
skills/auto-tmux/scripts/swarm-state.sh metrics
skills/auto-tmux/scripts/swarm-state.sh validate
skills/auto-tmux/scripts/swarm-board.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-board.md
metrics 会按任务状态、owner 和当前锁数量输出摘要，适合 commander 快速判断蜂群是否堵塞。
validate 会检查 tasks.tsv 表头、字段数量、重复任务 ID、非法状态、终态任务结果文件，以及锁目录中的 owner / created_at。
swarm-board.sh 会把 tasks.tsv、deps.tsv、锁目录和最近状态日志渲染成 Markdown 看板，适合交接给 commander 或 reviewer。
锁管理
锁用于避免多个 worker 同时修改同一文件、目录或服务。
获取锁：
skills/auto-tmux/scripts/swarm-state.sh lock-acquire \
--name "README.md" \
--owner "ai-hub:2.1"
释放锁：
skills/auto-tmux/scripts/swarm-state.sh lock-release \
--name "README.md" \
--owner "ai-hub:2.1"
查看锁：
skills/auto-tmux/scripts/swarm-state.sh lock-list
清理过期锁前先演练：
skills/auto-tmux/scripts/swarm-state.sh lock-prune --older-than 3600 --dry-run
skills/auto-tmux/scripts/swarm-state.sh lock-prune --older-than 3600
锁使用 mkdir 创建目录，具备基本原子性。若锁归属不匹配，默认拒绝释放；确需人工回收时才使用 --force。
lock-prune 用于 worker 崩溃或会话中断后的过期锁回收，必须先 --dry-run 确认目标。
报告
生成汇总报告：
skills/auto-tmux/scripts/swarm-state.sh report
报告包含：
- 任务列表。
- 当前锁。
- 最近状态日志。
报告前建议先运行 validate，避免把坏状态继续传给 commander 或 reviewer。
推荐协作流
- commander 初始化状态目录。
- commander 将任务写入
tasks.tsv。 - worker 获取文件或服务锁。
- worker 用
task-next或task-claim认领任务并写入START。 - worker 执行任务，必要时用
auto-tmux.sh record保留日志。 - worker 完成后写入
DONE和结果；无法继续时写入BLOCKED或FAIL。 - commander 用
report汇总状态，再用测试、diff、日志做验收。
安全边界
swarm-state.sh只管理状态，不直接控制 tmux pane。- 真实发送命令仍必须走
auto-tmux.sh send或auto-tmux.sh rescue。 - 状态文件默认在
/tmp，不保存密钥、Token、密码或私密项目内容。 - 锁只能降低冲突概率，不能替代 Git diff、测试和人工验收。