Repository navigation
Closed
Labels
agent-runtimeAgent orchestration, memory, and extensionsAgent orchestration, memory, and extensionsenhancementNew feature or requestNew feature or requestgit-workflowGit and pull request workflowsGit and pull request workflowsgoPull requests that update go codePull requests that update go codehelp wantedExtra attention is neededExtra attention is neededjavascriptPull requests that update javascript codePull requests that update javascript codesecuritySecurity boundary or high-risk capabilitySecurity boundary or high-risk capability高难度
Description
Parent: #98
问题概述 / Summary
Workspace 已有文件提案、整文件应用、持久收据和上下文压缩,但没有覆盖文件工具与 Shell 副作用的统一恢复模型。需要为每轮可变更操作建立可验证 Checkpoint,使用户能够预览、撤销、重做、Rewind 或从历史点 Fork,而不依赖脆弱的 Prompt 约定。
优先级 / Priority
P0。它是安全连续编辑、Shell 变更归因和可交付多代理的基础。
当前基线 / Current baseline
- 文件变更已有提案/应用收据,Git 已支持 stage/unstage/commit/branch 和远端 PR 基础操作。
- Run/Mission、事件流、attempt checkpoint 和上下文压缩已持久化,但不等于 Workspace 内容快照。
- Shell/构建工具可同时修改多个已跟踪、未跟踪或忽略文件;当前没有统一变更边界。
- 没有 Claude 式逐提示 Checkpoint/Rewind,也没有从恢复点创建独立会话/分支的产品入口。
范围 / Scope
- 定义 versioned
workspace-checkpoint.v1,记录 base commit、index/worktree manifest、内容 hash、元数据和触发操作的 receipt。 - 在每次写工具、命令批次、Git 变更和多代理合并前后建立事务边界;失败时保留可诊断的 partial state。
- 使用内容寻址 blob/delta 和上限策略,避免无界复制整个 Workspace;明确 ignored、large、binary、generated 与 external-change 状态。
- 提供 diff 预览、undo/redo、Rewind 和“从此处 Fork 新 Run/branch/worktree”;原 Run 历史保持不可改写。
- Rewind 采用 compare-and-swap 与三方冲突检测,遇到外部修改、dirty index、symlink/junction 或 root/commit 漂移时停止并展示影响。
- Shell 变更通过前后 manifest、Git 状态和文件 watcher 收据归因;无法可靠捕获的范围标记 incomplete,而非宣称可恢复。
- 重启恢复时 reconciliation 检查 checkpoint blob、Workspace identity、lease 和未完成事务。
- Desktop 提供时间线、影响文件、来源操作、可恢复性等级、预览和确认;CLI/OpenAPI 提供等价只读/操作入口。
非目标 / Non-goals
- 不替代 Git,也不静默提交、force reset 或覆盖用户并发编辑。
- 不保证恢复 Workspace 外部文件、注册表、数据库、网络服务或故意逃逸的子进程副作用。
- 不把
git reset --hard、全目录覆盖或删除未跟踪文件作为默认 Rewind 实现。 - 不在没有可验证内容/manifest 的情况下标记恢复成功。
涉及目录 / Affected directories
internal/workspace/internal/repository/internal/runner/internal/application/internal/store/internal/events/internal/policy/internal/approval/internal/httpapi/cmd/web/src/docs/
依赖 / Dependencies
- 被“模型可调用的工作区工具”和“普通模式真实命令闭环”阻塞;通过 GitHub Issue dependencies 维护。
- Git branch/worktree 创建可复用 feat(git): 本地 Git 写工作流与变更审阅 #44/feat(git): 远端 Git、Pull Request 与凭证/网络授权 #45 的 typed mutation 与审阅合同。
验收条件 / Acceptance criteria
- 文件工具与命令批次的前后状态都有稳定 checkpoint/receipt,可关联到精确 Run、attempt 和 capability generation。
- 纯文本、二进制、rename、delete、未跟踪、dirty index、换行与 Windows 大小写场景可正确预览和恢复。
- Shell 修改多个文件后能够给出完整/部分/不可恢复等级;不能捕获的副作用不会被隐藏。
- undo/redo/Rewind 遇到外部并发修改时 fail closed,提供三方冲突而不是覆盖用户内容。
- Fork 创建独立 Run/branch/worktree,继承明确的上下文/配置快照但不继承过期权限和进程。
- 崩溃发生在 blob 写入、manifest 提交、文件应用或事件持久化任一阶段时可重放或安全回滚。
- 存储配额、GC、引用计数和加密/敏感文件策略有测试,不造成无界磁盘增长。
- Desktop 时间线可浏览、预览、确认和解释失败;操作均可审计。
- 单元、集成、竞争、故障注入和双平台文件系统测试完成。
安全边界 / Security boundaries
恢复是受控的新写操作,不是历史状态自动授权。每次恢复仍需校验当前 Workspace、权限、影响范围和外部漂移。
Metadata
Metadata
Assignees
Labels
agent-runtimeAgent orchestration, memory, and extensionsAgent orchestration, memory, and extensionsenhancementNew feature or requestNew feature or requestgit-workflowGit and pull request workflowsGit and pull request workflowsgoPull requests that update go codePull requests that update go codehelp wantedExtra attention is neededExtra attention is neededjavascriptPull requests that update javascript codePull requests that update javascript codesecuritySecurity boundary or high-risk capabilitySecurity boundary or high-risk capability高难度
Activity