> ## 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。
```

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

此協定刻意避免大量通知：

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

## 協調同步

通知會明確告知監看者該做什麼。搭配 `changesSince: <version>` 使用 `session_status`，會回傳該版本之後的具型別事件（最多 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 端使用者訊息中的任一則相符，便會視為自我回聲。
* 若單筆本機 Claude JSONL 資料列大於每週期 1 MiB 的掃描上限，v1 中該工作階段的游標便會遭到阻塞；系統絕不會略過未分類的位元組。
* 配對節點 Claude 檢查會在每個週期分類最新的 50 個文字記錄項目。更大的突發量可能超出 v1 掃描視窗。
* 配對節點 Claude 歷程讀取不會公開明確的找不到討論串結果，因此 v1 不會將遠端 Claude 刪除分類為 `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)——工作階段索引鍵、範圍與生命週期