Synapse Skill 技能

技能简介

Synapse（PyPI 包名 synapse-cli-agent）是一个终端优先的开源 AI 编码 Agent 运行时，基于 LangChain Deep Agents 构建，Apache-2.0 许可。与"一问一答、跑完即弃"的轻量提示工具不同，Synapse 为跨多轮的长任务而设计：它提供响应迅速的 TUI 界面，把时间线、工具调用与上下文用量实时摆在你眼前；对工具输出做 token 感知的裁剪与处理；并引入"持久目标"机制——你交给它一个目标，它会持续推进直到真正完成。它的口号很直接：住在终端里的编码 Agent。项目同时提供英文与简体中文文档，支持 macOS、Linux 与 Windows。

核心能力

• 响应式 TUI：时间线视图完整记录对话、工具调用与文件改动，上下文用量实时可见，长会话不"失忆"。
• 持久目标（Persistent Goals）：把目标注入运行时，Agent 在多轮之间保持工作方向，跨会话延续直到任务完成。
• token 感知的工具输出处理：自动控制工具返回内容的体积，避免大文件输出瞬间撑爆上下文窗口。
• 独立运行时守护进程：synapse-runtime 可作为前台 daemon 常驻（S8），启动后输出一行 ready JSON 元数据，令牌生成在私有状态目录、绝不打印，配合 --token-file 支持部署级密钥管理。
• Web 控制台：React + TypeScript 单页控制台，通过 synapse web-console 启动（静态产物 + 配对 API + WebSocket 中继），宿主会按需自动拉起或复用 daemon，本机场景可用 --no-pairing 免输配对码。
• 多入口形态：CLI、TUI、Web 控制台与 ACP 消费者共用同一套运行时，可按场景切换。
• 跨平台安装：uv tool install 一条命令完成，Windows 另有 Scoop 桶与桌面快捷方式脚本。

安装配置

1. 全平台通用：uv tool install synapse-cli-agent，无需克隆仓库。
2. Windows：scoop bucket add synapse https://github.com/alex8224/synapse-agent 后 scoop install synapse（单文件可执行、自动更新），或直接从 manifest URL 安装。
3. 源码运行 Web 控制台：uv sync 同步依赖，cd web && npm ci && npm run build 生成前端产物，再执行 synapse web-console --workspace . --state-dir ~/.synapse/runtime --port 8080。
4. 首次启动前配置模型供应商（API Key 等环境变量），并按需指定 --state-dir 管理运行时状态目录。

使用步骤

1. 安装：执行 uv tool install synapse-cli-agent（Windows 用 Scoop）。
2. 启动 TUI：synapse tui -w .，在当前工作区打开交互界面。
3. 设定目标：输入任务目标（如"修复失败的测试""重构某模块"），Agent 开始多轮推进，时间线中可实时观察工具调用与上下文用量。
4. 需要常驻服务时启动运行时：synapse-runtime --state-dir ~/.synapse/runtime --host 127.0.0.1 --port 0，端口由内核分配，SIGINT/SIGTERM 优雅退出。
5. 需要图形界面时启动 Web 控制台：synapse web-console --workspace .，宿主会自动拉起或复用 daemon，浏览器打开配对页面即可操作。
6. 用 --no-start-runtime 禁止自动拉起、--runtime-port 指定已有 daemon，实现"daemon 必须由我亲自管理"的部署方式。

适用场景

1. 日常编码任务：让 Agent 直接修复失败测试、补写用例、重构模块，全程在终端内可见可控。
2. 跨多轮的长任务：需要多步探索、反复验证的目标型工作，持久目标机制保证方向不漂移。
3. 团队共享运行时：常驻 daemon + Web 控制台，配对码机制让同机或内网成员通过浏览器接入同一个 Agent 会话。
4. 脚本化 / 自动化集成：运行时暴露标准化接口（含 ACP），可被编辑器、CI 或其他程序消费。
5. 离线状态目录管理：以 --state-dir 为边界的运行状态，便于备份、迁移与多环境隔离。

适用人群

终端优先的开发者、重度使用 AI 结对编程的工程师、需要把编码 Agent 常驻为服务的团队，以及希望在浏览器中可视化管理 Agent 会话的技术负责人。

工作原理

Synapse 采用"运行时 + 多宿主"架构：底层是基于 LangChain Deep Agents 的 Agent 循环，负责规划、工具调用与目标推进；synapse-runtime 将其封装为带鉴权令牌的常驻服务（令牌在状态目录内生成、不落日志）；上层的 CLI、TUI、Web 控制台与 ACP 消费者都是这个运行时的"宿主"，通过配对码或本地令牌与之通信。TUI 把每一轮消息、工具调用与 token 用量渲染到时间线上，工具输出在进入上下文前经过 token 感知的裁剪层，保证长会话的可控性；Web 控制台宿主遵循"能复用绝不重复拉起、正常退出连带停止自己拉起的 daemon"的生命周期规则，避免端口与进程失控。

官方链接

• PyPI：https://pypi.org/project/synapse-cli-agent/
• GitHub：https://github.com/alex8224/synapse-agent
• 官网：https://synapse-agent.best