mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
71 lines
4.8 KiB
Markdown
71 lines
4.8 KiB
Markdown
# @deepseek-ai/dsh-time-context
|
||
|
||
[English](README.md) | 中文
|
||
|
||
可选的持久上下文，包含模型请求准备期间采样的带时区的当前时间与经过时长。`dsh-agent-spine-demo` 与随附示例不挂载该插件。决策记录：[持久 time-context Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md)。
|
||
|
||
## 配置
|
||
|
||
```yaml
|
||
- id: time-context
|
||
name: '@deepseek-ai/dsh-time-context'
|
||
config:
|
||
timeZone: Asia/Shanghai # optional IANA override; omit for the process zone
|
||
refreshIntervalMs: 60000 # optional; omit or set to 0 for every eligible attempt
|
||
```
|
||
|
||
省略 `timeZone` 时，插件会在加载时解析一次 Node 进程的系统时区。Node 遵循 `TZ`；如果没有该覆盖，时区由宿主或容器提供。显式 `timeZone` 必须是 IANA 标识符，并在插件加载时验证。
|
||
|
||
`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，对每次信号尚未中止的合格步骤前尝试执行追加。正数值只会在会话没有早先 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时执行追加。
|
||
|
||
## 时序语义
|
||
|
||
该插件会前置一个 `agent/step` 监听器。需要注入时，它会追加一条注入的 `user/message`，通过 `agent.inject()` 完成，时机位于 `step/start` 和普通自动压缩（compaction）之前，其源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制的尝试不追加任何内容。
|
||
|
||
正间隔调度会扫描原始持久会话事件，查找最新的上述源 `user/message`，包括已被压缩遮蔽的时间读数。因此，调度可以跨轮次以及进程恢复持续生效，不需要进程本地缓存状态。它会降低追加频率与历史增长，但绝不移除现有时间读数，且每个会话独立调度。
|
||
|
||
第 1 步从前一条模型可见消息起测量，包括开启轮次的提示词。后续步骤从同一轮次中前一个 time-context 事件起测量。两种基线都使用持久会话事件时间戳；挂钟时间倒退时，经过时长限制为零。如果第一步缺少基线，或者后续步骤因间隔抑制而没有较早的同轮次时间读数，则报告 `unavailable`。
|
||
|
||
时间读数记录的是一次请求准备尝试，不是已提交步骤或已传输请求。因为 listener 首先运行，后续的步骤前监听器取消或使该尝试失败时，该追加可能仍会保留。日志仅追加，该插件不执行回滚。
|
||
|
||
单独发布的 `./invariant` 配套模块会根据当前未结束的轮次、下一个步骤前位置、经过时长基线与持久事件时间检查每个归因于插件的时间读数。其渲染时间戳必须可解析，且不能晚于该事件；采样与追加之间的进程挂起不会使时间读数失效。
|
||
|
||
时间读数会保留在派生会话历史中，直到后续压缩遮蔽它。请求标头不含 time-context 状态。请求重建会在每个 `step/start` 处使用完整持久表层前缀，因此已传输请求无需与时间读数一一对应：失败的准备可能留下额外时间读数，而间隔抑制可让请求复用现有历史，无需添加时间读数。
|
||
|
||
## 模型体验
|
||
|
||
### 准备期时间上下文
|
||
|
||
#### 模型看到的内容
|
||
|
||
每次执行注入的准备尝试都会生成一条带源标记的上下文消息，包含下方两行。`<timestamp>` 是带数字偏移与 IANA 时区、形如 ISO 的本地时间戳；持续时间使用紧凑的整秒单位。正间隔可能使某次步骤尝试没有新时间读数。
|
||
|
||
##### 第一步
|
||
|
||
```markdown
|
||
Time sampled while preparing turn <turn>, step 1: <timestamp>
|
||
Elapsed since the preceding model-visible message: <duration-or-unavailable>.
|
||
```
|
||
|
||
##### 后续步骤
|
||
|
||
```markdown
|
||
Time sampled while preparing turn <turn>, step <step>: <timestamp>
|
||
Elapsed since the preceding step context: <duration-or-unavailable>.
|
||
```
|
||
|
||
#### Token 影响
|
||
|
||
每条注入的两行消息都会累积，直到压缩遮蔽它。正间隔会减少添加；省略或设为 `0` 则会为每次合格准备尝试添加一条。
|
||
|
||
#### KV Cache 影响
|
||
|
||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||
|
||
## 已知限制与暂缓事项
|
||
|
||
- **整秒显示**：时间戳与持续时间省略亚秒精度，尽管持久事件时间保留毫秒。
|
||
- **会话事件基线**：经过时长从持久追加时间戳起计算，而非客户端传输的原始发送时间戳。
|
||
- **进程本地默认时区**：省略设置时，使用插件加载时捕获的 Node 进程 `TZ`、宿主或容器时区，而非远程用户的时区；两者不同时，请配置显式 IANA 时区。
|
||
- **压缩之间的历史成本**：省略设置或设为 `0` 会为每次合格准备尝试保留一条时间读数，包括后续取消或失败的尝试；正间隔可以降低但无法消除该成本。
|