第十篇：实战演练 —— 用 nanobot 打造一个私人助手

从零开始，2 小时搭建属于你的"第二大脑"：集成日程管理、自动日报、知识记忆

经过前九篇源码级解析，我们已经深入理解了 nanobot 的每一块积木：核心循环、插件系统、LLM 交互、记忆机制、工具调用、配置与日志。现在是时候把这些知识组装起来，打造一个真正能用的私人助手了。

本文将带领你从零开始，完成一个功能完备的私人助手，它能够：

• ✅ 记住你的偏好（如称呼、工作领域）
• ✅ 管理日程（添加/查询待办事项）
• ✅ 自动生成日报（每晚总结当日工作）
• ✅ 联网搜索（查询实时信息）
• ✅ 多渠道接入（Telegram + 命令行）

让我们动手吧！

---

1. 项目规划：我们要造什么？

在动手之前，先明确我们的私人助手应该具备哪些能力。

1.1 功能脑图

root（我的私人助手）
核心对话
多轮对话
上下文记忆
人格设定
日程管理
添加待办
查询今日任务
标记完成
知识记忆
记住用户偏好
存储重要事实
自动写入MEMORY
日报系统
收集今日活动
每晚9点自动生成
发送摘要
工具集成
联网搜索
文件读写
定时任务
接入方式
命令行（CLI）
Telegram机器人

1.2 技术选型

组件	选择	理由
LLM 提供商	OpenRouter	一次配置，可切换多种模型（Claude/GPT/DeepSeek）
本地模型（可选）	vLLM + Qwen2.5	需要离线或隐私保护时使用
消息通道	Telegram	配置简单，支持移动端
记忆存储	文件系统	无需数据库，可读可改
定时任务	内置 cron 工具	nanobot 原生支持
部署环境	Ubuntu 22.04	稳定，支持 systemd 守护

---

2. 第一步：环境准备与初始化

2.1 安装 nanobot

安装命令参考：

# 使用 uv 快速安装（推荐）
pip install uv
uv tool install nanobot-ai

# 或使用 pip 直接安装
pip install nanobot-ai

2.2 初始化工作区

nanobot onboard

这条命令会在 ~/.nanobot/ 下创建：

• config.json - 主配置文件
• workspace/ - 工作目录（工具操作的安全边界）
• workspace/MEMORY.md - 长期记忆文件
• workspace/AGENTS.md - Agent 人格定义
• workspace/skills/ - 技能存放目录

2.3 验证安装

nanobot status

如果看到配置信息和运行状态，说明安装成功 。

---

3. 第二步：配置 LLM 提供商

3.1 配置 OpenRouter（推荐）

编辑 ~/.nanobot/config.json：

配置参考：

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-你的密钥"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-3.5-sonnet",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxIterations": 20
    }
  },
  "tools": {
    "restrictToWorkspace": true
  },
  "workspace": "/home/你的用户名/.nanobot/workspace"
}

3.2 配置本地模型（可选）

如果你希望完全离线使用，可以部署 vLLM + Qwen2.5：

本地部署参考：

# 安装 vLLM
pip install vllm

# 启动模型服务
vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000

然后修改配置：

{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "Qwen/Qwen2.5-7B-Instruct"
    }
  }
}

---

4. 第三步：定义 Agent 人格与记忆

nanobot 的"人格"和"记忆"都存储在可读的 Markdown 文件中，这是它最优雅的设计之一 。

4.1 编辑 AGENTS.md：定义你是谁

# 我是谁

我是一个专业的个人AI助理，我的用户是"小明"。
我是小明的工作助手，帮助他管理日程、记录想法、整理信息。

## 我的性格
- 专业但不失亲切
- 简洁明了，不啰嗦
- 主动提醒重要事项

## 我的职责
- 记录用户偏好和重要事实到 MEMORY.md
- 管理待办事项
- 每晚9点自动生成日报
- 需要时联网搜索信息

4.2 初始化 MEMORY.md：长期记忆

记忆系统设计参考：

## 用户信息
- 称呼：小明
- 职业：AI 研究员
- 工作领域：大模型应用开发
- 常用编程语言：Python、TypeScript

## 项目信息
- 当前项目：nanobot 私人助手开发
- 截止日期：2026-03-01

## 偏好
- 喜欢简洁的回答
- 日报格式：按项目分类
- 工作时间：9:00-18:00

4.3 测试人格与记忆

启动交互式会话，看看 Agent 是否记住了你的信息：

nanobot agent
> 你知道我叫什么吗？

如果配置正确，Agent 应该能从 MEMORY.md 中读取信息并正确回答。

---

5. 第四步：编写自定义工具

接下来，我们为私人助手添加两个核心工具：待办事项管理 和日报生成。

5.1 待办事项工具

在 ~/.nanobot/workspace/tools/todo.py 中创建：

from nanobot import tool
import json
from pathlib import Path
from datetime import datetime

TODO_FILE = Path.home() / ".nanobot" / "workspace" / "todo.json"

def _load_todos():
    """加载待办事项"""
    if TODO_FILE.exists():
        return json.loads(TODO_FILE.read_text())
    return {"tasks": []}

def _save_todos(todos):
    """保存待办事项"""
    TODO_FILE.write_text(json.dumps(todos, indent=2, ensure_ascii=False))

@tool(description="添加待办事项")
def add_todo(task: str, priority: str = "medium") -> str:
    """
    添加一个新的待办事项
    
    参数:
        task: 任务描述
        priority: 优先级 (high/medium/low)，默认为 medium
    """
    todos = _load_todos()
    new_task = {
        "id": len(todos["tasks"]) + 1,
        "task": task,
        "priority": priority,
        "created": datetime.now().isoformat(),
        "completed": False
    }
    todos["tasks"].append(new_task)
    _save_todos(todos)
    return f"✅ 已添加待办：{task}（优先级：{priority}）"

@tool(description="查询今日待办")
def list_todos(include_completed: bool = False) -> str:
    """
    列出待办事项
    
    参数:
        include_completed: 是否包含已完成事项
    """
    todos = _load_todos()
    today = datetime.now().date().isoformat()
    
    # 筛选今日创建或未完成的任务
    tasks = []
    for t in todos["tasks"]:
        if not include_completed and t["completed"]:
            continue
        created_date = t["created"][:10]
        status = "✅" if t["completed"] else "⏳"
        priority_mark = "🔴" if t["priority"] == "high" else "🟡" if t["priority"] == "medium" else "🟢"
        tasks.append(f"{status} {priority_mark} [{t['id']}] {t['task']}")
    
    if not tasks:
        return "🎉 今日没有待办事项！"
    
    return "📋 待办事项：\n" + "\n".join(tasks)

@tool(description="完成待办事项")
def complete_todo(task_id: int) -> str:
    """
    标记待办事项为已完成
    
    参数:
        task_id: 任务ID
    """
    todos = _load_todos()
    for t in todos["tasks"]:
        if t["id"] == task_id:
            if t["completed"]:
                return f"⚠️ 任务 {task_id} 已经完成了"
            t["completed"] = True
            _save_todos(todos)
            return f"✅ 任务 {task_id} 已完成：{t['task']}"
    return f"❌ 未找到任务 ID：{task_id}"

5.2 日报生成工具

创建 ~/.nanobot/workspace/tools/daily_report.py：

from nanobot import tool
from datetime import datetime
from pathlib import Path
import json

MEMORY_DIR = Path.home() / ".nanobot" / "workspace" / "memory"
TODO_FILE = Path.home() / ".nanobot" / "workspace" / "todo.json"

@tool(description="生成今日工作日报")
def generate_daily_report() -> str:
    """
    根据今日的活动和待办事项生成日报
    """
    today = datetime.now().strftime("%Y-%m-%d")
    
    # 收集今日笔记
    note_file = MEMORY_DIR / f"{today}.md"
    notes = ""
    if note_file.exists():
        notes = note_file.read_text()
    
    # 收集今日完成的待办
    completed_tasks = []
    if TODO_FILE.exists():
        todos = json.loads(TODO_FILE.read_text())
        for t in todos["tasks"]:
            if t["completed"] and t["created"][:10] == today:
                completed_tasks.append(t["task"])
    
    # 收集未完成但重要的任务
    pending_tasks = []
    if TODO_FILE.exists():
        todos = json.loads(TODO_FILE.read_text())
        for t in todos["tasks"]:
            if not t["completed"] and t["priority"] == "high":
                pending_tasks.append(t["task"])
    
    # 生成报告
    report = f"""# {today} 工作日报

## ✅ 今日完成
"""
    if completed_tasks:
        for t in completed_tasks:
            report += f"- {t}\n"
    else:
        report += "- 暂无完成任务\n"
    
    report += f"""
## ⏳ 进行中/待处理
"""
    if pending_tasks:
        for t in pending_tasks:
            report += f"- 🔴 {t}\n"
    else:
        report += "- 暂无高优先级待办\n"
    
    report += f"""
## 📝 今日笔记
{notes if notes else "无"}
"""
    
    # 保存日报到文件
    report_file = MEMORY_DIR / f"日报_{today}.md"
    report_file.write_text(report)
    
    return f"日报已生成：{report_file}\n\n{report}"

5.3 注册自定义工具

nanobot 会自动扫描 tools/ 目录下的 @tool 装饰器函数，无需额外注册 。重启 Agent 即可加载新工具。

---

6. 第五步：配置定时任务

我们希望助手每晚 9 点自动生成日报并发送。nanobot 内置了 cron 工具来实现定时任务 。

6.1 添加定时任务

通过对话让 Agent 设置定时任务：

用户：帮我设置一个定时任务，每晚 9 点生成日报并发送给我
Agent：好的，我来帮你设置。

Agent 会调用内置的 cron 工具，在配置中写入类似：

{
  "cron": {
    "daily_report": {
      "schedule": "0 21 * * *",
      "command": "generate_daily_report && send_message 日报已生成"
    }
  }
}

6.2 验证定时任务

nanobot cron list

应该能看到配置的定时任务列表。

---

7. 第六步：接入 Telegram

让助手走出命令行，成为随时可用的移动端服务。

7.1 创建 Telegram Bot

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot，按提示设置名称和用户名
3. 获取 API Token（形如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11）

7.2 获取你的用户 ID

1. 搜索 @userinfobot
2. 发送 /start，获取你的数字 ID

7.3 配置 Telegram 通道

编辑 ~/.nanobot/config.json，添加 channels 配置：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "你的机器人Token",
      "allowFrom": ["你的用户ID"]
    }
  }
}

allowFrom 限制只有你的 ID 可以使用机器人，增强安全性 。

7.4 启动网关服务

nanobot gateway

看到 [INFO] Telegram gateway started 说明启动成功。

现在，在 Telegram 中向你的机器人发送消息，它就会像在命令行中一样响应你。

---

8. 第七步：部署为后台服务

为了让助手 7×24 小时在线，我们需要把它部署为系统服务。

8.1 创建 systemd 服务

创建 /etc/systemd/system/nanobot.service：

[Unit]
Description=nanobot AI Assistant
After=network.target

[Service]
Type=simple
User=你的用户名
WorkingDirectory=/home/你的用户名/.nanobot
ExecStart=/usr/local/bin/nanobot gateway
Restart=always
RestartSec=10
Environment="PATH=/usr/local/bin:/usr/bin:/bin"

[Install]
WantedBy=multi-user.target

8.2 启动服务

sudo systemctl daemon-reload
sudo systemctl enable nanobot
sudo systemctl start nanobot
sudo systemctl status nanobot

---

9. 测试与验证

9.1 测试场景 1：记住偏好

用户：记得我喜欢简洁的回答
助手：好的，已记录您偏好简洁的回答风格。

检查 MEMORY.md，应该能看到新增的偏好记录。

9.2 测试场景 2：待办管理

用户：添加待办：写周报，优先级高
助手：✅ 已添加待办：写周报（优先级：high）

用户：今天有什么任务？
助手：📋 待办事项：
⏳ 🔴 [1] 写周报

9.3 测试场景 3：联网搜索

用户：搜索一下今天的 AI 新闻
助手：正在搜索...
（返回搜索结果）

9.4 测试场景 4：定时日报

等待晚上 9 点，检查 Telegram 是否收到自动推送的日报。

---

10. 项目总结与扩展方向

10.1 我们完成了什么？

模块	实现方式	对应前文
核心对话	nanobot AgentLoop	第三篇
记忆系统	MEMORY.md + 每日笔记	第六篇
工具调用	自定义 @tool 插件	第四、七篇
定时任务	内置 cron 工具	第七篇
多渠道接入	Telegram 通道	第二篇
配置管理	config.json + 环境变量	第八篇
部署运维	systemd 服务	第九篇

10.2 扩展方向

这个私人助手只是一个起点，你可以继续扩展：

1. 接入更多渠道：飞书、微信、Discord、QQ
2. 添加更多工具：GitHub API、天气查询、股票监控
3. 增强记忆：集成 Chroma 向量数据库实现语义搜索
4. 多 Agent 协作 ：使用 spawn 工具创建子代理处理并行任务
5. Web 管理界面：基于 Chainlit 或 OpenWebUI 构建可视化面板

---

写在最后

从第一篇的"初识 nanobot"到今天的"实战演练"，我们一起走过了十篇文章的旅程。我们看到了一个仅有 4000 行代码的项目，如何实现了 AI Agent 的核心能力；看到了港大团队如何用极简的工程哲学，打造出可读、可改、可用的开源框架。

nanobot 的价值不仅在于它的功能，更在于它证明了构建一个功能强大的 AI Agent 不需要复杂的微服务架构，单体 Python 脚本依然能打 。对于想学习 Agent 原理的开发者，对于需要快速搭建 AI 助手的团队，nanobot 都是一个绝佳的起点。

现在，轮到你动手了。克隆代码，跑起来，改一改，加个你自己的工具------你的"贾维斯"就在指尖。

项目地址：https://github.com/HKUDS/nanobot

---