Beads 项目统计实战指南用stats技能掌控编码 Agent 的任务全景【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 将编码 Agent 的工作流建立在结构化 issue 数据库之上而stats技能plugins/beads/skills/beads/commands/stats.md是快速把握项目全局的一站式入口通过 beads MCP 的stats工具读取项目指标并以清晰的方式呈现给 Agent 与用户。读完本文你将掌握stats工具返回的全部统计字段及其语义、底层 CLI 调用链与可用参数、如何派生优先级/类型分布与完成率等展示指标以及基于统计结果驱动后续操作blocked / ready / update的完整闭环。一、技能定位何时使用statsstats技能对应的命令是bd stats即bd status的别名。它就像git status之于工作区一样为 issue 数据库提供快照式总览不需要多次查询一次调用即可获得问题数量、工作就绪度与近期活动概览。适用场景包括项目健康检查快速判断 backlog 是否积压、是否有大量阻塞问题新贡献者/新 Agent 上手读取第一手的项目状态每日站会参考用一组数字汇报昨日进度与当前瓶颈CI/CD 或 shell 提示集成--json输出便于机器消费Agent 决策前置在分配任务、筛选候选 issue 之前先看整体盘子。技能文档明确要求使用 beads MCP 的stats工具获取项目指标并清晰呈现其呈现维度包括按状态统计的问题总数open、in_progress、blocked、closed按优先级分布的问题数按类型分布的问题数bug、feature、task、epic、chore完成率最近更新的问题。二、stats返回的数据全景stats工具的返回结构定义在 MCP 侧的数据模型中integrations/beads-mcp/src/beads_mcp/models.py#L275-L307整体分为summary与recent_activity两块与bd stats --json的输出一一对应。Summary状态与就绪度指标字段JSON 键说明total_issuestotal_issues全部问题总数含 closed 与 pinnedopen_issuesopen_issues状态为 open 的数量in_progress_issuesin_progress_issues状态为 in_progress 的数量closed_issuesclosed_issues状态为 closed 的数量blocked_issuesblocked_issues被阻塞的问题数使用--no-blocked跳过计算时为nulldeferred_issuesdeferred_issues被搁置on ice的问题数默认 0ready_issuesready_issues就绪可做的工作数依赖阻塞集合跳过时同样为nulltombstone_issuestombstone_issues墓碑已删除标记数量默认 0pinned_issuespinned_issues置顶持久问题数默认 0epics_eligible_for_closureepics_eligible_for_closure可关闭的 epic 数见下文注意事项average_lead_time_hoursaverage_lead_time_hours平均交付周期小时这些字段正是 CLI 层 internal/types/types.go#L1839-L1850 中Statistics结构的 JSON 序列化结果两个入口共用同一结构保证 MCP 与 CLI 输出口径一致。RecentActivity近期活动recent_activity记录最近 24 小时的 git 活动概览字段包括hours_tracked跟踪窗口默认 24、commit_count提交数、issues_created/issues_closed/issues_updated/issues_reopened各类 issue 变更数以及total_changes变更总数。注意从源码看活动跟踪已迁移到 Dolt 原生查询cmd/bd/status.go#L190-L195 中getGitActivity当前返回 nil因此 MCP 返回的recent_activity可能为空Agent 呈现时应做空值兜底。三、底层调用链从 MCP 到 CLI 到统计角色stats技能触发的完整链路如下MCP 工具层Agent 调用stats工具对应 integrations/beads-mcp/src/beads_mcp/tools.py#L675-L682 中的beads_stats()其返回值类型为StatsMCP 客户端层beads_stats()调用client.stats()integrations/beads-mcp/src/beads_mcp/bd_client.py#L800-L810它执行bd stats子命令校验返回为 dict 后用Stats.model_validate(data)解析CLI 层bd stats是bd status的别名cmd/bd/status.go#L32-L60命令定义中明确列出了bd status、bd status --no-activity、bd stats --no-blocked --json等用法示例统计角色层bd status通过openStatsReporter()获取issueops.StatsReporter角色cmd/bd/status.go#L116-L121在代理服务器模式下走proxiedStatsReporter()否则走 store 实现。角色接口定义在 issueops/statsreporter.go#L132-L196提供Stats与AssigneeStats两个方法。从源码结构看StatsReporter之所以是独立角色而非计数Counter的扩展是因为其中两个数字——blocked 数与由它派生的 ready 数——来自依赖图维护的传递性is_blocked标志无法用普通谓词在 issues 表上表达这正是统计结果依赖感知的底层原因。四、CLI 参数bd stats/bd status的完整旗标除--json持久旗标定义于 main.go外命令还支持以下参数cmd/bd/status.go#L197-L204旗标作用备注--json以 JSON 格式输出持久旗标MCPstats工具底层即依赖此输出--assigned仅统计分配给当前用户的问题走AssigneeStats路径字段语义与全局统计不同见第六节--no-blocked跳过阻塞数计算更快大工作区性能优化blocked_issues与ready_issues输出为nullproxied-server 模式下不支持--no-activity跳过 git 活动汇总当前实现活动已迁移至 Dolt 原生查询此旗标影响有限--all显示全部问题默认行为保留以兼容典型用法bd status # 人类可读的彩色摘要 bd stats --no-blocked --json # JSON 输出且跳过阻塞扫描更快 bd status --assigned # 只看当前用户的统计五、派生指标优先级分布、类型分布与完成率需要指出的是stats工具的原生返回只包含按状态统计的数字与近期活动不直接包含优先级分布、类型分布和完成率。技能文档要求 Agent present them clearly意味着这些展示指标需要 Agent 在拿到统计结果后派生类型分布可结合bd list --type bug、bd list --type feature等过滤查询逐一统计IssueType支持 bug、feature、task、epic、chore 等枚举或用搜索/查询工具按类型分组优先级分布类似地通过按--priority0–4 档过滤的bd list查询获得各档位数量完成率可由closed_issues / total_issues计算例如 120 个问题中关闭 72 个完成率 60%或更细粒度地按类型/优先级分别计算最近更新的问题stats返回的recent_activity只有计数没有明细需要借助bd search或bd list按更新时间排序获取具体条目。Agent 呈现时建议先给出 Summary 的关键数字再用派生指标补充维度最后落到行动建议形成数字 → 洞察 → 行动的完整段落。六、统计语义的注意事项避免误读从 issueops/statsreporter.go 的角色文档可以提炼出几条易被误读的语义空工作区返回全零而非错误空工作区的统计就是零值摘要这不是异常轮询新工作区时不需要分类错误bucket 之和可能不等于总数自定义状态的问题只计入total而不落入四个标准 bucketpinned_issues按置顶标志计数与各状态 bucket 有重叠blocked 数 ≠ 状态为 blocked 的数量全局统计中的blocked_issues计算的是传递性is_blocked标志被设置的行排除状态为 closed/pinned 者一个状态为 open 但存在未完成 blocker 的问题也会被计入ready 数是算术而非查询ReadyIssues OpenIssues − BlockedIssues下限为 0它不是bd ready的候选集大小——后者还应用类型排除、搁置窗口、指派过滤与数量限制。需要真实就绪工作清单时应直接使用bd ready见 ready.md--no-blocked是一个提示hint而非强约束当被采纳时blocked_issues与ready_issues会成对为null若后端没有快速路径则返回完整数字宁可给真答案也不给慢的假答案epics_eligible_for_closure与average_lead_time_hours目前恒为 0从源码注释看尚无实现计算这两个值它们被保留仅因属于线上序列化结构阅读输出时不要将 0 当作真实答案--assigned路径语义不同AssigneeStats中 blocked 数按存储状态为 blocked统计与全局按标志统计不同ready 数则是真实的就绪工作查询且集合范围包含 ephemeral wisps 层因此个人总数可能大于全局总数。七、基于统计的行动建议闭环技能文档给出的核心价值在于统计之后做什么即把数字翻译成下一步操作阻塞问题多说明依赖图上有未消解的 blocker。运行/beads:blocked对应 blocked.md调查阻塞链找出卡住整个管线的关键节点没有任何 in_progress 工作工作池可能空转。运行/beads:ready对应 ready.md找出就绪可做的任务让 Agent 尽快进入执行状态open 问题大量积压先不急于执行运行/beads:update对应 update.md结合优先级重新排定问题次序避免低价值任务抢占资源。建议将这一闭环固化为 Agent 的固定复盘流程每次stats输出后先判断三个信号阻塞水位、在途工作、backlog 积压再决定进入 blocked / ready / update 中的哪一条路径形成观测—诊断—行动的可复用模式。八、快速验证一条命令拿到全部统计MCP 工具的底层即bd stats --json可在工作区内直接验证bd stats --json输出形如字段名以 internal/types/types.go 的Statistics结构为准{ summary: { total_issues: 120, open_issues: 30, in_progress_issues: 8, closed_issues: 72, blocked_issues: 5, deferred_issues: 0, ready_issues: 25, tombstone_issues: 0, pinned_issues: 0, epics_eligible_for_closure: 0, average_lead_time_hours: 0 }, recent_activity: null }在 MCP 集成场景integrations/beads-mcp中Agent 无需关心 JSON 细节直接调用stats()工具即可获得类型化结果StatsSummary与RecentActivity配合本技能文档的呈现规范与行动建议即可完成从项目体检到任务推进的完整闭环。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads 项目统计实战指南：用 `stats` 技能掌控编码 Agent 的任务全景
Beads 项目统计实战指南用stats技能掌控编码 Agent 的任务全景【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 将编码 Agent 的工作流建立在结构化 issue 数据库之上而stats技能plugins/beads/skills/beads/commands/stats.md是快速把握项目全局的一站式入口通过 beads MCP 的stats工具读取项目指标并以清晰的方式呈现给 Agent 与用户。读完本文你将掌握stats工具返回的全部统计字段及其语义、底层 CLI 调用链与可用参数、如何派生优先级/类型分布与完成率等展示指标以及基于统计结果驱动后续操作blocked / ready / update的完整闭环。一、技能定位何时使用statsstats技能对应的命令是bd stats即bd status的别名。它就像git status之于工作区一样为 issue 数据库提供快照式总览不需要多次查询一次调用即可获得问题数量、工作就绪度与近期活动概览。适用场景包括项目健康检查快速判断 backlog 是否积压、是否有大量阻塞问题新贡献者/新 Agent 上手读取第一手的项目状态每日站会参考用一组数字汇报昨日进度与当前瓶颈CI/CD 或 shell 提示集成--json输出便于机器消费Agent 决策前置在分配任务、筛选候选 issue 之前先看整体盘子。技能文档明确要求使用 beads MCP 的stats工具获取项目指标并清晰呈现其呈现维度包括按状态统计的问题总数open、in_progress、blocked、closed按优先级分布的问题数按类型分布的问题数bug、feature、task、epic、chore完成率最近更新的问题。二、stats返回的数据全景stats工具的返回结构定义在 MCP 侧的数据模型中integrations/beads-mcp/src/beads_mcp/models.py#L275-L307整体分为summary与recent_activity两块与bd stats --json的输出一一对应。Summary状态与就绪度指标字段JSON 键说明total_issuestotal_issues全部问题总数含 closed 与 pinnedopen_issuesopen_issues状态为 open 的数量in_progress_issuesin_progress_issues状态为 in_progress 的数量closed_issuesclosed_issues状态为 closed 的数量blocked_issuesblocked_issues被阻塞的问题数使用--no-blocked跳过计算时为nulldeferred_issuesdeferred_issues被搁置on ice的问题数默认 0ready_issuesready_issues就绪可做的工作数依赖阻塞集合跳过时同样为nulltombstone_issuestombstone_issues墓碑已删除标记数量默认 0pinned_issuespinned_issues置顶持久问题数默认 0epics_eligible_for_closureepics_eligible_for_closure可关闭的 epic 数见下文注意事项average_lead_time_hoursaverage_lead_time_hours平均交付周期小时这些字段正是 CLI 层 internal/types/types.go#L1839-L1850 中Statistics结构的 JSON 序列化结果两个入口共用同一结构保证 MCP 与 CLI 输出口径一致。RecentActivity近期活动recent_activity记录最近 24 小时的 git 活动概览字段包括hours_tracked跟踪窗口默认 24、commit_count提交数、issues_created/issues_closed/issues_updated/issues_reopened各类 issue 变更数以及total_changes变更总数。注意从源码看活动跟踪已迁移到 Dolt 原生查询cmd/bd/status.go#L190-L195 中getGitActivity当前返回 nil因此 MCP 返回的recent_activity可能为空Agent 呈现时应做空值兜底。三、底层调用链从 MCP 到 CLI 到统计角色stats技能触发的完整链路如下MCP 工具层Agent 调用stats工具对应 integrations/beads-mcp/src/beads_mcp/tools.py#L675-L682 中的beads_stats()其返回值类型为StatsMCP 客户端层beads_stats()调用client.stats()integrations/beads-mcp/src/beads_mcp/bd_client.py#L800-L810它执行bd stats子命令校验返回为 dict 后用Stats.model_validate(data)解析CLI 层bd stats是bd status的别名cmd/bd/status.go#L32-L60命令定义中明确列出了bd status、bd status --no-activity、bd stats --no-blocked --json等用法示例统计角色层bd status通过openStatsReporter()获取issueops.StatsReporter角色cmd/bd/status.go#L116-L121在代理服务器模式下走proxiedStatsReporter()否则走 store 实现。角色接口定义在 issueops/statsreporter.go#L132-L196提供Stats与AssigneeStats两个方法。从源码结构看StatsReporter之所以是独立角色而非计数Counter的扩展是因为其中两个数字——blocked 数与由它派生的 ready 数——来自依赖图维护的传递性is_blocked标志无法用普通谓词在 issues 表上表达这正是统计结果依赖感知的底层原因。四、CLI 参数bd stats/bd status的完整旗标除--json持久旗标定义于 main.go外命令还支持以下参数cmd/bd/status.go#L197-L204旗标作用备注--json以 JSON 格式输出持久旗标MCPstats工具底层即依赖此输出--assigned仅统计分配给当前用户的问题走AssigneeStats路径字段语义与全局统计不同见第六节--no-blocked跳过阻塞数计算更快大工作区性能优化blocked_issues与ready_issues输出为nullproxied-server 模式下不支持--no-activity跳过 git 活动汇总当前实现活动已迁移至 Dolt 原生查询此旗标影响有限--all显示全部问题默认行为保留以兼容典型用法bd status # 人类可读的彩色摘要 bd stats --no-blocked --json # JSON 输出且跳过阻塞扫描更快 bd status --assigned # 只看当前用户的统计五、派生指标优先级分布、类型分布与完成率需要指出的是stats工具的原生返回只包含按状态统计的数字与近期活动不直接包含优先级分布、类型分布和完成率。技能文档要求 Agent present them clearly意味着这些展示指标需要 Agent 在拿到统计结果后派生类型分布可结合bd list --type bug、bd list --type feature等过滤查询逐一统计IssueType支持 bug、feature、task、epic、chore 等枚举或用搜索/查询工具按类型分组优先级分布类似地通过按--priority0–4 档过滤的bd list查询获得各档位数量完成率可由closed_issues / total_issues计算例如 120 个问题中关闭 72 个完成率 60%或更细粒度地按类型/优先级分别计算最近更新的问题stats返回的recent_activity只有计数没有明细需要借助bd search或bd list按更新时间排序获取具体条目。Agent 呈现时建议先给出 Summary 的关键数字再用派生指标补充维度最后落到行动建议形成数字 → 洞察 → 行动的完整段落。六、统计语义的注意事项避免误读从 issueops/statsreporter.go 的角色文档可以提炼出几条易被误读的语义空工作区返回全零而非错误空工作区的统计就是零值摘要这不是异常轮询新工作区时不需要分类错误bucket 之和可能不等于总数自定义状态的问题只计入total而不落入四个标准 bucketpinned_issues按置顶标志计数与各状态 bucket 有重叠blocked 数 ≠ 状态为 blocked 的数量全局统计中的blocked_issues计算的是传递性is_blocked标志被设置的行排除状态为 closed/pinned 者一个状态为 open 但存在未完成 blocker 的问题也会被计入ready 数是算术而非查询ReadyIssues OpenIssues − BlockedIssues下限为 0它不是bd ready的候选集大小——后者还应用类型排除、搁置窗口、指派过滤与数量限制。需要真实就绪工作清单时应直接使用bd ready见 ready.md--no-blocked是一个提示hint而非强约束当被采纳时blocked_issues与ready_issues会成对为null若后端没有快速路径则返回完整数字宁可给真答案也不给慢的假答案epics_eligible_for_closure与average_lead_time_hours目前恒为 0从源码注释看尚无实现计算这两个值它们被保留仅因属于线上序列化结构阅读输出时不要将 0 当作真实答案--assigned路径语义不同AssigneeStats中 blocked 数按存储状态为 blocked统计与全局按标志统计不同ready 数则是真实的就绪工作查询且集合范围包含 ephemeral wisps 层因此个人总数可能大于全局总数。七、基于统计的行动建议闭环技能文档给出的核心价值在于统计之后做什么即把数字翻译成下一步操作阻塞问题多说明依赖图上有未消解的 blocker。运行/beads:blocked对应 blocked.md调查阻塞链找出卡住整个管线的关键节点没有任何 in_progress 工作工作池可能空转。运行/beads:ready对应 ready.md找出就绪可做的任务让 Agent 尽快进入执行状态open 问题大量积压先不急于执行运行/beads:update对应 update.md结合优先级重新排定问题次序避免低价值任务抢占资源。建议将这一闭环固化为 Agent 的固定复盘流程每次stats输出后先判断三个信号阻塞水位、在途工作、backlog 积压再决定进入 blocked / ready / update 中的哪一条路径形成观测—诊断—行动的可复用模式。八、快速验证一条命令拿到全部统计MCP 工具的底层即bd stats --json可在工作区内直接验证bd stats --json输出形如字段名以 internal/types/types.go 的Statistics结构为准{ summary: { total_issues: 120, open_issues: 30, in_progress_issues: 8, closed_issues: 72, blocked_issues: 5, deferred_issues: 0, ready_issues: 25, tombstone_issues: 0, pinned_issues: 0, epics_eligible_for_closure: 0, average_lead_time_hours: 0 }, recent_activity: null }在 MCP 集成场景integrations/beads-mcp中Agent 无需关心 JSON 细节直接调用stats()工具即可获得类型化结果StatsSummary与RecentActivity配合本技能文档的呈现规范与行动建议即可完成从项目体检到任务推进的完整闭环。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考