nodeterm 项目概述

项目动机

传统终端标签页以栈式结构堆叠，运行上下文容易被隐藏，难以跟踪每个会话的真实状态。nodeterm 将这种栈式结构改造为空间化的画布：每个 shell 成为一个可拖动、可分组、可标注、可缩放的节点，会话在空间上保持并具备持久性，重启后心智模型依然完整。

应用围绕清晰的服务边界（service seam）构建，同一套画布可在三种形态下运行：

• 桌面应用（macOS 与 Linux）
• 自托管的浏览器应用（Server Edition），可从任意位置访问
• iOS 伴侣应用，可接入相同的实时会话

核心特性

一切皆为节点

右键画布即可创建终端或 AI 智能体（agent）。每个节点运行在独立的持久 tmux 会话中。除此之外还包含：

• 便签节点：可链接到 agent 作为上下文
• Monaco 编辑器节点
• 差异对比节点
• 网页/视频节点

退出应用甚至重启机器后，所有会话都能恢复。

Agent 状态感知

通过 hook 驱动（非输出抓取）实现状态识别：

• 脉冲式 RUNNING / NEEDS YOU 徽章
• 子 agent 卡片（含实时转录）
• 每节点上下文用量计
• 系统级通知

在 MacBook 上，agent 状态还会显示在刘海（notch）区域。

项目双视图

每个项目既是画布，又是看板（kanban）。卡片即实时会话：拖动卡片跨列时 agent 持续运行；点击卡片打开实时卡片弹窗（真实会话 + 成员、截止日期、优先级、评论），并支持分配团队成员。使用 ⌘⇧B 切换视图。

远程访问

扫描二维码即可配对 iOS 应用，同一会话在手机上继续，端到端加密，经由中继而非仅限局域网。Server Edition 让同一画布在任何浏览器中自托管运行。

语音输入

按住 ⌘⌥（macOS）或 Ctrl+Alt（Linux/Windows）并说话，本地 Whisper 进行转录，语音数据不离开本机。审查文本后点击发送（不会自动提交）。

节点类型

• 终端：xterm + tmux，支持 AI 自动命名
• Agent：Claude Code / Codex / Gemini / GitHub Copilot / opencode / Grok / 自定义
• 便签：可链接到 agent 作为上下文
• 分组：可绑定到 git worktree，实现每分支一个 agent
• 编辑器：Monaco，支持 ⌘S 保存
• 差异对比
• 网页 / 视频

其他重要能力

• 会话连续性（tmux）：终端在节点重挂载和应用完全重启后保持运行，包括活跃进程；机器重启后恢复回滚内容，agent 会话通过 claude --resume 继续。macOS 应用自带 tmux，开箱即用。
• Agent 增强：上下文链接、对话分支（仅 Claude）、多账号托管（managed accounts），以及内置的画布控制 CLI，agent 可驱动画布（打开节点、分派任务、互相验证工作）。
• 远程 / SSH 项目：在远程主机上通过 SSH 打开项目，终端、文件、git、看板均在远程运行，画布保持本地。
• 源码控制：VS Code 风格的暂存/取消暂存、撤销、分支切换/创建、提交、推送/同步/发布、worktree、gh 登录，全部由系统 git 提供支持。
• GitHub Issues 与看板：可选的 issue 卡片、精确的标签-列映射、双向移动/关闭/重新打开同步。
• AI 提交信息与终端命名：自带本地 agent CLI 以只读方式对暂存的差异或捕获输出运行。
• 电源与休眠：agent 工作中阻止机器空闲休眠，完成后立即释放（默认开启）。无法通过合盖保持唤醒，过夜任务需保持笔记本打开并接通电源，或使用 Server Edition。
• 命令面板（⌘K）、文件浏览器（⌘⇧E）、Markdown 视图（⌘M）、撤销/重做、原生 macOS 深色 UI。
• 自动更新与应用内公告：通过自托管的源进行检查，并提供"重启以更新"的横幅。

Server Edition

同一画布可在 Linux（或 macOS）主机上无头运行，从任意浏览器使用：终端、编辑器、源码控制、看板、agent 状态徽章均可在浏览器中工作。

# 启动开发服务器，浏览器访问 http://127.0.0.1:8443 并设置密码
npm run server:dev

推送通知主机

同一服务也可作为无头通知主机运行：安装到任意 Linux 主机上，手机即可接收 agent 的 RUNNING / NEEDS YOU 推送与 Live Activity 覆盖，无需开放任何端口（hook 服务仅绑定 loopback，推送通过 HTTPS 走 SSH 通道下放的授权）。

curl -fsSL https://raw.githubusercontent.com/eneskirca/nodeterm/main/scripts/install-server.sh | bash

一行命令完成安装、构建，并以 systemd 服务形式运行（NODETERM_HEADLESS=1），再次运行可更新。

键盘快捷键

快捷键	操作
⌘K	命令面板
⌘T / ⌘⇧C	新建终端 / 新建 Claude Code
⌘⇧B	切换看板
⌘W	关闭选中节点
⌘Z / ⌘⇧Z	撤销 / 重做
⌘M	切换 Markdown 视图
按住 ⌘⌥（Ctrl+Alt）	对焦终端语音输入
⌘⇧E	文件浏览器
⌘,	设置 · ⌘/ 快捷键
右键	操作菜单

所有快捷键均可在「设置 → 键盘快捷键」中重新映射。

技术架构

Electron 三上下文

• src/main：Electron 主进程外壳
• src/preload：唯一桥接层（window.nodeTerminal）
• src/renderer：React UI
• src/shared：所有三个上下文共享的类型与 IPC 通道名

CorePlatform 边界

所有服务（PTY、工作区/设置、git、agent、hooks）位于 src/core，通过小型平台接口暴露，从不直接导入 electron。Electron 是该边界的一种实现；浏览器版 Server Edition（src/server）是另一种实现，通过 WebSocket-RPC 桥接（src/renderer/bridge 在浏览器中填充 window.nodeTerminal）启动完全相同的服务。同一份代码库、同一份渲染层、多套外壳。

TerminalTransport 抽象

渲染层仅依赖此接口，不直接依赖 IPC 或 node-pty。LocalTransport 与本地主机通信；RemoteTransport 通过 SSH 与远程 agent 通信，远程项目无需改动画布 UI。

React Flow 作为单一事实源

React Flow 是活动节点的唯一事实源，项目将序列化节点持久化到磁盘，tmux 跨重启保持会话活跃。

三种表面

桌面应用、浏览器 Server Edition、移动伴侣应用（独立的 SwiftUI 仓库）均基于相同的 core + transport 边界构建。

构建与开发

需要 macOS 或 Linux 上的 Node.js 20+（推荐 tmux）。源码检出不包含打包好的 tmux：在 macOS 上运行一次 node scripts/build-tmux.mjs 构建到 resources/bin/tmux，或自行安装 tmux。

npm install        # 依赖 + 为 Electron ABI 重建 node-pty（postinstall）
npm run dev        # 开发模式，渲染层 HMR
npm run build      # 生产构建到 out/
npm start          # 预览生产构建
npm run typecheck  # 最快的正确性检查
npm test           # vitest 单元与集成测试
npm run dist       # 本地未签名的 .dmg 到 dist/
npm run dist:linux # 在 Linux 主机上生成 AppImage + .deb
npm run server:dev # 构建并运行浏览器 Server Edition（需要 Node 22 + tmux）

下载

• macOS：.dmg（Apple Silicon 与 Intel，支持自动更新），或通过 Homebrew 安装：

bash brew tap nodeterm/tap brew trust nodeterm/tap # Homebrew ≥6 拒绝加载未授信的 tap brew install --cask nodeterm

两行都需要；单独 brew install --cask nodeterm 会在 homebrew/cask 中搜索并报告找不到 cask。 - Linux（x64）：自更新的 AppImage，或用于 Debian/Ubuntu 的 .deb（sudo apt install ./nodeterm-*.deb，.deb 更新需手动）。 - iOS：在 App Store 搜索 nodeterm mobile。

许可证

采用 BUSL-1.1（Business Source License 1.1）：可自由复制、修改、再分发，并在