synapse-manager

Synapse Manager

通过结构化委派、监控和质量门槛来协调多 Agent 工作。

适用场景

• 协调 2 个或更多 Agent 处理相关子任务
• 监控已委派工作的进度
• 验证 Agent 的输出（测试、文件更改、集成情况）
• 发送包含错误详情和修复指导的定向反馈
• 协调 Agent 之间的交叉评审
• 实施多阶段计划（3 个或更多阶段，或更改 10 个或更多文件）
• 规划多文件更改的 Agent 分配

工作流（7 个步骤）

步骤 1：规划、编写规格并进行设置

范围明确时优先采用测试先行：创建测试 -> 提交并确认规格 -> 然后实施。对于探索性工作、原型或简单修复，可以在实施后编写测试。

先编辑 plugins/synapse-a2a/skills/，然后使用 sync-plugin-skills 同步生成的副本。

生成新 Agent 前先检查现有 Agent —— 重用速度更快（可避免启动开销、指令注入和等待就绪）：

synapse list --json

检查 WORKING_DIR、ROLE、STATUS、TYPE。只有 READY 状态的 Agent 才能立即接收工作。 其他相关状态：SENDING_REPLY（短暂的出站 A2A 发送／回复 POST； 等待其恢复到之前的状态）、PROCESSING（忙碌中）、WAITING （权限提示 —— 使用 synapse approve／synapse reject）、WAITING_FOR_INPUT （#538 — 任务已暂停并请求输入，可通过 synapse reply "<message>" 或 synapse reply "<message>" --to <sender_id> 回复）、RATE_LIMITED（#561 — LLM 提供商触发速率限制；等待限制窗口重置后再重新发送）、DONE （约 10 秒后降级为 READY）、SHUTTING_DOWN（不要发送）。

只有在没有现有 Agent 能处理任务时才生成新 Agent：

synapse spawn claude --worktree --name Impl --role "feature implementation"
synapse spawn gemini -w --name Tester --role "test writer"

跨模型生成 Agent（例如 Claude 生成 Gemini）可发挥不同模型的优势， 并在不同提供商之间分摊令牌用量，避免触发速率限制。

使用辅助脚本等待就绪。 从技能根目录解析该脚本，以确保无论当前工作目录是什么，命令都能正常运行，无论你位于插件源目录还是同步副本中：

cd plugins/synapse-a2a/skills/synapse-manager
scripts/wait_ready.sh Impl 30
scripts/wait_ready.sh Tester 30

# Synced copy example
cd .agents/skills/synapse-manager
scripts/wait_ready.sh Impl 30

各 CLI 的权限跳过标志请参阅 references/auto-approve-flags.md。

步骤 2：创建测试并确认规格

分配测试／规格任务，并在开始实施前确认范围：

synapse send Tester "Write the tests first and confirm the spec for auth module.
- Cover valid login, invalid credentials, token expiry, refresh flow
- Report any scope gaps before implementation starts" --attach synapse/server.py --force --wait

使用 --attach 发送 Agent 应研究的参考文件。 确认测试／规格时使用 --wait，解除执行阻塞后使用 --silent 或 --notify。

步骤 3：委派实施并监控

确认测试／规格后，委派实施任务：

synapse send Impl "Implement auth module — tests/spec are confirmed.
- Add OAuth2 flow in synapse/auth.py
- Follow existing patterns" --attach synapse/server.py --force --silent

synapse list --json                       # AI-safe snapshot
synapse history list --agent Impl         # Completed work

或者使用聚合脚本：

cd plugins/synapse-a2a/skills/synapse-manager && scripts/check_team_status.sh

如果某个 Agent 处于 PROCESSING 状态超过 5 分钟，发送中断信号：

synapse interrupt Impl "Status update — what is your current progress?" --force

步骤 4：批准计划

synapse approve <task_id>
synapse reject <task_id> --reason "Use refresh tokens instead of long-lived JWTs."

步骤 5：验证

先运行步骤 2 中创建的测试以快速获取反馈；如果更改涉及共享模块或公共接口，再考虑扩大回归测试范围：

# New tests first (fast feedback)
pytest tests/test_auth.py -v

# Full regression (catches cross-module breakage)
pytest --tb=short -q

回归问题分类 —— 区分新出现的问题和既有问题：

cd plugins/synapse-a2a/skills/synapse-manager && scripts/regression_triage.sh tests/test_failing_module.py -v

• 退出码 0 = 回归问题（由你的更改导致）→ 继续步骤 6
• 退出码 1 = 既有问题（原本就已损坏）→ 记录并继续

步骤 6：反馈

具体且可执行的反馈可以减少迭代次数：

synapse send Impl "Issues found — please fix:

1. FAILING TEST: test_token_expiry (tests/test_auth.py)
   ERROR: TypeError: cannot unpack non-iterable NoneType object
   FIX: Add None guard at the top of validate_token()

2. REGRESSION: test_existing_endpoint broke
   ERROR: expected 200, got 401
   CAUSE: auth middleware intercepts all routes
   FIX: Exclude health-check endpoints from auth" --force --silent

为团队保存模式：

synapse memory save auth-middleware-pattern \
  "Auth middleware must exclude /status and /.well-known/* endpoints" \
  --tags auth,middleware --notify

发送反馈后，返回步骤 3（监控）。

步骤 7：评审并收尾

交叉评审可发现盲点 —— 每个 Agent 都评审另一个 Agent 的工作：

synapse send Tester "Review implementation. Focus on: correctness, edge cases" --force \
  --attach synapse/auth.py --wait
synapse send Impl "Review test coverage. Focus on: missing cases, assertion quality" --force \
  --attach tests/test_auth.py --wait

最终验证和清理：

pytest --tb=short -q                      # All tests pass
synapse kill Impl -f && synapse kill Tester -f
synapse list --json                       # Verify cleanup

终止生成的 Agent 可释放端口、内存和 PTY 会话。孤立的 Agent 可能会意外接下原本分配给其他 Agent 的后续任务。

决策表

情况	操作
Agent 卡在 PROCESSING 超过 5 分钟	synapse interrupt <name> "Status?"
Agent 被 CLI/TUI 对话框阻塞（codex 编辑确认、模型选择器、速率限制提示）	synapse send-keys <name> <keys> — 以编程方式响应对话框，将内容写入 PTY，无需使用 synapse jump（例如，输入 a 表示 codex 的“不要再询问”，输入 \r 表示按 Enter）（#695）
Agent 处于 WAITING_FOR_INPUT 状态	synapse reply <task_id> "<answer>"
Agent 处于 RATE_LIMITED 状态	等待大模型提供商的窗口重置，然后重新发送
一次检查所有 Agent	synapse broadcast "Status check" -p 4
新测试失败	提供错误信息和建议的修复方案（步骤 6）
回归测试失败	使用 scripts/regression_triage.sh 进行分类
Agent 已就绪但没有输出	检查 git diff，必要时重新发送
Agent 提交计划	使用 synapse approve 或 synapse reject --reason "..."
发现可复用的模式	使用 synapse memory save <key> "<pattern>" --notify 保存
交叉审查发现问题	使用 --attach 发送修复请求，并重新验证
所有测试均通过，审查无问题	终止 Agent，报告完成

参考资料

参考资料	内容
references/auto-approve-flags.md	各 CLI 的跳过权限标志
references/worker-guide.md	Worker Agent 的职责和沟通模式
references/features-table.md	带命令的 A2A 功能
references/commands-quick-ref.md	所有与管理者相关的命令
scripts/wait_ready.sh	轮询，直到 Agent 达到 READY 状态
scripts/check_team_status.sh	汇总团队状态
scripts/regression_triage.sh	将测试失败分类为回归问题或既存问题