企业官网建设流程全解析

beads 文档工程化指南：从概念模型到验证门禁的写作规范深度解析

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

Beads 是面向编码 Agent 的持久化、依赖感知工作图（issue graph），其用户文档站（docs/）以 Mintlify 站点形式发布。本篇指南以仓库中.claude/skills/beads-docs/SKILL.md为核心骨架，系统拆解 beads 官方文档的"写作宪章"：统一的概念模型、强制术语表、散文与排版纪律、图表管线、生成文档回源编辑机制，以及提交前必须运行的验证门禁。读完你将掌握 beads 文档的完整写作/评审工作流，并能用同一套标准审阅或贡献任何一篇 docs/ 下的页面。

一、这份 Skill 是什么：docs/ 的"房规"与读者定位

.claude/skills/beads-docs/SKILL.md是 beads 仓库为"写作、编辑、重构或评审用户文档"定义的 house style（房规）。它的适用面非常广：任何触碰docs/的工作——概念页、参考文档、集成指南、恢复手册、图表、docs.json导航，甚至"只修一处文案"的请求——都必须遵循它。它同时明确了读者对象：

• docs/ 的读者是 beads 的"用户"：人类或 Agent，安装bd、跟踪工作、同步数据的人；
• 面向贡献者的材料（engdocs/、AGENTS.md）走另一套规则，可以字面化描述实现细节；
• 因此文档的核心目标是：先讲动机再讲术语、全站用同一套说法、用图与代码片段代替大段散文、绝不与代码脱节。

仓库中该 Skill 的配套材料位于 .claude/skills/beads-docs/references/，包括terminology.md（概念改名纪律）、simplification.md（精简段落流程）、verification.md（验证门禁清单），本文后续会逐一展开。

二、规范的核心：一份必须内化的概念模型

SKILL.md 反复强调：教学要一致，并链接到唯一的概念权威页 docs/core-concepts/index.md，而不是每页重新推导一遍模型。这个"canonical model"由以下概念构成：

值得内化的管线是：formula → (cook) → proto → (pour) → molecule，或→ (wisp) → wisp；gate 会暂停 molecule 的步骤；bd ready浮出可认领的步骤；sync 把整张图搬到别的机器。

存储事实（页面反复写错的点）：嵌入式模式（默认的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 实现细节（绝非用户概念），其 formula 是编排方法；而 beads 里 molecule/wisp/proto就是用户概念，formula 是被 cook 成 proto 的 TOML 源文件。写页面时严禁把 Gas City 的定义搬进 beads 页面（反之亦然）。

三、强制术语表：说同一件事，用同一个词

SKILL.md §2 给出"用左列，永不右列（除非特别注明）"的对照表。这套术语纪律在 .claude/skills/beads-docs/references/terminology.md 中有完整的"概念改名"规程。核心映射如下：

改名的纪律（references/terminology.md）：概念在散文中改名，但每个反映程序真实字面量的字符串必须保留——代码和它的输出是事实来源，如果文档改了二进制仍会打印的字符串，文档就撒谎了。具体规程为：先普查docs/、engdocs/、README.md、*.go中该词的出现；只改散文；保留程序输出、命令与子命令名（bd mol、bd dep）、flag、JSON 字段名、配置键（.beads/config.yaml）、label 名（proto 的templatelabel）、issue 类型、文件路径、任何反引号标识符；生成文件（docs/cli-reference/*、docs/CLI_REFERENCE.md、docs.json中的 CLI pages 数组）绝不手改——要改就改cmd/bd/*.go里的 Cobra 字符串并跑生成脚本；还要留意连带词（改gate不能误伤 "delegate"/"aggregate"，改mol不能破坏 "molecule"）。

四、内容立场：先讲价值，再讲机制

SKILL.md §3 定义了内容立场（content stance）：

• 先动机后机制：一页以它解决的问题开头，然后给方案，再讲机制，绝不以词汇表开篇；
• 文档不是项目历史：用户页面不出现internal/*包路径、不写"这在 vX 被移除了"、不做 "(v0.20.1+)" 版本门槛——beads 是 1.x 产品，pre-1.0 考古属于engdocs/或 CHANGELOG；
• 以价值领起：beads 的价值是"编码 Agent 的持久化、依赖感知记忆"——工作图比会话活得久，Agent 不因上下文丢失而失忆。与 GitHub Issues、Jira、markdown TODO 清单的对比框架是最好的新用户转化工具，要放在页面靠前的位置；
• 一个具体例子胜过三句抽象论述：断言能力时，展示bd调用及它的输出。

这条在 docs/getting-started/quickstart.md 中体现得淋漓尽致——首页先讲"扁平追踪器让 Agent 一上来就卡死"的问题，随即给出bd ready的对比输出，再进入安装与实操。

五、信息架构：docs.json 驱动的导航

导航定义在 docs/docs.json 中，分为九大组：Getting Started、Core Concepts、Architecture、Workflows、Recovery、Multi-Agent、Integrations、Community、Reference——其中生成的 CLI Reference 作为 Reference 内折叠的子组嵌套。要点：

• 每个 section 都有 index/Overview 页：一两句话介绍该 section，然后列出每个子页并附一行准确摘要与链接；
• 一页一职：一页既要教学又要当规范，两头都做不好——拆开并互相链接；
• 概念材料统一收敛在core-concepts/index：其他页面不要重新推导模型，链接过去即可；
• 仓库地图属于 README，不属于 docs/。

docs.json还维护了庞大的redirects数组（如/QUICKSTART→/getting-started/quickstart、/MOLECULES→/workflows/molecules），用于页面移动/重命名后的旧路由兼容。这也印证了 verification.md 的规则：移动或删除页面时，必须在redirects数组补一条从旧路由到新路由的跳转。

六、散文教义：把信息搬去更便宜的载体

SKILL.md §5 是"cut words, sharpen points"的实操层，核心思想是：多数臃肿是信息放错了介质，把它搬到更便宜的载体上，然后删掉不承担负载的部分。每页必须stand alone——冷着陆的读者需要一行式背景，而不是前一页。

Convert（把负载从散文搬走）：

• 关系或序列 →图（mermaid 原生渲染；更丰富的图走 Excalidraw 管线，见 §七）；
• 并行的选项/字段/对比 →表；
• "你运行 X，它做了 Y"的叙述 →带注释的 CLI 片段（展示命令和输出，注释关键行）；
• 边界情况与深层机制 →<Accordion>或参考页；把 80% 的常见情况留在页面上。

Delete（删除虚假负载）：清喉式开场（"在本节我们将……"）、修饰链（"generally / typically / in most cases"）、复述、对代码片段已经展示的东西再叙述一遍、以及代替证据的形容词。

精简流程（references/simplification.md）：当执行一次刻意的精简时，遵循每页循环（测量字数 → 按载体找机会 → 用页面自己的语气应用 → 损失检查 → 事实检查 → 跑门禁 → 预览后按批准提交，一次一页），并守住两条护栏：

• 损失检查（loss-check）：逐块对比删除的行——被删的如果是重要事实、命令、flag、配置键、注意点、行为或完整示例，且全站grep后无处安放，必须恢复为"更锐利的从句"而非原段落；
• 事实检查（fact-check）：对抗性地核验每个可检查的主张——CLI 命令/子命令/flag（最廉价的核对方式就是生成好的docs/cli-reference/页面）、配置键与默认值（internal/configfile/、cmd/bd/config.go）、环境变量、文件与目录路径、issue 类型与依赖类型、数值默认值。默认"未验证"而非"没问题"。

七、强调与格式：最小干预原则

SKILL.md §6 的排版纪律：

• 粗体在首次提及处命名术语；斜体标记属性或对比；每段约 1–2 处标记，绝不重复强调已引入的术语，绝不一个短语同时用两种处理；
• 正文没有# H1——frontmatter 的title就是 H1，正文用##/###；
• 链接是根相对且无扩展名（/getting-started/quickstart）；站外链接（engdocs/、仓库文件）用完整 GitHub URL；
• Mintlify 把.md解析为 MDX：不能有 HTML 注释（用{/* … */}），尖括号占位符（如<id>）必须放进反引号或代码围栏内；
• Mintlify 组件（<Note>、<Tip>、<Warning>、<Accordion>）要克制使用——滥用会失去力量。

八、图表管线：mermaid 优先，Excalidraw 走严格流程

§7 规定：mermaid 围栏原生渲染，图和流程优先用它；更丰富的图走 Excalidraw 管线——在docs/diagrams/excalidraw/下创作.excalidraw源文件，用make diagrams-excalidraw渲染（源文件与渲染出的.svg都提交），以/diagrams/excalidraw-rendered/<name>.svg形式嵌入并配描述性 alt 文本，标签保持简短。两条硬性规定：

• 必须栅格化并检查每张渲染图——文字溢出和布局问题在文本 diff 里是看不见的；
• 图和图片无法在 diff 中评审——渲染出来并先获得维护者批准再提交。

仓库 docs/core-concepts/index.md 里大量使用 mermaid 展示产品全貌循环（create → graph → ready → claim → close）、ready 判定、formula→proto→molecule 管线与 Dolt sync 拓扑，正是这条规定的落地范例。SKILL.md 强调这些图不是装饰：它们是"关系/序列搬去更便宜载体"这一散文教义的第一选择。

九、生成内容编辑在源头：CLI 参考文档的双阶段管线

§8 是全篇最具工程特色的一节：绝不手改生成文件。生成面包括：

• docs/cli-reference/*.md与docs/docs.json里的 CLI Reference 页面数组——bd从cmd/bd/*.go的 Cobra 命令字符串，通过bd help --docs-root把厂商中立的页面发射到未提交的 staging 树，再由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 bot）会对任何手改失败或自动修复。

文档描述的是固定发布版本，不是 main：docs/cli-docs.pin指名整份文档语料所对准的 release tag；管线从该 tag 构建 bd 并据此校验。Go 源在 main 上的改动，要等到 pin 被提升（发布时）并重新生成后才会出现在已提交的文档中。手写页面遵循同样的政策：写固定发布版的行为，绝不写 main 独有的功能。依据见engdocs/decisions/2026-07-17-docs-release-pin.md。

十、完成前必跑的验证门禁

§9 与 .claude/skills/beads-docs/references/verification.md 共同定义了"文档工作完成"的验收标准，按成本从低到高排列：

# 1. 文档同步：docs.json 导航 <-> 文件一致性、链接约定 # （docs/ 内根相对无扩展名；engdocs/ 与精选根文件用精确路径）、 # 孤儿检测（只有 CLI_REFERENCE.md 豁免）。 go test ./test/docsync # 2. 生成 CLI 文档的新鲜度：从实时命令树重新生成并与 # docs/CLI_REFERENCE.md、docs/cli-reference/、docs.json 中的 # CLI pages 数组做 diff（bd 发射通用页面到 staging， # tools/docsmint 产出提交用的 Mintlify 形式）。 ./scripts/generate-cli-docs.sh --check # CI 的 blame 范围变体（只对 PR 自身引入的漂移失败）： ./scripts/check-cli-docs-drift.sh # 3. 文档 flag 与新鲜度标记：过期的 flag/命令引用，以及参考文档上的 # `Last reviewed:` / `Freshness source:` 标记。 # （make check-docs 会一起跑 1 和 3。） ./scripts/check-doc-flags.sh ./bd ./scripts/check-doc-freshness.sh # 4. 编辑时实时预览。 make docs-dev # 或：./mint.sh dev -> http://localhost:3000 # 5. 按 CI 的方式检查坏链接（PR 上经 .github/workflows/docs-mintlify.yml # 做 baseline-aware 检查）： ./mint.sh broken-links

门禁没有完全覆盖但同样重要的原则：

• 每个代码围栏必须是真实的：bash围栏应展示当前bd接受的命令（核对生成的 CLI 参考）；formula 的 TOML 围栏必须能解析；
• MDX 合法性：无 HTML 注释（用{/* … */}）、反引号外无裸尖括号占位符、Mintlify 组件闭合平衡；
• 无正文# H1——frontmatter 的title才是 H1（注意代码围栏里的#注释不是 H1，要防误报）；
• 新鲜度标记：带Last reviewed:/Freshness source:的页面（configuration、ide-setup、azure-devops、json-schema、init-safety 等）编辑时必须保持完整且更新，scripts/check-doc-freshness.sh强制格式、时效与所命名的源路径存在。

移动或删除页面时要完成四步：在docs/docs.json的redirects数组补跳转；全仓库改写入站链接（README、engdocs/、examples/、npm-package/、plugins/、integrations/、scripts、Go 注释——用 grep 而非猜）；检查bd是否打印旧路径（是则改 Go 源并重新生成，绝不建指针桩）；修正锚文本并去重已坍缩到同一目标的链接。

十一、评审与提交纪律

§10 规定了协作流程：作者 → 维护者评审 → 在明确批准后提交。这对图和图片尤为重要——它们无法在文本 diff 中评审。提交按受众分组：用户文档（docs/）与贡献者文档（engdocs/、AGENTS.md）分开，与生成器/Go 改动分开。文档工作按AGENTS.md以 bd issue 跟踪。

结语：一套"永不与代码脱节"的文档系统

纵观全文，.claude/skills/beads-docs/SKILL.md真正回答的问题不是"怎么写好看的文档"，而是"在代码即事实来源的项目里，如何让文档长期不撒谎"。它用四个机制达成这一点：概念模型统一（全站共享core-concepts/index的唯一权威定义）、术语纪律（散文改名但字面量永远跟随二进制输出）、生成内容回源（CLI 参考文档只能改 Go 源后重新生成，配合cli-docs.pin对准固定发布版）、以及自动化的漂移门禁（go test ./test/docsync、generate-cli-docs.sh --check、freshness 检查）。对贡献者而言，这套 Skill 既是写作模板也是评审清单；对读者而言，它解释了为什么 beads 的文档能保持"先动机、后机制、图与片段代替散文、永不漂移"的品质。如果你想上手实践，可以从 docs/getting-started/quickstart.md 读起，再对照 docs/core-concepts/index.md 体会概念模型如何被复用，最后跑一遍 §10 的门禁清单感受"验证优先"的文档文化。

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