架构概述

MicroAgent 采用三层架构设计，遵循单向依赖原则，实现清晰的关注点分离。

三层架构

MicroAgent 采用三层架构设计，遵循单向依赖原则。

整体依赖关系

加载中...

Applications Layer

加载中...

SDK Layer

加载中...

Agent Service Layer

加载中...

设计原则

1. 单向依赖原则

规则: Applications → SDK → Agent Service

绝对禁止反向依赖，通过以下机制实现：

模块隔离

// ✅ Applications 只从 SDK 导入
import { createClient, registerBuiltinToolProvider } from '@micro-agent/sdk';

// ❌ 禁止直接导入 Agent Service
import { ... } from '../agent-service/...';

依赖注入反转

// Agent Service 定义接口（不依赖具体实现）
interface BuiltinToolProvider {
  getTool(name: string): Tool | undefined;
  listTools(): ToolDefinition[];
}

// Applications 实现接口并注册
const provider: BuiltinToolProvider = {
  getTool: (name) => tools.get(name),
  listTools: () => Array.from(tools.values()),
};
registerBuiltinToolProvider(provider);

// Agent Service 运行时获取实现
const provider = getBuiltinToolProvider();

2. 代码即文档

类型系统自解释，命名语义化，避免隐式逻辑。

// ✅ 类型即文档
interface Tool {
  readonly name: string;
  readonly description: string;
  readonly inputSchema: JSONSchema;
  execute(input: unknown, ctx: ToolContext): Promise<ToolResult>;
}

3. 组合优于继承

通过接口 + 事件总线解耦，避免继承链导致的循环依赖。

// ✅ 组合 + 事件总线解耦
class FeishuChannel implements Channel {
  constructor(private eventBus: EventBus) {
    this.eventBus.on('message:outbound', this.send.bind(this));
  }
}

4. 开放封闭原则

对扩展开放，对修改封闭。使用注册表模式实现插件式扩展。

class ToolRegistry {
  private tools = new Map<string, Tool>();
  
  register(tool: Tool): void {
    this.tools.set(tool.name, tool);
  }
}

5. 轻量化设计

最小依赖，最小抽象，无过度工程。

约束	阈值
单文件行数	≤ 300 行
单方法行数	≤ 25 行
方法嵌套层级	≤ 3 层
方法参数	≤ 4 个

核心依赖注入点

1. Container（通用依赖注入容器）

// agent-service/runtime/infrastructure/container.ts
class ContainerImpl implements Container {
  register<T>(token, factory)    // 注册瞬态工厂
  singleton<T>(token, factory)   // 注册单例工厂
  resolve<T>(token)              // 解析依赖
  has(token)                     // 检查是否已注册
}

2. BuiltinToolProvider（工具提供者注册）

// 解决 Agent Service 不能直接依赖 Applications 中的工具实现
registerBuiltinToolProvider(provider)  // 上层应用注册工具实现
getBuiltinToolProvider()               // Agent Service 获取工具提供者

3. BuiltinSkillProvider（技能提供者注册）

// 解决 Agent Service 不能直接依赖 Applications 中的技能实现
registerBuiltinSkillProvider(provider)  // 上层应用注册技能实现
getBuiltinSkillProvider()               // Agent Service 获取技能提供者

4. EventBus（事件总线 - 模块间解耦通信）

// agent-service/runtime/infrastructure/event-bus.ts
eventBus.on(event, handler)      // 订阅事件
eventBus.off(event, handler)     // 取消订阅
eventBus.emit(event, payload)    // 触发事件
eventBus.once(event, handler)    // 一次性订阅

消息处理流程

加载中...

Provider 多模型适配

架构

加载中...

厂商检测

// 根据 URL 域名和模型名称自动检测
detectVendor(baseUrl, model) → 'openai' | 'deepseek' | 'glm' | 'kimi' | 'minimax' | 'ollama' | 'openai-compatible'

思考模型支持

厂商	思考模型	参数设置
OpenAI	o1, o3 系列	reasoning_effort: 'high'
DeepSeek	deepseek-reasoner, deepseek-r1	thinking: { type: 'enabled' }
GLM	glm-4-plus, glm-5	enable_cot: true
Kimi	kimi-k2	reasoning: { effort: 'high' }
MiniMax	m2.x 系列	thinking: { type: 'enabled' }

模型路由器

// 根据任务类型选择模型
router.selectByTaskType('vision')  // 视觉任务
router.selectByTaskType('coder')   // 编程任务
router.selectByTaskType('chat')    // 对话任务

性能目标

指标	目标值
HTTP QPS	1000+
响应延迟 P95	<500ms
流式首字节 TTFT	<1s
并发会话	100+