tuistory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tuistory Driver

The orchestrator routed you here. Use these mechanics to execute your plan.

Launch a target command in a virtual PTY with Playwright-style CLI for typing, pressing keys, waiting, snapshotting, and recording.

编排器将你引导到这里。使用这些机制来执行你的计划。

在虚拟PTY中启动目标命令，采用Playwright风格的CLI来实现输入文本、按键、等待、快照和录制功能。

When to use

适用场景

Routine TUI automation and regression checks
Deterministic
```
wait
```
/
```
wait-idle
```
against the virtual screen buffer
Text snapshots of exactly what the user would see
Any scenario where you do not need to prove real terminal keyboard encoding

If you need to prove what Ghostty or Kitty actually emits for a given keystroke, use true-input instead.

常规TUI自动化与回归检查
针对虚拟屏幕缓冲区的确定性
```
wait
```
/
```
wait-idle
```
操作
精确捕获用户所见内容的文本快照
任何无需验证真实终端键盘编码的场景

如果你需要验证Ghostty或Kitty针对特定按键实际输出的内容，请改用true-input。

Prerequisites

前置条件

bash

npm install -g tuistory    # or: bun add -g tuistory

Optional:

tmux

(scrollback flows),

asciinema

(recordings),

agg

(

.cast

.gif

bash

npm install -g tuistory    # or: bun add -g tuistory

可选依赖：

tmux

（滚动回溯流）、

asciinema

（录制）、

agg

（将

.cast

转换为

.gif

）。

Core pattern

核心模式

bash

TCTL=${DROID_PLUGIN_ROOT}/bin/tctl

$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor
$TCTL -s demo wait ">" --timeout 15000
$TCTL -s demo type "hello"
$TCTL -s demo press enter
$TCTL -s demo snapshot --trim
$TCTL -s demo close

Note:

--repo-root

is mandatory for

droid-dev

launches —

tctl

enforces it.

Always pass
--env FORCE_COLOR=3 --env COLORTERM=truecolor
when launching. The virtual PTY doesn't advertise color support, so Node.js apps (Ink/chalk) suppress all color escape codes without these.

bash

TCTL=${DROID_PLUGIN_ROOT}/bin/tctl

$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor
$TCTL -s demo wait ">" --timeout 15000
$TCTL -s demo type "hello"
$TCTL -s demo press enter
$TCTL -s demo snapshot --trim
$TCTL -s demo close

注意： 启动

droid-dev

时

--repo-root

是必填项——

tctl

会强制校验这一点。

启动时务必传入
--env FORCE_COLOR=3 --env COLORTERM=truecolor
。虚拟PTY不会主动声明颜色支持，因此如果没有这些环境变量，Node.js应用（如Ink/chalk）会抑制所有颜色转义码。

Command reference (via tctl)

命令参考（通过tctl）

Command	Purpose
`launch <cmd> -s <name> --backend tuistory`	Start a tuistory session
`type <text>`	Send literal text
`press <key> [keys...]`	Send key chord (e.g., `press shift enter` )
`wait <pattern>`	Block until text or `/regex/` appears
`wait-idle`	Block until output stabilizes
`snapshot [--trim]`	Print cleaned text ( `--trim` strips trailing blanks)
`close`	Tear down session

Launch options:

--cols <n>

--rows <n>

--cwd <path>

--env KEY=VALUE

--record <path>

命令	用途
`launch <cmd> -s <name> --backend tuistory`	启动一个tuistory会话
`type <text>`	发送文本内容
`press <key> [keys...]`	发送组合按键（例如： `press shift enter` ）
`wait <pattern>`	阻塞直到文本或 `/regex/` 正则表达式出现
`wait-idle`	阻塞直到输出稳定
`snapshot [--trim]`	输出清理后的文本（ `--trim` 会去除末尾空白）
`close`	销毁会话

启动选项：

--cols <n>

、

--rows <n>

、

--cwd <path>

、

--env KEY=VALUE

、

--record <path>

。

Recording

录制功能

Pass

--record

at launch.

tctl

wraps

asciinema rec

around the PTY, so recording must be set at launch time (raw

tuistory

cannot record):

bash

$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record /tmp/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

启动时传入

--record

参数。

tctl

会在PTY外层包裹

asciinema rec

，因此录制功能必须在启动时设置（原生

tuistory

无法实现录制）：

bash

$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record /tmp/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

... interact ...

... 执行交互操作 ...

$TCTL -s demo close # finalizes the .cast


Before/after comparison -- launch two sessions against different worktrees:

```bash
$TCTL launch "droid-dev" -s before --backend tuistory \
  --repo-root /path/to/baseline-worktree \
  --cols 120 --rows 36 --record /tmp/before.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

$TCTL launch "droid-dev" -s after --backend tuistory \
  --repo-root /path/to/candidate-worktree \
  --cols 120 --rows 36 --record /tmp/after.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

Playback:

asciinema play /tmp/demo.cast

$TCTL -s demo close # 完成.cast文件的生成


前后对比——针对不同工作目录启动两个会话：

```bash
$TCTL launch "droid-dev" -s before --backend tuistory \
  --repo-root /path/to/baseline-worktree \
  --cols 120 --rows 36 --record /tmp/before.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

$TCTL launch "droid-dev" -s after --backend tuistory \
  --repo-root /path/to/candidate-worktree \
  --cols 120 --rows 36 --record /tmp/after.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

回放：

asciinema play /tmp/demo.cast

tmux (scrollback flows only)

tmux（仅用于滚动回溯流）

Only needed when the demo requires terminal-emulator scrollback and the app uses the standard buffer (not alternate screen). True-input sessions rarely need tmux because the real terminal owns native scrollback.

Use

--tmux

at launch.

tctl

wraps the command in tmux, starts tmux with

TERM=xterm-256color

, and preconfigures

default-terminal=tmux-256color

terminal-features=...,xterm-256color:RGB

terminal-overrides=...,xterm-256color:Tc

(fallback for tmux < 3.2),

COLORTERM=truecolor

(via

set-environment

escape-time=50

, and

mode-keys=vi

Copy-mode:

ctrl-b [

to enter,

g g

top,

shift-g

bottom,

ctrl-u

ctrl-d

half-page,

search,

to exit (not

esc

Launch with tmux:

bash

$TCTL launch "droid-dev" -s demo --backend tuistory --tmux \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record /tmp/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

When recording includes tmux redraws, asciinema must wrap tmux, not the reverse.

仅当演示需要终端模拟器的滚动回溯功能，且应用使用标准缓冲区（而非交替屏幕）时才需要使用。True-input会话很少需要tmux，因为真实终端拥有原生滚动回溯功能。

启动时使用

--tmux

参数。

tctl

会在tmux中包裹命令，启动tmux时设置

TERM=xterm-256color

，并预先配置

default-terminal=tmux-256color

、

terminal-features=...,xterm-256color:RGB

、

terminal-overrides=...,xterm-256color:Tc

（针对tmux < 3.2的兼容方案）、

COLORTERM=truecolor

（通过

set-environment

设置）、

escape-time=50

和

mode-keys=vi

。

复制模式：按

ctrl-b [

进入，

g g

跳转到顶部，

shift-g

跳到底部，

ctrl-u

ctrl-d

翻半页，

搜索，

退出（不要用

esc

）。

使用tmux启动：

bash

$TCTL launch "droid-dev" -s demo --backend tuistory --tmux \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record /tmp/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

当录制包含tmux重绘内容时，必须由asciinema包裹tmux，而不是反过来。

Known dead ends

已知误区

Raw
asciinema rec
: Do not call
```
asciinema rec
```
directly.
```
tctl --record
```
wraps
```
asciinema rec
```
around the PTY so that tuistory-relay still owns the session and interactive TUIs (Ink/React) receive stdin correctly. Calling
```
asciinema rec
```
manually bypasses this wiring — stdin forwarding breaks, typed keys echo on the outer PTY instead of reaching the child, and tuistory commands (
```
wait
```
,
```
snapshot
```
,
```
close
```
) cannot find the session.
Raw
tuistory launch
with tctl flags:
```
tuistory
```
has no
```
--record
```
,
```
--backend
```
,
```
--repo-root
```
, or
```
--env
```
flags. Passing them crashes
```
tuistory-relay
```
. Use
```
tctl
```
for all launches.

直接使用
asciinema rec
：不要直接调用
```
asciinema rec
```
。
```
tctl --record
```
会在PTY外层包裹
```
asciinema rec
```
，这样tuistory-relay仍能控制会话，且交互式TUI（如Ink/React）能正确接收标准输入。手动调用
```
asciinema rec
```
会绕过该机制——标准输入转发失效，输入的按键会在外部PTY回显而非传递给子进程，且tuistory命令（
```
wait
```
、
```
snapshot
```
、
```
close
```
）无法找到会话。
在原生
tuistory launch
中使用tctl参数：
```
tuistory
```
没有
```
--record
```
、
```
--backend
```
、
```
--repo-root
```
或
```
--env
```
参数。传入这些参数会导致
```
tuistory-relay
```
崩溃。所有启动操作请使用
```
tctl
```
。

Recovery

恢复操作

bash

$TCTL -s demo press esc         # bail out of a stuck dialog
$TCTL -s demo snapshot --trim   # check visible state
$TCTL -s demo close             # hard reset

bash

$TCTL -s demo press esc         # 退出卡住的对话框
$TCTL -s demo snapshot --trim   # 检查当前可见状态
$TCTL -s demo close             # 强制重置会话

Escape hatch: raw tuistory (last resort)

应急方案：原生tuistory（最后手段）

tctl

itself is broken or unavailable, you can fall back to raw

tuistory

for non-recording sessions only. Raw

tuistory

accepts only

--cols

--rows

, and

-s

— no other flags. Do not pass

--record

--backend

--repo-root

--env

, or

--tmux

bash

tuistory launch "my-tui-app" -s demo --cols 120 --rows 36
tuistory -s demo wait ">" --timeout 15000
tuistory -s demo snapshot --trim
tuistory -s demo close

如果

tctl

本身损坏或不可用，你可以退回到原生

tuistory

，但仅适用于非录制会话。原生

tuistory

仅接受

--cols

、

--rows

和

-s

参数——不支持其他任何参数。请勿传入

--record

、

--backend

、

--repo-root

、

--env

或

--tmux

。

bash

tuistory launch "my-tui-app" -s demo --cols 120 --rows 36
tuistory -s demo wait ">" --timeout 15000
tuistory -s demo snapshot --trim
tuistory -s demo close