agentflowctl 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +139 -134
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,67 +1,34 @@
|
|
|
1
1
|
# agentflowctl
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
讓 Claude Code、Codex、Gemini CLI（或任何 agent CLI）在同一條流程裡輪流寫規格、寫計畫、寫測試、寫實作、互相審查、互相修正，一路做到開 PR。
|
|
4
4
|
|
|
5
5
|
```
|
|
6
6
|
需求 → spec → plan ⇄ plan_review ⇄ plan_fix →（僵持時）仲裁 → implement（測試 A → 實作 B）→ verify ⇄ fix → review ⇄ fix → pr
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
從需求到 PR
|
|
9
|
+
從需求到 PR 全程由程式推進。每個步驟都是一次獨立的 agent 執行，用 `.flow/` 裡的檔案交接。是否通過一律由程式檢查：跑測試、比對 git diff、驗證 JSON。兩家模型就能完整運作；有第三家時，仲裁會交給沒參與討論的那一家。
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## 快速開始
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
同一個模型審查自己的程式碼，很容易對自己的寫法有盲點；測試和實作出自同一個模型，也容易「寫出剛好會過的測試」。agentflowctl 用三條規則打破這種同溫層：
|
|
16
|
-
|
|
17
|
-
| 規則 | 效果 |
|
|
18
|
-
|---|---|
|
|
19
|
-
| **審查者永遠不是最後寫程式的 agent** | 每一輪審查都是「別家」在看 |
|
|
20
|
-
| **同一個任務的測試與實作由不同 agent 負責**（`tddSplit`） | A 寫的測試，B 必須實作到通過，而且不能改測試 |
|
|
21
|
-
| **所有角色沿著同一個輪替順序前進** | 三家輪流扮演作者、審查者、修正者 |
|
|
22
|
-
|
|
23
|
-
最常見的是兩家，例如輪替順序 `claude → codex`，實際跑出來是很乾淨的乒乓模式：
|
|
24
|
-
|
|
25
|
-
```
|
|
26
|
-
計畫：claude 撰寫 → codex 審查（要求修改）→ claude 修改 → codex 審查（核准）
|
|
27
|
-
T-1 測試：claude 實作：codex
|
|
28
|
-
T-2 測試：codex 實作：claude
|
|
29
|
-
審查：codex（最後作者是 claude）→ 要求修改 → claude 修正 → codex 審查（核准）
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
有三家時，修正與審查會一直換人（例如 codex 寫、gemini 審、claude 修），仲裁也能交給完全沒參與的第三方。
|
|
33
|
-
|
|
34
|
-
每個 commit 的訊息結尾都會標上作者，例如 `feat(T-2): 匯出 [gemini]`，事後可以清楚看到每一段程式碼是哪家模型寫的、哪家審過。
|
|
35
|
-
|
|
36
|
-
## 在任何環境都能用
|
|
37
|
-
|
|
38
|
-
agentflowctl 本身只需要 **Node.js 22 以上與 git**，其他全部透過各家的 CLI 執行：
|
|
39
|
-
|
|
40
|
-
| 環境 | 說明 |
|
|
41
|
-
|---|---|
|
|
42
|
-
| macOS、Linux、Windows | 專案指令透過系統 shell 執行，git 操作不依賴任何平台專屬路徑 |
|
|
43
|
-
| CI（GitHub Actions 等） | 見 `examples/github-actions.yml`：issue 加上標籤就自動跑完並開 PR |
|
|
44
|
-
| 容器、遠端開發機 | 可丟棄的環境最適合完全無人值守地執行 |
|
|
45
|
-
| 在 Claude Code、Codex 裡面 | 讓它們用 shell 執行 `agentflowctl`，或之後包成 MCP server |
|
|
46
|
-
|
|
47
|
-
執行前先檢查環境：
|
|
13
|
+
需要 Node.js 22 以上與 git。先讓各家 CLI 完成訂閱登入，再檢查環境：
|
|
48
14
|
|
|
49
15
|
```bash
|
|
16
|
+
npm install -g agentflowctl
|
|
17
|
+
claude # 完成登入
|
|
18
|
+
codex # 完成登入
|
|
50
19
|
agentflowctl doctor
|
|
51
|
-
# ✅ claude adapter=claude
|
|
52
|
-
# ✅ codex adapter=codex
|
|
53
|
-
# ❌ gemini adapter=gemini
|
|
54
|
-
# 輪替順序：claude → codex
|
|
55
20
|
```
|
|
56
21
|
|
|
57
|
-
|
|
22
|
+
`doctor` 會列出已安裝的 CLI，並印出即將使用的輪替順序。沒有 `flow.config.json` 時，會自動採用偵測到的 CLI。
|
|
58
23
|
|
|
59
|
-
|
|
24
|
+
在專案資料夾內開始一次 run：
|
|
60
25
|
|
|
61
26
|
```bash
|
|
62
|
-
|
|
27
|
+
agentflowctl run --req "登入表單加上 zod 驗證與錯誤訊息"
|
|
63
28
|
```
|
|
64
29
|
|
|
30
|
+
這次 run 在專用 git worktree（`.agentflowctl/worktrees/<id>`）裡工作，基底是你目前的分支，新分支名是 `flow/<id>`。你正在編輯的工作目錄不會被改到。
|
|
31
|
+
|
|
65
32
|
從原始碼安裝：
|
|
66
33
|
|
|
67
34
|
```bash
|
|
@@ -72,31 +39,61 @@ pnpm run build
|
|
|
72
39
|
pnpm link --global
|
|
73
40
|
```
|
|
74
41
|
|
|
75
|
-
|
|
42
|
+
## 輪替怎麼打破同溫層
|
|
43
|
+
|
|
44
|
+
同一個模型審查自己的程式碼，容易放過自己的寫法；測試和實作出自同一個模型，也容易寫出剛好會過的測試。角色分配只有三條規則，定義在 `src/roles.ts`：
|
|
45
|
+
|
|
46
|
+
| 規則 | 效果 |
|
|
47
|
+
|---|---|
|
|
48
|
+
| 審查者永遠不是最後寫程式的 agent | 每一輪審查都由另一家看 |
|
|
49
|
+
| 同一個任務的測試與實作由不同 agent 負責（`tddSplit`） | A 寫的測試，B 實作到通過，而且不能改測試 |
|
|
50
|
+
| 所有角色沿著同一個輪替順序前進 | 各家輪流當作者、審查者、修正者 |
|
|
51
|
+
|
|
52
|
+
兩家時是乒乓。輪替順序 `claude → codex` 會跑成：
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
計畫：claude 撰寫 → codex 審查（要求修改）→ claude 修改 → codex 審查（核准）
|
|
56
|
+
T-1 測試：claude 實作：codex
|
|
57
|
+
T-2 測試：codex 實作：claude
|
|
58
|
+
審查：codex（最後作者是 claude）→ 要求修改 → claude 修正 → codex 審查（核准）
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
三家時，修正與審查會一直換人。例如 codex 寫、gemini 審、claude 修；仲裁交給沒寫過這份計畫、也沒審過它的那一家。
|
|
62
|
+
|
|
63
|
+
每個 commit 訊息結尾會標上實際作者，例如 `feat(T-2): 匯出 [gemini]`。
|
|
76
64
|
|
|
77
|
-
|
|
65
|
+
只裝一家也能跑完，只是審查、測試、實作都會落在同一家。
|
|
78
66
|
|
|
79
|
-
|
|
67
|
+
## 指令
|
|
80
68
|
|
|
81
69
|
```bash
|
|
82
|
-
agentflowctl run --req "
|
|
70
|
+
agentflowctl run --req "..."
|
|
83
71
|
agentflowctl run --req-file ./req.md --cycle codex,claude --max-agent-runs 40
|
|
84
|
-
agentflowctl run --req "..." --manual-plan # 計畫通過 AI
|
|
72
|
+
agentflowctl run --req "..." --manual-plan # 計畫通過 AI 審查後，仍停下來等你確認
|
|
85
73
|
|
|
86
|
-
agentflowctl approve f-xxxx # 搭配 --manual-plan
|
|
87
|
-
agentflowctl status f-xxxx # 階段、任務進度、各 agent
|
|
74
|
+
agentflowctl approve f-xxxx # 搭配 --manual-plan
|
|
75
|
+
agentflowctl status f-xxxx # 階段、任務進度、各 agent 用量、代打紀錄
|
|
88
76
|
agentflowctl list
|
|
89
77
|
agentflowctl logs f-xxxx --latest
|
|
90
|
-
agentflowctl resume f-xxxx #
|
|
78
|
+
agentflowctl resume f-xxxx # 從暫停、Ctrl-C 或失敗處接續
|
|
91
79
|
agentflowctl cancel f-xxxx
|
|
92
|
-
agentflowctl clean f-xxxx # 移除 worktree
|
|
80
|
+
agentflowctl clean f-xxxx # 移除 worktree 與 run 紀錄，分支保留
|
|
93
81
|
```
|
|
94
82
|
|
|
95
|
-
|
|
83
|
+
| 選項 | 作用 |
|
|
84
|
+
|---|---|
|
|
85
|
+
| `--req` / `--req-file` | 需求文字，或從檔案讀取 |
|
|
86
|
+
| `--base` | 基底分支，預設為目前分支 |
|
|
87
|
+
| `--cycle` | 這次 run 的輪替順序，例如 `claude,codex,gemini`；建立後就固定，`resume` 沿用 |
|
|
88
|
+
| `--max-agent-runs` | 這次 run 的 agent 執行次數上限 |
|
|
89
|
+
| `--budget` | 估計花費上限（美元）；使用 API 計費時才需要 |
|
|
90
|
+
| `--manual-plan` | 計畫通過審查後進入 `awaiting_approval`，等 `approve` 才開始實作 |
|
|
96
91
|
|
|
97
|
-
|
|
92
|
+
`status` 會列出任務。進行中的任務會標出正在寫測試還是正在寫實作。
|
|
98
93
|
|
|
99
|
-
|
|
94
|
+
## 設定
|
|
95
|
+
|
|
96
|
+
專案根目錄的 `flow.config.json`。完整範例見 `examples/flow.config.json`。未提供的欄位使用內建預設（安裝指令、測試指令、檢查清單預設對應 Vite + TypeScript + Vitest）。
|
|
100
97
|
|
|
101
98
|
```json
|
|
102
99
|
{
|
|
@@ -111,123 +108,131 @@ agentflowctl clean f-xxxx # 移除 worktree，分支保留
|
|
|
111
108
|
}
|
|
112
109
|
```
|
|
113
110
|
|
|
114
|
-
| 設定 | 說明 |
|
|
115
|
-
|
|
116
|
-
| `cycle` |
|
|
117
|
-
| `fixStrategy` | `ring
|
|
118
|
-
| `tddSplit` |
|
|
119
|
-
| `reviewQuorum` |
|
|
120
|
-
| `planReviewQuorum` |
|
|
121
|
-
| `planArbiter` |
|
|
122
|
-
| `tieBreak` |
|
|
123
|
-
| `auth` | `subscription
|
|
124
|
-
| `maxAgentRuns` | 單一 run 最多執行幾次 agent
|
|
125
|
-
| `
|
|
111
|
+
| 設定 | 預設 | 說明 |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| `cycle` | 自動偵測 | 輪替順序。同一家 CLI 可以登記成不同 agent，例如 `claude-fast` 與 `claude-strong` |
|
|
114
|
+
| `fixStrategy` | `ring` | `ring`：審查意見交給審查者的下一位；`author`：交回最後作者 |
|
|
115
|
+
| `tddSplit` | `true` | 測試與實作是否分開 |
|
|
116
|
+
| `reviewQuorum` | `1` | 程式碼需要幾位不同審查者都 `approve` |
|
|
117
|
+
| `planReviewQuorum` | `1` | 計畫需要幾位不同審查者都 `approve` |
|
|
118
|
+
| `planArbiter` | `true` | 計畫審查僵持時交付仲裁。關掉之後，僵持會直接讓 run 失敗 |
|
|
119
|
+
| `tieBreak` | `proceed` | 兩家仲裁意見分歧時：`proceed` 繼續並記錄爭議；`stop` 停下 |
|
|
120
|
+
| `auth` | `subscription` | `subscription` 移除子程序裡的 API key；`api` 保留，給 CI 用 |
|
|
121
|
+
| `maxAgentRuns` | `60` | 單一 run 最多執行幾次 agent |
|
|
122
|
+
| `install` / `test` / `checks` | 見 `src/schemas.ts` | verify 階段實際執行的指令 |
|
|
123
|
+
| `agents` | 內建 claude、codex、gemini | 覆寫內建 agent，或用 `command` adapter 接上其他 CLI |
|
|
126
124
|
|
|
127
|
-
verify 失敗（型別、lint
|
|
125
|
+
verify 失敗（型別、lint、建置）一律交回最後作者。審查意見才依 `fixStrategy` 決定修正者。
|
|
128
126
|
|
|
129
|
-
##
|
|
127
|
+
## 計畫怎麼在沒有人的情況下通過
|
|
130
128
|
|
|
131
|
-
|
|
129
|
+
人工確認計畫是為了擋住方向錯了還一路做下去。預設用三層機制取代它；加上 `--manual-plan` 時，三層都過了仍會停下來等你。
|
|
132
130
|
|
|
133
|
-
|
|
131
|
+
**格式與覆蓋率。** 每次撰寫或修改計畫之後，都要重新通過 zod、任務相依、無循環、每條驗收條件都有任務負責。沒過就還原。
|
|
134
132
|
|
|
135
|
-
|
|
133
|
+
**跨模型審查。** 審查看需求覆蓋、驗收條件能不能測、任務大小與技術方向。審查者只能寫意見。若改了規格或計畫，檔案會被還原。修改者要在 `plan.md` 的「審查回應」逐條回覆；不同意要寫理由。
|
|
136
134
|
|
|
137
|
-
|
|
135
|
+
**僵持時仲裁。** 兩種情況會觸發：這輪審查意見和上一輪一樣，或已達重試上限。仲裁者只判斷一件事：照這份計畫實作，能不能滿足需求。
|
|
138
136
|
|
|
139
|
-
|
|
|
137
|
+
| 有幾家 | 誰來仲裁 | 結果 |
|
|
140
138
|
| --- | --- | --- |
|
|
141
|
-
|
|
|
142
|
-
|
|
|
139
|
+
| 三家以上 | 沒參與這次討論的那一家 | 核准就繼續，否則 run 失敗 |
|
|
140
|
+
| 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就停下；分歧依 `tieBreak` |
|
|
141
|
+
| 一家 | 同一家 | 由它自己仲裁 |
|
|
143
142
|
|
|
144
|
-
|
|
143
|
+
兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含模型名稱的爭議清單（`.flow/dispute.md`）。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
|
|
145
144
|
|
|
146
|
-
|
|
145
|
+
裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。原始審查與仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。
|
|
146
|
+
|
|
147
|
+
## 階段與通過條件
|
|
148
|
+
|
|
149
|
+
| 階段 | 負責的 agent | 程式認定通過的條件 | 失敗時 |
|
|
150
|
+
|---|---|---|---|
|
|
151
|
+
| spec | 輪替順序第 1 位 | 檔案存在、zod 驗證、id 不重複 | 重試 |
|
|
152
|
+
| plan | 輪替順序第 1 位 | zod、相依存在、無循環、每條驗收條件都有任務 | 重試 |
|
|
153
|
+
| plan_review | 非計畫作者的下一位（可多位） | 所有審查者都 `approve` | 進入 plan_fix |
|
|
154
|
+
| plan_fix | 依 `fixStrategy` | 修改後仍通過 plan 的格式與 DAG 檢查 | 還原並重試 |
|
|
155
|
+
| 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 都不核准，或 `tieBreak: stop` 時 run 失敗 |
|
|
156
|
+
| 人工確認 | 你（只有 `--manual-plan`） | `agentflowctl approve` | — |
|
|
157
|
+
| implement 紅燈 | 第 i 個任務由第 i 位 | 有測試變更，而且測試執行後失敗 | 還原並重試 |
|
|
158
|
+
| implement 綠燈 | 測試作者的下一位 | 測試檔沒有任何修改，而且測試通過 | 還原，或帶著輸出重試 |
|
|
159
|
+
| verify | — | `install` 與所有 `checks` 通過 | 交回作者修正 |
|
|
160
|
+
| review | 非作者的下一位（可多位） | 所有審查者都 `approve` | 依 `fixStrategy` 交給下一位修正 |
|
|
161
|
+
| pr | — | push 成功；有 `gh` 就開 PR | — |
|
|
162
|
+
|
|
163
|
+
驗收條件寫在 `.flow/acceptance.json`（`AC-1`…），任務寫在 `.flow/tasks.json`（`T-1`…）。
|
|
147
164
|
|
|
148
165
|
## Adapter
|
|
149
166
|
|
|
150
|
-
| adapter | 執行方式 |
|
|
167
|
+
| adapter | 執行方式 | 權限 |
|
|
151
168
|
|---|---|---|
|
|
152
|
-
| `claude` | `claude -p --output-format stream-json` | acceptEdits、禁止 git
|
|
153
|
-
| `codex` | `codex exec --json --sandbox workspace-write
|
|
154
|
-
| `gemini` | `gemini -p --output-format stream-json --approval-mode yolo` |
|
|
155
|
-
| `command` |
|
|
169
|
+
| `claude` | `claude -p --output-format stream-json` | acceptEdits、禁止 git 寫入、設定檔在 `.agentflowctl/runs/<id>/claude-settings.json` |
|
|
170
|
+
| `codex` | `codex exec --json --sandbox workspace-write`（prompt 走 stdin） | 只能改工作目錄，預設不能連網 |
|
|
171
|
+
| `gemini` | `gemini -p --output-format stream-json --approval-mode yolo` | 沒有細緻權限；可在 `extraArgs` 加 `--sandbox`，或放在可丟棄環境 |
|
|
172
|
+
| `command` | 任意指令；`{prompt}` 替換，或走 stdin | 取決於該工具 |
|
|
156
173
|
|
|
157
|
-
Codex
|
|
174
|
+
Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。CLI 參數與事件格式更新得很快，第一次使用前先 `doctor`，再用一個小需求實測。
|
|
158
175
|
|
|
159
|
-
|
|
176
|
+
各家讀的專案說明檔不同：Claude Code 讀 `CLAUDE.md`，Codex 讀 `AGENTS.md`，Gemini 讀 `GEMINI.md`。把專案慣例寫在 `AGENTS.md`，另外兩個檔案各用一行引用它。agentflowctl 的 prompt 在 `prompts/`，不依賴任何一家的 skills 或 plugins。
|
|
160
177
|
|
|
161
|
-
##
|
|
178
|
+
## 登入、額度與代打
|
|
162
179
|
|
|
163
|
-
|
|
164
|
-
|---|---|---|---|
|
|
165
|
-
| spec | 輪替順序第 1 位 | 檔案存在、zod 驗證、id 不重複 | 重試 |
|
|
166
|
-
| plan | 輪替順序第 1 位 | zod 驗證、相依存在、無循環、每條驗收條件都有任務負責 | 重試 |
|
|
167
|
-
| plan_review | 非計畫作者的下一位（可多位） | 所有審查者都 `approve` | 進入 plan_fix |
|
|
168
|
-
| plan_fix | 審查者的下一位 | 修改後仍通過 plan 的所有格式與 DAG 檢查 | 還原並重試 |
|
|
169
|
-
| 仲裁 | 有第三家：第三方；只有兩家：兩家雙盲各自仲裁 | 一致核准；分歧依 `tieBreak` | 都不核准（或 `tieBreak: stop`）時 run 失敗，這時才需要人 |
|
|
170
|
-
| 人工確認 | 你（只有 `--manual-plan` 時） | `agentflowctl approve` | — |
|
|
171
|
-
| implement（紅燈） | 第 i 個任務由第 i 位 | 有測試變更，且執行後**失敗** | 還原並重試 |
|
|
172
|
-
| implement（綠燈） | 測試作者的下一位 | 測試檔**完全沒被修改**，且測試通過 | 還原或帶著輸出重試 |
|
|
173
|
-
| verify | — | install 與所有 checks 通過 | 交回作者修正 |
|
|
174
|
-
| review | 非作者的下一位（可多位） | 所有審查者都 `approve` | 依 `fixStrategy` 交給下一位修正 |
|
|
175
|
-
| pr | — | push 成功，有 `gh` 就開 PR | — |
|
|
180
|
+
預設 `auth: "subscription"`，只用各家 CLI 的訂閱登入。
|
|
176
181
|
|
|
177
|
-
|
|
182
|
+
執行 agent 時，會從子程序環境移除 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`CODEX_API_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`GOOGLE_API_KEY`，避免環境裡的 key 蓋過訂閱登入。`doctor` 發現這些變數時會提醒。專案指令（install、test、build）不受影響。
|
|
178
183
|
|
|
179
|
-
|
|
184
|
+
上限是執行次數（`maxAgentRuns`，預設 60），不是金額。Claude Code 回報的美元金額是 API 價格的估計值。
|
|
180
185
|
|
|
181
|
-
|
|
186
|
+
額度用完時：
|
|
182
187
|
|
|
183
|
-
|
|
188
|
+
| 步驟 | 行為 |
|
|
189
|
+
| --- | --- |
|
|
190
|
+
| 計畫審查、程式碼審查、仲裁 | 暫停。額度恢復後 `agentflowctl resume`。換人代審會變成作者審自己 |
|
|
191
|
+
| 規格、計畫、修改計畫、寫測試、寫實作、修正 | 由輪替順序上下一位還有額度的 agent 代打 |
|
|
192
|
+
| 每家都用完 | 暫停 |
|
|
184
193
|
|
|
185
|
-
|
|
194
|
+
換人或暫停前，額度用完的 agent 留下的半成品會先清掉。代打寫在 `.agentflowctl/runs/<id>/substitutions.jsonl`，`status` 會列出。commit 結尾標的是實際執行的模型。
|
|
186
195
|
|
|
187
|
-
|
|
188
|
-
| --- | --- | --- |
|
|
189
|
-
| 計畫審查、程式碼審查、仲裁 | **暫停**，等額度恢復後 `agentflowctl resume` | 由另一家代審，可能變成作者審查自己，失去交叉審查的意義 |
|
|
190
|
-
| 規格、計畫、修改計畫、寫測試、寫實作、修正 | **由另一家代打**，繼續執行 | 撰寫品質之後仍有審查把關 |
|
|
191
|
-
| 所有 agent 的額度都用完 | 暫停 | — |
|
|
192
|
-
|
|
193
|
-
換人或暫停前，額度用完的 agent 留下的半成品會先被清掉。代打會記錄在 `.agentflowctl/runs/<id>/substitutions.jsonl`，`agentflowctl status` 也會列出；commit 結尾標註的是實際執行的模型。
|
|
196
|
+
若寫實作的那家額度用完、改由寫測試的那家代打，這個任務的測試與實作就會出自同一家，`status` 會標註。審查步驟仍然暫停，等原本的另一家，因為那是此時剩下的交叉檢查。
|
|
194
197
|
|
|
195
|
-
|
|
198
|
+
額度錯誤靠錯誤訊息辨識（usage limit、rate limit、quota、429 等），只在 agent 執行失敗時判斷。辨識不到時，會當成一般失敗重試。
|
|
196
199
|
|
|
197
|
-
|
|
200
|
+
CI 無法使用訂閱登入時，設 `"auth": "api"` 保留 API key，並用 `--budget` 設估計花費上限。Codex、Gemini 只回報 token，要在 `agents.<name>.pricing` 設定價格才會算進預算。GitHub Actions 範例見 `examples/github-actions.yml`。
|
|
198
201
|
|
|
199
|
-
|
|
202
|
+
## 在哪裡跑
|
|
200
203
|
|
|
201
|
-
|
|
204
|
+
agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell 執行。
|
|
202
205
|
|
|
203
|
-
|
|
206
|
+
| 環境 | 適合的用法 |
|
|
207
|
+
|---|---|
|
|
208
|
+
| 自己的電腦 | 自己的專案、自己寫的需求。剛開始可以加 `--manual-plan`，確認審查品質後再拿掉 |
|
|
209
|
+
| CI、容器、遠端開發機 | 無人值守。見 `examples/github-actions.yml`：issue 加上標籤就跑完並開 PR |
|
|
210
|
+
| Claude Code、Codex 裡面 | 讓它們用 shell 執行 `agentflowctl` |
|
|
204
211
|
|
|
205
|
-
|
|
206
|
-
- 要無人值守或處理外部 issue：放到 CI runner 或容器這類可丟棄的環境。
|
|
207
|
-
- 不要把來路不明的 issue 內容直接交給 agentflowctl 在本機執行，需求文字本身就可能夾帶惡意指示；AI 審查計畫並不能擋住這類攻擊。
|
|
212
|
+
沒有容器隔離時，verify 會在你的電腦上執行 agent 寫出來的程式碼。Gemini 在無人值守時是 yolo 模式。處理外部 issue，或需求文字不是你自己寫的，放到可丟棄的環境。AI 審查計畫擋不住夾在需求裡的指示。
|
|
208
213
|
|
|
209
214
|
## 專案結構
|
|
210
215
|
|
|
211
216
|
```
|
|
212
217
|
src/
|
|
213
|
-
cli.ts
|
|
214
|
-
engine.ts
|
|
215
|
-
roles.ts
|
|
216
|
-
runner.ts 執行 agent
|
|
217
|
-
agents/ claude、codex、gemini、command
|
|
218
|
-
git.ts worktree
|
|
219
|
-
store.ts
|
|
220
|
-
tasks.ts 任務 DAG
|
|
221
|
-
schemas.ts
|
|
222
|
-
prompts/ 各階段 prompt
|
|
223
|
-
examples/ flow.config.json 與 GitHub Actions
|
|
218
|
+
cli.ts 指令列（run、doctor、status……）
|
|
219
|
+
engine.ts 狀態機與各階段
|
|
220
|
+
roles.ts 輪替規則（含計畫修正者與仲裁者）
|
|
221
|
+
runner.ts 執行 agent、正規化結果、執行專案指令
|
|
222
|
+
agents/ claude、codex、gemini、command
|
|
223
|
+
git.ts worktree 與 git 操作
|
|
224
|
+
store.ts 狀態、花費、代打紀錄
|
|
225
|
+
tasks.ts 任務 DAG
|
|
226
|
+
schemas.ts zod schema
|
|
227
|
+
prompts/ 各階段 prompt
|
|
228
|
+
examples/ flow.config.json 與 GitHub Actions
|
|
224
229
|
```
|
|
225
230
|
|
|
226
|
-
|
|
231
|
+
開發：
|
|
227
232
|
|
|
228
233
|
```bash
|
|
229
234
|
pnpm run typecheck
|
|
230
|
-
pnpm test
|
|
235
|
+
pnpm test
|
|
231
236
|
```
|
|
232
237
|
|
|
233
238
|
## 授權
|