dwgx/SmartCLI / skills/tui-ui
tui-ui
VerifiedDesign web-like user interfaces in the terminal and inside tmux with a cell-grid Canvas, CSS-like box model, flexbox/grid layout, and 17 reusable widgets such as Panel, Table, Card, ProgressBar, Meter, Tabs, Tree, Badge, Banner, and a braille line chart. Use when an agent needs a dashboard, panel, table, status page, TUI layout, tmux dashboard, screenshot-driven CLI/TUI replica, ANSI frame, truecolor render, pyte PNG screenshot smoke test, wide-character alignment, or a new terminal widget.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.0 KB |
| _selftest_effort_widgets.py | script | 4.9 KB |
| _shot_effort_widgets.py | script | 4.7 KB |
| examples/effort_selector.py | script | 22.1 KB |
| references/HARD-LESSONS.md | markdown | 7.5 KB |
| references/RENDERING-MODEL.md | markdown | 5.4 KB |
| references/effort-replica-spec.md | markdown | 11.8 KB |
| self_test.py | script | 5.7 KB |
| ui/__init__.py | script | 1.4 KB |
| ui/__main__.py | script | 183 B |
| ui/box.py | script | 9.2 KB |
| ui/cli.py | script | 8.7 KB |
| ui/core.py | script | 26.0 KB |
| ui/field.py | script | 19.7 KB |
| ui/layout.py | script | 11.1 KB |
| ui/raster.py | script | 27.9 KB |
| ui/registry.py | script | 2.7 KB |
| ui/sixel.py | script | 9.2 KB |
| ui/widgets.py | script | 24.3 KB |
| ui/widgets_ext/__init__.py | script | 207 B |
| ui/widgets_ext/braille_chart.py | script | 6.7 KB |
| ui/widgets_ext/fuzzy_filter_list.py | script | 5.0 KB |
| ui/widgets_ext/gradient_rule.py | script | 3.5 KB |
| ui/widgets_ext/preview_pane.py | script | 3.1 KB |
| ui/widgets_ext/radial_glow.py | script | 8.8 KB |
| ui/widgets_ext/slider_track.py | script | 7.7 KB |
references/HARD-LESSONS.md
View on GitHub# HARD LESSONS — 复刻真实 TUI 效果时踩过的坑(必读,血泪总结)
> 这份文档是训练资产。复刻任何"真实存在的" TUI/CLI 效果(如某个真实终端的 /effort-style 选择器、
> 某个 CLI 的动画、一个截图里的 UI)之前,先读完这 10 条铁律。
> 每一条都对应一次真实的、代价高昂的失败。违反任何一条 = 大概率重蹈覆辙。
## 背景:一次典型的失败模式
复刻参考选择器 `/effort`-style 的 ultracode 紫色动画,前后改了 **十几轮**,每轮都
自我感觉"这次对了",每轮用户一看真终端都是"还是不对"。根因不是代码能力,是
**方法**:一直在"盲猜 + 自我验证",从不看真实的东西。下面是提炼出的铁律。
---
## 铁律 1 — 有 ground truth 就必须先拿到,禁止脑补
**坑**:对着反编译源码/记忆脑补目标长什么样,然后写代码去逼近脑补的结果 →
误差叠误差,永远差一口气。
**根因**:把"我以为的样子"当成了"真实的样子"。
**做法**:复刻真实程序前,先用一切手段拿到 ground truth——
- 能拿到源码/字节就读精确常量;
- 有真程序就**用 SmartCLI 驱动它、抓真实渲染的每个格子字节/颜色**;
- 有动画就**截成多帧 PNG,逐帧看**。
对着 ground truth 做,不对着想象做。
## 铁律 2 — 尺度先确认,别猜"它大概是个什么"
**坑**:把一个 **8 行 × 88 列的大矩形光晕块**,误当成"贴着滑块条的 1-2 行细波纹",
猜了十几轮方向都错,因为尺度差了一个数量级。
**根因**:只抓了单行数据就下结论整体形态。
**做法**:先测**边界**——真实效果占几行几列(`row_cells` 扫所有行,记录每行
washed 的列区间)。形态(一维波纹 vs 二维矩形 vs 圆形光晕)在写任何渲染前必须先确定。
## 铁律 3 — 动画必须看"多帧",一帧推断不出运动
**坑**:只抓一帧静态图,就去猜动画是"平移/扩散/脉动",方向和形态全靠猜,反复错。
**根因**:单帧不含时间信息。"流动"≠"扩散"≠"脉动",看一帧分不清。
**做法**:抓**连续多帧**(真程序进入该状态的瞬间起,每 0.1~0.15s 一帧),
测量随时间变化的量(如 washed 区域的左边缘列号)。真实 /effort 的展开就是这么
测出来的:左边缘 col 49→39→27→8 单调左移 = 从 ultracode 向外扩散,~31 列/秒。
## 铁律 4 — 用真实运行验证,禁止用"自我感觉良好"验证
**坑**:改完渲染一张 pyte 静态 PNG,自己看着"差不多"就说"这次对了",
但那不是用户真终端看到的东西。
**根因**:pyte 渲染 / 手动 patch 过的测试环境 ≠ 真实运行环境。
**做法**:验证必须**在真实运行路径上**——真终端打开,或用 SmartCLI 驱动脚本本身、
抓它真实输出的字节。见铁律 8(自我验证)。
## 铁律 5 — 测试时的 monkeypatch 会掩盖真实崩溃
**坑**:测 PNG 时手动 `es.dist = _dist` 打了补丁,所以"自测通过";但脚本自己跑
根本没导入 `dist`,交互模式一渲染就 `NameError` 崩溃、输出全黑。用户真终端看到的
"错" = 脚本崩了,不是效果错。
**根因**:测试环境注入了脚本本身缺失的依赖,制造了虚假的成功。
**做法**:验证时**跑脚本自己的完整启动路径**(`python script.py`),不要在测试
harness 里替脚本补它缺的东西。抓 stderr。一个 import 没写全,真跑就现原形。
## 铁律 6 — 交互式 TUI 别因 isatty()=False 就降级退出
**坑**:`if not sys.stdout.isatty(): render_once(); return` —— 在 PTY(含我们
自己的 SmartCLI 驱动)下 isatty 常是 False,导致脚本只画一帧静态图就退出,
**动画根本没跑**,看起来"冻住了"。
**根因**:把 isatty 当成了"要不要动画"的开关,其实它只该决定"要不要读键盘输入"。
**做法**:渲染/动画循环无条件跑;只有**按键输入**才依赖真 tty。
## 铁律 7 — 终端换行必须 CRLF,LF 不回列
**坑**:`Canvas.to_ansi()` 用 `\n` 分行,喂给终端/pyte 时每行叠在上一行末尾列,
前几行内容被覆盖吃掉。
**根因**:终端默认 LNM 关闭,LF = 只下移不回列,需要 CR 回列。
**做法**:输出到终端/喂 pyte 前把 `\n` → `\r\n`(harness 的 `render_bytes_to_screen`
已内置这个归一化)。
## 铁律 8 — 自我验证的正确姿势:用 SmartCLI 驱动"自己写的东西"
**坑**:一直渲染静态图自我感觉良好;而真正该做的是——**我自己就是 agent CLI,
手里有 SmartCLI 驱动真 CLI + 抓屏的能力,却不用它去看真实的东西**。
**做法**(用户点破的关键):
1. `PtySession` 驱动**真实目标程序**,抓 ground truth(字节级颜色、多帧动画)。
2. `PtySession` 驱动**自己写的脚本**,抓它真实渲染 + stderr,逐帧对比 ground truth。
3. 差异用数字量化(washed 行数/列区间/左边缘随时间),不用"看着像"。
坑:抓自己时若脚本进了 alt-screen(`?1049h`),pyte 抓的是主屏(空的)——
改为把脚本 stdout 字节按 HOME(`\x1b[H`) 切帧、取最后一帧喂 pyte 渲染,才是真输出。
## 铁律 9 — Windows 非 UTF-8 stdout 会因非 ASCII 字形崩溃
**坑**:输出 `▀`/`⏵`/box-drawing 等非 ASCII 字形时,Windows 管道用 gbk/cp936
编码 → `UnicodeEncodeError` → 脚本崩。
**做法**:启动时 `sys.stdout.reconfigure(encoding='utf-8', errors='replace')`;
读取子进程输出时也强制 UTF-8。
## 铁律 10 — 别问用户"它长什么样",你有能力自己去看
**坑**:反复失败后想让用户描述/截图。但用户明确说:"你当然截图自己研究就行了。"
**根因**:忘了自己具备驱动真程序 + 抓屏 + 渲染 PNG 的完整能力。
**做法**:能自己拿到的 ground truth,就自己去拿。用户的时间用在拍板方向,
不该用在替 agent 做它能做的观察。
---
## 复刻真实效果的标准流程(把上面十条串起来)
1. **拿 ground truth**:反编译读常量 + SmartCLI 驱动真程序抓字节 + 多帧 PNG。(律1/3/8/10)
2. **测尺度与形态**:几行几列、一维/二维、静态/动画、怎么动。(律2/3)
3. **提取精确参数**:调色板真值、边界坐标、动画速度(量化,不估)。
4. **对着 ground truth 写**,不脑补。
5. **真实运行验证**:跑脚本完整启动路径(不 patch),抓 stderr,SmartCLI 抓自己逐帧对比。(律4/5/8)
6. **真终端确认**:CRLF、isatty 不降级、UTF-8 stdout。(律6/7/9)
7. 只有 ground truth 逐项对上,才算"做对了"。自我感觉不算数。
## 案例存档(可复现的 ground truth)
- `examples/effort_selector.py` — 验证过的最终复刻(violet 矩形 wash + 从 ultracode 展开),精确几何/调色板/动画常量的单一真实来源
- `ui/field.py::Ripple` — 它组合的涟漪原语
## 知识图谱(先看再动手)
本文是训练资产的"血泪原文";它在 SmartCLI 知识图谱里有一个带交叉链接的 twin。
复刻/创作任何效果前,先读 `knowledge/INDEX.md`(repo 根目录;skill 单独安装时以 `references/` twin 为准):
- **复刻**(还原真实存在的 UI/动画/截图)→ [[hard-lessons]](本文的图谱 twin)+ 已测量的 case [[effort-selector]]。
- **创作**(设计新组件/效果)→ [[rendering-model]](四原语内核,对应 `RENDERING-MODEL.md`)。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |