基于 CC 的外挂 RAG 中文教程（目录与导航）
本教程默认约定：CC = Claude Code（Claude 的命令行/代码智能体）。
说明：在中文语境里 CC 也常被用来指 Common Crawl（公开网页抓取语料）。如果你说的“CC 数据”指的是 Common Crawl，请直接走本目录中的 「可选路线：Common Crawl 作为外挂语料源」 章节（会把 Common Crawl 的数据结构与下载/解析细节讲全）。
你将得到什么（最终产出）
读完并按章节完成实操后，你将拥有：
- 一个可运行的 “外挂 RAG 服务”（本地优先），能把检索到的片段按可控格式喂给 CC 使用
- 一套从 原始语料 → 清洗/切分 → 向量化/索引 → 检索/重排 → 组装上下文 的完整流水线
- 一份 “CC 数据（上下文/工具调用/扩展点）完整拆解”：包括你在集成时会遇到的字段、边界与坑
- 一套可复用的 Prompt/用格式/证据约束模板，降低幻觉与“胡编引用”
- 一套 评估与调优方法：可量化对比不同切分、召回、重排与上下文拼装策略
适合谁看
- 正在使用或计划使用 Claude Code（CC） 做日常开发，希望让它“能看懂更多资料/更多仓库/更多内部文档”
- 想把 RAG 做成 外挂：不绑死在某一家平台内置知识库，便于本地化、私有化与可控
- 想搞清楚 “CC 到底把什么数据传给扩展/工具？我能在哪里插入检索？” 的实现派
阅读路线建议
- 最快落地路线（先跑起来）：Chapter 1 → 2 → 4 → 9 → 10 → 11
- 数据细节党（把 CC 数据吃透）：Chapter 1 → 2 → 3 → 4 → 8 → 9 → 10
- 更强检索效果（追指标）：Chapter 5 → 6 → 7 → 8 → 11 → 12
- 要用 Common Crawl（CC 数据=Common Crawl）：Chapter 13 → 14（可选）→ 6 → 7 → 8
全目录（Table of Contents）
第 1 章：总览——什么是“基于 CC 的外挂 RAG”，以及我们要做的系统长什么样
文件：chapter1.md
- 外挂 RAG 的边界：什么交给 CC，什么交给外部检索服务
- 端到端数据流（Query → Retrieve → Rerank → Context Pack → CC）
- 你将实现的“最小可用版本（MVP）”功能清单
- 成本、隐私与可控性：为什么要外挂，而不是把文档全贴进话
第 2 章：CC 的工作方式与扩展面概览（你可以“挂”在哪里）
文件：chapter2.md
- CC 的典型工作流：读仓库/执行工具/生成修改/迭代
- 常见扩展/集成位置（以“可插拔”为核心的思路）
-
“外挂 RAG”最常用的两种集成形态：
- 形态 A：把 RAG 暴露成 工具/服务，由 CC 调用
- 形态 B：把 RAG 做成 命令/工作流，由人触发或钩子触发
- 不同形态的优缺点与适用场景
第 3 章：CC 数据完整拆解（重点章节）
文件：chapter3.md
本章专门回应你的要求：“要包含 CC 数据的完整细节”。
目标是让你在做集成时，清楚“哪些数据在哪里出现、长什么样、该如何保存/裁剪/脱敏/缓存”。
- CC 的“上下文”构成拆解：对话上下文、项目上下文、工具输出、记忆文件、指令层
-
与外挂 RAG 相关的关键数据面：
- 用户 Query 的来源与改写
- CC 提供/可获得的文件路径、目录结构、选中文件（若有）
- 工具调用的输入/输出载荷（payload）如何影响检索
- 会话级/项目级的持久化信息（例如“项目记忆”类文件）
-
数据治理：
- 哪些字段属于敏感信息，如何做脱敏/过滤
- 缓存键怎么设计，如何避免“拿错会话的数据”
- 日志应该记录什么，才能复现问题且不泄密
-
本章结尾提供：
- 字段清单检查表
- 示例载荷模板（可直接复制）
- 常见坑位与规避策略
第 4 章：外挂 RAG 的架构设计——模块划分、接口契约与时序
文件：chapter4.md
- 组件拆分：Ingest / Index / Retrieve / Rerank / Pack / Serve
- “接口契约”怎么定：输入、输出、错误码、可观测字段
- 文档片段（Chunk）与元数据（Metadata）的标准化格式
- 引用（Citations）策略：如何让 CC 输出可追溯证据
第 5 章：数据摄取——从代码/文档到可检索语料（不止“读文件”）
文件：chapter5.md
-
数据源分类：
- 仓库源码、README/设计文档、Wiki、Issue、API 文档、日志/FAQ
-
清洗与解析：
- 语言检测与编码修复
- 去噪：目录排除、构建产物排除、重复文件处理
- 元数据策略：路径、模块、提交信息（可选）、时间戳、标签
第 6 章：切分（Chunking）与索引策略——RAG 好坏的分水岭
文件：chapter6.md
- 切分目标：可召回、可理解、可引用
-
常见策略：
- 固定长度 vs 结构化切分（标题/段落/代码块）
- 代码切分（按函数/类/文件结构）
- 重叠窗口（overlap）的取舍
- 元数据与 chunk 的绑定方式（强烈影响检索与引用）
- 质量控制：过短/过长/重复 chunk 的治理
第 7 章：向量化与向量库——Embedding 选择、存储结构与成本控制
文件：chapter7.md
- Embedding 的选择维度：语言、代码、成本、延迟、可部署性
- 向量库的选择维度：本地/云端、过滤能力、混合检索、可维护性
-
索引组织：
- 单库多集合 vs 多库分域
- 版本化索引（便于回滚与对比实验）
- 批处理与增量更新：如何只更新变更部分
第 8 章：检索与重排——从“能搜到”到“搜得准”
文件：chapter8.md
-
召回策略：
- Dense / Keyword / Hybrid
- Query 改写、扩展、意图识别
-
重排（Rerank）：
- 何时需要 rerank
- rerank 的输入拼装与截断策略
- 缓存与防抖：降低重复检索成本
- 失败兜底：无结果/低置信度时怎么提示 CC
第 9 章：与 CC 的集成实践——把外挂 RAG 变成 CC“可用的能力”
文件：chapter9.md
- 集成方式对照表：工具化 / 命令化 / 工作流化 / 钩子化
-
“检索工具”的数设计：
- query、top_k、filters、domain、repo_path、language…
-
“证据返回”的标准结构：
- chunk 内容、来源、路径、行号/段落、置信度、摘要
-
限制与原则：
- 不把整库一次性塞进上下文
- 强制引用、强制基于证据回答的提示策略
第 10 章：参考实现（端到端）——从 0 写一个最小可用外挂 RAG
文件：chapter10.md
- 项目脚手架（目录结构建议）
- Ingest 脚本（生成 chunk + metadata）
- Index 构建（批量 embedding + upsert）
- Retrieve API（检索 + 可选重排）
- Context Pack（把结果打包成 CC 易用的上下文块）
第 11 章：质量评估与回归测试——让 RAG 可量化、可迭代
文件：chapter11.md
- 构建评估集：问题、期望证据、期望答案要点
- 指标：Recall@K、MRR、nDCG（按你的目标裁剪）
- “引用正确性”评估：引用是否真包含答案依据
- 回归：切分/embedding/检索策略变化后如何自动对比
第 12 章：安全、权限与合规——外挂 RAG 最容易踩雷的地方
文件：chapter12.md
可选路线：当你说的“CC 数据”指 Common Crawl（公开网页语料）
第 13 章：Common Crawl 数据全解——格式、索引与下载策略（细节拉满）
文件：chapter13.md
- Common Crawl 的数据形态：WARC/WAT/WET（分别是什么、用来干什么）
- Crawl 批次（crawl id）的选择：新鲜度 vs 稳定性
- 通过索引定位 URL/域名数据：CDX/索引查询思路
- 下载与成本：断点续传、并行、去重、冷热分层
- 提取与清洗：HTML → 可用文本、语言过滤、反爬噪声处理
- 版权/合规注意事项（在“用作外挂检索”场景下的风险点）
第 14 章：用 Common Crawl 做外挂语料——从海量网页到可检索知识库
文件：chapter14.md
- 域名白名单/黑名单与主题过滤
- 高质量页面筛选（启发式与规则）
- 去重与近重复（SimHash/MinHash 思路）
- 构建可追溯引用：URL、抓取时间、段落定位
附录
第 15 章：速查表与模板合集（CC 数据字段清单 / 返回结构 / Prompt 模板）
文件：chapter15.md
- CC 数据字段速查表（你做集成一定用得上）
- 检索结果返回 JSON 模板（含引用字段）
- “仅基于证据回答”提示模板（多版本）
- 常见错误与排查清单（从日志定位到修复）
约定（写在最后，避免踩坑）
- 本教程强调“外挂”：检索、索引、缓存、权限都应由你掌控，而不是把所有东西塞进模型上下文
- 所有示例默认“可追溯引用”：没有证据就承认不知道，不鼓励编造
- 你可以把实现做成本地优先，也可以扩展到团队服务化；目录章节会同时覆盖两种思路