tgo-summary-env-pitfall.md
3.53 KB
TGO 摘要子进程环境变量 Pitfall(2026-07-26)
现象
TGO 群文章预摘要(/api/articles/summarize)提交后,任务状态显示 started,但稍后通过 batch_summarize.py 轮询或 /api/jobs 查看时,所有摘要任务均为 failed。
/tmp/hermes_jobs/<task_id>.log 中的关键报错:
Traceback (most recent call last):
File "/data/data/com.termux/files/usr/bin/hermes", line 6, in <module>
sys.exit(main())
...
File "/data/data/com.termux/files/home/hermes-agent-v0.19.0/hermes_cli/config.py", line 893, in ensure_hermes_home
home.mkdir(parents=True, exist_ok=True)
File "/data/data/com.termux/files/usr/lib/python3.14/pathlib/__init__.py", line 1011, in mkdir
os.mkdir(self, mode)
OSError: [Errno 30] Read-only file system: '/pixelphone'
根因
wechat-viewer/app.py 的 _spawn_hermes_job() 函数在启动 hermes chat 子进程时调用:
proc = subprocess.Popen(cmd, stdout=lf,
stderr=subprocess.STDOUT, text=True,
cwd=str(Path(__file__).parent), env=env)
env 由调用方(如 api_article_summarize())显式传入,仅包含 HOME 和 HERMES_HOME。subprocess.Popen(env=...) 的语义是完全替换子进程环境,而不是在父进程环境基础上叠加。结果子进程丢失了 PATH、LD_LIBRARY_PATH 等必要变量,并触发了某些环境相关的路径解析问题,最终 hermes CLI 把 HOME 解析为 /(或干脆未设置),试图创建 /pixelphone 而失败。
修复
将 env 合并到 os.environ.copy() 上,再传给 Popen:
# merge provided env on top of current process env so PATH/HOME survive
merged_env = os.environ.copy()
if env:
merged_env.update(env)
proc = subprocess.Popen(cmd, stdout=lf,
stderr=subprocess.STDOUT, text=True,
cwd=str(Path(__file__).parent), env=merged_env)
注意:必须重启 Flask(bash ~/wechat-viewer/restart.sh)才能使修改生效。app.py 在 DEBUG=False 下不会自动重载。
验证
- 重启 Flask 后,提交一篇未缓存文章的摘要:
bash curl -s -X POST http://127.0.0.1:5001/api/articles/summarize \ -H 'Content-Type: application/json' \ -d '{"url":"https://mp.weixin.qq.com/s/...","title":"..."}' - 等待 30-180 秒,查看
/api/jobs:- 修复前:
status: failed,log 中出现OSError: [Errno 30] Read-only file system: '/pixelphone' - 修复后:
status: completed,daily_reports中新增摘要记录
- 修复前:
排查命令
# 查看最新失败日志
tail -n 50 /data/data/com.termux/files/home/tmp/hermes_jobs/$(ls -t /data/data/com.termux/files/home/tmp/hermes_jobs/ | head -1)
# 查看未摘要文章数量
python3 - <<'PY'
import urllib.request, json
resp = urllib.request.urlopen('http://127.0.0.1:5001/api/articles/unsummarized', timeout=120).read()
d = json.loads(resp)
print('unsummarized count:', len(d['data']))
PY
相关文件
wechat-viewer/app.py— 修复点:_spawn_hermes_job()中subprocess.Popen(env=...)的env合并逻辑wechat-viewer/batch_summarize.py— 用于批量轮询摘要任务wechat-viewer/restart.sh— 重启 Flask 服务脚本
时间线
- 2026-07-26 09:00 左右:TGO 摘要任务批量失败,日志报
/pixelphone只读错误。 - 2026-07-26 09:08:定位根因为
subprocess.Popen(env=env)替换环境变量。 - 2026-07-26 09:09:修复
app.py,合并环境变量。 - 修复后因 5001 端口被旧 Flask 进程占用,未能立即重启验证,需手动释放端口后重启。