PR #2837 分析报告：Harbor in-process 模式文档
执行摘要
此 PR 为 Harbor 的 in-process 执行模式（任务在云端沙箱运行，无需独立 agent server）新增了完整文档指南，并重构了用户指南以清晰区分两种执行模式（本地 Docker vs. 云端沙箱）。这是一个纯文档变更（3 个 Markdown 文件，+127/-12 行），旨在提升新功能的可用性，不涉及任何运行时代码修改。
功能与动机
动机是为刚合并的 Harbor in-process 功能（由 PR #2836 引入）提供配套文档。PR body 明确指出需要为每种模式提供“完整指南”，避免信息重复，并确保文档反映实际的训练运行验证状态。核心问题是：用户如何配置和运行这个新的、更简洁的 Harbor 执行模式？
实现拆解
- 新增核心指南：创建
examples/experimental/harbor/README.md，作为 in-process 模式的权威文档。内容包括：
- 与 agent-server 模式的对比表格。
- 分步安装说明（使用特定的
harbor-miles-v0.20.0 分支）。
- 后端凭证配置（以 E2B 和 Daytona 为例）。
- 关键的网络要求（从沙箱到训练器 session-server 的端口路由）。
- 启动命令和参数说明。
- 基于实际训练运行的验证状态（包括 GPU e2e 测试通过记录）。
- 重构入口页面：将
docs/user-guide/harbor.md 从描述单一的 agent server 集成，改为呈现两种执行模式（本地 Docker daemon → agent-server 模式；云端沙箱 → in-process 模式），并指向各自的示例 README。
- 更新提供商矩阵：修改
docs/user-guide/environments.md 中的沙箱提供商表格，在 AgentENV 和 E2B 的“Used within”列中添加“Harbor”，并添加说明性段落，解释 in-process 路径通过 HARBOR_ENV_TYPE 可到达任何 Harbor 后端，但表格仅列出经过训练运行验证的组合。
此次变更仅涉及文档文件，无需展示源码级实现片段。核心的文档内容已通过 key_files 中的 annotated_snippet_markdown 字段展示了其关键结构和信息。
评论区精华
Review 主要由 claude[bot] 进行，焦点在于确保文档的绝对准确性：
🔴 关于 mini-swe-agent 依赖的纠正：机器人指出 “The install section claims mini-swe-agent 'does not need the fork's patches for correctness; public harbor[e2b] works for it', but harbor_agent_function.py's own header classifies 'the max_seq_len check in Chat and mini-swe-agent's poll_steps' under NEEDED... A user following this line installs public harbor for mini-swe-agent runs and loses the max_seq_len/MaxSeqLenExceededError check...” 作者随后修复了此不准确声明。
🟡 关于 Modal 文档的决策：机器人建议添加 Modal 凭证配置步骤。作者回复：“Leaving Modal out here on purpose: this section shows the two backends a training run has actually used, and credentials.py is the complete contract for the rest. I'd rather add Modal's steps after someone runs it than ship instructions nobody has exercised.” 这体现了文档应与实践验证紧密结合的原则。
🟡 关于端口范围精确性的修复：机器人指出 “The Network section tells operators only 'ports 30000/31000 must route'... but run.py launches 32 session-server workers... which bind ports 30000-30031.” 作者将文档修复为包含完整端口范围。
风险与影响
- 风险：主要风险在于文档内容的准确性。任何错误的安装命令、端口描述或凭证步骤都会导致用户配置失败。Review 过程已识别并修复了多个此类问题，降低了残留风险。
- 影响：影响范围限于文档层面，对系统稳定性、性能和安全性无直接影响。正面影响是显著降低了用户采用 Harbor in-process 模式的门槛，并为两种模式建立了清晰的文档结构。
关联脉络
- 与 PR #2836 和 #2876 的关系：此文档 PR 是 Harbor in-process 功能落地的最后一步。PR #2836 提供了启动器代码，PR #2876 提供了端到端测试证据，而此 PR 将所有内容文档化，并引用了测试结果以建立可信度。
- 文档组织模式：此 PR 确立了“一个模式一个完整指南”的文档组织原则，可能影响未来类似功能的文档编写方式。
建议
此 PR 是值得精读的，特别是对于负责 Harbor 功能或编写复杂集成文档的工程师。它展示了几项值得关注的实践：
- 文档驱动开发：在功能代码合并后，及时补充高质量的、步骤化的指南。
- 基于证据的文档：文档明确声明验证状态，并引用具体的测试运行日期和结果，增强了可信度。
- 审慎的范围控制：作者关于 Modal 的决策展示了如何在文档完整性和准确性之间做出权衡，优先保证文档内容是经过验证的。
对于一般开发者，此 PR 的主要价值是了解 Harbor 两种执行模式的区别和选择依据，可以作为采用该功能的起点。
参与讨论