Agent.Space 入门教程：完成你的第一个 Workspace 项目

学习 Agent.Space 最合适的方式，不是立刻迁移完整项目，而是先完成一个边界明确、可以回退的小任务。

你可以选择一个结果容易观察的任务，例如只更新一个页面、Review 一小段代码改动、完善一份明确文档，或诊断一个可以复现的错误。创建 Workspace，只加入任务真正需要的文件，选择受支持的 Agent harness 与兼容模型，再用提前写好的 Acceptance Criteria 判断结果。

这篇教程会带你从准备到 Review，再到完成第一次项目交接。

开始前，选择一个能够验证的小任务

合适的首次任务通常有四个特点：

• 边界明确： 只涉及项目中已知的一部分。
• 可以回退： 能恢复原文件，或直接放弃 Workspace 中的副本。
• 结果可见： 可以通过文件、Preview、测试或其他产物看到变化。
• 能够判断： Agent 开始前，就能写清楚什么叫“完成”。

例如：

• 只改落地页一个 Section 的文案，不改变布局；
• 为现有表单补一个验证状态；
• 围绕一个明确风险 Review 一小段 Patch；
• 根据给定 Outline 生成一份结构化文档；
• 复现一个错误并记录可能原因，但不实现修复。

不要把“做完整个产品”“把所有地方都优化一下”或“迁移整个仓库”当作第一次请求。这类任务会隐藏大量决策，难以 Review，也没有清楚的回退边界。

1. 围绕结果创建 Workspace

打开 Agent.Space，新建 Workspace。名称应描述项目或预期结果，而不是你准备使用哪个 Agent。Workspace 是成员、Session、已保存文件和工作上下文的共享容器；Agent 只是其中一位参与者。

例如，发布页文案 Review 会比 Codex 测试 更持久。之后即使在另一个 Session 使用 Claude Code 或 OpenCode，Workspace 名称仍然能够说明项目是什么。

Agent.Space 如何工作一文介绍了更完整的产品结构：Session 承载一个持续的 Agent 任务，Workspace 则让已保存项目能够跨 Session 保留。

2. 加入 Brief 和真正需要的文件

启动 Session 前，先准备一份简短 Brief，至少包含：

• 期望结果；
• 定义任务的文件或源材料；
• 允许修改的范围；
• 明确不能修改的范围；
• 用什么方式验证结果；
• 哪些决定必须交给人类确认。

把相关文件加入 Workspace。不要因为手里有完整压缩包，就不加区分地全部上传。多余材料可能带来相互冲突的说明、私人数据和无关上下文。

不要把 Credentials 写进 Prompt 或普通项目文件。如果任务需要访问另一个服务，应使用获批的 Secret 管理或环境配置路径，并只提供这次验证需要的权限。

3. 选择 Agent harness 与兼容模型

Agent.Space 会把 Agent harness 与模型分开选择。Harness 组织工具、权限、上下文和执行循环；模型提供底层能力。它们互相关联，却不是同一个选择。

当前支持哪些组合，应以线上 Agent 与模型选择器为准。不是每个模型都能与每个 harness 一起使用，可用性也可能变化。

第一次使用时，应根据“你能否判断这项工作”来选择，而不是试图找到一个适合所有场景的“最强 Agent”。构建任务、聚焦 Review 和文档转换，可能适合不同工作流。

如果你准备先评估 Codex，可以继续按照 Agent.Space 上的 Codex 入门流程，完成从 Workspace 到结果审查的完整闭环。

同时确认所选模型通过什么方式获得额度。Agent.Space Share 与 Flex 适合不同使用路径；所选模型会决定相关资金来源，一种额度不会在后台静默替另一种垫付。

4. 把任务写成可验收合同

一条合格的首次 Prompt 应描述结果与检查方式，而不是规定每一次按键。可以使用这个结构：

目标修改【具体产物】，让它达到【可观察结果】。
范围内- 【允许修改的文件、Section 或行为】- 【必须遵循的源材料】
范围外- 【必须保持不变的区域】- 【需要单独批准的外部动作】
验收检查- 【测试、Preview 状态或内容要求】- 【第二条成功条件】
结束前总结改动文件、已运行检查、未验证假设和建议的下一步。

这样既给 Agent 留出工作空间，也保留明确 Review 边界。如果任务需要主观判断，例如选择设计方向，应先让 Agent 提供选项，在人类确认后再实现。

5. 启动 Session，并关注证据

选择 Agent、确认兼容模型、添加必要文件，再发送这项有边界的任务。Agent.Space 会创建 Session，并启动第一个 Turn。

任务执行时：

• 后续要求放进 Queue，不要反复提交同一指令；
• 根据准确动作与目标处理权限请求；
• 外部变更与破坏性动作继续保留明确批准点；
• 决定依赖中间结果时，直接检查对应文件；
• 如果任务目标中途改变，先重写 Acceptance Criteria，而不是静默扩大范围。

Agent 正在输出，不等于项目事实已经确定。最后 Review 的证据，应当是已保存文件、可见结果与验证输出。

6. 检查文件、Preview 与验证结果

Turn 结束后，把结果与 Brief 对照。

1. 阅读 Agent 总结，记录它明确说明的限制。
2. 检查真实的已保存文件，确认没有无关改动。
3. 在 Inspector 或浏览器 Preview 中打开受支持的产出。
4. 运行与项目相符的检查，例如测试、Build、Lint、Type Check、内容 QA 或其他门槛。
5. 记录没有运行的检查与仍未验证的假设。
6. 决定接受结果、要求一次有边界的修改，或恢复到之前状态。

Preview、发布与文件交付是三个独立决定。Preview、发布和导出指南解释了什么时候继续使用临时 Review 视图、创建稳定 Web Release，或下载普通文件。

不要只因为渲染结果看起来精致就接受任务。完整 Review 还要检查范围、文件、行为、权限与事实依据。

7. 下一 Session 开始前，保存交接状态

即使是个人项目，也值得留下简短交接记录。写清：

• 原始期望结果；
• 哪些文件发生了变化；
• 哪些检查通过或失败；
• 当前 Preview 或交付产物；
• 剩余决定与风险；
• 一项带完成标准的下一步。

如果要让另一个 Agent Review 或继续工作，就在同一个 Workspace 里新建 Session。新 Agent 可以检查当前已保存文件和明确交接材料，但不会自动继承上一段 Session 的私有推理。因此，重要决定应进入可检查文件或消息。

首次项目的常见错误

一开始就完整迁移

大任务的失败可能来自范围、环境、权限、模型选择、缺失文件或要求不清，你很难知道到底是哪一层出了问题。小任务更容易验证整套工作流。

上传大量上下文，却不标明优先级

如果 Agent 不知道哪份材料是事实源，十份文档也不会更有帮助。明确主要 Brief，并说明支持文件应该怎样使用。

把 Agent 和模型当成一回事

更换模型不会自动改变 harness 的工作方式。两项选择都要检查，并确认它们兼容。

把 Agent 总结当成验证

Agent 可以说明自己尝试了什么；你仍然需要检查真实产物与对应测试。

不留下重启说明

Workspace 可以保留已保存文件，但 Runtime 进程可能停止。记录恢复所需命令和成功证据，不要假设每个进程都会永远运行。

Review 时不断扩大范围

如果 Review 发现了新的项目目标，就把它变成下一项有边界的任务，不要在模糊 Follow-up 中塞入第二个项目。

先跑通一个完整闭环，再扩大规模

当你能追踪完整闭环时，第一个 Agent.Space 项目才算成功：有边界的 Brief 进入 Workspace，一组兼容的 Agent 与模型完成任务，已保存产出通过对应 Review，而且下一步足够清楚。

之后再加入更大代码库、更多 Session、其他 Agent 或团队成员。这个顺序可以帮你看清哪一部分工作流真正产生价值，也让第一次实验不会难以诊断。

打开 Agent.Space，为一个可以回退的小任务创建 Workspace。写清预期结果，只加入最低限度的源材料，定义 Acceptance Criteria，并完成整套 Review 闭环后再扩大项目。