错峰运行 lion231226/dsh-peak-hours

dsh-peak-hours

DeepSeek Harness（dsh）的运行时段开关：在对话框模式按钮右侧加一个控件，让 dsh 要么全天运行，要么只在空闲时段运行；选后者时，所有任务（包括正在运行的任务）在进入高峰时段时自动暂停，回到空闲时段自动继续。

English documentation: README.md

运行时段规则

空闲时段就是价格减半的时段。高峰时段（北京时间 UTC+8）为：

| 时段 | 相位 |
| 周一至周五 09:00–12:00、14:00–18:00，不含中国法定节假日 | 高峰 |
| 其余全部：00:00–09:00、12:00–14:00、18:00–24:00、周末全天、法定节假日全天 | 空闲 |

调休上班的周末仍算空闲——规则只看"星期 + 是否法定节假日"，不引入调休表。

安装

方式一：dsh CLI

dsh plugin --profile web add github:lion231226/dsh-peak-hours

插件是纯 JavaScript、无构建步骤、无运行时依赖，源码安装即可用。仓库的 Release 里也附了预构建 tarball（dsh-peak-hours-0.1.1.tgz），插件市场会优先用它。

方式二：install.ps1（运行中的桌面端，热生效，不需要重启）

在仓库根目录执行；profile 默认取 $env:DSH_PROFILE powershell -ExecutionPolicy Bypass -File .\install.ps1 powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall

脚本做四件事：清理历史诊断目录；把包复制进 %DSH_HOME%\profiles\<profile>\node_modules\dsh-peak-hours；在 profiles\<profile>\cordis.patch.yml 里维护一个带标记的 insert 行（写前先用 js-yaml 校验，非法 YAML 一律拒绝写入——补丁文件一旦损坏，整个 profile 会停止 reconcile，后续任何改动都不再生效，只能重启恢复）；然后轮询 /api/peak-hours/health 确认插件真的起来了。

两种安装方式不要混用。 dsh plugin add 会把包登记为 profile bundle，由 bundle 层贡献它自己 cordis.patch.yml 里的 patch 行；install.ps1 则是手工往 profile 的 patch 文件里写这一行。
对一个已登记 bundle 的 profile 再跑本脚本，会留下两条同 id 的 entry——补丁应用与 cordis Loader 都不做去重（dsh-app-boot 的 insert 是直接 push，cordis-plugin-loader 没有重复检查），重启时有真实风险。脚本现在检测到这种情况会直接拒绝执行。

让一个已存在的 entry 真正生效：三条硬条件

运行中的 Loader 对"已经 failed 的 entry"不会自动重试，而 Node 的 ESM 模块缓存按 URL 生效、在进程生命周期内不失效。所以下面三条必须同时满足，插件才会真正挂载（这也是 install.ps1 第二阶段会自动换一个 row id 的原因）：

1. 入口契约：apply() 必须 resolve undefined（或返回一个 disposer 函数）。cordis 会把插件
apply() resolve 出的值当作 effect 清理句柄，返回其它对象会抛 TypeError: Invalid effect
（cordis 的 safeCollect，经 Fiber._reload）→ fiber 变 failed、什么都不注册。
内部的 surface 由另导出的 mount() 返回给测试用。
2. 新的模块 URL：改了源码后要让 Loader 真正重新求值，必须让模块 URL 变化——最稳的是换一个包目录，原地改文件跑的还是缓存里的旧模块。
3. 新的 row id：fiberPhase: "failed" 的 entry 用同一个 id 改配置不会重新 apply；重激活要换一个 row id（install.ps1 第二阶段会写成 peak-hours-<时间戳>）。

排查入口：plugin_manager list_plugins 找 include:<row id> 的 fiberPhase （active 正常 / failed 需要按上面三条重激活 / null 表示模块还没被解析到）。

界面

* 按钮挂在 composer 工具行的 conversation.input.left 槽位。运行时渲染顺序是
[＋] [模式按钮组：权限 + 计划] [本按钮] …，所以它紧贴模式选择按钮右侧
（依据：dsh-client-ui-conversation/lib/client.js:17492-17525）。
* 三种状态：

| 状态 | 按钮文案 | 状态点 |
| 全天运行 | 全天运行 | 中性 |
| 空闲时段 · 当前空闲 | 空闲时段 · 运行中 | 绿 |
| 空闲时段 · 当前高峰 | 空闲时段 · 已暂停 | 琥珀 |

* 弹层：两个模式选项、当前北京时间、下次切换时间 + 每秒倒计时、今日节假日、未知年份告警、时钟覆盖提示。
* 队列横幅：处于「仅空闲时段」且当前是高峰时，输入卡片上方出现一行提示，写明已排队的任务数与「将在 12:00:00 自动开始」，倒计时每秒本地跳动。不满足条件时完全不占位。
* 状态数据来自宿主路由：常规 15 秒轮询，边界前后 30 秒自动降到 3 秒；页面重新可见时立即刷新。
跨越边界后客户端会本地翻转相位，倒计时改为「正在刷新…」，不会显示负数。
* 说明：dsh 执行任务期间整个工具行会被框架隐藏（hidden: activity），这是官方行为，不是本插件造成的。

暂停/恢复是怎么做的

宿主半边只在 idle-only 模式下拦两道 waterfall，always 模式下完全不介入：

1. agent/pre-step（主闸门） —— 每一次模型调用之前。等待期间收到 abort 会向上抛，正是宿主
signal.throwIfAborted() 期望的控制流（dsh-agent-loop/lib/index.js:905,911-919）。
2. tools/pre-execute（步内闸门） —— 每个工具真正执行之前，负责"一步跑到一半就进入高峰"的情况。
abort 时返回宿主设计的 { kind: 'cancel' } 而不是抛异常（抛异常会被判为 scheduler failure 并让整步失败， dsh-tools/lib/index.js:3225,3236-3240）。

闸门语义：空闲相位进入 → 立即放行、不登记 waiter；高峰相位进入 → 登记 waiter，用一个计时器精确指向 nextTransition.at，到点重新评估并释放全部 waiter（不做高频轮询）。任务在 08:59:59 放行后，其下一次落在 09:00:00 之后的闸门检查就会被扣住——这就是"运行中的任务进入高峰自动暂停"的真实路径。

llm/stream 有意不拦：它返回 AsyncIterable 而非 promise，且宿主存在绕过它的调用路径
（preparedCall?.stream()）；主闸门已覆盖每次模型调用前、工具闸门已覆盖步内边界，多包一层只会增加风险。

等待期间什么都不丢：消息与工具调用都在会话日志里，不会发出模型请求，而且等待是可 abort 的（点停止即刻取消）。

HTTP 接口（回环，无需 GUI token）

运行模式是按会话的：每个会话有自己的选择，任务按"它属于哪个会话"判定；没有单独设置的会话跟随 default。

| 方法 | 路径 | 说明 |
| GET | /api/peak-hours/health | { ok, plugin, version } |
| GET | /api/peak-hours/state?session=<id> | 状态信封（见下）；不带 ?session= 时报 default |
| POST | /api/peak-hours/mode | { "mode": "always" \| "idle-only" \| null, "session"?: "<id>", "scope"?: "session" \| "default" }；mode:null + 会话 = 清除该会话的覆盖项；两者都不带则写 default。要求 Content-Type: application/json |
| POST | /api/peak-hours/clock | { "offsetMs": <int\|null>, "ttlMs"?: <int> }，ttlMs 上限 30 分钟 |

{ "ok": true, "state": {
"mode": "always", "defaultMode": "always", "modeSource": "session",
"sessionId": "session-abc", "phase": "idle", "reason": "off-hours",
"now": 1791541815888, "nowText": "2026-10-09 18:30:15",
"nextTransitionAt": 1791766800000, "nextTransitionText": "2026-10-12 09:00:00", "nextPhase": "peak",
"msUntilTransition": 224984112, "paused": false,
"waitingTasks": 0, "waitingTasksTotal": 0, "waitingTasksUnresolved": 0,
"holidayToday": null, "holidayCoverage": "known", "unknownHolidayYear": null,
"timeZone": "Asia/Shanghai (UTC+8)", "peakWindows": ["09:00-12:00", "14:00-18:00"],
"clockOverride": null, "config": { "allowClockOverride": true } } }

clockOverride 是测试/演示用的时间偏移（把"现在"伪装成任意时刻，用来验证暂停/恢复），必须带 TTL 自动过期——否则伪装成高峰后，被扣住的任务（包括发起测试的会话）可能要一直等到真实空闲窗口。
设 DSH_PEAK_HOURS_ALLOW_CLOCK=0 可整体关闭该接口；它动的是全宿主的时钟，所以 ttlMs 有 30 分钟上限。

waitingTasks 数的是?session= 指定的那个会话；不带该参数时数整个宿主——老的不带 session 的
curl 示例因此保持原义。waitingTasksTotal 恒为全宿主数。waitingTasksUnresolved 是"会话解析不出来"
的等待者数量：它们按 default 判定，这个计数存在的意义是让解析失败可见，而不是看起来像"没有任务在等"。

节假日数据

* 内置 2025（28 天）、2026（33 天）国务院办公厅放假安排，逐日列出；调休上班日不在集合内。
来源（含逐条原文）见 lib/core/holidays.js 的 HOLIDAY_SOURCE_DETAIL，主源为 gov.cn 政策库/国务院公报，并有新华社/人民网/光明网交叉核对。
* 2027 年通知尚未发布：该年走 holidayCoverage: "unknown" + unknownHolidayYear: 2027，当日按非节假日处理（工作日窗口内仍是高峰），界面会显示告警。发布后补一行数据即可。
* 自定义：createCalendar({ extra: { '2027-01-01': '元旦' } })，extra 优先且不受 years 约束。
* 两个官方口径提醒：2026 年中秋（9/25–27）与国庆（10/1–7）是两个独立假期；2025 年国庆+中秋为 8 天连休。

配置

插件行可带 config（默认值即可用）：

| 键 | 默认 | 含义 |
| allowClockOverride | true | 是否允许 POST /api/peak-hours/clock |
| version | 读 package.json | /health 上报的版本 |

每个会话的选择持久化在 %DSH_HOME%\peak-hours-state.json： { "version": 2, "default": "always", "sessions": { "<sessionId>": "idle-only" } }（原子写 + 写入串行化）。
旧格式 { "mode": ... } 在首次读取时迁移：该值成为 default、sessions 为空；文件损坏则回退 always + 空表并只记一条日志。会话表上限 500 条，淘汰"最久未被写入"的一条，每次淘汰记一条日志。
卸载时全部监听器、计时器、路由随 fiber 一起释放，不留残留。

从 0.1.x 升级

运行模式原本是全宿主单值，现在改为按会话，旧值成为 default——所以升级后，所有没有单独设置过的会话行为与升级前完全一致。有两点要知道：

* 安装后请刷新页面。 仍运行 0.1.x 客户端的页面发的是裸 {mode} 写，新宿主会正确地把它读作"写 default" ——也就是说旧 bundle 会复现本次修复的那个缺陷本身。
* 降级会丢 sessions。 0.1.x 不认识 sessions 表，会把文件按旧格式整体重写；回退版本前请先备份或删除 %DSH_HOME%\peak-hours-state.json。

已知边界

* 已经发出的一次模型调用不会被打断，任务在下一个安全边界（下一次 pre-step 或下一次工具执行前）暂停。
* 终端里的后台进程 / job_ 后台 shell 不是 agent 步进，不受闸门影响（需要时请自行暂停）。
高峰期间提交的消息不会被丢弃，只是被扣住，回到空闲时段自动继续。

测试与验证

node --test # 作者套件 + 独立验证套件
node --test "test//.test.mjs" # 作者套件（core 排期内核 / host 闸门与路由 / client）
node --test "verify//.test.mjs" # 独立验证套件
node tools/smoke-host.mjs # 宿主半边对假 ctx 的真 HTTP 冒烟
node tools/show-monday.mjs # 打印某一天的相位分段

verify/ 里的独立验证套件按同一份契约另写一遍：节假日逐日核对（对照国务院通知原文）、一秒分辨率的边界矩阵、转移函数的性质测试、假时钟下的闸门语义、对抗用例、客户端 bundle 检查，以及在真实 cordis 运行时下挂载插件的 harness。逐条命令与原始输出见 verify/EVIDENCE.md，接口契约与设计裁决见 SPEC.md。

Node 24 下 node --test <目录> 会把目录当模块解析并失败，请使用上面的 glob 形式。

实测结论（2026-10-09，运行中的桌面端 dsh 0.2.0-rc.2）

| 项目 | 结果 |
| 全量 node --test | 403 / 403 通过（core 58 + host 94 + client 148 + 独立验证 99 + 其他 4） |
| 宿主冒烟 node tools/smoke-host.mjs | SMOKE OK（真 HTTP + 假 ctx，含入口契约回归） |
| 真机健康检查 | GET /api/peak-hours/health → {"ok":true,"plugin":"dsh-peak-hours","version":"0.1.0"} |
| 真机暂停 | 用时钟覆盖把"现在"设为 2026-10-12 09:10（高峰）→ phase:"peak"、paused:true、waitingTasks: 2，持续 6 秒仍持有 |
| 真机准点恢复 | 边界前 2 秒仍 waitingTasks: 2，模拟时间跨过 12:00:00 的瞬间变 waitingTasks: 0、phase:"idle" |
| 行为侧证据 | 后台金丝雀任务在被扣住约 10 秒后自动继续，4 步全部跑完 |
| 客户端挂载 | conversation.input.left 出现 occupant {id:"peak-hours", order:20, active:true}；队列横幅挂在 conversation.input.dock，order:30 |
| 真实时钟验证（非模拟、无覆盖） | 2026-10-12 周一 09:01:58（上午高峰内）提交的消息被扣住 178 分钟：会话日志显示消息在 09:01:58.530 进入 inbox、2 毫秒后 turn 开始，随后直到 12:00:03.051 才出现下一条事件（step/start），即 12:00:00 边界后 3 秒；模型请求在 12:00:03.054。消息未丢失、区间未被跳过——它就是等窗口结束 |

许可

MIT