# manus

**Repository Path**: longrenbang_mark/manus

## Basic Information

- **Project Name**: manus
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-28
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 整体说明

fastAPI+Uvicorn:多进程 + 单线程EventLoop/进程

```shell
#--workers 4 指定进程数
uvicorn app.main:app --workers 4
```

netty:单进程 + 多线程EventLoop

# uv包管理工具

## 传统pip+.venv

创建环境

```shell
python -m venv .venv
```

激活环境

```shell
# win
.venv/Scripts/active

# mac
source .venv/bin/activate
```

安装依赖

```shell
pip install xx
```

生成依赖文件

```shell
pip freeze > reqirements.txt
```

同步环境依赖

```shell
pip install -r reqirements.txt
```

## uv新一代包管理工具

https://docs.astral.sh/uv/

uv完全支持pip-tools工作流

安装

```shell
curl -LsSf https://astral.sh/uv/install.sh | sh
```

创建环境

```shell
uv  venv --python 3.12
```

初始化项目

```shell
uv init
```

安装依赖

```shell
uv add fastapi 
```

移除依赖

```shell
uv remove fastapi 
```

在项目虚拟环境中执行命令，无需手动激活环境 推荐使用

```shell
uv run <command>
```

根据nv.lock文件同步依赖到虚拟环境，确保环境一致

```shell
uv sync
```

```shell
uv run uvicorn app.main:app --reload
```

# manus

## 运行项目

```shell
uv run uvicorn main:app --reload
```

## pydantic库

Pydantic 是一个用于 Python 的、主要基于类型提示（Type Hints）的数据验证和设置管理库

核心功能是：在你使用数据之前，确保数据的形状、格式和类型符合你的预期

## ReAct和CoT

### Chain-of-Th-Thought (CoT)

核心思想：通过让模型生成一系列中间推理步骤，最终得到答案。它模仿了人类解决问题时的“一步一步思考”的过程。

特点：纯粹在模型内部进行推理。它不涉及与外部环境（如工具、API、知识库）的交互。

两种形式：

标准CoT：在提示中给出几个带有推理步骤的例子（Few-Shot），模型会模仿这种格式。

Zero-Shot CoT：直接指令模型“让我们一步一步地思考”，无需示例。

### ReAct (Reasoning + Acting)

核心思想：将推理和行动交织在一起。模型通过思考来决定下一步该做什么（推理），然后执行一个动作（行动），并根据行动的结果再进行下一步的思考和行动。

特点：是一个与外部环境交互的循环闭环。它结合了大型语言模型的内在知识和外部工具的计算/检索能力。

三个核心步骤的循环：

Thought：根据当前情况和目标，推理下一步应该做什么。

Action：执行一个具体的动作（如使用搜索引擎、查询数据库、调用计算器）。

Observation：获取动作执行后的结果（如搜索引擎返回的摘要、数据库查询的记录）。

### 关联与区别

我们可以从两个层面来看它们的关联：演进关系和协同关系。

1. 演进关系：ReAct 建立在 CoT 之上
   ReAct 可以看作是 CoT 思想在需要与环境交互的任务上的自然延伸和增强。

CoT解决了“想清楚”的问题：它证明了让模型展示其内部推理过程，可以显著提高其在复杂问题（如数学、逻辑推理）上的准确性和可解释性。

ReAct解决了“做正确的事”的问题：对于需要外部信息或工具才能解决的问题（如问答、事实核查），光“想”是不够的，还必须“做”。ReAct 将
CoT 的“思维链”扩展为“思维-行动链”，在推理步骤中插入了改变状态的实际行动。

可以说，ReAct = CoT + 工具调用（Tool Use）。

2. 协同关系：ReAct 内部包含并依赖于 CoT
   在 ReAct 的每一步循环中，Thought（思考） 环节本质上就是一个微型的、目标导向的 CoT。

当模型生成一个 Thought 时，它正是在进行内部推理：“基于我已有的信息（初始问题和之前的观察），我现在缺少什么信息？我应该使用哪个工具来获取这个信息？我应该问什么问题？”

这个推理过程就是一条小型的思维链，它引导模型做出下一个正确的 Action。

### 实例对比

假设问题是：“现任英国首相的宠物狗的名字是什么？”

CoT 的回答方式：

思考：我记得鲍里斯·约翰逊是英国首相，他有一只狗叫迪琳。

思考：但问题是“现任”首相。我不太确定现在还是不是他。

最终答案：基于我的知识，如果鲍里斯·约翰逊仍然是首相，那么答案是迪琳。但我无法确认他是否还是首相。

结果：答案可能是错误的，因为模型知识有截止日期，它不知道里希·苏纳克已经接任。

ReAct 的回答方式：

Thought：要回答这个问题，我需要知道现任英国首相是谁，然后才能查他的宠物狗的名字。我应该先搜索“现任英国首相”。

Action: Search(现任英国首相)

Observation: [维基百科摘要：现任英国首相是里希·苏纳克，自2022年10月起任职。]

Thought：好的，现任首相是里希·苏纳克。现在我需要搜索“里希·苏纳克 宠物狗”。

Action: Search(里希·苏纳克 宠物狗)

Observation: [新闻文章：里希·苏纳克有一只拉布拉多犬，名叫诺瓦。]

Thought：我已经找到了所需信息，现任英国首相里希·苏纳克的宠物狗名叫诺瓦。我可以给出最终答案了。

Final Answer: 诺瓦。

结果：通过结合推理和行动，ReAct 给出了准确且最新的答案。

## DDD领域驱动设计

![img.png](_images/ddd.png)

### 用户接口层(interface) or 接入层/表示层(presentation)

职责：处理HTTP请求，解析websocket消息，序列化响应数据

### 应用层(application)

职责：代表一个完整的usecase用例，负责协调领域层的多个对象，完成一个业务操作

### 领域层(domain)

职责：包含所有核心业务逻辑，状态和规则

### 基础设施层(infrastructure)

职责：为其他层提供技术实现，如仓储，数据库配置，外部服务客户端，缓存实现

## pydantic-settings库读取配置文件

```python
from pydantic_settings import BaseSettings, SettingsConfigDict
from functools import lru_cache


class Settings(BaseSettings):
    """项目的整体配置信息"""
    env: str = "development"
    log_level: str = "INFO"

    sqlalchemy_database_uri: str = ""

    redis_host: str = "localhost"
    redis_port: int = 6379
    redis_db: int = 0
    redis_password: str | None = None

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore"
    )


@lru_cache()
def get_settings() -> Settings:
    """获取当前项目的配置信息，并对内容进行缓存，避免重复读取"""
    settings = Settings()
    return settings

```

## mcp协议

MCP全称Model Context Protocol，即模型上下文协议 ，起源于2024年11月25日Anthropic发布的文章：Introducing the Model Context
Protocol，MCP 定义了应用程序和AI模型之间交换上下文信息的方式，这使得开发者能够以一致的方式将各种数据源、工具和功能连接到AI模型（MCP并不是什么框架，也不是什么技术的突破，而仅仅一个中间协议层）。

![img.png](_images/mcp.png)

### MCP服务三个核心组件

1. MCP Hosts：运行 MCP 的主应用程序，例如 Claude Desktop、智能 IDE 或 AI 工具，负责通过MCP访问外部数据。

2. MCP Clients：协议客户端，与服务器建立一对一连接，负责发送请求并接收响应。

3. MCP Servers：轻量级程序，通过MCP暴露特定功能（如文件读取或 API 调用）。

![img.png](_images/mcp_process.png)

### MCP请求&响应消息格式

MCP客户端和服务器之间的所有消息必须遵循JSON-RPC 2.0规范，并且在协议中定义了四类消息类型：

#### 请求（Requests）

请求从 Client 发送到 Server，或者从服务器发送到客户端，用于启动操作，数据格式如下：

```plantuml
{
	jsonrpc: "2.0";
	id: string | number;
	method: string;
	params ? : {
		[key: string]: unknown;
	};
}
```

MCP协议基于JSON-RPC 2.0规范，确定了JSON-RPC 2.0中参数的特定值，如请求获取tools列表：

符合JSON-RPC 2.0规范中请求的规范，并指定了method为tools/list

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}
```

1. 请求必须包含字符串或整数 ID。
2. 与基本JSON-RPC不同，ID不得为null 。
3. 请求ID不得在同一会话中被请求者先前使用过（不过现实服务中，大部分没这类要求）。

#### 响应（Responses）

响应是对请求的回复，包含操作的结果或错误，数据格式如下:

```plantuml
{
	jsonrpc: "2.0";
	id: string | number;
	result ? : {
		[key: string]: unknown;
	}
	error ? : {
		code: number;
		message: string;
		data ? : unknown;
	}
}
```

1. 响应必须包含与其对应请求相同的ID。
2. 响应进一步分为成功结果或错误。必须设置result或error中的一个。响应不得同时设置两者。
3. 结果可以遵循任何JSON对象结构，而错误必须至少包含错误代码和消息。
4. 错误代码必须是整数。

#### 通知（Notifications）

通知从客户端发送到服务器，或者从服务器发送到客户端，作为单向消息。接收方不得发送响应，数据格式如下：

```plantuml
{
	jsonrpc: "2.0";
	method: string;
	params ? : {
		[key: string]: unknown;
	}
}
```

通知不得包含ID

#### 批处理（Batching）

JSON-RPC 还定义了批量处理多个请求和通知的方法，将它们放在一个数组中发送。MCP 实现可以支持
发送 JSON-RPC 批处理，但必须支持接收 JSON-RPC 批处理（具体是否支持看对应的 MCP 服务商），数
据格式如下：

```plantuml
Array<{
	jsonrpc: "2.0";
	id: string | number;
	method: string;
	params ? : {
		[key: string]: unknown;
	};
}>
```

除了JSON-RPC外，在MCP协议草案中，目前还提供了一个用于HTTP的授权认证，不过该方案目前仍
然是草案阶段，当前绝大部分MCP服务都是客户端和服务端自行定义认证和授权策略（例如使用ENV
环境变量+api key的方式）。

### MCP的生命周期

1. 初始化： 能力协商和协议版本约定，亦或者初始化会话id；
2. 操作： 正常协议通信，例如 `获取工具列表`、`调用指定工具`、`批处理` 等。
3. 关闭： 连接的优雅终止。

![img.png](_images/mcp_life.png)

首先是初始化阶段，这是客户端和服务器的第一次交互（实际上很多 MCP 服务因为无需管理状态，每次
工具调用都是独立无状态+及时响应的，所以没有初始化阶段和关闭阶段，上述时序图中的虚线）。
在初始化阶段，客户端必须使用 JSON-RPC 标准发送包含 initialize 的数据来启动此阶段，告知服务
端客户端具备的能力，涵盖：支持的协议版本、客户端能力、客户端等信息（完整信息查看：https://m
odelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#capability-negotiation），例如：

```plantuml
{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "initialize",
	"params": {
		"protocolVersion": "2024-11-05",
		"capabilities": {
			"roots": {
				"listChanged": true
			},
			"sampling": {}
		},
		"clientInfo": {
			"name": "ExampleClient",
			"version": "1.0.0"
		}
	}
}
```

在接收到客户端的初始化请求后，服务端必须响应其自身的能力和信息：

```plantuml
{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"protocolVersion": "2024-11-05",
		"capabilities": {
			"logging": {},
			"prompts": {
				"listChanged": true
			},
			"resources": {
				"subscribe": true,
				"listChanged": true
			},
			"tools": {
				"listChanged": true
			}
		},
		"serverInfo": {
			"name": "ExampleServer",
			"version": "1.0.0"
		}
	}
}
```

同时在初始化成功之后，客户端必须发送 initialized 通知以表示其已准备好开始正常操作：

```plantuml
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}
```

下一步就是操作阶段，在操作阶段，客户端和服务器根据协商好的能力交换JSON-RPC消息（如果使用
MCP SDK构建MCP服务，则内置预设了三个功能：Prompts(提示)、Resources(资源)、Tools(工具).

最后就是关闭阶段，MCP协议中也没有定义专门的关闭消息，而是使用底层传输机制指示连接终止，一
方（通常是客户端）会优雅地终止协议连接，同时在服务端对相应的资源进行释放、会话清除等。

### MCP的两种传输机制

标准输入输出(stdio)：基于操作系统提供的标准输入和标准输出机制实现，例如常见的命令行程序，
就是通过标准输入向程序传递指令和程序，通过标准输出返回处理结果，更适合用于本地小工具集成、
处理个人隐私数据、快速做功能Demo看效果等。

![img.png](_images/mcp_stdio.png)

可流式HTTP(Streamable-HTTP)：基于HTTP协议的流式传输协议，允许数据以流的形式在客户端
和服务器之间传输，而不需要一次性将所有数据加载完成（简单理解就是云端 API），更适合用于生产
环境、分布式系统和无状态服务架构等场景。

https://github.com/tadata-org/fastapi_mcp 将fastAPI应用转成成mcp server的一个库

1. 初始化请求发起后，收到的响应头中会携带mcp-session-id（并不是所有的mcp server都会返回，例如高德地图就没有
   因为是无状态的），这个字段可以用于标识某次会话的持续性（服务端有状态），所以需要客户端额外发起一次通知，告诉服务端，我准备好了；
2. 因为是可流式HTTP(GET+POST)，所以如果操作请求一次响应能完成（例如查询天气），则一次后
   会关闭；否则会像SSE一样一直传输数据（例如LLM每次输出输出）；
   ![img.png](_images/mcp_http.png)

### mcp server站点推荐

1. https://www.mcpworld.com/
2. https://bailian.console.aliyun.com/

# manus运行流程图

![img.png](_images/manus-flow.png)

![img.png](_images/manus-flow2.png)

## redis-stream

Redis Stream是Redis5.0引入的一种持久化的、可追加的、支持多消费者组的消息队列数据结构。它专门为消息流（log-like data
streams）场景设计，弥补了Redis原有Pub/Sub（消息不持久化）和List（功能简单的不足。）

```redis
xadd stream_name * username "linger" age 18
```

## 任务流事件拆解

![img.png](_images/event-stream.png)

## MCP工具

https://jina.ai

## Playwright和Browser-use

### CDP协议

CDP指的是Chrome DevTools Protocol(Chrome开发工具协议)

是一套允许第三方程序与chrome进行通信 调试 检测和控制的协议，日常的f12打开的开发者工具，本质上是一个webapp，通过CDP协议和
浏览器内核对话，Chrome浏览器通过特定的操作暴露出接口，使用特定的方法就可以和浏览器内核对话/操作。

windows系统启动CDP端口

```
#假设chrome安装在默认位置
"c:\program files\Goole\chrome\Application\chrome.exe" 
--remote-debugging-port=9222 
--user-data-dir="D:\chorme_dev-profile"
```

macOS系统启动CDP端口

```
/Application/Google\Chrome.app/Contents/MacOS/Google\Chrome 
--remote-debugging-port=9222 
--user-data-dir="/tmp/chrome_dev_test"
```

Linux系统启动CDP端口

```
google-chrome 
--remote-debugging-port=9222 
--user-data-dir="/tmp/chrome_dev_test"
```

启动成功之后，浏览器会自动打开。此时Chrome正在监听本地的9222端口，这时候访问http://127.0.0.1:9222/json/version

```json
{
  "Browser": "Chrome/149.0.7827.201",
  "Protocol-Version": "1.3",
  "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",
  "V8-Version": "14.9.207.35",
  "WebKit-Version": "537.36 (@6a7b3dbec3b2ca25877c2553b5473b2f277ef644)",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/a8a6778f-2266-4584-9446-e9e8da4d3b87"
}
```

其中**websocketDebuggerUrl**是CDP连接地址，如果你想查看当前打开了哪些标签页，请求http://127.0.0.1:9222/json/list,通过
websocket连接+实时传递参数，可以快速通过接口操控浏览器

使用websocket连接之后可以通过jsonrpc规则发送消息控制浏览器

控制页面跳转

```json
{
  "id": 1,
  "method": "Page.navigate",
  "params": {
    "url": "https://www.baidu.com"
  }
}
```

执行js代码

```json
{
  "id": 2,
  "method": "Runtime.evaluatie",
  "params": {
    "expression": "alert('使用CDP控制中')"
  }
}
```

获取当前页面的title

```json
{
  "id": 3,
  "method": "Runtime.evaluatie",
  "params": {
    "expression": "document.title",
    "returnByValue": true
  }
}
```

进行截图

```json
{
  "id": 4,
  "method": "Page.catureScreenshot",
  "params": {
    "format": "png"
  }
}
```

...

## 基于docker沙箱环境

### 常见的沙箱执行环境

1. docker容器，最常见，隔离性好，但启动慢，资源开销大。
2. MicroVM：基于硬件虚拟化（KVM）提供强隔离，启动快，适合不可信代码执行。表‌：E2B (Firecracker)、AWS Firecracker、QEMU 精简模式 。
3. WebAssembly (WASM/WASI)‌：基于能力模型的轻量级沙箱，跨平台且内存安全。‌代表‌：Wasmtime、Wasmer、MoonBit 运行时、Cloudflare
   Workers 。
4. 阿里云等云服务厂商

### 典型应用场景与选型建议

1. AI Agent 代码执行‌：首选 ‌E2B (Firecracker)‌ 或 ‌Docker‌，需兼顾多轮状态保持、文件系统操作及网络可控性 。
2. ‌在线编程评测/OJ‌：常用 ‌Docker‌ 或 ‌gVisor‌，平衡启动速度与隔离性，支持多语言镜像 。
3. ‌前端/插件隔离‌：使用 ‌浏览器沙箱 (iframe)‌ 或 ‌WASM‌，防止全局变量污染和恶意 DOM 操作 。
4. ‌恶意代码分析‌：采用 ‌完整虚拟机 (VM)‌ 或 ‌Firecracker‌，确保恶意行为完全无法逃逸至宿主机 。
5. ‌边缘/轻量计算‌：倾向 ‌WASM‌，极低内存占用和毫秒级启动，适合 Serverless 场景 。

### manus沙箱交互逻辑

![img.png](_images/sandbox.png)

## supervisor 进程管理程序

### 简介

https://supervisord.org

Supervisor 是一个用 Python 开发的进程管理工具，专门在 Linux/Unix
系统上管理那些需要长期运行的后台程序。它的核心作用就是守护进程：当被它管理的程序意外崩溃或被杀死时，Supervisor
能自动把它重新拉起来，保证服务持续可用

### 对比Systemd(systemctl)

管理范围（最核心区别）

- Systemctl（Systemd）：管理系统全局的服务。它是 Linux 内核启动后运行的第一个进程（PID
  1），负责挂载文件系统、启动网络、管理系统硬件等。它管的是整个操作系统的底层服务（如 sshd、nginx、数据库）。

- Supervisor：管理单个用户或特定应用的进程。它运行在操作系统之上，不关心网络或硬件，只专注于把你写的代码（如 Python/Node.js
  脚本、Java Jar 包）变成一个长期运行的后台服务。

适用场景

- Systemctl：适合稳定、原生的系统软件。这些服务通常由系统包管理器（如 apt 或 yum）安装，配置好后很少变动。

- Supervisor：极其适合开发环境和频繁迭代的应用。如果你每天要多次更新代码、重启服务，Supervisor 极其方便；其次，如果你跑的是非标准程序（比如自己写的
  Shell 脚本、Python 爬虫、或者需要指定特定 Python 虚拟环境的应用），写 systemd 脚本比较繁琐，但 Supervisor 写几行配置就能搞定。

进程管理特性

- Systemctl：依赖传统的 PID（进程号）文件来追踪进程。如果程序“双叉”（fork）变成守护进程，systemd 有时会抓错 PID，导致重启失效。
- Supervisor：不依赖 PID
  文件。它采用“进程组”的方式，直接把自己作为被管理进程的父进程。当程序崩溃时，它能瞬间感知（而非轮询）并立即拉起来，响应速度极快。而且它规定程序必须以前台（Foreground）运行，彻底杜绝了守护进程导致的管理混乱。

### mac上使用

安装

```shell
brew install supervisor
```

启动

```shell
# 最简单的方法：用 brew 提供的命令启动服务
brew services start supervisor
```

```shell
# 用 -c 指定配置文件，-n 表示在前台运行（不要关闭这个终端窗口）
supervisord -n -c /opt/homebrew/etc/supervisord.conf
```

### 常规操作

```shell

# 查看所有程序的状态
supervisorctl status all

# 启动、停止、重启特定程序
supervisorctl start myapp
supervisorctl stop myapp
supervisorctl restart myapp

# 启动、停止、重启所有程序
supervisorctl start all
supervisorctl stop all
supervisorctl restart all

# 重新加载整个 Supervisor 的配置（会重启所有程序）
supervisorctl reload
```

### 配置文件supervisord.conf

包含两部分配置，一部分是Supervisor本身配置，另一部分是管理进程配置

```ini
; ============================================
; Supervisor 自身配置（主配置文件）
; ============================================

[unix_http_server]
; 客户端（supervisorctl）连接用的 socket 文件路径
file = /opt/homebrew/var/run/supervisor.sock
; socket 文件权限，默认 0700 表示只允许本用户访问
chmod = 0700

[supervisord]
; 日志文件路径
logfile = /opt/homebrew/var/log/supervisord.log
; 日志文件大小上限，达到后自动轮转
logfile_maxbytes = 50MB
; 保留的旧日志文件数量
logfile_backups = 10
; 日志级别（debug, info, warn, error, critical）
loglevel = info
; 是否将 supervisord 自身以守护进程方式运行
nodaemon = false
; PID 文件路径，用于记录进程号
pidfile = /opt/homebrew/var/run/supervisord.pid
; 启动时等待子进程启动的最大秒数
minfds = 1024
; 最小可用的进程数限制
minprocs = 200

[supervisorctl]
; 客户端连接服务器使用的 URL，必须和上面的 file 路径一致
serverurl = unix:///opt/homebrew/var/run/supervisor.sock

[include]
; 包含外部配置文件，每个进程独立一个 .conf 文件，方便管理
files = /opt/homebrew/etc/supervisor/conf.d/*.conf
```

```ini

; ============================================
; 进程配置：myapp
; ============================================

[program:myapp]
; 启动命令（必须以前台模式运行，不能加 daemon 参数）
command = python3 /Users/yourname/myapp/app.py

; 程序的工作目录
directory = /Users/yourname/myapp

; 运行进程的操作系统用户（macOS 下用你的用户名）
user = yourname

; 是否随 supervisord 启动而自动启动
autostart = true

; 进程退出后自动重启（true=总是重启，false=不重启，unexpected=意外退出时重启）
autorestart = true

; 启动后稳定运行 10 秒才认为启动成功
startsecs = 10

; 启动失败时的最大重试次数
startretries = 3

; 把标准错误输出重定向到标准输出，方便统一查看日志
redirect_stderr = true

; 标准输出日志文件路径
stdout_logfile = /Users/yourname/myapp/logs/myapp.log
; 单个日志文件上限 10MB
stdout_logfile_maxbytes = 10MB
; 保留 5 个旧日志备份
stdout_logfile_backups = 5

; 环境变量（可选）
environment = PYTHONPATH="/Users/yourname/myapp",ENV="production"

; 停止信号（默认 TERM，某些程序需要 KILL）
stopsignal = TERM

; 等待进程停止的最长时间（秒），超时后强制杀死
stopwaitsecs = 10
```

### 管理沙箱进程思路

1. 安装chrome浏览器，并且开放cdp_url,同时socat将cdp_url的数据双向绑定到另一个端口，以解决chrome只能本地ip访问的限制
2. 安装x11vnc实现远程桌面，并使用websockify将VNC转换为websocket流量，以便前端可以通过浏览器查看远程桌面；
3. 安装xvfb启动虚拟显示器（在内存中模拟运行一个显示器）以供chrome浏览器模拟使用；

相当于整个docker容器中，会同时运行fastAPI+chrome+socat+xvfb+websockify 6个进程

![img.png](_images/sandbox2.png)

### 沙箱保活与资源合理分配

沙箱内部代码定时检查是否有新请求，加上docker run的时候加上参数 --rm

### 多任务多沙箱下使用docker提供的ip实现访问思路

## Agent-to-Agent(A2A)协议

### 简介

Agent2Agent (A2A) 协议是一个开放标准，旨在让不同框架或供应商构建的AI智能体能够相互通信、协作，而无需共享内部实现。

```mermaid
sequenceDiagram
    participant Client as 客户端智能体
    participant Remote as 远程智能体
    Note over Remote: 托管着Agent Card<br>（能力名片，JSON格式）
    Client ->> Remote: 1. 获取Agent Card<br>（发现能力）
    Remote -->> Client: 返回Agent Card
    Client ->> Remote: 2. 发起任务请求<br>（如 tasks/send）
    Note over Client, Remote: 通信基于JSON-RPC over HTTP
    Remote -->> Client: 3. 实时反馈与最终结果<br>（任务状态更新、产物）
    Note over Client, Remote: 支持长时间任务、流式传输(SSE)<br>和推送通知
```

参与者

- 用户 (User)：发起任务的最终实体，可以是人类，也可以是某个自动化服务。他们是整个协作流程的起点。
- 客户端 (Client)：代表用户发出请求的智能体或应用程序。它负责寻找合适的远程智能体、发起任务并管理通信状态。
- 远程智能体 (Remote Agent / Server)：作为A2A服务器端的智能体，负责接收并执行客户端分派的任务。它的内部运作机制对外部是“黑盒”，保证了核心逻辑和数据的安

通信元素

- 智能体名片 (Agent Card)
  服务发现与能力声明：一个JSON格式的公开文件，相当于智能体的“数字简历”。它描述了智能体的身份、技能、端点地址和认证方式，让客户端能找到并了解如何与之交互。通常托管在/.well-known/agent.json路径下
- 任务 (Task) 有状态的工作单元：代表一次需要跟踪和管理的完整工作流程。每个任务都有唯一ID，并会经历一个生命周期，如
  已提交、工作中、需要输入、已完成 或 失败 等状态。这是支持长时协作和多轮交互的基础。
- 消息 (Message) 单轮通信的载体：用于在客户端和智能体之间传递指令、上下文、问题或状态更新等信息。每条消息都包含发送者的角色（“用户”或“智能体”）和具体的内容（由一个或多个Part构成）
- 片段 (Part) 内容的原子单元：是构成消息或工件的基本内容块。它支持多种数据类型，包括文本 (TextPart)、文件 (
  FilePart，可内联或通过URI引用) 和结构化数据 (DataPart，如JSON格式的表单)
- 工件 (Artifact)
  智能体产出的结果：是智能体在处理任务过程中生成的有形输出，例如一份报告、一张图片或一个分析结果文件。工件同样由片段(Part)
  构成，可以随着任务进度分块流式传输

流式传输 (Streaming)：通过服务器发送事件 (SSE) 实现，用于实时推送任务状态更新或逐步生成的工件（如长文档的生成过程）。

推送通知 (Push Notifications)：适用于可能持续数小时甚至数天的超长任务。客户端提供一个Webhook
URL，当任务状态发生重大变化（如完成、失败或需要人工输入）时，服务器会异步通知客户端，无需维持长连接

### 生命周期

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Server as A2A 服务端
    participant Executor as Agent 执行器
    participant Storage as 任务存储
%% 阶段一：服务发现
    Client ->> Server: GET /.well-known/agent.json
    Server -->> Client: 返回 Agent Card (能力、端点、认证)
    Note over Client, Server: 客户端解析 Agent Card，准备发起请求
%% 阶段二：提交任务（简单 Message 场景）
    Client ->> Server: POST /message (无状态请求)
    Server ->> Executor: 直接处理
    Executor -->> Server: 即时返回结果
    Server -->> Client: 返回 Message 响应
%% 阶段三：提交任务（复杂 Task 场景）
    Client ->> Server: POST /task (创建 Task)
    Note over Server: 生成 taskId & contextId
    Server ->> Storage: 保存任务状态 (submitted)
    Server -->> Client: 返回 Task 对象 (含 taskId)
%% 阶段四：异步处理
    Server ->> Executor: 异步执行任务
    Executor -->> Storage: 更新状态为 working
%% 状态更新 - 轮询方式
    loop 轮询 (Polling)
        Client ->> Server: GET /task/{taskId}/status
        Server ->> Storage: 查询当前状态
        Storage -->> Server: 返回状态 (working)
        Server -->> Client: 返回状态更新
    end

%% 或使用 SSE 推送
    Note over Client, Server: 也可选择 SSE 方式接收推送
%% 阶段五：需要补充信息
    Executor -->> Storage: 更新状态为 input-required
    Storage -->> Server: 触发状态变更
    Server -->> Client: (SSE 推送或轮询返回) 状态更新 + 所需信息说明
    Client ->> Server: POST /task/{taskId}/input (补充信息)
    Server ->> Storage: 更新任务数据
    Server ->> Executor: 继续执行 (状态回到 working)
%% 阶段六：任务完成
    Executor -->> Storage: 更新状态为 completed + 结果数据
    Client ->> Server: GET /task/{taskId} (获取最终结果)
    Server ->> Storage: 查询完整任务数据
    Storage -->> Server: 返回任务 (含结果)
    Server -->> Client: 返回最终结果
%% 阶段七：任务取消
    Client ->> Server: POST /task/{taskId}/cancel
    Server ->> Executor: 执行取消逻辑
    Executor -->> Storage: 更新状态为 canceled
    Server -->> Client: 确认取消
    Note over Client, Storage: 任务进入终态后 (completed/failed/canceled/rejected) 不可再变更
```

### a2a传输协议

a2a协议底层传输协议最早只支持JSON-RPC2.0，1.0版本以后开始支持GRPC和HTTP+JSON/REST三种传输协议

常见的传输协议格式：

- JSON-RPC 采用json格式数据传输
- XML-RPC 采用xml数据格式（模拟supervisor客户端时候用到）
- gRPC 采用protobuf数据格式
- HTTP ...

注意事项：
官方的0.3版本和1.0版本有较大差异，1.0版本有很多地方都在兼容0.3版本

例如使用JSON-RPC2.0作为传输协议的时候，0.3版本中message/send改成了v1.0中的SendMessage,但是使用了JSONRPC03Adapter做适配

## Next.js

### Next.js与Nuxt.js

- Next.js:基于React生态
- Nuxt.js:基于Vue生态