OpenClaw Evolution Plugin - 架构设计文档

版本: 0.1.0

最后更新: 2026-03-10

系统概览

OpenClaw Evolution Plugin 采用 Monorepo 架构，包含多个独立但协同工作的包。系统通过事件驱动架构实现闭环进化流程。

┌─────────────────────────────────────────────────────────────────────────┐
│                        OpenClaw Host Runtime                            │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ Plugin Protocol
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Plugin Runtime                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                 │
│  │ Handshake    │  │ Event Bridge │  │ Card Adapter │                 │
│  │ Manager      │  │              │  │              │                 │
│  └──────────────┘  └──────────────┘  └──────────────┘                 │
│  ┌──────────────┐                                                        │
│  │ Compatibility │                                                       │
│  │ Manager       │                                                       │
│  └──────────────┘                                                        │
└─────────────────────────────────────────────────────────────────────────┘
                    │                                    │
                    │ HTTP/WebSocket                    │
                    ▼                                    ▼
┌──────────────────────────────┐      ┌─────────────────────────────────┐
│     Evolution Service        │      │    Insight Console              │
│  ┌────────────────────────┐  │      │  ┌───────────────────────────┐ │
│  │   Event Store          │  │      │  │  Dashboard                │ │
│  └────────────────────────┘  │      │  └───────────────────────────┘ │
│  ┌────────────────────────┐  │      │  ┌───────────────────────────┐ │
│  │   Trigger Engine       │  │      │  │  Evolution Funnel         │ │
│  └────────────────────────┘  │      │  └───────────────────────────┘ │
│  ┌────────────────────────┐  │      │  ┌───────────────────────────┐ │
│  │   Candidate Extractor  │  │      │  │  Candidate Review         │ │
│  └────────────────────────┘  │      │  └───────────────────────────┘ │
│  ┌────────────────────────┐  │      │  ┌───────────────────────────┐ │
│  │   Evaluation Engine    │  │      │  │  Skill Registry           │ │
│  └────────────────────────┘  │      │  └───────────────────────────┘ │
│  ┌────────────────────────┐  │      │  ┌───────────────────────────┐ │
│  │   Card Manager         │  │      │  │  Compatibility Status     │ │
│  └────────────────────────┘  │      │  └───────────────────────────┘ │
│  ┌────────────────────────┐  │      │  ┌───────────────────────────┐ │
│  │   Skill Registry       │  │      │  │  Avatar View              │ │
│  └────────────────────────┘  │      │  └───────────────────────────┘ │
└──────────────────────────────┘      └─────────────────────────────────┘
                    │
                    │ Events
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    OpenClaw Evolution System                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                 │
│  │ Avatar       │  │ State        │  │ Animation   │                 │
│  │ Manager      │  │ Machine      │  │ Protocol    │                 │
│  └──────────────┘  └──────────────┘  └──────────────┘                 │
│  ┌──────────────┐                                                        │
│  │ Replay       │                                                       │
│  │ Engine       │                                                       │
│  └──────────────┘                                                        │
└─────────────────────────────────────────────────────────────────────────┘

Monorepo 结构

/openclaw-evolution-plugin
├── packages/
│   ├── plugin-runtime/          # 插件运行时
│   │   ├── src/
│   │   │   ├── core/
│   │   │   │   ├── handshake.ts
│   │   │   │   ├── event-bridge.ts
│   │   │   │   └── card-adapter.ts
│   │   │   ├── compatibility/
│   │   │   │   ├── manager.ts
│   │   │   │   ├── adapter.ts
│   │   │   │   └── profiles/
│   │   │   └── plugin.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── evolution-service/       # 进化服务
│   │   ├── src/
│   │   │   ├── api/
│   │   │   │   ├── routes/
│   │   │   │   │   ├── runtime.ts
│   │   │   │   │   ├── events.ts
│   │   │   │   │   ├── candidates.ts
│   │   │   │   │   ├── evaluations.ts
│   │   │   │   │   ├── cards.ts
│   │   │   │   │   ├── skills.ts
│   │   │   │   │   └── insights.ts
│   │   │   │   └── server.ts
│   │   │   ├── engines/
│   │   │   │   ├── trigger.ts
│   │   │   │   ├── extractor.ts
│   │   │   │   ├── evaluator.ts
│   │   │   │   └── card-generator.ts
│   │   │   ├── storage/
│   │   │   │   ├── event-store.ts
│   │   │   │   ├── candidate-store.ts
│   │   │   │   ├── card-store.ts
│   │   │   │   └── skill-registry.ts
│   │   │   └── service.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── insight-console/         # 洞察控制台
│   │   ├── src/
│   │   │   ├── pages/
│   │   │   │   ├── dashboard.tsx
│   │   │   │   ├── funnel.tsx
│   │   │   │   ├── candidates.tsx
│   │   │   │   ├── evaluations.tsx
│   │   │   │   ├── skills.tsx
│   │   │   │   ├── compatibility.tsx
│   │   │   │   └── avatar.tsx
│   │   │   ├── components/
│   │   │   │   ├── cards/
│   │   │   │   ├── charts/
│   │   │   │   └── avatar/
│   │   │   ├── hooks/
│   │   │   ├── api/
│   │   │   └── app.tsx
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── evolution-engine/        # 进化引擎
│   │   ├── src/
│   │   │   ├── avatar/
│   │   │   │   ├── avatar.ts
│   │   │   │   ├── stages.ts
│   │   │   │   └── mutations.ts
│   │   │   ├── state-machine/
│   │   │   │   ├── machine.ts
│   │   │   │   └── transitions.ts
│   │   │   ├── animations/
│   │   │   │   ├── protocol.ts
│   │   │   │   └── effects.ts
│   │   │   ├── replay/
│   │   │   │   ├── logger.ts
│   │   │   │   └── player.ts
│   │   │   └── engine.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   └── shared-types/            # 共享类型定义
│       ├── src/
│       │   ├── events/
│       │   │   ├── runtime.ts
│       │   │   ├── evolution.ts
│       │   │   └── avatar.ts
│       │   ├── api/
│       │   │   ├── requests.ts
│       │   │   └── responses.ts
│       │   ├── models/
│       │   │   ├── candidate.ts
│       │   │   ├── card.ts
│       │   │   ├── skill.ts
│       │   │   └── avatar.ts
│       │   └── index.ts
│       ├── package.json
│       └── tsconfig.json
│
├── docs/
│   ├── PRD.md
│   ├── ARCHITECTURE.md
│   ├── EVENT_SCHEMA.md
│   ├── COMPATIBILITY.md
│   └── EVOLUTION_SYSTEM.md
│
├── examples/
│   ├── plugin-manifest.json
│   ├── event-payloads/
│   ├── api-calls.sh
│   └── demo-scenarios/
│
├── scripts/
│   ├── setup.sh
│   ├── build.sh
│   ├── test.sh
│   └── dev.sh
│
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── package.json              # 根 package.json
├── pnpm-workspace.yaml
├── tsconfig.base.json
└── README.md

核心组件设计

1. Plugin Runtime

职责

与 OpenClaw 主机运行时集成
实现插件协议
桥接事件到 Evolution Service
渲染进化卡片
管理兼容性

核心类

// core/handshake.ts
export class HandshakeManager {
  async performHandshake(hostInfo: HostInfo): Promise<HandshakeResult>
  async negotiateCapabilities(hostCapabilities: string[]): Promise<string[]>
  validateHostVersion(version: string): boolean
}

// core/event-bridge.ts
export class EventBridge {
  onRuntimeEvent(event: RuntimeEvent): void
  normalizeEvent(event: RawRuntimeEvent): NormalizedEvent
  forwardEvent(event: NormalizedEvent): Promise<void>
  startBatching(config: BatchingConfig): void
  stopBatching(): void
}

// core/card-adapter.ts
export class CardAdapter {
  renderCard(card: EvolutionCard): RenderResult
  chooseBestRenderer(hostCapabilities: string[]): CardRenderer
  fallbackToSidebar(card: EvolutionCard): RenderResult
  fallbackToExternal(card: EvolutionCard): RenderResult
}

// compatibility/manager.ts
export class CompatibilityManager {
  detectHostVersion(): HostInfo
  loadCapabilityProfile(version: string): CapabilityProfile
  selectAdapter(hostInfo: HostInfo): AdapterProfile
  mapEvent(event: any, adapter: AdapterProfile): NormalizedEvent
  getCompatibilityStatus(): CompatibilityStatus
}

插件清单 (Manifest)

{
  "name": "@openclaw/evolution-plugin",
  "version": "0.1.0",
  "displayName": "OpenClaw Evolution Plugin",
  "description": "Evolution layer for OpenClaw",
  "author": "OpenClaw Team",
  "entry": "dist/plugin.js",
  "minHostVersion": "1.0.0",
  "maxHostVersion": "2.0.0",
  "permissions": [
    "read:conversations",
    "read:events",
    "write:cards",
    "read:capabilities"
  ],
  "capabilities": [
    "inlineCards",
    "eventStreaming",
    "bidirectional"
  ],
  "dependencies": [],
  "settings": {
    "serviceEndpoint": "http://localhost:3000",
    "enableAutoEvaluation": false,
    "cardExpiryHours": 72
  }
}

2. Evolution Service

职责

接收和存储事件
运行触发引擎
生成候选改进
协调评估
管理卡片和技能注册表

架构模式

分层架构:

API Layer (/routes)
    ↓
Service Layer (/engines)
    ↓
Storage Layer (/storage)
    ↓
Database (PostgreSQL / SQLite)

核心类

// engines/trigger.ts
export class TriggerEngine {
  registerTrigger(trigger: Trigger): void
  evaluateEvent(event: NormalizedEvent): TriggerMatch[]
  checkThresholds(matches: TriggerMatch[]): boolean
}

// engines/extractor.ts
export class CandidateExtractor {
  extractFromPattern(event: NormalizedEvent): Candidate[]
  extractFromFeedback(event: NormalizedEvent): Candidate[]
  extractFromCorrection(event: NormalizedEvent): Candidate[]
  extractFromDiscovery(event: NormalizedEvent): Candidate[]
}

// engines/evaluator.ts
export class EvaluationEngine {
  createEvaluationRun(candidateId: string): EvaluationRun
  runEvaluation(runId: string): Promise<EvaluationResult>
  runTests(candidate: Candidate): TestResult[]
  validateSafety(candidate: Candidate): SafetyCheck[]
}

// engines/card-generator.ts
export class CardGenerator {
  generateCard(candidate: Candidate): EvolutionCard
  formatCardContent(candidate: Candidate): CardContent
  chooseCardType(candidate: Candidate): CardType
}

API 路由设计

POST /v1/runtime/handshake
  Request: { hostInfo, pluginInfo, capabilities }
  Response: { sessionId, capabilities, config }

POST /v1/events
  Request: NormalizedEvent[]
  Response: { received, errors }

GET /v1/events?session_id=&type=&limit=
  Response: NormalizedEvent[]

POST /v1/candidates
  Request: { content, type, source }
  Response: Candidate

GET /v1/candidates?status=&session_id=
  Response: Candidate[]

POST /v1/evaluations/run
  Request: { candidateId, testConfig }
  Response: EvaluationRun

GET /v1/evaluations/:id
  Response: EvaluationRun

GET /v1/cards?session_id=&status=
  Response: EvolutionCard[]

POST /v1/cards/:id/decision
  Request: { decision, notes }
  Response: { updatedCard, nextActions }

POST /v1/skills/promote
  Request: { candidateId, cardId }
  Response: SkillRegistryItem

POST /v1/skills/rollback
  Request: { skillId, toVersion }
  Response: SkillRegistryItem

GET /v1/insights/dashboard
  Response: DashboardMetrics

GET /v1/insights/funnel
  Response: FunnelMetrics

GET /v1/insights/skills
  Response: SkillsInsights

GET /v1/insights/compatibility
  Response: CompatibilityReport

数据库模式

-- Events
CREATE TABLE events (
  id UUID PRIMARY KEY,
  session_id VARCHAR(255) NOT NULL,
  type VARCHAR(100) NOT NULL,
  data JSONB NOT NULL,
  normalized_data JSONB,
  created_at TIMESTAMP DEFAULT NOW(),
  INDEX idx_session (session_id),
  INDEX idx_type (type)
);

-- Candidates
CREATE TABLE candidates (
  id UUID PRIMARY KEY,
  session_id VARCHAR(255) NOT NULL,
  type VARCHAR(50) NOT NULL,
  source VARCHAR(50) NOT NULL,
  content JSONB NOT NULL,
  confidence DECIMAL(3,2),
  status VARCHAR(50),
  created_at TIMESTAMP DEFAULT NOW(),
  INDEX idx_status (status),
  INDEX idx_session (session_id)
);

-- Evaluation Runs
CREATE TABLE evaluation_runs (
  id UUID PRIMARY KEY,
  candidate_id UUID REFERENCES candidates(id),
  status VARCHAR(50),
  result JSONB,
  started_at TIMESTAMP,
  completed_at TIMESTAMP,
  INDEX idx_candidate (candidate_id)
);

-- Cards
CREATE TABLE cards (
  id UUID PRIMARY KEY,
  session_id VARCHAR(255) NOT NULL,
  type VARCHAR(50),
  candidate_id UUID REFERENCES candidates(id),
  content JSONB NOT NULL,
  status VARCHAR(50),
  decision JSONB,
  created_at TIMESTAMP,
  expires_at TIMESTAMP,
  INDEX idx_session (session_id),
  INDEX idx_status (status)
);

-- Skills Registry
CREATE TABLE skills_registry (
  id UUID PRIMARY KEY,
  type VARCHAR(50) NOT NULL,
  name VARCHAR(255) NOT NULL,
  content JSONB NOT NULL,
  version INTEGER DEFAULT 1,
  promoted_at TIMESTAMP,
  rollback_version INTEGER,
  INDEX idx_type (type),
  INDEX idx_name (name)
);

3. Insight Console

技术栈

框架: React 18
构建工具: Vite
UI 库: shadcn/ui + Tailwind CSS
状态管理: Zustand
数据获取: React Query
路由: React Router

页面结构

// pages/dashboard.tsx
export function DashboardPage() {
  const metrics = useDashboardMetrics()
  return <DashboardView metrics={metrics} />
}

// pages/funnel.tsx
export function FunnelPage() {
  const funnel = useFunnelMetrics()
  return <FunnelView data={funnel} />
}

// pages/candidates.tsx
export function CandidatesPage() {
  const { data, filters } = useCandidates()
  return <CandidateList data={data} filters={filters} />
}

// pages/skills.tsx
export function SkillsPage() {
  const skills = useSkillsRegistry()
  return <SkillsRegistry skills={skills} />
}

// pages/avatar.tsx
export function AvatarPage() {
  const avatar = useAvatar()
  const mutations = useMutations()
  return <AvatarView avatar={avatar} mutations={mutations} />
}

组件架构

components/
├── cards/
│   ├── SkillCard.tsx
│   ├── RuleCard.tsx
│   ├── MemoryCard.tsx
│   └── CardRenderer.tsx
├── charts/
│   ├── FunnelChart.tsx
│   ├── TimelineChart.tsx
│   └── MetricsCard.tsx
├── avatar/
│   ├── AvatarDisplay.tsx
│   ├── StageBadge.tsx
│   └── MutationIndicator.tsx
└── layout/
    ├── Sidebar.tsx
    ├── Header.tsx
    └── ConsoleLayout.tsx

4. OpenClaw Evolution System

核心概念

// avatar/avatar.ts
export class OpenClawAvatar {
  private currentStage: AvatarStage
  private stageHistory: StageTransition[]
  private activeMutations: Mutation[]
  private stats: AvatarStats

  initialize(): void
  transitionTo(stage: AvatarStage): void
  applyMutation(mutation: Mutation): void
  triggerAnimation(type: AnimationType): void
  getDisplayState(): AvatarDisplayState
}

// state-machine/machine.ts
export class AvatarStateMachine {
  private states: StateMap
  private transitions: TransitionMap

  addState(stage: AvatarStage, config: StateConfig): void
  addTransition(from: AvatarStage, to: AvatarStage, trigger: string): void
  canTransition(from: AvatarStage, to: AvatarStage): boolean
  executeTransition(from: AvatarStage, to: AvatarStage): void
}

// animations/protocol.ts
export interface AnimationProtocol {
  triggerAnimation(event: AnimationEvent): void
  cancelAnimation(animationId: string): void
  getActiveAnimations(): Animation[]
}

// replay/logger.ts
export class ReplayLogger {
  logEvent(event: EvolutionEvent): void
  getReplay(sessionId: string): ReplaySession
  exportReplay(sessionId: string): ReplayExport
}

状态机设计

     ┌─────────┐
     │  base   │  初始状态
     └────┬────┘
          │ candidate_detected
          ▼
     ┌─────────┐
     │awakened │  首次检测到候选改进
     └────┬────┘
          │ evaluation_passed
          ▼
     ┌─────────┐
     │ learned │  评估通过
     └────┬────┘
          │ skill_promoted
          ▼
     ┌─────────┐
     │ evolved │  技能提升
     └─────────┘

动画事件协议

interface AnimationEvent {
  id: string
  type: AnimationType
  stage: AvatarStage
  intensity: 'low' | 'medium' | 'high'
  duration: number
  metadata: Record<string, unknown>
}

type AnimationType =
  | 'pulse'           // 阶段心跳
  | 'evaluating'      // 评估中
  | 'activation'      // 技能激活
  | 'mutation'        // 突变应用
  | 'transition'      // 阶段转换

5. CompatibilityManager

设计模式

策略模式 - 根据主机版本选择不同的适配器策略

适配器模式 - 将不同版本的事件模式转换为新版本

降级模式 - 当功能不可用时提供替代方案

核心类

export class CompatibilityManager {
  private hostVersion: string
  private capabilityProfile: CapabilityProfile
  private currentAdapter: AdapterProfile

  detectHostVersion(): string
  loadCapabilityProfile(version: string): CapabilityProfile
  selectAdapter(hostInfo: HostInfo): AdapterProfile
  mapEvent(event: any, adapter: AdapterProfile): NormalizedEvent
  getBestRenderingMode(): RenderingMode
  getCompatibilityStatus(): CompatibilityStatus
}

export interface AdapterProfile {
  name: string
  supportedHostVersions: SemVerRange[]
  eventMapping: EventMapping
  apiMapping: ApiMapping
  degradedFeatures: string[]
  fallbackStrategies: FallbackConfig
}

export interface EventMapping {
  [originalEvent: string]: string | ((event: any) => NormalizedEvent)
}

降级策略

interface FallbackConfig {
  cardRendering: {
    primary: 'inline' | 'sidebar' | 'external'
    fallbacks: RenderingMode[]
  }
  eventStreaming: {
    primary: 'websocket' | 'polling'
    fallbacks: StreamingMode[]
  }
}

type RenderingMode =
  | 'inline'      // 内联渲染
  | 'sidebar'     // 侧边栏
  | 'console'     // 控制台
  | 'external'    // 外部 H5 页面

通信协议

插件到服务通信

// 握手协议
interface HandshakeRequest {
  pluginInfo: PluginInfo
  hostInfo?: HostInfo
  requestedCapabilities: string[]
}

interface HandshakeResponse {
  sessionId: string
  grantedCapabilities: string[]
  config: ServiceConfig
  compatibility: CompatibilityStatus
}

// 事件提交协议
interface EventBatch {
  sessionId: string
  events: NormalizedEvent[]
  metadata: {
    batchId: string
    timestamp: Date
    count: number
  }
}

// 卡片渲染协议
interface CardRenderRequest {
  card: EvolutionCard
  renderingContext: RenderingContext
}

interface CardRenderResult {
  success: boolean
  mode: RenderingMode
  renderId?: string
  fallbackUrl?: string
}

服务到插件通信

// 卡片推送协议
interface CardPush {
  card: EvolutionCard
  urgency: 'low' | 'medium' | 'high'
  expiresAt: Date
}

// 配置更新协议
interface ConfigUpdate {
  key: string
  value: unknown
  version: number
}

// 兼容性警告协议
interface CompatibilityWarning {
  level: 'info' | 'warning' | 'error'
  message: string
  affectedFeatures: string[]
  recommendedAction: string
}

部署架构

开发环境

┌─────────────────────────────────────────────────────────────┐
│                    Developer Machine                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Plugin Dev  │  │ Service Dev │  │ Console Dev         │  │
│  │ (Plugin RT) │  │ (API+DB)    │  │ (Vite Dev Server)   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

生产环境

┌─────────────────────────────────────────────────────────────┐
│                     User Environment                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              OpenClaw Desktop/App                   │   │
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │         Plugin Runtime (Embedded)            │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          │
                          │ HTTPS/WSS
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Evolution Service                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ API Server   │  │ Worker       │  │ Database         │  │
│  │ (Node.js)    │  │ (Evaluation) │  │ (PostgreSQL)     │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    Insight Console                          │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         Web Server (Static + SPA)                    │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

技术选型

组件	技术	理由
Plugin Runtime	TypeScript	类型安全，易于维护
Evolution Service	Node.js + Express/Hono	与插件共享类型，异步性能好
Database	PostgreSQL / SQLite	生产用 PG，开发用 SQLite
Insight Console	React + Vite	快速开发，热更新
UI Library	shadcn/ui + Tailwind	现代化，可定制
State Management	Zustand	轻量，类型安全
Data Fetching	React Query	缓存，重试，乐观更新
Monorepo Tool	pnpm workspaces	快速，节省磁盘空间
Build Tool	tsup	快速 TypeScript 打包
Testing	Vitest + Playwright	统一测试框架

安全考虑

API 安全

HTTPS/WSS 加密通信
JWT 会话认证
Rate Limiting
CORS 配置
输入验证 (Zod schemas)

插件安全

权限最小化原则
沙箱执行环境
敏感数据不记录
卡片内容转义

数据安全

敏感信息加密存储
定期数据清理
用户数据隔离
审计日志

性能优化

事件处理

批量提交 (batching)
异步处理队列
事件压缩
索引优化

API 性能

响应缓存
分页查询
连接池
CDN 静态资源

控制台性能

代码分割
虚拟滚动
图片懒加载
服务端渲染 (可选)

监控和可观测性

日志

结构化日志
日志级别管理
错误追踪

指标

API 响应时间
事件处理量
卡片展示率
转化率

告警

服务可用性
错误率阈值
性能下降

版本控制策略

语义版本控制

Major: 不兼容的 API 变更
Minor: 向后兼容的功能添加
Patch: 向后兼容的问题修复

兼容性保证

至少支持最后 2 个 Major 版本
提前 3 个月通知 Breaking Changes
提供迁移指南

未来扩展

Phase 2 功能

多插件协同
分布式评估
A/B 测试框架
高级分析

Phase 3 功能

机器学习优化
自动特征工程
强化学习集成

文档版本: 0.1.0 最后更新: 2026-03-10 维护者: OpenClaw Evolution Team

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History