Dream as Fish

技术知识库

记录规范

guide · writing

记录规范

一条笔记，一个主要问题

标题使用可搜索的完整概念或问题，例如“UFS 中 UIC 命令如何完成链路启动”，避免“学习记录 1”。概念笔记尽量自洽，让脱离目录后的单篇内容仍能读懂。

固定结构

  1. YAML 元数据：机器可读的分类与生命周期。
  2. 摘要：用自己的话给出 2–5 句结论。
  3. 问题/背景：说明这篇笔记解决什么。
  4. 正文：解释机制；代码、图和数据服务于结论。
  5. 证据与来源：标明规范章节、内核版本、文件和函数。
  6. 关联：用 [[双向链接]] 连接前置、相似及相反概念。
  7. 待验证：明确不知道或尚未确认的部分。

四层知识结构

同一个主题按“导航—理解—操作—排错”拆成四层，不把理论、长命令和错误日志堆在同一篇笔记中。

目录回答的问题主要内容
10-Domains本领域有什么，应该按什么顺序学习？MOC、章节目标、概念导读、主线入口、故障索引、前置与后续
20-Concepts这是什么，为什么这样工作？术语、机制、边界、因果关系、适用条件，不承担完整操作流水线
30-Projects怎样从零做成并验证？可复现的成功主线、完整命令、配置内容、预期结果和完成标准
50-Labs为什么失败，如何定位并修复？故障现象、环境、根因、尝试、最终修复和验证结果

MOC 与章节

  • 每个章节 MOC 先写学习目标，再提供“概念导读”，随后链接 Project 主线和相关 Lab。
  • MOC 不复制长篇理论和命令，而是提供最短阅读路径与有意义的链接标题。
  • 新增 Concept、Project 或 Lab 后，应把它加入对应 MOC。

Concepts

  • 一篇 Concept 聚焦一个可独立理解的问题，例如“debootstrap 为什么分成两个阶段”。
  • 解释“是什么、为什么、如何关联”，写清版本和适用条件；不要把整套安装命令复制进 Concept。
  • Concept 至少链接一个相关 MOC 或 Project，使理论能够落到实际实验。

Projects

  • 30-Projects 保存可从零复现的成功主线。必须写清工作目录、前置条件、按顺序执行的完整命令、需要写入文件的完整内容、验证命令和完成标准。
  • Projects 使用“章节 → 小节 → 笔记”的语义层级：第一层目录代表一个完整学习目标，第二层目录代表该章内可独立验收的小节，Markdown 文件承载具体成功主线。
  • 第一、二层目录都采用 NN-语义名称；编号只表示同层阅读顺序，不跨层连续计数。例如 01-实验平台搭建/04-Debian-rootfs 与 02-Linux内核基础知识/01-GCC编译。
  • Project 在关键步骤前用一两句话说明目的，并链接对应 Concept；不在命令之间重复展开大段理论。
  • 重复的 ls 或临时探测可以合并，但不能省略影响结果的操作。
  • Project 遇到故障时只保留一句现象和对应 Lab 链接；详细错误日志不重复堆入主线。

Labs

  • 50-Labs 保存故障与调试闭环。每篇围绕一个主要问题，记录实际现象、环境、根因、尝试过的方案、最终修复和验证结果。
  • Labs 尽量镜像受影响 Project 的“章节 → 小节”路径，便于从成功主线定位故障；只有跨多个 Project 的通用故障才单独建立语义目录。
  • 成功的主线实验属于 Project，不因名称中包含“实验”就放入 Labs。
  • Lab 修复成功后，应把最终必要操作合并回相关 Project，确保 Project 单独阅读仍可复现。

链接方向

推荐形成以下双向路径：

MOC → Concept → Project → Lab
 ↑        ↘        ↗       │
 └───────── 关联与返回链接 ─┘
  • MOC 提供入口；Concept 链接实际 Project；Project 就近链接原理 Concept 和故障 Lab；Lab 链回受影响的 Project。
  • 首次出现的重要术语建立链接即可，避免同一段落反复链接造成噪声。

元数据字段

字段规则
id稳定、唯一，建议英文 kebab-case；文件改名时不改 ID
typemoc、concept、source、lab、project、daily、guide
statusseed（草稿）、growing（整理中）、evergreen（已验证）、archived
domain主领域：kernel、ufs、pcie、networking、meta 等
tags少而稳定，只表达横向特征，不复制目录层级
created/updatedISO 日期 YYYY-MM-DD
source来源笔记链接或 URL；没有则留空

命名与链接

  • MOC 使用 主题 MOC；其余文件使用自然语言标题，不加流水号。
  • 顶层章节编号与小节编号分别从 01 开始：不得把上一章最后的小节编号延续成下一章的第一个小节。
  • 同一小节的架构、平台和版本扩展继续放在原小节目录，并用“扩展：主题”命名；例如 RISC-V Debian rootfs 归入 30-Projects/01-实验平台搭建/04-Debian-rootfs。扩展不得占用新的同级小节或顶层章节编号。
  • 新编号必须对应新的语义目标：先回答“这是新章节、新小节，还是现有小节的扩展”，再创建目录。
  • 首次出现的重要术语链接到概念笔记；不要每次出现都链接。
  • 外部资料先建立来源笔记，再由概念笔记引用它。
  • 内核相关结论写明版本/commit；规范结论写明版本与章节。
  • 截图不能代替文字结论；图片说明里写清观察结果。

每周整理（约 20 分钟）

  • 清空或分类 01-Inbox。
  • 将实验结论提炼到概念笔记，而不是只留在日志中。
  • 把新笔记加入对应 MOC，并补至少一个有意义的关联链接。
  • 更新 status 和 updated，归档已失效内容。