docs: mintlify 文档撰写

docs/context/compaction.mdx

@@ -0,0 +1,63 @@
+---
+title: "上下文压缩"
+description: "对话太长怎么办——优雅地'遗忘'不重要的信息"
+---
+
+{/* 本章目标：解释 Compaction 机制的设计和策略 */}
+
+## 为什么需要压缩
+
+每次 API 调用的 token 有上限（通常 200K）。一场长时间的编程对话可能产生：
+
+- 大量的文件内容（AI 读了几十个文件）
+- 长篇的命令输出（构建日志、测试结果）
+- 往返的对话历史
+
+不压缩的话，很快就会撞到 token 上限，对话被迫终止。
+
+## 压缩的策略
+
+Claude Code 提供了多层压缩机制：
+
+<AccordionGroup>
+  <Accordion title="自动压缩">
+    当 token 接近上限时，系统自动触发压缩。AI 生成一份当前对话的**摘要**，替换掉早期的详细消息。效果就像人类的"记忆"——记住要点，忘记细节。
+  </Accordion>
+  <Accordion title="手动压缩">
+    用户可以随时通过 `/compact` 命令主动触发压缩。可以附带提示语（如 `/compact 聚焦在认证模块的修改上`），引导 AI 保留特定信息。
+  </Accordion>
+  <Accordion title="Micro Compact">
+    更细粒度的局部压缩——不是压缩整个对话，而是压缩某些特别长的工具输出（比如一个 5000 行的测试日志）。
+  </Accordion>
+</AccordionGroup>
+
+## 压缩边界
+
+压缩后，系统在消息历史中插入一个"边界标记"。后续的 API 调用只发送边界之后的消息：
+
+```
+[早期的 50 条消息] ← 被压缩
+[压缩摘要边界] ← 一段浓缩的摘要
+[后续的 10 条消息] ← 正常发送
+```
+
+这个设计保证了：
+- 压缩后的摘要为 AI 提供了历史上下文
+- 新的对话不受旧消息的 token 负担
+- 用户无感知——对话继续自然进行
+
+## 压缩前后的 Hooks
+
+压缩是一个可能丢失信息的操作，因此系统允许用户在压缩前后执行自定义脚本：
+
+- **Pre-compact Hook**：压缩前执行，可以标记"这些信息不能丢"
+- **Post-compact Hook**：压缩后执行，可以验证关键信息是否保留
+
+## 什么信息会被保留
+
+压缩不是简单的截断，AI 会智能地决定保留什么：
+
+- 用户的核心需求和目标
+- 重要的决策和原因
+- 当前工作的状态（改了哪些文件、做到哪一步）
+- 之前犯过的错误（避免重蹈覆辙）

docs/context/project-memory.mdx

@@ -0,0 +1,58 @@
+---
+title: "项目记忆"
+description: "让 AI 跨对话记住你的偏好和项目上下文"
+---
+
+{/* 本章目标：解释记忆系统如何让 AI 变得'有记忆' */}
+
+## AI 的记忆困境
+
+大语言模型没有真正的记忆。每次新对话，它都是一张白纸。用户不得不反复解释"我的项目用 Bun 不用 Node"、"commit 消息用中文"。
+
+## 记忆系统的解决方案
+
+Claude Code 通过一个基于文件的持久化记忆系统来模拟"跨会话记忆"：
+
+<CardGroup cols={2}>
+  <Card title="用户记忆" icon="user">
+    关于用户的信息：角色、偏好、技术背景
+  </Card>
+  <Card title="反馈记忆" icon="message">
+    用户对 AI 行为的纠正和肯定
+  </Card>
+  <Card title="项目记忆" icon="folder">
+    项目中的非代码信息：谁负责什么、截止日期
+  </Card>
+  <Card title="参考记忆" icon="link">
+    外部资源的位置：Issue tracker、Dashboard URL
+  </Card>
+</CardGroup>
+
+## 记忆的读写时机
+
+| 时机 | 动作 |
+|------|------|
+| 每次对话开始 | 加载记忆索引（MEMORY.md），相关记忆注入 System Prompt |
+| 用户纠正 AI | AI 自动判断是否值得记住，写入反馈记忆 |
+| 用户说"记住这个" | 立即保存到对应类型的记忆文件 |
+| 用户说"忘掉这个" | 找到并删除对应的记忆条目 |
+| 记忆可能过期时 | 使用前先验证（文件还在？函数还存在？），过期则更新或删除 |
+
+## 记忆 vs 代码注释 vs CLAUDE.md
+
+| | 记忆 | 代码注释 | CLAUDE.md |
+|---|---|---|---|
+| 存储位置 | `~/.claude/` 目录 | 代码文件中 | 项目目录中 |
+| 谁能看到 | 只有当前用户 | 所有开发者 | 所有使用 Claude Code 的人 |
+| 适合存什么 | 个人偏好、非公开的上下文 | 代码逻辑解释 | 项目约定、开发指南 |
+| 跨项目 | 是 | 否 | 否 |
+
+## 不该存什么
+
+记忆系统明确规定了不应存储的内容：
+
+- 代码结构和架构（读代码就知道）
+- git 历史（`git log` 就能查）
+- 调试方案（修复已在代码中）
+- CLAUDE.md 里已有的内容（避免重复）
+- 临时性任务状态（用任务系统）

docs/context/system-prompt.mdx

@@ -0,0 +1,53 @@
+---
+title: "System Prompt 的动态组装"
+description: "AI 的'工作记忆'是如何在每次对话前被精心拼装的"
+---
+
+{/* 本章目标：解释 System Prompt 的组装过程和设计思想 */}
+
+## 什么是 System Prompt
+
+每次调用 AI API 时，都需要发送一个 System Prompt——它是 AI 的"人设说明书"，告诉 AI：
+
+- 你是谁（Claude Code，一个编程助手）
+- 你能做什么（可用工具列表）
+- 你在什么环境（操作系统、当前目录、git 状态）
+- 你需要遵守什么规则（安全规范、输出格式）
+
+## 不是静态模板，而是动态组装
+
+Claude Code 的 System Prompt 不是一段写死的文本，而是根据当前环境**实时组装**的：
+
+| 组成部分 | 内容 | 来源 |
+|----------|------|------|
+| 基础人设 | 角色定义、行为准则 | 内置模板 |
+| 环境信息 | 操作系统、shell 类型、当前日期 | 运行时检测 |
+| Git 状态 | 当前分支、最近提交、工作区状态 | `git` 命令输出 |
+| 项目知识 | CLAUDE.md 文件内容 | 项目目录层级扫描 |
+| 记忆文件 | 用户偏好、项目约定 | 持久化记忆系统 |
+| 工具说明 | 每个可用工具的描述和参数 | 工具注册表 |
+
+## CLAUDE.md：项目级知识注入
+
+这是 Claude Code 最巧妙的设计之一。在项目根目录放一个 `CLAUDE.md` 文件，就能让 AI "理解" 你的项目：
+
+- **项目概述**：这个项目做什么、用了什么技术栈
+- **开发约定**：代码风格、命名规范、分支策略
+- **常用命令**：怎么构建、怎么测试、怎么部署
+- **注意事项**：已知的坑、特殊的配置
+
+系统会自动发现并合并多级 CLAUDE.md：
+
+```
+~/.claude/CLAUDE.md              ← 用户全局（个人偏好）
+  └── /project/CLAUDE.md         ← 项目根目录（团队共享）
+        └── /project/src/CLAUDE.md  ← 子目录（模块特定）
+```
+
+## 缓存策略
+
+System Prompt 的 token 消耗不小（可能占总量的 30%+）。为了降低成本，系统使用了缓存机制：
+
+- 不变的部分（基础人设、工具说明）可以跨请求复用
+- 变化的部分（git 状态、记忆文件）每次重新生成
+- 缓存节点的位置经过精心设计，最大化缓存命中率

docs/context/token-budget.mdx

@@ -0,0 +1,55 @@
+---
+title: "Token 预算管理"
+description: "精打细算每一个 token——AI 的'注意力'是有限资源"
+---
+
+{/* 本章目标：解释 token 预算管理的思路 */}
+
+## Token 是什么
+
+简单理解：token 约等于一个英文单词或半个中文字。AI 处理的所有输入和输出都按 token 计费。
+
+| 类型 | 说明 | 谁付费 |
+|------|------|--------|
+| 输入 token | 发给 AI 的所有内容（System Prompt + 对话历史 + 工具结果） | 用户 |
+| 输出 token | AI 生成的回复和工具调用 | 用户 |
+| 缓存 token | 重复发送的内容如果命中缓存，价格更低 | 部分用户 |
+
+## 预算控制的三个层面
+
+<CardGroup cols={3}>
+  <Card title="单次请求" icon="1">
+    每次 API 调用的最大输入/输出 token
+  </Card>
+  <Card title="单轮对话" icon="arrows-rotate">
+    一个 Agentic Loop 内的累计 token 消耗
+  </Card>
+  <Card title="整个会话" icon="clock">
+    全部对话轮次的累计花费（美元）
+  </Card>
+</CardGroup>
+
+## 工具输出的预算控制
+
+工具返回的内容可能非常长（一个大文件、一段长日志），直接全部塞给 AI 会浪费大量 token。系统对此有专门的控制：
+
+- **结果截断**：超过长度限制的工具输出自动截断
+- **结果替换**：已经被 AI"消化"过的旧工具结果，可以被替换为简短的摘要
+- **按需读取**：大文件不一次性读完，AI 可以指定读取范围
+
+## 缓存的经济学
+
+System Prompt 每次都要发送，但大部分内容不变。缓存机制让这部分"免费"（或大幅降价）：
+
+- 首次发送：全价
+- 后续请求命中缓存：约 1/10 的价格
+- 这就是为什么 System Prompt 的结构被精心设计——不变的部分放前面，变化的部分放后面
+
+## token 警告与自动压缩
+
+| token 使用率 | 系统行为 |
+|-------------|---------|
+| < 70% | 正常运行 |
+| 70% ~ 90% | 显示警告，提示用户可以手动压缩 |
+| > 90% | 自动触发压缩 |
+| 接近 100% | 强制压缩或终止当前轮次 |