zhuyongxin
24a71e78f1
- Record rejected answers in decision.md at the moment they are rejected - Allow explicit pre-authorized Build via a pre-authorized marker line - Land scripts/check-dev-flow.sh and derive devflow/index.md from archives - Add dev-flow process artifacts (decisions, prd) for open changes
43 lines
2.1 KiB
Markdown
43 lines
2.1 KiB
Markdown
# Decision: 目录名作为日期和标题的真理源
|
|
|
|
<!-- migrated-from: devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md (2026-09-18, change: migrate-devflow-archives) -->
|
|
|
|
## Problem
|
|
|
|
知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter,其中也有 `date`/`created` 和 `title` 字段,但实际使用中发现字段名不一致(`date` vs `created`)且格式有差异。
|
|
|
|
索引重建脚本需要确定日期和标题的权威来源——两个来源都存在且都可能被读到时,不指定权威就必然漂移。
|
|
|
|
## Decision
|
|
|
|
**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。**
|
|
|
|
- 日期从目录名的 `YYYYMMDD` 部分提取
|
|
- 短标识符从目录名的 `Slug` 部分提取(用于文件路径构建,不用于显示)
|
|
- 显示标题从 YAML frontmatter 的 `title` 字段提取
|
|
- `tags` 和 `author` 从 YAML frontmatter 提取
|
|
|
|
## Alternatives considered
|
|
|
|
- Q: YAML 字段全优先? A: 不——字段名不一致(date vs created),脚本要处理变体,漂移点更多。
|
|
- Q: 目录名全优先? A: 不——标题中的语义信息在下划线转空格后丢失(如 `mattpocock_skills` → `mattpocock skills`,实际标题更长更精确)。
|
|
|
|
## Consequences
|
|
|
|
**买到了**:
|
|
- 索引脚本不需要处理日期字段名变体(date vs created)
|
|
- 目录名是可见的、可审计的——与 `ls` 输出完全一致
|
|
- bash 用 glob 匹配 `knowledge_*` 目录,天然获取了日期和 slug
|
|
- 显示标题从 YAML 取,支持完整的、精确的标题文本(含标点、中文)
|
|
|
|
**付出了**:
|
|
- 索引脚本需要解析 YAML frontmatter(复杂度比仅取目录名高)
|
|
- 如果目录被重命名,slug 会变化但显示标题不受影响(可接受的行为)
|
|
- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定
|
|
|
|
## Verification
|
|
|
|
**只读(可直接跑)**
|
|
- `ls knowledge/entries/ | head -3` → 目录名均形如 `knowledge_YYYYMMDD_Slug`
|
|
- `grep -n 'date' scripts/update-knowledge-index.sh | head -5` → 日期提取自目录名而非 YAML
|