企业官网建设流程全解析

Crabbox 是一个"预热盒子、同步代码差异、跑完整测试套件"的远程沙箱执行工具。把 Crabbox 与 AI Agent 集成，核心是三件事：用Agent Skills教会本地编码 Agent 何时、如何调用 Crabbox；用委托 Runner 契约（Delegated Runner Contract）把任意托管沙箱以统一语义接入；用--require-artifact+--download构成一条无环境污染的可审计证据链，让 AI 生成的代码与测试都能留下可复查的远程执行证据。

为什么 AI Agent 需要一个可审计的执行层

当 AI Agent 帮你写代码、写测试时，"它说通过了"不等于"真的通过了"。你至少需要回答三个问题：

• 环境是否干净？命令是否在独立、可控的远端环境里运行，而不是夹带本机环境污染；
• 命令语义是否统一？不管后端是 VM、容器还是托管沙箱，成功/失败、退出码、日志的行为是否一致；
• 证据能否留档？测试产物、证明文件能否被强制要求并下载回来，供人或 Agent 复查。

Crabbox 的设计恰好覆盖这三点，而且它刻意保持"执行层"定位：不评判模型输出、不保管推理轨迹、不投递模型凭据——这些边界都交给仓库自己的测试协议。详见 docs/features/hermetic-agent-evidence.md。

用 Agent Skills 教会 AI Agent 使用 Crabbox

Agent Skills 是一种开放的、以SKILL.md为载体、带name和descriptionfrontmatter 的技能规范。Crabbox 原生支持它，让 Codex、Cursor、Claude Code、Gemini CLI 等编码 Agent 自动"认识"这个仓库里的远程执行能力。

一条命令完成接入

在仓库根目录执行：

crabbox init --detect

init会生成三样东西：仓库配置.crabbox.yaml、可选的 Actions hydration workflow，以及面向 Agent 的技能文件.agents/skills/crabbox/SKILL.md。技能文件告诉 Agent：何时预热并复用租约（lease）、如何运行命令或探测出的 job、失败时如何检查、最后如何停止租约。完整命令说明见 docs/commands/init.md。

Crabbox 自带两个可复用的技能源，位于仓库内：

• crabbox：skills/crabbox/SKILL.md —— 在沙箱中跑仓库命令、复用远程机器、收集执行证据的完整技能；
• crabbox-quickstart：skills/crabbox-quickstart/SKILL.md —— 面向初次接触者的最短路径：本机容器里跑通第一条命令并显式清理。

新手仓库建议先装 quickstart；当任务涉及 provider 登录、命名 job、密钥或产物时，它会自动把上下文交接给完整的crabbox技能。

多客户端发现路径

不同 Agent 客户端扫描的目录不同。默认.agents/skills是广泛共享路径，但 Claude Code（.claude/skills）、Cline（.cline/skills）、Kiro（.kiro/skills）等客户端有自己的原生路径。init支持重复传--skill参数，为多个客户端生成内容完全一致的副本：

crabbox init --detect \ --skill .agents/skills/crabbox/SKILL.md \ --skill .claude/skills/crabbox/SKILL.md

原则是：只为你仓库贡献者实际使用的客户端生成副本，不要盲目生成所有厂商路径——多根扫描的客户端可能遇到重复名称。各客户端的兼容矩阵完整列在 docs/integrations/agents.md。

⚠️ 注意：技能文件只提供"指令"，不授予凭据，也不会绕过 Agent 宿主自身的命令审批与沙箱策略。生成后的技能文件应当像 CI 配置一样接受代码评审。

委托 Runner 契约：让任意托管沙箱统一接入

很多托管执行平台只能通过 sandbox API、job 或 deployment 运行代码，不暴露 SSH。对这类平台，Crabbox 定义了委托 Runner 契约：一个足够小的"运行器形状"，任何远端只要实现它，就能作为 Crabbox 的内置 provider 接入。

职责划分非常清晰：

最小输入与结果形态

一个委托运行器只需接受一个带固定语义的执行请求：archive（同步归档或其指针）、command（argv 或 shell 字符串）、workdir（专用工作目录）、env（仅显式白名单转发的环境变量）、timeoutSecs、syncDelete。

返回结果则必须把平台生命周期状态与命令退出码区分开：结果 JSON 中的exitCode == 0才映射为 Crabbox 成功；平台级succeeded状态不足以判定用户命令成功。结果缺失或格式错误属于 provider 故障，而不是"用户命令成功"。

凭据与清理的硬性规则

契约对安全边界有强制要求：

• 🔒Provider 凭据是控制面凭据，永远不允许进入 runner 环境变量；API token 必须从环境变量或原生凭据库读取，而不是仓库 YAML 或命令行参数；
• 转发到 runner 的env摘要与请求载荷中必须剥离 provider 鉴权变量；
• token 必须在 HTTP 错误、日志、录制输出中脱敏；
• 归档大小必须在创建付费资源之前设上限；
• 若 claim 建立失败但 provider 资源已创建，适配器必须先取消该资源再返回错误。

Live Proof 验收门槛

离线测试必要但不充分。新 provider 合入前，需要一轮脱敏的 live run 证明：一次运行只创建一个资源、日志流不重复、exitCode=0正确映射成功、非零退出码透传、status/stop可解析租约、最终list无残留资源、日志不泄露 token。契约文档还附有逐条 Review Checklist，见 docs/features/delegated-runner-contract.md。

无环境污染的证据链：Hermetic Agent 模式

这是 Crabbox 与 AI Agent 集成中最有特色的一环：把"AI 写代码 + AI 写测试 + 第三方裁决"的 hermetic（密闭）工作流，放进干净的远程执行环境，并让证明文件成为成功的硬门槛。

三角色隔离

一个典型的 hermetic harness 把上下文隔离成三个角色：

隔离由 harness 的 manifest 强制执行——生成出来的测试并不自动等于"真理"，QA 仍需判断哪一方违背了规格。

证据链如何闭环

repo harness -> crabbox run -> required proof artifact -> downloaded evidence

仓库把证明流程声明为.crabbox.yaml中的一个命名 job，Agent 或人只需：

crabbox job run hermetic-agents

job 展开后依次完成：执行远程证明脚本 →requiredArtifacts强制校验证明 JSON 存在（命令退出 0 但产物缺失即判定运行失败）→downloads把 JSON/Markdown 证据拉回.crabbox/runs/hermetic-agents/。等价的手工命令是crabbox run --require-artifact <json> --download <remote=local> --shell <harness>，参数语义见 docs/commands/run.md 的 "Artifacts and downloads" 一节与 docs/commands/job.md。

关键设计：Crabbox 只要求证明文件存在，不校验其内容——内容正确性属于仓库命令的职责。同时.crabbox/runs/永远被排除在后续同步之外，上一轮的证明不会被当作源码上传，避免"环境污染"。

信任边界清单

共享一轮 hermetic run 之前，检查五项：

• 证明 JSON 包含独立的code_writer与test_writermanifest；
• 两个 writer 角色的泄漏检查（leak check）均通过；
• QA 裁决与归责字段齐全；
• 必需产物由 Crabbox 在远端强制，而非仅在本地生成；
• 下载的证据不含密钥与原始客户数据。

📌 边界提醒：Provider API key 与模型/工具凭据必须留在仓库 YAML 和命令参数之外。Crabbox 不提供面向工作负载的凭据投递——env.allow白名单不是秘密通道。

快速上手：五步完成集成

1. 安装并自检：crabbox --version，然后crabbox doctor确认就绪状态；
2. 初始化仓库：crabbox init --detect，按仓库实际调整.crabbox.yaml（class、sync.exclude、env.allow）；
3. 选择客户端技能路径：默认.agents/skills/crabbox/SKILL.md，需要时追加--skill副本；
4. 声明证据 job：在jobs下写command+requiredArtifacts+downloads，把 harness 脚本放仓库里；
5. 验证闭环：crabbox job run <name>跑一轮，确认证明文件下载成功、crabbox list无残留租约。

💡 如果你的编辑器是 Zed，仓库还自带了本地控制面扩展 integrations/zed/，可以直接在任务选择器里执行 doctor、warmup、远端命令与 job，扩展同样遵循"只调用 CLI、不接管凭据与租约"的原则。

相关文档

一句话总结：让 Agent 负责"说什么"，让 Crabbox 负责"跑在哪、怎么证明"——技能文件保证 Agent 会用，Runner 契约保证后端可换，必需产物加下载保证每一轮执行都留有可审计、无污染的证据。