docs: mintlify 文档撰写

docs/introduction/architecture-overview.mdx

@@ -0,0 +1,59 @@
+---
+title: "架构全景"
+description: "五层架构，一条数据流"
+---
+
+{/* 本章目标：一张图讲清楚整体架构，为后续章节建立坐标系 */}
+
+## 五层架构
+
+Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
+
+| 层次 | 职责 | 关键词 |
+|------|------|--------|
+| **交互层** | 终端 UI、用户输入、消息展示 | React/Ink、REPL |
+| **编排层** | 管理多轮对话、会话生命周期、成本追踪 | QueryEngine、会话持久化 |
+| **核心循环层** | 单轮对话：发请求 → 拿响应 → 执行工具 → 再发请求 | Agentic Loop |
+| **工具层** | AI 的"双手"——读写文件、执行命令、搜索代码 | Tool System、MCP |
+| **通信层** | 与 Claude API 的流式通信、多云 Provider 适配 | Streaming、Bedrock/Vertex |
+
+## 一条主数据流
+
+{/* TODO: 插入数据流序列图 */}
+
+整个系统的运转可以浓缩为一条核心数据流：
+
+<Steps>
+  <Step title="用户输入">
+    用户在终端键入自然语言需求
+  </Step>
+  <Step title="上下文组装">
+    系统自动拼接项目信息、git 状态、配置文件、记忆，形成完整的 System Prompt
+  </Step>
+  <Step title="API 调用">
+    将 System Prompt + 对话历史发送给 Claude API，流式接收响应
+  </Step>
+  <Step title="工具调用循环">
+    若 AI 返回工具调用请求 → 权限检查 → 执行工具 → 结果回传 → AI 继续思考 → 循环
+  </Step>
+  <Step title="任务完成">
+    AI 不再调用工具，输出最终回答，等待用户下一条输入
+  </Step>
+</Steps>
+
+## 四个核心设计原则
+
+<AccordionGroup>
+  <Accordion title="流式优先 (Streaming-first)">
+    所有 API 通信都是流式的——用户看到 AI "逐字打出"回答，而不是等待完整响应。工具执行结果也实时反馈。这不仅提升体验，更是处理长时间任务的工程必需。
+  </Accordion>
+  <Accordion title="工具即能力 (Tool as Capability)">
+    AI 的每一项"动手能力"都被抽象为一个 Tool。想让 AI 能做新事情？注册一个新 Tool 就好。统一的接口让能力可插拔、可组合。
+  </Accordion>
+  <Accordion title="权限即边界 (Permission as Boundary)">
+    AI 能操作真实环境是强大的，也是危险的。每个工具调用都经过权限系统的裁决——该放行的自动放行，该拦截的坚决拦截。
+  </Accordion>
+  <Accordion title="上下文即记忆 (Context as Memory)">
+    AI 没有真正的记忆，但通过精心的 System Prompt 组装、对话压缩、持久化记忆文件，系统营造出"AI 理解你的项目"的效果。这是上下文工程的核心。
+  </Accordion>
+</AccordionGroup>

docs/introduction/what-is-claude-code.mdx

@@ -0,0 +1,37 @@
+---
+title: "什么是 Claude Code"
+description: "一个住在终端里的 AI 编程搭档"
+---
+
+{/* 本章目标：让完全不了解 Claude Code 的读者在 3 分钟内建立直觉 */}
+
+## 一句话定义
+
+Claude Code 是一个运行在命令行终端里的 AI 编程助手。你用自然语言描述需求，它直接帮你读代码、改文件、跑命令、搜索项目——全部在你的本地环境中完成。
+
+## 它能做什么
+
+- **对话式编程**：像和同事聊天一样描述需求，AI 直接动手实现
+- **理解整个项目**：自动读取项目结构、git 历史、配置文件，建立项目全景认知
+- **操作你的电脑**：读写文件、执行 shell 命令、搜索代码——不只是给建议，而是真正动手
+- **保护你的安全**：每个敏感操作都需要你确认，有沙箱、有权限管控
+
+## 它和 ChatGPT / 普通聊天机器人的区别
+
+| | 普通聊天 AI | Claude Code |
+|---|---|---|
+| 运行环境 | 云端网页 | 你的本地终端 |
+| 能做什么 | 回答问题、生成文本 | 直接操作你的项目文件和命令行 |
+| 项目理解 | 你需要手动粘贴代码 | 自动读取整个项目上下文 |
+| 安全性 | 无需考虑 | 多层权限保护 |
+
+## 一次典型的交互流程
+
+{/* TODO: 插入一张交互流程示意图 */}
+
+1. 你在终端输入自然语言需求
+2. Claude Code 分析你的项目上下文
+3. 它决定使用哪些工具（读文件？执行命令？）
+4. 每个操作请求你确认（或根据规则自动放行）
+5. 执行完成后，把结果反馈给 AI，AI 决定下一步
+6. 循环，直到任务完成

docs/introduction/why-this-whitepaper.mdx

@@ -0,0 +1,40 @@
+---
+title: "为什么写这份白皮书"
+description: "将 LLM 能力落地到真实工作流的工程范本"
+---
+
+{/* 本章目标：解释为什么这个项目的架构值得深入研究 */}
+
+## 不只是一个聊天工具
+
+Claude Code 解决的核心问题是：**如何让大语言模型从"能说会道"变成"能说会做"**。
+
+这不是简单地给 AI 套一个 shell。它涉及一系列精巧的工程决策：
+
+- AI 说"我要编辑这个文件"时，如何确保安全？
+- 对话越来越长，token 快爆了怎么办？
+- AI 需要并行处理多个子任务时，如何隔离和协调？
+- 用户想扩展 AI 的能力（接数据库、连 API），如何设计插拔机制？
+
+## 这份白皮书关注什么
+
+<CardGroup cols={2}>
+  <Card title="功能视角" icon="eye">
+    不堆代码，从"用户能做什么、AI 如何决策"出发
+  </Card>
+  <Card title="设计决策" icon="lightbulb">
+    每个功能背后的"为什么这样设计"
+  </Card>
+  <Card title="架构模式" icon="sitemap">
+    可复用的模式：Agentic Loop、工具抽象、上下文工程
+  </Card>
+  <Card title="安全哲学" icon="shield">
+    AI 操作真实环境时的信任与控制平衡
+  </Card>
+</CardGroup>
+
+## 适合谁读
+
+- 想理解 AI Agent 产品架构的开发者
+- 正在构建类似工具的团队
+- 对 LLM 应用工程化感兴趣的任何人