学习文档真实性校验与 GitHub Skills 补强索引 2026

更新日期：2026-07-02
目标：用已安装 skills 和 GitHub 官方/高可信 skills 强化现有学习文档，但所有知识点最终以官方文档、标准、项目仓库和可运行示例为准。

这份文档不是替代原有学习文档，而是所有文档后续更新的“事实校验层”和“补强地图”。以后扩写任意一篇文档时，先看本文件对应目录的补强方向，再回到具体技术的官方资料核验版本、配置项、命令、限制和最佳实践。

---

1. 本次引入的 GitHub Skills

Skills 的价值是提供工作流、检查清单和落地提醒。它们不能替代官方文档，尤其不能替代最新的 API、CLI 参数、价格、限制、版本兼容性说明。

GitHub 来源	已安装/已使用的 skills	主要补强文档	使用边界
antfu/skills	vue-best-practices、vue-router-best-practices、vue-testing-best-practices、pinia、vitest、pnpm、turborepo、nitro、vitepress、unocss、tsdown	Vue、Nuxt、Vite、Monorepo、测试、包管理、构建工具	适合作为前端工程化和 Vue 生态检查清单；具体版本、配置项以 Vue、Nuxt、Vite、Vitest、pnpm、Turborepo 官方文档为准。
langchain-ai/langchain-skills	langchain-fundamentals、langchain-rag、langgraph-fundamentals、langgraph-persistence、langgraph-human-in-the-loop、langgraph-cli、langchain-middleware	LangChain、LangGraph、RAG、Agent 工作流	LangChain/LangGraph API 迭代很快，代码示例必须按官方 docs 当前版本复核。
neondatabase/agent-skills 与 neondatabase/postgres-skills	neon-postgres、postgres-best-practices	PostgreSQL、Prisma ORM、部署运维、全栈项目	Neon 平台特性和 Postgres 版本差异必须用 Neon Docs 与 PostgreSQL 官方文档核验。
addyosmani/agent-skills	performance-optimization、security-and-hardening、observability-and-instrumentation、ci-cd-and-automation、git-workflow-and-versioning、documentation-and-adrs、frontend-ui-engineering、source-driven-development	性能、安全、可观测性、CI/CD、Git、架构师文档	适合作为工程质量框架；指标阈值以 web.dev、OWASP、OpenTelemetry 等官方资料为准。
cloudflare/skills	cloudflare、wrangler、web-perf	前端 CDN、HTTP/CDN 缓存、Cloudflare Pages/Workers、性能优化、边缘计算	Cloudflare 产品限制、Wrangler 配置字段、兼容日期和价格必须查 Cloudflare Developers。
netlify/context-and-tools	netlify-caching、netlify-cli-and-deploy、netlify-config、netlify-deploy、netlify-edge-functions、netlify-frameworks、netlify-image-cdn	前端部署、CDN 缓存、图片 CDN、Nuxt/Vite 静态站点发布、边缘函数	Netlify 的缓存头、Image CDN、Edge Functions 限制必须查 Netlify Docs。
vercel-labs/agent-skills	deploy-to-vercel、vercel-optimize、vercel-cli-with-tokens	前端发布、性能与成本优化、CI/CD、环境变量管理	Vercel 项目部署、CLI 与平台能力以 Vercel Docs 和当前 CLI 为准；默认只做 preview 部署。
qdrant/skills	qdrant-search-quality、qdrant-deployment-options、qdrant-performance-optimization、qdrant-monitoring	LangChain RAG、AI 知识库项目、向量数据库、可观测性	RAG 检索质量、向量索引参数、部署模式必须用 Qdrant 官方文档和实际评测集验证。

安装提示：新下载的 skills 已放入本机 Codex skills 目录。Restart Codex to pick up new skills.

---

2. 真实性规则

1. 先定版本，再写结论。 任何涉及 Vue、Nuxt、Vite、Webpack、LangChain、LangGraph、Cloudflare、Netlify、Vercel、PostgreSQL、Docker、Nginx 的配置示例，都必须标明适用版本或文档核验日期。
2. 官方资料优先。 优先级为：官方文档、标准规范、官方 GitHub 仓库、发行说明、源码；博客和问答只能辅助理解，不能作为关键事实依据。
3. beta / experimental 必须标注。 例如 Rolldown、某些 Nitro/Workers/平台功能、LangChain 新 API、CLI 新参数，如果官方标记为 beta、experimental、preview，就不能写成稳定能力。
4. 配置项必须可落地。 每个配置示例要说明它影响哪些资源：HTML、JS chunk、CSS、字体、图片、SSR 输出、API 响应、上传文件、对象存储资源或边缘函数响应。
5. 性能结论要有指标。 Core Web Vitals 用 LCP、INP、CLS；构建和发布用 bundle size、cache hit ratio、TTFB、错误率、回滚时间、构建时长等指标。
6. 安全结论要有威胁模型。 不只写“开启安全配置”，要说明 XSS、CSRF、SSRF、供应链、密钥泄漏、缓存投毒、越权访问等风险如何被降低。
7. AI/RAG 结论要能评测。 不能只写“用向量库提升准确率”，要有 query set、Recall@k、MRR、NDCG、RAGAS 或人工标注闭环。
8. 不要把 skill 当权威事实。 skill 用来提醒工作流；事实仍回到官方文档核验。

---

3. 按现有目录的补强地图

目录	已有文档覆盖	应补强的真实知识点	推荐 skills / 官方来源
00-学习路线与索引	全栈路线、前端转 AI 路线	给路线增加“版本核验、项目验收、技能迁移”的关卡：每学完一类技术，要能产出一个可运行 demo、一次部署、一次测试和一次复盘。	documentation-and-adrs、source-driven-development
01-编程语言基础	JavaScript、TypeScript、Python、Java、Rust、正则	每篇语言文档都应区分语法、运行时、生态工具链和工程边界；JS/TS 重点补充 ESM、类型收窄、异步错误处理、浏览器/Node 差异。	MDN、TypeScript Handbook、Python Docs、Java Docs、Rust Book
02-前端基础与框架	Vue、Nuxt、Tailwind、vue.config、env、多端适配	Vue 3 Composition API、<script setup>、Pinia、Vue Router 守卫、Vue Testing、Nuxt SSR/ISR/routeRules、Tailwind 内容扫描与构建设定。	vue-best-practices、pinia、vue-router-best-practices、vue-testing-best-practices、nuxt、nitro
03-前端工程化与构建	Git、Vite、Webpack、前端 CDN、Monorepo、ESLint、Babel、Loader/Plugin	Vite base、Webpack publicPath、CDN asset hashing、pnpm workspace、Turborepo task graph、CI 构建缓存、release rollback、source map 安全策略。	vite、pnpm、turborepo、ci-cd-and-automation、cloudflare、netlify-caching、wrangler
04-前端架构师进阶	架构、微前端、性能、安全、可访问性、可观测性、权限、HTTP/CDN/BFF、实时通信、SSE、大文件上传	架构文档要从“方案介绍”升级为“指标 + 风险 + 决策记录”：Core Web Vitals、RUM、OpenTelemetry、WAF、CSP、缓存键、BFF 超时与重试、SSE 断线恢复、分片上传一致性。	performance-optimization、security-and-hardening、observability-and-instrumentation、web-perf、frontend-ui-engineering
05-后端与全栈框架	RESTful API、Node.js、NestJS、Spring、MyBatis	补充 REST 资源建模、HTTP 方法与状态码、OpenAPI、API 安全、API 分层、DTO/schema validation、错误码、日志 trace id、限流、数据库事务边界、测试金字塔和部署配置。	RFC 9110、MDN、OpenAPI、OWASP API Security、Node.js/NestJS/Spring/MyBatis 官方文档；质量类 skill 用于检查
06-数据库与数据访问	MySQL、PostgreSQL、MongoDB、Redis、Prisma、数据库对比	Postgres 类型选择、索引策略、迁移、连接池、serverless Postgres、Neon 分支、Prisma migration、Redis 缓存一致性、MongoDB 索引和聚合管道。	postgres-best-practices、neon-postgres、PostgreSQL Docs、Prisma Docs、Redis Docs、MongoDB Docs
07-AI与智能体开发	Agent 开发路线、LangChain、LangGraph	先建立 Agent 学习路线，再补 LangChain create_agent、tools schema、middleware、structured output；LangGraph StateGraph、reducers、Command、interrupt、checkpointer、PostgresSaver；RAG 需要检索评测。	project-development、tool-design、evaluation、langchain-*、langgraph-*、qdrant-search-quality、qdrant-monitoring
08-部署运维与容器	Docker、前端 Nginx 部署	Dockerfile 分层缓存、镜像安全扫描、Nginx 静态资源缓存、Brotli/gzip、SPA fallback、反向代理超时、Cloudflare/Netlify/Vercel/Pages 发布差异。	Docker Docs、Nginx Docs、cloudflare、wrangler、netlify-deploy、deploy-to-vercel
09-面试与资源	面试题、TS 实战项目地址	面试题要标注“考点来源”和“项目验证方式”，避免过时八股；GitHub 项目地址要定期检查维护状态、license、最近 commit 和可运行性。	source-driven-development、git-workflow-and-versioning
10-项目实战与产出	AI Prompt Workbench、组件工作台、任务平台、RAG 知识库、Agent Workflow、企业 Copilot、毕业项目	每个项目都要增加验收标准：功能路径、错误状态、性能预算、部署方式、可观测性、数据模型、权限模型、AI 评测集和回滚方案。	frontend-ui-engineering、evaluation、langchain-rag、langgraph-persistence、qdrant-*、ci-cd-and-automation
99-归档与重复文件	重复或归档资料	只保留历史参考价值，不再作为主学习路线事实来源；如果内容更完整，应迁移到主文档后注明来源。	documentation-and-adrs

---

4. 重点补强示例

4.1 前端 CDN 与构建产物

CDN 不是只给所有文件套一个域名。真实项目里要区分资源类型：

资源	是否适合 CDN	推荐策略
带 hash 的 JS/CSS chunk	适合	Cache-Control: public, max-age=31536000, immutable，构建产物不可覆盖同名文件。
index.html / SSR HTML	谨慎	通常短缓存或不缓存；如果缓存，要按登录态、地域、语言、实验分组设计 cache key。
图片、字体、视频	适合	图片可接入 Cloudflare Images、Netlify Image CDN 或对象存储 + CDN；字体需要 CORS 和 font-display。
API 响应	视业务而定	公共只读接口可 CDN 缓存；用户私有数据不要共享缓存，必须处理 Authorization、Cookie 和 Vary。
source map	不建议公开	生产环境如果需要上传到监控平台，避免直接暴露完整源码映射。

Vite 项目里，生产构建的静态资源根路径通常由 base 控制：

import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => ({
  base: mode === 'production' ? 'https://cdn.example.com/my-app/' : '/',
}))

Webpack 项目里，运行时加载异步 chunk、图片和字体时依赖 output.publicPath：

module.exports = {
  output: {
    filename: 'assets/js/[name].[contenthash:8].js',
    chunkFilename: 'assets/js/[name].[contenthash:8].js',
    publicPath: process.env.CDN_ORIGIN
      ? `${process.env.CDN_ORIGIN}/my-app/`
      : '/',
  },
}

Nuxt 项目要区分构建资源、SSR HTML 和 Nitro server routes。静态 _nuxt 资源可以长缓存，HTML 和 API 需要按渲染模式设计：

export default defineNuxtConfig({
  app: {
    cdnURL: process.env.NUXT_APP_CDN_URL || '',
  },
  nitro: {
    routeRules: {
      '/_nuxt/**': {
        headers: {
          'cache-control': 'public, max-age=31536000, immutable',
        },
      },
    },
  },
})

Netlify 可用 Netlify-CDN-Cache-Control 做 CDN-only 缓存，用 Netlify-Cache-Tag 做按标签清理；Cloudflare 要把 Cache Rules、Workers Cache API、R2/Pages/Workers 的职责分开；Vercel/Netlify/Cloudflare 的缓存语义不同，不能把一个平台的配置原样搬到另一个平台。

4.2 Vue / Nuxt 项目补强

Vue 文档后续应把“会写组件”升级为“可维护组件系统”：

• 业务组件默认使用 Vue 3、Composition API、<script setup lang="ts">。
• Pinia store 用于跨组件共享业务状态，组件内派生状态优先用 computed。
• Vue Router 守卫不要混用旧式 next() 和返回值模式，异步守卫要处理失败和重定向循环。
• 测试分层：纯函数单测、组件交互测试、关键路径 E2E，不用快照测试替代断言。
• Nuxt 要明确页面渲染模式：纯静态、SSR、ISR/SWR、server route、edge/serverless 部署目标。

4.3 Monorepo 与 CI/CD

Monorepo 文档应从“工具介绍”补到“任务图和发布边界”：

• pnpm workspace 负责包链接和依赖隔离，pnpm-lock.yaml 必须进入版本控制。
• Turborepo 的任务应定义 outputs 和输入环境变量，避免缓存命中错误。
• CI 至少包含 lint、typecheck、unit test、build；关键业务增加 integration/e2e、bundle budget、security audit。
• 发布要有 preview 环境、灰度或 feature flag、回滚指令和产物追踪。

示例 CI 检查顺序：

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build

4.4 性能、安全与可观测性

性能文档要用指标闭环：

• Core Web Vitals：LCP、INP、CLS。
• 构建产物：JS/CSS 体积、首屏关键资源、图片格式、字体加载、第三方脚本。
• CDN：cache hit ratio、TTFB、回源率、错误率、缓存清理时间。
• 服务端：p95/p99 延迟、错误率、饱和度、慢查询、队列积压。

安全文档要从威胁模型开始：

• 前端：XSS、CSP、依赖供应链、source map 暴露、敏感环境变量泄漏。
• BFF/API：SSRF、越权、CSRF、限流、参数校验、日志脱敏。
• CDN：缓存投毒、私有响应被共享缓存、错误的 Vary、开放重定向。
• AI：提示注入、工具越权、数据外泄、RAG 污染、模型输出未经验证即执行。

可观测性文档要把日志、指标、链路追踪连起来：

• 日志：结构化 JSON、trace id、用户/租户字段脱敏。
• 指标：RED（Rate、Errors、Duration）和 USE（Utilization、Saturation、Errors）。
• Trace：OpenTelemetry instrumentation，跨前端、BFF、数据库、队列、外部 API 传递上下文。
• 告警：基于用户影响，而不是只对 CPU 或内存做噪声告警。

4.5 LangChain / LangGraph / RAG

AI 文档要避免只讲“接一个模型”。真实项目至少需要：

• LangChain agent 使用工具 schema、middleware、structured output 和 recursion limit。
• LangGraph 用 StateGraph 表达复杂流程，列表状态要定义 reducer，持久化必须提供 checkpointer 和 thread_id。
• human-in-the-loop 用 interrupt() 和 Command(resume=...)，中断前的副作用必须幂等。
• 生产级记忆不要用进程内内存，LangGraph checkpoint 可用 PostgresSaver。
• RAG 不只存向量：要设计 chunk、metadata、embedding model、hybrid search、reranking、评测集和回归阈值。

RAG 评测最小闭环：

样本问题集 -> 标注相关文档 -> 检索 topK -> 计算 Recall@k / MRR / NDCG -> 生成回答 -> 人工或自动评测 -> 回归门禁

Qdrant 补强重点：

• 先用 exact search 判断是 embedding/data 问题还是 ANN 参数问题。
• exact search 也差，优先检查切片、embedding model 和数据质量。
• approximate search 差，才考虑 HNSW、quantization、payload index 等参数。
• 上线前要有 Prometheus/Grafana、健康检查、慢查询和 optimizer 状态监控。

4.6 PostgreSQL / Neon / Prisma

数据库文档应补足工程决策：

• Postgres 时间字段优先用 timestamptz 表达带时区时间。
• 除非长度本身是业务规则，否则文本字段优先考虑 text，长度约束用 check 或业务校验表达。
• 公开 ID 或客户端生成 ID 的场景可考虑 UUID，但要结合索引、排序和写入模式评估。
• serverless 环境要重点关注连接池；Neon、Vercel、Netlify、Cloudflare Workers 等平台的连接方式不同。
• Prisma migration 需要区分开发库、预发库、生产库，不要直接用同步 schema 的方式替代迁移审计。

---

5. 每篇学习文档建议新增的“真实性栏”

建议后续给重要文档增加这个小节：

## 真实性与版本说明

- 最后核验日期：YYYY-MM-DD
- 主要版本：Vue x / Vite x / Node x / PostgreSQL x
- 官方资料：
  - ...
- 本文示例适用范围：
  - ...
- 不适用或需谨慎：
  - ...

项目实战类文档建议增加：

## 验收标准

- 本地可运行：安装、启动、构建命令完整。
- 测试可验证：至少覆盖核心业务路径。
- 部署可复现：Vercel/Netlify/Cloudflare/Nginx/Docker 任一方式可复现。
- 性能有预算：JS/CSS 体积、LCP/INP/CLS、API p95。
- 安全有边界：认证、授权、输入校验、密钥、日志脱敏。
- 可观测：日志、指标、trace、告警或故障排查路径。

---

6. 官方资料入口

主题	官方资料
Vue	Vue Docs
Vue Router	Vue Router Docs
Pinia	Pinia Docs
Nuxt	Nuxt Docs
Nitro	Nitro Docs
Vite	Vite Docs
Webpack	Webpack Docs
Vitest	Vitest Docs
pnpm	pnpm Docs
Turborepo	Turborepo Docs
Tailwind CSS	Tailwind CSS Docs
CDN / HTTP	MDN HTTP Caching
Cloudflare	Cloudflare Developers
Netlify	Netlify Docs
Vercel	Vercel Docs
Web 性能	web.dev Core Web Vitals
Chrome 性能工具	Chrome DevTools Performance
安全	OWASP Top 10
LLM 安全	OWASP Top 10 for LLM Applications
可观测性	OpenTelemetry Docs
LangChain	LangChain Docs
LangGraph	LangGraph Docs
Qdrant	Qdrant Docs
PostgreSQL	PostgreSQL Docs
Prisma	Prisma Docs
Docker	Docker Docs
Nginx	Nginx Docs

---

7. 后续更新优先级

1. 前端 CDN 与 HTTP 缓存相关文档：已新增专门文档，应继续补 Cloudflare/Netlify/Vercel 的平台差异和实际响应头排查。
2. Vue / Nuxt / Vite / Webpack 文档：补版本说明、框架配置、测试和构建产物策略。
3. 前端性能、安全、可观测性文档：补可执行审计流程、指标阈值、日志/trace 示例、风险清单。
4. LangChain / LangGraph 文档：补 create_agent、middleware、StateGraph、checkpointer、human-in-the-loop 和 RAG 评测。
5. PostgreSQL / Prisma / Neon 文档：补连接池、迁移、索引、serverless 数据库连接差异。
6. 项目实战文档：每个项目增加验收标准、部署路径、测试路径、性能预算和故障排查路径。

---

8. 使用方式

更新任意学习文档时按这个顺序执行：

确定文档主题
-> 查看本索引对应目录的补强点
-> 选择相关 skill 作为检查清单
-> 打开官方文档核验版本和配置
-> 写入具体项目落地示例
-> 标注适用范围、风险和验收方式
-> 运行或说明无法运行的验证步骤

如果一个知识点无法找到官方资料、源码、标准或可复现实验支撑，就不要写成确定结论。可以写成“待验证假设”或“需要按项目环境验证”。