全文如下，未拆分为渐近披露格式。需者自取。

Web App 建构手册

从当前用户的四个已上线项目（内容/可视化型、工具型、游戏型 × 2）完整迭代史中提炼出的、针对该用户项目的通用需求条款和经验。

目标：让该用户讲述原型想法的首轮提示词，沿最短路径迭代成打磨完毕、可公开上线的生产级应用。

Part 0 · 使用说明

• 本文档应作为该用户所有新 Web App 项目首轮提示词的隐含部分。AI 助手在新项目开始时应通读，以获取用户偏好和历史教训。
• 全文分三层效力，读法各不相同：
  • Part I 核心不变量——最强约束，任何形态、任何阶段成立。长对话中优先记住这一节。
  • Part II 综合偏好——以往项目的最佳实践集合。对新题材、平台不适用或存在更优实践方案时，说明不适用理由即可，不必征求用户许可。
  • 一些特定情况下的建议：按需取用。
    • Part III 阶段检查点，在开始/部署时注意。
    • Part IV 踩坑备忘，一张事实性知识清单。
    • Part V 详细条件触发附录。条件包括：React 工具型、需要后端时、LLM 驱动功能、规模化内容管线、PWA、数据可视化。
• 本文与用户自身描述或项目内已有 AI 记忆文档 / 设计文档冲突时，以用户 / 项目一方为准。若怀疑用户失误，需与之讨论；若怀疑项目文档错误或过时且无特殊留痕注释时，服从本文，并将该冲突记录在交接笔记里。
• 在充分了解新项目的需求后，可将下面相关内容选择性写入项目内 AI 记忆文档，减少对本文档的依赖。

Part I · 核心不变量

架构与数据

1. 输入是唯一事实源：派生数据（计算结果、排序名次、格式化文本）永不写入 store，一律在读取端被动派生——任何输入一变，所有下游自动重算，杜绝陈旧状态。基于性能的缓存必须可验证并明确失效条件。
2. 核心逻辑 headless 可测：引擎、解析、数学、store action 是纯逻辑，脱离浏览器直接跑 node/vitest。
3. 错误浮出 UI 且按条目隔离：console.warn 了事等于吞掉；N 个条目逐个 try/catch，一个失败不拖垮整批；网络访问统一走经过状态检查、解析校验和错误归一化的 API 层。应用级 ErrorBoundary / 全局 error handler 兜底，未捕获错误显示可恢复 UI，不白屏。
4. 秘密只活在服务端：API key、隐藏 prompt 放服务端专属目录，物理上进不了客户端 bundle；部署流程自动扫描产物防泄漏，不靠自觉。
5. 构建系统自维护：文件自动发现（整目录复制、清单从构建输出扫描生成），不许手写枚举；版本号单一事实源（package.json，构建注入各处）；缓存失效自动化。“要记得同步改两处"即架构 bug。
6. 一切路径相对：从第一行代码用 ./，dist/ 必须能原样拖进任何静态托管。
7. 把错误变成反馈而非异常：有不可靠参与者（模型、用户输入、第三方数据）时，校验失败作为语义反馈回灌给产生方（模型重决策、用户看到行内解释），不中断、不静默。
8. 拆分纪律：“能玩起来"之后的第一个功能开始就拆（状态/逻辑、渲染、输入、数据加载最小四件套）；单文件超过400行且职责混杂即拆；不许出现上帝对象。
9. 调试后门"生产默认关闭”，而非"生产记得去关”：显式请求声明 + 服务端环境开关双重门控，生产不设开关 = 默认拒绝；UI 入口用 import.meta.env.PROD 隐藏。开发/生产配置用运行时检测或构建期注入，不许出现"切换到生产环境"的手动提交。

界面

10. 界面状态切换必须瞬时：用户操作应立即获得视觉确认，点击后 >200ms 才生效的视觉反馈即 bug。根因通常是粗粒度全量重渲染，解法是派生 + 细粒度订阅。
11. 外观参数单点集中：所有颜色、字体、字号、间距、圆角、阴影、z-index、动画时长/缓动定义为 CSS 自定义属性，集中在单一入口；组件内禁止硬编码颜色。具体数值和曲线是品味（→Part II 审美品味），需要"活在 token 里"。
12. 禁止 emoji 当 UI 图标：正规图标一律内联 SVG。
13. 无障碍基线：aria-label / aria-expanded / role、纯图标按钮必有 aria-label、focus 管理、触摸目标 ≥44px、documentElement.lang 与界面语言同步、动画尊重 prefers-reduced-motion；模态从第一个起就有 focus trap + Escape 关闭 + role="dialog" / aria-modal / aria-labelledby 三件套。
14. 不可用必须可发现：控件不可用时，无论选择 disabled 还是隐藏，用户都必须能获知原因——disabled 需配就近提示，渐进披露式的隐藏需有引导入口。按钮文字随语境变。
15. 破坏性操作（删除、覆盖）必过确认，或有可逆性保护（撤销）。
16. 提示信息触屏可达：一切 tooltip / hint 内容必须有触屏触发路径与关闭路径（点按切换、长按、点别处关闭均可）。
17. 移动端第一天即可用：移动端/触摸手势适配从原型期就位；像素级打磨放真机测试轮——那是计划内环节，不是意外返工。
18. 双语是一等公民：默认中文 + 英文一键瞬时切换；语言间 key 对称有测试守护；英文文案不许内联进代码。

Part II · 综合偏好

与 AI 助手的协作方式

• 第一次生成 AI Agent 记忆文档（CLAUDE.md 或 AGENTS.md 其中任一）时，symlink到另一个。任何记忆优先放入该文档。
• 代码注释只解释 why（约束、陷阱、反直觉的原因），不复述代码在做什么；命名语义化、DOM 结构可读——代码会被多个 AI 工具接力编辑，可读性即互操作性。
• 交接笔记写在docs/notes/下，固定三清单：“我擅自发挥的"“我没把握的"“留给你的”——写下偏离计划与不确定之处，比写做对了什么更有价值。
• 覆盖要留痕：凡覆盖 Part II 历史偏好的，把"覆盖了什么 + 理由"记入项目的 Agent 记忆文档，让后续接力的 AI 不把刻意为之当成疏漏改回去。
• 计划文档生命周期：计划 → 实施 → 移入 docs/archived/ 留档不删；里程碑后写基于真实提交历史的复盘，教训回流本文档与记忆文档。
• Claude Design 前端迭代是计划内环节：代码侧先保证外观 token 单点集中；改版时把必须保留的 deliberate design（响应式分支、既有 token 体系、双语约束）写成显式 constraints 交给设计回合；预期有设计迭代的项目配 build:single（单文件 HTML 构建）。
• 给 AI 留调试接口：核心状态文本序列化、单关卡/单条目独立调试脚本——让 AI 能脱离 UI 快速验证假设。

技术栈与工程

• 共同基座：Vite + TS strict + Vitest；Cloudflare Pages 部署（push main 自动构建 dist/;满足中国大陆可访问性）；Node 版本用 .nvmrc 钉住；数据/内容用人类可直接编辑的纯文本（CSV/JSON/Markdown），构建期内联或转换。
• 支持基线：Chrome/Edge 111+、Firefox 128+、Safari/iOS Safari 16.4+ （支持color-mix()）。
• 形态选型判据：有没有"很多个长得一样、各自有内部状态的交互单元”（卡片×N、槽位×N、多 Tab、需长期演进）——有就上 React 技术栈（→附录 A）；一个主画布 + 少量浮动面板就用原生 DOM，需要专业能力时按需引入小而专的库（D3 子包、marked、GSAP、Howler）。
• 默认纯静态：无后端、无外部 API、数据构建期打包进产物、离线可用、零外部请求。确需后端 →附录 B。
• 默认零收集：纯静态项目不引入任何分析/错误上报，且此立场明写进 README 与隐私政策。LLM驱动的项目是例外：需要全日志记录。
• 如有平台相关服务（广告、支付、触感、平台 SDK），用 Provider 模式隔离：统一接口 + 运行时平台检测，Web 上默认 no-op。
• CI：GitHub Actions 跑 npm ci → lint → build → test，Node 读 .nvmrc。关键教训是写清系统边界——CI 只检查不部署、托管平台只部署不测试、要门禁另开 branch protection；“本地复现 CI"的一行命令进文档。
• 浏览器验收用 Playwright + 截图交付；游戏型双套测试（规则单测 + 整局回放），一条 npm test 全跑；Python 辅助脚本配 pytest。

架构与数据流

• store 按生命周期拆：会话态与持久态（用户内容、主题、语言、设置）分开；持久态 localStorage persist，显式声明不持久化字段（partialize），刻意丢弃写注释，不 silent drop。
• 存档用单一版本化快照、原子写单 key，只存不可重算的进度（静态数据从源定义重建）；别让每个变量各写各的 key——会存出内部不一致的状态。
• 组件通信分寸：父子间 props / 回调是正常手段，不必绕行；跨树的兄弟组件不许直接引用彼此实例或 DOM，共享状态经 store / 事件。
• 引擎纯逻辑、事件流驱动呈现：规则引擎不碰 DOM，产出语义事件（MOVE / CAPTURE / EFFECT…），前端订阅事件做动画音效——逻辑与表现独立演进。
• 数据驱动规则：游戏或复杂模拟系统的规则、数值、组合表尽量放 data/*.json，代码只写解释器；加新内容 = 改数据，不动引擎；内部标识与显示名称解耦。
• 核心状态要有人类可读的文本序列化（如 ASCII 棋盘）：调试、日志、测试断言、与 AI 排障都靠它。
• 同一概念的不同真相分配不同类型：服务端真值 / 客户端缓存 / 展示态各用独立类型，让编译器防混用。
• 多来源汇流到同一中间表示：手写内容与算法/模型产出翻译成同一套命令结构、走同一条执行管线——上游不可能行为分叉。

布局

• 沉浸画布型（内容/可视化/游戏）：主内容铺满视口，功能 UI 是浮动叠加（header、侧栏、底部工具条、详情卡）；内容画布支持拖曳平移、捏合/滚轮缩放、双击复位，浮动面板不拦截面板外手势；极端宽高比下不溢出、不留大片死区。
• 工具应用型：header（logo + Tab + 设置）+ 主工作区网格；信息密度是美德——桌面敢上高密度网格一屏看全，等宽数字对齐、紧凑行距。
• 桌面和移动是两套刻意设计（高密度网格↔snap 轮播、底部工具条↔bottom sheet），重构时当 deliberate design 保留，不许"顺手统一”。
• 画布/可视化形态下，次要面板可折叠、默认折叠减少初见噪音；折叠/展开态与选中高亮在重渲染后保持。
• 空状态要设计：未放内容的槽位/卡片要有引导性占位，否则初见即"半成品感”。
• 栈式 ModalManager（历史集成、返回键关最上层、滚动条跟主题）在出现第二个可能并存的模态时再引入——单确认框的应用不值得这套机器。

视觉

• 语义化 token 分层：表面 base → surface → elevated → hover → overlay；边框 border / border-subtle / border-hover；文字主/次/三级 + muted/dim/faint；品牌一个 accent + accent-muted + focus-ring。
• 多主题 = :root 共享变量（布局、z-index、时长）+ 每主题一块整体覆盖（[data-theme="x"]）；color-scheme 跟随；Tailwind 项目用 @theme 桥接；JS/Canvas 用 cssVar(name, fallback) 懒读取。加一套主题 = 加一块变量覆盖。
• accent 克制但不羞怯：全 app 一个品牌色，只用在 logo、激活 Tab、focus ring 等少数署名位置；层级靠表面/边框/文字 token 拉开。
• 三字体体系：--font-display（logo、大数字、高潮时刻，全 app 仅 3–5 处）/ --font-sans（正文）/ --font-mono（数值、代码）；每族都是 CJK + Latin 配对，字重与 metrics 匹配，完整 CJK fallback + system-ui；数值上下文一律 font-variant-numeric: tabular-nums。
• 字体严格自托管/系统栈、零外部请求；用 CDN 时必须完整系统 fallback + 断网优雅降级。文本集合稳定的应用，CJK webfont 构建期子集化（可缩体积两个数量级），子集脚本进构建管线。
• 气质基线：总体克制、偏印刷品——小圆角、轻阴影；默认浅色 + 可切深色，深色非纯黑；题材决定气质，设计回合从头定方向。
• 非 emoji 的中性 Unicode glyph（▼ ✎ ⋮⋮）允许作轻量设计词汇，但每次上新真机确认不 emoji 化；尽量"图标 + 文字"并排。

交互与动画

• 时间性动画用 rAF + 连续浮点插值，60fps 无跳变；时间参数随播放速度自适应，参数表 + 插值写成纯函数可单测；时长与缓动活在 token 里（--duration-* / --ease-*），具体曲线按题材选——回弹/弹性更合适的场景不必迁就默认曲线。
• 连续动画、可中断、逻辑一致三者对齐到同一离散边界：逐单元执行（①先改逻辑态 → ②再起 tween → ③只在单元间检查中断），实体永不停在中间态；下一步决策/网络请求在当前动画播放期间并行发起——延迟藏进动画时长。
• 复杂编排（游戏型）可用 GSAP：timeline 复用 + 对象池，不逐次创建销毁。
• 高频操作加手势捷径（双击取消、长按等），处理与单击的竞态；列表/槽位支持拖拽排序。
• 默认状态精心选择（默认语言、默认范围、合理的初始示例数据）；生僻名词旁放小 ? 标记，点按/悬停显示一句话解释。
• 音效与触感（游戏型默认做，工具型可选）：统一 SoundManager，资源清单集中、预加载降延迟，音量/静音持久化；每种音效只挂一个触发点（该交互的唯一入口），持续动作用"循环 + keep-alive、停止自动淡出"；触感做成可关设置，经 Provider 模式隔离。

品味收敛

• 从历史总结，不一定适合当前项目。违背本节内容无需留痕。
• 浅色主题反复收敛到"暖纸面"：羊皮纸底、暖墨色文字层级、低饱和大地色、暖琥珀阴影——“纸落在纸上，不是冰放在雪上”。
• 深色主题收敛过两路：冷调深海军蓝系、暖调墨黑 + 琥珀系；表面层级靠亮度 + 微量彩度递进。
• 质感三技法：双层阴影存 CSS 变量（柔和环境影 + 贴身 key 影 + 顶边 1px inset 高光，hover 加深）；透明度 SVG 噪点垫底消塑料感；极淡径向/线性渐变做方向性光源而不显"渐变 UI"。
• 分类/阵营 tint 用 color-mix() 渐变而非平铺半透明，永不淡到与底色相同；辅以卡片顶边细 accent bar。
• 动效口味：缓动默认 smootherstep / easeInOutCubic；面板展开/收起过渡约 160–320ms，题材需要弹性/回弹时直接覆盖。
• 折叠控件词汇：方向性 chevron（指向面板将移动的方向），不用 +/− 这类无方向符号。
• 自定义滚动条（含模态内部）颜色跟主题适配。
• 内容型可"标题衬线、正文无衬线"；工具型全无衬线；游戏型 display 字体可按题材用书法/装饰体（仅限 display 位置）；theme.css 留字体实验开关（<html> 加 class 切换字体组合）。
• 游戏型可做多套完整主题——前提是 token 化让"加一套主题 = 加一块变量覆盖"。

移动端与性能

• 拇指可达性：高频控制面板不压在长滚动内容底下——移动端改 bottom sheet 或吸底工具条。
• 高频手势事件回调里只记录状态，rAF 合帧应用；大位图手势期用 GPU CSS transform 平移缩放（will-change: transform），结束再重绘精确帧；手势中加临时 class 关掉阴影/模糊等昂贵效果。
• 位图分辨率按 DPR + 像素预算决定；重计算分块进行，让出主线程。
• 初始加载可做一次性重活，但放关键路径之外，先渲染骨架。
• 减少请求数是构建期的事：CSS 合并、JSON 打包、<script defer>，都在构建管线自动做；产物体积有意识控制（底图/数据/字体裁剪到需要的范围）。

国际化

• 语言初始化优先级：用户保存的选择 > 浏览器语言 > 默认值。
• 实现随栈：原生项目用字典 JSON + t(key)，React 项目用 i18next；平铺语义 key；字典按领域拆（UI 文案、内容条目名各一份文件）。
• 专有名词建显式映射表（官方译名）；查表前宽松归一化（原样/小写/去空格/连字符互换），查不到 fallback 原文。
• 内容数据双语字段用 _zh / _en 后缀，按当前语言取。
• 长文档（README/帮助/法律）每种语言独立成文，“可公开发表"质量。
• 数字本地化做深：数量级词（万/亿 vs k/M）、单位换算、去尾零、按数值大小选小数位。

数据与内容

• 上游/遗留源走构建期转换管线：脚本挂 predev / prebuild 自动执行，清洗重映射成干净 JSON schema；脚本末尾做最小结构校验（必需字段、统计丢弃项），失败打印清晰错误而非中途崩溃。
• 应用内说明文案直接渲染 README（构建期内联）——文档即文案，不维护两套说法。
• 内容/数据类项目提供原始数据下载按钮（Blob 导出、正确文件名、附许可提示）。
• 用户创造的重要数据必有出口：localStorage 是缓存不是存储——用户清一次站点数据即蒸发。凡用户投入劳动产生的持久内容（设置组合、笔记、自建关卡、草稿），提供 JSON 导出/导入；导出物带 schema 版本号，导入需注意存档版本迁移,不许读到旧档时静默失败或半解析。工具型应用此项列入发布前检查。
• 渲染即消毒：一切经 HTML 管线渲染的非硬编码文本（UGC、URL 参数、模型输出）默认视为不可信；消毒收口在渲染入口一处，不散落各组件。有 UGC 渲染的项目配 CSP header。

注意：以下 Part III-V 的内容偶尔会存在另一个单独文档里，所以如果本文在此处截断，是正常的。 若截断，且需要阅读以下部分，可在本文档同目录下搜索关键词 Part III · 阶段检查点。

Part III · 阶段检查点

首次commit前

• .gitignore 就位（含 .env、.env.*、.dev.vars、日志与中间产物）。
• token 文件（variables.css / theme.css）建好，分层就位。
• 相对路径从第一行开始。
• 移动端基线就位。
• 架构不变量的自动检查挂进 npm script。

发布前

• 项目名/工作室名/品牌名需要锁定且核验文档字段替换；要上架的项目起草隐私政策、服务条款。
• 双/多语 key 体系就位。
• 真机测试轮 + 低端设备(或限 GPU 模拟器)过一遍：桌面流畅 ≠ 手机流畅。
• emoji audit：grep diff 里的 emoji 码点。
• favicon、app icon、apple-touch-icon 齐备（用户会"添加到主屏幕”）；自定义滚动条（含模态内部）颜色跟主题 token。
• SEO / 分享元数据：每个可分享入口有 title / meta description + og:title / og:description / og:image（1200×630）；双语站配 hreflang；内容站配 sitemap。
• 生产形态演练：用平台本地模拟器跑打包产物（如 wrangler pages dev dist），别只在 dev server 验证。
• 部署脚本 = 质量关卡：lint + test + build + 产物密钥扫描全过才上传，一条命令完成。
• 文档齐备：README.md（截图、线上链接、技术要点、许可，不留脚手架原文）；LICENSE（代码 MIT，自建数据/内容 CC-BY 4.0 + 应用内致谢入口）；部署文档自洽（首次部署 + 日常更新 + 冒烟测试的 curl 命令与预期输出；多渠道各写一节；平台暗坑随踩随记）；常用命令速查；CLAUDE.md/AGENTS.md（symlinked）文档需维护。
• 版本纪律：package.json version 随里程碑 bump、构建注入、UI 可查；维护 RELEASE_NOTES。
• CI 绿灯 + 部署确认上线。

Part IV · 踩坑备忘

不值得再付一次学费的错误清单。无优先级之分。

• 手机浏览器会把 ▶ ⏸ ↻ 等码点渲染成彩色 emoji。中性 glyph 也可能中招，故每次上新真机确认。
• backdrop-filter: blur() 是低端 Android 的帧率杀手：只在模糊背后真有可见内容时用，背后纯色就直接删——桌面看不出差别。
• CSS transition 与 JS 动画会打架：JS 接管前先 transition = 'none'，结束后恢复。
• AudioContext 必须在首次用户交互时 resume，否则静音。
• 原生 title 提示只对鼠标有效，触屏用户完全看不到。
• store 按引用判断变更：集合/数组字段更新必须传新对象，原地 mutate 不触发订阅。
• 粒子/循环动画空载时要提前退出，否则零内容也每帧空转耗电。
• PWA 缓存优先策略会让部署后用户拿到过期代码——HTML/JS/CSS 必须网络优先。
• LLM API 的消息结构约束：首条须为 user、角色严格交替、相邻同角色需合并；模型对"埋在 user 文本里的自己上一轮的话"近乎无视，会不停重复自己。
• 路由、函数目录、secret 注入的暗坑只有在本地跑打包产物（如 wrangler pages dev dist）时才暴露，dev server 一切正常不代表生产正常。

Part V · 条件触发附录

附录 A · React 工具型（触发：形态选型落在 React）

• 默认技术栈：React + Zustand + Tailwind（CSS-first）+ i18next + vite-plugin-pwa（→附录 E）。
• 派生用 useMemo / selector；性能问题优先靠细粒度订阅解决，React.memo / useCallback / 按 key 缓存引擎对象作为辅助手段。
• 纯逻辑从大组件抽到 lib/ 纯函数再测；jsdom + Testing Library 只做少量结构性测试。
• 重复 3 次的 UI 结构（确认弹窗等）抽公共组件；组件内逻辑膨胀时抽 hook。

附录 B · 需要后端时（触发：社区内容、排行榜、模型网关等无法纯静态的需求）

• 优先同平台无状态函数（Cloudflare Pages Functions / Workers，按需 D1/R2），与前端同源、同一次部署（免 CORS、免独立域名）；框架选可搬迁的（如 Hono：Workers 与 Node 通用）。
• 服务端无状态，会话状态客户端持有；能不上数据库就不上。
• 秘密经平台加密 secret 注入，只活在服务端目录（I-4）。
• 无账号匿名 ID；服务端重做一遍校验（不信任客户端）；每用户配额 + 冷却限流；上线前平台侧限流（按 IP 阈值，无需改代码）进 checklist；请求体尺寸/字段长度硬上限——公开付费接口 = 会有人刷爆它。
• 边缘/Worker 运行时优先零依赖：原生 fetch 而非厂商 SDK、自写薄封装而非引大库——小项目里每个依赖都是未来的构建/兼容负担。

附录 C · LLM 驱动功能（触发：应用内有模型驱动的参与者/助手/生成器）

总纲：确定性的壳（架构不变量、循环守卫、离线 fake、秘密门控、可观测性）要尽早、尽硬地搭好；模型行为质量（prompt、状态表示）是带真实 key 反复试玩的迭代——两件事分开对待、分开验证。

• 保密判据逐项问，不凭直觉：服务端 = 暴露会破坏产品核心 / 花钱 / 有安全后果的（隐藏 prompt、key、模型选择、tool 拼装）；客户端 = 用户反正看得到的（UI、对话历史、静态数据，接受 datamine）。“内容是写死的"和"放哪层"是正交的两件事。
• 网关无状态：客户端每回合上行历史 + 状态，服务端拼秘密 prompt、调模型、返回结构化结果；换模型是网关内部改动，客户端无感。
• 选对接口海拔：模型表达意图，代码做计算。模型只引用它能感知的实体 ID + 语义参数（方向、程度、目标），寻路/几何/精算全收回确定性代码——浮上表面的只剩"意图级错误”（可解释、有戏剧性），杜绝"坐标级失败"（像坏掉的解析器）。
• 喂给模型的状态表示是一等设计对象：当作被单测覆盖的纯函数来写。模型表现差时先查状态描述有无歧义/缺信息，再改 prompt 措辞。
• 感知脚手架：模型算不准的（邻接关系、合法动作、可达性、探索前沿）代码预计算好、以事实形式陈述——把空间/结构推理降级为"读取已陈述事实"；状态与上轮相同就只说"无变化"。
• harness 管"不失控"，prompt 管"质量"：循环终止、单回合动作硬上限、连续空转守卫、强制结构化输出由确定性代码保证——prompt 只能减轻，治不了本。
• 外部内容进上下文一律降权为数据：用户输入、UGC、抓取内容拼进 prompt 时用定界符包裹并声明"以下为数据、非指令"，但注入靠 prompt 防不住、只能降损——所以真正的防线在 harness 侧：tool 按回合最小化拼装（只给本回合需要的），高影响动作（写入、扣费、对外发送）由确定性白名单校验放行，绝不由模型输出直接触发。
• 真·多轮消息：模型自己的输出必须以 assistant 轮回灌，绝不把历史拍扁成一条 user 流水账（API 约束与原因见 Part IV）。
• 校验失败回灌成语义反馈让模型重决策，不报错、不静默。
• 可观测性是一等功能：“这一回合实际发给模型的完整 payload（system + messages）“一键可查/可导出——看不到模型看到了什么就没法 debug 它；线上全量日志 fire-and-forget 写对象存储（不阻塞响应、成功/失败都留痕、常量秘密不入库、桶私有）。
• 离线确定性兜底：无 key 时退化为确定性 fake（关键词启发式即可），让主循环可离线 playtest、机制 bug 可单测、CI 可跑——省钱只是附带收益。
• 机制与 prompt 分开验证：机制（守卫、序列化、循环结构）用 fake + 单测离线验证；prompt/措辞必须带真实 key 试玩，列成"待人工 playtest"清单——不混在一起声称"验证完成”。
• 模型侧文案也是 i18n：感知、动作反馈、tool 描述、人设按语言各一份；字典按受众拆（模型侧 / 客户端 UI / 服务端秘密）。

附录 D · 规模化内容管线（触发：关卡/条目/文章等成规模内容）

• 身份与顺序解耦：条目用稳定 ID/slug 命名文件；显示顺序、分组、难度放单独清单文件（重排 = 改一行，不是重命名一批文件）；清单由构建脚本从文件扫描生成或校验，防不同步。
• 先建验证工具，再量产内容：schema 校验 + 一致性/可解性检查（游戏关卡配自动求解器）进 CI 或构建。
• AI 生成内容三分工：LLM 负责搭结构（正确格式、合法摆放），自动验证器负责把关（可解、无捷径），核心设计（有趣、优雅、教学节奏）必须人工创作——机制紧耦合的内容 LLM 做不出值得称赞的质量。
• 内容量大且需反复调整时，投资内置编辑器：应用内编辑 + localStorage 草稿，复用生产渲染管线，所见即所得。
• UGC 上传前客户端验证 + 服务端再验证，配额与冷却见附录 B。

附录 E · PWA（触发：工具型 / 离线游戏型默认启用）

• Service Worker 缓存全部静态资源，断网可完整使用；缓存列表从构建清单生成，不手写；缓存名带版本号，构建自动 bump。
• HTML/JS/CSS 一律网络优先；缓存优先只对不可变资源（版本化文件名、字体、图片）安全（原因见 Part IV）。
• manifest 写全：name / short_name / theme_color / display + 192/512 图标；start_url 用 "./"，不用具体 HTML 文件。
• 验收标准：Chrome 离线加载正常、“添加到主屏幕"体验完整。

附录 F · 数据可视化（触发：可视化形态）

• 数据编码硬规则：面积编码数值 → 半径用 sqrt 比例；重尾分布一律对数尺度，色阶定义域从最小正值起；区间型数值中心取平均/中位数、min/max 用虚线圈或 error bar 显式表达；同一指标在所有联动视图用同一色阶同一 y 轴尺度；无数据 ≠ 零（固定小尺寸 + 中性色 + 特殊描边 + 注明）；图例范围 = 真实 min→max，不是想当然的 [0, max]。
• 多视图联动：同一实体在不同视图的 hover/选中双向同步；筛选、时间窗对所有视图同时生效。