Synapse/README.zh.md at main · Vincentwei1021/Synapse

面向人类研究者与 AI Agent 的研究编排平台

Synapse 是一个研究编排平台，让人类研究者与 AI Agent 协同工作。它管理完整的研究生命周期，从文献综述、问题制定到实验执行与报告生成，内置 Agent 管理、算力编排和实时可观测性。

灵感来源于 AI-DLC（AI 驱动开发生命周期）方法论，构建于 Chorus 之上。

Milestone： 我们已经在 Synapse 平台上复现了 Karpathy 的 auto-research 任务与效果。与直接设计单个 agent 的 program.md 行为模式不同，Synapse 将自主实验作为平台的原生能力。研究项目、实验生命周期、算力分配和上下文积累均由平台通过结构化的 MCP 工具统一管理，形成 dynamic contexting。所有研究记忆都持久化在平台中，作为工具化状态提供给 agent 按当前状态随时调用、获取与展开，而不是依赖 agent 的上下文窗口一次性强制全部读取。

Vibe Research

什么是 Vibe Research？

Vibe Coding 证明了人可以描述意图，让 AI 负责执行。Vibe Research 则把这种范式延伸到研究生命周期：

人类设定方向。Agent 执行、汇报、提议并迭代。人类审核、纠偏并做最终决策。

研究中 Agent 自主性的阶段

Synapse 的愿景，是有节奏地推动研究团队穿越这些阶段。

把 Stage 1 做顺：让实验执行、算力调度、结果沉淀和报告生成变成默认工作流，而不是一串手工交接。
让 Stage 2 变可靠：把上下文、论文、实验、进度和评审放在同一个系统里，让 Agent 可以在明确边界内独立推进，而不轻易跑偏。
让 Stage 3 可实现：提前搭好项目级委派所需的控制平面，包括结构化上下文、可观测性、编排能力、权限体系，以及关键节点上的人工 steering。

功能特性

项目工作空间

Synapse 为每个研究项目提供统一的操作空间，承载项目简介、数据集、评估方法、研究问题、实验、报告和滚动综合分析。人类和 Agent 不再在文档、脚本、表格和聊天工具之间来回切换，而是在同一份上下文上协作。

研究问题画布

以画布式层级结构组织研究问题与子问题
从探索、细化到创建实验与完成问题，持续追踪问题进度
让研究问题与对应实验、报告保持上下文连接

实验执行看板

五列实验流水线：draft → pending_review → pending_start → in_progress → completed
Agent 执行实时状态：sent、ack、checking_resources、queuing、running
通过 synapse_report_experiment_progress 回传进度
当队列为空时支持 autonomous loop，由 Agent 提出下一批实验

Agent 管理

基于 API Key 的 Agent MCP 访问方式
用户级 Agent 所有权、密钥管理和 Session 可观测性

五种 Agent 权限角色（可组合）：

权限	职责
预研	文献检索，通过 Semantic Scholar 发现相关论文
研究	提出研究问题，假设构建
实验	执行实验，分配算力，上报进度
报告	生成实验报告、文献综述、综合分析文档
管理	创建/删除项目、管理分组、审核研究问题

算力编排

算力池、节点盘点、GPU 预留，以及项目级算力池绑定
通过托管访问包让 Agent 安全连接计算节点
让 Agent 在实验前、实验中和实验间都能基于可用资源运行

报告、综合分析与 MCP 能力

Agent 在项目语境里自动撰写实验报告，而不是套固定模板
Synapse 会持续维护项目级综合分析文档
70+ MCP 工具覆盖项目上下文、文献检索、实验执行、算力访问与协作

快速开始

一键安装（无外部依赖）

npm install -g @synapse-research/synapse
synapse

打开 http://localhost:13000，使用 admin@synapse.local / synapse 登录。

内置 PGlite 嵌入式数据库，无需安装 PostgreSQL 或 Redis。数据存储在 ~/.synapse/data。

选项：synapse --port 3000 --data-dir /path/to/data --help

Docker

git clone https://github.com/Vincentwei1021/Synapse.git
cd Synapse

export DEFAULT_USER=admin@example.com
export DEFAULT_PASSWORD=changeme
docker compose up -d

打开 http://localhost:3000 登录。

本地开发

前提：Node.js 22+, pnpm 9+, PostgreSQL

cp .env.example .env
# 编辑 .env 配置 DATABASE_URL

pnpm install
pnpm db:push
pnpm dev

open http://localhost:3000

.env.example 中已包含内置登录账户：

字段	值
邮箱	`dev@synapse.local`
密码	`synapse123`

可在 .env 中修改 DEFAULT_USER 和 DEFAULT_PASSWORD。当两个变量均已设置时，Synapse 启用简单的邮箱/密码登录，无需配置 OIDC。

连接 AI Agent

方式一：OpenClaw（推荐）

openclaw plugins install @vincentwei1021/synapse-openclaw-plugin

然后在 OpenClaw 设置中配置 synapseUrl 和 apiKey。

提示： 如果遇到 Request timed out before a response was generated，请在 OpenClaw 配置中增大空闲超时：将 agents.defaults.llm.idleTimeoutSeconds 设为 300。

方式二：Claude Code 插件

claude
/plugin marketplace add Vincentwei1021/Synapse
/plugin install synapse@synapse-plugins

设置环境变量：

export SYNAPSE_URL="http://localhost:3000"
export SYNAPSE_API_KEY="syn_your_api_key"

方式三：Codex 插件

Codex 当前仅支持论文搜索阶段。在 Synapse 中创建 codex 类型的 Agent;codex 类型被限定为 pre_research 角色(Agent 对话框会强制此限制)。更广阶段(实验、报告)尚未接入 Codex。

MCP 服务器不随插件打包(Codex 不会展开插件 .mcp.json 中的 ${VAR}),因此需自行配置一次。CLI 与桌面 App 的步骤略有不同。

Codex CLI

codex plugin marketplace add Vincentwei1021/Synapse
codex plugin add synapse@synapse-plugins

export SYNAPSE_URL="http://localhost:3000"
export SYNAPSE_API_KEY="syn_your_api_key"
codex mcp add synapse --url "$SYNAPSE_URL/api/mcp" --bearer-token-env-var SYNAPSE_API_KEY

请在启动 Codex 之前运行 codex mcp add(它写入 ~/.codex/config.toml,启动时读取)。

Codex App(桌面版)

添加插件市场。 打开 Plugins → Built by OpenAI → Add more,来源填写 https://github.com/Vincentwei1021/Synapse.git,然后将市场选择器切换到 synapse-plugins。
安装插件。 在 Productivity → Synapse 下点击 + 安装,然后打开该插件进行配置。
配置 MCP 服务器。 在插件配置中添加服务器:
- 名称:synapse
- 传输方式:流式 HTTP
- URL:http://localhost:3000/api/mcp
- Bearer 令牌:直接粘贴你的 syn_... API key(App 在此处接受令牌值,无需环境变量)。
精简技能。 仅保留 Research 技能,取消勾选其他技能(它们面向 Codex 尚不支持的阶段)。

App 允许直接粘贴令牌值,因此 —— 不同于 CLI 的 --bearer-token-env-var 流程 —— 你无需 export SYNAPSE_API_KEY 或使用 launchctl setenv。

方式四：手动 MCP 配置

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "synapse": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer syn_your_api_key"
      }
    }
  }
}

进展

已实现

计划中

在 in_progress 实验过程中直接 steer 正在运行的 Agent
将底层实验日志与高层进度分离，并实时回传到面板
通过隔离的 git tree / worktree 并行运行实验
用一等能力支持 baseline 与 accept/reject criteria
追踪代码版本、配置、产物和环境等可复现信息

文档

文档	说明
CLAUDE.md	开发指南与编码规范
Architecture	技术架构
MCP Tools	MCP 工具参考
OpenClaw Plugin	插件设计与 Hooks
Docker	Docker 部署指南

许可证

AGPL-3.0 — 见 LICENSE.txt

Navigation Menu

Repository navigation

README.zh.md

README.zh.md

最新动态

目录

Vibe Research

什么是 Vibe Research？

研究中 Agent 自主性的阶段

功能特性

项目工作空间

相关文献与深度研究

研究问题画布

实验执行看板

Agent 管理

算力编排

报告、综合分析与 MCP 能力

快速开始

一键安装（无外部依赖）

Docker

本地开发

连接 AI Agent

方式一：OpenClaw（推荐）

方式二：Claude Code 插件

方式三：Codex 插件

方式四：手动 MCP 配置

进展

已实现

计划中

文档

许可证

FilesExpand file tree

README.zh.md

Latest commit

History

README.zh.md

File metadata and controls

最新动态

目录

Vibe Research

什么是 Vibe Research？

研究中 Agent 自主性的阶段

功能特性

项目工作空间

相关文献与深度研究

研究问题画布

实验执行看板

Agent 管理

算力编排

报告、综合分析与 MCP 能力

快速开始

一键安装（无外部依赖）

Docker

本地开发

连接 AI Agent

方式一：OpenClaw（推荐）

方式二：Claude Code 插件

方式三：Codex 插件

方式四：手动 MCP 配置

进展

已实现

计划中

文档

许可证