# Owner Reporting System

這是一套全域性的 owner-facing 主動回報流程，不屬於某一個特定專案。

它的目的，是把長時間、多步驟、不可漏回報的工作，整理成一條可觀測、可驗證、失敗不假成功的通知鏈路。

## Core flow

General queue drain path:
`producer -> pending/*.md -> watchdog -> driver -> Discord -> sent/*.md`

Watchdog-b single-shot direct path:
`producer -> pending/*.md -> driver -> Discord channel:1480577550445969541 -> sent/*.md`

元件：
- `scripts/owner_report_producer.py`
- `scripts/owner_report_consumer.py`
- `scripts/owner_report_driver.py`
- `scripts/owner_report_watchdog.py`
- `scripts/run_owner_report_watchdog.sh`
- `OWNER_REPORT_OPERATOR_MANUAL.md`

## Scope

適用於：
- ClawTeam / subagent / 背景流程 checkpoint
- 多步驟技術任務
- 明確要求不要漏回報的交辦
- 需要 oldest-first / success-only archive / stop-on-failure 語義的通知鏈路

不適用於：
- 單次短問答
- 不需要主動通知的小修改
- 一次即可回完的低風險任務

## Queue paths

- pending: `~/.clawteam/owner-reports/pending/`
- sent: `~/.clawteam/owner-reports/sent/`

## Local integration

本機目前由 user crontab 每分鐘執行一次 watchdog wrapper：

- wrapper: `/home/chchang/.openclaw/workspace/owner-reporting-system/scripts/run_owner_report_watchdog.sh`
- log: `/opt/workspace_auditing_report/logs/owner_report_watchdog_cron.out`
- default target: 預設 `OWNER_REPORT_CHANNEL=discord` + `OWNER_REPORT_TARGET=channel:1480577550445969541`
- backlog per run: 預設 `OWNER_REPORT_MAX_COUNT=5`

另外，watchdog-b owner-facing 單發驗證現在可直接走 `owner_report_driver.py`，不必依賴 wrapper watchdog 的目標/顯示語義判斷。

## Common commands

```bash
# produce one checkpoint report
cd /home/chchang/.openclaw/workspace/owner-reporting-system/scripts
uv run python owner_report_producer.py \
  --team general-task \
  --worker alice \
  --task-id example-task \
  --progress 50% \
  --done '第一階段完成' \
  --next '等待第二階段結果' \
  --status normal \
  --source manual-checkpoint

# dry-run watchdog
/home/chchang/.openclaw/workspace/owner-reporting-system/scripts/run_owner_report_watchdog.sh --dry-run

# process backlog immediately
OWNER_REPORT_MAX_COUNT=20 \
/home/chchang/.openclaw/workspace/owner-reporting-system/scripts/run_owner_report_watchdog.sh

# temporarily override destination
OWNER_REPORT_CHANNEL=telegram \
OWNER_REPORT_TARGET=864811879 \
/home/chchang/.openclaw/workspace/owner-reporting-system/scripts/run_owner_report_watchdog.sh --dry-run
```

更完整的操作、debug 與 failure semantics 請看 `OWNER_REPORT_OPERATOR_MANUAL.md`。