{
"canonical_name": "nottelabs/notte",
"compilation_id": "pack_766828fa02bd41d69d8e0c46dad9697b",
"created_at": "2026-05-14T05:11:43.570388+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install notte` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install notte",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_7c72aa1d52be4f4f890b7156152c1ae7"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_810c7b266241f3f0371a8fe76b94e566",
"canonical_name": "nottelabs/notte",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/nottelabs/notte",
"slug": "notte",
"source_packet_id": "phit_360abee9881e44c1aa85b0faa3ddff1f",
"source_validation_id": "dval_ee6e6f447d8946f9a39f3a30f16f1c16"
},
"merchandising": {
"best_for": "需要流程自动化能力，并使用 chatgpt的用户",
"github_forks": 180,
"github_stars": 1953,
"one_liner_en": "🌸 Best framework to build web agents, and deploy serverless web automation functions on reliable browser infra.",
"one_liner_zh": "🌸 Best framework to build web agents, and deploy serverless web automation functions on reliable browser infra.",
"primary_category": {
"category_id": "workflow-automation",
"confidence": "high",
"name_en": "Workflow Automation",
"name_zh": "流程自动化",
"reason": "matched_keywords:automation, agent, browser"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "notte",
"title_zh": "notte 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"type": "workflow_pattern"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-structured-data-extraction",
"type": "selection_signal"
}
]
},
"packet_id": "phit_360abee9881e44c1aa85b0faa3ddff1f",
"page_model": {
"artifacts": {
"artifact_slug": "notte",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install notte",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/nottelabs/notte#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"结构化数据提取"
],
"eyebrow": "流程自动化",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要流程自动化能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "🌸 Best framework to build web agents, and deploy serverless web automation functions on reliable browser infra."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.8.8",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5224b46e2312471c976888e8a2f8f4a6 | https://github.com/nottelabs/notte/releases/tag/v1.8.8 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.8",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.13",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_56505da48cd74758ab7a9a1d82092e18 | https://github.com/nottelabs/notte/releases/tag/v1.8.13 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.13",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.14",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_8f78a2591cea4f5aad8bfa0cb0ea15a0 | https://github.com/nottelabs/notte/releases/tag/v1.8.14 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.14",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.15",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_f611f1d0dd2440af8e84e9544ab1bdb6 | https://github.com/nottelabs/notte/releases/tag/v1.8.15 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.15",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.6",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_0ed3c86ff7a34e5896a4daeb75552d4d | https://github.com/nottelabs/notte/releases/tag/v1.8.6 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.6",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.9",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_6195971390e8494f88083c862aef7eb6 | https://github.com/nottelabs/notte/releases/tag/v1.8.9 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.9",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:900152988 | https://github.com/nottelabs/notte | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.8.7",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_ab102ac99c2441118475601c34ab0ee9 | https://github.com/nottelabs/notte/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.7",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:900152988 | https://github.com/nottelabs/notte | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:900152988 | https://github.com/nottelabs/notte | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:900152988 | https://github.com/nottelabs/notte | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.8.8。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 13,
"forks": 180,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1953
},
"source_url": "https://github.com/nottelabs/notte",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "🌸 Best framework to build web agents, and deploy serverless web automation functions on reliable browser infra.",
"title": "notte 能力包",
"trial_prompt": "# notte - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 notte 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 🌸 Best framework to build web agents, and deploy serverless web automation functions on reliable browser infra. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart-guide：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. package-structure：包结构分析。围绕“包结构分析”模拟一次用户任务，不展示安装或运行结果。\n4. core-modules：核心模块实现。围绕“核心模块实现”模拟一次用户任务，不展示安装或运行结果。\n5. agent-implementation：Agent实现与生命周期。围绕“Agent实现与生命周期”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart-guide\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. package-structure\n输入：用户提供的“包结构分析”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. core-modules\n输入：用户提供的“核心模块实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. agent-implementation\n输入：用户提供的“Agent实现与生命周期”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart-guide：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / package-structure：Step 3 必须围绕“包结构分析”形成一个小中间产物，并等待用户确认。\n- Step 4 / core-modules：Step 4 必须围绕“核心模块实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / agent-implementation：Step 5 必须围绕“Agent实现与生命周期”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/nottelabs/notte\n- https://github.com/nottelabs/notte#readme\n- README.md\n- pyproject.toml\n- docs/setup.md\n- docs/sdk_tutorial.md\n- .env.example\n- packages/notte-core/pyproject.toml\n- packages/notte-browser/pyproject.toml\n- packages/notte-agent/pyproject.toml\n- packages/notte-sdk/pyproject.toml\n- packages/notte-llm/pyproject.toml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 notte 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v1.8.15（https://github.com/nottelabs/notte/releases/tag/v1.8.15）；github/github_release: v1.8.14（https://github.com/nottelabs/notte/releases/tag/v1.8.14）；github/github_release: v1.8.13（https://github.com/nottelabs/notte/releases/tag/v1.8.13）；github/github_release: v1.8.11（https://github.com/nottelabs/notte/releases/tag/v1.8.11）；github/github_release: v1.8.10（https://github.com/nottelabs/notte/releases/tag/v1.8.10）；github/github_release: v1.8.9（https://github.com/nottelabs/notte/releases/tag/v1.8.9）；github/github_release: v1.8.8（https://github.com/nottelabs/notte/releases/tag/v1.8.8）；github/github_release: v1.8.7（https://github.com/nottelabs/notte/releases/tag/v1.8.7）；github/github_release: v1.8.6（https://github.com/nottelabs/notte/releases/tag/v1.8.6）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v1.8.15",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.15"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.14",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.14"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.13",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.13"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.11",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.11"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.10",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.10"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.9",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.9"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.8",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.8"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.7",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.7"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.8.6",
"url": "https://github.com/nottelabs/notte/releases/tag/v1.8.6"
}
],
"status": "已收录 9 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "流程自动化",
"desc": "🌸 Best framework to build web agents, and deploy serverless web automation functions on reliable browser infra.",
"effort": "安装已验证",
"forks": 180,
"icon": "bolt",
"name": "notte 能力包",
"risk": "可发布",
"slug": "notte",
"stars": 1953,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"结构化数据提取"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/nottelabs/notte 项目说明书\n\n生成时间：2026-05-14 04:53:36 UTC\n\n## 目录\n\n- [项目介绍](#project-introduction)\n- [快速入门指南](#quickstart-guide)\n- [包结构分析](#package-structure)\n- [核心模块实现](#core-modules)\n- [Agent实现与生命周期](#agent-implementation)\n- [结构化输出](#structured-output)\n- [会话管理系统](#session-management)\n- [动作执行系统](#action-system)\n- [凭证保险库](#vault-credentials)\n- [文件存储系统](#file-storage)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速入门指南](#quickstart-guide), [包结构分析](#package-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/nottelabs/notte/blob/main/README.md)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 项目介绍\n\n## 项目概述\n\nNotte 是一款面向互联网原生代理系统（Internet-native Agentic Systems）的软件套件，旨在为大型语言模型（LLM）代理提供强大的浏览器自动化和网页交互能力。Notte 将互联网转化为一个结构化、可导航的空间，使每个网站都成为智能代理可以精确解读和操作的地图。\n\n资料来源：[README.md:1]()\n\n## 核心定位\n\nNotte 的核心价值主张在于创建一个可编程的抽象层，覆盖在真实网页之上。通过该技术栈，AI 代理能够：\n\n- 精确解读网页内容结构\n- 执行复杂的浏览器交互操作\n- 实现端到端的自动化工作流\n\n资料来源：[README.md:1]()\n\n## 技术架构\n\n### 包结构\n\nNotte 采用多包架构设计，包含以下核心组件：\n\n| 包名 | 描述 |\n|------|------|\n| `notte-core` | 核心功能模块，包含动作定义、错误处理等基础组件 |\n| `notte-llm` | LLM 集成模块，提供提示词模板和文档分析能力 |\n| `notte-sdk` | Python SDK 模块，提供会话管理和 API 交互接口 |\n| `notte-agent` | 代理执行模块，处理代理决策和浏览器控制逻辑 |\n\n资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1]()\n资料来源：[packages/notte-core/src/notte_core/errors/processing.py:1]()\n\n### 架构分层图\n\n```mermaid\ngraph TD\n A[用户/外部系统] --> B[notte-sdk]\n B --> C[notte-agent]\n C --> D[notte-llm]\n D --> E[notte-core]\n E --> F[浏览器/Playwright]\n F --> G[网页 DOM]\n```\n\n## 核心功能模块\n\n### 浏览器动作系统\n\nNotte 定义了一套完整的浏览器动作类型，支持多种交互场景：\n\n| 动作类型 | 功能描述 |\n|----------|----------|\n| `goto` | 导航至指定 URL |\n| `goto_new_tab` | 在新标签页中打开 URL |\n| `close_tab` | 关闭当前标签页 |\n\n```python\n# 示例：导航动作\nclass GotoAction(BrowserAction):\n type: Literal[\"goto\"] = \"goto\"\n url: str\n description: str = \"Goto to a URL\"\n```\n\n资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1-20]()\n\n### 会话管理\n\nNotte SDK 提供了灵活的会话管理能力，支持快速感知和深度感知两种模式：\n\n```python\n# 快速感知模式（默认）\nobs = session.observe(perception_type='fast')\n\n# 深度感知模式（使用 LLM）\nobs = session.observe(perception_type='deep')\n\n# 带指令的感知（自然语言过滤）\nactions = session.observe(instructions=\"Fill the email input\")\n```\n\n资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:1-30]()\n\n### 文档分类与提取\n\nNotte LLM 模块提供了文档分析能力，支持对网页内容进行结构化处理：\n\n| 文档类别 | 说明 |\n|----------|------|\n| `search-results` | 搜索结果页面 |\n| `item` | 详情/物品页面 |\n| `other` | 其他类型页面 |\n\n资料来源：[packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md:1]()\n\n### 代理决策系统\n\nNotte Agent 模块实现了基于 LLM 的代理决策引擎，支持：\n\n- **元素识别**：通过 ID 系统标识可交互元素（`I`=输入、`B`=按钮、`L`=链接、`F`=图形、`O`=选项、`M`=杂项）\n- **动作序列**：支持表单填写、导航提取等常见操作序列\n- **验证码处理**：内置 CAPTCHA 检测和解决机制\n\n```mermaid\ngraph LR\n A[网页状态] --> B[元素识别]\n B --> C[动作规划]\n C --> D[执行验证]\n D -->|成功| E[下一状态]\n D -->|失败| F[错误处理]\n```\n\n资料来源：[packages/notte-agent/src/notte_agent/gufo/system.md:1-40]()\n\n## 错误处理机制\n\nNotte 建立了完善的错误处理体系，涵盖内部检查和运行时异常：\n\n| 错误类型 | 触发条件 |\n|----------|----------|\n| `InvalidA11yTreeType` | 无效的辅助功能树类型 |\n| `InvalidA11yChildrenError` | 子元素数量不满足假设条件 |\n| `InvalidPlaceholderError` | 占位符未被 vault 处理 |\n| `ScrapeFailedError` | 结构化数据提取失败 |\n\n资料来源：[packages/notte-core/src/notte_core/errors/processing.py:1-40]()\n\n## 使用方式\n\n### 安装\n\nNotte 通过 Python 包管理器分发，可通过标准方式安装。\n\n### 基本工作流\n\n```mermaid\ngraph TD\n A[创建会话] --> B[执行动作]\n B --> C[观察状态]\n C --> D{任务完成?}\n D -->|否| B\n D -->|是| E[返回结果]\n```\n\n```python\n# 完整示例\nobs = session.observe(perception_type='deep')\nprint(obs.space.description)\n```\n\n资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:20-25]()\n\n## 项目信息\n\n| 属性 | 值 |\n|------|------|\n| 版本 | 1.4.4 |\n| 许可证 | SSPL-1.0 |\n| 版权 | © 2025 Notte Labs, Inc. |\n| 作者 | Pinto, Andrea, Giordano, Lucas, nottelabs-team |\n\n资料来源：[README.md:1-15]()\n\n## 引用格式\n\n如需在学术场合引用 Notte，请使用以下 BibTeX 格式：\n\n```bibtex\n@software{notte2025,\n author = {Pinto, Andrea and Giordano, Lucas and {nottelabs-team}},\n title = {Notte: Software suite for internet-native agentic systems},\n url = {https://github.com/nottelabs/notte},\n year = {2025},\n publisher = {GitHub},\n license = {SSPL-1.0},\n version = {1.4.4},\n}\n```\n\n资料来源：[README.md:5-14]()\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[项目介绍](#project-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/setup.md](https://github.com/nottelabs/notte/blob/main/docs/setup.md)\n- [docs/sdk_tutorial.md](https://github.com/nottelabs/notte/blob/main/docs/sdk_tutorial.md)\n- [.env.example](https://github.com/nottelabs/notte/blob/main/.env.example)\n \n\n# 快速入门指南\n\nNotte 是一个面向互联网原生代理系统的软件套件，旨在为 LLM 智能体提供可靠的网页浏览和交互能力。本指南将帮助您快速上手 Notte SDK，从环境配置到实现第一个网页交互任务。\n\n## 环境要求\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 推荐使用 Python 3.10 或更高版本 |\n| pip | 21.0+ | Python 包管理器 |\n| API 密钥 | Notte 账户 | 从 [notte.cc](https://notte.cc) 获取 |\n\n## 环境配置\n\n### 获取 API 密钥\n\n1. 访问 [notte.cc](https://notte.cc) 并注册账户\n2. 在仪表板中生成您的 API 密钥\n3. 将密钥安全存储，避免泄露\n\n### 配置环境变量\n\n创建 `.env` 文件，参考 `.env.example` 中的配置模板：\n\n```bash\n# Notte API 配置\nNOTTE_API_KEY=your_api_key_here\nNOTTE_API_BASE_URL=https://api.notte.cc # 可选，默认为官方 API 地址\n```\n\n环境变量说明：\n\n| 变量名 | 必填 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `NOTTE_API_KEY` | 是 | - | 您的 Notte API 密钥 |\n| `NOTTE_API_BASE_URL` | 否 | `https://api.notte.cc` | API 基础 URL |\n\n资料来源：[.env.example](https://github.com/nottelabs/notte/blob/main/.env.example)\n\n## 安装 SDK\n\n### 使用 pip 安装\n\n```bash\npip install notte-sdk\n```\n\n### 从源码安装\n\n```bash\ngit clone https://github.com/nottelabs/notte.git\ncd notte\npip install -e .\n```\n\n## 核心概念\n\n在深入实践之前，理解以下核心概念有助于更好地使用 Notte SDK：\n\n```mermaid\ngraph TD\n A[Notte Session] --> B[观察页面]\n A --> C[执行动作]\n A --> D[抓取数据]\n B --> E[获取交互元素]\n C --> F[点击/输入/提交]\n D --> G[结构化输出]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style C fill:#fff3e0\n style D fill:#e8f5e9\n```\n\n| 概念 | 说明 |\n|------|------|\n| Session | 会话对象，管理与浏览器的连接状态 |\n| Observe | 观察操作，获取当前页面的交互元素 |\n| Execute | 执行操作，如点击、输入、表单填写等 |\n| Scrape | 抓取操作，从页面提取结构化数据 |\n\n资料来源：[docs/sdk_tutorial.md](https://github.com/nottelabs/notte/blob/main/docs/sdk_tutorial.md)\n\n## 基本使用流程\n\n### 1. 初始化客户端\n\n```python\nfrom notte_sdk import NotteClient\n\nclient = NotteClient()\n```\n\n### 2. 创建会话\n\n```python\nsession = client.sessions.create()\nprint(f\"会话ID: {session.id}\")\n```\n\n### 3. 导航到目标页面\n\n```python\nsession.execute(type=\"goto\", url=\"https://notte.cc\")\n```\n\n### 4. 观察页面元素\n\n```python\n# 快速感知模式\nobs = session.observe(perception_type=\"fast\")\n\n# 深度感知模式（使用 LLM 格式化）\nobs = session.observe(perception_type=\"deep\")\n```\n\n### 5. 执行动作\n\n```python\n# 点击元素\nsession.execute(type=\"click\", id=\"B1\")\n\n# 输入文本\nsession.execute(type=\"fill\", id=\"I1\", value=\"search term\")\n\n# 提交表单\nsession.execute(type=\"submit\", id=\"B2\")\n```\n\n资料来源：[docs/sdk_tutorial.md](https://github.com/nottelabs/notte/blob/main/docs/sdk_tutorial.md)\n\n## 常见任务示例\n\n### 网页抓取\n\nNotte 提供强大的网页抓取功能，支持结构化数据提取：\n\n```python\nfrom notte_sdk import NotteClient, NotteScrapeResponse\n\nclient = NotteClient()\n\n# 基础抓取\nresponse = client.scrape(\n url=\"https://notte.cc\",\n scrape_links=True,\n only_main_content=True\n)\n\n# 带自定义指令的结构化抓取\nfrom pydantic import BaseModel\n\nclass Article(BaseModel):\n title: str\n content: str\n date: str\n\nresponse = client.scrape(\n url=\"https://example.com/blog\",\n response_format=Article,\n instructions=\"Extract only the title, date and content of the articles\"\n)\n```\n\n抓取参数说明：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `url` | string | 是 | 要抓取的网页 URL |\n| `scrape_links` | boolean | 否 | 是否抓取页面链接 |\n| `only_main_content` | boolean | 否 | 是否仅提取主要内容 |\n| `response_format` | BaseModel | 否 | Pydantic 模型用于结构化输出 |\n| `instructions` | string | 否 | 提取数据的自定义指令 |\n\n### 动作观察与过滤\n\n使用自然语言指令快速定位交互元素：\n\n```python\nsession.execute(type=\"goto\", url=\"https://console.notte.cc\")\n\n# 使用自然语言过滤动作空间\nactions = session.observe(instructions=\"Fill the email input\")\nprint(actions[0].model_dump())\n```\n\n### 使用 cURL 直接调用 API\n\n如果您偏好使用 HTTP 直接调用：\n\n```bash\ncurl -X POST 'https://api.notte.cc/scrape' \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"url\": \"https://notte.cc\",\n \"only_main_content\": false,\n }'\n```\n\n## 错误处理\n\n### 常见错误及解决方案\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `AuthenticationError` | API 密钥无效或过期 | 检查并更新 `NOTTE_API_KEY` |\n| `NetworkError` | 网络连接问题 | 检查网络连接和代理设置 |\n| `SessionExpiredError` | 会话超时 | 重新创建会话 |\n| `ActionExecutionError` | 动作执行失败 | 检查元素 ID 和页面状态 |\n\n### 重试机制\n\nNotte SDK 支持自动重试机制，您可以在执行动作时配置：\n\n```python\nsession.execute(\n type=\"click\",\n id=\"B1\",\n raise_on_failure=True # 失败时抛出异常\n)\n```\n\n## 下一步\n\n- 阅读完整的 [SDK 教程](sdk_tutorial.md) 深入了解高级功能\n- 查看 [API 参考文档](api_reference.md) 了解完整的 API 接口\n- 探索 [示例代码库](../examples/) 获取更多实践案例\n\n## 相关资源\n\n- 官方文档：[https://docs.notte.cc](https://docs.notte.cc)\n- API 密钥管理：[https://console.notte.cc](https://console.notte.cc)\n- 搜索演示：[https://search.notte.cc](https://search.notte.cc)\n\n---\n\n\n\n## 包结构分析\n\n### 相关页面\n\n相关主题：[核心模块实现](#core-modules), [项目介绍](#project-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/notte-core/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-core/pyproject.toml)\n- [packages/notte-browser/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/pyproject.toml)\n- [packages/notte-agent/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/pyproject.toml)\n- [packages/notte-sdk/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-sdk/pyproject.toml)\n- [packages/notte-llm/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/pyproject.toml)\n- [packages/notte-mcp/pyproject.toml](https://github.com/nottelabs/notte/blob/main/packages/notte-mcp/pyproject.toml)\n \n\n# 包结构分析\n\n## 概述\n\nNotte 是一个面向互联网原生代理系统（Internet-native Agentic Systems）的软件套件，采用模块化架构设计。整个项目由多个独立的功能包组成，通过清晰的依赖关系组织，形成一套完整的浏览器自动化与LLM交互解决方案。\n\n项目根目录下包含 `packages/` 子目录，其中包含六个核心包：\n\n| 包名 | 版本 | 主要功能 |\n|------|------|----------|\n| notte-core | 0.1.0+ | 核心数据结构和错误处理 |\n| notte-browser | 0.1.0+ | 浏览器控制与页面交互 |\n| notte-agent | 0.1.0+ | Agent执行引擎 |\n| notte-sdk | 0.1.0+ | Python SDK客户端 |\n| notte-llm | 0.1.0+ | LLM提示词和响应处理 |\n| notte-mcp | 0.1.0+ | MCP协议服务器集成 |\n\n## 架构层次\n\n```mermaid\ngraph TD\n subgraph \"notte-llm\"\n LLM_Prompts[\"提示词模板\"]\n LLM_Output[\"输出解析\"]\n end\n \n subgraph \"notte-core\"\n Core_Actions[\"动作定义\"]\n Core_Observation[\"观察数据模型\"]\n Core_Errors[\"错误处理\"]\n end\n \n subgraph \"notte-browser\"\n Browser_Control[\"浏览器控制\"]\n Page_Scraping[\"页面抓取\"]\n end\n \n subgraph \"notte-agent\"\n Agent_Executor[\"Agent执行器\"]\n Agent_Gufo[\"Gufo系统\"]\n end\n \n subgraph \"notte-sdk\"\n SDK_Client[\"客户端封装\"]\n Session_Management[\"会话管理\"]\n end\n \n subgraph \"notte-mcp\"\n MCP_Server[\"MCP服务器\"]\n MCP_Tools[\"工具定义\"]\n end\n \n LLM_Prompts --> Core_Actions\n Core_Actions --> Browser_Control\n Agent_Executor --> Core_Actions\n Agent_Executor --> LLM_Prompts\n SDK_Client --> Session_Management\n SDK_Client --> Agent_Executor\n MCP_Server --> SDK_Client\n MCP_Tools --> MCP_Server\n```\n\n## 各包详细分析\n\n### notte-core\n\n**功能定位**：基础层，提供整个项目的基础数据类型、动作定义、观察结果模型和错误处理机制。\n\n**源码结构**：\n\n```\nnotte-core/src/notte_core/\n├── actions/\n│ └── actions.py # 动作类型定义（goto、click、fill等）\n├── observation/\n│ └── data models # 页面观察数据结构\n├── errors/\n│ └── processing.py # 错误类定义\n└── pruning.py # 树剪枝算法\n```\n\n**核心模块**：\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| actions | actions.py | 定义scrape、goto、click、fill等动作类型 |\n| errors | processing.py | NotteBaseError、InvalidInternalCheckError等 |\n| observation | 数据模型 | 页面元素的结构化表示 |\n\n**关键类型定义**（来源：[packages/notte-core/src/notte_core/actions/actions.py]()）：\n\n- `ScrapeAction`：页面数据抓取，支持指令过滤、选择器范围限定\n- `GotoAction`：页面导航\n- `ClickAction`：元素点击\n- `FillAction`：表单填充\n\n### notte-browser\n\n**功能定位**：浏览器控制层，基于Playwright实现浏览器自动化操作。\n\n**依赖关系**：\n\n```toml\n[project.dependencies]\nplaywright = \">=1.41.0\"\n```\n\n**核心功能**：\n\n| 功能 | 说明 |\n|------|------|\n| 页面导航 | 加载指定URL |\n| 元素交互 | 点击、填表、悬停等 |\n| 内容抓取 | 提取页面文本、图片、链接 |\n| 截图 | 页面可视化反馈 |\n\n### notte-agent\n\n**功能定位**：智能代理层，实现LLM驱动的自动化决策和执行。\n\n**源码结构**：\n\n```\nnotte-agent/src/notte_agent/\n├── gufo/\n│ └── system.md # Gufo系统提示词\n└── 执行器 # Agent核心逻辑\n```\n\n**核心能力**：\n\n| 能力 | 说明 |\n|------|------|\n| 动作规划 | 分析页面状态生成动作序列 |\n| 状态追踪 | 维护会话上下文 |\n| CAPTCHA处理 | 自动识别和处理验证码 |\n| 错误恢复 | 动作执行失败后的重试机制 |\n\n**Agent执行流程**（来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py]()）：\n\n```python\n# 会话创建\nwith client.Session() as session:\n session.execute(type=\"goto\", url=\"https://example.com\")\n obs = session.observe(perception_type='deep')\n # Agent决策循环...\n```\n\n### notte-sdk\n\n**功能定位**：Python客户端SDK，封装所有API调用和会话管理。\n\n**核心组件**：\n\n| 组件 | 文件/类 | 说明 |\n|------|---------|------|\n| NotteClient | client.py | 主客户端类 |\n| Session | sessions.py | 会话上下文管理器 |\n| observe | sessions.py | 页面观察方法 |\n| execute | sessions.py | 动作执行方法 |\n\n**会话管理**（来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py]()）：\n\n```python\nclass Session:\n \"\"\"会话上下文管理器\"\"\"\n \n def __init__(self, cookie_file=None):\n self._cookie_file = cookie_file\n \n def __enter__(self):\n self.start()\n return self\n \n def __exit__(self, exc_type, exc_val, exc_tb):\n self.stop()\n \n def observe(self, perception_type='fast', instructions=None):\n \"\"\"观察页面可用动作\"\"\"\n \n def execute(self, type, **kwargs):\n \"\"\"执行动作\"\"\"\n```\n\n**观察类型**：\n\n| 类型 | 说明 | 适用场景 |\n|------|------|----------|\n| `fast` | 快速感知 | 简单页面、高速查询 |\n| `deep` | 深度感知 | 复杂页面、需要LLM格式化 |\n\n### notte-llm\n\n**功能定位**：LLM交互层，处理提示词模板和响应解析。\n\n**源码结构**：\n\n```\nnotte-llm/src/notte_llm/prompts/\n├── action-listing/ # 动作列表生成\n├── data-extraction/ # 数据提取\n├── document-category/ # 文档分类\n├── extract-without-json-schema/ # 无schema提取\n└── debug-failing-action-exec/ # 调试失败动作\n```\n\n**提示词模板**：\n\n| 模板类型 | 用户文件 | 说明 |\n|----------|----------|------|\n| 动作列表 | user.md | 生成可执行动作序列 |\n| 数据提取 | user.md | 结构化数据抽取 |\n| 文档分类 | user.md | 页面分类（search-results、item、other） |\n| 失败调试 | user.md | 动作执行失败分析 |\n\n**文档分类类别**（来源：[packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md]()）：\n\n| 类别 | 说明 | 示例 |\n|------|------|------|\n| `search-results` | 搜索结果页面 | Google Flights搜索结果 |\n| `item` | 详情项页面 | 食谱详情页、商品页 |\n| `other` | 其他类型 | 首页、导航页 |\n\n### notte-mcp\n\n**功能定位**：Model Context Protocol服务器集成，提供标准化工具接口。\n\n**工具列表**（来源：[packages/notte-mcp/README.md]()）：\n\n| 工具名 | 功能 |\n|--------|------|\n| `notte_start_session` | 启动新的云浏览器会话 |\n| `notte_list_sessions` | 列出所有活动会话 |\n| `notte_stop_session` | 停止当前会话 |\n| `notte_observe` | 观察页面元素和可用动作 |\n| `notte_screenshot` | 页面截图 |\n| `notte_scrape` | 结构化数据提取 |\n| `notte_step` | 执行页面动作 |\n| `notte_operator` | 运行Notte Agent完成任务 |\n\n**使用方式**：\n\n```bash\npip install notte-mcp\nexport NOTTE_API_KEY=\"your-api-key\"\npython -m notte_mcp.server\n```\n\n## 依赖关系\n\n```mermaid\ngraph LR\n SDK[\"notte-sdk\"] --> Agent[\"notte-agent\"]\n SDK --> Browser[\"notte-browser\"]\n Agent --> LLM[\"notte-llm\"]\n Agent --> Core[\"notte-core\"]\n Browser --> Core\n MCP[\"notte-mcp\"] --> SDK\n```\n\n**依赖矩阵**：\n\n| 依赖方 \\ 被依赖方 | notte-core | notte-browser | notte-agent | notte-llm | notte-sdk |\n|------------------|------------|---------------|-------------|-----------|-----------|\n| notte-sdk | ✓ | - | ✓ | - | - |\n| notte-agent | ✓ | - | - | ✓ | - |\n| notte-browser | ✓ | - | - | - | - |\n| notte-mcp | - | - | - | - | ✓ |\n\n## 入口点设计\n\n### SDK入口\n\n```python\nfrom notte_sdk import NotteClient\n\nclient = NotteClient()\n```\n\n### MCP服务器入口\n\n```bash\npython -m notte_mcp.server\n```\n\n### CLI入口\n\n项目提供命令行接口进行快速操作：\n\n```bash\nnotte [options]\n```\n\n## 错误处理体系\n\nNotte采用分层错误处理机制（来源：[packages/notte-core/src/notte_core/errors/processing.py]()）：\n\n| 错误类 | 说明 | 使用场景 |\n|--------|------|----------|\n| `NotteBaseError` | 基类异常 | 所有自定义异常的父类 |\n| `InvalidInternalCheckError` | 内部检查失败 | 代码假设验证失败 |\n| `InvalidA11yTreeType` | 无障碍树类型错误 | 未知a11y树类型 |\n| `InvalidPlaceholderError` | 占位符错误 | Vault凭据获取失败 |\n| `ScrapeFailedError` | 抓取失败 | 数据提取操作异常 |\n\n## 许可证\n\n整个项目采用 **Server Side Public License v1.0 (SSPL-1.0)** 许可证发布。\n\n## 引用信息\n\n如需在学术场合引用本项目，请使用以下BibTeX格式：\n\n```bibtex\n@software{notte2025,\n author = {Pinto, Andrea and Giordano, Lucas and {nottelabs-team}},\n title = {Notte: Software suite for internet-native agentic systems},\n url = {https://github.com/nottelabs/notte},\n year = {2025},\n publisher = {GitHub},\n license = {SSPL-1.0},\n version = {1.4.4},\n}\n\n---\n\n\n\n## 核心模块实现\n\n### 相关页面\n\n相关主题：[包结构分析](#package-structure), [动作执行系统](#action-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [packages/notte-core/src/notte_core/ast.py](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/ast.py)\n \n\n# 核心模块实现\n\n## 1. 模块概述\n\nNotte 项目的核心模块实现涵盖了浏览器自动化代理系统的关键组件，包括动作执行系统、页面观察机制、DOM 树处理、快照管理和凭证安全系统。这些模块共同构成了一个完整的网页自动化框架，使 AI 代理能够精确地与网页元素进行交互。\n\n核心模块的架构设计遵循分层职责原则，将浏览器操作、页面解析、状态管理和安全控制分离到不同的子模块中，每个模块专注于特定的功能域，通过标准化的接口进行通信和数据交换。\n\n## 2. 动作执行系统\n\n### 2.1 动作类型体系\n\n动作执行系统是 Notte 自动化框架的核心，负责定义和管理所有可执行的浏览器操作。系统采用类继承结构，通过基类 `BrowserAction` 定义通用接口，具体动作类实现各自的业务逻辑。\n\n| 动作类型 | 说明 | 参数 |\n|---------|------|------|\n| `GotoAction` | 导航到指定 URL | url: str |\n| `GotoNewTabAction` | 在新标签页中打开 URL | url: str |\n| `CloseTabAction` | 关闭当前标签页 | 无 |\n| `ClickAction` | 点击页面元素 | id: str |\n| `FormFillAction` | 填写表单字段 | 表单字段字典 |\n\n基类 `BrowserAction` 定义了动作执行的通用接口，包括执行消息生成、参数规范和示例数据提供。每个具体动作类都实现了这些抽象方法，确保动作执行的标准化和可预测性。\n\n### 2.2 动作执行流程\n\n动作执行采用统一的调用模式，通过 `execute()` 方法触发。执行流程首先验证动作参数的有效性，然后调用底层的 Playwright 或类似浏览器自动化引擎执行实际操作，最后返回执行结果。\n\n```mermaid\ngraph TD\n A[创建动作实例] --> B[验证参数]\n B --> C{参数有效?}\n C -->|是| D[执行动作]\n C -->|否| E[抛出验证错误]\n D --> F{执行成功?}\n F -->|是| G[返回 ExecutionResult]\n F -->|否| H[记录错误信息]\n G --> I[更新会话状态]\n H --> I\n```\n\n### 2.3 动作参数定义\n\n每个动作类通过 `param` 属性提供参数规范，包括参数名称、数据类型和约束条件。这种设计使动作系统具备自描述能力，便于 LLM 代理理解和使用。\n\n```python\n@property\n@override\ndef param(self) -> ActionParameter | None:\n return ActionParameter(name=\"url\", type=\"str\")\n```\n\n参数规范采用强类型定义，支持字符串、整数、布尔值和复杂对象类型。系统自动进行类型检查和转换，减少运行时错误的发生。\n\n## 3. 页面观察机制\n\n### 3.1 观察类型\n\n页面观察机制负责分析当前页面状态并生成可交互元素列表。系统支持多种观察深度，以适应不同场景的性能和精度需求。\n\n| 观察类型 | 说明 | 适用场景 |\n|---------|------|---------|\n| `fast` | 快速感知模式 | 简单页面感知、查询优化 |\n| `deep` | 深度感知模式 | 复杂页面分析、LLM 动作空间生成 |\n\n快速感知模式使用简化的页面解析逻辑，直接从浏览器的可访问性树中提取元素信息，适用于需要快速响应的场景。深度感知模式则调用 LLM 对页面进行更深入的分析，生成更结构化的交互空间表示。\n\n### 3.2 观察响应结构\n\n观察结果通过 `ObserveResponse` 类型封装，包含当前页面 URL、可交互元素列表和空间描述信息。这种结构化输出便于代理理解页面状态并规划后续动作。\n\n```mermaid\ngraph LR\n A[页面 HTML] --> B[DOM 树解析]\n B --> C[可访问性树生成]\n C --> D{观察类型}\n D -->|fast| E[快速元素提取]\n D -->|deep| F[LLM 结构化分析]\n E --> G[ObserveResponse]\n F --> G\n```\n\n### 3.3 指令过滤机制\n\n观察系统支持通过自然语言指令过滤可交互元素。当提供 `instructions` 参数时，系统会解析指令语义，仅返回符合条件的目标元素，显著减少动作空间大小，提高代理决策效率。\n\n```python\nactions = session.observe(instructions=\"Fill the email input\")\nprint(actions[0].model_dump())\n```\n\n这种设计使开发者能够用自然语言描述交互意图，系统自动完成元素筛选和动作空间构建，降低了自动化脚本的编写难度。\n\n## 4. DOM 树处理\n\n### 4.1 树结构设计\n\nDOM 树模块负责将原始 HTML 文档解析为可编程访问的树形数据结构。树节点包含元素类型、属性、内容和层级关系，支持高效的遍历和查询操作。\n\n```mermaid\ngraph TD\n A[HTML 文档] --> B[解析器]\n B --> C[根节点]\n C --> D[head 节点]\n C --> E[body 节点]\n E --> F[交互元素]\n E --> G[文本节点]\n D --> H[元数据节点]\n```\n\n每个树节点关联唯一的标识符，用于在观察响应中引用具体元素。节点同时记录可访问性属性，如角色、名称和状态，这些属性决定了元素的交互方式。\n\n### 4.2 可访问性树\n\nNotte 使用可访问性树（Accessibility Tree）作为页面元素的主要表示形式，相比原始 DOM 树提供了更丰富的语义信息。可访问性树去除了装饰性元素，保留功能性内容，使代理能够更准确地理解页面结构。\n\n| 属性 | 说明 |\n|------|------|\n| `role` | 元素语义角色（button, link, input 等） |\n| `name` | 元素的可见名称或标签 |\n| `state` | 元素当前状态（checked, disabled 等） |\n| `value` | 输入元素的当前值 |\n\n### 4.3 节点遍历与查询\n\nDOM 树模块提供多种遍历和查询方法，支持按标签名、类名、ID 或 XPath 表达式定位节点。查询结果可进一步用于动作生成或内容提取。\n\n## 5. 快照管理\n\n### 5.1 快照概念\n\n快照（Snapshot）是 Notte 系统记录页面状态的机制，每次页面变化后系统自动生成新的快照。快照包含完整的页面 DOM 结构、可访问性树和元数据，支持历史回溯和状态对比。\n\n快照管理器维护快照的历史记录，通过版本号或时间戳标识不同状态的快照。代理可以查询历史快照以了解页面变化过程，或在执行操作前保存当前状态以便回滚。\n\n### 5.2 快照数据结构\n\n```python\nclass Snapshot:\n id: str\n url: str\n dom_tree: DOMTree\n accessibility_tree: A11yTree\n timestamp: datetime\n metadata: dict\n```\n\n快照数据存储为只读对象，确保历史状态的完整性和一致性。系统支持快照的序列化和反序列化，便于分布式环境下的状态共享。\n\n### 5.3 快照与观察的关系\n\n观察操作基于当前快照执行，每次观察都会创建新的快照记录。观察结果中的元素标识符与快照中的节点一一对应，保证动作执行的精确性。\n\n```mermaid\ngraph LR\n A[执行动作] --> B[页面更新]\n B --> C[生成新快照]\n C --> D[新快照 ID]\n D --> E[观察结果引用新元素]\n```\n\n## 6. 凭证管理系统\n\n### 6.1 凭证架构\n\n凭证管理系统（Vault）负责安全存储和管理敏感信息，如登录凭据、API 密钥和认证令牌。系统采用分层架构，将凭证存储与业务逻辑分离，支持多种后端存储实现。\n\n```mermaid\ngraph TD\n A[代理请求凭证] --> B[Vault 接口]\n B --> C{凭证类型}\n C -->|API 密钥| D[KeyVault]\n C -->|用户名密码| E[CredentialVault]\n C -->|OAuth 令牌| F[TokenVault]\n D --> G[安全存储]\n E --> G\n F --> G\n```\n\n### 6.2 凭证基类设计\n\n```python\nclass NotteBaseError(Exception):\n def __init__(\n self,\n agent_message: str,\n user_message: str,\n dev_message: str,\n ) -> None:\n self.agent_message = agent_message\n self.user_message = user_message\n self.dev_message = dev_message\n```\n\n凭证系统定义统一的异常类型，包含面向代理、用户和开发者的不同错误消息，便于问题的诊断和修复。当凭证操作失败时，系统根据上下文选择合适的错误消息返回。\n\n### 6.3 占位符机制\n\n代理通过占位符（Placeholder）引用凭证，系统在动作执行时自动替换占位符为实际凭证值。这种设计避免敏感信息硬编码在动作参数中，提高系统的安全性。\n\n| 占位符类型 | 说明 |\n|-----------|------|\n| `{vault:api_key:service}` | API 密钥占位符 |\n| `{vault:credential:site}` | 网站登录凭据占位符 |\n| `{vault:token:oauth}` | OAuth 令牌占位符 |\n\n## 7. AST 抽象语法树\n\nAST 模块提供网页内容的结构化表示能力，将无结构的 HTML/CSS/JavaScript 转换为可编程访问的语法树。该模块是高级自动化能力的基础，支持复杂页面结构的理解和操作。\n\n### 7.1 AST 与 DOM 的关系\n\nAST 与 DOM 树既有联系又有区别。DOM 树侧重于文档结构表示，AST 则更关注代码语义的表达。对于 JavaScript 代码，AST 能够解析变量声明、函数调用和控制流结构，为代码级别的自动化操作提供可能。\n\n| 特性 | DOM 树 | AST |\n|------|--------|-----|\n| 关注点 | 文档结构 | 代码语义 |\n| 适用范围 | HTML | HTML/CSS/JS |\n| 遍历方式 | 父子节点 | 语句/表达式 |\n| 用途 | 页面交互 | 代码分析 |\n\n### 7.2 节点类型系统\n\nAST 定义了丰富的节点类型，覆盖 JavaScript 语言的各种语法结构。常见节点类型包括：\n\n- **声明节点**：变量声明、函数声明、类声明\n- **表达式节点**：二元表达式、函数调用、成员访问\n- **控制流节点**：条件语句、循环语句、异常处理\n- **结构节点**：对象字面量、数组字面量\n\n节点类型系统支持 Visitor 模式遍历，代理可以实现自定义的节点处理器来执行特定的代码分析或转换任务。\n\n## 8. 错误处理机制\n\n### 8.1 错误分类体系\n\nNotte 定义了完善的错误分类体系，根据错误来源和性质分为不同类别：\n\n| 错误类型 | 说明 | 典型场景 |\n|---------|------|---------|\n| `InvalidInternalCheckError` | 内部检查失败 | 类型验证、假设检查 |\n| `InvalidA11yTreeType` | 无效的可访问性树类型 | 类型参数错误 |\n| `InvalidPlaceholderError` | 未处理的占位符 | 凭证引用错误 |\n| `ScrapeFailedError` | 数据抓取失败 | 页面解析异常 |\n\n### 8.2 错误消息设计\n\n每个错误类型包含面向不同角色的消息：\n\n- **开发消息（dev_message）**：详细的调试信息和修复建议\n- **代理消息（agent_message）**：代理可理解的错误描述和替代建议\n- **用户消息（user_message）**：面向终端用户的友好提示\n\n这种多层次的消息设计确保错误信息在开发、调试和生产环境中都能发挥作用。\n\n## 9. 模块间协作\n\n### 9.1 会话生命周期\n\n会话（Session）是 Notte 系统的核心概念，贯穿所有模块的协作过程。会话管理器的实现整合了动作执行、页面观察和快照管理功能：\n\n```python\nwith client.Session() as session:\n session.execute(type=\"goto\", url=\"https://example.com\")\n obs = session.observe()\n markdown = session.scrape()\n```\n\n会话提供上下文管理器支持，自动处理资源清理和状态同步。当会话结束时，系统自动保存 Cookie 状态并释放浏览器资源。\n\n### 9.2 数据流总览\n\n```mermaid\ngraph TD\n A[用户请求] --> B[会话管理器]\n B --> C[动作系统]\n C --> D[浏览器引擎]\n D --> E[页面快照]\n E --> F[DOM 树]\n F --> G[可访问性树]\n G --> H[观察服务]\n H --> I[代理决策]\n I --> C\n E --> J[凭证系统]\n J --> C\n```\n\n数据流展示了从用户请求到代理决策的完整链路。各模块通过标准化的数据结构和接口进行交互，保证系统的可扩展性和可维护性。\n\n### 9.3 状态同步机制\n\n会话维护当前的页面快照引用，当页面发生变化时自动更新。观察操作返回的是基于最新快照的元素列表，动作执行后触发新的快照生成，形成闭环的状态同步机制。\n\n## 10. 总结\n\n核心模块实现构成了 Notte 自动化框架的技术基础，通过动作系统、页面观察、DOM 处理、快照管理和凭证安全五大支柱，为 AI 代理提供完整的网页交互能力。这些模块相互协作，形成了一套从页面解析到动作执行的完整工作流，支持复杂场景下的自动化任务。\n\n---\n\n\n\n## Agent实现与生命周期\n\n### 相关页面\n\n相关主题：[结构化输出](#structured-output)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/notte-agent/src/notte_agent/agent.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/agent.py)\n- [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)\n- [packages/notte-agent/src/notte_agent/workflow.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/workflow.py)\n- [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)\n- [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)\n- [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)\n \n\n# Agent实现与生命周期\n\n## 概述\n\nNotte Agent 是一个精确的浏览器自动化代理系统，通过结构化命令与网站进行交互。该系统能够分析网页元素和结构，规划动作序列，并以JSON格式响应动作执行结果和状态评估。Agent架构支持多种底层浏览器自动化引擎（包括Falco和Gufo），并通过统一的接口提供网页浏览、内容提取、表单填写等核心功能。\n\n资料来源：[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)\n\n## 架构设计\n\n### 整体架构\n\nNotte Agent采用分层架构设计，核心组件包括：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| Agent基类 | 定义通用接口和生命周期管理 | `agent.py` |\n| Falco Agent | 基于Falco引擎的浏览器代理实现 | `falco/agent.py` |\n| Gufo Agent | 基于Gufo引擎的浏览器代理实现 | `gufo/agent.py` |\n| ActionRegistry | 动作注册与工具管理 | `falco/prompt.py` |\n| Workflow | 多步骤工作流编排 | `workflow.py` |\n| Conversation | 对话历史管理 | `common/conversation.py` |\n\n资料来源：[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)\n\n### 引擎抽象层\n\n系统通过抽象层支持多种浏览器自动化引擎：\n\n```mermaid\ngraph TD\n A[Agent基类] --> B[Falco Agent]\n A --> C[Gufo Agent]\n B --> D[Falco引擎]\n C --> E[Gufo引擎]\n D --> F[Playwright/CDP]\n E --> G[浏览器实例]\n```\n\nFalco和Gufo作为两种独立的Agent实现，共同继承自基础Agent接口，提供一致的外部行为但使用不同的底层浏览器控制机制。\n\n资料来源：[packages/notte-agent/src/notte_agent/agent.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/agent.py)\n\n## 元素标识系统\n\n### ID编码规范\n\nAgent使用标准化的元素标识系统，每个可交互元素的ID遵循特定编码规则：\n\n```mermaid\ngraph LR\n A[ID格式] --> B[角色前缀]\n A --> C[索引号]\n A --> D[分隔符]\n \n B --> E[I: 输入字段]\n B --> F[B: 按钮]\n B --> G[L: 链接]\n B --> H[F: 图片/图表]\n B --> I[O: 选择选项]\n B --> J[M: 杂项元素]\n```\n\n### 角色前缀对照表\n\n| 前缀 | 角色类型 | 示例元素 |\n|------|----------|----------|\n| `I` | Input | textbox, select, checkbox等输入控件 |\n| `B` | Button | 按钮元素 |\n| `L` | Link | 超链接 |\n| `F` | Figure | 图片和图表元素 |\n| `O` | Option | 下拉选择选项 |\n| `M` | Miscellaneous | 模态框、对话框等杂项元素 |\n\nID的完整格式为`<角色前缀><索引号>`，例如`B1`表示第一个按钮，`I2`表示第二个输入字段。\n\n资料来源：[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)\n\n## 动作系统\n\n### 动作类型\n\nAgent支持多种类型的浏览器自动化动作：\n\n| 动作类型 | 描述 | 适用场景 |\n|----------|------|----------|\n| ClickAction | 点击指定元素 | 按钮点击、链接导航 |\n| FormFillAction | 填写表单字段 | 用户登录、信息录入 |\n| CaptchaSolveAction | 解决验证码 | 自动化验证 |\n| ScrapeAction | 提取页面内容 | 数据采集 |\n| NavigationAction | 页面导航 | URL跳转、前进后退 |\n\n### 表单填写动作格式\n\n```json\n{\n \"type\": \"form_fill\",\n \"value\": {\n \"address1\": \"<地址>\",\n \"city\": \"<城市>\",\n \"state\": \"<州/省份>\"\n }\n}\n```\n\n### CAPTCHA处理规则\n\nAgent对验证码处理有严格的规范：\n\n- **禁止行为**：直接点击验证码元素（按钮、复选框、图片等），或对验证码元素执行\"click\"、\"type\"等动作\n- **正确处理**：检测到验证码（reCAPTCHA、hCaptcha、图像验证等）时，必须使用`CaptchaSolveAction`并指定正确的验证码类型\n- **支持类型**：包括\"我不是机器人\"复选框、图像选择网格、文本验证挑战等\n\n资料来源：[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)\n\n## Agent生命周期\n\n### 创建与启动\n\n使用NotteClient创建Agent实例：\n\n```python\nfrom notte_sdk import NotteClient\n\nnotte = NotteClient()\n\nwith notte.Session(open_viewer=True) as session:\n agent = notte.Agent(session=session)\n agent.start(\n task=\"Summarize the content of the page\",\n url=\"https://www.google.com\"\n )\n```\n\n### 状态管理\n\nAgent具有完整的状态管理机制：\n\n| 状态 | 描述 | 获取方法 |\n|------|------|----------|\n| 运行中 | Agent正在执行任务 | `agent.status()` |\n| 已停止 | Agent已被手动停止 | `agent.stop()` |\n| 已完成 | 任务执行完毕 | 状态检查 |\n| 异常 | 执行过程中出错 | 错误处理 |\n\n### 列表与停止操作\n\n```python\n# 列出所有活跃的Agent\nagents = notte.agents.list()\n\n# 停止指定的Agent\nagent.stop()\n\n# 获取Agent状态\nstatus = agent.status()\n```\n\n资料来源：[packages/notte-sdk/README.md](https://github.com/nottelabs/notte/blob/main/packages/notte-sdk/README.md)\n\n## 工作流编排\n\n### Workflow组件\n\nWorkflow用于编排复杂的多步骤自动化任务，支持：\n\n- 步骤序列定义\n- 条件分支处理\n- 错误恢复机制\n- 结果状态传递\n\n```mermaid\ngraph TD\n A[开始] --> B[步骤1: 页面导航]\n B --> C[步骤2: 元素观察]\n C --> D{条件判断}\n D -->|成功| E[步骤3: 表单填写]\n D -->|失败| F[备用方案]\n E --> G[步骤4: 内容提取]\n F --> G\n G --> H[完成]\n```\n\n### Fallback机制\n\nAgent支持降级（Fallback）机制，当主要实现无法完成任务时自动切换到备用方案：\n\n```python\n# agent_fallback.py 提供了降级策略定义\n```\n\n资料来源：[packages/notte-agent/src/notte_agent/workflow.py](https://github.com/nottelabs/notte/blob/main/packages/notte-agent/src/notte_agent/workflow.py)\n\n## 对话管理\n\n### Conversation组件\n\nConversation模块管理Agent与用户之间的交互历史：\n\n```python\nclass Conversation:\n def __init__(self):\n # 初始化对话历史记录\n pass\n \n def add_message(self, role: str, content: str):\n # 添加消息到历史\n pass\n \n def get_history(self):\n # 获取完整对话历史\n pass\n```\n\n对话历史对于维护Agent状态上下文、支持多轮交互任务至关重要。\n\n资料来源：[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)\n\n## 输入结构规范\n\n### 页面信息格式\n\nAgent接收的页面信息包含以下核心字段：\n\n| 字段 | 描述 | 必需 |\n|------|------|------|\n| Current URL | 当前页面地址 | 是 |\n| Available Tabs | 打开的浏览器标签页列表 | 是 |\n| Interactive Elements | 可交互元素列表 | 是 |\n\n### 元素列表格式\n\n```markdown\n# 主导航菜单\n* `B1`: 提交表单按钮\n* `I1`: 用户名输入框\n* `I2`: 密码输入框\n\n# 内容区域\n* `L1`: 文章链接\n* `F1`: 特色图片\n```\n\n## 响应格式规范\n\n### JSON响应结构\n\nAgent必须始终以有效的JSON格式响应：\n\n```json\n{\n \"action\": {\n \"type\": \"click\",\n \"id\": \"B1\"\n },\n \"reasoning\": \"点击提交按钮以完成表单提交\",\n \"state_assessment\": \"表单已填写完毕，可以提交\"\n}\n```\n\n### 动作执行结果\n\n每个动作执行后返回的结果包含：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| success | boolean | 动作是否成功执行 |\n| error | string | 错误信息（如有） |\n| page_state | object | 执行后页面状态 |\n| captured_data | object | 提取的数据（如适用） |\n\n## 最佳实践\n\n### 元素ID稳定性\n\n> **重要提示**：ID会在每个步骤发生变化，不要假设历史记录中的ID仍然存在或对应相同的元素。每次观察页面时都应重新获取当前的元素ID。\n\n### 动作序列规划\n\n1. 观察页面结构，获取可用元素\n2. 分析任务需求，规划动作序列\n3. 按顺序执行动作，每次观察页面变化\n4. 验证动作结果，必要时调整后续动作\n\n### 错误处理\n\nAgent内置了完善的错误处理机制：\n\n- **InvalidInternalCheckError**：内部检查失败\n- **InvalidA11yTreeType**：无障碍树类型错误\n- **InvalidPlaceholderError**：占位符处理错误\n- **ScrapeFailedError**：内容提取失败\n\n资料来源：[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)\n\n---\n\n\n\n## 结构化输出\n\n### 相关页面\n\n相关主题：[Agent实现与生命周期](#agent-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [packages/notte-llm/src/notte_llm/engine.py](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/src/notte_llm/engine.py)\n- [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)\n- [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)\n- [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)\n- [README.md](https://github.com/nottelabs/notte/blob/main/README.md)\n \n\n# 结构化输出\n\n## 概述\n\n结构化输出是 Notte 框架中用于将网页内容转换为机器可读格式的核心能力。该功能允许用户通过自然语言指令或 JSON Schema 定义，从非结构化的网页文档中提取结构化数据，并将其用于后续的 AI Agent 工作流中。\n\nNotte 的结构化输出系统包含以下几个核心组成部分：\n\n| 组件 | 职责 |\n|------|------|\n| ScrapeAction | 执行抓取的核心动作，支持多种输出格式配置 |\n| LLM 解析引擎 | 负责解析 LLM 返回的文本并提取结构化数据 |\n| Prompt 模板系统 | 提供文档分析和数据提取的指令模板 |\n| Schema 验证 | 支持 JSON Schema 和 Pydantic 模型验证 |\n\n资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1-100]()\n\n## 工作原理\n\n### 流程架构\n\n```mermaid\ngraph TD\n A[用户发起请求] --> B[配置输出格式]\n B --> C{输出类型}\n C -->|JSON Schema| D[使用 extract-json-schema]\n C -->|自然语言| E[使用 extract-without-json-schema]\n C -->|分类| F[使用 document-category]\n D --> G[调用 LLM]\n E --> G\n F --> G\n G --> H[LLM 返回 Markdown/JSON]\n H --> I[解析引擎提取数据]\n I --> J{格式验证}\n J -->|通过| K[返回结构化数据]\n J -->|失败| L[抛出 LLMParsingError]\n```\n\n### 核心机制\n\nNotte 的结构化输出依赖于 LLM 解析引擎的标签解析能力。引擎通过识别特定的 XML 风格标签来提取内容：\n\n```python\n# packages/notte-llm/src/notte_llm/engine.py\nclass SomeParser:\n def parse(self, text: str) -> str:\n # 支持外层标签解析\n if self.outer_tag:\n pattern = f\"<{self.outer_tag}>(.*?)\"\n match = re.search(pattern, content, re.DOTALL)\n \n # 支持内层代码块解析\n if self.inner_tag:\n pattern = f\"```{self.inner_tag}(.*?)```\"\n match = re.search(pattern, content, re.DOTALL)\n```\n\n引擎支持两层解析：\n1. **外层标签解析**：提取 `` 等 XML 标签内的内容\n2. **内层代码块解析**：从 markdown 代码块中提取具体数据\n\n资料来源：[packages/notte-llm/src/notte_llm/engine.py:1-50]()\n\n## 输出格式配置\n\n### 使用 JSON Schema\n\n通过 `response_format` 参数指定 JSON Schema 定义输出结构：\n\n```python\nfrom notte_sdk import NotteClient\n\nclient = NotteClient()\nresponse = client.scrape(\n url=\"https://example.com/blog\",\n response_format={\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\"type\": \"string\"},\n \"content\": {\"type\": \"string\"},\n \"date\": {\"type\": \"string\"}\n }\n }\n)\n```\n\n### 使用 Pydantic 模型\n\n通过 Pydantic BaseModel 定义数据结构，实现类型安全的结构化输出：\n\n```python\nfrom pydantic import BaseModel\nfrom notte_sdk import NotteClient\n\nclass Article(BaseModel):\n title: str\n content: str\n date: str\n\nclient = NotteClient()\nresponse = client.scrape(\n url=\"https://example.com/blog\",\n response_format=Article,\n instructions=\"Extract only the title, date and content of the articles\"\n)\n```\n\n资料来源：[README.md:1-100]()\n\n## ScrapeAction 参数详解\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `instructions` | str \\| None | None | 自然语言提取指令 |\n| `response_format` | dict \\| BaseModel | None | JSON Schema 或 Pydantic 模型 |\n| `only_main_content` | bool | True | 是否仅提取主体内容 |\n| `selector` | str \\| None | None | Playwright 选择器作用域 |\n| `only_images` | bool | False | 是否仅提取图片 |\n| `scrape_links` | bool | True | 是否提取链接 |\n| `scrape_images` | bool | False | 是否提取图片 URL |\n\n### 主要内容提取\n\n当 `only_main_content=True` 时，系统会自动排除导航栏、页脚等非核心内容：\n\n```python\nsession.execute(\n type=\"scrape\",\n only_main_content=True # 排除导航栏和页脚\n)\n```\n\n### 选择器作用域\n\n使用 Playwright 选择器将提取范围限定在特定 DOM 元素内：\n\n```python\nsession.execute(\n type=\"scrape\",\n selector=\"#main-content\" # 仅提取 main-content 内的内容\n)\n```\n\n资料来源：[packages/notte-core/src/notte_core/actions/actions.py:1-100]()\n\n## Prompt 模板系统\n\n### 数据提取模板\n\n数据提取模板定义了从网页文档中提取结构化信息的指导原则：\n\n```\n# 数据提取输出规范\n\n## 部分\n- 逻辑分解网页文档为有意义的章节\n- 描述每个部分的内容，聚焦文本元素\n- 为重复或结构化数据包含子章节\n\n## 部分\n- 使用 Markdown 标题、表格、列表格式化数据\n- 重复数据使用 Markdown 表格展示\n- 所有原始字段必须包含在表格中\n```\n\n资料来源：[packages/notte-llm/src/notte_llm/prompts/data-extraction/user.md:1-50]()\n\n### 文档分类模板\n\nNotte 支持自动识别网页类型，可分类为：\n\n| 分类 | 说明 | 示例 |\n|------|------|------|\n| `search-results` | 搜索结果页面 | Google 航班搜索 |\n| `item` | 单项详情页面 | 商品详情页、菜谱页 |\n| `other` | 其他类型 | 首页、导航页 |\n\n```xml\n\n[文档分类理由的详细分析，包括引用和论证...]\nsearch-results\n\n```\n\n资料来源：[packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md:1-50]()\n\n## 使用示例\n\n### 示例：Nike 产品抓取\n\n完整的结构化输出工作流示例：\n\n```python\nfrom notte_sdk import NotteClient\nfrom pydantic import BaseModel\n\nclass Product(BaseModel):\n name: str\n price: str\n sizes: list[str]\n colors: list[str]\n\nclient = NotteClient()\nwith client.Session() as session:\n session.execute(type=\"goto\", url=\"https://www.nike.com\")\n \n response = session.execute(\n type=\"scrape\",\n response_format=Product,\n instructions=\"Extract product name, price, available sizes and colors\"\n )\n```\n\n### 示例：分类与数据提取结合\n\n```mermaid\ngraph LR\n A[访问网页] --> B[document-category]\n B --> C{分类结果}\n C -->|search-results| D[提取列表数据]\n C -->|item| E[提取详情数据]\n C -->|other| F[提取导航信息]\n D --> G[返回结构化JSON]\n E --> G\n F --> G\n```\n\n## 错误处理\n\n### LLMParsingError\n\n当 LLM 返回格式不符合预期时，引擎会抛出解析错误：\n\n```python\n# packages/notte-llm/src/notte_llm/engine.py\nif self.fail_if_outer_tag:\n raise LLMParsingError(\n f\"No content found within <{self.outer_tag}> tags in the response: {text}\"\n )\n\nif self.fail_if_inner_tag:\n raise LLMParsingError(\n f\"No content found within ```{self.inner_tag}``` blocks in the response: {text}\"\n )\n```\n\n### 常见错误场景\n\n| 错误类型 | 原因 | 解决方案 |\n|----------|------|----------|\n| 缺少外层标签 | LLM 未按要求输出 XML 标签 | 检查 prompt 模板配置 |\n| 缺少内层代码块 | JSON 数据未包裹在代码块中 | 使用 `fail_if_inner_tag=True` |\n| Schema 验证失败 | 返回数据不符合定义的结构 | 检查 JSON Schema 定义 |\n\n## 最佳实践\n\n1. **优先使用 Pydantic 模型**：通过类型提示获得更好的 IDE 支持和验证\n2. **明确的提取指令**：使用自然语言清晰描述需要提取的字段\n3. **合理设置作用域**：使用 `selector` 减少无关内容的干扰\n4. **启用主要内容提取**：设置 `only_main_content=True` 排除噪音\n\n## 相关链接\n\n- [ScrapeAction API 文档](https://github.com/nottelabs/notte/blob/main/packages/notte-core/src/notte_core/actions/actions.py)\n- [LLM 解析引擎](https://github.com/nottelabs/notte/blob/main/packages/notte-llm/src/notte_llm/engine.py)\n- [Prompt 模板目录](https://github.com/nottelabs/notte/tree/main/packages/notte-llm/src/notte_llm/prompts)\n\n---\n\n\n\n## 会话管理系统\n\n### 相关页面\n\n相关主题：[动作执行系统](#action-system), [凭证保险库](#vault-credentials)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/notte-browser/src/notte_browser/session.py](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/src/notte_browser/session.py)\n- [packages/notte-browser/src/notte_browser/controller.py](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/src/notte_browser/controller.py)\n- [packages/notte-browser/src/notte_browser/playwright.py](https://github.com/nottelabs/notte/blob/main/packages/notte-browser/src/notte_browser/playwright.py)\n- [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)\n \n\n# 会话管理系统\n\n## 概述\n\n会话管理系统（Session Management System）是 Notte 项目中负责管理浏览器会话的核心模块。该系统提供了创建、控制、监控和终止浏览器会话的完整生命周期管理功能。Notte 的会话管理基于 Playwright 浏览器自动化框架，支持 Chrome 等多种浏览器的自动化控制。\n\n会话管理系统的主要职责包括：\n\n- 创建和管理浏览器会话实例\n- 处理会话的启动和停止\n- 管理会话级别的 Cookie 和浏览器状态\n- 提供页面观察（Observe）和动作执行（Execute）能力\n- 支持 CDP（Chrome DevTools Protocol）集成\n- 提供隐匿性功能（Stealth），包括代理配置和 CAPTCHA 处理\n\n资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py]()\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[NotteClient] --> B[Session]\n B --> C[BrowserController]\n C --> D[PlaywrightBrowser]\n C --> E[CDPSession]\n B --> F[Cookie管理]\n B --> G[Proxy配置]\n B --> H[观察与执行]\n```\n\nNotte 会话管理系统采用分层架构设计：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 客户端层 | `NotteClient` | SDK 入口，管理会话创建 |\n| 会话层 | `Session` | 会话生命周期管理 |\n| 控制器层 | `BrowserController` | 浏览器控制抽象 |\n| 浏览器层 | `PlaywrightBrowser` / `CDPSession` | 底层浏览器操作 |\n| 存储层 | Cookie/Proxy | 持久化配置 |\n\n资料来源：[packages/notte-browser/src/notte_browser/controller.py]()\n\n### 关键模块\n\n| 模块路径 | 功能描述 |\n|----------|----------|\n| `notte_browser/session.py` | 浏览器会话核心实现 |\n| `notte_browser/controller.py` | 浏览器控制器抽象层 |\n| `notte_browser/playwright.py` | Playwright 浏览器实现 |\n| `notte_integrations/sessions/cdp_session.py` | CDP 协议集成实现 |\n\n## 会话生命周期\n\n### 状态机模型\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: 初始化\n Created --> Starting: session.start()\n Starting --> Running: 浏览器就绪\n Running --> Executing: 执行动作\n Executing --> Running: 动作完成\n Running --> Stopping: session.stop()\n Stopping --> Stopped: 清理完成\n Stopped --> [*]\n \n Running --> Error: 异常发生\n Error --> Stopped: 错误处理\n```\n\n### 创建会话\n\n会话可以通过 `NotteClient` 的 `Session()` 方法创建，支持上下文管理器（with语句）自动管理生命周期。\n\n```python\nfrom notte_sdk import NotteClient\n\nclient = NotteClient()\nwith client.Session() as session:\n session.execute(type=\"goto\", url=\"https://example.com\")\n```\n\n资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:50-60]()\n\n### 会话配置参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `browser_type` | str | \"chrome\" | 浏览器类型（chrome, firefox等） |\n| `open_viewer` | bool | False | 是否打开可视化查看器 |\n| `proxies` | bool | False | 是否启用内置代理 |\n| `solve_captchas` | bool | False | 是否自动解决CAPTCHA |\n| `timeout_minutes` | int | 5 | 会话超时时间（分钟） |\n| `_cookie_file` | str | None | Cookie持久化文件路径 |\n\n## 浏览器控制器\n\n### BrowserController 抽象\n\n`BrowserController` 是浏览器控制的核心抽象类，定义了浏览器操作的统一接口。\n\n资料来源：[packages/notte-browser/src/notte_browser/controller.py]()\n\n### PlaywrightBrowser 实现\n\n`PlaywrightBrowser` 是基于 Playwright 框架的浏览器实现，负责底层的浏览器启动、页面导航、元素交互等操作。\n\n```python\n# Playwright 浏览器核心功能\n- 启动浏览器实例\n- 创建新页面/标签页\n- 执行页面导航\n- 元素定位和交互\n- 截图和页面内容抓取\n```\n\n资料来源：[packages/notte-browser/src/notte_browser/playwright.py]()\n\n### CDP Session 实现\n\nCDP（Chrome DevTools Protocol）会话提供了与 Chrome 浏览器的深层集成能力，适用于高级自动化场景。\n\n```python\nfrom notte_integrations.sessions.cdp_session import CDPSession\n\n# CDP 会话功能\n- 实时网络监控\n- JavaScript 执行拦截\n- 性能分析\n- 控制台日志捕获\n```\n\n资料来源：[packages/notte-integrations/src/notte_integrations/sessions/cdp_session.py]()\n\n## 会话观察与动作执行\n\n### 观察机制（Observe）\n\n观察机制用于获取当前页面的可交互元素列表，生成动作空间（Action Space）。\n\n```python\n# 快速观察（简单页面感知）\nobs = session.observe(perception_type='fast')\n\n# 深度观察（LLM格式化）\nobs = session.observe(perception_type='deep')\n\n# 带指令的观察\nactions = session.observe(instructions=\"填写邮箱输入框\")\n```\n\n| 感知类型 | 特点 | 适用场景 |\n|----------|------|----------|\n| `fast` | 简单页面感知，执行快速 | 简单页面、低延迟需求 |\n| `deep` | LLM调用格式化 | 复杂页面、精确动作空间 |\n\n资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:100-120]()\n\n### 动作执行（Execute）\n\n执行机制支持多种浏览器操作类型：\n\n| 动作类型 | 说明 | 示例 |\n|----------|------|------|\n| `goto` | 导航到指定URL | `type=\"goto\", url=\"...\"` |\n| `goto_new_tab` | 在新标签页打开URL | `type=\"goto_new_tab\", url=\"...\"` |\n| `close_tab` | 关闭当前标签页 | `type=\"close_tab\"` |\n| `scrape` | 抓取页面内容 | `type=\"scrape\", instructions=\"...\"` |\n| `click` | 点击元素 | `type=\"click\", id=\"B1\"` |\n| `fill` | 填写表单 | `type=\"fill\", id=\"I1\", value=\"...\"` |\n\n资料来源：[packages/notte-core/src/notte_core/actions/actions.py]()\n\n## Cookie 管理\n\n### 自动Cookie保存\n\n会话停止时自动保存Cookie到指定文件：\n\n```python\nwith client.Session(_cookie_file=\"cookies.json\") as session:\n # 访问需要登录的网站\n session.execute(type=\"goto\", url=\"https://example.com\")\n# 退出时会话自动保存Cookie\n```\n\n### Cookie持久化机制\n\n```mermaid\nsequenceDiagram\n participant Session\n participant Client\n participant Browser\n participant CookieFile\n \n Session->>Browser: 执行操作\n Session->>Session: session.stop()\n Session->>Browser: get_cookies()\n Browser->>Session: cookies_data\n Session->>CookieFile: create_or_append_cookies_to_file()\n CookieFile->>CookieFile: 保存Cookie\n```\n\n资料来源：[packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:40-48]()\n\n## 隐匿性功能（Stealth）\n\n### 代理配置\n\nNotte 支持内置代理配置，用于增强自动化任务的匿名性：\n\n```python\nwith client.Session(\n proxies=True, # 启用内置代理（默认美国节点）\n browser_type=\"chrome\",\n open_viewer=True\n) as session:\n agent = client.Agent(session=session, max_steps=5)\n response = agent.run(\n task=\"执行任务\",\n url=\"https://example.com\"\n )\n```\n\n### 自定义代理\n\n```python\nfrom notte_sdk import NotteClient, ExternalProxy\n\nclient = NotteClient()\n\nproxy_settings = ExternalProxy(\n server=\"http://your-proxy-server:port\",\n username=\"your-username\",\n password=\"your-password\"\n)\n\nwith client.Session(proxy=proxy_settings) as session:\n pass\n```\n\n### CAPTCHA处理\n\nNotte 内置CAPTCHA自动解决功能：\n\n```python\nwith client.Session(\n solve_captchas=True,\n browser_type=\"chrome\"\n) as session:\n # 系统会自动检测和处理CAPTCHA\n session.execute(type=\"goto\", url=\"https://example.com/recaptcha\")\n```\n\n## API 参考\n\n### NotteClient.Session()\n\n创建新的浏览器会话。\n\n**签名：**\n```python\ndef Session(\n self,\n browser_type: str = \"chrome\",\n open_viewer: bool = False,\n proxies: bool = False,\n solve_captchas: bool = False,\n timeout_minutes: int = 5,\n _cookie_file: str | None = None,\n) -> Session:\n```\n\n**返回值：** `Session` 实例\n\n### Session.execute()\n\n执行浏览器动作。\n\n**签名：**\n```python\ndef execute(\n self,\n type: Literal[\"goto\", \"goto_new_tab\", \"close_tab\", \"scrape\", ...],\n **kwargs\n) -> ExecutionResult:\n```\n\n### Session.observe()\n\n观察当前页面，生成动作空间。\n\n**签名：**\n```python\ndef observe(\n self,\n perception_type: Literal[\"fast\", \"deep\"] = \"fast\",\n instructions: str | None = None,\n **kwargs\n) -> ObserveResponse | list[InteractionActionUnion]:\n```\n\n## 最佳实践\n\n### 1. 使用上下文管理器\n\n始终使用 `with` 语句管理会话，确保资源正确释放：\n\n```python\n# 推荐写法\nwith client.Session() as session:\n session.execute(type=\"goto\", url=\"https://example.com\")\n\n# 不推荐：需要手动调用stop()\nsession = client.Session()\ntry:\n session.start()\n session.execute(type=\"goto\", url=\"https://example.com\")\nfinally:\n session.stop()\n```\n\n### 2. Cookie复用\n\n对于需要登录的网站，使用Cookie持久化避免重复登录：\n\n```python\n# 首次登录并保存Cookie\nwith client.Session(_cookie_file=\"session.json\") as session:\n session.execute(type=\"goto\", url=\"https://example.com/login\")\n # 执行登录操作...\n\n# 后续请求复用Cookie\nwith client.Session(_cookie_file=\"session.json\") as session:\n session.execute(type=\"goto\", url=\"https://example.com/protected\")\n```\n\n### 3. 合理选择感知类型\n\n| 场景 | 推荐感知类型 |\n|------|-------------|\n| 简单表单填写 | `fast` |\n| 复杂页面导航 | `deep` |\n| 批量操作 | `fast` |\n| 精确元素定位 | `deep` |\n\n## 错误处理\n\n### 常见错误\n\n| 错误类型 | 原因 | 解决方案 |\n|----------|------|----------|\n| `ValueError` | 会话未启动 | 确保在 `with` 块内执行操作 |\n| `RuntimeError` | 会话关闭失败 | 检查浏览器进程状态 |\n| 浏览器启动失败 | Playwright未安装 | 运行 `playwright install` |\n\n### 错误恢复\n\n```python\nfrom notte_sdk import NotteClient\n\nclient = NotteClient()\n\ntry:\n with client.Session() as session:\n session.execute(type=\"goto\", url=\"https://example.com\")\nexcept Exception as e:\n # 错误日志记录\n print(f\"会话执行错误: {e}\")\n # 重新创建会话\n```\n\n## 相关文档\n\n- [Agent 系统](../agent/agent-system.md)\n- [动作系统](../actions/actions.md)\n- [观察系统](../observation/observation.md)\n- [MCP 集成](../integrations/mcp-integration.md)\n\n---\n\n\n\n## 动作执行系统\n\n### 相关页面\n\n相关主题：[会话管理系统](#session-management), [核心模块实现](#core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 动作执行系统\n\n## 概述\n\n动作执行系统是 Notte 项目中负责与网页进行交互的核心模块。该系统定义了 Agent 可以执行的所有浏览器操作类型，包括页面导航、表单填充、元素点击、数据提取等。动作执行系统通过结构化的动作定义和统一的执行接口，使 AI Agent 能够以编程方式控制浏览器行为。\n\n系统架构遵循模块化设计原则，核心动作定义位于 `notte_core` 包中，而具体执行逻辑则在 `notte_browser` 和 `notte_agent` 包中实现。SDK 层提供了面向用户的简洁 API，隐藏了底层复杂性。\n\n## 动作类型体系\n\nNotte 的动作系统采用类型字面量（Literal Types）定义所有支持的浏览器操作。每一类动作都有明确的类型标识符、参数定义和执行消息。\n\n### 基础动作类型\n\n| 动作类型 | 描述 | 参数 |\n|---------|------|------|\n| `goto` | 导航到指定 URL | `url: str` |\n| `goto_new_tab` | 在新标签页中打开 URL | `url: str` |\n| `close_tab` | 关闭当前标签页 | 无 |\n| `click` | 点击元素 | `id: str` |\n| `hover` | 悬停在元素上 | `id: str` |\n| `scrape` | 从页面提取数据 | `instructions: str` |\n| `form_fill` | 填写表单 | `value: dict` |\n| `select_option` | 选择下拉选项 | `id: str`, `option: str` |\n| `captcha_solve` | 解决验证码 | `captcha_type: str` |\n| `reload` | 刷新页面 | 无 |\n\n### 导航动作\n\n#### GotoAction\n\n导航到指定 URL 是最基础的浏览器操作。`GotoAction` 接收一个 URL 参数，并将当前页面导航至该地址。\n\n```python\nclass GotoAction(BrowserAction):\n type: Literal[\"goto\"] = \"goto\"\n description: str = \"Navigate to a URL\"\n url: str\n\n def execution_message(self) -> str:\n return f\"Navigated to '{self.url}'\"\n```\n\n**示例：**\n```python\nsession.execute(type=\"goto\", url=\"https://www.example.com\")\n```\n\n#### GotoNewTabAction\n\n在新的浏览器标签页中打开 URL。此动作不影响当前页面的状态。\n\n**示例：**\n```python\nsession.execute(type=\"goto_new_tab\", url=\"https://www.example.com\")\n```\n\n#### CloseTabAction\n\n关闭当前活跃的浏览器标签页。如果关闭的是最后一个标签页，浏览器会话将保持但显示空白页面。\n\n### 交互动作\n\n#### ClickAction\n\n点击页面上的可交互元素，如按钮、链接等。元素通过系统分配的 ID 标识。\n\n#### HoverAction\n\n将鼠标悬停在指定元素上，通常用于触发下拉菜单或显示隐藏内容。\n\n#### SelectOptionAction\n\n从 `