docs(ai): 完善Agent介绍

Author: Snailclimb

docs/ai-coding/README.md

@@ -1,13 +1,13 @@
 ---
 title: AI 编程实战指南：Claude Code、Cursor、Codex、Trae 使用技巧与面试题
-description: AI 编程面试与实战学习路线，涵盖 Claude Code、Cursor、OpenAI Codex、Trae、CLI vs IDE 选型、多模型协同和代码审查。
+description: AI 编程实战指南：Claude Code 使用技巧与核心命令、Vibe Coding 技巧、OpenAI Codex 最佳实践、Spec Coding 规范驱动编程、AI 代码审查与提交管理。覆盖工具选型、真实项目案例和 AI 编程面试题，帮你把 AI 编程工具用稳、用到生产级。
 category: AI 编程
 tag:
   - AI 编程
   - AI 辅助开发
   - 开发效率
   - 后端面试
-icon: "mdi:code-tags"
+icon: mdi:code-tags
 head:
   - - meta
     - name: keywords
@@ -24,6 +24,8 @@ head:
 
 AI 编程工具好不好用，真不全看模型。很多时候，差别反而出在你怎么给上下文、怎么拆任务、怎么看 diff。
 
+当然了，这不是说模型不重要，模型的质量是根本。但使用同样的模型，在不同的人手中最终达到的效果是差别很大的。
+
 别把它想成“我把需求丢给 AI，然后代码自己就写好了”。真实项目里没这么轻松。更常见的是：AI 写到一半方向歪了，你得接回来；一次改太多文件，你得拆小；测试没过，你还得顺着错误往回追；它一本正经瞎编的时候，你得能看出来。
 
 所以这个专题不会只聊“哪个工具最强”。Claude Code、Cursor、OpenAI Codex、Trae 都有能帮上忙的地方，关键是你得知道：什么时候让 AI 写代码，什么时候让它查资料、读代码，什么时候该自己上手。还有更重要的一点，出问题以后怎么回滚，怎么把影响控制住。

docs/ai-coding/deepseek-v4-claude-code.md

@@ -53,7 +53,13 @@ npm install -g @anthropic-ai/claude-code
 }
 ```
 
-注意替换 `your_deepseek_api_key` 为你的 DeepSeek API Key。如果你使用的是 DeepSeek-V4-Flash，把 `ANTHROPIC_MODEL` 改为 `DeepSeek-V4-Flash` 即可。
+注意替换 `your_deepseek_api_key` 为你的 DeepSeek API Key。
+
+API Key 创建地址：<https://platform.deepseek.com/> 。
+
+![DeepSeek 创建 API Key](https://oss.javaguide.cn/github/javaguide/ai/coding/deepseek-api-keys.png)
+
+如果你使用的是 DeepSeek-V4-Flash，把 `ANTHROPIC_MODEL` 改为 `DeepSeek-V4-Flash` 即可。
 
 配置完成后启动 Claude Code：
 

docs/ai/agent/agent-basis.md

@@ -1,5 +1,5 @@
 ---
-title: AI Agent 核心概念：Agent Loop、Context Engineering、Tools 注册
+title: AI Agent 核心概念：Agent Loop、Plan-and-Execute、A2A、Agentic Workflows、Tools 注册
 description: 深入解析 AI Agent 核心概念，梳理从被动响应到常驻自治的演进历程，对比 Agent、传统编程、Workflow 的区别和适用场景。
 category: AI 应用开发
 head:
@@ -8,8 +8,6 @@ head:
       content: AI Agent,智能体,ReAct,Function Calling,RAG,MCP,多智能体协作,Computer Use
 ---
 
-<!-- @include: @article-header.snippet.md -->
-
 第一次被 ChatGPT 震到的时候，很多人应该都还在研究 Prompt 怎么写。那时候它更像一个会聊天的知识库。你问，它答；你不问，它也不会自己动。三年过去，AI 已经不只是在聊天框里回复文字了。它开始会调用工具，会读文件，会跑代码，甚至能操作电脑界面。
 
 再往前走一步，就是现在大家反复提到的 AI Agent。
@@ -30,9 +28,9 @@ AI Agent 不是突然冒出来的。它大概经历了几次明显变化。
 
 **2022 年，ChatGPT 这类产品刚火的时候**，大家主要还在和模型“对话”。能力很强，但它只能基于已有知识回答问题，不能主动调用外部工具，也不能自己完成操作。
 
-当时最重要的玩法是 Prompt Engineering。你把提示词写得越清楚，它回答得越稳。
+当时最重要的玩法是 [Prompt Engineering](https://javaguide.cn/ai/agent/prompt-engineering.html)。你把提示词写得越清楚，它回答得越稳。
 
-但它还是不能动。
+但它本质上还是会说，不是会做。
 
 **2023 年中，Function Calling 出现后，事情开始变了。**
 
@@ -42,15 +40,39 @@ LLM 可以调用外部 API，不再只是生成文字。RAG 也开始大规模
 
 **2023 年底，大家开始重视编排。**
 
-ReAct 这种推理框架逐渐被接受，多智能体协作也开始被讨论。Coze、Dify 这类平台把开发门槛降了下来，用 DAG（有向无环图）来约束执行流程，避免 AutoGPT 那种完全放飞的自治方式。
+ReAct 这种推理框架逐渐被接受。模型不只是直接给答案，而是先思考下一步要做什么，再决定是否调用工具，然后根据工具返回结果继续推理。
+
+多 Agent 协作也开始被讨论。比如一个 Agent 负责规划，一个 Agent 负责执行，一个 Agent 负责检查。
+
+Coze、Dify 这类平台把开发门槛降了下来，用 DAG（有向无环图）来约束执行流程，避免 AutoGPT 那种完全放飞的自治方式。
 
 **2024 年底，标准化和多模态开始变重要。**
 
-MCP 协议出现，解决工具接入碎片化的问题。Computer Use 让 Agent 可以操作图形界面。Cursor 这类 AI 编程工具也把 "Vibe Coding" 带火了。
+[MCP 协议](https://javaguide.cn/ai/agent/mcp.html)出现，解决工具接入碎片化的问题。Computer Use 让 Agent 可以操作图形界面。
+
+AI 编程工具也在这个阶段快速发展。Cursor、Claude Code、Codex 这类工具把代码库阅读、修改、测试、提交串了起来，“Vibe Coding”也在这个阶段被更多人讨论。
+
+**2025 年，Agent 开始往长任务执行方向走。**
+
+这一年，Agent 不再只是一次对话里的助手，而是开始变成可以接任务、跑流程、产出结果的工作单元。
+
+Agent Skills 这类机制也开始出现。很多任务不是一句 Prompt 就能做好，而是需要固定流程、上下文、模板、脚本和校验规则。Skill 做的就是把这些方法封装下来，让 Agent 遇到类似任务时按既定流程执行。
 
-**2025 年，Agent 开始往常驻自治方向走。**
+**到了 2026 年，Agent 开始更接近长期在线的数字工作单元。**
 
-Agent Skills、Heartbeat 这类机制成熟后，Agent 可以在后台长时间运行，也开始强调本地数据主权。
+OpenClaw 这类项目把 Skills 和 Heartbeat 推到更显眼的位置。
+
+Skills 负责封装能力，Heartbeat 负责周期性唤醒 Agent，让它检查消息、处理任务、更新状态，而不是只能等用户下一次提问。
+
+不过，Heartbeat 不等于真正的连续意识，它更像定时唤醒；本地数据主权也不等于绝对安全。只要 Agent 能安装 Skill、访问文件、执行脚本，就会带来新的权限、沙箱和供应链风险。
+
+Harness Engineering 也开始被更多人讨论。
+
+可以简单理解为：Agent = Model + Harness。模型负责推理和生成，Harness 负责把模型放进一个可执行、可观察、可恢复、可验证的工作环境里。
+
+大家不再只盯着模型参数、上下文长度和 Prompt 技巧，开始更关注模型外面的工程环境。
+
+**后续发展展望。**
 
 再往后看，几个方向会继续推进：内建记忆、预测能力，以及从数字世界扩展到物理机器人。
 
@@ -215,7 +237,7 @@ OpenAI Schema 解决数据格式问题，MCP 解决通信接入问题。
 
 Claude Code、Cursor 这类工具已经原生支持这套模式，会自动扫描项目里的 `.claude/skills/` 目录，由模型自己判断哪个 Skill 该激活。
 
-纯代码封装、调用路径固定，用 Toolkits。团队经验沉淀、任务流程灵活，用 Agent Skills 更合适。更详细的 Skills 工程实践——包括路由设计、SKILL.md 写法避坑、第三方 Skill 安全审计，可以看：[《Agent Skills 详解》](./skills.md)。
+纯代码封装、调用路径固定，用 Toolkits。团队经验沉淀、任务流程灵活，用 Agent Skills 更合适。更详细的 Skills 工程实践——包括路由设计、SKILL.md 写法避坑、第三方 Skill 安全审计，可以看：[《Agent Skills 详解》](https://javaguide.cn/ai/agent/skills.html)。
 
 ### 通信接入：MCP 协议
 
@@ -251,17 +273,19 @@ JSON Schema 是数据格式，MCP 是通信协议层。
 
 Prompt（提示词）可以简单理解为给大语言模型下达的指令。Prompt Engineering 就是怎么把这条指令写清楚，让模型输出更可控。关键在边界是否清晰——指令越模糊，模型越容易乱猜；指令越结构化，输出就越稳定。
 
-这块展开讲内容很多，可以单独看这篇：[《提示词工程（Prompt Engineering）》](./prompt-engineering.md)。
+这块展开讲内容很多，可以单独看这篇：[《提示词工程（Prompt Engineering）》](https://javaguide.cn/ai/agent/prompt-engineering.html)。
 
 ## 什么是 Context Engineering？
 
-很多 Agent 做不好，不是模型太弱，而是上下文太乱。
+很多时候， Agent 做不好，不是模型能力太多，而是上下文太乱。
 
 Context Engineering 做的事情，就是在有限 Token 窗口里，把最有用的信息喂给模型，把噪声挡在外面。它很容易和 Prompt Engineering 混在一起。
 
 Prompt Engineering 更偏提示词怎么写，Context Engineering 管得更宽，包括规则、记忆、工具描述、会话状态、外部观察结果、Token 预算。
 
-这块展开讲内容很多，可以单独看这篇：[《提示词工程（Prompt Engineering）》](./prompt-engineering.md) 和 [《上下文工程（Context Engineering）》](./context-engineering.md)。
+![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)。
 
 ## Agent 核心范式有哪些？
 
@@ -413,7 +437,7 @@ Node 只做一件事，读取状态、执行逻辑、写回结果。节点里可
 
 “审核不通过就回到修改，最多重试 3 次”，翻译成图结构，是一条从 ReviewNode 指向 ReviseNode 的条件边，加上 `iteration_count >= 3` 时跳到 ExitNode 的安全边界。State 里的 `iteration_count` 是让这条逻辑能跑起来的关键。
 
-这套图结构比写死的 if-else 链更容易扩展，出了问题也好定位到哪个节点哪条边。LangGraph（Python）和 Spring AI Alibaba Graph（Java）都是基于这套思路实现的。详细设计和代码实现可以看：[《AI 工作流中的 Workflow、Graph 与 Loop》](./workflow-graph-loop.md)。
+这套图结构比写死的 if-else 链更容易扩展，出了问题也好定位到哪个节点哪条边。LangGraph（Python）和 Spring AI Alibaba Graph（Java）都是基于这套思路实现的。详细设计和代码实现可以看：[《AI 工作流中的 Workflow、Graph 与 Loop》](https://javaguide.cn/ai/agent/workflow-graph-loop.html)。
 
 ### 什么时候用 Agent，什么时候用 Workflow？