openclaw/reporting-governance-plugin

Fork 0

Files

Eve 30cb206438 test: harden decision record storage slice

2026-05-08 13:21:43 +08:00

6.9 KiB

Raw Blame History

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，很容易出現兩種壞事：

做很大，但沒有任何一塊真的可驗證
名字切漂亮，實際上還是靠舊 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。

這樣後面每往前一步，才比較不會變成另一個大而空的治理殼。

6.9 KiB Raw Blame History Unescape Escape