Research Assistant Agent

面向论文复现、数据评测与预算受限自动研究的多智能体科研执行系统

Research Assistant Agent 把自然语言研究目标转换为可验证的执行计划：系统先理解任务、检索资料并固化评测契约，再由 Planner 生成 DAG，Scheduler 将节点路由给专业 Agent，在隔离沙箱中真实执行代码或实验，最后通过 Artifact、指标、EnvironmentManifest 和证据图给出可审计的结果。

项目由三个相对独立的源码部分组成：

• research-assistant/：完整产品实现，包含 Go 后端、React 工作台、Docker 沙箱服务、Python 研究优化器和可选 AI 服务。
• docker-core/：面向 Docker / gVisor 的底层沙箱内核实验模块，可独立构建和测试。
• tool/：一个零依赖的 Go 工具调用示例，演示 LLM Function Calling 的注册、路由与执行循环。

文档入口：1. 整体架构与 Agent 运行说明、2. 快速开始、3. 本地开发。变更记录见 docs/CHANGELOG.md，最近验证状态见 docs/verification.md。

系统把“研究意图”拆成可验证的执行链：

1. 理解：意图识别 + 类型化 ResearchContext（附件、论文元数据、文档、约束）。
2. 规划：统一 PlanBuilder 生成 DAG，InputBindings 绑定上下文/Artifact，DAG Validator 校验依赖与产物。
3. 授权：按计划级运行权限决定重要操作是自动执行还是逐项审批。
4. 执行：Scheduler 以租约、重试、取消和预算调度节点，专业 Agent 在 sandbox 中落地执行。
5. 验收：输出 Artifact、EnvironmentManifest、PlanOutcome 与逐主张证据图，而不是只看“节点是否完成”。

Researcher / Paper / Repository / Dataset
                    |
                    v
        React Workbench
  (permission selector / DAG / runtime action cards / outcome)
                    |
            REST / Upload / SSE
                    |
                    v
 API -> Intent Router -> ResearchContext
        (attachments, paper_metadata, document refs, constraints)
                    |
                    v
 Planner + InputBindings -> validated PlanGraph + Plan Store
                    |
                    v
 Scheduler (lease / retry / cancel / budget / awaiting_approval)
                    |
                    v
 Routed Task Executor
   Chat / General / Librarian / Answer / Benchmark / Coder / Research Coding / Data
                    |
                    v
 RuntimeGate (confirm_important / full_access)
                    |
                    v
 Sandbox Client -> docker-sandbox gateway -> executor -> Native Docker
                    |
                    v
 stdout / metrics / EnvironmentManifest / TrialLedger / claim evidence
                    |
                    v
 Artifact + PlanOutcome -> SSE -> Workbench

Archify 交互式图（自包含 HTML，浏览器直接打开）：系统架构图 · 多角色 Agent 执行工作流。

图形说明与编辑方式见 docs/README.md 和 docs/diagrams/README.md。

一次请求的完整执行路径如下：

1. 意图与上下文

   • 意图服务把自然语言分类为 Code_Execution、Paper_Reproduction、Framework_Evaluation、Custom_Benchmark、AutoResearch 或 General（服务返回的 Literature_Review / Data_Analysis 在 Go 侧归一为 General）。
   • 附件被解析为 AttachmentRef / DocumentRef；PDF 生成 paper_metadata，并写入 ResearchContext。
   • 计划级不变量检查附件/文档是否被节点引用，避免“上传了但没被消费”。

2. 计划生成

   • 统一 PlanBuilder 生成节点，节点通过 InputBindings 声明 context_attachment、context_document 或 artifact 来源。
   • Scheduler 在执行前解析绑定；必需绑定缺失时任务直接失败，不继续空跑。
   • DAG Validator 检查依赖、产物 producer、循环和关键节点契约。

3. 运行权限

   • 计划创建时选择 confirm_important（默认）或 full_access。
   • confirm_important：镜像拉取、依赖安装、数据/模型下载、GPU、网络访问前暂停，生成 RuntimeActionRequest；只有计划所有者能允许或拒绝。
   • full_access：在镜像 allowlist、磁盘/时长预算和 sandbox 安全边界内自动执行，并记录 auto_approved=true 审计动作。

4. 调度

   • Scheduler 负责租约、并发槽位、重试、取消、预算和 awaiting_approval 暂停/恢复。
   • 等待审批的任务不会被视为终态；审批通过后从原节点继续，拒绝则终止计划并标记 outcome=blocked。

5. Agent 执行

   • 节点按 assigned_to 路由到专业 Agent。
   • 所有跨 Agent 数据通过 Artifact/InputBindings 传递，不再依赖模板手工拼 Inputs。

6. Sandbox 执行

   • 运行时先探测宿主能力（Docker、GPU、CPU、内存、磁盘、镜像 allowlist），再准备镜像。
   • 依赖安装、运行命令和 import 检查都在 sandbox 中真实执行；输出 EnvironmentManifest。

7. 结果验收

   • PlanFinalizer 根据证据把结果标记为 completed、partial、smoke、mock、blocked、failed 或 needs_review。
   • Claim-Evidence 图把论文主张、判定准则和真实 Artifact 绑定；前端显示 OutcomeBadge 与 missing requirements。

论文复现请求在创建计划时传入：

{
  "intent": "复现我上传论文的核心方法并跑通最小测试",
  "attachments": ["<upload-id>"],
  "runtime_permission_mode": "confirm_important",
  "runtime_permission_acknowledged": false
}

• 重要操作需确认（confirm_important，默认）：拉取镜像、安装依赖、下载公开数据/模型、使用 GPU 或访问网络前，计划暂停并生成 RuntimeAction；只有计划所有者可以允许或拒绝。
• 完全权限（full_access）：上述操作在镜像 allowlist、磁盘/时长预算与 sandbox 安全边界内自动执行；创建计划时必须显式传 runtime_permission_acknowledged=true。
• 拒绝重要操作会立即终止计划：status=failed、outcome=blocked，并写入 missing_requirements=[user_rejected]；审批超时会写入 approval_timeout。
• 运行时链为 reproduction_spec -> runtime_probe -> image_prepare -> prepare_runtime -> install_dependencies -> runtime_validate -> paper_code_execute。
• runtime_validate 输出 EnvironmentManifest：镜像 digest、Python/pip freeze、GPU、数据 hash、运行命令与工作目录。
• 完整复现资源不足时不会用 smoke 冒充成功；outcome 会明确标记 smoke、partial 或 blocked。

Research Assistant Agent/
├── README.md
├── .github/workflows/ci.yml     # Linux/Windows CI：Go、前端、Python、Docker build
├── docs/                        # 架构图、设计、轮次报告、CHANGELOG 与验证状态
├── docker-core/                 # 底层 Docker/gVisor 沙箱内核实验模块
│   ├── checkpoint/              # 快照、回滚与负反馈注入
│   ├── config/                  # TOML 配置加载
│   ├── executor/                # DAG 调度、节点竞速与资源网关
│   ├── sandbox/                 # 持久化 TTY 沙箱
│   ├── watchdog/                # 语义断路器与超时防护
│   └── tests/                   # 真实 Docker 集成测试
├── research-assistant/          # 产品主实现
│   ├── backend/                 # Go API、Planner、Scheduler、Agent
│   ├── frontend/                # React + TypeScript 工作台
│   ├── docker-sandbox/          # 独立 Go 沙箱服务
│   ├── research-optimizer/      # Python 候选策略与经验存储
│   ├── ai-services/             # 可选 Python AI 服务
│   ├── examples/                # 可运行示例与验收脚本
│   ├── test/                    # E2E、Golden test 与 fixtures
│   ├── scripts/                 # Unix / Windows 启动脚本
│   ├── backend.env.example
│   ├── docker-compose.yml
│   └── Makefile
└── tool/                        # Go 工具调用框架示例

• 本项目是研究原型，接口和数据结构可能调整，不承诺向后兼容。
• 单机持久化基于“按计划原子快照 + 小型 append-only JSONL 索引/事件日志”；多副本部署需要共享事务数据库与 leader election。
• 已支持静态 API token 和计划所有权检查，但不是 OIDC、RBAC 或生产级多租户认证。
• docker-sandbox gateway 不挂载 Docker socket，也不挂载宿主工作区；只有内部 docker-sandbox-executor 持有 socket 和 /tmp 挂载。executor 不发布端口，仍是受控的高权限执行边界。
• 默认运行时镜像是 CPU/通用 Python 镜像；GPU 透传需要额外配置。
• 运行时权限只决定“是否自动执行重要操作”，不会绕过镜像 allowlist、资源上限、sandbox 隔离或计划所有权检查。
• 当前复现重点是轻量 smoke 与结构消融，不包含大规模数据集训练；资源不足时返回 blocked/partial，不会用 mock 冒充成功。
• Framework_Evaluation 仍保留 deterministic offline baseline；它不是真实 LangChain/LlamaIndex 性能 benchmark，真实框架评测需独立专项。
• 候选搜索是真实 Validation Reward 驱动的分层 UCB、Top-K Beam 与 UCT-style 搜索，不是完整 MCTS 或通用强化学习策略。

• Docker Engine 20.10+ 与 Docker Compose v2
• Git
• 一个 OpenAI-compatible LLM API Key（示例配置值见 research-assistant/backend.env.example）
• 本地开发需要 Go 1.26.1（backend、docker-sandbox、docker-core、tool）与 Node.js 22+
• 后端依赖 Linux 进程组与 Statfs，Windows 原生后端不受支持；Windows 请使用 Docker Compose

cd research-assistant
cp .env.example .env
# 编辑 .env，设置随机 SANDBOX_API_TOKEN、RESEARCH_OPTIMIZER_API_TOKEN 与 API_AUTH_TOKEN
# Compose 会从 .env 注入这些 Token；API_AUTH_TOKEN 由 nginx 反向代理在请求时注入，不会编进前端 bundle。
cp backend.env.example backend.env
# 编辑 backend.env，至少填写 OPENAI_API_KEY
docker compose up --build -d

启动后访问（端口可通过 .env 的 *_HOST_PORT 覆盖，以下为默认值）：

确认后端与沙箱均已就绪：

curl -s http://localhost:8080/api/health

期望响应中同时出现 backend.ok=true、repository.ok=true、sandbox.ok=true 与 research_optimizer.ok=true。查看日志或停止服务：

docker compose logs -f
docker compose down

在 Web UI 输入：

请使用 https://github.com/harvardnlp/annotated-transformer 复现
Attention Is All You Need，使用 smoke 模式运行轻量注意力消融，
不要执行 WMT14 完整训练。

在发送前选择“重要操作需确认”或“完全权限”。系统会生成并执行“解析论文 -> 冻结主张 Rubric -> 检索仓库 -> 准备工作区 -> 解析依赖 -> 生成 RuntimeSpec -> 探测 sandbox 能力 -> 准备镜像 -> 准备运行时 -> 安装依赖 -> 校验运行时/写 EnvironmentManifest -> 执行实验 -> 对比论文声明 -> 主张证据图”的主链。

如果选择“重要操作需确认”，镜像拉取和依赖安装会分别暂停，等待在右侧计划面板中允许或拒绝；拒绝后计划立即终止并标记 outcome=blocked。

上传 CSV、TSV、JSON 或 JSONL 后输入：

用 https://github.com/OWNER/REPOSITORY 跑 benchmark，
输入列是 review，标签列是 label，最多运行 500 条样本。

Benchmark Agent 会审计列映射、生成泄漏安全的 train/validation/test 划分，冻结 Metric/Reward 契约，并在模型不可见的隐藏标签上重算最终指标。

用 https://github.com/OWNER/REPOSITORY 做 AutoResearch，
按 autoresearch.json 运行，最多 3 轮，总时长不超过 15 分钟，最终验证 3 次。

系统冻结 ResearchSpec 与仓库 revision，在受限文件范围内生成候选，按真实指标执行 Keep/Reject、退化回滚和隐藏 Holdout 复验。

cd research-assistant
make install
export SANDBOX_API_TOKEN=<random-token>
make run-sandbox     # 终端 1，本地 engine 模式沙箱
make run-backend     # 终端 2，需要 SANDBOX_URL 与 API_AUTH_TOKEN
make run-frontend    # 终端 3

Windows 用户请使用 Docker Compose；scripts/windows/start-backend.ps1 会直接提示 Docker Compose，后端原生 Windows 编译仍不受支持。CI 的 Windows job 覆盖 docker-sandbox 测试与 docker-core 构建，backend 保持 Linux-only；前端在 Linux job 中构建与测试。详见 scripts/README.md。

复制 research-assistant/backend.env.example 为 backend.env。常用变量：

后端镜像构建还支持 DEBIAN_MIRROR 与 DEBIAN_SECURITY_MIRROR，由执行 docker compose 的 shell 或项目 .env 读取。GPU 透传需要宿主机安装 NVIDIA Container Toolkit，并设置 SANDBOX_DOCKER_GPUS=all。

以下为 Backend API（默认 :8080）：

Sandbox 服务（默认 :8082）另有：

完整路由和请求结构见 backend/README.md 与 openapi.json；命令行工具见 scripts/ra.mjs。

后端（Linux 或容器内）：

cd research-assistant/backend
go test ./...
go vet ./...

前端：

cd research-assistant/frontend
npm test
npm run lint
npm run build
npm run check:bundle

Sandbox 与 docker-core：

cd research-assistant/docker-sandbox && go test ./...
cd docker-core && go test ./...

容器内 E2E（需要运行中的 compose 栈；套件位于 research-assistant/test/e2e/，使用 RA_API_URL / RA_API_TOKEN）：

• 既有：http-smoke.mjs、routing-and-prompts.mjs、literature.mjs、literature-plan.mjs、document-intelligence.mjs、model-profiles.mjs、verification.mjs、sandbox-network.mjs、round6-*.mjs
• 桌面/命令：desktop-smoke.mjs（provider 能力矩阵）、sandbox-command.mjs（argv/legacy/截断）
• 深度：round7-api-coverage.mjs、round7-real-scenarios.mjs、round7-paper-reproduction.mjs、round7-autoresearch.mjs、round7-task-execute.mjs、round7-doc-assist.mjs、round7-sandbox-deep.mjs
• 最近一次结果与已知缺陷见 docs/verification.md；本地完整证据见 reports/eval-2026-10-28/REPORT.md（按约定不提交）

desktop/ 是独立的 Go module，包含 Windows 首发所需的桌面外壳支撑包：

• desktop/shell：settings→端口→token→supervisor→proxy 编排、崩溃自动重启、/desktop/state|diagnostics|retry 与错误页。
• desktop/supervisor：单实例锁、OS 分配端口、backend/sandbox 子进程启动与健康检查、退出顺序、Windows Job Object 回收。
• desktop/proxy：固定 loopback origin 的反向代理，SSE FlushInterval=-1，Host/Origin 守卫与 SPA 回退。
• desktop/settings：settings.json、环境变量注入表、Windows DPAPI 密钥存储（非 Windows 为显式 unsupported）。
• desktop/diagnostics / desktop/updater：脱敏诊断包；semver + SHA-256 + Ed25519 更新校验。
• desktop/onboarding / desktop/bridge / desktop/tray：首次启动向导、Wails 绑定、托盘契约。
• docker-sandbox/internal/engine/native：uv 管理的 CPython + venv 缓存、命令翻译、AppContainer/lowil runner、双 profile 网络、Job 限额、附录 D 探针；非 Windows 返回 unsupported_platform。
• docker-sandbox/internal/engine/vm / remote：WSL2 检测与执行路径（路径/argv 翻译）、OpenSandbox Provider 适配器。
• 后端、docker-sandbox、desktop 均支持 GOOS=windows GOARCH=amd64 go build ./...（desktop 另验证 Wails tag）；Linux 容器内运行纯逻辑单测。

构建说明见 desktop/README.md。Wails 入口使用 //go:build desktop && wails，不改变默认 CI 构建。

• docs：架构图、流程图、设计与轮次报告
• research-assistant：产品主实现与启动方式
• backend：Go API、规划、调度与 Agent
• frontend：React 工作台
• docker-sandbox：独立沙箱服务
• research-optimizer：Python 候选策略服务
• ai-services：可选 AI 服务与意图识别
• examples：可运行示例
• docker-core：底层沙箱内核实验模块
• tool：Go 工具调用框架示例