版本對應:Orca Desktop
v1.4.244(2026-10-29 發布;本手冊查證日期:2026-10-30)適用對象:資深軟體工程師、技術主管、平台工程(Platform Engineering)、DevOps/SRE、資安與稽核人員、AI Solution/Agent Architect
文件等級:企業標準技術白皮書/內部開發規範與教學手冊
核心原則:每一條規範與指引都附範例;AI 依指引產出後,人必須能 Review 並驗證其正確性——本書以「✅ 驗證方式」區塊與每章「Review 與驗證清單」落實此原則。
主要參考來源:
- 官方 GitHub Repository:https://github.com/stablyai/orca
- 官方文件站:https://www.onorca.dev/docs
- 官方 Release Notes:https://github.com/stablyai/orca/releases
⚠️ 版本快照提醒:Orca 近乎每日發版,本手冊為
v1.4.244時間點之整理。正式導入前請以官方 Repository、文件站與 Release Notes 當下內容為準;凡標示「依官方說明延伸(教學推論)」或「教學示例(非官方)」之內容,請自行查證後再用於正式環境。
目錄
本目錄依 Hugo 實際輸出的標題錨點自動生成並逐一驗證;點擊即可跳至對應章節。詳細小節請見下方「子目錄(詳細版)」。
第一部 認識 Orca
第二部 安裝與起步
第三部 Agent 管理
第四部 開發工作流
- 第十一章 Parallel Worktrees 平行代理實戰
- 第十二章 終端機與編輯器
- 第十三章 內建瀏覽器與 Design Mode
- 第十四章 Review 與 Source Control
- 第十五章 GitHub Linear 與 Jira 整合
第五部 自動化與遠端
- 第十六章 Orca CLI 與 Orchestration
- 第十七章 Scheduled Automations 與 Computer Use
- 第十八章 遠端執行模式
- 第十九章 Mobile Companion 行動裝置
第六部 方法論
第七部 企業案例
第八部 治理與維運
第九部 參考資料
附錄
子目錄(詳細版)
- 2.1 Project 與 Repository
- 2.2 Worktree 模型與生命週期
- 2.3 orca.yaml 與 worktreeinclude 共用檔案
- 2.4 Agent 與 Session
- 2.5 Tabs Panes 與 Split 版面
- 2.6 Quick Open 與 Jump Palette
- 2.7 Session Restore
- 2.8 本章 Review 與驗證清單
- 4.1 系統需求與前置條件
- 4.2 Windows 安裝
- 4.3 macOS 安裝
- 4.4 Linux 安裝
- 4.5 WSL 整合
- 4.6 Docker 與容器環境
- 4.7 更新機制與版本管理
- 4.8 安裝後健康檢查
- 4.9 本章 Review 與驗證清單
- 5.1 加入 Repository
- 5.2 建立第一個 Worktree
- 5.3 選擇與啟動 Agent
- 5.4 三個 Agent 同題競賽
- 5.5 分割窗格同時監看
- 5.6 選出勝者並審查合併
- 5.7 本章 Review 與驗證清單
- 6.1 設定分類總覽
- 6.2 General Appearance 與語言
- 6.3 Git 與 Repository 設定
- 6.4 Terminal 與 Quick Commands
- 6.5 Agents 與 Chat 設定
- 6.6 Browser Integrations 與 Notifications
- 6.7 SSH 與 Remote Orca Servers 設定
- 6.8 Experimental 與 Plugins
- 6.9 企業標準設定基準範例
- 6.10 本章 Review 與驗證清單
- 7.1 支援的 Agent 完整清單
- 7.2 權限預設與安全模式
- 7.3 Claude Code 整合
- 7.4 Codex 整合
- 7.5 Cursor CLI 整合
- 7.6 GLM 與其他相容模型整合
- 7.7 Native Chat 結構化聊天介面
- 7.8 Agent 選型決策指引
- 7.9 本章 Review 與驗證清單
- 8.1 BYO 訂閱模式說明
- 8.2 Usage 與 Rate Limit 追蹤
- 8.3 多帳號 Hot-swap
- 8.4 預估成本與 Stats
- 8.5 API Key 與憑證管理最佳實務
- 8.6 企業用量治理範例
- 8.7 本章 Review 與驗證清單
第九章 Hooks Memory 與 Session History
- 9.1 Per-repo Hooks
- 9.2 Worktree Setup Hooks
- 9.3 Memory 檔案設計
- 9.4 Agent Status Hooks
- 9.5 Session History 檢視與續接
- 9.6 本章 Review 與驗證清單
- 10.1 Agent 狀態指示與 Dashboard
- 10.2 啟動預設與 Restart Chip
- 10.3 Agent Hibernation
- 10.4 Notifications 與 Inbox
- 10.5 Agents Feed 活動摘要
- 10.6 本章 Review 與驗證清單
第十一章 Parallel Worktrees 平行代理實戰
- 11.1 平行分派的運作原理
- 11.2 同題競賽模式
- 11.3 分工協作模式
- 11.4 在十個 Worktree 間切換
- 11.5 Resource Manager 與清理
- 11.6 合併策略與衝突處理
- 11.7 本章 Review 與驗證清單
- 12.1 Terminal 窗格與分頁
- 12.2 Agent 啟動指令與 Quick Commands
- 12.3 終端機主題與快捷鍵
- 12.4 Monaco 編輯器與自動儲存
- 12.5 File Explorer 與拖曳檔案
- 12.6 Rich Markdown 編輯器
- 12.7 HTML Mermaid PDF 等檢視器
- 12.8 本章 Review 與驗證清單
- 13.1 Per-worktree 瀏覽器
- 13.2 Browser-use Profiles
- 13.3 Design Mode 操作
- 13.4 以 Design Mode 修正 UI 缺陷實作
- 13.5 瀏覽器自動化與 Artifact 分享
- 13.6 本章 Review 與驗證清單
- 14.1 Diff Viewer
- 14.2 Annotate AI Diff
- 14.3 逐行審查 AI Diff 實作
- 14.4 Attribution 歸屬標記
- 14.5 Commit Push 與 Amend
- 14.6 Rollback 與歷史追溯
- 14.7 本章 Review 與驗證清單
- 15.1 Git Worktree 與分支策略
- 15.2 GitHub Hosted Reviews Issues 與 Actions
- 15.3 Linear 整合
- 15.4 Jira 整合
- 15.5 GitLab Azure DevOps 與 Bitbucket 現況
- 15.6 GitHub 錯誤排除
- 15.7 本章 Review 與驗證清單
- 16.1 Orca CLI 安裝與驗證
- 16.2 CLI 指令分類速查
- 16.3 Orchestration 監督式多 Agent 流程
- 16.4 Skills Registry 與 MCP
- 16.5 Worktree Checkpoints
- 16.6 本章 Review 與驗證清單
第十七章 Scheduled Automations 與 Computer Use
- 17.1 Scheduled Automations 概念
- 17.2 建立第一個安全的自動化
- 17.3 執行位置 Precheck 與錯過補跑
- 17.4 Computer Use 設定
- 17.5 Snapshot Act Snapshot 操作模式
- 17.6 敏感輸入與安全邊界
- 17.7 本章 Review 與驗證清單
- 18.1 四種執行模式比較
- 18.2 SSH Worktrees 設定
- 18.3 SSH 進階驗證與連線選項
- 18.4 Remote Orca Servers 與 Tailscale
- 18.5 orca serve 無頭伺服器
- 18.6 Cloud VM 與每工作區環境
- 18.7 遠端模式選型指引
- 18.8 本章 Review 與驗證清單
- 19.1 平台支援與安裝
- 19.2 配對流程
- 19.3 行動端 Chat 與 Quick Commands
- 19.4 行動端 Source Control 與瀏覽器檢視
- 19.5 行動端安全治理
- 19.6 本章 Review 與驗證清單
第二十章 AI Coding Workflow 與 Prompt Engineering
- 20.1 端到端 AI Coding 流程
- 20.2 Orca 在各階段的角色
- 20.3 多 Agent 情境的 Prompt 設計原則
- 20.4 任務規格書範本
- 20.5 Prompt 反模式與修正
- 20.6 本章 Review 與驗證清單
- 22.1 為何人工驗證不可省略
- 22.2 三層驗證模型
- 22.3 Diff 審查準則
- 22.4 測試證據要求
- 22.5 規範類產出的驗證
- 22.6 文件與架構產出的驗證
- 22.7 驗收紀錄範本
- 22.8 本章 Review 與驗證清單
- 27.1 需求
- 27.2 分析
- 27.3 架構設計
- 27.4 Agent 分工
- 27.5 Coding 與 Review
- 27.6 Deploy 與 Maintenance
- 27.7 本章 Review 與驗證清單
- 28.1 威脅模型
- 28.2 Agent 權限與沙箱
- 28.3 憑證與金鑰治理
- 28.4 遠端與行動端存取控制
- 28.5 Telemetry 與資料外洩防護
- 28.6 稽核與合規對應
- 28.7 本章 Review 與驗證清單
- 31.1 導入成熟度模型
- 31.2 小型團隊
- 31.3 中型企業
- 31.4 大型企業
- 31.5 銀行與高監理產業
- 31.6 政府與系統整合商
- 31.7 導入里程碑與驗收指標
- 31.8 本章 Review 與驗證清單
- 32.1 基礎概念
- 32.2 安裝與環境
- 32.3 Agent 與帳號
- 32.4 Worktree
- 32.5 Review 與 Git
- 32.6 遠端與行動端
- 32.7 自動化與 CLI
- 32.8 效能與維運
- 32.9 本章 Review 與驗證清單
- 33.1 架構規劃
- 33.2 Agent 選用與分工
- 33.3 Parallel Worktrees
- 33.4 Prompt 設計
- 33.5 Git 與審查
- 33.6 安全與金鑰
- 33.7 遠端與自動化
- 33.8 維運與效能
- 33.9 本章 Review 與驗證清單
- 35.1 全書圖表索引
- 35.2 Flowchart 新人導入流程
- 35.3 Sequence Design Mode 互動
- 35.4 Class Diagram 核心概念模型
- 35.5 ER Diagram 設定與工作階段
- 35.6 Git Flow 多 Agent 分支策略
- 35.7 CI CD Pipeline
- 35.8 Deployment 遠端執行拓撲
- 35.9 State Diagram Agent 狀態機
- 35.10 本章 Review 與驗證清單
- 36.1 使用方式與驗證原則
- 36.2 Architecture
- 36.3 Coding
- 36.4 Migration
- 36.5 Review
- 36.6 Testing
- 36.7 Documentation
- 36.8 Refactor
- 36.9 Performance
- 36.10 Security
- 36.11 Banking
- 36.12 Framework Upgrade
- 36.13 Reverse Engineering
- 36.14 Orchestration 與 Automations
- 36.15 本章 Review 與驗證清單
- B.1 入門
- B.2 核心模型
- B.3 Agents
- B.4 終端機與編輯器
- B.5 瀏覽器
- B.6 Review 與整合
- B.7 CLI 與自動化
- B.8 遠端與行動
- B.9 通知與活動
- B.10 設定與隱私
- B.11 疑難排解
- B.12 Recipes
- B.13 GitHub 與其他官方連結
前言
本手冊是一份以「把人教會」為目標的企業級技術白皮書。它不是官方文件的翻譯,而是把 Orca 官方文件、GitHub README、Release Notes 與實務導入經驗重新組織,補上範例、企業治理考量,以及最重要的——讓讀者能親手驗證每一條敘述的方法。
AI 代理(Agent)可以在幾分鐘內產出數百行程式碼、一份設定檔或一整套規範;真正稀缺的能力,是人類審查者能否判斷這些產出「是否正確、是否安全、是否符合團隊規範」。因此全書每一個操作、設定與指引小節,都附有「✅ 驗證方式」區塊,讓你不必相信任何人(包括本手冊與 AI),而是用指令、畫面與檢查表自行確認。
0.1 文件資訊與版本對應
📌 查證狀態:官方文件明確記載|來源:What is Orca?、GitHub Releases
| 項目 | 內容 |
|---|---|
| 文件名稱 | Orca 教學手冊(企業標準技術白皮書版) |
| 對應產品版本 | Orca Desktop v1.4.244(2026-10-29 發布,stable 通道) |
| 前一版手冊對應版本 | v1.4.150(本版涵蓋 v1.4.151~v1.4.244 的變更) |
| 查證日期 | 2026-10-30 |
| 官方 Repository | stablyai/orca(MIT 授權、TypeScript、Electron) |
| 官方文件站 | onorca.dev/docs |
| 行動端 | iOS App Store、Android APK(見第十九章) |
| 撰寫語言 | 繁體中文(台灣用語);產品功能名詞保留英文,例如 Worktree、Design Mode、Native Chat |
| 介面語言說明 | Orca 自 v1.4.244 起提供繁體中文 UI;本書 UI 路徑一律以英文標示,方便對照官方文件,切換語言方式見 6.2 |
版本對應原則
Orca 幾乎每日發版,功能邊界變動很快。本手冊遵循以下原則:
- 所有事實以 v1.4.244 與 2026-10-30 擷取的官方文件快照為準。
- 若某功能在 Release Notes 有明確版本號,會在內文以「(v1.4.xxx)」標註首次出現或重大變更的版本,方便你判斷自己安裝的版本是否具備該功能。
- 標示為 Beta 或 Experimental 的功能(例如 Remote Orca Servers、Chat UI、Cloud VM、Agent Hibernation),企業導入時應視為「可能變動」,並排入定期複核。
範例:確認你手上的 Orca 版本與本書是否對應
# 列出官方最近 5 個 Release,確認 v1.4.244 是否存在與其發布時間
gh release list --repo stablyai/orca --limit 5
# 檢視特定版本的 Release Notes
gh release view v1.4.244 --repo stablyai/orca✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 本機 Orca 版本 | 開啟 Settings → General → Updates,查看目前版本 | 顯示 v1.4.244 或更新版本 | 低於 v1.4.244 時,部分章節功能可能不存在,先依 4.7 更新 |
| 官方 Release 存在 | gh release view v1.4.244 --repo stablyai/orca | 顯示該版 Release Notes | 若查無此版,代表網路或 gh 認證問題,先執行 gh auth status |
| 文件站可存取 | 瀏覽器開啟 onorca.dev/docs | 顯示「What is Orca?」頁面 | 企業 Proxy 可能封鎖,請向資安申請白名單 |
0.2 適用對象與閱讀路徑
本手冊共九部三十七章加附錄。不同角色關注的重點差異很大,建議依下表挑選優先章節,而不是從頭線性閱讀。
| 讀者角色 | 優先閱讀章節 | 閱讀目的 |
|---|---|---|
| 初次接觸的開發者 | 第一、二、四、五章 | 理解定位、完成安裝並跑通第一個三 Agent 工作階段 |
| 日常實戰的資深工程師 | 第七、十一~十五、二十章 | 熟悉 Agent 整合、平行 Worktree、Review 與 Prompt 設計 |
| 技術主管與架構師 | 第一、三、二十一、二十二、三十一、三十四章 | 評估架構、設計 AI 團隊、建立驗證方法論與導入策略 |
| DevOps、SRE 與 Platform Engineer | 第三、四、六、十六~十八、二十九章 | 環境建置、遠端執行、自動化與維運 |
| 資安與合規人員 | 第三章 3.5、第六章 6.9、第八章、第二十八章 | Telemetry、權限預設、金鑰治理、稽核對應 |
| 金融與高監理產業導入者 | 第二十二、二十六、二十八、三十一章 | 驗證流程、銀行案例、合規與分階段導入 |
| 教育訓練負責人 | 第五章、第二十二章、第三十二、三十六章 | 實作課程、驗收標準、FAQ 與 Prompt 範本 |
三種常見閱讀路徑
| 路徑 | 時間 | 建議順序 | 完成標準 |
|---|---|---|---|
| 快速體驗 | 30 分鐘 | 1.1 → 4.2/4.3/4.4(擇一)→ 第五章 | 已讓兩個以上 Agent 在不同 Worktree 處理同一題 |
| 一日上手 | 1 個工作天 | 第一~六章 → 第十一章 → 第十四章 | 已完成一次「同題競賽 → Review → Commit」,並套用 6.9 基準設定 |
| 導入評估 | 1~2 週 | 第一、三、六、十八、二十二、二十八、三十一、三十四章 | 產出導入評估報告,包含風險、治理與成本 |
💡 小技巧:若你只有 10 分鐘,先讀 1.2「Orca 不是什麼」與 2.4「Agent 與 Session」中的權限預設說明——這兩節能避免最常見、也最昂貴的誤解。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 已選定閱讀路徑 | 對照上表,寫下你的角色與路徑 | 有明確的章節清單與完成標準 | 不確定角色時,先走「快速體驗」路徑 |
| 完成標準可驗證 | 每一路徑的完成標準都能用畫面或指令確認 | 例如 git worktree list 可看到兩個以上 Worktree | 若無法驗證,回到對應章節的「✅ 驗證方式」 |
0.3 查證標示與驗證區塊使用說明
全書使用一套固定的標示系統。理解這套系統,你就能快速分辨「哪些是官方保證、哪些是作者推論、哪些是教學示例」,並知道如何自己動手驗證。
0.3.1 查證狀態標示
每一節開頭或關鍵陳述後,會出現下列格式的引用區塊:
> 📌 **查證狀態**:官方文件明確記載|來源:[Worktrees](https://www.onorca.dev/docs/model/worktrees)| 等級 | 意義 | 讀者應如何使用 |
|---|---|---|
| 官方文件明確記載 | 可在官方文件、README 或 Release Notes 找到直接敘述 | 可直接作為教育訓練與內部規範依據,但仍建議定期複核 |
| 依官方說明延伸(教學推論) | 以官方敘述為基礎,結合一般工程知識推導的結論或建議 | 導入前請依「✅ 驗證方式」在自己的環境實測 |
| 教學示例(非官方) | 作者設計的範例、案例、Prompt 或設定基準 | 視為範本,需依組織實況調整;案例章節皆非真實客戶專案 |
0.3.2 驗證區塊
「✅ 驗證方式」有兩種呈現方式。第一種是表格,適用於多個獨立檢查點:
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 範例:Worktree 已建立 | git worktree list | 出現新路徑與分支 | 檢查 Settings → Repository 與 2.2 的建立流程 |
第二種是編號步驟,適用於需要比對指令輸出的情境。閱讀時請特別注意「預期輸出(示意)」中的關鍵欄位,而不是逐字比對——路徑、雜湊值與時間戳記一定會不同。
0.3.3 AI 產出的人工 Review 區塊
凡是 Prompt、規範或指引類小節,都會附上「🧑⚖️ 人工 Review 要點」核取清單。用法如下:
- 依範例 Prompt 讓 Agent 產出結果。
- 審查者逐項勾選清單;任何一項無法勾選,就不得合併或採用該產出。
- 將勾選結果連同
git diff --stat、測試輸出一起保存,作為稽核證據(驗收紀錄範本見第二十二章)。
範例:本書的人工 Review 區塊長這樣
**🧑⚖️ 人工 Review 要點**
- [ ] 產出是否只修改了指定範圍內的檔案(`git diff --stat`)
- [ ] 測試是否實際執行並通過(要求提供指令與輸出,而非口頭宣稱)0.3.4 其他提示符號
| 符號 | 意義 |
|---|---|
| ⚠️ 注意事項 | 操作風險、版本差異或企業治理上必須留意的事項 |
| ❌ 常見錯誤 | 實務上最常見的誤用與修正方式 |
| 💡 小技巧 | 能提升效率但非必要的做法 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 能分辨三種查證等級 | 任選本書三個 📌 標示,說明其等級代表的可信度 | 能說出「官方記載可直接引用、推論需實測、示例需調整」 | 重讀 0.3.1 表格 |
| 會使用驗證區塊 | 依 0.3.2 範例實際執行一次 git worktree list | 能判讀輸出中的路徑與分支欄位 | 參考第二章 2.2 |
0.4 本版重大更新摘要
📌 查證狀態:官方文件明確記載|來源:GitHub Releases、Ways to run Orca、Settings reference
自前版手冊(v1.4.150)以來,Orca 歷經約九十個版本。以下依主題整理對企業導入影響最大的變更;版本號取自 Release Notes,沒有版本號者代表該功能記載於官方文件,但 Release Notes 摘要中查無對應條目。
0.4.1 執行位置與遠端
| 主題 | 變更內容 | 版本 | 本書章節 |
|---|---|---|---|
| Remote Orca Servers | 讓另一台電腦持有完整 Orca runtime,筆電、瀏覽器與手機作為 client 配對連線;設定介面由六個區段合併為單一伺服器清單,並支援以 Windows 10 1809/Windows Server 2019 作為伺服器(Beta) | v1.4.233 | 3.3、6.7、18.4 |
| orca serve | 無頭模式啟動 Orca runtime,可用 orca serve service install 安裝為 macOS LaunchAgent 或 Linux systemd user unit;關閉視窗不再停止伺服器 | v1.4.224 起陸續強化 | 18.5 |
| SSH 改用 Managed Orca server | Orca 在 SSH 主機上安裝並維護自己的伺服器,Node 版本錯誤或缺少編譯工具不再阻擋連線;可在 Settings → SSH → Managed servers 更新、回滾、復原 | v1.4.224 | 6.7、18.2 |
| SSH 驗證強化 | FIDO2(v1.4.165)、多因素驗證碼(v1.4.217)、僅憑證主機改走系統 ssh(v1.4.241) | 多版 | 18.3 |
| Cloud VM 與每工作區環境 | 以 repo 內的 orca.yaml recipe 加生命週期腳本,為每個 Worktree 建立獨立雲端沙箱、VM 或本機 Docker 容器(BYO 雲端帳號);位於 Settings → Experimental → Cloud VM | 官方文件記載 | 3.3、18.6 |
0.4.2 Agent 與對話
| 主題 | 變更內容 | 版本 | 本書章節 |
|---|---|---|---|
| Native Chat(Chat UI) | 由實驗性 Structured Chat 演進為結構化原生聊天介面,支援 Claude、Codex、Grok、OpenCode、Pi、OMP、Antigravity;新增 Rewind、@ 選檔、排隊訊息 Steer、Inline visuals、Settings → Chat 設定頁;終端機 Session 可即時轉為 Chat | v1.4.198~v1.4.243 | 6.5、7.7 |
| 權限模式 | Settings → Agents 提供 Manual、Auto、Yolo 三種新 Session 權限預設;Codex 新增唯讀 Ask mode | v1.4.232、v1.4.242 | 2.4、6.5、7.2 |
| Folder trust 自動回應 | Orca 啟動 Agent 時預設自動略過「是否信任此資料夾」提示,可在 Settings → Agents 關閉 | v1.4.219 | 6.5、28.2 |
| Hooks 與 Memory | Agent status hooks 可即時開關,並提供 orca agent hooks status 等 CLI;Worktree setup hooks 於 Settings → Repository → Hooks 設定 | v1.4.180 起 | 9.1~9.4 |
| Session History | 跨電腦搜尋 Agent 對話紀錄並提供 orca search;「Continue in New Session」更名為 Hand Off to Another Agent | v1.4.206、v1.4.224 | 9.5 |
| 新增支援的 Agent | OpenCode 2(v1.4.206)、Muse Code(v1.4.211)、ZCode(v1.4.214)、DeepSeek Harness、Freebuff、Qoder、CodeBuddy(v1.4.218)、Qwen Code、GLM Coding Plans、jcode(v1.4.221)、Rovo Dev(v1.4.223)、Antigravity 多項整合 | 多版 | 7.1 |
| Codex 每分頁獨立伺服器 | 每個 Codex 終端機預設執行自己的背景 server,可用 ORCA_CODEX_ISOLATE=0 或設定關閉 | v1.4.217~v1.4.218 | 6.5、7.4 |
0.4.3 工作流、整合與自動化
| 主題 | 變更內容 | 版本 | 本書章節 |
|---|---|---|---|
| Skills 與 MCP | Orca skills 一鍵安裝(含 paired 與 SSH 主機);共享 skills 支援的 Agent 增加 31 種;私有 skill bundle 可在主機間安全分享;MCP servers 於 Settings → Integrations 管理 | v1.4.187、v1.4.229、v1.4.238、v1.4.239 | 16.4 |
| Worktree Checkpoints | Agent 可透過 orca worktree set --comment 與 --workspace-status 回報目前進度,讓人類不必翻對話即可掌握狀態 | 官方文件記載 | 16.5 |
| Browser Profiles | 瀏覽器設定檔可設為 shared、per-repo、per-workspace;新增歷史紀錄、內嵌 DevTools、觀看 Agent 瀏覽、實驗性 Chrome 擴充功能 | v1.4.239~v1.4.243 | 13.2 |
| Jira 整合 | 支援 Cloud 與 Server/Data Center;新增 planning(list、board、sprint、JQL、favourites)與 CLI 讀寫 | v1.4.229 | 15.4 |
| GitHub 強化 | Stacked PRs(v1.4.180)、Projects Roadmap 與 Board(v1.4.198、v1.4.223)、Resolve with AI 衝突處理(v1.4.238) | 多版 | 14、15 |
| Automations | 在所有本機與遠端主機管理排程自動化;每次執行可指定 model 與 effort | v1.4.191~v1.4.192、v1.4.224 | 17.1~17.3 |
| 編輯器與檢視器 | 原生 Jupyter notebook(v1.4.214)、大型 CSV 編輯器(v1.4.222)、音訊與影片播放(v1.4.223) | 多版 | 12.7 |
0.4.4 平台、語言與安全
| 主題 | 變更內容 | 版本 | 本書章節 |
|---|---|---|---|
| 繁體中文 UI | 新增繁體中文、德文、俄文、土耳其文介面;Settings → Appearance → Language 切換 | v1.4.244 | 6.2 |
| 設定檔儲存 | Profile 儲存遷移至 SQLite;JSON 與 SQLite 不一致時會詢問使用哪一份 | v1.4.214 | 3.4 |
| Windows CLI | Windows 上的 orca 改為原生程式,不需 Visual C++ Redistributable | v1.4.219 | 4.2 |
| 安全修正 | ~/.copilot/config.json 權限改為僅擁有者可讀(v1.4.221);Artifact 公開分享預設關閉(v1.4.180);SSH 主機上 orca CLI 控制權預設關閉(v1.4.230) | 多版 | 6.7、28.3 |
| 行動端 | iOS 改由 App Store 安裝,移除 TestFlight 選項;Android 仍為 APK | v1.4.244 | 19.1 |
⚠️ 注意事項:升級者必讀的相容性變更
- v1.4.220、v1.4.221、v1.4.241、v1.4.243 都更換了背景 terminal host;更新後舊終端機會留在舊 host 直到關閉,新功能只在新開的終端機生效。
- 使用 paired server 或 SSH 主機時,許多新功能(Native Chat、Remote Add Account、Ask mode)需要主機端 Orca 同步升級才會生效。
- v1.4.230 起,未設定過的 SSH 主機會把「Allow this host’s orca CLI to control Orca」遷移為關閉,原本依賴此功能的腳本需重新啟用。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 繁體中文 UI 可用 | Settings → Appearance → Language 下拉選單 | 出現「繁體中文」選項 | 版本低於 v1.4.244,先更新 |
| 權限模式存在 | Settings → Agents 找到 Agent permissions | 可選 Manual、Auto、Yolo | 版本低於 v1.4.232 |
| Remote Orca Servers 為單一清單 | Settings → Remote Orca Servers | 單一伺服器清單與 Add server 按鈕 | 版本低於 v1.4.233 |
| 某變更的原始出處 | gh release view v1.4.233 --repo stablyai/orca | Release Notes 中可找到對應敘述 | 依本表版本號逐一查閱,若找不到請以官方文件為準 |
第一章 Orca 概述與定位
本章建立全書最重要的心智模型:Orca 是什麼、不是什麼、為何這樣設計,以及它和你已經在用的工具之間是什麼關係。
1.1 Orca 是什麼
📌 查證狀態:官方文件明確記載|來源:What is Orca?、GitHub README
Orca 是一個桌面版 ADE(Agent Development Environment,代理開發環境),用來同時執行多個 AI coding agent。它的核心設計是:每一個任務都擁有自己的 git worktree、自己的 Agent 終端機、自己的瀏覽器分頁。如此一來,你可以把工作同時分派給 Claude Code、Codex、Cursor CLI 等不同 Agent,而不需要 stash、切換分支,也不會打斷工作節奏。
官方 README 的標語是「The AI Orchestrator for 100x builders」,並強調「Run Codex, ClaudeCode, OpenCode or Pi side-by-side — each in its own worktree, tracked in one place」。用白話說:
你不是在跟一個 AI 對話;你是在指揮一群 AI CLI,每個都在自己的 Worktree 裡工作,而你負責比較、審查與合併。
Orca 的組成要素
| 要素 | 說明 | 本書章節 |
|---|---|---|
| Parallel Worktrees | 每個任務一個真實的 git worktree,Agent 之間互不覆寫檔案 | 2.2、第十一章 |
| Agent 終端機與 Native Chat | 以終端機或結構化聊天介面執行 40 種以上預設整合的 Agent CLI,且可執行任何 CLI Agent | 第七章 |
| Terminal Splits | xterm.js 終端機、WebGL 繪製、可無限分割,scrollback 可跨重啟保存 | 2.5、第十二章 |
| 內建瀏覽器與 Design Mode | 每個 Worktree 有自己的 Chromium 分頁;點選 UI 元素即可把 HTML、CSS 與截圖送入 Prompt | 第十三章 |
| Review 與 Source Control | Diff 檢視、Annotate AI Diff、Commit、Push、PR、Checks 皆在應用程式內完成 | 第十四、十五章 |
| Orca CLI | orca worktree create、orca terminal send、orca snapshot 等指令,讓腳本與 Agent 也能驅動 Orca | 第十六章 |
| 遠端與行動端 | SSH Worktrees、Remote Orca Servers、Cloud VM、Mobile Companion | 第十八、十九章 |
一天的典型工作樣貌(教學示例)
- 早上從 Jira 議題直接建立三個 Worktree,分別交給 Claude Code、Codex 與 Cursor CLI 處理同一個 Bug。
- 用 Split 版面同時監看三個 Agent;其中一個停在權限詢問時,側邊欄出現琥珀色問號。
- 午餐時間用手機收到「Agent 完成」通知,回覆一句追加指示。
- 下午在 Diff 檢視中逐行留言,把意見送回表現最好的 Agent 修正,最後在 Orca 內 Commit、Push 並開 PR。
- 一鍵刪除另外兩個 Worktree,分支一併清除。
範例:用 GitHub CLI 確認專案基本資訊
gh repo view stablyai/orca --json name,description,licenseInfo,primaryLanguage✅ 驗證方式
執行上方指令。
預期輸出(示意):
{ "description": "Orca is the ADE for working with a fleet of parallel agents...", "licenseInfo": { "key": "mit", "name": "MIT License" }, "name": "orca", "primaryLanguage": { "name": "TypeScript" } }判讀:
licenseInfo.key應為mit、primaryLanguage應為 TypeScript。若描述文字與上方不同,代表官方已更新定位說明,請以最新內容為準並回報手冊維護者。
1.2 Orca 不是什麼
📌 查證狀態:官方文件明確記載|來源:What is Orca?
釐清「不是什麼」,比說明「是什麼」更能避免導入時的錯誤期待。官方明確列出三點,本書再補充兩點常見誤解。
| Orca 不是 | 官方說法與實際意義 | 對企業導入的影響 |
|---|---|---|
| 不是模型 | Orca 執行你已經在用的 Agent,採 BYO(Bring Your Own)訂閱:自備 Claude、Codex 或 OpenCode 等訂閱 | 成本與資料處理條款取決於各 Agent 供應商,而非 Orca;採購與法遵審查對象是 Agent 供應商 |
| 不是 git 的替代品 | 每個 Worktree 都是真實的 git worktree,隨時可 cd 進去使用一般 git 指令 | 既有分支策略、Code Review 與 CI 流程不必改變 |
| 不是代管 VPS 產品 | Orca 預設在你的桌面執行;遠端運算一律使用你掌控的機器與雲端帳號 | 資料落地位置由企業自行決定,沒有「Orca 雲」 |
| 不是 No-code 工具 | 官方明言 Orca 為「以寫程式為業、會讀 Diff、在意 Commit」的人設計 | 教育訓練對象應是工程師,而非業務使用者 |
| 不是 LLM Provider 切換器(本書補充) | Orca 管理的是「Agent CLI 的帳號與用量」,不是「把某次模型呼叫導向哪個 Provider」 | 若需要統一的 LLM Gateway,應在 Agent CLI 層設定,而非期待 Orca 處理 |
📌 查證狀態:最後一列為依官方說明延伸(教學推論)|來源:Usage & rate-limit tracking
❌ 常見錯誤
- 誤以為裝了 Orca 就能使用 AI——實際上仍需先安裝並登入至少一個 Agent CLI(例如
claude、codex)。 - 誤以為 Orca 會「重新實作」Agent——Orca 啟動的是你本機已安裝的 CLI,CLI 版本、設定與認證仍由你管理。
- 誤以為 Worktree 是 Orca 私有格式——它就是標準 git worktree,離開 Orca 也能完整使用。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Worktree 是真實 git worktree | 在 Orca 建立 Worktree 後,於主 checkout 執行 git worktree list | 列出 Orca 建立的 Worktree 路徑與分支 | 若未列出,代表建立失敗,見 2.2 與第二十九章 |
| Orca 不自帶模型 | 在未安裝任何 Agent CLI 的機器開啟 Orca 的 Agent 選單 | 無法啟動任何 Agent,或顯示需安裝 | 若能直接對話,請確認是否有其他 CLI 已安裝在 PATH |
| 遠端運算為自有機器 | 檢查 Settings → SSH 與 Settings → Remote Orca Servers | 只會出現你自行新增的主機 | 若出現不明主機,立即移除並撤銷存取連結(見 6.7) |
1.3 ADE 定位與設計哲學
📌 查證狀態:依官方說明延伸(教學推論)|來源:What is Orca?、Your first 3-agent session
傳統 IDE 的中心是「一個人在編輯器裡打字」;AI 優先 IDE 的中心是「一個人加一個 AI 助手」;ADE 的中心則是「一個人指揮多個 Agent,並對結果負責」。從官方文件可以歸納出 Orca 的五項設計哲學:
| 設計哲學 | 具體體現 | 你應該怎麼用 |
|---|---|---|
| Worktree 即沙箱 | 預設以完全自主旗標啟動 Agent,理由是 Worktree 可拋棄;最後再由人決定 cherry-pick 或丟棄 | 讓 Agent 在隔離環境放手做,但把把關點放在 Review,而非執行中 |
| BYO 一切 | 自備訂閱、自備機器、自備雲端帳號 | 沿用既有供應商合約與資料治理 |
| 人類審查不可省略 | Diff 檢視、Annotate AI Diff、Attribution 都是一級功能 | 把 Review 時間列入工時估算 |
| 任何 CLI Agent 都能跑 | Agent 選單只是在終端機啟動一個行程 | 不必為了 Orca 更換團隊熟悉的 Agent |
| 在哪裡跑都可以 | Local、SSH、Remote Orca Server、Cloud VM 可混用 | 依任務特性選擇運算位置(見 3.3) |
官方把整個工作流濃縮為一條主線:add → worktree → agent → split → diff → ship。
flowchart LR
A["加入 Repository"] --> B["建立 Worktree"]
B --> C["啟動 Agent"]
C --> D["Split 監看"]
D --> E["Diff 審查與 Annotate"]
E -->|"需要修正"| C
E -->|"通過"| F["Commit、Push、PR"]
F --> G["刪除或封存 Worktree"]如何閱讀此圖:從左到右是一個任務的完整生命週期。關鍵在「Diff 審查」節點的兩條出線——審查不通過時,意見會回到 Agent 再跑一輪;只有通過人工審查,才會進入 Commit 與 PR。整個 Orca 的功能都是為了讓這個迴圈更快、更安全。
⚠️ 注意事項:「Worktree 即沙箱」只隔離檔案,不隔離網路、憑證與本機系統。Agent 在 Yolo 模式下仍可讀取你家目錄中的金鑰、呼叫外部 API。企業環境請務必閱讀 2.4 與第二十八章的權限治理。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 理解主線流程 | 不看書,畫出 add → worktree → agent → split → diff → ship | 六個步驟順序正確,且能說明 Diff 的回饋迴圈 | 重讀本節並完成第五章實作 |
| 理解沙箱邊界 | 說明 Worktree 隔離了什麼、沒隔離什麼 | 能指出「檔案隔離、網路與憑證未隔離」 | 閱讀 2.4 權限預設與第二十八章 |
1.4 解決的問題與適用情境
📌 查證狀態:官方文件明確記載|來源:What is Orca?、Race three agents on the same task
傳統痛點與 Orca 的解法
| 痛點 | Orca 的處理方式 |
|---|---|
| 多個 Agent 同時修改同一份 repo,彼此覆寫 | 每個 Agent 一個 Worktree,檔案實體隔離 |
| 不知道哪個 Agent 適合這個任務,只能逐一重試 | 同一 Prompt 平行分派給多個 Agent,比較結果;官方指出「三個 Agent 一致處多半正確,分歧處就是難點」 |
| 開了十幾個終端機,不知道哪個 Agent 在等我 | 狀態圖示、Agent Dashboard、通知與 Agents Feed |
| AI 產出的 Diff 很難認真審查 | 內建 Diff 檢視、逐行留言並送回 Agent |
| 筆電闔上,Agent 就停了 | SSH Worktrees、Remote Orca Servers、Cloud VM、Mobile Companion |
| UI 問題要截圖、描述位置,溝通成本高 | Design Mode 直接點選元素送入 Prompt |
適合的情境
- 已經在使用至少一種 Agent CLI,想「規模化」而不是「換掉」它。
- 任務可以拆解為邊界清楚、可獨立驗證的單位,例如修 Bug、補測試、局部重構、文件產生。
- 需要多角度探索的設計題,例如同時看三種重構切法。
- 舊系統盤點:讓多個 Agent 分頭閱讀不同模組(見第二十四章)。
需謹慎評估的情境
- 高度耦合、需要單一上下文連續推理的核心重構:平行分派會提高合併成本。
- 無法讓程式碼離開內網的環境:Agent CLI 會把程式碼片段送往模型供應商,須先完成資料分級與供應商審查。
- 要求原廠 SLA 的高監理環境:Orca 為開源、快速迭代的專案,多項功能仍標示 Beta 或 Experimental。
企業導入時的治理考量
| 面向 | 考量重點 |
|---|---|
| 權限 | Agent 預設以完全自主模式啟動,需決定組織的權限基準(見 6.9) |
| 稽核 | Worktree 與分支是真實 git 物件,可沿用既有 Commit、PR 稽核軌跡 |
| 資安 | 程式碼經由 Agent CLI 送往模型供應商;Orca 本身的 Telemetry 為匿名且可關閉(見 3.5) |
| 成本 | 平行 Agent 會倍增 Token 用量;用量追蹤見第八章,成本治理見第三十章 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 任務適合平行化 | 用「可獨立驗證、邊界清楚、彼此無依賴」三條件檢查候選任務 | 三條件皆符合 | 先拆解任務,或改用單一 Agent |
| 資料可外送 | 對照組織資料分級政策檢查目標 repo | 該 repo 允許送往所選 Agent 供應商 | 停止導入該 repo,改用允許的供應商或內部模型 |
| 治理考量已盤點 | 以上表四個面向各寫下一條組織決策 | 有書面決策 | 參考第二十八、三十一章補齊 |
1.5 與同類工具的定位差異
📌 查證狀態:依官方說明延伸(教學推論)|來源:Supported agents、GitHub README
比較 Orca 時最常見的錯誤,是把「Orca 包裝的對象」和「與 Orca 同層競爭的工具」混為一談。請先分清兩個層次:
flowchart TB
subgraph L1["工作介面層(與 Orca 同層)"]
O["Orca(ADE)"]
CU["Cursor 等 AI 優先 IDE"]
VS["VS Code 加 Copilot 擴充"]
WA["Warp 等 AI 終端機"]
end
subgraph L2["Agent CLI 層(被 Orca 啟動與管理)"]
CC["Claude Code"]
CX["Codex"]
CR["Cursor CLI"]
GH["GitHub Copilot CLI"]
OT["其他 40 種以上 CLI"]
end
O --> CC
O --> CX
O --> CR
O --> GH
O --> OT如何閱讀此圖:上層是「工程師每天盯著看的工作介面」,Orca 與 Cursor、VS Code、Warp 在這一層有定位重疊;下層是「真正寫程式的 Agent CLI」,它們是 Orca 啟動、隔離與比較的執行單元,而不是競爭者。注意 Cursor 同時出現在兩層:Cursor IDE 是同層工具,Cursor CLI 則可被 Orca 管理。
定位比較(概念性,非逐項功能核對)
| 工具類型 | 代表 | 核心模式 | 與 Orca 的關係 |
|---|---|---|---|
| ADE | Orca | 一人指揮多個 Agent、每任務一個 Worktree | 本書主角 |
| AI 優先 IDE | Cursor、Windsurf | 一人加一個深度整合的 AI | 可並存;可從 Orca 的 Open in 選單用其他編輯器開啟 Worktree |
| 通用編輯器加擴充 | VS Code 加 GitHub Copilot | 編輯器為主、AI 為輔 | 可並存;SSH Worktree 可用 VS Code Remote-SSH 開啟 |
| AI 終端機 | Warp | 取代終端機本身 | Orca 可匯入 Warp 主題;定位為終端機之上的多 Agent 管理層 |
| Agent CLI | Claude Code、Codex、Gemini、OpenCode | 單一終端機 Agent | 被 Orca 包裝與管理 |
| 自行組裝 | tmux 加 git worktree 腳本 | 手動管理 | Orca 把這套做法產品化,並加上狀態、Review 與遠端能力 |
選型判斷題(教學示例)
| 你的需求 | 建議 |
|---|---|
| 一人專注開發單一功能,偏好編輯器內補全 | AI 優先 IDE 即可,Orca 非必要 |
| 想同時跑三個 Agent 比較結果 | Orca |
| Agent 要長時間在遠端機器跑,並用手機監看 | Orca 搭配 Remote Orca Server |
| 團隊已標準化 VS Code 與 Copilot | 保留 VS Code 作為編輯器,評估以 Orca 管理 Copilot CLI 等平行任務 |
完整比較表與評分見第三十四章。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 團隊 Agent 是否被支援 | 對照 Supported agents 與 README 的 Supported Agents 清單 | 團隊常用 CLI 在清單中,或確認可作為「任何 CLI Agent」執行 | 未列名者仍可在終端機手動啟動,但無狀態偵測與用量追蹤 |
| 能區分兩個層次 | 用自己的話解釋 Cursor IDE 與 Cursor CLI 和 Orca 的關係 | 能指出一個同層、一個被管理 | 重讀本節圖說 |
| 選型結論有依據 | 針對團隊情境填寫上方選型判斷題 | 每個結論對應明確需求 | 參考第三十四章完整比較表 |
1.6 本章 Review 與驗證清單
- 能用一句話說明 Orca 是「每任務一個 Worktree、一個 Agent 終端機、一個瀏覽器分頁」的桌面 ADE
- 能列出官方明確的三個「不是」:不是模型、不是 git 替代品、不是代管 VPS
- 能說明「Worktree 即沙箱」只隔離檔案,不隔離網路與憑證
- 能畫出 add → worktree → agent → split → diff → ship 主線,並說明 Diff 回饋迴圈
- 已用三條件(可獨立驗證、邊界清楚、無依賴)檢查至少一個候選任務
- 能區分「工作介面層」與「Agent CLI 層」,並正確歸類 Cursor IDE 與 Cursor CLI
- 已執行
gh repo view stablyai/orca確認授權為 MIT
第二章 核心概念模型
Orca 的介面元素很多,但底層只有幾個核心概念:Project、Worktree、Agent Session,以及承載它們的 Tabs 與 Panes。本章逐一說明這些概念的關係,並示範如何用 git 與 Orca CLI 驗證你看到的畫面。
classDiagram
class Project {
+String name
+String baseRef
+String repoPath
}
class Worktree {
+String branch
+String startFromRef
+String path
+String runOn
}
class AgentSession {
+String agent
+String state
+String sessionId
}
class Tab {
+String type
+String orcaTabId
}
Project "1" --> "many" Worktree : 擁有
Worktree "1" --> "many" Tab : 版面包含
Tab "1" --> "0..1" AgentSession : 執行如何閱讀此圖:一個 Project(對應一個 git repo)擁有多個 Worktree;每個 Worktree 有自己的 Tabs 版面;終端機或 Chat 類型的 Tab 內可執行一個 Agent Session。Worktree 的 runOn 屬性決定它在本機、SSH 主機、Remote Orca Server 或 Cloud VM 上執行。
2.1 Project 與 Repository
📌 查證狀態:官方文件明確記載|來源:Worktrees、Orca CLI reference
Project 是 Orca 側邊欄的頂層單位,通常對應一個 git repository。加入 repo 時,Orca 讀取它的 git 狀態,並把預設分支(通常是 origin/main)設為 base ref——之後每個新 Worktree 預設都從這個 ref 分出。
| 概念 | 說明 |
|---|---|
| Base ref | Repo 層級的預設起點,可在 Settings → Repository 或用 orca repo set-base-ref 修改 |
| Project group | 匯入包含多個 git repo 的上層資料夾時,可把這些 repo 群組在一個 Project group 下 |
| Folder workspace | Project group 層級的類 Worktree 入口,綁定其中一個 repo 作為 Task 來源,適合跨 repo 的功能開發 |
| Primary checkout | 你原本 clone 下來的主工作目錄;Shared Paths 與 orca.yaml 都以它為來源 |
操作步驟(UI)
- 點選側邊欄頂端的 Create 按鈕(v1.4.199 起,「New workspace」與「Add project」合併為單一 Create 按鈕),或在 Project 下拉選單選 Add a new project。
- 選擇本機已存在的 git checkout,或輸入 clone URL。
- 若選擇的資料夾內含多個 repo,選擇「分別匯入」或「群組為一個 Project group」。
- 加入後,到 Settings → Repository 確認 base ref 是否正確。
範例:以 CLI 管理 Project
# 列出 Orca 已知的 repo 與其 id
orca repo list --json
# 以絕對路徑加入 repo
orca repo add --path /Users/alice/src/payment-api --json
# 把 base ref 改為 origin/develop
orca repo set-base-ref --repo id:<repoId> --ref origin/develop --json⚠️ 注意事項:加入 repo 前先在主 checkout 執行 git fetch origin,並確認沒有未提交的重大變更。Base ref 若指向尚未 fetch 的遠端分支,建立 Worktree 會失敗。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Repo 已加入 | orca repo list --json | 輸出包含該 repo 路徑與 id | 確認 Orca CLI 已註冊(見 4.8) |
| Base ref 正確 | orca repo show --repo id:<repoId> --json | base ref 欄位為預期值,例如 origin/main | 執行 orca repo set-base-ref 修正 |
| 遠端已 fetch | 在主 checkout 執行 git branch -r | 列出 origin/main 等遠端分支 | 執行 git fetch origin |
2.2 Worktree 模型與生命週期
📌 查證狀態:官方文件明確記載|來源:Worktrees
Orca 是 worktree-native 的工具:它不在同一個 checkout 上切分支或 stash,而是讓每個任務擁有一份獨立的磁碟副本。git worktree 讓多個工作目錄共享同一個 .git 物件庫,但各自擁有獨立的檔案樹、分支與索引,這正是平行 Agent 能安全運作的基礎。
Worktree 的四個屬性
| 屬性 | 說明 |
|---|---|
| Start-from ref | 這個 Worktree 從哪裡分出:base ref、其他本機分支(適合疊在審查中的 PR 上)、特定 commit SHA、或既有遠端分支 |
| 分支 | 預設由 Workspace 名稱、或連結的 GitHub PR、Linear 或 Jira 議題、GitLab MR 推導;可在 Advanced 抽屜手動指定 |
| 磁碟目錄 | 每個 Worktree 自己的檔案;建立時可選擇位置(v1.4.187) |
| Run on | 執行位置:Local、SSH 主機、Remote Orca Server 或 Cloud VM recipe |
生命週期
stateDiagram-v2
state "建立中" as Creating
state "工作中" as Working
state "審查中" as Reviewing
state "已出貨" as Shipped
state "休眠" as Sleeping
state "封存" as Archived
state "已刪除" as Deleted
[*] --> Creating : Create 對話框送出
Creating --> Working : 背景 fetch 與 worktree add 完成
Creating --> [*] : 失敗或取消
Working --> Reviewing : Agent 完成並開啟 Diff
Reviewing --> Working : Annotate 意見送回 Agent
Reviewing --> Shipped : Commit、Push、PR
Working --> Sleeping : 手動 Sleep 或 Hibernation
Sleeping --> Working : 重新開啟
Shipped --> Archived : 封存保留
Shipped --> Deleted : 刪除目錄與分支
Archived --> Deleted : 清理
Deleted --> [*]如何閱讀此圖:每個方框是 Worktree 的一種狀態,箭頭上的文字是觸發條件。最重要的是 Working 與 Reviewing 之間的雙向箭頭——這是「AI 產出、人類審查、意見回饋」的迴圈。Deleted 會同時移除目錄與分支(需確認);若分支含未合併的 commit,Orca 會保留分支並提示你審查(Preserved branches)。
各階段重點
| 階段 | 官方行為 | 實務建議 |
|---|---|---|
| Create | 送出後對話框立即關閉,git fetch 與 git worktree add 在背景進行;側邊欄出現進度列,失敗時可 Retry | 大型 repo 建立時可先切去其他 Worktree 工作 |
| Work | Agent 終端機、編輯器、瀏覽器分頁都綁定在此 Worktree | 一個 Worktree 只處理一個可驗收的任務 |
| Review | Diff 以 start-from ref 為基準;可 Annotate AI Diff 並查看 Attribution | 審查前先執行測試,見第二十二章 |
| Ship | Commit、Push、開 PR、等待 Checks 皆可在應用程式內完成 | PR 描述需包含驗證證據 |
| Archive 或 Delete | 一鍵移除 Worktree 與分支;無法完成時可 Force Delete | 刪除前確認分支已合併或已推送 |
操作步驟:建立 Worktree
- 在側邊欄 Project 列點選 +,或使用 Create 按鈕。
- 輸入任務名稱,例如
fix-login-race(留白則 Orca 以海洋生物命名);可貼上 GitHub PR、Linear、Jira 或 GitLab 連結以連結任務。 - 在 Branch from 選擇 start-from ref。
- 在 Run on 選擇執行位置(預設 Local)。
- 選擇 Agent 或 Blank Terminal;可勾選 Set as default 記住此選擇。
- 需要指定分支名稱時展開 Advanced,填入 Branch name;也可在此設定 Parent workspace(僅影響側邊欄巢狀顯示,不影響 git 歷史)。
範例:以 CLI 建立與移除 Worktree
# 建立 Worktree,連結 GitHub issue #123,並以 Claude Code 為第一個分頁
orca worktree create --repo id:<repoId> --name fix-login-race --issue 123 --agent claude --json
# 指定分支名稱(v1.4.244 起支援 --branch)
orca worktree create --repo id:<repoId> --name fix-login-race --branch bugfix/login-race --json
# 列出所有 Worktree
orca worktree ps --json
# 強制移除指定 Worktree
orca worktree rm --worktree id:<worktreeId> --force --json使用一般 git 也完全可以
cd /path/to/worktree
git status
git rebase origin/main
git cherry-pick <sha>Orca 會在下一次重新整理時偵測這些變更。你用 git worktree add 自行建立的 Worktree 預設不會出現在側邊欄,可透過 Non-Orca worktrees 對話框選擇 Show;用 git worktree remove 移除的 Worktree,Orca 也會自動清理其狀態。
❌ 常見錯誤
- 在同一個 Worktree 先後交辦多個不相關任務,導致 Diff 混雜、難以審查。
- 從未 fetch 的遠端分支建立 Worktree,導致建立失敗;先執行
git fetch origin。 - 批次刪除後忽略「Review N Branches」提示,誤以為分支已全部刪除。
✅ 驗證方式
在主 checkout 執行:
git worktree list git branch --list "*login*"預期輸出(示意):
/Users/alice/src/payment-api a1b2c3d [main] /Users/alice/orca/worktrees/fix-login-race d4e5f6a [fix-login-race] fix-login-race判讀:第一列是主 checkout,第二列是 Orca 建立的 Worktree;分支名稱應與你在 Create 對話框輸入或推導的名稱一致。刪除 Worktree 後再執行一次,該列與分支都應消失;若分支仍在,代表它含未合併 commit 而被保留,請依提示審查。
2.3 orca.yaml 與 worktreeinclude 共用檔案
📌 查證狀態:官方文件明確記載|來源:Worktrees、Agent hooks & memory、Settings reference
新建立的 Worktree 是一份乾淨的 checkout:所有被 gitignore 的東西——node_modules、快取、.env 等本機機密——都不存在。Orca 提供三種互補機制來補齊這個缺口。
| 機制 | 設定位置 | 行為 | 適用對象 | 由誰維護 |
|---|---|---|---|---|
| Worktree Shared Paths | Settings → Repository(每位使用者、每個 repo) | 從主 checkout 實體化到每個新 Worktree;macOS 盡可能用 APFS clone-copy,否則用 symlink | 個人環境特有的路徑 | 個人 |
worktree.sharedDirectories | repo 根目錄的 orca.yaml(進版控) | 以 symlink 或共享方式連結,不複製 | 大型、可重建的目錄,例如 node_modules、.cache | 團隊 |
.worktreeinclude | repo 根目錄(進版控) | 複製到每個新 Worktree,每個 Worktree 擁有自己的副本 | 小型、每個 Worktree 可能各自修改的檔案,例如 .env、.vscode/settings.json | 團隊 |
規則重點
orca.yaml的共享目錄會加到個人的 Worktree Shared Paths 清單,不會取代它。sharedDirectories的項目必須在主 checkout 中以目錄形式存在,且必須被 gitignore;被追蹤或不存在的路徑會被略過。.worktreeinclude允許空白行與#註解,目前只支援字面路徑;glob 與否定規則(!)會被略過並顯示警告。被追蹤、不存在或未被 gitignore 的路徑不會被複製。- 已經被共享或連結的路徑,不會再從
.worktreeinclude重複複製。
範例:Node.js 專案的標準設定
# orca.yaml(repo 根目錄)
worktree:
sharedDirectories:
- node_modules
- .cache# .worktreeinclude(repo 根目錄)
# 每個 Worktree 各自擁有一份副本,避免 Agent 修改後互相影響
.env
.env.local
.vscode/settings.json# .gitignore 必須涵蓋上述路徑,否則不會生效
node_modules/
.cache/
.env
.env.local
.vscode/settings.json搭配 Worktree setup hooks
若某些環境無法用共享解決(例如 Python 虛擬環境需要依各 Worktree 重新建立),可在 Settings → Repository → Hooks 設定建立 Worktree 後自動執行的指令,例如:
pnpm install --frozen-lockfile
direnv allow以 CLI 建立 Worktree 時,可用 --setup run、--setup skip 或 --setup inherit(依 repo 政策)控制是否執行這些 hooks:
orca worktree create --name review-api --agent claude --setup run --json關於 orca.yaml 的其他用途:orca.yaml 也承載 Cloud VM 每工作區環境的 recipe(environmentRecipes 項目)。官方建議透過 orca-per-workspace-env skill 讓 Agent 產生並以 doctor 驗證,而不是手寫;詳見第十八章 18.6。Recipe 只有在 environmentRecipes 位於主 checkout 的 orca.yaml 時,才會出現在建立 Worktree 的選單中。
⚠️ 注意事項
sharedDirectories是共享而非複製:Agent A 在 Worktree 中執行npm install some-pkg,會影響所有共用該node_modules的 Worktree。若平行 Agent 會修改相依套件,請改用 setup hooks 各自安裝。.env用.worktreeinclude複製時,機密會出現在每個 Worktree 目錄中,Agent 也讀得到。企業環境應改用開發專用、低權限的憑證(見第二十八章)。
範例 Prompt:請 Agent 為 repo 產生共享設定
請檢查這個 repo 的 .gitignore 與目錄結構,為 Orca 產生 orca.yaml 的 worktree.sharedDirectories 與 .worktreeinclude。
規則:
1. 只有大型、可重建、且已被 gitignore 的「目錄」才放 sharedDirectories。
2. 每個 Worktree 需要獨立副本的小檔案(例如 .env)放 .worktreeinclude,只能用字面路徑,不可用 glob。
3. 不得修改 .gitignore 以外的任何檔案;若需修改 .gitignore,請另外列出理由。
4. 最後輸出 git diff --stat 與每個路徑是否被 gitignore 的檢查結果(git check-ignore -v)。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
-
git diff --stat只包含orca.yaml、.worktreeinclude,以及有正當理由的.gitignore -
.worktreeinclude內沒有*、**、!等 glob 或否定語法 - 每個路徑都附上
git check-ignore -v的輸出,證明已被 gitignore -
sharedDirectories中沒有任何 Agent 可能各自修改的目錄 - 沒有把正式環境機密列入
.worktreeinclude
✅ 驗證方式
確認路徑已被 gitignore:
git check-ignore -v node_modules .cache .env .env.local .vscode/settings.json建立一個新 Worktree,進入其目錄檢查連結與複製結果(macOS 或 Linux):
ls -la node_modules .envWindows PowerShell:
Get-Item node_modules, .env | Select-Object Name, LinkType, Target預期結果:
node_modules顯示為 symlink 或連結(LinkType 有值,或 macOS 為 clone-copy 後的一般目錄);.env為一般檔案(LinkType 為空)。判讀:若
.env不存在,檢查它是否被 gitignore、是否存在於主 checkout、以及.worktreeinclude是否使用了 glob。若node_modules未連結,檢查它在主 checkout 是否存在且為目錄。
2.4 Agent 與 Session
📌 查證狀態:官方文件明確記載|來源:Agents & sessions、Supported agents、Chat UI
Agent Session 的官方定義是:一個 CLI Agent,在一個 Worktree 的一個終端機中執行。Orca 追蹤每個 Session 的生命週期,讓你不必逐一點開分頁就知道誰在工作、誰在等你。若開啟 Chat UI,支援的 Agent 會改以結構化 Native Chat 分頁呈現,但概念相同。
狀態指示
| 圖示 | 意義 | 你該做什麼 |
|---|---|---|
| 旋轉圖示 | 工作中 | 等待,或切去做其他事 |
| 琥珀色問號 | 等你回應(權限或需要輸入);側邊欄「Needs You」計數使用同一圖示 | 優先處理 |
| 翠綠勾號或圓點 | 完成或安靜的活躍狀態 | 前往審查 Diff |
| 紅點 | 被阻擋、中斷或失敗 | 檢查終端機輸出,必要時用 Restart chip |
| 灰點 | 閒置 | 視需要喚醒或關閉 |
| 無圖示 | 一般 shell,非 Orca 辨識的 Agent | 若應為 Agent,改由 Agent 選單啟動 |
狀態來源是終端機的 OSC 標題序列與 Agent hooks。若看不到狀態,最常見原因是你在終端機手動輸入了 Agent 指令,而不是從 Agent 選單啟動。
Session 生命週期
- Launch:從 Agent 選單選擇,Orca 啟動 CLI 行程。
- Work:OSC 標題更新狀態,輸出可搜尋、複製。
- Idle:Orca 偵測到「工作中 → 閒置」轉換並發出 Agent 完成通知。
- Exit:行程結束後分頁出現 Restart chip,一鍵以相同工作目錄重新啟動(Codex 會保留目前帳號)。
⚠️ 權限預設:企業導入第一個必須決定的事
Orca 預設以各 Agent 的完全自主旗標啟動:Claude 使用 --dangerously-skip-permissions、Codex 使用 --dangerously-bypass-approvals-and-sandbox、Gemini、Cursor、GitHub Copilot 等使用 --yolo。官方理由是 Worktree 可拋棄,Agent 在自己的 checkout 中實驗,最後仍由人決定是否採用 Diff。
v1.4.232 起可在 Settings → Agents → Agent permissions 為新 Session 選擇:
| 模式 | 行為 | 適用情境 |
|---|---|---|
| Manual | 各 Agent 保留自己的逐項核准提示 | 高監理環境、含正式環境憑證的機器 |
| Auto | 支援的 Agent(Claude、Claude Agent Teams、Codex)自行核准例行動作;不支援者用 Other agents 設定 Manual 或 Yolo | 一般企業開發的平衡選項 |
| Yolo | 完全自主,不詢問 | 隔離良好的拋棄式環境,例如 Cloud VM |
既有 Chat 會保留它開始時的模式;已自訂啟動參數的 Agent 不會被全域切換覆蓋。
範例:查看某個 Agent 實際以哪些參數啟動
macOS 或 Linux:
ps -eo pid,args | grep -E "claude|codex" | grep -v grepWindows PowerShell:
Get-CimInstance Win32_Process -Filter "Name like '%claude%' or Name like '%codex%'" | Select-Object ProcessId, CommandLineSession 與 Session History 的關係:Agent CLI 會把對話紀錄寫在自己的目錄(例如 ~/.codex/sessions、~/.claude)。Orca 掃描這些紀錄,在右側邊欄 Agents 分頁的 Agent Session History 中列出,可 Resume 或 Hand Off to Another Agent,詳見第九章。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 狀態偵測正常 | 從 Agent 選單啟動 Claude Code 並送出一個短任務 | 分頁依序顯示旋轉圖示、完成勾號 | 確認 Settings → Agents → Agent status hooks 已開啟,或執行 orca agent hooks status --json |
| 權限模式符合政策 | 用上方 ps 或 Get-CimInstance 指令檢查行程參數 | Manual 模式下不應出現 --dangerously-skip-permissions 等旗標 | 檢查該 Agent 是否有自訂啟動參數覆蓋了全域設定 |
| Restart chip 可用 | 在 Agent 終端機中結束 Agent 行程 | 分頁出現 Restart chip,點擊後於相同目錄重新啟動 | 檢查 Agent CLI 是否在 PATH(Settings → Agents) |
2.5 Tabs Panes 與 Split 版面
📌 查證狀態:官方文件明確記載|來源:Tabs, panes & split layouts、Terminal
Orca 的版面系統是為了「同時看多個 Agent 工作」而設計:Tab 裝一個東西(終端機、編輯器、瀏覽器、Diff、PR),Tab 組成 Tab group,Tab group 可以分割成巢狀版面。
操作重點
- 把 Tab 拖到 Pane 的右緣:左右分割;拖到下緣:上下分割。分割可巢狀。
- 任何類型都可以混排,例如左邊 Agent 終端機、右上 Diff、右下瀏覽器。
- 終端機 Tab 內也能再分割:使用 Tab 選單的 Split terminal right 或 Split terminal down。
- Pinned boundaries:分割線位置依 Worktree 保存,調整視窗大小不會打亂版面。
- 每個 Worktree 擁有自己的版面;切換 Worktree 會整個切換 Pane tree。
- 在 Tab 上按右鍵選 Copy Tab ID,可取得類似
orcaTabId: abc123的穩定參照,方便告訴 Agent 去看哪個分頁。
預設快捷鍵
| 動作 | macOS | Windows 與 Linux |
|---|---|---|
| 新終端機 Tab | Cmd+T | Ctrl+T |
| 向右分割 | Cmd+\ | Ctrl+\ |
| 向下分割 | Cmd+Shift+\ | Ctrl+Shift+\ |
| 下一個或上一個 Tab(所有類型) | Cmd+Shift+] 或 Cmd+Shift+[ | Ctrl+Shift+] 或 Ctrl+Shift+[ |
| 下一個或上一個 Tab(同類型) | Cmd+Option+] 或 Cmd+Option+[ | Ctrl+Alt+] 或 Ctrl+Alt+[ |
| 前一個最近使用的 Tab | Ctrl+Tab | Ctrl+Tab |
| 關閉 Worktree 內所有編輯器 Tab | Cmd+Option+W | Ctrl+Alt+W |
📌 查證狀態:Windows 與 Linux 的新終端機與分割快捷鍵為依官方說明延伸(教學推論),官方文件以 macOS 鍵位為主;請以 Settings → Shortcuts 實際顯示為準|來源:Terminal
所有快捷鍵都可在 Settings → Shortcuts 重新設定;既有安裝的自訂值保存在 ~/.orca/keybindings.json。
範例:監看三個 Agent 的推薦版面(教學示例)
┌──────────────────────┬──────────────────────┐
│ Agent A 終端機 │ Agent B 終端機 │
├──────────────────────┼──────────────────────┤
│ Agent C 終端機 │ 共用瀏覽器或 Diff │
└──────────────────────┴──────────────────────┘✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 可建立巢狀分割 | 將一個 Tab 拖到右緣,再把另一個拖到右側 Pane 的下緣 | 形成左一、右二的版面 | 確認拖曳到 Pane 邊緣的高亮區域 |
| 版面依 Worktree 保存 | 切換到另一個 Worktree 再切回 | 版面、分割線位置與聚焦 Tab 完全還原 | 見 2.7 Session Restore |
| 自訂快捷鍵已保存 | 修改一個快捷鍵後檢查 ~/.orca/keybindings.json | 檔案中出現對應覆寫值 | 確認修改的是 Settings → Shortcuts |
2.6 Quick Open 與 Jump Palette
📌 查證狀態:官方文件明確記載|來源:Quick Open & Jump Palette
當 Worktree 超過五個,導覽就會變成瓶頸。Orca 提供三種鍵盤優先的導覽工具:
| 工具 | 快捷鍵 | 範圍 | 重點功能 |
|---|---|---|---|
| Quick Open | Cmd-P(Windows 與 Linux 為 Ctrl-P) | 目前 Worktree 的檔案 | 依最近使用與比對分數排序;被 gitignore 的檔案作為第二輪結果出現 |
| New-tab omnibox | Tab 列上的 + | 開啟中的 Tab、檔案、URL、Agent、瀏覽歷史 | 輸入多字詞會優先網頁搜尋;前綴 ? 直接搜尋 |
| Worktree Jump Palette | Cmd-J(Windows 與 Linux 為 Ctrl-J) | 所有 Worktree、所有 Tab | 空白查詢時列出 Recent Chats & Terminals 與 Recent Worktrees;按 Tab 可篩選主機與專案 |
Jump Palette 實用技巧
- 空白查詢時,最近的 Agent 與終端機 Session 依「需要你 → 完成 → 閒置」排序;Cmd-1 至 Cmd-6(Windows 與 Linux 為 Ctrl-1 至 Ctrl-6)直接跳到前幾列。
- 可用 PR 編號(
#123)或 GitLab MR 編號(!123)找到對應 Worktree。 - Shift-Enter 在新的分割中開啟 Worktree,而非取代目前 Pane。
- 查詢不到時會出現 Create worktree 列,以輸入文字為名稱直接建立。
- 被側邊欄篩選隱藏的 Worktree,只要輸入查詢仍可找到。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Jump Palette 可跨 Worktree | 按 Cmd-J 或 Ctrl-J,輸入另一個 Worktree 名稱片段 | 該 Worktree 出現在結果中,Enter 後切換過去 | 檢查 Settings → Shortcuts 是否被重新設定 |
| 優先處理需要你的 Session | 讓一個 Agent 停在權限詢問,打開空白 Jump Palette | 該 Session 排在 Recent Chats & Terminals 第一列 | 確認狀態 hooks 已啟用 |
| Quick Open 可找到 gitignore 檔案 | Cmd-P 或 Ctrl-P 輸入 .env | .env 出現在追蹤檔案之後 | 確認檔案確實存在於此 Worktree |
2.7 Session Restore
📌 查證狀態:官方文件明確記載|來源:Session restore
關閉 Orca 再重新開啟時,Orca 會還原整個工作現場。關鍵在於:PTY 由背景 daemon 持有,所以關閉應用程式視窗不會殺死正在執行的 Agent。
| 會還原 | 說明 |
|---|---|
| 開啟中的 Worktree | 側邊欄中所有開啟的 Worktree |
| Tabs 與分割 | 每個 Worktree 的版面與聚焦的 Tab |
| 執行中的 Agent 行程 | Agent 在 Orca 關閉期間持續執行,下次啟動時 warm-reattach |
| 終端機 scrollback | 包含 Orca 關閉期間產生的輸出 |
| 聚焦的 Worktree 與 Tab | 回到你離開時的畫面 |
| 情境 | daemon 是否存活 | 結果 |
|---|---|---|
| Cmd-Q 正常結束 | 存活 | Agent 在背景繼續工作 |
| 自動更新重新啟動 | 存活 | Agent 不受影響 |
| Orca 應用程式當機 | 存活 | 下次啟動重新連上 |
| 主機重開機、OS 更新、kernel panic、強制斷電 | 終止 | 版面與最後保存的 scrollback 會還原,但 Agent 行程已結束,需在 Tab 中重新執行 |
⚠️ 注意事項
- 沒有「以全新 Session 開啟」模式;Orca 永遠會還原。想要乾淨狀態,請在結束前明確關閉 Worktree。
- 企業筆電常在夜間自動套用 OS 更新並重開機,長時間任務應移到 Remote Orca Server 或 SSH 主機(見第十八章)。
- 背景 daemon 也代表「關掉視窗不等於停止 Agent」。若要確保 Agent 停止(例如發現它在做錯事),請在終端機中中斷或關閉該 Tab,而不是只關閉視窗。
✅ 驗證方式
在一個 Worktree 中啟動 Agent,請它執行一個約需兩分鐘的任務,例如:
請執行完整測試套件,並在每完成一個測試檔案時輸出一行進度。任務進行中按 Cmd-Q(Windows 與 Linux 從選單結束應用程式)。
等待 30 秒後重新開啟 Orca。
預期結果:同一個 Worktree 與版面重新出現,scrollback 中可看到關閉期間產生的進度輸出,Agent 仍在工作或已完成。
判讀:若 Agent 已消失但版面仍在,代表 daemon 未存活(例如期間曾重開機),請檢查 Help → Open Logs 中的紀錄並見第二十九章。
2.8 本章 Review 與驗證清單
- 能說明 Project、Worktree、Tab、Agent Session 四者的從屬關係
- 已用
orca repo list --json或 Settings → Repository 確認 base ref - 已建立一個 Worktree,並用
git worktree list確認其路徑與分支 - 能說明 Worktree 生命週期中 Working 與 Reviewing 之間的回饋迴圈
- 能區分 Worktree Shared Paths、
worktree.sharedDirectories、.worktreeinclude的差異(共享或複製、個人或團隊) - 已用
git check-ignore -v驗證共享路徑皆被 gitignore - 能說出 Orca 預設的 Agent 權限旗標,以及 Manual、Auto、Yolo 的差異
- 已建立一個「左一、右二」的巢狀分割版面
- 會使用 Jump Palette 的 Shift-Enter 與 Tab 篩選
- 已實測 Cmd-Q 後 Agent 繼續執行,並理解重開機會終止 Agent 行程
第三章 系統架構
本章從「行程、執行位置、資料存放、對外連線」四個角度拆解 Orca,目的是讓資安、IT 與平台團隊能回答三個問題:程式碼在哪裡執行?資料存在哪裡?哪些資料會離開這台機器?
📌 查證狀態:本章架構圖整合官方文件中分散的元件描述,元件間的連線方式為依官方說明延伸(教學推論),並非官方發布的架構圖|來源:Session restore、Remote servers、Agents & sessions
3.1 整體架構與元件
flowchart LR
subgraph Desktop["使用者桌機"]
UI["Orca 桌面應用程式<br/>Electron 介面"]
Daemon["背景終端機 daemon<br/>持有 PTY"]
CLI["Orca CLI<br/>orca 或 orca-ide"]
Store[("本機設定與狀態<br/>userData、~/.orca")]
subgraph Agents["Agent CLI 行程"]
Claude["Claude Code"]
Codex["Codex"]
Other["其他 CLI Agent"]
end
end
subgraph Remote["遠端執行位置(選用)"]
SSH["SSH 主機<br/>受管 Orca server"]
ROS["Remote Orca Server<br/>orca serve"]
VM["Cloud VM<br/>environment recipe"]
end
subgraph External["外部服務"]
LLM["模型供應商 API"]
GH["GitHub、GitLab、<br/>Linear、Jira"]
PH["PostHog 匿名遙測"]
end
UI --> Daemon
CLI --> UI
Daemon --> Agents
UI --> Store
UI --> SSH
UI --> ROS
UI --> VM
Agents --> LLM
UI --> GH
UI --> PH如何閱讀此圖:左側是一台使用者桌機上的元件。Orca 介面本身不直接持有終端機,而是透過背景 daemon 管理 PTY,這就是關閉視窗後 Agent 仍能繼續執行的原因。Agent CLI 行程由 daemon 啟動,它們自己連線到模型供應商——Orca 不代理模型流量。右上的遠端執行位置是選用的;右下的外部服務中,PostHog 遙測可完全關閉(見 3.5)。
元件清單
| 元件 | 角色 | 可觀察方式 |
|---|---|---|
| Orca 桌面應用程式 | Electron 介面:側邊欄、Tabs、編輯器、Diff、瀏覽器、設定 | 作業系統的工作管理員或活動監視器 |
| 背景終端機 daemon | 持有所有 PTY,讓 Agent 在應用程式關閉或更新時繼續執行 | 狀態列 Resource Manager 的 daemon 控制項 |
| Agent CLI 行程 | 實際執行 Agent 的程式,例如 claude、codex;Orca 不內建模型 | Resource Manager 的 Sessions 與 PTY 清單 |
| Codex 專屬伺服器 | 預設每個 Codex Tab 執行自己的 Codex server,以隔離帳號與狀態 | Settings → Agents 的 Codex server 選項 |
| Orca CLI | 讓 Agent 或腳本控制 Orca:建立 Worktree、讀取終端機、操作瀏覽器 | orca status --json |
| 受管遠端伺服器 | SSH 主機或 Remote Orca Server 上執行的 Orca server,持有遠端 PTY 與檔案操作 | Settings → SSH 的 managed servers 清單 |
💡 小技巧:狀態列的 Resource Manager 會顯示 CPU、記憶體、Session 數、PTY 清單與 daemon 控制項;若發現某個 Worktree 佔用異常資源,可從這裡直接定位並清理(見第三十章)。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| daemon 正常運作 | 開啟狀態列 Resource Manager | 看到 daemon 狀態與目前的 PTY 清單 | 若狀態列未顯示,到 Settings → Appearance 開啟 Resource Manager |
| Agent 行程是獨立行程 | 啟動一個 Agent 後,用 2.4 的 ps 或 Get-CimInstance 指令查詢 | 看到 claude 或 codex 行程 | 確認該 Tab 是從 Agent 選單啟動 |
| CLI 可連上應用程式 | 執行 orca status --json | 輸出應用程式狀態 JSON | 見 4.8 註冊 CLI |
3.2 行程模型
📌 查證狀態:官方文件明確記載|來源:Session restore、Codex、Remote servers
理解行程模型,才能正確回答「關掉 Orca 之後 Agent 還在跑嗎?」「Agent 有哪些權限?」這類問題。
flowchart TB
App["Orca 應用程式"] -->|"建立與附加"| D["背景 daemon"]
D -->|"spawn"| P1["PTY 1:shell"]
D -->|"spawn"| P2["PTY 2:shell"]
P1 --> A1["claude 行程"]
P2 --> A2["codex 行程"]
A2 --> S2["每個 Tab 的 Codex server"]
A1 -->|"hooks 回報狀態"| App
A2 -->|"hooks 回報狀態"| App如何閱讀此圖:每個終端機 Tab 是 daemon 底下的一個 PTY,Agent 是 PTY 中 shell 的子行程,因此繼承該使用者帳號的完整權限與環境變數。Agent 透過 hooks(本機 loopback 端點)回報狀態給應用程式,這就是側邊欄能顯示「需要你」的原因。
關鍵事實
- Agent 以你的使用者身分執行:Orca 本身不提供沙箱。Agent 能讀寫你帳號可存取的任何檔案;隔離只能來自 Agent 自己的權限模式、Worktree 邊界的「約定」、或把執行移到 SSH 主機與 Cloud VM。
- daemon 跨越應用程式生命週期:應用程式結束、更新、當機時 daemon 存活;主機重開機時 daemon 與所有 Agent 一同結束。
- Codex 隔離:預設每個 Codex Tab 擁有自己的 Codex server;可設定環境變數
ORCA_CODEX_ISOLATE=0停用(官方文件記載的進階選項,一般不需調整)。 - Remote Orca Server 的執行環境:
orca serve優先使用 orcad(Node server),無法使用時退回 Electron server;封裝版 macOS 一律使用 Electron;可用ORCA_SERVE_RUNTIME=electron強制指定。
⚠️ 注意事項:因為 Agent 繼承 shell 環境,任何存在於你 shell profile 的雲端憑證(例如 AWS_PROFILE、GITHUB_TOKEN)都可能被 Agent 使用。企業環境應把正式環境憑證與開發機分開,詳見第二十八章。
✅ 驗證方式
在 Orca 的 Agent 終端機中執行:
env | grep -E "^(AWS_|AZURE_|GOOGLE_|GITHUB_TOKEN|GH_TOKEN)" | cut -d= -f1Windows PowerShell:
Get-ChildItem Env: | Where-Object Name -Match '^(AWS_|AZURE_|GOOGLE_|GITHUB_TOKEN|GH_TOKEN)' | Select-Object Name預期結果:只列出變數名稱(不顯示值);名單應只包含團隊允許 Agent 使用的開發用憑證。
判讀:若出現正式環境的雲端憑證變數,Agent 同樣能使用它們,請從 shell profile 移除,或改在 SSH 主機與 Cloud VM 上執行 Agent。
3.3 執行模式
📌 查證狀態:官方文件明確記載|來源:Ways to run Orca、Remote servers
Orca 支援四種執行位置,且可以混用:同一個側邊欄中,有的 Worktree 在本機、有的在 SSH 主機、有的在 Cloud VM。
| 模式 | 程式碼與 Agent 在哪裡 | 設定入口 | 適用情境 | 狀態 |
|---|---|---|---|---|
| Local | 你的桌機 | 預設 | 個人開發、快速試驗 | 正式 |
| SSH target | 你管理的遠端主機(主機需安裝 git) | Settings → SSH;建立 Worktree 時 Run on 選擇 | GPU 主機、公司內部開發伺服器、桌機資源不足 | 正式 |
| Remote Orca Server | 一台長期運作的 Orca 主機,桌機、手機、其他電腦都可連線 | 主機端 Settings → Remote Orca Servers → Advertise;用戶端 Add server | 跨裝置延續工作、長時間任務不受筆電重開機影響 | Beta |
| Cloud VM | 每個 Worktree 一台以 recipe 定義的雲端或 Docker 環境 | Settings → Experimental → Cloud VM | 需要完全隔離、可拋棄的環境,或 Yolo 模式 | 實驗性 |
flowchart LR
You["你的 Orca 用戶端"] --> L["Local Worktree"]
You -->|"SSH"| S["SSH 主機 Worktree"]
You -->|"Tailscale 或私有網路<br/>存取連結與 token"| R["Remote Orca Server"]
You -->|"recipe 佈建"| C["Cloud VM Worktree"]
Phone["Orca 行動 App"] --> R如何閱讀此圖:同一個用戶端可同時連到四種位置。Remote Orca Server 的特點是多個用戶端(含手機)可連到同一台主機,所以適合「辦公室開始、家裡繼續、手機核准」的情境。
選擇決策
- 程式碼可以放在個人筆電、任務短於一小時:Local。
- 需要特定硬體或公司內網資源:SSH target。
- 任務需要跨夜執行或跨裝置監控:Remote Orca Server。
- 需要每個 Agent 完全隔離、或要以 Yolo 模式執行不信任的任務:Cloud VM。
⚠️ 注意事項
- Remote Orca Server 的存取連結內含連線權限,等同密碼;絕不可暴露在公開網際網路。官方建議透過 Tailscale 等私有網路連線,且廣播位址不可使用
127.0.0.1。 - 每個用戶端擁有可單獨撤銷的 token,可在主機端 Shared Server Access 管理。
- 遠端主機的 Allow host orca CLI 自 v1.4.230 起預設關閉,意即遠端 shell 預設不能控制你的桌面 Orca;除非明確需要,請維持關閉。
詳細設定步驟見第十八章。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 可選擇執行位置 | 開啟建立 Worktree 對話框的 Run on 選單 | 列出 Local,以及已設定的 SSH 主機、Remote Orca Server、Cloud VM recipe | 先在對應的 Settings 頁面完成設定 |
| SSH 主機具備 git | 在本機執行 ssh <host> git --version | 顯示 git 版本 | 在遠端主機安裝 git |
| Remote Orca Server 未暴露公網 | 在主機端 Settings → Remote Orca Servers 檢查廣播位址 | 位址為 Tailscale(例如 100.x.y.z)或內網位址 | 立即停止 Advertise 並撤銷 Shared Server Access 中的 token |
3.4 資料儲存位置
📌 查證狀態:個別路徑為官方文件明確記載;表格整理與分類為依官方說明延伸(教學推論)|來源:Settings reference、Agent hooks & memory、Session history、Troubleshooting
| 資料 | 位置 | 說明 |
|---|---|---|
| Worktree 檔案 | 建立 Worktree 時選擇的目錄 | 一般 git worktree,可用任何工具操作 |
| 快捷鍵覆寫 | ~/.orca/keybindings.json | 既有安裝的自訂快捷鍵 |
| 應用程式狀態與設定 | Orca 的 userData 目錄;可選 SQLite 或 JSON 儲存 | 升級時 Orca 可能詢問是否改用 SQLite,官方建議選擇 Use SQLite |
| Agent hooks 端點 | {userData}/agent-hooks/endpoint.env(macOS 與 Linux)或 endpoint.cmd(Windows) | Agent hooks 回報狀態用的本機 loopback 端點與 token |
| Agent 對話紀錄 | 各 Agent 自己的目錄,例如 ~/.claude、~/.codex/sessions | Orca 只讀取來顯示 Session History,不會搬移 |
| 額外 Codex 帳號 | Orca 帳號資料下各帳號獨立的 home 目錄;WSL 為 ~/.local/share/orca/codex-accounts/<id>/home | 讓多帳號互不干擾 |
| Agent 記憶 | 各 Agent 自己的檔案,例如 CLAUDE.md、AGENTS.md | Orca 不另建記憶庫,見第九章 |
| 紀錄檔 | Help → Open Logs 開啟的資料夾 | 問題回報時使用;診斷 trace 只存本機 |
⚠️ 注意事項:endpoint.env 與 endpoint.cmd 含有本機 hooks token,不應提交到版本控制或貼到工單。若懷疑外洩,重新啟動 Orca 會產生新的端點資訊(教學推論,請以實測為準)。
💡 小技巧:企業備份政策若排除使用者 home 目錄下的隱藏資料夾,~/.claude、~/.codex 中的 Agent 對話紀錄將不會被備份。若需保留審計軌跡,請明確將它們納入(見第二十八章)。
✅ 驗證方式
從選單 Help → Open Logs 開啟紀錄資料夾,確認可看到最近的紀錄檔。
檢查 hooks 端點檔案存在(macOS 範例,userData 路徑依作業系統不同):
ls ~/Library/Application\ Support/Orca/agent-hooks/Windows PowerShell:
Get-ChildItem "$env:APPDATA\Orca\agent-hooks" -ErrorAction SilentlyContinue預期結果:看到
endpoint.env或endpoint.cmd。判讀:若找不到,userData 目錄名稱可能不同(例如大小寫差異);以 Help → Open Logs 開啟的位置往上一層尋找。上述 userData 實際路徑為教學推論,請以你的安裝為準。
3.5 遙測與隱私
📌 查證狀態:官方文件明確記載|來源:Telemetry
Orca 的匿名遙測預設開啟,用來了解功能使用情形。官方文件明確列出收集與不收集的範圍:
| 會送出 | 不會送出 |
|---|---|
| 隨機產生的匿名安裝 ID | 檔案路徑、repo 名稱、分支名稱 |
| 應用程式版本、作業系統、CPU 架構、更新通道 | Prompt 內容、Agent 輸出、程式碼 |
| 事件類別:應用程式生命週期、repo 與 Worktree 操作、啟動的 Agent 種類、Agent 錯誤類別 | IP 位址(官方說明不保留) |
| 少數白名單偏好設定的變更事件(記錄哪個設定改變、屬於布林或列舉,不含自由輸入的值)與隱私開關狀態 | 帳號、email、token |
遙測送往 PostHog(美國區域)。
關閉方式(三擇一,任一生效即停止送出)
- UI:Settings → Privacy 關閉 Share anonymous usage data。
- 環境變數
DO_NOT_TRACK=1。 - 環境變數
ORCA_TELEMETRY_DISABLED=1。
範例:以環境變數全機關閉
Windows(使用者層級,需重新登入或重新啟動 Orca):
setx ORCA_TELEMETRY_DISABLED 1macOS(對 GUI 應用程式生效,重新開機後需重新設定,或寫入 LaunchAgent):
launchctl setenv ORCA_TELEMETRY_DISABLED 1Linux(寫入使用者環境設定):
mkdir -p ~/.config/environment.d
echo 'ORCA_TELEMETRY_DISABLED=1' >> ~/.config/environment.d/orca.conf📌 查證狀態:環境變數名稱為官方文件明確記載;各作業系統讓 GUI 應用程式繼承環境變數的方法為依官方說明延伸(教學推論)|來源:Telemetry
遙測以外的對外連線
關閉遙測不代表 Orca 完全離線。以下連線依你使用的功能而產生:
| 連線 | 觸發條件 | 控制方式 |
|---|---|---|
| Agent 到模型供應商 | 執行任何 Agent | 由 Agent CLI 自身設定與企業代理控制 |
GitHub(含 gh CLI) | PR、Issue、Checks 功能 | Settings → Integrations;gh auth |
| Linear、Jira、GitLab、Bitbucket | 連結任務或 MR | Settings → Integrations 中個別設定 |
| 自動更新 | 檢查與下載更新 | Settings → General → Updates;v1.4.243 起遵循 Settings 中的 proxy |
| Artifacts 發布 | 手動發布 Artifact(預設關閉,單檔上限 10 MiB) | Settings → Artifacts |
| 行動 App relay | 配對手機時 | 不配對即不使用 |
| 雲端語音模型 | 選用 GPT-4o 等雲端聽寫模型 | Settings → Voice 改用本機模型 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| UI 已關閉遙測 | Settings → Privacy | Share anonymous usage data 為關閉 | 手動關閉;若由環境變數控制,UI 可能顯示為已停用 |
| 環境變數已生效 | 在 Orca 終端機執行 echo $ORCA_TELEMETRY_DISABLED(PowerShell:$env:ORCA_TELEMETRY_DISABLED) | 輸出 1 | 重新登入或重新啟動 Orca,讓應用程式繼承新環境 |
| 無遙測連線 | 透過企業代理或防火牆紀錄觀察 PostHog 網域的連線 | 關閉後不再出現 | 確認三種關閉方式至少一種生效 |
| Artifacts 未啟用 | Settings → Artifacts | 發布功能為關閉 | 依政策關閉 |
3.6 本章 Review 與驗證清單
- 能畫出「應用程式、daemon、PTY、Agent CLI」的行程關係
- 能說明為何關閉 Orca 視窗後 Agent 仍在執行,以及何時會被終止
- 已確認 Agent 終端機中沒有不該出現的正式環境憑證環境變數
- 能說出四種執行模式的差異與各自的適用情境
- 已確認 Remote Orca Server(若使用)未暴露於公網,且 Allow host orca CLI 維持關閉
- 知道 hooks 端點檔、Agent 對話紀錄、紀錄檔各存放在哪裡
- 能說明遙測會送出與不會送出的內容,並已依政策設定關閉方式
- 已列出組織需在防火牆或代理放行的對外連線清單
第四章 安裝與環境建置
本章依作業系統說明安裝步驟,並涵蓋 WSL、容器環境、更新管理與安裝後健康檢查。企業 IT 可直接把 4.8 的檢查腳本納入標準映像或新人報到流程。
4.1 系統需求與前置條件
📌 查證狀態:支援平台與下載格式為官方文件明確記載;官方未公布最低硬體需求,下表硬體建議為依官方說明延伸(教學推論)|來源:Install、Supported agents
支援平台
| 作業系統 | 官方提供的安裝格式 | 備註 |
|---|---|---|
| macOS | Apple Silicon 與 Intel 的 dmg;Homebrew cask | 已簽章並經 Apple 公證(notarized) |
| Windows | orca-windows-setup.exe 安裝程式 | 安裝程式經 SignPath 簽章 |
| Linux | AppImage、.deb、.rpm;社群 AUR 套件 | CLI 名稱為 orca-ide |
硬體建議(教學推論)
Orca 本身是 Electron 應用程式,真正吃資源的是平行執行的 Agent CLI、各 Worktree 的建置與測試行程,以及每個 Worktree 的磁碟副本。
| 使用規模 | 記憶體 | 磁碟可用空間 | 說明 |
|---|---|---|---|
| 個人試用(1 至 2 個 Agent) | 16 GB | repo 大小的 3 倍以上 | 足以執行一般 Web 專案 |
| 日常平行開發(3 至 5 個 Agent) | 32 GB | repo 大小的 6 倍以上 | 每個 Worktree 都可能執行自己的 dev server 與測試 |
| 重度平行(6 個以上) | 建議改用 SSH 主機或 Remote Orca Server | 依主機而定 | 把負載移出筆電,見第十八章 |
前置軟體
| 項目 | 必要性 | 驗證指令 |
|---|---|---|
| git | 必要(含 SSH 主機) | git --version |
| 至少一個 Agent CLI | 必要,例如 Claude Code、Codex、Gemini CLI、GitHub Copilot CLI | claude --version、codex --version |
GitHub CLI gh | 使用 PR、Issue、Checks 功能時建議安裝 | gh auth status -h github.com |
| Node.js 等專案工具鏈 | 依專案需求 | node --version |
⚠️ 注意事項:Orca 不內建任何模型。若組織尚未核准任何 Agent CLI 與其模型供應商,請先完成第二十八章的資安審查,再進行安裝。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| git 可用 | git --version | 顯示版本號 | 安裝 git 並重新開啟終端機 |
| 至少一個 Agent CLI 可用 | claude --version 或 codex --version | 顯示版本號 | 依該 Agent 官方說明安裝並登入 |
| gh 已登入(選用) | gh auth status -h github.com | 顯示 Logged in | 執行 gh auth login |
| 磁碟空間足夠 | macOS 與 Linux:df -h ~;Windows:Get-PSDrive C | 可用空間符合上表建議 | 清理空間或把 Worktree 放到其他磁碟 |
4.2 Windows 安裝
📌 查證狀態:官方文件明確記載|來源:Install、Orca CLI overview
操作步驟
- 從官方網站下載 Windows installer,或從 GitHub Releases 下載
orca-windows-setup.exe。 - 執行安裝程式;若 SmartScreen 提示,確認簽章發行者後繼續。
- 首次啟動時允許存取 home 目錄,並依需要匯入
~/.claude、~/.codex與 Ghostty 設定。 - 到 Settings → Terminal 將預設 shell 設為 PowerShell(多數使用者的選擇)或 CMD;若系統已安裝 WSL 且
wsl.exe --status成功,也可選 WSL(見 4.5)。 - 到 Settings → General → Orca CLI 註冊 CLI。Windows 上的
orca是原生程式(v1.4.219 起),不需要 Visual C++ Redistributable,註冊後會加入 PATH。 - 開啟新的 PowerShell 視窗驗證 CLI。
範例:檢查安裝程式簽章
Get-AuthenticodeSignature .\orca-windows-setup.exe | Select-Object Status, SignerCertificate⚠️ 注意事項
- 企業端點防護軟體可能攔截 Agent CLI 大量啟動子行程或寫入檔案,造成 Worktree 建立或測試變慢。若需設定排除清單,請由資安團隊評估,只排除 Worktree 所在目錄,而非整個使用者目錄。
- 註冊 CLI 後,已經開啟的終端機不會取得新的 PATH,需重新開啟。
✅ 驗證方式
開啟新的 PowerShell 視窗並執行:
Get-Command orca | Select-Object Source orca status --json預期結果:第一行顯示
orca的完整路徑;第二行輸出 Orca 應用程式狀態的 JSON。判讀:若找不到
orca,回到 Settings → General → Orca CLI 重新註冊並重新開啟終端機;若orca status無法連線,確認 Orca 應用程式正在執行。
4.3 macOS 安裝
📌 查證狀態:官方文件明確記載|來源:Install、Orca CLI overview
方法一:Homebrew(建議,便於 IT 管理)
brew install --cask stablyai/orca/orca❌ 常見錯誤:執行 brew install --cask orca 會安裝 Homebrew 中另一個同名、與本產品無關的 cask。請務必使用完整名稱 stablyai/orca/orca。
Homebrew cask 在每次 stable 版本發布時自動更新版本號,只追蹤 stable 通道。升級指令:
brew upgrade --cask stablyai/orca/orca方法二:dmg
- 依 CPU 下載 Apple Silicon 或 Intel 的 dmg。
- 拖曳到 Applications。
- 首次開啟時 macOS 可能要求確認——這對 Electron 應用程式是正常的,因為 Orca 已簽章並經公證。
首次啟動與 CLI
- 允許存取 home 目錄,依需要匯入
~/.claude、~/.codex與 Ghostty 設定。 - 到 Settings → General → Orca CLI 註冊 CLI;Orca 會在
~/.local/bin安裝 shim。 - 確認
~/.local/bin在 PATH 中。
echo $PATH | tr ':' '\n' | grep -x "$HOME/.local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc✅ 驗證方式
執行:
codesign -dv --verbose=2 /Applications/Orca.app 2>&1 | grep -E "Authority|TeamIdentifier" spctl -a -vv /Applications/Orca.app command -v orca orca status --json預期結果:
codesign顯示 Developer ID 簽章資訊;spctl顯示accepted與Notarized Developer ID;command -v orca顯示~/.local/bin/orca;orca status --json輸出狀態 JSON。判讀:若
spctl為 rejected,檔案可能非官方來源,請刪除後從官方網站重新下載。應用程式路徑/Applications/Orca.app為一般安裝位置,若安裝在他處請調整。
4.4 Linux 安裝
| 格式 | 更新方式 | 適用情境 |
|---|---|---|
| AppImage | Orca 自動更新 | 希望與 macOS、Windows 相同的自動更新體驗 |
| .deb(Debian、Ubuntu) | Orca 提示有新版並提供套件管理員指令;執行前需先結束 Orca | 由 IT 以套件庫集中管理 |
| .rpm(Fedora、RHEL) | 同上 | 同上 |
AUR stably-orca-bin 或 stably-orca-git | 透過 AUR helper | Arch Linux 使用者 |
範例:安裝指令
# AppImage
chmod +x Orca-*.AppImage
./Orca-*.AppImage
# Debian 與 Ubuntu
sudo apt install ./orca_*_amd64.deb
# Fedora 與 RHEL
sudo dnf install ./orca-*.x86_64.rpm
# Arch Linux(社群 AUR)
yay -S stably-orca-bin📌 查證狀態:上述檔名萬用字元為教學示例(非官方),請以 GitHub Releases 實際檔名為準|來源:GitHub Releases
CLI 名稱差異:Linux 上的 CLI 命名為 orca-ide,以避免與 GNOME 的 Orca 螢幕閱讀器衝突。本手冊後續以 orca 表示 CLI,Linux 使用者請自行替換為 orca-ide。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| CLI 可用且不衝突 | command -v orca-ide | 顯示 orca-ide 路徑 | 到 Settings → General → Orca CLI 註冊 |
| 未誤呼叫螢幕閱讀器 | command -v orca | 若有輸出,應是螢幕閱讀器而非 Orca IDE | 腳本中一律使用 orca-ide |
| 應用程式可連線 | orca-ide status --json | 輸出狀態 JSON | 確認 Orca 應用程式正在執行 |
| 套件版本 | dpkg -s orca 或 rpm -q orca | 顯示已安裝版本 | 套件名稱依實際發行為準(教學推論) |
4.5 WSL 整合
📌 查證狀態:官方文件明確記載|來源:Terminal、Codex、Release notes
Windows 使用者常把 repo 與工具鏈放在 WSL 中。Orca 對 WSL 的支援包括:
| 情境 | Orca 的行為 |
|---|---|
| 預設 shell | wsl.exe --status 成功時,Settings → Terminal 可選 WSL 作為預設 shell |
repo 位於 \\wsl.localhost\<distro>\... | 終端機透過 wsl.exe -d <distro> 啟動於該 distro |
| repo 位於 Windows 路徑但使用 WSL shell | 路徑轉譯為 /mnt/<drive>/...,並以 login bash 啟動 |
| WSL 中的 Orca CLI | v1.4.214 起,受管的 WSL 終端機內可使用 orca CLI |
| WSL 中的 Codex 多帳號 | 帳號資料存放於 ~/.local/share/orca/codex-accounts/<id>/home |
| 近期改進 | v1.4.242 降低 WSL 記憶體使用;v1.4.244 起 distro 停止時保留 Session |
建議做法(教學推論)
- repo 放在 WSL 檔案系統(例如
~/src/...),透過\\wsl.localhost\Ubuntu\home\<user>\src\...加入 Orca。跨/mnt/c存取 Windows 檔案系統的 I/O 較慢,大型 repo 的git status與套件安裝會明顯變慢。 - Agent CLI 與
gh安裝在 WSL 內,與 repo 使用相同環境。 - 在 WSL 內設定 git 身分與憑證,不要依賴 Windows 端設定。
範例:在 WSL 中準備環境
wsl.exe --status
wsl.exe -d Ubuntu -- bash -lc "git --version && command -v claude codex gh"✅ 驗證方式
在 Orca 中開啟一個位於 WSL repo 的 Worktree 終端機,執行:
uname -a pwd command -v orca預期結果:
uname顯示 Linux 與 WSL 核心字樣;pwd為 Linux 路徑(例如/home/alice/src/...);command -v orca有輸出。判讀:若
pwd顯示/mnt/c/...,代表 repo 位於 Windows 檔案系統,效能可能較差;若沒有orca,請將 Orca 更新到 v1.4.214 以上。
4.6 Docker 與容器環境
📌 查證狀態:官方未提供 Orca 桌面應用程式的 Docker 映像。官方文件中與容器相關的是 Cloud VM 的本機 Docker provider,以及
orca serve --supervise在容器中使用的說明;其餘內容為教學推論|來源:Remote servers、Ways to run Orca
企業常問「能不能把 Orca 放進容器」。正確的拆解方式是:
| 需求 | 建議做法 | 依據 |
|---|---|---|
| 每個 Agent 在隔離容器中執行 | 使用 Cloud VM,provider 選擇本機 Docker(或 Vercel Sandbox、Fly、Modal、SSH) | 官方文件明確記載 |
| 在伺服器上長期執行 Orca 供遠端連線 | 使用 orca serve;若容器已負責重新啟動行程,加上 --supervise | 官方文件明確記載 |
| 把 Orca 桌面介面本身放進容器 | 不建議;官方無此支援 | 教學推論 |
範例:在 Linux 主機以服務方式執行 Remote Orca Server
# 安裝為使用者服務(Windows 不支援 service 子命令)
orca-ide serve service install --port 6768
orca-ide serve service status
# 讓使用者服務在登出後繼續執行
loginctl enable-linger "$USER"範例:容器內以前景方式執行(教學示例,非官方)
# 僅示意結構:基底映像、Orca 取得方式與相依套件需依實際發行調整
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y git ca-certificates && rm -rf /var/lib/apt/lists/*
# 將官方 AppImage 解開後放入 /opt/orca(--appimage-extract)
COPY squashfs-root /opt/orca
WORKDIR /workspace
CMD ["/opt/orca/orca-ide", "serve", "--supervise", "--port", "6768"]⚠️ 注意事項:容器內的 Remote Orca Server 同樣不可暴露在公網;請只在 Tailscale 或內部網路上提供,並以 Shared Server Access 管理用戶端 token。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 服務已執行(Linux 主機) | orca-ide serve service status | 顯示服務執行中與連接埠 | 查看 journalctl --user 紀錄 |
| 登出後仍執行 | loginctl show-user "$USER" --property=Linger | Linger=yes | 再次執行 loginctl enable-linger |
| 只監聽私有網路 | ss -ltnp 檢查 6768 埠 | 連線僅能從 Tailscale 或內網到達 | 以防火牆限制來源,見第十八章 |
| Cloud VM Docker provider 可用 | Settings → Experimental → Cloud VM 啟用後建立測試 Worktree | Worktree 在容器中建立,終端機 hostname 為容器名稱 | 確認本機 Docker daemon 正在執行 |
4.7 更新機制與版本管理
📌 查證狀態:官方文件明確記載|來源:Install、Release notes
Orca 預設自動更新,追蹤 stable 通道。RC(release candidate)版本會更早取得新功能,經常每天發布,但沒有永久的 RC 選項,只能透過 Check for Updates 的修飾鍵取得:
| 操作(Settings → General → Updates 或應用程式選單的 Check for Updates) | 效果 |
|---|---|
| 一般點擊 | 檢查最新 stable |
| Shift+點擊 | 包含最新 RC prerelease |
| Cmd+點擊(macOS)或 Ctrl+點擊(Windows 與 Linux) | 最新的 perf 標記 prerelease |
| Option+點擊(僅 macOS) | 選擇通過相容性檢查的本機 macOS 建置 |
版本管理要點
- 降版:舊版本永遠可在 GitHub Releases 取得;回到舊版時 Orca 不會強制降級你的 Worktree 資料。
- 代理:v1.4.243 起,更新檢查與下載遵循 Settings 中設定的 proxy。
- 自動更新不會中斷 Agent:更新重新啟動時背景 daemon 存活(見 2.7)。但若某版本更換了 daemon 或終端機主機實作,release notes 會特別說明,升級前請閱讀。
- 遠端伺服器版本:SSH 主機上的受管 server 可在 Settings → SSH 執行 Update、Roll back、Recover;部分功能(例如 v1.4.242 的 Codex Ask 唯讀模式)需要配對的 server 也更新才生效。
企業版本管理建議(教學推論)
- 指定一位維護者訂閱 GitHub Releases,每週評估一次。
- 先在試點群組使用新版 3 至 5 個工作天,再開放全員更新。
- 若需凍結版本,以 Homebrew 或軟體派送工具安裝指定版本,並記錄於內部版本基準表(見 6.9)。
範例:查詢目前版本與最新版本
gh release list --repo stablyai/orca --limit 5
gh release view --repo stablyai/orca --json tagName,publishedAt✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 目前版本 | 應用程式選單 About Orca,或 Settings → General → Updates | 顯示版本號,例如 1.4.244 | 執行 Check for Updates |
| 與官方最新版比對 | gh release list --repo stablyai/orca --limit 5 | 目前版本等於或接近最新 stable | 依組織政策更新 |
| 更新經過代理 | 在受控網路中執行 Check for Updates | 可成功檢查,代理紀錄中可看到連線 | 確認版本為 v1.4.243 以上,且 Settings 中 proxy 正確 |
4.8 安裝後健康檢查
📌 查證狀態:個別指令為官方文件明確記載;檢查腳本的組合為教學示例(非官方)|來源:Orca CLI overview、Troubleshooting
安裝完成後,建議以腳本一次檢查所有前置條件,並把輸出存成新人報到紀錄。
macOS 與 Linux(bash)
#!/usr/bin/env bash
# orca-healthcheck.sh:Linux 請將 ORCA_BIN 改為 orca-ide
ORCA_BIN="${ORCA_BIN:-orca}"
check() {
local name="$1"; shift
if "$@" >/dev/null 2>&1; then echo "[OK] $name"; else echo "[FAIL] $name"; fi
}
check "git 已安裝" git --version
check "Orca CLI 在 PATH" command -v "$ORCA_BIN"
check "Orca 應用程式可連線" "$ORCA_BIN" status --json
check "Claude Code 已安裝" claude --version
check "Codex 已安裝" codex --version
check "gh 已登入 GitHub" gh auth status -h github.com
check "可連線 GitHub API" gh api rate_limit --jq '.resources.core.remaining'
echo "遙測環境變數:ORCA_TELEMETRY_DISABLED=${ORCA_TELEMETRY_DISABLED:-未設定}"Windows(PowerShell)
# orca-healthcheck.ps1
function Test-Step($Name, [scriptblock]$Block) {
try { & $Block *> $null; if ($LASTEXITCODE -in $null, 0) { "[OK] $Name" } else { "[FAIL] $Name" } }
catch { "[FAIL] $Name" }
}
Test-Step "git 已安裝" { git --version }
Test-Step "Orca CLI 在 PATH" { Get-Command orca -ErrorAction Stop }
Test-Step "Orca 應用程式可連線" { orca status --json }
Test-Step "Claude Code 已安裝" { claude --version }
Test-Step "Codex 已安裝" { codex --version }
Test-Step "gh 已登入 GitHub" { gh auth status -h github.com }
"遙測環境變數:ORCA_TELEMETRY_DISABLED=$env:ORCA_TELEMETRY_DISABLED"未安裝的 Agent 出現 FAIL 是正常的:只要組織核准的 Agent 皆為 OK 即可。
常見問題快速對照
| 症狀 | 可能原因 | 處理 |
|---|---|---|
orca: command not found | 未註冊 CLI,或終端機在註冊前開啟 | Settings → General → Orca CLI 註冊後重開終端機 |
orca status 連線失敗 | Orca 應用程式未執行 | 啟動 Orca 後重試 |
| PR 或 Checks 資料不出現 | gh 未登入或 API 額度用完 | gh auth status -h github.com、gh api rate_limit --jq '.resources.core' |
| 建立 Worktree 失敗 | 遠端分支未 fetch 或網路問題 | 在主 checkout 執行 git fetch origin 後於進度列點 Retry |
更多疑難排解見第二十九章。
✅ 驗證方式
執行對應作業系統的腳本:
bash orca-healthcheck.sh | tee orca-healthcheck-$(date +%Y%m%d).log預期結果:git、Orca CLI、Orca 應用程式可連線、組織核准的 Agent、gh 皆為
[OK]。判讀:任何
[FAIL]依上表處理;將 log 檔附在新人報到工單作為完成證據。
4.9 本章 Review 與驗證清單
- 已確認作業系統、硬體與磁碟空間符合 4.1 的建議
- 已從官方來源安裝並驗證簽章(Windows
Get-AuthenticodeSignature、macOSspctl) - macOS 使用
stablyai/orca/orca完整 cask 名稱,而非orca - 已註冊 Orca CLI,並在新終端機中執行
orca status --json成功(Linux 為orca-ide) - WSL 使用者已確認 repo 位於 Linux 檔案系統,且 WSL 終端機中可使用 orca CLI
- 理解官方不提供 Orca 桌面 Docker 映像,容器隔離改用 Cloud VM
- 能說明 stable 與 RC 的取得方式,以及如何降版
- 已執行 4.8 健康檢查腳本並保存輸出
第五章 第一次工作階段實作
本章以一個完整範例走過官方「First session」流程:加入 repo、讓三個 Agent 同時解同一個 bug、並排監看、選出最佳解並合併,最後清理落選的 Worktree。整個流程約 30 至 45 分鐘。
📌 查證狀態:流程步驟為官方文件明確記載;範例 repo、bug 與評分表為教學示例(非官方)|來源:Your first session、Run parallel agents
flowchart LR
A["5.1 加入 Repo"] --> B["5.2 建立 Worktree"]
B --> C["5.3 啟動 Agent"]
C --> D["5.4 三個 Agent 同題競賽"]
D --> E["5.5 分割窗格監看"]
E --> F["5.6 審查、選出勝者、合併"]
F --> G["清理落選 Worktree"]如何閱讀此圖:由左至右是本章各節的順序。5.4 與 5.5 是同時進行的——Agent 在工作時你在監看;5.6 是唯一需要人類做決定的關卡。
範例情境
本章使用一個假想的 payment-api repo,其登入流程有競態條件(race condition):同一使用者在 200 毫秒內送出兩次登入請求時,偶爾會產生兩個有效 session token。這個 bug 有多種合理修法(資料庫鎖、冪等鍵、單一飛行請求合併),適合用來比較不同 Agent 的解法。你可以換成自己團隊中一個範圍明確、可用測試重現的真實 bug。
5.1 加入 Repository
📌 查證狀態:官方文件明確記載|來源:Your first session
操作步驟
在主 checkout 中確認狀態乾淨並更新遠端:
cd ~/src/payment-api git status --short git fetch origin在 Orca 點選 Create(或 Project 下拉選單的 Add a new project),選擇
~/src/payment-api。加入後,repo 出現在側邊欄。到 Settings → Repository 確認 base ref 為
origin/main。(建議)在 repo 根目錄準備 2.3 介紹的
orca.yaml與.worktreeinclude,讓新 Worktree 一建立就能執行測試。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| repo 已加入 | 側邊欄出現 payment-api;或 orca repo list --json | 列出 repo 與 id | 確認選擇的是 git repo 根目錄 |
| 主 checkout 乾淨 | git status --short | 無輸出 | 先提交或 stash 本機變更 |
| base ref 正確 | Settings → Repository | origin/main | 修改 base ref |
5.2 建立第一個 Worktree
📌 查證狀態:官方文件明確記載|來源:Your first session、Worktrees
操作步驟
- 點選側邊欄
payment-api旁的 +。 - 名稱輸入
fix-login-race。 - Branch from 保持
origin/main。 - Run on 保持 Local。
- 先選擇 Blank Terminal(本節只驗證 Worktree 本身,5.3 再啟動 Agent)。
- 送出後對話框立即關閉,側邊欄出現進度列;完成後 Worktree 自動開啟。
先確認測試能在 Worktree 中重現 bug
git rev-parse --abbrev-ref HEAD
npm test -- --grep "concurrent login"在交給 Agent 之前,先確認「失敗的測試」存在且確實失敗。這是之後判斷 Agent 是否真的修好 bug 的客觀依據。若 repo 沒有可重現的測試,第一個任務應該是「請 Agent 先寫出會失敗的測試」,而不是直接修 bug。
✅ 驗證方式
在 Worktree 終端機執行:
pwd git rev-parse --abbrev-ref HEAD git log -1 --oneline預期結果:
pwd為 Orca 建立的 Worktree 目錄(不是~/src/payment-api);分支為fix-login-race;最新 commit 與origin/main相同。判讀:若
pwd是主 checkout,代表你開錯了終端機;若分支名稱不同,檢查 Settings → Git 的 Auto-Rename Branch 或 Advanced 中的 Branch name。
5.3 選擇與啟動 Agent
📌 查證狀態:官方文件明確記載|來源:Your first session、Supported agents
官方首次體驗流程建議從 Claude Code、Codex 或 Cursor CLI 開始。啟動前請先決定權限模式(見 2.4)。
操作步驟
- 第一次試用建議到 Settings → Agents → Agent permissions 選擇 Manual 或 Auto,熟悉 Agent 行為後再評估是否放寬。
- 在
fix-login-raceWorktree 的 Tab 列點 +,選擇 Claude Code(或其他已安裝的 Agent)。 - 確認分頁標題出現 Agent 名稱與狀態圖示。
- 若 Agent 尚未登入,依提示完成登入;多帳號設定見第八章。
範例 Prompt
這個 repo 的登入 API 有競態條件:同一使用者在 200 毫秒內送出兩次登入請求時,偶爾會產生兩個有效 session token。
重現測試:npm test -- --grep "concurrent login"
請你:
1. 先閱讀 src/auth/ 下的登入流程,說明競態發生的根本原因(不超過 5 行)。
2. 提出修正,並保持既有 API 介面不變。
3. 確保重現測試通過,且完整測試套件 npm test 全部通過。
4. 不得修改 src/auth/ 與 test/ 以外的檔案;不得刪除或跳過任何既有測試。
5. 完成後輸出:根本原因、修改摘要、git diff --stat、測試結果摘要。🧑⚖️ 人工 Review 要點
- 根本原因說明合理,且與修改內容一致
-
git diff --stat只涉及src/auth/與test/ - 沒有被刪除、改名或標記為 skip 的測試(搜尋
.skip、xit、@Ignore等) - 你親自重新執行測試,結果與 Agent 報告一致
- API 介面(路由、回應格式)沒有改變
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Agent 狀態可追蹤 | 送出 Prompt 後觀察分頁與側邊欄 | 出現旋轉圖示,完成時變為勾號並收到通知 | 從 Agent 選單重新啟動,不要在終端機手動輸入指令 |
| 權限模式正確 | 用 2.4 的 ps 或 Get-CimInstance 指令檢查參數 | 參數與你選擇的模式一致 | 檢查 Settings → Agents 中是否有自訂參數 |
| 測試結果可重現 | 在 Worktree 終端機自行執行 npm test | 與 Agent 報告一致 | 要求 Agent 說明差異,不要直接採信 |
5.4 三個 Agent 同題競賽
📌 查證狀態:官方文件明確記載|來源:Your first session、Run parallel agents
Orca 的核心使用模式之一:同一個任務交給多個 Agent,各自在獨立 Worktree 中解題,最後選出最好的。由於 Worktree 互相隔離,Agent 不會互相覆寫檔案。
操作步驟
- 重複 5.2 的步驟,建立
fix-login-race-2與fix-login-race-3。 - 三個 Worktree 分別選擇不同 Agent,例如 Claude Code、Codex、Cursor CLI;也可以三個都用同一個 Agent 來比較隨機性。
- 三個 Agent 都貼上 5.3 的同一份 Prompt。
範例:以 CLI 一次建立三個 Worktree
PROMPT="$(cat prompts/fix-login-race.txt)"
orca worktree create --repo id:<repoId> --name fix-login-race --agent claude --prompt "$PROMPT" --setup run --json
orca worktree create --repo id:<repoId> --name fix-login-race-2 --agent codex --prompt "$PROMPT" --setup run --json
orca worktree create --repo id:<repoId> --name fix-login-race-3 --agent cursor --prompt "$PROMPT" --setup run --json📌 查證狀態:
orca worktree create的--agent、--prompt、--setup選項為官方文件明確記載;Agent 識別字(例如cursor)請以orca worktree create --help實際輸出為準|來源:Orca CLI reference
⚠️ 注意事項
- 三個 Agent 若都會啟動 dev server,可能搶同一個連接埠。可在 Prompt 中指定不同連接埠,或用
orca ports(v1.4.240 起)查看佔用情形。 - 若
orca.yaml將node_modules設為共享目錄,而 Agent 修法需要新增套件,三個 Worktree 會互相影響(見 2.3)。 - 三個 Agent 同時執行測試會使 CPU 滿載,請觀察 Resource Manager。
✅ 驗證方式
執行:
orca worktree ps --json git worktree list預期結果:列出三個
fix-login-race*Worktree,各自位於不同目錄、不同分支。判讀:若少一個,檢查側邊欄是否有失敗的進度列並點 Retry;若兩個 Worktree 指向同一分支,請刪除後重建。
5.5 分割窗格同時監看
📌 查證狀態:官方文件明確記載|來源:Your first session、Tabs, panes & split layouts、Agents & sessions
三個 Agent 在不同 Worktree 中工作時,有三種監看方式:
| 方式 | 做法 | 優點 |
|---|---|---|
| 分割窗格 | 用 Jump Palette(Cmd-J 或 Ctrl-J)選取其他 Worktree 時按 Shift-Enter,在分割中開啟;或拖曳 Tab 到窗格邊緣 | 同時看到三個終端機的即時輸出 |
| 側邊欄狀態 | 只看側邊欄每個 Worktree 的狀態圖示,等通知 | 不佔螢幕,可同時做其他事 |
| Agent Dashboard(實驗性) | Settings → Experimental 開啟後,依 Needs You、Working、Done、Idle 分欄顯示所有 Agent | 適合 Agent 數量多時集中管理 |
建議監看節奏(教學推論)
- 前 2 分鐘觀察每個 Agent 是否正確理解任務(例如是否先閱讀
src/auth/)。方向錯誤時立即中斷並修正 Prompt,比等它做完再重來省時間。 - 之後切換到側邊欄狀態監看,優先處理琥珀色問號(需要你)。
- 收到完成通知後,不要馬上審查第一個完成的——等三個都完成再一起比較,避免「先到先贏」的偏誤。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 可同時看到三個 Agent | 依上表建立分割 | 一個畫面中顯示三個 Agent 終端機 | 參考 2.5 的拖曳方式 |
| 需要你的 Session 被凸顯 | 有 Agent 等待權限時觀察側邊欄 | 出現琥珀色問號與 Needs You 計數 | 檢查 Agent 狀態 hooks |
| 完成通知 | Agent 完成時 | 收到桌面通知 | 檢查 Settings → Notifications 與作業系統通知權限 |
5.6 選出勝者並審查合併
📌 查證狀態:審查、Annotate AI Diff、Commit 與 Push、刪除 Worktree 為官方文件明確記載;評分表為教學示例(非官方)|來源:Your first session、Run parallel agents
步驟一:客觀比較
在主 checkout 執行,比較三個分支相對 origin/main 的變更規模:
for b in fix-login-race fix-login-race-2 fix-login-race-3; do
echo "== $b"
git diff --stat origin/main...$b | tail -1
done在每個 Worktree 中自行執行測試,不要只看 Agent 的報告:
npm test 2>&1 | tail -5步驟二:以評分表比較
| 評分項目 | 權重 | fix-login-race | fix-login-race-2 | fix-login-race-3 |
|---|---|---|---|---|
| 重現測試通過 | 必要條件 | 通過或不通過 | 通過或不通過 | 通過或不通過 |
| 完整測試套件通過 | 必要條件 | 通過或不通過 | 通過或不通過 | 通過或不通過 |
| 根本原因說明正確 | 30% | 1 至 5 分 | 1 至 5 分 | 1 至 5 分 |
| 變更範圍最小且集中 | 25% | 1 至 5 分 | 1 至 5 分 | 1 至 5 分 |
| 可讀性與符合團隊慣例 | 25% | 1 至 5 分 | 1 至 5 分 | 1 至 5 分 |
| 新增測試涵蓋邊界情況 | 20% | 1 至 5 分 | 1 至 5 分 | 1 至 5 分 |
步驟三:在 Orca 中審查勝者的 Diff
- 開啟勝者 Worktree 的 Diff 檢視(Source Control)。
- 使用 Annotate AI Diff 在需要修改的行留下意見,送回該 Agent 修正。
- 重複「審查 → 意見 → 修正」直到滿意,再次執行測試。
- 在 Orca 中 Commit 並 Push,建立 PR;PR 描述附上根本原因、測試結果與評分表。詳細審查流程見第十四章。
步驟四:清理落選 Worktree
- 在側邊欄多選落選的兩個 Worktree,執行 Delete(Cmd-Shift-Backspace 或 Ctrl-Shift-Backspace)。
- 確認對話框會同時刪除目錄與分支。
- 若出現「Review N Branches」提示,代表有分支因含未合併 commit 而被保留;確認不需要後再刪除。
orca worktree rm --worktree id:<worktreeId2> --json
orca worktree rm --worktree id:<worktreeId3> --json💡 小技巧:落選方案中若有好的測試案例,可以先 git cherry-pick 到勝者分支再刪除。
✅ 驗證方式
合併 PR 並清理後,在主 checkout 執行:
git fetch origin --prune git worktree list git branch --list "fix-login-race*" git log origin/main --oneline -3預期結果:
git worktree list只剩主 checkout(以及其他無關的 Worktree);fix-login-race*分支已不存在或只剩已合併的分支;origin/main最新 commit 包含勝者的修正。判讀:若落選分支仍存在,回到 Orca 處理「Review N Branches」提示,或確認無用後手動
git branch -D。
5.7 本章 Review 與驗證清單
- 主 checkout 在加入 Orca 前已
git fetch origin且狀態乾淨 - 交給 Agent 前已確認存在會失敗的重現測試
- Prompt 包含範圍限制、禁止事項與要求輸出的驗證證據
- 已建立三個 Worktree 並以同一份 Prompt 交給不同 Agent
- 已用分割窗格或 Agent Dashboard 同時監看
- 已在每個 Worktree 自行執行測試,而非只採信 Agent 報告
- 已用評分表選出勝者,並以 Annotate AI Diff 完成至少一輪修正
- 已清理落選 Worktree,並處理「Review N Branches」提示
第六章 Settings 設定總覽
Orca 的設定頁面數量多,而且隨版本快速增加。本章不逐項翻譯每個選項,而是依「企業需要決策的設定」分組說明,最後在 6.9 提供可直接採用的企業標準設定基準表。各設定的深入用法請見對應章節。
📌 查證狀態:設定頁面名稱與選項為官方文件明確記載(以 v1.4.244 為準);分組方式與建議值為依官方說明延伸(教學推論)|來源:Settings reference
6.1 設定分類總覽
開啟方式:應用程式選單 Settings,或快捷鍵 Cmd-,(Windows 與 Linux 為 Ctrl-,)。設定頁頂端的搜尋框可依關鍵字搜尋所有頁面的選項。v1.4.244 起介面可切換為繁體中文,但本手冊沿用英文選項名稱,以便對照官方文件。
| 頁面 | 主要內容 | 企業關注度 | 詳見 |
|---|---|---|---|
| General | Orca CLI、更新、Open in、縮放、預設 Worktree 名稱、編輯器預設 | 中 | 6.2 |
| Appearance | 主題、字型、Resource Manager、用量百分比、應用程式圖示、Language | 低 | 6.2 |
| Privacy | 匿名遙測開關 | 高 | 3.5、6.9 |
| Git | base ref 解析、commit 簽章、外部 git editor、Auto-Rename Branch、GitHub API Budget | 中 | 6.3 |
| Repository | 每個 repo 的 base ref、hooks、自動執行指令、圖示、Source Control AI 覆寫、Shared Paths | 中 | 6.3 |
| Terminal | 字型與主題、Ghostty 與 Warp 匯入、預設 shell 與參數、OSC 52、色彩對比 | 中 | 6.4 |
| Quick Commands | 全域或專案範圍的常用指令 | 低 | 6.4 |
| Agents | 已安裝 Agent、啟動參數、權限模式、信任資料夾、帳號、hooks、保持喚醒、skill 更新 | 高 | 6.5 |
| Chat | Native Chat 行為、供應商、外觀、內嵌視覺、Chat 命名 | 中 | 6.5 |
| Browser | Profiles、縮放、Design Mode、Devtools、連結路由、搜尋引擎 | 中 | 6.6 |
| Artifacts | 公開分享連結 | 高 | 6.6 |
| Integrations | GitHub、Linear、Jira、Bitbucket、MiniMax、MCP servers | 高 | 6.6 |
| Notifications | 通知類別、音效、各機器開關、PR Checks 失敗、可更新提示 | 低 | 6.6 |
| Voice | 聽寫、麥克風、本機或雲端模型 | 中 | 6.6 |
| SSH | 目標主機、身分、跳板、連線重用、Allow host orca CLI、受管 server | 高 | 6.7 |
| Remote Orca Servers | 伺服器清單、Add server、Advertise、機器名稱 | 高 | 6.7 |
| Shortcuts | 快捷鍵 | 低 | 2.5 |
| Floating Workspace | 浮動工作區 | 低 | — |
| Session History、Tasks、Accounts、Agent Orchestration | Session 歷史、任務來源、帳號、Orchestration heartbeat | 中 | 第八、九、十一章 |
| Plugins(實驗性) | 外掛系統與 marketplace | 高 | 6.8 |
| Experimental | Activity Page、Agent Dashboard、Hibernation、Browser extensions、Chat UI、Cloud VM 等 | 高 | 6.8 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 可開啟設定 | 按 Cmd-, 或 Ctrl-, | 開啟 Settings 視窗 | 從應用程式選單開啟 |
| 設定搜尋可用 | 在搜尋框輸入 telemetry 或 usage data | 跳到 Privacy 的 Share anonymous usage data | 確認版本為 v1.4.244 附近,舊版頁面名稱可能不同 |
| 頁面與本表一致 | 逐頁瀏覽左側清單 | 與上表大致相符 | 以實際版本為準,並回報文件維護者更新本表 |
6.2 General Appearance 與語言
📌 查證狀態:官方文件明確記載|來源:Settings reference
General
| 選項 | 說明 | 建議 |
|---|---|---|
| Orca CLI | 註冊 orca(Linux 為 orca-ide)到 PATH | 開啟;Agent 與自動化都需要它 |
| Updates | 自動更新與 Check for Updates | 依 4.7 的企業版本策略 |
| Open in | 預設以哪個外部編輯器或終端機開啟 Worktree | 設為團隊標準 IDE |
| UI zoom | 介面縮放 | 個人偏好 |
| Default worktree name | 名稱留白時的命名方式 | 個人偏好 |
| 編輯器預設 | Word wrap、Preview tab、Diff 摺疊未變更區塊 | 建議開啟摺疊未變更區塊,方便審查 |
| Workspace 來源預設 | 側邊欄顯示哪些 Worktree 來源(例如 Non-Orca worktrees) | 預設即可 |
Appearance
| 選項 | 說明 |
|---|---|
| Theme、accent color、density | 主題與密度;已安裝的外掛可新增主題 |
| Fonts | 介面與編輯器字型 |
| Resource Manager | 狀態列顯示資源監控(建議開啟,見 3.1) |
| Usage percentages | 在狀態列顯示 Agent 用量百分比(見第八章) |
| App icon | 應用程式圖示 |
| Language | System、English、简体中文、繁體中文、한국어、日本語、Español、Deutsch、Русский、Türkçe |
範例:切換為繁體中文介面
- 開啟 Settings → Appearance → Language。
- 選擇 繁體中文(v1.4.244 新增);若選 System,則依作業系統語言決定。
- 依提示重新載入介面。
⚠️ 注意事項:繁體中文介面為新功能,部分字串可能仍為英文或翻譯與本手冊不同。撰寫內部 SOP 或回報問題時,建議同時附上英文選項名稱,以便對照官方文件。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 語言已切換 | 切換後查看側邊欄與設定頁 | 主要介面為繁體中文 | 確認版本為 v1.4.244 以上,重新啟動 Orca |
| CLI 已註冊 | 新終端機執行 orca status --json | 輸出狀態 JSON | 見 4.2 至 4.4 |
| Resource Manager 顯示 | 查看狀態列 | 出現 CPU 與記憶體資訊 | 在 Appearance 開啟 |
6.3 Git 與 Repository 設定
📌 查證狀態:官方文件明確記載|來源:Settings reference、Worktrees
Git(全域)
| 選項 | 說明 | 企業建議 |
|---|---|---|
| Base ref 解析 | 決定預設以哪個遠端分支為起點 | 維持預設,個別 repo 在 Repository 頁覆寫 |
| Commit signing | commit 簽章選項 | 若組織要求簽章 commit,必須開啟並在 git 設定好簽章金鑰 |
| External git editor | 外部 git 編輯器 | 個人偏好 |
| Auto-Rename Branch From Work | Agent 開始工作後,把 Orca 產生的海洋生物分支名改為有意義的名稱 | 建議開啟,方便審查與追蹤 |
| GitHub API Budget | 顯示本機 gh 的 REST、Search、GraphQL 剩餘額度 | PR Checks 或 Tasks 停止更新時先看這裡 |
Repository(每個 repo)
| 選項 | 說明 |
|---|---|
| Base ref | 覆寫此 repo 的預設起點 |
| Hooks | 建立 Worktree 後的 setup 指令,例如 pnpm install --frozen-lockfile |
| Auto-run commands | 建立 Worktree 時自動執行的指令 |
| Icons | repo 圖示 |
| Source Control AI overrides | 此 repo 的 AI commit message 等覆寫設定 |
| Worktree Shared Paths | 個人層級的共享路徑(見 2.3) |
範例:確認 commit 簽章已設定
git config --get commit.gpgsign
git config --get gpg.format
git config --get user.signingkey✅ 驗證方式
在 Orca 建立的 Worktree 中做一次測試 commit:
git commit --allow-empty -m "chore: verify signing" git log -1 --show-signature預期結果:
git log顯示Good signature或 SSH 簽章驗證成功字樣。判讀:若未簽章,檢查 Settings → Git 的簽章選項與上述
git config值;驗證完成後以git reset --hard HEAD~1移除測試 commit(僅在此測試 Worktree 中執行)。
6.4 Terminal 與 Quick Commands
📌 查證狀態:官方文件明確記載|來源:Settings reference、Terminal
Terminal
| 選項 | 說明 | 建議 |
|---|---|---|
| Font、theme | 終端機字型與主題 | 個人偏好 |
| Ghostty 與 Warp 匯入 | 匯入既有終端機設定 | 首次設定時使用 |
| Default shell 與參數 | Windows 可選 PowerShell、CMD 或 WSL;macOS 與 Linux 可加 -l 等參數 | 使用 login shell,確保 PATH 與工具鏈正確 |
| Allow TUI Clipboard Writes(OSC 52) | 預設開啟;允許 tmux、Neovim 等透過 PTY(包含 SSH)寫入系統剪貼簿 | 一般開發維持開啟;高監理環境可評估關閉 |
| Color contrast | 色彩對比調整 | 依無障礙需求 |
⚠️ 注意事項:OSC 52 開啟時,遠端主機上的程式(包括 Agent 執行的指令)可以寫入你的本機剪貼簿。這不會讓遠端讀取剪貼簿,但可能被用來置換你即將貼上的內容。處理敏感資料的團隊可考慮關閉。
Quick Commands
Quick Commands 是可一鍵執行的常用指令,有 Global 與 Project 兩種範圍;設定會標示「Saved on」哪台主機,並同步到行動 App。
範例:建議的團隊 Quick Commands(教學示例)
| 名稱 | 範圍 | 指令 |
|---|---|---|
| 測試 | Project | npm test |
| 型別檢查與 Lint | Project | npm run typecheck && npm run lint |
| 與 base 比較 | Global | git diff --stat origin/main...HEAD |
| 同步遠端 | Global | git fetch origin --prune |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Login shell 生效 | 新終端機執行 echo $0(PowerShell 執行 $PSVersionTable.PSVersion) | macOS 與 Linux 顯示 -zsh 或 -bash 等以連字號開頭的 login shell | 在 Default shell 參數加入 -l |
| 工具鏈在 PATH | 新終端機執行 command -v node git claude | 全部有輸出 | 檢查 shell profile 與 login shell 設定 |
| OSC 52 符合政策 | Settings → Terminal | 開關狀態與 6.9 基準一致 | 依基準調整 |
| Quick Command 可執行 | 執行「測試」Quick Command | 在目前 Worktree 執行並顯示結果 | 確認範圍為 Project 且在正確 repo |
6.5 Agents 與 Chat 設定
📌 查證狀態:官方文件明確記載|來源:Settings reference、Supported agents、Agent hooks & memory
Settings → Agents 是企業導入時最重要的設定頁面。
| 選項 | 說明 | 預設 | 企業考量 |
|---|---|---|---|
| Installed agents | 偵測到的 Agent CLI 清單 | 自動偵測 | 只保留組織核准的 Agent |
| Command、Args、Env | 每個 Agent 的啟動指令、參數與環境變數;Reset 還原預設 | 完全自主旗標 | 自訂參數會優先於全域權限模式 |
| Agent permissions | Manual、Auto、Yolo;Auto 適用 Claude、Claude Agent Teams、Codex,其他 Agent 由 Other agents 決定 | 依版本而定,請實際檢查 | 見 6.9 |
| Trust the folder when Orca starts an agent | Orca 啟動的 Agent(含 Orchestration worker、自動化、手機啟動的 Agent)略過「是否信任此資料夾」提示 | 開啟 | 高監理環境建議關閉 |
| Codex own server | 每個 Codex Tab 使用獨立 server | 開啟 | 維持開啟 |
| Accounts | Claude、Codex、OpenCode、Devin、Antigravity、GLM 等帳號管理 | — | 只登入公司核准的帳號,見第八章 |
| Agent status hooks | 讓 Agent 回報狀態給 Orca | 開啟 | 維持開啟,可用 orca agent hooks status --json 檢查 |
| Keep computer awake | On、Agent(Agent 工作時保持喚醒)、Off;狀態列咖啡圖示同步 | — | 建議 Agent |
| Skill freshness | 提示已安裝的 Orca skills 是否過期 | — | 維持開啟,見第七章 |
範例:把 Claude Code 與 Codex 改為較保守的啟動參數
| Agent | 在 Settings → Agents 的 Args 欄位填入 | 效果 |
|---|---|---|
| Claude Code | --permission-mode acceptEdits | 自動接受檔案編輯,但執行指令前詢問 |
| Codex | --sandbox workspace-write --ask-for-approval on-request | 只能寫入工作目錄,需要時請求核准 |
📌 查證狀態:上述旗標為各 Agent CLI 自身的選項,非 Orca 定義;請以
claude --help、codex --help的實際輸出為準|來源:Supported agents
⚠️ 注意事項:自訂 Args 後,全域權限模式切換不會覆蓋這個 Agent。若組織以全域模式作為管控手段,請避免讓使用者自訂參數,或在稽核時兩者都檢查。
Settings → Chat
v1.4.223 起提供,用於 Native Chat(需在 Settings → Experimental 開啟 Chat UI)。
| 區塊 | 內容 |
|---|---|
| Behavior | Chat 行為設定 |
| Providers | Chat 使用的供應商 |
| Appearance | Chat 外觀 |
| Inline visuals | 內嵌圖表或視覺化呈現 |
| Chat names | Chat 命名方式 |
Native Chat 的權限模式自 v1.4.241 起統一於 Settings → Agents 管理,不在 Chat 頁面。
✅ 驗證方式
在 Settings → Agents 截圖或記錄 Agent permissions、Trust the folder、各 Agent Args 的目前值。
執行:
orca agent hooks status --json啟動 Claude Code 與 Codex 各一個 Tab,用 2.4 的
ps或Get-CimInstance指令檢查實際啟動參數。預期結果:hooks 狀態為已啟用;實際參數與你在設定頁看到的一致,且符合 6.9 基準。
判讀:若實際參數包含
--dangerously-skip-permissions而你的政策是 Manual,代表權限模式未生效或有殘留的自訂 Args,請按 Reset 後重新設定。
6.6 Browser Integrations 與 Notifications
📌 查證狀態:官方文件明確記載|來源:Settings reference、Browser profiles、Notifications
Browser
| 選項 | 說明 | 企業考量 |
|---|---|---|
| Profiles | 瀏覽器 profile(cookie 與登入狀態隔離),可匯入既有瀏覽器 cookie | 匯入 cookie 會讓 Agent 能以你的身分瀏覽;只在必要時匯入,見第十三章 |
| Default zoom、Design Mode 預設 | 瀏覽器縮放與設計模式 | 個人偏好 |
| Devtools | 開發者工具 | 個人偏好 |
| Remote rendering、Browse via SSH host | 透過 SSH 主機瀏覽遠端服務 | 依需求 |
| Link Routing | 終端機、Markdown、編輯器中的連結以 Orca 瀏覽器或系統瀏覽器開啟;按住 Shift 反轉一次 | 個人偏好 |
| Search engine | 搜尋引擎 | 依公司政策 |
Artifacts
Artifacts 讓你把本機 HTML 或 Markdown 頁面分享為公開連結(單檔上限 10 MiB)。發布功能預設關閉。
| 選項 | 說明 |
|---|---|
| Show Artifacts | 開啟 Artifacts 清單,搜尋、預覽、複製或刪除連結 |
| Ask Before Deleting Artifacts | 刪除公開連結前確認 |
⚠️ 注意事項:Artifact 是公開連結,任何取得網址的人都能存取。企業環境除非已完成資料分類審查,否則應維持關閉。
Integrations
| 整合 | 認證方式 | 備註 |
|---|---|---|
| GitHub | OAuth;PR 與 Checks 也使用本機 gh | 見第十五章 |
| Linear | API token | — |
| Jira | Cloud:email 加 API token;Data Center:PAT 或 basic | 見第十五章 |
| Bitbucket | Token;ORCA_BITBUCKET_* 環境變數優先於 UI 設定 | 方便以集中派送的環境變數設定 |
| MiniMax | API key | — |
| MCP servers | MCP 伺服器設定 | 每個 MCP server 都是新的資料出口,需審查,見第七章 |
Notifications 與 Voice
| 頁面 | 重點選項 |
|---|---|
| Notifications | 通知類別(Agent 完成、需要你等)、音效、Machines(各機器分別關閉桌面通知)、PR Checks 失敗、可更新提示 |
| Voice | 聽寫開關、麥克風、Toggle 或 Hold 模式;模型可選本機 Parakeet、SenseVoice、Whisper,或雲端 GPT-4o |
⚠️ 注意事項:選用雲端聽寫模型時,語音內容會送到該供應商。若口述內容可能包含客戶資料,請使用本機模型。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Artifacts 未發布 | Settings → Artifacts → Show Artifacts | 清單為空,或只有經核准的項目 | 刪除不應公開的 Artifact |
| Integrations 僅連核准服務 | 逐一檢查 Settings → Integrations | 只有組織核准的服務已連線 | 中斷未核准的連線並撤銷其 token |
| MCP servers 已審查 | 檢查 Settings → Integrations 的 MCP servers 清單 | 每個都在核准清單中 | 移除未核准者 |
| Voice 使用本機模型 | Settings → Voice | 模型為 Parakeet、SenseVoice 或 Whisper | 依政策切換 |
| 通知可達 | 讓 Agent 完成一個短任務 | 收到桌面通知 | 檢查作業系統通知權限 |
6.7 SSH 與 Remote Orca Servers 設定
📌 查證狀態:官方文件明確記載|來源:Settings reference、Remote servers
Settings → SSH
| 選項 | 說明 | 預設 | 企業建議 |
|---|---|---|---|
| Targets | SSH 目標主機清單 | — | 只加入公司管理的主機 |
| Identity | 使用的 SSH 金鑰 | — | 使用專用金鑰,不與正式環境共用 |
| Proxy 與 jump host | 透過跳板主機連線 | — | 依網路架構 |
| Reuse SSH connection | 使用系統 OpenSSH 多工加速 | 開啟 | 維持開啟 |
| Allow this host’s orca CLI to control Orca | 允許遠端主機上的 orca CLI 控制你的桌面 Orca | 關閉(v1.4.230 起) | 維持關閉,除非有明確需求 |
| Managed servers | 主機上受管 Orca server 的 Update、Roll back、Recover、Stop、Forget | — | 與桌面版維持相同版本 |
| Kerberos | 透過 GSSAPIAuthentication | — | 依企業身分系統 |
範例:使用跳板主機與 Kerberos 的 ~/.ssh/config
Host devbox
HostName devbox.internal.example.com
User alice
ProxyJump bastion.example.com
GSSAPIAuthentication yes
IdentityFile ~/.ssh/id_ed25519_orcaSettings → Remote Orca Servers
| 選項 | 說明 |
|---|---|
| Server list、Add server | 用戶端:貼上主機產生的存取連結以加入伺服器 |
| Advertise | 主機端:開始廣播此 Orca 為 Remote Orca Server,並以 New Link → Generate Access Link 產生存取連結 |
| Shared Server Access | 主機端:列出各用戶端 token,可個別撤銷 |
| Machine name | 顯示給其他用戶端的機器名稱 |
| Advanced → Active Server | 選擇目前使用的伺服器 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| SSH 連線可用 | ssh devbox git --version | 不需輸入密碼即可顯示 git 版本 | 檢查金鑰、跳板與 Kerberos 票證(klist) |
| Allow host orca CLI 關閉 | Settings → SSH 中每台主機的設定 | 皆為關閉 | 關閉,或記錄核准開啟的理由 |
| 受管 server 版本一致 | Settings → SSH 的 managed servers 清單 | 版本與桌面版相同 | 執行 Update |
| Remote Orca Server token 無多餘項目 | 主機端 Shared Server Access | 只有目前使用中的用戶端 | 撤銷不明或已離職人員的 token |
6.8 Experimental 與 Plugins
📌 查證狀態:官方文件明確記載|來源:Settings reference、Release notes
Settings → Experimental
實驗性功能可能變更或移除,企業環境應逐項評估後再開放。
| 功能 | 說明 | 企業建議(教學推論) |
|---|---|---|
| Activity Page | Agent 活動總覽頁 | 可開放 |
| Compact cards | 精簡的 Worktree 卡片 | 可開放 |
| Agent hibernation | 閒置 Agent 自動休眠(預設 30 分鐘)以釋放資源 | 建議開放,見第三十章 |
| Agent Dashboard | 依 Needs You、Working、Done、Idle 分欄管理 Agent | 建議開放 |
| Browser extensions | 在本機 profile 使用 Chrome 擴充功能(例如 Bitwarden、1Password);開啟後需重新啟動 | 需資安審查擴充功能清單 |
| Chat UI | Native Chat 介面 | 試點後開放 |
| Cloud VM | 每個 Worktree 一個以 recipe 定義的隔離環境 | 由平台團隊統一提供 recipe |
Settings → Plugins(實驗性)
- 先開啟外掛系統,再逐一審查並啟用每個外掛;未經你同意,任何外掛都不會執行。
- 可加入 git marketplace 來源,瀏覽、預覽能力(面板、指令、語言包、VM recipe)、安裝、更新或回滾。
- 外掛 worker 一律在本機執行。
- 官方明確表示:能力與 API 可能變動,第三方外掛應視為不受信任的軟體。
❌ 常見錯誤:為了試用某個主題或語言包,直接加入來源不明的 marketplace 並安裝外掛。外掛在本機執行,等同安裝任意軟體。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 實驗性功能符合政策 | 逐項檢查 Settings → Experimental | 只開啟核准的項目 | 關閉未核准的項目 |
| 外掛系統狀態 | Settings → Plugins | 依政策為關閉,或只有核准的外掛 | 停用並移除未核准的外掛 |
| Marketplace 來源 | Settings → Plugins 的 marketplace 清單 | 只有組織核准的 git 來源 | 移除未核准的來源 |
6.9 企業標準設定基準範例
📌 查證狀態:設定項目與預設值為官方文件明確記載;建議值、分級與稽核方式為依官方說明延伸(教學推論)。官方文件未記載集中式政策派送機制,以下基準需以人工檢查、腳本或軟體派送工具落實|來源:Settings reference、Telemetry、Supported agents
以下提供兩種設定基準:標準適用一般企業開發團隊;高監理適用處理個資、金融、醫療等受監理資料的團隊。組織可依此建立自己的版本,並在每次升級 Orca 後重新檢查。
基準表
| 編號 | 設定路徑 | 官方預設 | 標準基準 | 高監理基準 | 理由 | 驗證方式 |
|---|---|---|---|---|---|---|
| B01 | Settings → Privacy → Share anonymous usage data | 開啟 | 依公司政策 | 關閉,且設定 ORCA_TELEMETRY_DISABLED=1 | 減少對外資料傳送 | UI 檢查;終端機 echo $ORCA_TELEMETRY_DISABLED 為 1 |
| B02 | Settings → Agents → Agent permissions | 完全自主(各 Agent 的 yolo 類旗標) | Auto | Manual | 預設旗標允許 Agent 不經詢問執行任何指令 | 用 ps 或 Get-CimInstance 檢查 Agent 啟動參數 |
| B03 | Settings → Agents 各 Agent 的 Args | 空白(使用預設) | 不自訂,或使用 6.5 的保守旗標 | 使用 6.5 的保守旗標並記錄 | 自訂 Args 會覆蓋全域權限模式 | 逐一檢查 Args 欄位 |
| B04 | Settings → Agents → Trust the folder when Orca starts an agent | 開啟 | 開啟 | 關閉 | 保留 Agent 自身的資料夾信任確認 | UI 檢查;啟動 Agent 時是否出現信任提示 |
| B05 | Settings → Agents → Agent status hooks | 開啟 | 開啟 | 開啟 | 狀態可見性是人工監督的前提 | orca agent hooks status --json |
| B06 | Settings → Agents → Keep computer awake | 依版本 | Agent | Agent | 長任務不中斷,且不讓電腦永遠不休眠 | 狀態列咖啡圖示 |
| B07 | Settings → SSH → Allow this host’s orca CLI to control Orca | 關閉 | 關閉 | 關閉 | 避免遠端主機控制桌面 | 每台主機逐一檢查 |
| B08 | Settings → Remote Orca Servers → Advertise | 關閉 | 只在 Tailscale 或內網開啟 | 關閉,或僅限核准主機 | 存取連結等同密碼 | 檢查廣播位址;檢查 Shared Server Access |
| B09 | Settings → Artifacts 發布 | 關閉 | 關閉 | 關閉 | 公開連結可能外洩資料 | Show Artifacts 清單為空 |
| B10 | Settings → Integrations → MCP servers | 無 | 只加入核准清單 | 只加入核准清單並記錄用途 | 每個 MCP 都是資料出口 | 比對核准清單 |
| B11 | Settings → Voice 模型 | — | 本機模型優先 | 僅本機模型 | 雲端模型會傳送語音 | UI 檢查 |
| B12 | Settings → Terminal → Allow TUI Clipboard Writes(OSC 52) | 開啟 | 開啟 | 評估後關閉 | 避免遠端程式置換剪貼簿 | UI 檢查 |
| B13 | Settings → Git → Commit signing | 依使用者 | 依公司政策 | 開啟 | 追蹤 commit 來源 | git log -1 --show-signature |
| B14 | Settings → Plugins | 關閉 | 只啟用核准外掛 | 關閉 | 外掛為本機執行的不受信任軟體 | UI 檢查 |
| B15 | Settings → Experimental | 皆關閉 | 開啟 Agent Dashboard、Hibernation | 只開啟 Agent Dashboard | 實驗性功能可能變動 | 逐項檢查 |
| B16 | Settings → Browser → Profiles cookie 匯入 | 未匯入 | 僅匯入測試帳號 | 不匯入 | 避免 Agent 以個人身分操作網站 | 檢查 profiles 清單 |
| B17 | Settings → General → Updates | 自動更新 stable | 自動更新 stable | 由 IT 派送指定版本 | 版本一致性與變更管理 | 比對 About Orca 版本與內部基準 |
⚠️ 注意事項
- 以上「官方預設」以 v1.4.244 文件為準;部分項目(例如 Agent permissions 的預設)可能隨版本調整,請在每次升級後依「驗證方式」欄實際檢查,而非依賴本表。
- B02 選擇 Auto 時,只有 Claude、Claude Agent Teams、Codex 支援;其他 Agent 依 Other agents 設定,請一併設為 Manual。
範例:基準檢查腳本(可自動化的部分)
#!/usr/bin/env bash
# orca-baseline-check.sh:只能檢查可由指令取得的項目,其餘需人工檢查
echo "B01 遙測環境變數:${ORCA_TELEMETRY_DISABLED:-未設定}"
echo "B05 Agent hooks:"; orca agent hooks status --json
echo "B02 執行中的 Agent 啟動參數:"
ps -eo args | grep -E "^(claude|codex|gemini|cursor-agent|copilot)" | grep -v grep || echo " (目前無執行中的 Agent)"
echo "B02 危險旗標檢查:"
ps -eo args | grep -E "dangerously|--yolo" | grep -v grep && echo " [警告] 發現完全自主旗標" || echo " [OK] 未發現完全自主旗標"
echo "B13 commit 簽章:$(git config --global --get commit.gpgsign || echo 未設定)"稽核紀錄範本
Orca 設定基準稽核紀錄
稽核日期:2026-10-30
受稽核者:alice(工程部)
Orca 版本:1.4.244
適用基準:標準/高監理(擇一)
B01 遙測:符合/不符合,證據:Privacy 截圖、環境變數輸出
B02 權限模式:符合/不符合,證據:Agents 截圖、ps 輸出
B03 自訂 Args:符合/不符合,證據:Agents 截圖
B04 至 B17:逐項記錄
不符合事項與改善期限:
稽核人簽名:✅ 驗證方式
依基準表逐項檢查,並執行基準檢查腳本:
bash orca-baseline-check.sh | tee orca-baseline-$(date +%Y%m%d).log預期結果:所有項目符合選定基準;腳本輸出
[OK] 未發現完全自主旗標(標準與高監理基準皆應如此)。判讀:任何不符合項目都記入稽核紀錄並指定改善期限。若腳本發現完全自主旗標,先確認是否為 B03 的自訂 Args 造成,再按 Reset 修正。
6.10 本章 Review 與驗證清單
- 能用 Cmd-, 或 Ctrl-, 開啟設定並以搜尋找到指定選項
- 已將介面語言設定為團隊慣用語言,並知道英文選項名稱以對照官方文件
- 已確認 commit 簽章符合組織政策
- 已設定 login shell,且 Agent 終端機中的工具鏈完整
- 已在 Settings → Agents 設定權限模式,並以行程參數驗證實際生效
- 已確認 Artifacts、Integrations、MCP servers、Voice 只使用核准的服務
- 已確認每台 SSH 主機的 Allow host orca CLI 為關閉
- 已審查 Experimental 與 Plugins 的開啟項目
- 已選定 6.9 的標準或高監理基準,完成逐項檢查並保存稽核紀錄
第七章 支援的 Agent CLI 與個別整合
本章說明 Orca v1.4.244 內建支援的 Agent CLI、各 Agent 的整合深度差異、權限預設,以及 Claude Code、Codex、Cursor CLI、GLM 系列與 Native Chat 的個別設定方法。讀完本章,你應該能為團隊選定 Agent 組合、寫出可審查的啟動設定,並親手驗證 Agent 是以預期的帳號、權限與模型在正確的 Worktree 內執行。
先建立一個關鍵心智模型:Orca 不是模型供應商,也不是 Agent 本身。Orca 的 Agent 下拉選單(agent combobox)本質上是「在某個 Worktree 的終端機裡啟動一個 CLI 行程」。模型、認證、計費都屬於該 CLI 與其供應商;Orca 負責的是隔離(Worktree)、啟動(預設參數)、觀測(狀態、用量)、續接(Session History、Hibernation)與審查(Diff、Review)。
7.1 支援的 Agent 完整清單
📌 查證狀態:官方文件明確記載|來源:Supported agents、GitHub README Supported Agents
概念說明
官方 README 的原則是「Works with any CLI agent」:只要能在終端機執行,就能在 Orca 執行。但「能執行」與「深度整合」差很多。官方把內建 Agent 依整合能力分成幾個層次,本書用下表的術語統一稱呼:
| 整合能力 | 意義 | 對日常工作的影響 |
|---|---|---|
| Auto-setup | 出現在內建 Agent 選單,一鍵啟動並帶入預設參數 | 不必手打指令,權限旗標自動帶入 |
| Status | 能回報 working/waiting/done 狀態 | 側欄、Dashboard、通知能正確反映進度 |
| Hooks | 透過 Agent hook 回報細緻狀態 | 能偵測「等待你回答」等狀態 |
| Usage | 讀取用量與 Rate Limit | 狀態列可看到距離限額多遠 |
| Hot-swap/Accounts | 多帳號一鍵切換 | 可分散限額、區分個人與公司帳號 |
| Session history/Resume | 掃描歷史對話並一鍵續接 | 可從 Agent Session History 續跑舊對話 |
| Structured native chat | 可用 Orca 的結構化聊天介面開啟 | 有 Rewind、排隊訊息、內嵌 Diff 卡等 |
| Supervised workers | 可作為 Orchestration 的受監督 worker | 可被協調者 Agent 分派任務(見第十六章) |
| Deep integration | 上述多項整合到最完整 | Claude Code、Codex、Cursor CLI、Muse Code 等 |
完整清單(v1.4.244,2026-10-30 查證)
下表合併官方 README「Supported Agents」與官方文件「Supported agents」兩處來源,共 43 項(其中 Claude Agent Teams 是 Claude Code 的團隊模式條目;MiMo Code 與 OpenClaude 僅見於 README 清單)。廠商欄連結到該 Agent 的官方說明;官方 Orca 文件未附連結者,連到 Orca 的 Supported agents 頁供讀者自行追查。
| 序 | Agent | 廠商/官方連結 | Orca 整合能力與備註 |
|---|---|---|---|
| 1 | Claude Code | Anthropic | Deep integration:用量、Hot-swap、Hooks、每帳號獨立設定資料夾;支援 Structured chat、Subagent 子列 |
| 2 | Claude Agent Teams | Anthropic(Orca 說明) | 預設停用;於 Settings → Agents 啟用後以 orca claude-teams 啟動,每位 teammate 有原生窗格;支援 Auto 權限模式 |
| 3 | Codex | OpenAI | Deep integration:用量、Hot-swap、每 tab 獨立 server、Task subagent 子列、Structured chat |
| 4 | Muse Code | Meta | Deep integration:Hooks、狀態、用量(本機 token 計算、無價格估算)、Session history;可作 supervised worker |
| 5 | Grok | xAI | Auto-setup;Structured native chat(含 model/effort 選擇) |
| 6 | GitHub Copilot CLI | GitHub | Auto-setup;預設帶 --yolo;v1.4.221 修正 ~/.copilot/config.json 權限 |
| 7 | OpenCode | OpenCode | Auto-setup、狀態、帳號 profile、Structured chat;支援 OpenCode 2 beta |
| 8 | Pi | Pi | Auto-setup、Hooks、狀態、Structured chat;背景 helper 以子列顯示 |
| 9 | ZCode | Z.ai | Auto-setup、Hooks、狀態、Session resume、用量、supervised workers;需安裝含終端 UI 的 zcode 版本 |
| 10 | DeepSeek Harness | DeepSeek Harness | Auto-setup、Hooks、狀態、提問、Resume;以 dsh-tui profile 啟動 |
| 11 | OMP(oh-my-pi) | OMP | Auto-setup、Hooks、狀態、Structured chat;背景 helper 以子列顯示 |
| 12 | Prime Agent | Prime Intellect(Orca 說明) | Auto-setup、Hooks、狀態、Session history |
| 13 | Gemini | Google(Orca 說明) | Auto-setup;預設帶 --yolo;可被 Hibernation 續接 |
| 14 | Antigravity | Auto-setup、Hooks、狀態、帳號;本機 supervised workers;IDE 與 2.0 對話可接續到新 CLI 對話;Structured chat 需安裝其 chat server | |
| 15 | Ante | Ante(Orca 說明) | Auto-setup、狀態 |
| 16 | Aider | Aider(Orca 說明) | Auto-setup |
| 17 | Goose | Block | Auto-setup |
| 18 | Amp | Amp | Auto-setup |
| 19 | Kilocode | Kilo | Auto-setup |
| 20 | Kiro | Kiro | Auto-setup、狀態、Session history |
| 21 | Charm Crush | Charm | Auto-setup;預設帶 --yolo |
| 22 | Auggie | Augment | Auto-setup |
| 23 | Autohand Code | Autohand | Auto-setup |
| 24 | Cline | Cline | Auto-setup |
| 25 | CodeBuddy | CodeBuddy | Auto-setup、Hooks、狀態、Session history;安裝:npm install -g @tencent-ai/codebuddy-code |
| 26 | Codebuff | Codebuff | Auto-setup |
| 27 | Freebuff | Freebuff | Auto-setup、狀態 |
| 28 | Command Code | Command Code | Auto-setup、狀態;預設帶 --yolo |
| 29 | Continue | Continue | Auto-setup |
| 30 | Cursor CLI | Cursor | Deep integration:OSC 狀態偵測、Restart chip、方案用量顯示;預設帶 --yolo |
| 31 | Devin | Devin | Auto-setup、帳號 profile;v1.4.244 新增 Devin Desktop「Open In」 |
| 32 | Droid(Factory) | Factory | Auto-setup、Hooks、狀態 |
| 33 | Kimi | Moonshot | Auto-setup;預設帶 --yolo;用量追蹤(Kimi Code) |
| 34 | Mistral Vibe | Mistral | Auto-setup |
| 35 | MiniMax | MiniMax(Orca 說明) | Auto-setup、用量與 Rate Limit 追蹤 |
| 36 | Qoder CLI | Qoder(Orca 說明) | Auto-setup、Hooks、狀態、Workspace trust、Session resume、supervised workers;含 Qoder CLI CN |
| 37 | Qwen Code | Qwen | 透過已安裝的 qwen 執行檔 Auto-setup;supervised workers |
| 38 | Rovo Dev | Atlassian | Auto-setup;透過 acli 偵測;預設帶 --yolo |
| 39 | Hermes Agent | Nous Research | Auto-setup;預設帶 --yolo |
| 40 | OpenClaw | OpenClaw(Orca 說明) | Auto-setup;可設定 GLM 等模型(見 7.6) |
| 41 | Trae | Trae(Orca 說明) | 透過 traecli(TRAE CN CLI)Auto-setup |
| 42 | MiMo Code | Xiaomi | 列於 README;可被 Agent Hibernation 續接 |
| 43 | OpenClaude | OpenClaude | 列於 README |
| — | 任何 CLI Agent | — | 未列名的 CLI 可在一般終端機執行,但沒有預設參數、狀態偵測與用量整合 |
與舊版(v1.4.150)相比的主要變化
| 項目 | 舊版手冊 | v1.4.244 現況 |
|---|---|---|
| 具名 Agent 數 | 29 個 | 43 項(官方兩處清單合併) |
| Gemini | 被視為「僅萬用支援」 | 已是內建 Auto-setup 條目,可 Hibernation 續接 |
| 新增內建 | — | Muse Code(v1.4.211)、ZCode(v1.4.214)、DeepSeek Harness/Freebuff/Qoder/CodeBuddy(v1.4.218)、Qoder CLI CN/Qwen Code/GLM Coding Plans(v1.4.221)、Rovo Dev 經 acli 偵測(v1.4.223)、OpenCode 2(v1.4.206) |
| 用量追蹤範圍 | Claude、Codex、Gemini、OpenCode、Kimi、MiniMax | 另含 Muse Code、Antigravity、Cursor、ZCode、GLM Coding Plan(見第八章) |
| 權限模式 | 只有預設 Yolo | Manual/Auto/Yolo 三段(v1.4.232) |
📌 查證狀態:版本時間軸依官方 release notes 整理|來源:Orca Releases
操作步驟:確認本機偵測到哪些 Agent
- 開啟 Settings → Agents,檢視 Installed agents 區塊,確認團隊核准的 CLI 已被偵測。
- 對不打算使用的 Agent 關閉啟用開關,讓啟動選單只出現核准清單。
- 在任一 Worktree 開新分頁,展開 Agent 下拉選單,確認清單與上一步一致。
- 對清單中「未偵測到」的 Agent,先在一般終端機確認 CLI 在 PATH 上並已登入。
範例:在終端機確認 CLI 安裝與 PATH
# macOS / Linux:確認常用 Agent CLI 是否在 PATH 上
for bin in claude codex cursor-agent gemini opencode copilot; do
printf '%-14s ' "$bin"; command -v "$bin" || echo "(not found)"
done# Windows PowerShell:同樣檢查
'claude','codex','cursor-agent','gemini','opencode','copilot' |
ForEach-Object { $c = Get-Command $_ -ErrorAction SilentlyContinue; '{0,-14} {1}' -f $_, ($(if ($c) { $c.Source } else { '(not found)' })) }✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| CLI 已安裝 | 執行上方腳本 | 核准清單內的 CLI 都顯示路徑 | 依該 CLI 官方文件安裝,並確認 PATH |
| Orca 偵測到 CLI | Settings → Agents → Installed agents | 核准的 CLI 皆列出且為啟用 | 重新啟動 Orca;仍未出現則在設定中指定 binary 路徑 |
| 選單已收斂 | 新分頁的 Agent 下拉選單 | 只看到核准清單內的 Agent | 回到 Settings → Agents 關閉未核准者 |
| 狀態可偵測 | 從選單啟動一個 Agent 並送出簡單指令 | 分頁出現 spinner,完成後變綠色 | 確認是從選單啟動而非手打指令;見 10.1 |
⚠️ 注意事項
- 官方近乎每日發版,Agent 清單會持續增加。企業的「核准 Agent 清單」應該是官方清單的子集合,並記錄核准日期與 Orca 版本。
- 清單中「Auto-setup」僅代表 Orca 會幫你啟動;Agent 本身的資料傳輸、模型與合規性仍需依該供應商條款評估(見第二十八章)。
企業治理考量:建議由平台團隊維護一份「核准 Agent 白名單」,每季對照官方清單複核一次,並將 Settings → Agents 的啟用狀態納入第六章的「企業標準設定基準」。
7.2 權限預設與安全模式
📌 查證狀態:官方文件明確記載|來源:Supported agents → Permissions default、Settings、Agents & sessions
概念說明
Orca 的設計前提是「Worktree 本身就是沙箱」:Agent 在一份可拋棄的 checkout 中工作,你在合併前仍可以檢視、挑選或丟棄 Diff。因此 Orca 預設為每個支援的 CLI 帶入「略過權限確認」的旗標:
| Agent | Orca 預設帶入的旗標 |
|---|---|
| Claude Code | --dangerously-skip-permissions |
| Codex | --dangerously-bypass-approvals-and-sandbox |
| Gemini、Cursor、Crush、Kimi、Rovo Dev、Hermes、GitHub Copilot、Command Code | --yolo |
| 其他有對應旗標的 Agent | 各自的等效旗標 |
自 v1.4.232 起,Orca 提供三段式權限模式,於 Settings → Agents → Agent Permissions 設定,適用於「新的」終端機與 Structured chat 工作階段:
| 模式 | 行為 | 支援範圍 | 適用情境 |
|---|---|---|---|
| Manual | 保留 Agent 自身的逐項確認 | 所有 Agent | 高監理專案、正式環境腳本、新手教學 |
| Auto | 由 Agent 自行核准例行動作,高風險動作仍會詢問 | Claude、Claude Agent Teams、Codex | 一般開發的平衡選擇 |
| Yolo | 帶入完全略過確認的旗標 | 所有有旗標的 Agent | 一次性實驗、同題競賽、已隔離的 Worktree |
選擇 Auto 時,可在 Other agents 為不支援 Auto 的 Agent 指定 Manual 或 Yolo。另有幾個重要規則:
- 既有工作階段不受影響:已開啟的 chat 保留其啟動時的模式;改預設或切換模型都不會變更它。
- 自訂參數優先:若你已在某 Agent 的 launch arguments 或環境變數填了非空的自訂值,Orca 視為「明確覆寫」,全域切換不會動到它,該 Agent 也會退出後續的權限模式遷移。
- v1.4.241 起:Settings → Chat 原本的獨立 permission 下拉已移除,統一到 Settings → Agents。
- 資料夾信任:Settings → Agents → Trust the folder when Orca starts an agent 預設開啟,Orca 啟動的 Agent(含 Orchestration worker、Automations、手機啟動)會略過「是否信任此資料夾」提示;關閉後保留各 Agent 自身的信任提示。
- Codex chat 的 Ask mode:Structured Codex chat 在 Ask 模式下維持唯讀,直到 Codex 提出編輯請求並由你核准;也可在建立時選 Approve for me 或 Full access。權限選擇影響「下一回合」,執行中的回合維持原權限。
操作步驟:為團隊設定安全的預設
- 開啟 Settings → Agents → Agent Permissions。
- 選擇 Auto(建議的企業預設),並在 Other agents 選 Manual。
- 若專案屬於高監理範圍,回到 Settings → Agents,將 Trust the folder when Orca starts an agent 關閉。
- 若只想讓某一個 Agent 恢復逐項確認,展開該 Agent 列,編輯其 Arguments,移除略過權限的旗標(此即成為明確覆寫)。
- 需要復原出廠旗標時,按該欄位旁的 Reset。
範例:Claude Code 的三種啟動參數對照
# Yolo(Orca 出廠預設)
claude --dangerously-skip-permissions
# Manual(移除旗標,保留 Claude 自身逐項確認)
claude
# 自訂覆寫:限制允許的工具(示意,旗標以 Claude Code 官方文件為準)
claude --permission-mode acceptEdits📌 查證狀態:前兩行依官方文件;第三行
--permission-mode屬 Claude Code 自身旗標,依官方說明延伸(教學推論),請以claude --help輸出為準|來源:Supported agents
範例:權限決策表(建議納入團隊規範)
| 條件 | 建議模式 | 理由 |
|---|---|---|
Worktree 內含正式環境憑證(.env.production) | Manual | 避免 Agent 自行執行可觸及正式環境的指令 |
任務需要執行 terraform apply、kubectl、資料庫遷移 | Manual | 高破壞性動作必須人工確認 |
| 一般功能開發、單元測試修正 | Auto | 例行動作自動、危險動作仍詢問 |
| 同題競賽、Spike、拋棄式原型 | Yolo | Worktree 可丟棄,追求速度 |
| SSH 遠端主機上的共用 checkout | Manual 或 Auto | 遠端主機可能有其他人的資料 |
範例 Prompt:請 AI 依專案特性產出權限設定建議
你是本公司的開發平台工程師。請根據下列專案資訊,為 Orca 的 Settings → Agents → Agent Permissions
產出設定建議,輸出 Markdown 表格(欄位:Agent、建議模式、是否關閉 Trust the folder、理由)。
限制:
1. 只能使用 Manual、Auto、Yolo 三種模式;Auto 只能套用在 Claude、Claude Agent Teams、Codex。
2. 若專案涉及正式環境憑證或資料庫遷移,必須建議 Manual。
3. 不得建議修改任何 Agent 的原始碼或安裝第三方外掛。
專案資訊:
- 專案:信用卡帳務批次(Java 21、Spring Batch)
- 使用 Agent:Claude Code、Codex、Gemini
- Worktree 中會存在 .env.local(測試資料庫連線)
- 需要執行 Flyway 遷移到測試資料庫🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- Gemini 沒有被建議為 Auto(官方 Auto 僅支援 Claude、Claude Agent Teams、Codex)
- 涉及 Flyway 遷移的情境被建議為 Manual,且理由提到資料庫變更
- 建議的設定路徑與 Orca 實際 UI 一致(Settings → Agents → Agent Permissions)
- 沒有捏造不存在的設定項(例如「每個 Worktree 獨立權限」之類 UI 中找不到的選項)
- 若建議關閉 Trust the folder,有說明會影響 Automations 與手機啟動的體驗
✅ 驗證方式
- 在 Settings → Agents → Agent Permissions 選 Auto,Other agents 選 Manual。
- 新開一個 Claude Code 分頁,請它執行一個會改檔的動作,再請它執行
rm -rf build。 - 新開一個 Gemini 分頁,請它建立一個檔案。
- 判讀:
檢查項目 預期結果 若不符合 Claude 例行編輯 不需確認即完成 確認該 Agent 沒有自訂 Arguments 覆寫 Claude 刪除指令 出現確認提示或被 Agent 拒絕自動執行(Auto 的判定由 Agent 自身決定) 檢查是否仍帶 --dangerously-skip-permissionsGemini 建檔 出現 Gemini 自身確認 確認 Other agents 已設為 Manual 既有分頁 維持原本模式 屬正常行為,需重開分頁才套用新預設
❌ 常見錯誤
- 以為改了全域模式就會影響已開啟的分頁。實際上只影響新工作階段。
- 曾經手動編輯過某 Agent 的 Arguments,之後切換全域模式卻「沒反應」。這是因為自訂值被視為明確覆寫,需按 Reset 才會回到受全域控制。
企業治理考量:權限模式屬於安全基準,建議寫入第二十八章的「Agent 權限與沙箱」政策,並在新人到職時以本節驗證步驟做一次實機確認。
7.3 Claude Code 整合
📌 查證狀態:官方文件明確記載|來源:Claude Code in Orca
概念說明
Claude Code 是 Orca 整合最深的 Agent 之一,提供:
| 能力 | 說明 |
|---|---|
| 帳號感知啟動 | 依目前選擇的 Claude 帳號啟動;每個帳號有獨立的設定資料夾 |
| 狀態偵測 | Orca 啟動時加入 status-line hook,發出 OSC 標題事件驅動狀態點 |
| 用量與 Rate Limit | 讀取本機 ~/.claude 用量狀態,顯示於狀態列(見 8.2) |
| 帳號 Hot-swap | 一鍵切換帳號;執行中工作階段受保護,不會觸發重疊的認證刷新;切換後保留共用 MCP server 登入 |
| Subagent 與 Agent Teams | 背景 subagent 與 teammates 以可展開子列顯示在 Worktree Agent 清單與 Dashboard |
| Hooks 與 Memory | 讀取 repo 的 .claude/ 設定與 CLAUDE.md(見第九章) |
| Structured chat | 可用 Native Chat 開啟(見 7.7) |
操作步驟:首次設定
安裝 Claude Code:
npm i -g @anthropic-ai/claude-code在任一終端機登入一次:
claude # 依畫面完成登入後輸入 /status 確認帳號,再 /exit 離開開啟 Orca,Orca 會自動讀取
~/.claude,不需要額外設定。在 Worktree 中開新分頁,從 Agent 下拉選單選 Claude Code。Orca 以該 Worktree 為工作目錄啟動。
(選用)需要多帳號時,於 Settings → Accounts(Claude 帳號清單)新增帳號。若預設瀏覽器已登入另一個 Claude 帳號,可改用 Copy sign-in link 在其他瀏覽器完成登入。
Subagent 導覽
- 預設開啟。選取子列可在 lead 終端機中檢視該 subagent 的 transcript,再選回父列即可返回。
- 可於 Settings → Agents → Claude subagent navigation 關閉;變更後需開啟新的 Claude 工作階段才生效。
- v1.4.242 起,Orca 會在各 Claude 設定資料夾的
keybindings.json加入一個導覽快捷鍵(取 Ctrl+Alt+G/H/V 中第一個可用者);已在執行的 Claude 工作階段需重新啟動。
範例:在 Orca 終端機確認 Claude 執行環境
# 在 Orca 啟動的 Claude Code 分頁中輸入(Claude 內建指令)
/status# 預期看到(示意)
Working directory: /Users/alice/orca-worktrees/payments/feat-refund
Account: alice@company.com
Model: <目前模型>範例 Prompt:讓 Claude Code 在 Worktree 內執行受控任務
請在目前的 Worktree 內完成以下工作,不要修改 src/legacy/ 以外的任何目錄:
1. 將 src/legacy/DateUtil.java 中所有 SimpleDateFormat 改為 java.time.DateTimeFormatter。
2. 為每個被修改的方法補上 JUnit 5 測試,放在 src/test/java/legacy/。
3. 執行 ./gradlew test --tests 'legacy.*',並把完整輸出最後 30 行貼在回覆中。
4. 最後輸出:變更檔案清單、未處理的風險、需要人工確認的地方。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
-
git diff --stat只出現src/legacy/與src/test/java/legacy/下的檔案 - 回覆中貼出的測試輸出與你自己重跑
./gradlew test --tests 'legacy.*'的結果一致 -
DateTimeFormatter的時區處理與原本SimpleDateFormat行為一致(特別是預設時區) - 沒有任何
@Disabled或被註解掉的測試 - 回覆列出的「未處理風險」確實存在於程式碼中,而非泛泛而談
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 工作目錄正確 | Claude 內輸入 /status | 顯示目前 Worktree 路徑 | 確認是從該 Worktree 的分頁啟動 |
| 帳號正確 | /status 與狀態列 Claude chip | 兩者顯示同一帳號 | 用狀態列帳號切換器選定後重開分頁 |
| 狀態點運作 | 送出指令後觀察分頁與側欄 | 執行中為 spinner,完成為綠點 | 確認 Settings → Agents → Agent status hooks 開啟 |
| Subagent 子列 | 請 Claude 啟動一個 subagent 任務 | 父列下出現可展開子列 | 確認 Claude subagent navigation 開啟並已重開工作階段 |
⚠️ 注意事項
- v1.4.227 起,Claude 帳號回到「各自獨立資料夾」模式。若你手動在
~/.claude修改設定,請確認改的是目前帳號實際使用的資料夾。 - Hot-swap 只影響「之後新啟動」的工作階段;執行中的 Claude 仍使用原帳號(細節見 8.3)。
7.4 Codex 整合
📌 查證狀態:官方文件明確記載|來源:Codex in Orca、Hot-swap Codex accounts、Troubleshooting
概念說明
Codex 整合的核心是「帳號身分在用量、Hot-swap 與重新啟動之間都被保留」。需要理解三個概念:
| 概念 | 說明 |
|---|---|
| System default | 使用你真實的 ~/.codex 登入,與在 Orca 外直接執行 codex 相同 |
| 額外帳號(managed) | Orca 為每個額外帳號建立獨立 home,憑證與 rollout 彼此隔離;Orca 會把你真實 ~/.codex/config.toml 的設定鏡像到啟用中的 runtime home |
| 每 tab 獨立 server | Codex 0.157 起,Orca 預設讓每個 Codex 分頁執行自己的背景 server,確保狀態正確且關閉一個分頁不影響其他分頁 |
每 tab 獨立 server 的取捨
| 面向 | 獨立 server(預設) | 共用 server |
|---|---|---|
| 狀態準確度 | 每個分頁獨立準確 | 可能互相干擾 |
| 關閉分頁 | 不影響其他 Codex | 可能中斷其他工作階段 |
codex agents、背景執行、Codex desktop/IDE 可見性 | 看不到 Orca 內的工作階段 | 可見 |
| 記憶體 | 較高 | 較低 |
| 設定方式 | 預設開啟 | 關閉 Settings → Agents → Run each Codex terminal on its own server,或設定 ORCA_CODEX_ISOLATE=0 |
操作步驟:首次設定與多帳號
- 依 OpenAI 文件安裝 Codex,並在一般終端機登入一次(
codex login)。 - 開啟 Orca,Orca 讀取
~/.codex的帳號與憑證。 - 在 Worktree 中從 Agent 下拉選單選 Codex;Orca 以 Worktree 為 cwd,並以目前選定帳號路由認證。
- 多帳號:開啟 Settings → Agents → Codex Accounts,為每個帳號取易懂的標籤(如「personal」「work」),細節見 8.3。
- 需要共用 server 時,關閉 Run each Codex terminal on its own server,之後新開的終端機才生效。
範例:在 shell 啟動檔強制共用 server
# ~/.zshrc 或 ~/.bashrc
export ORCA_CODEX_ISOLATE=0# Windows 使用者層級環境變數
[Environment]::SetEnvironmentVariable('ORCA_CODEX_ISOLATE', '0', 'User')Hand Off to Another Agent
從 Agent 終端機標頭或右鍵選單選 Hand Off to Another Agent,Orca 會開一個新的 Agent 工作階段(可同一 CLI 或不同 CLI),並注入一段由先前 transcript 擷取的有限交接 Prompt。原工作階段保持不動,這不是 codex resume。此功能在 v1.4.224 前名為「Continue in New Session」。
Codex on Windows 與 WSL
- v1.4.221 起,Windows 上的 Codex 與 macOS/Linux 一樣使用真實的
~/.codex。更新後首次出現 Codex 終端機時會顯示一次性提示:Codex 可能再次詢問資料夾信任或指令核准,且只在 Orca 內新增的 MCP server 需要重新加入。 - 可從帳號切換器新增 WSL-hosted Codex account:Orca 在 distro 內建立
~/.local/share/orca/codex-accounts/<id>/home,並透過\\wsl.localhost\<distro>\...讀取認證;啟動、Hot-swap 與 Rate Limit 查詢都經由選定的 distro。若 distro 未安裝 Codex,對話框會明確指出缺少哪個 distro 的執行檔。
疑難:path must be shorter than SUN_LEN
Codex 0.157 以上在 Orca 管理的帳號 home 路徑過長時,背景 daemon socket 會超過長度限制。v1.4.212 以後 Orca 會自動為受影響的 home 關閉該 daemon,不需搬移帳號或修改 ~/.codex/config.toml;代價是該 home 內 codex agents 與依賴 daemon 的續接不可用。
範例 Prompt:Codex 撰寫遷移計畫
請閱讀 db/migration/ 下所有 Flyway 檔案與 src/main/java/**/entity/*.java,
產出 docs/migration-plan-v42.md,內容包含:
1. 現有 schema 與 entity 不一致之處(表格:表名、欄位、entity 定義、DB 定義、建議處置)。
2. 建議新增的 V42__*.sql 遷移檔內容(只寫在文件中,不要建立實際檔案)。
3. 每一項變更的回滾 SQL。
不得修改 db/ 與 src/ 下任何檔案。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
-
git status只有docs/migration-plan-v42.md一個新檔 - 表格中列出的不一致,隨機抽 3 筆對照 entity 原始碼與遷移檔確認屬實
- 每一個前進 SQL 都有對應回滾 SQL,且回滾不會遺失資料(例如 DROP COLUMN 前需備份)
- 版本號 V42 與現有最大版本號連續
✅ 驗證方式
在 Orca 的 Codex 分頁外,另開一個一般 Orca 終端機,執行:
orca terminal list --worktree active --json預期輸出(示意,欄位以實際為準):
{ "terminals": [ { "handle": "...", "title": "Codex", "executionHostId": "local" , ... } ] }判讀:
檢查項目 預期結果 若不符合 Codex 分頁存在於目前 Worktree 清單中有 Codex 終端機 確認是在正確的 Worktree 開分頁 帳號正確 狀態列 Codex chip 顯示預期標籤 先切換帳號,再按 Restart chip 或重開分頁 獨立 server 設定 依設定, codex agents看不到(獨立)或看得到(共用)Orca 內工作階段確認是在變更設定之後新開的分頁
⚠️ 注意事項
- 已在執行的 Codex 工作階段保留其啟動時的帳號 home,直到你重新啟動它。
- Codex structured chat 需要 Codex 0.136.0 以上(v1.4.227 起)。
7.5 Cursor CLI 整合
📌 查證狀態:官方文件明確記載|來源:Cursor CLI in Orca、Usage & rate-limit tracking
概念說明
Cursor CLI 在 Orca 中屬於一級支援:可從選單啟動、完整 OSC 狀態偵測、結束時出現 Restart chip,並顯示 Cursor 方案的月用量。與 Claude Code、Codex 不同的是:
| 項目 | Cursor CLI 的行為 |
|---|---|
| 模型選擇 | 完全由 Cursor 自身設定決定,Orca 不覆寫 |
| 用量 | 讀取電腦上既有的 Cursor 登入,顯示方案月用量於狀態列、Usage popover 與 Settings → Accounts → Cursor |
| 登入 | Orca 不代為登入;登入過期時執行 cursor-agent login |
| Hibernation | 不屬於可續接 Agent,不會被休眠(見 10.3) |
| 權限預設 | 預設帶 --yolo |
操作步驟
依 Cursor 官方文件安裝 Cursor CLI,並登入一次:
cursor-agent login確認
cursor-agent在 PATH 上;Orca 會自動偵測。在 Worktree 開新分頁,從 Agent 下拉選單選 Cursor。
在 Cursor CLI 內部切換模型(Orca 不提供 Cursor 的模型選擇器)。
開啟 Settings → Accounts → Cursor 檢視方案用量。
範例:Session History 中的 Cursor 續接指令
# Agent Session History 的「Copy resume command」對 Cursor 產生的指令形式
cursor-agent --resume <session-id>✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| CLI 被偵測 | Agent 下拉選單 | 出現 Cursor | 確認 cursor-agent 在 PATH;重啟 Orca |
| 狀態點 | 送出指令 | 分頁顯示 spinner 再轉綠 | 確認是從選單啟動 |
| 用量顯示 | 狀態列 usage 區塊或 Settings → Accounts → Cursor | 顯示方案月用量 | 執行 cursor-agent login 重新登入;若顯示 usage failure,代表用量請求被拒而非登入過期 |
| Restart chip | 在 Cursor 中離開 CLI | 分頁出現 Restart chip | 確認非手動在一般 shell 中啟動 |
💡 小技巧:Cursor 不支援 Hibernation,若你在大量 Worktree 中使用 Cursor,請改以手動 Sleep(見 10.3)或 Resource Manager 控制資源。
7.6 GLM 與其他相容模型整合
📌 查證狀態:官方文件明確記載|來源:How to use GLM-5.2 in Orca ADE、Usage & rate-limit tracking
概念說明
Orca 不轉售任何模型存取權。要在 Orca 使用 GLM-5.2 這類第三方模型,原則只有一條:在 Agent harness(Claude Code、OpenCode、Cline、Kilo Code、Roo Code、Droid、OpenClaw 等)自己的設定處設定模型,然後從 Orca 選單啟動該 harness。Orca 提供隔離 Worktree、終端機、瀏覽器、Review 與 Session 管理;模型存取來自你的 Z.ai CodePlan 訂閱與 harness 設定。
| 前置條件 | 說明 |
|---|---|
| Z.ai CodePlan 訂閱 | 需具備 GLM Coding Plan 存取權 |
| Z.ai API Key | OpenAI 相容型 harness 需要 |
| 用量追蹤 | 可在 Settings → Accounts → GLM Coding Plan 選擇方案網站(Z.AI 或 Zhipu BigModel)並儲存方案 API Key;不需 ZCode CLI 登入,且已儲存的 Key 優先於 ZCode CLI 登入 |
設定方式對照
| Harness 類型 | 設定位置 | 關鍵值 |
|---|---|---|
| Claude Code | ~/.claude/settings.json 的 env 區塊 | 以環境變數覆寫各級模型名稱 |
| OpenAI 相容(OpenCode、Cline、Kilo Code、Roo Code、Droid) | 各 harness 的 provider 設定 | Base URL https://api.z.ai/api/coding/paas/v4、模型 glm-5.2、context 1000000 |
| OpenClaw | ~/.openclaw/openclaw.json | 於 models.providers.zai.models 新增模型並設為 primary |
操作步驟:Claude Code 改用 GLM-5.2
- 備份既有設定:
cp ~/.claude/settings.json ~/.claude/settings.json.bak。 - 編輯
~/.claude/settings.json,加入或更新env區塊(範例如下)。 - 在 Orca 中重新啟動 Claude Code 工作階段,讓新環境變數載入。
- 在 Claude Code 內輸入
/status確認啟用中的模型。 - Z.ai 建議 coding 任務以
/effort設為 max;Claude Code 較低的 effort 對應 GLM-5.2 的 high,xhigh/max/ultracode 對應 GLM-5.2 的 max。
範例:~/.claude/settings.json
{
"env": {
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
}
}[1m] 後綴代表使用 GLM-5.2 的 1M context 版本,此時應讓 CLAUDE_CODE_AUTO_COMPACT_WINDOW 維持 1000000 使壓縮視窗一致。若 Claude Code 回報 [1m] 模型不存在,請先更新 Claude Code。
📌 查證狀態:上述
env區塊僅示範模型相關鍵值;實際使用 Z.ai 端點時所需的認證與 Base URL 環境變數,請以 Z.ai 最新模型指南為準|來源:GLM-5.2 in Orca
操作步驟:OpenAI 相容 harness
- 開啟 harness 的設定(可在 Orca 內或外)。
- 選擇 OpenAI-compatible provider,若有 Z.ai provider 則選它。
- Base URL 設為
https://api.z.ai/api/coding/paas/v4。 - 填入 Z.ai API Key(建議以環境變數或 harness 的安全儲存,勿寫入 repo)。
- 自訂模型名稱設為
glm-5.2;若可設定 context window,填1000000。 - 除非 harness 明確支援此 provider 路徑的影像輸入,否則關閉 image support。
- 儲存後從 Orca 的 Agent 選單啟動該 harness。
範例:OpenClaw 新增 GLM-5.2 並設為主要模型
{
"models": {
"providers": {
"zai": {
"models": [
{
"id": "glm-5.2",
"name": "GLM-5.2",
"reasoning": true,
"input": ["text"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 1000000,
"maxTokens": 131072
}
]
}
}
},
"model": {
"primary": "zai/glm-5.2",
"fallbacks": ["zai/glm-4.7"]
},
"agents": {
"defaults": {
"models": {
"zai/glm-5.2": { "alias": "GLM" },
"zai/glm-4.7": {}
}
}
}
}📌 查證狀態:官方文件分三段列出各鍵值,此處合併為單一 JSON 以利理解;巢狀位置依官方描述的鍵路徑推導(教學推論),實際合併時請保留你現有設定的其他鍵|來源:GLM-5.2 in Orca
修改後重新啟動 OpenClaw gateway:
openclaw gateway restart✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| JSON 合法 | python -m json.tool ~/.claude/settings.json | 正常輸出,無錯誤 | 修正逗號、引號;或還原 .bak |
| Claude 使用 GLM | 重開 Claude Code 分頁後輸入 /status | 模型顯示 glm-5.2[1m] | 確認已重開工作階段;更新 Claude Code |
| OpenClaw 使用 GLM | 在 Orca 終端機執行 openclaw tui | 介面顯示 GLM-5.2 為啟用模型 | 確認 gateway 已重啟、JSON 路徑正確 |
| 用量可見 | Settings → Accounts → GLM Coding Plan 儲存 Key 後開啟狀態列 Usage popover | 出現 GLM Coding Plan 列 | 確認選對方案網站(Z.AI 或 Zhipu BigModel) |
| 未外洩金鑰 | git grep -n "api.z.ai" -- . ':!docs' 與 git status | repo 內沒有 API Key | 立即移除並輪替金鑰(見 8.5) |
⚠️ 注意事項
- 修改
~/.claude/settings.json會影響所有使用該設定資料夾的 Claude 工作階段,包括 Orca 外的終端機。企業環境建議為 GLM 用途建立獨立的 Claude 帳號資料夾,或以 Agent 的 per-agent 環境變數(Settings → Agents 展開該 Agent 的 environment)限定範圍。 - 使用第三方模型時,程式碼會傳送到該模型供應商。導入前必須完成資料分類與供應商評估(見第二十八章)。
7.7 Native Chat 結構化聊天介面
📌 查證狀態:官方文件明確記載(Experimental 功能)|來源:Chat UI (native chat)
概念說明
Chat UI 是疊在 Agent 工作階段上的實驗性檢視。開啟後,支援的新 Agent 會以 Orca 的結構化聊天(transcript + composer)開啟,對話狀態保存在 Orca 中,應用程式重啟後可還原。
| 面向 | Structured chat | Terminal-backed Chat UI | 原生終端機(TUI) |
|---|---|---|---|
| 支援 Agent | Claude、Codex、Grok、OpenCode(含 2.x)、Pi、OMP、Antigravity | 其他 Agent | 所有 Agent |
| 執行位置 | 本機 macOS/Linux/原生 Windows、Paired Orca Server 擁有的工作區 | WSL、SSH 工作階段 | 所有 |
| 重啟後還原對話 | 是 | 依終端機 | 依 Agent 自身 Resume |
| Rewind、排隊訊息、內嵌 Diff 卡 | 是 | 部分 | 否 |
| OSC/狀態細節完整度 | 仍在調校 | — | 最完整 |
操作步驟:啟用與分流
- 開啟 Settings → Experimental → Chat UI,打開開關。
- 於 Settings → Chat → Providers 關閉你希望仍以終端機開啟的 provider。此偏好適用於該桌機發起的所有啟動,包括 CLI、Orchestration 與手機轉送。
- 於 Settings → Experimental → Chat UI → Use your shell environment 決定是否傳入登入 shell 的環境變數(預設開啟;關閉後只傳入你允許的變數與 PATH、locale、
SSH_AUTH_SOCK等基本變數)。 - 於 Settings → Chat 調整字型、字級、寬度、對比,或開啟 Match terminal interface;Inline visuals 讓 Agent 在回覆中繪製圖表與 mockup;Chat names 選擇用哪個 Agent 為新聊天命名。
- Structured chat 啟動 Agent 時,使用 Settings → Agents 中該 Agent 儲存的 Command 與 Arguments。
Composer 常用操作速查
| 操作 | 方法 |
|---|---|
| 插入檔案路徑 | 輸入 @ 選檔,或從檔案樹/桌面拖曳到 composer |
| 搜尋聊天內容 | macOS Cmd+F、Windows/Linux Ctrl+F |
| 引用回覆 | 選取 Agent 回覆文字 → Add to chat |
| 叫回先前 Prompt | 空白草稿按上/下鍵 |
| 執行中插話 | 送出的訊息成為卡片,可 Steer 進執行中回合、編輯、刪除或拖曳排序 |
| 停止 | Stop;Claude 會結束整個行程(含背景指令與 subagent) |
| 回到某點重來 | 已送出訊息的 Rewind to here;需 Agent 閒置;Codex 會回退整個回合 |
| 斜線指令與 Skill | 開頭或空白後輸入 /,Claude 插入 /skill、Codex 插入 $skill |
| 清除與壓縮 | /clear 在同窗格開新對話並保留歷史;/compact 壓縮 context(Claude、Codex、Grok、OpenCode、OMP 支援) |
| 模型與選項 | Composer 上的 model/options pill(thought level、Fast mode 等);Codex 支援直接選模型並提供 Ultrafast |
| Context 用量 | Structured Claude chat 的模型旁圓環,顯示訊息、工具、memory 檔佔用 |
| 回答選擇題 | Agent 提出編號選項時,按數字鍵作答 |
在 Chat 與終端機之間移動
- 分頁右鍵或 Agent Session History 列:Resume in New Native Chat(以結構化聊天開啟舊對話)、Resume in New CLI(將聊天分叉到終端機)。原對話保持不變。
- 一旦對話被保留給 structured chat,該 Session 就不能再用終端機 Resume。
- 若同一對話仍在某終端機中可能寫入,Chat UI 不會送出競爭訊息;請先離開該終端機的 Agent。
- v1.4.243 起,可把執行中的終端機 Agent 工作階段即時轉為 Chat UI。
flowchart LR
A["新 Agent 分頁"] --> B{"Chat UI 已開啟?"}
B -- 否 --> T["終端機 TUI"]
B -- 是 --> C{"Provider 支援 structured 且非 WSL或SSH?"}
C -- 是 --> S["Structured chat"]
C -- 否 --> TB["Terminal-backed Chat UI"]
S -- "Resume in New CLI" --> T
T -- "Resume in New Native Chat" --> S
S -- "Hand Off" --> H["另一個 Agent 的新工作階段"]如何閱讀此圖:從左側「新 Agent 分頁」開始,先判斷 Chat UI 開關,再判斷 provider 與執行位置是否支援 structured chat。Structured chat 與終端機 TUI 之間的兩條標籤箭頭表示同一段對話可以在 Structured chat 與終端機之間「分叉」移動,原對話不受影響;Hand Off 則是把工作交給另一個 Agent 的全新工作階段。
範例:用 CLI 啟動並確認開在哪一種介面
orca agent launch --agent claude --worktree path:/projects/myapp --json# 回傳中的 outcome.kind 會說明開啟的是 structured chat 或 terminal,以及原因(示意)
{ "outcome": { "kind": "chat", ... } }範例 Prompt:在 structured chat 中善用 Plan 與 Checklist
/clear
請先用 TodoWrite 列出修正 issue #812(訂單金額四捨五入錯誤)的步驟清單,每一步不超過一行,
等我回覆「OK」後再開始實作。實作時每完成一步就更新清單狀態。
完成後列出:修改的檔案、執行的測試指令與輸出、仍需人工確認之處。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- Agent 在你回覆「OK」之前沒有修改任何檔案(查看 turn 標頭的檔案變更摘要)
- Composer 上方的 progress panel 清單與實際完成步驟一致
- 每個內嵌 Diff 卡都與
git diff結果相符 - 回覆中的測試輸出可以用相同指令重現
- 若中途使用 Rewind,確認被回退回合的檔案變更確實已還原(
git status)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Chat UI 啟用 | 開新 Claude 分頁 | 以 transcript + composer 介面開啟 | 檢查 Settings → Experimental → Chat UI 與 Settings → Chat → Providers |
| 重啟還原 | 關閉並重開 Orca | 分頁與對話仍在,或狀態列出現 chats to resume | 屬實驗功能,請回報並改用終端機 |
| 介面判定 | orca agent launch ... --json | outcome.kind 與預期一致 | 檢查是否為 WSL/SSH 工作區 |
| 移轉 | 分頁右鍵 Resume in New CLI | 新終端機分頁接續同一對話 | 確認對話未被保留給 structured chat 以外的終端機 |
⚠️ 注意事項
- Chat UI 仍是 Experimental:transcript 精確度、串流與終端機對等性仍在調校。需要每一個 OSC/狀態細節時,請使用原生 TUI。
- Structured chat 在背景成功完成時只會將分頁與工作區標示為未讀,不會發送系統通知或聲音(見 10.4)。
- Native chat 的新功能常需要 paired/SSH 主機同步更新 Orca(v1.4.232~v1.4.240 多次註明)。
企業治理考量:Use your shell environment 預設把登入 shell 的所有 export 傳入 chat。若 shell 啟動檔中含有雲端憑證,建議關閉並以白名單方式只放行必要變數。
7.8 Agent 選型決策指引
📌 查證狀態:整合能力依官方文件明確記載;選型建議為依官方說明延伸(教學推論)|來源:Supported agents、Agent hibernation、Usage tracking
概念說明
選 Agent 不是只比「哪個模型比較聰明」。在 Orca 中,Agent 的整合深度直接決定你能否觀測、治理與續接它。建議以「能力需求 → 治理需求 → 成本」三層篩選。
決策表一:Orca 整合能力對照(擷取企業常用 Agent)
| Agent | 狀態偵測 | 用量追蹤 | 多帳號 Hot-swap | Session history/Resume | Hibernation | Structured chat | Supervised worker | Auto 權限 |
|---|---|---|---|---|---|---|---|---|
| Claude Code | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 |
| Codex | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 |
| Cursor CLI | 是 | 是(方案月用量) | 否 | 是 | 否 | 否 | 是 | 否 |
| Gemini | 未載明 | 是 | 否 | 是 | 是 | 否 | 未載明 | 否 |
| Antigravity | 是 | 是 | 帳號 | 是 | 是 | 是 | 是(本機) | 否 |
| OpenCode | 是 | 是 | 帳號 profile | 是 | 是 | 是 | 是 | 否 |
| GitHub Copilot CLI | 未載明 | 否 | 否 | 是(Copilot) | 否 | 否 | 未載明 | 否 |
| Muse Code | 是 | 是(本機 token) | 否 | 是 | 否 | 否 | 是 | 否 |
| Qoder CLI | 是 | 否 | 否 | 是 | 否 | 否 | 是 | 否 |
📌 查證狀態:「是/否」依官方 Supported agents、Usage tracking、Session history、Hibernation 頁面交叉整理;「未載明」表示官方頁面未提及,不代表不支援,請以實機驗證|來源:Supported agents
決策表二:情境導向選型
| 情境 | 首選 | 備選 | 理由 |
|---|---|---|---|
| 主力日常開發,需要完整治理 | Claude Code 或 Codex | OpenCode | 用量、Hot-swap、Auto 權限、Hibernation 齊備 |
| 同題競賽(第十一章) | Claude Code + Codex + 第三家 | Gemini、OpenCode | 不同模型家族能產生差異化方案 |
| 大量 Worktree 長時間掛著 | 可 Hibernation 的 Agent | — | Cursor、Copilot、Hermes、Trae 不會休眠,會持續佔用資源 |
| 需要 Orchestration 分派 | 標示 supervised workers 的 Agent | — | Claude、Codex、Cursor、OpenCode、Muse、ZCode、Qoder、Qwen、Antigravity 等 |
| 資料不可出境或需指定模型 | 支援自訂 provider 的 harness(OpenCode、Cline、OpenClaw) | Claude Code 搭配 env 覆寫 | 模型由 harness 設定(見 7.6) |
| 團隊已採購 GitHub Copilot | GitHub Copilot CLI | — | 沿用既有授權與帳號治理 |
| 團隊使用 Atlassian 生態 | Rovo Dev | — | 透過 acli 偵測,與 Jira 流程一致 |
決策流程
flowchart TD
Q1{"需要用量與多帳號治理?"} -- 是 --> D1["Claude Code 或 Codex"]
Q1 -- 否 --> Q2{"需要 Orchestration worker?"}
Q2 -- 是 --> D2["選標示 supervised workers 的 Agent"]
Q2 -- 否 --> Q3{"需要指定第三方或自架模型?"}
Q3 -- 是 --> D3["OpenCode、Cline、OpenClaw 等可設 provider 的 harness"]
Q3 -- 否 --> Q4{"Worktree 會長時間閒置?"}
Q4 -- 是 --> D4["優先可 Hibernation 的 Agent"]
Q4 -- 否 --> D5["依團隊既有授權選擇"]如何閱讀此圖:從最上方問題開始,依序回答四個治理問題;越上方的問題優先權越高。到達任一終點後,再用「決策表一」確認該 Agent 是否具備你需要的其他能力。
工作範例:某金融科技團隊的 Agent 組合決策
📌 查證狀態:教學示例(非官方),非真實客戶專案
背景:12 人團隊、Java 與 TypeScript、每人同時 3~6 個 Worktree、需要月度用量報告、部分專案禁止程式碼送往未核准供應商。
- 列出需求:用量報告(必要)、多帳號(必要)、長時間閒置(常見)、Orchestration(未來)。
- 套用決策表一:只有 Claude Code 與 Codex 同時滿足「用量 + Hot-swap + Hibernation + Auto 權限」。
- 套用決策表二:同題競賽需要第三家,選 OpenCode(可指向已核准的供應商)。
- 結論:核准清單 = Claude Code、Codex、OpenCode;其餘在 Settings → Agents 停用。
- 權限:依 7.2 設為 Auto,Other agents(OpenCode)設 Manual。
範例 Prompt:請 AI 依團隊條件產出選型報告
請扮演企業架構師,根據下列條件產出 Orca Agent 選型報告(Markdown),包含:
(a) 候選 Agent 整合能力比較表;(b) 建議核准清單與理由;(c) 不建議的 Agent 與原因;(d) 驗證計畫。
限制:
- 只能使用 Orca 官方 Supported agents 頁面列出的 Agent 名稱與能力,不得自行補充未記載的能力;
無法確認的能力請標示「未載明」。
- 必須考慮 Agent hibernation 的支援清單:Claude, Codex, Gemini, Antigravity, OpenCode, Pi, MiMo Code,
Droid, Grok, Devin, OMP。
團隊條件:<貼上上方工作範例的背景>🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 比較表中每一個「是」都能在官方 Supported agents 或相關頁面找到依據
- 沒有把 Cursor CLI、GitHub Copilot 列為支援 Hibernation
- 沒有宣稱 Auto 權限支援 Claude、Claude Agent Teams、Codex 以外的 Agent
- 「不建議」理由是治理或能力面的事實,而非對供應商的主觀評價
- 驗證計畫中每一項都有可執行的步驟(UI 路徑或指令)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 核准清單生效 | 新分頁 Agent 下拉選單 | 只出現核准的 Agent | Settings → Agents 停用未核准者 |
| 用量需求滿足 | 狀態列 Usage popover | 核准清單中需追蹤用量的 Agent 皆出現 | 依第八章補登帳號 |
| Hibernation 需求滿足 | 開啟 Agent hibernation,閒置超過設定時間 | 背景 Worktree 進入 sleeping | 確認該 Agent 在可續接清單中(見 10.3) |
| 選型可重現 | 另一位審查者依決策表重跑一次 | 得到相同核准清單 | 決策條件描述不清,需補充 |
企業治理考量:選型結果應版本化(例如存於內部 Wiki 並記錄 Orca 版本),每次 Orca 重大版本更新或供應商條款變更時重新走一次決策表。
7.9 本章 Review 與驗證清單
- 能說明 Orca「啟動 CLI」與「提供模型」的差別,並解釋為何 Orca 不負責模型計費
- 已在 Settings → Agents → Installed agents 確認團隊核准清單,並停用其餘 Agent
- 能列出 Claude Code、Codex、Gemini 的預設權限旗標,並說明 Manual/Auto/Yolo 差異與 Auto 的支援範圍
- 已實際以
/status驗證 Claude Code 在正確 Worktree、帳號與模型下執行 - 能說明 Codex「每 tab 獨立 server」的取捨,並知道
ORCA_CODEX_ISOLATE=0的用途 - 能區分 Hand Off to Another Agent 與
codex resume - 已確認 Cursor CLI 的模型由 Cursor 自身設定,且 Cursor 不支援 Hibernation
- 能依 7.6 為 Claude Code 或 OpenAI 相容 harness 設定 GLM-5.2,並以
/status或openclaw tui驗證 - 已啟用並試用 Native Chat 的
@選檔、Steer、Rewind、Resume in New CLI - 已用 7.8 的決策表為自己的團隊產出核准清單,並請另一人重跑驗證結果一致
第八章 帳號用量與 Provider 治理
本章說明 Orca 的「自帶訂閱(BYO)」模式、用量與 Rate Limit 追蹤、多帳號 Hot-swap、預估成本,以及企業如何在這些能力之上建立用量治理。核心觀念延續第七章:計費主體永遠是各 Agent 供應商,Orca 是讀取與切換的介面。
8.1 BYO 訂閱模式說明
📌 查證狀態:官方文件明確記載|來源:Usage & rate-limit tracking、Settings、GLM-5.2 in Orca
概念說明
Orca 本身是 MIT 授權的開源桌面應用,不提供也不轉售模型額度。你使用的每一個 Agent 都以「你自己的訂閱或 API Key」運作,這就是 BYO(Bring Your Own)模式:
| 層次 | 由誰負責 | 在哪裡管理 |
|---|---|---|
| 模型存取與計費 | Agent 供應商(Anthropic、OpenAI、Google、Z.ai…) | 供應商主控台 |
| 認證憑證 | Agent CLI | ~/.claude、~/.codex、各 CLI 自己的設定目錄 |
| 多帳號清單 | Orca(讀取並隔離) | Settings → Accounts:Claude、Codex、OpenCode、Devin、Antigravity、GLM Coding Plan |
| 用量顯示 | Orca(讀取本機狀態或供應商 API) | 狀態列 Usage 區塊、Usage popover |
| 預估成本 | Orca(本機價格表推算) | Stats breakdown(見 8.4) |
與舊版手冊的差異:舊版曾以「Orca 只有帳號切換器、沒有 Provider 管理」描述。v1.4.244 的事實是:Orca 仍沒有統一的「模型路由」功能,但帳號管理範圍已擴及 Claude、Codex、OpenCode、Devin、Antigravity 與 GLM Coding Plan,用量追蹤也擴及十餘家供應商。
操作步驟:盤點目前的 BYO 帳號
- 開啟 Settings → Accounts,逐一檢視 Claude、Codex、OpenCode、Devin、Antigravity、GLM Coding Plan 的帳號清單。
- 在 Linux 上,留意是否有「saved credential could not be encrypted」警告(代表憑證未加密儲存)。
- 點狀態列的 usage 區塊開啟 Usage popover,確認每個供應商都有數字或明確狀態。
- 將結果記錄到團隊的帳號盤點表(範例如下)。
範例:帳號盤點表
| 供應商 | 帳號標籤 | 計費主體 | 方案 | 使用者 | Orca 中可見 | 備註 |
|---|---|---|---|---|---|---|
| Anthropic | work-team-a | 公司 | Team | alice | 是 | 主力開發 |
| Anthropic | personal | 個人 | Pro | alice | 是 | 不得用於公司 repo |
| OpenAI | work | 公司 | Business | alice | 是 | Codex 主帳號 |
| Z.ai | glm-plan | 公司 | GLM Coding Plan | 平台組 | 是 | 7.6 設定 |
遠端主機上的帳號
在無頭主機(orca serve 或桌面版)上,遠端客戶端的 Add account 按鈕會因為 runtime 範圍而停用。此時應在擁有帳號的主機本身執行:
orca account list
orca account add # 預設為 Claude
orca account add --agent codex # Codex 使用 device authorization,可在另一台電腦的瀏覽器完成✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 帳號已列出 | Settings → Accounts | 盤點表中的帳號皆出現 | 依 8.3 新增帳號 |
| 憑證已加密(Linux) | Settings → Accounts 是否有未加密警告 | 無警告 | 確認系統金鑰圈可用(v1.4.219 起 Wayland compositor 亦會加密) |
| 遠端帳號 | 在主機執行 orca account list | 列出主機上的帳號 | 確認是在主機本機執行,而非透過純客戶端工作階段 |
| 用量可讀 | Usage popover | 每列有數字或明確狀態文字 | 見 8.2 的狀態文字說明 |
企業治理考量:BYO 模式下,「哪個帳號在付錢」必須清楚。嚴禁個人帳號用於公司 repo,也嚴禁公司帳號用於個人專案;盤點表應由主管每月簽核。
8.2 Usage 與 Rate Limit 追蹤
📌 查證狀態:官方文件明確記載|來源:Usage & rate-limit tracking
概念說明
Orca 追蹤 Claude Code、Codex、Muse Code、Gemini、Antigravity、OpenCode、Kimi Code、MiniMax、Cursor、ZCode 與 GLM Coding Plan 的用量,顯示於狀態列,讓你在 Agent 卡住之前就知道離 Rate Limit 多遠。
| 顯示內容 | 說明 |
|---|---|
| 目前用量 | 相對於啟用中帳號的方案 |
| 重置時間 | 5 小時、每日、每週、Claude Fable 每週等視窗(依供應商) |
| 警告 chip | 任一限額超過 80% 時出現 |
| Credit 餘額 | Claude usage credits、OpenCode Zen 餘額、Codex credits;未回報餘額者顯示為「unavailable」而非 0 |
資料來源依供應商而異
| 供應商 | 來源 | 需要的設定 |
|---|---|---|
| Claude Code | 本機 ~/.claude 用量狀態 | 已登入即可 |
| Codex | 本機 Codex 用量狀態(啟用中帳號) | 已登入即可 |
| Muse Code | 本機 session logs(token 計數,無價格估算) | 無 |
| OpenCode Go | opencode.ai console API | 於 Settings → Accounts 填入完整 Cookie header(含 __Host-console_session) |
| Cursor | 電腦上既有的 Cursor 登入 | 過期時執行 cursor-agent login |
| Antigravity | Antigravity 自身 CLI 的配額(含 model-group pools) | 不需 Gemini CLI;查詢不耗配額 |
| ZCode | 磁碟上的 transcript 與 Coding Plan 配額 | 無 |
| GLM Coding Plan | 方案 API | Settings → Accounts → GLM Coding Plan 選網站並儲存 Key |
操作步驟:閱讀 Usage popover
- 點狀態列的 usage 區塊開啟 Usage popover。
- 每列依序為:圖示、名稱、方案、最近重置時間、各視窗的用量條;最緊的限額排第一。
- 按標頭的重新整理鈕重新讀取本機用量狀態。
- Claude 與 Codex 列可直接下鑽到帳號切換;Manage accounts 開啟設定頁。
- 於 Settings → Appearance 選擇以「% used」或「% remaining」顯示。
- 狀態列有兩種樣式:Detailed(所有視窗完整顯示)與 Compact(每個供應商只顯示最緊視窗;v1.4.224 起為預設)。視窗過窄時,部分供應商會收合成
+Nchip,點擊即可看到全部。
狀態文字判讀
| 顯示 | 意義 | 建議動作 |
|---|---|---|
| Loading usage… | 正在讀取 | 稍候或按重新整理 |
| not signed in | 該 CLI 未登入 | 在終端機登入該 CLI |
| Usage unavailable | 無法取得用量 | 檢查網路或供應商狀態 |
| No usage data | 尚無用量紀錄 | 正常,使用後會出現 |
| 供應商特定錯誤 | 如 Cursor 的 usage failure | Cursor:代表請求被拒,而非登入過期 |
行動端:在 Mobile Companion 開啟主機的 Accounts 畫面可看到相同的切換器與用量;Codex 若獲得 rate-limit reset credits,可從該畫面使用(見第十九章)。
範例:以「用量閾值」安排平行任務
規則(貼在團隊 Wiki):
- 任一帳號的 5 小時視窗 ≥ 80%(出現警告 chip):不再對該帳號開新的同題競賽 Worktree。
- ≥ 90%:用 8.3 的 Hot-swap 切到備用帳號,再開新工作階段。
- 每週視窗 ≥ 70% 且距重置 > 3 天:通知主管評估是否調整本週平行度。✅ 驗證方式
- 開啟 Usage popover,截圖記錄當下各供應商的用量。
- 在 Claude Code 分頁執行一段中等長度任務,完成後按 popover 的重新整理。
- 判讀:
檢查項目 預期結果 若不符合 用量有變化 Claude 列百分比上升 確認啟用帳號與執行任務的帳號相同 排序正確 最緊的限額在最上方 若顯示 Compact,切換到 Detailed 檢查各視窗 數字與供應商一致 與供應商主控台誤差在可接受範圍 Orca 讀本機狀態,可能有延遲;以供應商主控台為準
⚠️ 注意事項:狀態列永遠只反映「啟用中」帳號;其他帳號的用量請在帳號切換器查看。
8.3 多帳號 Hot-swap
📌 查證狀態:官方文件明確記載|來源:Hot-swap Codex accounts、Claude Code in Orca
概念說明
很多使用者以多個帳號分散 Rate Limit,或區分個人與公司帳號。Orca 讓你一鍵切換啟用帳號,不需重新登入、不需編輯設定。Codex 與 Claude Code 流程相同,只是資料目錄不同(~/.codex 與 ~/.claude)。
| 規則 | 說明 |
|---|---|
| 切換是即時的 | Orca 改寫的是「啟用中憑證的指標」,不會重新認證 |
| 只影響新工作階段 | 已在執行的 Agent 保留原帳號,直到重新啟動 |
| 狀態列跟隨啟用帳號 | 用量讀數隨之改變 |
| Restart chip 保留帳號 | 重新啟動時使用「當下」的啟用帳號 |
| System default | 對應你主機上 ~/.codex(或 ~/.claude)的真實登入;managed 帳號不會改寫它 |
| 設定鏡像 | Managed Codex 帳號會從你真實的 ~/.codex/config.toml 鏡像設定;來源檔遺失、空白(例如雲端同步尚未下載完成)或無法讀取時,Accounts 會顯示警告,Codex 沿用最後一次成功同步的設定 |
| Claude 專屬 | 執行中有 Claude 工作階段時也能切換,Orca 以保護機制避免重疊的認證刷新;切換後保留共用 MCP server 登入 |
操作步驟:新增與切換 Codex 帳號
- 在終端機以每個帳號各登入一次 Codex,讓認證存在於
~/.codex。 - 開啟 Settings → Agents → Codex Accounts,Orca 會列出偵測到的帳號與用量、目前限額。
- 為每個帳號取易懂的標籤,例如「work」「backup」「personal」。
- 點狀態列的 Codex chip 開啟帳號切換器,選擇要使用的帳號。
- 之後新開的 Codex 工作階段即使用該帳號;要讓既有工作階段改用新帳號,請按其 Restart chip 或重新開啟分頁。
- Claude Code 帳號在 Settings → Accounts 的 Claude 帳號清單新增,切換方式相同(點狀態列 Claude chip)。
sequenceDiagram participant U as 使用者 participant SB as 狀態列帳號切換器 participant O as Orca Runtime participant S1 as 既有 Codex 工作階段 participant S2 as 新 Codex 工作階段 U->>SB: 選擇帳號 backup SB->>O: 更新啟用中憑證指標 O-->>SB: 狀態列用量改顯示 backup Note over S1: 仍使用原帳號 work U->>O: 開新 Codex 分頁 O->>S2: 以 backup 的 home 啟動 U->>S1: 按 Restart chip O->>S1: 以當下啟用帳號 backup 重新啟動
如何閱讀此圖:由上而下是時間順序。切換帳號只改變 Orca 的「啟用中指標」與狀態列讀數;既有工作階段(S1)不受影響,直到你按 Restart chip 才會以「當下」的啟用帳號重新啟動;新分頁(S2)則直接使用新帳號。
範例:確認 Codex 工作階段使用哪個帳號 home
# 在 Orca 的 Codex 分頁旁開一般終端機,查看 Session History 的續接指令(Copy resume command)
# Codex 的 Resume 會在原工作階段曾設定時重新匯出 CODEX_HOME,因此可從指令判讀帳號 home
echo "$CODEX_HOME"📌 查證狀態:
CODEX_HOME重新匯出行為依官方 Session history 文件;以echo檢查屬教學推論,managed 帳號 home 的實際路徑以你的環境為準|來源:Agent session history
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 帳號已偵測 | Settings → Agents → Codex Accounts | 每個登入過的帳號皆列出且有標籤 | 在終端機用該帳號再登入一次 |
| 切換即時生效 | 狀態列 Codex chip 選 backup | 狀態列用量立即改為 backup 的數字 | 按 popover 重新整理 |
| 既有工作階段不受影響 | 切換前已開的 Codex 分頁 | 仍以原帳號運作 | 屬正常行為 |
| Restart 採用新帳號 | 按既有分頁的 Restart chip | 新程序使用 backup | 先確認切換器已選 backup 再按 Restart |
| 設定鏡像正常 | Settings → Accounts 無警告橫幅 | 無「config.toml」相關警告 | 修正橫幅指出路徑的檔案,再重新選擇帳號 |
❌ 常見錯誤
- 切換帳號後立刻在既有分頁繼續工作,以為已經換帳號。正確作法是切換後按 Restart chip 或開新分頁。
- 在 managed 帳號中修改
config.toml卻沒生效。應修改真實的~/.codex/config.toml,Orca 會鏡像過去。
企業治理考量:Hot-swap 讓「分散限額」變得非常容易,但也可能違反供應商的使用條款或公司的授權配置。企業應明確規範:哪些帳號可以互換、是否允許以多個帳號規避單一帳號限額,並依供應商條款審核。
8.4 預估成本與 Stats
📌 查證狀態:官方文件明確記載;Stats 的 UI 入口官方文件未明示,以下入口描述屬依官方說明延伸(教學推論)|來源:Usage & rate-limit tracking → Estimated cost
概念說明
Orca 的 Stats breakdown 可能為已知模型家族顯示預估成本,包含 Claude Opus 5.5、Fable 5.1,以及 Codex 的 GPT-5.6 與 GPT-6 Astra、Sol、Luna。重點是:
| 特性 | 說明 |
|---|---|
| 計算方式 | Orca 內建的本機價格表 × 本機用量,不是供應商的即時帳單 |
• inferred pricing | 模型由 Orca 推斷時的估算標記 |
• excludes unpriced models | Codex 成本中未定價的模型被排除;Overview 也會標示總額為部分 |
| Muse Code | 只有本機 token 計數,不提供價格估算 |
| 權威數據 | 一律以供應商主控台為準 |
操作步驟
- 開啟用量相關畫面中的 Stats 細目(依你的版本,入口可能在 Usage popover 或統計頁;若找不到,以 Quick Open 搜尋「Stats」)。
- 依模型家族檢視預估成本,留意
• inferred pricing與• excludes unpriced models標記。 - 每月以供應商主控台的實際帳單與 Orca 預估比對,記錄差異率。
範例:月度成本比對表
| 供應商 | Orca 預估(USD) | 主控台實際(USD) | 差異率 | 標記 | 判讀 |
|---|---|---|---|---|---|
| Anthropic | 412 | 438 | -5.9% | 無 | 可接受 |
| OpenAI | 285 | 361 | -21.1% | excludes unpriced models | 有未定價模型被排除,以主控台為準 |
| Meta Muse | —(僅 token) | 依合約 | — | 無價格估算 | 改用 token 數做趨勢分析 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 估算可見 | 開啟 Stats 細目 | 已知模型家族顯示預估金額 | 模型不在價格表內時不會顯示;屬正常 |
| 標記判讀 | 檢查是否有 • 標記 | 能說明每個標記的意義 | 回頭閱讀本節表格 |
| 與帳單一致性 | 填寫月度比對表 | 差異率有紀錄且可解釋 | 差異過大時一律以主控台為準並記錄原因 |
⚠️ 注意事項:預估成本不可作為內部計費(chargeback)或對外報價依據;它是趨勢與異常偵測工具。
8.5 API Key 與憑證管理最佳實務
📌 查證狀態:憑證位置與 Orca 行為依官方文件與 release notes;最佳實務屬依官方說明延伸(教學推論)|來源:Settings、Codex in Orca、Orca Releases
概念說明:Orca 環境中憑證可能出現的位置
| 位置 | 內容 | 風險 | 對策 |
|---|---|---|---|
~/.claude、~/.codex 與 managed 帳號 home | CLI 登入憑證 | 主機被入侵即外洩 | 磁碟加密、限制 OS 帳號存取 |
~/.copilot/config.json | GitHub Copilot token | v1.4.219~v1.4.220 曾可能被他人讀取(含 SSH 主機),v1.4.221 已改為 owner-only | 檢查檔案權限(範例如下) |
| Settings → Accounts 儲存的 Key/Cookie | GLM 方案 Key、OpenCode Cookie header | Linux 若無法加密會顯示警告 | 確保系統金鑰圈可用 |
| Settings → Agents per-agent environment | 自訂環境變數 | 可能被誤填 API Key | 優先使用 CLI 自身登入流程 |
| 登入 shell 的 export | 雲端憑證等 | Structured chat 預設會繼承(Use your shell environment) | 關閉並改用白名單 |
.worktreeinclude 複製的 .env | 本機開發憑證 | 每個 Worktree 都有一份副本,Agent 可讀取 | 只放開發用低權限憑證 |
| Prompt、聊天紀錄、Session History | 使用者貼上的內容 | 進入供應商與本機 transcript | 嚴禁貼上金鑰 |
操作步驟:每位開發者的憑證健康檢查
檢查 Copilot 設定檔權限(macOS/Linux):
ls -l ~/.copilot/config.json # 預期:-rw------- (owner-only);若不是,執行: chmod 600 ~/.copilot/config.json檢查 repo 中沒有被提交的金鑰:
git grep -nE "(sk-[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|__Host-console_session)" -- . || echo "no match"確認
.worktreeinclude只列出開發用檔案:cat .worktreeinclude git check-ignore -v .env .env.local開啟 Settings → Experimental → Chat UI,評估是否關閉 Use your shell environment。
開啟 Settings → Accounts,確認沒有未加密警告。
範例:團隊憑證規範(節錄)
1. Agent CLI 一律使用官方登入流程(claude、codex login、cursor-agent login),不得把 API Key 寫入 repo。
2. .worktreeinclude 只能列出開發環境 .env;正式環境憑證不得存在於開發者電腦。
3. Settings → Agents 的 environment 欄位不得填入長期金鑰;需要時使用短效 Token。
4. 不得在 Prompt、Design Mode 截圖、聊天或 Review 註解中貼上任何金鑰。
5. 離職或轉調時,於 Settings → Accounts 移除帳號,並在供應商主控台撤銷 Token。
6. 每次 Orca 版本更新,平台組檢查 release notes 中的 security 項目並通知全員。範例 Prompt:請 AI 掃描 Worktree 的憑證風險
請檢查目前 Worktree,只做「讀取與回報」,不要修改任何檔案:
1. 列出 .worktreeinclude 與 orca.yaml 中所有會被複製或共享到 Worktree 的路徑。
2. 對這些路徑與整個 repo,找出疑似金鑰、Token、密碼的字串(只回報檔名與行號,值以 *** 遮罩)。
3. 檢查 .gitignore 是否涵蓋上述敏感檔。
輸出 Markdown 表格:路徑、類型、是否被 git 追蹤、建議處置。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 回報中沒有出現任何未遮罩的金鑰值
-
git status顯示 Agent 沒有修改任何檔案 - 隨機抽查 2 個「是否被 git 追蹤」的判定,以
git ls-files <path>驗證 - 若回報「無風險」,自行以步驟 2 的
git grep再跑一次交叉確認
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Copilot 設定檔權限 | ls -l ~/.copilot/config.json | -rw------- | chmod 600,並升級至 v1.4.221 以上 |
| repo 無金鑰 | 步驟 2 的 git grep | no match | 移除、改寫歷史並立即輪替金鑰 |
| 共享檔受控 | cat .worktreeinclude | 只有開發用檔案 | 移除不必要項目 |
| 憑證加密 | Settings → Accounts | 無未加密警告 | 修復系統金鑰圈 |
❌ 常見錯誤:在 Annotate AI Diff 的註解或聊天中貼上「這是測試 key 你幫我試試」——這些內容會進入供應商端與本機 transcript,且會出現在 Session History 搜尋結果中。
8.6 企業用量治理範例
📌 查證狀態:教學示例(非官方),非真實客戶專案;所使用的 Orca 功能均依官方文件|來源:Usage & rate-limit tracking、Hot-swap Codex accounts
概念說明
Orca 提供「看得到」與「切得快」兩種能力,但沒有內建預算上限或強制配額。企業治理因此要以「規範 + Orca 可見性 + 供應商主控台」三者組合。
決策表一:帳號配置模式
| 團隊規模 | 帳號模式 | Hot-swap 政策 | 優點 | 風險 |
|---|---|---|---|---|
| 1~5 人 | 每人一個公司帳號 | 不允許 | 簡單、可追溯 | 單人限額易用盡 |
| 6~30 人 | 每人主帳號 + 團隊備用池 | 僅允許切到團隊備用池 | 平衡彈性與追溯 | 備用池需登記使用紀錄 |
| 30 人以上 | 依專案配置帳號 | 依專案切換 | 成本可依專案分攤 | 管理成本高 |
| 高監理產業 | 每人單一帳號 + 指定供應商 | 不允許 | 稽核清楚 | 平行度受限 |
決策表二:用量閾值與對應行動
| 訊號(Orca 可見) | 閾值 | 行動 | 負責人 |
|---|---|---|---|
| 狀態列警告 chip | 任一視窗 ≥ 80% | 暫停新開同題競賽 Worktree | 開發者 |
| 5 小時視窗 | ≥ 90% | Hot-swap 至備用池帳號(若政策允許),並登記 | 開發者 |
| 每週視窗 | ≥ 70% 且距重置 > 3 天 | 通知 Tech Lead 調整平行度 | Tech Lead |
| Credit 餘額 | 低於月預算 20% | 通知採購或主管 | 主管 |
| Stats 預估成本 | 單週超過月預算 40% | 檢討任務拆分與模型選擇 | Tech Lead |
工作範例:30 人支付團隊的四週導入
- 第 1 週:盤點。每人依 8.1 填寫帳號盤點表;平台組彙整,發現 4 人使用個人帳號處理公司 repo。
- 第 2 週:配置。建立團隊備用池(2 個 Claude、2 個 Codex 帳號),在每人 Settings → Agents → Codex Accounts 加上標籤「pool-1」「pool-2」;個人帳號於 Settings → Accounts 移除。
- 第 3 週:閾值演練。每人以 8.2 驗證步驟確認 Usage popover 可見;Tech Lead 示範 80% 與 90% 的處置。
- 第 4 週:月報。每週五由各組長截取 Usage popover 與 Stats 細目,並與供應商主控台比對,填入下方週報範本。
範例:每週用量週報範本
# 用量週報 2026-W44(支付團隊)
| 帳號標籤 | 供應商 | 週視窗最高用量 | 觸發 80% 次數 | Hot-swap 次數 | 主控台實際金額 | Orca 預估 | 差異率 |
|---|---|---|---|---|---|---|---|
| alice-work | Anthropic | 76% | 1 | 0 | 102 | 97 | -4.9% |
| pool-1 | OpenAI | 92% | 3 | 5 | 88 | 70 | -20.5% |
異常說明:pool-1 本週有 5 次 Hot-swap,原因為 refund 模組同題競賽;下週改為兩家競賽。範例 Prompt:請 AI 依週報草稿產出改善建議
以下是本週用量週報(Markdown 表格)。請:
1. 找出觸發 80% 次數 ≥ 3 或 Hot-swap 次數 ≥ 3 的帳號。
2. 針對每個帳號提出最多 2 項改善建議,只能從以下選項中選擇:
降低同題競賽數、改用較小模型、拆小任務、調整排程時段、啟用 Agent hibernation。
3. 不得建議新增帳號以規避限額。
輸出表格:帳號、問題、建議、預期效果。
<貼上週報>🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 被點名的帳號確實符合門檻(自行對照週報數字)
- 建議全部來自指定選項,沒有「新增帳號」之類違反政策的內容
- 「預期效果」沒有捏造具體金額,若有數字需能從週報推算
- 建議與 Orca 實際能力一致(例如 Agent hibernation 是降低資源,不是降低 token)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 盤點完整 | 抽查 3 人的 Settings → Accounts 與盤點表 | 完全一致 | 要求更新盤點表 |
| 無個人帳號 | 抽查帳號標籤 | 沒有個人帳號出現在公司電腦 | 移除並記錄 |
| 閾值可操作 | 請任一開發者示範 90% 處置 | 能完成 Hot-swap 並 Restart 既有工作階段 | 重新訓練 8.3 |
| 週報可追溯 | 比對週報與供應商主控台 | 金額欄位來自主控台,差異率有說明 | 退回組長補充 |
| 政策落地 | 新人到職清單 | 含本節決策表與驗證步驟 | 更新到職清單 |
企業治理考量:Orca 的用量資料存在於每位開發者的本機,並非集中式報表。若需集中管理,應以供應商的企業主控台或 API 作為權威來源,Orca 則作為開發者端的即時預警工具。
8.7 本章 Review 與驗證清單
- 能說明 BYO 模式下「計費主體」與「Orca 角色」的差別
- 已在 Settings → Accounts 完成帳號盤點,並確認 Linux 無未加密警告
- 能閱讀 Usage popover 的排序、視窗、警告 chip 與狀態文字
- 已切換 Detailed/Compact 與 % used/% remaining 並理解差異
- 已實際操作 Codex 或 Claude Hot-swap,並驗證既有工作階段需 Restart 才會換帳號
- 能說明 managed 帳號的
config.toml鏡像機制與警告橫幅的處置 - 能解讀 Stats 的
• inferred pricing與• excludes unpriced models標記,且知道權威數據在供應商主控台 - 已完成 8.5 的憑證健康檢查(Copilot 權限、
git grep、.worktreeinclude) - 已為團隊制定用量閾值決策表,並產出第一份週報
第九章 Hooks Memory 與 Session History
本章處理「Agent 每次啟動時拿到什麼脈絡、Worktree 建立時自動做了什麼、Orca 如何得知 Agent 狀態,以及如何找回與續接過去的對話」。這四件事分別對應 Per-repo Hooks、Worktree Setup Hooks、Memory 檔、Agent Status Hooks 與 Session History。
先釐清容易混淆的四種「Hook」:
| 名稱 | 誰定義 | 何時執行 | 存放位置 | 本書章節 |
|---|---|---|---|---|
| Per-repo Agent hooks | Agent(Claude Code、Codex) | Agent 自身生命週期事件 | repo 的 .claude/、.codex/ | 9.1 |
| Worktree setup/archive hooks | Orca | Worktree 建立後/封存前 | Settings → Repository → Hooks 或 orca.yaml | 9.2 |
| Startup hooks per agent | Orca | 該 Agent 啟動時 | Settings → Agents | 9.2 |
| Agent status hooks | Orca 管理 | Agent 回報 working/waiting/done | Orca 自動安裝 | 9.4 |
9.1 Per-repo Hooks
📌 查證狀態:Orca 行為依官方文件明確記載;Claude Code hook 語法屬依官方說明延伸(教學推論),以 Anthropic 官方文件為準|來源:Agent hooks & memory
概念說明
Orca 會讀取每個 repo 的 .claude/ 與 .codex/ 設定。你已經寫好的 Agent hooks,在 Orca 於該 repo 的 Worktree 中啟動 Agent 時會照常執行。換句話說,Orca 不發明新的 Agent hook 格式,而是尊重 Agent 既有慣例,並因為每個 Worktree 都是完整 checkout,讓 repo 內提交的 hooks 自動出現在每一個 Worktree 中。
| 適合放在 Per-repo hook 的事 | 不適合的事 |
|---|---|
| 編輯後自動格式化、lint | 需要正式環境憑證的動作 |
| 阻擋修改受保護目錄 | 長時間(數分鐘)執行的建置 |
| 寫入稽核紀錄 | 需要互動輸入的指令 |
操作步驟:為 repo 加入 Claude Code 編輯後檢查 hook
- 在 repo 根目錄建立
.claude/settings.json(提交到版本控制,讓所有 Worktree 共用)。 - 建立 hook 腳本
scripts/hooks/guard-protected.sh並賦予執行權限。 - 提交後在 Orca 建立新 Worktree,從選單啟動 Claude Code。
- 請 Claude 修改受保護目錄中的檔案,觀察 hook 是否阻擋。
範例:.claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "./scripts/hooks/guard-protected.sh" }
]
}
]
}
}範例:scripts/hooks/guard-protected.sh
#!/usr/bin/env bash
# 從 stdin 讀取 Claude Code 提供的 JSON,阻擋對 db/migration/ 的寫入
payload="$(cat)"
if printf '%s' "$payload" | grep -q '"file_path": *"[^"]*db/migration/'; then
echo "db/migration/ 受保護,請改為在 docs/ 提出遷移建議" >&2
exit 2
fi
exit 0📌 查證狀態:
PreToolUse、matcher、exit code 2 表示阻擋等語意為 Claude Code 自身 hook 規格,依官方說明延伸(教學推論);請以 Anthropic Claude Code 官方 hooks 文件與claude --help確認|來源:Claude Code
Codex 的 repo 設定:Orca 同樣讀取 .codex/。Codex 的 hook 與設定語法請依 OpenAI Codex 官方文件撰寫;本書不提供未經查證的 Codex hook 範例。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| hook 檔存在於 Worktree | 在新 Worktree 執行 ls .claude/settings.json scripts/hooks/ | 檔案存在 | 確認已提交且 Worktree 從含此提交的分支建立 |
| 腳本可執行 | test -x scripts/hooks/guard-protected.sh && echo ok | ok | chmod +x 後重新提交 |
| 阻擋生效 | 請 Claude 編輯 db/migration/V1__init.sql | Claude 回報被 hook 阻擋並顯示訊息 | 以下方指令單獨測試腳本(預期輸出 2) |
| 不影響正常檔案 | 請 Claude 編輯 src/ 下檔案 | 正常完成 | 檢查 grep 條件是否過寬 |
單獨測試腳本的指令:
echo '{"tool_input":{"file_path":"db/migration/x.sql"}}' | ./scripts/hooks/guard-protected.sh; echo $?⚠️ 注意事項:Per-repo hooks 會在每個Worktree、每位開發者、每次 Agent 啟動時執行。hook 內容需經 Code Review,視同 CI 腳本管理;惡意或錯誤的 hook 會被所有 Agent 自動執行。
9.2 Worktree Setup Hooks
📌 查證狀態:UI 路徑與 CLI 旗標依官方文件明確記載;
orca.yaml的scripts、setupAgentStartupPolicy鍵與環境變數依官方原始碼(src/shared/orca-yaml-hook-types.ts、src/main/setup-hook-env-vars.ts)|來源:Agent hooks & memory、Orca CLI reference、stablyai/orca
概念說明
新 Worktree 是乾淨的 checkout:沒有 node_modules、沒有 .env、沒有建置快取。Worktree setup hook 讓你在 Worktree 建立後自動執行指令,例如 pnpm install、direnv allow,或還原 .env 的腳本;archive hook 則在 Worktree 封存前執行清理。
| 機制 | 設定位置 | 適用範圍 | 版本控制 |
|---|---|---|---|
| Repository Hooks | Settings → Repository → Hooks(Auto-run commands on worktree create) | 本機該 repo | 否(個人設定) |
orca.yaml 的 scripts.setup/scripts.archive | repo 根目錄 | 所有使用者 | 是 |
setupAgentStartupPolicy | orca.yaml 或 Repository 設定 | 決定 Agent 是否等待 setup 完成 | 是/否 |
| Startup hooks per agent | Settings → Agents | 特定 Agent 啟動時 | 否 |
Shared paths/.worktreeinclude | 見第二章 2.3 | 共享或複製被 gitignore 的檔案 | 部分 |
Setup 腳本可用的環境變數
| 變數 | 意義 |
|---|---|
ORCA_ROOT_PATH | 主 checkout 路徑,適合從這裡複製共用檔案(如 .env) |
ORCA_WORKTREE_PATH | 正在建立的 Worktree 路徑;setup 指令以此為工作目錄 |
ORCA_WORKSPACE_NAME | 工作區名稱,通常取自分支名 |
Agent 啟動時機(setupAgentStartupPolicy)
| 值 | 行為 | 適用 |
|---|---|---|
start-immediately(預設) | Setup 與 Agent 平行啟動 | Setup 只做非必要準備 |
wait-for-setup | 等 Setup 完成才啟動 Agent | Agent 一開始就需要依賴套件或專案 skills |
操作步驟:設定共用的 setup/archive hook
- 在 repo 根目錄建立或編輯
orca.yaml(範例如下),提交到主分支。 - 第一次遇到含
orca.yaml腳本的 repo 時,Orca 會詢問是否信任;確認內容後再允許。 - 開啟 Settings → Repository → Hooks,確認 Orca 讀到
orca.yaml的腳本,並檢視 setup 執行政策(詢問、預設執行或預設略過)。 - 建立新 Worktree,觀察分頁中的即時 setup 狀態。
- 以 CLI 建立時可明確控制:
--setup run執行、--setup skip略過、--setup inherit依 repo 政策。
範例:orca.yaml
# orca.yaml(repo 根目錄)
setupAgentStartupPolicy: wait-for-setup
scripts:
setup: |
cp "$ORCA_ROOT_PATH/.env.local" "$ORCA_WORKTREE_PATH/.env.local" 2>/dev/null || true
pnpm install --frozen-lockfile
echo "setup done for $ORCA_WORKSPACE_NAME"
archive: |
rm -rf node_modules .turbo
worktree:
sharedDirectories:
- .cache範例:以 CLI 建立 Worktree 並控制 setup
# 依 repo 政策執行 setup,並在第一個終端機啟動 Claude
orca worktree create --name review-api --agent claude --setup run --json
# 快速檢視用,略過 setup
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json範例 Prompt:請 AI 為 repo 撰寫 setup hook
請為本 repo 撰寫 orca.yaml 的 scripts.setup 與 scripts.archive,要求:
1. setup:從 $ORCA_ROOT_PATH 複製 .env.local(若存在),執行 pnpm install --frozen-lockfile,
再執行 pnpm prisma generate。任何一步失敗都要以非 0 結束。
2. archive:只刪除 node_modules、.turbo、dist,不得刪除其他任何路徑。
3. 不得使用 sudo、curl | sh、或任何網路下載腳本。
4. 同時輸出一段說明,列出 setup 預估耗時與失敗時的排查方式。
只輸出 orca.yaml 內容與說明,不要修改其他檔案。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
-
archive中的rm -rf目標只有node_modules、.turbo、dist,沒有變數展開後可能為空的路徑(例如rm -rf "$X/") -
setup使用--frozen-lockfile,不會改寫 lockfile - 沒有
sudo、curl | sh、wget等下載執行 - 失敗會以非 0 結束(多行腳本建議以
set -e或&&串接) - 實際建立一個 Worktree 跑過一次,setup 狀態顯示成功
✅ 驗證方式
執行:
orca worktree create --name hook-test --setup run --json orca worktree list --json預期:新 Worktree 出現在清單;分頁顯示 setup 進度並完成。進入該 Worktree 執行:
ls -d node_modules && test -f .env.local && echo "setup ok"判讀:
檢查項目 預期結果 若不符合 依賴已安裝 node_modules存在查看分頁中的 setup 輸出;確認 orca.yaml在主分支.env.local已複製setup ok確認主 checkout 有此檔 Agent 等待 setup Agent 在 setup 完成後才啟動 確認 setupAgentStartupPolicy: wait-for-setuparchive 生效 封存該 Worktree 前後觀察 失敗的 archive hook 會阻擋移除(屬保護行為),修正腳本後重試
⚠️ 注意事項
- Orca 在無人值守的 setup 執行中一律啟用 git 憑證保護,避免腳本觸發憑證提示而卡住。
- WSL 環境下,Orca 會轉換
ORCA_ROOT_PATH、ORCA_WORKTREE_PATH等路徑變數;腳本請一律使用變數,不要寫死 Windows 路徑。 orca.yaml讀取失敗時不會被當成「沒有 setup」快取;修正檔案後重新建立 Worktree 即可。
企業治理考量:orca.yaml 的腳本會在每位開發者的電腦上自動執行,必須納入 Code Review 與 CODEOWNERS,並由平台組負責。
9.3 Memory 檔案設計
📌 查證狀態:Orca 行為依官方文件明確記載;檔案內容設計為教學示例(非官方)|來源:Agent hooks & memory、Chat UI
概念說明
Claude 的 CLAUDE.md 與 Codex 的 AGENTS.md(可放在 repo 根目錄或子目錄)是 Agent 的「專案記憶」,每次啟動(含 Resume 的工作階段)都會讀入。Orca 不改寫這些檔案(它們屬於 Agent),只在檔案總管中像一般檔案一樣顯示,讓你可以直接編輯。
| 設計原則 | 說明 |
|---|---|
| 短而具體 | Memory 會佔用每一次對話的 context;只放「每次都需要」的規則 |
| 可驗證 | 每條規則都應該能被檢查(例如指令、路徑、命名規則) |
| 分層 | 根目錄放全域規則,子目錄(如 services/payments/AGENTS.md)放局部規則 |
| 同步 | 同時使用 Claude 與 Codex 時,兩個檔案的核心規則應一致;可讓 CLAUDE.md 引用 AGENTS.md 的內容 |
| 版本控制 | 提交到 repo,修改需 Review |
操作步驟
- 在 Orca 的檔案總管開啟(或建立)repo 根目錄的
AGENTS.md與CLAUDE.md。 - 依下方範本撰寫,控制在約 100 行以內。
- 提交後建立新 Worktree,啟動 Agent 並要求它複述規則(驗證方式見下)。
- 使用 Structured Claude chat 時,點模型旁的 context 圓環,確認 memory 檔佔用的 token 量合理。
範例:AGENTS.md
# 專案規則(Agent 必讀)
## 建置與測試
- 安裝:pnpm install --frozen-lockfile
- 單元測試:pnpm test -- --run
- 型別檢查:pnpm typecheck
- 完成任何變更後,必須執行上述兩項並在回覆中貼出最後 20 行輸出。
## 程式碼規範
- TypeScript strict;禁止 any(測試檔除外)。
- 金額一律使用 src/lib/money.ts 的 Money 型別,禁止使用 number 表示金額。
## 禁區
- 不得修改 db/migration/、infra/、.github/workflows/。
- 不得新增相依套件;需要時在回覆中提出理由並停止。
## 回覆格式
- 結尾附「變更檔案清單」「測試證據」「需人工確認事項」三段。範例:CLAUDE.md
# Claude 專用補充
請先遵守 AGENTS.md 的所有規則(同目錄)。
## Claude 特有
- 需要多步驟時先用 TodoWrite 列計畫,等使用者確認再實作。
- 啟動 subagent 前,說明每個 subagent 的範圍,避免同時修改同一檔案。📌 查證狀態:
CLAUDE.md是否自動讀入同目錄的AGENTS.md依 Claude Code 版本而異,屬依官方說明延伸(教學推論);範本以「請先遵守」明示,並以下方驗證方式確認|來源:Agent hooks & memory
範例 Prompt:請 AI 從既有 repo 萃取 Memory 草稿
請閱讀 package.json、README.md、.github/workflows/*.yml、eslint 與 tsconfig 設定,
為本 repo 起草 AGENTS.md(100 行以內),包含:建置與測試指令、程式碼規範、禁區、回覆格式。
規則:
1. 每條指令必須真實存在於 package.json scripts 或 workflow 中,並在草稿後附「來源對照表」。
2. 不確定的規則標示 [待確認],不得自行發明。
3. 只輸出草稿,不要建立或修改檔案。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 「來源對照表」中的每個指令都能在
package.json或 workflow 中找到 - 親自執行草稿中的建置與測試指令,確認可成功執行
- 禁區目錄確實存在,且與 CODEOWNERS 或團隊共識一致
- 所有
[待確認]項目已由負責人決定或刪除 - 總長度在 100 行左右,沒有與 README 大量重複的說明
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Agent 讀到 Memory | 新工作階段第一句問「請條列本 repo 的禁區目錄」 | 正確列出 db/migration/、infra/、.github/workflows/ | 確認檔名大小寫與位置;重開工作階段 |
| 規則被遵守 | 請 Agent 修改 infra/ 下檔案 | Agent 拒絕或要求確認 | 規則寫得不夠明確,改用「不得」等強語氣 |
| 回覆格式 | 任一小任務完成後 | 結尾含三段指定內容 | 在 Memory 中把格式放到更前面 |
| Context 成本 | Structured Claude chat 的 context 圓環 | memory 佔比合理(不應主導 context) | 精簡 Memory,把細節移到子目錄 |
| Codex 一致 | 以 Codex 重複第一項 | 與 Claude 回答一致 | 同步 AGENTS.md 與 CLAUDE.md |
❌ 常見錯誤:把整份架構文件貼進 CLAUDE.md。這會讓每次對話都消耗大量 context,且 Agent 更容易忽略真正重要的規則。
9.4 Agent Status Hooks
📌 查證狀態:官方文件明確記載|來源:Agent hooks & memory、Settings、Orca CLI reference
概念說明
Agent status hooks 是 Orca 管理的 hook,讓 Agent 回報 working/waiting/done 狀態到 Orca UI,驅動狀態點、Dashboard、通知與 Hibernation 判斷。
| 特性 | 說明 |
|---|---|
| 開關位置 | Settings → Agents → Agent status hooks |
| 即時生效 | 關閉會移除受管 hook 並停止重新安裝;開啟會恢復,不需重啟 Orca(Windows 的 WSL hook relay 也跟隨此開關) |
| CLI | orca agent hooks status --json、orca agent hooks on --json、orca agent hooks off --json |
| Codex | Orca 只在內容變更時才寫入 ~/.codex 的 hook,避免 Codex 每次都要求核准 |
| 重啟存活 | Hook endpoint 寫在 {userData}/agent-hooks/endpoint.env(POSIX)或 endpoint.cmd(Windows),每次 hook 呼叫重新讀取,長時間執行的 Agent 在 Orca 重啟後仍能連到新的 Orca server |
| 進度註記 | Agent 可透過 orca worktree set --comment 更新 Worktree 的進度註記(另見 16.5 Worktree Checkpoints) |
sequenceDiagram participant A as Agent CLI participant H as Orca 受管 hook participant E as endpoint 檔 participant O as Orca Server participant UI as 側欄與 Dashboard A->>H: 事件(開始工作、等待輸入、完成) H->>E: 讀取目前 endpoint H->>O: 回報狀態 O->>UI: 更新狀態點與欄位 Note over O,E: Orca 重啟後改寫 endpoint 檔,hook 下次呼叫即連到新 server
如何閱讀此圖:每次 Agent 觸發事件,受管 hook 都會「先讀 endpoint 檔、再回報」。因為 endpoint 是每次重新讀取,即使 Orca 重新啟動、port 改變,執行中的 Agent 也不會把狀態送到已失效的位址。
操作步驟
開啟 Settings → Agents,確認 Agent status hooks 為開啟。
在終端機以 CLI 確認狀態:
orca agent hooks status --json疑難排解時可暫時關閉再開啟:
orca agent hooks off --json orca agent hooks on --json讓 Agent 回報進度註記(可寫入 Memory 規則,要求 Agent 在里程碑時執行):
orca worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Hooks 開啟 | orca agent hooks status --json | 回報為開啟 | 執行 orca agent hooks on --json |
| 狀態即時 | 啟動 Claude 並送出需要確認的指令 | 分頁顯示琥珀色問號(waiting) | 確認是從選單啟動;重開工作階段 |
| 重啟存活 | Agent 執行中重啟 Orca,再觀察狀態 | 狀態仍會更新 | 檢查 {userData}/agent-hooks/ 下 endpoint 檔是否存在 |
| Codex 不重複要求核准 | 連續開兩個 Codex 分頁 | 第二次不再要求核准 hook | 確認 Orca 版本為新版 |
| 進度註記 | 執行 orca worktree set --comment | 側欄 Worktree 顯示註記 | 確認 --worktree 選擇器正確 |
⚠️ 注意事項:關閉 Agent status hooks 會讓 Dashboard、通知、Hibernation 的準確度下降(只剩 OSC 標題偵測)。除非排錯,不建議關閉。
9.5 Session History 檢視與續接
📌 查證狀態:官方文件明確記載|來源:Agent session history、Orca CLI reference → Session search
概念說明
Orca 會掃描支援的 Agent CLI 留在磁碟上的 transcript,列在右側欄的 Agent Session History 面板。選一個舊工作階段按 Resume,Orca 會在新終端機以相同 cwd、相同 session ID 執行該 Agent 的續接指令。不需要額外啟用:只要 CLI 有寫 transcript,下次掃描就會出現。
支援掃描的 Agent:Claude、Codex、Muse Code、Hermes、Pi、OMP、Prime Agent、Cursor、Gemini、Antigravity、Rovo Dev、Copilot、OpenCode、Grok、OpenClaw、Devin、Droid、Kimi、Kiro、CodeBuddy、ZCode、Qoder。
Transcript 來源範例
| Agent | 來源 |
|---|---|
| Codex | ~/.codex/sessions |
| Claude | ~/.claude 歷史 |
| Muse Code | ~/.local/share/muse/sessions |
| OpenCode | 舊版 session 檔或 ~/.local/share/opencode/opencode.db |
| CodeBuddy | .codebuddy/projects 下的專案 transcript |
| Qoder | ~/.qoder/projects |
續接指令對照(Resume 實際執行的指令)
| Agent | 指令 |
|---|---|
| Claude | claude --resume <id> |
| Codex | codex resume <id>(若原工作階段設定過 CODEX_HOME 會重新匯出) |
| Muse Code | muse resume <session-id> |
| Pi | pi --session <session_file>(檔案遺失時無法 Resume) |
| Prime Agent | prime-agent --resume <path> |
| Cursor | cursor-agent --resume <id> |
| Rovo Dev | acli rovodev run --restore <id> |
操作步驟:找到並續接舊工作階段
- 開啟右側欄,切到 Agents 分頁,標頭為「Agent Session History」,並顯示如「12 shown · 47 recent」的計數。
- 用頂端的 Scope 切換範圍:Workspace(目前工作區)、Project(目前專案)、All(本機所有工作階段)。
- 在搜尋框輸入關鍵字,可比對標題、工作目錄、分支、模型與對話預覽。搜尋時排序可選 Most relevant 或 Newest;瀏覽時可選 Last updated 或 Created。
- 用 View options 選擇掃描哪些 Agent(Select all/Clear)、分組方式(Project、Folder、Agent)、以及 Hide empty sessions。
- 點一列開啟細節:工作目錄、分支、模型、訊息數、First prompt(展開時載入完整第一則訊息,可按 Copy)與最近幾回合。
- 從列的動作選:
- Resume:在該工作階段的 cwd 開新終端機並續接
- Resume in New Native Chat:以結構化聊天開啟(Claude 須在原工作區;Codex 可在其他工作區)
- Copy resume command:複製指令到外部終端機執行
- Copy session ID/Copy log path、Open log/Reveal log、Open cwd
- 也可以把列拖曳到工作區中直接續接。
- 需要重新掃描時,按標頭的 Refresh Session History。
跨電腦搜尋
在 Settings → Session History 為想要的電腦開啟 Search inside sessions(或 Enable on all computers),即可搜尋其他已連線電腦與 paired Orca Server 上已索引的 transcript。可搜尋資料保留在各自電腦上;離線或未授權的電腦會顯示範圍提示。
範例:以 CLI 搜尋對話
# 搜尋對話內容
orca search --query "rate limit" --scope conversation --limit 20 --json
# 只看 Codex、最近 30 天、依時間排序
orca search --query "migration" --agent codex --since 30d --sort recent --json
# 只查索引狀態
orca search --index-status --json範例 Prompt:續接舊工作階段時的「重新定錨」
我們在中斷前正在處理 refund 模組的冪等性修正。請先:
1. 執行 git log --oneline -5 與 git status,回報目前分支狀態。
2. 摘要你在本工作階段中已完成與未完成的項目(只根據對話與目前程式碼,不要猜測)。
3. 列出接下來 3 個步驟,等我確認後再繼續。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 回報的
git log、git status與你自己執行的結果一致 - 「已完成」項目都能在
git diff或提交中找到對應變更 - Agent 沒有在你確認前就開始修改檔案
- 若 Worktree 在中斷期間被他人更動,Agent 有指出差異
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 面板可見 | 右側欄 Agents 分頁 | 顯示 Agent Session History 與計數 | 按 Refresh Session History |
| 搜尋 | 輸入舊對話中的關鍵字 | 找到該工作階段 | 確認 View options 中該 Agent 已勾選 |
| Resume | 對 Claude 列按 Resume | 新終端機執行 claude --resume <id> 並出現舊對話 | 確認目前是本機工作區(遠端工作區只能瀏覽,不能 Resume) |
| CLI 搜尋 | orca search --query "<關鍵字>" --json | 回傳包含該工作階段 | 先執行 orca search --index-status --json 檢查索引 |
| 跨電腦 | 在另一台電腦開啟 Search inside sessions 後搜尋 | 結果包含另一台電腦的工作階段 | 檢查該電腦是否在線並已授權 |
⚠️ 注意事項
- Resume 是在「Orca 正在渲染的那台機器」上執行 Agent CLI。連到遠端工作區時,請切回本機工作區,或用 Copy resume command 到遠端自行執行。
- 一旦對話被保留給 structured chat,就不能再用終端機 Resume。
- Session History 會呈現完整對話內容,包含過去貼上的任何敏感資訊;這也是 8.5 嚴禁在 Prompt 中貼金鑰的原因之一。
企業治理考量:跨電腦搜尋會讓一位使用者在多台電腦之間檢索對話內容。高監理環境應評估是否只在單機啟用,並將 transcript 目錄納入端點資料保護政策。
9.6 本章 Review 與驗證清單
- 能區分 Per-repo Agent hooks、Worktree setup/archive hooks、Startup hooks per agent 與 Agent status hooks
- 已在 repo 中加入一個 Claude Code hook,並以單獨執行腳本與實際 Agent 操作兩種方式驗證
- 已撰寫
orca.yaml的scripts.setup/scripts.archive,並以orca worktree create --setup run驗證 - 能說明
ORCA_ROOT_PATH、ORCA_WORKTREE_PATH、ORCA_WORKSPACE_NAME的用途 - 能說明
setupAgentStartupPolicy的兩種值與適用情境 - 已建立
AGENTS.md/CLAUDE.md,並以「請 Agent 複述禁區」驗證被讀入 - 已以
orca agent hooks status --json確認 Agent status hooks 開啟 - 能說明 hook endpoint 檔讓 Agent 在 Orca 重啟後仍能回報狀態的原理
- 已從 Agent Session History 成功 Resume 一個 Claude 或 Codex 工作階段
- 已以
orca search從 CLI 找到一段舊對話
第十章 Agent 生命週期與通知
當你同時跑五個、十個 Agent,真正的瓶頸不是 Agent 的速度,而是「你什麼時候該回去看哪一個」。本章說明 Orca 如何判斷 Agent 狀態、如何把需要你的 Agent 推到眼前,以及如何讓閒置的 Agent 休眠以節省資源。
10.1 Agent 狀態指示與 Dashboard
📌 查證狀態:官方文件明確記載|來源:Agents & sessions、Agent Dashboard、Settings
概念說明
Orca 透過兩個訊號判斷 Agent 狀態:Agent 終端機送出的 OSC 標題序列,以及 9.4 的 Agent status hooks。狀態會顯示在分頁、側欄 Worktree 列與 Agent Dashboard。
| 符號 | 狀態 | 意義 | 你該做什麼 |
|---|---|---|---|
| 旋轉圖示 | Working | Agent 正在工作 | 不需介入 |
| 琥珀色問號 | Waiting/Needs You | 等你回答或核准 | 優先處理 |
| 翠綠色勾(Dashboard)或翠綠色點(側欄) | Done | 回合完成 | Review 成果 |
| 紅點 | Blocked/中斷/失敗 | 被阻擋或出錯 | 查看終端機輸出 |
| 灰點 | Idle | 已安靜一段時間 | 視需要收尾或讓它休眠 |
| 無符號 | 非可辨識 Agent | 一般終端機或未經選單啟動的 Agent | 改從選單啟動以取得狀態 |
stateDiagram-v2 state "啟動中" as Launch state "工作中" as Working state "等待你" as Waiting state "完成" as Done state "閒置" as Idle state "休眠" as Sleeping state "已結束" as Exited [*] --> Launch Launch --> Working: 收到提示 Working --> Waiting: 需要核准或回答 Waiting --> Working: 你回覆 Working --> Done: 回合完成 Done --> Working: 新提示 Done --> Idle: 約 30 分鐘無活動 Idle --> Sleeping: 符合休眠條件 Sleeping --> Working: 重新開啟並自動續接 Working --> Exited: 程序結束 Done --> Exited: 程序結束 Exited --> Launch: Restart chip Exited --> [*]
如何閱讀此圖:從 [*] 開始,Agent 啟動後在「工作中」「等待你」「完成」之間循環;只有「等待你」需要你介入。完成後長時間無活動會進入閒置;開啟 Hibernation(10.3)且符合條件時才會進入休眠。程序結束後可用 Restart chip(10.2)回到啟動。
Agent Dashboard
Agent Dashboard 是所有 Agent 的看板,目前屬實驗功能。
| 項目 | 說明 |
|---|---|
| 啟用 | Settings → Experimental → Agent Dashboard |
| 快捷鍵 | 在 Settings → Shortcuts 為 Toggle Agent Dashboard 指定按鍵(預設未綁定) |
| 欄位 | Needs You、Working、Done、Idle(Idle 預設隱藏,從看板齒輪開啟 Show idle agents) |
| 開啟方式 | 視窗內開啟或彈出獨立視窗 |
| 工具列 | 搜尋,以及 Project、Workspace 狀態、PR/MR 狀態篩選 |
| 卡片 | 標頭、預覽、頁尾;需要你時為琥珀色調,完成時為綠色調;SSH 與遠端主機有 host 標記 |
| Subagent | 巢狀 subagent 以子列呈現 |
操作步驟
- 開啟 Settings → Experimental,啟用 Agent Dashboard。
- 到 Settings → Shortcuts 為 Toggle Agent Dashboard 綁定按鍵,例如
Ctrl+Alt+D(自行選擇不衝突的按鍵)。 - 從新 Worktree 選單啟動兩個 Agent,一個給簡單任務,一個給需要核准的任務。
- 開啟 Dashboard,觀察卡片在欄位間移動;點卡片可跳到對應窗格。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 狀態點出現 | 從選單啟動 Claude 並送出提示 | 分頁出現旋轉圖示,完成後變綠 | 確認是從選單啟動;檢查 orca agent hooks status --json |
| Needs You | 讓 Agent 要求核准一個指令(Manual 權限) | 出現琥珀色問號,Dashboard 卡片移到 Needs You | 確認權限模式不是 Yolo |
| Dashboard 開啟 | 按綁定的快捷鍵 | Dashboard 出現 | 確認 Experimental 開關已啟用 |
| Idle 欄 | 齒輪開啟 Show idle agents | 出現 Idle 欄 | 等待足夠時間或確認設定 |
| 未辨識 Agent | 在一般終端機手動輸入 claude | 可能沒有狀態符號 | 屬預期;改從選單啟動 |
10.2 啟動預設與 Restart Chip
📌 查證狀態:官方文件明確記載;v1.4.242 續接保留旗標依官方 Release Notes|來源:Agents & sessions、Orca CLI reference、Releases
概念說明
| 階段 | 發生什麼 |
|---|---|
| Launch | 從選單、新 Worktree 對話框、CLI 或 Automation 啟動,帶入預設參數 |
| Work | Agent 讀寫檔案、執行指令;狀態為 Working/Waiting |
| Idle | 回合結束,觸發「Agent 完成」通知(10.4) |
| Exit | 程序結束,分頁顯示 Restart chip |
啟動預設
- Settings → Agents:展開某個 Agent 列,可編輯預設啟動參數(例如模型、權限旗標),並有 Reset 回復預設。
- 新 Worktree 對話框的 Agent 選擇器可按 Set as default,把該 Agent 設為預設。
- 自 v1.4.242 起,Resume 會保留 Claude 的 effort 與啟動旗標,以及 Codex 的權限設定。
Restart chip
Agent 程序結束後,分頁上出現 Restart chip。點擊即在相同 cwd以相同 Agent重新開啟;Codex 會沿用目前選用的帳號(見 8.3)。
範例:以 CLI 啟動與等待
# 以指定模型與 effort 在目前 Worktree 啟動 Codex
orca agent launch --agent codex --model gpt-6-astra --effort high --prompt "Fix the failing date parser tests" --json
# 等待某個終端機的 Agent 進入閒置(最多 5 分鐘)
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json📌 查證狀態:模型名稱
gpt-6-astra為官方 CLI 文件中的示例值;實際可用模型請以codex --help與帳號權限為準|來源:Orca CLI reference
範例:團隊建議的啟動預設
| Agent | 建議預設參數方向 | 理由 |
|---|---|---|
| Claude Code | 預設權限(Manual) | 讓核准點保留在人手上 |
| Codex | 一般任務 effort 中等,複雜重構才調高 | 控制用量(見第八章) |
| 其他 Agent | 維持 CLI 預設 | 減少不同電腦的差異 |
📌 查證狀態:教學示例(非官方)|來源:Agents & sessions
✅ 驗證方式
在 Settings → Agents 展開 Codex,加入一個啟動參數後儲存。
從選單啟動 Codex,在終端機頂端或
ps輸出確認參數已帶入:ps -ef | grep -i codex在 Agent 中輸入
/exit(或結束程序),預期分頁出現 Restart chip;點擊後在同一 cwd 重新啟動,可用pwd確認。執行
orca terminal wait ... --for tui-idle,預期 Agent 完成回合後指令結束並回傳 JSON;若逾時,確認--terminalhandle 正確(可由orca terminal list --json取得)。按 Reset 後重新啟動,預期參數回到預設。
10.3 Agent Hibernation
📌 查證狀態:官方文件明確記載|來源:Agent hibernation
概念說明
Hibernation 會讓「已完成且一段時間沒人碰」的 Agent 程序休眠以釋放記憶體;下次開啟該 Worktree 時,Orca 用 Agent 的續接旗標自動恢復對話。
| 設定 | 說明 |
|---|---|
| 開關 | Settings → Experimental → Agent hibernation(預設關閉) |
| Hibernate after | 預設 30 分鐘,範圍 1 分鐘至 24 小時 |
| 計時重置 | 按鍵、終端機輸出或造訪該分頁都會重置 |
| 多窗格 | 同一 Worktree 的多個窗格以單位一起休眠 |
| 手動 | 側欄可手動 Sleep,或 Sleep with Descendants 連同子工作區一起休眠 |
| 顯示 | 側欄篩選可決定是否顯示休眠中的 Worktree;快捷鍵 Toggle Sleeping Workspaces |
支援自動休眠(可續接)的 Agent:Claude、Codex、Gemini、Antigravity、OpenCode、Pi、MiMo Code、Droid、Grok、Devin、OMP。
不會休眠:Cursor CLI、Hermes、Copilot、Trae 等未提供可靠續接機制的 Agent。
flowchart TD
A["Agent 回合完成"] --> B{"位於目前或前景 Worktree"}
B -- 是 --> X["不休眠"]
B -- 否 --> C{"完成後有按鍵"}
C -- 有 --> X
C -- 無 --> D{"Agent 可續接"}
D -- 否 --> X
D -- 是 --> E{"閒置時間已達設定值"}
E -- 否 --> X
E -- 是 --> F{"有行動裝置、編排派工或存活的 subagent"}
F -- 有 --> X
F -- 無 --> S["休眠"]
S --> R["重新開啟 Worktree"]
R --> T{"續接成功"}
T -- 是 --> W["恢復原對話"]
T -- 否 --> N["開啟新的提示"]如何閱讀此圖:休眠必須所有條件同時成立;任何一個菱形走向「不休眠」都會讓 Agent 保持執行。重新開啟時,Orca 重用當初擷取的啟動指令與環境變數執行續接;續接失敗則開啟全新提示,不會遺失 Worktree 中的檔案。
操作步驟
- 開啟 Settings → Experimental → Agent hibernation。
- 練習時把 Hibernate after 設為 1 分鐘;正式使用建議 30 分鐘以上。
- 在一個背景 Worktree 啟動 Claude,完成一個小任務後切到另一個 Worktree,不要碰原本的分頁。
- 1 分鐘後觀察側欄,原 Worktree 顯示為休眠。
- 點回該 Worktree,Agent 自動續接。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 進入休眠 | 依上述步驟等待 | 側欄顯示休眠 | 確認不在前景 Worktree、完成後未按鍵、Agent 在可續接清單 |
| 釋放資源 | 休眠前後比較系統工作管理員中 Agent 程序 | 該 Agent 程序消失 | 檢查是否有存活的 subagent 或行動裝置連線 |
| 自動續接 | 點回 Worktree,問「我們剛剛做了什麼?」 | Agent 能回答前一個任務 | 若開啟新提示,代表續接失敗,可從 Session History(9.5)手動 Resume |
| 不支援的 Agent | 對 Cursor CLI 重複步驟 | 不休眠 | 屬預期 |
| 手動休眠 | 側欄右鍵 Sleep with Descendants | 父子工作區一起休眠 | 確認版本為 v1.4.164 以上 |
企業治理考量:Hibernation 對多 Agent 並行的筆電使用者效益最大。長時間執行的監督式工作流(第十六章)會因「未完成的編排派工」而不休眠,這是保護行為,不需調整。
10.4 Notifications 與 Inbox
📌 查證狀態:官方文件明確記載;v1.4.221 依機器靜音依官方 Release Notes|來源:Notifications、Releases
概念說明
| 事件 | 系統通知 | 音效 | 未讀標記 |
|---|---|---|---|
| 終端機 Agent 由 working 轉 idle | 有 | 有(連續觸發也不會被吞掉) | Worktree chip |
| Structured chat 回合成功 | 無 | 無 | 分頁與工作區標為未讀 |
| Structured chat 回合失敗或取消 | 無 | 無 | 無 |
Inbox(標頭鈴鐺):標頭的鈴鐺彙總所有 Worktree 的未讀項目;點擊會跳到對應窗格。macOS 的 Dock 圖示 badge 會同步未讀數。通知可按右鍵標回未讀。
Settings → Notifications
| 設定 | 說明 |
|---|---|
| 類別開關 | 每類事件可選系統通知、音效,或只顯示 chip |
| Machines | 依機器(本機、SSH 目標、paired server)決定是否通知,以排除清單儲存 |
| 自訂音效 | 支援 MP3、WAV、OGG、M4A、AAC、FLAC,可調音量 |
| 手機推播 | 不受上述設定影響(見第十九章) |
範例:團隊通知政策
| 角色 | 系統通知 | 音效 | 機器 | 理由 |
|---|---|---|---|---|
| 主力開發者(本機 3–5 個 Agent) | 開 | 開 | 本機 | 即時回應 Needs You |
| 平行跑 10 個以上 Agent | 開 | 關 | 本機 | 避免音效疲勞,改看 Dashboard |
| 透過 SSH 跑長任務 | 開 | 開 | 只開 SSH 目標 | 本機雜訊靜音 |
| 會議中 | 關 | 關 | 全部 | 改用手機推播或事後看 Inbox |
📌 查證狀態:教學示例(非官方)|來源:Notifications
範例:以 CLI 標記未讀(適合放在腳本或 Agent 規則)
# Agent 完成需要人工 Review 的里程碑時,標記目前 Worktree 為未讀
orca worktree set --worktree active --unread --json
# 已處理後標為已讀
orca worktree set --worktree active --read --json✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 完成通知 | 在背景 Worktree 讓 Agent 完成任務 | 收到系統通知與音效,Worktree 出現 chip | 檢查作業系統通知權限與 Settings → Notifications |
| Inbox 跳轉 | 點標頭鈴鐺中的項目 | 跳到對應窗格 | 確認項目仍未讀 |
| Structured chat | 完成一回合 chat | 只出現未讀標記,無系統通知 | 屬預期 |
| 機器靜音 | 在 Machines 關閉本機 | 本機 Agent 完成時不通知 | 確認設定已儲存 |
| 自訂音效 | 選一個 WAV 檔並調低音量 | 下次通知播放該音效 | 確認檔案格式在支援清單 |
| CLI 未讀 | 執行 orca worktree set --worktree active --unread --json | 側欄出現未讀標記 | 檢查 --worktree 選擇器 |
10.5 Agents Feed 活動摘要
📌 查證狀態:官方文件明確記載|來源:Agents feed
概念說明
Agents feed 是「發生了什麼事」的時間軸,從側欄的 Agents 入口開啟,預設啟用並有未讀 badge(設定中位於 Experimental 的 Activity Page)。
| 內容 | 說明 |
|---|---|
| 回合完成 | Agent 進入 idle 或 blocked |
| 新 Worktree | 建立新工作區 |
| 長時間阻擋 | 等你回應很久的 Agent |
| 回應預覽 | Agent 最後回覆的摘要 |
| 分組 | 依狀態分組,執行中的 Agent 置頂 |
與其他機制的分工
| 機制 | 適合回答的問題 |
|---|---|
| Dashboard(10.1) | 現在每個 Agent 在什麼狀態? |
| Inbox 與系統通知(10.4) | 現在有什麼需要我? |
| Agents feed(10.5) | 過去這段時間發生了什麼? |
| Session History(9.5) | 過去某段對話在哪?如何續接? |
Agents feed 是補充,不取代鈴鐺與系統通知。
操作步驟
- 點側欄 Agents 開啟 feed。
- 按
Cmd+F(macOS)或Ctrl+F(Windows/Linux)篩選;若焦點在終端機,該快捷鍵仍由終端機使用。 - 右鍵列可執行動作;按住
Cmd或Ctrl點擊可多選。 - 每天開工時從 feed 回顧前一天未處理的 blocked 項目。
範例 Prompt:請 Agent 依 feed 整理每日站會摘要
以下是我從 Orca Agents feed 複製的昨天活動(貼上內容)。請整理成站會摘要:
1. 已完成:每項一行,附 Worktree 名稱。
2. 卡住:列出 blocked 原因與建議下一步。
3. 今天優先處理的 3 件事。
只根據貼上的內容,不要推測未出現的工作。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 「已完成」每項都能在 feed 或對應 Worktree 找到
- 「卡住」的原因與 Agent 實際回覆一致,沒有被改寫成較樂觀的說法
- 貼上的內容沒有含金鑰或客戶資料
- 優先順序符合團隊目前的 Sprint 目標
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Feed 開啟 | 點側欄 Agents | 顯示活動時間軸 | 檢查 Settings → Experimental 的 Activity Page |
| 回合完成出現 | 讓一個 Agent 完成任務 | feed 新增一筆並顯示預覽 | 確認 Agent 從選單啟動 |
| 篩選 | 在 feed 按 Ctrl+F 輸入 Worktree 名稱 | 只顯示相關項目 | 先點 feed 區域讓焦點離開終端機 |
| 多選 | Ctrl+點擊兩列後右鍵 | 動作套用到兩列 | 確認版本支援 |
10.6 本章 Review 與驗證清單
- 能說出六種狀態符號的意義,並知道只有從選單啟動的 Agent 才有狀態
- 已啟用 Agent Dashboard 並綁定 Toggle Agent Dashboard 快捷鍵
- 已在 Settings → Agents 調整一個 Agent 的啟動參數,並驗證 Reset
- 已使用 Restart chip 在相同 cwd 重新啟動 Agent
- 已以
orca terminal wait --for tui-idle等待一個 Agent 完成 - 已啟用 Agent hibernation,觀察到休眠與自動續接
- 能列出不會休眠的 Agent 與阻止休眠的條件
- 已依角色設定通知類別、音效與 Machines
- 能說明 Structured chat 與終端機 Agent 的通知差異
- 能說明 Dashboard、Inbox、Agents feed、Session History 各自回答的問題
第十一章 Parallel Worktrees 平行代理實戰
本章把第二章介紹的 Worktree 模型落實到「一次指揮多個 Agent」的日常作業:如何分派、如何比較、如何在大量 Worktree 間移動、如何清理,以及最關鍵的——如何把多份 AI 產出安全地合併回主線。全章以 Orca v1.4.244 為準。
📌 查證狀態:官方文件明確記載(Worktree 模型、同題競賽與十個 Worktree 切換流程)|來源:Worktrees、Race three agents on the same task、Jump between 10 worktrees
11.1 平行分派的運作原理
概念說明
Orca 是「Worktree 原生」的 ADE:每一個任務都對應一個真實的 git worktree——同一個 .git 物件庫、各自獨立的工作目錄、各自的分支、各自的 Agent 終端機。平行代理之所以「安全」,不是因為 Agent 很守規矩,而是因為檔案系統層級就隔離了:Agent A 寫的 src/api/user.ts 與 Agent B 寫的 src/api/user.ts 是磁碟上兩個不同的檔案。
| 名詞 | 意義 | 在 Orca 中的位置 |
|---|---|---|
| Base ref | Repository 的基準分支,通常是 origin/main | Settings → Git 的 Default base ref resolver |
| Start-from ref | 新 Worktree 從哪裡分出 | 建立對話框的 Branch from 控制項 |
| Worktree 分支 | 每個 Worktree 獨佔的分支 | 預設由 Workspace 名稱或連結的 Issue/PR 推導 |
| Shared paths | 不進版控、但每個 Worktree 都需要的目錄或檔案 | Settings → Repository、orca.yaml、.worktreeinclude |
Start-from ref 有四種選擇:Repository 的 base ref(最快)、另一個本機分支(適合疊在審查中的 PR 上繼續做)、特定 commit SHA、既有的遠端分支(Orca 會先 fetch 再 checkout)。
建立 Worktree 是背景作業:送出建立對話框後視窗立即關閉,git fetch 與 git worktree add 在背景執行,側邊欄會出現進度列;你可以同時切去其他 Worktree,建立失敗時面板會提供 Retry。
flowchart LR
REQ["需求或 Bug 單"] --> SPLIT{"分派方式"}
SPLIT -->|"同題競賽"| R1["Worktree fix-bug(Claude Code)"]
SPLIT -->|"同題競賽"| R2["Worktree fix-bug-2(Codex)"]
SPLIT -->|"同題競賽"| R3["Worktree fix-bug-3(Cursor CLI)"]
SPLIT -->|"分工協作"| D1["Worktree feat-api(後端)"]
SPLIT -->|"分工協作"| D2["Worktree feat-ui(前端)"]
R1 --> CMP["人工比較 Diff 與測試證據"]
R2 --> CMP
R3 --> CMP
CMP --> WIN["保留勝者,刪除其餘"]
D1 --> INT["依序整合與衝突處理"]
D2 --> INT
WIN --> PR["Hosted Review(PR 或 MR)"]
INT --> PR
PR --> MAIN["main"]如何閱讀此圖:左側同一份需求有兩種分派法。上半部「同題競賽」把相同 Prompt 交給不同 Agent,最後只留一份;下半部「分工協作」把需求拆成互不重疊的子任務,最後要全部整合。兩條路徑都必須經過「人工比較或整合」這一關,才會進入 Hosted Review。
操作步驟(UI)
- 點側邊欄上方的 Create(v1.4.199 起「New workspace」與「Add project」合併為單一按鈕)。
- 在 Project 欄位輸入關鍵字篩選並按 Enter 選定專案;Run on 選擇本機、SSH 主機或 Remote Orca Server。
- 輸入 Workspace 名稱,例如
fix-login-timeout;需要連結工作項目時,可直接在名稱欄貼上 GitHub PR、Linear、GitLab MR 或 Jira 的網址。 - 在 Branch from 選擇 start-from ref;需要自訂分支名稱時展開 Advanced,在 Branch name 欄位輸入(例:
feature/login-timeout)。 - 在 Agent 選擇器挑選要啟動的 Agent(或 Blank Terminal),可勾 Set as default 作為之後的預設值。
- 送出後觀察側邊欄進度列,完成時會自動開啟你選擇的起始畫面。
範例:與 Orca 行為等價的 git 指令
# Orca 在背景做的事,大致等同於:
git fetch origin
git worktree add -b feature/login-timeout ../myapp-wt/login-timeout origin/main
# 檢視所有 worktree
git worktree list範例:用 Orca CLI 建立並直接派工
orca worktree create --name login-timeout \
--branch feature/login-timeout \
--agent claude \
--prompt "重現 issue #412 的登入逾時問題,先寫失敗測試再修正,只能修改 src/auth/ 與 tests/auth/" \
--json--branch 是 v1.4.244 新增的旗標,用來指定 Git 分支名稱而不套用設定的前綴;若名稱衝突,Orca 可能自動加上數字尾碼,--name 仍是 Workspace 顯示名稱。
範例:讓每個新 Worktree 都拿得到依賴與本機設定
# orca.yaml(repo 根目錄,進版控)
worktree:
sharedDirectories:
- node_modules
- .cache# .worktreeinclude(repo 根目錄)—— 逐一「複製」到每個新 worktree
.env.local
.vscode/settings.jsonsharedDirectories 是「共享」(symlink),適合可重建的大型目錄;.worktreeinclude 是「複製」,適合每個 Worktree 要各自擁有一份的檔案。兩者都只處理已被 gitignore 的路徑,且 .worktreeinclude 目前只支援字面路徑,不支援 glob 與否定規則。
⚠️ 注意事項:.worktreeinclude 會把 .env 類檔案複製到每個 Worktree,等於把機敏設定擴散成 N 份。企業環境應改用開發專用、低權限的憑證,正式環境金鑰絕不放進會被複製的檔案(治理細節見第二十八章)。
✅ 驗證方式
在主 checkout 執行:
git worktree list git branch --list "feature/*"預期輸出(示意):
/src/myapp a1b2c3d [main] /src/myapp-wt/login-timeout a1b2c3d [feature/login-timeout]判讀:新路徑存在且分支名稱正確即成功;若側邊欄顯示錯誤,先按 Retry,仍失敗再看第二十九章的「Worktree creation fails」排錯。
進入新 Worktree 執行
ls -la node_modules .env.local,確認共享目錄為 symlink、.env.local為一般檔案。
11.2 同題競賽模式
概念說明
同題競賽(Race)是 Orca 官方最推崇的用法:同一個 start-from ref、同一份 Prompt、三個不同 Agent、三條分支,最後挑一個勝者。原理很樸素——不同 Agent 犯的錯不一樣;三者一致的地方大概是對的,三者分歧的地方就是問題的困難點。平行跑三次通常比「失敗再重試」的序列迭代便宜。
| 適合競賽 | 不適合競賽 |
|---|---|
| 邊界清楚的 Bug 修正 | 牽動多模組的大型重構 |
| 演算法或效能熱點的替代實作 | 需要大量人工澄清的模糊需求 |
| 新元件的第一版 UI | 會呼叫付費外部 API 或寫入共用資料庫的任務 |
| 測試補強(比較誰抓到更多邊界) | 結果難以量化比較的文件撰寫 |
操作步驟
- 從同一個 start-from ref 建立三個 Worktree,命名
fix-bug、fix-bug-2、fix-bug-3(可在 Cmd-J 輸入新名稱後選 Create worktree 列,加快建立速度)。 - 每個 Worktree 各啟動一個不同 Agent,例如 Claude Code、Codex、Cursor CLI。
- 把完全相同的 Prompt 貼進三個 Agent。
- 把分頁拖到窗格邊緣分割畫面,同時監看三個 Agent(分割操作見第二章)。
- 三者完成後逐一審查 Diff(第十四章),對勝者使用 Annotate AI Diff 再收斂一輪。
- 從勝者 Worktree commit、push、開 PR。
- 刪除另外兩個 Worktree——一個動作同時移除目錄與分支。
範例 Prompt
任務:修正 issue #412「登入 30 秒後逾時」。
限制:
1. 只能修改 src/auth/** 與 tests/auth/**,不得修改其他目錄。
2. 先新增一個能重現問題的失敗測試,再修正程式。
3. 不得新增相依套件,不得修改 package.json 與 lock 檔。
完成後請回報:
- 根因(一段話)
- 修改檔案清單
- 實際執行的測試指令與完整輸出(貼上,不要摘要)範例:用 CLI 一次發動三方競賽
PROMPT='修正 issue #412 登入逾時。只能改 src/auth/ 與 tests/auth/;先寫失敗測試;回報根因、檔案清單與測試輸出。'
orca worktree create --name fix-bug --agent claude --prompt "$PROMPT" --json
orca worktree create --name fix-bug-2 --agent codex --prompt "$PROMPT" --json
orca worktree create --name fix-bug-3 --agent cursor --prompt "$PROMPT" --json--agent 的實際識別名稱以 orca worktree create --help 與 Settings → Agents 中偵測到的 Agent 為準。
範例:從主 checkout 客觀比較三份產出
for b in fix-bug fix-bug-2 fix-bug-3; do
echo "== $b"
git diff --stat main...$b
done
# 檢查是否有人越界修改禁止範圍
git diff --name-only main...fix-bug-2 | grep -v -E '^(src/auth/|tests/auth/)'評分表範例(教學示例)
| 準則 | 權重 | fix-bug | fix-bug-2 | fix-bug-3 |
|---|---|---|---|---|
| 失敗測試能重現問題 | 30% | 有 | 有 | 無 |
| 修正後全部測試通過(附輸出) | 30% | 是 | 是 | 是 |
| 變更行數最小且未越界 | 20% | +42 −8 | +120 −35 | +30 −5 |
| 根因說明與程式碼一致 | 20% | 一致 | 部分 | 不一致 |
| 結論 | — | 勝者 | 參考其測試案例 | 淘汰 |
🧑⚖️ 人工 Review 要點(三份產出回來後,審查者應逐項確認)
- 三份產出的根因說明是否一致;不一致時,先釐清誰對,而不是挑「看起來最乾淨」的
- 每份測試輸出都是實際貼上的終端機內容,而非「測試已通過」的口頭宣稱
-
git diff --name-only沒有越界檔案 - 落選方案中若有更好的測試案例,是否以
git cherry-pick或手動移植到勝者分支 - 勝者沒有偷偷新增相依套件或修改 CI 設定
⚠️ 注意事項:三方競賽的 Token 成本約為單一 Agent 的三倍,企業應在第八章的用量治理框架內規定「哪些等級的任務才允許競賽」。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 三個 Worktree 起點相同 | git merge-base main fix-bug 與另兩條分支比較 | 三個 SHA 完全一致 | 刪除重建,確認 Branch from 選擇同一 ref |
| Prompt 一致 | 檢視三個 Agent 分頁的第一則訊息 | 文字完全相同 | 重新送出統一 Prompt |
| 落選者已清理 | git worktree list 與 git branch --list "fix-bug*" | 只剩勝者 | 見 11.5 的 Preserved branches |
11.3 分工協作模式
概念說明
分工協作是把一個需求拆成多個檔案範圍不重疊的子任務,各自交給一個 Agent,最後全部整合。它的成敗幾乎完全取決於拆分品質:拆得好,合併幾乎零衝突;拆得差,Agent 越多、衝突越多。
拆分三原則:
- 先定契約,再平行:先由一個 Worktree(或人)產出 API 規格、型別定義、資料表 Schema,合併進主線後,其他 Worktree 再從新的主線分出。
- 按目錄切,不按功能切:
src/api/**、src/web/**、tests/e2e/**各歸一人;共用檔案(型別、路由表、i18n 字典)指定唯一擁有者。 - 用父子關係表達從屬:在建立對話框 Advanced → Parent workspace 指定父 Workspace,或 CLI 加
--parent-worktree active。父子關係只影響側邊欄巢狀顯示,不改變 Git 歷史。
sequenceDiagram
participant L as 技術主管
participant C as 契約 Worktree
participant B as 後端 Worktree
participant F as 前端 Worktree
participant T as 測試 Worktree
L->>C: 產出 OpenAPI 與共用型別
C-->>L: Diff 審查通過後合併到 main
par 從新的 main 平行分出
L->>B: 只改 src/api/
L->>F: 只改 src/web/
L->>T: 只改 tests/e2e/
end
B-->>L: Checkpoint 回報 in-review
F-->>L: Checkpoint 回報 in-review
T-->>L: Checkpoint 回報 in-review
L->>L: 依序整合(見 11.6)如何閱讀此圖:時間由上往下。第一段是「契約先行」,必須先合併;中段 par 區塊表示三個 Worktree 同時進行,彼此不溝通;最後由技術主管依 11.6 的順序整合。Agent 之間不直接交換檔案,而是透過主線與 Checkpoint 留言協調。
操作步驟
- 建立
contractWorktree,請 Agent 產出openapi.yaml與src/shared/types.ts,人工審查後合併。 - 在主 checkout 執行
git pull,讓 base ref 包含契約。 - 依序建立
feat-api、feat-web、feat-e2e三個 Worktree,Branch from 選更新後的origin/main,Parent workspace 選一個代表此需求的 Workspace(例如export-report)。 - 在每個 Prompt 中寫明「允許修改」與「禁止修改」路徑。
- 要求 Agent 在關鍵節點更新 Worktree Checkpoint,讓你在卡片上就能看到進度。
範例 Prompt(後端分工)
你負責「使用者資料匯出」的後端部分。
允許修改:src/api/export/**、tests/api/export/**
禁止修改:src/shared/types.ts(契約已凍結)、src/web/**、任何 CI 設定
依據:openapi.yaml 中的 POST /exports 與 GET /exports/{id}
完成條件:
1. 單元測試覆蓋成功、權限不足、資料過大三種情境
2. 執行 pnpm test -- tests/api/export 並貼上完整輸出
3. 每完成一個里程碑,執行:
orca worktree set --worktree active --comment "<做了什麼;下一步>" --workspace-status in-progress --json範例:Agent 回報 Checkpoint
orca worktree set --worktree active \
--comment "POST /exports 完成,3 個情境測試通過;下一步實作 GET /exports/{id}" \
--workspace-status in-progress --json範例:合併前偵測檔案重疊
for b in feat-api feat-web feat-e2e; do
git diff --name-only main...$b | sed "s|^|$b: |"
done | sort -k2 | awk '{print $2}' | uniq -d輸出為空代表三條分支沒有修改同一個檔案;若列出檔名,代表拆分失守,要在合併前決定該檔由誰擁有。
🧑⚖️ 人工 Review 要點
- 每條分支的
git diff --name-only都只落在其「允許修改」路徑 - 沒有任何分支修改已凍結的契約檔;若需要改契約,必須回到契約 Worktree 重新走一次
- Checkpoint 留言反映的是事實(可在終端機輸出找到對應證據)
- 測試 Worktree 的案例是依契約撰寫,而不是依某一方的實作反推
❌ 常見錯誤:讓三個 Agent 同時「順手」修改 src/shared/types.ts。結果是三份互相衝突的型別定義,合併成本超過平行省下的時間。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 父子結構正確 | 側邊欄父 Workspace 出現 N children 晶片 | 顯示 3 children | 在 Edit Worktree Details 調整 Parent |
| 範圍未越界 | 上方重疊偵測腳本 | 無輸出 | 依 11.6 處理或退回 Agent 修正 |
| Checkpoint 有更新 | orca worktree show --worktree name:feat-api --json | comment 為最新進度 | 在 Prompt 中再次要求回報 |
11.4 在十個 Worktree 間切換
概念說明
Worktree 一多,瓶頸就從「Agent 寫程式」變成「人找得到該處理的 Worktree」。Orca 針對十個以上 Worktree 的規模設計了三件工具:Jump Palette、Agent 狀態點、Restart chip,再加上通知鈴鐺。
| 工具 | 快捷鍵或位置 | 用途 |
|---|---|---|
| Worktree Jump Palette | Cmd-J(或側邊欄頂端 Search 按鈕) | 跨 Worktree 與分頁搜尋跳轉 |
| 在分割中開啟 | Jump Palette 內 Shift-Enter | 不取代目前窗格,另開分割 |
| 主機/專案篩選 | Jump Palette 內 Tab | 在大量結果中縮小範圍 |
| 最近的 Chat 與 Terminal | 空白查詢時的前六列,Cmd-1~Cmd-6(Windows/Linux 為 Ctrl-1~Ctrl-6) | 直接跳到最需要你的 Agent |
| Agent 狀態點 | 側邊欄 | 綠點:工作中;黃色或問號:等待你輸入 |
| Restart chip | Worktree 內 | 一鍵重新啟動已結束的 Agent(筆電睡眠後批次恢復很實用) |
| 通知鈴鐺 | 狀態列 | 逐一消化「Agent 已完成」佇列,點擊即跳到該 Worktree |
📌 查證狀態:官方文件明確記載|來源:Quick Open & Jump Palette;Windows/Linux 上
Cmd-J對應的實際組合鍵請以 Settings → Shortcuts 顯示為準(依官方說明延伸(教學推論))
操作步驟:早上開工的巡檢流程
- 按
Cmd-J,在空白查詢下看 Recent Chats & Terminals——排序是「需要你」優先、其次「已完成」、最後「閒置」。 - 先處理問號或黃點的 Worktree(Agent 在等你核准或回答)。
- 再從通知鈴鐺逐一點開「已完成」項目,進入審查。
- 對因睡眠而結束的 Agent,按 Worktree 內的 Restart chip 恢復。
- 用側邊欄篩選選單隱藏 Sleeping workspaces、Automation-created workspaces,讓清單只剩今天要處理的項目。
- 長期任務按右鍵 Pin,固定在專案頂端。
範例:可被 Jump Palette 快速命中的命名規範
<類型>-<工單號>-<簡述>[-<Agent 代號>]
fix-412-login-timeout-cc ← Claude Code 版本
fix-412-login-timeout-cx ← Codex 版本
feat-ENG-88-export-api
spike-perf-report-query在 Jump Palette 輸入 412 就能同時列出同一張工單的所有競賽 Worktree;輸入 #123 或 !77 也能以已快取的 GitHub PR 或 GitLab MR 編號找到 Worktree。Workspace 名稱可使用 Slack 風格的 emoji shortcode(例::rocket:),Orca 衍生 Git 分支名稱時會改寫為可讀文字。
💡 小技巧:Jump Palette 找不到時會出現 Create worktree 列,以輸入文字為名稱建立新 Worktree;但若已有符合結果,Enter 仍會優先跳轉,不會誤建。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 命名可被搜尋 | Cmd-J 輸入工單號 | 列出該工單全部 Worktree | 用滑鼠雙擊卡片標題重新命名 |
| 優先順序正確 | 空白查詢檢視前六列 | 問號圖示的項目排在最前 | 確認 Settings → Agents 的 Agent status hooks 已開啟 |
| 篩選可還原 | 篩選控制項的計數與 Clear | 計數歸零、清單完整 | 注意輸入查詢仍可找到被篩選隱藏的 Worktree |
11.5 Resource Manager 與清理
概念說明
每個 Worktree 都會維持檔案監看器、終端機行程、瀏覽器分頁與依賴目錄。官方的衛生建議很直接:合併後就積極刪除,留著幾十個已合併的 Worktree 只會拖慢 Jump Palette 與整台機器。
| 動作 | 位置 | 效果 |
|---|---|---|
| Sleep | Worktree 右鍵選單 | 關閉該 Worktree 的終端機與瀏覽器面板,保留檔案 |
| Sleep with Descendants (N) | 有子 Workspace 時的右鍵選單 | 連同已驗證的子 Workspace 一起 Sleep |
| Archive | 右鍵選單 | 封存,不出現在一般清單 |
| Delete | 右鍵選單或 Cmd-Shift-Backspace(Windows/Linux:Ctrl-Shift-Backspace) | 刪除目錄與分支(會確認) |
| Delete with Descendants… | 有子 Workspace 時 | 背景執行串聯刪除 |
| Resource Manager | 狀態列(Settings → Appearance 的狀態列開關) | 檢視 CPU、記憶體、Session、磁碟掃描;v1.4.238 起新增本機終端機的 PTYs 檢視 |
| Clean up workspaces | Resource Manager 內 | 跨本機、主 checkout、資料夾 Workspace 與離線 SSH 主機,依狀態、活動、大小、Git 狀態排序後批次清理 |
刪除時若 git 認為某個本機分支「可能有未合併的 commit」而拒絕刪除,Orca 會保留該分支,並跳出 Review N Branches 的提示,讓你逐一決定要強制刪除哪些。Workspace 資料夾本身仍會被刪除,不會還原。
操作步驟:每週清理
- 開啟狀態列 Resource Manager,先看哪些 Worktree 占用最多記憶體與磁碟。
- 進入 Clean up workspaces,以「最近活動」排序,並對照每列的 Git 狀態與連結的 Review(PR 已 merged 才刪)。
- 勾選要刪的 Workspace,送出。v1.4.185 之後清理對話框不會預先勾選任何項目,必須自己選。
- 若出現 Review N Branches,展開確認每條分支的未合併 commit,再決定是否強制刪除。
- 對暫時不用但還要保留的 Worktree 改用 Sleep。
範例:刪除前用 git 確認分支已合併
# 列出已合併進 main 的本機分支(可安全刪除)
git branch --merged main
# 列出尚未合併的分支(刪除前務必確認)
git branch --no-merged main
# 檢視某分支有哪些 commit 不在 main
git log --oneline main..fix-bug-2範例:用 CLI 移除 Worktree
orca worktree list --json
orca worktree rm --worktree name:fix-bug-2 --json
# 確認不需要保留時才加 --force
orca worktree rm --worktree name:fix-bug-3 --force --json若你直接用 git worktree remove 刪除,Orca 會在下次重新整理該 Repository 時自動清理自己的狀態。
⚠️ 注意事項:刪除對話框的 Force Delete 是分割按鈕,箭頭選單中的 Always force delete 會記住選擇並套用到之後所有刪除。企業環境建議不要啟用,以保留 git 對未合併 commit 的保護。
✅ 驗證方式
清理後執行:
git worktree list git worktree prune --dry-run git branch --no-merged main預期輸出(示意):
/src/myapp a1b2c3d [main] /src/myapp-wt/feat-export d4e5f6a [feat-export]判讀:
git worktree prune --dry-run無輸出代表沒有殘留的失效紀錄;--no-merged只剩你刻意保留的分支。Resource Manager 的記憶體數字應明顯下降。
11.6 合併策略與衝突處理
概念說明
平行化的價值是「縮短產出候選方案的時間」,不是「全自動合併」。合併永遠是人的決策點,也是最容易把 AI 的錯誤帶進主線的時刻。依情境選擇策略:
| 策略 | 適用模式 | 做法 | 風險 |
|---|---|---|---|
| 選勝者 | 同題競賽 | 只從勝者分支開 PR,其餘刪除 | 落選方案中好的測試被一併丟掉 |
| 摘取(cherry-pick) | 競賽後的補強 | 把落選分支中特定 commit 移植到勝者 | 被摘取的 commit 依賴其分支的其他變更 |
| 整合分支 | 分工協作 | 建 integration/<需求>,依相依順序合併各分支,跑完整測試後再開 PR | 整合分支本身也需審查 |
| 各自 PR 依序合併 | 分工協作且範圍完全不重疊 | 每條分支各開 PR,依契約→後端→前端→測試順序合併 | 後合併者需 rebase |
| Stacked PRs | 後一層依賴前一層 | GitHub 上以 Stack this PR above #N 建立堆疊(見第十五章) | 僅限 GitHub |
flowchart TB
START["所有 Worktree 回報 in-review"] --> OVL{"檔案範圍是否重疊"}
OVL -->|"否"| SEQ["依相依順序各自開 PR"]
OVL -->|"是"| INTB["建立 integration 分支"]
INTB --> M1["合併第一條分支並跑測試"]
M1 --> M2["合併下一條分支"]
M2 --> CF{"是否衝突"}
CF -->|"否"| TEST["完整測試"]
CF -->|"是"| RES["人工或 Resolve with AI 解衝突"]
RES --> RV["人工審查解衝突的 Diff"]
RV --> TEST
SEQ --> TEST
TEST --> PR["Hosted Review"]如何閱讀此圖:先判斷是否重疊;不重疊走左側的簡單路徑。重疊時一律建整合分支,一次只合併一條,每次合併後都測試;發生衝突時,無論由人或 AI 解決,解衝突產生的 Diff 都要再被人審查一次,才能進入完整測試。
Orca 內的衝突處理工具
- Diff Viewer 內建三方合併(three-way)檢視與行內解衝突 UI。
- 當 merge、rebase、cherry-pick 或 revert 停在衝突狀態時,Source Control 面板會在 Review conflicts 旁顯示 Resolve with AI(v1.4.238 新增;即使檔案衝突已手動解完、操作仍暫停時也可使用)。
- 不想繼續時,Source Control 提供 Abort merge 或 Abort rebase。
- Resolve with AI 背後的 Agent 與 Prompt 範本可在 Settings → Git & Source Control → Action recipes 調整(第十四章)。
操作步驟:整合分支流程
在主 checkout 建立整合分支:
git switch -c integration/export-report origin/main依相依順序合併,每次合併後跑測試:
git merge --no-ff feat-api -m "merge: feat-api into integration/export-report" pnpm test git merge --no-ff feat-web -m "merge: feat-web into integration/export-report"若發生衝突,在 Orca 中開啟該 Worktree 的 Source Control,點 Review conflicts 檢視三方合併;或點 Resolve with AI。
審查解衝突結果(見下方工作範例),確認後
git add並完成合併。全部合併後跑完整測試,再從整合分支開 PR。
工作範例:兩個 Agent 都改了同一個函式
feat-api 的 Agent 為匯出功能新增權限檢查;feat-web 的 Agent 為了前端顯示,在同一個函式加了欄位。合併時出現衝突:
export function toExportRow(user: User): ExportRow {
<<<<<<< HEAD
- return { id: user.id, email: user.email };
+ assertCanExport(user);
+ return { id: user.id, email: maskEmail(user.email) };
=======
- return { id: user.id, email: user.email };
+ return { id: user.id, email: user.email, displayName: user.name };
>>>>>>> feat-web
}❌ 不良的解衝突結果(AI 常見:選了「看起來比較完整」的一邊)
export function toExportRow(user: User): ExportRow {
- return { id: user.id, email: user.email };
+ return { id: user.id, email: user.email, displayName: user.name };
}問題:權限檢查 assertCanExport 與 Email 遮罩 maskEmail 被靜默丟掉,測試若沒覆蓋權限情境,CI 依然會是綠的。
✅ 正確的解衝突結果(兩邊意圖都保留)
export function toExportRow(user: User): ExportRow {
- return { id: user.id, email: user.email };
+ assertCanExport(user);
+ return {
+ id: user.id,
+ email: maskEmail(user.email),
+ displayName: user.name,
+ };
}範例:交給 Resolve with AI 時附加的要求(可寫入 Action recipe 範本)
解衝突時必須保留雙方的意圖,不可只選一邊。
對每個衝突區塊,列出:
1. HEAD 端的意圖(一句話)
2. 傳入分支的意圖(一句話)
3. 合併後如何同時滿足兩者
不得刪除任何安全相關呼叫(權限檢查、遮罩、輸入驗證)。
解完後執行 pnpm test 並貼上完整輸出。🧑⚖️ 人工 Review 要點(解衝突的 Diff 必看)
- 每個衝突區塊,雙方新增的行是否都還在(或有明確理由被移除)
- 安全相關呼叫(權限、遮罩、驗證、稽核記錄)沒有消失:
git diff ORIG_HEAD -- src/ | grep -E "^-.*(assert|mask|validate|audit)"應無輸出 - 沒有殘留衝突標記:
git diff --check無輸出、grep -rn "<<<<<<<" src/無結果 - 合併後的測試是實際執行並通過,且至少有一個測試覆蓋到衝突區塊
- 若使用 Resolve with AI,AI 有說明每個區塊的取捨理由
範例:整合後的 commit message
merge: integrate export-report (api + web)
- feat-api: POST/GET /exports with permission check and email masking
- feat-web: export dialog with displayName column
- conflict in toExportRow resolved by keeping both permission check
and displayName; covered by tests/api/export/to-export-row.test.ts
Refs: ENG-88✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 無衝突標記殘留 | git diff --check 與 grep -rn "<<<<<<<" src/ | 皆無輸出 | 回到衝突檔案修正 |
| 每條分支都已納入 | git branch --merged integration/export-report | 列出所有 feat 分支 | 補合併遺漏分支 |
| 安全呼叫未遺失 | 比對合併前後 grep -rn "assertCanExport" src/ 數量 | 數量不減少 | 退回重解衝突 |
| 測試通過 | pnpm test 完整輸出 | 全數通過 | 不得開 PR |
11.7 本章 Review 與驗證清單
- 能說明 base ref、start-from ref 與 Worktree 分支三者的關係
- 已用 UI 與
orca worktree create各建立過一次 Worktree,並以git worktree list確認 - 已設定
orca.yaml的sharedDirectories或.worktreeinclude,並理解「共享」與「複製」的差異與資安風險 - 已完成一次三方同題競賽,並用評分表與
git diff --stat選出勝者 - 已用「契約先行」完成一次分工協作,且重疊偵測腳本無輸出
- 能用
Cmd-J、狀態點、Restart chip 與通知鈴鐺在十個以上 Worktree 間巡檢 - 已用 Resource Manager → Clean up workspaces 完成一次清理,並處理過 Review N Branches
- 已在整合分支上解過一次衝突,並依 🧑⚖️ 清單審查解衝突結果
- 團隊已決定是否禁止 Always force delete,並寫入規範
第十二章 終端機與編輯器
Orca 刻意定位為「編輯器優先、而非 IDE 優先」:它提供與 VS Code 同源的終端機(xterm.js)與編輯器(Monaco),但不打算取代你的型別檢查器、Linter 或除錯器——那些請在終端機窗格中執行。本章說明在 Agent 工作流中最常用的終端機與編輯能力,以及企業導入時要注意的設定。
📌 查證狀態:官方文件明確記載|來源:Terminal、Monaco editor & autosave、File explorer、Rich markdown editor、Viewers
12.1 Terminal 窗格與分頁
概念說明
在 Orca 中,終端機就是一種分頁(Tab),可以和編輯器、瀏覽器、Diff 分頁放在同一個窗格樹中。Agent 終端機分頁會顯示 Agent 身分與即時狀態:工作中、等待輸入、已完成、已完成但未讀。Claude 與 Codex 的分頁標題還可能顯示對話名稱(手動改名優先)。
| 功能 | 操作 | 典型用途 |
|---|---|---|
| 新終端機分頁 | Cmd-T(焦點在終端機時) | 在目前 Worktree 開 shell |
| 向右分割 | Cmd-\ | Agent 在左、測試輸出在右 |
| 向下分割 | Cmd-Shift-\ | 上方 dev server、下方 log |
| 捲動緩衝區搜尋 | Cmd-F/Ctrl-F | 找 Agent 先前輸出的錯誤訊息,支援大小寫、Regex |
| Floating terminal | Cmd+Option+A(macOS)/Ctrl+Alt+A(Windows/Linux) | 不屬於任何 Worktree 的全域 shell,也可在此啟動 orchestration |
| Copy Context | 終端機右鍵 | 複製一段有界的輸出記錄,貼到其他工具 |
| Copy Session ID | 分頁右鍵 | 給腳本、支援請求使用 |
| Reset Terminal | 終端機右鍵 | 程式當掉後鍵盤或滑鼠模式卡住時清除,不重啟 shell |
預設 shell:在 Settings → Terminal 設定新本機分頁的預設 shell;留空則使用系統預設。Windows 可選 PowerShell、Command Prompt,以及(wsl.exe --status 成功時)WSL。分頁列 + 下拉選單也可一次性開啟其他 shell,不改預設。Orca 會在受管理的 WSL 終端機中自動提供 Orca CLI。
連結動作:直接點擊終端機中的網址、檔案路徑或 Workspace 連結,會跳出小型動作選單(Orca Browser、System Browser、Copy link);Cmd-click/Ctrl-click 則直接開啟。行為可在 Settings → Browser → Terminal URL clicks 與 Show terminal link actions 調整。
操作步驟:建立「Agent+測試」雙窗格
- 在 Worktree 開啟 Agent 分頁。
- 按
Cmd-\向右分割出一個 shell。 - 在右側執行測試監看,例如
pnpm test --watch。 - Agent 修改程式時,右側即時顯示測試結果;需要回頭找錯誤時,在右側按
Cmd-F搜尋FAIL。
範例:用 CLI 建立同樣的版面
orca terminal create --worktree active --title "tests" --command "pnpm test --watch" --json
orca terminal list --worktree active --json
orca terminal split --terminal <handle> --direction horizontal --command "pnpm dev" --json範例:讀取 Agent 終端機目前畫面(給腳本或另一個 Agent 用)
orca terminal read --terminal <handle> --screen --json--screen 讀的是目前渲染的畫面;不加則讀累積的輸出串流。終端機 handle 只在當次執行期有效,Orca 重啟後要重新 orca terminal list 取得。
⚠️ 注意事項:Copy Context 會把 Agent 輸出(可能含路徑、內部主機名、甚至 Token)放進剪貼簿。企業環境貼到外部工具前應先檢查內容。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 分割成功 | 按 Cmd-\ | 同分頁出現兩個 shell | 確認焦點在終端機窗格而非編輯器 |
| 預設 shell 正確 | 新開分頁執行 echo $SHELL 或 PowerShell 的 $PSVersionTable | 顯示設定的 shell | 檢查 Settings → Terminal 的 Default shell |
| CLI 可控制終端機 | orca terminal list --worktree active --json | 回傳終端機清單 JSON | 依第十六章確認 CLI 安裝 |
12.2 Agent 啟動指令與 Quick Commands
概念說明
Agent 啟動行為分兩層:每個 Agent 的啟動預設(Settings → Agents,可覆寫執行檔路徑、Command、Arguments 與環境變數,Native Chat 也使用同一組設定),以及 Quick Commands(Settings → Quick Commands,保存常用終端機指令與可重複使用的 Agent Prompt)。
自 v1.4.223 起,macOS 與 Linux 上較長或多行的啟動指令會完整送達 Agent,而不會被截斷或逐行執行;這只對更新後新開的終端機生效。
| 快捷鍵 | 行為 |
|---|---|
Cmd-Alt-T(macOS) | 以預設 Agent 開新 Agent 分頁 |
| Windows/Linux | 預設未綁定,到 Settings → Shortcuts 搜尋「New agent tab」指派 |
| 個別 Agent 的 New agent tab 動作 | 可各自綁定快捷鍵,直接啟動特定 CLI |
Quick Command 欄位:
| 欄位 | 說明 |
|---|---|
| Label | 顯示名稱 |
| Command | 指令本文,或 Claude、Codex 等 launch-time prompt Agent 的 Prompt 預設 |
| Scope | Global(全部 Worktree)或 Project(只在特定 Repository 顯示) |
| Saved on | 多主機環境下指令儲存在哪台 Orca 主機;與「在哪裡執行」無關 |
操作步驟
- 開啟 Settings → Quick Commands,或從 Worktree 分頁列的 Add command 按鈕新增。
- 填入 Label、Command,選擇 Scope。
- 執行方式有二:分頁列的 Quick Commands 分割按鈕(開新終端機分頁並執行),或終端機右鍵選單(插入到目前終端機)。
範例:團隊建議的 Quick Commands(教學示例)
| Label | Command | Scope |
|---|---|---|
| Dev server | pnpm dev | Project |
| Unit tests | pnpm test | Project |
| Lint 與型別檢查 | pnpm lint && pnpm typecheck | Project |
| Git 健檢 | git status -sb && git log --oneline -5 | Global |
| 審查前自檢 Prompt | 見下方 | Global |
請在提交前自我檢查:
1. 執行 git diff --stat,列出所有修改檔案並說明每個檔案為何需要修改。
2. 執行專案測試與 lint,貼上完整輸出。
3. 列出你不確定或刻意沒有處理的地方。
不要 commit,不要 push。🧑⚖️ 人工 Review 要點(Agent 執行上述自檢 Prompt 後)
- 修改檔案清單與
git diff --stat實際結果一致 - 測試與 lint 輸出是完整貼上,且結尾顯示通過
- 「不確定之處」有具體內容,而不是「無」
⚠️ 注意事項:Quick Commands 會同步到行動端 Companion。絕對不要把 Token、密碼寫進 Command 本文;需要時改用環境變數或密鑰管理工具。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Scope 正確 | 切到另一個 Repository 的 Worktree | Project 範圍指令不顯示 | 編輯指令的 Scope |
| 指令可執行 | 點分頁列 Quick Commands 的 Unit tests | 新分頁開啟並執行測試 | 確認 Command 在該 shell 中可執行 |
| Agent 啟動參數生效 | 新開 Agent 分頁,觀察啟動指令列 | 帶有 Settings → Agents 設定的 Arguments | 舊終端機需重開才套用 |
12.3 終端機主題與快捷鍵
概念說明
主題與快捷鍵看似個人偏好,但在多人導入時,統一的快捷鍵與可讀的對比度能大幅降低教育訓練成本。
| 設定 | 位置 | 說明 |
|---|---|---|
| 主題 | Settings → Terminal | 內建熱門主題,可自訂 |
| Ghostty 匯入 | Settings → Terminal → Import from Ghostty | 匯入主題、字型、游標 |
| Warp 主題匯入 | 主題選擇器的 Import themes from Warp 或 Import from YAML | 自動掃描 Warp 主題資料夾(Windows 為 %APPDATA%\warp\Warp\data\themes) |
| 對比度 | Settings → Terminal → Rendering → Color Contrast | Automatic、Off 或 Custom(1 到 21) |
| OSC 52 剪貼簿 | Settings → Terminal → Allow TUI Clipboard Writes (OSC 52) | 預設開啟,讓 tmux、Neovim 等透過 SSH 也能寫入剪貼簿 |
| JIS 鍵盤 | Settings → Terminal → JIS Yen (¥) to Backslash () | macOS 日文鍵盤 |
| 快捷鍵 | Settings → Shortcuts | 舊安裝的自訂值保存在 ~/.orca/keybindings.json |
Orca 宣告支援 kitty keyboard protocol,因此 Shift+Enter、Ctrl+Enter 等帶修飾鍵的按鍵能正確送達 Agent CLI,行為與 Ghostty、WezTerm 一致。
常用快捷鍵總表(macOS;Windows/Linux 以 Ctrl 對應,實際以 Settings → Shortcuts 為準)
| 動作 | 快捷鍵 |
|---|---|
| 新終端機分頁 | Cmd-T |
| 新 Agent 分頁 | Cmd-Alt-T |
| 關閉分頁 | Cmd-W |
| 向右/向下分割 | Cmd-\/Cmd-Shift-\ |
| 下一個/上一個分頁 | Cmd+Shift+]/Cmd+Shift+[ |
| 最近使用的分頁 | Ctrl+Tab |
| Worktree Jump Palette | Cmd-J |
| Floating terminal | Cmd+Option+A |
操作步驟:建立團隊共用快捷鍵基準
- 由一位成員在 Settings → Shortcuts 綁定團隊約定的組合(例如 Windows 上的 New agent tab、Send Review Notes to Agent)。
- 將
~/.orca/keybindings.json納入團隊內部的設定範本庫。 - 新成員導入時複製該檔,重開 Orca。
⚠️ 注意事項:OSC 52 允許終端機中的程式寫入系統剪貼簿。若團隊的資安政策要求遠端主機不得影響本機剪貼簿,應關閉此選項並寫入第六章的標準設定基準。
✅ 驗證方式
在終端機執行下列指令測試 OSC 52:
printf "\033]52;c;$(printf 'orca-osc52-test' | base64)\a"預期結果:在其他應用程式貼上時得到
orca-osc52-test(選項開啟時);關閉後則剪貼簿內容不變。判讀:結果與團隊政策不符時,調整 Settings → Terminal → Allow TUI Clipboard Writes (OSC 52)。
12.4 Monaco 編輯器與自動儲存
概念說明
Orca 的編輯器是 Monaco,檔案在失去焦點與短暫閒置後自動儲存,因此沒有「未儲存」圓點。對 Agent 工作流最重要的是磁碟變更保護:每次儲存前,Orca 會檢查檔案自上次讀寫後是否已在磁碟上被改過(例如 Agent 剛寫入);若是,自動儲存會暫停,並顯示 changed-on-disk 橫幅讓你比較、重新載入、保留自己的修改,或明確覆寫磁碟版本。v1.4.233 起更進一步拒絕覆寫你沒看過的磁碟變更。
| 功能 | 操作 |
|---|---|
| 選取下一個相同字詞 | Cmd-D |
| 檔案內搜尋/Worktree 內搜尋 | Cmd-F/Cmd-Shift-F |
| 跳到定義 | Cmd-Click(視語言支援) |
| Changes view mode | 編輯器分頁切換為 HEAD 對工作目錄的 Diff,n/p 移動 hunk、s stage |
| 自動換行 | Alt+Z,或分頁 ⋯ 選單;預設值在 Settings → General → Editor Word Wrap |
| Minimap | Settings → Appearance(預設關閉) |
| 編輯器字型 | Settings → Appearance → Editor Font Family(留空則與終端機相同) |
同路徑但位於不同主機(本機與 SSH)的檔案,各自擁有獨立的文字與 Undo 歷史,不會互相洩漏。
操作步驟:與 Agent 同時編輯同一檔案時
- 你正在編輯
src/report/query.ts,Agent 同時寫入同一檔案。 - Orca 偵測到磁碟變更,暫停自動儲存並顯示橫幅。
- 先點比較,看 Agent 改了什麼。
- 若 Agent 的修改應保留:選重新載入,再把你的修改重新套上。
- 若你的修改才是正確的:選保留自己的修改,必要時明確覆寫,並在 Agent 對話中告知它檔案已被人工修改。
範例:給 Agent 的協作約定 Prompt
我正在手動編輯 src/report/query.ts 的 buildWhereClause 函式。
在我說「交還」之前,請不要修改這個檔案;需要變更時,先在對話中提出 diff 建議。💡 小技巧:Orca 是編輯器優先,型別檢查與 Lint 請在分割的終端機窗格中以 watch 模式執行,例如 pnpm tsc --noEmit --watch。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 自動儲存運作 | 編輯後切換到其他分頁,執行 git diff | 看得到修改 | 確認檔案不是唯讀 |
| 磁碟衝突保護 | 編輯中在終端機執行 echo "// x" >> 該檔案 | 出現 changed-on-disk 橫幅 | 回報 Orca 版本並查第二十九章 |
| Changes view mode | 在分頁切換 Changes view mode | 顯示 HEAD 對工作目錄的 Diff | 確認檔案有未提交變更 |
12.5 File Explorer 與拖曳檔案
概念說明
每個 Worktree 左側都有即時反映磁碟狀態的檔案總管:Agent 新增或刪除檔案會立即出現;排序為資料夾優先、數字感知的自然排序(9、99、100)。Worktree 若使用 sparse checkout,樹狀結構只顯示 checkout 範圍內的目錄。
| 動作 | 說明 |
|---|---|
| Git 狀態著色 | untracked、modified、staged、ignored 不同顏色 |
| 右鍵動作 | discard、stage、rename、Copy Path、Copy Relative Path(Cmd+Option+Shift+C/Ctrl+Alt+Shift+C) |
| Copy | 把檔案本身放到作業系統剪貼簿(SSH 會先暫存到本機) |
| Reveal in Finder/File Explorer | 在作業系統檔案管理員中顯示 |
| Find in Folder | 以該資料夾為範圍開啟搜尋,或選取後按 Cmd-Shift-F/Ctrl-Shift-F |
| Download/Download Folder | 只對 SSH 或遠端檔案顯示 |
拖放的落點:放在哪裡就作用在哪裡——檔案樹(複製進來)、Markdown 編輯器(插入圖片)、Agent 終端機(貼上路徑)。SSH Worktree 也支援拖放,Orca 會先上傳到遠端主機,讓 Agent 看到真實的磁碟路徑。macOS 截圖縮圖可直接拖進本機 Claude Code 終端機或新 Workspace 撰寫器。
操作步驟:把規格文件交給 Agent
- 從檔案總管(Finder/Explorer)把
spec-export-v2.pdf拖到 Worktree 檔案樹的docs/specs/。 - 確認檔案出現在樹中且顯示為 untracked。
- 再把該檔從 Orca 檔案樹拖到 Agent 終端機,Prompt 中會出現它的路徑。
- 接著輸入任務描述送出。
範例 Prompt
請閱讀 docs/specs/spec-export-v2.pdf 第 3 節「欄位定義」,
與 src/api/export/schema.ts 比對,列出不一致的欄位(表格:欄位、規格、目前實作、建議)。
本輪只產出比對報告,不要修改任何程式碼。🧑⚖️ 人工 Review 要點
- 報告中引用的規格內容能在 PDF 對應頁面找到(抽查至少三列)
- Agent 確實沒有修改程式碼:
git status只多了你放入的 PDF - PDF 若屬機密文件,確認不會被 commit(加入
.gitignore或放在 Worktree 外)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 檔案已複製進 Worktree | git status --short docs/specs/ | 顯示 ?? docs/specs/spec-export-v2.pdf | 確認拖放落點是檔案樹而非終端機 |
| 路徑已傳給 Agent | 檢視 Agent 輸入列 | 出現檔案路徑 | 改拖到 Agent 終端機窗格本身 |
| 未誤提交 | git check-ignore -v docs/specs/spec-export-v2.pdf | 若為機密,應顯示被忽略的規則 | 更新 .gitignore |
12.6 Rich Markdown 編輯器
概念說明
AI 產出的設計文件、ADR、Runbook 多半是 Markdown。Orca 預設以 Rich 編輯器開啟 .md,讓審查者在「渲染後的畫面」上閱讀與留言,並可隨時用 Cmd-Shift-M 切回 Monaco 原始碼。
| 功能 | 操作 |
|---|---|
| Slash 選單 | 空白行輸入 /:標題、清單、程式碼、Callout、圖片、Mermaid、Toggle |
| 可折疊區塊 | /toggle-text、/toggle-h1~/toggle-h5(存為可攜的 details 語法) |
| GitHub 風格 Callout | 引用區塊首行 [!NOTE]、[!TIP]、[!IMPORTANT]、[!WARNING]、[!CAUTION] |
| 內部連結 | 輸入 [[ 自動完成 Worktree 內檔案路徑 |
| Review 註記 | 選取渲染文字後 Add Review Note(Cmd+Shift+A/Ctrl+Shift+A) |
| Front matter | 預設顯示,⋯ 選單 Hide front matter(逐檔設定) |
| 目錄 | 編輯器標題列的 Table of Contents 按鈕 |
| 大檔保護 | 超過 600 KB 先以原始碼編輯器開啟,可選 Open anyway |
| Share as artifact | 發布公開檢視連結(需先開啟 Settings → Artifacts → Allow publishing public artifact links,預設關閉) |
操作步驟:審查 AI 產出的設計文件
- 開啟
docs/adr/0012-export-queue.md,確認是 Rich 模式。 - 用 Table of Contents 快速瀏覽結構,確認必要章節(背景、決策、替代方案、後果)都在。
- 對有疑慮的段落選取文字,按
Cmd+Shift+A新增 Review Note。 - 審完後把所有註記整理成一則 Prompt 交給 Agent 修訂。
範例:好的與不好的文件 Review Note
| 不好的註記 | 好的註記 |
|---|---|
| 這段怪怪的 | 「每秒 500 筆」沒有來源;請引用壓測報告或改為待驗證假設 |
| 補充一下 | 替代方案只列了 Kafka,請補上「直接用資料庫佇列表」並比較維運成本 |
| 圖錯了 | Mermaid 圖中 Worker 直接寫入報表 DB,與第 3 段「經 API 寫入」矛盾,請統一 |
⚠️ 注意事項:Share as artifact 會產生公開連結(單檔上限 10 MiB),任何拿到連結的人都能檢視。企業應維持預設關閉,若需開啟,須規定只能分享已去識別化的內容,並定期從側邊欄 Artifacts 頁面稽核、撤銷連結。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Rich 模式可切換 | 按 Cmd-Shift-M | 在 Rich 與原始碼間切換 | 檔案大於 600 KB 時需 Open anyway |
| Review Note 已建立 | 選取文字按 Cmd+Shift+A | 段落旁出現註記 | 到 Settings → Shortcuts 確認綁定 |
| 分享閘門關閉 | Settings → Artifacts | Allow publishing public artifact links 為關閉 | 依企業政策調整並記錄 |
12.7 HTML Mermaid PDF 等檢視器
概念說明
Agent 常產出 HTML 報告、Mermaid 圖、CSV 資料或 Notebook。Orca 內建檢視器,讓審查不必離開 Worktree。
| 格式 | 能力 | 安全或限制 |
|---|---|---|
| HTML | Open in Orca Browser 或 Open Preview to the Side,經 Workspace 檔案連線讀取相對資源 | 沙箱化;讀取其他資料夾前會詢問;外部連結需確認;預覽內停用下載 |
| Mermaid | Markdown 預覽中即時渲染;.mmd 檔有獨立檢視器(平移、縮放) | — |
| 捲動、縮放、選取文字,縮放與位置會記住 | 位置只在本次執行期保留 | |
| 圖片 | png、jpg、svg、webp、gif;Image-diff 並排比較 | — |
| 音訊與視訊 | 常見格式內建播放,遠端串流 | 無法解碼時顯示錯誤 |
| CSV/TSV | 可直接編輯、排序、篩選、自動偵測分隔符 | 1 MiB 以上為唯讀分頁預覽 |
Jupyter .ipynb | 閱讀、編輯、本機 Python 執行(v1.4.214) | 執行前必須通過信任提示;需要 ipykernel |
操作步驟:驗證 Agent 產出的架構圖
- 請 Agent 把架構圖存成
docs/diagrams/export-flow.mmd。 - 在檔案樹點開,使用專用檢視器平移、縮放。
- 對照程式碼確認每個節點與箭頭都有對應實作。
範例:可直接開啟的 .mmd 檔
flowchart LR
UI["匯出對話框"] --> API["POST /exports"]
API --> Q["工作佇列"]
Q --> W["Export Worker"]
W --> S3["物件儲存"]
W --> N["通知服務"]如何閱讀此圖:由左至右是一次匯出請求的資料流。審查時逐一確認每個箭頭都能在程式碼中找到對應呼叫,例如 Q --> W 應對應到 Worker 的訂閱程式碼。
範例 Prompt(產出可審查的圖)
請依 src/api/export/ 與 src/worker/export/ 的實際程式碼,
產出 docs/diagrams/export-flow.mmd(Mermaid flowchart)。
每個節點標註對應的檔案路徑;只畫程式碼中確實存在的呼叫,不要畫規劃中的元件。🧑⚖️ 人工 Review 要點
- 每個節點的檔案路徑都存在(
ls驗證) - 圖中沒有程式碼裡找不到的元件(AI 常「補完」理想架構)
- Notebook 執行前確認來源可信,再通過信任提示
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Mermaid 可渲染 | 開啟 .mmd 檔 | 顯示圖形並可縮放 | 檢查語法,中文節點加雙引號 |
| HTML 沙箱生效 | 預覽含外部連結的 HTML,點擊連結 | 先出現確認提示 | 回報並檢查 Orca 版本 |
| CSV 未被意外改寫 | 只排序不編輯後執行 git diff 檔名 | 無差異 | 排序與篩選本就不應改寫檔案,若有差異請回報 |
12.8 本章 Review 與驗證清單
- 能用快捷鍵完成終端機分割、搜尋、Floating terminal 開關
- 已設定預設 shell,Windows 使用者能區分 PowerShell 與 WSL 分頁
- 已建立至少三個 Project 範圍的 Quick Commands,且無任何機敏資訊
- 團隊已決定 OSC 52 剪貼簿政策並寫入設定基準
- 已實際觸發一次 changed-on-disk 橫幅並正確處理
- 能把檔案拖進 Agent 終端機傳遞路徑,並確認機密檔不會被提交
- 已在 Rich Markdown 編輯器對 AI 文件留下具體的 Review Note
- Settings → Artifacts 的公開分享閘門狀態符合企業政策
- 能用內建檢視器審查 Mermaid、HTML、CSV、PDF 產出
第十三章 內建瀏覽器與 Design Mode
前端工作的回饋迴圈通常是「在瀏覽器看到問題 → 截圖 → 描述位置 → 等 Agent 猜」。Orca 把一個真正的 Chromium 瀏覽器嵌進每個 Worktree,並以 Design Mode 把「指著畫面說這裡不對」直接轉成 Agent 可用的結構化脈絡。本章也涵蓋瀏覽器 Profile 隔離、Agent 自動操作瀏覽器,以及 Artifact 分享的治理。
📌 查證狀態:官方文件明確記載|來源:Per-worktree browser、Browser-use profiles、Design Mode、Fix a UI bug with Design Mode
13.1 Per-worktree 瀏覽器
概念說明
每個 Worktree 都有自己的瀏覽器分頁集合:網址列、歷史、DevTools 一應俱全。切換 Worktree 時,該 Worktree 的分頁與捲動位置會一併還原。這讓「三個競賽 Worktree 各跑一個 dev server、各開一個瀏覽器分頁比較」成為自然的操作。
| 功能 | 操作或位置 | 補充 |
|---|---|---|
| 新分頁(限本 Worktree) | Cmd-T(焦點在瀏覽器時) | 重新開啟關閉分頁:Cmd-Shift-T |
| 頁面內搜尋 | Cmd-F | — |
| 一般與強制重新載入 | 重新載入按鈕右鍵 | Hard Reload 略過快取,適合前端資源反覆修改 |
| DevTools | 瀏覽器工具列 | v1.4.241 起可停靠在窗格內、調整大小或彈出 |
| 瀏覽歷史 | v1.4.240 新增(Cmd+Y/Ctrl+H) | + omnibox 也會搜尋本 Worktree 歷史 |
| Viewport 模擬 | 分頁自訂 viewport 尺寸 | 以 Chrome DevTools Protocol 模擬,媒體查詢會跟著生效 |
| 下載 | 工具列下方的下載列 | 可取消、開啟、顯示於資料夾 |
| Chrome 擴充套件 | Settings → Experimental → Browser extensions(重啟後生效) | 實驗功能,僅限本機 Profile;廣告封鎖器尚未實際封鎖 |
| 連結開啟方式 | Settings → Browser → Link Routing | 終端機、Markdown、編輯器中的連結開在 Orca 或系統瀏覽器 |
遠端 Workspace:連到 Remote Orca Server 的 Workspace,新頁面預設在本機渲染,但 HTTP(S)、WebSocket、DNS 與 loopback 流量仍經由遠端主機;可在 Settings → Browser → Remote server workspaces 改為 Server(streamed)。SSH Workspace 則由 Browse through SSH workspace hosts 決定流量走哪台機器。
操作步驟:三個競賽 Worktree 的畫面比較
- 在
fix-bug、fix-bug-2、fix-bug-3各自的終端機以不同 port 啟動 dev server,例如PORT=3001 pnpm dev、PORT=3002 pnpm dev、PORT=3003 pnpm dev。 - 在每個 Worktree 開瀏覽器分頁,分別前往
localhost:3001、3002、3003。 - 用
Cmd-J搭配Shift-Enter把其他 Worktree 開在分割窗格,並排比較。 - 需要測 RWD 時,在分頁設定 viewport 尺寸(例:390 × 844)。
範例:查詢 Worktree 偵測到的 dev server port
orca portsorca ports 為 v1.4.240 新增,用來列出 Worktree 偵測到的 dev server port;不支援直接 SSH 主機。實際參數以 orca ports --help 為準。
📌 查證狀態:依官方說明延伸(教學推論)|來源:v1.4.240 release notes(官方文件快照的 CLI reference 尚未收錄此指令)
⚠️ 注意事項:Chrome 擴充套件屬實驗功能,擴充套件可讀取頁面內容。企業應只允許白名單內的擴充套件(如公司核准的密碼管理器),並在第二十八章的威脅模型中登錄。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 分頁隨 Worktree 隔離 | 在 A 開分頁後切到 B | B 看不到 A 的分頁 | 確認不是在 Floating Workspace 開的分頁 |
| Viewport 模擬生效 | DevTools Console 輸入 window.innerWidth | 等於設定寬度 | 重新設定 viewport |
| 遠端流量路徑正確 | 檢視工具列的主機指示 | 顯示預期主機 | 調整 Settings → Browser 相關選項 |
13.2 Browser-use Profiles
概念說明
Profile 讓瀏覽器以特定身分運作:特定登入狀態、Cookie、User-Agent、Viewport。每個 Profile 有獨立的儲存分區(Cookie、Local Storage、Cache),彼此不會互相洩漏。Agent 透過 CLI 操作瀏覽器時,會沿用窗格目前啟用的 Profile。
v1.4.239 起,Settings → Browser → Profile for new tabs 可選:
| 模式 | 意義 | 適用情境 |
|---|---|---|
| Shared(預設) | 所有新分頁共用 | 個人開發 |
| Per-repo | 每個 Repository 一個 Profile | 不同客戶專案的登入互不干擾 |
| Per-workspace | 每個 Worktree 一個 Profile | 同一系統以不同角色測試(管理員、一般使用者) |
操作步驟
- 開啟 Settings → Browser → Profiles,點 Add profile,命名為
qa-admin。 - 視需要匯入 Cookie(Chrome、Edge、Vivaldi 或 Cookie 檔)、設定 User-Agent 與 Viewport。匯入只會取代匯入範圍內網域的 Cookie。
- 在瀏覽器工具列選擇
qa-admin,該窗格所有分頁即使用此 Profile。 - 再建立
qa-viewerProfile,在另一個窗格以一般使用者登入,並排比較權限差異。
範例:以 CLI 建立不偽裝 UA 的 Profile
orca tab profile create --no-ua-spoof某些網站(例如部分 Google 登入流程)會拒絕 Orca 預設的 Chrome 樣式 UA,此時改用保留原生 Electron UA 的 Profile。Google Cookie 一律不會被匯入,需在 Orca 內直接登入 Google;登入卡在舊帳號時,用 Settings → Browser → Session & Cookies → Clear Google cookies…。
範例 Prompt(以特定 Profile 重現權限 Bug)
目前瀏覽器窗格使用 qa-viewer Profile(一般使用者)。
請用 orca snapshot 與 orca click 重現:一般使用者在 /reports 頁面仍看得到「刪除」按鈕。
只回報重現步驟與截圖,不要修改程式碼。⚠️ 注意事項:Profile 中的 Cookie 等同登入憑證,Agent 可以使用它操作網站。企業規範應明定:Profile 只能放測試環境、測試帳號的登入;絕不匯入正式環境管理後台或個人主帳號的 Cookie。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Profile 隔離 | 在 qa-admin 登入後切到 qa-viewer 重新整理 | qa-viewer 仍為未登入或一般使用者 | 確認工具列選的 Profile |
| 新分頁模式 | Settings → Browser → Profile for new tabs | 顯示團隊約定的模式 | 調整並重開分頁(只影響新分頁) |
| Google 未被匯入 | 匯入後查看提示訊息 | 顯示 Google 登入未匯入 | 屬預期行為 |
13.3 Design Mode 操作
概念說明
Design Mode 把瀏覽器變成「指向即程式碼」的工具。開啟後游標變成選取器,點擊頁面上任一元素,Orca 會擷取並打包成一個附件送進目前作用中的 Agent:
- 元素的 HTML(外層與一小段鄰近結構)
- 計算後的 CSS(顏色、字型、間距)
- 元素的裁切截圖
- 若有開發模式 source map,還會附上原始檔與行號
你只需要再輸入「想怎麼改」。
sequenceDiagram
participant U as 開發者
participant B as Orca 瀏覽器
participant O as Orca
participant A as Agent
U->>B: 開啟 Design Mode 並點擊元素
B->>O: HTML、計算 CSS、截圖、原始檔位置
O->>A: 以單一附件送進作用中的 Agent
U->>A: 輸入修改需求
A->>A: 修改原始碼
A-->>B: Hot reload 重新整理
U->>B: 再次點擊元素驗證如何閱讀此圖:由上往下是一輪迴圈。關鍵在最後一步——人要再點一次元素驗證,而不是相信 Agent 說「已修正」。若仍不對,從第一步再來一輪。
操作步驟
- 在 Worktree 的瀏覽器窗格開啟有問題的頁面。
- 點工具列的 Design Mode 切換鈕(也可在 Settings → Shortcuts 為 Annotate page element 綁定快捷鍵)。
- 滑過元素會高亮,點擊即擷取。
- 需要一次指出多個問題時,使用**註記匣(annotation tray)**累積多則註記;滑過註記可 Edit 修改文字或意圖,再 Save 或 Cancel。
- 送出後,Orca 會移除已送出的註記;送出過程中新增或編輯的註記會保留。
- 預設值可在 Settings → Browser 的 Design Mode defaults 調整。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 擷取內容完整 | 點擊元素後檢視 Agent 輸入區附件 | 含 HTML、CSS、截圖 | 確認有作用中的 Agent 分頁 |
| 原始檔定位 | 在 dev 模式下點擊元素 | 附件含檔案與行號 | 確認 dev server 有輸出 source map |
| 註記清理 | 送出後檢視註記匣 | 已送出的註記消失 | 正在送出時新增的註記會保留,屬預期 |
13.4 以 Design Mode 修正 UI 缺陷實作
📌 查證狀態:教學示例(非官方),非真實客戶專案;流程依據官方 Fix a UI bug with Design Mode
情境:報表清單頁的「匯出」按鈕在深色模式下文字對比度不足,且與上方卡片的內距不一致。
操作步驟
- 在
fix-export-buttonWorktree 啟動 dev server,瀏覽器開啟/reports,切換為深色模式。 - 開啟 Design Mode,點擊「匯出」按鈕。
- 在附件後輸入修改需求(見下方 Prompt)。
- Agent 修改原始碼,hot reload 自動重新整理。
- 再次點擊按鈕,確認 Design Mode 擷取到的計算 CSS 已改變。
- 用 Diff Viewer 審查變更(第十四章),確認後 commit。
範例 Prompt:不好與好的寫法
❌ 不好:這個按鈕很醜,修一下。✅ 好:
這個按鈕在深色模式下文字與背景對比度不足。
1. 對比度需達 WCAG AA(一般文字 4.5:1)。
2. 內距改成與上方 .report-card 相同(附件中可看到 card 為 16px 24px)。
3. 只能使用 src/styles/tokens.css 中既有的 design token,不得寫死色碼。
4. 只修改 ExportButton 元件的樣式檔,不要動其他元件。
完成後回報修改了哪個檔案的哪幾行。預期的 Diff(示意)
.export-button {
- padding: 8px 12px;
- color: #6b7280;
- background: #1f2937;
+ padding: var(--space-4) var(--space-6);
+ color: var(--color-text-on-primary);
+ background: var(--color-primary-600);
}常見的不良產出(示意)
.export-button {
- padding: 8px 12px;
- color: #6b7280;
+ padding: 16px 24px !important;
+ color: #ffffff !important;
}
+
+button {
+ color: #ffffff;
+}問題:寫死色碼、使用 !important,還新增了影響全站的 button 選擇器——這正是 Design Mode 讓 Agent「看得到這一個元素」之後,仍需要人工把關的地方。
🧑⚖️ 人工 Review 要點
- 修改只落在指定元件的樣式檔:
git diff --name-only - 沒有寫死色碼、沒有
!important、沒有全域選擇器:git diff | grep -E "#[0-9a-fA-F]{3,6}|!important|^\+\s*button\s*\{"無輸出 - 用 Design Mode 再次點擊,計算 CSS 中的顏色與內距為預期值
- 淺色模式也要檢查一次,避免修了深色、壞了淺色
- 以 DevTools 或對比度工具實際量測,達 4.5:1
範例 commit message
fix(reports): improve export button contrast in dark mode
Use design tokens for padding and colors so the button matches
report cards and meets WCAG AA (4.5:1) in dark mode.✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 對比度達標 | DevTools 的對比度檢查 | 至少 4.5:1 | 以 Design Mode 再送一輪 |
| 範圍正確 | git diff --stat | 只有 ExportButton 的樣式檔 | 以 Annotate AI Diff 要求還原其他檔案 |
| 雙模式正常 | 切換淺色與深色模式各點一次 | 兩者都正確 | 補充要求後重跑 |
13.5 瀏覽器自動化與 Artifact 分享
概念說明
同一個內建瀏覽器也能被 Agent 透過 Orca CLI 操作——同一批分頁、同一個 Session。v1.4.241 起,Agent 操作瀏覽器時頁面上會顯示它的游標與活動標記,在對話中點擊瀏覽器連結即可跳到該頁。官方建議的操作模式是 snapshot → act → snapshot:先取得頁面快照(元素帶有 @e3 之類的參照),再操作,頁面變化後重新快照。
| 指令 | 用途 |
|---|---|
orca goto --url <url> | 前往網址 |
orca snapshot | 取得可操作元素與參照 |
orca click --element @e3 | 點擊元素 |
orca fill --element @e1 --value "..." | 填入欄位 |
orca wait --text "Welcome" | 等待文字出現 |
orca screenshot/orca full-screenshot | 截圖 |
orca console/orca network | 讀取 Console 與網路紀錄 |
orca set device --name "iPhone 12" | 裝置模擬 |
所有指令都可加 --worktree active --json。這些指令只控制 Orca 內建瀏覽器,不控制 Chrome、Safari 或 Orca 桌面 UI(桌面應用操作屬 Computer Use,見第十七章)。
範例:登入流程冒煙測試
orca goto --url http://localhost:3000/login --worktree active --json
orca snapshot --worktree active --json
orca fill --element @e1 --value "qa-viewer@example.test" --worktree active --json
orca fill --element @e2 --value "$QA_VIEWER_PASSWORD" --worktree active --json
orca click --element @e3 --worktree active --json
orca wait --text "Dashboard" --worktree active --json
orca screenshot --worktree active --json範例 Prompt
請以 snapshot → act → snapshot 的方式,對 http://localhost:3000 執行冒煙測試:
1. 登入(帳號使用環境變數 QA_VIEWER_USER 與 QA_VIEWER_PASSWORD,不要把值印出來)
2. 進入 /reports,確認看不到「刪除」按鈕
3. 每一步截圖,並用 orca console 檢查是否有錯誤
最後輸出表格:步驟、預期、實際、截圖檔名。不得修改任何程式碼。🧑⚖️ 人工 Review 要點
- 每一步都有對應截圖,且截圖內容與「實際」欄一致
- 密碼沒有出現在終端機輸出或報告中(
orca terminal read搜尋密碼片段) - Agent 在頁面變化後有重新 snapshot,而不是沿用失效的元素參照
- 只對測試環境操作,網址不是正式環境
Artifact 分享
在 Worktree 瀏覽器開啟的本機 HTML 檔,可用工具列 Share as artifact 透過已登入的 Orca 帳號產生公開檢視連結(與 Markdown 共用同一個閘門與管理介面)。重點限制:
- 必須先由人在該裝置開啟 Settings → Artifacts → Allow publishing public artifact links(預設關閉,v1.4.180 起);沒有 CLI 旗標能繞過。
- 單檔上限 10 MiB;相對路徑資源不會上傳,需分享自含式 HTML。
- 檢視公開連結不需登入;建立、列出、更新、刪除需要登入。
orca artifacts share ./reports/smoke-test.html --json
orca artifacts list --json
orca artifacts delete <id> --json⚠️ 注意事項:測試報告常含內部網址、帳號名稱與截圖。企業若開放 Artifact,應規定分享前去識別化,並由專人每月以 orca artifacts list 稽核、刪除過期連結。被拒絕時會出現 artifact_sharing_disabled,應修正設定而非重試。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 自動化可執行 | orca snapshot --worktree active --json | 回傳含元素參照的 JSON | 先開一個瀏覽器分頁(orca tab create --url ...) |
| 參照未失效 | 頁面跳轉後重新 snapshot | 新參照可正常點擊 | 每次頁面變化後都重新 snapshot |
| 分享閘門 | 閘門關閉時執行 orca artifacts share | 失敗並回報 artifact_sharing_disabled | 屬預期;依政策決定是否開啟 |
13.6 本章 Review 與驗證清單
- 能說明 Per-worktree 瀏覽器的隔離範圍與遠端 Workspace 的流量路徑
- 已為三個 Worktree 各開 dev server 並並排比較畫面
- 已建立至少兩個 Browser Profile,並確認彼此 Cookie 隔離
- 團隊已決定 Profile for new tabs 的模式,以及 Profile 只能放測試帳號的規範
- 已用 Design Mode 完成一次 UI 修正,並以「再點一次」與 Diff 審查驗證
- 能分辨 Design Mode 產出中的不良模式(寫死色碼、
!important、全域選擇器) - 已用 snapshot → act → snapshot 完成一次冒煙測試,且無密碼外洩
- Artifact 公開分享閘門狀態符合企業政策,並有定期稽核機制
第十四章 Review 與 Source Control
Agent 寫程式的速度遠超過人審查的速度,因此 ADE 的價值最終取決於「審查」這一關做得好不好。本章從 Diff Viewer 的操作開始,示範如何逐行審查 AI Diff、如何寫出有效的 Annotate 留言、如何利用 Attribution 聚焦風險,再到 commit、push、amend 與 rollback。方法論層面的三層驗證模型見第二十二章,本章聚焦在 Orca 內的實際操作。
📌 查證狀態:官方文件明確記載|來源:Diff viewer、Annotate AI Diff、Attribution、Commit & push、Review an AI diff line-by-line
14.1 Diff Viewer
概念說明
每個 Worktree 都內建一個對 start-from ref 的 Diff。它是為「認真審查 AI 程式碼」設計的,而不是瞄一眼用的。
| 功能 | 說明 |
|---|---|
| Combined diff | 一次呈現 staged、unstaged、untracked 全部變更,可搭配可調寬度的檔案樹 |
| 比較基準 | 預設對 start-from ref;工具列可切換為任一 commit、分支或 base ref |
| 逐 hunk 或逐行 stage | 視覺化的 git add -p |
| 三方合併 | 衝突時的 three-way 檢視與行內解決 |
| 圖片 Diff | 並排、滑動(swipe)、洋蔥皮(onion-skin) |
| HTML 預覽 | Combined diff 中,仍存在的 HTML 檔可按眼睛圖示 Open Preview to the Side |
| Show Whitespace | 顯示空白、Tab 等字元 |
| 收合未變更區域 | 預設關閉,從 Diff 編輯器動作選單開啟 |
| Word Wrap | 預設關閉;⋯ 選單或 Settings → General → Diff Word Wrap |
鍵盤操作
| 按鍵 | 動作 |
|---|---|
j/k | 下一個/上一個變更檔案 |
n/p | 下一個/上一個 hunk |
F7/Shift+F7 | 目前編輯器中的下一個/上一個變更 |
s | Stage 游標所在 hunk |
c | 開始留言(Annotate AI Diff) |
Source Control 面板頂端的分支列會顯示「目前分支 → 比較基準」,並有一個顯示新增/刪除總行數的小晶片;滑過時若主機提供,會顯示 Source、Tests、Generated 的分類(僅依路徑判斷,非內容分析)。
操作步驟:審查前的全局掃描
- 開啟 Worktree 的 Diff,確認比較基準是正確的 start-from ref。
- 看分支列晶片的總行數與 Source/Tests 分布:只有 Source 沒有 Tests,通常是第一個警訊。
- 展開檔案樹,先看檔案清單是否符合任務範圍,再看內容。
- 開啟 Show Whitespace,避免 AI 夾帶大量空白或換行格式變更。
範例:在終端機做同樣的全局掃描
git diff --stat main...HEAD
git diff --name-status main...HEAD
git diff --check main...HEAD # 行尾空白與衝突標記
git diff -w --stat main...HEAD # 忽略空白後的實際變更量若 --stat 與 -w --stat 差距很大,代表有大量純格式變更混在功能變更中,應要求 Agent 拆開。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 比較基準正確 | 檢視 Diff 工具列與分支列 | 顯示預期的 base | 從工具列切換基準 |
| 檔案數一致 | 比對檔案樹與 git diff --name-only main...HEAD 加上 untracked | 數量一致 | 按 Diff 工具列重新整理 |
| 鍵盤導覽可用 | 在 Diff 中按 j、n | 游標移到下一檔與下一 hunk | 先點擊 Diff 區域取得焦點 |
14.2 Annotate AI Diff
概念說明
Annotate AI Diff 是 Orca 針對 Agent 程式碼的行內審查迴圈:在任一行留言,最後一次批次送回 Agent 修訂。之所以要批次,是因為一則一則送會讓 Agent 來回擺盪;批次送出讓 Agent 一次思考、一次修訂,命中率高得多。
兩種留言管道,用途不同
| 管道 | 時機 | 留言存在哪裡 | 誰看得到 |
|---|---|---|---|
| Annotate AI Diff | PR 建立前,本機 Diff | Orca 本機,組成 Prompt 送給 Agent | 只有你與收到的 Agent |
| Hosted review 的 Checks 面板 | PR/MR 建立後 | 寫入 GitHub 等平台的 Review 留言 | 整個團隊 |
若留言需要留存為稽核紀錄或讓其他成員看到,必須在 PR 建立後於 Checks 面板留言(第十五章)。
操作步驟
- 滑過 Diff 任一行,左側 gutter 出現 +;拖曳多行或按住 Shift 延伸可選範圍(v1.4.206 起支援多行)。
- 點 + 或在該行按
c。 - 輸入留言(支援 Markdown),
Enter或Cmd/Ctrl-Enter儲存,Shift-Enter換行,Esc取消。 - 全部審完後,點 Diff 頂端的 Send to agent,在 Send notes to 選單選擇要修訂的 Agent,或從同一選單啟動新 Agent。
- Send Review Notes to Agent 預設未綁定,可到 Settings → Shortcuts 指派(v1.4.156 新增)。
- Agent 修訂後留言仍釘在原行,用來驗證是否修好;修好的按 Resolve 收合,未解決的會在下一次 Send 時一併送出。
好的與不好的留言
| 不好的留言 | 為什麼不好 | 好的留言 |
|---|---|---|
| 這裡不對 | 沒說哪裡不對、要改成什麼 | 逾時寫死 30000,請改讀 config.http.timeoutMs,並在 config.test.ts 補一個預設值測試 |
| 加測試 | 範圍不明 | 請補兩個測試:重試 3 次後仍失敗應丟出 PaymentTimeoutError;第 2 次成功時不應再重試 |
| 用更好的寫法 | 主觀、無標準 | 這段與 src/http/retry.ts 的 withRetry 重複,請改用既有工具函式 |
| 安全問題 | 沒指出風險 | 第 42 行把 Authorization header 寫進 log,會外洩 Token;請移除或遮罩 |
| ??? | 無資訊 | 這個 catch 吞掉所有例外,包含程式錯誤;請只捕捉 NetworkError 並重新拋出其他例外 |
好留言的公式:位置(已由行號錨定)+問題+期望結果+驗證方式。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 留言已釘選 | 留言後捲動 Diff | 留言跟著該行 | 確認按的是 Enter 而非 Esc |
| 批次送出 | 點 Send to agent | 出現 Send notes to 選單並列出可用 Agent | Worktree 內需有可用 Agent,或從選單啟動新 Agent |
| 追蹤修訂 | Agent 完成後重開 Diff | 留言仍在,可 Resolve | 留言跟隨行移動,若該行被刪除請人工判斷 |
14.3 逐行審查 AI Diff 實作
📌 查證狀態:教學示例(非官方),非真實客戶專案;流程依據官方 Review an AI diff line-by-line
情境:要求 Agent「為付款 API client 加上逾時重試」。Agent 回報「已完成,測試通過」。
sequenceDiagram
participant R as Reviewer
participant D as Orca Diff Viewer
participant A as Agent
R->>D: j/k 逐檔、n/p 逐 hunk 審查
R->>D: 以 c 在問題行留言
R->>D: Send to agent(批次)
D->>A: 單一 Prompt,含行號錨定的所有留言
A->>A: 修訂程式與測試
A-->>R: 狀態點轉為閒置或已完成
R->>D: 重開 Diff,逐則驗證並 Resolve
alt 仍有問題
R->>D: 對未解決處追加留言並再次 Send
else 全部解決
R->>D: Stage 並 Commit
end如何閱讀此圖:這是一個可重複的迴圈。每一輪只送一次批次;Agent 修訂完成後,人要回到 Diff 逐則對照留言驗證,而不是只看 Agent 的總結訊息。alt 區塊表示依驗證結果決定再來一輪或進入提交。
第一輪:Agent 的原始 Diff
--- a/src/payment/client.ts
+++ b/src/payment/client.ts
@@ -12,9 +12,22 @@ export class PaymentClient {
async charge(req: ChargeRequest): Promise<ChargeResult> {
- const res = await this.http.post('/charge', req);
- return res.data;
+ for (let i = 0; i < 5; i++) {
+ try {
+ logger.info('charge request', { headers: this.http.headers, req });
+ const res = await this.http.post('/charge', req, { timeout: 30000 });
+ return res.data;
+ } catch (e) {
+ await sleep(1000);
+ }
+ }
+ return { status: 'failed' } as ChargeResult;
}審查者的思考(逐 hunk 問三個問題:必要嗎?最小嗎?與檔案其他部分一致嗎?)
| 行 | 發現 | 嚴重度 |
|---|---|---|
logger.info(... headers ...) | 把含 Authorization 的 headers 寫進 log | 高(資安) |
catch (e) 不分類 | 4xx 業務錯誤也重試,可能重複扣款 | 高(正確性) |
迴圈 5 次、sleep(1000)、30000 | 魔術數字,且與既有 withRetry 重複 | 中 |
return { status: 'failed' } as ChargeResult | 用型別斷言吞掉失敗,呼叫端無法區分原因 | 中 |
| 沒有測試檔變更 | 「測試通過」只代表舊測試沒壞 | 高(證據不足) |
第一輪送出的 Annotate 留言(批次)
[src/payment/client.ts:15] 這行把 this.http.headers(含 Authorization)寫進 log,會外洩 Token。請移除 headers,只記錄 req.orderId。
[src/payment/client.ts:16-21] 所有例外都重試,4xx(例如餘額不足)重試可能造成重複扣款。只對逾時與 5xx 重試,且請求需帶 Idempotency-Key(使用 req.orderId)。
[src/payment/client.ts:14] 請改用 src/http/retry.ts 的 withRetry,次數與間隔讀 config.payment.retry,不要寫死。
[src/payment/client.ts:23] 不要用型別斷言回傳假結果;重試耗盡請丟出 PaymentTimeoutError。
[整體] 請新增 tests/payment/client.retry.test.ts,涵蓋:5xx 後成功、逾時耗盡丟錯、4xx 不重試、log 不含 Authorization。執行 pnpm test -- tests/payment 並貼上完整輸出。第二輪:修訂後的 Diff
--- a/src/payment/client.ts
+++ b/src/payment/client.ts
@@ -12,9 +12,19 @@ export class PaymentClient {
async charge(req: ChargeRequest): Promise<ChargeResult> {
- const res = await this.http.post('/charge', req);
- return res.data;
+ logger.info('charge request', { orderId: req.orderId });
+ return withRetry(
+ async () => {
+ const res = await this.http.post('/charge', req, {
+ timeout: config.payment.timeoutMs,
+ headers: { 'Idempotency-Key': req.orderId },
+ });
+ return res.data;
+ },
+ { ...config.payment.retry, retryOn: isRetryablePaymentError },
+ ).catch(toPaymentError);
}此時審查者回到每一則留言逐一 Resolve,並追加一則:
[src/payment/client.ts:24] toPaymentError 在哪裡定義?Diff 中沒看到新增,請確認不是引用了不存在的函式,並說明重試耗盡時它回傳哪個錯誤類別。這一則示範了 AI 常見問題:引用不存在或未提交的符號。只看 Diff 不容易發現,要搭配 git grep 驗證。
🧑⚖️ 人工 Review 要點(逐行審查 AI Diff 的通用清單)
- 檔案範圍:
git diff --name-only只包含任務相關檔案 - 每個新增符號都存在:
git grep -n "function toPaymentError\|const toPaymentError"有結果 - 無機敏資訊進 log:
git diff | grep -iE "authorization|token|password|secret"逐筆確認 - 錯誤處理有分類,不吞例外,不以型別斷言掩蓋失敗
- 副作用操作(扣款、寄信、寫入)重試時具冪等性
- 沒有魔術數字,與既有工具函式不重複
- 有新測試,且新測試在修正前會失敗(可要求 Agent 暫時還原修正並貼出失敗輸出)
- 測試輸出是完整貼上的終端機內容
- 所有 Annotate 留言都已 Resolve 或有明確的不修理由
✅ 驗證方式
執行:
git grep -n "toPaymentError" -- src/ pnpm test -- tests/payment git diff main...HEAD | grep -inE "authorization|bearer" || echo "no secrets in diff"預期輸出(示意):
src/payment/errors.ts:8:export function toPaymentError(e: unknown): never { src/payment/client.ts:24: ).catch(toPaymentError); PASS tests/payment/client.retry.test.ts (4 tests) no secrets in diff判讀:
toPaymentError必須同時出現在定義處與使用處;測試數量應等於你要求的情境數;若 grep 找到 Authorization,回到第一輪留言重送。
14.4 Attribution 歸屬標記
概念說明
Orca 會記錄 Agent 透過其工具寫入檔案的行範圍,在 Diff Viewer 的 gutter 以淡色標記標示 AI 產生的行;人在 AI 程式碼上再修改,該行歸屬會翻回人類。
| 用途 | 說明 |
|---|---|
| 聚焦審查 | 知道哪些行需要額外檢視 |
| 稽核與合規 | 區分 AI 與人工撰寫的程式碼 |
| 加速審查 | 不必重讀自己剛手寫的程式碼 |
重要限制:Attribution 只存在 Orca 本機,不會 commit 進 git。需要持久保存時,從 Diff 工具列匯出 Diff metadata。
操作步驟:把 Attribution 納入稽核
- 審查時優先檢視帶 AI 標記的行。
- 合併前,從 Diff 工具列匯出 Diff metadata,存到團隊的稽核儲存區(不建議放進程式碼 repo)。
- 在 commit message 以 trailer 註明 AI 協作,讓 git 歷史本身也保有基本歸屬資訊。
範例:commit trailer(教學示例,非 Orca 內建格式)
feat(payment): retry charge on timeout and 5xx with idempotency key
Refs: PAY-231
AI-Assisted: claude-code
Reviewed-by: Jane Lin <jane.lin@example.com>📌 查證狀態:依官方說明延伸(教學推論)——
AI-Assistedtrailer 為本手冊建議的團隊慣例,非 Orca 功能|來源:Attribution
範例:查詢含 AI 協作 trailer 的 commit
git log --format="%h %s%n %(trailers:key=AI-Assisted,valueonly)" main~50..main✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| AI 行有標記 | 讓 Agent 修改一行後開 Diff | gutter 出現 AI 標記 | Agent 需透過其工具寫檔才會被記錄 |
| 人工修改翻轉 | 手動編輯該行後重開 Diff | 標記消失 | 確認已自動儲存 |
| 持久化 | 匯出 Diff metadata 並檢查檔案 | 檔案含 AI 行範圍 | Attribution 不在 git 中,未匯出即無留存 |
14.5 Commit Push 與 Amend
概念說明
Source Control 面板(側邊欄)與 Diff 旁的 commit 面板涵蓋「審查 → stage → commit → push → 開 Review」的完整流程。主按鈕會隨狀態改變:有未 stage 變更時是 Stage Files,接著是 Commit,再來依與 upstream 的關係變成 Push、Pull 或 Sync。
| 動作 | 行為重點 |
|---|---|
| Commit | Cmd-Enter(macOS)/Ctrl-Enter(Windows/Linux);repo 的 pre-commit hook 照常執行,失敗輸出會行內顯示 |
| Generate with AI | 依 staged 變更起草 commit message |
| Fix with AI | commit 失敗時,把 hook 輸出、原 message、staged 檔案清單交給預設 Agent;只要求修復,不會要求它繞過 hook、commit 或 push |
| Push | 首次自動設定 upstream;落後時不會偷偷 force push |
| Force push with lease | 改寫歷史後才出現的獨立動作,標示將取代的 commit 數與 upstream 名稱,使用 --force-with-lease |
| Amend | 明確動作 Commit → Amend;已 push 的 commit 需再次確認 |
| Hosted review | push 後由 Source Control 建立 PR/MR;確認 base、標題、描述、Draft |
| Generate pull request details with AI | 依分支 Diff 與 commit 起草 PR 標題與描述 |
Action recipes:Generate with AI、Generate pull request details with AI、Fix with AI、Resolve with AI 都由「動作配方」驅動,可在 Settings → Git & Source Control → Action recipes 設定全域預設或單一 Repository 覆寫(Agent、CLI 參數、Prompt 範本)。範本變數包括 {basePrompt}、{branch}、{stagedFiles}、{stagedPatch}、{linkedIssue};PR 範本另有 {baseBranch}、{currentTitle}、{currentBody}、{commitSummary}、{changedFiles}、{patch}。
範例:企業 commit message 配方範本
{basePrompt}
依下列規範撰寫 commit message:
- 第一行:<type>(<scope>): <summary>,type 限 feat/fix/refactor/test/docs/chore,總長 72 字元內,英文小寫開頭、結尾不加句號
- 空一行後,以條列說明「為什麼」而非「做了什麼」
- 若有連結的工作項目,最後一行寫:Refs: <工作項目編號>(目前連結的 GitHub issue:{linkedIssue},若為空則省略此行,不要輸出空的 Refs)
- 不得出現 staged 檔案以外的內容
分支:{branch}
Staged 檔案:
{stagedFiles}官方提醒:{linkedIssue} 在沒有連結 GitHub issue 時會展開為空字串(包含純 Linear 或 GitLab 的 Workspace),所以範本應寫成指示句,而不是直接寫 Fixes #{linkedIssue},否則會產生 Fixes #。
好的與不好的 commit message
❌ update files
❌ fix bug
❌ feat: Implemented the retry logic for the payment client as requested by the user, including tests and log changes.✅ fix(payment): avoid duplicate charge when retrying 4xx responses
- retry only timeouts and 5xx via withRetry
- send Idempotency-Key derived from orderId
- stop logging request headers (contained Authorization)
Refs: PAY-231🧑⚖️ 人工 Review 要點(AI 產生 commit message 或 PR 描述後)
- 描述與
git diff --staged --stat的實際內容一致,沒有「宣稱做了但沒做」的項目 - 沒有把機敏資訊(主機名、帳號、Token 片段)寫進 message
-
Refs:/Fixes指向正確工作項目,且沒有空的Fixes # - PR 描述中的「測試方式」可實際照做
- Draft 狀態符合意圖(Agent 回傳不同 Draft 狀態時,Orca 會保留你的選擇)
操作步驟:從審查完成到開 PR
- 在 Diff 以
s逐 hunk stage,或在 Source Control 逐檔 stage。 - 點 Generate with AI 起草 message,依上方清單修改。
Cmd-Entercommit;若 hook 失敗,閱讀輸出,必要時用 Fix with AI。- 點 Push。
- 點 hosted review 動作建立 PR,用 Generate pull request details with AI 起草,確認 base 分支與 Draft 後送出。
⚠️ 注意事項:不要為了讓 commit 通過而要求 Agent 加 --no-verify。Orca 的 Fix with AI 刻意不要求繞過 hook,團隊 Prompt 也應遵守同一原則。
✅ 驗證方式
執行:
git log -1 --format="%H%n%an <%ae>%n%B" git status -sb git rev-parse --abbrev-ref --symbolic-full-name @{u}預期輸出(示意):
9f1c2ab... Jane Lin <jane.lin@example.com> fix(payment): avoid duplicate charge when retrying 4xx responses ... ## fix-pay-231...origin/fix-pay-231 origin/fix-pay-231判讀:作者為正確身分(若啟用 commit signing,再以
git log --show-signature -1確認);git status -sb不顯示 ahead/behind 代表已同步;upstream 存在代表首次 push 已設定追蹤。
14.6 Rollback 與歷史追溯
概念說明
Worktree 底層就是 git,回復與追溯完全使用標準 git;Worktree 隔離確保在 A 的回復不會影響 B。選擇回復方式的關鍵是「是否已經 push、是否已被他人使用」。
| 情境 | 建議做法 | 指令 |
|---|---|---|
| 未 commit,想放棄 Agent 的某檔修改 | Source Control 右鍵 discard,或 restore | git restore <file> |
| 未 push,想撤銷最後一個 commit 但保留修改 | soft reset | git reset --soft HEAD~1 |
| 未 push,Agent 整輪方向錯誤 | 回到特定 commit | git reset --hard <sha>(先確認無未提交工作) |
| 已 push 或已合併 | 產生反向 commit | git revert <sha> |
| reset 後後悔 | 從 reflog 找回 | git reflog 後 git reset --hard <sha> |
| merge 或 rebase 中途放棄 | Source Control 的 Abort merge/Abort rebase | git merge --abort/git rebase --abort |
歷史追溯工具
git log --follow -p -- <file>:追蹤單一檔案的完整演變(含改名)。git blame -w -C <file>:逐行追溯作者,忽略空白、偵測搬移。git range-diff:比較同一條分支 rebase 或 Agent 修訂前後的 commit 序列。- Worktree Checkpoint 留言(
orca worktree current --json)與 Session History(第九章)可補足「為什麼這樣改」的脈絡。
範例:用 range-diff 檢查 Agent 第二輪修訂改了什麼
# 修訂前先記下分支位置
git branch review/pay-231-round1 HEAD
# Agent 修訂並重新整理 commit 後
git range-diff main review/pay-231-round1 HEAD範例:回復已合併的 AI 變更
git log --oneline --grep "PAY-231" main
git revert -m 1 <merge-commit-sha>
git commit --amend -m "revert: payment retry (PAY-231) due to duplicate charge in staging
This reverts merge <merge-commit-sha>.
Refs: PAY-231, INC-77"💡 小技巧:每一輪 Annotate → 修訂都對應一個獨立 commit(message 註明回應了哪些留言),比把所有修正壓成一個巨大 commit 更容易回溯;要整理成單一 commit 可在開 PR 前 squash,或交由 GitHub 的 Squash and merge。
⚠️ 注意事項:回復前先確認該 Worktree 沒有 Agent 正在執行或有未提交的人工修改(看狀態點與 git status),避免 reset --hard 抹掉進行中的工作。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| revert 生效 | git show --stat HEAD | 變更與原 commit 方向相反 | 檢查 -m 父節點參數 |
| 無遺失工作 | git reflog -10 | 可找到 reset 前的 SHA | 用該 SHA 還原 |
| 回復後測試 | 執行完整測試 | 全數通過 | 回復可能與後續 commit 相依,需人工處理 |
14.7 本章 Review 與驗證清單
- 能用
j/k/n/p/s/c完成一次純鍵盤審查 - 能分辨 Annotate AI Diff(本機)與 Checks 面板留言(平台)的差異與適用時機
- 寫出的留言都具備「問題+期望結果+驗證方式」
- 已完成一次兩輪以上的 Annotate → 修訂 → Resolve 迴圈
- 能用
git grep驗證 AI 引用的符號確實存在 - 了解 Attribution 不進 git,並已決定團隊的匯出或 trailer 慣例
- 已設定團隊的 commit message Action recipe,且不會產生空的
Fixes # - 團隊規範明定不得以
--no-verify繞過 hook - 能依「是否已 push」選擇 reset 或 revert,並會用 reflog 救回
第十五章 GitHub Linear 與 Jira 整合
Orca 把「工作項目 → Worktree → Agent → PR → 合併」串成一條線:從 Issue 開 Worktree、Agent 在隔離分支上工作、push 後開 PR、在 Orca 內看 Checks 與留言、最後合併並回寫狀態。本章說明分支策略、GitHub/Linear/Jira 三大官方整合、其他程式碼託管平台的實際支援現況,以及 GitHub 錯誤排除。
📌 查證狀態:官方文件明確記載|來源:GitHub、Linear、Jira、GitHub errors
flowchart LR
I["工作項目:GitHub Issue/Linear/Jira"] --> W["建立 Worktree 與分支"]
W --> A["Agent 實作"]
A --> R["Annotate AI Diff 審查"]
R --> P["Push 並建立 PR"]
P --> C["Checks 與團隊 Review"]
C -->|"失敗"| F["Fix broken checks"]
F --> A
C -->|"通過"| M["合併並回寫狀態"]如何閱讀此圖:由左至右是一個工作項目的完整生命週期。Checks 失敗時回到 Agent 修正,形成迴圈;只有 Checks 與人工 Review 都通過才進入合併。
15.1 Git Worktree 與分支策略
概念說明
建立 Workspace 時,Orca 會從 Workspace 名稱推導分支名稱;若從 PR、Issue 或 MR 建立,則依該工作項目推導。Linear Issue 會優先使用 Linear 自己提供的分支名稱,讓 Linear 能自動關聯 PR。
| 設定或入口 | 位置 | 用途 |
|---|---|---|
| 自訂分支名稱 | 建立 Workspace 時 Advanced → Branch name | 覆寫推導的分支名稱;Workspace 綁定工作項目時此欄隱藏 |
| 預設名稱前綴 | Settings → General | 新 Worktree 名稱前綴 |
| Default base ref | Settings → Git | 新 Worktree 預設從哪個 ref 開分支 |
| Commit signing | Settings → Git | 簽署 commit |
| Auto-Rename Branch From Work | Settings → Git | 依工作內容自動重新命名分支 |
| GitHub API Budget | Settings → Git | 檢視 GitHub API 配額狀況 |
| CLI 指定分支 | orca worktree create --branch <name>(v1.4.244 新增) | 自動化腳本精確控制分支 |
建議的企業分支命名規範(教學示例)
| 類型 | 格式 | 範例 |
|---|---|---|
| 功能 | feat/<工作項目>-<簡述> | feat/PAY-231-charge-retry |
| 修正 | fix/<工作項目>-<簡述> | fix/ENG-88-null-session |
| 探索或比稿 | spike/<主題>-<agent> | spike/cache-layer-codex |
| Linear | 直接採用 Linear 建議名稱 | jane/eng-123-add-sso |
範例:以 CLI 建立指定分支的 Worktree 並啟動 Agent
orca worktree create --repo path:/srv/repos/payments \
--name pay-231-retry --branch feat/PAY-231-charge-retry \
--agent claude-code --prompt "閱讀 docs/payment.md 後,為 PaymentClient.charge 加入逾時重試;先列計畫,不要修改程式。" --json範例:在終端機確認 Worktree 與分支對應
git worktree list
git for-each-ref --format="%(refname:short) %(upstream:short)" refs/heads/feat/⚠️ 注意事項:同一分支只能被一個 Worktree checkout,這是 git 的限制。若建立時出現分支已被使用的錯誤,先用 git worktree list 找出佔用的 Worktree。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 分支名稱符合規範 | git -C <worktree> branch --show-current | 符合團隊格式 | 未 push 前可在 Orca 重新命名或 git branch -m |
| base 正確 | git merge-base HEAD origin/main 與預期比對 | 從正確 base 分出 | 檢查 Settings → Git 的 Default base ref |
| 一分支一 Worktree | git worktree list | 無重複分支 | 移除過期 Worktree 後 git worktree prune |
15.2 GitHub Hosted Reviews Issues 與 Actions
概念說明
Orca 的 GitHub 整合透過 gh CLI 運作,也可在 Settings → Integrations → GitHub 以 OAuth 連線。連線後,Worktree 側邊欄會顯示連結 PR 的狀態,Checks 面板呈現 CI、Review 留言與合併動作。
| 功能 | 說明 |
|---|---|
| PR 狀態 | 側邊欄顯示;可 Open review page in browser 或在 Orca 內建瀏覽器開啟 |
| PR 動作選單 | 複製連結、關閉、重新開啟;Draft 可 Mark ready for review |
| Checks 分頁 | CI 結果;GitHub Actions 失敗顯示紅色晶片並可行內看 log |
| Review 留言 | 新到舊分組顯示;可回覆串中任一則;支援 8 種 GitHub reactions |
| Fix broken checks | 把失敗的 Checks 交給 Agent 修正 |
| Auto-merge | 依 repo 設定提供 Squash、merge commit、Rebase;有 merge queue 時為 Merge when ready;Draft、已關閉、衝突或不穩定 PR 不顯示 |
| Stacked PRs | v1.4.180 起,僅 GitHub;顯示 Stack 地圖,Merge through #N 為原子操作,任一失敗即整體不合併 |
| Issues 抽屜 | 含 Activity 時間軸;從 Issue/PR 建立 Worktree 會開啟 composer |
| Tasks | GitHub Projects 的 Roadmap 與 Board 看板(拖曳會回寫狀態,v1.4.223) |
| 多個連結項目 | v1.4.224 起一個 Workspace 可連結多個 PR、MR、Task;Edit Worktree Details → Linked work,或 orca reference |
操作步驟:從 Issue 到合併
- 開啟 Issues 抽屜,選擇 Issue,點建立 Worktree;在 composer 補充 Prompt 並選擇 Agent。
- Agent 完成後依第十四章審查、commit、push,並建立 PR。
- 在 Checks 分頁確認 CI;失敗時展開紅色晶片看 log,判斷是程式問題還是環境問題。
- 確認是程式問題後點 Fix broken checks;Agent 修正後重新審查 Diff 再 push。
- 在 Checks 面板回覆團隊 Review 留言。
- 全部通過後使用 Auto-merge 或 Merge when ready。
範例 Prompt:Fix broken checks 前的補充指示
CI 的 test (ubuntu-latest) 失敗。請:
1. 先閱讀失敗 log,判斷根因並用三句話說明,不要先修改程式。
2. 只修正與本 PR 相關的原因;若是 flaky 或環境問題,停止並回報,不要修改測試讓它跳過。
3. 不得刪除或 skip 任何測試,不得修改 .github/workflows/。
4. 修正後在本機執行 pnpm test 並貼上完整輸出。🧑⚖️ 人工 Review 要點
- Agent 的根因說明與 CI log 一致
- Diff 中沒有
.skip、xit、@Ignore或放寬斷言等「讓測試變綠」的手法 - 沒有修改 CI workflow、lint 規則或測試門檻
- 修正後重新跑的是同一組失敗的 Checks
範例:用 CLI 連結多個工作項目
orca reference add --worktree active --github-pr 412 --json
orca reference list --worktree active --json⚠️ 注意事項:Stacked PRs 的 Merge through 會一次合併多個 PR,合併前務必逐一確認每個 PR 都已審查;它是原子操作,失敗時不會留下半合併狀態,但成功時影響範圍大。
✅ 驗證方式
執行:
gh auth status gh pr view --json number,state,isDraft,mergeStateStatus,statusCheckRollup --jq "{number,state,isDraft,mergeStateStatus}"預期輸出(示意):
✓ Logged in to github.com account jane-lin (keyring) {"isDraft":false,"mergeStateStatus":"CLEAN","number":412,"state":"OPEN"}判讀:Orca 側邊欄顯示的 PR 狀態應與
gh pr view一致;mergeStateStatus不是CLEAN時 Auto-merge 可能不顯示,屬預期行為。
15.3 Linear 整合
概念說明
在 Settings → Integrations → Linear 貼上 Linear 個人 API token 並選擇團隊後,Tasks 抽屜即可瀏覽、建立、編輯 Linear Issue,並直接從 Issue 開 Worktree。
| 功能 | 說明 |
|---|---|
| 抽屜檢視 | 合併顯示;Has Workspace 模式只看已有 Workspace 的 Issue |
| 從 Issue 開 Worktree | composer 預填,分支採用 Linear 建議名稱;可 Copy suggested branch name |
| 連結既有 Worktree | Edit Worktree Details → Issue 欄(GitHub 與 Linear 共用) |
| 編輯欄位 | 狀態、指派、優先度、標籤、估點 |
| 圖片 | Issue 內圖片會一併放入 Agent Prompt |
| 使用體驗 | 草稿於工作階段內保留、Load more 分頁、版面記憶、每個 repo 記住上次的來源 |
| 狀態同步 | 依團隊個別開啟(opt-in) |
| CLI 與 Skill | orca linear ... 指令與 orca-linear skill,讓 Agent 讀寫 Issue |
📌 查證狀態:官方文件明確記載|來源:Linear、CLI reference
範例:Agent 透過 CLI 讀取與更新 Linear
orca linear issue --current --full --json
orca linear status set --current --to "In Progress" --json
orca linear comment add --current --body "已完成實作並開 PR #412,待 Review。" --json
orca linear list-issues --team ENG --state started --assignee me --json
orca linear save-issue ENG-123 --state "In Progress" --assignee me --json範例 Prompt:讓 Agent 以 Linear Issue 為需求來源
使用 orca-linear skill 讀取目前 Worktree 連結的 Issue(含留言與圖片)。
1. 先把驗收條件整理成核對清單,不要修改程式。
2. 我確認後再實作;完成後執行測試並貼上輸出。
3. 只能把狀態改為 In Review 並留言附上 PR 連結;不得關閉 Issue、不得修改指派或優先度。🧑⚖️ 人工 Review 要點
- Agent 整理的驗收條件與 Issue 原文一致,沒有自行增加需求
- Agent 對 Linear 的寫入動作只限於 Prompt 允許的範圍
- Linear 上的留言不含內部主機、帳號或程式碼片段等機敏資訊
⚠️ 注意事項:Linear API token 擁有與你個人帳號相同的權限,Agent 透過 CLI 呼叫時也是以你的身分寫入。企業環境應以 Prompt 與 Agent 權限設定限制寫入動作,並啟用狀態同步前先與團隊確認工作流程。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 連線成功 | Tasks 抽屜切到 Linear | 列出所選團隊的 Issue | 重新產生 token 並確認已勾選團隊 |
| 分支名稱 | 從 Issue 建 Worktree 後 git branch --show-current | 與 Linear 建議名稱相同 | 確認未在 Advanced 覆寫 |
| CLI 可用 | orca linear issue --current --json | 回傳目前連結的 Issue | 先在 Edit Worktree Details 連結 Issue |
| 寫入可追溯 | 在 Linear 查看 Issue 活動紀錄 | 顯示預期的狀態與留言變更 | 檢查 Agent 是否超出 Prompt 範圍 |
15.4 Jira 整合
概念說明
從 Tasks → 來源選擇器 Jira → Connect Jira 連線,支援 Jira Cloud 與自架 Server/Data Center,且可同時連多個站台。
| 項目 | Jira Cloud | Jira Server/Data Center |
|---|---|---|
| 位址 | 站台 URL(例如 https://acme.atlassian.net) | 自架 base URL |
| 認證 | Atlassian Email + API token(id.atlassian.com → Security → API tokens) | 建議 Personal Access Token;或帳號密碼 |
| 憑證儲存 | 加密存於作業系統 keychain | 同左 |
| 功能 | 說明 |
|---|---|
| 多站台 | 站台選擇器含 All sites |
| 搜尋 | 純文字或 JQL;像 ABC-1 的查詢先做精確查找;JQL 回 400 時改用文字搜尋 |
| 編輯 | 狀態轉換、優先度、指派、自訂欄位、留言;草稿保留 |
| 建立 | 指派選擇 Automatic/me/搜尋使用者 |
| 從 URL 建 Worktree | 在建立名稱欄貼上 /browse/ABC-123 URL,或切換到 Jira 搜尋 |
| 卡片 | 顯示 View on Jira |
| 隱藏 | 不使用時可在 Settings → Tasks 隱藏 Jira |
版本演進:v1.4.221 加入純文字搜尋;v1.4.229 加入規劃功能(清單與看板、Sprint、JQL、我的最愛、CLI 讀寫);v1.4.239 加入使用者選擇器。
範例:常用 JQL
project = PAY AND assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC
project = PAY AND sprint in openSprints() AND labels = ai-ready範例 Prompt:以 Jira Issue 為需求
本 Worktree 對應 Jira PAY-231。請依 Issue 描述與驗收條件實作:
1. 先列出你理解的驗收條件與不確定之處,等我確認。
2. 不得修改 Jira 上的任何欄位;狀態轉換由我在 Orca 中操作。
3. 完成後提供 commit message 草稿,最後一行為 Refs: PAY-231。🧑⚖️ 人工 Review 要點
- 實作範圍對應 Issue 驗收條件,沒有夾帶其他 Issue 的工作
- commit 與 PR 標題含 Jira key,讓 Jira 的開發面板能關聯
- Jira 狀態轉換由人執行,與 PR 狀態一致
⚠️ 注意事項:v1.4.229 release notes 提到 Jira CLI 讀寫,但本手冊查證所用的 CLI reference 快照未列出 Jira 指令。使用前請以 orca --help 確認目前版本的實際指令。
📌 查證狀態:依官方說明延伸(教學推論)——Jira CLI 指令名稱未在 CLI reference 記載|來源:CLI reference、v1.4.229
✅ 驗證方式
執行(以 Jira Cloud 為例,驗證 token 本身有效,與 Orca 無關):
curl -s -u "jane.lin@example.com:$JIRA_API_TOKEN" \ "https://acme.atlassian.net/rest/api/3/myself" | jq -r ".displayName"預期輸出(示意):
Jane Lin判讀:curl 成功但 Orca 連線失敗時,檢查站台 URL 是否多了路徑;curl 回 401 代表 token 或 Email 錯誤。在 Orca 中搜尋
PAY-231應精確找到該 Issue。
15.5 GitLab Azure DevOps 與 Bitbucket 現況
Orca README 的標語是「GitHub & Linear, Native」,Settings → Integrations 文件列出的也只有 GitHub、Linear 與 Bitbucket。其他平台的支援散見於文件與 release notes,程度差異很大。下表只列有來源的事實;未記載者明確標示「文件未記載」,不代表一定不支援,請以目前版本實測。
| 平台 | 已記載支援 | 已記載不支援或限制 | 文件未記載 |
|---|---|---|---|
| GitLab | MR 與 Issue 走相同 Worktree Review 流程;Issues 抽屜列出專案 Issue 並可篩選指派給我;Draft MR 可 Mark ready 或 Close;Unlink MR 與連結其他 MR;Checks 顯示 bridge 與子 pipeline job 與 trace;建立時連結 MR;CLI --gitlab-issue、--gitlab-mr;Jump Palette !123;SSH Workspace 走 GITLAB_HOST | Draft MR 不可合併或 Auto-merge;不支援 Stacked PRs 與 reactions | Settings → Integrations 的 GitLab 認證設定方式 |
| Bitbucket Cloud | Settings → Integrations 內連線(Email 與 API token,或 Access token),儲存前驗證;可建立 PR;ORCA_BITBUCKET_* 環境變數優先;辨識 ssh.bitbucket.org remote | 無 Draft(Draft 開關隱藏);不支援 Stacked PRs | Bitbucket Server/Data Center |
| Azure DevOps | PR 會出現在 Worktree 側邊欄與 Checks 面板;建立流程會檢查遠端衝突;支援 on-prem Server 的專案層級 base | — | 連線設定、建立 PR、Work items 抽屜 |
| Gitea | PR 與其他平台一同顯示 | — | 連線設定與其他功能 |
📌 查證狀態:官方文件明確記載|來源:GitHub(含 GitLab、Bitbucket、Azure DevOps 段落)、Commit & push、Settings、CLI reference
相關 release notes
| 版本 | 平台 | 內容 |
|---|---|---|
| v1.4.176 | Azure DevOps | 修正 -preview api-version 重試,以及 on-prem Server 專案層級 base |
| v1.4.183 | Bitbucket | 新增連線與建立 PR |
| v1.4.193 | GitLab | 修正 Checks 側邊欄的 MR 選單 |
| v1.4.217 | Gitea | 修正 PR 查詢重新整理 |
| v1.4.223 | GitLab | 修正 SSH 環境下 MR 與 Issue 動作連到正確伺服器 |
| v1.4.240、v1.4.244 | Bitbucket | 辨識 ssh.bitbucket.org remote |
📌 查證狀態:官方文件明確記載|來源:v1.4.176、v1.4.183、v1.4.193、v1.4.217、v1.4.223、v1.4.240、v1.4.244
範例:GitLab 從 Issue 或 MR 建立 Worktree
orca worktree create --repo path:/srv/repos/billing --gitlab-issue 42 --json
orca worktree create --repo path:/srv/repos/billing --gitlab-mr '!77' --json
orca worktree create --repo path:/srv/repos/billing \
--gitlab-mr https://gitlab.acme.internal/platform/billing/-/merge_requests/77 --jsonCLI 接受編號、'#42'/'!77' 形式,以及含自架網域與巢狀群組的完整 URL。
範例:Bitbucket 以環境變數提供憑證(Remote Orca Server 情境)
# 在執行 Orca Server 的主機上設定;設定後 Orca UI 的 Connect/Disconnect 會隱藏
# 官方文件只記載前綴 ORCA_BITBUCKET_*,完整變數名稱請向 Orca 官方確認後填入
export ORCA_BITBUCKET_<VARIABLE>="<從密碼管理工具注入>"
env | grep "^ORCA_BITBUCKET_" | cut -d= -f1 # 只列名稱,不印出值📌 查證狀態:官方文件明確記載前綴
ORCA_BITBUCKET_*優先於已儲存憑證、會隱藏 Connect/Disconnect,且 Remote Orca Server 應在伺服器端設定;完整變數名稱文件未記載|來源:Settings、GitHub
企業導入建議(教學推論)
- GitHub 為主的團隊:可完整使用本章所有功能。
- GitLab 團隊:日常 MR 審查與 CI 檢視可用;導入前實測自架 GitLab 的認證方式,並接受無 Stacked PRs。
- Bitbucket Cloud 團隊:可建立 PR,但需調整「先開 Draft PR」的流程;Server/Data Center 需先 PoC。
- Azure DevOps 團隊:目前文件只記載 PR 顯示與衝突檢查,建議以本機 git 搭配 Azure DevOps 網頁完成 PR 建立與合併,並在 PoC 時實測。
⚠️ 舊版手冊曾引用特定原始碼路徑說明 GitLab 支援方式,該說法未經查證,本版不採用。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| GitLab MR 顯示 | 建立 --gitlab-mr Worktree 後看側邊欄 | 顯示 MR 狀態與 Checks pipeline | 確認 remote 主機與 GITLAB_HOST |
| Bitbucket 連線 | Settings → Integrations → Bitbucket | 顯示已連線;或因環境變數而隱藏按鈕 | 檢查 token 權限與 ssh.bitbucket.org remote 是否需升到 v1.4.240 以上 |
| Azure DevOps PR | push 後看 Worktree 側邊欄 | 出現 PR 狀態 | 屬文件未記載範圍,回報並改用網頁 |
| 版本 | Orca 關於畫面 | v1.4.244 或以上 | 舊版缺少上述修正 |
15.6 GitHub 錯誤排除
快速分類
| 症狀 | 可能原因 | 處理 |
|---|---|---|
| rate limit 或 403 並提到 rate | 配額用盡 | 等待重置;檢查是否有大量 Worktree 同時輪詢 |
| 401 或 auth 錯誤 | gh 未登入或 Token 過期 | gh auth login |
| 403 無 rate 字樣 | 權限不足或組織 SAML SSO 未授權 | 補 scope,或在 GitHub 授權 Token 給組織 |
| 404 | 私有 repo 無權限或 remote 錯誤 | 確認帳號可存取、git remote -v |
| 無法連線 | 網路、代理、防火牆 | 檢查企業 Proxy 設定 |
| 找不到 gh | 未安裝或不在 PATH | 安裝 gh 並重開 Orca |
配額桶:REST core 每小時 5,000;GraphQL 每小時 5,000 點;Search 每分鐘 30 次。rate limit 造成的 403 之後,Orca 的斷路器會短暫停止新的 gh 呼叫,避免雪上加霜。
關鍵觀念
gh api rate_limit本身不耗配額,因此可能看起來比實際健康;真正的檢查是做一次實際呼叫:gh api user -i,看回應 header。- 各來源說法不一時的信任順序:面板上的錯誤 > 真實 CLI 呼叫 > Settings → Git → GitHub API Budget。
- 環境變數
GITHUB_TOKEN/GH_TOKEN會覆蓋gh的登入,是最常見的陷阱。 - 認證是以主機為單位:SSH 或遠端主機上也要執行
gh auth login。 - 需要的 scope:
repo、read:org、project。GitHub Enterprise Server 用gh auth login --hostname <host>。 - GitHub API Budget 是 GitHub 配額,與 AI Provider 用量無關,不要混淆。
範例:完整診斷流程
gh --version
gh auth status
gh api rate_limit --jq '.resources | {core, graphql, search}'
gh api user -i | grep -i "x-ratelimit"
env | grep -E "^(GITHUB_TOKEN|GH_TOKEN)="範例:清除環境變數陷阱並重新登入
unset GITHUB_TOKEN GH_TOKEN
gh auth logout -h github.com
gh auth login -h github.com --scopes "repo,read:org,project"Windows PowerShell 對應:
Remove-Item Env:GITHUB_TOKEN, Env:GH_TOKEN -ErrorAction SilentlyContinue
gh auth logout -h github.com
gh auth login -h github.com --scopes "repo,read:org,project"若環境變數設定在使用者層級(例如系統環境變數或 shell 設定檔),需從來源移除後重新啟動 Orca。仍無法解決時,從 Help → Open Logs 取得記錄檔。
📌 查證狀態:官方文件明確記載|來源:GitHub errors
✅ 驗證方式
執行:
gh auth status gh api user -i | grep -iE "^HTTP|x-ratelimit-remaining|x-oauth-scopes"預期輸出(示意):
✓ Logged in to github.com account jane-lin (keyring) HTTP/2.0 200 OK X-Oauth-Scopes: project, read:org, repo X-Ratelimit-Remaining: 4870判讀:狀態 200 且 scope 含
repo、read:org、project代表認證正常;gh auth status顯示(GITHUB_TOKEN)而非(keyring)代表環境變數仍在覆蓋;回到 Orca 重新整理 Checks,面板錯誤應消失。
15.7 本章 Review 與驗證清單
- 團隊分支命名規範已定義,並知道 Linear Issue 會採用 Linear 建議名稱
- 已用
orca worktree create --branch或 Advanced → Branch name 建立過指定分支 - 已完成一次 Issue → Worktree → PR → Checks → 合併的完整流程
- Fix broken checks 的 Prompt 已明定不得 skip 測試或修改 CI
- 了解 Stacked PRs 僅限 GitHub,且 Merge through 為原子操作
- Linear、Jira 的 Agent 寫入範圍已在 Prompt 與團隊規範中限制
- Jira Cloud 與 Server/Data Center 的認證方式與團隊環境相符
- 已依 15.5 的表格判斷團隊託管平台的支援程度,並對「文件未記載」項目完成 PoC
- 能分辨 GitHub API Budget 與 AI Provider 用量
- 已確認環境中沒有
GITHUB_TOKEN/GH_TOKEN覆蓋gh登入
第十六章 Orca CLI 與 Orchestration
本章把 Orca 從「圖形介面工具」提升為「可被腳本與 Agent 驅動的執行平台」。讀完本章,你應該能夠:在任何終端機呼叫 orca 指令操作正在執行的 Orca、用一張速查表找到正確的指令類別、讓一個 Coordinator 監督多個 Worker 完成任務並由人工驗收、安裝與治理 Orca Skills,並用 Worktree Checkpoints 讓人類隨時掌握 Agent 進度。
📌 查證狀態:官方文件明確記載|來源:Orca CLI overview、Orca CLI reference、Orchestration
本章與舊版的主要差異(v1.4.150 → v1.4.244)
| 項目 | 舊版手冊描述 | v1.4.244 現況 |
|---|---|---|
| Orchestration 入口 | 泛稱「編排任務分派順序」 | 改為 Run、Task、Dispatch、Message、Decision gate 五元素模型;orca orchestration run 與 run-stop 已退役 |
| Worktree Checkpoints | 誤解為「可回到中繼狀態的快照」 | 實為 Worktree 上的文字狀態註記(comment)與卡片狀態,不是 Git 快照 |
| Skills | 未提及 | 官方提供 7 個可安裝 Skill,採「Hybrid stub」設計,旗標以執行中 CLI 為準 |
Windows 上的 orca | 未說明 | v1.4.219 起改為原生程式,不再需要 Visual C++ Redistributable |
SSH 主機上的 orca | 未說明 | v1.4.230 起預設僅能控制該主機自身,需逐主機開啟「Allow this host’s orca CLI to control Orca」 |
16.1 Orca CLI 安裝與驗證
概念說明
Orca CLI(指令名稱 orca)隨桌面版一起安裝,用來「從任何 Shell 操作一個正在執行的 Orca Runtime」。它不是獨立的雲端服務,也不是 Git 的替代品;它的價值在於讓腳本與 AI Agent 能以結構化(--json)方式完成原本要在 UI 上點擊的事情,例如建立 Worktree、讀寫終端機、開啟 Diff、驅動內建瀏覽器、排程自動化與多 Agent 協作。
| 特性 | 說明 | 對教學與治理的意義 |
|---|---|---|
| 隨 App 版本出貨 | CLI 與桌面版同版本,Orca 會把自己的 orca 放在終端機 PATH 最前面 | 腳本與 Agent 呼叫到的一定是「與執行中 App 相符」的 CLI,避免舊版全域安裝造成旗標不符 |
| 需要執行中的 Runtime | 大多數指令透過 Runtime 執行;orca skills 系列例外,不需 Runtime | 先以 orca status --json 確認連線,再執行其他指令 |
支援 --json | 輸出可被 jq、PowerShell ConvertFrom-Json 解析 | 自動化腳本一律加 --json,人工快速檢查才用一般輸出 |
| 支援 Selector | 以 active、path:、branch:、issue:、id: 指定目標 | 腳本不需記長 ID,也不必解析 UI 文字 |
📌 查證狀態:官方文件明確記載(註冊位置兩頁說法不同:Overview 與 Settings 參考頁寫 Settings → General → Orca CLI,CLI reference 寫 Settings → Experimental → CLI;以 v1.4.244 的 Settings 參考頁為準,若找不到請用 Settings 搜尋「CLI」)|來源:Orca CLI overview、Settings reference
操作步驟
- 開啟 Orca 桌面版,進入 Settings → General → Orca CLI,點選註冊(Register)把
orca加入系統 PATH。 - 關閉並重新開啟一個「新的」終端機視窗(舊視窗不會讀到新的 PATH)。
- 確認指令可被找到,並確認 CLI 能連上執行中的 Orca。
- 若 Orca 尚未啟動,可直接用
orca open --json開啟後再查狀態。 - (選用)讓 Agent 學會使用 CLI:安裝
orca-cliSkill(詳見 16.4)。
範例:macOS/Linux(bash/zsh)
# 1. 確認 orca 在 PATH 上
command -v orca
# 2. 確認可連上執行中的 Orca Runtime
orca status --json
# 3. 若 Orca 尚未執行,先開啟再查
orca open --json
orca status --json
# 4. 讓 Agent 取得與目前版本相符的 CLI 指南
orca skills install --skill orca-cli
orca skills get orca-cli範例:Windows(PowerShell)
# 1. 確認 orca 在 PATH 上(v1.4.219 起為原生執行檔)
Get-Command orca | Select-Object Name, Source
# 2. 以物件方式解析 JSON 結果
$status = orca status --json | ConvertFrom-Json
$status | Format-List
# 3. 若 Orca 尚未執行
orca open --json💡 小技巧:在 Linux 上若同時安裝了其他也叫 orca 的程式(例如螢幕閱讀器),官方 Skill 的解析順序是 ORCA_CLI_COMMAND 環境變數 → orca-dev → Linux 的 orca-ide → orca。企業標準映像檔可以統一設定 ORCA_CLI_COMMAND,避免 Agent 呼叫到同名但無關的程式。
📌 查證狀態:官方文件明確記載|來源:Orca skills registry & MCP
✅ 驗證方式
執行:
command -v orca && orca status --json預期輸出(示意,欄位依版本可能不同):
/usr/local/bin/orca {"ok":true, ... "version":"1.4.244", ...}判讀:
command -v沒有輸出:CLI 尚未註冊,或終端機是註冊前開啟的,請重開終端機或回到 Settings 重新註冊。status回報無法連線:Orca 未執行,執行orca open --json;若在 SSH 主機上執行,請看 18.2「SSH 主機上的 orca CLI」權限說明。- 版本號與桌面版「About」不同:表示呼叫到舊的全域安裝,請用
command -v orca(或 PowerShellGet-Command orca)找出實際路徑並移除舊版。
企業治理考量
| 面向 | 風險 | 建議做法 |
|---|---|---|
| 權限 | CLI 能建立/刪除 Worktree、送字到任何終端機 | Agent 預設權限模式(第七章 7.2)維持 Manual 或 Auto,不在生產主機使用 Yolo |
| 稽核 | --json 指令若由 Agent 執行,人類不易察覺 | 要求 Agent 把關鍵操作寫入 Worktree Checkpoint(16.5),並保留 Session History(第九章) |
| 遠端 | SSH 主機上的 Agent 若能控制整個 Orca,影響範圍擴大 | 維持「Allow this host’s orca CLI to control Orca」預設關閉,只對受信任主機開啟 |
| 版本一致 | 腳本使用的旗標隨 App 更新而演進 | 腳本與 Agent 一律以 orca skills get <topic> 取得版本相符的說明,不靠記憶 |
16.2 CLI 指令分類速查
概念說明
Orca CLI 指令多、更新快。本節把官方 CLI reference 依「你要做的事」分類,讓讀者先找到正確類別,再到官方參考頁查完整旗標。表格中的旗標若有多個可選值,以「、」分隔(例如 --setup 可為 run、skip、inherit)。
📌 查證狀態:官方文件明確記載|來源:Orca CLI reference、Orchestration、Scheduled automations、Computer use
16.2.1 Selector 速查
| Selector 寫法 | 意義 | 適用情境 |
|---|---|---|
active 或 current | 由目前 Shell 所在目錄或終端機推斷所屬 Worktree | 在 Worktree 內互動操作 |
id:<repoId> | 以 Repository ID 指定 | 腳本操作特定 Repo |
path:/abs/path | 以絕對路徑指定 Worktree | 腳本在 Worktree 外執行 |
branch:feature-name | 以分支名稱指定 | 依分支找 Worktree |
issue:123 | 以連結的 Issue 編號指定 | 依工單找 Worktree |
name:api | 以 Worktree 名稱指定 | References 等指令常用 |
id:<repoId>::<absolute-worktree-path> | 遠端 Runtime 的完整伺服器端 Selector | 遠端主機,避免本機路徑不存在 |
主機選擇:先執行 orca host list --json 取得可用主機,再用 --host local、--host ssh:<target-id> 或 --environment <server-name> 指定目標。
16.2.2 指令分類總表
| 類別 | 代表指令 | 主要用途 | 關鍵旗標或備註 |
|---|---|---|---|
| Runtime | orca open、orca status | 開啟 Orca、檢查連線 | 一律先跑 status --json |
| 無頭伺服器 | orca serve | 不開視窗啟動 Runtime | --port、--pairing-address、--mobile-pairing、--supervise;詳見 18.5 |
| 伺服器服務化 | orca serve service install、status、uninstall | 安裝為 LaunchAgent 或 systemd user unit | Windows 尚不支援;install 支援 --dry-run |
| 主機 | orca host list | 列出本機、SSH 目標、已配對伺服器 | 取得 --host、--environment 的值 |
| Repository | orca repo list、add、show、set-base-ref、search-refs | 管理 Repo 與 Base ref | 大量建 Worktree 前先 set-base-ref |
| Session 搜尋 | orca search | 搜尋 Agent 對話紀錄 | --query、--scope、--agent、--since、--sort、--index-status |
| Worktree | orca worktree list、ps、current、show、create、set、rm | 建立、查詢、標註、刪除 Worktree | create 支援 --agent、--prompt、--setup、--branch、--parent-worktree、--no-parent |
| Worktree 連結 | orca worktree create 或 set 搭配 --pr、--gitlab-issue、--gitlab-mr | 連結 PR、Issue、MR | set 時傳 null 可清除單一連結 |
| Agent 啟動 | orca agent launch | 在既有 Workspace 啟動 Agent | --agent、--model、--effort、--focus、--retry-launch |
| References | orca reference list、add、remove、find | 一個 Workspace 連結多個 PR 或工單 | 寫入需完整 URL;find 接受 URL 或 STA-1234 這類 key |
| 終端機 | orca terminal list、show、read、send、wait、create、split、rename、switch、close | 讀寫與管理終端機 | read --screen 讀目前畫面;wait --for tui-idle |
| 檔案 | orca file open、diff、open-changed | 在 Orca 開啟檔案與 Diff | 預設不搶焦點,需 --focus |
| 內建瀏覽器 | orca goto、snapshot、click、fill、wait、screenshot | 驅動 Worktree 專屬瀏覽器 | 採 snapshot、act、re-snapshot 循環 |
| 瀏覽器分頁與擷取 | orca tab list、create、switch、orca capture start、orca console、orca network、orca full-screenshot、orca pdf | 分頁、主控台、網路紀錄 | orca tab profile 管理瀏覽器 Profile |
| 裝置模擬 | orca set device | 切換響應式裝置尺寸 | 例:--name "iPhone 12" |
| 桌面 Computer Use | orca computer permissions、list-apps、get-app-state、click、set-value 等 | 操作原生桌面 App | Beta;詳見第十七章 |
| iOS 模擬器 | orca emulator list、attach、tap、type、gesture、rotate、kill、shutdown | 驅動 iOS Simulator | 座標為 0 到 1 的正規化值 |
| Linear | orca linear issue、search、list-issues、save-issue、comment add 等 | 讀寫 Linear 工單 | 搭配 orca-linear Skill |
| Skills | orca skills list、get、install、update、installed、share | 取得版本相符指南、安裝 Skill | 不需 Runtime;詳見 16.4 |
| 帳號(主機端) | orca account list、orca account add | 在無頭主機登入 Claude 或 Codex | 在擁有帳號的主機上執行 |
| Artifacts | orca artifacts share、update、unshare、list、delete | 分享 HTML 或 Markdown 公開連結 | 預設關閉,需人類於 Settings 開啟 |
| 排程自動化 | orca automations list、create、show、edit、run、runs、remove | 排程 Prompt | 詳見第十七章 |
| 受管伺服器與遠端環境 | orca environment list、status、update、rollback、recover、stop、forget、add、rm | 管理 SSH 受管伺服器與配對 Runtime | stop、forget 需 --yes |
| Agent 狀態 Hook | orca agent hooks status、on、off | 切換狀態 Hook | 即時生效 |
| Orchestration | orca orchestration run-create、task-create、worker-start、check、send、ask、gate-create 等 | 監督式多 Agent | 需於 Settings → Experimental 開啟;詳見 16.3 |
📌 查證狀態:依官方說明延伸(教學推論)— Release notes 另提到
orca ports(v1.4.240)與orca speech openai-key set(v1.4.237),但 v1.4.244 的 CLI reference 頁尚未收錄完整說明,本書不示範其旗標;需要時請執行orca --help或orca skills get orca-cli確認|來源:Orca Releases
範例:一支「開工腳本」——為工單建立 Worktree 並啟動 Agent
#!/usr/bin/env bash
set -euo pipefail
REPO_ID="$(orca repo list --json | jq -r '.result[0].id // .repos[0].id // empty')"
if [ -z "$REPO_ID" ]; then
echo "找不到 Repository,請先 orca repo add" >&2
exit 1
fi
# 確保新 Worktree 從 origin/main 分支
orca repo set-base-ref --repo "id:${REPO_ID}" --ref origin/main --json
# 依 GitHub Issue 123 建立 Worktree,啟動 Codex 並送出初始任務
orca worktree create \
--repo "id:${REPO_ID}" \
--name fix-login-123 \
--issue 123 \
--agent codex \
--setup run \
--prompt "閱讀 Issue #123,先寫出重現步驟與失敗測試,再提出修正;完成後回報測試指令與結果" \
--json
# 列出目前所有 Worktree 與其狀態
orca worktree ps --json📌 查證狀態:教學示例(非官方)— 指令與旗標取自官方 CLI reference;
jq篩選路徑為示意,實際 JSON 欄位請先以orca repo list --json檢視後調整|來源:Orca CLI reference
範例:PowerShell 版本
$repos = orca repo list --json | ConvertFrom-Json
$repos | ConvertTo-Json -Depth 5 # 先看實際欄位,再決定如何取 ID
orca worktree create --name fix-login-123 --agent codex --setup run `
--prompt "閱讀 Issue #123,先寫出失敗測試再修正,完成後回報測試指令與結果" --json
orca worktree ps --json | ConvertFrom-Json | Format-List範例:讀取終端機再決定是否送出輸入
# 先讀目前畫面(不是整段串流),確認 Agent 在等什麼
orca terminal read --worktree active --screen --json
# 等待 TUI 閒置最多 5 分鐘
orca terminal wait --for tui-idle --timeout-ms 300000 --json
# 確認後才送出
orca terminal send --text "continue" --enter --json⚠️ 注意事項
- 終端機 Handle 屬於 Runtime 範圍:Orca 重啟或出現 stale handle 錯誤時,重新執行
orca terminal list --json取得新 Handle。 terminal list回傳的hostScope若未包含某主機,代表該主機狀態「無法驗證」,不可直接判定終端機已結束。--screen與--cursor互斥;長輸出請用nextCursor分段讀取。orca worktree rm --force會移除工作目錄,腳本中務必先確認 Selector 指向正確目標。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Base ref 已設定 | orca repo show --repo id:<repoId> --json | 回傳內容顯示 origin/main 為 Base ref | 重新執行 set-base-ref,確認遠端分支名稱正確 |
| Worktree 已建立 | orca worktree ps --json 與 git worktree list | 兩者皆出現 fix-login-123 | 查看 Orca 側邊欄建立進度列的錯誤訊息並按 Retry |
| Agent 已啟動 | orca terminal list --worktree branch:fix-login-123 --json | 至少一個終端機,標題或指令含 codex | 確認 Settings → Agents 已啟用該 Agent |
| 初始 Prompt 已送達 | orca terminal read --worktree branch:fix-login-123 --json | 輸出中可看到 Issue #123 相關文字 | 以 orca terminal send 補送,或改用 orca agent launch --prompt |
16.3 Orchestration 監督式多 Agent 流程
概念說明
當你只需要對一個正在觀察的 Agent 說一句話,用 orca terminal send 就夠了。當你需要「誰負責哪件事、做完沒有、結果在哪裡、卡住要問誰」都能被追蹤時,就該用 Orchestration。它是 Orca 的結構化多 Agent 層,由五個元素組成:
| 元素 | 定義 | 生活化比喻 |
|---|---|---|
| Run | 持久的命名空間與 Coordinator 收件匣;本身不排程、不放置 Worker | 一個專案群組與它的公用信箱 |
| Task | 有規格(spec)、相依性與狀態的工作項目;狀態為 pending、ready、dispatched、completed、failed、blocked | 看板上的一張卡片 |
| Dispatch | 某個 Task 在某個終端機上的「一次嘗試」;是 worker_done 與 heartbeat 的權威依據 | 一張派工單 |
| Message | 收件匣郵件,類型含 status、dispatch、worker_done、escalation、question、heartbeat | 工作群組訊息 |
| Decision gate | Coordinator 擁有的決策問題,未解決前阻擋 Task | 主管簽核關卡 |
📌 查證狀態:官方文件明確記載(Orchestration 為 Experimental 功能,需先於 Settings → Experimental 開啟;舊指令
orca orchestration run、run-stop、coordinator-start、coordinator-stop已退役,執行後只會回傳指向orca skills get orchestration --full的說明)|來源:Orchestration
何時用哪一種指令
| 需求 | 建議指令 | 理由 |
|---|---|---|
| 對眼前 Agent 補一句話 | orca terminal send | 最輕量,無追蹤需求 |
| Worker 必須回報完成、可提問、要被 Task ID 追蹤 | orca orchestration worker-start 或 dispatch --inject | 有完成權威與 Worker 合約 |
| 需要持久命名空間與監督迴圈 | run-create 加 Task 加 Worker | 官方建議流程 |
| 完整交接、不需監督 | orca worktree create --agent --prompt | 交給 Agent 自主完成 |
監督式流程的運作方式
sequenceDiagram
participant H as 人員或 Coordinator Agent
participant R as Orca Runtime
participant W1 as Worker A(Codex)
participant W2 as Worker B(Claude)
H->>R: run-create(建立 Run 與收件匣)
H->>R: task-create ×2(建立 Task)
H->>R: worker-start Task A
R->>W1: 注入 Preamble 與 taskId、dispatchId
H->>R: worker-start Task B
R->>W2: 注入 Preamble 與 taskId、dispatchId
W2->>R: ask(阻擋性提問)
R->>H: question
H->>R: 回覆答案
W1->>R: send worker_done(outcome succeeded)
W2->>R: send worker_done(outcome failed)
H->>R: check --wait 取得 Delivery
H->>H: 人工驗收 Diff 與測試
H->>R: check --ack(確認處理完畢)
H->>R: worker-release 或 retry如何閱讀此圖:由上而下是時間軸。Coordinator(可以是你自己在終端機操作,也可以是一個負責協調的 Agent)只透過 Runtime 與 Worker 溝通;Worker 啟動時會收到 Orca 注入的 Preamble(含 Task ID 與 Dispatch ID)。Worker 有問題用 ask 回到 Coordinator,而不是卡在本地 TUI;完成時一定送一次 worker_done。Coordinator 用 check --wait 收信,處理完才 --ack,因此任何一封信都不會因為當機而遺失。
16.3.1 實作範例:結帳流程 QA 的監督式分工
📌 查證狀態:教學示例(非官方)— 情境為虛構,所有指令與旗標取自官方 Orchestration 文件|來源:Orchestration
情境:電商網站的結帳流程要在發版前做行動版版面稽核。你擔任 Coordinator,派兩個 Worker:Worker A(Codex)稽核「帳單設定頁」,Worker B(Claude)稽核「購物車頁」,各自在獨立的子 Worktree 中修正並回報。
操作步驟
前置確認:Orca 正在執行、Orchestration 已在 Settings → Experimental 開啟,並在 Settings → Agent Orchestration 確認 Worker heartbeat 間隔(預設 5 分鐘,可設 1 到 60 分鐘或關閉;變更只套用到新派出的 Worker)。
orca status --json orca skills get orchestration --full > orchestration-guide.md # 保存本版完整指南供查閱建立 Run(命名空間與收件匣):
orca orchestration run-create \ --objective "發版前稽核結帳流程行動版版面並彙整阻擋問題" \ --json建立兩個 Task,規格寫清楚「範圍、完成定義、回報內容」:
orca orchestration task-create \ --task-title "Billing audit" \ --spec "稽核 src/app/settings/Billing.tsx 在 375px 寬度下的版面。只修改 src/app/settings/ 底下檔案。完成定義:npm test -- billing 全數通過,並附上修正前後截圖路徑。" \ --json orca orchestration task-create \ --task-title "Cart audit" \ --spec "稽核 src/app/cart/ 在 375px 寬度下的版面。不得修改共用元件 src/components/;若必須修改,先用 ask 詢問。完成定義:npm test -- cart 全數通過。" \ --json為每個 Task 啟動 Worker,各自放進新的子 Worktree 並執行 Setup:
orca orchestration worker-start \ --task <billingTaskId> \ --worktree new-child --name billing-audit \ --agent codex --setup run \ --json orca orchestration worker-start \ --task <cartTaskId> \ --worktree new-child --name cart-audit \ --agent claude --model <opaque-model-id> --effort high \ --setup run \ --json--model接受供應商的不透明模型 ID(Claude、Codex、Muse、Cursor、Antigravity、OpenCode),--effort必須搭配--model,兩者皆不可與--terminal併用。啟動回執中的launch.requested與launch.effective會顯示實際生效值。進入監督迴圈:等待完成、升級與提問。
orca orchestration check --wait \ --types worker_done,escalation,question \ --timeout-ms 900000 \ --json等待期間 CLI 每 15 秒向 stderr 輸出一行 JSON heartbeat,stdout 只放最終結果,因此可安全地把 stdout 導向
jq。處理 Delivery 中的每一封信後,再以
--ack確認並繼續等待下一批:orca orchestration check --ack <deliveryId> --wait \ --types worker_done,escalation,question \ --timeout-ms 900000 \ --jsonWorker 端(由 Agent 依 Preamble 自動執行)的完成回報長這樣:
orca orchestration send \ --type worker_done \ --subject "Completed billing audit" \ --body "修正 footer 在 375px 重疊;npm test -- billing 通過 42/42;無後續事項。" \ --task-id <taskId> \ --dispatch-id <dispatchId> \ --outcome succeeded \ --files-modified "src/app/settings/Billing.tsx" \ --jsonWorker B 若需要決策,會送出阻擋性提問;
--json時輸出單一 JSON 物件,Worker 可用jq -r .answer取得答案:orca orchestration ask \ --to <coordinatorHandle> \ --question "購物車按鈕溢出需改共用 Button 元件,還是只改 cart 頁面?" \ --options "shared,page-only" \ --timeout-ms 600000 \ --json對於影響範圍較大的決策,Coordinator 可建立 Decision gate,由人類簽核後才放行:
orca orchestration gate-create \ --task <cartTaskId> \ --question "是否將共用 Button 的修改合併到 Task 分支?" \ --options '["yes","no"]' \ --json # 人類審查後 orca orchestration gate-resolve --id <gateId> --resolution "no" --json驗收完成後釋放 Worker(會封存可檢視的輸出並只關閉該 Coordinator 擁有的終端機);需要除錯時改用 retain;失敗則明確重試:
orca orchestration worker-release --dispatch <dispatchId> --json orca orchestration worker-retain --dispatch <dispatchId> --json orca orchestration worker-start --task <taskId> --retry-of <dispatchId> \ --worktree current --agent codex --json--retry-of不會繼承原本的--on或 Worktree 位置,必須重新指定。
PowerShell 注意事項:群組位址必須加引號,例如:
orca orchestration send --to "@all" --subject "Heads up" --body "暫停派工,進行人工審查。" --json
orca orchestration send --to "@idle" --subject "Anyone free?" --json群組位址(@all、@idle、@claude、@codex、@opencode、@gemini、@droid、@grok、@cursor、@worktree:<id>)不可用於 worker_done 或 heartbeat。
16.3.2 人工驗收 worker_done 結果
worker_done 只是 Worker 的「自我宣稱」。企業流程中,Coordinator(尤其是人類)必須把宣稱轉換成證據。建議依下列順序驗收:
flowchart TD
A["收到 worker_done"] --> B{"outcome 是 succeeded?"}
B -- "否" --> C["worker-read 讀輸出<br/>判斷重試或改規格"]
B -- "是" --> D["比對 taskId 與 dispatchId<br/>dispatch-show"]
D --> E["git diff --stat<br/>比對 --files-modified"]
E --> F{"只改了允許範圍?"}
F -- "否" --> G["退回:task-update 設 blocked<br/>或 retry 並收斂規格"]
F -- "是" --> H["親自重跑測試指令"]
H --> I{"測試通過?"}
I -- "否" --> G
I -- "是" --> J["Diff Viewer 逐行審查<br/>第十四章"]
J --> K["check --ack 並 worker-release"]如何閱讀此圖:菱形是判斷點,任何一個「否」都導向退回或重試,只有全部通過才 --ack 並釋放 Worker。重點在 E 與 H:Worker 宣稱改了哪些檔、測試通過,人類要用自己的指令重新取得證據。
驗收指令範例
# 1. 看派工單與 Worker 收到的 Preamble(確認任務規格沒被誤解)
orca orchestration dispatch-show --task <taskId> --json
orca orchestration dispatch-show --task <taskId> --preamble --json
# 2. 讀取 Worker 最近輸出(release 之後仍可讀)
orca orchestration worker-read --dispatch <dispatchId> --limit 50 --json
# 3. 到 Worker 的 Worktree 實際比對變更範圍
WT_PATH="$(git worktree list --porcelain | awk '/^worktree /{p=$2} /branch .*billing-audit/{print p}')"
git -C "$WT_PATH" diff --stat origin/main...HEAD
git -C "$WT_PATH" status --short
# 4. 親自重跑完成定義中的測試
( cd "$WT_PATH" && npm test -- billing )
# 5. 在 Orca 中開啟變更檔的 Diff 以逐行審查
orca file open-changed --mode diff --worktree "path:${WT_PATH}" --focus --json✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 完成訊息屬於正確派工 | orca orchestration dispatch-show --task <taskId> --json | 目前 Dispatch ID 與 worker_done 中的 --dispatch-id 相同 | 屬於過期重試的回報,不可採納;重新檢查目前 Dispatch |
| 變更範圍符合規格 | git diff --stat origin/main...HEAD | 只出現 spec 允許的路徑,且與 --files-modified 一致 | 以 task-update --status blocked 標記並退回,或收斂 spec 後 retry |
| 測試真的通過 | 人類親自執行 spec 中的測試指令 | 測試數與 Worker 回報一致且全數通過 | 以實際輸出為準,退回 Worker 並附上失敗紀錄 |
| 收件匣已清空 | orca orchestration check --peek --json | 沒有未處理的 worker_done、question、escalation | 逐封處理後再 --ack;--peek 與 --all 不會消耗郵件 |
| Worker 終端機已釋放 | orca orchestration worker-show --dispatch <dispatchId> --json | 狀態顯示已釋放 | 回執為 release_pending 或 release_unknown 時依回執的復原動作處理,不要直接大範圍關閉終端機 |
| Task 狀態正確 | orca orchestration task-list --json | 已驗收 Task 為 completed,退回者為 blocked 或 failed | 用 task-update --id <taskId> --status ... 修正並附 --result 說明 |
16.3.3 讓 Agent 擔任 Coordinator
在大量分工時,可以讓一個 Agent 擔任 Coordinator,人類只在 Decision gate 與最終驗收介入。v1.4.218 起 Structured Chat 也能執行 Orchestration。
範例 Prompt
你是本次 Run 的 Coordinator。開始前請執行 `orca skills get orchestration --full`,只使用該指南列出的指令與旗標,不得憑記憶發明旗標。
目標:發版前稽核結帳流程行動版版面。
1. 以 run-create 建立 Run。
2. 為 Billing 與 Cart 各建立一個 Task,spec 必須包含:允許修改的路徑、完成定義(測試指令)、回報格式。
3. 以 worker-start 在 new-child Worktree 啟動 Worker,--setup run。
4. 以 check --wait 監督;處理完每一封 Delivery 才 --ack。
5. 任何修改 src/components/ 共用元件的需求,一律以 gate-create 建立 Decision gate,等待人類 gate-resolve,不得自行決定。
6. 收到 worker_done 後,必須自行執行 git diff --stat 與 spec 中的測試,把結果整理成表格,標註「Worker 宣稱」與「Coordinator 實測」兩欄。
7. 不得執行 orchestration reset,不得合併任何分支。
最後輸出:每個 Task 的狀態、變更檔案清單、測試實測結果、待人類決策事項。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- Coordinator 是否先載入
orca skills get orchestration --full(看其終端機或 Session History) - 每個 Task 的 spec 是否包含允許路徑與可執行的測試指令
- 彙整表中「Coordinator 實測」欄是否附上實際指令輸出,而非只轉述 Worker 的
--body - 是否有任何共用元件修改繞過 Decision gate(
git diff --stat檢查src/components/) - 是否誤用
orchestration reset或關閉了非 Coordinator 擁有的終端機 - 所有 Worker 是否已 release,或有合理理由 retain
❌ 常見錯誤
- 使用已退役的
orca orchestration run,以為派工成功,實際上沒有任何效果。 - 在其他 Coordinator 仍在運作時執行
orca orchestration reset --all。reset影響的是 Runtime 全域的 Orchestration 狀態。 - 為了「之後再看輸出」而不釋放 Worker,導致終端機與記憶體累積;釋放後仍可用
worker-read讀取。 - 只看 Worker 的
--body就合併,沒有親自跑測試。
企業治理考量
| 面向 | 建議 |
|---|---|
| 權限 | Worker 由 Orca 啟動時會自動回應「信任此資料夾」提示(Settings → Agents 可關閉);高監理專案建議關閉,保留各 Agent 自身的信任提示 |
| 成本 | 每個 Worker 都是一個獨立 Agent 工作階段;以 --model、--effort 為低風險 Task 指定較低成本模型 |
| 稽核 | Task spec、worker_done 內容、Decision gate 決議都是稽核證據;Run 結束前以 task-list --json 匯出保存 |
| 跨主機 | Federated Worker 用 --on <host> 指定執行主機,之後的指令以 Dispatch ID 路由,不需重複 --on;Antigravity 的監督不支援 SSH |
16.4 Skills Registry 與 MCP
概念說明
Skill 是給 Agent 讀的「能力說明書」(SKILL.md)。Orca 的公開 Skill 採 Hybrid stub 設計:安裝到 Agent 技能目錄的只是一份很短的 stub,告訴 Agent 何時該用 Orca、如何解析 CLI 執行檔,以及用 orca skills get <topic> 從「執行中的 CLI」載入完整且版本相符的指南。如此一來,旗標說明永遠跟著 App 版本走,不會因為 Skill 檔案過期而讓 Agent 呼叫不存在的旗標。
📌 查證狀態:官方文件明確記載|來源:Orca skills registry & MCP
官方可安裝 Skill 一覽
| Skill | 用途 | 典型使用者 |
|---|---|---|
orca-cli | Worktree、終端機、檔案、自動化、內建瀏覽器 | 所有使用 Orca 的 Agent(預設安裝) |
orchestration | Run、Task、監督式 Worker、訊息、Decision gate | Coordinator Agent(預設安裝) |
computer-use | 透過無障礙樹操作桌面 App | 需要操作 GUI 的 Agent(預設安裝) |
orca-linear | 透過 orca linear 讀寫 Linear 工單(舊名 linear-tickets 仍可用) | 處理工單的 Agent |
orca-emulator | 控制 iOS Simulator | 行動 App 開發 |
orca-emulator-android | 透過 adb 控制 Android 模擬器或裝置 | 行動 App 開發 |
orca-per-workspace-env | 在 orca.yaml 設定每工作區環境 Recipe | 平台工程(見 18.6) |
操作步驟
- 桌面環境:到 Settings → Agents 查看已安裝 Skill 的新鮮度;Orca 偵測到較新版本時會提示「update available」,點 Update skills 在背景執行更新(關閉對話框不會中斷)。
- 無頭環境(SSH、容器、CI、
orca serve):使用orca skills install、orca skills update,它們不需要 Runtime。 - 預設安裝範圍為全域(
--global);只要套用到目前專案時加--local。 - 指定 Agent:
--agent claude-code,codex;若主機上偵測不到任何 Agent,--agent為必填。 - 讓 Agent 在每次使用前執行
orca skills get <topic>(必要時加--full)。
範例:桌面或 CI 主機安裝與更新
# 列出可安裝名稱
orca skills install
# 預覽將執行的 npx 指令(不實際安裝)
orca skills install --all --dry-run
# 為 Claude Code 與 Codex 安裝兩個核心 Skill
orca skills install --skill orca-cli --skill orchestration --agent claude-code,codex
# 只更新已安裝者
orca skills update --all
# 等價的手動 npx 指令
npx skills add https://github.com/stablyai/orca --skill orca-cli --global
npx skills update orca-cli orchestration computer-use --global範例:企業內部 Skill
任何含有 skills/<name>/SKILL.md 的 Repo 都能用 npx skills add 安裝。企業可以建立內部 Skill Repo,把公司規範變成 Agent 可讀的能力。
acme-agent-skills/
└── skills/
└── acme-release-check/
└── SKILL.md---
name: acme-release-check
description: 在 Acme 專案發版前執行的檢查流程。當使用者要求準備發版、建立 release PR 或檢查版本號時使用。
---
# Acme 發版檢查
1. 執行 `orca skills get orca-cli`,只使用其中列出的 orca 指令。
2. 執行 `npm run lint && npm test`,把指令與輸出摘要寫進回報。
3. 以 `orca worktree set --worktree active --comment "..." --workspace-status in-review --json` 更新 Checkpoint。
4. 不得修改 `infra/` 與 `.github/workflows/`。npx skills add https://git.acme.example/platform/acme-agent-skills --skill acme-release-check --global📌 查證狀態:教學示例(非官方)— 目錄結構規則取自官方文件,Skill 內容與內部 Repo 網址為虛構|來源:Orca skills registry & MCP
主機間分享私有 Skill
在 Skills → Share skills 可把一個或一組 Skill 發佈成「不公開但可撤銷」的連結(需要 Orca 帳號)。每個發佈版本不可變更;收件者可檢視內容後選擇安裝到本機、已配對 Runtime、WSL 或 SSH 主機。Agent 要透過 CLI 發佈,需人類先開啟預設關閉的 Settings → Share Skills → Allow agents and the Orca CLI to publish skill links:
orca skills installed --json
orca skills share --skill frontend --skill testing --bundle-name "Team Toolkit" --jsonskills share 只接受明確的 Skill ID 或名稱,不接受任意路徑或 --all。
MCP Servers
Model Context Protocol(MCP)Server 把外部工具提供給相容的 Agent。於 Settings → Integrations → MCP 登錄端點後,支援 MCP 的 Agent CLI 即可看到這些工具;Repository 層級的 MCP 設定會留在你選定的主機上。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Skill 指南可取得 | orca skills list 與 orca skills get orca-cli | 列出 Skill 並印出指南內容 | CLI 未註冊或版本過舊,回到 16.1 |
| 安裝指令正確 | orca skills install --skill orca-cli --dry-run | 印出解析後的 npx skills add ... 指令 | 若提示需要 --agent,代表主機未偵測到 Agent,明確指定 |
| Agent 能讀到 Skill | 在 Agent 對話中問「列出你可用的 Orca 相關 Skill」 | Agent 能說出 orca-cli 並表示會執行 orca skills get | 檢查安裝範圍是 --global 或 --local,以及 Agent 的技能目錄 |
| 更新狀態 | Settings → Agents 的已安裝 Skill 區 | 無 Needs attention 或 Skipped 列 | 依 Details 說明修正放置位置後重新檢查 |
企業治理考量
- Skill 本質上是「可讓 Agent 執行指令的說明」,等同程式碼:內部 Skill Repo 應有 Code Review、分支保護與版本標籤。
- 私有 Skill 分享連結「持有即可安裝」,請視同憑證;撤銷連結只阻擋未來存取,不會移除已安裝的副本。
- MCP Server 可能存取外部系統(工單、資料庫、雲端 API),登錄前需資安審核其權限範圍與資料流向。
- 開啟「Allow agents and the Orca CLI to publish skill links」等於允許 Agent 對外發佈內容,高監理環境建議維持關閉。
16.5 Worktree Checkpoints
概念說明
Worktree Checkpoint 是每個 Orca Worktree 上的一個「自由文字註記欄」,顯示在 UI 上,代表「這個 Worktree 此刻在做什麼」。Agent 可以用 CLI 更新它,讓人類不必翻聊天紀錄就能掌握進度。它可以搭配「卡片狀態」(todo、in-progress、in-review、completed 或自訂 ID)一起更新。
特別更正:舊版手冊把 Checkpoint 描述為「可回到中繼狀態的快照」,這是錯誤的。Checkpoint 不保存任何程式碼狀態;要回復程式碼請使用 Git(第十四章 14.6 Rollback 與歷史追溯)或 Native Chat 的 Rewind(第七章 7.7)。
📌 查證狀態:官方文件明確記載|來源:Worktree checkpoints
建議的 Checkpoint 時機
| 時機 | 範例註記 |
|---|---|
| 完成一段有意義的實作 | added retry to PaymentClient (src/pay/client.ts); next: integration test |
| 證實或推翻一個假設 | hypothesis refuted: not a cache issue; token expiry confirmed |
| 完成 Code Review | review done; 3 comments sent to agent |
| 遇到阻擋 | blocked: waiting for staging DB credentials |
| 階段轉換 | investigation done -> implementing fix |
格式規則:第一行描述「剛發生什麼、在哪裡、下一步或狀態」;第二行之後可補充目標與背景。更新前先讀取,保留仍有效的使用者內容,避免覆蓋。
操作步驟
- 讀取目前註記:
orca worktree current --json。 - 合併新進度後寫回,並視需要更新卡片狀態。
- 在 Orca 側邊欄確認 Worktree 卡片顯示新註記與狀態。
- 把規則寫進 Repo 的 Agent 指引檔(例如
AGENTS.md或CLAUDE.md),讓所有 Agent 遵循。
範例:手動更新
# 先讀,避免覆蓋人類寫的目標
orca worktree current --json
# 寫入兩行註記並切換卡片狀態
orca worktree set --worktree active \
--comment "fix implemented in src/auth/refresh.ts; running integration tests
goal: resolve #298 token refresh race" \
--workspace-status in-progress \
--json
# 測試通過後送審,並加上未讀圓點提醒人類
orca worktree set --worktree active \
--comment "integration tests 18/18 passed; ready for review" \
--workspace-status in-review --unread \
--json範例:寫入 Agent 指引檔的規則
## Orca Checkpoint 規則
- 每完成一個子任務、遇到阻擋、或從調查轉為實作時,執行:
`orca worktree set --worktree active --comment "<動作>; <位置>; <下一步>" --json`
- 更新前先執行 `orca worktree current --json`,保留使用者寫的 goal 行。
- 進入審查階段時加上 `--workspace-status in-review`。
- 不得把憑證、Token、客戶資料寫進 comment。✅ 驗證方式
執行:
orca worktree current --json預期輸出(示意):
{"ok":true,"result":{"name":"fix-auth-298", ... "comment":"integration tests 18/18 passed; ready for review", "workspaceStatus":"in-review", ...}}判讀:若
comment未更新,確認指令是否在該 Worktree 內執行(active依目前目錄解析),或改用--worktree path:/abs/path;若人類原本寫的 goal 行消失,代表 Agent 沒有先讀再寫,應修正指引檔規則。
企業治理考量:Checkpoint 會顯示在 UI、行動端與其他配對 Client 上,不可寫入機敏資訊。它適合作為「進度可視化」,但不能取代正式的工單狀態或稽核紀錄;需要留存時,搭配 orca reference 連結工單並把結論寫回工單系統。
16.6 本章 Review 與驗證清單
- 能在本機執行
command -v orca與orca status --json並正確判讀結果 - 知道 CLI 註冊位置在 Settings → General → Orca CLI,並理解官方文件對位置的兩種寫法
- 能說出
active、path:、branch:、issue:、id:五種 Selector 的使用時機 - 能用 16.2 速查表找到「讀終端機畫面」「開啟變更檔 Diff」「建立含 Agent 的 Worktree」的指令
- 已實際執行一次
run-create、task-create、worker-start、check --wait的監督迴圈 - 能說明 Run、Task、Dispatch、Message、Decision gate 的差異,並知道
orchestration run已退役 - 能依 16.3.2 的流程,用
git diff --stat與親自執行測試驗收worker_done - 能用
orca skills install --dry-run預覽 Skill 安裝,並說明 Hybrid stub 的用意 - 知道 MCP Server 在 Settings → Integrations → MCP 登錄,並能列出資安審核重點
- 能正確說明 Worktree Checkpoint 是狀態註記而非程式碼快照
- 已在 Repo 的 Agent 指引檔加入 Checkpoint 規則並驗證生效
第十七章 Scheduled Automations 與 Computer Use
本章處理兩種「人不在電腦前也能讓 Agent 做事」的能力:Scheduled Automations 讓 Prompt 依排程自動執行;Computer Use 讓 Agent 操作終端機與內建瀏覽器以外的原生桌面 App。兩者都大幅擴張 Agent 的行動範圍,因此本章每一節都附上安全邊界與企業治理建議。
📌 查證狀態:官方文件明確記載|來源:Scheduled automations、Computer use
v1.4.150 之後的重要變化
| 版本 | 變化 |
|---|---|
| v1.4.184 | 自動化頁面新增篩選與排序 |
| v1.4.191–192 | 可在同一張表管理本機與所有已連線遠端主機上的自動化 |
| v1.4.219 | Orca 啟動的 Agent(含自動化)會自動回應「信任此資料夾」提示,可於 Settings → Agents 關閉 |
| v1.4.224 | --extra-agent-args 可為單一自動化指定 model 與 effort |
| v1.4.242 | 修正自動化在日光節約時間(DST)切換時的排程問題 |
17.1 Scheduled Automations 概念
概念說明
一個 Automation 由四個要素組成:「何時」(Trigger)、「在哪裡」(Target)、「誰來做」(Provider,也就是 Agent)、「做什麼」(Prompt)。可選的 Precheck 讓你先用便宜的 Shell 指令判斷「這次值不值得跑」。
| 要素 | CLI 旗標 | 可用值 | 說明 |
|---|---|---|---|
| 名稱 | --name | 任意文字 | 用於列表搜尋 |
| 觸發 | --trigger | hourly、daily、weekdays、weekly、cron 運算式、RRULE 字串 | 搭配 --time 09:00 指定時刻 |
| 時區 | --timezone | IANA 時區,例如 Asia/Taipei | 未指定時使用 Runtime 預設時區 |
| 目標 Repo | --repo | Repo Selector | 每次執行在該 Repo 建立或選取工作 |
| 目標 Workspace | --workspace | Worktree Selector,例如 active | 在既有 Worktree 或資料夾 Workspace 內執行 |
| 專案主機 | --project、--host、--project-host-setup | ID | 指定特定專案主機設定 |
| Agent | --provider | 例如 claude、codex | 執行 Prompt 的 Agent |
| Prompt | --prompt | 文字 | 每次執行送出的指令 |
| Precheck | --precheck | Shell 指令 | 非零結束碼會記錄為「略過」 |
| 額外參數 | --extra-agent-args= | 僅限 model、effort 與 Claude 的 --add-dir | 值以 -- 開頭,必須用 = 連接 |
| 初始狀態 | --disabled、--enabled | 旗標 | 新建一律建議 --disabled |
兩個目標旗標都省略時,Orca 會嘗試由目前 Shell 目錄推斷所屬 Worktree。
flowchart LR
T["Trigger 時間到"] --> P{"有設定 Precheck?"}
P -- "否" --> R["建立或選取 Workspace"]
P -- "是" --> Q{"Precheck 結束碼為 0?"}
Q -- "否" --> S["記錄為 skipped"]
Q -- "是" --> R
R --> A["啟動 Provider Agent<br/>送出 Prompt"]
A --> H["記錄 Run 結果<br/>Succeeded 或 Failed"]
H --> V["人類於 Automations 頁<br/>或 runs 指令檢視"]如何閱讀此圖:每次排程觸發時,先經過可選的 Precheck 閘門;未通過只留下一筆 skipped 紀錄,不會啟動 Agent,也就不會產生模型費用。通過後才建立工作區並交給 Agent,最後的結果一定要有人檢視,自動化不等於免審查。
適合與不適合自動化的任務
| 適合 | 不適合 |
|---|---|
| 每日 Issue 分類並產出摘要 | 自動合併 PR 或推送到主分支 |
| 每小時檢查是否有待審 PR 並產出審查意見 | 修改正式環境設定或執行部署 |
| 每週相依套件更新報告 | 需要人類判斷取捨的設計決策 |
| 夜間彙整當日變更摘要 | 涉及個資或金鑰的資料處理 |
企業治理考量
| 面向 | 風險 | 建議 |
|---|---|---|
| 成本 | 排程頻率乘以模型成本會快速累積 | 先用 Precheck 過濾;以 --extra-agent-args 為例行任務指定較低成本模型 |
| 權限 | 自動化 Agent 無人值守 | Prompt 限定「只讀、只產報告」;--extra-agent-args 會拒絕權限、設定、Prompt、Session 類參數,無法繞過權限模式 |
| 稽核 | 誰建立、誰啟用、跑了什麼 | 以 orca automations list --json 定期匯出;每次執行結果以 runs 保存 |
| 執行位置 | 筆電睡眠時排程不會執行 | 長期排程放在 Remote Orca Server(第十八章 18.4) |
17.2 建立第一個安全的自動化
原則:一律先以 --disabled 建立 → 檢視設定 → 手動執行一次 → 檢視結果 → 確認無誤才啟用。
操作步驟
- 取得 Repo Selector:
orca repo list --json。 - 以
--disabled建立自動化。 - 以
list與show檢查設定。 - 以
run手動觸發一次,並以runs查看結果。 - 在 Orca 的 Automations 頁開啟該次 Run,檢視 Agent 實際產出。
- 確認無誤後以
edit --enabled啟用。 - 不再需要時以
remove刪除(會一併刪除執行歷史,刪除前先匯出)。
範例:每個工作日早上的唯讀 Issue 分類
orca automations create \
--name "Weekday triage (read-only)" \
--trigger weekdays \
--time 09:00 \
--timezone Asia/Taipei \
--provider codex \
--repo id:<repoId> \
--prompt "唯讀任務:列出過去 24 小時新開的 GitHub Issue,依 bug、feature、question 分類,標出疑似重複者。不得修改任何檔案、不得留言、不得關閉 Issue。把結果寫成 Markdown 表格,並以 orca worktree set --worktree active --comment 寫入一行摘要。" \
--disabled \
--json範例:在既有 Workspace 內的夜間摘要(cron)
orca automations create \
--name "Nightly status" \
--trigger "0 18 * * 1-5" \
--timezone Asia/Taipei \
--prompt "摘要今天此 Worktree 的變更:git log --since=midnight 與 git diff --stat。只輸出報告。" \
--provider claude \
--workspace active \
--disabled範例:為單一自動化指定模型(不影響主機預設)
orca automations create \
--name "Docs tidy" \
--trigger daily \
--prompt "整理 docs/ 下錯字與失效連結,只產出建議清單" \
--provider claude \
--extra-agent-args="--model opus --add-dir docs" \
--disabled
# 之後要清除額外參數
orca automations edit <automationId> --extra-agent-args= --json範例:PowerShell 檢視與啟用
$list = orca automations list --json | ConvertFrom-Json
$list | ConvertTo-Json -Depth 6
orca automations show <automationId> --json
orca automations run <automationId> --json
orca automations runs --id <automationId> --json
# 確認結果後才啟用
orca automations edit <automationId> --enabled --json範例 Prompt(自動化專用的安全寫法)
你正在以排程自動化身分執行,沒有人類即時監看。
允許:讀取程式碼、執行唯讀指令(git log、git diff、gh issue list、gh pr list)。
禁止:修改或刪除檔案、git commit、git push、在 GitHub 留言或變更標籤、存取 .env 或任何憑證檔。
輸出:
1. 一份 Markdown 報告,第一行為「結論:無事項」或「結論:需人類處理 N 項」。
2. 以 orca worktree set --worktree active --comment 寫入同一行結論。
若任何步驟需要寫入權限,停止並在報告中說明原因。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 該次 Run 的 Worktree 執行
git status --short為空,確認沒有任何檔案被修改 - GitHub 上沒有出現由自動化帳號留下的留言或標籤變更
- 報告第一行符合指定格式,且項目數與內文一致
- 報告引用的 Issue 編號實際存在(隨機抽查 2 到 3 筆)
- Worktree Checkpoint 已更新為同一行結論
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 已建立且停用 | orca automations show <automationId> --json | 顯示名稱、Trigger、Target 正確,狀態為停用 | 以 edit 修正;Trigger 顯示異常時確認 cron 或 RRULE 語法 |
| 手動執行成功 | orca automations runs --id <automationId> --json | 最新一筆為成功 | 在 Orca 開啟該 Run 看錯誤;若在開啟 Workspace 前就失敗,點 Rerun |
| 沒有越權 | 在該 Run 的 Worktree 執行 git status --short | 無輸出 | 立即停用並收緊 Prompt,檢查 Agent 權限模式 |
| 已啟用 | orca automations list --json | 該自動化為啟用狀態 | 執行 edit <automationId> --enabled --json |
❌ 常見錯誤
- 寫成
--extra-agent-args "--model opus"(空白分隔),因為值以--開頭會被誤判為另一個旗標;必須寫成--extra-agent-args="--model opus"。 - 把
--extra-agent-args與--reuse-session同時使用:額外參數需要每次全新 Session,兩者不可併用。 - 嘗試用額外參數傳入權限相關選項(例如略過核准),會被拒絕;權限應在 Settings → Agents 管理。
17.3 執行位置 Precheck 與錯過補跑
執行位置
自動化在「建立它的主機」上排程與執行。桌面 Automations 頁會把本機與已連線、支援的 Orca 主機的自動化放在同一張表,Host 欄顯示儲存與排程的位置;在 UI 建立時,Create on 先選主機,再選該主機上的專案。若某主機的 Orca Server 版本太舊,它仍會出現在選單但呈停用並提示 Update server。
| 執行位置 | 優點 | 限制 |
|---|---|---|
| 本機桌面 | 設定最簡單 | 筆電睡眠、關機或關閉 Orca 時不會執行 |
| SSH 主機 | 使用遠端算力與憑證 | 主機斷線時仍可在表中管理與刪除排程 |
| Remote Orca Server | 常駐、適合長期排程 | 需在伺服器上安裝與登入 Agent CLI(第十八章 18.4) |
在 Orca Server 上的既有 Workspace 執行時,對於「啟動後才讀取 Prompt」的 Agent(例如 Aider、Goose、Amp),Orca 會等它們就緒後再輸入 Prompt;Claude、Codex 這類以命令列參數接收 Prompt 的 Agent 不受影響。
Precheck:先用便宜的指令決定要不要跑
orca automations create \
--name "PR review" \
--trigger hourly \
--precheck "gh pr list --json number -q .[0].number" \
--prompt "審查被要求審查的 PR,只產出審查意見草稿,不得送出 review" \
--provider codex \
--repo id:<repoId> \
--disabled \
--json上例中若沒有待審 PR,gh 雖輸出空字串但結束碼可能仍為 0。若要「沒有 PR 就略過」,Precheck 必須在無資料時回傳非零:
--precheck 'test -n "$(gh pr list --search "review-requested:@me" --json number -q ".[].number")"'📌 查證狀態:依官方說明延伸(教學推論)— 「非零結束碼記錄為略過」為官方說明;
test -n的寫法為教學示例,請先在主機的 Shell 手動執行並以echo $?確認結束碼|來源:Scheduled automations
錯過補跑寬限(Missed-run grace)
主機在排程時間未執行(例如剛好在重開機)時,可設定寬限分鐘數,在寬限內恢復即補跑:
orca automations edit <automationId> --missed-run-grace-minutes 30 --json重用 Session 或每次全新
| 模式 | 設定方式 | 適用 | 注意 |
|---|---|---|---|
| 每次全新(預設) | orca automations edit <automationId> --fresh-session --json | 彼此獨立的例行任務 | 可搭配 --extra-agent-args |
| 重用上次 Session | 建立時加 --reuse-session(僅限目標為既有 Worktree) | 需要延續上下文,例如收件匣摘要 | 不可與 --extra-agent-args 併用;上下文會越來越長,注意成本 |
orca automations create \
--name "Inbox digest" \
--trigger hourly \
--prompt "摘要尚未處理的通知" \
--provider codex \
--workspace active \
--reuse-session \
--disabled✅ 驗證方式
先在目標主機的 Shell 驗證 Precheck 結束碼:
test -n "$(gh pr list --search "review-requested:@me" --json number -q ".[].number")"; echo "exit=$?"預期輸出(沒有待審 PR 時):
exit=1判讀:
exit=1代表該次排程會被記錄為 skipped,符合預期;若在沒有 PR 時仍是exit=0,代表 Precheck 寫法無法過濾,Agent 每小時都會被啟動並產生費用。接著執行orca automations runs --id <automationId> --json,確認在無 PR 的時段紀錄為 skipped。
企業治理考量
- Precheck 是在主機上執行的任意 Shell 指令,等同排程腳本;建立與修改權限應比照 cron 管理,納入變更審核。
- Precheck 中使用的
gh等工具會帶著主機上的登入身分,建議為自動化主機使用專用的服務帳號與最小權限 Token。 - 定期以篩選器(Host、Enabled 或 Paused、最後結果 Failed)檢視自動化清單,清除無主或長期失敗的排程。
17.4 Computer Use 設定
概念說明
orca computer 讓 Agent 檢視並操作原生桌面 App:列出執行中的 App、讀取無障礙樹(Accessibility Tree)、點擊控制項、設定值、輸入文字、捲動與截圖。用於「任務必須操作作業系統或第三方 App,而不是終端機或內建瀏覽器」的情境,例如沒有 API 的舊系統用戶端、需要驗證桌面 App 行為的 QA。
| 操作對象 | 使用的工具 | 章節 |
|---|---|---|
| 終端機 | orca terminal | 16.2 |
| Orca 內建瀏覽器的網頁 | orca goto、orca snapshot、orca click | 第十三章 |
| iOS Simulator | orca emulator | 16.2 |
| 原生桌面 App | orca computer | 本節 |
📌 查證狀態:官方文件明確記載(Computer Use 為 Beta,各平台隨附原生 Helper;指令面已足以讓 Skill 依賴,但旗標名稱仍可能變動。Release notes v1.4.151–v1.4.244 未記載 Computer Use 的變更)|來源:Computer use
操作步驟
確認 Runtime 正常:
orca status --json。檢查權限:
orca computer permissions --json。若有缺漏,到作業系統設定授權給 Orca Computer Use:
- macOS:System Settings → Privacy & Security → Accessibility 與 Screen Recording。
- Windows、Linux:依官方說明需要 Accessibility 權限;實際授權介面依作業系統而異(教學推論,請以
permissions --json回報為準)。
再次執行
orca computer permissions --json確認全部通過。查看平台支援的能力:
orca computer capabilities --json。為 Agent 安裝
computer-useSkill:npx skills add https://github.com/stablyai/orca --skill computer-use # 或無頭環境 orca skills install --skill computer-use
範例:首次設定檢查(bash)
orca status --json
orca computer permissions --json
orca computer capabilities --json
orca computer list-apps --json範例:PowerShell 檢查權限是否齊全
$perm = orca computer permissions --json | ConvertFrom-Json
$perm | ConvertTo-Json -Depth 5✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 權限齊全 | orca computer permissions --json | 沒有任何權限標示為缺少 | 依作業系統授權給 Orca Computer Use 後重跑;macOS 授權 Screen Recording 後可能需重新啟動 Orca |
| 能列出 App | orca computer list-apps --json | 回傳執行中的 App 與其 Bundle ID 或名稱 | 檢查 Runtime 是否在同一台機器;遠端連線的 Client 無法操作伺服器以外的桌面 |
| 能讀取狀態 | orca computer get-app-state --app <app> --no-screenshot --json | result.snapshot.treeText 有內容 | 目標 App 不支援無障礙 API 時,只能退回座標操作(17.5) |
企業治理考量
- Computer Use 讓 Agent 擁有「與使用者同等」的桌面操作能力,應視為高風險功能,預設不在一般開發者機器啟用
computer-useSkill。 - 建議在專用的虛擬桌面或測試帳號中使用,不要在開著電子郵件、網路銀行、正式環境管理後台的桌面上執行。
- 授權 Accessibility 與 Screen Recording 屬於作業系統層級權限,應由 MDM 或端點管理政策核准並記錄。
17.5 Snapshot Act Snapshot 操作模式
概念說明
所有 Computer Use 互動都遵循同一個循環:讀取 App 目前狀態 → 對特定元素執行動作 → 再讀一次狀態確認結果。元素索引(element index)只在「最近一次 get-app-state」有效,而且可能不連續;不可從 elementCount 自行推算索引。
sequenceDiagram
participant A as Agent
participant O as orca computer
participant X as 目標桌面 App
A->>O: list-apps
O-->>A: Bundle ID 清單
A->>O: get-app-state --app id
O->>X: 讀取無障礙樹與截圖
O-->>A: treeText 與 screenshot.path
A->>O: click --element-index 42
O->>X: 執行語意化點擊
A->>O: get-app-state(重新讀取)
O-->>A: 新的 treeText
A->>A: 比對畫面是否符合預期如何閱讀此圖:Agent 永遠不直接「盲點」。每次動作之後都會重新讀取狀態,因為導覽、焦點變化、捲動或重新繪製都會讓舊的元素索引失效。
操作步驟
list-apps取得 App 的 Bundle ID(優先使用),名稱不重複時也可用名稱,兩者都衝突時才用pid:<number>。get-app-state讀取樹狀結構;以--json時從result.snapshot.treeText讀取,截圖寫到磁碟並回傳screenshot.path。- 選擇語意化動作(click、set-value、perform-secondary-action)優先於鍵盤輸入(type-text、press-key)。
- 動作後重新
get-app-state驗證。 - 多視窗 App 先
list-windows,有穩定--window-id就用它,否則用--window-index。 - 無障礙定位失敗時,才謹慎退回座標操作。
範例:在 Safari 中操作(macOS)
orca computer list-apps --json
orca computer get-app-state --app com.apple.Safari --no-screenshot --json
# 從 treeText 找到網址列的索引,例如 12
orca computer click --app com.apple.Safari --element-index 12 --json
orca computer set-value --app com.apple.Safari --element-index 12 --value "https://intranet.example/report" --json
orca computer press-key --app com.apple.Safari --key Return --json
# 重新讀取確認頁面已載入
orca computer get-app-state --app com.apple.Safari --json範例:多視窗與座標退回
orca computer list-windows --app com.microsoft.edgemac --json
orca computer get-app-state --app com.microsoft.edgemac --window-id <id> --json
orca computer click --app com.microsoft.edgemac --window-id <id> --element-index 12 --json
# 無障礙定位失敗時才使用座標
orca computer click --app com.apple.Safari --x 120 --y 340 --json
orca computer drag --app <app> --from-element-index 3 --to-element-index 9 --json可用動作速查
| 動作 | 指令 | 建議程度 |
|---|---|---|
| 點擊元素 | orca computer click --element-index | 優先 |
| 設定欄位值 | orca computer set-value --value | 優先 |
| 次要動作(例如展開選單) | orca computer perform-secondary-action --action | 優先 |
| 捲動 | orca computer scroll --direction down | 一般 |
| 輸入文字 | orca computer type-text --text | 次要(受焦點影響) |
| 按鍵與快捷鍵 | orca computer press-key --key、orca computer hotkey --key CmdOrCtrl+A | 次要 |
| 貼上 | orca computer paste-text --text | 次要 |
| 拖曳 | orca computer drag --from-x --from-y --to-x --to-y | 最後手段 |
截圖選項:--no-screenshot 不擷取像素(較快、較小);--restore-window 先把隱藏或最小化的視窗帶到前景再擷取。
範例 Prompt
使用 computer-use Skill 操作「Acme 報表用戶端」。開始前執行 `orca skills get computer-use`。
規則:
1. 每次動作前後都執行 get-app-state,元素索引只能取自最新一次結果。
2. 優先使用 click、set-value;只有無障礙定位失敗時才用座標,並在回報中註明。
3. 只操作 Acme 報表用戶端,不得切換到其他 App。
4. 需要輸入帳密時停止並請人類處理。
完成後回報:執行的每一步指令、最後一次 get-app-state 的 treeText 中「匯出成功」相關節點、匯出檔案路徑。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
- 回報的每個
--element-index前都有一次get-app-state - 沒有對 Acme 報表用戶端以外的
--app執行動作 - 使用座標的步驟有註明理由
- 匯出檔案確實存在且內容正確(人類親自開啟)
- 截圖檔案(
screenshot.path)沒有拍到其他機敏視窗
✅ 驗證方式
執行:
orca computer get-app-state --app com.apple.Safari --no-screenshot --json | jq -r '.result.snapshot.treeText' | head -n 20預期輸出(示意):
[0] window "Intranet Report" [12] text field "Address" value="https://intranet.example/report" [15] button "Reload"判讀:若網址欄位的值與
set-value指定的相同,代表動作成功;若索引對應到不同元素,代表 Agent 使用了過期的狀態,必須重新讀取後再操作。
17.6 敏感輸入與安全邊界
概念說明
Computer Use 與自動化最常見的資安事故是「秘密外洩到不該出現的地方」:Shell 歷史、Agent 對話紀錄、截圖、日誌。Orca 提供 --value-stdin 與 --text-stdin 讓秘密從標準輸入傳入,不出現在指令列參數中。
📌 查證狀態:官方文件明確記載(stdin 傳遞方式);安全邊界建議為依官方說明延伸(教學推論)|來源:Computer use
範例:bash 從密碼管理工具讀取並透過 stdin 傳入
# 互動輸入秘密,不回顯也不寫入 Shell 歷史
read -rs TEXT # 互動輸入,不回顯
printf '%s' "$TEXT" | orca computer set-value \
--app com.apple.Safari --element-index 7 --value-stdin --json
unset TEXT範例:PowerShell
$secure = Read-Host -AsSecureString "Password"
$plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
[Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure))
$plain | orca computer type-text --app <app> --text-stdin --json
Remove-Variable plain, secure⚠️ 注意事項:PowerShell 透過管線傳給原生程式時可能在結尾附加換行,對於密碼欄位可能造成多一個字元或觸發送出。正式使用前請在測試欄位驗證,或改用 bash 的 printf '%s'(教學推論)。
安全邊界清單
| 邊界 | 做法 | 理由 |
|---|---|---|
| 秘密傳遞 | 只用 --value-stdin、--text-stdin | 避免出現在 Shell 歷史與程序清單 |
| Agent 不經手秘密 | Prompt 規定「需要帳密時停止並交給人類」 | Agent 對話紀錄會被保存與索引(orca search) |
| 截圖 | 不需要像素時加 --no-screenshot;定期清除 screenshot.path 指向的檔案 | 截圖可能拍到其他視窗內容 |
| 桌面隔離 | 使用專用 VM 或作業系統帳號執行 Computer Use | 縮小可被操作的範圍 |
| 自動化範圍 | 排程 Prompt 只做唯讀與報告 | 無人值守時無法即時制止錯誤動作 |
| 對外發佈 | Artifacts 發佈維持 Settings → Artifacts 預設關閉 | 沒有任何 CLI 旗標能繞過此開關,避免 Agent 把內部報告發佈成公開連結 |
| 資料夾信任 | 高監理專案關閉 Settings → Agents → Trust the folder when Orca starts an agent | 讓自動化與 Worker 啟動時保留 Agent 自身的信任提示 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 秘密未進 Shell 歷史 | bash 執行 history 並搜尋秘密字串;PowerShell 檢查 (Get-PSReadLineOption).HistorySavePath 指向的檔案 | 找不到秘密字串 | 清除歷史並輪替該秘密 |
| 秘密未進對話紀錄 | orca search --query "<秘密的前四碼>" --scope all --json | 無結果 | 刪除相關 Session 並輪替秘密,檢討 Prompt |
| Artifacts 未開放 | 檢查 Settings → Artifacts → Allow publishing public artifact links | 關閉 | 關閉後以 orca artifacts list --json 稽核既有連結並 delete |
| 截圖已清理 | 列出 screenshot.path 所在目錄 | 無殘留或已依政策保存 | 建立定期清除腳本 |
17.7 本章 Review 與驗證清單
- 能說明 Automation 的 Trigger、Target、Provider、Prompt、Precheck 五個要素
- 已用
--disabled建立一個自動化,並用show、run、runs驗證後才啟用 - 能正確寫出
--extra-agent-args="--model ..."並說明其限制與不可搭配--reuse-session - 已在目標主機驗證 Precheck 的結束碼行為
- 知道筆電睡眠時本機排程不會執行,並能說明何時改用 Remote Orca Server
- 能設定
--missed-run-grace-minutes並說明用途 - 已執行
orca computer permissions --json並取得完整權限 - 能示範 snapshot、act、snapshot 循環,並說明元素索引為何不能重複使用
- 能用
--value-stdin或--text-stdin傳入秘密,並驗證未留在歷史與對話紀錄 - 已確認 Artifacts 公開發佈開關與資料夾信任設定符合組織政策
第十八章 遠端執行模式
Orca 並不綁定在你的筆電上。每個 Worktree 都「在某處執行」:眼前的電腦、你已擁有的主機、一台常駐的共用伺服器,或為單一工作區臨時啟動的雲端 VM。本章依序說明四種模式的設定、驗證與治理,最後提供選型決策表與流程圖。
📌 查證狀態:官方文件明確記載|來源:Ways to run Orca、SSH worktrees、Remote Orca Servers、Work on a remote machine over SSH
舊版手冊需更正的觀念
| 舊版說法 | v1.4.244 正確說法 |
|---|---|
SSH Worktree 需先在 VPS 執行 orca serve | 不需要。SSH 模式由筆電上的 Orca 擁有 Runtime;v1.4.224 起首次連線時 Orca 會在主機上自動部署並維護「Managed Orca server」 |
| SSH 主機需正確的 Node 版本與建置工具 | v1.4.224 起改用 Orca 自帶的固定版本 Runtime;舊的 Runtime 選擇器(Auto、Orca-managed Node、Host Node)已移除 |
| 遠端只有 SSH 一種 | 共有 Local、SSH、Remote Orca Server、Cloud VM 四種,可在同一安裝中混用 |
| Remote Server 設定分散多處 | v1.4.233 起 Settings → Remote Orca Servers 合併為單一清單 |
18.1 四種執行模式比較
| 模式 | 檔案與 Agent 在哪裡 | 誰擁有機器 | Runtime 擁有者 | 最適合 |
|---|---|---|---|---|
| Local | 你的桌機或筆電 | 你 | 本機 Orca | 日常開發、快速迭代 |
| SSH 目標 | 透過 SSH 連線的遠端主機 | 你或團隊 | 筆電上的 Orca(主機上跑 Managed server) | 開發主機、GPU 主機、常駐 VPS |
| Remote Orca Server | 執行 Orca 桌面版或 orca serve 的機器 | 你或團隊 | 遠端機器 | 常駐共用 Runtime、行動端、自動化 |
| Cloud VM(每工作區環境) | 每個 Workspace 一個可拋棄的 VM 或沙箱 | 你的雲端帳號(自備供應商) | 依 Recipe 而定 | 隔離、可拋棄的 Agent 算力 |
Orca 不販售託管 VPS;所有遠端模式都使用你自己控制的機器與雲端帳號。
flowchart TB
subgraph LAPTOP["開發者筆電"]
UI["Orca 桌面 UI"]
LW["Local Worktree"]
end
subgraph SSHHOST["SSH 主機"]
MS["Managed Orca server"]
SW["SSH Worktree 與 Agent"]
end
subgraph SERVER["Remote Orca Server"]
RS["Orca 桌面版或 orca serve"]
RW["伺服器端 Worktree 與 Agent"]
end
subgraph CLOUD["Cloud VM(每工作區)"]
VM["Recipe 建立的 VM"]
VW["單一 Workspace"]
end
PHONE["Orca Mobile"]
UI --> LW
UI -- "SSH" --> MS
MS --> SW
UI -- "配對連結(Tailscale)" --> RS
RS --> RW
PHONE -- "配對" --> RS
UI -- "pairing URL 或 SSH" --> VM
VM --> VW如何閱讀此圖:每個方框代表一台機器,箭頭代表連線方向。SSH 模式中 UI 仍在筆電、執行在主機;Remote Orca Server 模式中伺服器擁有完整 Runtime,筆電與手機都只是 Client;Cloud VM 則依 Recipe 回傳 pairing URL 或 SSH 連線資訊,由 Orca 連入。
SSH 與 Remote Orca Server 的關鍵差異
| 比較 | SSH Worktrees | Remote Orca Server |
|---|---|---|
| Runtime 擁有者 | 筆電上的 Orca | 遠端機器 |
| 斷線時 | Agent 在主機上繼續執行,筆電重新附加 | 完整 Session 狀態保存在伺服器 |
| 多 Client | 一台筆電驅動主機 | 筆電、Web、手機、自動化可共用同一 Runtime |
| 典型設定 | 匯入 SSH config,建立 Worktree 時選 Run on | 分享伺服器 App 或執行 orca serve,再以 URL 配對 |
企業治理總覽
| 面向 | Local | SSH | Remote Orca Server | Cloud VM |
|---|---|---|---|---|
| 憑證所在 | 開發者筆電 | 遠端主機 | 伺服器 | VM 快照與雲端帳號 |
| 主要風險 | 筆電遺失 | SSH 金鑰外洩、主機被橫向移動 | 配對連結外洩、連接埠暴露 | 快照含憑證、雲端費用失控 |
| 主要控制 | 磁碟加密、MDM | 堡壘機、金鑰輪替、known_hosts | Tailscale ACL、撤銷授權 | 不在快照寫入秘密、自動銷毀 |
18.2 SSH Worktrees 設定
概念說明
把 Orca 指向任何 SSH 主機,建立 Worktree 時在 Run on 選該主機。Orca 會在遠端執行 git worktree add、在遠端執行 Agent,並同步檔案事件,讓編輯器、Diff 與瀏覽器用起來像本機。v1.4.224 起,首次連線時 Orca 會在主機上部署自己的 Managed Orca server,因此主機缺少正確 Node 版本或建置工具不再阻擋連線。
前置條件
- 能從筆電以
ssh <host>成功登入。 - 主機已安裝
git(要在主機上建立 Repo Worktree 時必要)。 - 主機上已安裝並登入要使用的 Agent CLI(主機用自己的 PATH、家目錄與憑證)。
範例:~/.ssh/config
Host bastion
HostName bastion.corp.example
User alice
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
Host devbox
HostName 10.20.30.40
User alice
Port 22
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ProxyJump bastion
ServerAliveInterval 30
ServerAliveCountMax 4📌 查證狀態:教學示例(非官方)— 設定語法為標準 OpenSSH;Orca 可從
~/.ssh/config(含 Include 檔)挑選主機預填表單|來源:SSH worktrees
操作步驟
在終端機先確認 SSH 本身可用:
ssh -G devbox | grep -E '^(hostname|user|port|proxyjump) ' ssh devbox 'git --version && uname -sm'開啟 Settings → SSH,點 Add Target(表單以對話框開啟)。
手動填寫 Host、User、Port、Identity file,或在同一對話框開啟 OpenSSH config 選擇器搜尋並挑選
devbox預填;已存在於 Orca 的主機會顯示 In Orca 標章。若金鑰有 Passphrase,首次連線時 Orca 會提示輸入。
點 Test 驗證連線,成功後點 Save。
首次連線時 Orca 自動在主機部署 Managed Orca server;可在 Settings → Managed servers 看到版本與執行中的終端機。
加入 Repo:在加入 Repository 時選擇 SSH 目標作為位置,或用檔案選擇器直接開啟遠端資料夾。
建立 Worktree:在 Run on 選
devbox。若主機已連線但尚未為此專案設定,會顯示 setup-needed 列,可就地 Set project location 選擇既有 checkout 或 clone。啟動 Agent,它會在遠端主機執行;之後照常在筆電上審查 Diff、Commit、Push。
連線狀態與斷線行為
| 狀態晶片 | 意義 | 你該做什麼 |
|---|---|---|
| 綠色 | 已連線 | 正常工作 |
| 黃色 | 重新連線中 | 等待;斷線期間輸入的按鍵會在恢復後依序送達且只送一次 |
| 紅色 | 已中斷 | 使用 Workspace 卡片上的 Connect 控制項重新連線 |
- 中斷不會終止遠端 Agent;重新連線後 Orca 會重新附加並重播捲動輸出。
- 關閉桌面 App 不會終止遠端 PTY,Session 保存在主機的 Managed server 上。
- 失去連線「不代表」工作已停止。在同一 Worktree 啟動第二個 Agent 之前,先確認主機上的狀態,避免兩個 Agent 互相覆寫。
- 不希望 Orca 啟動時自動連線某主機:編輯主機,關閉 Advanced → Reconnect on launch。
SSH 主機上的 orca CLI
預設情況下,在 SSH 主機上執行的 orca 指令只能觸及該主機自身的終端機與 Orchestration 訊息;Worker 仍可向派工的 Coordinator 回報,但無法控制其他主機、桌面、帳號或設定。若要讓該主機的 Agent 建立 Worktree、開終端機或派工,需在 Settings → SSH → 編輯主機 → Advanced Connection 開啟 Allow this host’s orca CLI to control Orca(v1.4.230 起,舊設定一律遷移為關閉)。
其他實用功能
| 功能 | 操作 | 限制 |
|---|---|---|
| 下載遠端檔案或資料夾 | 檔案總管右鍵 Download 或 Download Folder | 僅桌面版;資料夾下載需連線支援完整 SFTP |
| 以 VS Code 開啟 | Worktree 選單 Open in → VS Code(使用 Remote-SSH) | Cursor、Zed 不支援此遠端路徑 |
| 連接埠轉送 | 右側欄 Ports 分頁(Cmd+Shift+I),一鍵轉送偵測到的連接埠 | 特權連接埠會自動重新對應(例如遠端 80 對應本機 10080) |
| 從 Orca 移除但保留主機檔案 | 刪除失敗時選 Remove from Orca | 主機上的檔案不會被刪除 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| SSH 設定解析正確 | ssh -G devbox | hostname、user、proxyjump 為預期值 | 修正 ~/.ssh/config |
| 主機具備 git | ssh devbox 'git --version' | 印出 git 版本 | 在主機安裝 git |
| Orca 看得到主機 | orca host list --json | 出現 devbox 與其 ssh:<target-id> Selector | 回到 Settings → SSH 檢查是否已 Save |
| Managed server 正常 | orca environment list --json 與 orca environment status --environment <selector> --json | 狀態為執行中,版本與桌面版相符 | 在 Settings → Managed servers 執行 Update 或 Recover |
| Worktree 建在遠端 | ssh devbox 'git -C <repo-path> worktree list' | 出現新 Worktree 路徑 | 確認建立時 Run on 選的是 devbox 而非 Local |
| Agent 在遠端執行 | 在該 Worktree 終端機執行 hostname | 顯示遠端主機名稱 | 終端機可能開在本機,重新從 Worktree 開新終端機 |
企業治理考量
- SSH 主機上的 Agent 可以讀取主機上的一切資料。主機應與正式環境隔離,不放正式資料庫連線字串。
- 為「Agent 用主機」建立專用帳號與金鑰,與工程師個人帳號區隔,方便稽核與撤銷。
- 維持「Allow this host’s orca CLI to control Orca」預設關閉;只有作為 Orchestration Coordinator 的主機才開啟。
- Managed server 的 Update、Roll back 會改變主機上的軟體,應納入變更管理;CLI 對應指令為
orca environment update與orca environment rollback。
18.3 SSH 進階驗證與連線選項
概念說明
企業環境的 SSH 往往有堡壘機、多因素驗證、Kerberos 或硬體金鑰。Orca 內建 SSH 用戶端可處理大多數情況;遇到內建用戶端不支援的機制時,會自動改用系統的 OpenSSH。
| 機制 | Orca 的處理方式 | 你需要準備 |
|---|---|---|
| 主機金鑰驗證 | 依 OpenSSH known_hosts 與 Orca 已儲存金鑰比對;預設首次接觸時接受並記住,並顯示指紋 | 企業可預先散佈 known_hosts |
StrictHostKeyChecking yes | 拒絕未知主機 | 先將主機金鑰加入 known_hosts |
| 主機金鑰變更 | 在要求密碼或 Passphrase 之前就拒絕連線 | 先驗證新指紋,再依錯誤訊息提供的 ssh-keygen -R 指令移除舊紀錄 |
| 堡壘機與 Proxy | Advanced Connection 設定 proxy 或 jump host;或在 SSH config 用 ProxyJump | 堡壘機帳號 |
| 連線重用 | Reuse SSH connection 預設開啟(macOS、Linux 使用 OpenSSH 多工) | 主機政策拒絕多工時才關閉 |
| Passphrase | 存於記憶體直到 Orca 關閉;可在 SSH 設定選擇較長 TTL | 依政策決定 TTL |
| 多因素(OTP、MFA) | 轉送 keyboard-interactive 提示給你回答(v1.4.217) | 驗證器 App |
| 演算法不相容 | 自動改用系統 ssh 重試 | 系統 OpenSSH |
| Kerberos、GSSAPI | config 設 GSSAPIAuthentication yes 時改用系統 OpenSSH | 連線前先 kinit 取得有效票證 |
| FIDO2 硬體金鑰 | ed25519-sk、ecdsa-sk 自動交給系統 OpenSSH,觸碰與 PIN 提示照常運作 | OpenSSH 需在 PATH 或標準位置 |
| 僅憑證(certificate-only)主機 | 改走系統 ssh(v1.4.241) | SSH 憑證 |
📌 查證狀態:官方文件明確記載(certificate-only 主機一列取自 v1.4.241 Release notes)|來源:SSH worktrees、Orca Releases
範例:Kerberos 與 FIDO2 主機設定
Host build-krb
HostName build01.corp.example
User alice
GSSAPIAuthentication yes
GSSAPIDelegateCredentials no
Host secure-gpu
HostName gpu07.corp.example
User alice
IdentityFile ~/.ssh/id_ed25519_sk
IdentitiesOnly yes
ProxyJump bastion# Kerberos:連線前取得票證並確認
kinit alice@CORP.EXAMPLE
klist
# FIDO2:確認系統 OpenSSH 可用
ssh -V
ssh secure-gpu 'echo ok'範例:主機重建後安全更新 known_hosts
# 1. 透過可信管道(例如主機管理員或 CMDB)取得新指紋後,比對掃描結果
ssh-keyscan -t ed25519 devbox.corp.example 2>/dev/null | ssh-keygen -lf -
# 2. 指紋相符才移除舊紀錄(非 22 埠需使用 [host]:port 格式)
ssh-keygen -R devbox.corp.example
ssh-keygen -R "[devbox.corp.example]:2222"
# 3. 重新連線並接受新金鑰
ssh devbox 'echo ok'Node.js 下載受限的環境
Managed server 需要下載固定版本的 Node.js Runtime。若筆電與主機都無法下載,連線錯誤會提供 Use a Node.js mirror…,可填入企業內部鏡像後 Save and retry;Orca 會以固定的 checksum 驗證下載內容。之後可在 Settings → Advanced → Network 修改鏡像位址。
Managed server 無法執行的主機
不支援的作業系統或 CPU、noexec 掛載的家目錄、拒絕連接埠轉送的 SSH Server 都會讓 Managed server 無法執行。此時連線會失敗並在 Settings → SSH Hosts 說明原因,不再默默退回舊的 SSH Runtime;若必須繼續連線,只能暫時使用較舊的 Orca 版本。
✅ 驗證方式
執行:
ssh -G secure-gpu | grep -E '^(identityfile|proxyjump|gssapiauthentication) ' ssh -o BatchMode=no secure-gpu 'whoami && hostname'預期輸出(示意):
identityfile ~/.ssh/id_ed25519_sk proxyjump bastion gssapiauthentication no alice gpu07判讀:先確保「系統 ssh」能成功,再到 Settings → SSH 按 Test。若系統 ssh 成功而 Orca 失敗,檢查是否為 FIDO2 或 Kerberos 主機但 OpenSSH 不在 PATH;若出現主機金鑰不符,不要直接刪除 known_hosts,先向主機管理員確認指紋。
企業治理考量
| 控制項 | 建議 |
|---|---|
| 堡壘機 | 所有 Agent 用主機經堡壘機連線,堡壘機保留連線日誌 |
| 金鑰 | 優先 FIDO2 硬體金鑰或短效 SSH 憑證;個人金鑰定期輪替 |
| known_hosts | 由組態管理工具集中散佈,搭配 StrictHostKeyChecking yes |
| Agent forwarding | 預設不開啟 ForwardAgent,避免遠端 Agent 借用你的本機金鑰連到其他主機(教學推論) |
| Passphrase TTL | 維持預設(Orca 關閉即清除),除非有明確需求 |
18.4 Remote Orca Servers 與 Tailscale
概念說明
Remote Orca Server 讓一台電腦負責執行、另一台電腦(或手機)提供介面。伺服器保存 Projects、Worktrees、終端機、分頁、供應商帳號與 Agent Session;筆電只是連線上去的 Client。官方最推薦的方式是「兩台都裝 Orca 桌面版,透過 Tailscale 連線」,這條路徑不需要執行 orca serve。
📌 查證狀態:官方文件明確記載(Remote Orca Servers 為 Beta;應讓伺服器與 Client 走你控制的私有網路,例如同一個 Tailscale tailnet 或 LAN)|來源:Remote Orca Servers
前置條件
- 兩台電腦都安裝並更新到相同版本的 Orca。
- 兩台都安裝 Tailscale 並登入同一個 tailnet。
- 伺服器保持開機、連網、Orca 執行中。
- 伺服器上安裝並登入 Agent CLI(Codex、Claude Code、OpenCode 等)、
git與供應商 CLI;筆電上的登入不會帶到伺服器。
操作步驟:伺服器端
- 開啟 Orca 桌面版,進入 Settings → Remote Orca Servers。
- 在 Advertise this app as a server 下點 New Link。
- Connection address 選擇 Tailscale 位址(通常是
100.x.y.z,Orca 會將其排在最前面);若沒有出現,確認 Tailscale 已連線後按旁邊的重新整理。 - 點 Generate Access Link,複製 Pair another Orca client 下的連結。
操作步驟:Client 端(筆電)
- 開啟 Settings → Remote Orca Servers,點 Add Server。
- 輸入可辨識的名稱(例如
Team Build Server),貼上存取連結,點 Add Server。 - 若顯示 Disconnected,點 Connect。
- 新增伺服器不會強制所有新專案都放到伺服器;只有在需要時才到 Advanced → Active Server 把它設為預設。
範例:在伺服器上準備 Agent 與 Skills
# 在伺服器的終端機執行(桌面版或無頭主機皆可)
codex --version
claude --version
git --version
# 無頭主機無法用 UI 的 Add account,改用 CLI 在伺服器上登入
orca account add --agent claude
orca account add --agent codex
orca account list
# 無 Settings UI 時安裝或更新 Skills
orca skills install --skill orca-cli --skill orchestration
orca skills update --all範例:Tailscale ACL(限制只有開發群組能連到 Orca 伺服器)
{
"tagOwners": {
"tag:orca-server": ["group:platform-admins"]
},
"groups": {
"group:orca-users": ["alice@corp.example", "bob@corp.example"],
"group:platform-admins": ["carol@corp.example"]
},
"acls": [
{
"action": "accept",
"src": ["group:orca-users"],
"dst": ["tag:orca-server:6768"]
}
]
}📌 查證狀態:教學示例(非官方)— ACL 語法為 Tailscale 政策檔格式;6768 為
orca serve --port官方範例使用的埠號與行動端預設埠號,桌面版作為伺服器時實際使用的埠請以產生的存取連結為準|來源:Remote Orca Servers、Mobile companion
存取與撤銷
- Orca 為每個已配對的 Client 建立獨立、可撤銷的 Token,列在伺服器的 Shared Server Access。
- 點授權旁的垃圾桶即可撤銷,使用該授權的 Client 會立即中斷。
- 產生新連結會取代「尚未使用」的舊連結;已配對的 Client 保有各自授權直到被撤銷。
- 存取連結等同密碼,只傳給要配對的那台 Client。
- 不要把 Orca 連接埠直接轉送到公網;優先使用 Tailscale、WireGuard、可信 LAN、SSH 轉送或有驗證的通道。
- 不要為另一台電腦選擇
127.0.0.1,那只在伺服器本機有效。
使用中的行為
- Client 筆電睡眠或斷線時,Agent 繼續在伺服器執行。
- 重新連線後回到伺服器擁有的 Workspace、分頁與窗格狀態,不會產生重複分頁。
- 多個 Client 共用時,側邊欄篩選可選 Hide other-client workspaces,只顯示本裝置建立的 Workspace。
- 在伺服器刪除的專案會從所有 Client 側邊欄消失。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 同一 tailnet | 兩台都執行 tailscale status | 彼此出現在清單且 online | 登入同一 tailnet,檢查 ACL |
| 網路可達 | Client 執行 tailscale ping <server-name> | 收到 pong | 檢查 ACL 或 grants 是否允許 |
| 已配對 | Client 執行 orca host list --json | 出現該伺服器與其 --environment 名稱 | 重新 Add Server;若版本不相容兩邊都更新 |
| 工作在伺服器執行 | 在伺服器專案的終端機執行 hostname | 顯示伺服器主機名稱 | 確認選的是伺服器上的專案 |
| Agent 可用 | 伺服器終端機執行 command -v codex claude | 印出路徑 | 在伺服器安裝並登入該 CLI |
| 授權可撤銷 | 伺服器 Shared Server Access 撤銷測試授權 | 該 Client 立即中斷 | 確認撤銷的是正確授權 |
企業治理考量
| 面向 | 建議 |
|---|---|
| 網路 | 只走 Tailscale 或企業 VPN;以 ACL 或 grants 限制來源群組與目的埠;禁止公網轉送 |
| 身分 | 伺服器上的 Agent 帳號屬於「伺服器擁有者」,共用伺服器時需明確約定費用與責任歸屬 |
| 授權盤點 | 每月檢視 Shared Server Access,撤銷離職或遺失裝置的授權 |
| 連結外洩 | 立即在 Shared Server Access 撤銷並重新產生連結 |
| 資料 | 伺服器保存 Repo、Session 紀錄與憑證,應有磁碟加密與備份政策 |
18.5 orca serve 無頭伺服器
概念說明
orca serve 不開啟桌面視窗,直接啟動 Orca Runtime,適合無頭 Linux 伺服器、VM 或由服務管理器管理的環境。若伺服器是一台可以保持登入的 MacBook 或桌機,18.4 的桌面版做法更簡單。
| 比較 | 伺服器上跑桌面版 | orca serve |
|---|---|---|
| 最適合 | 舊筆電、Mac mini、桌機 | 無頭 Linux、VM、受管服務 |
| 設定方式 | Settings 與按鈕 | 終端機指令與服務設定 |
| 伺服器視窗 | 開啟 | 無 |
| 存取連結 | New Link → Generate Access Link | 印在終端機 |
| 生命週期 | 桌面 App 執行期間 | 前景程序或服務執行期間 |
📌 查證狀態:官方文件明確記載|來源:Remote Orca Servers、Orca CLI reference
主要旗標與子指令
| 指令或旗標 | 作用 |
|---|---|
orca serve --pairing-address <addr> | 指定 Client 要連線的位址(例如 Tailscale IP 或主機名稱) |
--port 6768 | 固定埠號,供防火牆、通道或服務定義使用 |
--mobile-pairing | 印出行動端專用 QR Code 與連結(第十九章) |
--supervise | 給服務管理器用:停止時以遞增延遲自動重啟、更新期間等待、多次失敗後放棄 |
orca serve service install | 寫入每使用者的 LaunchAgent(macOS)或 systemd user unit(Linux),執行 orca serve --supervise --no-pairing |
orca serve service status、uninstall | 查詢狀態、停止並移除服務(終端機 Daemon 與其 Session 保留) |
orca serve restore resume | 清除自動終端機還原的暫停狀態,並列出舊版 Client 要求的還原 |
orca serve service 系列與 --supervise 目前不支援 Windows,且需要主機已安裝 Orca App。orca serve 預設使用 Orca 自己的 Node 伺服器(orcad);若 orcad 無法運作會退回桌面 App 的伺服器並印出原因。封裝的 macOS App 目前一律使用桌面 App 的伺服器,可用 ORCA_SERVE_RUNTIME=electron 強制此路徑。
操作步驟:前景執行並配對
在伺服器安裝 Orca 與其 CLI,確認
command -v orca。取得 Tailscale 位址:
tailscale ip -4。前景執行:
orca serve --port 6768 --pairing-address 100.64.1.20指令會印出綁定的端點與 Runtime 配對 URL;把 URL 貼到 Client 的 Settings → Remote Orca Servers → Add Server。
按 Ctrl-C 停止。
同一台機器一次只用一種主機模式;若桌面版已在分享這台電腦,不要再啟動第二個
orca serve。
操作步驟:安裝為服務(Linux)
# 預覽將寫入的 unit 內容
orca serve service install --port 6768 --dry-run
# 安裝並查看狀態
orca serve service install --port 6768
orca serve service status --json
# Linux:讓 user service 在登出後仍執行
loginctl enable-linger "$USER"
loginctl show-user "$USER" --property=Linger服務模式不會把配對連結寫進日誌。要配對新 Client 時,先停止服務、在終端機前景執行一次 orca serve 取得連結,配對完成後再啟動服務;或從伺服器上的桌面 App 配對。
範例:容器或其他服務管理器
當容器編排器或既有服務管理器已負責重啟時,直接使用 --supervise:
orca serve --supervise --port 6768 --pairing-address orca-build.tailnet-name.ts.net --json位址錯誤時
若 orca serve 宣告了 Client 連不到的位址,停止後以正確位址重啟。不要使用萬用位址或 127.0.0.1 作為遠端 Client 的配對位址。
✅ 驗證方式
在伺服器執行:
orca serve service status --json loginctl show-user "$USER" --property=Linger預期輸出(示意):
{"ok":true, ... "running":true, ...} Linger=yes在 Client 執行並判讀:
nc -vz 100.64.1.20 6768 orca host list --jsonnc顯示 succeeded 而host list沒有伺服器:尚未完成配對,回到步驟 4。nc連不上:檢查 Tailscale ACL、主機防火牆,或服務是否在執行。Linger=no:登出後服務會停止,執行loginctl enable-linger。
企業治理考量
- 無頭伺服器上的
orca account add會把 Claude、Codex 憑證存在該主機;應使用團隊服務帳號或明確的個人歸屬,並記錄於資產清冊。 - 服務以「每使用者」身分執行,請用專用的系統帳號,不要用 root 或個人管理員帳號。
orca serve service uninstall不會終止終端機 Daemon 與其 Session;除役主機時需確認 Agent 程序已結束並清除資料。
18.6 Cloud VM 與每工作區環境
概念說明
每個 Worktree 可以從 Repo 中的 Recipe(orca.yaml 加生命週期腳本)啟動自己的隨需環境:雲端沙箱、VM 或本機 Docker 容器。建立 Worktree 時啟動,Suspend、Resume、Destroy 時收掉。Orca 只是薄薄一層包裝:供應商帳號、映像檔與帳單都是你的。產品 UI 中此功能標示為 Settings → Experimental → Cloud VM。
| 連線模式 | Recipe 的 create 腳本做什麼 | Orca 如何連入 |
|---|---|---|
| Orca server | 在環境中啟動 orca serve 並輸出 pairingCode | 以配對 URL 連入 |
| SSH | 不啟動伺服器,輸出 connection.type 為 ssh 的連線資訊 | 以 SSH 撥入 |
常見供應商包括 Vercel Sandbox、Fly、Modal、一般 SSH 主機與本機 Docker。
📌 查證狀態:官方文件明確記載(
environmentRecipes欄位與 Recipe 回傳格式取自官方 Repo 的orca-per-workspace-envSkill 指南與 orca.yaml 文件;Release notes v1.4.151–v1.4.244 未記載 Cloud VM 的變更)|來源:Ways to run Orca、orca.yaml 文件原始檔、orca-per-workspace-env 指南
操作步驟
開啟 Settings → Experimental → Cloud VM,此窗格包含簡短的建立指南與 Recipe、Runtime 控制項。
安裝或更新 Skill:
orca skills install --skill orca-per-workspace-env。在任一 Workspace 請 Agent 執行設定:
Use the orca-per-workspace-env skill to set up a per-workspace environment for this repo.Skill 會依序帶你完成:前置條件 → 基礎快照 → Agent 登入快照 →
orca.yamlRecipe → Doctor 驗證。其中建立快照與實際佈建屬於付費步驟,Skill 會在每一步前停下來徵求同意;Agent 登入需由你親自以 device-auth 流程完成。把含
environmentRecipes的orca.yaml合併到專案的主要 checkout(primary checkout)所在分支。只存在於 Feature 分支的 Recipe 不會出現在 Run on 選單。在 Recipes 看到 Recipe 後,建立 Worktree 時於 Run on 選擇它。
範例:orca.yaml(含一般設定與 Recipe)
# orca.yaml(Repository 根目錄)
scripts:
setup: |
pnpm install
archive: |
echo "Workspace archived"
setupAgentStartupPolicy: wait-for-setup
defaultTabs:
- title: Agent
- title: Git status
command: git status --short
worktree:
sharedDirectories:
- .cache
environmentRecipes:
- id: cloud-sandbox
name: Cloud Sandbox
create: ./scripts/orca-vm/cloud-sandbox-create.sh
suspend: ./scripts/orca-vm/cloud-sandbox-suspend.sh
resume: ./scripts/orca-vm/cloud-sandbox-resume.sh
destroy: ./scripts/orca-vm/cloud-sandbox-destroy.sh重點規則:
create必填,在本機 Repo 根目錄執行,stdout 只能輸出「一個」JSON 物件;進度與錯誤一律寫到 stderr。suspend與resume選填但需成對,從 stdin 讀取生命週期 JSON;resume必須重新輸出 Recipe JSON(配對資訊可能改變)。destroy只有在明確寫destroy: none時才可省略。- 整個檔案若 YAML 無效或有重複鍵,會被整份拒絕,連 setup、tabs、sharedDirectories 一起失效。
defaultTabs第一個分頁刻意不設 command:在桌面建立 Worktree 時,Agent 啟動會佔用第一個分頁。
範例:Orca server 模式的 create 輸出格式
{
"schemaVersion": 1,
"pairingCode": "orca-pairing-code-or-url",
"projectRoot": "/absolute/path/to/repo/on/remote",
"userData": { "provider": "example", "resourceId": "provider-resource-id" }
}pairingCode 與 projectRoot 為必填。在環境內啟動伺服器時,官方指南指定的寫法為 orca serve --port "$PORT" --project-root "$ABS_REPO_PATH_ON_REMOTE" --pairing-address "$EXTERNAL_WSS_URL" --recipe-json,不要自行增減旗標(例如沒有 --host)。
範例:destroy 腳本骨架(bash)
#!/usr/bin/env bash
set -euo pipefail
payload="$(cat)" # Orca 由 stdin 傳入生命週期 JSON
resource_id="$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.recipeResult?.userData?.resourceId ?? "")' "$payload")"
[ -n "$resource_id" ] || { echo "No resource id in lifecycle payload" >&2; exit 1; }
echo "Destroying ${resource_id}" >&2
# provider-cli remove "$resource_id" ← 換成供應商實際的刪除指令快照與憑證的硬性規則
| 規則 | 理由 |
|---|---|
| 絕不在已執行過 Orca Runtime 的機器上建立快照(或先刪除經驗證的 Orca user-data 目錄) | 首次 orca serve 會產生配對金鑰、裝置 Token 登錄與 Session 授權金鑰;被烤進快照後,所有 VM 會共用同一配對身分 |
不把秘密寫進 userData、Recipe JSON、State 檔、註解或 Commit | 這些檔案會進版控或被多台 VM 共用 |
Git Token 只透過供應商的臨時 --env 傳入,環境內用 GIT_ASKPASS 並於使用後刪除 | 避免 Token 出現在 clone URL 與歷史中 |
Agent 登入在 Runtime 內以 device-auth 完成並建立第二層快照,不要掛載或複製主機的 ~/.codex | 主機狀態檔在 Runtime 中會損壞;憑證短效時需定期重新登入 |
| 失敗的步驟要清除已建立的資源 | 避免付費資源殘留 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Recipe 在主要分支 | git show origin/main:orca.yaml | 輸出包含 environmentRecipes | 合併到主要 checkout 的分支後再試 |
| YAML 無重複鍵且有效 | 讓 Orca 載入後檢查 Settings → Experimental → Cloud VM 的 Recipes 是否出現 | 出現 Cloud Sandbox | 一般 YAML 檢查器可能接受重複鍵,Orca 不接受;逐一檢查鍵名 |
| 靜態接線正確(免費) | 依指南執行 orca vm recipe doctor cloud-sandbox --repo-path . --json | 沒有 fail 也沒有 warn | ok: true 但有 warn 時仍不算通過,逐一處理 warn |
| 腳本可執行 | ls -l scripts/orca-vm/ | 各腳本有執行權限 | chmod +x scripts/orca-vm/*.sh |
| 快照已登入 | 由 State 檔中的 snapshotId 啟動環境後執行 Agent 的狀態指令並看結束碼 | 結束碼為 0 | 重新執行登入快照步驟 |
| 會被銷毀 | 建立後再刪除測試 Workspace,到供應商主控台確認 | 資源已不存在 | 修正 destroy 腳本並手動清除殘留 |
📌 查證狀態:依官方說明延伸(教學推論)—
orca vm recipe doctor取自官方 Repo 的 Skill 指南,v1.4.244 文件站的 CLI reference 頁未收錄;請以orca skills get orca-per-workspace-env --full取得的版本為準,付費的--provision自我測試須先取得預算核准|來源:orca-per-workspace-env 指南
企業治理考量
- 費用:每個 Workspace 一台 VM,務必確認 destroy 有效;在雲端帳號設定預算告警與資源標籤(例如
owner、ticket)。 - 映像檔:基礎快照應由平台團隊集中建立與掃描弱點,定期重建。
- 資料駐留:選擇符合法規的區域;金融或政府專案確認供應商的合規認證。
- 自備雲端(BYO):Orca 不提供 VPS,責任邊界在你的雲端帳號。
18.7 遠端模式選型指引
決策表
| 情境或需求 | 建議模式 | 理由 | 主要注意事項 |
|---|---|---|---|
| 筆電效能足夠、任務短 | Local | 最簡單、延遲最低 | 筆電睡眠即中斷 |
| 已有開發主機或 VPS,想讓 Agent 在那裡跑,不想再裝第二套 Runtime | SSH | 筆電 Orca 擁有 Runtime,主機只負責執行 | 主機需 git 與 Agent CLI |
| 需要 GPU、大記憶體或靠近資料的算力 | SSH | 直接使用該主機資源 | 主機與正式環境隔離 |
| 筆電睡眠後 Agent 仍要繼續,且手機要接續同一 Session | Remote Orca Server | 伺服器擁有完整 Session | 伺服器需常駐並在 tailnet 上 |
| 多台 Client(筆電、Web、手機、自動化)共用 | Remote Orca Server | 單一常駐 Runtime | 授權盤點與撤銷 |
| 長期排程自動化 | Remote Orca Server | 排程不受筆電睡眠影響 | 伺服器上的 Agent 帳號歸屬 |
| 無頭 Linux 或 VM 作為伺服器 | Remote Orca Server(orca serve) | 不需桌面視窗,可服務化 | Windows 不支援服務指令 |
| 每個任務都要乾淨隔離、用完即丟 | Cloud VM | Recipe 定義、隨 Worktree 銷毀 | 雲端費用與快照治理 |
| 不信任的程式碼或高風險 Agent 實驗 | Cloud VM | 隔離爆炸半徑 | 不在快照中放憑證 |
| 企業內網、主機只能經堡壘機與 MFA 存取 | SSH | 支援 ProxyJump、MFA、Kerberos、FIDO2 | 由系統 OpenSSH 處理特殊機制 |
可以在同一安裝中混用:本機 Worktree 處理小修改、SSH 跑 GPU 主機、Recipe 提供類 CI 的隔離。
決策流程圖
flowchart TD
S["開始:這個任務要在哪裡執行?"] --> Q1{"每個任務都需要<br/>乾淨且可拋棄的環境?"}
Q1 -- "是" --> CV["Cloud VM<br/>每工作區環境"]
Q1 -- "否" --> Q2{"需要在筆電關機後持續執行<br/>或讓手機、自動化共用?"}
Q2 -- "是" --> Q3{"伺服器有桌面環境<br/>且可保持登入?"}
Q3 -- "是" --> RSD["Remote Orca Server<br/>桌面版加 Tailscale"]
Q3 -- "否" --> RSS["Remote Orca Server<br/>orca serve"]
Q2 -- "否" --> Q4{"需要筆電以外的算力<br/>或資料只在某主機上?"}
Q4 -- "是" --> SSHM["SSH Worktrees"]
Q4 -- "否" --> LOC["Local"]如何閱讀此圖:從上往下依序回答問題。第一個問題先篩出「隔離需求」(Cloud VM),第二個問題判斷「是否需要常駐 Runtime」(Remote Orca Server),再依伺服器有無桌面環境選擇桌面版或 orca serve;以上皆否時,看是否需要遠端算力決定 SSH 或 Local。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 選型有書面理由 | 檢查團隊的選型紀錄是否對應決策表的情境列 | 每個遠端主機或伺服器都有對應情境與負責人 | 補上紀錄,或移除無主主機 |
| 實際執行位置相符 | 在各 Worktree 終端機執行 hostname | 與選型一致 | 檢查建立時的 Run on |
| 主機清單可盤點 | orca host list --json | 只出現核准的本機、SSH 目標與伺服器 | 在 Settings 移除未核准者 |
18.8 本章 Review 與驗證清單
- 能說出 Local、SSH、Remote Orca Server、Cloud VM 四種模式的 Runtime 擁有者與適用情境
- 能說明 SSH 模式不需要手動執行
orca serve,並知道 Managed Orca server 的用途 - 已在 Settings → SSH 新增並測試一個 SSH 目標,且在其上建立 Worktree
- 已用
hostname驗證 Agent 實際在遠端執行 - 知道「Allow this host’s orca CLI to control Orca」的預設值與開啟時機
- 能處理主機金鑰變更,並說明為何不可直接刪除 known_hosts
- 能說明 Kerberos 與 FIDO2 主機為何改用系統 OpenSSH
- 已用 Tailscale 完成一次 Remote Orca Server 配對,並示範撤銷授權
- 能用
orca serve --pairing-address啟動無頭伺服器,並說明服務模式與 linger - 能寫出含
environmentRecipes的orca.yaml,並說明 Recipe 必須在主要 checkout 分支 - 能說明「不可在執行過 Orca Runtime 的機器上建立快照」的原因
- 能用 18.7 決策表與流程圖為三個實際任務選出執行模式
第十九章 Mobile Companion 行動裝置
Orca Mobile 讓你在手機或平板上查看並操作電腦(或伺服器)上執行中的 Agent:即時看輸出、回覆提示、切換工作區、啟動新 Agent,甚至提交程式碼。手機本身不執行 Agent,它是遠端 Runtime 的 Client。
📌 查證狀態:官方文件明確記載(Mobile companion 為 Beta)|來源:Mobile companion、Install the Android APK
v1.4.150 之後的主要變更
| 版本 | 變更 |
|---|---|
| v1.4.237 | 行動端加入 Notes |
| v1.4.243 | 行動端淺色與深色主題、iPhone 雙欄(iPhone Duo)版面 |
| v1.4.244 | iOS 正式改由 App Store 發佈,TestFlight 測試管道移除 |
📌 查證狀態:官方文件明確記載|來源:Orca Releases
19.1 平台支援與安裝
| 平台 | 取得方式 | 備註 |
|---|---|---|
| iPhone | App Store 搜尋 Orca | v1.4.244 起不再使用 TestFlight |
| iPad | App Store | 單一側邊欄版面 |
| Android | 官方下載頁提供的 app-release.apk | 目前不在 Google Play,僅能側載 |
Android 安裝步驟
- 在 Android 手機上用 Chrome 開啟官方 Mobile 下載頁,點 Android 下載。
- 下載完成後點通知或在「下載」中開啟
app-release.apk。 - 系統詢問時,暫時允許 Chrome「安裝不明應用程式」。
- 安裝完成後,立即回到設定關閉該權限。
- Samsung 裝置若被 Auto Blocker 擋下,可暫時關閉 Auto Blocker,安裝後再開啟。
- 不要關閉 Google Play Protect;若 Play Protect 發出警告,先確認 APK 來源為官方下載頁。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| App 已安裝 | 開啟 Orca App | 顯示配對或伺服器清單畫面 | 重新安裝;iOS 確認是 App Store 版本 |
| 側載權限已收回 | Android 設定 → 應用程式 → Chrome → 安裝不明應用程式 | 顯示「不允許」 | 手動關閉 |
| Play Protect 仍啟用 | Play 商店 → Play Protect | 顯示已開啟 | 立即開啟 |
| 版本相容 | App 與桌面版都更新到最新 | 配對後不出現更新提示 | 兩邊都更新;通訊協定有版本控管 |
企業治理考量(MDM 與側載)
- Android APK 屬於側載安裝,企業受管裝置應由 MDM 統一派送或列入允許清單,而不是讓員工自行開啟「安裝不明應用程式」。
- 若 MDM 政策禁止側載,請以 iOS 或桌面端替代,不要要求員工暫時解除政策。
- 在資產清冊記錄「哪些裝置安裝了 Orca Mobile、配對到哪台主機」。
📌 查證狀態:依官方說明延伸(教學推論)— MDM 派送與資產清冊為企業治理建議,非官方要求|來源:Install the Android APK
19.2 配對流程
概念說明
手機必須與一台「主機」配對:可以是執行中的 Orca 桌面版,也可以是 orca serve 無頭伺服器。配對碼是一次性的,幾分鐘後過期;每支手機配對後取得自己的裝置 Token。
| 連線方式 | 條件 | 特性 |
|---|---|---|
| Orca Relay(建議) | 桌面與手機都登入 Orca 帳號 | 不需要同一網路,也不需要自備位址 |
| LAN 或私有網路 | 手機能連到主機位址(同網路或 Tailscale) | 需要指定位址;桌面 App 關閉時 Session 中斷 |
操作步驟:從桌面版配對
- 在桌面 Orca 開啟帳號或狀態選單,選擇配對行動裝置,取得一次性配對碼(或 QR Code、深層連結)。
- 在手機開啟 Orca,點 Pair,貼上配對碼或直接開啟深層連結。
- 完成後手機會列出主機的 Workspaces。
- 主機顯示在手機上的名稱可在桌面 Settings → Remote Orca Servers 設定。
操作步驟:從無頭伺服器配對
# 在伺服器上,以 Tailscale 位址前景啟動並印出行動端 QR Code
orca serve --pairing-address 100.64.1.20 --mobile-pairing用手機掃描終端機印出的 QR Code,或把行動配對連結傳到手機開啟。手機必須能連到該位址(例如手機也安裝 Tailscale 並登入同一 tailnet)。預設埠號為 6768。
sequenceDiagram
participant D as 桌面 Orca 或 orca serve
participant P as Orca Mobile
participant R as Orca Relay
D->>D: 產生一次性配對碼
D-->>P: 配對碼、QR Code 或深層連結
P->>R: 以配對碼請求配對(Relay 模式)
R->>D: 轉送配對請求
D->>D: 核發此裝置專屬 Token
D-->>P: 回傳裝置 Token
P->>D: 之後以 Token 連線並同步 Workspaces如何閱讀此圖:配對碼只用一次,真正長期有效的是主機為「這支手機」核發的裝置 Token。Relay 模式下請求經 Orca Relay 轉送;LAN 模式下手機直接連到主機位址,流程相同但不經 Relay。
注意事項
- 在手機上修改主機名稱或位址不會重新配對;位址改變時可直接編輯,不需刪除重配。
- 通訊協定有版本控管,若出現更新提示,手機 App 與桌面版都要更新。
- 走 LAN 時,關閉桌面 App 就會中斷手機 Session;要長時間可用,改用 Remote Orca Server(第十八章)。
✅ 驗證方式
在伺服器執行(無頭伺服器情境):
tailscale ip -4 orca serve --pairing-address "$(tailscale ip -4 | head -n 1)" --mobile-pairing預期輸出:終端機印出綁定端點、行動配對 QR Code 與連結。
在手機上:
- 配對成功後看到主機名稱與 Workspace 清單。
- 開啟任一終端機分頁並看到即時輸出。
判讀:
- 配對碼過期:重新產生,幾分鐘內完成。
- 手機一直轉圈:確認手機已加入同一 tailnet,或改用 Relay。
- 出現 Authentication failed:見下方疑難排解表的排解順序。
連線疑難排解
| 症狀 | 可能原因 | 處理方式 |
|---|---|---|
| 畫面一直轉圈 | 連線狀態未更新 | 強制重新整理(下拉或重新開啟畫面) |
| Authentication failed | 裝置 Token 已被撤銷或失效 | 依序嘗試 Retry → Re-pair → Remove 後重新配對 |
| 出現更新提示 | 手機與主機通訊協定版本不同 | 手機 App 與桌面版都更新 |
| LAN 連線突然中斷 | 桌面 App 關閉或電腦睡眠 | 重新開啟桌面,或改用 Relay、Remote Orca Server |
| 配對碼無效 | 配對碼已過期或已使用 | 重新產生配對碼 |
| 主機位址改了 | 網路變更 | 在手機編輯主機位址即可,不需重新配對 |
19.3 行動端 Chat 與 Quick Commands
19.3.1 Chat UI 與 Composer
手機上的 Agent 分頁可用兩種方式呈現:原始終端機,或對話式的 Chat UI。Chat UI 支援 Claude、Codex、Grok、OpenCode、OMP 與 Pi。
| 設定層級 | 位置 | 說明 |
|---|---|---|
| 裝置預設 | 手機 Settings → Chat UI | 未變更前預設為終端機檢視 |
| 單一 Session | 長按分頁 | 為此 Session 覆寫預設 |
| Composer 功能 | 用途 |
|---|---|
@ 提及 | 引用檔案或資源 |
| 斜線指令 | 送出 Agent 支援的 slash command |
| 圖片 | 附加截圖或照片 |
| 語音輸入 | 以聽寫輸入 Prompt |
| Model pill | 查看或切換模型 |
| Live 模式 | 即時跟隨輸出 |
| 輔助按鍵列 | 提供 Tab、Shift+Tab 等手機鍵盤缺少的按鍵 |
終端機檢視的文字大小可在 50% 至 200% 間調整,自動修正預設關閉,避免手機鍵盤改寫指令。
範例 Prompt
請只回報目前進度,不要修改任何檔案:
1. 已完成哪些步驟
2. 目前卡在哪裡
3. 下一步需要我決定什麼🧑⚖️ 人工 Review 要點
- 在手機上只做「核准、回答、補充指示」,避免在小螢幕上審查大型 Diff
- 需要合併或發佈的決策,回到桌面完成完整 Review(第十一章)
- 確認 Prompt 沒有夾帶從手機剪貼簿貼上的秘密
19.3.2 Quick Commands
Quick Commands 是一鍵送出的預存指令,範圍可設為全域或單一專案,且與桌面版同步。
| 類型 | 送出內容 | 範例 |
|---|---|---|
| Terminal Command | 在終端機執行的 Shell 指令 | git status --short |
| Agent Prompt | 送給 Agent 的文字 | 「執行測試並只回報失敗項目」 |
範例:建議建立的 Quick Commands
[Terminal Command|全域] git status --short
[Terminal Command|專案] pnpm test --silent
[Agent Prompt|全域] 請總結目前進度,不要修改任何檔案。
[Agent Prompt|專案] 停止目前工作,等待我回到桌面後再繼續。📌 查證狀態:教學示例(非官方)— 指令內容為示意;Quick Commands 的類型、範圍與同步為官方記載|來源:Mobile companion
其他行動端工作區操作
| 功能 | 說明 |
|---|---|
| 建立 Workspace | 模式包含 Smart、GitHub、Linear、GitLab、Branch、Name |
| 啟動 Agent | 在 Workspace 內啟動新的 Agent |
| 批次關閉分頁 | 一次關閉多個分頁 |
| 帳號切換 | 切換 Agent 供應商帳號(包含 Codex 額度重置資訊) |
| 推播通知 | Agent 需要注意或完成時通知 |
| 檔案樹與 Notes | 瀏覽 Worktree 檔案;Notes 於 v1.4.237 加入 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Chat UI 可用 | 長按一個 Claude 或 Codex 分頁切換為 Chat UI | 顯示對話氣泡與 Composer | 該 Agent 不在支援清單,維持終端機檢視 |
| 訊息送達 | 在 Composer 送出上面的範例 Prompt | 桌面同一分頁出現相同輸入與回應 | 檢查連線狀態與版本 |
| 特殊按鍵 | 用輔助按鍵列送出 Shift+Tab | Agent 切換模式(例如 plan mode) | 改用終端機檢視操作 |
| Quick Command 同步 | 在手機建立專案範圍的 git status --short | 桌面同一專案的 Quick Commands 也出現 | 確認手機與桌面連到同一主機 |
| Quick Command 執行 | 在手機某 Worktree 執行它 | 列出變更檔案;空輸出代表工作樹乾淨 | 確認目前選取的是正確 Worktree |
19.4 行動端 Source Control 與瀏覽器檢視
Source Control
手機上的 Source Control 面板可以 Stage、Unstage、Commit,並以 Link an existing PR 把 Workspace 連到既有的 Pull Request。適合「Agent 已完成、你在外面先做小幅確認並提交草稿」的情境;完整審查仍應回到桌面 Diff Viewer。
操作步驟
- 在手機開啟 Workspace 的 Source Control 面板。
- 檢視變更檔案清單,只 Stage 你確認過的檔案。
- 輸入 Commit 訊息並 Commit。
- 若團隊已有對應 PR,用 Link an existing PR 連結。
- 回到桌面後在 Diff Viewer 完成完整 Review,再 Push 或合併。
瀏覽器檢視
行動端可開啟 Workspace 的瀏覽器分頁,並以 Web 與 Mobile 切換檢視,方便快速確認 Agent 修改的頁面在行動版面的呈現。
✅ 驗證方式
在手機 Commit 一個測試變更後,於桌面該 Worktree 終端機執行:
git log -1 --stat git status --short預期輸出(示意):
commit 3f9c2ab... docs: update checkout notes notes/checkout.md | 4 ++--判讀:Commit 出現在預期分支且只包含你 Stage 的檔案;若含有未預期檔案,用
git reset --soft HEAD~1撤回後重新整理(尚未 Push 時)。瀏覽器的 Mobile 切換若沒有改變版面,確認頁面本身有響應式設計。
19.5 行動端安全治理
手機是最容易遺失的裝置,卻能直接驅動在伺服器上持有憑證的 Agent。以下政策建議請納入企業行動裝置管理規範。
| 政策項目 | 建議做法 |
|---|---|
| 裝置 Token | 每支手機獨立 Token;定期盤點已配對裝置並移除不再使用者 |
| Relay 帳號 | Relay 需登入 Orca 帳號,使用公司核准的帳號並啟用強驗證 |
| 遺失裝置 | 立即在主機端撤銷該裝置授權,並輪替該裝置可接觸的 Agent 憑證 |
| 鎖定畫面通知 | 推播可能顯示 Agent 輸出片段,受管裝置應設定鎖定畫面不顯示通知內容 |
| 手機帳號切換 | 從手機可切換 Agent 供應商帳號,限制只有帳號擁有者可操作 |
| 高風險操作 | 從手機 Commit 只限草稿分支;合併、發佈與正式環境操作回到桌面 Review |
| 側載 | Android APK 由 MDM 派送或核准,不讓員工自行解除安全政策 |
| 版本 | 手機 App 與主機同步更新,避免舊版協定 |
📌 查證狀態:依官方說明延伸(教學推論)— 裝置 Token、Relay、撤銷與版本控管為官方記載,政策建議為企業治理推論|來源:Mobile companion、Remote Orca Servers
遺失裝置處理程序
- 主機若為 Remote Orca Server,在 Settings → Remote Orca Servers → Shared Server Access 撤銷該裝置授權。
- 透過 MDM 遠端鎖定或清除裝置。
- 輪替該主機上 Agent 供應商帳號的憑證(
orca account list盤點後重新登入)。 - 檢查遺失期間的 Session History 與 Git 紀錄是否有異常操作。
- 新裝置重新配對,取得新的裝置 Token。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 撤銷生效 | 撤銷測試手機授權後在該手機開啟 Orca | 出現 Authentication failed,無法看到 Workspace | 確認撤銷的是正確授權 |
| 通知不洩漏 | 鎖定手機後觸發 Agent 完成通知 | 鎖定畫面只顯示 App 名稱 | 調整裝置或 MDM 通知預覽設定 |
| 憑證已盤點 | 在主機執行 orca account list | 只列出核准的帳號 | 移除未核准帳號並重新登入 |
| 側載權限已收回 | Android 設定檢查 Chrome 的安裝不明應用程式權限 | 不允許 | 手動關閉或交由 MDM 強制 |
19.6 本章 Review 與驗證清單
- 已依平台正確安裝:iOS 用 App Store、Android 用官方 APK 並收回側載權限
- 能說明 Relay 與 LAN 配對的差異,以及為何 LAN 會隨桌面關閉而中斷
- 已用
orca serve --pairing-address <addr> --mobile-pairing完成一次無頭伺服器配對 - 知道配對碼一次性且會過期,長期有效的是每支手機的裝置 Token
- 能切換 Chat UI 與終端機檢視,並知道支援的 Agent
- 已建立至少一個 Terminal Command 與一個 Agent Prompt 的 Quick Command,並確認與桌面同步
- 能在手機完成 Stage、Commit,並回到桌面以
git log -1 --stat驗證 - 知道 Authentication failed 的排解順序:Retry、Re-pair、Remove
- 已擬定遺失裝置的撤銷與憑證輪替流程,並設定鎖定畫面不顯示通知內容
第二十章 AI Coding Workflow 與 Prompt Engineering
本章是全書「方法論」的起點。前面各章教的是 Orca 的功能怎麼操作;本章要回答的是:一個需求從進門到上線,人與 AI 各自負責哪一段、每一段交出什麼、又該如何驗證。本章所有指引都遵守同一個原則——AI 產出的任何東西,在人類用可重現的方法驗證之前,一律視為草稿。
📌 查證狀態:本章流程與 Prompt 設計原則屬依官方說明延伸(教學推論);其中引用的 Orca 功能(Worktree、Diff Viewer、Annotate AI Diff、Worktree Checkpoints、Orchestration)為官方文件明確記載|來源:Worktrees、Annotate AI Diff、Worktree checkpoints
20.1 端到端 AI Coding 流程
概念說明
AI 讓「寫程式」這一段變得又快又便宜,但也讓「錯誤產生的速度」同步變快。因此企業級 AI Coding 流程的設計重點不是「讓 AI 做更多」,而是在每個階段之間設立關卡(Gate):沒有通過關卡的產出,不得流向下一階段。
flowchart LR
REQ["需求"] --> G0{"G0 需求可驗收?"}
G0 -- "否" --> REQ
G0 -- "是" --> SPEC["任務規格書"]
SPEC --> G1{"G1 規格經人工核可?"}
G1 -- "否" --> SPEC
G1 -- "是" --> DISPATCH["Orca 分派至 Worktree"]
DISPATCH --> CODE["Agent 實作與自測"]
CODE --> G2{"G2 自動化檢查通過?"}
G2 -- "否" --> CODE
G2 -- "是" --> REVIEW["人工 Diff 審查"]
REVIEW --> G3{"G3 審查意見清零?"}
G3 -- "否,Annotate 回送" --> CODE
G3 -- "是" --> PR["Commit Push 與 PR"]
PR --> G4{"G4 CI 與核准者簽核?"}
G4 -- "否" --> CODE
G4 -- "是" --> MERGE["合併與部署"]
MERGE --> RECORD["驗收紀錄歸檔"]如何閱讀此圖:方框是「工作」,菱形是「關卡」。注意所有「否」的箭頭都往回走——AI 的價值在於讓回圈跑得很快,而不是讓人跳過關卡。G0、G1、G3、G4 必須由人類判定;G2 可完全自動化。
各階段的輸入、產出與關卡
| 階段 | 主導者 | 產出物 | 關卡判準(可驗證) |
|---|---|---|---|
| 需求 | 人(PO/PM) | 使用者故事、驗收條件 | G0:每條驗收條件都能寫成一個測試或一個可觀察結果 |
| 任務規格書 | 人+單一 Agent 協助澄清 | 20.4 範本的規格書 | G1:範圍、禁止事項、驗收指令皆已填寫,Tech Lead 核可 |
| 分派 | 人(Tech Lead) | Worktree、分支、Prompt | 每個 Worktree 對應一份規格、範圍不重疊 |
| 實作與自測 | Agent | Diff、測試、變更摘要 | G2:build、lint、test、secret scan 全綠 |
| 人工審查 | 人(Reviewer) | Annotate 意見、核准 | G3:所有意見已 Resolve,無未解釋的檔案變更 |
| PR 與合併 | 人+CI | PR、CI 報告 | G4:CI 綠燈、必要核准者簽核 |
| 歸檔 | 人 | 驗收紀錄(見 22.7) | 紀錄可讓第三方重現驗證結果 |
操作步驟(最小可行流程)
- 需求進門時,先用 G0 判準檢查:把每條驗收條件改寫為「執行 X,應看到 Y」。改寫不出來的,退回需求方。
- 開一個單一 Agent 對話(建議用 Native Chat),請 Agent 協助把需求整理成 20.4 的任務規格書,由人修改並核可。
- 在 Orca 為每份規格建立一個 Worktree,分支命名帶需求編號(例:
feat/ORD-1423-refund-api)。 - 把規格書貼給 Agent,要求它在關鍵節點以 Worktree Checkpoint 回報進度(見 16.5 節)。
- Agent 回報完成後,由你自己在該 Worktree 重新執行驗收指令(G2)。
- 打開 Diff Viewer 逐檔審查,用 Annotate AI Diff 留言並批次送回(G3,見 14.2 節)。
- 意見清零後 Commit、Push、建立 PR,等待 CI 與核准者(G4)。
- 合併後填寫驗收紀錄(22.7 節)並歸檔。
範例:用 CLI 建立帶規格的 Worktree 並要求 Checkpoint
orca worktree create --name ORD-1423-refund-api --agent claude \
--prompt "請先閱讀 docs/specs/ORD-1423.md,依規格實作。每完成一個驗收條件,就執行 orca worktree set --worktree active --comment 回報進度。" \
--json# Agent 回報後,人類讀取目前狀態
orca worktree current --json✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Worktree 已建立且分支正確 | git worktree list | 出現 ORD-1423-refund-api 對應路徑與分支 | 檢查 Repository 是否已加入 Orca(orca repo list --json) |
| 規格書已被 Agent 讀取 | 在 Agent 終端機或 Chat 檢視其第一輪輸出 | Agent 複述了規格中的範圍與禁止事項 | 停止 Agent,把規格內容直接貼進 Prompt |
| Checkpoint 正常回報 | orca worktree current --json | comment 欄位為最新進度描述 | 確認 Orca CLI 已註冊(第十六章 16.1 節) |
| 各關卡皆有人判定 | 檢查驗收紀錄的簽核欄位 | G0、G1、G3、G4 皆有姓名與日期 | 退回補簽,不得合併 |
⚠️ 注意事項:需求還在變動時就平行分派,是最昂貴的錯誤——需求一改,所有 Worktree 的產出一起作廢。G0、G1 沒過,就不要進入 Orca 分派。
企業治理考量:關卡的「判定人」必須是具名的真人,並寫進團隊的工作規範;這是稽核時最常被追問的一點(「這段 AI 程式碼是誰核准上線的?」)。
20.2 Orca 在各階段的角色
概念說明
Orca 是 ADE(Agentic Development Environment),不是 CI/CD 平台,也不是需求管理系統。它的強項集中在「分派 → 實作 → 審查 → 提交」這段迴圈。理解它不做什麼,與理解它做什麼同樣重要。
| 流程階段 | Orca 提供的能力 | Orca 不負責(需搭配既有工具) | 對應章節 |
|---|---|---|---|
| 需求與任務來源 | 從 GitHub Issue、Linear、Jira、GitLab 建立 Workspace;orca reference 連結需求單 | 需求優先序、排程與核准流程 | 第十五章 |
| 規格澄清 | Native Chat 單一 Agent 對話;Session History 可回溯 | 規格的正式核可與版控(應存入 repo) | 第七章、第九章 |
| 分派 | Parallel Worktrees、Agent 選擇、Orchestration(orca orchestration task-create、worker-start) | 人力配置決策 | 第十一章、第十六章 |
| 實作 | 每個 Worktree 獨立終端機、內建瀏覽器、Design Mode | 編譯器、測試框架本身 | 第十二章、第十三章 |
| 進度回報 | Worktree Checkpoints、Agent 狀態、Notifications、Agents Feed | 專案管理報表 | 第十章、第十六章 |
| 審查 | Diff Viewer、Annotate AI Diff、Attribution 歸屬標記 | 強制核准規則(由 GitHub 分支保護等負責) | 第十四章 |
| 提交 | Commit、Push、Force push with lease、建立 PR、Fix with AI | CI 執行、部署 | 第十四章、第十五章 |
| 自動化 | Scheduled Automations、orca CLI | 正式環境排程與告警 | 第十七章 |
| 監看 | Mobile Companion 回覆與核准 | APM、日誌平台 | 第十九章 |
範例:把需求單連到 Worktree,讓審查者能追溯來源
orca worktree create --name ORD-1423-refund-api \
--reference https://linear.app/acme/issue/ORD-1423 --json
orca reference list --worktree name:ORD-1423-refund-api --json✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 需求單已連結 | orca reference list --worktree name:ORD-1423-refund-api --json | 輸出包含 Linear 連結 | 確認 Linear 已於 Settings → Integrations 設定 |
| 團隊理解 Orca 邊界 | 請成員說明「CI 由誰執行」 | 回答為既有 CI(例:GitHub Actions),而非 Orca | 回到本表重新說明 |
❌ 常見錯誤:把 Orca 的 Commit 按鈕當作「合併核准」。Orca 的 Commit 與 Push 只是 git 操作;合併核准仍應由遠端平台的分支保護規則與 Code Owners 強制執行。
20.3 多 Agent 情境的 Prompt 設計原則
概念說明
在 Orca 中,一份 Prompt 常被複製給多個 Worktree 同時執行(同題競賽),或被拆成多份分給不同角色(分工協作)。單人對話時可以「邊聊邊修正」,多 Agent 平行時則不行——模糊會被放大成 N 份彼此矛盾的產出。以下八條原則,每條都附範例與審查要點。
20.3.1 原則一 明確範圍邊界
指定「可以改哪裡」與「不准改哪裡」。審查時用 git diff --name-only 即可客觀驗證。
範例 Prompt
【範圍】只允許修改:
- src/modules/refund/**
- test/modules/refund/**
【禁止】不得修改 src/shared/**、package.json、任何 migration 檔。
若你判斷必須修改禁止範圍,請停止並以「BLOCKED: 原因」回報,不要自行修改。🧑⚖️ 人工 Review 要點
-
git diff --name-only main...HEAD的每一行都落在允許範圍內 - 若 Agent 回報 BLOCKED,理由具體(指出哪個檔案、為何必須改)
- 沒有「順手」修改的格式化或重新命名
20.3.2 原則二 先有契約再平行
多個 Agent 共用的介面(API Schema、資料表、事件格式)必須先定稿並存入 repo,再當作輸入分派。
範例 Prompt
本任務的 API 契約已定稿於 docs/contracts/refund-api.yaml(OpenAPI 3.1)。
你只能實作契約中已定義的端點與欄位;若發現契約不足,請列在「未解決問題」中,不得自行新增欄位。🧑⚖️ 人工 Review 要點
- 實作的端點、欄位名稱、型別與契約逐一相符(可用契約測試工具或 schema 驗證)
- 契約檔本身在此 Worktree 中未被修改(
git diff main...HEAD -- docs/contracts/應為空)
20.3.3 原則三 要求結構化回報
規定 Agent 完成時的回報格式,讓審查者不必從頭讀懂全部程式碼。
範例 Prompt
完成後請以下列格式回報,不要省略任何段落:
## 變更摘要(每個檔案一行,說明為什麼改)
## 假設(你在規格不明時自行做的決定)
## 未解決問題
## 驗證證據(實際執行的指令與完整輸出末 20 行)🧑⚖️ 人工 Review 要點
- 「變更摘要」的檔案清單與
git diff --stat完全一致(多或少都要追問) - 每一條「假設」都由人判定是否接受;不接受者寫成 Annotate 意見
- 「驗證證據」是真實輸出而非「測試已通過」這類口頭宣稱
20.3.4 原則四 驗收標準寫成可執行指令
「怎樣算完成」必須能被機器或人重新執行並得到同一結果。
範例 Prompt
【驗收條件】以下指令全部 exit code 為 0 才算完成:
1. npm run lint
2. npm run typecheck
3. npm test -- test/modules/refund
並且 test/modules/refund 新增的測試至少涵蓋:全額退款、部分退款、超額退款被拒、重複請求冪等。🧑⚖️ 人工 Review 要點
- 審查者在自己的終端機重新執行三條指令,結果與 Agent 回報一致
- 四種情境各自有對應的測試名稱可指認
- 沒有用
.skip、xit、@Disabled等方式讓測試「通過」
20.3.5 原則五 明確停止條件
告訴 Agent 何時必須停下來問人,而不是自行猜測。這在 Yolo 權限模式下尤其重要(見 28.2 節)。
範例 Prompt
遇到以下任一情況,立即停止並回報,不要繼續:
- 需要新增或升級任何相依套件
- 需要連線到 localhost 以外的網路位址
- 測試連續兩次修正後仍失敗
- 需要讀取 .env 或任何憑證檔🧑⚖️ 人工 Review 要點
-
git diff main...HEAD -- package.json package-lock.json無未經同意的相依變更 - Agent 的終端機紀錄中沒有
cat .env、curl外部網址等違反停止條件的指令
20.3.6 原則六 平行 Prompt 必須自足
同題競賽時,每個 Agent 都看不到彼此,Prompt 不可依賴「上一輪對話」或「另一個 Agent 的結果」。
範例 Prompt
你是三個平行實作者之一,看不到其他人的產出。請只依本訊息與 docs/specs/ORD-1423.md 作業。
不要假設任何本訊息未提到的既有程式碼慣例;若需要,先用 git grep 查證再引用。🧑⚖️ 人工 Review 要點
- 三個 Worktree 都能各自獨立通過驗收指令
- 比較三份實作時,使用同一份評分表(正確性、範圍、測試品質、可讀性)
20.3.7 原則七 不在 Prompt 中放入機敏資訊
Prompt 會進入 Agent 供應商的模型服務,也會留在本機 Session History;遠端與行動端情境下還可能出現在其他裝置畫面上。
範例 Prompt
資料庫連線請使用環境變數 DATABASE_URL(已由開發環境注入),不要在程式碼、測試或回報中輸出它的值。
測試資料請使用 test/fixtures/ 下的假資料,不得使用任何真實客戶資料。🧑⚖️ 人工 Review 要點
- 對本次 Diff 執行 secret scan(28.3 節的 gitleaks 指令)無發現
- Agent 回報與測試輸出中沒有出現連線字串、Token、身分證號等
20.3.8 原則八 用範例取代形容詞
「寫得乾淨一點」「效能好一點」無法驗證;給出輸入與輸出範例才能驗證。
範例 Prompt
金額格式化規則請依下列範例,並為每一列寫成一個單元測試:
輸入 1234.5 → 輸出 "1,234.50"
輸入 0 → 輸出 "0.00"
輸入 -12.345 → 輸出 "-12.35"(四捨五入)
輸入 null → 拋出 InvalidAmountError🧑⚖️ 人工 Review 要點
- 四個範例各有一個測試,且斷言值與範例逐字相同
- 邊界值(負數、四捨五入方向)的實作與範例一致,而非 Agent 自行選擇的規則
✅ 驗證方式(本節八原則的整體檢查)
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 範圍邊界 | git diff --name-only main...HEAD | 全部在允許路徑內 | 以 Annotate 要求還原越界檔案 |
| 驗收可重現 | 審查者自行執行驗收指令 | exit code 皆為 0 | 退回並附上失敗輸出 |
| 回報結構完整 | 對照原則三的四個段落 | 四段皆存在且內容具體 | 要求 Agent 補齊 |
| 無機敏資訊 | gitleaks git --log-opts="main..HEAD" -v | no leaks found | 依 28.3 節處理外洩 |
20.4 任務規格書範本
概念說明
任務規格書(Task Spec)是人與 Agent 之間的「合約」。它同時有三個用途:給 Agent 的 Prompt 輸入、給審查者的驗收依據、給稽核的留存證據。建議存放在 repo 的 docs/specs/ 下並納入版控,讓規格與程式碼一起被審查。
範本(複製後填寫)
# 任務規格書:<需求編號> <任務標題>
## 1. 基本資訊
- 需求來源:<Issue/Linear/Jira 連結>
- 規格撰寫者:<姓名> 核可者:<Tech Lead 姓名> 核可日期:<YYYY-MM-DD>
- 指派 Agent:<Agent 名稱與權限模式,例:Claude Code/Manual>
- Worktree 與分支:<例:feat/ORD-1423-refund-api>
- 風險等級:<低/中/高>(高風險需雙人審查)
## 2. 背景與目標
<一段話說明為什麼要做、做完後使用者能做到什麼>
## 3. 範圍
- 允許修改:<路徑清單>
- 禁止修改:<路徑清單>
- 非目標(本次不做):<條列>
## 4. 輸入與參考
- 契約/介面:<檔案路徑>
- 既有慣例參考:<檔案路徑>
- 測試資料:<路徑;不得使用真實資料>
## 5. 驗收條件
| 編號 | 條件(可觀察結果) | 驗證指令或步驟 |
|---|---|---|
| AC-1 | <...> | <...> |
## 6. 停止條件
- <遇到哪些情況必須停止並回報>
## 7. 回報格式
- 變更摘要/假設/未解決問題/驗證證據(指令與輸出)
## 8. 審查與簽核
- 審查者:<姓名> 安全審查(高風險必填):<姓名>
- 驗收紀錄位置:<docs/acceptance/<需求編號>.md>填寫範例(教學示例(非官方),非真實客戶專案)
# 任務規格書:ORD-1423 退款 API
## 1. 基本資訊
- 需求來源:https://linear.app/acme/issue/ORD-1423
- 規格撰寫者:王小明 核可者:陳大華 核可日期:2026-10-28
- 指派 Agent:Claude Code/Manual 權限模式
- Worktree 與分支:feat/ORD-1423-refund-api
- 風險等級:高(涉及金流,需雙人審查)
## 2. 背景與目標
客服目前需人工於後台資料庫退款。本任務提供 POST /orders/{id}/refunds,
讓客服系統可發起全額或部分退款,並保證同一請求重送不會重複退款。
## 3. 範圍
- 允許修改:src/modules/refund/**、test/modules/refund/**
- 禁止修改:src/shared/**、src/modules/payment/**、db/migrations/**、package.json
- 非目標:退款通知信、報表、前端畫面
## 4. 輸入與參考
- 契約:docs/contracts/refund-api.yaml
- 既有慣例參考:src/modules/order/order.controller.ts、order.service.ts
- 測試資料:test/fixtures/orders.json
## 5. 驗收條件
| 編號 | 條件(可觀察結果) | 驗證指令或步驟 |
|---|---|---|
| AC-1 | 全額退款成功回傳 201 與退款編號 | npm test -- -t "full refund" |
| AC-2 | 部分退款後訂單剩餘可退金額正確遞減 | npm test -- -t "partial refund" |
| AC-3 | 退款金額超過剩餘可退金額回傳 422 | npm test -- -t "over refund" |
| AC-4 | 相同 Idempotency-Key 重送只產生一筆退款 | npm test -- -t "idempotent" |
| AC-5 | 金額計算全程使用整數分(cents),不使用浮點數 | git grep -n "parseFloat" -- src/modules/refund 無結果 |
| AC-6 | lint、typecheck、全部測試通過 | npm run lint && npm run typecheck && npm test |
## 6. 停止條件
- 需要修改 payment 模組或資料表結構
- 需要新增相依套件
- 同一測試連續修正兩次仍失敗
## 7. 回報格式
- 變更摘要/假設/未解決問題/驗證證據(貼上 AC-6 指令輸出末 20 行)
## 8. 審查與簽核
- 審查者:林美玲 安全審查:張志強
- 驗收紀錄位置:docs/acceptance/ORD-1423.md搭配規格書使用的分派 Prompt
請完整閱讀 docs/specs/ORD-1423.md,並嚴格依照其中的範圍、驗收條件與停止條件作業。
開始實作前,先用三到五行複述:你要修改哪些檔案、你不會碰哪些檔案、你打算如何驗證 AC-4。
我確認後你才開始寫程式。
完成後依第 7 節格式回報,並執行:
orca worktree set --worktree active --comment "ORD-1423 實作完成,AC-1~AC-6 自測通過;待人工審查" --workspace-status in-review --json🧑⚖️ 人工 Review 要點
- Agent 的「複述」正確反映範圍與禁止事項(若複述錯誤,代表規格寫得不夠清楚,先修規格)
- AC-1~AC-6 每一條都由審查者親自重跑,而不是只看 Agent 貼的輸出
- AC-5 這類「靜態規則」用指令驗證,結果附在驗收紀錄
- Worktree 卡片狀態已變為 in-review,且 comment 內容與實際狀態一致
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 規格書已入版控 | git log --oneline -- docs/specs/ORD-1423.md | 至少一筆 commit,作者為規格撰寫者 | 先提交規格再分派 |
| 驗收條件皆可執行 | 逐條執行第 5 節的驗證指令 | 每條都有明確通過或失敗結果 | 改寫無法執行的條件 |
| Agent 未越界 | git diff --name-only main...HEAD | 只出現允許修改路徑 | Annotate 要求還原 |
| 狀態回報 | orca worktree current --json | comment 與 workspace-status 已更新 | 提醒 Agent 依第 7 節回報 |
💡 小技巧:規格書第 5 節的「驗證指令」欄可以直接拿來當 CI 的檢查項目,也可以作為 22.7 節驗收紀錄的骨架,三份文件共用同一組編號(AC-1…),追溯最省力。
20.5 Prompt 反模式與修正
概念說明
以下每一組都是「壞 Prompt → 修正後 Prompt」,並說明壞在哪裡、修正後如何驗證。這些反模式在單人對話時只是效率問題,在多 Agent 平行時會變成品質與資安問題。
20.5.1 反模式一 形容詞需求
❌ 壞 Prompt
幫我優化一下訂單查詢,讓它快一點。問題:「快一點」沒有基準;三個 Agent 會給出三種方向(加索引、加快取、改 SQL),且都宣稱「已優化」。
✅ 修正後 Prompt
目標:GET /orders?customerId= 的 p95 延遲由目前 820ms 降到 300ms 以下。
基準量測:執行 npm run bench:orders,記錄修改前後的 p95。
限制:不得新增外部快取服務;若需要新增資料庫索引,只產出 migration 草稿並停止,等待 DBA 審查。
回報:修改前後的 bench 輸出原文。🧑⚖️ 人工 Review 要點
- 審查者自行執行
npm run bench:orders,前後數值與回報一致 - 若有 migration 草稿,Agent 已停止且未自行執行
20.5.2 反模式二 一個 Prompt 塞所有事
❌ 壞 Prompt
把會員模組重構成 Clean Architecture,順便升級到 Node 24、補測試、更新 README。問題:四件事混在一個 Diff,審查者無法分辨哪個變更是為了哪件事,出錯時也無法局部回滾。
✅ 修正後 Prompt(拆成四個 Worktree,依序執行)
任務 1/4(本 Worktree 只做這件事):為 src/modules/member 補齊特性測試(characterization tests),
鎖定目前行為;不得修改 src/ 下任何非測試檔案。
完成條件:npm test -- test/modules/member 全部通過,且覆蓋率報告中 member 模組行覆蓋率 ≥ 80%。
任務 2~4(重構、升級、文件)將在本任務合併後另行分派。🧑⚖️ 人工 Review 要點
-
git diff --name-only main...HEAD只有測試檔 - 特性測試在未修改的原始碼上全部通過(證明它鎖定的是現狀)
20.5.3 反模式三 沒有停止條件的 Yolo 任務
❌ 壞 Prompt
修好 CI 上所有失敗的測試,直到全部變綠為止。問題:在 Yolo 權限下,「直到變綠」最省力的路徑是刪測試、改斷言或加 skip。
✅ 修正後 Prompt
CI 上有 3 個失敗測試(見 ci-log.txt)。請逐一找出根因並修正「產品程式碼」。
禁止:刪除測試、修改斷言的期望值、加入 skip/only/@Disabled、調高 timeout。
若你判斷是測試本身寫錯,停止並說明理由,由人決定。
回報:每個測試的根因一句話、修正位置、修正前後該測試的輸出。🧑⚖️ 人工 Review 要點
-
git diff main...HEAD -- "*.test.ts"為空,或每一處測試變更都有 Agent 的停止說明與人類同意紀錄 - 根因說明可以在 Diff 中找到對應的修正行
20.5.4 反模式四 依賴對話記憶
❌ 壞 Prompt(第二天開新 Session)
照昨天講的方式繼續做。問題:新 Session、Hibernation 恢復或換 Agent 後,「昨天講的」不一定存在於 Context 中,Agent 會自行腦補。
✅ 修正後 Prompt
請先執行 orca worktree current --json 讀取本 Worktree 的進度註記,
再閱讀 docs/specs/ORD-1423.md 與 git log --oneline main..HEAD。
用五行以內摘要「已完成」與「剩餘」項目,等我確認後再繼續。🧑⚖️ 人工 Review 要點
- Agent 的摘要與 Checkpoint 註記、git log 一致
- 摘要中的「剩餘項目」與規格書驗收條件能一一對應
20.5.5 反模式五 把機敏資訊貼進 Prompt
❌ 壞 Prompt
用這組帳密連 UAT 資料庫查一下為什麼報表少資料:
postgres://report_admin:Pa55w0rd!@10.20.30.40:5432/uat問題:帳密進入模型供應商、Session History,且可能出現在行動端畫面或 Agent 產生的檔案中。
✅ 修正後 Prompt
UAT 資料庫連線已透過環境變數 UAT_DATABASE_URL 注入本 Worktree 的終端機。
請只執行唯讀查詢(SELECT),不得在輸出中印出連線字串。
請先列出你打算執行的 SQL,我同意後再執行。🧑⚖️ 人工 Review 要點
- Agent 執行的 SQL 全部為 SELECT
- 終端機輸出與回報中未出現連線字串(可用
orca terminal read --terminal <handle> --json取回內容後搜尋) - 若曾誤貼,依 28.3 節立即輪替該憑證
20.5.6 反模式六 只要結論不要證據
❌ 壞 Prompt
確認一下這個 PR 有沒有安全問題。問題:Agent 幾乎一定會回答「未發現明顯問題」,但無法得知它檢查了什麼。
✅ 修正後 Prompt
請以 OWASP Top 10(2021)逐項檢查本 Worktree 相對 main 的 Diff。
輸出一張表:類別|是否適用|檢查的檔案與行號|結論|證據(引用程式碼片段)。
「不適用」也要說明理由。不要給總結性的安全保證。🧑⚖️ 人工 Review 要點
- 表格十列齊全,每列的檔案與行號在 Diff 中真實存在
- 任一「適用」列都有程式碼引用,且審查者抽查至少兩列
✅ 驗證方式(反模式修正成效)
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Prompt 含可量測目標 | 檢查 Prompt 是否有數字或指令 | 每個目標都可量測 | 改寫為數值或指令 |
| Prompt 含禁止事項與停止條件 | 檢查 Prompt 文字 | 兩者皆存在 | 補上後再分派 |
| 單一 Worktree 單一目的 | git diff --stat main...HEAD 檢視變更主題 | 變更集中於單一目的 | 拆分 Worktree |
| 回報附證據 | 檢查 Agent 回報 | 含指令與原始輸出 | 要求補證據 |
💡 小技巧:把本節六組「修正後 Prompt」存成 Orca 的 Quick Commands(Agent Prompt 類型,見 12.2 節),團隊成員一鍵套用,比口頭宣導有效。完整 Prompt 範例庫見第三十六章。
20.6 本章 Review 與驗證清單
- 能畫出 20.1 的五道關卡,並說明哪幾道必須由人判定
- 能說明 Orca 在流程中「不負責」的三件事(例:CI 執行、合併核准規則、正式環境監控)
- 已用 20.4 範本為一個真實需求寫出規格書並提交到
docs/specs/ - 已實際用
orca worktree create --prompt分派一個任務,並用orca worktree current --json讀到 Agent 的 Checkpoint - 已用
git diff --name-only main...HEAD驗證 Agent 沒有越界修改 - 能指出 20.5 六種反模式,並各舉一個修正後的 Prompt
- 團隊已有共用的「回報格式」與「停止條件」範本
第二十一章 Agent 協作與企業 AI Team
第二十章處理「一個任務」怎麼走完流程;本章處理「多個 Agent 與多位人類」怎麼分工、怎麼交接、出事時誰負責。核心立場只有一句:角色可以由 AI 扮演,責任只能由人承擔。
📌 查證狀態:角色編組、RACI 與交接規範屬依官方說明延伸(教學推論);其中使用的 Orca Orchestration、Worktree Checkpoints、Agent 選擇與權限設定為官方文件明確記載|來源:Orchestration、Worktree checkpoints、Supported agents
21.1 角色設計原則
概念說明
「角色」在這裡指的是一組明確的輸入、產出、權限與驗收標準,而不是某個 Agent 產品。同一個 Claude Code 可以先當 Coding 角色、再開另一個 Worktree 當 Review 角色;關鍵是每個角色都有自己的規格與邊界。
設計角色時遵守五條原則:
| 原則 | 說明 | 反例 | 可驗證的做法 |
|---|---|---|---|
| 單一職責 | 一個角色只產出一種東西 | 「Coding 兼寫文件兼部署」 | 角色卡的「產出」欄只能有一類產出物 |
| 產出可驗收 | 每個角色的產出都有對應的驗證方法 | 「Architecture Agent 提供建議」 | 產出必須是可審查的檔案(ADR、測試、Diff) |
| 權限最小化 | 審查類角色不需要寫入權限 | Review Agent 用 Yolo 模式 | 審查類角色使用 Manual 權限或唯讀模式(例:Codex Ask mode) |
| 隔離執行 | 會寫入的角色各自一個 Worktree | 兩個 Coding Agent 共用一個 Worktree | git worktree list 中每個寫入角色各一列 |
| 人類對口 | 每個角色有一位具名的人類負責人 | 「AI 團隊自己會處理」 | 角色卡的「人類負責人」欄必填 |
範例:角色卡(Role Card)範本
# docs/ai-team/roles/review.yaml
role: Review
human_owner: 林美玲
agent: claude # 可替換為其他支援的 Agent
permission_mode: manual
worktree_policy: read-only-checkout # 只讀取 Coding Worktree 的 Diff,不提交
inputs:
- 任務規格書(docs/specs/<id>.md)
- Coding Worktree 相對 main 的 Diff
outputs:
- 審查報告(docs/reviews/<id>-ai-review.md)
forbidden:
- 修改任何 src/ 或 test/ 檔案
- 執行 git commit 或 git push
acceptance:
- 報告中每個問題都附檔案路徑與行號
- 人類負責人抽查至少兩個問題確認屬實✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 每個角色都有角色卡 | 列出 docs/ai-team/roles/ | 每個啟用角色一個檔案 | 補齊後才可分派 |
| 審查角色未寫入 | 在 Review Worktree 執行 git status --short | 除審查報告外無變更 | 收回寫入權限並重做 |
| 每個角色有人類負責人 | 檢查角色卡 human_owner | 皆為具名人員 | 指派負責人 |
21.2 八角色編組與職責
概念說明
以下八個角色是一套完整編組,涵蓋從規劃到部署。不需要一開始全部啟用——建議試點時只用 Planning、Coding、Testing、Review 四個,流程穩定後再加入其餘角色。
flowchart TD
HUMAN["人類 Tech Lead(Orchestrator)"]
PLAN["Planning 角色"]
ARCH["Architecture 角色"]
CODE["Coding 角色"]
TEST["Testing 角色"]
REV["Review 角色"]
SEC["Security 角色"]
DOC["Documentation 角色"]
OPS["DevOps 角色"]
HUMAN --> PLAN
PLAN --> ARCH
ARCH --> CODE
ARCH --> TEST
CODE --> REV
TEST --> REV
CODE --> SEC
REV --> DOC
SEC --> OPS
REV --> HUMAN
SEC --> HUMAN如何閱讀此圖:箭頭代表「產出物流向」。注意 Review 與 Security 的產出最後都回到人類 Tech Lead——AI 角色之間可以傳遞產出,但「是否放行」只能由人決定。
八角色職責表
| 角色 | 主要輸入 | 產出物 | 建議權限模式 | Orca 執行方式 | 驗收證據 |
|---|---|---|---|---|---|
| Planning | 需求單、既有程式碼 | 任務規格書草稿、相依關係 | Manual | Native Chat 單一對話 | 人修改後核可的規格書 commit |
| Architecture | 規格書、現有架構文件 | ADR、介面契約 | Manual | 獨立 Worktree,只寫 docs/ | 契約檔通過 schema 驗證;ADR 經架構師簽核 |
| Coding | 規格書、契約 | 程式碼 Diff | Auto 或 Yolo(隔離 Worktree 內) | 每任務一個 Worktree | 驗收指令全綠、範圍檢查通過 |
| Testing | 規格書、契約(不看實作) | 測試程式碼 | Auto 或 Yolo | 獨立 Worktree | 測試在錯誤實作上會失敗(見 22.4 節) |
| Review | 規格書、Coding Diff | 審查報告 | Manual 或唯讀 | 獨立 Worktree 或 Native Chat | 問題附行號,人類抽查屬實 |
| Security | Coding Diff、相依清單 | 安全檢查報告 | Manual | 獨立 Worktree | 掃描工具原始輸出+逐項結論 |
| Documentation | 合併後的程式碼 | README、API 文件 | Auto | 獨立 Worktree,只寫 docs/ | 文件中的路徑與指令經 22.6 節交叉驗證 |
| DevOps | 部署需求 | Pipeline、IaC Diff | Manual | 獨立 Worktree | plan/dry-run 輸出經 SRE 審查 |
📌 查證狀態:Manual/Auto/Yolo 三種權限模式為官方文件明確記載(v1.4.232 起,Settings → Agents),Auto 目前僅 Claude、Claude Agent Teams、Codex 支援|來源:Settings;各角色建議權限屬教學推論。
範例:用 Orchestration 建立「Coding+Testing 分離」編組
Testing 角色刻意不看實作,只依規格寫測試;這樣寫出的測試才能抓到 Coding 角色的誤解。
orca orchestration run-create --objective "ORD-1423 退款 API:實作與獨立測試" --json
orca orchestration task-create --spec "依 docs/specs/ORD-1423.md 實作,範圍限 src/modules/refund" --task-title "Coding" --json
orca orchestration task-create --spec "只依 docs/specs/ORD-1423.md 與 docs/contracts/refund-api.yaml 撰寫測試,不得閱讀 src/modules/refund" --task-title "Testing" --json
orca orchestration worker-start --task <codingTaskId> --worktree new-child --name ORD-1423-coding --agent claude --setup run --json
orca orchestration worker-start --task <testingTaskId> --worktree new-child --name ORD-1423-testing --agent codex --setup run --json
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --jsonTesting 角色範例 Prompt
你是 Testing 角色。你的唯一輸入是 docs/specs/ORD-1423.md 與 docs/contracts/refund-api.yaml。
不得開啟或搜尋 src/modules/refund 下的任何檔案。
請為 AC-1~AC-4 各寫至少一個測試,並額外寫出你認為規格沒講清楚的三個邊界情境(標註 [邊界])。
只修改 test/modules/refund/**。完成後列出每個測試對應的 AC 編號。🧑⚖️ 人工 Review 要點
- Testing Worktree 的
git diff --name-only main...HEAD只有test/路徑 - 每個 AC 都有至少一個對應測試
- [邊界] 測試中若有與規格衝突者,回頭修正規格而不是直接刪測試
- 把 Testing 的測試合併到 Coding 分支後執行,失敗項目逐一判定是實作錯還是測試錯
Review 角色範例 Prompt
你是 Review 角色,權限為唯讀。請審查 ORD-1423-coding 相對 main 的 Diff。
審查準則依序:1. 是否符合規格 AC-1~AC-6;2. 錯誤處理與邊界;3. 金額計算精度;4. 範圍是否越界。
輸出格式:每個問題一列「嚴重度(阻擋/建議)|檔案:行號|問題|建議修正」。
沒有發現問題的準則也要寫出你檢查了哪些檔案。不要修改任何檔案。🧑⚖️ 人工 Review 要點
- 報告中每個「檔案:行號」在 Diff 中真實存在
- 人類審查者對「阻擋」等級問題逐一確認,並轉成 Annotate AI Diff 意見送回 Coding 角色
- Review Worktree 本身沒有任何程式碼變更
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 各角色 Worktree 已建立 | orca worktree ps --json | 出現 coding 與 testing 兩個 Worktree | 檢查 worker-start 輸出錯誤訊息 |
| Testing 未讀取實作 | 檢視 Testing Agent 終端機紀錄(orca terminal read) | 無開啟 src/modules/refund 的紀錄 | 該批測試作廢重做 |
| Worker 完成事件 | orca orchestration check 輸出 | 收到 worker_done | 用 worker-read 查看卡在哪 |
| 權限模式正確 | Settings → Agents → Agent Permissions | 審查類 Agent 為 Manual | 調整後重新啟動該 Agent |
⚠️ 注意事項:「AI 審 AI」只能作為第一道篩網,不能取代人工審查。兩個模型可能共享同一種盲點(例:都認為浮點數處理金額沒問題)。
21.3 企業組織角色對應
概念說明
AI 角色要「掛」在真實組織職能下,才能落實責任歸屬。下表把常見企業職能對應到 AI 角色與簽核責任。
| 企業職能 | 對應 AI 角色 | 人類的不可委派責任 | 必須親自簽核的產出 |
|---|---|---|---|
| 產品經理(PM/PO) | Planning | 需求優先序、驗收條件最終版 | 任務規格書第 5 節 |
| 架構師 | Architecture | 架構決策、技術選型 | ADR、介面契約 |
| Tech Lead | Orchestrator(人) | 分派、關卡判定、合併放行 | PR 核准 |
| 前端/後端工程師 | Coding | 實作正確性、程式碼可維護性 | 自己負責模組的 Diff 審查 |
| QA 工程師 | Testing | 測試策略、回歸範圍 | 測試計畫與測試報告 |
| 資安工程師 | Security | 風險接受決策 | 高風險變更的安全審查 |
| DBA | Coding(限 migration 草稿) | 資料結構變更、正式環境執行 | 所有 migration |
| SRE/DevOps | DevOps | 部署、回滾、監控 | Pipeline 與 IaC 變更 |
| 技術寫手 | Documentation | 對外文件正確性 | 對外發布文件 |
範例:依風險等級決定簽核人數(寫入 CODEOWNERS)
# .github/CODEOWNERS(教學示例)
# 金流模組:需後端負責人與資安各一位核准
/src/modules/refund/ @acme/backend-leads @acme/appsec
/src/modules/payment/ @acme/backend-leads @acme/appsec
# 資料庫 migration:DBA 必須核准
/db/migrations/ @acme/dba
# 部署設定:SRE 必須核准
/deploy/ @acme/sre
/.github/workflows/ @acme/sre🧑⚖️ 人工 Review 要點
- 遠端平台已啟用「Require review from Code Owners」分支保護,否則 CODEOWNERS 只是提示
- 高風險路徑的 Code Owner 是人類團隊,不是機器帳號
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| CODEOWNERS 生效 | 建立一個只改 db/migrations/ 的測試 PR | PR 自動要求 @acme/dba 審查 | 檢查分支保護設定與檔案路徑 |
| 職能對應已公告 | 抽問兩位成員「migration 誰簽核」 | 回答一致為 DBA | 重新公告對應表 |
❌ 常見錯誤:管理層把「八個 AI 角色」解讀為「可以少聘八種人」。實際上 AI 角色增加的是產出量,而審查產能(人)才是瓶頸——角色越多,越需要具備判斷力的人類。
21.4 RACI 與交接規範
概念說明
RACI 釐清每個活動中誰是 R(Responsible,執行)、A(Accountable,最終負責,只能一位)、C(Consulted,諮詢)、I(Informed,知會)。AI 角色只能是 R,永遠不能是 A。
RACI 表(教學示例,可依組織調整)
| 活動 | PO | 架構師 | Tech Lead | 工程師 | QA | 資安 | SRE | AI 角色 |
|---|---|---|---|---|---|---|---|---|
| 撰寫任務規格書 | A | C | R | C | C | I | I | R(Planning 草稿) |
| 介面契約與 ADR | I | A | R | C | C | C | I | R(Architecture 草稿) |
| 分派 Worktree 與 Agent | I | I | A | R | I | I | I | - |
| 程式實作 | I | I | A | R | I | I | I | R(Coding) |
| 測試撰寫 | I | I | C | C | A | I | I | R(Testing) |
| 第一輪 AI 審查 | - | I | I | I | I | I | - | R(Review) |
| 人工 Diff 審查 | I | C | A | R | C | C | I | - |
| 安全審查(高風險) | I | C | C | I | I | A | I | R(Security 掃描) |
| 合併放行 | I | I | A | R | C | C | I | - |
| 部署與回滾 | I | I | C | I | I | I | A | R(DevOps 草稿) |
| 驗收紀錄歸檔 | C | I | A | R | C | I | I | - |
📌 查證狀態:教學示例(非官方)。RACI 為通用專案管理方法,Orca 本身不提供 RACI 設定功能。
交接規範
Agent 之間、Agent 與人之間、或人與人之間交接 Worktree 時,必須留下可讀的交接紀錄。Orca 的 Worktree Checkpoint(orca worktree set --comment)適合放「一行狀態」;完整交接內容應寫成檔案存入 repo 或附在 PR。
交接範本
# 交接紀錄:<需求編號> <Worktree 名稱>
- 交出方:<人或 Agent 名稱+Session> 接收方:<人或 Agent 名稱>
- 交接時間:<YYYY-MM-DD HH:mm>
- 分支與基準:<branch>(基於 <commit SHA>)
## 1. 目前狀態
- 已完成驗收條件:<AC 編號>
- 未完成驗收條件:<AC 編號>
- Worktree Checkpoint:<orca worktree current 的 comment 內容>
## 2. 重要決策與假設
- <決策>:<理由>(是否已獲人類確認:是/否)
## 3. 已知問題與風險
- <問題>:<重現方式>
## 4. 接收方第一步
1. <具體指令,例:npm test -- -t "idempotent">
2. <...>
## 5. 驗證交接完整性
- 指令:git log --oneline main..HEAD
- 指令:git status --short(應為空,所有變更已 commit)填寫範例(教學示例(非官方))
# 交接紀錄:ORD-1423 ORD-1423-coding
- 交出方:Claude Code(Coding 角色) 接收方:王小明(後端工程師)
- 交接時間:2026-10-29 18:40
- 分支與基準:feat/ORD-1423-refund-api(基於 9f3c2e1)
## 1. 目前狀態
- 已完成驗收條件:AC-1、AC-2、AC-3、AC-5、AC-6
- 未完成驗收條件:AC-4(冪等)
- Worktree Checkpoint:AC-4 blocked:需要新增 idempotency_keys 資料表,已依停止條件停止
## 2. 重要決策與假設
- 金額以整數分儲存:沿用 order 模組慣例(是否已獲人類確認:是,林美玲 10/29)
- 部分退款不限次數:規格未定義(是否已獲人類確認:否)
## 3. 已知問題與風險
- AC-4 需要 migration,屬 DBA 範圍,尚未建立
## 4. 接收方第一步
1. 與 DBA 確認 idempotency_keys 資料表設計
2. 回覆「部分退款次數上限」給 PO 確認
## 5. 驗證交接完整性
- 指令:git log --oneline main..HEAD(應有 4 筆 commit)
- 指令:git status --short(應為空)交接時同步更新 Checkpoint
orca worktree set --worktree active \
--comment "AC-4 blocked:需 idempotency_keys 資料表,已交接王小明;詳見 docs/handoffs/ORD-1423.md" \
--workspace-status todo --json🧑⚖️ 人工 Review 要點(接收方)
- 執行第 5 節的兩條指令,結果與交接紀錄描述一致
- 「是否已獲人類確認:否」的每一項都已轉為待辦,且指定了確認人
- Checkpoint 內容與交接紀錄第 1 節一致,且未覆蓋掉原本的目標描述(官方建議寫入前先用
orca worktree current --json讀取)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 交接時無未提交變更 | git status --short | 無輸出 | 交出方先 commit 或說明 |
| Commit 數與紀錄一致 | git log --oneline main..HEAD | 筆數與紀錄相符 | 釐清是否有遺漏或多餘 commit |
| Checkpoint 已更新 | orca worktree current --json | comment 指向交接紀錄 | 補寫 Checkpoint |
| RACI 中每列恰有一個 A | 檢查 RACI 表 | 每列一個且僅一個 A,且 A 不是 AI 角色 | 修正 RACI 表 |
💡 小技巧:把交接範本存成 Orca Quick Command 的 Agent Prompt,內容為「請依 docs/templates/handoff.md 產生交接紀錄並更新 Worktree Checkpoint」,讓 Agent 在被停止或交接前自動整理;但紀錄中「是否已獲人類確認」欄位仍須由人填寫。
21.5 本章 Review 與驗證清單
- 能說明「角色可以由 AI 扮演,責任只能由人承擔」並舉 RACI 中的例子
- 已為至少四個試點角色寫好角色卡,且每張卡有具名人類負責人
- 已實際用
orca orchestration建立 Coding 與 Testing 分離的兩個 Worker,並收到worker_done - 已驗證審查類角色使用 Manual 權限,且其 Worktree 無程式碼變更
- CODEOWNERS 與分支保護已對高風險路徑生效(以測試 PR 驗證)
- 已完成一次交接,接收方依交接紀錄第 5 節指令驗證通過
- RACI 表每一列恰有一個 A,且沒有任何 A 指派給 AI 角色
第二十二章 AI 產出的 Review 與驗證方法論
本章是全書的方法論核心,回答一個問題:當 AI Agent 交出程式碼、測試、規範、文件或架構圖時,人類要怎麼確認它是對的? 答案不是「多看幾遍」,而是一套可重複、可留證、可被第三方重現的驗證流程。
📌 查證狀態:本章方法論屬依官方說明延伸(教學推論);其中引用的 Diff Viewer、Annotate AI Diff、Attribution、Commit 流程與 Worktree Checkpoints 為官方文件明確記載|來源:Diff viewer、Annotate AI Diff、Attribution、Commit & push、Review an AI diff line-by-line
22.1 為何人工驗證不可省略
概念說明
AI Agent 的錯誤與人類工程師的錯誤「長得不一樣」:人類通常在不熟的地方猶豫並留下 TODO;AI 則常在錯誤的地方表現得同樣自信。下表是審查 AI 產出時最常見的八種失誤型態,後續各節的驗證方法都是針對它們設計的。
| 失誤型態 | 典型表現 | 為何難以察覺 | 主要抓法 | 對應章節 |
|---|---|---|---|---|
| 宣稱與事實不符 | 回報「所有測試通過」,實際只跑了部分 | 回報語氣肯定、格式工整 | 審查者親自重跑 | 22.4 |
| 範圍蔓延 | 順手改了共用模組、格式化整個檔案 | 淹沒在大量 Diff 中 | git diff --name-only 範圍檢查 | 22.3 |
| 邊界錯誤 | > 寫成 >=、off-by-one | 正常路徑測試都會通過 | 邊界值逐一追問、補邊界測試 | 22.3 |
| 測試竄改 | 放寬斷言、加 skip 讓測試變綠 | 測試報告是綠的 | 審查測試檔 Diff、紅綠驗證 | 22.3、22.4 |
| 吞掉錯誤 | try/catch 後只記 log 繼續執行 | 程式「不會壞」 | 審查每個新增的 catch 區塊 | 22.3 |
| 幻覺 API 或路徑 | 引用不存在的函式、檔案、設定鍵 | 名稱看起來很合理 | 編譯、型別檢查、路徑存在檢查 | 22.6 |
| 過時知識 | 使用已棄用的 API 或舊版設定 | 在舊版本上確實可行 | 對照實際相依版本 | 22.6 |
| 共同盲點 | AI Reviewer 與 AI Coder 犯同一種錯 | 「兩個 AI 都說沒問題」 | 人工審查+獨立測試 | 21.2、22.2 |
範例:一份「看起來完美」的 Agent 回報,以及它隱藏的問題
## 驗證證據
$ npm test
PASS test/modules/refund/refund.service.test.ts
Tests: 12 passed, 12 total
所有測試通過 ✅審查者重跑後發現:
npm test PASS test/modules/refund/refund.service.test.ts
FAIL test/modules/order/order.controller.test.ts
Tests: 1 failed, 57 passed, 58 totalAgent 實際上執行的是 npm test -- test/modules/refund,只跑了自己的模組,沒看到它改壞了 order 模組。回報格式上的 $ npm test 是 Agent「整理」過的。
🧑⚖️ 人工 Review 要點
- 任何「已通過」的宣稱,都以審查者自己終端機的輸出為準
- 檢查回報中的測試總數是否合理(本例 12 遠小於全專案 58)
- 檢查 Agent 的終端機原始紀錄(Orca 中該 Worktree 的終端機分頁,或
orca terminal read --terminal <handle> --json),確認實際執行的指令
企業治理考量:在多數監理框架下,「誰核准了這段變更」必須能指向一個具名的人。AI 產出若未經人工驗證即合併,責任歸屬會出現空白,這是稽核缺失而不只是品質問題(見 28.6 節)。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 團隊認知 | 請審查者說出八種失誤型態中的至少五種 | 能說出並舉例 | 以本表做一次內部訓練 |
| 不採信口頭宣稱 | 抽查最近三份驗收紀錄 | 每份都有審查者自行執行的輸出 | 退回補做驗證 |
22.2 三層驗證模型
概念說明
本書把 AI 產出的驗證分成三層,每一層回答不同問題,且不可互相替代。
| 層級 | 回答的問題 | 執行者 | 典型工具 | 失效時的後果 |
|---|---|---|---|---|
| L1 自動化檢查 | 「它能編譯、通過規則與測試嗎?」 | 機器(本機+CI) | build、lint、typecheck、test、secret scan、SAST、範圍檢查腳本 | 明顯錯誤流入審查,浪費人力 |
| L2 人工審查 | 「它做的是對的事、用對的方法嗎?」 | 具名審查者 | Orca Diff Viewer、Annotate AI Diff、Attribution、規格書 | 邏輯錯誤、設計錯誤上線 |
| L3 證據留存 | 「事後能證明 L1 與 L2 真的做過嗎?」 | 審查者+流程 | 驗收紀錄、PR、CI 紀錄、Checkpoint、Attribution 匯出 | 稽核時無法舉證 |
flowchart TD
OUT["Agent 產出(Diff、測試、文件)"] --> L1["L1 自動化檢查"]
L1 -- "失敗" --> BACK["退回 Agent(附失敗輸出)"]
L1 -- "通過" --> L2["L2 人工審查"]
L2 -- "有意見" --> ANNO["Annotate AI Diff 批次回送"]
ANNO --> OUT
BACK --> OUT
L2 -- "核准" --> L3["L3 證據留存"]
L3 --> DONE["可合併"]如何閱讀此圖:L1 是 L2 的「入場券」——沒過 L1 的產出不值得人花時間看。L3 不是最後才補做的文書工作,而是把 L1 的輸出與 L2 的決策「凍結」成證據。
依風險等級決定最低要求
| 項目 | 低風險(內部工具、文件) | 中風險(一般業務功能) | 高風險(金流、權限、個資、對外 API) |
|---|---|---|---|
| L1 build/lint/test | 必要 | 必要 | 必要 |
| L1 secret scan | 必要 | 必要 | 必要 |
| L1 SAST/相依弱點掃描 | 建議 | 必要 | 必要 |
| L1 範圍檢查腳本 | 建議 | 必要 | 必要 |
| L2 審查人數 | 1 | 1 | 2(含資安或領域專家) |
| L2 紅綠驗證(22.4) | 選用 | 建議 | 必要 |
| L3 驗收紀錄 | 簡式(PR 描述即可) | 完整範本 | 完整範本+Attribution 匯出 |
📌 查證狀態:風險分級與各層要求為教學示例(非官方),請依組織政策調整。
範例:L1 範圍檢查腳本(依規格書允許路徑自動驗證)
#!/usr/bin/env bash
# scripts/check-scope.sh <base-ref> <允許路徑正規表示式>
# 例:scripts/check-scope.sh main '^(src/modules/refund/|test/modules/refund/)'
set -euo pipefail
base="$1"
allow="$2"
violations=$(git diff --name-only "${base}...HEAD" | grep -Ev "$allow" || true)
if [ -n "$violations" ]; then
echo "SCOPE VIOLATION:"
echo "$violations"
exit 1
fi
echo "scope ok"# scripts/check-scope.ps1 -Base main -Allow '^(src/modules/refund/|test/modules/refund/)'
param([string]$Base, [string]$Allow)
$violations = git diff --name-only "$Base...HEAD" | Where-Object { $_ -notmatch $Allow }
if ($violations) { Write-Output "SCOPE VIOLATION:"; $violations; exit 1 }
Write-Output "scope ok"✅ 驗證方式
在一個刻意越界的測試分支執行(例:改動
package.json):scripts/check-scope.sh main '^(src/modules/refund/|test/modules/refund/)'預期輸出(示意):
SCOPE VIOLATION: package.json判讀:腳本必須對越界變更回傳非 0 的 exit code;若輸出
scope ok,代表正規表示式寫得太寬,先修腳本再信任它。驗證工具本身也要被驗證,這是本章反覆出現的原則。
22.3 Diff 審查準則
概念說明
Orca 的 Diff Viewer 預設比對 Worktree 的起始參考點(start-from ref),可切換為任意 commit、分支或 base ref;支援 j/k 切換檔案、n/p 切換 hunk、c 留言、s 暫存 hunk,並可開啟 Show Whitespace 與 Attribution 的 AI 行標記。審查時依下列十條準則逐檔檢查。
📌 查證狀態:Diff Viewer 快捷鍵、Show Whitespace、比對範圍切換、Attribution 標記為官方文件明確記載|來源:Diff viewer、Attribution
| 編號 | 準則 | 審查時問的問題 | 客觀輔助指令或功能 |
|---|---|---|---|
| D1 | 必要性 | 這個 hunk 是規格要求的嗎? | 對照規格書 AC 編號 |
| D2 | 最小性 | 有沒有更小的改法?有無順手重構或格式化? | git diff --stat main...HEAD;Show Whitespace |
| D3 | 一致性 | 和同檔案、同模組的既有寫法一致嗎? | 開啟同目錄其他檔案比對 |
| D4 | 邊界 | 等於、空值、零、負數、最大值時行為正確嗎? | 逐一列出邊界值並找對應測試 |
| D5 | 錯誤處理 | 新增的 catch 是否吞錯?失敗後狀態是否一致? | 搜尋 Diff 中新增的 catch |
| D6 | 並行與冪等 | 先查後寫是否有競態?重送是否安全? | 檢查是否有唯一約束或鎖 |
| D7 | 安全 | 輸入驗證、授權檢查、log 是否含機敏資料? | secret scan、SAST |
| D8 | 測試變更 | 有沒有放寬斷言、刪測試、加 skip? | git diff main...HEAD -- test/ |
| D9 | 相依變更 | 新增或升級套件是否經同意? | git diff main...HEAD -- package.json |
| D10 | 生成檔與雜訊 | lock 檔、snapshot、產生檔的變更是否合理? | Source Control 的 Code breakdown(Source/Tests/Generated) |
操作步驟
- 在 Orca 開啟該 Worktree 的 Diff Viewer,確認比對基準為
main(或規格書指定的 base ref)。 - 先看 Source Control 分支列的增減行數晶片,滑過可看 Source/Tests/Generated 拆分;Tests 為 0 的功能變更直接退回。
- 用
j/k逐檔、n/p逐 hunk 檢查,對照上表 D1~D10;帶有 AI 標記的行優先細看。 - 有疑問處按
c留言,寫完整句子並指出準則編號(例:「D4:等於剩餘金額時應允許」)。 - 全部看完後按 Send to agent 批次送回,選擇原 Coding Agent。
- Agent 修正後重新開啟 Diff,逐一確認釘選的留言已修正,按 Resolve;未修正者保留並再次送出。
以下五個 diff 範例都是 AI 常犯、且「測試可能仍然綠燈」的細微錯誤。
22.3.1 範例一 邊界條件錯誤
const remaining = order.paidCents - order.refundedCents;
- if (amountCents > remaining) {
+ if (amountCents >= remaining) {
throw new UnprocessableError('REFUND_EXCEEDS_REMAINING');
}問題:Agent 在「重構」時把 > 改成 >=,導致「退款金額恰好等於剩餘可退金額」時被拒絕——也就是全額退款壞了。若測試只用「退一半」和「退兩倍」兩種資料,測試全部綠燈。
審查者如何抓到:D4 邊界準則——看到任何比較運算子變更,立刻問「等於時應該怎樣」,並在測試中找 amount === remaining 的案例。
Annotate 意見範例
D4:這裡由 > 改為 >=,會讓「退款金額 == 剩餘金額」被拒(即全額退款失敗)。
規格 AC-1 要求全額退款成功。請還原為 >,並新增測試:剩餘 1000 分時退 1000 分應回 201。22.3.2 範例二 浮點數精度
- const amountCents = toCents(req.body.amount);
+ const amountCents = parseFloat(req.body.amount) * 100;問題:parseFloat("1.15") * 100 的結果是 114.99999999999999,存入整數欄位時可能被截斷為 114。金額相關程式碼使用浮點運算是金融業最常見的 AI 錯誤之一。
審查者如何抓到:規格書 AC-5 已寫成靜態規則,L1 即可攔截:
git grep -n "parseFloat" -- src/modules/refundsrc/modules/refund/refund.controller.ts:42: const amountCents = parseFloat(req.body.amount) * 100;有輸出即違規。人工審查時再補一個 1.15、0.07、19.99 這類「二進位無法精確表示」的測試值。
22.3.3 範例三 吞掉錯誤導致狀態不一致
- await paymentGateway.refund(order.paymentId, amountCents);
+ try {
+ await paymentGateway.refund(order.paymentId, amountCents);
+ } catch (err) {
+ logger.warn('refund gateway error', err);
+ }
await refundRepo.markRefunded(order.id, amountCents);問題:Agent 為了讓「閘道逾時」的測試不再拋例外,把錯誤包起來只記 log。結果是閘道退款失敗,系統卻記錄為已退款——帳務不一致。
審查者如何抓到:D5——每一個新增的 catch 都要問「捕捉之後,下一行還應該執行嗎?」。可用指令快速列出所有新增的 catch:
git diff main...HEAD -U0 -- src | grep -n "^+.*catch"Annotate 意見範例
D5:閘道失敗後仍執行 markRefunded,會造成帳務不一致。
請讓錯誤向上拋出(或回傳 502),並新增測試:閘道拋錯時 refundRepo.markRefunded 不得被呼叫。22.3.4 範例四 先查後寫的競態
+ const existing = await refundRepo.findByIdempotencyKey(key);
+ if (existing) {
+ return existing;
+ }
+ const refund = await refundRepo.create({ orderId, amountCents, idempotencyKey: key });
+ return refund;問題:單執行緒測試中完全正確;但兩個相同 Idempotency-Key 的請求同時進來時,兩者都查不到既有紀錄,於是各建立一筆退款。
審查者如何抓到:D6——看到「先查詢、再依結果寫入」的模式,就要求資料層唯一約束,並要求一個並行測試:
D6:findByIdempotencyKey 與 create 之間有競態。請:
1. 在 migration 草稿中為 idempotency_key 加唯一約束(DBA 審查);
2. create 遇到唯一約束衝突時改為回傳既有紀錄;
3. 新增測試:以 Promise.all 同時送出 5 個相同 key 的請求,資料庫中只能有 1 筆退款。22.3.5 範例五 為了綠燈而放寬測試
it('rejects over refund', async () => {
const res = await request(app)
.post(`/orders/${orderId}/refunds`)
.send({ amount: '999999' });
- expect(res.status).toBe(422);
- expect(res.body.code).toBe('REFUND_EXCEEDS_REMAINING');
+ expect([201, 422]).toContain(res.status);
});問題:測試名稱仍是「拒絕超額退款」,但斷言已允許 201(成功)。這個測試從此永遠不會失敗。這是 AI 在「修到測試全綠」指令下最常見的行為。
審查者如何抓到:D8——測試檔的 Diff 一律逐行看,任何斷言由「精確值」變成「集合」「範圍」「truthy」都要求說明。輔助指令:
git diff main...HEAD -- "test/**" | grep -nE "^-.*expect|^\+.*(skip|only|xit|toBeTruthy|toContain)"Annotate 意見範例
D8:此修改讓「超額退款」測試在成功時也會通過,等同移除了 AC-3 的驗證。
請還原原本的兩個斷言,並修正產品程式碼使其回傳 422。不得修改本測試的期望值。🧑⚖️ 人工 Review 要點(Diff 審查總表)
- D1~D10 每一條都看過,無法判斷者標註並請第二位審查者確認
- 所有比較運算子變更都已追問「等於時」的行為(範例一)
- 金額、時間、時區相關程式碼已用「不友善」的測試值驗證(範例二)
- 每個新增 catch 都確認了失敗後的狀態一致性(範例三)
- 每個「查詢後寫入」都有唯一約束或鎖(範例四)
- 測試檔 Diff 已逐行審查,沒有斷言被放寬(範例五)
- 所有 Annotate 意見都已 Resolve,未解決的意見有明確後續負責人
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 比對基準正確 | Diff Viewer 工具列顯示的比較對象 | 為規格書指定的 base ref | 從 Diff 工具列切換比較對象 |
| 審查意見已全部處理 | Diff Viewer 中檢查留言串 | 全部為 Resolved | 再次 Send to agent 或人工修正 |
| 無新增吞錯 | git diff main...HEAD -U0 -- src 搜尋新增 catch | 每個 catch 都已人工確認 | 以 Annotate 退回 |
| 測試未被放寬 | git diff main...HEAD -- test/ 逐行檢視 | 無斷言放寬、無 skip | 以 Annotate 退回 |
| 相依未異動 | git diff main...HEAD -- package.json | 為空或已有核准紀錄 | 退回並要求說明 |
💡 小技巧:Send Review Notes to Agent 預設沒有綁定快捷鍵,可在 Settings → Shortcuts 指定,讓整個審查流程不必離開鍵盤。批次送出比逐條送出更好——官方說明逐條送會讓 Agent「來回擺盪」,批次則一次思考、一次修正。
22.4 測試證據要求
概念說明
「測試通過」是一個需要證據的陳述。本書要求的測試證據包含五個要素,缺一不可:
| 要素 | 內容 | 為何需要 |
|---|---|---|
| E1 版本 | 受測的 commit SHA | 證明測的就是要合併的程式碼 |
| E2 指令 | 完整、可複製的執行指令 | 讓第三方可重現 |
| E3 輸出 | 原始輸出(至少摘要段),不可改寫 | 防止「整理過」的回報 |
| E4 結束碼 | exit code | 部分工具失敗時仍印出看似正常的訊息 |
| E5 有效性 | 測試在錯誤實作上會失敗(紅綠驗證) | 證明測試真的在檢驗東西 |
操作步驟:產生 E1~E4 證據
在要驗證的 Worktree 確認工作區乾淨,並記錄版本:
git status --short git rev-parse HEAD執行完整測試並保存原始輸出(bash):
mkdir -p evidence npm test 2>&1 | tee evidence/ORD-1423-test.log echo "exit=${PIPESTATUS[0]}" | tee -a evidence/ORD-1423-test.logPowerShell 版本:
New-Item -ItemType Directory -Force evidence | Out-Null npm test 2>&1 | Tee-Object -FilePath evidence\ORD-1423-test.log "exit=$LASTEXITCODE" | Tee-Object -FilePath evidence\ORD-1423-test.log -Append預期輸出末段(示意):
Test Suites: 9 passed, 9 total Tests: 64 passed, 64 total exit=0比對測試總數:與 main 分支相比,總數應增加或持平;若減少,必須逐一說明被刪除的測試。
操作步驟:E5 紅綠驗證(證明新測試有效)
新測試必須在「沒有這次修改的程式碼」上失敗,否則它可能根本沒有檢驗新行為。做法是把新測試搬到 main 上執行:
建立一個臨時驗證用 Worktree(標準 git 操作):
git worktree add ../verify-red main git -C ../verify-red checkout feat/ORD-1423-refund-api -- test/modules/refund在臨時 Worktree 執行新測試:
cd ../verify-red npm ci npm test -- test/modules/refund預期結果:新增的測試應該失敗(紅),例如:
FAIL test/modules/refund/refund.controller.test.ts ✕ full refund returns 201 (12 ms) ✕ idempotent request creates single refund (8 ms)回到功能分支執行同樣測試應全部通過(綠)。
清理臨時 Worktree:
cd - git worktree remove ../verify-red --force判讀:若新測試在 main 上也通過,代表測試沒有覆蓋到新行為(或新行為其實早已存在),退回要求重寫測試。
進階:變異測試(Mutation Testing)
對高風險模組,可用變異測試工具(JavaScript/TypeScript 的 StrykerJS、Java 的 PIT)自動在程式碼中植入小錯誤(例:> 改 >=),檢查測試能否抓到。22.3.1 的範例一正是一個典型變異。
npx stryker run --mutate "src/modules/refund/**/*.ts"預期在報告中看到 mutation score;團隊可訂定高風險模組的最低門檻(例:70%,教學示例),低於門檻者補測試。
📌 查證狀態:StrykerJS、PIT 為第三方開源工具,非 Orca 功能;指令參數請以該工具官方文件為準(教學示例(非官方))。
範例 Prompt:要求 Agent 提供合格的測試證據
完成實作後,請依下列順序執行並原樣貼上輸出,不要摘要或改寫:
1. git rev-parse HEAD
2. git status --short(應為空)
3. npm test 2>&1 | tail -n 30,並接著執行 echo "exit=${PIPESTATUS[0]}"
4. 列出本次新增的測試名稱,以及每個測試對應的 AC 編號
另外,請說明:若把 refund.service.ts 第一個比較運算子由 > 改為 >=,哪一個測試會失敗?🧑⚖️ 人工 Review 要點
- E1 的 SHA 與審查者看到的 Worktree HEAD 一致(
git rev-parse HEAD) - E3 輸出中測試總數與審查者自行執行的結果一致
- E4 exit code 為 0
- Agent 對「改成 >= 會讓哪個測試失敗」的回答,審查者實際手動改一次驗證(這是最便宜的手動變異測試)
- E5 紅綠驗證已執行,紅階段的失敗清單已附在驗收紀錄
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 證據對應正確版本 | 比對證據檔中的 SHA 與 PR head | 一致 | 重新產生證據 |
| 測試總數未減少 | 比較 main 與分支的測試總數 | 增加或持平 | 逐一說明被刪除的測試 |
| 新測試有效 | 執行紅綠驗證 | main 上紅、分支上綠 | 退回重寫測試 |
| 無跳過的測試 | 搜尋測試輸出中的 skipped 數 | 0,或每個 skip 都有核准理由 | 退回移除 skip |
22.5 規範類產出的驗證
概念說明
AI 很擅長寫出「看起來很專業」的程式碼規範、命名規則、API 設計準則。問題在於:一條無法被測試的規則,就無法被一致地執行。驗證規範類產出的方法是:把每條規則分類,能自動化的寫成可執行規則,並用「應該違規」與「不應違規」的樣本程式碼去測試規則本身。
操作步驟
- 請 AI 產出規範時,要求每條規則都附上「違規範例」與「合規範例」。
- 人工把規則分成三類:A 可自動化(lint、semgrep、架構測試)、B 半自動(可列出候選再人判斷)、C 只能人判斷(命名語意、可讀性)。
- 對 A 類規則,寫成工具規則,並以樣本檔測試規則本身。
- 在現有程式碼上試跑,計算誤報數;誤報過多的規則退回修改。
- 檢查新規則是否與既有 lint 設定衝突。
- 通過後才納入 CI,並記錄在驗收紀錄。
範例 Prompt:產出可驗證的規範
請為 src/modules/** 撰寫「金額處理規範」,最多 6 條。每條規則必須包含:
- 規則編號與一句話規則
- 理由(一句)
- 違規範例(TypeScript,3~5 行)
- 合規範例(TypeScript,3~5 行)
- 可否自動檢查(是/否);若是,提供 semgrep 規則 YAML
不要寫無法判定對錯的規則(例如「保持程式碼清晰」)。🧑⚖️ 人工 Review 要點
- 每條規則都有違規與合規範例,且範例本身能編譯
- 標為「可自動檢查」的規則,其 semgrep 規則已用
semgrep --test驗證(見下方) - 規則之間沒有互相矛盾(例:一條要求整數分、另一條範例卻用 Decimal 字串)
- 規則與現行程式碼的衝突數量已量測,並決定是「修程式」還是「修規則」
範例:把 AI 產出的規則寫成 semgrep 規則並測試規則本身
規則檔 rules/no-float-money.yaml:
rules:
- id: no-float-money
languages: [typescript]
severity: ERROR
message: 金額不得以浮點數轉換,請使用 toCents()(規範 MONEY-01)
pattern-either:
- pattern: parseFloat(...)
- pattern: Number($X) * 100規則的測試樣本 rules/no-float-money.ts(檔名與規則檔同名,semgrep 依註解判定預期結果):
// ruleid: no-float-money
const a = parseFloat(input.amount);
// ruleid: no-float-money
const b = Number(input.amount) * 100;
// ok: no-float-money
const c = toCents(input.amount);
// ok: no-float-money
const pageSize = Number(query.size);✅ 驗證方式
測試規則本身:
semgrep --test rules/預期輸出(示意,實際格式依 semgrep 版本而異):
1/1: ✓ All tests passed判讀:若
ok:標註的行被報出(誤報)或ruleid:標註的行未被報出(漏報),測試會失敗。例如Number(query.size)被誤報,代表規則寫成了Number(...)太寬。在現有程式碼上量測誤報:
semgrep --config rules/no-float-money.yaml src/ --json > evidence/money-rule-scan.json逐一檢視掃描結果,若誤報超過團隊門檻(例:超過 10%,教學示例),退回修改規則。
📌 查證狀態:semgrep 為第三方開源工具,
--test模式與ruleid:/ok:註解慣例請以 Semgrep 官方文件 為準(教學示例(非官方))。
範例:驗證 AI 產出的 API 規格(OpenAPI)
AI 產出的 OpenAPI 檔常出現:引用不存在的 schema、必填欄位與範例不符、狀態碼漏列。用 linter 先做 L1:
npx @redocly/cli lint docs/contracts/refund-api.yaml再以人工 L2 檢查:規格中的每個錯誤碼是否在規格書的驗收條件中出現;每個 example 是否符合其 schema。
❌ 常見錯誤:把 AI 寫的規範直接放進 Wiki 當作「團隊標準」,卻沒有任何工具執行它。三個月後新程式碼與規範各走各的,規範成為裝飾。
22.6 文件與架構產出的驗證
概念說明
AI 產出的 README、架構說明、模組相依圖、API 文件,最大的風險是與程式碼不一致:引用不存在的檔案、描述已不存在的相依關係、列出錯誤的端點數量。驗證原則是「每一個可被程式碼證明的陳述,都要用指令交叉比對」。
| 陳述類型 | 範例陳述 | 交叉驗證方法 |
|---|---|---|
| 檔案與路徑 | 「設定位於 config/refund.yaml」 | 路徑存在檢查腳本 |
| 端點清單 | 「退款模組提供 3 個端點」 | git grep 路由宣告並計數 |
| 相依關係 | 「refund 模組不直接依賴 payment 模組」 | git grep import 語句 |
| 版本 | 「使用 Express 5」 | 讀取 package.json |
| 指令 | 「執行 npm run migrate 建立資料表」 | 確認 package.json scripts 有此項並在隔離環境實跑 |
| 圖表 | Mermaid 架構圖 | 渲染檢查+節點與程式模組逐一對應 |
範例 Prompt:要求「引用即證據」的架構文件
請為 src/modules/refund 撰寫架構說明 docs/architecture/refund.md。
規則:
1. 每一個關於程式碼的陳述,後面都要附上證據引用,格式為(檔案路徑:行號)。
2. 提供一張 Mermaid flowchart 描述模組相依,圖中每個節點都必須對應一個實際存在的目錄或檔案。
3. 列出所有 HTTP 端點(方法+路徑),並註明宣告位置。
4. 不確定的地方寫「待確認」,不要推測。🧑⚖️ 人工 Review 要點
- 隨機抽 5 個「(檔案路徑:行號)」引用,開啟檔案確認該行確實支持該陳述
- 路徑存在檢查腳本(見下方)無輸出
- 端點數量與
git grep計數一致 - 相依圖中每條箭頭都能找到對應 import
- 所有「待確認」項目都有人追蹤
操作步驟:交叉驗證指令集
檢查文件中引用的路徑是否都存在(bash):
grep -oE '`[A-Za-z0-9_./-]+\.(ts|js|json|yaml|yml|md|sql)`' docs/architecture/refund.md \ | tr -d '`' | sort -u | while read -r p; do [ -e "$p" ] || echo "MISSING: $p"; donePowerShell 版本:
Select-String -Path docs\architecture\refund.md -Pattern '`([A-Za-z0-9_./-]+\.(ts|js|json|yaml|yml|md|sql))`' -AllMatches | ForEach-Object { $_.Matches } | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique | Where-Object { -not (Test-Path $_) } | ForEach-Object { "MISSING: $_" }預期:無任何輸出。出現
MISSING:即為幻覺路徑。核對端點清單:
git grep -nE "router\.(get|post|put|patch|delete)\(" -- src/modules/refund預期:列出的行數與文件中的端點數量一致,且方法與路徑逐一相符。
核對相依陳述(例:文件宣稱 refund 不直接依賴 payment):
git grep -nE "from ['\"].*modules/payment" -- src/modules/refund預期:無輸出。若有輸出,文件陳述錯誤(或程式碼違反架構原則,需另開議題)。
核對版本陳述:
node -p "require('./package.json').dependencies.express"預期:輸出版本號與文件描述一致。
核對文件中的指令是否存在於 scripts:
node -p "Object.keys(require('./package.json').scripts).join('\n')"預期:文件提到的每個
npm run <name>都在清單中。檢查 Mermaid 圖可渲染(使用 Mermaid 官方 CLI):
npx -p @mermaid-js/mermaid-cli mmdc -i docs/architecture/refund.md -o evidence/refund-rendered.md預期:無語法錯誤;開啟輸出檔確認圖片產生。也可在 Orca 內建的 Markdown 檢視器直接預覽 Mermaid(見 12.7 節)。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 無幻覺路徑 | 步驟 1 腳本 | 無 MISSING: 輸出 | 以 Annotate 要求修正或刪除 |
| 端點一致 | 步驟 2 計數 | 與文件數量相同 | 修正文件 |
| 相依陳述正確 | 步驟 3 | 與文件陳述一致 | 修正文件或開架構議題 |
| 版本正確 | 步驟 4 | 與文件一致 | 修正文件 |
| 圖表可渲染 | 步驟 6 | 無錯誤 | 依第三十五章 Mermaid 規範修正 |
| 引用可追溯 | 抽查 5 個行號引用 | 全部屬實 | 抽查擴大到全部引用 |
⚠️ 注意事項:文件中的指令不要直接在主要 Worktree 或含正式憑證的環境執行驗證,尤其是 migrate、deploy、清除類指令。請在臨時 Worktree 或容器中執行。
22.7 驗收紀錄範本
概念說明
驗收紀錄是 L3 證據留存的核心產出:它把 L1 的輸出、L2 的審查決策、以及人類簽核凍結在同一份文件中,讓事後的稽核者、接手者或未來的自己能重現「當時為什麼判定可以合併」。建議存放在 docs/acceptance/<需求編號>.md 並隨 PR 一起合併;證據檔放在 evidence/ 或 CI artifact。
📌 查證狀態:Attribution 僅保存在 Orca 本機、不會寫入 git;若需要持久化,官方說明可從 Diff 工具列匯出 diff metadata|來源:Attribution。驗收紀錄格式本身為教學示例(非官方)。
範本
# 驗收紀錄:<需求編號> <標題>
## 1. 基本資訊
- 規格書:docs/specs/<需求編號>.md(版本 commit:<SHA>)
- 分支/PR:<branch>/<PR 連結>
- 受驗版本(HEAD):<SHA>
- 產出 Agent 與權限模式:<例:Claude Code/Manual>
- 風險等級:<低/中/高>
## 2. L1 自動化檢查
| 檢查 | 指令 | 結果 | exit code | 證據檔 |
|---|---|---|---|---|
| 範圍檢查 | scripts/check-scope.sh main '<regex>' | scope ok | 0 | evidence/<id>-scope.log |
| Lint | npm run lint | 通過 | 0 | evidence/<id>-lint.log |
| 型別檢查 | npm run typecheck | 通過 | 0 | evidence/<id>-typecheck.log |
| 測試 | npm test | <N> passed | 0 | evidence/<id>-test.log |
| Secret scan | gitleaks git --log-opts="main..HEAD" | no leaks found | 0 | evidence/<id>-gitleaks.log |
## 3. 驗收條件對照
| AC | 驗證方式 | 審查者親自執行結果 | 通過 |
|---|---|---|---|
| AC-1 | <指令> | <摘要> | 是/否 |
## 4. L2 人工審查
- 審查者:<姓名>(第二審查者:<姓名>,高風險必填)
- Diff 審查準則 D1~D10:<全部檢查/例外說明>
- Annotate 輪數:<N>;未解決意見:<0 或列出並指定負責人>
- 紅綠驗證:<已執行;main 上失敗的測試清單>
- 接受的 Agent 假設:<條列>
## 5. L3 證據清單
- 測試與掃描 log:<路徑或 CI 連結>
- Attribution 匯出:<路徑;高風險必填>
- Worktree Checkpoint 最終內容:<orca worktree current 的 comment>
## 6. 結論與簽核
- 結論:<核准合併/有條件核准/退回>
- 條件或後續事項:<條列>
- 簽核:<姓名> 日期:<YYYY-MM-DD>填寫範例(教學示例(非官方),非真實客戶專案)
# 驗收紀錄:ORD-1423 退款 API
## 1. 基本資訊
- 規格書:docs/specs/ORD-1423.md(版本 commit:4be71a0)
- 分支/PR:feat/ORD-1423-refund-api/#512
- 受驗版本(HEAD):c81d9e3
- 產出 Agent 與權限模式:Claude Code/Manual;Testing 角色 Codex/Auto
- 風險等級:高
## 2. L1 自動化檢查
| 檢查 | 指令 | 結果 | exit code | 證據檔 |
|---|---|---|---|---|
| 範圍檢查 | scripts/check-scope.sh(允許路徑依規格書第 3 節) | scope ok | 0 | evidence/ORD-1423-scope.log |
| Lint | npm run lint | 通過 | 0 | evidence/ORD-1423-lint.log |
| 型別檢查 | npm run typecheck | 通過 | 0 | evidence/ORD-1423-typecheck.log |
| 測試 | npm test | 64 passed | 0 | evidence/ORD-1423-test.log |
| Secret scan | gitleaks git --log-opts="main..HEAD" | no leaks found | 0 | evidence/ORD-1423-gitleaks.log |
## 3. 驗收條件對照
| AC | 驗證方式 | 審查者親自執行結果 | 通過 |
|---|---|---|---|
| AC-1 | npm test -- -t "full refund" | 1 passed | 是 |
| AC-2 | npm test -- -t "partial refund" | 2 passed | 是 |
| AC-3 | npm test -- -t "over refund" | 1 passed | 是 |
| AC-4 | npm test -- -t "idempotent" | 2 passed(含 5 並行請求) | 是 |
| AC-5 | git grep -n "parseFloat" -- src/modules/refund | 無輸出 | 是 |
| AC-6 | npm run lint && npm run typecheck && npm test | 全部 exit 0 | 是 |
## 4. L2 人工審查
- 審查者:林美玲(第二審查者:張志強,資安)
- Diff 審查準則 D1~D10:全部檢查;D9 例外:無相依變更
- Annotate 輪數:2;未解決意見:0
- 紅綠驗證:已執行;main 上失敗 4 個(full refund、partial refund x2、idempotent 並行)
- 接受的 Agent 假設:部分退款不限次數(PO 王小明 10/30 確認)
## 5. L3 證據清單
- 測試與掃描 log:CI run #8812 artifacts
- Attribution 匯出:evidence/ORD-1423-attribution.json
- Worktree Checkpoint 最終內容:ORD-1423 驗收完成,待合併
## 6. 結論與簽核
- 結論:核准合併
- 條件或後續事項:上線後一週內觀察退款失敗率
- 簽核:陳大華 日期:2026-10-30💡 小技巧:驗收紀錄的表格內若需要寫含 | 的正規表示式或管線指令,請改為引用腳本名稱(如上例),把完整指令放在腳本或證據檔中,避免破壞 Markdown 表格。
🧑⚖️ 人工 Review 要點(審核一份驗收紀錄時)
- 第 1 節 HEAD SHA 與 PR 實際合併的 commit 一致
- 第 2 節每一列都有證據檔,且證據檔存在、內容與「結果」欄一致
- 第 3 節每個 AC 都是審查者「親自執行」的結果,而非 Agent 回報
- 高風險變更有第二審查者、紅綠驗證與 Attribution 匯出
- 第 6 節簽核人與 RACI 表中該活動的 A 一致(見 21.4 節)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 紀錄已入版控 | git log --oneline -- docs/acceptance/ORD-1423.md | 有 commit 且在合併前 | 補交紀錄,並記錄延遲原因 |
| 證據檔可取得 | 逐一開啟第 5 節列出的檔案或 CI 連結 | 皆可開啟 | 補齊或重新產生 |
| 版本一致 | git rev-parse <PR merge commit>^2 與紀錄 HEAD 比對 | 一致 | 重新驗收合併版本 |
| 第三方可重現 | 請未參與者依第 2、3 節指令重跑 | 結果一致 | 修正紀錄中的指令 |
22.8 本章 Review 與驗證清單
- 能說出 AI 產出的八種失誤型態,並各舉一個抓法
- 能說明三層驗證模型各自回答的問題,以及為何不可互相替代
- 已建立並「驗證過」範圍檢查腳本(在越界分支上確實失敗)
- 已在 Orca Diff Viewer 中依 D1~D10 完成一次審查,並用 Annotate AI Diff 批次送回、Resolve
- 能在 22.3 的五個
diff範例中,不看說明就指出錯誤 - 已對一個新功能完成 E5 紅綠驗證,並保存紅階段失敗清單
- 已把一條 AI 產出的規範寫成 semgrep 規則,並以
semgrep --test驗證規則本身 - 已對一份 AI 產出的架構文件執行路徑存在檢查與相依交叉比對
- 已用 22.7 範本完成一份驗收紀錄,且由未參與者成功重現
第二十三章 企業 Web 應用程式開發案例
📌 查證狀態:教學示例(非官方),非真實客戶專案
本章以一個「內部客戶資料查詢與匯出」系統為例,完整示範如何在 Orca 中把一個中型企業 Web 需求拆成 6 個平行任務、分派給不同 Agent、在各自的 Worktree 中開發,最後由人工整合與驗收。重點不在於 AI 寫了多少程式碼,而在於:每一份 AI 產出都有明確的驗收條件,審查者知道要看什麼、跑什麼、預期看到什麼。
本章使用的 Orca 功能與對應章節:
| Orca 功能 | 本章用途 | 詳細說明 |
|---|---|---|
| Worktree 與 orca.yaml | 每個子任務一個隔離的 checkout | 第二章、第十一章 |
| Jira items drawer | 從 Jira Story 直接建立 Worktree 並保持連結 | 第十五章 |
| Orchestration(Experimental) | 以 Run/Task/Worker 追蹤 6 個子任務的完成狀態 | 第十六章 |
| Worktree Checkpoints | Agent 以 comment 回報目前進度 | 第十六章 |
| Annotate AI Diff 與 Attribution | 逐行審查並批次退回修正 | 第十四章 |
| 內建瀏覽器與 Design Mode | 前端畫面驗收與 UI 微調 | 第十三章 |
23.1 案例背景
情境:某企業的客服與業務單位需要一套內部 Web 系統「Customer Lookup」,用來依條件查詢客戶資料並匯出 CSV。現況是客服人員直接向 DBA 申請 SQL 撈資料,平均等待 1 個工作天,且匯出檔案沒有遮罩、沒有稽核紀錄。
功能需求
- 以客戶編號、姓名(模糊查詢)、手機末四碼、建立日期區間、客戶等級等條件查詢,支援伺服器端分頁與排序。
- 查詢結果可匯出 CSV,單次上限 50,000 筆;超過上限時改為非同步匯出並以通知告知下載。
- 個資欄位(身分證字號、手機、Email)依角色顯示遮罩值或明碼。
- 每次查詢與匯出皆寫入稽核紀錄(誰、何時、什麼條件、匯出筆數)。
非功能需求
| 類別 | 指標 | 驗收方式 |
|---|---|---|
| 效能 | 查詢 P95 小於 800 ms(100 萬筆資料、10 併發) | k6 壓測報告 |
| 可用性 | 99.9%,滾動更新不中斷 | K8s rolling update 演練 |
| 安全 | OIDC 登入、RBAC、個資遮罩、OWASP Top 10 無高風險 | ZAP baseline 掃描、程式碼審查 |
| 稽核 | 查詢與匯出 100% 留痕,保存 7 年 | 稽核表抽樣比對 |
| 可維護性 | 後端單元測試覆蓋率 80% 以上 | JaCoCo 報告 |
技術棧(教學情境設定)
| 層次 | 技術 | 備註 |
|---|---|---|
| 前端 | Vue 3 + TypeScript + Vite + PrimeVue + Tailwind CSS | Composition API、Pinia |
| 後端 | Spring Boot 4 + Java 25 | Spring Security(OIDC Resource Server)、Spring Data JPA |
| 資料庫 | PostgreSQL(新服務自有資料)+ Oracle(既有客戶主檔,唯讀) | Flyway 管理 PostgreSQL schema |
| 快取 | Redis | 熱門查詢條件與代碼表快取 |
| 部署 | Docker + Kubernetes(Helm Chart) | HPA、PodDisruptionBudget |
| CI | GitHub Actions | 建置、測試、映像檔掃描、推送 |
| 需求管理 | Jira | Epic CL-100,Story CL-101~CL-106 |
📌 查證狀態:教學示例(非官方)|技術棧版本僅為情境設定,實際專案請以當下穩定版本與公司技術標準為準。
Orca 專案準備
在 Repository 根目錄放入 orca.yaml 與 .worktreeinclude,讓每個新 Worktree 一建立就能直接建置,不必每次重新下載相依套件或手動複製設定。
# orca.yaml(repo 根目錄)
worktree:
sharedDirectories:
- frontend/node_modules
- .m2-cache# .worktreeinclude(repo 根目錄)
.env.local
backend/src/main/resources/application-local.yml⚠️ 注意事項:sharedDirectories 以 symlink/共用方式提供,適合可重建的大型目錄;.worktreeinclude 是「複製」,每個 Worktree 各自擁有一份。application-local.yml 只能放本機開發用的假帳密,正式憑證一律走 Vault 或 K8s Secret,不可透過 .worktreeinclude 散布到每個 Worktree。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 共用目錄已生效 | 在新 Worktree 執行 Get-Item frontend\node_modules(PowerShell)或 ls -la frontend/node_modules(bash) | 顯示為連結(LinkType 或 -> 指向主 checkout) | 確認該目錄在主 checkout 存在且已列入 .gitignore |
| 本機設定已複製 | 在新 Worktree 檢查 .env.local 是否存在 | 檔案存在且內容與主 checkout 一致 | 確認路徑為字面路徑(不支援 glob)且已被 gitignore |
| 無正式憑證外洩 | git grep -nE "password\s*[:=]\s*[^$]" -- "*.yml" | 無任何正式環境密碼 | 移除並輪替該憑證 |
23.2 需求拆解與 Agent 分派
拆解原則:先固定「契約」再平行開發。本案例最常見的失敗模式是前端、後端、資料庫三個 Agent 各自假設不同的欄位名稱與分頁格式,整合時才發現對不起來。因此 T0「API 契約」必須先完成並經人工核准,其餘任務才能開始。
flowchart TD
REQ["Jira Epic CL-100 客戶查詢與匯出"] --> T0["T0 API 契約 OpenAPI"]
T0 --> GATE{"人工核准契約"}
GATE -->|"核准"| T1["T1 後端 API 與商業邏輯"]
GATE -->|"核准"| T2["T2 前端查詢與匯出頁"]
GATE -->|"核准"| T3["T3 資料庫 Schema 與 Migration"]
GATE -->|"退回"| T0
T3 --> T4["T4 Redis 快取策略"]
T1 --> T4
REQ --> T5["T5 Helm Chart 與 K8s 設定"]
REQ --> T6["T6 GitHub Actions Pipeline"]
T1 --> INT["整合 Worktree integ/cl-100"]
T2 --> INT
T4 --> INT
T5 --> INT
T6 --> INT
INT --> UAT["UAT 與上線審查"]如何閱讀此圖:由上而下是時間順序。T0 契約是唯一的起點,菱形「人工核准契約」是決策閘門(對應 Orca Orchestration 的 decision gate),只有核准後 T1~T3 才平行開工;T4 快取依賴後端與 Schema 完成;T5、T6 屬於平台類任務,與業務邏輯無相依,可從一開始就平行進行。所有分支最後匯入整合 Worktree,再進入 UAT。
任務拆解表
| 任務 | Agent | Worktree 分支 | 交付物 | 驗收條件 |
|---|---|---|---|---|
| T0 API 契約 | Claude Code | feature/CL-101-api-contract | api/customer-lookup.yaml(OpenAPI 3.1)、契約說明 | npx @redocly/cli lint 零錯誤;人工核准欄位、錯誤碼、分頁格式 |
| T1 後端 API | Codex | feature/CL-102-backend-api | Controller、Service、Repository、遮罩元件、稽核寫入、測試 | mvn verify 通過;覆蓋率 80% 以上;契約測試通過 |
| T2 前端頁面 | Claude Code | feature/CL-103-frontend | 查詢頁、結果表格、匯出按鈕、Pinia store、Vitest 測試 | npm run test 與 npm run build 通過;Design Mode 檢視無跑版 |
| T3 資料庫 | Codex | feature/CL-104-db-migration | Flyway V1__~V3__ 腳本、索引策略說明、Oracle 唯讀 View 規格 | flyway validate 通過;EXPLAIN 顯示走索引 |
| T4 快取 | Claude Code | feature/CL-105-redis-cache | @Cacheable 設定、TTL 與失效規則文件、測試 | Testcontainers Redis 測試通過;個資不進快取 |
| T5 K8s | Codex | feature/CL-106-helm | Helm Chart(Deployment、Service、HPA、PDB、NetworkPolicy) | helm lint、kubeconform 通過;無明文 Secret |
| T6 CI | Codex | feature/CL-106-ci | .github/workflows/ci.yml | actionlint 通過;PR 上實際觸發成功 |
操作步驟:從 Jira 建立 Worktree
- 開啟 Orca 左側 Tasks,來源切換為 Jira,搜尋
CL-101。 - 開啟 Issue 詳細抽屜,確認描述與驗收條件完整後,選擇從此 Issue 建立 Worktree。Orca 會預填名稱並把 Worktree 與 Jira Issue 連結,卡片上會顯示 Issue key 與摘要。
- 在 Create Workspace 對話框展開 Advanced,於 Branch name 輸入
feature/CL-101-api-contract(若團隊有分支命名規範),Agent 選 Claude Code。 - 重複以上步驟建立 T1~T6;T1~T3 先建立但暫不送出 Prompt,等 T0 核准。
也可以用 CLI 一次建立(適合由 Coordinator Agent 或腳本執行):
orca worktree create --name CL-101-api-contract --branch feature/CL-101-api-contract \
--reference https://acme.atlassian.net/browse/CL-101 --agent claude --setup run --json
orca worktree create --name CL-105-redis-cache --branch feature/CL-105-redis-cache \
--reference https://acme.atlassian.net/browse/CL-105 --agent claude --setup run --json以 Orchestration 追蹤任務(選用)
當任務數量超過 5 個,建議改用 Orchestration 讓每個 Worker 以 worker_done 明確回報,而不是靠人眼盯著每個終端機。先到 Settings → Experimental 啟用 Orchestration,並確認 orca status --json 成功。
orca orchestration run-create --objective "CL-100 Customer Lookup:契約優先,平行開發 T1-T6" --json
orca orchestration task-create --task-title "T0 API 契約" --spec "依 docs/specs/CL-101.md 產出 OpenAPI 3.1" --json
orca orchestration worker-start --task <T0-taskId> --worktree new-child --name CL-101-api-contract --agent claude --setup run --json
orca orchestration gate-create --task <T1-taskId> --question "T0 契約是否核准,可開始實作?" --options '["yes","no"]' --json
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json人工確認契約後,由技術主管執行:
orca orchestration gate-resolve --id <gateId> --resolution "yes" --json📌 查證狀態:依官方說明延伸(教學推論)|來源:Orchestration。Orchestration 為 Experimental 功能,旗標可能隨版本調整,請以
orca skills get orchestration --full輸出為準。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 7 個 Worktree 均已建立 | git worktree list | 列出 7 個 feature/CL-10x-* 分支 | 在 Orca 卡片查看建立進度列與錯誤訊息,點 Retry |
| Jira 連結正確 | Worktree 卡片顯示 CL-10x 與 View on Jira | 每張卡片連結到對應 Story | 於 Edit Worktree Details → Linked work 重新貼上 URL |
| Orchestration 任務可見 | orca orchestration task-list --json | 7 筆任務,T1~T3 為 blocked 或 pending | 確認 Experimental 已啟用、Run 已建立 |
| 閘門生效 | 未 resolve 前檢查 T1 狀態 | T1 未被 dispatch | 確認 gate 建立在正確的 taskId |
23.3 分派 Prompt 範例
所有 Prompt 都遵循第二十章的任務規格書結構:背景 → 範圍(可改/不可改)→ 輸入 → 交付物 → 驗收條件 → 回報方式。以下列出 5 則完整 Prompt。
23.3.1 T0 API 契約 Prompt
範例 Prompt
你是本專案的 API 設計者。請在目前 Worktree 完成 Jira CL-101。
【背景】
內部系統 Customer Lookup,前端 Vue 3、後端 Spring Boot 4。契約完成後會交給三個 Agent 平行實作,
因此契約必須精確、無歧義。
【範圍】
- 只可新增或修改:api/customer-lookup.yaml、docs/api/README.md
- 不可修改任何 backend/、frontend/ 程式碼
【需求】
1. GET /api/v1/customers:查詢參數 customerNo、name(模糊)、mobileLast4、createdFrom、createdTo、tier、
page(從 0 開始)、size(預設 20,最大 100)、sort(例:createdAt,desc)
2. 回應採 { content: [...], page: { number, size, totalElements, totalPages } }
3. Customer 欄位:customerNo、name、nationalIdMasked、mobileMasked、emailMasked、tier、createdAt(ISO-8601)
明碼欄位只在具 PII_VIEW 權限時回傳於 nationalId、mobile、email,否則該欄位不出現
4. POST /api/v1/customers/exports:同步匯出上限 50000 筆,超過回 202 與 exportId
5. GET /api/v1/customers/exports/{exportId}:查詢非同步匯出狀態
6. 錯誤格式統一採 RFC 9457 Problem Details,列出 400、401、403、404、422、429、500 的範例
7. 所有端點宣告 security: bearerAuth(OIDC JWT)
【驗收條件】
- 執行 npx @redocly/cli lint api/customer-lookup.yaml 零 error
- 每個 schema 欄位有 description 與 example
- 在 docs/api/README.md 列出「設計決策與待確認事項」
【回報】
完成後執行 orca worktree set --worktree active --comment "<摘要>" --workspace-status in-review --json,
並貼出 lint 指令的完整輸出。不要自行 commit。🧑⚖️ 人工 Review 要點(AI 依此 Prompt 產出後,審查者應逐項確認)
-
git diff --stat只出現api/與docs/api/兩個路徑 - 分頁從 0 或 1 開始已明確寫在 description,且與 Spring Data
Pageable一致 - 明碼欄位與遮罩欄位的出現條件寫清楚,沒有「視情況」之類模糊描述
-
size有maximum: 100,避免前端一次拉全表 - 錯誤回應的
type、title、status、detail符合 RFC 9457 - 「待確認事項」中的問題已由 PO 或架構師逐項答覆,答覆寫回 README 後才核准契約
✅ 驗證方式
執行:
npx @redocly/cli lint api/customer-lookup.yaml預期輸出(示意):
validating api/customer-lookup.yaml... api/customer-lookup.yaml: validated in 48ms Woohoo! Your API description is valid. 🎉判讀:若出現
operation-4xx-response或no-unused-components警告,要求 Agent 修正;error 數必須為 0 才能 resolve 閘門。
23.3.2 T1 後端 API Prompt
範例 Prompt
請在目前 Worktree 完成 Jira CL-102:依 api/customer-lookup.yaml(已核准,不可修改)實作後端。
【技術約束】
- Java 25、Spring Boot 4、Spring Data JPA、Spring Security OAuth2 Resource Server
- 套件根:com.acme.customerlookup;分層 web / service / repository / domain / audit / masking
- 查詢 Oracle 客戶主檔僅能透過唯讀 View CUST_LOOKUP_V(由 T3 定義),不可直接存取原始表
- 稽核紀錄寫入 PostgreSQL audit_log 表(T3 建立)
【必做】
1. CustomerController 回應格式與 HTTP 狀態碼必須完全符合 OpenAPI
2. PiiMaskingService:身分證 A123456789 → A12****789;手機 0912345678 → 0912***678;
Email alice@example.com → a****@example.com
3. 具 PII_VIEW 角色才回傳明碼;遮罩邏輯放在 Service 層,不可只在前端遮罩
4. 每次查詢與匯出呼叫 AuditService.record(),紀錄 userId、action、criteria(JSON)、resultCount、clientIp
5. 匯出採 StreamingResponseBody,避免一次載入 50000 筆至記憶體
6. 輸入驗證:name 至少 2 字元、日期區間不得超過 366 天,違反回 422 Problem Details
【測試】
- 單元測試:PiiMaskingService 每種格式至少 3 個案例(含 null、長度不足)
- @WebMvcTest:403(無角色)、422(驗證失敗)、200(遮罩與明碼兩種)
- 以 Testcontainers PostgreSQL 執行 AuditService 整合測試
- 執行 mvn -B verify,貼出 Tests run 摘要與 JaCoCo 覆蓋率
【禁止】
- 不可修改 api/、frontend/、db/ 目錄
- 不可在 log 中輸出明碼個資
- 不可停用或刪除任何既有測試
完成後以 orca worktree set 更新 comment 並將狀態設為 in-review。🧑⚖️ 人工 Review 要點
- 遮罩在 Service 層執行,Controller 不直接回傳 Entity
- 以 Attribution 標記確認
masking/、audit/的 AI 產出行,逐行審查邊界條件 - 搜尋
log.info、log.debug的參數,確認沒有直接印出 Customer 物件或身分證欄位 -
@PreAuthorize或 SecurityFilterChain 的規則與 OpenAPI 的 security 宣告一致 - 匯出確實是串流(檢查回傳型別),而非
List全載入後再寫出 - 測試報告為實際輸出,
Tests run數量與新增測試檔數量合理對應
✅ 驗證方式
執行:
cd backend mvn -B verify git grep -nE "log\.(info|debug|warn)\(.*(nationalId|mobile|email)" -- "src/main/**/*.java"預期輸出(示意):
[INFO] Tests run: 64, Failures: 0, Errors: 0, Skipped: 0 [INFO] --- jacoco:0.8.13:check (jacoco-check) @ customer-lookup --- [INFO] All coverage checks have been met. [INFO] BUILD SUCCESS第二個
git grep應無任何輸出。判讀:若
git grep有命中,代表 log 可能洩漏個資,以 Annotate AI Diff 在該行留言並退回。
23.3.3 T2 前端頁面 Prompt
範例 Prompt
請在目前 Worktree 完成 Jira CL-103:客戶查詢頁。
【輸入】
- api/customer-lookup.yaml(唯一真相來源)
- 設計稿:Jira CL-103 附件 lookup-page.png
【技術約束】
- Vue 3 Composition API + <script setup lang="ts">、Pinia、PrimeVue DataTable(lazy 模式)、Tailwind CSS
- 以 openapi-typescript 從契約產生型別到 src/api/generated.ts,不可手寫 DTO 型別
- API 呼叫集中在 src/api/customerApi.ts
【功能】
1. 查詢表單:欄位與驗證規則與契約一致(name 至少 2 字元、日期區間不超過 366 天)
2. DataTable 伺服器端分頁與排序;page 從 0 開始
3. 匯出按鈕:回應 200 直接下載;回應 202 顯示「已排入背景匯出」並輪詢狀態
4. 前端僅顯示後端回傳值,不得自行做遮罩或解遮罩
5. 錯誤以 Toast 顯示 Problem Details 的 title 與 detail
【測試】
- Vitest + Vue Test Utils:表單驗證、分頁參數組裝、202 流程
- 執行 npm run lint、npm run test -- --run、npm run build,貼出輸出
【範圍】只可修改 frontend/ 目錄。完成後啟動 npm run dev,並以 orca goto 開啟 http://localhost:5173/customers。🧑⚖️ 人工 Review 要點
-
src/api/generated.ts確實由工具產生(檔頭有產生器註記),沒有手動修改 - 分頁參數
page未被誤加 1 - 在 Orca 內建瀏覽器實際操作查詢、換頁、排序、匯出 4 個流程
- 以 Design Mode 點選有跑版的元件,把截圖與 DOM 脈絡直接送給 Agent 修正,避免文字描述不清
- 沒有把 Token 存在
localStorage(應依公司 OIDC 前端規範)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 型別與契約同步 | npx openapi-typescript ../api/customer-lookup.yaml -o src/api/generated.ts 後執行 git diff --exit-code src/api/generated.ts | 無差異(exit code 0) | 契約已變更或 Agent 手改型別,重新產生 |
| 單元測試 | npm run test -- --run | Test Files 6 passed、無 failed | 用 Annotate AI Diff 指出失敗原因後退回 |
| 建置 | npm run build | 產出 dist/,無 TypeScript 錯誤 | 檢查 vue-tsc 錯誤行 |
| 畫面驗收 | Orca 內建瀏覽器開啟查詢頁並操作 | 分頁、排序、匯出皆正常 | 用 Design Mode 標記元件並送回 Agent |
23.3.4 T3 資料庫 Prompt
範例 Prompt
請在目前 Worktree 完成 Jira CL-104:資料庫 Schema 與 Migration。
【範圍】只可修改 db/ 與 docs/db/。
【PostgreSQL(Flyway,位置 db/migration/postgresql)】
1. V1__create_audit_log.sql:audit_log(id bigserial PK, occurred_at timestamptz not null,
user_id varchar(64) not null, action varchar(32) not null, criteria jsonb, result_count int,
client_ip inet),依 occurred_at 做月分割(declarative partitioning)
2. V2__create_export_job.sql:export_job 表(exportId uuid、狀態、建立者、檔案位置、到期時間)
3. V3__indexes.sql:audit_log(user_id, occurred_at desc)
4. audit_log 只允許 INSERT 與 SELECT:建立角色 app_writer,撤銷 UPDATE、DELETE 權限
【Oracle(僅文件,不執行)】
5. docs/db/oracle-view-spec.md:定義唯讀 View CUST_LOOKUP_V 所需欄位與建議索引
(例如 CUSTOMER(MOBILE_LAST4)、CUSTOMER(UPPER(NAME))),並說明需由 DBA 執行
【驗證】
- 以 docker compose 啟動 PostgreSQL,執行 flyway migrate 與 flyway validate,貼出輸出
- 對 audit_log 灌入 100 萬筆測試資料,貼出常用查詢的 EXPLAIN (ANALYZE, BUFFERS)
【禁止】不可產生任何對 Oracle 的 DDL 或 DML 執行腳本;不可使用 DROP 或 TRUNCATE。🧑⚖️ 人工 Review 要點
- Migration 檔名版本號連續且不與既有版本衝突
-
REVOKE UPDATE, DELETE確實存在,確保稽核表不可竄改 -
EXPLAIN輸出顯示Index Scan或Bitmap Index Scan,而非全表Seq Scan - Oracle 部分只有文件,沒有可執行腳本;由 DBA 依公司變更流程處理
- 分割表有建立未來 3 個月分割或自動建立機制(例:pg_partman)
✅ 驗證方式
執行:
docker compose -f db/docker-compose.yml up -d flyway -configFiles=db/flyway.conf migrate flyway -configFiles=db/flyway.conf validate psql -h localhost -U app_writer -d lookup -c "DELETE FROM audit_log WHERE id = 1;"預期輸出(示意):
Successfully applied 3 migrations to schema "public", now at version v3 Successfully validated 3 migrations ERROR: permission denied for table audit_log判讀:最後一行必須是 permission denied;若 DELETE 成功,代表稽核表可被竄改,不可合併。
23.3.5 T5 與 T6 平台任務 Prompt
範例 Prompt
請在目前 Worktree 完成 Jira CL-106 的兩項平台設定(Helm 與 CI 分屬兩個 Worktree,本 Worktree 只做 Helm)。
【Helm Chart:deploy/helm/customer-lookup】
1. Deployment:replicas 3、readinessProbe /actuator/health/readiness、livenessProbe /actuator/health/liveness、
resources requests/limits 明確設定、securityContext runAsNonRoot: true、readOnlyRootFilesystem: true
2. HPA:CPU 70%,min 3、max 10
3. PodDisruptionBudget:minAvailable 2
4. NetworkPolicy:只允許 ingress-nginx namespace 進入 8080;egress 只允許 PostgreSQL、Oracle、Redis、OIDC Provider
5. Secret 一律以 ExternalSecret 參照 Vault 路徑 kv/customer-lookup,不可出現任何 base64 明文
6. values-dev.yaml、values-prod.yaml 分開,namespace 命名遵循 team-crm-<env>
【驗證】
- helm lint deploy/helm/customer-lookup
- helm template . -f values-prod.yaml | kubeconform -strict -summary
- 貼出兩者完整輸出🧑⚖️ 人工 Review 要點
-
helm template輸出中搜尋kind: Secret,應為 0 筆(全部是 ExternalSecret) -
values-prod.yaml的映像檔 tag 使用不可變 digest 或明確版本,不是latest - NetworkPolicy 的 egress 沒有
0.0.0.0/0 - K8s 與 CI 設定屬於高風險變更,需平台團隊(非原 Prompt 撰寫者)第二人審查
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Chart 語法 | helm lint deploy/helm/customer-lookup | 1 chart(s) linted, 0 chart(s) failed | 依錯誤行修正 |
| Manifest 合法 | helm template ... | kubeconform -strict -summary | Invalid: 0, Errors: 0 | 檢查 API 版本是否過時 |
| 無明文 Secret | helm template ... | grep -c "kind: Secret" | 0 | 改為 ExternalSecret |
| CI 語法 | actionlint .github/workflows/ci.yml | 無輸出 | 依 actionlint 訊息修正 |
23.4 整合與驗收
整合順序
各任務在自己的 Worktree 通過驗收後,建立整合 Worktree integ/cl-100,依「相依性由下而上」合併:T0 → T3 → T1 → T4 → T2 → T5 → T6。每合併一個就跑一次完整測試,避免多個變更同時進入後難以定位問題。
orca worktree create --name integ-cl-100 --branch integ/cl-100 --agent claude --setup run --json
git merge --no-ff feature/CL-101-api-contract
git merge --no-ff feature/CL-104-db-migration
git merge --no-ff feature/CL-102-backend-api
mvn -B -f backend/pom.xml verify整合驗收的四道關卡
| 關卡 | 方法 | 工具/指令 | 通過條件 |
|---|---|---|---|
| 1 契約一致 | 後端實際產出的 OpenAPI 與設計契約比對 | oasdiff breaking api/customer-lookup.yaml target/openapi.json | 無 breaking change |
| 2 契約測試 | 以契約驅動的 HTTP 測試打後端 | npx @stoplight/prism-cli proxy 或 Schemathesis | 無 schema 違反 |
| 3 端對端 | Playwright 跑查詢、分頁、匯出 | npx playwright test | 全數通過 |
| 4 非功能 | 壓測與安全掃描 | k6 run perf/lookup.js、ZAP baseline | P95 小於 800 ms;無 High 風險 |
契約一致性驗證範例
curl -s http://localhost:8080/v3/api-docs -o target/openapi.json
oasdiff breaking api/customer-lookup.yaml target/openapi.json --fail-on ERR
schemathesis run api/customer-lookup.yaml --url http://localhost:8080 --checks all \
-H "Authorization: Bearer $TEST_TOKEN"✅ 驗證方式
執行上述三行指令。
預期輸出(示意):
No breaking changes found ... ======================== SUMMARY ======================== Performed checks: not_a_server_error 412 / 412 passed PASSED status_code_conformance 412 / 412 passed PASSED response_schema_conformance 412 / 412 passed PASSED判讀:若
oasdiff回報response-property-removed之類訊息,表示後端偏離契約;以 Annotate AI Diff 在 T1 對應 Controller 留言後 Send to agent,而不是在整合分支上直接手改。
審查回饋循環
- 在整合 Worktree 開啟 Diff Viewer,切換到 Attribution 檢視,優先審查 AI 產出比例高的檔案(
masking/、audit/、NetworkPolicy)。 - 對每個問題行按
+留言,全部留完後點 Send to agent,選擇原任務的 Agent(或新開一個 Reviewer Agent)。 - 修正後,原留言仍釘在原行,逐條確認並 Resolve。
- 若需要留存「哪些行由 AI 產出」作為稽核證據,從 Diff 工具列匯出 diff metadata(Attribution 本身不會寫入 git)。
- 於 Source Control 面板 Commit;若 pre-commit hook 失敗,可用 Fix with AI 交由 Agent 修復,但修復結果仍需重新審查。
- Push 後以 hosted review 動作建立 PR,PR 描述中附上四道關卡的指令輸出摘要。
企業治理考量
| 面向 | 本案做法 |
|---|---|
| 權限 | Prompt 明確要求 Agent 不自行 commit 與 push;commit 由人工在 Source Control 面板執行 |
| 稽核 | Jira Issue ↔ Worktree ↔ PR 三者互相連結;Attribution metadata 匯出歸檔 |
| 資安 | 個資遮罩、稽核表防竄改、NetworkPolicy、無明文 Secret 四項列為必審 |
| 成本 | 契約與資安相關任務用較強模型,Helm/CI 樣板任務用較經濟模型(見第八章) |
❌ 常見錯誤
- 讓 T1、T2 在契約核准前就開工,最後花更多時間對齊欄位。
- 在整合分支直接修 AI 的錯誤,導致原任務分支與整合分支內容分歧,下次重跑無法重現。
- 只看「測試全綠」就合併,沒有檢查測試是否真的覆蓋遮罩與權限的負向案例。
💡 小技巧:把本章 T0~T6 的拆分當作「多層企業 Web 應用」模板,存成團隊的 Jira Epic 範本與 Prompt 範本;下一個專案只需替換領域欄位即可起手。
23.5 本章 Review 與驗證清單
- 能說明為何「契約優先」是多 Agent 平行開發的前提,並能用 decision gate 落實
- 已為每個子任務填寫「任務/Agent/分支/交付物/驗收條件」五欄表格
- 已實際執行
npx @redocly/cli lint並得到零 error - 已實際執行
mvn -B verify並確認 JaCoCo 覆蓋率檢查通過 - 已驗證
audit_log的 DELETE 會被拒絕(permission denied) - 已確認 Helm 輸出中沒有明文
kind: Secret - 已以
oasdiff與 Schemathesis 驗證後端與契約一致 - 已使用 Annotate AI Diff 批次退回至少一輪修正,並逐條 Resolve
- 已匯出 Attribution metadata 並與 PR 一起歸檔
第二十四章 舊系統逆向工程
📌 查證狀態:教學示例(非官方),非真實客戶專案
逆向工程(Reverse Engineering)的目標是「在沒有可靠文件的情況下,重建對系統的正確理解」。AI Agent 很擅長快速閱讀大量程式碼並產出摘要,但也很擅長自信地說錯。因此本章的核心方法是:每一條 AI 結論都必須能追溯到原始碼位置,並能被機械方式或抽樣方式驗證。Orca 在此提供的是平行容器、遠端執行與進度追蹤;實際的程式理解能力取決於底層 Agent CLI 與模型。
24.1 適用情境
典型觸發點
| 觸發點 | 說明 | 逆向工程的產出用途 |
|---|---|---|
| 系統要升級或重寫 | 例:Struts 1 要改為 Spring Boot | 範圍估算、遷移計畫(銜接第二十五章) |
| 原開發者離職或外包合約結束 | 知識只存在於程式碼中 | 交接文件、On-call 手冊 |
| 稽核或監理要求 | 需說明資料流與個資處理位置 | 資料流圖、個資欄位清單 |
| 事故頻繁 | 不清楚批次之間的相依關係 | 批次相依圖、失敗重跑手冊 |
| 併購或系統整合 | 需評估兩套系統的介面 | 介面清單、資料字典 |
本章示範系統(教學情境):某物流公司的訂單系統「LOGI-ORD」,運行 15 年,約 120 萬行程式碼:
| 模組 | 技術棧 | 規模(示意) | 原始碼位置 |
|---|---|---|---|
| M1 訂單受理 | Java 6、Struts 1.3、JSP | 約 1,800 個類別 | web/ |
| M2 交易核心 | EJB 2.1 Session Bean、WebLogic | 約 600 個類別 | ejb/ |
| M3 資料層 | Oracle PL/SQL Package、Trigger | 約 240 個 Package | db/plsql/ |
| M4 夜間結算 | COBOL 批次、JCL | 約 300 支程式、180 個 Copybook | mainframe/ |
| M5 管理報表 | ASP.NET Web Forms(.NET Framework 4.x) | 約 150 個頁面 | reports/ |
企業限制:原始碼與資料庫結構屬機敏資料,不可離開公司內網。因此 Agent 必須在內網的分析主機上執行,這正好使用 Orca 的 SSH Worktrees:編輯器與 Diff 在本機呈現,但 Agent 與檔案都在遠端主機。
操作步驟:設定內網分析主機
- 開啟 Settings → SSH → Add Target,填入
analysis01.corp.local、使用者與私鑰;或從 OpenSSH config picker 選取既有主機。 - 點 Test 確認連線與 Host key 指紋,再按 Save。
- 保持 Advanced Connection → Allow this host’s orca CLI to control Orca 為關閉(預設),避免遠端 Agent 能操作你本機的其他主機或設定。
- 建立 Worktree 時,Run on 選擇
analysis01。
📌 查證狀態:官方文件明確記載|來源:SSH worktrees
⚠️ 注意事項:遠端主機上的 Agent CLI 仍會把程式碼內容送往其模型供應商。若公司政策禁止原始碼外送,必須改用核准的私有部署模型或企業合約保障的端點(見第二十八章),SSH 只解決「檔案不落地到筆電」,不解決「模型端資料外送」。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| SSH 連線正常 | Worktree 卡片的 SSH 狀態晶片 | 綠色 connected | 依錯誤訊息處理 known_hosts 或金鑰,見第十八章 |
| Worktree 位於遠端 | 在 Worktree 終端機執行 hostname | 輸出 analysis01 | 重新建立並確認 Run on 選擇 |
| 遠端 CLI 權限受限 | Settings → SSH → 編輯主機 → Advanced Connection | 控制開關為關閉 | 關閉後開新終端機 |
24.2 平行盤點策略
兩階段策略:先粗掃、再深掘
一次要求 Agent「完整分析這個 120 萬行的系統」幾乎必然失敗:Context 不足、產出深淺不一、無法驗證。正確做法是分兩階段:
| 階段 | 目的 | 每個 Agent 的範圍 | 產出 | 時間盒 |
|---|---|---|---|---|
| 第一階段 粗掃(Survey) | 建立地圖:有哪些元件、進出點、外部相依 | 一個模組 | 元件清單、進出點清單、待深掘清單 | 每模組 2 小時 |
| 第二階段 深掘(Deep Dive) | 理解關鍵業務流程的實際邏輯 | 一條業務流程(跨模組) | 流程說明、規則表、特性測試(Characterization Test) | 每流程 1 天 |
flowchart LR
subgraph S1["第一階段 粗掃(依模組平行)"]
A1["Agent 1 M1 Struts"]
A2["Agent 2 M2 EJB"]
A3["Agent 3 M3 PL/SQL"]
A4["Agent 4 M4 COBOL"]
A5["Agent 5 M5 ASP.NET"]
end
S1 --> MAP["系統地圖與待深掘清單"]
MAP --> REV{"資深工程師篩選"}
subgraph S2["第二階段 深掘(依業務流程平行)"]
F1["流程 A 下單到出貨"]
F2["流程 B 運費計算"]
F3["流程 C 夜間結算"]
end
REV --> S2
S2 --> OUT["現況報告與特性測試"]如何閱讀此圖:第一階段以「模組」切分,5 個 Agent 各自在獨立 Worktree 中粗掃,產出統一格式的地圖;資深工程師依業務重要性與風險挑選第二階段的深掘目標,第二階段改以「業務流程」切分,因為真正的業務規則常橫跨多個模組(例如運費計算同時存在於 Struts Action、EJB 與 PL/SQL)。
任務拆解表
| 任務 | Agent | Worktree 分支 | 交付物 | 驗收條件 |
|---|---|---|---|---|
| R1 粗掃 M1 | Claude Code | re/R1-survey-struts | docs/re/M1-survey.md、docs/re/M1-routes.csv | 路由數與 struts-config.xml 中 action 數一致 |
| R2 粗掃 M2 | Codex | re/R2-survey-ejb | docs/re/M2-survey.md、docs/re/M2-beans.csv | Bean 數與 ejb-jar.xml 一致;交易屬性完整列出 |
| R3 粗掃 M3 | Codex | re/R3-survey-plsql | docs/re/M3-survey.md、docs/re/M3-objects.csv | 物件數與 USER_OBJECTS 查詢結果一致 |
| R4 粗掃 M4 | Claude Code | re/R4-survey-cobol | docs/re/M4-survey.md、docs/re/M4-jobs.csv | JCL 步驟與程式對應完整;Copybook 引用可追溯 |
| R5 粗掃 M5 | Codex | re/R5-survey-aspnet | docs/re/M5-survey.md、docs/re/M5-pages.csv | 頁面數與 .aspx 檔案數一致 |
| D1 深掘運費計算 | Claude Code | re/D1-freight-calc | docs/re/flows/freight.md、特性測試 | 規則表每列附原始碼位置;特性測試在現行系統上全數通過 |
以 Orchestration 管理兩階段
orca orchestration run-create --objective "LOGI-ORD 逆向工程:5 模組粗掃後挑選流程深掘" --json
orca orchestration task-create --task-title "R1 粗掃 M1 Struts" --spec "依 docs/re/TEMPLATE.md 粗掃 web/" --json
orca orchestration worker-start --task <R1-taskId> --worktree new-child --name re-R1-survey-struts --agent claude --json
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --jsonWorker 遇到需要人判斷的問題(例如「這兩個同名 Action 哪一個仍在使用?」)時,應以 orca orchestration ask 回問 Coordinator,而不是自行猜測:
orca orchestration ask --to <coordinatorHandle> \
--question "OrderAction 與 OrderActionV2 皆在 struts-config 註冊,是否兩者都在正式環境使用?" \
--options "both,v2-only,unknown" --timeout-ms 600000 --json粗掃期間,請 Agent 在每個里程碑以 Worktree Checkpoint 更新狀態,讓人不必進終端機就能看懂進度:
orca worktree set --worktree active \
--comment "M1 粗掃:已完成 412/412 action 對應;發現 37 個 action 無 JSP 引用,列入待確認" \
--workspace-status in-progress --json✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 粗掃任務都已回報 | orca orchestration task-list --json | R1~R5 皆為 completed | 用 worker-read --dispatch 查看卡在哪裡 |
| 回報包含具體數字 | 檢查各 Worktree comment | 有「已完成 N/M」形式的進度 | 要求 Agent 依 Checkpoint 格式重寫 |
| 問題有被提出而非猜測 | 檢查 Coordinator inbox 的 question 訊息 | 有疑義的項目都有 ask 紀錄 | 在 Prompt 中強化「不確定必須 ask」 |
24.3 各技術棧逆向重點
盤點重點總表
| 技術棧 | 必盤點項目 | 機械驗證方式 | 常見陷阱 |
|---|---|---|---|
| Java 6/7/8 一般 | 套件相依、JDK 內部 API、第三方函式庫版本 | jdeps -summary、jdeps --jdk-internals | 反射呼叫在靜態分析中看不到 |
| Struts 1.x | Action ↔ Form ↔ JSP ↔ Forward 對應、Validator 規則 | 解析 struts-config.xml 計數 | 動態 Forward、Tiles 定義 |
| EJB 2.x | Home/Remote 介面、交易屬性、JNDI 名稱、MDB 佇列 | 解析 ejb-jar.xml、weblogic-ejb-jar.xml | 容器管理交易的隱性邊界 |
| Spring MVC 舊版 | XML 與註解混用、AOP 切面 | 計數 <bean 與 @Component | 切面改變了看似單純的方法行為 |
| Oracle PL/SQL | Package 相依、Trigger、動態 SQL | 查詢 USER_DEPENDENCIES | Trigger 中的隱藏業務規則 |
| COBOL + JCL | Copybook 資料結構、JCL 步驟、檔案輸入輸出 | 計數 COPY 敘述與 EXEC PGM= | REDEFINES、COMP-3 欄位 |
| ASP.NET Web Forms | 頁面生命週期、ViewState、Code-behind 中的 SQL | 計數 .aspx、搜尋 SqlCommand | 在 Page_Load 的 PostBack 分支藏邏輯 |
| Delphi/VB6 | 表單事件、直接資料庫存取 | 搜尋 ADOQuery、Recordset | 全域變數造成的隱性狀態 |
24.3.1 Struts 與 EJB 粗掃 Prompt
範例 Prompt
你正在協助逆向工程 LOGI-ORD 的 M1(web/,Struts 1.3)。這是唯讀分析任務。
【規則】
1. 不可修改 web/ 下任何檔案;只可新增 docs/re/M1-*.md 與 docs/re/M1-*.csv
2. 每一項結論都要附來源,格式為 path:line,例如 web/WEB-INF/struts-config.xml:214
3. 不確定的事項寫入「待確認」區,不可猜測;需要人判斷時用 orca orchestration ask
4. 依 docs/re/TEMPLATE.md 的章節結構輸出
【產出】
A. docs/re/M1-routes.csv,欄位:path, actionClass, formBean, validate, forwards, jsp, sourceRef
B. docs/re/M1-survey.md:
- 模組職責(3 句內)
- 進出點:所有 HTTP 路由、對 EJB 的呼叫(列出 JNDI 名稱)、直接 JDBC 呼叫
- 外部相依:執行 jdeps -summary 與 jdeps --jdk-internals 的結果摘要
- 技術債與風險:使用 sun.* 內部 API、未關閉的 Connection、在 Action 中直接寫 SQL
- 待深掘清單:依「業務重要性 × 不確定性」排序前 10 項
【自我檢查】
完成前,請執行以下指令並把輸出貼在 M1-survey.md 附錄,證明 CSV 筆數與原始設定一致:
grep -c "<action " web/WEB-INF/struts-config*.xml
tail -n +2 docs/re/M1-routes.csv | wc -l🧑⚖️ 人工 Review 要點
-
git diff --stat只有docs/re/底下的新檔案 - CSV 筆數與
<action計數一致(差異必須逐筆說明,例如被註解掉的 action) - 隨機抽 10 列
sourceRef,開啟對應檔案確認行號與內容相符;正確率低於 90% 即整份退回 - 「待確認」區不是空的(120 萬行系統沒有任何不確定處,通常代表 Agent 在猜)
- JDK 內部 API 清單與自行執行
jdeps --jdk-internals結果一致
✅ 驗證方式
在分析主機執行:
jdeps -summary -cp "web/WEB-INF/lib/*" web/WEB-INF/classes jdeps --jdk-internals -cp "web/WEB-INF/lib/*" web/WEB-INF/classes grep -c "<action " web/WEB-INF/struts-config.xml預期輸出(示意):
classes -> java.base classes -> java.sql classes -> struts-1.3.10.jar classes -> commons-beanutils-1.8.0.jar ... classes -> JDK removed internal API com.acme.util.Base64Helper -> sun.misc.BASE64Encoder JDK internal API (JDK removed internal API) Warning: JDK internal APIs are unsupported and private to JDK implementation ... JDK Internal API Suggested Replacement ---------------- --------------------- sun.misc.BASE64Encoder Use java.util.Base64 @since 1.8 412判讀:Agent 報告中的內部 API 項目必須與此輸出一一對應;
412必須與 CSV 筆數相符。
24.3.2 PL/SQL 與資料層 Prompt
範例 Prompt
請粗掃 LOGI-ORD 的 M3(db/plsql/)。資料庫唯讀帳號已設定於環境變數 RE_DB_URL,
你只能執行 SELECT 查詢資料字典(USER_OBJECTS、USER_DEPENDENCIES、USER_TRIGGERS、USER_SOURCE),
不可執行任何 DML、DDL 或呼叫 Package。
【產出】
A. docs/re/M3-objects.csv:object_name, object_type, status, lines, depends_on, called_by_java(搜尋 web/ 與 ejb/)
B. docs/re/M3-survey.md:
- Trigger 清單與每個 Trigger 實際做的事(業務規則常藏在這裡)
- 動態 SQL(EXECUTE IMMEDIATE、DBMS_SQL)清單與 SQL Injection 風險評估
- 狀態為 INVALID 的物件
- Package 相依圖(Mermaid flowchart,節點文字用雙引號)
【自我檢查】
附上 SELECT object_type, COUNT(*) FROM user_objects GROUP BY object_type 的結果,與 CSV 分類計數對照。🧑⚖️ 人工 Review 要點
- 確認資料庫帳號真的只有唯讀權限(不要只相信 Prompt 中的「禁止」)
- Trigger 描述抽樣比對
USER_TRIGGERS.TRIGGER_BODY - 動態 SQL 有逐一列出字串拼接來源,風險等級有理由
- Mermaid 圖可正常渲染(貼到 Orca 的 Markdown 預覽確認)
✅ 驗證方式
以唯讀帳號執行:
SELECT object_type, COUNT(*) AS cnt FROM user_objects GROUP BY object_type ORDER BY object_type;預期輸出(示意):
OBJECT_TYPE CNT ------------- ---- FUNCTION 58 PACKAGE 240 PACKAGE BODY 238 PROCEDURE 91 TRIGGER 73 VIEW 112判讀:CSV 依
object_type分組計數必須相同;PACKAGE與PACKAGE BODY數量不同(240 對 238)代表有 2 個 Package 沒有 Body,報告應指出是哪兩個。
24.3.3 COBOL 批次 Prompt
範例 Prompt
請粗掃 M4(mainframe/),內容包含 COBOL 原始碼(*.cbl)、Copybook(*.cpy)與 JCL(*.jcl)。
【產出】
A. docs/re/M4-jobs.csv:job, step, program, input_dd, output_dd, cond, sourceRef
B. docs/re/M4-copybooks.md:每個 Copybook 的欄位表,含 PIC、USAGE(特別標示 COMP-3)、
REDEFINES、OCCURS,並換算為位元組長度
C. docs/re/M4-survey.md:夜間批次的執行順序圖(Mermaid flowchart)、
每支程式的輸入檔與輸出檔、失敗時是否可重跑(Restartable)
【規則】
- 不確定的位元組長度不可估計,標示「待確認」
- 執行順序必須依 JCL 中的 COND 與排程器匯出檔 scheduler/export.csv 推導,並註明依據🧑⚖️ 人工 Review 要點
- 由熟悉 COBOL 的資深人員抽查 3 個 Copybook 的位元組換算(COMP-3 長度最常出錯)
- 批次順序與排程器匯出檔一致,而非僅依檔名排序推測
- Restartable 判斷有依據(例如是否有 checkpoint 檔、輸出檔是否先刪後建)
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 程式數一致 | ls mainframe/*.cbl | wc -l 與 CSV 中 distinct program 比對 | 相同,或差異有說明(未被 JCL 引用的程式) | 要求 Agent 補上孤兒程式清單 |
| Copybook 引用完整 | grep -ohE "COPY [A-Z0-9-]+" mainframe/*.cbl | sort -u | wc -l | 與 Copybook 文件數一致 | 標記缺漏的 Copybook |
| 位元組長度正確 | 人工以 PIC S9(7)V99 COMP-3 等於 5 bytes 規則抽查 | 抽查全數正確 | 整份 Copybook 文件退回 |
24.3.4 深掘與特性測試 Prompt
粗掃只告訴我們「有什麼」,深掘要回答「它實際怎麼算」。最可靠的驗證方式是特性測試(Characterization Test,又稱 Golden Master):用現行系統的實際輸入與輸出建立測試,作為日後重寫時的行為基準。
範例 Prompt
請深掘業務流程「運費計算」(D1)。已知入口為 FreightAction(web/)→ FreightCalcBean(ejb/)
→ PKG_FREIGHT.CALC(db/plsql/)。
【產出】
1. docs/re/flows/freight.md:
- 時序圖(Mermaid sequenceDiagram)
- 規則表:條件、計算方式、來源(path:line),例如偏遠地區加成、重量級距、會員折扣、最低收費
- 邊界與例外:重量 0、負數、超過上限、地址代碼不存在
2. tests/characterization/FreightGoldenMasterTest.java:
- 讀取 tests/characterization/freight-samples.csv(由 DBA 從正式環境脫敏後提供的 500 筆實際輸入與結果)
- 對現行實作逐筆呼叫,斷言結果與 CSV 完全相同
3. 執行測試並貼出結果;若有不一致,不可修改 CSV 或程式,必須列出不一致的筆數與樣本並說明可能原因
【禁止】不可修改任何 web/、ejb/、db/ 的既有程式碼。🧑⚖️ 人工 Review 要點
- 規則表每一列都能在原始碼中找到對應,抽查比例至少 30%
- 特性測試確實讀取 CSV,沒有把期望值寫死在程式中
- 若有不一致筆數,原因分析合理(例如資料抽樣時的費率版本不同),而非「調整 CSV 讓測試通過」
- 樣本資料確實經過脫敏,沒有真實客戶姓名、電話
✅ 驗證方式
執行:
mvn -B -pl characterization test -Dtest=FreightGoldenMasterTest預期輸出(示意):
[INFO] Running com.acme.re.FreightGoldenMasterTest [INFO] Tests run: 500, Failures: 0, Errors: 0, Skipped: 0 [INFO] BUILD SUCCESS判讀:500 筆全數通過,才代表「規則表」描述的邏輯與實際行為一致,可作為後續重寫的驗收基準。
24.4 產出彙整與交接
統一報告範本
要求所有 Agent 依同一範本輸出,彙整時才能合併為一份系統現況文件。docs/re/TEMPLATE.md 的建議章節(範本內以二級標題呈現)如下:
| 章節 | 內容 | 必填要求 |
|---|---|---|
| 1 職責摘要 | 模組做什麼,3 句內 | 必填 |
| 2 進出點 | HTTP 路由、交易代碼、佇列、批次入口 | 每項附 path:line |
| 3 外部相依 | 函式庫、其他模組、外部系統 | 附工具輸出 |
| 4 資料存取 | 讀寫的資料表、檔案、交易邊界 | 每項附 path:line |
| 5 業務規則 | 條件與計算方式 | 每條附 path:line |
| 6 技術債與風險 | 等級高/中/低與理由 | 必填 |
| 7 待確認事項 | 問題、提問對象、狀態 | 不可為空 |
| 8 自我檢查證據 | 指令與完整輸出 | 必填 |
| 9 審查紀錄 | 審查者、日期、抽樣結果 | 由人工填寫 |
彙整流程
flowchart TD
R["各 Agent 模組報告"] --> C1["機械檢查 計數與格式"]
C1 -->|"不符"| BACK["Annotate AI Diff 退回"]
C1 -->|"通過"| C2["抽樣檢查 sourceRef 正確率"]
C2 -->|"低於 90%"| BACK
C2 -->|"達標"| C3["領域專家審閱 業務規則"]
C3 --> MERGE["合併為系統現況文件 v1.0"]
BACK --> R
MERGE --> HAND["交接會議與知識移轉"]如何閱讀此圖:每份報告必須依序通過三道檢查。第一道是機械檢查(計數一致、範本章節齊全),成本最低、最先做;第二道是抽樣驗證引用位置的正確率;第三道才請昂貴的領域專家閱讀業務規則。任一關不通過即以 Annotate AI Diff 批次留言退回原 Agent。
抽樣驗證腳本範例:隨機抽取 CSV 中的 sourceRef,自動開啟對應行供人工核對。
# 從 M1-routes.csv 隨機抽 20 筆 sourceRef,印出對應原始碼行
tail -n +2 docs/re/M1-routes.csv | shuf -n 20 | awk -F, '{print $NF}' | while IFS=: read -r f l; do
echo "== $f:$l"; sed -n "${l}p" "$f"
done✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 範本章節齊全 | grep -c "^## " docs/re/M*-survey.md | 每份 9 個 | 退回補齊 |
| 引用正確率 | 執行上方抽樣腳本,人工判斷 | 20 筆中至少 18 筆正確 | 整份退回重做 |
| 待確認事項有人追蹤 | 檢查第 7 節每項的狀態欄 | 皆有提問對象與狀態 | 交接前逐項指派 |
| 特性測試可重跑 | 交接對象在自己的環境執行 mvn test | 全數通過 | 補齊環境說明 |
交接要點
- 將報告與特性測試合併到主分支的
docs/re/與tests/characterization/,讓後續升級或重寫專案(第二十五章)直接引用。 - 以 Jira 或 Linear 建立「待確認事項」的追蹤票,並連結回對應 Worktree,避免問題隨著 Worktree 刪除而消失。
- 交接會議中由接手者(而非 Agent 或原審查者)現場執行一次特性測試與抽樣腳本,確認知識真正移轉。
- 分析用 Worktree 若不再需要,以 Resource Manager → Clean up workspaces 統一清理;若 git 因未合併提交保留分支,於 Review N Branches 中確認後再刪除。
❌ 常見錯誤
- 把 Agent 的「流暢摘要」當成事實,沒有要求
path:line來源。 - 對無文件模組期待單一 Agent 一次到位;應先粗掃確認範圍再深掘。
- 特性測試不一致時,讓 Agent「修正測試資料」使其通過,等於把現行系統的錯誤或資料差異掩蓋掉。
💡 小技巧:把 24.3 的技術棧總表與 Prompt 存為團隊 Skill 或 Prompt Library 條目(見第三十六章 36.13),下次遇到相同技術棧只需替換模組路徑。
24.5 本章 Review 與驗證清單
- 能說明為何逆向工程要分「粗掃」與「深掘」兩階段,以及兩階段的切分維度差異
- 已在 SSH 目標上建立分析用 Worktree,並確認 orca CLI 控制開關為關閉
- 已確認資料庫分析帳號在資料庫端為唯讀,而非只靠 Prompt 禁止
- 已實際執行
jdeps --jdk-internals並與 Agent 報告比對 - 已實際以計數方式驗證 CSV 筆數與原始設定一致
- 已以抽樣腳本驗證
sourceRef正確率達 90% 以上 - 已建立至少一組特性測試,且在現行系統上全數通過
- 所有待確認事項都已建立追蹤票並指派負責人
第二十五章 Framework Upgrade 框架升級
📌 查證狀態:教學示例(非官方),非真實客戶專案
框架升級的難處不在「改程式」,而在於「證明改完後行為沒變」。AI Agent 能大幅縮短機械式替換的時間,但也可能在沒人注意時改變語意(例如字元編碼、日期格式、交易邊界)。本章示範以 Orca 把升級切成可驗證的小步驟,每一步都有工具掃描、測試與人工審查三重證據;並以 Java 8 升級到 Java 25(LTS)搭配 Spring Boot 2.7 升級到 Spring Boot 4 為完整範例。
📌 查證狀態:依官方說明延伸(教學推論)|JDK 與 Spring 的變更事實請以 OpenJDK JEP 索引、Spring Boot Migration Guide 與 OpenRewrite 文件 為準;本章版本號與 Recipe 名稱撰寫時已盡力查證,執行前請以
mvn rewrite:discover列出實際可用 Recipe。
25.1 常見升級路徑
| 升級路徑 | 主要挑戰 | 建議中繼站 | 官方或主流自動化工具 |
|---|---|---|---|
| Java 8 → Java 25 | Java EE 模組移除、強封裝、Security Manager 停用、預設 UTF-8、GC 旗標變更 | 11 → 17 → 21 → 25 | OpenRewrite rewrite-migrate-java、jdeps、jdeprscan |
| Spring Boot 2.7 → 3.x | javax.* → jakarta.*、Spring Security 6 設定方式、Hibernate 6、屬性改名 | 先到 2.7 最新版清除棄用警告 | OpenRewrite rewrite-spring、spring-boot-properties-migrator |
| Spring Boot 3.x → 4.x | Spring Framework 7、Jakarta EE 11、Jackson 3、Hibernate 7、模組化 starter | 先到 3.5 清除棄用警告 | OpenRewrite rewrite-spring(以實際 Recipe 清單為準) |
| Hibernate 5 → 6/7 | HQL 解析更嚴格、ID 產生策略、型別對應 | 先升 5.6 並清除警告 | OpenRewrite Hibernate recipes |
| JUnit 4 → JUnit 5 以上 | Runner 與 Rule 改為 Extension、斷言 API | 可與 JDK 升級分開進行 | OpenRewrite JUnit4to5Migration |
| Vue 2 → Vue 3 | Options API 行為差異、全域 API、第三方元件 | @vue/compat 遷移建置 | Vue 官方 Migration Build |
| Angular 大版本 | 每次只能升一個主版本 | 逐版升級 | ng update |
| .NET Framework → .NET | 專案格式、System.Web 不支援、WCF | 先轉 SDK-style 專案 | .NET Upgrade Assistant |
升級的三個黃金原則
- 一次只變一件事:JDK 升級與框架升級分成不同步驟,出錯時才能定位原因。
- 先有安全網再動手:升級前測試覆蓋率不足時,先補特性測試(見第二十四章 24.3.4)。
- 自動化工具優先,AI 補位:能用 OpenRewrite 這類確定性工具完成的替換,不要讓 Agent 自由改寫;Agent 負責處理工具無法處理的部分,並解釋原因。
25.2 多 Agent 協同升級流程
角色分工
| 角色 | 職責 | 建議 Agent | 典型產出 |
|---|---|---|---|
| Scanner | 掃描相依、內部 API、棄用 API,產出風險清單 | Codex 或 Claude Code | docs/upgrade/scan-report.md |
| Recipe Runner | 執行 OpenRewrite 等確定性工具,整理產生的 patch | Codex | 單一 commit 的機械式變更 |
| Fixer | 處理工具無法自動處理的編譯錯誤與語意問題 | Claude Code | 小而聚焦的修正 commit |
| Verifier | 執行測試、比對升級前後行為、彙整證據 | 任一 Agent + 人工 | docs/upgrade/verification.md |
| Human Lead | 決策中繼版本、核准每一步、處理高風險項目 | 資深工程師 | 決策紀錄 |
以 Stacked Worktree 實現「一次一步」
Orca 的 Create Worktree 對話框中,Branch from 可以選另一個本機分支。利用這點,每一個升級步驟都從上一步的分支開出新 Worktree,形成可逐層審查、逐層回退的堆疊:
gitGraph
commit id: "main Java 8 SB 2.7"
branch step1-jdk11
commit id: "JDK 11 JAXB 依賴"
branch step2-jdk17
commit id: "JDK 17 add-opens 清理"
branch step3-sb3
commit id: "SB 3.5 jakarta"
branch step4-jdk21
commit id: "JDK 21"
branch step5-jdk25-sb4
commit id: "JDK 25 SB 4"如何閱讀此圖:每條分支代表一個升級步驟(圖中省略 upgrade/ 前綴,實際分支名為 upgrade/step1-jdk11 等),且都從前一步分支切出。審查者可以只看相鄰兩步之間的差異(例如 step2 到 step3 只有 Jakarta 遷移),若 step4 發現問題,只需回到 step3 的 Worktree 重新處理,而不影響已驗證過的前幾步。各步驟通過驗證後依序合併回 main,或在低風險專案中以一個 PR 堆疊(Stacked PR)呈現。
整體流程
flowchart TD
P["升級規劃 決定中繼版本"] --> S["Scanner 風險掃描"]
S --> D{"Human Lead 核准範圍"}
D --> R["Recipe Runner 執行 OpenRewrite"]
R --> F["Fixer 處理編譯與語意問題"]
F --> V["Verifier 測試與行為比對"]
V -->|"不通過"| F
V -->|"通過"| G{"Human Lead 步驟核准"}
G -->|"下一步"| S
G -->|"全部完成"| REL["分批上線與觀察"]如何閱讀此圖:這是一個以「步驟」為單位的迴圈。每一個中繼版本都走一次 掃描 → 核准 → 自動替換 → 人工/AI 修正 → 驗證 → 核准,驗證不過就回到 Fixer;全部步驟完成才進入上線。
遠端建置主機:大型 Maven 專案在筆電上跑完整測試可能超過 30 分鐘,且多個 Worktree 同時建置會耗盡記憶體。建議把 Verifier 的 Worktree 建在 SSH 目標(例如具 32 核心的建置主機),Agent 與 mvn verify 都在遠端執行,本機只負責審查 Diff。
夜間回歸(Scheduled Automations):升級期間每晚自動在升級分支上跑完整回歸並摘要結果,先以 --disabled 建立,確認無誤再啟用:
orca automations create \
--name "JDK25 升級夜間回歸" \
--trigger "0 1 * * 1-5" \
--timezone Asia/Taipei \
--precheck 'git -C /srv/order-svc fetch -q && git -C /srv/order-svc diff --quiet HEAD origin/upgrade/step5-jdk25-sb4 && exit 1 || exit 0' \
--prompt "在 upgrade/step5-jdk25-sb4 執行 mvn -B verify,摘要失敗測試與新出現的警告,不要修改任何程式碼" \
--provider codex \
--workspace "branch:upgrade/step5-jdk25-sb4" \
--disabled \
--json📌 查證狀態:依官方說明延伸(教學推論)|來源:Scheduled automations。
--precheck以非零 exit 代表略過本次執行;上例在「分支無新提交」時略過,以節省用量。Workspace selector 寫法請以orca automations create --help為準。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 堆疊分支正確 | git log --oneline --graph --all -- pom.xml | head -20 | 各 step 分支依序疊在前一步之上 | 重新以正確的 Branch from 建立 Worktree |
| 自動化已建立但未啟用 | orca automations list --json | 該筆 enabled 為 false | 檢查建立指令是否帶 --disabled |
| 手動試跑成功 | orca automations run <id> --json,再以 orca automations runs --id <id> --json 查看結果 | 產生摘要且無程式碼變更 | 調整 Prompt 中的禁止事項 |
25.3 Java 8 升級至 Java 25 範例分工
案例情境:訂單服務「order-svc」,約 18 萬行 Java,Maven 多模組,目前為 Java 8、Spring Boot 2.7、Hibernate 5.6、JUnit 4 與 5 混用、Lombok、部署於 Tomcat 內嵌容器的 Docker 映像。目標為 Java 25(LTS)與 Spring Boot 4。
25.3.1 Java 8 到 25 的主要相容性議題
| 議題 | 引入版本 | 影響 | 偵測方式 | 處理方式 |
|---|---|---|---|---|
Java EE 與 CORBA 模組移除(JAXB、JAX-WS、javax.activation、javax.annotation) | JDK 11(JEP 320) | ClassNotFoundException: javax.xml.bind.JAXBContext | jdeps、編譯錯誤 | 加入 Jakarta 對應依賴,或隨 Spring Boot 3 改為 jakarta.* |
javax.* → jakarta.* 命名空間 | Jakarta EE 9(Spring Boot 3 起採用) | Servlet、JPA、Validation 的 import 全面變更 | 編譯錯誤 | OpenRewrite Jakarta Recipe |
| Nashorn JavaScript 引擎移除 | JDK 15(JEP 372) | ScriptEngineManager 取得 null | 搜尋 getEngineByName("nashorn") | 改用獨立 Nashorn 或 GraalJS,或移除該用途 |
| JDK 內部 API 強封裝 | JDK 16(JEP 396)、JDK 17(JEP 403) | InaccessibleObjectException;--illegal-access 不再有效 | jdeps --jdk-internals、執行期例外 | 改用公開 API;不得已時加最小範圍的 --add-opens 並記錄 |
sun.misc.BASE64Encoder 等內部類別 | 早已不建議,新版不存在 | 編譯錯誤 | jdeps --jdk-internals | 改用 java.util.Base64 |
| Security Manager 永久停用 | JDK 17 棄用(JEP 411)、JDK 24 停用(JEP 486) | System.setSecurityManager 拋出 UnsupportedOperationException;啟動參數 -Djava.security.manager 會導致錯誤 | 搜尋 SecurityManager、AccessController、啟動腳本 | 移除相關程式碼;以容器、OS 權限與網路政策取代沙箱需求 |
sun.misc.Unsafe 記憶體存取方法 | JDK 23 棄用待移除(JEP 471)、JDK 24 起使用時警告(JEP 498) | 舊版 Netty、序列化函式庫等出現警告 | 啟動 log 中的 WARNING | 升級第三方函式庫至使用 VarHandle 或 FFM API 的版本 |
| 預設字元集改為 UTF-8 | JDK 18(JEP 400) | 未指定編碼讀寫檔案時,Windows 上原本是 MS950(Big5)的行為改變,造成中文亂碼 | 搜尋 new FileReader(、getBytes()、new String(bytes) 未帶 charset | 明確指定 StandardCharsets 或 Charset.forName("MS950") |
| 預設 Locale 資料改為 CLDR | JDK 9(JEP 252);JDK 23 起移除 COMPAT 選項 | 日期、數字格式輸出改變(例:中文上午下午、星期縮寫) | 比對報表、格式化輸出的特性測試 | 以明確 Pattern 格式化;更新期望值前需業務確認 |
| Finalization 棄用待移除 | JDK 18(JEP 421) | finalize() 未來將不再被呼叫 | jdeprscan --for-removal | 改用 try-with-resources 或 Cleaner |
Thread.stop 等危險方法 | JDK 20 起拋出 UnsupportedOperationException | 執行期失敗 | jdeprscan | 改為協作式中斷 |
| GC 與 JVM 旗標 | CMS 移除(JDK 14,JEP 363)、PermGen 相關旗標失效、GC log 改為 -Xlog | 啟動警告或無法啟動 | 檢查 Dockerfile、啟動腳本中的 -XX: 旗標 | 改用 G1 或 ZGC;以 -Xlog:gc* 取代 -XX:+PrintGCDetails |
| Annotation Processing 預設行為 | JDK 23 起 javac 不再隱式執行 classpath 上的 Processor | Lombok、MapStruct 未生效導致大量編譯錯誤 | 編譯錯誤如 cannot find symbol getXxx() | 在 maven-compiler-plugin 明確設定 annotationProcessorPaths |
| JNI 使用警告 | JDK 24(JEP 472) | 使用 native 函式庫時出現警告 | 啟動 log | 以 --enable-native-access 明確授權 |
| 32 位元 x86 移植移除 | JDK 25(JEP 503) | 舊 32 位元環境無法使用 | 盤點執行環境 | 改為 64 位元映像檔 |
| 第三方工具支援 class file 版本 | Java 25 對應 class file major version 69 | 舊版 JaCoCo、Mockito、Byte Buddy、ASM 無法處理 | 測試期例外 Unsupported class file major version 69 | 升級至官方宣告支援 Java 25 的版本 |
💡 小技巧:台灣企業最常被忽略的是 JEP 400 預設 UTF-8。許多舊系統在 Windows 伺服器上讀寫 Big5 檔案(例如銀行對帳檔、政府機關交換檔)都沒有指定編碼,在 Java 8 依賴系統預設 MS950 而「剛好正確」,升級後會靜默變成亂碼。請把「所有 I/O 都明確指定 charset」列為必審項目。
25.3.2 任務拆解
| 任務 | Agent | Worktree 分支 | 交付物 | 驗收條件 |
|---|---|---|---|---|
| U0 基線建立 | Codex | upgrade/step0-baseline | 補齊特性測試、記錄 Java 8 下的測試數、效能基線、API 回應快照 | mvn verify 全綠;基線報告含測試數、P95、記憶體用量 |
| U1 風險掃描 | Claude Code | upgrade/step0-scan | docs/upgrade/scan-report.md(jdeps、jdeprscan、相依版本矩陣、啟動參數清單) | 每項風險附來源與建議處理;工具輸出完整附錄 |
| U2 JDK 11 與 17 | Codex | upgrade/step1-jdk11、upgrade/step2-jdk17 | OpenRewrite UpgradeToJava17 結果、JAXB 依賴、--add-opens 清單 | jdeps --jdk-internals 無輸出;測試數與基線相同 |
| U3 Spring Boot 3.5 | Codex(Recipe)+ Claude Code(Fixer) | upgrade/step3-sb3 | Jakarta 遷移、Security 6 設定、屬性改名、Hibernate 6 HQL 修正 | spring-boot-properties-migrator 無警告;契約測試通過 |
| U4 JDK 21 與 25、Spring Boot 4 | Claude Code | upgrade/step4-jdk21、upgrade/step5-jdk25-sb4 | Toolchain、Dockerfile、CI matrix、Spring Boot 4 遷移、Jackson 3 相容修正 | 在 JDK 25 下 mvn verify 全綠;無 Unsupported class file 例外 |
| U5 語意與行為驗證 | Codex + 人工 | upgrade/verify | 新舊版本雙跑比對報告、效能比較、字元集與 Locale 檢查 | API 快照差異為 0 或逐項核准;P95 不劣於基線 10% |
25.3.3 OpenRewrite Recipe 範例
單一 Recipe 試跑(不修改檔案,只產生 patch)
mvn -U org.openrewrite.maven:rewrite-maven-plugin:dryRun \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE \
-Drewrite.activeRecipes=org.openrewrite.java.migrate.UpgradeToJava17預期輸出(示意):
[WARNING] These recipes would make changes to order-core/src/main/java/com/acme/order/util/Base64Helper.java:
[WARNING] org.openrewrite.java.migrate.UpgradeToJava17
[WARNING] org.openrewrite.java.migrate.Java8toJava11
[WARNING] org.openrewrite.java.migrate.UseJavaUtilBase64
...
[WARNING] Patch file available:
[WARNING] /work/order-svc/target/rewrite/rewrite.patch組合式 Recipe(rewrite.yml,放在 repo 根目錄)
---
type: specs.openrewrite.org/v1beta/recipe
name: com.acme.upgrade.Step3SpringBoot3
displayName: order-svc 第三步 升級至 Spring Boot 3.5 與 Jakarta
recipeList:
- org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_5
- org.openrewrite.java.testing.junit5.JUnit4to5Migration
- org.openrewrite.java.migrate.UseJavaUtilBase64
- org.openrewrite.java.ChangePackage:
oldPackageName: com.acme.legacy.security
newPackageName: com.acme.order.security
recursive: true<!-- pom.xml 片段:以 plugin 方式固定 Recipe 版本,避免 RELEASE 漂移 -->
<plugin>
<groupId>org.openrewrite.maven</groupId>
<artifactId>rewrite-maven-plugin</artifactId>
<version>${rewrite-maven-plugin.version}</version>
<configuration>
<activeRecipes>
<recipe>com.acme.upgrade.Step3SpringBoot3</recipe>
</activeRecipes>
<exportDatatables>true</exportDatatables>
</configuration>
<dependencies>
<dependency>
<groupId>org.openrewrite.recipe</groupId>
<artifactId>rewrite-spring</artifactId>
<version>${rewrite-spring.version}</version>
</dependency>
<dependency>
<groupId>org.openrewrite.recipe</groupId>
<artifactId>rewrite-testing-frameworks</artifactId>
<version>${rewrite-testing-frameworks.version}</version>
</dependency>
</dependencies>
</plugin>⚠️ 注意事項:
- 正式升級時,請將 Recipe 套件版本固定於
pom.xml的 properties,RELEASE只適合探索;否則兩次執行可能得到不同結果,無法重現。 - JDK 25 與 Spring Boot 4 的 Recipe(例如
UpgradeToJava25、spring.boot4系列)是否已收錄於你使用的版本,請先執行mvn rewrite:discover確認;若不存在,該部分改由 Fixer Agent 依官方 Migration Guide 手動處理,並在報告中註明。 - OpenRewrite 產生的變更必須獨立成一個 commit,Fixer 的手動修正另成 commit,審查者才能分辨「確定性工具改的」與「AI 改的」。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Recipe 存在 | mvn rewrite:discover | grep -i UpgradeToJava | 列出 UpgradeToJava17、UpgradeToJava21 等 | 升級 rewrite-migrate-java 版本或改走手動 |
| Patch 可審查 | 檢視 target/rewrite/rewrite.patch | 變更符合預期 Recipe 描述 | 調整 rewrite.yml 移除不需要的子 Recipe |
| Recipe 變更獨立 commit | git log --oneline -3 | 有一個 chore(upgrade): apply OpenRewrite ... commit | 以 git reset 拆分後重新提交 |
25.3.4 分派 Prompt 範例
範例 Prompt:U1 風險掃描
請在目前 Worktree(upgrade/step0-scan)對 order-svc 進行 Java 8 → Java 25 升級風險掃描。
這是唯讀任務,不可修改 src/ 與 pom.xml。
【必須執行並附上完整輸出】
1. mvn -B -q dependency:copy-dependencies -DoutputDirectory=target/lib
2. jdeps --multi-release 25 --jdk-internals -cp "target/lib/*" order-*/target/*.jar
3. jdeprscan --release 25 --for-removal --class-path "target/lib/*" order-*/target/*.jar
4. mvn -B versions:display-dependency-updates
5. 搜尋下列樣式並列出 path:line:
- SecurityManager、AccessController、doPrivileged
- getEngineByName("nashorn")、javax.script
- new FileReader(、new FileWriter(、getBytes()、new String((未指定 charset)
- finalize()
- Dockerfile 與 bin/*.sh 中的 -XX: 與 -D 啟動參數
【產出 docs/upgrade/scan-report.md】
- 依 25.3.1 的議題分類,每項列出:位置、影響、建議處理、需要人工決策與否
- 第三方函式庫相容矩陣:目前版本、支援 Java 25 的最低版本、資料來源(官方 release notes 連結)
- 無法確認支援狀況的函式庫標示「待確認」,不可推測
完成後以 orca worktree set 回報「掃描完成:高風險 N 項、中風險 M 項、待確認 K 項」。🧑⚖️ 人工 Review 要點
- 報告附錄的
jdeps、jdeprscan輸出是完整原始輸出,不是 Agent 改寫過的摘要 - 自行重跑
jdeps --jdk-internals,確認項目數與報告一致 - 第三方相容矩陣每一列都有可點擊的官方來源;隨機點開 3 個核對
- 字元集風險清單沒有遺漏(自行執行
git grep -n "new FileReader("比對) - 「需要人工決策」的項目(例如 Security Manager 的替代方案)已列入決策會議
範例 Prompt:U4 Fixer(JDK 25 與 Spring Boot 4)
你是升級 Fixer。目前 Worktree 為 upgrade/step5-jdk25-sb4,從 upgrade/step4-jdk21 切出,
已由 Recipe Runner 套用 OpenRewrite(見最近一個 chore(upgrade) commit)。
【目標】在 JDK 25 下讓 mvn -B verify 全數通過,且不改變業務行為。
【規則】
1. 每一類修正獨立一個 commit,訊息格式:fix(upgrade): <議題> <簡述>
2. 不可刪除、停用或 @Disabled 任何測試;不可降低 JaCoCo 門檻
3. 不可新增 --add-opens,除非附上:哪個函式庫需要、為何無法升級、Issue 連結;並在 docs/upgrade/add-opens.md 記錄
4. 所有檔案 I/O 必須明確指定 charset;與外部交換的 Big5 檔案使用 Charset.forName("MS950")
5. 不可修改 src/test/resources/snapshots/ 中的 API 回應快照
6. 遇到需要改變對外行為才能修正的情況(例如 Jackson 3 預設序列化差異),停止並用 orca orchestration ask 詢問
【完成條件】
- 執行 java -version 確認為 25
- mvn -B verify 的 Tests run 總數必須等於基線報告的數字(docs/upgrade/baseline.md)
- 貼出啟動應用後前 200 行 log 中所有 WARNING🧑⚖️ 人工 Review 要點
-
git log --oneline upgrade/step4-jdk21..HEAD顯示多個小 commit,每個只處理一類問題 -
git diff upgrade/step4-jdk21 -- "**/src/test/**"中沒有刪除斷言、沒有新增@Disabled - 以 Attribution 檢視 Fixer 修改的行,特別審查交易、序列化、時區、字元集相關程式碼
-
add-opens.md每一項都有理由與追蹤 Issue - 啟動 log 的 WARNING 都已分類(可接受、待升級函式庫、需修正)
- Tests run 總數與基線相同;若減少,必須逐一說明原因
25.4 升級驗證策略
升級驗證採「七道關卡」,由便宜到昂貴依序執行;前一道沒過,不進入下一道。
| 關卡 | 驗證內容 | 指令或方法 | 通過條件 |
|---|---|---|---|
| G1 編譯 | 新 JDK 下可編譯、無新增警告 | mvn -B -Dmaven.compiler.showWarnings=true compile | 0 error;警告數不高於基線 |
| G2 靜態掃描 | 無內部 API、無待移除 API | jdeps --jdk-internals、jdeprscan --for-removal | 無輸出或僅剩已核准項目 |
| G3 單元與整合測試 | 測試數量與結果 | mvn -B verify | Tests run 等於基線;0 failure |
| G4 契約與快照 | 對外 API 行為一致 | 快照比對、oasdiff breaking | 0 差異或逐項核准 |
| G5 雙跑比對 | 相同請求打新舊版本比對回應 | 回放腳本 + jq -S 正規化後 diff | 差異為 0 或逐項核准 |
| G6 效能與資源 | P95、吞吐量、記憶體、GC 暫停 | k6 或 Gatling、JFR | P95 不劣於基線 10% |
| G7 營運相容 | 啟動參數、映像檔、監控、log 格式 | 在預備環境部署並觀察 24 小時 | 無新增錯誤告警 |
G1 與 G2 驗證範例
java -version
mvn -B -q verify -DskipTests
jdeps --multi-release 25 --jdk-internals -cp "target/lib/*" order-*/target/*.jar
jdeprscan --release 25 --for-removal --class-path "target/lib/*" order-*/target/*.jar✅ 驗證方式
執行上述指令。
預期輸出(示意):
openjdk version "25.0.1" 2025-10-21 LTS OpenJDK Runtime Environment (build 25.0.1+8-LTS)jdeps --jdk-internals與jdeprscan --for-removal應無任何輸出。判讀:若
jdeprscan輸出uses deprecated method java/lang/Object::finalize()V (forRemoval=true)之類訊息,代表仍有待移除 API,回到 Fixer 處理。
G3 測試數量守恆檢查
AI Fixer 最危險的「捷徑」是刪除或停用失敗的測試。以下腳本比較基線與升級後的測試數:
base=$(grep -h "<testsuite" baseline-reports/*.xml | sed -E 's/.*tests="([0-9]+)".*/\1/' | paste -sd+ | bc)
curr=$(grep -h "<testsuite" order-*/target/surefire-reports/*.xml | sed -E 's/.*tests="([0-9]+)".*/\1/' | paste -sd+ | bc)
echo "baseline=$base current=$curr"
git diff --stat upgrade/step0-baseline -- "**/src/test/**" | tail -1
git grep -n "@Disabled\|@Ignore" -- "**/src/test/**" | wc -l預期輸出(示意):
baseline=2318 current=2318
41 files changed, 312 insertions(+), 298 deletions(-)
3判讀:baseline 與 current 必須相等;@Disabled 數量必須與基線相同(本例基線即有 3 個既有停用測試)。測試檔有變更是正常的(JUnit 4 → 5 遷移),但需人工抽查是否有斷言被刪除。
G5 雙跑比對(Shadow Comparison)
- 在預備環境同時部署 Java 8 版(
order-svc:legacy)與 Java 25 版(order-svc:next),連接同一份唯讀測試資料庫快照。 - 以 U0 錄製的 2,000 筆真實請求(已脫敏)回放到兩個版本。
- 對每一組回應以
jq -S排序鍵值並移除時間戳等非決定性欄位後比對。
while read -r path; do
curl -s "http://legacy:8080$path" | jq -S 'del(.meta.generatedAt)' > out/legacy.json
curl -s "http://next:8080$path" | jq -S 'del(.meta.generatedAt)' > out/next.json
diff -q out/legacy.json out/next.json > /dev/null || echo "DIFF $path"
done < replay/paths.txt | tee out/diff-report.txt
wc -l out/diff-report.txt預期輸出(示意):
0 out/diff-report.txt判讀:任何 DIFF 行都必須逐一調查。常見原因與處理:
| 差異類型 | 常見根因 | 處理 |
|---|---|---|
| 日期字串格式不同 | CLDR Locale 資料或 Jackson 3 預設設定 | 明確設定格式;由業務確認是否可接受 |
| 小數位數或科學記號 | BigDecimal 序列化設定 | 設定序列化選項保持原格式 |
| 中文亂碼 | 預設字元集變為 UTF-8 | 明確指定 charset |
| 欄位順序不同 | 已以 jq -S 排除,若仍有差異檢查陣列排序 | 檢查查詢是否缺少 ORDER BY |
| null 欄位出現或消失 | 序列化 inclusion 預設值改變 | 對齊原有設定 |
G6 效能比較
java -XX:StartFlightRecording=duration=300s,filename=next.jfr -Xlog:gc*:file=gc.log -jar order-app.jar &
k6 run --summary-export=perf-next.json perf/order-load.js
jq '.metrics.http_req_duration["p(95)"]' perf-baseline.json perf-next.json預期輸出(示意):
412.6
365.2判讀:第二個數字(Java 25)不高於第一個數字(Java 8 基線)的 110% 即通過。若變慢,先以 JFR 檢查 GC 暫停與鎖競爭,並確認容器記憶體限制下 JVM 是否正確偵測可用記憶體。
回退計畫:每一步驟的映像檔都保留並標記版本;上線採金絲雀(Canary)先導 5% 流量,觀察錯誤率與 P95 一個營業日,再逐步擴大。回退只需把流量切回 order-svc:legacy,因此升級期間不得同時進行資料庫 schema 的不相容變更。
❌ 常見錯誤
- 一次從 Java 8 跳到 Java 25 並同時升 Spring Boot 4,出錯時無法判斷是哪一層造成。
- 只看「編譯通過」或「測試全綠」,沒有檢查測試數量是否減少。
- 忽略內部共用函式庫(公司自己的 common-lib),主專案升級完才發現共用庫仍以 Java 8 編譯並使用已移除的 API。
- 把
--add-opens java.base/java.lang=ALL-UNNAMED當萬用解藥,等於把強封裝的保護全部關掉。
25.5 本章 Review 與驗證清單
- 能列出 Java 8 到 25 之間至少 8 項相容性議題,並說明各自的偵測方式
- 能說明 Security Manager 在 JDK 24 被永久停用後,原有沙箱需求應如何以其他機制取代
- 已用 Stacked Worktree 建立至少兩個相鄰升級步驟,並只審查相鄰步驟間的差異
- 已實際執行 OpenRewrite
dryRun並審閱rewrite.patch - 已確認 OpenRewrite 變更與 AI Fixer 變更分屬不同 commit
- 已實際執行
jdeps --jdk-internals與jdeprscan --for-removal且無未核准項目 - 已驗證升級後測試總數與基線相同,且
@Disabled數量未增加 - 已完成雙跑比對,差異報告為 0 或每項皆有核准紀錄
- 已比較 P95 與基線,並備妥回退計畫
第二十六章 銀行核心系統案例
📌 查證狀態:教學示例(非官方),非真實客戶專案
銀行核心系統是 AI 輔助開發風險最高的場域之一:一個錯誤的規則可能造成誤放款、一筆格式錯誤的報文可能讓跨行清算失敗、一行洩漏個資的 log 可能構成違規。本章的重點不是「讓 AI 寫核心交易」,而是示範:在既有金融內控框架(Maker-Checker、稽核軌跡、職務分工、資料遮罩)不打折的前提下,如何用 Orca 讓 AI 參與開發,並留下可供內稽、外稽與監理機關檢視的證據。
📌 查證狀態:依官方說明延伸(教學推論)|本章提及的法規與指引(例如金管會發布之金融業運用人工智慧相關指引、個人資料保護法、資通安全相關規範)僅作為治理設計的參考方向,條文內容與適用範圍請以主管機關最新公告及貴行法遵單位解釋為準。
26.1 案例背景
情境:某銀行要優化「企業授信申請與核准」子系統,並新增跨境匯款的 ISO 20022 報文轉換層。範圍如下:
| 子系統 | 現況 | 本期目標 |
|---|---|---|
| 信用查詢 | 櫃台人員直接查詢主機,無遮罩 | 微服務化查詢 API,依角色遮罩,查詢全程留痕 |
| 授信申請與核准 | 紙本簽核後由人工鍵入主機 | 線上 Maker-Checker 流程,依金額分級核准 |
| 授信規則 | 規則散落於 COBOL 程式與 Excel | 結構化為規則引擎(決策表),變更需雙人覆核 |
| 稽核紀錄 | 分散於各系統 log,可被 DBA 修改 | 集中、只增不改、可驗證完整性的稽核軌跡 |
| 跨境匯款 | 內部格式轉 SWIFT MT103 | 增加 ISO 20022 pacs.008 轉換(配合 CBPR+ 遷移) |
| 夜間批次 | 授信額度重算與報表 | 可重跑、具冪等性 |
內控目標(Control Objectives)
| 編號 | 控制目標 | 本案落實方式 |
|---|---|---|
| CO-1 | 職務分工(SoD) | 申請人(Maker)不得核准自己的案件;系統與資料庫雙層限制 |
| CO-2 | 雙人覆核 | 授信核准、規則變更、額度調整一律 Maker-Checker |
| CO-3 | 稽核軌跡完整 | 所有寫入動作產生稽核事件;以雜湊鏈驗證未被竄改 |
| CO-4 | 個資最小揭露 | 依角色遮罩;log、例外訊息、快取不得含明碼 |
| CO-5 | 變更管理 | 程式變更須有需求單、雙人 Code Review、測試證據、CAB 核准 |
| CO-6 | AI 使用治理 | AI 產出須標示、須人工覆核、AI 不得擔任 Checker |
開發環境限制與 Orca 配置
| 項目 | 配置 | 理由 |
|---|---|---|
| 開發端 | 行內 VDI 安裝 Orca,僅能連線行內 Git 與 Jira | 原始碼不落地個人裝置 |
| 執行位置 | Agent 透過 SSH Worktrees 在行內開發主機 devbox-01~devbox-04 執行 | 集中監控與資源控管 |
| Agent 白名單 | 僅允許資安核准的 Agent CLI 與企業合約模型端點 | 避免原始碼送往未核准服務 |
| 權限模式 | Agent 採需人工確認的權限模式,不使用略過確認的模式(見第七章 7.2) | 防止 Agent 自行執行破壞性指令 |
| 遠端 CLI 控制 | Allow this host's orca CLI to control Orca 一律關閉 | 遠端 Agent 不得橫向操作其他主機 |
| 測試資料 | 僅使用合成資料或經核准的去識別化資料 | 個資法與內規要求 |
| Mobile Companion | 不配對 | 避免行外裝置存取開發工作階段 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Agent 在行內主機執行 | 在 Agent 終端機執行 hostname 與 ip -4 addr | 為 devbox-0x,IP 屬行內網段 | 重建 Worktree 並選擇正確 Run on |
| 無外部 Git 遠端 | git remote -v | 僅行內 Git 伺服器 | 移除並通報資安 |
| 測試資料無真實個資 | 以 DLP 工具或正規表示式掃描 src/test/resources | 無符合身分證、真實帳號格式的資料 | 立即刪除並通報 |
| 遠端 CLI 控制關閉 | Settings → SSH → 各主機 Advanced Connection | 開關皆為關閉 | 關閉並記錄變更 |
26.2 任務拆解
flowchart TD
CR["變更需求單 CR-2026-118"] --> C1["B1 Maker-Checker 核准框架"]
CR --> C2["B2 稽核軌跡服務"]
CR --> C3["B3 資料遮罩函式庫"]
C1 --> B4["B4 授信申請與核准 API"]
C2 --> B4
C3 --> B4
C3 --> B5["B5 信用查詢 API"]
C2 --> B5
C1 --> B6["B6 授信規則決策表"]
CR --> B7["B7 ISO 20022 pacs.008 轉換"]
CR --> B8["B8 額度重算批次"]
B4 --> SIT["SIT 系統整合測試"]
B5 --> SIT
B6 --> SIT
B7 --> SIT
B8 --> SIT
SIT --> PAR["新舊雙軌比對"]
PAR --> UAT["UAT 與 CAB"]如何閱讀此圖:B1~B3 是「控制元件」,必須先完成並經資安與內控覆核,業務功能 B4~B6 才能建立在其上;這樣可以確保所有業務功能都使用同一套經過審查的 Maker-Checker、稽核與遮罩實作,而不是每個 Agent 各寫一套。B7、B8 與控制元件無直接相依,可平行進行。所有任務在 SIT 會合,接著進行新舊系統雙軌比對,最後才進入 UAT 與變更諮詢委員會(CAB)。
任務拆解表
| 任務 | Agent | Worktree 分支 | 交付物 | 驗收條件 | 風險等級 |
|---|---|---|---|---|---|
| B1 Maker-Checker 框架 | Claude Code | feature/CR118-B1-maker-checker | 核准狀態機、approval_request 表、權限檢查 | 自我核准在 API 與 DB 兩層皆被拒絕;狀態轉換測試 100% 覆蓋 | 高 |
| B2 稽核軌跡 | Codex | feature/CR118-B2-audit-trail | 稽核事件寫入、雜湊鏈、驗證工具 | 竄改任一筆即可被驗證工具偵測;應用帳號無 UPDATE、DELETE 權限 | 高 |
| B3 資料遮罩 | Claude Code | feature/CR118-B3-masking | 遮罩函式庫、Log 遮罩 Layout、單元測試 | 遮罩規則表 100% 對應測試;log 掃描無明碼 | 高 |
| B4 授信申請與核准 | Codex | feature/CR118-B4-credit-approval | 申請、分級核准 API | 依金額路由至正確核准層級;所有寫入產生稽核事件 | 高 |
| B5 信用查詢 | Codex | feature/CR118-B5-credit-inquiry | 查詢 API、快取 | 遮罩依角色正確;查詢留痕 | 中 |
| B6 授信規則決策表 | Claude Code | feature/CR118-B6-rules | 決策表、規則測試、新舊對照表 | 歷史案例回放結果與現行系統一致 | 高 |
| B7 ISO 20022 轉換 | Claude Code | feature/CR118-B7-iso20022 | 內部格式 ↔ pacs.008 轉換器 | 產出報文通過 XSD 驗證;欄位對應表經作業部門確認 | 高 |
| B8 額度重算批次 | Codex | feature/CR118-B8-batch | Spring Batch Job | 重跑兩次結果一致(冪等);中斷後可續跑 | 中 |
建立 Worktree:每個任務在 Jira 中都是 CR-2026-118 底下的子任務。從 Tasks → Jira 開啟子任務並建立 Worktree,Run on 選擇行內 devbox,讓 Worktree 與 Jira 互相連結,稽核時可從需求單追到分支與 PR。
26.3 各任務分派重點
26.3.1 Maker-Checker 核准框架
狀態設計
stateDiagram-v2
[*] --> DRAFT
DRAFT --> SUBMITTED : Maker 送出
SUBMITTED --> APPROVED : Checker 核准
SUBMITTED --> REJECTED : Checker 退回
SUBMITTED --> DRAFT : Maker 撤回
REJECTED --> DRAFT : Maker 修改
APPROVED --> EXECUTED : 系統執行
EXECUTED --> [*]如何閱讀此圖:每一個需要覆核的動作(授信核准、規則變更、額度調整)都以「核准請求」表示,從 DRAFT 開始。Maker 只能送出、撤回、修改;只有不同於 Maker 的 Checker 能把 SUBMITTED 轉為 APPROVED 或 REJECTED;APPROVED 之後由系統執行實際變更。圖中沒有任何從 DRAFT 直接到 APPROVED 的路徑,這就是 Maker-Checker 的核心保證。
範例 Prompt
你正在實作銀行授信系統的 Maker-Checker 框架(Jira CR-2026-118-B1)。這是高風險內控元件。
【範圍】只可修改 approval/ 模組與 db/migration/V20__approval_request.sql。
【資料模型】
approval_request(id, action_type, payload jsonb, amount numeric(18,2), status, maker_id, checker_id,
submitted_at, decided_at, decision_reason, version)
- 資料庫層:CHECK (checker_id IS NULL OR checker_id <> maker_id)
- status 僅允許 DRAFT、SUBMITTED、APPROVED、REJECTED、EXECUTED
【狀態機規則】
- 合法轉換:DRAFT→SUBMITTED、SUBMITTED→APPROVED、SUBMITTED→REJECTED、SUBMITTED→DRAFT、
REJECTED→DRAFT、APPROVED→EXECUTED;其他一律拋出 IllegalStateTransitionException
- 核准者必須具備對應金額層級的角色:
amount <= 5,000,000 → CREDIT_OFFICER;<= 50,000,000 → CREDIT_MANAGER;以上 → CREDIT_COMMITTEE
- 同一使用者不得同時為 Maker 與 Checker(應用層檢查 + DB CHECK 雙層)
- 使用樂觀鎖(version)防止兩位 Checker 同時核准
- 每次狀態轉換呼叫 AuditTrail.append()(介面由 B2 提供,先以 interface 依賴)
【測試(必須全部實作並執行)】
1. 狀態轉換矩陣:所有 5×5 組合,合法者成功、不合法者拋例外
2. 自我核准:API 回 403;直接以 JDBC 更新觸發 DB CHECK violation
3. 金額層級:邊界值 5,000,000、5,000,000.01、50,000,000、50,000,000.01
4. 併發:兩個執行緒同時核准,只有一個成功,另一個拋 OptimisticLockException
5. 每次轉換恰好產生一筆稽核事件
【禁止】
- 不可提供任何繞過 Checker 的「管理員直接核准」路徑
- 不可在程式碼中寫死任何使用者 ID 作為例外
完成後貼出 mvn -B -pl approval verify 的輸出,並以 orca worktree set 更新狀態。🧑⚖️ 人工 Review 要點
- 搜尋
approve、status =、setStatus(的所有呼叫點,確認沒有繞過狀態機直接改狀態的路徑 - DB 層 CHECK constraint 確實存在於 migration,而非只在 Java 中檢查
- 金額比較使用
BigDecimal.compareTo,不是double或equals - 狀態轉換矩陣測試確實列舉 25 種組合(看測試參數來源,而非只看通過數)
- 以 Attribution 標示的 AI 產出行,由非 Prompt 撰寫者的第二位工程師逐行覆核(CO-6)
✅ 驗證方式
執行:
mvn -B -pl approval verify psql "$DEV_DB_URL" -c "UPDATE approval_request SET status='APPROVED', checker_id=maker_id WHERE id=1;"預期輸出(示意):
[INFO] Tests run: 47, Failures: 0, Errors: 0, Skipped: 0 [INFO] BUILD SUCCESS ERROR: new row for relation "approval_request" violates check constraint "ck_maker_ne_checker"判讀:第二個指令必須失敗。若 UPDATE 成功,代表 DB 層防線不存在,任何能直連資料庫的人都能自我核准,不可合併。
26.3.2 稽核軌跡
設計要點:稽核事件表只允許新增;每筆事件包含前一筆的雜湊值,形成雜湊鏈。任何人(包含 DBA)修改或刪除中間任一筆,驗證工具都能偵測。
範例 Prompt
請實作稽核軌跡服務(CR-2026-118-B2)。
【資料表 audit_trail】
id bigserial, occurred_at timestamptz, actor_id, actor_role, action, entity_type, entity_id,
before_state jsonb, after_state jsonb, client_ip inet, correlation_id uuid, prev_hash char(64), hash char(64)
【規則】
1. hash = SHA-256( prev_hash || canonical_json(除 hash 外所有欄位) ),第一筆 prev_hash 為 64 個 0
2. 寫入需在同一交易中以 advisory lock 序列化,確保鏈不分岔
3. 應用帳號 app_rw 對 audit_trail 只有 INSERT 與 SELECT;以 migration 執行 REVOKE UPDATE, DELETE, TRUNCATE
4. before_state、after_state 寫入前必須經過 B3 遮罩函式庫處理(個資不得以明碼進入稽核表)
5. 提供 CLI 工具 audit-verify:從頭重算雜湊鏈,輸出第一筆不一致的 id
【測試】
- 連續寫入 10,000 筆後 audit-verify 回報 OK
- 以超級使用者竄改第 5,000 筆的 after_state,audit-verify 回報 BROKEN at id=5000
- 以 app_rw 執行 UPDATE、DELETE 皆失敗
- 併發 20 執行緒寫入,鏈仍完整🧑⚖️ 人工 Review 要點
- canonical JSON 的序列化規則(鍵排序、數字格式)有明確定義與測試,否則同一資料可能算出不同雜湊
- 雜湊計算包含
prev_hash,而非只對當筆資料雜湊 - REVOKE 寫在 migration 中且有測試證明
- 稽核寫入失敗時,業務交易必須一併回滾(不可「稽核失敗但交易成功」)
- 由資安或內稽人員參與審查雜湊鏈設計
✅ 驗證方式
以 SQL 直接檢查鏈結是否連續(不依賴 Agent 撰寫的驗證工具,作為獨立交叉驗證):
SELECT a.id
FROM audit_trail a
JOIN audit_trail p ON p.id = (SELECT max(id) FROM audit_trail WHERE id < a.id)
WHERE a.prev_hash <> p.hash
LIMIT 5;| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 鏈結連續 | 執行上方 SQL | 0 筆 | 調查斷點前後的寫入時序 |
| 竄改可偵測 | 測試環境手動修改一筆後執行 audit-verify | BROKEN at id=<被改的 id> | 檢查雜湊是否涵蓋所有欄位 |
| 不可修改 | 以 app_rw 執行 DELETE FROM audit_trail WHERE id=1 | permission denied | 補上 REVOKE |
| 無明碼個資 | SELECT count(*) FROM audit_trail WHERE after_state::text ~ '[A-Z][12][0-9]{8}' | 0 | 檢查是否漏接遮罩 |
26.3.3 資料遮罩
遮罩規則表(需經法遵與資安核准,作為 Agent 的唯一依據)
| 資料類型 | 原始範例 | 遮罩結果 | 明碼權限 |
|---|---|---|---|
| 身分證統一編號 | A123456789 | A12****789 | PII_FULL |
| 姓名 | 王小明 | 王○明 | PII_NAME |
| 存款帳號 | 0123456789012 | *********9012 | ACCT_FULL |
| 手機 | 0912345678 | 0912***678 | PII_FULL |
| 卡號 | 4111111111111111 | 411111******1111 | 不開放明碼 |
| 地址 | 台北市信義區松仁路100號5樓 | 台北市信義區*** | PII_FULL |
範例 Prompt
請依 docs/security/masking-rules.md(已核准,不可修改)實作遮罩函式庫(CR-2026-118-B3)。
【交付】
1. MaskingService:mask(value, type),null 與空字串原樣回傳,長度不足時全部遮罩
2. @Masked(type) 註解 + Jackson 序列化器:依目前使用者權限決定輸出遮罩或明碼
3. Logback MaskingPatternLayout:以正規表示式攔截 log 中符合身分證、帳號、卡號、手機格式的字串並遮罩
4. 例外訊息處理:GlobalExceptionHandler 回傳給前端的 detail 不得包含輸入值原文
【測試】
- 規則表每一列至少 3 個案例(正常、邊界、異常)
- 姓名含複姓(歐陽、司馬)、單名、外籍姓名
- 以 ListAppender 擷取 log,斷言不含任何明碼樣式
- 卡號在任何權限下都不得輸出明碼
【禁止】不可在測試資料中使用任何可能為真實人物的身分證號,一律使用檢查碼不合法的假號碼。🧑⚖️ 人工 Review 要點
- 規則表每一列都有對應測試,測試名稱可直接對照
- Log 遮罩是「最後防線」,不能取代在來源端不輸出個資;檢查業務程式碼是否仍有
log.info("customer={}", customer) - 卡號遮罩符合 PCI DSS 顯示限制(最多前 6 後 4)
- 測試用身分證號確實是不合法檢查碼的假號碼
✅ 驗證方式
在 SIT 環境執行完整測試後掃描 log:
grep -EHn "[A-Z][12][0-9]{8}|09[0-9]{8}|[0-9]{16}" logs/*.log | head -20預期輸出:無任何輸出。
判讀:任何命中都代表個資外洩到 log;以 Annotate AI Diff 標記產生該 log 的程式行並退回,同時通報資安評估是否需清除已收集的 log。
26.3.4 ISO 20022 報文轉換
範例 Prompt
請實作內部匯款格式轉 ISO 20022 pacs.008.001.08 的轉換器(CR-2026-118-B7)。
【輸入】
- docs/iso20022/field-mapping.xlsx(作業部門核准的欄位對應表,已匯出為 field-mapping.csv)
- schemas/pacs.008.001.08.xsd(官方 XSD,不可修改)
- samples/internal/*.json(30 筆合成樣本,涵蓋單筆、含中介銀行、含匯款用途代碼、含非 ASCII 姓名)
【規則】
1. 以 JAXB 依 XSD 產生類別,不可手寫 XML 字串
2. 金額使用 BigDecimal,幣別小數位依 ISO 4217(JPY 0 位、TWD 2 位、USD 2 位)
3. 非拉丁字元姓名依對應表規則轉為允許字元集,並保留原文於備註欄(若對應表要求)
4. 對應表中標示「待確認」的欄位不可自行決定,產生 TODO 清單並以 orca orchestration ask 詢問
5. 每筆樣本產出 XML 至 target/out/,並以 XSD 驗證
【測試】
- 30 筆樣本全數通過 XSD 驗證
- 反向解析產出的 XML,金額、幣別、受款人帳號與輸入一致(round-trip)
- 金額 0、負數、超過 18 位數皆拒絕🧑⚖️ 人工 Review 要點
- 欄位對應逐一與 field-mapping.csv 比對,由作業部門(非開發人員)簽核
- 確認沒有手寫 XML 字串拼接(搜尋
"<Document"、StringBuilder拼 XML) - 金額格式在 XML 中無科學記號、無多餘小數位
- 「待確認」欄位的答覆已記錄在 Jira,並與程式實作一致
✅ 驗證方式
執行:
for f in target/out/*.xml; do xmllint --noout --schema schemas/pacs.008.001.08.xsd "$f"; done 2>&1 | tee xsd-result.txt | grep -c " validates$" grep -c "fails to validate" xsd-result.txt預期輸出(示意):
30 0第一行代表 30 個檔案皆輸出
validates,第二行代表沒有任何fails to validate。判讀:出現
fails to validate時,xmllint 會指出元素與原因,例如金額小數位超過幣別允許位數;以該訊息作為 Annotate AI Diff 的留言內容退回。
26.3.5 授信規則與雙軌比對
授信規則(B6)與額度重算批次(B8)的正確性,無法只靠單元測試證明,必須以新舊雙軌比對驗證:同一批歷史案件同時跑現行系統與新系統,結果必須一致。
| 驗證步驟 | 內容 | 通過標準 |
|---|---|---|
| 1 取樣 | 取近 24 個月已結案授信案件 20,000 筆,經去識別化 | 涵蓋所有產品別與核准層級 |
| 2 回放 | 新規則引擎對每筆案件計算核准建議與額度 | 全數完成,無例外 |
| 3 比對 | 與現行系統當時的計算結果逐筆比對 | 不一致率 0%,或每筆差異皆有規則變更單佐證 |
| 4 簽核 | 授信管理部與風控部共同簽核比對報告 | 簽核紀錄歸檔至 CR 單 |
批次冪等性驗證:
java -jar batch.jar --job=creditLimitRecalc --runDate=2026-10-29
psql "$SIT_DB_URL" -At -c "SELECT md5(string_agg(customer_id||':'||limit_amt::text, ',' ORDER BY customer_id)) FROM credit_limit" > run1.md5
java -jar batch.jar --job=creditLimitRecalc --runDate=2026-10-29 --rerun=true
psql "$SIT_DB_URL" -At -c "SELECT md5(string_agg(customer_id||':'||limit_amt::text, ',' ORDER BY customer_id)) FROM credit_limit" > run2.md5
diff run1.md5 run2.md5 && echo "IDEMPOTENT"預期輸出:IDEMPOTENT。若兩次雜湊不同,代表批次重跑會產生不同結果(例如重複加總),不可上線。
26.4 治理與稽核流程
AI 輔助開發的變更管理流程
flowchart TD
CR["Jira 變更需求單 核准"] --> WT["Orca 建立 Worktree 連結 CR 子任務"]
WT --> PR1["Prompt 撰寫者 Maker 撰寫任務規格"]
PR1 --> AG["Agent 於行內 devbox 產出程式與測試"]
AG --> SELF["Maker 自我審查 Annotate AI Diff 回饋"]
SELF --> EVD["彙整證據包 測試輸出 Attribution 匯出"]
EVD --> PR2["建立 PR"]
PR2 --> CHK["Checker 第二位工程師 Code Review"]
CHK -->|"退回"| SELF
CHK -->|"高風險元件"| SEC["資安與內控覆核"]
CHK -->|"一般元件"| SIT["SIT 與雙軌比對"]
SEC --> SIT
SIT --> UAT["UAT 業務單位驗收"]
UAT --> CAB{"CAB 變更諮詢委員會"}
CAB -->|"核准"| DEP["依既有部署流程上線"]
CAB -->|"否決"| CR
DEP --> POST["上線後覆核與稽核抽查"]如何閱讀此圖:這張圖把銀行既有的變更管理流程與 Orca 的功能結合。從需求單到 Worktree 的連結保證可追溯;Maker(撰寫 Prompt 並審查 AI 產出的工程師)與 Checker(Code Review 的第二位工程師)必須是不同人,Agent 永遠只是「產出者」,不能擔任任何審查角色;高風險元件(B1、B2、B3、B6、B7)額外經資安與內控覆核;最後仍須經 UAT 與 CAB 核准才能上線。AI 的使用不刪減任何既有關卡。
職務分工矩陣(SoD)
| 活動 | Prompt 撰寫者(Maker) | Agent | Checker 工程師 | 資安與內控 | 業務單位 | CAB |
|---|---|---|---|---|---|---|
| 撰寫任務規格與 Prompt | 執行 | — | 知悉 | — | 提供需求 | — |
| 產出程式碼與測試 | 監督 | 執行 | — | — | — | — |
| 第一層審查(自我審查) | 執行 | 依回饋修正 | — | — | — | — |
| Code Review 核准 PR | 不得執行 | 不得執行 | 執行 | 高風險元件共同核准 | — | — |
| UAT 簽核 | 不得執行 | 不得執行 | 不得執行 | — | 執行 | — |
| 上線核准 | 不得執行 | 不得執行 | 不得執行 | 提供意見 | 提供意見 | 執行 |
技術層面的強制措施
| 控制 | 實作方式 | 驗證 |
|---|---|---|
| PR 需第二人核准 | Git 平台 Branch protection:至少 1 位非作者核准;高風險目錄以 CODEOWNERS 指定資安群組 | 嘗試自行核准自己的 PR 應被拒 |
| Agent 不得 push 到受保護分支 | Agent 執行帳號無受保護分支寫入權;Prompt 明示不得 commit/push | 檢查 Git 平台權限設定 |
| AI 產出可識別 | 每個 PR 附 Attribution 匯出的 diff metadata;commit trailer 標示使用的 Agent | 抽查 PR 附件 |
| 證據不可遺失 | 證據包上傳至 CR 單,而非只存在 Worktree(Worktree 刪除後即消失) | 稽核抽查 CR 單附件 |
| 用量與成本可追溯 | 依第八章彙整各 Agent 用量,按 CR 單分攤 | 月報 |
證據包內容(每個 PR 必附)
| 證據 | 來源 | 用途 |
|---|---|---|
| 任務規格與 Prompt 全文 | Worktree 中的 docs/tasks/<任務>.md | 證明 AI 收到的指示符合需求 |
| 測試指令與完整輸出 | 終端機輸出存檔 | 證明測試實際執行 |
| Attribution diff metadata | Diff Viewer 工具列匯出 | 區分 AI 與人工撰寫的程式碼 |
| Annotate AI Diff 留言與處理結果 | 審查紀錄截圖或匯出 | 證明人工確實審查並要求修正 |
| Worktree checkpoint 歷程 | orca worktree show --worktree <selector> --json 輸出 | 開發過程時間軸 |
| Checker 核准紀錄 | Git 平台 PR 頁面 | 雙人覆核證明 |
⚠️ 注意事項:Attribution 是 Orca 本機資料,不會寫入 git;Worktree 刪除後,若未匯出,AI 歸屬資訊就會消失。銀行案例中「匯出 Attribution 並附在 CR 單」必須列為 PR 合併前的強制步驟。
📌 查證狀態:官方文件明確記載|來源:Attribution
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 自我核准被阻擋 | 以 PR 作者帳號嘗試 Approve | Git 平台拒絕 | 修正 Branch protection |
| CODEOWNERS 生效 | 修改 approval/ 的 PR 是否自動要求資安群組審查 | 自動加入審查者 | 檢查 CODEOWNERS 路徑 |
| 證據包完整 | 隨機抽 3 個已合併 PR 檢查附件 | 6 項證據齊全 | 補件並檢討流程 |
| AI 不擔任審查者 | 檢查 PR 核准者清單 | 皆為具名真人帳號 | 移除服務帳號的核准權 |
❌ 常見錯誤
- 把 AI 平行產出的速度優勢拿來壓縮 UAT、雙軌比對與災難復原演練時間。
- 讓 Agent 擔任「Reviewer」並把它的「LGTM」當成 Checker 核准,違反雙人覆核精神。
- 只在應用層檢查 Maker 不等於 Checker,資料庫層沒有限制,DBA 或批次程式仍可繞過。
- 稽核表允許 UPDATE,或稽核內容含明碼個資,反而讓稽核表本身成為個資外洩來源。
💡 小技巧:先在「非核心、低風險」的周邊系統(例如內部報表、管理工具)試行本章流程 2~3 個月,累積證據包範本與審查經驗,再評估是否延伸到核心交易周邊的開發任務。
26.5 本章 Review 與驗證清單
- 能說明 Maker-Checker、稽核軌跡、職務分工、資料遮罩四項控制在本案的落實方式
- 已驗證自我核准在 API 與資料庫兩層皆被拒絕
- 已驗證稽核表無法被應用帳號 UPDATE 或 DELETE,且竄改可被雜湊鏈偵測
- 已以獨立 SQL 交叉驗證雜湊鏈,而非只相信 Agent 撰寫的驗證工具
- 已掃描 SIT log 與稽核表,確認無明碼個資
- 已以
xmllint驗證所有 pacs.008 樣本通過 XSD - 已完成新舊雙軌比對與批次冪等性驗證
- 已確認 Agent 不具受保護分支寫入權,且 PR 核准者皆為真人
- 每個 PR 的證據包(含 Attribution 匯出)已附在變更需求單
第二十七章 端到端完整企業案例
📌 查證狀態:教學示例(非官方),非真實客戶專案
本章把前四章的方法串成一條完整的交付鏈:從需求、分析、架構設計、Agent 分工、Coding 與 Review,一路到部署與維運。案例採保險業情境,刻意與第二十三章(一般 Web 應用)及第二十六章(銀行)不同,並涵蓋「Legacy 介面理解 → 新服務開發 → 金流整合 → 回寫既有系統 → 長期維運」的全生命週期。
本章使用的 Orca 功能地圖
| 生命週期階段 | Orca 功能 | 對應章節 |
|---|---|---|
| 需求 | Linear items drawer、從 Issue 建立 Worktree | 第十五章 |
| 分析 | SSH Worktrees、平行 Agent 逆向工程 | 第十八章、第二十四章 |
| 架構 | Rich Markdown 編輯器、Mermaid 檢視器 | 第十二章 |
| 分工 | Orchestration Run/Task/Worker、Decision gate | 第十六章 |
| Coding | Parallel Worktrees、Worktree Checkpoints、內建瀏覽器 | 第十一章、第十三章 |
| Review | Diff Viewer、Annotate AI Diff、Attribution、Fix with AI | 第十四章 |
| Deploy | Commit、Push、Hosted Review、Checks | 第十四章、第十五章 |
| Maintenance | Scheduled Automations、Resource Manager、Agents Feed | 第十章、第十七章 |
27.1 需求
業務背景:某壽險公司每年約有 40 萬張保單需要續期繳費。目前流程是寄送紙本繳費通知,保戶需臨櫃或轉帳繳費,逾期率約 6%,每月因逾期失效而需辦理復效的案件約 1,200 件。公司希望推出「保單續期提醒與線上續繳」服務。
使用者故事
| 編號 | 角色 | 故事 | 驗收條件 |
|---|---|---|---|
| US-1 | 保戶 | 在到期前 30、14、3 天收到提醒 | 依保戶偏好以 Email 或簡訊發送;已繳費者不再提醒;保戶可退訂 |
| US-2 | 保戶 | 點擊提醒連結後以信用卡完成續繳 | 3 步內完成;卡號不經過本公司伺服器 |
| US-3 | 保戶 | 繳費後立即看到成功結果並收到電子收據 | 結果頁於 5 秒內顯示;收據 1 分鐘內寄達 |
| US-4 | 保全人員 | 續繳結果自動回寫保單系統 | 回寫成功率 99.99%;失敗自動重試並告警 |
| US-5 | 行銷人員 | 查看提醒發送、開啟與轉換率 | 每日報表;不含個資明碼 |
非功能需求與成功指標
| 類別 | 指標 |
|---|---|
| 業務成效 | 上線 6 個月後逾期率由 6% 降至 3.5% 以下 |
| 可用性 | 繳費服務 99.95%;提醒服務 99.9% |
| 效能 | 繳費頁 P95 小於 1.5 秒;尖峰(月底)每分鐘 500 筆交易 |
| 安全與合規 | PCI DSS 範圍最小化;個資最小揭露;行銷通知需取得同意並提供退訂 |
| 一致性 | 「已扣款但未回寫」的案件需在 15 分鐘內自動修復或告警 |
操作步驟:在 Orca 建立需求追蹤
本專案產品團隊使用 Linear。開啟 Settings → Integrations → Linear,貼上個人 API Token 並選擇
RENEW團隊。在 Tasks 抽屜切換到 Linear,建立 Project「Renewal Online」,再為 US-1~US-5 各建立 Issue。
以
orca linear relation add標示相依關係,讓 Agent 也能讀到:orca linear relation add RENEW-4 --related RENEW-2 --type blocks --json orca linear issue RENEW-2 --relations --json從 Issue 建立 Worktree 時,Orca 會採用 Linear 建議的分支名稱,並把 Issue 中的附圖(例如繳費頁 mock-up)一併提供給 Agent 作為脈絡。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Linear 已連線 | Tasks 抽屜切到 Linear | 可看到 RENEW 團隊的 Issue | 檢查 Token 權限與團隊選擇 |
| 相依關係正確 | orca linear issue RENEW-2 --relations --json | 顯示 RENEW-4 被其 blocks | 重新執行 relation add |
| 每則故事有驗收條件 | 逐一開啟 Issue | 描述中有「驗收條件」段落 | 退回產品負責人補齊後再分派 |
27.2 分析
分析階段分三條平行軌道,各由一個 Agent 在獨立 Worktree 中進行,人負責收斂決策。
| 軌道 | 內容 | Agent | Worktree 分支 | 產出 |
|---|---|---|---|---|
| A1 Legacy 介面 | 依第二十四章方法盤點保單系統的查詢與回寫介面(CICS 交易、DB2 View、MQ 佇列) | Claude Code(SSH 至行內分析主機) | analysis/A1-legacy-policy | 介面清單、欄位字典、特性測試 |
| A2 合規分析 | 盤點 PCI DSS、個資、行銷同意的要求並轉成技術控制項 | Claude Code | analysis/A2-compliance | 控制項對照表(需求 → 技術措施 → 驗證方式) |
| A3 金流方案比較 | 比較兩家支付服務商的 Hosted Fields、Webhook、對帳 API | Codex | analysis/A3-psp | 比較表與建議(含 PCI 範圍影響) |
範例 Prompt:A2 合規分析
請在目前 Worktree 撰寫 docs/analysis/compliance-controls.md,作為「保單線上續繳」的合規控制項清單。
【輸入】docs/requirements/*.md、公司資安政策 docs/policy/security-baseline.md
【產出格式】一張表,欄位:
控制編號、來源(法規或政策名稱與條次,若不確定請標「待法遵確認」)、要求摘要、技術措施、
驗證方式(必須是可執行的指令、測試或可檢查的設定)、負責角色
【至少涵蓋】
- 卡號不得進入本公司系統(採 PSP Hosted Fields 或導轉,降低 PCI DSS 範圍)
- Webhook 必須驗證簽章並防重放
- 個資欄位遮罩與傳輸加密
- 行銷通知需同意紀錄與退訂機制
- 稽核紀錄保存期限
【規則】
- 不可捏造法規條次;不確定一律標「待法遵確認」
- 每個技術措施都要有對應的驗證方式,不可寫「定期檢查」這類無法執行的描述🧑⚖️ 人工 Review 要點
- 所有法規引用由法遵人員逐條核對,「待法遵確認」項目已得到回覆
- 「驗證方式」欄每一列都是可執行的檢查,而不是口號
- 控制項與 A3 選定的金流方案一致(例如 Hosted Fields 下本系統不應出現任何卡號欄位)
- 表格中的每個控制項都能在 27.4 的任務拆解中找到負責任務
分析結論與決策紀錄(ADR 摘要)
| ADR | 決策 | 理由 | 被否決的方案 |
|---|---|---|---|
| ADR-01 | 採 PSP Hosted Fields,本系統只接觸付款 Token | 卡號不進入本系統,PCI DSS 範圍最小 | 自建刷卡頁(PCI 範圍大、稽核成本高) |
| ADR-02 | 回寫 Legacy 採 Transactional Outbox + MQ | 避免「扣款成功但回寫遺失」,可重試、可追蹤 | 同步呼叫 CICS(Legacy 維護時段會失敗) |
| ADR-03 | 提醒排程採事件驅動,每日產生待提醒清單 | 可重跑、可稽核 | 每張保單一個 Timer(難以管理) |
| ADR-04 | 以 Webhook + 每日對帳檔雙重確認付款結果 | Webhook 可能遺失,對帳檔為最終依據 | 僅依 Webhook |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Legacy 介面理解正確 | 執行 A1 產出的特性測試(對測試區 Legacy) | 全數通過 | 回到第二十四章流程重新深掘 |
| 合規控制項完整 | 法遵與資安雙簽 compliance-controls.md | 簽核紀錄附在 Linear Project | 補齊後重簽 |
| ADR 已核准 | 架構審查會議紀錄 | 4 份 ADR 狀態皆為 Accepted | 未決 ADR 不得進入開發 |
27.3 架構設計
系統架構圖
flowchart LR
subgraph EXT["外部"]
U["保戶瀏覽器"]
PSP["支付服務商 PSP"]
SMS["簡訊與 Email 閘道"]
end
subgraph NEW["新服務 Kubernetes"]
GW["API Gateway"]
WEB["續繳前端 Vue 3"]
RS["renewal-svc 續期查詢"]
PAY["payment-svc 付款協調"]
NTF["notify-svc 通知"]
SCH["reminder-job 提醒排程"]
OUT["outbox-relay 事件轉送"]
DB[("PostgreSQL")]
end
subgraph LEG["既有系統"]
MQ["MQ 佇列"]
POL["保單系統 Legacy"]
DB2[("DB2 唯讀 View")]
end
U --> WEB
WEB --> GW
GW --> RS
GW --> PAY
WEB -->|"Hosted Fields 卡號直送"| PSP
PAY -->|"Token 授權請求"| PSP
PSP -->|"Webhook"| GW
RS --> DB2
SCH --> RS
SCH --> NTF
NTF --> SMS
PAY --> DB
PAY --> OUT
OUT --> MQ
MQ --> POL如何閱讀此圖:左側為外部參與者,中間為新建於 Kubernetes 的服務,右側為既有系統。最關鍵的一條線是「Hosted Fields 卡號直送」:卡號從保戶瀏覽器直接送往 PSP,新服務只拿到 Token,這是 ADR-01 降低 PCI 範圍的實現。付款結果由 payment-svc 寫入 PostgreSQL 與 Outbox 表,再由 outbox-relay 送進 MQ 回寫 Legacy(ADR-02);續期查詢只透過 DB2 唯讀 View 讀取保單資料。
續繳交易時序
sequenceDiagram
participant U as 保戶
participant W as 續繳前端
participant P as payment-svc
participant S as PSP
participant O as outbox-relay
participant L as 保單系統
U->>W: 點擊提醒連結
W->>S: Hosted Fields 送出卡號
S-->>W: 回傳付款 Token
W->>P: 送出 Token 與 Idempotency-Key
P->>S: 授權請求
S-->>P: 授權成功
P->>P: 同一交易寫入 payment 與 outbox
P-->>W: 顯示繳費成功
S->>P: Webhook 付款完成 已驗簽
O->>L: 經 MQ 回寫續繳結果
L-->>O: 回寫確認
O->>P: 標記 outbox 已送達如何閱讀此圖:由上而下為時間順序。注意三個可靠性設計:前端送出時帶 Idempotency-Key,避免保戶重複點擊造成重複扣款;payment-svc 在同一個資料庫交易中寫入付款紀錄與 Outbox 事件,確保兩者同生同滅;Webhook 先驗簽才處理。回寫 Legacy 是非同步的,失敗時由 outbox-relay 重試,不影響保戶看到的結果。
API 契約與架構產出的驗證
架構文件由 Agent 協助撰寫時,同樣需要可驗證:
| 產出 | 驗證方法 | 預期結果 |
|---|---|---|
OpenAPI 契約(api/*.yaml) | npx @redocly/cli lint api/*.yaml | 0 error |
| 非同步事件契約(AsyncAPI) | npx @asyncapi/cli validate api/events.yaml | File api/events.yaml is valid |
| Mermaid 架構圖 | 在 Orca 的 Markdown 預覽中開啟 | 圖可正常渲染,節點與 ADR 描述一致 |
| 架構與合規一致 | 搜尋前端與後端程式碼不應存在卡號欄位 | git grep -niE "cardNumber" 與 git grep -niw "pan" 皆無結果 |
27.4 Agent 分工
任務拆解表
| 任務 | Agent | Worktree 分支 | 交付物 | 驗收條件 |
|---|---|---|---|---|
| E1 契約 | Claude Code | renew/E1-contracts | OpenAPI、AsyncAPI、事件 schema | Lint 通過;人工核准(Gate) |
| E2 renewal-svc | Codex | renew/E2-renewal-svc | 續期查詢 API、DB2 View 存取 | 契約測試通過;查詢 P95 小於 300 ms |
| E3 payment-svc | Claude Code | renew/E3-payment-svc | Token 授權、Idempotency、Webhook 驗簽、Outbox | 重複請求不重複扣款;偽造 Webhook 被拒 |
| E4 notify-svc 與 reminder-job | Codex | renew/E4-notify | 提醒排程、Email 與簡訊、退訂、發送紀錄 | 已繳費者不提醒;退訂立即生效 |
| E5 outbox-relay 與回寫 | Codex | renew/E5-writeback | Outbox 轉送、重試、死信佇列、對帳修復 | 模擬 MQ 中斷後 15 分鐘內自動補送 |
| E6 前端 | Claude Code | renew/E6-frontend | 續繳頁、結果頁、收據頁 | E2E 測試通過;無卡號欄位 |
| E7 平台 | Codex | renew/E7-platform | Helm、GitHub Actions、監控告警 | helm lint、actionlint 通過 |
| E8 Security Review | Claude Code(唯讀) | renew/E8-security-review | 威脅模型、審查報告 | 高風險發現皆已修正或風險接受 |
時程規劃
gantt
title 保單續期線上續繳 專案時程
dateFormat YYYY-MM-DD
axisFormat %m/%d
section 分析
需求與合規分析 :a1, 2026-11-02, 7d
Legacy 介面逆向工程 :a2, 2026-11-02, 10d
ADR 審查 :milestone, m1, 2026-11-12, 0d
section 契約
E1 契約與核准 :crit, e1, after m1, 3d
section 平行開發
E2 renewal-svc :e2, after e1, 8d
E3 payment-svc :crit, e3, after e1, 10d
E4 notify 與排程 :e4, after e1, 8d
E5 outbox 與回寫 :crit, e5, after e1, 10d
E6 前端 :e6, after e1, 8d
E7 平台 :e7, after m1, 10d
section 驗證
E8 Security Review :e8, after e3, 4d
SIT 與對帳演練 :crit, s1, after e5, 7d
UAT :u1, after s1, 7d
正式上線 :milestone, m2, after u1, 0d如何閱讀此圖:每一列是一個任務,橫軸為日期。紅色(crit)為關鍵路徑:契約 → payment-svc 與 outbox 回寫 → SIT 與對帳演練 → UAT → 上線。E2、E4、E6、E7 有餘裕,可依 Agent 用量與審查人力彈性調整。平行開發讓 6 個任務在約兩週內同時進行,但審查人力是真正的瓶頸,請依審查者人數控制同時進入 Review 的任務數。
Orchestration 編排腳本
以下示範 Coordinator(可以是人在終端機中執行,也可以是一個負責協調的 Agent)如何建立任務、以閘門控制契約核准,並平行啟動 Worker。
orca orchestration run-create --objective "RENEW 線上續繳:契約核准後平行開發 E2-E7" --json
orca orchestration task-create --task-title "E1 契約" --spec "依 docs/specs/E1.md 產出 OpenAPI 與 AsyncAPI" --json
orca orchestration task-create --task-title "E3 payment-svc" --spec "依 docs/specs/E3.md 實作" --json
orca orchestration task-create --task-title "E5 outbox 與回寫" --spec "依 docs/specs/E5.md 實作" --json
orca orchestration gate-create --task <E3-taskId> --question "E1 契約已核准?" --options '["yes","no"]' --json
orca orchestration gate-create --task <E5-taskId> --question "E1 契約已核准?" --options '["yes","no"]' --json
orca orchestration worker-start --task <E1-taskId> --worktree new-child --name renew-E1-contracts --agent claude --setup run --json
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --jsonE1 回報 worker_done 且人工審查契約後:
orca orchestration gate-resolve --id <E3-gateId> --resolution "yes" --json
orca orchestration gate-resolve --id <E5-gateId> --resolution "yes" --json
orca orchestration worker-start --task <E3-taskId> --worktree new-child --name renew-E3-payment --agent claude --setup run --json
orca orchestration worker-start --task <E5-taskId> --worktree new-child --name renew-E5-writeback --agent codex --setup run --jsonWorker 完成時,必須在自己的終端機回報(含 taskId 與 dispatchId):
orca orchestration send --type worker_done \
--subject "E3 payment-svc 完成" \
--body "Idempotency、Webhook 驗簽、Outbox 完成;mvn verify 112 tests 通過;待辦:PSP 沙箱金鑰輪替說明" \
--task-id <E3-taskId> --dispatch-id <dispatchId> \
--outcome succeeded \
--files-modified "payment-svc/src/main/java/com/acme/renew/payment/PaymentService.java" \
--json📌 查證狀態:依官方說明延伸(教學推論)|來源:Orchestration。Worker 在完成後的終端機可用
worker-release釋放,之後以worker-read讀取歸檔輸出;不要為了重讀輸出而一直開著 Worker 終端機。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 閘門阻擋有效 | 在 gate 未 resolve 前執行 orca orchestration dispatch-show --task <E3-taskId> --json | 無進行中的 dispatch | 檢查 gate 是否建立在正確任務 |
| Worker 回報完整 | orca orchestration check --peek --json | worker_done 含 outcome、body、files-modified | 依 Worker contract 要求重送 |
| 子 Worktree 歸屬 | 側邊欄 Coordinator Worktree 顯示 N children 晶片 | 子任務 Worktree 巢狀顯示 | 確認 Worker 以 --worktree new-child 啟動 |
| 進度可視 | 各 Worktree 卡片的 comment 與狀態 | 依 checkpoint 規範更新 | 在 Prompt 中要求使用 orca worktree set |
27.5 Coding 與 Review
27.5.1 高風險任務 Prompt
範例 Prompt:E3 payment-svc
請在目前 Worktree 實作 payment-svc(Linear RENEW-2,Orchestration task 已注入 taskId 與 dispatchId)。
【必讀】api/payment.yaml、api/events.yaml、docs/adr/ADR-01.md、ADR-02.md、ADR-04.md、
docs/analysis/compliance-controls.md
【必做】
1. POST /payments:接收 paymentToken、policyNo、amount、Idempotency-Key(header,必填)
- 相同 Idempotency-Key 在 24 小時內重送,回傳第一次的結果,不得再次呼叫 PSP
- amount 必須等於 renewal-svc 查到的應繳金額,不得信任前端傳入值
2. POST /webhooks/psp:以 HMAC-SHA256 驗證簽章;timestamp 超過 5 分鐘拒絕(防重放);
相同 eventId 只處理一次
3. 授權成功後,在同一個資料庫交易中寫入 payment 與 outbox_event(type=RenewalPaid)
4. 日誌與錯誤訊息不得出現 paymentToken 全文(僅保留末 4 碼)
5. PSP 金鑰從環境變數或 Secret 讀取,不可寫入程式碼或設定檔
【測試】
- 併發 10 個相同 Idempotency-Key 的請求,PSP stub 只被呼叫 1 次
- 竄改 Webhook body 或簽章 → 401;timestamp 過舊 → 401;重複 eventId → 200 但不重複處理
- 模擬 outbox 寫入失敗 → payment 也回滾
- Pact 消費者契約:與前端 E6 的契約檔 pacts/frontend-payment.json 驗證通過
【回報】以 orca orchestration send --type worker_done 回報,body 包含測試數量與未完成事項。
不得自行 commit 或 push。🧑⚖️ 人工 Review 要點
- 金額以後端查詢結果為準,前端值僅用於比對(防竄改)
- Idempotency 實作有資料庫唯一鍵保護,而不只是記憶體快取
- HMAC 比較使用常數時間比較(
MessageDigest.isEqual),避免時序攻擊 -
git grep -nE "sk_live|sk_test|secret\s*="無任何金鑰 - Outbox 與 payment 寫入確實在同一
@Transactional邊界內,且沒有在交易中呼叫外部服務 - 交由 E8 Security Review Agent 與真人資安人員雙重審查
✅ 驗證方式
執行:
mvn -B -pl payment-svc verify mvn -B -pl payment-svc pact:verify預期輸出(示意):
[INFO] Tests run: 112, Failures: 0, Errors: 0, Skipped: 0 Verifying a pact between frontend and payment-svc a request to create payment with idempotency key returns a response which has status code 201 (OK) has a matching body (OK) [INFO] BUILD SUCCESS判讀:契約驗證任何一項顯示
FAILED,代表前後端對 API 的認知不一致,退回對應 Worktree 修正,而不是修改 Pact 檔讓它通過。
27.5.2 E5 回寫可靠性驗證
回寫 Legacy 是本案最容易在正式環境出事的地方。除了單元測試,必須做故障注入:
docker compose -f sit/docker-compose.yml stop mq
for i in $(seq 1 50); do ./sit/simulate-payment.sh "POL-$i"; done
psql "$SIT_DB_URL" -At -c "SELECT count(*) FROM outbox_event WHERE delivered_at IS NULL"
docker compose -f sit/docker-compose.yml start mq
sleep 120
psql "$SIT_DB_URL" -At -c "SELECT count(*) FROM outbox_event WHERE delivered_at IS NULL"
./sit/legacy-stub-count.sh RenewalPaid預期輸出(示意):
50
0
50判讀:MQ 停止時 50 筆皆滯留在 Outbox;MQ 恢復 2 分鐘後全數送達(0 筆未送達),且 Legacy stub 恰好收到 50 筆(不多也不少,代表無重複回寫)。若 Legacy 收到超過 50 筆,代表回寫端缺乏冪等處理。
27.5.3 Review 流程
flowchart TD
W["Worker 回報 worker_done"] --> A["Attribution 檢視 AI 產出比例"]
A --> B["Annotate AI Diff 逐行留言"]
B --> C{"需修正"}
C -->|"是"| D["Send to agent 批次退回"]
D --> W
C -->|"否"| E["E8 Security Review Agent 唯讀審查"]
E --> F["真人資安審查高風險發現"]
F --> G["Commit 與 Push"]
G --> H["建立 PR 並等待 Checks"]
H --> I["第二位工程師核准"]如何閱讀此圖:Worker 完成後,先用 Attribution 找出 AI 產出比例高的檔案,再用 Annotate AI Diff 一次留完所有意見,透過 Send to agent 批次退回,避免 Agent 一次只改一點來回擺盪。修正完成後交給唯讀的 Security Review Agent 做第二道掃描,但其結論只是「發現清單」,必須由真人資安判斷;最後走一般的 Commit、PR、Checks 與第二人核准。
操作步驟
- 在 E3 Worktree 開啟 Diff Viewer,確認比較基準為 start-from ref。
- 開啟 Attribution 標記,優先審查
payment/、webhook/中 AI 產出的行。 - 對問題行按
+或在行上按c留言;多行問題可拖曳選取範圍。 - 全部留言完成後點 Send to agent,選擇 E3 原本的 Agent。
- Agent 修正後,逐條比對原留言並點 Resolve;未解決的留言會在下次 Send 時自動帶入。
- 在 Source Control 面板 Stage、Commit;若 pre-commit hook(例如 Secret 掃描)失敗,可用 Fix with AI 交由 Agent 修復,但修復後需再次審查 Diff。
- Push 後以 hosted review 動作建立 PR;若 Create PR 流程中需要的後續 commit 失敗,依對話框中的失敗摘要處理。
- 從 Diff 工具列匯出 Attribution metadata,附在 PR 或 Linear Issue。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 留言皆已處理 | Diff Viewer 中無未 Resolve 的留言 | 0 筆未解決 | 再次 Send to agent |
| 測試證據在 PR 中 | 檢查 PR 描述 | 附測試指令與摘要輸出 | 補上 |
| Checks 全綠 | PR 頁面或 Orca 中的 Checks 狀態 | 全部通過 | 依失敗的 Check 回到 Worktree 修正 |
| 無強制推送覆蓋他人提交 | 檢查 Push 紀錄 | 一般 Push 或 Force push with lease | 禁止使用一般 force push |
27.6 Deploy 與 Maintenance
27.6.1 CI 與部署管線
flowchart LR
PR["PR 合併到 main"] --> CI["GitHub Actions 建置與測試"]
CI --> SCAN["SAST 相依掃描 映像檔掃描"]
SCAN --> IMG["推送映像檔 以 digest 標記"]
IMG --> STG["部署預備環境"]
STG --> SMOKE["冒煙測試與對帳演練"]
SMOKE --> APR{"上線核准"}
APR -->|"核准"| CAN["金絲雀 5 百分比流量"]
CAN --> OBS["觀察錯誤率 P95 回寫延遲"]
OBS -->|"正常"| FULL["全量上線"]
OBS -->|"異常"| RB["自動回退"]如何閱讀此圖:由左至右為一次發版。合併後先跑建置、測試與三類安全掃描,映像檔以不可變的 digest 標記;預備環境除冒煙測試外,還要跑一次與 PSP 沙箱的對帳演練;人工核准後以 5% 流量金絲雀發布,觀察錯誤率、P95 與「Outbox 未送達數」三個指標,異常即自動回退。
上線前驗證
helm lint deploy/helm/renewal
helm template deploy/helm/renewal -f deploy/helm/renewal/values-prod.yaml | kubeconform -strict -summary
actionlint .github/workflows/*.yml
trivy image --severity HIGH,CRITICAL --exit-code 1 registry.acme.local/renew/payment-svc@sha256:<digest>預期輸出(示意):
==> Linting deploy/helm/renewal
1 chart(s) linted, 0 chart(s) failed
Summary: 24 resources found parsing stdin - Valid: 24, Invalid: 0, Errors: 0, Skipped: 0
Total: 0 (HIGH: 0, CRITICAL: 0)27.6.2 以 Scheduled Automations 進行維運
上線後的例行工作適合交給排程自動化,但一律以「唯讀摘要、人決定是否行動」為原則。
| 自動化 | 排程 | Precheck | Prompt 重點 | 輸出 |
|---|---|---|---|---|
| 每日對帳摘要 | 每日 08:30 | 對帳檔已到達 | 比對 PSP 對帳檔與 payment 表,列出差異,不修改資料 | 差異清單 |
| 每週相依套件檢查 | 每週一 09:00 | 無 | 列出有 CVE 的相依與建議版本,不修改 pom.xml | 升級建議 |
| 每日 Outbox 健康檢查 | 每小時 | 有未送達事件 | 分析滯留原因並摘要 | 告警摘要 |
orca automations create \
--name "RENEW 每日對帳摘要" \
--trigger daily --time 08:30 --timezone Asia/Taipei \
--precheck 'test -f /data/psp/settlement/$(date +%Y%m%d).csv' \
--prompt "讀取今日 PSP 對帳檔與 payment 表(唯讀帳號),列出金額或狀態不一致的交易編號與差異原因推測。不得修改任何資料或程式碼。" \
--provider claude \
--repo renewal-platform \
--disabled \
--json⚠️ 注意事項:自動化執行時使用的資料庫帳號必須是唯讀帳號;Prompt 中的「不得修改」只是指示,真正的防線是帳號權限。先以 --disabled 建立、用 orca automations run <id> 手動試跑並檢查結果,確認後才 orca automations edit <id> --enabled。
27.6.3 長期維運清單
| 頻率 | 工作 | Orca 相關操作 |
|---|---|---|
| 每日 | 檢視自動化摘要與 Agents Feed | Agents Feed、Notifications |
| 每週 | 清理已合併任務的 Worktree | Resource Manager → Clean up workspaces;處理 Review N Branches |
| 每月 | 檢視 Agent 用量與成本,按專案分攤 | Usage 與 Stats(第八章) |
| 每月 | 檢查 Orca 與各 Agent CLI 版本更新,於測試 Worktree 驗證後再推廣 | 第二十九章版本管理 |
| 每季 | 複核合規控制項是否因法規或 PSP 變更而需調整 | 重跑 27.2 的 A2 Prompt 產出差異 |
| 每季 | 演練 MQ 中斷與 PSP 中斷的故障注入 | 27.5.2 腳本 |
維運 Runbook 範例:Outbox 滯留告警
- 在 Orca 建立 Worktree
ops/outbox-incident-<日期>,Run on 選擇可存取正式環境唯讀資料的維運主機(SSH)。 - 啟動 Agent,提供告警內容,要求「只分析、不修改」:查詢滯留事件數、最早滯留時間、MQ 連線狀態。
- Agent 以
orca worktree set --comment更新診斷進度,值班人員在側邊欄即可掌握。 - 由值班人員依診斷結果決定處置(重啟 relay、聯繫 Legacy 團隊等),處置動作由人執行。
- 事後把診斷過程整理為 Postmortem,並將有效的查詢指令補入 Runbook。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 自動化為唯讀 | 檢查自動化使用的資料庫帳號權限 | 僅 SELECT | 更換帳號 |
| 自動化試跑成功 | orca automations runs --id <id> --json | 最近一次結果為成功且有摘要 | 調整 Prompt 或 precheck |
| Worktree 未堆積 | Resource Manager 列表 | 已合併任務的 Worktree 已清理 | 每週固定清理 |
| 成功指標追蹤 | 每月業務報表 | 逾期率趨勢下降 | 回到 27.1 檢討需求假設 |
重點整理:本案例展示 Orca 在完整生命週期中的角色——它把需求(Linear)、分析(SSH 上的平行逆向工程)、開發(Orchestration 管理的平行 Worktree)、審查(Annotate AI Diff 與 Attribution)、部署(Source Control 與 PR)、維運(Scheduled Automations)串在同一個工作環境中,但每一個關鍵決策點(契約核准、資安審查、上線核准、維運處置)都保留給人。
❌ 常見錯誤
- 因平行開發速度加快,壓縮了合規審查、對帳演練與滲透測試時間。
- 只做 Webhook 不做對帳檔核對,Webhook 遺失時「扣款成功但保單未續期」。
- 維運自動化使用具寫入權限的帳號,僅靠 Prompt 禁止修改。
- 專案結束後 Worktree 與分支長期堆積,造成磁碟與記憶體負擔,也讓後續稽核難以分辨哪些是有效分支。
💡 小技巧:把 27.4 的任務拆解表與 Orchestration 腳本存成團隊模板,任何「涉及金流或個資的新服務」都以「契約 Gate → 平行開發 → Security Review → 雙重確認對帳」為起手式。
27.7 本章 Review 與驗證清單
- 能說明本案從需求到維運每個階段使用的 Orca 功能與人工決策點
- 已在 Linear 建立需求並以 relation 標示相依,Worktree 由 Issue 建立且保持連結
- 已完成合規控制項表,且每一列都有可執行的驗證方式並經法遵簽核
- 能解讀架構圖與時序圖,說明 Hosted Fields、Idempotency、Outbox 各自解決的風險
- 已以 Orchestration 建立任務與 Decision gate,並驗證 gate 未 resolve 前任務不會被派送
- 已驗證相同 Idempotency-Key 不會重複扣款、偽造 Webhook 會被拒絕
- 已完成 MQ 中斷的故障注入,確認 Outbox 補送且 Legacy 無重複回寫
- 已完成 Annotate AI Diff 審查循環並匯出 Attribution metadata
- 上線前已執行
helm lint、kubeconform、actionlint、trivy並全數通過 - 維運自動化皆以
--disabled建立、試跑後才啟用,且使用唯讀帳號
第二十八章 安全合規與金鑰治理
Orca 讓 Agent 在本機或遠端以你的身分執行指令、讀寫檔案、連網、提交程式碼;這等於把「開發者權限」交給了一個會犯錯、也可能被誘導的程式。本章以威脅模型為起點,依序說明權限、憑證、遠端與行動端、資料外洩防護,最後對應到稽核與合規要求。
📌 查證狀態:本章引用的 Orca 功能與預設值為官方文件明確記載,並已對照 v1.4.244 版本變更|來源:Supported agents、Settings、SSH worktrees、Remote Orca Servers、Mobile companion、Privacy & Telemetry;威脅模型、基準設定與合規對應屬依官方說明延伸(教學推論)
28.1 威脅模型
概念說明
威脅模型回答三個問題:要保護什麼(資產)、資料跨越哪些邊界(信任邊界)、可能出什麼錯(威脅)。Orca 情境下的關鍵認知是:Worktree 是「工作隔離」,不是「安全隔離」——同一台機器上的所有 Worktree 共用同一個作業系統使用者、同一個家目錄(含各 Agent CLI 的憑證)與同一個網路。
需保護的資產
| 資產 | 所在位置 | 外洩或遭竄改的影響 |
|---|---|---|
| 原始碼與商業邏輯 | Repository、各 Worktree | 智慧財產外洩、遭植入後門 |
| Agent CLI 憑證 | 各 CLI 自管目錄(例:~/.claude、~/.codex、~/.copilot) | 帳號遭盜用、費用暴增 |
| 整合服務 Token | Orca Settings → Integrations(GitHub、Linear、Jira、Bitbucket 等) | 需求單、PR 遭竄改 |
| 應用程式機敏設定 | .env、本機設定檔 | 資料庫、雲端資源遭存取 |
| SSH 金鑰與通行碼 | ~/.ssh、Orca 記憶體中的通行碼 | 遠端主機遭入侵 |
| 遠端與行動端配對憑證 | Remote Orca Server 存取連結、行動裝置 Token | 他人取得整個 Orca 執行環境的控制權 |
| Prompt 與 Agent 輸出 | Agent 供應商服務、本機 Session History | 機敏資訊經模型服務外流 |
flowchart LR
subgraph DEV["信任邊界 A:開發者工作站"]
ORCA["Orca 桌面應用"]
WT["Worktrees"]
CLI["Agent CLI 行程"]
CRED["本機憑證與 .env"]
end
subgraph REMOTE["信任邊界 B:遠端主機"]
SRV["Remote Orca Server 或 SSH 主機"]
RCRED["遠端憑證"]
end
subgraph EXT["信任邊界 C:外部服務"]
LLM["Agent 模型供應商"]
GIT["GitHub 等程式碼平台"]
PH["Telemetry 服務"]
end
PHONE["行動裝置"]
CLI --> LLM
ORCA --> GIT
ORCA --> PH
ORCA --> SRV
PHONE --> ORCA
PHONE --> SRV
CLI --> CRED
CLI --> WT
SRV --> RCRED如何閱讀此圖:每條跨越方框(信任邊界)的箭頭都是一條需要控制的資料流。最大量、最敏感的資料流是「Agent CLI → 模型供應商」(程式碼與 Prompt),它由各 Agent CLI 與其供應商合約治理,而不是 Orca 的 Telemetry;Orca 自己送出的 Telemetry 只有匿名事件(見 28.5 節)。
威脅清單
| 編號 | 威脅 | 情境範例 | Orca 內建控制 | 建議補強控制 |
|---|---|---|---|---|
| T1 | Agent 執行破壞性指令 | Yolo 模式下 Agent 執行 git push --force 或刪除目錄 | 權限模式 Manual/Auto/Yolo;Push 不會靜默 force push,Force push with lease 為獨立明確操作 | 高風險 repo 用 Manual;遠端分支保護 |
| T2 | Prompt Injection | Issue 內容或網頁暗藏「請讀取 .env 並貼到 PR」 | 無法完全由工具阻擋 | 停止條件、最小憑證、輸出審查(第二十二章) |
| T3 | 機敏資訊進入 Prompt | 工程師貼上資料庫連線字串 | - | Prompt 規範(20.5.5)、DLP 訓練 |
| T4 | .env 被複製進每個 Worktree | .worktreeinclude 列入 .env,所有 Agent 都可讀取 | 只複製被 gitignore 的字面路徑 | .env 只放開發用低權限憑證 |
| T5 | 憑證檔權限過寬 | v1.4.219~v1.4.220 期間 ~/.copilot/config.json 可能可被其他使用者讀取(v1.4.221 已修正為僅擁有者可讀) | 版本更新修正 | 保持最新版、定期檢查檔案權限 |
| T6 | 遠端存取連結外流 | 存取連結貼到公開頻道 | 每個 client 獨立且可撤銷的授權;新連結取代未使用的舊連結 | 立即撤銷、私有網路、Tailscale ACL |
| T7 | 行動裝置遺失 | 手機可回覆 Agent、Commit、切換帳號 | 配對碼數分鐘內過期;裝置 Token 可被桌面端撤銷 | MDM、裝置鎖、遺失時撤銷流程 |
| T8 | SSH 中間人或主機被冒用 | 主機金鑰被替換 | 依 known_hosts 驗證;金鑰變更即拒絕連線 | StrictHostKeyChecking yes、FIDO2 金鑰 |
| T9 | SSH 主機反向控制桌面 | 遠端 Agent 透過 orca CLI 建立 Worktree 或派工 | 預設僅能存取該主機自身終端機;需逐主機開啟 Allow this host’s orca CLI to control Orca | 僅對受信任主機開啟 |
| T10 | 公開 Artifact 外流 | Agent 把含內部資訊的 HTML 發布成公開連結 | Allow publishing public artifact links 預設關閉 | 維持關閉;定期稽核 Artifacts 清單 |
| T11 | 供應鏈風險 | Agent 自行新增惡意或過時套件 | - | 停止條件、相依變更審查(22.3 D9)、SCA 掃描 |
| T12 | 有漏洞的 AI 程式碼被合併 | 缺少授權檢查的 API | Diff Viewer、Annotate、Attribution | 三層驗證模型(22.2) |
📌 查證狀態:T5 的版本事實來自 v1.4.221 Release Notes;T6、T7、T8、T9、T10 的內建控制為官方文件明確記載|來源:Remote Orca Servers、Mobile companion、SSH worktrees、Settings
範例 Prompt:請 AI 協助產出專案威脅模型草稿
請依本專案(repo 根目錄)與下列使用情境,產出 STRIDE 威脅模型草稿:
- 開發者以 Orca 在本機平行執行 3 個 Agent(Claude Code、Codex、GitHub Copilot CLI)
- 部分任務在 SSH 主機 build-01 上執行
- Tech Lead 會用手機 Orca Mobile 回覆 Agent
輸出表格欄位:編號|STRIDE 類別|資產|威脅情境|現有控制(標註來源檔案或設定)|建議補強。
只列出能在本 repo 或上述情境中找到依據的威脅;找不到依據的寫「待確認」。🧑⚖️ 人工 Review 要點
- 每一列「現有控制」都能在 repo 檔案或 Orca Settings 中實際找到,不是 AI 想像的控制
- 至少涵蓋本節 T1~T12 中與本專案相關者,遺漏者補上
- 「建議補強」都有具體負責人與完成日期後才算定稿
- 威脅模型存入 repo(例:
docs/security/threat-model.md),並由資安人員簽核
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 資產盤點完整 | 對照本節資產表逐項確認 | 每項都有所在位置與負責人 | 補齊盤點 |
| 威脅模型已簽核 | git log --oneline -- docs/security/threat-model.md | 有資安人員核准的 commit 或 PR | 送資安審查 |
| 控制項真實存在 | 抽查 3 項「現有控制」 | 皆可在設定或檔案中找到 | 修正威脅模型 |
28.2 Agent 權限與沙箱
概念說明
Orca 對每個支援的 Agent CLI,在新啟動時會預填該 CLI 的「略過權限確認」旗標,例如 Claude 的 --dangerously-skip-permissions、Codex 的 --dangerously-bypass-approvals-and-sandbox、Gemini/Cursor/GitHub Copilot 等的 --yolo。官方的理由是 Worktree 可拋棄:Agent 在自己的 checkout 中實驗,你仍可在合併前挑選或丟棄 Diff。
這個理由在「程式碼正確性」層面成立,但在「安全」層面並不完整:Yolo 模式下的 Agent 仍可讀取家目錄中的憑證、存取網路、對遠端執行 git push。企業必須明確選擇權限模式,而不是沿用預設。
📌 查證狀態:官方文件明確記載|來源:Supported agents、Settings。Manual/Auto/Yolo 三種模式自 v1.4.232 起提供;v1.4.241 起 Chat 的權限設定統一移至 Settings → Agents。
三種權限模式
| 模式 | 行為 | 支援範圍 | 適用情境 |
|---|---|---|---|
| Manual | Agent 每個需要權限的動作都詢問人 | 所有 Agent | 高風險 repo、審查類角色、含正式憑證的環境 |
| Auto | Agent 自行核准例行動作,其餘仍詢問 | Claude、Claude Agent Teams、Codex | 一般開發,兼顧效率與控制 |
| Yolo | 略過所有權限確認 | 所有有對應旗標的 Agent | 隔離環境(拋棄式 VM、容器、無憑證主機) |
與權限相關的其他設定
| 設定 | 位置 | 預設 | 安全意涵 |
|---|---|---|---|
| Agent permissions | Settings → Agents | 支援的 CLI 預填略過權限旗標 | 選 Auto 時,可用 Other agents 為不支援 Auto 的 Agent 另選 Manual 或 Yolo |
| 自訂啟動參數 | Settings → Agents → 個別 Agent 的 Command/Arguments/環境變數 | 無 | 非空的自訂值視為明確覆寫,該 Agent 不再受全域權限切換影響 |
| Trust the folder when Orca starts an agent | Settings → Agents | 開啟 | Orca 啟動的 Agent(含 Orchestration Worker、Automations、手機啟動者)會略過 CLI 自身的「是否信任此資料夾」提示 |
| Claude Agent Teams | Settings → Agents | 關閉 | 開啟後可一次啟動多個 Claude 隊友 |
| Codex Ask mode | Codex Chat | - | v1.4.242 起為唯讀,適合審查與問答 |
| Allow this host’s orca CLI to control Orca | Settings → SSH → 編輯主機 → Advanced Connection | 關閉 | 開啟後該主機上的 Agent 可建立 Worktree、開終端機、派工 |
企業建議基準(教學示例(非官方))
| 環境 | 終端機 Agent 權限 | Folder trust 自動回應 | 補充控制 |
|---|---|---|---|
| 個人實驗、開源專案 | Yolo 或 Auto | 開啟 | 無正式憑證 |
| 企業一般專案(本機) | Auto;不支援 Auto 者 Manual | 開啟 | .env 僅放開發憑證;遠端分支保護 |
| 高監理專案(金融、個資) | Manual | 關閉 | 審查類角色唯讀;所有 push 經 PR |
| 隔離沙箱(拋棄式 VM、容器、Cloud VM) | Yolo | 開啟 | 沙箱內無正式憑證、網路出口受限 |
操作步驟:設定企業一般專案基準
- 開啟 Settings → Agents → Agent permissions,選擇 Auto。
- 在 Other agents 為不支援 Auto 的 Agent 選擇 Manual。
- 檢查各 Agent 的自訂 Command/Arguments:若有人曾手動加入
--yolo等旗標,該 Agent 不會跟隨全域設定,需清除自訂值或改為預設集(preset)。 - 高監理專案另外關閉 Trust the folder when Orca starts an agent。
- 對「需要 Yolo 才有效率」的任務,改在隔離環境執行:SSH 專用主機、Remote Orca Server 專用 VM,或 Experimental 的 Cloud VM(見第十八章)。
範例:用作業系統行程清單驗證實際啟動參數
設定畫面顯示的是「意圖」,行程的實際命令列才是「事實」。啟動 Agent 後執行:
# macOS/Linux
ps -eo pid,args | grep -E "claude|codex|copilot|gemini" | grep -v grep# Windows
Get-CimInstance Win32_Process |
Where-Object { $_.CommandLine -match 'claude|codex|copilot|gemini' } |
Select-Object ProcessId, CommandLine預期輸出(Manual 模式,示意):
4812 claude
4977 codex若出現 --dangerously-skip-permissions、--dangerously-bypass-approvals-and-sandbox 或 --yolo,代表該 Agent 仍為略過權限模式(可能是自訂參數覆寫了全域設定)。
範例:沙箱化的高權限任務 Prompt
你在拋棄式 VM(SSH 主機 sandbox-07)上以 Yolo 模式執行。此主機沒有正式環境憑證,網路僅允許連到內部套件鏡像。
任務:升級 test/ 下的 Jest 設定至新版並修正測試。
禁止:git push、修改 .github/、安裝 package.json 未列出的全域工具。
完成後只需 commit 到本地分支,由人類從 Orca 審查 Diff 後決定是否 push。🧑⚖️ 人工 Review 要點
-
git log --oneline origin/<branch>..HEAD顯示 commit 尚未 push(Agent 遵守禁止事項) -
git diff --name-only main...HEAD未包含.github/ - VM 上的 shell 歷程中沒有
npm install -g等未授權安裝
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 全域權限模式 | Settings → Agents → Agent permissions | 與組織基準一致 | 調整後重新啟動 Agent |
| 實際啟動參數 | 上方 ps 或 Get-CimInstance 指令 | 無略過權限旗標(Manual/Auto 環境) | 清除該 Agent 的自訂 Arguments |
| Folder trust | Settings → Agents | 高監理專案為關閉 | 關閉後新啟動的 Agent 生效 |
| SSH 主機反向控制 | Settings → SSH → 各主機 Advanced Connection | 僅受信任主機開啟 | 關閉不必要者 |
| 遠端分支保護 | 在 GitHub 嘗試直接 push 到 main | 被拒絕 | 啟用分支保護 |
⚠️ 注意事項:既有的 Chat 會沿用其開始時的權限模式,變更設定只影響新啟動的工作階段。調整基準後,請關閉並重新啟動進行中的 Agent。
28.3 憑證與金鑰治理
概念說明
Orca 不是統一的金鑰保管庫。憑證分散在三個地方,治理方式各不相同:
| 憑證類型 | 存放位置與管理者 | 治理重點 |
|---|---|---|
| Agent CLI 登入與 API Key | 各 CLI 自管(例:~/.claude、~/.codex、~/.copilot/config.json);Orca 的帳號切換器管理多帳號 | 檔案權限、帳號盤點、離職回收(帳號治理見第八章) |
| Orca 整合服務 Token | Settings → Integrations:GitHub OAuth、Linear API token、Jira(Cloud 為 email+API token,Server/Data Center 為 PAT 或帳密)、Bitbucket、MiniMax session cookie、MCP servers | 最小權限 Token、定期輪替;Bitbucket 可改用 ORCA_BITBUCKET_* 環境變數,且環境變數優先 |
| 專案機敏設定 | .env、本機設定檔,可能經 .worktreeinclude 複製到每個 Worktree | 只放開發用低權限憑證;正式憑證不進開發機 |
| SSH 金鑰 | ~/.ssh;通行碼由 Orca 保存在記憶體,關閉 Orca 即清除(可選擇延長 TTL) | 使用通行碼或 FIDO2 硬體金鑰 |
| 遠端主機上的憑證 | Remote Orca Server 使用伺服器端的 PATH、家目錄與憑證,不會沿用筆電上的登入 | 伺服器專用服務帳號 |
| 語音輸入雲端模型金鑰 | Settings → Voice(選用 OpenAI 雲端模型時) | 優先使用本機語音模型 |
📌 查證狀態:上表位置與行為為官方文件明確記載|來源:Settings、SSH worktrees、Remote Orca Servers、Worktrees。v1.4.219 起 Linux Wayland 環境提供憑證加密與「未加密」警告;Orca 本機憑證的確切加密機制官方未詳述,屬待查證項目。
28.3.1 防止憑證進入版控
範例:.gitignore 與 .env.example
# .gitignore(節錄)
.env
.env.*
!.env.example
*.pem
*.p12
*.key
id_rsa*
.npmrc
evidence/*.secret*# .env.example(只放鍵名與假值,納入版控)
DATABASE_URL=postgres://dev_user:CHANGE_ME@localhost:5432/app_dev
PAYMENT_GATEWAY_API_KEY=sk_test_REPLACE_ME範例:.worktreeinclude 的安全寫法
.worktreeinclude 會把列出的 gitignored 檔案複製到每個新 Worktree。這很方便,但也代表每個 Agent 都讀得到這些檔案。
# .worktreeinclude(repo 根目錄)
# 只列出「開發用、低權限、外洩可接受」的設定檔
.env.development.local
# 不要列入含正式或 UAT 憑證的檔案,例如 .env.production、.env.uat28.3.2 Secret Scanning
操作步驟
安裝 gitleaks(擇一):
brew install gitleakswinget install --id Gitleaks.Gitleaks掃描目前分支相對 main 的新 commit(審查 AI 產出時使用):
gitleaks git --log-opts="main..HEAD" -v掃描工作目錄(含未 commit 的檔案,例如 Agent 剛產生的設定檔):
gitleaks dir . -v設定 pre-commit hook,讓 Orca 的 Commit 按鈕也會觸發(Orca 會照常執行 repo 的 pre-commit hooks,失敗時於介面顯示輸出):
# .pre-commit-config.yaml repos: - repo: https://github.com/gitleaks/gitleaks rev: v8.24.2 # 請改為組織核准的版本 tag hooks: - id: gitleakspre-commit install在 CI 加入同樣的掃描,作為最後一道防線;並在遠端平台啟用 push protection(例:GitHub Secret Scanning)。
📌 查證狀態:gitleaks 與 pre-commit 為第三方開源工具,子指令與版本請以 gitleaks 官方 Repo 為準(較舊版本使用
gitleaks detect與gitleaks protect);Orca 執行 pre-commit hooks 為官方文件明確記載|來源:Commit & push
✅ 驗證方式
在測試分支建立一個含假 Token 的檔案(不要使用真實憑證):
# 以變數拼接,避免本文件本身被 secret scanner 誤判 prefix="ghp_" echo "GITHUB_TOKEN=${prefix}1a2B3c4D5e6F7g8H9i0J1k2L3m4N5o6P7q8R" > leak-test.env git add -f leak-test.env嘗試在 Orca 的 Source Control 面板按 Commit,或在終端機執行
git commit -m "test"。預期結果:pre-commit hook 失敗,Orca 顯示 gitleaks 輸出(示意):
Finding: GITHUB_TOKEN=ghp_1a2B3c... RuleID: github-pat File: leak-test.env leaks found: 1清除測試檔:
git restore --staged leak-test.env rm leak-test.env判讀:若 commit 成功,代表 hook 未安裝或規則未涵蓋,先修正再信任它。注意:若使用 Fix with AI 處理 hook 失敗,Orca 只會給 Agent 修復用的 Prompt,不會要求它略過 hook;但仍需審查 Agent 是否把 Token「搬到」別處而非移除。
28.3.3 憑證檔權限檢查
v1.4.221 修正了 ~/.copilot/config.json(含 Token)可能被其他使用者讀取的問題;官方說明舊檔要到下次新增資料夾時才會修正權限。建議主動檢查:
ls -l ~/.copilot/config.json ~/.codex/auth.json 2>/dev/null預期(示意):
-rw------- 1 alice staff 812 Oct 30 09:12 /Users/alice/.copilot/config.json若顯示 -rw-r--r--,手動修正:
chmod 600 ~/.copilot/config.jsonWindows 以 icacls 檢查,預期只有目前使用者、SYSTEM 與 Administrators:
icacls "$env:USERPROFILE\.copilot\config.json"📌 查證狀態:
~/.copilot/config.json權限事件為官方 v1.4.221 Release Notes 記載;~/.codex/auth.json等其他 CLI 的檔名依各 CLI 版本而異,屬教學推論,請以該 CLI 文件為準。
28.3.4 憑證外洩應變
操作步驟
先撤銷、再清理:立即在發行端(GitHub、雲端主控台、資料庫)撤銷或輪替該憑證。清理 git 歷史無法讓已外洩的憑證失效。
若憑證曾出現在 Prompt 或 Agent 輸出:視同已傳送至該 Agent 的模型供應商,依供應商合約申請刪除或確認保留政策。
若曾透過 Remote Orca Server 存取連結或行動裝置外洩:於 Settings → Remote Orca Servers → Shared Server Access 撤銷對應授權(見 28.4 節)。
搜尋影響範圍:
gitleaks git -v git log --all -S "ghp_1a2B3c" --oneline記錄事件時間軸、影響範圍與處置,納入 28.6 節的稽核證據。
🧑⚖️ 人工 Review 要點(審查 AI 產出時的憑證檢查)
-
gitleaks git --log-opts="main..HEAD" -v無發現 - Diff 中沒有新增寫死的 URL 帳密、Token、私鑰
- 新增的 log 語句沒有輸出 headers、request body 全文或環境變數
-
.gitignore、.worktreeinclude的變更經人工確認
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| pre-commit 有效 | 28.3.2 的假 Token 測試 | Commit 被擋下 | 重新安裝 hook |
| 工作目錄無憑證 | gitleaks dir . -v | no leaks found | 移除並輪替 |
| 憑證檔權限 | ls -l 或 icacls | 僅擁有者可讀寫 | chmod 600 或調整 ACL |
.worktreeinclude 安全 | 檢視檔案內容 | 不含正式或 UAT 憑證檔 | 移除並輪替已暴露憑證 |
| Orca 為最新版 | 檢查版本(第二十九章) | 不低於 v1.4.221 | 更新 Orca |
28.4 遠端與行動端存取控制
概念說明
遠端與行動端功能把「控制 Orca 的能力」延伸到其他機器與裝置。三種模式的風險面不同:
| 模式 | 誰擁有執行環境 | 憑證形式 | 外洩時的影響 | 撤銷方式 |
|---|---|---|---|---|
| SSH Worktrees | 筆電上的 Orca;遠端主機執行 Worktree 與終端機 | SSH 金鑰(可為 FIDO2、Kerberos) | 遠端主機遭入侵 | 移除 authorized_keys、輪替金鑰 |
| Remote Orca Server(Beta) | 遠端主機擁有完整 Orca 執行環境 | 每個 client 一組獨立、可撤銷的 Token(由存取連結配對取得) | 對方可操作伺服器上所有專案、終端機與 Agent | Shared Server Access 中刪除該授權,連線立即中斷 |
| Mobile Companion(Beta) | 桌面 Orca 為唯一真實來源 | 一次性配對碼換得裝置 Token | 可回覆 Agent、Commit、啟動 Agent、切換帳號 | 桌面端清除已配對裝置後,手機顯示 Authentication failed |
📌 查證狀態:官方文件明確記載|來源:SSH worktrees、Remote Orca Servers、Mobile companion
28.4.1 SSH 安全設定
重點控制
- 主機金鑰驗證:Orca 依 OpenSSH known_hosts 驗證;預設首次連線會接受並記住指紋,在 OpenSSH config 設定
StrictHostKeyChecking yes可拒絕未知主機。金鑰變更會在要求密碼前即被拒絕。 - 硬體金鑰與企業 SSO:
ed25519-sk、ecdsa-sk等 FIDO2 金鑰與GSSAPIAuthentication yes(Kerberos)會改由系統 OpenSSH 處理。 - 通行碼:只保存在記憶體,關閉 Orca 即清除;除非有明確需求,不要延長 TTL。
- 反向控制:Allow this host’s orca CLI to control Orca 預設關閉,維持關閉。
- Managed Orca server:首次連線時 Orca 會在主機上安裝其管理的伺服器;若使用 Node.js 鏡像站,Orca 會以固定 checksum 驗證下載內容。
範例:嚴格的 OpenSSH 設定(~/.ssh/config)
Host build-01
HostName build-01.corp.example
User svc-orca
IdentityFile ~/.ssh/id_ed25519_sk
StrictHostKeyChecking yes
UserKnownHostsFile ~/.ssh/known_hosts_corp在 Settings → SSH → Add Target 中可用 OpenSSH config 選擇器匯入此主機。
28.4.2 Remote Orca Server 存取控制
操作步驟
- 只在私有網路路徑上使用:同一 Tailscale tailnet、WireGuard、受信任 LAN 或 SSH 轉送。不要把 Orca 連接埠直接轉發到公網。
- 在伺服器端 Settings → Remote Orca Servers → Advertise this app as a server → New Link,連線位址選 Tailscale 位址(通常為
100.x.y.z),不要選127.0.0.1或萬用位址。 - 存取連結視同密碼,只傳給預定的 client;以
orca serve service install安裝的服務不會把配對連結寫進 log。 - 定期檢視 Shared Server Access,刪除不再使用的授權。
- 以 Tailscale ACL 限制只有特定群組能連到伺服器連接埠。
範例:Tailscale ACL(教學示例(非官方),HuJSON 格式)
{
"groups": {
"group:orca-users": ["alice@example.com", "bob@example.com"]
},
"tagOwners": {
"tag:orca-server": ["group:orca-users"]
},
"acls": [
{
"action": "accept",
"src": ["group:orca-users"],
"dst": ["tag:orca-server:6768"]
}
]
}📌 查證狀態:連接埠 6768 為 Orca 文件中
orca serve --port與行動端預設埠的範例值;ACL 語法以 Tailscale 官方文件 為準(教學推論)。
28.4.3 Mobile Companion 存取控制
重點控制
- 配對碼為一次性且數分鐘內過期;配對後手機取得裝置 Token。
- 使用 Orca Relay 配對時需要登入 Orca 帳號;LAN 配對需要手機與桌面可互相連線。
- 手機可執行的動作不只是「看」:回覆 Agent、附加檔案、Source Control 的 Stage 與 Commit、啟動 Agent、建立 Workspace、切換 Agent 帳號、使用 Codex reset credit。治理上應把手機視為具寫入權限的終端。
- 推播通知會在 Agent 完成時送達手機,鎖定畫面可能顯示內容摘要。
企業建議(教學示例(非官方))
| 控制 | 做法 |
|---|---|
| 裝置管理 | 僅允許 MDM 納管、啟用裝置鎖的手機配對 |
| 通知內容 | 作業系統層級設定鎖定畫面不顯示通知內容 |
| 高監理專案 | 不配對行動端,或僅配對無 Commit 需求的觀察用途 |
| 遺失處理 | 在桌面端清除已配對裝置,確認手機出現 Authentication failed,再輪替該桌面上的 Agent 帳號 |
| 盤點 | 每月列出各桌面的已配對裝置與 Remote Server 授權 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| SSH 嚴格主機驗證 | ssh -G build-01 輸出中的 stricthostkeychecking | 為 true | 修正 ~/.ssh/config |
| 未知主機被拒 | 對新主機首次連線測試 | 連線被拒,需人工確認指紋 | 檢查 OpenSSH config 是否套用 |
| 伺服器未暴露公網 | 從外部網路執行 nc -vz <公網IP> 6768 | 連線失敗 | 移除連接埠轉發、檢查防火牆 |
| Tailscale 連線限制 | 以不在 group:orca-users 的裝置執行 tailscale ping <伺服器> 並連線 6768 | 無法連到 6768 | 修正 ACL |
| 授權盤點 | Settings → Remote Orca Servers → Shared Server Access | 授權數與核准清單一致 | 刪除多餘授權 |
| 撤銷有效 | 撤銷測試 client 的授權 | 該 client 立即斷線 | 回報並停止使用 Remote Server |
| 行動端撤銷 | 清除已配對裝置後開啟手機 App | 顯示 Authentication failed 或要求重新配對 | 確認清除的是正確桌面 |
28.5 Telemetry 與資料外洩防護
概念說明
Orca 的 Telemetry 是匿名產品使用統計:以本機隨機 ID 為鍵,附帶 Orca 版本、作業系統、CPU 架構、粗略 OS 版本與發布頻道;事件類型包括 App 開啟、新增 repo 或 Workspace 的方式、啟動哪一類 Agent、粗略錯誤分類、少數白名單設定的切換。官方明確表示不傳送檔案內容、Prompt、Agent 輸出、終端機內容、repo 名稱、分支名稱、URL、路徑、commit 訊息、原始錯誤訊息或 stack trace;也不收集 IP(僅由請求推得國家)。資料送往 PostHog Cloud 美國區。逐筆錯誤細節只存在本機診斷檔,除非你主動分享診斷包。
📌 查證狀態:官方文件明確記載|來源:Privacy & Telemetry
關閉 Telemetry 的三種方式(任一即可,可疊加)
| 方式 | 操作 | 持久性 |
|---|---|---|
| App 設定 | Settings → Privacy → 關閉 Share anonymous usage data | 立即生效且持久 |
DO_NOT_TRACK=1 | 啟動 Orca 前設定環境變數 | 僅影響該次啟動;移除後恢復已儲存的偏好 |
ORCA_TELEMETRY_DISABLED=1 | 啟動 Orca 前設定環境變數 | 同上,Orca 專屬開關 |
操作步驟:企業統一關閉
每台工作站在 Settings → Privacy 關閉 Share anonymous usage data。
另以環境變數作為第二道保險,避免使用者重灌後忘記設定:
# Windows(使用者層級,可由 GPO 或 Intune 派送) [Environment]::SetEnvironmentVariable('ORCA_TELEMETRY_DISABLED', '1', 'User')# Linux(寫入登入 shell 設定後重新登入) echo 'export ORCA_TELEMETRY_DISABLED=1' >> ~/.profile# macOS(GUI App 不一定讀取 shell 設定;launchctl 設定於重開機後失效,需由 MDM 或登入項目重新設定) launchctl setenv ORCA_TELEMETRY_DISABLED 1完全結束 Orca 後重新啟動,使環境變數生效。
對
orca serve無頭伺服器,在服務定義或啟動 shell 中同樣設定環境變數。
📌 查證狀態:三種關閉方式為官方文件明確記載;各作業系統設定環境變數的方式(尤其 macOS
launchctl setenv)屬教學推論,請於貴組織環境實測。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| App 設定已關閉 | Settings → Privacy | Share anonymous usage data 為關閉 | 重新關閉 |
| 環境變數已設定(Windows) | [Environment]::GetEnvironmentVariable('ORCA_TELEMETRY_DISABLED','User') | 輸出 1 | 重新設定並重啟 Orca |
| 環境變數已設定(macOS) | launchctl getenv ORCA_TELEMETRY_DISABLED | 輸出 1 | 重新設定並重啟 Orca |
| 環境變數已設定(Linux) | 新登入 shell 執行 printenv ORCA_TELEMETRY_DISABLED | 輸出 1 | 確認寫入正確的 profile |
| 網路層無 Telemetry 流量 | 在企業 Proxy 或防火牆紀錄中搜尋該工作站對 PostHog 網域的連線 | 關閉後無新連線 | 檢查 Orca 是否以含環境變數的工作階段啟動 |
📌 查證狀態:網路層驗證為教學推論;PostHog 的實際網域請以 Proxy 紀錄觀察為準,不要僅依本書推測封鎖清單。
資料外洩防護(DLP):比 Telemetry 更大的資料流
關閉 Telemetry 只處理了最小的一條資料流。實務上更需要控制的是下列流向:
| 資料流 | 風險 | Orca 相關設定或功能 | 建議控制 |
|---|---|---|---|
| 程式碼與 Prompt 送往 Agent 模型供應商 | 機敏程式碼或資料進入第三方服務 | Settings → Agents 可停用未核准的 Agent,讓啟動選單只顯示核准清單 | 只核准已簽企業合約的供應商;確認資料保留政策 |
| 公開 Artifact 連結 | HTML 或 Markdown 公開於網路 | Allow publishing public artifact links 預設關閉(裝置層級開關) | 維持關閉;若曾開啟,以 orca artifacts list --json 盤點並刪除 |
| 終端機剪貼簿寫入(OSC 52) | 遠端 TUI 可寫入本機剪貼簿 | Settings → Terminal → Allow TUI Clipboard Writes(預設開啟) | 高監理環境關閉 |
| 瀏覽器流量經 SSH 主機 | 流量從遠端主機出口 | Settings → Browser → Browse through SSH workspace hosts | 依網路政策決定開關 |
| 語音輸入 | 雲端模型會上傳語音 | Settings → Voice 可選本機模型 | 優先選本機語音模型 |
| 行動端推播與畫面 | 鎖定畫面顯示內容 | 通知設定 | 見 28.4.3 |
| 診斷包 | 本機診斷檔含逐筆錯誤細節 | 僅在主動分享時送出 | 分享前由資安檢視內容 |
| Design Mode 與截圖 | 畫面中的個資進入 Agent Context | - | 使用遮罩後的測試資料 |
範例 Prompt:讓 Agent 協助盤點本機的資料外洩設定
請只做唯讀檢查,不要修改任何設定:
1. 執行 orca artifacts list --json,列出所有已發布的 artifact(名稱與建立時間)。
2. 列出 .worktreeinclude 的內容。
3. 執行 gitleaks dir . -v 並回報結果摘要。
輸出一張表:檢查項目|結果|是否需要人工處理。不要在輸出中顯示任何憑證值。🧑⚖️ 人工 Review 要點
- Agent 只執行了唯讀指令(檢查其終端機紀錄)
- artifact 清單中每一項都確認是否仍需公開
- gitleaks 結果中任何發現都依 28.3.4 處理
- Agent 的輸出中沒有顯示憑證值
28.6 稽核與合規對應
概念說明
稽核的本質是「能否證明控制有在運作」。AI 輔助開發增加了兩個稽核問題:哪些程式碼是 AI 產生的,以及誰驗證並核准了它。Orca 與 git 生態系可提供以下證據來源:
| 證據 | 來源 | 保存方式 | 注意事項 |
|---|---|---|---|
| 變更內容與作者 | git commit、PR | 遠端程式碼平台 | 建議 commit 訊息或 PR 欄位標記 AI 參與 |
| 審查與核准 | PR review、CODEOWNERS | 遠端程式碼平台 | 需啟用分支保護才具強制性 |
| AI 產出行標記 | Orca Attribution | 僅存在本機,不寫入 git | 需從 Diff 工具列匯出 diff metadata 才能留存 |
| 驗收證據 | 驗收紀錄、測試 log、掃描報告 | repo 的 docs/acceptance/、CI artifact | 見 22.7 節 |
| 任務進度與決策 | Worktree Checkpoint、交接紀錄 | Orca(Checkpoint)、repo(交接紀錄) | Checkpoint 為狀態欄位,重要內容應同步寫入 repo |
| Agent 對話 | 各 Agent 的 Session History;orca search 可搜尋對話 | 本機或伺服器 | 保存期限依各 CLI;可能含機敏內容,存取需控管 |
| 權限設定 | Settings → Agents、SSH、Remote Orca Servers | 本機 | 以截圖或設定匯出做定期留存 |
📌 查證狀態:Attribution 僅存在本機且可匯出、
orca search可搜尋對話為官方文件明確記載|來源:Attribution、CLI reference
合規控制對應表
下表將本書的控制措施對應到 ISO/IEC 27001:2022 附錄 A 控制項與台灣常見法規框架。本表為教學推論,不構成法律或稽核意見;實際適用條文請由貴組織法遵與資安單位確認。
| 控制領域 | ISO/IEC 27001:2022 附錄 A | 台灣法規或指引(參考) | 本書對應做法 | 稽核證據 |
|---|---|---|---|---|
| 存取控制與最小權限 | 5.15 存取控制、8.2 特權存取權限 | 資通安全管理法相關子法之存取控制要求 | 權限模式基準(28.2)、審查角色唯讀(21.1) | Settings 截圖、行程命令列檢查紀錄 |
| 鑑別資訊管理 | 5.17 鑑別資訊、8.5 安全鑑別 | 同上 | 憑證盤點與輪替(28.3)、FIDO2 SSH(28.4.1) | 憑證清冊、輪替紀錄、檔案權限檢查輸出 |
| 原始碼存取 | 8.4 原始碼之存取 | - | 分支保護、CODEOWNERS(21.3) | 分支保護設定、PR 紀錄 |
| 安全開發生命週期 | 8.25 安全開發生命週期、8.28 安全程式設計 | 金管會「金融業運用人工智慧(AI)指引」之人類監督精神 | 三層驗證模型(22.2)、Diff 審查準則(22.3) | 驗收紀錄、SAST 報告 |
| 變更管理 | 8.32 變更管理 | 金融機構既有變更管理規範 | 關卡 G0~G4(20.1)、RACI(21.4) | PR 核准、驗收紀錄簽核欄 |
| 測試 | 8.29 開發及驗收中之安全測試 | - | 測試證據 E1~E5(22.4) | 測試 log、紅綠驗證紀錄 |
| 資料外洩防護 | 8.12 資料洩露預防 | 個人資料保護法 | DLP 資料流控制(28.5)、Prompt 規範(20.5.5) | Agent 核准清單、artifact 盤點紀錄 |
| 雲端與第三方服務 | 5.19 供應者關係中之資訊安全、5.23 使用雲端服務之資訊安全 | 金融機構作業委託他人處理內部作業制度及程序辦法 | 核准 Agent 供應商清單、Telemetry 關閉(28.5) | 供應商評估、合約、Telemetry 設定驗證 |
| 日誌與監控 | 8.15 存錄、8.16 監視活動 | - | 證據來源表(本節) | CI 紀錄、Attribution 匯出 |
| 組態管理 | 8.9 組態管理 | - | 企業設定基準(第六章 6.9、本章 28.2) | 定期設定盤點紀錄 |
| 端點與行動裝置 | 8.1 使用者端點裝置 | - | 行動端控制(28.4.3) | MDM 清單、配對裝置盤點 |
範例:每月稽核腳本(找出缺少驗收紀錄的合併)
以下腳本假設 PR 合併訊息含需求編號(例:ORD-1423),並檢查 docs/acceptance/ 是否有對應紀錄(教學示例(非官方)):
#!/usr/bin/env bash
# scripts/audit-acceptance.sh 2026-10-01 2026-10-31
since="$1"; until="$2"
git log main --merges --since="$since" --until="$until" --pretty='%h %s' \
| grep -oE '[A-Z]+-[0-9]+' | sort -u | while read -r id; do
if [ ! -f "docs/acceptance/${id}.md" ]; then
echo "MISSING ACCEPTANCE: ${id}"
fi
done
echo "audit done"✅ 驗證方式
先驗證腳本本身:建立一個含
TEST-9999的測試合併 commit 但不建立驗收紀錄,執行:scripts/audit-acceptance.sh 2026-10-01 2026-10-31預期輸出(示意):
MISSING ACCEPTANCE: TEST-9999 audit done判讀:腳本能抓到刻意缺漏後,才用於正式稽核。正式執行時每一筆
MISSING ACCEPTANCE都需補件或說明。
範例 Prompt:請 AI 草擬合規對應,並要求可驗證性
請依 docs/security/threat-model.md 與本 repo 的 CI 設定,草擬「AI 輔助開發控制對應表」。
欄位:控制項|ISO/IEC 27001:2022 附錄 A 編號|本 repo 中的實作位置(檔案路徑或設定名稱)|證據產生方式(指令)。
規則:實作位置必須是 repo 中真實存在的檔案;找不到實作的控制項標記「缺口」,不要假設已實作。
不要引用你無法確定編號的法規條文,改寫「待法遵確認」。🧑⚖️ 人工 Review 要點
- 每個「實作位置」用 22.6 節的路徑存在檢查腳本驗證
- ISO 附錄 A 編號抽查至少三個,確認與 2022 版標準一致
- 所有「缺口」都已建立追蹤項目
- 台灣法規相關欄位經法遵單位確認,未經確認者保留「待法遵確認」
⚠️ 注意事項:Remote Orca Server 與 Mobile Companion 目前皆標示為 Beta。高監理產業若要納入正式流程,應在風險評估中明列 Beta 狀態,並以 28.4 節的補強控制作為核准條件。
28.7 本章 Review 與驗證清單
- 能說明「Worktree 是工作隔離,不是安全隔離」並舉出兩個理由
- 已為自己的專案完成威脅模型,並由資安人員簽核
- 已在 Settings → Agents 設定符合組織基準的權限模式,並以行程命令列驗證實際啟動參數
- 已確認高監理專案關閉 Folder trust 自動回應,且 SSH 主機的 orca CLI 反向控制維持關閉
- 已安裝 gitleaks pre-commit hook,並以假 Token 驗證 Orca 的 Commit 會被擋下
- 已檢查
~/.copilot/config.json等憑證檔權限,且 Orca 版本不低於 v1.4.221 -
.worktreeinclude不含正式或 UAT 憑證檔 - Remote Orca Server 只在私有網路使用,已驗證公網無法連線,並完成一次授權撤銷演練
- 行動端配對裝置已盤點,並完成一次遺失裝置撤銷演練
- 已以 App 設定與環境變數雙重關閉 Telemetry(若組織要求),並完成驗證
- 已建立核准 Agent 清單,並在 Settings → Agents 停用未核准者
- 已建立合規對應表,並以稽核腳本驗證每筆合併都有驗收紀錄
第二十九章 系統維護與疑難排解
本章把 Orca 視為一套「每天都在變動的企業桌面基礎設施」來維運:先建立版本與發版節奏的管理方式,再說明升級時必須留意的相容性變更、應用資料的備份與還原、Log 收集標準作業,最後提供一套可以直接照著走的故障排除決策流程。所有操作都附上「✅ 驗證方式」,讓 IT/平台團隊可以把本章直接改寫成內部 Runbook。
📌 查證狀態:官方文件明確記載|來源:Troubleshooting & FAQ、Install、Troubleshooting GitHub errors;資料目錄與 Log 檔名部分為依官方原始碼延伸(教學推論),於各節另行標示。
29.1 版本管理與發版節奏
29.1.1 發版通道與更新機制
Orca 是 Electron 桌面應用程式,預設會自動更新並追蹤 Stable 通道。官方另外提供 RC(Release Candidate) 建置,通常幾乎每天都有,新功能會先在 RC 出現。RC 沒有永久性的 App 內訂閱開關,而是靠「按住修飾鍵點擊 Check for Updates」來單次取得:
| 操作位置 | 修飾鍵 | 效果 | 企業建議用途 |
|---|---|---|---|
| Settings → General → Updates,或 App/Help 選單 | 一般點擊 | 檢查並安裝最新 Stable | 一般工程師 |
| 同上 | Shift+點擊 | 包含最新 RC 預覽版 | 平台組搶先驗證(Ring 0) |
| 同上 | Cmd+點擊(macOS)/Ctrl+點擊(Windows、Linux) | 最新 perf 標記的預覽版 | 效能問題回報者協助驗證修正 |
| 同上(僅 macOS) | Option+點擊 | 選擇通過相容性檢查的本機 macOS 建置 | 內部自行建置的特殊情境 |
各平台的安裝與更新方式也不同,企業在制定軟體派送策略時要分開處理:
| 平台/套件 | 更新方式 | 維運重點 |
|---|---|---|
| macOS 官方安裝檔(Apple Silicon、Intel) | App 內自動更新 | 已簽章與公證,首次啟動仍可能跳出確認 |
| macOS Homebrew Cask | brew upgrade --cask orca | Cask 每次 Stable 發版自動 bump,只追 Stable |
| Windows 安裝程式 | App 內自動更新 | orca CLI 為原生程式,不需 Visual C++ Redistributable |
| Linux AppImage | App 內自動更新 | 想讓 Orca 自行更新就選這個 |
| Linux .deb/.rpm | App 提示有新版,並給出套件管理指令 | 執行該指令前要先關閉 Orca;CLI 名稱為 orca-ide |
| 任何平台舊版 | 從 GitHub Releases 下載 | 回到舊版時,Orca 不會強制降級 Worktree 資料 |
📌 查證狀態:官方文件明確記載|來源:Install、Settings reference
29.1.2 發版節奏的實際量測
舊版手冊撰寫時對應 v1.4.150(2026-07-22)。本版對應 v1.4.244(2026-10-29)。兩者相隔約 14 週,版本號前進了 94 號;Release 摘要顯示中間有部分號碼跳號或作廢(例如 v1.4.157 tag 作廢、內容改以 v1.4.158 發布;v1.4.172 建置失敗、修正併入 v1.4.173),另外還有大量 -rc.N 預覽 tag。換算下來,Stable 平均每週約 6~7 版,「近乎每日發版」的判斷依然成立。
📌 查證狀態:依官方說明延伸(教學推論)|計算依據:GitHub Releases 的 tag 清單與版本號差距;讀者可用下方指令自行重算。
這個節奏帶來三個企業維運上的直接後果:
- 每週都可能有行為改變:例如權限下拉選單從 Settings → Chat 移到 Settings → Agents(v1.4.241)、SSH 主機改跑 managed Orca server(v1.4.224)。內部教材與截圖需要定期更新。
- 「問題是否已修好」與版本號高度相關:排錯時第一步永遠是確認版本號,再對照 Release Notes 與 GitHub Issues。
- Orca 與 Agent CLI 版本各自獨立:Orca 更新不代表 Claude Code、Codex、gh 也跟著更新,反之亦然;但兩者之間存在相依(例如 Codex chat 需 Codex ≥ 0.136.0,見 29.2)。
29.1.3 企業發版環(Release Ring)設計
flowchart LR
REL["官方 Stable 發布"] --> R0["Ring 0 平台組<br/>當日或 RC 搶先"]
R0 --> CHK{"升級檢查清單<br/>全數通過?"}
CHK -->|"是"| R1["Ring 1 試點團隊<br/>發布後 2~3 個工作天"]
CHK -->|"否"| HOLD["暫停推廣<br/>回報 Issue 並記錄"]
R1 --> OBS{"一週內無 P1 問題?"}
OBS -->|"是"| R2["Ring 2 全體工程師<br/>允許自動更新"]
OBS -->|"否"| HOLD
HOLD --> NEXT["等待下一個 Stable 版重新評估"]如何閱讀此圖:從左到右是新版本在企業內擴散的路徑。每一個菱形都是「關卡」,只有通過才能進入下一個環。任何一關失敗都會回到「暫停推廣」,等下一個 Stable 版重新走一次。因為 Orca 幾乎每天發版,「等下一版」的成本很低,比在全公司硬推一個有問題的版本划算。
📌 查證狀態:教學示例(非官方)|官方文件未記載企業層級的「停用自動更新」政策開關;若需鎖版,請以軟體派送工具(例如 Intune、Jamf、套件庫)管理安裝來源,並以本節驗證方式確認實際版本。
29.1.4 版本盤點指令
範例:在各平台查出「目前安裝的 Orca 版本」與「官方最新版本」。
# 官方最新 Stable 與發布時間(需已登入 gh)
gh release view --repo stablyai/orca --json tagName,publishedAt,isPrerelease
# 列出最近 10 個 Release(含 RC),觀察節奏
gh release list --repo stablyai/orca --limit 10
# macOS:讀取已安裝 App 的版本
defaults read /Applications/Orca.app/Contents/Info.plist CFBundleShortVersionString
# macOS(Homebrew 安裝者)
brew info --cask orca
# 相依 Agent CLI 的版本(各自獨立管理)
claude --version
codex --version
gh --version# Windows:從已安裝程式清單找出 Orca 版本(使用者層級與電腦層級都查)
Get-ItemProperty `
HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*, `
HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\* `
-ErrorAction SilentlyContinue |
Where-Object { $_.DisplayName -like '*Orca*' } |
Select-Object DisplayName, DisplayVersion, InstallLocation✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 已知官方最新版 | gh release view --repo stablyai/orca --json tagName | 顯示如 v1.4.244 或更新的 tag | 先執行 gh auth status 確認登入 |
| 本機版本可查 | 上方 macOS 或 PowerShell 指令 | 回傳版本字串,例如 1.4.244 | 確認安裝路徑;Linux 改用套件管理工具查詢 |
| 與 Ring 政策一致 | 比對本機版本與內部「核准版本清單」 | 版本號不低於核准下限 | 依 29.2 升級檢查清單升級 |
| Agent CLI 版本可查 | codex --version 等 | 回傳版本字串 | CLI 未安裝或不在 PATH,見 29.5 |
⚠️ 注意事項:gh release view 預設回傳的是最新的非預覽版;若團隊在 Ring 0 使用 RC,請改用 gh release list 一併查看 Pre-release 標記。
29.2 升級與相容性注意事項
29.2.1 v1.4.150 之後必須知道的相容性變更
下表從 v1.4.151~v1.4.244 的 Release Notes 中,挑出會直接影響企業維運的變更。升級跨越多個版本時,請把區間內每一列都讀過一次。
| 版本 | 變更 | 對維運的影響 | 建議動作 |
|---|---|---|---|
| v1.4.212 | 修正 Codex 0.157 以上在 Orca 管理的帳號 home 中出現 socket 路徑超過 SUN_LEN 的錯誤 | 使用新版 Codex 時舊 Orca 會報錯 | Orca 至少升到 v1.4.212,不需手動搬移帳號 |
| v1.4.214 | Profile 儲存遷移至 SQLite;內建 ripgrep 與 headless Bun | 首次啟動會轉換資料;JSON 與 SQLite 不一致時會詢問要用哪份 | 升級前先備份資料目錄(29.3) |
| v1.4.217~218 | 每個 Codex tab 預設使用獨立 server;新增「Run each Codex terminal on its own server」開關 | Codex desktop、codex agents 看不到 Orca 內的 session;記憶體用量增加 | 需共享時於 Settings → Agents 關閉,或設定 ORCA_CODEX_ISOLATE=0 |
| v1.4.219 | 「Trust the folder when Orca starts an agent」預設開啟;Windows 的 orca 改為原生程式 | Agent 啟動時自動略過資料夾信任提示 | 高監理環境評估是否關閉(Settings → Agents) |
| v1.4.220~221 | 更新後啟用新的背景 terminal service;舊 terminal 仍留在舊服務 | 升級後新舊 terminal 行為可能不同 | 升級後關閉並重開所有 terminal |
| v1.4.221 | 安全修正:v1.4.219~220 可能讓 ~/.copilot/config.json(含 token)權限過寬;Windows Codex 改用 ~/.codex | 曾使用這兩版者有憑證外洩風險;Windows 可能需重新信任資料夾與重新加入 MCP | 檢查並收緊檔案權限、評估輪替 token(見第二十八章) |
| v1.4.224 | SSH 主機改跑 managed Orca server(Settings → Managed servers) | 有開啟 terminal 的主機切換時 terminal 會重啟;無法執行者會顯示原因並拒絕連線 | 選在非尖峰時段升級;保留可連線的舊版作為退路 |
| v1.4.227 | Codex chat 需 Codex ≥ 0.136.0 | Codex CLI 過舊時 chat 無法使用 | 同步升級 Codex CLI |
| v1.4.230 | SSH 主機上的 orca CLI 控制權,未設定者遷移為關閉 | 遠端腳本呼叫 orca 會失敗 | 需要時於 Settings → SSH Hosts → Advanced Connection 個別開啟 |
| v1.4.232~240 | 多項 Native Chat 新功能需 paired/SSH 主機同步更新 Orca | 桌面新、主機舊時功能缺漏,舊主機遺失的內容無法還原 | 桌面與遠端主機的 Orca 版本一起升級 |
| v1.4.239 | Browser profiles 預設 Shared;Recover server… 可清除 stale lock | 清除 lock 前若有其他機器共用 home 會造成衝突 | 確認無其他機器使用同一 home 後再 Recover |
| v1.4.241 | 權限下拉從 Settings → Chat 移到 Settings → Agents;拒絕在 OpenCode 2.0.14/2.0.15/2.0.17/2.0.18 上選模型 | 內部教材路徑過時;特定 OpenCode 版本無法選模型 | 更新教材;OpenCode 改用其他版本 |
| v1.4.242 | Claude subagent 導覽預設開啟,會在各 Claude 設定資料夾的 keybindings.json 加入一個快捷鍵 | 會改動使用者的 Claude 設定檔 | 已執行的 Claude session 需重新啟動;有集中管理 Claude 設定者需知會 |
| v1.4.243 | 新的 terminal host;Worker heartbeat 預設 5 分鐘 | 舊 terminal 停留在舊 host 直到關閉 | 升級後重開 terminal;Orchestration 監控門檻依新預設調整 |
| v1.4.244 | 沿用 v1.4.243 的 terminal host;部分修正需主機重啟才生效;iOS 改指向 App Store,移除 TestFlight;Worktree 位置可用 ~ 代表家目錄 | 不必重開 terminal,但部分終端修正要重開機才看得到 | 行動裝置治理文件改為 App Store 版本 |
📌 查證狀態:官方文件明確記載|來源:GitHub Releases(v1.4.212~v1.4.244 各版 Release Notes)、Troubleshooting & FAQ
29.2.2 理解 terminal host 世代
多個版本(v1.4.220、v1.4.221、v1.4.241、v1.4.243)都提到「更新後啟動新的背景 terminal service/host,舊 terminal 留在舊服務」。這代表:升級完成後,畫面上已開啟的 terminal 並沒有享受到新版修正。如果升級是為了修某個終端問題,請關閉該 terminal 後重新開啟再驗證,否則會誤判「升級沒效」。
📌 查證狀態:官方文件明確記載|來源:GitHub Releases(v1.4.243、v1.4.244)
29.2.3 升級檢查清單
以下清單可直接貼進內部變更單。每一步都對應一個可觀察的結果。
升級前
- 記錄目前版本與目標版本(29.1.4 指令),並讀完兩者之間的 Release Notes 與 29.2.1 對照表。
- 確認所有 Worktree 的未提交變更已 commit 或匯出 patch(29.3.3)。
- 關閉 Orca 後備份資料目錄(29.3.2)。
- 確認 Agent CLI 與 gh 的版本符合新版需求(例如 Codex ≥ 0.136.0)。
- 若有 SSH/paired 主機,排定主機端 Orca server 一併升級的時段。
升級中
- Ring 0 機器以 Settings → General → Updates → Check for Updates 升級(或用派送工具安裝指定版本)。
- 若跳出「Orca asks which profile copy to use」,除非有特殊理由,選擇 Use SQLite (Recommended)。
- 升級後關閉所有舊 terminal 再重新開啟。
升級後煙霧測試
- 開啟一個既有 Repository,確認 Worktree 清單完整。
- 建立一個新 Worktree,啟動一個 Agent,送出一個無副作用的 Prompt(例如「列出本 repo 的頂層目錄」)。
- 開啟 Diff Viewer,對任一行加一則 Review Note。
- 執行
orca status --json,確認 CLI 能連到執行中的 Orca。 - 開啟 Source Control/PR 面板,確認 GitHub 狀態正常更新。
- 若有 SSH 主機,於 Settings → SSH Hosts 確認主機狀態與 managed server 版本。
範例:升級前後執行的最小驗證腳本(macOS/Linux)。
#!/usr/bin/env bash
set -euo pipefail
echo "== Orca runtime =="
orca status --json || echo "orca CLI 無法連線,請見 29.5"
echo "== Git worktrees =="
git -C "$HOME/src/myapp" worktree list
echo "== GitHub auth =="
gh auth status -h github.com
echo "== Agent CLIs =="
claude --version || true
codex --version || true✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 版本已更新 | 29.1.4 版本盤點指令 | 顯示目標版本 | 檢查派送工具或重新執行 Check for Updates |
| Runtime 正常 | orca status --json | 回傳 JSON,無錯誤 | Settings → General → Orca CLI 重新註冊 |
| Worktree 完整 | git worktree list 與 Orca 側邊欄比對 | 兩者一致 | 先別刪資料,依 29.3 還原備份比對 |
| Agent 可啟動 | 於新 Worktree 啟動 Agent | 看到 Agent 回應 | 依 29.5 的「Agent 無法啟動」流程 |
| 新 terminal 生效 | 關閉並重開 terminal 後重測原問題 | 問題消失或行為符合新版說明 | 若需 host 重啟(v1.4.244 說明),重開機後再測 |
❌ 常見錯誤:升級後直接在舊 terminal 裡驗證新修正,得到「升級無效」的錯誤結論。
💡 小技巧:把 29.2.1 對照表維護成內部 Wiki 的「累積相容性清單」,每週由平台組追加新列,升級跨越多版時只要讀對應區間即可。
29.3 備份與還原
29.3.1 需要備份的四類資料
| 類別 | 內容 | 位置 | 備份責任 | 敏感度 |
|---|---|---|---|---|
| 程式碼與分支 | 已 commit 的程式碼、各 Worktree 分支 | 遠端 Git 託管平台 | 既有 Git 備份機制 | 依專案而定 |
| Worktree 未提交變更 | 尚未 commit 的修改與未追蹤檔 | 各 Worktree 目錄 | 工程師本人(下班前) | 依專案而定 |
| Orca 應用資料 | Profile 狀態、版面、設定、Session 中繼資料 | 使用者資料目錄(見下) | IT/工程師 | 中高(含帳號中繼資料與瀏覽器 Profile) |
| Agent CLI 設定與憑證 | ~/.claude、~/.codex、gh 登入 | 使用者家目錄 | 依各 CLI 官方方式 | 高(含 token) |
Repository 層級的設定(orca.yaml、.worktreeinclude、Hooks 腳本)應該 commit 進 Git,因此跟著程式碼一起被備份,不必另外處理;這也是第二章與第九章建議把共用設定放進 repo 的原因之一。
29.3.2 Orca 應用資料目錄
官方文件只描述「Help → Open Logs」與「profile 有 JSON 與 SQLite 兩份副本」,沒有列出完整路徑。依官方原始碼,Orca 使用 Electron 的 userData 目錄,預設位置如下:
| 作業系統 | 使用者資料目錄 | 主要內容(依原始碼) |
|---|---|---|
| Windows | %APPDATA%\Orca | orca-profile-index.json、profiles\<id>\profile-state.db、profiles\<id>\orca-data.json、logs\ |
| macOS | ~/Library/Application Support/Orca | 同上 |
| Linux | ~/.config/Orca | 同上 |
| 所有平台 | ~/.orca/keybindings.json | 已自訂的快捷鍵覆寫 |
📌 查證狀態:依官方說明延伸(教學推論)|來源:官方原始碼 logs-directory.ts、profile-state-storage-paths.ts;
~/.orca/keybindings.json見 Settings reference。檔名屬內部實作,未來版本可能調整,請以實際目錄內容為準。
⚠️ 注意事項:資料目錄中也可能包含內建瀏覽器的 Cookie 與登入狀態。備份檔必須視為機敏資料:加密保存、限制存取、設定保存期限,且不可上傳到公開位置或附在 Issue 上。
29.3.3 備份操作步驟
- 完全結束 Orca(macOS 用 Cmd+Q;Windows、Linux 從選單 Quit),避免 SQLite 檔案在寫入中被複製。
- 匯出每個 Worktree 的未提交變更(見下方指令)。
- 壓縮使用者資料目錄,可排除 Chromium 快取資料夾以縮小體積。
- 將備份檔移到加密的公司儲存空間,記錄日期、Orca 版本與機器名稱。
範例:Windows(PowerShell)
$stamp = Get-Date -Format 'yyyyMMdd-HHmm'
$src = Join-Path $env:APPDATA 'Orca'
$dst = Join-Path $env:USERPROFILE "Backups\orca-userdata-$stamp.zip"
New-Item -ItemType Directory -Force -Path (Split-Path $dst) | Out-Null
$items = Get-ChildItem $src -Force |
Where-Object { $_.Name -notin @('Cache', 'Code Cache', 'GPUCache') }
Compress-Archive -Path $items.FullName -DestinationPath $dst
Copy-Item "$env:USERPROFILE\.orca\keybindings.json" `
"$env:USERPROFILE\Backups\keybindings-$stamp.json" -ErrorAction SilentlyContinue
Write-Output "Backup written to $dst"範例:macOS(bash)
stamp=$(date +%Y%m%d-%H%M)
mkdir -p "$HOME/Backups"
tar --exclude='Cache' --exclude='Code Cache' --exclude='GPUCache' \
-czf "$HOME/Backups/orca-userdata-$stamp.tgz" \
-C "$HOME/Library/Application Support" Orca
cp "$HOME/.orca/keybindings.json" "$HOME/Backups/keybindings-$stamp.json" 2>/dev/null || true範例:Linux(bash)
stamp=$(date +%Y%m%d-%H%M)
mkdir -p "$HOME/Backups"
tar --exclude='Cache' --exclude='Code Cache' --exclude='GPUCache' \
-czf "$HOME/Backups/orca-userdata-$stamp.tgz" -C "$HOME/.config" Orca範例:匯出所有 Worktree 的未提交變更與分支(bash)
repo="$HOME/src/myapp"
out="$HOME/Backups/wt-$(date +%Y%m%d-%H%M)"
mkdir -p "$out"
git -C "$repo" worktree list --porcelain | awk '/^worktree /{print $2}' |
while read -r wt; do
name=$(basename "$wt")
git -C "$wt" diff HEAD > "$out/$name.patch"
git -C "$wt" ls-files --others --exclude-standard > "$out/$name.untracked.txt"
done
# 所有本機分支(含尚未 push 的 Agent 分支)打包成單一檔案
git -C "$repo" bundle create "$out/all-branches.bundle" --all✅ 驗證方式
確認壓縮檔可讀且包含關鍵檔案:
tar -tzf "$HOME/Backups/orca-userdata-20261030-0900.tgz" | grep -E 'orca-profile-index.json|profile-state.db'確認 SQLite 檔案完整(需安裝
sqlite3;請對「解壓縮後的副本」執行,不要對使用中的正式檔案執行):sqlite3 ./restore-test/Orca/profiles/<id>/profile-state.db "PRAGMA integrity_check;"預期輸出:
ok確認 Git bundle 可用:
git bundle verify "$HOME/Backups/wt-20261030-0900/all-branches.bundle"判讀:
integrity_check不是ok、或 bundle verify 失敗,代表備份不可用,請在 Orca 完全關閉的狀態下重做備份。
29.3.4 還原操作步驟
- 完全結束 Orca。
- 將目前的資料目錄改名保留(例如
Orca.before-restore),不要直接刪除。 - 把備份解壓縮回原位置。
- 啟動 Orca。若出現「Orca asks which profile copy to use」,畫面會顯示 JSON 與 SQLite 各自的最後儲存時間;一般選 Use SQLite (Recommended),若確定 JSON 較新則選 Use JSON;不確定時選 Quit 先檢查兩份副本。
- 還原 Worktree 未提交變更:在對應 Worktree 中執行
git apply <name>.patch;遺失的分支可從 bundle 取回。
# 從 bundle 取回單一分支
git -C "$HOME/src/myapp" fetch "$HOME/Backups/wt-20261030-0900/all-branches.bundle" \
agent/backend/REQ-1024:agent/backend/REQ-1024
# 套用 patch 前先檢查
git -C "$HOME/src/myapp-wt/feat-a" apply --check feat-a.patch && \
git -C "$HOME/src/myapp-wt/feat-a" apply feat-a.patch📌 查證狀態:官方文件明確記載(profile 副本選擇對話框、舊版可下載且不強制降級 Worktree 資料)|來源:Troubleshooting & FAQ、Install;目錄還原步驟為依官方說明延伸(教學推論)。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 專案與 Worktree 清單恢復 | 開啟 Orca 側邊欄 | 與備份當時一致 | 改回 Orca.before-restore 並改用較早的備份 |
| 快捷鍵恢復 | Settings → Shortcuts 檢查自訂項 | 自訂按鍵存在 | 複製 keybindings.json 回 ~/.orca |
| 未提交變更恢復 | git status、git diff --stat | 與備份前的變更檔案數一致 | 用 git apply --reject 找出衝突區塊 |
| 分支恢復 | git branch --list 'agent/*' | 遺失的 Agent 分支重新出現 | 確認 bundle 時已包含該分支(git bundle list-heads) |
❌ 常見錯誤:Orca 執行中直接複製 profile-state.db,得到不一致的 SQLite 檔,還原後才發現資料毀損。
💡 小技巧:Orca 的設定大多可重建,真正難以重建的是「尚未 push 的 Agent 分支」與「未提交的修改」。把 29.3.3 的 Git 匯出腳本排進每日下班前的例行作業,效益通常比備份整個資料目錄更高。
29.4 Log 收集
29.4.1 Log 位置
官方提供的標準入口是 Help → Open Logs,會直接開啟 Orca 的 Log 資料夾,回報 Bug 時附上這個資料夾即可。依原始碼,Log 資料夾位於使用者資料目錄下的 logs:
| 作業系統 | Log 目錄 | 常見檔案(依原始碼) |
|---|---|---|
| Windows | %APPDATA%\Orca\logs | main.trace.ndjson、orcad.trace.ndjson、daemon.log |
| macOS | ~/Library/Application Support/Orca/logs | 同上 |
| Linux | ~/.config/Orca/logs | 同上 |
📌 查證狀態:Help → Open Logs 為官方文件明確記載(Troubleshooting & FAQ);實際目錄與檔名為依官方說明延伸(教學推論),來源為原始碼 logs-directory.ts。若與實際不符,以 Help → Open Logs 開出的資料夾為準。
另外兩種與排錯相關的資料:
- Agent 自身的對話紀錄:在 Session History(AI Vault)中的單一 Session 選單可以開啟或在檔案總管中顯示該 Session 的 Log,適合用來確認 Agent 實際收到的 Prompt 與執行過的指令。
- 本機診斷追蹤:依 Privacy & Telemetry 說明,錯誤細節只保存在本機的診斷 trace 檔,只有你主動分享診斷包時才會送到 Orca 團隊;匿名 Telemetry 不含錯誤訊息原文。
29.4.2 標準收集步驟
- 重現問題一次,記下發生的時間(含時區)。
- 從 Help → Open Logs 開啟 Log 資料夾,確認最後修改時間涵蓋問題發生時刻。
- 依下方各平台指令打包 Log。
- 收集環境資訊:Orca 版本、作業系統版本、執行位置(本機、WSL、SSH、Remote Orca Server)、相關 Agent CLI 版本。
- 若與 GitHub 相關,加上
gh auth status的遮蔽後輸出與一次gh api user的結果。 - 執行機敏字串掃描並遮蔽(29.4.3)。
- 透過 Help → Send Feedback(可貼上或拖入截圖)、GitHub Issues 或 Discord 回報;企業內部則先送平台組。
範例:Windows(PowerShell)
$stamp = Get-Date -Format 'yyyyMMdd-HHmm'
$logs = Join-Path $env:APPDATA 'Orca\logs'
$out = Join-Path $env:USERPROFILE "Desktop\orca-logs-$stamp.zip"
Get-ChildItem $logs | Sort-Object LastWriteTime -Descending | Select-Object -First 10 Name, Length, LastWriteTime
Compress-Archive -Path (Join-Path $logs '*') -DestinationPath $out
"OS: $([System.Environment]::OSVersion.VersionString)" | Out-File "$env:USERPROFILE\Desktop\orca-env-$stamp.txt"範例:macOS(bash)
stamp=$(date +%Y%m%d-%H%M)
logs="$HOME/Library/Application Support/Orca/logs"
ls -lt "$logs" | head -n 10
tar -czf "$HOME/Desktop/orca-logs-$stamp.tgz" -C "$HOME/Library/Application Support/Orca" logs
{ sw_vers; uname -m; orca status --json; } > "$HOME/Desktop/orca-env-$stamp.txt" 2>&1範例:Linux(bash)
stamp=$(date +%Y%m%d-%H%M)
tar -czf "$HOME/orca-logs-$stamp.tgz" -C "$HOME/.config/Orca" logs
{ cat /etc/os-release; uname -a; orca-ide status --json; } > "$HOME/orca-env-$stamp.txt" 2>&1⚠️ 注意事項:
- Linux 的 CLI 名稱是
orca-ide(避免與 GNOME Orca 螢幕閱讀器衝突)。 - 遠端情境(SSH、Remote Orca Server)的問題,要同時收集桌面端 Log,並在 Settings → SSH Hosts 或 Settings → Managed servers 記錄該主機的 server 版本與狀態;GitHub 驗證在遠端主機是各自獨立的,需在主機上執行
gh auth status。
29.4.3 遮蔽機敏資訊
Log 可能包含路徑、Repository 名稱、主機名稱,甚至在少數情況下帶出 token 片段。對外提交前,至少做一次字串掃描:
# 以 ripgrep 掃描常見 token 前綴與私鑰標記
rg -n --no-heading -e 'gh[pousr]_[A-Za-z0-9]{20,}' -e 'sk-[A-Za-z0-9_-]{20,}' \
-e 'xox[abp]-' -e 'BEGIN (RSA|OPENSSH) PRIVATE KEY' ./orca-logs-extractedGet-ChildItem .\orca-logs-extracted -Recurse -File |
Select-String -Pattern 'gh[pousr]_[A-Za-z0-9]{20,}', 'sk-[A-Za-z0-9_-]{20,}', 'BEGIN (RSA|OPENSSH) PRIVATE KEY' |
Select-Object Path, LineNumber29.4.4 Bug 回報範本
[環境]
Orca 版本:v1.4.244(Stable)
作業系統:Windows 11 23H2 / macOS 15.x / Ubuntu 24.04
執行位置:本機 / WSL / SSH(managed server 版本:___) / Remote Orca Server
相關 Agent CLI:codex 0.1xx、claude x.y.z
gh:已登入(帳號名稱已遮蔽)
[重現步驟]
1.
2.
3.
[預期結果]
[實際結果](含錯誤訊息原文、截圖)
[發生時間]2026-10-30 09:42 +08:00
[附件]orca-logs-20261030-0945.zip(已執行機敏字串掃描)✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Log 涵蓋問題時間 | 檢查最新檔案的 LastWriteTime | 晚於問題發生時間 | 重現一次再收集 |
| 打包完整 | 解壓縮後列出檔案 | 與 Log 資料夾內容一致 | 確認路徑是否被空白字元截斷(macOS 路徑需加引號) |
| 已遮蔽機敏資訊 | 執行 29.4.3 掃描 | 無任何命中 | 手動遮蔽後再掃描一次 |
| 環境資訊齊全 | 對照 29.4.4 範本 | 每個欄位都有值 | 補齊版本與執行位置 |
❌ 常見錯誤:只附截圖、不附版本號與 Log,維護者無法判斷是否已在新版修正。
29.5 常見故障排除流程
29.5.1 總體決策流程
flowchart TD
START["發生問題"] --> VER["確認 Orca 與 Agent CLI 版本"]
VER --> KNOWN{"Release Notes 或 Issues<br/>已有相同問題?"}
KNOWN -->|"是"| UPG["依說明升級或套用暫行解法"]
KNOWN -->|"否"| CAT{"問題類別"}
CAT -->|"Agent 無法啟動"| A1["在 Orca 外的一般終端執行該 CLI"]
A1 --> A2{"外部也失敗?"}
A2 -->|"是"| A3["修 CLI 安裝與登入"]
A2 -->|"否"| A4["檢查 Settings → Agents 的路徑<br/>再按 Restart chip"]
CAT -->|"Worktree 建立失敗"| W1["git fetch origin"]
W1 --> W2["檢查分支是否已有 Worktree"]
CAT -->|"GitHub 面板錯誤"| G1["gh auth status 與 gh api user"]
G1 --> G2{"403 且 rate limit?"}
G2 -->|"是"| G3["等待重置並減少 gh 用戶端"]
G2 -->|"否"| G4["重新驗證並確認 scope 與 SSO"]
CAT -->|"SSH 遠端終端失敗"| S1["Settings → SSH Hosts 檢視原因"]
S1 --> S2["Settings → Managed servers<br/>Update 或 Roll back 或 Recover"]
CAT -->|"效能與記憶體"| P1["Resource Manager 找出大戶"]
P1 --> P2["關閉閒置 Worktree 與瀏覽器<br/>啟用 Hibernation"]
A3 --> VERIFY["依驗證方式確認修復"]
A4 --> VERIFY
W2 --> VERIFY
G3 --> VERIFY
G4 --> VERIFY
S2 --> VERIFY
P2 --> VERIFY
UPG --> VERIFY
VERIFY --> OK{"已解決?"}
OK -->|"否"| ESC["收集 Log 並升級處理(29.4)"]
OK -->|"是"| DONE["記錄於內部知識庫"]如何閱讀此圖:從上方「發生問題」開始,先做「確認版本」與「是否已知問題」兩個所有類別共用的步驟,再依症狀類別分流到各自的第一步。每一條分支最後都匯集到「依驗證方式確認修復」;若仍未解決,就進入 29.4 的 Log 收集與升級處理,而不是在同一條分支反覆嘗試。
📌 查證狀態:官方文件明確記載(各分支的處理動作)|來源:Troubleshooting & FAQ、Troubleshooting GitHub errors;整體流程的編排為教學示例(非官方)。
29.5.2 症狀速查表
| 症狀 | 最可能原因 | 第一步 | 修正方式 |
|---|---|---|---|
| Agent 無法啟動 | CLI 未安裝、未登入,或不在 Orca 看到的 PATH | 在 Orca 外的一般終端執行該 CLI | 修安裝與登入;於 Settings → Agents 指定路徑;按 tab 上的 Restart chip |
| Codex 報 path must be shorter than SUN_LEN | Codex 0.157 以上在 Orca 管理的帳號 home 中 socket 路徑過長 | 確認 Orca 版本 | 升級到 v1.4.212 以上,Orca 會自動調整,不需搬移帳號或改 ~/.codex/config.toml |
| 啟動時詢問要用哪份 profile | JSON 與 SQLite 兩份 profile 內容不一致 | 比較畫面上的最後儲存時間 | 通常選 Use SQLite (Recommended);不確定先 Quit 並備份 |
| Diff 畫面錯誤或卡住 | 外部 rebase、reset 剛好發生在兩次重新整理之間 | 按 Diff 工具列的重新整理圖示 | 重新讀取 Worktree;必要時重開 Diff |
| Worktree 建立失敗 | 起始 ref 尚未 fetch;該分支已有 Worktree | git fetch origin | 刪除舊 Worktree 或改用新分支名稱 |
orca 顯示 command not found | CLI 未註冊或 shim 不在 PATH | Settings → General → Orca CLI | macOS 確認 ~/.local/bin 在 PATH;Windows 由安裝程式加入 PATH;Linux 指令為 orca-ide |
| SSH 可連線但遠端終端失敗 | 主機的 managed server 狀態異常或無法在該主機執行 | Settings → SSH Hosts 查看原因 | Settings → Managed servers 進行 Update、Roll back 或 Recover;無法支援的主機改用舊版 Orca |
v1.4.224 前開的遠端 terminal 沒有 orca 指令 | 該 terminal 沿用舊執行環境 | 確認 terminal 開啟時間 | 在同一主機開新 terminal |
| SSH 可下載檔案但 Download Folder 失敗 | 資料夾下載需要遞迴 SFTP | 確認連線類型 | 改在終端用 tar 或 scp |
| Open in VS Code 停用或只顯示 Local | 非 SSH Worktree、Open-in 指令設定錯誤 | 確認 Worktree 類型 | 改用 SSH Worktree;將 Open-in 設為 VS Code 或 Insiders;重新整理 SSH targets |
| Kerberos 登入失敗 | 沒有有效票證或未啟用 GSSAPI | klist | 確認 OpenSSH config 對該 Host 設定 GSSAPIAuthentication yes,再於 Settings → SSH 重新測試 |
| 瀏覽器回報 browser_no_tab | 目前 Worktree 沒有開啟分頁 | 確認瀏覽器窗格 | orca tab create --url http://localhost:3000 或手動開啟分頁 |
| 記憶體或 CPU 偏高 | 閒置 Worktree 的 file watcher、大量瀏覽器分頁 | 開啟 Resource Manager | 關閉閒置 Worktree 與瀏覽器;啟用 Agent Hibernation(第三十章) |
| GitHub 顯示 rate-limiting | REST core 每小時額度用盡 | gh api user -i 看 X-Ratelimit-Remaining | 等待重置、停止多餘 gh 自動化、關閉多餘 Orca 視窗 |
| GitHub authentication is unavailable | gh 未登入、token 過期或環境變數 token 錯誤 | gh auth status -h github.com | unset GITHUB_TOKEN GH_TOKEN 後重新 gh auth login |
| HTTP 403(非 rate limit) | 缺少 scope 或無存取權、SSO 未授權 | 用同一帳號在瀏覽器開該 PR | 以含 repo(必要時 read:org、project)的 scope 重新驗證並完成 SSO 授權 |
| HTTP 404 或 repository is unavailable | remote 錯誤、私有 repo 無權限、repo 已改名 | git remote -v | 修正 remote 或申請權限 |
| GitHub is unreachable | 網路、Proxy、VPN 或 GitHub 服務中斷 | 查看 GitHub Status | 暫時離開 VPN 重試;遠端主機確認可連 api.github.com |
| Orca 說 gh 未安裝但終端可用 | PATH 上有卡住的 gh launcher,或 Windows 的 WSL 與原生環境不一致 | which gh 或 Get-Command gh | 新版 Orca 會略過卡住的 launcher;仍失敗時完整重啟 Orca,並在 Orca 啟動的同一環境安裝 gh |
📌 查證狀態:官方文件明確記載|來源:Troubleshooting & FAQ、Troubleshooting GitHub errors
29.5.3 Runbook 一 Agent 無法啟動
在 Orca 之外開一般終端,確認 CLI 可執行並已登入:
which claude && claude --version which codex && codex --versionGet-Command claude, codex -ErrorAction SilentlyContinue | Select-Object Name, Source若外部也失敗:重新安裝 CLI 並依各 CLI 官方方式登入,這不是 Orca 的問題。
若只有 Orca 內失敗:開啟 Settings → Agents,確認該 Agent 已啟用,並在 per-agent launch defaults 中把 binary path 指定為步驟 1 查到的完整路徑。
按該 tab 上的 Restart chip 重新啟動。
若在 Windows 上同時使用 WSL 與原生環境,確認 CLI 安裝在 Orca 實際啟動 Agent 的那一側。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| CLI 在 Orca 外可用 | 一般終端執行 --version | 顯示版本 | 依 CLI 官方文件修安裝 |
| Orca 使用正確路徑 | Settings → Agents 檢查 binary path | 與 which 或 Get-Command 結果一致 | 修改後重開該 Agent tab |
| Agent 正常回應 | 送出「回覆 OK 即可」 | 數秒內回覆 | 收集 Log(29.4)並附上 CLI 版本 |
29.5.4 Runbook 二 GitHub 面板停止更新
先看 PR/Checks 面板上的錯誤文字,它是即時請求失敗的結果,可信度最高。
用真實 REST 請求確認是否被限流:
gh auth status -h github.com gh api user -i 2>&1 | head -n 40判讀:若回傳 403、訊息含 API rate limit exceeded,且
X-Ratelimit-Remaining: 0,代表 REST 被鎖到X-Ratelimit-Reset(Unix 秒數)所示時間。再看探測值(不消耗額度,可能比實際樂觀):
gh api rate_limit --jq '.resources | {core, graphql, search}'處置:等待重置;關閉多餘的 Orca 視窗與 dev build;暫停會大量呼叫 gh 的 Agent 自動化;限流期間不要狂按重新整理(Orca 已有 circuit breaker 自動退避)。
重置後仍失敗,改查驗證問題:清除殘留的
GITHUB_TOKEN、GH_TOKEN後重新登入,並完整重啟 Orca。
⚠️ 注意事項:Settings → Git → GitHub API Budget 讀的是不計額度的探測端點,有時顯示仍有餘額但實際 REST 已歸零。三者不一致時,信任順序為:面板錯誤 → 真實 CLI 請求 → Settings 數字。另外,GitHub API Budget 與 Accounts 中的 Claude、Codex 用量是兩回事,後者是 AI Provider 的限制。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 驗證正常 | gh api user --jq '{login, id}' | 回傳正確帳號 | gh auth login -h github.com 後重啟 Orca |
| 額度恢復 | gh api user -i 的 X-Ratelimit-Remaining | 大於 0 | 等到 X-Ratelimit-Reset 時間 |
| 面板恢復 | Source Control 與 PR Checks 面板 | 狀態更新、無橫幅 | 依 29.4 收集 Log 並附上遮蔽後的 gh auth status |
29.5.5 Runbook 三 Worktree 建立失敗
在主 Repository 開終端,更新遠端參照:
git fetch origin檢查是否已有 Worktree 佔用同一分支:
git worktree list若清單中有已被手動刪除目錄的殘留項目,清除登記:
git worktree prune --dry-run git worktree prune於 Orca 重新建立 Worktree,或改用新的分支名稱。
若錯誤與磁碟空間有關,用 Resource Manager → Clean up workspaces 檢視各 Workspace 大小後清理(清理前確認分支已合併,見第十一章)。
✅ 驗證方式
執行:
git worktree list預期輸出(示意):
/home/dev/src/myapp a1b2c3d [main] /home/dev/src/myapp-wt/fix-42 d4e5f6a [fix-42]判讀:新分支出現在清單中,且 Orca 側邊欄同步顯示,代表修復成功;若仍失敗,收集 Log 並附上
git worktree list --porcelain輸出。
29.5.6 支援分級與升級路徑
| 層級 | 負責人 | 處理範圍 | 時限(教學示例) | 交付物 |
|---|---|---|---|---|
| L1 自助 | 工程師本人 | 29.5.2 速查表內的已知問題 | 30 分鐘 | 依驗證方式確認修復 |
| L2 平台組 | Orca 管理員 | 版本、設定、SSH、GitHub 權限、跨團隊問題 | 1 個工作天 | 內部知識庫條目 |
| L3 外部 | 平台組代表 | 可重現的 Orca 缺陷 | 依官方回應 | GitHub Issue 連結與 29.4.4 回報 |
📌 查證狀態:教學示例(非官方)
29.6 本章 Review 與驗證清單
- 能說明 Stable 與 RC 通道的差異,以及 Shift+點擊、Ctrl/Cmd+點擊 Check for Updates 的效果
- 已用
gh release view --repo stablyai/orca與本機指令完成一次版本盤點 - 已建立內部 Release Ring 與「累積相容性清單」,並讀過 v1.4.212~v1.4.244 的相容性變更
- 理解 terminal host 世代:升級後會關閉並重開 terminal 再驗證
- 已在 Orca 完全關閉的狀態下備份使用者資料目錄,並以
PRAGMA integrity_check驗證 - 已用
git bundle與 patch 匯出所有 Worktree 的未推送分支與未提交變更,並以git bundle verify驗證 - 知道三個平台的 Log 位置,且能透過 Help → Open Logs 找到它
- 已練習一次 Log 打包、機敏字串掃描與 Bug 回報範本填寫
- 能依 29.5.1 決策流程處理 Agent 無法啟動、Worktree 建立失敗、GitHub 限流三類問題
- 知道 GitHub API Budget 探測值與真實 REST 額度可能不一致,並能用
gh api user -i確認
第三十章 效能與成本最佳化
平行 Agent 的價值來自「同時做很多事」,而成本也來自同一件事:每多一個 Worktree,就多一份磁碟上的 checkout、一組 file watcher、一個常駐 PTY、一段持續累積的模型 Context,以及一份 AI Provider 的用量。本章把效能與成本放在一起談,因為兩者的最佳化手段高度重疊——少開不必要的東西、讓閒置的東西睡著、讓每一次 Prompt 都物有所值。
30.1 多 Worktree 資源管理
30.1.1 資源消耗從哪裡來
| 資源 | 主要來源 | 官方說明 | 可調整手段 |
|---|---|---|---|
| 記憶體(RAM) | 內建瀏覽器分頁、Split 版面、每個 Agent 的常駐 PTY 與模型 Session | Split 版面搭配大量瀏覽器分頁是最大的 RAM 用戶 | 關閉不用的瀏覽器、啟用 Hibernation |
| CPU | Terminal 渲染、file watcher、Agent 子程序(編譯、測試) | 每個 Worktree 都維持 file watcher | 關閉不用的 Worktree;v1.4.242 起 terminal 閒置 CPU 已大幅下降 |
| 磁碟 | 每個 Worktree 是完整 checkout,另加依賴與建置輸出 | Worktree 是 repo 在磁碟上的獨立副本 | Worktree Shared Paths、定期清理 |
| Codex 額外開銷 | v1.4.217 起每個 Codex tab 使用獨立 server | Release Notes 註明記憶體用量會增加 | 視需要於 Settings → Agents 關閉「Run each Codex terminal on its own server」 |
| 網路與 API 額度 | gh 輪詢 PR/Checks、Agent 呼叫 gh | 同一 GitHub 帳號的所有工具共用每小時額度 | 減少 Orca 視窗數、批次化 gh 自動化 |
📌 查證狀態:官方文件明確記載|來源:Troubleshooting & FAQ(Performance & memory)、Worktrees、Agent hibernation、GitHub Releases(v1.4.217、v1.4.242)
30.1.2 用 Resource Manager 觀察實際用量
Resource Manager 是狀態列上的一個開關項目(Settings → Appearance → Status bar toggles),可看到 CPU、記憶體、Sessions、daemon 控制與 Workspace 磁碟掃描;當專案位於 paired Orca server 時,會以該 server 名稱列出遠端的程序。v1.4.238 起另有 PTY 檢視,可直接找出佔用資源的 terminal。
操作步驟
- Settings → Appearance → Status bar toggles,開啟 Resource Manager。
- 點擊狀態列的 Resource Manager,依記憶體排序,找出用量最大的 Workspace 與 PTY。
- 需要整理時,使用 Resource Manager → Clean up workspaces:列表包含本機 Worktree、主 Worktree、資料夾 Workspace,以及已斷線 SSH 主機上的 Workspace,可依狀態、最近活動、大小、Git 狀態與連結的 Review 搜尋排序。
- 勾選要移除的項目。注意:批次刪除會刪除磁碟上的資料夾;若 git 判斷某本機分支可能含未合併 commit,Orca 會保留該分支並跳出「Review N Branches」提示,讓你逐一決定是否強制刪除。
📌 查證狀態:官方文件明確記載|來源:Settings reference、Worktrees
30.1.3 硬體規格與平行上限參考表
官方沒有公布「幾 GB 記憶體可以跑幾個 Agent」的數字,因為用量取決於 repo 大小、Agent 種類、是否開瀏覽器與 dev server。下表是教學示例的起始值,請用 30.1.4 的方法在自己的環境量測後調整。
| 工作站等級(教學示例) | 記憶體 | 建議同時「活躍」Agent 數 | 同時開啟瀏覽器分頁 | 建議做法 |
|---|---|---|---|---|
| 輕薄筆電 | 16 GB | 2~3 | 1~2 | 只跑同題競賽或小型分工;開啟 Hibernation,閒置窗口設 15~30 分鐘 |
| 標準開發筆電 | 32 GB | 4~6 | 2~4 | 分批啟動任務;dev server 只在需要預覽的 Worktree 啟動 |
| 高階桌機/工作站 | 64 GB 以上 | 6~10 | 4~6 | 適合 Orchestration 協調者角色;長時間建置移到遠端 |
| SSH 主機或 Remote Orca Server | 依主機 | 依主機 CPU 與記憶體 | 由桌面端渲染或 Server 串流 | 重度編譯、測試、批次任務搬到遠端,本機只負責審查(第十八章) |
📌 查證狀態:教學示例(非官方)|數字為起始建議值,不代表官方規格或效能保證。
磁碟估算公式(教學示例)
所需磁碟 ≈ 同時存在的 Worktree 數 × (原始碼大小 + 依賴資料夾大小 + 建置輸出大小)
範例:原始碼 300 MB、node_modules 1.2 GB、建置輸出 500 MB、同時 8 個 Worktree
8 × (0.3 + 1.2 + 0.5) GB = 16 GB
若以 Worktree Shared Paths 共用 1.2 GB 的依賴快取(macOS 可用 APFS clone,否則為 symlink):
8 × (0.3 + 0.5) GB + 1.2 GB ≈ 7.6 GB⚠️ 注意事項:Worktree Shared Paths 只適用於 gitignore 的路徑。共用依賴資料夾時,若不同 Worktree 需要不同版本的依賴(例如框架升級分支),就不應共用,否則會互相污染(見第二章 orca.yaml 與 worktreeinclude 說明)。
30.1.4 量測自己的基準值
範例:量測目前 Worktree 數量與各自的磁碟用量。
repo="$HOME/src/myapp"
git -C "$repo" worktree list --porcelain | awk '/^worktree /{print $2}' |
while read -r wt; do du -sh "$wt"; done | sort -h$repo = "$env:USERPROFILE\src\myapp"
git -C $repo worktree list --porcelain |
Where-Object { $_ -like 'worktree *' } |
ForEach-Object {
$p = $_.Substring(9)
$size = (Get-ChildItem $p -Recurse -File -Force -ErrorAction SilentlyContinue |
Measure-Object Length -Sum).Sum
[pscustomobject]@{ Worktree = $p; GB = [math]::Round($size / 1GB, 2) }
} | Sort-Object GB -Descending量測記憶體基準的步驟(教學示例)
- 只開 Orca 與一個 Worktree、不啟動 Agent,記錄 Resource Manager 的總記憶體(A)。
- 啟動一個 Agent 並送出一個中型任務,完成後記錄(B)。單一 Agent 增量約為 B − A。
- 再開一個瀏覽器分頁並載入 dev server 頁面,記錄(C)。單一瀏覽器增量約為 C − B。
- 平行上限 ≈(可用記憶體 − 作業系統與其他工具保留 − A)÷(單一 Agent 增量 + 預期瀏覽器增量)。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 已建立基準值 | 記錄 A、B、C 三個數字 | 每台工作站型號各一份 | 補量測,避免直接套用他人數字 |
| 平行上限合理 | 以上限數量同時跑任務 30 分鐘 | 介面無明顯卡頓、作業系統未大量使用 swap | 降低上限或把建置移到遠端 |
| 磁碟有餘裕 | 上方 du 或 PowerShell 指令 | 剩餘空間大於下一批 Worktree 預估量的 1.5 倍 | 清理已合併 Worktree 或啟用 Shared Paths |
| 清理不誤刪 | Clean up workspaces 後查看 Review N Branches 提示 | 未合併分支仍保留 | 從 29.3 的 bundle 取回 |
❌ 常見錯誤:為了展示「十個 Agent 同時跑」而全部開在一台 16 GB 筆電上,結果審查者連 Diff 都打不開,總產出反而下降。
💡 小技巧:把平行數量當成「審查產能」而不是「機器產能」來設定。人一次能認真審的 Diff 通常只有 2~4 份,其餘 Agent 讓它們在遠端或 Hibernation 中等待即可。
30.2 記憶體與 Hibernation
30.2.1 Agent Hibernation 的運作方式
當你同時開著數十個 Worktree 時,每一個閒置 Agent 都是一個常駐的 PTY,背後還持有模型 Session。Agent Hibernation 會在 Agent 完成並閒置夠久後安靜地停止該 terminal,下次開啟這個 Worktree 時再自動以相同 Session 恢復。
此功能目前為實驗性,預設關閉,需在 Settings → Experimental → Agent hibernation 開啟。
Orca 只會在全部條件都成立時讓 Agent 休眠:
- Agent 處於 done 狀態(已完成最後一回合,且沒有等待輸入)。
- 該 terminal 不在目前作用中的 Worktree,也不在任何正在前景顯示 terminal 的 Worktree。
- Agent 完成後沒有收到任何按鍵輸入。
- 該 Agent 支援可恢復的 Session:Claude、Codex、Gemini、Antigravity、OpenCode、Pi、MiMo Code、Droid、Grok、Devin、OMP。
- 已閒置超過設定的時間窗口(預設 30 分鐘)。
- 沒有行動端 Session 正在操作這個 terminal。
- 沒有尚未結算的 Orchestration Dispatch(pending、dispatched 或 unknown);只有在執行階段確認為 completed、failed 或 circuit_broken 後才允許休眠。
- 該窗格上沒有仍在執行的 subagent 或 teammate。
同一個 Worktree 若有多個 Agent 窗格,會以 Worktree 為單位一起休眠,不會出現「只睡一半」的狀態。Cursor CLI、Hermes、Copilot、Trae 等不支援恢復的 terminal 會持續執行。
📌 查證狀態:官方文件明確記載|來源:Agent hibernation
stateDiagram-v2
[*] --> Working
Working --> Done : Agent 完成回合
Done --> Working : 使用者輸入或新輸出
Done --> Eligible : 閒置達 Hibernate after 且條件全數成立
Eligible --> Done : 按鍵或切回該 tab 重設計時
Eligible --> Hibernated : Orca 停止 PTY
Hibernated --> Resuming : 使用者開啟該 Worktree
Resuming --> Working : 以 resume 旗標恢復 Session
Resuming --> FreshPrompt : 無法恢復時開新提示
FreshPrompt --> [*]如何閱讀此圖:每個方框是 Agent terminal 的狀態,箭頭上的文字是觸發條件。重點有兩個:第一,從 Done 進入 Eligible 需要「閒置時間」與 30.2.1 列出的全部條件同時成立,任何按鍵都會把它拉回 Done;第二,恢復時若 transcript 已刪除或 Provider 輪替了 Session ID,會進入 FreshPrompt(開新提示),先前的對話仍可在 Session History 找到。
30.2.2 調整 Hibernate after 閒置窗口
在 Agent hibernation 開關下方的 Hibernate after 設定,決定已完成的背景 Agent 要閒置幾分鐘才休眠:預設 30 分鐘,範圍 1 分鐘到 24 小時。計時從 Agent 最後一次 done 更新開始,任何按鍵、新輸出或切回該 terminal 都會重設。
| 情境(教學示例) | 建議值 | 理由 |
|---|---|---|
| 16 GB 筆電、常開 10 個以上 Worktree | 10~15 分鐘 | 記憶體壓力大,寧可多付恢復成本 |
| 32 GB 以上、日常分工 | 30 分鐘(預設) | 兼顧記憶體與切換流暢度 |
| 同題競賽、需要頻繁比較多個結果 | 60~120 分鐘 | 避免審查途中反覆恢復 |
| 遠端主機上的長時間批次 | 依主機資源,可設數小時 | 遠端記憶體通常較充裕 |
手動休眠:也可以在側邊欄對 Worktree 右鍵選擇 Sleep;有巢狀子 Worktree 時可用 Sleep with Descendants。手動休眠會保留已完成與被中斷的可恢復 Session 紀錄,重新開啟時仍能用相同 resume 旗標啟動。若常隱藏休眠中的 Worktree,可在 Settings → Shortcuts 指定 Toggle Sleeping Workspaces 快捷鍵。
恢復時發生什麼事:Orca 以與 Session History 相同的 resume 旗標重新啟動 Agent CLI(例如 claude --resume <id>、codex resume <id>),並重用首次開啟時擷取的啟動指令、參數與私有環境變數,不需要任何點擊。
30.2.3 其他記憶體相關版本改善
| 版本 | 改善 | 對使用者的意義 |
|---|---|---|
| v1.4.214 | Profile 改存 SQLite、內建 ripgrep 與 headless Bun | 啟動與搜尋較省資源 |
| v1.4.242 | Terminal 閒置 CPU 大幅下降;WSL 主機不再每次重啟都重新配對,記憶體大降 | 多 terminal 長時間開著的成本下降 |
| v1.4.244 | Workspace 切換預熱(滑過即準備);Windows 新 terminal 立即顯示 prompt;macOS、Linux 關閉或調整 terminal 不再凍結其他 terminal;多 Agent Codex chat 不再讓本機聊天紀錄膨脹到 GB 等級 | 大量 Worktree 間切換更順暢 |
📌 查證狀態:官方文件明確記載|來源:GitHub Releases(v1.4.214、v1.4.242、v1.4.244)
範例:啟用並驗證 Hibernation 的步驟
- Settings → Experimental → 開啟 Agent hibernation,Hibernate after 暫設為 2 分鐘(僅供測試)。
- 在 Worktree A 啟動 Claude,送出「列出 src 目錄下的檔案即可」,等待完成。
- 切換到 Worktree B,不要再碰 A。
- 2 分鐘後,打開 Resource Manager 的 PTY 檢視,確認 A 的 Agent terminal 已不在執行清單。
- 切回 Worktree A,觀察 terminal 以 resume 方式恢復,並詢問「剛剛列出的第一個檔案是什麼」,確認對話延續。
- 測試完成後把 Hibernate after 改回正式值。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 休眠生效 | Resource Manager 的 PTY 與記憶體 | Worktree A 的 PTY 消失、記憶體下降 | 對照 30.2.1 的八個條件逐一檢查(最常見是 Agent 不在支援清單或有未結算 Dispatch) |
| 恢復延續對話 | 切回後詢問上一回合內容 | Agent 能回答 | 確認 Session History 中該 Session 仍存在 |
| 不支援的 Agent 不被休眠 | 以 Copilot 或 Cursor CLI 重做步驟 2~4 | 持續執行 | 屬正常行為,依官方限制 |
| 正式值已設定 | Settings → Experimental | Hibernate after 為團隊標準值 | 調回並記錄於標準設定基準(第六章) |
⚠️ 注意事項:Hibernation 會以首次啟動時擷取的環境變數恢復 Agent。若你在 Agent 執行期間輪替了 API Key 或切換了帳號,請確認恢復後的 Session 使用的是預期的身分(Codex 帳號可搭配 Hot-swap,見第八章)。
30.3 Context 與 Token 效率
30.3.1 為什麼多 Agent 情境更需要省 Context
單一 Agent 浪費一點 Context 只影響一個對話;同時跑五個 Agent 時,每一份重複貼上的規格、每一次「先把整個 repo 讀一遍」都會被乘以五。Context 越長,回應越慢、越容易忽略關鍵指示,也越快觸及用量上限。
30.3.2 Token 效率的八個做法
| 做法 | Orca 中的對應功能 | 效果 |
|---|---|---|
| 把共用規範寫進 repo 的 Memory 檔,而不是每次貼進 Prompt | Memory 檔案(第九章) | 規範只維護一份,Agent 依需要讀取 |
| 明確指定檔案範圍 | Native Chat 的 @ 選檔 | 避免 Agent 自行大範圍搜尋 |
| 對話過長時壓縮或清空 | Native Chat 的 /compact、/clear | 降低每回合重送的歷史量 |
| 換手時交接摘要而非整段歷史 | Session History 的 Hand Off to Another Agent | 新 Agent 從摘要開始 |
| 依任務難度選模型與 effort | orca agent launch --model ... --effort ...;Native Chat 每對話記住 model、effort、Fast | 簡單任務不浪費高階推理 |
| 自動化任務固定較省的模型 | Automations 的 --extra-agent-args | 排程任務成本可預測 |
| Design Mode 只在必要時送截圖與 HTML | Design Mode(第十三章) | 純文字可描述的需求不帶大量 HTML |
| 同題競賽只用在高不確定任務 | Parallel Worktrees(第十一章) | 減少落選方案的「沉沒 Token」 |
📌 查證狀態:功能本身為官方文件明確記載|來源:Native chat、Agent session history、CLI reference、Automations;「效果」欄為依官方說明延伸(教學推論)。
30.3.3 Prompt 對照範例
範例一:範圍過大
❌ 低效率:
請先完整閱讀這個 repo,理解所有模組後,幫我修好登入的 bug。✅ 高效率:
任務:修正 token 過期後未自動刷新的問題。
範圍:只允許修改 src/auth/session.ts 與 src/auth/session.test.ts。
已知線索:重現測試為 npm test -- session.test.ts 中的 "refresh after expiry"。
完成定義:該測試通過,且 npm test 全部通過;回報修改摘要與測試輸出最後 20 行。
不要:重構其他模組、更新依賴版本。範例二:重複貼規範
❌ 低效率:在五個 Agent 的 Prompt 中各貼一份 300 行的程式碼規範。
✅ 高效率:把規範放在 repo 的 Memory 檔(例如 AGENTS.md 或 CLAUDE.md),Prompt 只寫:
請遵守 repo 根目錄 AGENTS.md 的「命名與錯誤處理」兩節。範例三:依難度選模型
# 撰寫設計文件:高 effort
orca agent launch --agent codex --effort high --prompt "依 docs/spec/REQ-1024.md 撰寫設計文件草稿" --json
# 摘要 Diff:不需要高 effort
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json範例四:長對話壓縮(Native Chat 中輸入)
/compact🧑⚖️ 人工 Review 要點(套用以上做法後,審查者應逐項確認)
- Agent 的修改確實限縮在 Prompt 指定的檔案(
git diff --stat) - 回報中附有實際測試指令與輸出,而非口頭宣稱
-
/compact之後 Agent 仍記得任務的完成定義(請它複述一次) - 低 effort 任務的品質可接受;若需要多次重來,代表省錯地方
30.3.4 Token 消耗估算示例
📌 查證狀態:教學示例(非官方)|以下數字為假設值,用來示範計算方式,不代表任何 Provider 的實際計費或模型行為。
假設一個「修 bug」任務:
| 項目 | 範圍過大的 Prompt | 範圍明確的 Prompt |
|---|---|---|
| Agent 探索 repo 讀入的內容 | 約 120k tokens | 約 15k tokens |
| 對話回合數 | 8 回合(多次澄清) | 3 回合 |
| 每回合平均重送歷史 | 約 60k tokens | 約 12k tokens |
| 總輸入估計 | 120k + 8 × 60k ≈ 600k | 15k + 3 × 12k ≈ 51k |
| 同題競賽 3 個 Agent | ≈ 1.8M | ≈ 153k |
同一個任務、同樣三個 Agent,Context 管理的差距可以達到一個數量級。在 Orca 狀態列的用量條上,這個差距會直接反映為「多快觸及 5 小時或每週上限」。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 範圍限縮有效 | 任務結束後 git diff --stat | 只有指定檔案被修改 | 在 Prompt 加上「不要」清單並重跑 |
| 用量確實下降 | 同類任務前後比較狀態列 Usage 百分比變化 | 改寫後的增量明顯較小 | 檢查是否仍貼了大量規範或日誌 |
| 品質未下降 | 測試通過率與返工次數 | 不高於改寫前 | 回頭提高 effort 或補充線索 |
30.4 成本治理
30.4.1 Orca 的成本結構
Orca 本身是 MIT 授權的開源桌面應用程式,不另收授權費;實際成本來自三處:
- AI Provider 訂閱與用量:Orca 採 BYO(Bring Your Own)模式,各 Agent CLI 使用你自己的訂閱或 API 帳號(第八章)。
- 基礎設施:SSH 主機、Remote Orca Server、Cloud VM 的運算與儲存。
- 人力:審查 AI 產出的工程師時間,通常是最大的隱性成本。
30.4.2 Orca 提供的用量可視化
| 功能 | 位置 | 能看到什麼 | 限制 |
|---|---|---|---|
| 狀態列用量 | 狀態列 Usage 區段;Detailed 或 Compact 檢視 | 目前帳號相對方案的用量、5 小時/每日/每週等窗口的重置時間 | 只反映作用中帳號;其他帳號在帳號切換器查看 |
| 80% 警示 | 狀態列 | 跨過 80% 時顯示警示 chip | 只是提示,不會自動停止 Agent |
| Usage popover | 點擊狀態列用量 | 所有追蹤中的 Provider,最緊的上限排最前 | 部分 Provider 需在 Settings → Accounts 設定 |
| Provider 餘額 | Usage popover | Claude usage credits、OpenCode Zen、Codex credits | 未回報者顯示 unavailable,不是 0 |
| Stats 預估成本 | Stats 分頁 | 已知模型系列的預估費用 | 使用本機價格表,不是帳單;標示 inferred pricing 或 excludes unpriced models 者為部分估計 |
| GitHub API Budget | Settings → Git | REST、Search、GraphQL 剩餘額度 | 與 AI 用量無關;探測值可能比實際樂觀 |
📌 查證狀態:官方文件明確記載|來源:Usage & rate-limit tracking、Troubleshooting GitHub errors。官方明示:權威的支出數字應以 Provider 主控台為準。
30.4.3 成本治理迴圈
flowchart LR
BUD["設定月度預算與分配"] --> RUN["工程師在 Orca 執行任務"]
RUN --> OBS["每日觀察<br/>狀態列用量與 80% 警示"]
OBS --> REC["每週對帳<br/>Provider 主控台 vs Stats 預估"]
REC --> KPI["計算單位成本<br/>每個合併 PR 的成本"]
KPI --> ADJ{"超出門檻?"}
ADJ -->|"是"| ACT["調整:降 effort、減少競賽<br/>改用較省模型、移除閒置帳號"]
ADJ -->|"否"| KEEP["維持並記錄"]
ACT --> BUD
KEEP --> BUD如何閱讀此圖:這是一個每月循環一次的迴圈。左側是預算,中間的「每日觀察」依賴 Orca 的即時用量,「每週對帳」則以 Provider 主控台為準、Orca Stats 為輔。關鍵在「計算單位成本」:只看總花費無法判斷是否浪費,必須換算成每一個被合併的 PR 花了多少,才能比較不同團隊與不同做法。
30.4.4 成本治理實算範例
📌 查證狀態:教學示例(非官方)|以下金額、席次與方案皆為虛構假設,用於示範計算方法,請代入貴公司實際合約價格。
背景:某產品部門 20 名工程師導入 Orca 一個月。
假設條件
| 項目 | 假設值 |
|---|---|
| 方案 A(一般席位)月費 | 新台幣 600 元/人 |
| 方案 B(高用量席位)月費 | 新台幣 6,000 元/人 |
| API 計量帳號(自動化與 Orchestration 用) | 本月實際帳單新台幣 18,000 元 |
| 遠端 SSH 主機 | 2 台,合計新台幣 9,000 元/月 |
| 席位配置 | 方案 A 16 人、方案 B 4 人 |
| 本月合併 PR 數 | 260 個 |
| 同題競賽次數 | 40 次,每次 3 個 Agent,各取 1 個勝者 |
第一步:計算總成本
訂閱:16 × 600 + 4 × 6,000 = 9,600 + 24,000 = 33,600
API 計量:18,000
基礎設施:9,000
總計:33,600 + 18,000 + 9,000 = 60,600(新台幣/月)第二步:換算單位成本
每個合併 PR 的工具成本 = 60,600 ÷ 260 ≈ 233 元
每位工程師月均工具成本 = 60,600 ÷ 20 = 3,030 元第三步:找出浪費
同題競賽:40 次 × 3 個 Agent = 120 份產出,其中 80 份落選
若 API 計量帳單有 50% 來自競賽任務:18,000 × 50% = 9,000
落選比例 80 ÷ 120 ≈ 66.7%,落選部分約 9,000 × 66.7% ≈ 6,000 元第四步:決策與目標
| 觀察 | 調整動作 | 下月目標(教學示例) |
|---|---|---|
| 4 名方案 B 使用者中有 1 人整月用量未超過方案 A 上限的 50% | 降回方案 A | 訂閱節省 5,400 元 |
| 競賽落選成本約 6,000 元 | 競賽只用於「需求不明確或多方案比較」的任務,其餘改單一 Agent | 競賽次數降到 20 次以內 |
| 自動化任務都使用高 effort | 以 --extra-agent-args 指定較省的模型與 effort | API 計量下降 20% |
| 每 PR 成本 233 元 | 追蹤調整後是否下降且返工率不上升 | 每 PR 成本低於 200 元,返工率不高於本月 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 成本數字可追溯 | 每一個數字都能對應到 Provider 主控台或發票 | 100% 有來源 | 不使用 Stats 預估值作為對帳依據 |
| 合併 PR 數正確 | gh pr list --repo org/app --state merged --search "merged:2026-10-01..2026-10-31" --limit 1000 --json number --jq 'length' | 與報表一致 | 檢查是否漏算多個 repo |
| 浪費估算合理 | 抽樣 5 次競賽,確認落選方案是否真的無用 | 落選方案確實未被採用 | 若落選方案常被部分採用,調整估算比例 |
| 調整未犧牲品質 | 下月返工率(第三十一章 KPI) | 不高於本月 | 撤回最激進的降級動作 |
❌ 常見錯誤:直接把 Orca Stats 的預估成本當作財務報表數字。官方明示 Stats 使用本機價格表,可能因模型推定或未定價模型而只是部分總和。
💡 小技巧:在 Settings → Accounts 定期檢視所有已登入帳號(Claude、Codex、OpenCode、Devin、Antigravity、GLM Coding Plan),把離職或閒置帳號移除;這同時是成本治理與資安治理(第二十八章)。
30.5 本章 Review 與驗證清單
- 能說明記憶體、CPU、磁碟三種資源各自的主要消耗來源
- 已開啟 Resource Manager,並為自己的工作站量測 A、B、C 三個基準值
- 已依量測結果訂定平行上限,而非直接套用他人數字
- 能說明 Worktree Shared Paths 何時適用、何時會造成依賴污染
- 已開啟 Agent Hibernation 並完成一次「休眠到恢復」的驗證
- 能說出 Hibernation 的八個前提條件與不支援的 Agent
- 能用
@選檔、/compact、Hand Off、model 與 effort 參數降低 Token 消耗 - 能區分 Orca Stats 預估成本與 Provider 主控台的權威帳單
- 已用 30.4.4 的方法算出團隊的「每合併 PR 成本」
- 已訂出下月的成本調整動作,並設定品質不下降的驗證條件
第三十一章 建議導入策略
導入 Orca 的難點很少是「安裝」,而是「讓組織在平行 Agent 帶來的速度下,仍維持審查品質、成本與資安的可控性」。本章先提供一個五級成熟度模型,讓你判斷組織目前在哪裡;再依組織規模與產業給出含里程碑與 KPI 的導入計畫;最後在 31.7 統一定義每個 KPI 的計算方式與驗證指令。
📌 查證狀態:教學示例(非官方)|本章為導入方法論,所引用的 Orca 功能皆以官方文件為準並於內文標示章節;里程碑時程與 KPI 目標值為建議起點,需依組織實況調整。
31.1 導入成熟度模型
| 等級 | 名稱 | 組織特徵 | 主要使用的 Orca 能力 | 治理機制 | 代表 KPI | 晉級條件 |
|---|---|---|---|---|---|---|
| L1 | 探索 | 個別工程師自行下載試用 | 單一 Agent、Parallel Worktrees 同題競賽 | 無,或僅口頭約定 | 試用人數 | 至少 3 人連續使用 2 週並願意分享心得 |
| L2 | 試點 | 一個團隊、一到兩個代表性專案 | Worktree 分工、Diff Viewer、Annotate AI Diff、GitHub 整合 | 指定 Orca 管理員;Agent 權限與帳號清單 | PR 前置時間、返工率 | 試點 KPI 達標且無重大資安事件 |
| L3 | 標準化 | 多個團隊採用同一套做法 | 標準設定基準、Hooks、Memory 檔、Prompt Library、Usage 追蹤 | 版本 Release Ring、升級檢查清單、審查準則 | 審查覆蓋率、每 PR 成本 | 設定基準與教材覆蓋全部採用團隊 |
| L4 | 規模化 | 跨部門、含遠端與自動化 | SSH Worktrees、Remote Orca Servers、Orchestration、Scheduled Automations | CoE、成本分攤、稽核抽查、事故處理流程 | 自動化任務成功率、逃逸缺陷率 | 連續兩季 KPI 穩定且稽核無重大缺失 |
| L5 | 最佳化 | 以數據持續改善 | 全部能力,含 Hibernation、Agent 選型與成本最佳化 | 季度檢討、選型評分卡、持續教育 | 單位成本趨勢、工程師滿意度 | 持續維持 |
flowchart TD
START["評估導入 Orca"] --> SIZE{"組織型態"}
SIZE -->|"1~10 人團隊"| SMALL["31.2 小型團隊<br/>目標 L2,90 天"]
SIZE -->|"數十~數百人"| MID["31.3 中型企業<br/>目標 L3,6 個月"]
SIZE -->|"數百人以上"| LARGE["31.4 大型企業<br/>目標 L4,12 個月"]
SIZE -->|"銀行與高監理"| BANK["31.5 高監理產業<br/>先 L2 於周邊系統"]
SIZE -->|"政府與 SI"| GOV["31.6 政府與系統整合商<br/>PoC 後再決定"]
SMALL --> GATE["31.7 里程碑驗收"]
MID --> GATE
LARGE --> GATE
BANK --> GATE
GOV --> GATE
GATE --> NEXTLV{"KPI 達標?"}
NEXTLV -->|"是"| UP["晉級下一成熟度"]
NEXTLV -->|"否"| FIX["檢討原因並延長當前階段"]如何閱讀此圖:先依組織型態選一條路徑,每條路徑標示了「建議目標等級」與「時程」。不論走哪條路,都必須經過 31.7 的里程碑驗收;KPI 未達標時不晉級,而是延長目前階段。這個設計刻意避免「展示很驚豔就直接全公司推廣」的常見失敗。
範例:成熟度自評
請以「是/否」回答,每個「是」需附上證據連結:
1. 是否有指定的 Orca 管理員?(證據:組織公告或職務說明)
2. 是否有書面的 Agent 權限模式政策(Manual/Auto/Yolo)?(證據:政策文件)
3. 是否有標準設定基準並已套用到所有使用者?(證據:設定檢查紀錄)
4. 是否有版本 Release Ring 與升級檢查清單?(證據:最近一次升級的變更單)
5. 是否每月計算每合併 PR 成本?(證據:月報)
6. 是否有 AI 產出的審查準則並抽查執行?(證據:抽查紀錄)
判定:1~2 題「是」為 L2;3~4 題為 L3;5~6 題且已使用遠端與自動化為 L4。✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 自評有證據 | 每個「是」都能開啟對應連結 | 100% 有證據 | 將無證據的題目改判「否」 |
| 等級判定一致 | 兩位不同角色(工程主管與資安)各自評分 | 結果相同或相差一級以內 | 召開對齊會議釐清差異 |
| 晉級條件明確 | 對照表格「晉級條件」欄 | 有可量測的達標數字 | 補上 31.7 的 KPI 目標值 |
31.2 小型團隊
適用:1~10 人的新創或產品小組。目標:90 天內達到 L2,並證明平行 Agent 在你的程式碼庫上確實有效。
原則:先求「每個人都會用、會審」,再求制度。治理只做三件事:統一 Agent 權限模式、統一分支命名、統一審查標準。
| 里程碑 | 時間 | 交付物 | KPI 與目標(教學示例) | 驗證方式 |
|---|---|---|---|---|
| M1 安裝與首次工作階段 | 第 1 週 | 全員完成第五章實作 | 安裝完成率 100% | 每人提交 git worktree list 截圖與一個 Agent 產出的 PR |
| M2 統一做法 | 第 2~3 週 | 一頁式團隊約定:權限模式、分支命名 agent/<角色>/<編號>、審查清單 | 約定文件已 commit 進 repo | git log --oneline -- docs/orca-team-rules.md 有紀錄 |
| M3 日常使用 | 第 4~8 週 | 每週至少 2 個任務用 Worktree 分工或競賽完成 | Agent 參與的合併 PR 佔比 ≥ 30% | 31.7 KPI-2 指令 |
| M4 效益評估 | 第 9~12 週 | 前後對比報告 | PR 前置時間下降 ≥ 20%,返工率不上升 | 31.7 KPI-1、KPI-4 指令 |
範例:團隊約定(可直接 commit 為 docs/orca-team-rules.md)
# Orca 使用約定
- Agent 權限:Settings → Agents → Agent permissions 一律設為 Auto(支援者)或 Manual;禁止在主 checkout 使用 Yolo。
- 分支命名:agent/<角色>/<Issue 編號>,例如 agent/backend/142。
- Commit trailer:AI 參與的 commit 加上一行 AI-Agent: <agent 名稱>。
- 合併:一律經 PR,至少一位人類 Approve;不得直接合併 Agent 分支到 main。
- 平行上限:每人同時活躍 Agent 不超過 3 個。🧑⚖️ 人工 Review 要點(若此約定由 AI 起草,審查者應確認)
- 權限模式名稱與目前版本 Settings 一致(v1.4.232 起為 Manual、Auto、Yolo)
- 分支命名可被
git branch --list 'agent/*'篩出 - 沒有要求團隊做 Orca 不支援的事(例如「Orca 自動把 Attribution 寫入 git」——官方說明 Attribution 只存在本機)
❌ 常見錯誤:小團隊一開始就導入八角色 AI Team(第二十一章),結果審查負擔超過人力,兩週後回到單一 Agent。先用 2~3 個角色驗證流程。
31.3 中型企業
適用:數十到數百人的工程組織、多個產品團隊。目標:6 個月內達到 L3。
關鍵角色:1~2 名 Orca 管理員(平台組),負責標準設定基準、版本 Release Ring、教材與帳號治理;每個團隊 1 名 Champion,負責在地推廣與回饋。
| 里程碑 | 時間 | 交付物 | KPI 與目標(教學示例) | 驗證方式 |
|---|---|---|---|---|
| M1 試點 | 第 1~2 個月 | 2 個團隊依 31.2 完成 L2 | 試點團隊 KPI-1 改善 ≥ 15% | 31.7 KPI-1 指令,前後各一個月 |
| M2 標準設定基準 | 第 3 個月 | 依第六章 6.9 建立標準設定基準與檢查表 | 套用率 ≥ 90% | 抽查 10 台工作站的 Settings 截圖 |
| M3 Release Ring | 第 3 個月 | 29.1.3 的三環機制與累積相容性清單 | 升級後 7 天內 P1 事件 0 件 | 事件管理系統查詢 |
| M4 Prompt Library 與審查準則 | 第 4 個月 | 第二十二章審查準則、第三十六章 Prompt Library 內部版 | 審查覆蓋率 100% | 31.7 KPI-3 指令 |
| M5 用量治理 | 第 5 個月 | 30.4 的月度成本報表 | 每 PR 成本已連續兩個月產出 | 月報存檔 |
| M6 推廣 | 第 6 個月 | 其餘團隊完成教育訓練 | 活躍使用者 ≥ 目標人數的 70% | 31.7 KPI-5 方法 |
治理重點
- 標準設定基準至少涵蓋:Agent 權限模式、「Trust the folder when Orca starts an agent」是否開啟、Telemetry 政策、Artifacts 公開連結(預設關閉,維持關閉)、Hibernation 開啟與閒置窗口。
- 帳號:採 BYO 訂閱時,公司要明確規定「哪些 Provider、哪些方案」可以用在公司程式碼上,並定期盤點 Settings → Accounts。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 管理員與 Champion 已任命 | 組織公告 | 每個採用團隊都有 Champion | 未任命的團隊暫緩推廣 |
| 設定基準已落地 | 抽查工作站 Settings | 與基準一致 | 由 Champion 協助修正並記錄原因 |
| 試點效益可重現 | 第二個試點團隊也達標 | KPI 改善方向一致 | 分析差異(程式碼庫特性、任務類型) |
31.4 大型企業
適用:數百人以上、多事業群、多種程式碼託管平台。目標:12 個月內主要事業群達到 L4。
關鍵組織:成立 AI 開發工具卓越中心(CoE),成員包含平台工程、資安、法務、採購、財務代表。CoE 負責「選型清單、安全基準、成本分攤、稽核抽查」,各事業群保有在基準內調整的彈性。
| 里程碑 | 時間 | 交付物 | KPI 與目標(教學示例) | 驗證方式 |
|---|---|---|---|---|
| M1 CoE 成立與政策 | 第 1~2 個月 | AI 開發工具政策:核准 Provider 清單、權限模式、資料分級對應 | 政策經資安與法務簽核 | 簽核紀錄 |
| M2 軟體派送 | 第 2~3 個月 | 以既有派送工具(Intune、Jamf、套件庫)派送核准版本;Ring 機制 | 派送覆蓋率 ≥ 95% | 派送系統報表與 29.1.4 版本盤點 |
| M3 多事業群試點 | 第 3~5 個月 | 每個事業群至少一個 L2 團隊 | 各事業群 KPI-1、KPI-4 皆有基準值 | 31.7 指令 |
| M4 遠端與集中算力 | 第 5~8 個月 | SSH 主機或 Remote Orca Servers 標準映像與存取控制(第十八章、第二十八章) | 重度任務移轉到遠端的比例 ≥ 50% | 抽樣統計 Worktree 執行位置 |
| M5 自動化與 Orchestration | 第 7~10 個月 | 核准的 Scheduled Automations 範本與 Orchestration 使用規範 | 自動化任務成功率 ≥ 90% | 31.7 KPI-6 方法 |
| M6 成本分攤與稽核 | 第 9~12 個月 | 依事業群的成本報表與季度稽核 | 每 PR 成本、逃逸缺陷率連續兩季穩定 | 稽核報告 |
治理重點
- GitHub Enterprise 與 SSO:gh 需針對企業主機名登入(
gh auth login --hostname <企業主機>),私有組織 repo 的 token 可能需要 SAML SSO 授權(第十五章、29.5)。 - 託管平台差異:GitLab、Bitbucket 等整合程度與 GitHub 不同,事業群若使用不同平台,需各自驗證(第十五章 15.5)。
- Telemetry 政策:可用 Settings → Privacy 或環境變數
ORCA_TELEMETRY_DISABLED=1、DO_NOT_TRACK=1停用匿名 Telemetry;大型企業通常會在派送設定中統一處理(第二十八章)。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 版本一致性 | 從派送系統匯出版本分布 | 95% 以上在核准版本範圍內 | 追查未更新原因(離線、權限) |
| Telemetry 政策落地 | 抽查使用者環境變數或 Settings → Privacy | 與政策一致 | 修正派送設定 |
| 事業群彈性有邊界 | 比對各事業群設定與 CoE 基準 | 差異都有書面核准 | 未核准者回復基準 |
31.5 銀行與高監理產業
適用:銀行、證券、保險、醫療等受監理產業。目標:先在周邊、低風險系統達到 L2,核心系統暫緩,待治理成熟後再評估。
原則:所有 Agent 產出一律視為「草案」;既有的變更管理、職責分離、雙軌測試與簽核層級不因導入 AI 工具而簡化。
| 里程碑 | 時間 | 交付物 | KPI 與目標(教學示例) | 驗證方式 |
|---|---|---|---|---|
| M0 風險評估 | 第 1~2 個月 | 威脅模型(第二十八章 28.1)、資料分級、Provider 資料處理條款審閱 | 法遵、風控、資安簽核 | 簽核紀錄 |
| M1 受控環境 | 第 2~3 個月 | 專用工作站或遠端主機;Agent 權限 Manual;關閉自動信任資料夾;Artifacts 公開連結維持關閉;Telemetry 依政策 | 設定稽核 100% 符合 | 設定檢查表與截圖 |
| M2 周邊系統試點 | 第 3~6 個月 | 內部工具、報表、測試資料產生器等非核心系統 | 審查覆蓋率 100%;逃逸缺陷 0 件 | 31.7 KPI-3、KPI-7 |
| M3 稽核軌跡 | 第 4~6 個月 | 每個 PR 保存 Prompt、Diff 匯出(含 Attribution metadata)、審查紀錄 | 抽查 20 個 PR 證據完整率 100% | 稽核抽查報告 |
| M4 擴大評估 | 第 7 個月以後 | 是否延伸到次核心系統的評估報告 | 委員會決議 | 會議紀錄 |
Orca 設定對應(高監理建議值)
| 控制目標 | Orca 設定或做法 | 參考章節 |
|---|---|---|
| Agent 不可自行執行未核准指令 | Settings → Agents → Agent permissions 設為 Manual | 第七章 7.2、第二十八章 |
| 保留 Agent 自身的資料夾信任提示 | 關閉「Trust the folder when Orca starts an agent」 | 第六章 6.5 |
| 區分 AI 與人工撰寫的程式碼 | Attribution(本機)+從 Diff 工具列匯出 metadata 存檔 | 第十四章 14.4 |
| 防止程式碼經公開連結外流 | Settings → Artifacts「Allow publishing public artifact links」維持關閉 | 第二十八章 |
| 行動端存取控管 | 評估是否允許 Mobile Companion;如允許,限定公司管理裝置 | 第十九章 |
| 憑證外洩風險修補 | 確認未停留在 v1.4.219~220;檢查 ~/.copilot/config.json 權限 | 29.2.1 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 權限模式 | 抽查 Settings → Agents | 全部為 Manual | 列為稽核缺失並限期改正 |
| 檔案權限 | ls -l ~/.copilot/config.json(macOS、Linux) | 僅擁有者可讀寫(例如 -rw-------) | chmod 600 ~/.copilot/config.json 並評估輪替 token |
| 稽核證據完整 | 抽查 PR 是否附 Prompt、Diff 匯出、審查紀錄 | 100% 完整 | 補件並檢討流程 |
| 核心系統未誤用 | 搜尋核心系統 repo 的 Agent 分支 | git branch -r --list 'origin/agent/*' 無結果 | 立即停止並啟動事件處理 |
❌ 常見錯誤:以「只是內部工具」為由跳過法遵參與,事後才發現內部工具也處理了客戶資料。
31.6 政府與系統整合商
適用:政府機關、公部門專案、為多個客戶開發的 SI。目標:以 PoC 取得可否使用的明確結論,再決定是否進入 L2。
特殊考量
- 採購與成本結構:Orca 本身為 MIT 開源、免授權費,但底層 Agent CLI 需要訂閱或 API 費用;預算編列要分開列示(30.4)。
- 資料落地與供應商審查:BYO 模式下,程式碼會送往你選擇的 AI Provider;需確認該 Provider 的資料處理地點與條款符合法規與契約。
- 版本鎖定:若採購或資安規範要求固定版本,需自行保存核准版本的安裝檔(GitHub Releases 提供舊版),並以 29.2 的清單評估每次升級。
- SI 的多客戶隔離:不同客戶的程式碼、帳號、遠端主機必須隔離。最保守的做法是「一個客戶一個作業系統帳號或一台工作站」,避免 Orca 的帳號清單、瀏覽器 Profile 與 Session History 混用。
| 里程碑 | 時間 | 交付物 | KPI 與目標(教學示例) | 驗證方式 |
|---|---|---|---|---|
| M1 PoC 規劃 | 第 1 個月 | PoC 範圍:非正式環境、非機敏程式碼;評估指標 | 計畫書經資安核可 | 核可公文或紀錄 |
| M2 PoC 執行 | 第 2~3 個月 | 3~5 個代表性任務的前後對比 | 至少 3 個任務 KPI-1 改善 | 31.7 指令與任務紀錄 |
| M3 合規評估 | 第 3 個月 | 資料流向圖、Provider 條款比對、Telemetry 設定 | 無不可接受風險 | 評估報告 |
| M4 決策 | 第 4 個月 | 採用、有條件採用或不採用 | 決策有書面依據 | 會議紀錄 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 客戶隔離 | 檢查各工作站的 Settings → Accounts 與 Repository 清單 | 每台只有單一客戶的帳號與 repo | 立即移除並記錄 |
| 預算分列 | 檢查預算書 | 工具(0 元授權費)與 Provider 訂閱分列 | 修正預算書 |
| 版本可追溯 | 保存的安裝檔雜湊與 GitHub Releases 比對 | 一致 | 重新下載並記錄雜湊 |
31.7 導入里程碑與驗收指標
31.7.1 KPI 定義總表
| 代號 | KPI | 定義與公式 | 資料來源 | 建議目標(教學示例) |
|---|---|---|---|---|
| KPI-1 | PR 前置時間 | 合併 PR 的(mergedAt − createdAt)平均小時數 | GitHub API | 導入後下降 15~30% |
| KPI-2 | Agent 參與率 | 含 AI trailer 或來自 agent/ 分支的合併 PR ÷ 全部合併 PR | Git 歷史、GitHub API | 試點期 ≥ 30% |
| KPI-3 | 審查覆蓋率 | 至少一位人類 Approve 的合併 PR ÷ 全部合併 PR | GitHub API | 100% |
| KPI-4 | 返工率 | 期間內 Revert commit 數 ÷ 合併 PR 數 | Git 歷史 | 不高於導入前 |
| KPI-5 | 活躍使用者 | 期間內至少建立 1 個 agent/ 分支的人數 | Git 歷史 | 依推廣目標 |
| KPI-6 | 自動化成功率 | 成功的排程執行 ÷ 全部排程執行 | Automations 執行紀錄 | ≥ 90% |
| KPI-7 | 逃逸缺陷率 | 上線後發現、可追溯到 AI 參與 PR 的缺陷 ÷ AI 參與合併 PR | Issue 系統 | 不高於人工 PR |
| KPI-8 | 每合併 PR 成本 | 月度工具總成本 ÷ 合併 PR 數(30.4.4) | Provider 主控台、發票 | 逐月下降或持平 |
📌 查證狀態:教學示例(非官方)|KPI 依賴團隊遵守 31.2 的分支命名與 commit trailer 約定;Orca 的 Attribution 只存在本機、不會寫入 git,因此不能直接用來做跨團隊統計。
31.7.2 KPI 計算指令
KPI-1 PR 前置時間
gh pr list --repo org/app --state merged \
--search "merged:2026-10-01..2026-10-31" --limit 1000 \
--json createdAt,mergedAt \
--jq '[.[] | ((.mergedAt | fromdate) - (.createdAt | fromdate)) / 3600] | (add / length)'KPI-2 Agent 參與率(以分支前綴計算)
total=$(gh pr list --repo org/app --state merged --search "merged:2026-10-01..2026-10-31" \
--limit 1000 --json number --jq 'length')
agent=$(gh pr list --repo org/app --state merged --search "merged:2026-10-01..2026-10-31 head:agent/" \
--limit 1000 --json headRefName --jq '[.[] | select(.headRefName | startswith("agent/"))] | length')
echo "agent=$agent total=$total"KPI-3 審查覆蓋率
gh pr list --repo org/app --state merged --search "merged:2026-10-01..2026-10-31" \
--limit 1000 --json number,reviews \
--jq '[.[] | select([.reviews[] | select(.state == "APPROVED")] | length > 0)] | length'KPI-4 返工率(Revert 次數)
git -C ~/src/app log --since=2026-10-01 --until=2026-11-01 --oneline --grep='^Revert' | wc -lKPI-5 活躍使用者
git -C ~/src/app fetch --prune
git -C ~/src/app for-each-ref --format='%(authoremail)' 'refs/remotes/origin/agent/' | sort -u | wc -lKPI-2 補充:以 commit trailer 計算
git -C ~/src/app log --since=2026-10-01 --until=2026-11-01 --format='%H' --grep='^AI-Agent:' | wc -l✅ 驗證方式
先用一個已知結果的小範圍驗證指令正確性,例如只查一天:
gh pr list --repo org/app --state merged --search "merged:2026-10-15" --json number,createdAt,mergedAt手動計算這幾筆 PR 的前置時間,與 KPI-1 指令在同一天範圍的輸出比對。
預期輸出(示意,單位為小時):
18.4判讀:手算與指令結果一致,才把指令放進月報自動化;若
--limit小於實際 PR 數,結果會被截斷,請提高上限或分段查詢。
31.7.3 里程碑驗收會議範本
[里程碑] M3 日常使用(小型團隊)
[期間] 2026-11-01 ~ 2026-11-30
[KPI 結果]
- KPI-1 PR 前置時間:導入前 26.0 小時 → 本期 19.5 小時(-25%);指令與原始輸出:附件 A
- KPI-2 Agent 參與率:34%;附件 B
- KPI-4 返工率:導入前 3.1% → 本期 2.8%;附件 C
[質化回饋] 3 位工程師訪談摘要
[風險與事件] 無
[決議] 通過,進入 M4 / 延長 M3 兩週(原因:__)
[簽核] 工程主管__ 資安代表__📌 查證狀態:教學示例(非官方)|範本中的數字為虛構。
❌ 常見錯誤:只報告「速度變快」而沒有返工率與逃逸缺陷率,管理層因此做出擴大導入的決定,三個月後才發現品質下滑。
💡 小技巧:把 31.7.2 的指令放進一個每月排程的 CI Job,輸出成 CSV 歸檔;導入前一個月就先跑一次,取得基準值,否則之後無從比較。
31.8 本章 Review 與驗證清單
- 能用 31.1 自評題判定組織目前的成熟度等級,且每題都有證據
- 已依組織型態選定 31.2~31.6 的其中一條路徑與目標等級
- 已訂定每個里程碑的交付物、KPI 目標與驗證方式
- 已建立團隊約定(分支命名、commit trailer),使 KPI 可以被計算
- 已以小範圍資料驗證 31.7.2 的 KPI 指令正確性
- 導入前已取得 KPI 基準值
- 高監理產業已完成權限模式、資料夾信任、Artifacts、檔案權限的設定稽核
- SI 已落實客戶間的帳號與工作站隔離
- 里程碑驗收會議同時檢視速度、品質與成本三類指標
第三十二章 常見錯誤與 FAQ
本章把讀者在導入 Orca 時最常卡關的問題整理成 105 題問答,依「基礎概念 → 安裝與環境 → Agent 與帳號 → Worktree → Review 與 Git → 遠端與行動端 → 自動化與 CLI → 效能與維運」八大類排列,題號全章連續。每題的回答都遵循同一個原則:先給可執行的處理步驟,再給一個可以自行確認的驗證方法,讓讀者不必「相信」答案,而是能親手證明問題已排除。
📌 查證狀態:官方文件明確記載(排錯項目與指令)+依官方說明延伸(教學推論,處理順序與企業建議)|來源:Troubleshooting & FAQ、Troubleshooting GitHub errors、v1.4.152~v1.4.244 Release Notes
如何使用本章
- 先用
Ctrl+F搜尋錯誤訊息中的關鍵字(例如SUN_LEN、browser_no_tab、rate limit),通常可以直接定位到對應題目。 - 依答案中的步驟處理,每完成一步就執行一次驗證指令,避免一次改太多設定而無法判斷是哪一步生效。
- 若答案指向其他章節(例如第十八章 SSH 設定),請回到該章閱讀完整背景,本章只提供最短修復路徑。
- 處理後仍無法解決,請依 Q99 收集 Log 並回報,回報內容不得包含 Token、私鑰或客戶資料。
通用排錯流程(適用於所有題目)
flowchart TD
A["發現異常"] --> B{"在 Orca 外的一般終端機能否重現"}
B -- "能重現" --> C["問題在 CLI/git/gh/網路本身"]
B -- "只在 Orca 內發生" --> D["檢查 Orca 設定與版本"]
C --> E["修正工具安裝、登入或網路後再回 Orca 驗證"]
D --> F{"更新至最新版後是否仍發生"}
F -- "已解決" --> G["記錄於團隊已知問題清單"]
F -- "仍發生" --> H["Help → Open Logs 收集紀錄並回報"]
E --> G如何閱讀此圖:任何問題第一步都先判斷「是 Orca 的問題,還是底層工具的問題」。Orca 本身是協調層,Agent CLI、git、gh、SSH 都是它呼叫的外部程式;只要在 Orca 外的一般終端機也能重現,就應先修外部工具。只有在 Orca 內才發生時,才進入「更新版本 → 收集 Log → 回報」的路徑。
32.1 基礎概念
Q1:Orca 是一個會自己寫程式的 AI 嗎?
**A:**不是。Orca 是 ADE(Agent Development Environment),本身不內建推理模型,而是把 Claude Code、Codex、OpenCode 等既有的 Agent CLI 放進各自獨立的 Git Worktree 中平行執行,並提供監看、審查、合併與治理的介面。實際寫程式的是你選用的 Agent CLI。驗證方式:在 Orca 中啟動任一 Agent 後,於該分頁執行 ps 或在工作管理員查看程序,會看到 claude、codex 等 CLI 程序,而不是 Orca 自有的模型程序。詳見第一章。
Q2:ADE 和 IDE 差在哪裡?
**A:**IDE 以「一個人編輯一份程式碼」為中心;ADE 以「一個人指揮多個 Agent 在多份隔離的程式碼副本上平行工作」為中心,人的角色從打字者轉為分派者與審查者。導入教育訓練時,建議用第五章的「三個 Agent 同題競賽」實際操作一次,讓學員體會角色轉換。驗證方式:學員能在不看文件的情況下說出「Worktree 隔離」「平行分派」「人工審查合併」三個關鍵環節。
Q3:導入 Orca 代表要放棄現有的 Claude Code 或 Codex 嗎?
**A:**不需要,反而必須保留。Orca 是疊加在 Agent CLI 之上的協調層,沒有 Agent CLI 就無法運作。處理步驟:
- 在一般終端機確認現有 CLI 可正常使用,例如執行
claude --version、codex --version。 - 對照 Supported agents 確認該 CLI 是否已內建於 Orca 的 Agent 選單。
- 開啟 Settings → Agents,確認該 CLI 出現在 Installed agents 清單中。
驗證方式:在 Orca 建立 Worktree 時,Agent 下拉選單可以選到該 CLI 並成功啟動。
Q4:Orca 要付費嗎?成本從哪裡來?
**A:**Orca 桌面應用程式為 MIT 授權開源軟體,免費使用;成本來自你自備的 Agent 訂閱或 API 額度(BYO 訂閱模式),若使用 SSH 主機、Remote Orca Server 或 Cloud VM,另有你自己的主機或雲端帳單。Orca 不販售託管 VPS。處理步驟:導入前盤點團隊各 Agent 的訂閱方案,並在 Orca 狀態列的 Usage 名單觀察實際用量。驗證方式:開啟狀態列 Usage 彈出視窗,確認每個 Provider 都顯示方案與重設時間;成本估算方式見第八章與第三十章。
Q5:單人開發者適合用 Orca 嗎?
**A:**適合,但效益型態不同。單人最常見的用法是「同一任務開兩到三個 Worktree,讓不同 Agent 各自實作,再挑最好的一份」。建議從兩個 Worktree 起步,熟悉後再擴增。驗證方式:完成一次同題競賽,並能以 git diff main...<branch> --stat 比較兩個方案的變更範圍。
Q6:為什麼 Orca 要用 Worktree,而不是在同一個目錄切換分支?
**A:**因為多個 Agent 若共用同一份工作目錄,會互相覆寫檔案、互相干擾建置產物。Git Worktree 讓每個任務擁有獨立的檔案樹與分支,但共用同一個 .git 物件庫,既隔離又節省空間。驗證方式:
git worktree list預期每個 Orca 任務都對應一行獨立路徑與分支名稱。若只看到主目錄一行,代表尚未建立任何 Worktree。
Q7:使用 Orca 需要註冊帳號嗎?
**A:**核心功能不需要。官方說明 Orca 沒有帳號系統,Telemetry 也只使用本機產生的匿名 ID。只有兩種情境需要登入 Orca 帳號:一是行動端透過 Orca Relay 配對,二是發佈公開的 Artifact 連結(Settings → Artifacts,預設關閉)。驗證方式:未登入狀態下仍可新增 Repository、建立 Worktree 並啟動 Agent。
Q8:Orca 會把我的程式碼上傳到 Orca 的伺服器嗎?
**A:**依官方 Telemetry 說明,Orca 不會傳送檔案內容、Prompt、Agent 輸出、終端機內容、Repo 名稱、分支名稱、路徑或 Commit 訊息。但要注意:你選用的 Agent CLI 會把 Prompt 與相關程式碼送往該 Agent 的模型供應商,這屬於 Agent 供應商的資料政策,不是 Orca 的。處理步驟:若要完全關閉 Orca 匿名統計,到 Settings → Privacy 關閉「Share anonymous usage data」,或設定環境變數 ORCA_TELEMETRY_DISABLED=1。驗證方式:重新開啟 Settings → Privacy,確認開關維持關閉。詳見第三章與第二十八章。
Q9:Orca 到底支援哪些 Agent?要怎麼確認最新清單?
**A:**截至 v1.4.244,官方 Supported agents 頁面列出 40 餘個預先設定的 Agent,包含 Claude Code、Codex、Cursor CLI、GitHub Copilot CLI、Gemini、OpenCode、Grok、Muse Code、ZCode、DeepSeek Harness、Qoder CLI、Qwen Code、Rovo Dev、Antigravity 等;此外 Orca 也能啟動任何 CLI,因為 Agent 選單本質上只是在終端機啟動一個程序。驗證方式:開啟 Settings → Agents 查看 Installed agents,或直接閱讀 Supported agents。由於幾乎每日發版,請以官方頁面為準,本書清單見第七章。
Q10:Orca 有繁體中文介面嗎?
**A:**有。v1.4.244 新增德文、俄文、土耳其文與繁體中文介面。操作步驟:開啟 Settings → Appearance → Language,選擇「繁體中文」。若目前介面是英文,可在 Settings 搜尋框輸入「語言」或「Language」快速定位。驗證方式:切換後 Settings 分類名稱與主要選單改以繁體中文顯示。注意部分新功能的字串可能仍為英文,屬正常現象,本書保留英文功能名稱以便對照。
Q11:本手冊的說明與官方文件不一致時,以誰為準?
**A:**以官方文件與最新 Release Notes 為準。本書對應 v1.4.244(2026-10-29),而 Orca 幾乎每日發版。處理步驟:
- 先在 Settings → General → Updates 確認自己的版本號。
- 對照附錄 C 的版本差異紀錄,判斷差異是否來自版本落差。
- 閱讀 GitHub Releases 中較新版本的說明。
驗證方式:團隊內部的規範文件應標註「對應 Orca 版本」與「查證日期」,每季複核一次。
32.2 安裝與環境
Q12:Orca 有哪些官方安裝管道?
**A:**官方提供下列管道:macOS(Apple Silicon、Intel 的 .dmg)、Windows 安裝程式、Linux 的 AppImage/.deb/.rpm,以及 macOS Homebrew cask 與 Arch Linux AUR。舊版本一律可在 GitHub Releases 下載。驗證方式:安裝後開啟 Settings → General → Updates 能看到版本號,且可執行 Check for Updates。
# macOS(Homebrew,務必使用完整名稱)
brew install --cask stablyai/orca/orca
# Arch Linux(AUR)
yay -S stably-orca-binQ13:我執行 brew install --cask orca 結果裝到不相干的軟體?
**A:**官方 README 特別提醒:單獨的 orca cask 是另一個與 Plotly 有關的套件,不是 Orca ADE。處理步驟:
- 移除誤裝的套件:
brew uninstall --cask orca。 - 改用完整名稱安裝:
brew install --cask stablyai/orca/orca。 - 日後升級同樣使用完整名稱:
brew upgrade --cask stablyai/orca/orca。
驗證方式:執行 brew info --cask stablyai/orca/orca,確認來源為 stablyai/orca tap。
Q14:macOS 第一次開啟 Orca 跳出確認視窗,是不是下載到假的安裝檔?
**A:**官方說明 macOS 版本已簽章並通過公證,首次開啟時 macOS 仍可能要求確認,這對 Electron 應用屬正常現象。處理步驟:只從官方下載頁、GitHub Releases 或 Homebrew 取得安裝檔,再於提示中選擇開啟。驗證方式:
codesign -dv --verbose=2 /Applications/Orca.app 2>&1 | head -5
spctl -a -vv /Applications/Orca.app預期 spctl 顯示 accepted 且來源為 Notarized Developer ID。若顯示 rejected,請刪除檔案並重新從官方來源下載。
Q15:Linux 上 AppImage 無法執行或不會自動更新?
**A:**AppImage 需要執行權限,部分發行版還需要 FUSE 相關套件。另外官方說明:只有 AppImage 會自行更新;.deb/.rpm 版本只會提示有新版並給出套件管理器指令,執行該指令前需先完全關閉 Orca。處理步驟:
chmod +x ./orca-linux.AppImage
./orca-linux.AppImage若出現 FUSE 相關錯誤,請安裝發行版對應的 FUSE 2 相容套件(例如 Ubuntu 的 libfuse2 或新版的 libfuse2t64)。驗證方式:AppImage 可正常開啟,且 Settings → General → Updates 能檢查更新。
Q16:Linux 上輸入 orca 卻打開了螢幕閱讀器?
**A:**GNOME 桌面內建同名的 Orca 螢幕閱讀器。官方因此將 Linux 版 CLI 命名為 orca-ide。處理步驟:在 Linux 腳本與文件中一律使用 orca-ide,或在自己的 shell 設定中建立別名。驗證方式:
command -v orca-ide
orca-ide status --json預期能回傳 Orca 執行階段的狀態 JSON。注意:本書其他章節的 CLI 範例以 orca 表示,Linux 使用者請自行替換。
Q17:Windows 安裝後 orca 指令要求安裝 Visual C++ Redistributable?
**A:**自 v1.4.219 起,Windows 版內建的 orca 已改為原生程式,不再需要 Visual C++ Redistributable,且安裝程式會自動加入 PATH。若仍遇到此提示,代表你使用的是舊版。處理步驟:更新至 v1.4.219 以上版本,然後完全關閉並重開所有終端機。驗證方式:在新的 PowerShell 執行:
Get-Command orca
orca status --jsonQ18:Orca 支援 WSL 嗎?
**A:**支援。Windows 的預設 shell 可在 Settings → Terminal → Default shell 選擇 PowerShell、Command Prompt 或 WSL;Codex 也可從 WSL distro 新增帳號,Orca 會在 distro 內建立隔離的帳號目錄。v1.4.214 起 managed WSL 終端機自帶 Orca CLI,v1.4.242 起 WSL 主機不再每次重啟都重新配對且記憶體用量大降,v1.4.244 起 distro 停止後仍保留終端 session 與目錄。處理步驟:確保 Agent CLI 安裝在你實際要執行的環境(Windows 原生或 WSL 內),兩邊不會互通。驗證方式:在 Orca 的 WSL 終端機執行 which codex 與 codex --version,確認是 distro 內的版本。
Q19:官方有 Docker 映像檔嗎?可以把 Orca 放進容器嗎?
**A:**官方未發布現成的 Orca 桌面 Docker 映像檔。容器相關的官方路徑有兩種:一是以 orca serve 在無頭 Linux 主機或由服務管理器管理的 VM 中執行 Orca 執行階段(orca serve --supervise 適合容器內由外部重啟的情境);二是 Settings → Experimental → Cloud VM 的每工作區環境,Recipe 可以使用本機 Docker 作為 Provider。驗證方式:在容器內執行 orca serve --pairing-address <可達位址> 後,從桌面端 Settings → Remote Orca Servers → Add Server 貼上配對網址並顯示 Connected。企業自行組裝的映像檔須標示為「非官方」,並納入內部弱點掃描。
Q20:如何試用 RC 版本?升級後不滿意能降版嗎?
**A:**Orca 預設追蹤 stable 頻道,沒有永久性的 RC 開關。在 Settings → General → Updates 的 Check for Updates 上:Shift+點擊取得最新 RC;Cmd+點擊(macOS)或 Ctrl+點擊(Windows/Linux)取得最新效能標記預發布版;Option+點擊(僅 macOS)挑選通過相容性檢查的本機建置。若要降版,從 GitHub Releases 下載舊版安裝即可,官方說明降版不會強制降級你的 Worktree 資料。驗證方式:安裝後於 Updates 區塊確認版本號;企業環境建議只在測試機使用 RC。
Q21:第一次啟動時 Orca 要求存取家目錄、還問要不要匯入設定,可以拒絕嗎?
**A:**首次啟動時 Orca 會要求家目錄存取權(才能加入 Repository),並在偵測到 ~/.claude、~/.codex 與 Ghostty 終端機設定時詢問是否匯入。家目錄權限拒絕後將無法正常加入專案;匯入設定則可略過,日後在 Settings 中手動調整。驗證方式:完成首次啟動後,能從空白的起始畫面成功加入第一個 Repository。
Q22:公司有 Proxy 與防火牆,Orca 需要開放哪些連線?
**A:**Orca 本身需要連線檢查更新(v1.4.243 起更新檢查會使用 Settings 中的代理設定);Agent CLI 需要連到各自的模型供應商;GitHub 整合透過 gh 連到 api.github.com;SSH managed server 首次連線需下載 Node.js 執行階段(可改用內部 mirror,見 Q73);行動端 Relay 配對需要連到 Orca Relay。處理步驟:依實際使用的 Agent 與功能列出網域清單,向資安單位申請白名單。驗證方式:
gh api user --jq .login
curl -sI https://api.github.com | head -1再於 Orca 內實際啟動一次各 Agent 並送出簡單 Prompt。
Q23:開啟 Orca 時跳出「要使用哪一份 profile」的詢問?
**A:**v1.4.214 起 Orca 的 profile 儲存遷移到 SQLite。若 JSON 與 SQLite 兩份 profile 都可讀但內容不一致,Orca 會顯示各自最後儲存的時間,讓你選擇 Use SQLite (Recommended) 或 Use JSON,選定後 Orca 會套用並重新啟動;若想先檢查兩份內容,請選 Quit。處理步驟:一般情況選 Use SQLite;若你確定最近的變更只存在 JSON(例如剛從舊版降級回來),才選 Use JSON。驗證方式:重新啟動後確認 Repository 清單、Worktree 與快捷鍵設定完整。
Q24:Windows 新開的終端機要等好幾秒才出現提示字元?
**A:**v1.4.244 已修正此問題(原本約需 3 秒),但此修正執行在背景的 terminal host 內,而 v1.4.244 沿用 v1.4.243 的 terminal host,因此必須等 terminal host 重新啟動(例如重新開機)後才會生效。處理步驟:更新至 v1.4.244 後,在方便的時間點關閉所有終端機或重新開機。驗證方式:重開機後在 Orca 開新終端機,提示字元應立即出現。
32.3 Agent 與帳號
Q25:Agent 啟動不了,該從哪裡查起?
**A:**依官方建議的順序排查:
- 在 Orca 以外的一般終端機執行該 Agent CLI。若在外面也失敗,問題出在 CLI 安裝或登入,請先修好 CLI。
- 若只在 Orca 內失敗,開啟 Settings → Agents,確認該 CLI 位於 Orca 看得到的 PATH,必要時在 per-agent launch defaults 指定執行檔完整路徑。
- 點擊分頁上的 Restart chip 重新啟動 Agent。
驗證方式:
command -v claude
claude --version在 Orca 內的終端機與外部終端機執行結果應一致。若 Orca 內找不到指令,代表 PATH 不同,請完全關閉並重開 Orca 讓它重新讀取環境。
Q26:Codex 啟動時報錯「path must be shorter than SUN_LEN」?
**A:**Codex 0.157 以後的背景 daemon 使用 Unix socket,若 Orca 管理的帳號目錄路徑太長,就會超過 socket 路徑長度上限。官方修正方式是更新 Orca 至 v1.4.212 以上:Orca 會自動對受影響的帳號目錄關閉 daemon,讓 Codex 能正常啟動;不需要搬移帳號,也不需要修改系統的 ~/.codex/config.toml。副作用是該帳號目錄下無法使用 codex agents 與依賴 daemon 的 resume/continuation。驗證方式:更新後重新開啟 Codex 分頁,錯誤訊息消失;並確認 Settings → General → Updates 顯示版本 ≥ v1.4.212。
Q27:為什麼 Orca 啟動的 Agent 預設會略過權限確認?要怎麼改回手動核准?
**A:**Orca 預設為新啟動的 Agent 帶入各 CLI 的權限略過旗標(例如 Claude 的 --dangerously-skip-permissions、Codex 的 --dangerously-bypass-approvals-and-sandbox、多數 CLI 的 --yolo),理由是 Worktree 屬於可拋棄的隔離副本。企業環境若需人工核准,處理步驟:
- 開啟 Settings → Agents → Agent permissions,選擇 Manual(每次核准)、Auto(Claude、Claude Agent Teams、Codex 自行核准例行動作)或 Yolo。
- 若選 Auto,再用 Other agents 為不支援 Auto 的 Agent 指定 Manual 或 Yolo。
- 已自訂 launch arguments 的 Agent 不會被全域開關改變,需手動編輯該 Agent 的預設參數。
驗證方式:新開一個 Claude 分頁,觀察啟動指令列不再包含略過旗標,且執行 shell 指令前會詢問。注意既有 Chat 保留原本模式,只有新 Session 生效。詳見第七章與第二十八章。
Q28:Agent 啟動時不再問「是否信任此資料夾」,這安全嗎?
**A:**v1.4.219 起,Orca 啟動的 Agent(包含 Orchestration worker、Automations、從手機啟動的 Agent)會自動回應 Claude Code、Codex、Cursor、Copilot、Qoder、Antigravity 等的「Trust this folder」提示,預設開啟。若組織要求保留每次信任確認,處理步驟:到 Settings → Agents 關閉「Trust the folder when Orca starts an agent」。驗證方式:關閉後在一個新 Worktree 啟動 Claude Code,應再次出現信任提示。
Q29:切換 Codex 或 Claude 帳號後,正在跑的 Agent 為什麼還是用舊帳號?
**A:**這是設計行為:帳號切換只影響「之後新啟動」的 Session,已在執行的程序維持原帳號直到重新啟動。處理步驟:
- 點擊狀態列的 Codex(或 Claude)chip 開啟帳號切換器,選擇目標帳號。
- 對需要改用新帳號的分頁點擊 Restart chip。
驗證方式:重新啟動後,狀態列的用量讀數應改為新帳號的額度;Codex 可在該分頁執行 codex login status(依 Codex 版本而定)確認目前登入身分。
Q30:我改了 ~/.codex/config.toml,但 Orca 管理的 Codex 帳號好像沒套用?
**A:**Orca 會把你真實的 ~/.codex/config.toml 鏡像到目前作用中帳號的執行目錄。若來源檔遺失、為空(例如雲端同步尚未下載完成)或無法讀取,Accounts 會顯示警告,並沿用最後一次成功同步的設定。處理步驟:依警告橫幅指出的路徑修正檔案,然後重新啟動 Codex 或重新選取該帳號。驗證方式:
test -s ~/.codex/config.toml && echo "config ok"確認輸出 config ok,且 Settings → Agents → Codex Accounts 的警告消失。
Q31:在 Orca 開的 Codex Session,codex agents 或 Codex 桌面版都看不到?
**A:**v1.4.217 起,每個 Codex 分頁預設執行自己的背景 server,好處是狀態準確、關閉一個分頁不會影響其他分頁;代價是 Codex 的共享 server 功能(背景執行、codex agents、Codex 桌面版或 IDE 開啟的 Session)看不到 Orca 內的 Session,記憶體用量也較高。若需要共享,處理步驟:
- 關閉 Settings → Agents → Run each Codex terminal on its own server。
- 或在 shell 啟動檔加入
export ORCA_CODEX_ISOLATE=0。 - 開啟新的終端機(既有終端機維持舊行為)。
驗證方式:在新開的 Codex 分頁執行 codex agents,應可列出 Orca 內的 Session。
Q32:Windows 更新 Orca 後,Codex 又要求信任資料夾,而且我加過的 MCP server 不見了?
**A:**v1.4.221 起 Windows 版 Codex 改用與 macOS/Linux 相同的真實 ~/.codex 目錄。官方說明第一次出現 Codex 終端機時會提示:Codex 可能再次詢問信任資料夾或核准指令,而且「只在 Orca 內新增」的 MCP server 需要重新加入。處理步驟:依提示重新信任,並把 MCP server 加回 ~/.codex/config.toml。驗證方式:在新開的 Codex 分頁執行 codex mcp list,確認 MCP server 出現在清單中。
Q33:狀態列的 Usage 顯示「Usage unavailable」或「not signed in」?
**A:**Usage 追蹤依 Provider 而異:Claude、Codex 讀本機狀態;Cursor 讀現有的 Cursor 登入;OpenCode Go 需要在 Settings 貼上完整的 opencode.ai Cookie 標頭(含 __Host-console_session);MiniMax 需要在 Settings → Integrations 貼上 session cookie;GLM Coding Plan 可在 Settings → Accounts → GLM Coding Plan 存入方案 API Key。處理步驟:依 Provider 補齊設定,Cursor 的登入過期時執行 cursor-agent login,然後在 Usage 彈出視窗按標題列的重新整理。驗證方式:該 Provider 的列改為顯示方案名稱、用量條與重設時間。
Q34:Stats 顯示的預估成本和供應商實際帳單對不起來?
**A:**這是預期行為。官方說明 Stats 使用本機價目表估算,不是供應商的即時帳單;標示「inferred pricing」代表模型是推測的,「excludes unpriced models」代表部分模型未計入。處理步驟:成本治理以供應商主控台的帳單為準,Orca 的數字只用於趨勢觀察與內部預警。驗證方式:每月抽樣比對一次 Stats 與供應商帳單,記錄誤差比例,作為第三十章成本模型的校正依據。
Q35:找不到 Native Chat(結構化聊天)介面,或 Codex Chat 無法開啟?
**A:**Chat UI 需要先啟用,且 Provider 必須在支援範圍內。處理步驟:
- 到 Settings → Experimental 開啟 Chat UI,結構化 Chat 的外觀與 Provider 選項在 Settings → Chat。
- 在 Settings → Chat → Providers 確認要用的 Provider(Claude、Codex、Grok、OpenCode、OMP、Pi、Antigravity 等)已開啟。
- Codex Chat 需要 Codex 0.136.0 以上版本(v1.4.227 起的要求)。
驗證方式:執行 codex --version 確認版本,再新建 Codex Chat,應出現結構化的對話介面而非原始終端機。
Q36:「Continue in New Session」選項不見了?
**A:**v1.4.224 起改名為 Hand Off to Another Agent。它會啟動一個全新的 Agent Session(可選相同或不同 CLI),並從前一份逐字稿注入有長度限制的交接 Prompt;原 Session 保持不動,這不等於 codex resume。若要續接同一個對話,請改用 Agent Session History 的 Resume。驗證方式:在 Agent 終端機標題列或右鍵選單找到 Hand Off to Another Agent,執行後新分頁的第一則訊息應包含交接摘要。
Q37:聽說 Copilot 的設定檔權限有安全問題,我需要處理嗎?
**A:**需要確認。v1.4.221 的 Release Notes 說明:v1.4.219~v1.4.220 可能讓 ~/.copilot/config.json(含 Token)被同機其他使用者讀取,SSH 主機亦同;新版已改為僅擁有者可讀,但舊檔要等下次新增資料夾時才會修正。處理步驟:在本機與每台 SSH 主機上手動收緊權限,並視情況撤銷重發 Token。驗證方式:
chmod 600 ~/.copilot/config.json
ls -l ~/.copilot/config.json預期權限顯示為 -rw-------。
Q38:OpenCode 2 在 Orca 裡無法選模型?
**A:**v1.4.241 起,Orca 會拒絕在 OpenCode 2.0.14、2.0.15、2.0.17、2.0.18 這幾個版本上選擇模型(這些版本有已知問題)。處理步驟:將 OpenCode 升級到不在清單中的版本。驗證方式:執行 opencode --version 確認版本,再於 Orca 的模型選擇器切換模型並送出一則測試訊息。
Q39:更新後 Claude 的 keybindings.json 被加了一個快捷鍵?
**A:**v1.4.242 起 Claude subagent 導覽功能預設開啟,Orca 會在各 Claude 設定資料夾的 keybindings.json 加入一個快捷鍵(Ctrl+Alt+G、H、V 中第一個可用者),已在執行中的 Claude Session 需要重新啟動才會生效。處理步驟:若此快捷鍵與團隊既有設定衝突,請在 keybindings.json 中調整,並將變更納入團隊的設定基準。驗證方式:重新啟動 Claude Session 後,從側邊欄點選 subagent 能開啟其逐字稿。
Q40:側邊欄的 Agent 狀態一直不更新(不顯示 working、done)?
**A:**狀態顯示依賴 Agent status hooks。處理步驟:
orca agent hooks status --json
orca agent hooks on --json也可在 Settings → Agents → Agent status hooks 開啟,切換後立即生效、不需重啟(含 Windows WSL hook relay)。驗證方式:讓 Agent 執行一個簡短任務,側邊欄應依序顯示 working 與 done,且需要你回應時顯示問號圖示(needs you)。
32.4 Worktree
Q41:建立 Worktree 失敗,該怎麼處理?
**A:**官方列出兩個最常見原因:起始 ref 尚未 fetch,或目標目錄已存在該分支的 Worktree。處理步驟:
- 在 Repository 的終端機執行
git fetch origin。 - 執行
git worktree list,若同分支已有 Worktree,刪除它或改用新分支名稱。 - 回到 Worktree 的建立面板按 Retry。
驗證方式:
git fetch origin
git worktree list
git branch -a --list "*<分支名稱>*"確認起始 ref 存在、沒有重複的 Worktree 後,再次建立應成功,側邊欄的進度列會轉為正常卡片。
Q42:新 Worktree 裡沒有 node_modules、.env,Agent 一跑就失敗?
**A:**新 Worktree 是乾淨的 checkout,被 gitignore 的相依套件、快取與本機機密不會自動出現。Orca 提供三種互補機制:
- Settings → Repository → Worktree Shared Paths:個人層級,從主 checkout 實體化到每個新 Worktree(macOS 優先 APFS clone,否則 symlink)。
- Repo 根目錄的
orca.yaml中的worktree.sharedDirectories:適合node_modules、.cache等大型可重建目錄,以共享方式提供。 - Repo 根目錄的
.worktreeinclude:列出要「複製」進每個 Worktree 的檔案,例如.env。
worktree:
sharedDirectories:
- node_modules
- .cache驗證方式:建立新 Worktree 後執行 ls -la node_modules .env,確認目錄與檔案存在。注意列出的路徑必須在主 checkout 中存在且已被 gitignore,否則會被略過。
Q43:.worktreeinclude 寫了 *.env 卻沒有作用?
**A:**官方說明目前只支援字面路徑,glob 與否定規則會被略過並顯示警告;被追蹤、不存在或未被 gitignore 的路徑也不會複製。處理步驟:把萬用字元改為逐一列出實際路徑,例如 .env、.env.local。驗證方式:執行 git check-ignore -v .env .env.local 確認兩個檔案都被 gitignore,再建立新 Worktree 檢查是否已複製。
Q44:刪除 Worktree 時失敗,Workspace 一直留在清單上?
**A:**Orca 讓 git 執行實際刪除,若 git 無法完成(例如檔案被其他程序鎖住),Workspace 會保留在清單上讓你重試。處理步驟:
- 關閉該 Worktree 中的終端機、編輯器與佔用檔案的程序(Windows 常見於防毒或建置程序)。
- 再次刪除;若失敗原因允許,會出現 Force Delete。
- Force Delete 的下拉選單有 Always force delete,會記住此選擇套用到之後所有刪除,企業環境不建議開啟。
驗證方式:執行 git worktree list 確認該路徑已不存在,必要時執行 git worktree prune 清除殘留紀錄。
Q45:批次刪除 Workspace 後出現「Review N Branches」的提示?
**A:**批次刪除會移除磁碟上的資料夾,但若 git 認為某些本機分支可能還有未合併的 Commit,Orca 會保留這些分支並提示你檢視。處理步驟:點開提示,逐一確認分支內容,只對確定不需要的分支執行強制刪除。驗證方式:
git log main..<保留的分支> --oneline若輸出為空,代表沒有未合併 Commit,可安全刪除;有輸出則應先確認是否需要合併或另存。
Q46:我自己用 git worktree add 建立的 Worktree 沒出現在側邊欄?
**A:**外部建立的 Worktree 預設不會自動顯示。處理步驟:點擊側邊欄的 hidden worktrees 卡片,開啟 Non-Orca worktrees,對要顯示的 Worktree 選擇 Show。若要調整全域預設,到 Settings → General → Workspace 設定 Claude Code worktrees、GSD worktrees 等來源的可見性。驗證方式:該 Worktree 出現在側邊欄,且可在其中開啟終端機與 Diff。
Q47:怎麼指定 Worktree 的分支名稱?
**A:**預設由 Workspace 名稱或連結的 PR/Issue 推導分支名稱。若要自訂:在建立對話框展開 Advanced,於 Branch name 欄位輸入(例如 feature/login-audit)。從追蹤中的工作項目建立時,分支由該項目決定,欄位會被隱藏。CLI 自 v1.4.244 起支援 --branch:
orca worktree create --repo id:<repoId> --name login-audit --branch feature/login-audit --json驗證方式:執行 git -C <worktree 路徑> branch --show-current,輸出應為指定的分支名稱。
Q48:Worktree 位置設成 ~/worktrees 結果建立了一個名為 ~ 的資料夾?
**A:**v1.4.244 修正此問題:Worktree 位置中的 ~ 會被解讀為家目錄,舊設定值會在下次啟動時自動展開。處理步驟:更新至 v1.4.244 後重新啟動 Orca,再刪除先前誤建的 ~ 資料夾(刪除前務必確認路徑,避免誤刪真正的家目錄)。驗證方式:建立新 Worktree 後執行 git worktree list,路徑應為家目錄下的實際位置。
Q49:多個 Agent 平行工作,合併時衝突很多怎麼辦?
**A:**Worktree 只保證「工作期間」互不覆寫,合併時的衝突來自任務切分重疊。處理步驟:
- 事前:依模組或檔案邊界切分任務,並在 Prompt 明確禁止修改範圍外的檔案(見第二十章)。
- 事中:用
git diff --stat監看每個 Worktree 是否越界。 - 事後:v1.4.238 起可用 Resolve with AI 協助處理 merge、rebase、cherry-pick 衝突,但結果必須人工審查並重新跑測試。
驗證方式:合併後執行 git diff --check 確認沒有殘留衝突標記,並執行完整測試。
Q50:重新開機後,原本在跑的 Agent 都不見了?
**A:**這是預期行為。Session Restore 依賴背景 daemon 持有 PTY:一般結束 Orca(Cmd-Q)、自動更新重啟或 Orca 當機時,daemon 存活,Agent 會繼續執行;但重新開機、系統更新、強制斷電會讓 daemon 一起結束,下次啟動時只會還原 Worktree、分頁、分割版面與最後保存的捲動紀錄,Agent 程序本身已不存在。處理步驟:在對應分頁重新啟動 Agent,或從 Agent Session History 以 Resume 續接先前對話。驗證方式:重開機後檢查各分頁的捲動紀錄仍在,Resume 後 Agent 能回答先前對話的內容。
Q51:開啟 Agent hibernation 後,Agent 會不會被終止而遺失進度?
**A:**Hibernation(Settings → Experimental → Agent hibernation,預設關閉)只會暫停符合全部條件的終端機:Agent 已完成、不在前景、完成後沒有按鍵輸入、屬於可續接的 Agent(Claude、Codex、Gemini、Antigravity、OpenCode、Pi、Droid、Grok、Devin、OMP 等)、閒置超過設定時間(預設 30 分鐘)、沒有行動端操作中、沒有未結束的 Orchestration Dispatch。重新開啟 Worktree 時,Orca 會用 claude --resume <id> 或 codex resume <id> 等方式自動續接。Cursor CLI、Hermes、Copilot、Trae 等不可續接的 Agent 不會被休眠。驗證方式:將 Hibernate after 暫設為 1 分鐘,讓一個 Claude 任務完成後切到其他 Worktree,等待後再切回,確認對話內容完整續接。
Q52:用 CLI 或 Automation 建立的 Workspace 在側邊欄找不到?
**A:**側邊欄的篩選選單可以隱藏 Sleeping、Default branch、Automation-created、CLI-created、Other-client、Detached HEAD 等類型的 Workspace。處理步驟:點擊側邊欄的篩選控制,查看啟用中的篩選數量,按 Clear 重設。驗證方式:篩選清除後 Workspace 出現;也可用 Cmd-J(Windows/Linux 為 Ctrl-J)的 Worktree Jump Palette 直接輸入名稱搜尋,被篩選隱藏的項目仍可搜尋得到。
32.5 Review 與 Git
Q53:Diff 畫面看起來不對,或卡住不更新?
**A:**官方建議先點擊 Diff 工具列上的重新整理圖示,Orca 會重新讀取 Worktree。在 Orca 外部執行的 git 操作(rebase、reset 等)可能剛好落在兩次重新整理之間,造成畫面暫時不一致。處理步驟:
- 點擊 Diff 工具列的重新整理。
- 若仍不正確,在該 Worktree 的終端機確認 git 實際狀態。
- 若外部仍有 rebase 或 merge 進行中,先完成或中止它再重新整理。
驗證方式:
git status --short
git diff --statOrca Diff 顯示的檔案清單應與 git diff --stat 一致。
Q54:Annotate AI Diff 的留言會同步到 GitHub PR 嗎?
**A:**要分兩種情境。在本機 Diff 上使用 Annotate AI Diff 留下的註記,是 Orca 內部用來批次送給 Agent 修正的 Review Notes,不會寫入 GitHub。PR 建立後,在 PR 分頁或 Checks 面板對 Review Thread 的回覆,才會透過 GitHub 寫入 PR。處理步驟:若留言需要成為稽核紀錄,務必先建立 PR,再於 PR 介面留言。驗證方式:在瀏覽器開啟該 PR 的 Files changed 頁面,確認留言出現在對應行。
Q55:PR 面板顯示「GitHub is rate-limiting requests」?
**A:**GitHub 對每個已驗證使用者提供共用的每小時額度(REST core 約 5,000 次、GraphQL 約 5,000 點、Search 每分鐘 30 次),同一帳號下的 Orca、終端機中的 gh、會呼叫 gh 的 Agent、CI 腳本與其他應用程式全部共用。處理步驟:
- 等待錯誤訊息或
X-Ratelimit-Reset指出的重設時間。 - 關閉多餘的 Orca 視窗,暫停大量呼叫
gh的自動化或 Agent。 - 被限制期間不要反覆按重新整理,Orca 已自動退避。
- 重設後若仍失敗,改查驗證問題(見 Q57、Q58)。
驗證方式:
gh api user -i 2>&1 | head -40若回應為 403 且 X-Ratelimit-Remaining: 0,代表 REST 仍被封鎖;回應 200 即已恢復。
Q56:Settings 的 GitHub API Budget 顯示還有額度,PR 面板卻說被限流?
**A:**Settings → Git → GitHub API Budget 讀取的是 GitHub 的 rate_limit 端點,這個探測本身不計入額度,有時會在真實 REST 呼叫已歸零時仍顯示有剩餘。官方建議兩者不一致時依序相信:PR/Checks 面板上的錯誤(真實請求失敗)、終端機的真實 CLI 檢查、最後才是 Settings 的預算數字。另外不要把 GitHub API Budget 與 Accounts 下的 Claude/Codex 用量混淆,後者是 AI 供應商額度。驗證方式:
gh api rate_limit --jq '.resources.core'
gh api user --jq .login第一行是探測,第二行是真實呼叫;以第二行是否成功為準。
Q57:終端機的 gh 明明能用,Orca 卻說 GitHub CLI 未安裝?
**A:**常見原因有兩個:一是 PATH 上有個會卡住的 gh 啟動器,新版 Orca 會略過卡住的啟動器、改用通過版本檢查的那一份;二是 Orca 啟動時的 PATH 與終端機不同。處理步驟:
- 執行
which -a gh(Windows 用Get-Command gh -All)確認有幾份gh。 - 完全結束 Orca 再重開,讓 PATH 重新載入。
- Windows 上要把
gh安裝在 Orca 實際啟動的環境(WSL 或原生 Windows)。
驗證方式:gh --version 能立即回應,且 Orca 的 PR 面板不再顯示 GitHub CLI is unavailable。
Q58:gh auth status 顯示已登入,但 Orca 一直出現驗證錯誤或奇怪的限流?
**A:**最常見的陷阱是 shell 設定檔中匯出了 GITHUB_TOKEN 或 GH_TOKEN(例如 export GITHUB_TOKEN=$(gh auth token)),gh 會優先使用環境變數而非 keyring,過期或錯誤的 Token 會造成混亂。處理步驟:從 ~/.bash_profile、~/.zshrc 等檔案移除這些匯出,然後重新登入並重啟 Orca。
unset GITHUB_TOKEN GH_TOKEN
gh auth logout -h github.com
gh auth login -h github.com驗證方式:執行 gh auth status -h github.com,確認 Token 來源為 keyring 而非環境變數,且 gh api user --jq '{login, id}' 回傳正確帳號。
Q59:PR 面板出現 HTTP 403,但訊息不是 rate limit?
**A:**代表 Token 缺少權限範圍,或你沒有存取該資源的權限;組織若啟用 SAML SSO,Token 還需要經過 SSO 授權。處理步驟:
- 用與
gh api user相同的帳號在瀏覽器開啟該 PR,確認有權限。 - 重新驗證並包含
repo範圍,若使用 Projects 相關功能再加read:org、project。 - 到 GitHub 的 Token 設定頁對組織執行 SSO 授權。
驗證方式:gh pr view <PR 編號> --repo <owner>/<repo> 能正常顯示內容。
Q60:PR 面板顯示「repository is unavailable」或 HTTP 404?
**A:**通常是 remote 設定錯誤、Repo 已改名,或目前的 Token 看不到這個私有 Repo。處理步驟:
git remote -v
gh repo view <owner>/<repo>若 remote 指向舊名稱,執行 git remote set-url origin <新網址>;若 gh repo view 失敗,代表 Token 無權限,請依 Q59 處理。GitHub Enterprise 則需執行 gh auth login --hostname <企業主機名稱>。驗證方式:gh repo view 成功後,回 Orca 重新整理 PR 面板。
Q61:SSH Worktree 的 PR 面板無法顯示,但本機 Worktree 正常?
**A:**GitHub 驗證是「每台主機」各自獨立的,在筆電登入 gh 不會讓遠端主機也登入。處理步驟:SSH 進入該主機執行 gh auth login;若為 Remote Orca Server,請使用遠端伺服器的 GitHub 預算檢視,本機 Settings 只顯示桌面端的身分。驗證方式:在遠端主機執行 gh auth status -h github.com 與 curl -sI https://api.github.com | head -1,確認登入狀態與對外 HTTPS 連線正常。
Q62:我們用 GitLab、Bitbucket 或 Azure DevOps,Orca 支援到什麼程度?
**A:**依 v1.4.244 官方文件:GitHub 的 Actions 與 Issue 支援最深入(含 Stacked PR、Projects、Auto-merge);GitLab 的 MR 與 Issue 使用相同的 Worktree 審查流程,Checks 面板也能看 pipeline 與子 pipeline 的 job log;Bitbucket Cloud 可在 Settings → Integrations 以 Email 與 API token 或 Access token 連線並建立 PR(無 Draft PR);Azure DevOps 與 Gitea 的 PR 會出現在側邊欄與 Checks 面板。處理步驟:在導入評估時,用你們實際的平台走一次「建立 Worktree → Push → 建立 PR/MR → 查看 Checks」完整流程。驗證方式:側邊欄的 Worktree 卡片能顯示連結的 PR/MR 狀態。詳見第十五章。
Q63:建立 PR 時看不到「Stack this PR above #N」選項?
**A:**Stacked PR 只在 GitHub 上、且你選擇的 base 分支已有開啟中的 PR,並且執行主機支援建立 stack 時才會出現;GitLab MR 與 Bitbucket PR 維持單一 PR 建立。處理步驟:確認 base 分支選的是上一層 PR 的分支,並確認遠端主機(若為 SSH 或 Remote Server)的 Orca 已更新至支援版本。驗證方式:建立後 PR 側邊欄出現可展開的 Stack #N 地圖,列出各層 PR 狀態。
Q64:PR 畫面的 Enable auto-merge 按鈕不見了?
**A:**以下情況 Orca 會隱藏 Auto-merge 控制:PR 為 Draft、已關閉、有衝突、狀態不穩定,或 Repo 未允許 auto-merge。處理步驟:先把 Draft 改為 Ready for review、解決衝突,並請 Repo 管理員在 GitHub Repo 設定中啟用 Allow auto-merge。驗證方式:
gh repo view <owner>/<repo> --json autoMergeAllowed預期回傳 true,且 PR 狀態為 open 且無衝突時,按鈕會重新出現。
Q65:Agent 產生的 Commit 訊息風格五花八門,怎麼統一?
**A:**處理步驟:
- 在 Settings → Repository 的 Source Control AI overrides 設定 Commit message、PR 內容與分支名稱的產生規則(例如要求 Conventional Commits)。
- 在 Prompt 範本中明確寫出 Commit 規範。
- 搭配 commit-msg hook 或 CI 檢查作為最後防線。
驗證方式:
git log --oneline -20抽查最近 20 筆 Commit 是否符合規範,例如每筆都以 feat:、fix:、docs: 等前綴開頭。
32.6 遠端與行動端
Q66:SSH 可以連線,但遠端終端機無法使用?
**A:**v1.4.224 起,Orca 會在 SSH 主機上建立自己管理的 Orca server(managed server),因此主機上 Node 版本錯誤或缺少建置工具不再會阻擋連線。處理步驟:
- 到 Settings → SSH Hosts 查看該主機正在執行哪一種 server,以及失敗原因。
- 到 Settings → Managed servers 對該伺服器執行 Update、Roll back 或 Recover。
- 若主機無法執行 managed server(作業系統或 CPU 不支援、家目錄 noexec、SSH server 拒絕 port forwarding),新版不會退回舊的 SSH runtime,連線會直接失敗並說明原因;此時只能改用較舊的 Orca 版本連線該主機。
- 從 v1.4.224 延續下來的終端機仍可輸入輸出,但沒有
orcaCLI,需要 orca 指令時請在同一主機開新終端機。
驗證方式:
orca environment status --environment <selector> --json預期顯示伺服器版本與執行中的終端機數量。
Q67:SSH Worktree 的檔案可以下載,但右鍵選單沒有「Download Folder」?
**A:**資料夾下載需要遞迴 SFTP 傳輸能力。只走系統 OpenSSH 的連線可能只能下載單一檔案,因此不會顯示 Download Folder;此功能也只在桌面版提供,Web client 沒有。處理步驟:改在終端機用 tar 或 scp 作為替代:
ssh <host> "tar czf - -C /path/to/worktree target-dir" > target-dir.tar.gz
tar tzf target-dir.tar.gz | head驗證方式:第二行能列出壓縮檔內的檔案清單,代表下載完整。
Q68:Worktree 選單中的「Open in VS Code」是灰色的,或顯示 Local only?
**A:**此功能透過 VS Code Remote-SSH 開啟遠端路徑,有三個前提。處理步驟:
- 必須是 SSH Worktree,不能是 Remote Orca Server 作為作用中執行階段的 Workspace。
- 到 Settings → General → Open in menu,把 Open-in 指令設為 VS Code 或 VS Code Insiders(
code、code-insiders或其直接路徑),不能是 Cursor、Zed 或多參數的 shell 指令。 - 若主機曾被移除,重新整理 SSH targets。
驗證方式:選單項目旁出現 Remote SSH 標記,點擊後 VS Code 以 --remote ssh-remote+<host> <path> 開啟該 Worktree。
Q69:Kerberos 登入失敗?
**A:**OpenSSH 設定中有 GSSAPIAuthentication yes 的主機,Orca 會改用系統 OpenSSH 連線(內建的 ssh2 client 不支援 GSSAPI)。處理步驟:
- 先取得有效的 Kerberos ticket(
kinit或公司 SSO)。 - 確認
~/.ssh/config中該 Host 設有GSSAPIAuthentication yes。 - 在 Settings → SSH 重新匯入或重新 Test 該 target。
驗證方式:
klist
ssh -G <host> | grep -i gssapiklist 應顯示該主機 realm 的有效 ticket,ssh -G 應輸出 gssapiauthentication yes。
Q70:使用 FIDO2 硬體金鑰(ed25519-sk)的 SSH 主機無法驗證?
**A:**硬體金鑰類型(ed25519-sk、ecdsa-sk)會交給系統 OpenSSH 處理,以便觸碰或 PIN 提示正常運作。如果機器上沒有 OpenSSH 或不在 PATH 上,這類主機就無法驗證。處理步驟:安裝 OpenSSH 用戶端並確認在 PATH 上,然後重新 Test。驗證方式:在一般終端機執行 ssh -V 有版本輸出,且 ssh <host> 會出現觸碰金鑰的提示並成功登入。
Q71:SSH 連線被拒絕,訊息說 host key 已變更?
**A:**Orca 會比對 OpenSSH 的 known_hosts,若金鑰變更、被撤銷或類型不符,會在詢問密碼前就拒絕連線,這是防範中間人攻擊的機制。處理步驟:
- 先透過其他管道(主機管理員、雲端主控台)確認主機確實重建過,並取得新指紋。
- 依錯誤訊息提供的指令移除舊紀錄,例如
ssh-keygen -R <host>或含連接埠的ssh-keygen -R "[<host>]:2222"。 - 重新連線並核對指紋。
驗證方式:ssh-keyscan <host> | ssh-keygen -lf - 輸出的指紋應與管理員提供的一致。未經確認不得直接略過檢查。
Q72:在 SSH 主機上的 Agent 執行 orca worktree create 被拒絕?
**A:**v1.4.230 起,SSH 主機上的 orca 指令預設只能操作該主機自己的終端機與 Orchestration 訊息,不能建立 Worktree、開終端機或分派工作;先前未設定的主機在升級時被遷移為關閉。處理步驟:到 Settings → SSH,編輯該主機,在 Advanced Connection 開啟「Allow this host’s orca CLI to control Orca」。開啟前請評估:這等於允許該主機上的 Agent 操作你的 Orca。驗證方式:在該主機的新終端機執行 orca worktree ps --json,應能列出 Worktree。
Q73:SSH 首次連線時說無法下載 Node.js 執行階段?
**A:**managed server 需要下載 Node.js 執行階段,若你的電腦與主機都無法連到官方來源,連線錯誤會提供 Use a Node.js mirror…。處理步驟:填入公司內部的 mirror 網址,選擇 Save and retry,Orca 會用固定的 checksum 驗證每次下載。若 mirror 也失敗,到 Settings → Advanced → Network 修正 mirror 後再連線。驗證方式:連線成功後,Settings → Managed servers 顯示該主機的伺服器版本。
Q74:筆電闔上或網路斷線,遠端的 Agent 會停止嗎?
**A:**不會。SSH Worktree 的 PTY 存在主機的 managed server 上,斷線不會終止 Agent;Orca 會自動重連並重新附掛,斷線期間輸入的按鍵會在恢復時依序且僅送出一次。Remote Orca Server 則由伺服器保存完整 Session 狀態。處理步驟:重連後先檢查主機上的工作狀態,再決定是否啟動新 Agent,避免同一 Worktree 出現兩個 Agent。驗證方式:狀態 chip 由黃色(reconnecting)轉回綠色(connected),且分頁的捲動紀錄包含斷線期間的輸出。
Q75:Remote Orca Server 顯示 Disconnected,或找不到 Tailscale 位址?
**A:**處理步驟:
- 確認伺服器電腦處於喚醒狀態、Orca 仍在執行、兩台電腦登入同一個 tailnet。
- 在伺服器的 Settings → Remote Orca Servers 按 Connection address 旁的重新整理,Tailscale 位址通常以
100.開頭。 - 檢查 Tailscale ACL 或 grants 是否阻擋兩台裝置互連。
- 若伺服器列顯示協定版本不相容,兩台電腦都更新 Orca。
驗證方式:
tailscale status
tailscale ping <伺服器名稱>兩台裝置都顯示在線且 ping 成功後,在用戶端按 Connect,狀態應轉為 Connected。
Q76:Remote Orca Server 的存取連結不小心傳給了錯誤的人?
**A:**存取連結等同密碼。處理步驟:在伺服器的 Settings → Remote Orca Servers → Shared Server Access 找到對應的 grant,按垃圾桶撤銷,使用該 grant 的用戶端會立即斷線;再為正確的用戶端產生新連結(新連結會取代先前未使用的連結)。驗證方式:Shared Server Access 清單中已無該 grant,且事後檢查是否有異常操作紀錄,必要時依第二十八章的資安事件流程通報。
Q77:Remote Orca Server 上找不到 Agent CLI?
**A:**遠端 Session 使用的是伺服器的 PATH、家目錄與憑證,不是用戶端的。處理步驟:在伺服器電腦安裝並登入該 CLI;若為無頭的 orca serve 主機,從伺服器 shell 註冊帳號:
orca account add --agent claude
orca account add --agent codex
orca account list驗證方式:orca account list 列出帳號,且用戶端在該伺服器的專案中能成功啟動 Agent。
Q78:手機無法與桌面配對?
**A:**處理步驟:
- 若使用 Orca Relay,桌面與手機需登入同一個 Orca 帳號;若使用 LAN,需要選擇可達的位址。
- 配對碼幾分鐘後會過期,請重新產生。
- 若出現 Authentication failed,先按橫幅的 Retry;仍失敗則從桌面 Re-pair,或在手機 Remove host 後重新配對。
驗證方式:配對成功後,手機的主機清單顯示桌面的機器名稱與作業系統,並可看到 Worktree 清單與 Agent 狀態。
Q79:手機顯示「Update Orca Mobile」或「Update Orca on your computer」?我要怎麼更新 iOS 版?
**A:**手機與桌面使用有版本的行動協定,任一端太舊就會被封鎖。v1.4.244 起行動設定頁將 iOS 安裝導向 App Store,TestFlight 預覽選項已移除;Android 仍以 APK 安裝。處理步驟:iOS 從 App Store 更新、Android 從官方下載頁取得最新 APK、桌面依第二十九章的升級流程更新,更新後重新整理連線;若訊息仍在,移除主機後重新配對。驗證方式:手機可正常開啟該主機的 Session 與 Quick Commands。
Q80:Samsung 手機安裝 Android APK 時被 Auto Blocker 擋下?
**A:**官方建議:開啟 設定 → 安全性與隱私權 → Auto Blocker,暫時關閉後安裝 Orca,安裝完成立即重新開啟;不要停用 Play Protect。另外只允許瀏覽器或檔案 App 安裝未知來源 App,安裝後就關閉該權限。若下載一直不開始,請在 Chrome 等完整瀏覽器開啟下載頁,不要在 Discord 或 GitHub App 內建瀏覽器中下載。驗證方式:Auto Blocker 已重新開啟,且 Orca Mobile 可正常啟動並進入配對畫面。企業 MDM 若禁止側載,需走例外申請。
Q81:手機上某個 Worktree 一直顯示轉圈或 working,但桌面已經 idle?
**A:**手機依桌面 Agent 程序的心跳判斷狀態。處理步驟:在手機上強制重新整理該 Worktree 列以同步狀態;若仍不正確,確認手機與桌面之間的網路路徑(LAN、Tailscale 或 Relay)是否正常。驗證方式:重新整理後手機狀態與桌面側邊欄一致。
Q82:遠端 Worktree 啟動的開發伺服器,本機瀏覽器連不到?
**A:**遠端 Worktree 的右側欄有 Ports 分頁(Cmd+Shift+I 切換),Orca 會掃描 Workspace 所在主機的監聽埠並列在 Detected 下,一鍵即可轉送;特權埠會自動對應到本機其他埠(例如遠端 80 對應本機 10080)。CLI 的 orca ports(v1.4.240)不支援 direct SSH 主機。處理步驟:在 Ports 分頁點擊轉送,或手動新增轉送規則。驗證方式:
curl -sI http://localhost:<本機埠> | head -1預期回應 HTTP/1.1 200 或開發伺服器的正常回應碼。
32.7 自動化與 CLI
Q83:在終端機執行 orca 出現 command not found?
**A:**處理步驟:
- 到 Settings → General → Orca CLI 註冊 CLI。
- macOS 會在
~/.local/bin安裝 shim,請確認該目錄在 shell 的 PATH 上(例如在~/.zshrc加入export PATH="$HOME/.local/bin:$PATH")。 - Windows 的
orca是安裝程式加入 PATH 的原生程式,請重開終端機。 - Linux 的指令名稱是
orca-ide(見 Q16)。
驗證方式:
command -v orca
orca status --json第一行應輸出 CLI 路徑,第二行應回傳執行階段狀態;若 Orca 未開啟,先執行 orca open --json。
Q84:腳本呼叫到的 orca 版本和桌面版不一致?
**A:**Orca 會在自己開啟的終端機中把內建的 orca 放在 PATH 最前面,即使 shell 啟動檔加入了舊的全域安裝也一樣;但在 Orca 外部的終端機,可能先找到舊版。處理步驟:執行 which -a orca 找出所有副本,移除舊的全域安裝,或在 CI 腳本中使用完整路徑。驗證方式:在 Orca 內外的終端機分別執行 orca status --json,回報的版本應與桌面版一致。
Q85:瀏覽器自動化指令回傳 browser_no_tab?
**A:**代表目前的 Worktree 沒有開啟任何瀏覽器分頁。處理步驟:
orca tab create --url http://localhost:3000 --worktree active --json
orca tab list --worktree active --json或手動開啟瀏覽器窗格並導覽到目標頁面。驗證方式:orca tab list 列出至少一個分頁後,再執行 orca snapshot --json 應回傳 @e1 這類元素參照。
Q86:排程的 Automation 時間到了卻沒有執行?
**A:**處理步驟依序檢查:
- 是否仍為停用狀態:建議以
--disabled建立,確認無誤後要記得啟用。 - 執行主機是否在線:Automation 儲存並排程在特定主機上,主機離線或 Orca 未執行時不會觸發。
- Precheck 是否失敗:precheck 指令回傳非零值會記錄為 skipped run。
- 錯過時間是否超過寬限:用
--missed-run-grace-minutes設定補跑寬限。
orca automations list --json
orca automations runs --id <automationId> --json
orca automations edit <automationId> --enabled --json驗證方式:先執行 orca automations run <automationId> --json 手動觸發一次,確認 runs 清單出現成功紀錄。
Q87:Automation 的 --extra-agent-args 被拒絕?
**A:**官方規定此參數只接受模型與 effort 選項(Claude 另可用 --add-dir),適用 Claude、Codex、CodeBuddy、Cursor、Grok、OMP;權限、設定、Prompt、Session 相關選項一律拒絕,而且不能與 --reuse-session 併用。值以 -- 開頭,必須用等號傳遞。處理步驟:
orca automations edit <automationId> --extra-agent-args="--model opus" --json清除時使用 --extra-agent-args=。驗證方式:orca automations show <automationId> --json 中的 extra args 欄位與預期一致,手動執行一次確認 Agent 使用指定模型。
Q88:怎麼避免 Automation 在沒事可做時白白消耗額度?
**A:**使用 --precheck 先跑一個低成本的 shell 探測,非零結束碼就跳過該次執行。例如只在有待審 PR 時才啟動審查:
orca automations create --name "PR review" --trigger hourly --precheck "gh pr list --json number -q .[0].number" --prompt "Review requested PRs" --provider codex --repo my-repo --disabled --json驗證方式:在沒有待審 PR 的時段查看 orca automations runs,應記錄為 skipped,而非啟動 Agent。
Q89:Computer Use 指令回報缺少權限?
**A:**Computer Use 需要作業系統的 Accessibility 權限,macOS 另需 Screen Recording 權限。處理步驟:
orca computer permissions --json依回報缺少的項目,到系統設定授權給 Orca Computer Use,然後重新執行檢查。驗證方式:permissions 不再回報缺項,且 orca computer list-apps --json 能列出執行中的 App。此功能為 Beta,使用前請先關閉含機敏資訊的視窗。
Q90:Agent 透過 Computer Use 輸入密碼,會留在 shell 歷史紀錄嗎?
**A:**若直接寫在 --value 或 --text 參數中就會留下。官方建議改用 stdin 傳遞:
printf '%s' "$TEXT" | orca computer set-value --app com.apple.Safari --element-index 7 --value-stdin --json--text-stdin 對 type-text 與 paste-text 同樣適用。驗證方式:執行後檢查 history | tail -5,確認沒有出現明文。企業環境更建議禁止 Agent 處理正式環境憑證,見第十七章。
Q91:Orchestration 的 worker 一直沒有回報完成?
**A:**處理步驟:
- 用 Orchestration 指令查看 worker 狀態,必要時以
orca terminal read --terminal <handle> --json讀取該 worker 的終端輸出。 - v1.4.219 起完成報告會重試約兩分鐘;確定放棄時可用
worker-abandon。 - v1.4.243 起 worker heartbeat 間隔可在 Settings → Agent Orchestration 調整或關閉,預設 5 分鐘,變更只套用到新 worker。
驗證方式:coordinator 收到 worker_done 訊息,且該 worker 的 Dispatch 狀態轉為 completed。詳見第十六章。
Q92:Agent 使用的 Orca skill 指令過時,跟現在的 CLI 對不上?
**A:**Skills 需要隨 Orca 版本更新。處理步驟:
orca skills list
orca skills update --all也可在 Settings → Agents 的 Skill freshness 區塊按 Update,在背景更新全域 skills。驗證方式:側邊欄不再出現 Update available 標記,且 orca skills get orca-cli 顯示的內容與目前 CLI 版本一致。
Q93:在 Windows 上執行 orca serve service install 失敗?
**A:**官方說明 orca serve service 與 --supervise 相關指令目前不支援 Windows。處理步驟:Windows 主機改用桌面版的 Settings → Remote Orca Servers → Advertise this app as a server;若一定要無頭執行,請改用 Linux 或 macOS 主機。驗證方式:在 Linux 上執行 orca serve service status --json 顯示 running;Linux 若需要登出後持續執行,還需執行 loginctl enable-linger。
Q94:orca artifacts share 失敗,無法產生公開連結?
**A:**Artifact 發佈是裝置層級的選擇性功能,預設關閉。處理步驟:
- 到 Settings → Artifacts 登入 Orca 帳號。
- 開啟「Allow publishing public artifact links」。
- 確認檔案小於 10 MiB,且 HTML 為自包含檔案(相對路徑的資源不會上傳)。
驗證方式:orca artifacts list 能看到新連結。企業環境請先確認資料分級政策,公開連結任何人都可檢視。
32.8 效能與維運
Q95:開了幾個 Worktree 之後電腦就變得很慢?
**A:**官方指出每個 Worktree 都會維持檔案監看器,而大量瀏覽器分頁的分割版面是最主要的記憶體消耗來源。處理步驟:
- 關閉目前沒有在用的 Worktree,不用的瀏覽器分頁也一併關閉。
- 從狀態列開啟 Resource Manager 查看 CPU、記憶體、Session 與各 Workspace 的磁碟用量。
- 開啟 Agent hibernation(見 Q51)讓閒置 Agent 自動暫停。
- 長時間任務改到 SSH 主機或 Remote Orca Server 執行。
驗證方式:調整前後各記錄一次 Resource Manager 的記憶體數字,或在 macOS 用活動監視器、Windows 用工作管理員比較 Orca 相關程序總和。
Q96:要怎麼一次清理大量不再使用的 Workspace?
**A:**使用 Resource Manager → Clean up workspaces。清單包含本機 Worktree、主 Worktree、資料夾 Workspace 以及斷線 SSH 主機上的 Workspace,可依狀態、最近活動、大小、Git 狀態與連結的 PR 搜尋、篩選、排序後再勾選刪除。處理步驟:先依「大小」排序,優先處理已合併 PR 對應的大型 Workspace。驗證方式:清理後執行 git worktree list 與 git worktree prune --dry-run,確認沒有殘留紀錄。
Q97:更新 Orca 後,有些終端機行為跟新開的不一樣?
**A:**Orca 的終端機由背景的 terminal host 服務持有。v1.4.220、v1.4.221、v1.4.241、v1.4.243 都啟動了新的 terminal host,舊終端機會留在舊 host 直到關閉,所以新舊行為並存。v1.4.244 沿用 v1.4.243 的 host,部分修正要等 host 重新啟動(例如重開機)才生效。處理步驟:在方便的時間點關閉舊終端機重新開啟,或重新開機。驗證方式:重開後的終端機具備新版行為(例如 Windows 提示字元立即出現)。
Q98:Orca 幾乎每天發版,我們每一版都要升級嗎?
**A:**不需要逐版追。v1.4.150(2026-07-22)到 v1.4.244(2026-10-29)之間共有 78 個 stable 版本。建議做法:
- 每週由指定人員閱讀 Release Notes 的 Compat 段落,標記與團隊相關的變更。
- 先在測試機升級,跑過第四章的安裝後健康檢查。
- 每兩到四週統一升級一次;遇到安全修正(例如 v1.4.221 的 Copilot 設定檔權限)則立即升級。
- SSH 主機與 Paired server 的 Orca 版本與桌面保持一致,許多新功能需要兩端同版。
驗證方式:團隊版本清冊中每台機器的版本落差不超過一個升級週期。詳見第二十九章與附錄 C。
Q99:要回報 Bug 時,Log 在哪裡?
**A:**使用 Help → Open Logs 開啟 Orca 的 Log 目錄。回報管道有三個:Help → Send Feedback(可貼上或拖曳截圖)、GitHub Issues 以及官方 Discord。處理步驟:
- 先以最新版本重現問題。
- 收集 Log 與重現步驟,移除 Token、內部主機名稱與客戶資料。
- 先搜尋 GitHub Issues 是否已有相同回報。
驗證方式:回報內容包含版本號、作業系統、重現步驟與 Log 片段,且經第二人檢查確認無機敏資訊。
Q100:GitHub 額度總是很快用完,是誰在消耗?
**A:**官方列出常見消耗來源:同時開啟多個 Orca 視窗(各自會重新整理 PR 與 Tasks)、會自動呼叫 gh 的 Agent(指派 PR、輪詢 Checks、大量 GraphQL)、大量 Tasks 或跨 Repo 的展開、其他使用同一 Token 的應用程式。處理步驟:只保留一個 Orca 視窗;在 Prompt 中限制 Agent 輪詢頻率;腳本改用 GraphQL 批次查詢;CI 改用專用的 Bot Token。驗證方式:一小時內兩次執行 gh api rate_limit --jq '.resources.core.remaining',比較消耗量是否降低。
Q101:要怎麼備份 Orca 的設定,換電腦時快速還原?
**A:**程式碼由 git 保護,Orca 本身的設定則建議分層備份。處理步驟:
- 自訂快捷鍵位於
~/.orca/keybindings.json,可直接納入個人 dotfiles。 - Repo 層級的共享設定(
orca.yaml、.worktreeinclude)提交進 Repository,換電腦自動帶走。 - 其他設定(Agents 啟動參數、Quick Commands、SSH targets)依第六章的企業標準設定基準範例,維護一份可勾選的設定清單。
- 憑證與 Token 不要放進備份,換機後重新登入。
驗證方式:在新電腦依清單還原後,執行第四章的健康檢查並比對 Settings 主要項目。完整備份與還原流程見第二十九章。
Q102:如何在企業環境統一關閉 Telemetry?
**A:**三種方式任一即可,且可同時使用:在 Settings → Privacy 關閉「Share anonymous usage data」、設定 DO_NOT_TRACK=1,或設定 Orca 專用的 ORCA_TELEMETRY_DISABLED=1。企業建議以端點管理工具派送環境變數,避免依賴每位使用者手動切換。驗證方式:
[Environment]::GetEnvironmentVariable("ORCA_TELEMETRY_DISABLED", "User")macOS/Linux 則在登入 shell 執行 echo $ORCA_TELEMETRY_DISABLED,預期輸出 1。
Q103:長任務跑到一半,筆電進入睡眠導致 Agent 中斷?
**A:**使用 Settings → Agents → Keep computer awake(狀態列的咖啡杯 Caffeinate 圖示同樣可切換):On 為持續保持喚醒、Agent 為只在 Agent 工作時保持喚醒、Off 為關閉。處理步驟:一般建議選 Agent。若筆電需要闔上帶走,請改用 Remote Orca Server 或 SSH 主機執行長任務。驗證方式:設為 Agent 後啟動一個長任務,超過系統的睡眠逾時時間後確認任務仍在進行。
Q104:大型 Diff 打開時畫面凍結?
**A:**v1.4.195 起大型 Diff 改為延遲載入,v1.4.218 修正大型 Diff 造成凍結的問題,v1.4.244 也加快了 Diff 與編輯器。處理步驟:先更新至最新版;檢視時善用 Diff 的檔案樹與 Collapse Unchanged Regions(Settings → General),一次只展開需要審查的檔案。若變更量本身過大,代表任務切分過粗,應請 Agent 拆成較小的 Commit。驗證方式:git diff --stat | tail -1 顯示的變更行數若超過數千行,應優先拆分再審查。
Q105:遇到本章沒有涵蓋的問題,怎麼建立團隊自己的 FAQ?
**A:**處理步驟:
- 每次排錯後,依本章格式(問題、處理步驟、驗證方式)記錄到團隊知識庫,並標註 Orca 版本。
- 每季複核一次,刪除已被新版修正的條目,並對照附錄 C 補充新的相容性注意事項。
- 將高頻問題轉為第六章的設定基準或第三十三章的最佳實務。
驗證方式:團隊 FAQ 每個條目都有版本號與最後驗證日期,且最近一季內至少複核過一次。
32.9 本章 Review 與驗證清單
- 能說明「先在 Orca 外重現、再判斷是否為 Orca 問題」的通用排錯原則
- 已在自己的環境執行
orca status --json(Linux 為orca-ide status --json)並取得正常回應 - 已執行
gh auth status -h github.com與gh api user --jq .login,並能分辨rate_limit探測與真實 REST 呼叫的差異 - 已檢查 shell 設定檔中沒有過期的
GITHUB_TOKEN/GH_TOKEN - 能說明 Codex
SUN_LEN錯誤的原因與修正版本(v1.4.212) - 能說明 profile 副本詢問中 Use SQLite 與 Use JSON 的選擇依據
- 已為至少一個 Repository 設定
orca.yaml或.worktreeinclude,並驗證新 Worktree 取得所需檔案 - 已確認 Settings → Agents → Agent permissions 符合組織政策(Manual、Auto 或 Yolo)
- 已確認本機與 SSH 主機上
~/.copilot/config.json的權限為僅擁有者可讀 - 能說明 SSH managed server 的運作方式,以及 Download Folder、Open in VS Code、Kerberos、FIDO2 的前提條件
- 能說明 Remote Orca Server 存取連結外流時的撤銷步驟
- 已用
orca tab create排除過一次browser_no_tab錯誤 - 已以
--disabled建立一個 Automation,手動執行並檢查 runs 紀錄 - 已知道 Help → Open Logs 的位置,並了解回報 Bug 前必須移除機敏資訊
- 已建立團隊自有 FAQ 的格式與每季複核機制
第三十三章 最佳實務一百條
本章把全書的經驗濃縮成 100 條可執行的規則,依 8 個主題分類、連續編號。每一條都是「規則+簡短範例」,需要對照時以 ❌/✅ 呈現。建議用法:導入初期挑出與你目前成熟度(第三十一章)相關的 20~30 條作為團隊約定,其餘作為檢查清單逐季補上。
📌 查證狀態:依官方說明延伸(教學推論)|規則中引用的 Orca 功能與設定路徑以 v1.4.244 官方文件與 Release Notes 為準;規則本身為教學建議,非官方規範。
33.1 架構規劃
1. 把 Orca 定位為疊加在既有 Agent CLI 之上的管理層,而非取代品。
範例:團隊已用 Claude Code 與 Codex,導入時保留各自的登入與設定,Orca 只負責 Worktree、監看與審查。
2. 一個 Repository 只加入 Orca 一次,用 Worktree 區分任務,不要複製多份 clone。
- ❌ 為了平行開發 clone 三份
myapp、myapp2、myapp3。 - ✅ 一份 repo,三個 Worktree:
feat-login、feat-report、fix-142。
3. 平行分派前先畫出模組邊界,確認任務之間檔案範圍不重疊。
範例:前端 Agent 只碰 web/,後端 Agent 只碰 api/,共用型別放在先合併的 shared/ PR。
4. 跨模組任務採契約優先:先合併介面規格,再分派實作。
範例:先由一個 Agent 產出 openapi.yaml 並經人工審查合併,再讓前後端 Agent 各自依規格實作。
5. 強依賴的任務改為序列,不要勉強平行。
- ❌ 同時讓 A 改資料表結構、B 寫使用新欄位的查詢。
- ✅ A 合併後,B 從新的 main 建立 Worktree 再開始。
6. 把 Worktree 共用設定寫進 repo 的 orca.yaml 與 .worktreeinclude,不要靠口耳相傳。
範例:.env.local 與本機憑證範本透過 .worktreeinclude 帶入新 Worktree,新成員第一次就能啟動 dev server。
7. 把 Hooks 與 Memory 檔納入版本控制,讓每個 Agent 讀到同一份規範。
範例:AGENTS.md 記載命名、錯誤處理與測試指令,所有 Agent 的 Prompt 只需引用章節名稱。
8. 高風險核心邏輯(交易、授信、計費)不要拆成大量平行任務。
範例:利率計算模組由單一 Agent 加資深工程師結對完成,其餘周邊任務才平行化。
9. 需要多方案比較的架構決策,用同題競賽產出草案,由人選擇。
範例:「訊息佇列選型」讓三個 Agent 各寫一份評估文件,架構委員會比較後決定。
10. 為每個 Repository 標註「適合平行」與「不適合平行」的目錄。
範例:在 AGENTS.md 加一節「平行開發地圖」:docs/、tests/ 適合;core/ledger/ 不適合。
11. 先選 1~2 個代表性專案試點,再推廣。
範例:挑一個有完整測試的內部工具專案,而不是測試覆蓋率很低的舊系統。
12. 每季檢視一次 Repository 與 Worktree 結構,移除不再需要的項目。
範例:用 Resource Manager → Clean up workspaces 依「最近活動」排序,清理 30 天未動且已合併的 Worktree。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 共用設定已入庫 | git ls-files orca.yaml .worktreeinclude AGENTS.md | 列出檔案 | 補建並 commit |
| 任務範圍不重疊 | 平行任務結束後各自 git diff --stat main...<分支> | 檔案清單無交集 | 調整分派或改為序列 |
33.2 Agent 選用與分工
13. 依任務性質選 Agent,不要全公司只用一種。
範例:大型重構用推理較強的模型;產生測試資料或文件摘要用較快、較省的模型。
14. 以 Settings → Agents 只啟用核准的 Agent,讓啟動選單乾淨且可控。
範例:停用未經資安核准的 CLI,避免工程師誤選。
15. 在 Settings → Agents 設定一致的權限模式(Manual、Auto、Yolo),並寫進團隊約定。
- ❌ 有人 Yolo、有人 Manual,出事時無從判斷 Agent 被允許做什麼。
- ✅ 一般專案 Auto(支援者)、高監理專案 Manual,政策文件明列。
16. 知道 Yolo 的前提是「Worktree 可拋棄」,不要在主 checkout 或含機敏資料的目錄使用。
範例:Orca 預設為多數 CLI 帶入略過權限的旗標,理由是 Worktree 可丟棄;在共用主機上應改用 Manual。
17. 從 3 個角色的小編組開始,再依審查產能擴充。
範例:先用 Frontend、Backend、Test 三角色跑兩週,審查順暢後才加入 Security 與 DBA 角色。
18. 高風險角色(Security、DBA、SRE)的產出設定強制人工簽核。
範例:PR 模板勾選「涉及資料庫結構變更」時,CODEOWNERS 自動要求 DBA 審查。
19. 為每個角色寫好 Prompt 模板與驗收標準,存進 Prompt Library。
範例:Test 角色模板要求「列出新增測試名稱、執行指令、輸出最後 20 行」。
20. 長期任務用交接文件或 Hand Off to Another Agent,不要依賴 Agent 自身記憶。
範例:Session History 中使用 Hand Off to Another Agent,並要求先輸出「目前進度、未決問題、下一步」。
21. 用 Codex Ask mode 或唯讀任務做探索,確認方向後才允許修改。
範例:「先只讀不改,列出你會修改的檔案與理由」,人工確認後再切換為可寫入的任務。
22. 設定合理的「每人可監督 Agent 數」上限。
範例:每位工程師同時活躍 Agent 不超過 3 個,其餘交給 Hibernation 或排隊。
23. 建立內部「Agent 能力對照表」,每季依實際成果更新。
範例:記錄各 Agent 在「測試撰寫」「SQL 調校」「前端元件」三類任務的通過率。
24. 跨 Agent 統一 Lint 與格式化規則,交由工具而非 Prompt 保證一致。
範例:在 Worktree Setup Hook 執行 npm ci,並要求所有 Agent 完成前跑 npm run lint。
25. 不要把「AI Team」包裝成可完全取代真人團隊。
範例:對管理層簡報時,明列「AI 產出、人工審查、人工負責」三個欄位。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 權限模式一致 | 抽查 5 台工作站 Settings → Agents | 與政策一致 | 依第六章標準設定基準修正 |
| 角色模板齊全 | 檢查 Prompt Library 目錄 | 每個角色都有模板與驗收標準 | 補齊後再擴編角色 |
33.3 Parallel Worktrees
26. 同題競賽只用在高不確定性任務;明確任務用單一 Agent。
- ❌ 「改按鈕顏色」也開三個 Agent 競賽。
- ✅ 「找出記憶體洩漏原因」才開三個 Agent,各自提出假設。
27. Worktree 與分支名稱帶入需求編號。
範例:agent/backend/REQ-1024,日後可從分支追溯到需求與 PR。
28. 依量測結果設定同時活躍的 Worktree 上限(第三十章)。
範例:32 GB 筆電量測後訂為 5 個活躍 Agent,其餘排隊。
29. 建立 Worktree 時確認起始 ref 已 fetch。
範例:先 git fetch origin,再從 origin/main 建立,避免基於過期程式碼開發。
30. 為 Worktree 加上狀態與註記,讓團隊一眼看懂進度。
範例:orca worktree set --worktree active --workspace-status in-review --comment "等待 DBA 審查"。
31. 平行任務結束時要求 Agent 輸出結構化摘要。
範例:「完成後輸出:變更檔案、設計假設、未解決問題、測試指令與結果」。
32. 用分割窗格同時監看,但只把需要注意的 Agent 放在前景。
範例:兩個需要互動的 Agent 放左右分割,其餘在背景由 Agent Dashboard 追蹤狀態。
33. 善用 Agent Dashboard 與 Notifications,而不是逐一切換 tab 檢查。
範例:開啟 Agent Dashboard,只處理 Needs You 欄位中的項目。
34. 合併前一律走 Pull Request,不在本機直接合進 main。
範例:勝出的 Worktree 分支 push 後開 PR,經 CI 與人工審查才合併。
35. 合併後立即清理 Worktree,並保留未合併分支的提示。
範例:清理時若出現 Review N Branches,逐一確認後才強制刪除。
36. 共用依賴可用 Worktree Shared Paths,但升級依賴的分支要排除。
範例:一般 Worktree 共用 node_modules 快取;框架升級 Worktree 使用獨立依賴。
37. 建立合併衝突處理 SOP,必要時用 Resolve with AI 但仍需人工確認。
範例:rebase 衝突時使用 Resolve with AI 產生解法,再以測試與 Diff 審查確認。
38. 每月回顧平行化的實際效益(省下的時間 vs. 額外審查成本)。
範例:比較同類任務單 Agent 與競賽模式的 PR 前置時間與落選成本(第三十章 30.4.4)。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 命名可追溯 | git branch --list 'agent/*' | 每個分支含需求編號 | 補充命名規則並宣導 |
| 無殘留 Worktree | git worktree list 與已合併 PR 比對 | 已合併者都已清理 | 執行 Clean up workspaces |
33.4 Prompt 設計
39. Prompt 要明確寫出可修改的檔案範圍。
- ❌ 「幫我修好登入」。
- ✅ 「只修改
src/auth/session.ts與其測試檔」。
40. 寫出可驗證的完成定義。
範例:「npm test 全部通過,並貼出最後 20 行輸出」。
41. 列出「不要做」清單。
範例:「不要更新依賴版本、不要重新命名公開 API、不要修改 CI 設定」。
42. 提供共用上下文的連結或檔名,而不是整段貼上。
範例:「API 規格見 docs/openapi.yaml 的 /orders 段落」。
43. 用輸入與輸出範例取代模糊描述。
範例:「輸入 2026-02-30 應回傳錯誤碼 E_DATE_INVALID」。
44. 要求 Agent 回報假設與不確定之處。
範例:「若規格不明確,先列出你的假設,不要自行決定」。
45. 需求不穩定時先用單一對話澄清,再平行分派。
範例:先與一個 Agent 把需求整理成規格書(第二十章 20.4),確認後才分給三個 Worktree。
46. 審查類 Prompt 附上具體檢查基準。
範例:「依 OWASP Top 10 的 A01、A03、A07 逐項檢查,每項輸出結論與行號」。
47. Prompt 不得夾帶機敏資訊。
- ❌ 在 Prompt 中貼正式環境資料庫連線字串。
- ✅ 「連線設定從環境變數
DATABASE_URL讀取,測試使用 docker compose 的本機資料庫」。
48. 對話過長時使用 /compact 或開新對話並交接摘要。
範例:超過 30 回合的 Native Chat 先 /compact,再請 Agent 複述完成定義。
49. Design Mode 只在視覺問題上使用,純邏輯問題用文字描述。
範例:「按鈕對不齊」用 Design Mode 點選元素;「金額計算錯誤」直接描述輸入輸出。
50. Prompt 範本集中管理並定期更新。
範例:Prompt Library 每月檢討一次,把審查中最常見的退件原因補進範本的「不要做」清單。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 範圍被遵守 | git diff --stat | 只有指定檔案被修改 | 在 Prompt 加強範圍與不要做清單 |
| 完成定義被滿足 | 檢查 Agent 回報是否附指令與輸出 | 有實際輸出 | 退回並要求執行測試 |
| 無機敏資訊 | 以 29.4.3 的掃描方式檢查 Prompt 範本庫 | 無命中 | 移除並輪替已外洩的憑證 |
33.5 Git 與審查
51. 以 Diff Viewer 搭配 Annotate AI Diff 作為審查標準入口。
範例:逐行加 Review Note,再用 Send Review Notes to Agent 一次回饋。
52. 每輪「審查到修正」對應一個獨立 commit。
範例:fix: address review notes round 2,方便日後追溯每輪改了什麼。
53. AI 產出與人工產出使用同一套審查標準。
- ❌ 「這是 AI 寫的,測試過就好」。
- ✅ 同樣檢查可讀性、錯誤處理、安全與測試覆蓋。
54. 用 Attribution 找出需要特別細看的 AI 行,並在需要稽核時匯出 metadata。
範例:高風險 PR 審查時先看 gutter 標記的 AI 行;稽核需求下從 Diff 工具列匯出保存(Attribution 本身不寫入 git)。
55. 統一 commit message 規範並加上 AI trailer。
範例:feat(api): add order cancel endpoint 加上一行 AI-Agent: codex。
56. PR 模板加入「使用的 Agent 與 Prompt 連結」欄位。
範例:PR 描述附上 Prompt Library 條目編號與 Session History 搜尋關鍵字。
57. 合併前一定看 CI,Actions 失敗時從 Worktree 的紅色 chip 直接查看 Log。
範例:點擊 Worktree 上的失敗 chip,查看失敗 job 的 Log 後交給 Agent 修正。
58. Rollback 前確認該 Worktree 沒有其他進行中的工作。
範例:先 git status 與 git stash list,確認後才 git revert。
59. 外部 rebase 或 reset 之後,先重新整理 Diff 再審查。
範例:Diff 看起來怪異時按工具列的重新整理圖示,避免審到舊內容。
60. 高風險模組設定 CODEOWNERS 與必要審查者。
範例:/core/ledger/ @org/ledger-owners,Agent 分支無法繞過。
61. 使用 Stacked PR 拆分大型變更。
範例:資料層、服務層、UI 分三個堆疊 PR,各自審查後依序合併。
62. 定期稽核:抽查 AI 參與的合併 PR 是否都有人類 Approve。
範例:每月執行第三十一章 KPI-3 指令,結果低於 100% 時追查原因。
63. 明確規定哪些分支允許 Agent 建立 Worktree。
範例:禁止從 release/* 建立 Agent Worktree,修補一律從 main 開始再 cherry-pick。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| AI trailer 落實 | git log --since=30.days --grep='^AI-Agent:' --oneline | 與 Agent 參與的 PR 數大致相符 | 加入 commit-msg hook 提醒 |
| 審查覆蓋率 | 第三十一章 KPI-3 指令 | 100% | 啟用分支保護的必要審查 |
33.6 安全與金鑰
64. 各 Agent CLI 的憑證使用官方支援的機制保存,不寫入 repo 或 Prompt。
範例:使用 CLI 的登入流程或作業系統金鑰圈,而不是把 API Key 寫在 .env 並 commit。
65. 升級跨過 v1.4.219~v1.4.220 者,檢查 ~/.copilot/config.json 權限。
範例:ls -l ~/.copilot/config.json 應為僅擁有者可讀寫;不是則 chmod 600 並評估輪替 token。
66. 清除 shell 設定檔中殘留的 GITHUB_TOKEN、GH_TOKEN。
範例:從 ~/.zshrc 移除 export GITHUB_TOKEN=...,改由 gh 的 keyring 管理。
67. Linux 上注意未加密憑證的警告。
範例:Settings → Agents 的帳號清單若標示憑證無法加密,先修正 keyring 或 compositor 設定再使用。
68. 高監理環境關閉「Trust the folder when Orca starts an agent」。
範例:保留每個 Agent 自己的資料夾信任提示,作為額外確認點。
69. Artifacts 公開連結維持預設關閉。
範例:Settings → Artifacts 的「Allow publishing public artifact links」不開啟;需要分享時走內部文件系統。
70. 依公司政策設定 Telemetry。
範例:在派送設定中加入 ORCA_TELEMETRY_DISABLED=1,或要求使用者關閉 Settings → Privacy 的「Share anonymous usage data」。
71. SSH 主機比照伺服器存取控制,最小權限、優先金鑰或憑證驗證。
範例:遠端主機使用專用帳號與 FIDO2 或憑證登入,禁止密碼登入。
72. 遠端主機上的 orca CLI 控制權只對需要的主機開啟。
範例:只有跑 Orchestration 的主機在 Settings → SSH Hosts → Advanced Connection 開啟「Allow this host’s orca CLI to control Orca」。
73. Design Mode 與截圖不用於含個資或機敏資料的畫面。
範例:用遮罩後的測試資料重現 UI 問題,再送截圖給 Agent。
74. 行動端只允許公司管理的裝置配對,並定期撤銷不用的存取連結。
範例:每季檢查 Settings → Remote Orca Servers 的存取連結,撤銷離職或遺失裝置。
75. 第三方 Plugins 與 Browser extensions 視為不受信任的軟體。
範例:Settings → Plugins 只啟用經資安審查的外掛;實驗性 Browser extensions 預設不開。
76. 定期盤點並移除不再需要的 Provider 帳號。
範例:每月檢查 Settings → Accounts 中的 Claude、Codex、OpenCode 等帳號,移除離職人員或過期帳號。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 無殘留環境 token | env 輸出中搜尋 GITHUB_TOKEN、GH_TOKEN | 不存在 | 移除並重新 gh auth login |
| 憑證檔權限 | ls -l ~/.copilot/config.json | -rw------- | chmod 600 並評估輪替 |
| 公開連結關閉 | Settings → Artifacts | 開關為關閉 | 關閉並檢查既有連結(關閉不會刪除舊連結) |
33.7 遠端與自動化
77. 長時間建置與測試移到 SSH 主機或 Remote Orca Server,本機專心審查。
範例:大型 monorepo 的全量測試在遠端 Worktree 執行,本機只開 Diff。
78. SSH 主機使用 managed Orca server,並在 Settings → Managed servers 追蹤版本。
範例:升級桌面端後,同步在 Managed servers 對主機執行 Update。
79. 桌面端與 paired 或 SSH 主機的 Orca 版本保持一致。
範例:v1.4.232 以後的多項 Native Chat 功能需主機同步更新,否則功能缺漏。
80. GitHub 驗證在每台遠端主機分別處理。
範例:SSH 進主機執行 gh auth status;筆電登入不等於遠端已登入。
81. 需要長駐的無頭伺服器用 orca serve --supervise 或 service 安裝。
範例:Linux 主機執行 orca serve service install --port 6768 --dry-run 預覽後再正式安裝。
82. 第一個自動化一定是唯讀或低風險任務。
範例:每天早上產出「昨日合併 PR 摘要」,而不是自動修改程式碼。
83. 自動化任務以 --extra-agent-args 固定模型與 effort。
範例:摘要類排程固定使用較省的模型,避免每次執行成本不同。
84. 自動化結果一律進入人工審查佇列,不自動合併。
範例:自動化只開 Draft PR,由值班工程師審查。
85. 監看自動化的錯過補跑與失敗紀錄。
範例:每週檢查 Automations 執行紀錄,計算第三十一章 KPI-6 成功率。
86. Orchestration 先在 Settings → Experimental 啟用,並以 orca status --json 確認 runtime 正常再派工。
範例:協調者 Agent 派工前先執行狀態檢查,失敗則停止派工。
87. Orchestration 的 heartbeat 與監控門檻依 v1.4.243 新預設(5 分鐘)調整。
範例:Settings → Agent Orchestration 調整 heartbeat 間隔;變更只套用新 worker。
88. Computer Use 與瀏覽器自動化遇到敏感輸入時交還人工。
範例:登入、付款、雙因素驗證步驟由人工完成,Agent 只負責其餘流程。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 版本一致 | 比對桌面版本與 Settings → Managed servers 顯示的主機版本 | 相同 | 對主機執行 Update |
| 遠端 gh 正常 | 在主機上 gh auth status -h github.com | 已登入 | 在主機上 gh auth login |
| Runtime 可用 | orca status --json | 回傳 JSON 無錯誤 | 依第二十九章排錯 |
33.8 維運與效能
89. 每週檢視官方 Release Notes,並維護內部累積相容性清單。
範例:平台組每週一更新 Wiki 上的第二十九章 29.2.1 對照表。
90. 採用 Release Ring,先在平台組與試點團隊升級。
範例:Stable 發布當天 Ring 0 升級,2~3 個工作天後 Ring 1,一週後全體。
91. Orca 與各 Agent CLI 的版本分開追蹤,並記錄兩者相依。
範例:版本清單中記錄「Codex chat 需 Codex ≥ 0.136.0」。
92. 升級後關閉並重開 terminal 再驗證修正。
範例:v1.4.243 起新 terminal host 只套用新開的 terminal。
93. 升級前備份資料目錄與未推送分支。
範例:執行第二十九章 29.3.3 的備份腳本,並以 git bundle verify 確認。
94. 排錯第一步永遠是確認版本號並查詢 Release Notes 與 Issues。
範例:遇到 Codex SUN_LEN 錯誤,先確認是否低於 v1.4.212。
95. 回報問題附上 Log、版本與重現步驟,並先遮蔽機敏資訊。
範例:使用第二十九章 29.4.4 範本,附上已掃描的 Log 壓縮檔。
96. 開啟 Agent Hibernation,並依記憶體設定閒置窗口。
範例:16 GB 筆電設 15 分鐘,32 GB 以上維持預設 30 分鐘。
97. 關閉不用的 Worktree 與瀏覽器分頁。
範例:每天下班前用 Resource Manager 依記憶體排序,關閉前五名中不再需要的項目。
98. 啟用 Resource Manager 並定期掃描 Workspace 磁碟用量。
範例:每月一次 Clean up workspaces,依大小排序清理已合併的 Worktree。
99. 每月計算每合併 PR 成本,並以 Provider 主控台為準。
範例:使用第三十章 30.4.4 方法,Orca Stats 只作趨勢參考。
100. 每半年檢視導入成效,決定擴大、維持或調整範圍。
範例:依第三十一章 KPI 總表召開半年檢討,結論寫入下一期導入計畫。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 相容性清單有更新 | 檢查 Wiki 修訂紀錄 | 最近 7 天內有更新 | 指定負責人與週期 |
| 備份可用 | 抽查一份備份做還原演練 | 還原成功 | 依第二十九章 29.3 修正流程 |
| Hibernation 已啟用 | Settings → Experimental | 已開啟且閒置窗口符合標準 | 依第三十章調整 |
33.9 本章 Review 與驗證清單
- 已從 100 條中挑出與目前成熟度相符的條目,寫成團隊約定並 commit 進 repo
- 每一條納入約定的規則都有對應的驗證方法與負責人
- 已確認 33.1 的共用設定(
orca.yaml、.worktreeinclude、Memory 檔)已入庫 - 已統一 Agent 權限模式,並抽查落實情形
- 已建立分支命名與 AI trailer 規範,且可用 git 指令統計
- 已完成 33.6 的安全檢查:環境 token、憑證檔權限、Artifacts、Telemetry
- 遠端主機與桌面端版本一致,遠端 gh 已各自登入
- 已建立升級、備份、Log 回報與成本計算的例行作業
- 已排定每季回顧本章規則並增修
第三十四章 與其他工具比較
AI 開發工具在 2026 年的演進速度,與 Orca 本身一樣快。本章的目的不是替任何工具打分數,而是提供一套可重複使用的比較框架:先定義比較維度,再列出各工具的公開定位,最後給出選型建議與一套「用自己的任務實測」的驗證方法。
📌 查證狀態:Orca 欄位為官方文件明確記載(v1.4.244)|其他工具欄位為依公開資訊整理(查證日 2026-10-30),本手冊未逐項實測,也刻意不列出價格、效能分數等精確數字。正式選型前,請以各工具官方網站與文件的當下版本為準,並用 34.3.3 的方法自行驗證。
34.1 比較維度說明
| 維度 | 要回答的問題 | 為什麼重要 |
|---|---|---|
| 產品型態 | 是編輯器、終端 Agent、桌面編排器,還是雲端自主 Agent? | 決定工程師的主要操作介面與學習曲線 |
| 主要執行位置 | 程式碼與 Agent 在本機、遠端主機,還是供應商雲端執行? | 牽涉資料落地、網路政策與算力成本 |
| 平行多 Agent 與隔離 | 能否同時跑多個 Agent?彼此如何避免互相覆寫檔案? | 平行度是 ADE 類工具的核心價值 |
| Agent 與模型來源 | 只能用自家 Agent 或模型,還是可以帶入多家 CLI? | 影響供應商鎖定風險與選型彈性 |
| 審查與 Git 整合 | Diff 審查、逐行回饋、PR、CI 狀態是否在同一處? | 審查是 AI 產出的品質關卡 |
| 遠端與行動端 | 能否在遠端主機執行、在手機上監看與回覆? | 長時間任務與跨裝置工作 |
| 授權與成本模式 | 工具本身是否收費?AI 用量如何計費? | 預算編列與成本治理 |
| 開源程度 | 原始碼是否公開可審閱? | 資安審查、客製與長期可用性 |
| 企業治理 | 權限模式、稽核軌跡、集中管理能力如何? | 企業導入的必要條件 |
如何使用這些維度:不同組織的權重不同。高監理產業會把「執行位置」與「企業治理」放在最前;新創可能最在意「平行度」與「成本」。34.3.3 會示範如何把維度轉成加權評分卡。
34.2 完整比較表
34.2.1 定位與執行模型
| 工具 | 產品型態 | 主要執行位置 | 平行多 Agent 與隔離 | Agent 與模型來源 |
|---|---|---|---|---|
| Orca | 開源桌面 ADE,管理多個 Agent CLI | 本機、WSL、SSH 主機、Remote Orca Server;Cloud VM 為實驗功能 | 原生核心能力:每個任務一個 git Worktree,Dashboard 集中追蹤 | 包裝多家 Agent CLI(Claude Code、Codex、Cursor CLI、Copilot CLI、Gemini、OpenCode、Devin 等);BYO 帳號 |
| Cursor | AI 優先的程式碼編輯器(VS Code 系) | 本機編輯器,另有雲端背景 Agent | 依公開資訊,近期版本支援多 Agent 平行並可使用 worktree 或雲端環境隔離 | 自家 Agent,內建多家模型供選擇 |
| Claude Code(獨立使用) | Anthropic 的終端 Agent,另有 IDE 擴充與其他介面 | 本機終端為主;依公開資訊另有網頁與雲端執行形式 | 可開多個 Session;隔離需自行建立 worktree 或使用其 subagent 機制 | Anthropic Claude 模型 |
| Codex app | OpenAI 的 Codex 桌面應用程式 | 本機與 OpenAI 雲端任務 | 依公開資訊,支援多個平行執行緒並內建 worktree 隔離 | OpenAI 模型;Codex CLI 本身為開源 |
| Conductor | 桌面應用程式,平行執行多個程式碼 Agent | 本機(依公開資訊以 macOS 為主) | 依公開資訊,每個 Agent 使用獨立工作區(git worktree) | 以 Claude Code、Codex 等既有 Agent 為主,使用者自備帳號 |
| VS Code + Copilot agent mode | 通用編輯器加 GitHub Copilot 的 Agent 模式 | 本機編輯器;Copilot coding agent 在 GitHub 雲端環境執行並開 PR | 編輯器內可管理多個 Agent Session;雲端 coding agent 以分支與 PR 隔離 | Copilot 訂閱內提供多家模型;依公開資訊也可整合第三方 Agent |
| Windsurf | AI 優先的程式碼編輯器 | 本機編輯器 | 依公開資訊支援多個 Agent 對話;隔離方式以官方文件為準 | 自家 Agent,內建多家模型 |
| Devin | 雲端自主軟體工程 Agent | 供應商雲端環境 | 可同時派出多個雲端 Session,各自在獨立環境中執行 | 供應商自家系統;Orca 亦可啟動 Devin 的 CLI 與 Open In Devin Desktop |
34.2.2 審查、遠端、成本與治理
| 工具 | 審查與 Git 整合 | 遠端與行動端 | 授權與成本模式 | 開源程度 | 企業治理重點 |
|---|---|---|---|---|---|
| Orca | Diff Viewer、Annotate AI Diff、Attribution(本機)、GitHub PR 與 Checks、Stacked PR、Linear 與 Jira | SSH Worktrees、Remote Orca Servers、orca serve;iOS(App Store)與 Android(APK)行動端 | 工具免費;AI 用量走各 CLI 自備訂閱或 API | 開源(MIT) | Manual、Auto、Yolo 權限模式;Telemetry 可停用;版本迭代快需 Release Ring |
| Cursor | 編輯器內 Diff 與審查;標準 git | 依公開資訊有網頁或行動端管理雲端 Agent 的方式,請以官方為準 | 訂閱制,依方案提供用量 | 專有軟體 | 依方案提供團隊管理與隱私模式,細節以官方為準 |
| Claude Code(獨立使用) | 終端內顯示變更;標準 git 與 gh | 可在任何能 SSH 的主機執行;其他介面以官方為準 | Anthropic 訂閱或 API 用量計費 | 專有軟體 | 自身有權限與設定檔機制;可被 Orca 包裝使用 |
| Codex app | 應用程式內審查 Diff;可建立 PR | 依公開資訊可將任務交給雲端執行 | 依 OpenAI 方案或 API 用量 | App 為專有軟體;Codex CLI 開源 | 依 OpenAI 企業方案的管理功能;Codex CLI 可被 Orca 包裝 |
| Conductor | 應用程式內審查 Diff 並建立 PR | 以本機為主,以官方為準 | 依官方公告;AI 用量走使用者自備帳號 | 專有軟體 | 與 Orca 定位接近,比較時重點看平台支援、Agent 種類與遠端能力 |
| VS Code + Copilot agent mode | 編輯器 Diff、GitHub PR 深度整合;雲端 coding agent 直接產生 PR | Remote SSH、Dev Containers、Codespaces;GitHub 行動 App 可檢視 PR | Copilot 訂閱制,依方案提供進階請求額度 | VS Code 核心開源,Copilot 為專有服務 | GitHub 組織層級政策與稽核,對已使用 GitHub Enterprise 者整合度高 |
| Windsurf | 編輯器內 Diff 與審查;標準 git | 以官方為準 | 訂閱制 | 專有軟體 | 依方案提供團隊管理,細節以官方為準 |
| Devin | 以 PR 形式交付;可與 Slack、GitHub 等整合 | 雲端執行,透過網頁或整合工具互動 | 依官方方案,通常以用量單位計費 | 專有服務 | 程式碼需在供應商雲端執行,需評估資料處理條款 |
📌 查證狀態:Orca 列為官方文件明確記載|來源:Supported agents、Ways to run Orca、Mobile companion、Attribution、GitHub Releases。其餘各列為依公開資訊整理(查證日 2026-10-30)。
⚠️ 注意事項:
- 「Orca 對比 X」常常不是二選一。Orca 本身不提供模型,而是包裝 Claude Code、Codex、Cursor CLI、Copilot CLI、Devin 等 Agent CLI;很多團隊的實際組合是「Orca + 一到兩個 Agent CLI」或「VS Code 或 Cursor 寫碼,Orca 管平行任務」。
- Orca 的 Attribution 只存在本機、不寫入 git;如果稽核需求要求持久化,需要從 Diff 工具列匯出 metadata(第十四章)。
- Orca 的版本節奏很快(第二十九章),比較表中的 Orca 能力也會持續變動。
34.3 選型建議
34.3.1 依情境選型
| 團隊情境 | 建議方向 | 理由 |
|---|---|---|
| 已穩定使用一到兩種 Agent CLI,想安全地規模化平行處理 | Orca 疊加在既有 CLI 之上 | 保留既有 Agent 與帳號,取得 Worktree 隔離、集中監看與審查 |
| 需要同時比較多家 Agent 的表現 | Orca | 同一題目可分派給不同廠牌的 Agent 並排比較 |
| 單人深度結對編碼、重視編輯器內即時補全 | Cursor、Windsurf 或 VS Code + Copilot | 編輯器整合體驗是其主場 |
| 全面採用 GitHub Enterprise,希望治理集中在 GitHub | VS Code + Copilot agent mode(可再評估搭配 Orca) | 組織政策、PR 與稽核整合在同一平台 |
| 純終端重度使用者、暫不需要平行管理 | 直接使用 Claude Code 或 Codex CLI | 工具最少、學習成本最低;日後需要平行時再加 Orca |
| 只使用 OpenAI 生態並偏好單一廠商 | Codex app | 與 OpenAI 帳號與雲端任務整合 |
| 希望把明確定義的工作交給雲端、較少即時互動 | Devin 或其他雲端自主 Agent | 不占本機資源;需評估資料處理與成本模式 |
| 程式碼不得離開自有基礎設施 | Orca + 自有 SSH 主機,搭配符合政策的模型供應 | 執行位置可控;仍需確認 Agent 送往的模型端點符合政策 |
| 需要在手機上監看與回覆 Agent | Orca(iOS、Android)或各工具官方行動方案 | Orca 行動端可接收通知、回覆與使用 Quick Commands |
flowchart TD
Q0["選型起點"] --> Q1{"程式碼可否送往供應商雲端執行?"}
Q1 -->|"不可"| LOCAL["本機或自有主機執行<br/>Orca + SSH 主機<br/>或編輯器 + 終端 Agent"]
Q1 -->|"可以"| Q2{"主要需求是什麼?"}
Q2 -->|"平行多 Agent 與跨廠牌比較"| ORCA["Orca + 既有 Agent CLI"]
Q2 -->|"編輯器內結對編碼"| IDE["Cursor 或 Windsurf<br/>或 VS Code + Copilot"]
Q2 -->|"交付明確任務給雲端"| CLOUD["Devin 或雲端 coding agent"]
Q2 -->|"單一廠商生態"| VENDOR["Codex app 或 Claude Code"]
LOCAL --> POC["34.3.3 實測評分"]
ORCA --> POC
IDE --> POC
CLOUD --> POC
VENDOR --> POC如何閱讀此圖:第一個問題是硬性限制(資料能否離開自有環境),會直接排除部分選項;第二個問題才是偏好。所有路徑最後都匯集到「實測評分」,因為表格與流程圖只能縮小範圍,無法取代在自己程式碼庫上的實測。
📌 查證狀態:教學示例(非官方)
34.3.2 組合使用模式
| 模式 | 組合 | 適合 |
|---|---|---|
| 編輯器為主、Orca 為輔 | Cursor 或 VS Code 處理日常編碼;Orca 處理需要平行或長時間的任務 | 想保留熟悉編輯器的團隊 |
| Orca 為主 | Orca 內的 Monaco 編輯器、Terminal、Diff Viewer 完成大部分工作;需要時用 Open in 開啟外部編輯器 | 以 Agent 產出為主、人工以審查為主的團隊 |
| 雲端加本機 | 明確任務交給雲端 Agent,探索與審查在 Orca 本機進行 | 有雲端預算且資料政策允許 |
34.3.3 用加權評分卡實測
操作步驟
- 從團隊的真實待辦中挑 3 個任務:一個小型修正、一個中型功能、一個需要探索的問題。
- 為每個候選工具準備相同的任務規格書與相同的完成定義(第二十章 20.4)。
- 每個工具由同一位工程師在相同時間窗口內執行,記錄耗時、人工介入次數、測試是否通過、審查發現的問題數。
- 依下方評分卡加權計分,並由第二位工程師獨立審查產出。
- 把評分結果與原始紀錄一起存檔,作為採購或導入決策的附件。
範例:加權評分卡(教學示例)
| 維度 | 權重 | Orca + 既有 CLI | 候選工具 B | 候選工具 C | 評分依據 |
|---|---|---|---|---|---|
| 平行多 Agent 與隔離 | 25% | 1~5 分 | 1~5 分 | 1~5 分 | 3 個任務同時執行時是否互相干擾 |
| 審查與 Git 整合 | 20% | 1~5 分 | 1~5 分 | 1~5 分 | 審查者完成審查所需時間與發現問題數 |
| 執行位置與資料政策 | 20% | 1~5 分 | 1~5 分 | 1~5 分 | 是否符合資料分級政策(不符合直接淘汰) |
| 產出品質 | 15% | 1~5 分 | 1~5 分 | 1~5 分 | 測試通過與返工次數 |
| 成本 | 10% | 1~5 分 | 1~5 分 | 1~5 分 | 以第三十章方法換算每任務成本 |
| 學習曲線 | 10% | 1~5 分 | 1~5 分 | 1~5 分 | 新手完成第一個任務所需時間 |
加權總分 = Σ(各維度分數 × 權重)
範例:Orca 若各維度得分為 5、4、4、4、4、3
5×0.25 + 4×0.20 + 4×0.20 + 4×0.15 + 4×0.10 + 3×0.10 = 4.15📌 查證狀態:教學示例(非官方)|範例分數為虛構,僅示範計算方式。
🧑⚖️ 人工 Review 要點(若由 AI 協助整理比較表或評分卡,審查者應確認)
- 每一項關於第三方工具的陳述都有官方來源連結與查證日期
- 沒有出現無來源的價格、效能百分比或市占數字
- 「不支援」的判斷有實際操作或官方文件佐證,而不是「沒找到」
- 實測紀錄(耗時、介入次數、測試結果)與評分一致
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 比較表為最新 | 逐列開啟官方連結核對 | 每列都在 30 天內查證過 | 更新查證日期與內容 |
| 實測可重現 | 第二位工程師用同一任務重跑一次 | 結論方向一致 | 增加任務樣本數 |
| 資料政策篩選先行 | 檢查評分卡中「執行位置與資料政策」 | 不符合者已淘汰、未進入加權 | 重新計算 |
| 決策有紀錄 | 檢查決策附件 | 含評分卡、原始紀錄、審查意見 | 補齊後再送審 |
❌ 常見錯誤:把網路上的比較表直接當作採購依據。各工具每月都有重大更新,且在你的程式碼庫、你的資料政策下表現可能完全不同。
💡 小技巧:Orca 可以同時啟動不同廠牌的 Agent CLI,本身就是很好的「Agent 選型實驗室」——同一題目分派給三家 Agent,各自在獨立 Worktree 中完成,再用 Diff Viewer 並排比較。
34.4 本章 Review 與驗證清單
- 能說明 9 個比較維度各自要回答的問題
- 能說出 Orca 與編輯器型工具、終端 Agent、雲端自主 Agent 的定位差異
- 理解 Orca 是包裝多家 Agent CLI 的管理層,可與其他工具組合使用
- 比較表中所有第三方陳述都標示「依公開資訊整理(查證日 2026-10-30)」並附官方來源
- 已依資料政策先做硬性篩選,再進行偏好比較
- 已用 3 個真實任務完成加權評分卡實測,並由第二位工程師複核
- 已把評分卡與原始紀錄存檔,並排定定期重新查證
第三十五章 Mermaid 圖表彙整
本章有兩個目的:第一,提供全書 Mermaid 圖表的索引,讓讀者在準備教育訓練簡報、撰寫內部規範或審查 AI 產出的架構文件時,能快速找到對應圖表;第二,補齊前面各章較少出現的圖表類型(Sequence、Class、ER、gitGraph、State、Deployment),並把每一張圖都對應到 Orca v1.4.244 的真實行為,附上「如何閱讀此圖」與「如何驗證此圖與現實一致」。
📌 查證狀態:依官方說明延伸(教學推論)|本章所有圖表皆為教學示意(非官方原廠圖),依官方文件快照(查證日期 2026-10-30)繪製,不代表 Orca 內部實作或資料庫結構|來源:Orca Docs
為什麼圖表也需要「驗證」:AI Agent 很擅長產出看起來合理的 Mermaid 圖,但圖與真實系統不一致時,會讓新人建立錯誤心智模型,甚至讓稽核文件失真。因此本章每張圖都附「✅ 驗證方式」,示範如何用 git worktree list、orca CLI 與 Orca UI 反向比對圖中每一個節點與箭頭。這也是第二十二章「AI 產出的 Review 與驗證方法論」在圖表類產出上的具體應用。
35.1 全書圖表索引
下表列出本章收錄的 8 張補充圖,以及各章預期收錄的主要圖表。其他章節的撰寫者可能因內容需要增補圖表;實際圖表以各章內文為準,本索引列出的是全書骨幹圖表,用於教學路徑規劃。
| 編號 | 圖表名稱 | 圖表類型 | 所在章節 | 主要用途 |
|---|---|---|---|---|
| 1 | Worktree 生命週期 | flowchart 或 stateDiagram | 第二章 2.2 | 說明 Create、Work、Review、Ship、Archive 五階段 |
| 2 | Orca 整體架構總覽 | flowchart | 第三章 3.1 | UI、Runtime、Agent CLI、Git 與外部整合的關係 |
| 3 | 遠端執行模式決策流程 | flowchart | 第十八章 18.7 | 依需求選擇 Local、SSH、Remote Orca Server、Cloud VM |
| 4 | 銀行案例治理與稽核流程 | flowchart | 第二十六章 26.4 | 高監理產業的審核關卡與證據保存 |
| 5 | 端到端企業案例流程 | flowchart | 第二十七章 27.3 | 從需求到維運的全流程與 Agent 分工 |
| 6 | 新人導入流程 | flowchart | 第三十五章 35.2 | 新進工程師從安裝到第一次合併的路徑 |
| 7 | Design Mode 互動序列 | sequenceDiagram | 第三十五章 35.3 | 點選 UI 元素到 Agent 修正、Hot Reload 的往返 |
| 8 | 核心概念模型 | classDiagram | 第三十五章 35.4 | Host、Project、Repository、Worktree、Session 的關係 |
| 9 | 設定與工作階段實體關係 | erDiagram | 第三十五章 35.5 | Automation、Orchestration 與 Worktree 的關聯 |
| 10 | 多 Agent 分支策略 | gitGraph | 第三十五章 35.6 | 同題競賽、堆疊分支與合併 |
| 11 | CI CD Pipeline | flowchart | 第三十五章 35.7 | 從 Worktree 到 Production 的品質關卡 |
| 12 | 遠端執行拓撲 | flowchart | 第三十五章 35.8 | 四種執行方式的部署位置與連線方式 |
| 13 | Agent 狀態機 | stateDiagram-v2 | 第三十五章 35.9 | Agent Session 狀態指示與轉換條件 |
本書圖表共同規範(所有章節一致適用,也適用於讓 AI 產出圖表時的要求):
| 規範 | 正確寫法 | 錯誤寫法 | 原因 |
|---|---|---|---|
| 中文或括號節點加雙引號 | A["Worktree(隔離)"] | A[Worktree(隔離)] | 未加引號時括號會被解析為形狀語法 |
| 不使用初始化指令 | 直接以 flowchart TD 開頭 | 以 %%{init: ...}%% 開頭 | 本站主題統一控制樣式 |
| 不以 end 作節點 id | DONE["結束"] | end["結束"] | end 是 subgraph 保留字 |
| classDiagram 不用 note | 以「如何閱讀此圖」文字說明 | note for Worktree "..." | 本站渲染器相容性考量 |
| 關係標籤冒號前後空格 | A --> B : runs | A --> B:runs | 避免解析失敗 |
| 標示非官方 | 圖前加 📌 查證狀態 | 無任何標示 | 避免被誤當原廠規格引用 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 索引與內文一致 | 在全書原始檔搜尋 mermaid 程式碼區塊並計數 | 每個索引項目都找得到對應圖 | 補上索引或於內文補圖 |
| 圖表可渲染 | 用 Mermaid CLI 逐張轉檔 | 每張圖都成功輸出 SVG | 依 F 規範修正語法 |
| 章節號正確 | 對照 OUTLINE.md 章標題 | 章號與標題逐字一致 | 修正索引章號 |
批次驗證 Mermaid 語法的範例(需要 Node.js):
# 將單張圖存成 diagram.mmd 後轉為 SVG,成功即代表語法可被 Mermaid v11 解析
npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg💡 小技巧:Orca 內建的檢視器可直接預覽 Mermaid(見第十二章 12.7)。在 Worktree 中開啟含 Mermaid 區塊的 Markdown 檔,即可在送出 PR 前目視確認圖表是否正確渲染。
⚠️ 企業治理考量:架構圖、資料流圖常被納入稽核文件。建議在圖表下方標註「繪製依據」(例如官方文件連結、程式碼路徑、查證日期),並把圖表原始碼納入版本控制,讓每次變更都能透過 Diff 審查。
35.2 Flowchart 新人導入流程
📌 查證狀態:教學示意(非官方原廠圖)|依官方說明延伸(教學推論)|來源:Your first 3-agent session、Worktrees
新進工程師導入 Orca 時,最常見的問題不是「不會用」,而是跳過驗證步驟:例如 Agent CLI 只在筆電登入、卻在 Remote Orca Server 上執行;或沒設定 .worktreeinclude,導致新 Worktree 少了 .env 而測試全部失敗。下圖把導入流程畫成含兩個檢查關卡的流程圖。
flowchart TD
A["新進工程師報到"] --> B["安裝 Orca Desktop(第四章)"]
B --> C{"orca status --json 成功?"}
C -->|"否"| C1["依第二十九章排錯"]
C1 --> B
C -->|"是"| D["安裝並登入 Agent CLI(第七章)"]
D --> E["加入 Repository 為 Project(第五章)"]
E --> F["確認 orca.yaml 與 .worktreeinclude(第二章)"]
F --> G["建立第一個 Worktree"]
G --> H["啟動 Agent 並貼上任務規格"]
H --> I["三個 Agent 同題競賽(第五章 5.4)"]
I --> J["Diff Viewer 與 Annotate AI Diff 審查(第十四章)"]
J --> K{"人工審查通過?"}
K -->|"否,附註記退回"| H
K -->|"是"| L["Commit、Push 並建立 PR"]
L --> M["刪除或封存落選 Worktree"]
M --> N["導師簽核新人驗收清單"]如何閱讀此圖
- 由上而下閱讀;菱形節點是必須有明確證據才能通過的關卡。
- 第一個關卡「
orca status --json成功?」確認 Orca Runtime 可被 CLI 存取,這是後續 CLI、Orchestration、Automations 的前提。 - F 節點提醒:新 Worktree 是乾淨的 checkout,被 gitignore 的檔案(如
.env)需要透過.worktreeinclude複製,或透過orca.yaml的worktree.sharedDirectories共用(如node_modules)。 - 第二個關卡「人工審查通過?」若不通過,回到 H 節點,帶著 Annotate AI Diff 的註記重新下達任務,而不是直接自己改程式碼——這是讓新人學會「指揮 Agent」而非「替 Agent 收尾」。
- M 節點強調清理:落選的 Worktree 應刪除,避免占用磁碟與 Agent 記憶體。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Runtime 可用 | orca status --json | 回傳 JSON 且無錯誤 | 確認 Orca Desktop 已啟動,見第十六章 16.1 |
| Worktree 已建立 | git worktree list | 出現新 Worktree 路徑與分支 | 檢查建立面板的錯誤訊息並按 Retry |
| 共用檔案到位 | 在新 Worktree 執行 git status --ignored 並確認 .env 存在 | .env 被列為 ignored 且檔案存在 | 檢查 .worktreeinclude 是否為字面路徑(不支援 glob) |
| 競賽產出可比較 | 三個 Worktree 分別執行 git diff --stat | 三份差異皆在任務範圍內 | 重新收斂任務規格的檔案範圍 |
| 清理完成 | 再次執行 git worktree list | 落選 Worktree 已不在清單中 | 使用 Resource Manager → Clean up workspaces |
⚠️ 企業治理考量:把 N 節點的「新人驗收清單」做成固定表單,要求附上 git worktree list 輸出與第一個 PR 連結,即可同時作為訓練紀錄與權限開通的依據。
35.3 Sequence Design Mode 互動
📌 查證狀態:教學示意(非官方原廠圖)|官方文件明確記載互動步驟,圖形為教學整理|來源:Design Mode、Fix a UI bug with Design Mode
Design Mode 把 Orca 內建瀏覽器變成「指向即程式碼」的工具:點選畫面元素,元素的 HTML、Computed CSS、裁切截圖(以及在有 dev source map 時的原始檔與行號)會作為單一附件送進作用中的 Agent。下圖以時序呈現一次完整的修正往返。
sequenceDiagram
autonumber
actor U as 前端工程師
participant B as Orca 內建瀏覽器
participant T as Annotation Tray
participant A as Agent(作用中終端機)
participant S as Dev Server
U->>B: 點擊工具列的 Design Mode 切換
B-->>U: 游標變為選取器並高亮懸停元素
U->>B: 點選目標元素
B->>B: 擷取 outer HTML 與鄰近結構
B->>B: 擷取 Computed CSS 與裁切截圖
B->>B: 若有 dev source map 則解析原始檔與行號
U->>T: 新增或就地編輯多則註記
U->>A: 輸入想修改的內容並送出
T->>A: 元素脈絡以單一附件送達
T-->>T: 移除已送出的註記
A->>S: 修改原始碼並存檔
S-->>B: Hot Reload 重新渲染頁面
U->>B: 再次點選元素確認修正結果如何閱讀此圖
- 參與者由左至右:工程師、內建瀏覽器、註記匣(Annotation Tray)、Agent、開發伺服器。
- 第 4 至 6 步是 Orca 自動擷取的脈絡,工程師不必手動複製 DOM 或截圖,這是 Design Mode 相較「截圖貼給 AI」的主要差異。
- 第 7 步的 Annotation Tray 允許先累積多則註記,再一次送出;送出後 Orca 會移除已送出的註記(第 10 步),而送出過程中新增或編輯的註記會保留。
- 第 11 至 13 步是驗證迴圈:修改後由 Hot Reload 反映,工程師必須再次點選確認,而不是只看 Agent 回報「已修正」。
- 「Annotate page element」動作也可在 Settings → Shortcuts 重新綁定快捷鍵。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 脈絡已送達 | 在 Agent 終端機或 Native Chat 檢視附件 | 可看到元素 HTML、樣式與截圖 | 確認焦點在正確的 Agent 分頁 |
| 原始碼定位正確 | 在 Agent 回覆中找出檔案與行號,於 Monaco 開啟 | 指向實際渲染該元素的元件 | 確認 dev server 有輸出 source map |
| 修改範圍合理 | 在 Worktree 執行 git diff --stat | 僅修改相關的元件或樣式檔 | 用 Annotate AI Diff 標註退回 |
| 視覺結果正確 | Hot Reload 後再次點選該元素 | 樣式符合需求且其他元素未跑版 | 加開不同裝置尺寸再驗證一次 |
⚠️ 企業治理考量:Design Mode 會把頁面內容與截圖送入 Agent 的模型供應商。若頁面含真實客戶資料,必須改用遮罩或測試資料,並遵循第二十八章的資料外洩防護規範。
35.4 Class Diagram 核心概念模型
📌 查證狀態:教學示意(非官方原廠圖)|依官方說明延伸(教學推論);類別與屬性名稱為教學用抽象,不是 Orca 原始碼中的型別|來源:Worktrees、Agents and sessions、Ways to run Orca
第二章介紹了 Project、Worktree、Agent、Session 等概念。下圖用類別圖把它們的「一對多」關係一次呈現,特別加入 v1.4.x 後越來越重要的 Host(執行位置)、Linked Work(關聯的 PR/Issue)與巢狀 Worktree(Parent workspace)。
classDiagram
class Host {
+String kind
+String name
+String connectionState
}
class Project {
+String name
+String baseRef
}
class Repository {
+String path
+String orcaYamlPath
}
class Worktree {
+String displayName
+String branch
+String startFromRef
+String workspaceStatus
+String comment
}
class AgentSession {
+String agent
+String state
+String launchArgs
+restart()
}
class Tab {
+String kind
+String title
}
class LinkedWork {
+String provider
+String url
}
Host "1" --> "*" Project : hosts
Project "1" --> "1..*" Repository : groups
Repository "1" --> "*" Worktree : checks out
Worktree "1" --> "*" AgentSession : runs
Worktree "1" --> "*" Tab : contains
Worktree "1" --> "*" LinkedWork : links
Worktree "0..1" --> "*" Worktree : parent of如何閱讀此圖
- Host:Worktree 實際執行的位置,
kind可理解為 Local、SSH、Remote Orca Server、Cloud VM 四類(見 35.8)。 - Project 與 Repository:一般情況一個 Project 對應一個 Git Repo;匯入含多個 Repo 的父資料夾時,可組成 project group,因此畫成
1..*。 - Worktree:每個任務一個真實的 git worktree,擁有自己的分支、磁碟上的檔案與 Agent 終端機。
startFromRef對應建立時的 Branch from 選擇;comment與workspaceStatus對應 Worktree Checkpoints(todo、in-progress、in-review、completed)。 - AgentSession:一個 CLI Agent 在一個 Worktree 的一個終端機內執行;結束後可由 Restart Chip 以相同工作目錄重啟(
restart())。 - Tab:Terminal、Editor、Browser 等分頁皆以 Worktree 為範圍。
- LinkedWork:GitHub PR、GitLab MR、Linear、Jira 項目,可在建立時或 Edit Worktree Details → Linked work 附加多筆。
- 自我關聯:Advanced 抽屜可指定 Parent workspace,或由 Orchestration 建立子 Worktree;這只影響側邊欄巢狀顯示,不改變 Git 歷史。
✅ 驗證方式
執行以下指令取得實際物件:
orca repo list --json orca worktree list --json orca worktree current --json orca terminal list --worktree active --json預期判讀(示意):
repo list → 每個 Repository 一筆,對應圖中 Repository worktree list → 每個 Worktree 含分支與路徑,對應圖中 Worktree worktree current → 可看到 comment 與 workspace 狀態欄位 terminal list → 該 Worktree 底下的終端機,對應 AgentSession 與 Tab判讀:若
git worktree list的筆數多於 Orca 側邊欄,代表有外部建立的 Worktree 被隱藏,可從 Non-Orca worktrees 對話框選擇 Show;這也驗證了「Repository 對 Worktree 為一對多,但 Orca 只顯示已納管者」。
35.5 ER Diagram 設定與工作階段
📌 查證狀態:教學示意(非官方原廠圖)|依官方說明延伸(教學推論);非 Orca 實際資料庫綱要,僅用於理解物件間的業務關聯|來源:Scheduled automations、Orchestration、Usage tracking
企業導入時,稽核人員最常問:「這次程式變更是哪個 Automation 觸發?用了哪個帳號?在哪台主機跑?」下圖以實體關係圖串起 Host、Worktree、Agent 帳號、Automation 與 Orchestration,作為設計稽核欄位與追溯流程的參考。
erDiagram
HOST ||--o{ PROJECT : "hosts"
PROJECT ||--|{ REPOSITORY : "groups"
REPOSITORY ||--o{ WORKTREE : "checks out"
WORKTREE ||--o{ AGENT_SESSION : "runs"
AGENT_ACCOUNT ||--o{ AGENT_SESSION : "authenticates"
WORKTREE ||--o{ LINKED_WORK : "references"
AUTOMATION ||--o{ AUTOMATION_RUN : "produces"
AUTOMATION_RUN }o--o| WORKTREE : "runs in"
ORCH_RUN ||--o{ ORCH_TASK : "contains"
ORCH_TASK ||--o{ DISPATCH : "attempts"
DISPATCH }o--|| AGENT_SESSION : "assigned to"
HOST {
string hostId PK
string kind
string name
}
WORKTREE {
string worktreeId PK
string branch
string startFromRef
string workspaceStatus
}
AGENT_SESSION {
string sessionId PK
string agent
string state
}
AGENT_ACCOUNT {
string accountId PK
string agent
string label
}
AUTOMATION {
string automationId PK
string trigger
string provider
boolean enabled
}
AUTOMATION_RUN {
string runId PK
string outcome
datetime startedAt
}
ORCH_TASK {
string taskId PK
string status
}
DISPATCH {
string dispatchId PK
string outcome
}如何閱讀此圖
- 符號
||--o{代表「一對零或多」,||--|{代表「一對一或多」,}o--o|代表「多對零或一」。 - AUTOMATION 與 AUTOMATION_RUN:一個排程會產生多次執行紀錄;執行可能在既有 Worktree(
--workspace)或依 Repo 建立新工作(--repo),若 Precheck 失敗會記錄為 skipped,因此與 WORKTREE 是「零或一」。 - ORCH_TASK 與 DISPATCH:一個 Task 可有多次 Dispatch(重試時用
--retry-of),Task 狀態包含pending、ready、dispatched、completed、failed、blocked;完成權威來自當下有效的 Dispatch,因此worker_done必須同時帶taskId與dispatchId。 - AGENT_ACCOUNT:對應多帳號 Hot-swap 與 Usage 追蹤(第八章),稽核時可用來回答「哪個帳號花了多少用量」。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Automation 與 Run 為一對多 | orca automations runs --id <automationId> --json | 同一 automationId 下有多筆執行紀錄 | 先用 orca automations run <automationId> --json 手動觸發一次 |
| Task 與 Dispatch 為一對多 | orca orchestration task-list --json 後執行 orca orchestration dispatch-show --task <taskId> --json | 可看到 Task 狀態與目前 Dispatch | 確認已在 Settings → Experimental 啟用 Orchestration |
| Session 與帳號關聯 | 在 Settings → Agents 的 Usage 檢視比對 | 用量歸屬到正確帳號 | 見第八章 8.2 |
| Host 與 Worktree 關聯 | orca host list --json 與 orca worktree list --json 對照 | 遠端 Worktree 對應到正確 Host | 檢查建立時 Run on 選項 |
⚠️ 企業治理考量:若要建立內部稽核報表,建議以本圖為「概念模型」,實際欄位一律從 CLI 的 --json 輸出擷取,而非假設 Orca 內部資料表結構;Orca 版本更新時欄位可能調整,報表腳本需納入升級回歸測試(第二十九章 29.2)。
35.6 Git Flow 多 Agent 分支策略
📌 查證狀態:教學示意(非官方原廠圖)|依官方說明延伸(教學推論)|來源:Worktrees、Run parallel agents
Orca 每個 Worktree 都有自己的分支,從 Branch from 指定的起點(預設為 Repo 的 base ref,通常是 origin/main)分出。下圖示範一個典型情境:三個 Agent 同題競賽,Codex 的方案勝出並合併;另有一條「堆疊在審查中 PR 之上」的文件分支,最後依序合併。
gitGraph
commit id: "base"
branch agent-claude
checkout agent-claude
commit id: "claude-impl"
checkout main
branch agent-codex
checkout agent-codex
commit id: "codex-impl"
commit id: "codex-tests"
checkout main
branch agent-gemini
checkout agent-gemini
commit id: "gemini-impl"
checkout agent-codex
branch stacked-docs
checkout stacked-docs
commit id: "docs"
checkout main
merge agent-codex
merge stacked-docs
commit id: "release"如何閱讀此圖
main上的base是三個競賽 Worktree 共同的起點,確保比較公平。agent-claude、agent-codex、agent-gemini各對應一個 Worktree 與一個 Agent,彼此檔案完全隔離。stacked-docs從agent-codex分出,對應建立 Worktree 時在 Branch from 選擇「另一個本地分支」,適合在 PR 審查期間先行撰寫文件。- 只有
agent-codex與stacked-docs被合併;agent-claude、agent-gemini為落選方案,應刪除 Worktree。刪除時 Orca 會一併移除目錄與分支,若 git 因可能含未合併 commit 而保留分支,會出現 Review N Branches 提示,讓你決定是否強制刪除。
✅ 驗證方式
執行:
git worktree list git log --oneline --graph --all -n 20 git branch --merged main預期輸出(示意):
/repo a1b2c3d [main] /repo-wt/agent-claude b2c3d4e [agent-claude] /repo-wt/agent-gemini c3d4e5f [agent-gemini]判讀:
git branch --merged main應包含agent-codex與stacked-docs;若仍看到已合併分支對應的 Worktree,代表尚未清理。落選的agent-claude、agent-gemini在決策完成後也應從git worktree list消失。
❌ 常見錯誤:讓三個 Agent 從不同起點分支(例如有人選了舊 commit),導致比較結果失真。建立競賽 Worktree 時應統一 Branch from。
35.7 CI CD Pipeline
📌 查證狀態:教學示意(非官方原廠圖)|依官方說明延伸(教學推論);Orca 不提供 CI 伺服器,CI 由 GitHub Actions 或企業自有平台執行|來源:Commit and push、GitHub integration
Orca 負責「開發與審查」端:在 Worktree 中完成實作、審查 Diff、Commit、Push、建立 PR,並可在 Orca 內等待 Checks。部署則屬於企業自有管線。下圖把兩者的交接點畫清楚,避免誤以為 Agent 可以直接部署到正式環境。
flowchart LR
subgraph DEV["Orca Worktree(本機或遠端)"]
W1["Agent 實作"] --> W2["本地測試與 Lint"]
W2 --> W3["Diff 審查與 Annotate AI Diff"]
W3 --> W4["Commit(含 Attribution)"]
end
subgraph SCM["GitHub"]
P1["Push 分支"] --> P2["建立 PR"]
P2 --> P3["Actions Checks"]
P3 --> P4{"Checks 與人工 Review 皆通過?"}
end
subgraph DEPLOY["企業部署管線"]
D1["Build 與相依套件掃描"] --> D2["部署 Staging"]
D2 --> D3["UAT 驗收"]
D3 --> D4["變更審核後部署 Production"]
end
W4 --> P1
P4 -->|"否"| W1
P4 -->|"是"| D1
D4 --> MON["監控與回饋為新 Issue"]
MON -.-> W1如何閱讀此圖
- 左側 DEV 區塊全在 Orca 內完成,Attribution 讓 commit 帶有 AI 協作歸屬資訊(第十四章 14.4)。
- 中間 SCM 區塊的 PR 與 Checks 可在 Orca 內檢視(第十五章 15.2);P4 是雙重關卡:自動化 Checks 與人工 Review 缺一不可。
- 右側 DEPLOY 區塊由企業既有平台負責,Agent 不應持有 Production 部署憑證。
- 虛線箭頭代表監控發現的問題以新 Issue 回流,並可透過 Linear、Jira、GitHub 連結建立新的 Worktree。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 本地品質關卡有執行 | 檢查 PR 描述中附的測試指令與輸出 | 含實際指令與通過結果 | 退回並要求補證據 |
| Checks 狀態正確 | gh pr checks <PR編號> 或 Orca 內 PR 狀態 | 全部為 pass | 先修正再請求 Review |
| 分支保護生效 | gh api repos/<owner>/<repo>/branches/main/protection | 需要審查與狀態檢查 | 由 Repo 管理員設定 Branch protection |
| Agent 無部署權限 | 檢查 Agent 執行主機的環境變數與憑證 | 不存在 Production 部署金鑰 | 依第二十八章移除並輪替金鑰 |
35.8 Deployment 遠端執行拓撲
📌 查證狀態:教學示意(非官方原廠圖)|官方文件明確記載四種執行方式,拓撲為教學整理|來源:Ways to run Orca、SSH worktrees、Remote Orca Servers
Orca 的每個 Worktree 都必須「在某處執行」。v1.4.244 提供四種方式:Local、SSH Target、Remote Orca Server、Cloud VM(每工作區環境),而且可在同一個安裝中混用。下圖呈現 UI、Runtime、Agent 與檔案在各模式下的位置。
flowchart TB
subgraph CLIENT["使用者端"]
UI["Orca Desktop UI(筆電)"]
MOB["Orca Mobile"]
end
subgraph LOCALMODE["模式一 Local"]
L1["Agent、Terminal、Browser 皆在本機"]
L2["本機磁碟上的 git worktree"]
end
subgraph SSHMODE["模式二 SSH Target"]
S1["Orca 在主機上自動部署的受管伺服器"]
S2["遠端 git worktree 與 Agent 程序"]
end
subgraph ROSMODE["模式三 Remote Orca Server"]
R1["Orca Desktop 或 orca serve"]
R2["Projects、Worktrees、Terminals、Agent Sessions"]
end
subgraph VMMODE["模式四 Cloud VM(每工作區環境)"]
V0["orca.yaml 的 Recipe 與生命週期腳本"]
V1["自備 Provider:Vercel Sandbox、Fly、Modal、Docker"]
V2["每個 Worktree 一個可拋棄環境"]
end
UI --> L1
L1 --> L2
UI -->|"SSH"| S1
S1 --> S2
UI -->|"Tailscale 存取連結配對"| R1
MOB -->|"Tailscale 配對"| R1
R1 --> R2
UI -->|"Run on 選擇 Recipe"| V0
V0 --> V1
V1 --> V2
V2 -->|"pairing URL 或 SSH 連線資訊"| UI如何閱讀此圖
- Local:最單純的模式,UI 與 Runtime 在同一台機器,適合日常快速迭代。
- SSH Target:筆電上的 Orca 擁有 Runtime,透過 SSH 在遠端主機執行 git worktree 與 Agent;Orca 首次連線會在主機上部署自己的受管伺服器,因此遠端 Node 版本不符也不會阻擋連線。編輯器、Diff 與 UI 留在筆電。
- Remote Orca Server:遠端機器擁有完整 Runtime(Desktop App 或
orca serve),筆電、瀏覽器與手機都只是 UI;筆電闔上後 Agent 仍持續執行。建議走 Tailscale 等私有網路,不得把 Orca 連接埠直接暴露到公網。 - Cloud VM:在 Settings → Experimental → Cloud VM 啟用,由 Repo 中
orca.yaml的 Recipe 決定如何建立、暫停、恢復、銷毀環境;Provider 帳號與費用由使用者自備,Orca 不提供託管 VPS。環境建立後透過 pairing URL(Recipe 啟動orca serve)或 SSH 連線資訊接回 UI。 - 四種模式可混用:快速修改用 Local、GPU 工作用 SSH、需要 CI 般隔離時用 Recipe。
| 模式 | Runtime 擁有者 | 斷線後 | 多用戶端 | 典型設定入口 |
|---|---|---|---|---|
| Local | 筆電 Orca | 闔上筆電即暫停 | 否 | 直接建立 Worktree |
| SSH Target | 筆電 Orca | Agent 在主機上持續,筆電重新附著 | 一台筆電驅動 | Settings → SSH |
| Remote Orca Server | 遠端 Orca | 完整狀態保存在伺服器 | 筆電、Web、Mobile、Automation 共用 | Settings → Remote Orca Servers |
| Cloud VM | 每工作區環境 | 依 Recipe 的 suspend 與 resume | 依連線方式 | Settings → Experimental → Cloud VM |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 主機清單正確 | orca host list --json | 列出已設定的 SSH 與 Remote Orca 主機 | 回到 Settings 重新新增 |
| SSH Worktree 真的在遠端 | 在該 Worktree 終端機執行 hostname 與 git worktree list | 顯示遠端主機名稱與遠端路徑 | 確認建立時 Run on 選對主機 |
| Remote Orca Server 已連線 | Settings → Remote Orca Servers 狀態 | 顯示 Connected | 檢查 Tailscale 兩端是否在同一 tailnet |
| 伺服器端 Agent 已登入 | 在伺服器 shell 執行 orca account list | 列出 Claude、Codex 等受管帳號 | 於伺服器執行 orca account add --agent claude |
| Cloud VM Recipe 生效 | 建立 Worktree 時 Run on 清單 | 出現 Recipe 選項 | Recipe 必須寫在主要 checkout 的 orca.yaml |
| 未暴露公網 | 從外部網路掃描 Orca 連接埠 | 無法連線 | 關閉連接埠轉送,改走 Tailscale |
⚠️ 企業治理考量:Remote Orca Server 的存取連結等同密碼,每個配對用戶端都有可撤銷的獨立 Token,可在 Shared Server Access 撤銷。企業應定期盤點授權並記錄撤銷紀錄,詳見第二十八章 28.4。
35.9 State Diagram Agent 狀態機
📌 查證狀態:教學示意(非官方原廠圖)|依官方說明延伸(教學推論);狀態名稱對應官方狀態指示,轉換條件為教學整理|來源:Agents and sessions、Agent hibernation
Orca 透過終端機的 OSC 標題序列與 Agent Hooks 偵測 Agent 狀態,並在 Worktree 卡片、分頁與 Agent Dashboard 用一致的圖示呈現。理解狀態機,能幫助你判斷「哪個 Agent 需要我」以及「哪些 Agent 會被休眠以節省記憶體」。
stateDiagram-v2
state "啟動中(Launch)" as Launching
state "工作中(Spinner)" as Working
state "等待你(Needs You)" as NeedsYou
state "完成(Done)" as Done
state "閒置(Idle 灰點)" as Idle
state "受阻或失敗(紅點)" as Blocked
state "休眠(Hibernated)" as Hibernated
state "已結束(Restart Chip)" as Exited
[*] --> Launching : 從 Agent 選單啟動
Launching --> Working : OSC 標題或 Hook 回報
Working --> NeedsYou : 權限請求或提問
NeedsYou --> Working : 使用者回覆
Working --> Done : 回合完成並發出通知
Working --> Blocked : 中斷或錯誤
Working --> Idle : 約 30 分鐘無活動且未回報完成
Idle --> Working : 收到新輸入
Done --> Working : 下達新 Prompt
Done --> Hibernated : 符合休眠條件且超過閒置時間
Hibernated --> Launching : 重開 Worktree 以 resume 旗標重啟
Blocked --> Exited : 程序結束
Done --> Exited : 使用者離開 CLI
Exited --> Launching : 點擊 Restart Chip
Exited --> [*] : 刪除或封存 Worktree如何閱讀此圖
- 每個狀態對應 UI 圖示:Spinner 為工作中、琥珀色問號為等待你、翠綠勾或點為完成、紅點為受阻或失敗、灰點為閒置;一般 shell(非已知 Agent)則沒有指示。
- NeedsYou 在 Agent Dashboard(Settings → Experimental → Agent Dashboard)會出現在 Needs You 欄並以琥珀色標示,是最需要人工介入的狀態。
- Hibernated 需在 Settings → Experimental → Agent hibernation 啟用,且同時符合:已完成、非前景 Worktree、完成後無按鍵、屬可 resume 的 Agent、超過閒置時間(預設 30 分鐘,可設 1 分鐘至 24 小時)、沒有行動端操作、沒有未結束的 Orchestration Dispatch。
- Exited 狀態下分頁會出現 Restart Chip,一鍵以相同工作目錄重新啟動;Codex 的 Restart Chip 會保留目前帳號。
- 本圖為教學簡化,例如 Agent Dashboard 的 Idle 欄預設隱藏,需在看板設定中開啟 Show idle agents。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| Working 與 Done 轉換 | 給 Agent 一個短任務,觀察 Worktree 卡片 | Spinner 轉為完成圖示並收到通知 | 確認是從 Agent 選單啟動而非手打指令 |
| NeedsYou 狀態 | 將某 Agent 改為 Manual 權限後要求執行指令 | 出現琥珀色問號並列入 Needs You | 檢查 Settings → Agents → Agent Permissions |
| 等待閒置可程式化判斷 | orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json | 在 Agent 閒置時回傳 | 確認 handle 來自 orca terminal list |
| Hibernation 生效 | 將閒置時間設為 1 分鐘,切到其他 Worktree 等待 | 原 Worktree 顯示為休眠,重開後自動 resume | 確認 Agent 屬可 resume 清單,Cursor CLI 等不會休眠 |
| Restart Chip | 在 Agent 終端機結束 CLI | 分頁出現 Restart Chip | 若無,代表該終端機未被辨識為 Agent |
35.10 本章 Review 與驗證清單
- 能說出全書骨幹圖表分別位於哪些章節,並能依 35.1 的規範表檢查一張新圖是否合格
- 已用
npx -p @mermaid-js/mermaid-cli mmdc或 Orca 內建檢視器確認本章 8 張圖皆可渲染 - 能依 35.2 的兩個關卡,說明新人導入時為何必須先通過
orca status --json - 能說明 Design Mode 擷取的四類脈絡(HTML、Computed CSS、截圖、source map 位置),以及送出後註記如何處理
- 已用
orca worktree list --json與git worktree list對照 35.4 的類別圖,並理解 Parent workspace 不改變 Git 歷史 - 能用
orca automations runs與orca orchestration dispatch-show驗證 35.5 中的一對多關係 - 已用
git log --oneline --graph --all驗證多 Agent 分支圖,並完成落選 Worktree 清理 - 能指出 CI CD 流程中 Orca 與企業部署管線的交接點,且確認 Agent 不持有 Production 憑證
- 能比較四種執行方式的 Runtime 擁有者、斷線行為與設定入口
- 能解釋 Agent 各狀態圖示,並說明 Hibernation 的觸發條件
- 所有自行繪製或由 AI 產出的圖表都已標示「教學示意(非官方原廠圖)」或繪製依據
第三十六章 Prompt Library
本章收錄 120 則可直接改寫使用的 Prompt,涵蓋 12 個工程類別(每類 9 則)與 Orca 專屬的 Orchestration、Automations、Checkpoint 類別(12 則),全章連續編號 P1~P120。與舊版只列一句話的寫法不同,新版每一則都包含三個部分:
- Prompt 本體:可直接貼入 Agent 終端機或 Native Chat 的完整指令,含範圍、限制、產出格式與證據要求。
- 預期產出:AI 應交付的成品形態,讓你事先知道「要收什麼」。
- 🧑⚖️ 驗證要點:人工審查者用來確認 AI 產出正確性的檢查項目,盡量以可執行指令或可量化準則表達。
📌 查證狀態:教學示例(非官方)|Prompt 內容為本書撰寫之教學範例;其中引用的 Orca CLI 指令依官方文件快照(v1.4.244,查證日期 2026-10-30)|來源:Orca CLI reference、Orchestration、Scheduled automations
36.1 使用方式與驗證原則
36.1.1 Prompt 的標準結構
本章所有 Prompt 都採用同一個六段骨架,對應第二十章 20.4 的任務規格書。你可以把任何一則 Prompt 拆開來看,找到這六段:
| 區段 | 作用 | 範例片段 |
|---|---|---|
| 角色與目標 | 告訴 Agent 這次扮演誰、要達成什麼 | 你是資深後端工程師,目標是… |
| 背景與輸入 | 指定要讀的檔案、文件或 Issue | 先閱讀 docs/api-schema.md |
| 範圍 | 明確列出允許修改與禁止修改的路徑 | 只能修改 src/modules/customer/ |
| 限制 | 不得新增相依、不得改公開 API 等 | 不得修改任何 migration 檔 |
| 產出格式 | 檔案、表格、Markdown、Mermaid、JSON | 以 Markdown 表格輸出 |
| 證據要求 | 要求附上實際執行的指令與輸出 | 列出執行過的測試指令與結果 |
36.1.2 佔位符與改寫方式
Prompt 中以角括號表示需要替換的佔位符,例如 <模組路徑>、<目標版本>。改寫時請遵守三個原則:
- 替換所有佔位符:送出前搜尋角括號,確認沒有遺漏;遺漏的佔位符會讓 Agent 自行猜測。
- 縮小而非放大範圍:寧可把一則 Prompt 拆成兩個 Worktree 執行,也不要把範圍寫成「整個專案」。
- 保留證據要求段落:這是人工驗證的基礎,不可為了省 Token 刪除。
範例:改寫前後對照
改寫前(舊版風格,過於籠統):
請為 OrderService 補齊單元測試。改寫後(本章風格):
你是測試工程師。請閱讀 src/main/java/com/acme/order/OrderService.java 與既有測試 src/test/java/com/acme/order/。
範圍:只能新增或修改 src/test/java/com/acme/order/ 下的檔案,不得修改產品程式碼。
任務:為 OrderService 的 placeOrder 與 cancelOrder 補齊單元測試,涵蓋正常路徑與至少 3 種例外情境(庫存不足、重複取消、付款逾時)。
產出:測試檔案,以及一張表格列出每個測試方法對應的情境。
證據:執行 mvn -q -Dtest=OrderServiceTest test,貼上完整結果摘要;若有失敗,說明原因而非刪除測試。36.1.3 在 Orca 中執行 Prompt 的建議做法
| 情境 | 建議做法 | 對應章節 |
|---|---|---|
| 單一任務 | 每則 Prompt 一個新 Worktree,名稱帶 Prompt 編號(例如 p37-order-tests) | 第五章 |
| 想比較方案 | 同一 Prompt 分派給 2 至 3 個 Agent 同題競賽 | 第十一章 11.2 |
| 需要追蹤完成 | 用 Orchestration 建立 Task 並以 worker-start 分派 | 第十六章 16.3 |
| 例行性任務 | 先以 --disabled 建立 Automation,手動 run 驗證後再啟用 | 第十七章 |
| 讓協作者知道進度 | 要求 Agent 以 orca worktree set --comment 更新 Checkpoint | 第十六章 16.5 |
| 常用 Prompt | 設為 Quick Commands 或納入團隊 Skills | 第十二章 12.2、第十六章 16.4 |
36.1.4 通用證據尾段
任何一則 Prompt 都可在最後附加以下段落,讓產出格式一致、方便審查:
完成後請在回覆最後輸出「交付摘要」,包含:
1. 修改的檔案清單(等同 git diff --stat 的內容)
2. 實際執行過的指令與其輸出摘要(不可只寫「已通過」)
3. 未完成事項與已知風險
4. 你做出的假設,以及需要人工確認的決策點
並執行 orca worktree set --worktree active --comment "<一行摘要>" --workspace-status in-review --json 更新 Checkpoint。36.1.5 驗證原則
AI 產出的內容在被人工驗證之前,都只是候選答案。本章所有「🧑⚖️ 驗證要點」都依循以下原則(完整方法論見第二十二章):
- 證據優先於陳述:Agent 說「測試已通過」不算數,必須能重跑相同指令得到相同結果。
- 範圍檢查第一:先用
git diff --stat確認只動了允許的檔案,再看內容。 - 抽樣回到原始來源:分析類產出(盤點、逆向、架構評估)至少抽 3 處回到原始碼核對。
- 可重現性:數字(效能、覆蓋率、成本)必須附量測方法,能由審查者重現。
- 機敏資料零容忍:Banking 與 Security 類 Prompt 只使用去識別化資料,產出中出現疑似個資即退回。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 佔位符已替換 | 送出前在 Prompt 中搜尋角括號 | 無殘留佔位符 | 補齊後再送出 |
| 範圍受控 | git diff --stat | 只出現 Prompt 允許的路徑 | 以 Annotate AI Diff 標註退回 |
| 證據可重現 | 審查者自行重跑 Agent 提供的指令 | 結果與 Agent 回報一致 | 視為未完成,要求重做 |
| Checkpoint 已更新 | orca worktree current --json | comment 反映最新狀態 | 提醒 Agent 補寫 |
36.2 Architecture
架構類 Prompt 的產出多為文件與圖表,最大風險是「看起來合理但與程式碼不符」。驗證時務必抽樣回到原始碼,並確認 Mermaid 可渲染。
P1|現況架構盤點與 Context 圖
你是軟體架構師。請只讀取(不修改)本 Repo,盤點目前系統的高層架構。
任務:
1. 列出所有可部署單元(服務、批次、前端),每項附進入點檔案路徑。
2. 列出各單元之間的呼叫關係,標示同步(HTTP、gRPC)或非同步(MQ、事件)。
3. 以 Mermaid flowchart 繪製架構圖,含中文或括號的節點文字一律加雙引號。
限制:不得推測未在程式碼中出現的元件;不確定處標示「待確認」。
產出:docs/architecture/current-state.md。預期產出:一份 Markdown 文件,含可部署單元表、呼叫關係表與一張 Mermaid 架構圖,每個元件都有檔案路徑佐證。
🧑⚖️ 驗證要點:
-
git diff --stat只新增docs/architecture/current-state.md - 隨機抽 3 個呼叫關係,用
rg "<目標服務名>" src在程式碼中找到實際呼叫點 - Mermaid 圖以
npx -p @mermaid-js/mermaid-cli mmdc可成功轉檔 - 「待確認」項目已列出,沒有憑空出現的元件
P2|微服務拆分方案比較
你是架構顧問。請根據 docs/architecture/current-state.md 與 src/ 下的模組相依,提出三種將單體拆分為服務的方案。
每個方案需包含:拆分邊界、資料庫歸屬、跨服務一致性做法(例如 Saga、Outbox)、預估團隊分工、主要風險。
以表格比較三方案,並給出建議方案與理由。
限制:只產出文件,不修改程式碼;每個邊界需引用至少一個實際套件或資料夾路徑。
產出:docs/architecture/decomposition-options.md。預期產出:三方案比較表與建議,每個邊界有實際路徑對應。
🧑⚖️ 驗證要點:
- 每個建議邊界引用的路徑實際存在(
Test-Path或ls逐一確認) - 檢查跨邊界的資料表是否被兩個方案同時宣稱擁有
- 建議方案的理由能對應到比較表中的具體欄位,而非泛泛而談
- 至少一位熟悉該系統的資深工程師簽核
P3|Bounded Context 重新劃分
你是 DDD 實務專家。請分析 src/ 的領域模型(Entity、Aggregate、Service 命名與相依),提出 Bounded Context 劃分。
產出:
1. Context 清單,每個 Context 的職責、核心 Aggregate、對應程式路徑。
2. Context Map(Mermaid flowchart),標示上下游與整合模式(ACL、Shared Kernel、Published Language)。
3. 目前違反邊界的相依清單(檔案:行號)。
限制:不修改程式碼。預期產出:Context 清單、Context Map 與違反邊界清單。
🧑⚖️ 驗證要點:
- 違反邊界清單中的「檔案:行號」逐一開啟確認確實存在跨 Context 引用
- 同一個 Aggregate 沒有出現在兩個 Context
- 以
rg "^import .*<context套件>" src抽查相依方向與 Context Map 一致
P4|單點故障盤查
你是 SRE。請檢視 infra/、deploy/ 與應用程式設定檔,找出系統的單點故障(SPOF)。
每一項需列出:元件、為何是單點、故障影響範圍、建議改善、改善成本等級(低、中、高)。
限制:只讀取設定與程式碼,不連線任何環境;不確定部署副本數時標示「需以實際環境確認」。
產出:Markdown 表格。預期產出:SPOF 清單表格,含影響與改善建議。
🧑⚖️ 驗證要點:
- 每項 SPOF 的依據能在設定檔中找到(例如
replicas: 1) - 「需以實際環境確認」項目由維運人員以
kubectl get deploy -A等方式實際確認 - 沒有遺漏資料庫、訊息佇列、身分驗證服務等常見關鍵元件
P5|事件驅動與同步呼叫取捨分析
你是架構師。針對 <模組名稱> 與 <下游模組> 之間的整合,比較「同步 API 呼叫」與「事件驅動」兩種做法。
請涵蓋:延遲、一致性、錯誤處理、重試與冪等、可觀測性、團隊技能需求。
附上兩種做法的 Mermaid sequenceDiagram。
最後給出建議,並列出採用建議方案前必須驗證的三個假設。預期產出:比較表、兩張時序圖、建議與待驗證假設。
🧑⚖️ 驗證要點:
- 時序圖中的參與者名稱與程式碼中的實際元件一致
- 「待驗證假設」具體可測(例如「下游可接受 5 秒最終一致」),而非空泛敘述
- 冪等性討論有指出目前程式碼是否已有冪等鍵
P6|API Gateway 導入評估
你是平台工程師。請盤點本系統所有對外 API 端點(路由定義檔與 Controller),評估導入 API Gateway 的必要性。
產出:
1. 端點清單(方法、路徑、驗證方式、是否對外)。
2. 目前分散在各服務的橫切關注點(驗證、限流、記錄)。
3. 導入與不導入的比較,以及建議的最小可行設計。
限制:不修改程式碼;端點清單需可由程式碼重建。預期產出:端點清單、橫切關注點分析、導入建議。
🧑⚖️ 驗證要點:
- 用
rg "@(Get|Post|Put|Delete)Mapping" src或對應框架語法統計端點數,與清單筆數相符 - 「是否對外」欄位由負責人與實際網路設定比對
- 最小可行設計沒有引入超出需求的元件
P7|架構決策紀錄(ADR)草擬
你是架構師。請為「<決策主題>」撰寫一份 ADR,採用 Context、Decision、Status、Consequences、Alternatives 結構。
輸入:docs/architecture/ 下的相關文件與本次討論摘要(見下方)。
<貼上討論摘要>
要求:每個替代方案都要寫出被否決的具體理由;Consequences 需同時列出正面與負面影響。
產出:docs/adr/NNNN-<主題>.md,編號接續現有最大號。預期產出:一份編號正確、結構完整的 ADR。
🧑⚖️ 驗證要點:
- 檔名編號為現有最大號加一(
ls docs/adr確認) - 內容與討論摘要一致,沒有新增未討論過的決策
- 負面影響至少一項,且非流於形式
P8|多資料中心部署策略
你是基礎架構架構師。請依本系統的 RTO <目標值> 與 RPO <目標值>,提出兩種多資料中心部署策略(例如 Active-Active、Active-Standby)。
每種策略需包含:資料複寫方式、切換流程、預期 RTO 與 RPO、成本等級、演練方式。
以 Mermaid flowchart 繪製部署拓撲。
限制:所有數字須標示為估算,並說明估算依據。預期產出:兩種策略比較、拓撲圖與演練建議。
🧑⚖️ 驗證要點:
- 預估 RTO 與 RPO 有明確推導依據(例如複寫延遲、切換步驟耗時)
- 切換流程每一步都有負責角色
- 由 DBA 確認資料複寫方式為所用資料庫實際支援的功能
P9|架構變更影響通知清單
你是技術專案經理。針對以下架構變更:<變更摘要>,請:
1. 搜尋 Repo 中所有受影響的設定、文件、介面定義與測試。
2. 列出需要同步更新的文件與負責團隊(依 CODEOWNERS)。
3. 產出一封給相關團隊的變更通知草稿,含時程、影響、因應方式與聯絡窗口。
限制:只產出文件,不修改任何既有檔案。預期產出:影響清單、負責團隊對照與通知草稿。
🧑⚖️ 驗證要點:
- 負責團隊與
CODEOWNERS實際內容一致 - 以
rg "<變更關鍵字>"自行搜尋,確認影響清單無重大遺漏 - 通知草稿未包含內部機敏資訊
36.3 Coding
Coding 類 Prompt 的核心是「範圍」與「測試證據」。建議每則 Prompt 獨立一個 Worktree,必要時分派 2 至 3 個 Agent 同題競賽。
P10|依契約實作查詢 API
你是後端工程師。請在 src/modules/customer/ 實作客戶查詢 API,需完全符合 docs/api-schema.md 中 GET /customers/{id} 的契約。
範圍:只能修改 src/modules/customer/ 與 test/modules/customer/。
要求:包含輸入驗證、找不到資料回 404、無權限回 403;補上單元測試與一支整合測試。
證據:執行 <測試指令> 並貼上結果;附上一次實際呼叫的 request 與 response 範例。預期產出:API 實作、測試檔與執行證據。
🧑⚖️ 驗證要點:
-
git diff --stat僅限兩個允許目錄 - 自行重跑測試指令並通過
- 逐欄比對 response 與
docs/api-schema.md的欄位名稱、型別與必填性 - 404 與 403 兩個情境都有對應測試
P11|純函式化與副作用移除
請將 <檔案路徑> 中的 <函式名稱> 重構為純函式:輸入相同時輸出必定相同、不讀寫全域狀態、不做 I/O。
原本的副作用(記錄、快取寫入、時間取得)請移到呼叫端,或以參數注入。
範圍:該檔案與其直接呼叫端。
證據:重構前後執行相同測試皆通過;新增至少 2 個針對純函式的測試。預期產出:重構後函式、呼叫端調整與新增測試。
🧑⚖️ 驗證要點:
- 函式內不再出現全域變數、
Date.now()、檔案或網路存取 - 所有呼叫端都已調整(
rg "<函式名稱>\("確認) - 重構前後測試結果一致
P12|TypeScript 型別補強
你是前端工程師。請為 <元件路徑> 補上完整 TypeScript 型別:Props、Emits、內部狀態與 API 回應型別。
限制:不得使用 any;不得改變元件對外行為。
證據:執行 npx tsc --noEmit 與既有元件測試,皆需通過。預期產出:型別完整的元件與型別定義檔。
🧑⚖️ 驗證要點:
-
rg ": any|as any" <元件路徑>無結果 -
npx tsc --noEmit自行重跑通過 - 以 Orca 內建瀏覽器開啟頁面,確認元件行為未改變
P13|分頁與排序查詢
請為 <資源名稱> 列表 API 實作分頁與排序:預設每頁 20 筆、上限 100 筆;排序欄位僅允許白名單 <欄位清單>。
要求:回應包含 total、page、pageSize;非法排序欄位回 400;SQL 必須使用參數化查詢。
範圍:<模組路徑>。
證據:測試涵蓋第一頁、最後一頁、超出範圍頁、非法排序欄位四種情境,並貼上執行結果。預期產出:分頁排序實作與四種情境測試。
🧑⚖️ 驗證要點:
- 排序欄位白名單確實生效,無字串拼接 SQL
- pageSize 上限 100 有測試
- 以實際資料呼叫一次,確認 total 與資料庫筆數一致
P14|遵循既有風格新增模組
請參考 <既有相似模組路徑> 的結構與命名,新增 <新模組名稱> 模組,負責 <職責描述>。
限制:遵守 .eslintrc 與 .editorconfig;不得新增任何 package 相依;檔案結構需與參考模組一致。
證據:執行 lint 與測試指令並貼上結果;列出新模組與參考模組的檔案對照表。預期產出:新模組程式、測試與檔案對照表。
🧑⚖️ 驗證要點:
-
git diff -- package.json無變更 - Lint 無新增警告
- 對照表中的結構與實際檔案一致
P15|重複邏輯抽取
請找出 <目錄> 中重複出現 3 次以上、超過 5 行的相似邏輯,列出位置清單後再抽取為共用函式。
步驟:先只輸出清單與抽取計畫,等我回覆「同意」後再修改。
證據:抽取後所有既有測試通過;為共用函式新增測試。預期產出:先交付重複清單與計畫,經同意後交付重構。
🧑⚖️ 驗證要點:
- Agent 有確實停在計畫階段等待同意(可在終端機或 Native Chat 紀錄確認)
- 清單中每處重複確實相似,非誤判
- 抽取後
git diff中舊位置皆改為呼叫共用函式
P16|前後端一致的表單驗證
請閱讀後端 <DTO 或 Schema 路徑> 的驗證規則,在前端 <表單元件路徑> 實作對應的即時驗證。
要求:產出一張規則對照表(欄位、後端規則、前端規則);錯誤訊息使用 i18n 檔案中既有的鍵。
範圍:只修改前端表單與其測試。預期產出:前端驗證實作與規則對照表。
🧑⚖️ 驗證要點:
- 對照表逐列回到後端原始碼核對
- 在 Orca 內建瀏覽器實際輸入非法值,確認錯誤訊息出現
- 未新增 i18n 鍵以外的硬編碼字串
P17|例外處理補強
請為 <API 端點或服務方法> 補上例外處理,涵蓋:下游逾時、無權限、資料不存在、輸入格式錯誤四種情境。
要求:使用專案既有的例外類別與錯誤回應格式;錯誤記錄不得包含個資或 Token。
證據:每種情境一個測試並貼上執行結果。預期產出:例外處理程式碼與四個情境測試。
🧑⚖️ 驗證要點:
- 沒有空的 catch 或吞掉例外的寫法(
rg "catch \(.*\) \{\s*\}"抽查) - 錯誤記錄中無個資欄位
- HTTP 狀態碼與既有慣例一致
P18|同步改非同步
請將 <檔案路徑> 中的 <方法名稱> 由同步阻塞呼叫改為非同步實作(<語言對應機制,例如 CompletableFuture 或 async/await>)。
要求:列出所有呼叫端與需要的調整;說明錯誤傳遞與逾時處理方式。
證據:既有測試通過,並新增一個驗證逾時行為的測試。預期產出:非同步實作、呼叫端調整與逾時測試。
🧑⚖️ 驗證要點:
- 所有呼叫端都已處理非同步結果,無遺漏的 await 或 join
- 逾時測試確實會在逾時時失敗(可暫時改小逾時值驗證)
- 沒有在非同步流程中呼叫阻塞 API
36.4 Migration
Migration 類任務量大、跨檔多,建議先讓 Agent 只產出「清單與計畫」,人工確認後再分批分派到多個 Worktree。
P19|Java 已棄用 API 盤點
你是 Java 升級專家。目標:將本專案由 Java 8 升級至 Java <目標版本>。
第一步只盤點,不修改:
1. 執行 jdeps --jdk-internals 與編譯警告分析,列出使用已移除或已棄用 API 的位置(檔案:行號)。
2. 依「必須修改、建議修改、可延後」分級。
3. 附上每類問題的建議替代 API。
產出:docs/migration/java-deprecated-inventory.md,並附上實際執行的指令。預期產出:分級的棄用 API 清單與替代建議。
🧑⚖️ 驗證要點:
- 自行執行
jdeps --jdk-internals <jar>,結果與清單一致 - 抽查 5 筆「檔案:行號」確實存在
- 替代 API 確認存在於目標 JDK 版本的官方文件
P20|Spring Boot 設定屬性遷移
請將 src/main/resources/ 下所有 application*.yml 與 application*.properties,由 Spring Boot <來源版本> 遷移至 <目標版本> 的屬性名稱。
要求:產出對照表(舊屬性、新屬性、是否行為改變、出處);無法確定者標示「需人工確認」。
建議先加入 spring-boot-properties-migrator 輔助判斷,但完成後須移除。
證據:應用程式在目標版本可啟動,貼上啟動日誌中無屬性棄用警告的片段。預期產出:更新後的設定檔與屬性對照表。
🧑⚖️ 驗證要點:
- 對照表每一項可在 Spring Boot 官方遷移指南找到
-
git diff -- pom.xml build.gradle確認 properties-migrator 已移除 - 自行啟動應用程式並檢查日誌
P21|javax 改 jakarta 命名空間
請將專案中所有 javax.* 中屬於 Jakarta EE 的套件(例如 javax.servlet、javax.persistence、javax.validation)替換為 jakarta.*。
注意:javax.crypto、javax.net 等屬 JDK 的套件不可替換。
產出:替換清單,以及需要人工確認的邊界案例(反射字串、XML 設定、第三方套件相容性)。
證據:完整編譯與測試通過。預期產出:命名空間替換與邊界案例清單。
🧑⚖️ 驗證要點:
-
rg "javax\.(servlet|persistence|validation|annotation)" src無殘留 -
rg "jakarta\.(crypto|net)" src無誤改 - XML 與字串常數中的類別名稱也已處理
P22|Vue 2 Options API 改 Composition API
請將 <元件路徑> 由 Vue 2 Options API 改寫為 Vue 3 Composition API(script setup 語法)。
要求:保持 Props、Emits 與對外行為不變;mixins 改為 composables。
證據:既有元件測試通過;在 Orca 內建瀏覽器實際操作主要流程並截圖說明。預期產出:改寫後元件與對應 composables。
🧑⚖️ 驗證要點:
- 元件 Props 與 Emits 名稱、型別與改寫前一致
- 自行在內建瀏覽器操作主要流程
- 沒有殘留
this.存取
P23|Oracle SQL 改 PostgreSQL
請將 <SQL 或 Mapper 路徑> 中的 Oracle 專屬語法改寫為 PostgreSQL 相容語法(例如 NVL、ROWNUM、DECODE、序列、日期函式、外連接 (+) 語法)。
要求:每一處改寫都列出原語法、新語法、行為差異(NULL 處理、排序、精度)。
證據:在測試資料庫上執行改寫前後查詢,比對結果筆數與關鍵欄位。預期產出:改寫後 SQL 與差異對照表。
🧑⚖️ 驗證要點:
- 對照表中的行為差異經 DBA 確認
- 自行在測試資料庫比對前後結果
- 空字串與 NULL 的差異已被明確處理
P24|VM 部署遷移至 Kubernetes
請盤點本服務在 VM 上的部署方式(啟動腳本、環境變數、設定檔、排程、日誌位置),產出遷移至 Kubernetes 所需的調整清單與 manifest 草稿。
要求:機敏設定改用 Secret 引用,不得寫入明文;健康檢查、資源限制、優雅關閉需明確定義。
限制:只產出 deploy/k8s/ 下的草稿檔案與文件,不連線任何叢集。預期產出:調整清單與 Kubernetes manifest 草稿。
🧑⚖️ 驗證要點:
-
kubectl apply --dry-run=client -f deploy/k8s/通過 - manifest 中無明文密碼(
gitleaks detect --no-git -s deploy/k8s或人工檢查) - 啟動腳本中的每個環境變數都有對應
P25|Hibernate 版本遷移
請將 <Entity 路徑> 的 Hibernate 對應設定由 <來源版本> 遷移至 <目標版本>。
要求:列出 Lazy Loading、ID 產生策略、型別對應等可能改變行為之處;產生 SQL 差異比對方法。
證據:開啟 SQL 記錄,比對核心查詢在遷移前後產生的 SQL。預期產出:遷移後 Entity 設定與行為差異說明。
🧑⚖️ 驗證要點:
- 核心查詢的 SQL 前後差異已逐一檢視
- 沒有新增 N+1 查詢
- ID 產生策略變更經 DBA 確認不會撞號
P26|單體至微服務分階段路徑
請根據 docs/architecture/decomposition-options.md 的建議方案,規劃分階段遷移路徑(Strangler Fig 模式)。
每個階段需包含:範圍、前置條件、可獨立驗收的標準、回滾方式、預估工作量。
以 Mermaid gitGraph 或 flowchart 呈現階段順序。預期產出:分階段計畫與流程圖。
🧑⚖️ 驗證要點:
- 每個階段的驗收標準可量測
- 每個階段都有回滾方式
- 階段間相依順序合理,無循環
P27|.NET Framework 遷移至現代 .NET
請分析 <方案或專案路徑>,評估由 .NET Framework 遷移至 .NET <目標版本> 的可行性。
產出:
1. 無法直接相容的 NuGet 套件與 API(例如 System.Web、WCF 伺服端、AppDomain)。
2. 每項的替代方案。
3. 建議的遷移順序。
可使用 upgrade-assistant 或 API 分析工具,並附上實際執行的指令。預期產出:相容性分析報告與遷移順序。
🧑⚖️ 驗證要點:
- 自行重跑分析工具,結果一致
- 替代方案在目標 .NET 版本確實可用
- 遷移順序從相依最少的專案開始
36.5 Review
Review 類 Prompt 讓 Agent 擔任第一層審查者,但不能取代人工審查。建議搭配 Annotate AI Diff,把 Agent 的審查意見轉為可追蹤的逐行註記。
P28|OWASP Top 10 Diff 審查
你是應用安全審查者。請審查目前 Worktree 相對於 <start-from ref> 的 Diff(git diff <ref>...HEAD),以 OWASP Top 10 為基準。
每個發現需包含:類別、檔案:行號、風險說明、利用情境、修正建議、嚴重度。
沒有發現的類別也要列出「已檢查,未發現」。
限制:只審查,不修改。預期產出:依 OWASP 類別整理的審查表。
🧑⚖️ 驗證要點:
- 每個發現的「檔案:行號」都在本次 Diff 範圍內
- 高嚴重度發現由人工重現或確認
- 十個類別都有結論,無遺漏
P29|團隊錯誤處理慣例審查
請閱讀 docs/conventions/error-handling.md,審查本次 Diff 是否符合慣例。
輸出:不一致之處(檔案:行號、違反哪一條、建議寫法)。
若慣例文件本身有矛盾或不足,另列一節說明。預期產出:不一致清單與慣例改善建議。
🧑⚖️ 驗證要點:
- 每項違反都能對應到慣例文件中的具體條文
- 抽查建議寫法確實符合慣例
- 慣例改善建議交由慣例維護者決定,不直接採用
P30|API 向後相容性檢查
請比較本次 Diff 對公開 API 的影響:REST 路由、Request 與 Response 欄位、錯誤碼、事件 Schema、公開類別與方法簽章。
分類為:破壞性變更、非破壞性新增、行為改變。
破壞性變更需提出相容做法(例如版本化、欄位保留)。預期產出:相容性分類表與相容做法。
🧑⚖️ 驗證要點:
- 若有 OpenAPI 檔,以 diff 工具比對前後版本,結果與報告一致
- 「行為改變」項目有測試佐證
- 破壞性變更經 API 消費方確認
P31|SQL 效能審查
請審查本次 Diff 中新增或修改的 SQL 與 ORM 查詢,找出可能的效能問題:缺少索引、N+1、全表掃描、不必要的 SELECT *、大量 IN 條件。
每項附上:查詢位置、問題、建議修正、建議驗證方式(例如 EXPLAIN)。預期產出:查詢效能問題清單。
🧑⚖️ 驗證要點:
- 對高風險查詢在測試資料庫執行
EXPLAIN或EXPLAIN ANALYZE確認 - N+1 指控以開啟 SQL 記錄後的實際查詢次數驗證
- 索引建議與既有索引不重複
P32|吞例外審查
請找出本次 Diff 與 <目錄> 中可能吞掉例外或遺失錯誤資訊的寫法:空 catch、只記錄不拋出、捕捉過廣的例外型別、丟失原始 cause。
每項說明影響並提出修正。預期產出:問題清單與修正建議。
🧑⚖️ 驗證要點:
- 以
rg "catch \((Exception|Throwable)" <目錄>自行搜尋,與清單比對 - 修正建議保留原始 cause
- 確認沒有把刻意忽略的例外誤判(需看程式註解或上下文)
P33|測試覆蓋缺口分析
請比對本次 Diff 的產品程式碼與測試程式碼,找出未被測試涵蓋的分支與邊界案例。
如專案已有覆蓋率工具,請執行並附上本次變更檔案的覆蓋率數字。
產出:缺口清單(方法、未涵蓋情境、建議測試名稱)。預期產出:覆蓋率數字與測試缺口清單。
🧑⚖️ 驗證要點:
- 自行重跑覆蓋率工具,數字一致
- 缺口清單中的情境確實未被任何測試涵蓋
- 建議測試名稱符合團隊命名慣例
P34|Commit 訊息品質審查
請執行 git log <start-from ref>..HEAD --format="%h %s%n%b",審查每個 commit 訊息是否:說明變更動機、符合 <Conventional Commits 或團隊格式>、未包含機敏資訊、單一 commit 單一目的。
產出建議的改寫訊息,但不要自行改寫歷史。預期產出:逐 commit 審查結果與建議訊息。
🧑⚖️ 驗證要點:
- Agent 未執行
git rebase或git commit --amend(git reflog確認) - 建議訊息符合團隊格式
- 若需修改歷史,由人工決定並在 Orca 的 Source Control 操作
P35|硬編碼設定與機敏值掃描
請掃描 <目錄> 中硬編碼的設定值與疑似機敏資訊:密碼、Token、連線字串、內部 IP、API 端點。
可執行 gitleaks 或同類工具並附指令;結果中的機敏值一律以前 4 碼加星號遮罩,不得完整輸出。
產出:發現清單與建議改為環境變數或 Secret 管理的方式。預期產出:遮罩後的發現清單與改善建議。
🧑⚖️ 驗證要點:
- Agent 回覆中沒有出現完整機敏值
- 自行執行
gitleaks detect比對結果 - 真實外洩的金鑰立即依第二十八章流程輪替
P36|比較多個 Agent 的同題實作
你是技術主審。以下三個 Worktree 由不同 Agent 實作同一需求:<worktree A>、<worktree B>、<worktree C>。
請分別執行 git -C <路徑> diff --stat <start-from ref> 與測試指令,從正確性、範圍控制、可讀性、測試完整度、風險五個面向評分(1 至 5),並建議勝出方案以及值得從其他方案移植的片段。
限制:只讀取,不修改任何 Worktree。預期產出:評分表、勝出建議與移植建議。
🧑⚖️ 驗證要點:
- 評分依據引用具體檔案或測試結果
- 自行在三個 Worktree 重跑測試
- 移植片段經人工確認不會引入衝突(可在勝出 Worktree 試
git cherry-pick --no-commit)
36.6 Testing
測試類 Prompt 最常見的失敗是 Agent「為了讓測試通過而修改產品程式碼」或「寫出永遠會通過的測試」。驗證時務必確認範圍,並以變異方式檢查測試是否真的有效。
P37|服務層單元測試補齊
你是測試工程師。請為 <類別路徑> 的公開方法補齊單元測試。
範圍:只能新增或修改測試目錄下的檔案,不得修改產品程式碼。
涵蓋:正常路徑、邊界值、至少 3 種例外情境;外部相依以 Mock 或 Fake 取代。
證據:貼上測試執行結果;附一張「方法對應情境」表。預期產出:測試檔與對應表。
🧑⚖️ 驗證要點:
-
git diff --stat只有測試目錄 - 暫時把產品程式碼的一個條件反轉,確認至少一個測試失敗(手動變異測試)
- 測試名稱可讀,能說明情境
P38|含交易回滾的整合測試
請為 <API 端點> 撰寫整合測試,使用測試容器或內嵌資料庫,驗證:成功寫入、驗證失敗不寫入、下游失敗時交易回滾。
要求:每個測試獨立,不依賴執行順序;測試資料於測試內建立與清理。
證據:連續執行兩次測試皆通過,貼上結果。預期產出:整合測試與測試資料設定。
🧑⚖️ 驗證要點:
- 回滾測試確實查詢資料庫確認無殘留資料
- 以隨機順序執行測試仍通過
- 不需要連線任何共用環境
P39|前端元件互動測試
請為 <元件路徑> 撰寫元件測試(使用專案既有的測試框架),涵蓋:初始渲染、使用者輸入、非同步載入中、載入成功、載入失敗五種狀態。
API 呼叫以 Mock 取代;使用以角色或標籤查詢元素的方式,不依賴 CSS class。預期產出:元件測試檔。
🧑⚖️ 驗證要點:
- 五種狀態皆有獨立測試
- 沒有使用固定時間的等待(例如 sleep)
- 自行執行測試並通過
P40|批次作業測試資料設計
請為 <批次作業名稱> 設計測試資料集,涵蓋:正常資料、邊界值(最大長度、零、負數、跨日、閏年)、格式錯誤、重複資料、空檔案。
產出:測試資料檔(去識別化)與一張「資料列對應測試目的」的說明表。
限制:不得使用任何真實客戶資料。預期產出:測試資料檔與說明表。
🧑⚖️ 驗證要點:
- 資料中無真實姓名、身分證號、帳號等個資
- 每類邊界至少一筆
- 以批次作業實際執行一次,確認錯誤資料被正確拒絕
P41|第三方支付串接 Mock 測試
請為 <支付串接模組> 撰寫測試,以 Mock Server 模擬第三方支付回應:成功、失敗、逾時、重複通知、簽章錯誤。
要求:簽章驗證邏輯必須被測試涵蓋;不得連線真實支付服務。預期產出:支付串接測試與 Mock 設定。
🧑⚖️ 驗證要點:
- 測試設定中無真實商店代號或金鑰
- 簽章錯誤情境確實被拒絕
- 重複通知情境驗證冪等
P42|測試失敗根因分析
請執行完整測試套件 <測試指令>,對所有失敗案例進行根因分析。
每個失敗需列出:測試名稱、錯誤訊息摘要、根因(產品程式錯誤、測試錯誤、環境問題、不穩定測試)、建議修正。
限制:先只分析,不修改任何檔案。預期產出:失敗案例根因表。
🧑⚖️ 驗證要點:
- 失敗案例數與自行執行結果一致
- 被判定為「不穩定測試」者,以重跑多次驗證
- 根因說明能指到具體程式碼位置
P43|併發與競態測試
請為 <併發處理邏輯路徑> 撰寫併發測試,以多執行緒或多請求同時操作同一資源,驗證不會發生重複扣款、超賣或資料覆寫。
要求:測試需可重複執行並穩定重現問題(若存在);說明測試的併發數與重複次數設定理由。預期產出:併發測試與設定說明。
🧑⚖️ 驗證要點:
- 暫時移除鎖或交易,確認測試會失敗
- 連續執行 10 次結果穩定
- 測試執行時間在可接受範圍
P44|前後端契約測試
請為 <API 名稱> 建立契約測試(例如 Pact 或以 OpenAPI 驗證回應),確保前端假設的欄位與後端實際回應一致。
產出:消費端契約、提供端驗證測試,以及在 CI 中執行的建議設定。預期產出:契約檔與雙端測試。
🧑⚖️ 驗證要點:
- 故意刪除後端一個欄位,提供端驗證會失敗
- 契約檔中的範例資料已去識別化
- CI 設定建議與既有 Pipeline 相容
P45|資料庫 Migration 回滾測試
請為 <migration 檔案> 撰寫測試:在空資料庫依序執行 up、down、再 up,並驗證結構與資料一致。
若 migration 不可逆,請明確指出並提出補償方案。
證據:貼上三步驟的執行結果。預期產出:Migration 回滾測試與可逆性結論。
🧑⚖️ 驗證要點:
- 自行在本機測試資料庫執行三步驟
- down 之後結構確實回到原狀(比對 schema dump)
- 不可逆 migration 已在 PR 描述中明確標示
36.7 Documentation
文件類產出最容易「流暢但錯誤」。驗證重點是:每個技術陳述可回溯至程式碼或官方來源,且指令可實際執行。
P46|OpenAPI 規格產出
請依 <Controller 或路由路徑> 的實際程式碼,產出 OpenAPI 3 規格檔。
要求:包含所有端點、參數、Request 與 Response Schema、錯誤碼;範例值使用假資料。
證據:以 OpenAPI 驗證工具檢查規格有效,貼上指令與結果。預期產出:openapi.yaml 與驗證結果。
🧑⚖️ 驗證要點:
- 自行執行
npx @redocly/cli lint openapi.yaml或同類工具 - 端點數與程式碼一致
- 抽查 3 個 Response Schema 與實際回應一致
P47|模組 ADR 與選型說明
請為 <模組名稱> 撰寫架構決策紀錄,說明目前採用 <技術選型> 的理由、考慮過的替代方案、取捨與後續觀察指標。
輸入:模組程式碼、git log -- <模組路徑> 的提交歷史、相關 Issue。
限制:無法從輸入找到依據的理由,標示「推測」。預期產出:ADR 文件。
🧑⚖️ 驗證要點:
- 標示「推測」的段落由原作者或維護者確認
- 引用的提交與 Issue 確實存在
- 觀察指標可量測
P48|技術文件繁體中文在地化
請將 <文件路徑> 翻譯為繁體中文(台灣用語),產出 <目標路徑>。
規則:程式碼區塊、指令、檔案路徑、產品名稱與功能名稱(例如 Worktree、Design Mode)保留英文;標題層級與連結保持不變;術語依 docs/glossary.md。
證據:列出所有使用到的術語對照。預期產出:繁中文件與術語對照表。
🧑⚖️ 驗證要點:
- 程式碼區塊與原文逐字相同(以 diff 工具比對程式碼區塊)
- 連結數量與原文一致
- 無中國大陸用語(例如「軟件」「默認」「信息」)
P49|新人 Onboarding 指南
請為本專案撰寫新人 Onboarding 指南,內容包含:環境需求、取得程式碼、在 Orca 加入 Repository、.worktreeinclude 與 orca.yaml 的用途、建立第一個 Worktree、執行測試、常見問題。
要求:每個步驟附可執行指令與預期結果;指令需實際在乾淨 Worktree 中執行過。
產出:docs/onboarding.md。預期產出:可依步驟操作的 Onboarding 文件。
🧑⚖️ 驗證要點:
- 找一位未接觸過專案的成員依文件操作,記錄卡關處
- 文件中的每個指令都能執行
- 提及的 Orca 設定路徑與目前版本 UI 一致
P50|框架升級遷移手冊
請根據本 Worktree 中已完成的升級變更(git diff <start-from ref>...HEAD),撰寫給其他團隊參考的遷移手冊。
結構:適用範圍、前置條件、逐步操作、常見錯誤與解法、回滾方式、驗證清單。
要求:每個步驟引用本次變更的實際檔案作為範例。預期產出:遷移手冊。
🧑⚖️ 驗證要點:
- 手冊步驟與實際 Diff 一致,無遺漏
- 另一團隊試用一個步驟並回饋
- 回滾方式經過實際演練
P51|程式內說明精簡補強
請檢視 <檔案路徑>,只在邏輯不直觀的地方補上簡短說明(例如業務規則來源、特殊邊界處理原因),不要逐行註解,也不要描述程式碼字面上已表達的內容。
同時移除過時或與程式不符的既有註解,並列出移除清單與理由。預期產出:精簡後的程式內說明與移除清單。
🧑⚖️ 驗證要點:
-
git diff只有註解變動,無邏輯變更 - 新增說明都在真正不直觀之處
- 被移除的註解確實過時
P52|Legacy 盤點結構化報告
請彙整以下 Worktree 的盤點產出:<路徑清單>,產出一份結構化現況報告。
結構:系統概觀、模組清單、資料流、外部介接、技術債、風險分級、建議下一步。
要求:每項發現標註來源檔案;不同盤點結果互相矛盾時,列入「待釐清」章節而非自行選擇。預期產出:整合後的現況報告。
🧑⚖️ 驗證要點:
- 「待釐清」章節存在且有內容(多數盤點都會有矛盾)
- 抽查 5 項發現回到來源檔案
- 風險分級標準明確
P53|服務 Runbook 撰寫
請為 <服務名稱> 撰寫 Runbook,包含:服務概觀、相依服務、健康檢查方式、常見告警與處理步驟、重啟流程、回滾流程、聯絡窗口。
要求:處理步驟以可執行指令表達;需要權限的操作標註所需角色。
限制:不得寫入任何密碼或 Token。預期產出:Runbook 文件。
🧑⚖️ 驗證要點:
- 由值班工程師在測試環境依步驟演練一次
- 文件中無機敏值
- 健康檢查指令實際可用
P54|README 環境變數更新
請比對 git diff <start-from ref>...HEAD 中新增或修改的環境變數與設定項目,更新 README 的設定章節。
每個變數列出:名稱、用途、是否必填、預設值、範例(假資料)。
同時確認 .env.example 已同步更新。預期產出:更新後的 README 與 .env.example。
🧑⚖️ 驗證要點:
- 以
rg "process\.env\.|getenv\(" src比對變數清單 -
.env.example中無真實值 - 若專案使用
.worktreeinclude複製.env,說明中已提醒新 Worktree 的設定方式
36.8 Refactor
重構的定義是「不改變外部行為」。因此所有 Refactor 類 Prompt 的驗證核心都是:重構前後測試結果一致,且 Diff 中沒有夾帶功能變更。
P55|過長函式拆解
請將 <檔案路徑> 中的 <函式名稱>(目前約 <行數> 行)拆解為多個職責單一的小函式。
規則:不改變外部行為與公開簽章;每個新函式名稱需能說明意圖;不得在同一次變更中修正 bug(若發現 bug,另列清單)。
證據:重構前先執行測試並記錄結果,重構後再執行一次,兩者需一致。預期產出:拆解後程式碼、發現的 bug 清單(如有)與前後測試結果。
🧑⚖️ 驗證要點:
- 前後測試結果一致(自行重跑)
- Diff 中沒有夾帶邏輯修正
- 新函式的命名能被非作者理解
P56|條件判斷改策略模式
請將 <檔案路徑> 中依 <類型欄位> 分支的大型 switch 或 if-else,重構為策略模式。
要求:新增類型時只需新增一個策略類別;保留原本的預設行為;附上重構前後的類別結構 Mermaid classDiagram。
證據:所有分支都有測試,且重構前後一致。預期產出:策略介面與實作、類別圖、測試。
🧑⚖️ 驗證要點:
- 原本每個分支都有對應策略
- 預設行為測試存在
- classDiagram 可渲染且與程式碼一致
P57|消除全域狀態依賴
請找出 <模組路徑> 中直接讀寫全域狀態(全域變數、Singleton 可變狀態、靜態欄位)的位置,改為透過參數或依賴注入傳遞。
先輸出位置清單與修改計畫,經我回覆「同意」後再修改。預期產出:位置清單與計畫,同意後交付重構。
🧑⚖️ 驗證要點:
- Agent 確實等待同意後才修改
- 修改後以
rg確認清單中的全域存取已消失 - 測試可在不重設全域狀態的情況下獨立執行
P58|命名一致化
請依 docs/conventions/naming.md,找出 <目錄> 中不符合命名慣例或語意不清的變數、函式、類別名稱,提出改名清單(舊名、新名、理由)。
經我確認清單後,使用 IDE 等級的重新命名(含所有引用)完成修改。
限制:公開 API 名稱不得變更。預期產出:改名清單與確認後的重新命名。
🧑⚖️ 驗證要點:
- 公開 API 未被改名
- 編譯與測試通過
- 字串中的反射引用(例如設定檔中的類別名稱)也已同步
P59|大型前端元件拆分
請將 <元件路徑>(約 <行數> 行)拆分為多個可重用子元件。
要求:先輸出拆分計畫(子元件名稱、職責、Props 與 Emits);拆分後父元件對外行為不變;每個子元件有基本測試。
證據:在 Orca 內建瀏覽器操作主要流程,確認畫面與行為一致。預期產出:拆分計畫、子元件與測試。
🧑⚖️ 驗證要點:
- 子元件之間沒有循環相依
- 以 Design Mode 點選畫面元素,確認對應到新的子元件檔案
- 父元件 Props 介面不變
P60|死碼與未使用相依移除
請找出 <專案路徑> 中未被引用的程式碼與未使用的套件相依。
可使用 <語言對應工具,例如 knip、depcheck、unused-imports 或 IDE 分析>,附上執行指令。
限制:透過反射、設定檔或動態載入使用的程式碼需標示「疑似使用中」,不得刪除。
先輸出清單,經確認後再刪除。預期產出:死碼與未使用相依清單,確認後刪除。
🧑⚖️ 驗證要點:
- 自行重跑分析工具
- 「疑似使用中」項目未被刪除
- 完整建置與測試通過
P61|回呼地獄改 async/await
請將 <檔案路徑> 中巢狀回呼的非同步流程改寫為 async/await。
要求:錯誤處理行為與原本一致(含錯誤傳遞順序);平行執行的部分改用 Promise.all 並說明理由。
證據:既有測試通過,並新增一個錯誤路徑測試。預期產出:改寫後程式碼與錯誤路徑測試。
🧑⚖️ 驗證要點:
- 原本平行的流程沒有被改成串行(比較執行時間)
- 沒有遺漏 await 導致未處理的 Promise
- 錯誤路徑測試確實觸發錯誤
P62|繼承改組合評估
請分析 <類別路徑> 的繼承階層,評估改為組合的利弊。
產出:目前階層 classDiagram、改為組合後的 classDiagram、利弊比較、影響的呼叫端清單、建議是否進行。
限制:只產出分析,不修改程式碼。預期產出:兩張類別圖與評估報告。
🧑⚖️ 驗證要點:
- 目前階層圖與程式碼一致
- 呼叫端清單以
rg搜尋確認完整 - 建議結論與利弊比較一致
P63|錯誤處理統一化
請將 <模組路徑> 的錯誤處理統一改用團隊既有的例外類別體系(見 <例外基底類別路徑>)。
要求:錯誤碼與 HTTP 對應保持不變;不得新增新的例外基底類別;列出每處修改前後對照。
證據:錯誤情境測試全部通過。預期產出:統一後的錯誤處理與對照表。
🧑⚖️ 驗證要點:
- 錯誤回應格式與修改前一致(比對測試快照或實際呼叫)
- 沒有新增例外基底類別
- 錯誤記錄等級未被意外改變
36.9 Performance
效能類 Prompt 的產出必須附「量測方法」與「前後數據」。沒有量測的優化建議只能當作假設。
P64|API 效能瓶頸分析
你是效能工程師。請分析 <API 端點> 的處理流程(Controller 到資料存取),找出可能的效能瓶頸。
步驟:
1. 閱讀程式碼並列出可疑點。
2. 提出量測方法(例如在測試環境以 k6 或 wrk 壓測,或開啟 APM)。
3. 依可疑點提出優化建議與預期效益。
限制:不修改程式碼;所有效益數字標示為預估。預期產出:可疑點清單、量測計畫與優化建議。
🧑⚖️ 驗證要點:
- 量測計畫可直接執行
- 實際量測後再決定是否採用建議
- 預估數字有推導依據
P65|快取策略設計
請為 <高頻查詢名稱> 設計快取策略(例如 Redis)。
內容:快取鍵設計、TTL、失效規則(寫入時失效或延遲雙刪)、快取穿透、擊穿、雪崩的防護、監控指標。
以 Mermaid sequenceDiagram 呈現讀取與寫入流程。預期產出:快取設計文件與時序圖。
🧑⚖️ 驗證要點:
- 寫入路徑的失效處理可避免讀到舊資料,或明確接受短暫不一致
- 快取鍵不包含個資
- 監控指標包含命中率
P66|索引缺口檢查
請收集 <模組路徑> 中所有查詢的 WHERE、JOIN、ORDER BY 欄位,與目前 schema(<schema 檔或 migration 目錄>)的索引比對,列出缺少索引的查詢。
每項附:查詢位置、建議索引、預期效益、寫入成本影響。
限制:只產出建議與 migration 草稿,不執行。預期產出:缺索引清單與 migration 草稿。
🧑⚖️ 驗證要點:
- 在測試資料庫以
EXPLAIN比對建立索引前後的執行計畫 - 建議索引與既有索引不重複
- DBA 確認寫入成本可接受
P67|前端首次載入最佳化
請分析 <前端專案路徑> 的建置輸出與路由,提出首次載入效能改善建議:程式碼分割、延遲載入、圖片最佳化、第三方腳本處理。
請執行建置並附上 bundle 大小分析結果(使用專案可用的分析工具)。
在 Orca 內建瀏覽器以裝置模擬檢視主要頁面,記錄觀察結果。預期產出:bundle 分析結果與改善建議。
🧑⚖️ 驗證要點:
- 自行執行建置確認 bundle 數字
- 建議優先處理最大的區塊
- 改善後重新量測並比較
P68|批次作業耗時分析
請分析 <批次作業名稱> 的執行流程與最近的執行日誌 <日誌路徑(已去識別化)>,找出最耗時的步驟。
產出:步驟耗時表、瓶頸原因推論、改善建議(例如批次大小、平行度、索引)。
限制:推論需標示依據的日誌行。預期產出:耗時分析表與改善建議。
🧑⚖️ 驗證要點:
- 耗時表數字能從日誌時間戳記計算得出
- 推論依據的日誌行確實存在
- 改善建議在測試環境驗證後才套用
P69|記憶體洩漏風險檢查
請檢查 <模組路徑> 是否有記憶體洩漏風險:未釋放的資源、無上限的快取或集合、未移除的事件監聽、長生命週期物件持有短生命週期物件。
每項提出驗證方法(例如 heap dump 比較、長時間壓測)。預期產出:風險清單與驗證方法。
🧑⚖️ 驗證要點:
- 高風險項目以實際 heap dump 或記憶體監測驗證
- 無上限集合確實存在於程式碼中
- 修正建議不會引入新的資源競爭
P70|同步改批次處理效益評估
請評估將 <逐筆同步呼叫流程> 改為批次處理的效益與風險。
內容:吞吐量預估、延遲影響、錯誤處理(部分失敗)、冪等性、實作工作量。
附上簡單的量測腳本,讓我在測試環境比較兩種方式。預期產出:評估報告與量測腳本。
🧑⚖️ 驗證要點:
- 量測腳本可在測試環境執行且不碰正式資料
- 部分失敗的處理方式明確
- 實測數據與預估差距有說明
P71|高併發限流策略
請為 <服務名稱> 設計高併發情境的限流策略:限流位置(Gateway、服務、下游)、演算法(Token Bucket、滑動視窗)、限流維度(使用者、IP、API Key)、超限回應與重試建議。
附上設定範例與壓測驗證方法。預期產出:限流設計與設定範例。
🧑⚖️ 驗證要點:
- 壓測時超過門檻的請求確實回應 429 或約定的錯誤
- 限流維度不會誤傷正常的共用出口 IP 使用者
- 設定範例與實際使用的元件版本相容
P72|平行 Worktree 本機資源評估
請協助評估本機同時執行多個 Orca Worktree 與 Agent 的資源上限。
步驟:
1. 執行 orca worktree ps --json 取得目前 Worktree 與終端機概況。
2. 依作業系統執行記憶體與 CPU 量測指令(Windows 用 Get-Process,macOS 或 Linux 用 ps 或 top),記錄 Orca 與各 Agent 程序的用量。
3. 依量測結果建議同時執行的 Agent 上限、是否啟用 Agent hibernation 與建議的閒置時間。
產出:量測表與建議。預期產出:資源量測表、Agent 上限與 Hibernation 設定建議。
🧑⚖️ 驗證要點:
- 量測表數字可由自己重跑指令重現
- 建議的 Hibernation 設定在 Settings → Experimental → Agent hibernation 可找到並符合 1 分鐘至 24 小時範圍
- 採用建議後一週內觀察是否仍有記憶體壓力(見第三十章)
36.10 Security
安全類 Prompt 的產出必須經資安人員複核。Agent 可以發現問題,但「沒發現問題」不等於安全。
P73|SQL Injection 檢查
你是應用安全工程師。請檢查 <模組路徑> 所有資料庫存取,找出字串拼接 SQL、動態 ORDER BY、原生查詢未參數化等 SQL Injection 風險。
每項提供:位置、可被利用的輸入來源、修正方式(參數化或白名單)。
可執行 semgrep 等靜態分析工具並附指令。預期產出:風險清單與修正建議。
🧑⚖️ 驗證要點:
- 自行執行靜態分析工具比對
- 高風險項目由資安人員在測試環境驗證可利用性
- 修正後以同一工具重掃無殘留
P74|權限提升風險審查
請審查 <API 路徑或 Controller> 的授權邏輯,找出垂直權限提升(一般使用者存取管理功能)與水平權限提升(存取他人資料,IDOR)風險。
每個端點列出:需要的角色、是否檢查資源擁有者、發現的問題。預期產出:端點授權矩陣與問題清單。
🧑⚖️ 驗證要點:
- 以兩個不同使用者帳號在測試環境實際嘗試存取他人資源
- 授權矩陣與規格文件一致
- 每個發現都有對應測試案例建議
P75|日誌機敏資訊外洩檢查
請找出 <專案路徑> 中可能把機敏資訊寫入日誌的位置:密碼、Token、身分證號、卡號、完整 Request 或 Response 內容。
提出遮罩或移除建議,並建議集中化的遮罩機制。
輸出中的範例值一律使用假資料。預期產出:外洩風險清單與遮罩方案。
🧑⚖️ 驗證要點:
- 以
rg -i "log.*(password|token|secret)" <專案路徑>自行搜尋比對 - 遮罩方案以測試驗證確實生效
- Agent 輸出中沒有真實機敏值
P76|檔案上傳安全審查
請審查 <上傳功能路徑>,檢查:副檔名與 MIME 驗證、檔案大小上限、儲存路徑是否可被控制(路徑穿越)、是否可上傳可執行檔、是否掃毒、下載時的 Content-Disposition。
產出:檢查表(項目、現況、風險、建議)。預期產出:檔案上傳安全檢查表。
🧑⚖️ 驗證要點:
- 在測試環境上傳偽裝副檔名的檔案驗證
- 路徑穿越測試(檔名含
../)被拒絕 - 大小上限實際生效
P77|最小權限原則審查
請檢查本次變更涉及的服務帳號、資料庫帳號、雲端 IAM 角色與 Kubernetes RBAC 設定,是否符合最小權限原則。
列出過度授權的項目與建議的最小權限設定。
限制:只審查設定檔,不連線任何環境。預期產出:過度授權清單與建議設定。
🧑⚖️ 驗證要點:
- 建議權限經實際功能測試仍可運作
- 萬用字元權限(例如
*)都已被指出 - 由權限管理者核准後才套用
P78|輸入驗證與清理審查
請檢查 <API 路徑> 所有輸入(Path、Query、Body、Header)是否有適當的驗證與清理:型別、長度、格式、允許值、HTML 與腳本跳脫。
產出:輸入欄位驗證矩陣與缺口清單。預期產出:驗證矩陣與缺口清單。
🧑⚖️ 驗證要點:
- 對缺口欄位在測試環境送出超長或惡意輸入驗證
- 前端驗證不被視為唯一防線
- 矩陣涵蓋所有端點
P79|第三方套件漏洞評估
請執行本專案適用的相依套件漏洞掃描(例如 npm audit、mvn dependency-check、pip-audit 或 trivy fs .),彙整結果。
每個漏洞列出:套件、版本、CVE、嚴重度、是否實際被使用到的程式路徑、建議升級版本、升級風險。預期產出:漏洞彙整表與升級建議。
🧑⚖️ 驗證要點:
- 自行重跑掃描工具,數量一致
- 「是否實際被使用」判斷有程式碼依據
- 升級建議版本確實修補該 CVE(查官方公告)
P80|金鑰與憑證儲存審查
請審查本專案的金鑰、憑證與連線資訊的儲存方式:是否存在於 Repo、設定檔、CI 變數、容器映像、.env 檔。
對照企業資安基準(<基準文件路徑>),列出不符合項目與改善方式(例如改用 Secret Manager、輪替機制)。
特別確認 .worktreeinclude 複製的檔案與 orca.yaml 中是否有機敏內容。預期產出:金鑰儲存審查表與改善建議。
🧑⚖️ 驗證要點:
-
git log -p -S "<金鑰前綴>"確認歷史中無外洩,或已列入輪替 -
.worktreeinclude列出的檔案皆已被 gitignore - 改善建議符合第二十八章的金鑰治理規範
P81|CORS 與安全標頭審查
請審查 <服務路徑> 的 CORS 設定與 HTTP 安全標頭(CSP、HSTS、X-Content-Type-Options、Referrer-Policy、Frame 保護)。
指出過度寬鬆的設定(例如允許任意來源且帶憑證),並提出建議值。預期產出:設定審查與建議值。
🧑⚖️ 驗證要點:
- 在測試環境以
curl -I檢查實際回應標頭 - 以不在白名單的 Origin 發送請求確認被拒
- CSP 建議值不會破壞既有頁面(在 Orca 內建瀏覽器的 console 檢查違規訊息)
36.11 Banking
📌 查證狀態:教學示例(非官方),非真實客戶專案|本節 Prompt 僅示範金融業常見任務的提問方式;法規要求請以主管機關最新規定與企業法遵單位意見為準。
⚠️ 注意事項:本節所有 Prompt 一律搭配去識別化資料。建議在 Remote Orca Server 或企業核准的 SSH 主機上執行,並確認該主機的 Agent 帳號與模型供應商符合企業資料處理政策。
P82|個資欄位遮罩策略
你是金融業資安架構師。請盤點 <API 或模組路徑> 回應中的個人資料欄位(姓名、身分證號、帳號、電話、地址、生日),設計遮罩策略。
內容:欄位分級、各角色可見程度、遮罩格式、實作位置(序列化層或服務層)、稽核記錄需求。
限制:範例全部使用假資料。預期產出:欄位分級表、角色可見矩陣與實作建議。
🧑⚖️ 驗證要點:
- 欄位盤點與實際 Response DTO 一致
- 以不同角色帳號在測試環境呼叫,確認遮罩生效
- 法遵或資安單位簽核分級標準
P83|授信規則結構化
請將 <授信規則程式路徑> 中硬編碼的授信規則轉換為結構化規則設定(例如決策表或規則引擎格式)。
產出:規則清單(條件、結果、優先順序)、轉換後設定檔、轉換前後對照表,以及以相同測試案例驗證結果一致的測試。
限制:不得改變任何規則的判斷結果。預期產出:結構化規則、對照表與等價性測試。
🧑⚖️ 驗證要點:
- 等價性測試涵蓋每條規則的邊界值
- 業務單位逐條確認對照表
- 規則優先順序與原程式一致
P84|批次清算失敗重跑設計
請為 <清算批次名稱> 設計失敗重跑與補償機制。
內容:檢查點設計、冪等鍵、部分成功的處理、補償交易流程、人工介入點、稽核紀錄。
以 Mermaid stateDiagram-v2 呈現批次狀態。預期產出:重跑設計文件與狀態圖。
🧑⚖️ 驗證要點:
- 在測試環境模擬中途失敗並重跑,確認無重複入帳
- 狀態圖每個轉換都有觸發條件
- 人工介入點有權限與覆核設計
P85|ISO 20022 訊息對應
請將內部交易訊息格式(<格式定義路徑>)對應至 ISO 20022 <訊息類型,例如 pacs.008>。
產出:欄位對應表(內部欄位、ISO 元素路徑、轉換規則、必填性)、無法對應的欄位清單、轉換程式草稿與測試。
限制:使用假資料;元素路徑需註明參考的 Schema 版本。預期產出:欄位對應表、缺口清單與轉換草稿。
🧑⚖️ 驗證要點:
- 轉換產出的 XML 以對應版本 XSD 驗證通過
- 必填元素無遺漏
- 業務與清算單位確認對應規則
P86|跨資料中心資料同步策略
請評估 <服務名稱> 跨資料中心部署的資料同步策略,比較同步複寫、非同步複寫與應用層雙寫。
內容:一致性風險、切換時的資料遺失可能、對交易延遲的影響、監控與對帳機制。
最後給出建議並標示需要 DBA 與維運確認的假設。預期產出:同步策略比較與建議。
🧑⚖️ 驗證要點:
- 建議策略為所用資料庫產品實際支援
- 對帳機制可偵測資料不一致
- 假設清單經 DBA 與維運簽核
P87|異常交易偵測規則草擬
請為 <支付服務> 草擬基本的異常交易偵測規則與限流規則,例如:短時間多筆、異常金額、異常地區、新裝置大額交易。
每條規則列出:條件、閾值(標示為初始建議值)、處置方式(警示、阻擋、人工審核)、誤判風險。
產出規則文件與以假資料驗證的測試案例。預期產出:規則文件與測試案例。
🧑⚖️ 驗證要點:
- 閾值由風控單位依歷史資料調整
- 測試案例涵蓋觸發與不觸發兩種情況
- 處置方式有對應的通知與紀錄
P88|授信流程簽核關卡檢查
請比對 <授信流程程式路徑> 與 <內部作業規範文件路徑>,檢查流程中是否遺漏必要的簽核關卡或職務分工(Maker-Checker)。
產出:規範要求與程式實作對照表,標示缺漏與建議修正。預期產出:規範與實作對照表。
🧑⚖️ 驗證要點:
- 對照表每一列都引用規範條文與程式位置
- 在測試環境嘗試以同一人完成建立與核准,確認被阻擋
- 稽核單位確認對照結果
P89|稽核軌跡機制設計
請為 <金融服務模組> 設計符合稽核要求的操作紀錄機制。
內容:記錄事件清單、欄位(誰、何時、做了什麼、前後值、來源)、防竄改方式、保存期限、查詢介面。
限制:紀錄中個資需遮罩;設計需說明與既有日誌系統的整合方式。預期產出:稽核軌跡設計與實作草稿。
🧑⚖️ 驗證要點:
- 事件清單涵蓋所有金額與權限相關操作
- 防竄改方式可驗證(例如雜湊鏈驗證腳本)
- 保存期限符合法遵要求
P90|變更對災難復原演練的影響評估
請根據 git diff <start-from ref>...HEAD 的變更,評估對現有災難復原演練腳本(<腳本路徑>)的影響。
列出:需更新的步驟、新增的相依服務、資料復原順序變化、需要重新演練的情境。預期產出:DR 影響評估與腳本更新建議。
🧑⚖️ 驗證要點:
- 新增相依服務在 DR 環境存在
- 更新後腳本在演練環境執行一次
- 維運與稽核單位確認
36.12 Framework Upgrade
升級任務建議採第二十五章的「盤點、升級、驗證」三階段,並分派到不同 Worktree。以下 Prompt 中的目標版本請依官方 Release Notes 填入。
P91|升級檢查清單產出
請為本專案由 <框架與來源版本> 升級至 <目標版本> 產出完整檢查清單。
內容:語言與執行環境版本需求、相依套件相容性、已移除 API、設定變更、建置工具版本、測試框架版本、部署環境影響。
每項標註來源(官方遷移指南章節或 Release Notes)。預期產出:附來源的升級檢查清單。
🧑⚖️ 驗證要點:
- 抽查 5 項來源確實存在於官方文件
- 清單涵蓋建置與部署,不只程式碼
- 由技術負責人確認優先順序
P92|直接升級或中繼升級評估
請評估本專案應直接升級至 <目標版本>,還是先升級至 <中繼版本>。
依據:目前版本到目標版本之間的重大變更、本專案使用到的受影響功能、測試覆蓋率、團隊時程。
產出:兩種路徑的步驟、風險、工作量與建議。預期產出:路徑比較與建議。
🧑⚖️ 驗證要點:
- 「本專案使用到的受影響功能」以程式碼搜尋確認
- 工作量估算有拆解依據
- 建議與比較結果一致
P93|相依套件相容性掃描
請列出本專案所有直接與間接相依套件,標示與 <目標版本> 的相容性:相容、需升級(建議版本)、不相容(替代方案)、無法判斷。
請執行 <依賴樹指令,例如 mvn dependency:tree 或 npm ls --all> 並附上指令。預期產出:相依套件相容性表。
🧑⚖️ 驗證要點:
- 套件數與依賴樹輸出一致
- 「需升級」的建議版本確實支援目標版本(查各套件 Release Notes)
- 「無法判斷」項目列入人工追蹤
P94|可回滾升級計畫
請為本次升級撰寫可回滾計畫:回滾觸發條件(錯誤率、延遲、功能異常的具體門檻)、回滾步驟、資料相容性處理、回滾演練方式、決策者。
限制:若升級涉及不可逆的資料或 Schema 變更,需明確標示並提出前置措施。預期產出:回滾計畫文件。
🧑⚖️ 驗證要點:
- 觸發條件可由監控系統自動判斷
- 在 Staging 實際演練回滾一次
- 不可逆變更已有前置備份
P95|升級前後啟動時間與記憶體比較
請設計並執行升級前後的效能比較:應用程式啟動時間、穩定後記憶體用量、主要 API 的延遲。
做法:分別在升級前(<start-from ref>)與升級後的 Worktree 執行相同量測腳本,各量測 5 次取中位數。
產出:量測腳本、結果表與差異分析。預期產出:量測腳本與前後比較表。
🧑⚖️ 驗證要點:
- 兩次量測在相同機器與相同設定下進行
- 自行執行腳本可重現相近數字
- 顯著退化項目有原因分析
P96|整合測試重新驗證清單
請根據升級涉及的變更範圍,列出必須重新驗證的整合測試案例與手動測試情境。
依風險分為高、中、低,並說明每個情境與哪一項升級變更相關。預期產出:分級的重新驗證清單。
🧑⚖️ 驗證要點:
- 每個高風險情境都能追溯到具體升級變更
- 清單與既有測試案例編號對應
- QA 負責人確認並排程
P97|前端框架升級對 E2E 測試影響
請評估由 <前端框架來源版本> 升級至 <目標版本> 對既有 E2E 測試(<測試路徑>)的影響:選擇器變化、非同步行為、路由行為、測試工具相容性。
產出:受影響測試清單與修正建議。
可在 Orca 內建瀏覽器開啟升級後頁面,比對 DOM 結構差異。預期產出:受影響 E2E 測試清單與修正建議。
🧑⚖️ 驗證要點:
- 在升級後 Worktree 實際執行 E2E 測試,失敗清單與評估吻合
- 選擇器修正優先使用穩定屬性
- 沒有以延長等待時間掩蓋問題
P98|跨團隊升級變更通知
請根據本次升級內容撰寫給其他團隊的變更通知:升級內容、對外介面影響、需要其他團隊配合的事項、時程、回滾方式、聯絡窗口。
語氣正式,長度控制在一頁內。預期產出:一頁式變更通知草稿。
🧑⚖️ 驗證要點:
- 對外介面影響與 P30 的相容性分析一致
- 時程與回滾方式與 P94 一致
- 不含內部機敏資訊
P99|CI CD Pipeline 升級影響確認
請檢查 CI CD 設定(例如 .github/workflows/、Jenkinsfile、Dockerfile)是否受本次升級影響:建置映像版本、執行環境版本、快取鍵、測試指令、部署腳本。
產出需修改的檔案與修改內容,並在本 Worktree 推送後確認 Checks 結果。預期產出:Pipeline 修改與 Checks 結果。
🧑⚖️ 驗證要點:
- 以
gh pr checks <PR編號>或 Orca 內 PR 狀態確認全部通過 - Dockerfile 基底映像版本固定,不使用 latest
- 快取鍵已包含新版本資訊
36.13 Reverse Engineering
逆向工程的產出是「對既有系統的理解」,最大風險是 Agent 以合理推測填補空白。驗證時應要求每項發現附來源,並用多個 Agent 交叉比對(見 P108)。
P100|COBOL 批次檔案格式解析
你是大型主機系統分析師。請分析 <COBOL 程式與 Copybook 路徑>,整理批次程式的輸入與輸出檔案格式。
產出:每個檔案的欄位表(欄位名稱、PIC 定義、起始位置、長度、型別、業務意義推測)、程式處理流程摘要。
限制:業務意義屬推測者需標示;只讀取,不修改。預期產出:檔案欄位表與流程摘要。
🧑⚖️ 驗證要點:
- 欄位起始位置與長度加總與記錄長度一致
- 以一筆去識別化樣本資料依欄位表解析,結果合理
- 業務意義推測由熟悉系統的人員確認
P101|Struts Action 路由盤點
請盤點 <Struts 專案路徑> 的 struts-config.xml 與 Action 類別,產出路由對照表:URL、Action 類別、Form Bean、Forward 目標 JSP、驗證規則。
另列出設定中存在但找不到類別,或類別存在但未設定的項目。預期產出:路由對照表與不一致清單。
🧑⚖️ 驗證要點:
- 對照表筆數與設定檔 action 元素數一致
- 不一致清單逐項確認
- 抽查 3 條路由在舊系統實際操作驗證
P102|EJB 交易管理分析
請分析 <EJB 模組路徑> 的交易管理方式:容器管理或 Bean 管理、交易屬性(Required、RequiresNew 等)、跨 Bean 呼叫的交易傳播、例外與回滾規則。
產出:交易邊界圖(Mermaid sequenceDiagram)與潛在風險(例如長交易、意外的 RequiresNew)。預期產出:交易屬性表、交易邊界圖與風險清單。
🧑⚖️ 驗證要點:
- 交易屬性與 ejb-jar.xml 或註解一致
- 時序圖中的呼叫順序與程式碼一致
- 風險項目由資深開發者確認
P103|Delphi 表單事件邏輯整理
請分析 <Delphi 表單 .pas 與 .dfm 路徑>,整理表單上每個元件的事件處理(OnClick、OnChange 等)與其業務規則。
產出:事件清單(元件、事件、處理程序、業務規則摘要、涉及的資料表)與業務規則文件。
限制:推測的規則需標示。預期產出:事件清單與業務規則文件。
🧑⚖️ 驗證要點:
- 事件清單與 .dfm 中綁定的事件一致
- 業務規則由使用單位確認
- 涉及的資料表以 SQL 字串搜尋確認
P104|Web Forms ViewState 與遷移難度評估
請分析 <ASP.NET Web Forms 頁面路徑>:ViewState 使用情況、Session 依賴、PostBack 事件、伺服器控制項。
評估遷移至 <目標框架> 的難易度(高、中、低)與主要障礙,並建議遷移順序。預期產出:頁面分析表與遷移評估。
🧑⚖️ 驗證要點:
- 抽查頁面確認 ViewState 與 Session 使用描述正確
- 難易度分級標準明確
- 遷移順序考慮頁面間相依
P105|VB 直接資料庫存取盤點
請盤點 <VB 專案路徑> 中直接存取資料庫的程式碼位置(ADO 連線、SQL 字串、預存程序呼叫)。
產出:位置清單(檔案:行號、存取的資料表或預存程序、讀或寫)與資料表使用矩陣。預期產出:資料存取清單與資料表使用矩陣。
🧑⚖️ 驗證要點:
- 以
rg -i "(select|insert|update|delete) " <VB 專案路徑>自行比對 - 寫入操作無遺漏
- 矩陣中的資料表名稱與資料庫實際存在
P106|無文件模組粗略掃描
請對 <模組路徑> 進行粗略掃描(不超過 30 分鐘工作量):主要職責、對外介面、對內相依、外部系統介接、明顯的技術債。
產出一頁摘要,並列出建議深入分析的子模組與理由。
完成後執行 orca worktree set --worktree active --comment "粗掃完成;建議深入 <子模組>" --workspace-status in-review --json。預期產出:一頁摘要、深入分析建議與 Checkpoint 更新。
🧑⚖️ 驗證要點:
-
orca worktree current --json顯示 Checkpoint 已更新 - 對外介面描述與實際程式碼一致
- 建議深入的子模組理由具體
P107|高風險子模組深入分析
請針對 P106 粗掃結果中的 <子模組名稱>,進行深入分析:類別與函式結構、資料流、狀態管理、錯誤處理、隱含業務規則、測試現況。
產出詳細現況報告,包含 Mermaid 類別圖與資料流圖,每項發現附來源位置。預期產出:詳細現況報告與圖表。
🧑⚖️ 驗證要點:
- 抽查 5 項發現回到來源位置
- 圖表可渲染且與程式碼一致
- 隱含業務規則由業務人員確認
P108|多 Agent 理解結果交叉比對
以下是兩個不同 Agent 對同一 Legacy 模組的分析報告:<報告 A 路徑>、<報告 B 路徑>。
請逐項比對,分為:一致、互補、矛盾。
矛盾項目需回到原始碼查證,並說明哪一方正確或兩者皆不完整;無法判定者列入人工複核清單。預期產出:比對表與人工複核清單。
🧑⚖️ 驗證要點:
- 矛盾項目的查證附原始碼位置
- 人工複核清單由系統負責人逐項處理
- 最終結論更新回 P52 的整合報告
36.14 Orchestration 與 Automations
本節為 Orca 專屬 Prompt,用於讓 Agent 透過 Orca CLI 協調其他 Agent、維護 Checkpoint、建立排程自動化、建立每工作區環境等。使用前請確認:
- 已安裝 Orca CLI 並且
orca status --json成功。 - 已安裝 Orca Skills:
orca skills install --skill orca-cli --skill orchestration。 - 使用 Orchestration 前已在 Settings → Experimental 啟用。
📌 查證狀態:官方文件明確記載 CLI 指令|Prompt 為教學示例(非官方)|CLI 旗標會隨版本演進,Agent 應先執行
orca skills get orca-cli或orca skills get orchestration --full取得與已安裝版本相符的指引|來源:Orchestration、Skills registry
P109|監督式 Orchestration 協調者
你是本次工作的協調者(coordinator)。在做任何變更前,先執行 orca skills get orchestration --full 並遵循其中的流程;不要使用已退役的 orca orchestration run 指令。
目標:<整體目標>
步驟:
1. orca orchestration run-create --objective "<整體目標>" --json 建立 Run。
2. 將目標拆成 2 至 4 個彼此不重疊的 Task,各以 orca orchestration task-create --spec "<規格>" --task-title "<標題>" --json 建立;每個規格需包含允許修改的路徑與驗收標準。
3. 以 orca orchestration worker-start --task <taskId> --worktree new-child --agent <agent> --setup run --json 為每個 Task 啟動 Worker。
4. 以 orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json 等待訊息;處理完一個 Delivery 後用 --ack 確認。
5. 全部完成後輸出彙整:每個 Task 的結果、修改檔案、未完成事項,並以 worker-release 釋放已完成的 Worker 終端機。預期產出:一個 Run、數個 Task 與子 Worktree,以及最終彙整報告。
🧑⚖️ 驗證要點:
-
orca orchestration task-list --json中每個 Task 皆為 completed 或有明確的 failed 或 blocked 原因 - 側邊欄可看到子 Worktree 巢狀於父 Worktree 之下
- 每個子 Worktree 的
git diff --stat都在其 Task 規格允許的範圍內 - Task 之間沒有修改到同一檔案(或已說明合併方式)
P110|Worker 端完成回報合約
你是被分派的 Worker。請遵守以下合約:
1. 只處理 Dispatch 規格中的範圍。
2. 遇到需要決策的問題時,使用 orca orchestration ask --to <coordinatorHandle> --question "<問題>" --options "<選項1>,<選項2>" --timeout-ms 600000 --json,不要在終端機中等待人工輸入。
3. 長時間工作期間依 Dispatch 要求發送 heartbeat。
4. 完成時(無論成功或失敗)必須且只能執行一次:
orca orchestration send --type worker_done --subject "<一行摘要>" --body "<做了什麼、發現什麼、剩下什麼>" --task-id <taskId> --dispatch-id <dispatchId> --outcome <succeeded 或 failed> --files-modified "<檔案清單>" --json預期產出:Worker 完成任務並送出唯一一則 worker_done。
🧑⚖️ 驗證要點:
-
orca orchestration worker-show --dispatch <dispatchId> --json顯示已完成 -
worker_done同時帶有 taskId 與 dispatchId -
--files-modified與該 Worktree 的git diff --name-only一致
P111|決策閘門設定
你是協調者。在 Task <taskId> 進行到需要修改共用元件之前,請建立決策閘門:
orca orchestration gate-create --task <taskId> --question "是否允許修改共用元件 <元件名稱>?" --options '["yes","no"]' --json
在閘門被解決前,不得分派會修改該元件的工作。閘門解決後,依結果調整 Task 規格並繼續。
請在回覆中說明你為何認為此處需要人工決策。預期產出:一個待決的 Decision gate 與決策理由。
🧑⚖️ 驗證要點:
-
orca orchestration dispatch-show --task <taskId> --json可看到 Task 被閘門阻擋 - 人工以
orca orchestration gate-resolve --id <gateId> --resolution "yes" --json解決後,Task 才繼續 - 閘門解決前,共用元件檔案沒有出現在任何 Worktree 的 Diff 中
P112|同題競賽分派
請為以下需求建立三個同題競賽 Worktree,分別使用 claude、codex、<第三個 agent>:
需求:<需求描述與驗收標準>
做法:分別執行 orca worktree create --name <名稱>-<agent> --agent <agent> --prompt "<完整任務規格>" --json。
三個 Worktree 必須從相同的 base ref 建立。建立後列出三個 Worktree 的名稱與路徑,並在每個 Worktree 以 orca worktree set --comment 標記「競賽中」。
不要自行比較結果;比較將另外以 P36 進行。預期產出:三個相同起點的 Worktree 與各自的 Agent。
🧑⚖️ 驗證要點:
-
git worktree list出現三個新 Worktree - 三個分支的 merge-base 相同(
git merge-base <分支A> <分支B>) -
orca worktree list --json中三者的 comment 皆為「競賽中」
P113|Worktree Checkpoint 維護規範
在本 Worktree 工作期間,請在以下時機更新 Checkpoint:完成一個有意義的實作切片、確認或推翻一個假設、完成審查、遇到阻礙、由調查轉為修正或由修正轉為驗證。
更新前先執行 orca worktree current --json 讀取既有內容,保留仍有效的使用者目標與限制,不要覆蓋。
格式:第一行是剛發生的動作、位置與下一步;第二行起可保留目標說明。
指令:orca worktree set --worktree active --comment "<內容>" --workspace-status <todo、in-progress、in-review 或 completed> --json預期產出:Worktree 卡片上持續更新的狀態摘要。
🧑⚖️ 驗證要點:
- Worktree 卡片的 comment 與實際進度相符
- 使用者原本寫入的目標沒有被覆蓋
- 狀態轉換合理(例如測試未通過前不得標記 completed)
P114|建立停用狀態的排程自動化
請協助建立一個每個工作日早上 9 點執行的 Issue 分類自動化,先以停用狀態建立:
orca automations create --name "Weekday triage" --trigger weekdays --time 09:00 --timezone Asia/Taipei --prompt "<分類規則與輸出格式>" --provider codex --repo <repo selector> --disabled --json
建立後執行 orca automations show <automationId> --json,並向我說明:觸發時間、執行位置、使用的 Agent、Prompt 內容。
在我確認之前不要啟用。預期產出:一個停用中的 Automation 與設定說明。
🧑⚖️ 驗證要點:
-
orca automations list --json中該 Automation 為停用 - 時區為 Asia/Taipei,觸發時間正確
- Prompt 中沒有機敏資訊或過大的權限要求
P115|Precheck 條件設計
請為 PR 審查自動化設計 Precheck,讓沒有待審 PR 時跳過執行以節省用量:
orca automations create --name "PR review" --trigger hourly --precheck "<回傳非零即跳過的 shell 指令>" --prompt "<審查規則>" --provider codex --repo <repo selector> --disabled --json
請說明 Precheck 指令在「有 PR」與「無 PR」時的結束碼,並在本機先手動執行該指令兩種情況各一次,貼上結果。預期產出:含 Precheck 的停用 Automation 與 Precheck 測試結果。
🧑⚖️ 驗證要點:
- 自行執行 Precheck 指令,無待審 PR 時結束碼為非零
-
orca automations runs --id <automationId> --json在無 PR 時記錄為 skipped - Precheck 指令本身不會修改任何資料
P116|手動試跑並檢視自動化結果
請對 Automation <automationId> 進行試跑:
1. orca automations run <automationId> --json
2. 等待完成後執行 orca automations runs --id <automationId> --json
3. 開啟該次執行產生或使用的 Worktree,檢查 Agent 產出。
4. 回報:執行結果、耗時、產出是否符合 Prompt 要求、建議的 Prompt 調整。
確認無誤後,告訴我可以執行 orca automations edit <automationId> --enabled --json 啟用,但不要自行啟用。預期產出:試跑紀錄與 Prompt 調整建議。
🧑⚖️ 驗證要點:
- 在 Orca 的 Automations 頁面看到此次執行紀錄與結果
- Agent 沒有自行啟用 Automation
- 產出抽查符合 Prompt 要求後才由人工啟用
P117|每工作區 Cloud VM Recipe 建立
請使用 orca-per-workspace-env skill 為本 Repo 建立每工作區環境。
Provider:<Docker、Fly、Modal 或 Vercel Sandbox>。
流程依 skill 指引:前置條件、基底快照、Agent 認證、orca.yaml Recipe、doctor 驗證。
限制:Provider 憑證不得寫入 Repo;Recipe 腳本需支援 create、suspend、resume、destroy;完成後列出 doctor 的完整驗證結果。預期產出:orca.yaml 中的 Recipe 與生命週期腳本、doctor 驗證結果。
🧑⚖️ 驗證要點:
-
git diff中無 Provider Token 或私鑰 - Recipe 合併至主要 checkout 的
orca.yaml後,建立 Worktree 時 Run on 清單出現該 Recipe - 建立一個測試 Worktree 後執行 destroy,確認 Provider 端資源確實被釋放(避免持續計費)
P118|Design Mode 修正 UI 缺陷
(在 Orca 內建瀏覽器以 Design Mode 點選問題元素後送出)
附件中的元素在 <裝置寬度> 下 <問題描述,例如按鈕文字被截斷>。
請:
1. 依附件中的原始檔位置找出負責該元素的元件與樣式。
2. 以最小修改修正,不影響其他斷點的版面。
3. 說明修改原因與受影響的樣式規則。
完成後我會在內建瀏覽器重新點選驗證。預期產出:最小範圍的樣式或元件修改。
🧑⚖️ 驗證要點:
- Hot Reload 後再次以 Design Mode 點選元素,問題消失
- 以其他裝置尺寸檢查無跑版(
orca set device --name "iPhone 12" --worktree active --json可切換裝置模擬) -
git diff --stat只修改相關元件或樣式檔
P119|Remote Orca Server 健康檢查
你在 Remote Orca Server 的主機 shell 中執行。請進行健康檢查並回報:
1. orca status --json:Runtime 是否正常。
2. orca account list:Claude、Codex 等受管帳號是否存在(只回報帳號標籤,不輸出任何 Token)。
3. 確認 git、gh 與本專案所需 Agent CLI 在此主機的 PATH 中且版本符合需求。
4. 若使用 orca serve 服務,執行 orca serve service status 回報狀態。
5. 列出發現的問題與建議修正。
限制:不得變更任何設定,不得產生新的配對連結。預期產出:伺服器健康檢查報告。
🧑⚖️ 驗證要點:
- 回報中無任何 Token 或配對連結
- 從用戶端 Settings → Remote Orca Servers 確認狀態為 Connected
- 在 Shared Server Access 檢查授權清單,撤銷不再使用的用戶端
P120|Worktree 盤點與清理建議
請盤點目前所有 Worktree 並提出清理建議:
1. 執行 orca worktree ps --json 與 orca worktree list --json。
2. 對每個 Worktree 執行 git -C <路徑> status --short 與 git -C <路徑> log -1 --format="%cr",判斷是否有未提交變更與最後活動時間。
3. 分類:可刪除(已合併且無未提交變更)、需確認(有未提交變更或未合併 commit)、保留(進行中)。
4. 只輸出清單與建議,不要刪除任何 Worktree。預期產出:Worktree 分類清單與清理建議。
🧑⚖️ 驗證要點:
- 「可刪除」項目以
git branch --merged main確認已合併 - Agent 未刪除任何 Worktree(
git worktree list筆數不變) - 實際刪除由人工透過 Resource Manager → Clean up workspaces 執行,若出現 Review N Branches 提示,逐一確認後再強制刪除
36.15 本章 Review 與驗證清單
- 能說明本章 Prompt 的六段骨架,並能把一則一句話的 Prompt 改寫為含範圍、限制與證據要求的版本
- 已建立團隊版 Prompt Library,並替換所有角括號佔位符為實際路徑與指令
- 能說明為何每則 Prompt 都要附「預期產出」與「🧑⚖️ 驗證要點」,以及「證據優先於陳述」的原則
- 已至少執行一則 Coding 類與一則 Testing 類 Prompt,並以
git diff --stat與重跑測試完成驗證 - 已以手動變異方式(反轉一個條件)確認 AI 產出的測試確實有效
- Banking 與 Security 類 Prompt 僅使用去識別化資料,且產出中無完整機敏值
- 已用 P36 或 P108 進行一次多 Agent 交叉比對,並記錄人工判定結果
- 已用 P109 至 P111 完成一次監督式 Orchestration,並以
orca orchestration task-list --json確認所有 Task 狀態 - 已以
--disabled建立 Automation、手動試跑、檢視 runs 後才由人工啟用 - Agent 在工作中會以
orca worktree set更新 Checkpoint,且不覆蓋使用者原有的目標說明 - Agent 不會自行刪除 Worktree、啟用 Automation、改寫 Git 歷史或產生配對連結;這些動作一律由人工執行
第三十七章 總結與未來趨勢
本章為全書收尾,回答三個問題:Orca 最適合哪些組織與專案、從零開始導入的完整路徑長什麼樣子,以及 ADE(Agentic Development Environment)這個類別接下來可能往哪裡走。最後的全書總檢查清單依九個部整理,可直接複製到團隊的導入追蹤工具中使用。
📌 查證狀態:37.1、37.2 依官方文件與本書各章整理;37.3 為依官方說明延伸(教學推論)|來源:Orca 官方文件、GitHub Releases
37.1 最適合的組織與專案
Orca 的核心價值是「讓多個 AI Coding Agent 在互相隔離的 Worktree 中平行工作,並由人類集中審查與合併」。因此是否適合導入,取決於組織能否同時滿足三個前提:有可平行拆分的工作、有足夠的審查能力、有可接受的 Agent 使用政策。
適合度評估表
| 評估面向 | 高度適合 | 需要調整後導入 | 暫不建議 |
|---|---|---|---|
| 工作型態 | 大量可獨立拆分的 Issue、測試補強、遷移與重構 | 工作耦合度高,但可先拆出周邊任務 | 單一大型任務、無法拆分 |
| 版本控制 | 已使用 Git 與 PR 流程(GitHub、GitLab、Bitbucket、Azure DevOps) | 使用 Git 但無 PR 審查習慣 | 非 Git 版本控制系統 |
| 審查能力 | 有資深工程師負責 Review,且有 CI 與自動化測試 | 有 Review 但測試覆蓋率低 | 無人能審查 Agent 產出 |
| 合規要求 | 允許使用經核准的 AI 供應商,原始碼可在本機或自管主機處理 | 需先完成資料分級與供應商審查 | 原始碼完全禁止送往任何外部模型 |
| 執行環境 | 開發者有可安裝桌面 App 的權限,或可使用 SSH 主機 | 端點管控嚴格,需申請例外 | 無法安裝任何未核准軟體 |
| 團隊規模 | 1 至 30 人的產品團隊或平台團隊 | 大型組織,需分批試點 | 無人可擔任導入負責人 |
依專案類型的建議
| 專案類型 | 建議做法 | 對應章節 |
|---|---|---|
| 新 Web 產品開發 | 前後端任務分給不同 Worktree,搭配內建瀏覽器與 Design Mode 驗證畫面 | 第二十三章 |
| 舊系統逆向與文件化 | 先以唯讀分析 Agent 產出文件,再分模組平行補測試 | 第二十四章 |
| 框架或語言版本升級 | 依相依關係分批升級,每批一個 Worktree,CI 作為閘門 | 第二十五章 |
| 金融等高合規產業 | 權限模式採 Manual、所有變更經 PR 與人工審查、Telemetry 統一關閉 | 第二十六章、第二十八章 |
| 端到端功能交付 | 從 Issue 到合併全程在 Orca 中完成,並保留審查紀錄 | 第二十七章 |
如何解讀這兩張表:只要任一面向落在「暫不建議」,就應先處理該面向(例如先建立 PR 審查流程),而不是直接導入。Orca 會放大既有流程的優缺點:流程健全的團隊會得到更高的產出,流程鬆散的團隊則會得到更多需要審查的變更。
37.2 建議導入流程總覽
本節把第三十一章的導入策略與全書各部串成一條完整路徑,適合作為專案啟動會議的總覽。
flowchart TD
A["評估:適合度與合規審查"] --> B["準備:安裝與標準設定基準"]
B --> C["試點:1 至 3 人、2 至 4 週"]
C --> D{"試點指標是否達標"}
D -->|"否"| E["調整 Prompt、權限與任務切分"]
E --> C
D -->|"是"| F["擴大:團隊推廣與教育訓練"]
F --> G["進階:CLI、Automations、遠端執行"]
G --> H["營運:版本管理、成本監控、FAQ 維護"]
H --> I["持續改善:每季複核"]
I --> F如何閱讀此圖:流程由上而下分為評估、準備、試點、擴大、進階、營運六個階段。菱形節點是唯一的決策閘門,試點指標未達標時回到調整步驟後重新試點,而不是直接擴大。最下方的持續改善會回饋到擴大階段,代表導入不是一次性專案,而是每季循環的營運活動。
各階段重點與產出
| 階段 | 主要工作 | 產出物 | 對應章節 |
|---|---|---|---|
| 評估 | 依 37.1 評估適合度,完成供應商與資料分級審查 | 導入評估報告、核准的 Agent 清單 | 第一章、第二十八章 |
| 準備 | 安裝、設定基準、orca.yaml 範本、Prompt 範本 | 標準設定文件、安裝健康檢查紀錄 | 第四章至第六章、第二十章 |
| 試點 | 選 1 至 3 位工程師、一個中風險 Repo | 試點指標(審查時間、退回率、額度用量) | 第十一章、第二十二章、第三十章 |
| 擴大 | 教育訓練、AI Team 角色分工、審查規範 | 團隊操作手冊、審查清單 | 第二十一章、第三十一章 |
| 進階 | CLI Orchestration、Automations、SSH 與 Remote Orca Server | 自動化排程清單、遠端主機清冊 | 第十六章至第十九章 |
| 營運 | 版本管理、成本監控、FAQ 與最佳實務維護 | 版本清冊、月度成本報表、團隊 FAQ | 第二十九章、第三十章、第三十二章 |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 試點有明確指標 | 檢查試點計畫文件 | 至少包含審查時間、PR 退回率、額度用量三項 | 補齊指標後再開始試點 |
| 試點結果有決策紀錄 | 檢查試點結束會議紀錄 | 明確記載擴大、調整或停止的決定與理由 | 召開檢討會議補做決策 |
| 營運責任已指派 | 檢查 RACI 或負責人清單 | 版本管理、成本監控、FAQ 維護各有負責人 | 依第三十一章指派負責人 |
37.3 ADE 未來趨勢
📌 查證狀態:依官方說明延伸(教學推論)|來源:GitHub Releases、附錄 C 版本差異紀錄
以下趨勢是根據 v1.4.150 到 v1.4.244 的發版方向推論,並非官方路線圖,規劃時請以最新 Release Notes 為準。
趨勢一:從「一人多 Agent」走向「多人多 Agent」
這段期間 Orca 陸續加入 Remote Orca Server、Shared Server Access、手機配對與 Orca Relay,執行位置從單一筆電延伸到團隊共用的伺服器。可以預期,未來的重點會從個人生產力工具,轉向團隊層級的 Agent 工作空間,權限、稽核與共用額度管理的重要性會隨之提高。
趨勢二:Agent 協作的結構化
Orchestration 的 Dispatch、worker heartbeat、完成報告重試,以及 Stacked PR,顯示 Agent 之間的分工正從「人工開多個分頁」走向「由 coordinator 分派、追蹤與彙整」。組織應提早建立任務拆分與交接規範(第二十一章),因為工具越自動化,規範不清造成的錯誤擴散得越快。
趨勢三:審查成為瓶頸,工具往審查端投資
Annotate AI Diff、Attribution、Checks 面板整合多平台 CI、大型 Diff 效能改善等更新,都集中在「人類如何更快、更可靠地審查 Agent 產出」。產出速度已不再是限制,審查容量才是。團隊應把審查能力視為需要規劃的產能(第二十二章)。
趨勢四:Agent 中立與供應商分散
支援的 Agent CLI 持續增加,並提供帳號熱切換與用量追蹤。企業不必押注單一模型供應商,可依任務、成本與合規要求選擇。建議在採購策略中保留至少兩個核准的供應商,以因應價格、額度或政策變動。
趨勢五:從桌面延伸到自動化與電腦操作
Automations、Computer Use、Artifacts 與無頭的 orca serve,讓 Agent 可以在無人值守的情況下定時工作,甚至操作 GUI。這帶來的治理需求包括:排程任務的權限邊界、機密資訊的傳遞方式、產出物的外流風險。導入這些功能前,應先完成第二十八章的安全審查。
對組織的建議
- 建立「Agent 產出必經人類審查」的不可妥協原則,並以 PR 與 CI 落實。
- 把 Prompt 範本、
orca.yaml、審查清單當作程式碼管理,納入版本控制。 - 每季依附錄 C 的格式整理一次版本差異,評估新功能是否納入標準流程。
- 持續追蹤成本與品質指標,用數據而非感覺決定擴大或收斂。
37.4 全書總檢查清單
本清單依全書九個部整理,每一項都可在對應章節找到操作步驟與驗證方式。建議導入負責人在每個階段結束時逐項勾選,並保留勾選紀錄作為稽核佐證。
37.4.1 第一部 認識 Orca
- 能用一句話說明 Orca 是 ADE,而不是 AI 模型或 IDE 的替代品(第一章)
- 能說明 Repository、Worktree、Agent、Session、Tab 之間的關係(第二章)
- 能說明 Orca 使用自備訂閱(BYO subscription),程式碼由 Agent CLI 直接送往其供應商(第一章、第三章)
- 能畫出本機、SSH 主機、Remote Orca Server、手機四種執行位置的架構圖(第三章)
- 能說明 Telemetry 只收集匿名使用資料、不包含程式碼與 Prompt 內容(第三章)
37.4.2 第二部 安裝與初始設定
- 已依作業系統完成安裝,macOS 使用
brew install --cask stablyai/orca/orca或官方安裝檔(第四章) - 已確認 Linux 的 CLI 指令為
orca-ide,避免與螢幕閱讀器衝突(第四章) - 已完成安裝後健康檢查:
orca status --json回應正常(第四章) - 已完成第一次工作階段:新增 Repo、建立 Worktree、啟動 Agent、檢視 Diff(第五章)
- 已依企業標準設定基準完成 Settings,並記錄於設定清單(第六章)
- 已確認 Agent permissions 模式(Manual、Auto、Yolo)符合組織政策(第六章)
- 已依政策設定 Telemetry(Settings → Privacy 或環境變數)(第六章)
37.4.3 第三部 Agent 整合
- 已安裝並登入至少一個核准的 Agent CLI,且可在 Orca 中啟動(第七章)
- 已了解各 Agent 的權限旗標與 Orca 權限模式的對應(第七章)
- 已設定帳號與用量追蹤,知道額度用盡時如何熱切換帳號(第八章)
- 已了解 Hooks、Memory 與 Session History 的用途與資料存放位置(第九章)
- 已設定 Agent 狀態通知,並了解 Hibernation 的觸發條件(第十章)
37.4.4 第四部 平行開發工作流
- 已為主要 Repo 建立
orca.yaml或.worktreeinclude,新 Worktree 可直接啟動開發環境(第十一章) - 已訂定 Worktree 命名、數量上限與清理規則(第十一章)
- 已熟悉終端機分割、Monaco 編輯器與檔案瀏覽器的操作(第十二章)
- 已使用內建瀏覽器與 Design Mode 驗證至少一個 UI 變更(第十三章)
- 已使用 Annotate AI Diff 完成至少一次審查回饋循環(第十四章)
- 已確認
gh auth status正常,並在 Orca 中建立與查看 PR(第十五章) - 已依需求連結 Linear 或 Jira,並驗證 Issue 可轉為 Worktree(第十五章)
37.4.5 第五部 進階功能
- 已能用 CLI 建立 Worktree、讀取終端機輸出並查詢狀態(第十六章)
- 已了解 Orchestration 的 coordinator、worker 與 Dispatch 機制(第十六章)
- 已以
--disabled建立 Automation,手動執行並檢查 runs 紀錄後再啟用(第十七章) - 已評估 Computer Use 的權限與機密傳遞方式(
--value-stdin)(第十七章) - 已設定 SSH 主機,並確認 managed server、host key 驗證與 orca CLI 控制權限(第十八章)
- 若使用 Remote Orca Server,已建立存取連結的發放與撤銷流程(第十八章)
- 若使用手機,已完成配對並了解 Relay 與 LAN 的差異(第十九章)
37.4.6 第六部 方法論
- 已建立團隊 Prompt 範本,包含目標、限制、驗收條件與 Commit 規範(第二十章)
- 已定義 AI Team 角色(規劃、實作、審查、測試)與交接格式(第二十一章)
- 已建立 Agent 產出審查清單,並規定所有變更必須經人類審查(第二十二章)
- 已將 CI 與自動化測試設為合併閘門(第二十二章)
37.4.7 第七部 實戰案例
- 已選定最接近團隊情境的案例(第二十三章至第二十七章)作為試點範本
- 已依案例完成一次從 Issue 到合併的完整流程,並記錄耗時(第二十七章)
- 已整理試點中遇到的問題,回饋到 Prompt 範本與設定基準
37.4.8 第八部 企業治理與營運
- 已完成 AI 供應商審查、資料分級與核准 Agent 清單(第二十八章)
- 已確認憑證檔案權限(例如
~/.copilot/config.json僅擁有者可讀)與機密不進 Prompt 的規範(第二十八章) - 已建立版本升級節奏、測試機驗證與回滾流程(第二十九章)
- 已建立 Log 收集與 Bug 回報流程,且回報前會移除機敏資訊(第二十九章)
- 已建立月度成本與額度用量報表(第三十章)
- 已訂定導入階段、負責人與成功指標(第三十一章)
37.4.9 第九部 參考與總結
- 已閱讀 FAQ 並建立團隊自有 FAQ 與每季複核機制(第三十二章)
- 已將最佳實務納入團隊操作手冊(第三十三章)
- 已完成 Orca 與其他工具的比較評估,並記錄選型理由(第三十四章)
- 已將常用 Mermaid 圖與 Prompt 範本納入團隊知識庫(第三十五章、第三十六章)
- 已建立依附錄 C 格式追蹤版本差異的機制,並定期核對附錄 B 的官方文件連結
37.5 本章 Review 與驗證清單
- 已依 37.1 的適合度評估表完成自評,且沒有任何面向落在「暫不建議」
- 已依 37.2 的流程訂出各階段的時程、產出物與負責人
- 能區分 37.3 中的官方事實與教學推論,並知道以最新 Release Notes 為準
- 已將 37.4 全書總檢查清單複製到團隊追蹤工具,並指派各部負責人
- 已排定第一次季度複核日期
附錄A 名詞表
本附錄整理全書使用的 Orca 與 AI 開發相關名詞。英文名稱以 Orca v1.4.244 介面與官方文件的用語為準;中文為本書統一譯名,介面上顯示英文的項目,正文中通常保留英文以便對照操作。
📌 查證狀態:官方文件明確記載|來源:Orca 官方文件
A.1 核心概念
| 名詞 | 中文 | 說明 | 參見章節 |
|---|---|---|---|
| ADE(Agentic Development Environment) | 代理式開發環境 | 以管理多個 AI Coding Agent 平行工作為核心的開發環境,Orca 屬於此類別 | 第一章 |
| Repository | 儲存庫 | 加入 Orca 的 Git 專案,Worktree 由此建立 | 第二章 |
| Worktree | 工作樹 | Git 原生功能,同一 Repo 的獨立工作目錄與分支;Orca 中每個任務一個 Worktree | 第二章、第十一章 |
| Main worktree | 主工作樹 | Repo 原始的 checkout 目錄,與 Orca 建立的 Worktree 區分 | 第十一章 |
| Folder workspace | 資料夾工作區 | 非 Git 資料夾形式的 Workspace | 第十一章 |
| Workspace | 工作區 | Orca 側邊欄中可開啟的工作單位,包含 Worktree 與資料夾 | 第二章 |
| Agent | 代理 | 在終端機中執行的 AI Coding CLI,例如 Claude Code、Codex | 第七章 |
| Agent CLI | 代理命令列工具 | Agent 的命令列程式,Orca 不內建模型而是啟動這些 CLI | 第七章 |
| Session | 工作階段 | 一次 Agent 執行從啟動到結束的生命週期 | 第二章、第十章 |
| State dot | 狀態點 | 側邊欄顯示 Agent 狀態(工作中、等待輸入、完成等)的指示燈 | 第十章 |
| Restart chip | 重新啟動標籤 | Agent 結束後出現的快速重新啟動控制 | 第十章 |
| Tab、Pane、Split | 分頁、窗格、分割 | Orca 的版面單位,可拖曳分割並組成分頁群組 | 第二章、第十二章 |
| Session Restore | 工作階段還原 | 重開 Orca 後恢復 Worktree、分割、捲動紀錄與焦點分頁 | 第二章 |
| Quick Open | 快速開啟 | 在目前 Worktree 中快速開啟檔案 | 第二章 |
| Jump Palette | 跳轉面板 | Cmd+J 跨 Worktree、最近項目與分頁的跳轉 | 第二章、第十一章 |
| BYO subscription | 自備訂閱 | 使用者以自己的 Agent 訂閱或 API Key 付費,Orca 不轉售模型 | 第一章、第三十章 |
A.2 Agent 與帳號
| 名詞 | 中文 | 說明 | 參見章節 |
|---|---|---|---|
| Native Chat | 原生聊天介面 | 建立在支援 Agent Session 之上的選用聊天介面,提供結構化對話紀錄 | 第七章 |
| Agent permissions(Manual、Auto、Yolo) | 代理權限模式 | v1.4.232 起於 Settings → Agents 設定的權限模式,由嚴到寬 | 第六章、第七章 |
| Trust folder | 信任資料夾 | Agent CLI 首次在目錄執行時要求的信任確認 | 第七章 |
| Hot-swap | 帳號熱切換 | 一鍵切換作用中的 Codex 等帳號,不中斷工作 | 第八章 |
| Usage tracking | 用量追蹤 | 追蹤各 Agent 供應商的用量與限流狀態 | 第八章 |
| Hooks | 鉤子 | Agent 在特定事件執行的自訂指令,Orca 讀取並尊重既有慣例 | 第九章 |
| Memory | 記憶檔 | Agent 的專案記憶檔(例如 CLAUDE.md、AGENTS.md) | 第九章 |
| Session History | 工作階段歷史 | 右側欄瀏覽與恢復過去 Agent Session 的功能 | 第九章 |
| Hibernation | 休眠 | 自動暫停閒置背景 Agent 終端機,重開 Worktree 時恢復 | 第十章 |
| Agents feed | 代理動態 | 跨 Worktree 的 Agent 完成、阻塞與建立事件串流 | 第十章 |
| Inbox | 收件匣 | 集中顯示需要使用者處理的通知 | 第十章 |
| Keep computer awake(Caffeinate) | 保持喚醒 | 防止電腦在 Agent 工作時進入睡眠的設定 | 第十章、第三十二章 |
| Hand Off | 交接 | 將工作從一個 Agent 或位置轉交給另一個 | 第二十一章 |
A.3 工作流、審查與整合
| 名詞 | 中文 | 說明 | 參見章節 |
|---|---|---|---|
| orca.yaml | Orca 設定檔 | Repo 層級設定,定義 Worktree 建立後的 setup 指令等 | 第十一章 |
| .worktreeinclude | Worktree 複製清單 | 指定建立 Worktree 時要從主目錄複製的未追蹤檔案(如 .env) | 第十一章 |
| Shared Paths | 共享路徑 | 讓多個 Worktree 共用特定目錄,減少重複安裝 | 第十一章 |
| Worktree checkpoint | Worktree 檢查點註記 | 每個 Worktree 的自由文字狀態註記,供人與 Agent 交接 | 第十六章 |
| Quick Commands | 快速指令 | 預先定義、可一鍵送出的指令或 Prompt | 第六章、第十九章 |
| Resource Manager | 資源管理員 | 狀態列開啟,檢視 CPU、記憶體、Session 與磁碟用量並清理 Workspace | 第二十九章、第三十章 |
| Monaco | Monaco 編輯器 | 與 VS Code 相同的程式碼編輯器元件,支援自動儲存 | 第十二章 |
| xterm.js | 終端機元件 | Orca 終端機採用的元件,與 VS Code 相同 | 第十二章 |
| OSC 52 | 終端剪貼簿序列 | 讓終端程式寫入系統剪貼簿的跳脫序列 | 第十二章 |
| Design Mode | 設計模式 | 在內建瀏覽器點選 UI 元素並把元素資訊送給 Agent | 第十三章 |
| Browser-use profile | 瀏覽器身分設定檔 | 以特定登入身分與 Cookie 執行 Orca 瀏覽器 | 第十三章 |
| Diff viewer | 差異檢視器 | 每個 Worktree 內建、相對 base 分支的差異審查介面 | 第十四章 |
| Annotate AI Diff | AI 差異註記 | 在任一行留下註記並批次送回 Agent 修正的審查循環 | 第十四章 |
| Attribution | 來源歸屬 | 標示每一行由 Agent 或人類撰寫 | 第十四章 |
| Checks panel | 檢查面板 | 顯示 PR/MR 的 CI 結果與 Review Thread | 第十四章、第十五章 |
| Stacked PR | 堆疊式 PR | 以上一層 PR 分支為 base 的連續 PR,僅 GitHub 支援 | 第十五章 |
| Auto-merge | 自動合併 | 條件滿足時由 GitHub 自動合併 PR | 第十五章 |
| GitHub API Budget | GitHub API 預算 | Settings → Git 中顯示 GitHub 額度的面板 | 第十五章、第三十二章 |
| Linear、Jira drawer | Linear、Jira 抽屜 | 在任務抽屜瀏覽、建立並連結 Issue 至 Worktree | 第十五章 |
| Recipe | 操作食譜 | 官方文件中針對特定情境的逐步操作範例 | 附錄 B |
A.4 CLI、自動化、遠端與治理
| 名詞 | 中文 | 說明 | 參見章節 |
|---|---|---|---|
| Orca CLI | Orca 命令列 | orca(Linux 為 orca-ide),從終端機操作 Orca | 第十六章 |
| Selector | 選擇器 | CLI 用來指定 Worktree、終端機等目標的語法,例如 active | 第十六章 |
| Orchestration | 協作編排 | 以 Run、task、worker、message 與決策閘門協調多個 Agent | 第十六章 |
| Coordinator、Worker | 協調者、執行者 | Orchestration 中分派工作與執行工作的角色 | 第十六章 |
| Dispatch | 派工 | 將任務指派給 worker 的動作與狀態紀錄 | 第十六章 |
| Heartbeat | 心跳 | worker 定期回報存活狀態,預設 5 分鐘 | 第十六章、第三十二章 |
| Skills | 技能 | 提供給 Agent 的 Orca 使用指南,隨版本更新 | 第十六章 |
| MCP(Model Context Protocol) | 模型上下文協定 | Agent 與外部工具溝通的協定,Orca 提供對應整合 | 第十六章 |
| Automations | 排程自動化 | 依排程執行 Prompt 的 CLI 功能 | 第十七章 |
| Precheck | 預先檢查 | Automation 執行前的 shell 探測,非零結束碼即跳過 | 第十七章 |
| Computer Use | 電腦操作 | Agent 透過無障礙樹與截圖操作桌面 App(Beta) | 第十七章 |
| Artifacts | 產出物連結 | 將檔案發佈為公開連結的選用功能,預設關閉 | 第十七章 |
| SSH worktree | SSH 工作樹 | 位於遠端 SSH 主機上的 Worktree | 第十八章 |
| Managed Orca server | 受管 Orca 伺服器 | v1.4.224 起 Orca 在 SSH 主機上自行管理的伺服器程序 | 第十八章 |
| Remote Orca Server | 遠端 Orca 伺服器 | 在另一台電腦執行 Orca,從筆電連入 | 第十八章 |
| orca serve | 無頭伺服器模式 | 以命令列啟動不含桌面介面的 Orca 伺服器 | 第十八章 |
| Shared Server Access | 共用伺服器存取 | 管理 Remote Orca Server 存取連結與撤銷 | 第十八章、第二十八章 |
| Tailscale | Tailscale 私有網路 | 常用於連接 Remote Orca Server 的 WireGuard 私有網路 | 第十八章 |
| Port forwarding | 連接埠轉送 | 將遠端開發伺服器埠轉送到本機的 Ports 分頁功能 | 第十八章 |
| GSSAPI(Kerberos) | GSSAPI 驗證 | 企業單一登入常用的 SSH 驗證方式,交由系統 OpenSSH 處理 | 第十八章 |
| FIDO2 security key | FIDO2 硬體金鑰 | ed25519-sk 等硬體金鑰 SSH 驗證 | 第十八章 |
| Cloud VM | 雲端虛擬機 | 依 Workspace 按需建立的雲端執行環境 | 第十八章 |
| Mobile companion | 行動伴隨 App | iOS 與 Android 上監看與操作 Agent 的 App | 第十九章 |
| Orca Relay | Orca 中繼 | 手機與桌面不在同一網路時的中繼連線,需登入 Orca 帳號 | 第十九章 |
| Terminal host | 終端機主機程序 | 持有終端機程序的背景服務,升級時可能新舊並存 | 第二十九章、第三十二章 |
| RC channel | RC 發行管道 | 搶先試用的 Release Candidate 版本 | 第四章、第二十九章 |
| Telemetry | 遙測 | 匿名使用資料收集,可由設定或環境變數關閉 | 第三章、第二十八章 |
| Profile(SQLite) | 設定檔資料庫 | Orca 儲存設定與狀態的本機資料庫 | 第二十九章 |
如何使用此名詞表:撰寫團隊內部文件時,請沿用「中文」欄的譯名並在首次出現時附上英文;若官方未來調整介面用語,以 Settings 實際顯示的英文為準,並同步更新團隊名詞表。
附錄B 官方文件連結索引
本附錄列出 Orca 官方文件網站截至 v1.4.244(2026-10-29)的全部 57 頁,依主題分為 12 類,每頁附一句說明與本書對應章節。官方文件會持續更新,引用時請以網站最新內容為準。
📌 查證狀態:官方文件明確記載|來源:Orca 官方文件
B.1 入門
| 文件 | 說明 | 本書章節 |
|---|---|---|
| What is Orca? | 一分鐘了解 Orca 的定位與適用情境 | 第一章 |
| Install | macOS、Windows、Linux 安裝方式與 RC 版本 | 第四章、第二十九章 |
| Your first 3-agent session | 五分鐘內讓三個 Agent 平行運作 | 第五章 |
| Ways to run Orca | 本機、SSH、自架 Orca 伺服器與按需 VM 的選擇 | 第一章、第三章、第十八章 |
B.2 核心模型
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Worktrees | 每個功能或 Bug 對應一個 Git Worktree 的運作方式 | 第二章、第十一章 |
| Agents & sessions | 狀態點、重新啟動標籤與 Agent Session 生命週期 | 第二章、第十章 |
| Tabs, panes & split layouts | 拖曳分割窗格、分頁群組與快捷鍵 | 第二章 |
| Quick Open & Jump Palette | Cmd+J 跨 Worktree、最近項目與分頁跳轉 | 第二章 |
| Session restore | 重開 Orca 後恢復工作狀態 | 第二章 |
B.3 Agents
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Supported agents | 內建支援的 Agent 清單 | 第七章、第二十八章 |
| Claude Code in Orca | Claude Code 的整合、帳號與用量 | 第七章、第九章 |
| Codex in Orca | Codex 的深度整合與疑難排解 | 第七章、第四章 |
| Hot-swap Codex accounts | 一鍵切換多個 Codex 帳號 | 第八章 |
| Cursor CLI in Orca | Cursor CLI 的啟動與狀態偵測 | 第七章 |
| How to use GLM-5.2 in Orca ADE | 讓 Claude Code 等 CLI 改用 GLM 模型 | 第七章 |
| Chat UI (native chat) | 選用的原生聊天介面 | 第七章 |
| Usage & rate-limit tracking | 各供應商用量與限流追蹤 | 第八章、第三十章 |
| Agent hooks & memory | Hooks 與 Memory 慣例的支援 | 第九章 |
| Agent session history | 瀏覽與恢復過去的 Agent Session | 第九章 |
| Agent hibernation | 閒置 Agent 自動暫停與恢復 | 第十章、第三十章 |
B.4 終端機與編輯器
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Terminal | 以 xterm.js 為基礎、為 Agent 工作流調整的終端機 | 第十二章 |
| Monaco editor & autosave | 程式碼編輯器與自動儲存 | 第十二章 |
| File explorer & external drag-drop | 檔案瀏覽器與外部拖放 | 第十二章 |
| Rich markdown editor | Markdown 富文字編輯器 | 第十二章 |
| HTML, Mermaid, PDF & image viewers | 內建的各類檔案檢視器 | 第十二章 |
B.5 瀏覽器
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Per-worktree browser | 每個 Worktree 專屬的內建 Chromium 瀏覽器 | 第十三章 |
| Browser-use profiles | 以特定登入身分執行瀏覽器 | 第十三章 |
| Design Mode | 點選 UI 元素並交給 Agent 修改 | 第十三章 |
B.6 Review 與整合
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Diff viewer | 為 AI 程式碼審查設計的差異檢視器 | 第十四章 |
| Annotate AI Diff | 逐行註記並批次送回 Agent 的審查循環 | 第十四章 |
| Attribution | 標示每一行由誰撰寫 | 第十四章 |
| Commit & push from Orca | 在 Orca 內 Commit、Push 與開啟審查 | 第十四章 |
| Hosted reviews, issues & Actions | PR/MR、Issue 與 CI 的整合 | 第十五章 |
| Linear items drawer | Linear Issue 的瀏覽、建立與連結 | 第十五章 |
| Jira items drawer | Jira Cloud 與自架版 Issue 的連結 | 第十五章 |
B.7 CLI 與自動化
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Orca CLI overview | CLI 的用途與安裝 | 第十六章 |
| Orca CLI reference | 指令、選擇器與 Agent 友善的使用模式 | 第十六章 |
| Orchestration | 以 Run、task、worker 與決策閘門協調 Agent | 第十六章 |
| Orca skills registry & MCP | Agent skills 的安裝、更新與 MCP | 第十六章 |
| Worktree checkpoints | Worktree 的狀態註記欄位 | 第十六章 |
| Scheduled automations | 依排程執行 Prompt | 第十七章 |
| Computer use | 讓 Agent 操作本機桌面 App | 第十七章 |
B.8 遠端與行動
| 文件 | 說明 | 本書章節 |
|---|---|---|
| SSH worktrees | 透過 SSH 在遠端主機執行 Agent | 第十八章、第二十八章 |
| Remote Orca Servers | 在另一台電腦執行 Orca 並從筆電連入 | 第十八章、第二十八章 |
| Mobile companion | 手機配對、監看與操作 Agent | 第十九章 |
| Install Orca Mobile on Android | Android APK 下載與安裝 | 第十九章、第四章 |
B.9 通知與活動
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Notifications & Inbox | Agent 完成或等待時的通知與收件匣 | 第十章 |
| Agents feed | 跨 Worktree 的 Agent 事件串流 | 第十章 |
B.10 設定與隱私
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Settings reference | 全部 Settings 窗格與選項說明 | 第六章 |
| Privacy & Telemetry | 收集與不收集的資料,以及關閉方式 | 第三章、第六章、第二十八章 |
B.11 疑難排解
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Troubleshooting & FAQ | Agent 啟動、Worktree、CLI、SSH 等常見問題 | 第二十九章、第三十二章 |
| Troubleshooting GitHub errors | 限流、驗證失敗與其他 GitHub CLI 錯誤 | 第十五章、第二十九章、第三十二章 |
B.12 Recipes
| 文件 | 說明 | 本書章節 |
|---|---|---|
| Race three agents on the same task | 同一任務交給三個 Agent 比較結果 | 第五章、第十一章 |
| Jump between 10 worktrees | 以 Jump Palette 與狀態點管理大量 Worktree | 第十一章 |
| Fix a UI bug with Design Mode | 一分鐘內完成 UI 修正循環 | 第十三章 |
| Review an AI diff line-by-line | 逐行審查 AI 差異的完整流程 | 第十四章 |
| Work on a remote machine over SSH | 把 SSH 主機當作本機使用 | 第十八章 |
B.13 GitHub 與其他官方連結
| 資源 | 說明 | 本書章節 |
|---|---|---|
| stablyai/orca | 原始碼 Repository,根目錄 README 含功能總覽與多語版本 | 第一章 |
| Releases | 各版本 Release Notes 與安裝檔 | 第二十九章、附錄 C |
| Issues | Bug 回報與功能需求 | 第二十九章、第三十二章 |
| Download | 官方桌面版下載頁 | 第四章 |
| Android APK 下載 | Orca Mobile Android 安裝檔 | 第十九章 |
| Orca IDE(App Store) | Orca Mobile iOS 版 | 第十九章 |
| Discord | 官方社群 | 第三十二章 |
| X(@orca_build) | 官方公告帳號 | 附錄 D |
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 連結有效 | 以瀏覽器或 curl -sI <網址> 逐一檢查 | 回應 200 或正常轉址 | 到官方文件首頁搜尋新路徑並更新本附錄 |
| 頁數完整 | 比對官方文件側邊欄頁數 | 與本附錄 57 頁一致 | 新增頁面依分類補列並標註本書章節 |
| 內容版本 | 對照官方文件與最新 Release Notes | 內容未與 v1.4.244 之後的變更衝突 | 依附錄 C 格式記錄差異 |
附錄C 版本差異紀錄
本附錄整理 v1.4.150(2026-07-22)到 v1.4.244(2026-10-29)之間的重要變更,作為從舊版文件或舊版安裝升級時的對照表。內容依 GitHub Releases 的 Release Notes 濃縮改寫,只收錄對企業使用者有影響的項目;完整清單請以 Releases 頁面為準。
📌 查證狀態:官方文件明確記載|來源:GitHub Releases
C.1 期間概況
| 項目 | 內容 |
|---|---|
| 起點版本 | v1.4.150(2026-07-22) |
| 終點版本 | v1.4.244(2026-10-29) |
| 期間長度 | 約 14 週 |
| stable 版本數 | 起點之後共 78 個 stable 版本,平均每週 5 至 6 版 |
| 跳號說明 | 部分版本號未發布;v1.4.157 的 tag 作廢,內容改以 v1.4.158 發布;v1.4.172 建置失敗,修正併入 v1.4.173 |
| 主要方向 | 遠端執行(managed server、Remote Orca Servers)、原生聊天介面、支援 Agent 大幅增加、GitHub/Jira 整合深化、多語系介面 |
如何解讀:Orca 屬於高頻發版的產品,企業不需要逐版升級,但需要有人持續閱讀 Release Notes 的相容性段落,並依第二十九章的升級節奏統一升級。
C.2 重要版本時間軸
| 版本 | 日期 | 重點變更 | 影響章節 |
|---|---|---|---|
| v1.4.152 | 2026-07-23 | Codex 可把工作接續到新 Session;macOS orca serve 更新後安全重啟 | 第七章、第十八章 |
| v1.4.155 | 2026-07-24 | 「需要你處理」狀態統一使用問號圖示 | 第十章 |
| v1.4.156 | 2026-07-25 | 「Send Review Notes to Agent」可自訂快捷鍵 | 第十四章 |
| v1.4.159 | 2026-07-27 | 側邊欄可辨識並篩選由 CLI 建立的 Workspace | 第十一章、第十六章 |
| v1.4.165 | 2026-08-03 | Session History 顯示第一則 Prompt;SSH 斷線自動復原;支援 FIDO2 | 第九章、第十八章 |
| v1.4.166 至 v1.4.167 | 2026-08-03 | 中文、韓文與 Windows 輸入法的大量修正 | 第十二章 |
| v1.4.168 | 2026-08-04 | 語音輸入可選麥克風;Linear/Jira 新增 Issue 保留草稿 | 第十五章 |
| v1.4.170 至 v1.4.173 | 2026-08-05 | SSH 與遠端伺服器可靠性系列修正 | 第十八章 |
| v1.4.178 | 2026-08-10 | 帳號制 Artifact 分享;Cmd+J 加入最近的 Chat 與終端機 | 第二章、第十七章 |
| v1.4.180 | 2026-08-11 | Stacked PR;Artifact 發佈預設關閉 | 第十五章、第十七章 |
| v1.4.185 至 v1.4.186 | 2026-08-19 至 08-20 | Worktree 依來源控制可見性;清理對話框改版 | 第十一章 |
| v1.4.187 | 2026-08-21 | 主機間分享私有 skill;建立 Worktree 時選擇位置;CLI 可讀取終端機可視畫面 | 第十一章、第十六章 |
| v1.4.191 至 v1.4.192 | 2026-08-28 至 08-29 | 在所有本機與遠端主機管理 Automations | 第十七章 |
| v1.4.198 至 v1.4.199 | 2026-09-08 至 09-09 | Structured Chat 成熟;GitHub Projects Roadmap;單一 Create 按鈕 | 第七章、第十五章 |
| v1.4.206 | 2026-09-20 | 跨電腦搜尋 Session History 與 orca search;支援 OpenCode 2 | 第九章、第十六章 |
| v1.4.211 | 2026-09-25 | Muse Code 成為一級 supervised worker | 第七章、第十六章 |
| v1.4.212 | 2026-09-25 | 修正 Codex 在長路徑下的 SUN_LEN 錯誤 | 第三十二章 |
| v1.4.214 | 2026-09-26 | 原生 Jupyter Notebook;Profile 儲存改為 SQLite;內建 ripgrep | 第十二章、第二十九章 |
| v1.4.217 | 2026-09-29 | 每個 Codex 分頁使用獨立 server;SSH 多因素驗證 | 第七章、第十八章 |
| v1.4.218 | 2026-09-30 | 新增 DeepSeek Harness、Freebuff、Qoder、CodeBuddy;Reset Terminal;大型 Diff 不再凍結 | 第七章、第十二章、第十四章 |
| v1.4.219 | 2026-10-02 | 自動回應 Trust this folder;Windows orca 改為原生程式;Orchestration 完成報告重試 | 第七章、第十六章 |
| v1.4.220 | 2026-10-04 | SSH 主機可用不需 Node 的 runtime;新 terminal host | 第十八章、第二十九章 |
| v1.4.221 | 2026-10-05 | Copilot 設定檔權限安全修正;新增 Qwen Code、GLM Coding Plans 等 | 第七章、第二十八章 |
| v1.4.222 | 2026-10-07 | 大型 CSV 編輯器;用量選單顯示更多額度;CJK 輸入法 Enter 修正 | 第八章、第十二章 |
| v1.4.223 | 2026-10-08 | Chat Rewind;Settings → Chat;GitHub Projects Board | 第七章、第十五章 |
| v1.4.224 | 2026-10-10 | SSH 主機改用 managed Orca server;Automations 可設定 model/effort;一個 Workspace 可連結多個 PR | 第十七章、第十八章 |
| v1.4.227 | 2026-10-16 | 每個新 Chat 可設權限模式;Codex Chat 需 0.136.0 以上 | 第七章 |
| v1.4.229 | 2026-10-17 | Jira planning(list、board、sprint、JQL);Shared skills 擴大支援 | 第十五章、第十六章 |
| v1.4.230 | 2026-10-19 | SSH 主機上的 orca CLI 控制權預設關閉 | 第十八章、第二十八章 |
| v1.4.232 | 2026-10-20 | Manual/Auto/Yolo 權限模式;Node.js mirror | 第六章、第七章、第十八章 |
| v1.4.233 | 2026-10-20 | Remote Orca Servers 合併為單一清單;支援 Windows Server 2019 | 第十八章 |
| v1.4.235 | 2026-10-20 | Claude Chat 的 Rewind to here;每個對話記住 model 與 effort | 第七章 |
| v1.4.237 | 2026-10-21 | 手機筆記;無頭 orca serve 的手機語音輸入 | 第十九章 |
| v1.4.238 | 2026-10-23 | Resolve with AI;遠端伺服器新增帳號;Resource Manager PTY 檢視 | 第十四章、第十八章、第二十九章 |
| v1.4.239 | 2026-10-24 | 一鍵安裝 Orca skills;Browser profiles | 第十三章、第十六章 |
| v1.4.240 | 2026-10-25 | 瀏覽器歷史紀錄;orca ports | 第十三章、第十八章 |
| v1.4.241 | 2026-10-26 | 內嵌 DevTools;觀看 Agent 操作瀏覽器;權限設定移至 Settings → Agents | 第六章、第十三章 |
| v1.4.242 | 2026-10-27 | Claude subagent transcript;Codex Ask mode 唯讀;終端機閒置 CPU 降低 | 第七章、第三十章 |
| v1.4.243 | 2026-10-28 | Chrome extensions(實驗性);終端 Session 即時轉為 Chat;worker heartbeat 可調;新 terminal host | 第十三章、第十六章 |
| v1.4.244 | 2026-10-29 | 新增繁體中文、德文、俄文、土耳其文介面;遠端影音播放;orca worktree create --branch;iOS 改走 App Store | 第四章、第十九章 |
C.3 相容性與升級注意事項
| 版本 | 注意事項 | 建議動作 |
|---|---|---|
| v1.4.217 至 v1.4.218 | Codex 每個分頁改用獨立 server,會增加記憶體用量,且 Codex 桌面版與 codex agents 看不到 Orca 內的 Session | 需要共享時在 shell 啟動檔設定 ORCA_CODEX_ISOLATE=0,或在 Settings → Agents 關閉;變更只套用新終端機 |
| v1.4.219 | 預設自動回應資料夾信任提示;Windows orca 不再需要 Visual C++ Redistributable | 高合規環境評估是否在 Settings → Agents 關閉自動信任 |
| v1.4.220 | 啟動新的背景 terminal service,舊終端機留在舊服務;orca file open 預設不切換焦點 | 腳本需要切換焦點時加上 --focus;方便時重開終端機 |
| v1.4.221 | v1.4.219 至 v1.4.220 可能讓 ~/.copilot/config.json 被其他使用者讀取;Windows Codex 改用 ~/.codex | 立即升級並檢查檔案權限(含 SSH 主機);Windows 使用者重新信任資料夾、補回 MCP server |
| v1.4.224 | SSH 主機改用 managed Orca server,切換時會重啟終端機 | 安排在非工作時段切換;無法執行 managed server 的主機需另行評估 |
| v1.4.227 | Codex Chat 需 Codex 0.136.0 以上 | 執行 codex --version 確認 |
| v1.4.230 | SSH 主機上的 orca CLI 控制權在遷移時被設為關閉 | 只對需要的主機在 Advanced Connection 重新開啟 |
| v1.4.232 至 v1.4.240 | Native chat 多項新功能需要 paired 或 SSH 主機同步更新 | 桌面與主機的 Orca 版本一起升級 |
| v1.4.239 | Browser profiles 預設為 Shared;Recover server 清除 stale lock 前需確認沒有其他機器共用 home 執行 Orca | 依隔離需求改為 per-repo 或 per-workspace |
| v1.4.240 | orca ports 不支援 direct SSH 主機;pnpm reclaim-space 會回收舊 Worktree 的相依套件與建置輸出 | 執行回收前先停止相關程序 |
| v1.4.241 | 新 terminal host;權限設定由 Settings → Chat 移到 Settings → Agents;部分 OpenCode 2.0.x 版本不允許選模型 | 更新內部設定文件的路徑 |
| v1.4.242 | Claude subagent 導覽會在 Claude 的 keybindings.json 加入快捷鍵;執行中的 Claude Session 需重啟 | 檢查快捷鍵衝突 |
| v1.4.243 | 新 terminal host;Chrome extensions 需在 Settings → Experimental 開啟並重啟;heartbeat 變更只套用新 worker | 企業環境先評估擴充功能政策再開啟 |
| v1.4.244 | 沿用 v1.4.243 的 terminal host;部分修正需重開機才生效;SSH 與 paired server 修正需主機同版;Worktree 位置的 ~ 代表家目錄;iOS 改由 App Store 安裝 | 升級後安排一次重開機;通知 iOS 使用者改從 App Store 安裝 |
C.4 已移除或改名的功能
| 版本 | 變更 | 對舊文件的影響 |
|---|---|---|
| v1.4.176 | 移除 Source Control 群組排序偏好設定 | 舊教學中的該設定已不存在 |
| v1.4.184 | 移除無法到達的 Skills 頁面 | 改用 Settings → Agents 的 Skill freshness 或 orca skills |
| v1.4.199 | 「New workspace」與「Add project」合併為單一 Create 按鈕 | 舊截圖與步驟需更新 |
| v1.4.223 | Structured Chat 實驗開關改名為「Use updated structured native chat」並移到 Settings → Chat UI | 舊文件的 Experimental 路徑需更新 |
| v1.4.224 | 「Continue in New Session」改名為「Hand Off to Another Agent」 | 名詞統一使用 Hand Off |
| v1.4.233 | Remote Orca Servers 由六個區段合併為單一清單 | 舊的分區說明已不適用 |
| v1.4.241 | Settings → Chat 的權限下拉選單移除 | 權限一律在 Settings → Agents 設定 |
| v1.4.244 | 行動設定頁的 TestFlight 預覽選項移除 | iOS 一律從 App Store 安裝 |
C.5 升級作業程序
- 閱讀目標版本與目前版本之間所有 Release Notes 的相容性段落,對照 C.3 標記影響項目。
- 在測試機升級,執行第四章的安裝後健康檢查。
- 若團隊使用 SSH 主機或 Remote Orca Server,同步規劃主機端 Orca 的升級。
- 通知使用者升級時間、需要重開的終端機與需要重新登入的項目。
- 升級後依下表驗證,並更新團隊版本清冊。
✅ 驗證方式
| 檢查項目 | 驗證方法 | 預期結果 | 若不符合 |
|---|---|---|---|
| 桌面版本 | orca status --json(Linux 為 orca-ide) | 版本為目標版本 | 重新下載安裝並完全重啟 Orca |
| SSH 主機版本 | orca environment status --environment <selector> --json | managed server 版本與桌面相容 | 在 Settings → Managed servers 執行 Update |
| 憑證檔權限 | ls -l ~/.copilot/config.json | 權限為僅擁有者可讀寫 | 執行 chmod 600 ~/.copilot/config.json |
| Agent 可啟動 | 在新 Worktree 啟動核准的 Agent | 正常啟動且狀態點顯示工作中 | 依第三十二章 32.3 排錯 |
| GitHub 整合 | gh auth status -h github.com 並開啟 PR 面板 | 登入正常且 PR 顯示 | 依第三十二章 32.5 排錯 |
附錄D 參考資料
本附錄列出本書引用的資料來源。官方資料為本書的主要依據;第三方資料僅作背景參考,引用前請自行查證最新內容。
D.1 官方資料
| 資料 | 連結 | 用途 |
|---|---|---|
| Orca 官方文件 | https://www.onorca.dev/docs | 全書功能說明的主要依據,57 頁清單見附錄 B |
| Orca 官方網站與下載頁 | https://onorca.dev/download | 安裝檔下載 |
| GitHub Repository | https://github.com/stablyai/orca | 原始碼、README 與授權資訊 |
| GitHub Releases | https://github.com/stablyai/orca/releases | 版本差異(附錄 C)與安裝檔 |
| GitHub Issues | https://github.com/stablyai/orca/issues | 已知問題與回報管道 |
| Android APK 下載頁 | https://www.onorca.dev/download/android | Orca Mobile Android 版 |
| Orca IDE(App Store) | https://apps.apple.com/us/app/orca-ide/id6766130217 | Orca Mobile iOS 版 |
| Orca Discord | https://discord.gg/fzjDKHxv8Q | 官方社群與支援 |
| Orca 官方 X 帳號 | https://x.com/orca_build | 版本與活動公告 |
D.2 相關工具與服務
| 資料 | 連結 | 用途 |
|---|---|---|
| GitHub Status | https://www.githubstatus.com | 判斷 GitHub 服務中斷(第三十二章 32.5) |
| GitHub CLI 文件 | https://cli.github.com/manual | gh auth、gh api 等指令 |
| GitHub REST API 速率限制說明 | https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api | REST、GraphQL、Search 額度 |
| Git Worktree 文件 | https://git-scm.com/docs/git-worktree | Worktree 原理(第二章、第十一章) |
| Tailscale 文件 | https://tailscale.com/kb | Remote Orca Server 網路設定(第十八章) |
| SignPath | https://signpath.io | Windows 安裝檔程式碼簽章服務 |
| Mermaid 文件 | https://mermaid.js.org | 第三十五章圖表語法 |
D.3 第三方資料
以下資料出現在本書舊版草稿中,舊稿未保留網址。內容可能已過時,請自行查證後再引用:
| 資料 | 內容摘要 | 使用注意 |
|---|---|---|
| andrew.ooo 對 Orca 的技術評測 | 安裝檔約 250 MB、閒置記憶體約 400 至 800 MB 的實測數據 | 為舊版本實測,請以自身環境的 Resource Manager 數據為準(請自行查證) |
| Stably AI 公司背景(Y Combinator W22) | Orca 開發商的公司背景 | 請以官方網站或 Y Combinator 公開資料查證 |
Arch User Repository 套件 stably-orca-bin、stably-orca-git | Arch Linux 社群維護的安裝套件 | 非官方維護,企業環境請評估供應鏈風險(請自行查證) |
Repository 內文件 docs/reference/headless-linux-server.md | 在無頭 Linux 伺服器執行 Orca 的說明 | 檔案位置可能隨版本變動,請在 Repository 中搜尋最新路徑(請自行查證) |
D.4 查證方式與基準日期
- 本書功能描述以 Orca v1.4.244(2026-10-29 發布)及當時的官方文件為基準。
- 版本日期以
gh release list -R stablyai/orca的輸出為準。 - 官方文件與 Release Notes 不一致時,以實際安裝版本的 Settings 介面與
orca --help輸出為最終依據。 - 標註「教學推論」的內容是依官方說明延伸的建議,並非官方承諾。
- 建議每季依附錄 B 的驗證方式檢查一次連結有效性,並依附錄 C 格式補充新的版本差異。