Skip to main content
Comet Native 使用多层机制保护工作流。Hook Router 在写入发生前确定归属，Native Guard 根据阶段处理写入，Runtime 再用状态版本、锁、原子文件操作和事务保护稳定状态。恢复流程以落盘状态为依据，不依赖上一轮对话或 Agent 自述。 这些机制承担不同职责。Hook 适合阻止平台能够观察到的错误写入；Runtime 负责保护工作流状态和文件操作；Verifier 负责判断实现是否满足需求。任何一层都不能单独替代其他层。

​
分层运行时防护

​
写入归属于哪个 change

.comet/current-change.json 使用 comet.selection.v2，记录当前写入所属的 workflow 和 change。它只负责当前归属，不限制项目中 active change 的数量。 Hook Router 按以下顺序确定写入归属：
  1. 根据 Hook 请求提供的工作目录定位 Comet 项目；
  2. 读取项目启用的 workflow 和当前选择；
  3. 枚举对应 workflow 的 active change；
  4. 确定唯一 owner 后，只调用该 owner 的 Guard。
只有一个 active change 且没有当前选择时，Router 可以推断它是 owner。存在多个候选时，Router 会拒绝写入，直到通过 comet native select <change-name> 明确选择。选择文件损坏、目标已归档、workflow 已停用或 change 状态无法读取时，Router 也会停止写入。 旧版全局 Hook 如果没有可信的请求工作目录，会保持中性，避免从 Hook 安装目录或其他项目推断当前 change。项目发现或目标范围检查发生异常时，Router 会按失败关闭处理。

​
阶段感知的变更控制

Native Guard 会把项目内目标分为正式需求、实现文件和 Runtime 管理文件。 正式需求和实现文件必须分开写入。一次工具调用同时修改两类文件时，Guard 会拒绝该操作，避免需求变化和实现变化共享一个无法准确归属的状态转换。 Verify 或 Archive 期间观察到实现写入时，RC1 不会继续沿用原候选。Runtime 会增加实现轮次、清除失效的验收结论并回到 Build。正式需求发生变化时，Runtime 会回到 Shape，并使旧目标周期中的验证结果和归档批准失效。

​
可观察写入的前置保护

Hook Router 只能处理平台提供了写入意图和目标路径的事件。以下写入可能不经过阶段守卫：
  • IDE 或后台进程直接修改文件；
  • 平台没有暴露给 Hook 的 Shell 或文件操作；
  • Hook 请求没有可归属的目标路径；
  • 明确位于当前项目之外的目标。
因此，Hook 是写入前的工程保护，不是操作系统级沙箱。后续 Runtime 仍会校验状态版本、工作区、候选、检查和归档条件；Verifier 也会读取实际实现。平台未暴露的写入需要依靠后续检查和验收发现，Comet 无法保证即时拦截。

​
版本化状态一致性

comet-state.yaml 中的 state_version 从 1 开始，每次稳定状态转换只能增加一次。Runtime 写入新状态前会比较磁盘版本：
  • 当前版本必须等于操作预期版本；
  • 新版本必须恰好是当前版本加一；
  • 提交前会再次读取磁盘状态，防止另一进程抢先修改。
涉及用户决定的命令还会携带：
这两项保护可以拒绝旧对话中的确认、迟到的 Verifier 结果和已经过期的命令。发生版本冲突时，正确动作是重新读取最新 continuation，再执行当前状态允许的操作。

​
项目级并发互斥

Native 的状态修改、选择、迁移和 Archive 都通过项目级变更锁执行。同一时间只有一个受控变更操作可以进入临界区。 取得锁后，Runtime 还会检查：
  • artifact root 是否正在移动；
  • 是否存在未提交、未回滚或无法识别的事务；
  • 当前操作是否正是该事务允许继续的恢复动作。
发现未完成事务时，新的变更操作会停止，并返回需要先恢复事务的错误。锁和事务目录均由 Runtime 管理；手工删除可能使文件状态和事务记录失去对应关系。

​
路径与文件身份校验

Runtime 对正式产物做受限读取和原子写入：读取前校验路径在受管理目录内、不是符号链接、内容有效且未被中途替换（需要时记录 SHA-256）；写入先落临时文件再原子提交，提交中发现路径或目录变化就停止。这些校验全部由 Runtime 自动执行，你不需要手工干预。 你会看到什么：校验失败时对应命令报错并说明是哪一个文件；连续失败时 comet native doctor <change> 会给出诊断和恢复建议。该做什么：按报错处理文件本身（如移走中途替换的文件），不要手工删除锁或事务目录。

​
可恢复的事务式归档

Archive 会更新主 Spec、最终状态和报告，并把 active change 移入 archive。RC1 把这些动作记录为事务，而不是一组互不关联的文件命令。 事务会记录预期内容哈希和文件对象身份。替换或删除已有目标前，Runtime 会把原内容放入受控隔离区，并验证隔离后的对象仍与事务记录一致。中断后，Runtime 可以根据日志继续已确认的步骤；内容、路径或对象身份发生变化时，事务会停止。 以下情况需要先处理再继续 Archive：
  • active 和 archive 目录同时存在；
  • 事务日志损坏或与实际目录不一致；
  • 主 Spec 在事务期间发生变化；
  • 另一个 active change 在任何已登记 Git worktree 中声明了同一 capability。
同一 capability 存在多个 owner 时，Archive 要求用户确定串行顺序。先归档的 change 会更新主 Spec，后续 change 需要重新对齐并重新验收。Runtime 不会自动覆盖另一个 change 的规格。

​
基于稳定状态的断点恢复

跨会话和跨设备恢复的权威状态是 change 目录中的 comet-state.yaml。.comet/runtime/native/changes/<change-name>/state.json 只记录本机执行情况。 具体现场对应的恢复行为（检查中断、Verifier 任务丢失、archive-ready 返回 Verify、verification.md 重建等）统一见恢复手册。

​
零写入的自动恢复探测

comet resume-probe 根据 .comet/config.yaml 指定的默认 workflow 查找恢复目标。它不修改 change，也不切换分支或工作区。 ambient_resume: false 会关闭普通请求的自动恢复探测。显式进入 Comet 时仍按入口命令处理。多个 active change 存在时，探测命令使用明确名称或当前选择；缺少唯一归属时返回 ask_user。

​
统一诊断与恢复入口

日常推进只执行最新 continuation。需要排查时按以下顺序读取状态：
doctor --repair 只适用于 Runtime 已识别并支持恢复的状态。config、YAML、事务或目录归属无法确定时，保留现场比手工拼接状态更安全。 继续阅读：任务推进与中断恢复、产物与状态 和 恢复与故障处理。
最后修改于 2026年9月4日