Design review html

设计评审页 — 给拍板的人写 review HTML

这份技能沉淀自一位制作人兼策划连续多轮驳回后定下的硬要求。写给用户过目的方案不符合这里任何一条，就是要返工的。

0. 什么时候用

用：策划案、玩法方案、技术方案的策划视角稿、审计报告、内容提案、词表提案、任何等着用户逐条拍板的文档。 不用：写给自己的笔记、agent 之间传的中间结果、纯实现细节的工程计划。

产物默认是 HTML 页面（本技能全套）。如果用户明确要 Markdown，文风与条目结构规则照用，就地解释退化为括注或紧跟一行缩进的解释句——同样不许把解释推到文末。

1. 这个页面的本质：一页就是一次拍板会

页面不是报告，是决策材料。它的完整生命周期是一个闭环，写第一稿时就要为整个闭环设计：

1. 写稿（本技能其余部分全是写稿要求）；
2. 交付前先发一个中立 agent 做对抗审查（见 §9）；
3. 用户逐条圈 采纳/要改/否决，在批注框里写字，点「复制批注 JSON」发回对话；
4. 你把批注逐条写进决策日志（docs/qa/ 下对应文档）：引用用户原文，标明这条推翻了什么、作废了哪个在飞的提案；读不懂的批注单独问，不许猜；
5. 同步权威文档（如项目的玩法定案文档），再回来修订页面本身——被推翻的内容用 <s> 划掉保留，不删除（见 §7）。

批注的粒度跟着「用户能对它单独说采纳或否决」走：一个章节一个批注位，一个提案卡一个批注位，整页一个批注框是错的。模板的导出脚本按批注位（.note-box）遍历，一个章节里放几个都行——唯一要求是每个批注位 .verdicts 上的 data-id 全页唯一且发布后不再改，它就是批注 JSON 里的 id，回收后靠它一一对上。

2. 视角与文风

2.1 策划视角，不是程序员视角

用户要的是能拿来做玩法决策的材料，不是实现报告。每一条从「玩家会遇到什么」写起，不从「哪个函数没接线」写起。（下表反例来自真实项目，替换成你项目里的对应物。）

不要写	要写
组合器用 argmax 取最高分	同一段路上每一场普通战都是同一批敌人
城区倾向在战斗奖励里是空操作	你打完一场，掉的东西跟你在哪个区没关系
loot_screen 的重复计权是死代码	关键词掉落其实没有稀有度，每个词出现的概率都相等
%DrawRow 节点缺失	进化屏上买不到「每回合多抽一张」，那一整条成长线玩家摸不到

实现细节不是不能写，是不能当主语。放在条目末尾的「改哪儿」或「代价」里，一到两行。

2.2 词汇纪律：三档

这是被用户逐词纠正出来的档位，按优先级取词：

1. 现成的名字 —— 最优先，分两类，正当性来源不同：
   • 行业标准词，包括英文原词：游戏行业和工程界的通用叫法直接用——Hash、Overkill、首版、再版、保底、一次性消耗、构筑、词条、掉率、配平。**重要校准：反黑话 ≠ 文学化。**给技术向策划写稿，英文工程词远好过中文比喻——用户把「指纹」改回 Hash、「溢出伤害」改回 Overkill、「复刻」改回卡牌行业的 Reprint。
   • 这个项目代码或文档里既有、用户已经在用的名字（如某项目的 Definition 对应代码里的 definitionId）：沿用，不另造中文译名。注意这类只在该项目内成立，不能当成通用行业词带去别的项目。
2. 直白组合词 —— 找不到现成名字时，用几个普通词直接组合，读者第一眼就能猜对意思。实例（来自某项目）：换算表、引用图、材料兑现清单、按行归拢。
3. 自造比喻 —— 禁。被用户批「名字很奇怪 / 很愚蠢」的整批反例：记忆格、证书、考卷、因果图、追踪记录、黄金痕迹、行袋、制作位、推平、安检通道。项目里少量已被读者接受的既有比喻可以保留（那个项目里是门禁、血统、积木——项目专有清单，不通用），但新造一律先找现成词。

2.3 禁程序员黑话

不许出现只有写代码的人才懂的词和比喻。用户点名骂过「探索那一条车道」（原话：「啥是车道啊，谁开车了？」）。

车道/lane → 路线；argmax → 总是选同一个；回退/fallback → 退回到内置的那套；空操作/no-op → 写了但什么也没发生；接线/wire up → 接上、能用；消费者/consumer → 谁在读它；落点/hook → 出现的地方；复用 → 沿用同一套；对齐 → 改成一样、放在一起看。

判据：这句话玩家能不能听懂。听不懂就换。

2.4 别的行业的比喻也是黑话

金融、商业、管理那套比喻同样禁止——它们不是这个游戏里发生的事。用户驳回过「这笔账怎么分期付」（想说的其实是「这些内容要不要一次写齐」）。同类：真实的账 → 真实的代价；记账方式 → 由什么来解锁；这件事一直欠着 → 这件事该做一直没做。

判据：这个比喻描述的事情，在这个游戏里真的发生了吗。没发生就直说。

2.5 自造缩写禁止

自己把一句话压成一个词的产物不是术语。用户亲手把「等概率」改成「相等的概率」。同类：池宽 → 能用的词有多少个；恒为空 → 永远是空的；全量重建 → 每次都从头重新生成一整份。

判据：这个词在别的游戏的设计文档里出现过吗。出现过就是术语，可以用；只有你这里有，就展开写。省下的几个字不值钱，读者停顿一次的代价比省下的字多得多。

2.6 铁则

• 禁用中点分隔符「·」——它不是正式标点，要分隔就用正式标点或层级与留白。
• 说「玩法决策」，不说「产品决策」——读稿的人做的是玩法，不是产品经理的事。
• 不写「本节将介绍……」式的导览话术——目录和标题已经在干这件事。但页面开头必须有一段「阅读方式」：讲清哪些词能点、点开还能继续点、角标三色各是什么、批注写在哪、怎么一键带走。没有它，页面上所有交互对第一次打开的用户都不存在。模板里有这段的占位（.howto）。

3. 条目的固定结构

孤零零抛一个结论不行。每个决策条目按这个顺序写，缺一不可：

1. 现在是什么样 —— 玩家实际会遇到的情形，具体到一场战斗、一次操作、一个界面。
2. 为什么这是问题 —— 它伤害了哪种体验。不要只说「与设计不符」。
3. 改成什么 —— 具体规则。能写数字就写数字。
4. 玩家会感觉到什么变化 —— 改完之后那一刻的体验差别。改完玩家感觉不到的，说清楚为什么还值得改。
5. 代价 —— 内容量、平衡影响、要重测什么、会作废什么。用页面里的 .cost 段式（虚线上边框）收尾；没有代价的提案要明说「这条没有代价」。

同类条目归组；组内按「玩家受影响的程度」排，不按实现难度排。

4. 不要过度设计

• 需求是一句话，方案是一张七行权重表 → 砍。
• 为一个规则编了一段情绪理由 → 那段理由通常是自己想加东西的借口。
• 提案里出现「顺便也可以……」 → 删掉。
• 能用「固定值 + 小随机」解决的，不要引入一套玩家得单独学的新规则。

给最小的、能一句话说清的规则。

5. 中央词典（本技能的核心机制）

内联解释参照 https://ncase.me/nutshell/：名词就地点开展开，不跳走、不做脚注。但解释文本不许散落在各处——全部集中进一个中央 JS 对象（模板里叫 NUTS，页面上对用户提到它时叫「中央词典」）：

var NUTS = {
  '保底': '连续多次没有掉出稀有奖励后，系统逐步抬高概率、命中即重置的机制。起点概率来自[[掉率]]的基础值。',
  '掉率': '一件奖励在一次结算里出现的概率。'
};

规则：

• 单一来源。一个术语一条解释，改解释只改词典一处；正文里所有出现处、术语表全部跟着变。
• 正文里挂解释的写法：<button class="nut" data-term="保底" aria-expanded="false">保底</button>。首次出现处必挂；同一段里重复出现不必每次都挂。
• 解释回答「这个词在这个游戏里指什么」，末尾可注明拍板状态（已拍板 / 提议中）。两三句是常态；由多道子步骤组成的复合词可以到五句，超过五句说明该拆成两个词各自注册。
• 递归：解释文本里的 [[另一个术语]] 在展开时自动变成下一层可点的词，点开继续就地展开；[[术语|显示文本]] 支持别名。写了 [[拼错的词]] 会静默降级成纯文本，模板已在控制台加了警告——交付前开一次控制台查有没有 [nut] 未注册术语。
• 环路保护：展开时沿祖先链收集已展开过的术语，再出现的渲染成不可点的灰字（nut-dead 类），防止 A→B→A 无限套娃。
• 术语表自动生成：页面末尾放一个空的 <dl id="glossary-list">，脚本从词典自动填充（术语内的引用同样可点）。永远不要手写术语表——手写的会跟正文漂移。

完整可运行实现见本技能目录下的 template.html，无外部依赖。

6. 批注系统

• 每个可拍板单元放一个批注位（.note-box）：三个态度按钮 采纳 / 要改 / 否决（data-v 取 accept / revise / reject，可再点取消），加一个自由文本 textarea。
• 页面顶部 sticky 一条 topbar，右侧「复制批注 JSON」按钮，一键把全部批注写进剪贴板。
• 导出格式：

{
  "notes": [
    { "id": "budget", "title": "强度预算怎么落成系统", "verdict": "revise", "note": "曲线只做知识，不做门" }
  ]
}

• id 来自批注位 .verdicts 的 data-id（见 §1 的唯一性要求）；title 由脚本自动取该批注位之前最近的标题（h2/h3/h4，剥掉编号与角标）——不要另外维护一份标题映射，最初的参照实现用了硬编码映射，标题一改就漂移，模板刻意改掉了这一点。
• 没圈态度的条目 verdict 为空串，照样导出——「没表态」也是信息。
• 模板已做两层兜底，改稿时不要删：批注与态度即时存 localStorage（按页面路径隔离），刷新、误关标签页不丢；剪贴板 API 被拦时先走隐藏文本框复制，再失败就弹出可见文本框让用户手动复制，绝不无声失败。

7. 修订协议：划掉，不删除

页面会跟着多轮拍板演进，历史必须可见：

• 被推翻的定案：原文用 <s> 包住保留，紧跟加粗的新裁决与日期。HTML 里 ~~文字~~ 不起作用，必须用 <s> 标签。
• 章节标题挂状态角标（chip）：已拍板（绿）/ 提议（青）/ 开放（黄）。拍板后更新角标，不重写章节。
• 修订永远改同一个文件：文件名不换（版次写在 .doc-date 里），发布为 Artifact 时用同一 URL 重发、<title> 与 favicon 保持不变——否则用户手上的旧链接指向旧稿，历史在文件层面就断了。
• 页面接近末尾放一张决策索引表（模板有骨架）：每行一条决策，三列——决策内容、落在本页哪一节、依据出处（决策日志路径与条目号、权威文档章节、或「口头拍板，请复核」）。口头拍板而未落文档的必须如实标注。
• 开放问题单独成节，每条有自己的批注位——「还没想清楚」也是要用户圈的。
• 页脚写清本稿依据（调查、对标、决策日志）与下一步（批注怎么发回、发回后会发生什么）。

8. 起稿、路径与版面

起稿：直接复制本技能目录的 template.html，在它上面填内容，不要从零写。

产物路径与命名：放项目的 docs/review/ 下，文件名 YYYY-MM-DD-<主题>-review.html；页首 .doc-date 写日期与稿次（v1 / v2，重写一稿才递增）。写完把本地路径给用户，或发布为 Artifact 给链接——发布前确认用户要哪种。

模板已实现、改稿时不要删的东西：双主题 token（prefers-color-scheme 承接系统偏好，data-theme 两个方向的覆盖是给 Artifact 查看器的主题开关用的——查看器会把它写在根元素上，本地打开时只有系统偏好生效，所以两组都不能省，color-scheme 也要跟着切）；中文排版（正文 PingFang 一系、标题衬线、行高 1.85、栏宽 50rem）；section.block 的 scroll-margin-top（不然目录跳转会被 sticky 顶栏盖住标题）；按钮与可点词的 :focus-visible、aria-expanded、aria-pressed；动画包在 prefers-reduced-motion 里；单文件零外部请求（无 CDN、无 webfont URL，可直接本地打开或发布为 Artifact）。

写稿时要主动用的标记：

• 流程和规则骨架用 pre.flow / pre.ir 画树状文本图，不用图片。
• 表格一律包 .table-scroll（页面本体永不横向滚动）；对齐的数字列加 td.num（tabular-nums）。
• 章节编号只在会被「§N」引用（决策索引表、批注回复）时用，写成 <span class="secnum">N</span>（导出标题时会被剥掉）；纯装饰性的 01 / 02 / 03 禁。

9. 交付前对抗审查

写完不许直接给用户看。先发一个中立的 review agent——派发时显式指定模型，用比当前会话弱一档的模型（不继承当前会话的模型，也不用最强档）——至少三个视角：

1. 黑话审查 —— 逐词找 §2 全部违禁类型，列出来。
2. 事实审查 —— 每条断言回到代码或来源里核对。高发失败是「注释比代码乐观」和「写了骨架但没人调用」，要专门找这两种。
3. 过度设计审查 —— 逐条问「用户的需求真有这么复杂吗」。

审查改完才呈现。用户可以对单篇明示豁免这一步；豁免只对那一篇有效。