textual-ui-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Textual UI Developer

Textual UI 开发者

Use this skill to improve the MassGen Textual UI while minimizing flaky reproduction and API cost.

使用此技能优化MassGen Textual UI，同时减少不稳定复现问题和API成本。

Use This Skill When

适用场景

You need to debug timeline rendering or ordering issues.
You need to verify layout/styling changes in the real Textual shell.
You need to update or add TUI regression tests (snapshot/golden/transcript).
You need to reproduce UI behavior from
```
events.jsonl
```
deterministically.

你需要调试时间线渲染或排序问题。
你需要在真实的Textual shell中验证布局/样式变更。
你需要更新或添加TUI回归测试（快照/基准/脚本记录）。
你需要从
```
events.jsonl
```
中确定性地复现UI行为。

Default Strategy

默认策略

Prefer deterministic workflows before live model runs:

Reproduce from recorded/synthetic events (
```
events.jsonl
```
) with no API calls.
Confirm behavior in the real shell using
```
--tui-real
```
.
Encode findings into tests (unit, transcript golden, snapshot).

Use live

massgen --display textual

--textual-serve

only when needed.

在运行实时模型前优先使用确定性工作流：

从记录的/合成事件（
```
events.jsonl
```
）中复现，无需调用API。
使用
```
--tui-real
```
在真实shell中确认行为。
将发现的问题编码为测试（单元测试、脚本记录基准测试、快照测试）。

仅在必要时使用实时

massgen --display textual

或

--textual-serve

。

Quick Commands

快速命令

bash

undefined

bash

undefined

Full frontend/TUI test suite

完整前端/TUI测试套件

uv run pytest massgen/tests/frontend -q

Timeline transcript goldens

时间线脚本记录基准测试

uv run pytest massgen/tests/frontend/test_timeline_transcript_golden.py -q UPDATE_GOLDENS=1 uv run pytest massgen/tests/frontend/test_timeline_transcript_golden.py -q

Snapshot scaffold tests

快照框架测试

uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py -q uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py --snapshot-update -q uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py -q --snapshot-report snapshot_report.html uv run python scripts/render_snapshot_svgs.py --real-tui-only

Event replay (no API cost)

事件重放（无API成本）

uv run python scripts/dump_timeline_from_events.py /path/to/events.jsonl [agent_id] uv run python scripts/dump_timeline_from_events.py --tui /path/to/events.jsonl [agent_id] uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl [agent_id]

Example synthetic fixture

示例合成测试数据

uv run python scripts/dump_timeline_from_events.py --tui-real massgen/tests/frontend/fixtures/synthetic_tui_events.jsonl agent_a

undefined

uv run python scripts/dump_timeline_from_events.py --tui-real massgen/tests/frontend/fixtures/synthetic_tui_events.jsonl agent_a

undefined

Workflow

工作流程

1) Reproduce with Event Replay (No API Cost)

1) 使用事件重放复现（无API成本）

Start with transcript replay to verify timeline semantics quickly:

bash

uv run python scripts/dump_timeline_from_events.py /path/to/events.jsonl agent_a

Then inspect visually:

bash

undefined

先通过脚本记录重放快速验证时间线语义：

bash

uv run python scripts/dump_timeline_from_events.py /path/to/events.jsonl agent_a

然后可视化检查：

bash

undefined

Lightweight timeline-focused view

轻量级时间线聚焦视图

uv run python scripts/dump_timeline_from_events.py --tui /path/to/events.jsonl agent_a

Full runtime TextualApp shell

完整运行时TextualApp shell

uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl agent_a


Optional speed control for real replay:

```bash
MASSGEN_TUI_REPLAY_SPEED=8 uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl agent_a

Exit replay with

uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl agent_a


可选的实时重放速度控制：

```bash
MASSGEN_TUI_REPLAY_SPEED=8 uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl agent_a

按

退出重放。

2) Convert Findings into Tests

2) 将发现转化为测试

Pick the narrowest layer that captures the bug:

Unit logic:

test_tool_batch_tracker.py

test_content_processor.py

, helpers.

Transcript/golden behavior:

test_timeline_transcript_golden.py

massgen/tests/frontend/golden/

Widget/shell snapshots:

test_timeline_snapshot_scaffold.py

massgen/tests/frontend/__snapshots__/

Replay script behavior:

test_dump_timeline_from_events_script.py

选择最能覆盖问题的最窄层级：

单元逻辑：

test_tool_batch_tracker.py

、

test_content_processor.py

及辅助工具。

脚本记录/基准行为：

test_timeline_transcript_golden.py

massgen/tests/frontend/golden/

。

组件/shell快照：

test_timeline_snapshot_scaffold.py

massgen/tests/frontend/__snapshots__/

。

重放脚本行为：

test_dump_timeline_from_events_script.py

。

Final Presentation Focus Loop

最终展示聚焦循环

When iterating specifically on final-answer visualization:

Validate header semantics in unit tests (winner line, tie-break markers, vote line formatting) in
```
test_timeline_section_widget.py
```
.

Regenerate only final-presentation snapshots if intended UI changed:

uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py --snapshot-update -q

Verify runtime shell appearance with no API cost:

uv run python scripts/dump_timeline_from_events.py --tui-real massgen/tests/frontend/fixtures/synthetic_tui_events.jsonl agent_a

Run full frontend suite before finalizing:
- ```
uv run pytest massgen/tests/frontend -q
```

当专门迭代最终结果可视化时：

在
```
test_timeline_section_widget.py
```
的单元测试中验证头部语义（获胜行、平局标记、投票行格式）。

如果目标UI已变更，仅重新生成最终展示快照：

uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py --snapshot-update -q

无API成本验证运行时shell外观：

uv run python scripts/dump_timeline_from_events.py --tui-real massgen/tests/frontend/fixtures/synthetic_tui_events.jsonl agent_a

最终确定前运行完整前端测试套件：
- ```
uv run pytest massgen/tests/frontend -q
```

3) Snapshot Workflow

3) 快照工作流

If snapshot tests mismatch:

Open
```
snapshot_report.html
```
.
Check
```
Show difference
```
toggle interpretation:
- ON = blend-diff overlay (can look purple/black).
- OFF = raw current vs historical snapshots.
If change is intentional, regenerate with
```
--snapshot-update
```
.
Re-run the frontend suite to confirm stability.

如果快照测试不匹配：

打开
```
snapshot_report.html
```
。
检查
```
Show difference
```
切换的含义：
- 开启 = 混合差异叠加层（可能显示为紫色/黑色）。
- 关闭 = 原始当前快照与历史快照对比。
如果变更是有意的，使用
```
--snapshot-update
```
重新生成。
重新运行前端测试套件以确认稳定性。

3.1) Mandatory Screenshot Review

3.1) 强制截图审查

For visual/UI tasks, do not rely on test pass/fail alone. You must read screenshots directly before finalizing:

Review the snapshot images in
```
snapshot_report.html
```
(current vs historical).
Keep
```
Show difference
```
OFF first to verify raw rendering; then optionally use ON for pixel-level drift.
If screenshots are provided in chat/task context, inspect those images directly and compare against expected runtime appearance.
If your viewer cannot open
```
.svg
```
, render via browser engine:
- ```
npx playwright screenshot "file:///ABS/PATH/to/snapshot.svg" /tmp/snapshot.png
```
- Batch all (or real-TUI-only):
```
uv run python scripts/render_snapshot_svgs.py [--real-tui-only]
```
- Prefer this over ImageMagick conversion for Textual snapshots to avoid false artifacts.
Call out any mismatch between rendered snapshots and expected real TUI look, even if tests pass.
Only conclude "visual change verified" after explicit screenshot review.

对于视觉/UI任务，不要仅依赖测试通过/失败结果。在最终确定前必须直接查看截图：

在
```
snapshot_report.html
```
中查看快照图片（当前与历史对比）。
先保持
```
Show difference
```
关闭以验证原始渲染；然后可选择开启以查看像素级差异。
如果聊天/任务上下文提供了截图，直接检查这些图片并与预期运行时外观对比。
如果你的查看器无法打开
```
.svg
```
文件，通过浏览器引擎渲染：
- ```
npx playwright screenshot "file:///ABS/PATH/to/snapshot.svg" /tmp/snapshot.png
```
- 批量渲染（或仅真实TUI）：
```
uv run python scripts/render_snapshot_svgs.py [--real-tui-only]
```
- 对于Textual快照，优先使用此方法而非ImageMagick转换，以避免虚假差异。
即使测试通过，也要指出渲染快照与预期真实TUI外观之间的任何不匹配。
只有在明确审查截图后，才能得出“视觉变更已验证”的结论。

4) Optional Live Visual Validation

4) 可选实时视觉验证

Use live runs only after deterministic checks pass:

bash

undefined

仅在确定性检查通过后使用实时运行：

bash

undefined

Native terminal TUI

原生终端TUI

uv run massgen --display textual

Browser-hosted Textual

浏览器托管的Textual

uv run massgen --textual-serve

undefined

uv run massgen --textual-serve

undefined

Key Files

关键文件

scripts/dump_timeline_from_events.py

: text replay,

--tui

, and

--tui-real

modes.

massgen/frontend/displays/textual_terminal_display.py

TextualApp

, shell layout, runtime event routing.

massgen/frontend/displays/tui_event_pipeline.py

: timeline event adapter and filtering logic.

massgen/frontend/displays/timeline_event_recorder.py

: deterministic text transcript recorder.

massgen/tests/frontend/test_timeline_snapshot_scaffold.py

: snapshot scaffold (widget + real shell states).

massgen/tests/frontend/test_timeline_transcript_golden.py

: transcript golden regressions.

```
docs/modules/testing.md
```
: canonical testing commands and parity notes.

scripts/dump_timeline_from_events.py

：文本重放、

--tui

和

--tui-real

模式。

massgen/frontend/displays/textual_terminal_display.py

：

TextualApp

、shell布局、运行时事件路由。

massgen/frontend/displays/tui_event_pipeline.py

：时间线事件适配和过滤逻辑。

massgen/frontend/displays/timeline_event_recorder.py

：确定性文本脚本记录器。

massgen/tests/frontend/test_timeline_snapshot_scaffold.py

：快照框架（组件 + 真实shell状态）。

massgen/tests/frontend/test_timeline_transcript_golden.py

：脚本记录基准回归测试。

```
docs/modules/testing.md
```
：标准测试命令和兼容性说明。

Done Criteria

完成标准

A TUI change is complete when:

Relevant deterministic tests were added or updated first.
```
uv run pytest massgen/tests/frontend -q
```
passes.
Snapshot/golden updates are intentional and reviewed.
```
--tui-real
```
replay confirms expected real-shell behavior for the target scenario.

当满足以下条件时，TUI变更即完成：

已先添加或更新相关确定性测试。
```
uv run pytest massgen/tests/frontend -q
```
执行通过。
快照/基准更新是有意的且已审查。
```
--tui-real
```
重放确认目标场景的真实shell行为符合预期。