面向独立研究者的全栈 AI 辅助研究平台
将完整的科研工作流封装为可热插拔的智能模块，一个人也能拥有一支研究团队
平台概览 · 模块路线图 · 系统架构 · IdeaSpark · Benchmark · CodeLab · WriterAI · 快速开始 · 开发新模块
统一工作台：模块切换 · 对话流 · Agent 活动时间线 · 研究结果沉淀
SoloLab（一人实验室）是一个模块化的 AI 研究平台，将独立研究者的完整工作流，从灵感涌现到论文写作，封装为可热插拔的功能模块，通过统一架构编排。
平台总览：前端模块层 · 核心服务层 · 数据与记忆层
|
模块热插拔 每个模块独立运行 零耦合、即插即用 |
模型无关 OpenAI 兼容网关 支持 100+ 模型 |
透明可控 每步 Prompt 可见 Token 费用追踪 |
一键部署 Docker Compose 单人可运维 |
断点恢复 长任务可恢复 不丢失状态 |
SoloLab 的核心价值在于统一架构承载多个研究阶段的智能模块。每个模块独立开发、独立部署、即插即用：
| 模块 | 功能 | 状态 |
|---|---|---|
| 💡 IdeaSpark | 多智能体创意涌现 · Separate-Together · Elo 锦标赛 |  |
| 🔧 CodeLab | AI 编码助手 · 多代理并行探索 · 工具调用链 · 文件读写与终端 | |
| ✍️ WriterAI | 学术论文 Agent · 8 工具自主编排 · 流式预览 · 6 模板 · 像素级 PDF 导出 | |
| 📊 DataLens | 数据分析 · 可视化生成 · 统计检验 |  |
| 📚 LitReview | 系统性文献综述 · 引用图谱 · 研究趋势 | |
| 🔍 Reviewer | 模拟审稿人 · 批判性审查 · 改进建议 | |
前端工作台 · FastAPI 核心服务 · PostgreSQL / Redis / 文件存储
|
🧠 LLM Gateway OpenAI 兼容格式，支持 100+ 模型 内置降级链与模型 Fallback 实时费用追踪与预算控制 📦 Module Registry 基于 manifest.json 的热插拔ModuleBase 抽象类 + 标准生命周期动态加载/卸载，零停机 🔧 Tool Registry 统一 ToolBase 接口封装arXiv / Semantic Scholar / Tavily / PDF 自动限速与结果缓存 |
💾 Memory Manager pgvector 向量检索 + 4 级作用域 Module → Session → Project → Global 跨模块知识传递 ⏱️ Task State Manager Redis Stream 持久化每个 SSE 事件 递增 event_id 支持断线恢复24h 任务状态保留 📄 Document Pipeline PyMuPDF 学术 PDF 高精度解析 语义分块（500~1500 tokens） 自动元数据提取与向量存储 |
支持上传学术 PDF，通过 PyMuPDF 引擎高精度解析双栏排版、LaTeX 公式和表格，自动语义分块后存入向量数据库，供智能体深度检索：
上传学术 PDF → PyMuPDF 高精度解析 → 语义分块 → 向量化存储 → 供智能体检索
所有对话和运行结果持久化存储，支持会话切换、历史回溯和跨模块上下文传递：
会话持久化 · 历史回溯 · 跨模块上下文传递
多智能体创意涌现系统：5 个差异化智能体 × Separate-Together 协作 × 实时文献检索 × Elo 锦标赛排序
|
5 个角色智能体 差异化分工，独立发散后再协同收敛 |
28 次工具调用 / run 实时搜索与文献验证，保证创意可追溯 |
56 次受控实验 逐组件量化多智能体系统的真实收益 |
$0.028 / run 帕累托最优配置成本 |
|
科研工作中，idea 的产生 是最具挑战性的环节。 传统头脑风暴依赖多人协作，但独立研究者缺乏多样化的认知碰撞环境。大语言模型（LLM）虽然强大，但单一模型的输出容易陷入 单一视角 和 知识截止日期 的限制。 "我一个人做科研，最缺的不是写代码的能力，而是一个能跟我争论、质疑、补充的'虚拟同事'。" |
|
IdeaSpark 将一个研究主题转化为经过 多轮辩论、文献检索验证和锦标赛排序 的高质量研究创意。
|
发散者 Divergent Thinker temp: 1.0跨领域类比 大胆联想 🔧 web_search 🔧 arxiv_search |
领域专家 Domain Expert temp: 0.5深度专业知识 方法论审查 🔧 arxiv_search 🔧 scholar_search 🔧 doc_parse |
审辩者 Critic temp: 0.3挑战假设 寻找漏洞 🔧 arxiv_search |
连接者 Connector temp: 0.7发现关联 组合融合 — |
评估者 Evaluator temp: 0.3锦标赛投票 Elo 排序 — |
从并行发散到分组碰撞，再到全局整合与 Elo 排序
输入一个研究主题后，5 个智能体开始并行工作，实时展示每个 Agent 的思考过程、工具调用和创意产出：
智能体并行工作中：左侧对话流 · 右侧 Agent 活动时间线 · 实时工具调用
经过多轮协作和 Elo 锦标赛排序后，系统输出 Top-5 创意卡片，每张包含完整的方案描述、文献引用和可行性分析：
Top-5 创意看板：Elo 评分排序 · Agent 来源标注 · 完整文献引用
运行完成后，可一键生成结构化的 Markdown 研究报告，包含所有创意的详细描述和方法论分析：
一键生成 Markdown 研究报告：方法论描述 · 参考文献 · 可直接导出
系统运行时，智能体自主调用外部 API 获取前沿信息，确保每个创意都有据可查：
|
预印本论文搜索 获取最新学术成果 ~19 次/run |
引用图谱 + 论文元数据 验证研究脉络 ~4 次/run |
实时网络搜索 行业趋势与应用 ~5 次/run |
学术 PDF 全文解析 提取实验细节 按需调用 |
每次运行平均 28 次工具调用，确保 100% 的创意具有真实文献支撑（Grounding Rate = 100%）。
💡 "多智能体比单 LLM 好"是被广泛接受的直觉，但真的如此吗？我们用 56 次受控实验来回答。
我们设计了 7 种消融条件 × 4 个跨学科主题 × 2 次重复 = 56 次受控运行，配合 LLM-as-Judge 五维度评审（560 次评分），逐组件拆解了系统中每个部分的真实贡献。
| 条件 | Overall | Grounding | Cost | Latency |
|---|---|---|---|---|
| 🏆 Full System | 8.53 ± 0.07 | ✅ 100% | $0.080 | 493s |
| 1️⃣ SingleRound ⬅ 帕累托最优 | 8.45 ± 0.11 | ✅ 100% | $0.028 | 110s |
| 🚫🔍 NoTools | 6.21 ± 3.83 | ❌ 0% | $0.032 | 597s |
| 💬 Baseline (单 LLM) | 5.53 ± 0.43 | ❌ 0% | $0.005 | 18s |
📊 组件贡献归因🤖 多智能体框架 ████████████████████████████ +54% 🔍 工具调用(搜索) ██████████████████ +37% 🏅 Elo 锦标赛 █ +1.4% 🔄 多轮迭代 █ +0.9% 👨⚖️ Critic 审辩 ▏ +0.1%
90% 以上的质量提升来自"多智能体框架 + 工具调用"。 SingleRound 配置用 1/4 时间、1/3 成本达到 99% 质量，是当前最优的效率-质量平衡点。
📖 查看完整消融实验报告 →
含实验设计、逐层分析、三种假说与复现指南
一句话描述：把 AI Coding Agent 搬进浏览器 — 多代理并行探索 × 20+ 工具自主编排 × 内联 Diff 预览 × 跨会话记忆
|
3 类专用代理 Build / Explore / Plan 意图路由，各司其职 |
20+ 内置工具 Read / Edit / Grep / Bash / Web Agent 自主编排调用 |
并行子代理 Task 工具 spawn 多个 explore 独立上下文同时深入 |
3 变量直连 100+ LLM MODEL / KEY / URL 改 .env 即切换 Provider |
|
独立研究者写代码时，最缺的不是 IDE 插件，而是一个能理解整个项目、自主调查并动手修改的助手。 市面上的 AI 编码工具要么只能补全当前行（Copilot），要么需要独立客户端（Cursor/Claude Code）。 CodeLab 基于优秀的开源项目 OpenCode（MIT License）构建。在 OpenCode 强大的 Agent 引擎之上，SoloLab 进行了深度改造与扩展，将其集成为一站式 Web 编码模块：打开浏览器就是完整的 Coding Agent。 "给它一句话，它会派出 3 个探索代理并行调查代码，汇聚结果后自己写代码、跑测试、给你看 diff。" |
|
|
Build Agent 编码执行者 读取代码 → 分析 → 编辑文件 运行命令 → 验证结果 写测试 → 提交变更 🔧 Read / Edit / Write / Bash 🔧 Glob / Grep / Web |
Explore Agent 代码探索者 只读模式，极速搜索 映射架构 · 追踪依赖 2-3 个并行同时工作 🔧 Read / Glob / Grep 🔧 Bash (只读) |
Plan Agent 方案规划者 分析需求 → 设计方案 识别关键文件 · 权衡取舍 输出实施计划后移交 Build 🔧 Read / Glob / Grep 📄 结构化计划输出 |
输入任务后，Agent 自动规划执行策略，复杂任务会 spawn 多个子代理并行探索：
3 个 explore 子代理并行调查 · 独立上下文 · 结果自动汇聚
Agent 完成分析后，自主读取文件、编辑代码、运行验证命令。所有工具调用实时可见，Edit 操作自动展开 Diff 预览：
工具调用实时展示 · Edit 自动展开 Diff · Bash 命令输出内联
完成后，右侧面板显示所有修改的文件，会话自动保存到历史记录：
会话自动持久化 · 修改文件追踪 · Session 历史即时同步
Agent 运行时自主编排调用，无需人工指定：
|
Read · Edit · Write · MultiEdit Glob · Grep · Ls 内联 Diff 自动展开 |
Bash · ApplyPatch 支持任意 shell 命令 输出内联渲染 |
WebFetch · WebSearch 获取文档与 API 参考 实时网络访问 |
Task · TodoWrite · Plan Memory · Question 跨会话知识积累 |
输入 / 即弹出 Skill 浮窗，选择后自动加载专业化指令到 Agent 上下文。CodeLab 内置了完整的 SuperClaude Skill 包（30 个），开箱即用：
输入 / 弹出 Skill 列表 · 上下键选择 · Enter 确认 · 自动注入指令到 Agent
🔍 分析与探索/analyze 代码质量分析/explain 代码解释/research 深度调研/troubleshoot 问题诊断
|
🏗️ 构建与实现/implement 功能实现/build 编译打包/test 测试执行/workflow 工作流生成
|
📝 文档与规划/document 文档生成/design 架构设计/estimate 工期估算/brainstorm 需求探索
|
🔧 维护与优化/improve 代码改进/cleanup 死代码清理/git Git 操作/pm 项目管理
|
自定义 Skill：在
opencode/skills/你的skill名/SKILL.md放一个 Markdown 文件即可。重启 OpenCode 后自动发现，无需写代码。
Frontend ←→ Backend (Session 代理) ←→ OpenCode Engine ←→ 100+ LLM via Vercel AI SDK
极简 Provider 接入：
.env设置CODELAB_MODEL/CODELAB_API_KEY/CODELAB_BASE_URL三个变量即可切换任意 LLM。无注册表、无 models.dev 网络依赖、无配置文件。Anthropic / OpenAI / Google 原生 SDK 自动检测，其他 Provider 走 OpenAI Compatible。
CodeLab 的核心引擎基于 OpenCode（MIT License）构建。OpenCode 提供了卓越的 Agent 框架、工具系统、会话管理和 MCP 协议支持，是 CodeLab 得以实现的基石。
SoloLab 在 OpenCode 基础上的改造与扩展：
| 维度 | OpenCode 原有能力 | SoloLab CodeLab 扩展 |
|---|---|---|
| 🏗️ 部署形态 | 独立 CLI / TUI 终端应用 | Web 一站式平台模块，浏览器直接使用 |
| 🤖 多代理 | 单 Agent + 子任务 | 意图路由 + 并行子代理，自动 spawn 2-3 个 explore 同时调查 |
| 📝 提示词 | 英文提示词系统 | 基于 Claude Code 深度优化的中文提示词，Task 工具触发引导增强 |
| ⚙️ 模型配置 | 40+ Provider 聚合 + models.dev 网络依赖 | 3 个 .env 变量直连，移除 1200 行聚合层，零网络依赖 |
| 💾 会话管理 | 独立 SQLite 会话 | Frontend→Backend→OpenCode 单向代理，PG+SQLite 统一，级联删除 |
| 🎨 前端 | 终端 TUI (Solid.js) | Next.js Web UI，Warm Stone 设计体系，工具调用光效，Diff 自动展开 |
| 🗜️ 上下文 | 基础 Compaction | 三级 Compaction（L1 裁剪 / L2 启发式 / L3 LLM 摘要）+ 自适应 Prompt Cache |
感谢 OpenCode 团队的开源贡献。CodeLab 的所有改造代码遵循 Apache 2.0 许可证发布。
一句话描述：让研究者像跟合作者对话那样写论文 — 8 工具自主编排 × 流式预览 × 6 种期刊模板 × 像素级 PDF 导出
|
8 个专业工具 搜索 / 大纲 / 流式写作 / 引用 沙箱代码 / 图表 / 知识库 / 状态 |
4 层提示词架构 静态 Prompt + 状态锚 工具返回增强 + Agent Hooks |
6 种期刊模板 Nature / CVPR / ICCV / IEEE ACM / 中文期刊 · YAML 热插拔 |
PDF 像素一致 Playwright + KaTeX 数学公式 · 图表内联 · 中文字体 |
|
独立研究者写论文时，最耗时的不是思路，而是 反复的文献检索、格式调整、引用管理、图表绘制。传统 AI 写作助手停留在"帮我润色这段话"的层次，无法理解论文整体结构与投稿规范。 WriterAI 把完整学术写作流交给一个 会用工具的 Agent：自主去 arXiv/Scholar 搜索 → 按期刊模板生成大纲 → 流式写作每个章节 → 在沙箱中跑 matplotlib 出图 → 插入引用与图表 → 一键导出与预览像素一致的 PDF。 "给它一句话描述，它会先搜文献、列大纲征求同意、流式写出章节、遇到数据画图、遇到公式调 KaTeX、最后输出投稿即用的 PDF。" |
|
|
arXiv + Scholar + Tavily 实时检索并验证文献 |
基于 YAML 模板生成 章节结构 · 类型 · 顺序 |
SSE 流式写作单个章节 内联 [FIGURE:] 占位符 |
add / remove 自动编号 去重 · 跟随模板格式 |
|
Docker 沙箱 · 无网络 matplotlib / plotly / pandas |
替换正文 [FIGURE:] 占位符 图表流入段落间 |
按 doc_id 隔离的附件检索 仅作内部上下文 |
读取当前文档状态 做上下文决策 |
描述一个写作任务后，Agent 自动搜索文献 → 生成大纲 → 逐章节流式写作，右侧预览实时呈现每一段新生成的文字：
左 Chat · 中 文档预览实时流式生成 · 工具气泡追踪 Agent 每一步决策
输入框左下角的 + 菜单 可上传参考 PDF/MD/DOCX，附件严格按文档隔离（project_id = "writer:{doc_id}" 命名空间），不会污染其他会话的检索结果：
拖拽或点选上传 · 自动分块 + 向量化 · 状态轮询 · 删除 · 按 doc_id 严格隔离
一键导出为 PDF，数学公式通过 KaTeX 渲染，图表内联嵌入，中文字体自动识别，预览与 PDF 像素一致：
Playwright 驱动的 headless Chromium · KaTeX 数学 · 图表 Base64 内联 · 6 模板自动切换
AI 写作里最恼人的 bug 是 Agent "抽风重写" — 用户中文写到一半，Agent 突然切英文重写全文。WriterAI 没用硬状态机，而是用 soft enforcement：状态通过提示词注入最近 attention 窗口，让 Agent 自主修正。
| 层 | 职责 | 示例 |
|---|---|---|
| L1 · 静态 Prompt | 模板、角色、工具约定 | "你是 Nature 期刊写作助手，遵循算法化 Figure 协议..." |
| L2 · 状态锚 | 注入到 user message 最前面，最近 attention 窗口 | 🔒 LANGUAGE LOCK: 中文 ／ 📌 PENDING FIGURES: [fig1, fig2] |
| L3 · 工具返回增强 | write_section / insert_figure 返回后追加提示 | "你刚写的章节检测到语言为中文，后续请保持一致" |
| L4 · Agent Hooks | Python 层在工具调用后做状态提取 | 自动写入 metadata_json.language_lock 持久化 |
设计理念：软阻断 > 硬阻断。 状态通过提示词流入最近注意力窗口，让 Agent 自主修正；无需维护状态机、无需硬拒绝、无需重启对话。中英切换、图表占位符漏插等问题在 v6.4 后零复现。
Frontend ←→ FastAPI ←→ WriterAgent ←→ 8 Tools · Docker Sandbox · Playwright PDF Engine
📦 单表 JSONB 数据模型writer_documents 表 + JSONB 存 sections / references / figuresmetadata_json 存 language_lock / pending_placeholders / conversation加字段零迁移，用 flag_modified 持久化
🔄 多轮对话持久化 最近 5 轮完整消息序列持久化（tool_call_id 严格配对） 下一轮直接 replay，语言锁与占位符从 metadata 重建 刷新浏览器不丢上下文，跨 session 可续写 |
🐳 Docker 代码沙箱--network none · --memory 512m · --read-onlycap-drop ALL · 30s 超时 · 绝不注入 API 密钥matplotlib / plotly / pandas / numpy 预装，中日韩字体就绪 📎 附件按文档隔离 project_id = "writer:{doc_id}" 命名空间search_knowledge 工具强制带 scope 过滤 A 文档附件不会污染 B 文档的 Agent 检索 |
每个模板只是一个 YAML + 可选的 .docx 文件，放入 modules/writer/templates/ 即刻生效。无需改代码、无需重启。
| Nature 通用期刊 |
CVPR 双栏 · 视觉 |
ICCV 双栏 · 视觉 |
IEEE 工程学术 |
ACM 计算机学术 |
中文期刊 中文双语 |
新增模板只需在
modules/writer/templates/your_template/放一个template.yaml（定义 sections / citation / 页面设置）和可选的template.docx。TemplateRegistry启动时自动发现。
Backend
Frontend
CodeLab Engine
WriterAI Engine
AI / Search
Infra
- Docker & Docker Compose
仅需 Docker，无需安装 Python、Node.js、Bun、PostgreSQL 或 Redis。所有服务容器化运行。
git clone https://github.com/zephyr4123/sololab.git && cd sololab
cp .env.example .env # 编辑 .env 填入 API Key（见下方）
docker compose up -d # 🚀 一行拉起全部 6 个服务启动后自动完成：PostgreSQL + pgvector 初始化 → Redis 就绪 → 数据库表自动迁移 → OpenCode 引擎启动 → Backend 就绪 → Frontend 构建 → Caddy 反向代理。
| 入口 | 地址 | 说明 |
|---|---|---|
| 🖥️ 前端界面 | http://localhost:3000 | 主工作台 |
| 📡 API 文档 | http://localhost:8000/docs | Swagger UI |
| 🔧 OpenCode | http://localhost:3101 | CodeLab 引擎（内部） |
| 🔒 反向代理 | https://localhost | Caddy 自动 HTTPS |
# ── IdeaSpark 模块（必填）──
IDEASPARK_BASE_URL=https://api.openai.com/v1 # OpenAI 兼容端点
IDEASPARK_API_KEY=<your-real-key> # 占位符 sk-xxx 会被启动时拒绝
IDEASPARK_MODEL=gpt-4o
BUDGET_LIMIT_USD=50.0 # 任务级预算，LLM 调用前会真正 enforce
# ── CodeLab 模块（3 变量直连 AI SDK）──
CODELAB_MODEL=anthropic/claude-sonnet-4-5 # 格式: providerID/modelID
CODELAB_API_KEY=<your-real-key>
# CODELAB_BASE_URL= # anthropic/openai/google 无需设置
# ── WriterAI 模块（留空则复用 IDEASPARK_*）──
# WRITER_BASE_URL=
# WRITER_API_KEY=
# WRITER_MODEL=
WRITER_SANDBOX_TIMEOUT=30
WRITER_SANDBOX_MEMORY=512m
# ── 向量嵌入（必填）──
EMBEDDING_BASE_URL=https://api.openai.com/v1
EMBEDDING_API_KEY=<your-real-key>
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1024 # 嵌入维度（换模型时同步调，需重建相关表）
# ── 外部 API ──
TAVILY_API_KEY=tvly-xxx
S2_API_KEY= # Semantic Scholar 可选
# ── 鉴权（留空禁用，所有路由放行；填入则全部 mutation 路由要求 X-API-Key）──
# API_KEYS=sk-sololab-xxx,sk-sololab-yyy
# ── 可观测 ──
LOG_LEVEL=INFO
LOG_JSON=false # 生产建议 true，方便日志聚合
CORS_ALLOW_ORIGINS=http://localhost:3000 # 逗号分隔；用 "*" 时 credentials 自动关闭
# ── 工作区 ──
WORKSPACE_DIR=/path/to/your/code # CodeLab Agent 的沙箱边界
STORAGE_PATH=./storage # 沙箱图表等运行时文件详见 .env.example。API key 占位符（
sk-xxx、空字符串等）会被LLMConfig在启动时直接拒绝，请填入真实 key。
开发和生产都通过 Docker 运行。改代码后重建对应服务即可：
# 改了前端代码 → 重建 frontend
docker compose up -d --build frontend
# 改了 OpenCode 引擎 → 重建 opencode
docker compose up -d --build opencode
# 改了后端 Python 代码 → 自动热重载（--reload 模式），无需重建
# 如果改了依赖 → docker compose up -d --build backend
# 查看日志
docker compose logs -f backend opencode # 实时跟踪
docker compose ps # 查看服务状态# 后端测试默认在容器内（pytest/httpx/fakeredis 已在镜像里）
docker compose exec backend pytest tests/unit/backend/ -m unit -q
docker compose exec backend pytest tests/integration -m integration
# E2E 用 host 跑（需要浏览器）
cd tests/e2e && npx playwright test
# OpenCode 引擎测试（独立 Bun 运行时）
cd opencode && bun run test后端代码改完自动热重载（bind-mount + uvicorn
--reload），无需重建容器；只有改了pyproject.toml依赖或Dockerfile才需docker compose build backend。
📂 Benchmark 复现指南见 消融实验报告。
soloLab/
├── backend/ # FastAPI 后端
│ └── src/sololab/
│ ├── main.py # 应用入口；lifespan 拆为 7 个 _init_* helper
│ ├── config/ # Pydantic Settings (API key fail-fast)
│ ├── core/ # 核心服务层
│ │ ├── auth.py # APIKeyAuth + verify_api_key
│ │ ├── cost_tracker.py # 预算 + 持久化
│ │ ├── llm/ # Provider Strategy + Registry + Quirks
│ │ │ ├── cost.py # CostTrackingProvider — 单点接住 budget+tracer+cost record
│ │ │ └── providers/ # openai/deepseek/anthropic/qwen/openai_compat
│ │ ├── llm_gateway.py
│ │ ├── memory_manager.py
│ │ ├── message_store.py
│ │ ├── module_registry.py
│ │ ├── observability.py # structlog + RequestContextMiddleware + LLMCallTracer
│ │ ├── rate_limiter.py
│ │ ├── session_manager.py
│ │ ├── task_state_manager.py
│ │ └── tool_registry.py
│ ├── api/ # REST 路由（_deps.py 暴露 AuthDep + build_module_context）
│ ├── db/ # 持久层
│ │ ├── base.py # Base + engine + sessionmaker
│ │ └── models/ # 一聚合根一文件（auth/blackboard/cost/document/memory/session/writer）
│ ├── schemas/ # Pydantic transport models (agent/module)
│ ├── modules/ # 可插拔功能模块
│ │ ├── ideaspark/ # 💡 IdeaSpark 多智能体
│ │ └── writer/ # ✍️ WriterAI (agent / 8 tools / templates / sandbox / export)
│ └── tools/ # 外部工具 (arXiv/Scholar/Tavily/PDF)
│
├── opencode/ # CodeLab 引擎 (OpenCode 核心)
│ ├── packages/opencode/src/ # 核心源码 (45 子模块)
│ │ ├── agent/ # Agent 定义 (build/explore/plan)
│ │ ├── session/ # 会话 + Compaction + 记忆
│ │ ├── provider/ # LLM Provider (直连 Vercel AI SDK)
│ │ ├── tool/ # 20+ 工具 (read/edit/bash/grep...)
│ │ └── server/ # Hono HTTP/WebSocket
│ └── opencode.jsonc # 引擎配置
│
├── frontend/ # Next.js 14 前端
│ └── src/
│ ├── app/ # App Router 页面
│ ├── components/ # UI 组件库 (含 modules/codelab/)
│ ├── lib/ # API Client & OpenCode Client
│ ├── stores/ # Zustand 状态管理
│ └── types/ # TypeScript 类型定义
│
├── tests/ # 测试 (unit/integration/e2e)
├── docs/ # 架构文档 & PRD
├── infra/ # Dockerfiles & Caddyfile
└── docker-compose.yml # 一键部署 (6 服务: PG + Redis + OpenCode + Backend + Frontend + Caddy)
SoloLab 采用 manifest + ABC 抽象类 的插件架构，同时支持通过独立引擎（如 CodeLab 的 OpenCode）集成高度专业化的模块。新模块不需要修改任何核心代码，不需要注册路由，不需要手动接线——放入目录即刻生效。
|
零配置发现 放入 modules/ 目录自动扫描 manifest.json启动即加载 |
全服务注入 LLM · 工具 · 记忆 · 文档 通过 ModuleContext一次注入，开箱即用 |
运行时热插拔 加载/卸载零停机 on_load / on_unload完整生命周期钩子 |
原生流式输出execute() 即 AsyncGenerator天然支持 SSE 推送 前端零适配 |
1. 声明 manifest.json — 描述模块元数据与依赖
{
"id": "your-module",
"name": "YourModule",
"version": "0.1.0",
"description": "Module description",
"icon": "Sparkles",
"entry_point": "sololab.modules.your_module.module:YourModule",
"required_tools": ["web_search", "arxiv_search"],
"required_models": ["reasoning"],
"config_schema": {
"type": "object",
"properties": {
"max_rounds": { "type": "integer", "default": 3 }
}
}
}2. 实现 ModuleBase — 只需两个方法
class YourModule(ModuleBase):
def manifest(self) -> ModuleManifest:
return load_from_json("modules/your-module/manifest.json")
async def execute(self, request: ModuleRequest, ctx: ModuleContext) -> AsyncGenerator:
# ctx 自动注入所有核心服务：
# ctx.llm_gateway — 100+ 模型，一行调用
# ctx.tool_registry — arXiv/Scholar/Tavily/PDF
# ctx.memory_manager — 向量记忆检索
# ctx.task_state_manager — SSE 事件持久化
# ctx.document_pipeline — PDF 解析与分块
response = await ctx.llm_gateway.generate(...)
yield TextChunk(content=response)3. 放入 modules/ 目录 — 自动发现、热加载、即刻可用
backend/src/sololab/modules/
├── ideaspark/ # ✅ 多智能体创意
│ ├── manifest.json
│ └── module.py
├── writer/ # ✅ 学术论文 Agent
│ ├── manifest.json
│ ├── module.py
│ ├── agent.py # WriterAgent 编排器
│ ├── tools/ # 8 专业工具
│ ├── templates/ # YAML 模板 (Nature/CVPR/...)
│ ├── sandbox/ # Docker 代码沙箱
│ └── export/ # PDF 导出 (Playwright + KaTeX)
└── your-module/ # 🆕 你的新模块
├── manifest.json
└── module.py
无需修改
main.py、无需注册路由、无需重启服务。ModuleRegistry.discover_modules()在启动时自动扫描，运行时可通过 API 动态加载/卸载。
引擎型模块（如 CodeLab）也遵循同样的模式 — 通过 api/codelab.py 代理层接入，Backend 负责 Session 统一管理，前端通过标准 API 调用。平台对模块的集成方式保持开放：既支持原生 Python 模块，也支持独立引擎通过 HTTP 桥接。
License · Apache License 2.0 | CodeLab Engine · Based on OpenCode (MIT License)
Author · Suxiang Huang · 📧 huangsuxiang5@gmail.com · 💬 WeChat: 13976457218
🏛️ Memory and Reasoning Lab, Tianjin University
SoloLab · One-Person Lab, Infinite Minds
Built for independent researchers who refuse to let team size limit their ambitions.