# 工作階段記憶

工作階段記憶為長期智能體任務提供可持續、可審核的生命週期。工作階段從工作區和知識庫上下文開始，持續累積已確認的候選知識與進度檢查點，最後產生精簡快照。下一位使用者或智能體可以攜帶決策、目前進度和下一步動作繼續工作。

TokST 僅保存透過工作階段工具明確提交的內容。憑據、私鑰、缺乏明確用途的私密資料、原始推理過程和短期工具輸出保留在目前執行環境中。

## 適用情境

多步驟工作、需要交接的任務、需要保留審核過程的事項適合建立工作階段。例如功能開發、事故排查、發佈準備、合約審閱和多智能體協作。

單筆長期事實適合直接建立記憶。工作階段記憶同時保存該事實形成過程中的進度、交接點和審核記錄。

## 生命週期

| 階段 | 記錄內容 | 作用 |
|---|---|---|
| 開始 | 任務、工作區/知識庫範圍與回傳的上下文 | 建立工作邊界，減少重複組織上下文 |
| 擷取 | 候選事實、決策、偏好、任務、架構或一般說明 | 將已確認的長期資訊與原始工作材料分開 |
| 檢查點 | 精簡進度摘要與下一步動作 | 支援交接和中斷後的恢復 |
| 完成 | 最終摘要與不可變工作階段快照 | 為任務產生精簡的完成記錄 |
| 審核 | 編譯、駁回或撤銷候選內容 | 讓工作區管理者治理正式記憶 |
| 封存 | 保留稽核與搜尋記錄，隱藏預設列表 | 保持活躍工作區聚焦並保留歷史 |

`finalize` 預設把待處理候選內容編譯為正式記憶。使用 `--no-compile` 可將候選保留給管理者審核。撤銷已編譯候選會封存其關聯正式記憶，並保留完整稽核鏈路。

## CLI 工作流程

智能體執行使用 `TOKST_AGENT=1`，輸出保持結構化，伺服器會從 API 金鑰注入可信智能體身分。

```bash
# 1. 從本任務需要的知識庫上下文開始。
TOKST_AGENT=1 tokst session start \
  --atlas-id <atlas-id> \
  --task "實作工作區邀請到期機制" \
  --idempotency-key invite-expiry-v1 \
  --json

# 2. 僅擷取已確認、可重用的結論。
TOKST_AGENT=1 tokst session capture \
  --session <ses-id> \
  "待處理邀請會在所選有效期結束後過期。" \
  --kind decision \
  --title "邀請到期規則" \
  --tags workspace,invitations \
  --confidence 0.95 \
  --source-event-id issue-482-decision \
  --json

# 3. 交接或長時間暫停前保存檢查點。
TOKST_AGENT=1 tokst session checkpoint \
  --session <ses-id> \
  "遷移與 API 已完成；下一步驗證使用者後台。" \
  --json

# 4. 完成任務，預設編譯候選為正式記憶。
TOKST_AGENT=1 tokst session finalize \
  --session <ses-id> \
  "已完成到期流程並記錄使用者後台驗證事項。" \
  --json
```

常用後續指令：

```bash
# 檢視工作階段、候選、檢查點、快照和範圍內上下文。
tokst session status <ses-id> --json

# 列出目前工作區中自己的工作階段。
tokst session list --workspace <workspace-id> --status active --json

# Owner/Admin：檢視整個工作區，包括已封存工作階段。
tokst session list --workspace <workspace-id> --scope managed --archived --json

# 先查看工作區待審核候選佇列，再開啟個別工作階段。
tokst session candidates --workspace <workspace-id> --scope managed --status pending --json

# Owner/Admin：審核候選內容。
tokst session candidate --session <ses-id> --candidate <candidate-id> --action compile --json
tokst session candidate --session <ses-id> --candidate <candidate-id> --action dismiss --reason "已被替代" --json
tokst session candidate --session <ses-id> --candidate <candidate-id> --action revert --reason "決策錯誤" --json

# 封存保留歷史；還原會重新顯示該工作階段。
tokst session archive <ses-id> --reason "工作完成" --json
tokst session restore <ses-id> --json
```

本機執行環境使用相同的 `tokst local session ...` 生命週期，並將工作階段、候選、檢查點、快照和編譯後記憶寫入本機 SQLite。雲端工作階段提供工作區權限、智能體身分、後台治理和共享稽核歷史。

## 自動工作階段擷取

| 模式 | 擷取來源 | 適用範圍 |
|---|---|---|
| 輔助模式 | 智能體依循 Skill 或 MCP 指令呼叫工作階段工具 | 所有 MCP 與 REST 客戶端 |
| 自動記憶 | TokST 接收已連接 ACP 工作階段或原生用戶端橋接事件 | ACP 用戶端、WorkBuddy、OpenCode、Pi、Codex 與 Claude Code |

自動記憶在使用者裝置上執行。TokST 先在本機去識別 API 金鑰、Token、密碼、Cookie 和私鑰。雲端工作階段保留已去識別的使用者請求、智能體最終回覆和有效工具結果，供工作階段詳情追溯；原始推理、串流片段和敏感內容會立即捨棄。

每個自動工作階段都會記錄來源、原生或 ACP 工作階段識別、最近事件、編譯狀態和正式記憶連結。原生工作階段作為完整稽核容器，可包含多個獨立任務；每個完成的任務建立一筆正式記憶，針對同一任務的追問會更新對應記憶並保留版本追溯。工作階段頁會將一般工作會話與診斷記錄分開顯示。

自動整理會保留目前任務的確認事實、決策、變更、任務和架構資訊，並完整保留有效表格列、數字、單位、路徑、命令、URL、狀態、錯誤和後續事項。系統會清理重複表述、原始推理、串流片段和重複工具中介資料。工作階段詳情提供完整結果證據與任務記憶連結，正式記憶提供清楚、可檢索的結構化內容；每項任務完成後自動儲存一筆正式記憶，使用者可從工作階段詳情撤銷並封存關聯記憶。

```bash
tokst auto on
tokst acp proxy -- <acp-agent-command> [args]
tokst acp opencode
tokst auto status
tokst auto verify --agent all --json
tokst auto privacy --retain-raw 0
```

### 原生橋接與 ACP 連線

支援 ACP 的用戶端透過本機代理連線。`tokst auto on --agent all` 會偵測並安裝 WorkBuddy、OpenCode、Pi、Codex 與 Claude Code 的橋接器，然後啟動本機服務。安裝後重新啟動使用的用戶端。WorkBuddy 使用 Harness 生命週期；OpenCode 在終端與 macOS App 使用全域外掛；Pi 使用全域擴充；Codex 與 Claude Code 使用可與既有 Hook 共存的受管理 Hook。每個橋接器保留原生工作階段的稽核軌跡，並建立可撤銷 Markdown 記憶。

OpenCode 終端與 macOS App 從 `~/.config/opencode/plugins/tokst-automatic-memory.ts` 自動載入全域外掛。外部 ACP Host 透過 `tokst acp opencode` 使用同一條鏈路：ACP 宿主啟動 TokST，TokST 啟動 `opencode acp`，原始 ACP 請求和回應保持透明轉送。使用 `tokst auto status --agent opencode` 檢查原生與 ACP 狀態；`tokst auto repair --agent opencode` 會依目前 TokST 絕對路徑重建外掛。

啟用自動記憶時會自動安裝並啟動使用者層級服務：macOS 使用 `launchd`，Linux 使用 `systemd --user`，Windows 使用登入工作。服務在網路中斷時佇列已去識別 ACP、WorkBuddy 與 OpenCode 事件，並以穩定事件 ID 補傳。目前連線的 ACP 智能體完成私有整理，無需額外模型端點或模型金鑰。

每個 ACP 或原生工作階段穩定映射到一個 TokST 工作階段；其中的任務單元分別映射到正式記憶。`tokst auto status --agent workbuddy` 與 `tokst auto status --agent opencode` 顯示本機服務、橋接器狀態、路由、佇列與可行動診斷。Auto API 保存使用者與工作區策略；事件由本機服務處理。

## MCP 工作流程

雲端 MCP 與 stdio MCP 提供以下工作階段工具。本機 MCP 保留相同的主動工作階段生命週期與候選治理；ACP 專屬的恢復和自動記憶撤銷由雲端介面提供，因為其稽核鏈路與正式記憶保存在共享服務中。

| 工具 | 用途 |
|---|---|
| `tokst_session_start` | 建立範圍內任務並讀取上下文 |
| `tokst_session_capture` | 新增候選內容，可包含類型、標籤、標題、置信度和來源事件 ID |
| `tokst_session_checkpoint` | 保存進度與下一步動作 |
| `tokst_session_finalize` | 產生最終快照，並可選擇編譯候選內容 |
| `tokst_session_status` | 檢視工作階段狀態與恢復上下文 |
| `tokst_session_list` | 列出個人或受管理的工作區工作階段 |
| `tokst_session_moderate_candidate` | 編譯、駁回或撤銷候選內容 |
| `tokst_session_archive` | 封存或還原工作階段 |
| `tokst_session_reopen` | 雲端/stdio MCP：恢復 ACP 工作階段並保留自動記憶識別 |
| `tokst_session_revert_automatic_memory` | 雲端/stdio MCP：封存 ACP 工作階段的自動記憶並保留稽核 |
| `tokst_auto_status` | 讀取自動記憶策略與本機連線狀態 |
| `tokst_auto_configure` | 為工作區或知識庫啟用、暫停或設定自動記憶路由 |

建議將以下規則加入智能體專案指令：重要工作開始前建立工作階段；僅擷取已確認的長期內容；交接前建立檢查點；完成後結束工作階段；密鑰和原始推理不寫入 TokST。`tokst agent listen` 收到工作區交接後，接收智能體應恢復指定工作階段或建立新工作階段，並在確認交接後建立檢查點。

## 審核與權限

| 角色 | 工作階段權限 |
|---|---|
| Member | 在可存取工作區中建立、讀取、擷取、完成和封存本人工作階段 |
| Admin | 檢視受管理的工作區工作階段，並治理該工作區全部候選內容 |
| Owner | 具備 Admin 治理權限，並可檢視完整工作區稽核 |
| 系統管理員 | 在獨立系統管理員後台唯讀稽核跨工作區工作階段 |

使用者後台入口為 **控制台 → 工作階段**。頁面跟隨目前工作區，頂部提供待審核候選佇列，顯示來源工作階段、置信度、內容和處理狀態。成員管理自己的候選；Owner 與 Admin 管理整個工作區佇列。工作階段檢視同時顯示狀態、任務、建立者、智能體、知識庫、檢查點、最近活動和快照狀態。Realtime 僅刷新目前工作區。自動記憶會在 ACP 工作階段結束時由已連線的 Agent 建立一條可撤銷記憶；發生失敗時執行 `tokst auto status` 檢查連線、權限與去識別狀態。

## 可靠寫入與品質

- 用戶端可能重試建立工作階段時，傳入 `--idempotency-key`；同一鍵會回傳已有工作階段。
- 同一來源事件可能重複投遞時，傳入 `--source-event-id`；同一事件會回傳已有候選內容。
- 重複 `finalize` 會安全回傳已完成結果，避免產生競爭摘要。
- 置信度用於描述證據品質。低於 `0.6` 的候選會進入低置信度品質檢視，供管理者審核。
- 內容保持具體且可獨立重用。檢查點使用幾句話說明目前進度、阻塞項和下一步動作。

介面細節請參考 [CLI 參考](/docs/cli#會話記憶)、[MCP 參考](/docs/mcp#會話記憶協定) 和 [REST API 參考](/docs/rest-api#會話記憶-api)。