本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。英文原文

以 AX Code 進行長時間工作

狀態：有效範圍：目前狀態上次審閱：2026-09-13 負責人：AX Code 維護者

AX Code 把單次互動式超長執行限制在 72 小時。若要運作數天或數週，請執行受監督的 ax-code serve 行程，並把工作分成可持久的排程發生項。監督程式會重新啟動伺服器；專案資料庫會保留排程與佇列狀態。

持久的互動工作區

若本機工作應在關閉終端機後繼續，請選擇加入專案執行環境：

ax-code runtime start --dir /absolute/path/project
ax-code runtime attach --dir /absolute/path/project --continue
ax-code runtime status --dir /absolute/path/project
ax-code runtime list                  # every managed runtime on this machine
ax-code runtime stop --dir /absolute/path/project

沒有執行環境時，runtime attach 也會啟動它。執行環境以正規化的專案目錄為鍵；同時啟動會重用同一個行程。TUI 會顯示其執行主機與 中斷連線 動作。中斷連線會關閉用戶端，並讓已接受的工作繼續執行。runtime stop 會關閉該專案的執行環境，並中斷其進行中的工作。一般的 ax-code 仍維持既有的前景生命週期。

工作階段忙碌時送出、且已被接受的後續工作會存在伺服器上。預設會在進行中的回合結束後才開始，因此無關的請求不會打亂進行中的工作。若要改為修正進行中的回合，請在只有文字的草稿上按 ctrl+s（input_submit_steer，位於 keybinds）：文字會被納入作用中的生成，並在迴圈的下一個步驟邊界寫成使用者訊息，也就是進行中的工具呼叫安頓之後、下一次模型請求之前。若在回合即將結束時納入修正，執行會延長一個迭代，而不是被捨棄。導向是盡力而為：若已沒有作用中的生成，草稿會走一般路徑送出；若 hook 否決它，草稿會連同原因留在撰寫區。帶有附件與斜線指令的草稿一律使用後續佇列。其他用戶端也可透過控管層控制所述的導向 API 使用相同的遞送。已儲存的後續工作也可以事後導向：在空白撰寫區按 ctrl+s，會依序提升佇列中可導向的前綴，並停在第一個不可導向的列；側邊欄的後續區段與 /queue 對話框提供相同的逐列立即導向動作。已暫停的列可以就地導向——中斷回合會暫停等待中的後續工作，導向其中一項只遞送其文字，不會恢復佇列的其餘部分。只有非後續列（已排入的斜線指令、shell 指令）、帶附件的列、空白或過大的文字，以及已在執行或已完成的列，才是障礙。被導向的列會以 steeredInto 稽核軌跡取消，並留在 /queue 歷史中可見。沒有作用中的生成時，立即導向會退回把該列優先排到佇列前端——它仍只在回合結束後才開始。撰寫區只在收到確認後才清除。重新連上同一個工作階段，並用 /queue 檢查、暫停、編輯、恢復或取消它們。編輯會先暫停該項目，並保留附件與模型選擇；儲存不會恢復它。同時發生的過期編輯會被拒絕。在 /queue 中，Ctrl+R 包含已完成與已取消的歷史。較窄的終端機也會顯示可按的 Follow-ups 標題。中斷連線的檢視是快取的，不能變更項目。中斷作用中的回合會暫停待處理的後續工作，以免它們立刻開始另一個回合。準備好時請明確恢復它們。

後端重新啟動後，已接受且等待中的後續工作可以恢復。被該次重新啟動打斷的一般進行中提示會標成失敗，重試前必須檢查；還原佇列紀錄並不會還原正在執行的 shell 行程。遺失的確認可在該用戶端工作階段期間，以相同的請求身分從未變更的撰寫區重試。未儲存的草稿不是已接受的工作，而且這並不保證外部效果恰好一次。

此模式不會安裝登入服務、不會自動重新啟動崩潰的伺服器，也不會在主機睡眠或關機時執行。崩潰後請再次啟動或連上；無人值守的伺服器重新啟動請用下方的受監督服務範例。SSH 使用者應在清醒的遠端主機上執行執行環境，並在那裡連上。不要公開暴露 HTTP 連接埠。

執行環境探索會在 AX Code 狀態目錄的 runtime/ 資料夾下儲存私有能力憑證與記錄。狀態輸出會省略該能力憑證。關閉需要已驗證且相符的執行環境身分，不只是已儲存的 PID。即時行程不可用、紀錄損毀或版本不符時必須檢查；CLI 會拒絕終止未驗證的行程。升級前請先停止健康的執行環境，再用新的可執行檔重新啟動它。

可靠性模型

事件	行為
到期發生項被提交前，後端就結束	該發生項仍為到期
排程到佇列的交易提交後，後端才結束	啟動時會恢復同一個已排入的項目
提示開始後，後端才結束	被打斷的項目標成失敗，不會自動重放
主機錯過數次發生項	`run_once` 把它們合併成一次執行；`skip` 會前進而不執行
佇列執行超過期限	執行器取消工作階段，並記錄失敗的佇列項目
監督程式看到伺服器結束	下方範例會在短暫延遲後重新啟動它

這是不怕重複的復原，而不是對任意外部效果的恰好一次遞送。寫入外部系統的整合仍應使用自己的冪等鍵。

安裝服務之前

以將執行服務的同一個使用者安裝並測試 ax-code 可執行檔。
選擇一個絕對專案路徑。把它設為 AX_CODE_PROJECT，讓伺服器啟動時預熱該專案並啟動其排程器。
讓伺服器維持在 127.0.0.1；AX Code 的伺服器僅限本機。
把供應商憑證放在監督程式受保護的環境中，而不是放進已提交的服務檔。
替換所選範例中的每個 /absolute/path/... 佔位符。

範例使用固定連接埠，讓 Desktop 或 SDK 用戶端可以重新連接：

ax-code serve --hostname=127.0.0.1 --port=4096

systemd 使用者服務

把 systemd 範例複製到 ~/.config/systemd/user/ax-code.service，替換其絕對路徑，並可選擇把憑證放在 ~/.config/ax-code/server.env。

chmod 600 ~/.config/ax-code/server.env
systemctl --user daemon-reload
systemctl --user enable --now ax-code.service
systemctl --user status ax-code.service
journalctl --user -u ax-code.service -f

只有在你的作業原則允許使用者服務在使用者登出後繼續執行時，才使用 loginctl enable-linger "$USER"。

launchd 代理程式

把 launchd 範例複製到 ~/Library/LaunchAgents/com.axcode.server.plist，替換其絕對路徑，然後驗證並載入：

plutil -lint ~/Library/LaunchAgents/com.axcode.server.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.axcode.server.plist
launchctl kickstart -k "gui/$(id -u)/com.axcode.server"

launchd 不會在 ProgramArguments 中展開 shell 變數。請使用絕對路徑，並透過操作者管理的機制提供所需憑證。

PM2

複製 PM2 範例，替換其路徑，然後啟動：

pm2 start docs/examples/ax-code-ecosystem.config.cjs
pm2 save
pm2 logs ax-code-server

若行程必須在主機重新開機後回來，請遵循 PM2 依平台而異的啟動說明。

期限、追趕與復原

排程工作預設為 catchUpPolicy: "run_once"。停機之後，AX Code 會執行一次合併的發生項，而不是建立無界的積壓。若延遲的工作會造成誤導或不安全，請選擇 "skip"。

每個排程工作可以把 maxRunDurationMs 設為 1 秒到 72 小時。否則工作佇列執行使用 72 小時上限。作用中的項目每 30 秒更新一次心跳時間戳，終端狀態與錯誤細節仍留在專案資料庫。

非同步提示、指令與 shell 端點會在 HTTP 202 回應中回傳可持久的佇列項目。用戶端應保留其 id，並輪詢 GET /task-queue/:id，直到 completed、failed 或 cancelled；僅被接受並不表示完成。

啟動時，持久的 AX Code 後端會恢復已提交但尚未開始的排程佇列項目，以及明確標記的非同步項目。單次 CLI 指令不會取得那些項目的擁有權。已經開始的提示工作會以重新啟動說明標成失敗，讓操作者能在重試前檢查副作用。

查看排程工作在做什麼

每個排程工作的發生項在進行時都看得到，事後也可稽核：

開始、完成、失敗、略過，以及持續失敗的自動暫停，各自會產生點名該工作的應用程式內通知。
/schedule TUI 指令列出每個工作的狀態、排程、下次執行時間與最後錯誤，並開啟其近期執行歷史。從那裡可以暫停、恢復、立即執行、刪除（按 ctrl+d 兩次以確認），並跳到某次執行產生的工作階段。agent 的 list_scheduled_tasks 與 list_scheduled_task_runs 工具能以對話方式回答相同問題。
每次執行都在標題為該工作標題的新工作階段中執行，因此即使錯過通知，結果也只距工作階段清單一個項目。
若某次執行在你查看其他對話時要求權限或問題回答，警告通知會指出需要你的工作階段；/attention 列出已知的待處理請求，並開啟提出請求的工作階段。可以在該工作階段或已載入祖先的檢視中回答請求，包括子工作階段與孫工作階段。開啟請求絕不會自動核准它。
一次性工作只在成功執行後才停用。失敗的發生項會以有界退避重試，重複失敗會暫停該工作並通知——提醒不再能悄悄消失。

操作檢查

注意監督程式的重新啟動次數與伺服器記錄。
重試前檢查失敗的工作佇列項目與排程工作錯誤。
確認專案 SQLite 資料庫與記錄有足夠磁碟空間。
變更憑證、模型或服務路徑後，手動練習一次 立即執行。
透過監督程式停止，讓 AX Code 收到 SIGTERM；範例允許最多 90 秒的優雅關閉。

/loop 刻意只存在於行程內，重新啟動後不會留下。無人值守的持久工作請使用排程工作。

在平行工作階段之間導覽

終端機寬度達 146 欄或更寬時，左側導覽側邊欄會顯示目前工作區中的工作階段及其已載入的子 agent。用其 + 控制項展開一列，並按一下標題以開啟。已釘選的工作階段保持其順序與捷徑號碼。完整活動標籤區分工作中、重試中、核准與問題；父層也會反映子代的請求。這些標籤並不表示工作已通過驗證。既有的右側邊欄保留目前工作階段的上下文與控制項。

專案標題指出目前目錄。按一下它或使用 /navigation-info 可看完整專案路徑與目前工作階段標題。近期顯示已載入的工作階段；作用中保留工作中或等待中的工作階段樹，以及目前的工作階段樹。篩選與導覽選擇器共用並會被記住。用 /navigation-filter 從鍵盤切換它。中斷連線期間它顯示已快取的工作階段，而不是推斷哪些工作階段正在作用。清除（或 /navigation-clear）會要求確認，然後只從左側欄與導覽選擇器隱藏歷史列。它不會刪除工作階段；/sessions 仍會列出它們。目前工作階段樹、已釘選的工作階段，以及觀察到的工作中或等待中的樹會留在側欄。從 /sessions 開啟工作階段會把它帶回清單。

使用 /navigation-width 或導覽的寬度動作，選擇 20、24、28、30、32、36 或 40 欄（預設 28）。右側工作階段側邊欄有相同的寬度動作與 /sidebar-width（預設 32）。兩項偏好都會被記住，並在需要時自動縮小，以保留主要內容。在寬終端機上用 /navigation 隱藏或還原左側導覽欄。/sidebar 以相同方式隱藏或還原右側工作階段側邊欄。在較窄的終端機上，/navigation 會改為開啟工作階段與 agent 選擇器。只要導覽欄不在，可見的工作階段列就提供相同動作。已知請求需要輸入時會出現其待處理動作；中斷連線期間星號標記已快取的計數。/sessions 繼續開啟一般的工作階段選擇器。/attention 在每種寬度都可用。中斷連線期間，其清單會標成已快取；仍可開啟已快取的項目，但請求可能已在別處被回答。側邊欄的已知請求動作會開啟已知工作區中的待處理請求，而其工作階段樹仍限定於目前專案。這些檢視都受限於已連接的執行個體與已載入的工作階段資料；此計數不是其他伺服器或未載入工作區的完整清單。

未送出的草稿依執行中 TUI 內的專案與工作階段隔離。切換工作階段會保留文字、附件、游標位置與 shell 模式；返回時還原相符的草稿。這些草稿只在記憶體中，關閉 TUI 後不會留下。

選用的完成通知現在會說 Session idle。它跟隨所檢視工作階段子樹中觀察到的工作，並等待觀察到的作用中子代明確閒置，且沒有待處理請求。中斷連線、重新同步、缺少狀態、錯誤與取消可以抑制該通知。它是生命週期通知，不是測試已通過或目標已完成的證據。

新工作與設定

一般啟動會開啟新工作的工作介面，含底部撰寫區與工作階段導覽。開啟它或輸入草稿並不會建立已儲存的工作階段；工作階段在你送出時才建立。使用 /sessions 或左側導覽以接續既有工作。明確的 --session、--continue 與 --prompt 行為仍然可用；啟動不會啟用自動接續。

供應商設定不會自動開啟。沒有設定供應商時，請使用工作區中可見的 /connect 動作。已設定供應商但沒有選到有效模型時，該動作會變成 /models。供應商探索失敗會指向 /status；/connect 與 /providers 仍可用來修復設定。選到的模型是設定選擇，不是憑證或執行環境就緒檢查。這些提示也會出現在設定需要注意的回訪使用者身上。