232 lines
6.9 KiB
Markdown
232 lines
6.9 KiB
Markdown
# Reporting Governance Plugin：現在做到哪、為什麼這樣切、還沒做到什麼
|
||
|
||
這份文件是給**不想先看程式碼的人**看的。
|
||
|
||
一句話先講白：
|
||
**這個 plugin 在做的事，是把「代理有沒有老實回報、有沒有卡住不講、有沒有把該交接的事真的交出去」這些規則，從口頭要求，慢慢做成可驗證的程式與紀錄。**
|
||
|
||
---
|
||
|
||
## 1) 目前已經做了什麼
|
||
|
||
現在不是只有概念，而是已經有一條**可以跑、會留下痕跡、能被測試證明**的最小鏈路。
|
||
|
||
### 已經有的骨架
|
||
|
||
`plugins/reporting-governance/` 這個 package 已經拉出基本邊界：
|
||
|
||
- `core/`：放規則判斷與決策邏輯
|
||
- `adapters/`：接現有 runtime / script
|
||
- `storage/`：放可保存的 artifact 與 store contract
|
||
- `profiles/`：放部署設定 artifact
|
||
- `capabilities/`：放能力描述
|
||
|
||
這很重要，因為它代表這件事開始不是散在 repo 各角落，而是有自己的 package 家。
|
||
|
||
### 已經有的決策能力
|
||
|
||
目前已經有最小可跑的：
|
||
|
||
- policy evaluator：根據事件/證據判斷要不要出手
|
||
- decision runner：把判斷結果轉成可執行意圖
|
||
- compatibility preflight：先檢查輸入/相容性，不對就 fail closed
|
||
|
||
白話講，就是：
|
||
**系統已經不只是「看到問題」，而是能把問題翻成明確決策，例如要不要強制 checkpoint、要不要擋下某動作。**
|
||
|
||
### 已經有的 OpenClaw 參考鏈
|
||
|
||
目前 repo 裡最真實的一條鏈，是 watchdog 逾時告警路徑：
|
||
|
||
`watchdog -> queue -> dispatcher -> bridge -> sender -> receipt`
|
||
|
||
這條鏈已經能做到：
|
||
|
||
- 產生 canonical event
|
||
- 進 queue / spool
|
||
- 經過 bridge / sender binding
|
||
- 留下 receipt
|
||
- 在不能真的送出的情況下，誠實標示成 `pending_external_send`，不是假裝已送達
|
||
|
||
這件事的價值很實際：
|
||
**它已經能防止「其實沒送到，卻說送到了」這種黑箱假成功。**
|
||
|
||
### 已經有的 package-owned profile artifact
|
||
|
||
目前已經有一個 package 自己擁有的部署設定 artifact：
|
||
|
||
- `plugins/reporting-governance/profiles/strict-manager-mode.profile.json`
|
||
|
||
而且不是擺著好看，已經有：
|
||
|
||
- loader
|
||
- validator
|
||
- binding contract projector
|
||
- 測試
|
||
|
||
白話講：
|
||
**這個 plugin 已經開始自己宣告：我依賴哪些腳本、哪些 artifact 目錄、哪些 runtime 邊界。**
|
||
|
||
不是再靠「大家心裡知道」或 README 暗示。
|
||
|
||
### 這一輪新補的最小 storage contract slice
|
||
|
||
這輪再往前推了一小刀：
|
||
|
||
- 定義 `DecisionRecordArtifact`
|
||
- 定義 decision artifact validator / filename contract
|
||
- 落一個最小 file-based decision store
|
||
- 用測試證明 decision 可以被寫入、讀回、驗證，而且不能亂寫出 repo root
|
||
|
||
白話講：
|
||
**決策紀錄開始有 package 自己的保存格式，而不是每次臨時拼 JSON。**
|
||
|
||
---
|
||
|
||
## 2) 為什麼要這樣設計 / 為什麼要這樣切 slices
|
||
|
||
### 原因一：這題太大，不能一口氣抽乾淨
|
||
|
||
Reporting governance 牽到的東西很多：
|
||
|
||
- 事件模型
|
||
- 證據模型
|
||
- 決策模型
|
||
- queue / spool / receipt
|
||
- runtime adapter
|
||
- 真正外送通知
|
||
- 未來的 audit/export
|
||
|
||
如果一次硬做成完整 framework，很容易出現兩種壞事：
|
||
|
||
1. 做很大，但沒有任何一塊真的可驗證
|
||
2. 名字切漂亮，實際上還是靠舊 repo 腳本在撐
|
||
|
||
所以現在的主線策略是：
|
||
**每次只切一塊最小、能被測試證明、而且不會假裝完成的 slice。**
|
||
|
||
### 原因二：先把「誠實邊界」做出來
|
||
|
||
這個 plugin 的核心不是炫技，而是**不能說謊**。
|
||
|
||
所以設計上優先做的是：
|
||
|
||
- capability descriptor：先講清楚 runtime 有什麼能力
|
||
- compatibility preflight：能力不夠就 fail，不硬裝能做
|
||
- truthful receipt states：沒送到就是沒送到，不能灌水成 acked
|
||
- package-owned artifacts：讓輸入/輸出有固定契約
|
||
|
||
這就是為什麼現在會先看到 profile artifact、receipt truth model、decision record 這些東西，而不是先衝一個很大的「全能治理引擎」。
|
||
|
||
### 原因三：把 package 真正養成自己的邊界
|
||
|
||
如果 `core`、`adapters`、`storage` 不分開，未來就會很難回答：
|
||
|
||
- 哪些是可重用的治理邏輯？
|
||
- 哪些只是 OpenClaw 這個 runtime 的接線？
|
||
- 哪些是資料保存契約？
|
||
|
||
現在這樣切，是為了讓未來能逐步達到：
|
||
|
||
- `core` 不依賴特定 runtime
|
||
- `adapters` 負責接現場
|
||
- `storage` 擁有 artifact contract
|
||
|
||
這樣才有機會從「repo 內一套特殊腳本」長成「可攜的 plugin」。
|
||
|
||
---
|
||
|
||
## 3) 這些工作帶來什麼實際好處
|
||
|
||
### 好處一：比較不容易再發生黑箱失聯
|
||
|
||
watchdog / queue / receipt 這條鏈已經讓「任務太久沒回報」有一條比較正式的處理路。
|
||
|
||
不是再靠人記得盯。
|
||
|
||
### 好處二：可以區分「真的做到」和「只是說做到」
|
||
|
||
receipt truth model 的意義很直接：
|
||
|
||
- 有證據送出，才叫 acked
|
||
- 沒證據，就停在 pending / blocked / dispatched 等誠實狀態
|
||
|
||
這會直接降低假完成、假外送、假交接。
|
||
|
||
### 好處三：未來比較能換 runtime，不用整組重寫
|
||
|
||
先把 core / adapter / storage 切開，未來若不是 OpenClaw，也比較有機會重用核心規則。
|
||
|
||
### 好處四：決策開始可保存、可追查
|
||
|
||
這輪 decision store slice 的實際價值是：
|
||
|
||
- 決策不只存在記憶體
|
||
- 可落成 artifact
|
||
- 檔名與內容有固定 contract
|
||
- 可追 policy、decision、receipt、source event
|
||
|
||
這對 audit、debug、回放都很關鍵。
|
||
|
||
---
|
||
|
||
## 4) 目前明確還沒做到什麼
|
||
|
||
這裡要講老實話。
|
||
|
||
### 還沒做到完整 storage framework
|
||
|
||
現在只有先落一個最小 decision store slice。
|
||
|
||
**還沒有**完整抽成：
|
||
|
||
- event store
|
||
- evidence store
|
||
- queue store
|
||
- spool store
|
||
- receipt store
|
||
- 統一 manifest / audit export
|
||
|
||
### 還沒做到所有決策都能真的執行
|
||
|
||
目前 package `core` 已經能做判斷與規劃，
|
||
但很多實際 side effects 還是 adapter / runtime 責任。
|
||
|
||
例如：
|
||
|
||
- 真正 inline 攔截所有訊息/狀態變更
|
||
- 完整 rewrite / placeholder / review / downgrade_status 執行
|
||
- 非 watchdog 路徑的全面治理攔截
|
||
|
||
### 還沒完全脫離 repo 既有 scripts
|
||
|
||
現在 adapter 仍大量包既有 scripts。
|
||
這代表 package 邊界雖然成形，但 runtime 實作還在過渡期。
|
||
|
||
### 還沒形成完整對外穩定 API
|
||
|
||
現在還是 `0.1.0-mainline`，屬於 pre-1.0。
|
||
|
||
意思是：
|
||
|
||
- package surface 還在收斂
|
||
- 深層 `src/` import 不算穩定公開 API
|
||
- 現在能跑，不代表介面已經定版
|
||
|
||
---
|
||
|
||
## 現在最準確的定位
|
||
|
||
如果要一句話描述現在狀態：
|
||
|
||
**它已經不是只有規格文件；已經有最小可跑、可測、會留痕跡的治理鏈。**
|
||
|
||
但同時：
|
||
|
||
**它也還不是完整成熟的 reporting-governance framework。**
|
||
|
||
現在主線是在做一件對的事：
|
||
**把最重要、最容易說謊、最需要證據的那幾刀，先變成 package-owned contracts。**
|
||
|
||
這樣後面每往前一步，才比較不會變成另一個大而空的治理殼。
|