📚 文档治理

产品文档 + 五层研发知识漏斗 / frontmatter / INDEX / 自动化校验

⚙️ 本文件由 pnpm docs:rebuild 自动生成 — 修改无效。

涉及文档（15 个）

🎯 功能规格（4）

• 知识库改造 — 借鉴卡帕西的四层漏斗 · done
• 引入 raw + specs 层 + 全文档 frontmatter + .gitignore 隔离备份
• 文档治理自动化（docs:check + docs:rebuild + _overview） · done
• 用脚本 enforcement 解决"INDEX 脱节 / 断链 / 重复信息"持续累积的问题
• SPEC-005 — React 前端 lifecycle 系统性扫描 + 修复 · parked
• 334 处 useEffect/setState 全量审 — 找裸异步、unmount race、setState-on-unmounted；分 3 期推进
• 文档与功能同步治理升级 · in-progress
• 用产品文档试点、显式 Docs-Impact 声明和只读门禁降低功能与文档漂移

🔧 已知问题 + 修复（4）

• 设置页右侧出现两个滚动条 · fixed
• 设置的右侧两个滑动的？？
• 「去创建任务」按钮点击无反应 — storage API 混用 · fixed
• 按钮用 browser.storage.local.set 原生 API，watcher 用 wxt/storage 抽象，key 不同步
• 批量删 untracked 文件误删刚 Write 的新 ISSUE 文档 · fixed
• v0.10.112 写 ISSUE-0074 后跑 rm-untracked 脚本一并删掉了刚建未 git add 的 ISSUE 文件
• .gitignore 的裸 Icon 规则误伤 src/public/icon，任何 clone 都编译不过 · fixed
• macOS Finder 残留规则匹配到任意层级同名目录，被 5 处生产代码引用的 128.png 从未进 git

📋 工作流规则（5）

• 元规则：按需建档机制
• 用户首次描述某工具用法/工作流时，AI 必须立即落档，杜绝重复描述
• 文档目录规范 — 什么在根 / 什么在 docs/ · stable
• repo 根目录与 docs/ 分层规则；区分产品使用文档和五层研发知识漏斗
• Docs-Impact — 功能改动与文档同批同步 · stable
• src 或 WXT 配置进入提交时，声明同批更新的文档或具体无影响理由
• GitHub 推送规则 · stable
• 首次推送到 github + 日常同步策略 + 推哪些不推哪些
• 每版本沉淀检查表 — 何时必建 ISSUE / wiki / SPEC · stable
• 版本完成 commit 前的强制自查清单，防"小修不归档"积累成历史空白

🗒️ 原始素材（2）

• 讨论 — 文档体系体检诊断 · spec-ed
• 用户请求评估 v0.10.22 建立的文档体系；我跑数据诊断找出 9 个真问题
• 讨论 — 知识库结构借鉴卡帕西 · spec-ed
• 用户提出借鉴 Karpathy 的 raw + wiki 二分法构建多层知识体系

给 AI / 新协作者的建议阅读顺序

1. 先读 specs（了解需求 / 设计决策）
2. 遇到 bug 查 issues（避免重蹈覆辙）
3. 追溯起源看 raw（用户原话）