# duolan-multi-agents

**Repository Path**: larntin/duolan-multi-agents

## Basic Information

- **Project Name**: duolan-multi-agents
- **Description**: 基于 Deep Agent 开发的企业内可部署的多 Agents Harness 项目
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# multi-agents harness

企业内部 multi-agents harness 骨架。deepagents（LangGraph）+ FastAPI + FastMCP + OpenSandbox + MongoDB。
首个业务场景：采购比价。

设计决策全部记录在 [`docs/`](docs/)，入口是 [`docs/00-架构疑问选择.md`](docs/00-架构疑问选择.md)（决策日志）
与 [`docs/09-deepagents实测API与设计修订.md`](docs/09-deepagents实测API与设计修订.md)（实测与修订记录）。

---

## 一、跑起来

### 0. 前置：本机服务

基础服务**裸跑在本机，本项目不用 Docker 部署它们**。Docker 只给不可信代码执行沙箱。

| 服务 | 端口 | 说明 |
|---|---|---|
| MongoDB | 27017 | 无鉴权（有意为之，见 `CLAUDE.md`） |
| Redis | 6379 | **有密码**，写在 `.env` 里 |
| Docker Desktop | — | 沙箱要用 |

```bash
uv sync            # 装 Python 依赖（网络不通先设代理，见下）
cp .env.example .env
docker build -t ma-sandbox:latest deploy/sandbox   # 可选，当前用官方 code-interpreter 镜像
```

网络走本机代理，否则 PyPI / npm 会超时：

```powershell
$env:HTTP_PROXY='http://127.0.0.1:7897'; $env:HTTPS_PROXY='http://127.0.0.1:7897'
```

### 1. 四个常驻进程（各开一个终端）

它们都是前台进程，**关掉终端就停**。

```bash
# ① 代码执行沙箱服务（配置在 ~/.sandbox.toml，端口 8082）
uvx opensandbox-server

# ② MCP 网关：ERP 防腐层 + 等级权限（端口 8001）
uv run python -m mcp_server.server

# ③ 后端（端口 8090）
uv run python -m core.app

# ④ 前端（端口 5173，已代理到 8090）
cd web && pnpm install && pnpm dev
```

可选：

```bash
uv run phoenix serve      # 可观测性 UI，端口 6006；不起也不影响运行
```

### 2. 体检

```bash
uv run python -m core.preflight
```

必需项全绿才启动后端。缺服务时它会**拒绝启动并打印开启提示**，不会自作主张用容器顶替。

### 3. 打开 http://localhost:5173

---

## 二、建议按这个顺序试

| # | 操作 | 预期 | 验证了什么 |
|---|---|---|---|
| 1 | 点「新建」，输入：`用 execute 在 /workspace 建 a.md 写「测试」，再用 read_file 读回` | 两张工具卡片 + 助手回复 + 右侧产物区出现 `a.md` | 沙箱、事件流、产物捕获 |
| 2 | 点产物的「下载」 | 浏览器下载文件 | 产物下载 + uid 归属校验 |
| 3 | **刷新页面**，重新点开这个会话 | 对话与产物完整还原 | 历史快照、`/messages`、`/artifacts` |
| 4 | 继续问：`刚才那个文件还在吗？用 ls 看看 /workspace` | agent 能看到上一轮的文件 | **产物回灌**（新沙箱 + 从 MongoDB 灌回） |
| 5 | 输入：`请安装 mall-scraper 技能` | **弹出审批框**，点「批准」后继续执行 | **HITL 中断 → 审批 → 恢复** |
| 6 | 点左下「模型设置」→ 填模型 → 点「自检」 | 三步逐条打勾，显示档位与窗口 | BYOK 自检（QO） |
| 7 | 把「等级」改成 1，再问一次任何问题 | agent 可用工具变少 | 等级权限过滤 |

第 5 步是最值得看的——它是唯一一条「不批准就真的做不成」的链路：`fetch_external_domain` 批准后才会调 `patch_egress_rules` 给沙箱放行域名。

---

## 三、命令行验证（不用点界面）

```bash
uv run python -m scripts.verify_demo_model     # 模型三步自检
uv run python -m scripts.verify_gateway_tools  # 各等级可见工具集 vs 权限表
uv run python -m scripts.e2e_smoke             # 端到端：真沙箱 + 真模型
uv run python -m scripts.hitl_smoke            # 中断 → 审批 → 恢复
uv run python -m evals.runner                  # L1 评测跑分

uv run pytest -q -m "not sandbox"              # 日常测试（不需要 Docker）
uv run pytest -q                               # 全量（需 Docker + 沙箱服务）
```

---

## 四、端口

| 组件 | 端口 |
|---|---|
| ERP（外部系统，**暂未接入**，见 `docs/08`） | 8000 |
| MCP 网关 | 8001 |
| OpenSandbox server | 8082 |
| FastAPI | 8090 |
| 前端 | 5173 |
| MongoDB / Redis | 27017 / 6379 |
| Phoenix（可选） | 6006 / 4317 |

---

## 五、目录

```
core/            与业务无关的骨架（不许出现「采购」二字）
  agent/         唯一调用 create_deep_agent 的地方 + HITL 工具 + MCP 接入
  backend/       沙箱 backend、池、CompositeBackend、skills 同步
  models/        模型注册表、能力分档、BYOK 凭据、自检
  storage/       MongoDB 单栈：store / artifacts / 事件总线
  runtime/       run 生命周期 + SSE + 执行器 + 历史快照
  telemetry/     OTel（后端可换，不绑私有 SDK）
agents/          业务 agent，按领域分目录
mcp_server/      FastMCP 网关 + permissions.yaml
evals/           L1 评测用例、判定、指标、跑分器
web/             React + Tailwind 前端
scripts/         自检与冒烟脚本
docs/            设计文档与决策日志
```

---

## 六、已知边界

不是 bug，是有意为之或缺输入的部分：

| 项 | 现状 |
|---|---|
| **ERP 未接入** | MCP 工具已注册且权限过滤生效，但背后是 `NotConnectedERPClient`，调用会**明确报错**而非返回假数据 |
| **eval 只有 5 条** | `docs/03` 要求 20 条，补齐需要真实历史采购请求 |
| **L2 产物质量评测** | 未实现，需要先有真实业务产物 |
| **`/data` 目录语义** | 未定，只在 `BASE_DIRS` 里占位，没有路由 |
| **HITL 的 edit 决定** | 未开放，需要前端能编辑 tool args |
| **行级数据权限** | 第一版不做——目标 ERP 只有 admin/operator 两个角色，没有行级权限（`docs/08`） |
| **OTel** | 代码接好了，但没对着真实 Phoenix 验证过 |