高峰自动会话门：周末模式 + 高峰自动暂停 + 官方源二维判定 + 会话级冻结 + 后端自动重试

English · 中文 · 日本語 · 한국어

dsh-session-guard

• English README
• 中文 README
• 日本語 README
• 한국어 README
• Installation guide
• 中文安装指南
• 日本語インストールガイド
• 한국어 설치 안내
• Changelog
• 日本語 changelog
• 한국어 changelog

兼容性说明： v0.1.1 已包含日语（ja）和韩语（ko）字典，但当前官方 DSH 只通过 LocaleRuntime 提供 zh 和 en。在原版 DSH 中选择 ja 或 ko 会失败，并提示 locale "<id>" is not registered。需要等待官方 DSH 增加对应 locale ID 后才能正常使用。高级用户可以维护 DSH fork 进行扩展。

▼ DSH 版本适配

DSH 版本	加载	设置注册	会话事件 / 会话门	客户端半
0.1.0-rc.7 ~ 0.1.1-rc.x	✅	ctx.settings.register(ns, schema, { base })	✅ 形状一致	✅ 无平台值导入
0.1.2-alpha.2+ / 0.1.2-rc.1	✅	register 仍保留（另加 installSection）	✅ 形状一致	✅ 无平台值导入
0.1.3+ / 0.1.5-alpha.1	接口仍在（未验证）	register 仍在（行号未变）	✅	✅

一份产物同时支持两版本。session/event、agent.cancel、goals.pause、 agent.followup、commands.register、timer.interval、webServer.register、 agent/request、llm.listConfigurableProviders、settings.register/get 在 dsh-v0.1.1-rc.2 与 dsh-v0.1.2-rc.1 之间签名一致（并已核到 0.1.5-alpha.1）； 唯一需要双读的是 tool/result 记录的调用 id 形态（content[].toolCallId 优先、 source.callId 回退），已抽到 src/tool-call-id.js 并配单测——两版本的回放日志都可能出现这两种形态。 model/selection 事件仅 0.1.2+，只做切模型加速且必须特性探测；设置面只用 register + get 交集（不碰 installSection / 已移除的 installSettingsSection）。 漂移守卫脚本：tools/check-api-drift.ps1（对四个 tag 断言必需接口存在）。

高峰时段自动暂停运行中的会话、低峰/周末自动续跑；配合 input-traffic 的冻结按钮做到会话级锁定；后端自动重试在冻结/门控期间让路。核心基于自研会话门（agent.cancel keepInbox + goals.pause + session/event 安全边界 + followup 续跑），不再依赖 dsh-task-control。

无需修改 dsh 源码、无需提 PR：dsh plugin 命令组装 + bundle patch 装配的 cordis 插件。

💡 为什么推荐：DeepSeek 已于 2026-08-17 实行峰谷计费——高峰时段（北京时间 9:00-12:00、14:00-18:00）单价为闲时（含午间、夜间、周末与节假日）的 2 倍。本插件在高峰自动停住运行会话、退峰自动续跑，错峰长跑最多可省 50%；手动冻结（配 input-traffic 按钮）可进一步按会话精确控停。

功能一览

• 周末模式：识别周末（基于配置时区 Intl.DateTimeFormat，不踩裸 getUTCDay() 的北京边界 8 小时 bug）→ 周末无视峰谷、畅快跑。
• 高峰自动暂停（全局）：进入高峰（且非周末）时，对所有 running root session 自动暂停；退峰自动恢复全部——全局开关，无需手动。
• 官方源二维判定（providerGuard）：高峰期只在请求目标是 DeepSeek 官方源时才拦；用本地/第三方 provider（如 local-35b）照常跑，不受高峰门影响。判定口径 = 显式 id 名单 → baseURL 端点 → catalog 默认端点 → 内置 id。
• 请求级兜底 + 延后队列：入峰后才启动的会话、会话中途被切到官方源的情况，由 agent/request 请求级守卫拦住（默认 hold：请求挂起不报错，退峰自动放行）。
• 会话级冻结 / 恢复：sessionGuard 冗余端口 + POST /session-guard/rpc，input-traffic 冻结按钮逐会话透传接入；也提供 /pause /resume /cancel 手动命令。
• 后端自动重试（D9）：turn/end 瞬时失败（error/429/max-tokens）自适应退避自动续跑；永久失败停止；冻结/门控期间让路，绝不绕过会话门。
• fail-open：自研会话门不可用、session-guard 未装、设置服务缺失——均静默降级，绝不因依赖而崩。

界面预览

实际运行截屏（Windows，dsh web）——周末模式激活状态：

安装

dsh plugin --profile web add github:<owner>/dsh-session-guard

装后重启 dsh web 并刷新页面。

设置（设置 → 插件 → session-guard，简单开关）

附属配置：

• timezone（默认 Asia/Shanghai）——周末判定和徽标显示用的时区；不影响峰谷判定（峰谷固定按北京时间）；
• peakWindows（默认 09:00–12:00 / 14:00–18:00）——按北京时间（UTC+8）的峰谷窗口，与 DeepSeek 官方计费一致；
• pauseMode（safe/force）、pauseReason（wait/stop）——暂停推进方式；
• stepGateTimeoutMs（默认 300000）——step 门挂起超时；到期释放门并升级为回合级暂停（防死锁，不会形成「每 5 分钟一个 step」的 token 滴漏）；
• 官方源判定：officialProviders（追加官方 provider id，逗号分隔，优先级最高）、officialBaseURLs（官方端点 host 名单，默认 api.deepseek.com）；
• 延后队列：deferredMode（hold 挂起等待 / error 报错并延后）、deferredResumeText（退峰续跑文案）、deferredMaxHoldMs（挂起上限，默认 6 小时，到期转 error）；
• 重试参数：retryText、retryGraceMs、retryCooldownMs、retryBackoffFactor、retryBackoffMaxMs、retryMaxConsecutive。

行为

高峰自动门（全局）

• 入峰（且非周末）：stepLevelPause 开启时不再立即掐断回合——会话自然跑到下一个 agent/pre-step 边界由 step 门拉门（见下节）；关掉则对所有 running root session 调 gate.stopNextTurn（自研会话门真暂停，或按 queueFallback 回退锁等待队列）；
• 退峰 / 周末：先 releaseAll 放行被挂起的 step（回合原地续跑），再 gate.resume 全部会话——受 offPeakAutoResume 开关控制，关掉则退峰不自动恢复；
• 峰谷时区：固定使用北京时间（Asia/Shanghai），与 DeepSeek 官方计费基准一致，不受 timezone 配置影响；
• 状态机：单实例 NORMAL ↔ PAUSED_PEAK（scheduler.js），由单一 30s tick 驱动。

step 级门控（v0.2.0，省 token 的关键）

挂在 agent/pre-step waterfall 上：在下一个 step 的模型请求发生之前把回合挂起。

• 拉门条件（全部满足）：enabled + stepLevelPause + step > 1 + 高峰（北京时间，非周末）+ 目标 provider 属官方（providerGuard，关闭时全部拦）+ 该会话未被请求级 hold + 本峰内未被手动跳过；
• 为什么 step > 1：一个回合的第 1 个 step 由请求级守卫覆盖，两道门不重叠；
• 释放路径：①「⏸ 暂停中（继续）」按钮 / POST /session-guard/rpc {action:'stepResume'} / /resume → 放行当前 step，且本高峰内不再拦该会话；② 退峰 → 全部放行，回合原地续跑（不需要 followup）；③ 冻结按钮 / /pause / /cancel → 释放门并转入回合级暂停；④ signal abort（用户取消）→ 释放门；
• 超时升级：挂起超过 stepGateTimeoutMs（默认 5 分钟）→ 释放门并升级为回合级 force 暂停，退峰统一恢复（不会卡死，也不会在高峰形成 token 滴漏）；
• 状态：GET /session-guard/state?session=<id> 返回 paused: { step, turn } 与 stepGate: { held, since, bypass }；服务端口 state() 的 paused 仍是布尔（向后兼容），step 态用 pausedStep；
• 不落盘：挂起的是进程内 Promise，重启即失效（避免幽灵状态）。

暂停会话 / 继续会话按钮（session-guard 提供）

输入区右侧的「暂停会话」按钮（slot conversation.input.right，id session-guard-pause，order 20，排在 input-traffic「❄ 冻结追加」左侧）：

• 未暂停 → 「暂停会话」，可点：点击调 stepPause，在下一次 step 的模型请求之前暂停该会话（不打断当前 step；step 1 也拦，不受峰谷 / provider 限制）；
• 已暂停 → 「继续会话」，点击调 stepResume：放行当前 step，且本高峰内不再拦该会话；
• 事件推送：GET /session-guard/events?session=<id>（SSE）在 step 门状态变化时即时推送——高峰期自动拉门后按钮立刻变「继续会话」，无需等轮询；另每 10 秒轮询 /session-guard/state 兜底（SSE 不可用 / 断线时仍能收敛）；
• 样式与同一行的 input-traffic 按钮对齐（24px 高 / 6px 圆角 / 12px 字号 / 同一套 CSS 令牌），悬停与暂停态都有对应视觉反馈。

会话锁定（冻结）

• 冗余端口：ctx.provide('sessionGuard', service)——stopNextTurn(sessionId) / resume(sessionId) / lockQueue(sessionId) / unlockQueue(sessionId) / state(sessionId)；
• RPC 桥：POST /session-guard/rpc { action, sessionId }——input-traffic 冻结按钮按 sessionId 逐会话调用 stopNextTurn / resume；本插件未装则静默跳过（D8 fail-open）；
• 手动命令：/pause [force|safe] [stop|wait]、/resume [confirm] [rerun|skip]、/cancel——作用于调用它的会话（取 invocation.agent.id）。

后端自动重试（D9）

监听 turn/end，将失败分类：

• 瞬时失败（error/429/max-tokens 等）→ 自适应退避自动 followup(retryText) 续跑；
• 永久失败（鉴权/余额/模型/上下文超限）→ 停止；
• 冻结/门控期间让路：isFrozen(sessionId) 为真（queueLocked / paused / taskControl paused）时不重试；
• 用户介入或成功回合重置连续失败计数。

状态徽标（前端展示）

输入区右侧显示一个纯展示状态徽标，实时反映当前所处阶段：

• 轮询：每 15 秒请求 GET /session-guard/status，获取全局 phase、providerGuard、held、deferred、stepHeld；
• fail-open：路由不可达、网络错误、或 enabled 关闭时→ 徽标静默隐藏，不影响任何会话；
• 独立于 input-traffic：徽标由 session-guard 客户端独立渲染，不需要安装 input-traffic 插件即可显示。input-traffic 只负责冻结按钮，与徽标无依赖关系；
• tooltip：悬停显示 阶段 · 时区 · 周末模式 · 判定口径 · 挂起/延后/step 挂起数量。

官方源判定口径（providerGuard）

高峰期不是无差别停会话，而是先判断「这次请求真正要去的路由是不是 DeepSeek 官方源」：

• 端点优先于 id：同名 deepseek-official 但把 baseURL 指向中转的配置不会被误拦；反过来，pi-ai 内置 deepseek 路由的默认端点就是官方 API，不会被漏拦。
• 端点来源：ctx.get('llm').listConfigurableProviders() 找目录条目 → ctx.settings.get(settingsNs) 按 settingsPath 读 baseURL（只读非密字段，绝不读 apiKeyEnv 的值）。每次请求实时算、不缓存 → provider 配置热改立即生效。
• 目标转非官方即恢复：高峰暂停后把该会话切到本地/第三方 provider（0.1.2+ 的 model/selection 事件）→ 自动恢复该会话（受 deferredResume 约束）；只恢复本插件因入峰暂停的会话，不会碰用户手动 /pause 的会话。0.1.1 无该事件 → 退化为「下次请求或手动 /resume」。
• 取不到端点：llm 服务缺失、命名空间结构变化、字段非字符串——一律降级为 id / 内置端点判定并记 matchedBy，绝不抛出。
• 排查误判：GET /session-guard/provider?provider=<id> 返回 { official, matchedBy, endpoint }。

请求级守卫与延后队列

• 为什么要请求级：30s tick 只在 NORMAL → PAUSED_PEAK 跳变时处理当时 running 的会话；入峰后新启动的会话、会话中途切到官方源的情况都会漏。agent/request waterfall 是每次请求都过的兜底。
• 判定基于 next() 的返回值：模型选择中间件会在 waterfall 内把 provider/model 覆盖成 UI 里选的值，所以必须先 await next() 再判定。
• hold 模式（默认）：请求挂起、不发出也不报错，退峰瞬间自动放行（msUntilOffPeak 精确定时，30s tick 兜底）；用户取消（abort）则正常中断。
• error 模式：抛可识别的 PEAK_DEFERRED 错误 + 记入延后队列，退峰按 deferredResumeText 续跑（deferredResume 关闭则不自动继续）。
• 上限保护：deferredMaxHoldMs（默认 6h）到期仍未退峰 → 转 error，避免无限挂起。
• 互斥铁律：hold 期间不会再调会话门暂停（暂停要等安全边界，而请求被挂住就永远到不了安全边界 → 双方互等）。入峰时已挂起的会话会被跳过。
• 不持久化：延后队列是进程内 promise，重启即消失。

边界（明确不做）

• 不换 provider / 不做转接：只拦不路由；
• compaction 不走 agent/request：会话被暂停时不会发生压缩；高峰期间若手动触发压缩仍可能打官方源（本插件不拦 ctx.llm.stream 层）；
• 0.1.1 没有 model/selection 事件：切到非官方源后的自动恢复退化为「等下一次请求或手动 /resume」（0.1.2+ 立即生效）；
• 不新增 npm 依赖、不读写凭据、不动 dsh-llm-retry 的 429 / 传输层重试。

时区处理与校验

• 时区判定基于 IANA 时区名（如 Asia/Shanghai、Asia/Tokyo、Asia/Seoul），通过 Intl.DateTimeFormat 投影为配置时区的墙钟，不依赖裸 getUTCDay()——避免北京时区 UTC+8 边界错 8 小时的经典 bug（周六 00:30 北京时间，UTC 还是周五）；
• Intl.DateTimeFormat 本身即为校验层：传入无效时区名（如 Foo/Bar）会抛 RangeError，被外层 try-catch 静默降级为默认时区 Asia/Shanghai（fail-open）；
• 峰谷窗口为左闭右开 [start, end)，支持跨午夜窗口（如 22:00–06:00）；
• timezone 配置项对所有语言（中/英/日/韩）通用——Intl.DateTimeFormat 的 IANA 时区名不依赖 locale，日文/韩文界面下时区行为与中文完全一致。

与 input-traffic 的分工：一个「停」，一个「排」

两者作用在同一条链的不同环节，边界由 DSH 自身的 inbox 模型决定：

用户输入 ──(input-traffic 定档)──▶ next-step / next-turn 两条待处理队列
                                        │
                          agent/pre-step ──(本插件 step 门)──▶ 放行 / 挂起
                                        │
                            agent/request ──(本插件请求级 hold)──▶ 放行 / 挂起
                                        │
                                     模型调用

DSH 的队列语义（两条队列，别记混）

Inbox.claim() 永远先取光 next-step，只有该次边界要开新回合时再额外取 1 条 next-turn；一个 turn 的第 1 个 step 取 next-turn，之后都取 next-step。

职责划分

• session-guard = 停：只决定「何时可以推进」，不碰队列内容与顺序。
  • step 门（agent/pre-step）：在下一个 step 的模型请求之前挂起；
  • 回合级暂停（agent.cancel({keepInbox:true}) + goals.pause + 安全边界）：停掉当前回合，队列原样保留；
  • 请求级守卫（agent/request hold）：挂起这一次模型请求。
• input-traffic = 排：只决定「用户输入进哪条队列、什么档位、何时被消费」。
  • 三档 = 往哪条队列放：红「打断」先 cancel() 再 steer；黄「插话」steer（→ next-step，同 turn 的下一步）；绿「排队」留在 next-turn；
  • 冻结 = 把 queued + steering 行整体摘出（保留档位）+ composer block + 调 sessionGuard.stopNextTurn；恢复 = 清 block → 先 sessionGuard.resume → 按档位重投。

相遇点上的两条铁律

1. 冻结必须让本插件先释放 step 门：step 门挂在 agent/pre-step，而回合级暂停在等安全边界事件——两者互等（本插件 pauseTask / cancelTask 已先 release）；
2. step 门挂起时消息已被取走：preStep() 先 inbox.claim() 再派发 waterfall，所以挂起期间新输入排在被取走的那批之后；keepInbox 只作用于回合级暂停。

不会互相越界：input-traffic 不监听 agent/pre-step / agent/request（唯一例外是「打断」档显式 cancel()，那是用户主动要求打断）；本插件也不改写 next-step / next-turn 的内容与顺序。

按钮上：本插件的「暂停会话 / 继续会话」（order 20）与 input-traffic 的「❄ 冻结追加 / 恢复追加」（order 30）并列显示、互不取代——前者控 step 门，后者控队列摘除 + 回合级冻结。

冗余端口 sessionGuard

{
  stopNextTurn(sessionId, opts),  // 停掉 session 下一回合（自研会话门 / 回退锁队列）
  resume(sessionId, opts),        // 恢复（confirm + choice: rerun|skip）
  lockQueue(sessionId, reason),   // 显式锁队列
  unlockQueue(sessionId),         // 显式解锁
  stepPause(sessionId),           // 手动请求 step 级暂停（下一次 pre-step 边界拉门，step 1 也拦）
  stepResume(sessionId, opts),    // 解开 step 门（v0.2.0）；opts.bypass=false 时不置本峰跳过
  state(sessionId),               // { queueLocked, lockReason, paused, pausedStep, stepHeldSince, stepBypass, taskControlAvailable, taskControl }
}

HTTP 路由

• GET /session-guard/state?session=<id> — 会话状态（含 paused: { step, turn, manual } / stepGate / 最近目标 / 是否挂起 / 是否延后）
• GET /session-guard/events?session=<id> — SSE：step 门状态变化即时推送（按钮据此更新）
• GET /session-guard/settings — 设置 + taskControl 可用性
• GET /session-guard/status — 全局当前阶段（状态徽标轮询；含 stepHeld）
• GET /session-guard/provider?provider=<id> — 官方源判定诊断（official / matchedBy / endpoint）
• GET /session-guard/diag — 运行时诊断（含 stepGate）
• POST /session-guard/rpc — { action: stopNextTurn|resume|lockQueue|unlockQueue|stepPause|stepResume|state, sessionId }

状态存储

每会话 JSON：$DSH_HOME/.dsh/session-guard/<sessionId>.json（原子写；DSH_SESSION_GUARD_STATE_DIR 可覆盖）。

测试

npm test   # node --test tests/*.test.mjs（时区/周末/状态机/会话门/桥接/重试）

模块

License

MIT — 见 LICENSE。