第28章 Worktree 检查点

第 28 章：工作树检查点

每个 Orca 工作树都拥有一个在 UI 中可见的轻量级自由文本注释字段，用于展示当前工作树的实时状态快照。智能体可以通过 CLI 更新此字段，这是我们推荐的用于在无需强制使用聊天界面的情况下让协作者保持知情的一种模式。

模式

``` orca worktree set --worktree active --comment "复现了认证失败；正在测试凭证链修复" --json ```

卡片状态（可选）

在自由文本注释之外，当阶段发生变化时，同步设置工作区卡片状态：

``` orca worktree set --worktree active \ --comment "修复已实现；正在运行集成测试" \ --workspace-status in-progress \ --json ```

状态选项：todo、in-progress、in-review、completed（或工作区使用的自定义 ID）。

理想的检查点时机

- 完成了一个有实质意义的实施切片。 - 证实或证伪了某个假设。 - 完成了代码评审。 - 遇到阻碍（等待外部输入、上游 Bug、权限缺失）。 - 从调查阶段转入修复阶段，或从修复阶段转入验证阶段。

格式

第一行应包含动作：刚刚发生了什么、在哪里发生、当前状态或下一步。

``` orca worktree set --worktree active --comment "在 SearchBar 的 onChange 中添加了防抖 (src/components/SearchBar.tsx)；已准备就绪，待评审 目标：减少冗余 API 调用，参见 #298" --json ```

写入前先读取

如果注释中可能包含用户编写的上下文，请先读取它，以免覆盖已有的目标或约束条件：

``` orca worktree current --json ```

保留仍然有效的内容，丢弃过时的信息，并将你的更新融入其中。