docs: clarify reporting governance plugin landing pages
This commit is contained in:
Eve
@@ -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 <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.
|
||||
- full audit-export packaging
|
||||
- production-ready installer flow
|
||||
|
||||
Reference in New Issue
Block a user