docs(ai): polish agent articles with cross-links, loop distinctions and verified sources

Author: Snailclimb

docs/ai/README.md

@@ -38,7 +38,7 @@ head:
 本专栏内容同时收录在开源 AIGuide 项目中：
 
 - **项目地址**：[https://github.com/Snailclimb/AIGuide](https://github.com/Snailclimb/AIGuide)
-- **在线阅读**：[https://javaguide.cn/ai-coding/](https://javaguide.cn/ai-coding/)
+- **在线阅读**：[https://javaguide.cn/ai/](https://javaguide.cn/ai/)
 
 文章会随 API、框架和模型能力变化持续校订，涉及版本、价格和产品能力时请同时核对对应官方文档。
 
@@ -69,6 +69,9 @@ AI 应用一旦上线，稳定性、可观测、成本控制、质量回归这
 3. [LLM 运行机制](./llm-basis/llm-operation-mechanism.md)、[大模型 API 调用工程实践](./llm-basis/llm-api-engineering.md)：理解模型调用链路、上下文和结构化返回。
 4. [AI Agent 核心概念](./agent/agent-basis.md)、[大模型提示词工程](./agent/prompt-engineering.md)、[上下文工程](./agent/context-engineering.md)：建立 Agent 和 Prompt/Context 的基础认知。
 5. [多 Agent 协作系统设计](./agent/multi-agent.md)：继续学习任务拆分、状态共享、冲突处理和失败恢复。
+
+   Memory、MCP、Skills、Harness、Workflow、Loop 的完整顺序见 [Agent 专题 README](./agent/README.md)。
+
 6. [RAG 基础概念](./rag/rag-basis.md)、[RAG 文档处理与切分策略](./rag/rag-document-processing.md)、[RAG 检索优化](./rag/rag-optimization.md)：补齐企业知识库问答主线。
 7. [AI 应用系统设计](./system-design/ai-application-architecture.md)、[LLM/Agent 安全实战](./system-design/llm-security.md)、[大模型网关详解](./system-design/llm-gateway.md)、[AI 应用评测体系](./llm-basis/llm-evaluation.md)：把 Demo 放进真实后端系统里，补齐权限、安全、网关、评测和治理。
 

docs/ai/TODO.md

@@ -27,18 +27,18 @@ head:
 
 ## P0 · 系统设计和安全补全
 
-| 文件名                              | 标题                                                      | 核心切入                                                                                                                                                  |
-| ----------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `system-design/llm-security.md`     | LLM 应用安全实战：Prompt 注入、工具越权与数据泄露防护     | 从传统“输入不可信”切入 AI 新攻击面，覆盖 Prompt Injection、Indirect Injection、工具权限边界、MCP Server 风险、最小权限、审计和 OWASP LLM Top 10           |
-| `system-design/ai-observability.md` | AI 可观测性与 Trace：为什么 Agent 失败不能只看最终答案    | 一次请求里的模型调用、检索、工具调用、上下文拼装、重试、fallback 全链路 span，覆盖 Langfuse、OpenTelemetry、自建审计表和 Java 后端落地结构                |
-| `agent/tool-calling.md`             | Agent 工具调用详解：Function Calling、MCP Tool 与权限控制 | 串起 `structured-output-function-calling.md`、`mcp.md` 和 `ai-application-architecture.md`，重点讲工具 Schema、参数校验、权限审批、执行结果回传和失败恢复 |
+| 文件名                              | 标题                                                   | 核心切入                                                                                                                                        |
+| ----------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `system-design/llm-security.md`     | LLM 应用安全实战：Prompt 注入、工具越权与数据泄露防护  | 从传统“输入不可信”切入 AI 新攻击面，覆盖 Prompt Injection、Indirect Injection、工具权限边界、MCP Server 风险、最小权限、审计和 OWASP LLM Top 10 |
+| `system-design/ai-observability.md` | AI 可观测性与 Trace：为什么 Agent 失败不能只看最终答案 | 一次请求里的模型调用、检索、工具调用、上下文拼装、重试、fallback 全链路 span，覆盖 Langfuse、OpenTelemetry、自建审计表和 Java 后端落地结构      |
+| `agent/tool-calling.md`（不新建）   | 补链接到已有工具调用文章（已补）                       | 已链接 [结构化输出与 Function Calling](./llm-basis/structured-output-function-calling.md)；只有 Agent Loop 特有、现文未覆盖的缺口才另写         |
 
 ## P1 · Agent 工程短板补全
 
-| 文件名                             | 标题                                               | 核心切入                                                                        |
-| ---------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `agent/agent-evaluation.md`        | Agent 评测与调试：如何判断 Agent 真的完成了任务    | 任务完成率、工具调用成功率、幻觉率、格式遵循率、延迟成本、Trace 回放和回归集    |
-| `llm-basis/llm-model-selection.md` | 大模型选型指南：通用、推理、代码、多模态模型怎么选 | 不同能力维度对比、Router/fallback/多模型编排、客服/RAG/代码/语音 Agent 的选型表 |
+| 文件名                                | 标题                                               | 核心切入                                                                                                                    |
+| ------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `agent/agent-evaluation.md`（不新建） | 补链接到已有评测文章（已补）                       | 已链接 [Agent 应用怎么评测](./llm-basis/llm-evaluation.md#agent-应用怎么评测)；只有 Agent Loop 特有、现文未覆盖的缺口才另写 |
+| `llm-basis/llm-model-selection.md`    | 大模型选型指南：通用、推理、代码、多模态模型怎么选 | 不同能力维度对比、Router/fallback/多模型编排、客服/RAG/代码/语音 Agent 的选型表                                             |
 
 ## P1 · RAG 深水区扩展
 
@@ -68,7 +68,7 @@ head:
 
 1. `system-design/llm-security.md`：JavaGuide 读者对安全话题接受度高，可以从传统 Web 安全自然过渡到 AI 新攻击面。
 2. `system-design/ai-observability.md`：能和 `harness-engineering.md`、`rag-optimization.md`、`llm-evaluation.md` 接上，形成“调试 -> 评测 -> 观测”闭环。
-3. `agent/tool-calling.md`：把 Function Calling、MCP Tool、权限审批和工具执行链路单独讲透，后续安全和系统设计都能复用。
+3. 工具调用与 Agent 评测入口：已在 Agent README、入门篇和面试题补链接到已有文章；不新建 `agent/tool-calling.md` 或 `agent/agent-evaluation.md`，只有 Agent Loop 特有、现文未覆盖的缺口才另写。
 4. `framework/README.md` + `framework/spring-ai.md`：`framework/` 目前为空，先补 Java 读者最容易用上的 Spring AI。
 
 ## 维护规则

docs/ai/agent/README.md

@@ -37,6 +37,14 @@ Agent 不是“会调用工具的聊天机器人”。一旦任务变长，它
 5. [多 Agent 协作系统设计](./multi-agent.md)：理解任务拆分、状态共享、并发冲突和失败恢复。
 6. [Harness Engineering：六层检查框架、上下文管理与工程实践](./harness-engineering.md)、[AI 工作流中的 Workflow、Graph 与 Loop](./workflow-graph-loop.md)、[Loop Engineering 是什么](./loop-engineering.md)：进入生产级 Agent 工程化。
 
+阅读时注意区分三种循环：
+
+| 层次                  | 负责什么                                                          | 对应文章                                                                |
+| --------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| 内层 Agent Loop       | 一次任务中反复推理、调用工具、读取结果，直到完成或触发停止条件。  | [Agent 核心概念](./agent-basis.md#什么是-agent-loop)                    |
+| 工作流图上的回边      | 按状态和条件返回先前节点，让局部流程继续迭代。                    | [Workflow、Graph 与 Loop](./workflow-graph-loop.md#loop-graph-上的回溯) |
+| 外层 Loop Engineering | 把已有循环接到 CI、定时任务和停止条件上，决定何时启动下一轮任务。 | [Loop Engineering](./loop-engineering.md)                               |
+
 ## 核心文章
 
 - [AI Agent 核心概念](./agent-basis.md)：梳理 AI Agent 的演进脉络，讲清 Agent Loop、Context Engineering、Tools 注册等基础概念。
@@ -50,6 +58,11 @@ Agent 不是“会调用工具的聊天机器人”。一旦任务变长，它
 - [AI 工作流中的 Workflow、Graph 与 Loop](./workflow-graph-loop.md)：对比传统工作流与 AI 工作流的差异，覆盖 Spring AI Alibaba 和 LangGraph 实现。
 - [Loop Engineering 是什么？为什么说它是新瓶装旧酒？](./loop-engineering.md)：把 Loop Engineering 放回 Agent Loop、Context、Harness、Skills、MCP 和验证闭环里，理解它到底新在哪里。
 
+工具调用和评测的完整内容在已有文章中：
+
+- [结构化输出与 Function Calling](../llm-basis/structured-output-function-calling.md)：覆盖工具调用完整链路、权限、二次确认、幂等、审计、超时和 Java 示例。
+- [Agent 应用怎么评测](../llm-basis/llm-evaluation.md#agent-应用怎么评测)：覆盖任务完成率、工具调用、执行轨迹、错误恢复和多次运行一致性等指标。
+
 ## 高频问题
 
 - Agent 和 Workflow、Chatbot、普通工具调用有什么区别？

docs/ai/agent/agent-basis.md

@@ -1,5 +1,5 @@
 ---
-title: AI Agent 核心概念：Agent Loop、Plan-and-Execute、A2A、Agentic Workflows、Tools 注册
+title: AI Agent 核心概念：Agent Loop、Plan-and-Execute、结构化任务契约、Agentic Workflows、Tools 注册
 description: 深入解析 AI Agent 核心概念，梳理从被动响应到常驻自治的演进历程，对比 Agent、传统编程、Workflow 的区别和适用场景。
 category: AI 应用开发
 head:
@@ -70,7 +70,7 @@ Agent：用户说意图 → AI 决策 → 动态执行
 
 聊 Agent 不能只讲愿景，也得说点真实问题。
 
-- 长任务跑久了，历史信息会被截断，模型会”失忆”。更烦的是，上下文变长后推理质量不一定更好，很多模型对中间位置的信息利用效率并不高
+- 长任务跑久了，历史信息会被截断，模型会“失忆”。更烦的是，上下文变长后推理质量不一定更好，很多模型对中间位置的信息利用效率并不高
 - 工具调用可以降低幻觉，但不能彻底消灭。LLM 在推理步骤里仍然可能生成错误判断，工具返回结果也不一定能把它拉回来
 - 多轮迭代、工具调用、日志回传、上下文压缩，每一项都在烧 Token。复杂任务跑一轮，账单可能真会让人清醒
 - Agent 能执行代码、调 API、读写文件，也就一定会面对 Prompt Injection 和越权操作风险。更现实的做法是权限最小化、沙箱隔离、高危操作人工确认
@@ -95,6 +95,8 @@ AI Agent 是能感知环境、决策并执行动作的软件系统。LLM 处理
 
 **Tools（工具）**负责查询数据、调用 API、读写文件或执行代码。执行结果必须追加进上下文，成为下一轮的 Observation（观察）；否则模型看不到外部操作的反馈，后续动作也就无从判断。
 
+工具调用的完整链路、权限、二次确认、幂等、审计、超时和 Java 示例，见 [结构化输出与 Function Calling](../llm-basis/structured-output-function-calling.md)；任务完成率、工具调用和执行轨迹等指标，见 [Agent 应用怎么评测](../llm-basis/llm-evaluation.md#agent-应用怎么评测)。
+
 ### 什么是 Agent Loop？
 
 Agent Loop 把这条反馈链路连续跑起来。每轮先由 LLM 根据上下文选择动作，再执行工具并写回结果；任务完成或命中停止条件时退出。
@@ -103,7 +105,7 @@ Agent Loop 把这条反馈链路连续跑起来。每轮先由 LLM 根据上下
 
 Loop 初始化时载入 System Prompt、工具列表和用户请求。之后模型在“直接回复”和“调用工具”之间选择；工具结果写回上下文，直到模型不再请求工具。
 
-最大迭代轮次通常设在 10 到 20 轮，也可以按 Token 消耗终止。这个边界用来阻止错误判断把任务带进无限循环。
+最大迭代轮次设在 10 到 20 轮是常见上限之一，也可以按 Token 消耗终止。这个边界用来阻止错误判断把任务带进无限循环。
 
 上下文会随着每轮结果不断变长，关键信息被稀释后，模型更容易跑偏。Context Engineering 处理的正是筛选和组织这些信息的问题。LangChain、LlamaIndex、Spring AI 提供的封装不同，底层都绕不开这条 Loop。
 
@@ -228,7 +230,7 @@ Prompt Engineering 更偏提示词怎么写，Context Engineering 管得更宽
 
 ![Context Engineering 和 Prompt Engineering 差别](https://oss.javaguide.cn/github/javaguide/ai/context-engineering/context-engineering-vs-context-engineering-dimension-comparison.png)
 
-这块展开讲内容很多，可以单独看这篇：[《提示词工程（Prompt Engineering）》](https://javaguide.cn/ai/agent/prompt-engineering.html) 和 [《上下文工程（Context Engineering）》](https://javaguide.cn/ai/agent/context-engineering.html)。
+这块展开讲内容很多，可以单独看这两篇：[《提示词工程（Prompt Engineering）》](https://javaguide.cn/ai/agent/prompt-engineering.html) 和 [《上下文工程（Context Engineering）》](https://javaguide.cn/ai/agent/context-engineering.html)。
 
 ## Agent 核心范式有哪些？
 
@@ -304,22 +306,24 @@ Reflection 通常叠加在 ReAct 或 Plan-and-Execute 上：执行过程中加
 
 落地时还要处理任务契约、共享状态、并行写冲突、Worker 接管和检查点恢复。详细设计可以看 [《多 Agent 协作系统设计：任务拆分、状态共享、冲突处理与失败恢复》](./multi-agent.md)。
 
-### A2A 协议
+### 结构化任务契约
 
 单个 Agent 升级到 Multi-Agent 后，Agent 之间怎么沟通会变成一个工程问题。
 
 如果还靠自然语言互相聊天，Token 消耗很高，也容易出现格式解析错误。
 
-A2A 协议就是为了解决这个问题。
+结构化任务契约可以减少这类交接问题。
 
-它让 Agent 之间用结构化数据交互，比如带 Schema 的 JSON、XML，或者状态流转指令，而不是一堆自然语言废话。
+它要求角色之间交付带 Schema 的结果，而不是一段自然语言，比如用 JSON、XML 表达任务字段、结果和状态流转指令。
 
 类比一下，后端微服务之间不会通过解析 HTML 页面交换数据，而是用 RESTful 或 RPC 接口传结构化对象。
 
-A2A 协议就是给 Agent 之间定义接口契约。
+结构化任务契约明确每个角色接收什么、交付什么，以及如何校验结果。
 
 比如“产品经理 Agent”写完需求后，不会输出一句“我写好了，你开发一下”。它应该输出一个标准 JSON Payload，里面包含 TaskID、Dependencies、AcceptanceCriteria。开发 Agent 拿到后直接反序列化，进入执行流程。
 
+这种结构化交付不等于实现了 A2A 协议；跨进程 Agent 的能力发现、任务状态和产物交付，见 [多 Agent 篇的 A2A 一节](./multi-agent.md#a2a-能解决什么-不能解决什么)。
+
 ![A2A 协议架构](https://oss.javaguide.cn/github/javaguide/ai/agent/agent-a2a.png)
 
 ### Agentic Workflows

docs/ai/agent/agent-memory.md

@@ -12,7 +12,7 @@ head:
 
 长任务一跑起来，很快就会撞到几件硬约束：上下文窗口有上限，Token 账单会一路涨，Session 结束后如果没有落库，上一轮轨迹默认就跟进程一起消失。模型即使能完成当前推理，也缺少保存和复用历史记录的位置。
 
-记忆层需要同时保住当前对话的关键事实，并让新 Session 能取回用户偏好、背景和历史决策。文章依次讨论记忆的表征和功能分类、读写生命周期、短期与长期实现、主流产品和检索优化，以及 Markdown 记忆。滑动窗口怎么裁、overload 怎么卸，和同站的 [《上下文工程(Context Engineering) 是什么？和 Prompt Engineering 有什么区别？》](./context-engineering.md) 有交集，两篇可以对着看。
+记忆层需要同时保住当前对话的关键事实，并让新 Session 能取回用户偏好、背景和历史决策。文章依次讨论记忆的表征和功能分类、读写生命周期、短期与长期实现、主流产品和检索优化，以及 Markdown 记忆。滑动窗口怎么裁、offload 怎么卸，和同站的 [《上下文工程(Context Engineering) 是什么？和 Prompt Engineering 有什么区别？》](./context-engineering.md) 有交集，两篇可以对着看。
 
 ## Agent 的记忆系统是如何设计的？
 
@@ -83,6 +83,8 @@ head:
 
 ![上下文利用率的 40% 阈值现象](https://oss.javaguide.cn/github/javaguide/ai/harness/context-utilization-40-percent-threshold-phenomenon.svg)
 
+图中的 40% 来自特定模型和任务的观察，不是通用阈值；Lost in the Middle 的位置偏差与上下文增长后信息利用率下降是两件事，不能混为一谈。
+
 为了控制短期记忆膨胀，框架层常见三种做法，和上下文工程里的 Token 降级、JIT 卸载属于同一类思路。
 
 第一种是上下文缩减（Context Reduction）。当对话历史达到预设 Token 阈值时，框架自动丢弃最早的 N 轮消息，也就是滑动窗口；或者调用轻量模型把历史对话压缩成摘要，用信息损耗换上下文空间。