swain-stage

Stage

面向 swain 的 tmux 工作区管理器。创建窗格布局、管理动态 MOTD 状态面板，并让 Agent 直接控制可视化工作区。

前提条件： 必须在 tmux 会话中运行（必须设置 $TMUX）。运行任何子命令前，脚本都会检查 tmux——详见下文的错误处理。

脚本位置

Swain 项目的技能位于项目根目录下的 skills/ 中。对于此技能，请使用：

• skills/swain-stage/scripts/swain-stage.sh — 主要的 tmux 布局和窗格管理器
• skills/swain-stage/scripts/swain-motd.py — MOTD 状态面板（Textual TUI，通过 uv run 运行）
• skills/swain-stage/scripts/swain-motd.sh — 旧版 bash MOTD（作为 uv/Textual 不可用时的备用方案保留）
• skills/swain-stage/references/layouts/ — 布局预设
• skills/swain-stage/references/yazi/ — 内置的 Yazi 配置，在 fileBrowser 解析为 yazi 时使用

命令

布局预设

应用指定的布局。可用预设位于 skills/swain-stage/references/layouts/ 中：

布局	描述
focus	Agent 窗格 + 右上角 MOTD + 右下角文件浏览器
review	Agent + 编辑器（已更改的文件）+ MOTD
browse	Agent + 文件浏览器 + MOTD

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" layout review
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" layout browse
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" layout focus

默认布局在 swain.settings.json 的 stage.defaultLayout 中配置（默认值：focus）。

用户可以在 swain.settings.json 的 stage.layouts.<name> 中覆盖布局定义。

打开单个窗格

打开指定类型的窗格，而不应用完整布局：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane editor file1.py file2.py   # editor with specific files
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane browser                      # file browser at repo root
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane browser /some/path           # file browser at specific path
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane motd                         # MOTD status panel
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane shell                        # plain shell

MOTD 管理

MOTD 窗格显示动态状态面板，其中包含：

• 项目名称、分支和脏状态
• Agent 工作时显示动态旋转指示器（点字、点或条形样式）
• 当前 Agent 上下文（正在执行的任务）
• 活跃史诗及其进度比例（来自 swain-status 缓存）
• 活跃的 tk 任务
• 就绪（可操作）工件数量
• 最近提交信息
• 已分配的 GitHub issue 数量
• 已触及文件的数量

MOTD 是一个 Textual TUI 应用（swain-motd.py），通过 uv run 启动。如果 .agents/status-cache.json（由 swain-status 写入）可用，它会从中读取项目数据；如果缓存不存在或已过期（>5 min），则回退到直接查询 git/tk。Agent 状态（旋转指示器、上下文）始终从 .agents/stage-status.json 读取，以实现实时响应。Textual 能正确处理 Unicode 宽度，提供带圆角的规范边框绘制，并支持颜色主题。

状态文件位置：

• .agents/status-cache.json — swain-status 缓存（史诗进度、就绪项、任务数据）；由 swain-status.sh 写入
• .agents/stage-status.json — 实时 Agent 状态（旋转指示器活动、当前上下文）；由 stage-status-hook.sh 写入

通过钩子实现响应式状态： .claude/settings.json 中将 stage-status-hook.sh 配置为 Claude Code 钩子（PostToolUse、Stop、SubagentStart、SubagentStop）。它会自动写入 .agents/stage-status.json，让 MOTD 旋转指示器实时反映 Agent 活动，无需手动调用 motd update。

控制 MOTD：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd start                        # start MOTD in a new pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd stop                         # kill the MOTD pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "reviewing auth module"  # update context
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "idle"                # mark as idle
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "done"                # mark as done/idle

关闭窗格

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close right     # close the right pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close bottom    # close the bottom pane
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close all       # reset to single pane

状态

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" status          # show current layout info

重置

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" reset           # kill all panes except current

Agent 触发的窗格操作

Agent 应在工作期间直接使用 swain-stage。建议的模式：

完成修改后 — 打开审查视图

修改完文件后，打开这些文件供用户审查：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "changes ready for review"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane editor file1.py file2.py

研究期间 — 打开文件浏览器

探索代码库时：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" pane browser src/components/

工作时更新上下文

及时更新 MOTD，让其了解你正在做什么：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "analyzing test failures"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "writing migration script"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "done"

完成后清理

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" close right
bash "$(find "$REPO_ROOT" -path '*/swain-stage/scripts/swain-stage.sh' -print -quit 2>/dev/null)" motd update "idle"

设置

从 swain.settings.json（项目）和 ~/.config/swain/settings.json（用户覆盖设置）读取。用户设置优先。

键	类型	默认值	描述
editor	string	auto	编辑器命令。auto 会按以下顺序检测：micro > helix > nano > vim
fileBrowser	string	auto	文件浏览器命令。auto 会按以下顺序检测：yazi > nnn > ranger > mc
stage.defaultLayout	string	focus	默认应用的布局
stage.motd.refreshInterval	number	5	MOTD 刷新间隔（秒，空闲时）
stage.motd.spinnerStyle	string	braille	加载动画：braille、dots 或 bar
stage.layouts	object	{}	用户定义的布局覆盖设置（与预设文件使用相同的架构）

错误处理

• 如果未安装 tmux 二进制文件：脚本会以 "tmux not found" 退出。请主动提出安装："tmux is not installed. Install it now? I can run `brew install tmux` for you." 如果用户接受，运行 brew install tmux，然后重新运行原始子命令。
• 如果已安装 tmux，但当前不在 tmux 会话中（$TMUX 未设置）：脚本会以 "tmux not active — swain-stage requires a tmux session. Start tmux first." 退出。告知用户即可，不要提出安装（tmux 已存在）。
• 如果未安装编辑器或文件浏览器：向用户发出警告，并建议替代工具或通过 swain.settings.json 覆盖设置。
• 如果文件浏览器解析为 yazi，swain-stage 会注入 skills/swain-stage/references/yazi/ 中捆绑的配置，使文本文件通过系统默认应用打开，并确保目录颜色在深色终端中仍清晰可读。
• 如果无法使用 jq：警告用户设置无法读取，并使用硬编码的默认值。
• 窗格操作会尽力执行——如果无法创建或找到窗格，发出警告，但不要导致会话失败。