ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter10/book-translation/validation/real_20260730T053000Z_v3/single_agent_parts/getting_started_with_ai_agents_part_1_9_zh.md

@@ -0,0 +1,46 @@
+# 人工智能代理入门 [第1部分/共9部分]
+# 人工智能代理入门
+
+如果你使用过Cursor编写代码，看到它搜索代码库、编辑多个文件并重新运行测试直到通过，那么你已经使用过人工智能代理了。如果你使用过Deep Research通过反复搜索和阅读来研究某个主题，让Manus控制浏览器完成在线任务，让豆包手机助手订票或发送消息，或者让Pine AI协商降低电信账单，也是如此。
+
+这些产品形式多样，但它们有一个共同特征：它们不再是被动的“你问，它答”式对话。它们会规划自己的执行步骤，调用每个任务所需的工具，并根据结果调整策略。人工智能代理正在成为与计算机交互的一种新方式。
+
+本章从实际示例入手，逐步回溯人工智能代理的核心组件：读者将亲身体验现代代理能做什么，理解其背后的架构，并学习构建代理系统的设计模式和最佳实践。
+
+> **阅读提示**：本章是整本书的概念框架图：简明概述核心公式、运行循环、工程框架和代理设计模式。它建立了贯穿后续章节的通用词汇和参考点。第一次阅读时不要试图记住每个概念，要把握大局。后续每一章都会扩展这里介绍的一个方面，你可以在需要重新定位时回到本章。
+
+## 现代代理 = 大语言模型 + 上下文 + 工具
+
+现代代理系统的本质可以用一个简洁的公式概括：**代理 = 大语言模型（LLM） + 上下文 + 工具**。这个公式简单实用——前提是每个术语都要广义理解：
+
+- **大语言模型是代理的推理引擎**：它不仅仅是一组模型参数；它是代理的决策核心，负责理解意图、推理、规划和判断。大语言模型的能力来自预训练期间获取的世界知识和语言能力，以及通过后训练编码的决策策略（第7章将介绍监督微调、强化学习等技术）。
+- **上下文是代理的工作信息集**：不仅仅是输入模型的文本，而是代理在每个决策点可用的工作信息集——环境、用户记忆、领域知识、自身状态和任务进度。就像人做决策时需要评估情况、回忆相关经验并查阅参考资料一样，代理的上下文窗口包含了它当时可以使用的信息。
+- **工具是代理的行动接口**：不仅仅是少数可调用的API函数，而是代理可以采取行动的全套方式——从预定义的工具调用到按需加载的技能，从生成代码即时创建新能力到将工作委托给子代理，从与用户互动到响应外部事件。
+
+更直观地说：**代理 = 推理引擎 + 工作上下文 + 行动接口**。模型进行推理和决策，上下文提供这些决策所依赖的工作信息集，工具提供决策影响外部世界的接口。
+
+这三个组件正好对应强化学习（RL）中的三个核心概念（见第7章）。下表为**可选阅读**——如果你没有强化学习背景，可以随意跳过；后面的内容不依赖于此。它仅用于帮助了解强化学习的读者将相关知识映射到本书的术语中：
+
+| 直觉       | 代理组件   | 强化学习概念（可选） | 角色                                                         |
+|------------|------------|----------------------|--------------------------------------------------------------|
+| **推理引擎** | 大语言模型 | **策略**             | 确定“下一步做什么”的决策逻辑——根据当前信息，从所有可用选项中选择最合适的行动 |
+| **工作上下文** | 上下文     | **观测空间**         | 代理可用的所有信息——它能观测、读取、记住的内容以及能访问的系统 |
+| **行动接口** | 工具       | **行动空间**         | 代理可以做的全套事情——可用的“手段”，从发送消息到执行代码再到控制接口 |
+
+### 观测空间和行动空间：模型与世界的接口
+
+在经典教材《计算机体系结构：量化研究方法》中，亨尼西和帕特森在第1章开篇提出“什么是计算机体系结构？”，并将**指令集架构**（ISA）确定为软件和硬件之间的接口[^ch1-agent-interface]。这一视角为我们理解代理提供了一种有用的方式：**观测空间和行动空间共同构成了大语言模型与其外部环境之间的接口**。观测空间将环境中的信息转化为模型可以处理的上下文；行动空间将模型的决策转化为对外部世界的操作。对于模型来说，观测空间之外的信息实际上不存在。即使模型完全知道应该做什么，行动空间之外的操作仍然只是模型可以用语言推荐的事情。
+
+因此，**一旦底层模型保持不变，提高代理性能的主要系统工程手段通常是重新定义或扩展其观测空间和行动空间**。用本书的术语来说，这意味着扩展上下文和工具。许多看似需要“更智能模型”的问题实际上是接口问题：将与任务相关的数据带入上下文，或将所需操作暴露为工具，那么之前无法解决的任务可能无需重新训练模型就能解决。
+
+**Manus: merging spaces that had been separate.**  在Manus出现之前，生产型代理大多遵循三条不同的路径：深度研究、编码和计算机使用。Manus是第一个将这三者整合到一个系统中的具有广泛影响力的生产型代理。网络扩大了它的观测空间；文件系统和代码执行扩大了它的行动空间；屏幕感知以及点击和打字将图形界面带入了两者。Manus并非仅仅通过替换更强的模型就成为通用代理。它整合了三种代理的观测空间和行动空间，使一个代理跨越了之前的产品边界。
+
+**OpenClaw: extending the interface into the user's digital life.**  OpenClaw再次将两个空间向外扩展。它通过用户已经使用的消息通道——WhatsApp、Telegram、Slack、Discord、iMessage等——接收任务并返回结果，因此几乎可以从任何地方接触到该代理。它的本地优先网关，加上授权的工具、插件和技能，可以连接谷歌云端硬盘和Notion等云应用以及本地文件系统。因此，在用户明确授权的情况下，分散在不同账户和设备上的文件可以进入一个代理的观测空间，并由其工具进行操作。与最初以云沙盒为中心的Manus形式相比，在Manus中文件通常必须上传或单独配置连接器，而本地优先的OpenClaw跨越了更广泛的数据边界。Manus后来添加了自己的谷歌云端硬盘连接器和对本地文件的桌面访问——这进一步证明了一点：产品演进往往正是通过扩展观测空间和行动空间来实现的[^ch1-agent-products]。
+
+扩展并不意味着立即将所有可用的标记和工具倾倒进模型。不相关的上下文会增加噪声，而太多工具会增加选择成本和安全风险。有用的扩展必须是**按需、相关且可控的**：检索应将正确的信息放入上下文，工具发现应仅暴露当前需要的行动，权限和结果验证应约束这些行动。后续章节将展开介绍这些技术。
+
+[^ch1-agent-interface]: 约翰·L·亨尼西和大卫·A·帕特森，《计算机体系结构：量化研究方法》，第6版，摩根·考夫曼出版社，2019年，第1章“什么是计算机体系结构？”该书区分了指令集架构、计算机组织和硬件；指令集架构专门是软件和硬件之间的接口。参见https://shop.elsevier.com/books/computer-architecture/hennessy/978-0-12-811905-1
+
+[^ch1-agent-products]: Manus的官方资料将其原始沙盒描述为孤立的云虚拟机。在介绍其谷歌云端硬盘连接器时，Manus明确回顾了早期在云端硬盘、桌面和Manus之间手动下载和上传文件的零散工作流程。当它在2026年3月推出“My Computer”时，称重要工作存储在本地而非云端是云沙盒的根本限制。OpenClaw的官方README描述了一个运行在用户自己设备上的本地优先、始终在线的个人助手，并列出了二十多个消息通道；其工具和插件系统可以添加云集成和本地功能。参见https://manus.im/blog/manus-sandbox，https://manus.im/blog/manus-google-drive-connector，https://manus.im/blog/manus-my-computer-desktop，https://github.com/openclaw/openclaw，以及https://docs.openclaw.ai/tools
+
+理解每个组件的作用以及它们如何协同工作，是构建有效代理系统的基础。我们将从三者中最具体的部分——工具，即行动接口——开始，向内深入到大语言模型和上下文。首先，以下是不同类型代理在这三个维度上的比较：

chapter10/book-translation/validation/real_20260730T053000Z_v3/single_agent_parts/getting_started_with_ai_agents_part_2_9_zh.md

@@ -0,0 +1,65 @@
+# 人工智能代理入门 [第2部分/共9部分]
+
+| 代理产品         | 工作上下文                     | 行动接口                           | 策略                                 |
+|------------------|--------------------------------|------------------------------------|--------------------------------------|
+| **编码代理（例如Cursor）** | 需求文档、代码库、终端环境     | 开放式（内部推理、代码搜索、文件读写、命令执行等） | 增量式开发：理解需求→搜索相关代码→编辑代码→测试验证→调试修复 |
+| **搜索代理（例如Deep Research）** | 网络资源、学术数据库、本地文件 | 开放式（内部推理、搜索查询、网页阅读、摘要生成）   | 迭代深化：根据现有信息调整搜索方向，逐步合成完整报告 |
+| **计算机控制代理（例如浏览器使用）** | 计算机屏幕、浏览器页面、文件系统 | 开放式（内部推理、点击、打字、滚动、截图、代码执行等） | 视觉感知+操作：观察屏幕→识别目标元素→执行操作→验证结果 |
+| **手机助手代理（例如豆包）** | 手机屏幕、已安装应用           | 开放式（内部推理、点击、滑动、打字、打开应用等）   | 意图理解+应用控制：理解用户需求→定位目标应用→执行操作→确认完成 |
+| **个人任务代理（例如Pine AI）** | 用户账户信息、历史账单、服务提供商知识库 | 开放式（内部推理、打电话、发邮件、填表、与用户确认） | 多步骤任务执行：收集信息→制定协商策略→联系服务提供商→协商→报告结果 |
+
+这些系统具有三个共同特征：**开放式行动空间**——不是从固定的按钮集合中选择，而是生成任意自然语言和代码；**内部推理**——行动前进行规划；以及**持续交互**——根据环境反馈调整策略。这些能力正是来自推理引擎、工作上下文和行动接口的相互作用——也就是大语言模型、上下文和工具的相互作用。
+
+### 工具：代理的行动接口
+
+工具是代理与外部世界的桥梁。它们将代理从被动的观察者转变为可以搜索、写入文件、运行代码、调用API、发送消息或操作接口的主动系统。没有工具，代理仅限于文本生成；有了工具，它可以对外部系统采取行动。
+
+为了系统地讨论工具，我们可以根据代理与世界交互的方向将其分为五类。在这个阶段，简要概述每种类型的代表性场景足以建立整体图景；后续章节将深入探讨每种类型。
+
+**感知工具**允许代理访问信息：搜索引擎提供实时网络数据，文件系统读取本地文档，API和数据库连接外部服务和企业核心数据。
+
+**执行工具**允许代理对外部系统采取行动：代码执行、文件操作、系统命令和外部API调用将决策转化为具体行动。
+
+**协作工具**允许代理与其他代理分工：将专门任务委托给子代理，在关键决策点请求人类确认，或在多代理系统中协调行动。
+
+**事件触发工具**以与前三类根本不同的方式被调用：代理不调用它们；它们作为外部输入到达，触发代理开始工作。新邮件到来、预定时间到达或另一个系统触发Webhook回调；事件激活代理并启动推理和行动。代理从不自己调用这些工具，但它们仍然是代理与外部世界交互的通道，因此我们将其计入广义的工具系统中。
+
+**用户通信工具**是代理与用户通信的通道。执行工具改变外部世界，而通信工具传递信息——通过短信、语音通话、电子邮件等传递代理的进度或主动联系。
+
+第4章将涵盖这五类的完整分类法和设计原则。工具设计的质量直接决定了代理可以可靠完成的任务：接口定义模糊，模型会误用它们；错误处理不佳，单个失败的工具可能会让代理陷入困境；权限范围过广，一个代理错误可能变得不可逆转。随着MCP（模型上下文协议）标准的传播，集成工具变得像安装插件一样简单——生态系统正在迅速扩展，但设计原则不会过时。
+
+**工具调用**（也称为函数调用）是现代大语言模型代理的核心能力：它让模型以结构化方式调用外部工具，将大语言模型从纯文本生成器转变为可以通过外部接口行动的智能系统。本书通篇使用“工具调用”这一术语。
+
+工具调用分为四个步骤：首先，上下文告诉模型哪些工具可用（名称、用途、参数）；然后模型自行决定是否调用工具、调用哪个工具以及使用什么参数；接下来，工具运行后，其结果附加到上下文中；最后，模型根据该结果决定下一步行动。这个循环是本章稍后介绍的ReAct方法的基础。
+
+以天气查询为例，API级别四步过程的简化表示如下：
+
+```
+步骤1：声明工具                  步骤2：模型决定调用
+tools: [{                             assistant: {
+  name: "get_weather",                  tool_calls: [{
+    parameters: {                           function: "get_weather",
+      city: "string"                        arguments: {city: "Beijing"}
+    }                                      }]
+}]                                    }
+
+步骤3：结果附加到上下文          步骤4：模型根据结果响应
+tool: {                               assistant: {
+  tool_call_id: "call_1",               content: "Today in Beijing: 28°C, sunny."
+  content: '{"temp":28,"sky":"clear"}' }
+}                                     }
+```
+
+开发者只需定义工具并执行调用；模型自行决定是否调用、调用哪个工具以及传递什么参数。第2章将详细检查这种API结构。
+
+为代理设计工具时，从任务所需的最窄能力开始，然后随着任务变得更复杂逐步扩展。如果任务只需要基本算术，具有明确定义参数的计算器就足够了；当任务扩展到读取电子表格、清理缺失值、计算统计数据和绘制图表时，受约束的Python代码解释器比不断增长的专门工具集合更容易组合和探索。但通用性也会增加错误风险并扩大攻击面：代码必须在隔离沙盒中运行，默认禁用网络访问，无法访问授权工作目录外的文件，并且对执行时间、CPU、内存和输出大小有限制。
+
+同样，单个日志工具适用于记录一次执行；对于耗时数小时甚至数天的长期任务，受控的虚拟工作目录可以保存计划、中间结果、执行日志和最终工件，以便代理在多次运行中恢复。该目录还应限制可读和可写路径、存储容量和文件类型，并防止路径遍历，而不是将整个主机文件系统暴露给代理。
+
+通用工具并不总是比专门工具更好。高风险操作或受严格业务约束的操作——例如支付、数据删除、发送电子邮件和生产部署——仍应作为具有明确参数、受限权限和端到端可审计性的专用工具暴露，必要时添加预览和人类确认。因此，工具设计的核心原则是：**使用通用基础能力进行组合和探索；使用专门工具约束高风险操作并强制执行严格业务规则**。
+
+### 大语言模型：代理的推理引擎
+
+大语言模型（LLM）是代理的决策核心。给定用户请求，它首先必须推断真实意图（用户所说的往往不是他们真正想要的），然后将模糊或复杂的任务分解为可执行步骤。在整个执行过程中，它不断做出决策：下一步做什么、是否调用工具、调用哪个工具以及使用什么参数。这种理解–规划–执行能力来自预训练期间积累的知识，是工作流和自主代理都依赖的基础。
+
+大语言模型代理的一个显著能力是**内部推理**——在行动前，代理可以规划和推理任务。这不会改变外部环境，但会显著改善后续行动。这种能力来自预训练（在大量互联网文本上的初始训练，通过该训练模型学习语言模式和世界知识）：模型利用人类知识中编码的推理模式，包括数学定律、因果关系和分解问题的策略。因此，代理的推理不是盲目试错；它建立在结构化知识体系之上。

chapter10/book-translation/validation/real_20260730T053000Z_v3/single_agent_parts/getting_started_with_ai_agents_part_3_9_zh.md

@@ -0,0 +1,36 @@
+# 人工智能代理入门 [第3部分/共9部分]
+
+这种结构化推理让大语言模型代理能够处理完全新的任务，而无需先前示例——零样本和少样本这两个概念说明了这一点。直接体现是**零样本泛化**：面对从未见过的任务，代理通过重组已有的知识来处理，无需示例。模型可能从未被明确教过写关于量子物理的诗歌，但它可以根据已有的语言和物理知识生成合理的诗歌。
+
+有了几个示例，大语言模型代理还可以进行**少样本适配**：提示中两三个演示就足以让它学习新的任务模式。如果展示几个“用户评论->情感标签”的示例，它就能对新评论进行情感分类。简而言之：零样本意味着不用示例解决任务；少样本意味着从少量示例中学习模式。
+
+### 模型即代理：当模型本身成为产品
+“模型即代理”范式是人工智能代理开发的最新方向。先进模型通过后训练（尤其是强化学习）将工具调用内化为原生能力：何时调用工具、调用哪个工具、使用什么参数——模型自行决定，无需手动编排。这并不意味着框架层不重要。相反：模型越强，周围的框架就越重要。在代理语境中，框架是将模型能力转化为可靠任务执行的工程基础设施。它包括上下文管理、工具接口、安全约束以及验证和纠正机制（见本章最后一节）。
+
+模型拥有的决策权限越大，错误决策的影响就越大——这需要更精细的约束、验证和纠正来保持其可靠性。模型提供商的真正优势不是“让框架更薄”，而是能够共同优化模型及其周围的框架，持续迭代。
+
+但随之而来的是一个更深层次的问题：如果模型不断变强，今天的框架最终会被模型吸收吗？在《苦涩的教训》中，里奇·萨顿回顾了人工智能研究七十年中反复出现的模式[^ch1-1]：研究者反复将对领域的理解编码到系统中，实现短期收益，但最终输给了随计算和数据扩展的通用方法——搜索和学习。从这个角度看，框架中的多少约束、验证和纠正属于“人类先验”，是模型注定要内化的？本书的立场可以用八个汉字总结：**认可方向，务实节奏**。从方向上看，我们不怀疑模型会继续吸收框架的部分内容——工具调用和长视距规划曾经依赖外部编排，现在已成为原生模型能力。但实际上，这种吸收比直觉慢得多：训练需要数月时间尺度，没有模型能一次性内化所有真实业务的约束和偏好。模型当前的能力边界正是框架创造价值的地方。因此，框架工程不是对抗《苦涩的教训》，而是在工程时间尺度上践行它：模型尚不能可靠完成的，框架先覆盖；每当模型内化另一层，框架就舍弃该层，转向支持下一个能力前沿。这条主线贯穿全书——第2章从上下文工程角度提供务实答案，第8章进一步讨论代理如何从操作经验中选择和验证下一次系统更新，后记回到模型是否会吸收框架的完整答案。
+
+[^ch1-1]: Sutton, Rich. “The Bitter Lesson”, 2019. http://www.incompleteideas.net/IncIdeas/BitterLesson.html
+
+### 代理学习机制：从上下文适配到持续更新
+前面的讨论指出，模型可以通过强化学习将工具使用策略内化为原生能力。但代理行为的变化不仅发生在训练期间。根据更新发生的位置和持续时间，这些变化可以理解为三个互补路径（图1-1）：任务内上下文适配、跨任务外部工件更新、训练周期内的参数更新。
+
+![Figure 1-1: Three Levels of Agent Capability Updates](images/fig1-1.svg)
+
+**上下文适配**发生在当前任务内。一旦示例、状态和检索结果进入上下文，模型就能立即调整行为，但这不会改变下一会话的持久状态。其优势是速度快、成本低；局限性源于上下文窗口和信息组织方式。第2章将详细解释这种适配形式的工作原理。
+
+要让变化在任务间持续，系统可以更新**外部工件**：事实和经验可以组织成知识文档，可用语言表达的策略可以写入提示或技能，确定性程序和约束可以编码到程序和框架中。这些工件可审计且可修订，但代理仍必须在执行时通过上下文或工具接口访问它们。第3章到第5章建立知识和程序的基础，第8章讨论如何从评估的操作轨迹中生成此类更新。
+
+当目标是高维能力——如医学图像理解、自然语言风格或隐式决策策略——外部规则无法完全表达时，必须通过后训练更新**模型参数**。参数更新部署成本更高，但能产生自然且广泛的泛化；第7章系统介绍其方法。因此，这三个路径不是互斥的类别，而是在不同时间尺度上运作的协调机制：上下文支持即时适配，外部工件支持受控积累，参数内化难以明确表达的能力。
+
+### 上下文：代理的工作信息集
+上下文是代理在每个决策点可用的工作信息集。就像人做决策时需要桌上有正确的材料——任务说明、参考手册、之前的通信、最新数据——代理的上下文窗口是它可以使用的信息。从API角度（第2章详细介绍），每次大语言模型调用的上下文包括五部分：
+
+- **系统提示**：不同于对话中用户输入的提示，系统提示由开发者编写，在整个对话中保持固定。它是代理的“工作描述”——定义其身份、权限和行为规则。精心设计系统提示的提示工程是塑造代理操作行为的方式。系统提示还包含跨会话持久的**用户记忆**（偏好、过去行为、背景设置等个性化信息；见第3章），以及动态注入的环境状态。
+- **工具定义**：声明代理可用工具的名称、功能描述和参数格式。没有工具定义，代理无法识别或调用任何工具——消融研究（实验1-1）将验证这一点。工具定义与系统提示一起构成整个对话中保持不变的**静态前缀**。（这是基础模式；自2026年起，生产框架还可以在上下文末尾按需加载完整工具架构而不破坏前缀——见第2章和第4章的工具定义部分。）
+- **用户消息**：用户的输入。用户消息还可能包含通过RAG（检索增强生成，详情见第3章）动态检索的**外部知识**——涵盖训练数据截止日期之外的信息或私有领域知识。
+- **助手消息**：模型之前生成的响应，可包含最多三部分——`推理`（内部思维链，保持连贯性和决策可解释性）、`内容`（对用户的响应）和`工具调用`（代理采取行动的方式）。在特定响应中，这三部分可能不会同时出现：例如，当代理决定调用工具时，通常只有`推理`+`工具调用`；当给出最终答案时，通常只有`推理`+`内容`。
+- **工具结果**：代理框架执行工具后返回的输出。这些结果是代理下一步推理步骤的直接依据——也是它从结果中学习而非重复错误的依据。
+
+前两项（系统提示+工具定义）构成静态前缀；后三项（用户消息+助手消息+工具结果）构成随每次交互增长的动态消息历史。这五部分共同构成每次大语言模型推理的上下文。