goose · version 1.45.0 · Rust 1.94.1

第 10 章：配置、观测与测试——Runtime 的可运维完成面

10.1 是什么：配置决定运行时形态

Config 是全局配置入口，但配置内容分布在 providers、extensions、permissions、TLS、paths、experiments、migrations 和 declarative providers 等模块。它决定：

数据目录、session database、keyring、日志目录；
provider、model、TLS 和 OAuth；
extension 连接方式、timeout、env 和可用工具；
auto-compaction、max turns、tool pair summarization、telemetry；
GooseMode、code-mode、local inference、gateway 和 scheduler。

因此 goose 的启动不是“new Agent”这么简单，而是从配置恢复一个可执行 runtime。

flowchart LR
  Env[环境变量 / config.yaml / keyring] --> Config[Config + migrations]
  Config --> Paths[Paths + data dirs]
  Config --> Registry[ProviderRegistry]
  Config --> Ext[ExtensionManager]
  Config --> Sec[Permission + Security]
  Agent[Agent Loop] --> Trace[tracing / logs]
  Agent --> Usage[usage ledger]
  Agent --> Telemetry[PostHog / OTEL / Langfuse]
  Agent --> Diagnostics[doctor / diagnostics bundle]

10.2 源码怎么做：观测不是“打几个 log”

Agent 使用 tracing span 记录 session id、user、host、agent type、trace input/output；Provider usage 会写入 message metadata、session aggregates 和 usage_ledger。可选 telemetry/OTEL 功能把指标、日志和 trace 发往外部系统，但默认 feature 可以裁剪这些依赖。

logging.rs、tracing/、otel/、posthog.rs 和 gen_ai_telemetry.rs 分别覆盖本地日志、Langfuse/观察层、OpenTelemetry 和产品事件。失败路径里保留 provider error category、security finding id、permission decision 和 compaction usage，方便把“模型失败”和“工具被阻止”区别开。

10.3 Doctor 与诊断

CLI doctor 和 session diagnostics 会收集系统信息、配置路径、最近日志、extension 状态、scheduled recipe 等；crates/goose/src/session/diagnostics.rs 还提供截断和尾部读取，避免诊断包把整份大日志或 secret 带走。诊断是用户可操作的故障入口，不只是开发者 debug。

10.4 测试策略：从纯函数到协议回放

仓库中的测试覆盖多层：

provider formatter、canonical model、HTTP status 和 stream collect 的单元测试；
Agent Loop 的 mock provider、tool confirmation、stop hook、empty response、retry 和 usage 测试；
ExtensionManager 的 mock MCP client、notification、工具缓存、HTTP header 和名称恢复测试；
session manager 的 SQLite schema/migration/import/export/search 测试；
mcp_replays/ 保存真实 MCP 交互回放，减少对外部服务在线可用性的依赖；
ui/desktop 使用 Vitest/Playwright 类测试覆盖 chat、permissions、session 和渲染状态；
documentation/ 使用 Docusaurus build、typecheck 和 docs-map tests 验证文档站点。

这个测试布局对应 goose 的真实风险：模型协议可能变、工具协议可能变、历史数据不能丢、UI 事件不能乱序，而不是只验证一个函数返回值。

10.5 为什么这样做：运行时必须能解释自己的行为

Agent 是有副作用的系统。用户需要知道：为什么执行了工具、为什么要求批准、为什么压缩上下文、用了多少 token、为什么重试、为什么停不下来。配置、结构化事件、usage ledger、diagnostics 和 tracing 共同提供这条解释链。

10.6 阅读后的总判断

goose 最值得学习的不是某一个 provider 实现，而是几个边界的组合：

用 Provider 把模型协议变化隔离。
用 Message 的 typed content 和双可见性连接 UI、Agent、Provider、Storage。
用 ExtensionManager 把 MCP 能力变成可缓存、可路由、可安全审查的工具集合。
用 SessionManager 和 SQLite 把长任务、自动化和跨宿主恢复变成一等能力。
用 AgentEvent、ActionRequired、custom requests/notifications 让不同产品表面共享 runtime。

这五个边界组合起来，才构成一个可以长期演进的 native AI agent，而不是“会调用 LLM 的 CLI”。

源码定位

crates/goose/src/config/、model_config.rs：配置、迁移、provider/extension 设置。
crates/goose/src/logging.rs、tracing/、otel/、posthog.rs：观测。
crates/goose/src/session/diagnostics.rs、doctor.rs：诊断。
crates/goose/tests/、crates/goose/src/**/tests、mcp_replays/：核心测试与协议回放。
ui/desktop/src/**/*.test.tsx、playwright.config.ts：桌面端验证。