docs: clarify reporting governance plugin landing pages

2026-05-11 09:27:33 +08:00
parent bdd33bd42d
commit 241e586c27
2 changed files with 466 additions and 42 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,271 @@
+# Reporting Governance Plugin / 回報治理外掛
+
+> 讓「代理有沒有按規則回報、卡住時有沒有誠實升級、通知到底有沒有真的送出去」變成**可驗證的流程與 artifact**，而不是只靠口頭承諾。
+
+## 中文說明
+
+### 這個 repo 在做什麼？
+
+這個 repo 正在把一套 **agent reporting governance** 規則，整理成可安裝、可測試、可留痕跡的 OpenClaw plugin。
+
+目前最具體的能力是：
+
+- 定義 governance 的事件 / 證據 / 決策 / capability / deployment profile 契約
+- 提供一個正在成形的 package：`plugins/reporting-governance/`
+- 提供一條已可執行的 **watchdog auto-notify reference chain**
+  - `watchdog -> queue -> dispatcher -> bridge -> sender binding -> receipt`
+- 誠實區分通知狀態，例如：
+  - `dispatched`
+  - `pending_external_send`
+  - `acked`
+  - `blocked`
+
+白話說：它不是通用聊天 plugin，而是要處理這類問題：
+
+- long task 太久沒回報時，能不能自動留下證據並產生通知義務？
+- 通知在多段 handoff 之後，能不能還是看得出「真的送到了」還是「其實還沒」？
+- policy / profile / capability 能不能從文件變成 package 自己擁有的 contract？
+
+### 目前狀態：哪些真的可用、哪些還沒完整？
+
+#### 已經可用 / 有測試證據
+
+1. **Package skeleton 已存在**
+   - 位置：`plugins/reporting-governance/`
+   - 已有 `core/`, `adapters/`, `storage/`, `profiles/`, `capabilities/`, `schemas/`, `scripts/`
+
+2. **最小 governance core 已可執行**
+   - policy evaluator
+   - decision runner
+   - compatibility preflight
+   - runtime-integrated execution slice
+
+3. **Watchdog reference chain 已可執行且有整合測試**
+   - 會產生 event / queue / spool / receipt
+   - 不會把「尚未證明送達」假裝成 `acked`
+
+4. **Package-owned profile / capability artifacts 已落地**
+   - `plugins/reporting-governance/profiles/strict-manager-mode.profile.json`
+   - `plugins/reporting-governance/capabilities/openclaw-watchdog-reference.json`
+
+5. **打包 / 安裝 smoke test 已存在**
+   - 代表目前 package 至少能以受測方式被打包、安裝、再透過公開 exports/bin 驗證
+
+#### 還沒完成 / 不能誇大宣稱的部分
+
+1. **還不是 1.0 穩定 API**
+   - 版本目前是 `0.1.0-mainline`
+   - package surface 仍在收斂
+   - 不應依賴 repo 內部 `src/` 深層 private 路徑
+
+2. **還不是完整通用治理框架**
+   - 現在最成熟的是 watchdog-driven notify path
+   - 還沒把所有 inline governance decision 都接成完整 runtime enforcement
+
+3. **adapter 仍有過渡成分**
+   - 一部分 adapter 目前仍是 package 對既有 repo scripts 的包裝/收斂
+   - 這是 MVP 過程中的刻意設計，不是假裝全部已抽乾淨
+
+4. **storage / audit export 仍未全面完成**
+   - 已有最小 decision/profile artifact slice
+   - 但還不是完整 event/evidence/decision/audit framework
+
+### 如何驗證它目前真的有在工作？
+
+最實用的驗證方式有三種。
+
+#### 1) 跑 package smoke
+
+```bash
+npm --prefix plugins/reporting-governance run smoke
+```
+
+目前預期：
+- 指令成功
+- 會輸出 JSON
+- `ok: true`
+- `orchestrator.ok: true`
+- 在 sender 未完整配置時，通常會誠實停在 `pending` / `pending_external_send` 類狀態，而不是假裝已送達
+
+#### 2) 跑 package tests
+
+```bash
+node --test \
+  plugins/reporting-governance/test/package-structure.test.mjs \
+  plugins/reporting-governance/test/watchdog-chain.integration.test.mjs \
+  plugins/reporting-governance/test/runtime-integrated.integration.test.mjs \
+  plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs
+```
+
+這組測試重點驗證：
+- package 結構存在
+- tarball 可安裝到乾淨 consumer
+- 公開 exports / bin 可用
+- watchdog chain truth model 正常
+- mixed terminal outcomes 不會被錯誤提升成 `acked`
+
+#### 3) 直接看參考 artifact / profile / capability
+
+可先從這幾個檔案讀起：
+
+- `plugins/reporting-governance/README.md`
+- `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
+- `plugins/reporting-governance/capabilities/openclaw-watchdog-reference.json`
+- `plugins/reporting-governance/profiles/strict-manager-mode.profile.json`
+- `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`
+
+### 目前適合怎麼使用？
+
+#### 如果你是來理解這個專案
+
+建議閱讀順序：
+
+1. 先看這份 `README.md`
+2. 再看 `plugins/reporting-governance/README.md`
+3. 想看白話版現況，讀：
+   - `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`
+4. 想看 watchdog 參考鏈，讀：
+   - `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
+
+#### 如果你想驗證 package 現況
+
+```bash
+npm --prefix plugins/reporting-governance install
+npm --prefix plugins/reporting-governance test
+npm --prefix plugins/reporting-governance run smoke
+```
+
+#### 如果你想把它當成「OpenClaw reference runtime slice」來試
+
+目前最合適的理解方式是：
+
+- 它已經提供一個 **reference runtime composition**
+- 不是完整 production installer
+- 也不是所有治理規則都已接上 live runtime
+- 最成熟的入口是 watchdog/orchestrator 這條鏈
+
+### Repo 結構重點
+
+```text
+plugins/reporting-governance/   # 主 package
+  capabilities/                # capability descriptors
+  profiles/                    # generated deployment profile artifacts
+  profiles-src/                # profile source
+  schemas/                     # package-owned schemas
+  scripts/                     # executable entrypoints / smoke helpers
+  src/
+    core/                      # policy/decision/runtime-integrated core slice
+    adapters/                  # runtime adapter boundary
+    storage/                   # artifact/store contracts
+    reference/                 # reference runtime docs
+  test/                        # package tests
+
+docs/specs/                    # mainline specs
+docs/roadmaps/                 # status + roadmap docs
+scripts/                       # repo-level compatibility / fixture scripts
+state/                         # runtime artifact examples / local state
+```
+
+### 誠實的專案定位
+
+最準確的說法是：
+
+- **不是只有 spec**
+- **也還不是完整成熟產品**
+- **目前是一個已有真實可測 slice 的 plugin package 主線**
+
+也就是：
+
+> 已經能證明某些治理邊界真的成立，尤其是 watchdog 通知鏈與 truthful delivery state；但整體仍在往更完整、可攜、可安裝的 plugin 收斂中。
+
+---
+
+## English
+
+### What does this repository do?
+
+This repository is turning a set of **agent reporting governance** rules into an installable, testable, artifact-backed OpenClaw plugin.
+
+Today, the most concrete slice is a **watchdog auto-notify reference chain** that can:
+
+- detect overdue reporting situations,
+- emit canonical events,
+- create queue/spool/receipt artifacts,
+- and preserve truthful delivery states instead of claiming success too early.
+
+In plain English: this project is about making agent reporting obligations auditable and automatable, especially around “silent long task” failures and notification handoff truth.
+
+### Honest current status
+
+What works now:
+
+- a real package boundary under `plugins/reporting-governance/`
+- package-owned schemas, capability descriptors, and deployment profile artifacts
+- a minimal runnable governance core
+- a tested OpenClaw watchdog reference composition
+- packaging/install smoke coverage via public exports and bin entrypoints
+
+What is not complete yet:
+
+- this is still **pre-1.0** (`0.1.0-mainline`)
+- the API surface is still tightening
+- not all governance decisions are wired into a generalized runtime enforcement layer
+- some adapters still wrap existing repo scripts as part of MVP extraction
+- this is not yet a finished production-wide governance framework
+
+### How to verify the current state
+
+Run the package smoke check:
+
+```bash
+npm --prefix plugins/reporting-governance run smoke
+```
+
+Run a focused package verification set:
+
+```bash
+node --test \
+  plugins/reporting-governance/test/package-structure.test.mjs \
+  plugins/reporting-governance/test/watchdog-chain.integration.test.mjs \
+  plugins/reporting-governance/test/runtime-integrated.integration.test.mjs \
+  plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs
+```
+
+Or run the package test suite:
+
+```bash
+npm --prefix plugins/reporting-governance test
+```
+
+### Practical usage guidance
+
+Use the repository today as:
+
+- a **reference implementation** for reporting-governance package boundaries,
+- a **tested watchdog notification chain** for OpenClaw,
+- and a **working MVP package slice** for further extraction.
+
+Do **not** treat it yet as:
+
+- a stable 1.0 public API,
+- a complete governance framework for every runtime,
+- or a finished production installer.
+
+### Start here
+
+- Repo overview: `README.md`
+- Package details: `plugins/reporting-governance/README.md`
+- Plain-language status: `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`
+- Reference chain: `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
+
+---
+
+## See also
+
+- `plugins/reporting-governance/README.md`
+- `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`
+- `docs/roadmaps/reporting-governance-plugin-mvp.md`
+- `docs/specs/reporting-governance-capability-descriptor.md`
+- `docs/specs/reporting-governance-deployment-model.md`
+- `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
+- `CODER_WATCHDOG_REPORT.md`