AI Orchestrator (AI 编排引擎) - 通用 AI 平台协作框架

## 🎯 核心洞察

### 关键发现

Memory Service 作为**跨终端共享记忆中枢**，支持：
- ✅ Claude CLI
- ✅ Cursor CLI
- ✅ Qwen CLI
- ✅ 任何支持 MCP 协议的 AI 工具
- ✅ 自定义 AI Agent

---

## 📋 命名与定位

### 名称：AI Orchestrator（AI 编排引擎）

### 定位：

- **平台无关**：支持任何 AI CLI/SDK（Claude / Cursor / Qwen / ...）
- **协议驱动**：基于 MCP 和 Memory Service 标准协议
- **角色编排**：协调多个 AI Agent 跨平台协作
- **记忆共享**：所有 AI 通过 Memory Service 共享上下文

---

## 🏗️ 全新架构设计

### 系统架构

```
┌──────────────────────────────────────────────────────────────┐
│                    KysionAgents 核心系统                      │
│                                                               │
│  ┌─────────────────────────────────────────────────────┐     │
│  │         Memory Service (记忆中枢) - 核心基础         │     │
│  │  ┌──────────────────────────────────────────────┐   │     │
│  │  │  五级层级体系                                      │   │     │
│  │  │  Enterprise → Solution → Project → Role → Session │  │
│  │  └──────────────────────────────────────────────┘   │     │
│  │                                                      │     │
│  │  数据模型：                                           │     │
│  │  - Messages (对话记录)                              │     │
│  │  - Decisions (决策记录)                             │     │
│  │  - CodeChanges (代码变更)                           │     │
│  │  - Artifacts (产出物)                               │     │
│  └─────────────────────────────────────────────────────┘     │
│                          ▲                                   │
│                          │ SDK 调用                          │
│                          │                                   │
│  ┌──────────────────────┴───────────────────────────────┐   │
│  │         AI Orchestrator (AI 编排引擎) - 🆕           │   │
│  │                                                       │   │
│  │  ┌─────────────────────────────────────────────┐     │   │
│  │  │  AI Platform Adapters (AI 平台适配器)       │     │   │
│  │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐    │     │   │
│  │  │  │ Claude   │ │ Cursor   │ │  Qwen    │    │     │   │
│  │  │  │ Adapter  │ │ Adapter  │ │ Adapter  │    │     │   │
│  │  │  └──────────┘ └──────────┘ └──────────┘    │     │   │
│  │  │  ┌──────────┐ ┌──────────┐                 │     │   │
│  │  │  │ Custom   │ │  MCP     │                 │     │   │
│  │  │  │ Agent    │ │ Generic  │                 │     │   │
│  │  │  └──────────┘ └──────────┘                 │     │   │
│  │  └─────────────────────────────────────────────┘     │   │
│  │                                                       │   │
│  │  ┌─────────────────────────────────────────────┐     │   │
│  │  │  Workflow Engine (工作流引擎)                │     │   │
│  │  │  - 任务编排                                  │     │   │
│  │  │  - 角色分配                                  │     │   │
│  │  │  - 验收流程                                  │     │   │
│  │  │  - 状态同步                                  │     │   │
│  │  └─────────────────────────────────────────────┘     │   │
│  │                                                       │   │
│  │  ┌─────────────────────────────────────────────┐     │   │
│  │  │  Communication Channels (通信通道)           │     │   │
│  │  │  - Memory Service Bridge (核心)             │     │   │
│  │  │  - Telegram Gateway (可选)                  │     │   │
│  │  │  - File Queue (兜底)                        │     │   │
│  │  │  - Redis Pub/Sub (高性能)                   │     │   │
│  │  └─────────────────────────────────────────────┘     │   │
│  └───────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
```

---

## 🎯 核心设计理念

### 1. 平台无关性（Platform Agnostic）

**问题：** 不同 AI 平台有不同的调用方式

**解决：** 适配器模式

```typescript
// packages/ai-orchestrator/src/adapters/base-adapter.ts

interface AIAdapter {
  platform: 'claude' | 'cursor' | 'qwen' | 'custom';

// 统一接口
  execute(task: Task): Promise<TaskResult>;
  getContext(): Promise<Context>;
  saveContext(context: Context): Promise<void>;
}

// Claude 适配器
class ClaudeAdapter implements AIAdapter {
  platform = 'claude';

async execute(task: Task): Promise<TaskResult> {
    // 调用 Claude CLI
    const result = await execa('claude', [
      '--prompt', task.prompt,
      '--session', task.sessionId
    ]);

// 结果写入 Memory Service
    await memoryService.recordMessage({...});

return result;
  }
}

// Cursor 适配器
class CursorAdapter implements AIAdapter {
  platform = 'cursor';

async execute(task: Task): Promise<TaskResult> {
    // 调用 Cursor API
    // ...
  }
}

// Qwen 适配器
class QwenAdapter implements AIAdapter {
  platform = 'qwen';

async execute(task: Task): Promise<TaskResult> {
    // 调用 Qwen CLI/API
    // ...
  }
}
```

### 2. 记忆共享（Shared Memory）

**核心：** Memory Service 作为所有 AI 的共享记忆

```typescript
// 场景：Claude 执行任务，Cursor 验收

// Terminal 1 - Claude 执行
const claudeAdapter = new ClaudeAdapter({
  memoryService,
  role: 'backend-dev'
});

await claudeAdapter.execute({
  taskId: 'create-api',
  prompt: '创建用户认证 API'
});

// 自动写入 Memory Service
await memoryService.recordMessage({
  role_id: 'backend-dev',
  content: '已完成用户认证 API',
  metadata: {
    platform: 'claude',
    artifacts: ['src/auth/api.ts']
  }
});

// Terminal 2 - Cursor 验收
const cursorAdapter = new CursorAdapter({
  memoryService,
  role: 'code-reviewer'
});

// 从 Memory Service 读取上下文
const context = await memoryService.getSessionContext({
  role_id: 'code-reviewer',
  include_roles: ['backend-dev']  // 读取其他角色的记忆
});

await cursorAdapter.execute({
  taskId: 'review-api',
  prompt: '验收用户认证 API',
  context  // 包含 Claude 的执行记录
});
```

### 3. 工作流编排（Workflow Orchestration）

**声明式工作流配置**

```yaml
# .kysion/workflows/user-auth.yaml

workflow:
  name: user-authentication
  version: 1.0.0

# 角色定义（平台无关）
  agents:
    - id: backend-dev
      role: developer
      platform: claude        # 使用 Claude
      terminal: terminal-1

- id: frontend-dev
      role: developer
      platform: cursor        # 使用 Cursor
      terminal: terminal-2

- id: code-reviewer
      role: reviewer
      platform: qwen          # 使用 Qwen
      terminal: terminal-3

- id: architect
      role: supervisor
      platform: claude        # 使用 Claude
      terminal: terminal-4

# 任务流程
  tasks:
    - id: design-api
      name: 设计 API 接口
      assignee: architect
      platform: claude

output:
        - type: document
          path: docs/api-design.md

next: [implement-backend, implement-frontend]

- id: implement-backend
      name: 实现后端 API
      assignee: backend-dev
      platform: claude
      depends_on: [design-api]

context:
        include_tasks: [design-api]  # 共享 architect 的设计

reviewer: code-reviewer
      review_platform: qwen          # 跨平台验收！

output:
        - type: code
          path: src/auth/**/*.ts

- id: implement-frontend
      name: 实现前端界面
      assignee: frontend-dev
      platform: cursor               # 使用 Cursor 开发前端
      depends_on: [design-api]

context:
        include_tasks: [design-api, implement-backend]

reviewer: code-reviewer
      review_platform: qwen

# 验收规则
  review_rules:
    - id: code-quality
      applies_to: [implement-backend, implement-frontend]
      criteria:
        - type: test_coverage
          threshold: 80
        - type: lint_pass
          strict: true
        - type: type_check
          strict: true
```

### 4. 跨平台验收（Cross-Platform Review）

**关键能力：** 不同 AI 平台之间的独立验收

```typescript
// Terminal 1 - Claude 执行任务
// (通过 ClaudeAdapter)

// Terminal 2 - Qwen 自动验收
const qwenReviewer = new QwenAdapter({
  memoryService,
  role: 'code-reviewer'
});

// 工作流引擎自动触发
await workflowEngine.onTaskComplete('implement-backend', async (task) => {
  // 1. 从 Memory Service 读取任务上下文
  const context = await memoryService.getTaskContext(task.id);

// 2. 加载验收标准
  const criteria = workflow.review_rules.find(r =>
    r.applies_to.includes(task.id)
  );

// 3. 通知 Qwen 验收者
  await qwenReviewer.execute({
    taskId: `review-${task.id}`,
    prompt: `
      验收任务：${task.name}

上下文：
      ${JSON.stringify(context, null, 2)}

验收标准：
      ${JSON.stringify(criteria, null, 2)}

请执行独立验收，检查：
      1. 文件是否存在
      2. 测试覆盖率
      3. 代码质量
      4. 符合设计规范
    `,
    context
  });

// 4. Qwen 执行验收后，结果自动写入 Memory Service
  // 5. 工作流引擎读取验收结果，决定下一步
});
```

---

## 📊 核心优势

### 1. 真正的平台无关

| 维度 | 支持情况 |
|------|---------|
| Claude CLI | ✅ 完整支持 |
| Cursor | ✅ 完整支持 |
| Qwen | ✅ 完整支持 |
| Codeium | ✅ 可扩展 |
| 自定义 Agent | ✅ 可扩展 |
| MCP 兼容工具 | ✅ 通用适配器 |

### 2. 记忆共享

```
Claude 执行 → Memory Service → Qwen 验收
  ↓                             ↑
Cursor 前端 ←  共享上下文  ← 自定义 Agent
```

所有 AI 通过 Memory Service 共享：
- 对话历史
- 决策记录
- 代码变更
- 产出物
- 验收结果

### 3. 灵活编排

```yaml
# 场景1: 同一平台协作
backend-dev(claude) → reviewer(claude)

# 场景2: 跨平台协作
backend-dev(claude) → reviewer(qwen)

# 场景3: 多平台协作
architect(claude) → backend(claude) → frontend(cursor) → qa(qwen)
```

### 4. 独立验收

```
Terminal 1: Claude 写代码
Terminal 2: Qwen 验收代码
Terminal 3: Cursor 前端开发
Terminal 4: Claude Architect 监督

全部通过 Memory Service 自动协调！
```

---

## 🚀 使用示例

### 场景：Gitea Phase 0 Step-1（跨平台验收）

```yaml
# .kysion/workflows/gitea-phase0.yaml

workflow:
  agents:
    - id: codex
      platform: claude
      role: developer
      terminal: terminal-1

- id: qwen-qa
      platform: qwen
      role: reviewer
      terminal: terminal-2

tasks:
    - id: create-check-script
      assignee: codex
      platform: claude
      reviewer: qwen-qa
      review_platform: qwen    # 跨平台验收！
```

```bash
# Terminal 1 - Claude 执行
cd /Volumes/AiWorkSpace/KysionAgents
claude

"启动工作流 gitea-phase0，角色 codex"
# Claude 自动：
# 1. 注册到 AI Orchestrator
# 2. 执行 create-check-script 任务
# 3. 完成后写入 Memory Service
# 4. 触发验收请求

# Terminal 2 - Qwen 验收
cd /Volumes/AiWorkSpace/KysionAgents
qwen-cli

"启动验收模式 gitea-phase0，角色 qwen-qa"
# Qwen 自动：
# 1. 注册到 AI Orchestrator
# 2. 从 Memory Service 读取 codex 的工作成果
# 3. 执行验收检查
# 4. 写入验收结果到 Memory Service
# 5. 通知 codex
```

**完全自动化！无需你传话！**

---

## 📂 目录结构

```
packages/
├── ai-orchestrator/              # 🆕 AI 编排引擎
│   ├── src/
│   │   ├── adapters/             # AI 平台适配器
│   │   │   ├── base-adapter.ts
│   │   │   ├── claude-adapter.ts
│   │   │   ├── cursor-adapter.ts
│   │   │   ├── qwen-adapter.ts
│   │   │   ├── mcp-generic-adapter.ts
│   │   │   └── custom-agent-adapter.ts
│   │   │
│   │   ├── workflow/             # 工作流引擎
│   │   │   ├── engine.ts
│   │   │   ├── task-scheduler.ts
│   │   │   ├── review-orchestrator.ts
│   │   │   └── state-machine.ts
│   │   │
│   │   ├── channels/             # 通信通道
│   │   │   ├── memory-bridge.ts
│   │   │   ├── telegram.ts
│   │   │   ├── file-queue.ts
│   │   │   └── redis-pubsub.ts
│   │   │
│   │   ├── registry/             # 实例注册
│   │   │   ├── agent-registry.ts
│   │   │   └── heartbeat.ts
│   │   │
│   │   └── index.ts
│   │
│   ├── cli/                      # CLI 工具
│   │   ├── start-worker.ts
│   │   ├── start-reviewer.ts
│   │   └── status.ts
│   │
│   └── package.json
│
├── memory-service/               # 现有：记忆中枢
└── telegram-gateway/             # 现有：Telegram 网关
```

---

## 🎯 核心价值重新定义

### ✅ 这是什么

- **跨 AI 平台协作框架**：Claude、Cursor、Qwen 等统一编排
- **基于 Memory Service**：所有 AI 共享记忆
- **声明式工作流**：YAML 配置驱动
- **独立验收机制**：不同 AI 平台互相验收

---