Agido 极动

Appearance

开发指南 ​

开发环境搭建 ​

系统要求 ​

  • 操作系统: macOS 12+ / Windows 10+ (WSL2) / Linux (Ubuntu 22.04+)
  • Node.js: >= 18.0.0
  • Python: >= 3.11
  • Rust: >= 1.75
  • 包管理器: pnpm >= 8.0.0
  • Git: >= 2.30.0

推荐工具 ​

  • IDE: VSCode / WebStorm / RustRover
  • 浏览器: Chrome / Edge / Safari（最新版）
  • 容器: Docker Desktop（用于沙箱化执行和引擎部署）
  • API 调试: Postman / curl / HTTPie

项目架构 ​

技术栈 ​

层级技术
桌面端Tauri v2 + Rust + React
Web 端React + TypeScript
核心引擎Rust / TypeScript / Python
调度引擎TypeScript
引擎适配器TypeScript / Python
MCP ServerTypeScript
增强引擎TypeScript
数据存储SQLite + FTS5 + 向量库
AI 网关SkyGate（Rust）
容器化Docker

目录结构 ​

agido/
├── apps/                       # 应用层
│   ├── desktop/               # 桌面端（Tauri v2）
│   ├── web/                   # Web 端（React）
│   └── cli/                   # 命令行工具
├── packages/                   # 共享包
│   ├── core/                  # Agido Native 核心引擎
│   │   ├── dialog/            # L1 对话层
│   │   ├── execution/         # L2 执行层
│   │   ├── memory/            # L3 记忆层
│   │   ├── collaboration/     # L4 协作层
│   │   ├── evolution/         # L5 进化层
│   │   └── perception/        # L6 感知层
│   ├── scheduler/             # 统一调度引擎
│   │   ├── intent/            # 意图识别
│   │   ├── decomposition/     # 任务分解
│   │   ├── routing/           # 引擎路由
│   │   ├── aggregation/       # 结果聚合
│   │   └── context/           # 上下文同步
│   ├── adapters/              # 引擎适配器
│   │   ├── openclaw/          # OpenClaw 适配器
│   │   ├── hermes/            # Hermes Agent 适配器
│   │   ├── openhuman/         # OpenHuman 适配器
│   │   ├── dify/              # Dify 适配器
│   │   ├── coze/              # Coze 适配器
│   │   ├── autogen/           # AutoGen 适配器
│   │   └── crewai/            # CrewAI 适配器
│   ├── mcp-server/            # MCP Server
│   ├── enhanced/              # 增强引擎
│   │   ├── orchestration/     # 智能编排（DAG）
│   │   ├── health/            # 健康感知
│   │   └── knowledge/         # 知识融合
│   └── shared/                # 共享工具
├── server/                     # 服务端
│   ├── gateway/               # API 网关
│   └── mcp/                   # MCP Server
├── docs/                       # 文档
└── scripts/                    # 脚本

开发规范 ​

代码规范 ​

  • 使用 ESLint + Prettier 进行代码格式化
  • TypeScript 严格模式启用
  • Rust 使用 clippy + rustfmt
  • 组件命名使用 PascalCase
  • 函数命名使用 camelCase
  • 引擎适配器遵循 EngineAdapter 接口规范

Git 规范 ​

类型(scope): 简短描述

详细描述（可选）

Footer（可选）

类型说明：

  • feat: 新功能
  • fix: 修复
  • docs: 文档
  • style: 格式
  • refactor: 重构
  • perf: 性能优化
  • test: 测试
  • chore: 构建/工具

示例：

feat(scheduler): 添加负载感知路由策略

- 根据引擎负载智能分发任务
- 支持自定义负载阈值
- 添加负载趋势预测

Closes #123

分支管理 ​

  • main: 主分支，稳定版本
  • develop: 开发分支
  • feature/*: 功能分支
  • hotfix/*: 紧急修复
  • release/*: 发布分支

引擎适配器开发 ​

EngineAdapter 接口 ​

所有引擎适配器必须实现 EngineAdapter 接口：

typescript
interface EngineAdapter {
  name: string
  version: string

  initialize(config: EngineConfig): Promise<void>
  destroy(): Promise<void>

  execute(task: Task): Promise<TaskResult>
  healthCheck(): Promise<HealthStatus>

  getCapabilities(): EngineCapabilities
  getTools(): MCPTool[]
}

示例：创建新引擎适配器 ​

typescript
import { EngineAdapter, Task, TaskResult, HealthStatus, EngineConfig, EngineCapabilities, MCPTool } from '@agido/core'

export class MyEngineAdapter implements EngineAdapter {
  name = 'my-engine'
  version = '1.0.0'

  private config: EngineConfig | null = null

  async initialize(config: EngineConfig): Promise<void> {
    this.config = config
  }

  async destroy(): Promise<void> {
    this.config = null
  }

  async execute(task: Task): Promise<TaskResult> {
    const startTime = Date.now()
    try {
      const result = await this.doExecute(task)
      return {
        success: true,
        data: result,
        duration: Date.now() - startTime,
        engine: this.name
      }
    } catch (error) {
      return {
        success: false,
        error: error.message,
        duration: Date.now() - startTime,
        engine: this.name
      }
    }
  }

  async healthCheck(): Promise<HealthStatus> {
    return {
      status: 'healthy',
      latency: 0,
      errorRate: 0,
      resourceUsage: { cpu: 0, memory: 0 }
    }
  }

  getCapabilities(): EngineCapabilities {
    return {
      dialog: true,
      execution: true,
      memory: true,
      collaboration: false,
      evolution: false,
      perception: false
    }
  }

  getTools(): MCPTool[] {
    return [
      {
        name: 'my_engine_query',
        description: 'Query my engine',
        parameters: {
          type: 'object',
          properties: {
            query: { type: 'string', description: 'Query string' }
          },
          required: ['query']
        }
      }
    ]
  }

  private async doExecute(task: Task): Promise<any> {
    // 实现具体执行逻辑
  }
}

注册适配器 ​

typescript
import { Scheduler } from '@agido/scheduler'
import { MyEngineAdapter } from './my-engine-adapter'

const scheduler = new Scheduler()

scheduler.registerAdapter(new MyEngineAdapter(), {
  priority: 5,
  capabilities: ['dialog', 'execution'],
  fallback: 'agido-native'
})

调试技巧 ​

桌面端调试 ​

bash
# 开发模式
pnpm dev:desktop

# 调试 Tauri 主进程
RUST_LOG=debug pnpm dev:desktop

# 调试渲染进程
# 使用 Chrome DevTools (F12)

Web 端调试 ​

bash
# 开发模式
pnpm dev:web

# 使用 React DevTools 和 Chrome DevTools

MCP Server 调试 ​

bash
# 启动 MCP Server
pnpm dev:mcp

# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector http://localhost:3001

引擎健康调试 ​

bash
# 查看所有引擎健康状态
curl http://localhost:3000/api/v1/enhanced/health/engines

# 查看路由建议
curl "http://localhost:3000/api/v1/enhanced/health/routing-suggestion?task=dialog"

测试 ​

单元测试 ​

bash
# 运行所有测试
pnpm test

# 运行指定模块测试
pnpm test -- packages/core

# 覆盖率报告
pnpm test:coverage

E2E 测试 ​

bash
# 运行 E2E 测试
pnpm test:e2e

# headed 模式
pnpm test:e2e -- --headed

引擎集成测试 ​

bash
# 测试所有引擎适配器
pnpm test:engines

# 测试指定引擎
pnpm test:engines -- --engine openclaw

性能优化 ​

调度引擎优化 ​

  1. 路由缓存：频繁路由的任务类型缓存路由结果
  2. 预热连接：引擎适配器启动时预热连接池
  3. 批量执行：相同引擎的多个任务批量提交
  4. 超时控制：每个引擎任务设置合理超时

记忆系统优化 ​

  1. 索引优化：FTS5 索引 + 向量索引联合查询
  2. 分层缓存：热记忆内存缓存，冷记忆磁盘存储
  3. 增量同步：仅同步变更的记忆条目
  4. 压缩存储：长期记忆自动压缩摘要

MCP Server 优化 ​

  1. 连接复用：HTTP Keep-Alive + WebSocket 长连接
  2. 流式响应：DAG 编排结果流式返回
  3. 并发控制：限制同时执行的 DAG 数量
  4. 资源隔离：每个 DAG 执行沙箱隔离

部署 ​

Docker 部署 ​

bash
# 构建镜像
docker build -t agido:latest .

# 运行容器
docker run -d -p 3000:3000 -p 3001:3001 agido:latest

Docker Compose 部署（含引擎） ​

bash
# 启动所有服务
docker compose up -d

# 查看状态
docker compose ps

Kubernetes 部署 ​

bash
# 应用配置
kubectl apply -f k8s/

# 查看状态
kubectl get pods -n agido

常见问题 ​

Q: 引擎适配器连接超时？ ​

A: 检查：

  1. 引擎服务是否启动
  2. 网络连接是否正常
  3. 防火墙是否放行端口
  4. 超时配置是否合理

Q: DAG 编排执行失败？ ​

A: 检查：

  1. 各节点引擎是否健康
  2. 节点间数据依赖是否正确
  3. 失败回滚策略是否配置
  4. 查看执行快照定位问题

Q: 记忆同步冲突？ ​

A: 检查：

  1. 多引擎是否同时写入同一记忆
  2. 冲突消解策略是否配置
  3. 同步频率是否过高

相关资源 ​