Beads `bd statuses` 命令全解：内置状态、`status.custom` 自定义状态与分类行为

Beadsbd statuses命令全解内置状态、status.custom自定义状态与分类行为【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd statuses是 Beads 中用于查看全部合法 issue 状态及其分类的视图命令。它一方面展示 open、in_progress、blocked 等内置状态的图标与行为分类另一方面读取通过status.custom配置的自定义状态帮助团队理解当前工作流中每个状态在bd ready、bd list等命令中的可见性与语义。读完本文你将掌握内置状态分类的完整映射、status.custom的配置语法与校验规则以及自定义状态如何影响筛选、回收等下游行为。命令概览bd statuses属于views命令组功能为List valid issue statuses列出合法 issue 状态。其完整用法如下bd statuses [flags]常用形式bd statuses # 以表格形式列出所有状态含图标与分类 bd statuses --json # 以 JSON 输出该命令的--json标志与 Beads 其他命令如bd list --json一致便于脚本化消费状态清单。命令声明与执行入口位于 cmd/bd/statuses.go执行时先尝试走代理服务器路径usesProxiedServer()否则要求直接数据库访问ensureDirectMode随后从存储层读取自定义状态并渲染输出。内置状态与分类映射Beads 内置 7 种状态每种都带有固定行为分类和说明文字定义于 cmd/bd/statuses.go状态分类说明openactiveAvailable to work (default)可认领工作默认状态in_progresswipActively being worked on正在被处理blockedwipBlocked by a dependency被依赖阻塞deferredfrozenDeliberately put on ice for later刻意搁置备用closeddoneCompleted已完成pinnedfrozenPersistent, stays open indefinitely长期保持开启的常驻条目hookedwipAttached to an agents hook已挂接到 agent 钩子对应地状态常量定义于 internal/types/types.goAllStatuses列表internal/types/types.go是Status.IsValid()校验与bd schema枚举的唯一权威来源——即内置状态始终合法无需任何配置。内置状态到分类的映射逻辑集中在BuiltInStatusCategoryinternal/types/types.goopen→activein_progress、blocked、hooked→wipclosed→donedeferred、pinned→frozen分类Category控制行为分类决定了状态在各命令中的可见性是 Beads 工作流的核心机制原文定义如下active— 出现在bd ready和默认bd list中wip— 排除于bd ready但在默认bd list中可见done— 排除于bd ready和默认bd listfrozen— 排除于bd ready和默认bd list简言之active是可认领状态其余分类逐步从就绪队列中退场。wip代表进行中的工作仍可在列表中看到done与frozen则属于不参与默认视图的状态done表示完成frozen表示刻意冻结。分类常量定义于 internal/types/types.go其中还包含一个内部使用的unspecified分类用于未指定分类的兼容场景用户可配置的合法分类集合active/wip/done/frozen见validCategoriesinternal/types/types.go。从源码结构还可以看到分类不仅影响视图可见性也参与后台回收逻辑wisp相关代码cmd/bd/wisp.go将wipin_progress/blocked/hooked与frozendeferred/pinned视为正在进行或刻意搁置的工作而不可按年龄回收activeopen与doneclosed则允许按年龄回收。这说明分类系统同时串联了就绪队列、默认视图、GC/回收安全三层语义。通过status.custom配置自定义状态内置状态之外可以通过status.custom配置项添加团队自定义状态。核心命令bd config set status.custom in_review:active,qa_testing:wip,on_hold:frozen配置格式为逗号分隔的名称:分类键值对。完整支持两种格式分类标注格式推荐in_review:active,qa_testing:wip,on_hold:frozen旧版纯名称格式review,qa_testing不写分类兼容历史配置解析规则由ParseCustomStatusConfig实现internal/types/types.go具体约束如下规则说明名称格式必须以小写字母开头仅含小写字母、数字、-、_正则^[a-z][a-z0-9_-]*$分类合法性只能是active、wip、done、frozen之一否则报错内置状态冲突自定义名称不得与 open/in_progress/blocked/deferred/closed/pinned/hooked 撞名重复检测同一配置中不得出现重复名称数量上限最多 50 个自定义状态maxCustomStatuses空分类foo:这种冒号后为空的写法会被拒绝若使用旧版纯名称格式如review,qa_testing解析器会为它们分配unspecified分类见 internal/types/types.go 与CategoryUnspecified定义。这类状态依然合法但会被排除在bd ready之外——这正是原文档强调的legacy format 状态有效但不可就绪的底层原因。配置的读取与生效路径status.custom的实际读取遵循数据库优先、配置回退的分层逻辑见 internal/storage/issueops/config_helpers.go优先从数据库的custom_statuses表读取resolveCustomStatusesFromTableInTx表为空时回退到status.custom配置键getConfigKeysInTx配置键也不存在时再回退到 config.yaml 中的status.custom列表GetCustomStatusesFromYAML定义于 internal/config/config.go。当bd config set status.custom ...被调用时还会触发syncCustomStatusesTableinternal/storage/issueops/config_helpers.go把解析后的配置同步写入custom_statuses表保证后续读取稳定一致。输出详解文本视图与 JSON 视图renderStatusescmd/bd/statuses.go负责最终渲染。文本视图分为两段Built-in statuses: ● open [active] Available to work (default) ◐ in_progress [wip] Actively being worked on ⛔ blocked [wip] Blocked by a dependency ... Custom statuses: ... in_review [active] ... qa_testing [wip]图标由ui.RenderStatusIcon/ui.RenderStatusIconWithCategory生成具体符号以终端渲染为准。如果未配置任何自定义状态则会打印提示并给出配置指引No custom statuses configured. Configure with: bd config set status.custom name:category,... Categories: active, wip, done, frozenJSON 视图bd statuses --json返回结构化数据包含built_in_statusesname/category/icon/description与可选的custom_statuses数组name/category结构定义见 cmd/bd/statuses.go{ built_in_statuses: [ {name: open, category: active, icon: ●, description: Available to work (default)} ], custom_statuses: [{name: in_review, category: active}] }状态校验与下游联动自定义状态配置后会深度影响整个系统的校验与查询行为写入校验issue 的状态合法性通过Status.IsValidWithCustom/IsValidWithCustomStatuses检查internal/types/types.go校验时会把custom_statuses一并纳入因此使用自定义状态的 issue 可以正常创建、编辑与导入ValidateWithCustom、ValidateForImport。列表筛选bd list的--status别名--state标志支持逗号分隔的多状态过滤如bd list --status open,in_progress见 cmd/bd/list.go过滤值自然涵盖自定义状态。就绪队列bd ready只展示active分类内置open与自定义 active 状态unspecified旧格式状态即使合法也不会出现在就绪队列中。测试保障仓库提供了专门的测试覆盖例如 cmd/bd/statuses_types_proxied_integration_test.go 验证代理模式下自定义状态的分类透传config_test.go中验证GetCustomStatusesDetailed对 active/wip/done 分类的解析结果cmd/bd/config_test.gohuman_test.go则覆盖了文本渲染中自定义状态的场景。典型配置示例以下组合适合一个带评审与测试环节的团队工作流# 配置三个自定义状态并绑定分类 bd config set status.custom in_review:active,qa_testing:wip,on_hold:frozen # 查看生效结果 bd statuses # 脚本化获取完整状态清单 bd statuses --json # 在列表与就绪队列中验证可见性 bd ready bd list配置后in_review会出现在bd ready与默认bd list中可被认领qa_testing出现在默认bd list但不在bd ready中进行中的测试工作on_hold两个视图都不出现刻意冻结。如需修改直接重新执行bd config set status.custom ...覆盖即可配置变更会同步到数据库表并即时生效。小结bd statuses不只是一个只读的状态罗列命令它是理解 Beads 状态机与工作流语义的入口内置 7 状态 4 分类构成基础骨架status.custom提供可扩展的团队工作流能力分类系统则统一决定了就绪可见性、列表可见性与回收安全。结合 cmd/bd/statuses.go 的实现与 internal/types/types.go 的类型定义你可以完全掌控从状态如何定义到状态如何影响命令行为的完整链路。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考