Bike4Mind/bike4mind · 上手攻略

  • 仓库：Bike4Mind/bike4mind
  • 链接：https://github.com/Bike4Mind/bike4mind
  • 分类：ai / agent / rag / llm-infra
  • 作者：spark
  • 更新：2026-10-27

一、是什么

Bike4Mind 是一个开核心（open-core）AI 工作台，把「Notebook（笔记本）+ 自主 Agent + RAG 知识引擎 + 图像/语音模型」打包进同一个工作空间，宣称"任何模型都能接入、数据留在自己手里"。

技术栈是 TypeScript，pnpm + Turborepo 单体仓（要求 Node 24），主应用是 apps/client（Next.js SPA + pages API 后端），核心引擎在 b4m-core/*（对外发布为 @bike4mind/* 系列包），packages/cli 是带 ReAct Agent 的交互式命令行，packages/database 是 Mongoose 模型与迁移。实时 WebSocket 扇出走独立的 @bike4mind/subscriber-fanout 镜像。

仓库的自我定位是"Your bicycle for the mind in the age of AI"——把它理解成"AI 时代的自行车"：不是汽车（不是全自动托管平台），而是让你自己蹬、但省力的个人工具。

二、解决什么问题

它想解决的是多模型工作流的碎片化：很多人同时用 Claude / GPT / Gemini / xAI / 本地 Ollama，每换一个模型就要换一套 Notebook、换一套 Agent、换一套知识库。Bike4Mind 把这些做成一个工作空间内的可切换能力：

  • Notebooks — 核心工作区：聊天、文档、上下文放在一起，跨模型复用。
  • Multi-LLM by design — 在 Anthropic、OpenAI、Google Gemini、xAI、Ollama（本地）之间自由切换；图像侧支持 GPT-Image-2、Nano Banana、FLUX。
  • Quest Master — 自主多步任务规划：文本与图像生成、视觉复核、Web 搜索、数学、代码、人在环（human-in-the-loop）步骤，并行执行。
  • AI Agents — ReAct 风格 Agent，对你的工具和知识库动手干活。
  • Knowledge Engine — 对自有文档做 RAG：智能分块、向量检索、collections、标签。
  • Artifacts — Agent 产出的可复用片段、文档、可视化，带内置的发布/分享层。

一句话：给个人和小团队一个"自托管的 ChatGPT + Notebook + Agent 编排台"。

三、快速安装

路径 A：托管服务（最快，零安装）

直接到 https://app.bike4mind.com 登录即可，无需安装任何东西。

路径 B：自托管（Docker Compose，无需云账号）

前置条件：Docker + Docker Compose，约 4 GB 可用内存；还需要你打算使用的模型厂商 API Key（Anthropic / OpenAI / Gemini / xAI / DeepSeek / Moonshot(Kimi) / 或本地 Ollama）。

git clone https://github.com/bike4mind/bike4mind.git
cd bike4mind

# 复制环境变量模板
cp .env.selfhost.example .env.selfhost

# 生成三个必需密钥（各为 32 字节随机 hex）
openssl rand -hex 32   # -> JWT_SECRET
openssl rand -hex 32   # -> SESSION_SECRET
openssl rand -hex 32   # -> SECRET_ENCRYPTION_KEY

# 把上面三个值和你的模型 Key 写进 .env.selfhost
# 同时设置管理员邮箱（首次启动前设置，仅对邮箱验证码登录生效）
B4M_BOOTSTRAP_ADMIN_EMAIL=you@example.com

# 拉起整套栈（app + MongoDB + MinIO 对象存储 + ElasticMQ 队列 + Mailpit 邮件捕获）
docker compose -f compose.selfhost.yaml --env-file .env.selfhost up -d

起来之后访问 http://localhost:3000，登录验证码会进到内置的 Mailpit http://localhost:8025。镜像发布在 ghcr.io/bike4mind/bike4mind-selfhost（amd64 + arm64 多架构，由 CI 从 main 构建），不需要 Node / pnpm / 本地构建。

路径 C：只要 CLI

npm install -g @bike4mind/cli      # 或 npx @bike4mind/cli
b4m                               # 首次运行会引导你认证

路径 D：从源码开发

pnpm i -r                # 安装
pnpm turbo:core:build    # 构建 @bike4mind/* 核心包
pnpm turbo:typecheck     # 类型检查
pnpm turbo:test          # 跑测试

四、核心用法

CLI 交互与一次性执行

b4m                                  # 交互式会话
b4m "summarize the git log"          # 播种并提交首轮，随后保持交互界面

b4m -p "What is 2+2?" --output-format json     # 无头单次查询，输出 JSON
b4m -p "..." --output-format stream-json        # NDJSON，输出思维链/动作/观察

指向不同后端（含自托管实例）

b4m --dev            # 本地开发服务器 http://localhost:3001
b4m --prod           # 官方生产环境
b4m --api-url http://localhost:3000   # 任意实例（自托管 / AWS / 本地），会清掉绑定旧源的认证缓存
b4m --reset-api      # 恢复默认 API URL 并清除认证

环境选择持久化在 ~/.bike4mind/config.json，认证 token 按环境分别缓存，来回切换不需要重复登录。

MCP（模型上下文协议）

b4m mcp list                          # 列出已配置的 MCP server
b4m mcp add <name> -- <command...>    # 添加
b4m mcp enable <name>                 # 启用/禁用
b4m mcp serve [--http] [--port <n>]   # 把 Bike4Mind 自己暴露成一个 MCP server

本地模型（Ollama + Hugging Face GGUF）

b4m models ls --ollama-host http://127.0.0.1:11434
b4m models search qwen2.5 0.5b
b4m models pull Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M
b4m models use hf.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M
b4m models rm qwen2.5:0.5b

search 默认隐藏 abliterated / uncensored 构建并打印隐藏数量；pull 会先打印体积和许可证再询问，非 Apache-2.0 / MIT / BSD 类宽松许可证需显式 --accept-license。

技能与诊断

b4m skills push ~/.claude/skills/my-skill   # 把本地技能推成 Bike4Mind 技能
b4m skills push <path> --update              # 脚本/CI 里非交互更新
b4m doctor                                  # 诊断 Node、registry、ripgrep、原生模块
b4m update                                  # 检查并安装 CLI 更新

作为 claude 引擎嵌入宿主应用

CLI 支持一批 Claude Code 兼容的宿主侧参数：--mcp-config、--strict-mcp-config、--append-system-prompt、--allowedTools、--settings、--session-id、--resume。

五、典型适用场景

  1. 个人知识中枢 — 把读书笔记、项目文档、论文扔进 Knowledge Engine，用 RAG 让 Agent 基于你的私有材料回答，而不是通用模型的泛泛而谈。
  2. 多模型 A/B 与成本权衡 — 同一任务在 Claude / GPT / Gemini / xAI / 本地 Ollama 之间切换，按任务挑模型、按成本挑档位。
  3. 数据不出内网 — 自托管 + 本地 Ollama(vLLM)，敏感文档不出机器。这是它对比 SaaS 方案的核心卖点。
  4. 多步任务自动化 — Quest Master 做"生成图 → 视觉复核 → 搜索 → 出报告"这类带人工确认环节的长链路。
  5. CLI 化 agent 接入 CI — b4m -p ... --output-format json 无头调用，把 agent 塞进脚本和流水线。
  6. 给自家产品做 AI 能力底座 — 官方提供 "Building an app on Bike4Mind" 文档，做带用户登录和 AI 用量计费的 AI 应用。

六、坑与注意

  1. SECRET_ENCRYPTION_KEY 千万别随手换 — 它加密库里存的其他密钥（管理员设置、用户 API Key、OAuth token、社交连接），自托管下轮换不自动化。要轮换必须把旧值设进 SECRET_ENCRYPTION_KEY_PREVIOUS 并永久保留，否则旧密文不可恢复。
  2. APP_URL 设错会伪装成权限 bug — 它是 CSRF 来源白名单且 fail-closed。任何改状态请求（保存设置、生成 API Key、上传）都会 403，未设置时报 CSRF: APP_URL is not configured on this deployment.，设成你不访问的源则报 Invalid request origin...。读取请求两种情况都正常，所以很容易误判成权限问题而非配置问题。用非 localhost 部署（反代 / 局域网 / tailnet）必须设成浏览器实际访问的源。
  3. 升级必须把 ws 网关和 app 一起重建 — 浏览器与网关共享连接契约（浏览器把 realtime 凭据放在 ?ticket= 查询参数里由网关转发），版本错配会静默让所有浏览器的实时连接被拒（socket 直接被拒，没有任何报错）。只 pull 升级会留下旧版 ws 容器。正确做法：git pull 后用 --build 起来，或显式 docker compose -f compose.selfhost.yaml build ws。
  4. .env.selfhost 不能在值后面加行内注释 — compose 按字面读取这些值，KEY=value # comment 会把注释一起当成值。
  5. 管理员引导只对邮箱验证码登录生效 — 用 GitHub OAuth 首次登录拿不到 bootstrap 管理员身份；B4M_BOOTSTRAP_ADMIN_EMAIL 必须在首次启动前设好，否则第一个用邮箱码注册的账号成为管理员。
  6. 首次构建 MinIO 需要外网且耗时数分钟 — 要能访问 GitHub 源码、Go modules、Docker Hub 基础镜像和 Debian 包；上游 MinIO 与 mc 已归档，这是最后一版 pin，不再有上游更新。从源码构建 Next.js 单体仓需要给 Docker 12–16 GB 内存。热重建（约 1–2 分钟）vs 冷启动（数分钟）差别很大。
  7. CLI 依赖原生模块 — better-sqlite3（图像缓存）和 sharp（图像处理）需要编译，需要 Python 3 + C++ 编译器。报 "Could not locate the bindings file" 时跑 pnpm rebuild better-sqlite3 或 pnpm rebuild。
  8. 许可证不是 MIT/Apache，是 BSL 1.1 — 可以读、改、再分发、生产使用、给组织内部自托管、在其上构建商业产品；但不能把软件作为与它竞争的托管/管理服务对外提供。好消息是每个发布版本在公开满两年后自动转为 Apache-2.0，许可证不会收紧。
  9. b4m models use 选定的模型不可用时直接失败 — 已保存 host 时 b4m -p 不会静默切换到别的模型，Ollama 不应答也会失败。这是刻意的行为，但容易让人以为 CLI 坏了。
  10. 仓库卡片字段的版本漂移风险 — 本篇核对的是 2026-10-27 的 main 分支状态（仓库 pushed_at 为 2026-10-27T07:33Z）。README 未标注 CLI 版本号，CLI 版本请用 b4m --version 现场确认；镜像 tag 跟随 CI 从 main 构建，同样会漂移，生产部署务必固定到具体 digest 而非 latest。

七、与同类对比

项目 定位 与 Bike4Mind 的关键差异
Open WebUI 开源自托管 LLM 聊天 UI 侧重对话与模型管理；Notebook 式工作区、Agent 编排、Quest Master 这类多步规划不是核心
AnythingLLM 开源 RAG 桌面/服务器应用 RAG 是主轴，工作区与 Agent 编排更轻；无内置发布分享层
Dify / Flowise 可视化 LLM 应用编排平台 偏开发者搭建应用（工作流画布），Bike4Mind 偏个人日常知识工作台 + 开箱即用的 Agent
Claude Code / Codex CLI 终端编码 agent Bike4Mind 的 b4m CLI 定位类似且部分兼容 Claude Code 宿主参数，但多了 Notebook、知识库、多模型与图像生成；且 BSL 1.1 而非 Apache-2.0
私有 LLM 网关（如 LiteLLM / vLLM） 基础设施层模型代理 只做模型路由/推理，Bike4Mind 是上层完整工作台；不过它自己也能接 Ollama/vLLM
Notion AI / NotebookLM 商业化知识协作 闭源 SaaS，数据在厂商侧；Bike4Mind 强项恰是可自托管、数据本地

八、一句话推荐结论

推荐给：想自托管、有多模型与私有文档 RAG 需求、且愿意接受早期项目（94 Stars、303 个 open issue）折腾的个人开发者与小团队——特别是本地 Ollama + Docker Compose 这条路径，门槛确实不高。

不推荐给：需要生产级稳定性与明确 SLA 的企业场景；以及依赖纯宽松许可证的商用产品（BSL 1.1 有"不得提供竞品托管服务"的限制，两年后才转 Apache-2.0）。

⚠️ 诚实标注：本篇未做本地构建验证（只读公开内容，未 clone、未跑命令），安装命令与配置项均逐字取自 README 与 SELF_HOST.md / packages/cli/README.md。仓库未在 README 中给出 CLI 的版本号或 release tag，镜像 tag 随 CI 从 main 漂移，两项均已在坑 10 标注需现场核实。第三方"自托管 AI 工作台"赛道竞品众多，此处对比基于各自公开定位，未做实测对比。