# https://github.com/nottelabs/notte 项目说明书

生成时间：2026-05-14 04:53:36 UTC

## 目录

- [项目介绍](#project-introduction)
- [快速入门指南](#quickstart-guide)
- [包结构分析](#package-structure)
- [核心模块实现](#core-modules)
- [Agent实现与生命周期](#agent-implementation)
- [结构化输出](#structured-output)
- [会话管理系统](#session-management)
- [动作执行系统](#action-system)
- [凭证保险库](#vault-credentials)
- [文件存储系统](#file-storage)

<a id='project-introduction'></a>

## 项目介绍

### 相关页面

相关主题：[快速入门指南](#quickstart-guide), [包结构分析](#package-structure)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/nottelabs/notte/blob/main/README.md)
- [packages/notte-core/src/notte_core/actions/actions.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/actions/actions.py)
- [packages/notte-core/src/notte_core/errors/processing.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/errors/processing.py)
- [packages/notte-sdk/src/notte_sdk/endpoints/sessions.py](https://github.com/nottelabs/notte/blob/main/packages/notte-sdk/src/notte_sdk/endpoints/sessions.py)
- [packages/notte-agent/src/notte_agent/gufo/system.md](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/gufo/system.md)
</details>

# 项目介绍

## 项目概述

Notte 是一款面向互联网原生代理系统（Internet-native Agentic Systems）的软件套件，旨在为大型语言模型（LLM）代理提供强大的浏览器自动化和网页交互能力。Notte 将互联网转化为一个结构化、可导航的空间，使每个网站都成为智能代理可以精确解读和操作的地图。

资料来源：[README.md:1]()

## 核心定位

Notte 的核心价值主张在于创建一个可编程的抽象层，覆盖在真实网页之上。通过该技术栈，AI 代理能够：

- 精确解读网页内容结构
- 执行复杂的浏览器交互操作
- 实现端到端的自动化工作流

资料来源：[README.md:1]()

## 技术架构

### 包结构

Notte 采用多包架构设计，包含以下核心组件：

| 包名 | 描述 |
|------|------|
| `notte-core` | 核心功能模块，包含动作定义、错误处理等基础组件 |
| `notte-llm` | LLM 集成模块，提供提示词模板和文档分析能力 |
| `notte-sdk` | Python SDK 模块，提供会话管理和 API 交互接口 |
| `notte-agent` | 代理执行模块，处理代理决策和浏览器控制逻辑 |

资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1]()
资料来源：[packages/notte-core/src/notte_core/errors/processing.py:1]()

### 架构分层图

```mermaid
graph TD
    A[用户/外部系统] --> B[notte-sdk]
    B --> C[notte-agent]
    C --> D[notte-llm]
    D --> E[notte-core]
    E --> F[浏览器/Playwright]
    F --> G[网页 DOM]
```

## 核心功能模块

### 浏览器动作系统

Notte 定义了一套完整的浏览器动作类型，支持多种交互场景：

| 动作类型 | 功能描述 |
|----------|----------|
| `goto` | 导航至指定 URL |
| `goto_new_tab` | 在新标签页中打开 URL |
| `close_tab` | 关闭当前标签页 |

```python
# 示例：导航动作
class GotoAction(BrowserAction):
    type: Literal["goto"] = "goto"
    url: str
    description: str = "Goto to a URL"
```

资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1-20]()

### 会话管理

Notte SDK 提供了灵活的会话管理能力，支持快速感知和深度感知两种模式：

```python
# 快速感知模式（默认）
obs = session.observe(perception_type='fast')

# 深度感知模式（使用 LLM）
obs = session.observe(perception_type='deep')

# 带指令的感知（自然语言过滤）
actions = session.observe(instructions="Fill the email input")
```

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:1-30]()

### 文档分类与提取

Notte LLM 模块提供了文档分析能力，支持对网页内容进行结构化处理：

| 文档类别 | 说明 |
|----------|------|
| `search-results` | 搜索结果页面 |
| `item` | 详情/物品页面 |
| `other` | 其他类型页面 |

资料来源：[packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md:1]()

### 代理决策系统

Notte Agent 模块实现了基于 LLM 的代理决策引擎，支持：

- **元素识别**：通过 ID 系统标识可交互元素（`I`=输入、`B`=按钮、`L`=链接、`F`=图形、`O`=选项、`M`=杂项）
- **动作序列**：支持表单填写、导航提取等常见操作序列
- **验证码处理**：内置 CAPTCHA 检测和解决机制

```mermaid
graph LR
    A[网页状态] --> B[元素识别]
    B --> C[动作规划]
    C --> D[执行验证]
    D -->|成功| E[下一状态]
    D -->|失败| F[错误处理]
```

资料来源：[packages/notte-agent/src/notte_agent/gufo/system.md:1-40]()

## 错误处理机制

Notte 建立了完善的错误处理体系，涵盖内部检查和运行时异常：

| 错误类型 | 触发条件 |
|----------|----------|
| `InvalidA11yTreeType` | 无效的辅助功能树类型 |
| `InvalidA11yChildrenError` | 子元素数量不满足假设条件 |
| `InvalidPlaceholderError` | 占位符未被 vault 处理 |
| `ScrapeFailedError` | 结构化数据提取失败 |

资料来源：[packages/notte-core/src/notte_core/errors/processing.py:1-40]()

## 使用方式

### 安装

Notte 通过 Python 包管理器分发，可通过标准方式安装。

### 基本工作流

```mermaid
graph TD
    A[创建会话] --> B[执行动作]
    B --> C[观察状态]
    C --> D{任务完成?}
    D -->|否| B
    D -->|是| E[返回结果]
```

```python
# 完整示例
obs = session.observe(perception_type='deep')
print(obs.space.description)
```

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:20-25]()

## 项目信息

| 属性 | 值 |
|------|------|
| 版本 | 1.4.4 |
| 许可证 | SSPL-1.0 |
| 版权 | © 2025 Notte Labs, Inc. |
| 作者 | Pinto, Andrea, Giordano, Lucas, nottelabs-team |

资料来源：[README.md:1-15]()

## 引用格式

如需在学术场合引用 Notte，请使用以下 BibTeX 格式：

```bibtex
@software{notte2025,
  author = {Pinto, Andrea and Giordano, Lucas and {nottelabs-team}},
  title = {Notte: Software suite for internet-native agentic systems},
  url = {https://github.com/nottelabs/notte},
  year = {2025},
  publisher = {GitHub},
  license = {SSPL-1.0},
  version = {1.4.4},
}
```

资料来源：[README.md:5-14]()

---

<a id='quickstart-guide'></a>

## 快速入门指南

### 相关页面

相关主题：[项目介绍](#project-introduction)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/setup.md](https://github.com/nottelabs/notte/blob/main/docs/setup.md)
- [docs/sdk_tutorial.md](https://github.com/nottelabs/notte/blob/main/docs/sdk_tutorial.md)
- [.env.example](https://github.com/nottelabs/notte/blob/main/.env.example)
</details>

# 快速入门指南

Notte 是一个面向互联网原生代理系统的软件套件，旨在为 LLM 智能体提供可靠的网页浏览和交互能力。本指南将帮助您快速上手 Notte SDK，从环境配置到实现第一个网页交互任务。

## 环境要求

在开始之前，请确保您的开发环境满足以下要求：

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Python | 3.10+ | 推荐使用 Python 3.10 或更高版本 |
| pip | 21.0+ | Python 包管理器 |
| API 密钥 | Notte 账户 | 从 [notte.cc](https://notte.cc) 获取 |

## 环境配置

### 获取 API 密钥

1. 访问 [notte.cc](https://notte.cc) 并注册账户
2. 在仪表板中生成您的 API 密钥
3. 将密钥安全存储，避免泄露

### 配置环境变量

创建 `.env` 文件，参考 `.env.example` 中的配置模板：

```bash
# Notte API 配置
NOTTE_API_KEY=your_api_key_here
NOTTE_API_BASE_URL=https://api.notte.cc  # 可选，默认为官方 API 地址
```

环境变量说明：

| 变量名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| `NOTTE_API_KEY` | 是 | - | 您的 Notte API 密钥 |
| `NOTTE_API_BASE_URL` | 否 | `https://api.notte.cc` | API 基础 URL |

资料来源：[.env.example](https://github.com/nottelabs/notte/blob/main/.env.example)

## 安装 SDK

### 使用 pip 安装

```bash
pip install notte-sdk
```

### 从源码安装

```bash
git clone https://github.com/nottelabs/notte.git
cd notte
pip install -e .
```

## 核心概念

在深入实践之前，理解以下核心概念有助于更好地使用 Notte SDK：

```mermaid
graph TD
    A[Notte Session] --> B[观察页面]
    A --> C[执行动作]
    A --> D[抓取数据]
    B --> E[获取交互元素]
    C --> F[点击/输入/提交]
    D --> G[结构化输出]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#e8f5e9
```

| 概念 | 说明 |
|------|------|
| Session | 会话对象，管理与浏览器的连接状态 |
| Observe | 观察操作，获取当前页面的交互元素 |
| Execute | 执行操作，如点击、输入、表单填写等 |
| Scrape | 抓取操作，从页面提取结构化数据 |

资料来源：[docs/sdk_tutorial.md](https://github.com/nottelabs/notte/blob/main/docs/sdk_tutorial.md)

## 基本使用流程

### 1. 初始化客户端

```python
from notte_sdk import NotteClient

client = NotteClient()
```

### 2. 创建会话

```python
session = client.sessions.create()
print(f"会话ID: {session.id}")
```

### 3. 导航到目标页面

```python
session.execute(type="goto", url="https://notte.cc")
```

### 4. 观察页面元素

```python
# 快速感知模式
obs = session.observe(perception_type="fast")

# 深度感知模式（使用 LLM 格式化）
obs = session.observe(perception_type="deep")
```

### 5. 执行动作

```python
# 点击元素
session.execute(type="click", id="B1")

# 输入文本
session.execute(type="fill", id="I1", value="search term")

# 提交表单
session.execute(type="submit", id="B2")
```

资料来源：[docs/sdk_tutorial.md](https://github.com/nottelabs/notte/blob/main/docs/sdk_tutorial.md)

## 常见任务示例

### 网页抓取

Notte 提供强大的网页抓取功能，支持结构化数据提取：

```python
from notte_sdk import NotteClient, NotteScrapeResponse

client = NotteClient()

# 基础抓取
response = client.scrape(
    url="https://notte.cc",
    scrape_links=True,
    only_main_content=True
)

# 带自定义指令的结构化抓取
from pydantic import BaseModel

class Article(BaseModel):
    title: str
    content: str
    date: str

response = client.scrape(
    url="https://example.com/blog",
    response_format=Article,
    instructions="Extract only the title, date and content of the articles"
)
```

抓取参数说明：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 要抓取的网页 URL |
| `scrape_links` | boolean | 否 | 是否抓取页面链接 |
| `only_main_content` | boolean | 否 | 是否仅提取主要内容 |
| `response_format` | BaseModel | 否 | Pydantic 模型用于结构化输出 |
| `instructions` | string | 否 | 提取数据的自定义指令 |

### 动作观察与过滤

使用自然语言指令快速定位交互元素：

```python
session.execute(type="goto", url="https://console.notte.cc")

# 使用自然语言过滤动作空间
actions = session.observe(instructions="Fill the email input")
print(actions[0].model_dump())
```

### 使用 cURL 直接调用 API

如果您偏好使用 HTTP 直接调用：

```bash
curl -X POST 'https://api.notte.cc/scrape' \
  -H 'Authorization: Bearer <NOTTE-API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://notte.cc",
    "only_main_content": false,
  }'
```

## 错误处理

### 常见错误及解决方案

| 错误类型 | 可能原因 | 解决方案 |
|----------|----------|----------|
| `AuthenticationError` | API 密钥无效或过期 | 检查并更新 `NOTTE_API_KEY` |
| `NetworkError` | 网络连接问题 | 检查网络连接和代理设置 |
| `SessionExpiredError` | 会话超时 | 重新创建会话 |
| `ActionExecutionError` | 动作执行失败 | 检查元素 ID 和页面状态 |

### 重试机制

Notte SDK 支持自动重试机制，您可以在执行动作时配置：

```python
session.execute(
    type="click",
    id="B1",
    raise_on_failure=True  # 失败时抛出异常
)
```

## 下一步

- 阅读完整的 [SDK 教程](sdk_tutorial.md) 深入了解高级功能
- 查看 [API 参考文档](api_reference.md) 了解完整的 API 接口
- 探索 [示例代码库](../examples/) 获取更多实践案例

## 相关资源

- 官方文档：[https://docs.notte.cc](https://docs.notte.cc)
- API 密钥管理：[https://console.notte.cc](https://console.notte.cc)
- 搜索演示：[https://search.notte.cc](https://search.notte.cc)

---

<a id='package-structure'></a>

## 包结构分析

### 相关页面

相关主题：[核心模块实现](#core-modules), [项目介绍](#project-introduction)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-core/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-core/pyproject.toml)
- [packages/notte-browser/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/pyproject.toml)
- [packages/notte-agent/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/pyproject.toml)
- [packages/notte-sdk/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-sdk/pyproject.toml)
- [packages/notte-llm/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/pyproject.toml)
- [packages/notte-mcp/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-mcp/pyproject.toml)
</details>

# 包结构分析

## 概述

Notte 是一个面向互联网原生代理系统（Internet-native Agentic Systems）的软件套件，采用模块化架构设计。整个项目由多个独立的功能包组成，通过清晰的依赖关系组织，形成一套完整的浏览器自动化与LLM交互解决方案。

项目根目录下包含 `packages/` 子目录，其中包含六个核心包：

| 包名 | 版本 | 主要功能 |
|------|------|----------|
| notte-core | 0.1.0+ | 核心数据结构和错误处理 |
| notte-browser | 0.1.0+ | 浏览器控制与页面交互 |
| notte-agent | 0.1.0+ | Agent执行引擎 |
| notte-sdk | 0.1.0+ | Python SDK客户端 |
| notte-llm | 0.1.0+ | LLM提示词和响应处理 |
| notte-mcp | 0.1.0+ | MCP协议服务器集成 |

## 架构层次

```mermaid
graph TD
    subgraph "notte-llm"
        LLM_Prompts["提示词模板"]
        LLM_Output["输出解析"]
    end
    
    subgraph "notte-core"
        Core_Actions["动作定义"]
        Core_Observation["观察数据模型"]
        Core_Errors["错误处理"]
    end
    
    subgraph "notte-browser"
        Browser_Control["浏览器控制"]
        Page_Scraping["页面抓取"]
    end
    
    subgraph "notte-agent"
        Agent_Executor["Agent执行器"]
        Agent_Gufo["Gufo系统"]
    end
    
    subgraph "notte-sdk"
        SDK_Client["客户端封装"]
        Session_Management["会话管理"]
    end
    
    subgraph "notte-mcp"
        MCP_Server["MCP服务器"]
        MCP_Tools["工具定义"]
    end
    
    LLM_Prompts --> Core_Actions
    Core_Actions --> Browser_Control
    Agent_Executor --> Core_Actions
    Agent_Executor --> LLM_Prompts
    SDK_Client --> Session_Management
    SDK_Client --> Agent_Executor
    MCP_Server --> SDK_Client
    MCP_Tools --> MCP_Server
```

## 各包详细分析

### notte-core

**功能定位**：基础层，提供整个项目的基础数据类型、动作定义、观察结果模型和错误处理机制。

**源码结构**：

```
notte-core/src/notte_core/
├── actions/
│   └── actions.py          # 动作类型定义（goto、click、fill等）
├── observation/
│   └── data models         # 页面观察数据结构
├── errors/
│   └── processing.py       # 错误类定义
└── pruning.py              # 树剪枝算法
```

**核心模块**：

| 模块 | 文件 | 说明 |
|------|------|------|
| actions | actions.py | 定义scrape、goto、click、fill等动作类型 |
| errors | processing.py | NotteBaseError、InvalidInternalCheckError等 |
| observation | 数据模型 | 页面元素的结构化表示 |

**关键类型定义**（来源：[packages/notte-core/src/notte_core/actions/actions.py]()）：

- `ScrapeAction`：页面数据抓取，支持指令过滤、选择器范围限定
- `GotoAction`：页面导航
- `ClickAction`：元素点击
- `FillAction`：表单填充

### notte-browser

**功能定位**：浏览器控制层，基于Playwright实现浏览器自动化操作。

**依赖关系**：

```toml
[project.dependencies]
playwright = ">=1.41.0"
```

**核心功能**：

| 功能 | 说明 |
|------|------|
| 页面导航 | 加载指定URL |
| 元素交互 | 点击、填表、悬停等 |
| 内容抓取 | 提取页面文本、图片、链接 |
| 截图 | 页面可视化反馈 |

### notte-agent

**功能定位**：智能代理层，实现LLM驱动的自动化决策和执行。

**源码结构**：

```
notte-agent/src/notte_agent/
├── gufo/
│   └── system.md           # Gufo系统提示词
└── 执行器                  # Agent核心逻辑
```

**核心能力**：

| 能力 | 说明 |
|------|------|
| 动作规划 | 分析页面状态生成动作序列 |
| 状态追踪 | 维护会话上下文 |
| CAPTCHA处理 | 自动识别和处理验证码 |
| 错误恢复 | 动作执行失败后的重试机制 |

**Agent执行流程**（来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py]()）：

```python
# 会话创建
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    obs = session.observe(perception_type='deep')
    # Agent决策循环...
```

### notte-sdk

**功能定位**：Python客户端SDK，封装所有API调用和会话管理。

**核心组件**：

| 组件 | 文件/类 | 说明 |
|------|---------|------|
| NotteClient | client.py | 主客户端类 |
| Session | sessions.py | 会话上下文管理器 |
| observe | sessions.py | 页面观察方法 |
| execute | sessions.py | 动作执行方法 |

**会话管理**（来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py]()）：

```python
class Session:
    """会话上下文管理器"""
    
    def __init__(self, cookie_file=None):
        self._cookie_file = cookie_file
    
    def __enter__(self):
        self.start()
        return self
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        self.stop()
    
    def observe(self, perception_type='fast', instructions=None):
        """观察页面可用动作"""
        
    def execute(self, type, **kwargs):
        """执行动作"""
```

**观察类型**：

| 类型 | 说明 | 适用场景 |
|------|------|----------|
| `fast` | 快速感知 | 简单页面、高速查询 |
| `deep` | 深度感知 | 复杂页面、需要LLM格式化 |

### notte-llm

**功能定位**：LLM交互层，处理提示词模板和响应解析。

**源码结构**：

```
notte-llm/src/notte_llm/prompts/
├── action-listing/         # 动作列表生成
├── data-extraction/        # 数据提取
├── document-category/      # 文档分类
├── extract-without-json-schema/  # 无schema提取
└── debug-failing-action-exec/    # 调试失败动作
```

**提示词模板**：

| 模板类型 | 用户文件 | 说明 |
|----------|----------|------|
| 动作列表 | user.md | 生成可执行动作序列 |
| 数据提取 | user.md | 结构化数据抽取 |
| 文档分类 | user.md | 页面分类（search-results、item、other） |
| 失败调试 | user.md | 动作执行失败分析 |

**文档分类类别**（来源：[packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md]()）：

| 类别 | 说明 | 示例 |
|------|------|------|
| `search-results` | 搜索结果页面 | Google Flights搜索结果 |
| `item` | 详情项页面 | 食谱详情页、商品页 |
| `other` | 其他类型 | 首页、导航页 |

### notte-mcp

**功能定位**：Model Context Protocol服务器集成，提供标准化工具接口。

**工具列表**（来源：[packages/notte-mcp/README.md]()）：

| 工具名 | 功能 |
|--------|------|
| `notte_start_session` | 启动新的云浏览器会话 |
| `notte_list_sessions` | 列出所有活动会话 |
| `notte_stop_session` | 停止当前会话 |
| `notte_observe` | 观察页面元素和可用动作 |
| `notte_screenshot` | 页面截图 |
| `notte_scrape` | 结构化数据提取 |
| `notte_step` | 执行页面动作 |
| `notte_operator` | 运行Notte Agent完成任务 |

**使用方式**：

```bash
pip install notte-mcp
export NOTTE_API_KEY="your-api-key"
python -m notte_mcp.server
```

## 依赖关系

```mermaid
graph LR
    SDK["notte-sdk"] --> Agent["notte-agent"]
    SDK --> Browser["notte-browser"]
    Agent --> LLM["notte-llm"]
    Agent --> Core["notte-core"]
    Browser --> Core
    MCP["notte-mcp"] --> SDK
```

**依赖矩阵**：

| 依赖方 \ 被依赖方 | notte-core | notte-browser | notte-agent | notte-llm | notte-sdk |
|------------------|------------|---------------|-------------|-----------|-----------|
| notte-sdk | ✓ | - | ✓ | - | - |
| notte-agent | ✓ | - | - | ✓ | - |
| notte-browser | ✓ | - | - | - | - |
| notte-mcp | - | - | - | - | ✓ |

## 入口点设计

### SDK入口

```python
from notte_sdk import NotteClient

client = NotteClient()
```

### MCP服务器入口

```bash
python -m notte_mcp.server
```

### CLI入口

项目提供命令行接口进行快速操作：

```bash
notte <command> [options]
```

## 错误处理体系

Notte采用分层错误处理机制（来源：[packages/notte-core/src/notte_core/errors/processing.py]()）：

| 错误类 | 说明 | 使用场景 |
|--------|------|----------|
| `NotteBaseError` | 基类异常 | 所有自定义异常的父类 |
| `InvalidInternalCheckError` | 内部检查失败 | 代码假设验证失败 |
| `InvalidA11yTreeType` | 无障碍树类型错误 | 未知a11y树类型 |
| `InvalidPlaceholderError` | 占位符错误 | Vault凭据获取失败 |
| `ScrapeFailedError` | 抓取失败 | 数据提取操作异常 |

## 许可证

整个项目采用 **Server Side Public License v1.0 (SSPL-1.0)** 许可证发布。

## 引用信息

如需在学术场合引用本项目，请使用以下BibTeX格式：

```bibtex
@software{notte2025,
  author = {Pinto, Andrea and Giordano, Lucas and {nottelabs-team}},
  title = {Notte: Software suite for internet-native agentic systems},
  url = {https://github.com/nottelabs/notte},
  year = {2025},
  publisher = {GitHub},
  license = {SSPL-1.0},
  version = {1.4.4},
}

---

<a id='core-modules'></a>

## 核心模块实现

### 相关页面

相关主题：[包结构分析](#package-structure), [动作执行系统](#action-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-core/src/notte_core/actions/actions.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/actions/actions.py)
- [packages/notte-core/src/notte_core/browser/observation.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/browser/observation.py)
- [packages/notte-core/src/notte_core/browser/snapshot.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/browser/snapshot.py)
- [packages/notte-core/src/notte_core/browser/dom_tree.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/browser/dom_tree.py)
- [packages/notte-core/src/notte_core/credentials/base.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/credentials/base.py)
- [packages/notte-core/src/notte_core/ast.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/ast.py)
</details>

# 核心模块实现

## 1. 模块概述

Notte 项目的核心模块实现涵盖了浏览器自动化代理系统的关键组件，包括动作执行系统、页面观察机制、DOM 树处理、快照管理和凭证安全系统。这些模块共同构成了一个完整的网页自动化框架，使 AI 代理能够精确地与网页元素进行交互。

核心模块的架构设计遵循分层职责原则，将浏览器操作、页面解析、状态管理和安全控制分离到不同的子模块中，每个模块专注于特定的功能域，通过标准化的接口进行通信和数据交换。

## 2. 动作执行系统

### 2.1 动作类型体系

动作执行系统是 Notte 自动化框架的核心，负责定义和管理所有可执行的浏览器操作。系统采用类继承结构，通过基类 `BrowserAction` 定义通用接口，具体动作类实现各自的业务逻辑。

| 动作类型 | 说明 | 参数 |
|---------|------|------|
| `GotoAction` | 导航到指定 URL | url: str |
| `GotoNewTabAction` | 在新标签页中打开 URL | url: str |
| `CloseTabAction` | 关闭当前标签页 | 无 |
| `ClickAction` | 点击页面元素 | id: str |
| `FormFillAction` | 填写表单字段 | 表单字段字典 |

基类 `BrowserAction` 定义了动作执行的通用接口，包括执行消息生成、参数规范和示例数据提供。每个具体动作类都实现了这些抽象方法，确保动作执行的标准化和可预测性。

### 2.2 动作执行流程

动作执行采用统一的调用模式，通过 `execute()` 方法触发。执行流程首先验证动作参数的有效性，然后调用底层的 Playwright 或类似浏览器自动化引擎执行实际操作，最后返回执行结果。

```mermaid
graph TD
    A[创建动作实例] --> B[验证参数]
    B --> C{参数有效?}
    C -->|是| D[执行动作]
    C -->|否| E[抛出验证错误]
    D --> F{执行成功?}
    F -->|是| G[返回 ExecutionResult]
    F -->|否| H[记录错误信息]
    G --> I[更新会话状态]
    H --> I
```

### 2.3 动作参数定义

每个动作类通过 `param` 属性提供参数规范，包括参数名称、数据类型和约束条件。这种设计使动作系统具备自描述能力，便于 LLM 代理理解和使用。

```python
@property
@override
def param(self) -> ActionParameter | None:
    return ActionParameter(name="url", type="str")
```

参数规范采用强类型定义，支持字符串、整数、布尔值和复杂对象类型。系统自动进行类型检查和转换，减少运行时错误的发生。

## 3. 页面观察机制

### 3.1 观察类型

页面观察机制负责分析当前页面状态并生成可交互元素列表。系统支持多种观察深度，以适应不同场景的性能和精度需求。

| 观察类型 | 说明 | 适用场景 |
|---------|------|---------|
| `fast` | 快速感知模式 | 简单页面感知、查询优化 |
| `deep` | 深度感知模式 | 复杂页面分析、LLM 动作空间生成 |

快速感知模式使用简化的页面解析逻辑，直接从浏览器的可访问性树中提取元素信息，适用于需要快速响应的场景。深度感知模式则调用 LLM 对页面进行更深入的分析，生成更结构化的交互空间表示。

### 3.2 观察响应结构

观察结果通过 `ObserveResponse` 类型封装，包含当前页面 URL、可交互元素列表和空间描述信息。这种结构化输出便于代理理解页面状态并规划后续动作。

```mermaid
graph LR
    A[页面 HTML] --> B[DOM 树解析]
    B --> C[可访问性树生成]
    C --> D{观察类型}
    D -->|fast| E[快速元素提取]
    D -->|deep| F[LLM 结构化分析]
    E --> G[ObserveResponse]
    F --> G
```

### 3.3 指令过滤机制

观察系统支持通过自然语言指令过滤可交互元素。当提供 `instructions` 参数时，系统会解析指令语义，仅返回符合条件的目标元素，显著减少动作空间大小，提高代理决策效率。

```python
actions = session.observe(instructions="Fill the email input")
print(actions[0].model_dump())
```

这种设计使开发者能够用自然语言描述交互意图，系统自动完成元素筛选和动作空间构建，降低了自动化脚本的编写难度。

## 4. DOM 树处理

### 4.1 树结构设计

DOM 树模块负责将原始 HTML 文档解析为可编程访问的树形数据结构。树节点包含元素类型、属性、内容和层级关系，支持高效的遍历和查询操作。

```mermaid
graph TD
    A[HTML 文档] --> B[解析器]
    B --> C[根节点]
    C --> D[head 节点]
    C --> E[body 节点]
    E --> F[交互元素]
    E --> G[文本节点]
    D --> H[元数据节点]
```

每个树节点关联唯一的标识符，用于在观察响应中引用具体元素。节点同时记录可访问性属性，如角色、名称和状态，这些属性决定了元素的交互方式。

### 4.2 可访问性树

Notte 使用可访问性树（Accessibility Tree）作为页面元素的主要表示形式，相比原始 DOM 树提供了更丰富的语义信息。可访问性树去除了装饰性元素，保留功能性内容，使代理能够更准确地理解页面结构。

| 属性 | 说明 |
|------|------|
| `role` | 元素语义角色（button, link, input 等） |
| `name` | 元素的可见名称或标签 |
| `state` | 元素当前状态（checked, disabled 等） |
| `value` | 输入元素的当前值 |

### 4.3 节点遍历与查询

DOM 树模块提供多种遍历和查询方法，支持按标签名、类名、ID 或 XPath 表达式定位节点。查询结果可进一步用于动作生成或内容提取。

## 5. 快照管理

### 5.1 快照概念

快照（Snapshot）是 Notte 系统记录页面状态的机制，每次页面变化后系统自动生成新的快照。快照包含完整的页面 DOM 结构、可访问性树和元数据，支持历史回溯和状态对比。

快照管理器维护快照的历史记录，通过版本号或时间戳标识不同状态的快照。代理可以查询历史快照以了解页面变化过程，或在执行操作前保存当前状态以便回滚。

### 5.2 快照数据结构

```python
class Snapshot:
    id: str
    url: str
    dom_tree: DOMTree
    accessibility_tree: A11yTree
    timestamp: datetime
    metadata: dict
```

快照数据存储为只读对象，确保历史状态的完整性和一致性。系统支持快照的序列化和反序列化，便于分布式环境下的状态共享。

### 5.3 快照与观察的关系

观察操作基于当前快照执行，每次观察都会创建新的快照记录。观察结果中的元素标识符与快照中的节点一一对应，保证动作执行的精确性。

```mermaid
graph LR
    A[执行动作] --> B[页面更新]
    B --> C[生成新快照]
    C --> D[新快照 ID]
    D --> E[观察结果引用新元素]
```

## 6. 凭证管理系统

### 6.1 凭证架构

凭证管理系统（Vault）负责安全存储和管理敏感信息，如登录凭据、API 密钥和认证令牌。系统采用分层架构，将凭证存储与业务逻辑分离，支持多种后端存储实现。

```mermaid
graph TD
    A[代理请求凭证] --> B[Vault 接口]
    B --> C{凭证类型}
    C -->|API 密钥| D[KeyVault]
    C -->|用户名密码| E[CredentialVault]
    C -->|OAuth 令牌| F[TokenVault]
    D --> G[安全存储]
    E --> G
    F --> G
```

### 6.2 凭证基类设计

```python
class NotteBaseError(Exception):
    def __init__(
        self,
        agent_message: str,
        user_message: str,
        dev_message: str,
    ) -> None:
        self.agent_message = agent_message
        self.user_message = user_message
        self.dev_message = dev_message
```

凭证系统定义统一的异常类型，包含面向代理、用户和开发者的不同错误消息，便于问题的诊断和修复。当凭证操作失败时，系统根据上下文选择合适的错误消息返回。

### 6.3 占位符机制

代理通过占位符（Placeholder）引用凭证，系统在动作执行时自动替换占位符为实际凭证值。这种设计避免敏感信息硬编码在动作参数中，提高系统的安全性。

| 占位符类型 | 说明 |
|-----------|------|
| `{vault:api_key:service}` | API 密钥占位符 |
| `{vault:credential:site}` | 网站登录凭据占位符 |
| `{vault:token:oauth}` | OAuth 令牌占位符 |

## 7. AST 抽象语法树

AST 模块提供网页内容的结构化表示能力，将无结构的 HTML/CSS/JavaScript 转换为可编程访问的语法树。该模块是高级自动化能力的基础，支持复杂页面结构的理解和操作。

### 7.1 AST 与 DOM 的关系

AST 与 DOM 树既有联系又有区别。DOM 树侧重于文档结构表示，AST 则更关注代码语义的表达。对于 JavaScript 代码，AST 能够解析变量声明、函数调用和控制流结构，为代码级别的自动化操作提供可能。

| 特性 | DOM 树 | AST |
|------|--------|-----|
| 关注点 | 文档结构 | 代码语义 |
| 适用范围 | HTML | HTML/CSS/JS |
| 遍历方式 | 父子节点 | 语句/表达式 |
| 用途 | 页面交互 | 代码分析 |

### 7.2 节点类型系统

AST 定义了丰富的节点类型，覆盖 JavaScript 语言的各种语法结构。常见节点类型包括：

- **声明节点**：变量声明、函数声明、类声明
- **表达式节点**：二元表达式、函数调用、成员访问
- **控制流节点**：条件语句、循环语句、异常处理
- **结构节点**：对象字面量、数组字面量

节点类型系统支持 Visitor 模式遍历，代理可以实现自定义的节点处理器来执行特定的代码分析或转换任务。

## 8. 错误处理机制

### 8.1 错误分类体系

Notte 定义了完善的错误分类体系，根据错误来源和性质分为不同类别：

| 错误类型 | 说明 | 典型场景 |
|---------|------|---------|
| `InvalidInternalCheckError` | 内部检查失败 | 类型验证、假设检查 |
| `InvalidA11yTreeType` | 无效的可访问性树类型 | 类型参数错误 |
| `InvalidPlaceholderError` | 未处理的占位符 | 凭证引用错误 |
| `ScrapeFailedError` | 数据抓取失败 | 页面解析异常 |

### 8.2 错误消息设计

每个错误类型包含面向不同角色的消息：

- **开发消息（dev_message）**：详细的调试信息和修复建议
- **代理消息（agent_message）**：代理可理解的错误描述和替代建议
- **用户消息（user_message）**：面向终端用户的友好提示

这种多层次的消息设计确保错误信息在开发、调试和生产环境中都能发挥作用。

## 9. 模块间协作

### 9.1 会话生命周期

会话（Session）是 Notte 系统的核心概念，贯穿所有模块的协作过程。会话管理器的实现整合了动作执行、页面观察和快照管理功能：

```python
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    obs = session.observe()
    markdown = session.scrape()
```

会话提供上下文管理器支持，自动处理资源清理和状态同步。当会话结束时，系统自动保存 Cookie 状态并释放浏览器资源。

### 9.2 数据流总览

```mermaid
graph TD
    A[用户请求] --> B[会话管理器]
    B --> C[动作系统]
    C --> D[浏览器引擎]
    D --> E[页面快照]
    E --> F[DOM 树]
    F --> G[可访问性树]
    G --> H[观察服务]
    H --> I[代理决策]
    I --> C
    E --> J[凭证系统]
    J --> C
```

数据流展示了从用户请求到代理决策的完整链路。各模块通过标准化的数据结构和接口进行交互，保证系统的可扩展性和可维护性。

### 9.3 状态同步机制

会话维护当前的页面快照引用，当页面发生变化时自动更新。观察操作返回的是基于最新快照的元素列表，动作执行后触发新的快照生成，形成闭环的状态同步机制。

## 10. 总结

核心模块实现构成了 Notte 自动化框架的技术基础，通过动作系统、页面观察、DOM 处理、快照管理和凭证安全五大支柱，为 AI 代理提供完整的网页交互能力。这些模块相互协作，形成了一套从页面解析到动作执行的完整工作流，支持复杂场景下的自动化任务。

---

<a id='agent-implementation'></a>

## Agent实现与生命周期

### 相关页面

相关主题：[结构化输出](#structured-output)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-agent/src/notte_agent/agent.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/agent.py)
- [packages/notte-agent/src/notte_agent/agent_fallback.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/agent_fallback.py)
- [packages/notte-agent/src/notte_agent/workflow.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/workflow.py)
- [packages/notte-agent/src/notte_agent/common/conversation.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/common/conversation.py)
- [packages/notte-agent/src/notte_agent/falco/agent.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/falco/agent.py)
- [packages/notte-agent/src/notte_agent/gufo/agent.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/gufo/agent.py)
</details>

# Agent实现与生命周期

## 概述

Notte Agent 是一个精确的浏览器自动化代理系统，通过结构化命令与网站进行交互。该系统能够分析网页元素和结构，规划动作序列，并以JSON格式响应动作执行结果和状态评估。Agent架构支持多种底层浏览器自动化引擎（包括Falco和Gufo），并通过统一的接口提供网页浏览、内容提取、表单填写等核心功能。

资料来源：[packages/notte-agent/src/notte_agent/falco/system.md](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/falco/system.md)

## 架构设计

### 整体架构

Notte Agent采用分层架构设计，核心组件包括：

| 组件 | 职责 | 源码位置 |
|------|------|----------|
| Agent基类 | 定义通用接口和生命周期管理 | `agent.py` |
| Falco Agent | 基于Falco引擎的浏览器代理实现 | `falco/agent.py` |
| Gufo Agent | 基于Gufo引擎的浏览器代理实现 | `gufo/agent.py` |
| ActionRegistry | 动作注册与工具管理 | `falco/prompt.py` |
| Workflow | 多步骤工作流编排 | `workflow.py` |
| Conversation | 对话历史管理 | `common/conversation.py` |

资料来源：[packages/notte-agent/src/notte_agent/falco/prompt.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/falco/prompt.py)

### 引擎抽象层

系统通过抽象层支持多种浏览器自动化引擎：

```mermaid
graph TD
    A[Agent基类] --> B[Falco Agent]
    A --> C[Gufo Agent]
    B --> D[Falco引擎]
    C --> E[Gufo引擎]
    D --> F[Playwright/CDP]
    E --> G[浏览器实例]
```

Falco和Gufo作为两种独立的Agent实现，共同继承自基础Agent接口，提供一致的外部行为但使用不同的底层浏览器控制机制。

资料来源：[packages/notte-agent/src/notte_agent/agent.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/agent.py)

## 元素标识系统

### ID编码规范

Agent使用标准化的元素标识系统，每个可交互元素的ID遵循特定编码规则：

```mermaid
graph LR
    A[ID格式] --> B[角色前缀]
    A --> C[索引号]
    A --> D[分隔符]
    
    B --> E[I: 输入字段]
    B --> F[B: 按钮]
    B --> G[L: 链接]
    B --> H[F: 图片/图表]
    B --> I[O: 选择选项]
    B --> J[M: 杂项元素]
```

### 角色前缀对照表

| 前缀 | 角色类型 | 示例元素 |
|------|----------|----------|
| `I` | Input | textbox, select, checkbox等输入控件 |
| `B` | Button | 按钮元素 |
| `L` | Link | 超链接 |
| `F` | Figure | 图片和图表元素 |
| `O` | Option | 下拉选择选项 |
| `M` | Miscellaneous | 模态框、对话框等杂项元素 |

ID的完整格式为`<角色前缀><索引号>`，例如`B1`表示第一个按钮，`I2`表示第二个输入字段。

资料来源：[packages/notte-agent/src/notte_agent/falco/system.md](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/falco/system.md)

## 动作系统

### 动作类型

Agent支持多种类型的浏览器自动化动作：

| 动作类型 | 描述 | 适用场景 |
|----------|------|----------|
| ClickAction | 点击指定元素 | 按钮点击、链接导航 |
| FormFillAction | 填写表单字段 | 用户登录、信息录入 |
| CaptchaSolveAction | 解决验证码 | 自动化验证 |
| ScrapeAction | 提取页面内容 | 数据采集 |
| NavigationAction | 页面导航 | URL跳转、前进后退 |

### 表单填写动作格式

```json
{
  "type": "form_fill",
  "value": {
    "address1": "<地址>",
    "city": "<城市>",
    "state": "<州/省份>"
  }
}
```

### CAPTCHA处理规则

Agent对验证码处理有严格的规范：

- **禁止行为**：直接点击验证码元素（按钮、复选框、图片等），或对验证码元素执行"click"、"type"等动作
- **正确处理**：检测到验证码（reCAPTCHA、hCaptcha、图像验证等）时，必须使用`CaptchaSolveAction`并指定正确的验证码类型
- **支持类型**：包括"我不是机器人"复选框、图像选择网格、文本验证挑战等

资料来源：[packages/notte-agent/src/notte_agent/falco/system.md](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/falco/system.md)

## Agent生命周期

### 创建与启动

使用NotteClient创建Agent实例：

```python
from notte_sdk import NotteClient

notte = NotteClient()

with notte.Session(open_viewer=True) as session:
    agent = notte.Agent(session=session)
    agent.start(
        task="Summarize the content of the page",
        url="https://www.google.com"
    )
```

### 状态管理

Agent具有完整的状态管理机制：

| 状态 | 描述 | 获取方法 |
|------|------|----------|
| 运行中 | Agent正在执行任务 | `agent.status()` |
| 已停止 | Agent已被手动停止 | `agent.stop()` |
| 已完成 | 任务执行完毕 | 状态检查 |
| 异常 | 执行过程中出错 | 错误处理 |

### 列表与停止操作

```python
# 列出所有活跃的Agent
agents = notte.agents.list()

# 停止指定的Agent
agent.stop()

# 获取Agent状态
status = agent.status()
```

资料来源：[packages/notte-sdk/README.md](https://github.com/nottelabs/notte/blob/main/packages/notte-sdk/README.md)

## 工作流编排

### Workflow组件

Workflow用于编排复杂的多步骤自动化任务，支持：

- 步骤序列定义
- 条件分支处理
- 错误恢复机制
- 结果状态传递

```mermaid
graph TD
    A[开始] --> B[步骤1: 页面导航]
    B --> C[步骤2: 元素观察]
    C --> D{条件判断}
    D -->|成功| E[步骤3: 表单填写]
    D -->|失败| F[备用方案]
    E --> G[步骤4: 内容提取]
    F --> G
    G --> H[完成]
```

### Fallback机制

Agent支持降级（Fallback）机制，当主要实现无法完成任务时自动切换到备用方案：

```python
# agent_fallback.py 提供了降级策略定义
```

资料来源：[packages/notte-agent/src/notte_agent/workflow.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/workflow.py)

## 对话管理

### Conversation组件

Conversation模块管理Agent与用户之间的交互历史：

```python
class Conversation:
    def __init__(self):
        # 初始化对话历史记录
        pass
    
    def add_message(self, role: str, content: str):
        # 添加消息到历史
        pass
    
    def get_history(self):
        # 获取完整对话历史
        pass
```

对话历史对于维护Agent状态上下文、支持多轮交互任务至关重要。

资料来源：[packages/notte-agent/src/notte_agent/common/conversation.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/common/conversation.py)

## 输入结构规范

### 页面信息格式

Agent接收的页面信息包含以下核心字段：

| 字段 | 描述 | 必需 |
|------|------|------|
| Current URL | 当前页面地址 | 是 |
| Available Tabs | 打开的浏览器标签页列表 | 是 |
| Interactive Elements | 可交互元素列表 | 是 |

### 元素列表格式

```markdown
# 主导航菜单
* `B1`: 提交表单按钮
* `I1`: 用户名输入框
* `I2`: 密码输入框

# 内容区域
* `L1`: 文章链接
* `F1`: 特色图片
```

## 响应格式规范

### JSON响应结构

Agent必须始终以有效的JSON格式响应：

```json
{
  "action": {
    "type": "click",
    "id": "B1"
  },
  "reasoning": "点击提交按钮以完成表单提交",
  "state_assessment": "表单已填写完毕，可以提交"
}
```

### 动作执行结果

每个动作执行后返回的结果包含：

| 字段 | 类型 | 描述 |
|------|------|------|
| success | boolean | 动作是否成功执行 |
| error | string | 错误信息（如有） |
| page_state | object | 执行后页面状态 |
| captured_data | object | 提取的数据（如适用） |

## 最佳实践

### 元素ID稳定性

> **重要提示**：ID会在每个步骤发生变化，不要假设历史记录中的ID仍然存在或对应相同的元素。每次观察页面时都应重新获取当前的元素ID。

### 动作序列规划

1. 观察页面结构，获取可用元素
2. 分析任务需求，规划动作序列
3. 按顺序执行动作，每次观察页面变化
4. 验证动作结果，必要时调整后续动作

### 错误处理

Agent内置了完善的错误处理机制：

- **InvalidInternalCheckError**：内部检查失败
- **InvalidA11yTreeType**：无障碍树类型错误
- **InvalidPlaceholderError**：占位符处理错误
- **ScrapeFailedError**：内容提取失败

资料来源：[packages/notte-core/src/notte_core/errors/processing.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/errors/processing.py)

---

<a id='structured-output'></a>

## 结构化输出

### 相关页面

相关主题：[Agent实现与生命周期](#agent-implementation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-core/src/notte_core/actions/actions.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/actions/actions.py)
- [packages/notte-llm/src/notte_llm/engine.py](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/src/notte_llm/engine.py)
- [packages/notte-llm/src/notte_llm/prompts/extract-without-json-schema/system.md](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/src/notte_llm/prompts/extract-without-json-schema/system.md)
- [packages/notte-llm/src/notte_llm/prompts/data-extraction/user.md](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/src/notte_llm/prompts/data-extraction/user.md)
- [packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md)
- [README.md](https://github.com/nottelabs/notte/blob/main/README.md)
</details>

# 结构化输出

## 概述

结构化输出是 Notte 框架中用于将网页内容转换为机器可读格式的核心能力。该功能允许用户通过自然语言指令或 JSON Schema 定义，从非结构化的网页文档中提取结构化数据，并将其用于后续的 AI Agent 工作流中。

Notte 的结构化输出系统包含以下几个核心组成部分：

| 组件 | 职责 |
|------|------|
| ScrapeAction | 执行抓取的核心动作，支持多种输出格式配置 |
| LLM 解析引擎 | 负责解析 LLM 返回的文本并提取结构化数据 |
| Prompt 模板系统 | 提供文档分析和数据提取的指令模板 |
| Schema 验证 | 支持 JSON Schema 和 Pydantic 模型验证 |

资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1-100]()

## 工作原理

### 流程架构

```mermaid
graph TD
    A[用户发起请求] --> B[配置输出格式]
    B --> C{输出类型}
    C -->|JSON Schema| D[使用 extract-json-schema]
    C -->|自然语言| E[使用 extract-without-json-schema]
    C -->|分类| F[使用 document-category]
    D --> G[调用 LLM]
    E --> G
    F --> G
    G --> H[LLM 返回 Markdown/JSON]
    H --> I[解析引擎提取数据]
    I --> J{格式验证}
    J -->|通过| K[返回结构化数据]
    J -->|失败| L[抛出 LLMParsingError]
```

### 核心机制

Notte 的结构化输出依赖于 LLM 解析引擎的标签解析能力。引擎通过识别特定的 XML 风格标签来提取内容：

```python
# packages/notte-llm/src/notte_llm/engine.py
class SomeParser:
    def parse(self, text: str) -> str:
        # 支持外层标签解析
        if self.outer_tag:
            pattern = f"<{self.outer_tag}>(.*?)</{self.outer_tag}>"
            match = re.search(pattern, content, re.DOTALL)
            
        # 支持内层代码块解析
        if self.inner_tag:
            pattern = f"```{self.inner_tag}(.*?)```"
            match = re.search(pattern, content, re.DOTALL)
```

引擎支持两层解析：
1. **外层标签解析**：提取 `<document-analysis>` 等 XML 标签内的内容
2. **内层代码块解析**：从 markdown 代码块中提取具体数据

资料来源：[packages/notte-llm/src/notte_llm/engine.py:1-50]()

## 输出格式配置

### 使用 JSON Schema

通过 `response_format` 参数指定 JSON Schema 定义输出结构：

```python
from notte_sdk import NotteClient

client = NotteClient()
response = client.scrape(
    url="https://example.com/blog",
    response_format={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "content": {"type": "string"},
            "date": {"type": "string"}
        }
    }
)
```

### 使用 Pydantic 模型

通过 Pydantic BaseModel 定义数据结构，实现类型安全的结构化输出：

```python
from pydantic import BaseModel
from notte_sdk import NotteClient

class Article(BaseModel):
    title: str
    content: str
    date: str

client = NotteClient()
response = client.scrape(
    url="https://example.com/blog",
    response_format=Article,
    instructions="Extract only the title, date and content of the articles"
)
```

资料来源：[README.md:1-100]()

## ScrapeAction 参数详解

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `instructions` | str \| None | None | 自然语言提取指令 |
| `response_format` | dict \| BaseModel | None | JSON Schema 或 Pydantic 模型 |
| `only_main_content` | bool | True | 是否仅提取主体内容 |
| `selector` | str \| None | None | Playwright 选择器作用域 |
| `only_images` | bool | False | 是否仅提取图片 |
| `scrape_links` | bool | True | 是否提取链接 |
| `scrape_images` | bool | False | 是否提取图片 URL |

### 主要内容提取

当 `only_main_content=True` 时，系统会自动排除导航栏、页脚等非核心内容：

```python
session.execute(
    type="scrape",
    only_main_content=True  # 排除导航栏和页脚
)
```

### 选择器作用域

使用 Playwright 选择器将提取范围限定在特定 DOM 元素内：

```python
session.execute(
    type="scrape",
    selector="#main-content"  # 仅提取 main-content 内的内容
)
```

资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1-100]()

## Prompt 模板系统

### 数据提取模板

数据提取模板定义了从网页文档中提取结构化信息的指导原则：

```
# 数据提取输出规范

## <document-analysis> 部分
- 逻辑分解网页文档为有意义的章节
- 描述每个部分的内容，聚焦文本元素
- 为重复或结构化数据包含子章节

## <data-extraction> 部分
- 使用 Markdown 标题、表格、列表格式化数据
- 重复数据使用 Markdown 表格展示
- 所有原始字段必须包含在表格中
```

资料来源：[packages/notte-llm/src/notte_llm/prompts/data-extraction/user.md:1-50]()

### 文档分类模板

Notte 支持自动识别网页类型，可分类为：

| 分类 | 说明 | 示例 |
|------|------|------|
| `search-results` | 搜索结果页面 | Google 航班搜索 |
| `item` | 单项详情页面 | 商品详情页、菜谱页 |
| `other` | 其他类型 | 首页、导航页 |

```xml
<document-category>
[文档分类理由的详细分析，包括引用和论证...]
<document-category-answer>search-results</document-category-answer>
</document-category>
```

资料来源：[packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md:1-50]()

## 使用示例

### 示例：Nike 产品抓取

完整的结构化输出工作流示例：

```python
from notte_sdk import NotteClient
from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: str
    sizes: list[str]
    colors: list[str]

client = NotteClient()
with client.Session() as session:
    session.execute(type="goto", url="https://www.nike.com")
    
    response = session.execute(
        type="scrape",
        response_format=Product,
        instructions="Extract product name, price, available sizes and colors"
    )
```

### 示例：分类与数据提取结合

```mermaid
graph LR
    A[访问网页] --> B[document-category]
    B --> C{分类结果}
    C -->|search-results| D[提取列表数据]
    C -->|item| E[提取详情数据]
    C -->|other| F[提取导航信息]
    D --> G[返回结构化JSON]
    E --> G
    F --> G
```

## 错误处理

### LLMParsingError

当 LLM 返回格式不符合预期时，引擎会抛出解析错误：

```python
# packages/notte-llm/src/notte_llm/engine.py
if self.fail_if_outer_tag:
    raise LLMParsingError(
        f"No content found within <{self.outer_tag}> tags in the response: {text}"
    )

if self.fail_if_inner_tag:
    raise LLMParsingError(
        f"No content found within ```{self.inner_tag}``` blocks in the response: {text}"
    )
```

### 常见错误场景

| 错误类型 | 原因 | 解决方案 |
|----------|------|----------|
| 缺少外层标签 | LLM 未按要求输出 XML 标签 | 检查 prompt 模板配置 |
| 缺少内层代码块 | JSON 数据未包裹在代码块中 | 使用 `fail_if_inner_tag=True` |
| Schema 验证失败 | 返回数据不符合定义的结构 | 检查 JSON Schema 定义 |

## 最佳实践

1. **优先使用 Pydantic 模型**：通过类型提示获得更好的 IDE 支持和验证
2. **明确的提取指令**：使用自然语言清晰描述需要提取的字段
3. **合理设置作用域**：使用 `selector` 减少无关内容的干扰
4. **启用主要内容提取**：设置 `only_main_content=True` 排除噪音

## 相关链接

- [ScrapeAction API 文档](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/actions/actions.py)
- [LLM 解析引擎](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/src/notte_llm/engine.py)
- [Prompt 模板目录](https://github.com/nottelabs/notte/tree/main/packages/notte-llm/src/notte_llm/prompts)

---

<a id='session-management'></a>

## 会话管理系统

### 相关页面

相关主题：[动作执行系统](#action-system), [凭证保险库](#vault-credentials)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-browser/src/notte_browser/session.py](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/src/notte_browser/session.py)
- [packages/notte-browser/src/notte_browser/controller.py](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/src/notte_browser/controller.py)
- [packages/notte-browser/src/notte_browser/playwright.py](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/src/notte_browser/playwright.py)
- [packages/notte-integrations/src/notte_integrations/sessions/cdp_session.py](https://github.com/nottelabs/notte/blob/main/packages/notte-integrations/src/notte_integrations/sessions/cdp_session.py)
</details>

# 会话管理系统

## 概述

会话管理系统（Session Management System）是 Notte 项目中负责管理浏览器会话的核心模块。该系统提供了创建、控制、监控和终止浏览器会话的完整生命周期管理功能。Notte 的会话管理基于 Playwright 浏览器自动化框架，支持 Chrome 等多种浏览器的自动化控制。

会话管理系统的主要职责包括：

- 创建和管理浏览器会话实例
- 处理会话的启动和停止
- 管理会话级别的 Cookie 和浏览器状态
- 提供页面观察（Observe）和动作执行（Execute）能力
- 支持 CDP（Chrome DevTools Protocol）集成
- 提供隐匿性功能（Stealth），包括代理配置和 CAPTCHA 处理

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py]()

## 核心架构

### 系统组件关系

```mermaid
graph TD
    A[NotteClient] --> B[Session]
    B --> C[BrowserController]
    C --> D[PlaywrightBrowser]
    C --> E[CDPSession]
    B --> F[Cookie管理]
    B --> G[Proxy配置]
    B --> H[观察与执行]
```

Notte 会话管理系统采用分层架构设计：

| 层级 | 组件 | 职责 |
|------|------|------|
| 客户端层 | `NotteClient` | SDK 入口，管理会话创建 |
| 会话层 | `Session` | 会话生命周期管理 |
| 控制器层 | `BrowserController` | 浏览器控制抽象 |
| 浏览器层 | `PlaywrightBrowser` / `CDPSession` | 底层浏览器操作 |
| 存储层 | Cookie/Proxy | 持久化配置 |

资料来源：[packages/notte-browser/src/notte_browser/controller.py]()

### 关键模块

| 模块路径 | 功能描述 |
|----------|----------|
| `notte_browser/session.py` | 浏览器会话核心实现 |
| `notte_browser/controller.py` | 浏览器控制器抽象层 |
| `notte_browser/playwright.py` | Playwright 浏览器实现 |
| `notte_integrations/sessions/cdp_session.py` | CDP 协议集成实现 |

## 会话生命周期

### 状态机模型

```mermaid
stateDiagram-v2
    [*] --> Created: 初始化
    Created --> Starting: session.start()
    Starting --> Running: 浏览器就绪
    Running --> Executing: 执行动作
    Executing --> Running: 动作完成
    Running --> Stopping: session.stop()
    Stopping --> Stopped: 清理完成
    Stopped --> [*]
    
    Running --> Error: 异常发生
    Error --> Stopped: 错误处理
```

### 创建会话

会话可以通过 `NotteClient` 的 `Session()` 方法创建，支持上下文管理器（with语句）自动管理生命周期。

```python
from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
```

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:50-60]()

### 会话配置参数

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `browser_type` | str | "chrome" | 浏览器类型（chrome, firefox等） |
| `open_viewer` | bool | False | 是否打开可视化查看器 |
| `proxies` | bool | False | 是否启用内置代理 |
| `solve_captchas` | bool | False | 是否自动解决CAPTCHA |
| `timeout_minutes` | int | 5 | 会话超时时间（分钟） |
| `_cookie_file` | str | None | Cookie持久化文件路径 |

## 浏览器控制器

### BrowserController 抽象

`BrowserController` 是浏览器控制的核心抽象类，定义了浏览器操作的统一接口。

资料来源：[packages/notte-browser/src/notte_browser/controller.py]()

### PlaywrightBrowser 实现

`PlaywrightBrowser` 是基于 Playwright 框架的浏览器实现，负责底层的浏览器启动、页面导航、元素交互等操作。

```python
# Playwright 浏览器核心功能
- 启动浏览器实例
- 创建新页面/标签页
- 执行页面导航
- 元素定位和交互
- 截图和页面内容抓取
```

资料来源：[packages/notte-browser/src/notte_browser/playwright.py]()

### CDP Session 实现

CDP（Chrome DevTools Protocol）会话提供了与 Chrome 浏览器的深层集成能力，适用于高级自动化场景。

```python
from notte_integrations.sessions.cdp_session import CDPSession

# CDP 会话功能
- 实时网络监控
- JavaScript 执行拦截
- 性能分析
- 控制台日志捕获
```

资料来源：[packages/notte-integrations/src/notte_integrations/sessions/cdp_session.py]()

## 会话观察与动作执行

### 观察机制（Observe）

观察机制用于获取当前页面的可交互元素列表，生成动作空间（Action Space）。

```python
# 快速观察（简单页面感知）
obs = session.observe(perception_type='fast')

# 深度观察（LLM格式化）
obs = session.observe(perception_type='deep')

# 带指令的观察
actions = session.observe(instructions="填写邮箱输入框")
```

| 感知类型 | 特点 | 适用场景 |
|----------|------|----------|
| `fast` | 简单页面感知，执行快速 | 简单页面、低延迟需求 |
| `deep` | LLM调用格式化 | 复杂页面、精确动作空间 |

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:100-120]()

### 动作执行（Execute）

执行机制支持多种浏览器操作类型：

| 动作类型 | 说明 | 示例 |
|----------|------|------|
| `goto` | 导航到指定URL | `type="goto", url="..."` |
| `goto_new_tab` | 在新标签页打开URL | `type="goto_new_tab", url="..."` |
| `close_tab` | 关闭当前标签页 | `type="close_tab"` |
| `scrape` | 抓取页面内容 | `type="scrape", instructions="..."` |
| `click` | 点击元素 | `type="click", id="B1"` |
| `fill` | 填写表单 | `type="fill", id="I1", value="..."` |

资料来源：[packages/notte-core/src/notte_core/actions/actions.py]()

## Cookie 管理

### 自动Cookie保存

会话停止时自动保存Cookie到指定文件：

```python
with client.Session(_cookie_file="cookies.json") as session:
    # 访问需要登录的网站
    session.execute(type="goto", url="https://example.com")
# 退出时会话自动保存Cookie
```

### Cookie持久化机制

```mermaid
sequenceDiagram
    participant Session
    participant Client
    participant Browser
    participant CookieFile
    
    Session->>Browser: 执行操作
    Session->>Session: session.stop()
    Session->>Browser: get_cookies()
    Browser->>Session: cookies_data
    Session->>CookieFile: create_or_append_cookies_to_file()
    CookieFile->>CookieFile: 保存Cookie
```

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:40-48]()

## 隐匿性功能（Stealth）

### 代理配置

Notte 支持内置代理配置，用于增强自动化任务的匿名性：

```python
with client.Session(
    proxies=True,  # 启用内置代理（默认美国节点）
    browser_type="chrome",
    open_viewer=True
) as session:
    agent = client.Agent(session=session, max_steps=5)
    response = agent.run(
        task="执行任务",
        url="https://example.com"
    )
```

### 自定义代理

```python
from notte_sdk import NotteClient, ExternalProxy

client = NotteClient()

proxy_settings = ExternalProxy(
    server="http://your-proxy-server:port",
    username="your-username",
    password="your-password"
)

with client.Session(proxy=proxy_settings) as session:
    pass
```

### CAPTCHA处理

Notte 内置CAPTCHA自动解决功能：

```python
with client.Session(
    solve_captchas=True,
    browser_type="chrome"
) as session:
    # 系统会自动检测和处理CAPTCHA
    session.execute(type="goto", url="https://example.com/recaptcha")
```

## API 参考

### NotteClient.Session()

创建新的浏览器会话。

**签名：**
```python
def Session(
    self,
    browser_type: str = "chrome",
    open_viewer: bool = False,
    proxies: bool = False,
    solve_captchas: bool = False,
    timeout_minutes: int = 5,
    _cookie_file: str | None = None,
) -> Session:
```

**返回值：** `Session` 实例

### Session.execute()

执行浏览器动作。

**签名：**
```python
def execute(
    self,
    type: Literal["goto", "goto_new_tab", "close_tab", "scrape", ...],
    **kwargs
) -> ExecutionResult:
```

### Session.observe()

观察当前页面，生成动作空间。

**签名：**
```python
def observe(
    self,
    perception_type: Literal["fast", "deep"] = "fast",
    instructions: str | None = None,
    **kwargs
) -> ObserveResponse | list[InteractionActionUnion]:
```

## 最佳实践

### 1. 使用上下文管理器

始终使用 `with` 语句管理会话，确保资源正确释放：

```python
# 推荐写法
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")

# 不推荐：需要手动调用stop()
session = client.Session()
try:
    session.start()
    session.execute(type="goto", url="https://example.com")
finally:
    session.stop()
```

### 2. Cookie复用

对于需要登录的网站，使用Cookie持久化避免重复登录：

```python
# 首次登录并保存Cookie
with client.Session(_cookie_file="session.json") as session:
    session.execute(type="goto", url="https://example.com/login")
    # 执行登录操作...

# 后续请求复用Cookie
with client.Session(_cookie_file="session.json") as session:
    session.execute(type="goto", url="https://example.com/protected")
```

### 3. 合理选择感知类型

| 场景 | 推荐感知类型 |
|------|-------------|
| 简单表单填写 | `fast` |
| 复杂页面导航 | `deep` |
| 批量操作 | `fast` |
| 精确元素定位 | `deep` |

## 错误处理

### 常见错误

| 错误类型 | 原因 | 解决方案 |
|----------|------|----------|
| `ValueError` | 会话未启动 | 确保在 `with` 块内执行操作 |
| `RuntimeError` | 会话关闭失败 | 检查浏览器进程状态 |
| 浏览器启动失败 | Playwright未安装 | 运行 `playwright install` |

### 错误恢复

```python
from notte_sdk import NotteClient

client = NotteClient()

try:
    with client.Session() as session:
        session.execute(type="goto", url="https://example.com")
except Exception as e:
    # 错误日志记录
    print(f"会话执行错误: {e}")
    # 重新创建会话
```

## 相关文档

- [Agent 系统](../agent/agent-system.md)
- [动作系统](../actions/actions.md)
- [观察系统](../observation/observation.md)
- [MCP 集成](../integrations/mcp-integration.md)

---

<a id='action-system'></a>

## 动作执行系统

### 相关页面

相关主题：[会话管理系统](#session-management), [核心模块实现](#core-modules)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-core/src/notte_core/actions/actions.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/actions/actions.py)
- [packages/notte-core/src/notte_core/errors/processing.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/errors/processing.py)
- [packages/notte-agent/src/notte_agent/falco/system.md](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/falco/system.md)
- [packages/notte-agent/src/notte_agent/falco/prompt.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/falco/prompt.py)
- [packages/notte-sdk/src/notte_sdk/endpoints/sessions.py](https://github.com/nottelabs/notte/blob/main/packages/notte-sdk/src/notte_sdk/endpoints/sessions.py)
</details>

# 动作执行系统

## 概述

动作执行系统是 Notte 项目中负责与网页进行交互的核心模块。该系统定义了 Agent 可以执行的所有浏览器操作类型，包括页面导航、表单填充、元素点击、数据提取等。动作执行系统通过结构化的动作定义和统一的执行接口，使 AI Agent 能够以编程方式控制浏览器行为。

系统架构遵循模块化设计原则，核心动作定义位于 `notte_core` 包中，而具体执行逻辑则在 `notte_browser` 和 `notte_agent` 包中实现。SDK 层提供了面向用户的简洁 API，隐藏了底层复杂性。

## 动作类型体系

Notte 的动作系统采用类型字面量（Literal Types）定义所有支持的浏览器操作。每一类动作都有明确的类型标识符、参数定义和执行消息。

### 基础动作类型

| 动作类型 | 描述 | 参数 |
|---------|------|------|
| `goto` | 导航到指定 URL | `url: str` |
| `goto_new_tab` | 在新标签页中打开 URL | `url: str` |
| `close_tab` | 关闭当前标签页 | 无 |
| `click` | 点击元素 | `id: str` |
| `hover` | 悬停在元素上 | `id: str` |
| `scrape` | 从页面提取数据 | `instructions: str` |
| `form_fill` | 填写表单 | `value: dict` |
| `select_option` | 选择下拉选项 | `id: str`, `option: str` |
| `captcha_solve` | 解决验证码 | `captcha_type: str` |
| `reload` | 刷新页面 | 无 |

### 导航动作

#### GotoAction

导航到指定 URL 是最基础的浏览器操作。`GotoAction` 接收一个 URL 参数，并将当前页面导航至该地址。

```python
class GotoAction(BrowserAction):
    type: Literal["goto"] = "goto"
    description: str = "Navigate to a URL"
    url: str

    def execution_message(self) -> str:
        return f"Navigated to '{self.url}'"
```

**示例：**
```python
session.execute(type="goto", url="https://www.example.com")
```

#### GotoNewTabAction

在新的浏览器标签页中打开 URL。此动作不影响当前页面的状态。

**示例：**
```python
session.execute(type="goto_new_tab", url="https://www.example.com")
```

#### CloseTabAction

关闭当前活跃的浏览器标签页。如果关闭的是最后一个标签页，浏览器会话将保持但显示空白页面。

### 交互动作

#### ClickAction

点击页面上的可交互元素，如按钮、链接等。元素通过系统分配的 ID 标识。

#### HoverAction

将鼠标悬停在指定元素上，通常用于触发下拉菜单或显示隐藏内容。

#### SelectOptionAction

从 `<select>` 下拉列表中选择选项。需要指定目标元素 ID 和要选择的选项值。

### 表单处理

#### FormFillAction

表单填写是网页交互中最常见的操作之一。`FormFillAction` 支持批量填写多个字段，支持多种输入类型。

```python
# 示例：填写地址表单
form_values = {
    "address1": "123 Main St",
    "city": "San Francisco",
    "state": "CA"
}
session.execute(type="form_fill", value=form_values)
```

系统会自动识别目标元素并进行相应的输入操作，支持文本框、文本域、下拉选择等多种表单控件。

### 数据提取

#### ScrapeAction

从当前页面提取结构化数据。通过自然语言指令指定要提取的内容。

```python
obs = session.observe()
scrape_result = session.execute(
    type="scrape",
    instructions="提取所有搜索结果的标题和链接"
)
```

### 验证码处理

#### CaptchaSolveAction

处理页面上的验证码挑战。系统支持多种验证码类型，包括 reCAPTCHA、hCaptcha、图像验证等。

**关键规则：**
- 绝对不要直接点击验证码相关元素
- 必须使用 `captcha_solve` 专用动作
- 检测到验证码时应立即使用此动作

```python
# 解决 reCAPTCHA
session.execute(type="captcha_solve", captcha_type="recaptcha")
```

## 动作执行流程

```mermaid
graph TD
    A[用户/Agent 调用 execute] --> B[Session 接收动作请求]
    B --> C{验证动作类型}
    C -->|有效| D[构建动作对象]
    C -->|无效| E[抛出 ValidationError]
    D --> F[发送到 notte_browser 执行]
    F --> G{执行结果}
    G -->|成功| H[返回 ExecutionResult]
    G -->|失败| I{错误类型}
    I -->|可重试| J[执行重试逻辑]
    I -->|不可重试| K[抛出异常]
    J --> F
```

## 执行结果处理

### ExecutionResult

每次动作执行都会返回 `ExecutionResult` 对象，包含执行状态和相关信息：

| 字段 | 类型 | 描述 |
|------|------|------|
| `success` | `bool` | 执行是否成功 |
| `message` | `str` | 执行结果消息 |
| `session_id` | `str` | 会话标识符 |
| `url` | `str` | 执行后的页面 URL |
| `error` | `str \| None` | 错误信息（如果失败） |

### 错误处理

系统在 `notte_core/errors/processing.py` 中定义了丰富的错误类型：

| 错误类型 | 触发条件 |
|---------|---------|
| `InvalidPlaceholderError` | 占位符无法解析 |
| `ScrapeFailedError` | 数据提取失败 |
| `InvalidA11yTreeType` | 无障碍树类型无效 |
| `InvalidA11yChildrenError` | 元素子节点数量异常 |

## 动作选择机制

在 Agent 决策过程中，动作选择器（Action Selector）负责从页面的可交互元素中生成候选动作列表。

```mermaid
graph LR
    A[页面 DOM/Accessibility Tree] --> B[Perception 模块]
    B --> C[生成交互元素列表]
    C --> D[动作选择器 Pipe]
    D --> E[过滤/排序候选动作]
    E --> F[返回 ActionSpace]
```

### 元素标识符规范

系统使用统一的前缀标识不同类型的可交互元素：

| 前缀 | 元素类型 | 示例 |
|------|---------|------|
| `I` | 输入字段 | `I1`, `I2` |
| `B` | 按钮 | `B1`, `B2` |
| `L` | 链接 | `L1`, `L2` |
| `F` | 图片/图形 | `F1` |
| `O` | 下拉选项 | `O1` |
| `M` | 杂项元素 | `M1` |

## SDK 使用示例

### 基本执行流程

```python
from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    # 导航
    session.execute(type="goto", url="https://console.notte.cc")
    
    # 观察页面
    obs = session.observe()
    print(obs.space.description)
    
    # 执行交互
    session.execute(type="click", id="B1")
```

### 带指令的观察

使用 `instructions` 参数可以快速定位特定意图的交互元素：

```python
actions = session.observe(instructions="Fill the email input")
print(actions[0].model_dump())
```

### 感知类型

| 类型 | 描述 | 适用场景 |
|------|------|---------|
| `fast` | 快速页面感知，不调用 LLM | 高频交互、简单页面 |
| `deep` | 深度感知，使用 LLM 格式化 | 复杂页面、需要结构化理解 |

```python
# 快速感知
obs = session.observe(perception_type='fast')

# 深度感知
obs = session.observe(perception_type='deep')
```

## 动作定义源码结构

核心动作类继承自 `BrowserAction` 基类，每个动作实现以下关键方法：

```python
class BrowserAction(BaseModel):
    type: str
    description: str
    
    def execution_message(self) -> str:
        """返回动作执行后的状态消息"""
        ...
    
    @staticmethod
    def example() -> Self:
        """返回动作的示例实例"""
        ...
    
    @property
    def param(self) -> ActionParameter | None:
        """返回动作参数定义"""
        ...
```

资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1-100]()

## 最佳实践

1. **使用上下文管理器**：始终使用 `with` 语句管理 Session，确保资源正确释放
2. **选择合适的感知类型**：简单操作使用 `fast`，复杂页面使用 `deep`
3. **验证元素存在性**：页面元素 ID 可能在不同步骤间变化，不要依赖历史 ID
4. **处理验证码**：发现验证码时立即使用专用处理动作
5. **检查执行结果**：始终检查 `ExecutionResult.success` 字段

```python
# 推荐做法
with client.Session() as session:
    result = session.execute(type="goto", url="https://example.com")
    if not result.success:
        print(f"Navigation failed: {result.error}")
```

## 相关模块

| 模块 | 职责 |
|------|------|
| `notte_core.actions` | 定义所有动作类型和基类 |
| `notte_browser` | 实际执行浏览器操作 |
| `notte_agent` | Agent 决策和动作选择 |
| `notte_sdk` | 面向用户的执行接口 |

---

<a id='vault-credentials'></a>

## 凭证保险库

### 相关页面

相关主题：[文件存储系统](#file-storage)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-core/src/notte_core/credentials/base.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/credentials/base.py)
- [packages/notte-core/src/notte_core/credentials/types.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/credentials/types.py)
- [packages/notte-browser/src/notte_browser/vault.py](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/src/notte_browser/vault.py)
- [examples/auth-vault-agent/agent.py](https://github.com/nottelabs/notte/blob/main/examples/auth-vault-agent/agent.py)
</details>

# 凭证保险库

凭证保险库（Credentials Vault） 是 Notte 框架中用于安全管理用户凭证（credentials）和占位符（placeholder）的核心组件。它为 Agent 提供了一种安全的方式来存储、检索和使用敏感信息（如密码、API 密钥、验证码等），同时避免了这些敏感信息在日志或交互历史中暴露。

## 功能概述

凭证保险库的主要职责包括：

| 功能 | 描述 |
|------|------|
| 凭证存储 | 安全存储用户的认证凭据 |
| 占位符解析 | 将代码中的占位符替换为实际凭证值 |
| 动态注入 | 在表单填写时自动注入凭证 |
| 生命周期管理 | 管理凭证的有效期和刷新 |

凭证保险库与 Agent 系统紧密集成，当 Agent 执行需要认证的任务时（如登录网站），系统会从保险库中获取相应凭证，而不是让 Agent 直接处理敏感数据。资料来源：[packages/notte-core/src/notte_core/errors/processing.py:31-38]()

## 核心架构

### 组件关系图

```mermaid
graph TD
    A[Agent] --> B[Vault]
    B --> C[Credentials Store]
    B --> D[Placeholder Resolver]
    C --> E[BaseCredential]
    D --> F[InvalidPlaceholderError]
    G[Session] --> B
    H[Action Execution] --> B
```

### 凭证类型体系

Notte 框架定义了多种凭证类型，通过 `credentials/types.py` 中的类型系统进行管理：

- **BaseCredential**：所有凭证类型的基类
- **CredentialsPlaceholder**：用于在代码中引用保险库中的凭证
- **AgentCredentials**：专门用于 Agent 认证场景的凭证

资料来源：[packages/notte-core/src/notte_core/credentials/types.py]()

## 使用方式

### 基本使用流程

```mermaid
graph LR
    A[创建 Vault] --> B[添加凭证]
    B --> C[Agent 执行任务]
    C --> D[解析占位符]
    D --> E[注入凭证]
```

### 在 Agent 中使用保险库

以下示例展示了如何在 Agent 中集成凭证保险库：

```python
from notte_sdk import NotteClient

client = NotteClient()

# 创建保险库并添加凭证
with client.Vault() as vault:
    vault.add_credential(name="github_token", value="ghp_xxxxx")
    vault.add_credential(name="email", value="user@example.com")
    
    with client.Session() as session:
        agent = client.Agent(session=session, vault=vault, max_steps=10)
        response = agent.run(
            task="登录 GitHub 并访问我的仓库列表"
        )
```

资料来源：[examples/auth-vault-agent/agent.py]()

### 占位符机制

在任务描述中使用占位符引用保险库中的凭证：

```python
# 占位符格式
vault.add_credential(name="github_password", value="mypassword")

# 在任务中使用
task = "使用凭证 {github_password} 登录 GitHub"
```

当 Agent 执行时，系统会自动将 `{placeholder_name}` 格式的占位符替换为保险库中对应的实际值。

## API 参考

### Vault 类

| 方法 | 参数 | 返回值 | 描述 |
|------|------|--------|------|
| `add_credential` | `name: str, value: str` | `None` | 添加新凭证 |
| `get_credential` | `name: str` | `str` | 获取指定名称的凭证 |
| `remove_credential` | `name: str` | `bool` | 删除指定凭证 |
| `list_credentials` | - | `list[str]` | 列出所有凭证名称 |

### 占位符错误处理

当占位符未被正确处理时，系统会抛出 `InvalidPlaceholderError`：

| 错误字段 | 说明 |
|----------|------|
| `dev_message` | 指出占位符未被当前保险库处理 |
| `agent_message` | 提示 Agent 尝试选择其他值 |
| `user_message` | 用户友好的错误提示 |

资料来源：[packages/notte-core/src/notte_core/errors/processing.py:31-38]()

## 最佳实践

### 安全建议

1. **敏感信息隔离**：所有敏感凭证应存储在 Vault 中，避免硬编码
2. **环境变量分离**：生产环境中使用环境变量配置凭证，而非代码仓库
3. **最小权限原则**：仅为 Agent 提供完成任务所需的最少凭证

### 性能优化

| 策略 | 描述 |
|------|------|
| 延迟加载 | 仅在需要时加载凭证到内存 |
| 缓存机制 | 缓存已解析的占位符结果 |
| 会话复用 | 在同一会话中复用保险库实例 |

## 与其他组件的集成

### 与 Session 集成

保险库可以与浏览器会话配合使用，实现自动登录：

```python
with client.Vault() as vault:
    vault.add_credential(name="username", value="user@example.com")
    vault.add_credential(name="password", value="secret123")
    
    with client.Session() as session:
        agent = client.Agent(session=session, vault=vault)
        # Agent 会自动使用 vault 中的凭证进行登录
```

### 与 Agent Persona 集成

保险库可与 Agent Persona 结合使用，提供完整的数字身份认证能力：

```python
with client.Vault() as vault:
    with client.Persona() as persona:
        with client.Session() as session:
            agent = client.Agent(
                session=session,
                persona=persona,
                vault=vault,
                max_steps=15
            )
```

资料来源：[README.md](https://github.com/nottelabs/notte/blob/main/README.md)

## 实现细节

### 凭证存储层

凭证保险库的存储实现位于 `packages/notte-browser/src/notte_browser/vault.py`，该模块负责：

- 本地凭证的安全存储
- 与浏览器上下文的集成
- 跨会话的凭证持久化

### 核心基类

`packages/notte-core/src/notte_core/credentials/base.py` 定义了凭证管理的抽象接口，包括：

- 凭证的创建和销毁
- 占位符的注册和解析
- 凭证的验证和刷新

资料来源：[packages/notte-core/src/notte_core/credentials/base.py]()

## 总结

凭证保险库是 Notte 框架安全架构的重要组成部分，它通过以下方式保护敏感信息：

- 集中管理所有凭证
- 使用占位符避免敏感信息暴露
- 与 Agent 系统无缝集成
- 提供完善的错误处理机制

通过正确使用凭证保险库，开发者可以在保持安全性的同时，让 Agent 自动化执行需要认证的复杂任务。

---

<a id='file-storage'></a>

## 文件存储系统

### 相关页面

相关主题：[凭证保险库](#vault-credentials)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/notte-sdk/src/notte_sdk/endpoints/files.py](https://github.com/nottelabs/notte/blob/main/packages/notte-sdk/src/notte_sdk/endpoints/files.py)
- [packages/notte-core/src/notte_core/storage.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/storage.py)
- [docs/src/snippets/file-storage/quickstart.mdx](https://github.com/nottelabs/notte/blob/main/docs/src/snippets/file-storage/quickstart.mdx)
</details>

# 文件存储系统

## 概述

Notte 的文件存储系统是整个平台的核心模块之一，负责管理文件上传、下载、存储和检索功能。该系统与 Notte 的会话管理和浏览器交互功能紧密集成，为 AI Agent 提供持久化的文件存储能力。

文件存储系统的主要职责包括：

- 支持会话期间的文件上传与持久化
- 提供文件元数据管理
- 存储截图、图片等多媒体数据
- 与 Vault 凭证管理系统集成

## 核心架构

### 数据模型

文件存储系统的核心数据模型为 `FileData`，定义在 `packages/notte-core/src/notte_core/storage.py` 中：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `id` | str | 文件唯一标识符 |
| `name` | str | 文件名称 |
| `mime_type` | str | 文件 MIME 类型 |
| `size` | int | 文件大小（字节） |
| `url` | str \| None | 文件访问 URL |
| `content` | bytes \| None | 文件二进制内容 |

### 存储层级

```
┌─────────────────────────────────────────────┐
│              NotteClient                    │
│  (packages/notte-sdk/src/notte_sdk)         │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│         FilesEndpoint                       │
│  (packages/notte-sdk/src/notte_sdk/         │
│   endpoints/files.py)                       │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│         StorageService                      │
│  (packages/notte-core/src/notte_core/       │
│   storage.py)                               │
└─────────────────────────────────────────────┘
```

## API 接口

### FilesEndpoint 类

`FilesEndpoint` 是 SDK 层面的文件操作入口，提供以下核心方法：

| 方法名 | 参数 | 返回类型 | 说明 |
|--------|------|----------|------|
| `upload` | file: FileData | FileData | 上传文件并返回包含 ID 的文件对象 |
| `download` | file_id: str | bytes | 根据文件 ID 下载文件内容 |
| `list` | - | list[FileData] | 列出所有已存储的文件 |
| `delete` | file_id: str | None | 删除指定文件 |

### 端点路由

文件存储 API 的基础端点为：

```
POST /api/files/upload
GET  /api/files/{file_id}
GET  /api/files/{file_id}/download
DELETE /api/files/{file_id}
GET  /api/files
```

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/files.py:1-100]()

## 存储类型

Notte 支持多种类型的文件存储：

### 用户上传文件

用户通过 SDK 上传的自定义文件，如文档、配置文件等。

### 截图数据

浏览器截图自动存储为文件，便于 Agent 回溯和调试：

```python
class ScreenshotData(BaseModel):
    id: str
    timestamp: datetime
    data: bytes
    session_id: str
```

### 图片数据

`ImageData` 类封装了从网页抓取的图片资源：

```python
class ImageData(BaseModel):
    url: str | None
    alt_text: str | None
    id: str
    
    def bytes(self) -> bytes:
        """获取图片字节数据"""
```

资料来源：[packages/notte-core/src/notte_core/data/space.py:50-70]()

## 与会话系统集成

文件存储与 Notte 的会话管理系统深度集成。在会话运行期间：

1. **会话启动时**：可以指定 `cookies_file` 参数自动保存会话 cookie 到指定文件
2. **会话运行中**：截图和图片自动关联到当前会话
3. **会话结束时**：文件保持持久化，可供后续会话访问

```python
# 会话文件存储示例
with client.Session(cookies_file="./cookies.json") as session:
    session.execute(type="goto", url="https://example.com")
    # 截图自动保存为文件
    screenshot = session.screenshot()
```

资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:80-95]()

## 快速开始

### 安装与配置

确保已安装 notte-sdk：

```bash
pip install notte-sdk
```

### 上传文件

```python
from notte_sdk import NotteClient

client = NotteClient()
files = client.files

# 上传本地文件
with open("document.pdf", "rb") as f:
    file_data = files.upload(
        name="document.pdf",
        content=f.read(),
        mime_type="application/pdf"
    )
    print(f"文件已上传，ID: {file_data.id}")
```

### 下载文件

```python
# 通过文件 ID 下载
content = files.download(file_id="abc123")
with open("output.pdf", "wb") as f:
    f.write(content)
```

### 列出文件

```python
# 列出所有已存储的文件
all_files = files.list()
for file in all_files:
    print(f"{file.id}: {file.name} ({file.size} bytes)")
```

资料来源：[docs/src/snippets/file-storage/quickstart.mdx:1-50]()

## 错误处理

文件存储系统定义了以下专用错误类型：

### StorageError

基础存储错误类，所有存储相关异常都继承于此。

### FileNotFoundError

当请求的文件不存在时抛出：

```python
class FileNotFoundError(NotteBaseError):
    def __init__(self, file_id: str) -> None:
        super().__init__(
            dev_message=f"File with id {file_id} not found in storage",
            agent_message=f"Unable to access file",
            user_message="The requested file could not be found"
        )
```

### StorageQuotaExceededError

存储配额超限时的异常。

资料来源：[packages/notte-core/src/notte_core/storage.py:30-60]()

## 最佳实践

### 文件管理策略

1. **定期清理**：定期调用 `delete` 方法清理不再需要的文件
2. **批量操作**：使用 `list` 方法获取文件列表后进行批量筛选
3. **命名规范**：为文件指定清晰的 `name` 便于识别

### 性能优化

- 大文件建议分块上传
- 图片资源优先使用 `url` 引用而非直接存储 `content`
- 敏感文件使用 Vault 加密存储

## 相关模块

| 模块 | 路径 | 说明 |
|------|------|------|
| `SessionsEndpoint` | `packages/notte-sdk/src/notte_sdk/endpoints/sessions.py` | 会话管理，包含文件相关的 cookie 存储 |
| `StructuredData` | `packages/notte-core/src/notte_core/data/space.py` | 结构化数据存储 |
| `ImageData` | `packages/notte-core/src/notte_core/data/space.py` | 图片数据管理 |
| `Vault` | `packages/notte-core/src/notte_core/vault.py` | 敏感文件加密存储 |

---

---

## Doramagic 踩坑日志

项目：nottelabs/notte

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.8.8。

## 1. 安装坑 · 来源证据：v1.8.8

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.8.8
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5224b46e2312471c976888e8a2f8f4a6 | https://github.com/nottelabs/notte/releases/tag/v1.8.8 | 来源类型 github_release 暴露的待验证使用条件。

## 2. 配置坑 · 来源证据：v1.8.13

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.13
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_56505da48cd74758ab7a9a1d82092e18 | https://github.com/nottelabs/notte/releases/tag/v1.8.13 | 来源类型 github_release 暴露的待验证使用条件。

## 3. 配置坑 · 来源证据：v1.8.14

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.14
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8f78a2591cea4f5aad8bfa0cb0ea15a0 | https://github.com/nottelabs/notte/releases/tag/v1.8.14 | 来源类型 github_release 暴露的待验证使用条件。

## 4. 配置坑 · 来源证据：v1.8.15

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.15
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f611f1d0dd2440af8e84e9544ab1bdb6 | https://github.com/nottelabs/notte/releases/tag/v1.8.15 | 来源类型 github_release 暴露的待验证使用条件。

## 5. 配置坑 · 来源证据：v1.8.6

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.6
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0ed3c86ff7a34e5896a4daeb75552d4d | https://github.com/nottelabs/notte/releases/tag/v1.8.6 | 来源类型 github_release 暴露的待验证使用条件。

## 6. 配置坑 · 来源证据：v1.8.9

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.9
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6195971390e8494f88083c862aef7eb6 | https://github.com/nottelabs/notte/releases/tag/v1.8.9 | 来源类型 github_release 暴露的待验证使用条件。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:900152988 | https://github.com/nottelabs/notte | README/documentation is current enough for a first validation pass.

## 8. 运行坑 · 来源证据：v1.8.7

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.8.7
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ab102ac99c2441118475601c34ab0ee9 | https://github.com/nottelabs/notte/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | last_activity_observed missing

## 10. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:900152988 | https://github.com/nottelabs/notte | no_demo; severity=medium

## 11. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:900152988 | https://github.com/nottelabs/notte | No sandbox install has been executed yet; downstream must verify before user use.

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:900152988 | https://github.com/nottelabs/notte | no_demo; severity=medium

## 13. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | issue_or_pr_quality=unknown

## 14. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | release_recency=unknown

<!-- canonical_name: nottelabs/notte; human_manual_source: deepwiki_human_wiki -->