NextShell

NextShell 是一个基于 Electron + React + TypeScript 的桌面运维客户端，使用 pnpm Workspace 管理应用与共享包。

• SSH 连接管理：分组、搜索、收藏、快速连接
• 多会话终端：标签页、重连、认证重试
• SFTP 能力：远程/本地文件浏览、上传下载、打包传输、传输队列
• 远程编辑：内置编辑器与外部编辑器联动
• 运维工具：命令中心（批量执行）、Ping、Traceroute、端口转发
• 资源监控：系统、进程、网络监控（无 agent）
• 安全与数据：主密码、系统钥匙串（keytar）、本地 SQLite 存储、备份/恢复
• 资产导入：支持连接导入与 FinalShell 数据导入预览

• Monorepo：pnpm Workspace
• 桌面端：Electron（main/preload/renderer）+ React + Vite + Tailwind CSS
• 类型与契约：TypeScript + Zod
• 原生依赖：better-sqlite3、keytar、ssh2

• apps/desktop: Electron 应用入口
• apps/desktop/src/main: 主进程服务、IPC 注册、系统集成、Agent（MCP）端点
• apps/mcp-bridge: MCP stdio 桥接进程，把 MCP 客户端接到运行中的桌面端
• apps/desktop/src/preload: 安全桥接 API（window.nextshell）
• apps/desktop/src/renderer: 前端 UI、状态管理、业务逻辑
• packages/core: 核心领域类型与偏好模型
• packages/shared: IPC channel、合同类型、跨端共享常量
• packages/ssh: SSH/代理相关抽象
• packages/storage: 存储层能力（SQLite 相关）
• packages/security: 安全能力（如 keytar 封装）
• packages/terminal: 终端会话相关抽象
• packages/ui-kit: 共享 UI 组件

• Node.js 24.x
• pnpm 11.15.1（由根目录 packageManager 固定）
• macOS 或 Windows（CI 默认构建这两个平台）
• 建议安装可用的本地构建工具链，用于编译/重建原生模块

pnpm run setup
pnpm run dev

pnpm run setup 会按锁文件安装依赖并重建原生模块，适合首次拉取仓库后直接使用。

若出现 NODE_MODULE_VERSION 不匹配（常见于 better-sqlite3 / keytar / ssh2）：

1. 执行 pnpm run rebuild:native
2. 若仍失败，执行 pnpm run setup
3. 在 Node.js / Electron 版本变化后再次执行 pnpm run setup

Electron 与独立 Node.js 进程使用不同 ABI。pnpm run dev 会先切换到 Electron ABI， pnpm run test:node 会先恢复 Node.js ABI；在 Node.js 下手动运行主进程相关产物前可执行 pnpm run rebuild:native:node。（apps/mcp-bridge 不含原生依赖，不受此影响。）

若本地终端打开时报错 posix_spawnp failed：

• 这通常是开发环境或未正确重建原生模块的本地运行问题，不是 shell 配置错误，也不表示业务代码回归。
• 在标准 electron-builder release 打包流程下通常不会命中，因为打包产物会优先使用 node-pty/build/Release/spawn-helper。
• 常见原因是 macOS 开发环境中的 node-pty/prebuilds/.../spawn-helper 缺少执行位，导致本地终端无法拉起 shell。

建议按以下顺序恢复：

1. 执行 pnpm run rebuild:native
2. 若仍失败，执行 pnpm run setup
3. 若问题仍在，删除依赖后重新安装，再重复执行 pnpm run setup

• 非 tag 本地构建版本格式：<apps/desktop版本>-dev+<shortSha>
• 若无法读取 git SHA：<apps/desktop版本>-dev+unknown
• CI 发布通过环境变量 NEXTSHELL_BUILD_VERSION 注入版本
• Tag 触发工作流：.github/workflows/release-electron.yml
• 仅接受 SemVer tag（v1.2.3 或 1.2.3），且 tag commit 必须位于 main 分支祖先链上

• NEXTSHELL_BUILD_VERSION: 覆盖构建版本号（CI 发布使用）
• NEXTSHELL_GITHUB_REPO: 更新检查目标仓库（默认 HynoR/NextShell）
• VITE_GITHUB_REPO: 兼容变量，同样用于更新检查仓库配置

提交 PR 前建议至少运行：

pnpm run typecheck
pnpm run test
pnpm run test:node

• 云同步使用手册
• 架构说明
• IPC 契约

本项目使用 GNU GPLv3，详见 LICENSE。