【2026 最新】Apache Maka 教學：用 Event Log 驗證 Agent 中斷、續跑與權限

Apache Maka 教學最值得做的，不是再看一次「AI Agent 能幫你做什麼」，而是故意在任務中途按下停止：Agent 說進度已保存，真的代表工具結果、權限決策與終止狀態都已經寫進可恢復的紀錄嗎？重新啟動後，它會接著做、重做一次，還是乾脆停下來請你判斷？

這篇專為第一次接觸 Agent Runtime 的讀者寫。我們會把 Apache Maka 當成一個仍快速變動的實驗工作台，在拋棄式資料夾裡完成「安裝前驗證、事件帳本判讀、中斷與安全續跑、權限與 Credential Vault 稽核」四件事。你不必改 Maka 原始碼，也不必把任何正式專案或正式憑證交給它。

先說結論：安全續跑不是把舊程序叫醒

• 截至 2026 年 8 月 30 日，先從原始碼建置。官方主 README 明確表示尚未有核准的 Apache Release；CLI 文件雖仍列出 maka-agent@next，但當天 npm registry 並沒有這個 dist-tag，因此本文不把它當成可用安裝路徑。
• Runtime Event Log 是執行帳本，不只是聊天紀錄。它保存模型訊息、Tool Call、Tool Result、權限與終止等語意事件；目前主線把它寫進 runtime.sqlite。
• 有序中止、程序崩潰與安全續跑是三件事。只有功能旗標開啟後的 TUI /resume，才是在檢查安全邊界後延續被中斷的 Turn；maka run --resume則是對舊 Session 加一個新 Prompt。
• 安全結果不只有「自動接著跑」。遇到未決權限、未配對工具結果或無法證明的外部副作用時，系統明確停放（park）並拒絕重播，往往才是正確答案。

安全續跑 ＝ 舊事件事實 ＋ 安全邊界判斷 ＋ 新 Run；不是把舊程序喚醒。

Apache Maka 是什麼？先把 Workspace、Runtime 與 Event Log 分開

Apache Maka 是 Apache Incubator 中的 Agent 工作台專案。官方的主 README把路徑畫成：Desktop／TUI／CLI 把要求交給 Runtime Host，Runtime 再協調模型與工具，最後把事實提交到 Runtime Event Log，UI、Session 與模型 Context 都是從這些事實做出的投影。

把它想成餐廳會最好懂：聊天視窗是客人看到的「出餐畫面」，Runtime 是廚房，Event Log 則是每張點單、加單、退單與出餐時間都不能任意改寫的流水帳。畫面可以重新整理，模型的 Context 也可能被壓縮，但帳本才是事故後用來追查「哪一步真的發生」的依據。若你還不熟 Harness 與 Runtime 的差別，先讀 AI Agent Harness 是什麼與 如何動手做 Agent Harness。

這也解釋了為什麼本文不把「畫面還看得到上一句」當成恢復成功。真正要核對的是：原始要求是否存在、工具呼叫與結果是否成對、權限是否已決定、最後一筆是否形成可判斷的終止邊界，以及續跑是否建立新的執行身分。

Apache Maka 教學第 1 步：先做版本與發布狀態驗收

這一步不能省。Maka 主線目前變動很快：本文研究鎖定 Git commit 827b3fdf940f0bb5d309548a1f099104ec25da87；Manifest 顯示 0.2.0，但 Changelog 仍把它標為 Unreleased。GitHub Releases 上可看到較早的便利產物，它們也不等於經 Apache 投票核准的正式 Release。官方Incubator 專案頁顯示 Maka 於 2026 年 8 月 13 日進入孵化。

git ls-remote https://github.com/apache/maka.git HEAD
npm view maka-agent dist-tags versions deprecations
node --version
npm --version

截至本文核對日，第二行只會顯示舊的預覽版本資訊，npm view maka-agent@next會回傳 404。這不是叫你找一個不明鏡像繞過去，而是「停止條件」：當文件、Registry 與 Release 狀態不一致，就退回官方目前推薦的原始碼路徑。官方需求是 Node.js 22.19 以上、npm 11、Git 與 ripgrep；不要為了跑實驗去替換主機既有的正式開發環境，直接用容器、VM 或獨立測試帳號。

建立可丟棄、可重現的來源工作區

mkdir maka-resume-lab
cd maka-resume-lab
git clone https://github.com/apache/maka.git source
cd source
git checkout --detach 827b3fdf940f0bb5d309548a1f099104ec25da87
npm ci
npm run build
node packages/cli/dist/dev-cli.js --help

最後一行只檢查 CLI 是否能啟動，不需要模型金鑰。記下 packages/cli/dist/dev-cli.js的絕對路徑；後面會從 Fixture 資料夾呼叫它，讓 Agent 的目前工作目錄與 Maka 原始碼分開。真的要跑一個 Turn，Maka 不會附送共用模型帳號；請只使用你已獲授權的測試連線，並在這個拋棄式 Profile 內設定。原始碼版 CLI 使用 Maka Dev Profile，與一般發行版的 Maka Profile 不會自動同步，這正好降低誤用正式設定的機率。

Apache Maka 教學第 2 步：設計一個能判分的小任務

測試 Agent 恢復能力時，任務越大，越無法判斷它是「續跑」還是「重新猜一次」。本文使用一個只會產生兩個檔案的 Fixture，並把停止條件寫進 Prompt：

在目前資料夾建立 lab-output/step-1.txt，內容只能是 phase-1；
接著讀回該檔，建立 lab-output/done.txt，內容只能是 verified；
兩個檔案都確認後立刻停止。不要修改其他檔案，不要連網。

這個任務有三個優點：副作用只在單一資料夾、每一步都有肉眼可驗證的結果，而且「兩個檔案都存在就停止」不需要你相信 Agent 自己的成功宣告。先提交乾淨 Git 基線，之後每一組測試都從相同 Commit 建立新的 Worktree；做法與 Context 壓縮後的重新取得成本文章相同：固定輸入與環境，才有資格比較前後差異。

cd ..
mkdir maka-fixture
cd maka-fixture
git init
printf '只允許在 lab-output/ 寫入測試結果。\n' > FIXTURE.md
git add -- FIXTURE.md
git -c user.name="Maka Lab" \
  -c user.email="maka-lab@example.invalid" \
  commit -m "maka interruption fixture"
BASE_SHA=$(git rev-parse HEAD)
git worktree add --detach ../trial-a "$BASE_SHA"
git worktree add --detach ../trial-b "$BASE_SHA"
git worktree add --detach ../trial-c "$BASE_SHA"

若測試資料夾本來就包含私密檔、SSH Key、雲端設定或客戶程式碼，請換一個 Fixture；不要靠 Prompt 寫「請忽略祕密」來補救。這也是 Agent Workspace與一般聊天介面最關鍵的差別：工具能碰到的邊界，必須先由環境與權限限制。

Apache Maka Event Log 怎麼讀？先看 5 種事實

目前主線的 RuntimeEvent 型別把每筆事實拆成角色、作者、內容、動作、狀態與關聯 ID。新手不用讀完整 JSON，只要先回答以下五題：

1. 原始要求在不在？找 text 類事件，確認要求沒有在續跑時被複製成第二個使用者訊息。
2. 工具呼叫有沒有結果？function_call與function_response應能靠呼叫 ID 對上。只有呼叫、沒有可證明結果，就不是安全重播邊界。
3. 權限是否已關閉？permissionRequest之後要有允許、拒絕或明確關閉；未決問題不能被當作「大概允許」。
4. 最後狀態是什麼？終態可能是 completed、failed、aborted或cancelled。它們描述的是執行邊界，不是模型回答看起來是否完整。
5. 續跑是否換了新身分？安全續跑會保留來源關係，但建立新的 Invocation、Run 與 Turn；第一筆 continuation 事實要先持久化，才會再次呼叫模型。

Event Log 不是供應商 HTTP 請求的逐位元封包備份，也不能單憑它證明任意遠端 API「絕對只執行一次」。它是 Runtime 的語意事實來源。這種「事實層與畫面層分開」的設計，也能和 DeepSeek Agent Harness 的 Session 紀錄、程式化 Tool Call 的暫停與續跑一起理解。

「Append-only」也要說清楚範圍：已提交的 canonical event 依序新增，身分衝突會 fail closed；串流中的 partial snapshot 則放在可更新的獨立資料表，而且使用者明確清除 Session 時可以刪除事件。它不是防竄改帳本，也不是永遠不可刪的法遵稽核系統。

只匯出「稽核收據」，不要匯出完整 Payload

runtime.sqlite可能含 Prompt、工具參數與結果，不能直接上傳或貼進 Issue。先關閉或讓 Maka 閒置，再用 SQLite 的備份功能建立離線 Snapshot。把官方 README 所列的 <Electron userData>/workspaces/default/runtime.sqlite實際路徑填入變數；原始碼 Profile 名稱是 Maka Dev。

MAKA_DB="/absolute/path/to/Maka Dev/workspaces/default/runtime.sqlite"
LAB_RECEIPT="/absolute/path/to/maka-audit-receipt"
mkdir -p "$LAB_RECEIPT"

sqlite3 "$MAKA_DB" ".backup '$LAB_RECEIPT/runtime.snapshot.sqlite'"
sqlite3 -header -csv "$LAB_RECEIPT/runtime.snapshot.sqlite" \
  > "$LAB_RECEIPT/events.csv" <<'SQL'
WITH latest AS (
  SELECT invocation_id
  FROM runtime_events
  ORDER BY committed_at DESC
  LIMIT 1
)
SELECT event_seq,
       event_kind,
       json_type(payload_json, '$.actions.permissionRequest') IS NOT NULL
         AS permission_requested,
       json_type(payload_json, '$.actions.permissionDecision') IS NOT NULL
         AS permission_decided,
       json_type(payload_json, '$.actions.continuationStart') IS NOT NULL
         AS continuation_started,
       committed_at
FROM runtime_events
WHERE invocation_id = (SELECT invocation_id FROM latest)
ORDER BY event_seq;
SQL

shasum -a 256 "$LAB_RECEIPT/events.csv" > "$LAB_RECEIPT/events.sha256"
rm "$LAB_RECEIPT/runtime.snapshot.sqlite"

這張 CSV 刻意不輸出 payload_json、Session ID、Prompt、工具參數或結果，只保留順序、事件種類、三個布林旗標與時間。先在本機逐列看過，再決定是否分享；資料庫 Snapshot 用完就刪除。若未來 Schema 變動導致查詢失敗，應回頭看該 Commit 的SQLite Schema，不要猜欄位。

Apache Maka 教學第 3 步：三組故障注入怎麼跑？

先讓三組試驗使用相同模型、相同 Prompt、相同 Worktree 基線與相同權限模式。每組完成後記錄 git status --short、兩個檔案內容與上面的稽核收據。不要比較回答文筆；只比較可觀察副作用與事件邊界。

A 組：正常完成，建立基準線

在 trial-a啟動 TUI，使用預設會在要求擴大邊界時詢問的模式，不加 --yolo。送出小任務；若出現權限提示，先核對目標與理由，只允許測試資料夾內的必要動作。兩個檔案完成後，確認最後事件形成完成邊界。A 組不是在測恢復，而是在告訴你「健康軌跡應長什麼樣」。

cd ../trial-a
MAKA_DEV_CLI="/absolute/path/to/source/packages/cli/dist/dev-cli.js"
node "$MAKA_DEV_CLI"

# TUI 內送出前述小任務；完成後回到另一個 Terminal 檢查
git status --short
cat lab-output/step-1.txt
cat lab-output/done.txt

B 組：雙擊 Esc，有序中止

在 trial-b送出同一任務，看到第一個工具動作後，於 TUI 連按兩次 Esc。當前原始碼把「執行中雙 Esc」定義為中斷 Turn；如果權限視窗正開著，Esc 的意思可能是拒絕該提示，所以要先看畫面狀態。這條路徑會讓 Runtime 有機會記錄中止，不等同於程序突然消失。

記下哪些檔案已經存在、最後狀態與未決權限數。接著重新開啟 Session，但先不要輸入「請繼續」；若你先新增 Prompt，就已經改變測試問題。這種介面中斷策略，也可搭配 多 Agent 中斷路由的 continue／queue／ask-now／deny 思路，區分「要不要打斷」與「打斷後能不能安全恢復」。

C 組：程序崩潰，只在拋棄式環境進行

真正的 Crash 測試要讓程序來不及走正常收尾路徑。只在沒有其他 Maka 工作的測試帳號中，從第二個 Terminal 用 ps找出路徑明確指向本次 dev-cli.js的單一 PID，人工核對後才執行 kill -KILL <PID>。如果看到多個候選、無法確認 PID 或共用 Runtime Host，跳過這組；不要用模糊的 pkill規則。

ps -Ao pid,command | grep '[d]ev-cli.js'
# 人工核對唯一 PID 與完整路徑後，才把數字代入：
kill -KILL <VERIFIED_PID>

重新啟動時，先讓 Maka 的恢復程序檢查持久狀態，再取得收據。合理結果可能是修復出一個終止事件，也可能把不確定邊界停放；兩者都比直接重做一個可能已送出的遠端付款、部署或刪除動作安全。

Apache Maka 安全續跑：/resume與--resume差在哪？

這是最容易踩的命名陷阱。依目前 CLI 原始碼，maka --resume <session-id>偏向重新開啟既有 Session；maka run --resume <session-id> "新提示"是對相容 Session 加一個新 Turn；--continue則挑選目前工作目錄下最近的相容任務。它們都不能拿來證明「被中斷的那個 Turn 從安全邊界續跑」。

要驗證中斷 Turn 的 Safe Resume，先明確開啟目前預設關閉的功能旗標，再進 TUI 使用 /resume：

cd ../trial-b
MAKA_DEV_CLI="/absolute/path/to/source/packages/cli/dist/dev-cli.js"
MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 \
  node "$MAKA_DEV_CLI" --resume <SESSION_ID>

# 進入同一 Session 後，在 TUI 輸入
/resume

官方Resume 架構文件描述的核心順序是：讀取已提交的事件高水位、驗證工具結果與權限是否閉合、核對工作目錄／Workspace／工具目錄，再建立新的 Run／Invocation／Turn，持久化 continuation-start，最後才呼叫模型。這次呼叫會消耗 Token，而且不會復活舊的 JavaScript Stack、Provider Stream 或 OS Process。

你要量測三個結果：第一，lab-output/step-1.txt是否被重寫；第二，續跑後是否重複出現同一個外部副作用；第三，從 continuation_started到新終止事件之間增加了多少事件與模型用量。若 Planner 回報 park，先看是未決權限、缺少 Tool Result、Workspace 不符還是工具不可用；不要用新 Prompt 強迫它「無論如何繼續」。

Apache Maka 權限與 Credential Vault 怎麼驗收？

目前內部權限模式是 explore、ask、bypass，分別編譯成 read-only、workspace-write 與 danger-full-access；介面軌跡會用 Read only／Auto／Full access 等較白話標籤呈現，而目前一般選擇器主要讓使用者切換 Auto 與 Full access。本文只用預設詢問模式；非互動式 maka run無法彈出沙箱擴權提示，沒有明確 --yolo時會拒絕越界。--yolo代表完整檔案系統與網路能力，不是「少問幾次」而已。

更重要的是，官方安全模型把 Permission Engine 定位成使用者體驗與政策控制；面對惡意模型時，真正的外層強制邊界仍是作業系統與受管沙箱。看到「Agent 有先問」不代表它已成為完整資安隔離。

Vault 只看權限，不要把內容印到 Terminal

目前主 README 明確寫出：模型連線祕密放在本機明文 credential-vault.json，依賴 OS 帳號邊界；POSIX 寫入會使用 owner-only 權限與原子替換，它不是 Keychain，也不是加密儲存。原始碼中仍可看到其他 Credential 儲存路徑，所以不要宣稱「所有憑證只在唯一一個檔案」。

VAULT="/absolute/path/to/Maka Dev/workspaces/default/credential-vault.json"

# macOS：只顯示 mode、owner、路徑
stat -f '%Sp %Su %N' "$VAULT"

# Linux：只顯示 mode、owner、路徑
stat -c '%A %U %n' "$VAULT"

驗收目標是「只有目前 OS 帳號可讀寫」，不是把 Vault 打開確認 Key 長什麼樣。收據只記檔案權限是否符合預期、測試 Profile 名稱與檢查時間；不要記檔案內容、雜湊、Provider Header 或 Token。實驗結束後，先在 Maka 設定中移除測試連線，再刪除整個拋棄式 OS 帳號或 VM，會比手動挑檔案清理更可靠。

判定成功的 6 條規則：自動續跑不是唯一及格答案

1. 事件序號連續：同一 Invocation 內沒有倒退或重複的 event_seq。
2. 呼叫與結果閉合：每個已接受 Tool Call 都有對應結果，或恢復流程明確把不確定狀態停放。
3. 權限不靠猜：未決 Permission 不會在重新啟動後自動變成允許。
4. 續跑建立新 Run：來源關係仍可追，但不假裝舊 Process 從記憶體復活。
5. 副作用沒有盲目重做：檔案、部署、付款或遠端 API 若無法證明冪等，就拒絕自動重播。
6. 收據不帶祕密：分享的 Artifact 只有事件種類、順序、布林決策與環境版本，不含完整 Payload 或 Vault。

這組規則的重點不是替 Maka 打分，而是把「我覺得它有續跑」改成可反駁的驗收條件。若你想進一步做多 Agent 或 Runtime 評測，可接著讀 Cloudflare OS Agent Workspace，再到 AlphaLab 課程把環境隔離、工具邊界與回歸測試串成完整工作流。

常見問題：Apache Maka 中斷、續跑與安全

1. 現在可以直接安裝 maka-agent@next嗎？

截至 2026 年 8 月 30 日，不應把它當成可用路徑。官方 CLI README 仍列出該命令，但 live npm registry 當天沒有 next dist-tag；同時主 README 建議在核准 Apache Release 出現前從原始碼建置。

2. GitHub Releases 上的檔案算 Apache 正式版嗎？

不算。這個否定不是推測，而是專案目前 README 的明確聲明：現有 Registry 與 Repository 產物是在孵化前後建立，未經 Incubator PMC 審閱與投票。

3. Event Log 能完整重建供應商的原始 API 請求嗎？

不能把它當成逐位元網路封包檔。Runtime Event 是供 Maka 重播與投影的語意事實；部分 Provider Metadata 會保留，但它的承諾不是保存完整 Wire Request。

4. /resume會保證 Tool 永遠不重複執行嗎？

不會對任意 Bash 或遠端 API 提供通用 Exactly-once 保證。目前設計會在能證明的安全邊界延續，遇到模糊副作用則應停放；真正的防重仍需工具本身提供冪等鍵、交易紀錄或對帳流程。

5. Agent 有跳權限提示，就代表被安全隔離了嗎？

不代表。提示是重要的政策控制，但官方 Security Model 仍把 OS 與 Sandbox 視為對抗惡意模型的外層強制邊界。正式資料要靠最小權限與獨立環境隔離。

6. Credential Vault 有加密嗎？

目前模型連線 Vault 不是 Keychain 或加密儲存。官方說明是本機明文檔案、由 OS 帳號權限保護；因此本文才要求使用測試憑證與拋棄式 Profile。

7. 沒有模型 API Key，也能完成這篇 Apache Maka 教學嗎？

可以完成來源建置、CLI Help、Schema 與官方測試層驗收，但不能宣稱跑過真實模型 Turn。等你已經有合規、獲授權的測試連線，再補做 A／B／C 三組；不要為了文章臨時購買或外借憑證。

8. 哪一種結果最值得回報給 Maka 專案？

能用固定 Commit、最小 Fixture 與移除祕密的事件收據重現的結果。回報版本、OS、Node、觸發步驟、預期邊界與實際事件種類；不要附 runtime.sqlite、Vault、完整 Prompt 或客戶檔案。

給新手的 5 個重點

• 先鎖 Commit 與發布狀態，再複製安裝指令。
• 用只有兩個可驗證副作用的小任務，不用大型正式專案。
• 分開測正常完成、有序中止與程序崩潰。
• 分清楚 Session reopen、新 Turn 與 Safe Resume。
• 把 park 視為安全決策之一，並只分享移除祕密的收據。