# Flight Recorder (飛行記錄器)

*以執行為單位、雜湊連結的記錄，包括這次執行讀過什麼。*

> **Flight Recorder（飛行記錄器）** 是以執行為單位、只追加、雜湊連結的記錄：這次執行讀了什麼（讀清單）、寫了什麼、被允許或拒絕了什麼、誰批准了什麼。它存放在資料旁邊，用來回答「這個改動可能受到了什麼影響」。

**AN-03** · 符合性等級: L1 Authority · 概念組: 工作

## 要解決的問題

事故復盤時，日誌散落各處；「讀取」與隨後的動作之間沒有關聯；日誌可以被同一位管理員，甚至同一個智能體修改。

更根本的是：當一次合併或一條記憶被懷疑受到污染時，沒有辦法回答「那次執行讀過什麼」。

## 工作方式

- **兩類內容。** *事件*逐條記錄：提交、租約簽發與撤銷、閘門請求與決定、策略拒絕、派生、遺忘。*讀清單*（read manifest）按執行聚合：讀過哪些路徑@提交、哪些範圍、內容雜湊；不記每一次讀取呼叫，也不記內容。
- **每個提交帶來源後設資料：** `principal`、`on_behalf_of`、`run`、`lease`、`purpose` 和讀清單引用。
- **雜湊鏈**（按天），可選簽名與外部錨定（第二個節點、帶物件鎖的桶）。目標是「**篡改可以被發現**」，而不是「無法篡改」。
- **匯出：** OpenTelemetry GenAI spans、JSON Lines，或接入 SIEM。
- **隱私：** 預設只記後設資料，不記內容；記錄的保留與內容的刪除互相獨立；記錄本身受存取控制。
- **`explain(commit)`：** 返回這次提交對應的執行、租約、閘門決定、讀清單與輸入。
- **先記錄，後生效：** 有後果的操作必須先寫入意圖記錄。

## 從小處開始

- 一張追加寫的 SQLite 表，加上每日雜湊。
- 在每個提交資訊裡寫 `Run:`、`Lease:` 之類的 Git trailer。
- 匯出 OpenTelemetry spans，接入你已有的觀測棧。

## 介面草圖

僅作示意。欄位名在規範 v0.3 之前可能調整。

*record.json*

```json
{
  "seq": 18211,
  "time": "2026-11-12T09:14:22Z",
  "kind": "commit",
  "run": "run_91ab",
  "principal": "agt_cleo",
  "on_behalf_of": "usr_wei",
  "lease": "lse_7Qk3",
  "purpose": "Draft the Q4 release notes",
  "subject": { "path": "/shared/launch/notes.md", "commit": "91ce3a7" },
  "read_manifest": "rm_5d2e",
  "decision": { "effect": "allow", "rule": "r-17" },
  "taint": { "external": true, "sensitivity": "private" },
  "prev_hash": "sha256:b3a0..."
}
```

## 規範的要求

- 有後果的操作**必須**在生效之前寫入意圖記錄；寫入失敗時，操作**必須**失敗。
- 每次執行**必須**有讀清單，記錄讀過的路徑、提交與範圍（不含內容）。
- 記錄**必須**雜湊連結，並且**必須**能用公開的命令校驗。
- `explain(commit)` **必須**返回執行、租約、閘門決定與讀清單引用。
- 記錄的保留**必須**獨立於內容的刪除。

## 借鑑與區別

下面這些都是現成的零件。**真正新的部分是讀清單：** 把「讀」變成一個可追溯的輸入集合，使「被污染的合併」和「被投毒的記憶」可以復盤。

- [OpenTelemetry GenAI conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
- [Certificate Transparency](https://certificate.transparency.dev)
- [Sigstore Rekor](https://docs.sigstore.dev/logging/overview/)
- [Git trailers](https://git-scm.com/docs/git-interpret-trailers)

## 坦誠的侷限

- 沒有外部錨定時，擁有 root 的管理員仍然可以毀掉日誌。
- 記錄本身含有敏感的後設資料，必須受控。
- 讀清單的粒度是儲存成本與可追溯性之間的折中。

## 開放問題

- 高吞吐下讀清單的儲存成本如何控制？
- 跨節點的記錄如何合併與校驗？

## 常見問題

### 它會記錄智能體讀到的內容嗎？

預設不會。記錄裡只有路徑、提交、範圍與內容雜湊，足以指回原始資料，又不會把敏感內容複製進日誌。內容仍然在 Store 裡，受租約與標籤保護。

### 「防篡改」是什麼意思？

我們只承諾**篡改可以被發現**：記錄是雜湊連結的，改一條就會讓鏈校驗失敗；配合外部錨定（第二個節點或帶物件鎖的桶），可以抵禦擁有 root 的管理員。沒有錨定時，管理員仍可整體銷燬日誌。

### 為什麼要記「讀」？

因為風險常常來自讀取：一次讀了網頁的工作階段，隨後寫進的筆記就可能被污染。讀清單讓你事後能回答「這個改動受到了什麼影響」。

## 相關概念

- [Capability Lease (能力租約)](https://agentnas.com/zh-tw/concepts/capability-lease/): 發給一次執行的、有期限與預算的窄域授權；子租約只能更窄。
- [Trust Labels (信任標籤)](https://agentnas.com/zh-tw/concepts/trust-labels/): 來源與敏感度兩個小標籤，加上工作階段污點，強制執行 Rule of Two。
- [Cascade Forget (級聯遺忘)](https://agentnas.com/zh-tw/concepts/cascade-forget/): 沿血緣刪除派生物，按保留類處理歷史，並如實報告做不到的部分。

---

標準網址: https://agentnas.com/zh-tw/concepts/flight-recorder/
更新於: 2026-11-11 · 規範草案 v0.2 · CC BY 4.0