dsh-peak-block 0.1.1 → 0.2.0

package/README.md

@@ -10,13 +10,27 @@
 
 ![拦截效果](docs/拦截效果.webp)
 
+## 演示视频
+
+| 禁止梁文峰演示 · 24 秒 |
+| :---: |
+| [![禁止梁文峰演示](https://i1.hdslb.com/bfs/archive/2d7698c26fe79cd2438019521a5a099d75ad5d04.jpg)](https://www.bilibili.com/video/BV1zvth6oEFp/) |
+
 ## 安装
 
+**从 GitHub 安装**：源码在 `src/`，`lib/` 不入仓库，安装时 npm 会触发 `prepare` 脚本现场构建。
+
 ```powershell
 dsh plugin --profile web add github:better-er/dsh-peak-block
 ```
 
-一条命令装完即生效，自动挂载，重启 DSH web 后启用，无需手工编辑任何文件。
+**从 npm 安装**：包内已含构建产物 `lib/index.js`，安装时不再构建。
+
+```powershell
+dsh plugin --profile web add dsh-peak-block
+```
+
+两种方式装完都会自动挂载，重启 DSH web 后启用，无需手工编辑任何文件。
 
 ## 卸载
 
@@ -59,13 +73,17 @@ plugins:
 ## 要求与开发
 
 - 是**标准形态的 dsh host 单半身插件**：host 在 `agent/request` waterfall 里拦截并切换/阻止，设置全部经 cordis 配置文件注入，见上方配置表，不提供界面配置 UI。
-- 无构建：`lib/index.js` 为源码即产物，改完即用。
-- 纯函数 `isPeakBeijing` / `isOfficial` / `decide` 在 `lib/index.js` 导出，冒烟测试：
+- TypeScript 源码在 `src/index.ts`，由 tsdown 构建到 `lib/`；`lib/` 是产物不入库，改完要重新构建：
 
   ```powershell
-  node scripts/smoke.mjs
+  pnpm install
+  pnpm build        # 构建 lib/index.js 与 lib/index.d.ts
+  pnpm typecheck    # 严格类型检查
+  pnpm test         # vitest 单测，覆盖峰谷判定与拦截决策
   ```
 
+- 纯函数 `isPeakBeijing` / `isOfficial` / `decide` 从包入口导出，单测见 `tests/index.spec.ts`。
+
 ## License
 
 [MIT](./LICENSE)

package/lib/index.d.ts

@@ -0,0 +1,93 @@
+//#region src/index.d.ts
+/**
+ * dsh-peak-block host 端：梁文峰时间拦截向 DeepSeek 官方 API 的模型请求。
+ *
+ * 在「梁文峰时间」，即 DeepSeek 官方高峰时段——北京时间工作日 09:00–12:00、14:00–18:00、周末全天谷价——拦截原本发往官方 provider 的对话请求。
+ * 已配置 targetProvider 则切换路由，未配置则阻止并抛出带文案的错误提示。非高峰时段不拦截，正常走官方。
+ *
+ * 拦截 seam：agent/request waterfall。它对每次对话模型请求携带冻结的调用配置种子 LlmCallConfig，含 provider/model/reasoningEffort/temperature/maxTokens/stop。
+ * listener 可返回替代 config 切换 provider。要判断请求是否官方必须先调用 next 拿到 config，故实现为「先取 config 再决策」：切换时返回替代 config，阻止时抛带提示文案的错误。
+ * compaction 等走 ctx.llm.stream 直接调用的路径不经此 waterfall，本插件不拦。
+ */
+/** 插件名，与 cordis.patch.yml 的 name 一致。 */
+declare const name = "dsh-peak-block";
+/** 纯 host 半身，无额外服务注入。 */
+declare const inject: string[];
+/** 峰谷时段窗口。 */
+interface PeakWindow {
+  /** JS getUTCDay 序号：0=周日 … 6=周六，1..5 为周一..周五。 */
+  days: number[];
+  /** 峰时段列表，每项 [起, 止)，小时制，含起不含止，按 UTC+8 换算。 */
+  hourRanges: Array<[number, number]>;
+  /** 周末是否全天谷价，默认 true，即周末不拦。 */
+  weekendOffPeak: boolean;
+}
+/** 梁文峰时间默认窗口：工作日 09:00–12:00、14:00–18:00，UTC+8，周末全天谷。 */
+declare const DEFAULT_PEAK: PeakWindow;
+/** 模型请求的冻结调用配置种子，agent/request waterfall 的 next() 返回它，切换 provider 时原样带出其余字段。 */
+interface CallSeed {
+  provider?: string;
+  model?: string;
+  reasoningEffort?: string;
+  temperature?: number;
+  maxTokens?: number;
+  stop?: string[];
+  [key: string]: unknown;
+}
+/** 插件配置，全部经 cordis 配置文件注入。 */
+interface Config {
+  /** 总开关，显式 false 才关闭，缺省启用。 */
+  enabled?: boolean;
+  /** 视为「官方」的 provider 精确名单，不设则用默认判定，即只认 deepseek-official。 */
+  officialProviders?: string[];
+  /** 拦截后切到的目标 provider，留空即阻止并提示。 */
+  targetProvider?: string;
+  /** 峰谷时段窗口，可整体或局部覆盖默认窗口。 */
+  peakWindow?: Partial<PeakWindow>;
+}
+/** 单次请求的决策结果：pass 放行、switch 切 provider、block 阻止。 */
+type Decision = {
+  action: 'pass';
+} | {
+  action: 'switch';
+  config: CallSeed;
+} | {
+  action: 'block';
+};
+/** 决策输入，timeMs 由调用方注入以便测试。 */
+interface DecideOptions {
+  /** 判定用的 epoch 毫秒，本地时钟不可信时也照此换算 UTC+8。 */
+  timeMs: number;
+  /** 峰谷窗口，缺省用 DEFAULT_PEAK。 */
+  peakWindow?: Partial<PeakWindow>;
+  /** 官方 provider 精确名单，缺省只认 deepseek-official。 */
+  officialProviders?: string[];
+  /** 拦截后切到的目标 provider。 */
+  targetProvider?: string;
+}
+/** host 上下文里本插件用到的最小接口，只需注册 agent/request waterfall。 */
+interface HostContext {
+  on(event: 'agent/request', listener: (payload: unknown, next: () => Promise<CallSeed>) => Promise<CallSeed>): void;
+}
+/** 默认官方 provider 判定：只精确匹配 DSH 官方注册路由 deepseek-official。
+ * 不用名称前缀规则——pi-ai 自带的第三方 deepseek 中转不应算官方，避免误拦。 */
+declare function defaultIsOfficial(provider: string | undefined): boolean;
+/**
+ * 时刻是否处于梁文峰时间。纯 UTC+8 数学换算，与系统时区无关，本机时钟/时区不可信。
+ * 红线：周末全天谷价，仅工作日有峰。
+ */
+declare function isPeakBeijing(timeMs: number, peak?: Partial<PeakWindow>): boolean;
+/** provider 是否视为官方。显式名单用精确匹配；未提供名单用默认判定，即仅 deepseek-official。 */
+declare function isOfficial(provider: string | undefined, officialProviders?: string[]): boolean;
+/** 阻止时抛出的提示文案，用户可见，随界面失败信息呈现。 */
+declare const BLOCK_MESSAGE = "【梁文峰时间拦截 · dsh-peak-block】当前为 DeepSeek 官方高峰时段，且未配置拦截目标 targetProvider，请求已阻止。请为 dsh-peak-block 配置 targetProvider，或将请求留到梁文谷时段再发。";
+/**
+ * 纯拦截决策，可单测：返回 { action: 'pass' | 'switch' | 'block', config? }。
+ * - 非梁文峰时间或非官方 → pass，放行
+ * - 梁文峰时间 + 官方 + 有目标 → switch，切 provider 到目标
+ * - 梁文峰时间 + 官方 + 无目标 → block，阻止并提示
+ */
+declare function decide(seed: CallSeed | undefined, opts: DecideOptions): Decision;
+declare function apply(ctx: HostContext, config?: Config): void;
+//#endregion
+export { BLOCK_MESSAGE, CallSeed, Config, DEFAULT_PEAK, DecideOptions, Decision, HostContext, PeakWindow, apply, decide, defaultIsOfficial, inject, isOfficial, isPeakBeijing, name };

package/lib/index.js

@@ -1,88 +1,93 @@
-// dsh-peak-block host 端：梁文峰时间拦截向 DeepSeek 官方 API 的模型请求。
-//
-// 在「梁文峰时间」，即 DeepSeek 官方高峰时段——北京时间工作日 09:00–12:00、14:00–18:00、周末全天谷价——拦截原本发往官方 provider 的对话请求。
-// 已配置 targetProvider 则切换路由，未配置则阻止并抛出带文案的错误提示。非高峰时段不拦截，正常走官方。
-//
-// 拦截 seam：agent/request waterfall。它对每次对话模型请求携带冻结的调用配置种子 LlmCallConfig，含 provider/model/reasoningEffort/temperature/maxTokens/stop。
-// listener 可返回替代 config 切换 provider。要判断请求是否官方必须先调用 next 拿到 config，故实现为「先取 config 再决策」：切换时返回替代 config，阻止时抛带提示文案的错误。
-// compaction 等走 ctx.llm.stream 直接调用的路径不经此 waterfall，本插件不拦。
-
-export const name = 'dsh-peak-block'
-export const inject = []
-
+//#region src/index.ts
+/**
+* dsh-peak-block host 端：梁文峰时间拦截向 DeepSeek 官方 API 的模型请求。
+*
+* 在「梁文峰时间」，即 DeepSeek 官方高峰时段——北京时间工作日 09:00–12:00、14:00–18:00、周末全天谷价——拦截原本发往官方 provider 的对话请求。
+* 已配置 targetProvider 则切换路由，未配置则阻止并抛出带文案的错误提示。非高峰时段不拦截，正常走官方。
+*
+* 拦截 seam：agent/request waterfall。它对每次对话模型请求携带冻结的调用配置种子 LlmCallConfig，含 provider/model/reasoningEffort/temperature/maxTokens/stop。
+* listener 可返回替代 config 切换 provider。要判断请求是否官方必须先调用 next 拿到 config，故实现为「先取 config 再决策」：切换时返回替代 config，阻止时抛带提示文案的错误。
+* compaction 等走 ctx.llm.stream 直接调用的路径不经此 waterfall，本插件不拦。
+*/
+/** 插件名，与 cordis.patch.yml 的 name 一致。 */
+const name = "dsh-peak-block";
+/** 纯 host 半身，无额外服务注入。 */
+const inject = [];
 /** 梁文峰时间默认窗口：工作日 09:00–12:00、14:00–18:00，UTC+8，周末全天谷。 */
-export const DEFAULT_PEAK = {
-  days: [1, 2, 3, 4, 5], // JS getUTCDay：0=周日 … 6=周六，1..5=周一..周五
-  hourRanges: [[9, 12], [14, 18]],
-  weekendOffPeak: true,
-}
-
-/** 默认官方 provider 判定：只精确匹配 DSH 官方注册路由 `deepseek-official`。
- * 不用名称前缀规则——pi-ai 自带的第三方 `deepseek` 中转不应算官方，避免误拦。 */
-export function defaultIsOfficial(provider) {
-  return provider === 'deepseek-official'
+const DEFAULT_PEAK = {
+	days: [
+		1,
+		2,
+		3,
+		4,
+		5
+	],
+	hourRanges: [[9, 12], [14, 18]],
+	weekendOffPeak: true
+};
+/** 默认官方 provider 判定：只精确匹配 DSH 官方注册路由 deepseek-official。
+* 不用名称前缀规则——pi-ai 自带的第三方 deepseek 中转不应算官方，避免误拦。 */
+function defaultIsOfficial(provider) {
+	return provider === "deepseek-official";
 }
-
 /**
- * 时刻是否处于梁文峰时间。纯 UTC+8 数学换算，与系统时区无关，本机时钟/时区不可信。
- * 红线：周末全天谷价，仅工作日有峰。
- */
-export function isPeakBeijing(timeMs, peak = DEFAULT_PEAK) {
-  const shifted = timeMs + 8 * 3600 * 1000
-  const d = new Date(shifted)
-  const day = d.getUTCDay()
-  if (peak.weekendOffPeak !== false && (day === 0 || day === 6)) return false
-  if (Array.isArray(peak.days) && peak.days.length > 0 && !peak.days.includes(day)) return false
-  const hour = d.getUTCHours()
-  for (const [a, b] of peak.hourRanges) {
-    if (hour >= a && hour < b) return true
-  }
-  return false
+* 时刻是否处于梁文峰时间。纯 UTC+8 数学换算，与系统时区无关，本机时钟/时区不可信。
+* 红线：周末全天谷价，仅工作日有峰。
+*/
+function isPeakBeijing(timeMs, peak = DEFAULT_PEAK) {
+	const shifted = timeMs + 288e5;
+	const d = new Date(shifted);
+	const day = d.getUTCDay();
+	if (peak.weekendOffPeak !== false && (day === 0 || day === 6)) return false;
+	const days = peak.days;
+	if (Array.isArray(days) && days.length > 0 && !days.includes(day)) return false;
+	const hour = d.getUTCHours();
+	for (const [a, b] of peak.hourRanges ?? DEFAULT_PEAK.hourRanges) if (hour >= a && hour < b) return true;
+	return false;
 }
-
 /** provider 是否视为官方。显式名单用精确匹配；未提供名单用默认判定，即仅 deepseek-official。 */
-export function isOfficial(provider, officialProviders) {
-  if (!provider) return false
-  if (Array.isArray(officialProviders)) {
-    return officialProviders.some((p) => provider === p)
-  }
-  return defaultIsOfficial(provider)
+function isOfficial(provider, officialProviders) {
+	if (!provider) return false;
+	if (Array.isArray(officialProviders)) return officialProviders.some((p) => provider === p);
+	return defaultIsOfficial(provider);
 }
-
 /** 阻止时抛出的提示文案，用户可见，随界面失败信息呈现。 */
-export const BLOCK_MESSAGE =
-  '【梁文峰时间拦截 · dsh-peak-block】当前为 DeepSeek 官方高峰时段，且未配置拦截目标 targetProvider，请求已阻止。请为 dsh-peak-block 配置 targetProvider，或将请求留到梁文谷时段再发。'
-
+const BLOCK_MESSAGE = "【梁文峰时间拦截 · dsh-peak-block】当前为 DeepSeek 官方高峰时段，且未配置拦截目标 targetProvider，请求已阻止。请为 dsh-peak-block 配置 targetProvider，或将请求留到梁文谷时段再发。";
 /**
- * 纯拦截决策，可单测：返回 { action: 'pass' | 'switch' | 'block', config? }。
- * - 非梁文峰时间或非官方 → pass，放行
- * - 梁文峰时间 + 官方 + 有目标 → switch，切 provider 到目标
- * - 梁文峰时间 + 官方 + 无目标 → block，阻止并提示
- */
-export function decide(seed, opts) {
-  if (!isPeakBeijing(opts.timeMs, opts.peakWindow)) return { action: 'pass' }
-  if (!isOfficial(seed && seed.provider, opts.officialProviders)) return { action: 'pass' }
-  if (opts.targetProvider) {
-    return { action: 'switch', config: { ...(seed || {}), provider: opts.targetProvider } }
-  }
-  return { action: 'block' }
+* 纯拦截决策，可单测：返回 { action: 'pass' | 'switch' | 'block', config? }。
+* - 非梁文峰时间或非官方 → pass，放行
+* - 梁文峰时间 + 官方 + 有目标 → switch，切 provider 到目标
+* - 梁文峰时间 + 官方 + 无目标 → block，阻止并提示
+*/
+function decide(seed, opts) {
+	if (!isPeakBeijing(opts.timeMs, opts.peakWindow)) return { action: "pass" };
+	if (!isOfficial(seed?.provider, opts.officialProviders)) return { action: "pass" };
+	if (opts.targetProvider) return {
+		action: "switch",
+		config: {
+			...seed ?? {},
+			provider: opts.targetProvider
+		}
+	};
+	return { action: "block" };
+}
+function apply(ctx, config = {}) {
+	if (config.enabled === false) return;
+	const peakWindow = config.peakWindow;
+	const officialProviders = config.officialProviders;
+	const targetProvider = config.targetProvider;
+	ctx.on("agent/request", async (_payload, next) => {
+		const seed = await next();
+		const decision = decide(seed, {
+			timeMs: Date.now(),
+			peakWindow,
+			officialProviders,
+			targetProvider
+		});
+		if (decision.action === "pass") return seed;
+		if (decision.action === "switch") return decision.config;
+		throw new Error(BLOCK_MESSAGE);
+	});
 }
-
-export function apply(ctx, config = {}) {
-  if (config.enabled === false) return
-  const peakWindow = config.peakWindow || DEFAULT_PEAK
-  const officialProviders = config.officialProviders
-  const targetProvider = config.targetProvider
-  ctx.on('agent/request', async (_payload, next) => {
-    const seed = await next()
-    const decision = decide(seed, {
-      timeMs: Date.now(),
-      peakWindow,
-      officialProviders,
-      targetProvider,
-    })
-    if (decision.action === 'pass') return seed
-    if (decision.action === 'switch') return decision.config
-    throw new Error(BLOCK_MESSAGE)
-  })
-}
+//#endregion
+export { BLOCK_MESSAGE, DEFAULT_PEAK, apply, decide, defaultIsOfficial, inject, isOfficial, isPeakBeijing, name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-peak-block",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "梁文峰时间拦截官方 DeepSeek API 请求：北京时间工作日高峰时段 09:00-12:00、14:00-18:00 自动拦截发往官方 provider `deepseek-official` 的模型请求，可切换到第三方中转或预留的本机转 API 端口，未配置则阻止并提示；非高峰不拦、正常走官方，专治高峰掉速与刷屏。标准可安装 dsh 插件，host 单半身，设置经 cordis 配置文件注入。",
   "keywords": [
     "deepseek-harness",
@@ -17,10 +17,16 @@
     "type": "git",
     "url": "git+https://github.com/better-er/dsh-peak-block.git"
   },
+  "author": "betterer",
+  "packageManager": "pnpm@9.15.9",
   "type": "module",
   "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "exports": {
-    ".": "./lib/index.js",
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
@@ -31,8 +37,21 @@
   },
   "files": [
     "lib/index.js",
+    "lib/index.d.ts",
     "cordis.patch.yml",
     "docs/"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "scripts": {
+    "build": "tsdown",
+    "prepare": "tsdown",
+    "typecheck": "tsc --noEmit --pretty false",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.1"
+  }
 }