synapse-a2a

Synapse A2A 通信

通过 Google A2A Protocol 实现的智能体间通信框架。

工作树规范（子智能体请先阅读）

绝不要 cd 进入 .synapse/worktrees/<name>/ 目录。

子智能体（Claude Code Agent 工具、Codex 子进程，以及父会话驱动的任何其他 子进程）会继承父会话的持久 shell。在子智能体运行期间随意 cd 进入工作树，会导致父会话的工作目录被悄悄更改——git status、 git diff，甚至 git commit 随后都会在错误的工作树中执行，浪费调试时间， 还可能将提交错误地提交到其他分支。

使用 .synapse/worktrees/ 时请遵守以下规则：

• 绝不要 cd 进入工作树。整个会话期间都留在原始工作目录中。
• 使用绝对路径读取和写入工作树中的文件 （例如 Read /Volumes/.../.synapse/worktrees/foo/src/bar.py， 而不是 cd .synapse/worktrees/foo && cat src/bar.py）。
• 使用 git -C /abs/path/to/worktree ... 对工作树运行 git， 而不要切换目录。
• 工作树由 Synapse 管理（synapse spawn --worktree、 synapse team start --worktree）。请将其视为读写数据区，而不是工作目录。

如果需要在工作树内部执行操作（例如在那里运行 pytest），请使用 synapse spawn --worktree 为其启动专用 Agent，而不要更改父 shell 的目录。

快速参考

任务	命令
列出 Agent	面向人类使用 synapse list（自动刷新，可交互：方向键/1-9 选择，Enter 跳转，k 终止，/ 筛选）。面向 AI/脚本，请使用 synapse list --json、synapse list --plain 或 MCP list_agents
Agent 详情	synapse status <target> [--json]
卡住的 Agent 监视器（阶段 1）	synapse watchdog check [--alarm-only] [--json]（单次启发式扫描；#646）
发送消息	synapse send <target> "<msg>"（默认：--notify；自动检测 --from）
广播	synapse broadcast "<msg>"
等待回复	synapse send <target> "<msg>" --wait
即发即弃	synapse send <target> "<msg>" --silent
回复	synapse reply "<response>"
回复特定对象	synapse reply "<response>" --to <sender_id>
回复并报告失败	synapse reply --fail "<reason>"
中断（优先级 4）	synapse interrupt <target> "<msg>"
向 PTY 发送按键（TUI 对话框的应急处理；#695）	synapse send-keys <target> <keys>（例如，向 codex 发送 a 表示“不要再询问”，发送 \r 表示 Enter；绕过 A2A——当 Agent 卡在交互式对话框中且无法使用 synapse jump 时使用）
启动 Agent	synapse spawn <type> --name <n> --role "<r>" -- <tool-specific-automation-args>
启动并发送首个任务（委派时优先使用）	synapse spawn <type> --name <n> --role "<r>" --task-file <path> --task-timeout 600 --notify
使用工作树启动	synapse spawn <type> --worktree --name <n> --role "<r>" -- <tool-specific-automation-args>
启动团队	synapse team start <homogeneous-profiles...> [--worktree] -- <tool-specific-automation-args>
批准计划	synapse approve <id>
拒绝计划	synapse reject <id> --reason "<feedback>"
保存知识	synapse memory save <key> "<content>" --tags <t> --notify
搜索知识	synapse memory search "<query>"
锁定文件	synapse file-safety lock <file> <agent_id> --intent "..."
检查锁	synapse file-safety locks
任务历史	synapse history list --agent <name>
终止 Agent	synapse kill <name> -f
清理孤立进程	synapse cleanup --dry-run（列出）；synapse cleanup -f（终止所有父进程已崩溃/清除的孤立进程）
附加文件	synapse send <target> "<msg>" --attach <file> --wait
已保存的 Agent	synapse agents list / synapse agents set <profile> / synapse agents unset <profile> / synapse agents roles / synapse spawn <agent_id>；运行中的 Agent 会将 agent_definition_id 暴露为稳定的目标别名
共享会话移交	使用 SYNAPSE_SHARED_SESSION_DIR 执行 synapse session publish <name> / synapse session import <name>
发布到 Canvas	synapse canvas post <format> "<body>" --title "<title>"
链接预览	synapse canvas link "<url>" --title "<title>"
发布模板	synapse canvas briefing '<json>' --title "<title>"
发布计划卡片	synapse canvas plan '<json>' --title "<title>"（Mermaid DAG + 带状态跟踪的步骤列表）
打开 Canvas	synapse canvas open（自动启动服务并打开浏览器）
重启 Canvas	synapse canvas restart（停止并启动；升级后若 canvas status 报告 ⚠ STALE，请使用此命令）
同步工作流技能	synapse workflow sync（从工作流 YAML 重新生成技能并移除孤立项）
运行工作流（自动启动）	synapse workflow run <name> --auto-spawn（支持使用 depends_on 和 condition 的 DAG 步骤）
多 Agent 模式	synapse map init/list/show/run/status/stop（内置模式：generator-verifier、orchestrator-subagent、agent-teams、message-bus、shared-state）
导入 Wiki	synapse wiki ingest <source> [--scope project|global]（将源文件导入 Wiki）
查询 Wiki	synapse wiki query "<question>" [--scope project|global]（搜索 Wiki 页面）
检查 Wiki	synapse wiki lint [--scope project|global]（验证 Wiki 一致性）
Wiki 状态	synapse wiki status [--scope project|global]（显示 Wiki 索引统计信息）

协作决策框架

开始工作前，评估协作机会：

情况	操作
属于你职责范围内的小任务	自行完成
任务不属于你的职责范围，且有 READY Agent	委派：synapse send --notify 或 --silent
没有合适的 Agent，需要委派任务	在一条命令中启动并分配任务：synapse spawn <type> --name <n> --role "<r>" --task-file <spec.md> --task-timeout 600 --notify。此命令会启动 Agent、等待 READY 并发送首个任务，无需手动轮询就绪状态。
需要一个空白 Agent（没有初始任务）	synapse spawn <type> --name <n> --role "<r>"（稍后通过 synapse send 发送任务）
遇到阻碍或需要专业知识	询问：synapse send <target> "<question>" --wait
完成一个里程碑	汇报：synapse send <manager> "<summary>" --silent
发现一种模式	分享：synapse memory save <key> "<pattern>" --tags ... --notify

推荐的协作检查点（3 个以上阶段或需要修改 10 个以上文件）： 在着手大型工作前，考虑以下步骤：

1. synapse list --json 或 MCP list_agents——检查可用的 Agent
2. synapse memory search "<topic>"——检查是否有人已解决此问题
3. 在委派有益时，制定 Agent 分配计划（阶段 / Agent / 原因）
4. 按需启动专业 Agent（优先选择不同的模型类型，以增加多样性）

对于开销大于收益的小型或中型任务，可跳过此检查点。

积极使用 Synapse 功能

功能	重要性	命令
共享记忆	集体知识在 Agent 重启后仍然保留	synapse memory save/search/list
文件安全	锁定可防止两个 Agent 编辑同一文件时丢失数据——在 worktree 内请跳过（SYNAPSE_WORKTREE_PATH）	synapse file-safety lock/unlock/locks
Worktree	文件隔离可消除并行编辑时的合并冲突	synapse spawn --worktree
广播	面向团队的公告可即时送达所有 Agent	synapse broadcast "<msg>"
历史记录	审计跟踪记录事件及其发生时间	synapse history list/show/stats
概率式回忆	根据近期程度、重要性和关键词重合度，回忆相关的过往任务观察记录，而无需倾倒全部历史记录	HistoryManager.recall_observations
计划审批	通过门控执行，在采取行动前确保质量	synapse approve/reject
画布	用于共享内容丰富的卡片和模板（简报、比较、仪表板、步骤、幻灯片、计划）的可视化仪表板；可通过浏览器按钮或 GET /api/cards/{card_id}/download 将卡片下载为 Markdown、JSON、CSV 或原生格式	synapse canvas post/link/briefing/plan/open/list/restart
Agent 控制	通过 Canvas #/admin 视图在浏览器中管理 Agent（选择 Agent、发送消息、查看响应；双击 Agent 行可跳转到终端）	synapse canvas open → 导航至 #/admin
工作流视图	通过 Canvas #/workflow 视图在浏览器中管理工作流（列出工作流、检查步骤、创建／编辑／删除／导入／导出工作流 YAML、触发运行、通过实时 SSE 更新监控进度；运行历史记录会持久化到 SQLite，即使重启也会保留）	synapse canvas open → 导航至 #/workflow
Harnesses 视图	在 Canvas #/harnesses 中通过浏览器查看 Agent harness 资源——子视图包括 #/harnesses/skills（跨用户／项目／synapse／插件范围的 SKILL.md 清单，按当前项目根目录扫描）和 #/harnesses/mcp（当前根目录下项目 .mcp.json 中的 MCP 服务配置，以及用户范围配置：Claude Code ~/.claude.json、Codex ~/.codex/config.toml、Gemini ~/.gemini/settings.json、OpenCode ~/.config/opencode/opencode.json 和 Claude Desktop 配置）	synapse canvas open → 导航至 #/harnesses
计划卡片	Mermaid DAG + 步骤列表，可视化依赖关系	synapse canvas plan
LLM Wiki	用于摄取、查询和验证项目／全局文档的结构化知识库	synapse wiki ingest/query/lint/status
智能建议	用于分析提示词并为大型任务建议团队／任务拆分的 MCP 工具	MCP 工具：analyze_task
项目经验	已保存的定义可在启动时从 .synapse/learnings/<agent_definition_id>.md 加载适应项目的经验	synapse agents set + Markdown 经验
主动模式	基于任务规模的功能使用指南（SYNAPSE_PROACTIVE_MODE_ENABLED=true）	参见 references/features.md
MCP 引导	通过 MCP 资源向兼容的客户端分发说明（可选加入，包含通过仅工具模式使用 Copilot）。MCP 工具：bootstrap_agent、list_agents、analyze_task、canvas_post	synapse mcp serve / python -m synapse.mcp

何时使用 Canvas

当输出适合采用可视化结构，或之后还会被引用时，请使用 Canvas：

• 适合使用 Canvas： 图表、对比表、多步骤计划、设计文档、包含丰富格式的结果
• 不适合使用 Canvas： 简单的完成报告、单文件更改、快速状态更新（请改用 broadcast 或回复）

模板选择指南：

• briefing — 结构化报告、状态更新、发布摘要
• comparison — 前后对比、选项权衡、审查差异
• steps — 计划、迁移步骤、执行检查清单
• slides — 演练、演示、逐页叙述
• dashboard — 多组件运营快照、紧凑型状态看板
• plan — 带有 Mermaid 可视化和步骤跟踪的任务 DAG

单个内容块请使用原始命令 synapse canvas post <format>；多段内容请使用模板。

生成 Agent 决策表

⚠️ 同模型规则——请优先尝试子 Agent。 当 Claude Code Agent 需要另一个 Claude（或 codex Agent 需要另一个 codex）时，先使用进程内子 Agent（Claude 使用 Agent / Task 工具，Codex 使用子进程），然后再考虑使用 synapse spawn。在同一账户上生成同模型的 Agent 会共享速率限制窗口——这会消耗同一配额的双倍用量，而不是分散用量。仅当辅助 Agent 必须比父会话存续更久、需要子 Agent 无法提供的文件隔离，或承担独立的长期运行角色时，才使用同模型的 synapse spawn。

对于跨模型委派（Claude → codex / gemini）、不支持子 Agent 的 Agent（Gemini / OpenCode / Copilot），或需要持久运行的多任务辅助 Agent，synapse spawn 才是合适的工具。

默认生成策略： 使用 synapse spawn 时，请在 -- 后传入底层 CLI 专用的自动化参数，以便生成的 Agent 无人值守运行。大多数 CLI 使用跳过审批 / 自动批准标志；对于 OpenCode，请使用 --agent build 选择 build Agent 配置，并依靠 OpenCode 的权限配置处理审批行为。

对 synapse team start 应用相同规则：默认包含适当的转发 CLI 参数；如果这些参数因 CLI 而异，请确保团队使用同一种 CLI。

常见默认值（Synapse 已自动注入这些参数——如需退出自动批准，请传入 --no-auto-approve）：

• Claude Code：synapse spawn claude --name <n> --role "<r>" -- --permission-mode=auto
• Gemini CLI：synapse spawn gemini --name <n> --role "<r>" -- --approval-mode=yolo
• Codex CLI：synapse spawn codex --name <n> --role "<r>"（synapse 会注入 -cdefault_permissions=":workspace"；Codex 0.128+ 已移除 --full-auto）
• OpenCode：synapse spawn opencode --name <n> --role "<r>" -- --agent build（选择 build Agent 配置；不是跳过审批标志）
• Copilot CLI：synapse spawn copilot --name <n> --role "<r>" -- --allow-all
• Claude 团队：synapse team start claude claude -- --permission-mode=auto
• Gemini 团队：synapse team start gemini gemini -- --approval-mode=yolo
• Codex 团队：synapse team start codex codex（synapse 会注入 -cdefault_permissions=":workspace"）
• OpenCode 团队：synapse team start opencode opencode -- --agent build（选择 build Agent 配置；是否出现权限提示仍取决于 OpenCode 配置）
• Copilot 团队：synapse team start copilot copilot -- --allow-all

2026-04 迁移： Anthropic 弃用了 --dangerously-skip-permissions，改用 --permission-mode=auto（使用安全分类器，而非禁用所有检查）。Gemini 同样建议使用 --approval-mode=yolo，而不是旧版 --yolo / -y 短格式。Synapse 现在默认注入新标志；旧格式仍然可用，并保留在各配置文件的 alternative_flags 中。 | 条件 | 操作 | |-----------|--------| | 现有的 READY Agent 可以处理 | synapse send — 复用更快（可避免启动开销） | | 需要同模型的辅助 Agent（Claude → claude，Codex → codex） | 优先使用进程内子 Agent（Claude 使用 Agent/Task 工具，Codex 使用子进程）。synapse spawn 同模型 Agent 会共享速率限制窗口。 | | 需要并行执行 | 使用 synapse spawn，并添加 --worktree -- <tool-specific-automation-args>，以隔离文件（优先选择跨模型） | | 任务需要发挥另一种模型的优势 | 使用 synapse spawn 启动不同类型的 Agent（Claude 可启动 Gemini / Codex 等） | | 用户指定了 Agent 数量 | 严格遵照指定数量 | | 单个目标明确的子任务 | 子 Agent（同模型）或 synapse spawn（跨模型） | | N 个互相独立的子任务 | 同模型扇出时使用子 Agent，跨模型时使用 synapse spawn |

启动生命周期（首选，单条命令）：synapse spawn --task-file ... --task-timeout 600 --notify → 等待 A2A 完成通知 → 评估结果 → synapse kill <name> -f → 在 synapse list --json 中确认

旧版生命周期（仅在启动与首次任务之间需要控制时使用）：启动 → 轮询 synapse list --json 或 synapse status <target> --json，直到状态为 READY（等待数分钟；默认 30s 超时时间对大多数配置文件来说太短）→ synapse send --notify → 评估 → synapse kill -f → 确认清理完成。

⚠️ 常见问题： 向尚未处于 READY 状态的 Agent 发送任务，要么会在 HTTP 层挂起，要么会阻塞在内部就绪等待上。请使用 synapse spawn --task-file（首选，它会为你处理就绪状态），或在调用 synapse send 前明确确认 "status": "READY"。不要以为 30 秒就够了——大多数配置文件需要 1-5 分钟。

Agent 状态集（synapse list --json .status）：

状态	含义	操作
READY	空闲，可接受新任务	synapse send
SENDING_REPLY	正在临时发送外发的 A2A send/reply POST	等待；POST 完成后会恢复先前状态
PROCESSING	正在执行任务	等待，或在卡住时使用 synapse interrupt
WAITING	正在等待权限/审批提示	synapse approve / synapse reject
WAITING_FOR_INPUT	任务已暂停，正在请求非权限类输入（#538）	使用答案执行 synapse reply <task_id>
RATE_LIMITED	上一个任务因 LLM 提供商的速率限制而失败（#561）	等待提供商的限流窗口重置，然后重新发送
DONE	任务完成；约 10s 后降级为 READY	读取结果，然后继续
SHUTTING_DOWN	Agent 正在退出	不要发送任务

卡在 CLI 对话框中（不是 A2A WAITING）？ 如果 Agent 看似空闲，实际却 卡在自身的 TUI 提示中（codex 编辑确认、模型选择器、 速率限制对话框），请使用 synapse send-keys <target> <keys> 直接向 PTY 写入按键，而不使用 synapse jump。例如，synapse send-keys Impl a 会发送 codex 的“不再询问”快捷键。（#695）

任务完成后终止已启动的 Agent，可以释放端口、内存和 PTY 会话， 并防止孤立的 Agent 意外接受后续任务。

# Preferred: one-command spawn + delegate (handles readiness wait internally)
synapse spawn gemini \
    --name Tester \
    --role "test writer" \
    --task-file /tmp/test-spec.md \
    --task-timeout 600 \
    --notify
# (do other work; receive async A2A notification when Tester finishes)
# Evaluate result, then cleanup
synapse kill Tester -f
synapse list --json                       # Verify cleanup (AI-safe)

如果 synapse kill 失败，或者 Agent 仍出现在 synapse list --json 中，请使用 -f 重试， 检查 Agent 状态/日志，并报告清理失败，而不要留下 孤立的 Agent。

响应模式指南

根据是否需要结果进行选择：

模式	标志	使用场景
等待	--wait	继续之前需要得到答案（问题、审查）
通知	--notify（默认）	异步执行 — 完成后会收到通知
静默	--silent	仅委派、不等待响应（无需回复；发送者历史记录仍会在任务完成时尽力更新）

工作 Agent 指南

当你收到管理者分配的任务时：

收到任务时

1. 立即开始工作（对于已注册回复目标的 Synapse 跟踪消息，包括 [REPLY EXPECTED] 和 --response，可以使用 synapse reply；否则，用户粘贴的 A2A: 文本没有回复目标，因此请改用 synapse send 回复）
2. 检查共享知识：synapse memory search "<task topic>"
3. 编辑前锁定文件（如果设置了 SYNAPSE_WORKTREE_PATH，则跳过）：synapse file-safety lock <file> $SYNAPSE_AGENT_ID

工作期间

• 如果任务耗时超过 5 分钟，请报告进度：synapse send <manager> "Progress: <update>" --silent
• 立即报告阻碍：synapse send <manager> "<question>" --wait
• 保存发现：synapse memory save <key> "<finding>" --tags <topic>
• 也可以委派子任务——启动辅助 Agent（优先选择不同的模型类型）
• 务必清理启动的 Agent：synapse kill <name> -f

完成时

1. 向管理者报告：synapse send <manager> "Done: <summary>" --silent

失败时

1. 报告详情：synapse send <manager> "Failed: <error details>" --silent

相关技能

技能	用途
synapse-manager	多 Agent 编排工作流（委派、监控、验证）
synapse-reinst	在 /clear 或上下文重置后重新注入指令

参考资料

如需详细信息，请查阅以下参考文件：

参考文件	内容
references/commands.md	完整的 CLI 命令文档及所有选项
references/api.md	A2A 端点、就绪门控、错误处理
references/examples.md	多 Agent 工作流示例和模式
references/file-safety.md	文件锁定工作流和命令
references/messaging.md	发送、回复、优先级、状态、交互控件
references/spawning.md	启动生命周期、模式、工作树、权限、API
references/collaboration.md	Agent 命名、外部 Agent、身份验证、恢复、路径覆盖
references/features.md	会话、工作流、已保存的 Agent、令牌、技能、设置、Canvas