Macshop 入门教程:完成你的第一个工作空间项目

从创建工作空间、选择兼容 Agent 与模型,到添加文件、定义可验收任务、检查产出并保存下一步。

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

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

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

想跟着界面完成一个具体练习,可以先看做出第一个网页。本文重点讲怎样选任务、验收结果,以及为下一次工作留下交接材料。

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

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

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

例如:

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

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

准备在租用机器上运行项目时,先按独享 Mac 验收清单检查环境,再导入私人工作。

1. 围绕结果创建工作空间

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

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

Macshop 如何工作一文介绍了更完整的产品结构:Session 承载一个持续的 Agent 任务,工作空间则让已保存项目能够跨 Session 保留。

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

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

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

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

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

3. 选择 Agent harness 与兼容模型

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

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

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

如果你准备先评估 Codex,可以继续按照 Macshop 上的 Codex 入门流程,完成从工作空间到结果审查的完整闭环。

启动前还要确认模型和执行路径如何计费。下面的套餐与积分说明适用于标准平台模型调用,不适用于工作空间的所有使用方式。Macshop 套餐与积分指南说明了当前规则:适用套餐的额度优先使用,额度耗尽后自动转为按量扣除积分;套餐外的模型调用也按量计费。因此,“有套餐”不等于这次任务不会额外消耗积分。

第一次任务开始前,记下三件事:

  1. 当前所选模型和通道是否在套餐范围内,还剩多少额度,何时重置。
  2. 额度耗尽后的按量费率,以及可用积分的来源和有效期。
  3. 完成这一小步后何时停下来检查结果与用量,什么费用变化需要先由你确认。

更换 harness 或新建 Session 不会自动增加一份独立的免费额度。本机 Agent 使用电脑上的登录与订阅;自有模型 API 调用则由对应供应商计费。开始前核对不同使用路径的费用归属与公开产品说明。这些是文档规则,不是付费账户实测;先检查一个小任务的成果和用量,再决定是否继续。

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

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

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

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

5. 启动 Session,并关注证据

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

任务执行时:

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

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

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

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

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

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

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

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

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

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

首次项目的常见错误

一开始就完整迁移

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

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

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

把 Agent 和模型当成一回事

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

把 Agent 总结当成验证

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

不留下重启说明

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

Review 时不断扩大范围

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

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

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

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

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