# ai-braintrust

**Repository Path**: lagrange1736/ai-braintrust

## Basic Information

- **Project Name**: ai-braintrust
- **Description**: ai-braintrust：基于LangGraph构建的多智能体研究/学习助手，模拟专业团队协作，自动完成调研、分析、撰写与审核任务。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-braintrust

基于 LangGraph4j 的多智能体研究/学习助手：输入一个主题，由研究员、分析师、作家、审核员协作，产出带出处的 Markdown 报告。

角色人设和工具写在 `src/main/resources/agents/research-team.yml`，四个槽位固定。改 YAML 后重启生效。

## 工作流

```mermaid
flowchart LR
    start([START]) --> researcher[研究员]
    researcher -->|需要搜索| tools[searchWeb]
    tools --> researcher
    researcher -->|材料足够| analyst[分析师]
    analyst --> writer[作家]
    writer --> reviewer[审核员给出建议]
    reviewer --> human[人审闸门]
    human -->|通过或到此结束| endNode([END])
    human -->|按意见修改 最多2轮| writer
```

固定流水线。自动审核员只给建议；Web 上由你点「通过 / 按意见修改 / 到此结束」。修改最多 2 轮。CLI 无按钮，第一轮后自动通过。

## 技术栈

- Java 17、Spring Boot 3.4、Maven Wrapper
- LangGraph4j：状态机编排
- LangChain4j `OpenAiChatModel`：OpenAI 兼容协议，不绑定某一家官方 SDK
- 搜索：Tavily（可选）→ 维基百科 → DuckDuckGo → **百度兜底**（不用 Bing）
- 页面：Thymeleaf + SSE；浅色产品风（顶栏、卡片、角色分色）；可下载 Markdown

## 模型接入

四个角色各自独立的 Key / 地址 / 模型，互不影响：

| 角色 | Key | 地址 | 模型 |
|------|-----|------|------|
| 研究员 | `LLM_RESEARCHER_API_KEY` | `LLM_RESEARCHER_BASE_URL` | `LLM_RESEARCHER_MODEL` |
| 分析师 | `LLM_ANALYST_API_KEY` | `LLM_ANALYST_BASE_URL` | `LLM_ANALYST_MODEL` |
| 作家 | `LLM_WRITER_API_KEY` | `LLM_WRITER_BASE_URL` | `LLM_WRITER_MODEL` |
| 审核员 | `LLM_REVIEWER_API_KEY` | `LLM_REVIEWER_BASE_URL` | `LLM_REVIEWER_MODEL` |

某个角色没填时，才回退到共用的 `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL`。

地址示例：

| 服务 | `*_BASE_URL` | `*_MODEL` 示例 |
|------|----------------|----------------|
| DeepSeek | `https://api.deepseek.com` | `deepseek-v4-flash` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| xAI / Grok | `https://api.x.ai/v1` | `grok-4.6` |
| 大模型网关 | `http://127.0.0.1:3000/v1` | 网关里登记的名称 |

网关需提供 `/v1/chat/completions`，并开启 function calling（研究员要调搜索）。本仓库不实现网关。

只换某一个角色，例如作家：

```env
LLM_WRITER_API_KEY=sk-另一个账号
LLM_WRITER_BASE_URL=https://api.deepseek.com
LLM_WRITER_MODEL=deepseek-v4-pro
```

## 搜索

`searchWeb` **一次调用内**按顺序尝试，命中即停，**不使用 Bing**：

1. Tavily（配置了 `TAVILY_API_KEY` 时）
2. 维基百科（中文站 → 英文站）
3. 中文查询：百度 → DuckDuckGo；英文查询：DuckDuckGo → 百度兜底

某个后端超时或失败后，约 3 分钟内跳过它。全部失败则停止继续搜（避免空转多轮），材料会标明未能联网检索。

## 运行

JDK 17+。仓库带 Maven Wrapper。

```bash
copy .env.example .env
# 为四个角色分别填写 API Key
.\mvnw.cmd spring-boot:run
```

浏览器：http://localhost:8080  

首页会列出 YAML 团队（调研报告 / 学习笔记可切换）；可上传 PDF/Markdown/txt。草稿出来后请你点「通过 / 按意见修改 / 到此结束」。闸门会落到本机 `data/paused/`，刷新后时间线与草稿一起恢复（约 4 小时）。通过后可下载 `.md`，报告旁有本轮账单；参考来源以外的 URL 会被剔除。改 `.env` 或 YAML 后必须重启。

CLI 无界面，会在第一轮审核后自动通过。

CLI：

```bash
.\mvnw.cmd spring-boot:run "-Dspring-boot.run.arguments=LangGraph 和 AutoGen 的区别"
```

测试：`.\mvnw.cmd test`

`.env` 同一键以最后一次赋值为准；真实环境变量优先于 `.env`；UTF-8 BOM 会被忽略。不要提交 `.env`。

IDEA：打开带 `pom.xml` 的目录，Run `BraintrustApplication`。工作目录设为项目根，否则读不到 `.env`。

## 界面

首页为浅色工作台：顶栏品牌、主题输入与附件、左侧团队 / 待审核 / 最近任务、进度时间线、右侧报告。审核闸门出现在报告下方。强制刷新（Ctrl+F5）以免旧 CSS 缓存。

## 设计取舍

- 固定角色流水线，比 Supervisor 更好讲、更好测
- 工具循环画在图上；中文检索更早试百度，英文把百度放最后
- 审核闸门由人点通过 / 修改 / 结束；自动审核只给建议；未过期闸门刷新/重启不丢（`data/paused/`），时间线一并恢复
- 每个角色独立客户端（独立 Key）；失败信息带角色名、模型与地址
- Agent 人设在 YAML（可切换调研/笔记团队）；可上传 PDF/笔记；任务落在本地 `data/runs/`（含节点账本）
- 定稿扫描 URL，列表外的链接删除并注明
- 浏览器先 POST 领票再 SSE，重连不会再开一轮
- 不做 Dify 画布、向量库、代码解释器、Bing

计划（索引：[docs/README.md](docs/README.md)）：

- [Plan 1](docs/plan1.md)：状态机与可运行助手（已完成）
- [Plan 2](docs/plan2.md)：YAML 团队与独立 Key（已完成）
- [Plan 3](docs/plan3.md)：上传 PDF/笔记、出处必须来自检索、本地任务复盘（已完成）
- [Plan 4](docs/plan4.md)：人在回路审核闸门（已完成）
- [Plan 5](docs/plan5.md)：闸门落盘，刷新不丢（已完成）
- [Plan 6](docs/plan6.md)：任务可核对（已完成）