release: public alpha 0.6.0 baseline

2026-10-15 03:58:31 +08:00
commit d4242ae07c
238 changed files with 37724 additions and 0 deletions
@@ -0,0 +1,138 @@
+# Zero To Running
+
+This runbook prepares a new apt-based Linux host without embedding any private
+host, account, group, or provider value in the repository.
+
+JWeBot does not install desktop WeChat itself. Install a compatible client,
+create an X11/VNC desktop on display `:1`, sign in manually, and keep the main
+window visible before deployment.
+
+## 1. Obtain A Clean Snapshot
+
+Clone or unpack the public repository. Before using a fork:
+
+```sh
+./tools/check-secrets.py --history
+```
+
+## 2. Prepare The Host
+
+Run as root:
+
+```sh
+./deploy/scripts/bootstrap-jwebot.sh \
+  prepare \
+  /path/to/JWeBot \
+  jwebot \
+  default
+```
+
+The six-stage prepare flow:
+
+1. installs OS packages for Python, X11 interaction, screenshots, clipboard,
+   and OCR fallback;
+2. creates the runtime account when absent;
+3. creates `/opt/jwebot/venv`;
+4. installs runtime Python dependencies and JWeBot packages;
+5. generates a private config profile;
+6. creates private state directories.
+
+## 3. Configure
+
+Edit:
+
+```text
+/home/jwebot/.config/jwebot/profiles/default/
+```
+
+At minimum:
+
+- set the bot mention and provider URLs in component TOML;
+- put API keys only in `secrets/runtime.env`;
+- configure Steam owner ID and loopback proxy when using `/steam`;
+- put person aliases only in `context/people.json`;
+- configure a notification argv adapter or leave it disabled;
+- verify deployment paths.
+
+Activate as the runtime user:
+
+```sh
+sudo -u jwebot -H /opt/jwebot/venv/bin/python \
+  -m jwebot_config activate default
+```
+
+## 4. Prepare The Desktop
+
+The runtime expects:
+
+- an X11 desktop at `DISPLAY=:1`;
+- the runtime user's `.Xauthority`;
+- a visible WeChat main window named `Weixin`;
+- a maximized window large enough for the adaptive layout gate;
+- loopback VNC on port `5901` for guarded input;
+- no second process controlling the same GUI.
+
+VNC/noVNC must remain loopback-only or be reached through an authenticated SSH
+tunnel. Never expose it directly.
+
+## 5. Verify
+
+```sh
+./deploy/scripts/bootstrap-jwebot.sh \
+  verify \
+  /path/to/JWeBot \
+  jwebot \
+  default
+```
+
+Verify checks runtime imports, required executables, profile validation,
+repository config/privacy gates, and the visible WeChat window.
+
+## 6. Deploy
+
+```sh
+./deploy/scripts/bootstrap-jwebot.sh \
+  deploy \
+  /path/to/JWeBot \
+  jwebot \
+  default
+```
+
+This invokes the coordinated production deployer. It does not bypass queue,
+ready-window, health, SQLite, or restart-stability gates.
+
+## 7. Acceptance
+
+```sh
+systemctl --user is-active jwebot-edge.service
+systemctl --user is-active wechat-ocr-adaptive-recorder.service
+```
+
+```sh
+printf '%s\n' '{"op":"health"}' |
+  /opt/jwebot/venv/bin/python \
+  ~/.local/lib/wechat-health-watch/jwebot_edge.py respond
+```
+
+Send synthetic messages in the configured group:
+
+```text
+@JWeBot /version
+@JWeBot /steam
+@JWeBot /steam时长Dota2
+```
+
+Confirm one ACK, one final reply, no duplicate delivery, empty queues, stable
+restart counts, and SQLite `quick_check=ok`.
+
+## Non-Apt Hosts
+
+Use `prepare` as a dependency manifest:
+
+- install equivalent X11, OCR, Python, and clipboard packages;
+- create the same runtime user and virtualenv;
+- run `jwebot_config init/activate`;
+- run the verify and coordinated deployment gates manually.
+
+Do not translate package names into an unreviewed installer and run it directly
+on production.