docker-agent（原 cagent）v1.157.0 的修正清單：被 token 上限截斷的 tool call 曾照殘缺參數執行，被拒絕的呼叫可能反覆跑

現在去開 github.com/docker/cagent，會被 301 轉到 github.com/docker/docker-agent。2026-11-10 的 GitHub API 回報：created_at 是 2025-09-01，Apache-2.0，沒有封存，4671 顆星。什麼時候改的名，我手上的資料沒有。

名字換了，專案的口氣沒變。README 開頭寫它是 “Build, run, and share AI agents with a declarative YAML config, rich tool ecosystem, and multi-agent orchestration.”，又說 “no code required”。最小的設定長這樣，逐字照 README：

1
2
3
4
5
6
7
8
9
10

agents:
  root:
    model: openai/gpt-5-mini
    description: A helpful AI assistant
    instruction: |
      You are a knowledgeable assistant that helps users with various tasks.
      Be helpful, accurate, and concise in your responses.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo

執行是 docker agent run agent.yaml，因為它是 docker CLI 的 plugin；README 說 Docker Desktop 4.63 以上已經預裝。想從 registry 拿現成的，換成 docker agent run myorg/agent:tag。這一行是整個專案最容易讓人停下來的地方：agent 被當成 image 在 push 和 pull。

README 的 Key Features 把周邊也列齊了：模型端支援 OpenAI、Anthropic、Gemini、AWS Bedrock、Mistral、xAI、Docker Model Runner 等；工具端除了內建的 think、todo、memory，任何 MCP server 都能接，本機、遠端、Docker 打包的都行；RAG 有 BM25、embeddings、hybrid search 和 reranking 可以選。README 還說他們用 docker-agent 來開發 docker-agent，指令是 docker agent run ./golang_developer.yaml。另外有一段 Telemetry，寫著 “We collect anonymous usage data to improve the tool.”，細節在另一頁，我沒讀。

為什麼會出現這個專案，README 與多 agent 那頁都沒有交代動機，所以只能從時間線自己拼。

從 1.132 到 1.158，次版號走了 26 格，歷時 66 天；中間有沒有跳號我沒查。releases API 回了 100 筆，那是上限，不是版本總數，所以「這個專案出過幾版」我答不出來。以 2026-11-03 到 11-10 算，這一週有四版：1.157.0、1.157.1、1.157.2、1.158.0。其中兩版是純維護，真正帶內容的只有 1.157.0 與 1.158.0，所以「一週四版」聽起來很快，實際要讀的只有兩份。

1.157.0 除了下面要談的修正，還有兩件跟 agent 行為無關的事：加了一個 docker_agent_no_hook_templates build tag，讓嵌入它的人可以把 text/template 從 runtime 拿掉來縮小執行檔，release notes 說這對 WebAssembly 目標有關；另外 structured output 改用 google/jsonschema-go 驗證。1.158.0 讓兩個 TUI 常駐顯示工具執行時間，結束後留下 “Completed in …” 或 “Failed after …”，也更新了內嵌的 models.dev 型錄快照：新增 85 個模型、移除 86 個、約 258 個有更新。型錄一週的變動量有這麼大，所以這篇不列它支援哪些模型的哪個版本，列了也是過期資料。

並行之後多出來的問題

多 agent 的文件把兩種模式分得很清楚。Delegation 用 sub_agents，是 “Hierarchical (parent → child → parent)”，子 agent 在 sub-session 裡跑，拿到的是 “a clean task description”，父 agent 等它跑完才繼續。Handoffs 是 “Peer-to-peer graph (A → B → C → A)”，同一個 session，下一個 agent 看得到完整對話歷史，前一個 agent 就不在迴圈裡了。兩種可以混用。

這兩個模式的差別，落在 context 怎麼流動。Delegation 的子 agent 只拿到任務描述，所以父 agent 的對話不會洩進去，代價是子 agent 對前情一無所知；Handoffs 讓下一個 agent 看到全部歷史，省了重新交代，代價是前面累積的東西也全部帶過去。同一份 YAML 裡兩個都能選，等於把「要不要讓對方知道前情」變成一個每條邊都要做的決定。

接著文件講了一個限制：transfer_task 是 sequential，協調者會等 sub-agent 做完。要同時派出去，得改用 background_agents toolset，它給四個動作：run_background_agent 立刻回傳 task ID、list_background_agents 或 view_background_agent 看進度、wait_background_agents 收結果、stop_background_agent 取消。

同時派出去的任務會踩到同一份檔案，這是我從這個設計推出來的問題，文件那一頁沒有寫。v1.157.0 的 What’s New 第一條倒像是回答：「Adds worktree: true opt-in for background agents to isolate concurrent tasks in separate git worktrees with independent checkouts, tools, and hooks」。順序是先有順序執行，再有並行，並行之後才補隔離。我不確定這三個功能實際上是不是依這個順序出現的，我手上只有 worktree 這個選項是 11-05 的 v1.157.0 才加的。

這一週的修正，讀起來像一份失敗清單

最讓我意外的是同一個 release 的 Bug Fixes。我節錄五條，括號是 PR 編號，英文照 release notes：

• 「Fixes tool calls cut off by the output-token limit being executed with truncated arguments instead of being retracted」（#4784）
• 「Fixes Gemini adapter not reporting MAX_TOKENS as a length stop or SAFETY stops as refusals, which could cause refused tool calls to execute and loop」（#4786）
• 「Fixes sort -ofile and tree -ofile (option operands) being incorrectly classified as safe commands」（#4787）
• 「Fixes server-side fallback token usage counting only the final attempt’s tokens instead of all attempts, allowing token budgets to be exceeded」（#4799）
• 「Fixes llama.cpp context overflow errors not being recognized as token overflow, preventing auto-compact from triggering on Docker Model Runner」（#4785）

照字面讀，修之前的情況是這樣：模型講到一半被輸出上限截斷，那個講到一半的 tool call 還是會被執行，參數是缺的。Gemini 回來說「因為安全因素停了」，adapter 沒把它當成拒絕，release notes 說這可能讓被拒的呼叫照樣執行並繞圈。預算的計算只算最後一次嘗試，前面 fallback 掉的幾次不算，所以超支。sort -o 與 tree -o 我的理解是會把輸出寫進指定檔案，卻被歸在安全指令那一邊。release notes 沒有講是怎麼判斷的，但從「option operands」這個詞看得出來：選項後面跟著的檔名，原本沒被當成寫入目標。用指令名稱加旗標去判斷安全與否，漏洞通常就出在這種組合上。這是我的推論，我沒讀判斷邏輯的原始碼。

五條裡有一條碰的是 context 滿了怎麼辦，隔壁版本又有一條接著修。#4785 讓 llama.cpp 的 context overflow 能被認成 token overflow，auto-compact 才會觸發；隔了四天，v1.158.0 的 #4817 又處理壓縮本身超出預算的情況，改成帶較少的歷史重新要一次摘要。連續兩版都在修「壓縮」這個動作，我的讀法是，壓縮救不了迴圈的時候，會有人撞到，而且前一條出在 Docker Model Runner 上，後一條的 release notes 沒講是哪個後端。

這五條沒有一條跟 YAML 好不好寫有關。它們全是迴圈邊界上的事：停止原因怎麼翻譯、預算怎麼累加、哪些指令不用問人。這帶出一個有點尷尬的對照。README 的賣點是 no code required，我的讀法是你不用自己寫迴圈。可是迴圈裡這些邊界不會因為你沒寫就消失，只是從你的程式碼移到了別人的程式碼。你寫 YAML 的時候看不到它們，出事的時候也修不了，只能等下一個版號。換個角度說，把迴圈外包出去的好處，是別人替你踩坑；壞處，是你得相信踩坑的速度夠快。就這一週看，維護者的速度不慢。至於這一週以外，我手上沒有資料。

我的看法是，判斷一個 agent runtime 值不值得接進流程，該讀的是它的修正清單，不是功能表。功能表告訴你它想做什麼，修正清單告訴你它在哪裡出過事，以及維護者願不願意把出事的地方寫成白話。這一份寫得很直。

會讓我改看法的條件有兩個。一是我拿這五個情境去對別的 runtime 的 release notes 逐條比，發現大家早就修完了，那這份清單只是平均水準，不特別。二是讀了原始碼，發現這些路徑平常根本走不到。這兩件我都沒做。

會不會有人把它嵌進去

這週的 release notes 有幾條，單看會以為是雜項，放在一起會有輪廓。1.156.1 的 TypeScript SDK 是從 Go 原始碼產生 API wire types、sessions 與 events 的型別；1.157.0 的 build tag 讓嵌入者把 text/template 拿掉；1.158.0 讓 config history 和內嵌的模型型錄變成 Go host 可以不要的東西。三條的共同點，看起來像是有人把 docker-agent 當成函式庫或服務嵌進自己的程式，而不是只在終端機敲 docker agent run。

從哪裡看得出來，我只能說是推論：release notes 提到 “Go hosts”、”embedders”，還有給前端用的 TypeScript 型別，這些詞不會出現在只服務 CLI 的專案裡。專案實際被嵌進哪些產品，我沒查證，也沒看到任何使用者名單。

還沒讀到的部分

README 說 push 到「any OCI registry」，多 agent 文件說可以在 sub_agents 裡直接寫 myorg/agent:tag，會自動從 registry 拉下來。那個被拉下來的 agent 大概帶著自己的 toolsets 與指令（這是我的假設，文件沒寫），進了你的團隊以後，它能用的工具由誰決定，registry 有沒有簽章或驗證，README 與多 agent 那頁都沒有談。v1.158.0 的 PR #4821 標題提到 “A2A agent card” 的測試，專案裡似乎有 A2A 相關程式碼，支援到什麼程度我沒查證。

信任邊界這件事，我不打算替專案下結論。README 與那一頁文件講的是怎麼拉、怎麼引用，沒講拉下來之後怎麼驗；沒講不等於沒有，也許在我沒讀的頁面裡。我能確定的只有：這個機制被寫成賣點，而 v1.157.0 剛好修了一條「指令被誤判為安全」，兩件事擺在同一週。

下一個我想知道的是：別人的 agent 以一個 tag 的形式被拉進你的 sub_agents 之後，那份清單裡「哪些指令算安全」的判斷，是照誰的設定在跑。