机器翻译
本页面由 AI 自动翻译，可能存在术语或语义偏差。如有疑问，请以英文原文为准。
将你的知识迁移到 beads
大多数项目积累知识的速度，快于它们重新找到这些知识的速度。决策落在 ADR 目录里，调查落在研究笔记里，设计理由落在规格说明和 wiki 页面里，而一堆参考笔记则落在当时顺手的键值或记忆存储里。每个存储都有强劲的写入路径，却没有读取路径——在你需要的那一刻，没有任何东西把正确的笔记提取出来，于是知识在技术上被保存了，实际上却丢失了。
本页是把这些知识迁移到插件所依托的 beads 原生知识库的操作手册：每个参考条目对应一个延迟 bead，在决策时按标签检索，随你的 beads 数据库同步，而不是在单台机器上腐烂。它面向在自己仓库上运行本插件的开发者。指导是通用的；本仓库自身的迁移作为实战示例一并呈现。
先说清一条边界，因为它决定了你到底该动哪些东西：这是一次针对参考知识的迁移——决策、研究和设计理由，是你在相关选择出现时会重新翻开的内容。它不针对每次会话都会主动浮现的注入型工作记忆（lesson、pattern、root-cause、correction）。那些内容原地不动。阶段 0 会精确划出这条界线。
整个工作分为六个阶段。每个阶段都以你可以在继续之前核对的退出标准结束。
---
config:
flowchart:
nodeSpacing: 60
rankSpacing: 55
---
graph LR
P0["0 · Principles"] --> P1["1 · Per-repo setup"]
P1 --> P2["2 · Inventory"]
P2 --> P3["3 · Migrate"]
P3 --> P4["4 · Wire & verify"]
P4 --> P5["5 · Lifecycle"]
style P0 fill:#6366f1,color:#fff
style P3 fill:#22c55e,color:#000
style P5 fill:#f59e0b,color:#000阶段 0：原则
四个理念决定了这个知识库是否值得搭建。搞错它们，你之后就得重建；本仓库曾在最后关头躲过一个这样的错误，另一个则不得不返工，本阶段末尾的证据框正是原因。
知识存在于描述中
知识放在 bead 的描述里——一段自足的提炼，半 KB 到两 KB 半：结论或决策、支撑它的证据，以及后果。metadata.doc 里的文件路径是可选的深入指针，而非主体内容。原因在于同步：bead 描述随你的 Dolt 历史同步到每一台机器，而它们指向的文档语料通常被 gitignore 或只存在于单机上。描述只是一行指针的 bead，在真正重要的那条边界上什么也带不过去。
大小不是约束。256 KB 的描述能逐字节往返，远超你会写的任何内容。真正的限制是检索经济性——当 bead 浮现时读者能有效吸收多少——这才把目标定在 0.5–2.5 KB，而非某个存储上限。
延迟知识库模型
每个参考条目是一个 bead，保持一种为静默持久、绝不打扰而选择的形态：
status=deferred，配一个遥远未来的defer_until（本仓库用2099-01-01）。延迟 bead 对垃圾回收安全：bd gc、bd prune和bd admin compact针对的都是已关闭的 bead，而非延迟的。- 从
bd ready中隐藏，因此知识库从不干扰你的活动工作。 - 类型为
decision、research或design。 - 打上类别标记
kb，再加一到三个主题标签。
标签是唯一的查询轴
你按主题标签或关键词检索，此外没有其他可靠方式：
Bead 元数据仅供显示——按 metadata 字段过滤返回零结果——所以主题标签就是索引。这就是为什么你在阶段 1 里编写的词表分量如此之重，也是为什么标签在阶段 3 里要接受最重的人工审查。
注入记忆的边界
参考知识是一个层级；注入型工作记忆是另一个。经验、模式、根因和纠正（lesson、pattern、root-cause、correction）留在 bd memories 里，由 session-start 钩子主动浮现。不要把它们迁移进延迟知识库——迁移会让它们退出注入，而注入正是那个层级的全部意义。知识库存放你有意去查的笔记，而非你希望被主动递到手上的规则。
在本仓库——已关闭状态的险情
第一版设计把每个知识 bead 存为 closed。已关闭的 bead 正是 bd gc（衰减默认 90 天）、bd prune 和 bd admin compact 会删除的对象，于是整个知识库会在约三个月内悄然清空。一次构建前的压力测试在临时数据库上抓住了它；deferred 配一个遥远未来的日期，才是能存活下来的状态。
在本仓库——单薄的一行式
第一遍为研究文档建索引时，为每个文档创建了一个 bead，其描述只有一行——平均 125 个字符，是目录而非知识。第二遍把它们重写为完整提炼，平均约 1,500 个字符。上面的形态规则之所以存在，正是因为那个单薄版本看起来完成了，却什么也检索不到。
退出标准。 当以下各项都成立时，本阶段完成：
- [ ] 你能用一句话说清，为什么知识存在于描述中而非文件指针里。
- [ ] 你已选定一个遥远未来的
defer_until，并确认延迟 bead 在你的 beads 版本中能挺过bd gc。 - [ ] 你有一份写下来的清单，列明哪些内容不迁移——从你的注入记忆开始。
阶段 1：逐仓库配置
插件提供机制；你补上只有你仓库才知道的东西。把这两者分开，就是配置的全部。
插件提供什么，你自己编写什么
| 插件提供 | 你逐仓库编写 |
|---|---|
| 捕获指令——技能在创作知识时归档一个 bead | 原生 decision 之外的任何自定义类型 |
| 检索触发器——brainstorming 与调试中的知识检查 | 从你自己语料聚类而来的受控标签词表 |
| session-start 指向知识库的指针 | 两个守卫，适配到你的路径与测试面 |
声明你的自定义类型
decision 是原生的。加上知识库所用的两个参考类型：
编写你的标签词表
标签就是你的索引，所以要从你自己的材料构建词表——对你的实际语料聚类，命名反复出现的簇，在 15–25 个标签处打住。两条规则让它保持为可用的查询轴：不设单例标签（只有一个成员的标签，你永远不会拿来查询），也绝不盲目照抄别的项目的词表，因为它编码的是别的项目的主题。把清单放进一个守卫能读取的纯文本文件里：
适配两个守卫
两个守卫让知识库保持诚实，而两者在指向你的路径之前都毫无意义：
- 标签不变量守卫：每个知识 bead 都带
kb，再加一到三个主题标签，且每个标签只从词表文件中取。 - 文档↔bead 对账守卫：每个应有 bead 的源文档都确有一个。按语料分别限定范围，这样你 ADR 目录里漏掉的一次捕获，会独立于你的研究笔记而失败。
把两者都接入运行你检查的任何流程，让漂移的标签或漏掉的捕获在构建时就中断，而不是变成日后的一次查找。
在本仓库
词表最终定为 20 个主题标签，从既有语料聚类而来。两个守卫都在本仓库的 just guards 面里运行；对账守卫把 ADR 目录和研究文档作为两个独立限定范围的循环来覆盖，因此某个语料里的漏项无法躲在另一个语料的覆盖背后。
退出标准。 当以下各项都成立时，本阶段完成：
- [ ]
bd config set types.custom已运行，且bd config show列出了你的类型。 - [ ] 存在一份含 15–25 个标签、无单例、从你语料聚类而来的词表文件。
- [ ] 两个守卫都在你的测试面里运行，并在空库起始状态下通过。
阶段 2：盘点
在迁移任何东西之前，按每个来源映射到何处来归类它们——同样重要的是，哪些根本不该进知识库。
| 来源 | 映射到 |
|---|---|
| ADR 目录（架构决策） | decision |
| 设计文档、规格说明、RFC | design |
| 研究笔记、调查、发现 | research |
| 存放决策或设计理由的 wiki 页面或 README | decision / design |
| 过大的记忆库，仅参考类笔记 | 按笔记类型 |
| 参考笔记的键值存储 | 按笔记类型 |
排除任何不是你会在决策点重新翻开的参考知识：
| 排除 | 原因 |
|---|---|
| 实现计划、任务简报与报告 | 执行产物——它们描述的是工作，而非知识 |
| 临时 TODO | 属于任务追踪器，而非知识库 |
注入记忆（lesson / pattern / root-cause / correction） |
不同的记忆层级——它们留在 bd memories |
退出标准。 当以下各项都成立时，本阶段完成：
- [ ] 每个来源语料都被指定了类型，或被明确排除并各自附上原因。
- [ ] 排除清单点名了你的注入记忆和你的执行产物。
阶段 3：迁移
迁移是一条流水线：提炼每个条目、提议它的标签、让人来审标签、做敏感性甄别、创建 bead，然后在退休任何东西之前先验证。顺序很重要——审查关卡在写入之前，而非之后。
提炼
把每个来源变成一段 0.5–2.5 KB、能独立成立的描述：结论或决策、证据、后果，不带指向 bead 未携带上下文的"见上文"式引用。在每段描述成为 bead 之前，对它做一次密钥与 PII 扫描。描述随你的 Dolt 历史同步，而这历史比一次事后删除活得更久，所以规则是标记并丢弃，而非搬走了事。
先提议标签，再审查它们
让 LLM 提议主题标签；绝不自动套用。标签是查询轴，所以错误标签不只是给一个 bead 贴错——它会污染此后每次查询的返回。给标签做完整人工审查，逐行审。描述可以轻一些：做分层抽样点检（最长的、最短的、看起来最敏感的、每种类型各一个），叠加在一条无论如何每行都要过的机械底线之上——落在大小区间内、密钥扫描干净、自足。一段薄弱的提炼可以逐个 bead 挽回；标签腐烂则不能。
敏感性甄别
在同一次审查中，标记出任何其内容不应到达共享 Dolt 远端的东西——内部策略、未发布的计划、竞争定位。迁移会同步描述，这是源文件从未有过的新暴露。把被标记的条目搁置：让它们不进知识库，记录到一个对账守卫会尊重的 gitignored 排除清单里，只有当你拥有一个专属的 beads 远端来存放它们之后再迁移。
创建或充实 bead
从提炼后的描述创建全新 bead，通过标准输入管道传入，使其永不触及你的 shell 历史，并带上让重跑幂等的溯源元数据：
printf '%s' "<distilled 0.5-2.5KB summary>" | bd create "<one-line title>" -t <type> -l kb,<topics> --defer 2099-01-01 --metadata "$(jq -nc --arg d "<doc-path>" '{doc:$d}')" --body-file - --silent
如果早前一遍已留下一个单薄的索引行 bead，就原地充实它，而不是再造一个重复的：
metadata.doc（键值来源则用 metadata.kv_key）既是深入指针，也是幂等键：第二遍会找到已存在的 bead 而什么也不创建。
先验证，再退休
迁移分两个阶段，而这两个阶段不重叠。先验证：计数与你的盘点相符、抽样主题查询浮现出你确知在里面的条目、守卫为绿。之后才退休来源——而且只退休知识库替换掉的那些。一个键值存储或一组重复笔记会变成墓碑（bd 会保留每个条目迁往何处的溯源），绝非硬删除。仍作为你 bead 所指向的深入正文的语料——ADR 目录、研究文档——予以保留，不退休。
在本仓库——129 个 kv + 36 篇文档 + 55 个 ADR
三个语料迁入 216 个知识 bead：63 个 decision、75 个 design、78 个 research。键值存储退休为带每键溯源的墓碑；ADR 文件和研究文档原地保留，作为其 bead 所指向的深入正文。有八个条目——六篇研究文档和两个 ADR——在审查期间被搁置，因为其内容不应到达共享远端，由一份 gitignored 排除清单保持守卫为绿，直到有了专属的 beads 远端为止；该远端落地后，这八个条目在后续一轮中全部迁移完成。每一遍运行都幂等：第二遍创建零个 bead。密钥扫描在一个形似令牌的文件名落地前将其标出，未写入任何敏感内容。
在本仓库——检索精度从 14% 到 100%
回报是你可以信赖的检索。迁移之前，在键值存储里 grep position 返回七个命中，其中一个相关；知识库自己有案可查的标签查询返回零，因为 129 个条目里只有 26 个曾被打过标签，而这些标签没有共同词表。把同一个问题作为主题标签查询，返回三个结果，三个都相关——从 14% 精度到 100%。
退出标准。 当以下各项都成立时，本阶段完成：
- [ ] 每个迁移条目都过了机械底线和一次密钥/PII 扫描。
- [ ] 标签经过完整人工审查；被标记为敏感的条目已搁置，未写入。
- [ ] 在退休任何来源之前，计数与抽样查询均已验证；只有被替换的来源被立了墓碑。
阶段 4：接线与验证
迁移后的知识库在两件事自动发生之前都是惰性的：知识在被创作时被捕获，知识在决策被做出时被检索。把两者接上线，然后证明它们会触发。
在创作时捕获
把捕获命令放进那些本就在创作知识的步骤里，让归档 bead 成为工作的一部分，而非另一件杂事。在本插件中，这意味着研究写作归档它的 research bead、ADR 写作归档它的 decision bead、记忆整理器把参考类记忆路由进知识库——每一个都通过 --body-file - 管道传入提炼后的描述。
在决策时检索
把知识检查放在决策实际被做出的地方：brainstorming 的第一阶段和调试的第一阶段，都会在提议任何东西之前查询知识库，而 session-start 钩子带一个指向它的指针。这个指针是刻意的——正文从不注入，因此知识库保持为一次即时查找，而非每次会话的上下文税。
对两条路径做冒烟测试
证明捕获写入了真实描述，且检索能按主题找到它：
# 捕获冒烟测试——一个新知识 bead 带着真实正文落地
printf '%s' "Smoke: <two-sentence real finding>" | bd create "Smoke: retrieval works" -t research -l kb,<topic> --defer 2099-01-01 --body-file - --silent
# 检索冒烟测试——主题查询浮现出它
bd list --label <topic> --status all
有了阶段 1 的守卫在你的测试面里，漏掉的捕获或越出词表的标签现在会在发生的那一刻就让构建失败。
退出标准。 当以下各项都成立时，本阶段完成：
- [ ] 一次捕获冒烟测试产出一个带完整描述的 bead，而非只有标题的行。
- [ ] 一次检索冒烟测试按主题标签浮现出一个已知条目。
- [ ] 两个守卫都在你的测试面里运行且为绿。
阶段 5：生命周期
知识库不是一次性装载；它会漂移，而三个习惯让它保持准确。
替换时用 supersede
当一个决策改变或一份文档被重写时，别在可能正读着旧 bead 的人眼皮底下把它编辑掉——用 supersede 取代它，它会退休旧的并链接到替代者：
让整理器治理词表
一次周期性的 memory-curator 扫描承担词表治理：合并已经收敛的标签、退休从未挣得第二个成员的单例、在足够多的 bead 围绕某个新簇堆积起来后为它命名。词表漂移是常态；放任不治，就是查询轴腐烂的方式。
让冷却的记忆沉入知识库
一条已经冷却的注入记忆——仍然为真、但不再需要被主动递上——会作为参考知识沉入延迟知识库。这是阶段 0 的边界随时间反向运行：一条笔记，在你不再希望每次会话都把它递到手上、却仍想在去找它时能找到时，便从注入中毕业。
退出标准。 当以下各项都成立时，本阶段完成：
- [ ] 替换使用
bd supersede，而非抹去历史的原地编辑。 - [ ] 已排定一次周期性的整理器扫描来治理词表。
- [ ] 对于让冷却的注入记忆沉入知识库，有一条约定的路径。