企业官网建设流程全解析

Beads 项目统计实战指南：用stats技能掌控编码 Agent 的任务全景

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

Beads 将编码 Agent 的工作流建立在结构化 issue 数据库之上，而stats技能（plugins/beads/skills/beads/commands/stats.md）是快速把握项目全局的一站式入口：通过 beads MCP 的stats工具读取项目指标，并以清晰的方式呈现给 Agent 与用户。读完本文，你将掌握stats工具返回的全部统计字段及其语义、底层 CLI 调用链与可用参数、如何派生优先级/类型分布与完成率等展示指标，以及基于统计结果驱动后续操作（blocked / ready / update）的完整闭环。

一、技能定位：何时使用stats

stats技能对应的命令是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：状态与就绪度指标

这些字段正是 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技能触发的完整链路如下：

1. MCP 工具层：Agent 调用stats工具，对应 integrations/beads-mcp/src/beads_mcp/tools.py#L675-L682 中的beads_stats()，其返回值类型为Stats；
2. MCP 客户端层：beads_stats()调用client.stats()（integrations/beads-mcp/src/beads_mcp/bd_client.py#L800-L810），它执行bd stats子命令，校验返回为 dict 后用Stats.model_validate(data)解析；
3. CLI 层：bd stats是bd status的别名（cmd/bd/status.go#L32-L60），命令定义中明确列出了bd status、bd status --no-activity、bd stats --no-blocked --json等用法示例；
4. 统计角色层：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）：

典型用法：

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 等枚举），或用搜索/查询工具按类型分组；
• 优先级分布：类似地，通过按--priority（0–4 档）过滤的bd list查询获得各档位数量；
• 完成率：可由closed_issues / total_issues计算（例如 120 个问题中关闭 72 个，完成率 60%），或更细粒度地按类型/优先级分别计算；
• 最近更新的问题：stats返回的recent_activity只有计数没有明细，需要借助bd search或bd list按更新时间排序获取具体条目。

Agent 呈现时建议先给出 Summary 的关键数字，再用派生指标补充维度，最后落到行动建议，形成"数字 → 洞察 → 行动"的完整段落。

六、统计语义的注意事项（避免误读）

从 issueops/statsreporter.go 的角色文档可以提炼出几条易被误读的语义：

1. 空工作区返回全零而非错误：空工作区的统计就是零值摘要，这不是异常，轮询新工作区时不需要分类错误；
2. bucket 之和可能不等于总数：自定义状态的问题只计入total而不落入四个标准 bucket；pinned_issues按置顶标志计数，与各状态 bucket 有重叠；
3. blocked 数 ≠ 状态为 blocked 的数量：全局统计中的blocked_issues计算的是传递性is_blocked标志被设置的行（排除状态为 closed/pinned 者），一个状态为 open 但存在未完成 blocker 的问题也会被计入；
4. ready 数是算术而非查询：ReadyIssues = OpenIssues − BlockedIssues（下限为 0），它不是bd ready的候选集大小——后者还应用类型排除、搁置窗口、指派过滤与数量限制。需要真实就绪工作清单时，应直接使用bd ready（见 ready.md）；
5. --no-blocked是一个提示（hint）而非强约束：当被采纳时，blocked_issues与ready_issues会成对为null；若后端没有快速路径，则返回完整数字（宁可给真答案也不给慢的假答案）；
6. epics_eligible_for_closure与average_lead_time_hours目前恒为 0：从源码注释看，尚无实现计算这两个值，它们被保留仅因属于线上序列化结构；阅读输出时不要将 0 当作真实答案；
7. --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