tuning-panel

调参面板技能

创建定制的参数调优面板，让用户能够直观地控制正在迭代的值。这些面板会显示当前任务的所有相关参数，支持实时调整，并以适合大模型的格式导出调优后的值。

核心理念

宁可详尽，不要遗漏。 用户调优某项内容时，应显示所有可能合理影响结果的参数。缺少参数会迫使用户切换上下文；参数“太多”只会增加滚动距离。

仅在调试模式下显示。 调参面板绝不应出现在生产环境中。使用环境检查、构建标志或 URL 参数。

仅导出已更改的值。 大模型导出内容应只显示调优过的值，而不是全部 100 多个参数。

平台选择

平台	库	参考文档
React	Leva（推荐）	references/react-leva.md
SwiftUI	原生控件	references/swiftui.md
Vanilla JS	Tweakpane 或 dat.GUI	references/vanilla-js.md

实现工作流

步骤 1：识别所有可调参数

分析要调优的代码，并提取所有会影响输出的参数。按领域划分的详尽列表，请参阅 references/parameter-categories.md。

常见类别：

• 动画：时长、延迟、缓动、弹簧物理参数（刚度、阻尼、质量）
• 布局：内边距、外边距、间距、宽度、高度、位置
• 视觉：颜色、不透明度、阴影、边框、变换
• 排版：字号、行高、字间距、字重

发现策略：

1. 搜索魔法数字（任何硬编码的数值）
2. 查找样式对象（CSS-in-JS、内联样式、主题值）
3. 查找动画定义（Framer Motion、CSS 过渡、SwiftUI 动画）
4. 查找颜色值（文件中的任何位置，包括十六进制、RGB、HSL）
5. 检查带有数值或颜色默认值的组件属性
6. 检查 CSS 自定义属性（--var-name 声明）

步骤 2：创建调试模式面板

封装调参面板，使其仅在开发环境中显示：

• React：process.env.NODE_ENV === 'development'
• SwiftUI：#if DEBUG
• Vanilla JS：URL 参数 ?debug 或环境检查

代码示例请参阅对应平台的参考文档。

步骤 3：实现控件

遵循以下原则：

1. 使用文件夹/分区对相关参数进行分组
2. 使用合适的控件类型：数值使用滑块，颜色使用颜色选择器，枚举使用下拉菜单
3. 根据参数范围设置合理的最小值、最大值和步长
4. 为常见配置添加预设
5. 添加重置按钮，以恢复默认值

步骤 4：添加大模型导出

关键要求：

1. 在初始化时保存默认值，用于比较
2. 为浮点数设置容差（例如，Math.abs(a - b) > 0.001）
3. 仅筛选已更改的值——不显示未更改的参数
4. 采用易读的格式——按类别分组，使用易懂的名称

导出格式：

## Tuned Parameters for [ComponentName]

### Changed Values
- Duration: 300 → 450
- Spring Damping: 0.80 → 0.65
- Corner Radius: 12 → 16

### Apply These Values
Update the component at `src/components/Card.tsx:42` with the values above.

重要原因：

• 面板可能会显示 100 多个参数
• 导出所有值会浪费词元，并掩盖实际更改的内容
• 默认值 → 当前值 的格式便于快速浏览差异

其他资源

参考文件

• references/react-leva.md - 完整的 React/Leva 实现指南
• references/swiftui.md - SwiftUI 原生控件和导出模式
• references/vanilla-js.md - 用于原生 JS 的 Tweakpane 和 dat.GUI
• references/parameter-categories.md - 按领域划分的详尽参数列表

示例文件

• examples/react-leva-animation.tsx - 完整的动画调参面板
• examples/export-format.md - 完整的大模型导出模板