dsh-openviking-client

DSH (DeepSeek Harness) 插件：将 Agent 会话消息自动同步到 OpenViking 会话记忆库，由 OpenViking 服务端负责记忆提取与生命周期管理。

插件定位：被动、自动的会话同步器。DSH 侧每轮对话结束（turn/end）自动把增量消息写入 OpenViking 会话；记忆的提取、提交（commit）、归档全部由 OpenViking 服务端完成。主动检索能力（mcp__openviking__*）由独立的 MCP 客户端提供，本插件不重复实现。

功能特性

• 全量会话同步：会话创建时自动在 OpenViking 建立对应 session（携带 auto-commit 策略），对话消息按 turn 增量同步
• 增量去重：基于 syncedIds 集合做消息级 diff，只写入新增消息，不产生重复
• 自动提交策略：配置 autoCommitPolicy（消息数/Token 阈值/空闲时间），由服务端自动 commit 并提取记忆
• 故障容错：OpenViking 停机不中断 DSH 主流程，恢复后自动补写；网络失败指数退避重试（默认 2 次）
• 多租户身份支持：兼容 OpenViking 三种认证模式（dev / trusted / api_key）
• 可观测：请求级 + 同步级结构化日志

安装

# 在 DSH profile 目录安装（插件经 symlink 挂载到 profile 的 node_modules）
dsh plugin --profile web add <本目录>
# 或将编译产物拷贝到 profile，并在 cordis.patch.yml 中注册

依赖

• @deepseek-ai/dsh 0.1.0-rc.x
• Node.js ≥ 22（使用原生 fetch，零第三方 HTTP 依赖）
• 可达的 OpenViking 服务（默认 http://localhost:1933）

配置

在 ~/.dsh/cordis.patch.yml（或对应 profile patch 文件）中插入：

- insert:
    - id: dsh-openviking-client
      name: '/path/to/dsh-openviking-client/lib/index.js'
      config:
        enabled: true
        openvikingBaseUrl: http://localhost:1933
        autoCommitPolicy:
          message_count_threshold: 10
          pending_token_threshold: 10000
          idle_timeout_seconds: 86400
          keep_recent_count: 2
          min_commit_interval_seconds: 0
        timeoutMs: 5000
        retries: 2
        # identity:            # 可选：多租户身份（见下文）
        #   accountId: my-account
        #   userId: my-user
        #   apiKey: sk-xxx

配置项

配置	默认值	说明
enabled	true	主开关；false 时插件不发起任何请求
openvikingBaseUrl	http://localhost:1933	OpenViking 服务地址（不带尾斜杠）
autoCommitPolicy.message_count_threshold	10	待同步消息数达到该值触发 commit
autoCommitPolicy.pending_token_threshold	10000	待同步 Token 数达到该值触发 commit
autoCommitPolicy.idle_timeout_seconds	86400	空闲多久后触发 commit
autoCommitPolicy.keep_recent_count	2	commit 后保留的最近会话数
autoCommitPolicy.min_commit_interval_seconds	0	两次 commit 的最小间隔
timeoutMs	5000	单请求超时（毫秒）
retries	2	网络错误/5xx 重试次数（指数退避，base 200ms）
identity.accountId	无	发送 X-OpenViking-Account 头（trusted 模式）
identity.userId	无	发送 X-OpenViking-User 头（trusted 模式）
identity.apiKey	无	发送 X-API-Key 头（api_key 模式）

多租户身份（OpenViking 认证模式）

OpenViking 服务端模式	插件配置	效果
dev（默认，单租户）	不配置 identity	请求不带身份头，数据归 default account
trusted	identity.accountId / identity.userId	请求带 X-OpenViking-Account/User，数据归指定 account
api_key	identity.apiKey（可组合 account/user）	请求带 X-API-Key 认证

工作原理

DSH session 生命周期                     OpenViking 服务端
─────────────────────                   ──────────────────────
session/created ──► ensureSession ──► POST /api/v1/sessions
                    （携带 auto_commit_policy）

每轮对话结束       syncTurn（串行队列，增量 diff）
  turn/end ──────►  deriveMessages ──► 对比 syncedIds
                    mapMessage ──────► POST /api/v1/sessions/{id}/messages/batch
                                        （≤100 条/批，自动分块）

                    ✔ 成功 → 记录 syncedIds
                    ✘ 失败 → 静默跳过（不中断 DSH），下次 turn 补写

（服务端自动 commit ──► 记忆提取 ──► viking://user/memories/...）

消息映射（对齐 OpenViking 消息契约）：

DSH 消息	OpenViking message_kind
用户文本消息	user_query
工具调用/结果	tool_transport
助手回复	assistant_step

会话 ID 映射：DSH 会话 id 原样作为 OpenViking session_id（服务端会自动做安全化处理）。

开发

npm install          # 安装依赖
npm run build        # tsc 编译到 lib/
npm run typecheck    # 类型检查（无输出 = 通过）
npm test             # 运行单元测试（node:test + tsx）
npm run test:coverage

项目结构

src/
  config.ts   # 配置 schema 与默认值（schemastery）
  client.ts   # OpenViking HTTP 客户端（fetch，超时/重试/分块/身份头）
  mirror.ts   # 会话镜像：syncedIds 去重、消息映射、串行同步队列
  index.ts    # cordis 插件入口：事件挂载、client/mirror 组装
test/
  client.test.ts   # 客户端：重试/分块/身份头
  config.test.ts   # 配置 schema 校验
  mirror.test.ts   # 消息映射/增量同步/容错
  fixtures/        # 测试数据与人工测试指南
lib/              # tsc 编译产物（发布用）
spec/             # 需求/设计/任务/状态文档（内部开发文档）

测试

• 单元测试：npm test（28 例，覆盖 client 重试语义、分块、身份头、config schema、消息映射、增量同步、容错路径）
• 人工集成测试：test/fixtures/commands.md 提供 TC-01~TC-10 人工验证指南（会话创建、消息一致、增量无重复、停机容错、禁用零请求、高频性能等）

与官方插件的区别

OpenViking 官方提供了功能更完整的 @openviking/dsh-memory-plugin（含主动召回、MCP 工具桥、viking:// URI 防护等）。本插件聚焦于轻量的被动会话同步：

• ✅ 携带 auto_commit_policy 创建会话（官方插件不带策略参数，靠自身 token 阈值 commit）
• ✅ 消息级增量去重（syncedIds diff）
• ⚠️ 不含主动召回 / MCP 工具面 / URI 防护（这些由独立的 mcp-openviking 客户端提供）, 在 ~/.dsh/cordis.patch.yml（或对应 profile patch 文件）中插入：

- insert:
    - id: mcp-openviking
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: openviking
        transport: streamable-http
        url: http://localhost:1933/mcp
        headers:
          Authorization: 'Bearer your-api-key-here'

⚠️ 两者不可共存：都监听 session/event 写同一 OpenViking 会话，会双写冲突。二选一。

License

MIT