From 9e54175449d062a4b3c147b4c6366c47f7642d9a Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 13:56:21 +0800
Subject: [PATCH] feat: skills - emit auto-tmux remote metadata

---
 skills/auto-tmux/SKILL.md                     |  2 +-
 skills/auto-tmux/references/automation.md     |  2 +-
 .../auto-tmux/references/iteration-roadmap.md |  5 +--
 skills/auto-tmux/references/session-safety.md |  1 +
 skills/auto-tmux/scripts/README.md            |  3 +-
 skills/auto-tmux/scripts/remote-readonly.sh   | 31 ++++++++++++++++++-
 .../auto-tmux/scripts/validate-auto-tmux.sh   | 24 ++++++++++++++
 7 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md
index a6dc1b2..40d7d82 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -291,7 +291,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `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 输出
+- `scripts/remote-readonly.sh`: 通过 SSH 只读采集远端 tmux 拓扑、pane 输出和 `metadata.jsonl`
 - `scripts/record-summary.sh`: 汇总 pane 录制日志并生成复盘摘要
 - `scripts/completion.bash`: Bash completion，补全 `auto-tmux.sh` 与 `swarm-state.sh`
 - `scripts/safety-check.sh`: 发送/粘贴/分发前检查危险命令、敏感信息和过大 payload
diff --git a/skills/auto-tmux/references/automation.md b/skills/auto-tmux/references/automation.md
index c56f2b9..4fc2795 100644
--- a/skills/auto-tmux/references/automation.md
+++ b/skills/auto-tmux/references/automation.md
@@ -42,7 +42,7 @@
 | `swarm-report-pack.sh` | 聚合多个只读报告与 JSONL 导出 | 只写显式输出目录 |
 | `swarm-assign.sh` | 生成 ready task 到 worker pane 的分配建议 | 只读，不 claim，不发送 |
 | `swarm-health.sh` | 汇总 tmux 与 swarm state 健康报告 | 只读，不自动修复 |
-| `remote-readonly.sh` | SSH 只读采集远端 tmux 证据 | 不发送按键，输出默认脱敏 |
+| `remote-readonly.sh` | SSH 只读采集远端 tmux 证据 | 不发送按键，输出默认脱敏，生成 `metadata.jsonl` |
 | `record-summary.sh` | 汇总 pane 录制日志 | 只读，输出默认脱敏 |
 | `completion.bash` | Bash 子命令和常用参数补全 | 只定义 shell completion |
 | `swarm-dispatch.sh` | 渲染并可选下发提示词 | 默认只写文件，发送需 `--send` |
diff --git a/skills/auto-tmux/references/iteration-roadmap.md b/skills/auto-tmux/references/iteration-roadmap.md
index af62ecf..7400904 100644
--- a/skills/auto-tmux/references/iteration-roadmap.md
+++ b/skills/auto-tmux/references/iteration-roadmap.md
@@ -37,13 +37,14 @@
 | 29 | `4417e87` | 阻塞报告 | `swarm-blockers.sh` |
 | 30 | `0cabf50` | 报告包 | `swarm-report-pack.sh` |
 | 31 | `565352b` | 远程只读采集 | `remote-readonly.sh` |
-| 32 | `本轮` | session 安全策略 | `session-safety.md` |
+| 32 | `4a35cbc` | session 安全策略 | `session-safety.md` |
+| 33 | `本轮` | 远程证据包增强 | `remote-readonly.sh` 输出 `metadata.jsonl`，validator 覆盖 fake SSH |
 
 ## 后续候选方向
 
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
-| P3 | 远程证据包增强 | 远程只读采集后的 JSONL 摘要与归档元数据 |
+| P3 | 远程证据归档 | 把远程只读证据接入 `swarm-report-pack.sh` 的外部附件索引 |
 
 ## 每轮验收清单
 
diff --git a/skills/auto-tmux/references/session-safety.md b/skills/auto-tmux/references/session-safety.md
index 8fd3600..334d681 100644
--- a/skills/auto-tmux/references/session-safety.md
+++ b/skills/auto-tmux/references/session-safety.md
@@ -54,6 +54,7 @@ skills/auto-tmux/scripts/auto-tmux.sh capture -t "$target" -n 80
 
 - 输出证据默认脱敏；发现 token、API key、password、Bearer、`sk-` 等内容时不在报告中原样保留。
 - 远程采集结果写入显式输出目录，避免混入仓库。
+- 远程证据包必须包含 `index.md`、`remote-tmux.txt` 和 `metadata.jsonl`，便于人工阅读和机器审计。
 - 不把 `/tmp/auto-tmux-*` 证据包直接提交到 Git。
 - 需要分享证据时，优先分享摘要、状态、错误类型和可复现命令，不分享完整 pane 历史。
 
diff --git a/skills/auto-tmux/scripts/README.md b/skills/auto-tmux/scripts/README.md
index 8c2828d..3564ee8 100644
--- a/skills/auto-tmux/scripts/README.md
+++ b/skills/auto-tmux/scripts/README.md
@@ -17,7 +17,7 @@
 - [`swarm-report-pack.sh`](./swarm-report-pack.sh) - 聚合 board、依赖图、时间线、阻塞清单、分配建议和 JSONL 导出。
 - [`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 输出。
+- [`remote-readonly.sh`](./remote-readonly.sh) - 通过 SSH 只读采集远端 tmux 拓扑、pane 输出和 `metadata.jsonl`。
 - [`record-summary.sh`](./record-summary.sh) - 汇总 `record start` 产生的 pane 日志，生成复盘摘要。
 - [`completion.bash`](./completion.bash) - Bash completion，补全 `auto-tmux.sh` 和 `swarm-state.sh` 子命令。
 - [`safety-check.sh`](./safety-check.sh) - 发送、粘贴或分发前检查危险命令、敏感信息和过大 payload。
@@ -95,6 +95,7 @@ skills/auto-tmux/scripts/swarm-health.sh --session ai-hub --swarm-dir /tmp/ai_sw
 
 # 只读采集远端 tmux 证据
 skills/auto-tmux/scripts/remote-readonly.sh --host user@example.com --session ai-hub --out /tmp/auto-tmux-remote --dry-run
+# 真实采集后输出 index.md、remote-tmux.txt 和 metadata.jsonl
 
 # 汇总 pane 录制日志
 skills/auto-tmux/scripts/record-summary.sh --dir /tmp/auto-tmux-records --out /tmp/auto-tmux-record-summary.md
diff --git a/skills/auto-tmux/scripts/remote-readonly.sh b/skills/auto-tmux/scripts/remote-readonly.sh
index 6028040..1e6acc5 100755
--- a/skills/auto-tmux/scripts/remote-readonly.sh
+++ b/skills/auto-tmux/scripts/remote-readonly.sh
@@ -15,6 +15,10 @@ Defaults:
 
 This script is read-only. It runs tmux list/capture commands on the remote host.
 It never sends keys and never mutates remote tmux state.
+Outputs:
+  - remote-tmux.txt: redacted tmux topology and pane output
+  - metadata.jsonl: machine-readable evidence metadata
+  - index.md: human-readable evidence index
 EOF
 }
 
@@ -71,6 +75,16 @@ redact() {
     -e 's/(sk-[A-Za-z0-9_-]{12,})/<redacted-openai-key>/g'
 }
 
+json_escape() {
+  local value="$1"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  value="${value//$'\n'/\\n}"
+  value="${value//$'\r'/\\r}"
+  value="${value//$'\t'/\\t}"
+  printf '%s' "$value"
+}
+
 remote_script='
 set -e
 session_filter="$1"
@@ -103,18 +117,33 @@ if [[ "$dry_run" == "1" ]]; then
 fi
 
 mkdir -p "$out_dir"
+created_at="$(date -Is)"
 ssh "$host" "bash -s" -- "$session" "$lines" <<EOF | redact > "$out_dir/remote-tmux.txt"
 $remote_script
 EOF
 
+evidence_file="$out_dir/remote-tmux.txt"
+evidence_bytes="$(wc -c < "$evidence_file" | tr -d '[:space:]')"
+evidence_lines="$(wc -l < "$evidence_file" | tr -d '[:space:]')"
+if command -v sha256sum >/dev/null 2>&1; then
+  evidence_sha256="$(sha256sum "$evidence_file" | awk '{print $1}')"
+else
+  evidence_sha256=""
+fi
+
+cat > "$out_dir/metadata.jsonl" <<EOF
+{"type":"remote-readonly","created_at":"$(json_escape "$created_at")","host":"$(json_escape "$host")","session":"$(json_escape "${session:-<all>}")","lines":$lines,"evidence_file":"remote-tmux.txt","evidence_bytes":$evidence_bytes,"evidence_lines":$evidence_lines,"evidence_sha256":"$(json_escape "$evidence_sha256")","read_only":true,"redacted":true}
+EOF
+
 cat > "$out_dir/index.md" <<EOF
 # auto-tmux Remote Readonly
 
-- created_at: \`$(date -Is)\`
+- created_at: \`$created_at\`
 - host: \`$host\`
 - session: \`${session:-<all>}\`
 - lines: \`$lines\`
 - evidence: [remote-tmux.txt](./remote-tmux.txt)
+- metadata: [metadata.jsonl](./metadata.jsonl)
 EOF
 
 printf 'remote readonly evidence written: %s\n' "$out_dir"
diff --git a/skills/auto-tmux/scripts/validate-auto-tmux.sh b/skills/auto-tmux/scripts/validate-auto-tmux.sh
index 3763027..6c1a9a2 100755
--- a/skills/auto-tmux/scripts/validate-auto-tmux.sh
+++ b/skills/auto-tmux/scripts/validate-auto-tmux.sh
@@ -76,6 +76,27 @@ run_gate() {
   fi
 }
 
+test_remote_readonly_package() {
+  local tmp_dir fake_bin out_dir
+  tmp_dir="$(mktemp -d)"
+  fake_bin="$tmp_dir/bin"
+  out_dir="$tmp_dir/out"
+  mkdir -p "$fake_bin"
+  cat > "$fake_bin/ssh" <<'EOF'
+#!/usr/bin/env bash
+cat >/dev/null
+printf 'session: ai-hub windows=1 attached=0\n'
+printf '===== [ai-hub:0.0] =====\n'
+printf 'OPENAI_API_KEY=sk-testsecret000000\n'
+EOF
+  chmod +x "$fake_bin/ssh"
+  PATH="$fake_bin:$PATH" "$script_dir/remote-readonly.sh" --host example.com --session ai-hub --out "$out_dir" >/dev/null
+  grep -Fq 'metadata.jsonl' "$out_dir/index.md"
+  grep -Fq '"read_only":true' "$out_dir/metadata.jsonl"
+  grep -Fq '<redacted-openai-key>' "$out_dir/remote-tmux.txt"
+  rm -rf "$tmp_dir"
+}
+
 scripts=(
   "$script_dir/auto-tmux.sh"
   "$script_dir/swarm-state.sh"
@@ -121,6 +142,7 @@ 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
 run_gate "remote-readonly dry-run" "$script_dir/remote-readonly.sh" --host example.com --dry-run
+run_gate "remote-readonly package with fake ssh" test_remote_readonly_package
 run_gate "record-summary help" "$script_dir/record-summary.sh" --help
 run_gate "safety-check help" "$script_dir/safety-check.sh" --help
 run_gate "safety-check clean text" "$script_dir/safety-check.sh" --text "make test"
@@ -157,6 +179,7 @@ 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/session-safety.md" "remote-readonly.sh"
 require_contains "$skill_dir/references/session-safety.md" "远程默认只读"
+require_contains "$skill_dir/references/session-safety.md" "metadata.jsonl"
 require_contains "$script_dir/README.md" "validate-auto-tmux.sh"
 require_contains "$script_dir/README.md" "swarm-dispatch.sh"
 require_contains "$script_dir/README.md" "swarm-watch.sh"
@@ -170,6 +193,7 @@ require_contains "$script_dir/README.md" "swarm-report-pack.sh"
 require_contains "$script_dir/README.md" "swarm-assign.sh"
 require_contains "$script_dir/README.md" "swarm-health.sh"
 require_contains "$script_dir/README.md" "remote-readonly.sh"
+require_contains "$script_dir/README.md" "metadata.jsonl"
 require_contains "$script_dir/README.md" "record-summary.sh"
 require_contains "$script_dir/README.md" "completion.bash"
 require_contains "$script_dir/README.md" "safety-check.sh"