dsh-session-guard 0.1.2 → 0.2.0-beta.1

package/INSTALL.ko.md

@@ -1,42 +1,83 @@
-# 설치 안내(공식 DSH CLI)
-
-- [한국어 설치 안내](./INSTALL.ko.md)
-- [English installation guide](./INSTALL.md)
-- [中文安装指南](./INSTALL.zh.md)
-- [日本語インストールガイド](./INSTALL.ja.md)
-- [한국어 README](./README.ko.md)
-- [English README](./README.en.md)
-- [中文 README](./README.md)
-- [日本語 README](./README.ja.md)
-- [Changelog](./CHANGELOG.md)
-- [日本語 changelog](./CHANGELOG.ja.md)
-- [한국어 changelog](./CHANGELOG.ko.md)
-
-## 0. 사전 확인
-
-```bash
-echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
-dsh --version
-```
-
-## 1. 설치
-
-```bash
-dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
-```
-
-dsh web을 재시작하고 페이지를 새로고침.
-
-## 2. 검증
-
-**설정 → 플러그인 → session-guard** 열기. 스위치: `enabled`, `offPeakAutoResume`, `weekendMode`, `queueFallback`, `retryEnabled`.
-
-세션 UI의 상태 배지 확인—현재 단계(NORMAL / PAUSED_PEAK) 표시.
-
-## 3. 제거
-
-```bash
-dsh plugin --profile web remove dsh-session-guard
-```
-
-dsh web 재시작.
+# 설치 안내(공식 DSH CLI)
+
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 README](./README.ko.md)
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [日本語 README](./README.ja.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0. 사전 확인
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+```
+
+## 1. 설치
+
+```bash
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+dsh web을 재시작하고 페이지를 새로고침.
+
+## 2. 검증
+
+**설정 → 플러그인 → session-guard** 열기. 스위치: `enabled`, `providerGuard`, `guardSubagents`,
+`offPeakAutoResume`, `weekendMode`, `deferredResume`, `queueFallback`, `retryEnabled`;
+텍스트/목록 항목: `officialProviders`, `officialBaseURLs`, `deferredResumeText`.
+
+세션 UI의 상태 배지 확인—현재 단계(`高峰·拦官方` / `高峰·全部暂停` / `谷时` / `周末`) 표시.
+
+특정 라우트의 공식 소스 판정 확인(host 라우트, 재시작 불필요):
+
+```bash
+curl -s 'http://127.0.0.1:3080/session-guard/provider?provider=deepseek-official'
+# {"ok":true,"verdict":{"provider":"deepseek-official","official":true,"matchedBy":"endpoint","endpoint":"https://api.deepseek.com"}}
+```
+
+테스트 실행(네트워크·자격 증명 불필요):
+
+```bash
+npm test
+```
+
+## 3. 업그레이드
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+dsh web을 재시작하고 페이지를 새로고침. 설정은 `$DSH_HOME/settings.yaml`의 `session-guard`
+네임스페이스에 있어 업그레이드 후에도 유지됩니다. 새 키(`providerGuard`, `deferredMode` 등)는
+건드리기 전까지 기본값입니다.
+
+`0.1.3`/`0.1.4-beta.1`에서 `0.1.5-beta.1`로의 유일한 동작 변경은 피크 시 기본적으로
+**공식 소스만** 차단한다는 점입니다. 예전의 전체 정지로 되돌리려면 `providerGuard: false`
+(또는 `officialProviders` / `officialBaseURLs`로 판정을 좁히기).
+
+## 4. 문제 해결
+
+| 증상 | 확인 |
+|---|---|
+| 피크인데 세션이 계속 실행 | `GET /session-guard/status` → `phase`가 `peak`; `GET /session-guard/settings` → `enabled: true` |
+| 로컬 provider가 차단됨 | `GET /session-guard/provider?provider=<id>` → `matchedBy`가 `endpoint`/`unknown`이고 `official: false`여야 함. `explicit`이면 `officialProviders`에서 제거 |
+| 공식 요청이 차단되지 않음 | `matchedBy: 'endpoint'`에 `official: false`면 `baseURL`이 `officialBaseURLs`에 없음; host를 추가하거나 라우트 id를 `officialProviders`에 추가 |
+| 요청이 계속 보류됨 | `hold` 모드의 설계된 동작. 명시적 오류로 만들려면 `deferredMode: 'error'` 또는 `deferredMaxHoldMs`를 줄이기 |
+| 피크 후 재개되지 않음 | `deferredResume`이 켜져 있어야 함(또는 `/resume`); 세션급은 `offPeakAutoResume` |
+| 판정 진단 불가 | `GET /session-guard/diag` → `providerGuard`, `configurableProviders`, `held`, `deferred` |
+
+## 5. 제거
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+dsh web 재시작. 언로드 시 보류 중인 요청은 해제(reject)되며 promise 누수는 없습니다.

package/INSTALL.md

@@ -1,44 +1,86 @@
-# Installation Guide (Official DSH CLI)
-
-This guide uses only the official DSH `dsh plugin` command.
-
-- [English installation guide](./INSTALL.md)
-- [中文安装指南](./INSTALL.zh.md)
-- [日本語インストールガイド](./INSTALL.ja.md)
-- [한국어 설치 안내](./INSTALL.ko.md)
-- [English README](./README.en.md)
-- [中文 README](./README.md)
-- [日本語 README](./README.ja.md)
-- [한국어 README](./README.ko.md)
-- [Changelog](./CHANGELOG.md)
-- [日本語 changelog](./CHANGELOG.ja.md)
-- [한국어 changelog](./CHANGELOG.ko.md)
-
-## 0. Prerequisites
-
-```bash
-echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
-dsh --version
-```
-
-## 1. Install
-
-```bash
-dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
-```
-
-Restart dsh web and refresh the page.
-
-## 2. Verify
-
-Open **Settings → Plugins → session-guard**. Toggles: `enabled`, `offPeakAutoResume`, `weekendMode`, `queueFallback`, `retryEnabled`.
-
-Check status badge in the session UI — it shows the current phase (NORMAL / PAUSED_PEAK).
-
-## 3. Uninstall
-
-```bash
-dsh plugin --profile web remove dsh-session-guard
-```
-
-Restart dsh web.
+# Installation Guide (Official DSH CLI)
+
+This guide uses only the official DSH `dsh plugin` command.
+
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0. Prerequisites
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+```
+
+## 1. Install
+
+```bash
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+Restart dsh web and refresh the page.
+
+## 2. Verify
+
+Open **Settings → Plugins → session-guard**. Toggles: `enabled`, `providerGuard`, `guardSubagents`,
+`offPeakAutoResume`, `weekendMode`, `deferredResume`, `queueFallback`, `retryEnabled`; text/list
+fields: `officialProviders`, `officialBaseURLs`, `deferredResumeText`.
+
+Check the status badge in the session UI — it shows the current phase (`高峰·拦官方` / `高峰·全部暂停`
+/ `谷时` / `周末`).
+
+Check the official-source verdict for one route (host route, no restart needed):
+
+```bash
+curl -s 'http://127.0.0.1:3080/session-guard/provider?provider=deepseek-official'
+# {"ok":true,"verdict":{"provider":"deepseek-official","official":true,"matchedBy":"endpoint","endpoint":"https://api.deepseek.com"}}
+```
+
+Run the test suite (no network, no credentials):
+
+```bash
+npm test
+```
+
+## 3. Upgrade
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+Restart dsh web and refresh the page. Settings live in `$DSH_HOME/settings.yaml` under the
+`session-guard` namespace and survive the upgrade; new keys (`providerGuard`, `deferredMode`, …)
+fall back to their defaults until you touch them.
+
+From `0.1.3`/`0.1.4-beta.1` to `0.1.5-beta.1` the only behavior change is that peak hours now
+block **only** official-source targets by default. To restore the old blanket behavior set
+`providerGuard: false` (or `officialProviders` / `officialBaseURLs` to narrow the verdict).
+
+## 4. Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| Sessions still run during peak | `GET /session-guard/status` → `phase` must be `peak`; `GET /session-guard/settings` → `enabled: true` |
+| A local provider is blocked during peak | `GET /session-guard/provider?provider=<id>` → `matchedBy` should be `endpoint`/`unknown` with `official: false`. If it says `explicit`, remove the id from `officialProviders` |
+| An official request is NOT blocked | `matchedBy: 'endpoint'` with `official: false` means the route's `baseURL` is not in `officialBaseURLs`; add the host there, or add the route id to `officialProviders` |
+| Requests hang instead of failing | That is `hold` mode by design. Set `deferredMode: 'error'` for an explicit error, or lower `deferredMaxHoldMs` |
+| Nothing resumes after peak | `deferredResume` must be on (or run `/resume`); `offPeakAutoResume` controls session-level resume |
+| Verdict diagnostics unavailable | `GET /session-guard/diag` → `providerGuard`, `configurableProviders`, `held`, `deferred` |
+
+## 5. Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+Restart dsh web. Held requests are released (rejected) on unload — no promise leaks.

package/INSTALL.zh.md

@@ -1,42 +1,82 @@
-# 安装指南（官方 DSH CLI）
-
-- [安装指南](./INSTALL.zh.md)
-- [English installation guide](./INSTALL.md)
-- [日本語インストールガイド](./INSTALL.ja.md)
-- [한국어 설치 안내](./INSTALL.ko.md)
-- [中文 README](./README.md)
-- [English README](./README.en.md)
-- [日本語 README](./README.ja.md)
-- [한국어 README](./README.ko.md)
-- [版本更新日志](./CHANGELOG.md)
-- [日本語 changelog](./CHANGELOG.ja.md)
-- [한국어 changelog](./CHANGELOG.ko.md)
-
-## 0. 前置条件
-
-```bash
-echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
-dsh --version
-```
-
-## 1. 安装
-
-```bash
-dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
-```
-
-重启 dsh web 并刷新页面。
-
-## 2. 验证
-
-打开「设置 → 插件 → session-guard」。开关：`enabled`、`offPeakAutoResume`、`weekendMode`、`queueFallback`、`retryEnabled`。
-
-检查会话界面中的状态徽标——显示当前阶段（NORMAL / PAUSED_PEAK）。
-
-## 3. 卸载
-
-```bash
-dsh plugin --profile web remove dsh-session-guard
-```
-
-重启 dsh web。
+# 安装指南（官方 DSH CLI）
+
+- [安装指南](./INSTALL.zh.md)
+- [English installation guide](./INSTALL.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [版本更新日志](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0. 前置条件
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+```
+
+## 1. 安装
+
+```bash
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+重启 dsh web 并刷新页面。
+
+## 2. 验证
+
+打开「设置 → 插件 → session-guard」。开关：`enabled`、`providerGuard`、`guardSubagents`、
+`offPeakAutoResume`、`weekendMode`、`deferredResume`、`queueFallback`、`retryEnabled`；
+文本/列表项：`officialProviders`、`officialBaseURLs`、`deferredResumeText`。
+
+检查会话界面中的状态徽标——显示当前阶段（`高峰·拦官方` / `高峰·全部暂停` / `谷时` / `周末`）。
+
+查看某个路由的官方源判定（host 路由，无需重启）：
+
+```bash
+curl -s 'http://127.0.0.1:3080/session-guard/provider?provider=deepseek-official'
+# {"ok":true,"verdict":{"provider":"deepseek-official","official":true,"matchedBy":"endpoint","endpoint":"https://api.deepseek.com"}}
+```
+
+跑测试（不联网、不读凭据）：
+
+```bash
+npm test
+```
+
+## 3. 升级
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+重启 dsh web 并刷新页面。设置在 `$DSH_HOME/settings.yaml` 的 `session-guard` 命名空间下，升级不会丢；
+新增键（`providerGuard`、`deferredMode` 等）在你没动之前用默认值。
+
+从 `0.1.3`/`0.1.4-beta.1` 升到 `0.1.5-beta.1`，唯一的行为变化是高峰期默认**只拦官方源**。
+要恢复旧的「一律暂停」，把 `providerGuard` 设为 `false`（或用 `officialProviders` /
+`officialBaseURLs` 收窄判定）。
+
+## 4. 故障排查
+
+| 现象 | 怎么查 |
+|---|---|
+| 高峰期会话照常跑 | `GET /session-guard/status` → `phase` 必须是 `peak`；`GET /session-guard/settings` → `enabled: true` |
+| 本地 provider 被拦 | `GET /session-guard/provider?provider=<id>` → `matchedBy` 应为 `endpoint`/`unknown` 且 `official: false`。若是 `explicit`，把它从 `officialProviders` 里删掉 |
+| 官方请求没被拦 | `matchedBy: 'endpoint'` 且 `official: false` 说明该路由 `baseURL` 不在 `officialBaseURLs` 里；把 host 加进去，或把路由 id 加进 `officialProviders` |
+| 请求挂着不报错 | 这是 `hold` 模式的预期行为。要显式报错设 `deferredMode: 'error'`，或调小 `deferredMaxHoldMs` |
+| 退峰后不自动继续 | `deferredResume` 必须开着（或手动 `/resume`）；会话级恢复看 `offPeakAutoResume` |
+| 判定诊断不可用 | `GET /session-guard/diag` → `providerGuard`、`configurableProviders`、`held`、`deferred` |
+
+## 5. 卸载
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+重启 dsh web。卸载时挂起的请求会被释放（reject），不会泄漏 promise。