zhaolei/NetMesh
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
NetMesh/ET_INTEGRATION_CHECKLIST.md

220 lines
15 KiB
Markdown
Raw Permalink Normal View History

[Init] Initial commit - NetMesh terminal manager
2026-09-13 18:24:01 +08:00
# EternalTerminal (ET) 集成清单 — 按 Mosh 方式重做
> 目标：在上游最新架构（分支 `feat/et-history-reapply`，基于 `031bf0ee`）上，
> **完全照搬 Mosh 的方式**重新集成 EternalTerminal：
> 1. **打包客户端** —— 像 `mosh-client` 那样，把 `et` 客户端二进制构建 + 下载 +
> 捆绑进安装包，运行时只用捆绑的二进制（不依赖系统安装的 et）。
> 2. **接入协议** —— 把旧分支 `feat/eternal-terminal`（tip `67e81616`）里的 ET
> 后端 + UI 重新落到上游重构后的目录结构上，并让它启动**捆绑的** `et`。
>
> 旧实现参考：`git show 67e81616`（共 7 个 ET 提交，见 `feat/eternal-terminal`）。
> Mosh 模板参考（**仅 MoshCatty 纯二进制路径**）：`resources/mosh/README.md`、
> `scripts/fetch-mosh-binaries.cjs`、`scripts/resolve-mosh-bin-release.cjs`、
> `scripts/mosh-extra-resources.cjs`、`electron/bridges/terminalBridge/moshSession.cjs`。
> 客户端本体在独立仓库 [binaricat/MoshCatty](https://github.com/binaricat/MoshCatty)
> （`moshcatty-*` releases）；Netcatty 内已无 Cygwin 构建流水线 / FluentTerminal 回退。
## 关键设计差异（ET vs Mosh）
- **协议**：Mosh 需要 Node 做 SSH bootstrap + 抓 `MOSH CONNECT` + 换 PTY
（`moshHandshake` + `moshSession`）。**ET 不需要** —— `et` 客户端自己完成 SSH
引导 + 协议握手，我们只要把 `et` 当作普通 PTY 进程 `pty.spawn` 即可。所以**没有**
`etHandshake.cjs`。
- **凭证注入**：Mosh 自己驱动 ssh、直接往 PTY 里敲密码；ET 内部驱动 ssh，需用
**SSH_ASKPASS + 临时 ~/.ssh 环境**把保存的密码/密钥/跳板/算法喂给 et 内部的 ssh
（旧实现 `prepareEtSshEnvironment` 已完整实现，直接搬运）。
- **纯二进制**：MoshCatty 与理想 ET 打包都是「每平台一个客户端文件」。Mosh 侧已
无 terminfo / Cygwin DLL 袋；`et` 同样本地不渲染终端。Windows 若动态链 CRT
才考虑可选 DLL 目录，否则只放 `et[.exe]`。
- **构建系统**：Mosh 客户端在 **MoshCatty** 仓库用 Rust 构建并发布；Netcatty 只
`fetch`。**ET** 用 CMake + Ninja + vcpkg
（`cmake -DDISABLE_TELEMETRY=ON -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo`），
产物是单个 `et`（Windows `et.exe`），由 `scripts/build-et/` + `build-et-binaries.yml` 发布。
## 命名约定（镜像 Mosh / MoshCatty）
| Mosh (MoshCatty) | ET |
|------|----|
| `resources/mosh/<plat-arch>/mosh-client[.exe]` | `resources/et/<plat-arch>/et[.exe]` |
| 打包后 `<Resources>/mosh/mosh-client` | 打包后 `<Resources>/et/et` |
| 上游构建：`binaricat/MoshCatty` CI releases | `scripts/build-et/` + `build-et-binaries.yml` |
| `scripts/fetch-mosh-binaries.cjs` | `scripts/fetch-et-binaries.cjs` |
| `scripts/resolve-mosh-bin-release.cjs` | `scripts/resolve-et-bin-release.cjs` |
| `scripts/mosh-extra-resources.cjs` | `scripts/et-extra-resources.cjs` |
| env `MOSH_BIN_RELEASE` / 仓库 `MoshCatty` / tag `moshcatty-*` | env `ET_BIN_RELEASE` / 仓库 `Netcatty-et-bin` / tag `et-bin-*` |
| `npm run fetch:mosh[:dev]` | `npm run fetch:et[:dev]` |
| `bundledMoshClient()` / `resolveBareMoshClient()` | `bundledEtClient()` / `resolveBareEtClient()` |
---
## Phase 1 — 打包基础设施（构建/下载/捆绑）
- [x] **1.1** `resources/et/README.md` —— 镜像 `resources/mosh/README.md`：说明
二进制来源、`Netcatty-et-bin` 发布仓库、`et-bin-*` tag、许可证（ET 为
Apache-2.0，与 GPL-3.0 兼容）、可复现构建命令。
- [x] **1.2** `.gitignore` —— 追加 ET 段（镜像 mosh 段）：
`/resources/et/*/et`、`/resources/et/*/et.exe`、`/resources/et/*/*.dll`、
`/resources/et/*/et-win32-*-dlls/`。保留 `resources/et/README.md`。
- [x] **1.3** `scripts/build-et/build-linux.sh` —— manylinux2014 + vcpkg 静态三元组
构建 `et`（x64/arm64），产物 `et-linux-<arch>.tar.gz`(+.sha256)，内含单个 `et`。
校验非系统动态库（ldd 白名单）。
- [x] **1.4** `scripts/build-et/build-macos.sh` —— arm64 + x86_64 分别构建后 `lipo`
成 universal，`MACOSX_DEPLOYMENT_TARGET=11.0`，产物 `et-darwin-universal.tar.gz`。
- [x] **1.5** `scripts/build-et/build-windows.ps1`（或 `.sh`）—— MSVC + vcpkg
`x64-windows-static`，产物 `et-win32-x64.tar.gz`（含 `et.exe`；若动态链接 CRT
则随附 DLL 目录 `et-win32-x64-dlls/`，否则纯静态无 DLL）。
- [x] **1.6** `scripts/et-extra-resources.cjs` —— 镜像 `mosh-extra-resources.cjs`：
按平台/arch 仅当 `resources/et/<plat-arch>/et[.exe]` 存在时才产出 extraResources
指令（`to: "et/"`）；Windows 额外处理可选 DLL 目录。纯客户端文件为主。
- [x] **1.7** `scripts/resolve-et-bin-release.cjs` —— 镜像 `resolve-mosh-bin-release.cjs`：
`TAG_RE=/^et-bin-.../`，默认仓库 `Netcatty-et-bin`，env `ET_BIN_RELEASE` 优先。
- [x] **1.8** `scripts/fetch-et-binaries.cjs` —— 镜像 `fetch-mosh-binaries.cjs`：
`TARGETS` 四项（linux-x64/arm64、darwin-universal、win32-x64），全部 tar.gz；
SHA256SUMS 校验；解包到 `resources/et/<plat-arch>/`。**Windows 用自建产物**。
- [x] **1.9** 单元测试：`scripts/fetch-et-binaries.test.cjs`、
`scripts/resolve-et-bin-release.test.cjs`、`scripts/et-extra-resources.test.cjs`
（镜像对应 mosh 测试，改名/改路径）。
- [x] **1.10** `package.json` scripts：新增
`"fetch:et": "node scripts/fetch-et-binaries.cjs"`、
`"fetch:et:dev": "node scripts/fetch-et-binaries.cjs --host --resolve-release"`；
把 `dev` 脚本改成先 `fetch:mosh:dev && fetch:et:dev`；`test` glob 已覆盖
`scripts/*.test.cjs`（确认即可）。
- [x] **1.11** `electron-builder.config.cjs`：引入 `etExtraResources`，在 darwin/win32/
linux 三处把 `etExtraResources(plat)` 合并进 `extraResources`（与 mosh 数组拼接）。
- [x] **1.12** `.github/workflows/build-et-binaries.yml` —— 四个构建 job + 一个
`release` job（dispatch 且 `release_tag` 非空时发布到 `Netcatty-et-bin`，附
`SHA256SUMS`）。`paths` 过滤指向 `scripts/build-et/**`、`scripts/fetch-et-binaries.cjs`、
`scripts/et-extra-resources.cjs`。env 用 `ET_REF`（默认 ET release tag，如 `et-v6.2.x`）。
> 注：实际二进制由用户手动 `workflow_dispatch` 触发产出；本地/CI 未设
> `ET_BIN_RELEASE` 时 fetch 步骤安静跳过（同 mosh 的 `MOSH_BIN_RELEASE`）。
## Phase 2 — 运行时定位捆绑客户端
- [x] **2.1** `electron/bridges/terminalBridge.cjs` 新增 `bundledEtClient(opts)`
—— 镜像 `bundledMoshClient`：打包路径 `<Resources>/et/et[.exe]`；dev 回退
`<projectRoot>/resources/et/<plat-arch>/et[.exe]`；导出到 module.exports。
## Phase 3 — ET 协议后端（搬运旧实现到新架构）
- [x] **3.1** 新建 `electron/bridges/terminalBridge/etSession.cjs` —— 用上游
`moshSession.cjs` 的 `createXxxSessionApi(ctx)` + `with(ctx)` 工厂模式，封装：
`ET_ASKPASS_SCRIPT`、`writeSecureFile`、`prepareEtSshEnvironment`、
`createEtAskpassArtifacts`、`cleanupStaleEtTempDirs`、
`cleanupSessionExternalAuthArtifacts`、`execOnEtSession`、`startEtSession`。
**改动点**：`etCmd` 由 `findExecutable('et')` 改为 `resolveBareEtClient()`
（取捆绑二进制）；找不到时抛错（同 mosh：提示跑 `npm run fetch:et:dev`）。
Windows 若有动态链接 DLL 目录，可把该目录加进 PATH（MoshCatty 路径已无此需求）。
- [x] **3.2** `terminalBridge.cjs` 接线 `createEtSessionApi(ctx)`（镜像 moshSessionApi
的 ctx），传入 `bundledEtClient`、`tempDirBridge`、`execFile/execFileSync` 等；
解构出 `startEtSession`、`execOnEtSession`、`cleanupStaleEtTempDirs`、
`cleanupSessionExternalAuthArtifacts`、`resolveBareEtClient`。
- [x] **3.3** `init()` 调 `cleanupStaleEtTempDirs()`；`registerHandlers` 加
`ipcMain.handle("netcatty:et:start", startEtSession)`；`closeSession` 与
`cleanupAllSessions` 调 `cleanupSessionExternalAuthArtifacts(session)`；
`module.exports` 导出 `startEtSession`、`execOnEtSession`、`bundledEtClient`。
- [x] **3.4** 测试：`terminalBridge.bundledEt.test.cjs`（路径解析）+
`terminalBridge/etSession.test.cjs`（prepareEtSshEnvironment 的端口/密钥/
askpass/跳板/legacy 算法分支）。可参考旧分支是否已有 ET 测试并搬运。
## Phase 4 — domain / 类型 / preload 接口面
- [x] **4.1** `domain/models.ts`：`HostProtocol` 加 `'et'`；`ProtocolConfig.etPort?`；
`Host`/`GroupConfig` 加 `etEnabled?`/`etPort?`/`etTerminalPath?`；
`TerminalSession.etEnabled?`；`ConnectionLog.protocol` 加 `'et'`。
（照搬 `git show 794eecdf -- domain/models.ts`）
- [x] **4.2** `domain/groupConfig.ts`：加 `etEnabled` 默认项（照搬旧 diff）。
- [x] **4.3** `global.d.ts`：`NetcattyBridge` 加 `startEtSession?(options): Promise<...>`
及相关 options 类型（照搬 `git show 794eecdf -- global.d.ts`，并补齐后续 ET 提交
新增的 etPort/terminalPath/jumpHosts/legacyAlgorithms 字段）。
- [x] **4.4** `electron/preload/api.cjs`：加 `startEtSession`（镜像第 26 行的
`startMoshSession`）→ `ipcRenderer.invoke("netcatty:et:start", options)`。
**注意**：上游已把 preload 重构成 `createPreloadApi`，落点在 `preload/api.cjs`，
不是旧的 `preload.cjs` 内联对象。
## Phase 5 — 渲染层 + UI + i18n
- [x] **5.1** `application/state/useTerminalBackend.ts`：加 `etAvailable`（查
`bridge?.startEtSession`）+ `startEtSession`，并在返回对象/依赖数组里登记
（镜像 mosh 的第 10/42/198/205 行处）。
- [x] **5.2** `application/state/useSessionState.ts`：路由 ET 会话（照搬旧 diff，+6 行）。
- [x] **5.3** `components/terminal/runtime/createTerminalSessionStarters.ts`：加
`startEt(term)`（镜像 `startMosh`，组装 options：etPort/terminalPath/
jumpHosts/legacyAlgorithms/凭证/identityFilePaths）。
**注意**：上游把它从旧的 `infrastructure/runtime/` 移到了
`components/terminal/runtime/` —— 落点以上游为准。
- [x] **5.4** UI 组件（照搬 `git show b1a306f8 6c0d5bf3 55caa268` 的相应文件，
映射到上游同名组件）：
- [ ] `components/ProtocolSelectDialog.tsx` —— 新增 ET 选项
- [ ] `components/QuickConnectWizard.tsx`
- [ ] `components/HostDetailsPanel.tsx` —— ET 设置（启用、ET 端口、etterminal 路径）
- [ ] `components/GroupDetailsPanel.tsx`
- [ ] `components/VaultView.tsx`
- [ ] `components/Terminal.tsx` / `components/TerminalLayer.tsx`
- [ ] `components/terminal/TerminalConnectionDialog.tsx` / `TerminalToolbar.tsx`
- [ ] `App.tsx`
- [x] **5.5** i18n：`application/i18n/locales/en.ts` 与 `zh-CN.ts` 加 ET 文案
（照搬旧 diff，键名对齐上游现有 mosh 文案结构）。
## Phase 6 — 校验
- [x] **6.1** `npm run lint`（确保新 .cjs 在 scripts/ 下不受 ESLint 限制，
或按需加 eslint-disable，与 mosh 脚本一致）。
- [x] **6.2** `npm test`（新增的 fetch/resolve/extra-resources/etSession 测试全绿）。
- [x] **6.3** `npm run build`（渲染层 TS 编译通过，无类型错误）。
- [ ] **6.4** 手动冒烟（需先有发布的二进制）：
`ET_BIN_RELEASE=et-bin-... npm run fetch:et` → `npm run start` →
新建 ET 会话连一台装了 etserver 的主机，验证连接/输入/退出/凭证注入。
---
## 进度记录
- 状态：**Phase 1–5 已完成并通过校验**（仅余 1 个可选项 + CI 产二进制）
- 验证结果：
- `npx eslint <所有改动文件>` → 干净（0 错 0 警）
- `npx tsc --noEmit` → 我的改动 **0 个新增类型错误**
（`TerminalConnectionDialog` 里 `case 'mosh'` 的 TS2678 是既有问题，行号因我插入 ET 早返回从 60→64，非新增）
- `node --test`（ET 相关）→ etSession/bundledEt/3 个脚本测试 **全绿**
- `npm test` → 1383 通过 / 16 失败，**16 个全是既有的 Windows 环境失败**
（mosh 打包测试的 GNU-tar `C:` 问题、`isExecutableFile` 无 x 位、ACP execPath、SKILL.md 权限、Comware DH 等；均在我未改动的文件里）
- `npm run build`（Vite）→ **构建成功**（8.55s），渲染层打包通过
### 已完成
- **Phase 1**：`scripts/et-extra-resources.cjs` / `resolve-et-bin-release.cjs` /
`fetch-et-binaries.cjs`（+3 测试，27 通过）、`scripts/build-et/{build-linux.sh,
build-macos.sh,build-windows.ps1}`、`.github/workflows/build-et-binaries.yml`、
`resources/et/README.md`、`.gitignore`、`package.json`、`electron-builder.config.cjs`。
- **Phase 2**：`terminalBridge.cjs` 新增并导出 `bundledEtClient`。
- **Phase 3**：`terminalBridge/etSession.cjs`（startEtSession + prepareEtSshEnvironment +
SSH_ASKPASS 机制 + execOnEtSession + 清理），接线进 terminalBridge.cjs（ctx/IPC
`netcatty:et:start`/init 清理/close/quit 清理/导出），+2 测试（13 通过）。
**et 指向捆绑二进制**（resolveBareEtClient→bundledEtClient），找不到则报错。
- **Phase 4**：domain `connection.ts`/`history.ts`/`terminal.ts`、`groupConfig.ts`、
`types/global/netcatty-bridge-session.d.ts`（startEtSession + NetcattyJumpHost[]）、
`electron/preload/api.cjs`、`domain/vaultImport.ts`（排除 'et' 导入协议）。
- **Phase 5**：
- 启动派发：`useTerminalEffects.ts`、`Terminal.tsx`(×3) → `startEt`
- 运行时 starter：`createTerminalSessionStarters.ts` 新增 `startEt`（含单跳板/凭证/
legacy 算法/askpass 路径），`.types.ts` 加 `etAvailable`/`startEtSession`
- 后端 hook：`useTerminalBackend.ts`（etAvailable + startEtSession）
- 会话透传 etEnabled：`sessionFactories.ts`、`useSessionState.ts`(×6)、
`TerminalLayer.tsx`(×3)、`TerminalLayerSupport.tsx`、`AppHandlers.ts`(协议解析/日志/选择)
- UI：`HostDetailsAdvancedSections.tsx`（ET 开关+端口+etterminal 路径，与 Mosh 互斥）、
`HostDetailsPanel.tsx`、`ProtocolSelectDialog.tsx`（ET 选项）、
`TerminalConnectionDialog.tsx`（ET 标签）、`TerminalToolbar.tsx`（编码菜单门控）、
`GroupSshSettingsSection.tsx` + `GroupDetailsPanel.tsx`（组级 ET）、`VaultView.tsx`
- i18n：en/zh-CN 的 `hostDetails.section.et`、`hostDetails.et.*`、
`terminal.connection.protocol.et`、`terminal.et.*`
### 剩余（可选 / 非阻塞）
- [ ] **QuickConnectWizard.tsx**：把 ET 加为“快速连接”协议按钮（type/端口/建主机映射 +
UI 按钮）。当前快速连接未列 ET；保存主机后开启 ET 再连即可，故仅为便利项。
- [ ] **产出二进制**：手动 `workflow_dispatch` 跑 `build-et-binaries.yml`（带
`release_tag=et-bin-<ver>-1`）发布到 `Netcatty-et-bin`，并配 `ET_BIN_RELEASE_TOKEN`
secret。之后 `ET_BIN_RELEASE=... npm run fetch:et` 即可本地/打包捆绑 `et`。
build-et 脚本本机无法编译 C++，需在 CI 验证。
- [ ] **端到端冒烟**：有二进制后 `npm run dev`，对装有 etserver 的主机建 ET 会话验证。
- 当前分支：`feat/et-history-reapply`（基于上游 `031bf0ee`）
- 旧 ET 实现参考分支：`feat/eternal-terminal`（tip `67e81616`，7 个 ET 提交）
Reference in New Issue Copy Permalink