40 lines
1.7 KiB
Markdown
40 lines
1.7 KiB
Markdown
# ADR-001: 目录名作为日期和标题的真理源
|
||
|
||
**状态**：已接受
|
||
**日期**：2026-05-18
|
||
|
||
## 背景
|
||
|
||
知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter，其中也有 `date`/`created` 和 `title` 字段，但实际使用中发现字段名不一致（`date` vs `created`）和格式差异。
|
||
|
||
索引重建脚本需要确定日期和标题的权威来源。
|
||
|
||
## 决策
|
||
|
||
**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。**
|
||
|
||
- 日期从目录名的 `YYYYMMDD` 部分提取
|
||
- 短标识符从目录名的 `Slug` 部分提取（用于文件路径构建，不用于显示）
|
||
- 显示标题从 YAML frontmatter 的 `title` 字段提取
|
||
- `tags` 和 `author` 从 YAML frontmatter 提取
|
||
|
||
## 替代方案
|
||
|
||
| 方案 | 被拒原因 |
|
||
|------|---------|
|
||
| YAML 全优先 | 字段名不一致（date vs created） |
|
||
| 目录名全优先 | 标题中的语义信息在下划线转空格后丢失（如 `mattpocock_skills` → `mattpocock skills`，实际标题更长更精确）
|
||
|
||
## 后果
|
||
|
||
### 正面
|
||
- 索引脚本不需要处理日期字段名变体（date vs created）
|
||
- 目录名是可见的、可审计的——与 `ls` 输出完全一致
|
||
- bash 用 glob 匹配 `knowledge_*` 目录，天然获取了日期和 slug
|
||
- 显示标题从 YAML 取，支持完整的、精确的标题文本（含标点、中文）
|
||
|
||
### 负面
|
||
- 索引脚本需要解析 YAML frontmatter（复杂度比仅取目录名高）
|
||
- 如果目录被重命名，slug 会变化但显示标题不受影响（可接受的行为）
|
||
- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定
|