272 lines
9.4 KiB
Markdown
272 lines
9.4 KiB
Markdown
# 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`
|