diff --git a/README.md b/README.md
index d1487d9..0139a20 100644
--- a/README.md
+++ b/README.md
@@ -291,7 +291,8 @@ pip install -r tools/prompts-library/scripts/requirements.txt
**建议阅读顺序(从抽象到落地)**
1. 🔑 元方法论:用“生成器/优化器”的递归闭环让系统自我进化
2. 🧬 拼好码:复用成熟能力,用胶水代码连接、编排、适配业务流程
-3. 🔮 哲学方法论工具箱:把抽象方法论落到可验证、可迭代的工程动作
+3. 🐝 tmux 蜂群协作:用 tmux 让多个 AI 终端可感知、可调度、可救援
+4. 🔮 哲学方法论工具箱:把抽象方法论落到可验证、可迭代的工程动作
🔑 元方法论(点击展开/收起)
@@ -332,6 +333,29 @@ pip install -r tools/prompts-library/scripts/requirements.txt
+
+🐝 tmux 蜂群协作(点击展开/收起)
+
+> 一句话:用 tmux 的 `capture-pane`、`send-keys` 和脚本化封装,让多个 AI 终端从孤立会话变成可巡检、可调度、可救援的协作系统。
+
+传统模式里,人要分别盯住多个 AI 会话;蜂群模式里,人主要定义目标、边界和验收,commander 负责分发与巡检,worker 负责执行单一任务。
+
+| 能力 | 当前入口 | 用途 |
+|:---|:---|:---|
+| 感知 | `auto-tmux.sh capture` / `scan` | 读取单个或多个 pane 输出 |
+| 控制 | `auto-tmux.sh send` | 向明确 target 发送任务或按键 |
+| 救援 | `auto-tmux.sh rescue` | 对等待确认、卡住任务做最小干预 |
+| 记录 | `auto-tmux.sh record` | 为长任务保留审计日志 |
+| 调度 | `auto-tmux.sh hub` | 创建 commander + worker 工作台 |
+
+**使用边界**:这是实验性方法,不是无人值守生产系统。敏感凭证、生产数据库、危险命令和不可逆操作必须人工确认。
+
+👉 [研究判断](docs/research/README.md#research-tmux-ai-swarm)
+👉 [完整技术文档](skills/auto-tmux/references/ai-swarm-collaboration.md)
+👉 [可执行技能入口](skills/auto-tmux/SKILL.md)
+
+
+
🔮 哲学方法论工具箱(点击展开/收起)
diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt
index 132053c..db154b4 100644
--- a/assets/ai-citation/llms-full.txt
+++ b/assets/ai-citation/llms-full.txt
@@ -68,6 +68,8 @@ GEOFlow 的关键启发是:GEO 不是关键词堆砌,而是内容工程链
- docs/references/README.md#reference-technology-stack:常见软件系统技术栈、选型维度、组合案例与初学者学习路径。
- docs/research/README.md:新技术、技术栈、优秀 repo、工程范式和工具趋势研究入口。
- docs/research/README.md#research-harness-engineering:Harness Engineering 的工程控制、评估器与反馈闭环解析。
+- docs/research/README.md#research-tmux-ai-swarm:tmux 蜂群协作的实验性协作范式判断。
+- skills/auto-tmux/references/ai-swarm-collaboration.md:tmux 蜂群协作完整技术文档、架构模式、协议、案例和风险限制。
- docs/workflow/README.md:开发流程、质量门禁、版本控制和文档同步入口。
- docs/workflow/README.md#workflow-development-process:默认任务推进顺序、质量门禁和交付闭环。
- assets/ai-citation/geo-seo-checklist.md:GEO / SEO 内容工程检查清单。
diff --git a/docs/README.md b/docs/README.md
index 95cd9fd..07e8a94 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -63,6 +63,7 @@
- [README](./research/README.md) - 研究笔记索引。
- [AGENTS](./research/AGENTS.md) - 研究笔记目录操作规则。
- [Harness 工程解析](research/README.md#research-harness-engineering) - Harness Engineering 的工程控制、评估器与反馈闭环解析。
+- [tmux 蜂群协作](research/README.md#research-tmux-ai-swarm) - 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。
### workflow
diff --git a/docs/research/README.md b/docs/research/README.md
index 5d943bb..b344092 100644
--- a/docs/research/README.md
+++ b/docs/research/README.md
@@ -12,6 +12,7 @@
## 快速导航
1. [Harness 工程解析](#research-harness-engineering) - 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。
+2. [tmux 蜂群协作](#research-tmux-ai-swarm) - 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。
完整细粒度目录(点击展开/收起)
@@ -19,6 +20,7 @@
### 细粒度目录
- [1. Harness 工程解析](#research-harness-engineering)
+- [2. tmux 蜂群协作](#research-tmux-ai-swarm)
@@ -86,3 +88,105 @@
22. 未来工程师的分化本质是控制权分配:一类在代码生成速度上竞争,另一类在规则、评估、架构与闭环设计上竞争,后者决定系统长期生产力与可维护性
+
+---
+
+
+2. tmux 蜂群协作 - 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。(点击展开/收起)
+
+
+
+## 2. tmux 蜂群协作
+
+> 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式。
+
+### 是什么
+
+tmux 蜂群协作是把多个 AI CLI 会话放进同一个 tmux 工作台,通过 `capture-pane` 读取输出、`send-keys` 发送按键、共享状态文件同步进度,再用脚本封装形成 commander + worker 的多终端协作系统。
+
+在当前仓库中,它不再以旧的 `playbooks/` 目录存在,而是收敛到 `skills/auto-tmux/`:
+
+- 可执行入口:[auto-tmux skill](../../skills/auto-tmux/SKILL.md)
+- 脚本入口:[auto-tmux.sh](../../skills/auto-tmux/scripts/auto-tmux.sh)
+- 完整文档:[AI 蜂群协作](../../skills/auto-tmux/references/ai-swarm-collaboration.md)
+
+### 解决什么问题
+
+1. 多个 AI 会话互相不可见,导致重复工作、信息断裂和人工来回搬运。
+2. AI CLI 卡在确认、报错或长任务等待时,需要人工不断盯屏。
+3. 多任务并行时缺少统一巡检、分工、日志和验收证据。
+4. 多终端协作缺少安全边界,容易误发命令或控制错误窗口。
+
+### 当前判断
+
+这是一种值得保留的实验性方法,但必须脚本化、目标化和门禁化。
+
+推荐路线不是让 AI 直接随意执行 `tmux send-keys`,而是先使用 `skills/auto-tmux/scripts/auto-tmux.sh` 封装:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh hub --session ai-hub --workers 3 --cmd "codex"
+skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
+skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 80
+```
+
+这个封装层能做到:
+
+- 先确认 target 存在。
+- 默认对输出脱敏。
+- 发送前打印目标上下文。
+- 危险命令默认拒绝。
+- 巡检、救援和录制都可重复执行。
+
+### 适用场景
+
+- 多个 AI CLI 并行处理互不冲突的子任务。
+- commander 统一分配任务、巡检 worker、收集证据。
+- 需要观察长时间运行的安装、测试、构建或调试任务。
+- 需要把卡住的低风险确认交给脚本化救援。
+- 需要保留 pane 日志,用于复盘、审计和验收。
+
+### 不适用场景
+
+- 涉及生产数据库、云资源删除、密钥输入和敏感凭证展示。
+- 需要图形界面、复杂交互或强实时反馈的操作。
+- 无法接受误输入、误中断或误控制的任务。
+- 没有明确任务边界、锁、日志和验收标准的多 Agent 并发。
+
+### 采用建议
+
+最小可用结构:
+
+```text
+ai-hub
+├── commander
+├── worker1
+├── worker2
+└── worker3
+```
+
+推荐协议:
+
+1. commander 负责拆任务、巡检、救援和最终验收。
+2. worker 一次只处理一个明确子任务。
+3. 所有发送动作必须使用完整 `:.` target。
+4. 救援先 dry-run,再真实执行。
+5. 长任务必须 record,完成后汇报命令、diff、测试和风险。
+
+### 风险
+
+| 风险 | 说明 | 约束 |
+|:---|:---|:---|
+| 误控 pane | target 错误会向错误窗口发命令 | 先 `topology`,再 `capture` |
+| 死循环 | 多个 AI 互相救援或互相触发 | 设置 commander 单点调度 |
+| 文件冲突 | 多 worker 改同一文件 | 子任务分工和锁机制 |
+| 信息泄露 | capture 读到 token 或密码 | 默认脱敏,隔离敏感会话 |
+| 幻觉放大 | 多 AI 同时错误执行 | 以测试、diff、日志和人工验收兜底 |
+
+### 后续观察点
+
+- 是否需要把 `/tmp/ai_swarm/tasks.json` 标准化为 schema。
+- 是否需要增加 worker 状态机和锁文件脚本。
+- 是否需要接入 GitHub Actions、Prometheus 或本地 Web 面板。
+- 是否需要把 commander / worker prompt 模板独立成可复用 prompt。
+
+
diff --git a/llms.txt b/llms.txt
index 575984e..171fcab 100644
--- a/llms.txt
+++ b/llms.txt
@@ -38,6 +38,8 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程,帮
- docs/references/README.md#reference-engineering-practice
- docs/references/README.md#reference-technology-stack
- docs/research/README.md
+- docs/research/README.md#research-tmux-ai-swarm
+- skills/auto-tmux/references/ai-swarm-collaboration.md
- skills/README.md#当前保留
- prompts/README.md#在线提示词库
- assets/README.md#外部资源在线表格唯一真相源
diff --git a/metadata/taxonomy.yml b/metadata/taxonomy.yml
index e2d844d..7124ee8 100644
--- a/metadata/taxonomy.yml
+++ b/metadata/taxonomy.yml
@@ -138,6 +138,9 @@ documents:
- path: docs/research/README.md#research-harness-engineering
title: Harness 工程解析
role: 工程控制、评估器、反馈闭环与 AI 生成系统可靠性
+ - path: docs/research/README.md#research-tmux-ai-swarm
+ title: tmux 蜂群协作
+ role: 用 tmux 让多个 AI 终端可感知、可调度、可救援的实验性协作范式
workflow:
- path: docs/workflow/README.md#workflow-development-process
title: 开发流程
diff --git a/skills/auto-tmux/AGENTS.md b/skills/auto-tmux/AGENTS.md
index 61b5085..a90856c 100644
--- a/skills/auto-tmux/AGENTS.md
+++ b/skills/auto-tmux/AGENTS.md
@@ -20,6 +20,7 @@ skills/auto-tmux/
├── getting_started.md
├── api.md
├── automation.md
+ ├── ai-swarm-collaboration.md
├── examples.md
└── troubleshooting.md
```
diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index b92e7e8..f9b01ae 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -183,6 +183,7 @@ skills/auto-tmux/scripts/auto-tmux.sh wait -t :. --patter
- `references/getting_started.md`: 术语、oh-my-tmux 最小接入步骤
- `references/api.md`: tmux/oh-my-tmux 常用命令、选项与 gpakosz 特色键位
- `references/automation.md`: `scripts/auto-tmux.sh` 子命令、安全模型与 AI 蜂群协作流程
+- `references/ai-swarm-collaboration.md`: tmux 蜂群协作历史文档、架构模式、协议、案例和风险限制
- `references/examples.md`: 蜂群协议脚本与长示例
- `references/troubleshooting.md`: 典型故障到修复路径
- `scripts/auto-tmux.sh`: 安全封装的 tmux 自动化脚本入口
diff --git a/skills/auto-tmux/references/README.md b/skills/auto-tmux/references/README.md
index 6e4b15f..c228498 100644
--- a/skills/auto-tmux/references/README.md
+++ b/skills/auto-tmux/references/README.md
@@ -8,5 +8,6 @@
| [getting_started.md](./getting_started.md) | 术语、最短路径和工作姿势 |
| [api.md](./api.md) | tmux / oh-my-tmux 常用命令与配置速查 |
| [automation.md](./automation.md) | `auto-tmux.sh` 脚本子命令、安全模型和 AI 蜂群协作流程 |
+| [ai-swarm-collaboration.md](./ai-swarm-collaboration.md) | tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制 |
| [examples.md](./examples.md) | 巡检、救援、审计和多 AI 工作台示例 |
| [troubleshooting.md](./troubleshooting.md) | 常见故障与修复路径 |
diff --git a/skills/auto-tmux/references/ai-swarm-collaboration.md b/skills/auto-tmux/references/ai-swarm-collaboration.md
new file mode 100644
index 0000000..f45b8da
--- /dev/null
+++ b/skills/auto-tmux/references/ai-swarm-collaboration.md
@@ -0,0 +1,377 @@
+# AI 蜂群协作
+
+> 基于 tmux 的多 AI Agent 协作系统设计与实现。
+
+本文从历史文档 `AI蜂群协作-tmux多Agent协作系统.md` 整理而来,并按当前仓库结构升级为
+`auto-tmux` skill 的长期参考资料。当前推荐优先使用
+`skills/auto-tmux/scripts/auto-tmux.sh`,直接 tmux 命令作为兜底。
+
+## 1. 核心思想
+
+传统 AI 编程助手的局限:
+
+- 单一会话,无法感知其他任务。
+- 遇到等待、确认、卡住时需要人工干预。
+- 多任务并行时缺少协调。
+- 多个 AI 容易重复工作、争抢文件或互相覆盖。
+
+tmux 蜂群协作的核心是:让 AI 不再只是孤立会话,而是通过 tmux 获得感知、控制和协调能力。
+
+| 能力 | 实现方式 | 效果 |
+|:---|:---|:---|
+| 感知 | `capture-pane` / `auto-tmux.sh capture` | 读取指定终端输出 |
+| 控制 | `send-keys` / `auto-tmux.sh send` | 向指定终端发送按键或命令 |
+| 巡检 | `auto-tmux.sh scan` | 批量检查多个 pane 状态 |
+| 救援 | `auto-tmux.sh rescue` | 对等待确认、卡住或异常的 pane 做最小干预 |
+| 记录 | `pipe-pane` / `auto-tmux.sh record` | 保留长任务审计日志 |
+| 协调 | 共享状态文件 + 明确 target | 任务同步、分工、避免冲突 |
+
+```text
+传统模式: 人 <-> AI1, 人 <-> AI2, 人 <-> AI3
+
+蜂群模式: 人 -> commander -> worker1 / worker2 / worker3
+ \-> scan / capture / rescue / record
+```
+
+关键突破不是“让 AI 自动乱控终端”,而是把终端控制变成可观察、可定位、可审计、可回滚的工程动作。
+
+## 2. 技术原理
+
+tmux 的基本对象是:
+
+```text
+session
+└── window
+ └── pane
+```
+
+`auto-tmux` 要求所有控制都使用完整 target:
+
+```text
+:.
+```
+
+不要假设 pane 一定是 `.0`。不同 tmux 配置可能让 pane index 从 1 开始。正确做法是先查询拓扑:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
+```
+
+或用原生命令取真实 target:
+
+```bash
+target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
+```
+
+## 3. 最小工作台
+
+创建一个 commander + 3 个 worker 的工作台:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh hub --session ai-hub --workers 3 --cmd "codex"
+```
+
+查看拓扑:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
+```
+
+读取某个 worker:
+
+```bash
+target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
+skills/auto-tmux/scripts/auto-tmux.sh capture -t "$target" -n 120
+```
+
+发送任务:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh send -t "$target" --text "请运行 make test 并汇报失败原因" --enter
+```
+
+等待完成信号:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh wait -t "$target" --pattern "done|完成|Tests passed" --timeout 300
+```
+
+## 4. 协作协议
+
+### 4.1 角色
+
+| 角色 | 职责 |
+|:---|:---|
+| commander | 分配任务、巡检状态、救援卡住任务、汇总结果 |
+| worker | 处理单一明确任务,输出状态、证据、风险和结果 |
+| gate | 测试、lint、CI、脚本、人工确认等外部门禁 |
+
+### 4.2 状态目录
+
+可选共享状态目录:
+
+```text
+/tmp/ai_swarm/
+├── status.log
+├── tasks.json
+├── locks/
+└── results/
+```
+
+最小状态格式:
+
+```text
+[HH:MM:SS] [target] [STATUS] description
+```
+
+常用状态:
+
+```text
+[START] 开始任务
+[DONE] 完成任务
+[WAIT] 等待依赖或确认
+[ERROR] 出现错误
+[HELP] 请求帮助
+[SKIP] 跳过,已有其他 worker 处理
+```
+
+### 4.3 协作规则
+
+1. **先查后做**:开始前先 `topology` / `scan`,确认其他 worker 状态。
+2. **目标明确**:发送命令必须指向明确 target,不使用模糊窗口号。
+3. **单点职责**:一个 worker 一次只处理一个明确任务。
+4. **避免冲突**:涉及同一文件、同一服务、同一配置时先加锁或等待。
+5. **主动救援**:发现等待确认、卡死或明显错误时先 `capture`,再 `rescue --dry-run`。
+6. **保留证据**:长任务开启 `record`,关键检查保存 scan 日志。
+7. **人工兜底**:危险操作、敏感凭证、生产环境变更必须人工确认。
+
+## 5. 架构模式
+
+### 5.1 P2P 对等模式
+
+```text
+worker1 <-> worker2
+ ^ ^
+ | |
+worker3 <-> worker4
+```
+
+适合:简单探索、信息收集、互相巡检。
+
+风险:缺少统一调度,容易重复劳动或互相干扰。
+
+### 5.2 Master-Worker 主从模式
+
+```text
+commander
+├── worker1
+├── worker2
+└── worker3
+```
+
+适合:复杂项目、明确分工、需要统一验收的任务。
+
+当前仓库默认推荐这个模式,因为它更容易控制边界和回收证据。
+
+### 5.3 Pipeline 流水线模式
+
+```text
+analysis -> design -> implementation -> test
+```
+
+适合:有明确阶段的工作,例如需求分析、方案设计、实现、测试。
+
+风险:前一阶段输出质量差会向后传播,需要每阶段设置门禁。
+
+### 5.4 Hybrid 混合模式
+
+```text
+commander
+├── analysis group
+├── implementation group
+└── test group
+```
+
+适合:较大项目,多组并行。
+
+风险:协调成本高,必须有状态记录、锁和强制验收标准。
+
+## 6. 实战流程
+
+### 6.1 多服务并行开发
+
+示例分工:
+
+```text
+commander 任务分配、巡检、验收
+worker1 data-service
+worker2 trading-service
+worker3 telegram-service
+```
+
+巡检:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 100 --save-dir /tmp/auto-tmux-scan
+```
+
+发现错误:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --pattern "ERROR|Traceback|failed"
+```
+
+### 6.2 代码审计 + 自动修复
+
+推荐分工:
+
+```text
+worker1: 审计代码,输出问题列表
+worker2: 根据问题列表修复
+commander: 验收 diff、测试和风险
+```
+
+最小规则:
+
+- 审计 worker 不直接修复。
+- 修复 worker 不扩大范围。
+- commander 只接受有测试、diff 和风险说明的结果。
+
+### 6.3 自动值守
+
+自动值守只能用于低风险场景,例如等待测试、安装确认、日志观察。
+
+推荐先 dry-run:
+
+```bash
+target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
+skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --reply y --dry-run
+```
+
+确认后再执行:
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --reply y
+```
+
+## 7. 提示词模板
+
+### 7.1 Worker 模板
+
+```markdown
+你是 tmux AI 蜂群中的 worker。
+
+你的职责:
+1. 只处理分配给你的单一任务。
+2. 开始前确认任务目标、边界和验收标准。
+3. 执行中保留关键命令、错误和测试结果。
+4. 完成后输出:状态、修改文件、验证结果、风险。
+5. 不主动修改无关文件,不覆盖其他 worker 的成果。
+```
+
+### 7.2 Commander 模板
+
+```markdown
+你是 tmux AI 蜂群中的 commander。
+
+你的职责:
+1. 把总任务拆成互不冲突的 worker 子任务。
+2. 用 topology / scan / capture 读取 worker 状态。
+3. 对卡住任务先 dry-run 救援,再最小干预。
+4. 汇总每个 worker 的产出、测试和风险。
+5. 最终以测试、diff、日志和提交记录作为验收依据。
+```
+
+### 7.3 巡检汇报模板
+
+```markdown
+| target | 状态 | 当前任务 | 证据 | 下一步 |
+|:---|:---|:---|:---|:---|
+| ai-hub:1.1 | running | 执行测试 | 输出 make test | 等待完成 |
+| ai-hub:2.1 | blocked | 等待确认 | 出现 (y/n) | rescue dry-run |
+| ai-hub:3.1 | failed | 构建失败 | Traceback | 分配修复 |
+```
+
+## 8. 最佳实践
+
+### 8.1 命名规范
+
+```text
+session:
+ ai-hub AI 协作工作台
+ dev 开发任务
+ monitor 监控任务
+
+window:
+ commander 指挥官
+ worker1 工作节点 1
+ worker2 工作节点 2
+ worker3 工作节点 3
+```
+
+### 8.2 日志规范
+
+```text
+[time] [target] [START] description
+[time] [target] [DONE] description
+[time] [target] [WAIT] description
+[time] [target] [ERROR] description
+```
+
+### 8.3 安全建议
+
+1. 不自动确认危险操作。
+2. 不在含敏感凭证的 pane 做批量 capture。
+3. 不对未知 target 发送按键。
+4. 广播或同步 pane 后必须立即关闭。
+5. 长任务要记录日志,方便审计。
+6. 任何生产环境操作必须人工确认。
+
+## 9. 风险与限制
+
+| 风险 | 描述 | 缓解措施 |
+|:---|:---|:---|
+| 误操作 | AI 向错误 pane 发送命令 | 使用完整 target,先 topology,再 capture |
+| 死循环 | AI 互相触发或反复救援 | 使用 dry-run、冷却时间和人工确认 |
+| 资源竞争 | 多 worker 同时修改同一文件 | 使用任务锁和明确分工 |
+| 信息泄露 | capture 读到敏感信息 | 默认脱敏,隔离敏感会话 |
+| 架构漂移 | 多 worker 各自为政 | commander 统一验收,门禁拦截 |
+
+不适用场景:
+
+- 需要图形界面的操作。
+- 涉及密码输入、密钥展示或私密生产会话。
+- 高风险数据库、云资源、生产环境变更。
+- 无法容忍误输入或误中断的任务。
+
+## 10. 扩展方向
+
+- 跨机器协作:通过 SSH 包装远程 tmux,但必须先解决权限、审计和网络边界。
+- Web 面板:把 topology、scan、record 状态暴露为只读监控页面。
+- 智能调度:根据 worker 空闲程度、任务类型和失败状态分配任务。
+- CI 集成:让 GitHub Actions 或本地 gate 接收 worker 结果,统一决定是否通过。
+- 状态机治理:用 JSON schema 约束 `/tmp/ai_swarm/tasks.json` 与 `results/`。
+
+## 11. 快速参考
+
+```bash
+# 查看拓扑
+skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
+
+# 扫描状态
+skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 80
+
+# 捕获输出
+skills/auto-tmux/scripts/auto-tmux.sh capture -t -n 120
+
+# 发送任务
+skills/auto-tmux/scripts/auto-tmux.sh send -t --text "任务内容" --enter
+
+# 救援等待确认
+skills/auto-tmux/scripts/auto-tmux.sh rescue -t --pattern "(y/n)" --reply y --dry-run
+skills/auto-tmux/scripts/auto-tmux.sh rescue -t --pattern "(y/n)" --reply y
+
+# 记录日志
+skills/auto-tmux/scripts/auto-tmux.sh record start -t --dir /tmp/auto-tmux-records
+skills/auto-tmux/scripts/auto-tmux.sh record stop -t
+```
diff --git a/skills/auto-tmux/references/index.md b/skills/auto-tmux/references/index.md
index f9f7dcf..336b82d 100644
--- a/skills/auto-tmux/references/index.md
+++ b/skills/auto-tmux/references/index.md
@@ -5,6 +5,7 @@
- `getting_started.md`:术语、最小安装、前缀说明
- `api.md`:tmux/oh-my-tmux 常用命令、同步广播、安全写法
- `automation.md`:`scripts/auto-tmux.sh` 子命令、安全模型与 AI 蜂群协作流程
+- `ai-swarm-collaboration.md`:tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制
- `examples.md`:蜂群巡检脚本、自动救援脚本、Skill Seeker 抓取示例
- `troubleshooting.md`:常见报错与修复路径