🎉 init: 小龙的工作空间

2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
@@ -0,0 +1,678 @@
+# 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 启动时