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`
--- a/plugins/reporting-governance/README.md
+++ b/plugins/reporting-governance/README.md
@@ -1,17 +1,200 @@
 # Reporting Governance Plugin
-This package is the emerging package boundary for the reporting-governance mainline.
+> 中文在前，English below.  
 > This package is the current package home for the reporting-governance mainline.
-Current purpose:
+## 中文說明
- give the plugin a real package home
+### 這個 package 是做什麼的？
- publish capability descriptors as package artifacts
+
- fix boundaries between `core/`, `adapters/`, `storage/`, and reference implementations
+`@openclaw/plugin-reporting-governance` 的目標，是把「代理是否有按規則回報、是否在卡住時誠實升級、通知是否真的送達」這些治理要求，逐步整理成：
- prepare the next implementation round for evaluator / decision-runner extraction
+
- provide a minimal package-level policy evaluator and decision runner skeleton that can be verified in isolation
+- 可安裝的 package 邊界
- add one minimal package-owned deployment profile artifact / loader / binding contract slice that is executable in tests
+- 可驗證的 capability / profile / schema artifacts
- let profile artifacts drive one real orchestrator adapter entrypoint instead of staying test-only
+- 可執行的 adapter entrypoints
- add one minimal runtime-integrated slice wiring contract planning into real orchestrator execution
+- 可測試的 governance core slice
 目前最成熟、也最能直接展示價值的路徑，是 **OpenClaw watchdog reference chain**：
 ```text
 watchdog -> queue -> dispatcher -> bridge -> sender binding -> acked|blocked|pending_external_send
 ```
 白話講：
 這個 package 目前最擅長的是把「長任務太久沒回報」這種治理問題，轉成一條有事件、有 handoff、有 receipt、而且不會假裝成功的通知鏈。
 ### 目前誠實狀態
 #### 已經有、而且有測試支持的部分
 - package boundary 已建立：
  - `src/core/`
  - `src/adapters/`
  - `src/storage/`
  - `profiles/`
  - `capabilities/`
  - `schemas/`
 - 最小 runnable governance core 已存在：
  - `evaluatePolicyPack(...)`
  - `evaluatePolicies(...)`
  - `planDecisionExecution(...)`
  - `executeGovernanceContract(...)`
  - `executeRuntimeIntegratedGovernance(...)`
  - `runCompatibilityPreflight(...)`
 - OpenClaw watchdog reference composition 已可執行
 - package-owned deployment profile artifact 已存在且可 loader/validator 驗證
 - capability descriptor 已存在且與目前 reference runtime 對齊
 - package tarball / clean-consumer install / public exports smoke tests 已存在
 #### 還沒完成、不能誇大的部分
 - 版本仍是 `0.1.0-mainline`，屬於 **pre-1.0 surface-tightening phase**
 - 還不是完整通用的 reporting-governance framework
 - 還沒把所有治理行為都做成通用 inline enforcement
 - adapter 仍有一部分是對既有 repo scripts 的收斂與包裝
 - `src/` 裡有檔案，不代表那些路徑都是公開 API
 ### 現在最實用的驗證方式
 #### 1. 跑 smoke
 ```bash
 npm run smoke
 ```
 預期：
 - 成功輸出 JSON
 - `ok: true`
 - 會顯示 orchestrator 執行順序
 - 若 sender 未配置，結果應誠實停在 pending 類狀態
 #### 2. 跑測試
 ```bash
 npm test
 ```
 目前測試覆蓋重點包含：
 - package structure
 - descriptor / export boundary
 - policy evaluator / decision runner
 - compatibility preflight
 - profile artifact / profile generator
 - runtime-integrated slice
 - watchdog chain integration
 - orchestrator execution
 - packed consumer install smoke
 #### 3. 看目前最重要的 artifact / 文件
 - `capabilities/openclaw-watchdog-reference.json`
 - `profiles/strict-manager-mode.profile.json`
 - `src/reference/openclaw-watchdog-chain.md`
 ### 安裝 / 使用建議（依目前成熟度）
 #### 當作 package 開發與驗證目標
 在 repo root 或 package 目錄中：
 ```bash
 npm --prefix plugins/reporting-governance install
 npm --prefix plugins/reporting-governance test
 npm --prefix plugins/reporting-governance run smoke
 ```
 #### 當作程式依賴使用
 優先只依賴：
 - root export：`@openclaw/plugin-reporting-governance`
 - 已宣告的 adapter subpaths：
  - `@openclaw/plugin-reporting-governance/adapters`
  - `@openclaw/plugin-reporting-governance/adapters/watchdog`
  - `@openclaw/plugin-reporting-governance/adapters/dispatcher`
  - `@openclaw/plugin-reporting-governance/adapters/bridge-supervisor`
  - `@openclaw/plugin-reporting-governance/adapters/sender-binding`
  - `@openclaw/plugin-reporting-governance/adapters/orchestrator`
 不要把 repo 內 `src/...` 深層檔案路徑當成穩定公開 API。
 #### 當作 runtime slice 使用
 目前最合適的心態是：
 - 把它當成 **OpenClaw reference runtime composition**
 - 把它當成 **可驗證的 MVP package slice**
 - 不要把它當成「所有治理功能都已完成的 production product」
 ---
 ## English
 ### What is this package for?
 `@openclaw/plugin-reporting-governance` is turning reporting-governance requirements into:
 - a real package boundary,
 - package-owned schemas / capabilities / deployment profiles,
 - executable adapter entrypoints,
 - and a testable governance core slice.
 The most concrete implemented path today is the **OpenClaw watchdog reference chain**:
 ```text
 watchdog -> queue -> dispatcher -> bridge -> sender binding -> acked|blocked|pending_external_send
 ```
 In plain language: this package currently focuses on making overdue-reporting recovery auditable, testable, and honest about delivery truth.
 ### Honest status
 What is already real and tested:
 - package boundary under `plugins/reporting-governance/`
 - minimal runnable governance core
 - executable OpenClaw watchdog reference composition
 - package-owned deployment profile artifact
 - capability descriptor aligned to the current reference runtime
 - tarball/install/export smoke coverage
 What is not complete yet:
 - still **pre-1.0** (`0.1.0-mainline`)
 - not yet a fully generalized reporting-governance framework
 - not all governance behaviors are wired into general inline enforcement
 - some adapters still wrap existing repo scripts during MVP extraction
 - files under `src/` are not automatically public API
 ### Quick verification
 Run smoke:
 ```bash
 npm run smoke
 ```
 Run tests:
 ```bash
 npm test
 ```
 ### Practical install/use guidance
 Use public exports only:
 - `@openclaw/plugin-reporting-governance`
 - `@openclaw/plugin-reporting-governance/adapters`
 - `@openclaw/plugin-reporting-governance/adapters/watchdog`
 - `@openclaw/plugin-reporting-governance/adapters/dispatcher`
 - `@openclaw/plugin-reporting-governance/adapters/bridge-supervisor`
 - `@openclaw/plugin-reporting-governance/adapters/sender-binding`
 - `@openclaw/plugin-reporting-governance/adapters/orchestrator`
 Do not treat deep `src/...` imports as stable API.
 ---
 ## Package skeleton
@@ -257,35 +440,5 @@ This package still does **not** claim full implementation of:
 - production decision persistence
 - complete rewrite / placeholder / review / status-downgrade adapter execution
 - non-watchdog full runtime governance interception
-
+- full audit-export packaging
-It now provides the first package-mainline evaluator / decision-runner core, a compatibility-envelope boundary, a minimal package profile artifact/binding slice, and one profile-driven orchestrator path, but the remaining enforcement surface is still intentionally honest about adapter gaps.
+- production-ready installer flow
 ## Package-first smoke
 Minimal package-local smoke path:
 ```bash
 cd plugins/reporting-governance
 npm test
 npm run smoke
 # or after package install/link
 reporting-governance-package-smoke --compact
 ```
 Repeatable packed-consumer install smoke is now also covered by package test:
 ```bash
 cd plugins/reporting-governance
 npm pack
 node --test test/packed-consumer-install.smoke.test.mjs
 ```
 That path verifies a clean temp consumer can `npm install <tarball>` and then use only declared public surfaces:
 - package root export: `@openclaw/plugin-reporting-governance`
 - exported subpath: `@openclaw/plugin-reporting-governance/adapters/orchestrator`
 - package bin: `reporting-governance-package-smoke`
 This smoke path uses package-local `profiles-src/`, `schemas/`, and `scripts` only.
 It writes temp runtime artifacts under a caller-provided or temp workspace and verifies the dry-run orchestrator path end to end.