# Handle Comments > Use when handling Commentary comments in prototypes, Markdown, HTML, or prototype specification documents. - Skill: `lintendo/handle-comments` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add lintendo/handle-comments` - Raw SKILL.md: https://api.skillmd.com/api/skills/lintendo/handle-comments/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: lintendo (https://skillmd.com/u/lintendo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lintendo/handle-comments --- # Commentary 批注处理 本技能只处理 Commentary 批注，不处理 AnnotationViewer 的说明标注、`annotation-source.json` 或 `@axhub/annotation` 数据。 ## 存储范围 - 批注记录位于 `comments[]`，图片记录位于 `images[]`。 - 原型批注使用 `.axhub/make/comments/.json`，其中 `normalizedTargetPath` 为 `prototypes/`。 - Markdown、HTML、原型规格文档批注使用 `.axhub/make/comments/.json`。 - 所有类型的图片统一使用对应的 `.axhub/make/comment-assets//`，并由 `images[].assetPath` 指向具体文件。 - 优先使用已有目标上下文；上下文不足时可检查统一存储，并根据 `kind`、`resource.targetPath` 或 `documentPath` 定位本地目标，不从 URL 或页面标题猜测，也不读取旧 `localStorage` 批注。 - 不提供旧技能别名或旧批注格式兼容；文档改名后按新文档处理，不迁移旧批注。 ## 历史原型批注迁移 某些历史版本的原型批注可能仍在 `src/prototypes//.spec/prototype-comments.json`，图片可能仍在 `.spec/prototype-comment-assets/`。发现后不自动迁移或静默合并，先征得用户确认。 确认后，将原有 `comments[]` 和 `images[]` 复制到对应的新 hash 存储，复制仍被引用的图片并更新 `images[].assetPath`。验证新存储后只按新存储流程工作；默认保留历史源文件，目标已有数据时不覆盖或自行合并。 ## 处理流程 1. 读取相关批注文件，忽略 `deletedAt > 0` 的记录；用 `(pageScope, elementKey)` 关联批注和图片，用 `resource.targetPath` 或 `documentPath` 确定目标，并结合 `locator` 和批注内容定位修改区域。 2. 跳过 `state` 为 `editing` 或 `completed` 的批注，修改其余批注对应的目标代码或文档；图片只通过 `images[].assetPath` 读取。 3. 开始处理时将批注 `state` 改为 `editing`，验证成功后改为 `completed`，失败改为 `error`。 4. 正常处理不删除或改名批注和图片；`completed` 不表示删除。 处理时不调用 Axhub/Make 业务 CLI 或 HTTP API，不做 live sync。 ## 明确删除 只有用户明确要求删除当前单条批注时，才给匹配 `(pageScope, elementKey)` 的批注和关联图片写入同一个 `deletedAt`。 这是虚拟删除：不移除 JSON 记录或图片文件，不处理其它记录；前端读取标记后负责真实清理。无法唯一确认目标时不写删除标记。 ## 交付 用业务语言说明已完成的界面或文档修改、剩余异常批注和验证结果，不输出底层存储或内部节点日志。