---
{
  "id": "platform.image_editor.session-flow-and-lifecycle",
  "topic": "image_editor",
  "title": "圖片編輯器 session 流程與生命週期",
  "locale": "zh-TW",
  "version": "2026-07-24",
  "summary": "依 live-session 順序操作，並遵守瀏覽器選區、history、斷線與 export 的實際語意。",
  "content": "標準流程是 `list_sessions` → `select_region` → `request_edit` → 可選的 `undo` → `export`。`list_sessions` 只列出明確 grant 給本 Agent 且仍通過 image-project write 檢查的 sessions，並提供 `projectId`、`fileKey` 等 context。region 使用相對可見 canvas 的 normalized 0..1 座標，不是 pixel。`select_region` 會先清空再整個取代 mask，連使用者手繪選區也會被取代；若使用者可能想保留，應先確認。\n\n`request_edit` 在 command 執行當下讀取 mask。目前瀏覽器在沒有選區時會回 `selection_required`；瀏覽器回傳的 reason 才是 runtime 真相。成功後，結果會載入可見 canvas、推進 browser history，並更新 image project current revision。完整 prompt 不可寫入 knowledge 或 routing telemetry；editor action 會 redact `arguments.prompt`。\n\n`undo` 是共用 browser canvas history 的單步回退，所以可能退掉使用者自己的最近操作。位於 history 底部時會靜默 no-op，仍回 `{undone:true}`；Agent 沒有 redo action，undo 也不會退還已完成 edit 的費用。`export` 把目前 canvas 轉為 PNG，上傳成 File Center 管理的 image-project 新 revision，回傳 `imageKey` 與 `assetUrl`，但不會自動貼進對話。\n\n關閉或斷開瀏覽器會使 session 失效。遇到「session is not open」或「disconnected」應重新 `list_sessions`，不可重試舊 ID。要區分 not found、grant required、disconnected conflict、action timeout，以及帶 reason 的 browser rejection，例如 `missing_region` 或 `selection_required`。revoke/takeover cancellation 對該 grant 是終止結果，不是重試訊號。\n",
  "aliases": [
    "圖片編輯流程",
    "選取區域",
    "局部重繪",
    "編輯器復原",
    "匯出修圖",
    "image edit flow",
    "inpaint"
  ],
  "tags": [
    "image-editor",
    "session-flow",
    "lifecycle",
    "selection",
    "undo",
    "export"
  ],
  "relatedActions": [
    "arinova.image_editor.list_sessions",
    "arinova.image_editor.select_region",
    "arinova.image_editor.request_edit",
    "arinova.image_editor.undo",
    "arinova.image_editor.export"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/image_editor/session-flow-and-lifecycle/"
}
---

標準流程是 `list_sessions` → `select_region` → `request_edit` → 可選的 `undo` → `export`。`list_sessions` 只列出明確 grant 給本 Agent 且仍通過 image-project write 檢查的 sessions，並提供 `projectId`、`fileKey` 等 context。region 使用相對可見 canvas 的 normalized 0..1 座標，不是 pixel。`select_region` 會先清空再整個取代 mask，連使用者手繪選區也會被取代；若使用者可能想保留，應先確認。

`request_edit` 在 command 執行當下讀取 mask。目前瀏覽器在沒有選區時會回 `selection_required`；瀏覽器回傳的 reason 才是 runtime 真相。成功後，結果會載入可見 canvas、推進 browser history，並更新 image project current revision。完整 prompt 不可寫入 knowledge 或 routing telemetry；editor action 會 redact `arguments.prompt`。

`undo` 是共用 browser canvas history 的單步回退，所以可能退掉使用者自己的最近操作。位於 history 底部時會靜默 no-op，仍回 `{undone:true}`；Agent 沒有 redo action，undo 也不會退還已完成 edit 的費用。`export` 把目前 canvas 轉為 PNG，上傳成 File Center 管理的 image-project 新 revision，回傳 `imageKey` 與 `assetUrl`，但不會自動貼進對話。

關閉或斷開瀏覽器會使 session 失效。遇到「session is not open」或「disconnected」應重新 `list_sessions`，不可重試舊 ID。要區分 not found、grant required、disconnected conflict、action timeout，以及帶 reason 的 browser rejection，例如 `missing_region` 或 `selection_required`。revoke/takeover cancellation 對該 grant 是終止結果，不是重試訊號。