企业官网建设流程全解析

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 <name>=<value>

这里的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.md
• AGENTS.md、AGENT_INSTRUCTIONS.md
• 所有*.go源文件

统计的目的不是机械替换，而是阅读足够上下文，把散文（prose，即作为概念使用的词）与字面量（literal，即作为程序字符串使用的词）区分开。同一行代码里可能同时存在两者：比如错误提示里既提到用户可见的命令字面量，又在叙述性描述里用到概念词。

2. 只重命名散文，逐处判断

对每一处出现做独立判断，只修改作为概念使用的散文用法，并顺手修正冠词、语法，使其读起来自然。这里强调"逐处判断"而非全局替换，是因为同一个词在不同上下文里的身份可能不同——这正是第 3 步要展开的。

3. 保留字面量：五类必须原样保留的内容

程序真实输出（代码围栏内）

代码围栏中出现的真实程序输出，必须对照 cmd/bd/ 与 internal/ 源码逐一验证；如果二进制会打印它，文档就必须与之逐字一致。任何未经源码确认的输出示例都不应出现在文档里。

命令、标志、字段、配置键与标签

以下内容全部属于字面量范畴：

• 命令与子命令名：bd mol、bd dep、bd cook、bd ready；
• 命令行标志：--mol、--var、--ephemeral、--pour；
• JSON 字段名：如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.md
• docs/docs.json中的 CLI pages 数组

如果术语必须在这类文件里变化，正确做法是修改 cmd/bd/ 下 Cobra 命令定义中的字符串，然后运行 scripts/generate-cli-docs.sh 重新生成。这套流水线在 engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md 的决策 3、4 中有完整记载：bd只负责输出通用 Markdown（generic 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——可以完整走一遍流程：

1. 调查：在docs/、engdocs/、README.md、AGENTS.md及*.go中统计mol与molecule的出现；
2. 识别：bd mol pour、bd ready --mol、bd mol bond是命令/标志字面量；docs/workflows/molecules.md 的章节标题 "What is a Molecule?"、"Creating Molecules" 是散文概念；
3. 保留：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字段同样原样保留；
4. 不碰实现：internal/molecules/的包名、LoadAll、Loader等实现名称不属于文档重命名范围；
5. 防连带：mol的匹配不得破坏 "molecule"；
6. 验证：审计docs/中剩余的mol，确认除命令字面量外无散文遗漏。

总结

terminology.md 所确立的纪律可以浓缩为一句话：文档是程序的镜子，重命名只能改镜子里概念的说法，不能改镜子对程序字符串的反射。具体执行时遵循"调查 → 只改散文 → 保留五类字面量 → 不动代码/engdocs → 防连带词 → 事后审计"六步流程，遇到生成文件走cmd/bd/*.go+scripts/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