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

beads 文档工程化指南从概念模型到验证门禁的写作规范深度解析【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 是面向编码 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由以下概念构成概念角色关键点beadissue工作单元一条被跟踪的工作项带哈希 ID如bd-a1b2、类型、状态、优先级bead 与 issue 指同一事物dependency排序blocks边让工作项在阻塞者关闭前对 Agent 隐藏parent-child、related、discovered-from只做组织不做阻塞ready workbd ready计算的结果无开放阻塞者的 open 工作项排除 in_progress、blocked、deferred、被 gate 挂起者——即可认领的前沿formula工作流源文件一个定义步骤 DAG 的 TOML/JSON 文件bd cook将其编译为 protoproto工作流模板带{{variables}}的模板 epiclabel 为template不是真实工作molecule实例化工作流从 proto 浇筑出的真实 beadsbd mol pour持久存在wisp临时 molecule同样的实例化过程但生命周期是临时的bd mol wisp由bd purge清理gate异步等待阻塞工作流步骤直到被关闭——由人、定时器、GitHub run/PR 或跨 rig 的 bead 关闭sync跨机器移动在 git remote 的refs/dolt/data上做 Dolt push/pull.beads/issues.jsonl只是被动导出绝不是数据库federation跨仓库同步跨仓库/组织的点对点共享值得内化的管线是formula → (cook) → proto → (pour) → molecule或→ (wisp) → wispgate 会暂停 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 中有完整的概念改名规程。核心映射如下用这个不用这个备注bead/issuetask、ticket、TODO item 作为单元名两词都正确可互换教身份时以bead领起镜像 CLI 输出或 flag 时用issuetask 只是一种 issue 类型ready workunblocked queue、available tasks 作为正式术语直接说bd ready返回什么无开放阻塞者的 open 工作项prototemplate 作概念名词template只保留为 proto 携带的字面 labelmolecule行文中用 molmol只是命令字面量bd mol pourformula与 molecule/proto 混为一谈formula 是文件cook 产出 protopour 产出真实工作gatebarrier、checkpoint、lockgate 是带类型human、timer、gh:run、gh:pr、bead的异步等待条件sync Dolt push/pull把 export/import 说成同步工作流bd dolt push/bd dolt pull走refs/dolt/data.beads/issues.jsonl是给查看器和交换用的被动导出embedded mode/server modelocal mode、daemon mode嵌入式是默认数据在.beads/embeddeddolt/服务端连接dolt sql-server数据在.beads/dolt/federation把 multi-repo sync 当作独立功能名federation 才是点对点跨仓库共享功能hash IDrandom ID、UUIDbd-a1b2这类 ID 是内容派生哈希长度自适应防碰撞改名的纪律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 URLMintlify 把.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会对任何手改失败或自动修复。文档描述的是固定发布版本不是 maindocs/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 数组做 diffbd 发射通用页面到 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考