---
name: annotation-generator
description: |
  为任意 HTML 原型自动生成标注（annotation）。当用户说「生成标注」「给这个原型加标注」「做标注」「annotation」「data-anno」或任何涉及原型标注、交互说明、注释面板的请求时，必须主动触发本 Skill。
  本 Skill 负责识别原型中的页面/翻页屏/弹窗三层作用域，给关键元素打上 data-anno 锚点，生成同名的 `{页面}.annotations.json` 文件，并自动注入 annotation-layer.js。
compatibility: |
  需要 Claude Code 的文件工具（Read / Edit / Write / Bash）以及标准 Python/Node 环境用于语法校验。
---

# Annotation Generator — 原型标注自动生成

## 目标

让任意单文件 HTML 原型快速拥有右侧标注面板：
- 三层作用域：page（默认页）、screen（`.screen.active` 切屏页）、modal（`.modal-overlay` 弹窗）
- 自动编号、自动注入 `annotation-layer.js`
- URL 加 `?edit-anno=1` 可进入编辑/导出模式

## 触发条件

只要用户提到以下任一意图，立即触发：
- 「生成标注」「给这个页面加标注」「做标注」
- 「annotation」「annotate」「data-anno」
- 「给原型写交互说明」「右侧标注面板」「标注文档」

## 执行流程

1. **确定目标 HTML**
   - 优先使用用户指定的文件，其次当前 IDE 打开的 `.html`，再次 `prototypes/` 下最近修改的 `.html`。

2. **识别作用域**
   - `page`：默认页
   - `screen-<id>`：每个带 `id` 的 `.screen`
   - `<modal-id>`：每个带 `id` 的 `.modal-overlay`

3. **打 data-anno 锚点**
   - 为关键元素（头部、信息卡片、主按钮、输入框、选项卡、列表、弹窗整体等）添加语义化 `data-anno` slug。
   - 同一页面内不重复；已有 `data-anno` 则复用。

4. **生成 JSON**
   - 创建 `{页面名}.annotations.json`，为每个锚点生成一条标注：
     ```json
     {
       "id": "anno-home-001",
       "target": { "selector": "[data-anno='summary-points']" },
       "scope": "screen-home",
       "number": 1,
       "name": "点数汇总卡片",
       "trigger": "load",
       "description": "..."
     }
     ```
   - `scope` 对应第 2 步识别的作用域；同 scope 内 `number` 从 1 递增；`trigger` 按元素类型取 `load / click / input / hover / scroll`。

5. **注入脚本**
   - 在 `</body>` 前加入 `<script src="./shared/annotation-layer.js?v=3"></script>`；已有引用则刷新 `v=` 缓存版本号。

6. **校验并交付**
   - 检查 HTML 可解析、内联 JS 语法、JSON 合法、`annotation-layer.js` 语法。
   - 向用户汇报文件路径、标注数量与分布、校验结果、线上地址（如已部署）。

## 编辑模式

URL 后加 `?edit-anno=1` 可添加/删除/修改标注并导出 JSON。

## 示例

见 `examples/m-points-query-v1.annotations.json`。