企业官网建设流程全解析

1. 从 JSONL 到 AgentLoop：Pi Session 工作流程里最容易踩坑的衔接点

如果你正在本地调试 AI Agent，大概率遇到过这种场景：JSONL 文件里明明写满了 user、assistant、toolResult 三类记录，可 AgentLoop 跑起来之后，模型看到的上下文却和文件里对不上——要么少了一轮工具结果，要么分支选错了叶子节点，要么配置变更没生效。Pi 的 Session 设计把「持久化」和「运行时」拆成了两层，JSONL 是账本，AgentLoop 是记账员，中间靠buildSessionContext这个纯函数做翻译。理解这三者的衔接机制，比单纯记住事件名重要得多。

这篇是 Pi Session 工作流程解析的第二篇，聚焦 JSONL 会话记录与 AgentLoop 的衔接。我会先讲清楚message_end、turn_end、agent_end三层生命周期边界到底怎么嵌套，再给出可复制的 TaoToken 统一 Key/API 通道配置片段（含 endpoint 与auth.json示例），最后演示一次完整的会话回放验证动作，确认 AgentLoop 在多轮 Session 中的状态流转正确。适合已经在本地跑通 Pi、想进一步排查「为什么回放结果和预期不一致」的开发者。

核心检索词先摆出来：Pi Session 是什么、能做什么、适合谁。Pi Session 是 Pi 这个 Coding Agent 框架里的会话层，负责把对话和它发生的所有上下文当成可追加的事件日志来存；它能做断电恢复、分支追溯、压缩回滚、配置留痕；适合本地调试 AI Agent、需要多轮工具调用、想自己掌控会话数据的开发者。JSONL 是它的默认存储格式，一行一条SessionTreeEntry，cat就能读。

我试过在本地反复回放同一个 JSONL，发现最容易出问题的不是写入，而是「读回来之后 AgentLoop 拿到的上下文和写入时的意图不一致」。下面按衔接顺序拆开讲。

2. 三层生命周期边界：message_end、turn_end、agent_end 的嵌套关系与 JSONL 落盘时机

很多人第一次看 Pi 的事件流，会把message_end、turn_end、agent_end当成三个并列事件。实际上它们是三层嵌套的生命周期边界：一次 Agent 运行包含多个 turn，一个 turn 包含多条 message。从外到内是agent_start/agent_end→turn_start/turn_end→message_start/message_update/message_end。

message_end是 Session 落盘的最小单位。它一触发，那条消息就立刻appendEntry写进 JSONL。user prompt 没有流式，message_start之后马上message_end；assistant 有流式，message_update会触发 N 次，直到message_end才把最终内容写盘。toolResult 同理，执行完就写。这意味着「AI 一句话讲完就落盘」，断电也不丢用户已经看到的字。

turn_end是真正的「工作单元」边界。一个 turn = 一次 assistant 回复 + 它触发的所有工具调用 + 所有 toolResult。turn 结束后，harness 才会去检查「要不要换模型、要不要压缩、要不要插入 steer 消息」，这些批量配置变更（model_change、thinking_level_change、active_tools_change）在turn_end时统一落盘，避免每改一个就写一次磁盘。turn_end也是prepareNextTurn钩子的触发点。

agent_end是「是否还活着」的信号。它带messages: AgentMessage[]，即这次 run 新产生的所有消息，并发settled事件让 TUI 知道可以解锁输入框。如果长时间没收到，TUI 知道 Agent 还在忙。

实际时序（参考agent-loop.ts的事件发射顺序）大致是这样：

emit({ type: "agent_start" }) // 整个 loop 启动 1 次 emit({ type: "turn_start" }) // 第一个 turn 开始 emit({ type: "message_start", prompt }) // user prompt emit({ type: "message_end", prompt }) // user prompt 立刻结束（无流式） emit({ type: "message_start", assistantPartial }) emit({ type: "message_update", ... }) // 流式过程中触发 N 次 emit({ type: "message_end", assistantFinal }) // 如果有工具调用： emit({ type: "tool_execution_start", ... }) emit({ type: "tool_execution_end", ... }) emit({ type: "message_start", toolResult }) emit({ type: "message_end", toolResult }) emit({ type: "turn_end", message, toolResults }) // turn 边界，批量 flush 配置变更 // 如果需要继续（assistant 还要看 toolResult 再回话）： emit({ type: "turn_start" }) // 开新 turn // ... 再次流式 assistant ... emit({ type: "turn_end", ... }) // 直到 assistant stopReason === "stop" emit({ type: "agent_end", messages }) // 整个 loop 收尾

这里有个常见误解必须点破：agent_start/agent_end≠ 一次 Session。Session 是整本对话笔记本，可能跨多个工作日、几百条消息；而agent_start/agent_end只是「AI 响应一次用户输入」的完整流程。一次 Session 里会有很多次agent_start/agent_end。用算账的方式理解：

一次 Session = N 次agent_start/agent_end（你每说一句话算一次） 一次agent_start/agent_end= 1~M 次turn_start/turn_end（AI 调一次工具就多一个 turn） 一次turn_start/turn_end= 2~K 条消息（user + assistant + 0~N 个 toolResult）

所以三层事件和 Session 的关系是：Session 是账本，三层事件是「这次记账里具体写哪几行、什么时候结算」。把agent_start/agent_end误当成 Session，是排查回放问题时第一个要排除的认知偏差。

批量写的取舍也很明确：减少 IO 次数，但若程序在中途崩溃，最后一小段配置变更可能丢失——不过用户消息和 AI 回复都已经写盘了，不会丢对话内容。这个取舍在本地调试时尤其要注意：如果你在turn_end之前强杀进程，model_change这类配置可能没落盘，回放时模型 ID 会对不上。

3. TaoToken 前置：统一 Key/API 通道配置片段（endpoint + auth.json 示例）

在讲 AgentLoop 怎么读 JSONL 之前，先把模型通道配好。Pi 这类本地 Agent 框架通常允许你自定义 Base URL 和 Key，我用 TaoToken 的统一通道来演示，因为它把多家模型的 endpoint 收敛成一个，回放时不用来回改配置。

TaoToken 的 API 地址是https://taotoken.net/api，官网是https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。注意 API 地址不带 UTM 参数，直接用于请求。

先看auth.json示例。Pi 的认证配置一般放在项目根目录或用户配置目录下，字段名以你本地版本为准，下面这份是可复制的结构：

{ "providers": { "taotoken": { "type": "openai-compatible", "baseURL": "https://taotoken.net/api", "apiKey": "sk-你的TaoTokenKey", "models": { "default": { "id": "claude-sonnet-4-20250514", "maxTokens": 8192 }, "fast": { "id": "gpt-4o-mini", "maxTokens": 4096 } } } }, "defaultProvider": "taotoken" }

如果你用的是 TOML 风格的配置（部分 Pi 版本或周边工具支持），等价写法：

[providers.taotoken] type = "openai-compatible" baseURL = "https://taotoken.net/api" apiKey = "sk-你的TaoTokenKey" [providers.taotoken.models.default] id = "claude-sonnet-4-20250514" maxTokens = 8192

三件套必须写全：Base URL、Key、Model ID。少任何一个，AgentLoop 在prepareNextTurn阶段就会报错。Model ID 要和你在 TaoToken 控制台看到的模型名一致，写错了会在流式阶段返回reading choices相关错误。

如果你用 Claude Code 或类似的 CLI 工具，环境变量方式也可以：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的TaoTokenKey" export ANTHROPIC_MODEL="claude-sonnet-4-20250514"

配置好之后，先别急着跑 AgentLoop，用一条最小请求验证通道：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 16 }'

返回里有choices数组就说明通道通了。这一步很重要，因为后面 AgentLoop 回放失败时，你要能区分是「通道问题」还是「Session 衔接问题」。通道验证通过后，再进入 JSONL 回放环节。

4. 可复制配置与验证请求：一次完整的会话回放确认 AgentLoop 状态流转

现在进入正题：怎么用一份 JSONL 回放，确认 AgentLoop 在多轮 Session 中的状态流转正确。核心思路是——JSONL 是账本，buildSessionContext是翻译器，AgentLoop 是消费者。回放就是让翻译器重新读一遍账本，看它吐出的SessionContext和当初写入时的意图是否一致。

先看一份简化的 JSONL 会话记录，每行一个SessionTreeEntry：

{"id":"e1","parentId":null,"type":"message","role":"user","content":"帮我读一下 config.json","ts":1710000001} {"id":"e2","parentId":"e1","type":"message","role":"assistant","content":"好的，我来读取。","ts":1710000002} {"id":"e3","parentId":"e2","type":"tool_call","tool":"read_file","args":{"path":"config.json"},"ts":1710000003} {"id":"e4","parentId":"e3","type":"message","role":"toolResult","content":"{\"port\":8080}","ts":1710000004} {"id":"e5","parentId":"e4","type":"message","role":"assistant","content":"端口是 8080。","ts":1710000005} {"id":"e6","parentId":"e5","type":"config_change","key":"model_change","value":"gpt-4o-mini","ts":1710000006} {"id":"e7","parentId":"e6","type":"message","role":"user","content":"换成小模型再总结一遍","ts":1710000007}

注意e6这条config_change，它是在turn_end时批量落盘的。回放时如果 AgentLoop 没读到它，e7之后的请求还会用旧模型。

回放验证的代码骨架（TypeScript，示意）：

import { Session } from "./session"; import { buildSessionContext } from "./session"; import { runAgentLoop } from "./agent-loop"; async function replay(jsonlPath: string) { const session = await Session.loadFromJSONL(jsonlPath); const branch = session.getBranch(); // 从根到当前叶子的全部条目 const context = buildSessionContext(branch); // 扁平化成一维消息流 console.log("回放上下文条数:", context.messages.length); console.log("当前模型:", context.activeModel); console.log("当前工具集:", context.activeTools); const result = await runAgentLoop({ context, provider: "taotoken", baseURL: "https://taotoken.net/api", apiKey: process.env.TAOTOKEN_API_KEY, }); console.log("stopReason:", result.stopReason); console.log("新产生消息数:", result.messages.length); } replay("./sessions/demo.jsonl");

跑完之后重点看三个输出：context.messages.length是否等于 JSONL 里从根到叶子的消息条数；context.activeModel是否等于最后一条config_change的值；result.stopReason是否为stop。这三个对上了，说明buildSessionContext的翻译和 AgentLoop 的消费是一致的。

这里有个微妙之处：同一回合内buildContext会被调用两次——一次在prepareNextTurn（AgentHarness 准备上下文），一次在runAgentLoop内部（真正调 LLM 前）。因为prepareNextTurn会先注入 steer 消息，再让 AgentLoop 拿到最新上下文。回放时如果你只调了一次buildSessionContext，可能漏掉 steer 注入带来的差异。

验证请求本身可以用 TaoToken 的模型对话通道快速确认模型侧是否正常，但真正的状态流转确认靠的是上面这段回放代码的输出对比。建议把回放前后的context做一次 diff，尤其是activeTools和activeModel这两个字段。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 对照

回放过程中最常见的四类报错，我按实际遇到的频率排一下。

第一类：401 Unauthorized。这个基本是 Key 问题。检查auth.json里的apiKey是否和 TaoToken 控制台一致，注意有没有多余空格或换行。如果你用环境变量，确认ANTHROPIC_API_KEY或对应变量在当前 shell 里生效。还有一种情况是 Base URL 写成了带 UTM 的官网地址，请求打到了网页而不是 API，也会 401。记住 API 地址是https://taotoken.net/api，不带参数。

第二类：local proxy failed。这个报错通常出现在你本地配了某个转发层，但转发层没起来或者端口不对。排查顺序：先确认本地转发进程是否在跑，再确认baseURL指向的端口和转发层监听端口一致。如果你没配转发层却报这个错，检查是不是某个环境变量残留了旧的代理地址。清掉之后重启终端再试。

第三类：reading choices相关错误。这个一般出现在流式响应解析阶段，说明返回的 JSON 结构和 AgentLoop 预期的对不上。常见原因是 Model ID 写错了，或者请求里带了模型不支持的参数（比如某些模型不支持thinking字段）。对照 TaoToken 控制台里的模型名，把auth.json里的id改对。如果还报，把max_tokens调小到 1024 再试，排除是响应过大导致解析中断。

第四类：OAuth相关报错。如果你用的是 Claude Code 这类带 OAuth 流程的工具，报 OAuth 错误通常是因为它优先走了官方登录态，没走你配的 API Key。这时候要显式指定用 API Key 模式，或者在配置里把 OAuth 相关字段清掉。CC Switch 这类工具切换配置时，也要确认切换后 Base URL、Key、Model ID 三件套都更新了，别只换了 Key。

排查时有个通用方法：把 AgentLoop 的日志级别调到 debug，看它实际发出的请求 URL 和 headers。URL 不对就是配置问题，headers 里 Authorization 不对就是 Key 问题，返回体结构不对就是 Model ID 或参数问题。这三层分清楚，大部分报错都能定位。

另外提醒一句：JSONL 文件本身的问题也会伪装成上述报错。比如某行 JSON 格式坏了，Session.loadFromJSONL解析到那一行会抛异常，但错误信息可能被上层包装成别的样子。回放前先用jq或python -m json.tool逐行校验一遍 JSONL，能省很多时间。

6. 语义一致 CTA：把回放跑通之后继续往下走

回放跑通、stopReason为stop、activeModel和最后一条config_change对上之后，说明你的 JSONL 到 AgentLoop 这条链路是通的。接下来如果要做更长时间的编码任务或者多轮 Agent 调度，可以考虑用 Coding Plan 来统一管理模型额度和通道，避免每次调试都手动换 Key。

配置过程中如果卡在 Key 或通道上，直接去 API Keys 页面生成和核对，接入细节看接入文档，里面有各语言的最小请求示例。想先验证某个模型在 TaoToken 上的响应质量，用模型对话页面发几条消息试试，比在 AgentLoop 里反复回放快得多。

回放验证这件事，我的经验是把它做成一个脚本，每次改完 Session 相关代码就跑一遍，输出context.messages.length、activeModel、activeTools、stopReason四个值，和历史基线对比。这样状态流转一旦出问题，你能立刻知道是哪一层的事件没衔接上，而不是等到线上跑飞了才回头翻 JSONL。