mcpField
T
textual-tui

textual-tui

github.com/tristanmanchester开发365 次安装7 周前更新
代码仓库

关于 textual-tui

用于构建和维护 Textual 终端用户界面的指导技能，涵盖应用结构、响应式工作与状态、安全脚手架、交付和测试。

主要功能

  1. 01选择屏幕结构与内置组件
  2. 02安全处理异步任务和取消
  3. 03预览并写入起始模板
  4. 04检查交付方式与运行时安全
  5. 05测试键盘、布局和工作任务

适用场景

  1. 01规划 Textual 应用结构
  2. 02添加响应式后台工作
  3. 03生成并集成起始应用
  4. 04测试取消行为和窄屏布局

安装

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

$npx skills add https://github.com/tristanmanchester/agent-skills --skill textual-tui

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/project/
github-actions-ci.yml.tmpl
pyproject.toml.tmpl
assets/templates/
admin_modes_app.py.tmpl
admin_modes_tcss.tmpl
admin_modes_test.py.tmpl
chat_app.py.tmpl
chat_tcss.tmpl
chat_test.py.tmpl
dashboard_app.py.tmpl
dashboard_tcss.tmpl
dashboard_test.py.tmpl
data_explorer_app.py.tmpl
data_explorer_tcss.tmpl
data_explorer_test.py.tmpl
download_demo_app.py.tmpl
download_demo_tcss.tmpl
download_demo_test.py.tmpl
editor_app.py.tmpl
editor_tcss.tmpl
editor_test.py.tmpl
file_browser_app.py.tmpl
file_browser_tcss.tmpl
file_browser_test.py.tmpl
form_app.py.tmpl
form_tcss.tmpl
form_test.py.tmpl
log_monitor_app.py.tmpl
log_monitor_tcss.tmpl
log_monitor_test.py.tmpl
settings_app.py.tmpl

详细介绍

文本应用

检查应用、锁定的依赖项、入口点、TCSS、测试和实际用户工作流。优先选择内置组件和组合方式，而不是自定义渲染。将应用状态与长时间运行的工作分开，并将键盘操作路径放在首位。不要要求每个应用都具备仪表板、模式系统或命令面板。

选择结构

小型工具可以只使用一个 App；当用户上下文发生变化时，使用独立的 Screen；短暂中断时，使用 ModalScreen；局部步骤使用 ContentSwitcher；只有在顶层屏幕栈确实彼此独立时，才使用模式。使用稳定的 ID 和语义类来设置样式和编写测试，先适配窄终端，再扩展到更宽的面板。如果 DataTable、Tree/DirectoryTree、MarkdownViewer、TextArea 和内置输入组件的行为符合需求，就优先使用它们。不要仅为了满足行数启发式规则而拆分内聚组件。

仅在需要时阅读架构、组件或屏幕。

响应式工作与状态

更改并发行为前，请先阅读响应式机制与工作线程。异步工作线程共享事件循环：将阻塞调用包装在 async def 或 @work 中，并不会让它们变为非阻塞。请使用异步 API；对于阻塞 I/O，使用 thread=True；对于大量 CPU 工作，采用合适的进程或原生策略。

独占取消不等于事务回滚，也无法保证线程已经停止。传递请求修订号，并在 UI 线程应用结果时再次检查。区分工作线程失败、取消、无数据和成功返回数据这几种情况。已取消的远程写入仍可能已经发生。

reactive 控件会刷新相关状态；var 保留响应式功能，但不会自动刷新或重新布局。如果不需要响应式行为，两者都不能替代普通字段。保持计算方法开销低且纯粹，并确保 watcher 不执行阻塞工作。请有意识地初始化挂载前的响应式值。

现有项目与源码工具

将 SKILL_DIR 解析为已安装的技能目录，而不是应用仓库。检查/审计辅助工具只能提供启发式源码线索，不能证明架构正确、运行时响应式行为正常或缺失功能。更改标记出的代码前，请先阅读。不要仅为消除启发式警告而添加调色板/浏览器/导出/断点机制。

dump_dom_and_bindings.py 会使用 run_test 导入并运行应用；这可能执行启动操作以及网络/文件系统操作。仅在获授权的隔离测试环境中，配置好模拟服务和适当设置后运行。它并非被动读取源码。生成的 Pilot 测试和快照工具同样如此。

安全脚手架

入门模板仍然可用，但现在默认先预览生成结果：

python "$SKILL_DIR/scripts/scaffold_textual_app.py" --list-templates
python "$SKILL_DIR/scripts/scaffold_textual_app.py" \
  --template data-explorer --module my_app --class-name MyApp --app-title 'My App'

检查渲染后的应用、TCSS 和测试。要写入文件，请添加 --write --output-dir，并指定一个新的最终目录，且其父目录必须已存在。没有强制覆盖选项，也没有自动配置 pyproject/CI 的选项。自由输入的标题会作为 AST 字符串值插入，标识符会经过验证，并且所有选定的模板都会在写入前解析。生成的 Python 会由 ast.unparse 重新格式化，不会被执行。写入失败可能会留下不完整的私有草稿；它不是原子性多文件事务。

对于聊天入门模板，请阅读请求归属与测试。其中明确的 Stop 操作、草稿保留和延迟结果检查，都是所提供示例的一部分，不能仅凭工作线程装饰器推断出这些行为。

有选择地将生成内容集成到应用中。根据现有项目以及当前支持的 Python/工具版本审查打包和 CI 设置，不要直接照搬新的通用构建系统。较早的独立生成辅助工具只是可选的起步脚手架，不代表当前的依赖/CI 策略，也不会自动升级项目。

运行时、交付与测试

使用已安装的 textual-dev CLI 帮助文档了解 devtools/console/serve。提供服务会暴露一个具有文件系统和服务权限的服务器端应用；它不是沙箱，也不会自动构成身份验证边界。在通过浏览器交付前，请核实网络绑定、身份验证、租户隔离，以及实际提供下载的文件。将用户文本以及终端/标记语言转义序列视为不可信的显示数据。

使用 run_test/Pilot 测试变更后的行为，包括实际断言、失败/取消、焦点与键盘操作、窄/宽尺寸，以及清理。只有当视觉布局是相关风险时才使用快照，而不是将快照作为每次变更都必须满足的配额。固定睡眠时间不能证明工作线程或布局已稳定；请等待有界的可观察状态。无头测试无法证明每种实际终端/浏览器都会以相同方式渲染。用户正在阅读较早内容时，应保留其滚动位置，而不是始终将日志自动锚定到最新位置。

报告补丁、实际测试命令/结果，以及尚未测试的终端/浏览器路径。不要声称脚手架、语法解析或黄金截图证明了生产就绪。将 测试、浏览器交付 和 打包 作为特定主题的参考资料。

维护者：python "$SKILL_DIR/scripts/self_check.py" 会解析所有本地脚手架输出；python -m unittest discover -s "$SKILL_DIR/tests" -v 会测试脚手架引擎。这两者都不会执行生成的应用。

已审阅的来源（2026-09-13）：Textual 元数据、工作线程、响应性和测试。

评论

支持 Markdown