實作 ACP Thread Bound Agents：讓 AI 代理在 Discord 執行緒中穩定運作

你是否遇過這種狀況：想在 Discord 建立一個 AI 程式碼助理，但對話一長，上下文就開始混亂，或者服務重啟後，AI 就忘了原本在 thread 裡處理到一半的任務。處理長時程的 agent session 往往很痛苦，尤其是要確保訊息不漏接、不重複發送，還要能隨時恢復狀態。

這篇文章會帶你了解 OpenClaw 如何透過 ACP (Agentic Control Protocol) 解決這些問題，讓你的 agent 在 thread 中跑得更穩。

What You’ll Need

• 支援 Discord 頻道與 thread 功能的 OpenClaw 環境
• acpx 插件（作為首個 ACP runtime 服務）
• SQLite 儲存空間（用於存放專用的 ACP 控制平面狀態）
• 具備 Webhook 權限的 Discord bot 設定

Quick Start

OpenClaw 將 ACP 視為一等公民，你不需要手動處理複雜的路由邏輯，只需跟著以下步驟：

1. 啟動並綁定：在 Discord thread 中啟動一個 ACP session，系統會自動建立 thread 與 session 的綁定關係。
2. 聚焦目標：使用 /focus 指令將目前的 thread 鎖定到特定的 ACP session。
3. 訊息路由：你在該 thread 發送的訊息會自動路由到綁定的 ACP session，不需要額外配置。
4. 串流輸出：Agent 的輸出會透過 Webhook 自動串流回同一個 thread。
5. 結束與清理：任務完成後，使用 /unfocus 或透過 thread 歸檔 (archive) 來觸發自動清理。

技術架構要點

我們推薦使用混合架構來處理 ACP 代理，這能確保系統的穩定性：

• 控制平面 (OpenClaw Core)：負責管理 session 身份、thread 路由決策以及生命週期狀態（如 creating, idle, running, cancelling, closed, error）。
• 運行時適配器 (Runtime Adapters)：以插件形式存在（例如 acpx），專注於處理 ACP 的傳輸、排隊、取消與重新連線。
• 持久化模型：ACP 狀態會獨立存儲在 SQLite (WAL mode) 中，所有的事件都是 append-only，這讓系統在崩潰後能進行確定性的恢復與重播。

Troubleshooting

• 重複的 Discord 輸出：OpenClaw 內建了冪等性 (idempotency) 檢查。即使指令因為網路問題重試，系統也會確保不會產生重複的 run 或重複的 Discord 回覆。
• 重啟後綁定遺失：系統擁有持久化的 binding store，在啟動時會自動恢復之前的綁定狀態。
• 路由失效或錯誤：請檢查 thread 綁定目標是否正確設定為 acp。如果 metadata 出現缺口，系統會立即觸發 fail-closed 檢查以防止錯誤路由。
• Session 無法關閉：你可以手動使用 /unfocus 指令，或者檢查 thread 是否已被刪除或歸檔，系統通常會隨之觸發 unbind 生命週期。

如果你在配置過程中遇到任何問題，可以直接詢問我們的 AI Setup Assistant。

What’s Next

• Unified Runtime Streaming Refactor Plan
• 探索 /focus 與 /unfocus 的進階流程

你是否遇過這種情況：開發 Agent 時，只要網路稍微斷一下或進程重啟，整個執行狀態就消失了？處理長連接和異步任務總是讓人頭痛，特別是當你需要確保每個訊息都能精準送達，又不想讓系統變得笨重。我們在設計 OpenClaw 的 ACP (Agent Control Protocol) 時，核心目標就是解決這些關於穩定性與狀態管理的難題，讓你在構建複雜 Agent 時不需要從頭處理進程監控或斷線重連。

What You’ll Need

在深入架構之前，請確保你已經了解或準備好以下組件：

• OpenClaw Core (負責回覆管線與持久化)
• acpx 插件後端 (負責 Runtime Worker 監控)
• SQLite (需支援 WAL 模式)

Quick Start

要快速掌握 ACP 的運作邏輯，你可以按照這四個關鍵維度來理解：

1. 邊界模型 (Boundary Model)：區分 Core 與 Plugin。Core 處理 ACP Session 模式的調度、遞送仲裁和持久化；acpx 則負責進程調用、事件解析和 /acp 指令處理。
2. Runtime 擁有權：由一個 Gateway 進程擁有 ACP 的編排狀態。ACP 的執行是在受監控的子進程中運作。這種進程策略是基於 Session Key 長期存在的，而不是針對每條訊息重新啟動，這樣可以省下啟動成本。
3. 核心 Runtime 合約：透過定義標準介面，讓路由代碼不依賴 CLI 細節，切換後端時不需要修改調度邏輯。
4. 資料持久化：所有的狀態（Session, Runs, Events）都儲存在 SQLite 中，確保當 Gateway 重啟時可以自動恢復。

核心架構詳解

Core Runtime 合約

這是 ACP 的核心介面，定義了 Gateway 如何與不同的 Runtime 後端互動：

export type AcpRuntimePromptMode = "prompt" | "steer";

export type AcpRuntimeHandle = {
  sessionKey: string;
  backend: string;
  runtimeSessionName: string;
};

export type AcpRuntimeEvent =
  | { type: "text_delta"; stream: "output" | "thought"; text: string }
  | { type: "tool_call"; name: string; argumentsText: string }
  | { type: "done"; usage?: Record<string, number> }
  | { type: "error"; code: string; message: string; retryable?: boolean };

export interface AcpRuntime {
  ensureSession(input: {
    sessionKey: string;
    agent: string;
    mode: "persistent" | "oneshot";
    cwd?: string;
    env?: Record<string, string>;
    idempotencyKey: string;
  }): Promise<AcpRuntimeHandle>;

  submit(input: {
    handle: AcpRuntimeHandle;
    text: string;
    mode: AcpRuntimePromptMode;
    idempotencyKey: string;
  }): Promise<{ runtimeRunId: string }>;

  stream(input: {
    handle: AcpRuntimeHandle;
    runtimeRunId: string;
    onEvent: (event: AcpRuntimeEvent) => Promise<void> | void;
    signal?: AbortSignal;
  }): Promise<void>;

  cancel(input: {
    handle: AcpRuntimeHandle;
    runtimeRunId?: string;
    reason?: string;
    idempotencyKey: string;
  }): Promise<void>;

  close(input: { handle: AcpRuntimeHandle; reason: string; idempotencyKey: string }): Promise<void>;

  health?(): Promise<{ ok: boolean; details?: string }>;
}

控制平面資料模型

為了確保崩潰後的安全恢復，我們使用 SQLite (WAL 模式) 作為長期事實來源。以下是關鍵的資料表結構：

• acp_sessions: 儲存 Session 的狀態、後端配置與路徑。
• acp_runs: 追蹤每一次執行的狀態與錯誤訊息。
• acp_bindings: 管理 Thread, Channel 與 Session 之間的綁定關係。
• acp_events: 記錄所有的事件序列 (seq) 與 Payload。
• acp_delivery_checkpoint: 紀錄已遞送到外部平台（如 Discord）的事件進度。
• acp_idempotency: 確保操作的冪等性，避免重複執行。

對應的 Session 元資料定義如下：

export type AcpSessionMeta = {
  backend: string;
  agent: string;
  runtimeSessionName: string;
  mode: "persistent" | "oneshot";
  cwd?: string;
  state: "idle" | "running" | "error";
  lastActivityAt: number;
  lastError?: string;
};

路由與遞送邏輯

當訊息進來時，Gateway 會先檢查 Thread 綁定。如果目標是 ACP Session，則會進入 ACP Runtime 分支，而不是一般的 getReplyFromConfig。

在輸出端，ACP 事件流會被標準化為 OpenClaw 的回覆區塊。為了遵守 Discord 的速率限制，我們實施了串流策略：

• 使用合併窗口 (Coalescing Window) 輸出部分內容。
• 可配置最小間隔與最大區塊大小。
• 完成或失敗時，必定會發送最終訊息。

狀態機與事務邊界

系統嚴格遵守事務邊界，不允許出現部分成功的情況：

• Spawn 事務：建立 Session 行、更新綁定、並將初始 Run 入隊。
• Close 事務：標記 Session 關閉、刪除或過期綁定、寫入最終關閉事件。
• Cancel 事務：帶上 Idempotency Key 標記目標 Run 為取消中。

Session Actor 模型

AcpSessionManager 為每個 Session Key 運行一個 Actor：

• Actor 信箱會序列化 submit, cancel, close 與 stream 的副作用。
• 確保事件按順序 (seq) 寫入資料庫後，才進行外部遞送。
• 在成功發送後更新遞送檢查點 (Checkpoints)，防止重複或亂序輸出。

生命週期與安全控制

你可以透過以下指令控管生命週期：

• /acp cancel: 取消當前執行。
• /unfocus: 解除 Thread 綁定。
• /acp close: 關閉 ACP Session。

為了系統安全，我們加入了多重控制：

• 透過名稱白名單限制可用的 ACP Agent。
• 限制 ACP Session 的工作空間根目錄 (Workspace Roots)。
• 設定環境變數白名單。
• 限制每個帳號或全局的併發 Session 數量。

Troubleshooting

如果你在使用過程中遇到問題，可以參考以下常見情況：

• 問題：綁定存在但 ACP Session 遺失
  • 解決方案：系統會回傳明確的 stale-binding 錯誤。我們不會將過期的 ACP 綁定靜默轉發到普通的 LLM 路徑，以確保操作安全。
• 問題：Gateway 重啟後執行中斷
  • 解決方案：Gateway 啟動時會自動載入所有非終止狀態（如 creating, running）的 Session，並根據檢查點恢復遞送。

AI Setup Assistant

What’s Next

• 了解如何開發 acpx 插件後端
• 配置 Discord 串流限制參數
• 深入研究 SQLite WAL 模式優化
• 查看所有 ACP 指令列表

如果你曾經在深夜調試系統，卻發現 Session 數量莫名其妙失控，或者訊息串接（streaming）的反應速度不如預期，你一定懂那種想把設定檔翻爛的痛苦。要把 Agent 跑得穩，不能只靠運氣，你得精確掌控每一個配置開關。

這篇指南整理了 ACP (Agent Control Plane) 的所有 Config surface，讓你清楚知道哪些參數能幫你搞定生產環境的疑難雜症。

What You’ll Need

在開始調整配置前，請確保你具備以下條件：

• 存取系統配置文件的權限
• 對 ACP 基礎架構的初步了解

Quick Start

你可以透過編輯配置文件來調整 ACP 的行為。以下是源文檔中定義的所有可用參數，分為核心參數與插件特定參數。

Core keys

這些是控制 ACP 全局行為的核心鍵值：

• acp.enabled: 開啟或關閉 ACP 功能。
• acp.dispatch.enabled: 獨立的 ACP 路由切斷開關 (Kill switch)。
• acp.backend: 指定使用的後端，預設為 acpx。
• acp.defaultAgent: 系統預設呼叫的 Agent。
• acp.allowedAgents[]: 允許使用的 Agent 清單。
• acp.maxConcurrentSessions: 限制系統最大併發 Session 數量。
• acp.stream.coalesceIdleMs: 串流合併的空閒時間，影響訊息輸出的頻率。
• acp.stream.maxChunkChars: 每個串流 Chunk 的最大字元長度。
• acp.runtime.ttlMinutes: Runtime 的存活時間（分鐘）。
• acp.controlPlane.store: 儲存機制，預設使用 sqlite。
• acp.controlPlane.storePath: 儲存檔案的具體路徑。
• acp.controlPlane.recovery.eagerActors: 設定需要積極恢復的 Actor。
• acp.controlPlane.recovery.reconcileRunningAfterMs: 運行中狀態的對帳（Reconcile）延遲時間。
• acp.controlPlane.checkpoint.flushEveryEvents: 每累積多少個事件後強制刷新 Checkpoint。
• acp.controlPlane.checkpoint.flushEveryMs: 每隔多少毫秒強制刷新 Checkpoint。
• acp.idempotency.ttlHours: 冪等性（Idempotency）記錄的存活時間。
• channels.discord.threadBindings.spawnAcpSessions: 當 Discord 頻道綁定時，是否產生對應的 ACP Session。

Plugin/backend keys (acpx plugin section)

如果你使用的是 acpx 插件，還可以針對後端進行更細緻的控制：

• backend command/path overrides: 允許你覆寫後端執行的指令或路徑。
• backend env allowlist: 設定允許傳遞給後端的環境變數白名單。
• backend per-agent presets: 針對個別 Agent 設置不同的預設配置。
• backend startup/stop timeouts: 調整後端啟動與停止的超時限制。
• backend max inflight runs per session: 限制每個 Session 中同時進行的最大運行數。

Troubleshooting

由於源文檔未提供具體的錯誤案例，建議你在調整 acp.maxConcurrentSessions 或 acp.runtime.ttlMinutes 時，密切監控你的系統資源佔用情況。

如果你在設定過程中遇到任何問題，可以直接詢問我們的 AI 助手： AI Setup Assistant

What’s Next

• 深入了解 acpx 插件的進階用法
• 探索 Discord 頻道綁定的詳細配置

開發 Agent 系統最讓人頭痛的通常不是寫 Prompt，而是如何管理那些混亂的 Session 狀態。當你遇到網路斷線、系統重啟或是重複發送的指令時，如果沒有一個強大的控制平面（Control-plane），整個系統就會像斷線的風箏一樣失控。

我們需要一套嚴謹的規範來確保每一條指令都能精準送達，且狀態永遠保持一致。這份文件會帶你走過 ACP (Agentic Control Plane) 的核心實作細節，讓你不再為狀態同步而煩惱。

What You’ll Need

• src/acp 核心目錄結構
• SQLite 資料庫（用於 store.ts 狀態管理）
• Discord 整合環境（用於監控與執行緒綁定）
• acpx runtime 插件

Quick Start

要在你的系統中啟動 ACP，請遵循以下核心路徑：

1. 建立控制平面模組：在 src/acp/control-plane/ 下實作 manager.ts 和 store.ts，負責處理 Actor 生命週期與 SQLite 交易。
2. 註冊 Runtime Backend：使用 src/acp/runtime/registry.ts 提供的 API 註冊 acpx 或是其他自定義的 Backend。
3. 配置 Session Schema：更新 SessionEntry 以包含 SessionAcpMeta，並按照 Phase A 到 D 的順序進行遷移。
4. 開啟 Dispatch 開關：在設定中將 acp.dispatch.enabled 設為 true（建議在測試環境先驗證）。

---

核心實作細節

Control-plane 模組 (新增)

你需要在核心層級加入專門的 ACP 控制平面模組：

• src/acp/control-plane/manager.ts：擁有 ACP actors、生命週期轉換與指令序列化。
• src/acp/control-plane/store.ts：SQLite Schema 管理、交易處理與查詢輔助工具。
• src/acp/control-plane/events.ts：定義強型別的 ACP 事件與序列化邏輯。
• src/acp/control-plane/checkpoint.ts：持久化的交付檢查點與 Replay 遊標。
• src/acp/control-plane/idempotency.ts：冪等性金鑰（Idempotency Key）預留與回應重播。
• src/acp/control-plane/recovery.ts：開機時的對帳與 Actor 重新掛載計畫。

相容性橋接模組：

• src/acp/runtime/session-meta.ts：暫時保留用於投射到 SessionEntry.acp，在遷移完成後必須停止作為 Source-of-truth。

必須遵守的程式約束 (Invariants)

在撰寫程式碼時，你必須強制執行以下規則：

• ACP session 建立與 Thread 綁定必須是原子操作（單一交易）。
• 每個 ACP session actor 同一時間最多只能有一個活動中的 Run。
• 每個 Run 的事件 seq 必須嚴格遞增。
• 交付檢查點（Delivery Checkpoint）絕對不能超過最後一個已提交的事件。
• 冪等性重播對於重複的指令金鑰，必須回傳之前的成功 Payload。
• 過期或遺失的 ACP 元資料（Metadata）不能路由到正常的非 ACP 回覆路徑。

核心觸點 (Core Touchpoints)

你需要修改以下核心檔案：

• src/auto-reply/reply/dispatch-from-config.ts：ACP 分支呼叫 AcpSessionManager.submit 與事件投射交付；移除會繞過控制平面約束的直接 ACP Fallback。
• src/auto-reply/reply/inbound-context.ts：暴露標準化的路由金鑰與 ACP 控制平面的冪等性種子。
• src/config/sessions/types.ts：保持 SessionEntry.acp 作為僅供投射的相容性欄位。
• src/gateway/server-methods/sessions.ts：Reset/Delete/Archive 操作必須呼叫 ACP Manager 的 Close/Unbind 交易路徑。
• src/infra/outbound/bound-delivery-router.ts：針對 ACP 綁定的 Session 執行 Fail-closed 行為。
• src/discord/monitor/thread-bindings.ts：加入 ACP 過期綁定驗證工具，並連接到控制平面的查詢介面。
• src/auto-reply/reply/commands-acp.ts：將 Spawn/Cancel/Close/Steer 透過 ACP Manager API 進行路由。
• src/agents/acp-spawn.ts：停止 Ad-hoc 的元資料寫入，改為呼叫 ACP Manager 的 Spawn 交易。

明確不替換的檔案：

• src/discord/monitor/message-handler.preflight.ts：保留 Thread binding override 行為作為權威的 Session-key 解析器。

ACP Runtime Registry API

新增一個核心註冊模組 src/acp/runtime/registry.ts：

export type AcpRuntimeBackend = {
  id: string;
  runtime: AcpRuntime;
  healthy?: () => boolean;
};

export function registerAcpRuntimeBackend(backend: AcpRuntimeBackend): void;
export function unregisterAcpRuntimeBackend(id: string): void;
export function getAcpRuntimeBackend(id?: string): AcpRuntimeBackend | null;
export function requireAcpRuntimeBackend(id?: string): AcpRuntimeBackend;

行為準則：

• requireAcpRuntimeBackend 在 Backend 不可用時會拋出強型別錯誤。
• 插件服務在 start 時註冊 Backend，在 stop 時取消註冊。

acpx Runtime 插件合約

對於第一個生產環境的 Backend (extensions/acpx)，OpenClaw 與 acpx 透過嚴格的指令合約連接：

• 指令對應範例：
  • Ensure session: acpx --format json --json-strict --cwd <cwd> <agent> sessions ensure --name <name>
  • Prompt turn: acpx --format json --json-strict --cwd <cwd> <agent> prompt --session <name> --file -
• 串流處理：
  • OpenClaw 消費來自 acpx 的 ndjson 事件。
  • text => text_delta/output
  • thought => text_delta/thought

Session Schema 修正

在 src/config/sessions/types.ts 中修正 SessionEntry：

type SessionAcpMeta = {
  backend: string;
  agent: string;
  runtimeSessionName: string;
  mode: "persistent" | "oneshot";
  cwd?: string;
  state: "idle" | "running" | "error";
  lastActivityAt: number;
  lastError?: string;
};

遷移規則：

• Phase A: 雙向寫入（acp 投射 + ACP SQLite 來源）。
• Phase B: 以 ACP SQLite 讀取為主，舊版 SessionEntry.acp 為輔。
• Phase C: 遷移指令將舊版資料補回 ACP SQLite。
• Phase D: 移除輔助讀取，僅保留投射欄位供 UX 使用。

---

Troubleshooting

如果你在實作過程中遇到問題，請參考以下錯誤代碼：

• ACP_BACKEND_MISSING: ACP runtime backend 未配置。請安裝並啟用 acpx runtime 插件。
• ACP_BACKEND_UNAVAILABLE: ACP runtime backend 目前不可用。請稍後再試。
• ACP_SESSION_INIT_FAILED: 無法初始化 ACP session runtime。
• ACP_TURN_FAILED: ACP turn 在完成前失敗。

處理原則：

• 在 Thread 中回傳對使用者友善且可操作的訊息。
• 僅在 Runtime Logs 中記錄詳細的系統錯誤。
• 如果明確選擇了 ACP 路由，絕對不要靜默回退（Fallback）到正常的 LLM 路徑。

---

監控與運維準備

為了確保系統穩定，你必須追蹤以下指標：

• ACP Spawn 成功/失敗次數（按 Backend 與錯誤碼分類）。
• ACP Run 延遲百分位數（排隊等待、Runtime 執行、交付投射時間）。
• Idempotency Replay 命中率。
• Discord 交付重試與 Rate-limit 計數器。

你需要結構化的日誌，並包含 sessionKey, runId, backend, threadId, 與 idempotencyKey。另外，/acp sessions 指令應能顯示狀態、活動中的 Run 以及最後的錯誤訊息。

Rollout 守衛

我們加入了一個獨立的 ACP Dispatch 終止開關：

• acp.dispatch.enabled 預設為 false。
• 當禁用時，ACP Spawn 指令仍可綁定 Session，但 Dispatch 路徑不會啟動。
• 使用者會收到一條明確訊息，告知 ACP Dispatch 依政策已禁用。

想了解更多自動化配置的方式嗎？試試我們的 AI Setup Assistant。

What’s Next

• ACP Runtime API 參考
• Discord 執行緒綁定指南
• SQLite Schema 遷移手冊
• 插件開發 SDK

在開發複雜的 Agent 系統時，你可能遇過這種狀況：Session 狀態難以追蹤、指令行為不一致，或是當系統重啟後，之前的對話脈絡直接消失。處理這些分散的狀態與非同步任務總是讓人頭痛。這份文件會告訴你我們如何透過 ACP (Agent Control Plane) 的新架構來解決這些問題，讓你對 Agent 的控制更加精準。

What You’ll Need

根據源文檔規範，在開始之前請確保你具備以下基礎：

• Discord: 作為 Phase 4 優先支援的 Channel Adapter
• SQLite: 用於 Phase 1 的持久化儲存
• acpx backend adapter: 用於對接 Runtime 合約

Quick Start

如果你想在 5 分鐘內快速上手 ACP，這幾個核心指令是你必須掌握的：

新增指令

• /acp spawn <agent-id> [--mode persistent|oneshot] [--thread auto|here|off]：啟動一個新的 Agent 實例。
• /acp cancel [session]：取消目前的執行任務。
• /acp steer <instruction>：對運行中的 Agent 發送即時引導指令。
• /acp close [session]：關閉並清理 Session。
• /acp sessions：列出所有活躍中的 Session。

現有指令相容性

• /focus <sessionKey>：繼續支援 ACP 目標。
• /unfocus：保持現有語義。
• /session idle 與 /session max-age：取代舊有的 TTL 覆蓋機制。

---

階段性推出計畫 (Phased Rollout)

我們將 ACP 的部署分為七個階段，確保每一層的穩定性。

Phase 0: ADR 與 Schema 凍結

• 發佈 ACP Control-plane 所有權與 Adapter 邊界的新 ADR。
• 凍結資料庫 Schema，包含：acp_sessions, acp_runs, acp_bindings, acp_events, acp_delivery_checkpoint, acp_idempotency。
• 定義穩定的 ACP 錯誤碼、事件合約與狀態轉換守衛。

Phase 1: 核心控制面基礎

• 實作 AcpSessionManager 與每個 Session 的 Actor Runtime。
• 實作 ACP SQLite 儲存與 Transaction Helper。
• 實作 Idempotency（等冪性）儲存與 Replay Helper。
• 建立事件追加與傳遞檢查點（Delivery Checkpoint）模組。

Phase 2: 核心路由與生命週期整合

• 將 Thread-bound 的 ACP 輪次從 Dispatch Pipeline 路由至 ACP Manager。
• 當 ACP 綁定或 Session 異常時，強制執行 Fail-closed 路由。
• 整合 Reset/Delete/Archive/Unfocus 生命週期與 ACP 的 Close/Unbind 事務。

Phase 3: acpx 後端 Adapter 實作

• 根據 Runtime 合約（ensureSession, submit, stream, cancel, close）實作 acpx Adapter。
• 加入後端健康檢查與啟動/關閉註冊機制。
• 將 acpx ndjson 事件標準化為 ACP Runtime 事件。

Phase 4: 交付投影與 Channel UX (Discord 優先)

• 實作具備檢查點恢復功能的事件驅動 Channel 投影。
• 針對串流區塊（Streaming Chunks）實作具備 Rate-limit 感知的 Flush 策略。
• 確保每次 Run 只有唯一一次的最終完成訊息。
• 正式開放 /acp 系列指令。

Phase 5: 遷移與切換

• 引入雙寫機制（Dual-write）至 SessionEntry.acp 與 ACP SQLite。
• 提供舊版 ACP 元資料列的遷移工具。
• 將讀取路徑切換至以 ACP SQLite 為主。

Phase 6: 加固、SLO 與規模限制

• 強制執行並發限制（Global/Account/Session）、隊列策略與超時預算。
• 增加完整遙測、Dashboard 與警報閾值。
• 進行混沌測試，模擬崩潰恢復與重複交付抑制。

---

實作清單與測試計畫

實作檢查清單

• 核心控制面模組與測試。
• DB 遷移與回滾方案。
• ACP Manager API 與 Dispatch 及指令的整合。
• Plugin Runtime Bridge 中的 Adapter 註冊介面。
• 具備檢查點重放功能的 Thread-capable 交付邏輯。
• 針對 Reset/Delete/Archive/Unfocus 的生命週期 Hook。

測試重點

• Unit Tests: 測試 ACP DB 事務邊界（原子性）、狀態機轉換守衛、Actor 序列化與隊列順序。
• Integration Tests: 使用 Fake ACP Adapter 測試確定性的串流與取消行為，驗證重啟後的檢查點恢復。
• Gateway e2e Tests: 測試多輪對話、Gateway 重啟後的 Session 持續性、以及重複指令的等冪性處理。

---

風險與緩解措施

• 重複交付: 透過單一目的地解析器（Destination Resolver）與等冪事件檢查點來解決。
• 運行程序抖動: 採用長效型 Per-session Owners、並發上限與 Backoff 機制。
• Plugin 缺失: 實作明確的錯誤提示與 Fail-closed 路由，不允許隱式回退到一般 Session 路徑。
• 資料損壞: 開啟 WAL 模式，建立備份/還原 Hook 與唯讀診斷模式。

Troubleshooting

如果你在使用中遇到問題，請參考以下源文檔紀錄的解決方案：

• ACP 後端狀態缺失: 系統會產生明確的可操作錯誤訊息，請檢查後端服務是否正常註冊。
• Stale Bindings (過期綁定): 系統會自動偵測並顯式告知，你可以手動清理或依據 Policy 執行自動清理。
• 指令重複執行: 檢查 Idempotency Key。ACP 確保重複的指令嘗試不會建立多餘的 Run 或回覆。

---

Addendum: 程式碼重構細節

為了保持 ACP 路徑的可維護性，我們已經完成了以下重構：

1. 集中化策略評估: 透過 src/acp/policy.ts 共享邏輯。
2. 拆分指令處理器: src/auto-reply/reply/commands-acp.ts 現在僅作為 Router，具體行為拆分至 lifecycle.ts, runtime-options.ts 與 diagnostics.ts。
3. 拆分 Session Manager: 區分為 manager.core.ts, manager.types.ts 與 manager.utils.ts。

想要了解更多關於如何配置你的 Agent 控制面嗎？請諮詢 AI Setup Assistant。

What’s Next:

• 瞭解更多關於 Discord Adapter 的整合
• 深入研究 ACP SQLite Schema
• 查看 Plugin Runtime API 規範