大海
679 lines
28 KiB
Markdown
679 lines
28 KiB
Markdown
# Claw Agent Operating System v2 — 项目融合分析文档
|
||
|
||
> 基于 6 个开源 Agent 框架的能力模型融合
|
||
> 生成时间：2026-06-04
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目定位分析 (Step 1)](#1-项目定位分析)
|
||
2. [能力提取 (Step 2)](#2-能力提取)
|
||
3. [能力抽象层 (Step 3)](#3-能力抽象层)
|
||
4. [集成优先级判断 (Step 4)](#4-集成优先级判断)
|
||
5. [Claw 改造方案 (Step 5)](#5-claw-改造方案)
|
||
6. [PRD 产品需求文档 (Step 6)](#6-prd)
|
||
|
||
---
|
||
|
||
## 1. 项目定位分析
|
||
|
||
### 1.1 MCP-Use — MCP 全栈框架（第一优先级）
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| **项目目标** | 构建 MCP (Model Context Protocol) 的完整开发框架：Server、Client、App、Inspector + 云端部署 |
|
||
| **核心架构** | 双 SDK（TypeScript + Python），基于 LangChain Agent 引擎，Connector 抽象层（HTTP/stdio/WebSocket/Sandbox），MCPAgent 封装，Server Manager 动态工具管理 |
|
||
| **核心创新** | 1) MCP Apps — 跨平台 Widget 系统（Claude/ChatGPT/任意 MCP Client 一处编写处处运行）2) Server Manager 模式 — Agent 可动态连接/断开 MCP Server 3) 内置 Inspector 调试工具 4) Skills 系统（4 个预制 Skill：mcp-builder/openapi-to-mcp/chatgpt-app-builder/mcp-apps-builder） |
|
||
| **解决的问题** | MCP 开发碎片化 — 没有一个从开发→调试→部署的全流程框架；Agent 运行时动态工具注册能力缺失 |
|
||
|
||
### 1.2 Mastra — TypeScript AI 应用框架（第一优先级）
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| **项目目标** | 构建 TypeScript 生态的全栈 AI Agent 平台，覆盖 Agent/Workflow/Memory/RAG/Evals/Observability/MCP/Voice/Deploy |
|
||
| **核心架构** | Monorepo（20+ packages），核心模块：@mastra/core（Agent/Workflow/Memory），@mastra/evals（评估），@mastra/memory（记忆），@mastra/rag（检索增强），@mastra/mcp（MCP 协议），@mastra/voice（语音），@mastra/deployer（部署） |
|
||
| **核心创新** | 1) Graph-based Workflow 引擎（.then()/.branch()/.parallel() 声明式控制流）2) Human-in-the-loop（Suspend/Resume 暂停等待人工审批）3) DurableAgent（持久化 Agent 状态）4) Background Tasks 系统 5) Model Routing 统一 40+ 模型提供商接口 |
|
||
| **解决的问题** | AI Agent 应用从原型到生产的鸿沟 — 缺少评估、可观测、部署一体化方案；TypeScript 生态缺乏完整的 Agent 框架 |
|
||
|
||
### 1.3 CrewAI — 多 Agent 协作框架（第二优先级）
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| **项目目标** | 构建角色扮演式多 Agent 协作系统，通过 Crew/Agent/Task 三层抽象实现团队协作 |
|
||
| **核心架构** | Agent（角色定义 + LLM + 工具）→ Task（任务定义 + 期望输出）→ Crew（团队编排 + 执行策略），支持 sequential/hierarchical 两种执行模式 |
|
||
| **核心创新** | 1) Role-based Agent 设计（角色+目标+背景故事）2) Task 依赖链（一个 Task 的输出作为另一个的输入）3) Hierarchical Manager Agent 委托模式 4) Agent Evaluator（评估 Agent 表现）5) Skills Registry（技能注册与缓存） |
|
||
| **解决的问题** | 复杂任务需要多角色协作，但缺乏结构化的 Team-as-Code 抽象 |
|
||
|
||
### 1.4 AutoGen — 微软多 Agent 对话框架（第二优先级）
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| **项目目标** | 构建可编程的多 Agent 对话系统，支持 Agent 间自由对话、Human-in-the-loop、代码执行 |
|
||
| **核心架构** | ConversableAgent 基类 → AssistantAgent/UserProxyAgent 派生，GroupChat + GroupChatManager 编排，支持 .NET/Python 双语言 |
|
||
| **核心创新** | 1) Agent-to-Agent 自由对话模式（非预设流程）2) Code Executor（Agent 生成代码→执行→反馈循环）3) Team 模式（RoundRobin/Selector/MagenticOne）4) AG Studio（低代码 Agent 编排 UI）5) Tool Use 标准接口 |
|
||
| **解决的问题** | Agent 间通信缺乏标准化框架；代码生成+执行的自愈循环 |
|
||
|
||
### 1.5 MetaGPT — 多角色软件团队模拟（第三优先级）
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| **项目目标** | 用多 Agent 模拟一个完整软件公司的协作，从需求→设计→编码→测试全流程自动化 |
|
||
| **核心架构** | Role（角色）→ Action（行为）→ Environment（共享环境）→ Memory（短/长期记忆），SOP-driven（标准操作流程驱动），Action Graph 依赖图 |
|
||
| **核心创新** | 1) SOP（Standard Operating Procedure）驱动的 Agent 协作 2) Role-Environment-Memory-Action 四层抽象 3) Action Graph（自动依赖解析和并行调度）4) 多角色软件工程全流程（PM→Architect→Engineer→QA）5) Structured Output（JSON Schema 结构化输出） |
|
||
| **解决的问题** | LLM 输出不稳定，通过多角色相互审查（Code Review, API Review）提升质量；复杂工程任务需要结构化流程 |
|
||
|
||
### 1.6 RagaAI-Catalyst — Agent 可观测性与安全（第四优先级）
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| **项目目标** | 为 LLM/Agent 应用提供全生命周期观测、评估、安全测试（Red Teaming） |
|
||
| **核心架构** | ragaai_catalyst 核心 SDK + Evaluation 评估引擎 + Red Teaming 安全测试 + 多框架适配层（LangChain/CrewAI/LlamaIndex/SmolAgents/OpenAI Agents SDK/Haystack） |
|
||
| **核心创新** | 1) 多框架统一评估接口（同一套指标度量不同框架的 Agent）2) Red Teaming 自动化安全测试（场景生成→测试用例→评估）3) 可观测性管道（追踪→评估→得分）4) PII Masking（敏感信息脱敏） |
|
||
| **解决的问题** | Agent 上线前缺乏系统性评估和安全测试；不同 Agent 框架缺乏统一的质量度量标准 |
|
||
|
||
---
|
||
|
||
## 2. 能力提取
|
||
|
||
### MCP-Use 核心能力
|
||
|
||
| # | 能力 | 描述 |
|
||
|---|------|------|
|
||
| 1 | **MCP Server 构建** | 双语言 SDK（TS/PY），声明式创建 MCP Server、Tool、Resource、Prompt |
|
||
| 2 | **MCP Client 连接管理** | 多传输协议（HTTP/stdio/WebSocket/Sandbox），Session 生命周期管理 |
|
||
| 3 | **动态工具注册** | Server Manager 模式 — Agent 运行时动态连接/断开 MCP Server，工具集实时更新 |
|
||
| 4 | **跨平台 MCP App** | Widget 系统，定义一次 Tool Widget，所有 MCP Client 原生渲染 |
|
||
| 5 | **Agent 集成** | MCPAgent 封装 LangChain，支持 structured output、conversation memory、streaming |
|
||
|
||
### Mastra 核心能力
|
||
|
||
| # | 能力 | 描述 |
|
||
|---|------|------|
|
||
| 1 | **Graph Workflow 引擎** | 声明式控制流：`.then()` 顺序、`.branch()` 分支、`.parallel()` 并行，支持 Suspend/Resume |
|
||
| 2 | **Durable Agent** | Agent 状态持久化，支持长时间运行、暂停恢复、断点续传 |
|
||
| 3 | **统一 Model Routing** | 40+ LLM 提供商统一接口，运行时切换模型 |
|
||
| 4 | **Evals + Observability** | 内置评估框架（Scorer/ScoreTraces）、全链路追踪、日志、指标 |
|
||
| 5 | **Memory + RAG** | 对话记忆、工作记忆（Working Memory）、语义召回（Semantic Recall）、向量检索 |
|
||
|
||
### CrewAI 核心能力
|
||
|
||
| # | 能力 | 描述 |
|
||
|---|------|------|
|
||
| 1 | **Role-based Agent** | Agent = 角色 + 目标 + 背景故事 + 工具 + LLM |
|
||
| 2 | **Task 依赖链** | Task = 描述 + 期望输出 + 上下文（from previous task）+ Agent 分配 |
|
||
| 3 | **Crew 编排** | sequential（顺序执行）/ hierarchical（Manager Agent 委托），Process 模式 |
|
||
| 4 | **Agent 评估** | AgentEvaluator + 多维指标（goal/reasoning/tools/semantic_quality） |
|
||
| 5 | **Skills Registry** | 技能注册/缓存/事件系统 |
|
||
|
||
### AutoGen 核心能力
|
||
|
||
| # | 能力 | 描述 |
|
||
|---|------|------|
|
||
| 1 | **自由对话模式** | Agent 之间自由对话，非预设流程，GroupChat 管理 |
|
||
| 2 | **Code Executor** | Agent 生成代码 → 沙箱执行 → 反馈 → 自修复循环 |
|
||
| 3 | **Team 编排模式** | RoundRobin（轮询）/ Selector（智能选择）/ MagenticOne（统一代理） |
|
||
| 4 | **Human-in-the-loop** | UserProxyAgent 在关键节点请求人类输入 |
|
||
| 5 | **低代码 Studio** | AG Studio 提供可视化 Agent 编排界面 |
|
||
|
||
### MetaGPT 核心能力
|
||
|
||
| # | 能力 | 描述 |
|
||
|---|------|------|
|
||
| 1 | **多角色 SOP** | 标准操作流程驱动多 Agent 协作（PM→Architect→Engineer→QA）|
|
||
| 2 | **Action Graph** | 自动依赖解析、并行调度、增量执行 |
|
||
| 3 | **Role-Memory-Action-Environment** | 四层核心抽象，Environment 作为共享工作空间 |
|
||
| 4 | **结构化审查链** | Code Review + API Review 多角色相互审查提升质量 |
|
||
| 5 | **Structured Output** | JSON Schema 强约束输出格式 |
|
||
|
||
### RagaAI-Catalyst 核心能力
|
||
|
||
| # | 能力 | 描述 |
|
||
|---|------|------|
|
||
| 1 | **多框架统一评估** | 同一套指标（准确性/完整性/安全性/延迟）评估不同 Agent 框架 |
|
||
| 2 | **Red Teaming 安全测试** | 自动生成攻击场景 → 测试用例 → 评估 Agent 安全边界 |
|
||
| 3 | **全链路可观测性** | 追踪 → 评估 → 得分 → 可视化报告 |
|
||
| 4 | **PII Masking** | 敏感信息自动检测和脱敏 |
|
||
| 5 | **多框架适配器** | 支持 LangChain/CrewAI/LlamaIndex/OpenAI Agents SDK/Haystack/smolagents |
|
||
|
||
---
|
||
|
||
## 3. 能力抽象层
|
||
|
||
### 核心能力矩阵
|
||
|
||
| Capability | Description | Inputs | Outputs | Source Projects |
|
||
|------------|-------------|--------|---------|-----------------|
|
||
| **Multi-Agent Orchestration** | 多 Agent 协作编排：角色定义、任务分配、消息路由、执行策略 | Agent 配置、Task 描述、执行模式 | 协作结果、消息日志 | CrewAI, AutoGen, MetaGPT |
|
||
| **Declarative Workflow** | 声明式工作流：顺序/分支/并行控制、暂停恢复、断点续传 | Workflow DAG 定义、触发条件 | 执行结果、中间状态 | Mastra |
|
||
| **MCP Native Integration** | MCP 协议原生集成：Server/Client/App 全栈、动态工具注册 | MCP Server 配置、Tool 定义 | MCP 连接、工具集 | MCP-Use |
|
||
| **Memory System** | 多层级记忆：对话记忆、工作记忆、语义召回、向量存储 | 对话历史、用户偏好 | 上下文摘要、召回结果 | Mastra, MetaGPT |
|
||
| **Observability & Eval** | 可观测性：全链路追踪、评估指标、安全测试、可视化 | Agent 执行轨迹、Metric 定义 | 评估得分、Trace 报告 | RagaAI-Catalyst, Mastra |
|
||
| **Self-Evolution** | 自我进化：技能学习、反馈闭环、自动优化 | 执行日志、评估反馈、外部知识 | 优化后的 Agent 配置、新技能 | Mastra (evals), CrewAI (skills) |
|
||
|
||
### 能力依赖关系
|
||
|
||
```
|
||
Multi-Agent Orchestration ──┐
|
||
Declarative Workflow ──────┤
|
||
├──→ MCP Native Integration (工具层)
|
||
Memory System ─────────────┤ │
|
||
│ ▼
|
||
Observability & Eval ──────┘ Agent Runtime
|
||
│
|
||
▼
|
||
Self-Evolution (闭环)
|
||
```
|
||
|
||
### 统一接口定义
|
||
|
||
```typescript
|
||
// Capability: Multi-Agent Orchestration
|
||
interface IMultiAgentOrchestrator {
|
||
createTeam(config: TeamConfig): Team;
|
||
addAgent(team: Team, agent: AgentConfig): void;
|
||
assignTask(team: Team, task: Task): TaskHandle;
|
||
execute(team: Team, strategy: ExecutionStrategy): AsyncIterable<TeamEvent>;
|
||
}
|
||
|
||
// Capability: Declarative Workflow
|
||
interface IWorkflowEngine {
|
||
define(name: string): WorkflowBuilder;
|
||
// WorkflowBuilder: .then() .branch() .parallel() .suspend() .resume()
|
||
execute(workflow: Workflow, input: any): AsyncIterable<WorkflowEvent>;
|
||
}
|
||
|
||
// Capability: MCP Native
|
||
interface IMCPRuntime {
|
||
registerServer(config: MCPServerConfig): MCPServerHandle;
|
||
connectClient(transport: TransportConfig): MCPClientHandle;
|
||
listTools(client: MCPClientHandle): Promise<Tool[]>;
|
||
executeTool(client: MCPClientHandle, tool: Tool, input: any): Promise<any>;
|
||
}
|
||
|
||
// Capability: Memory System
|
||
interface IMemorySystem {
|
||
store(session: SessionId, entry: MemoryEntry): Promise<void>;
|
||
recall(session: SessionId, query: string): Promise<MemoryEntry[]>;
|
||
summarize(session: SessionId): Promise<string>;
|
||
persist(session: SessionId): Promise<void>;
|
||
}
|
||
|
||
// Capability: Observability
|
||
interface IObservability {
|
||
trace(execution: ExecutionId): TraceCollector;
|
||
evaluate(execution: ExecutionId, metrics: Metric[]): Promise<EvalResult>;
|
||
redTeam(agent: AgentHandle, scenarios: Scenario[]): Promise<SecurityReport>;
|
||
}
|
||
|
||
// Capability: Self-Evolution
|
||
interface ISelfEvolution {
|
||
learn(feedback: ExecutionFeedback): Promise<void>;
|
||
optimize(config: AgentConfig, metrics: MetricResult[]): Promise<AgentConfig>;
|
||
acquireSkill(skill: SkillDefinition): Promise<SkillHandle>;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 集成优先级判断
|
||
|
||
### 优先级总表
|
||
|
||
| 优先级 | 项目 | 核心价值 | 集成理由 |
|
||
|--------|------|---------|---------|
|
||
| 🔴 **High** | MCP-Use | MCP 全栈能力 | Claw 最缺乏标准化工具协议层；MCP 是 2026 Agent 互操作性事实标准 |
|
||
| 🔴 **High** | Mastra | Workflow + Memory + Evals | 直接补齐 Claw 缺失的三大核心：声明式工作流、多层级记忆、评估体系 |
|
||
| 🟡 **Medium** | CrewAI | Role-based 多 Agent | Role-Task-Crew 三层抽象可直接适配 Claw 的 Multi-Agent 需求 |
|
||
| 🟡 **Medium** | AutoGen | 自由对话 + Code Executor | Code Executor 是 Claw 的 ctx_execute 的升级方向；自由对话模式补充结构化编排 |
|
||
| 🟢 **Low** | MetaGPT | SOP 软件工程流程 | 场景过于特定（软件公司模拟），抽象层可借鉴但不需要全量引入 |
|
||
| 🔵 **Later** | RagaAI-Catalyst | 多框架评估 + 安全测试 | 可观测性基础先由 Mastra Evals 覆盖，Red Teaming 作为进阶能力后续引入 |
|
||
|
||
### 详细理由
|
||
|
||
**MCP-Use — High Priority**
|
||
- Claw 当前工具系统是闭源的 skill+tool 模型，缺乏标准协议层
|
||
- MCP 协议正成为 Agent 互操作性的行业标准（Anthropic/OpenAI/Google 都支持）
|
||
- MCP-Use 的 Widget 系统解决"工具结果可视化"的痛点
|
||
- Server Manager 动态工具注册 = Claw 未来需要的"热插拔"能力
|
||
|
||
**Mastra — High Priority**
|
||
- 三个最迫切的需求：Workflow（当前只有 taskflow skill）→ 需要完整的工作流引擎
|
||
- Memory（当前只有 file-based）→ 需要向量存储 + 语义召回
|
||
- Evals（完全没有）→ 需要系统性评估框架
|
||
- Durable Agent + Suspend/Resume = 长时间任务的核心需求
|
||
|
||
**CrewAI — Medium Priority**
|
||
- Role-Task-Crew 三层抽象清晰实用，易于适配
|
||
- Hierarchical Manager 模式补充 RoundRobin
|
||
- Skills Registry 机制可整合到 Self-Evolution 中
|
||
|
||
**AutoGen — Medium Priority**
|
||
- Code Executor 是 Claw ctx_execute 的自然升级方向
|
||
- GroupChat 自由对话模式补充结构化编排
|
||
- .NET 支持可忽略（Claw 是 Node.js/Python 生态）
|
||
|
||
**MetaGPT — Low Priority**
|
||
- SOP 驱动过于刚性，不如 Mastra 的声明式 Workflow 灵活
|
||
- Action Graph 依赖解析可借鉴逻辑，但不需要全量引入
|
||
- 软件工程场景太窄
|
||
|
||
**RagaAI-Catalyst — Later**
|
||
- Mastra 已内置 Evals + Observability 基础
|
||
- Red Teaming 作为安全增强功能后续迭代引入
|
||
- 多框架适配器与 Claw 的单一框架模式不匹配
|
||
|
||
---
|
||
|
||
## 5. Claw 改造方案
|
||
|
||
### 5.1 新模块架构
|
||
|
||
```
|
||
claw-agent-os-v2/
|
||
├── packages/
|
||
│ ├── mcp/ # ← 从 MCP-Use 提取
|
||
│ │ ├── server/ # MCP Server SDK
|
||
│ │ ├── client/ # MCP Client SDK
|
||
│ │ ├── apps/ # MCP Widget 系统
|
||
│ │ └── transport/ # HTTP/stdio/WebSocket/Sandbox
|
||
│ │
|
||
│ ├── workflow/ # ← 从 Mastra 提取
|
||
│ │ ├── engine/ # Graph Workflow 引擎
|
||
│ │ ├── builder/ # 声明式 DSL (.then/branch/parallel)
|
||
│ │ ├── suspend/ # Suspend/Resume 暂停恢复
|
||
│ │ └── durable/ # Durable Execution
|
||
│ │
|
||
│ ├── orchestration/ # ← 从 CrewAI + AutoGen 提取
|
||
│ │ ├── agent/ # Agent 基类
|
||
│ │ ├── role/ # Role-based Agent 定义
|
||
│ │ ├── team/ # Team 编排 (RoundRobin/Hierarchical)
|
||
│ │ ├── task/ # Task 定义与依赖
|
||
│ │ └── executor/ # Code Executor 沙箱
|
||
│ │
|
||
│ ├── memory/ # ← 从 Mastra 提取
|
||
│ │ ├── conversation/ # 对话记忆
|
||
│ │ ├── working/ # 工作记忆
|
||
│ │ ├── semantic/ # 语义召回 (向量)
|
||
│ │ └── persistence/ # 持久化存储
|
||
│ │
|
||
│ ├── observability/ # ← 从 Mastra + RagaAI 提取
|
||
│ │ ├── tracing/ # 全链路追踪
|
||
│ │ ├── evals/ # 评估引擎
|
||
│ │ ├── metrics/ # 指标收集
|
||
│ │ └── security/ # Red Teaming
|
||
│ │
|
||
│ ├── evolution/ # ← 新建，融合各项目
|
||
│ │ ├── skill-registry/ # 技能注册与发现
|
||
│ │ ├── feedback-loop/ # 反馈闭环
|
||
│ │ ├── optimizer/ # 自动优化
|
||
│ │ └── knowledge-base/ # 知识积累
|
||
│ │
|
||
│ └── core/ # ← 现有 Claw 核心改造
|
||
│ ├── runtime/ # Agent Runtime
|
||
│ ├── gateway/ # Gateway API
|
||
│ ├── protocol/ # 统一协议层
|
||
│ └── sandbox/ # 沙箱执行
|
||
```
|
||
|
||
### 5.2 核心数据结构
|
||
|
||
```typescript
|
||
// ===== Agent 定义 =====
|
||
interface ClawAgent {
|
||
id: string;
|
||
name: string;
|
||
role: AgentRole; // ← 从 CrewAI
|
||
model: ModelConfig; // ← 从 Mastra
|
||
tools: ToolBinding[]; // ← 从 MCP-Use (MCP tools)
|
||
memory: MemoryConfig; // ← 从 Mastra
|
||
skills: SkillRef[]; // ← 从 CrewAI + Evolution
|
||
}
|
||
|
||
interface AgentRole {
|
||
title: string;
|
||
goal: string;
|
||
backstory: string;
|
||
expertise: string[];
|
||
constraints: string[];
|
||
}
|
||
|
||
// ===== Workflow 定义 =====
|
||
type WorkflowStep =
|
||
| { type: 'then'; step: string; next: string }
|
||
| { type: 'branch'; condition: string; branches: Record<string, string> }
|
||
| { type: 'parallel'; steps: string[]; join: string }
|
||
| { type: 'suspend'; resumeCondition: string }
|
||
| { type: 'agent'; agent: string; task: Task };
|
||
|
||
interface Workflow {
|
||
id: string;
|
||
name: string;
|
||
steps: Map<string, WorkflowStep>;
|
||
initialState: string;
|
||
durables: boolean; // 是否持久化
|
||
}
|
||
|
||
// ===== MCP 集成 =====
|
||
interface MCPToolBinding {
|
||
server: MCPServerRef;
|
||
tool: string;
|
||
description: string;
|
||
schema: JsonSchema;
|
||
widget?: WidgetConfig; // ← MCP-Use Widget
|
||
}
|
||
|
||
interface MCPServerRef {
|
||
id: string;
|
||
name: string;
|
||
transport: 'http' | 'stdio' | 'websocket' | 'sandbox';
|
||
endpoint: string;
|
||
auth?: AuthConfig;
|
||
}
|
||
|
||
// ===== Memory =====
|
||
interface MemorySystem {
|
||
conversation: ConversationMemory; // 近期对话
|
||
working: WorkingMemory; // 当前任务上下文
|
||
semantic: VectorStore; // 长期语义记忆
|
||
}
|
||
|
||
interface ConversationMemory {
|
||
messages: Message[];
|
||
maxTokens: number;
|
||
summarizationStrategy: 'window' | 'sliding' | 'hierarchical';
|
||
}
|
||
|
||
// ===== Observability =====
|
||
interface Trace {
|
||
executionId: string;
|
||
agentId: string;
|
||
workflowId?: string;
|
||
steps: TraceStep[];
|
||
metrics: MetricPoint[];
|
||
evaluation?: EvalResult;
|
||
}
|
||
|
||
interface EvalResult {
|
||
scores: Record<string, number>; // goal_score, reasoning_score, tool_usage_score...
|
||
passCriteria: boolean;
|
||
suggestions: string[];
|
||
}
|
||
```
|
||
|
||
### 5.3 API 接口
|
||
|
||
```typescript
|
||
// ===== Claw Agent OS v2 API =====
|
||
|
||
// ---- Orchestration API ----
|
||
class ClawOrchestrator {
|
||
// 创建团队
|
||
createTeam(config: {
|
||
agents: ClawAgent[];
|
||
strategy: 'round-robin' | 'hierarchical' | 'free-chat';
|
||
manager?: ClawAgent; // hierarchical 模式的管理者
|
||
}): Team;
|
||
|
||
// 分配任务
|
||
delegate(team: Team, task: Task): TaskHandle;
|
||
|
||
// 执行
|
||
execute(task: TaskHandle): AsyncIterable<OrchestrationEvent>;
|
||
}
|
||
|
||
// ---- Workflow API ----
|
||
class ClawWorkflow {
|
||
// 创建工作流
|
||
define(name: string): WorkflowBuilder;
|
||
|
||
// 运行
|
||
run(workflow: Workflow, input: any): AsyncIterable<WorkflowEvent>;
|
||
|
||
// 暂停/恢复
|
||
suspend(executionId: string): void;
|
||
resume(executionId: string, input?: any): void;
|
||
}
|
||
|
||
// ---- MCP API ----
|
||
class ClawMCP {
|
||
// 注册 MCP Server
|
||
register(server: MCPServerConfig): MCPServerHandle;
|
||
|
||
// 发现工具
|
||
discoverTools(agent: ClawAgent): Promise<MCPToolBinding[]>;
|
||
|
||
// 动态连接
|
||
connect(agent: ClawAgent, server: MCPServerRef): Promise<void>;
|
||
disconnect(agent: ClawAgent, server: MCPServerRef): Promise<void>;
|
||
|
||
// 创建 Widget
|
||
defineWidget(config: WidgetConfig): WidgetHandle;
|
||
}
|
||
|
||
// ---- Memory API ----
|
||
class ClawMemory {
|
||
// 存储
|
||
remember(session: string, entry: MemoryEntry): Promise<void>;
|
||
|
||
// 召回
|
||
recall(session: string, query: string, limit: number): Promise<MemoryEntry[]>;
|
||
|
||
// 摘要
|
||
summarize(session: string): Promise<string>;
|
||
|
||
// 持久化
|
||
snapshot(session: string): Promise<MemorySnapshot>;
|
||
}
|
||
|
||
// ---- Evolve API ----
|
||
class ClawEvolve {
|
||
// 学习
|
||
learn(execution: Trace): Promise<LearningResult>;
|
||
|
||
// 优化
|
||
optimize(agent: ClawAgent, goal: OptimizationGoal): Promise<ClawAgent>;
|
||
|
||
// 技能获取
|
||
acquire(definition: SkillDefinition): Promise<SkillHandle>;
|
||
}
|
||
|
||
// ---- Observe API ----
|
||
class ClawObserve {
|
||
// 开始追踪
|
||
trace(executionId: string): TraceHandle;
|
||
|
||
// 评估
|
||
evaluate(trace: Trace, metrics: Metric[]): Promise<EvalResult>;
|
||
|
||
// 安全测试
|
||
redTeam(agent: ClawAgent): Promise<SecurityReport>;
|
||
}
|
||
```
|
||
|
||
### 5.4 Memory 系统影响
|
||
|
||
| 现有组件 | 改造 | 影响 |
|
||
|---------|------|------|
|
||
| `MEMORY.md` | 保持为稳定核心层 | 不变 |
|
||
| `memory/vault.md` | 迁移到 Vector Store | 向量化，支持语义搜索 |
|
||
| `memory/daily/` | 自动摘要 + 向量索引 | 减少手工维护 |
|
||
| `memory/registers/` | 合并到 ConversationMemory + WorkingMemory | 结构化为运行时记忆层 |
|
||
| `scripts/memory-sync.sh` | 替换为 ClawMemory.persist() | 不再需要 bash 脚本 |
|
||
|
||
### 5.5 Workflow 系统影响
|
||
|
||
| 现有组件 | 改造 |
|
||
|---------|------|
|
||
| `taskflow` skill | 替换为 ClawWorkflow 引擎，保留 TaskFlow job 概念作为 Trigger |
|
||
| `cron` 系统 | 保留，增加 Workflow 触发器类型 |
|
||
| `scripts/` 目录 | 迁移到 Workflow Step 的 Script Action |
|
||
| `sessions_spawn` | 扩展为 Workflow 的 Agent Step |
|
||
|
||
---
|
||
|
||
## 6. PRD — Claw Agent OS v2
|
||
|
||
### 6.1 产品概述
|
||
|
||
**产品名称**: Claw Agent Operating System v2
|
||
|
||
**一句话描述**: 具备 Multi-Agent、Workflow、MCP Native、Memory、Observability、Self-Evolution 六大能力的 AI Agent 操作系统。
|
||
|
||
**目标用户**: AI Agent 开发者、自动化工程师、DevOps 团队
|
||
|
||
### 6.2 核心功能需求
|
||
|
||
#### F1: Multi-Agent Orchestration（多 Agent 编排）
|
||
|
||
| ID | 功能 | 优先级 | 来源 |
|
||
|----|------|--------|------|
|
||
| F1.1 | Role-based Agent 定义（角色+目标+背景+工具+模型） | P0 | CrewAI |
|
||
| F1.2 | Team 编排模式（RoundRobin / Hierarchical / FreeChat） | P0 | CrewAI, AutoGen |
|
||
| F1.3 | Task 依赖链（上一个 Task 输出作为下一个输入） | P1 | CrewAI |
|
||
| F1.4 | Agent 间自由消息路由 | P1 | AutoGen |
|
||
| F1.5 | Hierarchical Manager Agent 委托 | P1 | CrewAI |
|
||
|
||
#### F2: Declarative Workflow（声明式工作流）
|
||
|
||
| ID | 功能 | 优先级 | 来源 |
|
||
|----|------|--------|------|
|
||
| F2.1 | Graph-based Workflow 引擎 | P0 | Mastra |
|
||
| F2.2 | 声明式控制流 DSL（.then/.branch/.parallel） | P0 | Mastra |
|
||
| F2.3 | Suspend/Resume（暂停人工审批） | P0 | Mastra |
|
||
| F2.4 | Durable Execution（持久化执行状态） | P1 | Mastra |
|
||
| F2.5 | 可视化 Workflow 编辑器 | P2 | Mastra Playground |
|
||
|
||
#### F3: MCP Native（MCP 协议原生集成）
|
||
|
||
| ID | 功能 | 优先级 | 来源 |
|
||
|----|------|--------|------|
|
||
| F3.1 | MCP Server SDK（TypeScript） | P0 | MCP-Use |
|
||
| F3.2 | MCP Client SDK（多传输协议） | P0 | MCP-Use |
|
||
| F3.3 | 动态工具注册（Server Manager 模式） | P0 | MCP-Use |
|
||
| F3.4 | MCP Widget 系统（跨平台工具可视化） | P1 | MCP-Use |
|
||
| F3.5 | MCP Inspector 内置调试工具 | P1 | MCP-Use |
|
||
|
||
#### F4: Memory System（多层级记忆）
|
||
|
||
| ID | 功能 | 优先级 | 来源 |
|
||
|----|------|--------|------|
|
||
| F4.1 | Conversation Memory（对话记忆 + 自动摘要） | P0 | Mastra |
|
||
| F4.2 | Working Memory（当前任务上下文） | P0 | Mastra |
|
||
| F4.3 | Semantic Recall（向量语义召回） | P1 | Mastra |
|
||
| F4.4 | 记忆持久化 + 跨会话恢复 | P1 | Mastra |
|
||
| F4.5 | Memory 管理 API（curd/search/summarize） | P1 | 自研 |
|
||
|
||
#### F5: Observability & Evaluation（可观测性）
|
||
|
||
| ID | 功能 | 优先级 | 来源 |
|
||
|----|------|--------|------|
|
||
| F5.1 | 全链路执行追踪 | P0 | Mastra |
|
||
| F5.2 | Agent 评估引擎（多维指标评分） | P1 | Mastra, RagaAI |
|
||
| F5.3 | 指标收集 + Dashboard | P2 | Mastra |
|
||
| F5.4 | Red Teaming 安全测试 | P2 | RagaAI |
|
||
| F5.5 | 告警规则 + 自动回滚 | P3 | 自研 |
|
||
|
||
#### F6: Self-Evolution（自我进化）
|
||
|
||
| ID | 功能 | 优先级 | 来源 |
|
||
|----|------|--------|------|
|
||
| F6.1 | Skills Registry（技能注册/发现/缓存） | P1 | CrewAI |
|
||
| F6.2 | 反馈闭环（执行→评估→优化） | P2 | Mastra Evals |
|
||
| F6.3 | Agent 自动调优（基于评估指标） | P2 | 自研 |
|
||
| F6.4 | 知识库积累（从执行中学习） | P3 | 自研 |
|
||
|
||
### 6.3 非功能需求
|
||
|
||
| ID | 需求 | 描述 |
|
||
|----|------|------|
|
||
| NF1 | 协议兼容 | MCP 协议 v1.0+ 完全兼容 |
|
||
| NF2 | 传输协议 | 支持 HTTP/SSE, stdio, WebSocket, Sandbox |
|
||
| NF3 | 扩展性 | 插件系统支持自定义 Agent/Tool/Workflow Step |
|
||
| NF4 | 性能 | Workflow 支持 100+ Steps、1000+ 并行分支 |
|
||
| NF5 | 持久化 | 支持 SQLite（单机）/ PostgreSQL（分布式） |
|
||
| NF6 | 安全 | API Key / OAuth / Bearer Token 统一认证 |
|
||
|
||
### 6.4 技术栈
|
||
|
||
| 层 | 技术选型 | 理由 |
|
||
|----|---------|------|
|
||
| Runtime | Node.js 22+ / Python 3.12+ | 双语言支持 |
|
||
| Agent Engine | LangChain 1.0 + Mastra Core | 复用成熟生态 |
|
||
| Workflow | Mastra Workflow Engine | Graph-based, 经过生产验证 |
|
||
| MCP | MCP-Use SDK (TS) | 最完整的 MCP 实现 |
|
||
| Memory | Pinecone / pgvector | 向量存储 |
|
||
| Storage | Drizzle ORM + SQLite/PG | 轻量 + 可扩展 |
|
||
| Observability | OpenTelemetry + Mastra Loggers | 标准化 |
|
||
|
||
### 6.5 里程碑计划
|
||
|
||
#### Phase 1: Foundation（8 周）
|
||
- [ ] MCP Server + Client SDK 集成到 Claw
|
||
- [ ] Agent 改造：支持 MCP Tool 注册
|
||
- [ ] Memory Layer: Conversation + Working Memory
|
||
- [ ] 现有 skill 系统 → MCP Tool 迁移
|
||
|
||
#### Phase 2: Orchestration（6 周）
|
||
- [ ] Role-based Agent 定义
|
||
- [ ] Team 编排（RoundRobin + Hierarchical）
|
||
- [ ] Task 依赖链
|
||
- [ ] Code Executor 沙箱升级
|
||
|
||
#### Phase 3: Workflow（6 周）
|
||
- [ ] Graph Workflow 引擎集成
|
||
- [ ] Suspend/Resume 人工审批
|
||
- [ ] Durable Execution
|
||
- [ ] 现有 taskflow/cron 迁移
|
||
|
||
#### Phase 4: Quality（4 周）
|
||
- [ ] Observability 全链路追踪
|
||
- [ ] Evals 评估框架
|
||
- [ ] Self-Evolution Skills Registry
|
||
- [ ] Dashboard
|
||
|
||
### 6.6 迁移路径
|
||
|
||
```
|
||
Claw v1 (当前)
|
||
├── skills/ → MCP Tools (F3)
|
||
├── taskflow skill → Workflow Engine (F2)
|
||
├── cron → Workflow Trigger (F2)
|
||
├── MEMORY.md → Memory System (F4)
|
||
├── sessions_* → Agent Orchestration (F1)
|
||
├── ctx_execute → Code Executor (F1)
|
||
└── N/A → Observability (F5) + Evolution (F6)
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：融合决策树
|
||
|
||
```
|
||
需要工具标准化？
|
||
└─ YES → MCP-Use → MCP Native Integration (F3)
|
||
|
||
需要复杂流程控制？
|
||
└─ YES → Mastra → Declarative Workflow (F2)
|
||
|
||
需要多 Agent 协作？
|
||
├─ 结构化角色 → CrewAI → Role-based Agent (F1.1-1.3)
|
||
├─ 自由对话 → AutoGen → FreeChat Mode (F1.4)
|
||
└─ 管理委托 → CrewAI → Hierarchical Manager (F1.5)
|
||
|
||
需要长记忆？
|
||
└─ YES → Mastra → Memory System (F4)
|
||
|
||
需要质量控制？
|
||
├─ 基础评估 → Mastra → Evals (F5.2)
|
||
└─ 安全测试 → RagaAI → Red Teaming (F5.4)
|
||
|
||
需要自我进化？
|
||
└─ YES → CrewAI Skills + Mastra Evals → Self-Evolution (F6)
|
||
```
|
||
|
||
---
|
||
|
||
> 文档版本: v1.0
|
||
> 下次更新: Phase 1 启动时
|