From 241e586c273ad3a576ad69bd4f88b65d61a82e34 Mon Sep 17 00:00:00 2001 From: Eve Date: Mon, 11 May 2026 09:27:33 +0800 Subject: [PATCH] docs: clarify reporting governance plugin landing pages --- README.md | 271 +++++++++++++++++++++++++ plugins/reporting-governance/README.md | 237 +++++++++++++++++---- 2 files changed, 466 insertions(+), 42 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2d99473 --- /dev/null +++ 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` diff --git a/plugins/reporting-governance/README.md b/plugins/reporting-governance/README.md index 4a28ff5..4f5f336 100644 --- 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 -- publish capability descriptors as package artifacts -- fix boundaries between `core/`, `adapters/`, `storage/`, and reference implementations -- 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 -- add one minimal package-owned deployment profile artifact / loader / binding contract slice that is executable in tests -- let profile artifacts drive one real orchestrator adapter entrypoint instead of staying test-only -- add one minimal runtime-integrated slice wiring contract planning into real orchestrator execution +### 這個 package 是做什麼的？ + +`@openclaw/plugin-reporting-governance` 的目標，是把「代理是否有按規則回報、是否在卡住時誠實升級、通知是否真的送達」這些治理要求，逐步整理成： + +- 可安裝的 package 邊界 +- 可驗證的 capability / profile / schema artifacts +- 可執行的 adapter entrypoints +- 可測試的 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 - -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. - - -## 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 ` 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. +- full audit-export packaging +- production-ready installer flow