OpenViking 记忆（DeepSeek Harness 插件）
一个可安装的 DeepSeek Harness 插件包，为 DSH 增加 OpenViking 自动召回、会话捕获、viking:// URI 保护，以及可被模型调用的记忆工具——均可通过 DSH 设置界面配置。
功能特性
- 自动召回（Auto-recall） —
agent/pre-step 使用当前步骤的输入进行检索，并追加一条持久化、带来源标注的插件用户消息。
- 用户画像注入（Profile injection） —
agent/session-start 注入 OpenViking 用户画像与可用记忆索引。
- 会话捕获（Session capture） —
session/event 捕获用户、助手以及（可选）工具结果消息，无需抓取对话记录；turn/end 在待处理令牌数达到阈值时提交。
- 离线韧性（Offline resilience） — 写入失败的内容进入
~/.openviking/pending/，并在下次会话开始时重放。
viking:// 保护 — tools/pre-execute 阻止 DSH 文件系统与 Shell 工具将虚拟 URI 当作本地路径处理。- 技能注入（Skill catalog） — 注册名为
openviking 的 DSH 技能 provider，把保存在 OpenViking 中的技能（viking://user/<space>/skills/ 与共享的 viking://agent/skills）注入进会话的 <available_skills> 目录；模型可像本地技能一样用 skill 工具按需加载完整正文。
- 记忆工具 — 15 个
viking_* 工具，涵盖检索、读写、浏览、归档展开、监视管理与技能管理（见工具）。
- 设置 — 连接身份与召回/捕获调优可在 设置 → 插件 → 插件配置（OpenViking 卡片）中实时配置。
环境要求
@deepseek-ai/dsh 0.1.5-rc.2 或更新的 0.1.5-rc.N 版本- Node.js
^22.19.0 或 >=24
- 可访问的 OpenViking 服务器
安装
从本地检出目录安装（首次使用前先运行 pnpm install && pnpm run build）：
dsh plugin --profile web add "$PWD"
或者安装已发布的包：
dsh plugin --profile web add @nextnowlabs/dsh-openviking
确认 profile 中包含该插件包：
dsh --profile web --dump-config
该包的补丁会在一个隔离了 openvikingMemory 服务的 Cordis 组内挂载运行时。
配置
OpenViking 的配置在 DSH Web → 设置 → 插件 → 插件配置（OpenViking 配置卡片，openviking 设置命名空间）中完成；未填写的字段使用内置默认值。设置变更通过运行时的重新配置路径实时生效。
下表列出全部设置字段；「界面」列为 ✓ 表示可直接在设置界面中编辑，其余字段通过设置文档或补丁 config 提供。
连接
| 字段 | 界面 | 默认值 | 用途 |
|---|
服务器端点 endpoint | ✓ | http://127.0.0.1:1933 | OpenViking 服务器基础 URL |
凭据引用 credential | ✓ | OPENVIKING_API_KEY | 保存 Bearer API 密钥的 DSH 凭据引用（环境风格名称）；密钥本体存储在 DSH 凭据存储中，不在设置文档内 |
账号 account | ✓ | (空) | 受信模式账号 |
用户 user | ✓ | (空) | 受信模式用户 |
Actor 对等节点 ID peerId | ✓ | (空) | 显式对等节点；留空则按会话工作区推导 |
请求超时 requestTimeoutMs | | 10000 | 所有 HTTP 请求的超时毫秒数 |
召回
| 字段 | 界面 | 默认值 | 用途 |
|---|
工作区对等节点 workspacePeer | ✓ | 开 | 从每个会话工作区推导 actor 对等节点 |
召回对等节点范围 recallPeerScope | ✓ | all | all 跨工作区召回；actor 仅限本会话对等节点 |
最大召回条数 recallLimit | ✓ | 10 | Pre-step 召回上限 |
召回令牌预算 recallTokenBudget | ✓ | 2000 | 每个召回块的令牌预算 |
分数阈值 scoreThreshold | ✓ | 0.35 | 最低召回分数 |
召回硬截止 recallTimeoutMs | ✓ | 6000 | 单次 pre-step 召回的硬性截止毫秒数；超时则跳过该步召回（画像与召回并行执行），避免慢/远端服务器拖住模型步 |
提交令牌阈值 commitTokenThreshold | ✓ | 20000 | 触发提交的待处理令牌数阈值 |
服务端查询扩展 recallQueryExpansion | | auto | auto 启用服务端查询扩展；off 关闭 |
召回内容最大字符 recallMaxContentChars | | 500 | 每条召回项最多展示的字符数 |
召回优先摘要 recallPreferAbstract | | 开 | 回退召回优先使用摘要而非全文 |
最小查询长度 minQueryLength | | 3 | 低于该长度不触发召回 |
画像令牌预算 profileTokenBudget | | 10000 | 会话开始时画像注入的令牌预算 |
注入画像 injectProfile | ✓ | 开 | 是否在每个会话注入 user-profile + <available-memories> 画像块；关闭后不注入，初始化也不再拉取画像（动态召回不受影响） |
技能注入 injectSkills | ✓ | 开 | 将 OpenViking 中保存的技能注入 DSH 技能目录 |
捕获
| 字段 | 界面 | 默认值 | 用途 |
|---|
逐事件同步捕获 syncTurns | ✓ | 开 | 在 session/event 上同步捕获 |
捕获工具结果 captureToolResults | ✓ | 关 | 将工具结果消息捕获进记忆 |
捕获助手轮次 captureAssistantTurns | ✓ | 开 | 将助手回复捕获进记忆 |
捕获模式 captureMode | | semantic | 捕获模式：semantic 或 keyword |
单条捕获最大字符 captureMaxLength | | 24000 | 每条捕获消息的最大字符数 |
工具结果捕获最大字符 captureToolMaxChars | | 1000000 | 每条捕获工具结果的最大字符数 |
提交保留最近条数 commitKeepRecentCount | | 10 | 提交后保留在活动会话中的最近消息条数 |
补丁还可以携带插件配置（含不在界面展示的字段，如 captureMode、requestTimeoutMs）：
- insert:
- id: openviking-memory
name: '@deepseek-ai/cordis-plugin-group'
group: true
isolate:
openvikingMemory: true
config:
- id: openviking-memory-runtime
name: '@nextnowlabs/dsh-openviking'
config:
endpoint: http://127.0.0.1:1933
recallTokenBudget: 2000
scoreThreshold: 0.35
captureToolResults: false
commitTokenThreshold: 20000
captureMode: semantic
requestTimeoutMs: 10000
行为说明
- API 密钥存放在 DSH 凭据存储：设置文档与插件配置只携带
credential 引用（默认 OPENVIKING_API_KEY）。每个 OpenViking 请求在发出前经 ctx.credentials.resolve(credential) 解析密钥并以 Authorization: Bearer 发送，因此凭据变更在下一个请求即生效，无需重启；设置界面通过 /_dsh/openviking/settings 同源路由写入新密钥，浏览器永不见其明文。
agent/session-start 通过 agent.inject() 注入 OpenViking 画像与可用记忆索引（injectProfile 关闭时不注入，且初始化不再拉取画像）。agent/pre-step 使用当前步骤的输入进行检索，并将一条持久化、带来源标注的用户消息追加到同一步骤。画像与召回上下文以会话事件进入，可重放、对压缩可见且不会进入请求头。- 画像与召回在
agent/pre-step 中并行构建，并受 recallTimeoutMs 硬性截止时间约束：慢/远端服务器超时后该步直接跳过召回（或画像），绝不阻塞模型步；画像构建在基础链路之前启动，与系统提示词装配重叠。
session/event 捕获用户、助手以及（可选）工具结果消息，无需抓取对话记录。turn/end 检查待处理令牌阈值，并在需要时提交。- 写入失败的内容进入共享的待处理队列，在下次会话开始时重放。
tools/pre-execute 阻止 DSH 文件系统与 Shell 工具将 viking:// URI 当作本地路径处理。ctx.skills 上注册名为 openviking 的技能 provider：目录发现走 GET /api/v1/skills，正文按需经 GET /api/v1/skills/{name}?include_content=true 加载。每个会话构建技能目录时都会重新发现，OpenViking 中新增/修改/删除的技能随即反映到 <available_skills>。
每个 DSH 会话都映射到 OpenViking 中的 dsh-<session-id>。由工作区推导的 actor 对等节点按会话解析，并随每个会话级请求发送。会话是惰性创建的：只有当实际捕获到消息、或有待重放的离线写入时才会在 OpenViking 中落盘，因此关闭捕获（syncTurns / captureAssistantTurns / captureToolResults 均关闭）的会话不会在服务器上留下空的会话记录。
技能注入
开启 injectSkills（默认开）后，保存在 OpenViking 中的技能会作为名为 openviking 的 provider 进入 DSH 技能目录，与本地文件系统技能共用同一套 skill 工具与 <available_skills> 机制：
- 数据来源 —
GET /api/v1/skills 返回当前用户私有技能（viking://user/<space>/skills/）与账户共享 Agent 技能（viking://agent/skills）的合并列表；同名时私有技能优先。
- 技能格式 — 与 DSH 本地技能一致：
SKILL.md 携带 YAML frontmatter（name、description，可选 tags、allowed_tools）。正文中的 frontmatter 会被剥离，仅把说明正文注入 <skill_instructions>。
- 优先级 — 排名固定为
550：本地用户技能（400–500）优先于同名 OpenViking 技能，而 OpenViking 技能仍高于内置技能（600）。
- 失败韧性 — 服务器不可达时该轮发现报告为不完整（不会把空目录当作权威结果缓存）；无技能时贡献为空，不影响会话。
用 OpenViking 的 ov add-skill ./skills/my-skill/（或 Web 端）保存技能后，新建 DSH 会话即可在技能目录中看到并加载它。
工具
该插件包注册了以下工具：
viking_search — 语义检索 OpenViking 记忆、资源与技能viking_read — 按 abstract / overview / full 读取 viking:// 内容viking_browse — 列出目录或查看 URI 元数据viking_tree — 递归列出目录树viking_write — 写入文本（replace / append / create）viking_edit — 精确字符串替换viking_grep — 按正则搜索文件内容viking_glob — 按文件名通配匹配viking_remember — 将事实记入当前会话viking_forget — 永久删除viking_add_resource — 摄入远程 URL 供检索viking_archive_expand — 展开当前会话的归档viking_list_watches — 列出监视任务viking_cancel_watch — 取消监视任务viking_manage_skill — 创建 / 更新 / 删除技能（SKILL.md 上传，同名即覆盖；可指定共享技能根）
viking_forget 与 viking_manage_skill（delete 动作）执行永久删除。调用它们的模型只应在用户明确要求删除时使用。
开发
本仓库是一个 pnpm/TypeScript 项目，lib/ 为编译产物（不随仓库提交）：
pnpm install # 安装 dsh devDependencies
pnpm run build # tsc server + tsc client + client bundle -> lib/
pnpm test # vitest run tests
pnpm run typecheck # server + client 的 no-emit 类型检查
lib/ 由 pnpm run build 生成，npm publish 的 prepack 钩子会在发布前自动重新构建。
live-recall.spec.ts 是一个针对真实 OpenViking 服务器的可选端到端门禁：设置 OPENVIKING_E2E=1 并在测试配置中填入连接凭据即可启用；否则跳过。
发布
scripts/publish.sh 负责发布到 npmjs 官方 registry：
npm run release # 发布到 npmjs（等价于 ./scripts/publish.sh）
npm run publish:dry # dry-run：构建 + 预览 tarball，不发布
./scripts/publish.sh --bump patch --push # 升级 patch 版并发布 + 推送 git tag
./scripts/publish.sh --tag beta # 发布为 beta dist-tag
注意：不要直接运行裸 npm publish。publish 是 npm 的生命周期脚本名，
npm 在上传完成后会再次执行它，导致 publish.sh 递归重入并报“版本已存在”。
统一使用 npm run release（或直接调用 ./scripts/publish.sh）。
发布前会自动检查：位于 main 分支、工作区干净（--skip-checks 可跳过）、已登录 npmjs、版本号未被占用。需要二步验证时用 -o <otp> 或 NPM_OTP 环境变量。首次发布先执行 npm login --registry https://registry.npmjs.org/。
许可证
MIT
