企业官网建设流程全解析

从规范到实践：GitButlerbutCLI 的开发指南（AGENTS.md 深度解读）

【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutler

but是 GitButler 项目的命令行前端，用 Rust 实现，通过 Tauri/Rust/Svelte 驱动整个版本控制工作流。crates/but/AGENTS.md是仓库为 AI Agent 与人类开发者共同编写的butCLI 开发规范，它界定了命令结构、工作树锁（worktree guard）的获取与死锁规避、快照式 CLI 测试、以及随命令演进而同步维护的 Agent 技能（skills）等关键工程约束。本文以该文档为骨架，结合crates/but/src/、crates/but-core/src/sync.rs、crates/but/tests/等处的真实源码，展开一份可落地的butCLI 二次开发实战指南。

文档定位：一份给 Agent 与人类的 CLI 开发契约

crates/but/AGENTS.md开篇即说明它的定位：它是对crates/AGENTS.md（全 crate 范围的 Rust 开发规范）在crates/but/目录下的补充，适用于所有涉及butCLI 的源码与测试改动。它适用于"在 crates/but 下进行的 CLI 工作"，包括命令新增、参数调整、行为修改与测试维护。

文档同时给出了一条重要的前置阅读规则：任何涉及 graph/workspace/branch/stack/commit 关系、可达性（reachability）、操作顺序、操作目标，或者 Git 图/历史/引用位置变动的 CLI 工作，都必须先阅读 crates/WORKSPACE_MODEL.md。这是 GitButler 工作区模型（虚拟分支与堆栈）的权威参考，but的很多命令语义都建立在它之上。

从仓库结构看，crates/but/src/args/下按命令划分参数定义模块（args 目录），包括commit.rs、branch.rs、squash.rs、undo.rs、worktree.rs等数十个命令；crates/but/src/command/是命令处理实现；crates/but/tests/存放 CLI 集成测试与快照。AGENTS.md 正是围绕这三个区域建立开发纪律。

命令结构与 I/O：文档注释即用户文档

使用cli-commandsskill 编写新命令

规范要求编写新 CLI 命令时遵循cli-commandsskill 的指引。该 skill 汇总了 GitButler 在大量命令迭代中沉淀的模式：如何组织 clap 参数、如何命名 flag、如何分组互斥参数、如何编写文档注释等。新增命令前应先参考它，避免每个命令各写一套风格。

ERROR_EXAMPLES：解析错误时的内联示例

部分命令在crates/but/src/args/中定义了ERROR_EXAMPLES常量，当用户参数解析失败时会被展示出来。规范强调：当改变命令的参数或行为时，必须同步更新这些示例，否则会误导用户。

以 commit.rs 为例：

/// Example invocations appended to a `but commit` parse error. pub(crate) const ERROR_EXAMPLES: &str = "\ Examples: but commit -b <branch> -m \"message\" # commit onto a branch (created if needed) but commit -b <branch> -m \"message\" <file-or-hunk>... # commit only the given changes but commit -m \"message\" # commit when only one stack is applied ";

搜索crates/but/src/可以发现，ERROR_EXAMPLES被定义在args/mod.rs、args/commit.rs、args/amend.rs、args/move.rs、args/squash.rs等多个命令模块中，是一个广泛采用的约定，而非个别命令的特例。

文档注释是用户手册的来源

文档注释（doc comments）会被but skill reference命令读取：它打印每个命令的第一段说明和 flag 帮助。因此规范要求：

• 先说清楚命令做什么；
• 当省略某个参数在终端（交互）与非交互运行中的行为不同时，两者都要写明。例如 commit.rs 的-m注释：

Without `-m` or `--no-message`, a terminal opens the editor and a non-interactive run commits with an empty message.

这正是"交互与非交互行为不同"的典型体现：有 TTY 时打开编辑器，无 TTY 时直接用空消息提交。

• 只有在终端中有意义的 flag（如打开 TUI、编辑器）应使用help_heading = "Interactive"分组，这样but skill reference生成参考文档时会省略这些 flag，保持非交互场景下文档的纯净。

以 commit.rs 的--interactive为例：

/// Open the TUI to interactively select what to commit. #[clap(short, long, group = "changes_to_commit", help_heading = "Interactive")] pub interactive: bool,

结合skill子命令的实现（args/skill.rs），but skill reference对应Subcommands::Reference，而--full会附加打印所有参考文档。这套机制保证了"命令注释 → 参考文档"的单向数据流，注释写得好，文档自然好。

工作树守卫与死锁：GitButler 并发模型的核心纪律

为什么需要工作树守卫

but的许多命令会读写工作树（worktree）与 Git 仓库状态。多个命令（或同一命令内部的多次调用）并发操作同一仓库时，必须通过锁保证一致性。GitButler 在but-core中实现了进程内（parking_lot::RwLock）与进程间（文件锁）两层锁，见 crates/but-core/src/sync.rs。

规范对命令处理器（command handler）的要求是：

1. 在操作开头获取所需的工作树守卫（guard），并把派生出的权限（permission）向下传递给调用链；
2. 当守卫已被持有时，优先调用接受权限的辅助函数，例如*_with_perm(...)；
3. 绝不能在持有某个守卫时，再去调用会获取另一个共享/独占工作树守卫的辅助函数。

这与crates/AGENTS.md中的 API 边界原则一致：but-api是 Tauri、Electron/N-API、CLI、TUI 共同的 API 表面，外层调用者应优先复用现有but-api函数；持有权限的组合调用方应使用_with_perm变体，避免额外加锁引入死锁风险。

从sync.rs的实现看，RepoExclusiveGuard和RepoSharedGuard各自持有parking_lot::RwLock的写/读守卫，并通过write_permission()/read_permission()派生权限令牌（如RepoExclusive/RepoShared），将令牌传给底层函数，而守卫本身保持在顶层调用者的生命周期内。类型文档明确写道："只在顶层调用者中获取锁，否则会面临死锁"——这正是 AGENTS.md 那条纪律的源码依据。

BUT_WS_LOCK_DEBUG=1：把死锁变成 panic

规范给出了调试工作树锁死锁的标准方法：使用 debug 构建并设置环境变量BUT_WS_LOCK_DEBUG=1。在该模式下，工作树守卫的获取在锁已被持有时直接 panic，而不是无限阻塞。随后配合 backtrace 运行失败命令：

BUT_WS_LOCK_DEBUG=1 RUST_BACKTRACE=1 cargo run -p but -- -C <repo> <command>

用 panic backtrace 找到嵌套的守卫获取点，然后把已有的权限透传到该调用点，或改用接受权限的辅助函数。

其实现位于 sync.rs 的panic_if_locked_in_debug：

• 仅在debug_assertions构建且环境变量BUT_WS_LOCK_DEBUG存在时生效，其余情况是 no-op，保持正常阻塞语义；
• 探测逻辑对共享和独占获取统一使用try_write_arc()，因为目的不是检查"本次 mode 能否继续"，而是检查"该仓库是否已有任何锁被本进程持有"。这样连嵌套的共享锁也会被捕获——单独的嵌套共享锁往往无害，但一旦外层操作改为独占锁，或调用路径稍后出现嵌套独占获取，就会死锁。因此把这类隐患尽早暴露出来。

修复路径：透传权限或切换_with_perm

根据 panic backtrace 定位到嵌套获取点后，规范给出两条修复路径：

1. 把已持有的权限透传到该调用点（thread the existing permission to that call site）；
2. 切换到已有的接受权限的辅助函数（*_with_perm(...)）。

crates/AGENTS.md也强调：but-api中带权限的函数遵循既定组合形态——在包装层附近获取权限，然后委托给_with_perm或其他接受权限的实现。这套命名约定让"谁持锁、谁传权限"在代码中一目了然。

CLI 测试：快照驱动的行为契约

断言风格：snapbox 优先

crates/but/tests/中的 CLI 测试应优先使用测试辅助环境env.but(...)配合 snapbox 断言：

env.but(...).assert().success() .stdout_eq(snapbox::str![...]) .stderr_eq(snapbox::str![...]);

• 对不稳定输出（如动态 ID、时间戳、路径）使用[..]或...通配符，而不是削弱断言本身；
• 不要用env.but(...).output()后直接断言 stdout/stderr，输出检查应统一放在 snapbox 中；
• 测试内使用会 panic 的断言宏（assert!、assert_eq!、assert_ne!），而不是anyhow::ensure!；
• 快照断言用snapbox::assert_data_eq!，由于该宏没有 message 参数，需要在断言上一行用// comment说明该快照为什么成立。

crates/AGENTS.md的断言部分补充了细节：快照断言默认带模式匹配（[..]和...通配符、路径分隔符归一化），需要精确匹配（如含反斜杠或字面[..]/...）时，对期望值追加.raw()；不稳定的输出应先清理（sanitize）再快照，而不是原样快照。

快照更新：SNAPSHOTS=overwrite

更新 CLI 快照的标准命令是：

SNAPSHOTS=overwrite cargo test -p but

可以追加测试名缩小范围，例如：

SNAPSHOTS=overwrite cargo test -p but <test-name>

对彩色终端输出，断言应针对snapbox::file!["snapshots/<test-name>/<invocation>.stdout.term.svg"]（仓库中确实存在大量.svg格式的终端快照，见 crates/but/tests/but/snapshots 目录），并用同样命令更新。

规范特别强调：更新快照后必须检查结果，确保测试仍然在测试它声称要测试的东西——快照一旦被覆盖，测试的"断言力"就转移到了人工审核环节，绝不能机械地overwrite后直接提交。

沙箱辅助函数：不要直接调 git

测试中应使用沙箱辅助函数，而不是std::process::Command::new("git")：

• env.invoke_bash(...)：用于多行命令序列；
• env.invoke_git("...")：用于单条 Git 命令。

规范还提醒：不要为了改用env.invoke_git(...)而重写已有的env.invoke_bash(...)调用——避免无意义的 churn。

这一约定背后是 GitButler 测试基建的设计：but_testsupport提供 sandbox 与 env 辅助，让每个测试在隔离的临时仓库中运行，同时通过受控方式执行 Git 命令，保证可复现性（参见 crates/but-testsupport/src/lib.rs 与crates/but/tests/but/utils.rs）。

CLI Skills：让命令与 Agent 技能同步演进

but的一大特色是它把自身的使用方法打包成可安装的 Agent 技能（skills）。仓库中对应目录为 crates/but/skill/，包含：

• SKILL.md：核心技能指南；
• references/下的reference.md（命令参考）、concepts.md（工作区模型概念）、examples.md（工作流示例）；
• 配套的AGENTS.md、CLAUDE.md、README.md等。

这些文档不是手写的，而是从命令的文档注释生成并由but skill命令输出。对应参数实现在 args/skill.rs：

• but skill（无子命令）：打印核心技能指南；
• but skill reference：打印每个but命令的语法与 flag；
• but skill concepts：打印工作区模型概念指南；
• but skill examples：打印工作流示例；
• --full：在核心指南后附加所有参考文档；
• but skill install：把技能文件安装到 Coding Agent（Agent Skills/.agents、Claude Code、OpenCode、Codex、GitHub Copilot、Cursor、Windsurf、Poolside 等），支持--global、--path、--detect以及交互式安装范围选择。

因此规范的收尾要求顺理成章：修改 CLI 命令或工作流之后，必须同步更新crates/but/skill/，让随but分发的 Agent 技能保持与命令实际行为一致。如果命令变了而技能文档没变，Agent 学到的就是过期接口，这比人类用户看错帮助信息后果更隐蔽。

实践要点速查

围绕crates/but/AGENTS.md，可以把butCLI 开发的工程纪律浓缩为以下清单：

总结

crates/but/AGENTS.md篇幅不长，却精准覆盖了butCLI 开发的全部关键风险点：命令的对外契约（注释、错误示例）、仓库并发安全（工作树守卫与_with_perm权限透传）、测试的可维护性（snapbox 快照与沙箱）、以及 Agent 技能的同步更新。这些规则相互咬合——好的文档注释产生好的but skill reference，正确的守卫获取顺序避免死锁，快照测试锁定行为不被无意破坏，而技能同步让 AI Agent 与人类开发者面对同一份"活文档"。对任何想在 GitButler 上扩展或修改but命令的开发者来说，这份规范是绕不开的入门契约，其背后的sync.rs锁模型与快照测试基建，也值得作为 Rust CLI 工程化的参考范本。

【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutler