前言¶
在 DSH 生態中，會話狀態通常以事件溯源的方式記錄。要與其他框架（如 CrewAI、LangGraph）或通用 JSON 消費方共享 AI 的”思考過程”，直接解析事件流成本較高。我們需要一種標準化的方式來描述、序列化和遷移認知狀態。
dsh-csp-runtime 插件實現了 Cognitive State Protocol (CSP) v0.1，這是一個跨框架的互操作層。它將 AI 的思考狀態（目標、信念、計劃、決策、不確定性）打包成可序列化的 JSON 快照，使其能夠持久化並跨 Agent 遷移。
核心定位¶
本插件定位爲互操作層，而非事件溯源的替代品。
- DSH 內部仍以事件流記錄會話。
- CSP 僅描述”思考狀態”，不定義具體工具或編排邏輯。
- 正交設計：與 CDP（語義層）、意圖網絡（編排層）可同時共存。CSP 僅引用 ID，不重複定義實體。
核心功能¶
- 狀態轉換：將 DSH event stream 轉換爲 CSP 格式。
- 狀態捕獲與持久化：捕獲並持久化目標、信念、計劃、決策、不確定性等 6 類認知狀態。
- 跨框架互操作：提供
dshToCsp和cspToGeneric接口，實現框架無關的導入導出。 - 交接令牌：支持
transferable、final、blocked三種模式，定義狀態如何被接手。 - CLI 編輯工具：提供
csp-edit.ts用於交互式編輯.csp.json文件。
安裝與配置¶
前置要求：Node.js >= 22.19，DSH cordis >= 0.1.0。
dsh plugin --profile web add github:helibeiqi/dsh-csp-runtime
插件僅註冊 cspStore 服務，並禁用其他服務註冊。配置僅允許以下 5 個頂層字段：
| 字段 | 類型 | 默認值 | 說明 |
|---|---|---|---|
sources |
{ statesDir?: string } |
./csp-states |
CSP 狀態來源目錄 |
capture |
{ enabled: boolean; autoInstrumentTools: boolean } |
{ enabled: false, autoInstrumentTools: false } |
捕獲策略，默認關閉 |
persistence |
{ enabled: boolean; path: string; format: 'json' } |
{ enabled: true, path: './csp-states', format: 'json' } |
文件持久化配置 |
handoff |
{ enabled: boolean; tokenTtlSeconds: number } |
{ enabled: true, tokenTtlSeconds: 3600 } |
交接令牌配置 |
interop |
{ dshExport: boolean; genericImport: boolean } |
{ dshExport: true, genericImport: true } |
跨框架導入導出開關 |
典型用法¶
1. 導出與轉換¶
從 DSH 事件流導出認知狀態，並轉換爲通用格式。
import { dshToCsp, cspToGeneric } from 'dsh-csp-runtime';
// 1. 將 DSH event stream 轉換爲 CSP
const csp = dshToCsp(dshEventStream, store);
// 2. 導出爲框架無關對象
const generic = cspToGeneric(csp);
// 交給 crewai / langgraph / 通用消費方
2. 交接令牌¶
生成和校驗交接令牌，確保接手方能正確理解狀態上下文。
import { createHandoff, verifyHandoff } from 'dsh-csp-runtime';
// 生成令牌
const token = createHandoff(store, stateId, {
mode: 'transferable',
continuation_prompt: '從 step-3 續做利潤率假設',
required_capabilities: ['cdp:equity-research'],
ttl_seconds: 3600,
});
// 校驗並重建可接續骨架
const result = verifyHandoff(JSON.stringify(token));
if (result.ok) {
// result.skeleton.goal_stack / plan_tree 完整保留
// belief_set 中的 transferred 字段將標記爲 true
}
3. 示例結構¶
一個完整的認知狀態快照（以 AAPL 股票分析爲例）包含：
- goal_stack: 當前進行和已完成的任務。
- belief_set: 基於證據的信念集合。
- plan_tree: 執行步驟樹。
- decision_trace: 決策歷史。
- uncertainty: 不確定性評估。
- handoff: 交接指令。
適用場景與注意¶
- 互操作性：適合需要在 DSH 與其他 Agent 框架間遷移認知狀態的應用。
- M1 開發者預覽：當前爲協議設計層交付物，API 和 Schema 在 0.x 版本可能變動，生產環境請鎖定版本。
- 性能：
capture默認關閉，顯式開啓可捕獲狀態。 - 安全性：Handoff Token 目前僅做哈希完整性校驗，無加密簽名。生產環境建議在 Host 層疊加傳輸加密。
- 能力限制：暫未實現 crewai / langgraph 的具體適配，僅提供通用映射。
