Huajishe Notes

3-目录治理规则

14 min read

3-目录治理规则

一句话定位

本文档定义世界模型（World Models）笔记库的目录结构规范、文件命名约定、内容质量标准与维护流程，确保笔记库的结构一致性和长期可维护性。

前置依赖

  • Obsidian 使用基础（创建笔记、标签管理、双向链接）
  • Markdown 语法基础
  • 文献管理基础（PDF 标注、论文引用格式）

核心思想

世界模型笔记库采用层级化+模块化的目录结构：

  • 层级化：按内容深度从”基础概念 核心论文 前沿扩展”组织
  • 模块化：按技术路线（如 Dreamer/MuZero/PlaNet）分组相关笔记

治理规则的核心目标是：

  1. 一致性：所有笔记遵循统一的命名、格式与结构标准
  2. 可发现性：通过清晰的目录结构与标签系统快速定位内容
  3. 可维护性：明确的修改规范避免版本混乱
  4. 可扩展性：预留扩展槽位支持新论文和新方向

目录结构规范

顶级目录结构

6-世界模型/
├── 0-总导航/           # 元笔记：路线图、阅读顺序、术语表、治理规则
├── 1-世界模型基础/     # 基础概念（4个模块）
├── 2-世界模型主线论文/ # 核心论文按路线分组（6个模块）
├── 3-规划与控制/       # 应用：MPC、PETS 等
├── 4-生成式增强世界模型/ # 前沿扩展：视觉增强、Transformer
├── 5-实验复现与工程实现/ # 工程实践
└── 6-科研问题与开放方向/ # 前沿研究问题

目录命名规范

规则：

  • 顶级目录：X-名称，其中 X 为数字序号（0-9），表示逻辑顺序
  • 二级目录：同样采用 X-名称 格式
  • 多级嵌套：最多允许 3 级（避免过深结构）

示例：

正确：1-世界模型基础/
正确：1-世界模型基础/2-观测与表征/
错误：1/世界模型基础/（缺少分隔符）
错误：1-世界模型基础/（末尾斜杠）

序号编排规则

序号含义示例
0元/导航类0-总导航
1基础概念类1-世界模型基础
2核心论文/算法类2-世界模型主线论文
3应用类3-规划与控制
4增强/扩展类4-生成式增强世界模型
5工程实现类5-实验复现与工程实现
6前沿探索类6-科研问题与开放方向

文件命名规范

笔记文件命名

格式：

序号-文件名.md

规则：

  1. 序号：与所属目录层级对应，使用连续的整数（从1开始）
  2. 简洁性：文件名应简洁明了，核心概念词优先
  3. 中文优先：中文笔记使用中文文件名
  4. 无特殊字符：避免使用 :、*、?、/、\ 等特殊字符
  5. 版本标识：如需版本号，使用 _v1、_v2 后缀

正确示例：

0-世界模型路线图.md
1-什么是世界模型.md
2-DreamerV1详解.md
2-MuZero算法推导.md
3-交叉熵方法CEM.md

错误示例：

世界模型路线图.md           # 缺少序号
0-世界模型路线图 v1.md      # 空格和版本标识位置错误
0-世界模型@路线图.md        # 特殊字符@
1-what_is_world_model.md    # 英文文件名（非中文内容除外）

论文笔记命名

格式：

X-论文简称.md
# 或
X-论文简称_核心公式.md

规则：

  • 简称应包含作者名或缩写（如 DreamerV1、PlaNet）
  • 同一论文的多份笔记（如背景、公式、代码）使用子文件夹

示例：

1-早期世界模型/
├── 1-World Models Ha 2018.md
├── 2-DreamerV1 详解.md
├── 3-DreamerV2 核心公式.md
└── 4-DreamerV3 统一框架.md

内容结构模板

必需 Frontmatter 字段

每个笔记文件必须包含以下 frontmatter 字段：

---
title: 文件标题
tags:
  - 标签1
  - 标签2
created: 创建日期（YYYY-MM-DD）
description: 一句话描述（不超过50字）
---

字段说明：

字段必填说明
title是应与文件名保持一致
tags是使用小写，单词间用 - 连接
created是格式：YYYY-MM-DD
description是用中文概括文件核心内容

内容结构规范

标准结构（按顺序）：

  1. 标题（Heading 1）：与文件名一致
  2. 一句话定位：用一句话概括本文的核心定位（前置依赖、目标）
  3. 前置依赖：阅读本文前需要掌握的知识
  4. 核心思想：本文的核心贡献/内容概述
  5. 模型结构图/伪代码：可视化理解
  6. 数学推导：完整的公式与变量定义
  7. 训练细节：优化器配置、损失函数、训练技巧
  8. 推理/Rollout/规划流程：算法的实际执行流程
  9. 优缺点分析：客观评价
  10. 与其他笔记的关联：双向链接
  11. 可复现性要点：实现关键点
  12. 总结：要点回顾
  13. 关键词：标签来源

内容格式规范

公式格式：

  • 行内公式使用 $...$
  • 独立公式使用 $$...$$
  • 公式后必须包含变量定义
  • 公式编号使用 式(X.X) 格式

示例：

其中：

  • ：编码器/推理模型
  • ：解码器/生成模型
  • ：KL 正则化权重

链接格式：

  • 内部链接：使用 [[笔记名称]] 或 [[路径/笔记名称]]
  • 外部链接：使用 [文字描述](URL) 格式

代码格式：

# 使用 ```python 代码块标记
# 添加行号和语法高亮
def world_model_loss(data):
    ...

标签管理规范

标签层级

层级示例说明
一级标签world-models、reinforcement-learning领域级
二级标签dreamer、muzero、planet论文/算法级
三级标签variational-inference、imagination-rollout概念级

标签命名规则

  • 使用小写字母
  • 单词间使用 - 连接（而非下划线 _）
  • 避免使用中文
  • 同一笔记的标签数量：3-8 个

正确示例：

tags:
  - world-models
  - dreamer
  - imagination-rollout
  - latent-variable

错误示例：

tags:
  - 世界模型            # 中文标签
  - Dreamer_V2          # 下划线和大写
  - rl                 # 过于简写

版本控制规范

修订记录

当笔记内容发生重要修改时，在文件末尾添加修订记录：

---
 
## 修订记录
 
| 日期 | 修订人 | 修订内容 | 版本 |
|------|--------|----------|------|
| 2026-05-22 | xxx | 初始版本 | v1.0 |
| 2026-06-01 | xxx | 补充公式推导 | v1.1 |

修订类型

修订类型说明
v1.0初始版本
v1.x内容补充/错误修正
v2.0重大结构调整/核心内容重写

注意事项

  • 修订记录放在文件末尾 --- 分隔符之后
  • 保留历史版本的笔记文件（使用 _v1、_archive 等后缀）
  • 不直接覆盖已发布的笔记，应创建新文件或明确标注修订

评审与质量标准

内容质量检查清单

提交新笔记前，确保以下各项满足：

  • 包含完整的 frontmatter（title、tags、created、description）
  • 包含”一句话定位”和”前置依赖”
  • 核心公式有完整的变量定义
  • 包含与其他笔记的双向链接（至少 2 个）
  • 关键术语在 2-术语表 中有对应条目
  • 无拼写错误、格式混乱
  • 代码块有语言标记和适当注释

评审流程

对于新论文笔记：

  1. 初稿：由研究者创建，包含论文核心内容
  2. 技术评审：检查公式正确性、内容完整性
  3. 格式评审：检查 frontmatter、链接、标签规范
  4. 发布：通过评审后合并到主分支

链接规范

内部链接规则

链接格式：

[[笔记名称]]                    # 链接到同目录下笔记
[[路径/笔记名称]]               # 链接到子目录笔记
[[../路径/笔记名称]]             # 链接到父目录笔记

链接文本显示：

[[笔记名称|显示文本]]           # 自定义显示文本
[[笔记名称#章节名|章节名]]             # 链接到特定章节

示例：

[[0-世界模型路线图]]                        # 显示"0-世界模型路线图"
[[0-世界模型路线图|查看完整路线图]]          # 显示"查看完整路线图"
[[2-术语表#elbo|ELBO]]                            # 链接到术语表 ELBO 章节

外部链接规则

论文链接：

- [论文标题](https://arxiv.org/abs/XXXX.XXXXX)
- [GitHub 仓库](https://github.com/xxx/xxx)

格式：标题使用 Markdown 链接，优先使用 arXiv/Papers with Code 等稳定链接。

常见问题与解答

Q1：如何处理术语翻译？

A：在首次出现处标注英文原文，采用”中文术语（English Term）“格式。

变分自编码器（Variational Autoencoder, VAE）

Q2：新论文应该放在哪个目录？

A：遵循以下优先级：

  1. 已有路线：放在对应路线目录下（如 MuZero 相关放 3-imagination RL路线/）
  2. 新路线：创建新的二级目录（如 7-新型世界模型/）
  3. 跨路线论文：放在最相关的路线下，在其他路线笔记中交叉引用

Q3：笔记内容与现有笔记重复怎么办？

A：

  1. 检查是否可以通过链接复用而非复制
  2. 如果确实需要重复，确保各有侧重（一个偏理论、一个偏实现）
  3. 在两个笔记中相互链接

Q4：如何处理 PDF 论文与笔记的关系？

A：

  1. PDF 论文存储在本地或云端，笔记中通过链接引用
  2. 笔记的 description 中标注对应论文信息
  3. 建议使用 Papers with Code 的标准引用格式

可复现性要点

  1. 目录结构验证：使用 tree 命令定期检查结构是否符合规范
  2. 链接检查：使用 Obsidian 的”检查外部链接”功能验证链接有效性
  3. 标签审计：定期检查标签使用情况，合并重复/相似标签
  4. 文件命名检查：确保所有文件符合命名规范

与其他笔记的关联

总结

目录治理规则是确保世界模型笔记库长期可维护的基础规范。核心要点包括：

  1. 层级化+模块化：通过 X-名称 格式实现清晰的层级结构
  2. 标准化命名：文件名、标签、链接遵循统一规范
  3. 模板化内容：每篇笔记遵循统一的结构模板
  4. 版本化管理：修订记录和版本号跟踪内容演进

遵守这些规范，将使笔记库保持结构清晰、易于扩展，并便于多人协作维护。

关键词

目录治理、规范命名、内容结构、Frontmatter、标签管理、链接规范、版本控制、Obsidian

Graph View