Unterm

Unterm

终端 AI Agent 可以驱动。

如果 Unterm 对你有用，在 GitHub 上点个 ⭐，能帮助更多人发现它。

基于 Unterm 原生 next-core 终端引擎构建的跨平台终端（macOS / Linux / Windows），采用了一项设计取舍：任何 AI Agent 都可以通过 MCP 从外部控制终端本身。Claude Code、Codex、Gemini CLI、Cursor、Aider，以及你自己的脚本，都能使用同一套 JSON-RPC 接口（152 个经过身份验证的方法，加上 auth.login）来启动 shell、运行命令、读取窗格状态、截取屏幕、录制会话，以及运行 Agent 驾驶舱。（主题、语言和 unterm.conf 不支持通过 MCP 设置；它们通过 Web Settings、unterm-cli 或文件设置。）

自 v0.68 起，终端也可以由编排器管理，而不只是被调用：它会公布自身能做什么以及每项能力的危险级别；通过会过期且无法重放的租约运行；让 Agent 各自处于无法互相查看的工作区中；并能为任务生成证据包，供未参与任务的人核验。

自 v0.55 起，双方的关系变成了双向：Agent 从外部驱动终端，而终端则成为内部运行的 Agent 的Agent 驾驶舱——提供每个窗格的实时 Agent 状态、优先显示等待处理项的收件箱、让 N 个 Agent 在 N 个隔离的 git worktree 中协作完成一项任务的 Agent 集群，以及用于查看差异、合并或回滚产出内容的 Review 页面。

其他 2026 年的终端各自选择了不同方向：Warp 将 AI 嵌入封闭的云服务（Oz），Ghostty 不妨碍你使用自己的工具，iTerm2 则仅支持 Mac。Unterm 选择了第三条路——将终端作为可由 MCP 控制的界面，刻意不在终端中加入 AI 生成功能，让外部 Agent 通过 API 操控终端，并为用户提供一个统一的驾驶舱来运行所有 Agent。

实际体现如下：

• 每个 Unterm 窗口都会启动一个本地 MCP 服务（基于 TCP 的逐行 JSON-RPC）和一个本地 HTTP 设置服务（Web Settings 页面），端口均自动分配。两者都需要通过身份验证令牌访问，也都仅监听 127.0.0.1，无需往返云端。
• 设置在浏览器中进行，而不是在终端中进行。基于单元格网格的 TUI 无法提供现代表单体验（没有合适的文本输入框、实时预览或颜色选择器）。终端内的 ▼ 菜单提供快捷操作和 Web Settings 页面的链接，实际配置则在浏览器中完成。
• 开箱即支持 9 种语言：en / 简体中文 / 繁體中文 / 日本語 / 한국어 / Deutsch / Français / Italiano / हिन्दी。自动检测系统区域设置，也可在 Web Settings 中或通过 unterm-cli lang set <code> 覆盖。
• 多实例发现：每个运行中的 Unterm 进程都拥有一个以北约音标命名的实例（alpha、bravo、charlie……），并将端口和身份验证令牌写入 ~/.unterm/instances/<name>.json。同时驱动多个窗口的 Agent 会枚举该目录。
• 跨平台一致性是正确性要求：如果某项功能在 Windows 上可用，但在 macOS 或 Linux 上失效，那就是 bug，而不是“暂不支持”。
• 做减法，而非添装饰：终端内没有 AI 聊天浮层，核心运行不依赖云服务。代理设置默认自动检测系统配置，也支持显式设置 HTTP/SOCKS 覆盖项、节点池、轮换策略和 Clash/mihomo 控制器。macOS 上的 Finder 集成使用原生 Finder 右键扩展和“服务”。

GUI 和终端运行时现在都使用 Unterm 原生的 next-core 引擎。仓库仍保留部分选定的上游组件及其归属声明，但 WezTerm mux/window 状态已不再是产品内核。

Agent 驾驶舱

在任意窗格中运行 Claude Code、Codex、Gemini CLI 或 Aider，Unterm 都能识别它们——无需配置，也无需包装器。五大支柱，全部在本地运行：

• Agent 状态引擎 — 读取 OSC 进度和标题信号、进程指纹以及可选的官方钩子，获取每个窗格中的 Agent 及其状态（工作中 / 等待你 / 空闲 / 已完成）。标签页徽标 + 顶栏中的跨窗口计数标记。
• 收件箱（Ctrl+Shift+A）— 将所有等待你处理的 Agent 放入一个队列，等待时间最长的排在最前。按 Enter 跳转到对应窗格；再按一个键即可回复其提示词。
• Agent 集群 — 一个任务 × N 个 Agent × N 个隔离的 git worktree（../<repo>.fleet/），每个对应一个标签页。可用同一个 Agent ×3 提高吞吐量，也可用 claude,codex,gemini 进行对比测试。
• 审查 — Agent 在接触仓库前会先创建检查点（悬空提交快照；不会触碰你的 HEAD 或索引）。Web 审查页面会显示各成员的差异，支持压缩合并（到已暂存为止——提交仍由你掌控）、丢弃和回滚。从 v0.57 开始，审查还会验证每个成员（推断或显式指定验证命令）、根据验证结果和更改规模为成员排名、要求验证通过后才能合并，并可在成员失败后于其现有 worktree 中重试。
• 一切皆可脚本化 — 驾驶舱本身就是 MCP + CLI：agent.status、cockpit.inbox、fleet.launch、review.merge……编排 Agent 可以运行集群并审查差异，无需人工介入。

unterm-cli agent status                                  # who's running where, in what state
unterm-cli agent inbox                                   # who's waiting for you
unterm-cli agent enable-hooks                            # exact state via official hooks (merge-only, backed up)
unterm-cli fleet launch --agents claude,codex "fix the flaky auth test"
unterm-cli review verify --fleet <id> --member 1         # run the member's validation
unterm-cli review list && unterm-cli review open         # ranked diffs in the browser

完整文档：unterm.app/docs/agent-cockpit。

---

安装

预构建的安装包已发布在 GitHub Releases：

https://github.com/zhitongblog/unterm/releases

平台	安装包
macOS	Unterm-macos-<version>.dmg（通用版 arm64+x86_64，已签名 + 公证）
Linux	unterm-<version>.deb 或 Unterm-<version>-x86_64.AppImage
Windows	Unterm-<version>-x64.msi 或 Unterm-windows-x64-<version>.zip

macOS

双击 Unterm-macos-<version>.dmg，然后将 Unterm.app 拖到 Applications 快捷方式上。该 DMG 使用 Developer ID 签名并经 Apple 公证，因此 Gatekeeper 会在首次启动时直接打开，不会显示警告。

DMG 中包含 Finder 集成。首次启动后，Finder 的右键菜单可为文件夹和文件 显示 Open in Unterm；如果 macOS 未立即刷新扩展，请从 DMG 中运行一次 Repair Finder Integration.app。

Linux（Debian / Ubuntu）

sudo apt install ./unterm-<version>.deb
unterm

其他发行版 — 使用 AppImage：

chmod +x Unterm-<version>-x86_64.AppImage
./Unterm-<version>-x86_64.AppImage

Windows

运行 MSI 安装程序；它会将 unterm.exe 安装到 Program Files\Unterm，并创建“开始”菜单快捷方式。

---

更新内容

• v0.68 — 终端现在也能接受治理。 Unterm 现在会将 CLI Agent 作为会话托管，而不是通过 shell 启动后等待退出代码（agent_session.*：Agent 说了什么、要求运行什么、如何结束，以及原样保留你自己的任务 ID）。它可以从 Unzoo 租用浏览器，也可以反过来被租用——terminal.manifest 会发布此终端能做什么，以及每类操作的危险程度；这些信息来自网关据此拒绝操作的同一张表。现在终于可以响应审批了：设置中会显示 Agent 正在等待什么，并提供“允许一次／对此任务始终允许／始终允许”选项。工作区彼此隔离，无法互相访问；shell 执行 cd 离开工作区后，也就不再位于其中。审计记录采用哈希链，因此任何编辑都会与下一行不匹配。unterm-cli provider | scope | artifact | evidence | system — 新增 46 个 MCP 方法（当时共 149 个；如今为 152 个）。
• v0.57 — 集群验证循环 + 全新品牌标志。 Review 现在会自动验证每个集群成员（可推断 Cargo / Go / npm / pnpm / yarn / Python / Maven / Gradle / .NET，也可使用自定义命令），根据验证结果和变更规模为成员排序，仅在验证通过后才允许 squash-merge（可审计的 force 覆盖选项），并可在现有工作树中重试失败的成员而不丢失工作——通过 MCP + CLI 使用 review.verify / fleet.retry。侧边栏新增按仓库分组的导航，并始终提供模糊搜索。所有 Logo 展示位置均改用新的命令循环标志。
• v0.55 — Agent Cockpit。 终端现在可以查看其中运行的 Agent：每个窗格的实时状态、标签页徽标和跨窗口统计；优先显示等待项的 Agent 收件箱（Ctrl+Shift+A）；让 N 个 Agent 在 N 个隔离工作树中执行同一任务的集群；以及提供检查点、差异、回滚和 squash-merge 的 Review 页面。新增 12 个 MCP 方法和 3 组 CLI 命令。
• v0.54 — 冷启动速度提升 2.8 倍（约 780ms → 约 280ms），得益于启动路径上的五项优化；同时不再因 Windows 输出洪流而耗费一个 CPU 核心（约 91% → 约 4%）；MCP 在输出洪流期间仍能保持响应。
• v0.53 — Composer + Git 面板。 提示词队列（Ctrl+Shift+J）可将批量提示词发送到 Agent 窗格，并在确认提示间智能自动前进；另有只读 Git 状态面板（Ctrl+Shift+G）。
• v0.52 — 开箱即支持更多 Agent。 Kimi Code CLI 和 Trae Agent 加入内置清单（共支持 7 个 Agent CLI）；重做了逐帧绘制路径；让 Windows 剪贴板和窗口大小调整更加稳定。

---

文档

完整的 Unterm 文档位于 **https://unterm.app/docs/**：

• Agent 驾驶舱 — Agent 状态引擎、Inbox、Fleet、Review：在一个终端中运行和监管 CLI Agent
• Agent 集成 — 如何从 Claude Code / Cursor / Aider / 你自己的客户端驱动 Unterm
• Agent 配方 — 常见 Agent 驱动终端工作流的可复制粘贴模式
• 产品路线图 — 当前正在构建的内容以及后续计划
• 产品需求 — 完整的产品范围、功能需求、MCP/CLI 覆盖范围和验收标准
• 详细产品规划 — 中文执行计划，涵盖用户场景、版本路线图、优先级、验证和 next-core 迁移
• Next-core 产品计划 — 分阶段计划：在构建 Unterm 自有终端核心的同时，稳定当前引擎
• Next-core 技术架构 — 用于替换 WezTerm 核心的中文架构计划，同时避免发展成更庞大的终端单体
• MCP 参考 — 所有 JSON-RPC 方法、参数和返回结构
• 多实例 — NATO 名称、实例目录、选择合适的窗口
• 身份配置文件 — 每个身份对应一个窗口。一次性绑定 GitHub / AWS / npm / OpenAI 令牌、git 身份和 SSH 密钥路由。支持 CLI + MCP。
• CLI 参考 — unterm-cli 子命令、标志和退出代码
• 配置 — ~/.unterm/ 下的所有文件
• 配置文件参考 — unterm.conf 中的所有键，包括 [env] 和 [keys]
• 架构 — 我们从 WezTerm 分叉的内容及其原因

本 README 是简版。网站上的是完整版。

---

功能

• GPU 加速渲染：通过 wgpu 支持所有三个平台：macOS 上使用 Metal，Windows 上使用 Direct3D 12，Linux 上使用 Vulkan。如果硬件渲染路径失败，Unterm 会尝试 OpenGL，然后使用软件渲染重试这两种路径（Windows 上使用 WARP），最后在 Windows 上尝试 Vulkan — 因此，即使机器没有可用的图形驱动，也能打开窗口。UNTERM_GPU_BACKEND=dx12|vulkan|gl|metal 可指定单一后端。
• 在终端中显示图片 — 支持 kitty 图形协议、iTerm2 内嵌图片（OSC 1337 File=）和 sixel，因此 chafa、img2sixel、viu、timg 和 unterm-cli imgcat 会显示图片本身。图片会随文本滚动、保留在回滚缓冲区中、在窗格边缘裁剪，并保留在绘制它们的屏幕（主屏幕或备用屏幕）上。Agent 可通过 screen.images / unterm-cli session images 列出图片。
• MCP 服务位于 127.0.0.1:<auto-port>（默认端口 19876） — 通过 TCP 使用按行分隔的 JSON-RPC，仅限环回地址并受身份验证令牌保护。它 提供 152 个经过身份验证的方法，另有 auth.login；meta.surface（或 unterm-cli reference）可通过一次调用返回权威的实时清单。
• Agent 驾驶舱 — 每个窗格的 Agent 状态、优先显示等待项的收件箱、工作树集群、检查点与审查。请参阅上文相关章节。
• 受治理的 Agent 工作 — 所有入口（MCP、CLI、brain、工作流、原始 PTY 写入）都必须通过同一个网关；能力租约设有过期时间并防止重放；工作区彼此隔离；审计记录采用哈希链；证据包可供他人验证。Agent 无法绕过前门控制浏览器：在受管理会话中，原始 CDP、Playwright、Puppeteer 和 Selenium 都会被拒绝，并会在拒绝信息中指出受支持的途径。
• Web 设置界面位于 127.0.0.1:<auto-port>（默认端口 19877） — 通过 unterm-cli settings open 或 ▼ 菜单中的 Settings (Web) 项目，即可在任意浏览器中打开。采用 Tailwind 样式的 SPA，支持全部 9 种语言，并支持键盘和鼠标操作。
• 代理管理 — 读取 macOS 系统偏好设置 / Windows 注册表 / GNOME gsettings / 代理环境变量，并在此基础上尝试常用本地端口。~/.unterm/proxy.json 还会持久保存手动配置的 HTTP/SOCKS URL、no_proxy、命名节点、轮换设置以及 Clash/mihomo 控制器设置。
• 区域截图：通过状态栏截取（左键单击会排除 Unterm 窗口，右键单击则会包含该窗口）。PNG 文件会保存到磁盘上的 ~/.unterm/screenshots/，并复制到系统图片剪贴板；图片路径会复制到文本剪贴板。通过 MCP，capture.screen、capture.window 和 capture.select（矩形区域）可在 macOS 和 Windows 上使用；Linux 上目前会返回 "not implemented on this platform yet"。capture.scrollback 和 capture.clipboard 在所有平台上均可使用。
• 滚动长截图，支持两个方向：capture.scrollback 会在无界面模式下将窗格的全部历史记录重新渲染为一张长 PNG（字体和主题完全一致，流式编码，窗口被遮挡时也可使用）；capture.window_scroll 会通过模拟滚轮事件和基于行哈希匹配拼接画面，并检测固定页眉/页脚，对另一个应用的窗口进行长截图（macOS）。两项功能也可通过 ▼ 菜单和 unterm-cli screenshot --scrollback / --scroll-app 使用。
• 会话录制 → Markdown：使用 OSC 133 分段，并内置脱敏功能（会掩盖 GitHub 令牌、KEY=value 以及长度为 40 个字符以上的十六进制/ base64 模式）。录制文件保存在项目目录下的 <cwd>/.unterm/sessions/<date>/<tab>-<time>.md；如果没有可写的项目上下文，则保存在 ~/.unterm/sessions/_orphan/。
• 在终端中右键粘贴 — 每次右键都会粘贴，无论是否有选区，也适用于所有窗格，包括 vim 或 Claude Code 等可感知鼠标操作的程序（不会将单击事件传递给它们）。选择文本即可复制：松开按键后，选区内容会复制到剪贴板。在 macOS 上，普通的 Ctrl+单击也算右键；中键同样可以粘贴。在标签栏上右键会打开标签上下文菜单（新建标签、分屏、重命名、移动、关闭），不会将应用界面上的右键操作传递为粘贴。
• 快速菜单：位于标签栏的 ▼ 按钮中，显示绑定表中的实时快捷键组合：
  • 新建标签 / 向右分屏
  • 目录跳转（切换当前窗格目录或在新标签中打开）/ 文件树
  • Git 面板 / 切换左侧标签栏
  • 查找 / 命令面板
  • 切换会话录制 / 导出当前会话 / 回滚缓冲区长截图
  • 设置（Web），以及版本/网站一栏
• 统一顶部栏：不再使用单独的标题栏，按钮样式与桌面平台一致：macOS 上为红绿灯按钮，Windows 上为 Fluent 标题栏按钮（Windows 11 上支持贴靠布局），Linux 上为 GNOME 风格圆形按钮。

---

身份配置文件

一次性将窗口绑定到一致的开发者身份——GitHub PAT、AWS 密钥、npm 令牌、git 作者信息、SSH 密钥。一种身份对应一个新窗口。标签栏中的标记会显示当前使用的身份。机密信息存储在操作系统原生密钥库（Keychain / Credential Manager / Secret Service）中，绝不会存放在 ~/.unterm/ 中。

unterm-cli profile create "Work — Acme"
unterm-cli profile set-secret "Work" GITHUB_TOKEN
unterm-cli profile spawn "Work"           # → new window bound to Work
unterm-cli profile set-default "Work"     # plain `unterm` now binds to Work
unterm-cli profile import                 # scans gh/aws/npm/ssh/docker/gcloud/netrc
                                          #   for existing credentials, read-only

在绑定了配置文件的 Shell 中：

$ env | grep UNTERM_PROFILE
UNTERM_PROFILE=work-acme
# GITHUB_TOKEN, GIT_AUTHOR_NAME, AWS_*, etc. all set from the profile

完整文档：unterm.app/docs/profiles。

多实例

每个运行中的 Unterm 进程都是一个实例，并使用北约音标名称：alpha、bravo、charlie，……zulu。第一个窗口占用 alpha，第二个占用 bravo，依此类推。当 26 个名称同时全部被占用时，下一个实例会从 alpha2 开始。名称易于读出，AI Agent 也能正确处理——无需 UUID，也不用费心记端口。

每个 GUI 实例都会将其元数据（mcp_port、http_port、auth_token、pid、started_at、version、platform）写入 ~/.unterm/instances/<name>.json。需要控制特定实例的 Agent 可以枚举该目录，并按 id、cwd 或 title 选择实例。

无头 Core 会将 core.json 写入其平台数据目录——Windows 上是 %LOCALAPPDATA%\Unterm，Linux 上是 ~/.local/share/Unterm，macOS 上是 ~/Library/Application Support/Unterm——而不是 ~/.unterm。（UNTERM_STATE_DIR 会覆盖这两个位置，这就是它们会被混淆的原因：所有设置了该变量的测试都发现两者一致。）unterm-cli mcp-stdio 和由 MCP 提供支持的 CLI 命令会优先使用该 Core 记录，因此终端会话在 GUI 重启后仍可继续运行；当没有打开任何窗口时，它还会以实例 core 的身份出现在 instance.list 中——unterm-cli --instance core 可连接到它。

实例是前端，而非窗口：从 v0.68 开始，一个进程可以持有多个窗口，每个窗口都有自己的 id。instance.windows 会列出这些窗口，instance.new_window 会打开一个窗口并返回其 id，instance.focus 会聚焦到指定窗口。

对于旧版单目标 Agent，~/.unterm/active.json 指向当前运行中的 GUI 实例，而 ~/.unterm/server.json 会为向后兼容保留同一条记录。

MCP 的 instance.* 命名空间可直接提供这些功能：instance.list、instance.info、instance.set_title、instance.focus。示例和发现协议请参阅多实例文档。

---

CLI

unterm-cli 二进制文件提供完整的 Unterm 产品功能，并透明地将请求路由到本地 MCP 服务。新集成应使用 unterm-cli mcp-stdio 或直接使用 unterm-cli；它们会按正确顺序解析 core.json、运行中的 GUI 实例记录和旧版文件。绕过 CLI 的脚本可以读取 Core 平台数据目录（%LOCALAPPDATA%\Unterm、~/.local/share/Unterm、~/Library/Application Support/Unterm）中的 core.json，以获取 Core MCP 端点；读取 ~/.unterm/instances/<name>.json，以获取特定 GUI 实例；或读取 ~/.unterm/server.json，以获取旧版活动 GUI 指针。注意，这两个目录并不相同：只有 Core 的记录存放在 ~/.unterm 之外。

# Settings + Web UI
unterm-cli settings open                       # open the Web Settings page
unterm-cli theme list / set <id>               # agent-inbox / standard / midnight / daylight / classic / notion-dark / notion-light
unterm-cli lang list / set <code> / current    # en-US / zh-CN / zh-TW / ja-JP / ko-KR / de-DE / fr-FR / it-IT / hi-IN

# Proxy
unterm-cli proxy status                        # auto-detect health
unterm-cli proxy nodes / switch <name> / disable / env / rotation

# Agent Cockpit
unterm-cli agent status                        # per-pane agent state (working/waiting/idle/done)
unterm-cli agent inbox                         # agents waiting for you, longest first
unterm-cli agent enable-hooks [--dry-run]      # wire Claude Code / Codex / Aider lifecycle hooks
unterm-cli fleet launch --agents claude,codex "task"   # N agents × N worktrees, one tab each
unterm-cli fleet list / clean
unterm-cli review list / diff / merge / discard / rollback
unterm-cli review open                         # Review page in the browser

# Capability providers — the browser and anything else outside this process
unterm-cli provider list                       # what can be reached, and what conflicts
unterm-cli provider bind unzoo                 # contact it; the first bind pins who answered
unterm-cli provider diagnose unzoo             # handshake, lease, evidence, idempotency, replay
unterm-cli provider acquire browser --ttl 300  # ask for a lease; answers `waiting` when it is not there
unterm-cli provider call <lease> tab_list --seq 1 --capability browser
unterm-cli provider chain <lease>              # lease → grant → approval → the calls made under it
unterm-cli provider approvals                  # what is waiting on you (answer these in Settings)
unterm-cli provider pause / resume / unbind / revoke <lease>

# Workspaces — named roots that cannot see each other
unterm-cli scope create alpha ~/code/alpha
unterm-cli scope check <workspace> <path> [--access write]
unterm-cli scope list / archive <workspace>

# What tasks produced, and proving it to somebody who was not there
unterm-cli artifact list [--task <id>] / usage / verify <id> / forget <id>
unterm-cli evidence export <task> ./bundle     # the whole story as plain files + hashes
unterm-cli evidence verify ./bundle            # recomputes; does not take your word for it
unterm-cli evidence audit                      # walk the audit hash-chain, report the first break

# The processes, and the data behind them
unterm-cli system status                       # core / gui / mcp, and "can work without a window"
unterm-cli system diagnostics [--out FILE]     # redacted: versions and health, no tokens or paths
unterm-cli system snapshot / snapshots / restore <id>
unterm-cli system upgrade --live X --staged Y --to 0.69.0   # rolls back if the new one does not answer
unterm-cli system installs                     # every copy on this machine, and which ones fight
unterm-cli system uninstall-plan [--remove-data]            # describes; never removes

# Sessions / panes
unterm-cli session list                        # list panes in active/latest instance
unterm-cli instance list                       # discover alpha/bravo/... windows
unterm-cli --instance bravo session list       # pin a command to one window
unterm-cli session create [--cwd DIR] [-- CMD] # spawn a new tab
unterm-cli --json session create -- pwsh.exe -NoLogo -NoProfile -Command "Write-Output ok"
unterm-cli session record start [--id N]
unterm-cli session record stop [--id N]
unterm-cli session export [--id N] [-o FILE]
unterm-cli sessions list [--project SLUG]
unterm-cli sessions read <session-id>

# Screenshots
unterm-cli screenshot [--include-window] [-o FILE]
# Long screenshot of a pane's ENTIRE scrollback (headless re-render -> tall PNG)
unterm-cli screenshot --scrollback [--pane N] [--max-rows N] [-o FILE]
# Long screenshot of ANOTHER app's window: scroll + stitch (macOS)
unterm-cli screenshot --scroll-app Safari [--scroll-title SUBSTR] [--max-frames N] [-o FILE]

为任何子命令传入 --json，即可获得原始 JSON-RPC 输出（适用于脚本）；请将其放在 -- CMD 之前，以便由 unterm-cli 而非子命令解析。session create 会将多词命令保留为 argv，而单个命令字符串仍会通过平台 Shell 运行。传入 --lang <code> 可覆盖单次调用的区域设置。当打开了多个 Unterm 窗口且需要确定性地指定目标时，请传入 --instance <id>（或设置 UNTERM_INSTANCE=<id>）。

可通过 MCP 和 CLI 发现多实例：调用 instance.list、运行 unterm-cli instance list，或检查 ~/.unterm/instances/。

AI Agent 自动发现

Unterm 会让这台机器上的所有 AI 编码 Agent 都知道它的存在，因此它们无需手动配置即可操作终端。首次启动时（每个版本一次），GUI 会运行 unterm-cli setup-ai，检测已安装的 Agent——Claude Code、Codex、Gemini CLI、Cursor、Windsurf、OpenCode——并为每个 Agent：

• 将 unterm MCP 服务注册到 Agent 的全局配置中（合并到现有配置，不会覆盖），这样 Agent 一启动，就能列出、运行、读取和截取真实终端的屏幕；
• 在 Agent 的全局上下文文件（CLAUDE.md / AGENTS.md / GEMINI.md）中添加一条简短、带标记分隔的 Unterm 说明，让即使从未加载 MCP 服务的 Agent 也知道 Unterm 已就绪。

注册的桥接程序（unterm-cli mcp-stdio）会在连接时自行发现正在运行的控制服务，优先选择 unterm-core，找不到时则回退到 GUI 实例记录，因此静态注册在重启和多个窗口之间始终有效。连接的 Agent 还会通过 MCP initialize 的 instructions 字段收到使用简介。

unterm-cli setup-ai              # detect agents + register (idempotent; safe to re-run)
unterm-cli setup-ai --dry-run    # show what would change, write nothing
unterm-cli setup-ai --no-context # register the MCP server only, don't touch context files
unterm-cli setup-ai --remove     # undo: strip the server entry + context block from every agent

---

配置

用户配置位于：

平台	位置
macOS	~/.unterm/
Linux	~/.unterm/
Windows	%USERPROFILE%\.unterm\

文件：

文件	用途
core.json	无头 Core 端点 + 身份验证令牌 + pid（MCP 自动化的首选）
server.json	活跃 GUI 实例的 MCP/HTTP 端口 + 身份验证令牌 + pid（自动生成，用于向后兼容，与活跃 GUI 同步）
active.json	指向当前活跃 GUI 实例 id 的指针（自动生成，仅在先前的活跃实例退出后更新）
instances/<name>.json	每个实例的元数据（NATO id、端口、令牌、pid、started_at、版本、平台）
auth_token	活跃身份验证令牌的旧版镜像（用于向后兼容）
proxy.json	自动/手动代理 URL、排除项、节点、轮换和 Clash 控制器状态
theme.json	活跃主题 id
lang.json	持久化的区域设置覆盖
compat.json	针对 $TERM_PROGRAM 的 {"term_program": "..."} 覆盖
scrollback.json	覆盖默认回滚行数
update_check.json	后台更新轮询器状态（上次检查时间、最近发现的版本）
onboarded.json	首次运行标记（已查看哪些 ▼ 项）
recording.json	录制配置（脱敏模式等）
unterm.conf	终端配置：字体、颜色、窗口、Shell、[env]、[keys]——参见配置参考
tasks.db	持久化任务存储；Agent Cockpit 机群（成员、工作树、分支、审核状态）存储于此。旧版 fleets.json 会导入一次。
checkpoints.json	每个仓库中 Agent 开始工作前的快照（悬空提交 SHA、每个仓库最近 20 个）
sessions/	录制元数据索引（按项目划分的子目录）
screenshots/	区域截图（PNG）

---

开发

前置条件：较新的稳定版 Rust 工具链。Linux 还需要 get-deps 中列出的系统依赖。

make build        # all binaries (debug)
make check        # static checks
make test         # tests
make clean-release-artifacts  # remove local dmg/msi/zip/deb/AppImage packages

为当前平台构建发布版：

cargo build --release -p unterm -p unterm-cli -p unterm-mux -p strip-ansi-escapes

构建平台软件包：

# macOS — universal .app + zip (run on macOS)
ci/deploy.sh

# Linux — .deb
ci/deploy.sh
# Linux — AppImage
ci/appimage.sh

# Windows — staged release tree + zip
bash ci/deploy.sh
# Windows — MSI (requires WiX 6 at .\.tools\wix.exe — install via `dotnet tool install --tool-path .\.tools wix --version 6.0.1`)
pwsh -File ci/build-msi.ps1

macOS 代码签名和公证仅在本地进行（没有 CI 步骤），因此 Developer ID .p12 私钥无需离开你的 Mac。一次性设置，在保存证书的 Mac 上执行：

xcrun notarytool store-credentials UntermNotary \
  --apple-id <your-apple-id> --team-id 6NQM3XP5RF

发布标签

Unterm 发布标签可以使用次版本标签（v0.50）或修订版本标签（v0.50.0）。使用与此次发布的更新日志和软件包版本相匹配的标签形式。只有在一批完整的修复／功能准备就绪，可以发布时，才创建标签。

git tag -a vX.Y.Z -m "Unterm vX.Y.Z" && git push origin vX.Y.Z
make release-mac                    # build universal + sign + notarize + upload

make release-mac 会从 git describe --exact-match HEAD 读取标签， 构建通用的 x86_64+aarch64 二进制文件，调用 ci/sign-macos.sh 并设置 NOTARY_PROFILE=UntermNotary，然后通过 gh release upload 将生成的 DMG 上传到对应的 GitHub Release。完成本地验证／上传后，运行 make clean-release-artifacts，以移除根目录下的发布软件包，同时保留 构建缓存。

每个 PR 上的 CI 都会针对 macOS、Linux 和 Windows 运行 cargo check。 推送标签（vX.Y 或 vX.Y.Z）会触发 release-linux 和 release-windows 工作流，将这两个平台的构建产物发布到 GitHub Releases。 macOS 按设计不参与 CI，详见上文。

---

仓库

此仓库是 Unterm 主项目：

https://github.com/zhitongblog/unterm

Unterm 包含经过修改的 WezTerm 组件。上游 WezTerm 仍是 Wez Furlong 及其贡献者维护的独立项目。

大使

Unterm 由一支规模很小的团队开发，因此大多数人都是经由其他开发者介绍而认识它的。如果你写过、录制过或谈论过 Unterm，分享链接——无需注册——我们会在 unterm.app/ambassador 上列出你的名字。请遵守几条基本准则：说明自己是用户，用自己的话撰写，只在欢迎自我推广的地方发布，不要使用虚假账号、虚假评价或购买星标。

---

如果 Unterm 为你节省了时间，请在 GitHub 上为它点星——这是其他人发现它的主要方式。