知识库改造 — 借鉴卡帕西的四层漏斗¶
1. 背景 / 动机¶
来源：../raw/conversations/2026-05-26-knowledge-base-inspired-by-karpathy|2026-05-26-知识库结构借鉴卡帕西
用户原话：
借鉴卡帕西的知识结构，构建 wiki 和 raw...希望实现： 1. 能不断迭代改进... 2. 新功能 需求，raw/wiki 怎么记录，数据结构 / API 接口，多人协作... 3. 同步 github，备份不同步 4. 所有文档有索引、title、元描述、标签
为什么要做：
- 现有 docs/{wiki, rules, issues}/ 三层缺一个"低门槛入口"（raw）
- 新功能/需求没有标准的 PRD 模板，多人协作时后端不知道做什么
- 文档没 frontmatter，obsidian 索引 / AI 检索受限
- 没有 .gitignore，无法选择性 push github（备份会被带上）
2. 目标 / 非目标¶
目标¶
- 建
docs/raw/+docs/specs/两层 - 所有 docs/ 下 md 加 YAML frontmatter
- 写 .gitignore 隔离 backup/ 与构建产物
- 写示例 raw + spec 让用户/AI 模仿
- 更新 CLAUDE.md / docs/README.md 入口
非目标¶
- 不迁移现有 wiki 内容到子目录（保持扁平）
- 不强制 github push（仅准备好，由用户手动）
- 不引入 obsidian 自动化插件（dataview / templater）
3. 用户故事¶
作为项目维护者，
我希望任何用户/AI 提出的需求都能先粘贴到 raw 不丢失，
评估后顺势写成 spec 给团队执行，实现完沉淀到 wiki，
以便单人迭代 + 多人协作都顺畅。
作为后端开发者（未来），
我希望打开 docs/specs/active/SPEC-xxx.md 就能看到数据模型 + API + 任务拆分，
不需要追溯多个聊天历史。
作为 AI 助手，
我希望每个文档有 frontmatter，让我按 tags / status 检索，
准确学习项目的当前架构。
4. 数据模型¶
不涉及代码 schema，只涉及文档 schema。
Frontmatter 标准¶
---
title: <标题>
description: <30字内描述>
tags: [tag1, tag2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: draft / stable / deprecated / archived
type: wiki / rule / issue / spec / raw / index
related:
---
文件命名¶
| 类型 | 格式 |
|---|---|
| wiki | 中文标题.md |
| rule | 中文标题.md（元规则加 00- 前缀） |
| issue | <4位编号>-<中文标题>.md |
| spec | SPEC-<3位编号>-<中文标题>.md |
| raw | YYYY-MM-DD-<简短中文>.md |
5. API 接口¶
不涉及 API（纯文档改造）。
6. UI 设计¶
不涉及 UI（纯文档改造）。
最终目录：
docs/
├── README.md 体系导航
├── raw/ 🆕 原始素材
│ ├── INDEX.md
│ ├── _template.md
│ ├── inbox/ ← 待处理
│ ├── feedback/ ← 用户反馈
│ ├── conversations/ ← 重要对话
│ └── ideas/ ← 未评估想法
├── specs/ 🆕 功能规格
│ ├── INDEX.md
│ ├── _template.md
│ ├── active/ ← 进行中
│ ├── done/ ← 已完成
│ └── parked/ ← 暂缓
├── wiki/ ← 已有（补 frontmatter）
├── rules/ ← 已有（补 frontmatter）
└── issues/ ← 已有（补 frontmatter）
7. 任务拆分¶
骨架¶
- 创建
docs/raw/{inbox,feedback,conversations,ideas}/ - 创建
docs/specs/{active,done,parked}/ - 写
raw/_template.md+raw/INDEX.md - 写
specs/_template.md+specs/INDEX.md
配置¶
- 写
.gitignore（排除 backup/ / dist*/ / node_modules / .obsidian 工作区配置） - 改写根
README.md（替换 WXT 模板默认内容）
示例¶
-
raw/conversations/2026-05-26-knowledge-base-inspired-by-karpathy.md（本 spec 来源） -
raw/feedback/2026-05-26-status-chip-misalign.md（关联到 ISSUE-0021） -
specs/done/SPEC-001-knowledge-base-refactor.md（本文件）
Frontmatter 补全（22 个现有 md）¶
- 写 Python 脚本扫描
docs/**/*.md，注入或更新 YAML frontmatter
入口更新¶
- 更新
CLAUDE.md加 6 步阅读顺序（含 raw/specs） - 更新
docs/README.md包含四层模型说明
规则¶
- 写
docs/rules/github-push.md—— 用户首次需要 push 时按此规则 - 更新
docs/rules/00-meta-rule.md加新触发场景（用户讲新需求 → raw/inbox/）
8. 风险 / 注意点¶
- ⚠️ 现有文档头部「伪 frontmatter」 形式不统一（有用
> **类型**：xxx块引用），脚本要兼容 - ⚠️ obsidian 的
[[wikilink]]在 github 渲染器不显示：我们用相对路径[文本](./path.md)作为主链接，frontmatter 里related: [[wikilink]]仅给 obsidian/AI 用 - ⚠️ frontmatter 写错会导致 obsidian/dataview 异常：必须 YAML 合法（缩进 / 引号 / 冒号）
9. 验证标准¶
-
find docs -name "*.md"所有文件首行是--- -
pnpm build通过（确认没破坏代码） - obsidian 打开
docs/能看到 tags / dataview（用户验证） - CLAUDE.md 包含 raw / specs 入口
-
.gitignore包含 backup/ + dist*/
10. 决策记录¶
- 2026-05-26：选 4 层（raw / specs / wiki / issues + rules）而不是 2 层（raw + wiki）—— 因为本项目有真实多人协作场景（后端独立），需要 specs 作为契约
- 2026-05-26：spec 命名用
SPEC-001-中文标题.md（保留全局序号 + 直观） - 2026-05-26：现有 docs 文件不重新归类到子目录，保持扁平 + 仅加 frontmatter —— 重新归类会破坏现有相对路径链接，收益小
- 2026-05-26：github push 本次不做，仅准备
.gitignore+ 写 push 指南到docs/rules/github-push.md，未来由用户手动触发