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 下不会自动重载。

验证

  1. 重启 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":"..."}'
  2. 等待 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 进程占用,未能立即重启验证,需手动释放端口后重启。