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 命令的索引Beadsbd是一个为编码 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 批量创建别名newbd assign分配负责人等价于bd update id --assignee namebd list/bd show/bd search/bd query查看与检索 issuebd close/bd reopen关闭与重新打开 issuebd 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-slotbd todoTODO 事项便捷封装add / done / listbd q快速捕获创建 issue 并只输出 ID2.2 视图与报表Views Reports面向数据洞察的命令bd count按过滤器统计 issue 数量bd diff展示两个提交或分支间的变更bd history查看 issue 的版本历史bd find-duplicates/bd duplicate/bd duplicates查找并合并语义相似的重复 issuebd lint检查 issue 是否缺少模板段落bd stale展示长期未更新的过期 issuebd status/bd statuses/bd types库概览统计、合法状态列表、合法类型列表。2.3 依赖与结构Dependencies Structurebd dep系列提供依赖管理add / remove / list / tree / cycles / relate / unrelatebd graph展示依赖图并校验图完整性bd epic/bd swarm处理史诗与 swarm 分子结构bd supersede标记议题被新议题取代bd orphans识别提交中已引用但仍打开的孤儿议题。2.4 同步与数据Sync Databd backupDolt 备份的初始化、同步、恢复与状态查看bd branch/bd vc分支管理与版本控制操作commit / merge / statusbd export/bd importJSONL 格式导出与导入bd federation点对点联邦需要 CGO 支持纯 Go 构建下会显示 stub 提示bd restore恢复被压缩compact议题的压缩前内容。2.5 安装与配置Setup Configurationbd init在当前目录初始化.beads/目录与 Dolt 数据库详见本文第五节bd bootstrap为全新 clone 与恢复场景做非破坏性数据库设置bd config系列配置管理set / get / list / unset / set-many / show / apply / drift / validatebd dolt系列Dolt 引擎配置start / stop / push / pull / remote / commit / status / show / test 等bd context/bd where/bd info查看仓库身份、beads 位置与数据库信息bd hooksgit hooks 安装 / 列举 / 执行 / 卸载bd setup与 AI 编辑器Claude、Cursor、Aider 等集成bd memories/bd remember/bd recall/bd forget持久记忆的列出、存储、检索与删除——这正是 Beads 给编码 Agent 装上记忆定位的核心能力bd human系列人类介入事项list / respond / dismiss / statsbd onboard/bd prime/bd quickstart为 Agent 输出工作流上下文。2.6 维护Maintenancebd doctor检查并修复 beads 安装健康状态官方建议从这里开始支持--perf性能诊断、--output导出诊断 JSON、--check单项检查artifacts / conventions / pollution / validate与--deep深图校验bd compact/bd flatten/bd gc压缩 Dolt 提交历史、压平全部历史、垃圾回收老 issue 衰减 提交压缩 Dolt GCbd prune/bd purge删除关闭的旧 issue / 关闭的临时ephemeralissue 以回收空间bd migrate迁移hooks / issues / schema / syncbd batch在单个数据库事务中执行多个写操作bd sql/bd ping/bd preflight/bd recompute-blocked/bd rename-prefix/bd rules/bd upgrade/bd worktreeSQL 直查、连通性检测、PR 就绪清单、blocked 状态重算、前缀重命名、规则审计与压缩、版本升级管理、worktree 并行开发。2.7 集成与高级Integrations Advanced五大外部平台集成每个都有近乎对称的 pull / push / sync / status 子命令族bd jira含 teams 列举、bd linear、bd github含 repos 列举、bd gitlab含 projects 列举、bd adoAzure DevOps含 projects 列举、bd notion含 connect / initbd repo多仓库同步配置add / list / remove / syncbd admin数据库维护cleanup / compact / resetbd audit记录并标记 Agent 交互append-only JSONLbd formula/bd cook/bd mol公式管理、编译公式为 proto、分子molecule工作流bond / pour / distill / squash / wisp 等bd metrics匿名用量指标开关与示例查看。2.8 其他Other Commandsbd completionbash / 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 生成采用中性输出 站点后处理的两阶段架构阶段 1bd help --docs-root root产生厂商中立的 Markdown。bd本身不感知任何站点生成器格式只把通用命令树输出到docs/CLI_REFERENCE.md以及暂存目录build/cli-docs/。阶段 2go 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 --checkCI 中对应的漂移检查脚本为 scripts/check-cli-docs-drift.sh。4.1 版本钉扎pin文档永远描述已发布版本仓库根目录的 docs/cli-docs.pin 文件钉住了生成文档所用的bd版本当前为v1.2.2。其含义是公开文档站点描述的是最新的已发布 release而非 main 分支源码。因此文档流水线会从该 tag 构建bdCGO_ENABLED0纯 Go 构建与 CI 一致而不是使用当前 checkout。发布时需同步 bump 该 tag 并重新运行生成脚本设BD_DOCS_IGNORE_PIN1可绕过钉扎。4.2 CGO 一致性守卫脚本内置了一个针对bd federation的守卫CGO 构建会暴露完整的 federation 命令树而 CI 的纯 Go 构建CGO_ENABLED0 -tags gms_pure_go只会输出 stub 提示 Federation commands require CGO见 cmd/bd/federation_nocgo.go。若检测到提供的二进制是 CGO 版脚本会警告并自动重建钉扎版本的纯 Go 二进制避免产生大量虚假的 federation 文档变更设BD_DOCS_ALLOW_CGO1可强制信任给定二进制。五、实操示例结合独立参考页理解命令细节每个命令的独立参考页docs/cli-reference/ 目录下 108 个.md文件以bd help --doc 命令为来源包含语法、别名、全部标志位与示例。以下选取三个典型命令展示参考页的用法5.1bd 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/--priority0-4 或 P0-P4默认2、-t/--typebug|feature|task|epic|chore|decision默认taskenhancement/feat→feature、dec/adr→decision为别名、--due支持6h、1d、2w、tomorrow、next monday、2025-01-15等格式、--defer推迟到指定日期前对bd ready隐藏、--deps格式type:id或id、--mol-typeswarm / patrol / work、--wisp-typeheartbeat、ping、patrol、gc_report 等 TTL 压缩类型、--ephemeral短生命周期、受 TTL 压缩、--metadataJSON 字符串或file.json、--validate校验描述包含类型所需章节、--silent脚本只输出 ID等。5.2bd 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.urlhttps://example.atlassian.net jira.projectPROJ # 原子批量设置 bd config show --source config.yaml # 查看带来源注解的生效配置 bd config drift --json # 只读检测配置与现实漂移退出码 1有漂移 bd config apply --dry-run # 预览一致性修正 bd config validate # 校验同步相关配置sovereignty/remote/URL/routing.modeconfig show的优先级链条为envBD_*/BEADS_*环境变量 config.yaml.beads/config.yaml default内置默认值另有 metadata、database、git 三类补充来源。5.3bd init与bd doctor入口与健康检查docs/cli-reference/init.md 说明bd init默认使用内嵌 Dolt 引擎无需外部服务--server可切换外部dolt sql-server--stealth通过.git/info/exclude实现个人隐形使用BD_NON_INTERACTIVE1或--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.md6884 行含全部子命令、示例、标志位独立命令页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 一致性纯 GoCGO_ENABLED0构建下的bd federation是 stub重新生成时请使用 CI 一致构建或用BD_DOCS_ALLOW_CGO1明确接受 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），仅供参考 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 命令的索引Beadsbd是一个为编码 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 批量创建别名newbd assign分配负责人等价于bd update id --assignee namebd list/bd show/bd search/bd query查看与检索 issuebd close/bd reopen关闭与重新打开 issuebd 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-slotbd todoTODO 事项便捷封装add / done / listbd q快速捕获创建 issue 并只输出 ID2.2 视图与报表Views Reports面向数据洞察的命令bd count按过滤器统计 issue 数量bd diff展示两个提交或分支间的变更bd history查看 issue 的版本历史bd find-duplicates/bd duplicate/bd duplicates查找并合并语义相似的重复 issuebd lint检查 issue 是否缺少模板段落bd stale展示长期未更新的过期 issuebd status/bd statuses/bd types库概览统计、合法状态列表、合法类型列表。2.3 依赖与结构Dependencies Structurebd dep系列提供依赖管理add / remove / list / tree / cycles / relate / unrelatebd graph展示依赖图并校验图完整性bd epic/bd swarm处理史诗与 swarm 分子结构bd supersede标记议题被新议题取代bd orphans识别提交中已引用但仍打开的孤儿议题。2.4 同步与数据Sync Databd backupDolt 备份的初始化、同步、恢复与状态查看bd branch/bd vc分支管理与版本控制操作commit / merge / statusbd export/bd importJSONL 格式导出与导入bd federation点对点联邦需要 CGO 支持纯 Go 构建下会显示 stub 提示bd restore恢复被压缩compact议题的压缩前内容。2.5 安装与配置Setup Configurationbd init在当前目录初始化.beads/目录与 Dolt 数据库详见本文第五节bd bootstrap为全新 clone 与恢复场景做非破坏性数据库设置bd config系列配置管理set / get / list / unset / set-many / show / apply / drift / validatebd dolt系列Dolt 引擎配置start / stop / push / pull / remote / commit / status / show / test 等bd context/bd where/bd info查看仓库身份、beads 位置与数据库信息bd hooksgit hooks 安装 / 列举 / 执行 / 卸载bd setup与 AI 编辑器Claude、Cursor、Aider 等集成bd memories/bd remember/bd recall/bd forget持久记忆的列出、存储、检索与删除——这正是 Beads 给编码 Agent 装上记忆定位的核心能力bd human系列人类介入事项list / respond / dismiss / statsbd onboard/bd prime/bd quickstart为 Agent 输出工作流上下文。2.6 维护Maintenancebd doctor检查并修复 beads 安装健康状态官方建议从这里开始支持--perf性能诊断、--output导出诊断 JSON、--check单项检查artifacts / conventions / pollution / validate与--deep深图校验bd compact/bd flatten/bd gc压缩 Dolt 提交历史、压平全部历史、垃圾回收老 issue 衰减 提交压缩 Dolt GCbd prune/bd purge删除关闭的旧 issue / 关闭的临时ephemeralissue 以回收空间bd migrate迁移hooks / issues / schema / syncbd batch在单个数据库事务中执行多个写操作bd sql/bd ping/bd preflight/bd recompute-blocked/bd rename-prefix/bd rules/bd upgrade/bd worktreeSQL 直查、连通性检测、PR 就绪清单、blocked 状态重算、前缀重命名、规则审计与压缩、版本升级管理、worktree 并行开发。2.7 集成与高级Integrations Advanced五大外部平台集成每个都有近乎对称的 pull / push / sync / status 子命令族bd jira含 teams 列举、bd linear、bd github含 repos 列举、bd gitlab含 projects 列举、bd adoAzure DevOps含 projects 列举、bd notion含 connect / initbd repo多仓库同步配置add / list / remove / syncbd admin数据库维护cleanup / compact / resetbd audit记录并标记 Agent 交互append-only JSONLbd formula/bd cook/bd mol公式管理、编译公式为 proto、分子molecule工作流bond / pour / distill / squash / wisp 等bd metrics匿名用量指标开关与示例查看。2.8 其他Other Commandsbd completionbash / 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 生成采用中性输出 站点后处理的两阶段架构阶段 1bd help --docs-root root产生厂商中立的 Markdown。bd本身不感知任何站点生成器格式只把通用命令树输出到docs/CLI_REFERENCE.md以及暂存目录build/cli-docs/。阶段 2go 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 --checkCI 中对应的漂移检查脚本为 scripts/check-cli-docs-drift.sh。4.1 版本钉扎pin文档永远描述已发布版本仓库根目录的 docs/cli-docs.pin 文件钉住了生成文档所用的bd版本当前为v1.2.2。其含义是公开文档站点描述的是最新的已发布 release而非 main 分支源码。因此文档流水线会从该 tag 构建bdCGO_ENABLED0纯 Go 构建与 CI 一致而不是使用当前 checkout。发布时需同步 bump 该 tag 并重新运行生成脚本设BD_DOCS_IGNORE_PIN1可绕过钉扎。4.2 CGO 一致性守卫脚本内置了一个针对bd federation的守卫CGO 构建会暴露完整的 federation 命令树而 CI 的纯 Go 构建CGO_ENABLED0 -tags gms_pure_go只会输出 stub 提示 Federation commands require CGO见 cmd/bd/federation_nocgo.go。若检测到提供的二进制是 CGO 版脚本会警告并自动重建钉扎版本的纯 Go 二进制避免产生大量虚假的 federation 文档变更设BD_DOCS_ALLOW_CGO1可强制信任给定二进制。五、实操示例结合独立参考页理解命令细节每个命令的独立参考页docs/cli-reference/ 目录下 108 个.md文件以bd help --doc 命令为来源包含语法、别名、全部标志位与示例。以下选取三个典型命令展示参考页的用法5.1bd 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/--priority0-4 或 P0-P4默认2、-t/--typebug|feature|task|epic|chore|decision默认taskenhancement/feat→feature、dec/adr→decision为别名、--due支持6h、1d、2w、tomorrow、next monday、2025-01-15等格式、--defer推迟到指定日期前对bd ready隐藏、--deps格式type:id或id、--mol-typeswarm / patrol / work、--wisp-typeheartbeat、ping、patrol、gc_report 等 TTL 压缩类型、--ephemeral短生命周期、受 TTL 压缩、--metadataJSON 字符串或file.json、--validate校验描述包含类型所需章节、--silent脚本只输出 ID等。5.2bd 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.urlhttps://example.atlassian.net jira.projectPROJ # 原子批量设置 bd config show --source config.yaml # 查看带来源注解的生效配置 bd config drift --json # 只读检测配置与现实漂移退出码 1有漂移 bd config apply --dry-run # 预览一致性修正 bd config validate # 校验同步相关配置sovereignty/remote/URL/routing.modeconfig show的优先级链条为envBD_*/BEADS_*环境变量 config.yaml.beads/config.yaml default内置默认值另有 metadata、database、git 三类补充来源。5.3bd init与bd doctor入口与健康检查docs/cli-reference/init.md 说明bd init默认使用内嵌 Dolt 引擎无需外部服务--server可切换外部dolt sql-server--stealth通过.git/info/exclude实现个人隐形使用BD_NON_INTERACTIVE1或--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.md6884 行含全部子命令、示例、标志位独立命令页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 一致性纯 GoCGO_ENABLED0构建下的bd federation是 stub重新生成时请使用 CI 一致构建或用BD_DOCS_ALLOW_CGO1明确接受 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），仅供参考