这是《产品经理的 Claude Code 技能包实战》系列的第 4 篇。 上一篇讲了怎么用 mobile-prototype 做出「能演示」的原型。但原型交到开发手里，还有一道坎——开发会不停地问「这个按钮点了跳哪」「这个字段从哪来」。这一篇讲怎么把交互说明直接「长」在原型上。
一、痛点：原型和交互说明，是两张皮
PM 交付原型给开发，通常是这样：
- 原型是一堆 HTML，交互说明写在 PRD 或单独的文档里
- 开发看原型时，得一边翻文档一边对照「这是哪个字段」
- 对不上的地方，就在群里 @ 你：「这个弹窗从哪进来的？」「这个列表点进去是哪页？」
你把交互写进 PRD 也没用——说明和界面是分离的，开发看界面时身边没有说明。于是同样的问题被不同的人反复问，你一遍遍解释。
理想的形态是：标注直接显示在原型上，开发把鼠标放上去、或点开侧边面板，就能看到每个元素是干嘛的、点了会怎样。这就是 annotation-generator 干的事。
二、这个技能包长什么样
触发方式
说「生成标注」「给这个原型加标注」「做标注」「annotation」「data-anno」就激活。
核心机制：三层作用域 + data-anno 锚点
它不是给整个页面贴一层说明，而是先识别原型的结构，再精准打标注。它会区分三层作用域：
- page —— 默认页
- screen-<id> —— 每个带 id 的 .screen（移动端切屏页）
- <modal-id> —— 每个带 id 的 .modal-overlay（弹窗）
然后给关键元素（头部、卡片、主按钮、输入框、选项卡、列表、弹窗）打上语义化的 data-anno 锚点，同页不重复、已有的复用。
产出：一份 JSON + 一个右侧标注面板
对每个锚点生成一条标注，写进 {页面名}.annotations.json：
{
"id": "anno-home-001",
"target": { "selector": "[data-anno='summary-points']" },
"scope": "screen-home",
"number": 1,
"name": "点数汇总卡片",
"trigger": "load",
"description": "…"
}
trigger 按元素类型自动取 load / click / input / hover / scroll；同一 scope 内 number 从 1 递增。最后在 </body> 前注入一个 annotation-layer.js，页面右侧就出现一个标注面板——开发打开原型，点任何标注就能定位到对应元素、看到说明。
下面就是一张「左预览右介绍」的原型页：左侧是手机里的真实界面，右侧是按 01–05 编号的说明（使用角色 / 本页定位 / 怎么用 / 示例 / 场景呼应）。标注面板就是在这样的页面上再叠加一层「点哪讲哪」的能力。
还有一个贴心的设计：URL 加 ?edit-anno=1 进入编辑模式，可以增删改标注并导出 JSON。标注内容可以边看边补，不用改代码。
三、实战流程
一句话，一份「开口说话」的原型就出来了。
四、踩坑与设计取舍
1. 为什么用 data-anno 锚点，而不是直接用元素选择器？ 因为 AI 生成的原型结构会变——今天这个 div 套那个，明天改了 class 名，脆弱的选择器（如 .main > div:nth-child(3)）就全失效了。data-anno 是专门打的稳定锚点，原型怎么改样式，标注都不会丢。
2. 为什么要分三层作用域？ 移动端原型经常是「一个 HTML 里多个切屏 + 多个弹窗」。如果不分作用域，标注会全部堆在一起，开发分不清哪条属于哪一屏。按 page/screen/modal 分组后，标注面板只显示当前屏的说明，干净很多。
3. 标注和原型分离存（JSON），而不是写死在 HTML 里。 这样标注可以独立维护、独立导出，也能被 ?edit-anno=1 的编辑模式改。标注是「关于原型的数据」，不该和原型本身耦合。
五、和上一篇的关系
annotation-generator 和 mobile-prototype 是一对组合拳：
- mobile-prototype 解决「给老板讲」——左预览右介绍，叙事级讲解
- annotation-generator 解决「给开发看」——元素级标注，精确的交互说明
一个管「为什么这么做」，一个管「这个具体怎么用」。两个加起来，原型从「能看」变成「既能演示又能交付」。
每套原型还带一个 plan.html 方案总览页——背景痛点、业务流程、方案核心一页讲清，开发/老板先看总览再钻进单页：
下一篇（五）：原型和标注都做好了，但它们还在你本地——《原型一键部署上线》。聊聊怎么把 prototypes 目录自动扫描、分类、增量部署到云服务器，发个链接别人就能看。
系列目录
- （一）用技能包写 PRD：为什么小而精胜过大而全 —— prd-writer
- （二）把 PRD 一键变成禅道任务 —— pm-zentao-task
- （三）移动端原型：左预览右介绍的演示套装 —— mobile-prototype
- （四）给原型自动加标注，开发不再问交互 —— annotation-generator（本篇）
- （五）原型一键部署上线 —— deploy-prototypes
- （六）UI 设计：67 风格 161 配色实测 —— ui-ux-pro-max
- （七）搭设计系统：三层 Token 实战 —— design-system
- （八）幻灯片与 Banner —— slides / banner-design
- （九）给 AI 装上眼睛和手 —— agent-reach / kimi-webbridge
- （十）把真人思维做成 AI 顾问 —— zhangxuefeng-skill
- （十一）让 AI 自己写测试、自己调试 —— superpowers
- （十二·终篇）我沉淀技能包的方法论：skill 是资产不是代码
