synapse

Name: synapse
Author: akillness

github.com/akillnessAgent 工作流136 次安装39 周前更新

代码仓库

关于 synapse

Synapse 是用于编排多个 AI Agent 的技能，面向需要将规划、分析、代码生成与执行组合起来的开发者。它基于 Claude、Gemini 和 Codex 的分工，支持并行、流水线及 swarm 工作流。

主要功能

01按角色分配 Claude、Gemini 和 Codex
02生成任务计划与代码
03分析内容并审查代码
04通过 Codex 执行命令
05支持并行、流水线和 swarm 工作流
06按任务配置服务与模型

适用场景

01将复杂开发任务拆分为多个步骤
02对大型代码库进行分析
03并行开展安全与性能审查
04运行构建、测试及自动化命令

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/akillness/synapse-skill --skill synapse

安装后在 Claude Code 中输入/synapse确认已加载。

附带文件README.md

详细介绍

Synapse AI Agent 编排技能

Synapse 是一个分布式 AI Agent 系统，可通过可配置的模型和基于角色的工作流来编排三项专用服务。

Agent 角色

Agent	角色	能力	默认模型
Claude	编排者/规划者	任务规划、架构设计、代码生成	claude-sonnet-4.5
Gemini	分析者/审查者	大上下文分析（>1M 个 token）、代码审查、安全审计	gemini-3-pro-preview
Codex	执行者	命令执行、构建流程、自动化测试	gpt-5.2

适用场景

在以下情况下使用此技能：

将复杂任务拆解为可执行的多步骤计划
根据描述或规范生成实现代码
分析大型代码库或内容（尤其是通过 Gemini 分析 >200k 个 token 的内容）
获取带质量评分的全面代码审查
运行沙箱化的 Shell 命令以执行构建、测试或自动化操作
执行完整的计划-分析-编码-审查-执行工作流
编排并行或流水线式的多 Agent 工作流

以下情况请勿使用：

不需要生成代码的简单问题
只需执行本地文件操作的任务
Docker/Synapse 服务不可用时

前提条件

Docker 必须正在运行，且 Synapse 服务处于活动状态。

# Clone Synapse (if not already)
git clone https://github.com/akillness/Synapse.git ~/Synapse
cd ~/Synapse

# Start services
docker compose up -d

# Verify all services are healthy
curl -s http://localhost:8000/health
# Expected: {"status": "healthy", "service": "gateway"}

安装

全局安装（推荐）

# Clone synapse-skill
git clone https://github.com/akillness/synapse-skill.git

# For OpenCode
ln -s $(pwd)/synapse-skill ~/.config/opencode/skills/synapse

# For Claude Code / Other Agents
mkdir -p ~/.agents/skills
ln -s $(pwd)/synapse-skill ~/.agents/skills/synapse

环境变量（可选）

# Custom Synapse location
export SYNAPSE_HOME="$HOME/Synapse"

# Gateway URL (default: http://localhost:8000)
export SYNAPSE_GATEWAY_URL="http://localhost:8000"

用于 Cursor IDE

在项目中创建 .cursor/rules/synapse.mdc：

---
description: Synapse AI Agent Orchestration
globs: ["**/*"]
alwaysApply: true
---

# Synapse Skill Integration

When orchestrating multi-agent tasks, use Synapse endpoints:
- Plan: POST http://localhost:8000/api/v1/claude/plan
- Code: POST http://localhost:8000/api/v1/claude/code
- Analyze: POST http://localhost:8000/api/v1/gemini/analyze
- Review: POST http://localhost:8000/api/v1/gemini/review
- Execute: POST http://localhost:8000/api/v1/codex/execute

Use @planner for task breakdown, @reviewer for code review.

用于 Claude Code（CLAUDE.md）

添加到你的 ~/.claude/CLAUDE.md：

## Synapse Integration

For multi-agent orchestration, use Synapse skill:
- Health check: curl http://localhost:8000/health
- Ensure Docker containers are running: docker ps | grep synaps
- Use /api/v1/workflow for full pipeline execution

用于 OpenCode（oh-my-opencode.json）

将 Synapse 优化的 Agent 配置添加到 ~/.config/opencode/oh-my-opencode.json：

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "synapse-planner": {
      "model": "google/antigravity-claude-sonnet-4-5"
    },
    "synapse-analyst": {
      "model": "google/antigravity-gemini-3-pro-high"
    },
    "synapse-coder": {
      "model": "google/antigravity-claude-sonnet-4-5-thinking"
    },
    "synapse-reviewer": {
      "model": "google/antigravity-gemini-3-pro-high"
    },
    "synapse-executor": {
      "model": "openai/gpt-5.2-codex-high"
    }
  }
}

OpenCode 模型提供方配置

如需自定义 Synapse 模型，将以下内容添加到 ~/.config/opencode/opencode.json：

{
  "provider": {
    "synapse": {
      "name": "Synapse Local",
      "api": "openai",
      "options": {
        "baseURL": "http://localhost:8000/api/v1/"
      },
      "models": {
        "claude-planner": {
          "name": "Claude Planner (Synapse)",
          "limit": { "context": 200000, "output": 64000 }
        },
        "gemini-analyst": {
          "name": "Gemini Analyst (Synapse)",
          "limit": { "context": 1000000, "output": 65536 }
        },
        "codex-executor": {
          "name": "Codex Executor (Synapse)",
          "limit": { "context": 272000, "output": 128000 }
        }
      }
    }
  }
}

OpenCode 技能集成

将技能符号链接到 ~/.config/opencode/skills/synapse 后，系统会自动加载。

OpenCode 的触发短语：

“orchestrate agents” → 激活 Synapse 工作流
“multi-agent workflow” → 启动并行或流水线执行
“run synapse” → 执行完整工作流

模型配置

Claude 服务模型（2026）

模型	API ID	最适用于	上下文	成本（输入/输出）
`claude-opus-4.5`	`claude-opus-4-5-20251101`	复杂推理、生产级代码、高级 Agent	200K	每百万 token $5/$25
`claude-sonnet-4.5`	`claude-sonnet-4-5-20250929`	任务规划、代码生成、架构设计（推荐）	1M	每百万 token $3/$15
`claude-haiku-4.5`	`claude-haiku-4-5-20251201`	快速响应、简单任务，性能达到 Sonnet 的 90%	200K	每百万 token $0.80/$4

Claude 4.5 亮点：

Opus 4.5：业界领先的编码能力（SWE-bench 得分超过 80%），最适合 Agent 和计算机操作
Sonnet 4.5：上下文窗口扩展至 1M 个 token（提升 5 倍），支持扩展思考模式
Haiku 4.5：成本效益高，性能达到 Sonnet 的 90%

Gemini 服务模型（2026）

模型	最适用于	上下文	成本
`gemini-3-pro-preview`	复杂推理、编码、Agent 任务（SWE-bench 得分 76.2%）	1M	每百万 token $2-4
`gemini-3-flash`	亚秒级延迟、对速度要求高的场景，由 3 Pro 蒸馏而来	1M	更低
`gemini-2.5-pro`	大上下文分析、代码审查、成熟稳定	1M	每百万 token $1.25
`gemini-2.5-flash`	成本高效，适合高用量场景（输入每百万 token $0.15）	1M	每百万 token $0.15

Gemini 3 亮点：

软件工程任务表现比 2.5 Pro 高 35%
支持用于快速原型设计的“氛围编码”
知识截止时间：2025 年 1 月

Codex 服务模型

模型	最适合	上下文	费用
`gpt-5.2`	软件工程、Agent 工作流	400K	$1.25/$10
`gpt-5.2-mini`	高性价比编码（用量提升 4 倍）	400K	$0.25/$2
`gpt-5.1-thinking`	超复杂推理	400K	更高

Agent 工作流模式

模式 1：并行专家

多个专家同时审查代码：

┌─────────────────────────────────────────────────────┐
│                    ORCHESTRATOR                      │
│                   (You / Claude)                     │
└────────────┬───────────┬───────────┬────────────────┘
             │           │           │
     ┌───────▼───┐ ┌─────▼─────┐ ┌───▼───────┐
     │ Security  │ │Performance│ │ Simplicity│
     │ Reviewer  │ │ Reviewer  │ │ Reviewer  │
     │ (Gemini)  │ │ (Gemini)  │ │ (Gemini)  │
     └───────────┘ └───────────┘ └───────────┘

工作流：

# 1. Spawn parallel reviews
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "<code>", "language": "python", "review_type": "security"}'

curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "<code>", "language": "python", "review_type": "performance"}'

curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "<code>", "language": "python", "review_type": "simplicity"}'

# 2. Aggregate results and synthesize

模式 2：流水线（顺序依赖）

每个阶段都依赖于前一阶段：

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Research │───▶│   Plan   │───▶│Implement │───▶│   Test   │───▶│  Review  │
│ (Gemini) │    │ (Claude) │    │ (Claude) │    │ (Codex)  │    │ (Gemini) │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘

工作流：

# Step 1: Research (Gemini analyzes requirements)
RESEARCH=$(curl -X POST http://localhost:8000/api/v1/gemini/analyze \
  -d '{"content": "<requirements>", "analysis_type": "documentation"}')

# Step 2: Plan (Claude creates implementation plan)
PLAN=$(curl -X POST http://localhost:8000/api/v1/claude/plan \
  -d "{\"task\": \"Implement based on: $RESEARCH\", \"constraints\": [\"python\", \"tests\"]}")

# Step 3: Implement (Claude generates code)
CODE=$(curl -X POST http://localhost:8000/api/v1/claude/code \
  -d "{\"description\": \"$PLAN\", \"language\": \"python\"}")

# Step 4: Test (Codex executes tests)
TEST=$(curl -X POST http://localhost:8000/api/v1/codex/execute \
  -d '{"command": "python -m pytest tests/", "timeout": 60}')

# Step 5: Review (Gemini reviews final code)
REVIEW=$(curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d "{\"code\": \"$CODE\", \"language\": \"python\"}")

模式 3：蜂群（自主组织）

工作者从任务池中领取可用任务：

                    ┌─────────────┐
                    │  Task Pool  │
                    │ ┌─┬─┬─┬─┬─┐ │
                    │ │1│2│3│4│5│ │
                    │ └─┴─┴─┴─┴─┘ │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           │               │               │
     ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
     │  Worker 1 │   │  Worker 2 │   │  Worker 3 │
     │  (Claude) │   │  (Gemini) │   │  (Codex)  │
     │ claims #1 │   │ claims #2 │   │ claims #3 │
     └───────────┘   └───────────┘   └───────────┘

工作流：

# Create task pool via workflow endpoint
curl -X POST http://localhost:8000/api/v1/workflow \
  -d '{
    "task": "Review all files in src/",
    "mode": "swarm",
    "workers": 3,
    "constraints": ["parallel", "auto-assign"]
  }'

模式 4：完整工作流（端到端）

使用工作流端点实现自动编排：

curl -X POST http://localhost:8000/api/v1/workflow \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Build a user authentication module",
    "constraints": ["FastAPI", "JWT", "PostgreSQL"],
    "workflow_type": "pipeline",
    "model_config": {
      "planner": "claude-sonnet-4",
      "analyst": "gemini-2.5-pro",
      "coder": "claude-sonnet-4",
      "executor": "gpt-5.2"
    }
  }'

基于角色分配模型

配置架构

{
  "roles": {
    "planner": {
      "service": "claude",
      "model": "claude-sonnet-4.5",
      "description": "Creates task plans and architecture designs"
    },
    "analyst": {
      "service": "gemini",
      "model": "gemini-3-pro-preview",
      "description": "Analyzes content and performs code reviews"
    },
    "coder": {
      "service": "claude",
      "model": "claude-sonnet-4.5",
      "description": "Generates implementation code"
    },
    "reviewer": {
      "service": "gemini",
      "model": "gemini-3-pro-preview",
      "description": "Performs comprehensive code reviews"
    },
    "executor": {
      "service": "codex",
      "model": "gpt-5.2",
      "description": "Executes commands and runs tests"
    }
  }
}

按任务类型选择角色

任务类型	主要角色	模型	端点
任务拆解	规划者	claude-sonnet-4	`/api/v1/claude/plan`
代码生成	编码者	claude-sonnet-4	`/api/v1/claude/code`
大上下文分析	分析者	gemini-2.5-pro	`/api/v1/gemini/analyze`
安全审查	审查者	gemini-3-pro-preview	`/api/v1/gemini/review`
构建与测试	执行者	gpt-5.2	`/api/v1/codex/execute`

API 参考

基础 URL

http://localhost:8000

端点摘要

服务	方法	端点	用途
系统	GET	`/health`	网关健康检查
系统	GET	`/metrics`	池和负载均衡器统计信息
Claude	GET	`/api/v1/claude/health`	服务健康状态
Claude	POST	`/api/v1/claude/plan`	创建任务计划
Claude	POST	`/api/v1/claude/code`	生成代码
Gemini	GET	`/api/v1/gemini/health`	服务健康状态
Gemini	POST	`/api/v1/gemini/analyze`	分析内容
Gemini	POST	`/api/v1/gemini/review`	审查代码
Codex	GET	`/api/v1/codex/health`	服务健康状态
Codex	POST	`/api/v1/codex/execute`	执行命令
工作流	POST	`/api/v1/workflow`	完整流水线

快速参考

用例	服务	端点	关键字段
拆解任务	Claude	`/api/v1/claude/plan`	`task`、`constraints`、`model`
生成代码	Claude	`/api/v1/claude/code`	`description`、`language`、`model`
分析代码库	Gemini	`/api/v1/gemini/analyze`	`content`、`analysis_type`、`model`
代码审查	Gemini	`/api/v1/gemini/review`	`code`、`language`、`review_type`、`model`
运行命令	Codex	`/api/v1/codex/execute`	`command`、`timeout`、`model`
完整流水线	工作流	`/api/v1/workflow`	`task`、`constraints`、`workflow_type`、`model_config`

运行任务

1. 健康检查（始终从这里开始）

# Check all services
curl -s http://localhost:8000/api/v1/claude/health
curl -s http://localhost:8000/api/v1/gemini/health
curl -s http://localhost:8000/api/v1/codex/health

预期响应：

{"status": "SERVING", "version": "1.0.0", "uptime_seconds": 123}

2. 创建计划（Claude）

curl -X POST http://localhost:8000/api/v1/claude/plan \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Build a REST API with authentication",
    "constraints": ["use FastAPI", "JWT tokens", "PostgreSQL"],
    "model": "claude-sonnet-4"
  }'

3. 生成代码（Claude）

curl -X POST http://localhost:8000/api/v1/claude/code \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A function to validate email addresses using regex",
    "language": "python",
    "model": "claude-sonnet-4"
  }'

4. 分析内容（Gemini）

curl -X POST http://localhost:8000/api/v1/gemini/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<large_codebase_content>",
    "analysis_type": "code",
    "model": "gemini-2.5-pro"
  }'

5. 审查代码（Gemini）

curl -X POST http://localhost:8000/api/v1/gemini/review \
  -H "Content-Type: application/json" \
  -d '{
    "code": "def add(a, b):\n    return a + b",
    "language": "python",
    "review_type": "comprehensive",
    "model": "gemini-3-pro-preview"
  }'

6. 执行命令（Codex）

curl -X POST http://localhost:8000/api/v1/codex/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python -m pytest tests/",
    "working_dir": "/tmp",
    "timeout": 60,
    "model": "gpt-5.2"
  }'

允许的命令： echo、ls、pwd、date、cat、head、tail、wc、grep、find、python、pip、npm、node、git、make

常见工作流

代码开发工作流

# 1. Create plan
curl -X POST http://localhost:8000/api/v1/claude/plan \
  -H "Content-Type: application/json" \
  -d '{"task": "Implement user authentication", "model": "claude-sonnet-4"}'

# 2. Generate code
curl -X POST http://localhost:8000/api/v1/claude/code \
  -H "Content-Type: application/json" \
  -d '{"description": "JWT authentication middleware", "language": "python"}'

# 3. Review code
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -H "Content-Type: application/json" \
  -d '{"code": "<generated_code>", "language": "python", "model": "gemini-3-pro-preview"}'

# 4. Run tests
curl -X POST http://localhost:8000/api/v1/codex/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "python -m pytest tests/", "timeout": 60}'

代码分析工作流

# 1. Read file content
FILE_CONTENT=$(cat myfile.py | jq -Rs .)

# 2. Analyze with large context model
curl -X POST http://localhost:8000/api/v1/gemini/analyze \
  -H "Content-Type: application/json" \
  -d "{\"content\": $FILE_CONTENT, \"analysis_type\": \"code\", \"model\": \"gemini-2.5-pro\"}"

# 3. Review with detailed model
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -H "Content-Type: application/json" \
  -d "{\"code\": $FILE_CONTENT, \"language\": \"python\", \"model\": \"gemini-3-pro-preview\"}"

错误处理

服务不可用（503）

{"detail": "Service not ready"}

解决方案： 检查 Docker 容器是否正在运行：

docker ps | grep synaps

连接被拒绝

解决方案： 启动 Synapse 服务：

cd ~/Synapse  # or $SYNAPSE_HOME
docker compose up -d

命令不允许（Codex）

{"success": false, "stderr": "Command not allowed"}

解决方案： 仅使用允许的命令（echo、ls、pwd、python 等）

故障排除

检查服务状态

# All containers running?
docker ps --format "table {{.Names}}\t{{.Status}}" | grep synaps

# Gateway health
curl -s http://localhost:8000/health

# Individual service health
curl -s http://localhost:8000/api/v1/claude/health
curl -s http://localhost:8000/api/v1/gemini/health
curl -s http://localhost:8000/api/v1/codex/health

重启服务

cd ~/Synapse  # or $SYNAPSE_HOME
docker compose down
docker compose up -d

查看日志

docker logs synaps-gateway
docker logs synaps-claude
docker logs synaps-gemini
docker logs synaps-codex

服务端口

服务	端口	协议
Gateway	8000	HTTP/REST
Claude	5011	gRPC
Gemini	5012	gRPC
Codex	5013	gRPC
Prometheus	9090	HTTP
Grafana	3000	HTTP

与 AI Agent 集成

任何支持 HTTP 请求的 AI 编码 Agent 都可以使用此技能：

OpenCode/Claude Code：使用 Bash 工具执行 curl 命令
Cursor：使用终端或 HTTP 客户端扩展
GitHub Copilot：在终端中使用内联 curl
Windsurf：使用内置终端

Agent 集成示例

User: "Create a plan to build a web scraper"

Agent uses Synapse skill:
1. curl POST /api/v1/claude/plan with task and model config
2. Parse response and present steps to user
3. Offer to generate code for each step
4. Execute tests via Codex
5. Review final code via Gemini

Swarm 模式集成

对于复杂的多文件任务，请使用 swarm 编排：

User: "Review all authentication files for security issues"

Agent orchestrates:
1. Spawn parallel Gemini reviewers for each file
2. Aggregate findings
3. Generate summary report
4. Propose fixes via Claude

当前状态（v2.3.0）

服务健康状况（已于 2026-01-28 验证）

服务	端点	状态	响应
Gateway	`/health`	✅ 健康	`{"status": "healthy"}`
Claude	`/api/v1/claude/plan`	✅ 成功	已生成 5 步计划
Gemini	`/api/v1/gemini/analyze`	✅ 成功	代码分析完成
Gemini	`/api/v1/gemini/review`	✅ 成功	得分 95/100
Codex	`/api/v1/codex/execute`	✅ 成功	命令已执行

连接池指标

Claude Pool          Gemini Pool          Codex Pool
┌────────────┐       ┌────────────┐       ┌────────────┐
│ Size: 2    │       │ Size: 2    │       │ Size: 2    │
│ Avail: 2   │       │ Avail: 2   │       │ Avail: 2   │
│ Acquired:3 │       │ Acquired:4 │       │ Acquired:3 │
│ Released:3 │       │ Released:4 │       │ Released:3 │
└────────────┘       └────────────┘       └────────────┘

Load Balancer Status: All endpoints healthy (1/1 each)
Avg Response Time (Claude): 21.47ms

架构概览

┌─────────────────────────────────────────────────────────────────────────────┐
│                         SYNAPSE WORKFLOW ARCHITECTURE                        │
└─────────────────────────────────────────────────────────────────────────────┘

                            ┌──────────────┐
                            │   Gateway    │ :8000
                            │   (REST)     │
                            └──────┬───────┘
                                   │
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
            ▼                      ▼                      ▼
   ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
   │     Claude     │    │     Gemini     │    │     Codex      │
   │     :5011      │    │     :5012      │    │     :5013      │
   │    (gRPC)      │    │    (gRPC)      │    │    (gRPC)      │
   └────────────────┘    └────────────────┘    └────────────────┘
          │                      │                      │
          ▼                      ▼                      ▼
   ┌────────────┐         ┌────────────┐         ┌────────────┐
   │   /plan    │         │  /analyze  │         │  /execute  │
   │   /code    │         │  /review   │         │            │
   └────────────┘         └────────────┘         └────────────┘

改进路线图

1. 统一工作流端点增强

当前：需要单独调用各项服务

curl /api/v1/claude/plan → curl /api/v1/claude/code → curl /api/v1/gemini/review → curl /api/v1/codex/execute

计划：通过 workflow_type 参数执行单次工作流调用

curl /api/v1/workflow -d '{"task": "...", "workflow_type": "pipeline|parallel|swarm"}'

2. MCP 工具直接集成

当前：通过 Bash 工具使用基于 curl 的访问方式

Bash → curl → Gateway → Service

计划：原生 MCP 服务工具

mcp__synapse__plan → Gateway → Claude
mcp__synapse__analyze → Gateway → Gemini
mcp__synapse__execute → Gateway → Codex

3. 增强错误处理

当前：简单错误响应

{"detail": "Service not ready"}

计划：提供包含重试指导的详细错误信息

{
  "error": "Service not ready",
  "retry_after": 5,
  "fallback_available": true,
  "fallback_service": "gemini-2.5-flash"
}

4. 支持 SSE 流式响应

当前：等待完整响应

response = await service.plan(request)  # Waits for completion

计划：实时进度流式传输

async for chunk in service.plan_stream(request):
    yield chunk  # Real-time progress updates

5. Redis 缓存层

计划架构：

              Request
                 │
                 ▼
          ┌─────────────┐     Cache Hit      ┌─────────────┐
          │   Gateway   │ ─────────────────▶ │    Redis    │
          └──────┬──────┘                    └─────────────┘
                 │ Cache Miss
                 ▼
          ┌─────────────┐
          │   Service   │
          └─────────────┘

6. 快捷命令（计划中）

# Shorthand commands for common operations
synapse plan "Build REST API"     # → Claude Plan
synapse review "def foo(): ..."   # → Gemini Review
synapse run "pytest tests/"       # → Codex Execute
synapse flow "Create feature X"   # → Full Pipeline

7. 自动检测服务

计划功能：

激活技能时检查 Docker 容器状态
自动提示重启不健康的服务
验证服务依赖关系

支持 Markdown

登录后评论

基本信息

作者: akillness
仓库: akillness/synapse-skill
分类: Agent 工作流
安装次数: 36
GitHub Stars: 1

报告问题