【2026 最新】Ordewell 教學：可編輯 Agent 任務圖真的比 Worktree 穩嗎？

你同時開了三個 Coding Agent：一個改 API、一個補測試、一個更新文件。半小時後，每個視窗都說「完成」，但 lockfile 被改了兩次、測試依賴還沒合併，最後仍得由你拼回正確順序。問題不一定是 Agent 不夠聰明，而是「在哪裡改」與「什麼先做」被混成同一題。

這篇 Ordewell 教學專為第一次接觸多 Agent 編排的讀者寫。我們會把 Ordewell 0.4.19 拆成白話零件，實際教你安裝、審查可編輯任務圖、安排 runner／model／effort，並用測試、Diff Boundary 與 Mutation Test 補上它不負責的正確性驗收。最後再公平回答：它真的比平行 Git Worktree 穩嗎？

先說結論：Task Graph 與 Worktree 解的是兩種問題

Worktree 隔離的是「在哪裡改」；Task Graph 約束的是「什麼先跑、誰來跑、什麼能解鎖下一步」。

• Ordewell 的強項：先把模糊目標變成可編輯的依賴圖，再讓已滿足依賴的任務並行；每個任務可指定 runner、model 與 effort。
• 平行 Worktree 的強項：每個 Agent 有分開的工作目錄、index 與 HEAD；即使兩邊想改同名檔案，也不會直接在同一份檔案上互踩。
• 不能直接宣布誰比較穩：Ordewell 的任務共享同一工作目錄；Git 的 worktree 指令則聚焦在工作目錄隔離，任務依賴要由人、腳本或其他編排層安排。前者少了合併步驟但承擔並行寫入風險，後者換得檔案隔離卻多了整合成本。
• 最務實的組合：用 Worktree 隔離真正獨立、可能碰到相同檔案的 epic；在每個 epic 裡，再用任務圖安排有明確前後關係、且檔案邊界清楚的工作。

Ordewell 是什麼？先記住這條公式

Ordewell ＝ 唯讀 Planner ＋ 可編輯依賴圖 ＋ 每任務一個新 Agent Session ＋ Marker 完成握手。

Ordewell 不是新的 AI 模型，而是跑在本機的 Agent 編排層。你給它一個目標，Planner 先研究 repo、提出任務與依賴；你可以在執行前修改 prompt、先後順序、runner、model、effort 與人工檢查點。執行時，已滿足依賴的任務可平行啟動；v0.4.19 文件的預設值是三個，設定表記載的範圍是一到五個。完整概念可對照 Ordewell 官方文件與 v0.4.19 README。

「每任務一個新 Session」只表示新的程序、上下文與終端紀錄，不表示每個任務有自己的 Git Worktree。v0.4.19 的 TaskOrchestrator 原始碼把各 runner 都啟動在同一個 workspace root；因此 Planner 若錯判檔案邊界，兩個 Agent 仍可能同時碰 lockfile、共用設定或產生檔。

如果你先想理解「模型」與「執行層」為何不同，可以讀 AI Agent Harness 是什麼；Ordewell 正是把計畫、排程、Session 與完成判定包成一套 Harness 的具體例子。

五個零件：從一句目標變成可執行任務圖

① Planner：「只畫施工圖的建築師」

Planner 先讀 repo 與你的目標，再提出工作分解。它的唯讀邊界會隨 backend 改變：以 Codex CLI 當 Planner 時，v0.4.19 的 Codex adapter會要求 read-only sandbox 與 never approval；HTTP provider 的研究 shell 則使用命令分類器。Ordewell 的 v0.4.19 安全說明明示後者不是 OS sandbox，也要求不要只靠分類器隔離 hostile repo content。無論選哪個 backend，陌生 repo 仍應使用容器、最小權限與不含秘密的環境。

② Task Graph：「有箭頭的施工清單」

每個節點是一項可交付工作，箭頭代表 dependency。A 完成後才能啟動 B，不相依的 C、D 則可並行。它比一張普通待辦清單多了「什麼條件解鎖下一步」，也比直接扔出五個 Agent 更容易在執行前發現錯誤順序。若你想先補圖結構的基礎，可參考 Graph Engineering 教學。

③ Runner／Model／Effort：「替每一工種配人」

Planner 與執行者要分開看。v0.4.19 內建的任務 runner 是 Claude Code、Codex 與 OpenCode；其他 CLI 要透過 runner manifest 擴充。你可以把讀文件交給較輕量的設定，把跨檔案重構交給較高 effort，但「可以混搭」不等於「一定省錢」：不同 CLI 的訂閱額度與 token 帳單並沒有被 Ordewell 統一計量。

④ Fresh Session：「每位工人拿一張新白紙」

每個任務拿到乾淨的對話上下文，降低長對話把舊假設一路帶下去的風險；相依任務會收到前置結果摘要，實際檔案修改則留在共用 workspace。代價是上下文連續性變少：如果 A 的重要判斷沒有寫進檔案、任務說明或可驗證 artifact，B 未必完整知道。

⑤ Completion Marker：「交工鈴，不是驗屋合格章」

Ordewell 會要求 runner 在完成時輸出專屬 marker，系統看到後把任務判為 PASS。這能避免只靠程序退出碼猜測 Agent 是否自認完成，卻不能證明程式正確。更關鍵的是，v0.4.19 的 VerdictEngine在看到 marker 時就立即決定通過；真正的後續 process exit 會被略過。官方單元測試甚至包含「先出 marker、之後 exit 137」仍通過的案例。

Marker 證明的是「Agent 發出了約定訊號」，不是「測試已過、需求已滿足、程序已正常結束」。

Ordewell 教學步驟一：在拋棄式 Repo 安裝

截至 2026 年 9 月 20 日，最新 npm／GitHub release 是 v0.4.19，需要 Node.js 20 以上；若要開互動式 TUI，還要先安裝 tmux。專案仍是 pre-1.0，官方 changelog 明示 minor release 可能包含不相容變更；第一次學習建議把版本釘住，不要讓隔天的最新版改掉操作語意。

mkdir ordewell-lab && cd ordewell-lab
git init
npm init -y
git add package.json
git -c user.name="Ordewell Lab" -c user.email="lab@example.invalid" commit -m "chore: baseline"
node --version
tmux -V
npx ordewell@0.4.19

如果不想進 TUI，也可以使用 headless CLI。空白 lab 裡的 goal 只用來看計畫形狀；要真的執行 API 任務，請改用一份已建立 baseline commit、且確實含 API fixture 的拋棄式 repo。下面用已安裝、已登入的 Codex CLI 同時示範兩個不同角色：AI_PROVIDER 選 Planner，--runner 選 task executor，不能把兩者混成同一個開關。

codex login status
export BASE_COMMIT=$(git rev-parse HEAD) # 必須在 Agent 執行前保存
export AI_PROVIDER="codex"             # Planner
npx ordewell@0.4.19 runners codex on   # 啟用 executor
npx ordewell@0.4.19 plan --runner codex --goal "為公開 API 加入 rate limit，補測試與操作文件"
npx ordewell@0.4.19 run

Ordewell 不需要另一把 provider key，並不表示 Codex 一定走訂閱制。先用 codex login status 確認目前身份：依 OpenAI 官方 Codex 驗證文件，ChatGPT 登入會依方案使用量計算，API key 登入則套用標準 API 費率。若改用其他 HTTP provider 當 Planner，也要依該 provider 的驗證與計費方式設定。

步驟二：先改計畫，再按執行

不要把 Planner 的第一版當聖旨。以「為公開 API 加 rate limit」為例，一份可審查的圖應該像下面這樣；重點不是任務多，而是每一條依賴都有理由。

1. A｜凍結需求與邊界：找出公開 route、既有 middleware、錯誤格式與禁止修改的檔案。產物是短規格，不是程式碼。
2. B｜實作 limiter：依賴 A，只能修改 middleware 與設定檔；明寫 runner、model、effort。
3. C｜補行為測試：依賴 A，可與 B 並行，但先限制在獨立 test file；不要讓它同時改 B 的實作檔。
4. D｜整合驗收：同時依賴 B、C，跑 lint、target tests、full suite，並檢查 diff boundary。
5. E｜更新文件：依賴 D；只有驗收通過後才把實際參數寫進文件。

審圖時問四個問題：兩個可並行任務會不會碰同一檔？後置任務需要的資訊是否成為 artifact？任何節點是否可以自己宣告成功卻沒有外部檢查？低風險工作是否真的值得換模型，還是切換成本更高？這套審法與 Agent Harness A/B Test的精神相同：先固定變因與驗收，再比較編排方式。

Ordewell 教學決策：任務圖、平行 Worktree、單 Agent 怎麼選？

選 Ordewell，如果：目標可拆成清楚節點、前後依賴比檔案衝突更棘手，而且你願意在執行前人工審圖。它免去每個分支再合併的動作，但你必須守住共享 workspace 的寫入邊界。

選平行 Worktree，如果：兩個 Agent 可能改同一模組、你想比較兩種實作，或錯誤隔離比自動排程重要。Git 官方文件說明 linked worktree 有自己的 working tree，以及各自的 HEAD、index 等 per-worktree 檔案；代價是最後要 merge／cherry-pick、處理衝突並重跑整合測試。想看成熟的 session／branch 操作，可讀 Claude Code Projects 平行分支教學與 Proliferate Worktree 教學。

選單 Agent，如果：改動小、上下文高度耦合、拆圖與交接比實作本身還久。一個小 bug 若只碰兩個檔案，硬拆五個節點通常只是多五份 prompt、多五次啟動與更多失真機會。

其實可以一起用：先用 Worktree 把「付款」、「帳號」、「通知」這類會互相碰撞的大 epic 隔開；每個 Worktree 裡只跑一份任務圖，讓節點負責該 epic 內的調查、實作、測試與文件。不要把這理解成 Ordewell 自動替每個 task 建 Worktree——v0.4.19 並沒有這項隔離。

步驟三：把外部 Oracle 接在 Marker 後面

Oracle 是「誰有資格判斷答案對不對」。Agent 自己輸出的 marker 只能當排程握手；真正的 Oracle 應由 CI、固定驗證腳本或人工驗收執行，不接受 task 的自我評分。Ordewell 的整合節點可以集中收據，但不能自己改寫驗收標準。

第一層：可重跑的 build／lint／tests

npm run build
npm run lint
npm test -- --runInBand
npm run test:e2e

上面只是 npm 專案的命令形狀，請換成你 repo 真正存在的 script。不要接受「我已檢查」這種自然語言；先跑目標測試快速回饋，再跑完整 regression，兩者的 exit code、stdout 摘要、時間與 commit／diff 狀態都留成 artifact。

第二層：Diff Boundary，抓出越界修改

# 使用執行前已保存的 BASE_COMMIT，檢查未提交與已提交變更
git status --short
git diff --name-only "$BASE_COMMIT"
git diff --check "$BASE_COMMIT"

為每個 task 先寫 allowed paths，例如 B 只能碰 src/middleware/** 與指定 config。驗收時只要出現 package-lock.json、migration、部署設定或其他禁止檔案，就算測試全綠也先擋下來。對共享 workspace 而言，這是一道成本低、又容易自動化的保險。

第三層：Mutation Test，檢查測試是不是真的會抓 bug

普通測試全綠，只能證明目前程式沒有觸發失敗。Mutation Testing 會刻意把 > 改成 >=、翻轉布林值或刪掉回傳，再看測試是否變紅；若 mutant 存活，代表測試可能只跑到程式，卻沒有守住行為。以 JavaScript／TypeScript 的 Stryker 為例，先檢查 initializer 產生的設定，再執行：

npm init stryker@latest
npx stryker run

這兩個命令來自 Stryker 官方入門文件。Mutation Test 通常比單元測試慢，不必每個小節點都跑；把它放在 D 的整合驗收，或只針對本次新增的核心邏輯。

步驟四：做四次故障注入，不要等真事故才學會恢復

下面是你可以在拋棄式 repo 自行執行的演練清單，不是 AlphaLab 已跑出的 benchmark 結果。每輪都先複製 session JSON、記錄 base commit 與終端輸出，測完再丟掉 repo。

故障一：Runner crash

在 B 執行中終止 runner，觀察 B 是否停止、相依的 D／E 是否沒有啟動、已在跑的平行 C 如何收尾。v0.4.19 排程器原始碼顯示，驗證失敗會把 running 設成 false；Retry 會重設 task，但隨後的 scheduler tick 因此不會自行重啟。正確演練是先 Retry 重設，再由操作介面重新 Execute Plan 或單獨 Run Task，並確認相依節點沒有被越過。

故障二：故意畫錯 dependency

先讓文件 E 不依賴驗收 D，看看它是否會提早把不存在的參數寫進文件。再把依賴修正、重新執行，確認 D 未通過時 E 保持 blocked。這一輪測的是「圖能否表達你的真實流程」，不是模型智力。

故障三：過早輸出 Marker

做一個會先輸出 marker、再以非零狀態結束的假 runner，或讓 task 在未建立預期檔案前宣告完成。預期 Ordewell 的排程層可能顯示 PASS；外部 Oracle 必須用缺檔、測試失敗或 diff boundary 把它擋下。這正是把「完成握手」與「交付驗收」分成兩層的理由。

故障四：留下半成品後中斷

讓 B 改到一半就中斷，再重新載入 session。檢查 orphaned in_progress 是否回到可處理狀態、哪些完成狀態真的已落盤、重新執行會不會重做 A。v0.4.19 的 session loader 原始碼顯示 reload 會正規化遺留狀態，但中途成功 task 的持久化時點仍值得你在自己的環境驗證；不要把「有 session 檔」直接等同 crash-safe resume。

成本怎麼記？Ordewell 不會替你產生完整收據

官方 repository 的 v0.4.19 benchmark README明確說，舊成本模型只套用 token 估計與價目表，沒有計量外部 CLI 的真實端到端執行；一次 real-repo 嘗試也沒有重現預期節省，因此不應引用任何節省比例。換模型可能更省，也可能因拆圖、重複上下文與重試而更貴。

session_id,task_id,runner,model,effort,start_at,end_at,status,
input_tokens,output_tokens,subscription_bucket,api_cost,
retry_count,files_changed,test_result,mutation_result,notes

最小收據至少要把 Planner、每個 runner 與 retry 分開；訂閱制若拿不到單次美元成本，就記 quota bucket、wall time 與 token（若 CLI 有回報），不要偽造一個精確金額。比較 Ordewell 與 Worktree 時，還要把人工審圖、合併衝突、失敗清理與重跑時間算進去。

六個風險：裝好不等於可以放手跑

1. 共享工作目錄：session 分開，檔案沒有分開；平行 task 必須避開共同檔案與產生物。
2. Marker 不是 correctness：它甚至不保證真正的 process 已正常退出；外部 Oracle 不能省。
3. Planner 邊界依 backend 而異：Codex planner 走 read-only sandbox；HTTP planner 的 shell classifier 不是 OS sandbox。陌生 repo 仍用容器、最小權限與空白 secrets。
4. Resume 要自己演練：狀態顯示、落盤時點與 retry 行為要用你釘住的版本驗證。
5. 文件可能領先 release：只使用 v0.4.19 CLI help／README 已證實的命令，不照抄 main 上尚未進 release 的介面。
6. Pre-1.0 會變：升級前備份 .ordewell/sessions、讀 changelog，並在拋棄式 repo 重跑故障注入。

FAQ：Ordewell 教學最常見的八個問題

1. Ordewell 一定比平行 Worktree 穩嗎？

不一定。它原生表達依賴，卻共享檔案系統；Worktree 原生隔離工作目錄，卻要另外安排依賴與整合。穩定性取決於你的主要失敗是「順序錯」還是「寫入互撞」。

2. Completion marker 等於任務成功嗎？

不等於。它只代表 runner 輸出約定字串。Build、測試、需求、Diff Boundary 與安全檢查都要由外部驗收。

3. 每個 task 都有自己的 Worktree 嗎？

沒有這種自動隔離。以 v0.4.19 而言，各 task runner 使用同一個 workspace root；分開的是 session／context，不是檔案。

4. 一定要同時用很多模型嗎？

不用。先用你最熟悉的一個 runner 跑通圖、Oracle 與收據，再做 model routing；否則失敗時很難分辨是模型、任務或編排。

5. 「不用 API key」代表不花錢嗎？

不代表。使用已登入的 CLI 可以不再配置另一把 provider key；但 Codex 若用 ChatGPT 登入，就依方案用量計算，若用 API key 登入，則按標準 API 費率計費。先跑 codex login status，再記成本收據。

6. Crash 後能從原地續跑嗎？

要看狀態是否已持久化。官方有 session reload 與遺留狀態正規化，但你仍應用固定版本做中斷演練，確認哪些完成 task 會被保留、哪些會重跑。

7. 小任務也值得畫圖嗎？

多半不值得。若單一 Agent 在一段上下文就能完成，圖的規劃、審查與交接成本可能高於收益。

8. 最先該測哪個故障？

先測過早 marker。它最直接揭露「排程完成」與「程式正確」的差距，也能逼你把外部 Oracle 接好。

給新手的七個重點

1. Ordewell 是編排 Harness，不是新模型。
2. Task Graph 管依賴；Worktree 管檔案隔離，兩者不是同義詞。
3. 執行前先審 dependency、檔案 ownership、runner 與驗收產物。
4. Completion marker 只是握手，不能替代 build、測試與 Diff Boundary。
5. Mutation Test 檢查的是「測試能否抓 bug」，不是把覆蓋率再印一次。
6. 沒有真實成本收據，就不要宣稱混合模型一定更省。
7. 先在拋棄式 repo 注入 crash、錯依賴、早 marker 與半成品，再碰正式專案。