Add plain-language status doc and minimal decision store contract
This commit is contained in:
Eve
@@ -0,0 +1,231 @@
|
||||
# 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。**
|
||||
|
||||
這樣後面每往前一步，才比較不會變成另一個大而空的治理殼。
|
||||
Reference in New Issue
Block a user