Add README with install, verification, and portability guide

2026-04-22 08:36:07 +08:00
parent 8138fb011d
commit ed0f6fd508
1 changed files with 168 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,168 @@
+# watchdog-discord-route
+
+Portable OpenClaw skill bundle for the **watchdog-b owner-facing Discord route**.
+
+This repo packages the scripts, env example, systemd user units, and skill documentation needed to install, verify, and repair the path:
+
+`watchdog-b -> notify_watchdog_b.py -> owner_report_producer.py -> owner_report_driver.py -> OpenClaw Discord send -> sent archive`
+
+## What this is for
+
+Use this bundle when you need to:
+
+- install watchdog-b on another OpenClaw host
+- verify end-to-end owner-facing Discord delivery
+- repair broken `owner_report_*` routing
+- refresh the live bundle under `scripts/watchdog-b/`
+- enable the `systemd --user` timer for watchdog-b
+
+## What is included
+
+### Skill docs
+- `SKILL.md`
+
+### Scripts
+- `scripts/check_openclaw_state.sh`
+- `scripts/run_watchdog_b.sh`
+- `scripts/notify_watchdog_b.py`
+- `scripts/verify_watchdog_b_e2e.sh`
+- `scripts/owner_report_consumer.py`
+- `scripts/owner_report_producer.py`
+- `scripts/owner_report_driver.py`
+- `scripts/install_watchdog_bundle.sh`
+- `scripts/bootstrap_watchdog_bundle.sh`
+- `scripts/openclaw_runtime_probe.py`
+- `scripts/watchdog-b.env.example`
+
+### systemd --user units
+- `scripts/openclaw-watchdog-b.service`
+- `scripts/openclaw-watchdog-b.timer`
+
+### References
+- `references/watchdog-b-readme.md`
+- `references/owner-reporting-system.md`
+- `references/owner-report-operator-manual.md`
+
+## Recommended install order
+
+Run from inside this repo:
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example
+mkdir -p ~/.config/openclaw
+cp ~/.config/openclaw/watchdog-b.env.example ~/.config/openclaw/watchdog-b.env
+```
+
+Then edit at least:
+
+```bash
+WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
+```
+
+Then validate:
+
+```bash
+./scripts/bootstrap_watchdog_bundle.sh
+```
+
+Only after bootstrap passes:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now openclaw-watchdog-b.timer
+```
+
+## Quick update / refresh on a host
+
+If you already have the repo or bundle and just want to refresh the live install:
+
+```bash
+./scripts/install_watchdog_bundle.sh --install-env-example --force
+./scripts/bootstrap_watchdog_bundle.sh
+```
+
+## End-to-end verification
+
+Run:
+
+```bash
+cd ~/.openclaw/workspace/scripts/watchdog-b
+./verify_watchdog_b_e2e.sh
+```
+
+Minimum success evidence:
+
+- pending owner report created
+- report moved to `~/.clawteam/owner-reports/sent/`
+- Discord send returns success / message id
+- artifacts written under `state/watchdog-b-verify-e2e/<run-id>/`
+
+Useful verification files:
+
+- `verify.log`
+- `run-output.txt`
+- `queue-before.txt`
+- `queue-after.txt`
+- `sent-head.txt`
+- `state/notify-state.json`
+
+## Important config
+
+Expected live config lives in:
+
+- `~/.config/openclaw/watchdog-b.env`
+
+Typical minimum values:
+
+```bash
+WATCHDOG_B_NOTIFY_DRY_RUN=0
+WATCHDOG_B_RUNNING_REPORT_MODE=enqueue-and-drain
+WATCHDOG_B_OWNER_DELIVERY_MODE=direct-discord
+WATCHDOG_B_OWNER_REPORT_CHANNEL=discord
+WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
+```
+
+Optional if the host really has a valid OpenClaw agent id:
+
+```bash
+WATCHDOG_B_MAIN_AGENT_ID=backend
+```
+
+If this is unset, stalled/idle paths skip main-agent nudge instead of failing on `Unknown agent id`.
+
+## Known pitfalls fixed in this bundle
+
+This bundle already includes fixes for these previously observed issues:
+
+1. **Wrong producer path**
+   - bad: `.../workspace/scripts/scripts/owner_report_producer.py`
+   - fixed: `.../workspace/scripts/watchdog-b/owner_report_producer.py`
+
+2. **Missing consumer in portable bundle**
+   - `owner_report_consumer.py` is included and installed to the live bundle
+
+3. **Bootstrap wrongly required old live owner-reporting-system tree**
+   - bootstrap now validates the installed live bundle under `scripts/watchdog-b/`
+
+4. **Invalid hard-coded `main` agent nudge**
+   - nudge now uses `WATCHDOG_B_MAIN_AGENT_ID` only when configured
+
+## Evidence standard
+
+When claiming success, distinguish these clearly:
+
+- **transport accepted**: send returned success / message id
+- **channel-readable**: message can be read back from the target Discord channel
+- **human-confirmed**: the user confirms they saw it
+
+Do not collapse them into one claim.
+
+## Safety / cleanup rules
+
+- Do **not** delete `~/.clawteam/owner-reports/sent/` history unless explicitly asked
+- Do **not** delete live `state/watchdog-b/notify-state.json` unless explicitly doing a hard reset
+- Prefer archiving old test residue under `state/archive/<timestamp>/`
+
+## Repo purpose
+
+This repo is meant to be a reusable, host-portable source of truth for the watchdog-b Discord delivery path, not just a local one-off workspace patch.