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為骨架系統(tǒng)梳理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創(chuàng)建新 issue也可從 markdown 或 graph JSON 批量創(chuàng)建別名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優(yōu)先級、操作狀態(tài)狀態(tài)維度管理bd delete刪除 issue 并清理引用bd link建立 issue 間的依賴關系bd gate/bd merge-slot異步協(xié)調門gate與串行化沖突解決的 merge-slotbd todoTODO 事項便捷封裝add / done / listbd q快速捕獲創(chuàng)建 issue 并只輸出 ID2.2 視圖與報表Views Reports面向數據洞察的命令bd count按過濾器統(tǒng)計 issue 數量bd diff展示兩個提交或分支間的變更bd history查看 issue 的版本歷史bd find-duplicates/bd duplicate/bd duplicates查找并合并語義相似的重復 issuebd lint檢查 issue 是否缺少模板段落bd stale展示長期未更新的過期 issuebd status/bd statuses/bd types庫概覽統(tǒng)計、合法狀態(tài)列表、合法類型列表。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 備份的初始化、同步、恢復與狀態(tài)查看bd branch/bd vc分支管理與版本控制操作commit / merge / statusbd export/bd importJSONL 格式導出與導入bd federation點對點聯(lián)邦需要 CGO 支持純 Go 構建下會顯示 stub 提示bd restore恢復被壓縮compact議題的壓縮前內容。2.5 安裝與配置Setup Configurationbd init在當前目錄初始化.beads/目錄與 Dolt 數據庫詳見本文第五節(jié)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 安裝 / 列舉 / 執(zhí)行 / 卸載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 安裝健康狀態(tài)官方建議從這里開始支持--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在單個數據庫事務中執(zhí)行多個寫操作bd sql/bd ping/bd preflight/bd recompute-blocked/bd rename-prefix/bd rules/bd upgrade/bd worktreeSQL 直查、連通性檢測、PR 就緒清單、blocked 狀態(tài)重算、前綴重命名、規(guī)則審計與壓縮、版本升級管理、worktree 并行開發(fā)。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 # 數據庫路徑默認自動發(fā)現(xiàn) .beads/*.db -C, --directory string # 執(zhí)行前切換目錄類似 git -C --dolt-auto-commit string # Dolt 自動提交策略off|on|batch默認 off可用配置鍵 dolt.auto-commit 覆蓋 --global # 使用全局共享服務器數據庫beads_global --ignore-schema-skew # 容忍前向 schema 漂移繼續(xù)執(zhí)行部分查詢可能失敗 --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 頁面數組——全部發(fā)生在倉庫工具里開源二進制保持零站點生成器依賴。一條命令即可重新生成全部文檔./scripts/generate-cli-docs.sh腳本還提供--check校驗模式它會重新生成到臨時目錄并與已提交文檔做 diff若不同則報錯退出可用于 CI 防止文檔漂移./scripts/generate-cli-docs.sh --checkCI 中對應的漂移檢查腳本為 scripts/check-cli-docs-drift.sh。4.1 版本釘扎pin文檔永遠描述已發(fā)布版本倉庫根目錄的 docs/cli-docs.pin 文件釘住了生成文檔所用的bd版本當前為v1.2.2。其含義是公開文檔站點描述的是最新的已發(fā)布 release而非 main 分支源碼。因此文檔流水線會從該 tag 構建bdCGO_ENABLED0純 Go 構建與 CI 一致而不是使用當前 checkout。發(fā)布時需同步 bump 該 tag 并重新運行生成腳本設BD_DOCS_IGNORE_PIN1可繞過釘扎。4.2 CGO 一致性守衛(wèi)腳本內置了一個針對bd federation的守衛(wèi)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可強制信任給定二進制。五、實操示例結合獨立參考頁理解命令細節(jié)每個命令的獨立參考頁docs/cli-reference/ 目錄下 108 個.md文件以bd help --doc 命令為來源包含語法、別名、全部標志位與示例。以下選取三個典型命令展示參考頁的用法5.1bd create創(chuàng)建 issue 或批量創(chuàng)建參考頁 docs/cli-reference/create.md 展示了一個信息量極大的命令支持從標題參數、markdown 文件、graph JSON 三種方式創(chuàng)建bd create Fix login bug -p 0 -t bug -a alice --due tomorrow bd create -f issues.md # 從 markdown 批量創(chuàng)建 bd create --graph plan.json --dry-run # 從 JSON 計劃創(chuàng)建依賴圖并預覽 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校驗描述包含類型所需章節(jié)、--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 # 只讀檢測配置與現(xiàn)實漂移退出碼 1有漂移 bd config apply --dry-run # 預覽一致性修正 bd config validate # 校驗同步相關配置sovereignty/remote/URL/routing.modeconfig show的優(yōu)先級鏈條為envBD_*/BEADS_*環(huán)境變量 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實現(xiàn)個人隱形使用BD_NON_INTERACTIVE1或--non-interactive跳過交互提示并默認角色為 maintainer密碼通過BEADS_DOLT_PASSWORD環(huán)境變量傳入。docs/cli-reference/doctor.md 展示bd doctor的六大模式常規(guī)健康檢查目錄存在性、schema 兼容、git hooks、.gitignore等、--perf性能診斷、--output診斷 JSON 導出、--check單項檢查、--deep深圖校驗、--serverDolt 服務器健康檢查。六、配套資源如何繼續(xù)深入單文件完整參考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命令實現(xiàn)源碼cmd/bd/如bd create相關實現(xiàn)見 cmd/bd/create.go、配置實現(xiàn)見 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保持文檔與發(fā)布版本一致發(fā)布時先更新 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 既是開發(fā)者按需檢索bd命令的手冊也是文檔即代碼實踐的范本108 個命令、完整標志位與版本釘扎全部由一條腳本從真實命令樹自動生成并可在 CI 中持續(xù)校驗確保文檔永遠與已發(fā)布版本的命令行行為嚴格一致?！久赓M下載鏈接】beadsBeads - A memory upgrade for your coding agent項目地址: https://gitcode.com/GitHub_Trending/beads1/beads創(chuàng)作聲明：本文部分內容由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為骨架系統(tǒng)梳理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創(chuàng)建新 issue也可從 markdown 或 graph JSON 批量創(chuàng)建別名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優(yōu)先級、操作狀態(tài)狀態(tài)維度管理bd delete刪除 issue 并清理引用bd link建立 issue 間的依賴關系bd gate/bd merge-slot異步協(xié)調門gate與串行化沖突解決的 merge-slotbd todoTODO 事項便捷封裝add / done / listbd q快速捕獲創(chuàng)建 issue 并只輸出 ID2.2 視圖與報表Views Reports面向數據洞察的命令bd count按過濾器統(tǒng)計 issue 數量bd diff展示兩個提交或分支間的變更bd history查看 issue 的版本歷史bd find-duplicates/bd duplicate/bd duplicates查找并合并語義相似的重復 issuebd lint檢查 issue 是否缺少模板段落bd stale展示長期未更新的過期 issuebd status/bd statuses/bd types庫概覽統(tǒng)計、合法狀態(tài)列表、合法類型列表。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 備份的初始化、同步、恢復與狀態(tài)查看bd branch/bd vc分支管理與版本控制操作commit / merge / statusbd export/bd importJSONL 格式導出與導入bd federation點對點聯(lián)邦需要 CGO 支持純 Go 構建下會顯示 stub 提示bd restore恢復被壓縮compact議題的壓縮前內容。2.5 安裝與配置Setup Configurationbd init在當前目錄初始化.beads/目錄與 Dolt 數據庫詳見本文第五節(jié)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 安裝 / 列舉 / 執(zhí)行 / 卸載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 安裝健康狀態(tài)官方建議從這里開始支持--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在單個數據庫事務中執(zhí)行多個寫操作bd sql/bd ping/bd preflight/bd recompute-blocked/bd rename-prefix/bd rules/bd upgrade/bd worktreeSQL 直查、連通性檢測、PR 就緒清單、blocked 狀態(tài)重算、前綴重命名、規(guī)則審計與壓縮、版本升級管理、worktree 并行開發(fā)。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 # 數據庫路徑默認自動發(fā)現(xiàn) .beads/*.db -C, --directory string # 執(zhí)行前切換目錄類似 git -C --dolt-auto-commit string # Dolt 自動提交策略off|on|batch默認 off可用配置鍵 dolt.auto-commit 覆蓋 --global # 使用全局共享服務器數據庫beads_global --ignore-schema-skew # 容忍前向 schema 漂移繼續(xù)執(zhí)行部分查詢可能失敗 --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 頁面數組——全部發(fā)生在倉庫工具里開源二進制保持零站點生成器依賴。一條命令即可重新生成全部文檔./scripts/generate-cli-docs.sh腳本還提供--check校驗模式它會重新生成到臨時目錄并與已提交文檔做 diff若不同則報錯退出可用于 CI 防止文檔漂移./scripts/generate-cli-docs.sh --checkCI 中對應的漂移檢查腳本為 scripts/check-cli-docs-drift.sh。4.1 版本釘扎pin文檔永遠描述已發(fā)布版本倉庫根目錄的 docs/cli-docs.pin 文件釘住了生成文檔所用的bd版本當前為v1.2.2。其含義是公開文檔站點描述的是最新的已發(fā)布 release而非 main 分支源碼。因此文檔流水線會從該 tag 構建bdCGO_ENABLED0純 Go 構建與 CI 一致而不是使用當前 checkout。發(fā)布時需同步 bump 該 tag 并重新運行生成腳本設BD_DOCS_IGNORE_PIN1可繞過釘扎。4.2 CGO 一致性守衛(wèi)腳本內置了一個針對bd federation的守衛(wèi)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可強制信任給定二進制。五、實操示例結合獨立參考頁理解命令細節(jié)每個命令的獨立參考頁docs/cli-reference/ 目錄下 108 個.md文件以bd help --doc 命令為來源包含語法、別名、全部標志位與示例。以下選取三個典型命令展示參考頁的用法5.1bd create創(chuàng)建 issue 或批量創(chuàng)建參考頁 docs/cli-reference/create.md 展示了一個信息量極大的命令支持從標題參數、markdown 文件、graph JSON 三種方式創(chuàng)建bd create Fix login bug -p 0 -t bug -a alice --due tomorrow bd create -f issues.md # 從 markdown 批量創(chuàng)建 bd create --graph plan.json --dry-run # 從 JSON 計劃創(chuàng)建依賴圖并預覽 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校驗描述包含類型所需章節(jié)、--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 # 只讀檢測配置與現(xiàn)實漂移退出碼 1有漂移 bd config apply --dry-run # 預覽一致性修正 bd config validate # 校驗同步相關配置sovereignty/remote/URL/routing.modeconfig show的優(yōu)先級鏈條為envBD_*/BEADS_*環(huán)境變量 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實現(xiàn)個人隱形使用BD_NON_INTERACTIVE1或--non-interactive跳過交互提示并默認角色為 maintainer密碼通過BEADS_DOLT_PASSWORD環(huán)境變量傳入。docs/cli-reference/doctor.md 展示bd doctor的六大模式常規(guī)健康檢查目錄存在性、schema 兼容、git hooks、.gitignore等、--perf性能診斷、--output診斷 JSON 導出、--check單項檢查、--deep深圖校驗、--serverDolt 服務器健康檢查。六、配套資源如何繼續(xù)深入單文件完整參考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命令實現(xiàn)源碼cmd/bd/如bd create相關實現(xiàn)見 cmd/bd/create.go、配置實現(xiàn)見 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保持文檔與發(fā)布版本一致發(fā)布時先更新 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 既是開發(fā)者按需檢索bd命令的手冊也是文檔即代碼實踐的范本108 個命令、完整標志位與版本釘扎全部由一條腳本從真實命令樹自動生成并可在 CI 中持續(xù)校驗確保文檔永遠與已發(fā)布版本的命令行行為嚴格一致?！久赓M下載鏈接】beadsBeads - A memory upgrade for your coding agent項目地址: https://gitcode.com/GitHub_Trending/beads1/beads創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考