nanobot 源码与测试索引
本表按“学习问题”组织，不按目录机械罗列。路径相对于 example/nanobot/code-EN。
入口与核心 Turn
| 问题 | 源码锚点 | 优先测试 | 对应讲解 |
|---|---|---|---|
| CLI 如何启动一次聊天？ | nanobot/cli/commands.py::agent | tests/cli/test_commands.py | 五个入口与运行边界 |
| Gateway 如何组装常驻服务？ | nanobot/cli/gateway.py、nanobot/gateway/runtime.py | tests/gateway/test_runtime.py、tests/cli/test_gateway_commands.py | Channel 与 Gateway |
| HTTP API 如何进入 Agent？ | nanobot/api/server.py::create_app、handle_chat_completions | tests/test_openai_api.py、tests/test_api_stream.py | HTTP API 与 Python SDK |
| Python SDK 如何建 runtime？ | nanobot/nanobot.py::Nanobot、nanobot/sdk/runtime.py | tests/test_nanobot_facade.py | 同上 |
| WebSocket 如何接收/发送？ | nanobot/channels/websocket.py::WebSocketChannel | tests/channels/test_websocket_integration.py | WebSocket 与 WebUI |
| 一次 Turn 的状态怎样推进？ | nanobot/agent/loop.py::AgentLoop._process_message | tests/agent/test_loop_runner_integration.py、test_loop_save_turn.py | AgentLoop 状态机 |
| 模型—工具循环如何结束？ | nanobot/agent/runner.py::AgentRunner.run | tests/agent/test_runner_core.py、test_runner_tool_execution.py | AgentRunner 的模型—工具循环 |
| system prompt 与历史怎样组成？ | nanobot/agent/context.py::ContextBuilder | tests/agent/test_context_builder.py、test_context_prompt_cache.py | ContextBuilder 与模型上下文 |
消息、事件与状态
| 问题 | 源码锚点 | 优先测试 | 对应讲解 |
|---|---|---|---|
| 入站/出站消息有哪些字段？ | nanobot/bus/events.py | tests/bus/、Channel tests | 消息、SessionKey 与入口 |
| 消息如何排队？ | nanobot/bus/queue.py::MessageBus | 相邻 AgentLoop/Channel integration tests | 同上 |
| Runtime Event 有哪些精确类型？ | nanobot/bus/runtime_events.py | tests/bus/test_runtime_events.py | 保存、响应与 RuntimeEvent |
| Session 如何保存、加载、锁定？ | nanobot/session/manager.py::SessionManager | tests/agent/test_session_atomic.py、test_session_manager_history.py | Session 文件与回放边界 |
| session key 如何规范化？ | nanobot/session/keys.py | tests/agent/test_unified_session.py | 消息、SessionKey 与入口 |
| 历史何时压缩？ | nanobot/agent/memory.py::Consolidator、nanobot/agent/autocompact.py | tests/agent/test_auto_compact.py、test_consolidator.py | Compaction、Memory 与 Dream |
| 持续目标怎样继续？ | nanobot/session/goal_state.py、turn_continuation.py | tests/agent/test_runner_goal_continue.py、test_loop_goal_wall_timeout.py | Goal 与 Continuation |
| Subagent 怎样创建和清理？ | nanobot/agent/subagent.py、agent/tools/spawn.py | tests/agent/test_subagent_lifecycle.py | Subagent 生命周期 |
Provider、Tool 与扩展
| 问题 | 源码锚点 | 优先测试 | 对应讲解 |
|---|---|---|---|
| Provider 的统一契约是什么？ | nanobot/providers/base.py::LLMProvider | tests/providers/ | Provider 解析与 Fallback |
| Provider 如何选择和实例化？ | nanobot/providers/registry.py、factory.py | tests/cli/test_commands.py、tests/agent/test_runtime_refresh.py | 同上 |
| fallback 如何串联？ | nanobot/providers/fallback_provider.py | tests/agent/test_runner_fallback.py | 同上 |
| Tool 契约是什么？ | nanobot/agent/tools/base.py::Tool | tests/tools/test_tool_validation.py | 新增 Tool |
| Tool 如何注册、校验、执行？ | nanobot/agent/tools/registry.py::ToolRegistry | tests/agent/test_runner_tool_execution.py | Tool 注册、校验与执行 |
| 外部 Tool 插件如何发现？ | nanobot/agent/tools/loader.py | tests/agent/test_tool_loader_entrypoints.py、test_tool_loader_scopes.py | 新增 Tool |
| Skill 如何发现和筛选？ | nanobot/agent/skills.py::SkillsLoader | tests/agent/test_skills_loader.py | 新增 Skill |
| MCP 如何连接和包装工具？ | nanobot/agent/tools/mcp.py | tests/agent/test_mcp_connection.py、test_mcp_transient_retry.py | 接入 MCP |
| Channel 如何发现？ | nanobot/channels/registry.py | tests/channels/test_channel_plugins.py | 新增 Channel |
| Channel 如何统一发送？ | nanobot/channels/base.py、manager.py | tests/channels/test_base_channel.py、test_channel_manager_delta_coalescing.py | Channel 与 Gateway |
自动化、工程与安全
| 问题 | 源码锚点 | 优先测试 | 对应讲解 |
|---|---|---|---|
| Cron 如何持久化和触发？ | nanobot/cron/service.py、types.py | tests/cron/ | Cron 与 Heartbeat |
| Heartbeat 如何接到 Cron？ | nanobot/cli/commands.py 中的 heartbeat job 组装、nanobot/cron/service.py | tests/agent/test_loop_cron_timezone.py、相邻 Cron tests | 同上 |
| 取消后怎样保护上下文？ | nanobot/agent/runner.py::_emit_checkpoint、nanobot/agent/loop.py::_restore_runtime_checkpoint | tests/agent/test_task_cancel.py、test_stop_preserves_context.py | asyncio 并发、取消与资源清理 |
| workspace 路径怎样限制？ | nanobot/security/workspace_policy.py、workspace_access.py | tests/agent/test_workspace_scope.py、tests/security/ | Workspace、Shell 与 SSRF 安全边界 |
| SSRF 怎样判断？ | nanobot/security/network.py | tests/security/ 与 web tool tests | 同上 |
| WebUI 怎样进入 Python 包？ | pyproject.toml、webui/、构建脚本 | packaging/build tests | 打包、WebUI 构建与跨平台 |
先读测试名，再读测试体
测试名通常直接表达维护者承诺的行为。先看 fixture、触发动作和断言，再回到实现，能显著减少从函数名猜设计的情况。
索引边界
- 这里不列出每个 Provider、Channel 或配置字段；完整清单见官方文档；
- 测试文件若随源码重组，应以当前
tests/目录和rg --files tests为准； - “相邻测试”表示行为可能跨多个测试层，不能只依赖一个文件证明全部边界。
返回：速查参考