GitButler 多技术栈 Monorepo 的 Agent 协作规范AGENTS.md 指令体系与贡献工作流深度解析【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutlerGitButler 是一个由 Rust、Svelte、React 与 TypeScript 共同组成的复杂 Monorepo 项目桌面端基于 Tauri同时还有 Electron/React 的下一代客户端。根目录的 AGENTS.md 是面向 AI 编码 Agent 与人类贡献者的总章程它定义了指令分层裁决规则、仓库地图Repo Map与统一的工作风格Working Style。本文将逐条解析这份文档的核心约束并结合 crates/AGENTS.md、apps/lite/AGENTS.md 两份嵌套细则以及optimize-icons.mjs、Icon.tsx等源码实现还原 GitButler 仓库从代码形态、Git 语义到验证流程的完整协作规范帮助你理解在一个混合技术栈仓库中如何做出符合社区预期的小而聚焦的变更。指令分层体系冲突时谁说了算根 AGENTS.md 开篇就声明了本仓库的身份Rust/Svelte/React/TypeScript 的 Monorepo并要求应用所有相关的指令文件Apply all relevant instruction files。当不同层级的指令产生冲突时按以下顺序裁决显式的人类指令Explicit human instructions——优先级最高最近的嵌套AGENTS.mdNearest nested AGENTS.md——即当前改动所在目录层级中距离最近的指令文件根目录的AGENTS.md——兜底的默认规范。这一设计意味着仓库不是一份文档管到底而是用越靠近代码的指令越具体、优先级越高的原则做分层治理。在 GitButler 的实际结构中嵌套细则主要有两处对应文档末尾的 Scoped Instructions 小节Rust 相关改动遵循 crates/AGENTS.md覆盖crates/下全部 Rust crate 的源码与测试变更Lite 相关改动遵循 apps/lite/AGENTS.md覆盖apps/lite/Electron/React 桌面应用的编写与验证规范。从仓库结构看这种根文件 作用域细则的模式可以继续向更深层扩展例如未来某个 crate 内部再放置自己的 AGENTS.md 以覆盖更细的边界裁决规则始终是取最近的嵌套文件。仓库地图六块功能区域的职责划分根 AGENTS.md 用一份简洁的 Repo Map 勾勒了仓库全貌这是任何 Agent 定位代码的起点路径职责crates/Rust crates核心业务逻辑如but-*系列与gitbutler-*系列apps/desktop/Tauri/Svelte 桌面应用apps/web/Svelte Web 应用apps/lite/Electron/React 桌面应用下一代客户端packages/共享 TypeScript 包包括 SDKgitbutler/but-sdke2e/Playwright、WebdriverIO 与 blackbox 端到端测试这份地图的价值在于界定了代码归属改动应先判断这个概念属于哪个 crate/包而不是随意放置。比如crates/内部又可细分为but-*新一代 API如but-api、but-ctx、but-graph、but-rebase与gitbutler-*legacy 色彩较重的旧 crate两大阵营嵌套细则对二者的边界做了专门约束见下文Rust 侧细则。工作风格小步、聚焦、面向测试根 AGENTS.md 的 Working Style 小节是面向所有贡献者的通用行为准则共 7 条可归纳为四组核心原则1. 默认只读改动要聚焦。将关于代码库的问题视为只读除非用户要求修改做出聚焦、可评审的改动避免无关的重写使用能解决实际问题的最简单设计不添加投机性的机制并删除你的改动使之不再需要的机制。2. 先观察再动手。引入新模式之前先检查相邻代码优先复用现有的 API、测试与约定——这与 Rust 细则中避免Manager/Service/Helper等含糊命名解决当下问题避免投机性抽象的要求一脉相承。3. 共享行为的全表面检查。在宣布某共享行为完成之前需要逐一检查每个受影响的表面与契约——desktop、web、Lite、CLI/TUI、N-API、SDK 与文档要么同步更新要么明确判定其不受影响。这一点在多前端Tauri Electron Web共享packages/ui、packages/shared与but-sdk的 GitButler 仓库中尤其关键。4. 用测试驱动修复规模。修复行为类 bug 时先在失败的测试中复现问题并调查目标文件现有的循环与分类逻辑作为候选宿主让测试而非诊断决定修复需要多少实现当修复需要新机制新模块、新公共 API、或已有并行遍历处的新并行遍历时先提出预期形态再动手构建。Rust 侧细则API 边界、Legacy 与 Git 语义crates/AGENTS.md 是根文档之外最大的一份细则它把 Rust 侧约束拆成了七个主题这里提炼最关键的部分。API 边界与 Legacy 治理gitbutler-*视为 legacy-heavy局部修复时保留局部所有权与就近模式不在新代码中引入新的gitbutler-*用法legacy 修复保持局部化只在必要、微小、有测试且行为中性时才做迁移。but-api是 API 面它是 Tauri、Electron/N-API、CLI 与 TUI 调用方的统一 API 表面外层调用者优先复用既有but-api函数但低层 crate不得依赖but-api。DTO 留在边界传输层 DTO 常放在各 crate 的本地json模块中调用低层 crate 之前先转换为领域类型。权限模式_with_perm带权限的but-api函数采用固定组合形态——在 wrapper 附近获取权限并委托给_with_perm或其他接收权限的实现CLI、TUI 等已持有权限的调用方应使用_with_perm变体以避免额外加锁与死锁风险。锁的获取发生在顶层 API/命令边界禁止持锁调用会再次获取权限的辅助函数。Context只留在组合边界把 repo、workspace、metadata、数据库句柄或Editor等粒度依赖传给低层 crate。DryRun语义dry-run 不应持久化 refs、objects 或 oplog 条目当 API 同时提供仅动作与记录时间线两种行为时*_only*函数必须保持无 oplog 副作用wrapper 负责准备 best-effort 的 oplog 快照并在变更成功后提交。Undo 基于快照新的用户可见变更都应参与撤销——通过既有的SnapshotDetails/OperationKindwrapper 模式记录 oplog 快照被有意排除在时间线之外的变更要明确说明而不是静默省略不要为 undo 设计自定义逆操作。图形/工作区变更以 WORKSPACE_MODEL.md 为准细则要求凡是涉及 graph/workspace/branch/stack/commit 关系、可达性、依赖、排序、操作目标或 Git 图/历史/ref 放置变更的代码先以 crates/WORKSPACE_MODEL.md 为参考。核心取向是API 边界使用 commit ID 与 ref在 editor 支撑的操作内部转换为操作局部选择器关系/可达性问题使用but_graph::Graph存在 editor 模型的 Git 图/历史/ref 重写使用but_rebase::graph_rebase::Editorbut_graph::Workspace与but_workspace::RefInfo仅作为有损的展示/兼容视图。代码形态、命名与 Git 仓库语义使用 Git/GitButler 领域命名类型与辅助函数归所属 crate/模块所有模块边界应从名称与调用图中可发现修复 bug 时避免顺带重构优先显式枚举匹配而非通配分支隐藏行为。用仓库 API 而非 shell 调githooks、调试工具、测试与 Git 互操作辅助处除外新仓库逻辑使用gixgit2与Context::git2_repo仅作为 libgit2 checkout/index、hooks、transport/auth 等 legacy/边界逃生舱。字节保真Git 路径、refname、commit message 与 diff 负载在到达 UI/API 边界前保持字节保真业务逻辑中避免有损的String转换可测试的业务逻辑中避免隐式SystemTime::now()需要确定性时显式传入时间外部 repo/worktree 变更后使用既有的 reload/invalidation 辅助函数。错误处理用anyhow::Context说明失败操作前端/API 需要分类时使用既有but_error::Code模式禁止消费方匹配错误字符串。but-db 迁移与版本控制迁移保持前向兼容停留在当前SchemaVersion新代码不再使用的列/表保持原位提升版本号会把所有旧二进制锁在数据库之外仅用于有计划、协调的断点绝不用于常规清理。版本控制假设工作树中可能包含其他 Agent 的改动不覆盖/清理/stage/commit/amend 非自己产生的改动需要 branch/commit/push/开 PR 时优先使用 GitButler 自己的butCLI/工作流用户说 ship it 时在 session 分支上提交没有则创建、推送并打开或更新 PRcommit message 与 PR 描述要简洁写清 why、impact 与核心决策不罗列本地验证命令。Rust 测试与验证命令细则给出了从窄到宽的验证路径与具体命令最窄相关测试/检查先行例如cargo test -p crate test-name或cargo check -p crate --all-targets图/rebase/工作区行为优先使用 fixture 支撑的前后快照现有可视化器加针对不变量的结构化断言快照输出易变时先稳定输入或归一化输出优化 Git 遍历/工作区行为时必须用 fixture 回归测试保住语义cargo fmt做格式化cargo clippy --fix --allow-dirty仅在检查 diff 范围后使用依赖变化后运行cargo machete修改通过gitbutler/but-sdk暴露的 Rust API/类型后运行pnpm build:sdk pnpm format以更新packages/but-sdk/src/generated断言约定标准断言用末位参数消息说明理由如assert!(1!2, arithmetic unit on CPU works)快照断言使用snapbox如snapbox::assert_data_eq!(actual, snapbox::str![[r#...#]])由于该宏无消息参数用上一行的// comment解释快照成立原因SNAPSHOTSoverwrite重新生成内联快照断言前先用but_testsupport辅助函数清洗 id/时间戳/路径等不稳定输出.raw()用于必须精确匹配的场景。Lite 侧细则React Compiler 时代的编码铁律apps/lite/AGENTS.md 针对 Electron/React 客户端给出了一套反直觉但务实的编写规范值得单独展开。记忆化默认交给 React Compiler细则明确由于项目使用React CompileruseMemo、useCallback、React.memo通常是冗余的仅在编译器无法判定计算纯性从而无法安全记忆化的热路径上才需要且必须直接对照 React Compiler 验证修改后的记忆化属性。对于仅在事件时需要的 Redux store 值优先useAppStore而非useAppSelector订阅React Query 只需缓存读取时同理。这一点在代码库中有大量佐证——apps/lite/ui/src下的Details.tsx、BranchesList.tsx、CommitForm.tsx等文件都同时使用useAppStore与useAppSelector供不同场景选择。useEffect 是反模式细则直言 useEffect通常是反模式Typically an anti-pattern要求深思熟虑后才可宣布它是最佳选项且即便如此也必须征求同意才能引入。这与仓库依赖eslint-plugin-react-you-might-not-need-an-effect见 apps/lite/package.json互相印证。数据获取与持久化React 侧所有数据获取都经由React Query需要抽象时先从提取 query options 开始仓库依赖tanstack/react-query与suspensive/react-query。所有非设置类的持久化客户端状态放进IndexedDB依赖idb-keyval并对持久化状态考虑向后兼容。注释只用于高层目的不显而易见的代码如不明显的技术边界情况是什么应当不言自明拿不准就不写。设计规范与图标管线Lite 的视觉语言图标、颜色、构成定义在 apps/lite/DESIGN.md改动任何用户可见内容前必须先读细则只负责说明强制执行它的工具链。其中图标工作流是最具体、最可复现的实战流程路径归属脚本apps/lite/ui/src/components/icons/*.svgLitepnpm -F gitbutler/lite optimize-iconspackages/ui/src/lib/icons/svg/*.svgshared Svelte UI 包desktop/webpnpm -F gitbutler/ui optimize-ui-icons两个脚本各自只遍历自己的目录把 SVG 放错目录是图标无法优化的最常见原因ui/src/components/file-icons/下的文件图标刻意不经过任一脚本重着色为currentColor会毁掉它们。新增一个 Lite 图标的完整步骤是从 Figma⚛️ Lite Core library以 16×16 导出 SVG以 kebab-case 文件名存入apps/lite/ui/src/components/icons/文件名即图标名folder-lock.svg→Icon namefolder-lock /运行pnpm -F gitbutler/lite optimize-icons同时提交 SVG 与重新生成的apps/lite/ui/src/components/iconNames.ts。脚本本身是 apps/lite/scripts/optimize-icons.mjs其头部注释完整记录了每项变换的存在理由见下节iconNames.ts是生成文件严禁手改增删 SVG 后重新运行即可。脚本是幂等的可随时安全运行。运行后应在应用内或Icon.stories.tsx同时以 16px 和更大尺寸渲染验证。Lite 的验证命令开发模式下应用通过 CDP 在 9222 端口可供自动化访问。验证按先快后慢组织且必须严格按文档原样执行命令类型检查pnpm -F gitbutler/lite check单元测试Vitest与 E2EPlaywrightpnpm -F gitbutler/lite test、pnpm -F gitbutler/lite test:e2e功能完成后依次运行 lint 与格式化pnpm oxlint:fix、pnpm knip:prod、pnpm knip:non-prod、pnpm exec oxfmt apps/lite、pnpm exec prettier --write apps/lite这些命令与根 package.json 中定义的check、test、lint、oxlint、knip:prod等 turbo/oxlint 脚本保持一致例如根目录oxlint:fix即oxlint --fixknip:prod即knip --strict。图标优化管线从源码看一条可复现的工程实践Lite 的图标工作流是细则 实现 生成物闭环的绝佳样例四段源码可以互相印证1. 优化脚本 apps/lite/scripts/optimize-icons.mjs对每个 SVG 依次执行四个纯文本变换optimizeSvg函数normalizeSize把根svg的width/height替换为100%保留viewBox以维持宽高比。原因是尺寸归属 CSS——Icon.module.css用--icon-size盒子承载SVG 填充该盒子硬编码width16会让Icon size{20} /失效replaceColors把fill/stroke的颜色值替换为currentColor保留none与已正确的currentColor使同一资源可在亮/暗主题与强调色容器中复用none是结构性值空心轮廓形状而非颜色必须保留addNonScalingStroke为path/circle/ellipse/line/polyline/polygon/rect元素添加vector-effectnon-scaling-stroke。图标基于 16px 网格、1.5px 描边绘制缺了它放大后图标会比邻居显得更粗minify去除注释、折叠空白、压缩标签间隙形成规范的单行形态。因为图标以原始字符串内联进 bundle 并通过dangerouslySetInnerHTML注入 DOMFigma 的缩进会直接进入用户页面单行规范也让重新导出产生干净的 diff。脚本还会基于磁盘上的文件名重新生成iconNames.ts的联合类型并打印 added/removed 名称的 diff 报告。2. 类型生成物 apps/lite/ui/src/components/iconNames.ts首行注明auto-generated by apps/lite/scripts/optimize-icons.mjs, Do not edit。IconName是磁盘文件名的联合类型当前包含folder-lock、branch-merge、spinner、workbench等百余个名称这正是Icon namefolder-lock /能获得编译期检查的原因。3. 组件 apps/lite/ui/src/components/Icon.tsxIcon接收name: IconName与可选size渲染一个带data-icon与aria-hidden的i元素通过style设置--icon-sizesize未传时缺省 16px再以dangerouslySetInnerHTML注入icons.get(name)的原始 SVG 字符串。4. 收集器 apps/lite/ui/src/components/icons.ts用 Vite 的import.meta.glob(./icons/*.svg, { query: ?raw, eager: true })一次性把全部 SVG 以原始字符串形式收集进MapIconName, string文件名去.svg后缀即键名——这就是文件名是图标名这一约定的实现根基。这套管线把设计资产 → 优化 → 类型安全引用 → 按需内联串成了一条无人为断点的链路而文件图标不走优化脚本currentColor之外的占位形状会被整块上色等边界知识则被明确写进脚本头部注释供后来者避坑。结语把规范当作代码库的一部分来维护GitButler 的 AGENTS.md 体系展示了大型混合技术栈仓库如何把协作纪律工程化根文档解决方向指令层级、仓库地图、通用工作风格嵌套细则解决具体场景Rust 的 API 边界与 Git 语义、Lite 的 React 编译器纪律与图标管线而测试与验证命令则让每条纪律都可被机器执行、可被回归。对希望参与 GitButler 的开发者而言正确的切入路径是从根 AGENTS.md 建立全局认知 → 依据改动落点进入 crates/AGENTS.md 或 apps/lite/AGENTS.md 获取领域约束 → 先用最窄的测试/检查命令验证 → 按小而聚焦、测试先行、全表面检查的原则提交变更。【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
