dsh-openviking-manager

English | 简体中文

dsh-openviking-manager 是一个 DSH Web UI 插件，用于管理已有 OpenViking 服务的客户端连接、用户 Key 和本机配置诊断，并提供会话级的 OpenViking 记忆开关。它只管理客户端配置与启停；记忆同步、提交和召回本身仍由官方 @openviking/dsh-memory-plugin 负责。

OpenViking 是火山引擎开源，专门给 AI Agent 设计的上下文数据库，用来解决 Agent 长上下文、记忆、知识库管理问题。OpenViking 需要部署对应的服务端程序，服务支持远程访问和账号隔离，因此也适用于做跨设备、跨会话的远程记忆中心。本插件只是为 OpenViking 增加一个配置界面，便于管理本地的客户端配置。

OpenViking 的安装配置详见其官方网站：DeepSeek Harness 记忆插件

安装

# 安装 openviking 的官方插件
dsh plugin --profile web add @openviking/dsh-memory-plugin
# 安装配置管理器
dsh plugin --profile web add dsh-openviking-manager
# 也可以直接从 GitHub 仓库安装或者从 file 安装
dsh plugin --profile web add github:xbzbing/dsh-openviking-manager

安装后可能需要重启对应的 DSH profile，在 DSH 插件页面可以看到openviking-manager的配置管理页面。

功能

• 读取、导入和原子更新 ~/.openviking/ovcli.conf；
• 保留已有 user_key，页面仅显示掩码而不回传明文；
• 检查 OpenViking 的 /health、/ready 与用户身份；
• 检查 ovcli.conf 的 JSON 格式和文件权限，并提供经确认的权限修复；
• 本机发现：读取 ~/.openviking/ov.conf 的非敏感状态，例如认证模式、是否存在 root key；ovcli.conf 始终优先；
• 临时使用 root_api_key 调用官方 Admin API：列账号、列用户、创建账号/用户、重新生成用户 Key；
• 根据当前 endpoint 推导 Studio 地址（<endpoint>/studio），允许用户手工改为反向代理地址；
• 会话级 OpenViking 开关：对话输入框左侧的按钮（默认开启）。关闭某个会话后，本插件会拦截官方插件在该会话的上下文注入、记忆写入/提交，并拒绝其 mcp__openviking__* 工具调用，使该会话不再读写 OpenViking；
• 记忆隔离开关「不允许跨主题共享记忆」：写入官方 ovcli.conf 的 plugin.recallPeerScope，默认开启——首次打开配置页时若文件未定义该键，会自动写入 actor 并重载，使默认行为即为按主题隔离；关闭则写回官方默认 all 允许跨主题共享。保存后自动重新加载官方记忆插件使配置即刻生效（卡片文案会提前提示重载及其副作用，重载结果在状态行报告）；用户级画像注入与共享资源不受该开关影响；.openviking/config.json 等 workspace 配置由用户手工管理，本插件不读写；
• 召回调优：在同一页调整官方插件的自动召回参数 —— scoreThreshold（召回分数阈值，本插件默认 0.5、官方默认 0.35）、recallLimit（单次注入条数上限，默认 10）、recallQueryExpansion（查询扩写，本插件默认关闭、官方默认 auto）、recallExcludeUris（排除的 URI 子树，适合屏蔽 skills、resources 目录索引这类样板内容）、timeoutMs（请求超时，本插件默认 15000 毫秒、官方 dsh 默认 10000）、recallContextTimeoutMs（召回搜索超时，官方默认 0＝按请求超时与扩写/改写地板派生）。后端 search/rerank 卡死时调低这两个超时，可让召回快速失败、不再拖住整个回合（会话感知搜索有 15s/45s 地板，只有 recallContextTimeoutMs 设正值才压得动）。键名与取值域严格取自官方 config-schema，只写 ovcli.conf 的 plugin 段并保留其他键；分数阈值、查询扩写与请求超时带产品默认，首次打开配置页且文件未定义该键时自动写入并重载（与记忆隔离默认开启同一机制），字段留空即回到该键的默认值，其余键留空则删除该键、恢复官方默认；OPENVIKING_* 环境变量优先级更高，被覆盖的字段只读并显示警告；保存后与隔离开关一样自动重新加载官方记忆插件；
• Actor peer id（高级，默认留空）：写入官方 ovcli.conf 的 plugin.peerId 键，用来指定本 DSH 进程归属哪个 peer（主题）。它与隔离开关是两件不同的事——隔离开关（recallPeerScope）只决定「召回范围」，peer id 决定「你是哪个 peer」：
  • 留空（推荐，多仓库场景）：官方插件按每个会话所在 workspace 的 git 身份自动推导 peer，每个仓库自动成为独立主题、主题内跨会话召回，无需逐仓配置。同一个 DSH 实例在多个仓库间工作时，请保持留空——此时 DSH 日志出现的 OpenViking MCP: actor-scoped recall needs an explicit peer id ... 属正常现象，可直接忽略：它只影响模型手动调用的 MCP 工具（退化为跨 peer 广召回），不影响自动注入到上下文的记忆隔离；
  • 填写：本进程所有会话被钉死到这一个 peer，并覆盖上述自动推导。仅适合「一个 DSH 实例只服务单个仓库」，或你有意让多个仓库共享同一主题的情况；填写后 MCP 手动工具也能限定到该 peer、那条日志随之消失。「填入当前仓库」按钮会用官方 workspace-identity 逻辑从当前仓库 git 远端推导出 peer id 供一键填入。留空即删除 plugin.peerId、恢复自动推导；OPENVIKING_PEER_ID 环境变量及 ovcli.conf 顶层的 actor_peer_id/peer_id 凭据优先级更高，命中时字段只读并显示警告（本插件不编辑顶层凭据键）；保存后同样自动重新加载官方记忆插件；
• UI 跟随 DSH 系统语言设置，支持简体中文和英文。

界面

| 在 DSH 中 | 恢复与初始化 | | :---: | :---: | | | | | | |

截图由 npm run screenshots 在一个隔离的 DSH 实例中生成，英文版见 README_EN.md。

安全边界

• root_api_key 只在浏览器表单和一次同源管理请求期间使用，绝不写入 ovcli.conf；创建/轮换完成后插件会清空该输入。
• 现有 user_key 从服务端本地读取，浏览器只收到掩码；连接验证可在不回显旧 key 的情况下完成。
• 多数管理路由仅接受同源请求，响应使用 no-store，且不在日志中记录请求头。
• 会话开关状态仅保存在插件进程内存中，重启 DSH 后所有会话恢复默认开启。
• 关闭只对之后的 agent step 生效：历史消息里已注入的 OpenViking 上下文在被压缩前仍留在该会话中；关闭期间官方插件此前排队的待提交写入仍可能由其全局恢复逻辑补发。本插件不启动、停止或修改 OpenViking 服务端，也不替换官方记忆插件。
• 跨主题共享开关只写官方声明的 plugin.recallPeerScope 键，保留 ovcli.conf 中的一切未知键；保存后的自动重载只经宿主 Cordis 公开机制重载官方插件使其重读配置，不修改官方代码，副作用是对打开的会话做一次提交归档并短暂重建 MCP 工具（卡片文案已提示）；自动重载未完成时只在状态行给出提示，官方插件未加载时提示手动重启 DSH。环境变量 OPENVIKING_RECALL_PEER_SCOPE 优先级更高，页面会显示其覆盖警告。
• 召回调优只写官方声明的 scoreThreshold、recallLimit、recallQueryExpansion、recallExcludeUris、timeoutMs、recallContextTimeoutMs 六个键，取值域按官方 config-schema 校验，越界或格式错误的请求被拒绝且不落盘，ovcli.conf 中的其余键（含凭据）一律保留。产品默认（scoreThreshold 0.5、recallQueryExpansion off、timeoutMs 15000）只是在首次打开配置页时写入一个官方键，不修改官方默认：文件或环境变量的取值仍然优先，尚未初始化的文件在此之前仍按官方默认运行；OPENVIKING_SCORE_THRESHOLD、OPENVIKING_RECALL_LIMIT、OPENVIKING_RECALL_QUERY_EXPANSION、OPENVIKING_RECALL_EXCLUDE_URIS、OPENVIKING_TIMEOUT_MS、OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS 优先级高于文件，被覆盖的字段只读并显示警告。
• Actor peer id 只写官方声明的 plugin.peerId 键（清理其 peer_id 旧拼写与 plugin.dsh 覆盖），保留 ovcli.conf 中的一切未知键与顶层凭据。校验仅拒绝明显非法输入（越界长度或非官方字符集），不代替服务端做进一步 sanitize。留空即删除该键、恢复官方的按会话 git 身份自动推导（不修改官方默认）；本插件不编辑顶层 actor_peer_id/peer_id 凭据键，仅在其生效时显示只读警告。OPENVIKING_PEER_ID 优先级高于文件。「填入当前仓库」只经官方 shared/workspace-peer.mjs 推导、不重写规则，官方包缺失或不在 git 仓库中时给出空建议而非报错。多仓库工作的记忆隔离应保持此字段留空，并忽略 OpenViking MCP 关于缺少显式 peer id 的日志输出。

环境要求

• Node.js >= 22
• DSH >= 0.1.6-alpha.2 < 0.3.0-0
• 一个可访问的 OpenViking 服务
• 官方 @openviking/dsh-memory-plugin >= 0.3.2（不设上限；本仓库已完整测试至 0.5.0，并对已部署的 0.5.20 逐项核对了本插件所依赖的 runtime 接口）

服务端兼容性

本插件只写 ovcli.conf 的 plugin 段，只调用数据面 /health、/ready、/api/v1/system/status 与 Admin 的 accounts/users/key 端点，不依赖任何已移除或废弃的接口，因此对 OpenViking 服务端 v0.4.22 的破坏性变更（Session used 上报接口移除、/admin/accounts/{id}/settings 与 /admin/agent-evolution 标记废弃、skills/find 返回结构调整等）无需任何适配。

唯一值得留意的语义变化（v0.4.22 #5358）：本地向量引擎（vectordb.backend = local/cuvs）的纯 cosine 分数由 [-1,1] 映射为 (cos + 1) / 2，即 [0,1]。排序不变、现有索引无需重建、服务端降级即恢复原始分数，但阈值不会自动调整。本插件的 scoreThreshold 默认 0.5 与官方默认 0.35 都是原样透传给服务端 score_threshold/min_score 的，映射后同等阈值下召回会放宽：

| 阈值 | 旧分数域（[-1,1]）含义 | 新分数域（[0,1]）含义 | | --- | --- | --- | | 0.35（官方默认） | cos ≥ 0.35 | cos ≥ -0.3 | | 0.5（本插件默认） | cos ≥ 0.5 | cos ≥ 0 | | 0.75 | cos ≥ 0.75 | cos ≥ 0.5（等价旧 0.5 的效果） |

• 要与旧版（≤ 0.4.21）保持相同的过滤强度，把 scoreThreshold 调到 0.75；
• 只用远端向量库（http/volcengine/vikingdb）或 IP/L2/稀疏融合分数时不受影响，无需调整；
• 升级后若发现弱相关内容变多，可在 0.5–0.75 之间按需微调。

OpenViking 服务端 v0.5.0

• 配置文件定位跟随官方插件：本插件读写的 ovcli.conf / ov.conf 现按官方插件 shared/credentials.mjs 的同一套链解析——OPENVIKING_CLI_CONFIG_FILE 选 ovcli.conf、OPENVIKING_CONFIG_FILE 选 ov.conf，均回退到 ~/.openviking 下的默认文件，并沿用「仅设 OPENVIKING_CONFIG_FILE 且其内容是 ovcli 形状时充当 ovcli.conf」的向后兼容。v0.5.0（#5551）把 OPENVIKING_CLI_CONFIG_FILE 定为 ov status/ov config 的统一真源，因此配置页始终编辑官方插件实际加载的那个文件，不会在设了该变量时写错文件。
• recallExcludeUris 传目录=排除整棵子树：v0.5.0（#5627）起，exclude_uris 传目录 URI 会排除整棵子树（旧版按字符串精确匹配，传目录实际什么都不排除）。本插件只把该键原样透传，键名与取值域（URI 列表）不变，无需适配；填目录时请预期其下所有条目都会被排除。
• Working Memory 默认关闭、插件 commit 归档全部消息、context 召回不再返回系统预置目录、MCP remember 返回文案变化等 v0.5.0 变更均发生在服务端或官方记忆插件内部，不触及本插件写的键或调用的端点，无需适配。OpenViking Gateway 是独立组件（独立进程、ov.conf 的 gateway 段、/api/v1/admin/gateway/*），本插件不配置、不编排网关。

开发

npm ci
npm run build       # 生成 lib/ 编译产物，不会生成 .tgz
npm test            # 单元测试 + Playwright E2E

lib/ 是随 git 分发的编译产物，改动 src/ 后必须重新构建并提交，否则从 GitHub 安装会加载到缺失或过期的入口。lib/standalone.js 仅供 Playwright 使用，不提交也不随包发布。仓库不会在构建流程中生成或保留 .tgz 安装包。

测试

npm run test:unit
npm run test:e2e

Playwright E2E 覆盖导入并保存 ovcli.conf、非法 endpoint 保护、服务端 user key 验证、临时 root key 的账号/用户选择，以及中文浏览器语言渲染。

项目结构

src/
  ovcli-config.ts       ovcli.conf 读取、校验、原子写入和权限修复
  openviking-paths.ts   跟随官方插件解析 ovcli.conf / ov.conf 的路径
  local-discovery.ts    ov.conf 非敏感发现
  openviking-client.ts  数据面连通性与身份验证
  openviking-admin.ts   官方 Admin API 适配
  manager-api.ts        DSH 同源 HTTP 路由（含会话开关）
  session-toggle.ts     会话级 OpenViking 开关的内存状态
  ov-prestep.ts         识别并剥离官方插件注入的 pre-step 消息
  ov-tool-guard.ts      关闭会话对 mcp__openviking__* 工具的拒绝
  openviking-gate.ts    对官方 OpenVikingRuntime 的按会话短路包装
  client/               DSH Web 页面、输入框开关按钮、样式和 i18n

许可证

本项目采用 MIT License。