From ae7c5af69d47a288f155760eeb1fd1ac9edbb64a Mon Sep 17 00:00:00 2001
From: Alice <alice_mc_claw@outlook.com>
Date: Wed, 22 Apr 2026 08:49:37 +0800
Subject: [PATCH] =?UTF-8?q?Make=20README=20bilingual=20(=E7=B9=81=E4=B8=AD?=
 =?UTF-8?q?/EN)=20and=20front-load=20quick=20install?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 382 ++++++++++++++++++------------------------------------
 1 file changed, 129 insertions(+), 253 deletions(-)

diff --git a/README.md b/README.md
index fa834cb..afe9fa2 100644
--- a/README.md
+++ b/README.md
@@ -1,313 +1,189 @@
 # watchdog-discord-route
 
-Portable OpenClaw skill bundle for the **watchdog-b owner-facing Discord route**.
+> **繁體中文 / English bilingual README** (same file)
 
-This repo packages the scripts, env example, systemd user units, and skill documentation needed to install, verify, and repair the path:
+這個 repo 是一個可攜式 OpenClaw skill bundle，用於打通並驗證 **watchdog-b → owner-facing Discord** 回報鏈路。
 
-`watchdog-b -> notify_watchdog_b.py -> owner_report_producer.py -> owner_report_driver.py -> OpenClaw Discord send -> sent archive`
+This repo is a portable OpenClaw skill bundle to deliver and verify the **watchdog-b → owner-facing Discord** reporting route.
 
-## Quick install (shortest path)
+---
 
-Run from inside this repo:
+## TL;DR 最短安裝（建議） / Quick Install (recommended)
+
+### 1) 安裝 bundle + 建立設定檔
 
 ```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
+```
+
+### 2) 設定 Discord 目標（必要）
+
+把 `WATCHDOG_B_OWNER_REPORT_TARGET` 改成真的 channel id（不要留 placeholder）：
+
+```bash
 sed -i 's#^WATCHDOG_B_OWNER_REPORT_TARGET=.*#WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID#' ~/.config/openclaw/watchdog-b.env
-./scripts/bootstrap_watchdog_bundle.sh && systemctl --user daemon-reload && systemctl --user enable --now openclaw-watchdog-b.timer
 ```
 
-Replace `YOUR_DISCORD_CHANNEL_ID` with the real target before enabling the timer.
-
-## Install flow
-
-```mermaid
-flowchart TD
-    A[Clone or unpack watchdog-discord-route] --> B[Run install_watchdog_bundle.sh --install-env-example]
-    B --> C[Create ~/.config/openclaw/watchdog-b.env from example]
-    C --> D[Set WATCHDOG_B_OWNER_REPORT_TARGET]
-    D --> E[Run bootstrap_watchdog_bundle.sh]
-    E --> F{Bootstrap passes?}
-    F -- no --> G[Fix config/runtime/path issues and rerun bootstrap]
-    G --> E
-    F -- yes --> H[systemctl --user daemon-reload]
-    H --> I[Enable/start openclaw-watchdog-b.timer]
-    I --> J[Optional: run verify_watchdog_b_e2e.sh]
-```
-
-## 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:
+### 3) Bootstrap（通過後才開 timer）
 
 ```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:
+### 4)（可選）跑 E2E 驗證
 
 ```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>/`
+## 安裝流程圖 / Install Flow
 
-Useful verification files:
+```mermaid
+flowchart TD
+    A[取得 repo / bundle] --> B[install_watchdog_bundle.sh --install-env-example]
+    B --> C[建立 ~/.config/openclaw/watchdog-b.env]
+    C --> D[設定 WATCHDOG_B_OWNER_REPORT_TARGET]
+    D --> E[bootstrap_watchdog_bundle.sh]
+    E --> F{Bootstrap 通過?}
+    F -- 否 / No --> G[修正 env/runtime/path 後重跑 bootstrap]
+    G --> E
+    F -- 是 / Yes --> H[systemctl --user enable --now openclaw-watchdog-b.timer]
+    H --> I[可選：verify_watchdog_b_e2e.sh]
+```
 
-- `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:
+用這個 bundle 來：
 
+- 在新主機快速部署 watchdog-b（採 `systemd --user timer`）
+- 驗證 owner-facing Discord 訊息是否真的送達
+- 修復 `owner_report_*` routing 路徑錯誤
+- 刷新 live bundle（`~/.openclaw/workspace/scripts/watchdog-b/`）
+
+### 包含內容
+
+- Skill 文件：`SKILL.md`
+- Scripts：`scripts/*.sh`, `scripts/*.py`, `scripts/watchdog-b.env.example`
+- systemd user units：`scripts/openclaw-watchdog-b.service`, `scripts/openclaw-watchdog-b.timer`
+- References：`references/*.md`
+
+### 重要設定（單一來源）
+
+設定檔：
 - `~/.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.
-
-## Known troubleshooting FAQ
-
-### 1. `bootstrap_watchdog_bundle.sh` says `owner-reporting-system root missing`
-
-Cause:
-- an older bundle / script still expects the old live tree
-- or the host has not refreshed to the fixed portable bundle yet
-
-Fix:
-- refresh the live bundle:
-
-```bash
-./scripts/install_watchdog_bundle.sh --install-env-example --force
-./scripts/bootstrap_watchdog_bundle.sh
-```
-
-Expected fixed behavior:
-- bootstrap should validate the installed live bundle under `scripts/watchdog-b/`
-- it should **not** require a separate `owner-reporting-system/` live directory
-
-### 2. `can't open file .../scripts/scripts/owner_report_producer.py`
-
-Cause:
-- notifier is using the wrong base path for `owner_report_producer.py`
-
-Bad path:
-- `.../workspace/scripts/scripts/owner_report_producer.py`
-
-Correct path:
-- `.../workspace/scripts/watchdog-b/owner_report_producer.py`
-
-Fix:
-- update to a bundle that uses the live script directory correctly
-- then rerun:
-
-```bash
-./scripts/install_watchdog_bundle.sh --install-env-example --force
-cd ~/.openclaw/workspace/scripts/watchdog-b
-./verify_watchdog_b_e2e.sh
-```
-
-### 3. `Unknown agent id "main"`
-
-Cause:
-- stalled / idle path tried to nudge a hard-coded `main` agent id that does not exist on that host
-
-Fix:
-- either leave `WATCHDOG_B_MAIN_AGENT_ID` unset
-- or set it to a real host-local agent id
-
-Example:
-
-```bash
-WATCHDOG_B_MAIN_AGENT_ID=backend
-```
-
-If unset, the fixed bundle skips main-agent nudge instead of failing.
-
-### 4. `~/.config/openclaw/watchdog-b.env` does not exist
-
-Cause:
-- install copied the example, but the live env was never created
-
-Fix:
-
-```bash
-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
 ```
 
-### 5. Bootstrap passes, but Discord delivery still fails
+可選（只有 host 上真的存在該 agent id 才設）：
 
-Check these in order:
+```bash
+WATCHDOG_B_MAIN_AGENT_ID=backend
+```
 
-1. `WATCHDOG_B_OWNER_REPORT_TARGET` is real, not placeholder
-2. Discord routing actually works on that host
-3. the send was only transport-accepted vs actually channel-readable
-4. `~/.clawteam/owner-reports/pending/` and `sent/` show the expected file movement
-5. `state/watchdog-b-verify-e2e/<run-id>/` contains the expected verification artifacts
+> 未設定時，stalled/idle 的 main-agent nudge 會被 skip，避免因 `Unknown agent id` 直接 fail。
 
-### 6. Timer is active, but owner-facing route still did not work
+---
 
-This means:
-- `systemd --user` scheduling is alive
-- but the notification chain may still be broken
+## What this is for (English)
 
-Do not stop at `timer active` / `service success`.
-You still need to verify:
-- pending owner report creation
-- sent archive movement
+Use this bundle to:
+
+- deploy watchdog-b on a new OpenClaw host (via `systemd --user timer`)
+- verify the owner-facing Discord delivery end-to-end
+- fix broken `owner_report_*` routing / path issues
+- refresh the live install under `~/.openclaw/workspace/scripts/watchdog-b/`
+
+### Included
+
+- Skill doc: `SKILL.md`
+- Scripts: `scripts/*.sh`, `scripts/*.py`, `scripts/watchdog-b.env.example`
+- systemd user units: `scripts/openclaw-watchdog-b.service`, `scripts/openclaw-watchdog-b.timer`
+- References: `references/*.md`
+
+### Single source of config
+
+Config file:
+- `~/.config/openclaw/watchdog-b.env`
+
+Minimum required:
+
+```bash
+WATCHDOG_B_OWNER_REPORT_TARGET=channel:YOUR_DISCORD_CHANNEL_ID
+```
+
+Optional (only set if the agent id exists on the host):
+
+```bash
+WATCHDOG_B_MAIN_AGENT_ID=backend
+```
+
+If unset, stalled/idle main-agent nudge is skipped to avoid `Unknown agent id` failures.
+
+---
+
+## 驗收/證據標準 / Evidence Standard
+
+請把「成功」拆成三層，不要混為一談：
+
+- **transport accepted**：send API 回傳成功/有 message id
+- **channel-readable**：可以從 target channel 讀回
+- **human-confirmed**：Eric 確認在 Discord 看到
+
+最低 E2E 成功訊號（verify script 期待的）：
+
+- `~/.clawteam/owner-reports/pending/` 產生 pending
+- pending 進入 `~/.clawteam/owner-reports/sent/`
 - Discord send success / message id
-- readback or human-visible evidence if claiming visible delivery
+- artifacts 寫入 `state/watchdog-b-verify-e2e/<run-id>/`
 
-### 7. How do I know whether I should rerun install or just rerun verify?
+---
 
-Use this rule:
+## 已知故障排查 FAQ / Troubleshooting FAQ
 
-- rerun **install** when scripts / env example / units may be stale or incomplete
-- rerun **bootstrap** when you need host-readiness validation
-- rerun **verify** when install is already in place and you need fresh E2E evidence
+### Q1: `.../scripts/scripts/owner_report_producer.py` 找不到
+A: 代表路徑基準錯了。正確應該在 `.../scripts/watchdog-b/owner_report_producer.py`。
 
-Practical order:
+修正：
 
 ```bash
 ./scripts/install_watchdog_bundle.sh --install-env-example --force
 ./scripts/bootstrap_watchdog_bundle.sh
+```
+
+### Q2: `Unknown agent id "main"`
+A: 不要硬編碼 `main`。改用 `WATCHDOG_B_MAIN_AGENT_ID`（或不設讓它 skip）。
+
+### Q3: timer active 但 owner-facing 沒送到
+A: timer 只代表排程活著，不代表鏈路通。請跑：
+
+```bash
 cd ~/.openclaw/workspace/scripts/watchdog-b
 ./verify_watchdog_b_e2e.sh
 ```
 
-## Safety / cleanup rules
+並檢查 `pending/`→`sent/` 移動與 send 回傳。
 
-- 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
+## Safety / 清理規則
 
-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.
+- **不要刪** `~/.clawteam/owner-reports/sent/` 歷史（除非明確要求）
+- **不要刪** `state/watchdog-b/notify-state.json`（除非做 hard reset）
+
+---
+
+## Repo
+
+- https://gitea.cowbay.org/openclaw/watchdog-discord-route