Beads 的 bd 命令行全集：108 个命令的官方参考指南与自动化文档生成管线-二趣网

Beads 的 bd 命令行全集：108 个命令的官方参考指南与自动化文档生成管线

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

本指南以 Beads 项目官方 CLI Reference 文档（docs/cli-reference/index.md）为骨架，系统梳理bd命令行的全部 108 个顶层命令、全局标志位、按场景划分的命令族，并深入剖析这些参考文档背后"从bd help自动生成到站点页面"的完整流水线。读完本文，你将能按场景快速定位所需命令、理解每个命令的定位与用法，并掌握如何用一条脚本命令重新生成与校验整套 CLI 文档。

一、CLI Reference 是什么：一张覆盖全部 108 个 bd 命令的索引

Beads（bd）是一个为编码 Agent 提供持久记忆与任务编排能力的命令行工具。其官方 CLI 参考（CLI Reference）不是手写文档，而是从运行中的bd命令树直接生成的权威索引，覆盖当前全部108 个顶层bd命令。它由两部分组成：

索引页（即本指南所依托的 docs/cli-reference/index.md）：列出全部 108 个命令的清单，每个命令链接到各自独立的参考页；
完整参考（docs/CLI_REFERENCE.md）：一份 6884 行的单文件全集，按功能场景分组，包含每个命令的用途、示例、子命令与参数，并附带全部全局标志位说明。

这两份文件都带有{/* AUTO-GENERATED: do not edit manually */}标记，意味着内容全部来自bd help --docs-root的输出，任何人不应手工编辑它们——任何对命令行为、帮助文本或标志位的修改，都应通过重新生成来同步到文档中。这一点从各命令独立参考页（如 docs/cli-reference/create.md 的头部）均可看到："Generated frombd help --doc create"。

二、108 个命令全览：按功能场景组织的命令地图

索引页列出了全部 108 个顶层命令。结合 docs/CLI_REFERENCE.md 中的场景分组，可以按用途将这些命令组织为以下八大类，便于按需快速定位。

2.1 议题日常操作（Working With Issues）

围绕 issue（议题）生命周期管理的核心命令：

命令	定位
`bd create`	创建新 issue，也可从 markdown 或 graph JSON 批量创建（别名`new`）
`bd assign`	分配负责人，等价于`bd update <id> --assignee <name>`
`bd list`/`bd show`/`bd search`/`bd query`	查看与检索 issue
`bd close`/`bd reopen`	关闭与重新打开 issue
`bd edit`/`bd update`	编辑 issue 字段（`$EDITOR`中编辑 / 命令行更新）
`bd comment`/`bd comments`/`bd note`	评论与备注管理
`bd label`/`bd tag`	标签管理（增删、传播到子议题、全库标签列举）
`bd priority`/`bd set-state`/`bd state`	优先级、操作状态（状态维度）管理
`bd delete`	删除 issue 并清理引用
`bd link`	建立 issue 间的依赖关系
`bd gate`/`bd merge-slot`	异步协调门（gate）与串行化冲突解决的 merge-slot
`bd todo`	TODO 事项便捷封装（add / done / list）
`bd q`	快速捕获：创建 issue 并只输出 ID

2.2 视图与报表（Views & Reports）

面向数据洞察的命令：

bd count：按过滤器统计 issue 数量；
bd diff：展示两个提交或分支间的变更；
bd history：查看 issue 的版本历史；
bd find-duplicates/bd duplicate/bd duplicates：查找并合并语义相似的重复 issue；
bd lint：检查 issue 是否缺少模板段落；
bd stale：展示长期未更新的过期 issue；
bd status/bd statuses/bd types：库概览统计、合法状态列表、合法类型列表。

2.3 依赖与结构（Dependencies & Structure）

bd dep系列提供依赖管理（add / remove / list / tree / cycles / relate / unrelate），bd graph展示依赖图并校验图完整性，bd epic/bd swarm处理史诗与 swarm 分子结构，bd supersede标记议题被新议题取代，bd orphans识别"提交中已引用但仍打开"的孤儿议题。

2.4 同步与数据（Sync & Data）

bd backup：Dolt 备份的初始化、同步、恢复与状态查看；
bd branch/bd vc：分支管理与版本控制操作（commit / merge / status）；
bd export/bd import：JSONL 格式导出与导入；
bd federation：点对点联邦（需要 CGO 支持，纯 Go 构建下会显示 stub 提示）；
bd restore：恢复被压缩（compact）议题的压缩前内容。

2.5 安装与配置（Setup & Configuration）

bd init：在当前目录初始化.beads/目录与 Dolt 数据库（详见本文第五节）；
bd bootstrap：为全新 clone 与恢复场景做非破坏性数据库设置；
bd config系列：配置管理（set / get / list / unset / set-many / show / apply / drift / validate）；
bd dolt系列：Dolt 引擎配置（start / stop / push / pull / remote / commit / status / show / test 等）；
bd context/bd where/bd info：查看仓库身份、beads 位置与数据库信息；
bd hooks：git hooks 安装 / 列举 / 执行 / 卸载；
bd setup：与 AI 编辑器（Claude、Cursor、Aider 等）集成；
bd memories/bd remember/bd recall/bd forget：持久记忆的列出、存储、检索与删除——这正是 Beads "给编码 Agent 装上记忆"定位的核心能力；
bd human系列：人类介入事项（list / respond / dismiss / stats）；
bd onboard/bd prime/bd quickstart：为 Agent 输出工作流上下文。

2.6 维护（Maintenance）

bd doctor：检查并修复 beads 安装健康状态（官方建议"从这里开始"），支持--perf性能诊断、--output导出诊断 JSON、--check单项检查（artifacts / conventions / pollution / validate）与--deep深图校验；
bd compact/bd flatten/bd gc：压缩 Dolt 提交历史、压平全部历史、垃圾回收（老 issue 衰减 + 提交压缩 + Dolt GC）；
bd prune/bd purge：删除关闭的旧 issue / 关闭的临时（ephemeral）issue 以回收空间；
bd migrate：迁移（hooks / issues / schema / sync）；
bd batch：在单个数据库事务中执行多个写操作；
bd sql/bd ping/bd preflight/bd recompute-blocked/bd rename-prefix/bd rules/bd upgrade/bd worktree：SQL 直查、连通性检测、PR 就绪清单、blocked 状态重算、前缀重命名、规则审计与压缩、版本升级管理、worktree 并行开发。

2.7 集成与高级（Integrations & Advanced）

五大外部平台集成，每个都有近乎对称的 pull / push / sync / status 子命令族：

bd jira（含 teams 列举）、bd linear、bd github（含 repos 列举）、bd gitlab（含 projects 列举）、bd ado（Azure DevOps，含 projects 列举）、bd notion（含 connect / init）；
bd repo：多仓库同步配置（add / list / remove / sync）；
bd admin：数据库维护（cleanup / compact / reset）；
bd audit：记录并标记 Agent 交互（append-only JSONL）；
bd formula/bd cook/bd mol：公式管理、编译公式为 proto、分子（molecule）工作流（bond / pour / distill / squash / wisp 等）；
bd metrics：匿名用量指标开关与示例查看。

2.8 其他（Other Commands）

bd completion（bash / zsh / fish / powershell 自动补全脚本生成）、bd help、bd version、bd init-safety、bd mail、bd blocked、bd defer/bd undefer、bd rename、bd ship、bd ready、bd swarm、bd tag、bd children、bd promote（将 wisp 提升为永久 bead）等。

三、全局标志位：每个命令都适用的公共参数

bd提供了跨命令共享的全局标志，适用于任何命令（见 docs/CLI_REFERENCE.md）：

--actor string # 审计追踪的操作者名称（默认取 $BEADS_ACTOR、git user.name、$USER） --db string # 数据库路径（默认自动发现 .beads/*.db） -C, --directory string # 执行前切换目录（类似 git -C） --dolt-auto-commit string # Dolt 自动提交策略：off|on|batch（默认 off，可用配置键 dolt.auto-commit 覆盖） --global # 使用全局共享服务器数据库（beads_global） --ignore-schema-skew # 容忍前向 schema 漂移继续执行（部分查询可能失败） --json # 以 JSON 格式输出 --profile # 生成 CPU profile 供性能分析 -q, --quiet # 抑制非必要输出（只保留错误） --readonly # 只读模式：阻止写操作（用于 worker 沙箱） --sandbox # 沙箱模式：禁用 Dolt 自动推送 -v, --verbose # 启用详细/调试输出

其中--dolt-auto-commit的batch模式值得特别注意：它把提交推迟到bd dolt commit，未提交的变更会保留在工作集中，进程收到 SIGTERM/SIGHUP 时会冲刷待处理提交——这为批处理场景提供了吞吐与一致性的折中。

四、参考文档从何而来：从`bd help`到站点的两层生成管线

CLI Reference 全部由仓库中的 scripts/generate-cli-docs.sh 生成，采用"中性输出 + 站点后处理"的两阶段架构：

阶段 1：bd help --docs-root <root>产生厂商中立的 Markdown。bd本身不感知任何站点生成器格式，只把通用命令树输出到docs/CLI_REFERENCE.md以及暂存目录build/cli-docs/。

阶段 2：go run ./tools/docsmint <root>做 Mintlify 后处理。tools/docsmint/main.go 的注释明确指出：所有 Mintlify 特定内容——MDX 安全注释标记、无扩展名路由链接、docs/docs.json 中 CLI Reference 页面数组——全部发生在仓库工具里，开源二进制保持零站点生成器依赖。

一条命令即可重新生成全部文档：

./scripts/generate-cli-docs.sh

脚本还提供--check校验模式：它会重新生成到临时目录并与已提交文档做 diff，若不同则报错退出（可用于 CI 防止文档漂移）：

./scripts/generate-cli-docs.sh --check

CI 中对应的漂移检查脚本为 scripts/check-cli-docs-drift.sh。

4.1 版本钉扎（pin）：文档永远描述已发布版本

仓库根目录的 docs/cli-docs.pin 文件钉住了生成文档所用的bd版本（当前为v1.2.2）。其含义是：公开文档站点描述的是最新的已发布 release，而非 main 分支源码。因此文档流水线会从该 tag 构建bd（CGO_ENABLED=0纯 Go 构建，与 CI 一致），而不是使用当前 checkout。发布时需同步 bump 该 tag 并重新运行生成脚本；设BD_DOCS_IGNORE_PIN=1可绕过钉扎。

4.2 CGO 一致性守卫

脚本内置了一个针对bd federation的守卫：CGO 构建会暴露完整的 federation 命令树，而 CI 的纯 Go 构建（CGO_ENABLED=0 -tags gms_pure_go）只会输出 stub 提示 "Federation commands require CGO"（见 cmd/bd/federation_nocgo.go）。若检测到提供的二进制是 CGO 版，脚本会警告并自动重建钉扎版本的纯 Go 二进制，避免产生大量虚假的 federation 文档变更；设BD_DOCS_ALLOW_CGO=1可强制信任给定二进制。

五、实操示例：结合独立参考页理解命令细节

每个命令的独立参考页（docs/cli-reference/ 目录下 108 个.md文件）以bd help --doc <命令>为来源，包含语法、别名、全部标志位与示例。以下选取三个典型命令展示参考页的用法：

5.1`bd create`：创建 issue 或批量创建

参考页 docs/cli-reference/create.md 展示了一个信息量极大的命令，支持从标题参数、markdown 文件、graph JSON 三种方式创建：

bd create "Fix login bug" -p 0 -t bug -a alice --due tomorrow bd create -f issues.md # 从 markdown 批量创建 bd create --graph plan.json --dry-run # 从 JSON 计划创建依赖图并预览 bd create --type event --event-category agent.started --event-target bd-20 bd create --waits-for bd-15 --waits-for-gate all-children

关键标志位一览（完整见参考页）：-p/--priority（0-4 或 P0-P4，默认2）、-t/--type（bug|feature|task|epic|chore|decision，默认task，enhancement/feat→feature、dec/adr→decision为别名）、--due（支持+6h、+1d、+2w、tomorrow、next monday、2025-01-15等格式）、--defer（推迟到指定日期前对bd ready隐藏）、--deps（格式type:id或id）、--mol-type（swarm / patrol / work）、--wisp-type（heartbeat、ping、patrol、gc_report 等 TTL 压缩类型）、--ephemeral（短生命周期、受 TTL 压缩）、--metadata（JSON 字符串或@file.json）、--validate（校验描述包含类型所需章节）、--silent（脚本只输出 ID）等。

5.2`bd config`：配置即数据库，版本控制友好

参考页 docs/cli-reference/config.md 说明：配置按项目存储在 beads 数据库中，对版本控制友好，主要命名空间包括export.*、import.*、jira.*、linear.*、github.*、custom.*、status.*、doctor.suppress.*。典型操作：

bd config set export.auto true # 启用自动导出（默认 false） bd config set export.path "beads.jsonl" # 自定义导出文件名（相对 .beads/） bd config set export.interval 60s # 导出最小间隔（默认 60s） bd config set status.custom "awaiting_review,awaiting_testing,awaiting_docs" bd config set doctor.suppress.pending-migrations true # 按 slug 抑制 doctor 警告 bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ # 原子批量设置 bd config show --source config.yaml # 查看带来源注解的生效配置 bd config drift --json # 只读检测配置与现实漂移（退出码 1=有漂移） bd config apply --dry-run # 预览一致性修正 bd config validate # 校验同步相关配置（sovereignty/remote/URL/routing.mode）

config show的优先级链条为：env（BD_*/BEADS_*环境变量）> config.yaml（.beads/config.yaml）> default（内置默认值），另有 metadata、database、git 三类补充来源。

5.3`bd init`与`bd doctor`：入口与健康检查

docs/cli-reference/init.md 说明：bd init默认使用内嵌 Dolt 引擎（无需外部服务），--server可切换外部dolt sql-server；--stealth通过.git/info/exclude实现个人隐形使用；BD_NON_INTERACTIVE=1或--non-interactive跳过交互提示并默认角色为 maintainer；密码通过BEADS_DOLT_PASSWORD环境变量传入。
docs/cli-reference/doctor.md 展示bd doctor的六大模式：常规健康检查（目录存在性、schema 兼容、git hooks、.gitignore等）、--perf性能诊断、--output诊断 JSON 导出、--check单项检查、--deep深图校验、--serverDolt 服务器健康检查。

六、配套资源：如何继续深入

单文件完整参考：docs/CLI_REFERENCE.md（6884 行，含全部子命令、示例、标志位）；
独立命令页：docs/cli-reference/（108 个.md，按命令名索引）；
生成与校验脚本：scripts/generate-cli-docs.sh、scripts/check-cli-docs-drift.sh；
站点后处理器：tools/docsmint/main.go；
站点导航配置（含 CLI Reference 页面数组与历史版本重定向）：docs/docs.json；
版本钉扎文件：docs/cli-docs.pin；
命令实现源码：cmd/bd/（如bd create相关实现见 cmd/bd/create.go、配置实现见 cmd/bd/config.go）；
更多入门材料：docs/getting-started/、README.md。

七、维护约定与注意事项

不要手工编辑生成文件：docs/CLI_REFERENCE.md、docs/cli-reference/下的所有页面以及docs/docs.json中的 CLI 页面数组均由脚本生成，修改命令行为后应重新运行./scripts/generate-cli-docs.sh；
保持文档与发布版本一致：发布时先更新 docs/cli-docs.pin 的 tag，再重新生成文档；
CI 一致性：纯 Go（CGO_ENABLED=0）构建下的bd federation是 stub，重新生成时请使用 CI 一致构建，或用BD_DOCS_ALLOW_CGO=1明确接受 federation 文档变更；
快速校验：提交前运行./scripts/generate-cli-docs.sh --check，若报 "out of sync" 说明文档已过期，需重新生成后再提交。

综上，这份 CLI Reference 既是开发者按需检索bd命令的手册，也是"文档即代码"实践的范本：108 个命令、完整标志位与版本钉扎，全部由一条脚本从真实命令树自动生成并可在 CI 中持续校验，确保文档永远与已发布版本的命令行行为严格一致。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析