QuantumKuba/dsh-continuum

dsh-continuum

智能体是临时的。项目是持续的。

CI 与打包验证
许可证：MIT
npm 版本

dsh-continuum 是面向 DeepSeek Harness (DSH) 的生产级市场插件。它提供持久化项目记忆、上下文安全的智能体交接、检查点、证据追踪，以及跨临时 LLM 智能体会话的长期任务连续性。

问题：临时智能体失忆症

在多智能体和长期运行的工作流中，单个智能体进程本质上是临时的：
- 上下文窗口被填满，迫使进行上下文清空或激进摘要。
- 子智能体死亡或超时，丢失关键推理、被否定的假设以及未提交的发现。
- 后续智能体重复昂贵的文献/代码库研究，或使已解决的缺陷回归。
- 未协调的智能体会覆盖彼此的工作，或自行验证不完整的实现。

dsh-continuum 将 DeepSeek Harness 从无状态提示运行器转变为具有韧性、可保留状态的软件工程环境。

核心能力

graph TD
subgraph DSH_Runtime["DeepSeek Harness Runtime"]
Agent["Ephemeral Agent Session"]
Prompt["Prompt Section (order: 200)"]
Tools["7 First-Party Tools"]
end

subgraph Continuum["dsh-continuum Core Engine"]
OCC["Optimistic Concurrency (OCC)"]
Leases["Renewable Task Leases"]
SoD["Separation of Duty (4-Eyes)"]
ContextEng["10-Tier Context Budgeter"]
Lock["Liveness File Lock (PID check)"]
end

subgraph Storage[".continuum/ Storage Layer"]
Log["events.jsonl (Append-Only)"]
Snap["checkpoints/ (Snapshots)"]
Arts["artifacts/ (Large Spilled Outputs >10KB)"]
Backup["Backup & Restore (.continuum-backup)"]
end

Agent -->|Invokes| Tools
Tools --> OCC
OCC --> Lock
Lock --> Log
Log --> Snap
Log --> Arts
Snap --> ContextEng
ContextEng -->|Injects Context Pack| Prompt

1. 确定性事件溯源（events.jsonl）：
每一次状态变更（项目创建、任务认领、发现、决策、证据、验证）都被建模为不可变、严格单调排序的事件。系统状态通过重放事件日志以确定性方式推导得出。
2. 崩溃韧性与部分行恢复：
如果宿主进程在写入中途死亡（SIGKILL 或断电），Continuum 会自动检测不完整的尾部 JSON 片段，安全地截断到最后一个已提交事件，并在不丢失数据的情况下继续操作。
3. 带存活检查的协作式锁定：
使用协作式锁文件与防御性 PID 存在性校验（process.kill(pid, 0)）来串行化并发进程写入。来自已终止进程的陈旧锁会被安全打破，而不会使用危险的任意超时。
4. 乐观并发控制（OCC）：
实体更新强制要求严格的版本匹配（expectedVersion）。带有陈旧假设的并发写入会被拒绝，并抛出类型化的 VersionConflictError，而不是静默覆盖状态。
5. 严格的变更幂等性：
使用相同 idempotencyKey 重试因网络中断或重放的工具调用时，会返回缓存结果，而不会重复产生副作用。不同操作之间意外的键冲突会立即触发 IdempotencyMismatchError。
6. 可续期的执行租约：
由代理认领的任务会签发有时限的租约（例如 10 分钟）。如果代理崩溃或放弃任务而未续期其租约，Continuum 的租约协调器会自动将任务释放回 ready 状态，并递增尝试计数器。
7. 四眼职责分离：
可配置的任务验证策略（independent、dual、redteam）在数学上禁止实现任务的代理自行验证该任务。
8. 确定性的 10 层上下文预算：
使用严格的优先级排序（活动任务 $\to$ 北极星 $\to$ 阻塞冲突 $\to$ 关键发现 $\to$ 近期交接）构建受令牌上限约束的系统提示词部分。大型输出（>10KB）会自动溢出到磁盘工件，以保护提示词预算。
9. 不可信内容封装：
外部网页抓取内容、用户输入和发现内容会被净化，并密封在严格的  边界内，以防止提示词突破攻击。
10. 加密备份与经验证的恢复：
将整个项目导出为自包含的 .continuum-backup 归档文件，并带有 SHA-256 完整性验证。

安装

安装到你的 DeepSeek Harness 项目中：

pnpm add dsh-continuum
or
npm install dsh-continuum

dsh plugin --profile web add dsh-continuum
（或在本地开发期间：dsh plugin --profile web ln /path/to/dsh-continuum）

Web UI“插件配置”与 settings.yaml

dsh-continuum 可与 DeepSeek Harness 的 @deepseek-ai/dsh-settings 服务无缝集成。你可以在 DSH Web UI 的 插件配置 中可视化配置它，或在 ~/.dsh/settings.yaml 中配置：

dsh-continuum:
autoInjectContext: true        # Automatically inject Context Pack into system prompts
maxContextPackTokens: 8000     # Maximum token budget for Context Pack
defaultLeaseTtlMinutes: 10     # Task execution lease TTL before sweep
storageMode: workspace         # 'workspace' (.continuum/) | 'home' (~/.continuum/) | 'custom'
customStoragePath: ""          # Custom directory if storageMode is 'custom'
在 Web UI 中所做的更改会立即实时生效，无需重启服务器。

Bundle 层堆栈（cordis.patch.yml）

该包包含 cordis.patch.yml，用于自动化配置文件层补丁：

dsh bundle patch: inserts dsh-continuum into a profile's layer stack.
- insert:
- id: dsh-continuum
name: dsh-continuum
config:
storageMode: workspace
autoInjectContext: true
maxContextPackTokens: 8000
defaultLeaseTtlMinutes: 10

7 个第一方 Continuum 工具

dsh-continuum 暴露了 7 个使用 @deepseek-ai/dsh-tools 定义的第一方工具：

| 工具 | 操作选项 | 描述 |
| :--- | :--- | :--- |
| continuum_project | init、get、status、history、export | 初始化项目、更新 North Star 需求，并导出备份包。 |
| continuum_task | create、claim、renew_lease、submit、verify、reopen、get | 管理任务生命周期、租约、交付物以及四眼验证。 |
| continuum_memory | record_finding、record_decision、ask_question、raise_conflict、attach_evidence、get | 记录事实、架构选择（支持取代）、冲突和证据。 |
| continuum_checkpoint | create、list | 捕获具名里程碑快照，以便快速重放和回滚。 |
| continuum_handoff | create、get_latest | 通过上下文备注，将状态从一个 agent 角色干净地转移到另一个角色。 |
| continuum_context | render | 检查或重新渲染当前活动的、受 token 预算约束的 Context Pack。 |
| continuum_status | check | 诊断、锁状态、租约到期情况以及事件日志健康状况。 |

并发与 Actor 安全
- 已认证主体强制执行：Actor 身份（id、role）安全地派生自 exec.agent.id 和运行时上下文；调用方 JSON 无法伪造主体 ID。
- 工具并发注解：安全的读取操作（get、history、render、check）被声明为 isConcurrencySafe: true，而变更操作则被串行化。

编程式 API 用法

你也可以在独立的 Node.js / TypeScript 代码中直接使用 Continuum：

import { ContinuumEngine, FileSystemStorageBackend, StorageResolver } from 'dsh-continuum'

// 1. Initialize storage backend
const resolver = new StorageResolver({ mode: 'workspace' })
const storage = new FileSystemStorageBackend(resolver)
const engine = new ContinuumEngine(storage)

// 2. Initialize project & North Star
await engine.initProject('proj-alpha', 'Project Alpha', 'Core Engine', {
id: 'agent-orchestrator',
role: 'orchestrator'
})

await engine.setNorthStar(
'Build resilient distributed consensus',
['Linearizable reads', 'Crash recovery'],
{ id: 'agent-orchestrator', role: 'orchestrator' }
)

// 3. Create task with independent verification policy
const task = await engine.createTask({
title: 'Implement WAL Appender',
description: 'Write write-ahead log with fsync flush barrier',
acceptanceCriteria: ['通过崩溃故障测试'],
verificationPolicy: 'independent' // 四眼原则
}, {
actor: { id: 'agent-orchestrator', role: 'orchestrator' }
})

// 4. 实现者认领任务（发放租约）
const claim = await engine.claimTask(task.data.id, {
actor: { id: 'agent-implementer', role: 'implementer' }
})
console.log('Claimed task with lease:', claim.data.leaseId)

任务状态机

任务严格遵循以下转换图：

┌──────────┐
│  queued  │
└────┬─────┘
│
┌────▼─────┐
│  ready   │◄───────────────────────┐
└────┬─────┘                        │
│ claimTask                    │
┌────▼─────┐                        │
│ claimed  │                        │
└────┬─────┘                        │
│ startTask                    │ (rejection / lease expired)
┌────▼─────┐                        │
│ running  │                        │
└────┬─────┘                        │
│ submitTask                   │
┌────▼─────┐                        │
│submitted │                        │
└────┬─────┘                        │
│ verifyTask                   │
├───────────────┐              │
│ (passed)      │ (rejected)   │
┌────▼───────┐  ┌────┴────────┐     │
│ completed  │  │  rejected   ├─────┘
└────────────┘  └─────────────┘

质量与验证

dsh-continuum 针对实际的 DeepSeek Harness 运行时和 Node.js 24 进行了全面测试：

- 14 个测试套件，31 个自动化测试：在单元、属性、集成和 E2E 各层级中 100% 通过。
- 基于属性的不变量测试（fast-check）：在 100 个随机事件流中验证了序列单调性、确定性重放和快照-尾部等价性。
- 零第三方代码渗入：完全采用宽松的 MIT 许可证。已验证与非宽松学术技能在概念上完全独立。

运行测试套件：

pnpm test

在 docs/VERIFICATION.md 中查看完整的验证追踪，在 docs/E2E-DEMO.md 中查看端到端多智能体场景。

许可证

MIT 许可证。详情请参阅 LICENSE 和 NOTICE.md。