pgworker 0.1.0

Thin local CLI relay for the prove-graph backend — spawns codex / claude / deepseek subprocesses on user machines and streams stdout/stderr back over WebSocket.

pgworker — 用户机器的本地守护进程

它是什么

一个跑在用户自己电脑上的 asyncio 守护进程，作为 prove-graph 后端 的远程 subprocess 中继。后端通过 WebSocket 发 stage.request （一段渲染好的 prompt + 调哪个 CLI 的指令），pgworker 起本机 codex / claude / deepseek 子进程，把 stdout 流式回传。

具体职责：

1. 维持一条到 web backend 的长 WebSocket 连接（应用层 ping/pong）
2. 接 stage.request，在 ~/.pgworker/scratch/<stage_run_id>/ 下喂 stage.request.files、起 subprocess、流回 stdout/stderr
3. 接 stage.cancel，SIGTERM/SIGKILL 当前子进程
4. 不持有 problem 状态、不 import prove_graph、不知道 当前 stage 是 analyze / attempt / verify、graph 长什么样

也就是说：它是 backend 在用户机器上的一只胳膊，仅此而已。 graph、prompt、orchestration、不变量都在服务端，不会进入用户机器。

包独立性

pgworker 是个独立的 PyPI 包（pgworker/pyproject.toml），依赖只有：

httpx>=0.27
websockets>=12
pydantic>=2.7

不依赖 prove-graph 框架包。用户安装：

pip install "pgworker @ git+https://github.com/ustc-ai4m/prove-graph.git#subdirectory=pgworker"

需要 Python 3.10+。装完 pgworker 命令在 PATH 上。装好的 pgworker 跑 python -c "import prove_graph" 会报 ModuleNotFoundError——这是 有意的：framework 代码不该出现在用户机器上。

协议版本

当前 pgworker 上报 protocol_version: 2（thin-worker 协议）。 服务端只接受 protocol_version >= 2 的连接。pgworker 与服务端的协议 规格在项目内部文档中维护；公开 PyPI 用户只需要 pgworker pair + pgworker run 两条命令。

注：上游 prove-graph 项目本身是私有仓库；pgworker 是它唯一公开 的脚手架包。装这个包不会让你访问到 prove-graph 框架代码。

为什么单列一个顶级目录

它不是框架库，所以不该在 prove_graph/ 包里。它不是 web 服务，所以也不该在 backend/ 里。它是第三类东西——"用户机器侧 的执行入口 + web 客户端"，与 backend/ 是同级 peer 部署。

它有寿命

本目录是过渡期产物。本项目的长期目标是 PydanticAI agent 在云端 全面接管，届时用户机器不再需要跑任何东西，所有 round 都在网页 backend 自己进程里完成。

当下面这两个条件同时满足时，整个 pgworker/ 目录可以一次性删除：

1. PydanticAI agent 在网页端各项任务上稳定性 / 质量 ≥ 现行的 Claude Code / Codex
2. 用户群体里再没有强烈的"我要用本机 claude/codex"诉求

届时清理步骤：

git rm -rf pgworker/
# backend/app/routers/pgworker.py 删除
# backend/app/services/{worker_registry, stage_relay}.py 删除
# prove_graph/agents/remote_cli.py + worker_protocol.py 删除
# ModelConfig.kind 移除 local-* 三个 kind

这是几十行 diff，没有遗留 cruft——这正是把它顶级单列的目的。

使用

pip install "pgworker @ git+https://github.com/ustc-ai4m/prove-graph.git#subdirectory=pgworker"
pgworker pair <pair-code> --server <网页端 URL>   # 一次性配对（在网页 Settings → Local devices 拿配对码）
pgworker run                                     # 前台跑守护进程；想后台跑请套 systemd / launchd / nohup / screen / tmux

诊断：

pgworker doctor          # 看本机 CLI 版本、token 状态
pgworker capabilities    # 看 capabilities JSON
pgworker revoke          # 删除本机 token

日志在 ~/.pgworker/run.log（5×1MB 轮转）。