11 · Agent Runtime、MCP 与 Persona

Buzz 的 Agent 栈分成四层：buzz-acp 管协作事件和进程；buzz-agent 管模型会话与 tool loop；buzz-dev-mcp 提供本地开发工具；buzz-persona 将人格、模型、hooks、skills 和 MCP 配置打包。sprig 则把这些能力组合成一个易分发的全栈进程。

1. 分层

Relay events
   ▼
buzz-acp                lifecycle / queue / ACP sessions
   ▼ ACP stdio
buzz-agent              LLM provider / history / tool loop / compaction
   ▼ MCP client calls
buzz-dev-mcp + others   shell / files / search / image / domain tools
   ▲
persona pack            prompt / model / env / hooks / skills / MCP specs

每层有独立协议边界，能替换其中一层而不重写全部系统。

2. buzz-agent 会话模型

Agent runtime 通过 stdio 暴露 ACP，对每个 session 保存：

• conversation history。
• system prompt 与 persona 投影。
• provider/model/thinking 配置。
• MCP server/tool catalog。
• cancellation token 与当前 turn 状态。
• usage 与 context budget。

实现允许多个 session 并发（愿景/配置上限围绕 8），但每个 session 内 turn 串行，避免 history 同时追加两条相互不可见的分支。

3. LLM tool loop

典型 turn：

user prompt + history
        │
        ▼
provider request
  ├─ final text ─────────────► complete
  ├─ tool call(s)
  │      ├─ validate arguments
  │      ├─ invoke MCP
  │      ├─ append tool result
  │      └─ call provider again
  └─ context pressure ───────► summarize/compact → continue

停止原因会区分正常完成、长度、tool use、取消和 provider 错误。usage 以 turn total 状态累计，防流式增量重复计费。

4. 取消不是杀主进程

取消需要穿过多个边界：ACP cancel → session cancellation token → provider stream/HTTP → MCP tool/process group。仅停止模型流不够，如果工具已启动 cargo test 或 shell 子进程，它仍可能继续修改磁盘。

buzz-dev-mcp 与 Agent MCP launcher 因而关注 process group 回收和有界输出。超时/取消时终止进程树，再回传结构化工具错误。

5. Context 与 compaction

长会话不能无限携带全文 history。Runtime 在接近模型上下文预算时做摘要/压缩：

• 保留系统/persona 与最近关键 turn。
• 把较早对话压成 summary item。
• hook 可在 _PostCompact 之后执行外部记忆同步。
• compaction 失败不能悄悄丢掉所有上下文。

MCP-driven hooks 用约定工具名 _Stop、_PostCompact 承载生命周期扩展；是否调用由 Agent 主权控制，不让 MCP server 反向劫持 runtime。

6. MCP 工具面

buzz-dev-mcp 包含：

工具	边界
shell	bounded stdout/stderr、timeout、process group kill
read_file	大小/范围限制
rg/tree	工作区搜索与目录枚举
str_replace	精确替换，避免模糊大面积写入
view_image	MIME、尺寸、解压炸弹防护
todo	Agent 内部工作清单

这些工具能力很强；真正的权限边界来自进程工作目录、环境、OS sandbox 与 harness permission mode，而不是 MCP JSON schema 本身。

7. Persona pack

Persona 以插件 manifest + .persona.md frontmatter 表达：

• system prompt / model / thinking。
• runtime 参数与触发策略。
• MCP servers、hooks、skills。
• 环境变量和展示元数据。

Resolver 合并默认配置与 persona override，并对路径做 canonicalization/边界检查，防 ../、绝对路径或 symlink 把 skill 指向 pack 外部敏感文件。

Persona 不只是“提示词皮肤”，而是 Agent 可执行能力的配置包；因此加载它等价于加载代码/权限配置，必须可审计。

8. sprig

sprig 把 ACP harness、Agent runtime 与开发 MCP 整合进一个发行物，降低 sidecar 编排成本。适合本地开箱使用；独立 crate 仍保留，因为生产环境可能希望：

• 用第三方 ACP Agent 替换 buzz-agent。
• 把 MCP server 放进单独 sandbox。
• 独立伸缩 harness 与 model runtime。

9. Provider 抽象

配置支持多个 provider/API 形态，Runtime 把它们归一成内部 content block、tool call、stop reason 和 usage。抽象泄漏主要发生在：

• streaming event 顺序。
• reasoning/thinking 参数。
• tool schema 兼容性。
• OAuth/API key 生命周期。
• context window 与自动升级模型名称。

因此测试包含 fake LLM、golden transcripts、OAuth、自动升级与回归场景，而不只测一个 happy path。

10. 安全与信任边界

untrusted channel content
       │ prompt injection risk
       ▼
LLM decision
       │ tool request, still untrusted
       ▼
MCP schema + permission mode + workspace/OS boundary
       │
       ▼
local side effect

签名只能证明频道内容是谁发的，不能证明内容值得执行。Agent 的 respond allowlist 与工具 permission 是不同层：前者决定谁能触发推理，后者决定推理能做什么。

11. 完成度

已实现： ACP server、provider/tool loop、MCP 进程管理、会话/取消、compaction、persona 解析、开发工具集与大量回归测试。

部分实现： 不同 provider 能力完全对齐、强 OS sandbox、跨设备持久会话恢复和更完整的共享算力调度。

12. 源码入口

• crates/buzz-agent/src/agent.rs：会话、turn 与 tool loop。
• crates/buzz-agent/src/mcp.rs：MCP server/process 管理。
• crates/buzz-agent/src/config.rs：provider、model 与 hooks 配置。
• crates/buzz-dev-mcp/src/：开发工具实现。
• crates/buzz-persona/src/：pack 解析、合并与安全路径解析。
• crates/sprig/src/：全栈组合发行物。
• docs/MCP_DRIVEN_HOOKS.md：hook 协议与主权原则。