README

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：

powershell
irm https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.ps1 | iex


macOS / Linux：

bash
curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh


安装和 agent-autoloop update 都装最新的 Release，那是通过了全部检查的版本。

装好后用你本机的 Agent 真实走一遍“提问 → 退出等回复 → 拍板 → 接着干完”：

bash
agent-autoloop try


下面是在终端里的真实输出：

text
事件发出去了，Agent 开始干活……

Agent 结束了这一轮，问了你一个问题。它现在不占进程、不花 Token。

【等你决定】1 试跑：选一个颜色
这是一次试跑，选哪个都行。
  1. 蓝色
  2. 绿色
回答：agent-autoloop answer 1 
答完运行 agent-autoloop status，能看到它接着把活干完。


交互终端里直接输入数字回车；非交互终端运行 agent-autoloop answer 1 2 选择“绿色”。再跑 agent-autoloop status，就能看到它接上刚才的会话并显示“你选了绿色，试跑通过”，还有今天和最近 7 天的轮数、Token 和费用（统计口径）。

 一件事怎么转起来

编号和上面的架构图一一对应：

1. 新事件进来。 早上 9 点的定时任务、GitHub 上新提的 Issue、业务系统报的错，都变成一条标准事件送进内核。
2. 按规则派活。 内核照你写的规则，决定交给哪个 Agent、去哪个目录干。同一件事排队时又来的消息，会合并成一轮处理。
3. 干完一轮就退出。 Agent 把结果写在最后一条回复里，进程直接退出。
4. 拿不准才问你。 碰到删数据、重启服务、花钱、对外发消息这类事，内核通过飞书或桌面通知发一张卡片给你。等你回复期间，它不占后台进程，也不消耗 Token。
5. 点一下，接着干。 你选完，它接上原来的对话，把剩下的活干完。

能自己搞定的事走图上方的自动闭环：直接办完，或者约个时间（比如半小时后）再醒来复查，全程不打扰你。

 日常怎么配？

 写一份规则（rules.json）

不需要写胶水代码。打开 ~/.agent-autoloop/rules.json，在 rules 里写清楚什么事、交给谁、在哪个目录干。to 填 agents 里已有的名字。比如每天早上 9 点写早报：

json
{
  "name": "早报",
  "when": { "cron": "0 9   " },
  "to": "codex",
  "cwd": "~/notes",
  "prompt": "整理昨天的笔记和提交，写今天的早报。"
}


外部事件写法一样，只是要先接好来源。比如有人提新 Issue 时交给 Codex，先按说明在 sources 里登记 github：

json
{
  "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 代码块：

text
订单已经核对完毕，库存充足。

agent-autoloop
{
  "ask": [{
    "title": "怎么发货？",
    "text": "两种方式今天都能发出。",
    "options": ["快递", "自提"],
    "key": "shipping"
  }]
}



除了提问（ask），还能发通知（notice）、关闭已解决的卡片（resolve）、预约复查（later）和触发新事件（events）。通告不需要回答，但结案时可以顺手写一句处理说明，这句话会留在卡片上；只是告诉一声的通告标成 fyi，不带按钮。万一 JSON 写错了，中台只让它在原会话里重写最后这段回复，不会把已经干完的业务重做一遍；重写也失败时，保留原结论并通知你回执没有生效（通用命令没有会话，直接走这一步）。接着旧会话跑

Discussions

Latest release

来源能查到自己发出的事件后来怎么样了；status 在终端里彩色分区显示；修好 Windows 自带 Administrator 账号、保留端口和短路径目录上的几处问题。旧规则、旧插件不用改。

- 来源查事件结果。 来源发完事件，用同一把密钥 GET /v1/events/ 就能查到它被哪些规则接了、每一轮现在什么状态（在跑、没跑成、等重试、被停、不再重试）和最后的结论。只查得到这个来源自己从门口发进来的事件，中台代它记的（回执发出的、手动运行、卡片回答、到期复查）和别的来源的都返回 404。
- status 更好读。 在终端里按颜色和分区排：总数、在线、等你、正在做、最近几轮、最近的卡片、定时、没有规则接的事件。新加“正在做”，写清已跑多久、因为什么开始。接管道、被 Agent 调用、设了 NO_COLOR 时仍是纯文本，--json 不变。
- Windows：自带的 Administrator 账号不再以管理员权限常驻。 开着 UAC 的自带 Administrator 账号，登录任务照样会拿到完整权限。现在 service install 发现这种情况会撤掉任务，并打印一行命令，改由「启动」文件夹以普通权限拉起；建不了任务时也打印这一行。
- Windows：数据目录在 8.3 短名路径下不再崩。 Node 24.16 起，中台监视规则文件时，短名目录里一有改动就会退出