nexuscrew

# 极光船员 [](https://www.npmjs.com/package/@mmmbuto/nexuscrew) [](LICENSE) [](https://nodejs.org) [](#platform-support) 极光船员是一个本地优先的Web控制面板，用于tmux会话和AI CLI工作器。它将真正的PTY流式传输到浏览器，组织会话为持久的卡组，并通过SSH连接多个极光船员安装，而无需替换tmux或现有的SSH设置。 <p align="center"> <img src="docs/img/fleet-deck-desktop.png" width="960" alt="极光船员桌面界面，显示多个实时的tmux会话，排列成卡组"> </p> 极光船员绑定到`127.0.0.1`，使用本地令牌验证PWA，并将会话所有权交给tmux。它没有托管的控制服务，用户账户系统或公共网络监听器。 ## 概述 | 区域 | 极光船员提供的内容 | |---|---| | 终端 | 通过WebSocket和xterm.js实现真正的PTY附件到实时的tmux会话 | | 工作空间 | 命名卡组，瓷砖式桌面布局，移动会话视图，保存的排序，固定和每个单元格的合成器状态 | | 船队 | 可重复使用的单元格，引擎，提供者，模型，权限策略，提示，启动状态和实时工作状态 | | 节点 | 单链接配对和所有者限定路由，基于受监督的OpenSSH连接 | | 操作 | 后台服务，启动集成，诊断，稳定的npm更新和选择性备份 | | AI集成 | 用于操作员通信，卡组发现和单元格间传递的标准输入/输出MCP桥接 | 浏览器是一个客户端，而不是会话主机： ```text 浏览器PWA │ 认证的HTTP + WebSocket在环回 ▼ 极光船员 ── 真实的PTY ── tmux会话 │ ├── 受监督的OpenSSH ── 远程极光船员节点 │ └── 标准输入/输出MCP桥接 ── Claude Code / Codex / Codex-VL / Pi ``` ## 安装 ### 要求 - Node.js 18或更新版本 - tmux 3.4或更新版本 - OpenSSH客户端（`ssh`）用于节点连接和干净的诊断结果 - Linux x64/ARM64，macOS x64/ARM64或Android ARM64通过Termux 极光船员提供脚本化的PTY预构建，适用于支持的目标。正常的全局安装不需要编译器或原生安装脚本批准。 ### Linux 使用发行版包管理器安装Node.js，tmux和OpenSSH，然后： ```bash npm install -g @mmmbuto/nexuscrew nexuscrew ``` ### macOS ```bash brew install node tmux npm install -g @mmmbuto/nexuscrew nexuscrew ``` ### Android / Termux ```bash pkg update pkg install nodejs-lts tmux openssh npm install -g @mmmbuto/nexuscrew nexuscrew ``` 首次运行时，创建仅限环回的运行时，在后台启动它，打开PWA，并呈现设置向导。后续运行重用已配置的服务，打印紧凑状态，然后退出。 首选端口是`41820`。如果另一个进程拥有它，极光船员选择下一个可用的环回端口并记录结果。 ## 命令行界面 PWA仍然是视觉控制表面，而CLI公开了无头主机和VPS安装的完整对等工作流。 | 命令 | 目的 | |---|---| | `nexuscrew` | 启动或重用后台运行时并打印简短状态 | | `nexuscrew init [--dry-run] [--port PORT]` | 初始化缺失的本地存储，幂等或预览操作 | | `nexuscrew show` | 在需要时启动并打开认证的PWA | | `nexuscrew show token` | 打印认证的浏览器链接而不打开它 | | `nexuscrew status` | 显示服务，端口，角色和节点状态 | | `nexuscrew stop` | 停止极光船员及其管理的隧道而不停止tmux会话 | | `nexuscrew restart` | 重启极光船员并在不停止tmux的情况下恢复自动启动节点链接 | | `nexuscrew boot` | 启用启动持久性 | | `nexuscrew boot off` | 禁用启动持久性，同时保持当前运行时活动 | | `nexuscrew doctor` | 检查Node，PTY，tmux，SSH，服务和平台集成 | | `nexuscrew nodes list [--json]` | 列出直接中心，连接的客户端和路由的只读对等体 | | `nexuscrew nodes inspect <name\|nodeId>` | 检查对等体的稳定身份 | | `nexuscrew nodes edit <name\|nodeId> ...` | 更改规范标签或方向特定的连接设置 | | `nexuscrew nodes up\|down\|connect\|disconnect\|restart\|reconnect <name\|nodeId>` | 在不需要PWA的情况下管理直接节点链接 | | `nexuscrew nodes share <name\|nodeId> on\|off` | 发布或撤销直接节点到授权网络 | | `nexuscrew nodes remove <name\|nodeId> --yes` | 在明确确认后撤销/忘记直接对等体 | | `nexuscrew nodes invite --ssh <target>` | 从无头中心创建一次性配对链接 | | `nexuscrew nodes pair\|join` | 从标准输入读取一次性配对链接并无头加入 | | `nexuscrew help` | 显示命令帮助 | | `nexuscrew version` | 显示已安装的版本 | 启动集成使用Linux上的用户systemd服务，macOS上的LaunchAgent和Android上的Termux：Boot脚本。Termux用户必须安装Termux：Boot应用并打开它一次；CLI可以验证脚本但不能证明Android应用激活。 标记为`boot:true`的单元格在该平台启动集成运行时启动。这是启动持久性，而不是tmux服务器本身的监视器：如果整个tmux服务器稍后消失，启动伴侣不会自动重新运行。 ## 船队：单元格，引擎和提供者 **单元格**是一个可重用的工作器定义：tmux会话名称，工作目录，引擎，模型，权限策略，可选系统和启动状态。启动停止的单元格会打开桌面和移动设备上的相同启动表，以便在进程启动前可以查看有效设置。 **引擎**描述如何启动CLI。干净的安装包括四个基本适配器： - Claude Code - Codex - Codex-VL - Pi 提供者目录的作用域限定于所选CLI，而不是机器特定的设置： | CLI | 内置提供者选择 | |---|---| | Claude Code | Anthropic, Alibaba Token Plan Personal, OpenRouter, Kimi Code, Amazon Bedrock, Google Vertex AI, Microsoft Foundry, Ollama Cloud, local Ollama, Z.AI, 自定义Anthropic兼容端点 | | Codex | OpenAI 或 ChatGPT 登录，OpenAI API，Ollama Cloud，本地 Ollama，LM Studio，自定义 OpenAI 响应端点 | | Codex-VL | OpenAI 或 ChatGPT 登录，OpenAI API，Alibaba Token Plan Personal，OpenRouter，Ollama Cloud，本地 Ollama，LM Studio，自定义 OpenAI 响应端点 | | Pi | 原生默认，Anthropic，OpenAI API，Alibaba Token Plan Personal，Codex OAuth，Gemini，GitHub Copilot，OpenRouter，Ollama，DeepSeek，Z.AI，自定义提供者 | 自定义Codex兼容端点使用真实的响应线API；极光船员不会静默地回退到聊天补全。还支持自定义的基于argv的引擎，并在信任边界验证后直接启动，无需shell。 OpenRouter是Claude Code和Codex-VL的一流服务。Claude使用OpenRouter的Anthropic Messages兼容端点，而Codex-VL使用具有直接基于命令的身份验证且无shell的测试版无状态响应端点。由于提供者/模型兼容性可以独立更改，因此所选的OpenRouter模型保持明确。打包的Kimi K3配置文件固定其一百万令牌元数据，而不是回退到较小的通用窗口。 Kimi Code是Kimi会员密钥的单独Claude Code提供者。它默认为`k3[1m]`，使用`https://api.kimi.com/coding/`，并使用隔离的Claude配置，以便原生Anthropic帐户保持不变。Kimi Code会员密钥与Moonshot按需付费API密钥不可互换。 Alibaba Token Plan Personal是Claude Code、Codex-VL和Pi的单独托管配置文件。它仅使用`ALIBABA_CODE_API_KEY`，默认为`qwen3.8-max-preview`，并且没有OpenAI或按需付费的回退。npm包还包括用于干运行先前的Wan图像/编辑和HappyHorse视频工作流的可移植`alibaba-token-media`技能。Claude Code、Codex、Codex-VL和Pi可以直接调用其依赖项无关的Python CLI；Pi不被假定为原生支持MCP。媒体生成始终需要明确的信用同意，并且在安装、测试或启动期间永不运行。 每个单元格和引擎的权限处理是明确的： - Claude引擎可以使用标准权限或`--dangerously-skip-permissions`。 - Codex和Codex-VL可以使用标准权限或`--dangerously-bypass-approvals-and-sandbox`。 - Pi使用其原生权限行为。 提供者密钥在启动进程的节点上解析。极光船员可以使用服务环境，兼容的用户拥有提供者文件或可选的节点本地写入权限存储。PWA报告变量是否配置，但从不返回其值。密钥从船队定义，备份，API响应，tmux状态，进程参数，临时文件和日志中排除。 具有固定变量的内置提供者公开一个专用的**KEY**部分在引擎编辑器中。它仅显示变量名，配置的源和所选节点上的受影响引擎。替换或删除共享密钥会警告哪些引擎使用它；输入的值在浏览器中是暂时的，仅写入节点本地凭证存储。 ### 内置船队所有权 极光船员是唯一的船队管理器。单元格和引擎定义，生命周期，启动所有权，重启监督和写入凭证都由内置运行时处理；不发现或调用外部`fleet`可执行文件。`nexuscrew-fleet.service`是可选的极光船员启动伴侣，仅启动标记为`boot:true`的单元格。 设置`NEXUSCREW_FLEET=0`以完全禁用船队。 ## 工作空间和终端行为 桌面卡组将多个实时终端放入保存的瓷砖布局。卡组默认情况下附加到当前PWA；`↗`将其分离到另一个浏览器窗口。会话和卡组顺序可以通过指针拖放或键盘控件更改并自动保存。 在移动设备上，位置可以独立折叠和按以下条件筛选：全部，已固定，活动，关闭或技术会话。相同的拥有者限定排序模型用于紧凑和展开的桌面视图。 <p align="center"> <img src="docs/img/fleet-mobile.gif" width="420" alt="极光船员移动船队视图，显示托管单元格和会话控件"> </p> 终端附件默认使用`tmux attach -f ignore-size`。因此，手机或狭窄的浏览器无法调整另一个终端客户端持有的会话。移动控件公开复制模式滚动，窗口和窗格导航，退出，Ctrl-C和分离。长文本和多行提示使用终端应用程序的有括号粘贴模式；剪贴板图像和拖放的文件存储在选定的会话收件箱中，并在不提交回车的情况下插入其路径。 输入合成器可以扩展以适应较长的提示。每个拥有者限定的tmux单元格在当前浏览器中保留其自己的草稿，大小偏好和有界提示历史，包括在文本区域边界处的安全上箭头/下箭头召回。此浏览器本地状态不被联合或包含在船队备份中，可以从设置→系统清除。 ## 通过SSH连接节点 每个安装都作为本地节点启动。节点通过单个配对链接或二维码加入另一个极光船员安装： 1. 在可访问的安装中，打开**设置→节点→邀请节点**。 2. 提供其他设备可以使用的OpenSSH目标，例如`user@host`或本地SSH配置别名。SSH端口，身份，代理，ProxyJump和主机密钥策略保留在用户的OpenSSH配置中。 3. 在加入的设备上，打开**设置→节点**，粘贴完整的配对链接，然后选择**测试和连接**。链接是配对有效载体；它不是要打开的浏览器地址。 4. 如果便携式地址无法选择正确的密钥，请打开**高级/编辑**并替换为已经可用的SSH别名。 高级设置将本地显示标签与本地路由句柄分开。路由默认为可读的斜杠加上稳定的节点ID后缀，以便所有报告主机名的设备仍然接收不同的句柄。如果中心报告冲突，极光船员应用其确定性的建议，并让设备使用相同的邀请重试。 极光船员为中心连接创建一个受监督的`ssh`进程，并在报告成功之前验证转发TCP端点。它不生成SSH密钥，编辑`authorized_keys`，或使用`autossh`作为隐藏的第二个监督程序。 新加入的设备默认情况下是私有的。启用**通过选定的中心共享此设备**会在现有的SSH进程中添加一个经过验证的反向通道。然后，中心决定授权的对等体是否看到整个网络，仅看到中心或显式的子集。客户端不需要对彼此具有直接的SSH可达性。 保留的反向端口在活动和待配对之间进行探测，并在使用前通过持久唯一性检查进行保护。共享存储为所需状态；激活失败会回滚到私有状态，而停用失败则保持私有，并在重启后协调。如果出现同名对等体或延迟分配冲突，则返回一个可操作的冲突，而不是静默地创建重复记录或消耗邀请。 共享控件分别报告期望的发布和验证的隧道可达性。如果一个分离的进程在升级后带有过时的`-R`参数生存下来，**重新连接和协调**应用当前的复选框状态，而不更改同意，并仅在保存的命令不同的情况下替换验证的极光船员监督程序。 OpenSSH密钥限制在全局`AllowTcpForwarding`启用后仍然适用。共享客户端需要其接受的中心密钥来允许确切的协商反向监听器，例如`permitlisten="127.0.0.1:44002"`；操作性隧道诊断打印实际所需的端口。极光船员从不编辑`authorized_keys`，因此此策略仍然是中心操作员的显式操作。 节点组可以在每个浏览器中独立重新排序，从桌面和移动列表中。它们的易读标签有一个服务器支持的源：从设置或名册中重命名，并且相同的规范标签在所有地方出现，而不会更改技术路由名称，节点身份，凭证，共享状态或卡组身份。 配对链接包含短期的单次邀请和路由字段，但不包含SSH私钥，提供者密钥或PWA令牌。节点和卡组身份在网络上保持所有者限定，每个路由的HTTP或WebSocket请求重新检查授权，跳数和循环规则。 ## 访问和安全模型 极光船员仅监听`127.0.0.1`。要使用远程安装，请通过SSH或您控制的VPN将环回端口带到您的设备： ```bash ssh -L 41820:127.0.0.1:41820 user@your-host ``` 然后打开由`nexuscrew show token`返回的认证链接。令牌存储在用户专有文件中，并在URL片段（`#token=...`）中传输，因此它不会在初始HTTP请求中发送或写入服务器访问日志。 安全边界故意很窄： - 仅限环回绑定；拒绝非环回绑定 - 每个API和WebSocket连接的本地承载令牌 - tmux仍然是会话授权者 - OpenSSH仍然是网络和身份授权者 - 提供者凭证保留在使用它们的节点上 - 文件操作拒绝遍历和符号链接逃逸 - 船队和联合变更经过模式验证和ACL检查 不支持通过反向代理，公共端口转发或网络绑定直接公开。 ## 备份和更新 设置→船队可以导出和恢复选定的单元格，系统提示和可重用的引擎定义。恢复预览冲突，支持逐项选择，并报告需要重启的活动单元格。存档包含凭证变量名，永不凭证值，令牌或实时tmux状态。 全局npm安装可以自动跟随稳定的`latest`标签。极光船员序列化更新，验证新的CLI和相同端口运行时，并在运行状况检查失败时回滚到确切的先前版本。它从不从`latest`安装预发布版本或降级。更新状态和手动控制在设置→系统可用；设置`NEXUSCREW_AUTO_UPDATE=0`以禁用调度程序。 在Linux上，生成的用户服务使用`KillMode=process`，因此重启极光船员不会停止共享的tmux服务器。当无法验证此保护时，生命周期命令关闭。 ## MCP 桥接 `nexuscrew mcp` 将本地已认证的运行时暴露为一个无依赖的 stdio MCP 服务器。 它旨在用于在托管的 tmux 单元格中运行的 AI 会话。 | 工具 | 用途 | |---|---| | `nc_notify` | 向操作员发送 PWA 通知 | | `nc_ask` | 提出一个非阻塞问题，并将答案返回给调用会话 | | `nc_send_file` | 将调用者主目录中的文件放入其可下载的输出框中 | | `nc_status` | 读取实时的 tmux 和 Fleet 状态 | | `nc_inbox` | 列出调用者接收到的文件 | | `nc_deck` | 发现包含调用 tmux 会话的拥有者限定槽 | | `nc_cells` | 列出跨可见节点的授权活动和非活动 Fleet 单元格 | | `nc_send_cell` | 将有界文本提交到由 `nc_cells` 返回的精确活动单元格 | | `nc_identity` | 只读身份诊断；可调用，无会话，无令牌 | 单元格交付使用带括号的粘贴，然后是单独的 Enter。`submitted` 回执确认 交付到目标 TUI，而不是由其模型接受或完成。没有无声 离线队列。 `nc_identity` 仅返回非敏感数据：调用者解析的 `source` （`tmux`、`NEXUSCREW_MCP_SESSION` 或 `missing`），身份环境变量的布尔存在， 稳定的 `code`（`OK`、`NEXUSCREW_MCP_IDENTITY_MISSING`、`NEXUSCREW_MCP_IDENTITY_INVALID`）和 修复提示。它从不调用 HTTP API 或读取令牌，因此即使在 身份缺失时也有效 - 使用它来诊断为什么身份门控工具关闭失败。 在 Claude Code 中注册桥接： ```json { "mcpServers": { "nexuscrew": { "command": "nexuscrew", "args": ["mcp"] } } } ``` 或在 Codex / Codex-VL 中（`env_vars` 允许变量 **名称**，而非值复制 到 CLI 或配置文件）： ```toml [mcp_servers.nexuscrew] command = "nexuscrew" args = ["mcp"] env_vars = ["NEXUSCREW_MCP_SESSION", "TMUX", "TMUX_PANE"] ``` Codex-VL 构建中，等效的 CLI 形式支持 `--env-var`（按名称允许，重复）： ```text codex-vl mcp add nexuscrew \ --env-var NEXUSCREW_MCP_SESSION \ --env-var TMUX \ --env-var TMUX_PANE \ -- nexuscrew mcp ``` 调用者按顺序解析，从其 tmux 会话（`tmux display-message -p '#S'`）， 然后从 `NEXUSCREW_MCP_SESSION` 回退，最后不解析。Codex/Codex-VL 启动 MCP stdio 进程时清除环境，因此这些客户端必须显式允许列出身份 环境变量，以便服务器观察它们；否则，身份门控工具（`nc_ask`、`nc_send_file`、 `nc_deck`、`nc_send_cell`、`nc_inbox`）保持关闭失败，带有稳定的 `NEXUSCREW_MCP_IDENTITY_*` 代码，而 `nc_notify` 降级为未知发送者。 ## 配置 运行时状态特定于当前用户： | 路径 | 内容 | |---|---| | `~/.nexuscrew/config.json` | 端口、Fleet 模式和运行时选项 | | `~/.nexuscrew/token` | 本地 PWA 持有者令牌 | | `~/.nexuscrew/credentials.json` | 可选的节点本地写入提供程序存储 | | `~/.nexuscrew/tunnels/` | 托管 SSH 监督状态和所有者专属日志 | | `~/NexusFiles/<session>/` | 每会话收件箱和发件箱 | 常见的环境覆盖包括 `NEXUSCREW_PORT`、`NEXUSCREW_CONFIG_FILE`、 `NEXUSCREW_TOKEN_FILE`、`NEXUSCREW_FILES_ROOT`、`NEXUSCREW_TMUX`、 `NEXUSCREW_FLEET=0`、`NEXUSCREW_READONLY=1`、`NEXUSCREW_AUTO_UPDATE=0` 和 `NEXUSCREW_DEBUG=1`。 ## 平台支持 | 平台 | 架构 | 后台集成 | PTY 提供程序 | |---|---|---|---| | Linux | x64, ARM64 | systemd 用户服务或分离运行时 | 打包的原生预构建 | | macOS | x64, ARM64 | LaunchAgent 或分离运行时 | 打包的原生预构建 | | Android / Termux | ARM64 | 分离运行时和可选 Termux:Boot | Android ARM64 包 | 在安装后或在设备之间移动配置时运行 `nexuscrew doctor`。 缺少 OpenSSH 客户端是一个阻塞诊断；`autossh` 单独报告并保持 可选，因为 NexusCrew 直接监督 OpenSSH。 ## 开发 ```bash npm test # 隔离的 Node 测试和前端测试 npm run build # 将 PWA 构建到 frontend/dist node bin/nexuscrew.js serve ``` 测试 tmux 使用私有套接字，必须从不附加到或终止 操作员的 tmux 服务器。 ## 路线图 下一架构轨道是一个可选的 MCP 网关：一个 NexusCrew MCP 端点，带有 上游 MCP 服务器的本地目录和通过共享节点的显式、按工具联合。 凭据和执行将保留在所有者节点上，拥有所有者限定工具身份 和读取/变异 ACL。该网关是计划工作，**不是当前版本的一部分**。 参见 [CHANGELOG.md](CHANGELOG.md) 获取已发布的更改。 ## 状态 当前稳定版本是 **v0.8.26**，在 npm 和 GitHub 上。 ## 许可证 Apache-2.0 © 2026 Davide A. Guglielmi (DioNanos)