Synapse Term：让 AI 直接操作你已经连好的 SSH、容器和 WSL 终端

Synapse Term：让 AI 直接操作你已经连好的 SSH、容器和 WSL 终端

直接下载：https://github.com/422511186/synapse-term/releases
GitHub：https://github.com/422511186/synapse-term

先说一个常见场景

你要排查一台生产机器：

本机 → 跳板机 → 二次认证 → 目标机 → docker exec → 切换用户

折腾一圈后，终端环境终于准备好了。接下来，你想让 AI 帮忙看日志、执行诊断命令，或者修改配置。

这时通常有几个选择：

• 使用 IDE 内的 AI，但当前环境可能藏在多层 SSH 或容器之后；
• 使用 CLI Agent，但可能需要另外配置远端连接和凭据；
• 把日志复制给网页端 AI，再把建议的命令逐条贴回终端。

我不太满意这种割裂的工作流，所以做了Synapse Term。

核心思路：连接由你建立，AI 复用当前终端

一句话概括：

你负责进入目标环境，AI 只操作你已经打开的终端会话。

你 → SSH → 跳板机 → SSH → 目标机 → docker exec → 容器 ↑ Synapse Term 在当前会话中 观察输出、执行命令、修改文件

无论你是通过 SSH、跳板机、容器、WSL，还是kubectl exec进入目标环境，对 Agent 来说都一样。

Synapse Term 不负责建立 SSH 连接，也不需要持有远端 SSH Key。AI 对远端环境的操作必须经过你当前打开的终端会话完成。

这也是 Synapse Term 想解决的核心问题：

在不把远端连接凭据交给 Agent 的前提下，让 AI 操作复杂的终端环境。

需要说明的是，这并不意味着模型服务看不到命令和终端输出。发送给模型的内容仍受你所选模型服务及其隐私政策约束。

Synapse Term 主要解决的是：

• 远端凭据由谁持有；
• AI 能否自行建立远端连接；
• 命令如何审批、执行和审计。

它并不等于让远端模型天然获得数据保密能力。

和现有工具有什么不同

IDE Agent、CLI Agent 和 Synapse Term 的侧重点不同：

Synapse Term 并不是要替代 Claude Code、Codex CLI 或 Cursor，而是针对另一类问题：

目标环境已经在某个终端里准备好了，怎样让 AI 可控地进入这个现成会话工作？

目前做了哪些事情

1. 命令必须经过事务和审批链路

Agent 不能绕过平台，直接向 PTY 写入任意包装脚本。

每条命令都要经过完整的执行链路：

Agent 请求执行命令 → 校验 Session 归属 → 校验执行环境和 Shell 方言 → 获取命令租约 → 执行策略检查和用户审批 → 分发明文命令 → 写入 PTY → 通过 nonce 识别完成状态和退出码 → 写入审计记录

对于控制字符、伪造完成序列和跨事务边界等异常输入，默认拒绝执行。

同一个 Session 在同一时间只允许一个活动命令，避免多个调用同时争用终端。

2. Agent 不会默认读取终端

普通对话不会自动读取终端屏幕，也不会因为你发送了一条消息，就自动获得终端控制权。

Agent 想知道当前环境的状态，必须显式调用“观察终端”工具。终端观察、命令执行和普通对话是分开的操作。

这样可以明确区分：

• Agent 实际观察到了什么；
• Agent 根据上下文推测了什么；
• Agent 是否获得了执行权限。

3. 工具能力保持克制

目前，内置 Agent 固定使用 9 个工具：

• 4 个终端工具：观察、执行、等待、中断；
• 5 个文件工具：列目录、搜索、读取、写入、编辑。

工具边界固定，便于做权限控制、用户审批和行为审计。

4. 支持三类模型协议

目前支持：

• OpenAI Responses API；
• OpenAI 兼容的 Chat Completions API；
• Anthropic Messages API。

不同协议会被统一适配到同一套 Agent 工具和执行流程。

API Key 存储在 Windows Credential Manager 或 macOS Keychain 中，不写入项目数据库、界面状态或审计日志。

5. 外部 AI 也可以接入

如果不想使用内置 Agent，还可以通过 MCP 或 ACP 接入外部客户端。

MCP

Synapse Term 会提供一个仅监听127.0.0.1的本地 HTTP 端点，并使用 Bearer Token 鉴权。

Session 默认不对外共享。只有手动将指定 Session 标记为共享后，外部 MCP 客户端才能访问。

例如，Codex 等没有 ACP 接口的客户端可以通过 MCP 接入。

ACP（当前存在已知问题，待修复）

平台支持启动本机的opencode acp子进程，并向其提供受控的终端能力和只读文件能力。

不过，v0.3.2 的 ACP 接入目前存在已知 Bug，还在修复中。如果你想体验外部 AI 接入，现阶段建议优先使用 MCP。

无论调用来自内置 Agent、MCP 还是 ACP，设计上都会经过同一套权限、审批和审计机制。

下载和使用

直接下载

不想从源码构建，可以直接下载：

https://github.com/422511186/synapse-term/releases

目前支持 Windows 和 macOS (arm架构)。

从源码运行

环境要求：

• Windows 或 macOS；
• Node.js 24+；
• pnpm。

corepackenablepnpminstall--frozen-lockfile# 启动浏览器 Mock UI，不连接真实桌面能力pnpmdev# 构建并启动桌面端pnpmbuildpnpmstart

基本使用流程：

1. 创建 Terminal Session，选择系统发现的 Shell；
2. 在终端中自行执行ssh、docker exec、kubectl exec或wsl；
3. 选择执行方言：POSIX、PowerShell 或仅观察；
4. 进入新环境后，重新验证执行方言；
5. 配置并启用模型；
6. 在 Agent 面板提交任务。

项目状态

当前版本为v0.3.2，采用 MIT License。

目前已经具备：

• Windows 和 macOS 构建支持；
• OpenAI Responses、Chat Completions 和 Anthropic Messages 协议支持；
• 内置 Agent 与 MCP 外部接入；
• 命令审批、租约和审计机制；
• 单元测试、集成测试和 E2E 测试；
• 真实模型验收测试；
• 31 篇架构决策记录；
• 架构、安全和运行手册。

项目仍在快速迭代，目前也有一些已知问题：

• ACP 接入仍需修复；
• 一些旧界面中还保留着Terminal Agent的历史名称；
• 部分功能和交互仍在持续打磨。

欢迎试用，但如果要用于生产环境，建议先充分验证审批策略、模型配置和实际命令行为。

希望获得哪些反馈

目前尤其希望了解以下几类需求和问题：

• 复杂环境测试：多层 SSH、容器、WSL、kubectl exec等场景；
• 安全审阅：命令事务、租约、审批和审计机制；
• 外部接入：MCP、ACP 的兼容性和使用体验；
• 模型协议：Gemini、Grok 或其他兼容服务的接入需求；
• Shell 支持：fish、nushell 等方言是否值得优先支持；
• 实际体验：哪些步骤仍然繁琐，哪些边界行为不符合预期。

遇到问题可以直接提交 Issue。安全机制和架构设计也欢迎大家审阅、讨论。

相关链接

• v0.3.2 下载：https://github.com/422511186/synapse-term/releases/tag/v0.3.2
• GitHub：https://github.com/422511186/synapse-term
• 项目文档：仓库docs/目录
• 架构决策记录：仓库docs/adr/目录

Synapse Term 不是 Claude Code 或 Codex CLI 的终端外壳。它自己管理 Agent、终端、文件、模型、审批和审计，定位是一个本地的 AI 终端工作台。

如果你经常需要让 AI 协助处理 SSH、远端容器、WSL 或生产排障任务，但又不希望把远端连接凭据交给 Agent，可以下载试试：

https://github.com/422511186/synapse-term/releases

Star、Issue 和 PR 都欢迎。