Beads 文档术语重命名纪律在散文与字面量之间保持文档与程序一致【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读本文解读 Beads 仓库中.claude/skills/beads-docs/references/terminology.md这份文档维护规范当项目中某个概念的名词发生变化时例如 mol 与 molecule、template 与 proto、issue 与 bead应如何安全地重命名文档而不让文档撒谎。读完本文你将掌握 Beads 文档体系docs/、engdocs/、CLI 参考中重命名散文、保留字面量的完整纪律理解哪些内容可以改、哪些内容必须与二进制输出保持一致以及如何借助生成流水线与重定向机制完成一次不破坏仓库链接的术语迁移。核心规则代码与输出才是真相来源terminology.md 开门见山地给出整个纪律的总纲当项目对某个东西的称呼发生变化时规则是在散文中重命名概念保留每一个反映真实程序行为的字面量literal。代码及其输出是真相来源——如果文档把二进制仍然打印出来的字符串改了名文档就变成了谎言。这句话把文档维护的优先级彻底说清程序的行为是第一事实文档是对该事实的描述。描述可以随概念演进而更新但凡是程序真实输出、真实命令、真实配置键的字面内容文档必须逐字对齐不得擅改。这一原则在 Beads 源码里有大量直接印证。例如 cmd/bd/cook.go 在烹饪公式成功后程序会真实打印To use: bd mol pour proto-id --var namevalue这里的bd mol pour、--var就是二进制仍然打印的字符串。如果某次文档重命名想把它改成bd molecule pour那么文档将与实际 CLI 输出脱节用户照文档操作将得到 command not found。docs/workflows/molecules.md 中的命令示例正是这种对齐的产物散文段落通篇使用 molecule 概念而所有可执行命令一律写作bd mol pour、bd ready --mol、bd mol bond等字面形式。六步纪律一次安全术语迁移的完整流程1. 调查先行先分清散文与字面量动手之前先在下列范围内统计目标词的全部出现次数docs/engdocs/README.mdAGENTS.md、AGENT_INSTRUCTIONS.md所有*.go源文件统计的目的不是机械替换而是阅读足够上下文把散文prose即作为概念使用的词与字面量literal即作为程序字符串使用的词区分开。同一行代码里可能同时存在两者比如错误提示里既提到用户可见的命令字面量又在叙述性描述里用到概念词。2. 只重命名散文逐处判断对每一处出现做独立判断只修改作为概念使用的散文用法并顺手修正冠词、语法使其读起来自然。这里强调逐处判断而非全局替换是因为同一个词在不同上下文里的身份可能不同——这正是第 3 步要展开的。3. 保留字面量五类必须原样保留的内容程序真实输出代码围栏内代码围栏中出现的真实程序输出必须对照 cmd/bd/ 与 internal/ 源码逐一验证如果二进制会打印它文档就必须与之逐字一致。任何未经源码确认的输出示例都不应出现在文档里。命令、标志、字段、配置键与标签以下内容全部属于字面量范畴命令与子命令名bd mol、bd dep、bd cook、bd ready命令行标志--mol、--var、--ephemeral、--pourJSON 字段名如molecules.jsonl中的is_template、needs配置键.beads/config.yaml中的键名标签名例如 proto 携带的template标签issue 类型名、文件路径以及任何被反引号包裹的标识符。例如 internal/molecules/molecules.go 的包注释明确写有is_template: true、bd list、bd molecule list等字样这些在文档中都必须保持原样。同词异义同一个词的不同身份一个词可能同时以概念和字面量两种身份存在task 既是一种 issue 类型字面量又是散文里泛指的工作任务概念Dolt 自己的 branch 与 git 分支的 branch 是两个不同事物的同名表述。重命名时必须识别这些歧义只动目标身份绝不误伤另一身份。生成文件绝不手工编辑以下文件是生成产物任何情况下都不要手工改动docs/cli-reference/*docs/CLI_REFERENCE.mddocs/docs.json中的 CLI pages 数组如果术语必须在这类文件里变化正确做法是修改 cmd/bd/ 下 Cobra 命令定义中的字符串然后运行 scripts/generate-cli-docs.sh 重新生成。这套流水线在 engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md 的决策 3、4 中有完整记载bd只负责输出通用 Markdowngeneric MD frontmatter仓库内的 tools/docsmint/ 工具负责将其后处理为 Mintlify 页面并拼接docs.json的 CLI 导航决策记录同时说明旧的 Docusaurus 站点目录website/已随此次文档迁移退役其website/docs/cli-reference/不再需要维护。已定案字面量注释截至 Mintlify 文档移植时点仓库已经沉淀了一批定案的字面量约定见下节详解。4. 不碰代码与 engdocs 实现名称除非被明确要求否则一次文档重命名不得顺手改动代码或engdocs/中的实现名称。若确实需要重命名二进制输出的字符串那是另一份独立的 Go PR并需重新生成 CLI 文档应在文档重命名中将其标记为 follow-up保证输出与文档最终对齐。5. 留意连带词词边界陷阱使用词边界匹配时极易误伤拼写相近的词对gate做词边界匹配时绝不能碰到 delegate、aggregate对mol做重命名时绝不能把 molecule 弄坏。这类陷阱要求重命名工具或人工流程对每个命中做二次确认避免连带破坏。6. 事后验证逐条审计剩余出现迁移完成后对docs/中生成文件之外剩下的每一处目标词出现进行显式审计并分类literal (correct)是合法的字面量保留missed prose (fix)是遗漏的散文用法需要修复。只有把所有剩余出现都归入这两类之一迁移才算完成。这一步骤把重命名从一次性替换变成可审计、可复核的过程。已定案的字面量约定五个容易踩坑的词mol只作命令字面量mol只作为命令字面量存在如bd mol pour、bd ready --mol在散文里概念一律写作molecule。这解释了为什么 docs/workflows/molecules.md 的标题与正文讲的是 Molecules而所有命令示例都是bd mol ...。另见 cmd/bd/doctor/maintenance.go其中医生命令的提示语同样区分了bd mol pour与bd mol wisp两个字面命令。template是 proto 携带的标签不是概念名template是 proto 携带的标签字面量作为概念正确称呼是proto即烹饪过的公式。docs/workflows/molecules.md 中的术语表正是这一约定的体现Proto 被定义为带有template标签的 Epic。源码侧 internal/molecules/molecules.go 的注释也用is_template: true描述模板标记属于 JSON 字段字面量。issue与bead两个都被认可不要机械互改CLI 的输出与标志使用的是 issue如bd create、bd close、bd dep add的操作对象、.beads/issues.jsonl因此镜像 CLI 的散文保留 issue 是正当的。不要机械地把一个词修正成另一个——它们是同一事物的两个已获批准的说法选择哪个取决于上下文是否贴近 CLI。.beads/issues.jsonl永远是被动导出涉及.beads/issues.jsonl时只能把它描述为被动导出passive export——即数据库内容的只读视图/交换格式。严禁称其为数据库同步协议或备份。这一点在 docs/architecture/index.md 的架构图中得到呼应issues.jsonl 被明确标注为 Passive JSONL export for viewers and interchange而真正的事务数据位于 Dolt 后端见 docs/architecture/dolt.md备份目录是完整的 Dolt 备份not anissues.jsonlexport。bd 打印的路径靠 redirects 覆盖不在旧路径重建指针桩bd可能在输出中打印文档路径如docs/RECOVERY.md、docs/SETUP.md等。规则是绝不在旧路径重新创建指针桩文件被移动的页面由 docs/docs.json 中的redirects数组统一覆盖。这是 engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md 决策 6 的明确决定——旧的指针桩RECOVERY、PLUGIN、DOLT、QUICKSTART、SETUP 等十一个路径被删除旧路由由 Mintlify 转发。如果bd打印的是旧路径正确修法是修复 Go 源码使其打印新路径然后重新生成文档同决策记录决策 7 给出了prime.go、init_git_hooks.go、dolt.go等一批 Go 字符串修复的实例。例如当前仓库中 docs/RECOVERY.md 仍存在但新站点中恢复类内容已迁至recovery/系列页面如recovery/init-safety旧路由/RECOVERY与/SETUP均通过redirects指到新位置。实战应用把纪律套用到 molecule 术语体系把上述纪律套用到 Beads 当前最活跃的术语体系——molecule——可以完整走一遍流程调查在docs/、engdocs/、README.md、AGENTS.md及*.go中统计mol与molecule的出现识别bd mol pour、bd ready --mol、bd mol bond是命令/标志字面量docs/workflows/molecules.md 的章节标题 What is a Molecule?、Creating Molecules 是散文概念保留bd mol current、bd mol stale、bd mol wisp list、bd mol show --parallel、bd mol squash、bd mol burn、bd mol distill等命令在 docs/workflows/molecules.md 中全部保持字面形式internal/molecules/molecules.go中molecules.jsonl文件名、is_template字段同样原样保留不碰实现internal/molecules/的包名、LoadAll、Loader等实现名称不属于文档重命名范围防连带mol的匹配不得破坏 molecule验证审计docs/中剩余的mol确认除命令字面量外无散文遗漏。总结terminology.md 所确立的纪律可以浓缩为一句话文档是程序的镜子重命名只能改镜子里概念的说法不能改镜子对程序字符串的反射。具体执行时遵循调查 → 只改散文 → 保留五类字面量 → 不动代码/engdocs → 防连带词 → 事后审计六步流程遇到生成文件走cmd/bd/*.goscripts/generate-cli-docs.sh的再生成路线遇到页面移动依赖docs/docs.json的redirects而非重建指针桩。这套规则保证了 Beads 庞大的文档体系109 个 CLI 参考页、核心概念、工作流、恢复指南在与快速演进的 CLI 保持同步时始终不产生文档撒谎的偏差。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考