nanobot 与 Agent 开发术语表
核心执行
| 术语 | 在本库中的含义 | 当前源码锚点 |
|---|
| Agent | 接收目标，组合模型、上下文和工具并推进任务的软件运行体；不等同于单次 LLM 请求 | nanobot/agent/loop.py、nanobot/agent/runner.py |
| Turn | 一条入站消息触发的一次顶层处理生命周期；内部可以有多轮模型调用和 Tool Call | AgentLoop._process_message() |
| AgentLoop | 管理 Turn 外层状态、Session、命令、持久化、响应和并发边界 | nanobot/agent/loop.py::AgentLoop |
| AgentRunner | 在一次运行中反复调用 Provider、解析 Tool Call、执行工具并把结果回填给模型 | nanobot/agent/runner.py::AgentRunner |
| ContextBuilder | 把系统提示、workspace 文件、Skills、历史和本轮输入组装为模型上下文 | nanobot/agent/context.py::ContextBuilder |
| Provider | 把 nanobot 的统一模型请求/响应契约适配到具体模型后端 | nanobot/providers/base.py::LLMProvider |
LLMResponse | Provider 返回给 Runner 的统一响应对象，包含文本、reasoning、tool calls、usage 等 | nanobot/providers/base.py::LLMResponse |
| Tool Call | 模型请求宿主执行某个工具的结构化动作；不是模型自己执行 Python 或 shell | nanobot/providers/base.py::ToolCallRequest |
| stop reason | Runner 结束本次运行的原因，而不只是最终文本 | nanobot/agent/runner.py、AgentRunResult.stop_reason |
消息、事件与会话
| 术语 | 含义 | 当前源码锚点 |
|---|
InboundMessage | 入口送入核心的业务消息，含 channel、sender、chat、content、media、metadata | nanobot/bus/events.py |
OutboundMessage | 核心交给 Channel 或直接调用方的用户可见输出 | nanobot/bus/events.py |
| MessageBus | 入站和出站业务消息的异步队列 | nanobot/bus/queue.py::MessageBus |
| RuntimeEventBus | 进程内运行状态发布/订阅总线；不承载普通聊天正文 | nanobot/bus/runtime_events.py::RuntimeEventBus |
| Session | 可持久化的对话历史和 metadata；用于跨 Turn 恢复 | nanobot/session/manager.py::Session |
| Session key | Session 的逻辑标识；默认由 channel:chat_id 组成，也可覆盖 | nanobot/session/keys.py、InboundMessage.session_key |
| model context | 某次 Provider 调用实际收到的 messages、system prompt 和工具 schema | nanobot/agent/context.py、nanobot/agent/runner.py |
| checkpoint | Tool 执行过程中的临时恢复点，用于取消或异常后的上下文保护 | nanobot/agent/runner.py::_emit_checkpoint、nanobot/agent/loop.py::_restore_runtime_checkpoint |
| compaction | 在 token/空闲边界下压缩会话历史，减少后续上下文负担 | nanobot/agent/memory.py::Consolidator、nanobot/agent/autocompact.py |
| Memory | workspace 中供 Agent 长期读写的知识材料；不等于原始 Session 历史 | nanobot/agent/memory.py |
| Dream | 周期性启动隔离会话、调用 Agent 整理长期记忆的机制 | nanobot/agent/memory.py 中的 Dream helpers、nanobot/cli/commands.py 中的系统任务 |
能力与扩展
| 术语 | 含义 | 最适合解决的问题 |
|---|
| Tool | 有明确 JSON schema、由宿主执行并返回结构化/文本结果的动作 | “让 Agent 做一个确定动作” |
| ToolRegistry | 注册、列出、校验和执行 Tool 的运行时容器 | 统一工具契约 |
| Tool loader | 发现内置 Tool、包模块和 nanobot.tools entry point | 插件式接入 Tool |
| Skill | 注入给模型的说明、流程和资源，指导模型怎样完成一类任务 | “教 Agent 如何做” |
| MCP | 连接外部 MCP server 并把远程能力包装为 nanobot Tool | 复用独立工具服务 |
| Provider | 模型后端协议适配 | 更换或新增 LLM 后端 |
| Channel | 外部聊天平台与 InboundMessage/OutboundMessage 之间的适配 | 接入新的消息平台 |
| Gateway | 组合 AgentLoop、Channel、Cron、Heartbeat、WebUI 等长运行服务 | 多入口常驻运行 |
| SDK | 在 Python 进程中调用 nanobot runtime 的公共接口 | 嵌入 Python 应用 |
| HTTP API | OpenAI-compatible 的网络接口 | 让外部程序经 HTTP 调用 |
长期运行
| 术语 | 含义 | 不应混淆为 |
|---|
| Goal | 保存在 Session metadata 中的持续目标状态 | 普通的一次性 prompt |
| Continuation | 在同一顶层 Turn 内继续下一段 Agent 运行的控制边界 | 新用户消息 |
| Subagent | 由主 Agent 派生、具有独立执行上下文的子任务运行体 | 普通并行 Tool |
| Cron | 按 at、every 或 cron 表达式触发动作的持久化调度 | Heartbeat 本身 |
| Heartbeat | 当前由 Cron 支撑的周期性检查/唤醒机制 | 操作系统健康检查 |
安全与可靠性
| 术语 | 含义 | 边界 |
|---|
| workspace restriction | 应用层路径策略，尽量把文件类 Tool 限制在 workspace | 不自动等于 OS 隔离 |
| sandbox | 通过更强执行边界约束命令/文件/网络；当前 bwrap 路径依赖 Linux/container 条件 | Windows 配置名不代表已生效 |
| SSRF | 服务端被诱导访问本机、内网、保留地址或不安全重定向 | 需要 URL、DNS 和重定向多层检查 |
| fallback | 主 Provider 失败时依次尝试候选模型/Provider | 不保证所有错误都应切换 |
| retry | 对同一 Provider/动作的可重试失败再次尝试 | 不等于 fallback |
| atomic write | 先写临时文件再替换目标，避免只写入半份状态 | 不自动保证跨多个文件的事务 |
最容易混淆的关系
flowchart LR
A["Turn<br/>一次顶层生命周期"] --> B["多次 Provider 调用"]
B --> C["零或多次 Tool Call"]
D["Session<br/>持久化历史"] --> E["ContextBuilder 选取/加工"]
E --> F["Model context<br/>本次实际输入"]
G["MessageBus<br/>业务消息"] -.不同.-> H["RuntimeEventBus<br/>运行状态"]
I["Skill<br/>教模型怎么做"] -.不同.-> J["Tool<br/>宿主执行动作"]
J -.远程来源之一.-> K["MCP server"]
返回：速查参考