PysolateExplained
打开文档导航
本科生解释查看 Markdown 源文件

Workspace Root、Branch 与私有 Attempt

一句话

Pysolate 让多个执行从同一个 workspace 起点各自复制出私有分支；只有 Host 明确选择并 publish 或 seal 的结果才继续可见，失败和未选结果可以直接 discard。

先看一个例子

三名同学要尝试修改同一份课程项目。若三个人直接编辑同一个目录，一人的半成品会立刻影响另外两人，失败后也很难判断哪些文件应该撤销。

更稳妥的方式是给每个人一份独立副本。大家从相同版本开始，但只修改自己的副本。老师检查完成后选择一个结果；其他副本删除。这里不需要把三份变化自动合并。

Pysolate 的 workspace attempt 使用的就是这种简单隔离。当前实现做完整物理 copy，不是 filesystem COW。

真实机制

Workspace 中几个名称承担不同职责：

  • Ref：Host 本地 Manager 用来找到一份 materialized workspace 的 opaque handle。它不是路径，也不是内容 digest。
  • Lease：某个 owner 对 Ref 的独占使用权。活跃 Lease 阻止其他 writer 同时修改。
  • Root：不可变的 lineage record，绑定 workspace 内容 digest、parent identity 和深度。Root identity 可以跨 materialization 表达同一条谱系。
  • Branch：从 base 完整复制出的私有可变 child，可在完成后 Seal 成新 Root，或 Discard。
  • Attempt：同样从 base 复制的试运行副本；Publish 返回 child Ref，Discard 删除它。

一次典型写入路径是：

base Ref
  ↓ ForkAttempt / copy
private child Ref
  ↓ Lease 给本次执行
Guest 写入自己的 workspace
  ↓ release + rescan + validate
Publish child Ref，或者 Discard

对导出 capsule，Host 先写入临时文件并校验 final snapshot，再通过 rename publish；任何前置失败都删除 staged 文件。Branch.Seal 会产生不可变 Root；Attempt.Publish 只是 caller 的终结决定，不会自动 Seal、不修改 base，也不把内容 merge 回 base。

Ref 和 Root identity 也不能混用。Ref 只在当前 Manager 中定位物理副本；Root identity 描述可验证的内容与 lineage。把 capsule 导入另一个 Manager 后会得到新 Ref，必须显式验证和绑定才能成为对应 Root。

Prepared Family 也没有改变 workspace owner。不同 member 可以绑定不同、且在 family 生命周期内不可重复的 workspace Ref；Family 只把 final workspace digest 放入 body-free terminal record。真正创建 branch/attempt、选择结果、Seal/Discard 或 publish root 的仍是 Host/Harness 或 subagent orchestrator。关闭 family 不会自动合并或发布目录。

为什么重要

技术上： 并行 Agent 或不同 backend 可以共享已知起点，却不会共享可变目录。失败 attempt 的清理是删除私有副本，不需要猜测如何回滚一组交错写入。

产品和业务上： 用户只看到被明确选择的结果；取消、失败或低质量候选不会污染后续任务。代价也比较清楚：当前完整 copy 会随 workspace 大小增加 provisioning 成本。

不能推出什么

  • 当前 workspace branch/attempt 不是 filesystem COW，创建副本可能复制整棵 ordinary file tree。
  • Publish 不等于 Seal，也不建立不可变 Root。
  • Stage/publish 保护本地 capsule 目标不出现半成品，不会回滚已经发生的外部 capability effect。
  • Prepared Family 的 terminal/acceptance record 只记录已观察到的 workspace identity，不自行选择 winner 或证明 publication 成功。

术语卡

  • Ref：Manager 内定位物理 workspace 的 opaque handle。
  • Lease：对一份 workspace 的独占使用权。
  • Root：不可变、可验证的 workspace lineage record。
  • Branch：可 Seal 成 Root 的私有 child。
  • Attempt：可 Publish 或 Discard 的私有试运行副本。

继续阅读