安装指南
下载单文件程序、接进你的 AI 客户端、重启验证。全程不需要登录，也不需要 Node.js 或 Docker。
一、下载
小本本是单文件可执行程序，下载即用。统一放在用户目录下的 ~/.xiaobenben/bin/（Windows 为 %USERPROFILE%\.xiaobenben\bin\）。
| 操作系统 | 文件名 | 下载地址 |
|---|---|---|
| Windows x64 | xbb-windows-x64.exe | https://dl.xiaobenben.net/latest/xbb-windows-x64.exe |
| macOS（Apple Silicon） | xbb-darwin-arm64 | https://dl.xiaobenben.net/latest/xbb-darwin-arm64 |
| macOS（Intel） | xbb-darwin-x64 | https://dl.xiaobenben.net/latest/xbb-darwin-x64 |
| Linux x64 | xbb-linux-x64 | https://dl.xiaobenben.net/latest/xbb-linux-x64 |
latest/ 是稳定别名，永远指向当前发布版。需要固定某一版做归档或复现时，把 latest 换成 releases/v<版本号>，例如 https://dl.xiaobenben.net/releases/v0.4.42/xbb-windows-x64.exe。
# macOS / Linux
mkdir -p ~/.xiaobenben/bin
curl -L -o ~/.xiaobenben/bin/xbb "https://dl.xiaobenben.net/latest/xbb-darwin-arm64"
chmod +x ~/.xiaobenben/bin/xbb
# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.xiaobenben\bin"
# 把下载的 exe 放到该目录，并重命名为 xbb.exe
建议统一重命名为 xbb（macOS / Linux）或 xbb.exe（Windows）——本文档后续所有命令都按这个名字写。
下载后可以核对 SHA-256：https://dl.xiaobenben.net/latest/SHA256SUMS.txt。
二、向量增强包（可选，但建议装）
不装也能用，检索会自动降级为关键词模式；装上之后具备语义匹配——口语改写、近义表达、换个说法也能命中。
| 平台 | 包名 |
|---|---|
| Windows x64 | xbb-ort-windows-x64.zip |
| macOS（Apple Silicon） | xbb-ort-darwin-arm64.zip |
| macOS（Intel） | 没有这个包，该平台无原生库，检索自动为关键词模式 |
| Linux x64 | xbb-ort-linux-x64.zip |
解压到 bin 目录（解压后得到 node_modules/ 文件夹，与可执行文件同层）：
# Windows
Expand-Archive xbb-ort-windows-x64.zip -DestinationPath "$env:USERPROFILE\.xiaobenben\bin\"
# macOS / Linux
unzip xbb-ort-darwin-arm64.zip -d ~/.xiaobenben/bin/
向量模型（约 24MB）在首次使用时自动下载到本机，不需要手动处理。
三、接进 AI 客户端
不需要任何环境变量。 客户端默认就把库放在 ~/.xiaobenben/memory.db。旧文档里的 XBB_DB 已废弃，新版不再读取。
一句话让 AI 自己装
把下面这句话粘贴到你的 AI 对话框，它会读完安装文档、下载、配置好：
请你按照链接说明为当前编辑器安装MCP：https://xiaobenben.net/doc/install/ai.md
注意：如果你的客户端只给沙箱权限（装不到真实系统目录），AI 会提示你开启完全访问，否则装了也随会话销毁。WorkBuddy 用户需要先打开「允许完全访问」。
手动配置（按客户端选一个）
Claude Code —— 命令行一条：
claude mcp add xiaobenben -- ~/.xiaobenben/bin/xbb mcp
opencode —— ~/.config/opencode/opencode.json：
{
"mcp": {
"xiaobenben": {
"type": "local",
"command": ["~/.xiaobenben/bin/xbb", "mcp"],
"enabled": true
}
}
}
opencode 的 command 是数组，其他客户端多为字符串，注意别抄错。
WorkBuddy —— ~/.workbuddy/mcp.json：
{
"mcpServers": {
"xiaobenben": {
"command": "C:\\Users\\你的用户名\\.xiaobenben\\bin\\xbb.exe",
"args": ["mcp"]
}
}
}
WorkBuddy 还有三步界面操作，AI 代不了：
- 彻底重启：先关主窗口，再右键任务栏托盘图标 → 退出（只关窗口它还在后台，配置不会重读），然后重新启动；
- 信任连接器：左侧「专家 · 技能 · 连接器」→「连接器」→ 右上角「自定义连接器」→ 找到
xiaobenben点授权； - 授权后「MCP 服务管理」里开关应为开启状态。
Cursor / Windsurf / Cline / Trae / 豆包桌面版：字段名各家不同但结构相同（command + args）。逐步带截图的手册见：
四、验证
MCP 配置只在客户端启动时加载，所以改完必须彻底重启客户端，否则工具不会出现。
重启后有两种验证方式：
看 AI 认不认得。 问一句”你现在有哪些小本本的工具？“——它应该能列出 write_memory、search_memory、recall_topic 等。
看库文不文件。 让 AI 记一条（“帮我记住：这个项目用 pnpm”），然后：
~/.xiaobenben/bin/xbb stats
能看到条数增加，就说明整条链路通了。
五、多个客户端共享同一份记忆
这是小本本的设计前提，不是附加功能：多个 AI 客户端必须共用同一个库文件。
- 所有客户端都用默认路径
~/.xiaobenben/memory.db，不要任何一方自定义路径； - 库文件已存在时绝不覆盖、绝不重建——第一个客户端建好之后，后面装的所有客户端共享它。
路径一旦不一致，记忆会静默分裂：每个客户端都”有记忆”，但各自只记得自己那部分，且没有任何报错。
常见卡点
Windows 首次运行弹 SmartScreen「已保护你的电脑」 —— 程序尚未做商业代码签名，点「更多信息」→「仍要运行」即可。
杀毒软件把 exe 隔离 —— 单文件程序体积较大（60–90MB），首次运行时被实时扫描拦下是常见现象。把 ~/.xiaobenben/ 加入排除目录。
装完看不到工具 —— 99% 是没有彻底重启客户端。只关窗口不算，要退出进程。
Windows 11 24H2 上启动即退出 —— 已在 v0.4.41 修复（系统目录里的旧版 onnxruntime 被优先加载导致原生层崩溃）。执行 xbb update 升级到 0.4.42 及以上，再重启客户端。
自更新
装好之后不必每次手动下载：
xbb update # 检查并应用更新
xbb update-status # 看当前源地址、有无待应用更新
托盘菜单和管理窗口（http://127.0.0.1:17630/ui）里也有「检查更新」。更新文件就位后需要重启小本本才生效——AI 不会替你重启。
更新包带 ed25519 签名，公钥内置在程序里，所以即使下载源被劫持也签不出可用清单。