iblai/os · 上手攻略

  • 仓库：iblai/os
  • 链接：https://github.com/iblai/os
  • 分类：agent
  • 作者：Tom
  • 更新：2026-10-22

§0 三证 checklist 与自检

项目 状态 证据
GitHub URL（已 fetch） ✅ 已抓取 README（raw main）、docs/development.md、package.json、release API、commit API
版本 / commit 锚点 ✅ package.json version 0.175.0；最新 release tag v0.175.0；main 最新 commit 7a487fb49108cf5fed67deebbb14e75c1d6aeda3（2026-10-21T17:37:16Z，github-actions[bot]）
README 子模块 anchor ✅ docs/development.md、docs/standalone-deployment.md、docs/platform-deployment.md、docs/DOWNLOADS.md、e2e/COVERAGE.md、AGENTS.md
顶会 / 论文 venue ⚠️ 该仓库为商业产品开源前端，没有论文或会议背书；README 中的 SOC 2 Type II 属厂商自述，未在本仓库内找到审计报告原文
作者归属 ⚠️ 仓库归属 ibl.ai 公司组织；README 中出现 CTO Miguel Amigot 的演示视频署名，但本仓库未提供 AUTHORS/CONTRIBUTORS 名单

诚实声明：本篇不含"论文级"证据，只有仓库内可核对的代码与配置事实。凡涉及商业后端行为（认证、计费、模型调用）均无法从本仓库验证，已在文中逐条标 ⚠️。

§1 这是什么

iblai/os 是 ibl.ai 平台的开源前端仓库，用 Next.js（App Router）+ React 19 + Redux Toolkit + Radix UI + Tailwind CSS 写成，一套代码同时输出 Web、macOS、Windows、Linux、iOS、Android 六个端：

  • Web：线上已部署于 os.ibl.ai
  • Chrome 侧边栏扩展（Chrome Web Store 上架）
  • macOS / Windows：Tauri 打包的原生壳（webview wrapper），universal .dmg 与 x64 安装包
  • iOS / Android：App Store 与 Google Play 上架
  • Linux：需从源码构建

它承载的功能面很宽：AI Agent 配置（可配 LLM、系统提示词、工具、安全过滤）、Projects 协作工作区、Canvas/Artifacts 富文档、MCP Server 接入、RAG 训练（上传文档 / 挂 Google Drive、OneDrive、Dropbox / 爬站点）、Web Search、Deep Research、LiveKit 实时语音通话与屏幕共享、分析看板（用量、主题、转录、财务报告）、多租户 + SSO（OAuth/OIDC/SAML）+ RBAC、Stripe 计费、iframe 嵌入与自定义域名、白标。

§2 解决什么问题

核心命题是"你的代码、你的数据、任意 LLM"。作者的意思是：多数 AI 应用要么锁死一家模型供应商，要么把整套后端闭源托管在厂商侧，机构无法把 agent 部署在自己机房、用自己的模型和数据。iblai/os 把界面层完全开源（MIT），让企业可以自托管前端、接自己的模型与租户 key，把品牌、权限、计费层握在自己手里。

第二个命题是"一套代码，处处可用"。原生端其实是 webview 壳，所以桌面/移动端的交付成本远低于原生重写。

第三个命题是"企业能力后置"：多租户隔离、SSO、RBAC、Stripe、白标是内置项而不是事后补丁。

§3 快速安装

前置（README 与 docs/development.md 一致）：

  • Node.js 25.3.0+（package.json engines.node 明确写 25.3.0，README 建议用 nvm）
  • pnpm 10+（packageManager 字段锁定 pnpm@10.11.1）
  • 一个 ibl.ai 平台的组织 key（NEXT_PUBLIC_MAIN_TENANT_KEY）

开发态：

git clone https://github.com/iblai/os.git
cd os
pnpm install

cp .env.example .env.local   # 填 tenant key 与平台 URL
pnpm dev                     # http://localhost:3000

.env.local 关键项（取自 docs/development.md 原样）：

NEXT_PUBLIC_AUTH_URL=https://login.iblai.app
NEXT_PUBLIC_API_BASE_URL=https://api.iblai.app
NEXT_PUBLIC_MAIN_TENANT_KEY=main
NEXT_PUBLIC_BASE_WS_URL=wss://asgi.data.iblai.app
NEXT_PUBLIC_IBL_LIVE_KIT_SERVER_URL=wss://livekit.call.iblai.app

用 Claude Code 的用户可以在仓库根目录跑 /setup，它会引导你连接 ibl.ai 租户并自动写好 .env.local。

生产部署（二选一）：

# A. Docker（README 推荐）
docker build -t os .
docker run -p 5000:5000 --env-file .env.local os

# B. standalone
pnpm build
PORT=3000 node server-wrapper.js

pnpm build = next build && ./scripts/post-build.sh，产物在 .next/standalone/server.js（next.config.ts 里把 outputFileTracingRoot 钉到项目目录，避免路径嵌套）。

原生端构建（可选环境变量在编译期通过 Rust option_env! 烘焙进二进制）：

IBL_TENANT=acme IBL_ALLOW_IN_APP_PURCHASE=true pnpm exec tauri build

§4 核心用法

4.1 命令与脚本清单

命令 作用
pnpm dev 开发服务器（3000 端口，自带 --no-experimental-webstorage）
pnpm build 生产构建（standalone 输出）
pnpm start 通过 server-wrapper.js 起生产服务
pnpm lint / lint:check ESLint（带 --fix）+ typecheck
pnpm typecheck tsc --noEmit，并额外校验 extensions/chrome/tsconfig.json
pnpm test Vitest 单元测试
pnpm test:e2e Playwright E2E（自动播种空 auth fixture）
pnpm tauri:dev / tauri:build 桌面端开发与打包
pnpm ext:build / ext:watch Chrome 扩展（Vite）构建
make e2e-install 首次安装 Playwright 浏览器
make e2e-ui / e2e / e2e-headed / e2e-chrome E2E 交互式 / 无头 / 有头 / 仅 Chrome
make e2e-journey J=01 跑单个 journey spec
make e2e-report 打开最近一次 HTML 报告

4.2 代码结构（据 docs/development.md 架构图）

  • app/platform/[tenantKey]/：多租户主路由，agent 页面嵌在其下
  • app/create-mentor/：agent 创建向导
  • components/：ui/（54 个 shadcn/ui 原语）、chat/、advanced-chat/、canvas/、mentors/、modals/edit-mentor-modal/、workflows/、model-download/（Tauri 本地 LLM 下载 UI）
  • features/：13 个状态模块（analytics / auth / chat / chat-input / mentors / messages / navigation / provider-association / rbac / subscription / tenants / top-banner / users）
  • hooks/：151 个自定义 React hook，含 use-voice-chat.ts（LiveKit 集成）
  • e2e/：Playwright journey 测试，e2e/COVERAGE.md 记录覆盖率

4.3 扩展点

  • 加 MCP 工具：走平台侧 MCP Server 配置，前端不直接持有 MCP 进程。
  • 换模型供应方：在 agent 编辑弹层里配 LLM，README 称支持 OpenAI / Anthropic / Google / Microsoft / Meta 及自有模型，切换无需改代码。
  • 白标：per-org branding + logo + disclaimer。
  • 嵌入门户：iframe embed mode + 自定义域名 + API key。

§5 典型适用场景

  1. 高校/政府/企业自建 AI 助教或导师平台：README 明确点名 universities、enterprises、government，且强调部署在自己基础设施、用自己的模型。app/ 里的 learn.iblai.app 相关 legacy LMS URL 与 create-mentor/ 向导都是为这类场景准备的。
  2. 需要多端一致的 C 端 AI 产品：一套 web 代码 + Tauri 壳 + 上架包，同时覆盖桌面与移动。
  3. 要 SSO / RBAC / 审计的内部工具：SSO 入口、回调、移动端 SSO 路由（app/sso-login/、app/mobile-sso-login/）都已在仓库里。
  4. 想做白标 SaaS：多租户 + 自定义品牌 + iframe 嵌入 + Stripe 计费。

§6 与同类对比

维度 iblai/os Dify Open WebUI Chatbot UI
开源范围 前端全开源（MIT），后端闭源需企业授权 应用层开源（含工作流编排） 自托管聊天前端 + 部分后端 纯前端壳
复杂度 Next.js 前端工程，编排能力依赖平台 重（Python + Postgres + Redis + 向量库） 中（Python 后端） 轻
端覆盖 六端 + Chrome 扩展 Web为主 Web为主 Web为主
企业能力 SSO/RBAC/多租户/Stripe/白标内置 需自行组合 有用户/权限 无

关键差异：iblai/os 开源的是"壳 + 企业能力"，智能体编排、RAG 检索、模型网关这些后端逻辑不在本仓库（README 明说需要 ibl.ai backend 或企业许可拿全量后端代码）。Dify/Open WebUI 属于"应用逻辑也开源"，这是选型时最容易误判的一点。

§7 坑与注意（工程节）

  1. 坑：以为 clone 完就能跑起来。现象：.env.local 缺 NEXT_PUBLIC_MAIN_TENANT_KEY 或平台 URL 时页面卡在加载 spinner，不跳登录页。影响：本地无法开发。修复：按 docs/development.md 逐项填 NEXT_PUBLIC_AUTH_URL / NEXT_PUBLIC_API_BASE_URL / NEXT_PUBLIC_BASE_WS_URL / NEXT_PUBLIC_IBL_LIVE_KIT_SERVER_URL，再 pnpm dev。⚠️ 后端账号本身需到 ibl.ai 申请，本仓库不含。
  2. 坑：Node 版本不对。现象：SDK 的 browser storage 守卫与 Node 内置 webstorage 冲突。影响：pnpm dev 报 webstorage 相关错。修复：用 Node 25.3.0+；若自定义了 scripts，保留 NODE_OPTIONS='--no-experimental-webstorage'。
  3. 坑：pnpm 版本漂移。现象：packageManager 锁定 pnpm@10.11.1，用 npm/yarn 安装会得到不同依赖树。影响：构建产物不一致。修复：npm install -g pnpm 并让 corepack 启用。
  4. 坑：端口被僵尸进程占住导致白屏。现象：/_next/static/... 与 /env.js 全部 404/503，页面空白。影响：误判为构建失败。修复：lsof -nP -iTCP:3000 -sTCP:LISTEN 找到占用进程（旧的 node/next 进程会 shadow 新进程，绑到 127.0.0.1 的会赢过通配绑定）并 kill 掉，再重启。
  5. 坑：上级目录有 stray lockfile 导致 standalone 路径嵌套。现象：~/package-lock.json 让 Next.js 把 home 目录当成 workspace root，产物变成 .next/standalone//server.js，post-build.sh 把静态资源拷错位置。影响：同样表现为白屏。修复：删掉上层多余 lockfile 后重建；仓库已在 next.config.ts 里固定 outputFileTracingRoot 兜底。
  6. 坑：Tauri 构建期环境变量不生效。现象：IBL_TENANT / IBL_ALLOW_IN_APP_PURCHASE 设置了却仍多租户。影响：锁租户版应用发错。修复：这两个变量由 Rust option_env! 在编译期烘焙，必须在执行 pnpm exec tauri build 的那个 shell 里导出；src-tauri/build.rs 已声明 cargo:rerun-if-env-changed 触发重编，CI 里要设在 build step 上。
  7. 坑：以为开源就能跑完整平台。现象：以为 clone 后自带 agent 运行时与模型代理。影响：部署出来是空壳，登录/对话全失败。修复：接受"前端 MIT + 后端需 ibl.ai 或企业许可（https://ibl.ai/contact）"的现实，或只用 iblai/iblai-infra-cli 部署已有 Docker 镜像。
  8. 坑：E2E 覆盖回退。现象：改了用户可见行为但没加 journey spec。影响：CI 漏测。修复：README 与 e2e/COVERAGE.md 要求覆盖率不得回退，新增/更新 journey；首次需 make e2e-install。
  9. 坑（次要）：README 下载链接与最新 release 不同步。现象：README 里硬编码的是 app-v0.95.28 的 dmg/exe，而 GitHub 最新 release 已是 v0.175.0。影响：按 README 下载会拿到明显更旧的版本。修复：以 release 页面/docs/DOWNLOADS.md 为准 —— 本条是本篇最硬的"版本号漂移"提醒。
  10. 坑（次要）：后端能力无源码可查。现象：README 列出的 Deep Research、Analytics、Stripe 逻辑全在闭源后端。影响：无法审计数据流与计费细节。修复：⚠️ 记为已知局限，做安全评估时要求厂商提供后端说明或企业授权源码。

§8 一句话推荐结论

推荐，但要清醒：如果你要的是"一套 MIT 前端 + 六端交付 + 企业级 SSO/多租户/白标外壳"，iblai/os 是目前少见的一体化样本，值得直接 fork 做二次开发；但如果你要的是能自托管运行的完整 agent 平台（编排、RAG、模型网关全开源），它不合适——那类需求应看 Dify 或 Open WebUI。上手门槛不高（Node 25 + pnpm + 一个租户 key），真正的前置条件是拿到 ibl.ai 账号和后端授权。