CHAPTER 00 · 导读
一次范式转换：从“写代码的人”到“定义并验证系统的人”
你已经会编程。这套教程不教你“编程”，而是帮你把已有的工程直觉迁移到 TypeScript 全栈生态，同时学会用 Coding Agent（编码智能体）替你写大部分代码，而你牢牢掌控方向和质量。
- 说出转到 TS 全栈时真正变化的三个默认假设，而不只是“语法不同”。
- 用“原理 / 会用 / 知道”三档，判断任意一个新技术名词该学到多深。
- 理解贯穿全书的练习项目 LinkNote，并为自己选一条学习路线。
一个你很可能会遇到的困惑
一个写了多年后端的工程师，打开一个由 Agent 生成的 Next.js 项目。每一行语法大致都认得：const、async、函数、对象……但他依然说不清：这个文件里的代码到底在服务器上跑，还是在用户浏览器里跑？为什么改了一个变量，页面没有更新？为什么 Agent 说“这里要加 'use client'”？
答案方向：卡住他的不是语法，而是三个“默认假设”被悄悄换掉了。只要把这三个假设换过来，大部分困惑会同时消失：
- 代码跑在哪里，不再是一个固定答案。在 Java 或 Go 的世界里，你的代码跑在“服务器”上，浏览器只是显示结果。在 TS 全栈世界里，同一种语言、同一个项目、甚至同一个文件夹中的代码，有的在构建时运行，有的在服务器上运行，有的被打包发给浏览器运行，有的跑在全球几百个边缘机房里。你必须随时知道“这段代码的运行位置”，因为它决定了能访问什么（数据库？用户的鼠标点击？）和不能泄露什么（密钥）。
- 界面不再是“命令式地改”，而是“声明式地算”。你熟悉的是“收到事件 → 找到那个元素 → 修改它”。React 的模型是：界面 = 函数(状态)。你只改状态，框架负责重新计算界面并找出差异。改了一个普通变量而不是“状态”，界面当然不会动。
- 写代码的主体变了。现在大部分实现代码可以由 Agent 生成。你的核心产出变成：清晰的意图、准确的约束、可验证的验收标准，以及对 Agent 产出的审查。这要求你拥有足够精确的词汇去描述需求，也要求你懂到足以发现错误的程度。
接下来的十五章，基本就是在把这三个假设逐一拆开、换成新的心智模型。
类比：当年从汇编 / C 走向面向对象，发生了什么？
你可能经历过，或者至少听说过那次转换。它和今天这次转换有一个非常有用的共同点，也有一个关键的不同点。
共同点：抽象上移，但底层知识从未失效。C 程序员不用再手动分配寄存器，但真正懂栈帧和内存布局的人，调试段错误的速度是别人的十倍。Java 程序员不用手动释放内存，但不懂引用和 GC 的人会写出内存泄漏。同理，今天你可以让 Agent 写出一个完整的 React 组件，但如果你不理解“状态变化 → 重新渲染”这条规则，你就看不出它为什么会无限循环地请求接口。
关键的不同：编译器是确定性的，Agent 不是。同一段 C 代码，每次编译结果都一样；编译器极少出错，所以你可以几乎完全信任它。Agent 则是概率性的：同一句需求，两次可能得到两种实现；它可能“自信地”写错，也可能悄悄改了你没让它改的地方。这意味着这次转换比当年多了一个核心技能：验证。你需要让 Agent 的产出变得可检查（类型、测试、截图、日志），并且自己具备判断力。
“Agent 就像一个更高级的编译器”这个说法只在“抽象上移”这一点上成立。在“可靠性”上它更像一个能力很强、速度极快、但刚入职、不了解你项目上下文的同事：你需要给它清楚的需求、项目约定和验收标准，并审查它的代码。这个同事不会累、不会不耐烦，但也不会主动告诉你“我其实没看懂需求”。
三档深度：什么要懂原理，什么会用就行
TS 生态的名词数量非常多，逐个学透不现实，也没必要。这套教程给每个知识点标注一个深度，你可以据此分配精力：
原理
必须理解内部机制。这是 Agent 出错时你能发现、能定位、能说清楚“为什么错”的依据。数量少，但每一个都要能画图、能预测结果。
会用
能熟练使用、能读懂、能准确命名。这是你和 Agent 对话的词汇表。不必知道源码怎么实现，但要知道它解决什么问题、常见用法和坑。
知道
知道它存在、解决什么问题、什么时候该考虑它。这是做技术选型和系统设计时的视野。需要时再让 Agent 帮你深入。
下表是整个教程的“精力分配表”。第一次看不必全懂——每个名词在后续章节首次出现时都会解释。
| 主题 | 深度 | 为什么是这个深度 | 章节 |
|---|---|---|---|
| 事件循环、Promise、async/await | 原理 | “顺序不对”“卡住”“竞态”类 bug 的根源；面试必问 | 03 |
| TS 类型系统：结构化类型、收窄、泛型、类型擦除 | 原理 | 读懂 Agent 写的类型；知道“类型在运行时不存在”，所以边界必须校验 | 04 |
| HTTP、Cookie、CORS、缓存 | 原理 | 鉴权、跨域、缓存失效这些问题 Agent 最容易“修一处坏一处” | 05 |
| React 渲染模型：状态 → 重渲染、Effect | 原理 | Agent 最常见的错误之一就是滥用 useEffect | 06 |
| 服务端 / 客户端边界：SSR、RSC、水合 | 原理 | 决定代码在哪跑、数据怎么流、密钥会不会泄露 | 07 |
| LLM 调用：token、上下文、流式、工具调用 | 原理 | AI 功能的成本、延迟、可靠性都由它决定 | 11 |
| Agent 循环与上下文管理 | 原理 | 既是你要构建的东西，也是你每天使用的工具 | 12、13 |
| Next.js / TanStack Start 的路由与数据加载 | 会用 | 日常开发的主体；API 细节可以查 | 07 |
| Zod、Drizzle / Prisma、TanStack Query、Hono | 会用 | 高频库，需要能读懂并说出名字 | 08 |
| Tailwind CSS、shadcn/ui | 会用 | Agent 生成 UI 的默认组合，要能读、能调 | 05 |
| Vitest、Playwright、类型检查、CI | 会用 | 你验证 Agent 产出的主要武器 | 10 |
| Vercel / Cloudflare / 自托管部署 | 会用 | 至少熟练一条，另外两条知道差异 | 09 |
| 打包器内部（Vite、Rolldown、Turbopack） | 知道 | 知道它们是什么即可，极少需要你亲自调 | 01 |
| Monorepo 工具、各种状态管理库、动画库 | 知道 | 遇到具体需求再引入 | 10 |
拿不准一个新名词该学多深时，问自己：“如果 Agent 在这里写错了，我需要看懂到什么程度才能发现？”如果错误会静默发生、后果严重（数据错乱、安全漏洞、性能雪崩），就往“原理”靠；如果错误会立刻以报错形式暴露，“会用”就够了。
贯穿项目：LinkNote
为了避免每章讲一堆互不相关的例子，整套教程围绕同一个小应用展开。你每学一块概念，都会看到它在这个应用里具体落在哪里。
- 用户粘贴一个网址 → 服务器抓取网页 → LLM 生成摘要和标签（流式显示）。
- 列表页可以按标签筛选、搜索；每个收藏有状态：处理中 / 完成 / 失败。
- “问我的收藏”：一个 Agent，能调用“搜索收藏”工具，回答“我上个月存的关于 React 的文章讲了什么？”
- 分别部署到 Vercel、Cloudflare 和一台自己的服务器上。
你不需要现在就理解图里每个方块。读完第 08 章时，回来看这张图，每一个箭头你都应该能说出“这里传的是什么数据、用什么协议、在哪里做校验”。
学习地图与两条路线
01 生态全景
运行时、包管理、打包器、框架、平台分别是什么，彼此什么关系。
02 环境搭建
Node、pnpm、编辑器、tsconfig，跑起第一个项目。
03 JS 运行时
事件循环、异步、闭包、模块——最重要的“原理”章。
04 TS 类型系统
结构化类型、收窄、泛型、在边界做运行时校验。
05 Web 平台
HTTP、浏览器、HTML/CSS、Tailwind。
06 React
UI = f(state)、组件、Hooks、何时不该用 Effect。
07 渲染与元框架
CSR/SSR/RSC、Next.js 与 TanStack Start。
08 后端与数据
API、校验、ORM、鉴权、端到端类型安全。
09 部署
Vercel、Cloudflare、自托管的取舍。
10 工程化
测试、Lint、CI、Monorepo、可观测性。
11 AI 应用
LLM API、流式、结构化输出、工具调用、RAG。
12 Agent 与 Harness
Agent 循环、MCP、Skills、上下文工程。
13 驾驭 Coding Agent
规格 → 计划 → 实现 → 验证的工作流与表达方法。
14 系统设计与面试
全栈系统设计框架与高频面试题。
15 术语表与计划
中英术语对照、8 周学习计划、检查清单。
路线 A：急着做出东西（约 2 周）
00 → 01 → 02 → 03 → 04 → 06 → 07 → 08 → 11 → 13。加粗的是不能跳的“原理”章。其余章节在遇到问题时回查。
路线 B：系统转型（约 8 周）
按顺序读完全部章节，每章完成“对 Agent 说”的练习，并在 LinkNote 上实际跑一遍。第 15 章有逐周计划。
怎么读这套教程
每章的结构基本一致，你可以把它当成一个学习闭环：
- 先看开场问题。它是你现有知识解释不了的一个具体现象。试着先猜一个答案（不用写下来）。
- 跟着机制走。重点看交互图：点“下一步”，观察每一步的中间状态，而不只是最终结果。
- 回到 LinkNote。看这个概念在真实项目里长什么样。
- 练习“对 Agent 怎么说”。每章都有“模糊说法 vs 精确说法”的对照。把精确说法用在你自己的 Agent 上，观察产出差异。
- 做自检。自检题故意换了条件，考的是迁移，不是复述。答不上来就回到对应小节。
学习时，你可以把 Agent 当成随叫随到的助教，但要问“可验证”的问题：
后者给出了你的背景、具体例子、要看的中间过程和检验方式——这四样东西，也正是后面你给 Agent 派开发任务时要提供的。
工程师转型时很容易先去“搭一个完美的学习环境”：先研究 Monorepo、先配十个 Lint 规则、先写一个自动化 Agent 工作流……然后三周过去，一个可用的页面都没做出来。本教程的建议是：先让 LinkNote 最简单的版本跑起来并部署上线，再在真实问题出现时回来学对应的工具。交付优先于准备。
自检
1. 同事说：“有了 Agent，就不需要学事件循环这种底层东西了。”用本章的类比，指出这句话哪里对、哪里不对。
对的部分：抽象上移后，你确实不需要亲手写处理异步顺序的每一行代码，就像 Java 程序员不需要手动释放内存。
不对的部分：底层知识在“排错与审查”时从未失效；而且 Agent 不是确定性的编译器，它会写错。异步顺序 bug 往往静默发生（数据偶尔错乱），按本章的判断方法，这类知识属于“原理”档。
2. 你第一次遇到 “Turbopack” 这个词。按三档深度，你会把它放在哪一档？依据是什么？
“知道”档。它是一个打包器（把源代码变成浏览器能加载的文件的工具）。如果它出问题，通常会以明确的构建报错暴露，而不是静默产生错误业务数据；而且你几乎不需要自己配置它。知道它是什么、和 Vite 属于同一类工具就够了。
3. 一段代码读取了数据库密码并拼进页面。结合“第一个默认假设”，你首先应该问什么问题？
“这段代码运行在哪里？”如果它会被打包发给浏览器（客户端组件），密码会直接泄露给所有用户；如果它只在服务器运行，风险在于渲染结果里是否带出了敏感数据。第 07 章会讲清楚如何判断和约束这条边界。