dsh-offpeak 0.0.0-stage → 3.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-offpeak contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,116 @@
+<p align="center">
+  <img src="./assets/dsh-offpeak-hero.png" alt="dsh-offpeak — Selective Control. Continuous Workflow." width="100%">
+</p>
+
+<p align="center">
+  <strong>English</strong> · <a href="README.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <img alt="dsh-plugin" src="https://img.shields.io/badge/dsh--plugin-ready-478CBF?logo=deepseek&logoColor=white">
+  <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square">
+</p>
+
+# dsh-offpeak
+
+A DSH (DeepSeek Harness) host plugin that keeps peak-hour usage under control: it closes the session gate before a peak-hour request goes out, holds only the requests whose **target is official or explicitly listed**, lets everything else run, and gives a single session a time-boxed "free run" exemption.
+
+Plugin id `dsh-offpeak`, settings namespace `offpeak`, config file `config/offpeak.json`.
+
+## What it does
+
+| Capability | Behaviour |
+|---|---|
+| Configurable peak policy | Peak windows, timezone, per-window weekdays and the weekend rule come from `config/offpeak.json` (env → `$DSH_HOME/config` → `<cwd>/config` → bundled default). A malformed file never silently disables the guard: errors are collected and reported (`configFile.errors` on `/session-guard/settings` and `/diag`), affected keys keep their defaults. |
+| Turn / step gating | On peak entry, running sessions are paused (or gated at the next `agent/pre-step` when `stepLevelPause` is on) and released automatically off peak. Manual `/pause` is never touched by the automatic release. |
+| Request-level guard | `agent/request` is checked on **every** request, so sessions started after peak entry — or switched to an official route mid-session — are still caught. `deferredMode: 'hold'` (default) holds the request silently; `'error'` raises a recognisable `PEAK_DEFERRED`. |
+| Target verdict | Priority: explicit `officialProviders` list → **model name (exact match, case-insensitive)** → live `baseURL` host → catalog default endpoint → built-in id (`deepseek-official`) → unknown. A request is held only when the verdict is `official`. |
+| Peak interception list | Tick models in the badge panel (or write `officialModelPatterns`): an entry is a **model name matched exactly**, so ticking `ocg/deepseek-flash` intercepts exactly that model, whatever route serves it — and nothing is intercepted until you tick something. The panel has a keyword filter, select-all / clear-select-all, refresh, hot reload, and a `×` undo on every intercepted entry. |
+| Free-run | Schedule one or more absolute time windows for one session; inside them the session is exempt everywhere (peak entry, step gate, request hold). Per-segment pause/resume, merged up to 8 windows, persisted — shown at the top of the same panel as the interception list. |
+| Badge | One clickable badge in the composer: `高峰` / `高峰 · 拦截中` / `高峰 · 畅跑中` / `谷时` / `周末`; red while blocking, green while allowing. |
+| Retry | Optional backend retry for transient turn failures (off by default); it always yields to the gates. |
+
+## Compatibility
+
+| Item | Notes |
+|---|---|
+| DSH host versions | `package.json`'s `engines.dsh` = `>=0.1.5-rc.2 <0.1.6-0 \|\| >=0.1.7-rc.1 <0.1.8-0 \|\| >=0.2.0-rc.1 <0.2.1-0`. **Only the 0.1.7 line is actually verified** (this plugin was developed and tested there); the other two ranges follow the same interfaces but were not exercised one by one — check `dsh --profile <yours> --dump-config` composes cleanly before installing. |
+| Settings and the write path | On the 0.1.7 line the client has **no `settingsScope`**, so the browser half injects only `slots + locale`: the settings form is auto-generated by the host from the exported `Config` schema, and the interception list is written through `POST /session-guard/rpc {action:'setModelPatterns'}`, which rewrites `config/offpeak.json` and reloads immediately. A custom settings card is rendered only when the host provides `settingsScope`. |
+| Node | `engines.node >= 20` (the bundled `node --test` suite uses Node 22+ type-stripping imports of `.ts`). |
+| Bootstrap deps | `@deepseek-ai/schemastery ^3.18.4` is a runtime dependency; `@deepseek-ai/cordis ^4.0.1` and the `@deepseek-ai/dsh-client-*` packages are **optional peerDependencies** (missing them is not an error). |
+| Stable surface | The `/session-guard/*` route prefix and the in-process `sessionGuard` service port are **deliberately kept** (compatibility with existing tooling/notes): renaming the plugin does not rename them. |
+| input-traffic | The bridge global is read from `window.__DSH_OFFPEAK_BRIDGE__` first, falling back to the historic `window.__DSH_SESSION_GUARD_BRIDGE__`; without either, the plugin ships its own fallback badge/freeze and the two do not replace each other. |
+| Known limitations | No statutory-holiday calendar; free-run interprets wall-clock input in the configured timezone; the interception list matches **exact model names** (no keyword/regex sweeping). |
+
+## Install
+
+Pick any of the three channels: the npm package, the GitHub repository, or a local directory / the tgz attached to a Release.
+
+```bash
+# (1) npm (recommended)
+dsh plugin --profile desktop add dsh-offpeak
+
+# (2) GitHub (first time needs an allowBuilds entry in the profile's pnpm-workspace.yaml so the package's prepare build may run)
+dsh plugin --profile desktop add github:lizilong1993/dsh-offpeak
+
+# (3) local directory / Release asset (no permissions needed)
+dsh plugin --profile desktop add ./dsh-offpeak
+dsh plugin --profile desktop add ./dsh-offpeak-<version>.tgz
+
+dsh --profile desktop --dump-config     # verify the composed patch layers
+```
+
+Building from source (for development):
+
+```bash
+git clone https://github.com/lizilong1993/dsh-offpeak.git
+cd dsh-offpeak
+npm install          # or pnpm install
+npm run build        # rebuild lib/client.js (the browser half)
+```
+
+Or point a profile at this checkout by hand — `~/.dsh/profiles/<profile>/package.json`:
+
+```json
+{ "dependencies": { "dsh-offpeak": "link:/path/to/dsh-offpeak" } }
+```
+
+and add `dsh-offpeak` to that file's `dsh.profile.bundles`. Then restart DSH (host code is loaded at boot) and refresh the page.
+
+## Configuration
+
+`config/offpeak.json` (default layer; form values win) — keys used most:
+
+```jsonc
+{
+  "timezone": "Asia/Shanghai",
+  "peakPolicy": { "peakWindows": [{ "name": "morning", "start": "09:00", "end": "12:00", "days": ["mon","tue","wed","thu","fri"] }] },
+  "weekendPolicy": { "enabled": true, "days": ["sat","sun"], "mode": "offPeak" },
+  "providerGuard": true,
+  "officialProviders": [],            // extra provider ids, exact match, highest priority
+  "officialModelPatterns": [],        // intercepted model names (exact, case-insensitive)
+  "officialBaseURLs": ["api.deepseek.com"],
+  "deferredMode": "hold",             // 'hold' | 'error'
+  "deferredResume": true,
+  "stepLevelPause": true
+}
+```
+
+`DSH_OFFPEAK_CONFIG` picks an explicit config file; the state root defaults to `.dsh/offpeak` (`DSH_OFFPEAK_STATE_DIR` overrides it).
+
+## HTTP / service surface
+
+`GET /session-guard/status` · `/state?session=` · `/settings` · `/provider?provider=&model=` · `/models` · `/diag` · `/events` (SSE) · `POST /session-guard/rpc` (`stopNextTurn|resume|lockQueue|unlockQueue|stepPause|stepResume|state|reloadConfig|setModelPatterns|freeRunAdd|…`), plus the in-process `sessionGuard` service port.
+
+## Tests
+
+`npm test` (node:test) · `npm run lint` · `npm run build`.
+
+## Acknowledgements
+
+- [drscrewdriver/dsh-session-guard](https://github.com/drscrewdriver/dsh-session-guard)
+
+## Licence
+
+MIT — see [LICENSE](./LICENSE).

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <img src="./assets/dsh-offpeak-hero.png" alt="dsh-offpeak — 该停的停，该跑的跑 / Selective Control. Continuous Workflow." width="100%">
+</p>
+
+<p align="center">
+  <a href="README.en.md">English</a> · <strong>中文</strong>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <img alt="dsh-plugin" src="https://img.shields.io/badge/dsh--plugin-ready-478CBF?logo=deepseek&logoColor=white">
+  <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square">
+</p>
+
+# dsh-offpeak
+
+一个 DSH（DeepSeek Harness）宿主插件：用来自动管理高峰期的会话与请求 —— 在高峰请求真正发出**之前**拉门、只拦**目标为官方源或显式列出的模型**的请求、其余照常跑，并支持给单个会话排一段时间「畅跑」豁免。
+
+插件 id `dsh-offpeak`，设置命名空间 `offpeak`，配置文件 `config/offpeak.json`。
+
+## 能力一览
+
+| 能力 | 行为 |
+|---|---|
+| 可配置峰谷策略 | 峰窗口、时区、每窗口的星期与周末规则全部来自 `config/offpeak.json`（env → `$DSH_HOME/config` → `<cwd>/config` → 包内默认）。配置文件写坏**绝不静默让守卫失效**：错误被收集并暴露（`/session-guard/settings` 与 `/diag` 的 `configFile.errors`），对应键保留默认值。 |
+| 回合 / step 门控 | 入峰时暂停 running 会话（`stepLevelPause` 开启则在下一个 `agent/pre-step` 拉门），退峰自动放行；自动放行**不碰**手动 `/pause`。 |
+| 请求级守卫 | `agent/request` **每个请求都过**，所以入峰后才启动的会话、会话中途切到官方源的情况都能兜住。`hold`（默认）静默挂起，`error` 抛可识别的 `PEAK_DEFERRED`。 |
+| 目标判定 | 优先级：显式 `officialProviders` → **模型名（精确匹配、大小写不敏感）** → 实时 `baseURL` → catalog 默认端点 → 内置 id（`deepseek-official`）→ unknown。只有判为官方才拦。 |
+| 高峰拦截列表 | 在徽标面板里勾选模型（或直接写 `officialModelPatterns`）：条目是**模型名精确匹配** —— 勾了 `ocg/deepseek-flash` 就只拦这一个模型，无论它跑在哪条路由上；**不勾不拦**。面板顶部有关键词过滤、全选/取消全选、刷新与热重载，每个已拦截项都带 `×` 撤销。 |
+| 畅跑 | 给单个会话排一段或多段绝对时间窗口，窗口内该会话在**入峰、step 门、请求挂起**三处都豁免；支持逐段暂停/恢复、合并上限 8 条、持久化。面板里与拦截列表同处一个展开区（最上方）。 |
+| 徽标 | 输入区一个可点徽标：`高峰` / `高峰 · 拦截中` / `高峰 · 畅跑中` / `谷时` / `周末`；拦截态红、放行态绿。 |
+| 自动重试 | 可选的后端重试（默认关），且永远给门控让路。 |
+
+## 兼容性
+
+| 项目 | 说明 |
+|---|---|
+| DSH 宿主版本 | `package.json` 的 `engines.dsh` = `>=0.1.5-rc.2 <0.1.6-0 \|\| >=0.1.7-rc.1 <0.1.8-0 \|\| >=0.2.0-rc.1 <0.2.1-0`（三段）。**实际验证只在 0.1.7 线做过**（本插件的开发与实测环境）；另两段按接口形态适配、尚未逐一实测 —— 装之前请先看下 `dsh --profile <你的 profile> --dump-config` 能否正常组装。 |
+| 设置与写入口 | 0.1.7 线的客户端**没有 `settingsScope`**，所以本插件的浏览器半只注入 `slots + locale`：设置表单由宿主按导出的 `Config` schema 自动生成；拦截列表的写入口是 `POST /session-guard/rpc {action:'setModelPatterns'}`，写 `config/offpeak.json` 后立即 `reloadConfig`。宿主提供 `settingsScope` 时才渲染自定义设置卡片。 |
+| Node | `engines.node >= 20`（仓库自带 `node --test` 测试为 Node 22+ 写法：直接 import `.ts` 类型擦除）。 |
+| bootstrap 依赖 | `@deepseek-ai/schemastery ^3.18.4` 为运行时依赖；`@deepseek-ai/cordis ^4.0.1` 与 `@deepseek-ai/dsh-client-*` 声明为**可选 peerDependencies**（不装不报错）。 |
+| 稳定接口（跨版本不变） | `/session-guard/*` 路由前缀与 `sessionGuard` 进程内服务端口是**保留名**（与既有工具/笔记兼容）：换插件名不会改它们。 |
+| 与 input-traffic 的关系 | 该插件的「最小桥」全局名优先读 `window.__DSH_OFFPEAK_BRIDGE__`，同时兼容它历史上写的 `window.__DSH_SESSION_GUARD_BRIDGE__`；没有它时本插件自带回退冻结/徽标，两者不互相取代。 |
+| 已知限制 | 不识别法定节假日；畅跑按配置时区解释墙钟；高峰拦截列表是**精确模型名**匹配（不做关键字/正则的批量覆盖）。 |
+
+## 安装
+
+三条通道任选：npm 包 / GitHub 仓库 / 本地目录或 Release 里的 tgz。
+
+```bash
+# ① npm（推荐）
+dsh plugin --profile desktop add dsh-offpeak
+
+# ② GitHub（首次需在 profile 的 pnpm-workspace.yaml 里给 allowBuilds 放行该包的 prepare 构建）
+dsh plugin --profile desktop add github:lizilong1993/dsh-offpeak
+
+# ③ 本地目录 / Release 资产（零权限）
+dsh plugin --profile desktop add ./dsh-offpeak
+dsh plugin --profile desktop add ./dsh-offpeak-<version>.tgz
+
+dsh --profile desktop --dump-config     # 验证补丁分层
+```
+
+从源码构建（开发用）：
+
+```bash
+git clone https://github.com/lizilong1993/dsh-offpeak.git
+cd dsh-offpeak
+npm install          # 或 pnpm install
+npm run build        # 重新构建 lib/client.js（浏览器半）
+```
+
+也可以手工在 profile 里指向这个检出 —— `~/.dsh/profiles/<profile>/package.json`：
+
+```json
+{ "dependencies": { "dsh-offpeak": "link:/path/to/dsh-offpeak" } }
+```
+
+并把 `dsh-offpeak` 加进同一文件的 `dsh.profile.bundles`；然后重启 DSH（host 代码在 boot 时加载）并刷新页面。
+
+## 配置
+
+`config/offpeak.json`（默认层；设置表单里的值优先），常用键：
+
+```jsonc
+{
+  "timezone": "Asia/Shanghai",
+  "peakPolicy": { "peakWindows": [{ "name": "morning", "start": "09:00", "end": "12:00", "days": ["mon","tue","wed","thu","fri"] }] },
+  "weekendPolicy": { "enabled": true, "days": ["sat","sun"], "mode": "offPeak" },
+  "providerGuard": true,
+  "officialProviders": [],            // 追加官方 provider id（精确匹配，最高优先级）
+  "officialModelPatterns": [],        // 高峰拦截的模型名（精确匹配、大小写不敏感）
+  "officialBaseURLs": ["api.deepseek.com"],
+  "deferredMode": "hold",             // 'hold' | 'error'
+  "deferredResume": true,
+  "stepLevelPause": true
+}
+```
+
+可用 `DSH_OFFPEAK_CONFIG` 显式指定配置文件；状态目录默认 `.dsh/offpeak`（`DSH_OFFPEAK_STATE_DIR` 可覆盖）。
+
+## HTTP / 服务面
+
+`GET /session-guard/status` · `/state?session=` · `/settings` · `/provider?provider=&model=` · `/models` · `/diag` · `/events`（SSE）· `POST /session-guard/rpc`（`stopNextTurn|resume|lockQueue|unlockQueue|stepPause|stepResume|state|reloadConfig|setModelPatterns|freeRunAdd|…`），以及进程内的 `sessionGuard` 服务端口。
+
+## 测试
+
+`npm test`（node:test）· `npm run lint` · `npm run build`。
+
+## 致谢
+
+- [drscrewdriver/dsh-session-guard](https://github.com/drscrewdriver/dsh-session-guard)
+
+## 许可
+
+MIT —— 见 [LICENSE](./LICENSE)。

package/config/offpeak.json

@@ -0,0 +1,44 @@
+{
+  "enabled": true,
+
+  "timezone": "Asia/Shanghai",
+
+  "peakPolicy": {
+    "peakWindows": [
+      {
+        "name": "morning",
+        "start": "09:00",
+        "end": "12:00",
+        "days": [
+          "mon",
+          "tue",
+          "wed",
+          "thu",
+          "fri"
+        ]
+      },
+
+      {
+        "name": "afternoon",
+        "start": "14:00",
+        "end": "18:00",
+        "days": [
+          "mon",
+          "tue",
+          "wed",
+          "thu",
+          "fri"
+        ]
+      }
+    ]
+  },
+
+  "weekendPolicy": {
+    "enabled": true,
+    "days": [
+      "sat",
+      "sun"
+    ],
+    "mode": "offPeak"
+  }
+}

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-offpeak bundle patch：一行装配进 profile。
+#
+# host 半（src/index.js）注册 sessionGuard 服务（冗余端口，供 input-traffic 适配）、
+# 高峰自动会话门（taskControl.pause/resume，缺失时回退锁等待队列）、
+# /session-guard/* 路由（路径保留旧名，input-traffic 依赖）与 设置→插件→offpeak 子板块。
+# 浏览器半（经 package.json dsh.client 声明）提供高峰面板（畅跑任务 + 拦截列表）。
+- insert:
+    - id: offpeak
+      name: dsh-offpeak

package/dsh.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "dsh-external/dsh-offpeak",
+  "version": "3.1.6",
+  "main": "./src/index.js",
+  "description": "可配置峰谷自动会话门：config/offpeak.json 驱动 peak 时段 + step 级门控 + 周末全天 off-peak + 单会话「畅跑」限时无视峰谷 + 波谷自动恢复 + 按模型名的高峰拦截列表。",
+  "engines": {
+    "dsh": ">=0.1.5-rc.2 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0"
+  },
+  "contributes": {
+    "tools": [],
+    "skills": []
+  },
+  "client": {
+    "main": "./lib/client.js"
+  }
+}