设计取舍

本页总结 Awaken 几个关键架构决策及其权衡。

Snapshot Isolation vs Mutable State

决策：phase hook 只读不可变 Snapshot，写入 MutationBatch，所有变更在 gather 结束后原子提交。

备选：hook 直接修改共享可变状态。

	Snapshot Isolation	Mutable State
正确性	不依赖 hook 执行顺序	容易受锁粒度和顺序影响
并发性	hook 可安全并行	需要精细锁或强制串行
复杂度	需要 batch / merge / conflict machinery	实现直观
可调试性	每个 phase 边界都是清晰状态跃迁	状态变化交织，难追踪
代价	每次 phase 快照需额外 `Arc` clone	无快照开销

为什么选 Snapshot：插件组合不应该依赖隐藏顺序。快照模型让 phase 更接近“状态到变更”的纯函数，便于推理和重放。

决策：执行遵循固定 phase 顺序。

备选：完全事件驱动，插件异步订阅事件。

为什么选 Phase：agent 执行天然是“推理 -> 工具 -> 检查终止”的顺序流程。phase 模型更适合在固定节点上插入权限、观察、提醒和请求变换。

决策：状态键是 Rust 类型，必须实现 StateKey。

备选：HashMap<String, Value> 风格的动态状态。

为什么选 Typed Keys：状态错误往往非常隐蔽。把键名、值类型和更新语义统一固化在类型上，更适合作为运行时核心机制。

决策：使用 PluginRegistrar 做结构化注册，而不是用 middleware 链包裹整条执行路径。

备选：类似 HTTP middleware 的包裹链。

	Plugin System	Middleware Chain
粒度	能分别注册 hook / key / tool / effect	只能包整个执行
组合	多插件可共享同一 phase	顺序高度敏感
选择性激活	可按 agent 启停插件	需要改链结构
复杂度	注册动作较多	心智模型简单
横切关注点	天然契合——每个插件处理一个关注点	每个 middleware 处理一个关注点，但会看到全部流量

为什么选 Plugin System：Awaken 的扩展点并不只在单一调用链上，而是散落在 phase、tool 拦截、state、effects、actions 等多个边界。

决策：同一个 server 同时提供 AI SDK v6、AG-UI、A2A、MCP HTTP，ACP 则作为独立 stdio 协议模块存在。

备选：只支持一种标准协议。

为什么选 Multi-Protocol：当前 agent 生态没有统一协议。把协议复杂度压在 server 层，比要求用户自写桥接更实用。