# Xiaxia Anchor Marking

> 用于把“锚点 / 打点 / 埋点 / 标记”做法复用到任何项目的设计稿、接口梳理、前端施工图、模块边界和验收清单中。 当用户说“打锚点”“打点”“标记接代码的位置”“埋点版设计”“把设计稿变成施工图”“标出 API/数据/事件/错误处理/权限/实时更新”“给复杂链路做可搜索 ID”时触发。

- Skill: `4xiaxia/xiaxia-anchor-marking` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add 4xiaxia/xiaxia-anchor-marking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/4xiaxia/xiaxia-anchor-marking/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: 4xiaxia (https://skillmd.com/u/4xiaxia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/4xiaxia/xiaxia-anchor-marking

---


# 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](meta.json)
- [symbol-system.md](symbol-system.md)
- [workflow.md](workflow.md)
- [templates.md](templates.md)
- [do-not-do.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

```markdown
⚡ 获取 Provider 列表
├─ ID: provider-list-get-001
├─ API: GET /settings/providers
├─ 数据：providers
├─ 事件：onMount
└─ 备注：页面加载时调用，失败时显示空态和重试
```

## Compact Inline Format

```markdown
[保存配置] ⚡ 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` / `💾 数据` / `🔄 实时` / `🔌 事件` / `📡 长连接` / `🔐 权限` / `⚠️ 错误` / `📦 转换` / `🎨 样式` / `🧩 复用`