Communitygithub.com

TokonoMix/agents-never-sleep

自主執行治理,適用於編碼代理:無人值守運行任務積壓至完成。ASK/PARK/HALT 自主合約、持久化每張門票的狀態機、確定性測試閘門、基於 Git 的可逆性、心跳看門狗、晨間報告。僅使用 Python 標準庫。

agents-never-sleep 是什麼?

Agents Never Sleep (ANS) 是一個為 AI 編碼代理設計的自主執行治理技能,確保在無人值守的情況下可靠地將任務積壓(backlog)運行至完成,而絕不因問題而軟暫停。其核心圍繞三個關鍵設計原則構建:狀態持久性、具體的暫停(PARK)與繼續語義,以及反飢餓機制。技能透過一個名為「自主合約」的結構來強制執行,該合約定義了代理對不確定性的三種回應:ASK(向人類提問,在無人值守時被禁止)、PARK(延遲當前決策或任務,並繼續運行)和 HALT(因不可逆危險而完全停止)。ANS 支援 Claude Code、Codex 等平台,並提供強大的基礎設施,包括確定性測試閘門(以防止由回歸導致的盲目進展)、基於 Git 的快照和還原、心跳看門狗,以及一個精密的啟動器 (`bin/ans-run`),用於在花費任何 token 之前進行預檢。代理透過 `next` 和 `complete` 命令與任務互動,在一個由兩個子命令驅動的循環中,由技能管理調度、則門和狀態持久化。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓Windsurf
npx skills add TokonoMix/agents-never-sleep

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

永不眠的代理 (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.sh PreToolUse 鉤子(匹配器 AskUserQuestion,環境變數閘門 CLAUDE_UNATTENDED=1)會拒絕該工具並引導你回到 PARK/PROCEED — 這是永不停止保證的鏡像。
  • PARK — 延遲此決策或任務,並保持運行繼續到下一個獨立任務。暫停是正常且健康的,不是停止。
  • HALT — 停止整個運行。僅在發生鉤子層無論如何都會阻止的真正不可逆危險時,或者根本沒有可逆性安全網(唯讀檔案系統、無 VCS 且無法建立 VCS)時使用。

在無人值守時,你只會選擇 PROCEED、PARK 或 HALT。絕不選擇 ASK。

根據影響範圍決定 PROCEED 還是 PARK(因此「不確定」很少見)

使分層具體化 — 猜測一個高影響範圍的項目並且整個運行都自信地犯錯,這是最壞的結果,比暫停更糟。

硬性暫停(絕不猜測): 資料庫綱要 / 遷移方向、公開或共享 API 合約、安全性 / 驗證 / 租戶隔離邊界、金錢 / 計費 / 定價、他人建構其上的跨任務介面,以及需求含義(你實際上不知道要建構什麼),除非該需求既是局部可逆的又是隔離的 — 那麼可以在一個標誌 / 草稿變更之後以可逆方式建構它,並暫停該決策(混合模式)。

繼續(假設 + 記錄 + 繼續): 命名、內部結構、日誌 / 註解 / 錯誤措辭、測試夾具、兩個等效本地實作之間的選擇、可簡單切換的預設值。

當真正無法分類時 → 暫停。 一個被錯誤暫停的小項目事後只需 5 秒決策;一個被錯誤假設的大項目則會浪費整個運行的工作。

提交每個 PROCEED 假設,以便可以還原;如果無法建立快照提交(git 鎖定 / 超時 / 唯讀物件儲存),則將任務視為 BLOCKED_ENV,而不是進行不可還原的編輯。每個 PARK 必須記錄:原因、候選解釋、精確的人類下一步行動及其污染範圍。

每張門票的循環(框架強制執行)

  1. 預檢測量能力(agents_never_sleep/preflight.py)— VCS/可逆性、平台、閘門、執行模式、tokonomix/Vault/Paperclip。能力缺失永遠不會停止運行;它會降低預期產出並提高保守度。無 VCS → 在任何風險編輯之前建立一個安全網(git init / 時間戳備份);如果不可能 → 僅進行非破壞性操作。
  2. 決定 ASK/PARK/HALT 該任務(見上文)。無人值守:ASK→PARK。
  3. 實作 PROCEED 任務 — 你,代理,是工作者:讀取框架交給你的任務並編輯檔案。你透過下面的兩個子命令一次驅動一個任務;框架擁有排程、暫停、快照/還原和永不停止哨兵的擁有權。
  4. 閘門 確定性測試(agents_never_sleep/gates.py)— 骨幹。分類失敗:由差異引入 → 硬性阻止(還原到最後一次綠色狀態 + 暫停/失敗);先前存在 / 不穩定 / 環境 → 降低信心,繼續或暫停(從不報告為「該任務失敗」);超時/環境 → BLOCKED_ENV。每個閘門都帶有每一步的超時和非互動環境,因此絕不會在 TTY 提示符上掛起。絕不要刪除或跳過一個失敗的測試來使測試通過 — 這是一個阻礙性的盲點。
  5. 記錄 恰好一個持久性結果(agents_never_sleep/state.py):DONE、DONE_LOW_CONFIDENCE、PARKED_DECISION、PARKED_FOUNDATIONAL、BLOCKED_ENV、FAILED_RETRYABLE、FAILED_BUG_IN_AGENT — 帶有必要的欄位。原子寫入;恢復安全。
  6. 下一個任務。 嘗試次數 + 循環上限(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 並可啟動。

……(為翻譯而截斷)

相關技能