12. 风险区域与设计取舍

12.1 高耦合区域

• agent-loop 与 session/system-prompt/tools/llm 高度耦合，但耦合点在服务接口，而不是具体实现。
• surface 和 deriveMessages 被持久化、compaction、UI、回放共同依赖，改动影响面大。

12.2 隐式约束

• seq = log.length，见 packages/core/session/src/index.ts:564-567。
• surface event 必须带 surfaceOp。
• model-visible 必须 logged。
• waterfall listener 必须调用 next() 才委托。
• 同一 agent/session 使用同一 id。

12.3 全局状态

• Host 端有 ctx.sessions、ctx.agents、ctx.tools 等全局 registry。
• 浏览器端有 slot registry 和 session manager。
• 这些状态通过 effect、scope 和 disposer 管理，不是无主全局变量。

12.4 并发或异步风险

• 工具并发要求 isConcurrencySafe() 正确；错误声明会导致共享状态竞争。
• tools/execute 只能替换 signal，不能替换 call identity，避免取消漂移。
• Agent 创建/恢复和 HMR 同时发生时，生命周期必须可回滚。
• 浏览器流式 token 高频更新必须合批，避免 React 抖动。

12.5 缓存一致性

• Session.deriveMessages() 和 events 都缓存快照；append 后失效。
• surface replacement 会使 replaceGeneration 增加，派生历史重建。
• projection 缓存与事件流、持久化恢复之间需要 checkpoint。

12.6 数据迁移或兼容性

• 当前 SESSION_FORMAT_VERSION = 0，不承诺兼容。
• 新增普通 event 类型靠 ignorable；结构变化才 bump format。
• 后端会拒绝旧 on-disk 格式。

12.7 性能瓶颈

• 每个 token 都 append assistant/chunk，高频日志路径必须避免阻塞 I/O。
• 大历史派生需要 projection 和 compaction。
• Web 客户端必须避免每个 token 重建整棵 React 树。

12.8 安全边界

• 沙箱、permission、approval、fs policy 是独立能力。
• 程序化工具调用（PTC）通过生成的工具 SDK 调度可见工具；逻辑调用仍重新进入权限、Guard、执行、结果和日志管线。
• credentials 不进入日志。
• Web browser trust 是 Host/Client 边界之一。

12.9 测试覆盖薄弱区域

从文档看，项目强调高覆盖，但需要真实 API 的行为只能在有 key 时验证。无 key 的 CI 自动跳过 e2e，因此“真实模型 + 真实工具”的回归依赖本地或专用 CI。

12.10 文档与实现差异

当前未发现明显 README 与源码冲突。由于项目迭代快，生成 catalog 和 package README 可能滞后，应以当前源码和配置为准。

12.11 新手不应首先修改的代码

• core/session 的 format/surface 规则。
• core/agent-loop 的 phase/cancel/error 状态机。
• core/tools 的调度与 materialize 逻辑。
• boot/app-boot 的 patch 解析和 module fallback。
• vendor/。