structured-handlelisted

# 结构化抓手 · 调参协议（Structured Handle） > 思想来源：AI 游戏调参器文案（用户分享）——"让 LLM 猜数值 = 无限次盲人摸象；让 LLM 造调参器 = 一次性给我一把游标卡尺。调参器不是工具，是协议。" > 适用场景：任何"AI 反复改数值、用户反复试、总感觉不对"的循环。 ## 何时触发（识别信号） 满足任一即启动本技能： 1. 同一批数值被 AI 猜改 ≥2 轮，用户仍说"感觉不对 / 更 X 一点 / 差口气"。 2. 任务成果的"手感/观感/体验"由多个可量化数值决定（物理参数、动画参数、间距、强度、语气刻度等）。 3. 用户希望"自己也能调"某个体验，而不只是依赖 AI 改代码。 4. 需要把体验参数分享/固化（导出配置、进产物包、跨端一致）。 **何时不用（Do NOT use for）**：单个数值的简单修改（直接改即可）；用户已明确给出具体参数值；纯视觉/内容任务（与数值无关）。 ## 核心流程（四步） ### 第 1 步：识别并停下"盲猜循环" - 若已进入猜数值循环，**先停止猜测**，向用户说明："与其我猜，不如先把参数变成你能拖的滑块"。 - 盘点该体验由哪些数值决定（列全，包括藏在代码里的魔法数字）。 ### 第 2 步：造结构化抓手 - **抽参数**：把所有魔法数字抽成单一配置对象（可变对象，不是 `as const`），各模块 `import { X } from 'config'` 引用同一份。 - **声明参数安全域**：每个参数必须标注 `下限-默认-上限` 三档（默认居中，上下限是"不搞崩体验"的边界）。例：重力 `-30 / -10 / -2`；浮动幅度 `0 / 5 / 12`。**给数值域时禁止随手写宽范围**，超界体验会崩。 - **可视化**：做一个参数面板（滑块/输入框）——滑块范围 = 安全域，步进取安全域的 5%-10%。 - **实时生效**：面板通过状态 store 写回同一个对象引用 → 下一帧/下一次渲染自动读到新值，**零重建、零热更新**。 - **活对象桥**：对运行时已创建的对象（如 THREE 光照/雾/颜色），写一个"桥"文件，用 `.color.set()` / `.intensity =` 直接改活对象，不重建。 ### 第 3 步：协议化沟通（核心） - 建立"模糊描述 ↔ 精确参数"映射表（例：用户说"太飘" → 重力/阻尼系数；"太灵" → 灵敏度/响应速度）。 - **接收量化分（来自 feel-calibrator）**：若上游给了 0-100 量化分，按比例映射到安全域：`参数值 = 下限 + (分数/100) × (上限-下限)`；分差 ±10 分 ≈ 参数域 ±10% 步进。没有量化分就用映射表直接给建议。 - 此后沟通在参数层进行：用户说模糊感受 → 映射到具体参数 → 给精确建议或直接改。 - **参数是量化的，语言是模糊的**——在参数层迭代，不回到自然语言来回撕。 ### 第 4 步：固化闭环 - 一键导出参数（JSON / 常量文件）→ 粘回代码固化。 - 参数随产物一起交付（进游戏存档、宠物包 manifest、UI 主题配置等），让"手感"可分享、可复现。 - 写 smoke test：模拟运行时捕获引用后被 tuner 改动，验证"改了能生效、固化能还原"。 ## 反模式（禁止） - ❌ 继续盲猜数值而不