> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作階段狀態感知

當多個工作階段處理同一個問題時——例如管理者將工作委派給子工作階段、使用者直接進入工作工作階段，或兩個代理程式透過 [`sessions_send`](/zh-TW/concepts/session-tool) 協調——每個工作階段都會對其他工作階段形成假設。其他參與者一介入，這些假設便立即過時。工作階段狀態感知是一套用來偵測介入、僅通知受影響工作階段一次，並讓它能在採取行動前以低成本掌握最新狀況的機制。

以下三個部分會協同運作：

1. **持久訊號日誌**會記錄每個工作階段的特定狀態變更。
2. **監看者**會保存各目標的游標，並接收一則合併後的狀態過時通知。
3. **協調同步**會透過 `session_status` 搭配 `changesSince` 擷取精確差異。

## 訊號日誌

當受監看的工作階段發生實質變更時，OpenClaw 會將具型別的事件附加至共享狀態資料庫（`session_state_events`）。事件包含中繼資料與單行摘要，但絕不包含訊息內容。

| 種類                     | 記錄時機                  | 通知監看者      |
| ---------------------- | --------------------- | ---------- |
| `human_direct_message` | 使用者直接向受監看的工作階段傳送一輪訊息  | 是          |
| `upstream_missing`     | 已採用工作階段的上游來源消失        | 是          |
| `goal_changed`         | 建立、更新或清除工作階段的目標狀態     | 是          |
| `child_spawned`        | 建立子代理程式或 ACP 子工作階段    | 否（設定游標初始值） |
| `run_completed`        | 子工作執行成功結束             | 否（僅記錄於日誌）  |
| `run_failed`           | 子工作執行失敗、逾時或遭取消        | 否（僅記錄於日誌）  |
| `compacted`            | 工作階段的歷程經過壓縮           | 否（僅記錄於日誌）  |
| `adopted`              | 目錄中的工作階段被採用至 OpenClaw | 否（僅記錄於日誌）  |

每個事件都會標示其參與者（`human`、`agent` 或 `system`）。遭取消及逾時的子工作執行會記錄為失敗，並在事件承載資料中保留確切結果（`cancelled`、`timeout` 或 `error`）。

工作階段的**狀態版本**就是其日誌中的最高序號，由每個工作階段的持久標頭追蹤，且不受修剪影響。工作階段記錄變更後，`sessions_list` 資料列會包含 `stateVersion`；`session_status` 則一律回報此值。

僅記錄於日誌的種類是供協調同步歷程使用，而非用於通知：一般子工作執行的完成通知仍由[子代理程式公告](/zh-TW/tools/subagents)負責，訊號日誌絕不會重複傳送。

## 監看者

監看者是持有目標游標（`session_watch_cursors`）的工作階段。游標有兩種來源：

* **隱含（衍生邊）。** 當工作階段衍生子代理程式或 ACP 子工作階段時，系統會自動以子工作階段衍生時的版本設定父工作階段游標的初始值。父工作階段絕不需要手動訂閱。
* **明確（`sessions_send watch: true`）。** 任何協調者都能監看非衍生的目標：在 `sessions_send` 中傳入 `watch: true`，訊息成功派送後，傳送者便會註冊為實際收到訊息之工作階段的監看者。註冊會從目標目前的狀態版本開始，先前的歷程絕不會產生通知。設定此參數時，工具結果會回報 `watched: true|false`。

監看者身分必須是包含代理程式限定資訊的工作階段金鑰。在 `session.scope="global"` 下，共享的 `global` 金鑰在不同代理程式之間具有歧義，因此這類工作階段會取得持久日誌與 `changesSince`，但不會收到主動通知。

監看會自行清理：游標資料列會隨訊號日誌保留期限到期、在監看者工作階段重設時移除，並在任一工作階段刪除時一併刪除。v1 不提供取消監看的動作。

系統會以固定頻率檢查從工作階段目錄採用的受監看工作階段，確認上游是否有使用者直接活動。偵測到的活動會像其他使用者直接輪次一樣，進入相同的訊號日誌與監看者流程。

如果已採用工作階段的上游來源遭到外部刪除，連續三次檢查不到（約三個監控週期）後，系統會向其監看者產生一個 `upstream_missing` 訊號，並移除上游連結。再次繼續該目錄工作階段時，會建立新的連結。

## 通知：一次，而非多次

當符合通知條件的事件寫入，且監看者的游標落後時，監看者會在下一輪收到一則系統通知：

```
工作階段 "agent:main:subagent:child" 已變更（其他參與者）。請先協調同步再採取行動：session_status sessionKey "agent:main:subagent:child" changesSince 12。
```

主工作階段監看者也會透過心跳偵測喚醒立即啟動；巢狀子代理程式監看者則會在下一輪收到通知。

此通訊協定刻意採取防洗版設計：

* **每個監看者／目標配對僅有一則待處理通知。** 通知待處理期間，其文字會維持逐位元組不變，且系統事件佇列會據此去除重複項目，因此即使同一目標快速發生二十次變更，監看者的提示中仍只會出現一行。
* **凍結浮水印。** 通知排入佇列時，游標會凍結其已通知位置。後續實質事件只會推進實質浮水印，不會再次通知。
* **取出時確認，僅在工作交錯時重新開啟。** 監看者的輪次取用通知時，游標便會前進。如果排入佇列與取用之間又有更多實質事件抵達，系統會針對剩餘部分只開啟一則新通知。
* **抑制自身事件。** 監看者絕不會收到由自己造成之事件的通知。
* **重新啟動復原。** 待處理通知存放於記憶體內佇列；閘道重新啟動後，啟動掃描會根據持久游標重新具現化這些通知。

## 協調同步

通知會明確告知監看者該怎麼做。使用 `session_status` 搭配 `changesSince: <version>`，會回傳該版本之後的具型別事件（最多 200 個），且不會推進任何游標：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "stateVersion": 19,
  "stateChanges": {
    "events": [
      {
        "sequence": 14,
        "kind": "human_direct_message",
        "actorType": "human",
        "summary": "使用者透過 telegram 傳送訊息"
      },
      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "目標已更新" }
    ],
    "historyGap": false
  }
}
```

`historyGap: true` 表示要求的版本早於目前保留的歷程——此時應重新整理完整工作階段狀態（`sessions_history`、`session_status`），而不是將回應視為精確差異。此缺口訊號是精確的：它來自各工作階段的已修剪浮水印，而非根據序號算術推斷。

## 儲存與限制

歷程存放於共享狀態資料庫，最多保留 30 天和 50,000 筆資料列；各工作階段的標頭在修剪後仍保持單調遞增。記錄採盡力而為模式——附加失敗會寫入日誌，但絕不會導致原始輪次失敗——因此 `stateVersion` 是訊號日誌標頭，而不是交易式變更資料擷取版本。

目前限制：

* 通知傳遞假設共享狀態資料庫由單一閘道程序持有。多個閘道會共用持久日誌與 `changesSince`，但 v1 不會跨程序推送通知。
* 壓縮事件涵蓋內嵌執行階段的壓縮擁有者；僅由原生控制框架執行的壓縮尚未完整記錄。
* 取消結果的承載資料詳細資訊目前由 ACP 子工作執行產生；原生子代理程式的取消則會顯示為一般失敗。
* 上游自身回音偵測會比較正規化後的使用者文字。如果外部提示與工作階段最近 10 則 OpenClaw 端使用者訊息之一相符，便會視為自身回音。
* 單一大於每次掃描上限 1 MiB 的本機 Claude JSONL 資料列，會在 v1 中阻塞該工作階段的游標；絕不會略過未分類的位元組。
* 配對節點的 Claude 檢查會在每個週期分類最新的 50 個文字記錄項目。較大的突發資料量可能超出 v1 掃描視窗。
* 配對節點的 Claude 歷程讀取不會提供明確的找不到討論串結果，因此遠端 Claude 刪除在 v1 中不會分類為 `upstream_missing`。
* 尚未採用的目錄工作階段在 v1 中仍位於感知層之外。
* 在此功能推出前採用的工作階段沒有上游連結；請從目錄繼續一次這些工作階段，以開始上游監控。
* 上游連結假設每個已採用的工作階段金鑰只對應一個擁有者代理程式（採用時使用預設儲存區代理程式）。v1 不會監控同一外部討論串的多代理程式採用情況。

## 相關內容

* [工作階段工具](/zh-TW/concepts/session-tool) — `sessions_send`、`session_status`、`sessions_list`
* [子代理程式](/zh-TW/tools/subagents) — 衍生邊與完成公告
* [心跳偵測](/zh-TW/gateway/heartbeat) — 佇列通知如何喚醒主工作階段
* [工作階段管理](/zh-TW/concepts/session) — 工作階段金鑰、範圍與生命週期