Appearance
Host 设计建议
这一页的目标不是解释概念，而是回答一个更实际的问题：
如果你自己要做一个 agent host，到底该接哪一层。
先看你在做什么产品
| 产品形态 | 优先考虑 |
|---|---|
| shell 工具 / CI / 批处理 | exec 类接口 |
| IDE / editor | ACP 或 app-server 类协议 |
| gateway / 多模型路由层 | provider API 或桥接协议 |
| daemon / 本地自动执行器 | CLI JSON stream 或 app-server |
什么时候选 provider API
适合：
- 你主要想统一不同模型
- 你不需要上游 agent 的本地工具语义
- 你要做路由、配额、账单、权限边界
不适合：
- 你想复用上游现成 agent runtime
- 你想拿 thread / turn / approval 级事件
什么时候选 CLI JSON stream
适合：
- 上游已经提供结构化 stdout 事件
- 你的产品是 daemon 或后台任务系统
- 你要快速接入，且不想维护长期 server 协议
典型例子：
text
host -> claude --output-format stream-json优点：
- 接入快
- 调试直观
- 运维简单
缺点：
- 生命周期控制有限
- 很多高级语义要靠上游 CLI 额外暴露
什么时候选 app-server / JSON-RPC
适合：
- 你要更强的宿主控制权
- 你需要 thread / turn / item / approval 语义
- 你在做长期运行的本地 runtime 接入
典型例子：
text
host -> codex app-server --listen stdio://优点：
- 控制面更强
- 状态更结构化
- 更适合宿主产品
缺点：
- 集成复杂度更高
- 你要自己实现协议侧适配
什么时候选 ACP
适合：
- 你在做 IDE 或通用 agent host
- 你希望外部 agent 都走同一宿主协议
- 你要把 prompt、approval、tool use、terminal、resume 统一成一套 UI
优点：
- 宿主和 agent 解耦
- 适合多家 agent 并存
- 长期看生态价值更大
缺点：
- 需要 adapter
- 不是每家上游 runtime 都天然支持 ACP
一个很实用的决策顺序
不要先问“哪个协议最先进”，要先问：
- 上游已经给了我什么最稳定的机器接口？
- 我需要多强的宿主控制权？
- 我是在做本地产品、IDE，还是中间层网关？
- 我有没有能力自己维护一个 adapter？
对应到本文几个例子
如果你做的是类似 Multica 的 daemon
优先顺序通常是：
- 上游有成熟 CLI JSON stream，就先接这个
- 如果上游有 app-server 且你确实需要强控制，再接 app-server
- 不要为了“看起来高级”硬上 ACP
所以：
Claude Code走 CLI stream 很合理Codex走 app-server 也很合理
如果你做的是类似 Zed 的 IDE
优先顺序通常是：
- 统一宿主协议
- 外部 agent 全部通过 adapter 进来
- 把 UI、审批、会话恢复、diff 等能力放在宿主层
所以 ACP 思路更自然。
如果你做的是类似 OpenClaw 的 gateway
优先顺序通常是：
- 先统一 provider routing
- 再按需要补 ACP bridge 或外部 harness orchestration
所以 OpenClaw 可以同时有：
- 直连 provider
- 作为 ACP bridge
- 反向拉起外部 agent
常见误判
误判 1
“支持某个 agent” 就等于 “直接调它的模型 API”。
不对。你可能是在：
- 调 provider API
- 拉 CLI
- 拉 app-server
- 通过 adapter 嵌入 runtime
误判 2
“ACP 一定比 CLI 好”。
不对。要看产品形态。
对 daemon 来说，CLI JSON stream 往往更快落地。
误判 3
“有 --json 就说明不需要更底层协议”。
不对。--json 解决的是输出结构化，不一定解决会话控制。
建议的最小实现路线
如果你要从零做一个 host，建议按难度从低到高走：
- 先接 provider API 或 CLI JSON stream
- 把宿主内部事件抽象统一起来
- 再根据需要引入 app-server 或 ACP adapter
不要一开始就做最重的协议层，否则很容易在“协议正确性”上花太多时间，而不是先把产品跑通。
最后一句话
选型的正确顺序是：
先看产品形态，再看控制需求，最后才看协议名词。