From 33a4f0109901e9e4ba5760ad5f8c447ba6019309 Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 13:58:16 +0800
Subject: [PATCH] feat: skills - attach evidence to auto-tmux reports

---
 skills/auto-tmux/SKILL.md                     |  3 +-
 skills/auto-tmux/references/automation.md     |  3 +-
 .../auto-tmux/references/iteration-roadmap.md |  5 +--
 skills/auto-tmux/scripts/README.md            |  1 +
 skills/auto-tmux/scripts/swarm-report-pack.sh | 33 ++++++++++++++++++-
 .../auto-tmux/scripts/validate-auto-tmux.sh   | 10 ++++++
 6 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index 40d7d82..b8c47d2 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -134,6 +134,7 @@ skills/auto-tmux/scripts/swarm-export.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm
 skills/auto-tmux/scripts/swarm-timeline.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-timeline.md
 skills/auto-tmux/scripts/swarm-blockers.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-blockers.md
 skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-report-pack
+skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-report-pack --attach /tmp/auto-tmux-remote
 skills/auto-tmux/scripts/swarm-assign.sh --swarm-dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-assign.md
 skills/auto-tmux/scripts/swarm-health.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/auto-tmux-health
 skills/auto-tmux/scripts/remote-readonly.sh --host user@example.com --session ai-hub --out /tmp/auto-tmux-remote --dry-run
@@ -288,7 +289,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `scripts/swarm-export.sh`: 导出任务、依赖和锁的 JSONL 状态包
 - `scripts/swarm-timeline.sh`: 渲染 `status.log` 的 Markdown 时间线
 - `scripts/swarm-blockers.sh`: 聚合 BLOCKED/FAIL 任务、锁和最近异常状态
-- `scripts/swarm-report-pack.sh`: 聚合 board、依赖图、时间线、阻塞清单、分配建议和 JSONL 导出
+- `scripts/swarm-report-pack.sh`: 聚合 board、依赖图、时间线、阻塞清单、分配建议、附件和 JSONL 导出
 - `scripts/swarm-assign.sh`: 根据 ready tasks 和 worker pane 生成只读分配建议
 - `scripts/swarm-health.sh`: 汇总 tmux 与 swarm state 的只读健康检查报告包
 - `scripts/remote-readonly.sh`: 通过 SSH 只读采集远端 tmux 拓扑、pane 输出和 `metadata.jsonl`
diff --git a/skills/auto-tmux/references/automation.md b/skills/auto-tmux/references/automation.md
index 4fc2795..32b970d 100644
--- a/skills/auto-tmux/references/automation.md
+++ b/skills/auto-tmux/references/automation.md
@@ -39,7 +39,7 @@
 | `swarm-export.sh` | 导出 JSONL 状态包 | 只读读取 state，写显式输出目录 |
 | `swarm-timeline.sh` | 渲染状态日志时间线 | 只读生成 Markdown |
 | `swarm-blockers.sh` | 聚合阻塞、失败、锁和异常状态 | 只读生成 Markdown |
-| `swarm-report-pack.sh` | 聚合多个只读报告与 JSONL 导出 | 只写显式输出目录 |
+| `swarm-report-pack.sh` | 聚合多个只读报告、附件与 JSONL 导出 | 只写显式输出目录 |
 | `swarm-assign.sh` | 生成 ready task 到 worker pane 的分配建议 | 只读，不 claim，不发送 |
 | `swarm-health.sh` | 汇总 tmux 与 swarm state 健康报告 | 只读，不自动修复 |
 | `remote-readonly.sh` | SSH 只读采集远端 tmux 证据 | 不发送按键，输出默认脱敏，生成 `metadata.jsonl` |
@@ -116,6 +116,7 @@ skills/auto-tmux/scripts/swarm-export.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm
 skills/auto-tmux/scripts/swarm-timeline.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-timeline.md
 skills/auto-tmux/scripts/swarm-blockers.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-blockers.md
 skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-report-pack
+skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-report-pack --attach /tmp/auto-tmux-remote
 skills/auto-tmux/scripts/swarm-assign.sh --swarm-dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-assign.md
 skills/auto-tmux/scripts/swarm-health.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/auto-tmux-health
 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/references/iteration-roadmap.md b/skills/auto-tmux/references/iteration-roadmap.md
index 7400904..ed95a13 100644
--- a/skills/auto-tmux/references/iteration-roadmap.md
+++ b/skills/auto-tmux/references/iteration-roadmap.md
@@ -38,13 +38,14 @@
 | 30 | `0cabf50` | 报告包 | `swarm-report-pack.sh` |
 | 31 | `565352b` | 远程只读采集 | `remote-readonly.sh` |
 | 32 | `4a35cbc` | session 安全策略 | `session-safety.md` |
-| 33 | `本轮` | 远程证据包增强 | `remote-readonly.sh` 输出 `metadata.jsonl`，validator 覆盖 fake SSH |
+| 33 | `ff8cd86` | 远程证据包增强 | `remote-readonly.sh` 输出 `metadata.jsonl`，validator 覆盖 fake SSH |
+| 34 | `本轮` | 报告附件索引 | `swarm-report-pack.sh --attach` |
 
 ## 后续候选方向
 
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
-| P3 | 远程证据归档 | 把远程只读证据接入 `swarm-report-pack.sh` 的外部附件索引 |
+| P3 | 报告包 manifest 增强 | 为 `swarm-report-pack.sh` 输出机器可读 `manifest.json` |
 
 ## 每轮验收清单
 
diff --git a/skills/auto-tmux/scripts/README.md b/skills/auto-tmux/scripts/README.md
index 3564ee8..510dbcd 100644
--- a/skills/auto-tmux/scripts/README.md
+++ b/skills/auto-tmux/scripts/README.md
@@ -86,6 +86,7 @@ skills/auto-tmux/scripts/swarm-blockers.sh --dir /tmp/ai_swarm --out /tmp/ai-swa
 
 # 生成完整报告包
 skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-report-pack
+skills/auto-tmux/scripts/swarm-report-pack.sh --dir /tmp/ai_swarm --out /tmp/ai-swarm-report-pack --attach /tmp/auto-tmux-remote
 
 # 生成 worker 分配建议
 skills/auto-tmux/scripts/swarm-assign.sh --swarm-dir /tmp/ai_swarm --session ai-hub --out /tmp/ai-swarm-assign.md
diff --git a/skills/auto-tmux/scripts/swarm-report-pack.sh b/skills/auto-tmux/scripts/swarm-report-pack.sh
index 1523e53..1c74d68 100755
--- a/skills/auto-tmux/scripts/swarm-report-pack.sh
+++ b/skills/auto-tmux/scripts/swarm-report-pack.sh
@@ -7,13 +7,14 @@ usage() {
 swarm-report-pack: build an auto-tmux swarm report pack
 
 Usage:
-  swarm-report-pack.sh [--dir DIR] [--session NAME] [--out DIR]
+  swarm-report-pack.sh [--dir DIR] [--session NAME] [--out DIR] [--attach DIR ...]
 
 Defaults:
   --dir AUTO_TMUX_SWARM_DIR or /tmp/ai_swarm
   --out /tmp/auto-tmux-report-pack-YYYYmmdd-HHMMSS
 
 This script is read-only for tmux and swarm state. It writes only to --out.
+Use --attach to copy explicit external evidence directories into the report pack.
 EOF
 }
 
@@ -26,6 +27,7 @@ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 swarm_dir="${AUTO_TMUX_SWARM_DIR:-/tmp/ai_swarm}"
 session=""
 out_dir="/tmp/auto-tmux-report-pack-$(date +%Y%m%d-%H%M%S)"
+attachments=()
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -41,6 +43,10 @@ while [[ $# -gt 0 ]]; do
       out_dir="${2:-}"
       shift 2
       ;;
+    --attach)
+      attachments+=("${2:-}")
+      shift 2
+      ;;
     -h|--help)
       usage
       exit 0
@@ -76,6 +82,30 @@ else
   run_report "assign" "$script_dir/swarm-assign.sh" --swarm-dir "$swarm_dir" --out "$out_dir/assign.md"
 fi
 
+attachment_lines=""
+if ((${#attachments[@]} > 0)); then
+  mkdir -p "$out_dir/attachments"
+  cat > "$out_dir/attachments.md" <<EOF
+# Attachments
+
+EOF
+  for attachment in "${attachments[@]}"; do
+    [[ -d "$attachment" ]] || die "attachment is not a directory: $attachment"
+    name="$(basename "$attachment")"
+    safe_name="$(printf '%s' "$name" | tr -c 'A-Za-z0-9._-' '_')"
+    dest="$out_dir/attachments/$safe_name"
+    suffix=1
+    while [[ -e "$dest" ]]; do
+      dest="$out_dir/attachments/${safe_name}_$suffix"
+      suffix=$((suffix + 1))
+    done
+    cp -a "$attachment" "$dest"
+    rel_path="attachments/$(basename "$dest")"
+    printf -- '- [%s](./%s)\n' "$attachment" "$rel_path" >> "$out_dir/attachments.md"
+    attachment_lines+="- [$rel_path](./$rel_path)"$'\n'
+  done
+fi
+
 cat > "$out_dir/index.md" <<EOF
 # auto-tmux Swarm Report Pack
 
@@ -91,6 +121,7 @@ cat > "$out_dir/index.md" <<EOF
 - [blockers.md](./blockers.md)
 - [assign.md](./assign.md)
 - [export/manifest.json](./export/manifest.json)
+$(if [[ -n "$attachment_lines" ]]; then printf '%s' "- [attachments.md](./attachments.md)"; fi)
 EOF
 
 rm -f /tmp/auto-tmux-report-pack.log
diff --git a/skills/auto-tmux/scripts/validate-auto-tmux.sh b/skills/auto-tmux/scripts/validate-auto-tmux.sh
index 6c1a9a2..dbc397c 100755
--- a/skills/auto-tmux/scripts/validate-auto-tmux.sh
+++ b/skills/auto-tmux/scripts/validate-auto-tmux.sh
@@ -138,6 +138,16 @@ run_gate "swarm-export help" "$script_dir/swarm-export.sh" --help
 run_gate "swarm-timeline help" "$script_dir/swarm-timeline.sh" --help
 run_gate "swarm-blockers help" "$script_dir/swarm-blockers.sh" --help
 run_gate "swarm-report-pack help" "$script_dir/swarm-report-pack.sh" --help
+run_gate "swarm-report-pack attachment" bash -c '
+  tmp="$(mktemp -d)"
+  mkdir -p "$tmp/swarm" "$tmp/remote"
+  printf "id\ttext\tstatus\towner\tupdated_at\tresult\n" > "$tmp/swarm/tasks.tsv"
+  printf "remote evidence\n" > "$tmp/remote/remote-tmux.txt"
+  "$1" --dir "$tmp/swarm" --out "$tmp/out" --attach "$tmp/remote" >/dev/null
+  grep -Fq "attachments.md" "$tmp/out/index.md"
+  grep -Fq "remote-tmux.txt" "$tmp/out/attachments/remote/remote-tmux.txt"
+  rm -rf "$tmp"
+' _ "$script_dir/swarm-report-pack.sh"
 run_gate "swarm-assign help" "$script_dir/swarm-assign.sh" --help
 run_gate "swarm-health help" "$script_dir/swarm-health.sh" --help
 run_gate "remote-readonly help" "$script_dir/remote-readonly.sh" --help