使用 agentseg 标注一个序列
您先分割目标物体一次，SAM 3 便会在每一帧上跟踪它，后端会标记出看起来有问题的帧（“issues”）。您的工作是提供一个好的初始掩码，然后检查 issues 并只修复真正错误的部分。大多数序列只需要 0–3 次修复。
从仓库根目录运行 CLI，如 .venv/bin/agentseg …（或 uv run agentseg …）。
每条命令输出一个 JSON 对象；读取其中的 ok、error 和 next。图像会以 PNG 文件写入并返回为 "image": "<path>"。请用您的文件读取工具打开该路径查看。 没有查看图像就无法判断掩码质量。
约定：像素坐标、框 x0,y0,x1,y1、点 x,y、帧是项目图像顺序中的 0 基索引。帧范围写为 120-139,150。
0. 服务
agentseg status # 后端 + sam_server + 已打开的项目
agentseg up # 启动已关闭的服务（sam_server 大约需要 1–2 分钟）
如果 up 失败，读取它打印的日志路径。不要杀死其他 GPU 进程。
在运行期间永远不要执行 agentseg down：后端托管着您，停止它会结束您的运行。GPU 可能被共享，因此命令可能因 sam_server 错误（CUDA 内存不足）而失败。等待 30–60 秒后重试；agentseg up 只会启动已关闭的服务。如果持续失败，请停止并报告。
1. 打开项目并找到目标物体
agentseg project open <image_folder> # 或一个已有的项目目录（包含 agentseg.db）
agentseg sheet # 整个序列中约 24 张缩略图预览
project open 返回 frames 和 image_size。
查看缩略图。选择一个目标物体完全可见、大且清晰的提示帧，不一定是第 0 帧。跟踪从关键帧向前和向后运行。
2. 在第一次掩码前解析标签
在调用 segment 或创建跟踪之前选择标签名称。使用用户请求中的目标名称；当没有明确给出时，从图像中推断一个简短、具体的名称并在运行中说明该选择。永远不要将标签留为 unknown、空字符串或占位符。如果存在多个合理的目标且选择会改变标注目标，请先询问用户再运行 SAM。解析后的名称会传递到第一次 track create 调用及后续的每次报告中。
例如，对于“给鱼雷打标签”，解析为 torpedo；对于“标记此文件夹中的木板”，解析为 board（或者当明确是某个物体时用 torpedo_board）。在整个序列中保持稳定。
在第一次掩码之前将其注册到项目的标签列表中（这个列表与用户在 Web 界面中选择的列表相同；如果已有标签已命名该物体，则重用它）：
agentseg labels # 已有的标签
agentseg labels --add <resolved_label>
3. 第一次掩码
agentseg view <f> --grid # 带 50px 坐标网格，用于读取坐标
agentseg segment <f> --box x0,y0,x1,y1 # 仅预览，不保存任何内容
框：紧贴，围绕整个物体。 在网格上找到物体的最左、最右、最上和最下像素（保险杠到保险杠、车轮、车顶），然后加上一个小边距（约为物体大小的 5–10%）。不要过多：一个留有大量余地的框会让 SAM 把物体的阴影或周围地面纳入，然后跟踪器会将其复制到每一帧。
- 读取
check：segment还会尝试一个增大 20% 的框。如果使用更大的框掩码会增长，则说明您的框切到了物体。如果更大框的缩放图显示了整个物体，则使用它的padded_preview_id；否则重新绘制包含整个物体的框。切勿忽略并重试相同的框。 segment返回image（整帧，黄色填充）和zoom（特写，仅轮廓，青色 = 使用的框）。打开缩放图并沿着轮廓走一圈：物体的每个末端都必须在轮廓内部。- 太多了？ 轮廓必须紧贴物体自身的边缘。如果它延伸到物体下方或旁边的阴影、道路或相邻物体中，则在相应部分使用
--neg x,y重新运行（并框得更紧）。 - 仍然是部分掩码？ 不要重试相同的框：它会给出相同的掩码。在缺失的部分使用
--pos x,y（SAM 常常在颜色或光照边界处停止：向阳的半边、背阴的半边、双色车辆）。 - 范围： 只包含用户所指的物体：“木板”不带底座，“汽车”不带拖车。
- 最多尝试 4 次。一个仅覆盖物体 2/3 的关键帧比没有还要糟糕：跟踪器会将其复制到每一帧，健康检查也看不到它。如果您在这帧上无法得到整个物体，请选择另一帧。然后：
agentseg track create --label <resolved_label> --preview <preview_id>
agentseg track propagate <track_id> # 每 500 帧约 1 分钟；返回 issues
对于后来添加的关键帧，在 segment 中传递 --track T：这样缩放图还会显示该跟踪最近的关键帧，以便您检查它是否是同一个物体。
3b. 当跟踪丢失物体时
SAM 3 通常在物体消失一段时间后会自动重新拾取它，因此短暂的间隔不需要任何操作。propagate 仅在掩码连续 60 帧为空时才停止一个方向的跟踪，并返回 lost：
"lost": [{"keyframe": 420, "direction": "forward", "lost_from": 579, "stopped_at": 638, "untracked": [639, 999]}]
更常见的失败是相反的：在空隙之后 SAM 回到了一个不同的、相似的物体上。每当跟踪在空帧之后重新出现时（在 sheet --track 中为红色），使用 view <空隙后的第一帧> --track T --zoom 检查身份。
在 issues 之前处理 lost。查看从 lost_from 开始到底发生了什么事：agentseg sheet --frames <lost_from-5>-<lost_from+40>（不带 --track，这样您可以看到纯帧）。
- 物体消失了（隧道、建筑物后面、摄像头转开、剪辑）：找到它回来的地方，
track absent T <lost_from>-<最后一帧消失> --no-propagate，然后在它回来的清晰帧上执行segment+track refine。 - 物体仍然可见：跟踪器丢掉了它。在
lost_from后立刻找一个清晰帧执行segment+track refine。 - 它直到结束也没有回来：将剩余部分标记为
absent。
每次修复都会重新传播；重复直到没有 lost。
使用用户给出的标签名称，或一个简短描述性的名称，例如 torpedo_board。
4. 检查 issues
propagate（以及 refine、absent、keyframes --rm）返回当前的 issue 列表：
{"id": 9, "start": 210, "end": 228, "worst_frame": 218, "kind": "drift", "n_frames": 19, "reasons": {...}}
对于每个 issue，查看它的 worst_frame：
agentseg view <worst_frame> --track <T> --grid
在视图中，跟踪掩码为品红色并带有轮廓。黄色框表示关键帧，青色框表示传播帧。着色会隐藏物体的颜色；对于身份或覆盖范围的问题，请使用特写：
agentseg view <f> --track <T> --zoom # [最近关键帧] [帧] [帧 + 轮廓]，无填充
身份。 在遮挡、隧道、摄像机切换或快速平移之后，SAM 常常会跳到附近的相似物体上。与关键帧面板比较：相同的颜色、相同的车身类型（SUV 对比轿车，掀背车对比三厢车）、相同的细节？“在正确位置的一辆深色车”是不够的。任何 reasons 中包含 dino_low（掩码看起来不像关键帧）的 issue 都需要在您评审之前进行缩放比较。如果它是另一个物体，真正的物体要么在其他地方（对它执行 segment + track refine），要么不可见（track absent）。
| 所见 | 操作 |
|---|---|
| 掩码正确；物体只是变小、变大、旋转或快速移动 | 标记为已检查： agentseg track review T <issue_id> --note "<一行原因>"。它的帧从待审变为已批准。 |
| 掩码溢出到背景或其他物体上，或者有远离的杂散斑点（巨大的 bbox） | 在该帧上使用紧框（+ --neg 在溢出部分）执行 segment，然后 track refine T <f> --preview P |
| 掩码只覆盖了物体的一部分（检查缩放图），或者位于错误物体上（与关键帧面板比较） | 相同：segment → track refine |
| 物体完全不可见（出框、完全遮挡），但存在掩码 | track absent T <range>。先用 sheet --track T --frames a-b 找到范围。 |
| 物体可见但没有掩码（sheet 中的红色“empty”） | 在物体清晰可见的帧上执行 segment → track refine |
规则：
- 不查看预览就绝不精炼。 一个坏的关键帧会污染许多帧的跟踪。
- 如果添加的关键帧使情况变得更糟：
agentseg track keyframes T --rm <f>。 - 批量修复： 对所有除了最后一个
refine或absent的步骤添加--no-propagate，或者随后执行一次agentseg track propagate T。每次传播花费 30–60 秒。 - 对于
absent，检查边界。使用sheet --track T --frames a-b在范围附近查看，并只标记物体确实不可见的帧（图像边缘的一小片仍算可见）。 - 同一个 issue 在 2 次修复后仍然存在 → 停止修复，保持打开（不要
review它）并在您的报告中提及。打开的 issues 是供人稍后检查的内容。 - 只在您查看了 issue 的帧之后再
review它。对于一个长的 issue，检查范围的sheet --track T --frames a-b，而不仅仅是worst_frame。多个同时检查的 issue：track review T 2,3,5 --note ...，但只能是你实际检查过的同类 issue；注释必须对其中每个 id 都成立。绝不要把lostissue（空帧）评审为“掩码正确”。 - 预算：每个序列大约 10 次修复和大约 40 次查看的图像。扫描范围时优先使用一次
sheet而不是多次view。
5. 最终检查与导出
agentseg sheet --track T # 边框颜色：黄色关键帧、绿色正常、
# 橙色待审、灰色缺席、红色无掩码
agentseg export # YOLO-seg（默认）；--format yolo-detect|coco
查看最终 sheet。橙色帧属于仍然打开的 issues：检查并 review 它们，修复它们，或者有意为人工留下它们。红色帧需要关注，除非物体在那里确实不可见；如果是，则标记为 absent。
6. 向用户报告
简短内容：
- 跟踪 ID 和标签
- 帧数
- 关键帧（帧号及原因）
- 缺席范围
- 已评审为正常的 issues，附带一行原因
- 未解决的 issues
- 导出路径
- 最终 sheet 路径
参考
agentseg status | up [--no-sam] [--no-ui] | down [--all]
agentseg project open <dir> [--name N] [--project-dir D]
agentseg labels [--add NAME]
agentseg view <f> [--track T] [--grid] [--preview P] [--zoom]
agentseg sheet [--track T] [--every N | --frames a-b,c]
agentseg segment <f> --box x0,y0,x1,y1 [--pos x,y]... [--neg x,y]... [--track T] [--no-grid]
agentseg track create --label L --preview P
agentseg track propagate T [--full] [--start a --end b] [--max-lost N] [--no-wait]
agentseg track issues T [--verbose]
agentseg track review T <ids|all> [--note TEXT]
agentseg track refine T <f> (--preview P | --box ... [--pos ..] [--neg ..]) [--no-propagate]
agentseg track keyframes T [--rm F] [--no-propagate]
agentseg track absent T <frames> [--no-propagate]
agentseg track list
agentseg export [--format yolo-seg|yolo-detect|coco] [--out DIR] [--approved-only] [--labels-only]
所有命令都接受 --help。错误会输出 {"ok": false, "error": "..."} 并以非零退出；读取消息，因为它通常指出了修复方法。