publieople WSL 开发环境
WSL (Windows Subsystem for Linux) 上的开发环境配置与常见陷阱。
触发条件
- 在 WSL 中创建 Python venv 失败（NTFS 权限错误）
- 在 WSL 中需要访问 Windows 侧的代理（Clash）
- NTFS 挂载盘上的文件权限/解压问题
- DeepSeek ReAct Agent 在 WSL 环境下的运行
- 通过 SSH 操作远端 fish shell 服务器时遇到
fish: $? is not the exit status - 在 WSL 内运行 tmux / 任何常驻进程，需要"清干净"做验证
- 从 Windows PowerShell 一行启动 WSL 里安装的 CLI（hermes / claude / codex 等），报"未找到命令"、"no API keys"、或"先进入 fish / 卡在 PS1 才执行命令"
- 在 WSL 里跑 > 60s 的 JVM / 构建任务，
terminal(background=true)起来后秒退 - 在 WSL 里
docker compose up -d后台跑完 action=log 只看到 ioctl 警告、不知道容器起没起；或 background shell 里cd /path && docker compose ...静默失败 - 从 GitHub release 下载 > 50MB 资产，速度极慢且续传无效
- 在 WSL 里
cp大文件 / 多文件目录到/mnt/c//mnt/e/等 Windows NTFS 挂载盘，写入静默失败（目标文件不存在 / size 截断 / cp 进程 exit 0 但目标没生成） - 后台进程完成通知里看到
bash: 无法设定终端进程组 (-1): 对设备不适当的 ioctl 操作+此 shell 中无任务控制→ 误以为是失败 - WSLg daemon 装着（
/tmp/.X11-unix/X0在、/mnt/wslg挂载正常）但当前 session 跑 Electron App 时报Missing X server or $DISPLAY+SIGSEGV，$DISPLAY空 - 在 Arch WSL 用
paru -S <AUR-gui-app>装了 Electron GUI App（如stably-orca-bin）但command -v <tool>找不到 — 包只装 GUI 启动器到/opt/<app>/，没把<tool>CLI 暴露到 PATH（CLI 是 App 运行时通过 IPC 暴露的 bridge，App 不跑就不存在） npm install -g <pkg>看似成功（"changed 1176 packages"），但含原生 binding 的包（better-sqlite3 / sharp / onnxruntime-node / @parcel/watcher / koffi 等）跑不起来 — 因为 npm 11+ 默认 blocked install scripts，需要--allow-scripts=<list>重装才能编译 native binarynpm install -g <pkg>成功后用 systemd user service 启动，发现所有 HTTP 请求都 HTTP 500、journalctl 无错、~/.X/storage.sqlitemtime 不变 — service 文件里写了ProtectHome=read-only（sandbox 默认值），但该服务要写~/.X/（SQLite / 配置 / OAuth token）- 长驻服务（omniroute / 类似 daemon）从 Hermes
terminal(background=true)启动后，启动 banner 正常出现但curl localhost:port拿不到响应（连接被拒），pgrep找不到 PID — sandbox 已 kill 进程 - WSL 里
systemctl start sshd失败、前台sshd -D -d报Bind to port 22 ... Address already in use，但 WSL 内ss -tlnp | grep :22和ps aux | grep sshd都为空 — Windows 宿主 OpenSSH Server 占 22，经 WSL2 localhost 转发幽灵占用
SSH 到 fish shell 远端服务器 — $? 必踩的坑
远端用户登录 shell 是 fish 时，inline 单引号命令里写 $? 会被 fish 拦截：
fish: $? is not the exit status. In fish, please use $status.
原因：ssh 把整个 command 作为 argv 传给远端登录 shell，fish 看到 $? 字面量就直接报错。命令根本没跑。
绕过（任选一）：
# 1. 强制远端用 bash 而不是登录 shell
ssh user@host bash -c '...your code with $?...'
# 2. heredoc 强制走 /bin/sh
ssh user@host /bin/sh <<'EOF'
...your code with $?...
EOF
判断：远端命令 exit 127 + stderr 含 fish: $? is not the exit status = 几乎一定是这个问题，不是命令本身语法错。
tmux / 长驻进程：永远别 kill-server 验证
Hermes TUI 本身就跑在 WSL tmux 里。配置改动后想"清干净再加载"时：
# ❌ 错 — 杀掉整个 tmux server，Hermes 进程跟着死
tmux kill-server
tmux new-session -d -s _v fish -l
tmux source-file ~/.tmux.conf
后果：本会话直接断，Hermes 状态丢失，下一次用户在另一个 shell 继续。
# ✅ 对 — 在当前 server 上起一个命名临时 session 验证，再 kill 那个 session
tmux new-session -d -s _vverify fish -l
tmux source-file ~/.tmux.conf
tmux display-message -p "prefix=[#{prefix}] mouse=[#{mouse}] shell=[#{default-shell}]"
tmux kill-session -t _vverify
或者用独立 socket 完全隔离：tmux -L _test new-session -d ... + tmux -L _test kill-server，这只杀那个 socket 下的 server，不动默认。
如果想检查 $? 又在 fish 环境：用 tmux display-message -p 把检查嵌进 tmux 内部，fish 看不到 $? 就不会爆。
NTFS 挂载盘上的 venv 权限问题
症状
在 /mnt/c/、/mnt/e/ 等 Windows 盘上使用 uv sync 或 pip install 时报错：
Operation not permitted (os error 1)
原因
Windows NTFS 文件系统不支持 Linux 的文件权限模型，导致 .venv/ 内的文件复制操作失败。
解决方案
将 venv 创建在 Linux 原生文件系统（ext4）上，然后软链接到项目目录：
# 1. 删除项目下的 .venv
rm -rf .venv
# 2. 在 Linux 侧创建 venv
uv venv --python 3.13 /home/po/.venvs/<project-name>
# 3. 建立软链接
ln -sf /home/po/.venvs/<project-name> .venv
# 4. 正常安装依赖
uv sync
注意：pyproject.toml 和项目代码仍可放在 NTFS 盘上，只有 .venv/ 需要移到 Linux 侧。
WSL 访问 Windows Clash 代理
Clash for Windows 的 HTTP 代理默认监听 127.0.0.1:7890，WSL 可直接访问。
探测代理
curl -s --connect-timeout 1 http://127.0.0.1:7890
# 返回 HTTP 400 = 代理正常运行（对裸请求的预期响应）
# 返回 000 / 无响应 = 代理未启动
设置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
常见 Clash for Windows 端口：HTTP 7890 | SOCKS5 7891
DeepSeek ReAct Agent 模式
参见 references/deepseek-react-patterns.md。核心陷阱：
- 必须设置
stop=["PAUSE"]— DeepSeek 不会自然停在 PAUSE，会一次生成完整多轮对话（含幻觉 Observation） - 正则匹配需兼容中英文冒号 — DeepSeek 输出可能混用
:和：
Python 版本冲突与依赖管理
uv add vs uv pip install
在 NTFS 挂载盘上的项目，不要用 uv add（它会尝试重建 NTFS 上的 .venv）。用 uv pip install 直接装到 Linux venv：
uv pip install <package> --python /home/po/.venvs/<project-name>/bin/python
Python 3.10 兼容问题
某些 ML 项目（如 CosyVoice2 依赖的 matcha-tts）需要 Python 3.10（因为用到了 Python 3.12 移除的 distutils）。
# uv python install 3.10 从 GitHub 下载，国内网络可能超时
# 替代方案：用 conda 管理 Python 版本
conda create -n <project> python=3.10
conda activate <project>
# conda 环境中可能需要补装 pip
python -m ensurepip --upgrade
注意：conda 创建的 Python 在某些 ML 包上可能有兼容问题（如 PyTorch CUDA 支持），需要额外配置。
uv python install 国内网络超时
uv python install 从 astral-sh 的 GitHub releases 下载 Python，国内网络可能 120s 超时。
解决：走代理
https_proxy=http://127.0.0.1:7890 uv python install 3.10
或跳过 uv 的 Python 管理，直接用 conda 或系统 Python。\n\n### Python 3.14 兼容问题
系统 Python 3.14 可能缺少某些包的 wheel（如 openai-whisper 缺少 pkg_resources）。用 uv 安装旧版 Python：
uv python install 3.12
uv venv --python 3.12 /home/po/.venvs/<name>
Docker Compose up -d 后台：输出全丢 + cwd 不续
症状：terminal(background=true, notify_on_complete=true) 跑 docker compose up -d，process 几秒后 exit_code=0，但 process action=log 只能看到两行 ioctl 警告，compose 的真实 stdout/stderr（拉镜像、构建、起容器）一个字节都看不见。你不知道是拉镜像失败还是构建报错——只能再 docker compose ps 看容器在不在。浪费 2-3 轮排错。
根因（两个叠加）：
- Hermes 后台 wrapper 的 tty/sandbox 把 compose 的 stdout/stderr 完全吞掉，只剩 bash 自己的 ioctl 警告
- background process 不续 cwd — 同一个 session 里前面
cd /home/po/x成功后，后面terminal(background=true) cd /home/po/x && docker compose up -d会因 cd 静默失败而找不到 yml，但整个命令链 exit 0 不报错
正确写法（首选 tee 法）：
# ✅ A. 前台 + tee —— `compose up -d` detached 后立即返回(几秒)，不触发 long-lived 警告
# (整个 build 拉镜像输出仍写 file，但 fg 进程早就退了 —— fg 进程在 compose detached 时已经退出)
cd /home/po/mediary-scout && docker compose up -d 2>&1 | tee /tmp/ms-up.log; echo "exit=$?"
# ✅ B. 后台但用 --project-directory 不依赖 cwd,跑完只看 exit_code 不读 action=log
docker compose --project-directory /home/po/mediary-scout -f /home/po/mediary-scout/docker-compose.yml up -d
# 验真:
docker compose --project-directory /home/po/mediary-scout -f /home/po/mediary-scout/docker-compose.yml ps
# ✅ C. 真要看 build 详细日志？前台跑 `compose build`(不带 -d),看 build 实时输出
docker compose --project-directory /home/po/mediary-scout -f /home/po/mediary-scout/docker-compose.yml build
反模式：
# ❌ 后台跑,想靠 action=log 看输出 —— 啥也没有,误以为失败
terminal(background=true) docker compose up -d
# ❌ background 里靠 cd 切目录 —— cwd 不续,失败静默,exit 0
terminal(background=true) cd /home/po/mediary-scout && docker compose up -d
判断快捷：后台跑完 compose up -d 立刻 compose ps —— 有容器 Running/Healthy = 跑通了，没容器 = 哪步出错，重跑 fg + tee 看 log。
Vite/Node 开发服务器：Windows 浏览器访问
WSL 中启动的 Vite dev server 在 Windows 浏览器可能无法访问。
必须加 --host
npx vite --host 0.0.0.0
# 不加 --host 时 Vite 只监听 localhost，Windows 端可能无法转发
不加 --host 时 ss -tlnp | grep 5173 显示端口未监听（虽然 Vite 打印了 ready 消息）。
浏览器地址优先级
| 优先级 | 地址 | 适用场景 |
|---|---|---|
| 1 | http://localhost:5173/ |
WSL2 localhost 转发正常时 |
| 2 | http://<WSL_IP>:5173/ |
localhost 转发失败时（用 ip addr show eth0 获取 IP） |
terminal(background=true) 静默退出
terminal(background=true) 启动 npx vite 可能静默退出（exit code 0，output 只有 bash ioctl 警告）。替代方案：在用户自己的 WSL 终端中手动运行 npx vite --host 0.0.0.0。
WSL 后台进程调试
后台进程在 WSL 中静默退出是常见问题。排查流程：
- 先在前台跑一次看报错：
python3 server.py 2>&1 - 确认无语法错误后再后台启动：
terminal(background=true) - 检查端口：
ss -tlnp | grep <port>
Hermes 长时任务被 sandbox 杀的硬性上限（实测 ~60-90s）
症状：terminal(background=true) 起的进程在 60-90 秒后无任何报错地消失（exit_code=0，但 log 不更新，PID 查不到）。实测：SPC 8.1.2 生成整合包 5 分钟全过程跑得通，但 terminal(background=true, timeout=1500) 起来的实例 uptime 只有 69s 就被砍。
根因：Hermes TUI 给后台进程附加了 sandbox 监管（看 stderr 的 bash: 无法设定终端进程组 (-1): 对设备不适当的 ioctl 操作 + 此 shell 中无任务控制 这两行警告），超时后 SIGTERM。
⚠️ 关于那两行 ioctl 警告的"误报"：Hermes 后台进程完成通知里也总是带这两行（
bash: 无法设定终端进程组 (-1)+此 shell 中无任务控制），即使命令真的成功跑完了。看到这两行不等于失败——判断成功与否要看 exit_code 和实际产出物（文件、port、log）。这条不是新坑，是 Hermes 的固定行为。
结论：
- 短任务（< 60s） → 后台方便，配合
process action=poll看进度 - 长任务（> 60s） → 必须前台 + 留 timeout 余量。
timeout 580 java -jar ...实测可用，600s 是 Hermes fg 命令上限 - 超长任务（> 10 分钟） → 用
delegate_task（会自动后台），或cronjob（deliver='local' 不会发回 TUI，但任务真跑完）
反模式：
# ❌ 看似后台、实际被砍
terminal(background=true, timeout=1800) java -jar foo.jar > log 2>&1
# uptime 69s 后 PID 不在了，log mtime 卡在 60s 处
正确做法：
# ✅ 前台跑 + 留余量
timeout 580 java -jar foo.jar > log 2>&1
# 或直接放后台用 nohup + setsid 完全脱钩（绕过 Hermes）
长驻服务的"假装跑通"陷阱 + 真正的 daemonize
服务 banner 出现 ≠ 服务真在跑。诊断流程（关键反模式 vs 正确）：
反模式（看着像但 sandbox 已 kill）：
# ❌ banner 出现后以为成功了 — 但 12s 后 curl 报 connection refused
terminal(background=true, timeout=30) omniroute
sleep 12; curl http://localhost:20128/v1/models
# 实际：sandbox 在 sandbox 周期清理时 SIGTERM 掉了，pgrep 不到 PID
正确诊断：
# 1. 用 CLI 子命令验证 native binary 加载（不依赖 daemonize）
omniroute doctor
# → 看 "Native binary: better-sqlite3 native binary is compatible"
# → 看 "Database: SQLite database not found"（意味着 native binding 没编译）
# 2. 前台短跑 + 重定向（看清 banner 之后实时退出码）
timeout 15 omniroute > /tmp/omniroute.log 2>&1; echo "exit=$?"
tail -15 /tmp/omniroute.log
# exit=124 是 timeout 主动杀的（表示服务跑起来了）
# exit!=124 是服务自己 crash
# 3. 真正 daemonize 必须在 Hermes 外启动
真正 daemonize 的 3 种方案（按推荐度）：
| 方案 | 命令 | 优点 | 缺点 |
|---|---|---|---|
| 新开 WSL tab | omniroute |
最简单 | 关 tab 就死 |
| systemd user service | 见下 | 开机自启 / restart on failure | 需 user-level systemd |
| tmux detached | tmux new -d -s omniroute 'omniroute' |
持久化 + 可 attach | 杀 tmux-server 全死 |
systemd unit 模板（用户级，不需要 sudo）— 不要加 sandbox 限制：
# ~/.config/systemd/user/omniroute.service
[Unit]
Description=OmniRoute AI Gateway
After=network.target
[Service]
Type=simple
ExecStart=/home/po/.npm-global/bin/omniroute
Restart=on-failure
RestartSec=5
TimeoutStartSec=30
# ⚠️ 不要加 ProtectHome=read-only 或 ProtectSystem=full
# 任何写 ~/.X/（SQLite / 配置 / OAuth token / hot-reload state）的服务
# 都会出现：banner 报 "running" + 端口监听 OK + 但任何请求都 HTTP 500
# journalctl 看不到任何错误，stat ~/.X/storage.sqlite mtime 不变是判定信号
ProtectSystem=false
ProtectHome=false
PrivateTmp=true
[Install]
WantedBy=default.target
启用：systemctl --user daemon-reload && systemctl --user enable --now omniroute.service
ProtectHome=read-only 是静默 500 的元凶（OmniRoute 真实案例）：看着像好习惯的 sandbox 默认值，启动 5s 报 "running"、监听 20128 OK，但任何 HTTP 请求都 HTTP 500，journalctl 没任何 stack（service 的 stdout 被吃了）。根因：SQLite DB / OAuth token / 配置写 ~/.omniroute/，read-only home 直接拒写；启动 banner 阶段不写 DB 所以启动 OK，第一个请求触发写入就 fail。判断：服务启动后看 ~/.X/storage.sqlite mtime — 如果启动后没动过就是 write 被拒。
经验法则：单机本地代理 / Hermes-style user-mode daemon 都需要 home 可写。PrivateTmp=true 保留无害。
npm 11+ 全局安装：install-scripts 静默被 blocked
症状：npm install -g <pkg> 输出 "changed 1176 packages in 5m" 看似成功，但运行时报错：
better-sqlite3 native binary was not foundError: Could not locate the bindings file- 某些 native-only 功能（SQLite / 图像处理 / ONNX 推理）直接 crash
根因：npm 11+ 默认开启 install-scripts 保护（PEP-668-like 机制），原生包的 postinstall 脚本被静默跳过 — 包括：
better-sqlite3、sharp、onnxruntime-node、koffi、@parcel/watcher@swc/core、esbuild、keytar、tls-client-nodeprotobufjs、core-js- 以及包的
postinstall（如 omniroute 自身的scripts/build/postinstall.mjs）
修复（重装带 allow-scripts）：
# 单次允许（推荐先试）
npm install -g --allow-scripts=<pkg-name>,better-sqlite3,keytar,tls-client-node,onnxruntime-node,sharp,core-js,esbuild,@parcel/watcher,@swc/core,protobufjs,koffi <pkg-name>
# 或永久配置（针对所有全局安装）
npm config set allow-scripts=<pkg-name>,better-sqlite3,keytar,tls-client-node,onnxruntime-node,sharp,core-js,esbuild,@parcel/watcher,@swc/core,protobufjs,koffi --location=user
典型案例：安装 omniroute 后 omnirroute doctor 报 WARN Native binary: better-sqlite3 native binary was not found，需要上面命令重装。
判断逻辑：
npm install -g输出末尾如果有npm warn install-scripts N packages had install scripts blocked→ 必须重装- 装完后用 CLI 自带的诊断命令验证：
omniroute doctor/claude doctor/ 看启动日志有没有native binding报错 - 千万别只看
package count changed当成功 — 那只是 JS 依赖装齐，native 层还裸着
诊断清单（安装含原生模块的 npm CLI 后必跑）：
# 1. CLI 启动？
<cli> --version
# 2. 加载 native 模块？大多数 CLI 有 doctor / status 子命令
<cli> doctor
# 看 native / database / native-binary 行
# 3. 真启动一次前台短跑
timeout 15 <cli> 2>&1 | head -30
# exit=124 (timeout kill) = 服务正常启动并 idle
# exit != 124 = 启动失败，看 stderr
ModelScope 下载
ModelScope（modelscope.cn）下载模型不需代理，且比 HuggingFace 更稳定（国内 CDN）。
HuggingFace 模型下载的 4 种备选方案（按优先级）
在 WSL 国内网络环境下，HuggingFace 下载常失败。逐级尝试：
方案 1: hf-mirror Git Clone + LFS
git clone https://hf-mirror.com/<org>/<repo> checkpoints
cd checkpoints && git lfs pull
注意：GIT_LFS_SKIP_SMUDGE=1 会跳过 LFS 文件（只下载指针），网络不好时反而不行。
方案 2: Modelscope Git Clone + LFS
git clone https://www.modelscope.cn/<org>/<repo>.git checkpoints
cd checkpoints && git lfs pull
用 modelscope 的 git 服务，国内 CDN 更稳定。
方案 3: HuggingFace CLI 直下
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download <org>/<repo> --local-dir checkpoints
但 hf-mirror 经常超时导致静默失败（exit 0 但只下了一个小文件）。验证：du -sh checkpoints/ 应该在 GB 级。
方案 4: Modelscope Python SDK
from modelscope import snapshot_download
snapshot_download('<org>/<repo>', local_dir='checkpoints')
LFS 下载验证
LFS 文件下载后在 .git/lfs/incomplete/ 中说明下载中断。删除 incomplete 目录重试：
rm -rf .git/lfs/incomplete && git lfs pull
成功的 LFS 文件应在 .git/lfs/objects/ 中，且根目录出现实际大文件（而非指针）。
uv sync 静默失败与大型 ML 项目依赖安装
症状
uv sync exit code 0，但 .venv/lib/python3.12/site-packages/ 只有 _virtualenv.pth，没有任何实际包。
原因
uv sync在锁文件已存在时可能跳过实际安装（尤其在 NTFS 盘或网络不稳时）uv lock在大型项目（如 PyTorch + CUDA 包依赖）上耗时极长（300s+ 超时）
解决：直接 pip 安装
# 1. 创建 venv（不用 uv sync）
uv venv --python 3.12
# 2. 安装 pip
uv pip install --python .venv/bin/python pip
# 3. 用 pip 直装 PyTorch（CUDA 版）
.venv/bin/python -m pip install \
-i https://download.pytorch.org/whl/cu128 \
torch torchaudio \
--extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 4. 装其他依赖
.venv/bin/python -m pip install \
-i https://pypi.tuna.tsinghua.edu.cn/simple \
transformers fastapi soundfile ...
CUDA 库版本不匹配（PyTorch + nvidia pip 包）
PyTorch 的 torchaudio .so 文件链接到 libcudart.so.12，但 pip 安装的 nvidia-cuda-runtime 可能提供 libcudart.so.13（CUDA 13.x 驱动）。
解决：设置 LD_LIBRARY_PATH 包含所有 nvidia pip 包的 lib 目录：
NVIDIA_LIB=$(find ~/.local/share/uv/python/cpython-3.12.*/lib/python3.12/site-packages/nvidia -name "lib" -type d | tr '\n' ':')
export LD_LIBRARY_PATH="${NVIDIA_LIB}/usr/lib/wsl/lib"
/tmp 磁盘空间不足
在 ML 项目中 pip 安装大包（如 nvidia-cudnn 366MB）时可能报 No space left on device。WSL 的 /tmp 通常是 tmpfs（7.8G），容易满。
解决：
mkdir -p ~/tmp
export TMPDIR=~/tmp
或者清理 modelscope 缓存：rm -rf /tmp/ms_cache
Fish shell: set -x 环境变量不生效
Fish 的 set -x VAR val; cmd 在某些场景（如 uv tool upgrade）环境变量不会被命令继承。
用 env 前缀替代：
# ❌ 不生效
set -x UV_HTTP_TIMEOUT 300; uv tool upgrade astrbot
# ✅ 生效
env UV_HTTP_TIMEOUT=300 uv tool upgrade astrbot
uv.toml 国内镜像
[pip]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
创建于项目根目录即可。与 pyproject.toml 中的 [tool.uv] 冲突时 uv.toml 优先。
uv tool 命令走镜像（不依赖 uv.toml）
uv tool upgrade/install 不受项目 uv.toml 控制。大包超时时直接设 UV_INDEX_URL：
env UV_HTTP_TIMEOUT=300 UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv tool upgrade astrbot --python 3.12
PYTHONPATH 全局污染（Hermes Agent）
Hermes Agent 设置了全局 PYTHONPATH=/home/po/.hermes/hermes-agent，导致所有 Python 的 sys.path 都被注入该路径。在 WSL 中运行其他 Python 项目（尤其是 ML 项目）时，这会引发包版本冲突。
解决：启动其他 Python 应用时 unset：
PYTHONPATH= python3 server.py
# 或
unset PYTHONPATH
uv pip install vs pip install 找不到 venv
uv pip install 默认在项目目录找 .venv。如果 venv 在其他位置：
uv pip install --python /path/to/venv/bin/python <package>
终端工具 "uvicorn" 关键字误判
Hermes 终端工具会检测命令中是否包含 uvicorn 并误判为长时服务器进程，拒绝执行。pip install uvicorn 或 pip show uvicorn 都会被拦截。
绕过：用 execute_code 工具调用 subprocess.run：
from hermes_tools import terminal
import subprocess
subprocess.run([venv_python, "-m", "pip", "install", "-i", mirror, "uvicorn"], ...)
或者用文件间接传递包名：echo 'uvicorn' > /tmp/pkg.txt && pip install -r /tmp/pkg.txt
uvicorn ML 服务：模型双加载陷阱
uvicorn.run("server:app") 会导致模型加载两次：
- Python 以
__main__运行server.py - uvicorn 重新 import
server模块（不同__name__） - 两个
IndexTTS2()实例 → VRAM ×2 → OOM
正确写法：
if __name__ == "__main__":
# 加载模型
model = load_model()
# 传入 app 对象，不是 "module:app" 字符串
uvicorn.run(app, host="0.0.0.0", port=8800)
另外 uvicorn lifespan 有 5 秒默认超时，模型加载（~35s）不能放在 lifespan startup 中。
PowerShell 一行启动 WSL 里安装的 CLI（hermes / claude / codex …）
Windows 终端里想直接敲 hermes / claude / codex 调 WSL 里的 CLI（典型场景：WSL 配好了全套 env 和 venv，但人在 PowerShell 里），wsl <cmd> 这种直觉写法一连踩三个坑：
坑 1：wsl <cmd> 找不到命令 — wsl 默认 PATH 不带 ~/.local/bin
wsl -e bash -lc "hermes" 启动的 shell 只继承 WSL 默认用户的 PATH（/usr/bin 等），不读 .bashrc 里的 export PATH 也不读 ~/.local/bin/env。hermes / claude / codex 全装在 ~/.local/bin/，直接报 未找到命令。
绕过：直接走绝对路径，不依赖 PATH 解析：
# ❌ 错
wsl hermes
wsl -e bash -lc "hermes"
# ✅ 对 — 直接调 venv 里的 entry point
wsl -e bash -lc "/home/po/.hermes/hermes-agent/venv/bin/hermes"
坑 2：wsl -e bash -lc "~/..." 中 ~ 解析成 /root — wsl 默认登录用户是 root
wsl -e 不带 -u 时用 /etc/wsl.conf 的 default 用户（默认 root）。~ 在 bash -lc 字符串里被 root 用户解析成 /root，不是 /home/po，于是报 /root/.local/bin/hermes: 没有那个文件或目录。
绕过：绝对路径写死，或用 -u po 切用户（但切用户会丢 root 那边的 env，见坑 3）。
坑 3：切到 -u po 后丢失 API key / proxy / 各种 env
hermes / claude 这类工具要读一堆 env（DEEPSEEK_API_KEY、BAILIAN_API_KEY、HTTPS_PROXY、NAPCAT_TOKEN、PYTHONPATH…）。WSL 默认 root 登录 shell 里这些 env 是齐的（写在 /etc/profile.d/ 或 root 的 .bashrc）。切到 -u po 后 po 的 shell 没这些 export，工具启动报"no API keys or providers found"。
最干净的解法：保持默认用户 root + 绝对路径调 po 的 venv，root 的 env 全在，po 的库全在：
# PowerShell $PROFILE 里加：
function hermes { wsl -e bash -lc "/home/po/.hermes/hermes-agent/venv/bin/hermes $($args -join ' ')" }
变体：
- claude code：
/home/po/.local/bin/claude（如果装在~/.local/bin而非 venv） - codex：
/home/po/.npm-global/bin/codex
验证链路是否通：
wsl -e bash -lc '/home/po/.hermes/hermes-agent/venv/bin/hermes --version'
# 应输出 Hermes Agent v... 不报 file not found
不输出 version = 路径错了；version 出来了但还是 "no providers" = 坑 3，切用户了。
坑 4：wsl -e bash -lc "..." 先进 fish 后才执行 hermes — -l + TTY 让 bash 卡在登录 shell 交互模式
症状：用户报"PowerShell 函数执行时先进入 WSL 的 fish / 显示 welcome banner，等我退出后再进 hermes"。
原因：wsl -e bash -lc "cmd" 中 -l 让 bash 作为登录 shell 启动。bash 登录 shell 看到 stdin/stdout 是 TTY（PowerShell 传过来的就是）→ 进交互模式 → 先读 .bash_profile / .profile、打印 PS1 等用户输入 → 然后才把 -c 字符串作为命令执行。用户的默认登录 shell 是 fish 时，会先看到 fish 的 welcome / 主题渲染，命令才执行。
官方文档依据（Microsoft WSL docs）：
"The Linux command following
wslis handled like any command run in WSL. Run as the WSL default user."wsl -e跳过默认 Linux shell，但仍会按你指定的 shell（bash）启动；如果加了-l它就走 login shell 路径。
修复：去掉 -l，用 bash -c 直接执行命令字符串：
# ❌ 错 — 触发登录 shell 交互模式
function hermes { wsl -e bash -lc "/home/po/.../hermes $($args -join ' ')" }
# ✅ 对 — bash -c 不读 .bash_profile，不进交互模式
function hermes { wsl -e bash -c "/home/po/.../hermes $($args -join ' ')" }
更优雅：直接走 wsl 默认 shell，把 HOME 用 env 前缀传给 hermes：
# 最简版：让 wsl 默认 shell（root 的 fish / bash）直接 exec hermes
function hermes { wsl HOME=/home/po /home/po/.hermes/hermes-agent/venv/bin/hermes $args }
HOME=val command 是 POSIX / fish / zsh / dash 通用语法，shell 看到就直接 exec hermes，不启新 shell。
副作用：bash -c（去掉 -l）不读 .bash_profile / .profile，所以 root 登录 shell 里 export 的 env（API key / proxy）会丢。如果 hermes 报"no API keys"，需要显式透传：
# 把 PowerShell 的关键 env 透传给 WSL root
function hermes {
$envArgs = @()
foreach ($name in 'HTTPS_PROXY','HTTP_PROXY','BAILIAN_API_KEY','DEEPSEEK_API_KEY','NAPCAT_TOKEN') {
if ($env:$name) { $envArgs += '--env', "$name=$($env:$name)" }
}
& wsl.exe @envArgs -e bash -c "HOME=/home/po /home/po/.hermes/hermes-agent/venv/bin/hermes $($args -join ' ')"
}
但 hermes 默认优先读 ~/.hermes/config.yaml 里写死的 key，不一定依赖瞬时 env。先试最简版，报"未配置"再加 env 透传。
官方 env 共享机制（更系统化）：PowerShell 那边设置 WSLENV 变量列表，决定哪些 Windows env 自动透传到 WSL：
$env:WSLENV = "HTTPS_PROXY/u:HTTP_PROXY/u:BAILIAN_API_KEY/u:DEEPSEEK_API_KEY/u:NAPCAT_TOKEN/u"
/u 标志表示"只在从 Win32 调用 WSL 时透传"。设一次，所有 wsl 命令都生效。
根本修复（一次解决所有坑）
把 hermes 需要的 PATH 补进 /etc/profile.d/，所有用户登录都有：
sudo tee /etc/profile.d/hermes-env.sh <<'EOF'
export PATH="$HOME/.local/bin:$PATH"
# 其他需要持久化的 env 在这里 export
EOF
要 sudo，你自己粘贴进 WSL 跑。
WSLg 在跑但 Electron 报 Missing X server / SIGSEGV
症状：$DISPLAY 空 + Missing X server or $DISPLAY + The platform failed to initialize. Exiting，有时末尾 SIGSEGV。/tmp/.X11-unix/X0 在，/mnt/wslg 挂载正常，cat /mnt/wslg/versions.txt 能看到版本号。
根因：WSLg daemon 起来了，但 systemd user bus 没把 XDG_RUNTIME_DIR / DISPLAY / WAYLAND_DISPLAY / PULSE_SERVER 注入到当前 session。仅靠 socket 文件不够，shell 必须有这几个 env，Electron / GTK / Qt 才会走 ozone/wayland backend。
诊断三连（验证 daemon vs session 注入是两层问题）：
# 1. WSLg daemon 在跑？
ls /tmp/.X11-unix/X0 /mnt/wslg/versions.txt # 都在 = daemon 活
cat /mnt/wslg/versions.txt | head -1 # 看版本（1.0.73+ 才稳）
# 2. session 拿到 env 了吗？
fish -lc 'env | grep -E "DISPLAY|WAYLAND|XDG_RUNTIME|PULSE"'
bash -lc 'env | grep -E "DISPLAY|WAYLAND|XDG_RUNTIME|PULSE"'
# 全部空 = 注入断了
# 3. systemd user bus 通吗？
systemctl --user is-active
# "Failed to connect to user scope bus via local transport: $DBUS_SESSION_BUS_ADDRESS and $XDG_RUNTIME_DIR not defined"
# = bus 断了 → env 注入源头断了
修复（按"最简修法优先"，用户级不改 system）：
手 export 当前 shell 验证（确认 fix 方向）：
export XDG_RUNTIME_DIR=/run/user/$(id -u) export DISPLAY=:0 export WAYLAND_DISPLAY=wayland-0 export PULSE_SERVER=unix:/mnt/wslg/PulseServer /opt/<app>/<binary> # 现在应能拉起 GUI，不再 SIGSEGV持久化到 fish config（不动 system，不动
/etc/profile.d/）：# ~/.config/fish/config.fish set -q XDG_RUNTIME_DIR[1]; or set -gx XDG_RUNTIME_DIR /run/user/(id -u) set -q DISPLAY; or set -gx DISPLAY :0 set -q WAYLAND_DISPLAY; or set -gx WAYLAND_DISPLAY wayland-0 set -q PULSE_SERVER; or set -gx PULSE_SERVER unix:/mnt/wslg/PulseServerset -q ... [1]; or模式只在 env 缺失时设置，避免覆盖 WSL 自己的注入（如果以后修了）。exit重进 fish 生效。exec fish或关掉 terminal 重开。
判断 shortcut：
/tmp/.X11-unix/X0不存在 → WSLg 没装/没启，重装wsl --update并重启 WSL- 存在但
$DISPLAY空 → 本节问题（session 注入断） - 都正常但 App 仍 SIGSEGV → 概率是 Electron 走错 ozone backend，强行
--ozone-platform=wayland或--in-process-gpu试
反模式（不要走）：
sudo tee /etc/profile.d/wslg-env.sh改全局 → 用户的硬约束是不自动 sudoexport DISPLAY=:0; export ... ; ./binary一行流 → 单次能用，下次进 shell 又没- 改
/etc/wsl.conf重启 WSL → 杀 Hermes TUI，得不偿失
AUR 装 Electron GUI App：CLI 是 IPC bridge，不是独立二进制
踩坑实记（用户在 Arch WSL 装 stably-orca-bin 后 command -v orca 找不到）：
$ pacman -Ql stably-orca-bin | grep 'bin/'
stably-orca-bin /opt/stably-orca/orca-ide # 主入口（GUI 启动器）
stably-orca-bin /opt/stably-orca/orca-ide.desktop
stably-orca-bin /usr/bin/stably-orca # 仅 GUI 启动器
stably-orca-bin /opt/stably-orca/resources/darwin/bin/orca # macOS 专用
stably-orca-bin /opt/stably-orca/resources/win32/bin/orca.cmd # Windows 专用
$ command -v orca
missing
根因：AUR 包 = Electron App 预编译 AppImage，只装 GUI 启动器和 .desktop。CLI（如 orca worktree create、orca terminal send）是 App 运行时通过 IPC 暴露的 bridge——App 不跑 = CLI 不存在。resources/darwin/ 和 resources/win32/ 下的 orca 二进制是给那两平台的，Linux 上不适用。
判断逻辑：
pacman -Qi <pkg>看装没装command -v <cli-name>确认 CLI 没暴露到 PATH（这是预期）pacman -Ql <pkg> | grep -E 'bin/'看实际有什么二进制- 启 GUI 验证：手 export WSLg env（见上节）+
/opt/<app>/<binary>，确认 App 能拉起 GUI 窗口 - App 跑起来后
orca ...CLI 才会变可用（IPC 起作用）
没 GUI 会话就别装。WSL headless + 无 X 转发 + 无 DISPLAY 时这包完全无用——只能去 /opt/ 吃灰，触发的所有 skill 触发链都是断的。
正确判断装哪个：
| 想用 | 装什么 | WSL 可行？ |
|---|---|---|
| GUI + 内部 CLI bridge | AUR <app>-bin + WSLg |
✅ 但要先有 WSLg env 注入 |
| 只用 CLI（脚本化） | 不能用 AUR；Windows 装 <app>.exe + ORCA_CLI_COMMAND 注入 WSL |
✅ Windows 必须有 |
| Remote 模式（CLI 管 headless runtime） | AUR <app>-bin + <app> serve |
⚠️ 新功能，稳定性未知 |
给 AI 自己的教训：当 skill 描述里 fire orca 这种命令时，先 verify CLI 在 PATH 上能跑，再决定要不要 fire。装 skill ≠ 触发链通了。
WSL sshd 绑 22 失败：Windows 宿主的幽灵占用
症状：systemctl start sshd 反复失败（最后 start-limit-hit），前台 sudo /usr/sbin/sshd -D -d 报 Bind to port 22 on 0.0.0.0 failed: Address already in use——但 WSL 里 ss -tlnp | grep :22 和 ps aux | grep sshd 都为空。
根因：Windows 宿主跑着 OpenSSH Server 占 22。WSL2 的 localhost 转发机制让 Windows 的 22 在 WSL 里表现为"已占用"，但占用进程不在 WSL 的网络命名空间里，所以 WSL 的 ss/ps 看不见。ssh localhost 会连到 Windows 的 sshd 而不是 WSL 的。
验证方法（指纹比对）：先 sudo ssh-keygen -A 后 ssh localhost，比对返回的 host key 指纹和你刚生成的 /etc/ssh/ssh_host_ed25519_key.pub 指纹——不一致即实锤连到了别的 sshd。
修法（推荐换端口，不动宿主）：
echo 'Port 2222' | sudo tee -a /etc/ssh/sshd_config
sudo systemctl reset-failed sshd # 清 start-limit-hit 熔断
sudo systemctl restart sshd
sudo ss -tlnp | grep 2222 # 确认 LISTEN
ssh -p 2222 localhost # 指纹应匹配 WSL 的 host key
为什么不动 Windows 侧：关宿主 OpenSSH Server 可能影响其他用途，换端口一行配置就绕过。
systemd 反复失败后的熔断：journalctl 里只看到 start-limit-hit 而看不到真实错误时，真实原因已被刷掉——先 sudo /usr/sbin/sshd -D -d 前台跑看首行报错，再 systemctl reset-failed 清熔断重试。
参考文件
references/uu-remote-ssh-tunnel.md— UU 远程端口映射 → WSL sshd 的完整方案（FRP 替代，含端口选择理由和迁移判断）references/deepseek-react-patterns.md— DeepSeek ReAct Agent 在 WSL 下的具体坑references/deepseek-api-patterns.md— DeepSeek API 的 ReAct/Function Calling 坑和写法（从 wsl-python-development 合并）references/mcp-fastmcp-api.md— MCP FastMCP 三种传输协议的现行 API（从 wsl-python-development 合并）references/paddlepaddle-setup.md— 百度飞桨在 WSL 上的安装、GPU 配置、3.3.0 API 已知坑references/indextts-deploy.md— Index-TTS 在 WSL 上的完整部署实录（依赖安装、模型下载、AstrBot 插件）references/powershell-wsl-launch.md— PowerShell 一行启动 WSL 里安装的 CLI（hermes / claude / codex 等）的 4 个连环坑（含bash -lc登录 shell 卡 PS1 / fish welcome）references/wsl-to-windows-file-copy.md— WSL → Windows NTFS 大文件传输的cp静默截断 + PowerShell SMB 路径（\\wsl.localhost\<distro>\...）解法references/github-release-download.md— GitHub release 资产下载的 JWT 签名陷阱（续传无效 / WSL 长连接慢）和 gh CLI + 浏览器替代方案templates/hello_paddle_mnist.py— 飞桨 3.3.0 兼容的 MNIST 训练模板scripts/wslg-diagnose.sh— WSLg daemon vs session env 注入的诊断脚本（daemon 装着但$DISPLAY空时一键给出 fix 方案）