junwei529/session-coordinator-dsh

DeepSeek Harness Session Coordinator（SCDP）

Session Coordinator for DeepSeek Harness（SCDP） 是构建于 DeepSeek Harness（DSH）之上的多 Session、多 Workstream 协调基础设施。它为彼此相关的 DSH Session 提供稳定的 Workstream 身份、精确的 Session 寻址、持久协调记录，以及可由其他插件和用户界面共同使用的明确恢复协议。

当一项工作跨越多个相互独立的 DSH Session，而临时 prompt 或任务标题已经不足以可靠回答以下问题时，就适合使用 SCDP：哪些 Session 属于同一项工作、记录应发送给哪一个精确 Session、当前有哪些投递证据，以及重启或传输结果不确定后应如何继续。

SCDP 提供什么

稳定的 Workstream 与精确的 Session membership

SCDP 使用不透明的 WorkstreamId 把现有 DSH Session 组织起来。Membership 绑定的是原生 DSH SessionId，不会根据任务标题、侧边栏位置、fork 标签或模型生成的文字推测身份。Workstream 支持创建、列出、带 revision 检查的重命名、关闭，以及 Workstream 与 Session 两个方向的查询。

SCDP 不替换 DSH Session，也不改写其原生身份、日志、fork lineage、workflow、goal 或 plan；它只在这些 Session 之上增加一层持久关系。

不可变、可寻址的协调记录

插件可以接受通用的 message、request 和 outcome 记录，目标可以是一个精确 Session，也可以是某个 Workstream 在接受记录时冻结的 membership。每条记录包含调用方提供的 recordId、correlationId、可选因果记录、来源 Session 和不可变内容。以同一 identity 重复提交完全相同的输入是幂等的；若用同一 identity 提交不同的不可变内容，则会明确返回 conflict，而不是悄悄产生第二种含义。

上层产品可以用这些通用记录承载 Result Notice、decision、disposition 和 acknowledgement 等约定。SCDP 负责保存它们的 identity、correlation、接收者和投递事实，但不解释其中的政策语义。

不隐藏不确定性的投递状态

记录被 SCDP ledger 接受，与记录已投递或已确认是不同事实。每个接收者都有以下五种投递状态之一：

- pending —— 记录已接受，但尚无持久投递证明；
- delivered —— 接收方 Session log 中已有 DSH inbox splice；
- acknowledged —— Session log 中已有对应的持久 user message；
- failed —— 已确定的终止失败，例如取消或 message-ID conflict；
- unknown —— 现有传输或持久化证据不足以判定效果。

Record、correlation、revision 和 delivery conflict 会作为类型化错误显式返回，不会被混入 unknown。发生中断后，调用方使用同一个 record identity 对照持久 Session 证据进行 reconcile。SCDP 不会把 unknown、conflict、delivered、acknowledged 或 failed 的投递当作新记录盲目重发。

持久化与重启恢复

Workstream、membership、记录、接受顺序和投递状态保存在 SCDP 自有的 DSH storage domain 中；投递 reconcile 通过 Session persistence 读取持久 DSH Session log。服务可用前会先验证 SCDP logical schema，重启后则重新打开已保存的协调状态，而不是根据 UI 标签或聊天摘要重建状态。

当前完成资格验证的 provider 组合仅为 DSH JSON 协调存储加 JSONL Session persistence；这不隐含对其他 provider 的支持声明。

面向插件与使用者的接口

- Host 以 ctx.sessionCoordinator 暴露类型化的同进程 service，包含 lifecycle、membership、record、reconcile 和 process 方法。
- 经过运行时校验的 DTO 与错误结果通过生成的 unary Remote 提供给 browser Client。
- Client 提供带命名空间的侧边栏 action 和 Session Coordinator overlay。列表和状态 projection 是派生视图，但整个 UI 并非只读：它会发出显式的 create、rename、close、attach、detach、accept、reconcile 和 process 命令。校验和状态转换仍由 Host 权威执行。
- Overlay 通过 DSH 原生 Client Session service 打开成员 Session，不替换 Conversation 或 Trajectory 视图。
- SCDP 不提供 Work Charter policy prompt、role engine 或 approval tool。模型可见的协调输入使用 DSH 持久 Session message 路径，因此可以从 Session log 重建。

公开 package surface 包括 Node ESM Host 入口、session-coordinator-dsh/types 下的类型合同、session-coordinator-dsh/remote 与 session-coordinator-dsh/typert 下生成的 Remote 支持，以及 session-coordinator-dsh/client 下的 DSH browser assembly 入口。Client 入口采用 DSH 的 lazy-CJS assembly 格式，并不是通用 CommonJS API。

SCDP 明确不负责决定什么

SCDP 是协调基础设施，不是 Work Charter、workflow、role、approval、policy 或 acceptance engine。它可以记录上层插件声明了某个 outcome，也可以展示这条记录如何投递，但不能判断工作是否获得授权、是否合规、是否正确或是否可接受。

它也不替换 DSH 的 persistence、fork/resume、subagent control、workflow、goal、plan、approval、sandbox 或 agent-loop 语义。SCDP 不是分布式共识系统、exactly-once message broker 或通用队列。

其他插件何时应依赖 SCDP

如果一个 DSH 插件需要稳定的跨 Session 身份、精确接收者、带 correlation 的持久记录，以及可在重启后安全恢复的投递机制，同时又希望把自身业务政策留在 SCDP 之上，那么它适合成为 SCDP consumer。

work-charter-dsh 是真实的下游参考。它使用 SCDP 提供 Workstream identity、Session membership 与寻址、Result Notice 投递、correlation 和恢复；Work Charter 的 role、writer rule、decision、evidence、acceptance 与 stop policy 由 WCDP 而非 SCDP 负责。

安装当前 alpha Pre-release

当前发布版本为 v0.1.1-alpha.1，在 GitHub 上标记为 Pre-release，且 latest=false。Package 使用 MIT License，保留 "private": true，并且没有发布到 npm。

此版本只针对官方 DSH tag dsh-v0.1.2-alpha.1、commit cd5ef8148158c3a752a658978873241fdf8e2bbc 完成资格验证。请从 Release 页面同时下载 tarball、SHA-256、SHA-512 和未签名 provenance artifact。已接受 tarball 的大小为 97,138 bytes，SHA-256 为：

9575d1edf782f16b2d87b49bc27e290ecf841fa607a7d4a4468a41de2389b269

Artifact 文档说明：已发布的 immutable tarball 来自 GitHub 发布步骤之前已经接受的 commit 8bed40f3e18b106c69e3dadbef6f029092e73424，因此其中内嵌的 README.md、CHANGELOG.md、SECURITY.md 和 THIRD_PARTY_NOTICES.md 仍保留打包时的 candidate 措辞。这些措辞属于历史快照，并不表示 tag 或 Pre-release 不存在。本次发布后文档收口不会替换 tarball，也不会改变上方已接受的 artifact bytes 与 hash。

将 artifact 加入 profile 前，先校验下载文件：

Get-FileHash -Algorithm SHA256 .\session-coordinator-dsh-0.1.1-alpha.1.tgz
dsh plugin --profile  add .\session-coordinator-dsh-0.1.1-alpha.1.tgz
dsh --profile  --dump-default-config

SCDP 有意不声明 dsh.bundle，因此 dsh plugin 会把它安装为普通 profile dependency，并可能输出相应的定位提示。兼容的消费方 bundle 或 composition 必须先挂载 SCDP，才能使用 ctx.sessionCoordinator；只添加该 tarball 不会产生独立的配置层。若使用基于 WCDP 的 profile，请查阅 WCDP 仓库，并且只使用明确固定到这个 SCDP 版本的 WCDP artifact。

这是绑定 artifact 的 alpha 安装路径，不是普通 registry 安装：资格验证使用的精确 DSH alpha.1 package set 当时无法从 npm 获得。

兼容性与已验证范围

| 对象 | 当前完成资格验证的声明 |
|---|---|
| SCDP | session-coordinator-dsh@0.1.1-alpha.1；public contract 3；logical schema 2 |
| DSH | 精确 dsh-v0.1.2-alpha.1@cd5ef8148158c3a752a658978873241fdf8e2bbc；不声明 version range |
| Runtime | Package engine 为 ^22.19.0 || >=24.0.0；已接受 alpha artifact 使用 Node v24.16.0 与 pnpm 11.7.0 生成 |
| Persistence | JSON 协调存储加 JSONL Session persistence |
| Distribution | GitHub Pre-release tarball 与 checksum/provenance artifact；private: true；未发布 npm |
| Runtime evidence | 在固定 artifact graph 上验证了真实 Loader 与 Remote composition、Workstream record 与投递/恢复、重启、browser UI，以及精确的下游 WCDP consumer |

这些声明不涵盖 SQLite 或其他 provider、其他 DSH 版本、Node 22 实际运行、多进程或跨主机协调、分布式排序、任意下游插件、生产成熟度或 support SLA，也不作 exactly-once 或一般可靠性声明。

文档、安全与许可证

- 产品规范
- 当前工程状态与恢复入口
- 验证方法、证据与限制
- 变更日志
- 安全政策与 private vulnerability reporting
- MIT License
- 第三方声明