TokST 面向人類與 AI 智能體的持久上下文

工作階段與自動記憶

進階 Runtime 工作流程。 長期記憶、上下文、知識庫、檔案和工作區治理請使用雲端 MCP。本機智能體擷取、定向任務執行、通訊和端點診斷需要安裝獨立 CLI。

工作階段以一條可稽核時間線記錄智能體的正常工作。TokST 擷取有效使用者請求、最終回覆與有價值的工具結果，再產生可閱讀的工作階段整理。工作階段包含可跨任務重用的事實、決策、偏好、規則或架構時，可擷取零筆或多筆長期記憶。

任務擁有獨立文件與流程。工作階段只記錄已經完成的工作，並可在使用者後續建立任務時提供上下文。

TokST 會在保存前移除憑據、私鑰、密碼、Cookie、敏感個人資料、原始推理與短期工具輸出。

適用情境

工作階段用於檢視 Pi、OpenCode、WorkBuddy、Codex 或 Claude Code 的自動擷取、整理版本、擷取記憶與診斷。功能開發、事故排查、發佈準備、合約審閱和多智能體協作都適合透過工作階段保留過程。

長期可重用的事實和決策保存在記憶中。定向執行與分派請參考任務文件。

生命週期

階段記錄內容作用
擷取使用者請求、最終回覆與有價值工具結果保留真實工作邊界
整理可閱讀的結果、證據、風險與後續動作讓每個完成單元可追溯
提取零筆或多筆長期可重用記憶將長期資訊與工作階段歷史分開
審核發布、修訂或撤銷提取記憶讓工作區管理者治理長期知識
封存保留稽核與搜尋記錄，隱藏預設列表保持活躍檢視聚焦並保留歷史

下方明確工作階段指令透過已連線 CLI Runtime 與既有自動化整合繼續可用。自動擷取使用相同的隱私、證據、審核與封存規則。

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

雲端工作階段提供工作區權限、智能體身分、用戶後台治理與共享稽核歷史。已連線 Runtime 裝置保留內部加密佇列，用於橋接投遞與去識別復原，不形成獨立的本機記憶產品。

自動工作階段擷取

模式擷取來源適用範圍
已連線 RuntimeCLI 橋接器記錄本機智能體活動已連線本機端點
自動記憶TokST 接收已連接 ACP 工作階段或原生用戶端橋接事件ACP 用戶端、WorkBuddy、OpenCode、Pi、Codex 與 Claude Code

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

每個自動工作階段都會記錄來源、原生或 ACP 工作階段識別、最近事件、編譯狀態、自動整理版本和關聯長期記憶。工作階段邊界同時具備有效使用者請求與最終結果時建立待確認草稿；通用啟動、恢復與關閉事件保留在活動與診斷記錄中。原生工作階段作為完整稽核容器，可包含多個獨立任務。使用者可從已發布整理結果建立正式任務。

自動整理會保留目前任務的確認事實、決策、變更、任務和架構資訊，並完整保留有效表格列、數字、單位、路徑、命令、URL、狀態和後續事項。系統會清理重複表述、原始推理、串流片段、HTTP 或配額錯誤和重複工具中介資料。工作階段詳情提供完整結果證據、自動整理版本與關聯長期記憶；每項任務可提取零條或多條長期記憶，使用者可從工作階段詳情撤銷並封存關聯記憶。

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

原生橋接與 ACP 連線

支援 ACP 的用戶端透過本機 Runtime 連線。執行 tokst start 連線裝置，再執行 tokst auto on --agent all 安裝並啟用 WorkBuddy、OpenCode、Pi、Codex 與 Claude Code 的橋接器。安裝後重新啟動使用的用戶端。WorkBuddy 使用 Harness 生命週期；OpenCode 在終端與 macOS App 使用全域外掛；Pi 使用全域擴充；Codex 與 Claude Code 使用可與既有 Hook 共存的受管理 Hook。每個已啟用橋接器保留原生工作階段的稽核軌跡，為每項完成任務建立自動整理，並從中提取可重用的長期記憶；恢復工作階段會持續更新對應整理版本。

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

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

每個 ACP 或原生工作階段穩定映射到一個 TokST 工作階段；其中的任務單元分別映射到自動整理版本和可選長期記憶。tokst status --agent workbuddy 與 tokst status --agent opencode 顯示本機服務、橋接器狀態、路由、佇列與可行動診斷。自動記憶策略由控制台與已連線 Runtime 管理；事件由本機服務處理。

已連線 Runtime

工作階段、任務與溝通透過已驗證 WSS 由已連線 TokST Runtime 處理，同時保持獨立記錄。自動記憶預設關閉，並按支援用戶端分別開啟。使用後台檢視、覆核、封存和復原這些記錄。雲端 MCP 為工作提供長期記憶與上下文。

任務

工作階段可以為使用者建立的任務提供已確認的來源上下文。分派、執行方式、結果、復原與任務權限請閱讀任務指南。

溝通儲存長期私訊與智能體群組，不會自動建立工作階段或任務。聯絡人、投遞、串流回覆和群組行為請查看溝通。

審核與權限

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

使用者後台入口為 控制台 → 工作階段。頁面跟隨目前工作區，顯示來源、整理版本、提取記憶、診斷、建立者、智能體、知識庫、最近活動和快照狀態。成員管理自己的候選；Owner 與 Admin 管理整個工作區佇列。Realtime 僅刷新目前工作區。自動記憶會在 ACP 工作階段完成後由已連線的 Agent 整理結果，並在有重用價值時提取長期記憶；發生失敗時執行 tokst status 檢查連線、權限與去識別狀態。

可靠寫入與品質

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

已連線 Runtime 指令請參考 CLI 參考。長期記憶與上下文請使用雲端 MCP。