Beads 项目bd lint命令详解按 Issue 类型自动检查缺失模板章节【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd lint是 Beads 项目中用于质量把关的命令行工具它基于 Issue 类型自动校验每条 Issue 的描述是否包含推荐章节如 Bug 的复现步骤与验收标准帮助团队在 Issue 创建后及时发现模板不完整的问题。读完本文你将掌握bd lint的全部用法、各类型章节要求矩阵、过滤与输出选项以及它在源码层面的校验实现与可配置扩展机制。命令概述bd lint的核心职责是检查 Issue 是否缺少基于其类型推荐的章节。它默认扫描仓库中所有处于 open 状态的 Issue也可以显式指定一个或多个 Issue ID 只检查特定条目。该命令定位在views命令组中属于只读的巡检类操作不会修改任何 Issue 数据。该文档由bd help --doc lint自动生成同步自命令源码 cmd/bd/lint.go 中的Long描述因此两者始终保持一致。各 Issue 类型的章节要求矩阵bd lint的校验规则由 Issue 类型决定内置要求如下Issue 类型必需章节说明bugSteps to Reproduce、Acceptance Criteria复现步骤用于定位问题验收标准用于验证修复是否有效taskAcceptance Criteria完成任务的可验证标准featureAcceptance Criteria功能实现完成的可验证标准epicSuccess Criteria高层级的成功标准chore无杂务类不要求任何章节永不产生警告这一矩阵在源码中有精确对应。类型IssueType的方法RequiredSections()定义于 internal/types/types.gobug要求两个章节task/feature/story均只要求Acceptance Criteriaepic要求Success Criteria而chore、milestone及自定义类型返回nil无要求。值得注意的细节是decision和spike类型同样有内置要求decision需要Decision、Rationale、Alternatives Considered三个章节spike需要Goal与Findings。虽然 CLI 帮助中的--type过滤提示只列出bug, task, feature, epic四个常见值但实际的类型系统支持更丰富的集合详见下文 Flags 一节。epic 的宽容匹配规则对于epic类型存在一个特殊豁免规范写法是Success Criteria但如果描述中出现了Acceptance Criteria同样可以通过校验。这样做的目的是让 Agent 不需要额外记忆史诗必须写 Success Criteria这种特殊约定——两种写法都被接受而新创建的 epic 仍以Success Criteria为规范参见 internal/validation/template.go 中的注释该行为对应 GitHub issue #3834。基本用法与示例命令语法bd lint [issue-id...] [flags]常用示例bd lint # 检查所有 open 状态的 Issue bd lint bd-abc # 检查指定的单个 Issue bd lint bd-abc bd-def # 同时检查多个 Issue bd lint --type bug # 只检查 bug 类型的 Issue bd lint --status all # 检查所有 Issue包含已关闭的指定多个 Issue ID 时命令会逐个读取对于不存在的 ID会在 stderr 输出Issue not found: id并跳过而不会中断整体执行对应源码 cmd/bd/lint.go 中的lintCollectByIDs测试用例nonexistent_id_graceful也验证了这一行为。Flags 详解bd lint提供两个过滤标志定义于 cmd/bd/lint.go标志简写默认值作用--status string-sopen按状态过滤传入all表示包含已关闭的 Issue--type string-t空不过滤按 Issue 类型过滤如bug、task、feature、epic过滤逻辑在buildLintFilter中实现cmd/bd/lint.go状态为空或open时构造一个StatusOpen过滤器只有显式传入all时才不限制状态传入其他字符串则被转换为对应IssueType。类型过滤为空时不限类型。从源码看--type实际上支持的类型集合比文档提示更广——IssueType类型系统还包括decision、spike、story、chore、milestone等init()中的 flag 描述列出了bug, task, feature, epic, decision, spike, story, chore, milestone全部九种其中chore类型虽然可以被过滤出来但由于它没有内置章节要求永远不会产生警告对应测试lint_by_type_chore_no_warnings。此外bd lint支持全局的--json标志测试助手bdLintJSON即通过bd lint --json调用用于机器可读输出。输出格式人类可读输出当存在章节缺失时默认输出按 Issue 分组展示Template warnings (2 issues, 3 warnings): bd-abc [bug]: Bug without template ⚠ Missing: Steps to Reproduce ⚠ Missing: Acceptance Criteria bd-def [task]: Task without AC ⚠ Missing: Acceptance Criteria当所有被检查的 Issue 都合规时输出✓ No template warnings found (N issues checked)JSON 输出配合--json标志输出结构化结果便于 CI 或脚本解析。JSON 顶层包含三个字段total警告总数、issues有警告的 Issue 数、results明细数组。每个results条目对应源码中的LintResult结构cmd/bd/lint.go{ total: 2, issues: 1, results: [ { id: bd-abc, title: Bug without template, type: bug, missing: [Steps to Reproduce, Acceptance Criteria], warnings: 2 } ] }missing数组中的每一项都是缺失章节的标题文本。退出码语义退出码是bd lint用于自动化集成的重要契约对应测试exit_code_1_on_warnings与exit_code_0_when_clean0所有被检查的 Issue 均满足模板要求1存在章节缺失警告即使使用--json输出只要results非空退出码仍为 1。这意味着可以直接把bd lint接入 CI 门禁当有 Issue 模板不完整时流水线失败从而强制团队维护可执行的 Issue 描述。底层校验实现剖析bd lint的命令层只负责收集 Issue 与渲染输出真正的校验逻辑位于 internal/validation/template.go核心函数链为ValidateTemplate(issueType, description)将描述文本与mergeLintSections(issueType)返回的必要章节逐一比对mergeLintSections(issueType)把内置章节RequiredSections()与配置追加章节合并去重内置章节优先其规范 Hint 优先保留LintIssue(issue)面向完整Issue结构的入口同时检查Description与AcceptanceCriteria两个字段。匹配规则灵活而非教条ValidateTemplate采用大小写不敏感的包含匹配它把章节标题如## Steps to Reproduce去掉 Markdown 前缀后转为小写再检查描述中是否包含该文本。这意味着以下写法都能通过校验## Steps to Reproduce### Steps to Reproduce任意级标题前缀均可正文中出现steps to reproduce字样不要求精确的 Markdown 格式验收标准字段的豁免GH#2468LintIssue有一个关键增强internal/validation/template.go如果 Issue 的AcceptanceCriteria专用字段非空则即使描述中没有Acceptance Criteria或Success Criteria标题该章节要求也视为已满足。这避免了内容其实已填写、只因缺一个标题就被标记的误报让校验更贴近真实工作流。失败信息结构校验失败时返回TemplateError其中包含IssueType与Missing []MissingSection每个MissingSection携带章节标题Heading与写作指引Hint例如Heading: ## Steps to Reproduce、Hint: Describe how to reproduce the bug。命令层将这些 Hint 过滤掉、只取 Heading 进入输出。通过配置扩展章节要求Additive 机制内置章节要求之外bd lint支持按类型追加额外必需章节配置命名空间为lint.sections.typebd config set lint.sections.epic Standards scorecard, Cost配置后epic类型除内置的Success Criteria外还会要求描述中包含Standards scorecard与Cost两个章节。该机制的核心设计原则是纯追加ADDITIVE配置只增加要求绝不放松内置要求——内置章节在任何配置下都不可被绕过见 internal/validation/template.go 中LintSectionsConfigPrefix的说明。配置解析函数ConfiguredLintSections对每个配置值做了规范化处理以逗号分隔逐项去除首尾空白丢弃空项剥离标题前缀#后统一规范为## 标题形式因此# Cost、## Cost、cost等价按标题文本做大小写不敏感的去重保留首次出现的大小写写法。追加章节在mergeLintSections中与内置章节合并最终同样进入ValidateTemplate的匹配流程。这一机制让不同团队可以在不修改代码的前提下将自身的流程规范如安全评审、成本评估、发布清单固化为 lint 门禁。与其他命令的协同bd create创建 Issue 时的模板校验与bd lint共享同一套RequiredSection定义internal/types/types.go 注释明确说明其同时被bd lint与bd create --validate使用因此创建时未达标、事后用bd lint复查规则完全一致不存在创建与检查标准漂移的问题。关闭原因校验同一个validation包还提供ValidateCloseReason用于validation.on-close配置下对关闭原因做最低质量标准检查非空、非closed默认值、长度不低于 20 字符与模板 lint 共同构成 Issue 生命周期的质量防线。后端路由命令实现了嵌入式embedded与代理proxied两种后端模式的分发usesProxiedServer()判断见 cmd/bd/lint.go与项目整体的双后端架构保持一致代理模式的独立实现位于 cmd/bd/lint_proxied_server.go。测试验证bd lint的行为有完整的嵌入式集成测试覆盖见 cmd/bd/lint_embedded_test.go按 ID 检查裸 bug缺章节产生警告带完整章节的 bug 不产生警告lint_specific_id_with_warnings、lint_specific_id_clean多 ID 检查多个违规 Issue 同时被报告lint_multiple_ids类型过滤--type bug只命中 bug--type chore永远零警告lint_by_type_bug、lint_by_type_chore_no_warnings状态过滤--status all包含已关闭的违规 Issue默认open排除之lint_status_all、lint_status_default_excludes_closed输出契约JSON 的missing数组非空、人类可读输出含Missing:标记、干净时输出No template warnings、有警告时退出码为 1json_missing_sections、human_readable_*、exit_code_*。这些测试同时印证了退出码、过滤语义与输出格式可作为接入脚本时的行为基准。小结bd lint以按类型校验模板章节这一简单规则把 Issue 质量从依赖个人自觉提升为可自动执行的工程门禁默认覆盖全部 open Issue支持按 ID、类型、状态精确圈定检查范围人类可读与 JSON 双输出满足交互与 CI 两种场景退出码契约让它能无缝嵌入流水线而lint.sections.type的追加式配置则允许团队把自定义规范固化进检查体系。其背后是internal/validation与internal/types中清晰解耦的类型—规则—校验三层设计值得作为CLI 质量工具如何与领域模型协同的实现参考。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
