agent-autoloop v1.1.0 发布：稳定性、安全与性能修复

Official release notes (https://github.com/KKKKhazix/agent-autoloop/releases/tag/v1.1.0) v1.0.0 之后的第一批修复和改进。 **从这个版本开始，安装和 `agent-autoloop update` 都装最新的 Release，不再跟 `main`。** 已经装了的运行两次 `agent-autoloop update`：第一次拉到 `main` 最新，第二次落到 Release 上。 第一次启动会从日志重建一次投影，历史多时要等一会儿。 ## 更稳 - 插件出错不再拖垮中台：读不懂输出只算这一轮没跑成，通道或接单程序停了 30 秒后重启，没接住的错误只记日志（#79）。 - `rules.json` 被删、读不到或写错时继续用旧规则，只说一次；中台停着时写坏的也会说（#51、#80）。 - 别的进程占着数据库时，这次到期 5 秒后再试；命令行和中台可以同时写（#53、#79）。 - 连续失败 10 次后停止自动重试，发卡片交给人（#50）。 - 接着旧会话跑时干到一半断了，不再开新会话把业务重做一遍（#60）。 - 查进程失败时不再判定进程已死（#63）。 - 规则删掉或改名后，排着的这一轮停下并发卡片（#54）。 - “接单程序没连上”的卡片关掉后不再马上重发，之后新来的活照常提醒（#80）。 - 飞书监听启动不了时只记日志（#26）。 ## 修复 - 登录 shell 是 fish 时 Agent 启动不了（#22）。 - Claude 把结果输出成一整行数组时读不到（#18）。 - 桌面应用目录里有文件时，找内置 Claude Code 报错（#78）。 - 续接会话时用量重复计入（#56）；没跑成的一轮丢掉回执的用量和会话（#67）。 - `join` 覆盖已有配置（#19）；`init --help` 直接执行安装（#75）；`key remove` 在名字带大写、下划线或点时吊销不了（#39）；`try` 把上一次的失败当成这一次的（#23）。 - `hub.listen` 解析出错时监听所有网卡或启动崩溃（#41）；systemd unit 的值没加引号（#38）；`doctor` 不认系统级服务（#74）；卸载在 Node 25.1 上报错（#61）。 ## 安全 - 卡片链接过期后不再显示内容（#81）。 - `master.key` 为空或残缺时拒绝启动，不再拿它签链接（#52）。 - 声明超过 8 MB 的请求不读内容（#57）；卡片回答和通道回报的长度上限由内核执行（#40）。 - `doctor` 提醒没写 `answerers` 的通道，这种通道里谁都能回答卡片（#84）。 ## 新增 - GitLab 事件插件（#29）。 - 通告卡片可以顺带写一句处理说明（#48）。 ## 性能 - 心跳最多一分钟记一条事实（#62）；排队 5000 件时，心跳从 325 ms 降到 0.2 ms 左右（#70、#73）。 - 接单程序运行中也按时清理旧输出（#82）。 - 只有决定存储内容的文件变了才重建投影（#83）。 ## 感谢 这一版有这些贡献者的 PR：1yu2、abduallahJamal、chenjie1129、KaranocaVe、liuyaanng、Minggnim-jpg、shaojian0514、wsqyouth、wuleiyuan、xiaojian94xiaojian、xiaokekehaha、xiaozefeng、zhangbp7474。 --- The first batch of fixes and improvements since v1.0.0. **From this version on, the installer and `agent-autoloop update` install the newest release instead of following `main`.** If you've already installed, run `agent-autoloop update` twice: the first run pulls the latest `main`, the second settles on the release. The first start rebuilds the projection from the log once, which takes a while with a lot of history. ## Steadier - A plugin's trouble no longer takes the hub down: output it can't read fails only that run, a channel or worker that stops is restarted after 30 seconds, and stray errors are only logged (#79). - With `rules.json` deleted, unreadable or wrong, the old rules keep running and you're told once, even if it broke while the hub was down (#51, #80). - With the database held by another process, what's due is tried again in 5 seconds, and the CLI and the hub can write at the same time (#53, #79). - After 10 failures in a row, automatic retries stop and a card goes to you (#50). - A resumed run that breaks halfway is no longer redone in a new session (#60). - Failing to check on a process no longer counts as the process being dead (#63). - A queued run whose rule was removed or renamed stops and sends a card (#54). - Closing the "worker not connected" card no longer brings it straight back, and work that comes later is still told (#80). - A Feishu listener that can't start is only logged (#26). ## Fixes - Agents couldn't start when the login shell was fish (#22). - Claude's result was missed when printed as a one-line array (#18). - Finding the Claude Code inside the desktop app failed when that folder held files (#78). - Usage was counted twice on resumed sessions (#56), and a run that didn't finish lost its receipt's usage and session (#67). - `join` overwrote existing configuration (#19); `init --help` ran the install (#75); `key remove` couldn't revoke names with capitals, underscores or dots (#39); `try` took the last failure for this one (#23). - `hub.listen` could bind every interface or crash at startup (#41); systemd unit values weren't quoted (#38); `doctor` didn't recognize a system-level service (#74); uninstalling failed on Node 25.1 (#61). ## Security - An expired card link no longer shows the card (#81). - An empty or cut-short `master.key` refuses to start instead of signing links with it (#52). - Requests declaring over 8 MB aren't read (#57), and length limits on answers and channel reports are enforced in the kernel (#40). - `doctor` points out channels without `answerers`, where anyone can answer a card (#84). ## New - A GitLab event source (#29). - Notice cards can take a line about how they were handled (#48). ## Performance - A heartbeat writes at most one fact a minute (#62), and with 5,000 queued a heartbeat went from 325 ms to about 0.2 ms (#70, #73). - The worker clears old output while running, not only at startup (#82). - The projection is rebuilt only when the files that decide what's stored change (#83). ## Thanks This release has pull requests from 1yu2, abduallahJamal, chenjie1129, KaranocaVe, liuyaanng, Minggnim-jpg, shaojian0514, wsqyouth, wuleiyuan, xiaojian94xiaojian, xiaokekehaha, xiaozefeng and zhangbp7474. Repository README (current repository documentation, not release changes) # Agent Autoloop **让你的命令行 Agent 在后台自己接活、自己跟进到底；平时不烦你，遇到拿不准的事才发卡片找你拍板。** **中文** | [English](README.en.md) [上手](#上手) · [场景模板](#拿来即用的场景模板) · [插件](#插件体系四个方向都能自由替换) · [内核](#内核的四个机制) · [文档](#更多文档)  ## 它解决什么问题？ 平时我们用 Claude Code、Codex 这类命令行 Agent，大多是“人守着终端用”：你输一句话，盯着它跑，等它问你下一步；一旦关掉窗口或者人走开，事情就断了。 **Agent Autoloop** 是一个极轻量的自动化中台。它把任务调度做成一个零外部依赖的**内核**，把事件来源、Agent、通知通道，甚至代码上线流水线全部拆成可随时插拔的**插件**。 - **一台电脑、一条命令就能跑。** 装在你的 Mac 或 Linux 上，不用买云服务器，也不用开放公网端口。 - **一行配置接新 Agent。** 不需要 SDK，也不需要改 Agent 源码，能接收提示词并打印最后一条回复的命令行工具都能接。 - **没有后台界面。** 需要你拍板时把卡片推到飞书、钉钉、企微、Slack、Discord 或桌面通知；想看全局进展，敲一行命令。 ## 上手 支持 macOS 和 Linux。运行前需要装好 Node 24、Git、curl，以及任意一个你已经登录好的命令行 Agent，不需要 GitHub 账号。也可以直接把[安装说明](INSTALL.md)丢给你的 Agent，让它替你装好。 > **Windows 版：待定。** 很多朋友在问 Windows 版，我都看到了。我现在人在外面出差，手边没有 Windows 电脑，没法真机开发和测试，所以现在还不能在 Windows 上用。这个周末（11 月 7、8 日）回家后，我会把它开发完，做完兼容性测试，再正式推出。进度会更新在 [#17](https://github.com/KKKKhazix/agent-autoloop/issues/17)。 ```bash curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh ``` 安装和 `agent-autoloop update` 都装最新的 [Release](https://github.com/KKKKhazix/agent-autoloop/releases)，那是通过了全部检查的版本。 装好后用你本机的 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 和费用（[统计口径](skills/agent-autoloop/SKILL.md#看情况回答)）。 ## 一件事怎么转起来 编号和上面的架构图一一对应： 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，先按[说明](skills/agent-autoloop/SKILL.md#接一个事件插件)在 `sources` 里登记 `github`： ```json { "name": "处理 issue", "when": { "source": "github", "types": ["issues.opened"] }, "to": "codex", "cwd": "~/code/app", "skill": "handle-issue", "parallel": 3 } ``` 保存后几秒内自动生效，可以运行 `agent-autoloop check` 检查。就算改错了，或者文件被删、读不到，系统也会继续按旧规则跑，并发卡片提醒你。 ### Agent 怎么跟中台配合？ 中台对 Agent 只有一个约定：**在最后一条回复里交代结果**。事情办完了，正常输出一句结论就行。需要向你请示时，在回复末尾附一段 `agent-autoloop` 代码块： ````text 订单已经核对完毕，库存充足。 ```agent-autoloop { "ask": [{ "title": "怎么发货？", "text": "两种方式今天都能发出。", "options": ["快递", "自提"], "key": "shipping" }] } ``` ```` 除了提问（`ask`），还能发通知（`notice`）、关闭已解决的卡片（`resolve`）、预约复查（`later`）和触发新事件（`events`）。通告不需要回答，但结案时可以顺手写一句处理说明，这句话会留在卡片上。万一 JSON 写错了，中台只让它在原会话里重写最后这段回复，不会把已经干完的业务重做一遍；重写也失败时，保留原结论并通知你回执没有生效。接着旧会话跑也一样：会话接不上才开新的；接上了、干到一半断了，就算没跑成，过几分钟回到原会话重试，不开新会话重做。 ## 拿来即用的场景模板 每套模板都带规则、任务 Skill 和启用说明。 | 想做什么 | 已经封装好的流程 | |---|---| | [每日早报](examples/recipes/morning-brief/README.md) | 默认每天 8 点整理本地笔记和 Git 提交，写入 `briefs/YYYY-MM-DD.md` | | [跟进 GitHub Issue](examples/recipes/github-issues/README.md) | 每 5 分钟查新 Issue，在本地改代码并通知你查看；不提交、不推送、不回复 Issue | | [线上告警排查](examples/recipes/ops-alerts/README.md) | 接收报错、对照代码查原因，需要重启时发卡片询问，回答后继续 | | [用户反馈处理](examples/recipes/feedback/README.md) | 重读反馈当前状态、修复、交付核实、准备回复；需要决定时飞书问你，回答后继续 | | [网站巡检](examples/recipes/website-watch/README.md) | 每 5 分钟检查状态和关键内容，首次异常交给 Agent，持续异常不重复通知，恢复后更新原卡片 | | [飞书周报与业务摘要](examples/recipes/feishu-brief/README.md) | 周日 18 点按你的权限读汇报和指定表格，生成本地摘要；飞书只发简短摘要，完整稿留在本机 | | [PR 自动交付](skills/agent-autoloop/SKILL.md#交付流水线) | 打上 `deliver` 标签后，审查、等 CI、合并、等发布并核对线上版本 | **启用：** 打开对应说明，把任务 Skill 放进所用 Agent 的 skills 目录，把示例规则合入 `~/.agent-autoloop/rules.json`，替换电脑名和路径，再运行 `agent-autoloop check`。 反馈处理、网站巡检和飞书摘要默认使用北京时间，只发给本人的飞书私聊。样例数据都是虚构的；脚本和回执只用本地 HTTP 与假飞书 CLI 验证过，没有在真实账号上跑过完整业务。 更多模板：[Claude 委托 Codex 处理网页](examples/recipes/browser-handoff/README.md)、[每周代码清理](examples/skills/weekly-sweep/SKILL.md)、[交付 PR](examples/skills/ship-pr/SKILL.md)。 ## 插件体系：四个方向都能自由替换 内置插件随程序安装，填好配置即可启用；第三方插件用 `agent-autoloop add ` 安装。 | 方向 | 内置 | 配置 | |---|---|---| | **事件**：怎么发现新活 | [GitHub Webhook](plugins/github/source.ts)、[GitLab Webhook](plugins/gitlab/source.ts)、[HTTP 接口](docs/protocol.md#来源把世界变成事件)、[定时规则](skills/agent-autoloop/SKILL.md#改规则)、[Issue 轮询脚本](examples/watch-github-issues.sh) | [说明](skills/agent-autoloop/SKILL.md#接一个事件插件) | | **Agent**：谁来干活 | [Claude Code](plugins/claude/agent.ts)、[Codex](plugins/codex/agent.ts)、[ACP](plugins/acp/agent.ts)、[通用命令](plugins/command/agent.ts) | [说明](skills/agent-autoloop/SKILL.md#接一个-agent) | | **通道**：去哪找你拍板 | [桌面通知](plugins/desktop/channel.ts)（默认开启）、[飞书](plugins/feishu/channel.ts)、[钉钉 / 企微 / Slack / Discord](plugins/webhook/templates.ts) | [说明](skills/agent-autoloop/SKILL.md#接一个通道) | | **交付**：把 CI/CD 也做成插件 | [`delivery`](plugins/delivery/delivery.ts) | [说明](skills/agent-autoloop/SKILL.md#交付流水线) | **实测情况：** Claude Code、Codex 和 ACP（官方 Codex ACP 适配器）跑通了多轮问答和跨进程会话续接；飞书跑通了发送、按钮回调和卡片更新；四种 Webhook 模板只在本地模拟服务上验证过，GitLab Webhook 按官方文档的格式测试，没连过真实 GitLab。这些文字通道靠回答链接拍板，要把 `hub.publicUrl` 配成手机或电脑能打开的地址。 **其他命令行 Agent 一行接入。** 设置 `use: "command"` 并传入命令数组，`{prompt}` 作为独立参数传递，不会被当成 shell 代码执行。下面的命令整理自各家官方文档，我们还没有逐个跑过： | Agent | 接入命令 | |---|---| | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cli-help.md#dsh-headless) | `dsh --profile headless {prompt}` | | [pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md) | `pi --print {prompt}` | | [OpenClaw](https://docs.openclaw.ai/cli/agent) | `openclaw agent exec {prompt}` | | [Hermes](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | `hermes chat -q {prompt}` | | [Cursor](https://cursor.com/docs/cli/reference/parameters) | `agent -p --trust {prompt}` | | [WorkBuddy / CodeBuddy](https://www.codebuddy.ai/docs/cli/headless) | `codebuddy -p {prompt}` | **交付流水线。** 给 GitHub PR 打上 `deliver` 标签后，它会自己跟进到上线：**审代码 → 等 CI → 合并 PR → 等部署 → 核对线上版本**。审查和交付配置只从 `main` 读取，绝不在接单电脑上检出或运行 PR 里的代码；排队、并发和重试直接复用内核。 **写自己的插件。** 从 [Agent](examples/plugins/hello-agent/agent.ts)、[通道](examples/plugins/hello-channel/channel.ts)、[事件](examples/plugins/hello-source/source.ts) 三个可运行的最小模板开始，见[插件开发说明](docs/plugins.md)。要让 Agent 操作网页，先看[浏览器接入](docs/plugins.md#浏览器接入)。命令行和 [MCP](skills/agent-autoloop/SKILL.md#mcp-与密钥撤销) 也能查看和回答卡片。 ## 内核的四个机制 内核约 1800 行代码、零运行时依赖。它不读系统时钟、不用随机数、不向外发请求，插件主动连进来，账号凭据留在各自的插件里；同样的输入永远得出同样的结果。它把四个计算机领域的成熟做法用到了命令行 Agent 上： - **挂起零消耗**：等你拍板时进程直接退出，等待状态存在数据库里，Agent 不用一直挂着。你三天没回，这三天就没有 Agent 进程在跑、不花 Token，只有很轻的中台在后台等着；你一回答，它接着原来的对话继续干。 - **事件溯源**：所有状态都从一条只追加的日志算出来，日志和索引在同一个事务里写进磁盘，写完才应答。进程被强杀，已经确认的事不丢（整机断电没有单独测过）；任何一轮为什么跑、结果是什么，一条命令就能查清；数据格式变了就从日志重建，不用写迁移脚本。 - **指令数据分离**：思路和 SQL 参数化一样。Issue 的标题和正文等外部文字只作为资料放进文件，不拼进提示词，提示词里只有校验过字符的类型、编号和链接；用哪个 Agent、在哪个目录、什么权限，只由你本机的规则决定，事件里带 `cwd`、`agent`、`access` 字段会被直接拒收。 - **跳数熔断**：思路和网络包的 TTL 一样。Agent 交回的事件会再派给 Agent，层数一路累加，经过人工提问和定时复查也不清零，Agent 自己改不了；超过 8 层就只记录、不再派活，并发一张卡片告诉你。 ### 自己跑一遍 在程序目录 `~/.agent-autoloop/app` 下运行： | 验证什么 | 命令 | |---|---| | 任何一轮的来龙去脉 | `agent-autoloop why 1` | | 20 万步模拟断网、丢包、崩溃和重复提交，一个种子就能复现 | `node sim/random.ts 24301 200000` | | 强杀进程 1000 次，已确认的记录一条不丢 | `node sim/crash.ts 1000 12648430` | | 下面的性能数字 | `npm run benchmark` | ```text 第 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。写入逐条提交，事务落盘后才应答。`npm run benchmark` 的达标线按这台机器定，换台机器可能报未达标。 | 指标 | 实测 | |---|---:| | 冷启动 | 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 | | 内核行数（含空行和注释） | 1651 | | 运行时依赖 | 0 | 历史变大后，状态汇总会变慢，日志和索引也继续占磁盘；格式变化后的首次启动要从日志全量重建，110 万条用时 43.1 秒。[完整数据和测法](docs/protocol.md#历史增长实测)。 ## 用量与合规说明 中台直接调用你本机已经安装并登录好的命令行工具，不会读取或转存你的账号凭据。模型调用消耗算在你自己的账号名下，额度和使用范围遵循各家模型厂商的服务条款。 在高频自动化场景下，各家厂商通常更建议使用 API Key（个人订阅额度主要是为日常人工交互设计的，详见 [Anthropic](https://code.claude.com/docs/en/legal-and-compliance) 与 [OpenAI](https://learn.chatgpt.com/docs/auth) 的官方说明）。如果你用它对外提供服务，请使用 API Key。本项目为独立开源项目，与上述厂商无隶属或背书关系。 ## 更多文档 - [安装说明](INSTALL.md) - [规则与交付流水线配置手册](skills/agent-autoloop/SKILL.md) - [如何编写插件](docs/plugins.md) - [完整通信协议](docs/protocol.md) - [安全边界说明](SECURITY.md) - [参与贡献与交流](CONTRIBUTING.md) - [项目开发约定](AGENTS.md) 仓库目录 | 位置 | 放什么 | |---|---| | `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/` | 性能与真机验证、安装冒烟脚本，以及 Linux / macOS CI | | 根目录文档与 `install.sh` | 中英文 README、安装说明、安全边界、开发约定、许可证与安装脚本 | 读代码可以从 `bin/agent-autoloop.ts` → `cli/main.ts` 开始，再按功能进入 `host/`、`worker/` 或 `plugins/`；内核设计先看[协议](docs/protocol.md)。同名文件分属不同层：`host/http.ts` 转换 Node 请求，`kernel/http.ts` 定义接口行为；`protocol/rules.ts` 校验输入，`kernel/rules.ts` 定义规则类型和匹配。 [MIT License](LICENSE)