Grasp

文档

核心概念

FSM 编排、人审门禁、沙箱执行与产物契约。

FSM 编排

Grasp 把 coding agent 变成工作流里的步骤。你在有限状态机上编排：

  • 节点即状态：Agent、输入、输出、赋值、分支、人工门禁，共六种
  • 边即转移，可配置成功、失败、回滚路径
  • 可用 when 守卫、检查点，把风险步骤显式化

不再是无法撤销的一次性 Agent 跑法：先设计路径，再门禁关键步骤。

Agent 节点与能力

工作流里只有一种 Agent 节点。节点上只配三项：选哪个 Agent（agent_profile）、目标（prompt，支持 {{变量}}）和超时（分钟）。Agent 能做什么由 Agent 自己在 agent.json 的 capabilities 中声明，在 Agent Studio 的「能力」标签页编辑：

  • interaction：clarify 与人多轮对话，人确认后才结束；auto 一次跑完。
  • review：仅 auto 可用。跑完后停下等人复审，复审期间会话保持在线，可以继续修改、启动预览。
  • tools：可授予的平台工具，ask_question、ask_form、set_artifact_preview、set_preview、update_plan_status。clarify 必须授予 ask_question。
  • reads / writes：可读的产物（* 为全部）和要写的结构化产物，每项可标为必填。必填产物缺失时节点失败。
  • 写入带判定的产物（test_result、review）时，节点在画布上有「通过」「不通过」两个出口，全部判定通过才走「通过」。

同一个 Agent 放进多个节点时，这些节点的能力相同，节点之间只靠目标区分；需要不同权限就建两个 Agent。行为规则写在 Agent 工作区的 AGENTS.md 和 skills 里，平台只保留不可修改的通用协议。

内置三个模板：需求澄清（clarify，写需求规格和计划）、实现（auto，开启复审，写实现结果）、测试评审（auto，开启复审，写测试结果和评审结论）。三者都能用 set_preview 启动预览。首次引导生成的默认工作流是「输入 → 需求澄清 → 实现 → 测试评审」，评审通过到输出，不通过回到实现。

工作流里出现未知节点类型时，校验报「未知节点类型 X」，运行直接失败；Agent 没有声明能力时报「Agent X 未声明能力」。

人审门禁（gate）

当某一步需要人做决定时，运行会停在 gate，直到有人批准或拒绝。

批准时刻是一等公民，而不是事后补丁。产品名 Grasp 的赌注是：Agent 可以很快，但关键决策仍由人拥有。

临时审批链接（human_gate）

待审批 Inbox 里，仅 human_gate 卡片（以及有视觉网页产物时的预览工具条）提供「复制临时链接」。登录用户可为当前 pending 实例创建一条一次性链接，发给未登录的外部人员打开与审批工作台同样的三区界面（左产物台 | 右多轮 ReAct | 底栏通栏上游上下文 + 确认并流转 / 驳回）。

  • 默认 24 小时，可选 1h / 8h / 24h / 72h / 7d；每个实例最多 1 条有效链接。
  • 铸造时可单选权限预设：全权限（默认，热态可 reply / cancel / 确认与驳回）或 仅 ReAct 聊天（可 reply / cancel，禁止一切公开 confirm/reject 流转）。预设写在链接行上，Preview.actions 与公开 decide/reply/cancel 同源服务端强制；仅藏按钮不够。存量无字段链接按全权限解释。
  • 管理面板默认掩码展示；复制写入完整 URL。同一浏览器标签刷新后仍可再复制同一有效链。**Regen（继承预设）**立刻作废旧链并沿用原 TTL 档位与权限预设；换权限须新建（作废旧活跃链），不可热改。立即撤销后链接不可用。门禁仍 pending 时，已撤销/已过期可再创建；审批已完成后只读，不能再创建。澄清与应用预览走下方「待复审临时链接」同策略。
  • 外部页无需登录。顶栏仅种类标签「外部一次决策」+ 剩余时间 + 预设芯片（冷态可附「会话已结束」）；不展示 Grasp 品牌、应用侧栏、Run# 或「打开运行详情」。
  • 热会话可在右侧发送 / 取消，视觉网页可取点标注。全权限冷态只读历史，底栏仍可最终处置；仅 ReAct 冷态展示死胡同说明（无法继续操作 / 禁止流转），绝不回退为可 decide。确认与驳回均须填写姓名与意见。确认并流转不触发 Agent。
  • 一次性令牌仅在确认或驳回成功后消耗；中间 ReAct 发送 / 取消不烧链；仅 ReAct 链上的越权 decide 被拒绝时也不消耗（生命周期依赖 TTL / 撤销 / 站内完成 / Run 结束）。过期、撤销、登录侧先审完或 Run 结束都会立刻失效。不可用态保持深色工作台空态，不再使用紫色一次确认镜框。
  • 每位访客的对话独立。 同一链接发给多人时，每个浏览器（按本地保存的匿名访客标识区分，刷新或新开标签页沿用）各自拥有一段对话和独立的 Agent 上下文，彼此看不到对方的消息；访客首次发言前看到的是节点此前的对话。Agent 在沙箱里另开会话，工作区和产物仍然共享，任一访客让 Agent 改动的产物，其他访客和站内都能看到。每条链接最多同时 6 位访客对话，超出时提示稍后再试；访客空闲 30 分钟后其沙箱会话被回收，再次发言会带着已有对话重新开始。
  • 先决者生效。 任一访客确认或驳回成功后，链接对所有人失效，所有访客会话一并结束。

待复审临时链接（Inbox kind=review / clarify）

Inbox 待复审、应用预览与 待澄清卡片使用同一套管理面板与令牌规则（ShareLinkKindReview，含 TTL 与权限预设），认证 API 走 /api/runs/:id/nodes/:nodeId/share-link*，不复用 /gates/...，也不伪造 Gate 行。站内入口：卡片「复制临时链接」、移动端详情顶栏同名按钮。公开页：待复审标识为「外部复审」；待澄清标识为「待澄清 / 外部澄清」。热态可多轮 ReAct（发送 / 流式轮询 / 取消）；节点登记了应用预览时，公开页默认提供远程桌面与取点（短时 ticket 通道，脱敏 ports；API 端口同源 iframe）；移动端仅降级提示。底栏仅「确认并流转」（无驳回、无姓名意见）。访客对话隔离、共享工作区与先决者生效的规则同上。澄清确认走 Agent 收尾写入结构化需求，取消仅清当前轮并保留队列。运行详情澄清/复审 Tab / 登录侧复审面板 / 产物预览工具条不提供临时链接入口。

应用预览：noVNC 与 IP 直连

每个沙箱只有一个 noVNC 桌面地址，桌面上就是 Agent 自己的屏幕：Agent 用 chrome-devtools MCP 操作的那个有头 Chromium。节点一有沙箱就能在面板里看这块桌面，不必先 set_preview；连上时不会改动 Agent 正在看的页面。set_preview 登记端口后，平台把这块桌面切到沙箱内的 http://127.0.0.1:端口/，端口标签只是在同一桌面里跳转，不会再开新的 VNC 连接或新的预览地址。桌面页面一直保留：离开再进入、切换标签、刷新平台页面后，看到的还是上次的页面，登录态和表单内容都在；Chromium 重启后登录态也会保留。外部分享页同样只有一个绑定节点沙箱的桌面 ticket。

预览默认只观看。点击画面即可接管，这一次点击不会操作页面；也可以点工具栏的「接管」。完成后点「交还」。取点标注期间的点击仍用于选元素，不会因此进入接管。这只是为了防止误点，不是权限控制。

Agent 授予了 set_preview 时，noVNC 工具栏会多一个「新标签页直连打开」按钮，打开 http://IP:端口/，那里可以用取点条和右下角的「对话」抽屉。

Live 实时变体

授予了 set_preview 且会与人对话（clarify，或开启复审的 auto）的 Agent 节点带 Live 实时变体。Agent 用 set_preview 登记沙箱内应用端口后，从节点打开直连预览页，点击聊天输入框底部、附件按钮旁的「页面协作」图标，打开菜单后使用「页面候选」。noVNC、仅注册外部 URL 或没有 Live 操作权限时不提供候选生成入口。

「页面协作」菜单默认收起，图标与附件按钮位于同一工具栏，鼠标悬停可查看完整名称。点击图标展开后，可分别设置「页面操作」和「页面候选」。使用完可以收起菜单，两个开关的状态会保留；图标显示已启用的数量，具体启用了哪些功能可通过悬停提示或展开菜单查看。

「页面协作」中的「页面候选」默认关闭。开启后，直接输入需求并发送，Agent 会在当前真实页面上生成 3 个候选，等待你比较和选择；无需先点选元素或打开页面工具栏。图片和取点标注会随需求一起发送。关闭开关恢复普通聊天，不会删除已有候选；撤销候选请使用「放弃」。节点设置决定这项能力是否可用，聊天开关决定本次需求是否生成候选。

同一菜单内的「允许 Agent 操作页面」也默认关闭，单独控制 Agent 是否能读取、点击和填写你正在看的预览页。两个开关各自独立，生成页面候选无需开启页面操作。页面操作开启后，Agent 读取到的页面内容会出现在本会话中，其他参与者也能看到，建议使用测试账号；菜单内保留隐私提醒，以及已连接、已暂停、未连接或控制已转到另一标签页的状态提示。

使用方法：

  1. 点击聊天输入框底部、附件按钮旁的「页面协作」图标，在菜单中开启「页面候选」。接着描述需求并发送，例如「把这个安装弹窗改得更清晰，保留紫色风格」；输入前可先收起菜单。Agent 根据需求、附件、标注和当前页面路由定位相关组件。
  2. Agent 把变体直接写进沙箱源码（包在 data-grasp-live / data-grasp-variant 临时标记里），dev server 的热更新把它们渲染到你正在看的真实页面上。
  3. 原位轮换：元素下方出现 ‹ 2/3 › ✕ Accept 切换条，可用 ← → 切换、拖动参数微调；切换有淡入过渡，并遵循系统的减少动态效果设置；并排挑选：一屏摆出原版和全部候选，点「选这个」即采用，或「保留原版」。
  4. 采用：只把选中的变体写回源码并删除全部标记；放弃：恢复原样。已有候选时可在聊天中继续修改当前候选，或说「就用这个」采用当前版本；候选尚在生成、恢复中或未显示时，先等待或处理该会话，再开始下一组。

页面工具栏的「取点」点中元素后会弹出操作卡：选「引用」把元素作为批注交给 Agent；选「修改」则展开设计面板，选择设计动作（更醒目 / 更克制 / 打磨 / 排版 / 配色 / 布局 / 精简 / 适配 / 动效 / 趣味细节 / 大胆探索），需要时展开「标注」写批注、圈画或添加定位批注，选择 2–4 个变体后点「生成」。Live 开启时，打开「取点」会在工具栏上方出现一条操作栏：可在「选元素」和「插入区块」（点选锚点，在它前后插入新区块）之间切换，也可以直接在「整页调整…」输入框里用一句话调整整页；页面上有候选时出现 👁，按住看原版，单击隐藏候选控件。这些入口都不是聊天生成候选的前置步骤。工具栏和这些面板跟随 Grasp 里设置的语言，预览打开后切换语言也会同步。

对话抽屉里每次 Live 操作都是一张卡片，可在卡片上切换、并排看、采用或放弃；会话进行中直接说「2 的标题再大一点」，Agent 只改变体 2。刷新、新标签或切换路由都不会丢状态：标记在源码里，会话状态在服务端，当前看第几个存在本标签页。还有未采用或放弃的变体时不能「确认并流转」（抽屉里有「全部放弃」）；沙箱仓库的本地 pre-commit 钩子也会拒绝含标记的提交。

页面与对话卡片同步当前候选；说「就用这个」会采用发送消息时正在看的版本及其微调参数。要采用其他编号，先切到该候选再发送。整页调整失败或中断后，可以重试同一个请求，也可以「关闭失败请求」；关闭会保留已有改动，不会回滚整页。「全部放弃」也会关闭失败的整页请求，采用前请查看保留的结果。采用过程中断后，可点击「重试采用」，继续使用原先确定的版本和参数。扫描无法完成时，确认会暂停，恢复工作区后可重试。

真实 Docker 沙箱

在工作流编辑页顶部打开「工作流默认配置」，开启「共享沙箱」并保存。默认关闭，每个节点使用独立沙箱；开启后，同一次运行的节点复用沙箱工作区、已安装依赖和未提交修改，不同运行仍各自隔离。设置只对新启动的运行生效，无需平台总开关。切换节点时按该 Agent 的配置更新模型和 Git 授权；沙箱仍被其他会话占用或无法复用时，该节点使用独立沙箱。

Agent 不是在笔记本上跑的黑盒 prompt。它们通过仓库内嵌的 sandbox-gateway 在 Docker 容器中执行，经 ACP 通信。

支持 Cursor、Claude Code、CodeBuddy、Trae、OpenCode、Codex 和 DeepSeek Harness。Agent 的编码工具与模型来源分别配置，密钥只在「设置 → 凭据」保存。

「凭据」标签分为「Agent CLI」和「API 账号」：前者保存编码工具的平台授权，后者保存模型服务账号的厂商、API Base 和 Key，两类均显示品牌图标。Agent 引用具名模型配置（编码工具 + 凭据 + 上游模型）。创建、编辑、初始化向导和执行使用同一引用；模型配置或账号不可用时明确报错，不会自动换用其他密钥。

编码工具 模型来源与连接协议
Cursor、Trae 工具平台授权；不开放通用第三方模型直连
Claude Code 工具平台授权；Anthropic Messages 连接（连接模式要求 CLI ≥ 2.1.257）
CodeBuddy 工具平台授权；Chat Completions 连接
OpenCode、DeepSeek Harness Chat Completions、Responses、Anthropic Messages；DSH 固定适配 0.2.1-rc.2
Codex ChatGPT 登录文件；Responses 连接

先在「凭据」标签配置常见服务商或自定义服务的 API Base 和 Key，也可仅保存密钥；再到「模型」标签保存一条有名称的模型配置，组合编码工具、已有凭据和所选模型。Agent 绑定这条模型配置即可复用组合，平台授权仍使用工具自己的 Key。模型配置的工具创建后固定；停用、删除配置或清除引用密钥后，Agent 会明确失败，不会自动切换其他授权。添加模型时选择已有模型或填写供应商原始 ID，允许包含 /。页面不另设模型目录或模型连接列表。Claude Code、CodeBuddy 可分别设置主模型和辅助任务模型；DSH 的 DeepSeek 原生路由仅适用于官方服务。页面中的“未验证”表示没有对应真实模型服务的执行结果，适配和模拟测试通过不等于供应商实测。

工作区只列出和使用按当前数据结构显式创建的凭据，不自动生成空槽位。长驻沙箱在模型或授权变更后需要关闭并重新打开。

模型配置是共享引用：修改其凭据、模型或角色设置，会影响所有引用它的 Agent。配置的 CLI 创建后固定，更换 CLI 需要新建模型配置并重新绑定。Agent 草稿可以暂未配置，运行前必须选择模型，或开启「继承默认配置」使用默认配置中的模型。新建 Agent 默认开启继承；元信息页开启「继承默认配置」后只显示一张继承卡片，使用默认模型和 Git，不需要重复选择；关闭后恢复本地配置。Git 可选择多个授权，并为每条设置可选的站点或仓库范围；未选择且未开启继承时不注入 Git 授权，工作流共用沙箱会在切换节点时替换授权。

产物契约与 MCP

每个 run 有隔离的 artifact MCP。Agent 调用例如：

  • write_artifact
  • set_*
  • node_complete

按 run token 隔离，留下可检查的纸面轨迹。

PM：pm-agent-fs（工作区成员 + Agent 工作目录）

工作区绑定的 PM Leader 可启用独立 MCP pm-agent-fs（默认启用；已有部署若已显式保存过 EnabledMcps 需在 PM 设置中手动勾选）：

  • pm_list_workspace_agents：列出工作区的全部 Agent，并标注相对 Leader 的 self / other
  • pm_fs_*：对工作区 Agent 的 host 侧 workspace/ 做 list/read/write/delete/mkdir/rename（不是 Run 沙箱 FS）

写入结果与 Agent Studio「工作目录」同一磁盘树；刷新或重新打开该 Agent 后可见（不做热更新）。若 Studio 仍打开同一 Agent 且存在未保存草稿，随后 Save 可能覆盖 MCP 已写入内容——使用/Demo 时请刷新并避免并行脏写。

单仓自托管

sandbox-gateway 与通用沙箱镜像源码在本仓库。一次克隆即可自托管。