前言¶
在 DeepSeek Harness（DSH）里跑多会话时，内置的 @deepseek-ai/dsh-time-context 会在每轮首步注入当前时间、浏览器时区和「距上一条模型可见消息多久」。这对单窗口对话够用，但在 QQ 群、定时任务、子代理并行时，会出现两类结构性缺口：一是无法只对指定会话授时，token 会花在不需要的会话上；二是感知不到会话边界——不知道别的窗口上次活跃是多久前，也无法区分「用户主动开口」与定时唤醒、工具触发产生的消息。
dsh-session-clock 由社区维护者 xfgil 发布，归类为「记忆」类插件，定位是内置 time-context 的补充，不是替代。下面介绍它补什么、怎么装、怎么配。
这是什么¶
一句话：dsh-session-clock 给指定会话注入会话时钟行，并持久化跨轮、跨会话的空闲间隔；默认与内置 dsh-time-context 并存（mode: supplement），时间戳与时长写法与内置保持一致，两条注入放在一起不打架。
- 目录页：SkillHub - dsh-session-clock
- 源码与文档：GitHub - xfgil/dsh-session-clock
- 许可证：MIT（package.json）
- 当前包版本：0.1.1
- 支持的 DSH 版本：
>=0.2.0-rc.2 <0.3.0-0（README 开发与验证所用为0.2.1-rc.2）
与内置 time-context 的分工¶
内置插件擅长「现在几点、距上一条模型可见消息多久」；本插件不重复这些（除非你把 mode 设为 full 并禁用内置 time-context）。README 用表格归纳差异，核心增量如下：
| 能力 | 内置 dsh-time-context | dsh-session-clock |
|---|---|---|
| 只给指定会话授时 | 否 | 是（sessions / exceptSessions） |
/正则/、* 匹配会话 |
否 | 是 |
| 跨会话「任意会话上次活跃」指针 | 否 | 是 |
| 距上一次用户主动说话 | 否（只算模型可见消息） | 是 |
| 重启后间隔仍成立 | 依赖会话内事件 | 持久化到 $DSH_HOME/session-clock/activity.json |
| agent 主动查询 | 否 | session_clock 工具 |
| HTTP 状态观测 | 否 | loopback 端点 |
核心功能¶
按会话授时¶
在 profile 的 cordis.patch.yml 里用白名单、黑名单控制哪些会话会收到注入：
sessions: ['onebot-*', 'session-*'] # 白名单，支持 * 通配与 /正则/
exceptSessions: ['/^onebot-group-.*$/'] # 黑名单，优先级高于白名单
'*' 表示全部会话。非法正则会退化为字面量匹配，不会让插件崩溃。
注入内容与间隔语义¶
每条注入一行，形如：
Session clock for onebot-group-2000000002-mv40ioj5: previous user message 3d 4h 12m 9s ago; any session last active 12m 3s ago (session-36f403a5-...), turn 42.
previous user message ... ago：距上一次用户主动发言（不含注入、不含定时唤醒）。any session last active ... ago：跨会话指针，括号内为上次活跃会话 id。turn 42：本会话累计轮次。
可通过 includeUserGap、includeGlobalIdle、includeTurnCount 等配置逐项关闭子句。
持久化¶
状态写入 $DSH_HOME/session-clock/activity.json（默认 ~/.dsh/session-clock/activity.json）。写盘采用延迟合并与原子替换（临时文件再 renameSync）。DSH 重启后会话对象重建，但文件中的间隔基线仍在。
session_clock 工具¶
| action | 作用 |
|---|---|
now |
本会话（或指定 session_id）当前时间与各类空闲时长 |
list |
最近活跃会话及空闲时长（limit 控制条数） |
HTTP 观测面（仅 loopback）¶
非本机访问返回 403。常用路径：
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /session-clock |
enabled / mode / 计数 / 上次决策原因 |
| GET | /session-clock/list |
已跟踪会话及空闲时长 |
| POST | /session-clock/toggle |
开/关注入 |
| POST | /session-clock/flush |
立即落盘 |
lastDecision 可区分「本轮回跳过注入」与插件异常，例如 mode=supplement 只在首步注入时，错过首步整轮静默。
安装与启用¶
插件以当前 DSH 进程权限运行，安装前建议阅读仓库源码与 MIT 许可证。社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，本包通过 npm / 插件管理器分发。
前置条件¶
宿主需已带内置 @deepseek-ai/dsh-time-context（0.2.0-rc.2，由 @deepseek-ai/dsh-base 提供，勿在 profile 里重复挂载第二份 time-context，否则每 turn 首步会出现两条相同注入）。
Node 引擎要求：>=22（package.json）。
推荐安装¶
dsh plugin --profile <你的profile> add dsh-session-clock
装好后通常无需重启；用 GET /session-clock 查看 enabled: true 且 ready: true。若接口 404，可重启 DSH 再 reconcile 一次。
也可从 Releases 下载源码包解压后，用 dsh plugin --profile <你的profile> add link:/绝对路径/dsh-session-clock 挂链接（便于改源码配合 HMR）。
典型配置¶
在 profile 的 cordis.patch.yml 中：
- id: session-clock
name: dsh-session-clock
config:
mode: supplement
timeZone: Asia/Shanghai
sessions: ['*']
refreshIntervalMs: 60000
常用键说明（完整列表见 README）：
| 键 | 默认 | 说明 |
|---|---|---|
mode |
supplement |
只补增量；append 额外给距上一轮结束；full 复刻 time-context 三行 |
sessions |
['*'] |
授时会话白名单 |
exceptSessions |
[] |
黑名单，优先于白名单 |
refreshIntervalMs |
60000 |
同会话两次注入最小间隔（ms），0 不节流 |
skipSubagents |
true |
跳过 origin === 'subagent' 的会话 |
minGapSeconds |
0 |
空闲不足则不注入 |
timeZone 留空用进程时区；进程为 UTC 或取不到、或配置非法时，落到 fallbackTimeZone（默认 Asia/Shanghai），插件不会停摆。
与 time-context 共存（默认）¶
不要改动 profile 里已有的 time-context 条目。若要用本插件整体替代内置 time-context：
- 在
cordis.patch.yml给- id: time-context加disabled: true； - 本插件设
mode: full。
适用场景与注意¶
适合：多通道（如 QQ onebot）、定时唤醒与人工对话混跑、需要「用户多久没主动说话」或「别的会话上次活跃」的 agent；需要重启后仍准确的空闲间隔；只想对部分会话授时以省 token。
注意：
- 每轮只在首步注入一条（
supplement），与内置 time-context 节奏一致。 - 删除
activity.json会清空所有间隔记录。 webServer可选；没有 HTTP 服务时注入仍工作，只是没有观测面。- 零额外 npm 运行时依赖，仅用 Node 内置模块与插件自带
time.js/store.js。
结尾¶
dsh-session-clock 在不动内置 time-context 的前提下，补上按会话开关、跨会话指针、用户主动发言间隔与持久化四类能力，并暴露 session_clock 工具与 loopback HTTP 便于排查。需要细节时以 README 为准。
- 目录页：https://www.skillhub.cn/plugins/xfgil/dsh-session-clock
- GitHub：https://github.com/xfgil/dsh-session-clock
