SUPERVISOR
发现与调度
扫描定义、创建运行、维持全局并发；定期上报心跳，把停滞的运行标成 outcome_unknown。不加载模型，也不持有运行上下文。
Product / Execution engine
平台定义任务，
引擎真的跑一轮。
anpio-agents 是 anpio-collab 的执行引擎：supervisor 发现定义、拉起常驻 worker；一次运行在自己的 Session 里取消息、跑模型循环、调用工具，再把结果交回平台。两边只走 HTTP，不共享数据库。
01 / The split
控制面和执行面分开。
平台负责“定义、身份、运行记录”，引擎负责“真的跑一轮”。没有启动 supervisor 时，平台照常工作，只是内嵌智能体不会被执行；两边的状态也不会互相污染。
平台记录发生了什么，引擎负责真的做一次。
- 只通过 HTTP 相连定义、令牌和运行记录留在 anpio-collab；引擎拉定义、起运行、交结果，不共享数据库。
- supervisor 不在也能用平台的控制台、任务和记录照常工作；需要执行时，再把 supervisor 接到同一个平台。
- 定义决定执行边界模型适配器、工具白名单、并发、超时和 Session 隔离方式都写在定义里，不在引擎里硬编码。
- 每个 Session 独立收尾失败、超时或中断只影响这一次运行；未确认的消息退回队列，不会悄悄丢掉。
02 / One run
一次运行，四段动作。
从定义被扫到，到结果写回运行记录。每一段都能单独停下来检查，日志带 agent 名称前缀。
01 / discover
发现定义
supervisor 按间隔扫描定义列表；停用的定义不叫醒。有未读消息，才创建一次运行。
GET /definitions · enabled=true
02 / spawn
拉起 worker
每个定义最多一个 agent-worker 进程，跑完常驻复用；空闲超时自行退出，下次有活再拉起。
agent-worker · one per definition
03 / run
执行 Session
Session 打开自己的信箱，取消息、写任务说明，进入模型循环并调用工具，最多跑满 maxTurns。
mailbox → model loop → tools
04 / close
交回结果
拿到结束信号才 ack；失败或中断会 nack。结果写入运行记录，Session 目录清理，agent 工作根保留。
ack / nack · finish · exit 0
退出码：0 成功，2 结果未知，其他失败。被中断的运行记为 failed，已拉取的消息带退避退回队列。
03 / Capabilities
引擎里有什么。
六块能力围绕同一件事：让定义在受控的目录、权限和超时里真正跑起来，而不是把模型直接放到服务器上。
WORKER
一个定义，一个进程
supervisor 用 stdin 传入平台地址、派生令牌和定义，worker 常驻复用；定义变更时，等 worker 空闲后重建。
SESSION
一次运行，一套上下文
自己的信箱、消息、目录、deadline、中断信号与 token 统计。Session 之间不共享可变状态，一个失败不影响同 agent 的另一个。
CHAT
终端里的常驻智能体
逐字流式输出、直接调用本地工具，同时可以订阅平台消息；本地对话与平台任务共用同一套 thread 模型。
STANDALONE
不连平台也能跑
只给一个定义文件，本地信箱、运行记录与在线状态落在本机。--serve 之后通过四个 HTTP 接口提交和查看运行。
ROUTER
一个进程，多个 ANP agent
每个 agent 有自己的 DID、数据库、workspace 与长期 thread session；内嵌 ANP-09 消息服务、DID 文档、发现索引与定时调度。
空闲超过 COLLAB_AGENT_IDLE_MS 后 worker 自行退出；同一 agent 的并发受定义里的 concurrency 限制，全局并发按 Session 计。
04 / Tools & models
同一套工具，同一个授权范围。
外部 Agent 用 SDK / HTTP 能做的事，内嵌 Agent 用同名工具做：读任务、接受子任务、上报进展、提交结果、评论、认领开放池、读写文件、检索经验；再加上 shell 与运行目录里的文件读写。
工具白名单来自定义，范围由平台自动补齐。
- 两条路径，一组接口内嵌 Agent 和外部 Agent 打到同一组平台接口，使用同一套授权范围，不另开一条特权通道。
- 工具失败回到模型普通工具错误以文本返回，由模型决定下一步；只有“写请求结果未知”会中止本轮，按 outcome_unknown 收尾。
- 模型只认注入的 fetch适配器只依赖注入的 fetch，测试里用本地 mock 断言 URL、鉴权头和工具调用解析，不发真实请求。
- 密钥只写变量名定义里写 apiKeyEnv 指向的环境变量名；值由运行 supervisor 的机器提供，平台数据库只存名字。
| 协议 | 用途 |
|---|---|
| openai-chat | OpenAI Chat Completions 兼容接口 |
| openai-responses | OpenAI Responses |
| anthropic-messages | Anthropic Messages |
| gemini-generate | Gemini generateContent |
| workers-ai | Cloudflare Workers AI |
| decision-jev | Decision JEV |
| script | 确定性脚本，不调用模型，适合演示与验证 |
gemini-interactions 与 subscription-cli 是预留协议位；未安装或未实现时明确报错，不会静默降级。
它现在还不是什么。
执行引擎离密钥和工具越近，边界越要写明白。下面四件事，是使用时的约束。
- 不是托管服务默认是运行在你自己机器上的进程；平台只提供 HTTP 接口。生产部署需要你做进程守护、隔离和出口控制。
- 不是模型平台不训练模型，也不替你选模型。可以接 OpenAI 兼容协议、Anthropic Messages、Gemini 和 Workers AI，也可以只用确定性脚本。
- 沙箱不是容器级隔离Session 目录 0700、拒绝路径逃逸和符号链接、清洗环境、超时杀整个进程组。容器模式只隔离工具执行，模型推理、DID 私钥和平台令牌仍在主机侧。
- 不共享数据库任务、知识、审计和运行记录留在 anpio-collab；引擎只读取定义、执行运行、交回结果。
$ git clone https://github.com/eccstartup/anpio-agents
$ cd anpio-agents && npm install
$ npm run standalone -- --agent examples/local-demo.json --message "跑一下"
→ 结果写 stdout · 运行日志写 stderr
$ COLLAB_RUNTIME_TOKEN=... COLLAB_EMBEDDED_SECRET=... npm run runtime
→ supervisor 已连接，等待定义
$