feat: skills - deepen auto-tmux swarm tooling

2026-08-24 00:08:06 +00:00 · 2026-05-19 02:30:58 +08:00
parent b885ce0e71
commit 3efbaf91a7
13 changed files with 674 additions and 9 deletions
@@ -8,6 +8,7 @@
 | [getting_started.md](./getting_started.md) | 术语、最短路径和工作姿势 |
 | [api.md](./api.md) | tmux / oh-my-tmux 常用命令与配置速查 |
 | [automation.md](./automation.md) | `auto-tmux.sh` 脚本子命令、安全模型和 AI 蜂群协作流程 |
+| [swarm-state.md](./swarm-state.md) | 蜂群状态、任务、锁和报告协议 |
 | [ai-swarm-collaboration.md](./ai-swarm-collaboration.md) | tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制 |
 | [examples.md](./examples.md) | 巡检、救援、审计和多 AI 工作台示例 |
 | [troubleshooting.md](./troubleshooting.md) | 常见故障与修复路径 |
@@ -24,7 +24,7 @@ tmux 蜂群协作的核心是：让 AI 不再只是孤立会话，而是通过 t
 | 巡检 | `auto-tmux.sh scan` | 批量检查多个 pane 状态 |
 | 救援 | `auto-tmux.sh rescue` | 对等待确认、卡住或异常的 pane 做最小干预 |
 | 记录 | `pipe-pane` / `auto-tmux.sh record` | 保留长任务审计日志 |
-| 协调 | 共享状态文件 + 明确 target | 任务同步、分工、避免冲突 |
+| 协调 | `swarm-state.sh` + 明确 target | 任务同步、分工、加锁、避免冲突 |

 ```text
 传统模式: 人 <-> AI1, 人 <-> AI2, 人 <-> AI3
@@ -108,7 +108,13 @@ skills/auto-tmux/scripts/auto-tmux.sh wait -t "$target" --pattern "done|完成|T

 ### 4.2 状态目录

-可选共享状态目录：
+推荐使用 `scripts/swarm-state.sh` 初始化共享状态目录：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh init --dir /tmp/ai_swarm
+```
+
+默认共享状态目录：

 ```text
 /tmp/ai_swarm/
@@ -145,6 +151,33 @@ skills/auto-tmux/scripts/auto-tmux.sh wait -t "$target" --pattern "done|完成|T
 6. **保留证据**：长任务开启 `record`，关键检查保存 scan 日志。
 7. **人工兜底**：危险操作、敏感凭证、生产环境变更必须人工确认。

+### 4.4 任务与锁
+
+添加任务：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-add --id task-001 --text "检查 README 链接"
+```
+
+worker 认领任务：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-claim --id task-001 --owner "ai-hub:2.1"
+```
+
+修改文件前获取锁：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh lock-acquire --name README.md --owner "ai-hub:2.1"
+```
+
+完成后释放锁并记录结果：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh lock-release --name README.md --owner "ai-hub:2.1"
+skills/auto-tmux/scripts/swarm-state.sh task-done --id task-001 --owner "ai-hub:2.1" --result "make test passed"
+```
+
 ## 5. 架构模式

 ### 5.1 P2P 对等模式
@@ -20,6 +20,7 @@
 | `rescue` | pattern 命中后发送确认 | 不命中不发送 |
 | `scan` | 批量巡检 pane 输出 | 可按 session 限定范围 |
 | `record` | 开启/停止 pane 输出审计日志 | 文件写入到显式目录 |
+| `snapshot` | 导出拓扑和 pane 输出证据包 | 默认脱敏，写入显式目录 |
 | `hub` | 初始化 AI 多终端工作台 | 已存在 session 不覆盖 |
 | `wait` | 等待 pane 输出出现某个 pattern | 超时失败 |

@@ -55,6 +56,12 @@ skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --pattern "ERROR|Tra
 skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --save-dir /tmp/auto-tmux-scan
 ```

+生成完整证据快照：
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh snapshot --session ai-hub --dir /tmp/auto-tmux-snapshot -n 120
+```
+
 ### 3. 安全发送命令

 ```bash
@@ -123,11 +130,43 @@ ai-hub
 3. commander 用 `scan` 收集状态，用 `capture` 保留证据。
 4. 需要确认输入时，用 `rescue --dry-run` 先验证 pattern，再真实发送。
 5. 长任务用 `record start` 留日志，结束后 `record stop`。
+6. 多 worker 修改同一文件、目录或服务前，用 `swarm-state.sh lock-acquire` 声明锁。
+
+## 状态与锁脚本
+
+初始化状态目录：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh init --dir /tmp/ai_swarm
+```
+
+添加并认领任务：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-add --id task-001 --text "检查 README 链接"
+skills/auto-tmux/scripts/swarm-state.sh task-claim --id task-001 --owner "ai-hub:2.1"
+```
+
+获取文件锁：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh lock-acquire --name README.md --owner "ai-hub:2.1"
+```
+
+完成任务并生成报告：
+
+```bash
+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 report
+```

 ## 验证命令

 ```bash
 bash -n skills/auto-tmux/scripts/auto-tmux.sh
+bash -n skills/auto-tmux/scripts/swarm-state.sh
 skills/auto-tmux/scripts/auto-tmux.sh help
+skills/auto-tmux/scripts/swarm-state.sh help
+skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict
 ```
@@ -5,6 +5,7 @@
 - `getting_started.md`：术语、最小安装、前缀说明
 - `api.md`：tmux/oh-my-tmux 常用命令、同步广播、安全写法
 - `automation.md`：`scripts/auto-tmux.sh` 子命令、安全模型与 AI 蜂群协作流程
+- `swarm-state.md`：蜂群状态、任务、锁和报告协议
 - `ai-swarm-collaboration.md`：tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制
 - `examples.md`：蜂群巡检脚本、自动救援脚本、Skill Seeker 抓取示例
 - `troubleshooting.md`：常见报错与修复路径
@@ -0,0 +1,149 @@
+# Swarm State and Lock Protocol
+
+`scripts/swarm-state.sh` 是 `auto-tmux` 的最小蜂群状态管理脚本，用于在 tmux 多 AI 协作时记录状态、分配任务、声明锁和汇总报告。
+
+它不依赖数据库、`jq` 或后台服务，默认把状态写入 `/tmp/ai_swarm`。需要隔离不同项目时，用 `--dir DIR` 或环境变量 `AUTO_TMUX_SWARM_DIR` 指定目录。
+
+## 文件结构
+
+```text
+/tmp/ai_swarm/
+├── status.log
+├── tasks.tsv
+├── locks/
+│   └── <name>.lock.d/
+│       ├── owner
+│       └── created_at
+└── results/
+    └── <task-id>.txt
+```
+
+## 初始化
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh init
+```
+
+指定目录：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh init --dir /tmp/my-ai-swarm
+```
+
+## 状态日志
+
+写入状态：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh log \
+  --target "ai-hub:2.1" \
+  --status START \
+  --message "开始执行 make test"
+```
+
+查看最近状态：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh status -n 20
+```
+
+状态建议：
+
+| 状态 | 含义 |
+|:---|:---|
+| `START` | 开始任务 |
+| `DONE` | 完成任务 |
+| `WAIT` | 等待依赖、输入或门禁 |
+| `ERROR` | 出现错误 |
+| `HELP` | 请求帮助 |
+| `SKIP` | 跳过，已有其他 worker 处理 |
+| `LOCK` | 获取锁 |
+| `UNLOCK` | 释放锁 |
+
+## 任务管理
+
+新增任务：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-add --id task-001 --text "检查 README 链接"
+```
+
+认领任务：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-claim --id task-001 --owner "ai-hub:2.1"
+```
+
+完成任务：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-done \
+  --id task-001 \
+  --owner "ai-hub:2.1" \
+  --result "make test passed"
+```
+
+查看任务：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-list
+```
+
+## 锁管理
+
+锁用于避免多个 worker 同时修改同一文件、目录或服务。
+
+获取锁：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh lock-acquire \
+  --name "README.md" \
+  --owner "ai-hub:2.1"
+```
+
+释放锁：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh lock-release \
+  --name "README.md" \
+  --owner "ai-hub:2.1"
+```
+
+查看锁：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh lock-list
+```
+
+锁使用 `mkdir` 创建目录，具备基本原子性。若锁归属不匹配，默认拒绝释放；确需人工回收时才使用 `--force`。
+
+## 报告
+
+生成汇总报告：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh report
+```
+
+报告包含：
+
+- 任务列表。
+- 当前锁。
+- 最近状态日志。
+
+## 推荐协作流
+
+1. commander 初始化状态目录。
+2. commander 将任务写入 `tasks.tsv`。
+3. worker 获取文件或服务锁。
+4. worker 认领任务并写入 `START`。
+5. worker 执行任务，必要时用 `auto-tmux.sh record` 保留日志。
+6. worker 完成后写入 `DONE` 和结果。
+7. commander 用 `report` 汇总状态，再用测试、diff、日志做验收。
+
+## 安全边界
+
+- `swarm-state.sh` 只管理状态，不直接控制 tmux pane。
+- 真实发送命令仍必须走 `auto-tmux.sh send` 或 `auto-tmux.sh rescue`。
+- 状态文件默认在 `/tmp`，不保存密钥、Token、密码或私密项目内容。
+- 锁只能降低冲突概率，不能替代 Git diff、测试和人工验收。