Bill
3b2fe06f71
From the 2026-09-15 decision, releases go to the Gitea release + the domestic update channel with --skip-github; the GitHub release assets are no longer synced per version (the code/tag mirror stays).
50 lines
3.8 KiB
Markdown
50 lines
3.8 KiB
Markdown
# OpenTerminal 开发备忘
|
||
|
||
Electron + electron-vite + React 终端工具（本地终端 / SSH / SFTP）。
|
||
|
||
## 常用命令
|
||
|
||
- 开发：`npm run dev`（主进程改动不热重建，需重启）
|
||
- dev 实例使用独立用户数据目录 `%APPDATA%\OpenTerminal-dev` 与独立单实例锁（`src/main/index.ts` 顶部 `!app.isPackaged` 分支），窗口标题带 `(dev)`：**可与已安装的正式版同时运行，互不干扰**，也不会把测试设置/会话写进真实配置
|
||
- 类型检查：`npx tsc --noEmit -p tsconfig.web.json`
|
||
- 打包：`npm run dist`，产物在 `release/`（msi + exe + latest.yml + blockmap）
|
||
- 国内网络需镜像：`ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ npm run dist`
|
||
|
||
## 仓库与远程
|
||
|
||
- `origin` = Gitea `https://git.codingplan.site/admin/OpenTerminal.git`（主仓库 + 更新通道）
|
||
- `github` = `https://github.com/billowliu2/OpenTerminal.git`（镜像 + 备用更新源）
|
||
- ⚠️ Gitea 的 upload-pack 有故障，`git fetch origin` 会报 `bad pack header`；查询远端状态用 API 或 `git ls-remote`。推送正常。
|
||
- 2026-09：远端 main 旧历史（M3–M8，至 v0.8.0 d3a628f）被 force-push 覆盖为当前历史，旧提交仍由 tag v0.6.0 / v0.7.0 / v0.8.0 保留。
|
||
|
||
## 凭据
|
||
|
||
- `.env`（已 gitignore）：`GIT_TOKEN`（Gitea）、`GH_TOKEN`（GitHub）等。git 推送通过 credential helper 使用该令牌。
|
||
|
||
## 发布新版本
|
||
|
||
1. `package.json` 版本号 +1，写 `RELEASE_NOTES.md`（仓库根，已 gitignore）
|
||
2. `npm run dist` 构建
|
||
3. `node scripts/release.cjs <版本号> --skip-github`，例如 `node scripts/release.cjs 1.0.11 --skip-github`
|
||
- **只发国内**（2026-09-15 起的产品决定）：Gitea release（含 msi/exe 资产）→ Gitea 更新通道（`api/packages/admin/generic/openterminal-update/stable`，更新 latest.yml/blockmap/exe/release-notes.md）
|
||
- 国内通道全程直连，**不需要设代理**；代理只在显式补发 GitHub 时才用（`HTTPS_PROXY=http://127.0.0.1:7897`，脚本只把它用于 GitHub 请求）
|
||
- GitHub 那一步的状态：`README` 与更新机制里仍保留 GitHub 作为更新回退源，但**release 资产不再随版本发布同步**；若某天需要补，跑一次 `node scripts/release.cjs <版本号> --skip-gitea` 即可
|
||
4. 验证更新通道：`curl https://git.codingplan.site/api/packages/admin/generic/openterminal-update/stable/latest.yml` 应返回新版本号
|
||
5. `git tag v<版本号>` 并推送两个远程（代码/tag 的镜像保持同步，仅 release 资产不发 GitHub）
|
||
|
||
## 更新机制
|
||
|
||
- 检查更新：先 Gitea 更新通道（强制直连，不走系统代理），失败回退 GitHub（走系统代理）。 electron-updater 用独立 session（partition `electron-updater`），代理模式在 `useFeed` 里按源切换
|
||
- 更新日志：Gitea 仓库是私有的（匿名 API 404），改为从更新通道的 `release-notes.md` 读取（直连 session `openterminal-update-direct`），再回退 Gitea/GitHub releases API
|
||
- electron-updater 不支持 MSI 自动更新，自动更新只走 NSIS exe
|
||
|
||
## 主题机制
|
||
|
||
- 终端主题由 xterm 主题派生 UI 配色：`src/renderer/src/theme/chrome.ts` 的 `applyChromeTheme` 写入 `--chrome-bg/-bg-deep/-border/-hover` CSS 变量，antd token 在 `main.tsx` ThemedConfigProvider 派生
|
||
- 标签强调色：`settings.tabAccentColor`（默认 `#3fb950`），经 `--tab-accent` CSS 变量生效
|
||
|
||
## 终端尺寸同步
|
||
|
||
- `TerminalView.scheduleFit`：fit 后**去抖 100ms** 再把 cols/rows 发给 PTY，并跳过与上次相同的尺寸。每次 ResizeObserver 都戳 PTY 会让全屏 TUI（Claude Code 等）在最大化/还原的中间尺寸上反复重绘，留下重复帧
|
||
- 拖动窗口期间 xterm 网格立即更新，PTY 尺寸在停止后 100ms 生效
|