docs(ai): Agent部分内容优化完善

Author: Snailclimb

docs/.vuepress/styles/index.scss

@@ -4,6 +4,29 @@ body {
   }
 }
 
+#markdown-content img,
+.vp-content img,
+.theme-hope-content img {
+  max-width: 100%;
+  height: auto;
+}
+
+.article-promo-image {
+  display: block;
+  margin: 1rem auto;
+
+  img {
+    display: block;
+    margin: 0 auto;
+  }
+}
+
+.article-footer-qrcode {
+  display: block;
+  width: min(612px, 100%);
+  margin: 0 auto;
+}
+
 // ============================================
 // 沉浸式阅读模式 - 隐藏导航栏、侧边栏和目录
 // ============================================

docs/ai/agent/agent-basis.md

@@ -21,7 +21,7 @@ head:
 3. **Compaction 与摘要压缩**：长任务上下文如何持久化？如何避免上下文溢出？
 4. **Sub-agent 架构**：如何通过子智能体分担主 Agent 的上下文压力？
 
-## 从一个例子说起
+## 为什么同样的 Agent 会因上下文不同而大相径庭？
 
 **为什么同样的模型，Agent 表现却天差地别？**
 
@@ -55,7 +55,7 @@ Model: 抱歉给您带来不便。请问您购买的是哪款耳机？订单号
 
 一句话：**当前 Agent 的大部分失败，根源在上下文**。上下文不够，模型再强也没用；上下文对了，中等水平的模型也能完成任务。
 
-## 理解 Context Engineering
+## 如何理解 Context Engineering？
 
 ### 它和 Prompt Engineering 到底有什么区别？
 
@@ -87,13 +87,13 @@ LLM 的上下文窗口是有限的内存，Context Engineering 决定了这块
 - **System Prompt（系统指令）**：静态 Prompt 的结构化编排。比如 `.cursorrules`、`.claude/rules` 这类配置文件，核心是把角色设定、目标、约束、执行流、输出格式拆解清楚，让模型在复杂任务里不脱轨。
 - **User Prompt**：业务数据与指令。
 - **Memory（记忆系统）**：短期记忆（Session 滑动窗口管理）和长期记忆（核心事实提取 + 向量数据库存储）。
-- **RAG & Tools（动态增强）**：按需检索外部文档作为背景知识 + 把工具描述以结构化形式挂载到上下文。本质上，RAG 就是 Context Engineering 的一种特定实现模式——“检索什么、怎么检索、检索结果怎么填入上下文”这三个问题，本身就是上下文工程。
+- **RAG & Tools（动态增强）**：按需检索外部文档作为背景知识 + 把工具描述以结构化形式挂载到上下文。RAG 可以看作 Context Engineering 的一种特定实现：它要回答“检索什么、怎么检索、检索结果怎么填入上下文”这三个问题。
 - **Structured Output（结构化输出）**：输出格式的定义，比如 JSON Schema、function call 的返回结构等。这直接影响下游消费方的解析和后续 Agent 链路的衔接，是容易被忽视但实战价值很高的一环。
 - **Token 优化（上下文裁剪）**：摘要压缩、历史剔除、Context Caching，在保证信息完整度的同时控制 Token 消耗。
 
 ![上下文窗口（Context Window）= LLM 的工作记忆](https://oss.javaguide.cn/github/javaguide/ai/llm/llm-context-window.png)
 
-## 核心技术板块
+## Context Engineering 的核心技术板块有哪些？
 
 ### 如何做好静态规则的结构化编排？
 
@@ -122,7 +122,7 @@ LLM 的上下文窗口是有限的内存，Context Engineering 决定了这块
 使用 JSON，包含字段：incident_summary, root_cause, evidence, recommendation
 ```
 
-把这些规则固化为 `.cursorrules` 或 `AGENTS.md` 文件，Agent 在复杂任务里的“脱轨”概率会大幅降低。值得一提的是，随着模型能力不断提升，Prompt 格式的精确性可能正在变得不那么关键——但结构化编排带来的**可维护性**和**团队协作效率**提升是长期价值。
+把这些规则固化为 `.cursorrules` 或 `AGENTS.md` 文件，Agent 在复杂任务里的“脱轨”概率会大幅降低。随着模型能力提升，Prompt 格式的精确性可能没以前那么敏感，但结构化编排带来的**可维护性**和**团队协作效率**仍然很有价值。
 
 ### 动态信息应该怎样按需挂载？
 
@@ -145,13 +145,13 @@ LLM 的上下文窗口是有限的内存，Context Engineering 决定了这块
 
 配套优化手段是 **Context Caching**：在大规模并发请求里，相同 System Prompt 部分只需加载一次，显著降低首 Token 延迟和推理成本。
 
-## 上下文失效的根因
+## 上下文为何会失效？
 
 **为什么上下文越长，效果反而可能越差？**
 
-很多人在使用超长上下文模型时会有个误解：上下文越长，模型能用的信息越多，效果应该越好。
+直觉告诉你：窗口越大、塞的信息越多，模型应该表现越好。
 
-错了。真实情况是：**上下文存在边际效益递减，甚至可能负向增长**。
+实际跑下来恰恰相反。**上下文存在边际效益递减，塞过头还会负向增长**。
 
 背后的原因是 LLM 的 Attention 机制。Transformer 架构让每个 Token 都要和上下文里所有其他 Token 计算注意力关系，这意味着 n 个 Token 的上下文会产生 n² 量级的注意力计算。
 
@@ -161,7 +161,7 @@ LLM 的上下文窗口是有限的内存，Context Engineering 决定了这块
 
 **工程启示**：不同模型的衰减曲线不同——有些模型的退化比较平缓，有些则比较陡峭，因此上下文长度的最优阈值需要针对具体模型实测。但有一点是确定的：上下文必须被当作有限资源来管理，不是塞满越好。找到“高信噪比”的平衡点，是 Context Engineering 最核心的手艺。
 
-## 有效上下文的构建原则
+## 有效上下文的构建原则有哪些？
 
 ### System Prompt 怎样写才算“恰到好处”？
 
@@ -198,7 +198,7 @@ Few-shot prompting（给示例）是经过验证的有效策略，但很多人
 
 业界常用的做法是选 **3-5 个多样化的典型示例（canonical examples）**。Anthropic 也强调了示例的多样性和典型性比数量更重要——"Canonical"的意思是“权威的、标准化的”，每个示例要能代表一类典型场景的解决模式，而非覆盖所有边缘情况。对模型来说，示例是“一幅画胜千言”的视觉化教学，展示“什么情况用什么策略”而非“什么输入对应什么输出”。
 
-## 运行时上下文检索
+## 运行时如何做好上下文检索？
 
 ### 为什么预检索在复杂 Agent 场景下不够用？
 
@@ -210,7 +210,7 @@ Few-shot prompting（给示例）是经过验证的有效策略，但很多人
 
 **Just-in-Time（按需加载）** 策略因此兴起。
 
-其核心思想是：Agent 运行时不要预先装载所有可能相关的信息，而是维护轻量级的**引用句柄**（文件路径、存储查询、Web 链接），在真正需要时才通过工具动态拉取数据。
+它的思路是：Agent 运行时不要预先装载所有可能相关的信息，而是维护轻量级的**引用句柄**（文件路径、存储查询、Web 链接），在真正需要时才通过工具动态拉取数据。
 
 拿 Claude Code 举例：它处理大数据库分析时，不是把所有数据 Load 进上下文，而是写定向查询语句、存储结果、用 `head`/`tail` 命令分析数据文件。Agent 像人类一样通过“文件名”和“目录结构”理解信息位置，通过“文件大小”和“时间戳”判断重要性，而不是一开始就加载全部内容。
 
@@ -228,7 +228,7 @@ Anthropic 把这种方式称为**渐进式披露（Progressive Disclosure）**
 
 混合策略的决策边界也有规律可循：**动态内容占比高、探索空间大的场景**（如代码库分析、信息检索）适合 Just-in-Time 为主；**动态内容少、上下文稳定的场景**（如法律文书审阅、财务报表分析）更适合预检索 + 少量运行时补充。
 
-## 长时任务的上下文持久化
+## 长时任务下上下文如何持久化？
 
 ![长任务上下文持久化：抵抗腐化的三大武器](https://oss.javaguide.cn/github/javaguide/ai/context-engineering/long-task-context-persistence-three-weapons-against-corruption.svg)
 
@@ -244,7 +244,7 @@ Anthropic 把这种方式称为**渐进式披露（Progressive Disclosure）**
 
 一个最轻量的压缩手段是**工具结果清理**：一旦工具在历史里被调用过且结果已被消化，后续上下文里这个结果的原始文本就没必要保留了。Anthropic 的 Developer Platform 已经把这个做成了原生功能。
 
-> **工程提示**：压缩 Prompt 的调优是个迭代过程。建议用复杂 Agent 轨迹数据反复调优——先最大化召回（不要漏掉重要信息），再逐步精简冗余内容。一次性编写完美的压缩指令几乎不可能，持续迭代才是正道。
+> **工程提示**：压缩 Prompt 的调优是个迭代过程。建议用复杂 Agent 轨迹数据反复调优——先最大化召回（不要漏掉重要信息），再逐步精简冗余内容。压缩指令很难一次写准，需要持续迭代。
 
 ### 如何让 Agent 学会“记笔记”？—— Structured Note-taking
 
@@ -276,41 +276,35 @@ Anthropic 在"How we built our multi-agent research system"里详细描述了这
 | Note-taking | 迭代式开发、有清晰里程碑、多步推进的任务 |
 | Sub-agents  | 复杂研究、需要并行探索、结果需汇总的场景 |
 
-## 工具链与工程落地
-
-### 落地 Context Engineering 需要哪些工具？
+## 落地 Context Engineering 需要哪些工具？
 
 说完方法论，顺手整理下工程落地需要的主流工具：
 
-**编排框架**：LangChain、LangGraph 这一类框架负责 Agent 的控制流、状态管理和循环调度。
-
-**数据框架**：LlamaIndex 专注 RAG 场景下的数据摄取、索引和检索优化。
-
-**向量数据库**：Pinecone、Weaviate、Chroma、Qdrant 这一类负责 Embedding 的存储和语义搜索。
-
-**通信协议**：MCP（Model Context Protocol）解决了“工具如何标准化接入宿主程序”的问题，被誉为 AI 领域的 USB-C。Anthropic 发布的 MCP 协议基于 JSON-RPC 2.0，定义了 Tools（可执行函数）、Resources（只读数据）、Prompts（可复用模板）三类标准原语。
-
-**Memory 产品**：Mem0、LETTA（原 MemGPT）、ZEP 这类专门做 Agent 记忆层的平台，在向量库之上封装了记忆写入、检索、遗忘的完整生命周期管理。
+- **编排框架**：LangChain、LangGraph 这一类框架负责 Agent 的控制流、状态管理和循环调度。
+- **数据框架**：LlamaIndex 专注 RAG 场景下的数据摄取、索引和检索优化。
+- **向量数据库**：Pinecone、Weaviate、Chroma、Qdrant 这一类负责 Embedding 的存储和语义搜索。
+- **通信协议**：MCP（Model Context Protocol）解决了“工具如何标准化接入宿主程序”的问题，常被类比为 AI 应用里的 USB-C。Anthropic 发布的 MCP 协议基于 JSON-RPC 2.0，定义了 Tools（可执行函数）、Resources（只读数据）、Prompts（可复用模板）三类标准原语。
+- **Memory 产品**：Mem0、LETTA（原 MemGPT）、ZEP 这类专门做 Agent 记忆层的平台，在向量库之上封装了记忆写入、检索、遗忘的完整生命周期管理。
 
-## 总结
+## 如何把 Context Engineering 的要点落实到工程实践？
 
-Context Engineering 之所以重要，是因为它意味着工作重心的转移：**从优化单个 Prompt，到设计整个信息供给系统**。
+这篇文章的判断可以收成一句话：**Agent 的大多数失败不在模型智商，而在上下文精度**。
 
-过去我们关心的是“怎么措辞”，现在我们关心的是“构建什么样的上下文工程架构”。模型能力在增长，但注意力是有限的——这个基本约束不会因为模型变强就消失。
+过去关心"怎么措辞"，现在关心的是"什么信息、什么格式、什么时机塞进窗口"。模型能力在增长，但注意力有限这个硬约束不会消失——窗口再大，塞满噪声一样变蠢。
 
-具体到工程实践，记住四条核心原则：
+工程上值得反复验证的几个判断：
 
-1. **上下文是系统输出，不是静态配置**。每次 LLM 调用前，你都在组装一个动态的上下文——这个组装逻辑本身才是工程的核心。
-2. **高信噪比优于高信息量**。上下文的长度不决定效果，找到让模型做出正确决策所需的最小高密度信息集，才是手艺。
-3. **上下文需要代谢机制**。对于长任务，没有什么是“一次组装永久有效”的——压缩、笔记、多 Agent 分层，这些机制让上下文在时间维度上保持新鲜和可用。
-4. **从最简方案开始，逐步增加复杂度**。Anthropic 反复强调 "do the simplest thing that works"——先用最小可行的上下文方案跑通基线，再基于实际 failure case 逐层优化。过度工程化的上下文系统和不足的上下文一样危险。
+- **上下文是系统输出，不是静态配置**。每次 LLM 调用前你都在组装一个动态上下文，这个组装逻辑本身才是工程核心——改一个检索策略、换一种摘要方式、调整工具 Schema 的挂载顺序，效果差别可能比换模型还大。
+- **高信噪比优于高信息量**。上下文的长度不决定效果。Dex Horthy 的 40% 阈值实验说明：塞满窗口不如只放必要信息。找到让模型做出正确决策所需的最小高密度信息集，才是手艺。
+- **长任务里上下文会腐化**。没有什么是"一次组装永久有效"的——Compaction、结构化笔记、Sub-agent 分层，三者组合才能让上下文在时间维度上不变质。
+- **从最简方案起步**。Anthropic 反复强调 "do the simplest thing that works"。过度工程化的上下文系统和不足的上下文一样危险——Guide 见过不少团队还没跑通基线就去做记忆分层，结果调试成本比收益还高。
 
-Agent 失败的根源大多在上下文精度不够。把上下文工程做到位，中等水平的模型也能完成看似复杂的任务。
+把上下文工程做到位，中等水平的模型也能完成看似复杂的任务。反过来说，再贵的模型拿到一坨噪声，输出一样拉胯。
 
-## 参考
+## 延伸阅读有哪些？
 
 - [Effective context engineering for AI agents - Anthropic](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
 - [Context Engineering: The New Frontier of AI Development](https://medium.com/techacc/context-engineering-a8c3a4b39c07)
 - [The New Skill in AI is Not Prompting, It's Context Engineering](https://www.philschmid.de/context-engineering)
-- [Context Engineering by Simon Willison](https://simonwillison.net/2024/Nov/9/context-engineering/)
-- [Own your context window](https://www.pinecone.io/learn/own-your-context-window)
+- [Context Engineering by Simon Willison](https://simonwillison.net/2025/jun/27/context-engineering/)
+- [12 Factor Agents - Own Your Context Window](https://www.humanlayer.dev/blog/12-factor-agents)