ykfs/dsh-openviking-client

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