Agent 作为可注入的 Driver

更新于 · 在 sijie.xyz 查看原条目 ↗

✓ 已落地

Agent core 现在已经是一个可以通过 Bridge/Driver 模式独立启动的模块。

设计

Agent core = 借助 Bridge/Driver 模式实现的、可独立启动的模块。

这层抽象位于 backend/agentcore/（刻意放在 internal/ 之外）：

  • driver.go：定义了 Driver 接口，包含以下方法：Persona、Skill、RunSkill、ExtMCPURL、Plugins、SearchCorpus、ListCorpus、GetCorpus、Resolve
    • Agent core 是抽象（Abstraction）；Driver 是实现者（Implementor）
  • bridge.go：把任意 Driver 适配到循环的内部端口上（driverSandbox → sandbox.Runner、driverSkillGetter、driverMCPGetter、driverResolver → 凭据解析器）
  • agentcore.go：eino loop 类型之上的公共门面（facade）
  • 启动句柄：BuildVisitorAgent(ctx, d Driver, in *LaunchInput)（visitor_build.go:50）

它是真实可用的证据

eval-harness/ 是一个独立的 Go 模块，其中的 EvalDriver（eval_driver.go）实现了该接口，并在预制数据（canned data）上运行真正的 eino loop：

  • golden_assembly_test.go（golden-path 场景）
  • plugin_assembly_test.go / booker_assembly_test.go（插件专属测试）
  • retrieval_assembly_test.go（检索 / corpus 测试）
  • launch_test.go（端到端）+ 跑在真实模型上的那组 *_live_test.go

今天只有评测通过这个句柄启动——"eval 不过是又一个调用方"在类型系统里成立，在生产里还没有：截至 2026-09-07（36789537d），BuildVisitorAgent 只有一个非测试调用方（eval-harness/main.go:164、candidate.go:138），backend/internal 和 backend/cmd 下没有任何包 import agentcore。生产的网页路径是 internal/routes/public/sessions.go → capreg.AssembleVisitorBundle → inference.RunAgentTurn。设想的终态——生产传入一个 prod Driver，评测传入一个 EvalDriver——就是下面"剩余工作"那一项。

铁律

  1. 重新导出（re-export）internal/ 里的类型 = 一种依赖，禁止。 调用方只能 import agentcore。
  2. Fixtures 只能存在于调用方（eval-harness）。后端本身保持无 fixture。
  3. 由 check-no-mock 守护：确保没有 mock/fixture 代码混入后端。

类视图——教科书式的 Bridge

classDiagram
  class Driver {
    <<interface - the Implementor>>
    +Persona(ctx) (Persona, error)
    +Skill(ctx) (*VisitorSkillSpec, error)
    +RunSkill(ctx, SkillRun) (SkillResult, error)
    +ExtMCPURL(ctx) (string, error)
    +Plugins(ctx) ([]PluginSpec, error)
    +SearchCorpus(ctx, query) ([]CorpusHit, error)
    +ListCorpus(ctx, parentPath, page) ([]CorpusHit, error)
    +GetCorpus(ctx, path) (CorpusDoc, error)
    +Resolve(ctx) (Cred, error)
  }
  class LaunchInput {
    OwnerID string
    Mode string
    ConversationID string
    CodeID string
    SystemPromptOverride string
    GrantedCapabilities []string
  }
  class VisitorAgent {
    Labels map[string]string
    ReturnDirectly map[string]bool
    SystemPrompt string
    Tools []tool.BaseTool
  }
  class bridgeAdapters {
    bridge.go - driverSandbox / driverSkillGetter / driverMCPGetter / driverResolver
    wrap a Driver into the loop's internal ports
  }
  class EvalDriver {
    eval-harness, separate go.mod
    canned data behind the interface
  }
  class BuildVisitorAgent {
    <<launch handle>>
    takes ctx, Driver, *LaunchInput
    returns (*VisitorAgent, error)
  }
  bridgeAdapters ..> Driver : wraps
  Driver <|.. EvalDriver
  BuildVisitorAgent ..> Driver : consumes any
  BuildVisitorAgent ..> LaunchInput : input
  BuildVisitorAgent --> VisitorAgent : builds

生产和评测的差异按设计只在于一个构造函数参数——这就是这个模式的全部（今天只接好了评测那一侧；见上文）。

早前的偏离（已修复）

早前的偏离（fixture 文件被焊死在 backend/agentcore/ 里）已经修复——该目录现在不含任何 fixture；预制数据只存在于被注入的 Driver 背后（"Driver 就是环境"）。

剩余工作（路线图第③层）

把"注入即启动"从仅测试用途，提升为一等运行时能力：并行 prompt 实验——这是 eight-controls-applied 缺失的"质量的另一半"。

另见：entry-agnostic-agent（内向/外向对称性）；eval-harness-on-prod-loop（历史背景）。

相关笔记