pi-launcher

macOS / Windows 桌面启动器:按需启动 pi-agent 的本地 Web UI,免去手动开终端、敲命令、等端口、点浏览器的重复操作。

基于 Wails v2 (Go + Vue 3) 构建。逻辑与 dsh-launcher 几乎一致,仅替换为目标 CLI 与图标。

---

这是什么

@agegr/pi-web 是一个 npm 全局安装的命令行工具,启动后会:

1. 拉起本地 HTTP 服务(默认端口 30141)
2. 浏览器访问 http://localhost:30141/

pi-launcher 把这串动作封装成一个独立的 .app(macOS)/ .exe(Windows):

• 启动前自检:Node / pi-web 命令 / 凭据 / 30141 端口
• 一键启动 → 等端口就绪 → 自动开浏览器 → 最小化到 Dock
• 一键停止 / 一键安装(npm install -g @agegr/pi-web) / 一键升级
• 退出时自动清理:杀子进程、释放端口、不留孤儿 node

适合场景:日常用 pi 但不想每次都开终端敲命令。

---

截图

(启动器窗口 1040 × 1280,深色背景,左右两栏:左环境检查,右操作 + 日志)

---

安装 pi CLI(目标程序)

启动器只是壳,真正干活的 pi 命令需要先手动装一次:

npm install -g @agegr/pi-web

启动器自带的「安装 / 升级」按钮会帮你跑同样的命令,不用自己再开终端。

注意:@agegr/pi-web 默认会拉取一份 Electron 浏览器壳 + 本地凭据目录 ~/.pi/(类比 dsh 的 ~/.dsh/)。首次启动器自检会提示你 pi-web login。

---

编译启动器本身

需要:

• Go ≥ 1.25
• Node ≥ 18
• Wails v2:go install github.com/wailsapp/wails/v2/cmd/wails@latest
• macOS 编译产物需要 macOS;Windows 同理(见下方说明)

macOS

./scripts/build-mac.sh
# 产物: build/bin/pi-launcher.app

./scripts/install-app.sh
# 复制到 /Applications/ 并刷新 LaunchServices 图标缓存

Windows

在 Windows 上跑:

scripts\build-windows.bat

Wails v2 跨平台必须本机编译,Mac 上 build 不了 Windows exe。

---

开发模式

wails dev

Vite 热重载前端 + Go 后端,浏览器另开 devtools:http://localhost:34115

---

核心架构

pi-launcher/
├── main.go              # Wails 入口 + macOS 窗口配置 + --selftest 调试模式
├── app.go               # 后端:CheckEnv / Start / Stop / Install / Update
├── wails.json           # 项目元数据(name / outputfilename)
├── go.mod
├── build/
│   ├── darwin/Info.plist
│   ├── windows/icon.ico
│   └── appicon.png / iconfile.icns  # 应用图标(替换此处换图标)
├── frontend/
│   ├── src/App.vue      # 单文件 SPA,环境检查 + 操作面板 + 日志
│   ├── src/main.js
│   ├── package.json
│   └── vite.config.js
├── scripts/
│   ├── build-mac.sh     # macOS 构建脚本
│   ├── build-windows.bat
│   └── install-app.sh   # 复制到 /Applications + 刷新图标缓存
└── README.md

后端关键点

• initNpmPrefix() — 启动时一次性 npm prefix -g 缓存,后续读缓存
• buildChildEnv() — 给子进程手动塞 /opt/homebrew/bin 等路径,GUI 进程 ~/.zshrc 不读
• waitForPort(30141, 30s) — 轮询端口 LISTEN 替代等 URL 字符串
• killPITree() + freePort(30141) — 退出 / 停止时双保险,杀进程树 + 精准释放端口
• 全部外部命令都包 recover() + 超时,任何子命令崩都不会拖垮 GUI

前端关键点

• 单文件 App.vue,分左右两栏:左环境检查(Node / pi / 凭据 / 端口),右操作按钮 + 实时日志流
• 通过 Wails EventsOn 订阅 pi:install:log / pi:install:done 拿到 npm 子进程实时输出
• Start 成功后自动调 WindowMinimise 收进 Dock

---

与 dsh-launcher 的差异

项	dsh-launcher	pi-launcher
目标 CLI	@deepseek-ai/dsh	@agegr/pi-web
命令名	dsh	pi-web
凭据目录	~/.dsh/.credentials.yaml	~/.pi/.credentials.yaml(待确认)
端口	3080	30141
进程匹配	dsh/lib/bin.js / dsh-pet	pi-web 相关进程(待定)
安装包名	@deepseek-ai/dsh	@agegr/pi-web
启动 URL	http://127.0.0.1:3080/	http://localhost:30141/
图标	build/appicon.png	同位置替换

迁移思路:把 app.go 里所有 dsh 字面量改成 pi、dshPkg 常量改成 @agegr/pi-web、HomeDshDir 改成 HomePiDir(~/.pi),端口 3080 改成 30141,再换图标即可。

---

自检模式(调试用)

不启 GUI,直接调后端走完流程:

./build/bin/pi-launcher --selftest

会打印:nodeOK / piPath / piVer / cred / portBusy / 进程列表 / waitForPort 测试结果。

---

已知问题

• Windows 图标闪烁:首次安装 Windows 版后任务栏图标可能延迟更新,等几秒或重新 pin。
• macOS Dock 图标缓存:scripts/install-app.sh 已处理 lsregister -f + Dock 重启,通常一次就好。
• 端口 30141 被占:启动器会自动 kill -9 残留 PID,但如果你跑别的服务也用 30141 会被误杀——届时改 waitForPort / freePort 的端口号。

---

License

个人项目,MIT。