永不眠的代理 (ANS)
在無人值守的情況下,將任務積壓運行至完成,絕不因問題而軟暫停。困難的部分不在於執行工作,而在於狀態持久性 + 具體的暫停與繼續語義 + 反飢餓,因此此技能圍繞此核心構建。可靠性主幹已優先交付(請參閱 BUILD-PLAN.md);更重的多模型審查漏斗則在此之上順序構建,現已建置完成(狀態參見下文「疊加在脊柱上的質量機制」)。
完整的原理說明:
agents-never-sleep-design.md(13 個設計討論串 + 3 次委員會審查)。 MVP 主幹以一個小型 Python 套件實作,位於agents_never_sleep/目錄下(舊的匯入名稱harness在整個 1.x 版本中透過回溯相容墊片仍然可用),並由acceptance/run_acceptance.py(唯一映射到「運行中途停止」痛點的測試)驗證。
自主合約 — 三種不同的狀態,從不混為一談
一個運行對不確定性恰好有三種回應。將它們保持分離;混為一談會使運行倒退回它原本要防止的停滯。
- ASK — 向人類提問。在無人值守時禁止。 不要發出
AskUserQuestion;凌晨 2 點沒有人可以回答,一個問題就會浪費整個運行。這是透過結構而非紀律強制執行的:deny_ask.shPreToolUse 鉤子(匹配器AskUserQuestion,環境變數閘門CLAUDE_UNATTENDED=1)會拒絕該工具並引導你回到 PARK/PROCEED — 這是永不停止保證的鏡像。 - PARK — 延遲此決策或任務,並保持運行繼續到下一個獨立任務。暫停是正常且健康的,不是停止。
- HALT — 停止整個運行。僅在發生鉤子層無論如何都會阻止的真正不可逆危險時,或者根本沒有可逆性安全網(唯讀檔案系統、無 VCS 且無法建立 VCS)時使用。
在無人值守時,你只會選擇 PROCEED、PARK 或 HALT。絕不選擇 ASK。
根據影響範圍決定 PROCEED 還是 PARK(因此「不確定」很少見)
使分層具體化 — 猜測一個高影響範圍的項目並且整個運行都自信地犯錯,這是最壞的結果,比暫停更糟。
硬性暫停(絕不猜測): 資料庫綱要 / 遷移方向、公開或共享 API 合約、安全性 / 驗證 / 租戶隔離邊界、金錢 / 計費 / 定價、他人建構其上的跨任務介面,以及需求含義(你實際上不知道要建構什麼),除非該需求既是局部可逆的又是隔離的 — 那麼可以在一個標誌 / 草稿變更之後以可逆方式建構它,並暫停該決策(混合模式)。
繼續(假設 + 記錄 + 繼續): 命名、內部結構、日誌 / 註解 / 錯誤措辭、測試夾具、兩個等效本地實作之間的選擇、可簡單切換的預設值。
當真正無法分類時 → 暫停。 一個被錯誤暫停的小項目事後只需 5 秒決策;一個被錯誤假設的大項目則會浪費整個運行的工作。
提交每個 PROCEED 假設,以便可以還原;如果無法建立快照提交(git 鎖定 / 超時 / 唯讀物件儲存),則將任務視為 BLOCKED_ENV,而不是進行不可還原的編輯。每個 PARK 必須記錄:原因、候選解釋、精確的人類下一步行動及其污染範圍。
每張門票的循環(框架強制執行)
- 預檢測量能力(
agents_never_sleep/preflight.py)— VCS/可逆性、平台、閘門、執行模式、tokonomix/Vault/Paperclip。能力缺失永遠不會停止運行;它會降低預期產出並提高保守度。無 VCS → 在任何風險編輯之前建立一個安全網(git init / 時間戳備份);如果不可能 → 僅進行非破壞性操作。 - 決定 ASK/PARK/HALT 該任務(見上文)。無人值守:ASK→PARK。
- 實作 PROCEED 任務 — 你,代理,是工作者:讀取框架交給你的任務並編輯檔案。你透過下面的兩個子命令一次驅動一個任務;框架擁有排程、暫停、快照/還原和永不停止哨兵的擁有權。
- 閘門 確定性測試(
agents_never_sleep/gates.py)— 骨幹。分類失敗:由差異引入 → 硬性阻止(還原到最後一次綠色狀態 + 暫停/失敗);先前存在 / 不穩定 / 環境 → 降低信心,繼續或暫停(從不報告為「該任務失敗」);超時/環境 → BLOCKED_ENV。每個閘門都帶有每一步的超時和非互動環境,因此絕不會在 TTY 提示符上掛起。絕不要刪除或跳過一個失敗的測試來使測試通過 — 這是一個阻礙性的盲點。 - 記錄 恰好一個持久性結果(
agents_never_sleep/state.py):DONE、DONE_LOW_CONFIDENCE、PARKED_DECISION、PARKED_FOUNDATIONAL、BLOCKED_ENV、FAILED_RETRYABLE、FAILED_BUG_IN_AGENT — 帶有必要的欄位。原子寫入;恢復安全。 - 下一個任務。 嘗試次數 + 循環上限(
agents_never_sleep/ledger.py)會強制暫停一個超過其跨恢復嘗試次數上限或可證明在循環的任務,因此運行永遠不會浪費在一個被詛咒的項目上。一個低產出的斷路器會停止並在大部分工作被暫停/阻塞時發出警報。
運行它 — 代理就是工作者(驅動此循環)
在從互動式會話啟動之前,在聊天中向使用者詢問一次: 在此會話中在此處運行任務積壓(前景 — 如果他們關閉終端則停止),或透過 bin/ans-run 啟動一個分離的運行,該運行在登出後仍存活?這是一個設定/路由決策,不是運行中的問題 — 它不違反永不 ASK 合約,並且這是你要問的唯一問題。
如果配置了 tokonomix 共識模式(PROCEED 負載中的 council 區塊,或存在 tokonomix_* MCP 工具):在運行開始時:
- 無人值守(
CLAUDE_UNATTENDED=1): 發出一行日誌並立即繼續 — 絕不阻塞或詢問:ℹ️ Tokonomix 共識已啟用 — 透過 tokonomix_rate_consensus 自動評分每次委員會呼叫。 - 互動式(無
CLAUDE_UNATTENDED): 如果該帳戶尚未儲存評分偏好(即review_feedback_opt_in尚未設定 — 可檢測到,因為首次共識回應中缺少feedback_invite),則在聊天中向使用者詢問一次:「Tokonomix 共識已啟用。每次委員會呼叫後,我可以自動提交一個有用性評分(分數 + 發現)以改善模型分數。啟用此功能嗎?(是/否)」 將答案儲存在
.unattended/state/consensus_rating_pref.json中,以便僅在跨會話時詢問一次。如果回答是:繼續自動評分。如果回答否:完全跳過評分呼叫。
如果 consensus_rating_endpoint_enabled 在首次評分嘗試時返回 404,則記錄一次視為盲點,並跳過此次執行的所有後續評分呼叫。
框架無法從 Python 循環內部呼叫你,所以你驅動它。交替使用這兩個子命令,直到任務積壓耗盡。每個子命令會向標準輸出輸出一個 JSON 物件。
# 1. 向框架請求下一個要執行的事項。它會自動暫停模糊/高影響範圍的任務
# 並且只會交給您一個準備好實作的任務,或一個終端訊號。
python3 -m agents_never_sleep.run next --repo <project> --tickets <dir-of-.md-tickets>
讀取 JSON status:
-
PROCEED→ 僅透過編輯儲存庫中的檔案來實作ticket.body(不要觸及其他任務,不要停止,不要詢問)。然後呼叫complete:python3 -m agents_never_sleep.run complete --repo <project> --attempted "你所做的一行摘要"如果你真的無法做到,請使用
--cannot-implement(搭配--attempted解釋原因)— 框架會還原你的部分編輯並記錄 BLOCKED_ENV。執行complete後,再次呼叫next。如果
PROCEED負載攜帶了council或specialists區塊,並且你執行了審查 — 你必須在complete時回饋結果,否則建議性信任閘門將永遠不會觸發:... complete --attempted "…" [--council-verdict pass|concerns|error --council-cost <€>] \ [--specialist-concerns architect,security,… --specialist-cost <€>] [--review-coverage "<執行者>"]。 僅在你沒有執行此類審查時才省略一個標誌。(詳細資訊:下面的委員會和專家部分。) -
PARK_CONSENSUS_ELIGIBLE→ 該任務將會因為模糊的需求含義而暫停(僅此原因,絕非硬性暫停類別)。執行負載的prompt所要求的基於依據的 tokonomix 共識(平行 + 盲目的提案者,一個無關的評判者)— 絕不要問一個自由文字的「我應該繼續嗎?」,這是提示明確禁止的危險框架。然後報告結構化的裁決,回顯來自提供負載的attempt_id:... resolve-park --ticket-id <id> --attempt-id <來自提供負載的 attempt_id> --resolved \ --chosen-reading "<解讀>" --evidence "<引用的確切證據>" --dissent-count <N> \ --synthesis-text "<評判者綜合>"如果共識無法根據引用的證據進行釐清,則使用
--not-resolved。框架的確定性閘門是唯一的仲裁者 — 已解決的裁決會路由到正常的PROCEED流程(實作,然後像往常一樣執行complete);被拒絕的裁決則會將任務暫停並附上稽核軌跡,然後繼續。對相同任務的重複resolve-park始終是安全的無操作(ALREADY_RESOLVED)。(詳細資訊:下面的 F5 部分。) -
DRAINED/HALTED/LOW_YIELD→ 運行結束;運行報告已寫入。停止。 -
NON_DESTRUCTIVE→ 無人值守但未儲存配置;先執行一次互動式配置運行。
永遠不要發明你自己的循環或提前停止。 next 擁有 .unattended/run-incomplete 哨兵,Stop 鉤子用它來阻止過早停止;繼續呼叫 next,直到它返回一個終端狀態。框架處理編輯前快照、編輯後閘門、紅色時還原、嘗試次數上限、循環檢測和低產出斷路器 — 你唯一的工作是編輯。
哨兵路徑合約(承載性,強制執行)。 Stop 鉤子檢查
${UE_RUN_INCOMPLETE:-$PWD/.unattended/run-incomplete}並且驅動程式寫入相同路徑。它們會自動保持一致 僅當代理從儲存庫根目錄執行時(因此$PWD == --repo;使用--repo .)。 對於 CWD 可能與--repo不同的無人值守運行(cron /claude-run), 啟動時匯出UE_RUN_INCOMPLETE=<repo>/.unattended/run-incomplete。為了防止永不停止無聲地失敗,next在無人值守 + CWD ≠--repo+UE_RUN_INCOMPLETE未設定時硬性失敗(status:"ERROR",退出碼 2)— 修正啟動方式(cd 進入儲存庫,或設定環境變數)。
首次互動式運行會觸發一個最小的專案級嚮導(.claude/agents-never-sleep.json)。
該技能永遠不會自我排程 — 無人值守運行(cron / claude-run)始終是使用者的明確操作,因此嚮導總是先執行。無人值守但無配置 → 僅進行非破壞性操作 + 在報告中附帶一個醒目的註解。
密封的驗收演示(
acceptance/run_acceptance.py)使用一個確定性的DemoWorker在進程內驅動循環,僅用於自我測試 — 沒有進程內的run子命令。實際運行始終使用上面的next/complete流程。
啟動運行 — bin/ans-run(token 前預檢 + 工作目錄鎖定)
agents_never_sleep/preflight.py 在代理會話啟動後測量能力 — 此時第一個 token 已經花費,一個註定失敗的運行已經花費了金錢。對於無頭/cron 啟動,請改為透過啟動器啟動:
bin/ans-run [--repo <project>] [--agent <preset>] [--fg] [--check] [--trust] "<提示>"
它是一個確定性的 GO/NO-GO 閘門,在代理 CLI 啟動之前執行:
- 配置信任(TOFU) —
.claude/agents-never-sleep.json隨儲存庫一起傳播,並描述了啟動器要執行的命令(代理 argv、主機檢查)。新的或更改過的配置必須由每個使用者信任一次 — 在提示符處互動式進行,或在審查後透過ans-run --trust明確進行。無頭 + 未信任 = NO-GO。信任記錄在儲存庫外部(~/.config/agents-never-sleep/trusted.json,以配置的 SHA-256 為鍵)— 儲存庫不能為自己擔保。永遠不要在你信賴程度低於其make install的儲存庫中執行 ans-run。 - 身份 — 可配置的
launcher.target_user+ 根守衛:以 root 身份啟動並配置了目標使用者 → 以該使用者身份重新執行;以 root 身份啟動且未配置 → NO-GO(無人值守運行絕不能以 root 身份執行), - 代理選擇 —
launcher.agents下的命名預設集,透過--agent或launcher.default_agent選擇。啟動時不進行平台檢測(會話環境標記是偽造的,並且在 cron 下會消失);嚮導是執行檢測(作為預填提示)和人類決策的地方。每個預設集有三個閘門:argv[0] 必須是已知的代理 CLI(claude/codex/gemini/copilot;僅能透過信任配置中的launcher.allow_custom_agent覆寫),二進位檔案必須通過 5 秒--version能力探測(在花費 token 之前捕獲標誌漂移),並且autonomy_confirmed必須為 true(請參閱下文), - 憑證 —
launcher.credentials_paths在配置時是阻塞的,未配置時僅警告(鑰匙圈和 API 金鑰設定沒有憑證檔案), - 儲存庫健康狀況 — git 可用(捕獲可疑擁有權)、儲存庫可寫、磁碟空間(
launcher.min_disk_mb)、臟/暫存的工作目錄作為警告呈現, - 主機檢查 — 服務/資料庫探測完全來自
launcher.checks([{"name", "command", "blocking"}]);啟動器中沒有硬編碼的站點特定內容。
退出碼:0 已啟動/GO · 64 NO-GO · 65 工作目錄正忙。
自主性標誌是人類的明確決定 — 永遠不是預設值
一個完全開啟 CLI 權限系統的分離式運行會在其第一個批准提示處停滯(標準輸入已關閉,沒有人在看);防止這種情況的標誌授予了真正的權力。提供的映射(agents_never_sleep/agent_clis.py,嚮導和啟動器的單一來源)將兩種變體分開,並且嚮導在要求你確認之前顯示該標誌授予了什麼 — 只有這樣,預設集才會記錄 autonomy_confirmed 並可啟動。
……(為翻譯而截斷)