标注指引（Annotation Guide）

since v0.10.13

为项目编写一段 Markdown 形式的「指引」，新标注员第一次进入工作台时会自动在左上角浮层弹出，显著降低标注一致性偏差与退回率。参考 CVAT Project.annotation_guide 设计。

何时用

类别边界容易混淆（例如「卡车 vs 厢式货车」）。
同一图像里多种实例需要不同标注策略。
项目对 mask 边缘 / bbox 紧贴度 / 类别替换有特定规则。
易混淆反例需要图示说明。

在哪里写

进入 /projects/<id>/settings?section=annotation-guide（项目设置页 → 「标注指引」）。
顶部 编辑 / 预览 tab 切换 Markdown 源码与最终渲染效果。
支持 GFM（表格、勾选框、删除线）和图片嵌入。
点保存写入项目；之后所有标注员进入工作台第一次会自动展开 📖 浮层。

图片资源

直接将图片拖入编辑器或粘贴到光标位置：

自动上传到项目专属 storage 空间（projects/{id}/guide/...）。
编辑器自动插入 ![文件名](guide-asset:KEY) 占位。
渲染时平台签发 1 小时有效的短期 URL，自动替换为可访问链接。

限制：

单文件 ≤ 5 MB。
仅接受 image/png · image/jpeg · image/webp · image/gif · image/svg+xml。
删除项目时图片会一并清理；删除单张图片时旧引用会失效，预览显示「[加载图片中…]」。

工作台浮层行为

默认折叠，停留在工作台左上角。
首次进入 + 项目有指引 → 自动展开一次，并写入 localStorage wb:guide-seen:{projectId}。
标注员手动折叠后写 localStorage wb:guide-collapsed:{projectId}=1，后续保持折叠。
项目未配置指引 → 浮层完全不渲染，零界面干扰。

从其它项目复制时的指引行为

/dashboard?new=1&from=<id> 复制项目配置时，wizard 顶部 banner 提供 checkbox 「同时复制标注指引（图片资源与源项目共享存储）」：

默认勾选。取消勾选则新项目从空指引开始。
勾选时 annotation_guide Markdown 文本会被 deep copy 进新项目；guide_assets 数组也会复制，但底层存储对象（key）与源项目共享 —— 源项目删除该资源时新项目同样失效。如需独立资源，先在新项目设置页里重新拖入图片覆盖（旧引用会变成"加载中…"占位）。

编写建议

顶部放 1 段 ≤ 3 行的核心宗旨（"我们到底想标什么"）。
用三级标题分章节：类别定义 / 易混淆边界 / 典型反例 / 常见问题。
易混淆类别用截图 + 红色框示意，附简短 caption。
不要把工程细节（bbox 紧贴度、是否包含遮挡）藏在第 5 段；放最上面。
写完点预览自检一遍渲染效果。

已知限制

当前 Markdown 编辑器（CodeMirror 6）不带 spell-check，跨语言混排请人工检查。
浮层默认 320px 宽，超出会触发滚动；图片宽度建议 ≤ 600px 以避免横向滚动。
v0.10.13 首版不做「指引内嵌视频」；如需视频指引请上传到外部 CDN，用 Markdown 链接附在指引正文。
历史变更不可视化（不像 task 注释那样有时间线）；项目设置的 PATCH 走 audit log。

与「项目模板」的关系

v0.10.13 仅落 Annotation Guide。独立 ProjectTemplate 表 + 模板库 UI（跨项目复用 / 公共模板）在 v0.10.14 单独 epic 推进，详见 CHANGELOG。