Communitygithub.com

TokonoMix/agents-never-sleep

编码代理的自主执行治理工具:无须值守即可将待办事项清单跑完。ASK/PARK/HALT 自治契约、持久化每工单状态机、确定性测试关卡、git 支持的回滚、心跳看门狗、晨间报告。仅用 Python 标准库。

agents-never-sleep 是什么?

Agents Never Sleep (ANS) 是一种自主执行治理框架,专为编码代理(如 Claude Code、Codex、Gemini CLI、Copilot)设计。它提供了一个结构化的“自治契约”,包含 ASK、PARK 和 HALT 三种状态,确保代理在无人值守时永远不会因提问而软停止。该框架的核心是一个基于 Python 标准库的轻量级包,通过状态机管理每个工单的生命周期,包括预检、确定性测试关卡(用于反向安全)、git 回滚和心跳看门狗。它支持多种平台,通过环境变量 `CLAUDE_UNATTENDED=1` 或 `ans-run` 启动器实现无人值守运行,该启动器在代理 CLI 启动前执行预令牌预检和工作树锁定。ANS 的主要价值在于防止运行因单个工单而被困,通过工单尝试上限和循环检测强制执行公平调度,并通过低级产量断路器应对整体阻塞情况。它设计为由代理驱动主循环,交替使用 `next` 和 `complete` 子命令,同时框架负责快照、回滚和状态持久化。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Agents Never Sleep (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;凌晨两点没有人回答,一个单一问题就会浪费整个运行。这是通过结构而非纪律强制执行的:deny_ask.sh PreToolUse 钩子(匹配器 AskUserQuestion,环境门控 CLAUDE_UNATTENDED=1)拒绝该工具并引导你回到 PARK/PROCEED——永不停止保证的镜像。
  • PARK —— 推迟此决策或工单并保持运行继续到下一个独立工单。暂停是正常且健康的,不是停止。
  • HALT —— 停止整个运行。仅当出现钩子层本应阻止的真正不可逆危险,或完全没有可逆性安全网(只读文件系统、无 VCS 且无法创建)时。

无人值守时你永远只选择 PROCEED、PARK 或 HALT。绝不 ASK。

通过影响范围决定 PROCEED 与 PARK(因此“不确定”很少见)

使分级具体化——在高影响范围项目上猜测并自信地错误会导致整个运行的最坏结果,比暂停更糟。

硬 PARK(绝不猜测): 数据库模式/迁移方向、公共或共享 API 契约、安全/认证/租户隔离边界、金钱/计费/定价、他人构建的跨工单接口,以及需求含义(你实际上不知道要构建什么),除非它既是本地可逆的又是隔离的——那么可以在标志/草稿变更后安全地构建它并暂停决策(混合方式)。

继续执行(假设+记录+继续): 命名、内部结构、日志/注释/错误措辞、测试夹具、两个等效本地实现之间的选择、可轻松切换的默认值。

当真正无法分类时 → PARK。 一个错误暂停的小项目事后只需 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 → 该工单原本会由于模糊的需求含义而暂停(仅此原因,绝不是硬 PARK 类别)。运行负载的 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 .)。 对于当前工作目录可能与 --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(预令牌预检 + 工作树锁定)

agents_never_sleep/preflight.py 在代理会话启动后测量能力——届时第一个令牌已消耗,一次注定失败的运行已经花费了金钱。对于无头/cron 启动,请改为通过启动器启动:

bin/ans-run [--repo <project>] [--agent <preset>] [--fg] [--check] [--trust] "<prompt>"

它是一个确定性的 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 能力探测(在令牌消耗前捕获标志漂移),并且 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 并变得可启动。

...

[为翻译而截断]

相关技能