OpenViking × DeepSeek Harness 记忆插件接入指南：为 dsh 赋予跨项目长期记忆

OpenViking × DeepSeek Harness 记忆插件接入指南为 dsh 赋予跨项目长期记忆【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 为 AI Agent 提供统一的自进化上下文数据库而 DeepSeek Harnessdsh作为 DeepSeek 官方的 Agent 开发工具可以通过openviking/dsh-memory-plugin插件获得跨项目、跨会话的长期记忆能力。本文以 docs/zh/agent-integrations/17-dsh.md 为骨架结合 examples/dsh-memory-plugin 下的源码实现完整讲解该插件的安装、验证、配置、运行机制与常见问题排查让你能直接在自己的 DSH 环境中复现「每次对话自动召回相关记忆、自动捕获新内容且模型直接拿到 OpenViking 工具与openviking-memory技能」的完整链路。一、插件能做什么dsh插件以 Cordis 插件的形式跑在 DSH 进程内而非外挂 hook因此能紧密贴着会话生命周期工作安装后无需额外配置即可获得四项核心能力自动召回每个模型步骤pre-step前用当前输入做语义检索把结果作为持久消息追加到同一步骤自动捕获直接从 DSH 的事件流捕获 user、assistant 以及可选的工具结果消息待同步 token 超过阈值即 commit并保留最近十条消息在本地上下文中工具面直通模型看到的是 OpenViking 的完整 MCP 工具集以mcp__openviking__*前缀发布无需手工维护工具子集技能注入附带共享的openviking-memory技能让模型知道何时该检索、读取和写入。插件源码位于 examples/dsh-memory-plugin以 npm 包openviking/dsh-memory-plugin发布运行时没有任何 npm 依赖——它的消息结构来自deepseek-ai/dsh-llm的createUserMessage工具面来自deepseek-ai/dsh-mcp-client技能提供来自deepseek-ai/dsh-skill-filesystem这些 peerDependencies 由 DSH 自身安装无需向 profile 额外添加任何东西见 examples/dsh-memory-plugin/README.md。二、安装两种方式任选方式一统一安装器推荐DSH 与其他记忆插件Claude Code、Codex、OpenCode、pi 等共用同一个安装器。它会依次询问语言English/中文、要安装的 harness、下载源和 OpenViking 凭据每一步都是幂等的重复运行完全安全。bash (curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)GitHub 访问困难的地区可以从火山引擎 TOS 镜像运行同一个安装器或在下载源选项里选「TOS 镜像」bash (curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)选择 DSH 后安装器会询问装到哪个 profile默认web也可以用--dsh-profile name提前指定。安装完成后用一段时间开一个新会话问问之前提过的事情——它会记得。方式二手动安装配置连接写~/.openviking/ovcli.conf含url、api_key可选account/user或设置OPENVIKING_URL和OPENVIKING_API_KEY环境变量。如果使用纯本地模式http://127.0.0.1:1933无鉴权这一步可以跳过——插件默认就指向本地。把插件装进 profiledsh plugin --profile web add openviking/dsh-memory-plugindsh plugin会转发给 profile 目录下的 pnpm所以任何 profile 名都可以web是dsh首次运行时自动创建的那个。注意从源码 checkout 目录直接链接dsh plugin --profile web add ./examples/dsh-memory-plugin仅在 checkout 自带node_modules时可用因为 Node 会从源码树的 realpath 解析 bundle 的 dsh peers而不是从 profile 解析。确认 profile 已生效dsh --profile web --dump-config输出里应该能看到openviking-memory插件组。还没有ovcli.conf见部署指南 → CLI。卸载dsh plugin --profile web rm openviking/dsh-memory-plugin。三、验证启动、看注入、查召回启动dsh --profile web打开一个会话按以下三点确认插件生效上下文注入会话开头应该能看到一条 OpenViking 上下文注入形如openviking-context sourceprofile的画像块工具可见模型应该具备mcp__openviking__*工具召回生效问一句更早会话里聊过的事确认召回结果被注入。如果什么都没有设置OV_DEBUG_LOG/tmp/ov-dsh.log后查看该文件。从源码看注入发生在agent/session-start与agent/pre-step两个事件上index.mjs 中injectStartupProfile在会话启动时注入画像块agent/pre-step监听器以{ prepend: true }注册确保在其他贡献者之后追加画像与召回结果且 profile 与 recall 通过Promise.all并发执行以减少瀑布等待时间。四、工作方式事件驱动、会话映射与工具面4.1 生命周期与事件挂钩插件的apply()在 index.mjs 中注册了完整的事件监听DSH 事件插件行为agent/session-start注入 OpenViking 画像块与可用记忆索引agent/pre-step用当前步骤输入做语义检索把结果作为持久消息追加到同一步骤session/event捕获 user、assistant 及可选的工具结果消息并检查 token 阈值决定是否 commitsession/flush冲刷该会话的待写队列tools/pre-execute拦截把viking://URI 当本地路径的 filesystem/shell 调用注入选择pre-step 用户消息而非 system prompt是刻意设计DSH 的 preset 若声明了complete: true如自带的minimalpreset会在组装阶段把 persona 恢复为唯一 prompt 区块静默丢弃其他贡献——基于 system prompt 的记忆插件在这种 preset 下会无提示地丢失上下文。而 pre-step 注入让每次注入都成为可重放、对压缩可见的会话事件见 examples/dsh-memory-plugin/README.md 的设计说明。4.2 会话映射与 peer每个 DSH 会话映射为 OpenViking 中的dsh-session-id子 agent 各自拥有独立会话。对应关系由 shared/session-model.mjs 的deriveHarnessSessionId(dsh-, session.id)生成子 agent 会话可通过skipSubagentSessions: true排除匹配header.origin: subagent。4.3 MCP 工具面模型看到的工具面就是 OpenViking 的 MCP 工具集经由与其他记忆集成相同的 stdio 代理 servers/mcp-proxy.mjs 接入以mcp__openviking__前缀发布包括mcp__openviking__search、mcp__openviking__read、mcp__openviking__list、mcp__openviking__tree、mcp__openviking__grep、mcp__openviking__glob、mcp__openviking__remember、mcp__openviking__write、mcp__openviking__edit、mcp__openviking__forget、mcp__openviking__add_resource以及服务器声明的其余工具。工具列表会在服务器通告变更时重新同步因此服务器升级新增工具无需发新版 bundle。为什么不直接让 DSH 连接服务器的/mcp端点因为服务器在stateless_httpTrue时仍会以空闲 200 SSE 流响应GET /mcp一旦 MCP SDK 客户端打开这条独立流就不再解析 POST 响应tools/list永远不会返回代理自己掌握传输层不受影响见 README 设计说明。由于代理每个 profile 只起一个进程有两个直接后果actor peer 是进程级的召回、捕获、commit 仍按每个会话从该会话的工作区仓库解析 peer但工具调用携带的是启动时解析的 peer。若一个进程要服务多个工作区且需要精确归属工具调用请显式设置OPENVIKING_PEER_IDremember不是会话级的服务端 MCP 的remember写入的是服务端一个短生命周期的会话而非当前的dsh-session-id流对话本身仍由自动捕获记录。MCP 桥接mountOpenVikingMcp与技能提供者mountOpenVikingSkills在apply()中最后挂载且不阻塞等待——因为桥接会阻塞在首次tools/list上这样即使服务器连接受理但迟迟不响应也不会拖住上面所有生命周期注册见 index.mjs 注释。4.4 URI 拦截误把viking://URI 当本地路径的文件或 shell 调用会被tools/pre-execute拦截guardVikingUri并提示改用对应的 OpenViking 工具。viking://是虚拟数据库路径而非文件系统路径这一保护在 uri-guard.mjs 中实现。4.5 写入失败重放写入失败会进入共享的 OpenViking 待写队列shared/pending-queue.mjs在下次会话开始时重放replayPending。syncTurns: false时重放同样被禁用——队列中的写入会一直保留直到某个仍在写入的会话把它们排空。对应逻辑见 runtime.mjs 的initializeState与enqueuePending。五、配置详解5.1 凭证解析顺序凭证解析顺序为OPENVIKING_*环境变量 →~/.openviking/ovcli.conf→~/.openviking/ov.conf与 Claude Code、Codex、OpenCode、pi 共用同一条链路见 shared/credentials.mjs这些文件变更后会自动重载。ov.conf的server段url/host/port/root_api_key与codex段也会被读取。patch 中写的凭证优先于环境变量行为开关则优先读环境变量。环境变量默认值说明OPENVIKING_URL/OPENVIKING_BASE_URLhttp://127.0.0.1:1933服务端点OPENVIKING_API_KEY/OPENVIKING_BEARER_TOKEN—API Key以Authorization: Bearer发送OPENVIKING_ACCOUNT/OPENVIKING_USER—可信模式下的 account 与 userOPENVIKING_PEER_ID—显式指定 actor peerOPENVIKING_WORKSPACE_PEERtrue按每个会话的工作区推导 peer设为0则不发送 peerOPENVIKING_RECALL_PEER_SCOPEall设为actor可将召回限制在当前工作区OV_DEBUG_LOG—把调试日志写到该路径MCP 代理的凭证通过子进程环境传递DSH 会从继承的 env 中清洗凭证形态的变量名且子进程看不到 Cordis patch所以 mcp.mjs 的buildMcpConfig要把运行时已解析的endpoint/apiKey/account/user/peerId显式写入代理的子进程 envDSH Desktop 下还需设置ELECTRON_RUN_AS_NODE1让 Electron 以 Node 方式运行代理脚本。5.2 行为参数Cordis patch行为参数写在 profile 的 Cordis patch 条目里模板见 cordis.patch.yml- insert: - id: openviking-memory name: deepseek-ai/cordis-plugin-group group: true isolate: openvikingMemory: true config: - id: openviking-memory-runtime name: openviking/dsh-memory-plugin config: endpoint: http://127.0.0.1:1933 recallTokenBudget: 2000 scoreThreshold: 0.35 captureToolResults: false skipSubagentSessions: true commitTokenThreshold: 20000 mcpToolCallTimeoutMs: 60000所有配置项的默认值与边界约束都在 config.mjs 的DEFAULT_CONFIG与clamp*函数中定义关键参数如下参数默认值约束范围说明endpointhttp://127.0.0.1:1933—服务端点结尾多余的/会被去除recallTokenBudget2000200–50000单次召回的 token 预算scoreThreshold0.350–1召回相似度阈值recallLimit101–50召回结果条数上限recallMaxContentChars500100–5000单条召回内容最大字符数recallPreferAbstracttrue—优先返回摘要而非全文minQueryLength31–64最短查询长度低于此值不触发召回profileTokenBudget10000500–50000画像注入的 token 预算commitTokenThreshold200001000–1000000触发 commit 的 pending token 阈值commitKeepRecentCount100–1000commit 时保留在本地上下文的最近消息数captureModesemanticsemantic/keyword捕获模式captureMaxLength24000200–100000单条捕获内容最大长度captureToolResultsfalse—是否捕获工具结果消息captureAssistantTurnstrue—是否捕获 assistant 轮次skipSubagentSessionsfalse—是否跳过origin: subagent的子 agent 会话requestTimeoutMs100001000–120000普通请求超时mcpToolCallTimeoutMs600001000–600000MCP 工具调用超时syncTurnstrue—见下文「只读模式」5.3 只读模式syncTurns: false同一个config块里的syncTurns: false让该集成变成只读画像注入和记忆召回照常但什么都不再写回——不捕获对话、不 commit也不重放此前会话排入队列的写入那些写入会一直留在队列里直到某个仍在写入的会话把它们排空。源码层面runtime.mjs的capture()、maybeCommit()、dispose()均在开头检查state.config.syncTurns测试 runtime.test.mjs 的syncTurns false sends nothing用例验证了「无捕获、无 commit、无 dispose flush、无重放」的完整行为。5.4 工作区 peerpeerSource同一个config块里的peerSource决定工作区 peer 的派生方式实现见 shared/workspace-peer.mjsgit默认取仓库归一化后的originURLgitgithub.com:volcengine/OpenViking.git得到github.com-volcengine-openviking其次是仓库根路径因此同一个仓库的每个 clone、worktree 和子目录共用同一个 peer不在仓库中则完全不发送 peer在那里记下的内容进入用户级空间viking://user/you/memoriescwd恢复此前的行为——把工作目录路径中的非字母数字字符全部替换成-none完全不发送 peer。peerSource也接受模板字符串如team-{dir}或模板数组拼写错误的 preset 名不含{的裸字符串会被警告并回退到默认链避免产生一个无人预期的命名空间。注意DSH 不会读取工作区的.openviking/config.json所以写在里面的peer.id不生效要让仓库之外的目录拥有独立记忆请为它设置OPENVIKING_PEER_ID详见让一个目录拥有独立记忆。旧版基于路径的 peer 下写入的记忆仍可被召回到默认的recallPeerScope: all会扫遍用户下的所有 peer且resolveEffectivePeerId返回的legacyPeerId会让召回同时命中旧命名空间。5.5 技能注入插件通过自己的独立ctx.skills提供者includeDefaultRoots: false只挂载 skills/openviking-memory/SKILL.md不会遮蔽或复制 DSH 自带的 filesystem 技能目录。技能内容指导模型会话生命周期启动注入、任务中检索、有持久信息时写入、结束时自动捕获 commit、检索工具选择search的 context 模式优先、find快速三选、grep/glob精确匹配、写入纪律remember只用于用户明确要求保留或明确的持久事实forget是永久删除仅当用户明确要求时使用viking://URI 是虚拟路径绝不能传给 filesystem 工具。六、版本与运行前提从 examples/dsh-memory-plugin/README.md 的 Requirements 可以确认deepseek-ai/dsh需要0.1.0-rc.6或更新的0.1.x版本peer 范围止于0.2.0之前Node.js 需要^22.19.0或24需要一个可达的 OpenViking 服务器且服务器须支持viking://~home-alias召回面向调用者自身的viking://~/memories与viking://~/skills空间。自测方式在插件目录运行npm ci安装精确锁定的 dsh devDependencies、npm run check做语法与版本一致性检查、npm test运行全部单元测试live-recall.test.mjs是可选的真服务器端到端闸门用OPENVIKING_E2E1加正常凭证链启用——它通过会话 commit 存入哨兵记忆等待抽取后断言召回能取回该哨兵这是任何 stub 都无法验证的性质。七、常见问题排查现象排查方向没有注入也没有 OpenViking 工具dsh --profile web --dump-config里应能看到openviking-memory重新运行安装器或dsh plugin --profile web add …装到了错误的 profile安装器默认web用--dsh-profile name重新运行安装时报ERESOLVEdeepseek-ai/dsh-*各包预发布 tag 不同步请精确安装deepseek-ai/dsh0.1.0-rc.6安装时报包「不在 npm registry 中」pnpm 默认拒绝发布不满 24 小时的版本minimumReleaseAge。等一等或把该精确版本加进 profile 的pnpm-workspace.yaml的minimumReleaseAgeExclude召不回任何内容curl http://localhost:1933/health检查端点配置以及 prompt 是否长于最小查询长度3 个字符OpenViking 返回 401 / 403检查OPENVIKING_API_KEY可信模式部署还要检查OPENVIKING_ACCOUNT与OPENVIKING_USER串入了其他项目的记忆设置OPENVIKING_RECALL_PEER_SCOPEactor崩溃后没有 commitcommit 由 token 阈值和 teardown 触发排队的写入会在下次会话开始时重放八、延伸阅读集成能力参考各 harness 集成能力的横向对照客户端配置参考peer 派生、peer.id与工作区记忆隔离的完整说明部署指南OpenViking 服务器与 CLI 凭据的部署方式插件源码examples/dsh-memory-plugin包含全部.test.mjs行为测试共享安装器与共享库examples/memory-plugin-sharedshared/与skills/下的文件由node examples/memory-plugin-shared/sync.mjs生成【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考