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