mcpField
T
textual-ui-developer

textual-ui-developer

github.com/massgen开发1.1k101 次安装20 周前更新
代码仓库

关于 textual-ui-developer

textual-ui-developer 是用于调试、验证和测试 MassGen Textual UI 的技能。它优先采用确定性事件回放和回归测试，再考虑运行实时模型。

主要功能

  1. 01回放记录或合成事件
  2. 02在真实终端界面检查 UI
  3. 03添加单元、转录和快照测试
  4. 04审查并更新快照与基准文件
  5. 05运行前端测试套件

适用场景

  1. 01调试时间线渲染与排序
  2. 02在终端界面验证布局改动
  3. 03无需 API 调用即可复现 UI 行为
  4. 04通过测试记录 UI 回归

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/massgen/massgen --skill textual-ui-developer

安装后在 Claude Code 中输入/textual-ui-developer确认已加载。

详细介绍

Textual UI 开发者

使用此技能改进 MassGen Textual UI，同时尽量减少不稳定的复现和 API 成本。

适用场景

  • 需要调试时间线渲染或排序问题。
  • 需要在真实 Textual shell 中验证布局或样式更改。
  • 需要更新或添加 TUI 回归测试（快照／黄金样例／转录）。
  • 需要根据 events.jsonl 确定性地复现 UI 行为。

默认策略

优先采用确定性工作流，再运行实时模型：

  1. 使用记录的／合成的事件（events.jsonl）复现，不调用 API。
  2. 使用 --tui-real 在真实 shell 中确认行为。
  3. 将结果编入测试（单元测试、转录黄金样例、快照）。
  4. 仅在必要时使用实时 massgen --display textual 或 --textual-serve。

快速命令

# Full frontend/TUI test suite
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)
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

工作流

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

先回放转录，快速验证时间线语义：

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

然后检查视觉效果：

# Lightweight timeline-focused view
uv run python scripts/dump_timeline_from_events.py --tui /path/to/events.jsonl agent_a

# Full runtime TextualApp shell
uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl agent_a

实时回放时可选择调整速度：

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

按 q 退出回放。

2) 将结果转化为测试

选择最精简且能覆盖该问题的层级：

  • 单元逻辑：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。
最终展示检查循环

如果专门迭代最终答案的可视化效果：

  1. 在 test_timeline_section_widget.py 的单元测试中验证标题语义（获胜者行、平局标记、投票行格式）。
  2. 如果 UI 有预期更改，只重新生成最终展示快照：
    • uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py --snapshot-update -q
  3. 无需 API 成本，验证运行时 shell 的外观：
    • uv run python scripts/dump_timeline_from_events.py --tui-real massgen/tests/frontend/fixtures/synthetic_tui_events.jsonl agent_a
  4. 最后运行完整的前端测试套件：
    • uv run pytest massgen/tests/frontend -q
3) 快照工作流

如果快照测试不匹配：

  1. 打开 snapshot_report.html。
  2. 检查 Show difference 开关的含义：
    • ON = 混合差异叠加层（可能看起来是紫色／黑色）。
    • OFF = 当前快照与历史快照的原始图像。
  3. 如果更改是有意的，使用 --snapshot-update 重新生成。
  4. 重新运行前端测试套件，确认稳定性。
3.1) 必须检查截图

对于视觉／UI 任务，不要仅凭测试通过或失败来判断。最终确认前必须直接查看截图：

  1. 在 snapshot_report.html 中检查快照图像（当前与历史版本）。
  2. 先关闭 Show difference，验证原始渲染效果；然后可选择开启该选项，检查像素级差异。
  3. 如果聊天／任务上下文中提供了截图，请直接检查这些图像，并与预期的运行时外观进行对比。
  4. 如果图像查看器无法打开 .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 转换，以避免产生虚假伪影。
  5. 即使测试通过，也要指出渲染后的快照与预期的真实 TUI 外观之间的任何不匹配。
  6. 只有在明确检查过截图后，才能得出“视觉更改已验证”的结论。
4) 可选的实时视觉验证

仅在确定性检查通过后运行实时验证：

# Native terminal TUI
uv run massgen --display textual

# Browser-hosted Textual
uv run massgen --textual-serve

关键文件

  • 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：权威测试命令和一致性说明。

完成标准

满足以下条件，即表示 TUI 更改已完成：

  1. 首先添加或更新了相关的确定性测试。
  2. uv run pytest massgen/tests/frontend -q 通过。
  3. 快照/黄金测试更新经过审慎评估和审查。
  4. 使用 --tui-real 回放，确认目标场景下真实 Shell 的行为符合预期。

评论

支持 Markdown