docs: skills - document auto-tmux session safety

2026-08-24 16:18:37 +00:00 · 2026-05-19 13:52:15 +08:00
parent eaf9ee56f4
commit 5b15d777d8
10 changed files with 103 additions and 2 deletions
@@ -40,6 +40,8 @@ skills/auto-tmux/
    ├── getting_started.md
    ├── api.md
    ├── automation.md
    ├── safety-policy.md
    ├── session-safety.md
    ├── swarm-state.md
    ├── prompt-templates.md
    ├── ai-swarm-collaboration.md
@@ -73,6 +75,7 @@ skills/auto-tmux/
 - `scripts/validate-auto-tmux.sh` 是技能专属质量门禁，覆盖脚本、文档索引和 smoke test。
 - 技能文档可以引用软链接入口；更新上游内容必须通过 `tools/external/` 下的 submodule 指针完成。
 - 不在本目录直接修改 submodule 内容；如需改造，先 fork 上游并更新 submodule 来源。
 - SSH/远程 session 的默认边界写在 `references/session-safety.md`；不得把 `remote-readonly.sh` 扩展成远程写操作入口。
 ## 依赖关系
@@ -54,6 +54,7 @@ skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict
 - 优先使用 `scripts/auto-tmux.sh`，需要低层调试时再直接使用 tmux 原生命令。
 - 发送按键前必须先 `capture-pane` 复核目标上下文；脚本会默认打印最近上下文。
 - 发送长文本、粘贴文件或下发 prompt 前先运行 `scripts/safety-check.sh`。
 - SSH/远程场景默认只读，先用 `scripts/remote-readonly.sh` 采集证据，再按 `references/session-safety.md` 判断是否需要人工确认升级。
 - 批量操作前必须先列出 session/window/pane 白名单。
 - 多 worker 并发前用 `swarm-state.sh` 管理任务、锁和状态，避免重复修改同一资源。
 - 不在未知 pane 中发送破坏性命令。
@@ -212,6 +212,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - MUST：在发送按键前用 `capture-pane` 复核目标上下文；按键操作必须带 `<session>:<window>.<pane>` 绝对定位。
 - MUST：遵循 oh-my-tmux 约定，不修改主配置文件；自定义写入 `~/.tmux.conf.local`。
 - MUST：批量操作前先 `list-windows`/`list-panes` 建立白名单，避免误控用户窗口。
 - MUST：SSH/远程场景默认只读，先用 `scripts/remote-readonly.sh` 采集证据；远程控制必须另行确认，不从只读脚本升级。
 - SHOULD：救援/确认前先 grep 关键词（如 `(y/n)`、`password`），只对匹配目标发送。
 - SHOULD：发送完整命令行时避免先发 `Escape`；先 `C-c` 中断、`C-u` 清行，再用 `send-keys -l` 逐字发送完整命令。
 - SHOULD：长 prompt、文件粘贴、跨 worker 分发前运行 `scripts/safety-check.sh`，批量发送先 `--dry-run`。
@@ -270,6 +271,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `references/api.md`: tmux/oh-my-tmux 常用命令、选项与 gpakosz 特色键位
 - `references/automation.md`: `scripts/auto-tmux.sh` 子命令、安全模型与 AI 蜂群协作流程
 - `references/safety-policy.md`: 发送、广播、清理、归档和敏感信息处理的安全策略
 - `references/session-safety.md`: 本地 session、远程 SSH 和多 Agent 协作的分层安全边界
 - `references/swarm-state.md`: 蜂群状态、任务、锁和报告协议
 - `references/prompt-templates.md`: commander/worker/reviewer 提示词模板和下发方式
 - `references/ai-swarm-collaboration.md`: tmux 蜂群协作历史文档、架构模式、协议、案例和风险限制
@@ -8,4 +8,5 @@
 - 上游来源统一写为 `tools/external/.tmux`、`tools/external/tmux` 或 `tools/external/Skill_Seekers-development`。
 - 示例命令必须优先使用可复制的占位符或 `git rev-parse --show-toplevel` 动态定位仓库根目录。
 - 脚本类说明优先引用 `skills/auto-tmux/scripts/auto-tmux.sh`，再给原生命令兜底。
 - SSH/远程 session 规则写入 `session-safety.md`；远程默认只读，不把只读采集扩展成控制入口。
 - 不确定的 tmux 行为必须给出验证命令，不编造。
@@ -9,6 +9,7 @@
 | [api.md](./api.md) | tmux / oh-my-tmux 常用命令与配置速查 |
 | [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 协作的分层安全边界 |
 | [swarm-state.md](./swarm-state.md) | 蜂群状态、任务、锁和报告协议 |
 | [prompt-templates.md](./prompt-templates.md) | commander/worker/reviewer 提示词模板和下发方式 |
 | [ai-swarm-collaboration.md](./ai-swarm-collaboration.md) | tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制 |
@@ -9,6 +9,7 @@
 - **拒绝危险动作**：`rm -rf`、`git reset --hard`、`git clean -fd`、`tmux kill-server` 等命令默认拒绝，必须显式 `--force`。
 - **批量动作可解释**：scan/rescue 都基于明确 session、pane、pattern 和 reply，不做无条件广播。
 - **交接报告只读**：brief 汇总 doctor、topology、scan 和 state report，不发送按键、不改变 tmux 状态。
 - **远程默认只读**：SSH 场景使用 `remote-readonly.sh` 采集证据，远程控制规则见 `session-safety.md`。
 - **不改用户配置**：脚本只操作 tmux server，不写 `~/.tmux.conf`；oh-my-tmux 配置仍走 `assets/oh-my-tmux` 参考入口。
 ## 子命令总览
@@ -6,6 +6,7 @@
 - `api.md`：tmux/oh-my-tmux 常用命令、同步广播、安全写法
 - `automation.md`：`scripts/auto-tmux.sh` / `scripts/swarm-brief.sh` 子命令、安全模型与 AI 蜂群协作流程
 - `safety-policy.md`：发送、广播、清理、归档和敏感信息处理的安全策略
 - `session-safety.md`：本地 session、远程 SSH 和多 Agent 协作的分层安全边界
 - `swarm-state.md`：蜂群状态、任务、锁和报告协议
 - `prompt-templates.md`：commander/worker/reviewer 提示词模板和下发方式
 - `ai-swarm-collaboration.md`：tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制
@@ -36,13 +36,14 @@
 | 28 | `c6eeb1f` | 状态时间线 | `swarm-timeline.sh` |
 | 29 | `4417e87` | 阻塞报告 | `swarm-blockers.sh` |
 | 30 | `0cabf50` | 报告包 | `swarm-report-pack.sh` |
-| 31 | `本轮` | 远程只读采集 | `remote-readonly.sh` |
+| 31 | `565352b` | 远程只读采集 | `remote-readonly.sh` |
 | 32 | `本轮` | session 安全策略 | `session-safety.md` |
 ## 后续候选方向
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
-| P3 | session 安全策略 | 远程只读采集后的 SSH 场景规则细化 |
+| P3 | 远程证据包增强 | 远程只读采集后的 JSONL 摘要与归档元数据 |
 ## 每轮验收清单
@@ -0,0 +1,86 @@
 # auto-tmux Session Safety
 本文件定义 `auto-tmux` 在本地 session、远程 SSH session 和多 AI 蜂群协作中的安全边界。核心原则：先只读取证，再决定是否控制；远程默认只读，控制必须回到明确 pane、明确命令、明确验收的本地执行路径。
 ## 分层安全模型
 | 层级 | 典型动作 | 默认策略 | 允许升级条件 |
 |:---|:---|:---|:---|
 | 只读观察 | `topology`、`inspect`、`capture`、`scan`、`snapshot`、`remote-readonly.sh` | 允许 | 不需要升级 |
 | 本地单 pane 控制 | `send`、`paste`、`rescue` | 谨慎允许 | 已确认 target、上下文和 payload |
 | 本地批量控制 | `broadcast`、`swarm-dispatch --send` | 默认 dry-run | 白名单、dry-run、payload 安全检查通过 |
 | session 清理 | `cleanup` | 默认 dry-run | 明确 session 且显式 `--force` |
 | 远程控制 | SSH 后发送按键、执行写操作、清理远端 session | 禁止作为默认路径 | 另行人工确认，不由 `remote-readonly.sh` 执行 |
 ## 远程只读规则
 `scripts/remote-readonly.sh` 只用于采集远端 tmux 证据。它的远端动作必须限定为：
 - `tmux has-session`
 - `tmux list-sessions`
 - `tmux list-windows`
 - `tmux list-panes`
 - `tmux capture-pane`
 禁止把它扩展为：
 - `tmux send-keys`
 - `tmux kill-session`
 - `tmux kill-server`
 - 修改远端 `~/.tmux.conf` 或 shell 配置
 - 执行 `git reset`、`rm`、`docker`、数据库写入等非 tmux 只读命令
 ## 发送前检查
 任何会改变 pane 状态的动作，必须满足：
 1. target 使用 `<session>:<window>.<pane>` 绝对定位。
 2. 先通过 `inspect` 或 `capture` 查看最近输出。
 3. 对长文本、文件和 prompt 运行 `scripts/safety-check.sh`。
 4. 批量发送先 `--dry-run`，确认目标集合后再执行。
 5. 发送后立刻 capture 保存结果，不能只相信命令返回值。
 推荐流程：
 ```bash
 target="ai-hub:1.0"
 skills/auto-tmux/scripts/auto-tmux.sh inspect -t "$target" -n 40
 skills/auto-tmux/scripts/safety-check.sh --text "make test"
 skills/auto-tmux/scripts/auto-tmux.sh send -t "$target" --text "make test" --enter
 skills/auto-tmux/scripts/auto-tmux.sh capture -t "$target" -n 80
 ```
 ## 敏感信息处理
 - 输出证据默认脱敏；发现 token、API key、password、Bearer、`sk-` 等内容时不在报告中原样保留。
 - 远程采集结果写入显式输出目录，避免混入仓库。
 - 不把 `/tmp/auto-tmux-*` 证据包直接提交到 Git。
 - 需要分享证据时，优先分享摘要、状态、错误类型和可复现命令，不分享完整 pane 历史。
 ## 多 Agent 协作边界
 多 Agent 共用 tmux 时，安全问题通常来自“误控”和“重复写”。执行前必须先区分：
 - commander：分配任务、巡检、验收、归档。
 - worker：只处理分配给自己的任务。
 - reviewer：只读审查 worker 产出。
 并发写同一文件、目录或服务前，必须使用 `swarm-state.sh lock-acquire` 声明锁；发现锁冲突时不继续发送任务。
 ## 回滚与复盘
 出现误发送、误广播或错误清理风险时：
 1. 立即停止继续发送。
 2. `capture` 保存目标 pane 的当前输出。
 3. `swarm-blockers.sh` 记录阻塞或失败。
 4. `swarm-archive.sh` 打包证据。
 5. 在任务记录中写明误操作范围、已执行命令、影响对象、修复动作和防复发规则。
 ## 验收
 ```bash
 skills/auto-tmux/scripts/remote-readonly.sh --host example.com --session ai-hub --dry-run
 skills/auto-tmux/scripts/safety-check.sh --text "make test"
 skills/auto-tmux/scripts/validate-auto-tmux.sh
 ```
@@ -151,8 +151,12 @@ require_contains "$skill_dir/SKILL.md" "scripts/safety-check.sh"
 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/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/session-safety.md" "remote-readonly.sh"
 require_contains "$skill_dir/references/session-safety.md" "远程默认只读"
 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"