docs: 新增第10-13章(Provider与认证/Session树/Compaction/SDK)并优化阅读页

- 新增4章深入篇, 术语表移至第14章, 全景导读校准到15章
- 前端: 侧边栏收窄居中修正、UI柔化、暗色降刺眼、图片lightbox缩放
- 修复Markdown渲染: 表格内|转义、CJK加粗紧贴行内代码导致的**泄漏

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Albert-PZY

README.md

@@ -8,7 +8,7 @@
 
 Pi 是 Mario Zechner（libGDX 作者）开源的 TypeScript AI Agent 框架，核心理念是 **LLM + Tools + A Loop**——用最少的代码实现最大的灵活性，`agent-core` 仅约 1500 行。
 
-本文档从源码出发，用 11 个章节讲清 Pi 的完整架构，目标是**两三天内建立完整心智模型**：不只讲"怎么用"，更讲"为什么这么设计"。
+本文档从源码出发，用 15 个章节讲清 Pi 的完整架构，目标是**两三天内建立完整心智模型**：不只讲"怎么用"，更讲"为什么这么设计"。
 
 ## 章节目录
 
@@ -24,7 +24,11 @@ Pi 是 Mario Zechner（libGDX 作者）开源的 TypeScript AI Agent 框架，
 | [07](docs/07-context-engineering.md) | 上下文工程 | Compaction 压缩、分支摘要、动态 System Prompt |
 | [08](docs/08-session-management.md) | 会话管理 | Session Tree、JSONL 存储、Fork 分叉 |
 | [09](docs/09-extension-system.md) | 扩展系统 | Skills / Extensions / Prompt Templates |
-| [10](docs/10-glossary.md) | 术语表 | 60+ 术语按逻辑分组速查 |
+| [10](docs/10-provider-and-auth.md) | Provider 与认证 | 认证优先级、CredentialStore、OAuth 刷新、跨厂商 handoff |
+| [11](docs/11-session-tree.md) | Session 树与上下文构建 | Entry vs Message、`buildContextEntries` / `buildSessionContext`、分支操作 |
+| [12](docs/12-compaction-internals.md) | Compaction 内部机制 | 切点规则、Split Turn、检查点、结构化摘要 |
+| [13](docs/13-sdk-integration.md) | SDK 与嵌入集成 | `createAgentSession`、`AgentSessionRuntime`、三种 Run Mode |
+| [14](docs/14-glossary.md) | 术语表 | 60+ 术语按逻辑分组速查 |
 
 每章包含源码示例、PlantUML 架构图、检查清单，章节之间环环相扣。
 

docs/00-overview.md

@@ -161,18 +161,35 @@ note right: Agent 的"历史"
 :第9章 扩展系统;
 note right: Agent 的"成长"
 
-:第10章 术语表;
+:第10章 Provider 与认证;
+note right: 深入：认证怎么解析
+
+fork
+  :第11章 Session 树与上下文构建;
+  note right: 深入第8章
+fork again
+  :第12章 Compaction 内部机制;
+  note right: 深入第7章
+end fork
+
+:第13章 SDK 与嵌入集成;
+note right: 把 Pi 当库用
+
+:第14章 术语表;
 note right: 速查手册
 
 stop
 @enduml
 ```
 
+前 9 章是**主干**，建立从抽象层到扩展系统的完整认知；第 10–13 章是**深入篇**，往主干的关键节点再钻一层（认证、会话树、压缩、嵌入集成），可按需选读。
+
 **建议学习方式**：
 
 1. **第一天**：读完第 0-3 章，建立全局认知
 2. **第二天**：读完第 4-6 章，理解核心机制
 3. **第三天**：读完第 7-9 章，掌握高级特性
+4. **进阶**：按兴趣挑第 10-13 章深入；第 14 章术语表随时速查
 
 每章末尾有"检查清单"，确认自己理解后再进入下一章。
 

docs/09-extension-system.md

@@ -332,5 +332,5 @@ note bottom of MCP: Pi 没有内置 MCP\n但扩展可以桥接
 ---
 
 **上一章**：[第八章 · 会话管理](08-session-management.md)  
-**下一章**：[第十章 · 术语表](10-glossary.md) — 所有关键术语速查
+**下一章**：[第十章 · Provider 与认证](10-provider-and-auth.md) — 认证如何被解析
 

docs/10-provider-and-auth.md

@@ -0,0 +1,332 @@
+# 第十章 · Provider 与认证
+
+> 第二章讲了 pi-ai 如何用 `stream()` 统一 30+ 厂商。这一章往下钻一层：
+> **一个请求的认证是怎么被解析出来的**——从环境变量、凭据存储，到 OAuth 自动刷新。
+
+---
+
+## 10.1 Provider 是运行时的最小单元
+
+第二章把注意力放在 `stream()` 和 `Model` 上。但真正**持有状态**的是 Provider：
+
+```plantuml
+@startuml
+skinparam backgroundColor transparent
+
+rectangle "Models 集合" as M #FFF3E0 {
+  rectangle "anthropicProvider" as P1 #E8F5E9
+  rectangle "openaiProvider" as P2 #E3F2FD
+  rectangle "openrouterProvider" as P3 #F3E5F5
+}
+
+note bottom of P1
+  每个 Provider 自己拥有：
+  · 模型目录 (catalog)
+  · 认证 (API key / OAuth)
+  · stream 行为
+end note
+
+M --> P1
+M --> P2
+M --> P3
+
+@enduml
+```
+
+一句话区分：
+
+- **Provider** = 运行时单元，拥有目录、认证、流式行为
+- **Models** = 集合，把请求路由到"拥有该模型"的 Provider
+- **API 实现** = 底层线路协议（`anthropic-messages` / `openai-responses` / `openai-completions`），被多个 Provider 共享
+
+所以 xAI、Groq、Cerebras、OpenRouter 等大多复用 `openai-completions` 这一套 API 实现，差异只在 Provider 层的认证和 baseUrl。
+
+### 构建一个 Models 集合
+
+```typescript
+import { createModels } from '@earendil-works/pi-ai';
+import { anthropicProvider } from '@earendil-works/pi-ai/providers/anthropic';
+import { openaiProvider } from '@earendil-works/pi-ai/providers/openai';
+
+const models = createModels();
+models.setProvider(anthropicProvider());
+models.setProvider(openaiProvider());
+
+// 或者：一次注册所有内置 Provider（体积大，按需选择）
+// import { builtinModels } from '@earendil-works/pi-ai/providers/all';
+// const models = builtinModels();
+```
+
+按需注册（tree-shaking 友好）还是全量注册，是**包体积**和**便利性**的取舍——见第二章 2.3 的懒加载策略。
+
+## 10.2 认证解析的优先级
+
+当你调用 `models.stream()`，集合会通过"拥有该模型的 Provider"解析认证，再合并进请求。**显式传入的值永远最优先**：
+
+```plantuml
+@startuml
+skinparam backgroundColor transparent
+skinparam ActivityBackgroundColor #f8f9fa
+skinparam ActivityBorderColor #dee2e6
+
+start
+:models.stream(model, ctx, options);
+
+if (options.apiKey 显式传入?) then (yes)
+  :直接使用显式 key;
+  note right: 显式值胜过一切
+else (no)
+  if (CredentialStore 有存储凭据?) then (yes)
+    :使用存储凭据;
+    note right
+      存储凭据"拥有"该 Provider
+      有存储就不再看环境变量
+    end note
+  else (no)
+    if (环境变量已设置?) then (yes)
+      :使用环境变量;
+    else (no)
+      :解析失败 → stream error;
+    endif
+  endif
+endif
+
+:合并 headers / baseUrl;
+:发起请求;
+stop
+@enduml
+```
+
+关键规则：**存储凭据一旦存在，就"独占"该 Provider**。环境变量只在没有存储凭据时才被查询；OAuth 刷新失败绝不会静默回退到环境变量的 key——这是防止"看似成功、实则用错身份"的安全设计。
+
+### 不发请求也能查认证
+
+`getAuth()` 让你在不真正调用 LLM 的情况下检查解析结果：
+
+```typescript
+// 传 Provider ID：Provider 级认证
+const providerAuth = await models.getAuth(model.provider);
+
+// 传 model：额外并入该模型的静态 model.headers
+const modelAuth = await models.getAuth(model);
+
+if (modelAuth) {
+  console.log(`configured via ${modelAuth.source}`);
+  // e.g. "ANTHROPIC_API_KEY" / "OAuth" / "stored credential"
+  console.log(modelAuth.auth.headers);
+} else {
+  console.log('not configured');
+}
+```
+
+两种重载都会解析凭据、必要时刷新过期 OAuth，可能返回 `apiKey` / `headers` / `baseUrl`。未配置的 Provider 解析为 `undefined`；真正坏掉时抛 `ModelsError`（`"oauth"`=刷新失败但保留凭据以便重登，`"auth"`=key 解析或存储故障）。请求路径会把同样的失败作为 stream error 暴露。
+
+## 10.3 环境变量：最省事的入口
+
+Node 环境下，内置 Provider 会自动读取约定的环境变量（浏览器里没有环境变量，需显式传 `apiKey`）：
+
+| Provider | 环境变量 |
+|----------|---------|
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` 或 `ANTHROPIC_OAUTH_TOKEN` |
+| Google | `GEMINI_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Mistral | `MISTRAL_API_KEY` |
+
+> 完整表格见 [pi-ai README](https://github.com/earendil-works/pi/blob/main/packages/ai/README.md#environment-variables)。Amazon Bedrock 解析环境里的 AWS 凭据链（`AWS_PROFILE`、access key、`AWS_BEARER_TOKEN_BEDROCK` 等）；Vertex AI 解析显式 key 或 gcloud ADC + 项目/区域。
+
+## 10.4 CredentialStore：凭据存储
+
+交互式输入的 API key、OAuth token 都存在 `CredentialStore` 里——每个 Provider 一条带类型标签的凭据。pi-ai 默认给一个内存实现，应用注入持久化实现：
+
+```typescript
+import { createModels, type CredentialStore } from '@earendil-works/pi-ai';
+
+const models = createModels({ credentials: myFileBackedStore });
+```
+
+接口很小，只有五个动作：
+
+```typescript
+interface CredentialStore {
+  read(providerId): Promise<Credential | undefined>;
+  list(): Promise<Array<{ providerId; type }>>;   // 只返回非敏感元数据
+  modify(providerId, fn): Promise<void>;          // 唯一写入路径
+  delete(providerId): Promise<void>;
+}
+```
+
+三个设计要点：
+
+1. **`modify` 是唯一写入路径**——它是一次串行化的 read-modify-write。OAuth token 刷新就跑在 `modify` 里，所以并发请求、多个进程都不会重复刷新同一个已轮换的 token。
+2. **`list()` 不得解析 secret**，也不能执行配置的 key 命令——枚举必须廉价且安全。
+3. API key 凭据用和 pi 的 `auth.json` 相同的判别式，可携带 Provider 作用域的 env/config 值（如 `CLOUDFLARE_ACCOUNT_ID`）。
+
+## 10.5 OAuth：登录与自动刷新
+
+部分 Provider 支持 OAuth，而非静态 API key：
+
+- **Anthropic**（Claude Pro/Max 订阅）
+- **OpenAI Codex**（ChatGPT Plus/Pro 订阅）
+- **GitHub Copilot**（Copilot 订阅）
+- **OpenRouter**（PKCE 流程，铸造一个用户可控的 API key）
+
+每个这样的 Provider 在 `provider.auth.oauth` 上带一个 `OAuthAuth`，有三个操作：
+
+```plantuml
+@startuml
+skinparam backgroundColor transparent
+
+rectangle "OAuthAuth" {
+  rectangle "login(interaction)" as L #E8F5E9
+  rectangle "refresh(credential)" as R #E3F2FD
+  rectangle "toAuth(credential)" as T #FFF3E0
+}
+
+note bottom of L: 用中立的 prompt/notify 协议\n驱动登录，返回凭据
+note bottom of R: 刷新即将过期的凭据\n(OpenRouter 是 no-op)
+note bottom of T: 从凭据派生请求认证\n(Copilot 的 baseUrl 来自这里)
+
+@enduml
+```
+
+**刷新是自动的**：`models.getAuth(providerId)` 和请求路径都会在凭据存储的锁内刷新过期 token，所以并发请求、多进程都不会重复刷新。OpenRouter 因为拿到的是永久 key，其 refresh 是空操作。
+
+驱动登录的入口是 `models.login()`：
+
+```typescript
+const models = createModels({ credentials: myStore }); // 持久化 store
+models.setProvider(anthropicProvider());
+
+await models.login('anthropic', 'oauth', {
+  prompt: async (p) => {
+    // p.type: 'text' | 'secret' | 'select' | 'manual_code'
+    return await askUser(p.message);
+  },
+  notify: (event) => {
+    if (event.type === 'auth_url') console.log(`打开: ${event.url}`);
+    if (event.type === 'device_code')
+      console.log(`Code: ${event.userCode} at ${event.verificationUri}`);
+  },
+});
+
+// 之后请求自动解析并刷新 token
+await models.complete(models.getModel('anthropic', 'claude-sonnet-4-5')!, ctx);
+
+// 登出
+await models.logout('anthropic');
+```
+
+CLI 里最快的登录方式：
+
+```bash
+npx @earendil-works/pi-ai login              # 交互式选择 Provider
+npx @earendil-works/pi-ai login anthropic    # 指定 Provider
+```
+
+凭据保存到当前目录的 `auth.json`。
+
+## 10.6 跨厂商 Handoff
+
+Pi 支持在**同一段对话中途切换 Provider**，同时保留上下文——包括 thinking block、工具调用、工具结果。当一个 Provider 的消息发给另一个 Provider 时，库会自动做兼容转换：
+
+```plantuml
+@startuml
+skinparam backgroundColor transparent
+
+participant "用户" as U
+participant "Claude\n(anthropic)" as C
+participant "GPT-5\n(openai)" as G
+participant "Gemini\n(google)" as Ge
+
+U -> C: "25 * 18 = ?"
+C --> U: [thinking] + "450"
+U -> G: "算得对吗?"
+note right of G
+  Claude 的 thinking 被转为
+  <thinking> 标签文本
+end note
+G --> U: "对"
+U -> Ge: "原题是什么?"
+Ge --> U: "25 * 18"
+
+@enduml
+```
+
+转换规则：
+
+| 消息类型 | 处理方式 |
+|---------|---------|
+| user / toolResult 消息 | 原样透传 |
+| 同 Provider/API 的 assistant 消息 | 原样保留 |
+| **不同 Provider** 的 assistant 消息 | thinking block 转为 `<thinking>` 标签文本 |
+| 工具调用与普通文本 | 原样保留 |
+
+这让"先用快模型、复杂推理再切强模型"或"在 Provider 故障时切换"成为可能。所有 Provider 都能消费其他 Provider 的消息，包括带部分内容的 aborted 消息。
+
+## 10.7 自定义 Provider
+
+本地推理服务器（Ollama、vLLM、LM Studio）或任何 OpenAI/Anthropic 兼容端点，用 `createProvider()` 接入：
+
+```typescript
+import { createModels, createProvider, envApiKeyAuth } from '@earendil-works/pi-ai';
+import { openAICompletionsApi } from '@earendil-works/pi-ai/api/openai-completions.lazy';
+
+const ollama = createProvider({
+  id: 'ollama',
+  name: 'Ollama',
+  baseUrl: 'http://localhost:11434/v1',
+  // 无 key 的本地服务：resolve 返回空认证即可
+  auth: { apiKey: { name: 'Ollama', resolve: async () => ({ auth: {} }) } },
+  models: [ollamaModel],
+  api: openAICompletionsApi(),
+});
+
+const models = createModels();
+models.setProvider(ollama);
+```
+
+有真实 key 的 Provider 用 `envApiKeyAuth(displayName, envVars)` 得到标准行为（存储凭据优先，然后第一个命中的环境变量）：
+
+```typescript
+const proxy = createProvider({
+  id: 'my-proxy',
+  auth: { apiKey: envApiKeyAuth('My proxy API key', ['MY_PROXY_API_KEY']) },
+  models: [/* ... */],
+  api: openAICompletionsApi(),
+});
+```
+
+### compat：抹平兼容差异
+
+`openai-completions` 被很多 Provider 实现，细节各有不同。默认会按 baseUrl 自动检测；未知端点可用 `compat` 字段覆盖：
+
+```typescript
+interface OpenAICompletionsCompat {
+  supportsStore?: boolean;            // 是否支持 store 字段
+  supportsDeveloperRole?: boolean;    // developer 角色 vs system
+  supportsReasoningEffort?: boolean;  // reasoning_effort
+  maxTokensField?: 'max_completion_tokens' | 'max_tokens';
+  thinkingFormat?: 'openai' | 'deepseek' | 'qwen' | /* ... */;
+  // ...更多
+}
+```
+
+常见场景：Ollama、vLLM、SGLang 等不认识 reasoning 模型用的 `developer` 角色，就设 `compat.supportsDeveloperRole: false`，让 system prompt 作为 `system` 消息发送。
+
+## 10.8 本章检查清单
+
+- [ ] 能区分 Provider、Models、API 实现三者的职责
+- [ ] 说得出认证解析的优先级：显式 > 存储凭据 > 环境变量
+- [ ] 理解"存储凭据独占 Provider"这条安全规则
+- [ ] 知道 `modify` 为什么是 CredentialStore 唯一写入路径
+- [ ] 理解 OAuth 自动刷新如何避免并发重复刷新
+- [ ] 知道跨厂商 handoff 时 thinking block 如何被转换
+
+---
+
+**上一章**：[第九章 · 扩展系统](09-extension-system.md)  
+**下一章**：[第十一章 · Session 树与上下文构建](11-session-tree.md) — 对话历史如何组织成树