chore: migrate repository to standard knowledge base layout

2026-08-21 06:48:04 +00:00 · 2026-05-02 03:29:06 +08:00
parent 40a721c24d
commit 628a3bc832
565 changed files with 687 additions and 711 deletions
@@ -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 <s:w.p> -p -S -120`
+- 全量抓取到文件：`tmux capture-pane -t <s:w.p> -p -S -100000 > pane.log`
+- 实时镜像：`tmux pipe-pane -t <s:w.p> -o 'cat >> /tmp/pane.log'`
+
+### 发送按键/命令
+- 发送字符串+回车：`tmux send-keys -t <s:w.p> "command here" Enter`
+- 发送单键：`tmux send-keys -t <s:w.p> C-c`、`Escape`、`Space`
+- 发送确认：`tmux send-keys -t <s:w.p> "y" Enter`
+- 退出 copy-mode 后再发：`tmux send-keys -t <s:w.p> 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 <name> -n <win> 'cmd'`
+- 新窗口：`tmux new-window -t <s> -n <name> 'cmd'`
+- 重命名：`tmux rename-window -t <s:w> <new>`
+- 分屏：`tmux split-window -t <s:w> -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：始终用 `<s:w.p>`，避免仅用 `-t 0`（易撞到当前 pane）。
+- 广播遗留未关：操作完立即 `synchronize-panes off`，避免误输入。
+- Unicode 宽度导致状态栏错位：优先使用仓库内 `.tmux.conf.local` 默认设置；若仍异常用 `tmux -f /dev/null -L test` 排查终端字体。
@@ -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 <p> -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
+# 解压后挑选与 tmux-autopilot 相关的 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 的巡检脚本即可形成「指挥+工人」模式。
@@ -0,0 +1,42 @@
+# Getting Started & Vocabulary
+
+## 核心术语（10 个）
+
+1. session：tmux 的最外层会话。
+2. window：session 下的窗口，编号 `<session>:<window>`。
+3. pane：窗口内分屏，编号 `<session>:<window>.<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/skills/tmux-autopilot/assets/oh-my-tmux/.tmux.conf" ~/.tmux.conf
+cp -n "$repo_root/skills/tmux-autopilot/assets/oh-my-tmux/.tmux.conf.local" ~/.tmux.conf.local
+
+# 3) 启动会话并验证前缀
+tmux new -s demo -n shell
+# 在 tmux 内按 <Ctrl+a> ? 打开快捷键帮助，确认状态栏与主题正常
+
+# 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>:<window>.<pane>`；跨 session 操作更安全。
+- 批量广播前先名单化：`tmux list-panes -a -F '#S:#I.#P #{pane_current_command}'`。
+- 高风险按键（`Ctrl+C`、确认 `y`）先 `capture-pane` 再发送。
+- 长任务用 `pipe-pane` 记录；救援/打断后再关。
@@ -0,0 +1,15 @@
+# tmux-autopilot Reference Index
+
+## Quick Links
+
+- `getting_started.md`：术语、最小安装、前缀说明
+- `api.md`：tmux/oh-my-tmux 常用命令、同步广播、安全写法
+- `examples.md`：蜂群巡检脚本、自动救援脚本、Skill Seeker 抓取示例
+- `troubleshooting.md`：常见报错与修复路径
+
+## Notes
+
+- 长文档、脚本细节放这里，`SKILL.md` 只保留可立即执行的片段。
+- 配置来源：技能内 `../assets/oh-my-tmux`，实际指向仓库 submodule `tools/external/.tmux`（gpakosz/oh-my-tmux）。
+- 源码来源：技能内 `../assets/tmux-src`，实际指向仓库 submodule `tools/external/tmux`。
+- 大规模文档抓取/刷新可用 `tools/external/Skill_Seekers-development`，示例见 `examples.md`。
@@ -0,0 +1,35 @@
+# Troubleshooting & Edge Cases
+
+格式：症状 → 可能原因 → 诊断 → 修复
+
+- `no such session` / `no current client`  
+  → 会话名写错或未 attach  
+  → `tmux list-sessions` 校验；需要时 `tmux new -s <name>`  
+  → 重试带绝对目标：`-t <s:w.p>`
+
+- 发送无效、卡在 copy-mode  
+  → pane 处于 copy-mode  
+  → `tmux display-message -pt <t> '#{pane_in_mode}'`  
+  → 先 `tmux send-keys -t <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` 抓历史