Better WorkflowsRC1
5.0.0-rc.1V5.0 RC1 已公開上架，GA 仍待完成。

證據齊備，才算完成。
證據不明，就先停下來。

Better Workflows 是開源的 AI 工程 QA＋交付守門人，像一位要求嚴格的資深 QA 工程師，替 AI agent 把關每一次交付。只有證據屬於目前的儲存庫、revision、scope 與目標，且能被再次檢查，階段才算通過。

  • Goal-first
  • Evidence-driven
  • Fail-closed
  • Risk-adaptive
開始安裝 看閘門如何運作 GitHub

gate-demo · 閘門逐步演示

示意演示，並非即時執行
  1. $better-workflows:auto <描述你要的結果>
  2. routeevidence-required · policy dev-publish-v1
  3. goal凍結 goal、scope、acceptance 與 authority 已綁定
  4. source綁定目前 repository 與 revision，擷取 source sentinel 有效
  5. worktree建立 task-owned branch 與 worktree，不動你的 checkout 已隔離
  6. execute在綁定的 scope 內執行有界工作 完成
  7. verifytyped evidence 綁定目前 source，review receipt 齊備 通過
  8. authority此 target 已授權，只允許單一副作用 授權
  9. act執行「一次」外部副作用 已送出
  10. reconcile核對 provider 狀態：回傳 outcome unknown 未知核對 provider 與 repository 狀態 一致
  11. complete不重試、不宣告完成 未抵達重新取樣 sentinel，重驗 acceptance，清理 task-owned 資源 完成

STOPPED SAFELYprovider 結果未知：不重試、不宣告完成，先停下來等你決定。

COMPLETE終態的 provider 與 repository 證據齊備，已清理本任務擁有的 branch 與 worktree。

GATE STATE

STOPPED AT 08 / 09
  1. 目標凍結GOALPASS
  2. 來源綁定SOURCEPASS
  3. 隔離 worktreeWORKTREEPASS
  4. 有界執行EXECUTEPASS
  5. 證據有效且已審查VERIFY · GATEPASS
  6. 此 target 已授權AUTHORITY · GATEPASS
  7. 單一副作用ACTPASS
  8. 核對 provider 狀態RECONCILE · GATEBLOCKED
  9. 完成並清理COMPLETENOT REACHED
PROVIDER 結果

這是示意演示。欄位與狀態僅用來說明閘門如何通過、又在哪裡停下；另一種結局是 provider 結果已確認，流程走到完成。

01設計原則PRINCIPLES

Prompt 能描述意圖，
卻從不授予權限。

階段只有在證據屬於目前的儲存庫、revision、scope 與目標，且可被再次檢查時才會通過。證據缺漏、過期、衝突或結果未知時，流程會停止並請你決定，而不是假裝任務已完成。

WITHOUT vs WITH沒有治理，與有 Better Workflows

面向沒有治理有 Better Workflows
授權Intent 與 authority 混為一談Goal、scope 與 authority 是各自獨立的紀錄
時效通過的檢查可能屬於舊的 revision證據綁定目前的 source 與 target
重試重試可能重複一個外部動作嘗試次數有上限，未知的結果會先被核對
完成「完成」可能只代表指令回傳了完成需要終態的 provider 與 repository 證據
隔離兩個任務編輯同一個 checkout會修改 Git 的任務各自使用專屬的 branch 與 worktree

AUTHORITY LAYERS權責分層

  1. L1
    Prompt

    記錄想要的結果

    不授予權限
  2. L2
    Context

    綁定目前的事實

  3. L3
    Harness

    限定誰可以在哪裡行動

  4. L4
    Loop

    限制重試與核對的次數

  5. L5
    Graph

    投影已受理的狀態，不是 scheduler、policy 輸入或權限來源

    僅投影

02工作流程WORKFLOW

風險決定驗證強度，
而不是儀式。

清楚、可復原、低風險的變更可以走 Auto 快速路徑，只做小而聚焦的檢查；其餘一律升級為證據工作流，驗證強度與風險相稱。

AUTO FLOWAuto 的五個步驟

  1. 檢查程式碼儲存庫、Goal、scope 與原分支
  2. 判斷 Auto 快速路徑 或 evidence-required
  3. 唯讀工作留在原處；Git 修改才建立或重用隔離 task worktree
  4. 驗證結果；獲授權後才回併修改
  5. 只清理本任務擁有的 branch 與 worktree

ROUTING快速路徑，或證據工作流

ENTRYPOINT$better-workflows:auto
BINDS ONE POLICYread-only-v1code-change-v1dev-publish-v1
AUTO 判斷依任務與風險，選擇驗證強度
FAST PATH

Auto 快速路徑

清楚、可復原、低風險的變更

只做小而聚焦的 targeted check，不走完整證據流程。

即使走快速路徑，仍然

  • 不繞過 protected branch
  • 不擴大 scope
  • 不安裝工具
  • 不略過 task-owned worktree
EVIDENCE WORKFLOW

證據工作流

其餘所有變更

驗證強度依風險調整；證據必須屬於目前的 source 與 target。

這些檢查會立即升級為證據模式

  • package-manager
  • network
  • child-process
  • native
  • checkout-external

LIFECYCLE用四個問題取代「完成」

  1. 01

    Define

    TaskContract

    目標、範圍、驗收、權限與風險路線，凍結了嗎？

    1. 陳述目標
    2. 綁定範圍與目前脈絡
    3. 要修改 Git？是 ⇒ 建立或重用 task-owned worktree
  2. 02

    Verify

    Evidence

    證據綁定到目前的原始碼了嗎？

    1. 在界線內執行有界工作
    2. 審查並驗證有效證據source sentinel · typed evidence · graph 與 review receipt
  3. 03

    Reconcile

    Provider truth

    外部副作用的結果，已經確認了嗎？

    1. 此 target 已授權？否／未知 ⇒ 安全停止
    2. 執行「一次」副作用一次性授權
    3. 核對 provider 與 repository 狀態未知 ⇒ 調查，不盲目重試；安全停止
  4. 04

    Complete

    Terminal decision

    重新取樣之後，驗收仍然成立嗎？

    1. 重新取樣 sentinel，重新驗證 acceptance、ledger、review 與遠端結果
    2. 完成，並清理本任務擁有的資源

Replay 重播的是「判斷」，在已記錄的證據上再做一次決定；它不會重新 push、merge、deploy 或 release。

GIT SAFETYGit 邊界

Git 邊界示意圖 你的 checkout 維持不變；修改在專屬的 task branch 與 worktree 完成，並以已檢查的候選版本透過 compare-and-swap 回併。 你的 checkout（唯讀工作留在這裡）task branch + task-owned worktreeCAS
修改在專屬 worktree 完成，回併走已檢查的候選版本與 compare-and-swap。
  • G1

    唯讀工作留在原處。

  • G2

    會修改 Git 的工作一律使用專屬的 task branch 與 task-owned worktree，絕不動你的 checkout。

  • G3

    回併使用已檢查的候選版本，並以 compare-and-swap 完成。

  • G4

    只在有證明時，才清理本任務擁有的 branch 與 worktree。

  • G5

    未提交的變更（dirty state）不會被 stash，也不會被隱藏。

  • G6

    乾淨、由AI 工具建立的專屬 worktree 會被採用，而不是再巢狀建立一個。

03支援範圍HOSTS & PLATFORMS

RC1 支援到哪裡，
我們直接標出來。

V5.0 RC1 只涵蓋 macOS × Node.js 22/24 上的 Codex、Gemini CLI 與 Qwen Code。Claude Code、Linux 與 Windows 的資格驗收延至 V5.1，目前不算已支援。

V5.0 RC1 公開範圍：工具與作業系統
工具macOSLinuxWindows
Codex官方推薦RC1 公開V5.1 延後V5.1 延後
Gemini CLIRC1 公開V5.1 延後V5.1 延後
Qwen CodeRC1 公開V5.1 延後V5.1 延後
Claude CodeV5.1 延後V5.1 延後V5.1 延後

NODE.JS 22/24 · 隨附 helper 需要 ≥ 22.14.0V5.1 延後 = 資格驗收尚未完成，不算已支援

技術細節：V4 歷史支援矩陣（僅供參考）HOST-SUPPORT-V1

下方 V4 支援矩陣屬於歷史資料。目前 RC1 範圍為 macOS、Codex／Gemini CLI／Qwen Code 與 Node 22/24；GA 尚未完成。

V4 · HOST-SUPPORT-V1

V4 AI / OS capability matrix

證據至上的 AI 工程 QA＋交付守門人。

讓 AI agent 依風險選擇驗證強度，在隔離環境安全完成工作。

單純修改快速完成；重要工作使用證據 gate；Git 修改預設使用專屬 worktree。

AI hostSupportOS coverageIntegration
Codex Recommended on macOStier1macos: tier1 · linux: tier1 · windows: previewCodex plugin
Claude Codetier1macos: tier1 · linux: tier1 · windows: previewClaude Code plugin
Gemini CLItier1macos: tier1 · linux: tier1 · windows: previewGemini CLI extension
Qwen Codetier1macos: tier1 · linux: tier1 · windows: previewQwen Code extension
Kimi Code CLIpreviewmacos: preview · linux: preview · windows: previewCompatibility pack
Kiropreviewmacos: preview · linux: preview · windows: previewCompatibility pack
Grok Buildpreviewmacos: preview · linux: preview · windows: previewCompatibility pack
Cursorpreviewmacos: preview · linux: preview · windows: previewCompatibility pack
GitHub Copilotpreviewmacos: preview · linux: preview · windows: previewCompatibility pack

native = host-native · core-bridge = shared control layer · unverified/unavailable are explicit limits.

AI hosttask-contracttyped-evidencereplayaction-gatetask-worktreenative-pickernative-subagents
Codexnativenativenativenativecore-bridgenativenative
Claude Codecore-bridgecore-bridgecore-bridgecore-bridgecore-bridgeunavailableunverified
Gemini CLIcore-bridgecore-bridgecore-bridgecore-bridgecore-bridgeunavailableunverified
Qwen Codecore-bridgecore-bridgecore-bridgecore-bridgecore-bridgeunavailableunverified
Kimi Code CLIcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
Kirocore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
Grok Buildcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
Cursorcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
GitHub Copilotcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified

官方推薦：macOS + Codex——原生整合最深、參考體驗最完整。

網站來源版本：16690d7c323e204b98efd3c3675e7933a66531e1

04開始使用INSTALL

選擇你的工具，
貼上指令。

RC1 在 macOS 上提供 Codex、Gemini CLI 與 Qwen Code 的安裝路徑。隨附的 helper 需要 Node.js 22.14.0 或更新版本。請選擇你信任的本機儲存庫；Better Workflows 不宣稱能隔離惡意的儲存庫程式碼。

  1. 1

    安裝

    選擇你的工具，複製指令到終端機執行。官方推薦 macOS + Codex。

  2. 2

    重新載入

    Codex：開啟「新的」任務，讓 skill 清單更新。Gemini CLI 與 Qwen Code：安裝後重新啟動 session。

  3. 3

    提出第一個請求

    在對話中輸入 $better-workflows:auto，接著描述你需要的結果。

  4. RC1 尚非 GA。完整安裝步驟請見 快速開始

Codex

codex plugin marketplace add stephen-taipei/better-workflows
codex plugin add better-workflows@better-workflows

然後開啟一個「新的」Codex 任務，skill 清單才會更新。

Gemini CLI

gemini extensions install https://github.com/stephen-taipei/better-workflows --ref V5.0.rc1

安裝後請重新啟動 session。

Qwen Code

git clone --branch V5.0.rc1 --depth 1 https://github.com/stephen-taipei/better-workflows.git
qwen extensions install ./better-workflows

安裝後請重新啟動 session。

FIRST REQUEST · 第一個請求

$better-workflows:auto 檢視這個儲存庫並修正已確認的缺陷。
$better-workflows:auto 檢視這個儲存庫並摘要主要部分，不要修改檔案。

上面是修正請求，下面是唯讀請求。

05證明邊界PROOF BOUNDARY

能證明的與還不能證明的，
都寫在這裡。

我們把話說在前面：它能阻擋哪些錯誤、哪些還沒有被證明，以及它不是什麼。

能偵測並阻擋

可觀測的錯誤

  • 錯誤的儲存庫或 revision
  • 過期的證據（stale evidence）
  • 虛假的完成宣稱
  • 未授權的副作用
  • 未知的 provider 結果
  • 過早的 cleanup

尚未證明

長期成效

  • 尚未以統計證明，長期多輪的 agent 任務有較低的 scope drift、rework 或決策錯誤率
  • 無法證明你最初的目標，是正確的產品決策

它不是

邊界之外

  • 不是 sandbox：不宣稱隔離惡意的儲存庫程式碼，請選擇你信任的本機儲存庫
  • 不是無限制的 agent runtime
  • 不會收集敏感或私人的歷史紀錄
Better Workflows 能阻擋錯誤的程式碼儲存庫、錯 revision、stale evidence、未授權副作用與過早 cleanup 等可觀測錯誤；但尚未以統計證明長期任務的整體 scope drift、rework 或錯誤決策率下降。
  1. B1Auto 快速路徑 仍會執行 targeted check，且絕不繞過 protected branch
  2. B2protected 或 remote target 必須走受治理 PR、fresh checks 與 merge authority
  3. B3Replay 是重播已記錄證據的判斷，不會重新 merge、push 或 deploy

06發行狀態與授權STATUS & LICENSE

V5.0 RC1 已公開上架，GA 仍待完成。

RC1 是受控預發行版本，公開入口僅有 Auto。GA 需要的條件與延後的項目都列在下面，不會預先宣稱。

  1. NOW 2026-10-03 公開

    V5.0 RC1

    5.0.0-rc.1 · V5.0.rc1

    macOS × Node.js 22/24 上的 Codex、Gemini CLI 與 Qwen Code。唯一公開入口是 Auto。

  2. PENDING 尚未發行

    GA 5.0.0

    需要同時滿足

    • 至少 30 個自然 canary 日
    • 20 次連續符合資格的啟動
    • 三個不同的儲存庫

  3. DEFERRED 延至 V5.1

    V5.1

    Claude Code · Linux · Windows

    這些工具與作業系統的資格驗收延至 V5.1，目前尚未發行。

STATEMENT正式聲明

V5.0 RC1 · 公開上架與授權

V5.0 RC1（5.0.0-rc.1，tag V5.0.rc1）是受控預發行版本，公開入口僅有 Auto。V4 支援矩陣仍屬歷史文件範圍；RC1 不代表 GA 驗收或 V5 全面完成。

V5.0 RC1 涵蓋 macOS × Node 22/24 上的 Codex、Gemini CLI 與 Qwen Code。Claude Code、Linux 與 Windows 的驗收延至 V5.1。GA 仍需至少 30 個自然 canary 日、20 次連續符合資格的啟動，以及三個不同儲存庫。

第一方 Better Workflows 核心採 AGPL-3.0-only。實體獨立的 minimal wire package 另採 Apache-2.0；其 LICENSE 與 NOTICE 適用於該 package。

基本產品免費。Professional Pack 規劃為專有產品，Cloud 是後續獨立產品；兩者目前尚未提供。

LICENSING授權與提供狀態

授權與提供狀態
項目授權或形式狀態
第一方核心AGPL-3.0-onlyRC1 已公開
minimal wire packageApache-2.0實體獨立，其 LICENSE 與 NOTICE 適用於該 packageRC1 已公開
基本產品免費RC1 已公開
Professional Pack規劃為專有產品尚未提供
Cloud後續獨立的產品尚未提供

07文件DOCS

依你的下一步閱讀。

5 個文件頁面，繁體中文與英文都有。想先看一次完整的過程，從 Evidence Cinema 開始。

卡通場景：藍色狐狸向舉手攔阻的琥珀色陸龜出示證明，青綠色機器人在一旁等候。INTERACTIVE · 互動示範

EVIDENCE CINEMA · 證據劇場

證據不是字幕，它決定結局。

八幕原創卡通重播：從意圖到可證明完成。可以暫停、倒帶，並切換「證據完整」與「provider outcome unknown」兩種結局。

  • Captain Root
  • Scout Pixel
  • Ledger
  • Vera
  • Sentinel
  • Echo
六位原創角色 · sanitized 教學重播，不是 live run
進入證據劇場

08常見問題FAQ

常見問題，
直接回答。

沒找到答案？到 GitHub 或 支援頁面 詢問。

Better Workflows 是什麼？

它是開源的 AI 工程 QA＋交付守門人，像一位要求嚴格的資深 QA 工程師，替 AI agent 把關。階段只有在證據屬於目前的儲存庫、revision、scope 與目標，且能被再次檢查時才會通過；證據缺漏、過期、衝突或未知時，流程會停下來請你決定，而不是假裝完成。

它會自己推送、合併或部署嗎？

不會單憑 prompt 就做。Prompt 只描述意圖，從不授予權限。只有 Root 可以編輯、回併、部署、接受風險或宣告完成；每個副作用都需要有效證據、出處與綁定預期目標的動作，而且一次只執行一個副作用。

小改動也要跑完整流程嗎？

不用。清楚、可復原的低風險變更可以走 Auto 快速路徑，只做小而聚焦的檢查；其餘會升級為證據工作流。即使走快速路徑，也不會繞過 protected branch、不擴大 scope、不安裝工具，也不略過 task-owned worktree。

它會動到我目前的 checkout 嗎？

唯讀工作留在原處。會修改 Git 的工作一律使用專屬的 task branch 與 task-owned worktree，不會動你的 checkout；未提交的變更（dirty state）不會被 stash，也不會被隱藏。

RC1 支援哪些環境？Claude Code、Linux 與 Windows 呢？

V5.0 RC1 的公開範圍是 macOS × Node.js 22/24，搭配 Codex、Gemini CLI 與 Qwen Code；官方推薦 macOS + Codex。Claude Code、Linux 與 Windows 的資格驗收延至 V5.1，目前尚未發行。

它能保證程式沒有錯誤嗎？

不能。它能阻擋錯誤的儲存庫或 revision、stale evidence、未授權副作用與過早 cleanup 等可觀測錯誤，但尚未以統計證明長期任務的 scope drift、rework 或決策錯誤率下降，也無法證明你最初的目標是正確的產品決策。

它是 sandbox 嗎？

不是。它不宣稱隔離惡意的儲存庫程式碼，請選擇你信任的本機儲存庫；它也不是無限制的 agent runtime，並且不會收集敏感或私人的歷史紀錄。

授權與費用是什麼？

第一方核心採 AGPL-3.0-only，實體獨立的 minimal wire package 採 Apache-2.0。基本產品免費；Professional Pack 規劃為專有產品，Cloud 是後續獨立產品，兩者目前尚未提供。

V5.0 RC1 · 已公開上架

讓下一次「完成」，
有證據可查。

安裝公開的 RC1，從 $better-workflows:auto 開始。GA 仍待完成，這點我們會一直寫在最前面。

開始安裝RC1 發行說明