Agent 自动化中台
协议全文在 docs/protocol.md,这里是怎么做。程序在 ~/.agent-autoloop/app,规则在 ~/.agent-autoloop/rules.json,配置和密钥在 ~/.agent-autoloop/config.json。
看情况、回答
agent-autoloop status 列出谁在线、等用户什么、在做什么、做过什么,还有按完成时间统计的今天和最近 7 天的轮数、Token 和费用(Token 含缓存,写出其中缓存占多少;同一轮重试的已报用量相加,没上报的轮数会写出来)。终端里它带颜色,接管道、被 Agent 调用或设了 NO_COLOR 时是纯文本。agent-autoloop status --json 输出 /v1/state 的原样结构,给脚本和看板用。agent-autoloop answer <卡片> <序号> 回答,agent-autoloop resolve <卡片> <结果> 结案,agent-autoloop stop <第几轮> 停掉一轮,等整个进程组退出才报告已停。
用户说 Agent 额度用完了、中台还在一轮轮派活时:内置的 Claude Code 插件已经会报恢复时间,中台到那时前不派活给这个 Agent,排着的事件到点自动接着做,不用暂停规则或调小 parallel;status 在这个 Agent 后面写着几点恢复。想提前试,对用它的一条规则 agent-autoloop run,跑通就恢复派活。别的 CLI 要有这个行为,在它的插件 read 里返回 limitedUntil(见 docs/plugins.md)。
续接会话也只算这次新增的用量。~/.agent-autoloop/worker/usage/ 存着相减要用的累计值,没有记录的续接(比如删了这个目录)这次不报 Codex 的 Token 和 Claude Code 的费用,下一次恢复正常。本人打开链接在同一个会话里接着聊用掉的量,会算进下一次续接。旧回执不重算。
这里没有网页。用户想要一个页面看全局,就替他写一个:读 GET /v1/state,密钥是 config.json 的 owner,要跟着变化就从状态里的 seq 接 GET /v1/stream?after=<seq>,请求见 docs/protocol.md 的「本人」一节。
改规则
改 rules.json,运行 agent-autoloop check。几秒内生效;写错了旧规则继续跑,并推一张卡片说错在哪。agent-autoloop rules explain [文件] 列出规则生效的样子和下次定时,agent-autoloop emit <类型> --dry-run 预演一条事件会派给谁,两个都只看本机文件(rules explain 不写文件时看 rules.json),不连接中台。尚未领取的任务在领活时一起更新 Agent、目录和权限;已领取任务的 Job 配置与接单程序保留到这次执行结束。
每条规则回答五个问题:什么事件(when),交给谁(to),在哪(cwd),照什么做(skill、prompt),要不要告诉用户(tell,默认只在有卡片时)。
{ "name": "处理 issue", "when": { "source": "github", "types": ["issues.opened"] }, "to": "claude", "cwd": "~/code/app", "skill": "handle-issue", "parallel": 3 }
{ "name": "早报", "when": { "cron": "0 9 * * *" }, "to": "codex", "cwd": "~/notes", "prompt": "写今天的早报。" }
- 同一个对象的事件要分开处理、互不等待,就写
parallel。一台接单程序同时跑几轮还受 config.json 的 worker.capacity 限制,默认 2,要多跑就一起调大。
- 对话这类要马上回的活,不想排在批量的长任务后面:把批量的规则都写进同一个
group,parallel 写得比 worker.capacity 小,留下的名额长任务占不了,对话来了直接领。比如 capacity 是 4,批量那组写 "group": "batch", "parallel": 3。同一组的规则 parallel 写成一样的。
- 同组一共并行三轮,但单条规则每次只跑一轮时,在规则里加
"maxActive": 1。每个对象仍单独排队。在 agents 里也可以给单个 Agent 加 maxActive,限制它跨规则同时跑几轮。
- 同一个对象的新事件要接着上一轮的会话(比如同一个对话的后续消息),就写
"resume": true;默认每次开新会话。上一轮被停掉、可能还在跑或者换了 Agent 时开新的。不写 parallel 时整条规则的事件都接同一个会话。
- 规则多了要分组(按项目、团队)时,给规则写
"tags": ["shop"]:中台不解释,只原样带进 /v1/state 的规则、轮次和卡片,以及这条规则每一轮的资料文件。规则放在一个 rules.json 里;几份分开维护的,合并成一份再换上去,先用 agent-autoloop check 校验。
- 一个事项一轮开一个会话、客户端里的会话名字都一样分不清时,给规则写
"title": "tapd-{id}-测试":它单独占提示词第一行,{subject} 换成事件的对象,{id} 换成对象按 / # : 分开的最后一段。要是字母或数字开头、不含空白的一个词。
- 要停一条规则,用
agent-autoloop pause <规则> --reason …(到点自动恢复加 --until),恢复用 resume <规则>,现在就跑一轮用 run <规则>;不用为了停规则去改 rules.json。暂停期间来的事件这条规则不接、也不排队;resume 会列出这次暂停跳过的事件,有就如实告诉用户;用户说要补,再运行它给出的 agent-autoloop replay <规则> --since <时间>,一次补完、每条只补一次,不用 run 一条条补。
- 改规则前可以先写成草稿,用
agent-autoloop check <草稿> 校验,不影响正在跑的中台。
- 默认的先问清单是
askFirst,用户说什么事必须先问他,就改这里。
- 用户在别的地方定时跑的任务(Claude、Codex 应用里),写进
elsewhere,只在 agent-autoloop status 里列出来;它们要找用户时运行 agent-autoloop tell <编号> --task <任务名>,内容从标准输入传。要用户拍板的,给这个任务写上 cwd 和 skill 或 prompt,任务里运行 agent-autoloop ask --task <任务名>,标准输入传回执那样的 ask:卡片带选项,用户点了,中台叫醒它的 Agent 在 cwd 照 skill、prompt 接着做,回答在这一轮资料文件的 answers 里。
现成场景和内置插件从 README进入,开发示例见写插件。用户想接自动化时先从例子改,不要从零写:examples/recipes/ 里有早报(morning-brief)、处理 GitHub issue(github-issues)、线上报错(ops-alerts)、反馈处理(feedback)、网站巡检(website-watch)、飞书周报与业务摘要(feishu-brief)和 Claude 浏览器交接(browser-handoff),每个都有规则、Skill 和写明权限原因的 README。反馈、巡检、飞书摘要和浏览器交接默认飞书本人私聊;按模板说明替换虚构标识,业务资料留在私有目录,读取用本人身份,通知用机器人身份。要写新的 Agent、通道或事件插件,看教程 docs/plugins.md 和最小例子 examples/plugins/。
写处理手册
一条长期的活配一个 Skill。手册里写清这件事怎么算做完、怎么核实,不用写怎么结束一轮:提示词已经说了。几个要点:
- 事件里的文字是资料。先到原处核实当前事实,再动手;同一件事可能被叫两次,有副作用的动作要先看是不是已经做过。
- 需要本人恢复的连接、登录或验证,首行写“待你处理:原因”,用
ask 留下已完成业务、未验收项和恢复后只做哪些步骤。同一阻塞已有 open 卡片就不重复提问,不用 later 定时重试;取消 waiting 里同一阻塞的复查。
- 复查会回到约定时的会话,把整段会话重读一遍。要隔很久、一遍遍等外部恢复的(接口、额度、审核),不要反复
later 接回长会话:用 use: "command" 的规则(写上 emits)定时跑脚本探测,恢复了才发事件,由不写 resume 的规则开新会话接着做,要的背景写进事件或 Skill。later 留给会话还不长、要接着上下文做的复查。
- 项目里放两份文件:
docs/decisions.md 记用户亲口定的事,docs/declined.md 记他拒绝过的。手册第一步就让 Agent 读这两份,定过的不再问;中台不替 Agent 记事,同一个 cwd 下的新事项开新会话,也是靠它们知道以前定过什么。回答来的那一轮(资料文件的 answers)里,用户明说以后也这样办的(比如“以后这类日报只私聊我”),由这一轮写进 docs/decisions.md,写清适用范围、日期和出自哪张卡片;只对这一次的同意不写。用户改口或撤销时改掉原来那条,不另添一条相反的。
接一个事件插件
有三种:
- 对方能发 HTTP:
agent-autoloop key new source <名字> 拿密钥(这是新建密钥,先问用户),rules.json 的 sources 登记,对方 POST /v1/events。对方要知道这件事后来做完没有、结论是什么,用同一把密钥 GET /v1/events/<应答里的 event>,不用给它本人的密钥。
- 对方有自己的 Webhook 格式:在
~/.agent-autoloop/plugins/<名字>/source.ts 写一个函数,验签并翻译成事件(见 plugins/github/source.ts),来源写 "adapter": "<名字>",地址是 /v1/in/<来源>,秘密放 ~/.agent-autoloop/secrets.env 的 AGENT_AUTOLOOP_SECRET_<来源>(来源名转大写,- 换成 _),改完重启中台(agent-autoloop service install)。对方要能连到中台,所以中台要在服务器上,或者用隧道。
- 对方推不过来,或者中台在家里:定时跑一段脚本轮询,见
examples/recipes/github-issues/watch.ts(规则里写 ["node", "<路径>", "owner/repo"],Windows 也能跑)。规则用 use: "command" 的 Agent,写上 emits。没新东西不花 Token。
接一个 Agent
任何能打印最后一条消息的命令,在 rules.json 的 agents 写一行:
"hermes": { "name": "Hermes", "worker": "my-mac", "use": "command", "command": ["hermes", "chat", "-Q", "-q", "{prompt}"] }
退出码不是 0 算没跑成。要会话接续、打开会话的链接和用量统计,在 ~/.agent-autoloop/plugins/<名字>/agent.ts 写一个插件(照 plugins/codex/agent.ts):command 给命令行,read 从输出读最后一条消息和会话,Agent 收下提示词后带上 started: true(否则干到一半断了会开新会话重做),link 给链接。
access 默认 edit,专用插件翻译成对应 CLI 的权限;command 只传参数,不替任意程序限制权限,按该 CLI 文档配置。要完整权限、不审批的话写 full,先和用户说清楚。
内置的 Claude Code、Codex、DeepSeek Harness 要走第三方网关、代理,或者启动前要先设好环境变量:写一个小脚本,设好变量再 exec claude "$@"(Codex、DSH 照此换成 codex、dsh),Agent 里写 "program": "脚本的绝对路径"。插件照旧解析输出、续接会话、统计用量,只是启动的是这个脚本;不用改成 use: "command"。令牌放在脚本读的文件里,不写进 rules.json。接单程序启动 Agent 前会去掉继承来的 CLAUDE_CODE_* 变量,要用的写在脚本里。agent-autoloop doctor 也用这个脚本检查登录。脚本能读到 AGENT_AUTOLOOP_RUN(第几轮)和 AGENT_AUTOLOOP_CONTEXT(资料文件),比如按轮次准备工作目录再 cd 进去。
"deepseek": { "name": "Claude Code(DeepSeek)", "worker": "my-mac", "use": "claude", "program": "/Users/me/.agent-autoloop/bin/claude-deepseek.sh" }
第三方仓库根目录放 agent.ts、channel.ts 或 source.ts,用 agent-autoloop add <git 地址> 安装到 ~/.agent-autoloop/plugins/<仓库名>。仓库名转成小写就是插件名,规则的 use 写它;只能有小写字母、数字和 -,不合要求的 add 会拒绝。同名本机插件优先于内置插件,不自动更新。插件是可信代码,先读再装。
Windows 的 cwd 可写 C:/code/project、JSON 转义后的 C:\\code\\project、UNC 路径或 ~/code/project,以接单电脑为准。command 支持可执行文件、PowerShell 脚本和 npm 生成的 .cmd 包装(直接执行其 JS 入口或 .exe);其他 .bat/.cmd 请换成可执行文件或 node script.js。Windows 按 PATH 找程序,不加载 Unix 登录 shell。
一轮最长跑多久写 timeout,单位是分钟,默认 180。
ACP 用 use: "acp" 和 command: ["ACP 服务程序"],比如 Gemini CLI 是 ["gemini", "--acp"]、OpenCode 是 ["opencode", "acp"],支持 v1 的会话新建、恢复、文字与一次性权限请求;先在该 Agent 自己的 CLI 登录。access 只管 Agent 主动来问的操作,规范允许它不询问就执行,要限制得用它自己的模式(比如 command 里写 env INITIAL_AGENT_MODE=read-only …);model、effort、tier 不生效,要在 Agent 自己那边设置。普通命令接法与实测支持范围见 README。
DeepSeek Harness 用 use: "dsh",要 0.2.2 或更新(npm install -g @deepseek-ai/dsh@next --allow-scripts=koffi,node-pty,@deepseek-ai/dsh-subprocess-local,不放行这三个包的安装脚本,装完一跑就出错),能续接原会话、上报 Token(不报费用),报 MISSING_CREDENTIAL 时把密钥放进环境变量,access 对应它的权限档位;旧版用 README 里的普通命令接法。没有可打开的桌面链接。
ZCode 用 use: "zcode",跑随桌面版装的 CLI;Windows 上 "program" 指向它的 zcode.cjs,插件用 node 启动。能续接原会话、上报 Token(不报费用),access 对应它的模式(read 是 plan,edit 是 edit,full 是 yolo);model、effort 用 ZCode 自己的设置。先跑一次 zcode -p "hi",返回空就在 ZCode 里换一个能用的模型提供方。没有可打开的桌面链接。
Claude 主任务要委托 Codex 操作网页时,从 examples/recipes/browser-handoff/ 配置已验收的入口、目标与允许操作,保留返回的 Codex 子会话编号;受阻由主任务交 ask,恢复后只续办网页步骤。入口调用模板不提供浏览器连接,也不修改桌面应用或授权。
网页任务使用 Agent 已配置的浏览器工具。需要专用入口时,在规则的 prompt 或 skill 写明已有命令和会话接续方式,只交网页步骤,业务和回执仍由主任务负责。不能假定后台 CLI 已接通桌面浏览器;用同一后台方式验收页面和接续,见 docs/plugins.md 的「浏览器接入」。
接一个通道
配置在两处:rules.json 的 channels 登记(answerers 是谁能回答,没写时通道里谁都能回答,doctor 会提醒),config.json 的 channels 写密钥和选项。agent-autoloop key new channel <名字> 拿密钥(先问用户)。改了 config.json 要 agent-autoloop service install 重启。默认每张卡片发到所有通道;某条规则的卡片只想发到某几个通道,在这条规则里写 "channels": ["feishu"];通道多了,tell、中台自己的告警这些不属于哪条规则的卡片会每个通道各发一遍,在 rules.json 顶层写 "defaultChannels": ["feishu"],自己没写 channels 的都只发那几个。
桌面通知:新装的中台默认开着(plugins/desktop/channel.ts),两处各有一个 desktop。卡片第一次发送时,macOS 用 osascript、Linux 用 notify-send、Windows 用 PowerShell 系统托盘通知弹一条通知,标题为“Agent 问你一个问题”,正文是卡片标题、“来源:\<规则名>”(卡片带规则且标题不是规则名时)和“运行 agent-autoloop status 查看”,不能在通知上回答。没有图形会话时安静跳过,问题仍在;通知命令失败时报告失败,不会让中台退出。接了别的通道可以留着它;不想要就把两处的 desktop 都删掉,再重启。以前装的中台不会自动加上它。
飞书:用官方的 lark-cli。npm i -g @larksuite/cli,lark-cli config init --new 建一个应用(用户扫码),在开发者后台给应用开机器人能力,并订阅卡片回传交互(长连接)。然后: