工作階段記憶
工作階段記憶為長期智能體任務提供可持續、可審核的生命週期。工作階段從工作區和知識庫上下文開始，持續累積已確認的候選知識與進度檢查點，最後產生精簡快照。下一位使用者或智能體可以攜帶決策、目前進度和下一步動作繼續工作。
TokST 僅保存透過工作階段工具明確提交的內容。憑據、私鑰、缺乏明確用途的私密資料、原始推理過程和短期工具輸出保留在目前執行環境中。
適用情境
多步驟工作、需要交接的任務、需要保留審核過程的事項適合建立工作階段。例如功能開發、事故排查、發佈準備、合約審閱和多智能體協作。
單筆長期事實適合直接建立記憶。工作階段記憶同時保存該事實形成過程中的進度、交接點和審核記錄。
生命週期
| 階段 | 記錄內容 | 作用 |
|---|---|---|
| 開始 | 任務、工作區/知識庫範圍與回傳的上下文 | 建立工作邊界，減少重複組織上下文 |
| 擷取 | 候選事實、決策、偏好、任務、架構或一般說明 | 將已確認的長期資訊與原始工作材料分開 |
| 檢查點 | 精簡進度摘要與下一步動作 | 支援交接和中斷後的恢復 |
| 完成 | 最終摘要與不可變工作階段快照 | 為任務產生精簡的完成記錄 |
| 審核 | 編譯、駁回或撤銷候選內容 | 讓工作區管理者治理正式記憶 |
| 封存 | 保留稽核與搜尋記錄，隱藏預設列表 | 保持活躍工作區聚焦並保留歷史 |
finalize 預設把待處理候選內容編譯為正式記憶。使用 --no-compile 可將候選保留給管理者審核。撤銷已編譯候選會封存其關聯正式記憶，並保留完整稽核鏈路。
CLI 工作流程
智能體執行使用 TOKST_AGENT=1，輸出保持結構化，伺服器會從 API 金鑰注入可信智能體身分。
# 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
常用後續指令：
# 檢視工作階段、候選、檢查點、快照和範圍內上下文。
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、狀態、錯誤和後續事項。系統會清理重複表述、原始推理、串流片段和重複工具中介資料。工作階段詳情提供完整結果證據與任務記憶連結，正式記憶提供清楚、可檢索的結構化內容；每項任務完成後自動儲存一筆正式記憶，使用者可從工作階段詳情撤銷並封存關聯記憶。
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 參考、MCP 參考 和 REST API 參考。