wehub-resource-sync
400 lines
19 KiB
Markdown
400 lines
19 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/HKUDS/nanobot) · [上游 README](https://github.com/HKUDS/nanobot/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="./images/readme-cover-dark.png">
|
||
<img alt="nanobot README 封面" src="./images/readme-cover-light.png">
|
||
</picture>
|
||
|
||
<div align="center">
|
||
<p>
|
||
<a href="https://nanobot.wiki/docs/latest/getting-started/nanobot-overview">English</a> |
|
||
<a href="https://nanobot.wiki/cn/docs/latest/getting-started/nanobot-overview">简体中文</a> |
|
||
<a href="https://nanobot.wiki/zh-Hant/docs/latest/getting-started/nanobot-overview">繁體中文</a> |
|
||
<a href="https://nanobot.wiki/es/docs/latest/getting-started/nanobot-overview">Español</a> |
|
||
<a href="https://nanobot.wiki/fr/docs/latest/getting-started/nanobot-overview">Français</a> |
|
||
<a href="https://nanobot.wiki/id/docs/latest/getting-started/nanobot-overview">Bahasa Indonesia</a> |
|
||
<a href="https://nanobot.wiki/ja/docs/latest/getting-started/nanobot-overview">日本語</a> |
|
||
<a href="https://nanobot.wiki/ko/docs/latest/getting-started/nanobot-overview">한국어</a> |
|
||
<a href="https://nanobot.wiki/ru/docs/latest/getting-started/nanobot-overview">Русский</a> |
|
||
<a href="https://nanobot.wiki/vi/docs/latest/getting-started/nanobot-overview">Tiếng Việt</a>
|
||
</p>
|
||
<p>
|
||
<a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/pypi/v/nanobot-ai" alt="PyPI"></a>
|
||
<a href="https://pepy.tech/project/nanobot-ai"><img src="https://static.pepy.tech/badge/nanobot-ai" alt="Downloads"></a>
|
||
<img src="https://img.shields.io/badge/python-≥3.11-blue" alt="Python">
|
||
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
|
||
<a href="https://github.com/HKUDS/nanobot/graphs/commit-activity" target="_blank">
|
||
<img alt="上月提交" src="https://img.shields.io/github/commit-activity/m/HKUDS/nanobot?labelColor=%20%2332b583&color=%20%2312b76a"></a>
|
||
<a href="https://github.com/HKUDS/nanobot/issues?q=is%3Aissue%20is%3Aclosed" target="_blank">
|
||
<img alt="已关闭 Issue" src="https://img.shields.io/github/issues-search?query=repo%3AHKUDS%2Fnanobot%20is%3Aissue%20is%3Aclosed&label=issues%20closed&labelColor=%20%237d89b0&color=%20%235d6b98"></a>
|
||
<a href="https://twitter.com/intent/follow?screen_name=nanobot_project" target="_blank">
|
||
<img src="https://img.shields.io/twitter/follow/nanobot_project?logo=X&color=%20%23f5f5f5" alt="follow on X(Twitter)"></a>
|
||
<a href="https://nanobot.wiki/docs/latest/getting-started/nanobot-overview"><img src="https://img.shields.io/badge/Docs-nanobot.wiki-blue?style=flat&logo=readthedocs&logoColor=white" alt="Docs"></a>
|
||
<a href="./COMMUNICATION.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
|
||
<a href="./COMMUNICATION.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
|
||
<a href="https://discord.gg/MnCvHqpUGB"><img src="https://img.shields.io/badge/Discord-Community-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
|
||
</p>
|
||
</div>
|
||
|
||
🐈 **nanobot** 是一款开源、超轻量的个人 AI 智能体（agent），你可以真正拥有它。它将智能体核心保持小巧且可读，同时提供适用于真实长期工作的实用组件：WebUI、聊天渠道、工具、记忆、MCP、模型路由、自动化与部署。
|
||
|
||
## 从这里开始
|
||
|
||
| 你想要... | 前往 |
|
||
|---|---|
|
||
| 无需终端/配置背景即可安装 nanobot | [零基础入门](./docs/start-without-technical-background.md) |
|
||
| 快速安装并获得一条 CLI 回复 | [安装](#-安装) 与 [快速开始](#-快速开始) |
|
||
| 打开内置浏览器 UI | [WebUI](#-webui) |
|
||
| 连接 Telegram、Discord、WeChat、Slack、Email、Mattermost 或其他聊天应用 | [聊天应用](./docs/chat-apps.md) |
|
||
| 配置提供商、回退模型、Langfuse、MCP、Web 工具或安全设置 | [文档](./docs/README.md) 与 [配置](./docs/configuration.md) |
|
||
| 理解或扩展内部实现 | [架构](./docs/architecture.md) 与 [开发](./docs/development.md) |
|
||
|
||
## nanobot 能做什么？
|
||
|
||
nanobot 是一个可自托管的个人 AI 智能体运行时。它可以：
|
||
|
||
- 在浏览器 WebUI 或终端中运行
|
||
- 连接 Telegram、Discord、Slack、WeChat、Email、Mattermost 及其他聊天应用
|
||
- 使用文件、shell、Web 搜索、Web 抓取、MCP、cron、图像生成和子智能体（subagents）等工具
|
||
- 通过 Dream 保留会话历史与长期记忆
|
||
- 运行长期目标与定时自动化
|
||
- 提供 Python SDK 与 OpenAI 兼容 API，便于集成
|
||
- 部署为长期运行的本地或服务端智能体网关
|
||
|
||
## 最新版本
|
||
|
||
**v0.2.2 - Durability Release**
|
||
|
||
亮点：
|
||
|
||
- 分段式 WebUI 对话记录
|
||
- Python SDK 运行时控制
|
||
- 自动化管理
|
||
- 搜索/STT 提供商改进
|
||
- 网关/会话/提供商可靠性提升
|
||
|
||
[查看完整更新日志](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2)
|
||
|
||
## 开源合作伙伴
|
||
|
||
<p align="center">
|
||
<a href="https://platform.kimi.com?aff=nanobot"><picture><source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg"><img alt="Kimi Open Source Friends" height="44" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0"></picture></a>
|
||
<a href="https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link"><img alt="MiniMax" height="40" src="https://mintcdn.com/minimax-zh/1UjvBcdoC6r0UeyA/logo/light.svg?fit=max&auto=format&n=1UjvBcdoC6r0UeyA&q=85&s=672d724b639b2d88d0702fae329ea4f8"></a>
|
||
</p>
|
||
|
||
## 近期更新
|
||
|
||
- **2026-06-21** Python SDK 运行时控制、可选 Keenable 密钥、更简洁的运行钩子。
|
||
- **2026-06-20** Telegram 富文本消息、更安全的 SDK 并发、更顺畅的快速开始。
|
||
- **2026-06-19** Firecrawl 应用、OpenAI 图像编辑、更安全的会话删除。
|
||
- **2026-06-18** 飞书恢复、Keenable 搜索、Mistral 优化、工作区感知的 git。
|
||
- **2026-06-17** 默认空闲自动压缩、更清晰的 `/dream`、macOS 安装器修复。
|
||
|
||
更早的更新请见[发布归档](./docs/release-archive.md)或 [GitHub releases](https://github.com/HKUDS/nanobot/releases).
|
||
|
||
## 💡 为什么选择 nanobot
|
||
|
||
- **持久化工作流**：目标、记忆、工具与聊天上下文可在长期工作中持续保留。
|
||
- **聊天原生触达**：WebUI、API、Telegram、飞书、Slack、Discord、Teams、邮件与 Mattermost。
|
||
- **模型自由**：OpenAI 兼容 API、本地 LLM、图像生成、搜索与回退模型。
|
||
- **小巧核心**：内部实现可读，内置 MCP、记忆、部署与自动化。
|
||
- **拥有你的技术栈**：无需庞大平台，即可检查、定制、自托管与扩展。
|
||
|
||
## 📦 安装
|
||
|
||
> [!IMPORTANT]
|
||
> 若你需要最新功能与实验特性，请从源码安装。
|
||
>
|
||
> 若你追求最稳定的日常使用体验，请通过 PyPI 安装或使用 `uv`。
|
||
|
||
请选择**一种**安装方式：
|
||
|
||
前置条件：Python 3.11 或更高版本。仅源码安装需要 Git；仅在你开发 WebUI 本身时才需要 Node.js/Bun。
|
||
|
||
若终端、API 密钥或配置文件对你而言尚不熟悉，请使用[零基础入门](./docs/start-without-technical-background.md)中的引导式教程，而非本精简 README 路径。
|
||
|
||
**一键安装**
|
||
|
||
macOS / Linux：
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
|
||
```
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
|
||
```
|
||
|
||
默认命令会从 PyPI 安装或升级 `nanobot-ai`，然后启动 `nanobot onboard --wizard`。它通过使用活动虚拟环境、`uv`、`pipx`，或 `~/.nanobot/venv` 下的托管 venv，避免系统级 pip 安装。若快速开始已完成，请跳过下方手动初始化/配置步骤，直接进入**打开 WebUI**。
|
||
|
||
若要在不更改环境的情况下预览计划，请传入 `--dry-run`；当你想预览 main 分支安装时，可将其与 `--dev` 组合使用。
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run
|
||
```
|
||
|
||
```powershell
|
||
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run
|
||
```
|
||
|
||
若要安装当前的 `main` 分支，请传入 `--dev`：
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev
|
||
```
|
||
|
||
```powershell
|
||
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev
|
||
```
|
||
|
||
若你想先查看脚本，可打开 [`scripts/install.sh`](./scripts/install.sh) 或 [`scripts/install.ps1`](./scripts/install.ps1)。
|
||
|
||
**使用 `uv` 安装**
|
||
|
||
```bash
|
||
uv tool install nanobot-ai
|
||
```
|
||
|
||
**使用 pip 从 PyPI 安装**
|
||
|
||
```bash
|
||
python -m pip install nanobot-ai
|
||
```
|
||
|
||
若在 macOS 或 Linux 上 pip 报告 `externally-managed-environment`，请使用一键安装器、`uv tool install nanobot-ai`、`pipx install nanobot-ai`，或在虚拟环境中安装。
|
||
|
||
**从源码安装**
|
||
|
||
```bash
|
||
git clone https://github.com/HKUDS/nanobot.git
|
||
cd nanobot
|
||
python -m pip install -e .
|
||
```
|
||
|
||
验证安装：
|
||
|
||
```bash
|
||
nanobot --version
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
**1. 初始化**
|
||
|
||
若一键设置已启动向导并在其中完成快速开始，可跳过此步骤。
|
||
|
||
```bash
|
||
nanobot onboard
|
||
```
|
||
|
||
若你偏好交互式设置，请使用 `nanobot onboard --wizard`。
|
||
|
||
**2. 配置**（`~/.nanobot/config.json`）
|
||
|
||
若你已在向导中配置好提供商（provider）和模型设置，可跳过此步骤。
|
||
|
||
`nanobot onboard` 会创建 `~/.nanobot/config.json` 和 `~/.nanobot/workspace/`。请在配置文件中配置这 **两部分**。将以下代码块添加或合并到现有文件中，而不是替换整个文件。
|
||
|
||
下方示例使用通用的 OpenAI 兼容 `custom` 提供商，以便精简路径不会推荐某一托管服务。提供商示例是配方（recipe），而非排名或背书。可复制粘贴的提供商专属设置见 [Provider Cookbook](./docs/provider-cookbook.md)。
|
||
|
||
*设置你的 API 密钥*：
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"custom": {
|
||
"apiKey": "your-api-key",
|
||
"apiBase": "https://api.example.com/v1"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
*设置模型预设并设为活动状态*：
|
||
|
||
```json
|
||
{
|
||
"modelPresets": {
|
||
"primary": {
|
||
"label": "Primary",
|
||
"provider": "custom",
|
||
"model": "model-id-from-your-provider",
|
||
"maxTokens": 8192,
|
||
"contextWindowTokens": 200000,
|
||
"temperature": 0.1
|
||
}
|
||
},
|
||
"agents": {
|
||
"defaults": {
|
||
"modelPreset": "primary"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
直接配置 `agents.defaults.provider` 和 `agents.defaults.model` 对现有配置仍然有效，但命名预设是推荐路径，因为它们还支持 `/model` 切换和 `fallbackModels`。
|
||
|
||
对于其他提供商，配置结构相同：
|
||
|
||
| 替换项 | 位置 |
|
||
|---|---|
|
||
| Provider config key | `providers.<provider>` |
|
||
| API key | `providers.<provider>.apiKey` |
|
||
| Preset provider name | `modelPresets.primary.provider` |
|
||
| Model ID | `modelPresets.primary.model` |
|
||
| Endpoint URL, only when needed | `providers.<provider>.apiBase` |
|
||
|
||
**3. 打开 WebUI**
|
||
|
||
启动浏览器工作台：
|
||
|
||
```bash
|
||
nanobot webui
|
||
```
|
||
|
||
`nanobot webui` 会在需要时准备本地 WebSocket 通道，启动 gateway，并打开 `http://127.0.0.1:8765`。默认将首次运行的 WebUI 绑定到 `127.0.0.1`，因此不会暴露到你的局域网（LAN）。不想一直开着终端？使用 `nanobot webui --background`，然后用 `nanobot gateway status`、`logs`、`restart` 和 `stop` 管理 gateway。
|
||
|
||
若需手动或仅终端设置，可测试一条 CLI 消息：
|
||
|
||
```bash
|
||
nanobot status
|
||
nanobot agent -m "Hello!"
|
||
```
|
||
|
||
在 `nanobot status` 中，大多数提供商显示 `not set` 是正常的。活动预设的提供商应已配置，且 `Config` 与 `Workspace` 应显示勾选标记。
|
||
|
||
若上述步骤正常，可启动交互式聊天：
|
||
|
||
```bash
|
||
nanobot agent
|
||
```
|
||
|
||
需要 `PATH`、API 密钥、提供商/模型匹配或 JSON 错误方面的帮助？请参阅更完整的 [Install and Quick Start](./docs/quick-start.md) 与 [Troubleshooting](./docs/troubleshooting.md)。
|
||
|
||
- 想要可粘贴的提供商设置？见 [Provider Cookbook](./docs/provider-cookbook.md)
|
||
- 想了解提供商/模型匹配？见 [Providers and Models](./docs/providers.md)
|
||
- 需要网页搜索、MCP、安全设置或更多配置选项？见 [Configuration](./docs/configuration.md)
|
||
- 想在本地运行？见 [Ollama](./docs/providers.md#ollama)、[vLLM or another local OpenAI-compatible server](./docs/providers.md#vllm-or-other-local-openai-compatible-server)，以及完整的 [provider reference](./docs/configuration.md#providers)。
|
||
- 想在 Telegram、Discord、WeChat 或 Feishu 等聊天应用中使用 nanobot？见 [Chat Apps](./docs/chat-apps.md)
|
||
- 需要 Docker 或 Linux 服务部署？见 [Deployment](./docs/deployment.md)
|
||
|
||
## 🌐 WebUI
|
||
|
||
WebUI **内置于已发布的 wheel 包中** — 无需额外构建步骤。它是用于聊天会话、工作区控制、Apps、Skills、Automations 和设置的浏览器工作台。完整用户指南见 [`docs/webui.md`](./docs/webui.md)。
|
||
|
||
<p align="center">
|
||
<img src="images/nanobot_webui.png" alt="nanobot webui preview" width="900">
|
||
</p>
|
||
|
||
**打开方式**
|
||
|
||
```bash
|
||
nanobot webui
|
||
```
|
||
|
||
该命令在确认后启用本地 WebSocket 通道，启动 gateway，并打开 [`http://127.0.0.1:8765`](http://127.0.0.1:8765). 若要从局域网中的另一台设备打开，见 [WebUI docs -> LAN access](./docs/webui.md#lan-access)。
|
||
|
||
WebUI 默认由 WebSocket 通道在端口 `8765` 上提供服务。gateway 的 `18790` 端口用于健康检查端点，而非浏览器 UI。
|
||
|
||
> [!TIP]
|
||
> 正在开发 WebUI 本身？请参阅 [`webui/README.md`](./webui/README.md) 了解源码树、Vite 开发服务器、构建与测试工作流。
|
||
|
||
## 🏗️ 架构
|
||
|
||
<p align="center">
|
||
<img src="images/nanobot_arch.png" alt="nanobot architecture" width="800">
|
||
</p>
|
||
|
||
🐈 nanobot 通过围绕一个精简的 agent 循环来保持轻量：消息从聊天应用进入，LLM 决定何时需要工具，memory 或 skills 仅作为上下文按需拉入，而不是变成沉重的编排层。这使核心路径清晰易读、易于扩展，同时仍允许你添加 channels、tools、memory 和部署选项，而不会把系统变成单体应用。
|
||
|
||
## ✨ 功能
|
||
|
||
<table align="center">
|
||
<tr align="center">
|
||
<th><p align="center">📈 24/7 Real-Time Market Analysis</p></th>
|
||
<th><p align="center">🚀 Full-Stack Software Engineer</p></th>
|
||
<th><p align="center">📅 Smart Daily Routine Manager</p></th>
|
||
<th><p align="center">📚 Personal Knowledge Assistant</p></th>
|
||
</tr>
|
||
<tr>
|
||
<td align="center"><p align="center"><img src="case/search.gif" width="180" height="400"></p></td>
|
||
<td align="center"><p align="center"><img src="case/code.gif" width="180" height="400"></p></td>
|
||
<td align="center"><p align="center"><img src="case/schedule.gif" width="180" height="400"></p></td>
|
||
<td align="center"><p align="center"><img src="case/memory.gif" width="180" height="400"></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center">Discovery • Insights • Trends</td>
|
||
<td align="center">Develop • Deploy • Scale</td>
|
||
<td align="center">Schedule • Automate • Organize</td>
|
||
<td align="center">Learn • Memory • Reasoning</td>
|
||
</tr>
|
||
</table>
|
||
|
||
## 📚 文档
|
||
|
||
浏览 [repo docs](./docs/README.md) 获取最新功能与 GitHub 开发版信息，或访问 [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) 查看稳定版文档。
|
||
|
||
- 使用面向任务的指南：[Guides](./docs/guides/README.md)
|
||
- 无技术背景入门：[Start Without Technical Background](./docs/start-without-technical-background.md)
|
||
- 从零开始并具备开发者基础：[Install and Quick Start](./docs/quick-start.md)
|
||
- 理解运行时模型：[Concepts](./docs/concepts.md)
|
||
- 阅读源码级概览：[Architecture](./docs/architecture.md)
|
||
- 选择提供商/模型：[Providers and Models](./docs/providers.md)
|
||
- 复制提供商设置配方：[Provider Cookbook](./docs/provider-cookbook.md)
|
||
- 调试设置与运行时故障：[Troubleshooting](./docs/troubleshooting.md)
|
||
- 用熟悉的聊天应用与 nanobot 对话：[Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) · [Chat Apps](./docs/chat-apps.md)
|
||
- 调度或触发 agent 工作：[Automations](./docs/automations.md)
|
||
- 配置提供商、网页搜索、MCP 与运行时行为：[Configuration](./docs/configuration.md)
|
||
- 将 nanobot 与本地工具和自动化集成：[OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md)
|
||
- 使用 Docker 或作为 Linux 服务运行 nanobot：[Deployment](./docs/deployment.md)
|
||
|
||
## 🤝 贡献与路线图
|
||
|
||
欢迎提交 PR！代码库刻意保持小巧且易读。🤗
|
||
|
||
### 贡献流程
|
||
|
||
有关环境搭建、代码审查与贡献指南，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
||
|
||
**路线图** — 选择一项并 [提交 PR](https://github.com/HKUDS/nanobot/pulls)!
|
||
|
||
- **多模态（Multi-modal）** — 看见与听见（图像、语音、视频）
|
||
- **长期记忆（Long-term memory）** — 永不遗忘重要上下文
|
||
- **更强的推理（Better reasoning）** — 多步规划与反思
|
||
- **更多集成** — 日历等
|
||
- **自我改进（Self-improvement）** — 从反馈与错误中学习
|
||
|
||
## 联系方式
|
||
|
||
本项目由 [Xubin Ren](https://github.com/re-bin) 发起，作为一项个人开源项目，并仍以个人身份、利用个人资源进行维护，同时得到开源社区的贡献。如有问题、想法或合作意向，欢迎联系 [xubinrencs@gmail.com](mailto:xubinrencs@gmail.com)。
|
||
|
||
### 贡献者
|
||
|
||
<a href="https://github.com/HKUDS/nanobot/graphs/contributors">
|
||
<img src="https://contrib.rocks/image?repo=HKUDS/nanobot&max=100&columns=12&updated=20260210" alt="Contributors" />
|
||
</a>
|
||
|
||
|
||
## ⭐ Star 历史
|
||
|
||
<div align="center">
|
||
<a href="https://star-history.com/#HKUDS/nanobot&Date">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/nanobot&type=Date&theme=dark" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/nanobot&type=Date" />
|
||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/nanobot&type=Date" style="border-radius: 15px; box-shadow: 0 0 30px rgba(0, 217, 255, 0.3);" />
|
||
</picture>
|
||
</a>
|
||
</div>
|
||
|
||
<p align="center">
|
||
<em> 感谢访问 ✨ nanobot！</em><br><br>
|
||
<img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.nanobot&style=for-the-badge&color=00d4ff" alt="Views">
|
||
</p>
|