henrydaum/second-brain · 上手攻略
- 仓库：henrydaum/second-brain
- 链接：https://github.com/henrydaum/second-brain
- 分类：AI Agent Framework / Personal Knowledge Management
- 作者：Tom
- 更新：2026-08-27
是什么
second-brain 是一个个人 agentic OS（操作系统级框架），核心理念是"把 AI 助手做成你机器的操作系统"。通过本地文件智能 + 工作流自动化 + 多模态消息平台通信，完成从文件处理、代码执行、邮件管理到网页搜索的全套任务。
核心架构分 10 个模块：
- Attachment Parsing — 解析各类附件（图片/文档/音频等）
- File Parsing — 索引并理解本地文件
- LLM Loop — 核心推理循环
- Path-Driven Tasks — 路径驱动的任务执行
- Event-Driven Tasks — 事件驱动的任务触发
- Conversation Runtime — 对话运行时
- Frontends — 多前端（Telegram、Web UI、REPL）
- Commands — 命令系统
- Plugins — 插件体系
- Sandbox & SDK — 沙箱隔离与 SDK
在 harness-bench（106 个沙箱离线 agent 任务）的评测中，second-brain 得分高于 OpenClaw 和 Hermes。
解决什么问题
传统 AI 助手（ChatGPT、Claude Web）的局限：
- 平台锁定：记忆绑定在单一服务商，换模型一切清零。
- 无法操控本地文件：只能对话，无法读写真实文件系统。
- 缺乏持久化记忆：每次会话从零开始，无法累积个人上下文。
- 多模态通信缺失：只能在网页里聊天，无法接入 Telegram、邮件等。
second-brain 把记忆层搬到本地 Markdown 文件，实现： - 记忆自主权：文件在本地，git 可版本化，换模型记忆无损迁移。 - 任务自主权：直接操控文件、运行脚本、执行 SQL、搜索网页。 - 通信自主权：Telegram / Web UI 多前端并行，消息推送到手机。
快速安装
环境要求
- Python 3.11+
- Git
方式一：直接安装（推荐）
git clone https://github.com/henrydaum/second-brain
cd second-brain
python -m venv .venv
# 激活虚拟环境
source .venv/bin/activate # macOS / Linux
# .venv\Scripts\activate # Windows
pip install -r requirements.txt
python main.py
安装完成，进入 REPL 后运行：
/setup
按引导完成四步：
1. 安装 essentials 插件包（LLM 后端 + 文件读写搜索 + Shell 脚本 + SQL + 网页搜索 + 子 agent + Telegram 前端）
2. 填入 API Key（Atlas Cloud 是赞助商快速入口，也支持任意 OpenAI 兼容端点）
3. Telegram（可选，需要 BotFather token + userinfobot ID）
4. Web UI（可选）
方式二：Docker
docker build -t second-brain .
docker run --rm -it --init -v sb-data:/data second-brain
⚠️ Docker 方式下容器默认无法访问宿主机文件系统，适用于服务器/NAS 等不便直接安装的场景。日常使用推荐直接安装。
Web UI 单独安装
Web UI 在独立仓库 second-brain-ui：
git clone https://github.com/henrydaum/second-brain-ui
cd second-brain-ui
npm install
cp .env.example .env.local
# 编辑 .env.local，填入 VITE_SB_TOKEN（来自 /config 中的 secret_http_token）
npm run dev
# 打开 http://localhost:5173
核心用法
REPL 命令
进入 REPL 后，用斜杠命令与 Second Brain 交互：
| 命令 | 功能 |
|---|---|
/setup |
首次配置引导 |
/config |
查看/修改配置项 |
/restart |
重启服务 |
/locations |
查看数据目录路径 |
/packages install |
安装插件包 |
/packages install frontend_http |
安装 Web UI 后端 |
配置关键参数
在 REPL 运行 /config，常用配置项：
sync_directories # 要索引的本地文件夹列表
secret_http_token # Web UI 访问令牌
llm_provider # LLM 提供商（Atlas Cloud / OpenAI / 兼容端点）
llm_api_key # API Key
插件包体系
/packages install
常用包：
| 包名 | 内容 |
|---|---|
bundle_knowledgebase |
PDF/Office/图片/音视频索引；OCR + 转录 + embedding + 三种搜索 |
bundle_memory |
自维护持久记忆；笔记和 skills 自动在相关时浮现 |
bundle_gmail |
Gmail 读写、回复、标签管理 |
frontend_http |
Web UI 后端 |
工作流程示例
# 在 REPL 中
Second Brain > 分析 ~/Documents 目录下所有 PDF 文件，做摘要
# → 触发 Path-Driven Task，扫描目录，解析每个 PDF，LLM Loop 汇总
Second Brain > 每天早上 8 点给我发一份当日待办
# → 触发 Event-Driven Task，配置定时任务，Telegram 推送
典型适用场景
- 个人知识中枢：把本地文件变成可查询的知识库，接入 Telegram 随时提问。
- 多模态消息流：Telegram 控制家里服务器，邮件摘要推送，手机端全搞定。
- 持久化个人 agent：session 500 能调用 session 5 的记忆上下文，实现真正意义的个人连续性。
- 快速自动化脚本：用自然语言写 Shell 脚本、SQL 查询，由 agent 执行并返回结果。
- 换模型零损失：记忆是 Markdown 文件，任何模型都能读，换模型不需要重新训练或迁移。
坑与注意
- Python 3.11+ 强依赖：Python 3.10 及以下不保证兼容性，安装前确认版本。
- 初次同步大量文件时任务消息刷屏：设置
sync_directories后首次索引会产生大量任务消息，属正常现象，完成后自动停止。 - Web UI token 不匹配最常见问题：如果看到空白页或 401，先检查
.env.local中的VITE_SB_TOKEN与/config中secret_http_token是否一致。 - bundle_knowledgebase 是大下载：包含 embedding 模型，首次安装需要较长时间和网络带宽。
- 数据目录因 OS 而异：Windows
%LOCALAPPDATA%\Second Brain\、macOS~/Library/Application Support/Second Brain/、Linux~/.local/share/Second Brain/。 - 评测结果来自作者自测：harness-bench 上击败 OpenClaw/Hermes 的结论来自作者本人的评测环境，实际效果因模型和配置不同可能存在差异。
与同类对比
| 维度 | second-brain | OpenClaw | Athena-Public | Mem0 |
|---|---|---|---|---|
| 记忆持久化 | 本地 Markdown | 多端同步 | 本地 Markdown | 云端 embedding |
| 模型兼容性 | 任意 OpenAI 兼容 | 多协议 | 任意 LLM | 通用 |
| 多前端 | REPL / Telegram / Web UI | Discord/多平台 | AI IDE 内 | API |
| 文件操控 | 原生 | 原生 | 有限 | ❌ |
| 工作流自动化 | 路径+事件驱动 | 工作流引擎 | ❌ | ❌ |
| 开源 | ✅ MIT | ✅ Apache 2.0 | ✅ MIT | ❌ 部分开源 |
| 评测基准 | harness-bench 自测 | 无 | 无 | 无 |
核心差异化：second-brain 把"个人操作系统"这件事做到最彻底——记忆是文件、前端是 Telegram/Web、工具是本地 Shell。相比之下多数框架还是"chat with your files"，而 second-brain 是"live with your files"。
一句话推荐结论
如果你想拥有一个永久属于自己、换模型不丢失记忆、能操控本地文件、装在口袋里的 AI 操作系统，second-brain 是目前个人 agent 框架中完成度最高的选项之一。
来源：GitHub README (raw) · second-brain-evals repo · second-brain-eval-results repo · harness-bench.ai · second-brain-ui repo · docs/DOCKER.md