AI代理系统¶

📎 引用文件

本文引用的文件 - loop.py - context.py - memory.py - tools.py - chat.py - llm.py - persistent.py - skills.py - service.py - __init__.py

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考量
故障排除指南
结论
附录：使用示例与最佳实践

简介¶

本文件为 Vibe-Trading 的 AI 代理系统提供系统化、可操作的技术文档。重点覆盖以下能力与机制： - 基于自然语言的智能研究与策略开发（含回测验证） - Agent 核心循环（ReAct）与上下文管理 - 工具注册与发现、工具调用流程与安全控制 - 会话状态管理与持久化记忆 - 与 LLM 提供商的集成方式、流式推理与重试 - 性能优化策略、故障排查与最佳实践

该系统通过“五层上下文压缩”、“并行只读工具执行”、“结构化摘要更新”、“跨会话持久记忆”和“安全沙箱化的工具白名单”，在长对话与复杂金融任务中保持稳定、可控与可追溯。

项目结构¶

围绕 AgentLoop 的核心代码位于 agent/src/agent，配合 providers、session、memory、tools 等模块构成完整闭环： - agent/src/agent：AgentLoop、ContextBuilder、SkillsLoader、WorkspaceMemory、工具基类与注册表 - agent/src/providers：ChatLLM、LLM 工厂与多提供商适配 - agent/src/session：会话生命周期编排、SSE 事件总线、消息历史与尝试（Attempt）管理 - agent/src/memory：跨会话持久化记忆（文件索引、语义链接、FTS 搜索） - agent/src/tools：自动发现与构建工具注册表，支持 MCP 远程工具注入与安全过滤

graph TB A["用户输入"] --> B["SessionService 会话编排"] B --> C["ToolRegistry 工具注册表"] B --> D["ChatLLM 聊天客户端"] B --> E["PersistentMemory 持久记忆"] B --> F["AgentLoop ReAct 核心循环"] F --> G["ContextBuilder 上下文构建"] F --> H["工具执行 读写批处理/并发"] F --> I["TraceWriter 运行轨迹"] F --> J["GroundingLedger 归因记录"] D --> K["LLM 工厂 providers/llm.py"]

图表来源 - service.py:158-440 - loop.py:502-750 - context.py:210-322 - tools.py:54-95 - chat.py:272-397 - llm.py:89-423

章节来源 - service.py:158-440 - loop.py:502-750 - context.py:210-322 - tools.py:54-95 - chat.py:272-397 - llm.py:89-423

核心组件¶

AgentLoop：实现 ReAct 主循环，负责消息迭代、上下文压缩、工具调度、追踪与终止条件。
ContextBuilder：组装系统提示词、技能描述、工具描述、工作区状态与持久记忆快照，生成 OpenAI 格式消息列表。
ToolRegistry + BaseTool：统一工具抽象、自动发现、参数校验、执行封装与错误返回。
ChatLLM：对 LangChain 的封装，支持函数调用、流式输出、DSML 解析、内容过滤与 Provider 错误包装。
PersistentMemory：跨会话的文件级记忆存储，支持重要性衰减、去重、FTS 检索与语义链接。
SessionService：会话生命周期管理、并发限制、SSE 事件广播、消息历史与指标加载。

章节来源 - loop.py:502-750 - context.py:210-322 - tools.py:13-95 - chat.py:272-397 - persistent.py:196-438 - service.py:158-440

架构总览¶

下图展示从用户输入到最终输出的端到端流程，包括 ReAct 循环、上下文构建、工具执行、记忆存取与 SSE 事件推送。

sequenceDiagram participant U as "用户" participant S as "SessionService" participant R as "ToolRegistry" participant L as "ChatLLM" participant A as "AgentLoop" participant C as "ContextBuilder" participant M as "PersistentMemory" participant T as "工具执行" U->>S : 发送消息 S->>R : 构建工具注册表(本地+MCP) S->>A : 创建并运行 AgentLoop A->>C : 构建系统提示与消息 C-->>A : 消息列表 A->>L : 流式/同步调用(带工具定义) L-->>A : 文本/思考/工具调用请求 alt 需要工具 A->>T : 执行工具(只读并行/写串行) T-->>A : 结果(JSON/错误) A->>C : 格式化工具结果 A->>L : 继续下一轮(携带结果) else 直接回答 A-->>S : 最终文本 end S-->>U : SSE 事件(文本增量/工具调用/完成)

图表来源 - service.py:158-440 - loop.py:624-800 - context.py:286-322 - chat.py:299-397 - tools.py:66-245

详细组件分析¶

AgentLoop（ReAct 核心循环）¶

五层上下文管理：
微压缩：仅清理旧工具结果，保留最近 N 条
上下文折叠：对长文本进行首尾保留、中间折叠（零 API 成本）
自动摘要：超过阈值时触发 LLM 结构化摘要，带尾部预算保护
显式压缩工具：模型主动调用 compact 工具触发摘要
迭代更新：第 N 次压缩更新前一次摘要而非从头开始
工具执行：
连续只读工具并行执行（线程池），写操作串行
超时、取消、重试、内容过滤熔断
追踪与归因：
TraceWriter 写入 trace.jsonl
GroundingLedger 记录数据来源与引用
run_manifest.json 记录系统提示哈希、工具集、包版本

flowchart TD Start(["进入循环"]) --> Estimate["估计消息 token 数"] Estimate --> Check1{"是否超过阈值 50%?"} Check1 -- 是 --> Micro["微压缩：清理旧工具结果"] Check1 -- 否 --> CollapseCheck Micro --> CollapseCheck{"是否超过阈值 70%?"} CollapseCheck -- 是 --> Collapse["上下文折叠：长文本首尾保留"] CollapseCheck -- 否 --> AutoCheck{"是否超过阈值 100%?"} Collapse --> AutoCheck AutoCheck -- 是 --> AutoCompact["自动摘要：LLM 结构化总结"] AutoCheck -- 否 --> NextIter["下一轮迭代"] AutoCompact --> NextIter NextIter --> End(["结束或继续"])

图表来源 - loop.py:227-322 - loop.py:727-749

章节来源 - loop.py:227-322 - loop.py:502-750

上下文管理（ContextBuilder）¶

系统提示词模板包含：
输出原则（数据溯源、as-of 标注、证据优先、分析非建议、深度匹配、拒绝越界）
工具与技能描述（动态注入）
工作区状态摘要（run_dir、计数器）
持久记忆快照（可选）
自动召回：根据用户消息检索相关记忆片段并注入
工具结果与助手消息格式化：兼容 provider 差异（reasoning_content、tool_calls、extra_content）

classDiagram class ContextBuilder { +build_system_prompt(user_message) str +build_messages(user_message, history) List[Dict] +_format_tool_descriptions() str +format_tool_result(tool_call_id, tool_name, result) Dict +format_assistant_tool_calls(tool_calls, content, reasoning_content) Dict } class WorkspaceMemory { +run_dir str +counters dict +increment(key) int +to_summary() str } class SkillsLoader { +get_descriptions() str +get_content(name) str } ContextBuilder --> WorkspaceMemory : "读取状态摘要" ContextBuilder --> SkillsLoader : "获取技能描述"

图表来源 - context.py:210-322 - memory.py:13-54 - skills.py:100-189

章节来源 - context.py:210-322 - memory.py:13-54 - skills.py:100-189

工具注册与发现（ToolRegistry + build_registry）¶

自动发现：扫描 src/tools 下所有模块，收集 BaseTool 子类并注册
安全策略：
shell 工具默认禁用，需显式开启
check_available 用于依赖检查（如 API Key、包缺失）
会话注入：目标工具（如 goal、autopilot）注入 session_id 与事件回调
MCP 集成：
按配置追加远程工具，失败隔离不影响本地工具
实时券商通道受 mandate/kill switch 保护，未授权跳过

flowchart TD A["build_registry()"] --> B["扫描 src/tools 模块"] B --> C{"check_available()"} C -- 通过 --> D["注册工具到 ToolRegistry"] C -- 不通过 --> E["跳过该工具"] D --> F{"是否配置 MCP 服务器?"} F -- 是 --> G["构建 MCP 工具包装器"] G --> H{"是否实时券商?"} H -- 是 --> I["检查授权/交互模式"] I -- 通过 --> J["注册包装工具"] I -- 不通过 --> K["跳过并告警"] H -- 否 --> J F -- 否 --> L["返回注册表"] J --> L

图表来源 - __init__.py:33-245 - tools.py:54-95

章节来源 - __init__.py:33-245 - tools.py:54-95

会话状态管理与持久化存储（SessionService + PersistentMemory）¶

会话服务：
并发限制：每会话一个 AgentLoop，防止消息交错
事件总线：SSE 推送 message.received、attempt.started/completed/cancelled/failed
指标加载：从 artifacts/metrics.csv 提取回测指标
持久记忆：
文件索引 MEMORY.md，条目 .md 文件含 frontmatter
重要性衰减（访问频率、时间）、去重窗口、FTS 搜索、语义链接扩展
层级目录与压缩级别（raw/daily/digest）

sequenceDiagram participant U as "用户" participant S as "SessionService" participant P as "PersistentMemory" participant A as "AgentLoop" U->>S : 发送消息 S->>P : 自动召回相关记忆 S->>A : 运行 AgentLoop A-->>S : 工具调用/结果/最终答案 S-->>U : SSE 事件(文本增量/工具/完成) Note over P,S : 记忆写入/索引更新/链接维护

图表来源 - service.py:158-440 - persistent.py:196-438

章节来源 - service.py:158-440 - persistent.py:196-438

与 LLM 提供商的集成（ChatLLM + llm.py）¶

统一接口：chat/stream_chat，支持函数调用、流式文本与推理内容
多提供商适配：
OpenAI 兼容、Anthropic、DeepSeek 原生/兼容路径
自定义头部隔离、代理禁用、温度字段自适应
健壮性：
无流响应降级为非流调用
ProviderStreamError 包装并提供可重试判断
DSML 工具调用解析（部分模型以文本形式返回）

classDiagram class ChatLLM { +chat(messages, tools, timeout) LLMResponse +stream_chat(messages, tools, on_text_chunk, on_reasoning_chunk, timeout, should_cancel) LLMResponse -_parse_response(ai_message) LLMResponse } class LLMFactory { +build_llm(model_name) Any } ChatLLM --> LLMFactory : "获取底层模型"

图表来源 - chat.py:272-397 - llm.py:89-423

章节来源 - chat.py:272-397 - llm.py:89-423

依赖关系分析¶

AgentLoop 依赖：
ContextBuilder（上下文构建）
ToolRegistry（工具执行）
ChatLLM（模型调用）
PersistentMemory（跨会话记忆）
TraceWriter/GroundingLedger（追踪与归因）
SessionService 依赖：
ToolRegistry（构建工具集）
ChatLLM（模型实例）
PersistentMemory（记忆注入）
EventBus（SSE 事件）
工具注册表依赖：
BaseTool 子类（自动发现）
MCP 包装器（可选）
安全策略（shell 工具、实时券商）

graph LR S["SessionService"] --> R["ToolRegistry"] S --> L["ChatLLM"] S --> PM["PersistentMemory"] S --> AL["AgentLoop"] AL --> CB["ContextBuilder"] AL --> TR["ToolRegistry"] AL --> CHAT["ChatLLM"] AL --> MEM["WorkspaceMemory"] AL --> TRACE["TraceWriter"] AL --> GROUND["GroundingLedger"]

图表来源 - service.py:346-440 - loop.py:502-750 - tools.py:54-95 - context.py:210-322

章节来源 - service.py:346-440 - loop.py:502-750 - tools.py:54-95 - context.py:210-322

性能考量¶

上下文压缩分层：
微压缩与上下文折叠避免不必要的 LLM 调用
自动摘要带尾部预算，防止关键信息丢失
工具执行优化：
只读工具并行执行，减少等待时间
结果截断与分页，控制消息大小
流式输出与节流：
推理内容节流，降低 UI 回放缓冲压力
首次推理块立即发出，提升感知速度
资源限制：
会话并发限制（每会话一个 AgentLoop）
工具超时、重试与熔断（内容过滤）
记忆系统：
重要性衰减与去重窗口，减少冗余写入
FTS 搜索与语义链接，加速召回

[本节为通用指导，无需特定文件来源]

故障排除指南¶

工具不可用：
检查 check_available 返回（依赖缺失、API Key 未配置）
查看日志中的“工具不可用，跳过”
会话忙：
同一会话不允许并发 send_message，先取消或等待完成
流式失败：
ProviderStreamError 提供 provider/model 信息与可重试判断
无流响应自动降级为非流调用
内容过滤：
连续过滤触发熔断，调整输入或模型设置
记忆写入失败：
文件锁超时、权限问题，检查磁盘与路径
MCP 连接失败：
单个服务器失败不影响其他工具，查看警告日志

章节来源 - __init__.py:136-154 - service.py:43-50 - chat.py:117-163 - persistent.py:42-73

结论¶

Vibe-Trading 的 AI 代理系统通过 ReAct 循环、分层上下文管理、安全工具注册与发现、跨会话持久记忆以及健壮的 LLM 集成，实现了高可用、可扩展且可追溯的智能研究与策略开发平台。其设计兼顾了性能、安全与可维护性，适合复杂的金融分析与自动化交易研究场景。

[本节为总结，无需特定文件来源]

附录：使用示例与最佳实践¶

自然语言驱动的研究与策略开发¶

步骤概览： 1. 描述需求（如“分析某股票近一年走势并生成均值回归策略”） 2. Agent 自动识别任务类型，加载对应技能（如 strategy-generate） 3. 生成策略代码与配置，执行回测 4. 输出指标（收益率、夏普、最大回撤、交易次数） 5. 进行归因分析（交易归因、Beta 回归、 regime 分析、蒙特卡洛检验）
关键工具：
backtest、write_file、read_file、factor_analysis、options_pricing、market_data
注意事项：
每个数字必须指向具体工具调用
标注数据截止时间与来源
若工具失败，明确说明“未获取到”或“覆盖率截止于某日期”

章节来源 - context.py:23-200 - loop.py:727-749

回测验证与报告¶

自动生成 artifacts/metrics.csv，SessionService 自动加载指标
支持多层归因分析，按策略健康度路由不同分析层
输出 Markdown 表格，便于渲染与分享

章节来源 - service.py:567-581 - context.py:82-129

工具调用安全控制¶

Shell 工具默认禁用，需显式启用
实时券商通道需授权，未授权跳过并告警
工具参数校验与结果截断，防止溢出与泄露

章节来源 - __init__.py:136-154 - __init__.py:174-244

性能优化建议¶

合理设置 token 阈值，平衡上下文长度与成本
利用只读工具并行执行，缩短等待时间
使用流式输出与推理节流，提升用户体验
启用记忆衰减与去重，减少冗余写入

[本节为通用指导，无需特定文件来源]

← 语义搜索 Agent核心循环 →