Synapse

基于 LangChain Deep Agents 的本地 Synapse。

• Harness: deepagents.create_deep_agent
• Backend: LocalShellBackend（无 sandbox）
• 默认审批: 关闭 / 自动通过
• 依赖管理: uv

功能

安装

前置要求

• Python >= 3.12
• uv（包管理器）

方法一：安装为系统 CLI 工具（推荐）

项目已声明 console script，可一次安装到用户 PATH，之后无需 uv run。

# 可编辑安装（开发推荐；改代码立刻生效）
powershell -ExecutionPolicy Bypass -File scripts/install.ps1

# 或手动
uv tool install --editable --force .

安装后任意目录直接使用：

synapse tui -w .
synapse run "查看当前仓库结构并总结" -w .

仓库根目录还提供 synapse.cmd 薄启动器（优先 PATH 上的入口，其次 .venv\Scripts，最后回退 uv run）。

方法二：本地 venv 开发

# 同步依赖
uv sync

# 使用 venv 入口（Windows）
.\.venv\Scripts\synapse.exe tui -w .

# 或模块入口
uv run python -m synapse tui -w .

# 兼容旧写法
uv run synapse chat -w .

卸载

uv tool uninstall synapse
# 或
powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -Uninstall

快速开始

安装并配置完成后，即可运行：

# TUI 交互界面（推荐）
synapse tui -w .

# 单次执行
synapse run "总结当前项目结构" -w .

# CLI 对话
synapse chat -w .

会话管理

synapse sessions list
synapse sessions export <thread_id> -f md
# 默认写入 .coding-agent/exports/<thread_id>.md；打印到终端加 --stdout

模型与 MCP 管理

synapse models list
synapse mcp list

配置

Synapse 采用分层配置策略：用户全局配置（~/.synapse/）与项目本地配置（<workspace>/.synapse/）合并，项目层覆盖用户层。

~/.synapse/              # 用户全局层（优先级低）
  models.json            # 模型 profiles + api_key（推荐方式）
  mcp.json               # MCP Server 定义
  settings.json          # 非敏感 Settings 覆盖
  themes.json            # 自定义 UI 主题

<workspace>/.synapse/    # 项目层（优先级高，覆盖用户层）
  models.json
  mcp.json
  settings.json
  themes.json
  system_prompt.md       # 自定义系统提示
  sessions.sqlite
  checkpoints.sqlite

方式一：环境变量（.env 快速入门）

从模板创建，填入密钥即可：

cp .env.example .env

核心变量：

完整变量列表见 .env.example。

方式二：models.json（多模型 profiles，推荐）

在 ~/.synapse/ 或 <workspace>/.synapse/ 下创建 models.json。支持多 profile、自定义模型参数（temperature、max_tokens、thinking 等）。

参考示例：examples/models.example.json

{
  "default": "primary",
  "models": {
    "primary": {
      "model": "openai:gpt-4.1",
      "api_key": "sk-REPLACE_ME",
      "websocket": false,
      "context_window": 128000,
      "temperature": 0.2,
      "max_tokens": 8192
    },
    "deepseek": {
      "model": "openai:deepseek-v4-pro",
      "api_key": "sk-REPLACE_ME",
      "base_url": "http://127.0.0.1:3000/v1",
      "context_window": 128000,
      "thinking": "high",
      "temperature": 0.2
    }
  }
}

OpenAI Responses API 同时支持 HTTP/SSE 与普通 LLM WebSocket。profile 中设置
"websocket": true 后，Synapse 使用持久 /v1/responses WebSocket；省略或设为
false 时保持现有 HTTP/SSE。自定义 OpenAI-compatible 网关必须实现该 WebSocket
端点，否则请保持关闭。WebSocket 模式会自动启用 use_responses_api。

通过 AGENT_ACTIVE_MODEL 环境变量或 CLI 参数切换 profile。

非多模态模型的图片识别

主模型与识图模型独立配置。主模型 profile 不写 image_input 时，Synapse 会按常见模型名推断；未知的 OpenAI-compatible 模型默认按纯文本模型处理。需要覆盖推断时，在 profile 中写 "image_input": true/false。

识图模型放在同一层 models.json 顶层的 vision_model 配置中（也支持 settings.json），可以自由更换任意兼容 OpenAI Chat Completions 图片输入的服务：

{
  "vision_model": {
    "model": "qwen-vl-max",
    "base_url": "https://your-vision-gateway.example/v1",
    "api_key_env": "VISION_API_KEY",
    "timeout_secs": 45,
    "max_input_bytes": 10485760,
    "max_retries": 2,
    "fallback_model": "qwen-vl-plus",
    "allow_remote_urls": false,
    "think": true,
    "prompt": "Describe the image for a text-only coding assistant. Extract visible text and errors."
  }
}

vision_model.model、base_url、api_key_env 均可更换；api_key 也支持，但建议使用环境变量。think 是识图模型独立的思考开关，开启后发送 thinking: {"type": "enabled"}；它不影响主模型。默认只处理本地/内存图片；将 allow_remote_urls 设为 true 才会把消息中的 HTTP(S) 图片 URL 转发给识图服务。该服务只用于把图片转换成文字，配置后图片内容会发送到指定服务。多模态主模型会跳过该 middleware，不调用识图服务。

MCP 服务器配置

在 ~/.synapse/ 或 <workspace>/.synapse/ 下创建 mcp.json。

参考示例：examples/mcp.example.json

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "enabled": false
    },
    {
      "name": "anysearch",
      "transport": "streamable_http",
      "url": "https://api.anysearch.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ANYSEARCH_API_KEY}"
      },
      "enabled": false,
      "tool_prefix": "anysearch__"
    }
  ]
}

配置后通过 synapse mcp list 查看状态，可在 TUI 中动态启用/禁用。

Settings 覆盖

在 ~/.synapse/settings.json 或 <workspace>/.synapse/settings.json 中写入非敏感配置，与 .env 环境变量作用相同但优先级更高（项目层 > 用户层 > 环境变量）。

使用技巧

TUI 快捷键

文本选择：transcript 中答案/Thought/工具组/用户条支持鼠标拖选（有高亮），划选后用 Alt+C 复制。

斜杠命令（chat / TUI）

• /help /thread /new /sessions /session ... /switch <id>
• /rename /export [md\|json] [path]
• /model /model <alias>
• /mcp list|tools|test|reload|enable|disable|config
• /clear /exit

补全：TUI 输入 / 后有 ghost 建议（Tab/→ 接受，Shift+Tab 上一项，Ctrl+Space 列出候选）；chat 模式下 Tab 补全。

MCP transports

连接在后台事件循环中保持复用；/mcp reload 重建 agent 与连接池。

models.json 字段说明

.env 仍可读，仅作迁移/CI 兼容，不推荐作为常规分发方式。

示例：修复 sample_repo

tests/fixtures/sample_repo 中 sub() 有意写错，可用于验证 agent 闭环：

# 先确认测试失败
uv run pytest tests/fixtures/sample_repo -q

# 让 agent 修复（需要有效模型密钥）
uv run synapse run "修复 calculator.sub 的 bug，使 tests 全部通过" -w tests/fixtures/sample_repo

环境变量参考

关键 Agent 行为变量：

安全说明

• 不使用 sandbox：命令在宿主机执行。
• 默认不审批；仅建议在受信开发机使用。
• 可用 --require-approval 临时打开 HITL。
• safety.py 提供危险命令黑名单（警告/检测用）；默认不拦截 agent 内置 execute。
• --readonly / AGENT_READONLY=true 通过 harness 排除 execute/write_file/edit_file。

开发

uv run pytest
uv run ruff check src tests

项目结构

src/synapse/
  agent.py           # create_deep_agent 装配
  backends.py        # LocalShellBackend
  cli.py             # typer CLI
  config.py          # pydantic-settings
  models_registry.py # 多模型目录
  mcp_client.py      # MCP → tools
  sessions.py        # 会话元数据
  subagents.py       # 默认子代理
  harness.py         # excluded_tools
  fs_permissions.py  # FilesystemPermission
  prompts.py
  safety.py
  tools/             # session tools
  ui/                # stream + TUI
docs/design.md
skills/              # agent skills
examples/            # models/mcp 配置样例
AGENTS.md

设计文档

更完整的架构与分期说明见 docs/design.md。