Appearance
Final · 最终项目交付
产出：一个本地优先、可安装、可运行、可展示、可写进简历的智能知识库 Agent。
basic/project 不属于新的模块编号。它位于模块 8 之后、模块 9 之前，是这门课的独立收尾层。
模块 1-8 负责让你逐步掌握 LLM / RAG / Agent 的核心能力；到了 basic/project，目标从“课堂 Demo”切换为“最终交付物”。
也就是说：
- 模块 1-8：学能力
basic/examples：看每节课的单点 Demobasic/project：把能力收敛成一个可交付的本地工具- 模块 9：把这个工具包装成简历项目和面试表达
为什么不再保留 v1-v8
早期课程结构同时保留了课内 Demo、v1-v8 主线版本和最终项目，维护成本高，也容易让学员困惑“到底该跑哪一套代码”。
现在基础课收敛为两层：
basic/examples：每节课的最小可运行示例。basic/project：基础课最终成品。
basic/project 不再强调每一课的目录增量，而是把前面学过的能力重新组织成一个本地优先的知识库 Agent：
- 有自然语言对话和
/指令两种交互方式 - 有多知识库管理，而不是只围绕一个临时 Demo 知识库
- 有本地持久化，重启后知识库、会话和历史仍然保留
- 有文档导入、检索、问答、摘要、写作等完整工作流
- 有 README、配置、数据目录和评测脚本，适合课程收尾、录屏和项目包装
一句话概括：
basic/examples：解释每课能力basic/project：课程主线的最终交付工具
最终项目架构
basic/project 的架构可以分成五层：
final 最终项目架构：五层分组 + 内部模块
用户入口
自然语言请求让 Agent 自主判断意图
Slash 指令/add、/ask、/write、/status
本地 REPL课程演示和日常使用入口
↓
本地交互层
命令解析识别 / 指令和参数
会话控制创建、切换、恢复会话
结果输出把工具结果和模型回答展示给用户
Agent 编排层
System Prompt角色、规则、输出格式、安全边界
ReAct + Tool Call多步推理和工具执行
Todo / SubAgent / 写作流规划、委派和多 Agent 协作
↓
核心能力层
知识库管理create / use / list / remove / status
摄入链路文本、URL、文件、目录 → 切块 → Embedding
检索与问答BM25/FTS5 + 向量检索 + RRF + 引用来源
内容任务摘要、写作、长期记忆读写
↓
质量与评测层
输出约束
重试 / 缓存
成本统计
检索评测bm25 / vector / hybrid
结果评测ask / summarize / write
本地存储层
~/.kb/config.json当前知识库和全局配置
知识库 .sqlite文档、分块、FTS5、sqlite-vec、model_calls
sessions.sqlite + logs会话历史、计划、结构化日志
外层看五层职责，内层看每层包含的具体模块；这就是 final 从课程能力到最终工具的收口方式。
这套分层的重点不是“代码目录好看”，而是让最终工具具备清楚的边界：
- 交互层负责接收输入和展示输出
- Agent 层负责判断要不要调用工具、调用什么工具、是否需要多步执行
- 核心层负责稳定的业务能力，不依赖具体入口
- 质量层负责让结果可检查、成本可追踪
- 存储层负责本地优先和可恢复
因此，final 后续如果要扩成 HTTP 服务、桌面壳或 Web UI，核心逻辑不需要重写，只需要替换交互入口。
一次请求怎么流动
以“把 docs 目录导入知识库，然后问一个问题”为例，final 的运行链路是：
- 用户输入自然语言，或者直接输入
/add docs - 交互层把请求交给命令处理器或 Agent
- Agent 根据工具描述选择
addDocument - 核心层读取文件、解析文本、切块、生成 Embedding
- 存储层把文档、分块、向量写入当前知识库的
.sqlite - 用户提问时，检索层同时跑 BM25/FTS5 和向量检索
- 系统用 RRF 融合两路结果，组成带来源编号的上下文
- 模型基于上下文生成回答，回答中保留
[1]、[2]这样的引用 - 调用记录、token、成本和日志写入本地
这个流程把课程中的 RAG、Tool Call、Agent、质量控制和本地存储串成了一个完整产品闭环。
用到了哪些课程知识点
basic/project 不是另起炉灶，而是把模块 1-8 的核心知识点压缩进一个工具形态。
| 课程模块 | final 中的落地方式 | 说明 |
|---|---|---|
| 模块 1：LLM Chat | 对话式交互、多轮历史、上下文窗口、历史压缩 | 模块 1 讲“对话为什么能连续”，final 进一步把会话做成本地持久化 |
| 模块 2：Prompt | 结构化 System Prompt、拒答规则、输出格式、安全边界 | final 部分回收 Prompt System 思路，但没有完整落地环境上下文注入 |
| 模块 3：RAG 基础 | 文档导入、切块、Embedding、向量检索、RAG 问答 | 课程可用内存或 pgvector 讲通用方案，final 为本地工具切到 SQLite + sqlite-vec |
| 模块 4：RAG 进阶 | BM25/FTS5、向量检索、混合检索、RRF、引用来源、离线评测 | 这是 final 中最完整落地的一组 RAG 进阶能力 |
| 模块 5：Agent | Tool Call、ReAct 多步执行、SubAgent 委派 | final 允许 Agent 根据自然语言自主调用知识库、导入、摘要、写作等工具 |
| 模块 6：Memory | remember/recall 长期记忆、/plan 任务计划、会话历史持久化 | final 采用工具化记忆，不是每轮自动注入所有记忆 |
| 模块 7：Multi-Agent | 写作工作流中的 Researcher / Writer / Reviewer / Editor 编排 | final 不是所有任务都默认 Multi-Agent，而是在写作场景专项启用 |
| 模块 8：Production | 重试、基础缓存、模型级 Fallback、调用统计、成本估算、本地日志、质量评测 | final 选择符合本地优先工具定位的工程能力落地 |
需要注意：课程里有些内容是“生产设计认知”，不代表 final 必须完整实现。例如完整语义缓存、环境上下文注入、完整 RAGAS 指标体系，都属于后续增强方向。
哪些是课程知识点之外的东西
basic/project 还加入了一批课程模块 1-8 没有单独展开的产品化能力。这些不是新的 AI 原理，而是把项目做成“可交付工具”必须补上的工程工作。
| 产品化能力 | 在 final 中解决什么问题 | 为什么不放进前 8 个模块讲 |
|---|---|---|
| 本地交互入口 | 让用户可以通过自然语言和 / 指令稳定使用工具 | 前 8 个模块重点是学 AI 能力，不是设计最终工具入口 |
| 多知识库管理 | 支持创建、切换、删除多个知识库 | 模块 3 只需要讲清一个知识库如何问答 |
| 多会话持久化 | 保留不同会话、历史、计划和当前知识库 | 模块 1 讲上下文原理即可，产品化留到 final 收口 |
| 双轨历史 | 压缩后的历史给模型，完整历史给用户查看和恢复 | 这是最终工具体验问题，不是基础 LLM 原理 |
| 本地数据目录 | 把配置、知识库、会话和日志统一放到 ~/.kb/ | 服务于本地优先交付，不适合作为早期课程负担 |
| 核心逻辑分层 | 核心能力和交互入口分离，后续可扩展到 HTTP / Web / Desktop | 属于交付架构，不是单个 AI 知识点 |
| 交付物标准 | README、环境变量、数据目录说明、评测脚本、运行命令 | 服务于课程收尾、录屏和简历包装 |
这些能力的作用是把“能跑的 Demo”变成“别人拿到也能理解、安装、运行和展示的项目”。
哪些课程内容没有完整进入 final
课程允许讲得比 basic/project 更宽，但最终交付页必须把边界说清楚。
| 知识点 | 当前 final 状态 | 正确理解 |
|---|---|---|
| Rerank | 未并入主实现 | 模块 4 可作为进阶增强，不是 final 主线门槛 |
| HyDE | 未并入主实现 | 适合写成后续优化方向 |
| 完整 RAGAS 指标体系 | 未作为产品心智落地 | final 更强调检索策略对比和最终结果评测 |
| 自动模型级 Fallback | 已支持 FALLBACK_* 配置 | 最少配置 FALLBACK_MODEL 即可启用；未单独配置的 provider、API key、base URL 会复用 CHAT_* |
| 完整语义缓存 | 当前是基础缓存，不是 embedding 相似度缓存 | 模块 8 讲设计思路，final 先做轻量落地 |
| 每轮自动记忆注入 | 未完整落地 | final 通过 remember/recall 工具让 Agent 按需读写记忆 |
| 全局默认 Multi-Agent | 未落地 | final 只在写作工作流中启用多 Agent 编排 |
| 完整环境上下文注入 | 未完整落地 | 模块 2 作为 Prompt System 认知保留 |
这不是课程和项目冲突，而是取舍：课程要帮你理解完整能力版图，final 要交付一个边界清楚、能稳定运行的本地工具。
学这一步该怎么看
推荐顺序：
- 先按模块阅读基础课正文。
- 需要观察单点能力时，运行
basic/examples里的课内 Demo。 - 最后进入
basic/project/README.md，按最终工具方式运行和体验。
如果你是为了做项目包装：
- 对外讲述时，以
basic/project作为最终交付物 - 对内解释能力来源时，用模块 1-8 说明项目为什么会长成这样
- 遇到课程讲了但
basic/project没做全的内容，统一说成“生产增强方向”，不要说成“当前项目已经完整支持”
与模块 9 的关系
模块 9 不是继续开发新功能，而是把 basic/project 包装成简历项目、面试项目和录屏 Demo。
你最终要表达的是：
- 我理解 LLM / RAG / Agent 的核心能力
- 我能把这些能力一步步并入一个主线项目
- 我能把课程内 Demo 收敛成一个有真实交互、真实存储、真实评测、真实交付边界的工具
这就是 final 在整门课里的位置。