结构化抓手 · 调参协议（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 改动，验证"改了能生效、固化能还原"。

反模式（禁止）

• ❌ 继续盲猜数值而不造抓手。
• ❌ 参数写死分散在代码各处（找不到、改不动）。
• ❌ 只有参数没有实时反馈（用户无法立刻感知变化）。
• ❌ 描述模糊时硬翻译成数字（必须先建映射表或直接给滑块让用户自己拉）。

常见问题（Common Issues）

• 滑块拖了没反应 → 面板没写回同一个对象引用（零重建原则被破坏），检查 store 与渲染是否共用引用。
• 改了能生效，导出固化后还原不了 → smoke test 没覆盖"固化→还原"路径，补测试。
• 用户还是说模糊感受 → 映射表没建全，把"太飘/太灵"这类词先映射到具体参数再迭代。
• 参数太多找不到 → 按领域分组（角色/世界/相机/光照…），面板分组展示。

落地示例（本技能自带的案例）

• 桌宠手感调参：见 references/feel-tuner-example.md（引擎参数抽离 + 滑块面板 + 宠物包携带手感）。
• 游戏调参器架构（原文案例）：见 references/game-tuner-architecture.md。