TRAE-dynamic-ui
TraeWork 内置 skill —— 动态 UI 渲染。通过 PureShowWidget 工具生成可视化内容（图表、可视化、报告、对比、看板），支持 inline（对话流内）和 panel（独立面板）两种模式。
一、定位
| 字段 | 值 |
|---|---|
| 所属 | TraeWork 内置 skill（可视化） |
| 触发条件 | 用户要求图表、可视化、报告、对比、看板；或提到「动态 UI/图表/可视化」 |
| 核心方法 | 用 PureShowWidget 工具渲染 |
| ⚠️ 反触发 | 用户要求构建独立网站、Web 应用、生成 HTML 文件时不要触发 |
二、什么时候用 / 不用
2.1 什么时候用
- 用户要求图表、流程图、可视化
- 用户要求报告、对比、看板
- 用户提到「动态 UI」「图表」「可视化」
2.2 什么时候不要用
- ❌ 构建独立网页、网站、Web 应用
- ❌ 创建完整 HTML 项目或 landing page
- ❌ 生成 HTML 文件到磁盘
- ❌ 脚手架前端项目
经验法则：
如果意图是可交付的 Web 项目 → 不要用本 skill
如果意图是伴随聊天的视觉解释或交互小部件 → 用本 skill
三、两种模式选择
3.1 → Inline 模式
适用：
- 简单流程图（≤5 节点）
- 架构概览图
- 数据卡片（2-4 个 KPI）
- 小型 SVG 插图
- 交互式控件 demo
- 估算 HTML <100 行
特点：紧凑、高度有限、streaming 友好、与文字混排。
调用：PureShowWidget(mode="inline", ...)
必读：
references/design-system.md（必读）references/inline-mode.md（必读）references/svg-guide.md（如果是 SVG 图表）references/chart-guide.md（如果是图表 / 地图）
3.2 → Panel 模式
适用：
- 多选项对比（3+ 选项并排）
- 状态报告 / 周报（KPI + 图表 + 时间线）
- 看板 / 编辑器（拖放、可导出）
- 代码审查注释（多文件 diff + 评论）
- 概念解释器（多 section + 交互 demo）
- 仪表盘（多图表协调）
- 任何需要滚动、多区域、复杂交互的内容
- 估算 HTML >200 行
特点：无高度限制、多 section 布局、复杂脚本、可导出。
调用：PureShowWidget(mode="panel", ...)
必读：
references/design-system.md（必读）references/panel-mode.md（必读）references/chart-guide.md（如果是图表）
3.3 路由决策表
| 信号 | → 模式 |
|---|---|
| 估算 HTML <100 行 | inline |
| 估算 HTML >200 行 | panel |
| 需要滚动 | panel |
| 多 section / 多区域 | panel |
| 有导出功能 | panel |
| 纯 SVG 插图 | inline |
| 「做报告/看板/对比」 | panel |
| 「画图/流程图」 | inline |
| 100-200 行灰区 | 倾向 inline，除非需要滚动 / 多区域 |
四、工具参数
PureShowWidget 工具的参数：
| 参数 | 说明 |
|---|---|
mode | "inline"（默认）或 "panel" |
loading_messages | 1-4 条短消息，渲染时显示 |
title | snake_case 标识符 |
widget_code | SVG 或 HTML 代码 |
五、⚠️ 关键硬规则
5.1 流式输出顺序（硬规则）
widget_code 内容按 token 逐步流式渲染。必须严格按以下顺序输出：
<style>块最先输出 — 确保样式在内容出现前已就绪- HTML 内容 — 有了样式，内容一出现就是正确的视觉效果
<script>最后输出 — 脚本放在末尾，不阻塞视觉渲染
违反此顺序会导致流式渲染时内容先以无样式状态闪烁。任何模式下（inline / panel）都必须遵守。
5.2 事件绑定（硬规则）
永远不要在同一个元素上绑定两次事件——选一种并坚持：
- 在 HTML 元素上用
onclick属性（不需要<script>），或 - 在
<script>块里用addEventListener（HTML 元素上不要有onclick）
原因：渲染引擎先 innerHTML 注入 HTML，然后单独重跑 <script> 块。如果同时用 onclick 和 addEventListener，handler 会触发两次——比如 classList.toggle('open') 会先 toggle 开再 toggle 关，视觉上无效果。
推荐：在末尾的单个 <script> 块里用 addEventListener（结构 vs 行为分离更干净）。
六、生成 widget 的 5 步流程
- 必读
references/design-system.md（色彩 + 排版规范） - 必读
examples/INDEX.md，匹配当前场景对应的 1-2 个最相近示例 - 读匹配的示例文件——研究它的 CSS 结构、grid 布局、色彩分配、签名元素（eyebrow、pills、accent bars）
- 根据 Mode Routing 结果加载模式规则：
inline-mode.md或panel-mode.md - 生成 widget — 用相同结构手法，为用户请求填充新内容
6.1 从示例学什么
- 布局：grid 列、flex 模式、max-width、padding 节奏
- 色彩分配：类别如何映射色彩 ramp（sky=primary、mint=success、coral=error、amber=warning）
- 签名元素：eyebrow 标签、accent bars、状态 pills、带大彩色数字的 metric 卡片
- 交互：hover 状态、click handler、动画、导出按钮
- 排版：serif 标题、mono eyebrows/code、sans body。只用 400 和 600 字重
6.2 最低视觉质量门槛
每个 widget 必须有：
- 至少 1 个非灰色色彩 ramp 有意义地应用
- 第一个 section 上有 eyebrow 标签（mono 11px 大写）
- 正确层级：serif 标题 > sans body > mono 元数据
- 卡片 / 面板用
var(--color-background-primary)+ 边框 + 圆角
如果输出看起来像纯灰文字在框里 → 没达标。加颜色、加节奏、加视觉签名。
七、20 个示例模板
| # | 模板 | 用途 |
|---|---|---|
| 01 | exploration-approaches | 多方案探索 |
| 02 | exploration-visual-directions | 视觉方向探索 |
| 03 | implementation-plan | 实现计划 |
| 04 | code-review-pr | PR 注释审查 |
| 05 | code-review-writeup | PR 说明文档 |
| 06 | module-map | 模块架构图 |
| 07 | prototype-animation | 动画原型 |
| 08 | prototype-interaction | 交互原型 |
| 09 | svg-illustrations | SVG 技术插图 |
| 10 | flowchart | 流程图 |
| 11 | slide-deck | 幻灯片 |
| 12 | feature-explainer | 功能解释器 |
| 13 | concept-explainer | 概念教学 |
| 14 | status-report | 周报/状态 |
| 15 | incident-timeline | 事故复盘 |
| 16 | triage-board | 工单分诊看板 |
| 17 | feature-flags | Feature Flag 编辑器 |
| 18 | prompt-tuner | Prompt 调优器 |
| 19 | metrics-dashboard | 监控仪表盘 |
| 20 | comparison-matrix | 技术方案对比 |
八、引用来源
- TraeWork 实际 skill 路径 —— 本文内容完全来自此文件
- 同目录的
references/和examples/文件夹
九、一句话总结
TRAE-dynamic-ui 是「动态 UI 渲染」技能——通过 PureShowWidget 工具把可视化嵌入对话流（inline）或独立面板（panel）。关键纪律：<style> 先输出、HTML 居中、<script> 最后；不要重复绑事件；用设计系统 + 示例做参考，不从零画。