| name | xiaxia-anchor-marking |
| description | 用于把“锚点 / 打点 / 埋点 / 标记”做法复用到任何项目的设计稿、接口梳理、前端施工图、模块边界和验收清单中。
当用户说“打锚点”“打点”“标记接代码的位置”“埋点版设计”“把设计稿变成施工图”“标出 API/数据/事件/错误处理/权限/实时更新”“给复杂链路做可搜索 ID”时触发。
|
Xiaxia Anchor Marking
不是为了把文档画花，而是为了让设计、代码、测试和回归能在同一个位置相遇。
Usage Instructions
Good at:
- 给页面设计稿、流程图、模块说明补“可施工锚点”。
- 把 UI 文案变成前端/后端/测试都能查找的接入点。
- 标出 API、数据绑定、事件监听、实时刷新、WebSocket、权限、错误处理、数据转换、动态样式、组件复用。
- 生成“埋点统计”和“回归查找入口”，方便后续施工、验收和复盘。
- 学会用icon来表示一些要写很多文本的地方，用注释的方式既可以帮助你快速找到线索也可以提高效率，前提要做好图示。
- 并非注释都只能在代码里，有的前台也可以巧妙的用icon来和后端数据组呼应。free可商用的icon：https://www.streamlinehq.com/icons/streamline-colors
Not good at:
- 替代真实产品分析、接口设计或测试执行。
- 为了数量堆标记；没有实现意义的位置不要硬打点。
- 把密钥、验证码、敏感 token 写进标记。
Read First
Core Idea
夏夏旧项目里的做法是：在设计稿正文中直接留下“可被代码接住”的锚点。这个方法现在升级为通用技能：凡是设计、代码、测试、回归容易错位的地方，都用可搜索 ID 把它们接到同一个真实位置。
锚点不是运行时真相，也不是装饰批注。锚点是施工索引、对照表和回归入口。
一个好锚点至少回答：
- 这里是什么能力？
- 由什么事件触发？
- 读写什么数据？
- 对接哪个 API / WebSocket / 本地状态？
- 失败时怎么处理？
- 后面如何按 ID 找回来？
Operating Rules
0. 先判定锚点层级
每个锚点必须先归层：
truth：真相源、字段归属、业务合同。ui：页面、组件、交互入口、动态样式。api：HTTP / WebSocket / SSE / 本地服务。state：store、props、localStorage、IndexedDB、文件系统。event：用户操作、系统回调、播放游标、拖拽提交。risk：错误处理、权限、空态、超时、回滚、禁止事项。verify：回归检查、截图、脚本、最小验收。
1. 先分层，再打点
- 先看页面或流程的主路径，不要一上来逐字标记。
- 按“页面 → 模块 → 功能 → 状态/异常”分层。
- 主路径优先：加载、提交、保存、刷新、授权、状态变更、错误恢复。
2. 用符号表达接入类型
⚡ 标 API 接入点。💾 标数据绑定或状态字段。🔄 标轮询、订阅、定时刷新、实时状态。🔌 标用户事件、系统事件、回调入口。📡 标 WebSocket / SSE / 长连接。🔐 标权限、身份、CSRF/state、敏感操作确认。⚠️ 标错误处理、重试、降级、空态、超时。📦 标 API 与 UI 之间的数据转换。🎨 标由状态驱动的动态样式。🧩 标可复用组件或可抽离模块。
3. 每个锚点必须有可回找 ID
- ID 格式：
{page}-{module}-{function}-{sequence}。
- 示例：
provider-list-get-001、cron-list-toggle-001、copilot-login-oauth-001。
- 同一个页面内 ID 不重复；迁移到代码时保留原 ID 或建立映射表。
- 如果项目已经有专用前缀，沿用项目专用前缀，例如白板 B/C 链路使用
bc-*。
4. 标正文，也标统计
- 正文中用标准格式或简化格式。
- 文档末尾给出按类型统计：API 几个、数据绑定几个、事件几个、错误处理几个、总计几个。
- 统计不是 KPI；它是施工范围和回归范围。
5. 锚点要落到验证
- API 点要能映射到端点、请求参数、响应字段。
- 数据点要能映射到 state/store/props/storage/session。
- 事件点要能映射到 handler、触发时机和副作用。
- 错误点要能映射到用户可见反馈和降级策略。
- 权限点要能映射到角色、认证状态或安全检查。
6. 不制造第二真相
- 锚点只帮助搜索、施工和回归。
- 锚点不能替代运行时字段、接口合同、工程资产、timeline、segmentation、配置真相。
- 如果锚点和代码冲突，以当前代码和正式合同为准；锚点文件需要更新。
Standard Format
⚡ 获取 Provider 列表
├─ ID: provider-list-get-001
├─ API: GET /settings/providers
├─ 数据：providers
├─ 事件：onMount
└─ 备注：页面加载时调用，失败时显示空态和重试
Compact Inline Format
[保存配置] ⚡ POST /settings/providers；💾 formData；🔌 onSubmit；⚠️ 保存失败提示；ID: provider-form-save-001
Workflow
- 定范围：确认本次只给哪个页面、模块、业务流或风险链路打点。
- 扫主线：列出页面、模块、主流程、关键状态。
- 找接缝：标出 UI 与 API、数据、事件、权限、错误、实时更新相接的位置。
- 归层级：标清 truth / ui / api / state / event / risk / verify。
- 补 ID：按项目规则命名；没有规则时用
{page}-{module}-{function}-{sequence}。
- 写批注：优先用标准格式，密集设计稿可用简化格式。
- 查缺口：专门补
⚠️、🔐、📦，这三类最容易漏。
- 做统计：文末汇总每类数量和总计。
- 给验收：列出可搜索 ID、相关接口、最小回归点。
Decision Heuristics
- 如果一个 UI 元素会触发代码，就至少有
🔌 或 ⚡。
- 如果一个 UI 元素展示动态内容，就至少有
💾。
- 如果状态会变，就检查是否需要
🎨、🔄 或 📡。
- 如果操作会失败，就必须有
⚠️。
- 如果操作涉及账号、密钥、删除、授权、管理权限，就必须有
🔐。
- 如果 API 字段和 UI 字段不一致，就必须有
📦。
- 如果同类块出现三次以上，考虑加
🧩。
Output Shape
交付一份“埋点版”文档时，推荐包含：
- 页面/模块基本信息。
- 带锚点的设计稿或流程说明。
- 标准锚点清单。
- API / 数据 / 事件 / 权限 / 错误处理对照。
- 埋点统计。
- 回归验证清单。
Honest Boundaries
- 如果原始文档没有接口或字段，只能写
TODO: 待确认 API/字段，不要编造。
- 如果用户只是要视觉概念稿，不要强行把所有装饰元素都打点。
- 如果涉及凭据，只记录“凭据存在/校验/保存状态”，不记录真实值。
- 如果旧项目记录与当前代码冲突，以当前代码和真实接口为准。
- 如果一个项目已经有真相导览、字段注册表、组件注册表或变更树，先接入这些文档，不另起平行索引。
Long-Range Use
这个 skill 以后指导我们走很远时，重点是“少而准”：
- 对高风险链路打锚点，不对所有文字打锚点。
- 对会跨人、跨窗口、跨代码层的地方打锚点。
- 对以后可能复盘、验收、交付、交给 subagent 的地方打锚点。
- 每次新增锚点，都要能回答：未来谁会靠它找到什么？
Quick Reference
⚡ API / 💾 数据 / 🔄 实时 / 🔌 事件 / 📡 长连接 / 🔐 权限 / ⚠️ 错误 / 📦 转换 / 🎨 样式 / 🧩 复用
