# 上下文缓存使用说明

## 开始使用

1. 完全退出 DeepSeek Harness（包括托盘），再打开。插件安装在桌面端 `desktop` 配置中。
2. 在输入框旁点击“上下文缓存”，按钮会显示“开”或“关”。未生成会话时可预选，下一次进入的首个未配置会话会接收该选择；已有独立设置的会话不会被覆盖。
3. 在会话导航中点击“上下文缓存”，或打开右侧同名面板。
4. 也可输入 `/virtual-context on`、`/virtual-context off` 或 `/virtual-context status`。

按钮的开关控制面板显示。插件不会自动复制整段聊天记录，也不会删除宿主消息。需要保存的内容由 Agent 调用 `vctx` 写入。

如果切换失败，会显示错误；连接超过 8 秒会提示超时，可再次点击重试。

## 设置页

打开“设置 → 上下文缓存”。显示偏好立即保存到当前浏览器；替换策略需要点击“保存替换策略”，保存在本地数据库，桌面端和同一配置的其他界面共享。

| 设置 | 含义 |
| --- | --- |
| 显示位置 | 面板总开关、会话标签页、右侧侧栏 |
| 看板内容 | 紧凑模式、换入换出记录、供应商缓存命中记账 |
| 查询事件条数 | 20–2000 条；滑块和数值框同步；记录表展示最近 12 条、曲线展示最近 60 次 |
| 自动刷新 | 默认每 2 秒；可选手动或每 2/5/10/30/60 秒；旧设置中的自定义频率也保留，最低 1 秒 |
| 轻量查看 | 100 条，手动刷新，紧凑显示 |
| 日常使用 | 200 条，每 5 秒刷新 |
| 详细排查 | 1000 条，每 2 秒刷新 |

“恢复默认”只重置显示偏好，不重置替换策略或删除页面数据。

## 替换策略

这里的“替换”是将驻留的 `working` 工作页换出到 `archive` 归档，从后续插件快照移除。正文、修订和检索能力保留。需要时使用 `recall` / `page_in` 换回。

| 模式 | 触发条件 |
| --- | --- |
| 手动替换（默认） | 在看板点击“立即替换工作页”；不自动换出 |
| 每 N 轮替换 | 收到 N 条新的用户消息后触发；同一轮的工具调用和多个模型步骤不重复计数；运行环境、工具通知及其他内部注入不计入用户轮次 |
| 达到阈值替换 | 模型步骤开始前，检查插件驻留快照占用是否达到预算的指定百分比 |
| 轮次或阈值触发 | 两者任一满足即执行 |

替换间隔范围 1–100 轮；触发阈值 10%–100%；目标占用 5%–95%，且必须低于触发阈值。每次执行后轮次计数归零。计数和最近执行结果持久保存，重启不会重置。

可选换出优先级：价值密度较低的工作页优先，或最久未使用的工作页优先。可保护最近 0–20 页工作页，默认保护 1 页；所有核心页与大纲核心索引始终保留。

例如：选择“轮次或阈值触发”，间隔 5 轮、阈值 80%、目标 50%、保留最近 1 页。达到条件时逐页归档可换出的工作页，直至低于 50% 或没有可换出的页面。如果核心页和受保护工作页本身超过目标，看板会明确显示“未达到目标”，不会删除或强制归档这些页面。

策略对同一个 namespace 的会话统一生效。切换自动模式后，在模型步骤或新的用户消息到来时检查；没有后台定时清理任务。面板关闭时策略依然有效。默认字节预算不等于模型完整上下文窗口，历史消息仍需使用宿主 `/compact` 压缩。

## 当前上下文与最近请求

看板上方的“当前实际上下文”每次查询都会调用宿主 `Session.deriveMessages()`，包含当前系统提示、用户/助手消息和工具结果，遵循宿主的消息压缩与替换。它不会只读取启动时的 `request/header` 或 `request/context`。尚未加载的会话会明确显示不可读取，需要打开或恢复对话。

“最近请求”来自插件加载后捕获的 `llm/stream` 调用，按会话隔离，显示发送时间、消息数量和内容预览。当前消息可能已经包含最近调用后新生成的回复，因此两者不同是正常现象。最近请求只保留在内存，重启后需等待下一次调用，最多保留 128 个会话；这是送入 LLM 接口的消息，不是供应商适配器转换后的最终网络报文。

预览保留完整内容的开头与结尾各 32768 字符，超长中段省略，保留最新消息可见。统计和指纹覆盖全部已过滤的消息与工具定义 JSON；不含 API Key、连接头和适配器私有回放数据。字节数不是 token 数。生成中的流式回复尚未提交到会话时，不计入当前派生消息。

默认每 2 秒刷新；旧版未设置自动刷新的偏好会迁移到 2 秒。之后可在设置中明确选“关闭”，保留手动刷新。下方“插件缓存页”是独立页存储的预算和统计，不代表模型完整上下文容量。

主导航的上下文缓存看板隐藏聊天输入框，切回聊天立即恢复。只打开右侧上下文缓存面板时仍可正常输入。

## 看板卡片

- **窗口构成**：核心前缀、大纲、工作尾部和剩余驻留预算。
- **替换策略**：当前模式、本周期轮数、累计执行次数、最近归档数量、手动替换按钮。
- **重写曲线**：每次快照变化的失效字节；绿色表示稳定前缀仍可复用。
- **缓存命中记账**：仅展示模型供应商实际返回的用量；没有真实调用时显示空状态。
- **换入换出记录**：页面名称、原因、层变化、字节数。自动策略记录为 `policy_replace`，原因是 `turns`、`threshold` 或 `manual`。

布局会随标签页和窄侧栏宽度自动调整；也可以使用“刷新看板”手动更新。

## 让 Agent 保存和找回内容

示例请求：

> 调用 vctx，operation=write，input={"title":"项目约束","content":"离线优先；数据库使用 SQLite。","tier":"core"}。

> 将阶段性结果以 working 页保存，并在切换任务时用 recall 检索相关内容。

实际工具参数的 `input` 是 JSON 字符串，例如：

```json
{"operation":"recall","input":"{\"query\":\"项目约束\",\"limit\":3}"}
```

默认数据库位于 `~/.dsh/dsh-vcontext/context.db`，设置了 `DSH_HOME` 时相对于该目录。插件默认优先寻找 Harness 已下载的 Python 运行时，然后使用系统 Python；也可设置 `VCTX_PYTHON` 或在本地 profile patch 中显式指定绝对路径。预算、数据库和解释器等宿主参数可在 `~/.dsh/profiles/desktop/cordis.patch.yml` 中覆盖，修改后重启。链接安装的仓库目录不能随意移动。