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 节定义的四种基本动作movesconvert to a cheaper carrier转换到更便宜的载体、delete dead load删除无效负载、emphasis强调、diagrams图表。simplification.md 不是重复定义这些动作而是规定如何在真实页面上执行这些动作——它是过程processSKILL.md 是动作集moves二者互补。1.1 一个页面能削减多少取决于它承载多少真正的冗余simplification.md 明确区分了三类页面这是决定工作量的第一原则页面类型简化空间处理策略重复陈述兄弟页面内容的页面大用一句话 指向所有者页面的链接替换重复段落长度来自有回报的教学worked examples 其演示的行为几乎不动强行压向某个数字会掏空教学价值已经精简的页面零完全不动其中所有者页面有明确约定模型类内容指向/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 pageMeasure测量用wc -w page记录当前字数Find opportunities找机会按载体分类按链接去重dedup-by-link→ 散文转表格prose→table→ 散文转折叠面板prose→accordion→ 新增/复用图表add/reuse a diagram→ 删除throat-clearing 开场白、hedges 模糊限制语、restatement 重复陈述的顺序逐类排查Apply应用必须用页面自己的语气voice执行改动。不参与简化的段落绝不重排——否则真实改动会被淹没在 diff 里评审者无法判断你改了什么Loss-check损失检查见第 3 节Fact-check事实检查见第 4 节Gates质量门禁见第 5 节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证明每个断言为假拿不准时按未验证处理而不是看起来没问题。需要核查的事实类别与对应校验源均可在仓库中找到断言类别校验源仓库相对路径CLI 命令/子命令/flag生成的 docs/cli-reference/ 页面——由构造保证正确generated by construction配置键与默认值internal/configfile/、cmd/bd/config.go环境变量对应命令源码与 scripts/check-doc-flags.sh 的检查范围文件/目录路径嵌入式模式数据位于.beads/embeddeddolt/服务器模式位于.beads/dolt/issue 类型、依赖类型docs/core-concepts/issues.md 等核心概念页数值型默认值命令源码与配置默认值定义两点特别提醒存储路径是最容易写错的点beads 默认的bd init是嵌入式模式数据在.beads/embeddeddolt/只有bd init --server才使用.beads/dolt/。SKILL.md 明确警告永远不要把.beads/dolt/写成通用数据路径。生成的参考页豁免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 -tagsgms_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-links5.1 docsync导航、孤儿页面与链接约定go test ./test/docsync对应的实现是 test/docsync/docsync_test.go它把 Mintlify 站点docs/与 docs/docs.json 导航钉死在精确对应状态主要检查四点TestMintNavigationPagesExistdocs.json中的每个导航条目必须指向docs/下的真实页面TestEveryDocsPageIsPublisheddocs/下只允许存在已发布的页面——每个 markdown 文件必须出现在导航中CLI_REFERENCE.md与RECOVERY.md是两个豁免项前者是bd help --all生成的单文件参考后者是已发布 bd 二进制会打印的路径TestDocsSiteLinksdocs/内已发布页面遵循 Mintlify 链接约定——内部链接根相对、无扩展名.md后缀会破坏 Mintlify 路由engdocs/与根目录 markdown 则按 GitHub 浏览方式要求精确文件路径TestMintRedirectsResolvedocs.json的redirects数组必须格式正确且指向存在的页面。注意测试还强制要求 redirects 数组不能为空——页面迁移后旧路径的保护机制被视为必不可少。测试包注释明确指出这套守卫以 Gas City 的 docsync 守卫为模板且 docs/ 与 engdocs/ 使用各自树的链接约定。5.2 门禁之外的原则门禁覆盖不到的检查verification.md 强调有些约束门禁无法完全覆盖需要人工保证每个代码围栏必须真实bash围栏中的命令必须是当前bd真实接受的命令可对照生成的 CLI 参考公式的 TOML 围栏必须能解析MDX 有效性禁止 HTML 注释用{/* … */}代替、反引号外不允许裸尖括号占位符、Mintlify 组件必须配对无正文# H1frontmatter 的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 展示了完整流水线bd help --docs-root root只产出与站点生成器无关vendor-neutral的输出docs/CLI_REFERENCE.md 暂存树build/cli-docs/不入库go run ./tools/docsmint root把暂存树后处理为入库的 Mintlify 页面docs/cli-reference/并拼接到docs/docs.json的 CLI Reference 页面数组中docs/cli-docs.pin 钉住发布 tag——已发布文档描述的是被钉住的发布版本而非当前 checkout可用BD_DOCS_IGNORE_PIN1绕过。这意味着想改 CLI 参考页的措辞正确做法是修改 Go 源码中的 help 字符串并重新生成而不是手改docs/cli-reference/下的文件。这也是生成的参考页由构造保证正确说法的来源。6. 页面移动/删除时的配套操作虽然简化通常不涉及移动页面但简化导致页面被合并/删除时verification.md 要求完成全套操作避免破坏入站链接与外部书签Redirect在docs/docs.json的redirects数组加入旧路由 → 新路由的条目test/docsync 的TestMintRedirectsResolve会校验其合法性重写入站链接用grep全仓库搜索README.md、AGENTS.md、AGENT_INSTRUCTIONS.md、engdocs/、examples/、npm-package/、plugins/、integrations/、scripts/ 及 Go 注释而非只搜docs/检查bd打印的输出若bd会打印旧路径需修改 Go 源码并重新生成 CLI 文档——不允许在旧路径创建指针存根decision 6 的规则见 engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md修正锚文本链接标签若指向旧页面名称要一并更新并去重折叠到同一目标的链接。7. 提交与评审纪律让削减可被逐步审批简化流程与验证流程共同规定了提交纪律按受众分组提交用户文档docs/、贡献者文档engdocs/、AGENTS.md、生成器/Go 改动分开提交图片/图表必须在文本 diff 之外被看过SVG 必须先栅格化、人工查看、获得维护者批准才能提交——因为布局问题在文本 diff 中不可见每次一个页面/章节避免削减在章节间叠加放大后难以纠偏文档工作按AGENTS.md的约定作为bdissue 跟踪。8. 与其他参考文档的分工beads 的文档技能由三份参考文件构成simplification.md 是其中之一分工清晰参考文件职责.claude/skills/beads-docs/references/terminology.md散文 vs 字面术语的完整改名纪律如 bead/issue 与 task 的区别、molecule 与mol命令字面量、embedded/server mode 的命名.claude/skills/beads-docs/references/simplification.md本文主题——过程如何在真实页面上执行 SKILL.md §5–§7 的 moves.claude/skills/beads-docs/references/verification.md验证门禁的完整命令集与门禁覆盖不到的检查三者共同服务于 SKILL.md 的终极目标文档在讲术语之前先讲动机motivate before they jargon处处以相同方式说相同的话用图与代码片段而非文字墙呈现概念并且永远不脱离代码never drift from the code。简化流程正是不脱离代码这条底线在裁剪场景下的具体执行保障——损失检查防漏删事实检查防漂移门禁防格式与导航破坏一次一页的提交纪律让整个过程可控可审。9. 实践检查清单把整套流程浓缩成一份可执行的清单供对docs/执行简化时逐项对照wc -w page记录基线字数判断页面类型重复型链接去重/ 教学型基本不动/ 已精简型不动按载体顺序找机会链接去重 → 表格 → 折叠面板 → 图表 → 删除开场白/模糊限制语/重复陈述用页面自身语气执行改动不重排未简化段落Loss-checkdiff 被删行区分有意删除与真正损失真损失以锐化短句恢复Fact-check对抗性验证命令/flag、配置键与默认值、环境变量、路径.beads/embeddeddolt/vs.beads/dolt/、issue/依赖类型、数值默认值生成的 CLI 参考页豁免Gatesgo test ./test/docsync、围栏真实性、MDX 有效性、无正文 H1、make docs-dev预览、./scripts/generate-cli-docs.sh --check与./scripts/check-doc-flags.sh/check-doc-freshness.sh若涉及移动/删除页面redirect 全仓库重写入站链接 检查bd打印路径 修正锚文本预览获批后一次一个页面/章节按受众分组提交。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
