知识库体检报告
对
pages/全部 108 篇（体检时）做的一次机器化体检 + 与市面知识库/学习路线的分类对标。体检日期：2026-09-30 · 第一批修复与内容补齐完成于 2026-10-01（现 118 篇） · 第二批新增文档审查与优化完成于 2026-10-02 规范依据 GUIDE.md · 计划见 PLAN.md
用法：本文件不是规范，也不是计划。它回答两个问题——哪些文章需要修改、哪些分类该补内容。 处理完一条就在本文件划掉，并在 PROGRESS.md 追加一行。
处理进度（2026-10-02 更新）
| 项 | 状态 |
|---|---|
| 1.1 B32/B33 三处漏登记 + ID 冲突 | ✅ 已修（含 B32→B34 顺延） |
| 1.2 首页与 README 篇数、hero 文案 | ✅ 已修 |
| 1.3 七处相对死链 | ✅ 已修（复查 0 处） |
| 1.4 G 域缺互链章节 | ✅ 误报已澄清：19 篇均有互链章节，只是叫「延伸方向」；顺带修掉 3 处真实过期引用 |
| 1.5 A03 翻新方案 | ✅ 已翻新（537→393 行）+ 2026-10-02 补 frontmatter |
| 1.6 踩坑区待补充清单 | ⬜ 遇到即填 |
| 三之二 N1 三域缺 README | ✅ 已建 backend/basic/database 三份域 README 并注册导航 |
| 三之二 N2 DB11 孤岛 | ✅ 已加 4 条入链（GP02/GP08/G12 + 自检），不再是全库唯一孤岛 |
| 三之二 N3 C01 偏薄 | ✅ 已补强：257 行 / 5 代码块（二维决策矩阵 + 四运行时并发对照 + 迁移账本） |
| 三之二 N4 G12 偏薄 | ✅ 已补强：307 行 / 4 代码块（预算守卫 + 上下文体检 + 三层级联压缩） |
| 三之二 N5 A03 frontmatter | ✅ 已补 |
| 三之二 N6 三篇标题统一 | ✅ E01 / DB11 / GP08 的 H1 与文件名已对齐 |
| — 构建验证 | ✅ npm run docs:build 通过（78s / 138 页 HTML），三域 README + 补强篇均已上线 |
零、一句话结论
内容本身没什么空洞——全库扫不到真实的 TODO / 占位未写（扫出来的 TODO 全是示例代码里的 ADD_TODO、grep "TODO"）。
真正的问题是元数据和索引没跟上内容：2 篇写完却没登记、首页篇数全部过期、7 处死链、G 域 19 篇缺互链章节。 这些是"库变大之后的维护债"，成本很低但影响很大——读者点不到、统计不可信。
分类层面，对标市面 AI 全栈路线，缺的是上下文工程、检索进阶、Python、后端三篇、向量库这几块。
一、必须修（一致性硬伤，约半天）
1.1 B32 / B33 两篇写完但三处漏登记 ⭐ 最严重
| 文件 | 状态 |
|---|---|
pages/flutter/.../07-工程化/32-规格驱动开发与AI协作.md | 已写完 |
pages/flutter/.../05-项目实战/33-uni-app对照查证.md | 已写完 |
漏掉的（GUIDE 第一节 5 步中的第 3/4/5 步）：
| # | 漏了什么 | 后果 |
|---|---|---|
| 1 | .vitepress/config.ts 未注册 nav / sidebar | 站点导航里根本点不到这两篇 |
| 2 | plan/flutter.md 未进「已写」表 | 计划与实际不一致 |
| 3 | pages/flutter/.../README.md 清单表未补行 | 域内索引缺两篇 |
附带一个 ID 冲突：plan/flutter.md 待写表里 B32 被「动态化与热更新 ⏸P3」占着， 但实际写的 32- 是「规格驱动开发与 AI 协作」。
处理方案：把已写的
B32登记为「规格驱动开发与 AI 协作」，「动态化与热更新」顺延到B34。
1.2 首页与 README 的篇数全部过期
| 区域 | 写着 | 实际 | 出错位置 |
|---|---|---|---|
| 前端 | 5 篇 | 28 篇 | index.md 内容总览 + 模块卡片、README.md 现有内容表 |
| 速查区 | 5 篇 | 8 篇 | 同上（两张卡都写 5 篇） |
| 面试题区 | 4 篇 | 8 篇 | 同上（实际已写 8 个分类页） |
| Flutter | 32 篇 | 34 篇 | 同上（B32/B33 没算进去） |
index.md的 herotagline还写着「前端转 Flutter 的成长记录」， 但库的重心已经是 AI 全栈——文案也该换了。
1.3 七处相对死链（正文里的 ./xxx.md 形式）
| 文件 | 错误链接 | 应为 |
|---|---|---|
AI/practice/04-MCP实战-... | ../AI/practice/01-LLM-API实操入门.md | ./01-LLM-API实操入门.md |
AI/practice/06-Agent实战-... | ../AI/practice/01-LLM-API实操入门.md | ./01-LLM-API实操入门.md |
flutter/.../01-入门导览/00-学习路线图.md | ./01-Dart语言基础.md | ../02-Dart基础/01-Dart语言基础.md |
flutter/.../02-Dart基础/01-Dart语言基础.md | ./02-Flutter核心基础.md | ../03-Flutter基础/02-Flutter核心基础.md |
flutter/.../06-平台能力/18-本地存储与持久化.md | ../../README.md | ../README.md |
flutter/.../06-平台能力/24-推送通知与深链接.md | ../../README.md | ../README.md |
flutter/.../06-平台能力/26-混合开发与Add-to-App.md | ../../README.md | ../README.md |
注：
config.ts里开了ignoreDeadLinks: true，所以构建不会报错，问题被静默吞掉了。 建议修完后改用「站内绝对路径」写法，或至少每季度跑一次链接检查。
1.4 G 域 19 篇全部缺「相关文档」章节
GUIDE 5.1 的标准长文骨架要求结尾有 ## 相关文档（本域、跨域、速查/踩坑互链）。
| 域 | 缺失情况 |
|---|---|
| G · AI | 12 篇正文 + 7 篇实操 全部没有互链章节 |
| B · Flutter | 约 20 篇缺 相关文档；另有 8 篇缺 自检清单 |
| A · 前端 | 仅 05-React与Vue 缺 自检清单 |
这是投入产出比最高的一项：知识库的价值在互链，AI 域和前端域之间（如 G05 LLMOps ↔ A12 可观测性、G02 RAG ↔ A04 缓存）完全没打通。
1.5 挂了 26 天未决的翻新项
plan/frontend.md 待翻新表里的 A03 · TypeScript 进阶与 Dart 对照： Dart 对照部分与 B 域各篇的前端对照重复，两个方案（删减 / 迁入 B 域）自 2026-09-04 起未决。 PROGRESS.md 的待办区也挂着同一条。
1.6 踩坑区「待补充清单」6 条全空
pages/troubleshooting/README.md 末尾列了 6 个待记录场景，一条都没填： build_runner 冲突 · iOS 证书失败 · Add-to-App 集成期错误 · Riverpod 疑难 bug · 列表性能实例 · 真机/模拟器差异。
踩坑区是「最不可替代的部分」，但这 6 条是遇到时才写的，不必硬造——建议保留清单，遇到即填。
二、建议修（提升价值，非硬伤）
| 项 | 说明 | 建议 |
|---|---|---|
| frontmatter 缺失 | 115 篇中 76 篇无（GUIDE 允许历史文章暂不补；本轮新增 5 篇全部已带） | 随翻新顺带补，不必专项 |
| AI README 无清单表 | 只有代码块目录树，其他域都是可点击清单表 | 补一张链接表，与其他域一致 |
| 附录时效 | plan 要求每月刷新，标注停在「2026-09」 | 月底刷新一次，写具体日期 |
| Flutter 行号引用 | 大量 main.dart:210-257，规范要求每季度抽查 | 9-04 起未查，可安排一次 |
| 文件名含空格 | 21-Platform Channel 原生桥接.md、25-Flutter Web与桌面端.md | 规范允许历史遗留，链接已用 %20，可不动 |
三、分类缺口（对标市面知识库）
对标对象（2026 年当前）：
| 来源 | 类型 | 关键信号 |
|---|---|---|
| AI Engineer Learning Path（aishippinglabs，基于 1000+ JD 分析） | AI 岗技能图谱 | Python 82.5% · Docker 31% · CI/CD 29.3% · K8s 29.1% · 向量库 10.8% |
| Applied AI Engineer Roadmap（codefarm，9 阶段） | AI 工程路线 | 上下文工程与记忆独立成阶段；高级检索（HNSW/Hybrid/Rerank/HyDE）；GraphRAG；Harness 工程；成本与模型路由 |
| 全栈知识库通用骨架（CSDN 等） | 目录结构 | 环境 / 前端 / 后端 / DevOps / 算法 / 系统设计 / 工具流 |
| 面试鸭 2026 分类 | 面试题库 | AI Agent（MCP/A2A、Tool Calling、ReAct、上下文窗口管理、记忆机制）已成独立大类 |
3.1 缺口清单
| # | 分类 | 本库现状 | 市面基准 | 建议新增 | 优先级 |
|---|---|---|---|---|---|
| 1 ✅ | 上下文工程 | G04 里有一章 | roadmap 第 3 阶段 | 已交付 G12：上下文装配、填充率分区响应、Token 预算、压缩三层级联、四种失败模式、记忆四层外置、工具与上下文 | 完成 |
| 2 ✅ | 检索进阶 | GP02 入门 RAG | roadmap 第 5/6 阶段 | 已交付 GP08：ANN 索引选型与调参、RRF 边界、HyDE、学到的稀疏、pre/post-filter、GraphRAG 判断框架、RAG 分层评测、静默降级诊断 | 完成 |
| 3 ✅ | Python（AI 侧） | AI 岗 82.5% essential | 已交付 E01（并激活 E 域）：Python 与 TS/Dart 对照，聚焦迁移陷阱而非语法大全 | 完成 | |
| 4 ✅ | 后端 C 域 | 全栈必备；公司要求前端接后端 | 已交付 C01~C03：运行时选型、API 设计与版本兼容、认证授权与权限模型 | 完成 | |
| 5 ✅ | 向量数据库 | AI 岗 10.8% | 已交付 DB11：pgvector（类型/索引/调参/过滤冲突/两阶段量化/运维） | 完成 | |
| 6 | 成本与模型路由 | 散在 G05 | roadmap 第 9 阶段 | Token 成本模型、缓存、大小模型路由、批处理 | P1 |
| 7 | DevOps D 域 | 候选池，0 篇 | Docker/CI/CD/K8s 在 AI JD 中 31/29/29% | 从候选池升级，先写 Docker 与部署 2 篇（前端视角） | P1 |
| 8 | 安全 S 域 | 0 / 7 篇 | 面试 IS 分类也还空着 | S01 Web 应用安全 + S02 认证授权，与 IS 同步 | P1 |
| 9 | 速查区扩域 | 8 篇全是 B/E 域 | 市面库普遍按语言/主题铺满 | 补 TS / CSS / 手写题（A 域）、Python、SQL、Docker | P1 |
| 10 | 踩坑区扩域 | 4 篇全是 Flutter | 同上 | 补前端踩坑、AI 踩坑（上下文超限/限流/OOM/幻觉）、工具链已有一条可扩展 | P1 |
| 11 | 网络 N 域 | 0 / 12 篇 | 面试 IN 已内联覆盖大半 | 缓办：先 N04 HTTP 深入 + N07 WebSocket | P2 |
| 12 | 工程方法论 F 域 | 候选池（但已写 B32 规格驱动） | — | 升级为域：调试方法论、Code Review、技术选型、方案写作 | P2 |
| 13 | 项目复盘 / 作品集 | 无此形态 | 市面强调 4~6 个可讲项目 | 新增 projects/ 形态区，或并入 IH 项目深挖素材 | P2 |
| 14 | 前端域扩展 | 28 篇已完整 | — | WebGL/数据可视化、低代码搭建、国际化本地化（plan 已提但未登记） | P3 |
| 15 | 数据库 DB 域 | 0 / 10 篇 | 面试 ID 分类空着 | 随 C 域推进，先 DB02 索引 + DB05 Redis | P2 |
3.2 建议执行顺序
text
第一批（维护债） ✅ 已完成 2026-09-30 ~ 10-01
B32/B33 三处登记 → 首页/README 篇数与文案 → 7 处死链 → A03 翻新
第二批（AI 全栈最短板） ✅ 已完成 2026-10-01（第 4 项未做）
上下文工程 G12 → 检索进阶 GP08 → Python E01 → 〔成本与模型路由〕
第三批（后端与工程能力） ✅ 已完成 2026-10-01（第 2 项未做）
C01/C02/C03 → 〔Docker 与部署〕→ 向量库 DB11下一批建议（按性价比排序）
text
1. 成本与模型路由（P1，第二批遗留）
Token 成本模型、Prompt 缓存、大小模型路由、批处理 —— 现在有 G12 打底，写起来更快
2. Docker 与部署（P1，AI 岗 JD 中 Docker 31% / CI/CD 29%）
从候选池升级 D 域，先写 2 篇（前端视角）
3. 形态区铺开（P1，把已有知识变成可查可复习）
速查扩域(TS / Python / SQL) → 踩坑扩域(前端 / AI) → 面试 IS / ID / IB
4. 安全 S 域（P1）与数据库主体（DB01~DB10）
5. 全库互链收尾
B 域约 20 篇缺「相关文档」；各域 README 清单同步（本次已修 G / 后端 / 数据库 / 基本功）三之二、第二批新增文档审查（2026-10-01）
对第二批新增/翻新的 8 篇做机器化复查：骨架、frontmatter、链接、入链、内容密度。 结论：骨架与链接全部合格，问题集中在「三个新域缺索引」「一篇孤岛」「两篇内容偏薄」。
复查对象
| 文档 | ID | 行数 | 代码块 | 表格 | 骨架 | frontmatter | 入链 |
|---|---|---|---|---|---|---|---|
| 12-上下文工程 | G12 | 234 | 1 ⚠️ | 10 | ✅ | ✅ | 5 |
| 08-检索进阶 | GP08 | 310 | 6 | 11 | ✅ | ✅ | 4 |
| 01-Python语言基础与TS对照 | E01 | 410 | 16 | 10 | ✅ | ✅ | 4 |
| 01-运行时选型 | C01 | 173 ⚠️ | 1 ⚠️ | 6 | ✅ | ✅ | 5 |
| 02-API设计 | C02 | 228 | 3 | 10 | ✅ | ✅ | 3 |
| 03-认证与授权 | C03 | 209 | 4 | 8 | ✅ | ✅ | 5 |
| 11-pgvector向量检索 | DB11 | 345 | 13 | 10 | ✅ | ✅ | 0 ❌ |
| 03-TypeScript进阶与Dart对照 | A03 翻新 | 396 | 10 | 8 | ✅ | 缺 ⚠️ | 2 |
参照组（库内成熟文章）：
01-跨端方案横向对比456 行 / 4 代码块 / 8 判断句；09-数据层链路581 行 / 22 代码块。
待优化项
| # | 级别 | 问题 | 为什么是问题 | 怎么改 |
|---|---|---|---|---|
| N1 | ⭐⭐⭐ | README.md | 违反 GUIDE 4.1 第 4 步；sidebar 首项没有「域索引」，读者进域后无从鸟瞰 | 各建一份 README：域定位 + 篇目清单表 + 待写清单（照 pages/AI/README.md 的写法） |
| N2 | ⭐⭐⭐ | 写得再好也只出现在侧边栏末端，读者从 RAG / 检索路径走不到它 | 在 GP02「生产化检查清单」、GP08「二、ANN 索引」、G12「六、记忆」各加一条链入 | |
| N3 | ⭐⭐ | 它是全库唯一正面回答「Node 能不能做后端」的 P0 决策文，但比同类的 01-跨端方案横向对比（456 行）薄一半以上 | 补：并发模型的可运行对照代码（Node / Go 压测片段）、团队与场景的二维决策表、真实迁移成本账 | |
| N4 | ⭐⭐ | 上下文工程是强实操主题，Token 预算与压缩不给代码就退化为概念文 | 补：Token 预算计算片段、三层级联压缩的可运行骨架、上下文诊断脚本 | |
| N5 | ⭐ | GUIDE 4.3 要求「随翻新顺带补」，本轮正好翻新过却漏了 | 补 domain: A / id: A03 / status: done / priority: P1 / updated | |
| N6 | ⭐ | 导航文本（config.ts）用 H1，搜索与文件名用另一套，长期会漂移 | E01（H1 是「从 TS/Dart 迁移」）、DB11（H1 是「在 Postgres 里做向量检索」）、GP08 —— 统一为文件名表述，或反向改文件名（改文件名需同步 config.ts） |
已确认不是问题的项（避免重复劳动）
- 骨架章节命名变体：practice 系列用「生产化检查清单 / 动手任务 / 延伸方向」，AI 正文用「延伸方向」——GUIDE 5.1 已明确二者等价，GP08 符合域惯例，不必强改。
- A03 的「开篇：类型系统对照」：frontend 域既有叫法（
01「开篇：一张表看懂四条技术路线」、05「开篇：一张表看懂两者差异」），一致。 - DB11 的
$1$2：PostgreSQL 参数占位符，非价格，正则误报。 - 3 处「死链」：
tool["fn"](**args)等代码块内的函数调用，正则误报，实际零死链。 - 首页与 README 篇数：共 118 篇（含 9 份域 README，内容 109 篇），前端 28 / Flutter 34 / AI 22 / 后端 3 / DB 1 / 基本功 1 / 速查 8 / 踩坑 4 / 面试 8 —— 全部准确。
- frontmatter 覆盖 39/115：历史 76 篇允许暂不补，字段完整的 39 篇无缺字段。
建议顺序
text
先补索引（N1，3 份 README，约 1 小时）
→ 再打通孤岛（N2，3 条链入，10 分钟）
→ 顺手补 A03 frontmatter（N5，1 分钟）
→ 最后动笔补强 C01 与 G12（N3 / N4，真正的内容工作量）
→ N6 标题统一可并入下次翻新三之三、全库质量扫描与修复（2026-10-02 晚）
对
pages/下全部 118 篇做机器化扫描（frontmatter、骨架章节、实操密度、入链、占位符、命名）， 再逐项人工复核后修复。原则：不为了指标达标而填充空壳。
扫描基线（118 篇）
| 维度 | 达标 | 处置 |
|---|---|---|
| frontmatter | 40/118 | 历史 78 篇缺，GUIDE 4.3 明确「历史文章暂不补齐」，依规不动 |
| 定位引言 | 110/118 | 缺 8 篇已统一补齐 |
| 相关文档 / 延伸方向 | 74/118 | 真缺 14 篇已补；另 17 篇已有行内「导航：上一章 / 下一章」等价互链，不重复追加 |
| 自检清单 | 72/118 | AI 域以「延伸方向」收尾属域惯例；速查 / 踩坑另有 5.2 / 5.3 约定，均不属缺失 |
| H1 与文件名一致 | 66/118 | 多为标题加了副标题的措辞差异，非断链，暂不动 |
本轮实际修改
| 动作 | 数量 | 说明 |
|---|---|---|
| 补「相关文档」互链章节 | 14 篇 | 主要为 Flutter 教程；按「域索引 + 上下篇 + 形态区」生成，0 自链 |
| 统一「> 一句话定位」引言 | 8 篇 | AI 域 00/03/04/05/06/07/08/10，引言取自各篇速览卡原句，与同域骨架对齐 |
| 修正 plan 文件死链 | 6 处 | plan/flutter.md 3 处文件名缺 Flutter 前缀；plan/network.md 3 处路径层数错误（../frontend → ../../pages/frontend、../security → ./security） |
死链 42 → 36，自链接保持 0。
已复核确认不是问题的项
- 「内容偏薄」7 篇（AI 附录 / 00 / 04 / 09 / 10 / 11、
interview/ai.md）：均为表格型参考 / 索引文档，按 Diátaxis 属 Reference，本就不需要代码块。 - 占位符 24 处命中：全部是示例代码（
grep -rn "TODO"、// TODO: 迁移）与说明模板（[XXX]()），无真实未写完内容。 - 两个「孤岛」：
21-Platform Channel、25-Flutter Web为 %20 链接导致的统计误报，真实入链 12 条 / 4 条。
🔴 待决策：仓库根未登记的 interview/ 目录
根目录存在游离目录 interview/（01-JavaScript核心.md、05-Flutter核心.md、README.md）：
- config.ts 注册的全部是
/pages/interview/*，该目录从未登记（违反 GUIDE 2.4 及第八节「未登记的目录 = 违规目录」）； - 内容与正式的
pages/interview/（9 个分类文件）重复，系早期版本； - 剩余约 33 个死链全部源于此——其内部链接按「位于 pages/ 下」书写（
../flutter/...），实际父目录是仓库根； - 已确认无任何文档引用它，站内完全孤立。
建议删除（内容仍在 Git 历史可回溯），但涉及文件删除，已提请用户确认，未擅自执行。
四、体检方法（可复现）
| 检查项 | 做法 |
|---|---|
| 占位与待办 | 正则扫 TODO / TBD / 待补充 / FIXME，人工核对上下文（本库 10 处命中全是示例代码） |
| 导航注册 | 解析 config.ts 的 link: 与 pages/**/*.md 求差集 |
| 清单一致性 | 解析各域 README 的 markdown 链接 vs 目录实际文件 |
| 死链 | 提取正文相对链接，按目录解析后检查文件是否存在 |
| 骨架完整性 | 检查 开篇速览 / 自检清单 / 常见误区 / 动手练习 / 相关文档 五节 |
| frontmatter | 检查是否以 --- 开头且含 title/domain/id/status/priority/updated |
建议每季度跑一次；跑完在本文件更新日期并追加到
PROGRESS.md（类型记为规范或翻新）。