# 阅读指南与学习路线

## 这本手册帮助你完成什么

**Node 与 Electron 当前从零开始，请先打开[专门学习路线](node-electron-roadmap.html)。** 新增的 Node 机制课程与 Electron 桌面课程从运行环境讲起，保留你已有的 JavaScript 和 Vue 经验，按“为什么需要 → 如何工作 → 完整实验 → 错误排查 → 练习与验收”逐步展开。Node 的讲解参考《深入浅出 Node.js》重视原理的取向，用当前官方资料核对行为；Electron 最后附[完整 Vue 桌面笔记项目](electron-project.html)。

你的目标是以前端为专业主轴，完成一个 AI 产品从需求、交互、接口、数据到部署的交付。你已经有多年前端经验，不需要从变量、循环和组件入门重新学起；需要补的是运行环境、可信边界、持久化、模型不确定性，以及上线后的反馈闭环。

贯穿手册的产品是一个“团队知识与任务助手”：用户登录后上传资料、提出问题、查看引用，也可以让助手查询业务数据并生成待确认的操作。它覆盖普通 Web 应用与 AI 应用共同需要的基础，且能逐步增加难度。每章示例也可以单独运行；它们不是把文件按顺序粘贴就自动组成一套生产系统的代码仓库。

AI 应用开发与 AI 辅助开发是两种同时需要练习的能力。前者把模型的生成、检索与工具使用能力变成产品；后者帮助你阅读代码、制定方案、编写实现和验证结果。使用 AI 是正常工作方式。学习的终点是你能解释设计、判断输出和处理故障，而不是脱离工具背下全部 API。

## 能力导图：以前端为主轴完成 AI 产品

这条路线的落点是 **AI 应用工程 + 全栈交付**。你需要会把模型能力接入真实产品，并负责界面体验、接口、数据和故障处理。模型训练、分布式训练与论文复现属于另一条需要额外投入的方向，暂时不作为完成这条路线的前提。未来项目明确需要时，再从数学、Python 与模型机制继续深入。

```text
你的已有基础：9 年前端开发经验
│
├─ 主轴：前端与 AI 协作 · L3 能负责
│  ├─ 需求 → 字段映射 → 接口契约 → 可验收方案
│  ├─ 消息状态 / 取消重试 / 流式解析 / 多请求竞态
│  ├─ Markdown安全 / 引用呈现 / 长内容性能 / 无障碍
│  └─ 给AI上下文 / 审查改动 / 设计验证 / 独立接管排障
│
├─ 全栈后端 · L2 能交付
│  ├─ Node运行时 / 异步控制 / HTTP / 文件处理
│  ├─ 数据建模 / SQL / 索引 / 事务 / 并发一致性
│  └─ 登录会话 / 资源权限 / 后台任务 / 幂等与恢复
│
├─ Electron桌面 · 从零建立 L2 能交付
│  ├─ 主进程 / 渲染进程 / preload隔离上下文 / 窗口生命周期
│  ├─ 受控IPC / 文件与本地数据 / 后台任务 / Vue桌面集成
│  └─ 调试验证 / 构建与打包 / 签名与更新原理 / 完整笔记实验
│
├─ AI应用核心 · L2 能交付
│  ├─ 模型机制与限制 / HTTP接入 / 上下文 / 结构化输出
│  ├─ 文档处理 → 分块 → 检索 → 证据 → 引用回答
│  └─ 工具调用 / 受控工作流 / Agent循环 / MCP边界
│
├─ 质量与运行 · L2 能交付
│  ├─ 固定评测集 / 指标 / 回归与失败分析
│  ├─ 日志追踪 / 延迟 / 费用 / 输入与权限安全
│  └─ 本地容器 / 配置 / CI / 备份恢复 / 发布与回滚原理
│
└─ 补充能力 · 先理解，再按需求深入
   ├─ Python与数据处理：能写脚本、清洗数据、运行评测
   ├─ 数学：理解向量、概率、相似度与指标含义
   └─ 多模态 / 本地模型 / 微调：会判断用途、条件与代价
```

### 每个模块到底学到哪里可以暂时停

| 能力 | 第一阶段具体交付标准 | 暂不要求 | 进入章节 |
| --- | --- | --- | --- |
| 系统理解 | 画出身份、资料、模型与写操作经过的边界，解释失败恢复 | 一开始拆微服务 | [系统边界](system-boundaries.html) |
| 契约设计 | 校验外部数据，区分缺失/null，定义错误与版本冲突 | 复杂类型体操 | [接口契约](contracts.html) |
| 需求设计 | 从界面字段映射到API与持久化规则，列出异常验收 | 巨型方案文档 | [需求与方案](requirements.html) |
| AI前端 | 流式展示、取消重试、旧请求隔离、正确引用与安全渲染 | 为AI换前端框架 | [交互状态](ui-state.html)、[流式实验](streaming-ui.html) |
| Node运行时 | 理解模块、异步、字节、流和进程；能解释并修改完整实验 | V8内核与C++扩展开发 | [Node零基础](node-start.html) |
| Node服务 | 写出带校验、错误处理和资源清理的HTTP接口 | 背完所有核心模块 | [小型服务实战](node-build-service.html)、[HTTP API](http-api.html) |
| Electron | 页面通过受控IPC操作本地数据，能排查窗口与主进程问题 | 第一阶段做插件平台或在线发布 | [桌面运行模型](electron-mental-model.html)、[笔记项目](electron-project.html) |
| 数据库 | 设计关系、写参数化查询、用事务和约束保护并发结果 | 自己实现数据库内核 | [数据建模](data-model.html)、[事务](transactions.html) |
| 身份与权限 | 用两个用户证明资源隔离，后台与工具同样检查权限 | 手写密码学算法 | [会话](auth-session.html)、[授权](authorization.html) |
| 模型接入 | 真实调用一个接口，处理超时、限流、格式与费用 | 同时接所有供应商 | [模型HTTP](model-http.html) |
| RAG | 解释资料生命周期，分别诊断检索遗漏和生成错误 | 先买复杂检索平台 | [入库](doc-ingestion.html)、[回答](rag-answer.html) |
| 工具与Agent | 参数校验、确认、幂等、步数与预算上限、恢复查询 | 多Agent作为默认方案 | [工具调用](tool-calling.html)、[工作流](workflow-agent.html) |
| 质量 | 用固定问题集比较改动，报告错误类型与成本 | 只凭个人感觉打分 | [评测](evaluation.html) |
| 运行维护 | 能在本机或容器启动，定位日志，备份并实际恢复 | 先建设大型运维平台 | [运行部署](deploy.html)、[CI与备份](ci-backups.html) |
| Python | 能读写数据、处理错误、运行批量评测脚本 | 重学一遍基础编程 | [Python](python-basics.html) |
| 数学与训练 | 能解释指标和资源取舍，判断是否需要训练 | 第一阶段研究训练框架 | [数学](math-basics.html)、[本地与微调](local-finetune.html) |

这里的“暂时停”表示具备推进项目的最低能力，不是永远不深入。遇到查询变慢，再学执行计划与索引；遇到租户权限变复杂，再深化授权模型；模型评测发现特定模式无法解决，再研究提示、检索或微调哪一层真正对应问题。技术学习由可观察的需求牵引，避免在还没有产品问题时无限扩充工具清单。

### 怎样利用已有经验，又不跳过陌生领域

你已有的需求理解、交互设计、类型约束和浏览器排障经验可以直接复用。需要重新验证的是服务器事实：谁真正控制权限、写入是否已经发生、进程退出后哪些状态还在、请求取消是否影响外部任务。熟悉JavaScript能减少语言成本，但不会自动带来数据库与分布式执行经验。

可以让AI承担阅读官方文档、搭建小实验、生成实现和解释报错。你保留四项责任：判断需求是否准确，审查数据与权限边界，选择能够揭示错误的验证，接管失败后的排查。用AI并不降低L2/L3标准；它改变达到标准时使用的工具，不改变最终需要承担的工程判断。

### 以三个作品检查进展

第一件作品是没有模型的文档管理：上传、归属、处理状态、删除、重启恢复。第二件是可恢复的AI问答：流式、取消、错误、持久化、成本。第三件是知识与任务助手：资料引用、权限检索、用户确认、幂等执行和评测报告。三件可以是同一个仓库的三个阶段，不需要反复重搭项目。

每一阶段都保留正常案例和失败案例。能够演示“两个用户互相不能读取”“文档删除后不可检索”“任务成功但响应丢失可以查回”，比单纯展示聊天动画更能检验全栈能力。运行环境可以始终在本机，不要求把学习站点或练习项目发布到公网。


## 掌握程度怎么判断

| 等级 | 你需要做到 | 不能用什么代替 |
| --- | --- | --- |
| L1：理解 | 解释用途、机制、限制，知道何时需要它 | 记住缩写或看完视频 |
| L2：能交付 | 借助文档与 AI 做出真实功能，检查结果，处理常见错误 | 只运行别人准备好的顺利案例 |
| L3：能负责 | 做方案取舍，处理复杂问题，对性能、质量和维护负责 | 只会熟悉的一种实现方式 |

前端与 AI 协作作为 L3 主轴；Node、数据库、模型接入、RAG、部署以 L2 为第一阶段目标；数学和模型训练机制先到 L1。等级是学习目标，不是行业统一职级。你可以先对每章做自测，已经能完成验收的章节快速通过，把精力放在自己无法解释的问题上。

例如，“会事务”不是会输入 BEGIN，而是能说明为什么两次写入必须一起成功，为什么事务要使用同一个连接，失败后如何回滚，以及并发请求可能造成什么结果。“会 RAG”不是会调向量库，而是能区分检索遗漏和生成错误，并用固定问题集验证修改。

## 推荐的阅读顺序

1. 先读学习方法、系统边界、环境与契约，建立共同语言。
2. 学 Node、HTTP、数据库、登录和权限，做出普通全栈版文档管理。
3. 学模型接口、上下文、结构化输出与流式前端，增加 AI 对话。
4. 学资料入库、检索、引用与评测，做出知识库版。
5. 学工具调用、工作流、权限与任务恢复，增加受控的业务动作。
6. 每阶段都练部署、日志和测试；遇到数据处理需求再补 Python。

你也可以先完成一个离线流式示例感受产品形态，再返回后端基础。不要把“先学基础”理解为几个月都不能做产品；每学一个基础，就让它承担一个实际任务。节点顺序由依赖决定，推进速度由验收决定，日历只是提醒。

## 每章怎么使用

第一遍只回答三个问题：它解决什么问题？输入与输出是什么？失败时谁负责处理？然后读代码，预测运行结果，再执行。看到陌生 API 时，先读参数、返回值和异常说明；不要让 AI 直接把整章压缩成一段看似熟悉的术语。

第二遍完成练习。先隐藏参考答案，记录你的方案与疑问。允许让 AI 帮你解释报错，但请给出真实命令、实际结果和预期结果。完成后至少改变一个条件：空输入、并发、权限不符、网络中断、超时或重复请求。顺利路径证明功能存在，失败路径帮助你理解边界。

第三遍在自己的项目中复用，再写一小段学习记录。下面是可复制的记录格式；它是 Markdown 文本，不需要执行。

```markdown
# 一次可验证的学习记录

- 要解决的问题：同一任务重复点击后创建了两条记录。
- 原因假设：前端禁用按钮不能阻止网络重试或多个客户端。
- 本次方案：服务端使用用户范围内的幂等键和唯一约束。
- 成功证据：连续提交两次，只产生一条任务记录。
- 失败证据：相同键但不同内容返回明确冲突。
- 仍未验证：两个进程同时请求时的行为。
- 下一步：加入并发集成测试，再确认数据库约束。
```

这份记录的用途是把“感觉会了”转换为证据。它也能成为你给 AI 的上下文：已确认的事实、当前假设和未解决的问题被分开了，AI 就不容易把猜测当作前提继续写代码。

## 示例环境与真实性边界

Node 示例以支持现代 Web API 的 Node 22.22+ 或 Node 24 环境为基线，主要使用 ESM 的 `.mjs` 文件；Python 标准库示例使用 Python 3.11+，特殊要求以章节说明为准。第三方依赖和供应商 API 会变化，复现实验时应固定自己的依赖版本和模型配置。

标注“离线模拟”的例子使用确定性数据，适合学习控制流和测试，不代表真实模型的效果。标注“需要服务”的例子需要你自行启动数据库或配置模型凭据。文档引用官方资料核对接口与机制，但没有把所有外部数据库、云平台和付费模型组合逐一联调。不要把教学用内存数据、硬编码演示用户或日志输出原样当作生产实现。

站点本身是静态文档，可以离线阅读；运行文档里的数据库或模型程序是另外一件事。搜索、代码复制和目录导航都在浏览器本地完成。部分浏览器在直接打开本地文件时限制剪贴板权限，复制失败时可以选中代码手动复制。

## 练习：建立自己的起点

从导图中选三个你认为已经掌握的模块，分别写出一个真实交付例子、一次排错经历、一个还解释不清的问题。再选两个最薄弱的模块，安排一个能在本地完成的小实验。

<details>
<summary>参考做法与判断依据</summary>

“熟悉 Vue”可以进一步落到“能解释流式更新为何造成频繁渲染，并比较逐 token 更新和按帧合并更新”。“学过数据库”可以落到“能用两个连接重现重复写入，再用唯一约束修复”。对没有证据的能力先标记为待验证，不必因为工作年限要求自己什么都会。

</details>

## 本章验收与自测

- 能说清自己要交付哪类 AI 产品，以及哪些能力继续作为专业主轴。
- 能区分 L1、L2、L3，并为一个 L2 模块写出可执行的验收条件。
- 能区分学习记录里的事实、假设和下一步实验。

**问：会让 AI 生成一套接口，算达到 L2 吗？** 答：还需要你能解释权限与数据规则，验证输出，并处理常见错误。

**问：必须先系统学完机器学习吗？** 答：这条应用路线先学与当前设计有关的概念；训练工程需要另一套更深入的理论和实践。

**问：是不是每章都要按同样时间学习？** 答：不需要。按前置依赖与验收结果调整，熟悉的内容快速通过，无法定位故障的内容增加实验。

## 官方参考与延伸

- [Vue 中文指南：学习文档的组织参考](https://cn.vuejs.org/guide/introduction)
- [Node.js Learn](https://nodejs.org/en/learn)
- [Anthropic：工作流与 Agent 的设计原则](https://www.anthropic.com/engineering/building-effective-agents)