openclaw/reporting-governance-plugin

Fork 0

Files

Eve 241e586c27 docs: clarify reporting governance plugin landing pages

2026-05-11 09:27:33 +08:00

9.4 KiB

Raw Permalink Blame History

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？

目前狀態：哪些真的可用、哪些還沒完整？

已經可用 / 有測試證據

Package skeleton 已存在
- 位置：plugins/reporting-governance/
- 已有 core/, adapters/, storage/, profiles/, capabilities/, schemas/, scripts/
最小 governance core 已可執行
- policy evaluator
- decision runner
- compatibility preflight
- runtime-integrated execution slice
Watchdog reference chain 已可執行且有整合測試
- 會產生 event / queue / spool / receipt
- 不會把「尚未證明送達」假裝成 acked
Package-owned profile / capability artifacts 已落地
- plugins/reporting-governance/profiles/strict-manager-mode.profile.json
- plugins/reporting-governance/capabilities/openclaw-watchdog-reference.json
打包 / 安裝 smoke test 已存在
- 代表目前 package 至少能以受測方式被打包、安裝、再透過公開 exports/bin 驗證

還沒完成 / 不能誇大宣稱的部分

還不是 1.0 穩定 API
- 版本目前是 0.1.0-mainline
- package surface 仍在收斂
- 不應依賴 repo 內部 src/ 深層 private 路徑
還不是完整通用治理框架
- 現在最成熟的是 watchdog-driven notify path
- 還沒把所有 inline governance decision 都接成完整 runtime enforcement
adapter 仍有過渡成分
- 一部分 adapter 目前仍是 package 對既有 repo scripts 的包裝/收斂
- 這是 MVP 過程中的刻意設計，不是假裝全部已抽乾淨
storage / audit export 仍未全面完成
- 已有最小 decision/profile artifact slice
- 但還不是完整 event/evidence/decision/audit framework

如何驗證它目前真的有在工作？

最實用的驗證方式有三種。

1) 跑 package smoke

npm --prefix plugins/reporting-governance run smoke

目前預期：

指令成功
會輸出 JSON
ok: true
orchestrator.ok: true
在 sender 未完整配置時，通常會誠實停在 pending / pending_external_send 類狀態，而不是假裝已送達

2) 跑 package tests

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

目前適合怎麼使用？

如果你是來理解這個專案

建議閱讀順序：

先看這份 README.md
再看 plugins/reporting-governance/README.md
想看白話版現況，讀：
- docs/roadmaps/reporting-governance-plugin-status-plain-language.md
想看 watchdog 參考鏈，讀：
- plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md

如果你想驗證 package 現況

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 結構重點

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:

npm --prefix plugins/reporting-governance run smoke

Run a focused package verification set:

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:

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

9.4 KiB Raw Permalink Blame History Unescape Escape