Beads 仓库 Contributor PR 指南从分层哲学到可过审的 Pull Request 实操手册【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本文导读本文以 CONTRIBUTING_PR_GUIDELINES.md 为骨架系统讲解 Beadsbd一个面向编码 Agent 的记忆增强与议题跟踪工具仓库中提交 Pull Request 的完整规则——包括分层哲学、开 PR 前的自我验证要求、单层 PR 的拆分策略、storage/issueops 与 cmd/bd 之间的分层边界以及代码风格与提交信息规范。读完本文你将掌握一套可复制的 PR 预检流程能显著降低 PR 被拒概率也能理解维护者视角下的评审决策逻辑。一、核心哲学small and clean分层即秩序Beads 项目对 PR 的第一条要求是小而干净。这句话不是口号而是被代码库结构严格贯彻的工程约束。仓库明确把代码划分为三层schema数据模型层对应 schema/schema.go 与 internal/typesIssue、Status、IssueType等核心类型storage / issueops存储与议题操作原语层对应 internal/storage 与 issueopsapplication (cmd/bd)应用/CLI 层对应 cmd/bd 下数百个命令实现文件。从源码结构看这三层的依赖方向是单向的cmd/bd依赖internal/storageinternal/storage又依赖公共契约包 issueops见 internal/storage/storage.go#L1-L19 的包注释The concrete storage implementation lives in the dolt sub-package. This package holds interface and value types that are referenced by both the dolt implementation and its consumers (cmd/bd, etc.)。维护者评审的核心优化目标正是保持各层干净 diff 可评审。最常见的被拒原因在开 PR 之前其实都是可以修复的——本文后面的所有章节都是在帮你提前踩平这些坑。二、开 PR 之前先用 Beads 自身证明问题原文档给出的铁律是任何 bug 或性能声明都必须先在 Beads 自身stock beads里被证明。这一条在实际评审中直接决定 PR 的去留。1. 提供纯 Beads 的最小复现提交 bug 修复类 PR 时必须附带一个只用 Beads 就能跑的最小复现测试或 benchmark证明 bug 存在于库存 Beads 中与任何外部编排层无关。原文档明确点名了几类常见误报来源gascity、factory、外部 agent framework——如果复现依赖这些编排器PR 大概率会被判定为orchestrator bug而拒绝。从仓库的测试组织方式看Beads 确实为这种纯自身复现提供了充分的基础设施issueops/claimer_external_test.go、issueops/issueops_external_test.go 这类 external 测试文件专门从包外消费者视角验证行为契约根目录的 issue_roles_external_test.go、issue_lifecycle_external_test.go 同样以外部视角覆盖角色与生命周期语义基准测试在仓库中也有现成范式例如 cmd/bd/template_test.go#L1034 的BenchmarkLoadTemplateSubgraph_HierarchicalChildren。2. 用库存 Beads 复核在声称任何 bug 之前先在没有任何 orchestrator 在跑的环境下复现。很多表面上的 Beads bug最后都被证明是编排层的问题——这是评审中最常见的误判来源原文档对此用了 many apparent beads bugs turn out to be orchestrator-layer issues 的表述。3. 性能声明必须带 benchmark如果 PR 声称更快了就必须包含能证明这一点的 bench 测试。评审者不会默认新代码更快。这是硬性要求性能优化类 PR 没有 benchmark等于没有证据。仓库中性能相关的测试文化可以参考 engdocs/PERFORMANCE_TESTING.md 与 engdocs/TESTING.md 中关于测试设计的规定。三、规模与范围一层一个 PRStack 拆分1. 一个 PR 只动一层如果某个修复同时需要改动 storage/issueops 层和 applicationcmd/bd层那么应当把它们拆成两个按序叠放的 PRstacked PRs先提存储原语PRstorage primitive再在其上叠加应用接线PRapplication wiring。原文档的理由非常直白一个同时触碰 issueops 原语和 cmd/bd 代码的 PR 很难评审。原语 PR 先落地应用 PR 才能在上面继续推进。2. 保持 diff 可评审如果 PR 超过几百行就要主动寻找拆分的办法。一个 1.3 万行的 diff 是不会被评审的A 13K-line diff will not be reviewed。这条经验也被工具化地固化进了维护侧脚本scripts/pr-preflight.sh 中有一个硬编码的告警阈值——if [[ $files -gt 30 || $additions -gt 1000 ]]见该脚本 Large PR 检查段即改动超过 30 个文件或新增超过 1000 行就会输出[warn] Large PR; verify scope is one issue and one PR.。开 PR 前用这个脚本自检一次就等于提前站在了评审者的视角上。四、分层规则原语在最低层先做上层绝不跨层这是本仓库架构纪律的核心原文档用了两条规则来约束1. 新能力先落在最底层新能力必须首先出现在 storage/issueops 层然后才被应用层调用。以新增一个查询为例标准路径是先在 issueops 中实现该包按角色拆分为 querier.go、reader.go、treewalker.go、cycledetector.go、statsreporter.go 等约 30 个文件将能力暴露到 internal/storage/storage.go 的Storage接口上并实现cmd/bd 应用层再调用这个新方法——不能自己跨层去写实现。从 internal/storage/storage.go#L109-L120 可以看到这种角色访问器模式的真实形态Storage接口并不把方法平铺在一起而是通过IssueLifecycle() (issueops.Lifecycle, error)、IssueReader() ...这样的访问器返回角色子接口注释还专门声明A capability the lifecycle role does not cover gets its own role interface and its own accessor here; it does not get appended to issueops.Lifecycle.新增能力开新角色接口与访问器绝不往既有接口上追加方法。对应的生命周期契约见 issueops/issueops.go#L450-L478 的Lifecycle接口Create/Update/Close/Reopen四个受守卫的原子操作以及 internal/storage 目录下的hook_issue_operations.go、hook_decorator.go等装饰器实现——每一层 store 的链式装饰都是通过包住内层结果来叠加 hook 与遥测行为。2. 上层绝不向下跨层如果发现cmd/bd在做本该属于 issueops 的 SQL 式工作那就是抽象边界出错的信号。此时正确动作不是顺手在 cmd/bd 里修掉而是先提交一个 storage 原语 PR把能力下沉到正确的层。这与 engdocs/PROJECT_CHARTER.md 中界定的项目范围一脉相承Beads 拥有的是issue tracking primitives它不应编码编排层策略也不应变成存储引擎见该文档 Core Scope 与 Storage Boundary 两节。五、代码风格行内注释最小化commit message 承载 why1. 少写行内注释评审者会例行要求删除行内注释。原文档给出两条实践原则让 commit message 和 PR 描述来承载 why只在代码本身无法表达、且属于非显而易见的不变量non-obvious invariants时才使用注释。这一点可以从 internal/storage/storage.go 的注释风格中反向印证该文件顶部那些长注释如ErrCommitIndeterminate、ClaimedByFragment的说明全部是在解释跨包共享的契约语义与不变量而不是在复述代码做了什么——这正是注释只写非显而易见不变量的正面范本。2. 想解释代码写进 commit message当你想用注释解释一段代码时把它写进 commit message。仓库在 CONTRIBUTING.md 中给出了推荐的提交信息格式首行一句话主题正文用-列表展开要点。例如Add cycle detection for dependency graphs - Implement recursive CTE-based cycle detection - Add tests for simple and complex cycles - Update documentation with examples另外提醒提交前确保 PR 中不包含.beads/数据数据库、JSONL也不要有任何多余生成物或垃圾文件这些在 scripts/pr-preflight.sh 中同样是硬性检查项PR changes .beads/ data; contributor PRs must not include planning database changes.会直接 block。六、When in Doubt先读维护者视角不确定自己的 PR 会被怎么看待时通读 PR_MAINTAINER_GUIDELINES.md。它解释了评审哲学、triage 分组与 outcome 类型理解维护者视角后就能在开 PR 之前预判反馈。几个关键信息Triage 分组easy win目标明确的 bug 修复、文档更新、依赖 bot 升级等低风险项、fix-merge candidate有简单阻塞的 easy win、needs review可疑、复杂、宽泛或有风险需要深入调查。Outcome 类型包括 Merge、Merge-fix、Fix-merge维护者直接在贡献者分支上修复后合并、Cherry-pick、Split-merge、Replacement PR、Retire、Reject 等——其中Fix-merge 是常态而非例外只要rebase 后正确就属于 fix-merge维护者会自己 checkout 分支、解决冲突、push 回贡献者分支并合并不会要求贡献者做纯 rebase 这种最后一步劳动原文档称 Rebases are maintainer work。贡献者保护外部贡献者 PR 拥有优先权合并、评审、关闭任何 PR 之前必须先检查是否已有贡献者 PR 覆盖同一区域Prior art is part of the review。理解这套逻辑对贡献者的实际收益是请求修改request changes是最后的兜底手段维护者更倾向于直接吸收、转化、落地有用的部分。所以你的 PR 哪怕有小问题也大概率会被以保留贡献的方式修掉而不是被退回重做。七、实操清单开 PR 前逐项自检综合原文档与仓库配套脚本一份可复制的提交前 checklist 如下纯 Beads 复现bug 修复类 PR 附带仅用 Beads无 orchestrator的最小复现测试或 benchmark库存验证在无编排器环境下复核 bug 确实存在性能证据声称提速的 PR 附带 bench 测试单层拆分跨层修复拆成 stacked PRs原语 PR → 应用 PR控制 diff超过数百行就主动拆分参考 preflight 的 30 文件/1000 行告警阈值分层合规新能力先落在 issueops/storage通过Storage接口暴露cmd/bd 只做接线注释纪律删除可省略的行内注释把 why 写进 commit message仓库卫生不含.beads/数据、无垃圾文件跑本地门禁make ci-pr-lint格式与 lint 包装器需 golangci-lint v2.10.1与make test全部通过测试选择遵循 engdocs/TESTING.md 的比例化验证预算用工具预检scripts/pr-preflight.sh --search topic keywords确认没有撞上已存在的 open PR再对具体 PR 跑scripts/pr-preflight.sh pr-number查看 block/warn 项先读维护者指南快速浏览 PR_MAINTAINER_GUIDELINES.md确保 PR 描述与 diff 一致、一个 PR 只承载一个连贯关注点。说明scripts/pr-preflight.sh默认从git remote推导仓库也可用--repo owner/name显式指定脚本需要gh、git、jq三个命令可用见脚本头部need检查。结语Beads 的 PR 流程本质上是一套分层架构纪律的工程化表达先在自身证明问题、原语下沉到正确层、用 stacked PR 保持 diff 可评审、用 commit message 代替行内注释。这些规则不是评审者的个人偏好而是由storage.Storage接口、issueops.Lifecycle契约、pr-preflight.sh脚本与 lint 门禁共同固化的代码库事实。对贡献者无论是人还是 Agent来说逐条对照本文的 checklist就能把最常见的被拒原因在提交前全部消除——这正是该仓库source of truth式 PR 指南的完整含义。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
