From 7beaadb4fc6a85c853a7860dd2e22cce7b817816 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Tue, 19 May 2026 01:58:48 +0800 Subject: [PATCH] feat: skills - add auto-tmux --- AGENTS.md | 2 + README.md | 2 + skills/AGENTS.md | 4 +- skills/README.md | 8 +- skills/auto-tmux/AGENTS.md | 33 ++++ skills/auto-tmux/README.md | 29 +++ skills/auto-tmux/SKILL.md | 176 ++++++++++++++++++ skills/auto-tmux/assets/AGENTS.md | 10 + skills/auto-tmux/assets/README.md | 14 ++ skills/auto-tmux/assets/oh-my-tmux | 1 + skills/auto-tmux/assets/tmux-src | 1 + skills/auto-tmux/references/AGENTS.md | 10 + skills/auto-tmux/references/README.md | 11 ++ skills/auto-tmux/references/api.md | 41 ++++ skills/auto-tmux/references/examples.md | 70 +++++++ .../auto-tmux/references/getting_started.md | 42 +++++ skills/auto-tmux/references/index.md | 14 ++ .../auto-tmux/references/troubleshooting.md | 35 ++++ 18 files changed, 501 insertions(+), 2 deletions(-) create mode 100644 skills/auto-tmux/AGENTS.md create mode 100644 skills/auto-tmux/README.md create mode 100644 skills/auto-tmux/SKILL.md create mode 100644 skills/auto-tmux/assets/AGENTS.md create mode 100644 skills/auto-tmux/assets/README.md create mode 120000 skills/auto-tmux/assets/oh-my-tmux create mode 120000 skills/auto-tmux/assets/tmux-src create mode 100644 skills/auto-tmux/references/AGENTS.md create mode 100644 skills/auto-tmux/references/README.md create mode 100644 skills/auto-tmux/references/api.md create mode 100644 skills/auto-tmux/references/examples.md create mode 100644 skills/auto-tmux/references/getting_started.md create mode 100644 skills/auto-tmux/references/index.md create mode 100644 skills/auto-tmux/references/troubleshooting.md diff --git a/AGENTS.md b/AGENTS.md index a88dd5b..c022a13 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -166,6 +166,7 @@ git push origin develop │ ├── README.md # skills 总览与索引 │ ├── AGENTS.md # skills/ 目录规则 │ ├── auto-skill/ # 元技能核心 +│ ├── auto-tmux/ # tmux 自动化操控与多终端协作 │ └── claude-official-skills/ # Claude 官方 skills 软链接入口 │ ├── assets/ # 静态资产与外部资源入口 @@ -238,6 +239,7 @@ git push origin develop - `docs/references/README.md#reference-engineering-practice` - 项目架构、代码组织、开发经验、底层程序逻辑、AI 编程质量门禁与常见坑的统一入口 - `docs/references/README.md#reference-technology-stack` - 常见软件系统技术栈、选型维度、组合案例与初学者学习路径 - `skills/auto-skill/` - Skills 生成、重构与校验的元技能 +- `skills/auto-tmux/` - tmux 自动化操控、pane 巡检、按键注入与多终端协作技能 ### docs README 结构契约 diff --git a/README.md b/README.md index 0f4f3c5..1a7809d 100644 --- a/README.md +++ b/README.md @@ -501,6 +501,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt * [**Skills 制作器**](https://github.com/yusufkaraaslan/Skill_Seekers): 可根据需求生成定制化 Skills 的工具。 * [**元提示词**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 用于生成提示词的高级提示词。 * [**元技能：Auto Skill**](./skills/auto-skill/SKILL.md): 用于生成、重构与校验 Skills 的元技能。 +* [**auto-tmux**](./skills/auto-tmux/SKILL.md): tmux 自动化操控、pane 巡检、按键注入与多终端协作技能。 * [**Mermaid Chart**](https://www.mermaidchart.com/): 用于将文本描述转换为架构图、序列图等可视化图表。 * [**NotebookLM**](https://notebooklm.google.com/): 一款用于 AI 解读资料、音频和生成思维导图的工具。 * [**Zread**](https://zread.ai/): AI 驱动的 GitHub 仓库阅读工具，有助于快速理解项目代码。 @@ -586,6 +587,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt ├── prompts/ # 提示词库入口（指向云端表格） ├── skills/ # 技能库入口 │ ├── auto-skill/ # 元技能核心 +│ ├── auto-tmux/ # tmux 自动化操控与多终端协作 │ └── claude-official-skills/ # Claude 官方 skills 软链接入口 ├── tools/ # 辅助工具、外部仓库与工具配置 ├── scripts/ # 自动化脚本 diff --git a/skills/AGENTS.md b/skills/AGENTS.md index 81d83e1..f5ac5c1 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -14,7 +14,8 @@ skills/ │ ├── scripts/ # (可选) 可执行脚本/自动化 │ ├── assets/ # (可选) 模板/样例/静态资源 │ └── agents/ # (可选) Agent 元数据（如 openai.yaml） -└── auto-skill/ # 元技能：生成/校验/脚手架化其它技能 +├── auto-skill/ # 元技能：生成/校验/脚手架化其它技能 +└── auto-tmux/ # tmux 自动化操控、pane 巡检与多终端协作 ``` ## 外部仓库引用（约定） @@ -46,5 +47,6 @@ skills/ ## 快速定位（常用技能） - `skills/auto-skill/`：元技能（技能生成/校验/脚手架） +- `skills/auto-tmux/`：tmux 自动化技能；通过 `assets/` 软链接复用 `tools/external/.tmux` 与 `tools/external/tmux` - `skills/claude-official-skills/`：Claude 官方 skills 仓库（Anthropic）的软链接入口 - `skills/auto-skill/scripts/Skill_Seekers-development`：Skill Seekers submodule 的软链接入口 diff --git a/skills/README.md b/skills/README.md index 14a08a5..c00af86 100644 --- a/skills/README.md +++ b/skills/README.md @@ -7,13 +7,15 @@ | 技能 | 说明 | |:---|:---| | [auto-skill](./auto-skill/SKILL.md) | 生成、重构与校验 Skills 的元技能 | +| [auto-tmux](./auto-tmux/SKILL.md) | tmux 自动化操控、pane 巡检、按键注入、蜂群协作和 oh-my-tmux 参考入口 | | [claude-official-skills](./claude-official-skills/) | Claude 官方 skills 仓库的软链接入口，事实来源在 `tools/external/claude-official-skills/` | ## 维护口径 - `auto-skill/` 是本仓库的 Skill 生产与升级入口，继续保留。 +- `auto-tmux/` 是 tmux 自动化与多 AI 终端协作入口，通过软链接复用 `tools/external/.tmux` 与 `tools/external/tmux`。 - `claude-official-skills/` 是外部官方仓库展示入口，通过 submodule 管理事实来源。 -- 领域型/工具型 Skill 如交易、数据库、代理、Telegram、tmux、EPUB 等不在主仓库维护；如需引入，优先使用独立仓库、submodule 或重新生成的方式。 +- 领域型/工具型 Skill 如交易、数据库、代理、Telegram、EPUB 等不在主仓库维护；如需引入，优先使用独立仓库、submodule 或重新生成的方式。 ## 外部技能仓库 @@ -31,6 +33,9 @@ # 查看元技能 cat skills/auto-skill/SKILL.md +# 查看 tmux 自动化技能 +cat skills/auto-tmux/SKILL.md + # 初始化外部 skills 仓库 git submodule update --init --recursive ``` @@ -46,5 +51,6 @@ git submodule update --init --recursive ## 相关资源 - [元技能文件](./auto-skill/SKILL.md) - 生成、重构与校验 Skills +- [auto-tmux](./auto-tmux/SKILL.md) - tmux 自动化操控与多终端协作 - [提示词库](../prompts/) - 更细粒度的提示词集合 - [文档库](../docs/) - 方法论与开发经验 diff --git a/skills/auto-tmux/AGENTS.md b/skills/auto-tmux/AGENTS.md new file mode 100644 index 0000000..79f7a34 --- /dev/null +++ b/skills/auto-tmux/AGENTS.md @@ -0,0 +1,33 @@ +# skills/auto-tmux + +本目录是 tmux 自动化操控技能：面向 AI 终端巡检、按键注入、蜂群协作与 oh-my-tmux 配置复用。 + +## 目录结构 + +```text +skills/auto-tmux/ +├── AGENTS.md # 本文件：目录职责、结构与边界 +├── SKILL.md # 技能入口：触发条件、命令片段、规则与质量门 +├── assets/ # 外部 tmux 相关仓库的只读软链接入口 +│ ├── oh-my-tmux -> ../../../tools/external/.tmux +│ └── tmux-src -> ../../../tools/external/tmux +└── references/ # 长文档、示例与故障排查 + ├── index.md + ├── getting_started.md + ├── api.md + ├── examples.md + └── troubleshooting.md +``` + +## 职责边界 + +- `assets/oh-my-tmux` 只暴露 gpakosz/oh-my-tmux submodule，不在技能目录内复制配置源码。 +- `assets/tmux-src` 只暴露 tmux/tmux submodule，供需要查看源码或上游文档时定位。 +- 技能文档可以引用软链接入口；更新上游内容必须通过 `tools/external/` 下的 submodule 指针完成。 +- 不在本目录直接修改 submodule 内容；如需改造，先 fork 上游并更新 submodule 来源。 + +## 依赖关系 + +- 上游来源：`tools/external/.tmux` 与 `tools/external/tmux`。 +- 下游使用：`SKILL.md` 和 `references/` 中的命令示例。 +- 验证入口：`skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict`。 diff --git a/skills/auto-tmux/README.md b/skills/auto-tmux/README.md new file mode 100644 index 0000000..fe1202f --- /dev/null +++ b/skills/auto-tmux/README.md @@ -0,0 +1,29 @@ +# auto-tmux + +`auto-tmux` 是 tmux 自动化操控技能，用于读取 pane 输出、发送按键、批量巡检、救援卡住的终端，以及组织多 AI 终端协作。 + +## 入口 + +- [SKILL.md](./SKILL.md) - 技能触发条件、命令片段、规则和质量门禁。 +- [references/](./references/) - tmux / oh-my-tmux 参考、示例和故障排查。 +- [assets/](./assets/) - 指向仓库外部 submodule 的只读软链接入口。 + +## 资产来源 + +| 入口 | 指向 | 用途 | +|:---|:---|:---| +| `assets/oh-my-tmux` | `tools/external/.tmux` | gpakosz/oh-my-tmux 配置参考 | +| `assets/tmux-src` | `tools/external/tmux` | tmux 上游源码参考 | + +## 快速验证 + +```bash +skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict +``` + +## 使用边界 + +- 发送按键前必须先 `capture-pane` 复核目标上下文。 +- 批量操作前必须先列出 session/window/pane 白名单。 +- 不在未知 pane 中发送破坏性命令。 +- 不在本目录复制或修改上游 tmux / oh-my-tmux 源码。 diff --git a/skills/auto-tmux/SKILL.md b/skills/auto-tmux/SKILL.md new file mode 100644 index 0000000..f1d909b --- /dev/null +++ b/skills/auto-tmux/SKILL.md @@ -0,0 +1,176 @@ +--- +name: auto-tmux +description: "tmux 自动化操控：读取/广播/救援 session|window|pane，基于 oh-my-tmux 配置安全地让 AI 自控/互控终端。触发：需要 capture-pane/send-keys、批量巡检、蜂群 AI 协作、卡死救援或快速查看快捷键。" +--- + +# auto-tmux Skill + +让 AI 像熟练运维一样操作 tmux：读取终端输出、发送按键、批量巡检、协作/救援其他终端，默认兼容 `tools/external/.tmux`（gpakosz/oh-my-tmux），并在本技能内通过 `assets/oh-my-tmux` 与 `assets/tmux-src` 暴露上游 submodule。 + +## When to Use This Skill + +触发条件（满足其一即可）： +- 需要远程读取/复制某个 tmux pane 的最新输出（日志、提示、错误）。 +- 需要向指定 pane 发送按键/命令（确认 `y`、`Enter`、`Ctrl+C`、广播同一窗口）。 +- 需要批量巡检/接管多 AI 终端（蜂群协作、自动救援卡死任务）。 +- 需要快速回忆 oh-my-tmux 快捷键、前缀或同步面板操作。 +- 需要在当前仓库复用 `tools/external/.tmux` 配置并避免修改主配置。 +- 需要从技能目录内快速查看 oh-my-tmux 配置或 tmux 上游源码入口。 + +## Not For / Boundaries + +- 不用于执行非 tmux 环境（目标不存在时先创建 session/window/pane）。 +- 不直接编辑 `~/.tmux.conf` / `.tmux.conf`（遵循 oh-my-tmux：修改请放到 `.tmux.conf.local`）。 +- 不盲发破坏性按键：`kill-server`、`rm -rf` 等必须先 capture-pane 确认目标上下文。 +- 如果 tmux 版本 < 2.6，需先升级再使用本技能的命令组合。 + +## Quick Reference + +### 常用模式（≤20 条，直接复制即用） + +**查看快捷键帮助**（oh-my-tmux 双前缀：主 `C-a`，备用 `C-b`，前缀后按 `?`） +```text +[按] ? +``` + +**枚举拓扑（session/window/pane）** +```bash +tmux list-sessions +tmux list-windows -a -F '#S:#I:#W#F' +tmux list-panes -a -F '#S:#I.#P #{pane_current_command} #{pane_title}' +``` + +**读取指定 pane 最近 120 行** +```bash +tmux capture-pane -t :. -p -S -120 +``` + +**向指定 pane 发送确认键** +```bash +tmux send-keys -t :. "y" Enter +``` + +**安全中断挂住任务** +```bash +tmux send-keys -t :. C-c +``` + +**开启/关闭窗口内广播（同步全部 pane）** +```bash +tmux set-window-option synchronize-panes on +tmux set-window-option synchronize-panes off +``` + +**一次扫描全部窗口并截取最近输出（蜂群巡检骨架）** +```bash +for w in $(tmux list-windows -a -F '#S:#I'); do + tmux capture-pane -t "$w" -p -S -80 | sed "s/^/[$w] /"; +done +``` + +**远程救援：发现等待输入即发送 y** +```bash +target="0:3.0" # 示例 +tmux capture-pane -t "$target" -p -S -50 | grep -qi "(y/n)" && \ + tmux send-keys -t "$target" "y" Enter +``` + +**新建 AI 蜂群工作台（1 指挥 + 3 工人）** +```bash +tmux new-session -d -s ai-hub -n commander 'bash' +tmux new-window -t ai-hub -n worker1 'kiro-cli chat' +tmux new-window -t ai-hub -n worker2 'kiro-cli chat' +tmux new-window -t ai-hub -n worker3 'kiro-cli chat' +tmux attach -t ai-hub +``` + +**启用 oh-my-tmux 配置（仓库内版本）** +```bash +repo_root="$(git rev-parse --show-toplevel)" +ln -sfn "$repo_root/skills/auto-tmux/assets/oh-my-tmux/.tmux.conf" ~/.tmux.conf +cp -n "$repo_root/skills/auto-tmux/assets/oh-my-tmux/.tmux.conf.local" ~/.tmux.conf.local +``` + +**记录 pane 输出到文件** +```bash +tmux pipe-pane -t :. -o 'cat >> /tmp/tmux---.log' +``` + +## Rules & Constraints + +- MUST：在发送按键前用 `capture-pane` 复核目标上下文；按键操作必须带 `:.` 绝对定位。 +- MUST：遵循 oh-my-tmux 约定，不修改主配置文件；自定义写入 `~/.tmux.conf.local`。 +- MUST：批量操作前先 `list-windows`/`list-panes` 建立白名单，避免误控用户窗口。 +- SHOULD：救援/确认前先 grep 关键词（如 `(y/n)`、`password`），只对匹配目标发送。 +- SHOULD：发送完整命令行时避免先发 `Escape`；先 `C-c` 中断、`C-u` 清行，再用 `send-keys -l` 逐字发送完整命令。 +- SHOULD：pane 处在 Codex UI 时，先发送 `/exit` 回到 shell 再执行命令。 +- SHOULD：长任务开启 `pipe-pane` 记录审计；广播完成后立即 `synchronize-panes off`。 +- NEVER：在未知 pane 发送破坏性命令；NEVER 在 root 会话不经确认发送 `Ctrl+C`/`Ctrl+D`。 + +## Examples + +### Example 1：自动给卡住的安装脚本回车确认 +- 输入：安装脚本停在 `Proceed? (y/n)`，位置在 `0:3.0`。 +- 步骤： + 1) `tmux capture-pane -t 0:3.0 -p -S -50 | grep -qi "(y/n)"` 确认等待输入。 + 2) `tmux send-keys -t 0:3.0 "y" Enter` 发送确认。 +- 验收：脚本继续运行，无额外多余输入。 + +### Example 2：蜂群巡检 + 自动救援 +- 输入：4 个 AI 终端分布在 session `ai-hub` 的多个窗口。 +- 步骤： + 1) 运行 Quick Reference 巡检循环收集最近 80 行并观察状态。 + 2) 对匹配 `"(y/n)"` 的 pane 触发「远程救援」片段自动发 `y`。 + 3) 对输出包含 `Traceback` 或 `ERROR` 的 pane，先 `capture-pane` 记录再人工介入。 +- 验收：等待确认的终端恢复，未误伤正常任务；巡检日志保存在本地。 + +### Example 3：快速搭建 oh-my-tmux AI 工作台 +- 输入：需要 1 个指挥 + 3 个 worker，并使用仓库内 oh-my-tmux 配置。 +- 步骤： + 1) 运行「启用 oh-my-tmux 配置」片段完成软链和本地副本（若已存在跳过）。 + 2) 运行「新建 AI 蜂群工作台」片段创建 session 并 attach。 + 3) 在 commander pane 使用「枚举拓扑」确认 worker 窗口存在。 +- 验收：前缀键为 `C-a`，状态栏正常；4 个窗口可互相捕获/发送按键。 + +## FAQ + +- Q: 为什么按 `C-b` 无反应？ + - A: oh-my-tmux 默认主前缀是 `C-a`，`C-b` 仅作备用；确保无其他程序占用 `C-a`。 +- Q: 如何只广播当前窗口而不影响其他窗口？ + - A: 只对当前窗口执行 `set-window-option synchronize-panes on`，使用完立即关闭。 +- Q: 远程发送命令前如何确认当前工作目录？ + - A: `tmux display-message -pt '#{pane_current_path}'`，必要时先 `send-keys 'cd /path' Enter`。 + +## Troubleshooting + +- `no such session/window/pane` → 检查目标名称，先 `list-sessions`/`list-windows` 校验再重试。 +- 前缀键冲突 → 查看 `~/.tmux.conf.local` 是否改写前缀；可在其中设置 `set -g prefix C-b #!important`。 +- 状态栏样式错乱/重复 → 按 README 建议用 `tmux -f /dev/null -L test` 排查；多半是终端宽字符/字体导致。 +- 发送命令没效果 → 目标 pane 可能在 copy-mode；优先用 `tmux display-message -pt '#{pane_in_mode}'` 判断，再用 `tmux send-keys -t -X cancel` 退出；避免用 `Escape`（会触发 Meta 前缀，可能吞掉首字符）。 + +## References + +- `references/index.md`: 导航与文件速览 +- `references/getting_started.md`: 术语、oh-my-tmux 最小接入步骤 +- `references/api.md`: tmux/oh-my-tmux 常用命令、选项与 gpakosz 特色键位 +- `references/examples.md`: 蜂群协议脚本与长示例 +- `references/troubleshooting.md`: 典型故障到修复路径 +- `assets/oh-my-tmux`: gpakosz/oh-my-tmux submodule 的相对软链接入口 +- `assets/tmux-src`: tmux/tmux submodule 的相对软链接入口 + +## Maintenance + +- Sources: `skills/auto-tmux/assets/oh-my-tmux`、`skills/auto-tmux/assets/tmux-src`、蜂群实战提示词、Skill Seeker 生成的抓取材料（如需扩展自动化）。 +- Last updated: 2026-04-28 +- Known limits: 未涵盖 tmux 插件管理（tpm）及多用户共享权限配置；需时再补充。 + +## Quality Gate + +发布前自检（配合 `auto-skill` 校验脚本）： +1. `description` 已含“capture-pane/send-keys/蜂群”等触发关键词。 +2. 「When to Use」「Not For」已覆盖边界；前缀/版本要求清晰。 +3. Quick Reference ≤ 20 条且均可直接执行；无长篇解释。 +4. ≥3 个端到端示例，含输入/步骤/验收。 +5. 长文档放在 `references/` 并可导航；无文档堆砌。 +6. 不确定项给出验证路径；禁止虚构 tmux 行为。 +7. 运行 `skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux` 通过。 diff --git a/skills/auto-tmux/assets/AGENTS.md b/skills/auto-tmux/assets/AGENTS.md new file mode 100644 index 0000000..a100b14 --- /dev/null +++ b/skills/auto-tmux/assets/AGENTS.md @@ -0,0 +1,10 @@ +# skills/auto-tmux/assets Agent 指南 + +本目录只承载 auto-tmux 的外部资源入口。 + +## 规则 + +- 只允许保存指向仓库内 `tools/external/` 的相对软链接。 +- 不要复制 `tmux` 或 `oh-my-tmux` 源码到本目录。 +- 上游内容更新必须通过 `tools/external/` 下的 Git submodule 指针完成。 +- 修改软链接后，运行 `find skills/auto-tmux/assets -maxdepth 1 -type l -printf '%p -> %l\n'` 核对目标。 diff --git a/skills/auto-tmux/assets/README.md b/skills/auto-tmux/assets/README.md new file mode 100644 index 0000000..b79672f --- /dev/null +++ b/skills/auto-tmux/assets/README.md @@ -0,0 +1,14 @@ +# auto-tmux assets + +本目录只保存指向仓库内外部 submodule 的软链接入口，不保存上游源码副本。 + +| 入口 | 指向 | 用途 | +|:---|:---|:---| +| `oh-my-tmux` | `../../../tools/external/.tmux` | gpakosz/oh-my-tmux 配置参考 | +| `tmux-src` | `../../../tools/external/tmux` | tmux 上游源码参考 | + +初始化或更新 submodule： + +```bash +git submodule update --init --recursive +``` diff --git a/skills/auto-tmux/assets/oh-my-tmux b/skills/auto-tmux/assets/oh-my-tmux new file mode 120000 index 0000000..0052859 --- /dev/null +++ b/skills/auto-tmux/assets/oh-my-tmux @@ -0,0 +1 @@ +../../../tools/external/.tmux \ No newline at end of file diff --git a/skills/auto-tmux/assets/tmux-src b/skills/auto-tmux/assets/tmux-src new file mode 120000 index 0000000..b2c1bfe --- /dev/null +++ b/skills/auto-tmux/assets/tmux-src @@ -0,0 +1 @@ +../../../tools/external/tmux \ No newline at end of file diff --git a/skills/auto-tmux/references/AGENTS.md b/skills/auto-tmux/references/AGENTS.md new file mode 100644 index 0000000..96c9741 --- /dev/null +++ b/skills/auto-tmux/references/AGENTS.md @@ -0,0 +1,10 @@ +# skills/auto-tmux/references Agent 指南 + +本目录保存 auto-tmux 的参考资料、示例和排障说明。 + +## 规则 + +- 参考资料只能引用仓库相对路径，不写个人机器绝对路径。 +- 上游来源统一写为 `tools/external/.tmux`、`tools/external/tmux` 或 `tools/external/Skill_Seekers-development`。 +- 示例命令必须优先使用可复制的占位符或 `git rev-parse --show-toplevel` 动态定位仓库根目录。 +- 不确定的 tmux 行为必须给出验证命令，不编造。 diff --git a/skills/auto-tmux/references/README.md b/skills/auto-tmux/references/README.md new file mode 100644 index 0000000..deab942 --- /dev/null +++ b/skills/auto-tmux/references/README.md @@ -0,0 +1,11 @@ +# auto-tmux references + +本目录保存 auto-tmux 的长参考资料。 + +| 文件 | 用途 | +|:---|:---| +| [index.md](./index.md) | 参考资料索引 | +| [getting_started.md](./getting_started.md) | 术语、最短路径和工作姿势 | +| [api.md](./api.md) | tmux / oh-my-tmux 常用命令与配置速查 | +| [examples.md](./examples.md) | 巡检、救援、审计和多 AI 工作台示例 | +| [troubleshooting.md](./troubleshooting.md) | 常见故障与修复路径 | diff --git a/skills/auto-tmux/references/api.md b/skills/auto-tmux/references/api.md new file mode 100644 index 0000000..c05df52 --- /dev/null +++ b/skills/auto-tmux/references/api.md @@ -0,0 +1,41 @@ +# API / CLI / Config Reference + +## 结构化速查（按场景） + +### 拓扑与定位 +- 列 session：`tmux list-sessions` +- 列窗口（含 flag）：`tmux list-windows -a -F '#S:#I:#W#F'` +- 列 pane：`tmux list-panes -a -F '#S:#I.#P #{pane_current_command} #{pane_title}'` + +### 读取输出 +- 抓取最近 N 行：`tmux capture-pane -t -p -S -120` +- 全量抓取到文件：`tmux capture-pane -t -p -S -100000 > pane.log` +- 实时镜像：`tmux pipe-pane -t -o 'cat >> /tmp/pane.log'` + +### 发送按键/命令 +- 发送字符串+回车：`tmux send-keys -t "command here" Enter` +- 发送单键：`tmux send-keys -t C-c`、`Escape`、`Space` +- 发送确认：`tmux send-keys -t "y" Enter` +- 退出 copy-mode 后再发：`tmux send-keys -t Escape` + +### 广播 / 同步 +- 开启窗口广播：`tmux set-window-option synchronize-panes on` +- 关闭广播：`tmux set-window-option synchronize-panes off` +- 广播一次性命令（推荐先列出名单）：配合上面 `list-panes` 逐一 send-keys + +### session/window 管理 +- 新建：`tmux new-session -d -s -n 'cmd'` +- 新窗口：`tmux new-window -t -n 'cmd'` +- 重命名：`tmux rename-window -t ` +- 分屏：`tmux split-window -t -h|-v 'cmd'` + +### oh-my-tmux 关键配置 +- 前缀：默认 `set -g prefix C-a`；若想回到 `C-b` 在 `~/.tmux.conf.local` 中加 `#!important`。 +- 主题/状态栏调整：在 `~/.tmux.conf.local` 修改对应变量（按 README 指引）。 +- 升级/重载：`tmux source-file ~/.tmux.conf.local` + +## 常见误用与修复 + +- 错 pane：始终用 ``，避免仅用 `-t 0`（易撞到当前 pane）。 +- 广播遗留未关：操作完立即 `synchronize-panes off`，避免误输入。 +- Unicode 宽度导致状态栏错位：优先使用仓库内 `.tmux.conf.local` 默认设置；若仍异常用 `tmux -f /dev/null -L test` 排查终端字体。 diff --git a/skills/auto-tmux/references/examples.md b/skills/auto-tmux/references/examples.md new file mode 100644 index 0000000..761572b --- /dev/null +++ b/skills/auto-tmux/references/examples.md @@ -0,0 +1,70 @@ +# Long Examples + +## 用例 1：巡检 + 自动救援脚本（bash） + +```bash +#!/usr/bin/env bash +# 巡检所有窗口，标注输出并对 (y/n) 提示自动回车 +set -euo pipefail + +for w in $(tmux list-windows -a -F '#S:#I'); do + panes=$(tmux list-panes -t "$w" -F '#S:#I.#P') + for p in $panes; do + log=$(tmux capture-pane -t "$p" -p -S -80) + printf '--- [%s] ---\n%s\n' "$p" "$log" + if echo "$log" | grep -qi "(y/n)"; then + tmux send-keys -t "$p" "y" Enter + echo "[action] sent y to $p" + fi + done +done +``` +- 运行：保存为 `scan_and_rescue.sh`，`chmod +x` 后执行；建议放在 commander 窗口运行。 +- 验收：匹配的 pane 自动继续，其他 pane 不受影响。 + +## 用例 2：批量录制 + 审计 + +```bash +#!/usr/bin/env bash +# 对 ai-hub 会话所有 pane 开启 pipe-pane 记录 +set -euo pipefail + +for p in $(tmux list-panes -a -F '#S:#I.#P #{session_name}' | awk '$2=="ai-hub"{print $1}'); do + tmux pipe-pane -t "$p" -o "cat >> /tmp/${p//[:.]/-}.log" +done +echo "audit pipes enabled under /tmp/*-ai-hub-*.log" +``` +- 用于长跑任务或多 AI 协作时保留证据；任务结束后记得 `tmux pipe-pane -t

-o cat` 关闭。 + +## 用例 3：Skill Seeker 抓取 oh-my-tmux 文档并生成补充参考 + +> 目的：在需要更全面文档时，用仓库自带的 `Skill_Seekers-development` 自动抓取 gpakosz/.tmux 与 README，生成扩展参考文件，再手动筛选进 `references/`。 + +```bash +repo_root="$(git rev-parse --show-toplevel)" +cd "$repo_root/tools/external/Skill_Seekers-development" +# 准备 Python 环境（如未安装） +uv tool install skill-seekers # 或 pip install skill-seekers + +# 直接抓取 GitHub 仓库并生成 skill 雏形 +skill-seekers github --repo gpakosz/.tmux --name tmux-oh-my --output /tmp/skill-out + +# 可选：抓取 README 站点或 PDF +# skill-seekers scrape --url https://github.com/gpakosz/.tmux --name tmux-oh-my-web --async + +# 产物：/tmp/skill-out/tmux-oh-my.zip +# 解压后挑选与 auto-tmux 相关的 API/快捷键，整理到 references/api.md 或 examples.md +``` +- 这样满足“严选来源 + 自动化抓取”要求，后续人工抽取精华补入本技能。 + +## 用例 4：多 AI 工作台一键启动（命令行版） + +```bash +tmux new-session -d -s ai-hub -n commander 'bash' +for w in worker1 worker2 worker3; do + tmux new-window -t ai-hub -n "$w" 'kiro-cli chat' +done +tmux select-window -t ai-hub:commander +tmux attach -t ai-hub +``` +- 进入后执行用例 1 的巡检脚本即可形成「指挥+工人」模式。 diff --git a/skills/auto-tmux/references/getting_started.md b/skills/auto-tmux/references/getting_started.md new file mode 100644 index 0000000..7aa0dab --- /dev/null +++ b/skills/auto-tmux/references/getting_started.md @@ -0,0 +1,42 @@ +# Getting Started & Vocabulary + +## 核心术语（10 个） + +1. session：tmux 的最外层会话。 +2. window：session 下的窗口，编号 `:`。 +3. pane：窗口内分屏，编号 `:.`。 +4. prefix：组合键前缀，oh-my-tmux 主前缀为 `Ctrl+a`，备用 `Ctrl+b`。 +5. capture-pane：抓取 pane 输出到 stdout。 +6. send-keys：向 pane 注入按键/命令。 +7. synchronize-panes：窗口级广播开关。 +8. pipe-pane：将 pane 输出流向命令/文件。 +9. copy-mode：tmux 内置滚动/复制模式，需先退出再发按键。 +10. .tmux.conf.local：oh-my-tmux 推荐的用户自定义文件。 + +## 最短路径：接管本仓库内 oh-my-tmux 并跑通命令 + +```bash +# 1) 确认 tmux 版本 >= 2.6 +tmux -V + +# 2) 软链配置（不会覆盖已有 .tmux.conf.local，如需自定义请编辑该文件） +repo_root="$(git rev-parse --show-toplevel)" +ln -sfn "$repo_root/tools/external/.tmux/.tmux.conf" ~/.tmux.conf +cp -n "$repo_root/tools/external/.tmux/.tmux.conf.local" ~/.tmux.conf.local + +# 3) 启动会话并验证前缀 +tmux new -s demo -n shell +# 在 tmux 内按 ? 打开快捷键帮助，确认状态栏与主题正常 + +# 4) 基础自检：列窗、抓取、发送 +tmux list-windows +tmux capture-pane -t demo:0.0 -p -S -10 +tmux send-keys -t demo:0.0 "echo ok" Enter +``` + +## 工作姿势 + +- 始终用绝对定位 `:.`；跨 session 操作更安全。 +- 批量广播前先名单化：`tmux list-panes -a -F '#S:#I.#P #{pane_current_command}'`。 +- 高风险按键（`Ctrl+C`、确认 `y`）先 `capture-pane` 再发送。 +- 长任务用 `pipe-pane` 记录；救援/打断后再关。 diff --git a/skills/auto-tmux/references/index.md b/skills/auto-tmux/references/index.md new file mode 100644 index 0000000..19fc4ce --- /dev/null +++ b/skills/auto-tmux/references/index.md @@ -0,0 +1,14 @@ +# auto-tmux Reference Index + +## Quick Links + +- `getting_started.md`：术语、最小安装、前缀说明 +- `api.md`：tmux/oh-my-tmux 常用命令、同步广播、安全写法 +- `examples.md`：蜂群巡检脚本、自动救援脚本、Skill Seeker 抓取示例 +- `troubleshooting.md`：常见报错与修复路径 + +## Notes + +- 长文档、脚本细节放这里，`SKILL.md` 只保留可立即执行的片段。 +- 配置来源：仓库内 `tools/external/.tmux`（gpakosz/oh-my-tmux）。 +- 大规模文档抓取/刷新可用 `tools/external/Skill_Seekers-development`，示例见 `examples.md`。 diff --git a/skills/auto-tmux/references/troubleshooting.md b/skills/auto-tmux/references/troubleshooting.md new file mode 100644 index 0000000..61a41b4 --- /dev/null +++ b/skills/auto-tmux/references/troubleshooting.md @@ -0,0 +1,35 @@ +# Troubleshooting & Edge Cases + +格式：症状 → 可能原因 → 诊断 → 修复 + +- `no such session` / `no current client` + → 会话名写错或未 attach + → `tmux list-sessions` 校验；需要时 `tmux new -s ` + → 重试带绝对目标：`-t ` + +- 发送无效、卡在 copy-mode + → pane 处于 copy-mode + → `tmux display-message -pt '#{pane_in_mode}'` + → 先 `tmux send-keys -t Escape` 再发命令 + +- 状态栏符号混乱、重复一行 + → 终端宽字符/字体问题或重复加载配置 + → `tmux -f /dev/null -L test` 检查；确认 `LC_CTYPE` 使用 UTF-8；清理多重 source + → 使用仓库版 `.tmux.conf.local` 默认字体设置 + +- 广播误伤其他 pane + → `synchronize-panes` 未关闭 + → `tmux show-window-options | grep synchronize` + → `tmux set-window-option synchronize-panes off` + +- Powerline 符号缺失 + → 字体未带 Powerline codepoints + → 切换到带符号字体或安装 `PowerlineSymbols.otf`，再重载 `tmux source-file ~/.tmux.conf.local` + +- `prefix` 无反应 + → 其他程序占用或配置被覆盖 + → `grep prefix ~/.tmux.conf.local` 确认；可改为 `C-b` 并加 `#!important` + +- 长任务输出缺失 + → 未开启 pipe-pane / buffer 溢出 + → 提前 `pipe-pane` 到文件；或 `capture-pane -S -100000` 抓历史