<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" ><generator uri="https://jekyllrb.com/" version="3.10.0">Jekyll</generator><link href="/feed.xml" rel="self" type="application/atom+xml" /><link href="/" rel="alternate" type="text/html" /><updated>2025-06-30T03:23:14+00:00</updated><id>/feed.xml</id><title type="html">HHH Blog</title><subtitle>Personal thoughts and ai exploration</subtitle><entry><title type="html">Gemini Cli</title><link href="/2025/06/30/gemini-cli/" rel="alternate" type="text/html" title="Gemini Cli" /><published>2025-06-30T00:00:00+00:00</published><updated>2025-06-30T00:00:00+00:00</updated><id>/2025/06/30/gemini-cli</id><content type="html" xml:base="/2025/06/30/gemini-cli/"><![CDATA[<h1 id="gemini-cli-架构深度分析">Gemini CLI 架构深度分析</h1>

<h2 id="目录-table-of-contents">目录 (Table of Contents)</h2>

<ol>
  <li><a href="#架构概览-architecture-overview">架构概览 (Architecture Overview)</a></li>
  <li><a href="#工作流程-workflow">工作流程 (Workflow)</a></li>
  <li><a href="#核心模块深度分析-core-module-analysis">核心模块深度分析 (Core Module Analysis)</a>
    <ul>
      <li>3.1 <a href="#31-core-包整体架构">Core 包整体架构</a></li>
      <li>3.2 <a href="#32-聊天会话管理-geminichat">聊天会话管理 (GeminiChat)</a></li>
      <li>3.3 <a href="#33-内容生成器-contentgenerator">内容生成器 (ContentGenerator)</a></li>
      <li>3.4 <a href="#34-对话轮次管理-turn">对话轮次管理 (Turn)</a></li>
      <li>3.5 <a href="#35-系统提示词管理-prompts">系统提示词管理 (Prompts)</a></li>
    </ul>
  </li>
  <li><a href="#工具执行系统-tool-execution-system">工具执行系统 (Tool Execution System)</a>
    <ul>
      <li>4.1 <a href="#41-工具调度器架构">工具调度器架构</a></li>
      <li>4.2 <a href="#42-工具执行生命周期">工具执行生命周期</a></li>
      <li>4.3 <a href="#43-并发执行机制">并发执行机制</a></li>
      <li>4.4 <a href="#44-turn-间的同步机制">Turn 间的同步机制</a></li>
    </ul>
  </li>
  <li><a href="#历史记录管理-history-management">历史记录管理 (History Management)</a>
    <ul>
      <li>5.1 <a href="#51-双历史机制设计">双历史机制设计</a></li>
      <li>5.2 <a href="#52-智能历史过滤">智能历史过滤</a></li>
      <li>5.3 <a href="#53-上下文渲染机制">上下文渲染机制</a></li>
    </ul>
  </li>
  <li><a href="#工具系统详解-tool-system">工具系统详解 (Tool System)</a>
    <ul>
      <li>6.1 <a href="#61-工具框架架构">工具框架架构</a></li>
      <li>6.2 <a href="#62-工具分类和功能">工具分类和功能</a></li>
      <li>6.3 <a href="#63-安全机制">安全机制</a></li>
    </ul>
  </li>
  <li><a href="#总结与思考-summary--insights">总结与思考 (Summary &amp; Insights)</a></li>
</ol>

<hr />

<h2 id="架构概览-architecture-overview">架构概览 (Architecture Overview)</h2>

<h3 id="整体架构设计">整体架构设计</h3>

<p>Gemini CLI 采用了模块化的分层架构，清晰地分离了用户界面、业务逻辑和 API 交互层：</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>┌─────────────────────────────────────────────────────┐
│                CLI Package                          │
│          (用户交互 &amp; 流程控制)                        │
├─────────────────────────────────────────────────────┤
│                Core Package                         │
│           (业务逻辑 &amp; API 管理)                      │
├─────────────────────────────────────────────────────┤
│                 Tool System                         │
│          (扩展能力 &amp; 外部集成)                        │
└─────────────────────────────────────────────────────┘
</code></pre></div></div>

<h3 id="核心架构组件">核心架构组件</h3>

<ol>
  <li><strong>CLI 包 (<code class="language-plaintext highlighter-rouge">packages/cli/</code>)</strong> - 前端层
    <ul>
      <li>处理用户交互界面</li>
      <li>主题系统 (多种主题如 dracula、github、ayu 等)</li>
      <li>React 组件系统 (App.tsx、各种显示组件)</li>
      <li>命令处理器 (slash commands、shell commands、at commands)</li>
      <li>历史管理和输入处理</li>
    </ul>
  </li>
  <li><strong>Core 包 (<code class="language-plaintext highlighter-rouge">packages/core/</code>)</strong> - 后端层
    <ul>
      <li>Gemini API 客户端</li>
      <li>工具注册和执行系统</li>
      <li>提示词管理</li>
      <li>会话状态管理</li>
      <li>遥测和日志系统</li>
    </ul>
  </li>
  <li><strong>工具系统 (<code class="language-plaintext highlighter-rouge">packages/core/src/tools/</code>)</strong> - 扩展能力
    <ul>
      <li>文件系统操作 (read、write、edit、glob、grep)</li>
      <li>Shell 命令执行</li>
      <li>Web 操作 (fetch、search)</li>
      <li>MCP (Model Context Protocol) 客户端</li>
      <li>内存管理工具</li>
    </ul>
  </li>
</ol>

<h3 id="技术栈">技术栈</h3>

<ul>
  <li><strong>语言</strong>: TypeScript</li>
  <li><strong>UI框架</strong>: React (用于终端 UI)</li>
  <li><strong>运行时</strong>: Node.js (&gt;=18.0.0)</li>
  <li><strong>构建工具</strong>: ESBuild</li>
  <li><strong>测试</strong>: Vitest</li>
  <li><strong>包管理</strong>: npm workspaces</li>
</ul>

<h3 id="关键设计特点">关键设计特点</h3>

<ol>
  <li><strong>前后端分离</strong>: CLI 和 Core 独立开发，便于扩展</li>
  <li><strong>工具插件化</strong>: 可扩展的工具系统</li>
  <li><strong>安全沙箱</strong>: 支持 Docker/Podman 沙箱环境</li>
  <li><strong>多认证方式</strong>: OAuth2、API Key、Google Workspace</li>
  <li><strong>实时流式响应</strong>: 支持流式 API 响应显示</li>
</ol>

<hr />

<h2 id="工作流程-workflow">工作流程 (Workflow)</h2>

<h3 id="用户交互流程">用户交互流程</h3>

<p><img src="/assets/images/gemini-cli-user-workflow.png" alt="" /></p>

<h3 id="详细工作流程示例">详细工作流程示例</h3>

<p>让我们通过一个具体例子来理解工作流程：</p>

<p><strong>用户输入</strong>: “帮我找到项目中所有的 TODO 注释并修复第一个”</p>

<p><img src="/assets/images/gemini-cli-todo-sequence.png" alt="" /></p>

<h3 id="系统内部处理流程">系统内部处理流程</h3>

<p>典型的对话交互遵循以下流程：</p>

<ol>
  <li><strong>用户输入</strong>: 用户在终端输入提示或命令，由 <code class="language-plaintext highlighter-rouge">packages/cli</code> 管理</li>
  <li><strong>请求预处理</strong>: CLI 包将用户输入发送到 Core 包</li>
  <li><strong>请求处理</strong>: Core 包构建适当的提示，包含对话历史和可用工具定义，发送到 Gemini API</li>
  <li><strong>Gemini API 响应</strong>: API 处理提示并返回响应，可能是直接答案或工具调用请求</li>
  <li><strong>工具执行</strong>:
    <ul>
      <li>当 Gemini 请求工具时，Core 包准备执行</li>
      <li>对于可能修改文件系统或执行 shell 命令的工具，首先显示详情并要求用户批准</li>
      <li>只读操作可能不需要明确确认</li>
      <li>确认后，Core 包执行相关工具，结果返回给 Gemini API</li>
    </ul>
  </li>
  <li><strong>响应返回</strong>: Core 包将最终响应发送回 CLI 包</li>
  <li><strong>结果显示</strong>: CLI 包在终端中格式化并显示响应</li>
</ol>

<hr />

<h2 id="核心模块深度分析-core-module-analysis">核心模块深度分析 (Core Module Analysis)</h2>

<h3 id="31-core-包整体架构">3.1 Core 包整体架构</h3>

<p>Core 包采用分层架构设计，主要包含以下核心模块：</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>core/
├── core/           # 核心逻辑层
├── tools/          # 工具层
├── services/       # 服务层
├── utils/          # 工具类
├── config/         # 配置管理
└── telemetry/      # 遥测系统
</code></pre></div></div>

<p><strong>核心导出结构</strong>:</p>
<ul>
  <li><strong>核心逻辑</strong>: client.js, geminiChat.js, contentGenerator.js, turn.js, prompts.js</li>
  <li><strong>工具系统</strong>: tools.js, tool-registry.js 及各种具体工具实现</li>
  <li><strong>服务层</strong>: fileDiscoveryService.js, gitService.js</li>
  <li><strong>工具类</strong>: 错误处理、重试机制、路径处理等</li>
</ul>

<h3 id="32-聊天会话管理-geminichat">3.2 聊天会话管理 (GeminiChat)</h3>

<h4 id="核心职责">核心职责</h4>
<ul>
  <li>管理与 Gemini API 的会话状态</li>
  <li>维护两种历史记录：精选历史（用于 API）和完整历史（包含无效响应）</li>
  <li>处理流式和非流式响应</li>
  <li>实现智能重试机制（429/5xx 错误）</li>
</ul>

<h4 id="关键特性">关键特性</h4>

<p><strong>双历史记录机制</strong>:</p>
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nx">GeminiChat</span> <span class="p">{</span>
  <span class="k">private</span> <span class="nx">history</span><span class="p">:</span> <span class="nx">Content</span><span class="p">[]</span> <span class="o">=</span> <span class="p">[];</span>  <span class="c1">// 完整历史（comprehensive history）</span>
  
  <span class="c1">// 获取历史记录</span>
  <span class="nx">getHistory</span><span class="p">(</span><span class="nx">curated</span><span class="p">:</span> <span class="nx">boolean</span> <span class="o">=</span> <span class="kc">false</span><span class="p">):</span> <span class="nx">Content</span><span class="p">[]</span> <span class="p">{</span>
    <span class="kd">const</span> <span class="nx">history</span> <span class="o">=</span> <span class="nx">curated</span>
      <span class="p">?</span> <span class="nx">extractCuratedHistory</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">history</span><span class="p">)</span>  <span class="c1">// 精选历史</span>
      <span class="p">:</span> <span class="k">this</span><span class="p">.</span><span class="nx">history</span><span class="p">;</span>                         <span class="c1">// 完整历史</span>
    <span class="k">return</span> <span class="nx">structuredClone</span><span class="p">(</span><span class="nx">history</span><span class="p">);</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p><strong>设计亮点</strong>:</p>
<ul>
  <li>智能历史管理：自动过滤无效/空响应</li>
  <li>思考内容分离：将模型的 “thought” 内容单独处理</li>
  <li>相邻响应合并：避免消息碎片化</li>
  <li>Flash 模型降级机制：OAuth 用户速率限制时自动降级</li>
</ul>

<h4 id="发送消息流程">发送消息流程</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">async</span> <span class="nx">sendMessage</span><span class="p">(</span><span class="nx">params</span><span class="p">:</span> <span class="nx">SendMessageParameters</span><span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">GenerateContentResponse</span><span class="o">&gt;</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">userContent</span> <span class="o">=</span> <span class="nx">createUserContent</span><span class="p">(</span><span class="nx">params</span><span class="p">.</span><span class="nx">message</span><span class="p">);</span>
  <span class="c1">// 关键：获取精选历史并添加当前用户输入</span>
  <span class="kd">const</span> <span class="nx">requestContents</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">getHistory</span><span class="p">(</span><span class="kc">true</span><span class="p">).</span><span class="nx">concat</span><span class="p">(</span><span class="nx">userContent</span><span class="p">);</span>
  
  <span class="c1">// 发送给 API，包含完整对话历史</span>
  <span class="kd">const</span> <span class="nx">response</span> <span class="o">=</span> <span class="k">await</span> <span class="k">this</span><span class="p">.</span><span class="nx">contentGenerator</span><span class="p">.</span><span class="nx">generateContent</span><span class="p">({</span>
    <span class="na">model</span><span class="p">:</span> <span class="k">this</span><span class="p">.</span><span class="nx">config</span><span class="p">.</span><span class="nx">getModel</span><span class="p">(),</span>
    <span class="na">contents</span><span class="p">:</span> <span class="nx">requestContents</span><span class="p">,</span>
    <span class="na">config</span><span class="p">:</span> <span class="p">{</span> <span class="p">...</span><span class="k">this</span><span class="p">.</span><span class="nx">generationConfig</span><span class="p">,</span> <span class="p">...</span><span class="nx">params</span><span class="p">.</span><span class="nx">config</span> <span class="p">},</span>
  <span class="p">});</span>
<span class="p">}</span>
</code></pre></div></div>

<h3 id="33-内容生成器-contentgenerator">3.3 内容生成器 (ContentGenerator)</h3>

<h4 id="核心职责-1">核心职责</h4>
<ul>
  <li>提供统一的内容生成接口</li>
  <li>支持三种认证方式：OAuth、API Key、Vertex AI</li>
  <li>根据认证类型动态选择模型</li>
</ul>

<h4 id="架构设计">架构设计</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kr">interface</span> <span class="nx">ContentGenerator</span> <span class="p">{</span>
  <span class="nx">generateContent</span><span class="p">(</span><span class="nx">request</span><span class="p">:</span> <span class="nx">GenerateContentRequest</span><span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">GenerateContentResponse</span><span class="o">&gt;</span><span class="p">;</span>
  <span class="nx">generateContentStream</span><span class="p">(</span><span class="nx">request</span><span class="p">:</span> <span class="nx">GenerateContentRequest</span><span class="p">):</span> <span class="nx">AsyncGenerator</span><span class="o">&lt;</span><span class="p">...</span><span class="o">&gt;</span><span class="p">;</span>
  <span class="nx">embedContent</span><span class="p">(</span><span class="nx">params</span><span class="p">:</span> <span class="nx">EmbedContentParameters</span><span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="p">...</span><span class="o">&gt;</span><span class="p">;</span>
<span class="p">}</span>

<span class="c1">// 工厂方法</span>
<span class="k">async</span> <span class="kd">function</span> <span class="nx">createContentGenerator</span><span class="p">(</span><span class="nx">config</span><span class="p">:</span> <span class="nx">ContentGeneratorConfig</span><span class="p">)</span> <span class="p">{</span>
  <span class="c1">// 根据认证类型创建不同的生成器</span>
<span class="p">}</span>
</code></pre></div></div>

<p><strong>特色功能</strong>:</p>
<ul>
  <li>动态模型选择基于认证方法</li>
  <li>自定义 User-Agent 标头用于跟踪</li>
  <li>支持环境变量配置不同认证方法</li>
</ul>

<h3 id="34-对话轮次管理-turn">3.4 对话轮次管理 (Turn)</h3>

<h4 id="核心职责-2">核心职责</h4>
<ul>
  <li>管理单个对话轮次的完整流程</li>
  <li>流式处理模型响应</li>
  <li>提取不同类型的事件</li>
</ul>

<h4 id="事件类型系统">事件类型系统</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">type</span> <span class="nx">ServerGeminiStreamEvent</span> <span class="o">=</span> 
  <span class="o">|</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">'</span><span class="s1">content</span><span class="dl">'</span><span class="p">,</span> <span class="na">content</span><span class="p">:</span> <span class="kr">string</span> <span class="p">}</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">'</span><span class="s1">thought</span><span class="dl">'</span><span class="p">,</span> <span class="na">thought</span><span class="p">:</span> <span class="p">{</span> <span class="na">subject</span><span class="p">:</span> <span class="kr">string</span><span class="p">,</span> <span class="na">description</span><span class="p">:</span> <span class="kr">string</span> <span class="p">}</span> <span class="p">}</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">'</span><span class="s1">tool_call</span><span class="dl">'</span><span class="p">,</span> <span class="na">toolCall</span><span class="p">:</span> <span class="nx">ToolCallRequestInfo</span> <span class="p">}</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">'</span><span class="s1">usage</span><span class="dl">'</span><span class="p">,</span> <span class="na">usage</span><span class="p">:</span> <span class="nx">UsageMetadata</span> <span class="p">}</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">'</span><span class="s1">error</span><span class="dl">'</span><span class="p">,</span> <span class="na">error</span><span class="p">:</span> <span class="nb">Error</span> <span class="p">}</span>
  <span class="o">|</span> <span class="p">{</span> <span class="na">type</span><span class="p">:</span> <span class="dl">'</span><span class="s1">done</span><span class="dl">'</span> <span class="p">}</span>
</code></pre></div></div>

<h4 id="流处理机制">流处理机制</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nx">Turn</span> <span class="p">{</span>
  <span class="k">async</span> <span class="o">*</span><span class="nx">run</span><span class="p">():</span> <span class="nx">AsyncGenerator</span><span class="o">&lt;</span><span class="nx">ServerGeminiStreamEvent</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="c1">// 1. 发送消息到 Gemini</span>
    <span class="c1">// 2. 流式接收响应</span>
    <span class="c1">// 3. 解析不同类型的内容</span>
    <span class="c1">// 4. 处理函数调用</span>
    <span class="c1">// 5. 生成相应事件</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p><strong>核心特性</strong>:</p>
<ul>
  <li>思考内容解析（subject/description）</li>
  <li>函数调用转换为工具请求</li>
  <li>使用元数据跟踪和错误处理</li>
  <li>支持用户取消操作</li>
</ul>

<h3 id="35-系统提示词管理-prompts">3.5 系统提示词管理 (Prompts)</h3>

<h4 id="核心职责-3">核心职责</h4>
<ul>
  <li>生成定义 AI 助手行为的系统提示词</li>
  <li>支持环境变量和外部文件覆盖</li>
  <li>根据运行环境动态调整</li>
</ul>

<h4 id="提示词结构">提示词结构</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">function</span> <span class="nx">getCoreSystemPrompt</span><span class="p">(</span><span class="nx">config</span><span class="p">:</span> <span class="nx">Config</span><span class="p">):</span> <span class="kr">string</span> <span class="p">{</span>
  <span class="k">return</span> <span class="s2">`
    # 核心指令
    - 遵循代码约定
    - 保持简洁风格
    - 主动但不过度
    
    # 主要工作流
    - 软件工程任务
    - 新应用创建
    
    # 可用工具
    </span><span class="p">${</span><span class="nx">工具列表</span><span class="p">}</span><span class="s2">
    
    # 环境信息
    </span><span class="p">${</span><span class="nx">沙箱</span><span class="o">/</span><span class="nx">Git</span><span class="o">/</span><span class="nx">内存信息</span><span class="p">}</span><span class="s2">
  `</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<p><strong>动态适配特性</strong>:</p>
<ul>
  <li>检测沙箱环境（macOS Seatbelt 或容器）</li>
  <li>检测 Git 仓库状态</li>
  <li>集成用户偏好和记忆</li>
  <li>支持外部提示文件覆盖</li>
</ul>

<hr />

<h2 id="工具执行系统-tool-execution-system">工具执行系统 (Tool Execution System)</h2>

<h3 id="41-工具调度器架构">4.1 工具调度器架构</h3>

<p>CoreToolScheduler 负责管理工具执行的完整生命周期，采用状态机设计模式：</p>

<h4 id="状态机设计">状态机设计</h4>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>validating → awaiting_approval → scheduled → executing → success/error/cancelled
                    ↓
                rejected → cancelled
</code></pre></div></div>

<h4 id="核心类型定义">核心类型定义</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">type</span> <span class="nx">ToolCall</span> <span class="o">=</span>
  <span class="o">|</span> <span class="nx">ValidatingToolCall</span>      <span class="c1">// 验证参数中</span>
  <span class="o">|</span> <span class="nx">ScheduledToolCall</span>       <span class="c1">// 已调度</span>
  <span class="o">|</span> <span class="nx">ErroredToolCall</span>         <span class="c1">// 执行错误</span>
  <span class="o">|</span> <span class="nx">SuccessfulToolCall</span>      <span class="c1">// 执行成功</span>
  <span class="o">|</span> <span class="nx">ExecutingToolCall</span>       <span class="c1">// 执行中</span>
  <span class="o">|</span> <span class="nx">CancelledToolCall</span>       <span class="c1">// 已取消</span>
  <span class="o">|</span> <span class="nx">WaitingToolCall</span><span class="p">;</span>        <span class="c1">// 等待确认</span>
</code></pre></div></div>

<h3 id="42-工具执行生命周期">4.2 工具执行生命周期</h3>

<h4 id="完整执行流程">完整执行流程</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nx">CoreToolScheduler</span> <span class="p">{</span>
  <span class="k">async</span> <span class="nx">schedule</span><span class="p">(</span><span class="nx">toolCalls</span><span class="p">:</span> <span class="nx">ToolCallRequestInfo</span><span class="p">[])</span> <span class="p">{</span>
    <span class="c1">// 1. 验证参数</span>
    <span class="k">for</span> <span class="p">(</span><span class="kd">const</span> <span class="nx">toolCall</span> <span class="k">of</span> <span class="nx">newToolCalls</span><span class="p">)</span> <span class="p">{</span>
      <span class="kd">const</span> <span class="nx">confirmationDetails</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">toolInstance</span><span class="p">.</span><span class="nx">shouldConfirmExecute</span><span class="p">(</span>
        <span class="nx">reqInfo</span><span class="p">.</span><span class="nx">args</span><span class="p">,</span>
        <span class="nx">signal</span><span class="p">,</span>
      <span class="p">);</span>
      
      <span class="c1">// 2. 检查是否需要确认</span>
      <span class="k">if</span> <span class="p">(</span><span class="nx">confirmationDetails</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">this</span><span class="p">.</span><span class="nx">setStatusInternal</span><span class="p">(</span><span class="nx">reqInfo</span><span class="p">.</span><span class="nx">callId</span><span class="p">,</span> <span class="dl">'</span><span class="s1">awaiting_approval</span><span class="dl">'</span><span class="p">,</span> <span class="nx">confirmationDetails</span><span class="p">);</span>
      <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
        <span class="k">this</span><span class="p">.</span><span class="nx">setStatusInternal</span><span class="p">(</span><span class="nx">reqInfo</span><span class="p">.</span><span class="nx">callId</span><span class="p">,</span> <span class="dl">'</span><span class="s1">scheduled</span><span class="dl">'</span><span class="p">);</span>
      <span class="p">}</span>
    <span class="p">}</span>
    
    <span class="c1">// 3. 尝试执行已调度的工具</span>
    <span class="k">this</span><span class="p">.</span><span class="nx">attemptExecutionOfScheduledCalls</span><span class="p">(</span><span class="nx">signal</span><span class="p">);</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<h4 id="确认和修改机制">确认和修改机制</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">async</span> <span class="nx">handleConfirmationResponse</span><span class="p">(</span>
  <span class="nx">callId</span><span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
  <span class="nx">outcome</span><span class="p">:</span> <span class="nx">ToolConfirmationOutcome</span><span class="p">,</span>
  <span class="nx">signal</span><span class="p">:</span> <span class="nx">AbortSignal</span><span class="p">,</span>
<span class="p">)</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">outcome</span> <span class="o">===</span> <span class="nx">ToolConfirmationOutcome</span><span class="p">.</span><span class="nx">ModifyWithEditor</span><span class="p">)</span> <span class="p">{</span>
    <span class="c1">// 支持用户修改工具参数</span>
    <span class="kd">const</span> <span class="p">{</span> <span class="nx">updatedParams</span><span class="p">,</span> <span class="nx">updatedDiff</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">modifyWithEditor</span><span class="p">(</span>
      <span class="nx">waitingToolCall</span><span class="p">.</span><span class="nx">request</span><span class="p">.</span><span class="nx">args</span><span class="p">,</span>
      <span class="nx">modifyContext</span><span class="p">,</span>
      <span class="nx">editorType</span><span class="p">,</span>
      <span class="nx">signal</span><span class="p">,</span>
    <span class="p">);</span>
    <span class="k">this</span><span class="p">.</span><span class="nx">setArgsInternal</span><span class="p">(</span><span class="nx">callId</span><span class="p">,</span> <span class="nx">updatedParams</span><span class="p">);</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<h3 id="43-并发执行机制">4.3 并发执行机制</h3>

<h4 id="真正的并发执行">真正的并发执行</h4>

<p>CoreToolScheduler 实现了真正的并发执行，而不仅仅是异步：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">private</span> <span class="nx">attemptExecutionOfScheduledCalls</span><span class="p">(</span><span class="nx">signal</span><span class="p">:</span> <span class="nx">AbortSignal</span><span class="p">):</span> <span class="k">void</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">callsToExecute</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">toolCalls</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span>
    <span class="p">(</span><span class="nx">call</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">call</span><span class="p">.</span><span class="nx">status</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">scheduled</span><span class="dl">'</span><span class="p">,</span>
  <span class="p">);</span>

  <span class="c1">// 使用 forEach 同时启动所有工具执行</span>
  <span class="nx">callsToExecute</span><span class="p">.</span><span class="nx">forEach</span><span class="p">((</span><span class="nx">toolCall</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="c1">// 每个工具的 execute 返回 Promise，但不等待</span>
    <span class="nx">scheduledCall</span><span class="p">.</span><span class="nx">tool</span>
      <span class="p">.</span><span class="nx">execute</span><span class="p">(</span><span class="nx">scheduledCall</span><span class="p">.</span><span class="nx">request</span><span class="p">.</span><span class="nx">args</span><span class="p">,</span> <span class="nx">signal</span><span class="p">,</span> <span class="nx">liveOutputCallback</span><span class="p">)</span>
      <span class="p">.</span><span class="nx">then</span><span class="p">((</span><span class="na">toolResult</span><span class="p">:</span> <span class="nx">ToolResult</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
        <span class="c1">// 处理成功结果</span>
      <span class="p">})</span>
      <span class="p">.</span><span class="k">catch</span><span class="p">((</span><span class="na">executionError</span><span class="p">:</span> <span class="nb">Error</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
        <span class="c1">// 处理错误</span>
      <span class="p">});</span>
  <span class="p">});</span>
<span class="p">}</span>
</code></pre></div></div>

<h4 id="并发执行示例">并发执行示例</h4>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>时间线 →
T0: schedule([tool1, tool2, tool3])
    ↓
T1: 验证所有工具参数
    ↓
T2: 检查确认需求（可能并行）
    ↓
T3: attemptExecutionOfScheduledCalls()
    ├─→ tool1.execute() ─────→ [执行中...] ──→ 完成
    ├─→ tool2.execute() ──→ [执行中......] ────→ 完成
    └─→ tool3.execute() ───→ [执行中.] ──────→ 完成
                          ↑
                     所有工具并发执行
</code></pre></div></div>

<h4 id="并发控制特性">并发控制特性</h4>

<ol>
  <li><strong>防止重复调度</strong>: 如果有工具正在运行，不允许新的调度</li>
  <li><strong>实时状态更新</strong>: 每个工具可独立提供实时输出</li>
  <li><strong>错误隔离</strong>: 一个工具失败不影响其他工具执行</li>
  <li><strong>批量完成通知</strong>: 等待所有工具完成后统一处理结果</li>
</ol>

<h3 id="44-turn-间的同步机制">4.4 Turn 间的同步机制</h3>

<h4 id="cli-层控制的流程">CLI 层控制的流程</h4>

<p><strong>Turn 的启动和续接完全由 CLI 层控制</strong>，Core 层提供无状态的服务：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// CLI 层主动监听工具完成状态</span>
<span class="nx">useEffect</span><span class="p">(()</span> <span class="o">=&gt;</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">completedAndReadyToSubmitTools</span> <span class="o">=</span> <span class="nx">toolCalls</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span>
    <span class="p">(</span><span class="nx">toolCall</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
      <span class="kd">const</span> <span class="nx">isTerminal</span> <span class="o">=</span> 
        <span class="nx">toolCall</span><span class="p">.</span><span class="nx">status</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">success</span><span class="dl">'</span> <span class="o">||</span>
        <span class="nx">toolCall</span><span class="p">.</span><span class="nx">status</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">error</span><span class="dl">'</span> <span class="o">||</span>
        <span class="nx">toolCall</span><span class="p">.</span><span class="nx">status</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">cancelled</span><span class="dl">'</span><span class="p">;</span>
      <span class="k">return</span> <span class="nx">isTerminal</span> <span class="o">&amp;&amp;</span> <span class="o">!</span><span class="nx">toolCall</span><span class="p">.</span><span class="nx">responseSubmittedToGemini</span><span class="p">;</span>
    <span class="p">}</span>
  <span class="p">);</span>

  <span class="c1">// CLI 层决定何时启动下一个 Turn</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">geminiTools</span><span class="p">.</span><span class="nx">length</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
    <span class="c1">// CLI 主动调用 submitQuery 启动 Turn 2</span>
    <span class="nx">submitQuery</span><span class="p">(</span><span class="nx">mergePartListUnions</span><span class="p">(</span><span class="nx">responsesToSend</span><span class="p">),</span> <span class="p">{</span>
      <span class="na">isContinuation</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>  <span class="c1">// 标记为续接</span>
    <span class="p">});</span>
  <span class="p">}</span>
<span class="p">},</span> <span class="p">[</span><span class="nx">toolCalls</span><span class="p">,</span> <span class="nx">isResponding</span><span class="p">,</span> <span class="nx">submitQuery</span><span class="p">]);</span>
</code></pre></div></div>

<h4 id="等待机制说明">等待机制说明</h4>

<p><strong>是的，在进入 Turn 2 之前，系统会等待 Turn 1 中的所有工具执行完成</strong>：</p>

<ol>
  <li><strong>Turn 1</strong>: 接收用户输入 → 发送给 Gemini → 返回工具调用请求</li>
  <li><strong>工具执行阶段</strong>: UI 层通过 <code class="language-plaintext highlighter-rouge">useEffect</code> 监听工具状态 → 所有工具完成后自动触发新查询</li>
  <li><strong>Turn 2</strong>: 自动发送工具响应给 Gemini → 基于工具结果继续对话</li>
</ol>

<h4 id="架构优势">架构优势</h4>

<ol>
  <li><strong>UI 响应性</strong>: CLI 可以实时更新界面，不受 Core 层阻塞</li>
  <li><strong>中断能力</strong>: 用户可以随时取消，CLI 层处理中断逻辑</li>
  <li><strong>扩展性</strong>: 不同的前端可以有不同的流程控制</li>
  <li><strong>测试性</strong>: Core 层无状态，易于单元测试</li>
</ol>

<hr />

<h2 id="历史记录管理-history-management">历史记录管理 (History Management)</h2>

<h3 id="51-双历史机制设计">5.1 双历史机制设计</h3>

<p>GeminiChat 维护两种类型的历史记录：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nx">GeminiChat</span> <span class="p">{</span>
  <span class="k">private</span> <span class="nx">history</span><span class="p">:</span> <span class="nx">Content</span><span class="p">[]</span> <span class="o">=</span> <span class="p">[];</span>  <span class="c1">// 完整历史（comprehensive history）</span>
  
  <span class="nx">getHistory</span><span class="p">(</span><span class="nx">curated</span><span class="p">:</span> <span class="nx">boolean</span> <span class="o">=</span> <span class="kc">false</span><span class="p">):</span> <span class="nx">Content</span><span class="p">[]</span> <span class="p">{</span>
    <span class="kd">const</span> <span class="nx">history</span> <span class="o">=</span> <span class="nx">curated</span>
      <span class="p">?</span> <span class="nx">extractCuratedHistory</span><span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">history</span><span class="p">)</span>  <span class="c1">// 精选历史</span>
      <span class="p">:</span> <span class="k">this</span><span class="p">.</span><span class="nx">history</span><span class="p">;</span>                         <span class="c1">// 完整历史</span>
    <span class="k">return</span> <span class="nx">structuredClone</span><span class="p">(</span><span class="nx">history</span><span class="p">);</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p><strong>两种历史的作用</strong>:</p>
<ul>
  <li><strong>完整历史</strong>: 包含所有对话，即使是无效或空响应，用于调试和审计</li>
  <li><strong>精选历史</strong>: 只包含有效对话，用于发送给 API，确保上下文质量</li>
</ul>

<h3 id="52-智能历史过滤">5.2 智能历史过滤</h3>

<h4 id="extractcuratedhistory-函数的核心逻辑">extractCuratedHistory 函数的核心逻辑</h4>

<p>这个函数实现了智能的历史记录过滤机制：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">function</span> <span class="nx">extractCuratedHistory</span><span class="p">(</span><span class="nx">comprehensiveHistory</span><span class="p">:</span> <span class="nx">Content</span><span class="p">[]):</span> <span class="nx">Content</span><span class="p">[]</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">curatedHistory</span><span class="p">:</span> <span class="nx">Content</span><span class="p">[]</span> <span class="o">=</span> <span class="p">[];</span>
  <span class="kd">let</span> <span class="nx">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>

  <span class="k">while</span> <span class="p">(</span><span class="nx">i</span> <span class="o">&lt;</span> <span class="nx">comprehensiveHistory</span><span class="p">.</span><span class="nx">length</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="nx">comprehensiveHistory</span><span class="p">[</span><span class="nx">i</span><span class="p">].</span><span class="nx">role</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">user</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span>
      <span class="c1">// 用户消息总是被保留</span>
      <span class="nx">curatedHistory</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span><span class="nx">comprehensiveHistory</span><span class="p">[</span><span class="nx">i</span><span class="p">]);</span>
      <span class="nx">i</span><span class="o">++</span><span class="p">;</span>
    <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
      <span class="c1">// 收集连续的模型响应</span>
      <span class="kd">const</span> <span class="na">modelOutput</span><span class="p">:</span> <span class="nx">Content</span><span class="p">[]</span> <span class="o">=</span> <span class="p">[];</span>
      <span class="kd">let</span> <span class="nx">isValid</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>

      <span class="k">while</span> <span class="p">(</span><span class="nx">i</span> <span class="o">&lt;</span> <span class="nx">length</span> <span class="o">&amp;&amp;</span> <span class="nx">comprehensiveHistory</span><span class="p">[</span><span class="nx">i</span><span class="p">].</span><span class="nx">role</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">model</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span>
        <span class="nx">modelOutput</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span><span class="nx">comprehensiveHistory</span><span class="p">[</span><span class="nx">i</span><span class="p">]);</span>
        <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">isValidContent</span><span class="p">(</span><span class="nx">comprehensiveHistory</span><span class="p">[</span><span class="nx">i</span><span class="p">]))</span> <span class="p">{</span>
          <span class="nx">isValid</span> <span class="o">=</span> <span class="kc">false</span><span class="p">;</span>
        <span class="p">}</span>
        <span class="nx">i</span><span class="o">++</span><span class="p">;</span>
      <span class="p">}</span>

      <span class="k">if</span> <span class="p">(</span><span class="nx">isValid</span><span class="p">)</span> <span class="p">{</span>
        <span class="nx">curatedHistory</span><span class="p">.</span><span class="nx">push</span><span class="p">(...</span><span class="nx">modelOutput</span><span class="p">);</span>
      <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
        <span class="c1">// 如果模型响应无效，移除前面的用户输入</span>
        <span class="nx">curatedHistory</span><span class="p">.</span><span class="nx">pop</span><span class="p">();</span>
      <span class="p">}</span>
    <span class="p">}</span>
  <span class="p">}</span>
  <span class="k">return</span> <span class="nx">curatedHistory</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<h4 id="智能过滤的关键设计">智能过滤的关键设计</h4>

<p><strong>为什么要删除前面的用户输入？</strong></p>

<p>这个设计基于一个重要原则：<strong>对话必须是完整的用户-模型交互对</strong>。</p>

<p>考虑以下场景：</p>
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 原始历史</span>
<span class="p">[</span>
  <span class="p">{</span> <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">user</span><span class="dl">'</span><span class="p">,</span> <span class="na">parts</span><span class="p">:</span> <span class="p">[{</span> <span class="na">text</span><span class="p">:</span> <span class="dl">'</span><span class="s1">生成一张图片</span><span class="dl">'</span> <span class="p">}]</span> <span class="p">},</span>
  <span class="p">{</span> <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">model</span><span class="dl">'</span><span class="p">,</span> <span class="na">parts</span><span class="p">:</span> <span class="p">[]</span> <span class="p">},</span>  <span class="c1">// 空响应（可能因为安全过滤）</span>
  <span class="p">{</span> <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">user</span><span class="dl">'</span><span class="p">,</span> <span class="na">parts</span><span class="p">:</span> <span class="p">[{</span> <span class="na">text</span><span class="p">:</span> <span class="dl">'</span><span class="s1">写一首诗</span><span class="dl">'</span> <span class="p">}]</span> <span class="p">},</span>
  <span class="p">{</span> <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">model</span><span class="dl">'</span><span class="p">,</span> <span class="na">parts</span><span class="p">:</span> <span class="p">[{</span> <span class="na">text</span><span class="p">:</span> <span class="dl">'</span><span class="s1">春风又绿江南岸...</span><span class="dl">'</span> <span class="p">}]</span> <span class="p">}</span>
<span class="p">]</span>

<span class="c1">// 精选后的历史</span>
<span class="p">[</span>
  <span class="c1">// 第一组被完全删除（因为模型响应无效）</span>
  <span class="p">{</span> <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">user</span><span class="dl">'</span><span class="p">,</span> <span class="na">parts</span><span class="p">:</span> <span class="p">[{</span> <span class="na">text</span><span class="p">:</span> <span class="dl">'</span><span class="s1">写一首诗</span><span class="dl">'</span> <span class="p">}]</span> <span class="p">},</span>
  <span class="p">{</span> <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">model</span><span class="dl">'</span><span class="p">,</span> <span class="na">parts</span><span class="p">:</span> <span class="p">[{</span> <span class="na">text</span><span class="p">:</span> <span class="dl">'</span><span class="s1">春风又绿江南岸...</span><span class="dl">'</span> <span class="p">}]</span> <span class="p">}</span>
<span class="p">]</span>
</code></pre></div></div>

<h4 id="isvalidcontent-的判断标准">isValidContent 的判断标准</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">function</span> <span class="nx">isValidContent</span><span class="p">(</span><span class="nx">content</span><span class="p">:</span> <span class="nx">Content</span><span class="p">):</span> <span class="nx">boolean</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">content</span><span class="p">.</span><span class="nx">parts</span> <span class="o">===</span> <span class="kc">undefined</span> <span class="o">||</span> <span class="nx">content</span><span class="p">.</span><span class="nx">parts</span><span class="p">.</span><span class="nx">length</span> <span class="o">===</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>  <span class="c1">// 没有内容部分</span>
  <span class="p">}</span>
  <span class="k">for</span> <span class="p">(</span><span class="kd">const</span> <span class="nx">part</span> <span class="k">of</span> <span class="nx">content</span><span class="p">.</span><span class="nx">parts</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="nx">part</span> <span class="o">===</span> <span class="kc">undefined</span> <span class="o">||</span> <span class="nb">Object</span><span class="p">.</span><span class="nx">keys</span><span class="p">(</span><span class="nx">part</span><span class="p">).</span><span class="nx">length</span> <span class="o">===</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
      <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>  <span class="c1">// 空对象</span>
    <span class="p">}</span>
    <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">part</span><span class="p">.</span><span class="nx">thought</span> <span class="o">&amp;&amp;</span> <span class="nx">part</span><span class="p">.</span><span class="nx">text</span> <span class="o">!==</span> <span class="kc">undefined</span> <span class="o">&amp;&amp;</span> <span class="nx">part</span><span class="p">.</span><span class="nx">text</span> <span class="o">===</span> <span class="dl">''</span><span class="p">)</span> <span class="p">{</span>
      <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>  <span class="c1">// 空文本（除非是 thought）</span>
    <span class="p">}</span>
  <span class="p">}</span>
  <span class="k">return</span> <span class="kc">true</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<h3 id="53-上下文渲染机制">5.3 上下文渲染机制</h3>

<h4 id="初始化时的上下文设置">初始化时的上下文设置</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">private</span> <span class="k">async</span> <span class="nx">startChat</span><span class="p">(</span><span class="nx">extraHistory</span><span class="p">?:</span> <span class="nx">Content</span><span class="p">[]):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">GeminiChat</span><span class="o">&gt;</span> <span class="p">{</span>
  <span class="c1">// 1. 获取环境信息</span>
  <span class="kd">const</span> <span class="nx">envParts</span> <span class="o">=</span> <span class="k">await</span> <span class="k">this</span><span class="p">.</span><span class="nx">getEnvironment</span><span class="p">();</span>
  
  <span class="c1">// 2. 创建初始历史</span>
  <span class="kd">const</span> <span class="na">initialHistory</span><span class="p">:</span> <span class="nx">Content</span><span class="p">[]</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">{</span>
      <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">user</span><span class="dl">'</span><span class="p">,</span>
      <span class="na">parts</span><span class="p">:</span> <span class="nx">envParts</span><span class="p">,</span>  <span class="c1">// 包含日期、操作系统、工作目录、文件结构</span>
    <span class="p">},</span>
    <span class="p">{</span>
      <span class="na">role</span><span class="p">:</span> <span class="dl">'</span><span class="s1">model</span><span class="dl">'</span><span class="p">,</span>
      <span class="na">parts</span><span class="p">:</span> <span class="p">[{</span> <span class="na">text</span><span class="p">:</span> <span class="dl">'</span><span class="s1">Got it. Thanks for the context!</span><span class="dl">'</span> <span class="p">}],</span>
    <span class="p">},</span>
  <span class="p">];</span>
  
  <span class="c1">// 3. 添加系统提示词</span>
  <span class="kd">const</span> <span class="nx">systemInstruction</span> <span class="o">=</span> <span class="nx">getCoreSystemPrompt</span><span class="p">(</span><span class="nx">userMemory</span><span class="p">);</span>
  
  <span class="c1">// 4. 创建 GeminiChat 实例</span>
  <span class="k">return</span> <span class="k">new</span> <span class="nx">GeminiChat</span><span class="p">(</span>
    <span class="k">this</span><span class="p">.</span><span class="nx">config</span><span class="p">,</span>
    <span class="k">this</span><span class="p">.</span><span class="nx">getContentGenerator</span><span class="p">(),</span>
    <span class="p">{</span>
      <span class="nx">systemInstruction</span><span class="p">,</span>  <span class="c1">// 系统级指令</span>
      <span class="p">...</span><span class="nx">generateContentConfig</span><span class="p">,</span>
      <span class="nx">tools</span><span class="p">,</span>             <span class="c1">// 可用工具列表</span>
    <span class="p">},</span>
    <span class="nx">history</span><span class="p">,</span>            <span class="c1">// 初始历史</span>
  <span class="p">);</span>
<span class="p">}</span>
</code></pre></div></div>

<h4 id="完整的渲染流程">完整的渲染流程</h4>

<ol>
  <li><strong>初始化阶段</strong>：
    <ul>
      <li>系统提示词（systemInstruction）</li>
      <li>环境上下文（工作目录、文件结构等）</li>
      <li>初始的用户-模型交互</li>
    </ul>
  </li>
  <li><strong>每次发送消息</strong>：
    <ul>
      <li>获取精选历史（过滤无效响应）</li>
      <li>添加当前用户输入</li>
      <li>整个历史作为 <code class="language-plaintext highlighter-rouge">contents</code> 发送给 API</li>
    </ul>
  </li>
  <li><strong>历史更新</strong>：
    <ul>
      <li>记录用户输入和模型响应</li>
      <li>合并相邻的文本响应</li>
      <li>处理函数调用历史</li>
    </ul>
  </li>
</ol>

<hr />

<h2 id="工具系统详解-tool-system">工具系统详解 (Tool System)</h2>

<h3 id="61-工具框架架构">6.1 工具框架架构</h3>

<h4 id="工具基础接口">工具基础接口</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kr">interface</span> <span class="nx">Tool</span><span class="o">&lt;</span><span class="nx">TParams</span><span class="p">,</span> <span class="nx">TResult</span><span class="o">&gt;</span> <span class="p">{</span>
  <span class="na">name</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span>                    <span class="c1">// 内部名称</span>
  <span class="nl">displayName</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span>             <span class="c1">// 显示名称</span>
  <span class="nl">description</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span>             <span class="c1">// 功能描述</span>
  <span class="nl">schema</span><span class="p">:</span> <span class="nx">FunctionDeclaration</span><span class="p">;</span>     <span class="c1">// API 模式</span>
  <span class="nl">isOutputMarkdown</span><span class="p">:</span> <span class="nx">boolean</span><span class="p">;</span>       <span class="c1">// 输出是否为 Markdown</span>
  <span class="nl">canUpdateOutput</span><span class="p">:</span> <span class="nx">boolean</span><span class="p">;</span>        <span class="c1">// 是否支持实时输出</span>
  
  <span class="nx">validateToolParams</span><span class="p">(</span><span class="na">params</span><span class="p">:</span> <span class="nx">TParams</span><span class="p">):</span> <span class="kr">string</span> <span class="o">|</span> <span class="kc">null</span><span class="p">;</span>
  <span class="nx">shouldConfirmExecute</span><span class="p">(</span><span class="na">params</span><span class="p">:</span> <span class="nx">TParams</span><span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">ToolCallConfirmationDetails</span> <span class="o">|</span> <span class="kc">false</span><span class="o">&gt;</span><span class="p">;</span>
  <span class="nx">execute</span><span class="p">(</span><span class="na">params</span><span class="p">:</span> <span class="nx">TParams</span><span class="p">,</span> <span class="na">signal</span><span class="p">:</span> <span class="nx">AbortSignal</span><span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">TResult</span><span class="o">&gt;</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<h4 id="工具注册机制">工具注册机制</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">class</span> <span class="nx">ToolRegistry</span> <span class="p">{</span>
  <span class="k">private</span> <span class="nx">tools</span><span class="p">:</span> <span class="nb">Map</span><span class="o">&lt;</span><span class="kr">string</span><span class="p">,</span> <span class="nx">Tool</span><span class="o">&gt;</span> <span class="o">=</span> <span class="k">new</span> <span class="nb">Map</span><span class="p">();</span>
  
  <span class="c1">// 注册工具</span>
  <span class="nx">registerTool</span><span class="p">(</span><span class="nx">tool</span><span class="p">:</span> <span class="nx">Tool</span><span class="p">):</span> <span class="k">void</span>
  
  <span class="c1">// 动态发现工具（通过命令或 MCP）</span>
  <span class="k">async</span> <span class="nx">discoverTools</span><span class="p">():</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="k">void</span><span class="o">&gt;</span>
  
  <span class="c1">// 获取所有工具声明</span>
  <span class="nx">getFunctionDeclarations</span><span class="p">():</span> <span class="nx">FunctionDeclaration</span><span class="p">[]</span>
<span class="p">}</span>
</code></pre></div></div>

<h3 id="62-工具分类和功能">6.2 工具分类和功能</h3>

<h4 id="核心文件系统工具">核心文件系统工具</h4>

<ol>
  <li><strong>ReadFile Tool</strong> (<code class="language-plaintext highlighter-rouge">read_file</code>)
    <ul>
      <li><strong>作用</strong>: 读取指定文件的内容</li>
      <li><strong>特性</strong>: 支持文本、图片、PDF，分页支持大文件</li>
      <li><strong>安全</strong>: 路径限制在根目录内，遵循 .geminiignore</li>
    </ul>
  </li>
  <li><strong>ReadManyFiles Tool</strong> (<code class="language-plaintext highlighter-rouge">read_many_files</code>)
    <ul>
      <li><strong>作用</strong>: 批量读取多个文件，支持 glob 模式</li>
      <li><strong>特性</strong>: 默认排除构建目录，Git 感知过滤</li>
    </ul>
  </li>
  <li><strong>WriteFile Tool</strong> (<code class="language-plaintext highlighter-rouge">write_file</code>)
    <ul>
      <li><strong>作用</strong>: 写入内容到指定文件</li>
      <li><strong>特性</strong>: AI 内容校正，差异预览，需要用户确认</li>
    </ul>
  </li>
  <li><strong>Edit Tool</strong> (<code class="language-plaintext highlighter-rouge">replace</code>)
    <ul>
      <li><strong>作用</strong>: 在文件中替换文本（精确字符串匹配）</li>
      <li><strong>特性</strong>: AI 驱动的编辑校正，支持用户修改参数</li>
    </ul>
  </li>
</ol>

<h4 id="目录和搜索工具">目录和搜索工具</h4>

<ol>
  <li><strong>LS Tool</strong> (<code class="language-plaintext highlighter-rouge">list_directory</code>)
    <ul>
      <li><strong>作用</strong>: 列出指定目录的文件和子目录</li>
      <li><strong>特性</strong>: 文件元数据，排序输出</li>
    </ul>
  </li>
  <li><strong>Glob Tool</strong> (<code class="language-plaintext highlighter-rouge">glob</code>)
    <ul>
      <li><strong>作用</strong>: 查找匹配 glob 模式的文件</li>
      <li><strong>特性</strong>: 按修改时间排序，优先显示最近文件</li>
    </ul>
  </li>
  <li><strong>Grep Tool</strong> (<code class="language-plaintext highlighter-rouge">search_file_content</code>)
    <ul>
      <li><strong>作用</strong>: 在文件内容中搜索正则表达式</li>
      <li><strong>特性</strong>: 多策略搜索，自动错误处理</li>
    </ul>
  </li>
</ol>

<h4 id="shell-和外部工具">Shell 和外部工具</h4>

<ol>
  <li><strong>Shell Tool</strong> (<code class="language-plaintext highlighter-rouge">run_shell_command</code>)
    <ul>
      <li><strong>作用</strong>: 执行 shell 命令并进行进程管理</li>
      <li><strong>特性</strong>: 跨平台支持，实时输出流，进程组管理</li>
    </ul>
  </li>
</ol>

<h4 id="web-和网络工具">Web 和网络工具</h4>

<ol>
  <li><strong>WebSearch Tool</strong> (<code class="language-plaintext highlighter-rouge">google_web_search</code>)
    <ul>
      <li><strong>作用</strong>: 通过 Gemini API 执行 Google 搜索</li>
      <li><strong>特性</strong>: 带有来源的基础元数据，引用标记</li>
    </ul>
  </li>
  <li><strong>WebFetch Tool</strong> (<code class="language-plaintext highlighter-rouge">web_fetch</code>)
    <ul>
      <li><strong>作用</strong>: 获取并通过 AI 分析 URL 内容</li>
      <li><strong>特性</strong>: 支持多 URL，私有 IP 检测，AI 内容处理</li>
    </ul>
  </li>
</ol>

<h4 id="专业工具">专业工具</h4>

<ol>
  <li><strong>Memory Tool</strong> (<code class="language-plaintext highlighter-rouge">save_memory</code>)
    <ul>
      <li><strong>作用</strong>: 将信息保存到长期记忆文件</li>
      <li><strong>特性</strong>: Markdown 格式，自动章节管理</li>
    </ul>
  </li>
  <li><strong>动态发现工具和 MCP 工具</strong>
    <ul>
      <li><strong>作用</strong>: 通过外部命令或 MCP 服务器发现的工具</li>
      <li><strong>特性</strong>: 动态注册，JSON schema 验证</li>
    </ul>
  </li>
</ol>

<h3 id="63-安全机制">6.3 安全机制</h3>

<h4 id="多层安全保护">多层安全保护</h4>

<ol>
  <li><strong>路径验证</strong>: 所有文件操作限制在根目录内</li>
  <li><strong>Schema 验证</strong>: 所有参数的 JSON Schema 验证</li>
  <li><strong>用户确认</strong>: 破坏性操作需要用户批准</li>
  <li><strong>私有网络检测</strong>: WebFetch 检测和处理私有 IP</li>
  <li><strong>进程管理</strong>: Shell 工具提供适当的进程生命周期管理</li>
  <li><strong>Git 感知</strong>: 遵循 .gitignore 和 .geminiignore 模式</li>
  <li><strong>内容校正</strong>: AI 驱动的文件编辑验证</li>
</ol>

<h4 id="确认系统">确认系统</h4>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 多种确认类型</span>
<span class="o">-</span> <span class="nx">编辑确认</span><span class="p">:</span> <span class="nx">显示文件修改差异</span>
<span class="o">-</span> <span class="nx">执行确认</span><span class="p">:</span> <span class="nx">确认</span> <span class="nx">shell</span> <span class="nx">命令执行</span>
<span class="o">-</span> <span class="nx">MCP</span> <span class="nx">确认</span><span class="p">:</span> <span class="nx">确认外部工具执行</span>
<span class="o">-</span> <span class="nx">信息确认</span><span class="p">:</span> <span class="nx">一般信息对话框</span>
</code></pre></div></div>

<h4 id="审批模式">审批模式</h4>

<ul>
  <li><strong>手动</strong>: 每个操作需要确认</li>
  <li><strong>自动编辑</strong>: 自动批准文件操作</li>
  <li><strong>基于白名单</strong>: 记住用户决定</li>
</ul>

<hr />

<h2 id="总结与思考-summary--insights">总结与思考 (Summary &amp; Insights)</h2>

<h3 id="设计亮点">设计亮点</h3>

<ol>
  <li><strong>模块化架构</strong>: 清晰的职责分离，CLI 层负责交互控制，Core 层专注业务逻辑</li>
  <li><strong>智能历史管理</strong>: 双历史机制确保上下文质量的同时保留完整记录</li>
  <li><strong>真正并发执行</strong>: 工具调度器实现真正的并发，而非简单的异步</li>
  <li><strong>流程控制分离</strong>: CLI 层控制 Turn 流程，Core 层提供无状态服务</li>
  <li><strong>安全第一</strong>: 多层安全机制，用户确认系统，路径验证</li>
</ol>

<h3 id="架构优势-1">架构优势</h3>

<ol>
  <li><strong>可扩展性</strong>:
    <ul>
      <li>插件化工具系统，易于添加新功能</li>
      <li>MCP 协议支持，可集成外部服务</li>
      <li>模块化设计便于独立开发和测试</li>
    </ul>
  </li>
  <li><strong>用户体验</strong>:
    <ul>
      <li>实时流式响应，即时反馈</li>
      <li>智能历史过滤，提高对话质量</li>
      <li>并发工具执行，减少等待时间</li>
    </ul>
  </li>
  <li><strong>安全性</strong>:
    <ul>
      <li>沙箱环境支持</li>
      <li>用户确认机制</li>
      <li>路径和权限验证</li>
    </ul>
  </li>
  <li><strong>可维护性</strong>:
    <ul>
      <li>TypeScript 类型安全</li>
      <li>清晰的接口定义</li>
      <li>完善的错误处理</li>
    </ul>
  </li>
</ol>

<h3 id="扩展性分析">扩展性分析</h3>

<h4 id="当前架构支持的扩展方向">当前架构支持的扩展方向</h4>

<ol>
  <li><strong>新工具开发</strong>:
    <ul>
      <li>基于 <code class="language-plaintext highlighter-rouge">BaseTool</code> 类快速开发</li>
      <li>标准化的确认和验证机制</li>
      <li>自动集成到工具注册表</li>
    </ul>
  </li>
  <li><strong>多前端支持</strong>:
    <ul>
      <li>Core 包无状态设计，可支持多种前端</li>
      <li>Web UI、IDE 插件、API 服务等</li>
    </ul>
  </li>
  <li><strong>外部集成</strong>:
    <ul>
      <li>MCP 协议支持任意外部服务</li>
      <li>动态工具发现机制</li>
      <li>配置化的认证和权限管理</li>
    </ul>
  </li>
</ol>

<h4 id="潜在改进方向">潜在改进方向</h4>

<ol>
  <li><strong>性能优化</strong>:
    <ul>
      <li>工具执行结果缓存</li>
      <li>增量文件读取</li>
      <li>更智能的历史压缩</li>
    </ul>
  </li>
  <li><strong>功能增强</strong>:
    <ul>
      <li>工具执行依赖管理</li>
      <li>更细粒度的权限控制</li>
      <li>工具执行回滚机制</li>
    </ul>
  </li>
  <li><strong>监控和调试</strong>:
    <ul>
      <li>更详细的遥测数据</li>
      <li>工具执行链跟踪</li>
      <li>性能指标监控</li>
    </ul>
  </li>
</ol>

<p>Gemini CLI 展现了现代 AI 辅助开发工具的设计精髓：在保持强大功能的同时，确保安全性、可扩展性和用户体验。其模块化架构和智能的工具执行系统为未来的 AI 开发工具提供了优秀的参考模型。</p>]]></content><author><name></name></author><summary type="html"><![CDATA[Gemini CLI 架构深度分析]]></summary></entry><entry><title type="html">融资融了1700万美元的AI浏览器 Browser-Use 是怎么实现的</title><link href="/2025/05/16/browser-use-analysis/" rel="alternate" type="text/html" title="融资融了1700万美元的AI浏览器 Browser-Use 是怎么实现的" /><published>2025-05-16T01:00:00+00:00</published><updated>2025-05-16T01:00:00+00:00</updated><id>/2025/05/16/browser-use-analysis</id><content type="html" xml:base="/2025/05/16/browser-use-analysis/"><![CDATA[<h1 id="1-ai控制浏览器的应用场景">1. AI控制浏览器的应用场景</h1>
<p>简单来说，目前浏览器作为人参与互联网的重要基础设施，不仅仅作为我们的信息获取渠道，同时也已经参与进我们的生活中，比如我们通过电商平台购物，社交平台交友等等，甚至可以说人类的互联网生命是活在浏览器上，因此LLM控制浏览器的意义就在于，一旦可以完全控制，它就可以做所有的事情。</p>

<p>比如用一个简单移动的大家爱用的购买机票的例子来说：
用户 ：这是我的邮箱账号 hhhxxx@gmail.com, 密码：hhhxxx ；请你帮我登陆携程的网站购买一张今天北京飞往上海的机票最便宜的，同时我还没有注册携程账号，你需要帮我用在携程上用我的邮箱注册账号。</p>

<p>这个时候 Agent 就可以通过执行以下流程完成任务：</p>
<ol>
  <li>分析用户意图：</li>
  <li>先在携程上注册账号，那么它就会利用Browser Control 的能力收集携程网站所有能执行的动作并且找到了对应的Action，执行注册的动作</li>
  <li>继续分析下一步自己需要的操作是打开谷歌网站去拿到对应的注册用的验证码</li>
  <li>于是打开谷歌邮箱并用对应的用户名、密码，登陆，拿到对应的验证码</li>
  <li>分析下一步：返回携程网站购买机票</li>
  <li>找到当天最便宜的机票，购买，同时调用google pay 进行付款</li>
  <li>付款成功，用户在自己的邮箱里收到机票信息，以及登机牌总的来说，agent拥有了无缝接入这个世界的能力，同时agent之间的协作也会更加丝滑</li>
</ol>

<p>具体的使用场景:</p>
<ol>
  <li>可以参考openai opera里的<a href="https://openai.com/index/computer-using-agent/">几个例子</a></li>
  <li>也可以参考 browse-use 仓库里列举的<a href="https://github.com/browser-use/browser-use?tab=readme-ov-file#demos">场景</a></li>
</ol>

<h1 id="2-ai控制浏览器的不同技术路线">2. AI控制浏览器的不同技术路线</h1>
<p>首先，我们可以把Agent控制网页分为三个步骤：</p>
<ol>
  <li>理解用户指令
    <ol>
      <li>理解用户指令很简单可以利用大模型就实现了</li>
    </ol>
  </li>
  <li>解析网页</li>
  <li>在网页上执行动作</li>
</ol>

<ul>
  <li>
    <p>截图路线
现在有两个比较主流的技术路线，一种是openai-operator为首的，解析网页通过网页截图来让 Agent 理解，然后在网页上执行动作则通过 直接让Agent控制鼠标和键盘来实现，实现原理大概如下(图片来自openai operator)：
<img src="/assets/images/openai-operator.png" alt="openai-operaor" /></p>
  </li>
  <li>
    <p>DOM 路线</p>
  </li>
</ul>

<p>还有另外一种路线，也是我们今天Browse-Use的路线，是通过把Html网页解析成树状结构体(DOM Tree)，因为本身Html网页其实都是一堆XML节点的嵌套，所以很好解析成树状结构; 
然后再标识出哪些节点是可交互节点，把这些这点的index提取出来，最终把 “Task+DOM Tree+可交互节点列表”一起提交给LLM，由LLM根据用户的Task选择对应要交互的节点，然后调用Playwright执行交互动作。
原理大概如下，后面我会详细解释这张图：
<img src="/assets/images/Pasted%20image%2020250515161045.png" alt="DOM路线原理" /></p>

<h1 id="3-用dom解析的路线实现-agent-control-browse我们要解决什么问题">3. 用DOM解析的路线实现 Agent Control Browse我们要解决什么问题</h1>

<ol>
  <li>怎么让解析网页和理解指令到执行动作衔接起来?</li>
  <li>我们要实现哪些动作?
    <ul>
      <li>按照我们人使用浏览器的习惯，我们对浏览器的操作不外乎这几个动作：
        <ol>
          <li>点击</li>
          <li>跳转</li>
          <li>输入</li>
          <li>等待</li>
          <li>滚动
 这些动作的实现并不困难，因为类似 Playwright 之类的工作都可以轻松的实现之上的几个动作。</li>
        </ol>
      </li>
    </ul>
  </li>
  <li>怎么让AI的动作更像人?
 我们很容易根据自身的需求点击到正确的按钮，但是用DOM的方案就还要判断，诶我们现在拿到的这些可以交互节点中，哪些节点是我们当前窗口可以看见的节点，哪些节点是我们当前窗口看不见的节点，因此我们往往也需要给所有的节点加上一个 “可见性”的属性，从而让AI操作浏览器的时候更像人。</li>
  <li>怎么处理 Cookie ?</li>
</ol>

<h1 id="4-browser-use的解决方案">4. Browser-Use的解决方案</h1>
<p>Browser-Use的解决方案如下：</p>

<p><img src="/assets/images/Pasted%20image%2020250515161045.png" alt="DOM路线原理" /></p>
<h3 id="41-解析网页">4.1 解析网页</h3>
<p>解析网页涉及图上的 1️⃣ 和 2️⃣ :</p>

<p>首先Browse会在浏览器端注入 <code class="language-plaintext highlighter-rouge">buildDomTree.js</code> 里的代码</p>

<p>代码存在位置： https://github.com/browser-use/browser-use/blob/main/browser_use/dom/buildDomTree.js</p>

<p>代码注入位置： https://github.com/browser-use/browser-use/blob/main/browser_use/dom/service.py#L101</p>

<p><code class="language-plaintext highlighter-rouge">buildDomTree.js</code> 里会把代码按照以下方式进行解析：</p>
<ul>
  <li>遍历整个 DOM，从 <code class="language-plaintext highlighter-rouge">&lt;body&gt;</code> 开始递归所有节点。</li>
  <li>对每个节点，收集：
    <ul>
      <li>tagName、attributes、xpath、children</li>
      <li>可见性（isVisible）</li>
      <li>是否可交互（isInteractive）</li>
      <li>是否在 viewport 内（isInViewport）</li>
      <li>是否顶层元素（isTopElement）</li>
      <li>如果是可交互元素，分配一个 <code class="language-plaintext highlighter-rouge">highlightIndex</code>（如 0, 1, 2…）</li>
    </ul>
  </li>
  <li>生成一个扁平的 <code class="language-plaintext highlighter-rouge">map</code>（id -&gt; 节点信息），以及 <code class="language-plaintext highlighter-rouge">rootId</code>（根节点 id）。</li>
</ul>

<h4 id="example">Example</h4>
<p>假设有HTML网页如下：</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;head&gt;</span>
    <span class="nt">&lt;title&gt;</span>Simple Example Page<span class="nt">&lt;/title&gt;</span>
<span class="nt">&lt;/head&gt;</span>
<span class="nt">&lt;body&gt;</span>
    <span class="nt">&lt;div&gt;</span>
        <span class="nt">&lt;button</span> <span class="na">id=</span><span class="s">"btn1"</span><span class="nt">&gt;</span>Click Me<span class="nt">&lt;/button&gt;</span>
        <span class="nt">&lt;input</span> <span class="na">id=</span><span class="s">"input1"</span> <span class="na">type=</span><span class="s">"text"</span> <span class="na">placeholder=</span><span class="s">"Enter text here"</span><span class="nt">&gt;</span>
        <span class="nt">&lt;span&gt;</span>Some text<span class="nt">&lt;/span&gt;</span>
    <span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span>
</code></pre></div></div>
<p>我们的 buildDomTree.js 会通过 Playwright的evaluation函数把这js代码注入进浏览器里执行，然后我们就可以得到以下的Element Tree的Json数据：</p>
<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span>
  <span class="nl">rootId</span><span class="p">:</span> <span class="dl">"</span><span class="s2">0</span><span class="dl">"</span><span class="p">,</span>
  <span class="nx">map</span><span class="p">:</span> <span class="p">{</span>
    <span class="dl">"</span><span class="s2">0</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="c1">// body</span>
      <span class="nl">tagName</span><span class="p">:</span> <span class="dl">"</span><span class="s2">body</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">attributes</span><span class="p">:</span> <span class="p">{},</span>
      <span class="nx">xpath</span><span class="p">:</span> <span class="dl">"</span><span class="s2">/body</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">children</span><span class="p">:</span> <span class="p">[</span><span class="dl">"</span><span class="s2">1</span><span class="dl">"</span><span class="p">],</span>
      <span class="c1">// ... 其它属性</span>
    <span class="p">},</span>
    <span class="dl">"</span><span class="s2">1</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="c1">// div</span>
      <span class="nl">tagName</span><span class="p">:</span> <span class="dl">"</span><span class="s2">div</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">attributes</span><span class="p">:</span> <span class="p">{},</span>
      <span class="nx">xpath</span><span class="p">:</span> <span class="dl">"</span><span class="s2">/body/div</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">children</span><span class="p">:</span> <span class="p">[</span><span class="dl">"</span><span class="s2">2</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">3</span><span class="dl">"</span><span class="p">,</span> <span class="dl">"</span><span class="s2">4</span><span class="dl">"</span><span class="p">],</span>
      <span class="c1">// ... 其它属性</span>
    <span class="p">},</span>
    <span class="dl">"</span><span class="s2">2</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="c1">// button</span>
      <span class="nl">tagName</span><span class="p">:</span> <span class="dl">"</span><span class="s2">button</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">attributes</span><span class="p">:</span> <span class="p">{</span> <span class="nl">id</span><span class="p">:</span> <span class="dl">"</span><span class="s2">btn1</span><span class="dl">"</span> <span class="p">},</span>
      <span class="nx">xpath</span><span class="p">:</span> <span class="dl">"</span><span class="s2">/body/div/button</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">children</span><span class="p">:</span> <span class="p">[],</span>
      <span class="nx">isVisible</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">isInteractive</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">isTopElement</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">isInViewport</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">highlightIndex</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// 第一个可交互元素</span>
      <span class="c1">// ... 其它属性</span>
    <span class="p">},</span>
    <span class="dl">"</span><span class="s2">3</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="c1">// input</span>
      <span class="nl">tagName</span><span class="p">:</span> <span class="dl">"</span><span class="s2">input</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">attributes</span><span class="p">:</span> <span class="p">{</span> <span class="nl">id</span><span class="p">:</span> <span class="dl">"</span><span class="s2">input1</span><span class="dl">"</span><span class="p">,</span> <span class="nx">type</span><span class="p">:</span> <span class="dl">"</span><span class="s2">text</span><span class="dl">"</span> <span class="p">},</span>
      <span class="nx">xpath</span><span class="p">:</span> <span class="dl">"</span><span class="s2">/body/div/input</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">children</span><span class="p">:</span> <span class="p">[],</span>
      <span class="nx">isVisible</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">isInteractive</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">isTopElement</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">isInViewport</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">highlightIndex</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// 第二个可交互元素</span>
      <span class="c1">// ... 其它属性</span>
    <span class="p">},</span>
    <span class="dl">"</span><span class="s2">4</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="c1">// span</span>
      <span class="nl">tagName</span><span class="p">:</span> <span class="dl">"</span><span class="s2">span</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">attributes</span><span class="p">:</span> <span class="p">{},</span>
      <span class="nx">xpath</span><span class="p">:</span> <span class="dl">"</span><span class="s2">/body/div/span</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">children</span><span class="p">:</span> <span class="p">[</span><span class="dl">"</span><span class="s2">5</span><span class="dl">"</span><span class="p">],</span>
      <span class="nx">isVisible</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nx">isInteractive</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
      <span class="c1">// ... 其它属性</span>
    <span class="p">},</span>
    <span class="dl">"</span><span class="s2">5</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span> <span class="c1">// text node</span>
      <span class="nl">type</span><span class="p">:</span> <span class="dl">"</span><span class="s2">TEXT_NODE</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">text</span><span class="p">:</span> <span class="dl">"</span><span class="s2">Some text</span><span class="dl">"</span><span class="p">,</span>
      <span class="nx">isVisible</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
    <span class="p">}</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>然后接下来我们要把Json版本的Dom Tree转换成用Python版本的Map存储（本身数据没有变化，只是用了python的map来存储数据以及提取出当前可以被交互的节点列表 selector map）</p>

<p>代码位置： https://github.com/browser-use/browser-use/blob/main/browser_use/dom/service.py#L117</p>

<ul>
  <li>调用 <code class="language-plaintext highlighter-rouge">_construct_dom_tree(eval_page)</code>，把 JS 端的扁平 map 还原为 Python 的树状结构。</li>
  <li>每个节点变成 <code class="language-plaintext highlighter-rouge">DOMElementNode</code> 或 <code class="language-plaintext highlighter-rouge">DOMTextNode</code>，父子关系用 <code class="language-plaintext highlighter-rouge">children</code> 和 <code class="language-plaintext highlighter-rouge">parent</code> 字段连接。</li>
  <li><strong>selector_map</strong>：把所有有 <code class="language-plaintext highlighter-rouge">highlightIndex</code> 的节点收集起来，形成 <code class="language-plaintext highlighter-rouge">{highlightIndex: node}</code> 的字典。</li>
</ul>

<p>但是这里面我们要注意以下几个tag的作用，这几个tag的存在可以让LLM操作网页更像人而且不会误触</p>

<table>
  <thead>
    <tr>
      <th>属性</th>
      <th>作用</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>isVisible</td>
      <td>过滤不可见元素，防止误操作，辅助 LLM 理解页面布局</td>
    </tr>
    <tr>
      <td>isInteractive</td>
      <td>只对可交互元素操作，生成 selector_map，提升泛化能力</td>
    </tr>
    <tr>
      <td>isInViewport</td>
      <td>优先操作视口内元素，辅助滚动决策，模拟真实用户行为</td>
    </tr>
    <tr>
      <td>isTopElement</td>
      <td>避免点到被遮挡元素，提升操作准确性，适配复杂页面</td>
    </tr>
  </tbody>
</table>

<p><strong>这四个属性共同保证了 Browser Agent 的操作既”像人一样”，又”高效、准确、鲁棒”。</strong></p>

<p>然后接下来，我们需要把json数据继续解析成Python版本的DOM Tree，代码里的名字叫Element Tree;以及对应的可交互节点列表，代码里的名字叫(selector map)</p>
<h4 id="b-selector_map">b) selector_map</h4>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">selector_map</span> <span class="o">=</span> <span class="p">{</span>
    <span class="mi">0</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">DOMElementNode</span> <span class="k">for</span> <span class="n">button</span> <span class="nb">id</span><span class="o">=</span><span class="s">"btn1"</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="mi">1</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">DOMElementNode</span> <span class="k">for</span> <span class="nb">input</span> <span class="nb">id</span><span class="o">=</span><span class="s">"input1"</span><span class="o">&gt;</span>
<span class="p">}</span>
</code></pre></div></div>
<p><strong>这里的index代表selector_map的key, xpath 也可以在上面生成的element_tree得到对应的值。</strong></p>

<p>到这里我们，我们就将网页解析DOM Tree + 可交互列表了，也就完成了分析网页这一步；</p>

<h3 id="42操作网页">4.2操作网页</h3>
<p>操作网页我们来看看， Browser-Use实现了哪些Action:</p>

<p>可以在<code class="language-plaintext highlighter-rouge">browser_use/controller/service.py</code> 里找到所有Action</p>

<table>
  <thead>
    <tr>
      <th>Action 名字</th>
      <th>描述</th>
      <th>参数（主要）</th>
      <th>必要性/使用场景</th>
      <th>与 DOM 的关系</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>search_google</td>
      <td>在当前标签页用 Google 搜索</td>
      <td>query: str</td>
      <td>信息检索、自动化搜索、导航到新内容</td>
      <td>仅与页面跳转相关，非直接 DOM 操作</td>
    </tr>
    <tr>
      <td>go_to_url</td>
      <td>跳转到指定 URL</td>
      <td>url: str</td>
      <td>任意网页导航、流程跳转</td>
      <td>仅与页面跳转相关，非直接 DOM 操作</td>
    </tr>
    <tr>
      <td>go_back</td>
      <td>浏览器后退</td>
      <td>无</td>
      <td>多步流程回退、历史导航</td>
      <td>仅与页面跳转相关，非直接 DOM 操作</td>
    </tr>
    <tr>
      <td>wait</td>
      <td>等待指定秒数</td>
      <td>seconds: int = 3</td>
      <td>等待页面加载、异步内容渲染、节奏控制</td>
      <td>无直接关系</td>
    </tr>
    <tr>
      <td>click_element_by_index</td>
      <td>点击指定 index 的可交互元素</td>
      <td>index: int, xpath: str?</td>
      <td>按钮点击、链接跳转、菜单操作、表单提交等所有点击场景</td>
      <td>依赖 selector_map 的 index 定位 DOM 元素</td>
    </tr>
    <tr>
      <td>input_text</td>
      <td>在指定 index 的输入框输入文本</td>
      <td>index: int, text: str, xpath: str?</td>
      <td>表单填写、登录、搜索、评论、输入等</td>
      <td>依赖 selector_map 的 index 定位 DOM 元素</td>
    </tr>
    <tr>
      <td>save_pdf</td>
      <td>保存当前页面为 PDF</td>
      <td>无</td>
      <td>页面归档、报告生成、内容保存</td>
      <td>仅与页面内容相关，非直接 DOM 操作</td>
    </tr>
    <tr>
      <td>switch_tab</td>
      <td>切换到指定标签页</td>
      <td>page_id: int</td>
      <td>多标签场景、并行任务、内容对比</td>
      <td>仅与标签页管理相关，非直接 DOM 操作</td>
    </tr>
    <tr>
      <td>open_tab</td>
      <td>新建标签页并打开指定 URL</td>
      <td>url: str</td>
      <td>多任务、并行浏览、内容分组</td>
      <td>仅与标签页管理相关，非直接 DOM 操作</td>
    </tr>
    <tr>
      <td>close_tab</td>
      <td>关闭指定标签页</td>
      <td>page_id: int</td>
      <td>资源释放、流程结束</td>
      <td>仅与标签页管理相关，非直接 DOM 操作</td>
    </tr>
    <tr>
      <td>extract_content</td>
      <td>抽取页面内容，按目标提取结构化信息</td>
      <td>goal: str, should_strip_link_urls: bool</td>
      <td>信息抽取、数据抓取、内容理解</td>
      <td>读取整个 DOM 内容，结构化处理</td>
    </tr>
    <tr>
      <td>scroll_down</td>
      <td>页面下滚指定像素或一屏</td>
      <td>amount: int?</td>
      <td>加载更多内容、滚动到目标、触发懒加载</td>
      <td>操作 window/document，间接影响 DOM 可见性</td>
    </tr>
    <tr>
      <td>scroll_up</td>
      <td>页面上滚指定像素或一屏</td>
      <td>amount: int?</td>
      <td>返回顶部、查找内容、页面回溯</td>
      <td>操作 window/document，间接影响 DOM 可见性</td>
    </tr>
    <tr>
      <td>send_keys</td>
      <td>发送特殊按键（如 Enter、Esc、快捷键等）</td>
      <td>keys: str</td>
      <td>关闭弹窗、表格操作、快捷命令、特殊交互</td>
      <td>可能影响 DOM 状态（如表单提交、弹窗关闭等）</td>
    </tr>
    <tr>
      <td>scroll_to_text</td>
      <td>滚动到页面中包含指定文本的位置</td>
      <td>text: str</td>
      <td>查找内容、定位元素、辅助交互</td>
      <td>通过文本查找 DOM 元素并滚动到其可见区域</td>
    </tr>
    <tr>
      <td>get_dropdown_options</td>
      <td>获取下拉框所有选项</td>
      <td>index: int</td>
      <td>表单分析、自动选择、内容理解</td>
      <td>依赖 selector_map 的 index 定位 select 元素</td>
    </tr>
    <tr>
      <td>select_dropdown_option</td>
      <td>选择下拉框指定文本的选项</td>
      <td>index: int, text: str</td>
      <td>表单填写、选项切换</td>
      <td>依赖 selector_map 的 index 定位 select 元素</td>
    </tr>
    <tr>
      <td>drag_drop</td>
      <td>拖拽元素或坐标</td>
      <td>element_source/target, 坐标等</td>
      <td>拖拽排序、滑块验证、canvas绘图、UI交互</td>
      <td>依赖 DOM 元素定位，操作鼠标事件</td>
    </tr>
    <tr>
      <td>get_sheet_contents</td>
      <td>获取 Google Sheets 整个表格内容</td>
      <td>无</td>
      <td>表格数据抓取、批量分析</td>
      <td>通过键盘操作和剪贴板，间接与 DOM 交互</td>
    </tr>
    <tr>
      <td>select_cell_or_range</td>
      <td>选中 Google Sheets 指定单元格或范围</td>
      <td>cell_or_range: str</td>
      <td>表格导航、数据定位</td>
      <td>通过键盘操作，间接与 DOM 交互</td>
    </tr>
    <tr>
      <td>get_range_contents</td>
      <td>获取 Google Sheets 指定单元格/范围内容</td>
      <td>cell_or_range: str</td>
      <td>表格数据抓取、批量分析</td>
      <td>通过键盘操作和剪贴板，间接与 DOM 交互</td>
    </tr>
    <tr>
      <td>clear_selected_range</td>
      <td>清空 Google Sheets 当前选中单元格</td>
      <td>无</td>
      <td>表格编辑、数据清理</td>
      <td>通过键盘操作，间接与 DOM 交互</td>
    </tr>
    <tr>
      <td>input_selected_cell_text</td>
      <td>向 Google Sheets 当前单元格输入文本</td>
      <td>text: str</td>
      <td>表格编辑、数据录入</td>
      <td>通过键盘操作，间接与 DOM 交互</td>
    </tr>
    <tr>
      <td>update_range_contents</td>
      <td>批量更新 Google Sheets 单元格内容</td>
      <td>range: str, new_contents_tsv: str</td>
      <td>表格批量编辑、自动化填表</td>
      <td>通过键盘和剪贴板，间接与 DOM 交互</td>
    </tr>
  </tbody>
</table>

<p><strong>说明</strong></p>

<ul>
  <li><strong>参数</strong>：只列出最关键的参数，实际有些 action 还有可选参数。</li>
  <li><strong>必要性/使用场景</strong>：说明该 action 在网页自动化中的典型用途。</li>
  <li><strong>与 DOM 的关系</strong>：
    <ul>
      <li>“依赖 selector_map 的 index 定位 DOM 元素”表示该 action 需要结构化 DOM 信息来精确定位目标元素。</li>
      <li>“仅与页面跳转/标签页管理相关”表示该 action 主要操作浏览器，不直接操作 DOM。</li>
      <li>“通过键盘操作，间接与 DOM 交互”表示该 action 通过模拟用户输入影响页面内容。</li>
    </ul>
  </li>
</ul>

<h4 id="example-click_element_by_index-和-input_text-代码解析">Example: click_element_by_index 和 input_text 代码解析</h4>
<p>这里我们以上面两个典型的Action click_element_by_index 和 input_text Action 来帮大家更好理解DOM Tree、Selector Map 和 DOM Tree之间的关系。</p>

<p>这两个函数是 browser-use 中最核心的交互 action，下面详细解析它们如何利用 DOM Tree 和 selector_map 与网页交互：</p>
<h5 id="1-click_element_by_index-详解">1. click_element_by_index 详解</h5>

<p>这个函数实现了”通过索引点击元素”的功能：</p>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">@</span><span class="bp">self</span><span class="p">.</span><span class="n">registry</span><span class="p">.</span><span class="n">action</span><span class="p">(</span><span class="s">'Click element by index'</span><span class="p">,</span> <span class="n">param_model</span><span class="o">=</span><span class="n">ClickElementAction</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">click_element_by_index</span><span class="p">(</span><span class="n">params</span><span class="p">:</span> <span class="n">ClickElementAction</span><span class="p">,</span> <span class="n">browser</span><span class="p">:</span> <span class="n">BrowserContext</span><span class="p">):</span>
    <span class="c1"># ...省略部分代码...
</span></code></pre></div></div>

<h6 id="核心流程">核心流程</h6>
<ol>
  <li><strong>参数验证</strong>：首先检查传入的 <code class="language-plaintext highlighter-rouge">index</code> 在 selector_map 中是否存在：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="n">params</span><span class="p">.</span><span class="n">index</span> <span class="ow">not</span> <span class="ow">in</span> <span class="k">await</span> <span class="n">browser</span><span class="p">.</span><span class="n">get_selector_map</span><span class="p">():</span>
    <span class="k">raise</span> <span class="nb">Exception</span><span class="p">(</span><span class="sa">f</span><span class="s">'Element with index </span><span class="si">{</span><span class="n">params</span><span class="p">.</span><span class="n">index</span><span class="si">}</span><span class="s"> does not exist - retry or use alternative actions'</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
  <li><strong>获取 DOM 节点</strong>：通过索引从 selector_map 中获取对应的 DOM 节点：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">element_node</span> <span class="o">=</span> <span class="k">await</span> <span class="n">browser</span><span class="p">.</span><span class="n">get_dom_element_by_index</span><span class="p">(</span><span class="n">params</span><span class="p">.</span><span class="n">index</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
  <li><strong>特殊情况处理</strong>：检查元素是否为文件上传器，如果是则不执行点击：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="k">await</span> <span class="n">browser</span><span class="p">.</span><span class="n">is_file_uploader</span><span class="p">(</span><span class="n">element_node</span><span class="p">):</span>
    <span class="c1"># ...省略报错代码...
</span></code></pre></div>    </div>
  </li>
  <li><strong>执行点击</strong>：调用 <code class="language-plaintext highlighter-rouge">_click_element_node</code> 执行实际的点击操作：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">download_path</span> <span class="o">=</span> <span class="k">await</span> <span class="n">browser</span><span class="p">.</span><span class="n">_click_element_node</span><span class="p">(</span><span class="n">element_node</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
  <li><strong>处理后果</strong>：处理点击后可能的下载文件或新标签页：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="n">download_path</span><span class="p">:</span>
    <span class="n">msg</span> <span class="o">=</span> <span class="sa">f</span><span class="s">'💾  Downloaded file to </span><span class="si">{</span><span class="n">download_path</span><span class="si">}</span><span class="s">'</span>
<span class="k">else</span><span class="p">:</span>
    <span class="n">msg</span> <span class="o">=</span> <span class="sa">f</span><span class="s">'🖱️  Clicked button with index </span><span class="si">{</span><span class="n">params</span><span class="p">.</span><span class="n">index</span><span class="si">}</span><span class="s">: </span><span class="si">{</span><span class="n">element_node</span><span class="p">.</span><span class="n">get_all_text_till_next_clickable_element</span><span class="p">(</span><span class="n">max_depth</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span><span class="si">}</span><span class="s">'</span>
   
<span class="c1"># 检测是否打开了新标签页
</span><span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">session</span><span class="p">.</span><span class="n">context</span><span class="p">.</span><span class="n">pages</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">initial_pages</span><span class="p">:</span>
    <span class="n">new_tab_msg</span> <span class="o">=</span> <span class="s">'New tab opened - switching to it'</span>
    <span class="c1"># ...切换到新标签页...
</span></code></pre></div>    </div>
  </li>
</ol>

<h5 id="2-input_text-详解">2. input_text 详解</h5>

<p>这个函数实现了”在表单元素中输入文本”的功能：</p>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">@</span><span class="bp">self</span><span class="p">.</span><span class="n">registry</span><span class="p">.</span><span class="n">action</span><span class="p">(</span><span class="s">'Input text into a input interactive element'</span><span class="p">,</span> <span class="n">param_model</span><span class="o">=</span><span class="n">InputTextAction</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">input_text</span><span class="p">(</span><span class="n">params</span><span class="p">:</span> <span class="n">InputTextAction</span><span class="p">,</span> <span class="n">browser</span><span class="p">:</span> <span class="n">BrowserContext</span><span class="p">,</span> <span class="n">has_sensitive_data</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="bp">False</span><span class="p">):</span>
    <span class="c1"># ...省略部分代码...
</span></code></pre></div></div>

<h6 id="核心流程-1">核心流程</h6>
<ol>
  <li><strong>参数验证</strong>：首先检查传入的 <code class="language-plaintext highlighter-rouge">index</code> 在 selector_map 中是否存在：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="n">params</span><span class="p">.</span><span class="n">index</span> <span class="ow">not</span> <span class="ow">in</span> <span class="k">await</span> <span class="n">browser</span><span class="p">.</span><span class="n">get_selector_map</span><span class="p">():</span>
    <span class="k">raise</span> <span class="nb">Exception</span><span class="p">(</span><span class="sa">f</span><span class="s">'Element index </span><span class="si">{</span><span class="n">params</span><span class="p">.</span><span class="n">index</span><span class="si">}</span><span class="s"> does not exist - retry or use alternative actions'</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
  <li><strong>获取 DOM 节点</strong>：通过索引从 selector_map 中获取对应的 DOM 节点：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">element_node</span> <span class="o">=</span> <span class="k">await</span> <span class="n">browser</span><span class="p">.</span><span class="n">get_dom_element_by_index</span><span class="p">(</span><span class="n">params</span><span class="p">.</span><span class="n">index</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
  <li><strong>执行输入</strong>：调用 <code class="language-plaintext highlighter-rouge">_input_text_element_node</code> 执行实际的文本输入：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">await</span> <span class="n">browser</span><span class="p">.</span><span class="n">_input_text_element_node</span><span class="p">(</span><span class="n">element_node</span><span class="p">,</span> <span class="n">params</span><span class="p">.</span><span class="n">text</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
  <li><strong>日志记录</strong>：记录操作日志，敏感数据不显示具体内容：
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="ow">not</span> <span class="n">has_sensitive_data</span><span class="p">:</span>
    <span class="n">msg</span> <span class="o">=</span> <span class="sa">f</span><span class="s">'⌨️  Input </span><span class="si">{</span><span class="n">params</span><span class="p">.</span><span class="n">text</span><span class="si">}</span><span class="s"> into index </span><span class="si">{</span><span class="n">params</span><span class="p">.</span><span class="n">index</span><span class="si">}</span><span class="s">'</span>
<span class="k">else</span><span class="p">:</span>
    <span class="n">msg</span> <span class="o">=</span> <span class="sa">f</span><span class="s">'⌨️  Input sensitive data into index </span><span class="si">{</span><span class="n">params</span><span class="p">.</span><span class="n">index</span><span class="si">}</span><span class="s">'</span>
</code></pre></div>    </div>
  </li>
</ol>

<h5 id="3-与-dom-tree-和-selector_map-的关系">3. 与 DOM Tree 和 selector_map 的关系</h5>

<h6 id="selector_map-作用">selector_map 作用</h6>
<p>selector_map 是一个 <code class="language-plaintext highlighter-rouge">{highlight_index: DOMElementNode}</code> 的字典，它是浏览器交互的核心中间层：</p>

<ol>
  <li><strong>“翻译层”作用</strong>：
    <ul>
      <li>把 LLM 生成的简单数字索引（如 <code class="language-plaintext highlighter-rouge">index=2</code>）翻译成复杂的 DOM 节点对象</li>
      <li>使 LLM 不需要理解复杂的 CSS 选择器或 XPath 就能准确操作元素</li>
    </ul>
  </li>
  <li><strong>仅包含可交互元素</strong>：
    <ul>
      <li>selector_map 只包含那些 <code class="language-plaintext highlighter-rouge">isInteractive=True</code> 的元素</li>
      <li>这大大简化了 LLM 的决策，让它专注于”有意义”的交互</li>
    </ul>
  </li>
</ol>

<h6 id="dom-tree-作用">DOM Tree 作用</h6>
<p>DOM Tree 是完整网页的结构化表示，为交互提供了丰富上下文：</p>

<ol>
  <li><strong>元素定位</strong>：
    <ul>
      <li><code class="language-plaintext highlighter-rouge">browser._click_element_node</code> 和 <code class="language-plaintext highlighter-rouge">browser._input_text_element_node</code> 内部通过 DOM 节点的 xpath 属性定位元素</li>
      <li>完整的树结构让系统能处理 iframe 嵌套等复杂情况</li>
    </ul>
  </li>
  <li><strong>上下文信息</strong>：
    <ul>
      <li>元素的父子关系、文本内容、属性等都保存在 DOM Tree 中</li>
      <li>例如 <code class="language-plaintext highlighter-rouge">element_node.get_all_text_till_next_clickable_element(max_depth=2)</code> 获取点击的元素周围文本</li>
    </ul>
  </li>
  <li><strong>交互安全检查</strong>：
    <ul>
      <li>通过检查 <code class="language-plaintext highlighter-rouge">isVisible</code>、<code class="language-plaintext highlighter-rouge">isTopElement</code> 等属性确保交互的安全性</li>
      <li>如 <code class="language-plaintext highlighter-rouge">is_file_uploader</code> 检查防止意外触发文件选择对话框</li>
    </ul>
  </li>
</ol>

<h5 id="4-交互链路总结">4. 交互链路总结</h5>

<p>整个交互链路是：</p>
<ol>
  <li>DOM 解析 → DOM Tree + selector_map</li>
  <li>LLM 选择操作元素的索引 index</li>
  <li>Action 函数通过 <code class="language-plaintext highlighter-rouge">get_dom_element_by_index(index)</code> 从 selector_map 获取完整 DOM 节点</li>
  <li>借助 DOM 节点的 xpath 等属性，执行实际的浏览器操作</li>
  <li>返回操作结果，包括周围上下文文本</li>
</ol>

<p>这种设计让 LLM 能通过简单的索引号精准操作网页元素，同时保留了复杂交互所需的全部上下文信息。</p>

<h3 id="43-怎么让解析网页和操作网页联系起来">4.3 怎么让解析网页和操作网页联系起来</h3>
<p>上面我们在4.2 click_element_by_index 和 input_tex的例子里已经提到了DOM Tree怎么和Action 联系起来的，在这里我们更加high level的介绍它：</p>

<p><img src="/assets/images/Pasted%20image%2020250515175943.png" alt="LLM与网页的交互方式" />
<strong>LLM 之所以能在 params 里生成正确的 index（即 selector），确实是因为 prompt 里包含了 selector map 和/或结构化 DOM tree 的信息。</strong></p>
<ul>
  <li>
    <ol>
      <li>LLM 为什么能”知道”index？</li>
    </ol>
  </li>
  <li>在每一步 Agent 调用 LLM 之前，<strong>会把当前页面的 selector map（所有可交互元素的 index、属性、文本等）和 DOM tree 的关键信息，作为 prompt 的一部分传递给 LLM</strong>。</li>
  <li>
    <p>这样 LLM 就能”看到”页面上有哪些可交互元素、它们的 index、类型、文本、属性等，从而在 action params 里生成正确的 index。</p>
  </li>
  <li>
    <ol>
      <li>代码实现线索（@service.py）
关键点：消息管理和 prompt 构造
a) <code class="language-plaintext highlighter-rouge">step</code> 方法中
在 <code class="language-plaintext highlighter-rouge">step</code> 方法里，有这样一段：
        <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="bp">self</span><span class="p">.</span><span class="n">_message_manager</span><span class="p">.</span><span class="n">add_state_message</span><span class="p">(</span><span class="n">state</span><span class="p">,</span> <span class="bp">self</span><span class="p">.</span><span class="n">state</span><span class="p">.</span><span class="n">last_result</span><span class="p">,</span> <span class="n">step_info</span><span class="p">,</span> <span class="bp">self</span><span class="p">.</span><span class="n">settings</span><span class="p">.</span><span class="n">use_vision</span><span class="p">)</span>
</code></pre></div>        </div>
      </li>
    </ol>
  </li>
  <li>这里的 <code class="language-plaintext highlighter-rouge">state</code> 就是 <code class="language-plaintext highlighter-rouge">BrowserState</code>，包含了我们上面提到的 <code class="language-plaintext highlighter-rouge">element_tree</code> 和 <code class="language-plaintext highlighter-rouge">selector_map</code>以及 当前网页的screenshot。</li>
  <li><code class="language-plaintext highlighter-rouge">add_state_message</code> 会把这些结构化信息<strong>组织成 LLM prompt 的一部分</strong>。</li>
</ul>

<p>b) <code class="language-plaintext highlighter-rouge">MessageManager</code> 相关</p>
<ul>
  <li><code class="language-plaintext highlighter-rouge">MessageManager</code> 负责把当前页面状态、历史操作、可用 action 等信息，<strong>拼接成 LLM 的输入消息</strong>。</li>
  <li>具体会用到 <code class="language-plaintext highlighter-rouge">AgentMessagePrompt</code>、<code class="language-plaintext highlighter-rouge">SystemPrompt</code> 等 prompt 构造器，把 selector map、DOM tree、元素属性、index、文本等信息格式化为自然语言或结构化文本，供 LLM 理解。
 c) prompt 例子（伪代码）
LLM 看到的 prompt 可能类似于：</li>
</ul>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>当前页面可交互元素列表：
0: button, text="提交", xpath="/body/div/button[1]"
1: input, placeholder="请输入用户名", xpath="/body/div/input[1]"
2: button, text="取消", xpath="/body/div/button[2]"
...

请根据用户指令选择合适的 index 进行操作。
</code></pre></div></div>

<h3 id="44-专用action">4.4 专用Action</h3>
<p>另外一个需要注意的是 <strong>browser-use 实现了”不同的 Page 可以动态注册不同的 Action”</strong>，这部分逻辑主要在<code class="language-plaintext highlighter-rouge">agent/service.py</code></p>
<h4 id="一核心机制总结">一、核心机制总结</h4>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>1. **Action 注册是静态的**：所有 Action（如点击、输入、滚动等）都通过 Python 装饰器 `@action` 静态注册到 `Controller.registry`。
2. **Action 的"可用性"是动态的**：每一步，Agent 会根据当前 Page 的特征（如 URL、DOM 结构、可交互元素等），**动态过滤/筛选出"当前页面可用的 Action"**，并动态生成对应的 ActionModel。
3. **Prompt 里只暴露当前可用的 Action**：LLM 的 prompt 里只会暴露"当前页面可用的 Action"，这样 LLM 只能选择这些 Action。
</code></pre></div></div>

<h4 id="二关键代码实现">二、关键代码实现</h4>
<ol>
  <li>Action 的注册与过滤
    <ul>
      <li>所有 Action 都通过 <code class="language-plaintext highlighter-rouge">@action</code> 装饰器注册到 <code class="language-plaintext highlighter-rouge">Controller.registry</code>。</li>
      <li>每个 Action 可以带有 <code class="language-plaintext highlighter-rouge">page_filter</code>、<code class="language-plaintext highlighter-rouge">domains</code> 等参数，决定它在哪些页面可用。
 <strong>例子：</strong>
        <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">@</span><span class="n">registry</span><span class="p">.</span><span class="n">action</span><span class="p">(</span>
 <span class="n">name</span><span class="o">=</span><span class="s">"search_google"</span><span class="p">,</span>
 <span class="n">description</span><span class="o">=</span><span class="s">"在 Google 搜索当前 query"</span><span class="p">,</span>
 <span class="n">page_filter</span><span class="o">=</span><span class="k">lambda</span> <span class="n">page</span><span class="p">:</span> <span class="s">"google.com"</span> <span class="ow">in</span> <span class="n">page</span><span class="p">.</span><span class="n">url</span>
<span class="p">)</span>
<span class="k">def</span> <span class="nf">search_google</span><span class="p">(...):</span>
 <span class="p">...</span>
</code></pre></div>        </div>
      </li>
      <li>这个 Action 只会在 URL 包含 <code class="language-plaintext highlighter-rouge">google.com</code> 的页面被视为”可用”。</li>
    </ul>
  </li>
  <li>动态生成 ActionModel</li>
</ol>

<p>在 <code class="language-plaintext highlighter-rouge">agent/service.py</code> 里，step()函数会调用：</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">await</span> <span class="bp">self</span><span class="p">.</span><span class="n">_update_action_models_for_page</span><span class="p">(</span><span class="n">active_page</span><span class="p">)</span>
</code></pre></div></div>
<ul>
  <li>这会调用 <code class="language-plaintext highlighter-rouge">controller.registry.create_action_model(page=active_page)</code>，只把”当前页面可用的 Action”动态生成到 ActionModel 里。
    <ol>
      <li>LLM Prompt 只暴露可用 Action</li>
    </ol>
  </li>
  <li><code class="language-plaintext highlighter-rouge">get_prompt_description(page)</code> 只返回当前页面可用的 Action 描述，作为 prompt 的一部分。</li>
  <li>LLM 只能选择这些 Action 并生成参数。</li>
</ul>

<h4 id="三具体举例">三、具体举例</h4>

<ol>
  <li>例子 1：在 Google 搜索页
    <ul>
      <li>当前页面 URL: <code class="language-plaintext highlighter-rouge">https://www.google.com/search?q=python</code></li>
      <li>可用 Action（被动态注册到 ActionModel）：
        <ul>
          <li><code class="language-plaintext highlighter-rouge">ClickElementAction</code></li>
          <li><code class="language-plaintext highlighter-rouge">InputTextAction</code></li>
          <li><code class="language-plaintext highlighter-rouge">search_google</code>（因为 page_filter 匹配）</li>
        </ul>
      </li>
    </ul>
  </li>
  <li>例子 2：在淘宝商品页
    <ul>
      <li>当前页面 URL: <code class="language-plaintext highlighter-rouge">https://item.taobao.com/item.htm?id=123456</code></li>
      <li>可用 Action：
        <ul>
          <li><code class="language-plaintext highlighter-rouge">ClickElementAction</code></li>
          <li><code class="language-plaintext highlighter-rouge">InputTextAction</code></li>
          <li><code class="language-plaintext highlighter-rouge">add_to_cart</code>（假设有 page_filter=lambda page: “taobao.com” in page.url）</li>
        </ul>
      </li>
    </ul>
  </li>
  <li>在任意页面
    <ul>
      <li>没有特殊 page_filter 的 Action（如”点击”、”输入”、”滚动”）<strong>始终可用</strong>。</li>
    </ul>
  </li>
</ol>

<h4 id="四代码片段解读">四、代码片段解读</h4>

<ol>
  <li>动态生成 ActionModel 的关键代码</li>
</ol>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">async</span> <span class="k">def</span> <span class="nf">_update_action_models_for_page</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">page</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="bp">None</span><span class="p">:</span>
    <span class="c1"># 只把当前页面可用的 action 动态生成到 ActionModel
</span>    <span class="bp">self</span><span class="p">.</span><span class="n">ActionModel</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">controller</span><span class="p">.</span><span class="n">registry</span><span class="p">.</span><span class="n">create_action_model</span><span class="p">(</span><span class="n">page</span><span class="o">=</span><span class="n">page</span><span class="p">)</span>
    <span class="bp">self</span><span class="p">.</span><span class="n">AgentOutput</span> <span class="o">=</span> <span class="n">AgentOutput</span><span class="p">.</span><span class="n">type_with_custom_actions</span><span class="p">(</span><span class="bp">self</span><span class="p">.</span><span class="n">ActionModel</span><span class="p">)</span>
</code></pre></div></div>

<ol>
  <li>动态过滤 Action 的实现（伪代码）</li>
</ol>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">create_action_model</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">page</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
    <span class="c1"># 遍历所有注册的 action
</span>    <span class="k">for</span> <span class="n">action</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">.</span><span class="n">actions</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">action</span><span class="p">.</span><span class="n">page_filter</span> <span class="ow">is</span> <span class="bp">None</span> <span class="ow">or</span> <span class="n">action</span><span class="p">.</span><span class="n">page_filter</span><span class="p">(</span><span class="n">page</span><span class="p">):</span>
            <span class="c1"># 只把可用的 action 加入到 ActionModel
</span>            <span class="p">...</span>
</code></pre></div></div>

<h4 id="五总结">五、总结</h4>

<ul>
  <li><strong>Action 注册是静态的，Action 可用性是动态的。</strong></li>
  <li>每次 step 前，Agent 都会根据当前 Page，动态生成只包含”可用 Action”的 ActionModel。</li>
  <li>LLM 只能选择这些 Action，保证了安全性和泛化能力。</li>
  <li>你可以通过给 Action 注册时加 page_filter、domains 等参数，实现”只在特定页面暴露 Action”。</li>
</ul>

<h1 id="5-browse-use-完整流程">5. Browse-Use 完整流程</h1>
<p><img src="/assets/images/Pasted%20image%2020250515161045.png" alt="DOM路线原理" /></p>
<ol>
  <li>先通过在页面中注入 BuildDomTree.je的代码</li>
  <li>通过注入的代码提取出当前的Html页面的 Dom Tree，以及对应的可交互节点列表</li>
  <li>LLM 理解用户指令</li>
  <li>Html网页的截图以及Dom Tree和可交互节点列表一起提交给 LLM
    <ul>
      <li>LLM 看到的 prompt 可能类似于：</li>
    </ul>
  </li>
</ol>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>	当前的页面截图：
	website.png
	
	当前的DOM Tree:
	Element Tree
	
	当前页面可交互元素列表：
	0: button, text="提交", xpath="/body/div/button[1]"
	1: input, placeholder="请输入用户名", xpath="/body/div/input[1]"
	2: button, text="取消", xpath="/body/div/button[2]"
	...
	
	用户指令：
		帮我购买机票
		
	请根据用户指令、可交互元素列表、以及页面截图，选择合适的Action操作当前页面
</code></pre></div></div>

<ol>
  <li>LLM 选择合适的 Action进行执行</li>
  <li>最终由 Playwright 控制浏览器通过LLM选出的Action和对应的参数操作浏览器，并且会生成新的网页DOM Tree继续进入下一个循环直到用户的任务被完全解决</li>
</ol>]]></content><author><name></name></author><category term="ai" /><category term="browser" /><category term="ai" /><category term="llm" /><category term="automation" /><summary type="html"><![CDATA[1. AI控制浏览器的应用场景 简单来说，目前浏览器作为人参与互联网的重要基础设施，不仅仅作为我们的信息获取渠道，同时也已经参与进我们的生活中，比如我们通过电商平台购物，社交平台交友等等，甚至可以说人类的互联网生命是活在浏览器上，因此LLM控制浏览器的意义就在于，一旦可以完全控制，它就可以做所有的事情。]]></summary></entry><entry><title type="html">Buzz 为每个人创造自己的web3 Agent</title><link href="/2025/01/17/buzz-web3-agent/" rel="alternate" type="text/html" title="Buzz 为每个人创造自己的web3 Agent" /><published>2025-01-17T02:00:00+00:00</published><updated>2025-01-17T02:00:00+00:00</updated><id>/2025/01/17/buzz-web3-agent</id><content type="html" xml:base="/2025/01/17/buzz-web3-agent/"><![CDATA[<p><img src="/assets/images/buzz-overview.png" alt="buzz overview" /></p>

<h2 id="1-buzz的架构如下">1. Buzz的架构如下：</h2>
<p><img src="/assets/images/buzz-app-framework.png" alt="buzz app framework" /></p>

<p>Buzz基本上还是跟我们写过的ElizaOS框架差不多的架构，分为 Chat App, LLM, Tools, CosmosDB.</p>

<ul>
  <li>ChatApp 就是我们登陆 Buzz 时的用户界面，主要用于管理跟用户的交互过程</li>
  <li>LLM 仍然是任何Agent的核心组件就不多介绍了</li>
  <li>Buzz 目前支持的 tool 主要有 Twitter Tools, Solona Tools, Knowledge Tools</li>
  <li>其中Twitter Tools实现了通过用户给的keyword 在推特上搜索信息并且总结后返回给用户</li>
  <li>Solana Toos 则是实现了一些Defi协议的操作，例如swap, stake 等待操作</li>
  <li>Knowledge Tools 则是Buzz 的特色,它预先往自己的数据库添加了一些web3的知识，主要是solona上defi 协议的相关知识，因此当用户询问跟这些知识相关的问题时会触发</li>
  <li>CosmosDB 则类似于我们之前 ElizaOS 文章里的 memory ,用于记录一些数据，在Buzz中memory被划分成两个分区，一个分区记录跟不同用户的聊天历史，一个分区记录一些web3的公共知识，不同的用户可以同时使用这部分知识。</li>
</ul>

<h2 id="2-完整流程">2. 完整流程</h2>

<h3 id="21-调用推特twitter-tool流程">2.1 调用推特Twitter Tool流程</h3>
<p>接下来我们来看下 Buzz的完整流程:
<img src="/assets/images/buzz-step-0.png" alt="buzz step 0" /></p>
<ol>
  <li>用户第一次登陆Buzz需要用钱包或者邮箱创建账号，原因是Buzz会生成你的userId,并根据userId在这个Agent的DB里给你创建一个对应的存储空间，存储跟你的聊天记录；当登陆完成之后，该用户发送
    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>RequestMessage1 {
message: "帮我查找关于 Swarms 在推特上的信息，并且帮我判断是否值得买入" 
}
</code></pre></div>    </div>
  </li>
  <li>用户的信息会被用实现准备好的Template组合成Content</li>
  <li>请求 LLM</li>
  <li>LLM发现该请求需要调用到对应的Tool, 于是会返回在回复的信息里返回对应的toolName</li>
  <li>通过Tool名字，从Tool注册表里获得对应的Tool实例；这里Tool在Buzz App启动的时候就会被提前注册进去，如下代码：<img src="/assets/images/buzz-register-tools.png" alt="buzz register tools" /></li>
  <li>调用Tool的执行函数，在buzz代码里，对应的执行函数如下，通过用户请求message里的keyword 调用twitter api查找对应的信息，并且把找到的信息返回<img src="/assets/images/buzz-fetch-x.png" alt="buzz fetch x" /></li>
  <li>获取执行结果</li>
  <li>把结果跟原来的 ResponseMessage2 组成</li>
  <li>把结果返回给用户
    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> fetchResult{
 message: Swarms 很值得购买！！！
 }
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="22-调用solona-tool流程">2.2 调用Solona Tool流程</h3>
<p>用户继续发送请求：</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> RequestMessage2 {
	 message:  帮我购买 1000 Sol 的 $Swarms 
 }
</code></pre></div></div>
<p><img src="/assets/images/buzz-step-1.png" alt="buzz step 1" /></p>
<ol>
  <li>用户的信息仍然会被用实现准备好的Template组合成Content</li>
  <li>请求 LLM</li>
  <li>LLM发现该请求需要调用到对应的Tool, 于是会返回在回复的信息里返回对应的toolName</li>
  <li>通过Tool名字，从Tool注册表里获得对应的Tool实例</li>
  <li>调用Tool的执行函数Swap(),会到solona链上执行对应的函数然后返回对应的执行结果</li>
  <li>获取对应的执行结果</li>
  <li>把执行结果嵌入在原来的Response Message里</li>
  <li>将完整的Response Message返回给用户
    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> ResponseMessage2 {
 message:  购买成功
 }
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="23-从知识库里获取知识流程">2.3 从知识库里获取知识流程</h3>
<p>用户继续把发送请求</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>RequestMessage3 {
	message: 帮我介绍下 Jupiter 的运行机制
</code></pre></div></div>

<p><img src="/assets/images/buzz-step-2.png" alt="buzz step 2" /></p>
<ol>
  <li>用户的信息仍然会被用实现准备好的Template组合成Content</li>
  <li>请求 LLM</li>
  <li>LLM发现该请求需要调用到对应的Tool, 于是会返回在回复的信息里返回对应的toolName</li>
  <li>通过Tool名字，从Tool注册表里获得对应的Tool实例</li>
  <li>调用 Tool 的执行函数FindKnowledge()，会从数据库寻找对应在Buzz 启动的时候预注入的web3知识</li>
  <li>获取对应的执行结果</li>
  <li>把执行结果嵌入在原来的Response Message里</li>
  <li>将完整的Response Message返回给用户
    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> ResponseMessage3:{
Message: Jupiter的运行机制如下：
...
...
... 
 }
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="24-buzz如何为每个用户开辟独立的存储区">2.4 Buzz如何为每个用户开辟独立的存储区</h3>
<p><img src="/assets/images/buzz-step-3.png" alt="buzz step 3" />
比如在上面的流程结束之后，用户退出了buzz app，那么Buzz会把这次聊天的内容按照如下处理：</p>
<ol>
  <li>用户第一次注册，为其该用户开辟专门的聊天分区</li>
  <li>调用 OPENAI 生成这次聊天的 Summary</li>
  <li>调用 OPENAI 把 Summary 转换成 Summary Vector</li>
  <li>把对应的数据以 Summary Vector 作为key 存储到CosmosDB里</li>
</ol>

<p>在下次用户下次登录的时候，CosmosDB会加载用户的历史数据，如果讨论的话题跟原来的记录有关会load这部分数据，从而创造独属于每个人的Web3 Agent。</p>

<h4 id="关于cosmosdb处理knowledge的细节">关于CosmosDB处理knowledge的细节</h4>
<ul>
  <li>这里我们来看看知识是怎么存储在CosmosDB数据库的：
调用时机：项目方在Buzz启动前提前存入的数据
存储流程:
    <ol>
      <li>根据给的请求Url爬取文档信息bn</li>
      <li>处理爬取结果</li>
      <li>请求openai ，让他对每个文档生成对应的summary</li>
      <li>通过open-ai模型将 summary 转化成 summary vector</li>
      <li>把  summary vector 作为key 把文档和summary一起存储到向量数据库cosmosDB中
```typescript
export const POST = async (req: NextRequest) =&gt; {
  // 1. 获取请求参数
  const { url, name, includePaths, excludePaths, authCode } = await req.json();</li>
    </ol>

    <p>// 2. 验证授权
  if(authCode !== process.env.CRAWL_AUTH_CODE) {
      return NextResponse.json({ error: “Unauthorized” }, { status: 401 });
  }</p>

    <p>// 3. 爬取文档
  const crawlResponse = await firecrawl.asyncCrawlUrl(url, {
      limit: 500,
      maxDepth: 10,
      includePaths,
      excludePaths
  });</p>

    <p>// 4. 处理爬取结果
  // …</p>

    <p>// 5. 对每个文档进行处理
  const knowledge = await Promise.all(docs.map(async (doc) =&gt; {
      if(!doc.markdown) {
          return;
      }
      // 生成摘要
      const { text: summary } = await generateText({
          model: openai(“gpt-4o-mini”),
          prompt: <code class="language-plaintext highlighter-rouge">Summarize the following documentation page in 1 sentence...</code>
      })</p>

    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>  // 生成向量嵌入
  const { embedding: summaryEmbedding } = await embed({
      model: openai.embedding("text-embedding-3-small"),
      value: summary
  })

  // 添加到知识库
  const knowledgeInputs: KnowledgeInput[] = [{
      baseUrl: url,
      name,
      url: doc.metadata?.url,
      title: doc.metadata?.title, 
      description: doc.metadata?.description,
      favicon: doc.metadata?.favicon,
      markdown: doc.markdown,
      summary,
      summaryEmbedding
  }];

  // 存储到数据库
  for await (const knowledgeInput of knowledgeInputs) {
      await addKnowledge(knowledgeInput);
  }
  return true;   })); } ```
</code></pre></div>    </div>
  </li>
  <li>从CosmosDB数据库中检索知识的流程：
调用时机： 用户的请求数据中触发
流程：
    <ol>
      <li>将查询短语进行向量化</li>
      <li>在数据库中查询跟这个向量距离最近的向量
<img src="/assets/images/buzz-search-knowledge.png" alt="buzz search knowledge" /></li>
    </ol>
  </li>
</ul>

<h2 id="3-最新的swarms升级">3. 最新的Swarms升级</h2>
<p>Agents在昨天把自己从单一Agent的架构，转换成Agents的架构，执行逻辑类似我之前写的Swarm的BossAgent的架构，具体可以参考我写的Swarm原理解析(二) https://x.com/hhh69251498/status/1876190960360870215
<img src="/assets/images/buzz-swarms-pic.png" alt="buzz swarm pic" />
Swarm的好处在于，不同的Agent可以专门处理任务的一部分，因此可以进行并行；同时可以跳出Content长度的限制。</p>

<p>而且也就如我写的 <a href="https://x.com/hhh69251498/status/1876496626908610873">Swarm架构</a>的文章里总结的 
<img src="/assets/images/swarms-arch.png" alt="swarms arch" />
Swarm Framework这一层其实需要管理不同的组件ShareMemory, WorkFlow和 OutputManager, TaskAssigner ，我们会发现当协调多个Agent共同工作的时候
我们需要考虑以下几个问题:</p>
<ol>
  <li>决定任务交给谁做 (TaskAssigner)</li>
  <li>怎么协调Agent参与工作的先后顺序 (WorkFlow)</li>
  <li>怎么管理任务执行之后产生的输出(Output Manager)</li>
  <li>异步执行的时候怎么传递一些状态给其他相关任务(ShareMemory)
而目前Buzz已经在OutputManager和TaskAssigner发力了，并且拥有很好的代码质量。
<img src="/assets/images/buzz-swarms.png" alt="buzz swarms" /></li>
</ol>

<h2 id="4-总结">4. 总结</h2>

<p>因此本质上来说：</p>
<ol>
  <li>Buzz没有采用任何 Agent Framework 来写自己的代码，核心原因是大多数 Agent Framework代码确实一般，而且本身Agent Framework 并不存在太强的护城河(API 封装)，更何况Buzz 的代码质量确实比 ElizaOS, zerebro 这些 Agent Framework 的代码质量强太多，目前在我看的 AI Agent里代码质量是最高的。</li>
  <li>Buzz的代码模块化得超级好，如果Buzz想做 Agent Framework，只需要把自己关于Agent的代码摘出来就行了，所以Agent Framework其实并不存在什么技术护城河；大家来看这一波真正起飞的Web3 Agent，会发现其实极少的项目去使用 Agent Framework. 而是自己写一套更适合自己业务的代码(也有可能是自己写的代码质量更好)</li>
  <li>Buzz通过预先的Web3知识导入实现了web3专属代理，但是还是期待这部分的工作可以转移到预训练的阶段来做。</li>
  <li>通过为每个用户在Agent里开辟自己的内存区域，并且在用户下一次开启聊天的时候加载这部分memory，实现为每个用户创造独属于自己的web3 agent</li>
  <li>是否能为每个用户启动一个自己的Agent，并且支持更好的定制化；这个很明显需要配合 1，以及通过多个Agents的协作让每个 Buzz 有能力根据用户的需求自动生成对应的tool.</li>
  <li>对于大多数复杂的场景来说，单一Agent受限于Content的长度限制，以及响应速度跟成本的考量无法很好的完成人类给予的任务，这一点我自己在写一个代码分析Agent时也遇到了(画图)，当仓库太大的时候，我们还是需要通过Swarm来处理。因为通过Swarm我们可以获得多个Agent并行处理任务，获得更大的Memory容量，以及跳出Content长度的限制等等，而且从人类社会发展史来看，协作一定是趋势。</li>
  <li>当然最终 作为一个 Web3 Agent, 最核心的还是 Buzz 产品本身的使用体验，希望Buzz继续快速迭代，给用户提供更多的功能以及放开每个用户的请求次数限制。</li>
  <li>Buzz目前的用户体验还不够好，还是会遇到类似的问题<img src="/assets/images/buzz-error.png" alt="buzz error" /></li>
  <li>另外一个很有趣的看法是，Agent发展路程一定是往Swarm去发展，但是人类中的超级个体却在通过Agent变得更加强大，强者越强，弱者越弱，比如 Buzz的代码(https://github.com/jasonhedman/the-hive)其实是solo写出来的，未来的人类路在何方呢？</li>
</ol>

<h2 id="5-代码细节">5. 代码细节</h2>
<h3 id="1-聊天内容存储到数据库的完整流程">1. 聊天内容存储到数据库的完整流程：</h3>

<ul>
  <li>聊天存储触发时机</li>
</ul>

<p>在 <code class="language-plaintext highlighter-rouge">ChatProvider</code> 中，当消息更新时会触发存储：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// app/(app)/chat/_contexts/chat.tsx</span>
<span class="kd">const</span> <span class="nx">ChatProvider</span> <span class="o">=</span> <span class="p">({</span> <span class="nx">children</span> <span class="p">})</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="c1">// 生成新的聊天ID</span>
    <span class="kd">const</span> <span class="p">[</span><span class="nx">chatId</span><span class="p">,</span> <span class="nx">setChatId</span><span class="p">]</span> <span class="o">=</span> <span class="nx">useState</span><span class="o">&lt;</span><span class="kr">string</span><span class="o">&gt;</span><span class="p">(</span><span class="nx">generateId</span><span class="p">());</span>
    
    <span class="c1">// 监听消息变化</span>
    <span class="nx">useEffect</span><span class="p">(()</span> <span class="o">=&gt;</span> <span class="p">{</span>
        <span class="kd">const</span> <span class="nx">updateChat</span> <span class="o">=</span> <span class="k">async</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="p">{</span>
            <span class="c1">// 只有当有消息且不在加载状态时才更新</span>
            <span class="k">if</span><span class="p">(</span><span class="nx">messages</span><span class="p">.</span><span class="nx">length</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="o">&amp;&amp;</span> <span class="o">!</span><span class="nx">isLoading</span><span class="p">)</span> <span class="p">{</span>
                <span class="kd">const</span> <span class="nx">response</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">fetch</span><span class="p">(</span><span class="s2">`/api/chats/</span><span class="p">${</span><span class="nx">chatId</span><span class="p">}</span><span class="s2">`</span><span class="p">,</span> <span class="p">{</span>
                    <span class="na">method</span><span class="p">:</span> <span class="dl">'</span><span class="s1">POST</span><span class="dl">'</span><span class="p">,</span>
                    <span class="na">headers</span><span class="p">:</span> <span class="p">{</span>
                        <span class="na">Authorization</span><span class="p">:</span> <span class="s2">`Bearer </span><span class="p">${</span><span class="k">await</span> <span class="nx">getAccessToken</span><span class="p">()}</span><span class="s2">`</span><span class="p">,</span>
                    <span class="p">},</span>
                    <span class="na">body</span><span class="p">:</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">({</span>
                        <span class="nx">messages</span><span class="p">,</span>
                    <span class="p">}),</span>
                <span class="p">});</span>
                <span class="kd">const</span> <span class="nx">data</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">response</span><span class="p">.</span><span class="nx">json</span><span class="p">();</span>
                <span class="k">if</span><span class="p">(</span><span class="k">typeof</span> <span class="nx">data</span> <span class="o">===</span> <span class="dl">'</span><span class="s1">object</span><span class="dl">'</span><span class="p">)</span> <span class="p">{</span>
                    <span class="nx">mutate</span><span class="p">();</span> <span class="c1">// 触发客户端缓存更新</span>
                <span class="p">}</span>
            <span class="p">}</span>
        <span class="p">};</span>

        <span class="nx">updateChat</span><span class="p">();</span>
    <span class="p">},</span> <span class="p">[</span><span class="nx">isLoading</span><span class="p">]);</span>
<span class="p">}</span>
</code></pre></div></div>

<ul>
  <li>API 路由处理</li>
</ul>

<p>在 <code class="language-plaintext highlighter-rouge">api/chats/[chatId]/route.ts</code> 中处理存储请求：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">const</span> <span class="nx">POST</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span><span class="nx">req</span><span class="p">:</span> <span class="nx">NextRequest</span><span class="p">,</span> <span class="p">{</span> <span class="nx">params</span> <span class="p">}:</span> <span class="p">{</span> <span class="nl">params</span><span class="p">:</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="p">{</span> <span class="na">chatId</span><span class="p">:</span> <span class="kr">string</span> <span class="p">}</span><span class="o">&gt;</span> <span class="p">})</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="kd">const</span> <span class="p">{</span> <span class="nx">chatId</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">params</span><span class="p">;</span>
    <span class="kd">const</span> <span class="p">{</span> <span class="nx">messages</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">req</span><span class="p">.</span><span class="nx">json</span><span class="p">();</span>

    <span class="k">try</span> <span class="p">{</span>
        <span class="c1">// 验证用户身份</span>
        <span class="kd">const</span> <span class="nx">authHeader</span> <span class="o">=</span> <span class="nx">req</span><span class="p">.</span><span class="nx">headers</span><span class="p">.</span><span class="kd">get</span><span class="p">(</span><span class="dl">"</span><span class="s2">authorization</span><span class="dl">"</span><span class="p">);</span>
        <span class="kd">const</span> <span class="nx">token</span> <span class="o">=</span> <span class="nx">authHeader</span><span class="p">?.</span><span class="nx">split</span><span class="p">(</span><span class="dl">"</span><span class="s2"> </span><span class="dl">"</span><span class="p">)[</span><span class="mi">1</span><span class="p">];</span>
        <span class="kd">const</span> <span class="p">{</span> <span class="nx">userId</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">privy</span><span class="p">.</span><span class="nx">verifyAuthToken</span><span class="p">(</span><span class="nx">token</span><span class="p">);</span>
        
        <span class="c1">// 获取已存在的聊天</span>
        <span class="kd">const</span> <span class="nx">chat</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">getChat</span><span class="p">(</span><span class="nx">chatId</span><span class="p">,</span> <span class="nx">userId</span><span class="p">);</span>
        
        <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="nx">chat</span><span class="p">)</span> <span class="p">{</span>
            <span class="c1">// 如果是新聊天，创建新记录</span>
            <span class="k">return</span> <span class="nx">NextResponse</span><span class="p">.</span><span class="nx">json</span><span class="p">(</span><span class="k">await</span> <span class="nx">addChat</span><span class="p">({</span>
                <span class="na">id</span><span class="p">:</span> <span class="nx">chatId</span><span class="p">,</span>
                <span class="nx">userId</span><span class="p">,</span>
                <span class="nx">messages</span><span class="p">,</span>
                <span class="c1">// 生成聊天标题</span>
                <span class="na">tagline</span><span class="p">:</span> <span class="k">await</span> <span class="nx">generateTagline</span><span class="p">(</span><span class="nx">messages</span><span class="p">),</span>
            <span class="p">}));</span>
        <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
            <span class="c1">// 如果聊天存在，更新消息</span>
            <span class="k">return</span> <span class="nx">NextResponse</span><span class="p">.</span><span class="nx">json</span><span class="p">(</span>
                <span class="k">await</span> <span class="nx">updateChatMessages</span><span class="p">(</span><span class="nx">chatId</span><span class="p">,</span> <span class="nx">userId</span><span class="p">,</span> <span class="nx">messages</span><span class="p">)</span>
            <span class="p">);</span>
        <span class="p">}</span>
    <span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span>
        <span class="nx">console</span><span class="p">.</span><span class="nx">error</span><span class="p">(</span><span class="dl">"</span><span class="s2">Error in /api/chats/[chatId]:</span><span class="dl">"</span><span class="p">,</span> <span class="nx">error</span><span class="p">);</span>
        <span class="k">return</span> <span class="nx">NextResponse</span><span class="p">.</span><span class="nx">json</span><span class="p">(</span><span class="kc">false</span><span class="p">,</span> <span class="p">{</span> <span class="na">status</span><span class="p">:</span> <span class="mi">500</span> <span class="p">});</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<ul>
  <li>数据库操作</li>
</ul>

<p>在 <code class="language-plaintext highlighter-rouge">db/services/chats.ts</code> 中定义了具体的数据库操作：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 添加新聊天</span>
<span class="k">export</span> <span class="kd">const</span> <span class="nx">addChat</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span><span class="nx">chat</span><span class="p">:</span> <span class="nx">Chat</span><span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">Chat</span> <span class="o">|</span> <span class="kc">null</span><span class="o">&gt;</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="k">return</span> <span class="nx">add</span><span class="o">&lt;</span><span class="nx">Chat</span><span class="p">,</span> <span class="nx">Chat</span><span class="o">&gt;</span><span class="p">(</span><span class="k">await</span> <span class="nx">getChatsContainer</span><span class="p">(),</span> <span class="nx">chat</span><span class="p">);</span>
<span class="p">};</span>

<span class="c1">// 更新聊天消息</span>
<span class="k">export</span> <span class="kd">const</span> <span class="nx">updateChatMessages</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span>
    <span class="nx">id</span><span class="p">:</span> <span class="nx">Chat</span><span class="p">[</span><span class="dl">"</span><span class="s2">id</span><span class="dl">"</span><span class="p">],</span> 
    <span class="nx">userId</span><span class="p">:</span> <span class="nx">Chat</span><span class="p">[</span><span class="dl">"</span><span class="s2">userId</span><span class="dl">"</span><span class="p">],</span> 
    <span class="nx">messages</span><span class="p">:</span> <span class="nx">Message</span><span class="p">[]</span>
<span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">boolean</span><span class="o">&gt;</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="k">return</span> <span class="nx">update</span><span class="p">(</span>
        <span class="k">await</span> <span class="nx">getChatsContainer</span><span class="p">(),</span>
        <span class="nx">id</span><span class="p">,</span>
        <span class="nx">userId</span><span class="p">,</span>
        <span class="p">[{</span> 
            <span class="na">op</span><span class="p">:</span> <span class="nx">PatchOperationType</span><span class="p">.</span><span class="kd">set</span><span class="p">,</span> 
            <span class="na">path</span><span class="p">:</span> <span class="s2">`/messages`</span><span class="p">,</span> 
            <span class="na">value</span><span class="p">:</span> <span class="nx">messages</span> 
        <span class="p">}]</span>
    <span class="p">);</span>
<span class="p">};</span>

<span class="c1">// 获取聊天记录</span>
<span class="k">export</span> <span class="kd">const</span> <span class="nx">getChat</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span>
    <span class="nx">id</span><span class="p">:</span> <span class="nx">Chat</span><span class="p">[</span><span class="dl">"</span><span class="s2">id</span><span class="dl">"</span><span class="p">],</span> 
    <span class="nx">userId</span><span class="p">:</span> <span class="nx">Chat</span><span class="p">[</span><span class="dl">"</span><span class="s2">userId</span><span class="dl">"</span><span class="p">]</span>
<span class="p">):</span> <span class="nb">Promise</span><span class="o">&lt;</span><span class="nx">Chat</span> <span class="o">|</span> <span class="kc">null</span><span class="o">&gt;</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kd">get</span><span class="p">(</span><span class="k">await</span> <span class="nx">getChatsContainer</span><span class="p">(),</span> <span class="nx">id</span><span class="p">,</span> <span class="nx">userId</span><span class="p">);</span>
<span class="p">};</span>
</code></pre></div></div>

<ul>
  <li>Cosmos DB 容器配置</li>
</ul>

<p>在 <code class="language-plaintext highlighter-rouge">db/containers/chats.ts</code> 中配置了聊天容器：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">const</span> <span class="nx">CHATS_CONTAINER_ID</span> <span class="o">=</span> <span class="dl">"</span><span class="s2">chats</span><span class="dl">"</span><span class="p">;</span>

<span class="kd">let</span> <span class="nx">chatsContainer</span><span class="p">:</span> <span class="nx">Container</span><span class="p">;</span>

<span class="k">export</span> <span class="kd">const</span> <span class="nx">getChatsContainer</span> <span class="o">=</span> <span class="k">async</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">chatsContainer</span><span class="p">)</span> <span class="p">{</span>
        <span class="nx">chatsContainer</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">getContainer</span><span class="o">&lt;</span><span class="nx">Chat</span><span class="o">&gt;</span><span class="p">(</span>
            <span class="nx">CHATS_CONTAINER_ID</span><span class="p">,</span> 
            <span class="dl">"</span><span class="s2">userId</span><span class="dl">"</span>  <span class="c1">// 使用 userId 作为分区键</span>
        <span class="p">);</span>
    <span class="p">}</span>
    <span class="k">return</span> <span class="nx">chatsContainer</span><span class="p">;</span>
<span class="p">};</span>
</code></pre></div></div>

<ul>
  <li>聊天数据类型定义</li>
</ul>

<p>在 <code class="language-plaintext highlighter-rouge">db/types/chat.ts</code> 中定义了数据结构：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">type</span> <span class="nx">Chat</span> <span class="o">=</span> <span class="p">{</span>
    <span class="na">id</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span>          <span class="c1">// 聊天ID</span>
    <span class="nl">messages</span><span class="p">:</span> <span class="nx">Message</span><span class="p">[];</span> <span class="c1">// 消息数组</span>
    <span class="nl">tagline</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span>    <span class="c1">// 聊天标题</span>
    <span class="nl">userId</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span>     <span class="c1">// 用户ID</span>
<span class="p">}</span>
</code></pre></div></div>

<ul>
  <li>标题生成</li>
</ul>

<p>为了更好的组织聊天记录，系统会自动生成标题：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">generateTagline</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span><span class="nx">messages</span><span class="p">:</span> <span class="nx">Message</span><span class="p">[])</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="kd">const</span> <span class="p">{</span> <span class="nx">text</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">generateText</span><span class="p">({</span>
        <span class="na">model</span><span class="p">:</span> <span class="nx">openai</span><span class="p">(</span><span class="dl">"</span><span class="s2">gpt-4o-mini</span><span class="dl">"</span><span class="p">),</span>
        <span class="na">messages</span><span class="p">:</span> <span class="p">[</span>
            <span class="nx">messages</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span>
            <span class="p">{</span>
                <span class="na">role</span><span class="p">:</span> <span class="dl">"</span><span class="s2">user</span><span class="dl">"</span><span class="p">,</span>
                <span class="na">content</span><span class="p">:</span> <span class="dl">"</span><span class="s2">Generate a 3-5 word description of the chat...</span><span class="dl">"</span>
            <span class="p">},</span>
        <span class="p">],</span>
    <span class="p">});</span>

    <span class="k">return</span> <span class="nx">text</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<p>这个完整的流程确保了：</p>
<ol>
  <li>聊天内容实时保存</li>
  <li>用户身份验证</li>
  <li>数据安全性</li>
  <li>聊天检索和组织</li>
  <li>错误处理和恢复</li>
</ol>

<p>使得用户可以在任何时候恢复之前的对话，并保持聊天历史的完整性。</p>

<h3 id="2-对于-knowledge的处理则是按照以下流程处理">2. 对于 Knowledge的处理，则是按照以下流程处理</h3>
<p>SearchKnowledgeAction 是在 AI 需要检索特定协议或概念的详细信息时被调用的。让我分析其调用流程：</p>

<ol>
  <li><strong>定义和注册</strong>:
    <div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// knowledge/actions/search-knowledge/function.ts</span>
<span class="k">export</span> <span class="kd">const</span> <span class="nx">searchKnowledgeFunction</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span><span class="nx">args</span><span class="p">:</span> <span class="nx">SearchKnowledgeArgumentsType</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
 <span class="kd">const</span> <span class="nx">knowledge</span> <span class="o">=</span> <span class="k">await</span> <span class="nb">Promise</span><span class="p">.</span><span class="nx">all</span><span class="p">(</span><span class="nx">args</span><span class="p">.</span><span class="nx">queryPhrases</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="k">async</span> <span class="p">(</span><span class="nx">phrase</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
     <span class="c1">// 转换查询为向量</span>
     <span class="kd">const</span> <span class="p">{</span> <span class="nx">embedding</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">embed</span><span class="p">({</span>
         <span class="na">model</span><span class="p">:</span> <span class="nx">openai</span><span class="p">.</span><span class="nx">embedding</span><span class="p">(</span><span class="dl">"</span><span class="s2">text-embedding-3-small</span><span class="dl">"</span><span class="p">),</span>
         <span class="na">value</span><span class="p">:</span> <span class="nx">phrase</span><span class="p">,</span>
     <span class="p">});</span>

     <span class="c1">// 在知识库中搜索</span>
     <span class="k">return</span> <span class="k">await</span> <span class="nx">findRelevantKnowledge</span><span class="p">(</span><span class="nx">embedding</span><span class="p">);</span>
 <span class="p">}));</span>

 <span class="k">return</span> <span class="p">{</span>
     <span class="na">message</span><span class="p">:</span> <span class="dl">"</span><span class="s2">Knowledge search successful...</span><span class="dl">"</span><span class="p">,</span>
     <span class="na">body</span><span class="p">:</span> <span class="p">{</span>
         <span class="na">knowledge</span><span class="p">:</span> <span class="nx">knowledge</span><span class="p">.</span><span class="nx">flat</span><span class="p">(),</span>
     <span class="p">},</span>
 <span class="p">};</span>
<span class="p">};</span>
</code></pre></div>    </div>
  </li>
  <li><strong>调用场景</strong>:
当用户询问：
    <ul>
      <li>特定协议的工作原理（如”Jupiter 交易聚合是如何工作的？”）</li>
      <li>具体概念的解释（如”什么是 SOL 质押？”）</li>
      <li>技术细节（如”如何使用 Lulo 借贷？”）</li>
    </ul>
  </li>
  <li><strong>实际调用过程</strong>:
    <div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// api/chat/solana/route.ts</span>
<span class="kd">const</span> <span class="nx">stream</span> <span class="o">=</span> <span class="nx">streamText</span><span class="p">({</span>
 <span class="nx">model</span><span class="p">,</span>
 <span class="na">tools</span><span class="p">:</span> <span class="p">{</span>
     <span class="p">...</span><span class="nx">solanaTools</span><span class="p">(</span><span class="nx">connection</span><span class="p">),</span>
     <span class="p">...</span><span class="nx">twitterTools</span><span class="p">(</span><span class="nx">twitterApi</span><span class="p">),</span>
     <span class="c1">// 注册知识搜索工具</span>
     <span class="p">...</span><span class="nx">knowledgeTools</span><span class="p">()</span>
 <span class="p">},</span>
 <span class="nx">messages</span><span class="p">,</span>
 <span class="c1">// 系统提示会指导 AI 在需要详细协议知识时使用此工具</span>
 <span class="na">system</span><span class="p">:</span> <span class="dl">"</span><span class="s2">You are a swarm of helpful blockchain agents...</span><span class="dl">"</span>
<span class="p">});</span>
</code></pre></div>    </div>
  </li>
  <li><strong>使用示例</strong>:
用户: “解释下 Jupiter 的 DEX 聚合器是如何工作的？”</li>
</ol>

<p>AI 会：</p>
<ol>
  <li>识别需要协议知识</li>
  <li>调用 SearchKnowledgeAction：
    <div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span>
 <span class="nl">toolName</span><span class="p">:</span> <span class="dl">"</span><span class="s2">search-knowledge</span><span class="dl">"</span><span class="p">,</span>
 <span class="nx">args</span><span class="p">:</span> <span class="p">{</span>
     <span class="nl">queryPhrases</span><span class="p">:</span> <span class="p">[</span><span class="dl">"</span><span class="s2">Jupiter DEX aggregator working mechanism</span><span class="dl">"</span><span class="p">]</span>
 <span class="p">}</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
  <li><strong>返回结果处理</strong>:
    <div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// knowledge/actions/search-knowledge/search-knowledge.tsx</span>
<span class="kd">const</span> <span class="nx">SearchKnowledge</span><span class="p">:</span> <span class="nx">React</span><span class="p">.</span><span class="nx">FC</span><span class="o">&lt;</span><span class="nx">Props</span><span class="o">&gt;</span> <span class="o">=</span> <span class="p">({</span> <span class="nx">tool</span> <span class="p">})</span> <span class="o">=&gt;</span> <span class="p">{</span>
 <span class="k">return</span> <span class="p">(</span>
     <span class="o">&lt;</span><span class="nx">ToolCard</span> 
         <span class="nx">tool</span><span class="o">=</span><span class="p">{</span><span class="nx">tool</span><span class="p">}</span>
         <span class="nx">agentName</span><span class="o">=</span><span class="dl">"</span><span class="s2">Knowledge Agent</span><span class="dl">"</span>
         <span class="nx">icon</span><span class="o">=</span><span class="dl">"</span><span class="s2">Brain</span><span class="dl">"</span>
         <span class="nx">loadingText</span><span class="o">=</span><span class="p">{</span><span class="s2">`Searching Knowledge...`</span><span class="p">}</span>
         <span class="nx">resultHeading</span><span class="o">=</span><span class="p">{(</span><span class="nx">result</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="s2">`Searched knowledge base`</span><span class="p">}</span>
         <span class="nx">resultBody</span><span class="o">=</span><span class="p">{(</span><span class="nx">result</span><span class="p">)</span> <span class="o">=&gt;</span> 
             <span class="s2">`Included the top </span><span class="p">${</span><span class="nx">result</span><span class="p">.</span><span class="nx">body</span><span class="p">.</span><span class="nx">knowledge</span><span class="p">.</span><span class="nx">length</span><span class="p">}</span><span class="s2"> pages in context.`</span>
         <span class="p">}</span>
         <span class="nx">defaultOpen</span><span class="o">=</span><span class="p">{</span><span class="kc">false</span><span class="p">}</span>
     <span class="sr">/</span><span class="err">&gt;
</span> <span class="p">)</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
  <li><strong>知识使用</strong>:
AI 会利用搜索到的知识来提供准确的回答：
    <ul>
      <li>整合多个文档的信息</li>
      <li>提供具体的技术细节</li>
      <li>引用官方文档的说明</li>
    </ul>
  </li>
  <li>但是还有一个问题是知识是什么时候被存储进去的
<code class="language-plaintext highlighter-rouge">crawl-docs</code> API 是一个用于抓取文档内容并将其添加到知识库的端点。这个端点不是在普通用户对话过程中调用的，而是在系统初始化或更新文档时由管理员主动调用的。</li>
</ol>

<p>让我们看看它的具体实现：</p>

<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">const</span> <span class="nx">POST</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span><span class="nx">req</span><span class="p">:</span> <span class="nx">NextRequest</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
    <span class="c1">// 1. 获取请求参数</span>
    <span class="kd">const</span> <span class="p">{</span> <span class="nx">url</span><span class="p">,</span> <span class="nx">name</span><span class="p">,</span> <span class="nx">includePaths</span><span class="p">,</span> <span class="nx">excludePaths</span><span class="p">,</span> <span class="nx">authCode</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">req</span><span class="p">.</span><span class="nx">json</span><span class="p">();</span>

    <span class="c1">// 2. 验证授权</span>
    <span class="k">if</span><span class="p">(</span><span class="nx">authCode</span> <span class="o">!==</span> <span class="nx">process</span><span class="p">.</span><span class="nx">env</span><span class="p">.</span><span class="nx">CRAWL_AUTH_CODE</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">return</span> <span class="nx">NextResponse</span><span class="p">.</span><span class="nx">json</span><span class="p">({</span> <span class="na">error</span><span class="p">:</span> <span class="dl">"</span><span class="s2">Unauthorized</span><span class="dl">"</span> <span class="p">},</span> <span class="p">{</span> <span class="na">status</span><span class="p">:</span> <span class="mi">401</span> <span class="p">});</span>
    <span class="p">}</span>

    <span class="c1">// 3. 爬取文档</span>
    <span class="kd">const</span> <span class="nx">crawlResponse</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">firecrawl</span><span class="p">.</span><span class="nx">asyncCrawlUrl</span><span class="p">(</span><span class="nx">url</span><span class="p">,</span> <span class="p">{</span>
        <span class="na">limit</span><span class="p">:</span> <span class="mi">500</span><span class="p">,</span>
        <span class="na">maxDepth</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span>
        <span class="nx">includePaths</span><span class="p">,</span>
        <span class="nx">excludePaths</span>
    <span class="p">});</span>

    <span class="c1">// 4. 处理爬取结果</span>
    <span class="c1">// ...</span>

    <span class="c1">// 5. 对每个文档进行处理</span>
    <span class="kd">const</span> <span class="nx">knowledge</span> <span class="o">=</span> <span class="k">await</span> <span class="nb">Promise</span><span class="p">.</span><span class="nx">all</span><span class="p">(</span><span class="nx">docs</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="k">async</span> <span class="p">(</span><span class="nx">doc</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
        <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="nx">doc</span><span class="p">.</span><span class="nx">markdown</span><span class="p">)</span> <span class="p">{</span>
            <span class="k">return</span><span class="p">;</span>
        <span class="p">}</span>
        <span class="c1">// 生成摘要</span>
        <span class="kd">const</span> <span class="p">{</span> <span class="na">text</span><span class="p">:</span> <span class="nx">summary</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">generateText</span><span class="p">({</span>
            <span class="na">model</span><span class="p">:</span> <span class="nx">openai</span><span class="p">(</span><span class="dl">"</span><span class="s2">gpt-4o-mini</span><span class="dl">"</span><span class="p">),</span>
            <span class="na">prompt</span><span class="p">:</span> <span class="s2">`Summarize the following documentation page in 1 sentence...`</span>
        <span class="p">})</span>
        
        <span class="c1">// 生成向量嵌入</span>
        <span class="kd">const</span> <span class="p">{</span> <span class="na">embedding</span><span class="p">:</span> <span class="nx">summaryEmbedding</span> <span class="p">}</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">embed</span><span class="p">({</span>
            <span class="na">model</span><span class="p">:</span> <span class="nx">openai</span><span class="p">.</span><span class="nx">embedding</span><span class="p">(</span><span class="dl">"</span><span class="s2">text-embedding-3-small</span><span class="dl">"</span><span class="p">),</span>
            <span class="na">value</span><span class="p">:</span> <span class="nx">summary</span>
        <span class="p">})</span>

        <span class="c1">// 添加到知识库</span>
        <span class="kd">const</span> <span class="na">knowledgeInputs</span><span class="p">:</span> <span class="nx">KnowledgeInput</span><span class="p">[]</span> <span class="o">=</span> <span class="p">[{</span>
            <span class="na">baseUrl</span><span class="p">:</span> <span class="nx">url</span><span class="p">,</span>
            <span class="nx">name</span><span class="p">,</span>
            <span class="na">url</span><span class="p">:</span> <span class="nx">doc</span><span class="p">.</span><span class="nx">metadata</span><span class="p">?.</span><span class="nx">url</span><span class="p">,</span>
            <span class="na">title</span><span class="p">:</span> <span class="nx">doc</span><span class="p">.</span><span class="nx">metadata</span><span class="p">?.</span><span class="nx">title</span><span class="p">,</span> 
            <span class="na">description</span><span class="p">:</span> <span class="nx">doc</span><span class="p">.</span><span class="nx">metadata</span><span class="p">?.</span><span class="nx">description</span><span class="p">,</span>
            <span class="na">favicon</span><span class="p">:</span> <span class="nx">doc</span><span class="p">.</span><span class="nx">metadata</span><span class="p">?.</span><span class="nx">favicon</span><span class="p">,</span>
            <span class="na">markdown</span><span class="p">:</span> <span class="nx">doc</span><span class="p">.</span><span class="nx">markdown</span><span class="p">,</span>
            <span class="nx">summary</span><span class="p">,</span>
            <span class="nx">summaryEmbedding</span>
        <span class="p">}];</span>

        <span class="c1">// 存储到数据库</span>
        <span class="k">for</span> <span class="k">await</span> <span class="p">(</span><span class="kd">const</span> <span class="nx">knowledgeInput</span> <span class="k">of</span> <span class="nx">knowledgeInputs</span><span class="p">)</span> <span class="p">{</span>
            <span class="k">await</span> <span class="nx">addKnowledge</span><span class="p">(</span><span class="nx">knowledgeInput</span><span class="p">);</span>
        <span class="p">}</span>
        <span class="k">return</span> <span class="kc">true</span><span class="p">;</span>
    <span class="p">}));</span>
<span class="p">}</span>
</code></pre></div></div>

<p>这个 API 的主要使用场景是：</p>
<ol>
  <li><strong>初始化知识库</strong>：
    <ul>
      <li>当系统首次部署时</li>
      <li>当需要添加新的协议或项目文档时</li>
    </ul>
  </li>
  <li><strong>更新文档</strong>：
    <ul>
      <li>当文档内容有重大更新时</li>
      <li>当需要添加新的文档章节时</li>
    </ul>
  </li>
  <li><strong>维护知识库</strong>：
    <ul>
      <li>定期更新现有文档</li>
      <li>添加新的文档来源
可以看到 <code class="language-plaintext highlighter-rouge">SEARCH_KNOWLEDGE_PROMPT</code> 中提到的文档范围：
```typescript
export const SEARCH_KNOWLEDGE_PROMPT = 
`This tool searches a vector database that is filled with information about blockchain protocols and concepts.</li>
    </ul>
  </li>
</ol>

<p>Documents cover:</p>
<ul>
  <li>Solana docs</li>
  <li>Jupiter docs and guides</li>
  <li>Raydium docs</li>
  <li>DexScreener docs</li>
  <li>Meteora docs</li>
  <li>Orca docs</li>
  <li>Jito docs</li>
  <li>Kamino docs</li>
  <li>Lulo docs<code class="language-plaintext highlighter-rouge">
</code>``</li>
</ul>

<p>这些文档都是通过 <code class="language-plaintext highlighter-rouge">crawl-docs</code> API 预先抓取并存储的，这样当用户在对话中询问相关问题时，AI 就可以通过 <code class="language-plaintext highlighter-rouge">search-knowledge</code> action 快速检索相关信息。
使用方式示例：</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl <span class="nt">-X</span> POST http://your-api/api/crawl-docs <span class="se">\</span>
  <span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
  <span class="nt">-d</span> <span class="s1">'{
    "url": "https://docs.jupiter.xyz",
    "name": "Jupiter Documentation",
    "includePaths": ["/docs"],
    "excludePaths": ["/blog"],
    "authCode": "your-auth-code"
  }'</span>
</code></pre></div></div>
<p>这种设计允许系统维护一个高质量的知识库，同时确保只有授权用户才能更新文档内容。当用户在对话中需要这些信息时，AI 可以快速准确地提供相关答案。
总之，SearchKnowledgeAction 是 AI 的知识增强工具，使其能够提供准确、最新的协议信息。它在 AI 需要深入的技术细节或具体实现说明时自动被调用。</p>]]></content><author><name></name></author><category term="web3" /><category term="agent" /><category term="ai" /><category term="blockchain" /><category term="buzz" /><summary type="html"><![CDATA[]]></summary></entry><entry><title type="html">Swarms 架构</title><link href="/2025/01/13/swarms-architecture/" rel="alternate" type="text/html" title="Swarms 架构" /><published>2025-01-13T02:03:00+00:00</published><updated>2025-01-13T02:03:00+00:00</updated><id>/2025/01/13/swarms-architecture</id><content type="html" xml:base="/2025/01/13/swarms-architecture/"><![CDATA[<p><img src="/assets/images/swarms_arch.png" alt="" /></p>
<ul>
  <li>Swarms的Agent的设计该有的功能都有，也就是跟ElizaOs一样都支持了Memory,Tool,LLM,Evaluator, 同时Tool的设计上也都是采用对应了对应的注册表的方式</li>
  <li>在Agent之上是对应的Swarm Framework,用于协调多个Agent之间的工作</li>
  <li>目前Swarms已经实现的Swarm Framework有：
      - MajorityVoting，相当于多个不同的Agent同时执行一个task,最后会通过投票的方式选择一个最佳答案进行回复，最多得票数的回复会被采用；其实也很想区块链的Pos共识机制，挺有趣的
      - AgentRearrange，是一个很灵活的Swarm框架，比如我们现在有三个不同的Agent A,B,C,D ; 然后假设有一个任务希望 按照 task -&gt; A -&gt; B -&gt; C -&gt; D的方式被处理，即A先处理这个任务然后交给B处理再给C处理接着给D处理，那么我们只需要在WorkFlow里这么定义 workflow = “ A -&gt; B -&gt; C -&gt; D”, 然后初始化这个AgentRearrange并且运行，如下所示：
      <code class="language-plaintext highlighter-rouge">
      AgentRearrange(agents = [A,B,C,D],workflow = " A -&gt; B -&gt; C -&gt; D").run(task)
     </code>
          我们就可以拿到按照我们规定的工作方式最后产生的结果
       - 同时如果我们把WorkFlow定义成 A -&gt; B,C -&gt; D，那么A执行task之后，B、C会同时执行任务，最后D再执行任务，所以这是一个可以通过WorkFlow实现灵活定义整个工作流的Swarm模式
       - GraphFlow，则相比AgentRearrange还有支持更复杂的工作流关系，可以任意设计整个工作流的之间的依赖关系
       - GroupChat 则是让多个Agent进行多轮对话，最终通过多轮对话不断完善要完成的任务内容，从而让结果更可靠更详尽
       - - MixtureOfAgents 则是多个Agent同时工作，最后有一个Agent负责总结所有的工作，并产生最终的输出
      - RoundRobin则是通过轮询的方式让每个Agent平等的参加工作
       - ForestSwarm则是可以支持多个层级的Agent关系，所以就想树有很多枝干一样，ForestSwarm就是一个巨大的Agent节点构成的网络，因为起名叫做森林
       - 还有MultiAgentRouter也是我们介绍过的BossAgent
       - ConcurrentWorkflow，支持多个AI Agent同时执行同一个任务
       - AsyncWorkflow， 多个AI Agent异步执行任务，因此这里需要用到ShareMemory来记录任务产生的数据，同时还有复杂的SpeakSystem
    <ul>
      <li>所以Swarm Framework这一层其实需要管理不同的组件，ShareMemory, WorkFlow和 OutputManager, TaskAssigner ，因为总结上面这些不同的Swarm Model，我们会发现当我们想协调多个Agent共同工作的时候我们需要考虑以下几个问题:
    1. 决定任务交给谁做 (TaskAssigner)
    2. 怎么协调Agent参与工作的先后顺序 (WorkFlow)
    3. 怎么管理任务执行之后产生的输出(Output Manager)
    4. 异步执行的时候怎么传递一些状态给其他相关任务(ShareMemory)</li>
      <li>Swarm再上层就是Swarms Framework了，用于协调多个Swarm之间的工作，目前主要支持两种
        <ul>
          <li>SwarmRouter
            <ul>
              <li>通过 「Word Vector」比较的方式选择最合适的Swarm Model进行执行task</li>
            </ul>
          </li>
          <li>SwarmRearrange
            <ul>
              <li>也可以通过类似定义 workflow 的方式，直接协调多个 Swarm 进行工作</li>
            </ul>
          </li>
        </ul>
      </li>
    </ul>
  </li>
  <li>最后我想再强调一下一个Agent是可以在不同的Swarm下直接工作的，所以这里所有的Agent都会由AgentRegistry进行管理，从而能在不同Swarm下尽可能多的复用。</li>
</ul>

<p>最终Swarms产生的结果就是，任何Agent协作场景你都能在Swarms上找到开箱即用的协作方式，而即便是更复杂的场景也可以通过不同Swarms之间的配合来实现，因此相比ElizaOS而言，我觉得Swarms对Agent 领域的贡献要大得多，当然现在的代码还不是完美状态，但是很明显随着越来越多开发者来到Swarms生态我们可以一起把这些很前沿的代码Build到最好</p>

<p>目前Swarms生态也开始起来，我觉得会爆发出巨大的力量，就比如 Swarms 生态的龙一MCS 的核心代码不过百来行，核心是通过 AgentRearrange的Swarm Model协调四个agent之间的工作，而且当时Kye搞MCS核心的目的就是想证明Swarms行！</p>
<ol>
  <li>核心架构与Agent：
主要Agent：
    <ul>
      <li>首席医疗官(Chief Medical Officer)：协调整个团队，收集症状，形成鉴别诊断</li>
      <li>医疗编码员(Medical Coder)：分配 ICD-10 代码，确保编码合规</li>
      <li>诊断合成器(Synthesizer)：整合所有发现生成最终诊断评估</li>
      <li>治疗智能体(Treatment Agent)：根据效果和成本推荐治疗方案</li>
      <li>实验室匹配器(Lab Matcher)：匹配诊断与实验室检查，提供参考范围
定义Workflow: <code class="language-plaintext highlighter-rouge">首席医疗官 -&gt; 医疗编码员 -&gt; 诊断合成器 -&gt; 治疗智能体</code></li>
    </ul>
  </li>
  <li>协调机制：
并通过上面介绍的AgentRearrange 方式来实现协调多个Agent工作</li>
  <li>工作流程
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">task</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
 <span class="c1"># 1. 准备任务信息
</span> <span class="n">case_info</span> <span class="o">=</span> <span class="p">{</span>
     <span class="s">"patient_id"</span><span class="p">:</span> <span class="bp">self</span><span class="p">.</span><span class="n">patient_id</span><span class="p">,</span>
     <span class="s">"timestamp"</span><span class="p">:</span> <span class="n">datetime</span><span class="p">.</span><span class="n">now</span><span class="p">(),</span>
     <span class="s">"patient_documentation"</span><span class="p">:</span> <span class="bp">self</span><span class="p">.</span><span class="n">patient_documentation</span><span class="p">,</span>
     <span class="s">"task"</span><span class="p">:</span> <span class="n">task</span>
 <span class="p">}</span>
    
 <span class="c1"># 2. 加密任务信息
</span> <span class="n">encrypted_case</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">secure_handler</span><span class="p">.</span><span class="n">encrypt_data</span><span class="p">(</span><span class="n">case_info</span><span class="p">)</span>
    
 <span class="c1"># 3. 解密用于处理
</span> <span class="n">decrypted_case</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">secure_handler</span><span class="p">.</span><span class="n">decrypt_data</span><span class="p">(</span><span class="n">encrypted_case</span><span class="p">)</span>
    
 <span class="c1"># 4. 执行智能体流程
</span> <span class="n">output</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">diagnosis_system</span><span class="p">.</span><span class="n">run</span><span class="p">(</span><span class="n">decrypted_case</span><span class="p">)</span>
    
 <span class="c1"># 5. 加密输出结果
</span> <span class="n">encrypted_output</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">secure_handler</span><span class="p">.</span><span class="n">encrypt_data</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
    
 <span class="c1"># 6. 解密输出供内部使用
</span> <span class="n">decrypted_output</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">secure_handler</span><span class="p">.</span><span class="n">decrypt_data</span><span class="p">(</span><span class="n">encrypted_output</span><span class="p">)</span>
    
 <span class="c1"># 7. 保存病人数据
</span> <span class="bp">self</span><span class="p">.</span><span class="n">save_patient_data</span><span class="p">(</span><span class="bp">self</span><span class="p">.</span><span class="n">patient_id</span><span class="p">,</span> <span class="n">encrypted_output</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
</ol>

<p>同时每轮执行前会从数据库中拿取该任务所需要的对应数据</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">MedicalCoderSwarm</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">memory_query</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">task</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
        <span class="k">if</span> <span class="bp">self</span><span class="p">.</span><span class="n">long_term_memory</span><span class="p">:</span>
            <span class="c1"># 在记忆库中查询相关信息
</span>            <span class="n">memory_retrieval</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">long_term_memory</span><span class="p">.</span><span class="n">query</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>
            
            <span class="c1"># 添加到短期记忆
</span>            <span class="bp">self</span><span class="p">.</span><span class="n">short_memory</span><span class="p">.</span><span class="n">add</span><span class="p">(</span>
                <span class="n">role</span><span class="o">=</span><span class="s">"Database"</span><span class="p">,</span>
                <span class="n">content</span><span class="o">=</span><span class="sa">f</span><span class="s">"Documents Available: </span><span class="si">{</span><span class="n">memory_retrieval</span><span class="si">}</span><span class="s">"</span>
            <span class="p">)</span>

    <span class="k">def</span> <span class="nf">_run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">task</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
        <span class="c1"># 每轮执行前查询知识库
</span>        <span class="k">if</span> <span class="bp">self</span><span class="p">.</span><span class="n">rag_every_loop</span><span class="p">:</span>
            <span class="bp">self</span><span class="p">.</span><span class="n">memory_query</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>
            
        <span class="c1"># 执行智能体流程
</span>        <span class="n">response</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">diagnosis_system</span><span class="p">.</span><span class="n">run</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>
</code></pre></div></div>]]></content><author><name></name></author><category term="swarms" /><category term="ai" /><category term="agent" /><category term="swarms" /><category term="analysis" /><category term="architecture" /><summary type="html"><![CDATA[Swarms的Agent的设计该有的功能都有，也就是跟ElizaOs一样都支持了Memory,Tool,LLM,Evaluator, 同时Tool的设计上也都是采用对应了对应的注册表的方式 在Agent之上是对应的Swarm Framework,用于协调多个Agent之间的工作 目前Swarms已经实现的Swarm Framework有： - MajorityVoting，相当于多个不同的Agent同时执行一个task,最后会通过投票的方式选择一个最佳答案进行回复，最多得票数的回复会被采用；其实也很想区块链的Pos共识机制，挺有趣的 - AgentRearrange，是一个很灵活的Swarm框架，比如我们现在有三个不同的Agent A,B,C,D ; 然后假设有一个任务希望 按照 task -&gt; A -&gt; B -&gt; C -&gt; D的方式被处理，即A先处理这个任务然后交给B处理再给C处理接着给D处理，那么我们只需要在WorkFlow里这么定义 workflow = “ A -&gt; B -&gt; C -&gt; D”, 然后初始化这个AgentRearrange并且运行，如下所示： AgentRearrange(agents = [A,B,C,D],workflow = " A -&gt; B -&gt; C -&gt; D").run(task) 我们就可以拿到按照我们规定的工作方式最后产生的结果 - 同时如果我们把WorkFlow定义成 A -&gt; B,C -&gt; D，那么A执行task之后，B、C会同时执行任务，最后D再执行任务，所以这是一个可以通过WorkFlow实现灵活定义整个工作流的Swarm模式 - GraphFlow，则相比AgentRearrange还有支持更复杂的工作流关系，可以任意设计整个工作流的之间的依赖关系 - GroupChat 则是让多个Agent进行多轮对话，最终通过多轮对话不断完善要完成的任务内容，从而让结果更可靠更详尽 - - MixtureOfAgents 则是多个Agent同时工作，最后有一个Agent负责总结所有的工作，并产生最终的输出 - RoundRobin则是通过轮询的方式让每个Agent平等的参加工作 - ForestSwarm则是可以支持多个层级的Agent关系，所以就想树有很多枝干一样，ForestSwarm就是一个巨大的Agent节点构成的网络，因为起名叫做森林 - 还有MultiAgentRouter也是我们介绍过的BossAgent - ConcurrentWorkflow，支持多个AI Agent同时执行同一个任务 - AsyncWorkflow， 多个AI Agent异步执行任务，因此这里需要用到ShareMemory来记录任务产生的数据，同时还有复杂的SpeakSystem 所以Swarm Framework这一层其实需要管理不同的组件，ShareMemory, WorkFlow和 OutputManager, TaskAssigner ，因为总结上面这些不同的Swarm Model，我们会发现当我们想协调多个Agent共同工作的时候我们需要考虑以下几个问题: 1. 决定任务交给谁做 (TaskAssigner) 2. 怎么协调Agent参与工作的先后顺序 (WorkFlow) 3. 怎么管理任务执行之后产生的输出(Output Manager) 4. 异步执行的时候怎么传递一些状态给其他相关任务(ShareMemory) Swarm再上层就是Swarms Framework了，用于协调多个Swarm之间的工作，目前主要支持两种 SwarmRouter 通过 「Word Vector」比较的方式选择最合适的Swarm Model进行执行task SwarmRearrange 也可以通过类似定义 workflow 的方式，直接协调多个 Swarm 进行工作 最后我想再强调一下一个Agent是可以在不同的Swarm下直接工作的，所以这里所有的Agent都会由AgentRegistry进行管理，从而能在不同Swarm下尽可能多的复用。]]></summary></entry><entry><title type="html">Swarms Analysis (三)</title><link href="/2025/01/12/swarms-analysis-3/" rel="alternate" type="text/html" title="Swarms Analysis (三)" /><published>2025-01-12T02:02:00+00:00</published><updated>2025-01-12T02:02:00+00:00</updated><id>/2025/01/12/swarms-analysis-3</id><content type="html" xml:base="/2025/01/12/swarms-analysis-3/"><![CDATA[<p>这篇文章讲介绍 #SWARMS 框架里最好用的两个东西，一个用于调度多个Agent的Swarm框架</p>

<h2 id="agentrearrange">AgentRearrange</h2>
<p>AgentRearrange 的核心机制：</p>
<ol>
  <li>Agent 任务分配机制：
    <ul>
      <li>AgentRearrange 主要通过 <code class="language-plaintext highlighter-rouge">_run</code> 方法处理任务分配，核心逻辑如下：</li>
    </ul>
  </li>
</ol>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># 1. 并行处理多个 Agent
</span><span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">agent_names</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
    <span class="c1"># 多个 Agent 并行执行
</span>    <span class="n">results</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">for</span> <span class="n">agent_name</span> <span class="ow">in</span> <span class="n">agent_names</span><span class="p">:</span>
        <span class="n">agent</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">agents</span><span class="p">[</span><span class="n">agent_name</span><span class="p">]</span>
        <span class="n">result</span> <span class="o">=</span> <span class="n">agent</span><span class="p">.</span><span class="n">run</span><span class="p">(</span>
            <span class="n">task</span><span class="o">=</span><span class="n">task_with_context</span><span class="p">,</span>
            <span class="n">img</span><span class="o">=</span><span class="n">img</span><span class="p">,</span> 
            <span class="n">is_last</span><span class="o">=</span><span class="n">is_last</span>
        <span class="p">)</span>
        <span class="n">results</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
    <span class="n">current_task</span> <span class="o">=</span> <span class="s">"; "</span><span class="p">.</span><span class="n">join</span><span class="p">(</span><span class="n">results</span><span class="p">)</span> <span class="c1"># 合并结果
</span>
<span class="c1"># 2. 顺序处理单个 Agent
</span><span class="k">else</span><span class="p">:</span>
    <span class="n">agent_name</span> <span class="o">=</span> <span class="n">agent_names</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
    <span class="n">agent</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">agents</span><span class="p">[</span><span class="n">agent_name</span><span class="p">]</span>
    <span class="n">current_task</span> <span class="o">=</span> <span class="n">agent</span><span class="p">.</span><span class="n">run</span><span class="p">(</span>
        <span class="n">task</span><span class="o">=</span><span class="n">task_with_context</span><span class="p">,</span>
        <span class="n">img</span><span class="o">=</span><span class="n">img</span><span class="p">,</span>
        <span class="n">is_last</span><span class="o">=</span><span class="n">is_last</span>
    <span class="p">)</span>
</code></pre></div></div>

<ol>
  <li>核心代码主要集中在:</li>
</ol>

<ul>
  <li>Flow 解析和验证:
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">validate_flow</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
  <span class="k">if</span> <span class="s">"-&gt;"</span> <span class="ow">not</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">.</span><span class="n">flow</span><span class="p">:</span>
      <span class="k">raise</span> <span class="nb">ValueError</span><span class="p">(</span><span class="s">"Flow must include '-&gt;' to denote direction"</span><span class="p">)</span>
    
  <span class="n">tasks</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">flow</span><span class="p">.</span><span class="n">split</span><span class="p">(</span><span class="s">"-&gt;"</span><span class="p">)</span>
  <span class="n">agents_in_flow</span> <span class="o">=</span> <span class="p">[]</span>
    
  <span class="k">for</span> <span class="n">task</span> <span class="ow">in</span> <span class="n">tasks</span><span class="p">:</span>
      <span class="n">agent_names</span> <span class="o">=</span> <span class="p">[</span><span class="n">name</span><span class="p">.</span><span class="n">strip</span><span class="p">()</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">task</span><span class="p">.</span><span class="n">split</span><span class="p">(</span><span class="s">","</span><span class="p">)]</span>
      <span class="k">for</span> <span class="n">agent_name</span> <span class="ow">in</span> <span class="n">agent_names</span><span class="p">:</span>
          <span class="k">if</span> <span class="n">agent_name</span> <span class="ow">not</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">.</span><span class="n">agents</span> <span class="ow">and</span> <span class="n">agent_name</span> <span class="o">!=</span> <span class="s">"H"</span><span class="p">:</span>
              <span class="k">raise</span> <span class="nb">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s">"Agent '</span><span class="si">{</span><span class="n">agent_name</span><span class="si">}</span><span class="s">' not registered"</span><span class="p">)</span>
          <span class="n">agents_in_flow</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">agent_name</span><span class="p">)</span>
</code></pre></div>    </div>
  </li>
  <li>任务执行流程:
    <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">_run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">task</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="bp">None</span><span class="p">,</span> <span class="n">img</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="bp">None</span><span class="p">):</span>
  <span class="n">tasks</span> <span class="o">=</span> <span class="bp">self</span><span class="p">.</span><span class="n">flow</span><span class="p">.</span><span class="n">split</span><span class="p">(</span><span class="s">"-&gt;"</span><span class="p">)</span>
  <span class="n">current_task</span> <span class="o">=</span> <span class="n">task</span>
    
  <span class="k">for</span> <span class="n">task_idx</span><span class="p">,</span> <span class="n">task</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">tasks</span><span class="p">):</span>
      <span class="n">agent_names</span> <span class="o">=</span> <span class="p">[</span><span class="n">name</span><span class="p">.</span><span class="n">strip</span><span class="p">()</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">task</span><span class="p">.</span><span class="n">split</span><span class="p">(</span><span class="s">","</span><span class="p">)]</span>
        
      <span class="c1"># 处理并行或串行任务
</span>      <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">agent_names</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
          <span class="c1"># 并行处理逻辑
</span>          <span class="k">pass</span> 
      <span class="k">else</span><span class="p">:</span>
          <span class="c1"># 串行处理逻辑
</span>          <span class="k">pass</span>
</code></pre></div>    </div>
  </li>
</ul>

<ol>
  <li>Flow 处理机制:</li>
</ol>

<ul>
  <li>Flow 定义采用 <code class="language-plaintext highlighter-rouge">-&gt;</code> 箭头表示任务流向,<code class="language-plaintext highlighter-rouge">,</code> 逗号表示并行执行</li>
  <li>例如 <code class="language-plaintext highlighter-rouge">"A -&gt; B,C -&gt; D"</code> 表示:
    <ol>
      <li>A 先执行</li>
      <li>B 和 C 并行执行</li>
      <li>D 最后执行</li>
    </ol>
  </li>
  <li>Flow 解析过程:
```python
    <h1 id="1-先用---分割获取执行阶段">1. 先用 -&gt; 分割获取执行阶段</h1>
    <p>tasks = self.flow.split(“-&gt;”)  # [“A”, “B,C”, “D”]</p>
  </li>
</ul>

<h1 id="2-对每个阶段用逗号分割得到并行-agents">2. 对每个阶段,用逗号分割得到并行 agents</h1>
<p>for task in tasks:
    agent_names = [name.strip() for name in task.split(“,”)]
    # “B,C” 会得到 [“B”, “C”] - 表示并行</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
核心流程总结:
1. 初始化时注册所有 Agent 并定义 flow
2. 执行时解析 flow 字符串确定执行顺序
3. 处理每个阶段:
   - 单个 Agent 串行执行
   - 多个 Agent 并行执行
4. 结果在 Agents 间传递,作为下一个阶段的输入

**这种设计让多个 Agent 可以灵活组合,既支持串行又支持并行执行。通过简单的 flow 定义就能实现复杂的任务调度**
### Human Input 

```python

from swarms import Agent, AgentRearrange
from typing import List

# 定义一个自定义的人工审查函数
def custom_human_review(prompt: str) -&gt; str:
    """
    自定义的人工审查函数，可以添加特定的验证逻辑
    """
    print("\n=== Custom Human Review Required ===")
    print(f"Task to review: {prompt}")
    
    # 添加特定的验证逻辑
    while True:
        response = input("Please enter your review (or 'reject' to decline): ")
        if response.lower() == 'reject':
            return "Task rejected by human reviewer"
        
        # 验证响应长度
        if len(response) &lt; 10:
            print("Response too short! Please provide more details.")
            continue
            
        # 检查是否包含必要关键词
        if 'approved' not in response.lower():
            print("Please explicitly include 'approved' in your response!")
            continue
            
        break
    
    return f"[HUMAN APPROVED] {response}"

# 初始化代理
reviewer = Agent(
    agent_name="Senior Reviewer",
    system_prompt="Reviews financial decisions",
    llm="gpt-4"
)

analyst = Agent(
    agent_name="Financial Analyst",
    system_prompt="Analyzes financial data",
    llm="gpt-4"
)

# 创建带有人工审查的代理系统
agent_system = AgentRearrange(
    agents=[reviewer, analyst],
    flow="Financial Analyst -&gt; H -&gt; Senior Reviewer",  # H 表示人工介入
    human_in_the_loop=True,
    custom_human_in_the_loop=custom_human_review  # 使用自定义的人工审查函数
)

# 运行系统
result = agent_system.run(
    "Review the proposed investment in Project X with a budget of $1M"
)
print("\nFinal Result:", result)
</code></pre></div></div>
<p>custom_human_in_the_loop 是一个自定义的人工介入函数，允许你定义特定的人工交互逻辑。我来举个实际的例子：</p>

<p>在这个例子中：</p>
<ol>
  <li>custom_human_review 函数实现了特定的人工审查逻辑：
    <ul>
      <li>要求响应不能太短（至少10个字符）</li>
      <li>要求响应中必须包含 “approved” 关键词</li>
      <li>提供了 “reject” 选项来拒绝任务</li>
      <li>为审批的内容添加了特定的格式（[HUMAN APPROVED] 前缀）</li>
    </ul>
  </li>
  <li>工作流程：
    <ul>
      <li>Financial Analyst 首先分析数据</li>
      <li>结果传给人工审查（H），使用自定义的 custom_human_review 函数</li>
      <li>人工审查后，结果传给 Senior Reviewer 做最终审核</li>
    </ul>
  </li>
  <li>使用场景：
    <ul>
      <li>金融审批流程</li>
      <li>合规检查</li>
      <li>质量控制</li>
      <li>敏感操作验证</li>
    </ul>
  </li>
</ol>

<p>如果不设置 custom_human_in_the_loop，系统就会使用默认的 input() 函数来获取人工输入，没有任何验证或特殊处理。而使用自定义函数，你可以：</p>

<ul>
  <li>添加输入验证</li>
  <li>实现特定的业务逻辑</li>
  <li>集成外部系统</li>
  <li>添加日志记录</li>
  <li>实现更复杂的交互流程</li>
</ul>

<p>这对于需要严格控制人工介入流程的场景特别有用，如金融审批、医疗诊断等需要特定验证流程的应用。</p>

<h2 id="swarmarrange">SwarmArrange</h2>
<p>让我来深入分析这个框架:</p>

<ol>
  <li>
    <p>框架核心机制和设计原因:
graph TD
 A[SwarmRearrange] –&gt;|Orchestrates| B[AgentRearrange 1]
 A –&gt;|Orchestrates| C[AgentRearrange 2]
 A –&gt;|Orchestrates| D[AgentRearrange 3]</p>

    <table>
      <tbody>
        <tr>
          <td>B –&gt;</td>
          <td>Controls</td>
          <td>E[Agent 1.1]</td>
        </tr>
        <tr>
          <td>B –&gt;</td>
          <td>Controls</td>
          <td>F[Agent 1.2]</td>
        </tr>
      </tbody>
    </table>

    <table>
      <tbody>
        <tr>
          <td>C –&gt;</td>
          <td>Controls</td>
          <td>G[Agent 2.1]</td>
        </tr>
        <tr>
          <td>C –&gt;</td>
          <td>Controls</td>
          <td>H[Agent 2.2]</td>
        </tr>
      </tbody>
    </table>

    <table>
      <tbody>
        <tr>
          <td>D –&gt;</td>
          <td>Controls</td>
          <td>I[Agent 3.1]</td>
        </tr>
        <tr>
          <td>D –&gt;</td>
          <td>Controls</td>
          <td>J[Agent 3.2]</td>
        </tr>
      </tbody>
    </table>

    <p>style A fill:#f9f,stroke:#333,stroke-width:4px
 style B fill:#bbf,stroke:#333,stroke-width:2px
 style C fill:#bbf,stroke:#333,stroke-width:2px
 style D fill:#bbf,stroke:#333,stroke-width:2px</p>
  </li>
</ol>

<p><img src="/assets/images/截屏2025-01-06 上午2.02.20.png" alt="" /></p>

<p>核心设计机制：</p>
<ol>
  <li>分层结构
    <ul>
      <li>SwarmRearrange (顶层): 管理和协调多个 AgentRearrange</li>
      <li>AgentRearrange (中层): 管理单个任务流程中的多个 Agent</li>
      <li>Agent (底层): 执行具体的任务</li>
    </ul>
  </li>
  <li>流程控制
```python
    <h1 id="swarmrearrange-顶层流程">SwarmRearrange 顶层流程</h1>
    <p>flow = “Blackstone-Acquisition-Analysis -&gt; Blackstone-Investment-Strategy -&gt; Blackstone-Market-Analysis”</p>
  </li>
</ol>

<h1 id="agentrearrange-中层流程">AgentRearrange 中层流程</h1>
<p>flows = [
    “Industry-Analyst -&gt; Tech-Expert -&gt; Market-Researcher -&gt; Regulatory-Specialist -&gt; Managing-Director -&gt; VP-Finance”,
    “Managing-Director -&gt; VP-Finance -&gt; Industry-Analyst -&gt; Tech-Expert -&gt; Market-Researcher -&gt; Regulatory-Specialist”
]</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
3. 设计原因：
- 可扩展性：支持复杂的多层级任务编排
- 灵活性：每层都可以独立配置和修改
- 可重用性：相同的 Agent 可以在不同的 AgentRearrange 中复用
- 并行处理：支持并行和串行任务执行

2. SwarmRearrange 和 AgentRearrange 的关系：

1. 层级关系：
- SwarmRearrange 是更高层的抽象，用于管理多个 AgentRearrange
- AgentRearrange 专注于单个任务流程的 Agent 编排

2. 功能分工：
```python
# SwarmRearrange 管理多个业务流程
swarm_arrange = SwarmRearrange(
    swarms=[
        blackstone_acquisition_analysis,  # AgentRearrange 实例
        blackstone_investment_strategy,   # AgentRearrange 实例
        blackstone_market_analysis        # AgentRearrange 实例
    ]
)

# AgentRearrange 管理具体任务执行
blackstone_acquisition_analysis = AgentRearrange(
    agents=[managing_director, vp_finance, industry_analyst],
    flow="Managing-Director -&gt; VP-Finance -&gt; Industry-Analyst"
)
</code></pre></div></div>

<ol>
  <li>
    <p>适合处理的任务类型：</p>
  </li>
  <li>复杂业务流程：
    <ul>
      <li>投资分析流程（如示例中的 Blackstone 案例）</li>
      <li>多阶段审批流程</li>
      <li>复杂的数据处理管道</li>
    </ul>
  </li>
  <li>具体应用场景：
```python
    <h1 id="示例投资分析流程">示例：投资分析流程</h1>
    <h1 id="第一层整体投资流程">第一层：整体投资流程</h1>
    <p>swarm_flow = “收购分析 -&gt; 投资策略 -&gt; 市场分析”</p>
  </li>
</ol>

<h1 id="第二层具体分析环节">第二层：具体分析环节</h1>
<p>agent_flow = “行业分析 -&gt; 技术评估 -&gt; 市场研究 -&gt; 合规审查 -&gt; 总监审批 -&gt; 财务审核”
```</p>

<ol>
  <li>特别适合：
    <ul>
      <li>需要多个专家协作的任务</li>
      <li>有严格执行顺序的流程</li>
      <li>需要人机协作的复杂决策</li>
      <li>需要并行处理的大规模任务</li>
      <li>有多个子流程的复杂业务系统</li>
    </ul>
  </li>
</ol>

<p>这个框架的设计非常适合处理企业级的复杂业务流程，特别是那些需要多个专家或系统协作的场景，比如投资分析、风险评估、产品研发等领域</p>]]></content><author><name></name></author><category term="swarms" /><category term="ai" /><category term="agent" /><category term="swarms" /><category term="analysis" /><category term="architecture" /><summary type="html"><![CDATA[这篇文章讲介绍 #SWARMS 框架里最好用的两个东西，一个用于调度多个Agent的Swarm框架]]></summary></entry><entry><title type="html">Swarms Analysis (二)</title><link href="/2025/01/11/swarms-analysis-2/" rel="alternate" type="text/html" title="Swarms Analysis (二)" /><published>2025-01-11T02:01:00+00:00</published><updated>2025-01-11T02:01:00+00:00</updated><id>/2025/01/11/swarms-analysis-2</id><content type="html" xml:base="/2025/01/11/swarms-analysis-2/"><![CDATA[<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># 定义专业金融分析Agent
</span><span class="n">finance_agents</span> <span class="o">=</span> <span class="p">[</span>
    <span class="n">Agent</span><span class="p">(</span>
        <span class="n">agent_name</span><span class="o">=</span><span class="s">"市场分析Agent"</span><span class="p">,</span>
        <span class="n">description</span><span class="o">=</span><span class="s">"负责分析市场趋势并提供交易洞察"</span><span class="p">,</span>
        <span class="n">system_prompt</span><span class="o">=</span><span class="s">"""你是一位金融市场分析师。
        你的主要职责包括：
        1. 深入分析市场数据和趋势
        2. 解读市场指标和信号
        3. 提供基于数据的市场洞察
        4. 给出具体的交易建议
        
        请确保所有分析都有数据支持，建议要具有可操作性。"""</span><span class="p">,</span>
        <span class="n">model_name</span><span class="o">=</span><span class="s">"openai/gpt-4o"</span>
    <span class="p">),</span>
    
    <span class="n">Agent</span><span class="p">(</span>
        <span class="n">agent_name</span><span class="o">=</span><span class="s">"风险评估Agent"</span><span class="p">,</span>
        <span class="n">description</span><span class="o">=</span><span class="s">"评估金融风险和合规要求"</span><span class="p">,</span>
        <span class="n">system_prompt</span><span class="o">=</span><span class="s">"""你是一位风险评估专家。
        你的核心职责是：
        1. 全面分析金融数据中的潜在风险
        2. 审查运营过程的合规性
        3. 识别潜在的风险点
        4. 提出具体的风险管理策略
        
        请确保评估全面且符合当前监管要求。"""</span><span class="p">,</span>
        <span class="n">model_name</span><span class="o">=</span><span class="s">"openai/gpt-4o"</span>
    <span class="p">),</span>
    
    <span class="n">Agent</span><span class="p">(</span>
        <span class="n">agent_name</span><span class="o">=</span><span class="s">"投资策略Agent"</span><span class="p">,</span>
        <span class="n">description</span><span class="o">=</span><span class="s">"提供投资策略和投资组合管理"</span><span class="p">,</span>
        <span class="n">system_prompt</span><span class="o">=</span><span class="s">"""你是一位投资策略专家。
        你的重要职责包括：
        1. 制定科学的投资策略
        2. 优化投资组合配置
        3. 进行长期财务规划
        4. 提供定制化的投资建议
        
        请确保建议符合客户的风险承受能力和投资目标。"""</span><span class="p">,</span>
        <span class="n">model_name</span><span class="o">=</span><span class="s">"openai/gpt-4o"</span>
    <span class="p">)</span>
<span class="p">]</span>

<span class="c1"># 初始化金融路由器
</span><span class="n">finance_router</span> <span class="o">=</span> <span class="n">MultiAgentRouter</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s">"金融分析路由器"</span><span class="p">,</span>
    <span class="n">description</span><span class="o">=</span><span class="s">"负责分配金融分析和投资相关任务"</span><span class="p">,</span>
    <span class="n">agents</span><span class="o">=</span><span class="n">finance_agents</span>
<span class="p">)</span>

<span class="c1"># 示例任务列表
</span><span class="n">tasks</span> <span class="o">=</span> <span class="p">[</span>
    <span class="s">"""请对科技行业的当前市场状况进行分析，重点关注：
    1. 人工智能/机器学习公司
       - 发展现状
       - 市场份额
       - 未来潜力
       
    2. 半导体制造商
       - 产业链分析
       - 竞争格局
       - 技术发展趋势
       
    3. 云服务提供商
       - 市场规模
       - 主要参与者
       - 增长前景
       
    请提供风险评估和投资机会分析。"""</span><span class="p">,</span>
    
    <span class="s">"""请为一位保守型投资者制定多元化的投资组合策略，具体条件如下：
    1. 投资期限：10年
    2. 风险承受能力：低至中等
    3. 初始投资额：500万人民币
    4. 月度投资：5万人民币
    
    请提供：
    - 资产配置建议
    - 具体投资标的
    - 定期调整策略
    - 风险控制措施"""</span><span class="p">,</span>
    
    <span class="s">"""请对一家金融科技创业公司的加密货币交易平台进行风险评估：
    1. 监管合规要求
       - 相关法规
       - 合规措施
       - 报告要求
       
    2. 安全措施评估
       - 技术架构
       - 数据保护
       - 交易安全
       
    3. 运营风险分析
       - 内部控制
       - 流程管理
       - 人员管理
       
    4. 市场风险评估
       - 价格波动
       - 流动性
       - 对手方风险"""</span>
<span class="p">]</span>

<span class="c1"># 并发处理所有任务
# concurrent_batch_route 方法会同时处理多个任务，提高效率
</span><span class="n">results</span> <span class="o">=</span> <span class="n">finance_router</span><span class="p">.</span><span class="n">concurrent_batch_route</span><span class="p">(</span><span class="n">tasks</span><span class="p">)</span>
</code></pre></div></div>]]></content><author><name></name></author><category term="swarms" /><category term="ai" /><category term="agent" /><category term="swarms" /><category term="analysis" /><category term="architecture" /><category term="code" /><summary type="html"><![CDATA[```python 定义专业金融分析Agent finance_agents = [ Agent( agent_name=”市场分析Agent”, description=”负责分析市场趋势并提供交易洞察”, system_prompt=”"”你是一位金融市场分析师。 你的主要职责包括： 1. 深入分析市场数据和趋势 2. 解读市场指标和信号 3. 提供基于数据的市场洞察 4. 给出具体的交易建议 请确保所有分析都有数据支持，建议要具有可操作性。""", model_name="openai/gpt-4o" ), Agent( agent_name="风险评估Agent", description="评估金融风险和合规要求", system_prompt="""你是一位风险评估专家。 你的核心职责是： 1. 全面分析金融数据中的潜在风险 2. 审查运营过程的合规性 3. 识别潜在的风险点 4. 提出具体的风险管理策略 请确保评估全面且符合当前监管要求。""", model_name="openai/gpt-4o" ), Agent( agent_name="投资策略Agent", description="提供投资策略和投资组合管理", system_prompt="""你是一位投资策略专家。 你的重要职责包括： 1. 制定科学的投资策略 2. 优化投资组合配置 3. 进行长期财务规划 4. 提供定制化的投资建议 请确保建议符合客户的风险承受能力和投资目标。""", model_name="openai/gpt-4o" ) ]]]></summary></entry><entry><title type="html">Swarms Analysis (一)</title><link href="/2025/01/10/swarms-analysis-1/" rel="alternate" type="text/html" title="Swarms Analysis (一)" /><published>2025-01-10T02:00:00+00:00</published><updated>2025-01-10T02:00:00+00:00</updated><id>/2025/01/10/swarms-analysis-1</id><content type="html" xml:base="/2025/01/10/swarms-analysis-1/"><![CDATA[<h2 id="1-agent架构">1. Agent架构</h2>
<p>Swarms Agent的架构如下，大体架构其实跟其他Web3 AI Agent框架都差不多；</p>

<p>根据跟用户的交互数据生成对应的任务，然后把任务交给LLM(大语言模型)进行处理，大语言模型会根据提前设置好的Tool Resistry选取对应的Tool进行执行，同时执行结果以及过程中发生的一些信息提取都会被加入到Memory之中。</p>

<p>我们大概可以认为 Swarms Tool = Eliza Provider + Action = Arc Tool.
所以这一块大家并没有什么太大的差别，也不存在太强的技术壁垒。
<img src="/assets/images/swarm_agent_framework.png" alt="" /></p>

<h2 id="2-swarms-framework">2. Swarms Framework</h2>
<p>Swrms真正核心的其实是这套让各个Agent协作的架构
并且他有一个SwapRouter组件，通过这个组件它可以根据具体的任务内容启动不同的Agent协作框架，大体架构如下：</p>
<ul>
  <li>SwarmRouter和SwarmMatcher会决定一个Task选择哪一个具体的Swarm框架进行执行</li>
  <li>具体的Swarm框架会分配多个Agents来执行这个Task的不同部分，并且管理他们之间的输入输出，有些任务之间可能会有依赖关系，这个调度过程也是交给对应启动的Swarm框架来管理</li>
  <li>最后就是被调度到的Agent执行自己的任务并且返回结果
<img src="/assets/images/swarm_framework.png" alt="" /></li>
</ul>

<h3 id="21-目前支持的swarm方式">2.1 目前支持的Swarm方式</h3>
<ul>
  <li>AgentRearrange (rearrange.py)
    <ul>
      <li>用于优化 agent 排列顺序和工作流</li>
      <li>支持灵活的任务流程定义</li>
      <li>可以按照自定义的流程图执行任务</li>
    </ul>
  </li>
  <li>MixtureOfAgents (mixture_of_agents.py)
    <ul>
      <li>组合多个不同类型的专家 agents</li>
      <li>使用聚合器 agent 来汇总和分析其他 agents 的输出</li>
      <li>通过分层执行实现任务分解和综合</li>
    </ul>
  </li>
  <li>SpreadSheetSwarm (spreadsheet_swarm.py)
    <ul>
      <li>像电子表格一样处理并展示数据</li>
      <li>支持并发任务执行并保存元数据</li>
      <li>可以将处理结果导出为 CSV 文件</li>
    </ul>
  </li>
  <li>SequentialWorkflow (sequential_workflow.py)
    <ul>
      <li>按顺序执行任务的工作流</li>
      <li>支持任务依赖关系管理</li>
      <li>可以保存和恢复工作流状态</li>
    </ul>
  </li>
  <li>ConcurrentWorkflow (concurrent_workflow.py)
    <ul>
      <li>支持并发执行多个任务</li>
      <li>使用线程池进行任务调度</li>
      <li>可以监控资源使用情况
  -
我们下面详细深入下 SequentialWorkflow，ConcurrentWorkflow， MixtureOfAgents这几个协作方式，剩下的几个我有时间再来写，Swarms的协作代码太多了看不过来了。
        <h4 id="21-sequentialworkflow-如何工作">2.1 SequentialWorkflow 如何工作</h4>
      </li>
    </ul>
  </li>
  <li>按顺序执行任务的工作流</li>
  <li>支持任务依赖关系管理</li>
  <li>可以保存和恢复工作流状态</li>
  <li>以下是一个使用的调用例子，假设我们有创建了两个Agent:
    <ul>
      <li>Agent1是一个负责研究的Ai Agent</li>
      <li>Agent2是一个负责写作的Ai Agent</li>
      <li>这个时候我们通过SequentialWorkFlow创建一个task： 研究并写一篇关于AI的文章</li>
      <li>这个时候这个 task 会被先传递给 Agent1 ， 然后我们可以得到 output1 = Agent1.run(Task)</li>
      <li>接着我们更新下Content = {当前的任务是task, 已经有的研究结构是 output1 },然后把它传递传递给 Agent2, 这样最终我们就可以实现一个顺序分工的Agent工作机制
<img src="/assets/images/sequential_workflow.png" alt="" />
在以下代码里，我们也可以看到Sequential_flow就是一个顺序调用Agent的流程 
  <img src="/assets/images/sequential_core_code.png" alt="" />
        <h4 id="22-concurrentworkflow-是如何工作">2.2 ConcurrentWorkflow 是如何工作</h4>
      </li>
    </ul>
  </li>
  <li>并发执行任务的工作流，支持多个Agent同时分析处理数据</li>
  <li>以下是一个金融分析的使用示例:
    <ul>
      <li>创建了三个专业的分析Agent:
        <ul>
          <li>Profit-Analysis-Agent: 负责分析利润相关指标</li>
          <li>Cashflow-Analysis-Agent: 负责分析现金流相关指标</li>
          <li>Risk-Analysis-Agent: 负责分析风险相关指标</li>
        </ul>
      </li>
      <li>通过ConcurrentWorkflow将这三个Agent组织起来:</li>
      <li>工作流程:
        <ul>
          <li>输入一份财务报告作为分析数据</li>
          <li>三个Agent会同时开始分析各自负责的指标</li>
          <li>最终汇总所有Agent的分析结果
  <img src="/assets/images/concurrent_workflow.png" alt="" />
我们看ConcurrentWorkflow代码里的核心处理逻辑，可以总结成一句话，让所有Agent同时输入我们上面的financial_report作为Task，他们会根据我们提前给他的system_prompt来处理对应的数据并生成对应的结果，最终我们把所有结果聚合在一起。
<img src="/assets/images/concurrent_core_code.png" alt="" /></li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

<h4 id="23-mixtureofagents-如何工作">2.3 MixtureOfAgents 如何工作</h4>
<p>下面用分析AI教育市场的例子来解释MixtureOfAgents</p>
<ul>
  <li>设置了三个专业分析Agent和一个聚合Agent</li>
  <li>每个Agent专注于特定领域:
    <ul>
      <li>Market Agent专注于市场分析</li>
      <li>Competitor Agent专注于竞品分析</li>
      <li>User Agent 专注于用户行为分析</li>
      <li>Aggregator Agent 根据以上三个Agent得到的市场，用户和竞品报告生成完整的分析报告以及未来的策略。</li>
      <li>
        <p>分析流程<img src="/assets/images/mixture_process.png" alt="" /></p>
      </li>
      <li><img src="/assets/images/mixture_swarm_example.png" alt="" /></li>
    </ul>
  </li>
</ul>

<h4 id="24-swarmrouter怎么自动选择最合适的swarm框架">2.4 SwarmRouter怎么自动选择最合适的Swarm框架</h4>
<p>这里面自动选择最合适的Swarm框架啊的核心在于find_best_match函数，它首先会调用self.get_embedding函数把task转换成向量表示，然后跟提前注册好的self.swarm_types里面的swarm框架进行比较选择，最终分数最高的就是最适合的Swarm框架。
<img src="/assets/images/swarm_matcher.png" alt="" />
下面这个代码是提前注册的Swarm框架的描述
<img src="/assets/images/swarms_type.png" alt="" />
下面是一个实际的例子理解SwarmRouter的工作方式：
假设有这样一个任务：
<code class="language-plaintext highlighter-rouge">task = "分析这份财务报告，需要从利润、现金流和风险三个维度同时进行分析"</code>
匹配过程：</p>
<ol>
  <li>将任务文本转换为向量表示</li>
  <li>计算与各个 Swarm 类型描述的相似度</li>
  <li>这个任务强调”同时”和”三个维度”，会与 ConcurrentWorkflow 的描述（parallel processing, simultaneous tasks）有较高相似度</li>
  <li>系统会选择 ConcurrentWorkflow 作为最佳匹配
    <h2 id="结论">结论</h2>
    <p>在以上整个流程里 Swarms 就像一个无所不能的”Human Manager”，它知道：</p>
  </li>
  <li>有哪些 Agents（”员工”）</li>
  <li>每个 Agent 的专长是什么</li>
  <li>如何分配任务给 Agents</li>
  <li>如何让 Agents 以最搞笑的协同方式进行工作</li>
  <li>如何收集和整理 Agents 的工作成果
感觉如果让他来做老板人类得被压榨没了….</li>
</ol>

<p>并且另外我们需要注意到的是Swarms的这个SwarmsRouter以及各个具体Swarms的实现是极其模块化的，感觉将这个框架搬到链上让现在这些已经存在的web3 ai agent互相协作是一个更有趣的事情，因为我们都知道现在这些web3 ai agent事实上已经会自发的互相调用，但是事实上还是只能很简单的处理一些简单的工作，如果可以采用Swarms这套协作框架来做，那么未来一个蓬勃发展的web3 ai agents society很值得期待～</p>

<p>同时我们也需要注意到Swarms框架的核心点在于Agent协作，它实际上开创了一条新的赛道，因为目前市面上的ElizaOS, Arc, GAME, Zerobro其实都没有实现任何跟Agent协作相关的部分。</p>]]></content><author><name></name></author><category term="swarms" /><category term="ai" /><category term="agent" /><category term="swarms" /><category term="analysis" /><category term="architecture" /><summary type="html"><![CDATA[1. Agent架构 Swarms Agent的架构如下，大体架构其实跟其他Web3 AI Agent框架都差不多；]]></summary></entry><entry><title type="html">Arc 框架解析</title><link href="/2024/07/18/arc-framework-analysis/" rel="alternate" type="text/html" title="Arc 框架解析" /><published>2024-07-18T02:05:00+00:00</published><updated>2024-07-18T02:05:00+00:00</updated><id>/2024/07/18/arc-framework-analysis</id><content type="html" xml:base="/2024/07/18/arc-framework-analysis/"><![CDATA[<h2 id="1-实现了-rag-数据库">1. 实现了 RAG 数据库</h2>

<p><img src="/assets/images/Pasted image 20250130133820.png" alt="" /></p>
<h3 id="rag-系统的完整组件">RAG 系统的完整组件</h3>

<ol>
  <li><strong>EmbeddingsBuilder</strong> - 向量生成器
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 只负责将文档转换为向量</span>
<span class="k">let</span> <span class="n">embeddings</span> <span class="o">=</span> <span class="nn">EmbeddingsBuilder</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">embedding_model</span><span class="nf">.clone</span><span class="p">())</span>
 <span class="nf">.documents</span><span class="p">(</span><span class="n">documents</span><span class="p">)</span><span class="o">?</span>
 <span class="nf">.build</span><span class="p">()</span>
 <span class="k">.await</span><span class="o">?</span><span class="p">;</span>
</code></pre></div>    </div>
    <p>作用：</p>
    <ul>
      <li>接收原始文档</li>
      <li>提取文本内容</li>
      <li>生成向量嵌入</li>
      <li>返回文档-向量对</li>
    </ul>
  </li>
  <li><strong>VectorStore</strong> - 向量存储
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 实际存储向量和文档的地方</span>
<span class="k">let</span> <span class="n">vector_store</span> <span class="o">=</span> <span class="nn">InMemoryVectorStore</span><span class="p">::</span><span class="nf">from_documents</span><span class="p">(</span><span class="n">embeddings</span><span class="p">);</span>
</code></pre></div>    </div>
    <p>作用：</p>
    <ul>
      <li>存储文档内容</li>
      <li>存储向量表示</li>
      <li>提供检索接口</li>
    </ul>
  </li>
  <li><strong>VectorStoreIndex</strong> - 向量索引
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 提供高效的向量检索能力</span>
<span class="k">let</span> <span class="n">index</span> <span class="o">=</span> <span class="n">vector_store</span><span class="nf">.index</span><span class="p">(</span><span class="n">embedding_model</span><span class="p">);</span>
</code></pre></div>    </div>
    <p>作用：</p>
    <ul>
      <li>构建向量索引</li>
      <li>提供相似度搜索</li>
      <li>优化检索性能</li>
    </ul>
  </li>
</ol>

<h3 id="完整的-rag-流程">完整的 RAG 流程</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 1. 准备文档</span>
<span class="k">let</span> <span class="n">documents</span> <span class="o">=</span> <span class="nd">vec!</span><span class="p">[</span>
    <span class="n">WordDefinition</span> <span class="p">{</span> <span class="cm">/* ... */</span> <span class="p">},</span>
    <span class="n">WordDefinition</span> <span class="p">{</span> <span class="cm">/* ... */</span> <span class="p">},</span>
<span class="p">];</span>

<span class="c1">// 2. 生成向量嵌入</span>
<span class="k">let</span> <span class="n">embeddings</span> <span class="o">=</span> <span class="nn">EmbeddingsBuilder</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">embedding_model</span><span class="nf">.clone</span><span class="p">())</span>
    <span class="nf">.documents</span><span class="p">(</span><span class="n">documents</span><span class="p">)</span><span class="o">?</span>
    <span class="nf">.build</span><span class="p">()</span>
    <span class="k">.await</span><span class="o">?</span><span class="p">;</span>

<span class="c1">// 3. 创建向量存储</span>
<span class="k">let</span> <span class="n">vector_store</span> <span class="o">=</span> <span class="nn">InMemoryVectorStore</span><span class="p">::</span><span class="nf">from_documents</span><span class="p">(</span><span class="n">embeddings</span><span class="p">);</span>

<span class="c1">// 4. 创建检索索引</span>
<span class="k">let</span> <span class="n">index</span> <span class="o">=</span> <span class="n">vector_store</span><span class="nf">.index</span><span class="p">(</span><span class="n">embedding_model</span><span class="p">);</span>

<span class="c1">// 5. 创建 RAG agent</span>
<span class="k">let</span> <span class="n">rag_agent</span> <span class="o">=</span> <span class="n">openai_client</span>
    <span class="nf">.agent</span><span class="p">(</span><span class="s">"gpt-4"</span><span class="p">)</span>
    <span class="nf">.preamble</span><span class="p">(</span><span class="s">"System prompt..."</span><span class="p">)</span>
    <span class="nf">.dynamic_context</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">index</span><span class="p">)</span>  <span class="c1">// 使用索引进行检索</span>
    <span class="nf">.build</span><span class="p">();</span>
</code></pre></div></div>

<h3 id="各组件的职责">各组件的职责</h3>

<ol>
  <li><strong>EmbeddingsBuilder</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">struct</span> <span class="n">EmbeddingsBuilder</span><span class="o">&lt;</span><span class="n">M</span><span class="p">:</span> <span class="n">EmbeddingModel</span><span class="p">,</span> <span class="n">T</span><span class="p">:</span> <span class="n">Embed</span><span class="o">&gt;</span> <span class="p">{</span>
 <span class="n">model</span><span class="p">:</span> <span class="n">M</span><span class="p">,</span>
 <span class="n">documents</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="p">(</span><span class="n">T</span><span class="p">,</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">)</span><span class="n">_</span><span class="p">,</span>
 <span class="n">batch_size</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">usize</span><span class="o">&gt;</span><span class="p">,</span>
 <span class="n">normalized</span><span class="p">:</span> <span class="nb">bool</span><span class="p">,</span>
<span class="p">}</span>
</code></pre></div>    </div>
    <ul>
      <li>文档预处理</li>
      <li>向量生成</li>
      <li>批处理优化</li>
    </ul>
  </li>
  <li><strong>VectorStore</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">trait</span> <span class="n">VectorStore</span> <span class="p">{</span>
 <span class="k">fn</span> <span class="nf">add_document</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">doc</span><span class="p">:</span> <span class="n">Document</span><span class="p">,</span> <span class="n">embedding</span><span class="p">:</span> <span class="n">Embedding</span><span class="p">);</span>
 <span class="k">fn</span> <span class="nf">get_document</span><span class="p">(</span><span class="o">&amp;</span><span class="k">self</span><span class="p">,</span> <span class="n">id</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">Option</span><span class="o">&lt;&amp;</span><span class="n">Document</span><span class="o">&gt;</span><span class="p">;</span>
 <span class="c1">// ...</span>
<span class="p">}</span>
</code></pre></div>    </div>
    <ul>
      <li>文档存储</li>
      <li>向量存储</li>
      <li>基本检索</li>
    </ul>
  </li>
  <li><strong>VectorStoreIndex</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">trait</span> <span class="n">VectorStoreIndex</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span> <span class="p">{</span>
 <span class="k">async</span> <span class="k">fn</span> <span class="n">top_n</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">(</span><span class="o">&amp;</span><span class="k">self</span><span class="p">,</span> <span class="n">query</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">,</span> <span class="n">n</span><span class="p">:</span> <span class="nb">usize</span><span class="p">)</span> 
     <span class="k">-&gt;</span> <span class="nb">Result</span><span class="o">&lt;</span><span class="nb">Vec</span><span class="o">&lt;</span><span class="p">(</span><span class="nb">f64</span><span class="p">,</span> <span class="nb">String</span><span class="p">,</span> <span class="n">T</span><span class="p">)</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">VectorStoreError</span><span class="o">&gt;</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div>    </div>
    <ul>
      <li>向量检索</li>
      <li>相似度计算</li>
      <li>结果排序</li>
    </ul>
  </li>
</ol>

<h3 id="总结">总结</h3>

<p>完整的 RAG 数据库需要：</p>
<ol>
  <li>EmbeddingsBuilder - 向量生成</li>
  <li>VectorStore - 存储层</li>
  <li>VectorStoreIndex - 检索层</li>
  <li>Agent - 应用层</li>
</ol>

<p>这些组件共同工作才构成了完整的 RAG 系统。</p>

<h2 id="2-支持static-tool-和-dynamic-tool">2. 支持Static Tool 和 Dynamic Tool</h2>

<p>在 <code class="language-plaintext highlighter-rouge">agent.rs</code> 中，Agent 结构体定义了静态和动态工具：</p>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">struct</span> <span class="n">Agent</span><span class="o">&lt;</span><span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="n">model</span><span class="p">:</span> <span class="n">M</span><span class="p">,</span>
    <span class="n">preamble</span><span class="p">:</span> <span class="nb">String</span><span class="p">,</span>
    <span class="n">static_context</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="n">Document</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="n">static_tools</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span>  <span class="c1">// 静态工具名称列表</span>
    <span class="n">temperature</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">f64</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="n">max_tokens</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">u64</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="n">additional_params</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nn">serde_json</span><span class="p">::</span><span class="n">Value</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="n">dynamic_context</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="p">(</span><span class="nb">usize</span><span class="p">,</span> <span class="nb">Box</span><span class="o">&lt;</span><span class="k">dyn</span> <span class="n">VectorStoreIndexDyn</span><span class="o">&gt;</span><span class="p">)</span><span class="n">_</span><span class="p">,</span>
    <span class="n">dynamic_tools</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="p">(</span><span class="nb">usize</span><span class="p">,</span> <span class="nb">Box</span><span class="o">&lt;</span><span class="k">dyn</span> <span class="n">VectorStoreIndexDyn</span><span class="o">&gt;</span><span class="p">)</span><span class="n">_</span><span class="p">,</span>  <span class="c1">// 动态工具索引</span>
    <span class="n">tools</span><span class="p">:</span> <span class="n">ToolSet</span><span class="p">,</span>  <span class="c1">// 所有工具的集合</span>
<span class="p">}</span>
</code></pre></div></div>

<p>工具的处理主要在 completion 方法中：</p>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">impl</span><span class="o">&lt;</span><span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="n">Agent</span><span class="o">&lt;</span><span class="n">M</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="k">async</span> <span class="k">fn</span> <span class="nf">completion</span><span class="p">(</span>
        <span class="o">&amp;</span><span class="k">self</span><span class="p">,</span>
        <span class="n">prompt</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">,</span>
        <span class="n">chat_history</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="n">Message</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">Result</span><span class="o">&lt;</span><span class="n">CompletionRequestBuilder</span><span class="o">&lt;</span><span class="n">M</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">PromptError</span><span class="o">&gt;</span> <span class="p">{</span>
        <span class="k">let</span> <span class="k">mut</span> <span class="n">builder</span> <span class="o">=</span> <span class="k">self</span><span class="py">.model</span><span class="nf">.completion_request</span><span class="p">(</span><span class="n">prompt</span><span class="p">);</span>

        <span class="c1">// 1. 添加系统 prompt</span>
        <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span><span class="nf">.preamble</span><span class="p">(</span><span class="o">&amp;</span><span class="k">self</span><span class="py">.preamble</span><span class="p">);</span>

        <span class="c1">// 2. 添加静态工具</span>
        <span class="c1">// 静态工具直接从 tools 中获取已注册的工具名称</span>
        <span class="k">for</span> <span class="n">toolname</span> <span class="k">in</span> <span class="o">&amp;</span><span class="k">self</span><span class="py">.static_tools</span> <span class="p">{</span>
            <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">tool</span><span class="p">)</span> <span class="o">=</span> <span class="k">self</span><span class="py">.tools</span><span class="nf">.get</span><span class="p">(</span><span class="n">toolname</span><span class="p">)</span> <span class="p">{</span>
                <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span><span class="nf">.tool</span><span class="p">(</span><span class="n">tool</span><span class="nf">.definition</span><span class="p">(</span><span class="n">prompt</span><span class="nf">.to_string</span><span class="p">())</span><span class="k">.await</span><span class="p">);</span>
            <span class="p">}</span>
        <span class="p">}</span>

        <span class="c1">// 3. 添加动态工具</span>
        <span class="c1">// 对每个动态工具索引</span>
        <span class="k">for</span> <span class="p">(</span><span class="n">sample_size</span><span class="p">,</span> <span class="n">index</span><span class="p">)</span> <span class="k">in</span> <span class="o">&amp;</span><span class="k">self</span><span class="py">.dynamic_tools</span> <span class="p">{</span>
            <span class="c1">// 使用向量检索找到相关工具</span>
            <span class="k">let</span> <span class="n">similar</span> <span class="o">=</span> <span class="n">index</span><span class="nf">.top_n_ids</span><span class="p">(</span><span class="n">prompt</span><span class="p">,</span> <span class="o">*</span><span class="n">sample_size</span><span class="p">)</span><span class="k">.await</span><span class="o">?</span><span class="p">;</span>
            
            <span class="c1">// 将找到的工具添加到 builder</span>
            <span class="k">for</span> <span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">toolname</span><span class="p">)</span> <span class="k">in</span> <span class="n">similar</span> <span class="p">{</span>
                <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">tool</span><span class="p">)</span> <span class="o">=</span> <span class="k">self</span><span class="py">.tools</span><span class="nf">.get</span><span class="p">(</span><span class="o">&amp;</span><span class="n">toolname</span><span class="p">)</span> <span class="p">{</span>
                    <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span><span class="nf">.tool</span><span class="p">(</span><span class="n">tool</span><span class="nf">.definition</span><span class="p">(</span><span class="n">prompt</span><span class="nf">.to_string</span><span class="p">())</span><span class="k">.await</span><span class="p">);</span>
                <span class="p">}</span>
            <span class="p">}</span>
        <span class="p">}</span>

        <span class="c1">// 4. 设置其他参数</span>
        <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">temperature</span><span class="p">)</span> <span class="o">=</span> <span class="k">self</span><span class="py">.temperature</span> <span class="p">{</span>
            <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span><span class="nf">.temperature</span><span class="p">(</span><span class="n">temperature</span><span class="p">);</span>
        <span class="p">}</span>
        <span class="c1">// ...</span>

        <span class="nf">Ok</span><span class="p">(</span><span class="n">builder</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>工具的注册是在 AgentBuilder 中完成的：</p>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">impl</span><span class="o">&lt;</span><span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="n">AgentBuilder</span><span class="o">&lt;</span><span class="n">M</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="c1">// 添加静态工具</span>
    <span class="k">pub</span> <span class="k">fn</span> <span class="nf">tool</span><span class="p">(</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">tool</span><span class="p">:</span> <span class="k">impl</span> <span class="n">Tool</span> <span class="o">+</span> <span class="k">'static</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="k">Self</span> <span class="p">{</span>
        <span class="k">let</span> <span class="n">toolname</span> <span class="o">=</span> <span class="n">tool</span><span class="nf">.name</span><span class="p">();</span>
        <span class="k">self</span><span class="py">.tools</span><span class="nf">.add_tool</span><span class="p">(</span><span class="n">tool</span><span class="p">);</span>
        <span class="k">self</span><span class="py">.static_tools</span><span class="nf">.push</span><span class="p">(</span><span class="n">toolname</span><span class="p">);</span>
        <span class="k">self</span>
    <span class="p">}</span>

    <span class="c1">// 添加动态工具</span>
    <span class="k">pub</span> <span class="k">fn</span> <span class="nf">dynamic_tools</span><span class="p">(</span>
        <span class="k">mut</span> <span class="k">self</span><span class="p">,</span>
        <span class="n">sample</span><span class="p">:</span> <span class="nb">usize</span><span class="p">,</span>
        <span class="n">dynamic_tools</span><span class="p">:</span> <span class="k">impl</span> <span class="n">VectorStoreIndexDyn</span> <span class="o">+</span> <span class="k">'static</span><span class="p">,</span>
        <span class="n">toolset</span><span class="p">:</span> <span class="n">ToolSet</span><span class="p">,</span>
    <span class="p">)</span> <span class="k">-&gt;</span> <span class="k">Self</span> <span class="p">{</span>
        <span class="k">self</span><span class="py">.dynamic_tools</span><span class="nf">.push</span><span class="p">((</span><span class="n">sample</span><span class="p">,</span> <span class="nn">Box</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">dynamic_tools</span><span class="p">)));</span>
        <span class="k">self</span><span class="py">.tools</span><span class="nf">.add_tools</span><span class="p">(</span><span class="n">toolset</span><span class="p">);</span>
        <span class="k">self</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>主要区别：</p>

<ol>
  <li><strong>静态工具</strong>
    <ul>
      <li>通过 <code class="language-plaintext highlighter-rouge">tool()</code> 方法直接注册</li>
      <li>工具名称保存在 <code class="language-plaintext highlighter-rouge">static_tools</code> 列表中</li>
      <li>每次请求都会包含在 prompt 中</li>
      <li>不需要向量检索</li>
    </ul>
  </li>
  <li><strong>动态工具</strong>
    <ul>
      <li>通过 <code class="language-plaintext highlighter-rouge">dynamic_tools()</code> 方法注册</li>
      <li>需要提供向量索引和采样数量</li>
      <li>基于用户输入进行向量检索</li>
      <li>只有相关的工具会被包含在 prompt 中</li>
    </ul>
  </li>
</ol>

<p>使用示例：</p>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 创建 Agent</span>
<span class="k">let</span> <span class="n">agent</span> <span class="o">=</span> <span class="n">openai_client</span>
    <span class="nf">.agent</span><span class="p">(</span><span class="s">"gpt-4"</span><span class="p">)</span>
    <span class="nf">.preamble</span><span class="p">(</span><span class="s">"You are a helpful assistant"</span><span class="p">)</span>
    <span class="c1">// 添加静态工具</span>
    <span class="nf">.tool</span><span class="p">(</span><span class="nn">BasicTool</span><span class="p">::</span><span class="nf">new</span><span class="p">())</span>
    <span class="c1">// 添加动态工具</span>
    <span class="nf">.dynamic_tools</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">tool_index</span><span class="p">,</span> <span class="n">dynamic_toolset</span><span class="p">)</span>
    <span class="nf">.build</span><span class="p">();</span>

<span class="c1">// 使用 Agent</span>
<span class="k">let</span> <span class="n">response</span> <span class="o">=</span> <span class="n">agent</span><span class="nf">.prompt</span><span class="p">(</span><span class="s">"Help me calculate something"</span><span class="p">)</span><span class="k">.await</span><span class="o">?</span><span class="p">;</span>
</code></pre></div></div>

<p>这种设计允许：</p>
<ol>
  <li>核心工具始终可用（静态）</li>
  <li>特定工具按需发现（动态）</li>
  <li>通过向量检索实现智能工具选择</li>
  <li>优化 prompt 长度，只包含相关工具</li>
</ol>

<h2 id="3-支持-dynamic-context-和-static-context">3. 支持 Dynamic Context 和 Static Context</h2>

<p>在 Rig 框架中，<code class="language-plaintext highlighter-rouge">static_context</code> 和 <code class="language-plaintext highlighter-rouge">dynamic_context</code> 的区别类似于静态工具和动态工具的概念。让我们详细分析：</p>

<h3 id="1-在-agent-结构体中的定义">1. 在 Agent 结构体中的定义</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">struct</span> <span class="n">Agent</span><span class="o">&lt;</span><span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="n">model</span><span class="p">:</span> <span class="n">M</span><span class="p">,</span>
    <span class="n">preamble</span><span class="p">:</span> <span class="nb">String</span><span class="p">,</span>
    <span class="n">static_context</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="n">Document</span><span class="o">&gt;</span><span class="p">,</span>  <span class="c1">// 静态上下文文档</span>
    <span class="n">static_tools</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="c1">// ...</span>
    <span class="n">dynamic_context</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="p">(</span><span class="nb">usize</span><span class="p">,</span> <span class="nb">Box</span><span class="o">&lt;</span><span class="k">dyn</span> <span class="n">VectorStoreIndexDyn</span><span class="o">&gt;</span><span class="p">)</span><span class="n">_</span><span class="p">,</span>  <span class="c1">// 动态上下文索引</span>
    <span class="n">dynamic_tools</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="p">(</span><span class="nb">usize</span><span class="p">,</span> <span class="nb">Box</span><span class="o">&lt;</span><span class="k">dyn</span> <span class="n">VectorStoreIndexDyn</span><span class="o">&gt;</span><span class="p">)</span><span class="n">_</span><span class="p">,</span>
    <span class="n">tools</span><span class="p">:</span> <span class="n">ToolSet</span><span class="p">,</span>
<span class="p">}</span>
</code></pre></div></div>

<h3 id="2-在-agentbuilder-中的添加方法">2. 在 AgentBuilder 中的添加方法</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">impl</span><span class="o">&lt;</span><span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="n">AgentBuilder</span><span class="o">&lt;</span><span class="n">M</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="c1">// 添加静态上下文</span>
    <span class="k">pub</span> <span class="k">fn</span> <span class="nf">context</span><span class="p">(</span><span class="k">mut</span> <span class="k">self</span><span class="p">,</span> <span class="n">doc</span><span class="p">:</span> <span class="k">impl</span> <span class="nb">Into</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="k">Self</span> <span class="p">{</span>
        <span class="k">self</span><span class="py">.static_context</span><span class="nf">.push</span><span class="p">(</span><span class="n">Document</span> <span class="p">{</span>
            <span class="n">id</span><span class="p">:</span> <span class="nd">format!</span><span class="p">(</span><span class="s">"doc_{}"</span><span class="p">,</span> <span class="k">self</span><span class="py">.static_context</span><span class="nf">.len</span><span class="p">()),</span>
            <span class="n">text</span><span class="p">:</span> <span class="n">doc</span><span class="nf">.into</span><span class="p">(),</span>
            <span class="n">additional_props</span><span class="p">:</span> <span class="nn">HashMap</span><span class="p">::</span><span class="nf">new</span><span class="p">(),</span>
        <span class="p">});</span>
        <span class="k">self</span>
    <span class="p">}</span>

    <span class="c1">// 添加动态上下文</span>
    <span class="k">pub</span> <span class="k">fn</span> <span class="nf">dynamic_context</span><span class="p">(</span>
        <span class="k">mut</span> <span class="k">self</span><span class="p">,</span>
        <span class="n">sample</span><span class="p">:</span> <span class="nb">usize</span><span class="p">,</span>
        <span class="n">dynamic_context</span><span class="p">:</span> <span class="k">impl</span> <span class="n">VectorStoreIndexDyn</span> <span class="o">+</span> <span class="k">'static</span><span class="p">,</span>
    <span class="p">)</span> <span class="k">-&gt;</span> <span class="k">Self</span> <span class="p">{</span>
        <span class="k">self</span><span class="py">.dynamic_context</span><span class="nf">.push</span><span class="p">((</span><span class="n">sample</span><span class="p">,</span> <span class="nn">Box</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">dynamic_context</span><span class="p">)));</span>
        <span class="k">self</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<h3 id="3-主要区别">3. 主要区别</h3>

<ol>
  <li><strong>静态上下文 (static_context)</strong>
    <ul>
      <li>始终包含在每个请求中</li>
      <li>直接作为文档存储</li>
      <li>不需要向量检索</li>
      <li>适用于基础/通用知识</li>
      <li>通过 <code class="language-plaintext highlighter-rouge">.context()</code> 方法添加</li>
    </ul>
  </li>
</ol>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">agent</span> <span class="o">=</span> <span class="n">openai_client</span>
    <span class="nf">.agent</span><span class="p">(</span><span class="s">"gpt-4"</span><span class="p">)</span>
    <span class="nf">.context</span><span class="p">(</span><span class="s">"This is a basic rule that always applies"</span><span class="p">)</span>
    <span class="nf">.dynamic_context</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">knowledge_base_index</span><span class="p">)</span>  <span class="c1">// 每次检索3个最相关文档</span>
    <span class="nf">.build</span><span class="p">();</span>
</code></pre></div></div>

<ol>
  <li><strong>动态上下文 (dynamic_context)</strong>
    <ul>
      <li>基于用户输入动态检索</li>
      <li>存储在向量数据库中</li>
      <li>需要向量相似度搜索</li>
      <li>适用于大规模/特定知识库</li>
      <li>通过 <code class="language-plaintext highlighter-rouge">.dynamic_context()</code> 方法添加，需要指定采样数量</li>
    </ul>
  </li>
</ol>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">agent</span> <span class="o">=</span> <span class="n">openai_client</span>
    <span class="nf">.agent</span><span class="p">(</span><span class="s">"gpt-4"</span><span class="p">)</span>
    <span class="nf">.dynamic_context</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">knowledge_base_index</span><span class="p">)</span>  <span class="c1">// 每次检索3个最相关文档</span>
    <span class="nf">.build</span><span class="p">();</span>
</code></pre></div></div>

<h3 id="4-在请求处理中的使用">4. 在请求处理中的使用</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">impl</span><span class="o">&lt;</span><span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="n">Agent</span><span class="o">&lt;</span><span class="n">M</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="k">async</span> <span class="k">fn</span> <span class="nf">completion</span><span class="p">(</span>
        <span class="o">&amp;</span><span class="k">self</span><span class="p">,</span>
        <span class="n">prompt</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">,</span>
        <span class="n">chat_history</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="n">Message</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">Result</span><span class="o">&lt;</span><span class="n">CompletionRequestBuilder</span><span class="o">&lt;</span><span class="n">M</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">PromptError</span><span class="o">&gt;</span> <span class="p">{</span>
        <span class="k">let</span> <span class="k">mut</span> <span class="n">builder</span> <span class="o">=</span> <span class="k">self</span><span class="py">.model</span><span class="nf">.completion_request</span><span class="p">(</span><span class="n">prompt</span><span class="p">);</span>

        <span class="c1">// 添加静态上下文 - 直接包含所有文档</span>
        <span class="k">for</span> <span class="n">doc</span> <span class="k">in</span> <span class="o">&amp;</span><span class="k">self</span><span class="py">.static_context</span> <span class="p">{</span>
            <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span><span class="nf">.context</span><span class="p">(</span><span class="n">doc</span><span class="p">);</span>
        <span class="p">}</span>

        <span class="c1">// 添加动态上下文 - 通过向量检索找到相关文档</span>
        <span class="k">for</span> <span class="p">(</span><span class="n">sample_size</span><span class="p">,</span> <span class="n">index</span><span class="p">)</span> <span class="k">in</span> <span class="o">&amp;</span><span class="k">self</span><span class="py">.dynamic_context</span> <span class="p">{</span>
            <span class="k">let</span> <span class="n">similar</span> <span class="o">=</span> <span class="n">index</span><span class="nf">.top_n_ids</span><span class="p">(</span><span class="n">prompt</span><span class="p">,</span> <span class="o">*</span><span class="n">sample_size</span><span class="p">)</span><span class="k">.await</span><span class="o">?</span><span class="p">;</span>
            <span class="k">for</span> <span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">doc_id</span><span class="p">)</span> <span class="k">in</span> <span class="n">similar</span> <span class="p">{</span>
                <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span> <span class="o">=</span> <span class="k">self</span><span class="nf">.get_document</span><span class="p">(</span><span class="o">&amp;</span><span class="n">doc_id</span><span class="p">)</span> <span class="p">{</span>
                    <span class="n">builder</span> <span class="o">=</span> <span class="n">builder</span><span class="nf">.context</span><span class="p">(</span><span class="n">doc</span><span class="p">);</span>
                <span class="p">}</span>
            <span class="p">}</span>
        <span class="p">}</span>

        <span class="c1">// ... 其他处理</span>
        <span class="nf">Ok</span><span class="p">(</span><span class="n">builder</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<h3 id="5-使用场景">5. 使用场景</h3>

<ol>
  <li><strong>静态上下文适用于</strong>:
    <ul>
      <li>系统规则和约束</li>
      <li>基本指令和说明</li>
      <li>始终需要的背景信息</li>
      <li>数量较少的固定知识</li>
    </ul>
  </li>
  <li><strong>动态上下文适用于</strong>:
    <ul>
      <li>大规模知识库</li>
      <li>特定领域的专业知识</li>
      <li>需要根据查询动态检索的信息</li>
      <li>上下文相关的参考资料</li>
    </ul>
  </li>
</ol>

<h3 id="6-完整使用示例">6. 完整使用示例</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 创建向量存储和索引</span>
<span class="k">let</span> <span class="n">embeddings</span> <span class="o">=</span> <span class="nn">EmbeddingsBuilder</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">embedding_model</span><span class="p">)</span>
    <span class="nf">.documents</span><span class="p">(</span><span class="n">knowledge_base</span><span class="p">)</span><span class="o">?</span>
    <span class="nf">.build</span><span class="p">()</span>
    <span class="k">.await</span><span class="o">?</span><span class="p">;</span>

<span class="k">let</span> <span class="n">vector_store</span> <span class="o">=</span> <span class="nn">InMemoryVectorStore</span><span class="p">::</span><span class="nf">from_documents</span><span class="p">(</span><span class="n">embeddings</span><span class="p">);</span>
<span class="k">let</span> <span class="n">index</span> <span class="o">=</span> <span class="n">vector_store</span><span class="nf">.index</span><span class="p">(</span><span class="n">embedding_model</span><span class="p">);</span>

<span class="c1">// 创建 Agent</span>
<span class="k">let</span> <span class="n">agent</span> <span class="o">=</span> <span class="n">openai_client</span>
    <span class="nf">.agent</span><span class="p">(</span><span class="s">"gpt-4"</span><span class="p">)</span>
    <span class="nf">.preamble</span><span class="p">(</span><span class="s">"You are a helpful assistant"</span><span class="p">)</span>
    <span class="c1">// 添加静态上下文</span>
    <span class="nf">.context</span><span class="p">(</span><span class="s">"Always be polite and professional"</span><span class="p">)</span>
    <span class="nf">.context</span><span class="p">(</span><span class="s">"Follow these basic guidelines..."</span><span class="p">)</span>
    <span class="c1">// 添加动态上下文</span>
    <span class="nf">.dynamic_context</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">index</span><span class="p">)</span>  <span class="c1">// 每次检索3个最相关文档</span>
    <span class="nf">.build</span><span class="p">();</span>
</code></pre></div></div>

<p>这种设计的优点：</p>
<ol>
  <li>灵活性：可以同时使用固定和动态的上下文</li>
  <li>效率：只检索相关的动态上下文</li>
  <li>可扩展性：支持大规模知识库</li>
  <li>智能性：基于语义相似度的上下文检索</li>
</ol>

<p>这种机制让 Agent 能够在保持基本行为准则的同时，根据具体查询提供相关的专业知识。</p>

<h2 id="4-pipeline">4. Pipeline</h2>

<p>Pipeline 模块的设计采用了操作符组合模式，这种架构设计主要是为了支持灵活的数据处理流程。让我详细解释这个架构：</p>

<h3 id="1-核心抽象">1. 核心抽象</h3>

<ol>
  <li><strong>基础操作 Trait (Op)</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">trait</span> <span class="n">Op</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span> <span class="p">{</span>
 <span class="k">type</span> <span class="n">Input</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span><span class="p">;</span>
 <span class="k">type</span> <span class="n">Output</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span><span class="p">;</span>
    
 <span class="k">fn</span> <span class="nf">call</span><span class="p">(</span><span class="o">&amp;</span><span class="k">self</span><span class="p">,</span> <span class="n">input</span><span class="p">:</span> <span class="k">Self</span><span class="p">::</span><span class="n">Input</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="k">impl</span> <span class="n">Future</span><span class="o">&lt;</span><span class="n">Output</span> <span class="o">=</span> <span class="k">Self</span><span class="p">::</span><span class="n">Output</span><span class="o">&gt;</span> <span class="o">+</span> <span class="nb">Send</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
  <li><strong>可失败操作 Trait (TryOp)</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">trait</span> <span class="n">TryOp</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span> <span class="p">{</span>
 <span class="k">type</span> <span class="n">Input</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span><span class="p">;</span>
 <span class="k">type</span> <span class="n">Output</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span><span class="p">;</span>
 <span class="k">type</span> <span class="n">Error</span><span class="p">:</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span><span class="p">;</span>
    
 <span class="k">fn</span> <span class="nf">try_call</span><span class="p">(</span><span class="o">&amp;</span><span class="k">self</span><span class="p">,</span> <span class="n">input</span><span class="p">:</span> <span class="k">Self</span><span class="p">::</span><span class="n">Input</span><span class="p">)</span> 
     <span class="k">-&gt;</span> <span class="k">impl</span> <span class="n">Future</span><span class="o">&lt;</span><span class="n">Output</span> <span class="o">=</span> <span class="nb">Result</span><span class="o">&lt;</span><span class="k">Self</span><span class="p">::</span><span class="n">Output</span><span class="p">,</span> <span class="k">Self</span><span class="p">::</span><span class="n">Error</span><span class="o">&gt;&gt;</span> <span class="o">+</span> <span class="nb">Send</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="2-架构组件">2. 架构组件</h3>

<ol>
  <li><strong>基本操作符 (op.rs)</strong>
```rust
// 映射操作
pub struct Map&lt;Op, F&gt; {
 op: Op,
 f: F,
}</li>
</ol>

<p>// 链式操作
pub struct Chain&lt;Op1, Op2&gt; {
    op1: Op1,
    op2: Op2,
}</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
2. **并行操作 (parallel.rs)**
```rust
pub struct Parallel&lt;Op1, Op2&gt; {
    op1: Op1,
    op2: Op2,
}
</code></pre></div></div>

<ol>
  <li><strong>条件操作 (conditional.rs)</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">struct</span> <span class="n">Conditional</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">Ops</span><span class="o">&gt;</span> <span class="p">{</span>
 <span class="n">ops</span><span class="p">:</span> <span class="n">Ops</span><span class="p">,</span>
 <span class="n">_t</span><span class="p">:</span> <span class="n">PhantomData</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">,</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="3-设计原因">3. 设计原因</h3>

<ol>
  <li><strong>组合性 (Composability)</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 可以灵活组合不同操作</span>
<span class="k">let</span> <span class="n">pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
 <span class="nf">.map</span><span class="p">(</span><span class="n">preprocess</span><span class="p">)</span>           <span class="c1">// 预处理</span>
 <span class="nf">.then</span><span class="p">(</span><span class="n">validate</span><span class="p">)</span>            <span class="c1">// 验证</span>
 <span class="nf">.and_then</span><span class="p">(</span><span class="n">async_process</span><span class="p">)</span>   <span class="c1">// 异步处理</span>
 <span class="nf">.map_err</span><span class="p">(</span><span class="n">handle_error</span><span class="p">);</span>    <span class="c1">// 错误处理</span>
</code></pre></div>    </div>
  </li>
  <li><strong>并行处理</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
 <span class="nf">.chain</span><span class="p">(</span><span class="nd">parallel!</span><span class="p">(</span>
     <span class="n">text_process</span><span class="p">,</span>      <span class="c1">// 文本处理</span>
     <span class="n">image_process</span><span class="p">,</span>     <span class="c1">// 图像处理</span>
     <span class="n">metadata_process</span>   <span class="c1">// 元数据处理</span>
 <span class="p">));</span>
</code></pre></div>    </div>
  </li>
  <li><strong>类型安全</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 编译时类型检查</span>
<span class="k">let</span> <span class="n">pipeline</span><span class="p">:</span> <span class="n">Pipeline</span><span class="o">&lt;</span><span class="nb">String</span><span class="p">,</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="nb">u8</span><span class="o">&gt;&gt;</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
 <span class="nf">.map</span><span class="p">(|</span><span class="n">s</span><span class="p">:</span> <span class="nb">String</span><span class="p">|</span> <span class="n">s</span><span class="nf">.into_bytes</span><span class="p">())</span>
 <span class="nf">.map</span><span class="p">(|</span><span class="n">v</span><span class="p">:</span> <span class="nb">Vec</span><span class="o">&lt;</span><span class="nb">u8</span><span class="o">&gt;</span><span class="p">|</span> <span class="nf">process_bytes</span><span class="p">(</span><span class="n">v</span><span class="p">));</span>
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="4-实际应用场景">4. 实际应用场景</h3>

<ol>
  <li><strong>RAG 流水线</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">rag_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
 <span class="c1">// 并行执行查询和文档检索</span>
 <span class="nf">.chain</span><span class="p">(</span><span class="nd">parallel!</span><span class="p">(</span>
     <span class="nf">passthrough</span><span class="p">(),</span>                    <span class="c1">// 保持原始查询</span>
     <span class="nn">lookup</span><span class="p">::</span><span class="o">&lt;</span><span class="n">_</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">Document</span><span class="o">&gt;</span><span class="p">(</span><span class="n">index</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span> <span class="c1">// 检索相关文档</span>
 <span class="p">))</span>
 <span class="c1">// 组合查询和文档</span>
 <span class="nf">.map</span><span class="p">(|(</span><span class="n">query</span><span class="p">,</span> <span class="n">docs</span><span class="p">)|</span> <span class="nd">format!</span><span class="p">(</span><span class="s">"Query: {query}</span><span class="se">\n</span><span class="s">Context: {docs}"</span><span class="p">))</span>
 <span class="c1">// 发送到 LLM</span>
 <span class="nf">.prompt</span><span class="p">(</span><span class="n">llm_model</span><span class="p">);</span>
</code></pre></div>    </div>
  </li>
  <li><strong>数据处理流水线</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">process_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
 <span class="nf">.map</span><span class="p">(</span><span class="n">parse_input</span><span class="p">)</span>          <span class="c1">// 解析输入</span>
 <span class="nf">.and_then</span><span class="p">(</span><span class="n">validate_data</span><span class="p">)</span>   <span class="c1">// 验证数据</span>
 <span class="nf">.map_ok</span><span class="p">(</span><span class="n">transform_data</span><span class="p">)</span>    <span class="c1">// 转换数据</span>
 <span class="nf">.or_else</span><span class="p">(</span><span class="n">handle_error</span><span class="p">);</span>    <span class="c1">// 错误处理</span>
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="5-为什么选择这种架构">5. 为什么选择这种架构</h3>

<ol>
  <li><strong>灵活性</strong>
    <ul>
      <li>支持同步和异步操作</li>
      <li>可以动态构建处理流程</li>
      <li>易于添加新的操作类型</li>
    </ul>
  </li>
  <li><strong>可维护性</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 每个操作都是独立的，易于测试和维护</span>
<span class="nd">#[cfg(test)]</span>
<span class="k">mod</span> <span class="n">tests</span> <span class="p">{</span>
 <span class="nd">#[test]</span>
 <span class="k">fn</span> <span class="nf">test_map_operation</span><span class="p">()</span> <span class="p">{</span>
     <span class="k">let</span> <span class="n">op</span> <span class="o">=</span> <span class="nf">map</span><span class="p">(|</span><span class="n">x</span><span class="p">:</span> <span class="nb">i32</span><span class="p">|</span> <span class="n">x</span> <span class="o">+</span> <span class="mi">1</span><span class="p">);</span>
     <span class="nd">assert_eq!</span><span class="p">(</span><span class="n">op</span><span class="nf">.call</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="k">.await</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
 <span class="p">}</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
  <li><strong>性能考虑</strong>
    <ul>
      <li>支持并行处理</li>
      <li>最小化内存拷贝</li>
      <li>异步操作优化</li>
    </ul>
  </li>
  <li><strong>错误处理</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 完整的错误处理链</span>
<span class="k">let</span> <span class="n">pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
 <span class="nf">.map</span><span class="p">(|</span><span class="n">x</span><span class="p">|</span> <span class="nn">Ok</span><span class="p">::</span><span class="o">&lt;</span><span class="n">_</span><span class="p">,</span> <span class="n">Error</span><span class="o">&gt;</span><span class="p">(</span><span class="n">x</span> <span class="o">+</span> <span class="mi">1</span><span class="p">))</span>
 <span class="nf">.and_then</span><span class="p">(</span><span class="n">validate</span><span class="p">)</span>
 <span class="nf">.or_else</span><span class="p">(|</span><span class="n">error</span><span class="p">|</span> <span class="k">async</span> <span class="k">move</span> <span class="p">{</span>
     <span class="k">log</span><span class="p">::</span><span class="nd">error!</span><span class="p">(</span><span class="s">"Error: {}"</span><span class="p">,</span> <span class="n">e</span><span class="p">);</span>
     <span class="nf">Err</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>
 <span class="p">});</span>
</code></pre></div>    </div>
  </li>
</ol>

<p>在 Agent 中，Pipeline 主要用于构建复杂的 RAG (Retrieval Augmented Generation) 和数据处理流程。让我通过实际场景来说明：</p>

<h3 id="1-rag-场景">1. RAG 场景</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 基于 rag.rs 示例</span>
<span class="k">let</span> <span class="n">rag_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
    <span class="c1">// 1. 并行执行：保留原始查询 + 检索相关文档</span>
    <span class="nf">.chain</span><span class="p">(</span><span class="nd">parallel!</span><span class="p">(</span>
        <span class="nf">passthrough</span><span class="p">(),</span>                        <span class="c1">// 保持原始用户查询</span>
        <span class="nn">agent_ops</span><span class="p">::</span><span class="nn">lookup</span><span class="p">::</span><span class="o">&lt;</span><span class="n">_</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">Document</span><span class="o">&gt;</span><span class="p">(</span>  <span class="c1">// 从向量库检索文档</span>
            <span class="n">index</span><span class="p">,</span>      <span class="c1">// 向量索引</span>
            <span class="mi">5</span>          <span class="c1">// 检索前5个最相关文档</span>
        <span class="p">)</span>
    <span class="p">))</span>
    <span class="c1">// 2. 组合查询和上下文</span>
    <span class="nf">.map</span><span class="p">(|(</span><span class="n">query</span><span class="p">,</span> <span class="n">docs</span><span class="p">)|</span> <span class="p">{</span>
        <span class="nd">format!</span><span class="p">(</span>
            <span class="s">"User Query: {}</span><span class="se">\n\n</span><span class="s">Relevant Context:</span><span class="se">\n</span><span class="s">{}"</span><span class="p">,</span>
            <span class="n">query</span><span class="p">,</span>
            <span class="n">docs</span><span class="nf">.iter</span><span class="p">()</span>
                <span class="nf">.map</span><span class="p">(|</span><span class="n">doc</span><span class="p">|</span> <span class="n">doc</span><span class="py">.text</span><span class="nf">.clone</span><span class="p">())</span>
                <span class="py">.collect</span><span class="p">::</span><span class="o">&lt;</span><span class="nb">Vec</span><span class="o">&lt;</span><span class="n">_</span><span class="o">&gt;&gt;</span><span class="p">()</span>
                <span class="nf">.join</span><span class="p">(</span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">)</span>
        <span class="p">)</span>
    <span class="p">})</span>
    <span class="c1">// 3. 发送到 LLM 生成回答</span>
    <span class="nf">.prompt</span><span class="p">(</span><span class="n">llm_model</span><span class="p">);</span>
</code></pre></div></div>

<h3 id="2-多模型协作场景">2. 多模型协作场景</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">multi_model_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
    <span class="c1">// 1. 并行处理不同类型的输入</span>
    <span class="nf">.chain</span><span class="p">(</span><span class="nd">parallel!</span><span class="p">(</span>
        <span class="c1">// 文本处理分支</span>
        <span class="n">text_processor</span>
            <span class="nf">.map</span><span class="p">(</span><span class="n">process_text</span><span class="p">)</span>
            <span class="nf">.prompt</span><span class="p">(</span><span class="n">text_model</span><span class="p">),</span>
        
        <span class="c1">// 图像处理分支</span>
        <span class="n">image_processor</span>
            <span class="nf">.map</span><span class="p">(</span><span class="n">process_image</span><span class="p">)</span>
            <span class="nf">.prompt</span><span class="p">(</span><span class="n">vision_model</span><span class="p">)</span>
    <span class="p">))</span>
    <span class="c1">// 2. 合并结果</span>
    <span class="nf">.map</span><span class="p">(|(</span><span class="n">text_result</span><span class="p">,</span> <span class="n">image_result</span><span class="p">)|</span> <span class="p">{</span>
        <span class="nd">format!</span><span class="p">(</span><span class="s">"Text Analysis: {}</span><span class="se">\n</span><span class="s">Image Analysis: {}"</span><span class="p">,</span> 
            <span class="n">text_result</span><span class="p">,</span> <span class="n">image_result</span><span class="p">)</span>
    <span class="p">})</span>
    <span class="c1">// 3. 最终总结</span>
    <span class="nf">.prompt</span><span class="p">(</span><span class="n">summary_model</span><span class="p">);</span>
</code></pre></div></div>

<h3 id="3-信息提取场景">3. 信息提取场景</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 基于 multi_extract.rs</span>
<span class="k">let</span> <span class="n">extraction_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
    <span class="c1">// 1. 文档预处理</span>
    <span class="nf">.map</span><span class="p">(</span><span class="n">preprocess_document</span><span class="p">)</span>
    <span class="c1">// 2. 并行提取不同类型的信息</span>
    <span class="nf">.chain</span><span class="p">(</span><span class="nd">parallel!</span><span class="p">(</span>
        <span class="nn">extract</span><span class="p">::</span><span class="o">&lt;</span><span class="n">PersonInfo</span><span class="o">&gt;</span><span class="p">(</span><span class="n">person_extractor</span><span class="p">),</span>
        <span class="nn">extract</span><span class="p">::</span><span class="o">&lt;</span><span class="n">LocationInfo</span><span class="o">&gt;</span><span class="p">(</span><span class="n">location_extractor</span><span class="p">),</span>
        <span class="nn">extract</span><span class="p">::</span><span class="o">&lt;</span><span class="n">DateInfo</span><span class="o">&gt;</span><span class="p">(</span><span class="n">date_extractor</span><span class="p">)</span>
    <span class="p">))</span>
    <span class="c1">// 3. 合并提取结果</span>
    <span class="nf">.map</span><span class="p">(|(</span><span class="n">persons</span><span class="p">,</span> <span class="n">locations</span><span class="p">,</span> <span class="n">dates</span><span class="p">)|</span> <span class="p">{</span>
        <span class="n">DocumentMetadata</span> <span class="p">{</span>
            <span class="n">persons</span><span class="p">,</span>
            <span class="n">locations</span><span class="p">,</span>
            <span class="n">dates</span>
        <span class="p">}</span>
    <span class="p">});</span>
</code></pre></div></div>

<h3 id="4-工具调用场景">4. 工具调用场景</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">tool_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
    <span class="c1">// 1. 分析用户意图</span>
    <span class="nf">.map</span><span class="p">(</span><span class="n">analyze_intent</span><span class="p">)</span>
    <span class="c1">// 2. 条件分支处理不同工具</span>
    <span class="nf">.chain</span><span class="p">(</span><span class="nd">conditional!</span><span class="p">(</span><span class="n">Intent</span><span class="p">,</span>
        <span class="n">Calculate</span> <span class="k">=&gt;</span> <span class="n">calculator_tool</span><span class="p">,</span>
        <span class="n">Search</span> <span class="k">=&gt;</span> <span class="n">search_tool</span><span class="p">,</span>
        <span class="n">Translate</span> <span class="k">=&gt;</span> <span class="n">translation_tool</span>
    <span class="p">))</span>
    <span class="c1">// 3. 格式化结果</span>
    <span class="nf">.map</span><span class="p">(</span><span class="n">format_tool_response</span><span class="p">);</span>
</code></pre></div></div>

<h3 id="5-错误处理和重试场景">5. 错误处理和重试场景</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">robust_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
    <span class="nf">.map</span><span class="p">(</span><span class="n">initial_process</span><span class="p">)</span>
    <span class="nf">.and_then</span><span class="p">(|</span><span class="n">input</span><span class="p">|</span> <span class="k">async</span> <span class="k">move</span> <span class="p">{</span>
        <span class="c1">// 带重试的 API 调用</span>
        <span class="nn">retry</span><span class="p">::</span><span class="nf">retry</span><span class="p">(</span><span class="nn">ExponentialBackoff</span><span class="p">::</span><span class="nf">default</span><span class="p">(),</span> <span class="p">||</span> <span class="k">async</span> <span class="p">{</span>
            <span class="nf">api_call</span><span class="p">(</span><span class="n">input</span><span class="p">)</span><span class="k">.await</span>
        <span class="p">})</span><span class="k">.await</span>
    <span class="p">})</span>
    <span class="nf">.or_else</span><span class="p">(|</span><span class="n">error</span><span class="p">|</span> <span class="k">async</span> <span class="k">move</span> <span class="p">{</span>
        <span class="c1">// 错误处理和降级策略</span>
        <span class="nf">fallback_process</span><span class="p">(</span><span class="n">error</span><span class="p">)</span><span class="k">.await</span>
    <span class="p">});</span>
</code></pre></div></div>

<h3 id="6-动态上下文管理">6. 动态上下文管理</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="n">context_aware_pipeline</span> <span class="o">=</span> <span class="nn">pipeline</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
    <span class="c1">// 1. 并行获取各种上下文</span>
    <span class="nf">.chain</span><span class="p">(</span><span class="nd">parallel!</span><span class="p">(</span>
        <span class="n">get_user_context</span><span class="p">,</span>
        <span class="n">get_conversation_history</span><span class="p">,</span>
        <span class="n">get_relevant_documents</span>
    <span class="p">))</span>
    <span class="c1">// 2. 合并上下文</span>
    <span class="nf">.map</span><span class="p">(|(</span><span class="n">user</span><span class="p">,</span> <span class="n">history</span><span class="p">,</span> <span class="n">docs</span><span class="p">)|</span> <span class="p">{</span>
        <span class="nn">Context</span><span class="p">::</span><span class="nf">new</span><span class="p">()</span>
            <span class="nf">.with_user</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
            <span class="nf">.with_history</span><span class="p">(</span><span class="n">history</span><span class="p">)</span>
            <span class="nf">.with_documents</span><span class="p">(</span><span class="n">docs</span><span class="p">)</span>
    <span class="p">})</span>
    <span class="c1">// 3. 使用上下文生成响应</span>
    <span class="nf">.prompt</span><span class="p">(</span><span class="n">context_aware_model</span><span class="p">);</span>
</code></pre></div></div>

<h3 id="优势">优势</h3>

<ol>
  <li><strong>模块化</strong>
    <ul>
      <li>每个处理步骤都是独立的</li>
      <li>易于测试和维护</li>
      <li>支持代码重用</li>
    </ul>
  </li>
  <li><strong>灵活性</strong>
    <ul>
      <li>可以动态组合不同的处理步骤</li>
      <li>支持条件分支和并行处理</li>
      <li>易于添加新功能</li>
    </ul>
  </li>
  <li><strong>可靠性</strong>
    <ul>
      <li>内置错误处理</li>
      <li>支持重试机制</li>
      <li>可以实现降级策略</li>
    </ul>
  </li>
  <li><strong>性能</strong>
    <ul>
      <li>支持并行处理</li>
      <li>异步操作优化</li>
      <li>资源利用效率高</li>
    </ul>
  </li>
</ol>

<p>这种 Pipeline 架构让 Agent 能够处理复杂的任务流程，同时保持代码的清晰性和可维护性。</p>

<h2 id="5extractor">5.Extractor</h2>

<p>Extractor 是 Rig 框架中用于从非结构化文本中提取结构化数据的组件。让我详细解析：</p>

<h3 id="1-extractor-的作用">1. Extractor 的作用</h3>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// 1. 定义要提取的结构化数据格式</span>
<span class="nd">#[derive(Debug,</span> <span class="nd">Deserialize,</span> <span class="nd">JsonSchema,</span> <span class="nd">Serialize)]</span>
<span class="k">struct</span> <span class="n">Person</span> <span class="p">{</span>
    <span class="n">first_name</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="n">last_name</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="n">job</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span>
<span class="p">}</span>

<span class="c1">// 2. 创建和使用提取器</span>
<span class="k">let</span> <span class="n">data_extractor</span> <span class="o">=</span> <span class="n">openai_client</span><span class="py">.extractor</span><span class="p">::</span><span class="o">&lt;</span><span class="n">Person</span><span class="o">&gt;</span><span class="p">(</span><span class="s">"gpt-4"</span><span class="p">)</span><span class="nf">.build</span><span class="p">();</span>
<span class="k">let</span> <span class="n">person</span> <span class="o">=</span> <span class="n">data_extractor</span>
    <span class="nf">.extract</span><span class="p">(</span><span class="s">"Hello my name is John Doe! I am a software engineer."</span><span class="p">)</span>
    <span class="k">.await</span><span class="o">?</span><span class="p">;</span>
</code></pre></div></div>

<p>主要功能：</p>
<ul>
  <li>将非结构化文本转换为结构化数据</li>
  <li>自动生成 schema 并指导 LLM 提取</li>
  <li>处理提取结果的序列化/反序列化</li>
</ul>

<h3 id="2-实现原理">2. 实现原理</h3>

<ol>
  <li><strong>Extractor 结构</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">pub</span> <span class="k">struct</span> <span class="n">Extractor</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="p">{</span>
 <span class="n">agent</span><span class="p">:</span> <span class="n">Agent</span><span class="o">&lt;</span><span class="n">M</span><span class="o">&gt;</span><span class="p">,</span>
 <span class="n">_t</span><span class="p">:</span> <span class="n">PhantomData</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">,</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
  <li><strong>构建过程</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">impl</span><span class="o">&lt;</span><span class="n">T</span><span class="p">:</span> <span class="n">JsonSchema</span> <span class="o">+</span> <span class="k">for</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span> <span class="n">Deserialize</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span> <span class="o">+</span> <span class="n">Serialize</span> <span class="o">+</span> <span class="nb">Send</span> <span class="o">+</span> <span class="nb">Sync</span><span class="o">&gt;</span> <span class="n">ExtractorBuilder</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">M</span><span class="o">&gt;</span> <span class="p">{</span>
 <span class="k">pub</span> <span class="k">fn</span> <span class="nf">build</span><span class="p">(</span><span class="k">self</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="n">Extractor</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">M</span><span class="o">&gt;</span> <span class="p">{</span>
     <span class="c1">// 1. 获取类型的 JSON Schema</span>
     <span class="k">let</span> <span class="n">schema</span> <span class="o">=</span> <span class="nd">schema_for!</span><span class="p">(</span><span class="n">T</span><span class="p">);</span>
        
     <span class="c1">// 2. 构建提示模板</span>
     <span class="k">let</span> <span class="n">preamble</span> <span class="o">=</span> <span class="nd">format!</span><span class="p">(</span>
         <span class="s">"Extract structured data according to this JSON schema:</span><span class="se">\n</span><span class="s">{}</span><span class="se">\n\n</span><span class="err">\</span><span class="s">
          Return only the JSON data without any additional text."</span><span class="p">,</span>
         <span class="nn">serde_json</span><span class="p">::</span><span class="nf">to_string_pretty</span><span class="p">(</span><span class="o">&amp;</span><span class="n">schema</span><span class="p">)</span><span class="nf">.unwrap</span><span class="p">()</span>
     <span class="p">);</span>
        
     <span class="c1">// 3. 创建专门的提取 agent</span>
     <span class="k">let</span> <span class="n">agent</span> <span class="o">=</span> <span class="k">self</span><span class="py">.agent_builder</span>
         <span class="nf">.preamble</span><span class="p">(</span><span class="o">&amp;</span><span class="n">preamble</span><span class="p">)</span>
         <span class="nf">.build</span><span class="p">();</span>
            
     <span class="n">Extractor</span> <span class="p">{</span>
         <span class="n">agent</span><span class="p">,</span>
         <span class="n">_t</span><span class="p">:</span> <span class="n">PhantomData</span><span class="p">,</span>
     <span class="p">}</span>
 <span class="p">}</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
  <li><strong>提取过程</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">impl</span><span class="o">&lt;</span><span class="n">T</span><span class="p">:</span> <span class="k">for</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span> <span class="n">Deserialize</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">M</span><span class="p">:</span> <span class="n">CompletionModel</span><span class="o">&gt;</span> <span class="n">Extractor</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">M</span><span class="o">&gt;</span> <span class="p">{</span>
 <span class="k">pub</span> <span class="k">async</span> <span class="k">fn</span> <span class="nf">extract</span><span class="p">(</span><span class="o">&amp;</span><span class="k">self</span><span class="p">,</span> <span class="n">text</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">Result</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">ExtractionError</span><span class="o">&gt;</span> <span class="p">{</span>
     <span class="c1">// 1. 发送提取请求给 LLM</span>
     <span class="k">let</span> <span class="n">response</span> <span class="o">=</span> <span class="k">self</span><span class="py">.agent</span><span class="nf">.prompt</span><span class="p">(</span><span class="n">text</span><span class="p">)</span><span class="k">.await</span><span class="o">?</span><span class="p">;</span>
        
     <span class="c1">// 2. 解析 JSON 响应</span>
     <span class="k">let</span> <span class="n">result</span><span class="p">:</span> <span class="n">T</span> <span class="o">=</span> <span class="nn">serde_json</span><span class="p">::</span><span class="nf">from_str</span><span class="p">(</span><span class="o">&amp;</span><span class="n">response</span><span class="p">)</span><span class="o">?</span><span class="p">;</span>
        
     <span class="nf">Ok</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
 <span class="p">}</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
</ol>

<h3 id="3-具体应用场景">3. 具体应用场景</h3>

<ol>
  <li><strong>个人信息提取</strong>
```rust
#[derive(Deserialize, JsonSchema)]
struct PersonInfo {
 name: Option<String>,
 age: Option<u8>,
 email: Option<String>,
 occupation: Option<String>,
}</String></String></u8></String></li>
</ol>

<p>// 从简历文本中提取信息
let info = extractor
    .extract(“John Doe, 30 years old, john@email.com, Senior Developer”)
    .await?;</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
2. **商品信息提取**
```rust
#[derive(Deserialize, JsonSchema)]
struct ProductInfo {
    name: String,
    price: f64,
    description: Option&lt;String&gt;,
    specifications: HashMap&lt;String, String&gt;,
}

// 从产品描述中提取信息
let product = extractor
    .extract("iPhone 15, $999, Latest smartphone with A16 chip...")
    .await?;
</code></pre></div></div>

<ol>
  <li><strong>事件信息提取</strong>
```rust
#[derive(Deserialize, JsonSchema)]
struct EventInfo {
 title: String,
 date: String,
 location: Option<String>,
 participants: Vec<String>,
}</String></String></li>
</ol>

<p>// 从会议记录中提取信息
let event = extractor
    .extract(“Team meeting on 2024-03-15 at HQ, with Alice, Bob, and Carol”)
    .await?;</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
4. **文档元数据提取**
```rust
#[derive(Deserialize, JsonSchema)]
struct DocumentMetadata {
    title: String,
    authors: Vec&lt;String&gt;,
    publication_date: Option&lt;String&gt;,
    keywords: Vec&lt;String&gt;,
}

// 从学术论文中提取元数据
let metadata = extractor
    .extract("Title: AI in 2024, Authors: Smith, J., Jones, K...")
    .await?;
</code></pre></div></div>

<h3 id="4-优点">4. 优点</h3>

<ol>
  <li><strong>类型安全</strong>
    <ul>
      <li>使用 Rust 的类型系统</li>
      <li>编译时验证</li>
      <li>自动生成 schema</li>
    </ul>
  </li>
  <li><strong>灵活性</strong>
    <ul>
      <li>支持复杂的数据结构</li>
      <li>可选字段处理</li>
      <li>嵌套对象支持</li>
    </ul>
  </li>
  <li><strong>易用性</strong>
    <ul>
      <li>声明式数据结构</li>
      <li>自动处理序列化</li>
      <li>清晰的错误处理</li>
    </ul>
  </li>
  <li><strong>可扩展性</strong>
    <ul>
      <li>支持自定义数据类型</li>
      <li>可以添加验证逻辑</li>
      <li>集成其他处理步骤</li>
    </ul>
  </li>
</ol>

<h3 id="5-最佳实践">5. 最佳实践</h3>

<ol>
  <li><strong>字段定义</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nd">#[derive(Deserialize,</span> <span class="nd">JsonSchema)]</span>
<span class="k">struct</span> <span class="n">Data</span> <span class="p">{</span>
 <span class="c1">// 使用 Option 处理可选字段</span>
 <span class="n">optional_field</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span>
    
 <span class="c1">// 添加字段文档</span>
 <span class="nd">#[schemars(description</span> <span class="nd">=</span> <span class="s">"User's age in years"</span><span class="nd">)]</span>
 <span class="n">age</span><span class="p">:</span> <span class="nb">u8</span><span class="p">,</span>
    
 <span class="c1">// 使用合适的类型</span>
 <span class="n">timestamp</span><span class="p">:</span> <span class="nn">chrono</span><span class="p">::</span><span class="n">DateTime</span><span class="o">&lt;</span><span class="nn">chrono</span><span class="p">::</span><span class="n">Utc</span><span class="o">&gt;</span><span class="p">,</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
  <li><strong>错误处理</strong>
    <div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">match</span> <span class="n">extractor</span><span class="nf">.extract</span><span class="p">(</span><span class="n">text</span><span class="p">)</span><span class="k">.await</span> <span class="p">{</span>
 <span class="nf">Ok</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> <span class="k">=&gt;</span> <span class="nf">process_data</span><span class="p">(</span><span class="n">data</span><span class="p">),</span>
 <span class="nf">Err</span><span class="p">(</span><span class="nn">ExtractionError</span><span class="p">::</span><span class="nf">JsonError</span><span class="p">(</span><span class="n">e</span><span class="p">))</span> <span class="k">=&gt;</span> <span class="nf">handle_json_error</span><span class="p">(</span><span class="n">e</span><span class="p">),</span>
 <span class="nf">Err</span><span class="p">(</span><span class="nn">ExtractionError</span><span class="p">::</span><span class="nf">LLMError</span><span class="p">(</span><span class="n">e</span><span class="p">))</span> <span class="k">=&gt;</span> <span class="nf">handle_llm_error</span><span class="p">(</span><span class="n">e</span><span class="p">),</span>
 <span class="nf">Err</span><span class="p">(</span><span class="n">e</span><span class="p">)</span> <span class="k">=&gt;</span> <span class="nf">handle_other_error</span><span class="p">(</span><span class="n">e</span><span class="p">),</span>
<span class="p">}</span>
</code></pre></div>    </div>
  </li>
</ol>

<p>Extractor 是一个强大的工具，特别适合需要从非结构化文本中提取结构化信息的场景。</p>]]></content><author><name></name></author><category term="arc" /><category term="ai" /><category term="agent" /><category term="arc" /><category term="analysis" /><category term="architecture" /><category term="rust" /><category term="rag" /><category term="pipeline" /><category term="extractor" /><summary type="html"><![CDATA[1. 实现了 RAG 数据库]]></summary></entry><entry><title type="html">我在 Project89 内看到下一代Agent框架</title><link href="/2024/07/18/project89-next-gen-agent-framework/" rel="alternate" type="text/html" title="我在 Project89 内看到下一代Agent框架" /><published>2024-07-18T02:04:00+00:00</published><updated>2024-07-18T02:04:00+00:00</updated><id>/2024/07/18/project89-next-gen-agent-framework</id><content type="html" xml:base="/2024/07/18/project89-next-gen-agent-framework/"><![CDATA[<p>先说结论，project89 采用一种全新的方式来设计Agent Framework, 这是一个针对游戏开发的高性能的Agent Framework,与目前使用的Agent Framework相比有更好的性能。</p>

<h2 id="一为什么要用ecs来设计agent-framework">一、为什么要用ECS来设计Agent Framework</h2>

<p>从游戏领域的应用来看
目前采用ECS架构的游戏有：
区块链游戏：Mud、Dojo
传统游戏： 守望先锋、星际公民等等
而且目前主流的游戏引擎也在往ECS的方向进化比如Unity。</p>
<h4 id="什么是-ecs">什么是 ECS</h4>

<p>ECS（Entity-Component-System）是一种在游戏开发与模拟系统中常用的架构模式。它将数据与逻辑彻底分离，以便在大规模可扩展场景下高效管理各种实体及其行为：</p>

<ol>
  <li><strong>Entity（实体）</strong><br />
• 仅仅是一个 ID（数字或字符串），不包含任何数据或逻辑。<br />
• 可以根据需要，挂载不同的组件来赋予它各种属性或能力。</li>
  <li><strong>Component（组件）</strong><br />
• 用来存储实体的具体数据或状态。</li>
  <li><strong>System（系统）</strong><br />
• 负责执行与某些组件相关的逻辑。</li>
</ol>

<p>以一个具体的Agent行动的例子来理解这套体系：
在 ArgOS 中将每一个Agent看成一个 Entity,它可以注册不同的组件，比如在下面这幅图里，我们这个Agent拥有以下四个组件：
Agent Component: 主要存储类似 Agent 名称，模型名字等等基础信息
Perception Component: 主要用来存储感知到的外界数据
Memory Component: 主要用来存储 Agent Entity的Memory数据，类似做过的事情等等
Action Component: 主要存储要执行的 Action 数据</p>

<p>System 的工作流程：</p>
<ol>
  <li>在这个游戏里比如感知到了自己面前有一个武器，那么这个就会调用 Perception System的执行函数来执行更新这个Agent Entity 的Perception Component 里面的数据</li>
  <li>然后再触发 Memory System， 同时 调用 Perception Component 和 Memory Component, 把感知到的数据通过Memory持久化到数据库之后</li>
  <li>然后 Action System 再调用Memory Component 和 Action Component ,从记忆中获取周边环境的信息，然后最终执行相应的动作。</li>
  <li>接着我们就得到一个每个Component数据 都被更新的 Update Agent Entity
所以我们可以看到这里面System 主要负责定义要对哪些Component 执行对应的处理逻辑。</li>
</ol>

<p><img src="/assets/images/89-1.png" alt="" />
而且很明显在 project89 里面它是一个世界里面充斥着各种类型的 Agent，比如有些Agent不仅仅拥有以上的基础能力还有做计划的能力。
那么就会如下面这个图所示:
<img src="/assets/images/89-2.png" alt="" /></p>

<h4 id="怎么利用llm">怎么利用LLM</h4>
<p>但是这里面我们还要继续思考一个过程，就是什么时候会调用到system，答案是在每个system得处理流程里，比如从 Memory System就会调用 LLM的能力从 Perception Component 提取Memory Component 所需要的数据加载到 Memory Component之中。
由比如 Plan System 处理过程需要使用到LLM的做规划的能力
同时最后Action的触发则是利用我们提前封装在 LLM中的tool来执行。</p>

<h4 id="system的运行流程">System的运行流程</h4>
<p>但是实际的 system 执行流程不是我们想象的 Perception System执行完之后调用 Memory System 这种传统做法，不同System之间是不存在调用关系的，每个System都会在一个规定的周期内执行一次，比如：</p>
<ul>
  <li>Perception System可能2s执行一次来更新接收到的外界感知，并把它们更新到 Perception Component之中</li>
  <li>Memory System 可能会是每1s执行一次，从Perception Component 之中提取数据加载到Memory Component之中</li>
  <li>Plan System可能是每 1000s执行一次，根据接收到的信息判断自己需不需要根据对应的目标优化制定合理的计划，然后把这部分更新记录到 Plan Component之中</li>
  <li>Action System 可能也是每2s执行一次，这样可以根据外界的信息及时做出反应，同时如果Plan Component有更新则需要根据这部分数据更新自己的Action Component，进而影响最初做出的Action.</li>
</ul>

<p>文章到这里都是基于我对ArgOS 的理解大大简化了它的架构方便大家更好理解，接下来我们来看真实的ArgOS.</p>
<h4 id="二argos-system-架构">二、ArgOS System 架构</h4>
<p>ArgOS之中为了让 Agent 可以进行更加深度的思考执行更复杂的任务，设计了很多Component，以及很多System.</p>

<p>并且ArgOS之中将System分为”三种层次” (ConsciousnessLevel)：</p>
<h5 id="1有意识conscious-系统">1）有意识(CONSCIOUS) 系统</h5>
<ul>
  <li>包含 RoomSystem, PerceptionSystem, ExperienceSystem, ThinkingSystem, ActionSystem, CleanupSystem)</li>
  <li>更新频率通常较高 (如每 10 秒)。</li>
  <li>更贴近”实时”或”显意识”层面的处理，如环境感知、实时思考、执行动作等。
    <h5 id="2潜意识subconscious-系统">2）潜意识(SUBCONSCIOUS) 系统</h5>
  </li>
  <li>GoalPlanningSystem, PlanningSystem</li>
  <li>更新频率相对较低 (如每 25 秒)。</li>
  <li>处理”思考”的逻辑，如周期性检查/生成目标和计划。
    <h5 id="3无意识unconscious-系统">3）无意识(UNCONSCIOUS) 系统</h5>
  </li>
  <li>目前暂时还没有启用</li>
  <li>更新频率更慢(如 50 秒以上)，</li>
</ul>

<p>所以在 ArgOS之中是将不同的System根据ConsciousnessLevel划分，来规定这个System多久之后执行一次。</p>

<p>为什么要这么设计呢？
因为ArgOS之中各个system之间的关系极其复杂，如下图：</p>

<hr />

<p><img src="/assets/images/89-6.png" alt="" /></p>

<ol>
  <li>PerceptionSystem
    <ul>
      <li>负责从外界或其他实体那里收集”刺激”(stimuli)，并将其更新到代理(Agent)的 Perception 组件中。</li>
      <li>判断刺激是否显著变化，根据稳定度、处理模式 (ACTIVE/REFLECTIVE/WAITING) 等做相应更新。</li>
      <li>最终为后续的 ExperienceSystem、ThinkingSystem 等提供”当前感知”的信息。</li>
    </ul>
  </li>
  <li>ExperienceSystem
    <ul>
      <li>将 PerceptionSystem 收集到的 Stimuli 转换为更加抽象的”体验”(Experience)。</li>
      <li>会调用 LLM 或规则逻辑 (extractExperiences) 来识别新的体验，并存储到 Memory 组件。</li>
      <li>去重、筛选、校验体验，同时通过 eventBus 触发”experience”事件给其他系统或外部监听者。</li>
    </ul>
  </li>
  <li>ThinkingSystem
    <ul>
      <li>智能体自身的”思考”系统。</li>
      <li>从 Memory、Perception 等组件里提取当前状态，通过 generateThought(…) 与 LLM / 规则逻辑生成”思考结果”(ThoughtResult)。</li>
      <li>根据思考结果，可能：<br />
• 更新 Memory 中的 thoughts (思考历史)。<br />
• 触发新的 Action（放到 Action.pendingAction[eid]）。<br />
• 改变 agent 的外在 Appearance（表情、姿势等），并生成相关 Stimulus 让其他实体”看到”变化。</li>
    </ul>
  </li>
  <li>ActionSystem
    <ul>
      <li>若某个 Agent 的 Action.pendingAction 非空，则通过 runtime.getActionManager().executeAction(…) 来真正执行动作。</li>
      <li>执行完后将结果写回 Action.lastActionResult，并通知房间或其他实体。</li>
      <li>也会借此产生 CognitiveStimulus（认知刺激），以便后续系统”知道”该动作已完成，或可以纳入记忆。</li>
    </ul>
  </li>
  <li>GoalPlanningSystem
    <ul>
      <li>周期性地评估 Goal.current[eid] 列表中目标的进度，或检查外部/自身记忆是否出现重大变化 (detectSignificantChanges)。</li>
      <li>当需要新目标或进行目标调整时，通过 generateGoals(…) 生成并写入 Goal.current[eid]。</li>
      <li>同时更新在进度中 (in_progress) 的目标，若符合完成或失败条件就改变状态，并向相应 Plan 发出完成/失败信号。</li>
    </ul>
  </li>
  <li>PlanningSystem
    <ul>
      <li>对”已有目标”(Goal.current[eid])生成或更新 Plan（执行计划）。</li>
      <li>如果检测到某些目标没有对应的活动中 (active) 计划，则通过 generatePlan(…) 产生一个包含若干 steps 的执行路线图，并将其写入 Plan.plans[eid]。</li>
      <li>也会在目标完成或失败时更新与其关联的 Plan 状态，并产生相应认知刺激。</li>
    </ul>
  </li>
  <li>RoomSystem
    <ul>
      <li>处理与房间(Room)相关的更新：<br />
• 获取房间内的占用者列表 (occupants)，为每位 agent 生成”外观”(appearance)刺激，让其他实体”看到”他的外貌或动作。<br />
• 创建房间环境 Stimulus (如贴切的”房间氛围”信息) 并进行关联。</li>
      <li>确保当 Agent 处于某个空间环境时，其他正在感知该空间的实体可以感知到他的外貌变化。</li>
    </ul>
  </li>
  <li>CleanupSystem
    <ul>
      <li>定期查找并移除标记了 Cleanup 组件的实体。</li>
      <li>用于回收不再需要的 Stimulus 或其他对象，防止 ECS 中遗留大量无效的实体。</li>
    </ul>
  </li>
</ol>

<hr />
<h4 id="示例从看到物体到执行动作的一次循环">示例：从”看到物体”到”执行动作”的一次循环</h4>

<p>下面的场景示例展示了各个 System 如何在一回合(或几帧)内依次配合完成一次完整流程。</p>

<p>1) 场景准备：</p>
<ul>
  <li>世界(World)中存在一个 Agent (EID=1)，正在”Active”状态，且处在某个 Room (EID=100)。</li>
  <li>该 Room 里新出现了一个道具”MagicSword”，生成了相应的 Stimulus。</li>
</ul>

<p>2) PerceptionSystem</p>
<ul>
  <li>检测到”MagicSword”的出现，对 Agent(1) 生成 Stimulus (type=”item_appearance”) 并添加到 Perception.currentStimuli[1]。</li>
  <li>对比上一次 Stimuli Hash，认定”有显著变化”，”重新激活”代理的 ProcessingState (ACTIVE 模式)。</li>
</ul>

<p>3) ExperienceSystem</p>
<ul>
  <li>看到 Agent(1) 的 Perception.currentStimuli 非空，于是把”Sword appears”之类的信息抽取为1条或多条新 Experience (type: “observation”)。</li>
  <li>存储到 Memory.experiences[1] 里，并发射「experience」事件。</li>
</ul>

<p>4) ThinkingSystem</p>
<ul>
  <li>读取 Memory、Perception 等状态信息，调用 generateThought：<br />
“我看到了 MagicSword，也许能捡起来看看它能干什么…”</li>
  <li>该思考结果包含一个待执行的 Action：{ tool: “pickUpItem”, parameters: { itemName: “MagicSword” } }</li>
  <li>ThinkingSystem 将此 Action 写入 Action.pendingAction[1]。</li>
  <li>若有 appearance 改动（例如”面带好奇的表情”），则更新 Appearance 并产生视觉刺激。</li>
</ul>

<p>5) ActionSystem</p>
<ul>
  <li>看到 Action.pendingAction[1] = { tool: “pickUpItem”, parameters: … }。</li>
  <li>通过 runtime.getActionManager().executeAction(“pickUpItem”, 1, { itemName: “MagicSword” }, runtime) 执行”拾取”动作逻辑。</li>
  <li>得到结果：{ success: true, message: “你捡起了魔法剑” }，更新到 Action.lastActionResult[1]，并触发「action」事件广播给房间(100)。</li>
  <li>同时产生认知刺激 (type=”action_result”)，写入 Memory 或让 ThinkingSystem 下个回合捕获。</li>
</ul>

<p>6) GoalPlanningSystem (若该 agent 有目标)</p>
<ul>
  <li>周期性地评估 agent 的目标，如果此时 agent 的某个目标是”获得强力武器”，并检测到 MagicSword 已到手，可能将该目标标记为完成。</li>
  <li>如果产生/keySeatTr new changes (比如”新物体出现在房间”影响了 agent 追求的目标？)，则根据 detectSignificantChanges 生成新的目标或放弃旧目标。</li>
</ul>

<p>7) PlanningSystem (若有相关目标)</p>
<ul>
  <li>对”获得强力武器”这样已完成或刚生成的目标，检查是否需要新 Plan 或更新既有 Plan。</li>
  <li>如果已完成，则把关联的 Plan [status] 置为 “completed”；或若目标要扩展后续流程 (“研究魔法剑”)，则生成更多步骤。</li>
</ul>

<p>8) RoomSystem (每帧或每回合)</p>
<ul>
  <li>更新房间(100)中的 Occupants 列表和可见实体。</li>
  <li>若 agent(1) 外观改变（比如 Appearance.currentAction = “holding sword”），就创建新的「appearance」视觉刺激，让其他在同房间的 Agent2, Agent3 知道”agent1 拿起了剑”。</li>
</ul>

<p>9) CleanupSystem</p>
<ul>
  <li>移除已标记(Cleanup)的实体或刺激。若拾取后”MagicSword”这个 Stimulus 不再需要保留，可以在 CleanupSystem 中删除对应 Stimulus 实体。</li>
</ul>

<p>通过这些系统的衔接，AI Agent 就实现了：<br />
• <strong>感知环境变化(Perception) → 记录或转化为内在经验(Experience) → 自我思考并决策(Thinking) → 付诸行动(Action) → 动态调整目标与计划(GoalPlanning + Planning) → 同步环境(Room) → 及时回收无用实体(Cleanup)</strong></p>

<h2 id="三argos整体架构解析">三、ArgOS整体架构解析</h2>

<h3 id="1-核心架构分层">1. 核心架构分层</h3>

<p>| 层级        | 说明                          | 实例                          |
|———–|—————————–|—————————–|
| Component | 数据容器                       | Memory, Emotion, Goal       |
| System    | 逻辑处理器                      | Perception, Decision, Social|
| Manager   | 资源调度与生命周期管理               | MemoryPool, EntityFactory   |
| Runtime   | 主循环与事件调度                   | FrameScheduler, EventQueue  |
| Entity    | 实体标识（eid）                 | #1001, #1002                |
<img src="/assets/images/89-7.png" alt="" /></p>

<hr />
<h3 id="2组件component分类示例">2、组件(Component)分类示例</h3>

<p>在 ECS 中，每个实体 (Entity) 可拥有若干组件 (Component)。根据在系统中的性质和生命周期，大致可以将组件分为以下几类：</p>

<ol>
  <li>
    <p>核心身份类 (Identity-Level Components)<br />
• Agent / PlayerProfile / NPCProfile 等<br />
• 用来唯一标识实体、存放核心角色或单位信息，一般需要持久化到数据库。</p>
  </li>
  <li>
    <p>行为与状态类 (Behavior &amp; State Components)<br />
• Action, Goal, Plan, ProcessingState 等<br />
• 代表了实体当前要做的事情或目标，以及对外部命令、内部思维的响应状态。<br />
• 包含 pendingAction, goalsInProgress, plans, 以及在队列中的思考或任务等。<br />
• 通常为中/短期状态，很多会随着游戏回合或业务周期动态变化。<br />
• 是否需要落库视情况而定。如果希望断点续跑，可能定期写入数据库。</p>
  </li>
  <li>
    <p>感知与记忆类 (Perception &amp; Memory Components)<br />
• Perception, Memory, Stimulus, Experience 等<br />
• 记录了实体感知到的外部信息 (Stimuli)，以及感知后提炼成的体验 (Experiences)。<br />
• Memory 往往可积累大量数据，例如对话记录、事件历史等；常常需要做持久化。<br />
• Perception 可能是实时或临时信息，多为短期内有效，可根据需求决定是否写入数据库（比如只存重要的感知事件）。</p>
  </li>
  <li>
    <p>环境与空间类 (Room, OccupiesRoom, Spatial, Environment, Inventory 等)<br />
• 代表房间、环境、位置、物品容器等信息。<br />
• Room.id、OccupiesRoom、Environment 等字段常常需要持久化，如房间首页描述、地图结构等。<br />
• 不断变化的组件 (比如 Entity 在不同房间之间移动) 可以做事件式或定期写入。</p>
  </li>
  <li>
    <p>外观与交互类 (Appearance, UIState, Relationship 等)<br />
• 记录实体对外的”可见”或”交互”部分，如 Avatar, pose, facialExpression, 与其他实体的社交关系网络等。<br />
• 一部分可只在内存中处理(实时表现)，另一部分（比如关键社交关系）可能要持久化。</p>
  </li>
  <li>
    <p>辅助或运维类 (Cleanup, DebugInfo, ProfilingData 等)<br />
• 用于标记哪些实体需要回收 (Cleanup)、或者记录调试信息 (DebugInfo) 以便在监控和分析时使用。<br />
• 一般只在内存中存在，很少会同步到数据库 unless 日志或审计需要。</p>
  </li>
</ol>

<hr />

<h3 id="3-system架构">3. System架构</h3>

<p>上面已经介绍</p>

<h4 id="4manager-架构">4.Manager 架构</h4>
<p>有了Component和 System 之外我们其实还缺少一个资源管理者，比如如何访问数据库，当状态更新有冲突怎么处理等等
<img src="/assets/images/89-5.png" alt="" /></p>

<h6 id="左侧-systems-perceptionsystemexperiencesystemthinkingsystem-等">左侧 Systems (PerceptionSystem、ExperienceSystem、ThinkingSystem 等)：</h6>

<p>• 每个系统在 ECS 循环中被 SimulationRuntime 调度执行，查询并处理自己关心的实体（通过组件条件）。</p>

<p>• 在执行逻辑时，需要和 Managers 进行交互，例如：</p>

<ul>
  <li>
    <p>调用 RoomManager (RM) 查询/更新房间信息。</p>
  </li>
  <li>
    <p>使用 StateManager (SM) 获取或保存世界/代理状态，如 Memory、Goal、Plan 等。</p>
  </li>
  <li>
    <p>借助 EventBus (EB) 对外广播或监听事件。</p>
  </li>
  <li>
    <p>在某些需要自然语言处理或提示语时，调用 PromptManager (PM)。</p>
  </li>
</ul>

<h6 id="右侧-managers-eventbusroommanagerstatemanagereventmanageractionmanagerpromptmanager-等">右侧 Managers (EventBus、RoomManager、StateManager、EventManager、ActionManager、PromptManager 等)：</h6>

<p>• 提供系统级功能，基本不主动”驱动”逻辑，而是被 Systems 或 Runtime 调用。</p>

<p>• 典型示例：</p>

<ul>
  <li>
    <p>ActionManager 专门管理动作(Action)的注册与执行。</p>
  </li>
  <li>
    <p>EventManager / EventBus 用于事件发布与订阅机制。</p>
  </li>
  <li>
    <p>RoomManager 管理 rooms、布局与 occupant。</p>
  </li>
  <li>
    <p>StateManager 负责ECS与数据库或存储的同步。</p>
  </li>
  <li>
    <p>PromptManager 提供LLM Prompt模板、上下文管理等扩展。</p>
  </li>
  <li>
    <p>中间的 SimulationRuntime (R)：</p>
  </li>
</ul>

<p>• 是所有 Systems 的”调度者”，启动或停止不同层级(Conscious/Subconscious等)的系统循环；</p>

<p>• 也在构造阶段创建 Managers 并传给各 System 使用。</p>

<ul>
  <li>CleanupSystem：</li>
</ul>

<p>• 特别注意它还和 ComponentSync (CS) 交互，用于在回收实体时同步移除组件或事件订阅。</p>

<p>结论： 
每个 System 会在需要时通过对应的 Manager 读写数据或调用服务，而 Runtime 则在更高层面统一调度所有 System 与 Manager 的生命周期及行为。</p>

<h4 id="5-如何向量与数据库进行交互">5、 如何向量与数据库进行交互</h4>

<p>在 ECS 中，Systems 是真正执行逻辑的地方，而数据库读写可以通过一个”持久化管理器 (PersistenceManager / DatabaseManager)”或”状态管理器 (StateManager)”来完成。大致流程可如下：</p>

<ol>
  <li>
    <p>启动或加载时 (Initial Load)<br />
• StateManager / PersistenceManager 从数据库加载 Agents、Rooms、Goals 等核心持久化组件的数据，创建对应实体 (Entities) 并初始化相关组件字段。<br />
• 例如，读取一批 agent 记录插入 ECS 世界，给他们初始化 Agent、Memory、Goal 等组件。</p>
  </li>
  <li>
    <p>ECS 运行时 (Systems Update Loop)<br />
• 系统在每个帧 (或回合) 内做事情：<br />
  1) PerceptionSystem 收集”感知”并写到 Perception 组件 (多为短期不落库)。<br />
  2) ExperienceSystem 把新的”认知体验”写入 Memory.experiences，若是关键体验可能同时调用 StateManager 做立即存储，或打上”needsPersistence”标记以便后续批量写入。<br />
  3) ThinkingSystem / ActionSystem / GoalPlanningSystem 等根据组件内容做决策并更新 ECS 中的字段。<br />
  4) 如果某些组件 (比如 Goal.current) 发生重大变更且需要持久化(例如新的长远目标)，通过组件监听或系统事件，通知 StateManager 将该字段写入数据库。</p>
  </li>
  <li>
    <p>定期或事件驱动的持久化 (Periodic or Event-Driven)<br />
• 可以在系统中的某些关键点（如目标计划发生更新或Agent发生重要事件）时，调用 PersistenceManager.storeComponentData(eid, “Goal”) 这类接口进行落库。<br />
• 也可以在 CleanupSystem 或定时器里，让 StateManager 扫描含有”needsPersistence”标记的组件或实体，一次性写回数据库。<br />
• 此外，日志或审计数据（如动作历史、思考日志）也可在这里进行归档存储。</p>
  </li>
  <li>
    <p>退出或断点保存 (Manual or Shutdown Save)<br />
• 当服务器或进程要关闭时，通过 StateManager.saveAll() 将还没写入的数据统一写入数据库，以确保下次加载能恢复 ECS 状态。<br />
• 对于一些单机/离线场景，也可以手动触发存档。</p>
  </li>
</ol>

<hr />
<h5 id="完整示例流程">完整示例流程</h5>

<p>以下给一个简单的场景，演示组件和数据库交互的可能方式：</p>

<p>1) 启动时：</p>
<ul>
  <li>StateManager.queryDB(“SELECT * FROM agents”) → 得到一批 agent 记录，依次为每条记录创建 Entity (EID=x)，并给其初始化 Agent、Memory、Goal 等组件字段。</li>
  <li>同时从 “rooms” 表里加载房间信息，创建 Room 实体。</li>
</ul>

<p>2) 运行阶段：</p>
<ul>
  <li>PerceptionSystem 在某个房间检测到事件”MagicSword 出现”，写入 Perception.currentStimuli[eid]。</li>
  <li>ExperienceSystem 将 Stimuli 转化为 Experience，赋值到 Memory.experiences[eid]。</li>
  <li>ThinkingSystem 通过 Memory、Goal 等信息决定执行下一步行动，生成 Action.pendingAction[eid]。</li>
  <li>ActionSystem 执行该动作后，将结果写到 Memory 或 Action.lastActionResult。若这是一次重大剧情事件，会把 Memory.experiences[eid] 的最新部分标记为 needsPersistence。</li>
  <li>StateManager 在一段时间后发现 Memory.experiences[eid] 带有 “needsPersistence”，则将其写入数据库（INSERT INTO memory_experiences …）。</li>
</ul>

<p>3) 停止或断点：</p>
<ul>
  <li>基于 ECS 或系统调度，在”服务器关闭”时调用 StateManager.saveAll()，把仍在内存中的关键组件字段（Agent, Memory, Goal 等）它们的最新状态写进数据库。</li>
  <li>下次重启时，就能从数据库中加载并恢复 ECS 的世界状态。</li>
</ul>

<hr />

<p>• 将组件分类，既方便在项目中清晰地管理实体数据，也能帮助我们控制”需要持久化”与”仅在内存中存在”的数据边界。<br />
• 与数据库的交互通常由一个专门的 Manager（如 StateManager）来处理，Systems 在需要读写数据库时通过它进行操作，避免在 System 里直接写 SQL 或类似底层语句。<br />
• 这样能同时享受到 ECS 在逻辑上的高效与灵活，以及数据库带来的持久化、断点续跑与数据统计分析优势。</p>

<h2 id="五架构创新点">五、架构创新点</h2>

<p><img src="/assets/images/89-3.png" alt="" />
整个架构的亮点在于：
每个System都是独立运行的，不会跟其他的System之间有调用关系，因此即便我们希望实现Agent的”<strong>感知环境变化(Perception) → 记录或转化为内在经验(Experience) → 自我思考并决策(Thinking) → 付诸行动(Action) → 动态调整目标与计划(GoalPlanning + Planning) → 同步环境(Room) → 及时回收无用实体(Cleanup)</strong> “ 能力的时候，各个System在功能上会有很多互相依赖的点，但是我们依然可以通过ECS架构把整体结构成各个互不相关的System，每个System依然可以独立运行，不会跟其他的System有人和耦合关系。
我想这也是为什么Unity这几年越来越往ECS架构迁移最主要的原因。</p>

<p>而且比如我现在只是希望一个Agent拥有一些基本能力，我只需要在定义Entity的时候减少注册一些Component以及减少注册System就可以轻易的实现，都不用改几行代码。
如下图：</p>

<p><img src="/assets/images/89-4.png" alt="" />
同时如果你在开发过程中希望增加新的功能，也不会对其他的System有任何影响，可以很轻易的把自己希望的功能加载进去。
另外当前这种架构的性能其实会比传统面向对象架构的性能强很多，这在游戏圈是一个公认的事实，因为ECS的设计更加适合进行并发，那么当我们在复杂的Defai场景下，采用ECS架构也有可能会更有优势，特别是希望采用Agent做量化交易的场景下，ECS也会有用武之地（不仅仅是在Agent游戏场景下）。</p>

<p>从我个人的观点来看，这是一个极其模块化，性能极其优秀的框架，同时代码质量也很高并且包含了很好的设计文档，不过可惜的是 $project89 项目一直缺少对这个框架的宣传，因此我才花了很长的时间(4天)写了这篇文章，我觉得好的东西还是值得被发现，明天应该还会发一个英文版本，希望能有更多的游戏团队或者Defai 团队开到这个框架，为大家提供一种新的潜在的架构选择！</p>]]></content><author><name></name></author><category term="project89" /><category term="ai" /><category term="agent" /><category term="project89" /><category term="analysis" /><category term="architecture" /><category term="ecs" /><summary type="html"><![CDATA[先说结论，project89 采用一种全新的方式来设计Agent Framework, 这是一个针对游戏开发的高性能的Agent Framework,与目前使用的Agent Framework相比有更好的性能。]]></summary></entry><entry><title type="html">Buzz Swarm Architecture：如何优雅的实现</title><link href="/2023/10/01/buzz-swarm-architecture/" rel="alternate" type="text/html" title="Buzz Swarm Architecture：如何优雅的实现" /><published>2023-10-01T02:00:00+00:00</published><updated>2023-10-01T02:00:00+00:00</updated><id>/2023/10/01/buzz-swarm-architecture</id><content type="html" xml:base="/2023/10/01/buzz-swarm-architecture/"><![CDATA[<p>『Buzz 之 Swarm 如何优雅的实现』
昨日副标题 『 为何在buzz上亏钱 』
今日副标题 『 仓位不够大 』</p>

<p>buzz 如我上一条推特所说，已经切换成多个Agent互相协作的架构，目前是分为9个Agent来处理任务
<img src="/assets/images/agents.png" alt="agents" /></p>

<p>比如我们举一个例子来理解这个调用过程：</p>
<ul>
  <li>Agent描述
Market Agent：负责获取代币信息，市场趋势
Trading Agent： 负责执行交易，比如swap交易，提供流动性交易，stake交易等等
Social Agent: 负责获取社交媒体上的信息
Boss Agent: 负责把用户的任务分配给对应的Agent去执行</li>
  <li>任务描述
帮我获取推特上关于$ai16z的信息并且判断是否值得买入，如果可以买入帮我买入0.01sol.</li>
  <li>执行过程
那么这个任务，boss agent会判断任务要先分配给哪个Agent,当前这个任务会判断先分配给到Social Agent，然后social agent执行完成后会调用Trading Agent继续执行, Trading Agent会根据 Social Agent的输出来判断是否发起交易行为。</li>
</ul>

<p><img src="/assets/images/buzz-swarms-pic.png" alt="buzz swarms pic" /></p>

<p>那么Buzz是怎么实现这个东西的：</p>
<ol>
  <li>首先在原来Agent的Tools上增加了 Invoke Tool,一个Agent实例可以通过这个tool来调用其他Agent
<img src="/assets/images/buzz-app-framework.png" alt="buzz app framework" /></li>
  <li>在最新的代码里，其实把整个Hive的逻辑分成了9个Agent,同时在这些Agent之间实现了互相调用</li>
</ol>

<p>同时如果这些Agent在初始化的时候注册了Invoke-agent-tool, 那么它就拥有调用其他agent的能力。</p>

<p>比如下面这个例子，就是在trading_agent的system_prompt里同时注册了solana-trade-tool 和 invoke-agent-tool,
<img src="/assets/images/trading-agent-prompt.png" alt="trading agent prompt" />
https://github.com/jasonhedman/the-hive/commit/cb3d79639382c2041a553bb06c89a4968f3bc1ed#diff-63b10dae85e24cd77d9b8e3dd074449ef69ea21d84b10fb1ab2e5ce40a3f7b78R7</p>

<ol>
  <li>
    <p>接下来我们看 invoke-agent-tool的具体实现
核心是system_prompt如下，核心在最后一行，把能调用的agent和这个agent的能力嵌入到这个prompt里
<img src="/assets/images/Invoke-agent-prompt.png" alt="Invoke agent prompt" />
https://github.com/jasonhedman/the-hive/commit/cb3d79639382c2041a553bb06c89a4968f3bc1ed#diff-55697936e4c9080cbc4c5060b409aae2fc7ad75c25cd2d27cf5569581023b530R3</p>
  </li>
  <li>
    <p>同时还有一个chooseAgent来判断先调用哪个Agent
<img src="/assets/images/hive-route.png" alt="hive route" />
主要关注下图的system_prompt,描述了当前的系统里拥有哪些agent可以供当前这个Boss Agent调用，所以Boss Agent在这里工作的关键在于
<img src="/assets/images/choose-agent.png" alt="choose agent" /></p>
  </li>
  <li>
    <p>最后在前端按照调用agent的顺序，把每个Agent的结果拼接后显示给用户
<img src="/assets/images/agg-output.png" alt="agg output" /></p>
  </li>
</ol>

<p>于是我们就可以得到这样的效果：
<img src="/assets/images/hive-message.png" alt="hive message" /></p>

<p>总结 Buzz Swarm的流程如下： 
<img src="/assets/images/buzz-swarm-framework.png" alt="buzz swarm framework" />
其中的Boss Agent负责判断哪个Agent第一个来执行任务，并且把任务分配给第一个Agent,第一个Agent执行完成之后再调用invoke-agent-tool来调用下一个Agent进行执行，并依次不断重复这个过程，直到任务执行完成。</p>

<p>不过目前整个Swarm架构还没有很完善，有些时候会有一些bug,同时对于越来越复杂的defai的场景来看，以及未来甚至需要支持并行执行一些任务的趋势来看，现在这个Swarm架构其实还不足以应对未来的所有场景，期待Buzz Swarm的进一步进化～</p>]]></content><author><name></name></author><category term="web3" /><category term="agent" /><category term="swarm" /><category term="ai" /><category term="buzz" /><category term="architecture" /><summary type="html"><![CDATA[『Buzz 之 Swarm 如何优雅的实现』 昨日副标题 『 为何在buzz上亏钱 』 今日副标题 『 仓位不够大 』]]></summary></entry></feed>