执行摘要

• 一句话：重组沙箱 provider 文档，新增用户与开发者双页面
• 推荐动作：值得快速浏览，不必精读。本 PR 的借鉴价值在于信息架构决策：按读者（用户 vs 开发者）切割文档、用“网格 + 勾选自带链接”表达跨模块兼容矩阵、以及“注册表条目即 provider 契约”的抽象。维护 agentic rollout 相关代码或文档的工程师，应在后续 provider 相关 PR 中同步更新这两个新页面，避免事实漂移。

功能与动机

PR body 明确说明动机：Provider setup（credential、endpoint、各 provider 的 quirks）此前被复制进每个 recipe README 和 smoke 工具的 README，而 “how to add a provider” 没有归属。因此按读者重新切割：用户侧一页讲清每个 provider 怎么配，开发者侧一页讲清新 provider 怎么接；同时 environments.md 回归 connector 索引，recipe README 只保留与自身 launch 命令相关的一行，其余链接到新页面。

实现拆解

1. 新增用户侧聚合页 docs/user-guide/sandbox-providers.md（+72）。页面核心是 provider × connector 网格：行是 AgentENV、Daytona、E2B、Modal，列是 Harbor、HUD、NeMo Gym、OpenEnv；勾选表示该组合跑过真实 rollout，列头链接到对应 connector 的 recipe，小众组合（如 AgentENV × OpenEnv、Daytona × Harbor）的勾选自带独立链接。网格下方按 provider 给出凭据与端点配置：统一契约是“环境变量或 key file 两种方式，launcher 只转发文件路径、不转发内容”，并记录各 provider 怪癖——E2B Cloud 模板构建以非 root 用户进行、Daytona 有总磁盘配额、Modal 的 token pair 必须成对出现。

2. 新增开发者侧接入指南 docs/developer/adding-a-sandbox-provider.md（+45）。开篇立契约：“一个 provider 就是 miles/rollout/agentic/credentials.py 中 PROVIDER_CREDENTIALS 的一个注册项，connector 代码不按 provider 分支”。四步流程：注册表条目 → golden episode（scripts/sandbox_smoke/run.py --connector harbor --backend <name>）→ GPU rollout（HARBOR_ENV_TYPE=<name> + tests/e2e/agentic/test_harbor_rollout.py）→ 在网格中勾选并补配置小节。并用表格对照两个测试的分工：golden 测平台往返、rollout 测 harness + 会话服务器 + TITO 记录 + 奖励。

3. 去重与读者切割。docs/user-guide/environments.md 删除内嵌 provider 表，只留指向新页面的链接；examples/experimental/openenv/README.md 删除逐 provider 的凭据参数表，保留 provider 特有行为（模板预构建、agentenv 为 e2b 别名、e2b>=2.12 的版本约束注释），参数表里凭据行合并为一行指向新文档；examples/experimental/harbor/README.md 的 Validation 段从带日期/机型的运行记录压缩为一句“端到端跑过”，并把 --save-dir 磁盘空间警告保留在命令块之后；scripts/sandbox_smoke/README.md 删除 “Exercised so far” 运行记录表，因为实测组合记录已迁到用户侧网格。

4. 导航与引用一致性。docs/docs.json 把 user-guide/sandbox-providers 挂到 User Guide → Agentic Environments 分组、developer/adding-a-sandbox-provider 挂到 Developer Guide 顶层；tests/e2e/agentic/test_harbor_rollout.py 与 test_sandbox_golden.py 的 docstring 把 “which combinations have been run” 的引用从 scripts/sandbox_smoke/README.md 改为新文档表格，确保不会出现双份事实。

5. 配套。无源码、测试断言、配置或部署变更；纯文档与 docstring 引用更新，CI 行为不受影响。

关键文件：

• docs/user-guide/sandbox-providers.md（模块 用户文档；类别 docs；类型 documentation）: 本 PR 核心新增页：provider × connector 实测网格 + 各 provider 凭据与端点配置指南，成为用户侧“单一事实来源”，替代散落在各 README 的重复说明。
• docs/developer/adding-a-sandbox-provider.md（模块 开发者文档；类别 docs；类型 documentation）: 本 PR 第二个核心新增页：开发者接入指南，明确“provider = PROVIDER_CREDENTIALS 注册项”契约，并给出四步接入流程与两层测试的分工说明。
• examples/experimental/openenv/README.md（模块 示例文档；类别 docs；类型 documentation）: 重复信息最多的清理对象：删除逐 provider 的凭据参数表，保留 provider 特有行为（模板预构建、agentenv 别名、e2b>=2.12 约束），参数表凭据行合并为指向新文档的链接。
• scripts/sandbox_smoke/README.md（模块 冒烟脚本；类别 docs；类型 documentation）: 删除 “Exercised so far” 运行记录表（harbor × e2b、harbor × daytona 的 PASS 记录）与重复凭据说明，实测组合记录迁移到用户侧网格，并补充注册测试的说明。
• examples/experimental/harbor/README.md（模块 示例文档；类别 docs；类型 documentation）: Validation 段落从“带日期与机型的运行日志”压缩为一句端到端结论，具体 provider 实测记录交给网格；同时保留并调整 --save-dir 磁盘空间警告的位置。
• docs/docs.json（模块 文档导航；类别 config；类型 configuration）: 导航注册两个新页面：user-guide/sandbox-providers 挂到 Agentic Environments 分组、developer/adding-a-sandbox-provider 挂到 Developer Guide 顶层，保证站点可发现性。
• docs/user-guide/environments.md（模块 用户文档；类别 docs；类型 documentation）: 回归 connector 索引定位：删除内嵌的 provider 使用表格，改为指向 sandbox-providers 页面的链接，明确 provider 是与 connector 不同的轴。
• tests/e2e/agentic/test_harbor_rollout.py（模块 端到端测试；类别 test；类型 test-coverage）: docstring 把 “which combinations have been run” 的引用从 scripts/sandbox_smoke/README.md 改为 docs/user-guide/sandbox-providers.md 的表格，保证实测记录只有一份。
• tests/e2e/agentic/test_sandbox_golden.py（模块 沙箱测试；类别 test；类型 test-coverage）: 与 test_harbor_rollout.py 相同：docstring 引用从 smoke README 改为新文档表格，与开发者指南中“实测组合看网格”的表述保持一致。
• docs/user-guide/openenv.md（模块 用户文档；类别 docs；类型 documentation）: provider 列举从可读的四种名称收敛为指向 sandbox-providers 页面的链接，并保留“共享 Docker env server”的补充说明。
• docs/user-guide/harbor.md（模块 用户文档；类别 docs；类型 documentation）: 链接引用微调（+1/-1），与新页面保持一致。

关键符号：未识别

评论区精华

review 中无实质设计交锋：claude[bot] 自动审查返回 “Code review found no issues”，未发现高置信度问题；Shi-Dong 手动审查给出 “Great job, LGTM!” 并批准合并。唯一的人工评论是作者通过 issue 评论触发的 @claude review。由于是纯文档 PR，review comments 为空，所有疑虑已收敛，结论为可直接合并。

• PR 整体审查结论 (other): 全部通过，无未解决疑虑。

风险与影响

• 风险：文档性风险（无代码风险）：
  • 手工维护的实测网格易过期：docs/user-guide/sandbox-providers.md 的勾选靠人工更新，若新组合跑通后无人补勾，用户会低估可用面；反之若只跑了 golden smoke 就勾选，会稀释“真实 rollout”的语义。
  • 相对链接敏感：examples/experimental/openenv/README.md、scripts/sandbox_smoke/README.md 均使用 ../../../docs/... 相对路径，示例目录一旦移动即失效。
  • 与凭据契约耦合：文档细节（如 Modal token pair、E2B 双端点）绑定 miles/rollout/agentic/credentials.py 的字段语义，后续 provider 演进（例如 PR#3215 的存储配额 override）若不同步更新，会出现“代码已支持、文档已过期”的漂移。
  • 无回归、性能、安全或兼容性影响：纯文档变更，测试文件仅改 docstring，CI 行为不变。
  • 影响：用户影响：跑 sandbox 型 recipe 的用户只需看 sandbox-providers.md 一个页面即可完成 provider 配置，配方类 README 显著变薄；要接入新 provider 的开发者获得明确四步清单。系统影响：零运行时行为变化，CI 检测无行为变化，站点导航净增 2 页。团队影响：文档维护者从“多处复制”改为“单点更新”，后续 provider 功能演进（Modal、Daytona、AgentENV 等）的文档成本降低；但新增了 1 个需要人工维护的实测网格。
  • 风险标记：纯文档变更, 手工维护的实测网格易过期, 相对链接易失效, 与凭据契约耦合

关联脉络

• PR #3195 test(agentic): run the sandbox tests on any provider, not just e2b: 本 PR 栈在其上：3195 让沙箱测试由凭据注册表驱动、任意 provider 可测，本 PR 把“实测组合记录”从 smoke README 迁到用户文档，正是承接 3195 的成果。
• PR #3214 docs: Harbor runs on Modal: 同一文档区域：补充 Modal 实测结论，与 sandbox-providers.md 的 Modal 配置与网格勾选直接相关。
• PR #3215 harbor daytona: reclaim orphaned sandboxes by default, and a storage override: 同批 provider 支持演进：其存储配额配置语义与本 PR 新增的 provider 配置文档（Daytona 磁盘配额提示）相关，后续需同步文档。
• PR #2876 ci(e2e): Harbor trials on real e2b sandboxes through the full rollout path (manual for now): test_harbor_rollout.py 测试线的起点，本 PR 更新了该文件 docstring 的引用。
• PR #2837 docs: the in-process Harbor example: harbor README 文档的上一版本，本 PR 继续精简其 Validation 段落并引入统一 provider 文档。