beads-docs

编写 beads 文档

这是 docs/ 的统一风格指南，适用于 beads 用户文档；这些文档以 Mintlify 网站形式发布。目标是：先说明动机，再引入术语；在各处始终用相同方式表达相同内容；通过图片和代码片段展示概念，而不是堆砌大段文字；并始终与代码保持一致。创建、编辑或审阅任何页面时，都要遵循此指南。

docs/ 面向 beads 的用户——安装 bd、跟踪工作并进行同步的人类或 Agent。面向贡献者的内容位于 engdocs/ 和 AGENTS.md，遵循不同的规则（可以按字面描述实现）。本指南中提到“文档”时，指的是 docs/。

1. 规范模型

Beads 是一个具有依赖关系的 issue 图，并在其上提供工作流层。始终以一致的方式介绍它，并链接到规范概念页面——docs/core-concepts/index.md，而不是重复解释。

概念	作用	核心要点
bead（issue）	工作单元	一个经过跟踪的事项，包含哈希 ID（bd-a1b2）、类型、状态和优先级；“bead”和“issue”指的是同一事物
依赖关系	排序	blocks 边会让 Agent 看不到 bead，直到其阻塞项关闭；parent-child、related、discovered-from 用于组织事项，但不会造成阻塞
就绪工作	bd ready 的计算结果	没有未关闭阻塞项的开放 bead，排除 in_progress、blocked、deferred 和 hooked 状态的 bead——可认领工作的前沿
formula	工作流来源	定义步骤 DAG 的 TOML/JSON 文件；bd cook 会将其编译为 proto
proto	工作流模板	带有 template 标签且包含 {{variables}} 的模板 epic；不是实际工作
molecule	已实例化的工作流	从 proto 倒出的实际 bead（bd mol pour）；持久存在
wisp	临时 molecule	相同的实例化形式，但生命周期是临时的（bd mol wisp）；由 bd purge 清除
gate	异步等待	阻塞工作流步骤，直到由人类、计时器、GitHub 运行/PR 或跨 rig bead 将其关闭
同步	跨机器传输	通过 git 远程上的 refs/dolt/data 进行 Dolt 推送/拉取；.beads/issues.jsonl 是被动导出文件，绝不是数据库
联邦	跨仓库同步	在不同仓库/组织之间以点对点方式共享 bead

需要牢记的流程：formula → (cook) → proto → (pour) → molecule 或 → (wisp) → wisp。Gate 会暂停 molecule 步骤；bd ready 会显示可认领的步骤；同步会在机器之间传输整个图。

经常被页面写错的存储事实：嵌入式模式（默认的 bd init）将数据存储在 .beads/embeddeddolt/；服务端模式（bd init --server）使用 .beads/dolt/。切勿将 .beads/dolt/ 描述为通用数据路径。

跨项目术语（beads ↔ Gas City）。 同属一个项目系列的 Gas City 项目也使用 molecule、formula、wisp 和 gate 这些词，但两套文档对它们的用法不同：Gas City 文档将 molecule/wisp 视为 v1 实现细节（绝不作为用户概念），而 Gas City 的 formula 是由编排器跨 Agent 运行的编排方法。在 beads 中，molecule/wisp/proto 是用户概念，而 formula 是用于 cook 并生成 proto 的 TOML 源文件。切勿将 Gas City 的定义套用到 beads 页面（反之亦然）；如果页面需要衔接两个项目，必须明确说明所指的是哪个项目中的含义。

2. 必需术语

使用左栏中的术语；不要使用右栏中的术语（注明的情况除外）。关于叙述文本与字面名称的完整更名规则，请参阅 references/terminology.md。

使用此术语	不使用此术语	备注
bead / issue	将“task”“ticket”“TODO item”用作单元名称	两种说法都正确，可以互换；介绍其概念时优先使用 bead，与 CLI 输出或标志一致时使用 issue（bd create、“issue types”）。“task”是一种 issue 类型，绝不能作为通用单元名称。
ready work	将“unblocked queue”“available tasks”“the ready set”用作正式术语	说明 bd ready 返回的内容：没有未关闭阻塞项的未关闭 bead。
proto	将“template”用作表示该概念的名词	template 仅作为 proto 所带的字面标签名称保留。
molecule	在叙述中使用“mol”	mol 是命令字面名称（bd mol pour）；该概念称为 molecule。
formula	将 formula 与 molecule/proto 混为一谈	formula 是文件；制作会生成 proto；倾倒会生成实际工作项。
gate	“barrier”“checkpoint”“lock”	Gate 是带有类型（human、timer、gh:run、gh:pr、bead）的异步等待条件。
sync = Dolt 推送/拉取	将导出/导入称为同步工作流	通过 refs/dolt/data 执行 bd dolt push / bd dolt pull。.beads/issues.jsonl 是供查看器和数据交换使用的被动导出文件。
embedded mode / server mode	将“local mode”“daemon mode”用于存储模式	Embedded 是默认模式；数据位于 .beads/embeddeddolt/。Server mode 连接到 dolt sql-server；数据位于 .beads/dolt/。
federation	将“multi-repo sync”作为独立功能名称	Federation 是跨仓库点对点共享功能。
hash ID	“random ID”“UUID”	诸如 bd-a1b2 的 ID 是基于内容生成的哈希，并会自适应调整长度以避免冲突。

3. 内容原则

• 先说明动机，再讲机制。 页面开头先说明它要解决的问题， 然后介绍解决方案，最后讲解机制。绝不要以术语介绍开篇。
• 文档不是项目历史。 不要出现 internal/* 包路径，不要写 “this was removed in vX”，也不要在面向用户的页面上设置“(v0.20.1+)”之类的版本门槛——beads 是 1.x 产品，1.0 之前的历史考据应放在 engdocs/ 或 CHANGELOG 中。
• 先讲价值。 Beads 的价值在于为编码 Agent 提供持久、能识别依赖关系的记忆——工作图谱的存续时间长于会话，因此 Agent 即使丢失上下文也能继续工作。与 GitHub Issues、Jira、 Markdown TODO 列表的比较，是吸引新用户的最佳方式；已有此类内容的页面应尽早保留。
• 一个具体示例胜过三句抽象描述。 断言某项功能时，应展示一个 bd 调用及其输出。

4. 信息架构

导航位于 docs/docs.json：Getting Started、Core Concepts、 Architecture、Workflows、Recovery、Multi-Agent、Integrations、Community 和 Reference；生成的 CLI Reference 嵌套在 Reference 下，作为一个折叠子组。

• 每个分区都必须有索引/Overview 页面，用一两句话介绍该分区，然后列出每个子页面，并附上一句话准确摘要和链接。
• 一页只讲一个目的。试图兼顾教学和规范说明的页面两者都做不好——应拆分并互相链接。
• 概念内容统一放在 core-concepts/index；不要在其他页面重新阐述模型，而应链接到该页面。
• 仓库结构图应放在 README 中，而不是 docs/ 中。

5. 文案准则——删减冗词，突出重点

大多数冗长内容都是把信息放在了不合适的载体上。将其移到成本更低的载体上，然后删掉没有实际作用的内容。每个页面都必须独立完整——初次访问的读者需要一行背景说明，而不是依赖前一个页面。

转换（将负担从文案中移走）：

• 关系或流程 → 图表（mermaid 可原生渲染；更丰富的图表使用 Excalidraw 流程——参见 §7）。
• 并列选项、字段或比较 → 表格。
• “你运行 X，它会执行 Y”这类叙述 → 带注释的 CLI 代码片段（展示命令及其输出，并为值得关注的行添加注释）。
• 边缘情况和深层机制 → <Accordion>，或参考页面。页面上保留 80% 的常见情况。

删除（这些负担本来就是多余的）：铺垫式开场白（“在本节中，我们将……”）、层层保留措辞（“通常／一般来说／在大多数情况下”）、重复陈述、复述代码片段已展示的内容，以及用形容词代替证据。

进行有意的简化时，请遵循 references/simplification.md——逐页迭代流程，以及确保删减不失真的两道护栏：遗漏检查（绝不删除只在此处出现的事实）和事实核查（删减后的文案必须与代码保持一致）。

6. 强调与格式

• 粗体仅在术语首次出现时用于标记术语。斜体用于标记属性或对比。每段约标记 1–2 处；不要再次强调已介绍的术语；同一短语不要同时使用两种格式。
• 正文中不要使用 # H1——frontmatter 中的 title 就是 H1。使用 ##/###。
• 链接使用根相对路径且不带扩展名（/getting-started/quickstart）。 指向站点外部的链接（engdocs/、仓库文件）使用完整的 GitHub URL。
• Mintlify 会将 .md 解析为 MDX：不要使用 HTML 注释（改用 {/* … */}），尖括号占位符（如 <id>）必须放在反引号或代码围栏内。
• 谨慎使用 Mintlify 组件（<Note>、<Tip>、<Warning>、<Accordion>）——重复使用会削弱效果。

7. 图表

Mermaid 围栏代码可原生渲染——绘制图表和流程图时优先使用。要制作更丰富的图表，请使用 Excalidraw 流程：在 docs/diagrams/excalidraw/ 下编写 .excalidraw 源文件，使用 make diagrams-excalidraw 渲染（源文件和渲染后的 .svg 均需提交），嵌入 /diagrams/excalidraw-rendered/<name>.svg 并添加描述性替代文本，同时保持标签简短（两行的“名称／角色”胜过塞在框内的一整句话）。以下两点务必遵守：

• 将每个渲染后的图表栅格化并检查——文本溢出和布局问题在文本差异中不可见。
• **无法通过差异审查图表和图片。**渲染后交由维护者批准，再进行提交。

8. 在源文件中编辑生成的内容

切勿手动编辑生成的文件。生成的内容包括：

• docs/cli-reference/*.md 和 docs/docs.json 中的 CLI Reference 页面数组——bd 会将与供应商无关的页面（通过 bd help --docs-root，从 cmd/bd/*.go 中的 Cobra 命令字符串生成）输出到未提交的暂存树中，随后 tools/docsmint 会将其后处理为已提交的 Mintlify 格式。bd 本身绝不会输出 Mintlify（或任何站点生成器）的特定内容；这部分由 docsmint 负责。
• docs/CLI_REFERENCE.md——由 bd help --docs-root 直接输出的单文件参考文档。

要更改其中任何文件的措辞，请编辑 Go 源代码（Short:、Long:、Example: 字符串），然后运行 ./scripts/generate-cli-docs.sh（该脚本会运行两个阶段）。要更改 Mintlify 页面格式本身（注释标记、链接样式、导航），请编辑 tools/docsmint 及其测试。漂移检查机制（generate-cli-docs.sh --check、PR CI 中的 scripts/check-cli-docs-drift.sh，以及 docs-autofix 机器人）会因任何手动编辑而失败或自动修复。

文档描述的是固定版本，而非 main。 docs/cli-docs.pin 指定了整套文档所针对的发布标签；流水线会从该标签构建 bd 并根据该标签进行验证，因此，在 main 上对 Go 源代码的修改只有在更新固定版本（发布时，并随后重新生成文档）后才会反映到已提交的文档中。手写页面遵循同一政策：记录固定版本的功能，绝不记录仅存在于 main 中的功能。请参阅 engdocs/decisions/2026-07-17-docs-release-pin.md。

9. 完成前先验证

运行 references/verification.md 中的检查。简要列表：bazel test //test/docsync:docsync_test --config=ci（导航↔文件同步 + 链接规范）、./scripts/generate-cli-docs.sh --check（确保生成的文档为最新）、./scripts/check-doc-freshness.sh（Last reviewed 标记），以及通过 make docs-dev（或 ./mint.sh dev）在 localhost:3000 上实时预览。

移动或删除页面时：在 docs/docs.json 的 redirects 数组中添加重定向，在整个仓库中改写所有指向该页面的链接（README、engdocs/、examples/、npm-package/、插件资源——使用 grep 搜索，不要猜），并检查 bd 是否会输出旧路径（如果会，请修复 Go 源代码并重新生成——绝不要使用指向旧页面的占位页面；决策 6 涵盖了带重定向的旧路由）。

10. 审查与提交规范

• 作者提交 → 维护者审查 → 获得明确批准后提交。 这一点对于图表和图片尤为重要，因为它们无法通过文本差异进行审查。
• 按受众分组提交：用户文档（docs/）、贡献者文档（engdocs/、AGENTS.md）以及生成器/Go 更改分别提交。
• 根据 AGENTS.md，将文档工作记录为 bd 问题。