From b565b038c3371eb8e8e919fc4ff8c7faeaef31c4 Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@users.noreply.github.com>
Date: Tue, 19 May 2026 14:17:38 +0800
Subject: [PATCH] docs: skills - document auto-tmux jsonl schema

---
 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/jsonl-schema.md   | 76 +++++++++++++++++++
 .../auto-tmux/scripts/validate-auto-tmux.sh   |  4 +
 8 files changed, 88 insertions(+), 2 deletions(-)
 create mode 100644 skills/auto-tmux/references/jsonl-schema.md

diff --git a/skills/auto-tmux/AGENTS.md b/skills/auto-tmux/AGENTS.md
index 9b76171..396d251 100644
--- a/skills/auto-tmux/AGENTS.md
+++ b/skills/auto-tmux/AGENTS.md
@@ -44,6 +44,7 @@ skills/auto-tmux/
     ├── automation.md
     ├── safety-policy.md
     ├── session-safety.md
+    ├── jsonl-schema.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 19f3140..9c99675 100644
--- a/skills/auto-tmux/SKILL.md
+++ b/skills/auto-tmux/SKILL.md
@@ -279,6 +279,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `references/automation.md`: `scripts/auto-tmux.sh` 子命令、安全模型与 AI 蜂群协作流程
 - `references/safety-policy.md`: 发送、广播、清理、归档和敏感信息处理的安全策略
 - `references/session-safety.md`: 本地 session、远程 SSH 和多 Agent 协作的分层安全边界
+- `references/jsonl-schema.md`: JSONL/manifest 机器可读输出字段约定
 - `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 d8e83d9..bab71ed 100644
--- a/skills/auto-tmux/references/AGENTS.md
+++ b/skills/auto-tmux/references/AGENTS.md
@@ -9,4 +9,5 @@
 - 示例命令必须优先使用可复制的占位符或 `git rev-parse --show-toplevel` 动态定位仓库根目录。
 - 脚本类说明优先引用 `skills/auto-tmux/scripts/auto-tmux.sh`，再给原生命令兜底。
 - SSH/远程 session 规则写入 `session-safety.md`；远程默认只读，不把只读采集扩展成控制入口。
+- 机器可读输出字段约定写入 `jsonl-schema.md`；新增 JSONL/manifest 输出必须同步维护。
 - 不确定的 tmux 行为必须给出验证命令，不编造。
diff --git a/skills/auto-tmux/references/README.md b/skills/auto-tmux/references/README.md
index b9f9455..bc9f2ae 100644
--- a/skills/auto-tmux/references/README.md
+++ b/skills/auto-tmux/references/README.md
@@ -10,6 +10,7 @@
 | [automation.md](./automation.md) | `auto-tmux.sh` / `swarm-brief.sh` 脚本子命令、安全模型和 AI 蜂群协作流程 |
 | [safety-policy.md](./safety-policy.md) | 发送、广播、清理、归档和敏感信息处理的安全策略 |
 | [session-safety.md](./session-safety.md) | 本地 session、远程 SSH 和多 Agent 协作的分层安全边界 |
+| [jsonl-schema.md](./jsonl-schema.md) | JSONL/manifest 机器可读输出字段约定 |
 | [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 9025164..15ce9ee 100644
--- a/skills/auto-tmux/references/index.md
+++ b/skills/auto-tmux/references/index.md
@@ -7,6 +7,7 @@
 - `automation.md`：`scripts/auto-tmux.sh` / `scripts/swarm-brief.sh` 子命令、安全模型与 AI 蜂群协作流程
 - `safety-policy.md`：发送、广播、清理、归档和敏感信息处理的安全策略
 - `session-safety.md`：本地 session、远程 SSH 和多 Agent 协作的分层安全边界
+- `jsonl-schema.md`：JSONL/manifest 机器可读输出字段约定
 - `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 cdffc8c..1506798 100644
--- a/skills/auto-tmux/references/iteration-roadmap.md
+++ b/skills/auto-tmux/references/iteration-roadmap.md
@@ -44,13 +44,14 @@
 | 36 | `9eac52f` | 报告包压缩 | `swarm-report-pack.sh --tar` |
 | 37 | `ab6d8f2` | worker 结果收敛 | `swarm-results.sh` |
 | 38 | `3b10fb6` | 结果摘要导出 | `swarm-results.sh --jsonl` |
-| 39 | `本轮` | JSONL 字段门禁 | `check-jsonl.sh` |
+| 39 | `842cd2d` | JSONL 字段门禁 | `check-jsonl.sh` |
+| 40 | `本轮` | JSONL 格式治理 | `jsonl-schema.md` |
 
 ## 后续候选方向
 
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
-| P3 | JSONL 格式治理 | 将 remote metadata 和 swarm results 的字段约定写入 reference |
+| P3 | 交付包审计清单 | 为报告包补一页 reviewer 审计 checklist |
 
 ## 每轮验收清单
 
diff --git a/skills/auto-tmux/references/jsonl-schema.md b/skills/auto-tmux/references/jsonl-schema.md
new file mode 100644
index 0000000..2196f40
--- /dev/null
+++ b/skills/auto-tmux/references/jsonl-schema.md
@@ -0,0 +1,76 @@
+# auto-tmux JSONL Schema Notes
+
+本文件记录 `auto-tmux` 机器可读输出的字段约定。当前脚本优先保持零依赖，因此 `scripts/check-jsonl.sh` 只做轻量字段门禁，不替代完整 JSON Schema 校验器。
+
+## swarm-result
+
+来源：`scripts/swarm-results.sh --jsonl`
+
+| 字段 | 含义 |
+|:---|:---|
+| `type` | 固定为 `swarm-result` |
+| `created_at` | 导出时间，ISO 8601 |
+| `swarm_dir` | 状态目录 |
+| `id` | 任务 ID |
+| `status` | `DONE`、`FAIL` 或 `BLOCKED` |
+| `owner` | worker pane 或 owner 标识 |
+| `text` | 任务描述 |
+| `result` | 结果摘要 |
+
+最小门禁：
+
+```bash
+skills/auto-tmux/scripts/check-jsonl.sh /tmp/ai-swarm-results.jsonl \
+  --require-key type \
+  --require-key id \
+  --require-key status
+```
+
+## remote-readonly
+
+来源：`scripts/remote-readonly.sh`
+
+| 字段 | 含义 |
+|:---|:---|
+| `type` | 固定为 `remote-readonly` |
+| `created_at` | 采集时间，ISO 8601 |
+| `host` | SSH host 参数 |
+| `session` | tmux session，未指定时为 `<all>` |
+| `lines` | 每个 pane 采集的行数 |
+| `evidence_file` | 默认 `remote-tmux.txt` |
+| `evidence_bytes` | 脱敏后证据文件字节数 |
+| `evidence_lines` | 脱敏后证据文件行数 |
+| `evidence_sha256` | 脱敏后证据文件 SHA-256；无 `sha256sum` 时为空 |
+| `read_only` | 固定为 `true` |
+| `redacted` | 固定为 `true` |
+
+最小门禁：
+
+```bash
+skills/auto-tmux/scripts/check-jsonl.sh /tmp/auto-tmux-remote/metadata.jsonl \
+  --require-key type \
+  --require-key evidence_file \
+  --require-key read_only \
+  --require-key redacted
+```
+
+## auto-tmux-swarm-report-pack
+
+来源：`scripts/swarm-report-pack.sh`
+
+`manifest.json` 是单个 JSON 对象，不是 JSONL。当前由 `validate-auto-tmux.sh` 直接检查关键字段。
+
+| 字段 | 含义 |
+|:---|:---|
+| `type` | 固定为 `auto-tmux-swarm-report-pack` |
+| `created_at` | 打包时间，ISO 8601 |
+| `swarm_dir` | 状态目录 |
+| `session` | tmux session，未指定时为 `<not provided>` |
+| `files` | 报告包核心文件列表 |
+| `attachments` | 显式 `--attach` 加入的证据目录列表 |
+
+## 维护规则
+
+- 新增机器可读输出时，先写清字段含义，再把最小字段门禁接入 `validate-auto-tmux.sh`。
+- 能用 Bash 轻量检查的字段，用 `check-jsonl.sh` 兜底；需要严格解析时再引入成熟 JSON Schema 工具。
+- 证据字段默认描述脱敏后的文件，不记录原始敏感输出。
diff --git a/skills/auto-tmux/scripts/validate-auto-tmux.sh b/skills/auto-tmux/scripts/validate-auto-tmux.sh
index 49cc6ef..f32dec9 100755
--- a/skills/auto-tmux/scripts/validate-auto-tmux.sh
+++ b/skills/auto-tmux/scripts/validate-auto-tmux.sh
@@ -215,9 +215,13 @@ require_contains "$skill_dir/SKILL.md" "scripts/swarm-dispatch.sh"
 require_contains "$skill_dir/references/index.md" "automation.md"
 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/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/jsonl-schema.md" "swarm-result"
+require_contains "$skill_dir/references/jsonl-schema.md" "remote-readonly"
 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"