DojoAgents 工具与执行沙箱完整指南：让 AI Agent 安全地写代码、算指标、抓数据
【免费下载链接】DojoAgentsDojoAgents: Full-Market AI Copilot for Personal Investment项目地址: https://gitcode.com/gh_mirrors/do/DojoAgents
DojoAgents 是一款面向个人投资的全市场 AI 副驾驶（AI Copilot）。它的核心能力之一，是让 AI Agent 在工具系统与执行沙箱的双重保护下，安全地写 Python 代码、计算金融指标、抓取行情与新闻数据。这篇指南面向新手，带你理解工具沙箱的设计思路，以及每个常用工具能做什么、边界在哪里。
为什么 Agent 的工具需要一个“执行沙箱”
让 AI 直接执行代码和命令，新手最担心三个问题：
- 失控执行——Agent 跑了一个死循环或耗时任务，卡死整个系统；
- 越权访问——Agent 读到、改到了不该碰的文件，或拿到不该有的网络权限；
- 噪音干扰——超长的终端输出、ANSI 颜色码、敏感信息，污染模型上下文。
DojoAgents 的答案是把"工具"和"沙箱"分开设计：
- **Tools（工具）**是 Agent 执行外部动作的标准接口，负责"能做什么"；
- **Sandbox（沙箱）**在执行前应用安全策略和超时边界，负责"做到什么程度为止"。
两者在 Tools 与 Sandbox 架构文档 中有完整定义。
工具系统四件套：从注册到执行
| 组件 | 职责 | 源码位置 |
|---|---|---|
ToolSpec | 工具的名称、描述、参数 schema、handler、沙箱策略 | dojoagents/tools/registry.py |
ToolRegistry | 工具的注册、查找、列出 | dojoagents/tools/registry.py |
ToolExecutor | 执行工具、捕获异常、规范化结果 | dojoagents/tools/executor.py |
SandboxPolicy | 工具调用的安全与超时策略 | dojoagents/tools/sandbox.py |
SandboxPolicy是一个简单的策略对象，四个字段划清边界：
| 字段 | 默认值 | 含义 |
|---|---|---|
allowed_roots | 空 | 允许访问的文件目录白名单 |
allow_network | False | 是否允许网络访问（默认关闭） |
allowed_commands | 空 | 允许执行的命令白名单 |
timeout_seconds | 120 | 单次工具调用超时（秒） |
执行流程在 ToolExecutor.execute_one() 中：先做沙箱策略检查，再用超时包装器运行工具 handler，任何异常都会被捕获并转成结构化的失败结果，而不是让进程崩溃。
核心工具逐个看
execute_code：写 Python 算指标
这是"算指标"的主力。Agent 提交的 Python 代码不会直接在主进程里运行，而是被包装后放进受控子进程执行：
- 白名单预加载：默认只预加载
pandas（别名pd）、numpy（np）、json等安全包，见 code_execution_tool.py； - 干净环境：子进程只保留 PATH、TZ、语言等最小环境变量，
HOME指向临时目录，避免代码"顺手"摸到宿主机的配置； - 金融数据入口：代码里可以直接
import dojo_tools，通过 dojoagents/tools/dojo_tools_stub.py 这个"桩模块"访问行情、财务等金融数据，而无需自己发 HTTP 请求。
terminal：安全地跑 shell 命令
terminal工具负责执行 shell 命令，见 terminal_tool.py：
- 命令在 BaseEnvironment 的统一封装中运行，超时（默认 120 秒）未到就自动终止，返回退出码
124； - 输出自动清洗：ANSI 颜色码被剥离，超长输出按"头 40% + 尾 60%"截断到 3 万字符以内，防止刷屏；
- 敏感信息脱敏：输出在返回前经过 dojoagents/agent/redact.py 的
redact_sensitive_text()处理； - 长任务可以
background=true放到后台进程注册表里跑，完成后再通知 Agent，不阻塞对话。
web_search 与 web_extract：两步抓取数据
抓数据走"搜索 → 提取"两步：
web_search：只返回结果的元数据行（标题、摘要、链接），轻量快速；web_extract：对选中的 URL 抓取并规范化整页内容。
定义在 dojoagents/tools/web_searcher.py。网络能力是否开启，由沙箱策略统一管控，默认是关闭的。
dojo.sdk.*：金融只读主路径
金融数据的主路径是dojo.sdk.*一族工具（只读，覆盖行情、财务、行业板块等），由 Runtime 通过get_dojo_sdk_specs()注册。工具结果最终统一规范化为ToolResult，可携带data（结构化数据）、viz_blocks（可视化块）、artifacts（产物引用）、resource_changes（资源刷新通知）等字段，前端按resource_changes刷新缓存，而不是按工具名猜副作用——契约细节见 工具契约参考。
write_session_file：把产物写回会话
当 Agent 算完指标、生成报告后，用write_session_file把 JSON/JSONL 等交付物写回会话目录（官方也特意提醒：写交付物请用它，而不是 terminal）。你上传的资料也会经过 dojoagents/tools/session_input_tool.py 被解析成 Agent 可读的输入。
五种执行环境：从本机到云端
同一套接口，可插拔地跑在不同执行环境里，源码都在 dojoagents/tools/environments/：
| 环境 | 适用场景 | 特点 |
|---|---|---|
Local | 日常开发 | 直接在宿主机 shell 执行，最简单 |
Docker | 需要隔离 | 自动起容器，把当前工作目录挂载到/workspace，命令互不干扰 |
SSH | 远程机器 | 命令发到远程主机执行 |
Modal | 云端算力 | 重计算任务丢到云端沙箱 |
Base | 所有环境 | 统一负责命令包装、超时、cwd 跟踪 |
例如 DockerEnvironment 会自动创建dojo-sandbox-*容器并把宿主机目录挂载进去——你在本地看到的结果和容器里跑的是一致的，但文件系统彼此隔离。
执行完之后，你会看到什么
- 成功：
ToolResult.ok=True，content是清洗后的文本，latency_ms记录耗时； - 超时：进程被强制终止，返回 "Command timed out" 和退出码
124； - 需要人确认：部分工具会抛出
AgentEscalationError，执行器把它转成"升级给用户"的结果而不是静默失败，见 dojoagents/tools/escalation.py。
也就是说，无论 Agent 做了什么，结果都是有界、可解释、可审计的。
常见问题速查
- 沙箱默认允许联网吗？不允许，
allow_network默认False，需要时在策略中显式开启。 - 超时是多久？默认 120 秒，可在
SandboxPolicy中调整；长任务建议用terminal的后台模式。 - execute_code 能 import 任意包吗？只有预加载白名单（pandas/numpy/json）开箱即用，其余受子进程环境限制。
- 怎么给 Agent 加工具？参考 添加工具 与 Tools 与 Sandbox 两份开发文档。
一句话总结：DojoAgents 用ToolSpec 声明能力、ToolRegistry 管理工具、ToolExecutor 统一执行、SandboxPolicy 划定边界，让 AI Agent 在个人投资场景里既能写代码、算指标、抓数据，又始终跑在安全笼子里。
【免费下载链接】DojoAgentsDojoAgents: Full-Market AI Copilot for Personal Investment项目地址: https://gitcode.com/gh_mirrors/do/DojoAgents
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考