Agent 从入门到精通
如何设计 Harness 架构

Growth AIOS Components 项目架构 ​

本书的核心案例来源。从一个本地自动化工具演化出的 Harness 架构。

项目路径 ​

D:\DEV\CODE\Automator\Components

模块全景 ​

核心 Agent 层 ​

模块路径职责核心文件数
AiAgentAiAgent/Agent 核心引擎：LeadAgent、SubAgent、会话管理、上下文提供71
AiAgent.EmbeddedAiAgent.Embedded/内置专业 Agent：浏览器、代码执行、FFmpeg、AutoHotKey44
AiAgent.IntegrationAiAgent.Integration/工作流规划 Agent：6 步规划流水线65
Agent.MemoryAgent.Memory/记忆存储与压缩引擎11

基础设施层 ​

模块路径职责核心文件数
LLMLLM/多模型适配：OpenAI/Anthropic/Google/通义/Ollama70
WorkflowWorkflow/工作流引擎：节点执行、分支、循环、嵌套139
MCPMCP/MCP 协议集成：工具注册、远程调用20
PluginPlugin/插件系统：OpenAPI 解析、认证、执行47

执行层 ​

模块路径职责核心文件数
CLICLI/命令行引擎：PowerShell 执行、OCR、文档转换57
CodeRunnerCodeRunner/代码执行：Python/AHK/EXE 多语言沙箱49
TriggerTrigger/触发器：定时/文件监控/热键/WebHook37
VarVaultVarVault/变量保险箱：凭证管理、加密存储21

架构演化路径 ​

阶段1：自动化节点引擎
  └── Workflow（工作流编排）
  └── CLI（命令行执行）
  └── CodeRunner（代码节点执行）

阶段2：接入 LLM
  └── LLM（多模型适配层）
  └── AiAgent（Agent 核心引擎）
       ├── LeadAgent（主 Agent 编排）
       └── SubAgent（子 Agent 执行）

阶段3：上下文工程
  └── Agent.Memory（记忆存储）
  └── Context/（上下文提供者链）
       ├── MemoryFactsContextProvider
       ├── MonitoringContextProvider
       └── TitleContextProvider

阶段4：能力封装
  └── AiAgent.Embedded（专业 Agent）
       ├── BrowserAgent（浏览器自动化）
       ├── CodeRunnerAgent（代码执行）
       ├── FFmpegAgent（视频处理）
       └── CustomAgentGenerator（自定义 Agent 生成）
  └── Skill（技能系统）
  └── Rule（规则约束）
  └── Tool（工具注册）

阶段5：Harness 工程
  └── Evaluation/（评估检查）
       ├── EvalCheck
       └── FunctionEvaluator
  └── Diagnostics/（诊断追踪）
  └── Monitoring/（监控指标）

阶段6：Agent 基座战略
  └── Integration.CLI（对外 CLI 接口）
  └── AiAgent.Integration（工作流规划 Agent）
       └── 6 步规划流水线：
           Step1: RequirementParser（需求解析）
           Step2: SkeletonSelector（骨架选择）
           Step3: NodeSelector（节点选择）
           Step4: TopologyAssembler（拓扑组装）
           Step5: ParamFiller（参数填充）
           Step6: CanvasBuilder（画布构建）

核心设计模式 ​

1. 模块注册模式 ​

每个模块通过 Register(this IServiceCollection, IConfiguration) 注册服务：

csharp
// AiAgentModule.cs
public static void Register(this IServiceCollection services, IConfiguration configuration)
{
    services.TryAddSingleton<IAgentSubAgentProvider, DefaultAgentSubAgentProvider>();
    services.TryAddSingleton<IAgentToolProvider, DefaultAgentToolProvider>();
    services.AddSingleton<SessionManager>();
    services.AddSingleton<LeadAgentManager>();
    // ...
}

2. Provider 可覆盖模式 ​

核心层注册默认空实现，Integration 层提前注册覆盖：

csharp
// 核心层：默认空实现
services.TryAddSingleton<IAgentToolProvider, DefaultAgentToolProvider>();

// Integration 层：提前注册真实实现（覆盖默认）
services.AddSingleton<IAgentToolProvider, RealToolProvider>();

3. ContextProvider 链模式 ​

多个上下文提供者通过 IEnumerable<AIContextProvider> 自动收集：

csharp
services.AddSingleton<AIContextProvider>(sp => sp.GetRequiredService<MemoryFactsContextProvider>());
services.AddSingleton<AIContextProvider>(sp => sp.GetRequiredService<MonitoringContextProvider>());
services.AddSingleton<AIContextProvider>(sp => sp.GetRequiredService<AgentSkillsManager>().BuildProvider());

4. Lead-Sub Agent 分层 ​

LeadAgent（主 Agent）
  ├── 接收用户需求
  ├── 编排 TaskTool（任务分解）
  ├── 委托 SubAgent（子任务执行）
  └── 汇总结果返回

SubAgent（子 Agent）
  ├── 隔离上下文
  ├── 专注单一任务
  ├── 可配置工具集
  └── 结果摘要返回给 Lead

关键技术决策 ​

决策选择原因
Agent 框架基于 MAF (Microsoft.Agents.AI)利用微软的 ChatClientAgent 管道
模型适配自研 Provider 层支持国产模型（通义、DeepSeek、Qwen）
记忆存储自研 Agent.Memory参考字节 Viking 记忆管理
工具协议MCP + 内置工具标准化 + 灵活性兼顾
工作流引擎自研 Workflow需要 Coze 兼容 + 本地执行
代码执行多语言沙箱Python/AHK/EXE + WASM 隔离