把 Vela
用明白。

01開始

從下載到說出第一句話，只有三步：連上模型、選一個資料夾、交代任務。

這是什麼#

Vela 是一款在你電腦上工作的 AI 編程夥伴。你在輸入框裡描述任務，它在你的專案資料夾裡讀檔、改檔、執行指令，把過程收成緊湊的一行行；需要你點頭的事會停下來等你。

它不是把程式碼搬去某台遠端主機：Agent 迴圈、檔案系統與 Git 操作都在本機主程序完成，只有你交給模型閱讀與修改的內容，才會送往你自己連接的模型服務。

安裝與第一次開啟#

1. 下載安裝檔到 GitHub Release 下載 Vela-1.1.3-arm64.dmg，打開後把 Vela 拖進「應用程式」。
2. 第一次開啟安裝檔沒有經過 Apple 公證。如果 macOS 擋下來，到「系統設定 → 隱私權與安全性」，在下方選擇「仍要打開」。
3. 連上模型打開「模型與帳號」，登入一家供應商，或填入 API 金鑰；也可以新增自訂的模型介面。

首次啟動先選擇語言，再透過插畫介紹認識 Vela。八步設定依序帶你調整外觀、資訊欄配置、技能、模型、權限、記憶與指令，以及背景行為；可選步驟可以略過。之後可在「設定 → 關於與更新」重看介紹與版本亮點，不會改變已儲存的偏好。

第一次對話#

開啟一個本機專案資料夾，或建立一個獨立的 Git worktree。選好模式、權限與模型之後，在輸入框寫下你想完成的事——像交代同事一樣把背景與驗收條件說清楚，第一句話不需要完美，隨時可以在回覆途中補充。

從原始碼啟動#

需要 Node.js 22.19.0 以上與 pnpm 11.24.0：

git clone https://github.com/KryptonGao/VelaHarness
cd VelaHarness
pnpm install
pnpm dev

開發版使用獨立的資料目錄 ~/.vela-dev，可以和安裝版同時執行，帳號與對話互不干擾。

02介面導覽

主介面分成三個區域：左邊找對話，中間做事，右邊看細節。

三個區域#

輸入框旁的三件事#

• 模式　Agent、Plan 或 Goal；回覆進行中不能切換，先按停止再換。
• 權限　每次詢問、幫我批准或完全訪問；決定有風險的動作要不要先問你。
• 模型　這個對話要用哪個模型與推理強度；之後也能在對話中更換。

快速鍵#

03三種模式

同一個輸入框，三種做事的節奏。回覆進行中不能切換模式，想換先停下來。

Agent：邊做邊說#

預設模式。讀檔、改檔、跑指令，一邊做一邊跟你說；需要決定時停下來問你。可用的工具包含 read、bash、edit、write，以及提問與成果驗收。

Plan：先看方案再動手#

Plan 模式只讀不寫：在計畫被批准之前，修改檔案的動作會在執行前被拒絕，指令也只放行 cat、ls、grep、rg、git status 這類唯讀命令。

Vela 會交出一份完整的 Plan Document——標題、修訂號與方案全文。修訂號從 1 遞增，改方案要重送完整新版；舊版標成「已被取代」，只能讀，不能執行。批准之後可以選在目前對話繼續，或清空規劃留下的上下文、用新對話執行。執行時對應的待辦清單為 1–50 項，同時最多一項進行中。

Goal：盯著目標做到底#

適合多步驟的長期目標。Vela 會持續推進、寫下進度備註，並在回報完成前記錄驗證結果；驗證分低、中、高風險：中風險要查 diff 並跑定向測試，高風險還要加上回歸檢查。

驗證之後又動了程式碼，先前的驗證就失效，需要重新驗證。Vela 不能自己暫停目標——暫停是你的操作。

怎麼選#

04權限與審批

有風險的動作先問過你，是 Vela 的預設脾氣。

三檔權限#

審批與收件匣#

審批、提問、待檢查與背景任務的結果，都集中在左側的收件匣；徽章只計算真正需要你處理的事項。審批五分鐘沒有回應會自動過期；重新啟動後仍待處理的審批與提問一律作廢，需要重新發起。關掉視窗之後 Vela 仍在背景待命，新事項會通知你。

權限的作用範圍#

• 權限跟著對話走：換一個對話，可以有不同的設定。
• 子代理繼承它所屬對話的權限；explore 子代理只讀，不會動檔案。
• 定時任務與任務配方可以在啟動時覆寫權限，只作用於該次執行建立的新對話與其子代理。

05對話與協作

過程退後，事情才浮得出來；需要分工時，Vela 會自己找幫手。

緊湊過程#

預設的緊湊模式把每次工具呼叫收成一行：讀了哪些檔案、改了哪幾行、跑了什麼指令，連續呼叫自動合併成摘要。點檔名在右側預覽、展開編輯看 diff、展開指令看輸出；一輪結束後整段過程可以收起，只留結論。想要一張張卡片，到「設定 → 對話顯示」切換。

子代理小隊#

大任務可以拆給幾位子代理同時進行：explore 只讀查資料，general 可以動手改檔；子代理之間能互相傳訊息，也能再帶自己的小隊。

每一位子代理都有自己的一頁，點 /root/auth 這樣的樹狀路徑，就能在右側看到它想了什麼、做了什麼、結論是什麼。子代理的對話會一併保存。

軌跡回放#

每次執行的完整紀錄：時間軸與事件清單連動，思考、工具呼叫與回傳都在上面；可以按時長、輪次或模型呼叫檢視。選一個節點看它的參數、結果與計時，指標包含首個 Token 的等待、生成耗時、Token 用量與快取命中；連最初的系統提示詞與工具定義都留著。舊對話沒有記錄的指標會標成「未記錄」。

回答裡的互動介面#

計算器、對比表、圖表與流程圖可以直接長在回答裡，你當場調參數、看結果。它們是宣告式資料，由 Vela 自己的元件畫出來，模型的腳本不會被執行；唯一的例外是設定裡開啟的沙盒微應用，要由你按下執行，才會在受限環境中跑起來。

圖表裡的數字可能是回答裡直接寫死的值，也可能引用本次對話真實的工具結果；引用工具結果時會把來源標在元件旁邊，引用不到時顯示失敗，而不是編造內容。

06改動與驗收

改壞了可以退回去，做完了看得見證據。

檢查點與回滾#

Vela 在每一輪開始與結束時記錄工作區的檔案狀態。想重來時，編輯其中一則訊息並重新送出，該輪之後的對話會被撤回，工作區檔案從檢查點還原；重新送出前就有的未提交改動會保留。

還原有明確的界線：不會覆蓋 Git 索引與提交、被忽略的相依套件與建置目錄、工作區以外的檔案，以及對外部服務做過的操作。

成果驗收#

完成的工作回覆可以在工作面板打開「驗收」分頁：每一條需求對上實際的修改、已記錄的驗證證據與待確認事項。檔案連結會開啟對應輪次的 diff，失敗的檢查預設展開。如果驗證之後又改了東西，該項會標成「可能已過期」。純問答的回答不會有這個分頁；沒有提交驗收時，面板會給出保守的摘要。

任務交接包#

想換一個新對話接著做，從「更多對話操作 → 產生交接包…」開始：目標、已確認的決策、修改過的檔案、實際的驗證與未完成事項整理成一份文字，檢查編輯後開新對話，內容已填進輸入框，何時送出由你決定。事實取自工具記錄與檔案檢查點，模型只負責整理目標、決策與未完成事項；它編出來的文件與驗證會被丟掉。模型暫時不可用時，交接包會降級成純事實版本並明確標示。

對話導出#

對話可以導出成 Markdown 或 HTML 單一檔案：可以選擇附上軌跡與檔案 diff、也可以略過思考過程。輸出裡的命令與日誌會依照規則脫敏；導出的 diff 是閱讀用的紀錄，不是可以直接 git apply 的補丁。被回滾的輪次不會出現在導出中。

07記憶與自動化

會記住約定，也能在你不在的時候按時做事。

記憶#

記憶是兩份看得見的 Markdown：全域記憶 ~/.vela/MEMORY.md 記你的偏好；專案記憶 <工作區>/.vela/MEMORY.md 記這個專案的約定。你可以在「設定 → 記憶」查看、編輯、清空或刪除。

每個檔案上限 16 KiB，寫入時帶著內容的 revision 防止衝突；衝突時 Vela 不會硬寫。專案記憶跟著工作區走：每個 Git worktree 有自己的記憶，不會自動複製或回退主工作樹。Plan 模式、子代理與定時任務只能讀記憶，不能寫。

定時任務#

可以設定一次、每天、每週，或一段 Cron 表示式（含時區）。每次執行都在綁定的工作區開一個新對話，也能預先指定權限、模型與推理強度，或沿用應用程式的設定。

應用程式關閉或電腦睡眠時不會執行；恢復後依你的設定補跑一次；選擇跳過時，遲到超過 60 秒的執行不會補跑。同一個任務同時只跑一次，重複觸發會被記為略過。

任務配方#

把反覆做的事寫成含參數的模板。在輸入框輸入 / 打開「技能／任務配方」選單，選一個配方後先填參數、看過預覽，再啟動一個新對話。配方可以放在資料目錄、專案或團隊共享文件裡，也能在啟動時覆寫模式、模型與權限。

Skills#

一個含 SKILL.md 的資料夾，就教會 Vela 一項新手藝。載入順序依序是 .pi/skills、.agents/skills、~/.agents/skills、~/.vela/skills，專案內同名優先；原本在 Codex 或 Claude Code 裡的 Skills 也能直接搬過來。

08連接外部世界

需要時才去找工具，用完就收。

MCP 與外掛#

Vela 可以連接本機或遠端的 MCP 伺服器：全域設定在 ~/.vela/mcp.json，專案設定在 <工作區>/.pi/mcp.json。專案伺服器第一次啟用時要在設定頁確認信任，信任綁定工作區路徑與檔案內容，內容改了要重新確認。

工具預設按需發現：平時不占上下文，需要時透過搜尋找到；也可以指定為隨時可用，或完全隱藏。唯讀授權要逐個確認；Plan 模式與 explore 子代理只拿得到明確授權為唯讀的工具。

Notion 是內建外掛：在設定裡一鍵連接，不需要填 URL 或 Token，OAuth 在系統瀏覽器完成，憑證以系統安全儲存空間加密保存在本機。

瀏覽器面板#

對話裡的連結可以在右側面板打開；Vela 也能在同一個頁面上點擊、填寫、截圖，幫你驗證剛改好的介面。同一個資料目錄的對話共用登入狀態，Cookie 只留在本機；Plan 模式不提供瀏覽器工具。單次操作預設 30 秒，上限 120 秒。

PR 中心#

「我建立的」、「待我審查」、「分配給我」與「提及我」四種關係放在同一頁，可以跨倉庫查看；概覽、檢查狀態、留言、檔案樹與 diff 都在這裡。

可以讓 Agent 回應審閱意見：限定你本人建立且正在開啟中的 PR，它會在獨立 worktree 裡修改並在本機提交，你檢查過之後才推送與回覆。

GitHub 的邊界#

• 所有 GitHub 操作都經由本機的 gh CLI，使用你已經登入的身分；Vela 不存取你的 Token。
• 只支援 github.com；GitHub Enterprise 不在目前的範圍。
• 搜尋與排序只在已載入的結果範圍內生效，不是全站搜尋。

09設定與資料

東西放在哪，你都找得到。

資料放在哪#

外觀與語言#

介面提供繁體中文、簡體中文、英文、日語與韓文五種語言。淺色與深色各有幾套配色，可以固定，也可以跟隨系統切換。工具的顯示方式、會話連結要開在面板還是系統瀏覽器，都在設定裡。

更新#

安裝版啟動後會檢查 GitHub Release，之後約每 4 小時再看一次；發現新版本便在背景下載。安裝前會先驗證 Ed25519 簽章，再核對 SHA256SUMS.txt 裡的雜湊值，最後確認解壓出的應用程式版本正確，全部通過才替你換版。下載完成後可以選「立即重新啟動」，或稍後再裝——下次退出 Vela 時自動完成。

自動更新可以在設定裡關掉；關掉之後只在你手動檢查時連網。更新失敗時先看 ~/.vela/updates/installer.log。從磁碟映像檔直接執行、或應用程式目錄沒有寫入權限時，Vela 不會自動替換，只能手動安裝。

日誌與診斷#

日誌以 JSON Lines 存在 ~/.vela/logs，每天一個檔案，保留 14 天、總量上限 100 MB。遇到問題時，到「設定 → 日誌與診斷」匯出診斷包：裡面有日誌、系統資訊與脫敏後的設定摘要；憑證、對話訊息與記憶內容不會被放進去，只有你勾選時才加入當前對話的軌跡。

10常見問題

出港前最常被問到的幾件事。