widgets-state-security-distribution

Widget、状态、配置、安全与分发

当 TUI 需要产品级交互模式、健壮的应用状态、安全的终端处理、用户自定义或发布指导时，请使用此技能。

Widget 设计原则

• 每个 widget 都应具备状态、焦点规则、键盘行为、（如支持）鼠标行为、验证、无障碍回退方案和快照测试。
• 保持交互可预测：列表用于导航，表格用于排序／筛选／分页，表单在字段附近进行验证，对话框锁定焦点，命令面板搜索命令，滚动条指示位置但不是必需的。
• 对大型列表／表格／树进行虚拟化，并将视口偏移量、选中项和展开的节点保存在状态中。
• 对图表、进度条、微调器和仪表盘，提供文本摘要以及减少动态效果／禁用动画的模式。

状态与事件架构

优先采用显式的 model-update-view 或 reducer 架构：

1. Model 存储领域状态和 UI 状态。
2. 事件／消息表示按键、鼠标、粘贴、调整大小、定时器、工作线程结果和错误。
3. Update 转换状态并安排副作用。
4. View 根据状态和尺寸进行渲染。
5. 副作用异步运行并返回消息。

这样可以保证渲染具有确定性、降低测试成本，并防止后台任务直接向终端写入内容。

配置与自定义

• 在适用的类 Unix 系统上使用 XDG 基础目录；在 Windows 和 macOS 上使用平台原生的配置／缓存／状态目录。
• 允许高级用户以及 tmux/Zellij 等冲突较多的环境重新映射按键绑定。
• 将主题存储为语义角色，而非特定 widget 的原始颜色。
• 严格验证配置文件；如果 TUI 无法启动，则以纯文本形式显示可采取行动的错误信息。

终端安全

终端输出会被解释执行。在将不受信任的文本写入终端，或写入日后可能在终端中查看的日志之前，请先对其进行净化。转义序列注入可能会更改标题、写入剪贴板数据、伪造提示、隐藏文本或破坏显示状态。

• 除非有意渲染，否则应剥除或以可见形式转义不受信任数据中的控制字符。
• 将粘贴的文本视为数据，而非命令。
• 限制粘贴长度，并在粘贴完成后进行验证。
• 避免根据不受信任的内容自动执行 OSC 52 剪贴板写入。
• 让超链接清晰可见，并避免使用误导性的链接文本。

分发规则

• 说明支持的终端和回退方案。
• 提供 --no-tui 路径，用于自动化、无障碍访问和故障恢复。
• 遵循平台惯例进行打包：在可行时提供静态二进制文件，并酌情提供 Homebrew/Scoop/Winget/MSI/软件包、Shell 补全、man 手册页和校验和。
• 在容器中检测缺失的 TTY，并提供按行处理的行为。
• 确保崩溃清理机制在发布版本中也能正常工作，而不只是在开发环境中有效。

参考文件

• references/widget-patterns.md - 常见终端 widget、行为约定和反模式。
• references/state-config-distribution-security.md - MVU 状态、异步副作用、配置、打包和终端安全。