{"repo": "bcefghj/learn-nanobot", "files": {"docs/06-install-and-hands-on/README.md": {"740d041a52e1d50499aabc70ec5bd6ae592737d0": {"t": 1785746516.4572914, "n": 15197, "h": "30d96d61f238da06", "c": "# 06 - 安装与上手\n\n> **阅读时间**：约 2 小时  \n> **前置知识**：[05 - MCP 协议详解](../05-mcp-protocol/README.md)  \n> **学习目标**：完成 Nanobot 的安装配置，运行你的第一个 AI Agent，理解全部配置项\n\n---\n\n## 目录\n\n- [6.1 为什么需要动手实践](#61-为什么需要动手实践)\n- [6.2 环境准备](#62-环境准备)\n- [6.3 安装 Nanobot](#63-安装-nanobot)\n- [6.4 配置向导 nanobot onboard](#64-配置向导-nanobot-onboard)\n- [6.5 config.json 配置详解](#65-configjson-配置详解)\n- [6.6 第一次运行：交互模式](#66-第一次运行交互模式)\n- [6.7 自定义 AGENTS.md：定义 Agent 身份](#67-自定义-agentsmd定义-agent-身份)\n- [6.8 引导文件体系](#68-引导文件体系)\n- [6.9 常见问题排错](#69-常见问题排错)\n- [6.10 实战练习](#610-实战练习)\n- [6.11 面试话术](#611-面试话术)\n- [6.12 本章小结](#612-本章小结)\n\n---\n\n## 6.1 为什么需要动手实践\n\n学习 AI Agent 框架，**纸上得来终觉浅**。在面试中，面试官最看重的不是你能背多少概念，而是：\n\n1. **你有没有真正用过？** —— 安装、配置、调试的全流程经验\n2. **你能不能描述细节？** —— 配置文件的字段含义、启动参数的作用\n3. **你遇到过什么问题？** —— 排错经历本身就是加分项\n\n> 💡 **面试真相**：一个能说出 \"我在配置 Nanobot 的 context_window_tokens 时发现设置过大会导致记忆压缩不触发\" 的候选人，比只能背概念的候选人强 10 倍。\n\n---\n\n## 6.2 环境准备\n\n### 6.2.1 系统要求\n\n| 项目 | 最低要求 | 推荐配置 |\n|------|---------|---------|\n| 操作系统 | macOS / Linux / Windows (WSL) | macOS / Ubuntu 22.04+ |\n| Python | 3.10+ | 3.11 或 3.12 |\n| 内存 | 4 GB | 8 GB+ |\n| 磁盘空间 | 500 MB | 2 GB+ |\n| 网络 | 可访问 LLM API | 稳定的国际网络 |\n\n### 6.2.2 Python 环境配置\n\n**方式一：使用系统 Python（简单）**\n\n```bash\n# 检查 Python 版本\npython3 --version\n# 输出应为 Python 3.10.x 或更高\n\n# 如果版本过低，使用 pyenv 安装\ncurl https://pyenv.run | bash\npyenv install 3.12.0\npyenv global 3.12.0\n```\n\n**方式二：使用 Conda（推荐隔离环境）**\n\n```bash\n# 创建独立环境\nconda create -n nanobot python=3.12 -y\nconda activate nanobot\n\n# 验证\npython --version\n# Python 3.12.x\n```\n\n**方式三：使用 uv（最快，推荐）**\n\n```bash\n# 安装 uv（Rust 编写的超快 Python 包管理器）\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 验证\nuv --version\n```\n\n> 💡 **面试加分**：uv 是 Astral 公司用 Rust 编写的 Python 包管理工具，安装速度比 pip 快 10-100 倍。Nanobot 官方推荐使用 uv。\n\n### 6.2.3 LLM API Key 准备\n\nNanobot 需要连接大语言模型 API，支持多种 Provider：\n\n| Provider | 获取方式 | 推荐度 |\n|----------|---------|--------|\n| OpenAI | [platform.openai.com](https://platform.openai.com) | 首选 |\n| Anthropic (Claude) | [console.anthropic.com](https://console.anthropic.com) | 推荐 |\n| DeepSeek | [platform.deepseek.com](https://platform.deepseek.com) | 国内友好 |\n| OpenRouter | [openrouter.ai](https://openrouter.ai) | 聚合多模型 |\n| 本地模型 (Ollama) | [ollama.com](https://ollama.com) | 免费、离线 |\n\n```bash\n# 准备好你的 API Key\nexport OPENAI_API_KEY=\"sk-xxxxxxxxxxxxxxxxxxxxxxxx\"\n\n# 或者使用 DeepSeek（国内推荐）\nexport DEEPSEEK_API_KEY=\"sk-xxxxxxxxxxxxxxxxxxxxxxxx\"\n```\n\n---\n\n## 6.3 安装 Nanobot\n\n### 6.3.1 方式一：pip 安装（通用）\n\n```bash\n# 安装最新版\npip install nanobot-ai\n\n# 验证安装\nnanobot --version\n\n# 查看帮助\nnanobot --help\n```\n\n### 6.3.2 方式二：uv 工具安装（推荐）\n\n```bash\n# 使用 uv 安装为全局工具\nuv tool install nanobot-ai\n\n# 验证\nnanobot --version\n```\n\n> **uv tool install vs pip install 的区别**：\n> - `uv tool install` 会创建独立的虚拟环境，不污染全局 Python 环境\n> - `pip install` 直接安装到当前 Python 环境\n> - 推荐使用 uv，尤其是需要在多个项目中使用不同版本时\n\n### 6.3.3 方式三：从源码安装（开发者）\n\n```bash\n# 克隆源码\ngit clone https://github.com/HKUDS/nanobot.git\ncd nanobot\n\n# 使用 uv 安装开发依赖\nuv sync --dev\n\n# 或使用 pip\npip install -e \".[dev]\"\n```\n\n### 6.3.4 安装后验证\n\n```bash\n# 验证命令是否可用\nwhich nanobot\n\n# 查看版本\nnanobot --version\n\n# 查看所有子命令\nnanobot --help\n```\n\n预期输出类似：\n\n```\nUsage: nanobot [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --version  Show version and exit.\n  --help     Show this message and exit.\n\nCommands:\n  onboard   Interactive setup wizard\n  ...\n```\n\n---\n\n## 6.4 配置向导 nanobot onboard\n\n### 6.4.1 运行配置向导\n\nNanobot 提供了一个交互式配置向导，帮助你快速完成初始配置：\n\n```bash\n# 在你想要作为 workspace 的目录下运行\nmkdir my-agent && cd my-agent\nnanobot onboard\n```\n\n### 6.4.2 向导流程详解\n\n配置向导会依次引导你完成以下步骤：\n\n```\nStep 1: 选择 LLM Provider\n  → OpenAI / Anthropic / DeepSeek / OpenRouter / Custom\n\nStep 2: 输入 API Key\n  → 输入你的 API Key（会被安全存储）\n\nStep 3: 选择默认模型\n  → gpt-4o / claude-sonnet-4-20250514 / deepseek-chat / ...\n\nStep 4: 配置 Workspace\n  → 当前目录 / 自定义目录\n\nStep 5: 生成配置文件\n  → 自动创建 config.json\n```\n\n### 6.4.3 向导生成的文件\n\n运行完 `nanobot onboard` 后，你会得到：\n\n```\nmy-agent/\n├── config.json          # 主配置文件\n├── AGENTS.md            # Agent 身份定义（可能自动生成）\n└── memory/              # 记忆存储目录\n    └── MEMORY.md        # 长期记忆文件\n```\n\n---\n\n## 6.5 config.json 配置详解\n\n这是 Nanobot 最核心的配置文件，理解每个字段对面试至关重要。\n\n### 6.5.1 完整配置示例\n\n```json\n{\n  \"agents\": {\n    \"defaults\": {\n      \"workspace\": \".\",\n      \"model\": \"gpt-4o\",\n      \"provider\": \"openai\",\n      \"max_tokens\": 16384,\n      \"context_window_tokens\": 128000,\n      \"temperature\": 0.7,\n      \"max_tool_iterations\": 40\n    }\n  },\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"api_base\": \"https://api.openai.com/v1\"\n    },\n    \"deepseek\": {\n      \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"api_base\": \"https://api.deepseek.com\"\n    },\n    \"ollama\": {\n      \"api_key\": \"ollama\",\n      \"api_base\": \"http://localhost:11434/v1\"\n    }\n  },\n  \"channels\": {\n    \"telegram\": {\n      \"bot_token\": \"123456:ABC-DEF...\"\n    }\n  },\n  \"tools\": {\n    \"web_search\": {\n      \"provider\": \"brave\",\n      \"api_key\": \"BSA...\"\n    }\n  }\n}\n```\n\n### 6.5.2 agents.defaults 字段详解\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `workspace` | string | `\".\"` | Agent 的工作目录，所有文件操作基于此路径 |\n| `model` | string | `\"gpt-4o\"` | 使用的 LLM 模型标识 |\n| `provider` | string | `\"openai\"` | LLM 服务提供商，对应 providers 中的 key |\n| `max_tokens` | int | `16384` | 单次 LLM 回复的最大 token 数 |\n| `context_window_tokens` | int | `128000` | 上下文窗口大小，直接影响记忆压缩触发时机 |\n| `temperature` | float | `0.7` | 生成随机性，0=确定性，1=高随机性 |\n| `max_tool_iterations` | int | `40` | 单次对话中工具调用的最大迭代次数 |\n\n**关键理解**：\n\n```\ncontext_window_tokens 的作用：\n┌──────────────────────────────────────────────────┐\n│              context_window_tokens = 128000       │\n│  ┌──────────┐ ┌──────────┐ ┌─────────────────┐   │\n│  │ System   │ │ Memory   │ │ Conversation    │   │\n│  │ Prompt   │ │ MEMORY.md│ │ History         │   │\n│  │ ~2000    │ │ ~1000    │ │ 不断增长...      │   │\n│  └──────────┘ └──────────┘ └─────────────────┘   │\n│                                                   │\n│  当总 token 数接近 128000 时 → 触发记忆压缩        │\n└──────────────────────────────────────────────────┘\n```\n\n> 💡 **面试要点**：`context_window_tokens` 不是越大越好。设置过大会导致：\n> 1. 记忆压缩不触发，旧对话堆积导致 API 费用暴增\n> 2. 模型注意力分散，回答质量下降\n> 3. 超过模型实际支持的窗口会直接报错\n\n### 6.5.3 providers 配置\n\nproviders 定义了 LLM 服务的连接信息：\n\n```json\n{\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxx\",         // API 密钥\n      \"api_base\": \"https://api.openai.com/v1\"  // API 端点\n    }\n  }\n}\n```\n\n**多 Provider 场景**：\n\n```json\n{\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxx\",\n      \"api_base\": \"https://api.openai.com/v1\"\n    },\n    \"deepseek\": {\n      \"api_key\": \"sk-yyy\",\n      \"api_base\": \"https://api.deepseek.com\"\n    },\n    \"local\": {\n      \"api_key\": \"not-needed\",\n      \"api_base\": \"http://localhost:11434/v1\"\n    }\n  }\n}\n```\n\n**使用国内代理**：\n\n```json\n{\n  \"providers\": {\n    \"openai-proxy\": {\n      \"api_key\": \"sk-xxx\",\n      \"api_base\": \"https://your-proxy.com/v1\"\n    }\n  }\n}\n```\n\n### 6.5.4 channels 配置\n\nchannels 定义了消息通道（平台接入），详见 [09 - 多平台接入](../09-multi-platform/README.md)：\n\n```json\n{\n  \"channels\": {\n    \"telegram\": {\n      \"bot_token\": \"123456:ABC...\"\n    },\n    \"discord\": {\n      \"bot_token\": \"MTIz...\"\n    },\n    \"feishu\": {\n      \"app_id\": \"cli_xxx\",\n      \"app_secret\": \"xxx\"\n    }\n  }\n}\n```\n\n### 6.5.5 tools 配置\n\ntools 部分配置工具相关的参数：\n\n```json\n{\n  \"tools\": {\n    \"web_search\": {\n      \"provider\": \"brave\",\n      \"api_key\": \"BSAxxxxxxxx\"\n    },\n    \"exec\": {\n      \"allowed\": true\n    }\n  }\n}\n```\n\n### 6.5.6 配置文件查找顺序\n\nNanobot 按以下优先级查找配置：\n\n```\n1. 命令行参数指定  （最高优先级）\n2. 当前目录 config.json\n3. ~/.config/nanobot/config.json\n4. 环境变量\n5. 内置默认值      （最低优先级）\n```\n\n---\n\n## 6.6 第一次运行：交互模式\n\n### 6.6.1 启动 Agent\n\n```bash\n# 在配置好的 workspace 目录下\ncd my-agent\n\n# 直接运行（进入交互模式）\nnanobot\n```\n\n### 6.6.2 交互界面\n\n启动后你会看到一个交互式命令行界面：\n\n```\n🤖 Nanobot v0.x.x\n📂 Workspace: /Users/you/my-agent\n🧠 Model: gpt-4o (openai)\n\nYou: 你好，请介绍一下你自己\n\nAgent: 你好！我是一个 AI 助手，运行在 Nanobot 框架上...\n\nYou: 帮我创建一个 hello.py 文件\n\nAgent: 好的，我来帮你创建文件。\n[调用工具: write_file]\n[文件已创建: hello.py]\n\nYou: /quit\n```\n\n### 6.6.3 常用交互命令\n\n| 命令 | 说明 |\n|------|------|\n| 直接输入 | 与 Agent 对话 |\n| `/quit` 或 `Ctrl+C` | 退出交互模式 |\n| 多行输入 | 部分终端支持 Shift+Enter |\n\n### 6.6.4 观察 Agent 的行为\n\n运行后，注意观察以下几点（这些都是面试可以聊的素材）：\n\n1. **System Prompt 加载**：Agent 启动时读取 AGENTS.md、MEMORY.md 等文件构建系统提示词\n2. **工具调用**：当你让 Agent 操作文件时，可以看到它调用了哪些工具\n3. **记忆保存**：退出时观察 memory/ 目录的变化\n4. **会话历史**：sessions/ 目录下会生成 JSONL 格式的会话记录\n\n```bash\n# 运行后查看生成的文件\ntree my-agent/\n# my-agent/\n# ├── config.json\n# ├── AGENTS.md\n# ├── memory/\n# │   ├── MEMORY.md\n# │   └── HISTORY.md\n# └── sessions/\n#     └── cli:default.jsonl\n```\n\n---\n\n## 6.7 自定义 AGENTS.md：定义 Agent 身份\n\n### 6.7.1 AGENTS.md 的作用\n\n`AGENTS.md` 是 Nanobot 中定义 Agent 身份和行为的核心文件。它的内容会被注入到 System Prompt 中，决定了 Agent \"是谁\"、\"能做什么\"、\"怎么做\"。\n\n### 6.7.2 基础格式\n\n```markdown\n# My Assistant\n\n你是一个专业的编程助手，擅长 Python 和 JavaScript 开发。\n\n## 行为准则\n\n- 回答问题时要准确、简洁\n- 编写代码时注重可读性和可维护性\n- 遇到不确定的问题要诚实说明\n\n## 专业领域\n\n- Python 后端开发\n- React 前端开发\n- 数据库设计与优化\n```\n\n### 6.7.3 高级 AGENTS.md 示例\n\n```markdown\n# 技术面试教练\n\n你是一位经验丰富的技术面试教练，专门帮助候选人准备 AI Agent 方向的面试。\n\n## 核心职责\n\n1. **知识讲解**：深入浅出地解释 AI Agent 相关概念\n2. **模拟面试**：模拟真实面试场景进行提问\n3. **答案优化**：帮助候选人优化回答的结构和表达\n4. **查漏补缺**：发现知识盲区并提供学习建议\n\n## 回答风格\n\n- 先给结论，再展开解释\n- 使用\"总-分-总\"的结构\n- 适当使用类比帮助理解\n- 每个回答控制在 3 分钟以内\n\n## 工具使用\n\n- 使用 `read_file` 查阅参考资料\n- 使用 `web_search` 搜索最新面试题\n- 使用 `write_file` 生成面试笔记\n```\n\n### 6.7.4 AGENTS.md 与 System Prompt 的关系\n\n```\nSystem Prompt 构建过程：\n┌──────────────────────────────────┐\n│  1. 内置基础指令（Nanobot 框架）   │\n│  2. SOUL.md（全局人格指引）        │\n│  3. AGENTS.md（Agent 身份定义）    │\n│  4. USER.md（用户信息）           │\n│  5. TOOLS.md（工具使用指引）       │\n│  6. MEMORY.md（长期记忆）         │\n│  7. 技能摘要（Skills 目录）       │\n│  = 最终 System Prompt             │\n└──────────────────────────────────┘\n```\n\n---\n\n## 6.8 引导文件体系\n\nNanobot 通过一组 Markdown 文件来引导 Agent 的行为，这是其\"Markdown 即配置\"理念的体现。\n\n### 6.8.1 SOUL.md —— 全局人格\n\n```markdown\n# SOUL.md 示例\n\n你是一个友好、专业、有耐心的 AI 助手。\n\n## 价值观\n- 诚实：不确定时承认不知道\n- 安全：不执行可能造成损害的操作\n- 隐私：尊重用户的隐私数据\n\n## 沟通风格\n- 使用简体中文\n- 语气专业但不刻板\n- 适当使用例子帮助理解\n```\n\n**SOUL.md 的特点**：\n- 存放位置：workspace 根目录\n- 注入时机：始终注入 System Prompt\n- 作用范围：影响 Agent 的整体人格和价值观\n- 优先级：高于 AGENTS.md\n\n### 6.8.2 USER.md —— 用户画像\n\n```markdown\n# USER.md 示例\n\n## 用户信息\n- 名称：小明\n- 角色：初级后端开发工程师\n- 技术栈：Python, FastAPI, PostgreSQL\n- 目标：准备 AI Agent 方向的面试\n\n## 偏好\n- 喜欢看代码示例\n- 偏好简体中文\n- 需要详细解释概念\n```\n\n**USER.md 的作用**：\n- 帮助 Agent 了解用户背景，提供个性化回答\n- 用户可以随时修改，Agent 会感知变化\n- 减少每次对话中重复描述自己的需求\n\n### 6.8.3 TOOLS.md —— 工具使用指引\n\n```markdown\n# TOOLS.md 示例\n\n## 文件操作规范\n- 创建文件前先用 list_dir 检查目录结构\n- 修改文件时优先使用 edit_file 而非 write_file\n- 重要文件修改前先备份\n\n## Shell 命令规范\n- 避免使用 rm -rf\n- 长时间运行的命令使用后台模式\n- 安装包时使用 --yes 避免交互确认\n\n## 搜索规范\n- 优先使用 web_search 获取最新信息\n- 搜索结果需要验证可靠性\n```\n\n### 6.8.4 文件优先级与覆盖关系\n\n```\n优先级从高到低：\nSOUL.md  >  AGENTS.md  >  USER.md  >  TOOLS.md\n   │            │            │           │\n   └── 人格     └── 身份     └── 用户    └── 工具\n```\n\n---\n\n## 6.9 常见问题排错\n\n### 6.9.1 安装问题\n\n**问题 1：`nanobot: command not found`**\n\n```bash\n# 原因：安装路径不在 PATH 中\n# 解决方案 1：检查 pip 安装路径\npip show nanobot-ai | grep Location\n\n# 解决方案 2：使用 python -m\npython -m nanobot\n\n# 解决方案 3：使用 uv 重新安装\nuv tool install nanobot-ai\n```\n\n**问题 2：Python 版本不兼容**\n\n```bash\n# 报错：requires Python >= 3.10\n# 解决：升级 Python\npyenv install 3.12.0\npyenv global 3.12.0\n\n# 或使用 conda\nconda create -n nanobot python=3.12 -y\n```\n\n**问题 3：依赖冲突**\n\n```bash\n# 使用虚拟环境隔离\npython -m venv nanobot-env\nsource nanobot-env/bin/activate\npip install nanobot-ai\n```\n\n### 6.9.2 配置问题\n\n**问题 4：API Key 无效**\n\n```bash\n# 报错：Authentication failed / Invalid API key\n# 排查步骤：\n# 1. 确认 key 是否正确复制（无多余空格）\n# 2. 确认 provider 与 key 匹配\n# 3. 测试 key 是否有效\ncurl https://api.openai.com/v1/models \\\n  -H \"Authorization: Bearer sk-xxx\"\n```\n\n**问题 5：模型不存在**\n\n```bash\n# 报错：Model not found\n# 原因：model 字段与 provider 不匹配\n# 例如：provider 设置为 deepseek，但 model 设置为 gpt-4o\n\n# 正确配置：\n# provider: \"deepseek\" → model: \"deepseek-chat\"\n# provider: \"openai\"   → model: \"gpt-4o\"\n```\n\n**问题 6：连接超时**\n\n```bash\n# 国内用户常见问题\n# 解决方案 1：使用代理\nexport https_proxy=http://127.0.0.1:7890\n\n# 解决方案 2：使用国内 Provider\n# 配置 DeepSeek 或其他国内模型服务\n\n# 解决方案 3：使用 api_base 指向代理地址\n{\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxx\",\n      \"api_base\": \"https://your-proxy.example.com/v1\"\n    }\n  }\n}\n```\n\n### 6.9.3 运行时问题\n\n**问题 7：记忆文件找不到**\n\n```bash\n# 确认 workspace 配置是否正确\ncat config.json | python -m json.tool | grep workspace\n\n# 手动创建记忆目录\nmkdir -p memory\n```\n\n**问题 8：工具调用失败**\n\n```bash\n# 常见原因：\n# 1. restrict_to_workspace 限制了文件访问范围\n# 2. exec 工具被禁用\n# 3. web_search 没有配置 API Key\n\n# 检查工具配置\ncat config.json | python -m json.tool | grep -A 5 tools\n```\n\n---\n\n## 6.10 实战练习\n\n### 练习 1：创建一个翻译助手\n\n```bash\n# 1. 创建项目目录\nmkdir translator-agent && cd translator-agent\n\n# 2. 初始化配置\nnanobot onboard\n\n# 3. 创建 AGENTS.md\ncat > AGENTS.md << 'EOF'\n# 翻译助手\n\n你是一个专业的中英互译助手。\n\n## 规则\n- 中文输入 → 翻译为英文\n- 英文输入 → 翻译为中文\n- 保持原文的语气和风格\n- 专业术语提供注释\nEOF\n\n# 4. 运行\nnanobot\n```\n\n### 练习 2：创建一个代码审查助手\n\n```bash\nmkdir code-reviewer && cd code-reviewer\nnanobot onboard\n```\n\n编写 AGENTS.md：\n\n```markdown\n# 代码审查助手\n\n你是一位资深的代码审查专家。\n\n## 职责\n1. 审查用户提供的代码\n2. 指出潜在的 Bug 和安全隐患\n3. 提供优化建议\n4. 检查代码风格一致性\n\n## 审查流程\n1. 先用 `read_file` 读取代码文件\n2. 分析代码结构和逻辑\n3. 逐一列出发现的问题\n4. 给出改进后的代码示例\n\n## 输出格式\n- 🔴 严重问题（必须修复）\n- 🟡 警告（建议修复）\n- 🟢 建议（可选优化）\n```\n\n### 练习 3：观察记忆系统\n\n```bash\n# 1. 启动 Agent，进行几轮对话\nnanobot\n\n# 2. 对话内容示例：\n# You: 我叫张三，是一名后端开发工程师\n# You: 我最近在学习 Kubernetes\n# You: 请记住我喜欢用 Python\n\n# 3. 退出后检查记忆文件\ncat memory/MEMORY.md\ncat memory/HISTORY.md\n\n# 4. 重新启动，验证 Agent 是否记住了你的信息\nnanobot\n# You: 我叫什么名字？\n# Agent 应该能回答：你叫张三\n```\n\n---\n\n## 6.11 面试话术\n\n### 话术 1：描述你如何搭建 Nanobot 环境\n\n> **面试官**：你有使用过 AI Agent 框架吗？能描述一下搭建过程吗？\n>\n> **参考回答**：\n>\n> \"有的，我深入学习并使用过 HKUDS/nanobot 框架。搭建过程主要分几步：\n>\n> 首先是环境准备，Nanobot 要求 Python 3.10 以上，我用的是 uv 来安装，因为它比 pip 快很多。安装命令是 `uv tool install nanobot-ai`，这样会创建独立的虚拟环境，不污染全局。\n>\n> 然后运行 `nanobot onboard` 进行交互式配置，主要是选择 LLM Provider、填入 API Key、选择默认模型。它会生成一个 config.json 文件。\n>\n> 配置文件里有几个关键参数我特别关注：`context_window_tokens` 控制上下文窗口大小，直接影响记忆压缩的触发时机；`max_tool_iterations` 限制了单次对话中工具调用次数，防止 Agent 陷入死循环。\n>\n> 最后通过 AGENTS.md 定义 Agent 的身份和行为规范，就可以运行 `nanobot` 启动交互模式了。整个过程大概 10 分钟就能跑起来一个可用的 Agent。\"\n\n### 话术 2：配置文件的设计理念\n\n> **面试官**：你觉得 Nanobot 的配置设计有什么特点？\n>\n> **参考回答**：\n>\n> \"Nanobot 的配置设计体现了 **Markdown 即配置** 的理念，这是它区别于其他框架的一大特色。\n>\n> 具体来说，它用 JSON 文件管理技术配置（API Key、模型参数等），用 Markdown 文件管理行为配置（Agent 身份、用户画像、使用规范等）。这种分离很优雅：JSON 给机器读，Markdown 给人和 AI 读。\n>\n> 特别值得一提的是它的引导文件体系——SOUL.md 定义人格、AGENTS.md 定义身份、USER.md 定义用户画像、TOOLS.md 定义工具规范——这四个文件共同构建了一个层次清晰的 System Prompt。这种设计让非技术人员也能通过修改 Markdown 来定制 Agent 行为，大大降低了使用门槛。\"\n\n### 话术 3：遇到的问题和解决方案\n\n> **面试官**：搭建过程中遇到过什么问题吗？\n>\n> **参考回答**：\n>\n> \"遇到过几个典型问题。一个是 API 连接超时，因为在国内直连 OpenAI API 不稳定，我的解决方案是在 config.json 的 providers 里把 api_base 改为代理地址，也可以直接换用 DeepSeek 这样的国内 Provider。\n>\n> 另一个是 context_window_tokens 的设置问题。一开始我设得比较大，结果发现记忆压缩一直不触发，对话越来越长导致 API 费用很高。后来理解了这个参数的作用——当 `estimate_prompt_tokens_chain` 超过这个值时才会触发 MemoryConsolidator——就把它调到了一个合理的范围。\n>\n> 还有一个工具调用权限的问题，默认的 `restrict_to_workspace` 配置会限制 Agent 只能操作 workspace 内的文件，一开始没理解，尝试让 Agent 操作外部文件时总是失败。理解了这个安全机制后，我反而觉得这是一个很好的设计。\"\n\n---\n\n## 6.12 本章小结\n\n### 核心知识点回顾\n\n| 知识点 | 要点 |\n|--------|------|\n| 安装方式 | pip install / uv tool install / 源码安装 |\n| 配置向导 | `nanobot onboard` 交互式生成 config.json |\n| 核心配置 | agents.defaults / providers / channels / tools |\n| 关键参数 | context_window_tokens, max_tool_iterations |\n| 引导文件 | SOUL.md → AGENTS.md → USER.md → TOOLS.md |\n| 运行模式 | `nanobot` 直接进入交互模式 |\n\n### 面试核心要点\n\n1. **安装方式**：推荐 uv，解释 uv 的优势\n2. **配置设计**：JSON + Markdown 双配置体系\n3. **关键参数**：context_window_tokens 与记忆压缩的关系\n4. **引导文件**：四层引导体系的设计理念\n5. **实际经验**：能描述具体问题和解决方案\n\n---\n\n> **下一章**：[07 - 记忆系统实战](../07-memory-system/README.md) —— 深入理解 Nanobot 的双层记忆架构"}, "bc2575b10d4d6b0264e05cfceb0591a92c6fbd68": {"t": 1785765185.23757, "n": 15197, "h": "30d96d61f238da06", "c": "# 06 - 安装与上手\n\n> **阅读时间**：约 2 小时  \n> **前置知识**：[05 - MCP 协议详解](../05-mcp-protocol/README.md)  \n> **学习目标**：完成 Nanobot 的安装配置，运行你的第一个 AI Agent，理解全部配置项\n\n---\n\n## 目录\n\n- [6.1 为什么需要动手实践](#61-为什么需要动手实践)\n- [6.2 环境准备](#62-环境准备)\n- [6.3 安装 Nanobot](#63-安装-nanobot)\n- [6.4 配置向导 nanobot onboard](#64-配置向导-nanobot-onboard)\n- [6.5 config.json 配置详解](#65-configjson-配置详解)\n- [6.6 第一次运行：交互模式](#66-第一次运行交互模式)\n- [6.7 自定义 AGENTS.md：定义 Agent 身份](#67-自定义-agentsmd定义-agent-身份)\n- [6.8 引导文件体系](#68-引导文件体系)\n- [6.9 常见问题排错](#69-常见问题排错)\n- [6.10 实战练习](#610-实战练习)\n- [6.11 面试话术](#611-面试话术)\n- [6.12 本章小结](#612-本章小结)\n\n---\n\n## 6.1 为什么需要动手实践\n\n学习 AI Agent 框架，**纸上得来终觉浅**。在面试中，面试官最看重的不是你能背多少概念，而是：\n\n1. **你有没有真正用过？** —— 安装、配置、调试的全流程经验\n2. **你能不能描述细节？** —— 配置文件的字段含义、启动参数的作用\n3. **你遇到过什么问题？** —— 排错经历本身就是加分项\n\n> 💡 **面试真相**：一个能说出 \"我在配置 Nanobot 的 context_window_tokens 时发现设置过大会导致记忆压缩不触发\" 的候选人，比只能背概念的候选人强 10 倍。\n\n---\n\n## 6.2 环境准备\n\n### 6.2.1 系统要求\n\n| 项目 | 最低要求 | 推荐配置 |\n|------|---------|---------|\n| 操作系统 | macOS / Linux / Windows (WSL) | macOS / Ubuntu 22.04+ |\n| Python | 3.10+ | 3.11 或 3.12 |\n| 内存 | 4 GB | 8 GB+ |\n| 磁盘空间 | 500 MB | 2 GB+ |\n| 网络 | 可访问 LLM API | 稳定的国际网络 |\n\n### 6.2.2 Python 环境配置\n\n**方式一：使用系统 Python（简单）**\n\n```bash\n# 检查 Python 版本\npython3 --version\n# 输出应为 Python 3.10.x 或更高\n\n# 如果版本过低，使用 pyenv 安装\ncurl https://pyenv.run | bash\npyenv install 3.12.0\npyenv global 3.12.0\n```\n\n**方式二：使用 Conda（推荐隔离环境）**\n\n```bash\n# 创建独立环境\nconda create -n nanobot python=3.12 -y\nconda activate nanobot\n\n# 验证\npython --version\n# Python 3.12.x\n```\n\n**方式三：使用 uv（最快，推荐）**\n\n```bash\n# 安装 uv（Rust 编写的超快 Python 包管理器）\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 验证\nuv --version\n```\n\n> 💡 **面试加分**：uv 是 Astral 公司用 Rust 编写的 Python 包管理工具，安装速度比 pip 快 10-100 倍。Nanobot 官方推荐使用 uv。\n\n### 6.2.3 LLM API Key 准备\n\nNanobot 需要连接大语言模型 API，支持多种 Provider：\n\n| Provider | 获取方式 | 推荐度 |\n|----------|---------|--------|\n| OpenAI | [platform.openai.com](https://platform.openai.com) | 首选 |\n| Anthropic (Claude) | [console.anthropic.com](https://console.anthropic.com) | 推荐 |\n| DeepSeek | [platform.deepseek.com](https://platform.deepseek.com) | 国内友好 |\n| OpenRouter | [openrouter.ai](https://openrouter.ai) | 聚合多模型 |\n| 本地模型 (Ollama) | [ollama.com](https://ollama.com) | 免费、离线 |\n\n```bash\n# 准备好你的 API Key\nexport OPENAI_API_KEY=\"sk-xxxxxxxxxxxxxxxxxxxxxxxx\"\n\n# 或者使用 DeepSeek（国内推荐）\nexport DEEPSEEK_API_KEY=\"sk-xxxxxxxxxxxxxxxxxxxxxxxx\"\n```\n\n---\n\n## 6.3 安装 Nanobot\n\n### 6.3.1 方式一：pip 安装（通用）\n\n```bash\n# 安装最新版\npip install nanobot-ai\n\n# 验证安装\nnanobot --version\n\n# 查看帮助\nnanobot --help\n```\n\n### 6.3.2 方式二：uv 工具安装（推荐）\n\n```bash\n# 使用 uv 安装为全局工具\nuv tool install nanobot-ai\n\n# 验证\nnanobot --version\n```\n\n> **uv tool install vs pip install 的区别**：\n> - `uv tool install` 会创建独立的虚拟环境，不污染全局 Python 环境\n> - `pip install` 直接安装到当前 Python 环境\n> - 推荐使用 uv，尤其是需要在多个项目中使用不同版本时\n\n### 6.3.3 方式三：从源码安装（开发者）\n\n```bash\n# 克隆源码\ngit clone https://github.com/HKUDS/nanobot.git\ncd nanobot\n\n# 使用 uv 安装开发依赖\nuv sync --dev\n\n# 或使用 pip\npip install -e \".[dev]\"\n```\n\n### 6.3.4 安装后验证\n\n```bash\n# 验证命令是否可用\nwhich nanobot\n\n# 查看版本\nnanobot --version\n\n# 查看所有子命令\nnanobot --help\n```\n\n预期输出类似：\n\n```\nUsage: nanobot [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --version  Show version and exit.\n  --help     Show this message and exit.\n\nCommands:\n  onboard   Interactive setup wizard\n  ...\n```\n\n---\n\n## 6.4 配置向导 nanobot onboard\n\n### 6.4.1 运行配置向导\n\nNanobot 提供了一个交互式配置向导，帮助你快速完成初始配置：\n\n```bash\n# 在你想要作为 workspace 的目录下运行\nmkdir my-agent && cd my-agent\nnanobot onboard\n```\n\n### 6.4.2 向导流程详解\n\n配置向导会依次引导你完成以下步骤：\n\n```\nStep 1: 选择 LLM Provider\n  → OpenAI / Anthropic / DeepSeek / OpenRouter / Custom\n\nStep 2: 输入 API Key\n  → 输入你的 API Key（会被安全存储）\n\nStep 3: 选择默认模型\n  → gpt-4o / claude-sonnet-4-20250514 / deepseek-chat / ...\n\nStep 4: 配置 Workspace\n  → 当前目录 / 自定义目录\n\nStep 5: 生成配置文件\n  → 自动创建 config.json\n```\n\n### 6.4.3 向导生成的文件\n\n运行完 `nanobot onboard` 后，你会得到：\n\n```\nmy-agent/\n├── config.json          # 主配置文件\n├── AGENTS.md            # Agent 身份定义（可能自动生成）\n└── memory/              # 记忆存储目录\n    └── MEMORY.md        # 长期记忆文件\n```\n\n---\n\n## 6.5 config.json 配置详解\n\n这是 Nanobot 最核心的配置文件，理解每个字段对面试至关重要。\n\n### 6.5.1 完整配置示例\n\n```json\n{\n  \"agents\": {\n    \"defaults\": {\n      \"workspace\": \".\",\n      \"model\": \"gpt-4o\",\n      \"provider\": \"openai\",\n      \"max_tokens\": 16384,\n      \"context_window_tokens\": 128000,\n      \"temperature\": 0.7,\n      \"max_tool_iterations\": 40\n    }\n  },\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"api_base\": \"https://api.openai.com/v1\"\n    },\n    \"deepseek\": {\n      \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"api_base\": \"https://api.deepseek.com\"\n    },\n    \"ollama\": {\n      \"api_key\": \"ollama\",\n      \"api_base\": \"http://localhost:11434/v1\"\n    }\n  },\n  \"channels\": {\n    \"telegram\": {\n      \"bot_token\": \"123456:ABC-DEF...\"\n    }\n  },\n  \"tools\": {\n    \"web_search\": {\n      \"provider\": \"brave\",\n      \"api_key\": \"BSA...\"\n    }\n  }\n}\n```\n\n### 6.5.2 agents.defaults 字段详解\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `workspace` | string | `\".\"` | Agent 的工作目录，所有文件操作基于此路径 |\n| `model` | string | `\"gpt-4o\"` | 使用的 LLM 模型标识 |\n| `provider` | string | `\"openai\"` | LLM 服务提供商，对应 providers 中的 key |\n| `max_tokens` | int | `16384` | 单次 LLM 回复的最大 token 数 |\n| `context_window_tokens` | int | `128000` | 上下文窗口大小，直接影响记忆压缩触发时机 |\n| `temperature` | float | `0.7` | 生成随机性，0=确定性，1=高随机性 |\n| `max_tool_iterations` | int | `40` | 单次对话中工具调用的最大迭代次数 |\n\n**关键理解**：\n\n```\ncontext_window_tokens 的作用：\n┌──────────────────────────────────────────────────┐\n│              context_window_tokens = 128000       │\n│  ┌──────────┐ ┌──────────┐ ┌─────────────────┐   │\n│  │ System   │ │ Memory   │ │ Conversation    │   │\n│  │ Prompt   │ │ MEMORY.md│ │ History         │   │\n│  │ ~2000    │ │ ~1000    │ │ 不断增长...      │   │\n│  └──────────┘ └──────────┘ └─────────────────┘   │\n│                                                   │\n│  当总 token 数接近 128000 时 → 触发记忆压缩        │\n└──────────────────────────────────────────────────┘\n```\n\n> 💡 **面试要点**：`context_window_tokens` 不是越大越好。设置过大会导致：\n> 1. 记忆压缩不触发，旧对话堆积导致 API 费用暴增\n> 2. 模型注意力分散，回答质量下降\n> 3. 超过模型实际支持的窗口会直接报错\n\n### 6.5.3 providers 配置\n\nproviders 定义了 LLM 服务的连接信息：\n\n```json\n{\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxx\",         // API 密钥\n      \"api_base\": \"https://api.openai.com/v1\"  // API 端点\n    }\n  }\n}\n```\n\n**多 Provider 场景**：\n\n```json\n{\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxx\",\n      \"api_base\": \"https://api.openai.com/v1\"\n    },\n    \"deepseek\": {\n      \"api_key\": \"sk-yyy\",\n      \"api_base\": \"https://api.deepseek.com\"\n    },\n    \"local\": {\n      \"api_key\": \"not-needed\",\n      \"api_base\": \"http://localhost:11434/v1\"\n    }\n  }\n}\n```\n\n**使用国内代理**：\n\n```json\n{\n  \"providers\": {\n    \"openai-proxy\": {\n      \"api_key\": \"sk-xxx\",\n      \"api_base\": \"https://your-proxy.com/v1\"\n    }\n  }\n}\n```\n\n### 6.5.4 channels 配置\n\nchannels 定义了消息通道（平台接入），详见 [09 - 多平台接入](../09-multi-platform/README.md)：\n\n```json\n{\n  \"channels\": {\n    \"telegram\": {\n      \"bot_token\": \"123456:ABC...\"\n    },\n    \"discord\": {\n      \"bot_token\": \"MTIz...\"\n    },\n    \"feishu\": {\n      \"app_id\": \"cli_xxx\",\n      \"app_secret\": \"xxx\"\n    }\n  }\n}\n```\n\n### 6.5.5 tools 配置\n\ntools 部分配置工具相关的参数：\n\n```json\n{\n  \"tools\": {\n    \"web_search\": {\n      \"provider\": \"brave\",\n      \"api_key\": \"BSAxxxxxxxx\"\n    },\n    \"exec\": {\n      \"allowed\": true\n    }\n  }\n}\n```\n\n### 6.5.6 配置文件查找顺序\n\nNanobot 按以下优先级查找配置：\n\n```\n1. 命令行参数指定  （最高优先级）\n2. 当前目录 config.json\n3. ~/.config/nanobot/config.json\n4. 环境变量\n5. 内置默认值      （最低优先级）\n```\n\n---\n\n## 6.6 第一次运行：交互模式\n\n### 6.6.1 启动 Agent\n\n```bash\n# 在配置好的 workspace 目录下\ncd my-agent\n\n# 直接运行（进入交互模式）\nnanobot\n```\n\n### 6.6.2 交互界面\n\n启动后你会看到一个交互式命令行界面：\n\n```\n🤖 Nanobot v0.x.x\n📂 Workspace: /Users/you/my-agent\n🧠 Model: gpt-4o (openai)\n\nYou: 你好，请介绍一下你自己\n\nAgent: 你好！我是一个 AI 助手，运行在 Nanobot 框架上...\n\nYou: 帮我创建一个 hello.py 文件\n\nAgent: 好的，我来帮你创建文件。\n[调用工具: write_file]\n[文件已创建: hello.py]\n\nYou: /quit\n```\n\n### 6.6.3 常用交互命令\n\n| 命令 | 说明 |\n|------|------|\n| 直接输入 | 与 Agent 对话 |\n| `/quit` 或 `Ctrl+C` | 退出交互模式 |\n| 多行输入 | 部分终端支持 Shift+Enter |\n\n### 6.6.4 观察 Agent 的行为\n\n运行后，注意观察以下几点（这些都是面试可以聊的素材）：\n\n1. **System Prompt 加载**：Agent 启动时读取 AGENTS.md、MEMORY.md 等文件构建系统提示词\n2. **工具调用**：当你让 Agent 操作文件时，可以看到它调用了哪些工具\n3. **记忆保存**：退出时观察 memory/ 目录的变化\n4. **会话历史**：sessions/ 目录下会生成 JSONL 格式的会话记录\n\n```bash\n# 运行后查看生成的文件\ntree my-agent/\n# my-agent/\n# ├── config.json\n# ├── AGENTS.md\n# ├── memory/\n# │   ├── MEMORY.md\n# │   └── HISTORY.md\n# └── sessions/\n#     └── cli:default.jsonl\n```\n\n---\n\n## 6.7 自定义 AGENTS.md：定义 Agent 身份\n\n### 6.7.1 AGENTS.md 的作用\n\n`AGENTS.md` 是 Nanobot 中定义 Agent 身份和行为的核心文件。它的内容会被注入到 System Prompt 中，决定了 Agent \"是谁\"、\"能做什么\"、\"怎么做\"。\n\n### 6.7.2 基础格式\n\n```markdown\n# My Assistant\n\n你是一个专业的编程助手，擅长 Python 和 JavaScript 开发。\n\n## 行为准则\n\n- 回答问题时要准确、简洁\n- 编写代码时注重可读性和可维护性\n- 遇到不确定的问题要诚实说明\n\n## 专业领域\n\n- Python 后端开发\n- React 前端开发\n- 数据库设计与优化\n```\n\n### 6.7.3 高级 AGENTS.md 示例\n\n```markdown\n# 技术面试教练\n\n你是一位经验丰富的技术面试教练，专门帮助候选人准备 AI Agent 方向的面试。\n\n## 核心职责\n\n1. **知识讲解**：深入浅出地解释 AI Agent 相关概念\n2. **模拟面试**：模拟真实面试场景进行提问\n3. **答案优化**：帮助候选人优化回答的结构和表达\n4. **查漏补缺**：发现知识盲区并提供学习建议\n\n## 回答风格\n\n- 先给结论，再展开解释\n- 使用\"总-分-总\"的结构\n- 适当使用类比帮助理解\n- 每个回答控制在 3 分钟以内\n\n## 工具使用\n\n- 使用 `read_file` 查阅参考资料\n- 使用 `web_search` 搜索最新面试题\n- 使用 `write_file` 生成面试笔记\n```\n\n### 6.7.4 AGENTS.md 与 System Prompt 的关系\n\n```\nSystem Prompt 构建过程：\n┌──────────────────────────────────┐\n│  1. 内置基础指令（Nanobot 框架）   │\n│  2. SOUL.md（全局人格指引）        │\n│  3. AGENTS.md（Agent 身份定义）    │\n│  4. USER.md（用户信息）           │\n│  5. TOOLS.md（工具使用指引）       │\n│  6. MEMORY.md（长期记忆）         │\n│  7. 技能摘要（Skills 目录）       │\n│  = 最终 System Prompt             │\n└──────────────────────────────────┘\n```\n\n---\n\n## 6.8 引导文件体系\n\nNanobot 通过一组 Markdown 文件来引导 Agent 的行为，这是其\"Markdown 即配置\"理念的体现。\n\n### 6.8.1 SOUL.md —— 全局人格\n\n```markdown\n# SOUL.md 示例\n\n你是一个友好、专业、有耐心的 AI 助手。\n\n## 价值观\n- 诚实：不确定时承认不知道\n- 安全：不执行可能造成损害的操作\n- 隐私：尊重用户的隐私数据\n\n## 沟通风格\n- 使用简体中文\n- 语气专业但不刻板\n- 适当使用例子帮助理解\n```\n\n**SOUL.md 的特点**：\n- 存放位置：workspace 根目录\n- 注入时机：始终注入 System Prompt\n- 作用范围：影响 Agent 的整体人格和价值观\n- 优先级：高于 AGENTS.md\n\n### 6.8.2 USER.md —— 用户画像\n\n```markdown\n# USER.md 示例\n\n## 用户信息\n- 名称：小明\n- 角色：初级后端开发工程师\n- 技术栈：Python, FastAPI, PostgreSQL\n- 目标：准备 AI Agent 方向的面试\n\n## 偏好\n- 喜欢看代码示例\n- 偏好简体中文\n- 需要详细解释概念\n```\n\n**USER.md 的作用**：\n- 帮助 Agent 了解用户背景，提供个性化回答\n- 用户可以随时修改，Agent 会感知变化\n- 减少每次对话中重复描述自己的需求\n\n### 6.8.3 TOOLS.md —— 工具使用指引\n\n```markdown\n# TOOLS.md 示例\n\n## 文件操作规范\n- 创建文件前先用 list_dir 检查目录结构\n- 修改文件时优先使用 edit_file 而非 write_file\n- 重要文件修改前先备份\n\n## Shell 命令规范\n- 避免使用 rm -rf\n- 长时间运行的命令使用后台模式\n- 安装包时使用 --yes 避免交互确认\n\n## 搜索规范\n- 优先使用 web_search 获取最新信息\n- 搜索结果需要验证可靠性\n```\n\n### 6.8.4 文件优先级与覆盖关系\n\n```\n优先级从高到低：\nSOUL.md  >  AGENTS.md  >  USER.md  >  TOOLS.md\n   │            │            │           │\n   └── 人格     └── 身份     └── 用户    └── 工具\n```\n\n---\n\n## 6.9 常见问题排错\n\n### 6.9.1 安装问题\n\n**问题 1：`nanobot: command not found`**\n\n```bash\n# 原因：安装路径不在 PATH 中\n# 解决方案 1：检查 pip 安装路径\npip show nanobot-ai | grep Location\n\n# 解决方案 2：使用 python -m\npython -m nanobot\n\n# 解决方案 3：使用 uv 重新安装\nuv tool install nanobot-ai\n```\n\n**问题 2：Python 版本不兼容**\n\n```bash\n# 报错：requires Python >= 3.10\n# 解决：升级 Python\npyenv install 3.12.0\npyenv global 3.12.0\n\n# 或使用 conda\nconda create -n nanobot python=3.12 -y\n```\n\n**问题 3：依赖冲突**\n\n```bash\n# 使用虚拟环境隔离\npython -m venv nanobot-env\nsource nanobot-env/bin/activate\npip install nanobot-ai\n```\n\n### 6.9.2 配置问题\n\n**问题 4：API Key 无效**\n\n```bash\n# 报错：Authentication failed / Invalid API key\n# 排查步骤：\n# 1. 确认 key 是否正确复制（无多余空格）\n# 2. 确认 provider 与 key 匹配\n# 3. 测试 key 是否有效\ncurl https://api.openai.com/v1/models \\\n  -H \"Authorization: Bearer sk-xxx\"\n```\n\n**问题 5：模型不存在**\n\n```bash\n# 报错：Model not found\n# 原因：model 字段与 provider 不匹配\n# 例如：provider 设置为 deepseek，但 model 设置为 gpt-4o\n\n# 正确配置：\n# provider: \"deepseek\" → model: \"deepseek-chat\"\n# provider: \"openai\"   → model: \"gpt-4o\"\n```\n\n**问题 6：连接超时**\n\n```bash\n# 国内用户常见问题\n# 解决方案 1：使用代理\nexport https_proxy=http://127.0.0.1:7890\n\n# 解决方案 2：使用国内 Provider\n# 配置 DeepSeek 或其他国内模型服务\n\n# 解决方案 3：使用 api_base 指向代理地址\n{\n  \"providers\": {\n    \"openai\": {\n      \"api_key\": \"sk-xxx\",\n      \"api_base\": \"https://your-proxy.example.com/v1\"\n    }\n  }\n}\n```\n\n### 6.9.3 运行时问题\n\n**问题 7：记忆文件找不到**\n\n```bash\n# 确认 workspace 配置是否正确\ncat config.json | python -m json.tool | grep workspace\n\n# 手动创建记忆目录\nmkdir -p memory\n```\n\n**问题 8：工具调用失败**\n\n```bash\n# 常见原因：\n# 1. restrict_to_workspace 限制了文件访问范围\n# 2. exec 工具被禁用\n# 3. web_search 没有配置 API Key\n\n# 检查工具配置\ncat config.json | python -m json.tool | grep -A 5 tools\n```\n\n---\n\n## 6.10 实战练习\n\n### 练习 1：创建一个翻译助手\n\n```bash\n# 1. 创建项目目录\nmkdir translator-agent && cd translator-agent\n\n# 2. 初始化配置\nnanobot onboard\n\n# 3. 创建 AGENTS.md\ncat > AGENTS.md << 'EOF'\n# 翻译助手\n\n你是一个专业的中英互译助手。\n\n## 规则\n- 中文输入 → 翻译为英文\n- 英文输入 → 翻译为中文\n- 保持原文的语气和风格\n- 专业术语提供注释\nEOF\n\n# 4. 运行\nnanobot\n```\n\n### 练习 2：创建一个代码审查助手\n\n```bash\nmkdir code-reviewer && cd code-reviewer\nnanobot onboard\n```\n\n编写 AGENTS.md：\n\n```markdown\n# 代码审查助手\n\n你是一位资深的代码审查专家。\n\n## 职责\n1. 审查用户提供的代码\n2. 指出潜在的 Bug 和安全隐患\n3. 提供优化建议\n4. 检查代码风格一致性\n\n## 审查流程\n1. 先用 `read_file` 读取代码文件\n2. 分析代码结构和逻辑\n3. 逐一列出发现的问题\n4. 给出改进后的代码示例\n\n## 输出格式\n- 🔴 严重问题（必须修复）\n- 🟡 警告（建议修复）\n- 🟢 建议（可选优化）\n```\n\n### 练习 3：观察记忆系统\n\n```bash\n# 1. 启动 Agent，进行几轮对话\nnanobot\n\n# 2. 对话内容示例：\n# You: 我叫张三，是一名后端开发工程师\n# You: 我最近在学习 Kubernetes\n# You: 请记住我喜欢用 Python\n\n# 3. 退出后检查记忆文件\ncat memory/MEMORY.md\ncat memory/HISTORY.md\n\n# 4. 重新启动，验证 Agent 是否记住了你的信息\nnanobot\n# You: 我叫什么名字？\n# Agent 应该能回答：你叫张三\n```\n\n---\n\n## 6.11 面试话术\n\n### 话术 1：描述你如何搭建 Nanobot 环境\n\n> **面试官**：你有使用过 AI Agent 框架吗？能描述一下搭建过程吗？\n>\n> **参考回答**：\n>\n> \"有的，我深入学习并使用过 HKUDS/nanobot 框架。搭建过程主要分几步：\n>\n> 首先是环境准备，Nanobot 要求 Python 3.10 以上，我用的是 uv 来安装，因为它比 pip 快很多。安装命令是 `uv tool install nanobot-ai`，这样会创建独立的虚拟环境，不污染全局。\n>\n> 然后运行 `nanobot onboard` 进行交互式配置，主要是选择 LLM Provider、填入 API Key、选择默认模型。它会生成一个 config.json 文件。\n>\n> 配置文件里有几个关键参数我特别关注：`context_window_tokens` 控制上下文窗口大小，直接影响记忆压缩的触发时机；`max_tool_iterations` 限制了单次对话中工具调用次数，防止 Agent 陷入死循环。\n>\n> 最后通过 AGENTS.md 定义 Agent 的身份和行为规范，就可以运行 `nanobot` 启动交互模式了。整个过程大概 10 分钟就能跑起来一个可用的 Agent。\"\n\n### 话术 2：配置文件的设计理念\n\n> **面试官**：你觉得 Nanobot 的配置设计有什么特点？\n>\n> **参考回答**：\n>\n> \"Nanobot 的配置设计体现了 **Markdown 即配置** 的理念，这是它区别于其他框架的一大特色。\n>\n> 具体来说，它用 JSON 文件管理技术配置（API Key、模型参数等），用 Markdown 文件管理行为配置（Agent 身份、用户画像、使用规范等）。这种分离很优雅：JSON 给机器读，Markdown 给人和 AI 读。\n>\n> 特别值得一提的是它的引导文件体系——SOUL.md 定义人格、AGENTS.md 定义身份、USER.md 定义用户画像、TOOLS.md 定义工具规范——这四个文件共同构建了一个层次清晰的 System Prompt。这种设计让非技术人员也能通过修改 Markdown 来定制 Agent 行为，大大降低了使用门槛。\"\n\n### 话术 3：遇到的问题和解决方案\n\n> **面试官**：搭建过程中遇到过什么问题吗？\n>\n> **参考回答**：\n>\n> \"遇到过几个典型问题。一个是 API 连接超时，因为在国内直连 OpenAI API 不稳定，我的解决方案是在 config.json 的 providers 里把 api_base 改为代理地址，也可以直接换用 DeepSeek 这样的国内 Provider。\n>\n> 另一个是 context_window_tokens 的设置问题。一开始我设得比较大，结果发现记忆压缩一直不触发，对话越来越长导致 API 费用很高。后来理解了这个参数的作用——当 `estimate_prompt_tokens_chain` 超过这个值时才会触发 MemoryConsolidator——就把它调到了一个合理的范围。\n>\n> 还有一个工具调用权限的问题，默认的 `restrict_to_workspace` 配置会限制 Agent 只能操作 workspace 内的文件，一开始没理解，尝试让 Agent 操作外部文件时总是失败。理解了这个安全机制后，我反而觉得这是一个很好的设计。\"\n\n---\n\n## 6.12 本章小结\n\n### 核心知识点回顾\n\n| 知识点 | 要点 |\n|--------|------|\n| 安装方式 | pip install / uv tool install / 源码安装 |\n| 配置向导 | `nanobot onboard` 交互式生成 config.json |\n| 核心配置 | agents.defaults / providers / channels / tools |\n| 关键参数 | context_window_tokens, max_tool_iterations |\n| 引导文件 | SOUL.md → AGENTS.md → USER.md → TOOLS.md |\n| 运行模式 | `nanobot` 直接进入交互模式 |\n\n### 面试核心要点\n\n1. **安装方式**：推荐 uv，解释 uv 的优势\n2. **配置设计**：JSON + Markdown 双配置体系\n3. **关键参数**：context_window_tokens 与记忆压缩的关系\n4. **引导文件**：四层引导体系的设计理念\n5. **实际经验**：能描述具体问题和解决方案\n\n---\n\n> **下一章**：[07 - 记忆系统实战](../07-memory-system/README.md) —— 深入理解 Nanobot 的双层记忆架构"}}}}