{
"canonical_name": "e2b-dev/E2B",
"compilation_id": "pack_3d707ec7e3664ff2802e38f0469feac1",
"created_at": "2026-05-19T07:25:50.451700+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, 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 `npm i e2b` 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": "npm i e2b",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_ab3ddeefa40e476485f6919752db89f8"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_dc63a90daf91aaaf36b16981cf9f68a3",
"canonical_name": "e2b-dev/E2B",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/e2b-dev/E2B",
"slug": "e2b",
"source_packet_id": "phit_c7049c31b89a4a90b1fabba255e18796",
"source_validation_id": "dval_f21c731f96224a40a2c234a37a3e5491"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 907,
"github_stars": 12212,
"one_liner_en": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"one_liner_zh": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "semantic truth gate rework constraint"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "E2B",
"title_zh": "E2B 能力包",
"visible_tags": [
{
"label_en": "Agent Runtime Infrastructure",
"label_zh": "Agent 运行时基础设施",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-agent-runtime-infrastructure",
"type": "product_domain"
},
{
"label_en": "Sandbox",
"label_zh": "沙箱",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-sandbox",
"type": "user_job"
},
{
"label_en": "Code Execution",
"label_zh": "代码执行",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-code-execution",
"type": "core_capability"
},
{
"label_en": "Cloud Runtime",
"label_zh": "云端运行时",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-cloud-runtime",
"type": "workflow_pattern"
},
{
"label_en": "Isolated Runtime",
"label_zh": "隔离运行",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-isolated-runtime",
"type": "selection_signal"
}
]
},
"packet_id": "phit_c7049c31b89a4a90b1fabba255e18796",
"page_model": {
"artifacts": {
"artifact_slug": "e2b",
"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": "npm i e2b",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/e2b-dev/E2B#readme",
"verified": true
}
],
"display_tags": [
"Agent 运行时基础设施",
"沙箱",
"代码执行",
"云端运行时",
"隔离运行"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Open-source, secure environment with real-world tools for enterprise-grade agents."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_2b063fe8cb80490584e7647332a2c4c6 | https://github.com/e2b-dev/E2B/issues/1331 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：process was not killed when auto paused",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Closed Port Error",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Please add skills to use with any ai agent to use e2b in our project",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: Sandbox create fails from template, but succeeds without template",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：build status polling timed out",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…",
"category": "配置坑",
"evidence": [
"social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8"
],
"severity": "medium",
"suggested_check": "Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。",
"title": "社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8",
"user_impact": "这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Support `AbortSignal` in JS SDK methods for request cancellation",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_f74f7dd596784e88aff40ef33d5b505e | https://github.com/e2b-dev/E2B/issues/1312 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Support `AbortSignal` in JS SDK methods for request cancellation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | 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:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 50,
"forks": 907,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 12212
},
"source_url": "https://github.com/e2b-dev/E2B",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"title": "E2B 能力包",
"trial_prompt": "# E2B - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 E2B 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Open-source, secure environment with real-world tools for enterprise-grade agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：JavaScript/TypeScript SDK。围绕“JavaScript/TypeScript SDK”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：Python SDK。围绕“Python SDK”模拟一次用户任务，不展示安装或运行结果。\n5. page-6：沙箱生命周期管理。围绕“沙箱生命周期管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“JavaScript/TypeScript SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“Python SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-6\n输入：用户提供的“沙箱生命周期管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“JavaScript/TypeScript SDK”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“Python SDK”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-6：Step 5 必须围绕“沙箱生命周期管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/e2b-dev/E2B\n- https://github.com/e2b-dev/E2B#readme\n- README.md\n- package.json\n- packages/js-sdk/src/index.ts\n- packages/js-sdk/src/sandbox/index.ts\n- packages/python-sdk/e2b/sandbox/main.py\n- packages/js-sdk/src/envd/api.ts\n- packages/python-sdk/e2b/envd/api.py\n- packages/js-sdk/package.json\n- packages/js-sdk/src/sandbox/commands/index.ts\n- packages/js-sdk/src/sandbox/filesystem/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 E2B 的核心服务。\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_issue: Support `AbortSignal` in JS SDK methods for request cancellation（https://github.com/e2b-dev/E2B/issues/1312）；github/github_issue: RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox too（https://github.com/e2b-dev/E2B/issues/1331）；github/github_issue: Paused sandbox is not persisting the file changes / addition after secon（https://github.com/e2b-dev/E2B/issues/884）；github/github_issue: (feature request) Run-scoped messaging for multi-sandbox agent workflows（https://github.com/e2b-dev/E2B/issues/1330）；github/github_issue: process was not killed when auto paused（https://github.com/e2b-dev/E2B/issues/1031）；github/github_issue: Docker Build Secrets Support（https://github.com/e2b-dev/E2B/issues/815）；github/github_issue: When using autoPause in sandbox creation, connect overrides this when re（https://github.com/e2b-dev/E2B/issues/875）；github/github_issue: Closed Port Error（https://github.com/e2b-dev/E2B/issues/907）；github/github_issue: AuthenticationError: Unauthorized, please check your credentials. - Inva（https://github.com/e2b-dev/E2B/issues/980）；github/github_issue: Template Build Fails with \"syncing took too long\" Error（https://github.com/e2b-dev/E2B/issues/996）；github/github_issue: build status polling timed out（https://github.com/e2b-dev/E2B/issues/1009）；github/github_issue: [Bug]: Incorrect info about webhooks in docs and dashboard（https://github.com/e2b-dev/E2B/issues/1103）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Support `AbortSignal` in JS SDK methods for request cancellation",
"url": "https://github.com/e2b-dev/E2B/issues/1312"
},
{
"kind": "github_issue",
"source": "github",
"title": "RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox too",
"url": "https://github.com/e2b-dev/E2B/issues/1331"
},
{
"kind": "github_issue",
"source": "github",
"title": "Paused sandbox is not persisting the file changes / addition after secon",
"url": "https://github.com/e2b-dev/E2B/issues/884"
},
{
"kind": "github_issue",
"source": "github",
"title": "(feature request) Run-scoped messaging for multi-sandbox agent workflows",
"url": "https://github.com/e2b-dev/E2B/issues/1330"
},
{
"kind": "github_issue",
"source": "github",
"title": "process was not killed when auto paused",
"url": "https://github.com/e2b-dev/E2B/issues/1031"
},
{
"kind": "github_issue",
"source": "github",
"title": "Docker Build Secrets Support",
"url": "https://github.com/e2b-dev/E2B/issues/815"
},
{
"kind": "github_issue",
"source": "github",
"title": "When using autoPause in sandbox creation, connect overrides this when re",
"url": "https://github.com/e2b-dev/E2B/issues/875"
},
{
"kind": "github_issue",
"source": "github",
"title": "Closed Port Error",
"url": "https://github.com/e2b-dev/E2B/issues/907"
},
{
"kind": "github_issue",
"source": "github",
"title": "AuthenticationError: Unauthorized, please check your credentials. - Inva",
"url": "https://github.com/e2b-dev/E2B/issues/980"
},
{
"kind": "github_issue",
"source": "github",
"title": "Template Build Fails with \"syncing took too long\" Error",
"url": "https://github.com/e2b-dev/E2B/issues/996"
},
{
"kind": "github_issue",
"source": "github",
"title": "build status polling timed out",
"url": "https://github.com/e2b-dev/E2B/issues/1009"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Incorrect info about webhooks in docs and dashboard",
"url": "https://github.com/e2b-dev/E2B/issues/1103"
}
],
"status": "已收录 13 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"effort": "安装已验证",
"forks": 907,
"icon": "code",
"name": "E2B 能力包",
"risk": "可发布",
"slug": "e2b",
"stars": 12212,
"tags": [
"Agent 运行时基础设施",
"沙箱",
"代码执行",
"云端运行时",
"隔离运行"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/e2b-dev/E2B 项目说明书\n\n生成时间：2026-05-17 14:04:55 UTC\n\n## 目录\n\n- [项目介绍](#page-1)\n- [系统架构](#page-2)\n- [JavaScript/TypeScript SDK](#page-3)\n- [Python SDK](#page-4)\n- [CLI 命令行工具](#page-5)\n- [沙箱生命周期管理](#page-6)\n- [文件系统操作](#page-7)\n- [Git 操作与网络配置](#page-8)\n- [模板系统与构建](#page-9)\n- [模板生成器与 Handlebars 模板](#page-10)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n- [packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/template/readycmd.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/readycmd.ts)\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/commands/commandHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/commandHandle.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/python-sdk/e2b/api/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/client.py)\n- [packages/python-sdk/e2b/volume/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/volume/client/client.py)\n- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n \n\n# 项目介绍\n\n## 概述\n\nE2B 是一个开源基础设施项目，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。该项目提供了 JavaScript SDK（Node.js）和 Python SDK 两套开发工具包，使开发者能够轻松启动和控制云端沙箱环境。资料来源：[packages/python-sdk/README.md:1]()\n\nE2B 的核心价值在于为 AI 应用提供了一个安全、可控的代码执行环境。当 AI 模型生成代码后，开发者可以通过 E2B 在隔离的沙箱中运行这些代码，而无需担心安全问题或资源污染。资料来源：[packages/js-sdk/README.md:1]()\n\n## 核心功能\n\n### 安全沙箱环境\n\nE2B 沙箱是基于 Docker 容器技术构建的安全隔离环境。每个沙箱都是完全独立的，拥有自己的文件系统、网络和进程空间。这种隔离确保了运行在沙箱中的代码不会影响主机系统或其他沙箱。资料来源：[packages/js-sdk/src/sandbox/index.ts:1]()\n\n沙箱支持以下关键安全特性：\n\n| 特性 | 说明 | 默认值 |\n|------|------|--------|\n| 互联网访问 | 控制沙箱是否可访问外部网络 | 启用 |\n| 安全模式 | 启用额外的安全限制 | 启用 |\n| 网络隔离 | 自定义网络配置 | 支持 |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n### 多语言 SDK 支持\n\nE2B 提供了两个官方的 SDK 实现：\n\n#### JavaScript SDK\n\nJavaScript SDK 面向 Node.js 环境，支持 TypeScript 和 JavaScript。安装方式如下：\n\n```bash\nnpm i e2b\n```\n\n该 SDK 提供了完整的沙箱控制能力，包括文件系统操作、命令执行、进程管理等。资料来源：[packages/js-sdk/README.md:1]()\n\n#### Python SDK\n\nPython SDK 面向 Python 环境，支持 Python 3.x。安装方式如下：\n\n```bash\npip install e2b\n```\n\n该 SDK 提供了与 JavaScript SDK 类似的功能，并针对 Python 生态进行了优化。资料来源：[packages/python-sdk/README.md:1]()\n\n### 模板系统\n\nE2B 的模板系统允许开发者定义预配置的沙箱环境。模板本质上是一个 Dockerfile，包含了基础镜像、环境变量、依赖安装等配置。资料来源：[packages/js-sdk/src/template/index.ts:1]()\n\n模板支持多种基础镜像来源：\n\n| 方法 | 描述 | 示例 |\n|------|------|------|\n| from_base_image | E2B 默认基础镜像 | e2bdev/base:latest |\n| from_python_image | Python 环境 | python:3 |\n| from_node_image | Node.js 环境 | node:lts |\n| from_bun_image | Bun 环境 | oven/bun:latest |\n| from_debian_image | Debian 环境 | debian:bookworm |\n| from_ubuntu_image | Ubuntu 环境 | ubuntu:24.04 |\n| from_image | 自定义镜像 | 自定义镜像名称 |\n\n资料来源：[packages/js-sdk/src/template/types.ts:1]()\n\n模板构建过程会将所有指令转换为 Dockerfile 格式，包括 RUN、COPY、ENV 等指令。资料来源：[packages/js-sdk/src/template/index.ts:1]()\n\n### 命令执行系统\n\n沙箱支持通过命令执行系统运行任意命令。每个命令执行后会返回标准输出、标准错误和退出码。资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n命令执行的核心特性包括：\n\n```typescript\ninterface CommandResult {\n stdout: string // 标准输出\n stderr: string // 标准错误\n exitCode: number // 退出码，0 表示成功\n error?: string // 错误信息\n}\n```\n\n开发者可以通过 `wait()` 方法异步等待命令执行完成，如果命令以非零退出码结束，将抛出 `CommandExitError` 异常。资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n### 文件系统操作\n\nE2B 提供了强大的文件系统操作能力，支持多种文件格式读取和写入。资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1]()\n\n#### 文件读取格式\n\n| 格式 | 说明 | 适用场景 |\n|------|------|----------|\n| text | 文本格式（默认） | 读取文本文件 |\n| bytes | 字节数组 | 读取二进制文件 |\n| blob | Blob 对象 | Web 环境文件处理 |\n| stream | 可读流 | 大文件流式处理 |\n\n资料来源：[packages/js-sdk/src/volume/index.ts:1]()\n\n#### 文件写入\n\n文件写入支持 gzip 压缩传输，并可通过 `use_octet_stream` 参数选择使用 multipart/form-data 或 application/octet-stream 格式上传。资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:1]()\n\n### 就绪检查命令\n\n模板系统支持设置启动命令和就绪检查命令。就绪检查确保沙箱中的服务完全启动后才标记为可用状态。资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\nE2B 提供了几个内置的就绪检查工具：\n\n| 函数 | 描述 | 实现方式 |\n|------|------|----------|\n| waitForURL | 等待 HTTP URL 返回指定状态码 | curl + grep |\n| waitForProcess | 等待指定名称的进程运行 | pgrep |\n| waitForFile | 等待文件存在 | shell test |\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1]()\n\n### 存储卷管理\n\nE2B 支持持久化存储卷功能，允许沙箱挂载外部存储。这些存储卷可以在沙箱之间共享数据，或用于持久化存储重要数据。资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n存储卷挂载配置示例：\n\n```typescript\nconst sandbox = await Sandbox.create('template-name', {\n volumeMounts: {\n '/data': 'my-volume-name'\n }\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n### MCP 服务器集成\n\nE2B 模板系统支持集成 MCP（Model Context Protocol）服务器，允许在沙箱中运行各种 MCP 服务。资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\n添加 MCP 服务器的示例：\n\n```python\ntemplate.add_mcp_server('exa')\ntemplate.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n```\n\n注意：使用 MCP 服务器需要基础镜像预装了 mcp-gateway。资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\n## 系统架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[开发者应用] --> B[E2B SDK]\n B --> C[API Gateway]\n C --> D[Sandbox Manager]\n D --> E[Docker Container]\n E --> F[envd Agent]\n F --> G[文件系统]\n F --> H[网络栈]\n F --> I[进程管理]\n```\n\n### SDK 分层架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[高级 API]\n B --> C[连接配置]\n C --> D[API Client]\n D --> E[HTTP/REST]\n```\n\n## API 客户端配置\n\nE2B SDK 内部使用 HTTP 客户端与后端 API 通信，支持丰富的配置选项。资料来源：[packages/python-sdk/e2b/api/client/client.py:1]()\n\n| 配置项 | 说明 |\n|--------|------|\n| base_url | API 基础 URL |\n| timeout | 请求超时时间 |\n| verify_ssl | 是否验证 SSL 证书 |\n| follow_redirects | 是否跟随重定向 |\n| cookies | 请求 Cookie |\n| headers | 自定义请求头 |\n| httpx_args | 额外传递给 httpx 的参数 |\n\n资料来源：[packages/python-sdk/e2b/api/client/client.py:1]()\n\n## 命令行工具\n\nE2B 提供了命令行工具用于管理模板。主要命令包括：\n\n### 模板构建\n\n```bash\ne2b template build\n```\n\n该命令会根据指定目录下的 Dockerfile 或模板配置构建沙箱模板。资料来源：[packages/cli/src/commands/template/build.ts:1]()\n\n### 模板创建\n\n```bash\ne2b template create\n```\n\n该命令用于创建新的沙箱模板，支持交互式配置。资料来源：[packages/cli/src/commands/template/create.ts:1]()\n\n## 快速开始\n\n### 1. 安装 SDK\n\n根据使用的编程语言选择对应的 SDK 安装命令：\n\n```bash\n# JavaScript/TypeScript\nnpm i e2b\n\n# Python\npip install e2b\n```\n\n### 2. 获取 API 密钥\n\n1. 访问 [e2b.dev](https://e2b.dev) 注册账号\n2. 在仪表板获取 API 密钥\n3. 设置环境变量\n\n```bash\nexport E2B_API_KEY=e2b_***\n```\n\n### 3. 创建沙箱\n\n**JavaScript 示例：**\n\n```javascript\nimport { Sandbox } from 'e2b'\n\nconst sandbox = await Sandbox.create('python-default')\nconst result = await sandbox.commands.run('echo \"Hello World\"')\nconsole.log(result.stdout)\nawait sandbox.close()\n```\n\n**Python 示例：**\n\n```python\nimport e2b\n\nsandbox = e2b.Sandbox()\nresult = sandbox.commands.run('echo \"Hello World\"')\nprint(result.stdout)\nsandbox.close()\n```\n\n## 环境变量配置\n\n| 变量名 | 说明 | 必需 |\n|--------|------|------|\n| E2B_API_KEY | API 认证密钥 | 是 |\n| E2B_SANDBOX_TIMEOUT | 默认沙箱超时时间（毫秒） | 否 |\n| E2B_DEBUG | 启用调试模式 | 否 |\n\n## 错误处理\n\nE2B SDK 定义了多种错误类型用于处理不同的异常情况：\n\n| 错误类型 | 说明 |\n|----------|------|\n| SandboxError | 沙箱基础错误 |\n| CommandExitError | 命令执行失败（退出码非0） |\n| NotFoundError | 资源未找到 |\n| TemplateError | 模板相关错误 |\n| TimeoutError | 操作超时 |\n\n资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n## 相关资源\n\n- 官方网站：[https://www.e2b.dev/](https://www.e2b.dev/)\n- JavaScript SDK NPM：[https://www.npmjs.com/package/e2b](https://www.npmjs.com/package/e2b)\n- Python SDK PyPI：[https://pypi.org/project/e2b/](https://pypi.org/project/e2b/)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-1), [JavaScript/TypeScript SDK](#page-3), [Python SDK](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/index.ts)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/python-sdk/e2b/sandbox/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/main.py)\n- [packages/js-sdk/src/envd/api.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/api.ts)\n- [packages/python-sdk/e2b/envd/api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/api.py)\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n \n\n# 系统架构\n\n## 概述\n\nE2B 是一个开源基础设施平台，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。系统架构围绕三个核心概念构建：**沙箱（Sandbox）**、**模板（Template）** 和 **API 客户端**。这种设计使得开发者可以通过 SDK 定义可复现的运行时环境，并动态创建和管理隔离的执行实例。\n\n资料来源：[README.md:1-10]()\n\n## 核心组件架构\n\nE2B 系统由以下主要组件构成：\n\n| 组件 | 语言实现 | 职责 |\n|------|---------|------|\n| JavaScript SDK | TypeScript | 提供浏览器和 Node.js 环境下的沙箱管理能力 |\n| Python SDK | Python | 提供 Python 环境下的沙箱管理能力 |\n| CLI 工具 | TypeScript | 提供命令行界面用于模板管理和部署 |\n| API 网关 | 后端服务 | 处理沙箱生命周期请求和状态管理 |\n| envd 服务 | 后端服务 | 在沙箱内部执行命令和文件操作 |\n\n资料来源：[packages/js-sdk/README.md:1-20]()\n\n## SDK 架构\n\n### SDK 导出结构\n\nJavaScript SDK 和 Python SDK 都遵循统一的模块化设计，核心导出包括：\n\n```mermaid\ngraph TD\n A[E2B SDK] --> B[Sandbox 类]\n A --> C[Template 类]\n A --> D[辅助函数]\n B --> B1[启动/停止沙箱]\n B --> B2[文件系统操作]\n B --> B3[进程管理]\n B --> B4[网络访问]\n C --> C1[基础镜像选择]\n C --> C2[依赖安装]\n C --> C3[环境变量配置]\n C --> C4[启动命令设置]\n```\n\n资料来源：[packages/js-sdk/src/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()\n\n### API 客户端架构\n\nSDK 通过统一的 API 客户端与后端服务通信：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `apiKey` | E2B API 密钥 | 环境变量 `E2B_API_KEY` |\n| `baseURL` | API 基础地址 | `https://api.e2b.dev` |\n| `timeout` | 请求超时时间 | 60000ms |\n| `headers` | 自定义请求头 | 包含 SDK 版本、运行时信息 |\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:1-20]()\n\n## 沙箱（Sandbox）架构\n\n### 沙箱生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建中: 调用 sandbox.start()\n 创建中 --> 运行中: envd 服务就绪\n 运行中 --> 暂停中: 调用 sandbox.pause()\n 暂停中 --> 运行中: 调用 sandbox.resume()\n 运行中 --> 停止中: 调用 sandbox.kill() 或超时\n 停止中 --> [*]\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()\n\n### 沙箱创建请求\n\n沙箱创建时，SDK 向后端发送包含完整配置的对象：\n\n```typescript\ninterface NewSandbox {\n templateID: string; // 模板标识符\n metadata?: Record;\n mcp?: Record; // MCP 服务器配置\n envVars?: Record;\n timeout?: number; // 超时时间（秒）\n secure?: boolean; // 安全模式\n allow_internet_access?: boolean;\n network?: NetworkConfig;\n autoPause?: boolean;\n autoResume?: { enabled: boolean };\n volumeMounts?: VolumeMount[];\n}\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-30]()\n\n### 沙箱文件系统\n\n沙箱提供虚拟文件系统，支持以下操作：\n\n| 操作 | JavaScript SDK | Python SDK |\n|------|---------------|------------|\n| 读取文件 | `sandbox.fs.read(path)` | `sandbox.fs.read(path)` |\n| 写入文件 | `sandbox.fs.write(path, content)` | `sandbox.fs.write(path, content)` |\n| 列出目录 | `sandbox.fs.list(path)` | `sandbox.fs.list(path)` |\n| 创建目录 | `sandbox.fs.makeDir(path)` | `sandbox.fs.make_dir(path)` |\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()\n\n## 模板（Template）架构\n\n### 模板构建器模式\n\nTemplate 使用流式构建器（Builder）模式，允许链式调用定义环境：\n\n```mermaid\ngraph LR\n A[Template] --> B[基础镜像]\n B --> C[依赖安装]\n C --> D[环境变量]\n D --> E[启动命令]\n E --> F[TemplateFinal]\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:1-50]()\n\n### 模板配置选项\n\n| 配置方法 | 功能 | 示例 |\n|---------|------|------|\n| `from_image(image)` | 从指定 Docker 镜像创建 | `from_image(\"python:3.11\")` |\n| `from_python_image(version)` | 从 Python 官方镜像创建 | `from_python_image(\"3\")` |\n| `from_node_image(variant)` | 从 Node.js 官方镜像创建 | `from_node_image(\"lts\")` |\n| `from_bun_image(variant)` | 从 Bun 官方镜像创建 | `from_bun_image(\"latest\")` |\n| `from_base_image()` | 从 E2B 基础镜像创建 | - |\n| `run_cmd(cmd)` | 执行 shell 命令 | `run_cmd(\"pip install flask\")` |\n| `copy(src, dest)` | 复制文件到沙箱 | `copy(\"./app\", \"/app\")` |\n| `set_envs(envs)` | 设置环境变量 | `set_envs({\"PORT\": \"3000\"})` |\n| `npm_install()` / `pip_install()` | 安装语言依赖 | - |\n| `apt_install(packages)` | 安装系统包 | `apt_install([\"vim\"])` |\n| `bun_install()` | 使用 Bun 安装依赖 | - |\n| `set_start_cmd(cmd, ready_cmd)` | 设置启动命令 | `set_start_cmd(\"npm start\", waitForURL(\"...\"))` |\n\n资料来源：[packages/js-sdk/src/template/types.ts:50-150]()、[packages/python-sdk/e2b/template/main.py:1-100]()\n\n### 模板构建流程\n\n```mermaid\ngraph TD\n A[定义 Template] --> B[调用 build 方法]\n B --> C[生成 Dockerfile]\n C --> D[上传到 E2B 构建服务]\n D --> E{构建状态}\n E -->|building| F[轮询构建状态]\n F --> E\n E -->|success| G[返回 BuildInfo]\n E -->|error| H[抛出 BuildError]\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts:1-80]()\n\n### 启动就绪检查\n\n系统支持多种就绪检查策略：\n\n| 函数 | 用途 | 实现方式 |\n|------|------|---------|\n| `waitForURL(url, statusCode)` | 等待 HTTP URL 可访问 | curl + grep |\n| `waitForProcess(name)` | 等待进程运行 | pgrep |\n| `waitForFile(path)` | 等待文件存在 | shell test |\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1-50]()\n\n## 环境变量和配置\n\n### SDK 配置\n\n| 环境变量 | 说明 | JavaScript SDK | Python SDK |\n|----------|------|---------------|------------|\n| `E2B_API_KEY` | API 认证密钥 | ✅ | ✅ |\n| `E2B_BASE_URL` | 自定义 API 地址 | 可选 | 可选 |\n| `E2B_TIMEOUT` | 默认超时时间 | 可选 | 可选 |\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:1-20]()\n\n### 沙箱环境变量\n\n沙箱创建时可传入环境变量，格式为键值对映射：\n\n```python\n# Python SDK 示例\nsandbox = Sandbox(\n template=\"my-template\",\n envs={\n \"NODE_ENV\": \"production\",\n \"DATABASE_URL\": \"postgres://...\"\n }\n)\n```\n\n```typescript\n// JavaScript SDK 示例\nconst sandbox = await Sandbox.create({\n template: \"my-template\",\n envs: {\n \"NODE_ENV\": \"production\",\n \"DATABASE_URL\": \"postgres://...\"\n }\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:10-20]()\n\n## MCP 服务器集成\n\nE2B 支持 MCP（Model Context Protocol）服务器集成，允许沙箱访问外部工具和服务：\n\n```mermaid\ngraph LR\n A[MCP 服务器] -->|mcp-gateway| B[沙箱环境]\n B --> C[SDK 调用]\n C --> D[工具执行]\n```\n\n| 方法 | 说明 |\n|------|------|\n| `add_mcp_server(servers)` | 添加 MCP 服务器 |\n| `Template.betaDevContainerPrebuild()` | 预构建 devcontainer |\n| `Template.betaSetDevContainerStart()` | 设置 devcontainer 启动 |\n\n资料来源：[packages/js-sdk/src/template/types.ts:100-130]()\n\n## 部署架构\n\n### 模板构建部署\n\n```mermaid\ngraph LR\n A[本地开发] --> B[定义 Template]\n B --> C[Template.build]\n C --> D[E2B API]\n D --> E[Docker 构建]\n E --> F[镜像仓库]\n F --> G[生产环境]\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:1-50]()\n\n### 构建产物\n\n| 产物 | 说明 |\n|------|------|\n| Docker 镜像 | 存储在 E2B 镜像仓库中 |\n| 模板元数据 | 包含镜像 ID、别名、标签等信息 |\n| 构建日志 | 用于调试构建问题 |\n\n## 安全模型\n\n| 安全特性 | 说明 |\n|---------|------|\n| 隔离执行 | 每个沙箱在独立容器中运行 |\n| 网络控制 | 可配置 `allow_internet_access` |\n| 超时机制 | 可设置沙箱最大运行时间 |\n| 安全模式 | 可启用 `secure: true` 增强隔离 |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:15-25]()\n\n## 依赖安装方法对比\n\n| 包管理器 | JS SDK | Python SDK | 系统级 |\n|---------|--------|-----------|--------|\n| npm/yarn | `npm_install()` | - | - |\n| pip | - | `pip_install()` | - |\n| pip3 | - | `pip_install()` | - |\n| apt-get | `apt_install()` | `apt_install()` | ✅ |\n| bun | `bun_install()` | `bun_install()` | - |\n| 全局安装 | `npm_install(g=True)` | - | - |\n\n资料来源：[packages/js-sdk/src/template/types.ts:80-120]()、[packages/python-sdk/e2b/template/main.py:50-150]()\n\n## 总结\n\nE2B 系统架构采用分层设计，通过统一的 SDK 抽象隐藏底层复杂性：\n\n- **表现层**：JavaScript SDK 和 Python SDK 提供统一的 API\n- **通信层**：API 客户端处理认证、请求序列化和错误处理\n- **服务层**：后端 API 和 envd 服务管理沙箱生命周期\n- **执行层**：Docker 容器提供资源隔离\n\n这种架构使得开发者可以专注于业务逻辑，而无需关心底层基础设施的复杂性。\n\n---\n\n\n\n## JavaScript/TypeScript SDK\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [Python SDK](#page-4), [沙箱生命周期管理](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n- [packages/js-sdk/src/api/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n- [packages/js-sdk/src/api/metadata.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/sandbox/mcp.d.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/mcp.d.ts)\n- [packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [packages/js-sdk/src/envd/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)\n \n\n# JavaScript/TypeScript SDK\n\n## 概述\n\nE2B JavaScript/TypeScript SDK 是一个开源基础设施，允许用户在云端安全隔离的沙箱中运行 AI 生成的代码。该 SDK 提供了启动和控制沙箱的完整能力，支持 Node.js、Browser 和 Deno 运行时环境。\n\n资料来源：[packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n\n### 核心能力\n\n| 功能模块 | 描述 |\n|---------|------|\n| 沙箱管理 | 创建、启动、停止和管理云端沙箱 |\n| 文件系统操作 | 在沙箱中读写文件、执行命令 |\n| 模板系统 | 构建可复用的沙箱模板 |\n| MCP 集成 | 支持 Model Context Protocol 服务器 |\n| API 通信 | 通过 gRPC 和 REST 与后端服务通信 |\n\n资料来源：[packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n\n## 架构设计\n\n### 技术栈\n\n```mermaid\ngraph TD\n A[JavaScript SDK] --> B[@connectrpc/connect-web]\n A --> C[@bufbuild/protobuf]\n A --> D[openapi-fetch]\n \n E[沙箱环境] --> F[envd 服务]\n F --> G[文件系统 API]\n F --> H[命令执行 API]\n F --> I[环境变量 API]\n \n B --> E\n C --> E\n D --> J[REST API]\n```\n\n### 依赖关系\n\nSDK 核心依赖包括：\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| @bufbuild/protobuf | ^2.6.2 | Protocol Buffers 序列化 |\n| @connectrpc/connect | 2.0.0-rc.3 | gRPC-Web 通信协议 |\n| @connectrpc/connect-web | 2.0.0-rc.3 | Web 端 gRPC 支持 |\n| openapi-fetch | ^0.14.1 | REST API 调用 |\n| chalk | ^5.3.0 | 控制台输出格式化 |\n| glob | ^11.1.0 | 文件模式匹配 |\n\n资料来源：[packages/js-sdk/package.json:18-36](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n\n### 运行时支持\n\nSDK 支持多种 JavaScript 运行时环境：\n\n- **Node.js**: 主要支持版本 >=18\n- **Browser**: 支持现代浏览器环境\n- **Deno**: 原生支持 Deno 运行时\n\n资料来源：[packages/js-sdk/src/api/metadata.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n\n## 安装与配置\n\n### 安装方式\n\n```bash\nnpm i e2b\n```\n\n### 环境变量配置\n\n```bash\nE2B_API_KEY=e2b_your_api_key_here\n```\n\nSDK 通过以下方式获取环境变量：\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:17-29](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n\n```typescript\nexport function getEnvVar(name: string) {\n if (runtime === 'deno') {\n return Deno.env.get(name)\n }\n\n if (typeof process === 'undefined') {\n return ''\n }\n\n return process.env[name]\n}\n```\n\n### 默认请求头\n\nSDK 自动附加以下元数据头：\n\n| 头信息 | 来源 | 说明 |\n|-------|------|------|\n| browser | platform.name | 浏览器标识 |\n| lang | js | 语言标识 |\n| lang_version | runtimeVersion | 运行时版本 |\n| package_version | package.json | SDK 版本 |\n| publisher | e2b | 发布者标识 |\n| sdk_runtime | runtime | 运行时类型 |\n| system | platform.os?.family | 操作系统类型 |\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:7-15](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n\n## API 端点\n\n### 沙箱管理接口\n\n#### 创建沙箱\n\n```\nPOST /sandboxes\n```\n\n请求体 schema 定义：\n\n资料来源：[packages/js-sdk/src/api/schema.gen.ts:18-35](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n\n```typescript\ninterface paths {\n \"/sandboxes\": {\n post: {\n parameters: {\n query?: never;\n header?: never;\n path?: never;\n cookie?: never;\n };\n requestBody: {\n content: {\n \"application/json\": components[\"schemas\"][\"NewSandbox\"];\n };\n };\n responses: {\n 201: {\n headers: { [name: string]: unknown };\n content: { \"application/json\": components[\"schemas\"][\"Sandbox\"] };\n };\n };\n };\n };\n}\n```\n\n#### 获取沙箱列表\n\n```\nGET /sandboxes\n```\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| metadata | string | 元数据过滤条件（URL 编码） |\n\n响应示例：\n\n```json\n{\n \"application/json\": components[\"schemas\"][\"ListedSandbox\"][]\n}\n```\n\n资料来源：[packages/js-sdk/src/api/schema.gen.ts:1-25](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n\n### 环境变量接口\n\n#### 获取环境变量\n\n```\nGET /envs\n```\n\n响应结构：\n\n```typescript\ninterface paths {\n \"/envs\": {\n get: {\n parameters: {\n query?: never;\n header?: never;\n path?: never;\n cookie?: never;\n };\n requestBody?: never;\n responses: {\n 200: {\n headers: { [name: string]: unknown };\n content: {\n \"application/json\": components[\"schemas\"][\"EnvVars\"];\n };\n };\n };\n };\n };\n}\n```\n\n资料来源：[packages/js-sdk/src/envd/schema.gen.ts:1-35](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)\n\n### 文件操作接口\n\n#### 下载文件\n\n```\nGET /files\n```\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| path | string | 文件路径（URL 编码） |\n| signature | string | 文件访问签名 |\n| signature_expiration | string | 签名过期时间 |\n| username | string | 用户标识 |\n\n资料来源：[packages/js-sdk/src/envd/schema.gen.ts:50-65](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)\n\n## MCP 服务器支持\n\nSDK 提供完整的 Model Context Protocol (MCP) 服务器类型定义。\n\n### 支持的 MCP 服务器类型\n\n资料来源：[packages/js-sdk/src/sandbox/mcp.d.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/mcp.d.ts)\n\n| 类别 | 服务器 |\n|------|--------|\n| 云服务 | awsCore, awsCdk, awsDiagram, awsDocumentation, awsTerraform, azure, aks |\n| 搜索 | brave, exa, braveSearch |\n| 数据库 | astraDb, chroma, clickhouse, cdataConnectcloud |\n| 开发工具 | circleci, buildkite, camunda, apify |\n| 文档 | astroDocs, atlasDocs, atlan |\n| 安全 | beagleSecurity |\n| 通信 | atlassian, close, audienseInsights |\n\n### MCP 服务器接口定义\n\n```typescript\nexport interface McpServer {\n airtable?: AirtableMCPServer;\n aks?: AzureKubernetesServiceAKS;\n apiGateway?: ApiGateway;\n apify?: ApifyMCPServer;\n arxiv?: ArXivMCPServer;\n astGrep?: AstGrep;\n // ... 更多服务器类型\n}\n```\n\n## 模板系统\n\n### 模板类型定义\n\n资料来源：[packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n\nSDK 提供链式 API 构建模板：\n\n```typescript\ninterface TemplateBuilder {\n // 包管理器安装\n npmInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;\n bunInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;\n yarnInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;\n pnpmInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;\n \n // 系统包安装\n aptInstall(packages: string | string[], options?: { noInstallRecommends?: boolean; fixMissing?: boolean }): TemplateBuilder;\n \n // MCP 服务器\n addMcpServer(servers: string | string[]): TemplateBuilder;\n}\n```\n\n### 模板使用示例\n\n```typescript\n// 使用基础镜像创建模板\nconst template = Template()\n .fromBaseImage()\n .runCmd('echo Hello World E2B!')\n\n// 安装 npm 包\ntemplate.npmInstall('express')\ntemplate.npmInstall(['lodash', 'axios'])\ntemplate.npmInstall('typescript', { dev: true })\n\n// 安装系统包\ntemplate.aptInstall('vim')\ntemplate.aptInstall(['git', 'curl'], { noInstallRecommends: true })\n\n// 添加 MCP 服务器\ntemplate.addMcpServer('exa')\ntemplate.addMcpServer(['brave', 'github'])\n```\n\n## 快速开始\n\n### 基本使用流程\n\n```mermaid\ngraph LR\n A[初始化 SDK] --> B[创建沙箱]\n B --> C[执行命令/操作文件]\n C --> D[获取结果]\n D --> E[停止沙箱]\n```\n\n### 完整示例\n\n资料来源：[packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n\n```typescript\nimport { Sandbox } from 'e2b'\n\n// 创建沙箱实例\nconst sandbox = await Sandbox.create()\n\n// 执行命令\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\n\n// 读写文件\nawait sandbox.filesystem.write('/data/example.txt', 'Hello World')\nconst content = await sandbox.filesystem.read('/data/example.txt')\n\n// 停止沙箱\nawait sandbox.close()\n```\n\n### 环境变量设置\n\n```typescript\n// 设置 API 密钥\nconst E2B_API_KEY = process.env.E2B_API_KEY\n```\n\n## 构建配置\n\n### tsup 配置\n\n资料来源：[packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)\n\n```javascript\nexport default defineConfig({\n minify: false,\n target: ['es2017'],\n sourcemap: true,\n dts: true,\n format: ['esm', 'cjs'], // 同时支持 ESM 和 CommonJS\n clean: true,\n entry: {\n index: './src/index.ts',\n },\n esbuildOptions: (options) => {\n options.legalComments = 'none'\n return options\n },\n})\n```\n\n### 输出格式\n\n| 格式 | 说明 |\n|-----|------|\n| ESM | ECMAScript Module，适合现代构建工具 |\n| CJS | CommonJS，适合 Node.js 直接运行 |\n| TypeScript 声明 | 自动生成 .d.ts 类型文件 |\n\n## SDK 关键词\n\n资料来源：[packages/js-sdk/package.json:26-39](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n\n```\ne2b, ai-agents, agents, ai, code-interpreter, sandbox, code, runtime, vm, nodejs, javascript, typescript\n```\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| NPM 包 | https://www.npmjs.com/package/e2b |\n| Python SDK | https://pypi.org/project/e2b |\n| 官方文档 | https://e2b.dev/docs |\n| 支持渠道 | https://e2b.dev/docs/support |\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [JavaScript/TypeScript SDK](#page-3), [沙箱生命周期管理](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/python-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/package.json)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/envd/process/process_pb2.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/process/process_pb2.py)\n- [packages/python-sdk/example.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/example.py)\n \n\n# Python SDK\n\n## 概述\n\nE2B Python SDK 是一个开源的基础设施库，用于在云端安全隔离的沙箱环境中运行 AI 生成的代码。该 SDK 提供了创建和控制沙箱的能力，支持同步和异步两种操作模式。开发者可以通过简单的 API 调用，在隔离环境中执行命令、运行代码，并与管理服务进行通信。\n\n## 核心架构\n\n### 模块结构\n\nPython SDK 主要由以下几个核心模块组成：\n\n| 模块 | 文件路径 | 功能说明 |\n|------|----------|----------|\n| sandbox_async | `e2b/sandbox_async/main.py` | 异步沙箱实现，支持 `Sandbox` 类的异步方法 |\n| sandbox_sync | `e2b/sandbox_sync/main.py` | 同步沙箱实现，提供阻塞式的沙箱操作 |\n| template | `e2b/template/main.py` | 模板构建器，用于定义沙箱环境配置 |\n| template_async | `e2b/template_async/main.py` | 异步模板管理 |\n| template_sync | `e2b/template_sync/main.py` | 同步模板管理 |\n\n### 运行时架构图\n\n```mermaid\ngraph TD\n A[开发者应用] --> B[Python SDK]\n B --> C{同步/异步模式}\n C -->|同步| D[sandbox_sync]\n C -->|异步| E[sandbox_async]\n D --> F[API 客户端]\n E --> F\n F --> G[E2B API 服务]\n G --> H[沙箱实例]\n H --> I[envd 进程]\n I --> J[隔离文件系统]\n I --> K[网络环境]\n```\n\n## 沙箱管理\n\n### 创建沙箱\n\nPython SDK 提供了两种沙箱创建方式：同步和异步。\n\n#### 异步创建方式\n\n```python\nfrom e2b import Sandbox\nimport asyncio\n\nasync def main():\n sandbox = await Sandbox.create()\n # 执行操作\n await sandbox.close()\n\nasyncio.run(main())\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n\n#### 同步创建方式\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout)\n```\n\n资料来源：[README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n### 沙箱响应模型\n\n沙箱创建成功后会返回 `SandboxCreateResponse` 对象，包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| sandbox_id | str | 沙箱唯一标识符 |\n| sandbox_domain | str | 沙箱域名 |\n| envd_version | str | envd 版本号 |\n| envd_access_token | str | envd 访问令牌 |\n| traffic_access_token | str | 流量访问令牌 |\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n\n### 沙箱生命周期管理\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建中: Sandbox.create()\n 创建中 --> 运行中: 沙箱启动成功\n 运行中 --> 停止中: sandbox.close()\n 停止中 --> 已停止: 资源清理完成\n 创建中 --> 失败: API 错误\n 运行中 --> 失败: 连接断开\n 失败 --> [*]\n 已停止 --> [*]\n```\n\n## 模板系统\n\n### 模板构建器\n\n模板系统允许开发者定义沙箱的初始环境配置，包括基础镜像、系统包安装、环境变量设置等。\n\n#### 基础镜像选择\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image('3') # Python 3\n # 或\n .from_node_image('lts') # Node.js LTS\n # 或\n .from_bun_image('latest') # Bun 最新版\n # 或\n .from_base_image() # E2B 默认基础镜像\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n#### 系统包安装\n\n```python\ntemplate = (\n Template()\n .from_ubuntu_image('24.04')\n .apt_install('vim')\n .apt_install(['git', 'curl', 'wget'])\n)\n```\n\n#### 环境变量配置\n\n```python\ntemplate.set_envs({\n 'NODE_ENV': 'production',\n 'PORT': '8080'\n})\n```\n\n### 启动命令配置\n\n```python\nfrom e2b import Template, wait_for_url, wait_for_port, wait_for_file\n\ntemplate = (\n Template()\n .from_node_image()\n .copy('app.js', '/home/user/')\n .set_start_cmd('node app.js', wait_for_port(3000))\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/readycmd.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/readycmd.py)\n\n### 模板构建\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image('3')\n .copy('requirements.txt', '/home/user/')\n .run_cmd('pip install -r /home/user/requirements.txt')\n)\n\n# 构建带标签的模板\nTemplate.build(template, 'my-python-env:v1.0')\n\n# 构建带多标签的模板\nTemplate.build(template, 'my-python-env', tags=['v1.1.0', 'stable'])\n```\n\n资料来源：[packages/python-sdk/e2b/template_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_sync/main.py)\n\n## 进程与命令执行\n\n### 命令运行\n\n在沙箱中执行命令有两种方式：\n\n#### 使用 commands.run()\n\n```python\nresult = sandbox.commands.run('echo \"Hello from E2B!\"')\nprint(result.stdout) # Hello from E2B!\n```\n\n#### 使用 process 模块\n\n```python\nprocess = sandbox.process.start(\n cmd='python app.py',\n cwd='/home/user'\n)\n```\n\n资料来源：[packages/python-sdk/example.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/example.py)\n\n### 进程通信协议\n\n进程通信使用 protobuf 定义的协议，核心模型包括：\n\n| 消息类型 | 说明 |\n|----------|------|\n| Stdin | 标准输入消息 |\n| Stdout | 标准输出消息 |\n| Stderr | 标准错误输出 |\n| Exit | 进程退出信号 |\n\n资料来源：[packages/python-sdk/e2b/envd/process/process_pb2.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/process/process_pb2.py)\n\n## 错误处理\n\n### 异常类型\n\n| 异常类型 | 说明 |\n|----------|------|\n| SandboxException | 沙箱操作相关错误 |\n| TemplateException | 模板构建相关错误 |\n| handle_api_exception | API 调用错误处理 |\n\n### 版本兼容性检查\n\nSDK 会在创建沙箱时检查 envd 版本：\n\n```python\nif Version(res.parsed.envd_version) < Version(\"0.1.0\"):\n await SandboxApi._cls_kill(res.parsed.sandbox_id)\n raise TemplateException(\n \"You need to update the template to use the new SDK. \"\n \"You can do this by running `e2b template build` in the directory with the template.\"\n )\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n\n## 安装与配置\n\n### 环境要求\n\nPython SDK 需要 Python 3.8 或更高版本。\n\n### 安装命令\n\n```bash\npip install e2b\n```\n\n### 环境变量配置\n\n```bash\nE2B_API_KEY=e2b_***\n```\n\n资料来源：[packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n\n## API 客户端配置\n\n### 连接配置\n\n```python\nfrom e2b import ConnectionConfig\n\nconfig = ConnectionConfig(\n api_key=\"your-api-key\",\n # 其他可选参数\n)\n```\n\n### API 客户端初始化\n\nSDK 内部通过 `get_api_client()` 函数获取 API 客户端：\n\n```python\napi_client = get_api_client(\n config,\n require_api_key=True,\n require_access_token=False,\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/main.py)\n\n## 快速开始示例\n\n```python\nfrom e2b import Sandbox\n\n# 同步使用\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n\n# 异步使用\nimport asyncio\nfrom e2b import Sandbox\n\nasync def main():\n sandbox = await Sandbox.create()\n result = await sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout)\n await sandbox.close()\n\nasyncio.run(main())\n```\n\n资料来源：[README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n## 进阶功能\n\n### MCP 服务器集成\n\n模板支持添加 MCP (Model Context Protocol) 服务器：\n\n```python\ntemplate = (\n Template()\n .from_base_image()\n .add_mcp_server('exa')\n .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### 缓存控制\n\n跳过缓存，强制重新构建：\n\n```python\ntemplate.skip_cache().run_cmd('apt-get update')\n```\n\n### Bun 包管理器\n\n```python\ntemplate = (\n Template()\n .from_bun_image()\n .bun_install('express')\n .bun_install(['lodash', 'axios'])\n .bun_install('tsx', g=True) # 全局安装\n)\n```\n\n## 数据模型\n\n### SandboxDetail\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| sandbox_id | str | 沙箱 ID |\n| started_at | datetime | 启动时间 |\n| state | str | 当前状态 |\n| template_id | str | 模板 ID |\n| alias | str | 模板别名 |\n| allow_internet_access | bool | 是否允许互联网访问 |\n| domain | str | 沙箱域名 |\n| metadata | dict | 元数据 |\n\n资料来源：[packages/python-sdk/e2b/api/client/models/sandbox_detail.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/models/sandbox_detail.py)\n\n### 模板标签\n\n```python\n@dataclass\nclass TemplateTag:\n tag: str # 标签名称\n build_id: str # 构建 ID\n created_at: datetime # 创建时间\n```\n\n资料来源：[packages/python-sdk/e2b/template_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/main.py)\n\n---\n\n\n\n## CLI 命令行工具\n\n### 相关页面\n\n相关主题：[沙箱生命周期管理](#page-6), [模板系统与构建](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n- [packages/cli/src/utils/commands2md.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/utils/commands2md.ts)\n \n\n# CLI 命令行工具\n\n## 概述\n\nE2B CLI 是一个命令行工具，用于构建和管理 E2B 云端沙箱以及沙箱模板。它提供了与 E2B 后端服务交互的便捷方式，使开发者能够通过终端快速创建、配置和部署沙箱环境。\n\nCLI 工具是 E2B SDK 生态系统的重要组成部分，支持通过命令行直接操作沙箱和模板资源，而无需编写额外的代码。\n\n资料来源：[packages/cli/README.md:1-3]()\n\n## 安装方式\n\nE2B CLI 支持多种安装方式，开发者可以根据自己的环境选择最适合的方法。\n\n### 通过 Homebrew 安装（macOS）\n\n```bash\nbrew install e2b\n```\n\n### 通过 NPM 安装\n\n```bash\nnpm install -g @e2b/cli\n```\n\n资料来源：[packages/cli/README.md:10-19]()\n\n## 认证配置\n\n使用 CLI 之前需要进行身份认证。E2B 提供了交互式和非交互式两种认证方式。\n\n### 交互式登录\n\n```bash\ne2b auth login\n```\n\n该命令会打开浏览器窗口引导用户完成认证流程。\n\n### 非交互式认证\n\n在没有浏览器访问权限的环境中，可以设置 `E2B_ACCESS_TOKEN` 环境变量进行认证。访问令牌可在 [e2b.dev/dashboard](https://e2b.dev/dashboard) 的账户设置中的团队选择器下获取。\n\n```bash\nE2B_ACCESS_TOKEN=sk_e2b_... e2b template build\n```\n\n> [!IMPORTANT]\n> 注意 `E2B_ACCESS_TOKEN` 与 `E2B_API_KEY` 的区别。CLI 使用访问令牌，而 SDK 使用 API 密钥。\n\n资料来源：[packages/cli/README.md:21-35]()\n\n## 命令结构\n\nCLI 采用分层命令结构，支持子命令扩展。命令文档生成工具可以将命令定义转换为 Markdown 格式的文档。\n\n### 文档生成机制\n\nCLI 提供了将命令自动转换为文档的功能，支持以下特性：\n\n- 解析命令选项及其默认值\n- 生成子命令文档\n- 清理终端颜色代码\n- 转义 HTML 特殊字符\n\n```typescript\n// 处理子命令\ncommand.commands.forEach((subcommand: any) => {\n const [, subMdContent] = commandToMd(subcommand, fullName)\n mdContent += subMdContent + '\\n\\n'\n})\n```\n\n资料来源：[packages/cli/src/utils/commands2md.ts:40-47]()\n\n## 模板命令\n\n模板是 E2B 沙箱的基础配置，定义了沙箱环境的初始状态。CLI 提供了完整的模板管理能力。\n\n### 创建模板\n\n创建新模板时，CLI 会生成相应的使用示例并支持多语言 SDK 代码片段输出。\n\n```bash\ne2b template create\n```\n\n模板创建完成后会输出成功信息，包含模板 ID 和使用示例：\n\n```\n✅ Building sandbox template {templateID} finished.\n```\n\n示例输出格式支持 Python SDK 和 JS SDK 两种格式，方便不同技术栈的开发者使用。\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-15]()\n\n### 构建模板\n\n构建命令将本地模板配置打包并上传到 E2B 后端进行构建。\n\n```bash\ne2b template build\n```\n\n#### 构建流程状态\n\n构建过程会返回不同的状态，CLI 根据状态码进行相应处理：\n\n| 状态 | 处理方式 |\n|------|----------|\n| `building` | 继续轮询直到构建完成 |\n| `success` | 输出成功信息和示例代码 |\n| `error` | 抛出错误并提示支持渠道 |\n\n```typescript\nswitch (template.status) {\n case 'building':\n // 继续轮询\n break\n case 'success':\n // 输出成功信息和示例\n console.log(`✅ Building sandbox template... finished.`)\n break\n case 'error':\n throw new Error(`❌ Building sandbox template... failed.`)\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:50-80]()\n\n#### Dockerfile 处理\n\nCLI 支持自定义 Dockerfile 构建模板：\n\n```typescript\nexport function getDockerfile(root: string, file?: string) {\n // 检查用户指定的 Dockerfile 是否存在\n if (file) {\n const dockerfilePath = path.join(root, file)\n const dockerfileContent = loadFile(dockerfilePath)\n \n if (dockerfileContent === undefined) {\n throw new Error(`No ${dockerfileRelativePath} found in the root directory.`)\n }\n \n return { dockerfilePath, dockerfileContent, dockerfileRelativePath }\n }\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:95-110]()\n\n### 构建产物格式\n\n成功构建后，CLI 会输出格式化的模板信息：\n\n```typescript\nconsole.log(\n `\\n✅ Building sandbox template ${asFormattedSandboxTemplate({\n templateID: templateName,\n })} finished.\\n${exampleHeader}\\n${exampleUsage}\\n`\n)\n```\n\n输出包含：\n- 模板 ID/别名\n- 使用示例代码\n- Python SDK 示例\n- JS SDK 示例\n\n资料来源：[packages/cli/src/commands/template/create.ts:8-13]()\n\n## 环境变量\n\nCLI 使用以下环境变量进行配置：\n\n| 变量名 | 用途 | 来源 |\n|--------|------|------|\n| `E2B_ACCESS_TOKEN` | CLI 认证令牌 | 用户设置 |\n| `E2B_API_KEY` | SDK API 密钥 | SDK 使用 |\n\n资料来源：[packages/cli/README.md:31-34]()\n\n## 错误处理\n\nCLI 实现了统一的错误处理机制：\n\n### 构建错误\n\n```typescript\ncase 'error':\n throw new Error(\n `\\n❌ Building sandbox template ${asFormattedSandboxTemplate({\n aliases,\n ...template,\n })} failed.\\nCheck the logs above for more details or contact us ${asPrimary(\n '(https://e2b.dev/docs/support)'\n )} to get help.\\n`\n )\n```\n\n### 文件缺失错误\n\n```typescript\nif (dockerfileContent === undefined) {\n throw new Error(\n `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`\n )\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:68-76]()\n\n## 相关资源\n\n- 官方文档：[https://e2b.dev/docs](https://e2b.dev/docs)\n- CLI 文档：[https://e2b.dev/docs/cli](https://e2b.dev/docs)\n- 支持渠道：[https://e2b.dev/docs/support](https://e2b.dev/docs/support)\n\n资料来源：[packages/cli/README.md:36-37]()\n\n---\n\n\n\n## 沙箱生命周期管理\n\n### 相关页面\n\n相关主题：[文件系统操作](#page-7), [Git 操作与网络配置](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/python-sdk/e2b/sandbox/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/sandbox_api.py)\n- [packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py)\n- [packages/js-sdk/src/sandbox/commands/commandHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/commandHandle.ts)\n- [packages/python-sdk/e2b/sandbox/commands/command_handle.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/commands/command_handle.py)\n \n\n# 沙箱生命周期管理\n\n## 概述\n\n沙箱生命周期管理是 E2B 平台提供的核心功能，用于控制沙箱实例在超时、异常或资源管理场景下的行为方式。通过生命周期配置，用户可以定义沙箱在空闲超时后是被终止（kill）还是暂停（pause），以及是否支持自动恢复（auto_resume）功能。 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:15-17]()\n\n## 核心概念\n\n### 生命周期状态\n\nE2B 沙箱支持以下生命周期状态：\n\n| 状态 | 描述 | 可用选项 |\n|------|------|----------|\n| **Running** | 沙箱正在正常运行 | - |\n| **Paused** | 沙箱被暂停，资源冻结 | `on_timeout: \"pause\"` |\n| **Terminated** | 沙箱已被终止销毁 | `on_timeout: \"kill\"` |\n\n### 生命周期配置参数\n\n```typescript\ninterface LifecycleConfig {\n on_timeout: \"kill\" | \"pause\" // 超时行为（默认: \"kill\"）\n auto_resume: boolean // 是否支持自动恢复（默认: false，仅在 pause 模式下有效）\n}\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `on_timeout` | `\"kill\"` \\| `\"pause\"` | `\"kill\"` | 空闲超时后的行为 |\n| `auto_resume` | `boolean` | `false` | 是否在访问时自动恢复暂停的沙箱 |\n\n## 创建沙箱时的生命周期配置\n\n### TypeScript SDK\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create('my-template', {\n lifecycle: {\n on_timeout: \"pause\",\n auto_resume: true\n }\n})\n```\n\n### Python SDK (异步)\n\n```python\nfrom e2b import Sandbox\n\nsandbox = await Sandbox.create(\n template='my-template',\n lifecycle={\"on_timeout\": \"pause\", \"auto_resume\": True}\n)\n```\n\n### Python SDK (同步)\n\n```python\nfrom e2b import Sandbox\n\nsandbox = Sandbox.create(\n template='my-template',\n lifecycle={\"on_timeout\": \"pause\", \"auto_resume\": True}\n)\n```\n\n## 生命周期状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Creating: 创建沙箱\n Creating --> Running: 创建成功\n Creating --> [*]: 创建失败\n \n Running --> Idle: 空闲超时\n Idle --> Running: 恢复操作\n Idle --> Paused: 到达超时阈值\n \n Paused --> Running: auto_resume=true
访问时自动恢复\n Paused --> Terminated: 手动终止\n \n Running --> Terminated: 手动终止
on_timeout=\"kill\"\n Terminated --> [*]\n \n note right of Paused: 仅当 lifecycle.on_timeout=\"pause\" 时触发\n note right of Idle: 平台内部状态\n```\n\n## 自动暂停与恢复机制\n\n### 工作原理\n\n1. **自动暂停**：当沙箱在配置的超时时间内没有活跃操作时，平台自动将沙箱状态从 `Running` 转换为 `Paused`，释放底层计算资源 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:25]()\n\n2. **自动恢复**：当 `auto_resume` 设置为 `true` 时，对暂停状态沙箱的任何访问操作（如运行命令、读取文件）会自动触发沙箱恢复 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:25]()\n\n```mermaid\nsequenceDiagram\n participant Client\n participant SandboxAPI\n participant SandboxInstance\n \n Client->>SandboxAPI: 创建沙箱 (lifecycle: auto_resume=true)\n SandboxAPI->>SandboxInstance: 启动沙箱\n \n Note over SandboxInstance: 空闲超时检测\n SandboxInstance-->>SandboxInstance: 自动暂停\n \n Client->>SandboxAPI: 访问暂停的沙箱\n SandboxAPI->>SandboxInstance: 自动恢复\n SandboxInstance-->>Client: 沙箱就绪\n \n Note over SandboxInstance: 恢复后继续使用\n```\n\n### 配置约束\n\n| 场景 | `on_timeout` 要求 | 说明 |\n|------|-------------------|------|\n| 启用自动恢复 | 必须为 `\"pause\"` | auto_resume 仅在 pause 模式下生效 |\n| 立即终止 | 设置为 `\"kill\"` | 超时后立即销毁沙箱（默认行为） |\n\n## CLI 沙箱信息查看\n\n通过 E2B CLI 可以查看沙箱的生命周期状态：\n\n```bash\ne2b sandbox info \n```\n\n返回的沙箱信息包含以下生命周期相关字段：\n\n| 字段 | 说明 |\n|------|------|\n| `state` | 当前状态（Running、Paused 等） |\n| `lifecycle` | 生命周期配置 |\n| `sandboxId` | 沙箱唯一标识 |\n\n## 最佳实践\n\n### 1. 开发调试场景\n\n使用默认的 `kill` 模式，简化资源管理：\n\n```typescript\nconst sandbox = await Sandbox.create('debug-template', {\n lifecycle: {\n on_timeout: \"kill\" // 默认值\n }\n})\n```\n\n### 2. 长时任务场景\n\n使用暂停模式配合自动恢复，避免重复创建开销：\n\n```typescript\nconst sandbox = await Sandbox.create('worker-template', {\n lifecycle: {\n on_timeout: \"pause\",\n auto_resume: true\n },\n timeoutMs: 30 * 60 * 1000 // 30分钟活跃超时\n})\n```\n\n### 3. 成本敏感场景\n\n使用 `kill` 模式确保资源及时释放：\n\n```python\nsandbox = await Sandbox.create(\n template='batch-template',\n lifecycle={\"on_timeout\": \"kill\"}\n)\n```\n\n## 相关源码\n\n- **JavaScript SDK**: `packages/js-sdk/src/sandbox/sandboxApi.ts` - 沙箱 API 调用实现\n- **Python SDK**: `packages/python-sdk/e2b/sandbox/sandbox_api.py` - 沙箱 API 封装\n- **Python API Client**: `packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py` - 创建沙箱 API 请求\n- **命令处理**: `packages/js-sdk/src/sandbox/commands/commandHandle.ts` - 命令执行与生命周期交互\n- **Python 命令处理**: `packages/python-sdk/e2b/sandbox/commands/command_handle.py` - Python 命令执行\n\n---\n\n\n\n## 文件系统操作\n\n### 相关页面\n\n相关主题：[沙箱生命周期管理](#page-6), [Git 操作与网络配置](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)\n- [packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)\n- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)\n \n\n# 文件系统操作\n\nE2B 的文件系统操作模块提供了在沙箱（Sandbox）环境中读写文件和目录的完整能力。通过这个模块，用户可以在沙箱内执行文件浏览、读取、写入、监控等操作，是 E2B 沙箱与外部系统交互的核心途径之一。\n\n---\n\n## 模块概述\n\nE2B 的文件系统操作横跨两个主要 SDK：\n\n- **JavaScript/TypeScript SDK (`@e2b`)**：基于异步 API 设计，支持流式读取和多种返回格式\n- **Python SDK (`e2b`)**：提供同步和异步两套接口，与 Python 生态深度集成\n\n文件系统操作主要通过 `Sandbox` 实例的 `.filesystem` 属性访问，也可通过 Volume API 操作持久化存储卷中的文件。\n\n---\n\n## 核心功能\n\n### 读取文件\n\n文件系统模块支持以多种格式读取文件内容，适用于不同的使用场景。\n\n#### JavaScript SDK\n\n`Sandbox.filesystem.read()` 方法支持以下返回格式：\n\n| 格式 | 返回类型 | 说明 |\n|------|----------|------|\n| `text` | `string` | 文件内容作为文本（默认） |\n| `bytes` | `Uint8Array` | 文件内容作为字节数组 |\n| `blob` | `Blob` | Web API Blob 对象 |\n| `stream` | `ReadableStream` | 流式读取，适合大文件 |\n\n```typescript\nconst sandbox = await Sandbox.create('base')\n\n// 读取为文本\nconst content = await sandbox.filesystem.read('/path/to/file.txt', {\n format: 'text'\n})\n\n// 读取为字节数组\nconst bytes = await sandbox.filesystem.read('/path/to/file.bin', {\n format: 'bytes'\n})\n\n// 流式读取大文件\nconst stream = await sandbox.filesystem.read('/path/to/large.zip', {\n format: 'stream'\n})\n```\n\n**可选参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `user` | `string` | 以指定用户身份读取（需 envd 0.5.0+） |\n| `gzip` | `boolean` | 启用 gzip 解压缩传输 |\n\n资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts](packages/js-sdk/src/sandbox/filesystem/index.ts)\n\n#### Python SDK\n\n```python\nsandbox = await sb.Sandbox.create()\n\n# 读取为文本\ncontent = await sandbox.filesystem.read('/path/to/file.txt')\n\n# 读取为字节\ncontent = await sandbox.filesystem.read('/path/to/file.txt', format='bytes')\n```\n\n---\n\n### 写入文件\n\n写入操作支持批量写入多个文件，并自动创建必要的父目录。\n\n#### JavaScript SDK\n\n```typescript\nawait sandbox.filesystem.write([\n { path: '/app/config.json', data: JSON.stringify(config) },\n { path: '/app/index.js', data: 'console.log(\"hello\")' }\n])\n```\n\n#### Python SDK\n\n```python\nawait sandbox.filesystem.write([\n { 'path': '/app/config.json', 'data': json.dumps(config) },\n { path: '/app/index.js', 'data': 'console.log(\"hello\")' }\n])\n```\n\n**写入选项参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `user` | `string` | 以指定用户身份写入 |\n| `request_timeout` | `int` | 请求超时时间（毫秒） |\n| `gzip` | `boolean` | 使用 gzip 压缩传输 |\n| `use_octet_stream` | `boolean` | 使用 `application/octet-stream` 代替 `multipart/form-data`（需 envd 0.5.7+） |\n\n```python\n# 使用 octet-stream 方式上传，适合大文件\nawait sandbox.filesystem.write(\n [{ 'path': '/data/model.bin', 'data': model_bytes }],\n use_octet_stream=True,\n gzip=True\n)\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)\n\n---\n\n### 目录监控\n\nJavaScript SDK 提供了 `WatchHandle` 类用于监控目录变化。\n\n```typescript\nconst watchHandle = await sandbox.filesystem.watchDir('/app', (event) => {\n console.log(`${event.type}: ${event.name}`)\n})\n\n// 停止监控\nawait watchHandle.stop()\n```\n\n**事件类型：**\n\n| 事件类型 | 说明 |\n|----------|------|\n| `create` | 文件或目录被创建 |\n| `write` | 文件被写入 |\n| `remove` | 文件或目录被删除 |\n| `rename` | 文件或目录被重命名 |\n\n```typescript\n// 完整的监控示例\nconst watchHandle = await sandbox.filesystem.watchDir(\n '/workspace',\n (event) => {\n console.log(`文件 ${event.name} 发生 ${event.type} 事件`)\n },\n (error) => {\n console.error('监控出错:', error)\n }\n)\n```\n\n`WatchHandle` 类的结构：\n\n```typescript\nclass WatchHandle {\n // 停止监控\n async stop(): void\n \n // 内部事件迭代器\n private async *iterateEvents(): AsyncIterator\n \n // 内部事件处理器\n private async handleEvents(): Promise\n}\n```\n\n资料来源：[packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)\n\n---\n\n### Volume 文件操作\n\nVolume API 提供了对持久化存储卷的文件操作能力，接口设计与普通文件系统类似。\n\n```typescript\nconst volume = await Volume.get(volumeId)\n\n// 读取 Volume 中的文件\nconst content = await volume.readFile('/data/file.txt')\n\n// 读取为不同格式\nconst bytes = await volume.readFile('/data/archive.zip', {\n format: 'bytes'\n})\n```\n\n**Volume API 读取格式：**\n\n| 格式 | 返回类型 | 说明 |\n|------|----------|------|\n| `text` | `string` | 文件内容作为文本（默认） |\n| `bytes` | `Uint8Array` | 文件内容作为字节数组 |\n| `blob` | `Blob` | Web API Blob 对象 |\n| `stream` | `ReadableStream` | 流式读取 |\n\n```typescript\n// 流式读取大文件\nconst stream = await volume.readFile('/data/dataset.csv', {\n format: 'stream',\n requestTimeoutMs: 120000\n})\n\n// 处理流式数据\nfor await (const chunk of stream) {\n processChunk(chunk)\n}\n```\n\n**Volume 读取选项：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `requestTimeoutMs` | `number` | 请求超时时间（毫秒） |\n| `signal` | `AbortSignal` | 可中止的请求信号 |\n\n资料来源：[packages/js-sdk/src/volume/index.ts](packages/js-sdk/src/volume/index.ts)\n\n---\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Sandbox.filesystem]\n A --> C[Volume.readFile]\n \n B --> D[FilesystemConnection]\n C --> E[VolumeConnection]\n \n D --> F[envd API]\n E --> G[Volume API]\n \n F --> H[沙箱 envd 服务]\n G --> I[E2B Volume 服务]\n \n H --> J[沙箱文件系统]\n I --> K[持久化存储]\n```\n\n### 文件读取流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant FS as Filesystem\n participant API as envd API\n participant Envd as envd 服务\n\n User->>FS: read(path, opts)\n FS->>API: GET /files?path=...\n API->>Envd: 请求文件内容\n Envd-->>API: 文件内容\n API-->>FS: 返回响应\n FS-->>User: 根据格式返回结果\n```\n\n---\n\n## 版本兼容性\n\n### 用户身份参数\n\nenvd 版本对 `user` 参数的支持：\n\n```typescript\n// envd < 0.5.0：使用默认用户\n// envd >= 0.5.0：可指定 user 参数\n\nlet user = opts?.user\nif (\n user == undefined &&\n compareVersions(this.envdApi.version, ENVD_DEFAULT_USER) < 0\n) {\n user = defaultUsername // 回退到默认用户\n}\n```\n\n### Octet Stream 上传\n\n`use_octet_stream` 选项需要特定 envd 版本支持：\n\n```python\nsupports_octet_stream = self._envd_version >= ENVD_OCTET_STREAM_UPLOAD\nuse_octet_stream = use_octet_stream and supports_octet_stream\n```\n\n如果不支持，会自动回退到 `multipart/form-data` 方式上传。\n\n资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)\n\n---\n\n## 错误处理\n\n### 常见错误类型\n\n| 错误类型 | 说明 | 处理方式 |\n|----------|------|----------|\n| `NotFoundError` | 文件或目录不存在 | 检查路径是否正确 |\n| `TimeoutError` | 请求超时 | 增加 `requestTimeoutMs` |\n| `PermissionError` | 权限不足 | 使用 `user` 参数指定有权限的用户 |\n| `NetworkError` | 网络连接问题 | 检查网络和沙箱状态 |\n\n### 404 错误处理\n\n```typescript\nconst res = await volume.api.GET('/volumecontent/{volumeID}/file', {...})\n\nif (res.response.status === 404) {\n throw new NotFoundError(`Path ${path} not found`)\n}\n```\n\n---\n\n## 最佳实践\n\n### 1. 选择合适的读取格式\n\n```typescript\n// 小文件：使用 text 或 bytes\nconst config = await sandbox.filesystem.read('/app/config.json', {\n format: 'text'\n})\n\n// 大文件：使用 stream 避免内存溢出\nconst stream = await sandbox.filesystem.read('/data/large-file.bin', {\n format: 'stream'\n})\n\n// Web 环境：使用 blob\nconst blob = await sandbox.filesystem.read('/assets/bundle.js', {\n format: 'blob'\n})\n```\n\n### 2. 批量写入优化\n\n```python\n# 好的做法：批量写入减少请求次数\nawait sandbox.filesystem.write([\n { 'path': f'/app/file{i}.txt', 'data': content }\n for i in range(100)\n])\n\n# 避免：逐个写入（性能差）\nfor i in range(100):\n await sandbox.filesystem.write([\n { 'path': f'/app/file{i}.txt', 'data': content }\n ])\n```\n\n### 3. 启用 gzip 压缩\n\n```typescript\n// 对于文本内容，启用 gzip 可显著减少传输时间\nconst content = await sandbox.filesystem.read('/app/large.json', {\n gzip: true\n})\n```\n\n### 4. 目录监控资源管理\n\n```typescript\n// 务必在不需要时停止监控\nconst watchHandle = await sandbox.filesystem.watchDir('/workspace', onEvent)\n\n// 使用完毕后清理\ntry {\n await doWork()\n} finally {\n await watchHandle.stop()\n}\n```\n\n---\n\n## 总结\n\nE2B 的文件系统操作模块提供了完整、一致且易用的文件操作接口。核心特点包括：\n\n- **多格式支持**：text、bytes、blob、stream 满足不同场景需求\n- **流式处理**：对大文件提供流式读取，避免内存压力\n- **压缩传输**：可选 gzip 压缩优化网络传输\n- **目录监控**：支持实时监控文件系统变化事件\n- **Volume 集成**：可操作持久化存储卷中的文件\n- **跨 SDK 一致**：JavaScript 和 Python SDK 提供相似的接口设计\n\n---\n\n\n\n## Git 操作与网络配置\n\n### 相关页面\n\n相关主题：[沙箱生命周期管理](#page-6), [文件系统操作](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/git/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/git/index.ts)\n- [packages/python-sdk/e2b/sandbox_sync/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/git.py)\n- [packages/python-sdk/e2b/sandbox_async/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/git.py)\n- [packages/python-sdk/e2b/sandbox/_git/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/__init__.py)\n- [packages/python-sdk/e2b/sandbox/_git/args.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/args.py)\n- [packages/js-sdk/src/sandbox/network.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/network.ts)\n- [packages/python-sdk/e2b/sandbox/network.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/network.py)\n \n\n# Git 操作与网络配置\n\n## 概述\n\nE2B 平台提供了在沙箱环境中执行 Git 操作和配置网络设置的完整功能。Git 操作主要通过模板构建器（Template Builder）在沙箱镜像构建阶段执行，支持克隆仓库、指定分支、浅克隆等常用功能。网络配置则允许用户在创建沙箱时控制网络访问权限和 MCP 网关的网络设置。\n\n## Git 操作\n\n### 模板中的 Git 克隆\n\n在 E2B 中，Git 操作主要通过 `Template` 类的 `git_clone` 方法实现。该方法在镜像构建阶段执行，而非沙箱运行时执行，这意味着所有 Git 相关的准备工作需要在构建模板时完成。\n\n```mermaid\ngraph TD\n A[创建 Template 实例] --> B[选择基础镜像]\n B --> C[调用 git_clone 方法]\n C --> D[执行 git clone 命令]\n D --> E[构建并部署模板]\n E --> F[沙箱启动时已包含克隆的仓库]\n```\n\n### Python SDK 中的 Git 操作\n\n#### git_clone 方法签名\n\n```python\ndef git_clone(\n self,\n url: str,\n path: Optional[Union[str, Path]] = None,\n branch: Optional[str] = None,\n depth: Optional[int] = None,\n user: Optional[str] = None,\n) -> \"TemplateBuilder\":\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| url | str | 是 | Git 仓库的完整 URL 地址 |\n| path | str 或 Path | 否 | 克隆目标路径 |\n| branch | str | 否 | 指定分支名称 |\n| depth | int | 否 | 浅克隆的提交历史深度 |\n| user | str | 否 | 执行命令的用户身份 |\n\n#### 使用示例\n\n```python\nfrom e2b import Template\n\n# 基本克隆\ntemplate = (\n Template()\n .from_python_image(\"3.11\")\n .git_clone(\"https://github.com/user/repo.git\", \"/app/repo\")\n)\n\n# 指定分支的浅克隆\ntemplate = (\n Template()\n .from_node_image(\"24\")\n .git_clone(\n \"https://github.com/user/repo.git\",\n path=\"/workspace/project\",\n branch=\"main\",\n depth=1\n )\n)\n\n# 以 root 用户身份克隆\ntemplate = (\n Template()\n .from_base_image()\n .git_clone(\n \"https://github.com/user/repo.git\",\n \"/root/repo\",\n user=\"root\"\n )\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### JavaScript SDK 中的 Git 操作\n\n#### gitClone 方法签名\n\n```typescript\ngitClone(\n url: string,\n path?: string,\n options?: {\n branch?: string;\n depth?: number;\n },\n user?: string\n): TemplateBuilder\n```\n\n#### 使用示例\n\n```typescript\nimport { Template } from 'e2b'\n\n// 基本克隆\nconst template = Template()\n .fromPythonImage('3')\n .gitClone('https://github.com/user/repo.git', '/app/repo')\n\n// 指定分支和深度的克隆\nconst template = Template()\n .fromNodeImage('24')\n .gitClone(\n 'https://github.com/user/repo.git',\n '/workspace/project',\n { branch: 'main', depth: 1 }\n )\n```\n\n### git clone 命令生成\n\n底层实现通过构建 `git clone` 命令行参数来实现功能：\n\n```python\nargs = [\"git\", \"clone\", url]\nif branch:\n args.append(f\"--branch {branch}\")\n args.append(\"--single-branch\")\nif depth:\n args.append(f\"--depth {depth}\")\nif path:\n args.append(str(path))\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n## 网络配置\n\n### 沙箱网络访问控制\n\nE2B 沙箱支持网络访问权限控制，用户可以在创建沙箱时通过 `allow_internet_access` 参数决定是否允许沙箱访问外部网络。\n\n```mermaid\ngraph LR\n A[沙箱创建请求] --> B{allow_internet_access}\n B -->|True| C[允许访问外部网络]\n B -->|False| D[禁止访问外部网络]\n C --> E[可访问互联网资源]\n D --> F[仅限内部网络通信]\n```\n\n### Python SDK 网络配置\n\n#### 同步沙箱创建\n\n```python\nwith Sandbox.create(\n allow_internet_access=True, # 允许网络访问\n network=True # 启用网络功能\n) as sandbox:\n result = sandbox.commands.run(\"curl https://api.example.com\")\n```\n\n#### 异步沙箱创建\n\n```python\nsandbox = await Sandbox.create(\n allow_internet_access=True,\n network=True,\n lifecycle=Lifecycle.KEEP_ALIVE\n)\n```\n\n#### 网络参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| allow_internet_access | bool | None | 控制沙箱是否可访问外部网络 |\n| network | bool | True | 启用沙箱网络功能 |\n\n资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n\n### JavaScript SDK 网络配置\n\n```typescript\nconst sandbox = await Sandbox.create({\n allowInternetAccess: true,\n network: true,\n})\n```\n\n## MCP 网关网络配置\n\n### MCP 服务器添加\n\n在 Python SDK 中，可以使用 `add_mcp_server` 方法为模板添加 MCP（Model Context Protocol）服务器。该功能要求基础镜像已预装 mcp-gateway。\n\n```python\ndef add_mcp_server(self, servers: Union[str, List[str]]) -> \"TemplateBuilder\":\n```\n\n#### 使用示例\n\n```python\ntemplate = (\n Template()\n .from_base_image() # 需使用包含 mcp-gateway 的镜像\n .add_mcp_server('exa')\n .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n)\n```\n\n#### 前置条件检查\n\n```python\nif self._template._base_template != \"mcp-gateway\":\n raise BuildException(\n \"Devcontainers can only used in the devcontainer base template\"\n )\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### MCP 网关启动配置\n\n在沙箱运行时，MCP 网关通过特定命令启动，并使用环境变量进行认证配置：\n\n```python\ntoken = str(uuid.uuid4())\nsandbox._mcp_token = token\n\nres = sandbox.commands.run(\n f\"mcp-gateway --config {shlex.quote(json.dumps(mcp))}\",\n user=\"root\",\n envs={\"GATEWAY_ACCESS_TOKEN\": token},\n)\n```\n\n| 配置项 | 说明 |\n|--------|------|\n| mcp-gateway | MCP 网关可执行文件 |\n| --config | MCP 服务器配置 JSON |\n| GATEWAY_ACCESS_TOKEN | 网关访问认证令牌 |\n\n资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n\n## 环境变量配置\n\n### Git 操作环境配置\n\n在执行 Git 操作时，可以通过 `set_envs` 方法设置环境变量：\n\n```python\ntemplate.set_envs({\n 'GIT_TERMINAL_PROMPT': '0', # 禁用 Git 交互提示\n 'GIT_SSL_NO_VERIFY': 'true' # 禁用 SSL 验证（测试环境）\n})\n```\n\n#### set_envs 方法实现\n\n```python\ninstruction: Instruction = {\n \"type\": InstructionType.ENV,\n \"args\": [item for key, value in envs.items() for item in [key, value]],\n \"force\": self._template._force_next_layer,\n \"forceUpload\": None,\n}\nself._template._instructions.append(instruction)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n## 缓存控制\n\n### 跳过缓存构建\n\n对于需要强制重新构建的指令，可以使用 `skip_cache` 方法：\n\n```python\ntemplate.skip_cache().run_cmd('apt-get update')\n```\n\n此方法会设置 `_force_next_layer = True`，确保后续指令及其所有层都重新构建，忽略任何缓存层。\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n## 完整使用示例\n\n### Python SDK 综合示例\n\n```python\nfrom e2b import Template, Sandbox\n\n# 创建包含 Git 仓库和 MCP 服务器的模板\ntemplate = (\n Template()\n .from_python_image(\"3.11\")\n .git_clone(\n \"https://github.com/user/private-repo.git\",\n \"/app/repo\",\n branch=\"main\",\n depth=1\n )\n .set_envs({\n \"GIT_TERMINAL_PROMPT\": \"0\",\n \"APP_ENV\": \"production\"\n })\n .run_cmd(\"pip install -r requirements.txt\")\n)\n\n# 构建模板\nbuild_info = template.build(\"my-app-template:v1.0\")\n\n# 使用模板创建沙箱并启用网络\nwith Sandbox.create(\n template=build_info.template_id,\n allow_internet_access=True,\n metadata={\"user\": \"developer\"}\n) as sandbox:\n # 执行应用程序\n result = sandbox.commands.run(\"python /app/repo/main.py\")\n print(result.stdout)\n```\n\n### JavaScript SDK 综合示例\n\n```typescript\nimport { Template, Sandbox } from 'e2b'\n\n// 创建模板\nconst template = Template()\n .fromNodeImage('24')\n .gitClone(\n 'https://github.com/user/repo.git',\n '/workspace/project',\n { branch: 'main', depth: 1 }\n )\n .setEnvs({ NODE_ENV: 'production' })\n .runCmd('npm install')\n\n// 构建并部署\nconst buildInfo = await Template.build(template, 'my-node-app:v1.0')\n\n// 创建沙箱\nconst sandbox = await Sandbox.create({\n template: buildInfo.template.id,\n allowInternetAccess: true,\n})\n\nconst result = await sandbox.commands.run('node /workspace/project/index.js')\nconsole.log(result.stdout)\n```\n\n## 架构流程图\n\n```mermaid\ngraph TD\n subgraph 模板构建阶段\n A[定义 Template] --> B[选择基础镜像]\n B --> C[执行 Git 克隆]\n C --> D[设置环境变量]\n D --> E[安装依赖]\n E --> F[构建 Docker 镜像]\n F --> G[部署到 E2B]\n end\n \n subgraph 沙箱运行阶段\n G --> H[创建沙箱实例]\n H --> I{allow_internet_access}\n I -->|True| J[启用网络访问]\n I -->|False| K[禁用网络访问]\n J --> L[运行用户代码]\n K --> L\n L --> M[执行命令]\n M --> N[访问网络资源]\n end\n \n subgraph MCP 网关配置\n O[配置 MCP 服务器]\n O --> P[启动 mcp-gateway]\n P --> Q[设置访问令牌]\n Q --> R[MCP 服务器就绪]\n end\n \n L -.-> R\n```\n\n## 注意事项\n\n1. **Git 凭证管理**：对于私有仓库，需要在模板构建前配置适当的认证方式\n2. **网络隔离**：生产环境中应根据需求谨慎设置 `allow_internet_access`\n3. **基础镜像要求**：使用 MCP 功能需要选择包含 mcp-gateway 的基础镜像\n4. **缓存策略**：开发调试时可使用 `skip_cache()` 强制重新构建\n\n---\n\n\n\n## 模板系统与构建\n\n### 相关页面\n\n相关主题：[模板生成器与 Handlebars 模板](#page-10), [CLI 命令行工具](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/python-sdk/e2b/template/types.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/types.py)\n- [packages/python-sdk/e2b/template_async/build_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/build_api.py)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n \n\n# 模板系统与构建\n\n## 概述\n\nE2B 的模板系统是一套用于构建沙箱运行环境的配置框架，允许开发者通过声明式 API 定义沙箱的基础镜像、系统依赖、应用依赖、环境变量以及启动命令。该系统支持 JavaScript SDK 和 Python SDK，提供了统一且直观的接口来创建可复用的沙箱模板。\n\n模板系统的核心是 `TemplateBuilder` 类，它采用链式调用模式（Builder Pattern），允许开发者通过 fluent API 逐步配置模板的各个组成部分。构建完成的模板可以通过 SDK 的 `build` 方法部署到 E2B 基础设施上，生成可供沙箱使用的镜像。\n\n## 核心概念\n\n### 模板状态机\n\n模板在构建过程中经历以下状态转换：\n\n```mermaid\nstateDiagram-v2\n [*] --> TemplateBuilder: 初始化\n TemplateBuilder --> TemplateBuilder: 添加指令\n TemplateBuilder --> TemplateBuilder: 安装依赖\n TemplateBuilder --> TemplateFinal: set_start_cmd()\n TemplateFinal --> [*]: Template.build()\n \n state TemplateBuilder {\n [*] --> withInstructions\n withInstructions --> withInstructions\n }\n \n state TemplateFinal {\n [*] --> readyToBuild\n }\n```\n\n- **TemplateBuilder**：模板构建器状态，可以添加各种构建指令\n- **TemplateFinal**：模板最终状态，仅在设置启动命令后达到，此时模板才能被构建\n\n资料来源：[packages/js-sdk/src/template/types.ts:50-55]()\n\n### 基础镜像选择\n\nE2B 支持多种基础镜像类型，通过不同的方法选择：\n\n| 方法 | 描述 | 用途 |\n|------|------|------|\n| `fromBaseImage()` | 使用默认基础镜像 | 创建通用沙箱环境 |\n| `fromPythonImage(tag?)` | 使用 Python 镜像 | Python 应用开发 |\n| `fromImage(name)` | 使用指定镜像 | 自定义镜像需求 |\n\n资料来源：[packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n\n## JavaScript SDK 模板 API\n\n### 安装包管理器\n\n#### Bun 安装\n\n```typescript\n// 安装单个包\ntemplate.bunInstall('express')\n\n// 安装多个包\ntemplate.bunInstall(['lodash', 'axios'])\n\n// 全局安装\ntemplate.bunInstall('typescript', { g: true })\n\n// 安装为开发依赖\ntemplate.bunInstall('tsx', { dev: true })\n\n// 从 package.json 安装\ntemplate.bunInstall()\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:100-115]()\n\n#### npm 安装\n\n```typescript\n// 安装单个包\ntemplate.npmInstall('express')\n\n// 安装多个包\ntemplate.npmInstall(['lodash', 'axios'])\n\n// 全局安装\ntemplate.npmInstall('typescript', { g: true })\n```\n\n#### pip 安装\n\n```typescript\n// 安装单个包\ntemplate.pipInstall('flask')\n\n// 安装多个包\ntemplate.pipInstall(['flask', 'requests'])\n\n// 安装 requirements.txt\ntemplate.pipInstall()\n```\n\n### 系统包安装\n\n#### apt-get 安装\n\n```typescript\n// 安装单个系统包\ntemplate.aptInstall('vim')\n\n// 安装多个系统包\ntemplate.aptInstall(['git', 'curl', 'wget'])\n\n// 不安装推荐包\ntemplate.aptInstall(['vim'], { noInstallRecommends: true })\n\n// 修复缺失依赖\ntemplate.aptInstall(['vim'], { fixMissing: true })\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:125-140]()\n\n### 环境变量配置\n\n```typescript\n// 设置环境变量\ntemplate.setEnvs({\n NODE_ENV: 'production',\n PORT: '8080',\n DATABASE_URL: 'postgres://localhost:5432/mydb'\n})\n```\n\n环境变量通过 `InstructionType.ENV` 指令类型添加到指令列表中。\n\n### MCP 服务器集成\n\nE2B 支持通过 mcp-gateway 集成 MCP (Model Context Protocol) 服务器：\n\n```typescript\n// 添加单个 MCP 服务器\ntemplate.addMcpServer('exa')\n\n// 添加多个 MCP 服务器\ntemplate.addMcpServer(['brave', 'firecrawl', 'duckduckgo'])\n```\n\n**注意**：使用 MCP 服务器功能需要基础镜像预装 mcp-gateway（如 `mcp-gateway` 镜像）。\n\n资料来源：[packages/js-sdk/src/template/types.ts:150-160]()\n\n### Devcontainer 支持\n\n```typescript\n// 克隆仓库并启动 devcontainer\ntemplate\n .gitClone('https://myrepo.com/project.git', '/my-devcontainer')\n .startDevcontainer('/my-devcontainer')\n\n// 预构建并启动 devcontainer\ntemplate\n .gitClone('https://myrepo.com/project.git', '/my-devcontainer')\n .betaDevContainerPrebuild('/my-devcontainer')\n .betaSetDevContainerStart('/my-devcontainer')\n```\n\n### 设置启动命令\n\n```typescript\n// 使用字符串命令\ntemplate.setStartCmd(\n 'python app.py',\n 'curl -f http://localhost:3000/health'\n)\n\n// 使用 ReadyCmd 对象\ntemplate.setStartCmd(\n 'python app.py',\n {\n cmd: 'curl -f http://localhost:3000/health',\n timeout: 30000\n }\n)\n```\n\n`setStartCmd` 方法将模板状态从 `TemplateBuilder` 转换为 `TemplateFinal`，此时模板才能被构建。\n\n## Python SDK 模板 API\n\n### 初始化与构建\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_base_image()\n .run_cmd(\"echo Hello World E2B!\")\n)\n\n# 构建模板\nbuild_info = Template.build(template, \"my-template:v1.0\")\n```\n\n### 安装依赖\n\n#### Bun 安装\n\n```python\n# 安装单个包\ntemplate.bun_install('express')\n\n# 安装多个包\ntemplate.bun_install(['lodash', 'axios'])\n\n# 全局安装\ntemplate.bun_install('typescript', g=True)\n\n# 开发依赖\ntemplate.bun_install('tsx', dev=True)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:150-175]()\n\n#### apt-get 安装\n\n```python\n# 安装系统包\ntemplate.apt_install('vim')\ntemplate.apt_install(['git', 'curl', 'wget'])\n\n# 不安装推荐包\ntemplate.apt_install('vim', no_install_recommends=True)\n\n# 修复缺失依赖\ntemplate.apt_install('vim', fix_missing=True)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:190-215]()\n\n### MCP 服务器\n\n```python\n# 添加 MCP 服务器\ntemplate.add_mcp_server('exa')\ntemplate.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n```\n\n## 构建选项\n\n### JavaScript SDK\n\n```typescript\ninterface BuildOptions {\n // 镜像标签（可选）\n tags?: string[]\n}\n```\n\n```typescript\n// 简单命名\nawait Template.build(template, 'my-template:v1.0')\n\n// 多标签构建\nawait Template.build(template, 'my-template', { \n tags: ['v1.0', 'stable', 'latest'] \n})\n```\n\n### Python SDK\n\n```python\n# 异步构建\nimport asyncio\nfrom e2b import Template, AsyncTemplate\n\nasync def build_template():\n template = Template().from_base_image().run_cmd(\"echo test\")\n build_info = await AsyncTemplate.build(template, \"my-template:v1.0\")\n```\n\n## Docker 注册表配置\n\nE2B 支持配置通用 Docker 注册表认证：\n\n```typescript\ntype GenericDockerRegistry = {\n type: 'registry'\n username: string\n password: string\n}\n```\n\n此配置允许访问私有 Docker 镜像仓库。\n\n## CLI 命令行工具\n\nE2B CLI 提供了模板构建的命令行接口：\n\n```bash\n# 构建模板\ne2b template build\n\n# 初始化新模板\ne2b template init\n```\n\nCLI 使用 `getDockerfile` 函数获取 Dockerfile 内容：\n\n```typescript\nexport function getDockerfile(root: string, file?: string) {\n // 检查用户指定的 Dockerfile\n if (file) {\n const dockerfilePath = path.join(root, file)\n // ...\n }\n // 否则使用默认 Dockerfile\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:55-80]()\n\n## 模板构建流程\n\n```mermaid\ngraph TD\n A[创建 Template] --> B[选择基础镜像]\n B --> C[安装系统包]\n C --> D[安装应用包]\n D --> E[设置环境变量]\n E --> F[配置 MCP 服务器]\n F --> G[设置启动命令]\n G --> H[调用 build 方法]\n H --> I[上传到 E2B 云端]\n I --> J[构建 Docker 镜像]\n J --> K[模板就绪]\n```\n\n## 缓存控制\n\n模板系统支持选择性跳过缓存层：\n\n```typescript\n// 跳过后续构建指令的缓存\ntemplate.skip_cache().runCmd('apt-get update')\n```\n\n这对于需要强制重新执行某些关键指令的场景非常有用。\n\n## 错误处理\n\n### SDK 版本兼容性检查\n\n```typescript\nif (compareVersions(res.data!.envdVersion, '0.1.0') < 0) {\n await this.kill(res.data!.sandboxID, opts)\n throw new TemplateError(\n 'You need to update the template to use the new SDK.'\n )\n}\n```\n\n### CLI 构建错误\n\n```typescript\ncase 'error':\n throw new Error(\n `Building sandbox template failed.\\n` +\n `Check the logs above for more details or contact us (https://e2b.dev/docs/support)`\n )\n```\n\n## 最佳实践\n\n1. **使用特定版本标签**：为模板指定明确的版本号，避免使用 `latest` 造成不一致\n2. **合理拆分依赖**：将系统依赖和应用依赖分开，便于缓存复用\n3. **使用 skip_cache 策略**：仅在必要时跳过缓存，减少构建时间\n4. **健康检查命令**：为 `set_start_cmd` 配置合理的 ready_cmd，确保沙箱真正就绪\n5. **环境变量管理**：使用环境变量而非硬编码配置值，提高模板可复用性\n\n## 相关资源\n\n- [JavaScript SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [Python SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [CLI 工具文档](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n\n---\n\n\n\n## 模板生成器与 Handlebars 模板\n\n### 相关页面\n\n相关主题：[模板系统与构建](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/commands/template/generators/handlebars.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/generators/handlebars.ts)\n- [packages/cli/src/commands/template/generators/template-generator.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/generators/template-generator.ts)\n- [packages/cli/src/templates/python-template.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/python-template.hbs)\n- [packages/cli/src/templates/typescript-template.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/typescript-template.hbs)\n- [packages/cli/src/templates/python-build-sync.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/python-build-sync.hbs)\n \n\n# 模板生成器与 Handlebars 模板\n\n## 概述\n\nE2B 的模板生成器（Template Generator）是 CLI 工具中负责将 `Template` 类实例转换为可部署模板的核心组件。它使用 [Handlebars](https://handlebarsjs.com/) 模板引擎来生成各种格式的输出，包括 Dockerfile、启动脚本和使用示例代码。\n\n模板生成器的主要职责包括：\n\n- 将 `TemplateClass` 实例序列化为中间 JSON 格式\n- 通过 Handlebars 模板引擎处理数据并生成最终输出\n- 支持多种编程语言的代码示例生成（Python SDK、JS/TS SDK）\n- 提供自定义 Handlebars helpers 用于模板逻辑处理\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[TemplateClass 实例] --> B[transformTemplateData]\n B --> C[TemplateJSON + HandlebarStep]\n C --> D[Handlebars 模板引擎]\n D --> E[最终输出]\n \n F[Handlebars 类] --> G[eq helper]\n F --> H[escapeQuotes helper]\n F --> I[escapeDoubleQuotes helper]\n \n J[模板类型] --> K[python-template.hbs]\n J --> L[typescript-template.hbs]\n J --> M[python-build-sync.hbs]\n```\n\n### 处理流程\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 命令\n participant TG as TemplateGenerator\n participant HB as Handlebars\n participant TPL as .hbs 模板文件\n \n CLI->>TG: 调用生成方法\n TG->>TG: transformTemplateData()\n TG->>TG: 解析 Template.toJSON()\n TG->>HB: 编译模板\n HB->>TPL: 读取 .hbs 文件\n TPL-->>HB: 模板内容\n HB-->>TG: 渲染结果\n TG-->>CLI: 返回生成的代码\n```\n\n## Handlebars 核心实现\n\n### Handlebars 类\n\n`Handlebars` 类是 Handlebars 库的封装，提供了模板编译和自定义 helpers 的支持。\n\n**文件位置**: `packages/cli/src/commands/template/generators/handlebars.ts`\n\n#### 类结构\n\n```typescript\nclass Handlebars {\n private handlebars: typeof HandlebarsLib\n\n constructor() {\n const handlebars = HandlebarsLib.create()\n handlebars.registerHelper('eq', function (a: any, b: any, options: any) {\n if (a === b) {\n return options.fn(this)\n }\n return ''\n })\n\n handlebars.registerHelper('escapeQuotes', function (str) {\n return str ? str.replace(/'/g, \"\\\\'\") : str\n })\n\n handlebars.registerHelper('escapeDoubleQuotes', function (str) {\n return str ? str.replace(/\"/g, '\\\\\"') : str\n })\n\n this.handlebars = handlebars\n }\n\n compile(template: string) {\n return this.handlebars.compile(template)\n }\n}\n```\n\n资料来源：[packages/cli/src/commands/template/generators/handlebars.ts:1-40]()\n\n### 自定义 Helpers\n\n模板系统提供了三个核心自定义 helpers：\n\n| Helper 名称 | 功能 | 示例 |\n|------------|------|------|\n| `eq` | 相等比较，类似于 `{{#if (eq a b)}}` | `{{#eq type \"RUN\"}}...{{/eq}}` |\n| `escapeQuotes` | 转义单引号 | `{{escapeQuotes str}}` |\n| `escapeDoubleQuotes` | 转义双引号 | `{{escapeDoubleQuotes str}}` |\n\n#### eq Helper\n\n用于在模板中进行条件渲染，类似于 Handlebars 内置的 `if` 但支持相等判断：\n\n```handlebars\n{{#eq instruction.type \"RUN\"}}\nRUN {{instruction.args.[0]}}\n{{/eq}}\n```\n\n#### escapeQuotes Helper\n\n用于转义字符串中的单引号，防止在 JavaScript/TypeScript 代码中产生语法错误：\n\n```handlebars\n{{escapeQuotes command}}\n```\n\n#### escapeDoubleQuotes Helper\n\n用于转义字符串中的双引号，防止在需要双引号包裹的上下文中产生语法错误：\n\n```handlebars\n{{escapeDoubleQuotes filename}}\n```\n\n## 数据转换层\n\n### transformTemplateData 函数\n\n该函数负责将 `TemplateClass` 实例转换为 Handlebars 模板可用的数据格式。\n\n**签名**:\n\n```typescript\nexport async function transformTemplateData(\n template: TemplateClass\n): Promise\n```\n\n#### HandlebarStep 接口\n\n```typescript\ninterface HandlebarStep {\n type: string\n args?: string[]\n envVars?: Record\n src?: string\n dest?: string\n}\n```\n\n#### 转换过程\n\n1. 调用 `Template.toJSON(template, false)` 获取 JSON 表示\n2. 解析 JSON 为 `TemplateWithStepsJSON` 类型\n3. 返回包含 steps 数组的合并结果\n\n资料来源：[packages/cli/src/commands/template/generators/handlebars.ts:59-74]()\n\n## 模板类型\n\n### 模板文件列表\n\nE2B CLI 提供了多种预定义的 Handlebars 模板：\n\n| 模板文件 | 用途 |\n|---------|------|\n| `python-template.hbs` | Python SDK 使用示例生成 |\n| `typescript-template.hbs` | TypeScript SDK 使用示例生成 |\n| `python-build-sync.hbs` | Python 构建同步代码生成 |\n\n### python-template.hbs\n\n用于生成 Python SDK 的使用示例代码，包含：\n\n- 模板初始化代码\n- 环境变量设置\n- 包安装指令\n- 启动命令配置\n\n### typescript-template.hbs\n\n用于生成 TypeScript/JavaScript SDK 的使用示例代码，包含：\n\n- TypeScript 类型安全的模板构建\n- 异步操作处理\n- 错误处理模式\n\n### python-build-sync.hbs\n\n用于生成同步构建相关的 Python 代码，支持：\n\n- 同步模板构建流程\n- 构建状态轮询\n- 结果处理\n\n## 模板指令类型\n\n在 E2B 模板系统中，每条构建指令都被序列化为特定的数据结构：\n\n### 指令类型枚举\n\n| 类型 | 说明 | 生成的 Dockerfile 指令 |\n|------|------|----------------------|\n| `RUN` | 执行命令 | `RUN ` |\n| `COPY` | 复制文件 | `COPY ` |\n| `ENV` | 设置环境变量 | `ENV =` |\n| `WORKDIR` | 设置工作目录 | `WORKDIR ` |\n| `USER` | 设置用户 | `USER ` |\n\n### 指令数据结构\n\n```typescript\ninterface Instruction {\n type: InstructionType\n args: string[]\n force?: boolean\n forceUpload?: string | null\n}\n```\n\n## Dockerfile 生成\n\n`Template` 类提供了 `toDockerfile()` 方法用于生成 Dockerfile 内容：\n\n```typescript\nprivate toDockerfile(): string {\n let dockerfile = `FROM ${this.baseImage}\\n`\n for (const instruction of this.instructions) {\n if (instruction.type === InstructionType.RUN) {\n dockerfile += `RUN ${instruction.args[0]}\\n`\n continue\n }\n if (instruction.type === InstructionType.COPY) {\n dockerfile += `COPY ${instruction.args[0]} ${instruction.args[1]}\\n`\n continue\n }\n if (instruction.type === InstructionType.ENV) {\n const values: string[] = []\n for (let i = 0; i < instruction.args.length; i += 2) {\n values.push(`${instruction.args[i]}=${instruction.args[i + 1]}`)\n }\n dockerfile += `ENV ${values.join(' ')}\\n`\n continue\n }\n dockerfile += `${instruction.type} ${instruction.args.join(' ')}\\n`\n }\n if (this.startCmd) {\n dockerfile += `ENTRYPOINT ${this.startCmd}\\n`\n }\n return dockerfile\n}\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts]()\n\n## 使用示例\n\n### 基础模板构建\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image(\"3.11\")\n .pip_install(\"flask\")\n .run_cmd(\"mkdir -p /app\")\n .set_workdir(\"/app\")\n .set_start_cmd(\"python app.py\", \"curl http://localhost:5000/health\")\n)\n```\n\n### CLI 命令行使用\n\n```bash\ne2b template build --name my-template\n```\n\n生成的输出包含：\n\n- ✅ 构建成功的确认消息\n- Python SDK 使用示例\n- JavaScript/TypeScript SDK 使用示例\n\n资料来源：[packages/cli/src/commands/template/create.ts]()\n\n## 错误处理\n\n模板生成过程中的错误处理机制：\n\n| 错误场景 | 处理方式 |\n|---------|---------|\n| Dockerfile 不存在 | 抛出文件未找到错误 |\n| 构建失败 | 输出错误日志并显示支持链接 |\n| 指令解析失败 | 抛出 JSON 解析错误 |\n\n```typescript\nif (dockerfileContent === undefined) {\n throw new Error(\n `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`\n )\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts]()\n\n## 最佳实践\n\n### 1. 模板命名规范\n\n- 使用描述性名称：`my-app-template`\n- 支持标签语法：`my-app:v1.0`\n\n### 2. 指令顺序\n\n推荐顺序：\n\n1. `from_image()` 或其他基础镜像方法\n2. `set_envs()` 环境变量设置\n3. `run_cmd()` 系统命令\n4. `pip_install()` / `npm_install()` 包安装\n5. `copy()` 文件复制\n6. `set_workdir()` 工作目录设置\n7. `set_start_cmd()` 启动命令\n\n### 3. 缓存优化\n\n使用 `skip_cache()` 方法跳过特定指令的缓存：\n\n```python\ntemplate.skip_cache().run_cmd(\"apt-get update\")\n```\n\n### 4. 环境变量转义\n\n当在模板中使用特殊字符时，使用相应的转义 helpers：\n\n```handlebars\n{{escapeQuotes env_value}}\n```\n\n## 相关文档\n\n- [E2B Python SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [E2B JS SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [E2B CLI 文档](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n- [模板 API 类型定义](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：e2b-dev/E2B\n\n摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths。\n\n## 1. 配置坑 · 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b063fe8cb80490584e7647332a2c4c6 | https://github.com/e2b-dev/E2B/issues/1331 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：process was not killed when auto paused\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Closed Port Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：build status polling timed out\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：Support `AbortSignal` in JS SDK methods for request cancellation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Support `AbortSignal` in JS SDK methods for request cancellation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f74f7dd596784e88aff40ef33d5b505e | https://github.com/e2b-dev/E2B/issues/1312 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Docker Build Secrets Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Template Build Fails with \"syncing took too long\" Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with \"syncing took too long\" Error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown\n\n\n",
"markdown_key": "e2b",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:609539715",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/e2b-dev/E2B"
},
{
"evidence_id": "art_49c083e4950344c48d9f0a6a3182e45f",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/e2b-dev/E2B#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "E2B 说明书",
"toc": [
"https://github.com/e2b-dev/E2B 项目说明书",
"目录",
"项目介绍",
"概述",
"核心功能",
"系统架构",
"API 客户端配置",
"命令行工具",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "71f6719bf62e5ea0799eb73d5f6b3f533a85396b",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"packages/cli/vitest.config.ts",
"packages/cli/package.json",
"packages/cli/README.md",
"packages/cli/tsconfig.json",
"packages/cli/tsup.config.js",
"packages/connect-python/pyproject.toml",
"packages/connect-python/README.md",
"packages/python-sdk/pyproject.toml",
"packages/python-sdk/package.json",
"packages/python-sdk/README.md",
"packages/python-sdk/example.py",
"packages/js-sdk/package.json",
"packages/js-sdk/README.md",
"packages/js-sdk/tsconfig.json",
"packages/js-sdk/tsup.config.js",
"packages/cli/src/terminal.ts",
"packages/cli/src/user.ts",
"packages/cli/src/index.ts",
"packages/cli/src/api.ts",
"packages/cli/src/options.ts",
"packages/cli/tests/setup.ts",
"packages/cli/src/config/index.ts",
"packages/cli/src/utils/templatePrompt.ts",
"packages/cli/src/utils/errors.ts",
"packages/cli/src/utils/confirm.ts",
"packages/cli/src/utils/commands2md.ts",
"packages/cli/src/utils/signal.ts",
"packages/cli/src/utils/wait.ts",
"packages/cli/src/utils/templateSort.ts",
"packages/cli/src/utils/urls.ts",
"packages/cli/src/utils/format.ts",
"packages/cli/src/utils/filesystem.ts",
"packages/cli/src/docker/constants.ts",
"packages/cli/src/commands/index.ts",
"packages/cli/src/commands/template/migrate.ts",
"packages/cli/src/commands/template/build.ts",
"packages/cli/src/commands/template/list.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# e2b - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 e2b 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm i e2b` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0005` supported 0.86, `clm_0008` supported 0.86\n- `pip install e2b` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0006` supported 0.86, `clm_0009` supported 0.86\n- `npm i @e2b/code-interpreter # JavaScript/TypeScript` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `pip install e2b-code-interpreter # Python` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install -g @e2b/cli` 证据：`packages/cli/README.md` Claim：`clm_0007` supported 0.86\n- `npm i @e2b/code-interpreter` 证据：`packages/js-sdk/README.md` Claim：`clm_0005` supported 0.86, `clm_0008` supported 0.86\n- `pip install e2b-code-interpreter` 证据：`packages/python-sdk/README.md` Claim：`clm_0006` supported 0.86, `clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0005` supported 0.86, `clm_0008` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `packages/cli/README.md`, `packages/cli/src/api.ts`, `packages/cli/src/commands/auth/login.ts` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：711\n- 重要文件覆盖：40/711\n- 证据索引条目：44\n- 角色 / Skill 条目：12\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 e2b 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 e2b 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 e2b 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 12 个角色 / Skill / 项目文档条目。\n\n- **Changesets**（project_doc）：in the root of the project. This will create a new changeset in the .changeset folder. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **Claude**（project_doc）：Use pnpm for node and poetry for python to install and update dependencies. Run pnpm run format , pnpm run lint and pnpm run typecheck before committing changes. To re-generate the API client run make codegen in the repository root. Run tests on affected codepaths using pnpm run test . Generate changesets after updating packages/cli, packages/js-sdk, packages/python-sdk. Default credentials are stored in .env.local… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **What is E2B?**（project_doc）：! E2B SDK Preview /readme-assets/e2b-sdk-light.png gh-light-mode-only ! E2B SDK Preview /readme-assets/e2b-sdk-dark.png gh-dark-mode-only 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **E2B CLI**（project_doc）：This CLI tool allows you to build manager your running E2B sandbox and sandbox templates. Learn more in our documentation https://e2b.dev/docs . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/cli/README.md`\n- **connect-python**（project_doc）：🚧 Currently pending an open RFC to be moved into the Connect RPC org https://github.com/connectrpc/connectrpc.com/pull/71 . Please show support. 🚧 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/connect-python/README.md`\n- **What is E2B?**（project_doc）：--- What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/js-sdk/README.md`\n- **What is E2B?**（project_doc）：What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/python-sdk/README.md`\n- **Contributing**（project_doc）：Contributing If you want to contribute, open a PR, issue, or start a discussion on our Discord https://discord.gg/dSBY3ms2Qr . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Integration test template**（project_doc）：$ e2b template build -c \"cd /basic-nextjs-app/ && sudo npm run dev\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/js-sdk/tests/integration/template/README.md`\n- **Abort Signal Support**（project_doc）：Add signal: AbortSignal option to JS SDK methods to support cancelling in-flight requests. The signal can be passed to Sandbox.create , Sandbox.connect , sandbox.commands.run , sandbox.files. , volume methods, and other request options. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/abort-signal-support.md`\n- **Releasing e2b cli**（project_doc）：to create a changeset run pnpm run changeset 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`DEV.md`\n- **Feature request**（project_doc）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n\n## 证据索引\n\n- 共索引 44 条证据。\n\n- **Changesets**（documentation）：in the root of the project. This will create a new changeset in the .changeset folder. 证据：`.changeset/README.md`\n- **Claude**（documentation）：Use pnpm for node and poetry for python to install and update dependencies. Run pnpm run format , pnpm run lint and pnpm run typecheck before committing changes. To re-generate the API client run make codegen in the repository root. Run tests on affected codepaths using pnpm run test . Generate changesets after updating packages/cli, packages/js-sdk, packages/python-sdk. Default credentials are stored in .env.local in the repository root or inside ~/.e2b/config.json. 证据：`CLAUDE.md`\n- **What is E2B?**（documentation）：! E2B SDK Preview /readme-assets/e2b-sdk-light.png gh-light-mode-only ! E2B SDK Preview /readme-assets/e2b-sdk-dark.png gh-dark-mode-only 证据：`README.md`\n- **E2B CLI**（documentation）：This CLI tool allows you to build manager your running E2B sandbox and sandbox templates. Learn more in our documentation https://e2b.dev/docs . 证据：`packages/cli/README.md`\n- **connect-python**（documentation）：🚧 Currently pending an open RFC to be moved into the Connect RPC org https://github.com/connectrpc/connectrpc.com/pull/71 . Please show support. 🚧 证据：`packages/connect-python/README.md`\n- **What is E2B?**（documentation）：--- What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 证据：`packages/js-sdk/README.md`\n- **What is E2B?**（documentation）：What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 证据：`packages/python-sdk/README.md`\n- **Package**（package_manifest）：{ \"name\": \"e2b\", \"private\": true, \"scripts\": { \"version\": \"pnpm changeset version && pnpm run -r postVersion\", \"publish\": \"pnpm changeset publish && pnpm run -r postPublish\", \"test\": \"pnpm test --recursive --if-present\", \"rm-node-modules\": \"find . -name 'node modules' -type d -prune -exec rm -rf '{}' +\", \"pnpm-install-hack\": \"cd packages/js-sdk && sed -i '' 's/\\\"version\\\": \\\". \\\"/\\\"version\\\": \\\"9.9.9\\\"/g' package.json && cd ../.. && pnpm i && git checkout -- packages/js-sdk/package.json\", \"lint\": \"pnpm --if-present --recursive run lint\", \"typecheck\": \"pnpm --if-present --recursive run typecheck\", \"format\": \"pnpm --if-present --recursive run format\", \"changeset\": \"pnpm dlx @changesets/cli\" }… 证据：`package.json`\n- **Contributing**（documentation）：Contributing If you want to contribute, open a PR, issue, or start a discussion on our Discord https://discord.gg/dSBY3ms2Qr . 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@e2b/cli\", \"version\": \"2.10.1\", \"description\": \"CLI for managing e2b sandbox templates\", \"homepage\": \"https://e2b.dev\", \"license\": \"MIT\", \"author\": { \"name\": \"FoundryLabs, Inc.\", \"email\": \"hello@e2b.dev\", \"url\": \"https://e2b.dev\" }, \"bugs\": \"https://github.com/e2b-dev/e2b/issues\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/e2b-dev/e2b\", \"directory\": \"packages/cli\" }, \"publishConfig\": { \"access\": \"public\" }, \"keywords\": \"e2b\", \"ai-agents\", \"agents\", \"ai\", \"code-interpreter\", \"sandbox\", \"code\", \"cli\", \"runtime\", \"vm\", \"nodejs\", \"javascript\", \"typescript\" , \"sideEffects\": false, \"scripts\": { \"prepublishOnly\": \"pnpm build\", \"build\": \"tsc --noEmit --skipLibCheck && tsup… 证据：`packages/cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"e2b\", \"version\": \"2.20.1\", \"description\": \"E2B SDK that give agents cloud environments\", \"homepage\": \"https://e2b.dev\", \"license\": \"MIT\", \"author\": { \"name\": \"FoundryLabs, Inc.\", \"email\": \"hello@e2b.dev\", \"url\": \"https://e2b.dev\" }, \"bugs\": \"https://github.com/e2b-dev/e2b/issues\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/e2b-dev/e2b\", \"directory\": \"packages/js-sdk\" }, \"publishConfig\": { \"access\": \"public\" }, \"sideEffects\": false, \"main\": \"dist/index.js\", \"module\": \"dist/index.mjs\", \"types\": \"dist/index.d.ts\", \"scripts\": { \"prepublishOnly\": \"pnpm build\", \"build\": \"tsc --noEmit && tsup\", \"dev\": \"tsup --watch\", \"example\": \"tsx example.mts\", \"test\": \"vitest run\", \"ge… 证据：`packages/js-sdk/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@e2b/python-sdk\", \"private\": true, \"version\": \"2.21.1\", \"scripts\": { \"example\": \"poetry run python example.py\", \"test\": \"poetry run pytest -n 4 --verbose -x\", \"postVersion\": \"poetry version $ pnpm pkg get version --workspaces=false tr -d \\\\\\\" \", \"postPublish\": \"poetry build && poetry config pypi-token.pypi ${PYPI TOKEN} && poetry publish --skip-existing\", \"pretest\": \"poetry install\", \"typecheck\": \"poetry run make typecheck\", \"lint\": \"poetry run make lint\", \"format\": \"poetry run make format\" } } 证据：`packages/python-sdk/package.json`\n- **Integration test template**（documentation）：$ e2b template build -c \"cd /basic-nextjs-app/ && sudo npm run dev\" 证据：`packages/js-sdk/tests/integration/template/README.md`\n- **Package**（package_manifest）：{ \"dependencies\": { \"date-fns\": \"^2.30.0\" } } 证据：`packages/cli/testground/demo-basic/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`packages/cli/LICENSE`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`packages/connect-python/LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`packages/js-sdk/LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`packages/python-sdk/LICENSE`\n- **Abort Signal Support**（documentation）：Add signal: AbortSignal option to JS SDK methods to support cancelling in-flight requests. The signal can be passed to Sandbox.create , Sandbox.connect , sandbox.commands.run , sandbox.files. , volume methods, and other request options. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError . 证据：`.changeset/abort-signal-support.md`\n- **Releasing e2b cli**（documentation）：to create a changeset run pnpm run changeset 证据：`DEV.md`\n- **Feature Request**（documentation）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Config**（structured_config）：{ \"$schema\": \"https://unpkg.com/@changesets/config@2.3.1/schema.json\", \"changelog\": \"@changesets/cli/changelog\", \"commit\": false, \"fixed\": , \"ignore\": , \"linked\": , \"access\": \"public\", \"baseBranch\": \"main\", \"updateInternalDependencies\": \"patch\", \"privatePackages\": { \"version\": true, \"tag\": true } } 证据：`.changeset/config.json`\n- **Mcp Server**（structured_config）：{ \"additionalProperties\": false, \"properties\": { \"airtable\": { \"title\": \"Airtable MCP Server\", \"description\": \"Provides AI assistants with direct access to Airtable bases, allowing them to read schemas, query records, and interact with your Airtable data. Supports listing bases, retrieving table structures, and searching through records to help automate workflows and answer questions about your organized data.\", \"required\": \"airtableApiKey\", \"nodeenv\" , \"additionalProperties\": false, \"properties\": { \"airtableApiKey\": { \"type\": \"string\" }, \"nodeenv\": { \"type\": \"string\" } }, \"type\": \"object\", \"x-dockerHubUrl\": \"https://hub.docker.com/mcp/server/airtable-mcp-server/overview\" }, \"aks\": { \"title… 证据：`spec/mcp-server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"es2022\", \"module\": \"es2022\", \"lib\": \"es2022\", \"dom\", \"dom.iterable\" , \"allowJs\": true, \"declaration\": true, \"declarationMap\": true, \"moduleResolution\": \"node\", \"sourceMap\": true, \"strict\": true, \"strictNullChecks\": true, \"strictFunctionTypes\": true, \"strictBindCallApply\": true, \"strictPropertyInitialization\": true, \"noImplicitThis\": true, \"alwaysStrict\": true, \"esModuleInterop\": true, \"preserveSymlinks\": true, \"downlevelIteration\": true, \"resolveJsonModule\": true, \"forceConsistentCasingInFileNames\": true, \"allowSyntheticDefaultImports\": true, \"outDir\": \"dist\", \"baseUrl\": \".\", \"rootDirs\": \"src\" , \"paths\": { \"e2b\": \"../js-sdk/src\" } } } 证据：`packages/cli/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"outDir\": \"dist\", \"target\": \"es6\", \"lib\": \"dom\", \"ESNext\" , \"sourceMap\": true, \"allowJs\": true, \"skipLibCheck\": true, \"esModuleInterop\": true, \"allowSyntheticDefaultImports\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"noFallthroughCasesInSwitch\": true, \"moduleResolution\": \"node\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"declaration\": true, }, \"include\": \"src\" , \"exclude\": \"dist\", \"node modules\", \"tsup.config.js\" } 证据：`packages/js-sdk/tsconfig.json`\n- **.editorconfig**（source_file）：root = true .py indent size = 4 证据：`.editorconfig`\n- **.Eslintrc**（source_file）：module.exports = { env: { node: true, browser: true, es6: true, }, extends: 'eslint:recommended', 'plugin:@typescript-eslint/recommended' , parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 'latest', sourceType: 'module', }, ignorePatterns: 'dist/', 'node modules/', ' .gen.ts' , plugins: '@typescript-eslint', 'unused-imports' , rules: { '@typescript-eslint/member-ordering': 'error', '@typescript-eslint/ban-ts-comment': 'off', // \"move fast\" mode '@typescript-eslint/no-explicit-any': 'off', // \"move fast\" mode 'linebreak-style': 'error', 'unix' , 'unused-imports/no-unused-imports': 'error', // No double quotes quotes: 'error', 'single', { avoidEscape: true } , // No extra se… 证据：`.eslintrc.cjs`\n- **.gitattributes**（source_file）：packages/python-sdk/e2b/api/client/ linguist-generated=true packages/python-sdk/e2b/envd/filesystem/ linguist-generated=true packages/python-sdk/e2b/envd/process/ linguist-generated=true / .gen.ts linguist-generated=true 证据：`.gitattributes`\n- **Logs**（source_file）：vale-styles .vercel .vscode .DS Store 证据：`.gitignore`\n- **.npmrc**（source_file）：enable-pre-post-scripts=true auto-install-peers=true exclude-links-from-lockfile=true prefer-workspace-packages=false link-workspace-packages=false engine-strict=true 证据：`.npmrc`\n- **imporatant to keep // $HighlightLine comments at the end of the line**（source_file）：imporatant to keep // $HighlightLine comments at the end of the line apps/web/src/code/ 证据：`.prettierignore`\n- **.prettierrc**（source_file）：{ \"singleQuote\": true, \"semi\": false, \"trailingComma\": \"es5\" } 证据：`.prettierrc`\n- **.tool-versions**（source_file）：deno 1.46.3 nodejs 20.19.5 pnpm 9.15.5 python 3.10 poetry 2.1.1 证据：`.tool-versions`\n- **.Vale**（source_file）：Packages = Microsoft, proselint, write-good, alex, Readability, Joblint, Google 证据：`.vale.ini`\n- **These owners will be the default owners for everything in**（source_file）：These owners will be the default owners for everything in the repo. Unless a later match takes precedence. @jakubno @ValentaTomas 证据：`CODEOWNERS`\n- **Makefile**（source_file）：.PHONY: codegen codegen: @echo \"Building codegen image\" docker build -q -t codegen-env . -f codegen.Dockerfile @echo \"Generating code\" docker run -v $$PWD:/workspace codegen-env make generate 证据：`Makefile`\n- **Install Golang deps**（source_file）：Install Golang deps RUN go install github.com/bufbuild/buf/cmd/buf@v1.50.1 && \\ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1 && \\ go install connectrpc.com/connect/cmd/protoc-gen-connect-go@v1.18.1 证据：`codegen.Dockerfile`\n- **Pnpm Workspace**（source_file）：packages: - packages/ 证据：`pnpm-workspace.yaml`\n- **Openapi Volumecontent**（source_file）：openapi: 3.0.0 info: version: 0.1.0 title: E2B API 证据：`spec/openapi-volumecontent.yml`\n- **Generated code uses security schemas in the alphabetical order.**（source_file）：openapi: 3.0.0 info: version: 0.1.0 title: E2B API 证据：`spec/openapi.yml`\n- **Get directory of this script**（source_file）：Get directory of this script directory = os.path.dirname os.path.abspath file path = os.path.join directory, \"openapi.yml\" 证据：`spec/remove_extra_tags.py`\n- **Supabase**（source_file）：Supabase .branches .temp 证据：`supabase/.gitignore`\n- **A string used to distinguish different Supabase projects on the same host. Defaults to the working**（source_file）：A string used to distinguish different Supabase projects on the same host. Defaults to the working directory name when running supabase init . project id = \"workspace\" 证据：`supabase/config.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, package.json\n- **系统架构**：importance `high`\n - source_paths: packages/js-sdk/src/index.ts, packages/js-sdk/src/sandbox/index.ts, packages/python-sdk/e2b/sandbox/main.py, packages/js-sdk/src/envd/api.ts, packages/python-sdk/e2b/envd/api.py\n- **JavaScript/TypeScript SDK**：importance `high`\n - source_paths: packages/js-sdk/package.json, packages/js-sdk/src/sandbox/index.ts, packages/js-sdk/src/sandbox/commands/index.ts, packages/js-sdk/src/sandbox/filesystem/index.ts, packages/js-sdk/example.mts\n- **Python SDK**：importance `high`\n - source_paths: packages/python-sdk/package.json, packages/python-sdk/e2b/sandbox_async/main.py, packages/python-sdk/e2b/sandbox_sync/main.py, packages/python-sdk/e2b/envd/process/process_pb2.py, packages/python-sdk/example.py\n- **CLI 命令行工具**：importance `medium`\n - source_paths: packages/cli/package.json, packages/cli/src/commands/index.ts, packages/cli/src/commands/sandbox/create.ts, packages/cli/src/commands/template/build.ts, packages/cli/src/commands/auth/login.ts\n- **沙箱生命周期管理**：importance `high`\n - source_paths: packages/js-sdk/src/sandbox/sandboxApi.ts, packages/python-sdk/e2b/sandbox/sandbox_api.py, packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py, packages/js-sdk/src/sandbox/commands/commandHandle.ts, packages/python-sdk/e2b/sandbox/commands/command_handle.py\n- **文件系统操作**：importance `medium`\n - source_paths: packages/js-sdk/src/sandbox/filesystem/index.ts, packages/js-sdk/src/sandbox/filesystem/watchHandle.ts, packages/python-sdk/e2b/sandbox/filesystem/filesystem.py, packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py, packages/js-sdk/src/envd/filesystem/filesystem_connect.ts\n- **Git 操作与网络配置**：importance `medium`\n - source_paths: packages/js-sdk/src/sandbox/git/index.ts, packages/python-sdk/e2b/sandbox_sync/git.py, packages/python-sdk/e2b/sandbox_async/git.py, packages/python-sdk/e2b/sandbox/_git/__init__.py, packages/python-sdk/e2b/sandbox/_git/args.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `71f6719bf62e5ea0799eb73d5f6b3f533a85396b`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `packages/cli/vitest.config.ts`, `packages/cli/package.json`, `packages/cli/README.md`, `packages/cli/tsconfig.json`, `packages/cli/tsup.config.js`, `packages/connect-python/pyproject.toml`, `packages/connect-python/README.md`, `packages/python-sdk/pyproject.toml`, `packages/python-sdk/package.json`, `packages/python-sdk/README.md`, `packages/python-sdk/example.py`, `packages/js-sdk/package.json`, `packages/js-sdk/README.md`, `packages/js-sdk/tsconfig.json`, `packages/js-sdk/tsup.config.js`, `packages/cli/src/terminal.ts`, `packages/cli/src/user.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2b063fe8cb80490584e7647332a2c4c6 | https://github.com/e2b-dev/E2B/issues/1331 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：process was not killed when auto paused\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Closed Port Error\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：build status polling timed out\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- Trigger: [Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- Host AI rule: Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- Why it matters: 这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- Evidence: social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：e2b-dev/E2B\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：process was not killed when auto paused（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Closed Port Error（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Please add skills to use with any ai agent to use e2b in our project（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/e2b-dev/E2B 项目说明书\n\n生成时间：2026-05-17 14:04:55 UTC\n\n## 目录\n\n- [项目介绍](#page-1)\n- [系统架构](#page-2)\n- [JavaScript/TypeScript SDK](#page-3)\n- [Python SDK](#page-4)\n- [CLI 命令行工具](#page-5)\n- [沙箱生命周期管理](#page-6)\n- [文件系统操作](#page-7)\n- [Git 操作与网络配置](#page-8)\n- [模板系统与构建](#page-9)\n- [模板生成器与 Handlebars 模板](#page-10)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n- [packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/template/readycmd.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/readycmd.ts)\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/commands/commandHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/commandHandle.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/python-sdk/e2b/api/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/client.py)\n- [packages/python-sdk/e2b/volume/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/volume/client/client.py)\n- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n \n\n# 项目介绍\n\n## 概述\n\nE2B 是一个开源基础设施项目，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。该项目提供了 JavaScript SDK（Node.js）和 Python SDK 两套开发工具包，使开发者能够轻松启动和控制云端沙箱环境。资料来源：[packages/python-sdk/README.md:1]()\n\nE2B 的核心价值在于为 AI 应用提供了一个安全、可控的代码执行环境。当 AI 模型生成代码后，开发者可以通过 E2B 在隔离的沙箱中运行这些代码，而无需担心安全问题或资源污染。资料来源：[packages/js-sdk/README.md:1]()\n\n## 核心功能\n\n### 安全沙箱环境\n\nE2B 沙箱是基于 Docker 容器技术构建的安全隔离环境。每个沙箱都是完全独立的，拥有自己的文件系统、网络和进程空间。这种隔离确保了运行在沙箱中的代码不会影响主机系统或其他沙箱。资料来源：[packages/js-sdk/src/sandbox/index.ts:1]()\n\n沙箱支持以下关键安全特性：\n\n| 特性 | 说明 | 默认值 |\n|------|------|--------|\n| 互联网访问 | 控制沙箱是否可访问外部网络 | 启用 |\n| 安全模式 | 启用额外的安全限制 | 启用 |\n| 网络隔离 | 自定义网络配置 | 支持 |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n### 多语言 SDK 支持\n\nE2B 提供了两个官方的 SDK 实现：\n\n#### JavaScript SDK\n\nJavaScript SDK 面向 Node.js 环境，支持 TypeScript 和 JavaScript。安装方式如下：\n\n```bash\nnpm i e2b\n```\n\n该 SDK 提供了完整的沙箱控制能力，包括文件系统操作、命令执行、进程管理等。资料来源：[packages/js-sdk/README.md:1]()\n\n#### Python SDK\n\nPython SDK 面向 Python 环境，支持 Python 3.x。安装方式如下：\n\n```bash\npip install e2b\n```\n\n该 SDK 提供了与 JavaScript SDK 类似的功能，并针对 Python 生态进行了优化。资料来源：[packages/python-sdk/README.md:1]()\n\n### 模板系统\n\nE2B 的模板系统允许开发者定义预配置的沙箱环境。模板本质上是一个 Dockerfile，包含了基础镜像、环境变量、依赖安装等配置。资料来源：[packages/js-sdk/src/template/index.ts:1]()\n\n模板支持多种基础镜像来源：\n\n| 方法 | 描述 | 示例 |\n|------|------|------|\n| from_base_image | E2B 默认基础镜像 | e2bdev/base:latest |\n| from_python_image | Python 环境 | python:3 |\n| from_node_image | Node.js 环境 | node:lts |\n| from_bun_image | Bun 环境 | oven/bun:latest |\n| from_debian_image | Debian 环境 | debian:bookworm |\n| from_ubuntu_image | Ubuntu 环境 | ubuntu:24.04 |\n| from_image | 自定义镜像 | 自定义镜像名称 |\n\n资料来源：[packages/js-sdk/src/template/types.ts:1]()\n\n模板构建过程会将所有指令转换为 Dockerfile 格式，包括 RUN、COPY、ENV 等指令。资料来源：[packages/js-sdk/src/template/index.ts:1]()\n\n### 命令执行系统\n\n沙箱支持通过命令执行系统运行任意命令。每个命令执行后会返回标准输出、标准错误和退出码。资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n命令执行的核心特性包括：\n\n```typescript\ninterface CommandResult {\n stdout: string // 标准输出\n stderr: string // 标准错误\n exitCode: number // 退出码，0 表示成功\n error?: string // 错误信息\n}\n```\n\n开发者可以通过 `wait()` 方法异步等待命令执行完成，如果命令以非零退出码结束，将抛出 `CommandExitError` 异常。资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n### 文件系统操作\n\nE2B 提供了强大的文件系统操作能力，支持多种文件格式读取和写入。资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1]()\n\n#### 文件读取格式\n\n| 格式 | 说明 | 适用场景 |\n|------|------|----------|\n| text | 文本格式（默认） | 读取文本文件 |\n| bytes | 字节数组 | 读取二进制文件 |\n| blob | Blob 对象 | Web 环境文件处理 |\n| stream | 可读流 | 大文件流式处理 |\n\n资料来源：[packages/js-sdk/src/volume/index.ts:1]()\n\n#### 文件写入\n\n文件写入支持 gzip 压缩传输，并可通过 `use_octet_stream` 参数选择使用 multipart/form-data 或 application/octet-stream 格式上传。资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:1]()\n\n### 就绪检查命令\n\n模板系统支持设置启动命令和就绪检查命令。就绪检查确保沙箱中的服务完全启动后才标记为可用状态。资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\nE2B 提供了几个内置的就绪检查工具：\n\n| 函数 | 描述 | 实现方式 |\n|------|------|----------|\n| waitForURL | 等待 HTTP URL 返回指定状态码 | curl + grep |\n| waitForProcess | 等待指定名称的进程运行 | pgrep |\n| waitForFile | 等待文件存在 | shell test |\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1]()\n\n### 存储卷管理\n\nE2B 支持持久化存储卷功能，允许沙箱挂载外部存储。这些存储卷可以在沙箱之间共享数据，或用于持久化存储重要数据。资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n存储卷挂载配置示例：\n\n```typescript\nconst sandbox = await Sandbox.create('template-name', {\n volumeMounts: {\n '/data': 'my-volume-name'\n }\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n### MCP 服务器集成\n\nE2B 模板系统支持集成 MCP（Model Context Protocol）服务器，允许在沙箱中运行各种 MCP 服务。资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\n添加 MCP 服务器的示例：\n\n```python\ntemplate.add_mcp_server('exa')\ntemplate.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n```\n\n注意：使用 MCP 服务器需要基础镜像预装了 mcp-gateway。资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\n## 系统架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[开发者应用] --> B[E2B SDK]\n B --> C[API Gateway]\n C --> D[Sandbox Manager]\n D --> E[Docker Container]\n E --> F[envd Agent]\n F --> G[文件系统]\n F --> H[网络栈]\n F --> I[进程管理]\n```\n\n### SDK 分层架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[高级 API]\n B --> C[连接配置]\n C --> D[API Client]\n D --> E[HTTP/REST]\n```\n\n## API 客户端配置\n\nE2B SDK 内部使用 HTTP 客户端与后端 API 通信，支持丰富的配置选项。资料来源：[packages/python-sdk/e2b/api/client/client.py:1]()\n\n| 配置项 | 说明 |\n|--------|------|\n| base_url | API 基础 URL |\n| timeout | 请求超时时间 |\n| verify_ssl | 是否验证 SSL 证书 |\n| follow_redirects | 是否跟随重定向 |\n| cookies | 请求 Cookie |\n| headers | 自定义请求头 |\n| httpx_args | 额外传递给 httpx 的参数 |\n\n资料来源：[packages/python-sdk/e2b/api/client/client.py:1]()\n\n## 命令行工具\n\nE2B 提供了命令行工具用于管理模板。主要命令包括：\n\n### 模板构建\n\n```bash\ne2b template build\n```\n\n该命令会根据指定目录下的 Dockerfile 或模板配置构建沙箱模板。资料来源：[packages/cli/src/commands/template/build.ts:1]()\n\n### 模板创建\n\n```bash\ne2b template create\n```\n\n该命令用于创建新的沙箱模板，支持交互式配置。资料来源：[packages/cli/src/commands/template/create.ts:1]()\n\n## 快速开始\n\n### 1. 安装 SDK\n\n根据使用的编程语言选择对应的 SDK 安装命令：\n\n```bash\n# JavaScript/TypeScript\nnpm i e2b\n\n# Python\npip install e2b\n```\n\n### 2. 获取 API 密钥\n\n1. 访问 [e2b.dev](https://e2b.dev) 注册账号\n2. 在仪表板获取 API 密钥\n3. 设置环境变量\n\n```bash\nexport E2B_API_KEY=e2b_***\n```\n\n### 3. 创建沙箱\n\n**JavaScript 示例：**\n\n```javascript\nimport { Sandbox } from 'e2b'\n\nconst sandbox = await Sandbox.create('python-default')\nconst result = await sandbox.commands.run('echo \"Hello World\"')\nconsole.log(result.stdout)\nawait sandbox.close()\n```\n\n**Python 示例：**\n\n```python\nimport e2b\n\nsandbox = e2b.Sandbox()\nresult = sandbox.commands.run('echo \"Hello World\"')\nprint(result.stdout)\nsandbox.close()\n```\n\n## 环境变量配置\n\n| 变量名 | 说明 | 必需 |\n|--------|------|------|\n| E2B_API_KEY | API 认证密钥 | 是 |\n| E2B_SANDBOX_TIMEOUT | 默认沙箱超时时间（毫秒） | 否 |\n| E2B_DEBUG | 启用调试模式 | 否 |\n\n## 错误处理\n\nE2B SDK 定义了多种错误类型用于处理不同的异常情况：\n\n| 错误类型 | 说明 |\n|----------|------|\n| SandboxError | 沙箱基础错误 |\n| CommandExitError | 命令执行失败（退出码非0） |\n| NotFoundError | 资源未找到 |\n| TemplateError | 模板相关错误 |\n| TimeoutError | 操作超时 |\n\n资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n## 相关资源\n\n- 官方网站：[https://www.e2b.dev/](https://www.e2b.dev/)\n- JavaScript SDK NPM：[https://www.npmjs.com/package/e2b](https://www.npmjs.com/package/e2b)\n- Python SDK PyPI：[https://pypi.org/project/e2b/](https://pypi.org/project/e2b/)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-1), [JavaScript/TypeScript SDK](#page-3), [Python SDK](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/index.ts)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/python-sdk/e2b/sandbox/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/main.py)\n- [packages/js-sdk/src/envd/api.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/api.ts)\n- [packages/python-sdk/e2b/envd/api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/api.py)\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n \n\n# 系统架构\n\n## 概述\n\nE2B 是一个开源基础设施平台，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。系统架构围绕三个核心概念构建：**沙箱（Sandbox）**、**模板（Template）** 和 **API 客户端**。这种设计使得开发者可以通过 SDK 定义可复现的运行时环境，并动态创建和管理隔离的执行实例。\n\n资料来源：[README.md:1-10]()\n\n## 核心组件架构\n\nE2B 系统由以下主要组件构成：\n\n| 组件 | 语言实现 | 职责 |\n|------|---------|------|\n| JavaScript SDK | TypeScript | 提供浏览器和 Node.js 环境下的沙箱管理能力 |\n| Python SDK | Python | 提供 Python 环境下的沙箱管理能力 |\n| CLI 工具 | TypeScript | 提供命令行界面用于模板管理和部署 |\n| API 网关 | 后端服务 | 处理沙箱生命周期请求和状态管理 |\n| envd 服务 | 后端服务 | 在沙箱内部执行命令和文件操作 |\n\n资料来源：[packages/js-sdk/README.md:1-20]()\n\n## SDK 架构\n\n### SDK 导出结构\n\nJavaScript SDK 和 Python SDK 都遵循统一的模块化设计，核心导出包括：\n\n```mermaid\ngraph TD\n A[E2B SDK] --> B[Sandbox 类]\n A --> C[Template 类]\n A --> D[辅助函数]\n B --> B1[启动/停止沙箱]\n B --> B2[文件系统操作]\n B --> B3[进程管理]\n B --> B4[网络访问]\n C --> C1[基础镜像选择]\n C --> C2[依赖安装]\n C --> C3[环境变量配置]\n C --> C4[启动命令设置]\n```\n\n资料来源：[packages/js-sdk/src/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()\n\n### API 客户端架构\n\nSDK 通过统一的 API 客户端与后端服务通信：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `apiKey` | E2B API 密钥 | 环境变量 `E2B_API_KEY` |\n| `baseURL` | API 基础地址 | `https://api.e2b.dev` |\n| `timeout` | 请求超时时间 | 60000ms |\n| `headers` | 自定义请求头 | 包含 SDK 版本、运行时信息 |\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:1-20]()\n\n## 沙箱（Sandbox）架构\n\n### 沙箱生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建中: 调用 sandbox.start()\n 创建中 --> 运行中: envd 服务就绪\n 运行中 --> 暂停中: 调用 sandbox.pause()\n 暂停中 --> 运行中: 调用 sandbox.resume()\n 运行中 --> 停止中: 调用 sandbox.kill() 或超时\n 停止中 --> [*]\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()\n\n### 沙箱创建请求\n\n沙箱创建时，SDK 向后端发送包含完整配置的对象：\n\n```typescript\ninterface NewSandbox {\n templateID: string; // 模板标识符\n metadata?: Record;\n mcp?: Record; // MCP 服务器配置\n envVars?: Record;\n timeout?: number; // 超时时间（秒）\n secure?: boolean; // 安全模式\n allow_internet_access?: boolean;\n network?: NetworkConfig;\n autoPause?: boolean;\n autoResume?: { enabled: boolean };\n volumeMounts?: VolumeMount[];\n}\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-30]()\n\n### 沙箱文件系统\n\n沙箱提供虚拟文件系统，支持以下操作：\n\n| 操作 | JavaScript SDK | Python SDK |\n|------|---------------|------------|\n| 读取文件 | `sandbox.fs.read(path)` | `sandbox.fs.read(path)` |\n| 写入文件 | `sandbox.fs.write(path, content)` | `sandbox.fs.write(path, content)` |\n| 列出目录 | `sandbox.fs.list(path)` | `sandbox.fs.list(path)` |\n| 创建目录 | `sandbox.fs.makeDir(path)` | `sandbox.fs.make_dir(path)` |\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()\n\n## 模板（Template）架构\n\n### 模板构建器模式\n\nTemplate 使用流式构建器（Builder）模式，允许链式调用定义环境：\n\n```mermaid\ngraph LR\n A[Template] --> B[基础镜像]\n B --> C[依赖安装]\n C --> D[环境变量]\n D --> E[启动命令]\n E --> F[TemplateFinal]\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:1-50]()\n\n### 模板配置选项\n\n| 配置方法 | 功能 | 示例 |\n|---------|------|------|\n| `from_image(image)` | 从指定 Docker 镜像创建 | `from_image(\"python:3.11\")` |\n| `from_python_image(version)` | 从 Python 官方镜像创建 | `from_python_image(\"3\")` |\n| `from_node_image(variant)` | 从 Node.js 官方镜像创建 | `from_node_image(\"lts\")` |\n| `from_bun_image(variant)` | 从 Bun 官方镜像创建 | `from_bun_image(\"latest\")` |\n| `from_base_image()` | 从 E2B 基础镜像创建 | - |\n| `run_cmd(cmd)` | 执行 shell 命令 | `run_cmd(\"pip install flask\")` |\n| `copy(src, dest)` | 复制文件到沙箱 | `copy(\"./app\", \"/app\")` |\n| `set_envs(envs)` | 设置环境变量 | `set_envs({\"PORT\": \"3000\"})` |\n| `npm_install()` / `pip_install()` | 安装语言依赖 | - |\n| `apt_install(packages)` | 安装系统包 | `apt_install([\"vim\"])` |\n| `bun_install()` | 使用 Bun 安装依赖 | - |\n| `set_start_cmd(cmd, ready_cmd)` | 设置启动命令 | `set_start_cmd(\"npm start\", waitForURL(\"...\"))` |\n\n资料来源：[packages/js-sdk/src/template/types.ts:50-150]()、[packages/python-sdk/e2b/template/main.py:1-100]()\n\n### 模板构建流程\n\n```mermaid\ngraph TD\n A[定义 Template] --> B[调用 build 方法]\n B --> C[生成 Dockerfile]\n C --> D[上传到 E2B 构建服务]\n D --> E{构建状态}\n E -->|building| F[轮询构建状态]\n F --> E\n E -->|success| G[返回 BuildInfo]\n E -->|error| H[抛出 BuildError]\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts:1-80]()\n\n### 启动就绪检查\n\n系统支持多种就绪检查策略：\n\n| 函数 | 用途 | 实现方式 |\n|------|------|---------|\n| `waitForURL(url, statusCode)` | 等待 HTTP URL 可访问 | curl + grep |\n| `waitForProcess(name)` | 等待进程运行 | pgrep |\n| `waitForFile(path)` | 等待文件存在 | shell test |\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1-50]()\n\n## 环境变量和配置\n\n### SDK 配置\n\n| 环境变量 | 说明 | JavaScript SDK | Python SDK |\n|----------|------|---------------|------------|\n| `E2B_API_KEY` | API 认证密钥 | ✅ | ✅ |\n| `E2B_BASE_URL` | 自定义 API 地址 | 可选 | 可选 |\n| `E2B_TIMEOUT` | 默认超时时间 | 可选 | 可选 |\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:1-20]()\n\n### 沙箱环境变量\n\n沙箱创建时可传入环境变量，格式为键值对映射：\n\n```python\n# Python SDK 示例\nsandbox = Sandbox(\n template=\"my-template\",\n envs={\n \"NODE_ENV\": \"production\",\n \"DATABASE_URL\": \"postgres://...\"\n }\n)\n```\n\n```typescript\n// JavaScript SDK 示例\nconst sandbox = await Sandbox.create({\n template: \"my-template\",\n envs: {\n \"NODE_ENV\": \"production\",\n \"DATABASE_URL\": \"postgres://...\"\n }\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:10-20]()\n\n## MCP 服务器集成\n\nE2B 支持 MCP（Model Context Protocol）服务器集成，允许沙箱访问外部工具和服务：\n\n```mermaid\ngraph LR\n A[MCP 服务器] -->|mcp-gateway| B[沙箱环境]\n B --> C[SDK 调用]\n C --> D[工具执行]\n```\n\n| 方法 | 说明 |\n|------|------|\n| `add_mcp_server(servers)` | 添加 MCP 服务器 |\n| `Template.betaDevContainerPrebuild()` | 预构建 devcontainer |\n| `Template.betaSetDevContainerStart()` | 设置 devcontainer 启动 |\n\n资料来源：[packages/js-sdk/src/template/types.ts:100-130]()\n\n## 部署架构\n\n### 模板构建部署\n\n```mermaid\ngraph LR\n A[本地开发] --> B[定义 Template]\n B --> C[Template.build]\n C --> D[E2B API]\n D --> E[Docker 构建]\n E --> F[镜像仓库]\n F --> G[生产环境]\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:1-50]()\n\n### 构建产物\n\n| 产物 | 说明 |\n|------|------|\n| Docker 镜像 | 存储在 E2B 镜像仓库中 |\n| 模板元数据 | 包含镜像 ID、别名、标签等信息 |\n| 构建日志 | 用于调试构建问题 |\n\n## 安全模型\n\n| 安全特性 | 说明 |\n|---------|------|\n| 隔离执行 | 每个沙箱在独立容器中运行 |\n| 网络控制 | 可配置 `allow_internet_access` |\n| 超时机制 | 可设置沙箱最大运行时间 |\n| 安全模式 | 可启用 `secure: true` 增强隔离 |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:15-25]()\n\n## 依赖安装方法对比\n\n| 包管理器 | JS SDK | Python SDK | 系统级 |\n|---------|--------|-----------|--------|\n| npm/yarn | `npm_install()` | - | - |\n| pip | - | `pip_install()` | - |\n| pip3 | - | `pip_install()` | - |\n| apt-get | `apt_install()` | `apt_install()` | ✅ |\n| bun | `bun_install()` | `bun_install()` | - |\n| 全局安装 | `npm_install(g=True)` | - | - |\n\n资料来源：[packages/js-sdk/src/template/types.ts:80-120]()、[packages/python-sdk/e2b/template/main.py:50-150]()\n\n## 总结\n\nE2B 系统架构采用分层设计，通过统一的 SDK 抽象隐藏底层复杂性：\n\n- **表现层**：JavaScript SDK 和 Python SDK 提供统一的 API\n- **通信层**：API 客户端处理认证、请求序列化和错误处理\n- **服务层**：后端 API 和 envd 服务管理沙箱生命周期\n- **执行层**：Docker 容器提供资源隔离\n\n这种架构使得开发者可以专注于业务逻辑，而无需关心底层基础设施的复杂性。\n\n---\n\n\n\n## JavaScript/TypeScript SDK\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [Python SDK](#page-4), [沙箱生命周期管理](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n- [packages/js-sdk/src/api/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n- [packages/js-sdk/src/api/metadata.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/sandbox/mcp.d.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/mcp.d.ts)\n- [packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [packages/js-sdk/src/envd/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)\n \n\n# JavaScript/TypeScript SDK\n\n## 概述\n\nE2B JavaScript/TypeScript SDK 是一个开源基础设施，允许用户在云端安全隔离的沙箱中运行 AI 生成的代码。该 SDK 提供了启动和控制沙箱的完整能力，支持 Node.js、Browser 和 Deno 运行时环境。\n\n资料来源：[packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n\n### 核心能力\n\n| 功能模块 | 描述 |\n|---------|------|\n| 沙箱管理 | 创建、启动、停止和管理云端沙箱 |\n| 文件系统操作 | 在沙箱中读写文件、执行命令 |\n| 模板系统 | 构建可复用的沙箱模板 |\n| MCP 集成 | 支持 Model Context Protocol 服务器 |\n| API 通信 | 通过 gRPC 和 REST 与后端服务通信 |\n\n资料来源：[packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n\n## 架构设计\n\n### 技术栈\n\n```mermaid\ngraph TD\n A[JavaScript SDK] --> B[@connectrpc/connect-web]\n A --> C[@bufbuild/protobuf]\n A --> D[openapi-fetch]\n \n E[沙箱环境] --> F[envd 服务]\n F --> G[文件系统 API]\n F --> H[命令执行 API]\n F --> I[环境变量 API]\n \n B --> E\n C --> E\n D --> J[REST API]\n```\n\n### 依赖关系\n\nSDK 核心依赖包括：\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| @bufbuild/protobuf | ^2.6.2 | Protocol Buffers 序列化 |\n| @connectrpc/connect | 2.0.0-rc.3 | gRPC-Web 通信协议 |\n| @connectrpc/connect-web | 2.0.0-rc.3 | Web 端 gRPC 支持 |\n| openapi-fetch | ^0.14.1 | REST API 调用 |\n| chalk | ^5.3.0 | 控制台输出格式化 |\n| glob | ^11.1.0 | 文件模式匹配 |\n\n资料来源：[packages/js-sdk/package.json:18-36](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n\n### 运行时支持\n\nSDK 支持多种 JavaScript 运行时环境：\n\n- **Node.js**: 主要支持版本 >=18\n- **Browser**: 支持现代浏览器环境\n- **Deno**: 原生支持 Deno 运行时\n\n资料来源：[packages/js-sdk/src/api/metadata.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n\n## 安装与配置\n\n### 安装方式\n\n```bash\nnpm i e2b\n```\n\n### 环境变量配置\n\n```bash\nE2B_API_KEY=e2b_your_api_key_here\n```\n\nSDK 通过以下方式获取环境变量：\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:17-29](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n\n```typescript\nexport function getEnvVar(name: string) {\n if (runtime === 'deno') {\n return Deno.env.get(name)\n }\n\n if (typeof process === 'undefined') {\n return ''\n }\n\n return process.env[name]\n}\n```\n\n### 默认请求头\n\nSDK 自动附加以下元数据头：\n\n| 头信息 | 来源 | 说明 |\n|-------|------|------|\n| browser | platform.name | 浏览器标识 |\n| lang | js | 语言标识 |\n| lang_version | runtimeVersion | 运行时版本 |\n| package_version | package.json | SDK 版本 |\n| publisher | e2b | 发布者标识 |\n| sdk_runtime | runtime | 运行时类型 |\n| system | platform.os?.family | 操作系统类型 |\n\n资料来源：[packages/js-sdk/src/api/metadata.ts:7-15](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)\n\n## API 端点\n\n### 沙箱管理接口\n\n#### 创建沙箱\n\n```\nPOST /sandboxes\n```\n\n请求体 schema 定义：\n\n资料来源：[packages/js-sdk/src/api/schema.gen.ts:18-35](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n\n```typescript\ninterface paths {\n \"/sandboxes\": {\n post: {\n parameters: {\n query?: never;\n header?: never;\n path?: never;\n cookie?: never;\n };\n requestBody: {\n content: {\n \"application/json\": components[\"schemas\"][\"NewSandbox\"];\n };\n };\n responses: {\n 201: {\n headers: { [name: string]: unknown };\n content: { \"application/json\": components[\"schemas\"][\"Sandbox\"] };\n };\n };\n };\n };\n}\n```\n\n#### 获取沙箱列表\n\n```\nGET /sandboxes\n```\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| metadata | string | 元数据过滤条件（URL 编码） |\n\n响应示例：\n\n```json\n{\n \"application/json\": components[\"schemas\"][\"ListedSandbox\"][]\n}\n```\n\n资料来源：[packages/js-sdk/src/api/schema.gen.ts:1-25](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n\n### 环境变量接口\n\n#### 获取环境变量\n\n```\nGET /envs\n```\n\n响应结构：\n\n```typescript\ninterface paths {\n \"/envs\": {\n get: {\n parameters: {\n query?: never;\n header?: never;\n path?: never;\n cookie?: never;\n };\n requestBody?: never;\n responses: {\n 200: {\n headers: { [name: string]: unknown };\n content: {\n \"application/json\": components[\"schemas\"][\"EnvVars\"];\n };\n };\n };\n };\n };\n}\n```\n\n资料来源：[packages/js-sdk/src/envd/schema.gen.ts:1-35](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)\n\n### 文件操作接口\n\n#### 下载文件\n\n```\nGET /files\n```\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| path | string | 文件路径（URL 编码） |\n| signature | string | 文件访问签名 |\n| signature_expiration | string | 签名过期时间 |\n| username | string | 用户标识 |\n\n资料来源：[packages/js-sdk/src/envd/schema.gen.ts:50-65](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)\n\n## MCP 服务器支持\n\nSDK 提供完整的 Model Context Protocol (MCP) 服务器类型定义。\n\n### 支持的 MCP 服务器类型\n\n资料来源：[packages/js-sdk/src/sandbox/mcp.d.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/mcp.d.ts)\n\n| 类别 | 服务器 |\n|------|--------|\n| 云服务 | awsCore, awsCdk, awsDiagram, awsDocumentation, awsTerraform, azure, aks |\n| 搜索 | brave, exa, braveSearch |\n| 数据库 | astraDb, chroma, clickhouse, cdataConnectcloud |\n| 开发工具 | circleci, buildkite, camunda, apify |\n| 文档 | astroDocs, atlasDocs, atlan |\n| 安全 | beagleSecurity |\n| 通信 | atlassian, close, audienseInsights |\n\n### MCP 服务器接口定义\n\n```typescript\nexport interface McpServer {\n airtable?: AirtableMCPServer;\n aks?: AzureKubernetesServiceAKS;\n apiGateway?: ApiGateway;\n apify?: ApifyMCPServer;\n arxiv?: ArXivMCPServer;\n astGrep?: AstGrep;\n // ... 更多服务器类型\n}\n```\n\n## 模板系统\n\n### 模板类型定义\n\n资料来源：[packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n\nSDK 提供链式 API 构建模板：\n\n```typescript\ninterface TemplateBuilder {\n // 包管理器安装\n npmInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;\n bunInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;\n yarnInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;\n pnpmInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;\n \n // 系统包安装\n aptInstall(packages: string | string[], options?: { noInstallRecommends?: boolean; fixMissing?: boolean }): TemplateBuilder;\n \n // MCP 服务器\n addMcpServer(servers: string | string[]): TemplateBuilder;\n}\n```\n\n### 模板使用示例\n\n```typescript\n// 使用基础镜像创建模板\nconst template = Template()\n .fromBaseImage()\n .runCmd('echo Hello World E2B!')\n\n// 安装 npm 包\ntemplate.npmInstall('express')\ntemplate.npmInstall(['lodash', 'axios'])\ntemplate.npmInstall('typescript', { dev: true })\n\n// 安装系统包\ntemplate.aptInstall('vim')\ntemplate.aptInstall(['git', 'curl'], { noInstallRecommends: true })\n\n// 添加 MCP 服务器\ntemplate.addMcpServer('exa')\ntemplate.addMcpServer(['brave', 'github'])\n```\n\n## 快速开始\n\n### 基本使用流程\n\n```mermaid\ngraph LR\n A[初始化 SDK] --> B[创建沙箱]\n B --> C[执行命令/操作文件]\n C --> D[获取结果]\n D --> E[停止沙箱]\n```\n\n### 完整示例\n\n资料来源：[packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n\n```typescript\nimport { Sandbox } from 'e2b'\n\n// 创建沙箱实例\nconst sandbox = await Sandbox.create()\n\n// 执行命令\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\n\n// 读写文件\nawait sandbox.filesystem.write('/data/example.txt', 'Hello World')\nconst content = await sandbox.filesystem.read('/data/example.txt')\n\n// 停止沙箱\nawait sandbox.close()\n```\n\n### 环境变量设置\n\n```typescript\n// 设置 API 密钥\nconst E2B_API_KEY = process.env.E2B_API_KEY\n```\n\n## 构建配置\n\n### tsup 配置\n\n资料来源：[packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)\n\n```javascript\nexport default defineConfig({\n minify: false,\n target: ['es2017'],\n sourcemap: true,\n dts: true,\n format: ['esm', 'cjs'], // 同时支持 ESM 和 CommonJS\n clean: true,\n entry: {\n index: './src/index.ts',\n },\n esbuildOptions: (options) => {\n options.legalComments = 'none'\n return options\n },\n})\n```\n\n### 输出格式\n\n| 格式 | 说明 |\n|-----|------|\n| ESM | ECMAScript Module，适合现代构建工具 |\n| CJS | CommonJS，适合 Node.js 直接运行 |\n| TypeScript 声明 | 自动生成 .d.ts 类型文件 |\n\n## SDK 关键词\n\n资料来源：[packages/js-sdk/package.json:26-39](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n\n```\ne2b, ai-agents, agents, ai, code-interpreter, sandbox, code, runtime, vm, nodejs, javascript, typescript\n```\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| NPM 包 | https://www.npmjs.com/package/e2b |\n| Python SDK | https://pypi.org/project/e2b |\n| 官方文档 | https://e2b.dev/docs |\n| 支持渠道 | https://e2b.dev/docs/support |\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [JavaScript/TypeScript SDK](#page-3), [沙箱生命周期管理](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/python-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/package.json)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/envd/process/process_pb2.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/process/process_pb2.py)\n- [packages/python-sdk/example.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/example.py)\n \n\n# Python SDK\n\n## 概述\n\nE2B Python SDK 是一个开源的基础设施库，用于在云端安全隔离的沙箱环境中运行 AI 生成的代码。该 SDK 提供了创建和控制沙箱的能力，支持同步和异步两种操作模式。开发者可以通过简单的 API 调用，在隔离环境中执行命令、运行代码，并与管理服务进行通信。\n\n## 核心架构\n\n### 模块结构\n\nPython SDK 主要由以下几个核心模块组成：\n\n| 模块 | 文件路径 | 功能说明 |\n|------|----------|----------|\n| sandbox_async | `e2b/sandbox_async/main.py` | 异步沙箱实现，支持 `Sandbox` 类的异步方法 |\n| sandbox_sync | `e2b/sandbox_sync/main.py` | 同步沙箱实现，提供阻塞式的沙箱操作 |\n| template | `e2b/template/main.py` | 模板构建器，用于定义沙箱环境配置 |\n| template_async | `e2b/template_async/main.py` | 异步模板管理 |\n| template_sync | `e2b/template_sync/main.py` | 同步模板管理 |\n\n### 运行时架构图\n\n```mermaid\ngraph TD\n A[开发者应用] --> B[Python SDK]\n B --> C{同步/异步模式}\n C -->|同步| D[sandbox_sync]\n C -->|异步| E[sandbox_async]\n D --> F[API 客户端]\n E --> F\n F --> G[E2B API 服务]\n G --> H[沙箱实例]\n H --> I[envd 进程]\n I --> J[隔离文件系统]\n I --> K[网络环境]\n```\n\n## 沙箱管理\n\n### 创建沙箱\n\nPython SDK 提供了两种沙箱创建方式：同步和异步。\n\n#### 异步创建方式\n\n```python\nfrom e2b import Sandbox\nimport asyncio\n\nasync def main():\n sandbox = await Sandbox.create()\n # 执行操作\n await sandbox.close()\n\nasyncio.run(main())\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n\n#### 同步创建方式\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout)\n```\n\n资料来源：[README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n### 沙箱响应模型\n\n沙箱创建成功后会返回 `SandboxCreateResponse` 对象，包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| sandbox_id | str | 沙箱唯一标识符 |\n| sandbox_domain | str | 沙箱域名 |\n| envd_version | str | envd 版本号 |\n| envd_access_token | str | envd 访问令牌 |\n| traffic_access_token | str | 流量访问令牌 |\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n\n### 沙箱生命周期管理\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建中: Sandbox.create()\n 创建中 --> 运行中: 沙箱启动成功\n 运行中 --> 停止中: sandbox.close()\n 停止中 --> 已停止: 资源清理完成\n 创建中 --> 失败: API 错误\n 运行中 --> 失败: 连接断开\n 失败 --> [*]\n 已停止 --> [*]\n```\n\n## 模板系统\n\n### 模板构建器\n\n模板系统允许开发者定义沙箱的初始环境配置，包括基础镜像、系统包安装、环境变量设置等。\n\n#### 基础镜像选择\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image('3') # Python 3\n # 或\n .from_node_image('lts') # Node.js LTS\n # 或\n .from_bun_image('latest') # Bun 最新版\n # 或\n .from_base_image() # E2B 默认基础镜像\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n#### 系统包安装\n\n```python\ntemplate = (\n Template()\n .from_ubuntu_image('24.04')\n .apt_install('vim')\n .apt_install(['git', 'curl', 'wget'])\n)\n```\n\n#### 环境变量配置\n\n```python\ntemplate.set_envs({\n 'NODE_ENV': 'production',\n 'PORT': '8080'\n})\n```\n\n### 启动命令配置\n\n```python\nfrom e2b import Template, wait_for_url, wait_for_port, wait_for_file\n\ntemplate = (\n Template()\n .from_node_image()\n .copy('app.js', '/home/user/')\n .set_start_cmd('node app.js', wait_for_port(3000))\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/readycmd.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/readycmd.py)\n\n### 模板构建\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image('3')\n .copy('requirements.txt', '/home/user/')\n .run_cmd('pip install -r /home/user/requirements.txt')\n)\n\n# 构建带标签的模板\nTemplate.build(template, 'my-python-env:v1.0')\n\n# 构建带多标签的模板\nTemplate.build(template, 'my-python-env', tags=['v1.1.0', 'stable'])\n```\n\n资料来源：[packages/python-sdk/e2b/template_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_sync/main.py)\n\n## 进程与命令执行\n\n### 命令运行\n\n在沙箱中执行命令有两种方式：\n\n#### 使用 commands.run()\n\n```python\nresult = sandbox.commands.run('echo \"Hello from E2B!\"')\nprint(result.stdout) # Hello from E2B!\n```\n\n#### 使用 process 模块\n\n```python\nprocess = sandbox.process.start(\n cmd='python app.py',\n cwd='/home/user'\n)\n```\n\n资料来源：[packages/python-sdk/example.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/example.py)\n\n### 进程通信协议\n\n进程通信使用 protobuf 定义的协议，核心模型包括：\n\n| 消息类型 | 说明 |\n|----------|------|\n| Stdin | 标准输入消息 |\n| Stdout | 标准输出消息 |\n| Stderr | 标准错误输出 |\n| Exit | 进程退出信号 |\n\n资料来源：[packages/python-sdk/e2b/envd/process/process_pb2.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/process/process_pb2.py)\n\n## 错误处理\n\n### 异常类型\n\n| 异常类型 | 说明 |\n|----------|------|\n| SandboxException | 沙箱操作相关错误 |\n| TemplateException | 模板构建相关错误 |\n| handle_api_exception | API 调用错误处理 |\n\n### 版本兼容性检查\n\nSDK 会在创建沙箱时检查 envd 版本：\n\n```python\nif Version(res.parsed.envd_version) < Version(\"0.1.0\"):\n await SandboxApi._cls_kill(res.parsed.sandbox_id)\n raise TemplateException(\n \"You need to update the template to use the new SDK. \"\n \"You can do this by running `e2b template build` in the directory with the template.\"\n )\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n\n## 安装与配置\n\n### 环境要求\n\nPython SDK 需要 Python 3.8 或更高版本。\n\n### 安装命令\n\n```bash\npip install e2b\n```\n\n### 环境变量配置\n\n```bash\nE2B_API_KEY=e2b_***\n```\n\n资料来源：[packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n\n## API 客户端配置\n\n### 连接配置\n\n```python\nfrom e2b import ConnectionConfig\n\nconfig = ConnectionConfig(\n api_key=\"your-api-key\",\n # 其他可选参数\n)\n```\n\n### API 客户端初始化\n\nSDK 内部通过 `get_api_client()` 函数获取 API 客户端：\n\n```python\napi_client = get_api_client(\n config,\n require_api_key=True,\n require_access_token=False,\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/main.py)\n\n## 快速开始示例\n\n```python\nfrom e2b import Sandbox\n\n# 同步使用\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n\n# 异步使用\nimport asyncio\nfrom e2b import Sandbox\n\nasync def main():\n sandbox = await Sandbox.create()\n result = await sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout)\n await sandbox.close()\n\nasyncio.run(main())\n```\n\n资料来源：[README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n## 进阶功能\n\n### MCP 服务器集成\n\n模板支持添加 MCP (Model Context Protocol) 服务器：\n\n```python\ntemplate = (\n Template()\n .from_base_image()\n .add_mcp_server('exa')\n .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### 缓存控制\n\n跳过缓存，强制重新构建：\n\n```python\ntemplate.skip_cache().run_cmd('apt-get update')\n```\n\n### Bun 包管理器\n\n```python\ntemplate = (\n Template()\n .from_bun_image()\n .bun_install('express')\n .bun_install(['lodash', 'axios'])\n .bun_install('tsx', g=True) # 全局安装\n)\n```\n\n## 数据模型\n\n### SandboxDetail\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| sandbox_id | str | 沙箱 ID |\n| started_at | datetime | 启动时间 |\n| state | str | 当前状态 |\n| template_id | str | 模板 ID |\n| alias | str | 模板别名 |\n| allow_internet_access | bool | 是否允许互联网访问 |\n| domain | str | 沙箱域名 |\n| metadata | dict | 元数据 |\n\n资料来源：[packages/python-sdk/e2b/api/client/models/sandbox_detail.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/models/sandbox_detail.py)\n\n### 模板标签\n\n```python\n@dataclass\nclass TemplateTag:\n tag: str # 标签名称\n build_id: str # 构建 ID\n created_at: datetime # 创建时间\n```\n\n资料来源：[packages/python-sdk/e2b/template_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/main.py)\n\n---\n\n\n\n## CLI 命令行工具\n\n### 相关页面\n\n相关主题：[沙箱生命周期管理](#page-6), [模板系统与构建](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n- [packages/cli/src/utils/commands2md.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/utils/commands2md.ts)\n \n\n# CLI 命令行工具\n\n## 概述\n\nE2B CLI 是一个命令行工具，用于构建和管理 E2B 云端沙箱以及沙箱模板。它提供了与 E2B 后端服务交互的便捷方式，使开发者能够通过终端快速创建、配置和部署沙箱环境。\n\nCLI 工具是 E2B SDK 生态系统的重要组成部分，支持通过命令行直接操作沙箱和模板资源，而无需编写额外的代码。\n\n资料来源：[packages/cli/README.md:1-3]()\n\n## 安装方式\n\nE2B CLI 支持多种安装方式，开发者可以根据自己的环境选择最适合的方法。\n\n### 通过 Homebrew 安装（macOS）\n\n```bash\nbrew install e2b\n```\n\n### 通过 NPM 安装\n\n```bash\nnpm install -g @e2b/cli\n```\n\n资料来源：[packages/cli/README.md:10-19]()\n\n## 认证配置\n\n使用 CLI 之前需要进行身份认证。E2B 提供了交互式和非交互式两种认证方式。\n\n### 交互式登录\n\n```bash\ne2b auth login\n```\n\n该命令会打开浏览器窗口引导用户完成认证流程。\n\n### 非交互式认证\n\n在没有浏览器访问权限的环境中，可以设置 `E2B_ACCESS_TOKEN` 环境变量进行认证。访问令牌可在 [e2b.dev/dashboard](https://e2b.dev/dashboard) 的账户设置中的团队选择器下获取。\n\n```bash\nE2B_ACCESS_TOKEN=sk_e2b_... e2b template build\n```\n\n> [!IMPORTANT]\n> 注意 `E2B_ACCESS_TOKEN` 与 `E2B_API_KEY` 的区别。CLI 使用访问令牌，而 SDK 使用 API 密钥。\n\n资料来源：[packages/cli/README.md:21-35]()\n\n## 命令结构\n\nCLI 采用分层命令结构，支持子命令扩展。命令文档生成工具可以将命令定义转换为 Markdown 格式的文档。\n\n### 文档生成机制\n\nCLI 提供了将命令自动转换为文档的功能，支持以下特性：\n\n- 解析命令选项及其默认值\n- 生成子命令文档\n- 清理终端颜色代码\n- 转义 HTML 特殊字符\n\n```typescript\n// 处理子命令\ncommand.commands.forEach((subcommand: any) => {\n const [, subMdContent] = commandToMd(subcommand, fullName)\n mdContent += subMdContent + '\\n\\n'\n})\n```\n\n资料来源：[packages/cli/src/utils/commands2md.ts:40-47]()\n\n## 模板命令\n\n模板是 E2B 沙箱的基础配置，定义了沙箱环境的初始状态。CLI 提供了完整的模板管理能力。\n\n### 创建模板\n\n创建新模板时，CLI 会生成相应的使用示例并支持多语言 SDK 代码片段输出。\n\n```bash\ne2b template create\n```\n\n模板创建完成后会输出成功信息，包含模板 ID 和使用示例：\n\n```\n✅ Building sandbox template {templateID} finished.\n```\n\n示例输出格式支持 Python SDK 和 JS SDK 两种格式，方便不同技术栈的开发者使用。\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-15]()\n\n### 构建模板\n\n构建命令将本地模板配置打包并上传到 E2B 后端进行构建。\n\n```bash\ne2b template build\n```\n\n#### 构建流程状态\n\n构建过程会返回不同的状态，CLI 根据状态码进行相应处理：\n\n| 状态 | 处理方式 |\n|------|----------|\n| `building` | 继续轮询直到构建完成 |\n| `success` | 输出成功信息和示例代码 |\n| `error` | 抛出错误并提示支持渠道 |\n\n```typescript\nswitch (template.status) {\n case 'building':\n // 继续轮询\n break\n case 'success':\n // 输出成功信息和示例\n console.log(`✅ Building sandbox template... finished.`)\n break\n case 'error':\n throw new Error(`❌ Building sandbox template... failed.`)\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:50-80]()\n\n#### Dockerfile 处理\n\nCLI 支持自定义 Dockerfile 构建模板：\n\n```typescript\nexport function getDockerfile(root: string, file?: string) {\n // 检查用户指定的 Dockerfile 是否存在\n if (file) {\n const dockerfilePath = path.join(root, file)\n const dockerfileContent = loadFile(dockerfilePath)\n \n if (dockerfileContent === undefined) {\n throw new Error(`No ${dockerfileRelativePath} found in the root directory.`)\n }\n \n return { dockerfilePath, dockerfileContent, dockerfileRelativePath }\n }\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:95-110]()\n\n### 构建产物格式\n\n成功构建后，CLI 会输出格式化的模板信息：\n\n```typescript\nconsole.log(\n `\\n✅ Building sandbox template ${asFormattedSandboxTemplate({\n templateID: templateName,\n })} finished.\\n${exampleHeader}\\n${exampleUsage}\\n`\n)\n```\n\n输出包含：\n- 模板 ID/别名\n- 使用示例代码\n- Python SDK 示例\n- JS SDK 示例\n\n资料来源：[packages/cli/src/commands/template/create.ts:8-13]()\n\n## 环境变量\n\nCLI 使用以下环境变量进行配置：\n\n| 变量名 | 用途 | 来源 |\n|--------|------|------|\n| `E2B_ACCESS_TOKEN` | CLI 认证令牌 | 用户设置 |\n| `E2B_API_KEY` | SDK API 密钥 | SDK 使用 |\n\n资料来源：[packages/cli/README.md:31-34]()\n\n## 错误处理\n\nCLI 实现了统一的错误处理机制：\n\n### 构建错误\n\n```typescript\ncase 'error':\n throw new Error(\n `\\n❌ Building sandbox template ${asFormattedSandboxTemplate({\n aliases,\n ...template,\n })} failed.\\nCheck the logs above for more details or contact us ${asPrimary(\n '(https://e2b.dev/docs/support)'\n )} to get help.\\n`\n )\n```\n\n### 文件缺失错误\n\n```typescript\nif (dockerfileContent === undefined) {\n throw new Error(\n `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`\n )\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:68-76]()\n\n## 相关资源\n\n- 官方文档：[https://e2b.dev/docs](https://e2b.dev/docs)\n- CLI 文档：[https://e2b.dev/docs/cli](https://e2b.dev/docs)\n- 支持渠道：[https://e2b.dev/docs/support](https://e2b.dev/docs/support)\n\n资料来源：[packages/cli/README.md:36-37]()\n\n---\n\n\n\n## 沙箱生命周期管理\n\n### 相关页面\n\n相关主题：[文件系统操作](#page-7), [Git 操作与网络配置](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/python-sdk/e2b/sandbox/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/sandbox_api.py)\n- [packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py)\n- [packages/js-sdk/src/sandbox/commands/commandHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/commandHandle.ts)\n- [packages/python-sdk/e2b/sandbox/commands/command_handle.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/commands/command_handle.py)\n \n\n# 沙箱生命周期管理\n\n## 概述\n\n沙箱生命周期管理是 E2B 平台提供的核心功能，用于控制沙箱实例在超时、异常或资源管理场景下的行为方式。通过生命周期配置，用户可以定义沙箱在空闲超时后是被终止（kill）还是暂停（pause），以及是否支持自动恢复（auto_resume）功能。 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:15-17]()\n\n## 核心概念\n\n### 生命周期状态\n\nE2B 沙箱支持以下生命周期状态：\n\n| 状态 | 描述 | 可用选项 |\n|------|------|----------|\n| **Running** | 沙箱正在正常运行 | - |\n| **Paused** | 沙箱被暂停，资源冻结 | `on_timeout: \"pause\"` |\n| **Terminated** | 沙箱已被终止销毁 | `on_timeout: \"kill\"` |\n\n### 生命周期配置参数\n\n```typescript\ninterface LifecycleConfig {\n on_timeout: \"kill\" | \"pause\" // 超时行为（默认: \"kill\"）\n auto_resume: boolean // 是否支持自动恢复（默认: false，仅在 pause 模式下有效）\n}\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `on_timeout` | `\"kill\"` \\| `\"pause\"` | `\"kill\"` | 空闲超时后的行为 |\n| `auto_resume` | `boolean` | `false` | 是否在访问时自动恢复暂停的沙箱 |\n\n## 创建沙箱时的生命周期配置\n\n### TypeScript SDK\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create('my-template', {\n lifecycle: {\n on_timeout: \"pause\",\n auto_resume: true\n }\n})\n```\n\n### Python SDK (异步)\n\n```python\nfrom e2b import Sandbox\n\nsandbox = await Sandbox.create(\n template='my-template',\n lifecycle={\"on_timeout\": \"pause\", \"auto_resume\": True}\n)\n```\n\n### Python SDK (同步)\n\n```python\nfrom e2b import Sandbox\n\nsandbox = Sandbox.create(\n template='my-template',\n lifecycle={\"on_timeout\": \"pause\", \"auto_resume\": True}\n)\n```\n\n## 生命周期状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Creating: 创建沙箱\n Creating --> Running: 创建成功\n Creating --> [*]: 创建失败\n \n Running --> Idle: 空闲超时\n Idle --> Running: 恢复操作\n Idle --> Paused: 到达超时阈值\n \n Paused --> Running: auto_resume=true
访问时自动恢复\n Paused --> Terminated: 手动终止\n \n Running --> Terminated: 手动终止
on_timeout=\"kill\"\n Terminated --> [*]\n \n note right of Paused: 仅当 lifecycle.on_timeout=\"pause\" 时触发\n note right of Idle: 平台内部状态\n```\n\n## 自动暂停与恢复机制\n\n### 工作原理\n\n1. **自动暂停**：当沙箱在配置的超时时间内没有活跃操作时，平台自动将沙箱状态从 `Running` 转换为 `Paused`，释放底层计算资源 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:25]()\n\n2. **自动恢复**：当 `auto_resume` 设置为 `true` 时，对暂停状态沙箱的任何访问操作（如运行命令、读取文件）会自动触发沙箱恢复 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:25]()\n\n```mermaid\nsequenceDiagram\n participant Client\n participant SandboxAPI\n participant SandboxInstance\n \n Client->>SandboxAPI: 创建沙箱 (lifecycle: auto_resume=true)\n SandboxAPI->>SandboxInstance: 启动沙箱\n \n Note over SandboxInstance: 空闲超时检测\n SandboxInstance-->>SandboxInstance: 自动暂停\n \n Client->>SandboxAPI: 访问暂停的沙箱\n SandboxAPI->>SandboxInstance: 自动恢复\n SandboxInstance-->>Client: 沙箱就绪\n \n Note over SandboxInstance: 恢复后继续使用\n```\n\n### 配置约束\n\n| 场景 | `on_timeout` 要求 | 说明 |\n|------|-------------------|------|\n| 启用自动恢复 | 必须为 `\"pause\"` | auto_resume 仅在 pause 模式下生效 |\n| 立即终止 | 设置为 `\"kill\"` | 超时后立即销毁沙箱（默认行为） |\n\n## CLI 沙箱信息查看\n\n通过 E2B CLI 可以查看沙箱的生命周期状态：\n\n```bash\ne2b sandbox info \n```\n\n返回的沙箱信息包含以下生命周期相关字段：\n\n| 字段 | 说明 |\n|------|------|\n| `state` | 当前状态（Running、Paused 等） |\n| `lifecycle` | 生命周期配置 |\n| `sandboxId` | 沙箱唯一标识 |\n\n## 最佳实践\n\n### 1. 开发调试场景\n\n使用默认的 `kill` 模式，简化资源管理：\n\n```typescript\nconst sandbox = await Sandbox.create('debug-template', {\n lifecycle: {\n on_timeout: \"kill\" // 默认值\n }\n})\n```\n\n### 2. 长时任务场景\n\n使用暂停模式配合自动恢复，避免重复创建开销：\n\n```typescript\nconst sandbox = await Sandbox.create('worker-template', {\n lifecycle: {\n on_timeout: \"pause\",\n auto_resume: true\n },\n timeoutMs: 30 * 60 * 1000 // 30分钟活跃超时\n})\n```\n\n### 3. 成本敏感场景\n\n使用 `kill` 模式确保资源及时释放：\n\n```python\nsandbox = await Sandbox.create(\n template='batch-template',\n lifecycle={\"on_timeout\": \"kill\"}\n)\n```\n\n## 相关源码\n\n- **JavaScript SDK**: `packages/js-sdk/src/sandbox/sandboxApi.ts` - 沙箱 API 调用实现\n- **Python SDK**: `packages/python-sdk/e2b/sandbox/sandbox_api.py` - 沙箱 API 封装\n- **Python API Client**: `packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py` - 创建沙箱 API 请求\n- **命令处理**: `packages/js-sdk/src/sandbox/commands/commandHandle.ts` - 命令执行与生命周期交互\n- **Python 命令处理**: `packages/python-sdk/e2b/sandbox/commands/command_handle.py` - Python 命令执行\n\n---\n\n\n\n## 文件系统操作\n\n### 相关页面\n\n相关主题：[沙箱生命周期管理](#page-6), [Git 操作与网络配置](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)\n- [packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)\n- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)\n \n\n# 文件系统操作\n\nE2B 的文件系统操作模块提供了在沙箱（Sandbox）环境中读写文件和目录的完整能力。通过这个模块，用户可以在沙箱内执行文件浏览、读取、写入、监控等操作，是 E2B 沙箱与外部系统交互的核心途径之一。\n\n---\n\n## 模块概述\n\nE2B 的文件系统操作横跨两个主要 SDK：\n\n- **JavaScript/TypeScript SDK (`@e2b`)**：基于异步 API 设计，支持流式读取和多种返回格式\n- **Python SDK (`e2b`)**：提供同步和异步两套接口，与 Python 生态深度集成\n\n文件系统操作主要通过 `Sandbox` 实例的 `.filesystem` 属性访问，也可通过 Volume API 操作持久化存储卷中的文件。\n\n---\n\n## 核心功能\n\n### 读取文件\n\n文件系统模块支持以多种格式读取文件内容，适用于不同的使用场景。\n\n#### JavaScript SDK\n\n`Sandbox.filesystem.read()` 方法支持以下返回格式：\n\n| 格式 | 返回类型 | 说明 |\n|------|----------|------|\n| `text` | `string` | 文件内容作为文本（默认） |\n| `bytes` | `Uint8Array` | 文件内容作为字节数组 |\n| `blob` | `Blob` | Web API Blob 对象 |\n| `stream` | `ReadableStream` | 流式读取，适合大文件 |\n\n```typescript\nconst sandbox = await Sandbox.create('base')\n\n// 读取为文本\nconst content = await sandbox.filesystem.read('/path/to/file.txt', {\n format: 'text'\n})\n\n// 读取为字节数组\nconst bytes = await sandbox.filesystem.read('/path/to/file.bin', {\n format: 'bytes'\n})\n\n// 流式读取大文件\nconst stream = await sandbox.filesystem.read('/path/to/large.zip', {\n format: 'stream'\n})\n```\n\n**可选参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `user` | `string` | 以指定用户身份读取（需 envd 0.5.0+） |\n| `gzip` | `boolean` | 启用 gzip 解压缩传输 |\n\n资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts](packages/js-sdk/src/sandbox/filesystem/index.ts)\n\n#### Python SDK\n\n```python\nsandbox = await sb.Sandbox.create()\n\n# 读取为文本\ncontent = await sandbox.filesystem.read('/path/to/file.txt')\n\n# 读取为字节\ncontent = await sandbox.filesystem.read('/path/to/file.txt', format='bytes')\n```\n\n---\n\n### 写入文件\n\n写入操作支持批量写入多个文件，并自动创建必要的父目录。\n\n#### JavaScript SDK\n\n```typescript\nawait sandbox.filesystem.write([\n { path: '/app/config.json', data: JSON.stringify(config) },\n { path: '/app/index.js', data: 'console.log(\"hello\")' }\n])\n```\n\n#### Python SDK\n\n```python\nawait sandbox.filesystem.write([\n { 'path': '/app/config.json', 'data': json.dumps(config) },\n { path: '/app/index.js', 'data': 'console.log(\"hello\")' }\n])\n```\n\n**写入选项参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `user` | `string` | 以指定用户身份写入 |\n| `request_timeout` | `int` | 请求超时时间（毫秒） |\n| `gzip` | `boolean` | 使用 gzip 压缩传输 |\n| `use_octet_stream` | `boolean` | 使用 `application/octet-stream` 代替 `multipart/form-data`（需 envd 0.5.7+） |\n\n```python\n# 使用 octet-stream 方式上传，适合大文件\nawait sandbox.filesystem.write(\n [{ 'path': '/data/model.bin', 'data': model_bytes }],\n use_octet_stream=True,\n gzip=True\n)\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)\n\n---\n\n### 目录监控\n\nJavaScript SDK 提供了 `WatchHandle` 类用于监控目录变化。\n\n```typescript\nconst watchHandle = await sandbox.filesystem.watchDir('/app', (event) => {\n console.log(`${event.type}: ${event.name}`)\n})\n\n// 停止监控\nawait watchHandle.stop()\n```\n\n**事件类型：**\n\n| 事件类型 | 说明 |\n|----------|------|\n| `create` | 文件或目录被创建 |\n| `write` | 文件被写入 |\n| `remove` | 文件或目录被删除 |\n| `rename` | 文件或目录被重命名 |\n\n```typescript\n// 完整的监控示例\nconst watchHandle = await sandbox.filesystem.watchDir(\n '/workspace',\n (event) => {\n console.log(`文件 ${event.name} 发生 ${event.type} 事件`)\n },\n (error) => {\n console.error('监控出错:', error)\n }\n)\n```\n\n`WatchHandle` 类的结构：\n\n```typescript\nclass WatchHandle {\n // 停止监控\n async stop(): void\n \n // 内部事件迭代器\n private async *iterateEvents(): AsyncIterator\n \n // 内部事件处理器\n private async handleEvents(): Promise\n}\n```\n\n资料来源：[packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)\n\n---\n\n### Volume 文件操作\n\nVolume API 提供了对持久化存储卷的文件操作能力，接口设计与普通文件系统类似。\n\n```typescript\nconst volume = await Volume.get(volumeId)\n\n// 读取 Volume 中的文件\nconst content = await volume.readFile('/data/file.txt')\n\n// 读取为不同格式\nconst bytes = await volume.readFile('/data/archive.zip', {\n format: 'bytes'\n})\n```\n\n**Volume API 读取格式：**\n\n| 格式 | 返回类型 | 说明 |\n|------|----------|------|\n| `text` | `string` | 文件内容作为文本（默认） |\n| `bytes` | `Uint8Array` | 文件内容作为字节数组 |\n| `blob` | `Blob` | Web API Blob 对象 |\n| `stream` | `ReadableStream` | 流式读取 |\n\n```typescript\n// 流式读取大文件\nconst stream = await volume.readFile('/data/dataset.csv', {\n format: 'stream',\n requestTimeoutMs: 120000\n})\n\n// 处理流式数据\nfor await (const chunk of stream) {\n processChunk(chunk)\n}\n```\n\n**Volume 读取选项：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `requestTimeoutMs` | `number` | 请求超时时间（毫秒） |\n| `signal` | `AbortSignal` | 可中止的请求信号 |\n\n资料来源：[packages/js-sdk/src/volume/index.ts](packages/js-sdk/src/volume/index.ts)\n\n---\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Sandbox.filesystem]\n A --> C[Volume.readFile]\n \n B --> D[FilesystemConnection]\n C --> E[VolumeConnection]\n \n D --> F[envd API]\n E --> G[Volume API]\n \n F --> H[沙箱 envd 服务]\n G --> I[E2B Volume 服务]\n \n H --> J[沙箱文件系统]\n I --> K[持久化存储]\n```\n\n### 文件读取流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant FS as Filesystem\n participant API as envd API\n participant Envd as envd 服务\n\n User->>FS: read(path, opts)\n FS->>API: GET /files?path=...\n API->>Envd: 请求文件内容\n Envd-->>API: 文件内容\n API-->>FS: 返回响应\n FS-->>User: 根据格式返回结果\n```\n\n---\n\n## 版本兼容性\n\n### 用户身份参数\n\nenvd 版本对 `user` 参数的支持：\n\n```typescript\n// envd < 0.5.0：使用默认用户\n// envd >= 0.5.0：可指定 user 参数\n\nlet user = opts?.user\nif (\n user == undefined &&\n compareVersions(this.envdApi.version, ENVD_DEFAULT_USER) < 0\n) {\n user = defaultUsername // 回退到默认用户\n}\n```\n\n### Octet Stream 上传\n\n`use_octet_stream` 选项需要特定 envd 版本支持：\n\n```python\nsupports_octet_stream = self._envd_version >= ENVD_OCTET_STREAM_UPLOAD\nuse_octet_stream = use_octet_stream and supports_octet_stream\n```\n\n如果不支持，会自动回退到 `multipart/form-data` 方式上传。\n\n资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)\n\n---\n\n## 错误处理\n\n### 常见错误类型\n\n| 错误类型 | 说明 | 处理方式 |\n|----------|------|----------|\n| `NotFoundError` | 文件或目录不存在 | 检查路径是否正确 |\n| `TimeoutError` | 请求超时 | 增加 `requestTimeoutMs` |\n| `PermissionError` | 权限不足 | 使用 `user` 参数指定有权限的用户 |\n| `NetworkError` | 网络连接问题 | 检查网络和沙箱状态 |\n\n### 404 错误处理\n\n```typescript\nconst res = await volume.api.GET('/volumecontent/{volumeID}/file', {...})\n\nif (res.response.status === 404) {\n throw new NotFoundError(`Path ${path} not found`)\n}\n```\n\n---\n\n## 最佳实践\n\n### 1. 选择合适的读取格式\n\n```typescript\n// 小文件：使用 text 或 bytes\nconst config = await sandbox.filesystem.read('/app/config.json', {\n format: 'text'\n})\n\n// 大文件：使用 stream 避免内存溢出\nconst stream = await sandbox.filesystem.read('/data/large-file.bin', {\n format: 'stream'\n})\n\n// Web 环境：使用 blob\nconst blob = await sandbox.filesystem.read('/assets/bundle.js', {\n format: 'blob'\n})\n```\n\n### 2. 批量写入优化\n\n```python\n# 好的做法：批量写入减少请求次数\nawait sandbox.filesystem.write([\n { 'path': f'/app/file{i}.txt', 'data': content }\n for i in range(100)\n])\n\n# 避免：逐个写入（性能差）\nfor i in range(100):\n await sandbox.filesystem.write([\n { 'path': f'/app/file{i}.txt', 'data': content }\n ])\n```\n\n### 3. 启用 gzip 压缩\n\n```typescript\n// 对于文本内容，启用 gzip 可显著减少传输时间\nconst content = await sandbox.filesystem.read('/app/large.json', {\n gzip: true\n})\n```\n\n### 4. 目录监控资源管理\n\n```typescript\n// 务必在不需要时停止监控\nconst watchHandle = await sandbox.filesystem.watchDir('/workspace', onEvent)\n\n// 使用完毕后清理\ntry {\n await doWork()\n} finally {\n await watchHandle.stop()\n}\n```\n\n---\n\n## 总结\n\nE2B 的文件系统操作模块提供了完整、一致且易用的文件操作接口。核心特点包括：\n\n- **多格式支持**：text、bytes、blob、stream 满足不同场景需求\n- **流式处理**：对大文件提供流式读取，避免内存压力\n- **压缩传输**：可选 gzip 压缩优化网络传输\n- **目录监控**：支持实时监控文件系统变化事件\n- **Volume 集成**：可操作持久化存储卷中的文件\n- **跨 SDK 一致**：JavaScript 和 Python SDK 提供相似的接口设计\n\n---\n\n\n\n## Git 操作与网络配置\n\n### 相关页面\n\n相关主题：[沙箱生命周期管理](#page-6), [文件系统操作](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/git/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/git/index.ts)\n- [packages/python-sdk/e2b/sandbox_sync/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/git.py)\n- [packages/python-sdk/e2b/sandbox_async/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/git.py)\n- [packages/python-sdk/e2b/sandbox/_git/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/__init__.py)\n- [packages/python-sdk/e2b/sandbox/_git/args.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/args.py)\n- [packages/js-sdk/src/sandbox/network.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/network.ts)\n- [packages/python-sdk/e2b/sandbox/network.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/network.py)\n \n\n# Git 操作与网络配置\n\n## 概述\n\nE2B 平台提供了在沙箱环境中执行 Git 操作和配置网络设置的完整功能。Git 操作主要通过模板构建器（Template Builder）在沙箱镜像构建阶段执行，支持克隆仓库、指定分支、浅克隆等常用功能。网络配置则允许用户在创建沙箱时控制网络访问权限和 MCP 网关的网络设置。\n\n## Git 操作\n\n### 模板中的 Git 克隆\n\n在 E2B 中，Git 操作主要通过 `Template` 类的 `git_clone` 方法实现。该方法在镜像构建阶段执行，而非沙箱运行时执行，这意味着所有 Git 相关的准备工作需要在构建模板时完成。\n\n```mermaid\ngraph TD\n A[创建 Template 实例] --> B[选择基础镜像]\n B --> C[调用 git_clone 方法]\n C --> D[执行 git clone 命令]\n D --> E[构建并部署模板]\n E --> F[沙箱启动时已包含克隆的仓库]\n```\n\n### Python SDK 中的 Git 操作\n\n#### git_clone 方法签名\n\n```python\ndef git_clone(\n self,\n url: str,\n path: Optional[Union[str, Path]] = None,\n branch: Optional[str] = None,\n depth: Optional[int] = None,\n user: Optional[str] = None,\n) -> \"TemplateBuilder\":\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| url | str | 是 | Git 仓库的完整 URL 地址 |\n| path | str 或 Path | 否 | 克隆目标路径 |\n| branch | str | 否 | 指定分支名称 |\n| depth | int | 否 | 浅克隆的提交历史深度 |\n| user | str | 否 | 执行命令的用户身份 |\n\n#### 使用示例\n\n```python\nfrom e2b import Template\n\n# 基本克隆\ntemplate = (\n Template()\n .from_python_image(\"3.11\")\n .git_clone(\"https://github.com/user/repo.git\", \"/app/repo\")\n)\n\n# 指定分支的浅克隆\ntemplate = (\n Template()\n .from_node_image(\"24\")\n .git_clone(\n \"https://github.com/user/repo.git\",\n path=\"/workspace/project\",\n branch=\"main\",\n depth=1\n )\n)\n\n# 以 root 用户身份克隆\ntemplate = (\n Template()\n .from_base_image()\n .git_clone(\n \"https://github.com/user/repo.git\",\n \"/root/repo\",\n user=\"root\"\n )\n)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### JavaScript SDK 中的 Git 操作\n\n#### gitClone 方法签名\n\n```typescript\ngitClone(\n url: string,\n path?: string,\n options?: {\n branch?: string;\n depth?: number;\n },\n user?: string\n): TemplateBuilder\n```\n\n#### 使用示例\n\n```typescript\nimport { Template } from 'e2b'\n\n// 基本克隆\nconst template = Template()\n .fromPythonImage('3')\n .gitClone('https://github.com/user/repo.git', '/app/repo')\n\n// 指定分支和深度的克隆\nconst template = Template()\n .fromNodeImage('24')\n .gitClone(\n 'https://github.com/user/repo.git',\n '/workspace/project',\n { branch: 'main', depth: 1 }\n )\n```\n\n### git clone 命令生成\n\n底层实现通过构建 `git clone` 命令行参数来实现功能：\n\n```python\nargs = [\"git\", \"clone\", url]\nif branch:\n args.append(f\"--branch {branch}\")\n args.append(\"--single-branch\")\nif depth:\n args.append(f\"--depth {depth}\")\nif path:\n args.append(str(path))\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n## 网络配置\n\n### 沙箱网络访问控制\n\nE2B 沙箱支持网络访问权限控制，用户可以在创建沙箱时通过 `allow_internet_access` 参数决定是否允许沙箱访问外部网络。\n\n```mermaid\ngraph LR\n A[沙箱创建请求] --> B{allow_internet_access}\n B -->|True| C[允许访问外部网络]\n B -->|False| D[禁止访问外部网络]\n C --> E[可访问互联网资源]\n D --> F[仅限内部网络通信]\n```\n\n### Python SDK 网络配置\n\n#### 同步沙箱创建\n\n```python\nwith Sandbox.create(\n allow_internet_access=True, # 允许网络访问\n network=True # 启用网络功能\n) as sandbox:\n result = sandbox.commands.run(\"curl https://api.example.com\")\n```\n\n#### 异步沙箱创建\n\n```python\nsandbox = await Sandbox.create(\n allow_internet_access=True,\n network=True,\n lifecycle=Lifecycle.KEEP_ALIVE\n)\n```\n\n#### 网络参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| allow_internet_access | bool | None | 控制沙箱是否可访问外部网络 |\n| network | bool | True | 启用沙箱网络功能 |\n\n资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n\n### JavaScript SDK 网络配置\n\n```typescript\nconst sandbox = await Sandbox.create({\n allowInternetAccess: true,\n network: true,\n})\n```\n\n## MCP 网关网络配置\n\n### MCP 服务器添加\n\n在 Python SDK 中，可以使用 `add_mcp_server` 方法为模板添加 MCP（Model Context Protocol）服务器。该功能要求基础镜像已预装 mcp-gateway。\n\n```python\ndef add_mcp_server(self, servers: Union[str, List[str]]) -> \"TemplateBuilder\":\n```\n\n#### 使用示例\n\n```python\ntemplate = (\n Template()\n .from_base_image() # 需使用包含 mcp-gateway 的镜像\n .add_mcp_server('exa')\n .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n)\n```\n\n#### 前置条件检查\n\n```python\nif self._template._base_template != \"mcp-gateway\":\n raise BuildException(\n \"Devcontainers can only used in the devcontainer base template\"\n )\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### MCP 网关启动配置\n\n在沙箱运行时，MCP 网关通过特定命令启动，并使用环境变量进行认证配置：\n\n```python\ntoken = str(uuid.uuid4())\nsandbox._mcp_token = token\n\nres = sandbox.commands.run(\n f\"mcp-gateway --config {shlex.quote(json.dumps(mcp))}\",\n user=\"root\",\n envs={\"GATEWAY_ACCESS_TOKEN\": token},\n)\n```\n\n| 配置项 | 说明 |\n|--------|------|\n| mcp-gateway | MCP 网关可执行文件 |\n| --config | MCP 服务器配置 JSON |\n| GATEWAY_ACCESS_TOKEN | 网关访问认证令牌 |\n\n资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n\n## 环境变量配置\n\n### Git 操作环境配置\n\n在执行 Git 操作时，可以通过 `set_envs` 方法设置环境变量：\n\n```python\ntemplate.set_envs({\n 'GIT_TERMINAL_PROMPT': '0', # 禁用 Git 交互提示\n 'GIT_SSL_NO_VERIFY': 'true' # 禁用 SSL 验证（测试环境）\n})\n```\n\n#### set_envs 方法实现\n\n```python\ninstruction: Instruction = {\n \"type\": InstructionType.ENV,\n \"args\": [item for key, value in envs.items() for item in [key, value]],\n \"force\": self._template._force_next_layer,\n \"forceUpload\": None,\n}\nself._template._instructions.append(instruction)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n## 缓存控制\n\n### 跳过缓存构建\n\n对于需要强制重新构建的指令，可以使用 `skip_cache` 方法：\n\n```python\ntemplate.skip_cache().run_cmd('apt-get update')\n```\n\n此方法会设置 `_force_next_layer = True`，确保后续指令及其所有层都重新构建，忽略任何缓存层。\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n## 完整使用示例\n\n### Python SDK 综合示例\n\n```python\nfrom e2b import Template, Sandbox\n\n# 创建包含 Git 仓库和 MCP 服务器的模板\ntemplate = (\n Template()\n .from_python_image(\"3.11\")\n .git_clone(\n \"https://github.com/user/private-repo.git\",\n \"/app/repo\",\n branch=\"main\",\n depth=1\n )\n .set_envs({\n \"GIT_TERMINAL_PROMPT\": \"0\",\n \"APP_ENV\": \"production\"\n })\n .run_cmd(\"pip install -r requirements.txt\")\n)\n\n# 构建模板\nbuild_info = template.build(\"my-app-template:v1.0\")\n\n# 使用模板创建沙箱并启用网络\nwith Sandbox.create(\n template=build_info.template_id,\n allow_internet_access=True,\n metadata={\"user\": \"developer\"}\n) as sandbox:\n # 执行应用程序\n result = sandbox.commands.run(\"python /app/repo/main.py\")\n print(result.stdout)\n```\n\n### JavaScript SDK 综合示例\n\n```typescript\nimport { Template, Sandbox } from 'e2b'\n\n// 创建模板\nconst template = Template()\n .fromNodeImage('24')\n .gitClone(\n 'https://github.com/user/repo.git',\n '/workspace/project',\n { branch: 'main', depth: 1 }\n )\n .setEnvs({ NODE_ENV: 'production' })\n .runCmd('npm install')\n\n// 构建并部署\nconst buildInfo = await Template.build(template, 'my-node-app:v1.0')\n\n// 创建沙箱\nconst sandbox = await Sandbox.create({\n template: buildInfo.template.id,\n allowInternetAccess: true,\n})\n\nconst result = await sandbox.commands.run('node /workspace/project/index.js')\nconsole.log(result.stdout)\n```\n\n## 架构流程图\n\n```mermaid\ngraph TD\n subgraph 模板构建阶段\n A[定义 Template] --> B[选择基础镜像]\n B --> C[执行 Git 克隆]\n C --> D[设置环境变量]\n D --> E[安装依赖]\n E --> F[构建 Docker 镜像]\n F --> G[部署到 E2B]\n end\n \n subgraph 沙箱运行阶段\n G --> H[创建沙箱实例]\n H --> I{allow_internet_access}\n I -->|True| J[启用网络访问]\n I -->|False| K[禁用网络访问]\n J --> L[运行用户代码]\n K --> L\n L --> M[执行命令]\n M --> N[访问网络资源]\n end\n \n subgraph MCP 网关配置\n O[配置 MCP 服务器]\n O --> P[启动 mcp-gateway]\n P --> Q[设置访问令牌]\n Q --> R[MCP 服务器就绪]\n end\n \n L -.-> R\n```\n\n## 注意事项\n\n1. **Git 凭证管理**：对于私有仓库，需要在模板构建前配置适当的认证方式\n2. **网络隔离**：生产环境中应根据需求谨慎设置 `allow_internet_access`\n3. **基础镜像要求**：使用 MCP 功能需要选择包含 mcp-gateway 的基础镜像\n4. **缓存策略**：开发调试时可使用 `skip_cache()` 强制重新构建\n\n---\n\n\n\n## 模板系统与构建\n\n### 相关页面\n\n相关主题：[模板生成器与 Handlebars 模板](#page-10), [CLI 命令行工具](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/python-sdk/e2b/template/types.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/types.py)\n- [packages/python-sdk/e2b/template_async/build_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/build_api.py)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n \n\n# 模板系统与构建\n\n## 概述\n\nE2B 的模板系统是一套用于构建沙箱运行环境的配置框架，允许开发者通过声明式 API 定义沙箱的基础镜像、系统依赖、应用依赖、环境变量以及启动命令。该系统支持 JavaScript SDK 和 Python SDK，提供了统一且直观的接口来创建可复用的沙箱模板。\n\n模板系统的核心是 `TemplateBuilder` 类，它采用链式调用模式（Builder Pattern），允许开发者通过 fluent API 逐步配置模板的各个组成部分。构建完成的模板可以通过 SDK 的 `build` 方法部署到 E2B 基础设施上，生成可供沙箱使用的镜像。\n\n## 核心概念\n\n### 模板状态机\n\n模板在构建过程中经历以下状态转换：\n\n```mermaid\nstateDiagram-v2\n [*] --> TemplateBuilder: 初始化\n TemplateBuilder --> TemplateBuilder: 添加指令\n TemplateBuilder --> TemplateBuilder: 安装依赖\n TemplateBuilder --> TemplateFinal: set_start_cmd()\n TemplateFinal --> [*]: Template.build()\n \n state TemplateBuilder {\n [*] --> withInstructions\n withInstructions --> withInstructions\n }\n \n state TemplateFinal {\n [*] --> readyToBuild\n }\n```\n\n- **TemplateBuilder**：模板构建器状态，可以添加各种构建指令\n- **TemplateFinal**：模板最终状态，仅在设置启动命令后达到，此时模板才能被构建\n\n资料来源：[packages/js-sdk/src/template/types.ts:50-55]()\n\n### 基础镜像选择\n\nE2B 支持多种基础镜像类型，通过不同的方法选择：\n\n| 方法 | 描述 | 用途 |\n|------|------|------|\n| `fromBaseImage()` | 使用默认基础镜像 | 创建通用沙箱环境 |\n| `fromPythonImage(tag?)` | 使用 Python 镜像 | Python 应用开发 |\n| `fromImage(name)` | 使用指定镜像 | 自定义镜像需求 |\n\n资料来源：[packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n\n## JavaScript SDK 模板 API\n\n### 安装包管理器\n\n#### Bun 安装\n\n```typescript\n// 安装单个包\ntemplate.bunInstall('express')\n\n// 安装多个包\ntemplate.bunInstall(['lodash', 'axios'])\n\n// 全局安装\ntemplate.bunInstall('typescript', { g: true })\n\n// 安装为开发依赖\ntemplate.bunInstall('tsx', { dev: true })\n\n// 从 package.json 安装\ntemplate.bunInstall()\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:100-115]()\n\n#### npm 安装\n\n```typescript\n// 安装单个包\ntemplate.npmInstall('express')\n\n// 安装多个包\ntemplate.npmInstall(['lodash', 'axios'])\n\n// 全局安装\ntemplate.npmInstall('typescript', { g: true })\n```\n\n#### pip 安装\n\n```typescript\n// 安装单个包\ntemplate.pipInstall('flask')\n\n// 安装多个包\ntemplate.pipInstall(['flask', 'requests'])\n\n// 安装 requirements.txt\ntemplate.pipInstall()\n```\n\n### 系统包安装\n\n#### apt-get 安装\n\n```typescript\n// 安装单个系统包\ntemplate.aptInstall('vim')\n\n// 安装多个系统包\ntemplate.aptInstall(['git', 'curl', 'wget'])\n\n// 不安装推荐包\ntemplate.aptInstall(['vim'], { noInstallRecommends: true })\n\n// 修复缺失依赖\ntemplate.aptInstall(['vim'], { fixMissing: true })\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:125-140]()\n\n### 环境变量配置\n\n```typescript\n// 设置环境变量\ntemplate.setEnvs({\n NODE_ENV: 'production',\n PORT: '8080',\n DATABASE_URL: 'postgres://localhost:5432/mydb'\n})\n```\n\n环境变量通过 `InstructionType.ENV` 指令类型添加到指令列表中。\n\n### MCP 服务器集成\n\nE2B 支持通过 mcp-gateway 集成 MCP (Model Context Protocol) 服务器：\n\n```typescript\n// 添加单个 MCP 服务器\ntemplate.addMcpServer('exa')\n\n// 添加多个 MCP 服务器\ntemplate.addMcpServer(['brave', 'firecrawl', 'duckduckgo'])\n```\n\n**注意**：使用 MCP 服务器功能需要基础镜像预装 mcp-gateway（如 `mcp-gateway` 镜像）。\n\n资料来源：[packages/js-sdk/src/template/types.ts:150-160]()\n\n### Devcontainer 支持\n\n```typescript\n// 克隆仓库并启动 devcontainer\ntemplate\n .gitClone('https://myrepo.com/project.git', '/my-devcontainer')\n .startDevcontainer('/my-devcontainer')\n\n// 预构建并启动 devcontainer\ntemplate\n .gitClone('https://myrepo.com/project.git', '/my-devcontainer')\n .betaDevContainerPrebuild('/my-devcontainer')\n .betaSetDevContainerStart('/my-devcontainer')\n```\n\n### 设置启动命令\n\n```typescript\n// 使用字符串命令\ntemplate.setStartCmd(\n 'python app.py',\n 'curl -f http://localhost:3000/health'\n)\n\n// 使用 ReadyCmd 对象\ntemplate.setStartCmd(\n 'python app.py',\n {\n cmd: 'curl -f http://localhost:3000/health',\n timeout: 30000\n }\n)\n```\n\n`setStartCmd` 方法将模板状态从 `TemplateBuilder` 转换为 `TemplateFinal`，此时模板才能被构建。\n\n## Python SDK 模板 API\n\n### 初始化与构建\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_base_image()\n .run_cmd(\"echo Hello World E2B!\")\n)\n\n# 构建模板\nbuild_info = Template.build(template, \"my-template:v1.0\")\n```\n\n### 安装依赖\n\n#### Bun 安装\n\n```python\n# 安装单个包\ntemplate.bun_install('express')\n\n# 安装多个包\ntemplate.bun_install(['lodash', 'axios'])\n\n# 全局安装\ntemplate.bun_install('typescript', g=True)\n\n# 开发依赖\ntemplate.bun_install('tsx', dev=True)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:150-175]()\n\n#### apt-get 安装\n\n```python\n# 安装系统包\ntemplate.apt_install('vim')\ntemplate.apt_install(['git', 'curl', 'wget'])\n\n# 不安装推荐包\ntemplate.apt_install('vim', no_install_recommends=True)\n\n# 修复缺失依赖\ntemplate.apt_install('vim', fix_missing=True)\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:190-215]()\n\n### MCP 服务器\n\n```python\n# 添加 MCP 服务器\ntemplate.add_mcp_server('exa')\ntemplate.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])\n```\n\n## 构建选项\n\n### JavaScript SDK\n\n```typescript\ninterface BuildOptions {\n // 镜像标签（可选）\n tags?: string[]\n}\n```\n\n```typescript\n// 简单命名\nawait Template.build(template, 'my-template:v1.0')\n\n// 多标签构建\nawait Template.build(template, 'my-template', { \n tags: ['v1.0', 'stable', 'latest'] \n})\n```\n\n### Python SDK\n\n```python\n# 异步构建\nimport asyncio\nfrom e2b import Template, AsyncTemplate\n\nasync def build_template():\n template = Template().from_base_image().run_cmd(\"echo test\")\n build_info = await AsyncTemplate.build(template, \"my-template:v1.0\")\n```\n\n## Docker 注册表配置\n\nE2B 支持配置通用 Docker 注册表认证：\n\n```typescript\ntype GenericDockerRegistry = {\n type: 'registry'\n username: string\n password: string\n}\n```\n\n此配置允许访问私有 Docker 镜像仓库。\n\n## CLI 命令行工具\n\nE2B CLI 提供了模板构建的命令行接口：\n\n```bash\n# 构建模板\ne2b template build\n\n# 初始化新模板\ne2b template init\n```\n\nCLI 使用 `getDockerfile` 函数获取 Dockerfile 内容：\n\n```typescript\nexport function getDockerfile(root: string, file?: string) {\n // 检查用户指定的 Dockerfile\n if (file) {\n const dockerfilePath = path.join(root, file)\n // ...\n }\n // 否则使用默认 Dockerfile\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:55-80]()\n\n## 模板构建流程\n\n```mermaid\ngraph TD\n A[创建 Template] --> B[选择基础镜像]\n B --> C[安装系统包]\n C --> D[安装应用包]\n D --> E[设置环境变量]\n E --> F[配置 MCP 服务器]\n F --> G[设置启动命令]\n G --> H[调用 build 方法]\n H --> I[上传到 E2B 云端]\n I --> J[构建 Docker 镜像]\n J --> K[模板就绪]\n```\n\n## 缓存控制\n\n模板系统支持选择性跳过缓存层：\n\n```typescript\n// 跳过后续构建指令的缓存\ntemplate.skip_cache().runCmd('apt-get update')\n```\n\n这对于需要强制重新执行某些关键指令的场景非常有用。\n\n## 错误处理\n\n### SDK 版本兼容性检查\n\n```typescript\nif (compareVersions(res.data!.envdVersion, '0.1.0') < 0) {\n await this.kill(res.data!.sandboxID, opts)\n throw new TemplateError(\n 'You need to update the template to use the new SDK.'\n )\n}\n```\n\n### CLI 构建错误\n\n```typescript\ncase 'error':\n throw new Error(\n `Building sandbox template failed.\\n` +\n `Check the logs above for more details or contact us (https://e2b.dev/docs/support)`\n )\n```\n\n## 最佳实践\n\n1. **使用特定版本标签**：为模板指定明确的版本号，避免使用 `latest` 造成不一致\n2. **合理拆分依赖**：将系统依赖和应用依赖分开，便于缓存复用\n3. **使用 skip_cache 策略**：仅在必要时跳过缓存，减少构建时间\n4. **健康检查命令**：为 `set_start_cmd` 配置合理的 ready_cmd，确保沙箱真正就绪\n5. **环境变量管理**：使用环境变量而非硬编码配置值，提高模板可复用性\n\n## 相关资源\n\n- [JavaScript SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [Python SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [CLI 工具文档](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n\n---\n\n\n\n## 模板生成器与 Handlebars 模板\n\n### 相关页面\n\n相关主题：[模板系统与构建](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/commands/template/generators/handlebars.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/generators/handlebars.ts)\n- [packages/cli/src/commands/template/generators/template-generator.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/generators/template-generator.ts)\n- [packages/cli/src/templates/python-template.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/python-template.hbs)\n- [packages/cli/src/templates/typescript-template.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/typescript-template.hbs)\n- [packages/cli/src/templates/python-build-sync.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/python-build-sync.hbs)\n \n\n# 模板生成器与 Handlebars 模板\n\n## 概述\n\nE2B 的模板生成器（Template Generator）是 CLI 工具中负责将 `Template` 类实例转换为可部署模板的核心组件。它使用 [Handlebars](https://handlebarsjs.com/) 模板引擎来生成各种格式的输出，包括 Dockerfile、启动脚本和使用示例代码。\n\n模板生成器的主要职责包括：\n\n- 将 `TemplateClass` 实例序列化为中间 JSON 格式\n- 通过 Handlebars 模板引擎处理数据并生成最终输出\n- 支持多种编程语言的代码示例生成（Python SDK、JS/TS SDK）\n- 提供自定义 Handlebars helpers 用于模板逻辑处理\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[TemplateClass 实例] --> B[transformTemplateData]\n B --> C[TemplateJSON + HandlebarStep]\n C --> D[Handlebars 模板引擎]\n D --> E[最终输出]\n \n F[Handlebars 类] --> G[eq helper]\n F --> H[escapeQuotes helper]\n F --> I[escapeDoubleQuotes helper]\n \n J[模板类型] --> K[python-template.hbs]\n J --> L[typescript-template.hbs]\n J --> M[python-build-sync.hbs]\n```\n\n### 处理流程\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 命令\n participant TG as TemplateGenerator\n participant HB as Handlebars\n participant TPL as .hbs 模板文件\n \n CLI->>TG: 调用生成方法\n TG->>TG: transformTemplateData()\n TG->>TG: 解析 Template.toJSON()\n TG->>HB: 编译模板\n HB->>TPL: 读取 .hbs 文件\n TPL-->>HB: 模板内容\n HB-->>TG: 渲染结果\n TG-->>CLI: 返回生成的代码\n```\n\n## Handlebars 核心实现\n\n### Handlebars 类\n\n`Handlebars` 类是 Handlebars 库的封装，提供了模板编译和自定义 helpers 的支持。\n\n**文件位置**: `packages/cli/src/commands/template/generators/handlebars.ts`\n\n#### 类结构\n\n```typescript\nclass Handlebars {\n private handlebars: typeof HandlebarsLib\n\n constructor() {\n const handlebars = HandlebarsLib.create()\n handlebars.registerHelper('eq', function (a: any, b: any, options: any) {\n if (a === b) {\n return options.fn(this)\n }\n return ''\n })\n\n handlebars.registerHelper('escapeQuotes', function (str) {\n return str ? str.replace(/'/g, \"\\\\'\") : str\n })\n\n handlebars.registerHelper('escapeDoubleQuotes', function (str) {\n return str ? str.replace(/\"/g, '\\\\\"') : str\n })\n\n this.handlebars = handlebars\n }\n\n compile(template: string) {\n return this.handlebars.compile(template)\n }\n}\n```\n\n资料来源：[packages/cli/src/commands/template/generators/handlebars.ts:1-40]()\n\n### 自定义 Helpers\n\n模板系统提供了三个核心自定义 helpers：\n\n| Helper 名称 | 功能 | 示例 |\n|------------|------|------|\n| `eq` | 相等比较，类似于 `{{#if (eq a b)}}` | `{{#eq type \"RUN\"}}...{{/eq}}` |\n| `escapeQuotes` | 转义单引号 | `{{escapeQuotes str}}` |\n| `escapeDoubleQuotes` | 转义双引号 | `{{escapeDoubleQuotes str}}` |\n\n#### eq Helper\n\n用于在模板中进行条件渲染，类似于 Handlebars 内置的 `if` 但支持相等判断：\n\n```handlebars\n{{#eq instruction.type \"RUN\"}}\nRUN {{instruction.args.[0]}}\n{{/eq}}\n```\n\n#### escapeQuotes Helper\n\n用于转义字符串中的单引号，防止在 JavaScript/TypeScript 代码中产生语法错误：\n\n```handlebars\n{{escapeQuotes command}}\n```\n\n#### escapeDoubleQuotes Helper\n\n用于转义字符串中的双引号，防止在需要双引号包裹的上下文中产生语法错误：\n\n```handlebars\n{{escapeDoubleQuotes filename}}\n```\n\n## 数据转换层\n\n### transformTemplateData 函数\n\n该函数负责将 `TemplateClass` 实例转换为 Handlebars 模板可用的数据格式。\n\n**签名**:\n\n```typescript\nexport async function transformTemplateData(\n template: TemplateClass\n): Promise\n```\n\n#### HandlebarStep 接口\n\n```typescript\ninterface HandlebarStep {\n type: string\n args?: string[]\n envVars?: Record\n src?: string\n dest?: string\n}\n```\n\n#### 转换过程\n\n1. 调用 `Template.toJSON(template, false)` 获取 JSON 表示\n2. 解析 JSON 为 `TemplateWithStepsJSON` 类型\n3. 返回包含 steps 数组的合并结果\n\n资料来源：[packages/cli/src/commands/template/generators/handlebars.ts:59-74]()\n\n## 模板类型\n\n### 模板文件列表\n\nE2B CLI 提供了多种预定义的 Handlebars 模板：\n\n| 模板文件 | 用途 |\n|---------|------|\n| `python-template.hbs` | Python SDK 使用示例生成 |\n| `typescript-template.hbs` | TypeScript SDK 使用示例生成 |\n| `python-build-sync.hbs` | Python 构建同步代码生成 |\n\n### python-template.hbs\n\n用于生成 Python SDK 的使用示例代码，包含：\n\n- 模板初始化代码\n- 环境变量设置\n- 包安装指令\n- 启动命令配置\n\n### typescript-template.hbs\n\n用于生成 TypeScript/JavaScript SDK 的使用示例代码，包含：\n\n- TypeScript 类型安全的模板构建\n- 异步操作处理\n- 错误处理模式\n\n### python-build-sync.hbs\n\n用于生成同步构建相关的 Python 代码，支持：\n\n- 同步模板构建流程\n- 构建状态轮询\n- 结果处理\n\n## 模板指令类型\n\n在 E2B 模板系统中，每条构建指令都被序列化为特定的数据结构：\n\n### 指令类型枚举\n\n| 类型 | 说明 | 生成的 Dockerfile 指令 |\n|------|------|----------------------|\n| `RUN` | 执行命令 | `RUN ` |\n| `COPY` | 复制文件 | `COPY ` |\n| `ENV` | 设置环境变量 | `ENV =` |\n| `WORKDIR` | 设置工作目录 | `WORKDIR ` |\n| `USER` | 设置用户 | `USER ` |\n\n### 指令数据结构\n\n```typescript\ninterface Instruction {\n type: InstructionType\n args: string[]\n force?: boolean\n forceUpload?: string | null\n}\n```\n\n## Dockerfile 生成\n\n`Template` 类提供了 `toDockerfile()` 方法用于生成 Dockerfile 内容：\n\n```typescript\nprivate toDockerfile(): string {\n let dockerfile = `FROM ${this.baseImage}\\n`\n for (const instruction of this.instructions) {\n if (instruction.type === InstructionType.RUN) {\n dockerfile += `RUN ${instruction.args[0]}\\n`\n continue\n }\n if (instruction.type === InstructionType.COPY) {\n dockerfile += `COPY ${instruction.args[0]} ${instruction.args[1]}\\n`\n continue\n }\n if (instruction.type === InstructionType.ENV) {\n const values: string[] = []\n for (let i = 0; i < instruction.args.length; i += 2) {\n values.push(`${instruction.args[i]}=${instruction.args[i + 1]}`)\n }\n dockerfile += `ENV ${values.join(' ')}\\n`\n continue\n }\n dockerfile += `${instruction.type} ${instruction.args.join(' ')}\\n`\n }\n if (this.startCmd) {\n dockerfile += `ENTRYPOINT ${this.startCmd}\\n`\n }\n return dockerfile\n}\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts]()\n\n## 使用示例\n\n### 基础模板构建\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image(\"3.11\")\n .pip_install(\"flask\")\n .run_cmd(\"mkdir -p /app\")\n .set_workdir(\"/app\")\n .set_start_cmd(\"python app.py\", \"curl http://localhost:5000/health\")\n)\n```\n\n### CLI 命令行使用\n\n```bash\ne2b template build --name my-template\n```\n\n生成的输出包含：\n\n- ✅ 构建成功的确认消息\n- Python SDK 使用示例\n- JavaScript/TypeScript SDK 使用示例\n\n资料来源：[packages/cli/src/commands/template/create.ts]()\n\n## 错误处理\n\n模板生成过程中的错误处理机制：\n\n| 错误场景 | 处理方式 |\n|---------|---------|\n| Dockerfile 不存在 | 抛出文件未找到错误 |\n| 构建失败 | 输出错误日志并显示支持链接 |\n| 指令解析失败 | 抛出 JSON 解析错误 |\n\n```typescript\nif (dockerfileContent === undefined) {\n throw new Error(\n `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`\n )\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts]()\n\n## 最佳实践\n\n### 1. 模板命名规范\n\n- 使用描述性名称：`my-app-template`\n- 支持标签语法：`my-app:v1.0`\n\n### 2. 指令顺序\n\n推荐顺序：\n\n1. `from_image()` 或其他基础镜像方法\n2. `set_envs()` 环境变量设置\n3. `run_cmd()` 系统命令\n4. `pip_install()` / `npm_install()` 包安装\n5. `copy()` 文件复制\n6. `set_workdir()` 工作目录设置\n7. `set_start_cmd()` 启动命令\n\n### 3. 缓存优化\n\n使用 `skip_cache()` 方法跳过特定指令的缓存：\n\n```python\ntemplate.skip_cache().run_cmd(\"apt-get update\")\n```\n\n### 4. 环境变量转义\n\n当在模板中使用特殊字符时，使用相应的转义 helpers：\n\n```handlebars\n{{escapeQuotes env_value}}\n```\n\n## 相关文档\n\n- [E2B Python SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [E2B JS SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [E2B CLI 文档](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n- [模板 API 类型定义](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：e2b-dev/E2B\n\n摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths。\n\n## 1. 配置坑 · 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b063fe8cb80490584e7647332a2c4c6 | https://github.com/e2b-dev/E2B/issues/1331 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：process was not killed when auto paused\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Closed Port Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：build status polling timed out\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：Support `AbortSignal` in JS SDK methods for request cancellation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Support `AbortSignal` in JS SDK methods for request cancellation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f74f7dd596784e88aff40ef33d5b505e | https://github.com/e2b-dev/E2B/issues/1312 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Docker Build Secrets Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Template Build Fails with \"syncing took too long\" Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with \"syncing took too long\" Error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：e2b-dev/E2B\n\n摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths。\n\n## 1. 配置坑 · 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b063fe8cb80490584e7647332a2c4c6 | https://github.com/e2b-dev/E2B/issues/1331 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：process was not killed when auto paused\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Closed Port Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：build status polling timed out\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：Support `AbortSignal` in JS SDK methods for request cancellation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Support `AbortSignal` in JS SDK methods for request cancellation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f74f7dd596784e88aff40ef33d5b505e | https://github.com/e2b-dev/E2B/issues/1312 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Docker Build Secrets Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Template Build Fails with \"syncing took too long\" Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with \"syncing took too long\" Error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# E2B - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 E2B 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Open-source, secure environment with real-world tools for enterprise-grade agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：JavaScript/TypeScript SDK。围绕“JavaScript/TypeScript SDK”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：Python SDK。围绕“Python SDK”模拟一次用户任务，不展示安装或运行结果。\n5. page-6：沙箱生命周期管理。围绕“沙箱生命周期管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“JavaScript/TypeScript SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“Python SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-6\n输入：用户提供的“沙箱生命周期管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“JavaScript/TypeScript SDK”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“Python SDK”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-6：Step 5 必须围绕“沙箱生命周期管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/e2b-dev/E2B\n- https://github.com/e2b-dev/E2B#readme\n- README.md\n- package.json\n- packages/js-sdk/src/index.ts\n- packages/js-sdk/src/sandbox/index.ts\n- packages/python-sdk/e2b/sandbox/main.py\n- packages/js-sdk/src/envd/api.ts\n- packages/python-sdk/e2b/envd/api.py\n- packages/js-sdk/package.json\n- packages/js-sdk/src/sandbox/commands/index.ts\n- packages/js-sdk/src/sandbox/filesystem/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 E2B 的核心服务。\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",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：e2b-dev/E2B\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm i e2b\n```\n\n来源：https://github.com/e2b-dev/E2B#readme\n\n## 来源\n\n- repo: https://github.com/e2b-dev/E2B\n- docs: https://github.com/e2b-dev/E2B#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_f21c731f96224a40a2c234a37a3e5491"
}