企业官网建设流程全解析

beads 文档简化流程全解：在削减冗余的同时不丢失任何事实

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

导读

本文以 beads 仓库文档维护体系中的「简化（simplification）」方法论为核心，完整讲解如何在裁剪文档冗余文字的同时，通过损失检查（loss-check）、事实检查（fact-check）与自动化门禁，确保每个事实、命令、配置项都不被静默删除、不被改写失真。读完本文，你将掌握一套可落地的逐页精简工作流，并理解 beads 仓库中docs/站点（Mintlify）与engdocs/工程文档两套语境的差异化校验规则。

1. 简化是什么：目标不是字数，是更便宜的载体

beads 的文档维护技能（.claude/skills/beads-docs/SKILL.md）定义了文档写作的"house style"，而简化流程（.claude/skills/beads-docs/references/simplification.md）是其中负责"做减法"的过程文档。它开篇就划出一条重要边界：

字数是输出，不是目标（Word count is the output, not the target）。

简化的核心不是把文章变短，而是：

• 去除冗余与不必要的字词，让观点更尖锐（sharper），而不是更单薄（thinner）；
• 把信息迁移到更便宜的载体（cheaper carrier）——表格、折叠面板（accordion）、图表，或指向已拥有该内容的页面的链接；
• 删除的只是"重复陈述"（restatement），而不是信息本身。

从源码结构看，这套理念直接对应 SKILL.md 第 5 节定义的四种基本动作（moves）：convert to a cheaper carrier（转换到更便宜的载体）、delete dead load（删除无效负载）、emphasis（强调）、diagrams（图表）。simplification.md 不是重复定义这些动作，而是规定如何在真实页面上执行这些动作——它是"过程"（process），SKILL.md 是"动作集"（moves），二者互补。

1.1 一个页面能削减多少，取决于它承载多少真正的冗余

simplification.md 明确区分了三类页面，这是决定工作量的第一原则：

其中"所有者"页面有明确约定：模型类内容指向/core-concepts/index（即 docs/core-concepts/index.md），命令细节指向/cli-reference/<cmd>（即 docs/cli-reference/ 下对应页面）。

此外，折叠面板和表格只是为了可扫读而折叠内容，并不删除字词——这类工作不能用字数差来衡量，这是衡量简化成果时常犯的错误。

2. 逐页循环（The per-page loop）：六步标准流程

simplification.md 给出了严格的逐页操作循环，这是整套方法论的骨架：

# Step 1. Measure：先量化现状 wc -w <page>

1. Measure（测量）：用wc -w <page>记录当前字数；
2. Find opportunities（找机会，按载体分类）：按"链接去重（dedup-by-link）→ 散文转表格（prose→table）→ 散文转折叠面板（prose→accordion）→ 新增/复用图表（add/reuse a diagram）→ 删除（throat-clearing 开场白、hedges 模糊限制语、restatement 重复陈述）"的顺序逐类排查；
3. Apply（应用）：必须用页面自己的语气（voice）执行改动。不参与简化的段落绝不重排——否则真实改动会被淹没在 diff 里，评审者无法判断你改了什么；
4. Loss-check（损失检查）：见第 3 节；
5. Fact-check（事实检查）：见第 4 节；
6. Gates（质量门禁）：见第 5 节；
7. Preview, then commit on approval（预览并获批后提交）：一次只提交一个页面或一个章节，让评审者能在"削减在章节间叠加放大"之前及时介入纠偏。

2.1 为什么"不重排未简化段落"是硬约束

第 3 步的约束在实践中最容易被忽视。它的深层原因是 diff 审计性：如果顺手重排了与本次简化无关的句子，评审者就不得不从大段无意义的 diff 中寻找真实变化，简化动作本身的可审性（reviewability）就被破坏了。这与第 6 步"一次一个页面/章节"的提交纪律是一体两面——削减必须是可追踪、可回退、可逐步审批的。

3. 损失检查：简化绝对不能丢失事实

简化是最容易让真实细节悄悄消失的环节，因此 simplification.md 要求每次简化后对页面做一次损失检查（loss-check）：

将页面与其精简前的版本做 diff，逐行检查被删除的内容：每个被删除的块，是否是重要的事实、命令、flag、配置键、caveat、行为或 worked example——并且它在任何其他地方都没有被保留（用grep在docs/全站检查是否已迁移到别处）？

随后要把删除诚实地区分为两类：

• 有意删除（Intentional cuts，保持删除）：
  • 术语迁移（terminology migration，参见 .claude/skills/beads-docs/references/terminology.md 的 rename 纪律）；
  • 模糊限制语/重复陈述的删除；
  • 已迁移到更好载体的内容（并带 redirect）；
  • 有意退役的过时声明（如 pre-1.0 的门禁描述、已移除的命令）。
• 真正的损失（Genuine losses，必须恢复）：一个真实细节被删除，且没有在别处找到归宿。

恢复的真正损失要以**锐化后的短句（sharpened clause）**而非恢复大段原文的方式处理——把缺失的why折叠回你保留下来的某个句子里，而不是把删掉的整段再加回来。这与整个简化哲学一致：信息密度优先于段落完整性。

4. 事实检查：用源码对抗性验证被改写的散文

写作和修剪都会引入漂移（drift）：过时的版本号、改名后在散文里存活的 flag、被重写后夸大实现的句子。simplification.md 要求对**所有可核查的断言（checkable claim）**做对抗性验证：

对抗性验证（Verify adversarially）：试图用某个file:line证明每个断言为假，拿不准时按"未验证"处理，而不是"看起来没问题"。

需要核查的事实类别与对应校验源（均可在仓库中找到）：

两点特别提醒：

1. 存储路径是最容易写错的点：beads 默认的bd init是嵌入式模式，数据在.beads/embeddeddolt/；只有bd init --server才使用.beads/dolt/。SKILL.md 明确警告：永远不要把.beads/dolt/写成通用数据路径。
2. 生成的参考页豁免：docs/cli-reference/与 docs/CLI_REFERENCE.md 是通过重新生成保证正确的，对它们"用自身源码做事实检查"属于循环论证（circular），不在验证范围内。simplification.md 还指出，实践上一次完整的验证流程通常能抓出若干个真实错误。

5. 质量门禁（Gates）：简化工作完成前的硬性关卡

第 6 步的门禁清单在 .claude/skills/beads-docs/references/verification.md 中有完整命令，简化流程引用了其中核心几条，并按"最便宜优先"排序：

# 1. 文档同步：docs.json 导航 <-> 文件一一对应，链接约定检查 go test -tags=gms_pure_go ./test/docsync # （Makefile 中 make check-docs 会合并运行 1 + 3） # 2. 生成型 CLI 文档的新鲜度：从当前命令树重新生成并 diff ./scripts/generate-cli-docs.sh --check # CI 的 blame 限定变体（只对 PR 引入的漂移失败）： ./scripts/check-cli-docs-drift.sh # 3. 文档 flag + 新鲜度标记 ./scripts/check-doc-flags.sh ./bd ./scripts/check-doc-freshness.sh # 4. 实时预览 make docs-dev # 等价于 ./mint.sh dev -> http://localhost:3000 # 5. 失效链接（按 CI 方式检查） ./mint.sh broken-links

5.1 docsync：导航、孤儿页面与链接约定

go test ./test/docsync对应的实现是 test/docsync/docsync_test.go，它把 Mintlify 站点（docs/与 docs/docs.json 导航）钉死在"精确对应"状态，主要检查四点：

• TestMintNavigationPagesExist：docs.json中的每个导航条目必须指向docs/下的真实页面；
• TestEveryDocsPageIsPublished：docs/下只允许存在已发布的页面——每个 markdown 文件必须出现在导航中（CLI_REFERENCE.md与RECOVERY.md是两个豁免项，前者是bd help --all生成的单文件参考，后者是已发布 bd 二进制会打印的路径）；
• TestDocsSiteLinks：docs/内已发布页面遵循 Mintlify 链接约定——内部链接根相对、无扩展名（.md后缀会破坏 Mintlify 路由），engdocs/与根目录 markdown 则按 GitHub 浏览方式要求精确文件路径；
• TestMintRedirectsResolve：docs.json的redirects数组必须格式正确且指向存在的页面。注意测试还强制要求 redirects 数组不能为空——页面迁移后旧路径的保护机制被视为必不可少。

测试包注释明确指出这套守卫"以 Gas City 的 docsync 守卫为模板"，且 docs/ 与 engdocs/ 使用各自树的链接约定。

5.2 门禁之外的原则：门禁覆盖不到的检查

verification.md 强调有些约束门禁无法完全覆盖，需要人工保证：

• 每个代码围栏必须真实：bash围栏中的命令必须是当前bd真实接受的命令（可对照生成的 CLI 参考）；公式的 TOML 围栏必须能解析；
• MDX 有效性：禁止 HTML 注释（用{/* … */}代替）、反引号外不允许裸尖括号占位符、Mintlify 组件必须配对；
• 无正文# H1：frontmatter 的title才是 H1（注意代码围栏内的#注释是误报源）；
• 新鲜度标记：带Last reviewed:/Freshness source:行的页面（configuration、ide-setup、azure-devops、json-schema、init-safety 等）在编辑时必须保持完整且更新。scripts/check-doc-freshness.sh 会强制标记的格式、年龄（Last reviewed默认 90 天内，可用DOC_FRESHNESS_MAX_AGE_DAYS覆盖）以及Freshness source中列出的源码路径真实存在，且页面必须在 engdocs/DOC_INVENTORY.md 中有清单条目。

5.3 生成型 CLI 文档的"编辑源头"纪律

CLI 参考页属于"生成的文档"，其编辑源头在代码而非页面本身。scripts/generate-cli-docs.sh 展示了完整流水线：

1. bd help --docs-root <root>只产出与站点生成器无关（vendor-neutral）的输出：docs/CLI_REFERENCE.md+ 暂存树build/cli-docs/（不入库）；
2. go run ./tools/docsmint <root>把暂存树后处理为入库的 Mintlify 页面docs/cli-reference/，并拼接到docs/docs.json的 CLI Reference 页面数组中；
3. docs/cli-docs.pin 钉住发布 tag——已发布文档描述的是被钉住的发布版本，而非当前 checkout，可用BD_DOCS_IGNORE_PIN=1绕过。

这意味着：想改 CLI 参考页的措辞，正确做法是修改 Go 源码中的 help 字符串并重新生成，而不是手改docs/cli-reference/下的文件。这也是"生成的参考页由构造保证正确"说法的来源。

6. 页面移动/删除时的配套操作

虽然简化通常不涉及移动页面，但简化导致页面被合并/删除时，verification.md 要求完成全套操作，避免破坏入站链接与外部书签：

1. Redirect：在docs/docs.json的redirects数组加入旧路由 → 新路由的条目（test/docsync 的TestMintRedirectsResolve会校验其合法性）；
2. 重写入站链接：用grep全仓库搜索（README.md、AGENTS.md、AGENT_INSTRUCTIONS.md、engdocs/、examples/、npm-package/、plugins/、integrations/、scripts/ 及 Go 注释），而非只搜docs/；
3. 检查bd打印的输出：若bd会打印旧路径，需修改 Go 源码并重新生成 CLI 文档——不允许在旧路径创建指针存根（decision 6 的规则，见 engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md）；
4. 修正锚文本：链接标签若指向旧页面名称要一并更新，并去重折叠到同一目标的链接。

7. 提交与评审纪律：让削减可被逐步审批

简化流程与验证流程共同规定了提交纪律：

• 按受众分组提交：用户文档（docs/）、贡献者文档（engdocs/、AGENTS.md）、生成器/Go 改动分开提交；
• 图片/图表必须在文本 diff 之外被"看过"：SVG 必须先栅格化、人工查看、获得维护者批准才能提交——因为布局问题在文本 diff 中不可见；
• 每次一个页面/章节：避免削减在章节间叠加放大后难以纠偏；
• 文档工作按AGENTS.md的约定作为bdissue 跟踪。

8. 与其他参考文档的分工

beads 的文档技能由三份参考文件构成，simplification.md 是其中之一，分工清晰：

三者共同服务于 SKILL.md 的终极目标：文档在讲术语之前先讲动机（motivate before they jargon），处处以相同方式说相同的话，用图与代码片段而非文字墙呈现概念，并且永远不脱离代码（never drift from the code）。简化流程正是"不脱离代码"这条底线在裁剪场景下的具体执行保障——损失检查防漏删，事实检查防漂移，门禁防格式与导航破坏，一次一页的提交纪律让整个过程可控可审。

9. 实践检查清单

把整套流程浓缩成一份可执行的清单，供对docs/执行简化时逐项对照：

1. wc -w <page>记录基线字数；
2. 判断页面类型：重复型（链接去重）/ 教学型（基本不动）/ 已精简型（不动）；
3. 按载体顺序找机会：链接去重 → 表格 → 折叠面板 → 图表 → 删除（开场白/模糊限制语/重复陈述）；
4. 用页面自身语气执行改动，不重排未简化段落；
5. Loss-check：diff 被删行，区分有意删除与真正损失；真损失以锐化短句恢复；
6. Fact-check：对抗性验证命令/flag、配置键与默认值、环境变量、路径（.beads/embeddeddolt/vs.beads/dolt/）、issue/依赖类型、数值默认值；生成的 CLI 参考页豁免；
7. Gates：go test ./test/docsync、围栏真实性、MDX 有效性、无正文 H1、make docs-dev预览、./scripts/generate-cli-docs.sh --check与./scripts/check-doc-flags.sh/check-doc-freshness.sh；
8. 若涉及移动/删除页面：redirect + 全仓库重写入站链接 + 检查bd打印路径 + 修正锚文本；
9. 预览获批后，一次一个页面/章节按受众分组提交。

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