📚 文档治理¶
产品文档 + 五层研发知识漏斗 / frontmatter / INDEX / 自动化校验
⚙️ 本文件由
pnpm docs:rebuild自动生成 — 修改无效。
涉及文档(20 个)¶
🎯 功能规格(5)¶
- 知识库改造 — 借鉴卡帕西的四层漏斗 · 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 声明和只读门禁降低功能与文档漂移
- 整页 Markdown 本地存储与上传契约 —— 给后端开发的接口需求 · in-progress
- 本地 PageMarkdown 表已落地;上传通道待后端,客户端只留接口面不接线
🔧 已知问题 + 修复(7)¶
- 设置页右侧出现两个滚动条 · 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
- package.json 加了依赖、lockfile 没跟上 —— HEAD 装不起来 · fixed
- 第一版只 path-scoped 提了 package.json,turndown 三条依赖在 lock 里 0 条
- 剪贴板写入吞错家族第三例 — task-filter-picker 复制任务 ID 静默失败 · fixed
- navigator.clipboard.writeText(id) 不 await、catch 空吞——ISSUE-0042 Y3 家族复发,闸字面锚定查不出等价形态
- L3 导出流式化——根除「导出全部只出最新 5 万行」截断(eligible 路径) · fixed
- 分批原生游标流式导出(4000/批)替代单次 50k cap 拉取;对账总数改与流同源精确计数(修 hasEmailOnly>5 万必炸);ESC/遮罩取消链闭环;宁失败不静默少给
📋 工作流规则(6)¶
- 元规则:按需建档机制
- 用户首次描述某工具用法/工作流时,AI 必须立即落档,杜绝重复描述
- 注释里别写可 grep 的代码字面量 · stable
- 本仓大量判据靠 grep 计数,注释里写代码串会让判据数错
- 文档目录规范 — 什么在根 / 什么在 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 / 新协作者的建议阅读顺序¶
- 先读 specs(了解需求 / 设计决策)
- 遇到 bug 查 issues(避免重蹈覆辙)
- 追溯起源看 raw(用户原话)