xiaxia-anchor-marking

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

• meta.json
• symbol-system.md
• workflow.md
• templates.md
• do-not-do.md

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

1. 定范围：确认本次只给哪个页面、模块、业务流或风险链路打点。
2. 扫主线：列出页面、模块、主流程、关键状态。
3. 找接缝：标出 UI 与 API、数据、事件、权限、错误、实时更新相接的位置。
4. 归层级：标清 truth / ui / api / state / event / risk / verify。
5. 补 ID：按项目规则命名；没有规则时用 {page}-{module}-{function}-{sequence}。
6. 写批注：优先用标准格式，密集设计稿可用简化格式。
7. 查缺口：专门补 ⚠️、🔐、📦，这三类最容易漏。
8. 做统计：文末汇总每类数量和总计。
9. 给验收：列出可搜索 ID、相关接口、最小回归点。

Decision Heuristics

• 如果一个 UI 元素会触发代码，就至少有 🔌 或 ⚡。
• 如果一个 UI 元素展示动态内容，就至少有 💾。
• 如果状态会变，就检查是否需要 🎨、🔄 或 📡。
• 如果操作会失败，就必须有 ⚠️。
• 如果操作涉及账号、密钥、删除、授权、管理权限，就必须有 🔐。
• 如果 API 字段和 UI 字段不一致，就必须有 📦。
• 如果同类块出现三次以上，考虑加 🧩。

Output Shape

交付一份“埋点版”文档时，推荐包含：

1. 页面/模块基本信息。
2. 带锚点的设计稿或流程说明。
3. 标准锚点清单。
4. API / 数据 / 事件 / 权限 / 错误处理对照。
5. 埋点统计。
6. 回归验证清单。

Honest Boundaries

• 如果原始文档没有接口或字段，只能写 TODO: 待确认 API/字段，不要编造。
• 如果用户只是要视觉概念稿，不要强行把所有装饰元素都打点。
• 如果涉及凭据，只记录“凭据存在/校验/保存状态”，不记录真实值。
• 如果旧项目记录与当前代码冲突，以当前代码和真实接口为准。
• 如果一个项目已经有真相导览、字段注册表、组件注册表或变更树，先接入这些文档，不另起平行索引。

Long-Range Use

这个 skill 以后指导我们走很远时，重点是“少而准”：

• 对高风险链路打锚点，不对所有文字打锚点。
• 对会跨人、跨窗口、跨代码层的地方打锚点。
• 对以后可能复盘、验收、交付、交给 subagent 的地方打锚点。
• 每次新增锚点，都要能回答：未来谁会靠它找到什么？

Quick Reference

⚡ API / 💾 数据 / 🔄 实时 / 🔌 事件 / 📡 长连接 / 🔐 权限 / ⚠️ 错误 / 📦 转换 / 🎨 样式 / 🧩 复用