Reorganize workspace and archive skill artifacts

2026-05-20 11:39:30 +08:00
parent 0e0275d46a
commit f45122dafb
83 changed files with 9733 additions and 15 deletions
@@ -0,0 +1,39 @@
+# 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` 命名约定