mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
8117f61396
# Conflicts: # packages/context/workspace-context/README.md # packages/llm/llm-retry/README.md # packages/session-persistence/session-checkpoint-policy/README.md # scripts/type-equiv.manifest.json
71 lines
4.7 KiB
Markdown
71 lines
4.7 KiB
Markdown
# @deepseek-ai/dsh-time-context
|
||
|
||
[English](README.md) | 中文
|
||
|
||
可选的持久上下文，包含模型请求准备期间采样的当前分区时间与已经过时间。`dsh-agent-spine-demo` 与已发布示例不装载它。决策记录：[持久 time-context Agent Note](../../../.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` 时，对每次信号尚未 abort 的合格步骤前尝试执行追加。正数值只会在会话没有早先 time-context 注入、墙上时间向后移动，或自最新注入起已经过至少相应毫秒数时执行追加。
|
||
|
||
## 时序语义
|
||
|
||
该插件会前置一个 `agent/step` listener。需要注入时，它会追加一条注入的 `user/message`，通过 `agent.inject()` 完成，时机位于 `step/start` 和普通自动压缩之前，其源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制的尝试不追加任何内容。
|
||
|
||
正间隔调度会扫描原始持久会话事件，查找最新的上述源 `user/message`，包括已被压缩遮蔽的 reading。因此，调度可以跨轮次和已恢复进程应用，不需要进程本地 cache 状态。它会降低追加频率与历史增长，但绝不移除现有 reading，且每个会话独立调度。
|
||
|
||
第 1 步从最新的前置模型可见消息起测量，包括开启轮次的提示词。后续步骤从同一轮次中前一个 time-context 事件起测量。两种基线都使用持久会话事件时间戳；墙上时钟向后移动时，已经过时间限制为零。如果第一步缺少基线，或者后续步骤因间隔抑制而没有较早的同轮次 reading，则报告 `unavailable`。
|
||
|
||
时间 reading 记录的是一次请求准备尝试，不是已提交步骤或已传输请求。因为 listener 首先运行，后续步骤前 listener 取消或使尝试失败时，该追加可能仍会保留。日志仅追加，该插件不执行回滚。
|
||
|
||
单独发布的 `./invariant` 配套模块会根据开启轮次、下一个步骤前位置、已经过时间基线与持久事件时间检查每个归因于插件的 reading。其渲染时间戳必须可解析，且不能晚于该事件；采样与追加之间的进程挂起不会使 reading 失效。
|
||
|
||
时间 reading 会保留在派生会话历史中，直到后续压缩遮蔽它。请求标头不含 time-context 状态。请求重建会在每个 `step/start` 处使用完整持久表层前缀，因此已传输请求无需与 reading 一一对应：失败的准备可能留下额外 reading，而间隔抑制可让请求复用现有历史，无需添加 reading。
|
||
|
||
## 模型体验
|
||
|
||
### 准备期时间上下文
|
||
|
||
#### 模型看到的内容
|
||
|
||
每次执行注入的准备尝试都会生成一条带源标记的上下文消息，包含下方两行。`<timestamp>` 是带数字偏移与 IANA 时区、形如 ISO 的本地时间戳；持续时间使用紧凑的整秒单位。正间隔可能使某次步骤尝试没有新 reading。
|
||
|
||
##### 第一步
|
||
|
||
```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`、宿主或容器时区，而非远程 user 的时区；两者不同时，请配置显式 IANA 时区。
|
||
- **压缩之间的历史成本**：省略设置或设为 `0` 会为每次合格准备尝试保留一条 reading，包括后续取消或失败的尝试；正间隔可以降低但无法消除该成本。
|