Agent Autoloop
让你的命令行 Agent 在后台自己接活、自己跟进到底；平时不烦你，遇到拿不准的事才发卡片找你拍板。
中文 | English
它解决什么问题？
平时我们用 Claude Code、Codex 这类命令行 Agent，大多是“人守着终端用”：你输一句话，盯着它跑，等它问你下一步；一旦关掉窗口或者人走开，事情就断了。
Agent Autoloop 是一个极轻量的自动化中台。它把任务调度做成一个零外部依赖的内核，把事件来源、Agent、通知通道，甚至代码上线流水线全部拆成可随时插拔的插件。
- 一台电脑、一条命令就能跑。 装在你的 Windows、Mac 或 Linux 上，不用买云服务器，也不用开放公网端口。
- 一行配置接新 Agent。 不需要 SDK，也不需要改 Agent 源码，能接收提示词并打印最后一条回复的命令行工具都能接。
- 没有后台界面。 需要你拍板时把卡片推到飞书、钉钉、企微、Slack、Discord 或桌面通知；想看全局进展，敲一行命令。
上手
支持 Windows、macOS 和 Linux。需要 Node 24 或更新、Git，以及一个已经登录的命令行 Agent；macOS/Linux 还需要 curl，不需要 GitHub 账号。也可以把安装说明交给你的 Agent。
Windows PowerShell：
irm https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.ps1 | iexmacOS / Linux：
curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh安装和 agent-autoloop update 都装最新的 Release，那是通过了全部检查的版本。
装好后用你本机的 Agent 真实走一遍“提问 → 退出等回复 → 拍板 → 接着干完”：
agent-autoloop try下面是在终端里的真实输出：
事件发出去了，Agent 开始干活……
Agent 结束了这一轮，问了你一个问题。它现在不占进程、不花 Token。
【等你决定】#1 试跑：选一个颜色
这是一次试跑，选哪个都行。
1. 蓝色
2. 绿色
回答：agent-autoloop answer 1 <序号>
答完运行 agent-autoloop status，能看到它接着把活干完。
交互终端里直接输入数字回车；非交互终端运行 agent-autoloop answer 1 2 选择“绿色”。再跑 agent-autoloop status，就能看到它接上刚才的会话并显示“你选了绿色，试跑通过”，还有今天和最近 7 天的轮数、Token 和费用（统计口径）。
一件事怎么转起来
编号和上面的架构图一一对应：
- 新事件进来。 早上 9 点的定时任务、GitHub 上新提的 Issue、业务系统报的错，都变成一条标准事件送进内核。
- 按规则派活。 内核照你写的规则，决定交给哪个 Agent、去哪个目录干。同一件事排队时又来的消息，会合并成一轮处理。
- 干完一轮就退出。 Agent 把结果写在最后一条回复里，进程直接退出。
- 拿不准才问你。 碰到删数据、重启服务、花钱、对外发消息这类事，内核通过飞书或桌面通知发一张卡片给你。等你回复期间，它不占后台进程，也不消耗 Token。
- 点一下，接着干。 你选完，它接上原来的对话，把剩下的活干完。
能自己搞定的事走图上方的自动闭环：直接办完，或者约个时间（比如半小时后）再醒来复查，全程不打扰你。
日常怎么配？
写一份规则（rules.json）
不需要写胶水代码。打开 ~/.agent-autoloop/rules.json，在 rules 里写清楚什么事、交给谁、在哪个目录干。to 填 agents 里已有的名字。比如每天早上 9 点写早报：
{
"name": "早报",
"when": { "cron": "0 9 * * *" },
"to": "codex",
"cwd": "~/notes",
"prompt": "整理昨天的笔记和提交，写今天的早报。"
}外部事件写法一样，只是要先接好来源。比如有人提新 Issue 时交给 Codex，先按说明在 sources 里登记 github：
{
"name": "处理 issue",
"when": { "source": "github", "types": ["issues.opened"] },
"to": "codex",
"cwd": "~/code/app",
"skill": "handle-issue",
"parallel": 3
}agent-autoloop pause <规则>、resume <规则> 暂停和恢复一条规则，暂停期间到点不跑、来事件不接，恢复后不补跑；agent-autoloop run <规则> 立即跑一轮。这些记在中台的日志里，不改 rules.json。
保存后几秒内自动生效，可以运行 agent-autoloop check 检查，agent-autoloop check <文件> 检查一份草稿，不碰正在跑的中台；agent-autoloop rules explain 看生效的规则和下次定时，agent-autoloop emit <类型> --dry-run 预演一条事件会派给谁（不连接中台、不写日志）。就算改错了，或者文件被删、读不到，系统也会继续按旧规则跑，并发卡片提醒你。
Agent 怎么跟中台配合？
中台对 Agent 只有一个约定：在最后一条回复里交代结果。事情办完了，正常输出一句结论就行。需要向你请示时，在回复末尾附一段 agent-autoloop 代码块：
订单已经核对完毕，库存充足。
```agent-autoloop
{
"ask": [{
"title": "怎么发货？",
"text": "两种方式今天都能发出。",
"options": ["快递", "自提"],
"key": "shipping"
}]
}
```
除了提问（ask），还能发通知（notice）、关闭已解决的卡片（resolve）、预约复查（later）和触发新事件（events）。通告不需要回答，但结案时可以顺手写一句处理说明，这句话会留在卡片上；只是告诉一声的通告标成 fyi，不带按钮。万一 JSON 写错了，中台只让它在原会话里重写最后这段回复，不会把已经干完的业务重做一遍；重写也失败时，保留原结论并通知你回执没有生效（通用命令没有会话，直接走这一步）。接着旧会话跑也一样：会话接不上才开新的；接上了、干到一半断了，就算没跑成，过几分钟回到原会话重试，不开新会话重做。同一事项的新事件默认开新会话；规则写 "resume": true 就接着上一轮的会话。
拿来即用的场景模板
每套模板都带规则、任务 Skill 和启用说明。
| 想做什么 | 已经封装好的流程 |
|---|---|
| 每日早报 | 默认每天 8 点整理本地笔记和 Git 提交，写入 briefs/YYYY-MM-DD.md |
| 跟进 GitHub Issue | 每 5 分钟查新 Issue，在本地改代码并通知你查看；不提交、不推送、不回复 Issue |
| 线上告警排查 | 接收报错、对照代码查原因，需要重启时发卡片询问，回答后继续 |
| 用户反馈处理 | 重读反馈当前状态、修复、交付核实、准备回复；需要决定时飞书问你，回答后继续 |
| 网站巡检 | 每 5 分钟检查状态和关键内容，首次异常交给 Agent，持续异常不重复通知，恢复后更新原卡片 |
| 飞书周报与业务摘要 | 周日 18 点按你的权限读汇报和指定表格，生成本地摘要；飞书只发简短摘要，完整稿留在本机 |
| 收件箱分诊 | 默认每天 8 点读过去 24 小时的未读邮件，写成清单和回复草稿；不发送、不改邮箱状态 |
| PR 自动交付 | 打上 deliver 标签后，审查、等 CI、合并、等发布并核对线上版本 |
启用： 打开对应说明，把任务 Skill 放进所用 Agent 的 skills 目录，把示例规则合入 ~/.agent-autoloop/rules.json，替换电脑名和路径，再运行 agent-autoloop check。
反馈处理、网站巡检、飞书摘要和收件箱分诊默认使用北京时间，只发给本人的飞书私聊。样例数据都是虚构的；脚本和回执只用本地 HTTP 与假飞书 CLI 验证过，没有在真实账号上跑过完整业务。
更多模板：Claude 委托 Codex 处理网页、每周代码清理、交付 PR。
插件体系：四个方向都能自由替换
内置插件随程序安装，填好配置即可启用；第三方插件用 agent-autoloop add <git 地址> 安装。
| 方向 | 内置 | 配置 |
|---|---|---|
| 事件：怎么发现新活 | GitHub Webhook、GitLab Webhook、HTTP 接口、定时规则、Issue 轮询脚本 | 说明 |
| Agent：谁来干活 | Claude Code、Codex、ACP、DeepSeek Harness、通用命令 | 说明 |
| 通道：去哪找你拍板 | 桌面通知（默认开启）、飞书、钉钉 / 企微 / Slack / Discord | 说明 |
| 交付：把 CI/CD 也做成插件 | delivery |
说明 |
实测情况： Claude Code、Codex 和 ACP（官方 Codex ACP 适配器）跑通了多轮问答和跨进程会话续接；飞书跑通了发送、按钮回调和卡片更新；四种 Webhook 模板只在本地模拟服务上验证过，GitLab Webhook 按官方文档的格式测试，没连过真实 GitLab。这些文字通道靠回答链接拍板，要把 hub.publicUrl 配成手机或电脑能打开的地址。
内置 Agent 走第三方网关。 Claude Code、Codex 要接第三方模型服务，或者启动前要先设好环境变量，写一个设好变量再启动它的小脚本，在 Agent 里写 "program": "脚本路径"，会话续接和用量统计照旧，见说明。
其他命令行 Agent 一行接入。 设置 use: "command" 并传入命令数组，{prompt} 作为独立参数传递，不会被当成 shell 代码执行。下面的命令整理自各家官方文档，我们还没有逐个跑过：
| Agent | 接入命令 |
|---|---|
| DeepSeek Harness 旧版（内置插件要 0.2.2 或更新） | dsh --profile headless {prompt} |
| pi | pi --print {prompt} |
| OpenClaw | openclaw agent exec {prompt} |
| Hermes | hermes chat -Q -q {prompt} |
| Cursor | agent -p --trust {prompt} |
| WorkBuddy / CodeBuddy | codebuddy -p {prompt} |
会说 ACP 的 Agent 用 use: "acp" 接，还能接着原来的会话做：Gemini CLI 写 "command": ["gemini", "--acp"]，OpenCode 写 "command": ["opencode", "acp"]。这两条同样整理自官方文档，还没跑过。
交付流水线。 给 GitHub PR 打上 deliver 标签后，它会自己跟进到上线：审代码 → 等 CI → 合并 PR → 等部署 → 核对线上版本。审查和交付配置只从 main 读取，绝不在接单电脑上检出或运行 PR 里的代码；排队、并发和重试直接复用内核。
写自己的插件。 从 Agent、通道、事件 三个可运行的最小模板开始，见插件开发说明。要让 Agent 操作网页，先看浏览器接入。命令行和 MCP 也能查看和回答卡片。
内核的四个机制
内核约 1850 行代码、零运行时依赖。它不读系统时钟、不用随机数、不向外发请求，插件主动连进来，账号凭据留在各自的插件里；同样的输入永远得出同样的结果。它把四个计算机领域的成熟做法用到了命令行 Agent 上：
- 挂起零消耗：等你拍板时进程直接退出，等待状态存在数据库里，Agent 不用一直挂着。你三天没回，这三天就没有 Agent 进程在跑、不花 Token，只有很轻的中台在后台等着；你一回答，它接着原来的对话继续干。
- 事件溯源：所有状态都从一条只追加的日志算出来，日志和索引在同一个事务里写进磁盘，写完才应答。进程被强杀，已经确认的事不丢（整机断电没有单独测过）；任何一轮为什么跑、结果是什么，一条命令就能查清；数据格式变了就从日志重建，不用写迁移脚本。
- 指令数据分离：思路和 SQL 参数化一样。Issue 的标题和正文等外部文字只作为资料放进文件，不拼进提示词，提示词里只有校验过字符的类型、编号和链接；用哪个 Agent、在哪个目录、什么权限，只由你本机的规则决定，事件里带
cwd、agent、access字段会被直接拒收。 - 跳数熔断：思路和网络包的 TTL 一样。Agent 交回的事件会再派给 Agent，层数一路累加，经过人工提问和定时复查也不清零，Agent 自己改不了；超过 8 层就只记录、不再派活，并发一张卡片告诉你。
自己跑一遍
Windows 用 npm run test:windows 和 node scripts/install-smoke-windows.ts，运行共用行为测试与原生进程、安装检查；Unix shell 测试仍在 Linux/macOS 上跑。
在程序目录 ~/.agent-autoloop/app 下运行：
| 验证什么 | 命令 |
|---|---|
| 任何一轮的来龙去脉 | agent-autoloop why 1 |
| 20 万步模拟断网、丢包、崩溃和重复提交，一个种子就能复现 | node sim/random.ts 24301 200000 |
| 强杀进程 1000 次，已确认的记录一条不丢 | node sim/crash.ts 1000 12648430 |
| 下面的性能数字 | npm run benchmark |
第 1 轮 · 演示
11-03 20:47:25 规则版本 #1
11-03 20:47:25 触发事件：来源 local · 类型 demo.start · 对象 example
11-03 20:47:25 local 领取（演示程序）
11-03 20:47:25 结束：演示完成
实测性能
Apple M5 Pro、24 GB、Node 24.21.0。写入逐条提交，事务落盘后才应答。
| 指标 | 实测 |
|---|---|
| 冷启动 | 88.78 ms |
| 空闲内存 | 59.94 MB RSS |
| 1000 个同时等待的长轮询 | 170.49 MB RSS |
| 持久化写入 | 2394 条/秒 |
| 派活 p99 | 1.82 ms |
| 排队 5000 时被挡下的心跳 p99 | 1.66 ms |
| 110 万条事实时的启动 | 99.8 ms |
| 内核行数（含空行和注释） | 约 1850 |
| 运行时依赖 | 0 |
历史变大后，状态汇总会变慢，日志和索引也继续占磁盘；格式变化后的首次启动要从日志全量重建，110 万条用时 43.1 秒。完整数据和测法。
用量与合规说明
中台直接调用你本机已经安装并登录好的命令行工具，不会读取或转存你的账号凭据。模型调用消耗算在你自己的账号名下，额度和使用范围遵循各家模型厂商的服务条款。
在高频自动化场景下，各家厂商通常更建议使用 API Key（个人订阅额度主要是为日常人工交互设计的，详见 Anthropic 与 OpenAI 的官方说明）。如果你用它对外提供服务，请使用 API Key。本项目为独立开源项目，与上述厂商无隶属或背书关系。
更多文档
仓库目录
| 位置 | 放什么 |
|---|---|
kernel/ |
内核：决策、事实日志、状态投影、到期任务、规则匹配、接口行为与卡片表单 |
host/ |
运行外壳：Node HTTP、文件与 SQLite 连接、时钟、配置、状态汇总、后台服务和插件加载 |
protocol/ |
通信格式、JSON Schema、输入校验、HTTP 客户端和一致性检查 |
worker/ |
接单程序：领活、运行 Agent、心跳与停止、读取和提交回执 |
cli/、bin/ |
用户命令及启动入口，包括状态、回答、why、MCP、更新与卸载 |
plugins/ |
内置 Agent、事件、通道和交付插件 |
examples/recipes/ |
完整场景：规则、任务 Skill 和启用说明 |
examples/plugins/、examples/skills/、examples/*.sh |
最小插件模板、独立任务手册和 Shell 示例 |
skills/agent-autoloop/ |
中台的正式配置与操作手册，安装时也提供给 Agent 使用 |
docs/ |
通信协议、插件开发说明与中英文架构图 |
tests/、sim/ |
日常行为测试，以及模拟、穷举、强杀和变异检查 |
scripts/、.github/workflows/ |
性能与真机验证、安装冒烟脚本，以及 Windows / Linux / macOS CI |
根目录文档与 install.sh |
中英文 README、安装说明、安全边界、开发约定、许可证与安装脚本 |
读代码可以从 bin/agent-autoloop.ts → cli/main.ts 开始，再按功能进入 host/、worker/ 或 plugins/；内核设计先看协议。同名文件分属不同层：host/http.ts 转换 Node 请求，kernel/http.ts 定义接口行为；protocol/rules.ts 校验输入，kernel/rules.ts 定义规则类型和匹配。
