跳转至

truth-lab 全场景开发工作流

适用环境:Windows + WSL 本机,阿里云 ECS 服务器,Pico Ultra VR 头显 更新日期:2026-06-02


1. 架构总览

┌─────────────────────────────────────────────────────────────┐
│                   阿里云 ECS 服务器                           │
│  ├── truth-lab 源码 (git clone)                              │
│  ├── npm run build → dist/                                  │
│  ├── rsync dist/ → ~/truth-lab-dist/                        │
│  ├── nginx → ilmhub.top/truth-lab/                          │
│  └── Hermes Agent(我)← 通过飞书跟你聊天                      │
└────────────────────┬────────────────────────────────────────┘
                     │ ilmhub.top
┌─────────────────────────────────────────────────────────────┐
│                    Pico Ultra 头显                            │
│  浏览器 → https://ilmhub.top/truth-lab/                     │
│  → 点击 🎮 进入 VR / 拖拽控制点 / 仿真等                     │
│  USB 线连本机(仅调试时需要)                                 │
└─────────────────────────────────────────────────────────────┘
                     │ USB
┌─────────────────────────────────────────────────────────────┐
│                    本机 Windows + WSL                         │
│  ├── adb (Windows 或 WSL 均可)                               │
│  ├── Chrome → chrome://inspect                               │
│  ├── Chrome Remote Desktop(外出时远程桌面)                   │
│  └── 代码编辑器(vscode 等,改代码用)                         │
└─────────────────────────────────────────────────────────────┘

2. 日常开发流程

2.1 改代码 → 部署

# 1. 本机改完代码 → 提交
git add .
git commit -m "feat: xxx"
git push

# 2. SSH 到云服务器
ssh admin@101.132.106.49

# 3. 拉取 + 构建 + 部署
cd ~/truth-lab
git pull
npm run build:fast    # 约 5 秒,跳过类型检查
# 或 npm run build    # 完整构建含 tsc 类型检查
npm run deploy        # rsync 到 ~/truth-lab-dist/

说明: npm run deploy 等于 rsync -avz --delete dist/ admin@101.132.106.49:~/truth-lab-dist/ 因为服务器上 dist/ 就是本机,所以相当于本地复制。

2.2 让 Hermes 代劳

你只需在飞书跟我说:

"@Hermes 帮我改控制点颜色,然后 build 部署"

我就能直接操作云服务器上的代码、构建、部署。你不用自己 SSH 上去。


3. 真机调试流程

3.1 Pico 端设置(只需做一次)

设置 → 通用 → 开发者选项 → 开启 USB 调试

没看到开发者选项?去"关于本机"连点版本号 7 次解锁

之后 Pico 浏览器不需要任何额外配置,直接打开 https://ilmhub.top/truth-lab/

3.2 本机装 adb

Windows 安装 adb:

  1. 下载 Android SDK Platform Tools
  2. 解压到 C:\adb
  3. C:\adb 加到环境变量 PATH
  4. 打开 CMD / PowerShell 验证:
    adb --version
    

WSL 里装 adb(替代方案):

sudo apt update
sudo apt install adb

⚠️ WSL 的 adb 需要 USB 转发支持,较复杂。推荐用 Windows 原生 adb。

3.3 开始调试

# 1. USB 线连 Pico 到本机
#    Pico 上弹出授权 → 点"允许"

# 2. 确认连接
adb devices
# 应输出: xxxxxxxxxxxx    device

# 3. 转发 DevTools 端口
adb forward tcp:9222 localabstract:chrome_devtools_remote

# 4. 打开 Chrome → 地址栏输入
chrome://inspect
# → 看到 Pico 浏览器页面列表 → 点 inspect

Chrome DevTools 面板:

面板 用途
Console 看报错、console.log、手动执行 JS
Sources 断点调试、查看源码
Network 网络请求监控
Performance 性能分析、帧率
Elements DOM 检查

常用调试命令:

1
2
3
4
5
6
7
8
9
// 在 Console 中
navigator.xr.isSessionSupported('immersive-vr').then(console.log)

// 查看手柄输入源
navigator.xr.requestSession('immersive-vr').then(session => {
  session.addEventListener('inputsourceschange', e => {
    console.log('inputsources:', e.session.inputSources)
  })
})

3.4 无线调试(可选)

1
2
3
4
5
6
7
8
9
# 1. 先 USB 连一次,开启无线
adb tcpip 5555

# 2. 拔掉 USB
adb connect <PICO_IP地址>:5555

# 3. 转发 + 调试
adb forward tcp:9222 localabstract:chrome_devtools_remote
# Chrome → chrome://inspect

⚠️ Pico 重启后无线 ADB 会关闭,需要重新 USB → tcpip。


4. 外出开发方案

4.1 Hermes 在服务器上干活(你在飞书上遥控)

外出时,你的主要开发通道是**飞书 ↔ 我(Hermes)**。

我能做的事情:

能做的 不能做的
✅ 修改 truth-lab 源码 ❌ 操控你的本机 Windows
✅ 跑 npm run build / deploy ❌ 连接 Pico(USB 在本机)
✅ 查看构建日志、报错 ❌ 打开 Chrome DevTools
✅ push 代码到 Gitee
✅ git commit

示例:

1
2
3
你:@Hermes 在控制点拖拽时加一个震动反馈
我:已修改 useVrDrag.ts,正在 build...
我:部署完成,刷新 Pico 看看效果

4.2 需要远程操控本机时 — Chrome Remote Desktop

当需要 adb 连 Pico、开 Chrome DevTools 等**本机操作**时,用远程桌面。

本机 Windows 设置(一次):

  1. Chrome 打开 remotedesktop.google.com
  2. 点"远程访问" → "下载" → 安装 Chrome Remote Desktop
  3. 设 PIN 码(6 位以上)
  4. ✅ 完成

外出时:

1
2
3
4
5
6
手机/任意电脑 → Chrome → remotedesktop.google.com → 输入 PIN

→ 看到完整的 Windows 桌面
→ 开 WSL 终端敲 adb forward
→ 开 Chrome 看 chrome://inspect
→ 操作文件、开编辑器

4.3 外出完整场景

1
2
3
4
5
6
7
8
9
场景 A:只改代码
  你 → 飞书 → 我(Hermes)→ 服务器改代码 + build + deploy ✅
  Pico 刷新就能看到效果

场景 B:需要真机调试
  你 → Chrome Remote Desktop → 本机 Windows 桌面
  → 开 WSL 终端 → adb forward
  → 开 Chrome → chrome://inspect
  → 调试完关掉,剩下交给我

5. 常用命令速查

服务器端

# 构建(在 ~/truth-lab 目录下)
npm run build:fast    # 快速:跳过 tsc,~5 秒
npm run build         # 完整:含类型检查
npm run deploy        # rsync 到 ~/truth-lab-dist/

# 查看 nginx 状态
sudo systemctl status nginx

# 查看部署文件
ls ~/truth-lab-dist/

本机端(Windows CMD / WSL)

# ADB
adb devices                             # 查看连接设备
adb forward tcp:9222 localabstract:...  # 转发 DevTools 端口
adb logcat -s chromium:*:V              # 看 Pico 浏览器日志
adb exec-out screencap -p > ss.png      # 截图
adb tcpip 5555                          # 开启无线模式
adb connect <IP>:5555                   # 无线连接

# Git
git add . && git commit -m "msg" && git push

飞书 → Hermes

1
2
3
4
"帮我改 xxx 然后 build 部署"
"看看构建报错"
"把控制点改回紫色"
"加一个新功能:..."

6. Pico Ultra 控制器参考

// 按钮映射
// gamepad.buttons[0] = 扳机 Trigger (0~1)
// gamepad.buttons[1] = 握持 Grip (0~1)
// gamepad.buttons[2] = 摇杆按下
// gamepad.buttons[3] = X/A 按钮
// gamepad.buttons[4] = Y/B 按钮
// gamepad.buttons[5] = 菜单键

// 摇杆
// gamepad.axes[0] = X (-1~1)
// gamepad.axes[1] = Y (-1~1)

// 注意:无触摸板,用摇杆 + 按键替代

7. 已知问题 & 解决方案

问题 原因 解决
adb devices 看不到 Pico USB 线或授权问题 换线,Pico 上重新点"允许"
chrome://inspect 空白 端口没转发 先跑 adb forward
Pico 上页面不更新 缓存 下拉刷新或清除浏览器缓存
构建报 tsc 错误 类型错误 修复类型或用 build:fast 跳过
WebXR 进不去 不是 HTTPS ilmhub.top 已有合法证书 ✅
远程桌面卡顿 网络问题 降低分辨率,或用手机 App 应急