docs(ai): 恢复 Agent 系列文档优化

- 恢复 agent-basis.md 优化内容
- 恢复 context/harness/prompt/mcp/skills 等文档优化
- 恢复 workflow-graph-loop.md 优化
- 添加 rag-project 示例片段

Author: Snailclimb

docs/ai/agent/agent-basis.md

@@ -8,12 +8,19 @@ head:
       content: Context Engineering,上下文工程,Agent,LLM,RAG,Prompt Engineering,Compaction,Sub-agent
 ---
 
-大家好，我是 Guide。
+<!-- @include: @article-header.snippet.md -->
 
-这两年 AI 圈有个特别有意思的现象：同样的模型、同样的代码框架，为什么别人的 Agent 能稳稳当当完成任务，你的却动不动就迷失方向、重复操作、或者输出一些看起来很对但实际跑不通的东西？
+这两年 AI 圈有个特别有意思的现象——同样的模型、同样的代码框架，为什么别人的 Agent 能稳稳当当完成任务，你的却动不动就迷失方向、重复操作、或者输出一些看起来很对但实际跑不通的东西？
 
 答案大概率出在**上下文**上。
 
+今天这篇文章就来系统梳理 Context Engineering 的核心概念和工程方法，帮你搞清楚如何让 Agent 拥有高质量的上下文供给系统。本文接近 1.5w 字，建议收藏，通过本文你将搞懂：
+
+1. **为什么上下文决定 Agent 表现**：同样的模型，Agent 表现为什么天差地别？
+2. **上下文工程的核心框架**：静态规则编排、动态信息挂载、Token 预算降级、按需加载分别怎么落地？
+3. **Compaction 与摘要压缩**：长任务上下文如何持久化？如何避免上下文溢出？
+4. **Sub-agent 架构**：如何通过子智能体分担主 Agent 的上下文压力？
+
 ## 从一个例子说起
 
 **为什么同样的模型，Agent 表现却天差地别？**
@@ -84,7 +91,7 @@ LLM 的上下文窗口是有限的内存，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 Window）= LLM 的工作记忆](https://oss.javaguide.cn/github/javaguide/ai/llm/llm-context-window.png)
 
 ## 核心技术板块
 
@@ -161,7 +168,6 @@ LLM 的上下文窗口是有限的内存，Context Engineering 决定了这块
 System Prompt 的编写存在两个常见失败模式：
 
 - **第一个极端：过度设计**。工程师把复杂的 if-else 逻辑硬编码进 Prompt 里，试图精确控制 Agent 的每一步行为。结果是指令脆弱得像纸片房，维护成本极高，而且模型在未见过的边缘情况里依然会脱轨。
-
 - **第二个极端：过度抽象**。只给“你要做一个有帮助的助手”这种模糊指令，模型无法从中获得足够的决策依据，要么频繁追问用户，要么输出与业务预期严重偏离。
 
 正确的做法是：**足够具体以引导行为，同时足够抽象以提供通用启发**。具体和抽象之间的平衡点，就是 Anthropic 工程博客中提到的"Goldilocks zone"（刚刚好的区域）。
@@ -180,7 +186,7 @@ System Prompt 的编写存在两个常见失败模式：
 
 常见失败案例是“大而全”的工具——把一堆相关但各自独立的功能塞进一个工具里，比如 `manage_database` 同时包含“建表、查数据、删数据、备份、导出”五个能力。Agent 在选择工具时会陷入模糊判断，在填充参数时也会被无关字段干扰。
 
-> 🐛 **常见误区**：很多人觉得工具描述写得越详细越好。实际上，工具描述的关键在于“边界清晰”而非“面面俱到”——什么时候该用、什么时候不该用，这两条线划清楚，比堆砌功能描述有效得多。
+> **常见误区**：很多人觉得工具描述写得越详细越好。实际上，工具描述的关键在于“边界清晰”而非“面面俱到”——什么时候该用、什么时候不该用，这两条线划清楚，比堆砌功能描述有效得多。
 
 **一个工具只做一件事，参数描述要包含格式示例**。这是工程化的基本准则，也是 Agent 工具设计的核心原则。
 
@@ -190,7 +196,7 @@ Few-shot prompting（给示例）是经过验证的有效策略，但很多人
 
 典型错误是往 Prompt 里塞几十个 edge case 示例，试图覆盖所有规则。这种做法的问题是：模型会过度拟合这些示例的表层模式，而忽略真正应该学的底层逻辑。
 
-业界常用的做法是选 **3-5 个多样化的典型示例（canonical examples）**。Anthropic 也强调了示例的多样性和典型性比数量更重要——“Canonical”的意思是“权威的、标准化的”，每个示例要能代表一类典型场景的解决模式，而非覆盖所有边缘情况。对模型来说，示例是“一幅画胜千言”的视觉化教学，展示“什么情况用什么策略”而非“什么输入对应什么输出”。
+业界常用的做法是选 **3-5 个多样化的典型示例（canonical examples）**。Anthropic 也强调了示例的多样性和典型性比数量更重要——"Canonical"的意思是“权威的、标准化的”，每个示例要能代表一类典型场景的解决模式，而非覆盖所有边缘情况。对模型来说，示例是“一幅画胜千言”的视觉化教学，展示“什么情况用什么策略”而非“什么输入对应什么输出”。
 
 ## 运行时上下文检索
 
@@ -214,7 +220,7 @@ Anthropic 把这种方式称为**渐进式披露（Progressive Disclosure）**
 
 当然，按需加载有明显的代价：**运行时探索比预检索更慢**，而且需要工程师提供足够好的导航工具（glob、grep、tree 等）让 Agent 能在信息海洋里不迷路。
 
-> 🐛 **常见误区**：很多人以为 Just-in-Time 就是“不预处理就好了”。实际上恰恰相反——按需加载对工具集和导航策略的设计要求更高。如果导航启发式规则不够好，Agent 容易误用工具、追入死胡同，浪费宝贵的上下文空间。
+> **常见误区**：很多人以为 Just-in-Time 就是“不预处理就好了”。实际上恰恰相反——按需加载对工具集和导航策略的设计要求更高。如果导航启发式规则不够好，Agent 容易误用工具、追入死胡同，浪费宝贵的上下文空间。
 
 更重要的是，如果缺乏精心设计的导航启发式规则，Agent 容易陷入**探索失败模式**：误用工具、追入死胡同、错过关键信息。这些失败会直接消耗宝贵的上下文空间，让原本就有限注意力预算雪上加霜。所以 Just-in-Time 不是“不预处理就好了”，而是需要同时设计好工具集和导航策略。
 
@@ -262,7 +268,7 @@ Anthropic 在 Sonnet 4.5 发布时推出了 Memory Tool 公开测试版，通过
 
 Anthropic 在"How we built our multi-agent research system"里详细描述了这个模式，相比单 Agent 在复杂研究任务上实现了显著的质量提升。
 
-**三种技术怎么选**：
+**三种技术怎么选：**
 
 | 技术        | 适用场景                                 |
 | ----------- | ---------------------------------------- |
@@ -297,7 +303,7 @@ Context Engineering 之所以重要，是因为它意味着工作重心的转移
 1. **上下文是系统输出，不是静态配置**。每次 LLM 调用前，你都在组装一个动态的上下文——这个组装逻辑本身才是工程的核心。
 2. **高信噪比优于高信息量**。上下文的长度不决定效果，找到让模型做出正确决策所需的最小高密度信息集，才是手艺。
 3. **上下文需要代谢机制**。对于长任务，没有什么是“一次组装永久有效”的——压缩、笔记、多 Agent 分层，这些机制让上下文在时间维度上保持新鲜和可用。
-4. **从最简方案开始，逐步增加复杂度**。Anthropic 反复强调 “do the simplest thing that works”——先用最小可行的上下文方案跑通基线，再基于实际 failure case 逐层优化。过度工程化的上下文系统和不足的上下文一样危险。
+4. **从最简方案开始，逐步增加复杂度**。Anthropic 反复强调 "do the simplest thing that works"——先用最小可行的上下文方案跑通基线，再基于实际 failure case 逐层优化。过度工程化的上下文系统和不足的上下文一样危险。
 
 Agent 失败的根源大多在上下文精度不够。把上下文工程做到位，中等水平的模型也能完成看似复杂的任务。