nanobot 架构解析
上级索引：00-概览与索引
🗺️ 核心数据流
Channel（CLI/WebUI/聊天App）
→ MessageBus（InboundMessage）
→ AgentLoop（session, workspace, context 管理）
→ AgentRunner（provider/tool 循环）
→ Provider（LLM 后端）
→ Tools（files, shell, web, MCP, cron...）
→ AgentLoop 读写 State（Session, memory, hooks, skills）
→ MessageBus（OutboundMessage）
→ Channel（回复）
🔧 两大核心组件
| 组件 | 文件 | 职责 |
|---|---|---|
| AgentLoop | agent/loop.py | 面向 Channel，管理 session key 选择、workspace 范围、context 构建、hooks 注册、outbound 发布 |
| AgentRunner | agent/runner.py | 面向 Model，管理 provider 调用、streaming delta 处理、tool call 执行、结果回注、迭代终止 |
调试原则：Channel 路由/session/outbound 问题看
loop.py；provider 调用/tool 执行/streaming 问题看runner.py
📁 文件结构
nanobot/
├── agent/
│ ├── loop.py # AgentLoop - channel 侧 turn 编排
│ ├── runner.py # AgentRunner - model/tool 循环
│ ├── context.py # ContextBuilder - 上下文构建
│ ├── memory.py # 长期记忆 + Dream 周期任务
│ └── tools/
│ ├── base.py # Tool 基类和 schema
│ ├── registry.py # Tool 自动发现
│ ├── shell.py # Shell 执行（含沙箱）
│ ├── filesystem.py# 文件系统工具
│ ├── web.py # Web 搜索/抓取（含 SSRF 检查）
│ ├── mcp.py # MCP 工具集成
│ ├── cron.py # 定时任务
│ ├── image_generation.py
│ └── self.py # 运行时自检
├── providers/
│ └── registry.py # 所有 Provider 元数据集中注册
├── channels/
│ ├── base.py # Channel 基类合约
│ ├── manager.py # Channel 发现和生命周期管理
│ └── websocket/ # WebUI/WebSocket channel
├── session/
│ └── manager.py # Session 存储和压缩
├── config/
│ ├── schema.py # 配置 schema（camelCase/snake_case 均支持）
│ ├── loader.py # 配置加载和保存
│ └── paths.py # 运行时路径助手
├── security/
│ ├── workspace_access.py # Workspace 访问范围
│ ├── workspace_policy.py # Workspace 策略
│ └── network.py # SSRF/网络检查
├── cron/ # 定时任务服务
├── bus/
│ ├── events.py # InboundMessage/OutboundMessage 事件定义
│ └── queue.py # 消息队列
└── web/dist/ # 打包的 WebUI（生产构建）
🚪 入口模式
| 入口 | 命令 | 适用场景 |
|---|---|---|
| CLI 单次 | nanobot agent -m "..." | 脚本、快速问答、初次验证 |
| CLI 交互 | nanobot agent | 终端持续对话，保留 session 历史 |
| Gateway | nanobot gateway | 聊天 App、WebUI、定时任务、长运行服务 |
| OpenAI 兼容 API | nanobot serve | 程序化调用 /v1/chat/completions |
| WebUI | nanobot webui | 浏览器工作台，自动打开 WebUI |
🔌 扩展点
- 自定义 Tool：继承
agent/tools/base.py的 Tool 基类，放入tools/目录或通过 plugin entry points 注册，自动发现 - 自定义 Channel：继承
channels/base.py的 Channel 基类 - Skills：放在
<workspace>/skills/或nanobot/skills/下的 Markdown 技能文件，Agent 按需加载 - MCP Server：通过
tools.mcpServers配置接入任意第三方 MCP Server
🌐 网络端口
| 端口 | 用途 |
|---|---|
18790 | Gateway health endpoint（/health） |
8765 | WebUI / WebSocket |
📝 个人笔记
{{待填：阅读源码后的理解和疑问}}