docs: mintlify 文档撰写

docs/conversation/multi-turn.mdx

@@ -0,0 +1,59 @@
+---
+title: "多轮对话管理"
+description: "一场跨越数小时的编程对话是如何被管理的"
+---
+
+{/* 本章目标：解释会话编排、持久化、成本追踪 */}
+
+## 单轮 vs 多轮
+
+- **单轮**（一次 Agentic Loop）：用户说一句 → AI 执行一系列操作 → 回答
+- **多轮**（一个 Session）：用户和 AI 来回对话几十轮，持续数小时
+
+多轮对话带来的挑战远超单轮：消息越来越多、token 不断累积、上下文逐渐模糊。
+
+## 会话编排器的职责
+
+在单轮 Agentic Loop 之上，有一个编排器负责管理整个会话生命周期：
+
+<CardGroup cols={2}>
+  <Card title="对话状态管理" icon="database">
+    维护完整的消息历史，包括用户消息、AI 回复、工具调用结果
+  </Card>
+  <Card title="会话持久化" icon="floppy-disk">
+    自动保存对话记录到磁盘，支持断线重连、历史回顾
+  </Card>
+  <Card title="文件快照" icon="camera">
+    在 AI 修改文件前自动保存快照，支持回滚
+  </Card>
+  <Card title="成本追踪" icon="calculator">
+    精确记录每轮的 token 消耗和 API 费用
+  </Card>
+</CardGroup>
+
+## 会话恢复
+
+意外退出？网络断了？没关系：
+
+- 每轮对话结束后，完整的 transcript 会被写入磁盘
+- 下次启动时，可以选择恢复之前的对话
+- 恢复时，系统重建消息历史和上下文状态
+
+## 成本感知
+
+AI 编程助手的一个现实问题是**费用可能失控**。Claude Code 内建了多层成本控制：
+
+| 机制 | 作用 |
+|------|------|
+| Token 计数器 | 实时显示本次会话已消耗的输入/输出 token |
+| 费用估算 | 根据模型定价计算累计美元花费 |
+| 预算上限 | 用户可设定最大花费，到达后自动停止 |
+| 压缩提醒 | Token 接近上限时提示用户触发压缩 |
+
+## 模型切换
+
+在一个会话中，用户可以随时切换模型或调整参数：
+
+- `/model` 切换到不同的模型（Sonnet / Opus / Haiku）
+- `/fast` 切换快速模式
+- 模型切换不会丢失对话历史

docs/conversation/streaming.mdx

@@ -0,0 +1,50 @@
+---
+title: "流式响应：逐字呈现"
+description: "为什么 Claude Code 的回答是'打字机效果'而不是一整块弹出"
+---
+
+{/* 本章目标：解释流式通信的意义和它如何与工具执行交织 */}
+
+## 为什么需要流式
+
+想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
+
+流式响应让用户**实时看到 AI 的思考过程**：
+- 文字逐字出现，用户能提前判断方向是否正确
+- 工具调用的参数在生成过程中就能预览
+- 长时间任务不会让用户觉得"卡死了"
+
+## 流式与工具调用的交织
+
+一次 AI 响应中可能同时包含文字和工具调用。流式系统需要处理这种交织：
+
+```
+AI 开始输出文字 → "我来看看这个文件的内容..."
+AI 发出工具调用 → [FileRead: src/main.ts]
+           ↓ 暂停流式输出
+     工具执行中... 
+     结果返回给 AI
+           ↓ 恢复流式输出
+AI 继续输出 → "这个文件里有一个 bug，第 42 行..."
+AI 发出下一个工具调用 → [FileEdit: src/main.ts]
+```
+
+## 流式工具执行
+
+更进阶的是，**工具本身的执行也可以是流式的**：
+
+- 运行一个长命令（比如 `npm install`），输出逐行显示
+- 搜索大型项目时，匹配结果逐条呈现
+- AI 在等待工具结果的同时，已经开始规划下一步
+
+## 多 Provider 适配
+
+Claude Code 支持多个 AI 服务提供商，每个提供商的流式协议略有不同：
+
+| Provider | 特点 |
+|----------|------|
+| Anthropic Direct | 原生 SSE 流，延迟最低 |
+| AWS Bedrock | 通过 AWS SDK 包装的流式接口 |
+| Google Vertex | gRPC 流转换为事件流 |
+
+系统通过统一的事件抽象层屏蔽这些差异——上层代码不需要关心底层用的是哪个 Provider。

docs/conversation/the-loop.mdx

@@ -0,0 +1,66 @@
+---
+title: "Agentic Loop：对话的心跳"
+description: "AI 不只回答问题，它会反复思考-行动-观察，直到任务完成"
+---
+
+{/* 本章目标：解释 Agentic Loop 这个核心机制 */}
+
+## 什么是 Agentic Loop
+
+传统聊天机器人：你问一句，它答一句。  
+Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
+
+这背后的机制叫做 **Agentic Loop**（智能体循环）：
+
+{/* TODO: 插入 Loop 示意图 */}
+
+<Steps>
+  <Step title="思考">
+    AI 分析当前上下文，决定下一步该做什么
+  </Step>
+  <Step title="行动">
+    AI 发出工具调用请求（比如"读取这个文件"、"执行这条命令"）
+  </Step>
+  <Step title="观察">
+    工具执行完毕，结果回传给 AI
+  </Step>
+  <Step title="循环或结束">
+    AI 根据观察结果决定：继续下一步操作，还是任务已完成、直接回答用户
+  </Step>
+</Steps>
+
+## 一个真实的例子
+
+> 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
+
+AI 的内部过程：
+
+1. **思考**：我需要先了解项目结构 → **行动**：调用 Glob 工具扫描所有源文件
+2. **观察**：拿到文件列表 → **思考**：逐个检查 → **行动**：调用 Grep 搜索 import 语句
+3. **观察**：发现 3 个文件有未使用导入 → **行动**：调用 FileEdit 逐个删除
+4. **观察**：编辑成功 → **结束**：告诉用户"已清理 3 个文件中的 5 条未使用导入"
+
+整个过程可能涉及 10+ 次工具调用，但用户只需要说一句话。
+
+## 为什么不是"一次规划，批量执行"
+
+<Note>
+一个常见的替代方案是：AI 先生成一个完整的计划，然后一次性执行所有步骤。Claude Code 选择了逐步循环，原因是：
+</Note>
+
+- **每一步都能看到真实结果**：文件内容、命令输出、错误信息——这些只有执行后才知道
+- **动态调整**：如果第 3 步发现了意外情况，AI 可以立刻改变策略
+- **错误恢复**：某步失败了，AI 可以当场诊断和修复，不需要推倒重来
+- **用户可控**：用户可以在任何一步中断，AI 的循环不会失控
+
+## 循环的终止条件
+
+Agentic Loop 不会无限运行，以下情况会让循环停止：
+
+| 条件 | 说明 |
+|------|------|
+| AI 主动结束 | AI 判断任务完成，返回纯文本回答（不再调用工具） |
+| 用户中断 | 用户按 Ctrl+C 或 ESC 打断当前操作 |
+| Token 预算耗尽 | 单轮对话的 token 用量达到上限 |
+| 输出过长自动续写 | AI 回复被截断时，系统自动发起续写请求（有次数上限） |
+| 成本上限 | 累计 API 花费超过用户设定的预算 |