we0agent

Guides

Snapshots

为会修改文件的 agent 接入 git-backed snapshot，记录 patch、diff，并为会话回滚提供文件状态基础。

Snapshot 用来回答一个问题：agent 改了哪些文件，以及能不能把这些文件状态和会话一起回滚。它适合会写代码、编辑文档、生成文件或运行会改变工作区命令的 agent。

组件关系

Mermaid
Rendering diagram...

基本概念

概念说明
worktreeagent 会读写的文件目录。
FileSystemRuntime当前文件系统和 Git 执行环境，并根据 worktree 派生内部 snapshot 仓库位置。
SnapshotState绑定 worktree 和内部 gitdir 的状态对象。
SnapshotTracker由 ports.session_revert.snapshot_tracker(session_id) 提供给 engine 的快照端口。
track()记录当前 worktree 状态，返回 snapshot hash。
patch(hash)查询某个 snapshot 对应的文件变更。
diff_full(from_hash, to_hash)查询两个 snapshot 之间的完整 diff。

最小接入

示例项目推荐直接把 SessionRevertService 放进 We0AgentPorts：

from we0agent.domain.models.agent import We0AgentPorts
from we0agent.snapshot.runtime import LocalFileSystemRuntime
from we0agent.builtins.service.session_revert import SessionRevertService

file_system = LocalFileSystemRuntime(root="/abs/app-runtime")

ports = We0AgentPorts(
    session_revert=SessionRevertService(
        session_id="demo-session",
        file_system=file_system,
        worktree="/abs/project",
    )
)

agent = We0Agent(
    name="demo",
    model=model,
    system_prompt=prompt,
    tools=tools,
    ports=ports,
)

Snapshot 示例运行命令和产物说明见 Examples: snapshot_feature。

Snapshot 生命周期

Mermaid
Rendering diagram...

track() 只记录 worktree 里的文件变化。工具如果写到了 worktree 外，snapshot 看不到。

过滤规则

快照服务会避免把无关或危险内容塞进 snapshot 仓库。通常应排除：

  • snapshot 仓库自身
  • 临时数据库
  • 大型二进制产物
  • 业务 secrets
  • node_modules、缓存目录、构建目录

SnapshotService 会强制过滤自有 snapshot 仓库目录；普通 SDK 用法通过 LocalFileSystemRuntime(root=...) 显式声明运行时根目录。

Patch 与 Diff

patch(snapshot_hash) 返回某个 snapshot 对应的变更摘要，适合展示「本轮 agent 改了什么」。

diff_full(from_hash, to_hash) 返回两个 snapshot 之间的完整文件 diff，适合回滚、对比和审计。

常见展示方式：

数据用途
文件路径UI 列出变更文件。
added / deleted / modified标记变更类型。
patch text展示具体行级 diff。
summary给用户展示自然语言摘要。

与 Revert 的关系

Snapshot 本身只记录文件状态。会话回滚增强由 SessionRevertService 提供入口，并组合：

  • BuiltinSessionRevertRuntime：执行 revert、unrevert 和 cleanup。
  • SessionRunnerManager：确认 session 没有正在运行。
  • SessionSnapshotService：恢复文件状态。
  • SessionSummaryService：维护 summary/diff。
  • We0EventHub：发布回滚相关事件。

回滚语义见 Revert，内建类参数见 Built-ins。

生产建议

  • 普通 SDK 接入显式传入 LocalFileSystemRuntime(root=...) 和 worktree。
  • 云端或 e2b sandbox 场景应把 root 指向宿主管理的运行时目录。
  • 每个 session 绑定自己的 snapshot state，避免不同会话互相覆盖。
  • 工具写文件时尽量使用绝对路径或明确 worktree 根目录。
  • 不要把 secrets、缓存、大二进制文件纳入 snapshot。
  • 对高风险写操作同时使用工具权限和 snapshot，不要只依赖回滚兜底。

易错点

症状常见原因处理
没有 patch没有注入 session_revert，或工具写到了 worktree 外检查 ports 和工具路径。
snapshot 仓库污染业务仓库自定义 snapshot state 指向业务 .git使用 file_system.snapshot_state(worktree=...) 生成内部 gitdir。
revert 提示 busy会话还在运行等待 idle 或先 abort。
diff 为空没有实际文件变化，或变化被过滤检查 worktree 和过滤规则。

下一步

On this page

组件关系基本概念最小接入Snapshot 生命周期过滤规则Patch 与 Diff与 Revert 的关系生产建议易错点下一步