From b46c412ec2fd51eccb062452210579639559c6fd Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 14:00:02 +0800
Subject: [PATCH] feat: skills - add auto-tmux report manifest

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

diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index b8c47d2..e4a6995 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -289,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、依赖图、时间线、阻塞清单、分配建议、附件和 `manifest.json`
 - `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 32b970d..77c5c85 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 导出 | 生成 `index.md` 和 `manifest.json` |
 | `swarm-assign.sh` | 生成 ready task 到 worker pane 的分配建议 | 只读，不 claim，不发送 |
 | `swarm-health.sh` | 汇总 tmux 与 swarm state 健康报告 | 只读，不自动修复 |
 | `remote-readonly.sh` | SSH 只读采集远端 tmux 证据 | 不发送按键，输出默认脱敏，生成 `metadata.jsonl` |
diff --git a/skills/auto-tmux/references/iteration-roadmap.md b/skills/auto-tmux/references/iteration-roadmap.md
index ed95a13..af433f1 100644
--- a/skills/auto-tmux/references/iteration-roadmap.md
+++ b/skills/auto-tmux/references/iteration-roadmap.md
@@ -39,13 +39,14 @@
 | 31 | `565352b` | 远程只读采集 | `remote-readonly.sh` |
 | 32 | `4a35cbc` | session 安全策略 | `session-safety.md` |
 | 33 | `ff8cd86` | 远程证据包增强 | `remote-readonly.sh` 输出 `metadata.jsonl`，validator 覆盖 fake SSH |
-| 34 | `本轮` | 报告附件索引 | `swarm-report-pack.sh --attach` |
+| 34 | `5677df3` | 报告附件索引 | `swarm-report-pack.sh --attach` |
+| 35 | `本轮` | 报告包 manifest | `swarm-report-pack.sh` 输出根级 `manifest.json` |
 
 ## 后续候选方向
 
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
-| P3 | 报告包 manifest 增强 | 为 `swarm-report-pack.sh` 输出机器可读 `manifest.json` |
+| P3 | 报告包压缩 | 为 `swarm-report-pack.sh` 增加可选 tar.gz 打包 |
 
 ## 每轮验收清单
 
diff --git a/skills/auto-tmux/scripts/README.md b/skills/auto-tmux/scripts/README.md
index 510dbcd..3654a43 100644
--- a/skills/auto-tmux/scripts/README.md
+++ b/skills/auto-tmux/scripts/README.md
@@ -15,6 +15,7 @@
 - [`swarm-timeline.sh`](./swarm-timeline.sh) - 将 `status.log` 渲染为 Markdown 时间线。
 - [`swarm-blockers.sh`](./swarm-blockers.sh) - 聚合 BLOCKED/FAIL 任务、锁和最近异常状态。
 - [`swarm-report-pack.sh`](./swarm-report-pack.sh) - 聚合 board、依赖图、时间线、阻塞清单、分配建议和 JSONL 导出。
+- 报告包根目录会生成 `index.md` 和 `manifest.json`，附件目录通过 `--attach` 显式加入。
 - [`swarm-assign.sh`](./swarm-assign.sh) - 根据 ready tasks 和 worker pane 生成只读分配建议。
 - [`swarm-health.sh`](./swarm-health.sh) - 汇总 doctor、topology、scan、validate、metrics、board 和 assign。
 - [`remote-readonly.sh`](./remote-readonly.sh) - 通过 SSH 只读采集远端 tmux 拓扑、pane 输出和 `metadata.jsonl`。
diff --git a/skills/auto-tmux/scripts/swarm-report-pack.sh b/skills/auto-tmux/scripts/swarm-report-pack.sh
index 1c74d68..5adee15 100755
--- a/skills/auto-tmux/scripts/swarm-report-pack.sh
+++ b/skills/auto-tmux/scripts/swarm-report-pack.sh
@@ -23,11 +23,22 @@ die() {
   exit 1
 }
 
+json_escape() {
+  local value="$1"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  value="${value//$'\n'/\\n}"
+  value="${value//$'\r'/\\r}"
+  value="${value//$'\t'/\\t}"
+  printf '%s' "$value"
+}
+
 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=()
+created_at="$(date -Is)"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -83,6 +94,8 @@ else
 fi
 
 attachment_lines=""
+attachment_json=""
+attachment_count=0
 if ((${#attachments[@]} > 0)); then
   mkdir -p "$out_dir/attachments"
   cat > "$out_dir/attachments.md" <<EOF
@@ -103,13 +116,39 @@ EOF
     rel_path="attachments/$(basename "$dest")"
     printf -- '- [%s](./%s)\n' "$attachment" "$rel_path" >> "$out_dir/attachments.md"
     attachment_lines+="- [$rel_path](./$rel_path)"$'\n'
+    if ((attachment_count > 0)); then
+      attachment_json+=","$'\n'
+    fi
+    attachment_json+="    {\"source\":\"$(json_escape "$attachment")\",\"path\":\"$(json_escape "$rel_path")\"}"
+    attachment_count=$((attachment_count + 1))
   done
 fi
 
+cat > "$out_dir/manifest.json" <<EOF
+{
+  "type": "auto-tmux-swarm-report-pack",
+  "created_at": "$(json_escape "$created_at")",
+  "swarm_dir": "$(json_escape "$swarm_dir")",
+  "session": "$(json_escape "${session:-<not provided>}")",
+  "files": [
+    "index.md",
+    "board.md",
+    "deps.md",
+    "timeline.md",
+    "blockers.md",
+    "assign.md",
+    "export/manifest.json"
+  ],
+  "attachments": [
+$attachment_json
+  ]
+}
+EOF
+
 cat > "$out_dir/index.md" <<EOF
 # auto-tmux Swarm Report Pack
 
-- created_at: \`$(date -Is)\`
+- created_at: \`$created_at\`
 - swarm_dir: \`$swarm_dir\`
 - session: \`${session:-<not provided>}\`
 
@@ -120,6 +159,7 @@ cat > "$out_dir/index.md" <<EOF
 - [timeline.md](./timeline.md)
 - [blockers.md](./blockers.md)
 - [assign.md](./assign.md)
+- [manifest.json](./manifest.json)
 - [export/manifest.json](./export/manifest.json)
 $(if [[ -n "$attachment_lines" ]]; then printf '%s' "- [attachments.md](./attachments.md)"; fi)
 EOF
diff --git a/skills/auto-tmux/scripts/validate-auto-tmux.sh b/skills/auto-tmux/scripts/validate-auto-tmux.sh
index dbc397c..66153c5 100755
--- a/skills/auto-tmux/scripts/validate-auto-tmux.sh
+++ b/skills/auto-tmux/scripts/validate-auto-tmux.sh
@@ -145,6 +145,9 @@ run_gate "swarm-report-pack attachment" bash -c '
   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 "manifest.json" "$tmp/out/index.md"
+  grep -Fq "\"type\": \"auto-tmux-swarm-report-pack\"" "$tmp/out/manifest.json"
+  grep -Fq "\"attachments\"" "$tmp/out/manifest.json"
   grep -Fq "remote-tmux.txt" "$tmp/out/attachments/remote/remote-tmux.txt"
   rm -rf "$tmp"
 ' _ "$script_dir/swarm-report-pack.sh"