用户输入一句话，模型决定要不要调用 Tool；如果调用 Tool，就把结果放回 messages，再请求一次模型；模型不再调用 Tool 时，整个任务结束。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

while (true) {
  const assistantMessages = await callModel(messages)

  const toolUses = findToolUses(assistantMessages)

  if (toolUses.length === 0) {
    return
  }

  const toolResults = await runTools(toolUses)

  messages = [
    ...messages,
    ...assistantMessages,
    ...toolResults,
  ]
}

这套循环很朴素，但 Claude Code 已经在它上面补了非常多生产环境能力：权限确认、上下文压缩、输出截断恢复、模型 fallback、Hook、取消、远程会话、JSONL 持久化等等。

最近帮朋友做点 Agent 的活儿，引入了 Goose 作为基座，发现 Goose 的 Agent Loop 竟然是一个状态机。

Claude Code 已经证明，一个 while (true) 可以承载复杂的 Agent 行为。Goose 为什么还要换成状态机？

从一个场景看起：

用户没有立刻批准

假设用户让 Agent 做一件事：

1

删除测试环境中过期的用户数据。

模型理解任务后，返回：

1

ToolRequest(delete_records)

这个操作显然不能直接执行。系统需要向用户确认：

1

该操作将删除 1,284 条测试环境记录，是否继续？

如果用户一分钟内点击「允许」，事情很简单。

1
2
3
4
5

模型请求工具
→ 等待用户确认
→ 执行工具
→ 返回 Tool Result
→ 模型继续

Claude Code 当前的设计很适合这种活跃交互。

Claude Code 中主流程由 queryLoop() 持续运行。模型返回 Tool Use 后，执行层会进入权限判断；最终，checkPermissionsAndCallTool() 会等待 canUseTool() 的结果。

canUseTool() 在交互模式下会创建一个 Promise：一边将待确认的 Tool 放进终端界面的确认队列，一边保留 Promise 的 resolve。此时执行链停在 await canUseTool(...)；用户点击「允许」或「拒绝」后，界面调用对应的 resolve，Promise 才变为 allow 或 deny。

若结果是 allow，原来的调用链继续执行 tool.call()；若结果是 deny，则生成一条拒绝的 Tool Result 并交回模型。整个过程中，queryLoop() 不会进入下一轮模型调用，它在等待本轮 Tool 调度完成。

也就是说，Claude Code 的控制流大致是：

1
2
3
4
5
6
7
8

queryLoop 正在运行
→ 模型返回 ToolUse
→ Tool 执行层调用 canUseTool
→ UI 等待用户确认
→ 用户同意
→ 原来的 Tool 调用继续执行
→ Tool Result 回到 messages
→ queryLoop 继续下一轮

这套机制在本地终端中很自然。只要 Claude Code 进程仍在运行、等待权限结果的调用链没有被取消，用户两小时后点击「允许」，原来的 Tool 调用依然可以继续。

这里有个细节：等待两个小时本身并不是问题。只要原进程、连接和调用链都还在，await canUseTool(...) 就可以一直等待；用户回来后调用 Promise 的 resolve，原来的 Tool 调用自然会继续。

真正的分界点在于，等待是否跨越当前执行现场。

最直观的情况是：用户关掉了终端，Claude Code 进程崩溃，或机器休眠导致当前连接和进程不再可靠。更复杂的产品中，审批可能由企业系统完成；任务也可能交给后台执行服务处理。

这里的「后台执行服务」是指从队列中取出任务、在后台运行的进程，它为了重启、迁移或扩缩容，未必会一直是最初处理任务的那个进程。Tool 也可能是异步任务，要等外部系统晚些时候回调。

问题在于，Promise 只是当前进程内存中的一个续执行点。进程结束后，Promise 与它的 resolve 都会消失；外部系统回传「审批单 123 已通过」时，也无法直接找到原来内存中的 Promise。让一个后台执行服务长时间挂着等待异步 Tool 的回调，通常也不经济。

这时，问题不再是「如何等待用户点击」，而是：

原来的 Agent 调用栈已经不存在时，系统如何知道这项 Tool 调用仍在等待审批？审批通过后，又该从哪里继续？

一旦不能依赖内存里的 Promise、局部变量和原来的调用栈，系统就需要把「正在等什么、等到后做什么」保存成可恢复的状态。

Goose 状态机真正想解决的，正是这种跨越执行生命周期的等待。

Claude Code 的 while 循环已经很成熟

在讨论 Goose 前，还是先把 Claude Code 说清楚。

Claude Code 并不是一个只有「模型 → Tool → 模型」的简单循环。

queryLoop() 内部维护了一个很完整的 state：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  messages,                   // 当前对话
  toolUseContext,             // 正在处理的 Tool 上下文
  turnCount,                  // 已经跑了多少轮

  // 压缩、输出截断等恢复过程的临时记录
  autoCompactTracking,
  maxOutputTokensOverride,
  maxOutputTokensRecoveryCount,
  hasAttemptedReactiveCompact,

  transition,                 // 上一轮为何重试或继续
  // 还有 Tool 摘要、Stop Hook 等控制状态
}

不需要逐个背字段。它们大致在做三件事：保留当前对话与 Tool 上下文；记录本轮已经走到哪里；以及在压缩、截断、重试时防止反复兜圈子。

这也正是它和最初那种几行 while 循环的差别：主循环除了「下一步调模型还是调工具」，还得同时带着这些临时状态往前走。

比如模型因为上下文过长而失败时，Claude Code 不会马上把错误展示给用户。它会尝试压缩消息，然后构造新的 state：

1
2
3
4
5
6
7
8
9
10
11

state = {
  messages: postCompactMessages,
  toolUseContext,
  hasAttemptedReactiveCompact: true,
  turnCount,
  transition: {
    reason: 'reactive_compact_retry',
  },
}

continue

下一轮 while (true) 再带着压缩后的上下文请求模型。

输出截断时也是类似的处理：

1
2
3
4
5

模型输出被截断
→ 临时提高 token 上限重新生成
或
→ 保留半截输出，追加一条「从断点继续」的消息
→ 继续下一轮

所以 Claude Code 的 while 循环不是简单实现，而是一个围绕「本次活跃查询」不断推进的调度中心。

它很适合解决：

1

当前终端中的任务如何持续高质量地跑完？

Goose 想解决的，则是另一个问题：

1
2

当前任务即使暂停、离开进程、等待外部事件，
系统是否仍然能可靠地知道下一步是什么

Goose 官方怎么解释这次改造

Goose 官方在 Unrolling the agent loop 中，对旧式 Agent Loop 的描述很直接：

1

一个持有大量本地状态的、单体的流式协程。

它提出将 Agent Loop 「展开」为一个可重复进入的状态机：

1
2
3

一次只推进一个 turn；
每个 turn 到达明确停止点后返回；
Conversation 本身就是状态。

官方给出的动机主要有三个：

1
2
3

1. 每个 turn 是普通函数调用，容易测试和推理；
2. 交互之间不保存挂起状态，适合事件驱动架构；
3. 每种行为都是可组合的 Operation，可以替换或扩展。

Goose 后续在 2026 Q3 Roadmap 中，也把它放进了「Goose 作为可嵌入 Agent 开发套件」的方向中：希望开发者能替换运行时组件、加入应用策略，并接入长任务或横向扩展的编排系统。

这里的重点不是「状态机比 while 高级」。

而是：当任务不再是一次短暂的终端交互时，不能把正确性建立在「那条异步调用链还活着」上。

最小 Demo：不记住状态，只读取历史

先写一个最小 Demo。

假设模型总是想查询销售数据，查询前必须得到用户确认：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

function nextStep(history) {
  // 从已发生的事件推导当前状态，不依赖函数外的临时变量。
  const kinds = new Set(history.map(item => item.kind))

  // 新任务刚开始：模型决定请求查询工具。
  if (history.length === 1 && history[0].kind === 'user') {
    return {
      kind: 'tool_request',
      tool: 'query_sales',
      args: { month: '2026-08' },
    }
  }

  // 已有工具请求、尚未审批：要求用户确认。
  if (
    kinds.has('tool_request') &&
    !kinds.has('approval') &&
    !kinds.has('action_required')
  ) {
    return {
      kind: 'action_required',
      message: '查询经营数据需要用户确认',
    }
  }

  // 用户已批准、工具尚未执行：返回一个待执行的 Tool Effect。
  if (kinds.has('approval') && !kinds.has('tool_response')) {
    return {
      kind: 'execute_tool',
      tool: 'query_sales',
      args: { month: '2026-08' },
    }
  }

  // 工具已有结果：模型基于结果生成最终回答。
  if (kinds.has('tool_response') && !kinds.has('assistant')) {
    return {
      kind: 'assistant',
      text: '8 月营收为 128 万元，环比增长 12%。',
    }
  }

  // 没有可推进的状态，任务暂时结束。
  return null
}

这里的 return 不是直接执行工具，也不是直接结束整个任务。它只是返回「下一步要做什么」：普通消息要写入历史，execute_tool 则应交给工具执行器。实际运行器负责执行这些动作，并在下一次根据更新后的历史调用 nextStep()：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

async function executeTool(effect) {
  if (effect.tool !== 'query_sales') {
    throw new Error(`未知工具：${effect.tool}`)
  }

  // 真实系统会在这里调用 MCP、数据库或 HTTP API。
  // Demo 用固定结果模拟一次异步工具调用。
  return {
    kind: 'tool_response',
    tool: effect.tool,
    result: { revenue: 1280000 },
  }
}

async function advance(history) {
  const event = nextStep(history)

  // null 表示当前没有可推进的步骤，例如正在等审批。
  if (event === null) {
    return null
  }

  if (event.kind === 'execute_tool') {
    // Effect 本身不进入模型上下文；执行后的结果才写回历史。
    const toolResponse = await executeTool(event)
    history.push(toolResponse)
    return toolResponse
  }

  // 普通事件写入 Session 或数据库；Demo 先追加到数组。
  history.push(event)
  return event
}

将上面的 nextStep()、executeTool() 和 advance() 放进同一个文件后，下面的 runDemo() 就可以直接运行完整流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

async function runDemo() {
  const history = [
    { kind: 'user', text: '生成 8 月销售摘要' },
  ]

  console.log(await advance(history))
  // => { kind: 'tool_request', tool: 'query_sales', ... }

  console.log(await advance(history))
  // => { kind: 'action_required', message: '查询经营数据需要用户确认' }

  console.log(await advance(history))
  // => null：已有待确认请求，状态机在此停止并等待外部事件。

  // 两小时后，审批系统或用户界面将确认结果写入持久化历史。
  history.push({ kind: 'approval', allowed: true })

  console.log(await advance(history))
  // => { kind: 'tool_response', tool: 'query_sales', ... }
  //    这里的 advance() 已实际调用 executeTool()。

  console.log(await advance(history))
  // => { kind: 'assistant', text: '8 月营收为 128 万元，环比增长 12%。' }

  console.log(await advance(history))
  // => null：已经得到最终回答，本轮任务结束。

  return history
}

runDemo().catch(console.error)

最终 history 的状态变化是：

1
2
3
4
5
6

user
→ tool_request(query_sales)
→ action_required(等待用户确认)
→ approval
→ tool_response(query_sales)
→ assistant(生成最终摘要)

这个 Demo 当然也有 history 变量；为了便于运行，它暂时只是一个数组。关键不在于「完全不用变量」，而在于状态不依赖这些只能存在于当前调用栈中的临时标志位：

1
2

let pendingTool = null
let waitingForApproval = true

真实系统会将 history 写入 Session、数据库或日志；进程重启后，可以重新加载它。这样就没有一个必须常驻内存的标志位变量，也没有一个必须从原位置恢复的调用栈。

换句话说，运行时的 history 变量只是持久化历史在内存中的当前表示。任务状态可以从这份历史重新推导：

1
2
3
4

是否已经请求工具？
是否已经要求审批？
用户是否已经同意？
工具是否已经产生结果？

然后根据这些事实，推导下一步。

这就是 Goose 设计里最重要的一句话：

Conversation 不只是模型的上下文，也是 Agent 的运行状态。

Goose 的源码如何实现

Goose 当前状态机的入口在：

1

crates/goose/src/agents/agent.rs

create_state_machine() 会组装一组有序的 Operation：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

开始
↓
用户中途纠偏（Steer）
↓
最大轮数限制
↓
上下文压缩
↓
工具调用压缩
↓
工具审批
↓
Skill / Recipe
↓
工具执行
↓
未知工具处理
↓
重试
↓
Stop Hook
↓
错误退出
↓
模型推理

create_state_machine() 的源码核心并不复杂：它把这些 Operation 按顺序装进 steps，再把模型推理放到最后。重点不在记住每一个类名，而在这条顺序是程序固定下来的：审批在工具执行前，模型推理在最后。

这里的每一个步骤都不直接说「继续跑主循环」。

它们只做两件事：

1
2

1. 根据当前 Session 与 Conversation，判断自己是否适用；
2. 如果适用，产生一组 Effects。

这些 Effects 由 SessionManager 统一应用：

1
2
3
4
5

AppendMessage          → 追加并持久化消息
ReplaceConversation    → 替换压缩后的对话
SetRecipe              → 保存当前 Recipe
SetExtensionData       → 保存扩展状态
RecordUsage            → 保存模型用量

状态机运行器自己仍然有一个很小的循环：

1
2
3
4
5
6
7
8
9
10
11
12
13

loop {
    let session = load_session(session_id).await?;

    let Some(result) = machine.step(&session).await? else {
        break;
    };

    apply_effects(&session, result.effects).await?;

    if result.yield_to_client {
        break;
    }
}

所以 Goose 并没有消灭 while。

它只是让 while 不再承载业务状态。

1
2
3
4
5

Claude Code 的 while：
负责推进模型、Tool、恢复、压缩、权限等大量任务逻辑。

Goose 的 while：
负责加载状态、执行一个步骤、应用 Effects、再读取状态。

复杂逻辑被拆到了各自的 Operation 里。

再回到审批场景

现在把前面的删除操作放回两种架构里看。

Claude Code

1
2
3
4
5
6
7
8
9

queryLoop 正在运行
→ ToolUse(delete_records)
→ 权限系统返回 ask
→ UI 展示确认队列
→ 当前执行链等待用户
→ 用户批准
→ tool.call()
→ Tool Result 回写 messages
→ queryLoop 继续

它的优势是直接、顺滑，尤其适合本地终端中的即时交互。

Goose

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Conversation 出现 ToolRequest(delete_records)

↓

ToolApprovalOperation 发现未审批请求

↓

写入 ActionRequired(delete_records)

↓

本次状态机运行结束，不会在这里挂着等待

用户稍后批准

↓

Conversation 出现 ToolConfirmationResponse

↓

以同一个 Session 发起一次新的状态机运行

↓

ToolApprovalOperation 将请求标记为可执行

↓

ToolExecutionOperation 执行

↓

写入 ToolResponse

↓

InferenceRunner 再次调用模型

它的优势是，任务可以不依赖原来的进程。

这里的「新的状态机运行」不是指原来的 while 循环挂着一小时后再继续。写入 ActionRequired 后，当前运行会在没有可继续处理的步骤时结束，或将控制权交回客户端；没有新事件时，不存在一个空转的循环。

一小时后，审批来自网页、Slack 或内部系统时，系统先将 ToolConfirmationResponse 写入持久化 Conversation，再用同一个 Session 发起新的运行。新的运行加载这份更新后的历史，看到「该 ToolRequest 已批准但尚未执行」，才继续审批标记、工具执行与模型推理。

因此，状态机的基本模型不是「一直 while 等待外部事件」，而是「外部事件到达后，基于新的 Conversation 再推进若干步」。

为什么这对复杂 Agent 有价值

如果只是在本地写代码，很多时候 Claude Code 的方式已经足够好。

但 Agent 一旦开始承担更长、更异步、更受约束的任务，就会遇到一些新需求：

1
2
3
4
5
6

- 审批来自外部系统
- 工具调用可能等待数小时
- 子 Agent 在后台完成后再汇报
- 任务可能被交给另一个 Worker
- 某个项目临时要求更严格的工具策略
- 需要记录每一步为什么发生

状态机的好处会慢慢显现出来。

1. 企业策略有了明确插入点

例如某个组织规定：

1

生产环境操作必须关联变更单。

在单体循环里，通常会变成 Tool 执行前的一段额外判断。

在 Goose 的模型里，可以更明确地表达为：

1
2
3
4

ToolRequest
→ ChangeTicketOperation
→ ToolApprovalOperation
→ ToolExecutionOperation

策略的位置、输入与输出都清楚。

2. 某个状态转换可以单独测试

例如要测试：

1

用户拒绝 delete_records 后，工具绝不能执行。

在完整 queryLoop 中，通常需要模拟模型输出、权限界面、Tool 调度和消息流。

在 Goose 的模型中，可以直接准备：

1
2

ToolRequest(delete_records)
+ ToolConfirmationResponse(Deny)

然后只验证审批 Operation 是否将请求标记为不可执行。

3. 可以接入外部编排系统

当一个 turn 是短暂、可持久化的状态转换时，任务可以更自然地接到：

1
2
3
4
5

消息队列
后台 Worker
人工审批服务
任务调度器
Temporal / Restate 一类工作流平台

Goose 官方也明确将事件驱动、长任务和横向扩展视为这种设计的目标之一。

总

Claude Code 的 queryLoop() 很值得学习。

它展示了一条成熟 Agent 主循环如何处理流式模型调用、工具执行、权限、压缩、错误恢复和会话续写。

Goose 的状态机也很值得学习。

它关注的是另一层问题：当 Agent 不再是一条持续运行的调用链，而是一个会暂停、恢复、等待外部事件、迁移和扩展的任务时，系统应该如何继续运行。

所以两者的差异不是：

1
2

Claude Code 用 while；
Goose 用状态机。

更准确的说法是：

1
2
3
4
5

Claude Code：
把复杂的 Agent 行为集中编排在一次 Query Loop 中。

Goose：
把复杂的 Agent 行为拆成基于持久化状态的独立转换。

回到最开始那项迟到的审批。

如果用户马上点击「允许」，两种设计的体验差别不大。

只有当等待跨越当前的进程、连接或执行现场时，状态机的价值才真正出现。

之前看到 KV Cache，只知道它缓存历史 token 的 Key 和 Value。

但这句话后面接着冒出来的词更多：token、embedding、Transformer、attention head、Q/K/V、prefill、decode、Prompt Cache……感觉像是在用一堆新名词解释另一个新名词。

这次直接从根源理解，看一下「一段文字进入大模型之后，到底经历了什么？」。

使用 distilbert/distilgpt2（DistilGPT-2）跑实验。它是 GPT-2 的蒸馏版：有 6 层 Transformer、每层 12 个 attention head，规模远小于今天常见的大模型，但完整保留了自回归生成、attention 和 KV Cache 的执行过程。

大模型是一个 token 一个 token 地生成文本

大模型不会一次把整段回答都写好。给它一段已有文本，它只做一件事：为下一个 token给出整张词表上的分数，然后按某种策略选出一个 token，接到原文本后面，再重复同样的过程。

1
2
3
4
5

已有 token：'The' / ' cat' / ' sat' / ' on'
→ 模型预测第 5 个 token：' the'
→ 已有 token：'The' / ' cat' / ' sat' / ' on' / ' the'
→ 模型预测第 6 个 token
→ ……

这叫自回归生成。在这个例子里，The / cat / sat / on 是已经给定的提示词；模型先处理这 4 个 token，得到第 5 个 token 的预测。选出第 5 个 token 后，它又成了新的上下文的一部分，模型据此继续预测第 6 个。

KV Cache 就出现在这个循环里：第 5 个 token 到来时，前 4 个 token 已经被处理过；第 6 个 token 到来时，前 5 个 token 又已经被处理过。后面会看到，模型怎样避免每一步都从头计算这段不断变长的上下文。

要理解这个循环，先从最开始的一次处理看起：文本怎样变成 token，token 又怎样进入模型。

文本进模型之前，模型其实还什么都没做

先加载 tokenizer 和模型：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("distilbert/distilgpt2")
model = AutoModelForCausalLM.from_pretrained(
    "distilbert/distilgpt2",
).eval()

embedding_table = model.get_input_embeddings().weight

print("词表大小:", tokenizer.vocab_size)
print("embedding 表形状:", tuple(embedding_table.shape))

# 输出：
# 词表大小: 50257
# embedding 表形状: (50257, 768)

这里有两样东西，容易混在一起。

tokenizer 可以理解成一套翻译规则：它把文本翻译成模型能处理的编号。

model 才是训练出来的大模型本体。它里面有很多参数矩阵，包括 embedding 表、Transformer 的参数、最后预测下一个 token 的参数。

词表有 50,257 个位置。每个位置对应一个 token ID；embedding 表有 50,257 行，每个 ID 都能查到一行浮点数。

接着让 tokenizer 处理文本：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

prompt = "The cat sat on"
input_ids = tokenizer(prompt, return_tensors="pt").input_ids

tokens = [
    repr(tokenizer.decode([token_id]))
    for token_id in input_ids[0].tolist()
]

print("文本:", repr(prompt))
print("token IDs:", input_ids[0].tolist())
print("tokens:", tokens)

# 输出：
# 文本: 'The cat sat on'
# token IDs: [464, 3797, 3332, 319]
# tokens: ["'The'", "' cat'", "' sat'", "' on'"]

token 不是固定的一个字或一个词，而是 tokenizer 按自己的词表切出的一段文本。比如这里的 ' cat' 连前面的空格也带上了，中文里「今天天气怎么样」可能被切成 ['今天', '天气', '怎么样', '？']，也可能切得更细，具体取决于模型的 tokenizer。

回到例子中，此时模型实际看到的是：

1

[464, 3797, 3332, 319]

不是：

1

The cat sat on

再看其中第一个 ID 怎样变成向量：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

first_token_id = input_ids[0, 0].item() # 模型要支持一次并行处理多条输入，所以这里是二维数组
first_embedding = embedding_table[first_token_id]

print(
    "第一个 token 的 embedding 形状:", tuple(first_embedding.shape),
    "\\n前 8 个数:", first_embedding[:8].tolist(),
)

# 输出：
# 第一个 token 的 embedding 形状: (768,)
# 前 8 个数: [-0.06264858692884445, -0.04490645229816437,
#              0.0558876097202301, -0.05465700104832649,
#              -0.1171262264251709, -0.07286953926086426,
#              -0.22325637936592102, -0.0032198030967265368]

这条链路到这里才真正进入模型内部：

1
2
3
4
5
6

文本
→ tokenizer 切 token
→ token ID
→ 查 token embedding 表
→ 查位置 embedding 表
→ 两条向量逐元素相加

"The" 这个 token 的 ID 是 464，模型从 token embedding 表第 464 行取出一个 768 维向量，记作 E_The。但 E_The 只说明「这是 The」；它还没有说明 The 在这段输入中的第几个位置。

1
2
3

[-0.06264858692884445, -0.04490645229816437, 0.0558876097202301, -0.05465700104832649,
 -0.1171262264251709, -0.07286953926086426,
 -0.22325637936592102, -0.0032198030967265368... 共 768 个浮点数]

DistilGPT-2 还有一张训练好的位置 embedding 表，形状是 (1024, 768)：最多 1024 个位置，每个位置也用一个 768 维向量表示。当前这 4 个 token 的位置编号是 [0, 1, 2, 3]，模型从这张表中取出 P_0、P_1、P_2、P_3，再和对应 token 向量逐元素相加：

1
2
3
4

h_The = E_The + P_0
h_cat = E_cat + P_1
h_sat = E_sat + P_2
h_on  = E_on  + P_3

这里不是把两个向量拼接起来；每一对都是 768 个位置一一相加，所以结果仍是 768 维。这样，同一个 token 即使出现在不同位置，进入模型的向量也会不同。

1
2
3
4
5
6
7
8
9
10
11
12

transformer = model.transformer  # 取出模型中的 Transformer 主体，里面有 wte 和 wpe 两张表
position_ids = torch.arange(input_ids.shape[1]).unsqueeze(0)  # 4 个 token 的位置编号：[[0, 1, 2, 3]]

token_embeddings = transformer.wte(input_ids)       # 用 4 个 token ID 查 token embedding 表
position_embeddings = transformer.wpe(position_ids)  # 用 4 个位置 ID 查位置 embedding 表
h0 = token_embeddings + position_embeddings          # 每个 token 向量和自己对应的位置向量逐元素相加

print(position_ids.tolist())               # [[0, 1, 2, 3]]：本次输入实际用到的 4 个位置
print(tuple(token_embeddings.shape))       # (1, 4, 768)：1 条输入、4 个 token、每条 768 维
print(tuple(position_embeddings.shape))    # (1, 4, 768)：同样查出了 4 条位置向量
print(tuple(transformer.wpe.weight.shape)) # (1024, 768)：位置表共有 1024 行，每行 768 维
print(tuple(h0.shape))                     # (1, 4, 768)：相加不改变形状

这里的 1024 不是这次输入有 1024 个 token，而是这张位置 embedding 表预先准备了位置 0 到 1023 的 1024 行。当前输入只有 4 个 token，所以只查到其中的第 0、1、2、3 行；它也意味着这个版本的 DistilGPT-2 最多只能处理 1024 个位置。

后面所有 Transformer 计算，处理的是 h_The / h_cat / h_sat / h_on 这样的向量，不再是字符。

先看 Transformer 是干什么的

此时模型已经拿到四个带有位置信息的 token 向量：

1
2
3
4

The 的向量
cat 的向量
sat 的向量
on 的向量

但它们还只是每个 token 最初的表示。模型需要做的是：让每个位置结合前面的上下文，变成一个更有上下文信息的新向量。

例如，单独看：

1

on

信息很少。但放在：

1

The cat sat on

里，它前面有主体、有动作，模型需要把这些关系带进当前位置的向量里。

完成这件事的一整套模块，就叫一个 Transformer 层。

一层 Transformer 中最重要的两步可以先粗略理解成：

1
2
3
4
5

Attention：
当前 token 去前面 token 里取自己需要的信息。

MLP：
拿到这些信息后，再对当前 token 做一轮自己的加工。

所以一层的作用不是「生成一个词」，而是：

1
2
3

所有 token 的当前向量
→ 彼此交换上下文信息
→ 每个 token 得到更丰富的新向量

模型会把这种层一层一层叠起来：

1
2
3
4
5
6

token embedding + position embedding
→ 第 0 层 Transformer
→ 第 1 层 Transformer
→ …
→ 最后一层的向量
→ 预测下一个 token

靠后一层收到的不是最初的 token 向量，而是已经混入前文信息、被前面层加工过的向量。

这就是「层」的作用：把一次还不够的上下文加工，连续做很多轮。

Attention Head 又是干什么的

前面说的 Attention，可以先想成一条通道：当前 token 用自己的 Query 去查询前面 token 的 Key 和 Value，得到一份上下文信息。

Transformer 实际不会只保留一条通道，而是同时运行多条独立的 Attention 通道；每条通道就叫一个 attention head。不同 head 有各自的 Q/K/V 参数，最后再把它们得到的信息合并。

可以先把它理解成：

1
2
3
4
5

一层 Transformer
├─ head 0：用一套自己的参数看上下文
├─ head 1：用另一套自己的参数看上下文
├─ …
└─ 把这些结果合并，再继续加工

每个 head 都有独立的参数，所以它们不一定会看同一种关系。

有的 head 可能更偏向相邻位置，有的可能更在意某些长距离关联。真实模型里，这些模式未必总能被清楚命名；不需要说「某个 head 专门负责语法、某个专门负责事实」，那样有点过度解释。

这个实验模型的配置是：

1
2
3
4
5
6
7
8

print(
    "Transformer 层数:", model.config.n_layer,
    "attention head 数:", model.config.n_head,
    "hidden size:", model.config.n_embd, # 叫 hidden 是因为这串向量只在模型内部各层之间传递，用户看不到。
)

# 输出：
# Transformer 层数: 6 attention head 数: 12 hidden size: 768

现在这三个数字就能对上了：

1
2
3
4
5
6
7
8

6 层 Transformer：
输入会连续经过六轮上下文加工。

12 个 attention head：
每一层里有 12 套并行的 attention。

hidden size = 768：
每个 token 当前的完整向量有 768 个数字。

因为 hidden size 是 768，同时又有 12 个 head，所以每个 head 分到的向量宽度是：

1

768 ÷ 12 = 64

这也是后面缓存形状里最后那个 64 的来源。

真实大模型通常有几十到上百层 Transformer、几十到上百个 attention head，hidden size 往往是数千到上万维；DistilGPT‑2 仍然小得多，但已经能让我们看到多个 head 和 64 维 K/V 的实际形状。

Attention 里面的 Q、K、V 是怎么来的

前面已经拿到了 The / cat / sat / on 的 token ID 和 embedding。下面沿着 DistilGPT-2 第 0 层 attention 的实际执行顺序往下看：先得到层输入，再做 QKV 投影，接着拆成 12 个 head，最后计算 ' on' 对前面位置的读取结果。

先把 Q、K、V 在这件事里的分工说清楚。它们都不是单个能直接翻译成中文的数，而是模型为每个 token 算出的三条向量；名字描述的是它们在 attention 中扮演的角色：

1
2
3

Q（Query，查询）：当前 token 想从上下文中找什么
K（Key，索引）：每个可见 token 提供什么线索，供 Q 判断是否匹配
V（Value，内容）：匹配后真正被取回、再混合进当前 token 的信息

例如更新 ' on' 时，Q_on 会和 The / cat / sat / on 各自的 K 比较，先得到「该读谁、各读多少」的权重；再用同一组权重混合四条 V，得到 ' on' 在这个 head 中的更新结果。Q 和 K 负责决定读取比例，V 才是被读取的内容。QKV 只是把 Q、K、V 这三组向量合在一起的简称；下面再看它们的数值是怎样从模型参数中算出来的。

1. 进入第 0 层时，手里有什么

四个 token 先查 embedding 表，再加上各自的位置 embedding。于是第 0 层看到的是一个矩阵，而不是四次互不相干的调用：

1
2
3
4
5

H₀ =
[h_The
 h_cat
 h_sat
 h_on]                         shape: (1, 4, 768)

三个维度依次是：batch=1、4 个 token、每个 token 的完整向量宽度 768。到这里，H₀ 只是第 0 层的输入；attention 还没有开始。

2. attention 之前，先做一次 LayerNorm

DistilGPT-2 的每一层都会先对每个 token 当前的 768 个数做 LayerNorm，再送入 attention。它的作用是把这一条向量的数值范围拉回比较稳定的尺度，让后续层更容易训练和计算。

对某一个 token 的向量 h，LayerNorm 只在它自己的 768 个维度内计算均值 μ 和方差 σ²：

1
2
3

μ   = mean(h₁, h₂, ..., h₇₆₈)
σ²  = mean((h - μ)²)
xᵢ = γᵢ × (hᵢ - μ) / √(σ² + ε) + βᵢ

γ 和 β 也是训练好的 768 维参数。这里没有 token 之间的信息交换：The 的 LayerNorm 不会读取 cat，它只调整 The 自己那条向量的尺度。因此 LayerNorm 前后形状完全不变：

1
2
3
4
5
6
7
8
9

transformer = model.transformer
layer0 = transformer.h[0]

position_ids = torch.arange(input_ids.shape[1]).unsqueeze(0)
h0 = transformer.wte(input_ids) + transformer.wpe(position_ids)
x = layer0.ln_1(h0)

print(tuple(h0.shape))  # (1, 4, 768)
print(tuple(x.shape))   # (1, 4, 768)

下面把 LayerNorm 输出记作 X。其中 x[0, 3] 是 ' on' 在进入 attention 前的当前向量：它有 768 个浮点数。打印前 8 个数看起来会是 [-0.12, 0.35, ...] 这样的普通浮点数；单独某一维没有可直接翻译成人类词义的含义，重要的是它们作为一个 768 维整体参与后续计算。

3. W_QKV 从哪里来

它不是运行时临时算出来的，而是训练好的模型参数。训练时它从随机数开始，随着「预测下一个 token」的误差不断经反向传播调整；训练完成后，数值被保存在模型权重文件（如 model.safetensors）里。

理论图里常把三套参数写成 W_Q、W_K、W_V。DistilGPT-2 为了计算方便，把它们拼成一张大矩阵：

1
2

W_QKV = [W_Q | W_K | W_V]        shape: (768, 2304)
b_QKV                             shape: (2304,)

其中 2304 = 3 × 768。所以一次矩阵乘法就能同时产生 Q、K、V。下面把这次计算得到的结果统一记作小写 qkv：

1

qkv = X × W_QKV + b_QKV          shape: (1, 4, 2304)

这一次「乘权重矩阵、再加偏置」的线性变换称作投影：把每个 token 当前的 768 个数，按训练好的规则算成 2304 个新数。不是把向量简单截断，也不是几何课里把东西投到平面上。

到这一步所有 token 的 Q、K、V 其实已经算出来了，后续只是切割。

4. 先切成 Q、K、V 三份，再排成 12 个 head

投影输出 qkv 的形状是 (1, 4, 2304)。先只看其中一个位置，比如 ' on'：它对应的一行有 2304 个数，按顺序存成下面三段：

1
2
3
4

' on' 的 2304 个数
├─ 前 768 个数：Q_on（完整 Q）
├─ 中间 768 个数：K_on（完整 K）
└─ 后 768 个数：V_on（完整 V）

The、cat、sat 也各有这样一行；所以沿最后一维每 768 个数切一次，就得到三块形状相同的张量：

下面的 q、k、v 只是 Python 变量名，分别装着 Q、K、V；大小写不表示两次不同的计算，也不表示两种不同的数据。

1
2
3
4
5

q, k, v = qkv.split(768, dim=-1)  # Python 中的小写 q/k/v，分别装 Q/K/V 三段

print(tuple(q.shape))  # (1, 4, 768)：4 个 token 各有一条完整的 q（Query）
print(tuple(k.shape))  # (1, 4, 768)：4 个 token 各有一条完整的 k（Key）
print(tuple(v.shape))  # (1, 4, 768)：4 个 token 各有一条完整的 v（Value）

例如 k[0, 0] 是 The 的完整 768 维 Key，k[0, 3] 是 ' on' 的完整 768 维 Key。它们都在这一次批量投影中产生；不是等到 ' on' 发起查询时才去生成前面三个位置的 Key。

这时的每条 q、k、v 仍是 768 维的总结果。DistilGPT-2 在配置中把这 768 维安排给 12 个 attention head 使用，因此每个 head 分到 768 ÷ 12 = 64 维：

1
2
3

一条 768 维 Q
→ [head 0 的 64 维 | head 1 的 64 维 | ... | head 11 的 64 维]
→ 形状从 (768) 变为 (12, 64)

这里只是把已经算好的 768 个数重新标出「哪 64 个属于哪个 head」，没有再做一次矩阵乘法。完整的 768 维输入 X 已经先参与了上面的 X × W_QKV 投影；64 不是从原始输入向量中预先切出来单独计算的。

代码把这三个张量都做同样的重排：

1
2
3
4
5
6
7
8
9
10

num_heads = 12                  # DistilGPT-2 的 head 数
head_dim = 768 // num_heads     # 每个 head 的宽度：64

def split_heads(t):
    batch_size, token_count, _ = t.shape                 # 这里是 1 条输入、4 个 token
    t = t.view(batch_size, token_count, num_heads, head_dim)  # (1, 4, 768) → (1, 4, 12, 64)
    return t.permute(0, 2, 1, 3)                          # 调整为 (batch, head, token, 维度)

q, k, v = map(split_heads, (q, k, v))  # 三个张量都得到 12 个 head 的表示
print(tuple(q.shape))                  # (1, 12, 4, 64)

现在维度顺序是 (batch, head, token 位置, head 内向量维度)。因此在第 0 层、第 0 个 head里：

1
2
3
4
5

Q_on  = q[0, 0, 3, :]    shape: (64,)
K_The = k[0, 0, 0, :]    shape: (64,)
K_cat = k[0, 0, 1, :]    shape: (64,)
K_sat = k[0, 0, 2, :]    shape: (64,)
K_on  = k[0, 0, 3, :]    shape: (64,)

同理，V_The 到 V_on 也是四条 64 维向量。

5. ' on' 用自己的 Q，读取四个位置的 K/V

现在 K_The、K_cat、K_sat、K_on 的来源已经清楚了：它们是四个位置各自的 64 维 Key。更新 ' on' 时，模型只取它自己的 Q_on，分别和这四条 Key 做点积：

1
2
3

scores = Q_on · [K_The, K_cat, K_sat, K_on]ᵀ / √64
α      = softmax(scores)
h′_on  = α_The × V_The + α_cat × V_cat + α_sat × V_sat + α_on × V_on

第一行的输出是 4 个标量分数；除以 √64 = 8 后再做 softmax，

第二行得到 4 个非负、总和为 1 的权重；

第三行才混合 4 条 64 维 Value，输出仍然是 64 维向量。

Q/K 只负责产生 α，V 不参加点积匹配。

对当前下载的 DistilGPT-2，脚本重建出的第 0 层、第 0 个 head、' on' 的权重是：

1
2

α = [0.4397, 0.2247, 0.2872, 0.0484]
     The     cat     sat      on

所以这一个 head 的实际输出是：

1
2
3
4

h′_on = 0.4397 × V_The
      + 0.2247 × V_cat
      + 0.2872 × V_sat
      + 0.0484 × V_on

这里的百分比不是下一个 token 的概率，也不是「The 比 cat 更重要」的全局结论。它只说明：在第 0 层、第 0 个 head、更新 ' on' 的这一刻，这个 head 主要从前三个位置取回 Value，很少读取 ' on' 自己的 Value。别的 head 和别的层会有不同的权重。

6. 明明四个位置的 Q/K/V 都算出来了，为什么 The 看不到后边的 token

这里要把「能并行生成 Q/K/V」和「能读取谁」分开。prefill 时四个位置的 Q/K/V 会一次性计算完；但在 scores 进入 softmax 前，causal mask 会把未来位置的分数遮住。于是：

1
2
3
4

The  的 Q 只能匹配 K_The
cat  的 Q 只能匹配 K_The、K_cat
sat  的 Q 只能匹配 K_The、K_cat、K_sat
on   的 Q 只能匹配 K_The、K_cat、K_sat、K_on

也就是说，未来 token 的 K/V 可以已经算好，却不能参与当前 token 的权重和加权和。这个因果限制还有一个直接后果：生成新 token 不会反过来改变旧位置已经得到的 K/V；后面 KV Cache 能复用历史 K/V，就建立在这里。

一个 Transformer 层结束后，怎样得到下一个 token 的预测

前面展开的是一个 head 如何更新 ' on'。一层里其实有 12 个 head；它们各自为每个 token 产出一条 64 维结果。对同一个 token，把 12 条结果并排放回去，就又回到了 768 维：

1
2

12 个 head 的输出： (1, 12, 4, 64)
调整维度并拼接后： (1, 4, 768)

接着有一个输出投影 W_O，形状是 (768, 768)。它把 12 个 head 拼接后的信息再混合一次，输出仍是每个 token 一条 768 维向量。这里的「混合」让一个 head 的结果不必永远只待在自己原来的 64 维槽位里。

attention 输出不会直接覆盖旧向量，而是先加回进入 attention 前的向量，这叫残差连接：

1

h_after_attention = h_before_attention + attention_output

随后每个 token 再经过一次 LayerNorm 和 MLP。DistilGPT-2 的 MLP 先把宽度从 768 扩大到 3072，经过 GELU 非线性激活，再投影回 768。3072 = 4 × 768：这里的 4 是 GPT-2 架构预先定下的 MLP 扩展倍率，不是根据 head 数或当前输入临时算出来的；换一种模型，这个倍率也可能不同。

1
2
3
4
5

(1, 4, 768)
→ Linear：768 → 3072
→ GELU
→ Linear：3072 → 768
→ 加回 MLP 前的向量（第二次残差连接）

MLP 不在 token 之间读取信息；它和前面的 LayerNorm 一样，逐个加工每条 token 向量。attention 负责从上下文取信息，输出投影负责混合 head，MLP 负责在每个位置内部进一步变换。完成这三部分后，才得到这一层的输出，并作为下一层的输入。

DistilGPT-2 有 6 层，所以这套过程会连续重复 6 次。最后一层之后还有一次 LayerNorm，模型再用词表投影把每个 768 维向量映射成 50,257 个 logits：

1
2

最后一层输出：       (1, 4, 768)
词表投影后的 logits： (1, 4, 50257)

这一步只在第 6 层 Transformer 完成之后做一次，不会每经过一层就做一次词表投影。前面 6 层一直在把每个位置的 768 维向量加工得更适合预测；最后才统一把它们变成词表分数。

这次输入有 4 个位置，所以最后一次投影会同时得到 4 行 logits：

1
2
3
4

'The'  这一行 → 对应「下一个应是 ' cat'」的预测
' cat' 这一行 → 对应「下一个应是 ' sat'」的预测
' sat' 这一行 → 对应「下一个应是 ' on'」的预测
' on'  这一行 → 用来选择第 5 个 token

训练时，这 4 行都会分别和真实的下一个 token 对照来计算误差；但现在是在生成文本，所以只需要最后一行 ' on' 的结果。

50,257 正是前面打印的 tokenizer.vocab_size：DistilGPT-2 词表中一共有 50,257 个 token ID。词表投影的最后一维因此不是「50,257 个词」，而是 ID 从 0 到 50,256 的 50,257 个候选 token；每一个候选项都有一个 logits 分数。

这里每个 logits 是一个 token 的原始分数，还不是概率；需要 softmax 才会变成 50,257 个概率。对于 The / cat / sat / on，第 4 个位置 ' on' 的那一行 logits 才用于从这 50,257 个候选项中选择第 5 个 token。

把这一行按概率从大到小取前 5 个，就能直接看到模型此刻认为最可能接在后面的 token 是什么：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import torch  # softmax、topk 等张量运算

with torch.no_grad():  # 这里只做推理，不需要为反向传播保存中间结果
    prefill = model(input_ids, use_cache=True)  # 一次处理 4 个输入 token，得到每个位置的 logits 和 KV Cache

last_logits = prefill.logits[0, -1]  # 取第 1 条输入的最后位置（' on'）：形状是 (50257,)
probabilities = torch.softmax(last_logits, dim=-1)  # 把 50,257 个原始分数变成总和为 1 的概率
top_probs, top_ids = torch.topk(probabilities, k=5)  # 找出概率最高的 5 个概率，以及它们各自的 token ID

for token_id, probability in zip(top_ids.tolist(), top_probs.tolist()):  # 一次取一个候选 ID 和它的概率
    token = tokenizer.decode([token_id])  # 把 ID 还原成人能读到的 token 文本
    print(f"ID={token_id:>5}, token={token!r}, probability={probability:.4f}")  # 打印这一个候选

next_id = top_ids[0].view(1, 1)  # 贪心策略：5 个候选中直接取概率最高的第 1 名，并恢复成模型输入所需的 (1, 1)
next_text = tokenizer.decode(next_id[0])  # 将选中的 ID 解码为文本
print("贪心选择:", next_id.item(), repr(next_text))  # 显示最终追加到句子后的 token

# 本次运行排第 1 的是：
# 贪心选择: 262 ' the'

所以「可能的 token」一开始其实是整张词表中的 50,257 个 ID；上面的循环会打印概率最高的 5 个。这里用的是贪心策略，直接选择其中概率最高的 ID 262，再经 tokenizer 解码成文本 ' the'。原始文本于是变成 The cat sat on the。如果改用 temperature、top-p 或随机采样，仍然从同一行概率中选，但不一定每次都选第 1 名。

第一次处理完整输入时，KV Cache 出现了

先把完整提示词送进模型的阶段，叫 prefill。这里输入是 4 个 token，模型会并行处理整段 The / cat / sat / on；但 causal mask 仍保证每个位置只能读取左侧和自己。

prefill 的副产品就是 past_key_values。把它打印出来：

1
2
3
4
5
6
7
8
9
10

cache = prefill.past_key_values

for layer, (key, value) in enumerate(cache):
    print(f"layer {layer}: K{tuple(key.shape)}, V{tuple(value.shape)}")

# 输出：6 层 transformer
# layer 0: K(1, 12, 4, 64), V(1, 12, 4, 64)
# layer 1: K(1, 12, 4, 64), V(1, 12, 4, 64)
# ...
# layer 5: K(1, 12, 4, 64), V(1, 12, 4, 64)

每层的形状 (1, 12, 4, 64) 分别表示：

1
2
3
4

1   ：batch size，一次只处理 1 条输入
12  ：12 个 attention head
4   ：已经处理过的 4 个 token
64  ：每个 head 的 K/V 向量宽度

因此，KV Cache 不是一句对话的摘要，也不是只存一份数据。它在 6 层 × 12 个 head 中分别保存历史 token 的 Key 和 Value。之后的 token 会继续拿自己的 Query 去匹配这些 Key，并按权重读取这些 Value。

这里为什么只缓存 K 和 V，不缓存 Q？因为新的 token 只会使用自己的 Q发起一次新查询；历史 token 的 Q 已经完成使命，未来不会再拿它来查询。

新 Token 到来时，KV Cache 到底省掉了什么

先把时序固定住。prefill 已经处理完 The / cat / sat / on，并从最后一行 logits 选出了第 5 个 token：' the'。这时文本看起来已经是：

1

The / cat / sat / on / the

但缓存里还只有前 4 个位置的 K/V；' the' 刚被选出来，还没有经过 6 层 Transformer。因此还要把它送回模型一次。这次调用不是为了再预测 ' the'，而是处理 ' the'，并预测第 6 个 token。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

cached = model(
    next_id,                  # 这次只输入新选出的 ' the'，形状是 (1, 1)
    past_key_values=cache,    # 同时交给模型前 4 个位置、每一层的 K/V
    use_cache=True,           # 让模型把 ' the' 新算出的 K/V 也保存下来
    output_attentions=True,   # 额外返回 attention 权重，便于观察；正常推理不必打开
)

print("本次模型输入:", tuple(next_id.shape))
print("新缓存长度:", cached.past_key_values[0][0].shape[2])
print("第 0 层权重形状:", tuple(cached.attentions[0].shape))
print("本次 logits 形状:", tuple(cached.logits.shape))

# 输出：
# 本次模型输入: (1, 1)
# 新缓存长度: 5
# 第 0 层权重形状: (1, 12, 1, 5)
# 本次 logits 形状: (1, 1, 50257)

(1, 1) 表示「1 条输入、这次只有 1 个新 token」，不是模型只知道一个 token。

前 4 个 token 的 K/V 已经藏在 cache 里；缓存长度从 4 变成 5，表示 ' the' 的 K/V 已经追加进去。

cached.logits 只有 1 行，是因为本次只处理了 ' the'；这一行的 50,257 个分数用来选择第 6 个 token。

以第 0 层、一个 head 为例，这次真正发生的是：

1
2
3
4
5

' the' 的当前向量
→ 只为 ' the' 生成新的 Q、K、V                 每条：(1, 12, 1, 64)
→ 新 K/V 接到缓存的 4 个旧 K/V 后面             K/V：(1, 12, 5, 64)
→ 新 Q 与 5 个 Key 匹配，再混合 5 个 Value      权重：(1, 12, 1, 5)
→ 得到 ' the' 在这一层的新向量，继续进入下一层

(1, 12, 1, 5) 在这里的作用只有一个：它说明 ' the' 虽然是单独送进来的 1 个新 token，但每个 head 仍要读取 5 个位置（前 4 个 token 加上 ' the' 自己）。这些权重怎样从 Q、K、V 算出，前面已经展开过；这里继续只看缓存省掉的计算。

现在再看 KV Cache 到底省了什么。没有缓存时，为了处理 ' the' 并预测第 6 个 token，模型要把 The / cat / sat / on / the 五个 token 一起重新送过 6 层。前 4 个 token 明明上一步已经处理过，却还得再走一遍。

有缓存时，模型只让新来的 ' the' 走这 6 层；前 4 个 token 不再重新计算。模型直接拿出它们早已留下的 K/V，给 ' the' 读取。换句话说：KV Cache 省掉的是「重做历史 token」，不是「处理新 token」。

提示词第一次进入模型时，长文本本身就要花更久的 prefill；进入生成阶段后，每生成一个新 token，它都还要和全部历史 K/V匹配并读取。历史从 100 个 token 增加到 10,000 个 token，新 token 要看的资料就从 100 份增加到 10,000 份。这就是长上下文仍然会慢的原因。

Prompt Cache：把不同请求的共同前缀复用掉

上一节的 KV Cache 只服务于同一次连续生成：回答每多一个 token，缓存就多一个位置。Prompt Cache 把同样的复用扩大到不同请求之间，由服务端保存已经处理过的公共提示词前缀。

假设应用每次都带上相同的系统提示词、工具定义和固定文档：

1
2

请求 A = [固定前缀] + [用户问题 A]
请求 B = [固定前缀] + [用户问题 B]

服务端处理请求 A 时，会为 [固定前缀] 完成 prefill，并留下每层的 K/V。处理请求 B 时，如果开头切出来的 token 序列和这个前缀完全相同，服务端就直接复用这些 K/V，只从 [用户问题 B] 开始计算。它缓存的不是回答，也不是「这段话的大意」，而是这段前缀已经算好的 K/V。

复用会在第一个不同 token 停下。例如改写一个词、插入动态日期、调整工具顺序，甚至某些空格变化，都可能从那个位置起不再命中；前面相同的部分仍可复用，后面则重新 prefill。因此稳定且较长的内容适合放在提示词前面，用户问题、时间和临时上下文放在后面。

这和用户修改提示词后的普通请求并不冲突：新请求不会回头修改上一轮生成的 KV Cache；服务端只是在新请求开始时，尝试从自己保存的 Prompt Cache 中找到共同前缀。

一句话区分：KV Cache 是一轮回答内部、随着生成不断增长的缓存；Prompt Cache 是服务端在多次请求间复用相同开头的缓存。

服务商如果提供「缓存读取输入」这一档，命中的固定前缀会按缓存读取计价，单价通常低于普通输入。网上也有人分享因为 Prompt Cache 吃大亏的：

某团队的客服 Agent 每天处理 10 万次对话，原本一切正常。某天工程师为了让 Agent “知道”当前时间，在系统提示词里加了一行 Current time: ，把时间戳实时注入进去。第二天监控告警：所有对话的首 token 延迟从 0.5 秒涨到 3-5 秒，月度推理账单几乎翻了一倍。

Current time 值每次在变，导致它之后的内容每次能无法命中 Prompt Cache。 所以设计 Agent 提示词时，应尽量把不变的内容放在前面，把频繁变化的信息放在后面。

总

回到一次真实的大模型 API 调用，用户在聊天框里输入一句话后，应用通常会把系统提示词、工具定义、历史消息和这句新消息一起组织成 API 请求，通过网络发给服务端。客户端一般发送的是文本或 messages 结构，不需要自己管理 token ID、K/V 或 past_key_values。

1
2
3
4
5
6
7
8

用户输入
→ 客户端拼出 prompt / messages，并调用 API
→ 服务端应用模型模板，tokenizer 切成 token
→ 检查开头是否命中 Prompt Cache
→ prefill：处理未命中的提示词部分，建立本次请求的 KV Cache
→ decode：每次生成 1 个 token，并把它的 K/V 追加到本次 KV Cache
→ 将 token 解码为文本，持续或一次性返回给客户端
→ 客户端显示给用户

若 API 开启流式返回，用户看到的文字会一小段一小段出现；底层仍是服务端不断生成 token，再把已生成的文本片段推送回来。每一步选择哪个 token，还会受 temperature、top-p 等采样参数影响，但不影响 KV Cache 的工作方式。

本次回复结束后，这一轮连续生成使用的 KV Cache 通常随请求结束而释放；Prompt Cache 是否还能被下一次请求命中，则取决于共同前缀和服务商自己的缓存策略。

到这里可以把三层东西分开看：

所谓「训练出来的模型」，核心是一大批被训练调整过的数字：embedding 表、位置 embedding、LayerNorm 的 γ/β、每层的 W_QKV、输出投影、MLP 参数，以及最后把隐藏向量映射到词表分数的参数。它们一般保存在 .safetensors 等权重文件中。模型配置（层数、hidden size、head 数等）和 tokenizer 虽然不是训练得到的参数，但让这些参数能被正确解释和执行；三者合在一起，才是一份可推理的模型包。

「开源模型」这个说法容易太笼统，至少要分三层看：

1
2
3

开放权重：可以下载训练好的参数、配置和 tokenizer，在本地推理。
开放代码：可以查看或使用模型、推理或训练相关的实现代码。
开放训练过程：还公开训练数据、数据处理、训练配方和日志。

一个模型可能只开放权重，不等于数据和完整训练过程也开放；实际使用前还需要查看它的许可证和使用限制。

拿到开放权重后，部署并不是重新实现 Q/K/V。一般要做的是：选择一个推理运行时，把权重和 tokenizer 加载到足够的 CPU/GPU 内存中，启动一个能接收请求的服务。运行时负责把矩阵计算真正跑起来，并通常负责批处理、调度、KV Cache 显存管理、上下文长度限制、采样和流式输出。是否支持 Prompt Cache、怎样淘汰缓存，则属于这层运行时或服务端的实现。

如果只是调用云端 API，应用开发者通常不需要写 KV Cache，也不需要自己部署模型；需要写的是业务侧代码：怎样拼系统提示词和历史消息、怎样把用户输入发给 API、怎样流式显示回复、怎样处理工具调用、检索结果、权限和异常。如果自己部署开放模型，除了这些业务代码，还要负责模型服务的硬件、启动、扩缩容、监控和安全等工程工作。

产品介绍

产品主要用对话承载，可以聊天录入机酒、行程、小红书资料。

日程可以查看每日的安排，可以录入酒店、机票、地点、门票。机票、酒店也可以单独点击查看。

之前一些有用的小红书链接会发到微信群里，后边找的时候很麻烦，可以把小红书链接发给 Agent，会自动归档到资料里。

意图定义

最开始做的时候，并不知道「意图识别」是什么。最初的想法就是：用户说一句话，直接交给大模型，让它自己判断要不要调用工具、调用哪个工具，最后再生成回答。

这个想法很自然，因为大模型看起来什么都懂。用户说「第 3 天干嘛」，它知道是在问日程；用户发一个酒店订单截图，它也能看懂是酒店；用户说「这个地方安全吗」，它也能推断出和旅行有关。

所以最开始，想象中的系统大概是：

1
2
3
4

用户输入
-> 大模型理解
-> 大模型决定工具
-> 大模型回答

但真正往产品里做的时候，发现这条路并没有那么稳。后来又看了一些关于意图识别和 Agent 工程的资料，才意识到这里应该拆出一个更明确的路由层。

比如用户输入：

1

股票买哪个

如果全交给大模型，它可能真的开始分析股票。但我做的是旅行助手，它不应该回答投资建议，否则既越过了产品边界，也浪费 token。

再比如用户输入：

1

https://windliang.wang/ 加入到资料

这里有链接，也有「加入资料」的动作。如果不先判断范围，系统很容易直接抓取、总结、入库。但这个链接本身没有旅行语境，并不应该直接进入旅行资料库。

还有这种问题：

1

这个地方安全吗？

它确实和旅行有关，但也不能简单地当成普通问答。因为安全信息最好结合当前目的地、必要时搜索最新资料，并且给出来源。

Agent 不能只靠大模型自由发挥。它需要一个路由层，先判断这句话属于什么范围、对应哪个产品能力、是否需要追问、能不能继续执行。

也就是意图识别，不是给一句话贴标签，而是决定系统下一步该走哪条业务链路：查数据库、读附件、保存资料、搜索网页、写入行程、追问用户，还是直接拒绝。

意图梳理

项目是一个旅行助手，核心场景是帮用户管理一次旅行。

用户可以创建一个行程，比如：

1

2026 年国庆 · 西班牙

然后围绕这个行程做几类事。

1. 查询每日安排

用户可能会问：

1
2

第 3 天干嘛？
今天有什么安排？

这类问题对应到：

1

day_query

系统会读取当前行程里对应 Day 的安排，按时间整理出来。

2. 整理机票、酒店、门票订单

用户可以上传截图、PDF 或订单信息：

1
2
3

帮我整理这张机票
这个酒店订单记一下
门票二维码加到行程里

这几类分别对应：

1
2
3

flight
hotel
ticket

系统会提取航班时间、入住退房、门票日期、地址、订单号等结构化信息，并写入当前行程。

3. 导入行程表

比如用户上传 Excel、CSV，或者说：

1
2

把这个计划表导入
按这个表写进行程

对应的是：

1

itinerary

系统会解析日期、时间、地点、事项，然后写入每日安排。

4. 保存旅行资料

比如：

1
2
3

这篇西班牙攻略加入资料
小红书这个链接先存一下
这个景点官网留作参考

对应的是：

1

memory

系统会抓取链接内容，总结后放进当前行程的资料库。后续用户追问时，这些资料会成为上下文。

5. 分析攻略或截图

用户可能发一张小红书截图、攻略图片，然后问：

1
2

这张图里有什么推荐？
这个攻略适合我们吗？

对应的是：

1

note

它更像“资料阅读”和“攻略分析”，不一定马上写入行程。

6. 旅行通用问答

比如：

1
2
3

这个地方安全吗？
巴塞罗那有什么好吃的？
住的地方离机场远吗？

对应的是：

1

general

系统会结合当前行程、资料库、历史对话，必要时调用搜索或回答模型。

7. 需要追问

比如：

1

https://example.com 加入资料

这句话有「加入资料」的动作，但链接本身没有旅行语境。系统不知道它是不是旅行资料，所以我把它归到：

1

clarify

这时不应该直接入库，而应该先问：

1

这个链接和当前旅行有什么关系？

8. 超出范围

比如：

1
2

股票买哪个？
帮我写个劳动合同

对应的是：

1

out_of_scope

旅行助手不应该接这些任务。

所以，产品能力和意图的关系大致是：

1
2
3
4
5
6
7
8
9
10

day_query     -> 查询每日安排
flight        -> 识别机票订单
hotel         -> 识别酒店订单
ticket        -> 识别门票/票券
itinerary     -> 导入或写入行程
memory        -> 保存旅行资料
note          -> 分析攻略/截图
general       -> 旅行问答
clarify       -> 追问补充信息
out_of_scope  -> 拒绝非旅行问题

意图识别不是为了给用户一句「分类结果」，而是为了决定系统下一步应该进入哪个产品能力。

为什么不直接让大模型判断所有事

如果系统足够简单，当然可以直接让大模型判断。

但旅行助手不是一个纯聊天机器人。它背后有数据库、有用户资料、有附件解析、有搜索、有写入动作。

这时，大模型判断错一次，后果不只是「回答差一点」。

它可能会：

1
2
3
4
5

把非旅行问题当成旅行问题回答
把普通链接错误保存进资料库
把「只是问问」理解成「写进行程」
把需要追问的问题直接执行
把多个意图压成一个意图

尤其是带写入动作的场景，我不敢让模型凭感觉决定。

比如：

1

这个加进去

这里的「这个」是什么？是上一条攻略？是一个景点？是一张门票？还是用户只是想保存资料？

如果系统直接让大模型调用写入工具，就很危险。

更接受的做法是：

1
2
3
4

高确定性的，用规则快速判断
模糊的，用便宜模型辅助分类
需要执行的，始终由业务代码控制
不确定的，追问用户

也就是说，大模型可以参与意图识别，但不应该独占意图识别。

那回到意图识别，可以把它看成一个从粗到细的路由过程：

1
2
3
4

先把用户的话整理清楚
再判断这是不是旅行助手该处理的范围
然后识别它对应哪个产品能力
最后才决定要不要调用模型、搜索、读附件或写数据库

对应到项目里，就是三层：

1
2
3

第一层：输入归一化
第二层：旅行范围判断
第三层：业务意图识别

这三层解决的问题不一样。

输入归一化解决的是：用户说得太口语、太省略，系统要先把话补完整。

旅行范围判断解决的是：这件事是不是旅行助手该接的，不能什么都往后丢。

业务意图识别解决的是：如果它属于旅行场景，那到底应该走日程查询、订单识别、资料保存、攻略分析，还是旅行问答。

这样拆完之后，大模型就不是整个系统的入口，而是其中一个兜底判断器。规则能确定的，直接走规则；规则不确定的，再让便宜模型帮忙复判；真正执行时，仍然由业务代码控制。

第一层：先把用户的话整理一下

真实用户不会按照系统字段说话。

他们会说：

1
2
3
4

机酒帮我整理一下
住哪来着
这个地方安全吗？
把刚才那个加进去

这里有缩写、口语、代词、省略和上下文引用。

所以现在先做输入归一化。

例如：

1
2
3
4
5

机酒 -> 机票 酒店 机酒
住哪 -> 酒店 住宿
怎么过去 -> 怎么去 交通
最划算 -> 推荐 价格 预算
这里 / 这个 / 当地 -> 补上当前行程名称和目的地

代码大概是这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

function normalizeInputForIntent(input: string, trip?: Trip) {
  let normalized = input
    .normalize("NFKC")
    .replace(/\s+/g, " ")
    .replace(/[？?]+$/g, "")
    .trim();

  const replacements: Array<[RegExp, string]> = [
    [/机酒/g, "机票 酒店 机酒"],
    [/住哪|住哪里|住宿地/g, "酒店 住宿"],
    [/怎么过去|如何过去/g, "怎么去 交通"],
    [/最划算|省钱|性价比/g, "推荐 价格 预算"],
  ];

  for (const [pattern, replacement] of replacements) {
    normalized = normalized.replace(pattern, replacement);
  }

  const tripTokens = trip ? getTripReferenceTokens(trip).join(" ") : "";

  if (tripTokens && /(这里|那里|当地|这个|它|那边)/.test(normalized)) {
    normalized = `${normalized} ${tripTokens}`;
  }

  return normalized.trim();
}

原始输入：

1

这个地方安全吗？

如果当前行程是“2026 年国庆 · 西班牙”，归一化后，系统就能把“这个地方”放回当前行程语境里判断。

这一步的目的不是润色文本，而是把用户的自然表达变成系统更容易判断的表达。

第二层：判断是不是旅行范围

旅行范围有三种：

1

type TravelScope = "travel" | "non_travel" | "uncertain";

例如：

1
2
3
4
5
6
7
8

股票买哪个
=> non_travel / out_of_scope

https://windliang.wang/
=> non_travel / out_of_scope

https://windliang.wang/ 加入资料
=> uncertain / clarify

代码里会先做范围判断：

1
2
3
4
5
6
7
8
9

const rawQuestion = getActualQuestion(message);
const actualQuestion = normalizeInputForIntent(rawQuestion, trip);

const travelScope = resolveTravelScope({
  file,
  input: actualQuestion,
  rawInput: rawQuestion,
  trip,
});

如果是明确非旅行问题，就直接变成 out_of_scope：

1
2
3
4
5
6
7
8
9
10

if (travelScope.scope === "non_travel") {
  const intent: AssistantIntent = "out_of_scope";

  return finishTurn({
    ok: true,
    title: "这个问题和旅行行程无关哦",
    detail: "",
    intent,
  });
}

这一步其实是在回答一个更基础的问题：

这个请求是不是旅行助手应该处理的？

只有这个问题过了，才继续判断它是 memory、hotel、ticket 还是 general。

第三层：判断具体业务意图

当系统确认请求属于旅行范围，或者至少不确定但可能相关时，才进入业务意图识别。

当前项目的意图有十种：

1
2
3
4
5
6
7
8
9
10

day_query
flight
hotel
ticket
itinerary
memory
note
general
clarify
out_of_scope

这些意图不是标签，而是后续链路。

例如：

1
2
3
4
5
6
7
8
9
10

day_query
=> 读取 Day 日程
memory
=> 抓取链接，总结并保存资料
clarify
=> 不执行，先追问
out_of_scope
=> 不处理，提示超出旅行范围
general
=> 进入旅行问答，必要时搜索或调用回答模型

规则识别会输出候选意图、分数和原因：

1
2
3
4
5

type IntentCandidate = {
  intent: AssistantIntent;
  reason: string;
  score: number;
};

比如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

if (isDayScheduleQuestion(normalizedInput)) {
  return {
    candidates: [
      {
        intent: "day_query",
        reason: "命中 Day/当天日程查询",
        score: 100,
      },
    ],
    intent: "day_query",
    normalizedInput,
    originalInput: input,
  };
}

再比如机票、酒店、门票：

1
2
3
4
5
6
7
8
9
10
11

if (/机票|航班|起飞|落地|登机|flight/.test(combined)) {
  addCandidate("flight", 88, "命中机票/航班信号");
}

if (/酒店|入住|退房|住宿|hotel/.test(combined)) {
  addCandidate("hotel", 88, "命中酒店/住宿信号");
}

if (hasTicketSignal && (file || hasSaveSignal)) {
  addCandidate("ticket", 96, "命中票券信号，且有附件或保存动作");
}

最后按分数选出当前主意图：

1
2
3
4
5
6
7

const [winner] = [...candidates].sort((left, right) => {
  if (right.score !== left.score) {
    return right.score - left.score;
  }

  return candidates.indexOf(left) - candidates.indexOf(right);
});

链接的例子

旅行助手里有一个典型场景：用户发链接。

最开始的规则很简单：

1

只要输入包含 URL，就识别为 memory

也就是保存到资料库，但这样用户随便发一个个人网站，也会被当成旅行资料。

所以把规则更加细化：

1
2
3
4

旅行平台链接 -> 可以倾向 memory
普通链接 + 旅行语境 + 保存动作 -> memory
普通链接 + 保存动作 + 无旅行语境 -> clarify
普通裸链接 + 无旅行语境 -> out_of_scope

代码里会先提取安全 URL，并排除 localhost、内网地址这类不适合抓取的链接：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

function getSafeMemoryUrl(input: string) {
  const rawUrl = extractFirstUrl(input);

  if (!rawUrl) {
    return undefined;
  }

  const url = new URL(rawUrl);

  if (!["http:", "https:"].includes(url.protocol)) {
    return undefined;
  }

  if (isPrivateMemoryHost(url.hostname)) {
    return undefined;
  }

  return url;
}

然后判断它是不是旅行平台、有没有旅行文本、有没有保存动作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

function resolveUrlTravelSignal(input: string) {
  const url = getSafeMemoryUrl(input);

  if (!url) {
    return undefined;
  }

  const travelHost = hasTravelUrlHost(url);
  const travelText = hasTravelUrlTextSignal(input, url);
  const saveSignal = hasMemorySaveSignal(input);

  return {
    shouldSaveMemory: travelHost || (travelText && saveSignal),
    travelHost,
    travelText,
    saveSignal,
    url: url.toString(),
  };
}

最后落到不同意图：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

if (urlSignal?.shouldSaveMemory) {
  return {
    intent: "memory",
    candidates: [
      {
        intent: "memory",
        reason: "旅行链接或旅行资料保存信号",
        score: 92,
      },
    ],
  };
}

if (urlSignal?.saveSignal && !urlSignal.travelHost && !urlSignal.travelText) {
  addCandidate("clarify", 74, "只有保存动作，但缺少旅行语境");
}

比如：

1
2
3
4
5
6
7
8
9
10
11

小红书攻略链接 加入资料
=> memory

这篇西班牙攻略加入资料 https://example.com
=> memory

https://example.com 加入资料
=> clarify

https://example.com
=> out_of_scope

这里的关键是：动作不等于意图成立。

「加入资料」只是动作信号。系统还要判断这个资料是不是属于当前旅行场景。

如果不确定，就追问，而不是硬执行。

规则和模型怎么分工

不能完全靠规则，也不能完全靠模型。

规则适合高确定性的场景：

1
2
3
4
5

第 3 天干嘛 -> day_query
机票订单 -> flight
酒店订单 -> hotel
门票二维码 -> ticket
股票买哪个 -> out_of_scope

规则快、便宜、稳定。能确定的事情，不需要花一次模型调用。

但规则也有边界。

比如：

1
2
3
4

这个能不能带老人去？
这个链接有用，先放着
把刚才那个加进去
住的地方离机场远吗？

这些句子依赖上下文、代词和隐含动作。继续堆正则，会越来越脆。

所以引入了一个便宜模型：

1

glm-4.7-flash

它只在规则不确定时调用。

触发条件在代码里大概是这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

function shouldUseIntentClassifier({
  actualQuestion,
  intentResolution,
  rawQuestion,
  travelScope,
}: Args) {
  if (travelScope.scope === "uncertain") {
    return true;
  }

  const [topCandidate, secondCandidate] = sortedCandidates;

  if (topCandidate.intent === "general" && topCandidate.score <= 70) {
    return true;
  }

  if (topCandidate.intent === "clarify") {
    return true;
  }

  if (topCandidate.score < 80) {
    return true;
  }

  if (secondCandidate && topCandidate.score - secondCandidate.score <= 8) {
    return true;
  }

  if (/(这个|那个|它|刚才|当地|这里|那里)/.test(rawQuestion)) {
    return true;
  }

  return Boolean(resolveUrlTravelSignal(rawQuestion));
}

模型只做结构化分类：

1
2
3
4
5
6
7
8
9

{
  "scope": "travel",
  "intent": "general",
  "confidence": 0.82,
  "reason": "用户在询问当前目的地安全情况",
  "slots": {
    "needs_search": true
  }
}

调用时会限制它的行为：

1
2
3
4
5
6
7

const callOptions = {
  model: "glm-4.7-flash",
  responseFormat: "json",
  temperature: 0,
  maxTokens: 300,
  thinking: "disabled",
};

它不负责回答，不负责搜索，不负责写库。

也就是说，现在的分工是：

1
2
3

规则负责确定性
小模型负责模糊判断
业务代码负责执行

为什么模型不能直接执行

因为「理解」和「执行」是两件事。

模型可以判断：

1

用户可能想把这个攻略加到行程里

但真正要不要写入数据库，应该由代码判断：

1
2
3
4
5

有没有明确写入动作？
有没有目标 Day？
有没有结构化地点和时间？
用户是否确认？
工具是否返回 success？

当前项目里有一个原则：

只有工具返回成功，系统才能说“已写入”。

代码里会检查写入工具是否真的成功：

1
2
3

if (isSaveItineraryToolCall(toolCall) && isSuccessfulToolWrite(result)) {
  hasSuccessfulItineraryWrite = true;
}

如果模型没有成功调用写入工具，却在回答里声称已经写入，系统会拦截：

1
2
3
4
5
6
7
8
9
10
11
12
13

if (
  answer &&
  !hasSuccessfulItineraryWrite &&
  isExplicitItineraryWriteRequest(question) &&
  claimsItineraryWrite(answer)
) {
  return {
    ok: false,
    title: "还没有写入行程",
    detail: "刚才模型没有完成写入工具调用，所以我没有把它当成已写入。",
    intent: "general",
  };
}

这就是为什么不想让模型直接接管执行。

Agent 的可靠性，不来自模型一句「我认为」，而来自流程里的硬约束。

代码不是不相信模型的文字，而是先确认模型调用了 save_itinerary_items，再确认工具返回 success: true。只有这两个条件同时满足，系统才允许说“已写入”。

调试意图

为了调试给项目做了两件事。

第一，页面上有 Debug 面板，会展示：

1
2
3
4
5
6
7

输入归一化
旅行范围判断
规则意图识别
发送给 GLM · 意图分类
GLM 返回 · 意图分类
意图分类模型已采纳
最终意图

代码里每个关键节点都会写 Debug：

1
2
3
4
5
6
7
8
9
10
11

pushDebugEntry(debugEntries, "输入归一化", {
  actualQuestion,
  rawQuestion,
});

pushDebugEntry(debugEntries, "旅行范围判断", travelScope);

pushDebugEntry(debugEntries, "规则意图识别", {
  candidates: intentResolution.candidates,
  intent: intentResolution.intent,
});

第二，每一轮 Debug 都会落到本地文件：

1

.agent-debug/

简化后的代码是：

1
2
3
4
5
6
7
8
9
10
11

async function writeAgentDebugLog({ entries, response, tripId }: Args) {
  const debugRoot = path.join(process.cwd(), ".agent-debug");
  const filePath = path.join(debugRoot, `${Date.now()}.json`);

  await mkdir(debugRoot, { recursive: true });
  await writeFile(
    filePath,
    JSON.stringify({ entries, response, tripId }, null, 2),
    "utf8",
  );
}

这样可以回看每一次判断为什么出错。

比如看到一条：

1

https://windliang.wang/ 加入到资料

如果结果是：

1

memory

说明规则过宽。

如果结果是下边的就更合理。

1
2
3

scope: uncertain
intent: clarify
reason: 只有保存动作，但缺少旅行语境

没有 Debug，意图识别只能靠猜。有了 Debug，就能像调业务系统一样调 Agent。

当前架构和优化

当前项目的整体流程是：

当前这套已经比「一句 Prompt 识别意图」稳很多，但产品毕竟还没经历大量真实用户输入，用户多了肯定会有各种意料之外的问题，后续还有很多方向可以优化。

尤其是现在规则层里还有不少正则。正则不是不能用，它适合处理高确定性的信号，比如：

1
2
3
4

第 3 天干嘛 -> day_query
机票 / 航班 / 起飞 / 落地 -> flight
酒店 / 入住 / 退房 -> hotel
股票 / 基金 / 炒股 -> out_of_scope

这些规则快、便宜、可控。

但问题也很明显：正则很容易越写越厚，最后变成一张很难维护的网。

比如：

1
2
3
4
5
6
7

住哪来着
住宿在哪
我们那天睡哪
酒店离机场远吗
这个地方适合老人吗
这篇先放着
这个加进去

它们表达的是相近意思，但关键词不一定稳定。继续补正则，短期能解决一个 case，长期会出现几个问题：

1
2
3
4
5

覆盖不全：用户换个说法就识别不到
误伤：关键词出现在无关语境里也会命中
边界重叠：同一句话同时像 memory、general、itinerary
难以解释：规则越多，最后很难知道为什么命中
难以回归：修一个 case，可能弄坏另一个 case

后续可以有下边的优化点：

1. 把单意图升级成多意图

现在系统本质上还是单意图。

比如：

1

机酒帮我整理一下

它其实同时包含：

1
2

flight
hotel

再比如：

1

这篇攻略不错，帮我加到第 3 天

它可能同时包含：

1
2

memory
itinerary

现在只能选一个主意图，后面更合理的是输出：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "intents": [
    {
      "intent": "memory",
      "priority": 1
    },
    {
      "intent": "itinerary",
      "priority": 2
    }
  ]
}

然后由流程决定是串行处理、追问确认，还是只执行其中一个。

2. 引入 Slot Filling，而不是只判断 intent

现在已经让模型分类结果里可以带 slots，但业务上还没有充分利用。

这一步其实就是意图识别里很关键的 Slot Filling。

Intent 解决的是：

1

用户想做什么？

Slot Filling 解决的是：

1
2

这件事需要哪些关键信息？
这些信息现在齐了吗？

比如用户说：

1

把这个加到第 3 天

只识别出 itinerary 还不够，还要抽出：

1
2
3
4
5
6
7
8
9

{
  "intent": "itinerary",
  "slots": {
    "day": 3,
    "target": "这个",
    "write_action": true,
    "missing": ["具体要加入的内容"]
  }
}

再比如：

1

这篇西班牙攻略加入资料 https://example.com

应该得到：

1
2
3
4
5
6
7
8
9

{
  "intent": "memory",
  "slots": {
    "url": "https://example.com",
    "destination": "西班牙",
    "save_action": true,
    "material_type": "攻略"
  }
}

这样系统不只是知道用户“想保存资料”，还能知道保存什么、是否和当前行程有关、缺不缺关键字段。

如果关键槽位缺失，就应该进入：

1

clarify

而不是继续执行。

3. 把正则从「业务判断」降级成「候选召回」

现在有些正则还承担最终判断职责。后面应该把它们改成候选召回。

也就是说，正则不再直接决定最终意图，而是先召回可能的候选：

1
2
3
4
5
6
7
8

命中“酒店/住宿/住哪”
=> 候选：hotel、general

命中“加入资料/保存”
=> 候选：memory、clarify

命中“第 3 天/今天”
=> 候选：day_query、itinerary

然后再结合上下文、槽位完整度、模型复判，决定最终走哪条链路。

这样正则的角色会更轻，也更可维护。

4. 把规则拆成可配置的意图词表

现在规则主要写在代码里，改起来快，但长期会膨胀。

后面可以把它拆成配置：

1
2
3
4
5
6
7
8
9
10
11

{
  "hotel": {
    "keywords": ["酒店", "入住", "退房", "住哪", "住宿"],
    "negativeKeywords": ["酒店股票", "酒店集团财报"],
    "requiredSignals": ["travel_scope"]
  },
  "memory": {
    "keywords": ["攻略", "游记", "加入资料", "保存"],
    "requiredSignals": ["url", "travel_context"]
  }
}

这样新增表达不用一直改代码，也更容易做评测和版本管理。

5. 用 Embedding 或检索替代一部分正则

有些表达靠关键词很难覆盖，比如：

1
2
3
4

这个适合带老人去吗
这条路线会不会太累
我们住那边方便吗
这篇先放着回头看

这类更适合用相似样本召回。

比如系统里沉淀一些已标注样本：

1
2
3

这个适合带老人去吗 -> general, slots: { topic: "suitability" }
这条路线会不会太累 -> general, slots: { topic: "route_intensity" }
这篇先放着回头看 -> clarify 或 memory

新输入来了以后，先用 Embedding 找相似样本，再把这些样本作为 few-shot 给便宜模型。

这比无限补正则更自然。

6. 做更细的澄清策略

现在 clarify 只是一个意图。

但追问本身也可以分类型：

1
2
3
4
5
6

缺少旅行语境
缺少目标日期
缺少写入确认
缺少附件类型
多个意图冲突
槽位不完整

不同原因应该问不同的问题。

比如：

1

https://example.com 加入资料

应该问：

1

这个链接和当前旅行有什么关系？是攻略、酒店、门票，还是其他参考资料？

而不是泛泛地说「请补充信息」。

7. 建一套意图识别评测集

现在主要靠手动测试。

后面应该把典型输入沉淀成测试集，例如：

1
2
3
4
5
6

股票买哪个 -> out_of_scope
第 3 天干嘛 -> day_query
这个地方安全吗 -> general
https://example.com 加入资料 -> clarify
这篇西班牙攻略加入资料 https://example.com -> memory
机酒帮我整理一下 -> flight + hotel

每次改规则或 Prompt，都跑一遍评测。

否则意图识别很容易出现「修好一个，弄坏另一个」的情况。

8. 记录准确率、延迟和成本

意图识别不是只看准不准，还要看：

1
2
3
4
5
6
7
8

规则命中率
模型调用率
平均延迟
单次成本
clarify 比例
out_of_scope 比例
模型采纳率
槽位缺失率

如果模型调用率太高，说明规则层不够好。

如果 clarify 太多，说明系统太保守。

如果 memory 误判高，说明 URL 和保存动作的边界还要继续收紧。

如果槽位缺失率高，说明很多意图不该直接执行，而应该先追问。

这些指标会比单次 Debug 更有价值。

总

如果把大模型看成发动机，意图识别就是方向盘。

没有方向盘，发动机越强，跑偏得越快。

一个好的意图识别系统，不是追求一次判断永远正确，而是要做到：

1
2
3
4
5

明确的，快速处理
模糊的，谨慎追问
越界的，及时拒绝
复杂的，交给模型辅助
执行的，始终由代码兜底

Agent 开发中，一部分还是传统的工程，一部分是让渡给大模型，这个度的把握也挺有意思。测试也变得困难起来，因为面对的输入变成了无穷多，不再像之前一样把固定链路测了即可。

文章中大部分知识都是看极客时间的「AI Agent 系统设计面试现场」，这里也推荐下，感兴趣的同学也可以看下，比我这里提到的会更系统。

从 https://coursesub.top/ 这里去买的话可以省 18 元。

文章主要基于最近很火 https://github.com/bojieli/ai-agent-book 《深入理解 AI Agent》（作者和 Agent 合作完成的一本书）第一章和最近总结的 claude code 源码 分析的有感而写，前端失业转 Agent 开发中，有不对的地方感谢指出

Agent = 大模型 + 上下文 + 工具

那最近一直说的 Harness 又是什么？

通过 ReAct 循环很容易把 大模型 + 上下文 + 工具串起来，实现一个 Agent。

用户提出问题，模型先思考当前应该做什么，然后调用工具行动，再观察工具返回的结果并继续思考下一步， 把整个过程的模型返回、工具执行结果这些上下文每次都带给模型，思考 -> 行动 -> 思考 -> 行动 … ，直到完成任务。

把之前这篇文章 一文入门 Agent 的代码拿过来：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

def solve(self, question: str, verbose: bool = True) -> str:
        """
        使用 ReAct 模式解决问题
        
        Args:
            question: 用户问题
            verbose: 是否显示详细过程
            
        Returns:
            最终答案
        """
        messages = [
            {"role": "system", "content": self._get_system_prompt()},
            {"role": "user", "content": question}
        ]
        
        for step in range(self.max_steps):
            if verbose:
                print(f"\\n=== 步骤 {step + 1} ===")
                
            # 获取模型响应
            try:
                assistant_message = self._call_llm(messages)
                if verbose:
                    print(f"Assistant: {assistant_message}")
                    
                messages.append({"role": "assistant", "content": assistant_message})
                
                # 检查是否包含最终答案
                if"Final Answer:"in assistant_message:
                    final_answer = assistant_message.split("Final Answer:")[-1].strip()
                    if verbose:
                        print(f"\\n🎉 找到答案: {final_answer}")
                    return final_answer
                
                # 解析并执行行动
                action_result = self._parse_action(assistant_message)
                if action_result:
                    tool_name, params = action_result
                    observation = self._execute_tool(tool_name, params)
                    
                    if verbose:
                        print(f"🔧 执行工具: {tool_name}")
                        print(f"📋 参数: {params}")
                        print(f"👁️ 观察结果: {observation}")
                    
                    # 添加观察结果到对话历史
                    messages.append({
                        "role": "user", 
                        "content": f"Observation: {observation}"
                    })
                else:
                    # 如果没有找到有效的行动，继续下一轮
                    if verbose:
                        print("⚠️ 未找到有效的行动，继续思考...")
                        
            except Exception as e:
                error_msg = f"API 调用错误: {str(e)}"
                if verbose:
                    print(f"❌ {error_msg}")
                return error_msg
                
        return"达到最大步数限制，未能找到答案。"

然后看似就实现了一个非常通用的问答 Agent

程序不再限制用户可以问什么类型的问题、问题格式是什么，使用什么工具、拿到结果下一步怎么做也不再写死逻辑到代码里，变成了大模型指挥一切。

程序好像一下子附上了魔法，但这算实现了 Agent，到此结束了吗？

一个能跑的 Demo 和一个可靠的产品之间还有巨大的鸿沟，而这些脆弱点正是 Harness 工程要解决的问题。

模型可能产生幻觉（编造不存在的工具或参数）、选错工具，或在遇到错误时无法自我恢复，生产系统还要加入约束、验证和纠正。

Harness 负责把模型放进一个可控的运行环境里：

• 给模型准备上下文：系统提示词 、工具定义、用户消息、模型回复、工具执行结果
• 暴露工具接口：搜索、读写文件、调用 API、执行代码等。
• 约束行为：哪些能做，哪些要用户确认，哪些绝对不能做。
• 验证结果：工具调用是否成功，产物是否满足要求，状态是否真的改变。
• 纠正失败：重试、回滚、换策略、熔断、交给人。

所以文章开头 「Agent = 大模型 + 上下文 + 工具」只是最小工程实现，一个真正能可靠做事的 Agent 应该是：

Agent = 大模型 + Harness

Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正

知道了 Harness 的概念，接下来就有另一个常常探讨的问题：如果模型持续变强，今天这些 Harness 会不会最终被模型「吃掉」？

模型可以通过后训练将工具调用能力内化为原生能力，慢慢的蚕食 Harness，公式未来可能再次简化为 Agent = 大模型，「模型即 Agent（Model as Agent）」。

比如 KimiK3 通过强化学习训练，将工具调用的决策策略内化为原生能力——何时调用工具、调用哪个、传什么参数都由模型自主决定，从而能够自主完成网络搜索等任务。

GPT-5.6 通过后训练将 Deep Research 式的任务编排策略内化为原生能力——何时澄清用户意图、何时搜索网络、何时调用代码解释器分析数据、何时继续补充信息，都由模型自主决定。

坏消息是节奏确实是这么个节奏，好消息是此刻还没有，这个「吃」的过程远比想象中慢。模型无法一次内化真实业务中所有的约束与偏好，模型此刻的能力边界，就是 Harness 此刻的价值所在。

模型自主决策的空间越大，出错时的影响面也越大，因此需要更精细的约束、验证和纠正机制来确保可靠性。模型还做不稳的，Harness 先补上；模型每内化一层，Harness 就卸下一层，转而兜底新的能力前沿。

继续，Harness 是最终答案了吗？

最早大家做 Prompt Engineering，重点是「怎么把一句话写好」，让模型回答得更准。

后来发现光写 prompt 不够，于是进入 Context Engineering：不只是改一句提示词，而是管理模型能看到的全部信息，比如系统提示词、工具说明、历史对话、知识库、用户记忆。核心问题变成：模型该看到什么？

再往后是 Harness Engineering：光让模型看到还不够，还要让它「可靠地行动」。所以要设计工具接口、权限约束、结果验证、错误恢复、反馈循环。核心问题变成：模型运行在什么样的工程外壳里？

然后是 Loop Engineering：关注点从一次任务运行，扩展到长时间、多轮次的持续执行。比如 Agent 下一步该做什么、什么时候检查结果、什么时候才能真的停下来。核心问题变成：怎么让 Agent 持续推进任务，而不是中途偷懒、卡死或假装完成？

最后是 Graph Engineering：把多个 Agent 循环、普通程序、人类审批步骤都组织成一个明确的执行图。哪个节点做什么，结果流向哪里，什么时候持久化状态，都由图结构管理。核心问题变成：怎么把多个能力单元编排成一个可控系统？

概念越来越多，也不用担心之前的段子「AI 领域只要学的慢就不用学了」，这些概念并不是跳变，而是后者包含前者，层层包含，核心是一个共同目标「设计一个可靠、可验证、可持续运行的 Agent 产品」。

Agent 岗位的出现，也正是因为当各家模型的能力越来越接近、不再是决定性的差异因素时，竞争优势就转移到了模型之外的工程实践。

而工程实践可能要考虑到一些东西：

• 选择模型：开源的、闭源的、多模态的、带推理的、成本、速度，要选最适合真实任务、预算、策略边界和交互形式的模型

• 编排模式：上下文如何在多次模型调用之间流动，工具如何被调度，执行路径是预先写死（工作流模式），还是由模型动态决定（自主 Agent 模式）。

• 安全性：降低提示注入、越权操作、隐私泄露、错误执行等问题。在信息进入上下文前过滤无关、有害或恶意内容；在工具调用或回复生效前检查权限、风险等级和输出内容，高风险操作可要求人工确认；通过数据库权限、行级安全、约束校验等机制阻止越权修改。

软件工程有设计模式，比如之前总结的前端设计模式 pattern.windliang.wang （时代的眼泪），Agent 工程当然也会发展出来：

• 提议者—审核者：生成和评判分离：一个角色产出，另一个独立角色只看结果、测试或结构化证据来判断，避免同一个 Agent 自审。
• 渐进式披露：不把所有信息一次性塞进上下文，而是先给目录，再按需加载细节，以节省上下文并提高选择精度。
• 只增不改：状态以追加方式演进，已经写下的内容不轻易改动，从而便于缓存、重放和审计。
• 边界集 + 保留集：每次修改同时验证「应该被改变的样本」和「不应该被影响的样本」，避免过拟合或无效修改。
• 最小 diff + 可回滚：每次改动尽量小、来源清楚、可以单独撤回，方便出问题时定位和恢复。

最后再来三个原则：

• 保持简单，从最直接的方案开始，只有确实需要时才增加框架和抽象，因为复杂度会增加调试盲区；
• 保持透明，让 Agent 的计划、执行日志和关键决策可观察，方便调试，也让用户知道系统为什么这样做；
• 设计好工具接口，从 Agent 的视角设计清晰、直观、不易误用的工具名称和参数，把错误尽量消除在接口设计阶段，而不是指望模型每次都猜对。

AI 时代的巨轮滚滚向前，前端经历了从切图仔、到从后端剥离为独立岗位、到欣欣向荣、到前端已死、再到现在的合并回后端岗位，和后端一起又回到了全栈岗位。

好消息是当然也带来了新的岗位「Agent 开发」，像之前所说的，工具在变，但核心还是解决问题。过去的积累也不是全部没用了，做工程化的东西很多东西都还在（处理状态、接入接口、权限控制、记录日志、做监控、优化体验等等），只是多在程序中引入了一个大脑，而且很多东西还可以和 AI 探讨、让 AI 实现。

当选择了程序员的道路，就代表拥抱了终身学习，加油、共勉。

title: 2、CC 的心脏：queryLoop Agent 主循环

上一篇最后停在 launchRepl() 和 runHeadless()：一次会话已经准备好了，模型、权限、Tools、Skills、Agents 和 MCP 也已经装进了运行环境。

这篇文章讲一个最核心的问题：假设用户只输入「检查登录模块」，Claude Code 为什么会自己搜索文件、读取源码，最后再给出答案？

答案就在 src/query.ts 的 queryLoop() 中。

它做的事情其实很朴素：

1. 把当前消息发给模型；
2. 模型如果要求调用 Tool，Claude Code 就执行 Tool；
3. 把 Tool Result 放进消息，再次请求模型；
4. 模型不再调用 Tool 时，结束循环。

图里的 messages 会逐轮累积，不是每轮重新创建一份只有新结果的消息：

1
2
3
4
5
6
7
8
9
10
11
12
13

turnCount = 1
// messages.length => 1
// [用户问题]

turnCount = 2
// messages.length => 3
// [用户问题, Grep tool_use, Grep tool_result]

turnCount = 3
// messages.length => 5
// [用户问题,
//  Grep tool_use, Grep tool_result,
//  Read tool_use, Read tool_result]

这里最关键的一点是：

模型只会生成「我要调用 Grep」这样的 tool_use。真正搜索文件的是 Claude Code 进程，不是模型。

因此，一次用户输入不等于一次模型请求。

本文的例子中，用户只输入了一句话，但 queryLoop() 请求了三次模型。前两次模型要求使用 Tool，第三次才产生最终答案。

主循环可以精简成下面的伪代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// 等价简版，用于理解主线，不是源码原文
async function* simplifiedQueryLoop(state) {
  while (true) {
    // 1. 用当前 messages 请求模型
    const assistantMessages = []

    for await (
      const message of callModel(state.messages)
    ) {
      yield message

      if (message.type === 'assistant') {
        assistantMessages.push(message)
      }
    }

    // 2. 找出模型真正返回的 Tool Use
    const toolUseBlocks =
      findToolUseBlocks(assistantMessages)

    // 3. 没有 Tool Use，任务结束
    if (toolUseBlocks.length === 0) {
      return {
        reason: 'completed',
      }
    }

    // 4. 执行 Tool，逐个收集 Tool Result
    const toolResults = []

    for await (
      const update of runTools(toolUseBlocks)
    ) {
      if (update.message) {
        toolResults.push(update.message)
      }
    }

    // 5. 把模型消息和 Tool Result 交给下一轮
    state = {
      ...state,
      messages: [
        ...state.messages,
        ...assistantMessages,
        ...toolResults,
      ],
      turnCount: state.turnCount + 1,
    }
  }
}

后面的大部分源码，都是在给这五步增加生产环境需要的能力，例如权限检查、流式输出、上下文压缩、Fallback、Hook 和中止处理。这一篇只看主循环，其他机制后面再展开。

这篇文章专注于主循环的流程，主要是三点：

1. 模型怎样产生 tool_use；
2. Claude Code 怎样执行 Tool 并生成 tool_result；
3. 新消息怎样进入下一轮，循环最后怎样结束。

循环入口

交互模式下，REPL 会把第一篇组装好的消息、Prompt 和 ToolUseContext 传给 query()：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// src/screens/REPL.tsx:2793-2803
for await (
  const event of query({
    messages: messagesIncludingNewMessages,
    // => [{
    //   type: 'user',
    //   message: {
    //     role: 'user',
    //     content: '检查登录模块',
    //   },
    // }]

    systemPrompt,
    userContext,
    systemContext,
    canUseTool,

    toolUseContext,
    // => {
    //   options: {
    //     mainLoopModel: 'claude-sonnet-4-6',
    //     tools: [
    //       { name: 'Read', ... },
    //       { name: 'Edit', ... },
    //       { name: 'Grep', ... },
    //       { name: 'Glob', ... },
    //       { name: 'Bash', ... },
    //     ],
    //     commands: [...],
    //     thinkingConfig: { type: 'adaptive' },
    //   },
    //   abortController: AbortController,
    //   getAppState: () => AppState,
    //   setAppState: function,
    // }
    // 其中 getAppState().toolPermissionContext.mode => 'plan'

    querySource: getQuerySourceForREPL(),
    // => 'repl_main_thread'
  })
) {
  onQueryEvent(event)
}