From c314c7f697e34b9bb921384052cd26ec51e6e2ad Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 14:34:55 +0800
Subject: [PATCH] docs: skills - add auto-tmux reading paths

---
 skills/auto-tmux/AGENTS.md                    |  1 +
 skills/auto-tmux/SKILL.md                     |  1 +
 skills/auto-tmux/references/AGENTS.md         |  1 +
 skills/auto-tmux/references/README.md         |  1 +
 skills/auto-tmux/references/index.md          |  1 +
 .../auto-tmux/references/iteration-roadmap.md |  5 +-
 skills/auto-tmux/references/reading-paths.md  | 79 +++++++++++++++++++
 .../auto-tmux/scripts/validate-auto-tmux.sh   |  4 +
 8 files changed, 91 insertions(+), 2 deletions(-)
 create mode 100644 skills/auto-tmux/references/reading-paths.md

diff --git a/skills/auto-tmux/AGENTS.md b/skills/auto-tmux/AGENTS.md
index 289ea56..e7eb335 100644
--- a/skills/auto-tmux/AGENTS.md
+++ b/skills/auto-tmux/AGENTS.md
@@ -48,6 +48,7 @@ skills/auto-tmux/
     ├── session-safety.md
     ├── jsonl-schema.md
     ├── report-pack-review.md
+    ├── reading-paths.md
     ├── swarm-state.md
     ├── prompt-templates.md
     ├── ai-swarm-collaboration.md
diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index 9af9600..5a7be01 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -286,6 +286,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `references/session-safety.md`: 本地 session、远程 SSH 和多 Agent 协作的分层安全边界
 - `references/jsonl-schema.md`: JSONL/manifest 机器可读输出字段约定
 - `references/report-pack-review.md`: report pack reviewer 最短验收路径
+- `references/reading-paths.md`: commander、worker、reviewer、operator 的角色化阅读路线
 - `references/swarm-state.md`: 蜂群状态、任务、锁和报告协议
 - `references/prompt-templates.md`: commander/worker/reviewer 提示词模板和下发方式
 - `references/ai-swarm-collaboration.md`: tmux 蜂群协作历史文档、架构模式、协议、案例和风险限制
diff --git a/skills/auto-tmux/references/AGENTS.md b/skills/auto-tmux/references/AGENTS.md
index 53e9264..8caf236 100644
--- a/skills/auto-tmux/references/AGENTS.md
+++ b/skills/auto-tmux/references/AGENTS.md
@@ -11,4 +11,5 @@
 - SSH/远程 session 规则写入 `session-safety.md`；远程默认只读，不把只读采集扩展成控制入口。
 - 机器可读输出字段约定写入 `jsonl-schema.md`；新增 JSONL/manifest 输出必须同步维护。
 - report pack 审查路径写入 `report-pack-review.md`；新增报告文件时同步更新阅读顺序和通过标准。
+- 角色化阅读路线写入 `reading-paths.md`；新增关键 reference 时同步判断是否进入某个角色路径。
 - 不确定的 tmux 行为必须给出验证命令，不编造。
diff --git a/skills/auto-tmux/references/README.md b/skills/auto-tmux/references/README.md
index 97d84e0..a726209 100644
--- a/skills/auto-tmux/references/README.md
+++ b/skills/auto-tmux/references/README.md
@@ -12,6 +12,7 @@
 | [session-safety.md](./session-safety.md) | 本地 session、远程 SSH 和多 Agent 协作的分层安全边界 |
 | [jsonl-schema.md](./jsonl-schema.md) | JSONL/manifest 机器可读输出字段约定 |
 | [report-pack-review.md](./report-pack-review.md) | report pack reviewer 最短验收路径 |
+| [reading-paths.md](./reading-paths.md) | commander、worker、reviewer、operator 的角色化阅读路线 |
 | [swarm-state.md](./swarm-state.md) | 蜂群状态、任务、锁和报告协议 |
 | [prompt-templates.md](./prompt-templates.md) | commander/worker/reviewer 提示词模板和下发方式 |
 | [ai-swarm-collaboration.md](./ai-swarm-collaboration.md) | tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制 |
diff --git a/skills/auto-tmux/references/index.md b/skills/auto-tmux/references/index.md
index 1e0b1df..bbb3308 100644
--- a/skills/auto-tmux/references/index.md
+++ b/skills/auto-tmux/references/index.md
@@ -9,6 +9,7 @@
 - `session-safety.md`：本地 session、远程 SSH 和多 Agent 协作的分层安全边界
 - `jsonl-schema.md`：JSONL/manifest 机器可读输出字段约定
 - `report-pack-review.md`：report pack reviewer 最短验收路径
+- `reading-paths.md`：commander、worker、reviewer、operator 的角色化阅读路线
 - `swarm-state.md`：蜂群状态、任务、锁和报告协议
 - `prompt-templates.md`：commander/worker/reviewer 提示词模板和下发方式
 - `ai-swarm-collaboration.md`：tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制
diff --git a/skills/auto-tmux/references/iteration-roadmap.md b/skills/auto-tmux/references/iteration-roadmap.md
index 8ae8ac3..d9df3c1 100644
--- a/skills/auto-tmux/references/iteration-roadmap.md
+++ b/skills/auto-tmux/references/iteration-roadmap.md
@@ -49,13 +49,14 @@
 | 41 | `a74be2c` | 交付包审计清单 | `review-checklist.sh` |
 | 42 | `01b4a6f` | 审计清单结果门禁 | `review-checklist.sh --strict` |
 | 43 | `82486a7` | report pack 自检命令 | `verify-report-pack.sh` |
-| 44 | `本轮` | report pack 自检文档 | `report-pack-review.md` |
+| 44 | `d448fdb` | report pack 自检文档 | `report-pack-review.md` |
+| 45 | `本轮` | 文档摘要索引 | `reading-paths.md` |
 
 ## 后续候选方向
 
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
-| P3 | 文档摘要索引 | 为 auto-tmux references 生成角色化阅读路线 |
+| P3 | 操作事故 runbook | 为误发送、误广播、远程采集失败补处理流程 |
 
 ## 每轮验收清单
 
diff --git a/skills/auto-tmux/references/reading-paths.md b/skills/auto-tmux/references/reading-paths.md
new file mode 100644
index 0000000..affa0cd
--- /dev/null
+++ b/skills/auto-tmux/references/reading-paths.md
@@ -0,0 +1,79 @@
+# auto-tmux Reading Paths
+
+本文件按角色给出最短阅读路线，避免所有人从头读完整 references。
+
+## Commander
+
+目标：分配任务、巡检状态、回收证据、决定是否交接。
+
+阅读顺序：
+
+1. `getting_started.md`
+2. `swarm-state.md`
+3. `automation.md`
+4. `report-pack-review.md`
+5. `troubleshooting.md`
+
+关键命令：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-ready --dir /tmp/ai_swarm
+skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-report-pack --tar
+skills/auto-tmux/scripts/verify-report-pack.sh --pack /tmp/ai-swarm-report-pack
+```
+
+## Worker
+
+目标：领取单个任务、执行、写回结果，不越界改动。
+
+阅读顺序：
+
+1. `prompt-templates.md`
+2. `swarm-state.md`
+3. `safety-policy.md`
+4. `session-safety.md`
+
+关键命令：
+
+```bash
+skills/auto-tmux/scripts/swarm-state.sh task-next --owner ai-hub:1.0 --dir /tmp/ai_swarm
+skills/auto-tmux/scripts/swarm-state.sh task-done --id task-001 --owner ai-hub:1.0 --result "make test passed" --dir /tmp/ai_swarm
+```
+
+## Reviewer
+
+目标：只读审查交付包，判断是否可合并、可交接、可复现。
+
+阅读顺序：
+
+1. `report-pack-review.md`
+2. `jsonl-schema.md`
+3. `automation.md`
+4. `troubleshooting.md`
+
+关键命令：
+
+```bash
+skills/auto-tmux/scripts/verify-report-pack.sh --pack /tmp/ai-swarm-report-pack
+skills/auto-tmux/scripts/check-jsonl.sh /tmp/ai-swarm-report-pack/results.jsonl --require-key type --require-key id --require-key status
+```
+
+## Operator
+
+目标：操作 tmux、远程采集、救援卡住的 pane，并控制误操作风险。
+
+阅读顺序：
+
+1. `api.md`
+2. `automation.md`
+3. `session-safety.md`
+4. `safety-policy.md`
+5. `troubleshooting.md`
+
+关键命令：
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
+skills/auto-tmux/scripts/auto-tmux.sh inspect -t ai-hub:1.0 -n 80
+skills/auto-tmux/scripts/remote-readonly.sh --host user@example.com --session ai-hub --out /tmp/auto-tmux-remote --dry-run
+```
diff --git a/skills/auto-tmux/scripts/validate-auto-tmux.sh b/skills/auto-tmux/scripts/validate-auto-tmux.sh
index 5d80256..e2feee4 100755
--- a/skills/auto-tmux/scripts/validate-auto-tmux.sh
+++ b/skills/auto-tmux/scripts/validate-auto-tmux.sh
@@ -234,14 +234,18 @@ require_contains "$skill_dir/references/index.md" "safety-policy.md"
 require_contains "$skill_dir/references/index.md" "session-safety.md"
 require_contains "$skill_dir/references/index.md" "jsonl-schema.md"
 require_contains "$skill_dir/references/index.md" "report-pack-review.md"
+require_contains "$skill_dir/references/index.md" "reading-paths.md"
 require_contains "$skill_dir/references/README.md" "swarm-state.md"
 require_contains "$skill_dir/references/README.md" "safety-policy.md"
 require_contains "$skill_dir/references/README.md" "session-safety.md"
 require_contains "$skill_dir/references/README.md" "jsonl-schema.md"
 require_contains "$skill_dir/references/README.md" "report-pack-review.md"
+require_contains "$skill_dir/references/README.md" "reading-paths.md"
 require_contains "$skill_dir/references/jsonl-schema.md" "swarm-result"
 require_contains "$skill_dir/references/jsonl-schema.md" "remote-readonly"
 require_contains "$skill_dir/references/report-pack-review.md" "verify-report-pack.sh"
+require_contains "$skill_dir/references/reading-paths.md" "Commander"
+require_contains "$skill_dir/references/reading-paths.md" "Reviewer"
 require_contains "$skill_dir/references/session-safety.md" "remote-readonly.sh"
 require_contains "$skill_dir/references/session-safety.md" "远程默认只读"
 require_contains "$skill_dir/references/session-safety.md" "metadata.jsonl"