AI Agent Engineer

AI Agent Engineer

工程与安全学习导航

4 min read

工程与安全学习导航

前面的文档回答了“nanobot 如何完成一次 Turn”。这一部分换一个角度：当多个请求同时到达、用户中途停止、Provider 暂时失败、进程被关闭，或者模型试图访问工作区之外时，系统怎样避免混乱和数据损坏？

对应源码

风险主题源码
并发、取消和 Turn 资源nanobot/agent/loop.py、nanobot/agent/runner.py
Provider、Tool 和持久化错误nanobot/providers/base.py、nanobot/agent/tools/、nanobot/session/manager.py
可观测性和测试nanobot/bus/runtime_events.py、nanobot/agent/hook.py、tests/
Workspace、Shell 和 SSRFnanobot/security/、nanobot/agent/tools/shell.py、sandbox.py
打包和前端构建pyproject.toml、hatch_build.py、webui/、nanobot/web/

学习目标

完成本部分后，你应当能够：

  • 画出 nanobot 的主要并发边界；
  • 区分超时、取消、可恢复错误和不可恢复错误；
  • 根据日志、状态轨迹、Runtime Event 和持久化文件选择观察点；
  • 解释 workspace guard、shell sandbox 和 SSRF guard 各自保护什么；
  • 理解 Python 包、WebUI 静态资源和 Bridge 如何进入发布产物。

前置知识

推荐顺序

顺序文档核心问题
1asyncio 并发、取消与资源清理哪些任务能并行，哪些必须串行？
2错误、重试与数据一致性失败后应该重试、降级、保存还是终止？
3日志、RuntimeEvent 与测试策略应该观察哪一层证据？
4Workspace、Shell 与 SSRF 安全边界“限制到工作区”到底保证了什么？
5打包、WebUI 构建与跨平台源码如何变成可安装、可运行的产品？

一张工程风险地图

flowchart LR
    A["并发请求"] --> A1["Session Lock"]
    A --> A2["全局 Semaphore"]
    A --> A3["Tool concurrency_safe"]

    B["中断与关闭"] --> B1["Task.cancel"]
    B --> B2["恢复运行 checkpoint"]
    B --> B3["关闭 MCP / Channel"]
    B --> B4["Session flush_all"]

    C["外部失败"] --> C1["Provider retry"]
    C --> C2["Fallback"]
    C --> C3["错误转为可见结果"]

    D["不可信输入"] --> D1["Tool schema"]
    D --> D2["Workspace guard"]
    D --> D3["SSRF guard"]
    D --> D4["Shell sandbox"]

    E["进程崩溃"] --> E1["临时文件"]
    E --> E2["os.replace"]
    E --> E3["必要时 fsync"]

这张图中的机制不是同一个“安全层”。例如，Session Lock 解决同一会话并发写入问题，却不会阻止模型读取私有文件；SSRF guard 阻止内网目标，却不会限制普通公网请求的内容。

本部分的事实边界

应用级 guard 不等于操作系统隔离

当 restrictToWorkspace 开启但没有系统 sandbox 时，nanobot 会通过路径解析和命令检查实施应用级限制。源码明确把这种状态标为 application 且 enforced=False。不要把它描述成不可绕过的 OS 安全边界。

没有统一的“事务层”

Session、Cron、Memory、配置和 WebUI 状态分别采用自己的写入策略。某个文件使用了 os.replace，不能推出所有状态都具备相同耐久性。

主要源码入口

  • nanobot/agent/loop.py
  • nanobot/agent/runner.py
  • nanobot/providers/base.py
  • nanobot/session/manager.py
  • nanobot/cron/service.py
  • nanobot/agent/tools/shell.py
  • nanobot/agent/tools/sandbox.py
  • nanobot/security/workspace_access.py
  • nanobot/security/workspace_policy.py
  • nanobot/security/network.py
  • nanobot/cli/commands.py
  • pyproject.toml
  • webui/vite.config.ts

下一篇：asyncio 并发、取消与资源清理

Backlinks