前言¶
在 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 的具体适配，仅提供通用映射。
