前言¶
在 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
