使用 agentseg 標註序列
您對物件進行一次性分割，SAM 3 會自動追蹤其餘的每一幀，後端會標記看起來有問題的影格（即「問題」）。您的工作是提供一個良好的初始遮罩，然後檢查問題並只修正真正有問題的部分。大多數序列只需要 0–3 次修正。
從 repo 根目錄執行 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。查看 sheet。選擇一個提示影格，其中物件完全可見、大而清晰，不一定是第 0 幀。追蹤會從關鍵影格雙向（向前和向後）執行。
2. 在建立第一個遮罩之前解析標籤
在呼叫 segment 或建立軌跡之前選擇標籤名稱。使用使用者請求中的物件名稱；當請求不明確時，從圖片推斷一個簡短、具體的名稱，並在執行中說明該選擇。永遠不要將標籤保留為 unknown、空字串或佔位符。如果存在多個合理的物件，且選擇會改變標註目標，請在執行 SAM 之前詢問使用者。解析後的名稱會帶入第一個 track create 呼叫以及之後的每個報告。
例如，對於「標註魚雷」解析為 torpedo；對於「標註此資料夾中的板子」解析為 board（或者當物件身分明確時使用 torpedo_board）。在整個序列中保持名稱穩定。
在第一個遮罩之前，將其註冊到專案的標籤列表中（這與人員在網頁 UI 中選擇的清單相同；如果已有命名物件的標籤，請重複使用）：
agentseg labels # 現有標籤
agentseg labels --add <resolved_label>
3. 第一個遮罩
agentseg view <f> --grid # 50 像素標記網格，用於讀取座標
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 分鐘；回傳問題
對於之後添加的關鍵影格，請將 --track T 傳遞給 segment：此時縮圖也會顯示軌跡的最近關鍵影格，以便您可以檢查它是否是同一個物件。
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 檢查身分。
在處理問題****之前處理 lost。查看從 lost_from 開始實際發生的情況：agentseg sheet --frames <lost_from-5>-<lost_from+40>（不加 --track，這樣您可以看到原始的影格）。
- 物件消失了（隧道、建築物後面、鏡頭移開、剪輯）：找到它回來的地方，執行
track absent T <lost_from>-<last gone frame> --no-propagate，然後在它回來的一個清晰影格上執行segment+track refine。 - 物件仍然可見：追蹤器丟失了它。在
lost_from之後的一個清晰影格上執行segment+track refine。 - 它在結束前再也沒有回來：將剩餘部分標記為
absent。
每次修復都會重新傳播；重複直到沒有 lost 為止。
使用使用者提供的標籤名稱，或一個簡短描述性的名稱，例如 torpedo_board。
4. 審查問題
propagate（以及 refine、absent、keyframes --rm）會回傳當前的問題列表：
{"id": 9, "start": 210, "end": 228, "worst_frame": 218, "kind": "drift", "n_frames": 19, "reasons": {...}}
對於每個問題，請查看其 worst_frame：
agentseg view <worst_frame> --track <T> --grid
在檢視中，軌跡遮罩為洋紅色並帶有輪廓。黃色框標記關鍵影格，青色框標記已傳播的影格。填充色會遮蓋物體的顏色；關於身分或覆蓋範圍的任何資訊，請使用特寫：
agentseg view <f> --track <T> --zoom # [最近關鍵影格] [影格] [影格 + 輪廓]，無填充
身分。 在遮擋、隧道、鏡頭切換或快速平移後，SAM 經常跳到附近的相似物件上。與關鍵影格面板比較：相同顏色、相同車型（SUV 與轎車、掀背車與三廂車）、相同細節？「一輛位置正確的深色汽車」是不夠的。任何其 reasons 包含 dino_low（遮罩看起來與關鍵影格不同）的問題，在您審查之前都需要進行縮圖比較。如果是另一個物件，真正的物件要麼在其他地方（對它執行 segment + track refine），要麼不可見（track absent）。
| 您看到的情況 | 操作 |
|---|---|
| 遮罩正確；物件只是變小、變大、旋轉或快速移動 | 將其標記為已檢查： agentseg track review T <issue_id> --note "<一行原因>"。它的影格會從待審查轉為已批准。 |
| 遮罩溢出到背景或其他物件上，或有遠離的離散斑點（邊界框巨大） | 對該影格使用一個緊密的邊界框（+ --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圍繞範圍進行檢查，並僅標記物件真正不可見的影格（靠近影像邊緣的一小條仍算作可見）。 - 同一個問題在 2 次修復後仍然存在 → 停止修復它，保持其開啟（不要對其執行
review），並在您的報告中提到它。未解決的問題是人員之後會檢查的內容。 - 僅在您檢視了問題的影格後才能對其執行
review。對於一個長問題，檢查該範圍的一個sheet --track T --frames a-b，而不僅僅是worst_frame。可以一次檢查多個問題：track review T 2,3,5 --note ...，但僅限於您實際檢查過的相同類型的問題；該說明必須對列表中的每個 ID 都成立。切勿將lost問題（空影格）審查為「mask correct」。 - 預算：每個序列約 10 次修復和約 40 張檢視的圖片。掃描範圍時，優先使用一個
sheet而不是多個view。
5. 最終檢查與匯出
agentseg sheet --track T # 邊框顏色：黃色關鍵影格、綠色良好、
# 橘色待審查、灰色為不存在、紅色為無遮罩
agentseg export # YOLO-seg（預設）；--format yolo-detect|coco
查看最終的 sheet。橘色影格屬於仍然開啟的問題：檢查並對其執行 review，修復它們，或者故意將它們保持開啟以供人員處理。紅色影格需要注意，除非物件在那裡確實不存在；如果是，則將它們標記為 absent。
6. 向使用者報告
簡短：
- 軌跡 ID 和標籤
- 影格數量
- 關鍵影格（影格號及原因）
- 不存在的範圍（absent ranges）
- 已審查為無問題的問題，附帶一行原因
- 未解決的問題
- 匯出路徑
- 最終 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": "..."} 並以非零狀態碼退出；請閱讀訊息，因為它通常會指出修復方法。