AI HERO · SITE HANDBOOK · 全站学习手册
Matt Pocock（Total TypeScript 作者）的 AI 工程站。99 篇可学内容的中文摘要已全部编进本页，加上 69 条词典全量释义与三门系列课逐课展开——不跳外部页面即可读完整学习路径；售卖页已排除，每篇末尾留「原文」脚注备查。
§0 · OVERVIEW
全站内容围绕一件事：专业开发者如何把 AI 用出工程水准。它分两条主线——用 agent 写代码（skills、词典、Claude Code 实战）和写 AI 驱动的应用（LLM 基础、AI SDK、MCP、评测）。按你的目的选一条路线：
路线 A用好编码 agent —— 大多数人的第一优先级
路线 B做 AI 应用（TypeScript）—— AI Engineer 方向
路线 C手册式随查 —— 学过后当工具书
一句话总评：这个站最独特的资产是 skills 体系（把工程纪律写成 agent 可执行的工作流）和 AI 编码词典（给 agentic coding 一套精确词汇）；课程系列（AI SDK / MCP）是免费视频课，适合 TypeScript 开发者系统入门。
§1 · SKILLS SYSTEM
站长的核心开源资产：github.com/mattpocock/skills。一个 skill = 把「我遇到某类问题时会走的固定打法」写成小 markdown 文件，agent 按同样方式执行——不是给 agent 套脚手架，而是把你的品味和标准写下来让它复现。整包安装：
从模糊想法到合并代码的主干：面试落盘 → spec → 工单 → 实现 → 审查。/grill-with-docs 的单篇精读见姊妹篇。
新仓库先跑 setup 登记，迷路时问路由器。
动手之前把问题的形状摸清。
仓库日常：重构、排障、冲突、积压、引导。
不碰代码的日常杂务：对齐、交接、问卷、学习、复述、写作。
被其他 skill 复用的底座与纪律。
版本沿革（changelog，5 篇，未展开）：v1（token 省 63%）→ v1.1（wayfinder/to-spec/to-tickets）→ v1.2（/wait-what、Claude Code 插件）→ ubiquitous language 改名 grill-with-docs → handoff/prototype/review。见 /skills/ 目录。
§2 · DICTIONARY
给 agentic coding 一套精确词汇，每条都是「工程师能用的平实英语」定义。目录页：/ai-coding-dictionary，源仓库 mattpocock/dictionary-of-ai-coding。以下为全量条目的中文速览（释义为编译，链接指向原文）。
| AI | 一个移动的标签，不是具体技术——永远指向「计算机新学会的、令人惊艳的事」，当下=大语言模型。 |
| Model | 参数本身。无状态，只做下一 token 预测，自己无法做任何 agentic 的事。 |
| Parameters | 模型内部的数字（常以十亿计），训练时调定；模型知道的一切都在里面，又称 weights。 |
| Training | 用海量文本调整参数、提升下一 token 预测的过程。 |
| Inference | 运行训练好的模型生成输出；每次 provider 请求都在发生，参数保持固定。 |
| Effort | 模型回答前「思考多少」的旋钮：更努力=花更多输出 token，换难题上更高的成功率。 |
| Token | 模型读写的原子单位，约词大小；上下文窗口、成本、延迟都按 token 计。 |
| Next-token prediction | 模型唯一的工作方式：从上下文采样一个下一 token、追加、再跑一遍。 |
| Non-determinism | 相同输入可能不同输出；来自文本生成方式与 provider 的服务方式。 |
| Model provider | 提供推理服务的一方：通常远程（Anthropic / OpenAI / Google），也可以本地（Ollama、llama.cpp）。 |
| Harness | 把模型变成 agent 的一切外围：工具、系统提示、上下文窗口管理、权限、hooks。 |
| Model provider request | harness 与 provider 之间的一次往返：送去上下文，带回一个响应。 |
| Input tokens | 每次请求 harness 发去的 token，费率低于输出。 |
| Output tokens | 模型生成的 token，生产成本更高，计费也更高。 |
| Prefix cache | provider 侧缓存：连续请求跳过共享前缀的重复处理，这部分按更低费率计。 |
| Cache tokens | 命中前缀缓存的输入 token，费率低得多。 |
| Stateless | 不向前携带信息：模型跨请求无状态，agent 默认跨会话也无状态。 |
| Context | agent 当下能获取的、与任务相关的信息。 |
| Context window | 每次请求模型能看到的一切：有限、因模型而异、是模型感知世界的唯一表面。 |
| Stateful | 向前携带信息：会话跨 turn 有状态；配记忆系统可跨会话有状态。 |
| Agent | 套上 harness（工具+系统提示+上下文窗口）、与用户轮流对话的模型——「运动中的模型」。 |
| System prompt | harness 在每次请求前加上的指令——agent 的常备简报，一个会话内通常稳定。 |
| Session | 一段有界的交互：从空开始、不断累积，清空/关闭/压缩成新会话时结束。 |
| Turn | 一条用户消息 + agent 响应它所做的一切（含一次或多次 provider 请求），直到交还用户。 |
| Environment | agent 作用的世界：harness 之外、经工具结果感知、经工具调用改变的一切。 |
| Filesystem | 文件与目录树——编码 agent 的默认环境。 |
| Tool | harness 暴露给 agent 调用的函数（Read / Write / Bash / Search）——agent 感知与作用于环境的途径。 |
| Tool call | 模型输出里「点名某工具 + 参数」——只是结构化文本，必须由 harness 读取执行。 |
| Tool result | harness 执行后送回的内容——文件内容、输出或错误；agent 看环境的唯一视图。 |
| MCP | 把外部工具服务器插进 harness 的协议——agent 获得自带工具之外的工具的方式。 |
| Permission request | 执行未预批准的工具调用前给用户看的确认——把人放进环里的机制。 |
| Permission mode | agent mode 中管权限的部分：哪些调用触发确认、哪些自动执行。 |
| Agent mode | 预设包 = 权限模式 + 注入系统提示的行为指令；可会话中途切换。 |
| Sandbox | agent 运行其中的隔离环境（容器 / VM / 受限 shell），限制动作的爆炸半径。 |
| Sycophancy | 自信的附和——训练偏好「人类喜欢的回答」（包括附和）的产物。 |
| Hallucination | 自信的错误输出，两种：事实性（编造事实）与忠实性（漂离已加载的上下文）。 |
| Parametric knowledge | 训练时存进参数的知识，训练完即冻结；与上下文知识相对。 |
| Knowledge cutoff | 参数知识的截止日期；之后的库和 API 若不加载文档就是编造陷阱。 |
| Contextual knowledge | agent 此刻能从上下文直接读到的事实。 |
| Attention relationship | 两个 token 之间的配对——有意义的配对相互影响更强；N 个 token 约 N² 对。 |
| Attention budget | 每个 token 可分配给其余上下文的影响力，固定不随上下文变长而增长。 |
| Attention degradation | 会话变长，注意力预算摊到更多竞争者，有效信号被稀释。 |
| Smart zone | 会话早期 agent 又快又准；变长后滑进 dumb zone——马虎、健忘、易错。 |
| Clearing | 结束当前会话开新的：下一条消息从空会话、空上下文开始。 |
| Handoff | 把 agent 上下文从一个会话转移到另一个，无回路；载体可以是工件、压缩等。 |
| Primary source | 本体：代码、转录、原始数据——完整权威，但加载进上下文很贵。 |
| Secondary source | 对本体的一步转述：摘要、文档、压缩摘要——便宜，但天然有损。 |
| Handoff artifact | 作为交接载体的文档——一个会话写给另一个会话读。 |
| Spec | 描述多会话工作的交接工件：写「建什么」而非每个会话怎么干；由 ticket 组成。 |
| Ticket | 界定一个会话工作量的交接工件：可独立、可挂在 spec 下；兄弟 ticket 间可互相阻塞。 |
| Compaction | 在内存里完成的交接：旧会话历史被摘要后作为新会话的种子——细节换空间，有损。 |
| Autocompact | 上下文窗口将满时由 harness 自动触发的 compaction。 |
| Memory system | 让 agent 跨会话有状态的尝试：持久化到环境、会话开始时重载。 |
| AGENTS.md | 环境中的文件，harness 在会话开始时装进上下文——项目给 agent 的常备简报。 |
| Progressive disclosure | 只加载 agent 此刻需要的上下文，其余用指针指路——借自 UI 设计。 |
| Context pointer | 文档中指向另一文档的提及，任务需要时才拉进上下文。 |
| Skill | 打包成单位的可教能力——平时不占上下文，被指针按需拉入。 |
| Subagent | agent 经工具调用派生的 agent：独立会话运行、只回报一个工具结果，不能再派生。 |
| Human-in-the-loop | 人与 agent 会话内配对：审查、纠偏、实时协作。 |
| AFK | 用户启动会话后离开（away from keyboard），agent 无人值守运行。 |
| Automated check | 环境中运行的确定性验证：测试、类型、lint、build、pre-commit 钩子——只判 pass/fail。 |
| Automated review | agent 审另一个 agent 的活（常用不同模型或系统提示）——非确定性，会形成判断。 |
| Human review | 用户读 agent 产的代码并形成判断——读 diff 算，读摘要不算。 |
| Vibe coding | 不做人工审查、把 diff 当黑盒接受的工作模式。 |
| Design concept | 用户与 agent 共有的「在建之物」共识，独立于任何资产之外。 |
| Grilling | 发展 design concept 的技术：agent 苏格拉底式面试用户，一次敲定一个决策。 |
| Prototyping | 对话保真度不够时，让 agent 造个快速粗糙的版本，供大家对着实物讨论。 |
| DX | 开发者体验：代码库与工具链让人类多容易把活干好——文档、反馈速度、报错质量。 |
| AX | Agent 体验：环境为 agent 干好活准备得如何——检查、架构、白拿的上下文。 |
§3 · COURSES
做 AI 应用前的概念地基，官方推荐顺序（课程目录）。
免费视频课讲「AI 很强但很怪」；这五篇文字版把怪癖与约束讲透：token、上下文窗口、工具、agent、消息与系统提示。
前 16 篇按官方课序（课程目录），最后 3 篇为延伸。
ai 包即得 generateText/streamText/generateObject/streamObject，各 provider 另装如 @ai-sdk/openai。ai 导入 generateText，传入 model 与 prompt，从返回对象中解构 text。@ai-sdk/anthropic 的 claude-3.5-haiku，换成 claude-3.5-sonnet 只需改模型一行。generateText 最后一次性吐出全部文本，体验差；改用 streamText 即可逐 token 流式返回。streamText 接收的参数（model + prompt）与 generateText 完全相同，但返回 textStream 异步可迭代对象。for await 循环把每个 chunk 写到 stdout，也很容易接到网络请求流式推给 UI。text promise，不需要流式时直接 await 即可拿完整文本。generateText/streamText 等传一个 system 属性即可。messages 数组实现同样效果。LanguageModel。LanguageModel 类型天然支持依赖注入，业务函数与具体模型完全解耦。CoreMessage 类型：每条消息含 role（user/system/assistant/tool）与 content，对话史就是消息数组，随对话增长。generateText。result.response.messages 并以 JSON 返回，由客户端负责追加与保存历史。@ai-sdk/openai-compatible 的 createOpenAICompatible 可连接任何 OpenAI 兼容 API，不限本地。generateText，用法与云端模型完全一致。maxRetries: 0，连不上立即失败（SDK 默认重试 3 次以应对网络问题）。generateObject，结果的 object 拥有完整 TypeScript 类型安全访问。.describe() 为每个字段补充语义说明，帮模型理解要取什么，字段名不够直观时尤其有用。schemaName 并配 system prompt 约束输出风格，示例成功生成 Baba Ganoush 菜谱。generateObject 换成 streamObject，即可边生成边拿到结构化数据。partialObjectStream 是异步可迭代，用 for await 逐次读取对象的部分更新。result.object（result 在首个 chunk 到达时就返回，所以要单独等最终值）。generateObject，但传 output: "enum" 加 enum 数组列出所有候选值。object 即枚举结果，配 system prompt 说明分类任务；示例对三种语句分别得到 neutral/negative/positive。generateObject 加 output: "array"。.describe() 补充说明。object 即类型安全的对象数组。streamObject，数组元素可以边生成边流式展示。readFileSync 读成 Uint8Array，通过 messages 数组以 content 部件 type: "image" 传入 generateText。new URL(imageUrl) 直接放进 image 属性，由 LLM 侧下载查看。.describe() 给模型最大胜率。type: "file"，readFileSync 读原始二进制并附上 MIME 类型传给 generateObject。embedMany（批量）与 embed（单个）生成向量，模型如 openai.embedding("text-embedding-3-small")。cosineSimilarity 计算余弦相似度并排序，"Canine" 与 "Dog" 最相似（约 0.89），全程无需再调 LLM。tool() 创建工具：parameters 用 Zod schema 描述参数（配 .describe()），execute 执行任意异步逻辑（调 API、写库等），description 告诉 LLM 工具用途。generateText 的 tools 对象，并用 system prompt 引导模型调用。steps，查看 steps[0].toolCalls（工具名与入参）与 toolResults（执行结果）。toolResults 可以回喂给 LLM，为后续多步 agent 行为打基础。streamText 传 maxSteps 才会继续。steps 查看 toolCalls/toolResults；不建议把 maxSteps 设为 Infinity，因为模型有时不会自停。generateText + LanguageModel 一套代码通吃所有模型。streamText 对所有 provider 返回统一的 textStream。createUIMessageStream 组合两条子流：writer.merge 并入初始 streamText 回复，再用 streamObject（Zod schema 约定 suggestions: string[]）生成建议。useChat<MyMessage> 泛型获得类型安全，从最新消息的 parts 中取出建议渲染成可点击按钮。原文 ↗ /streaming-in-next-question-suggestions-with-the-ai-sdk
checkIsRequestSafe 用 generateText 调 gemini-2.0-flash-lite，system prompt 要求只回一个 token：'1' 安全、'0' 拦截，因此极快。UIMessageStreamWriter 写 text-start/text-delta/text-end 三段输出提示信息。MCP 是「AI 的 USB-C」。前 6 篇按官方课序（课程目录），最后 3 篇为延伸。
claude mcp add 添加名为 github-server 的 MCP server,scope 选项目级-y @modelcontextprotocol/server-github@latestGITHUB_PERSONAL_ACCESS_TOKEN=<你的 GitHub API Key>,配置完成即可使用claude mcp add "weather-example" npx tsx /path/to/file.ts 一条命令接入npx -y <包名>@latest 直接运行你的 MCP server,更新自动送达#!/usr/bin/env node shebang;package.json 的 bin 字段指向 dist/main.js(单一 bin 条目即会被 npx 执行)npm publish --access public 发布,需先 npm login,包名不能重复原文 ↗ /anthropics-new-model-context-protocol-in-2-minutes~hc0tx
§4 · IN THE TRENCHES
Claude Code 本体的调教：hooks 拦截、statusline、系统提示瘦身。
原文 ↗ /this-hook-stops-claude-code-running-dangerous-git-commands
怎么写好「项目给 agent 的常备简报」。
原文 ↗ /my-agents-md-file-for-building-plans-you-actually-read
从阶段划分到反馈环：把工程纪律装进 AI 开发。
原文 ↗ /essential-ai-coding-feedback-loops-for-type-script-projects
让 agent 挂机干活：入口、建议、可观测性、以及为什么别用官方插件。
围绕自家 skill 写的实战长文。
原文 ↗ /things-people-get-wrong-with-grill-me-and-grill-with-docs
§5 · EVALS
评测入门（what-are-evals）与 17 种改进技法已收在 §3 路线图课程里；这里是他专门的评测文章与工具 Evalite。
npx evalite 开箱即用,需要持久化再切 SQLite,省掉设置 SQLite 的门槛§6 · PAPER GUIDES
值得读一遍的外部经典，附他的解读。
原文 ↗ /storm-generate-high-quality-articles-based-on-real-research
§7 · TAKES
其余观点文已分插在 §4（rewired-brain、personal-software、grill-me 走红记）。
§+ · EXCLUDED & NOTES
llms.txt、sitemap.md、skills.md——本身就是「AX 友好」的示范。what-are-tokens 在 sitemap 中出现两次（同一页）；本图已去重。