dsh-opencontext

dsh plugin --profile web add dsh-opencontext

dsh-opencontext


为 DeepSeek Harness (DSH) agent 提供持久化记忆与检索增强上下文的插件,

基于 @melandlabs/opencontext。

• 包名:dsh-opencontext
• 协议:Apache-2.0
• Node 版本:^22.19.0 || >=24.0.0
• 工具前缀:oc_*
• 技能:opencontext
• 命令:/oc doctor

安装

从 npm 安装（推荐）

# 直接从 npm 安装
dsh plugin --profile web add dsh-opencontext

# 确认已挂载
dsh --profile web --dump-config
#   ... 应包含 `id: dsh-opencontext`

# 启动 DSH web 并验证
dsh --profile web web
#   访问 http://127.0.0.1:3080/plugins，确认 dsh-opencontext 显示 "Enabled"

从源码安装（开发用）

# 1. 进入插件目录
cd /path/to/opencontext/plugins/dsh-opencontext

# 2. 构建插件(生成 lib/)
pnpm install
pnpm build

# 3. 注册到 DSH profile
dsh plugin --profile web add /path/to/opencontext/plugins/dsh-opencontext

# 4. 确认已挂载
dsh --profile web --dump-config
#   ... 应包含 `id: dsh-opencontext`

# 5. 启动 DSH web 并验证
dsh --profile web web
#   访问 http://127.0.0.1:3080/plugins，确认 dsh-opencontext 显示 "Enabled"

功能

核心工具(8 个)

工具 · 用途

oc_search · 在长期记忆(memory + insights + knowledge)中检索。

oc_remember · 用户明确要求时,持久化一条记忆。

oc_memory_list · 列出当前作用域的近期记忆条目。

oc_memory_get · 通过 id 读取一条或多条记忆。

oc_memory_revise · 软废弃旧条目,存储新内容作为后继。

oc_memory_retire · 软废弃一条记忆。

oc_prepare_context · 手动构建一个字节受限的 <opencontext_evidence> 上下文块。

oc_capture_source · 捕获任意内容源以供后续检索。

摘要与结果工具(3 个)

工具 · 用途

oc_session_summary · 在自然断点生成并存储会话摘要。

oc_task_outcome · 记录任务结果、决策与成就。

oc_recent_summaries · 列出近期会话摘要与任务结果。

Insights 工具(2 个,可选)

工具 · 用途

oc_insights_search · 检索结构化 insights(决策、偏好、结果)。

oc_insight_capture · 从对话中捕获结构化 insight。

Knowledge/RAG 工具(3 个,可选)

工具 · 用途

oc_knowledge_search · 对已上传文档进行 RAG 检索。

oc_document_upload · 上传文档到知识库。

oc_document_list · 列出知识库中的所有文档。

所有工具成功时返回 { ok: true, value },失败时返回

{ ok: false, error: { code, message } } —— 永远不向模型抛出异常。

召回流水(Recall Waterfall)

每次 agent/pre-step 事件触发一次召回:

1. 从最后一条用户消息中提取查询(截断到 256 字符)。

2. 调用 backend.search({ query, limit: maxRecallItems, ... }),

由 requestTimeoutMs 限定超时。

3. 将命中格式化为一个带 <opencontext_evidence> 围栏的块,字节

上限为 maxBytes(默认 8000)。

4. 该块作为插件来源的用户消息追加到对话,头部明确标注为

不可信的历史证据。

5. 任何后端错误都会被记入警告日志,本轮对话继续进行。

自动捕获

第二个 agent/pre-step 监听器在召回之后执行,将每条用户消息写入

存储,标记为 sourceType: "user_input"。受 config.capturePrompts

控制(默认 true,可设 OPENCONTEXT_DSH_CAPTURE_PROMPTS=0 禁用)。

默认采用 fire-and-forget 模式,不会阻塞轮次;如需严格顺序,

可开启 flushOnCapture: true。

轮次结束摘要

开启 autoSummarize 后,turn/end 监听器会:

1. 生成当前轮次的简要摘要

2. 将其存储为 turn-summary 记忆

3. 若启用 captureToolOutcomes,同时捕获工具结果

工具结果捕获

开启 captureToolResults 后,tool/result 监听器会将工具调用结果

捕获为 tool-interaction 记忆,形成可检索的工具交互日志。

技能:opencontext

在 apply 时注册。让模型在每次会话开始时即了解召回/捕获约定、

信任模型与全部 16 个 oc_* 工具的语义。

命令:/oc doctor

输出 JSON 状态:

{
  "ok": true,
  "plugin": "dsh-opencontext",
  "backend": "lib",
  "scope": "local:9cd22c419df9",
  "db": "/Users/you/.opencontext/memory/store.db",
  "probe": { "ok": true, "mode": "lib", "details": "db=/Users/you/.opencontext/memory/store.db" },
  "recentCount": 0,
  "features": ["insights", "knowledge", "prompt-capture"]
}

配置

按以下顺序解析(优先级从高到低):

1. cordis.patch.yml 中 id: dsh-opencontext 的 config 块

2. OPENCONTEXT_DSH_* 环境变量

3. ConfigSchema 中的默认值

字段 · 类型 · 默认值 · 环境变量

baseUrl · string · http://127.0.0.1:8000 · OPENCONTEXT_DSH_BASE_URL

authorization · string · "" · OPENCONTEXT_DSH_AUTHORIZATION

scopeId · string · "" (自动) · OPENCONTEXT_DSH_SCOPE_ID

timeoutMs · number · 4000 · OPENCONTEXT_DSH_TIMEOUT_MS

requestTimeoutMs · number · 1000 · OPENCONTEXT_DSH_REQUEST_TIMEOUT

maxBytes · number · 8000 · OPENCONTEXT_DSH_MAX_BYTES

capturePrompts · bool · true · OPENCONTEXT_DSH_CAPTURE_PROMPTS (1/0)

flushOnCapture · bool · false · OPENCONTEXT_DSH_FLUSH_ON_CAPTURE (1/0)

maxRecallItems · number · 8 · OPENCONTEXT_DSH_MAX_RECALL_ITEMS

autoSummarize · bool · false · OPENCONTEXT_DSH_AUTO_SUMMARIZE (1/0)

captureToolResults · bool · false · OPENCONTEXT_DSH_CAPTURE_TOOL_RESULTS (1/0)

enableInsights · bool · true · OPENCONTEXT_DSH_ENABLE_INSIGHTS (1/0)

enableKnowledge · bool · true · OPENCONTEXT_DSH_ENABLE_KNOWLEDGE (1/0)

仅作为开关:

• OPENCONTEXT_DSH_HTTP_URL — 切到 HTTP 模式(任何非空值)。

KOL 制作期间不建议启用。

信任模型

召回块为主机提供的上下文,而非指令。块头显式标注其为不可信

的历史证据;若与用户请求冲突,以用户请求为准。该块从不进入

system-prompt 角色,而是作为插件来源的用户消息追加,模型可以在

不影响系统契约的情况下选择忽略。

开发

pnpm install
pnpm typecheck
pnpm test          # 108 个单元测试
pnpm build         # tsc → lib/

架构

┌──────────────────────────────────────────────────────────────────────────┐
│                                DSH Agent                                 │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  agent/pre-step pipeline                                           │  │
│  │  ┌───────────────────────────┐    ┌───────────────────────────┐        │  │
│  │  │  Recall                   │    │  Capture                  │        │  │
│  │  │  (search history)         │    │  (store user input)       │        │  │
│  │  └───────────────────────────┘    └───────────────────────────┘        │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                               │                                    │
│                               v                                    │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  turn/end & tool/result listeners                                  │  │
│  │  ┌───────────────────────────┐    ┌───────────────────────────┐        │  │
│  │  │  Sessi

…(truncated)