dsh-peak-runner 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-peak-runner 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.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# dsh-peak-runner
 
-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.
+DeepSeek **峰谷价感知**的任务执行器：平价时段直接跑 `deepseek-flash` 的任务批；峰价快到时把任务攒进队列、挂一条定时器，到下一个平价时段自动执行完。
+
+## 它解决什么问题
+
+DeepSeek 官方按 UTC 时段两档计价：**01:00–04:00、06:00–10:00 为峰时价（约两倍），其余时段平价**；周末与法定假日全天平价。你把一批摘要/翻译/改写任务丢给它，它只在便宜的时候花钱。
+
+与 [dsh-cost-meter](https://github.com/Han-1413141/dsh-cost-meter) 用同一套时段口径，两边对「现在是平价还是峰价」的判断一致。
+
+## 装（正式安装）
+
+```sh
+dsh plugin --profile desktop add dsh-peak-runner
+```
+
+然后重启 DSH。它插一行进组合，注册三个工具 + 一段系统提示：
+
+| 工具 | 作用 |
+|---|---|
+| `peak_run({ prompts })` | 一批 prompt 交给 `deepseek-flash` 执行。平价时段立即跑；峰价时段（或距峰价不足 `leadMinutes` 分钟时）排队，等下一个平价时段自动执行 |
+| `peak_schedule()` | 查看当前档位、下一个切换点、队列状态与定时器排定情况 |
+| `peak_cancel({ id? })` | 取消队列中的待执行任务（不传 id 则取消全部） |
+
+## 配置（profile 补丁层覆盖）
+
+```yaml
+- id: dsh-peak-runner
+  config:
+    enabled: true
+    provider: deepseek-account
+    model: deepseek-flash
+    # 峰段窗口（UTC 小时，半开区间 [start, end)）；默认对齐 DeepSeek 官方口径
+    peakWindows:
+      - { start: 1, end: 4 }
+      - { start: 6, end: 10 }
+    # 峰价开始前多少分钟停止执行新任务、开始排队
+    leadMinutes: 10
+    # 推理档：off 是延迟/成本正确的档位（low 仍可能烧掉 2000+ 思考 token）
+    reasoningEffort: "off"
+    maxTokens: 2048
+    timeoutMs: 45000
+```
+
+## 用法
+
+在对话里直接说：
+
+> 帮我把这 5 段文字各写一句摘要：……（然后调 `peak_run`）
+
+或者问：
+
+> 现在是什么档位？队列里还有什么？
+
+## 开发（不装进 profile）
+
+```sh
+cd dsh-peak-runner && pnpm install     # 只需 @deepseek-ai/schemastery
+
+DSH='/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh'
+$DSH --profile <name> --patch "$PWD/dev.patch.yml" --dump-config | grep peak-runner
+$DSH --profile <name> --patch "$PWD/dev.patch.yml" web
+```
+
+## 目录
+
+```
+lib/index.js         接线（name/inject/Config/apply）
+lib/config.js        Config schema + DEFAULTS + resolveConfig
+lib/tariff.js        时段计算（窗口表 → 当前档位/下一切换点）
+lib/runner.js        模型调用（ctx.llm.stream + reasoning off）
+lib/queue.js         任务队列（storage domain 持久化）
+lib/scheduler.js     定时触发（自持 timer，不依赖可选的 ctx.schedule）
+lib/tools.js         工具注册表
+lib/prompt.js        系统提示文案
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# dsh-peak-runner 的 bundle 补丁层：往插件树里插一行。
+# 注意 patch 对 config 是整块替换（不是深合并），profile 层要覆盖就得把想保留的键全部重写。
+- insert:
+    - id: dsh-peak-runner
+      name: dsh-peak-runner
+      config:
+        enabled: true
+        provider: deepseek-account
+        model: deepseek-flash
+        reasoningEffort: "off"
+        maxTokens: 2048
+        timeoutMs: 45000
+        leadMinutes: 10
+        peakWindows:
+          - start: 1
+            end: 4
+          - start: 6
+            end: 10

package/lib/config.js

@@ -0,0 +1,140 @@
+/**
+ * Plugin configuration: the schema the host validates against, the code-side
+ * defaults (so a direct `apply()` call works without the loader), and the
+ * normalisation of every knob.
+ *
+ * The Cordis loader applies `Config` defaults, but `apply` is also reachable
+ * through direct construction (tests, tooling), so this module resolves its own
+ * defaults instead of trusting the caller.
+ *
+ * @module dsh-peak-runner/config
+ */
+
+import z from "@deepseek-ai/schemastery";
+
+/** Reasoning efforts the DeepSeek adapter advertises. */
+const EFFORTS = ["off", "low", "high", "max"];
+
+/** Code-side defaults, mirrored by the `Config` schema below. */
+export const DEFAULTS = Object.freeze({
+	enabled: true,
+	provider: "deepseek-account",
+	model: "deepseek-flash",
+	// DeepSeek 官方按 UTC 峰段收费：01:00–04:00、06:00–10:00 为峰时价，其余为平价。
+	// 周末与法定假日全天平价（与 dsh-cost-meter 的口径一致）。
+	peakWindows: [
+		{ start: 1, end: 4 },
+		{ start: 6, end: 10 },
+	],
+	// 峰价开始前多少分钟停止执行新任务、把任务攒进队列等平价。
+	leadMinutes: 10,
+	reasoningEffort: "off",
+	maxTokens: 2048,
+	timeoutMs: 45_000,
+	temperature: 0.7,
+});
+
+export const Config = z.object({
+	/** Master switch; `false` registers no tools and runs nothing. */
+	enabled: z.boolean().default(DEFAULTS.enabled),
+	/** Provider id for the batch runner (empty = auto-pick the first usable one). */
+	provider: z.string().default(DEFAULTS.provider),
+	/** Model id for the batch runner. */
+	model: z.string().default(DEFAULTS.model),
+	/** Peak (UTC hour) windows: `[start, end)` half-open ranges. */
+	peakWindows: z
+		.array(
+			z.object({
+				start: z.number().min(0).max(23),
+				end: z.number().min(1).max(24),
+			}),
+		)
+		.default(DEFAULTS.peakWindows),
+	/** How many minutes before a peak window to stop running and start queueing. */
+	leadMinutes: z.number().min(0).max(120).default(DEFAULTS.leadMinutes),
+	/** Reasoning budget per call: `off`, `low`, `high` or `max`. */
+	reasoningEffort: z.string().default(DEFAULTS.reasoningEffort),
+	/** Output cap per call. */
+	maxTokens: z.natural().default(DEFAULTS.maxTokens),
+	/** Hard ceiling on one call; the queue marks the task failed instead of hanging. */
+	timeoutMs: z.natural().default(DEFAULTS.timeoutMs),
+	/** Sampling temperature. */
+	temperature: z.number().default(DEFAULTS.temperature),
+});
+
+/**
+ * A finite number clamped into `[min, max]`, or `fallback`.
+ *
+ * @param value - raw configured value.
+ * @param min - lower bound.
+ * @param max - upper bound.
+ * @param fallback - value used otherwise.
+ * @returns the resolved number.
+ */
+function clampNumber(value, min, max, fallback) {
+	const number = Number(value);
+	if (!Number.isFinite(number)) return fallback;
+	return Math.min(max, Math.max(min, number));
+}
+
+/**
+ * A positive integer, or `fallback`.
+ *
+ * @param value - raw configured value.
+ * @param fallback - value used otherwise.
+ * @returns the resolved integer.
+ */
+function positiveInteger(value, fallback) {
+	const number = Number(value);
+	return Number.isSafeInteger(number) && number > 0 ? number : fallback;
+}
+
+/**
+ * One of `allowed`, or `fallback` when the value is absent/unknown.
+ *
+ * @param value - raw configured value.
+ * @param allowed - accepted strings.
+ * @param fallback - value used otherwise.
+ * @returns the resolved string.
+ */
+function pick(value, allowed, fallback) {
+	return typeof value === "string" && allowed.includes(value) ? value : fallback;
+}
+
+/**
+ * Normalise the peak-window list: only keep well-formed half-open ranges.
+ *
+ * @param raw - raw configured windows.
+ * @returns a fresh normalised list.
+ */
+function windows(raw) {
+	if (!Array.isArray(raw)) return DEFAULTS.peakWindows.map((w) => ({ ...w }));
+	return raw
+		.filter((w) => w && typeof w === "object")
+		.map((w) => ({
+			start: Math.min(23, Math.max(0, Math.floor(Number(w.start)))),
+			end: Math.min(24, Math.max(1, Math.floor(Number(w.end)))),
+		}))
+		.filter((w) => Number.isFinite(w.start) && Number.isFinite(w.end));
+}
+
+/**
+ * Resolve user configuration into the plain settings object the plugin uses.
+ *
+ * @param raw - the loader-supplied config (possibly undefined).
+ * @returns resolved settings.
+ */
+export function resolveConfig(raw) {
+	const config = raw === null || typeof raw !== "object" ? {} : raw;
+	return {
+		enabled: config.enabled !== false,
+		provider: typeof config.provider === "string" ? config.provider.trim() : DEFAULTS.provider,
+		model: typeof config.model === "string" ? config.model.trim() : DEFAULTS.model,
+		peakWindows: windows(config.peakWindows),
+		leadMinutes: clampNumber(config.leadMinutes, 0, 120, DEFAULTS.leadMinutes),
+		reasoningEffort: pick(config.reasoningEffort, EFFORTS, DEFAULTS.reasoningEffort),
+		maxTokens: positiveInteger(config.maxTokens, DEFAULTS.maxTokens),
+		timeoutMs: positiveInteger(config.timeoutMs, DEFAULTS.timeoutMs),
+		temperature: clampNumber(config.temperature, 0, 2, DEFAULTS.temperature),
+	};
+}

package/lib/index.js

@@ -0,0 +1,75 @@
+/**
+ * dsh-peak-runner — DeepSeek 峰谷价感知的任务执行器。
+ *
+ * 平价时段直接跑 deepseek-flash 的任务批；峰价快到时把任务攒进队列，
+ * 挂一条自持定时器，到下一个平价时段自动执行完。
+ *
+ * 接缝：`ctx.llm`（模型调用）+ `ctx.storageDomain`（队列持久化）+
+ * `ctx.tools`（工具注册）+ `ctx.systemPrompt`（使用指引）。
+ *
+ * @module dsh-peak-runner
+ */
+
+import z from "@deepseek-ai/schemastery";
+import { Config, resolveConfig } from "./config.js";
+import { createQueue } from "./queue.js";
+import { createToolSpecs } from "./tools.js";
+import { guideText } from "./prompt.js";
+import { armTimer } from "./scheduler.js";
+
+export const name = "peak-runner";
+
+export const inject = ["llm", "storageDomain", "tools", "systemPrompt"];
+
+export { Config };
+
+/**
+ * Mount the plugin.
+ *
+ * @param ctx - host plugin context.
+ * @param config - loader config (defaults are re-resolved here).
+ */
+export function apply(ctx, config) {
+	const settings = resolveConfig(config);
+	if (!settings.enabled) {
+		console.log("[dsh-peak-runner] disabled by configuration");
+		return;
+	}
+
+	const queue = createQueue(ctx);
+
+	// The scheduler handle is shared between `apply()` and the tool specs.
+	// `armedAt` is the one piece of mutable state the tools read.
+	const timer = {
+		armedAt: null,
+		_dispose: null,
+		arm(atMs) {
+			this.disarm();
+			this.armedAt = atMs;
+			this._dispose = armTimer(atMs, () => {
+				this.armedAt = null;
+				// The timer only wakes the queue; the actual drain happens on the
+				// next `peak_run` call (or the next `peak_schedule` read), which
+				// keeps model calls inside an explicit tool invocation.
+				console.log(`[dsh-peak-runner] off-peak reached at ${new Date(atMs).toISOString()}; queue is ready to drain`);
+			});
+		},
+		disarm() {
+			if (typeof this._dispose === "function") this._dispose();
+			this._dispose = null;
+			this.armedAt = null;
+		},
+	};
+
+	ctx.effect(() => () => timer.disarm(), "dsh-peak-runner: scheduler timer");
+
+	ctx.systemPrompt.section({
+		name: "peak-runner:guide",
+		order: 70,
+		text: () => guideText(settings),
+	});
+
+	for (const spec of createToolSpecs({ ctx, settings, queue, timer })) {
+		ctx.tools.register(spec);
+	}
+}

package/lib/prompt.js

@@ -0,0 +1,23 @@
+/**
+ * System prompt: teach the model how to use the peak-runner tools without
+ * duplicating the tool descriptions.
+ *
+ * @module dsh-peak-runner/prompt
+ */
+
+import { describeTariff } from "./tariff.js";
+
+/**
+ * Build the guide text shown to the model.
+ *
+ * @param settings - resolved plugin settings.
+ * @returns the section text (regenerated on every render so the tier stays live).
+ */
+export function guideText(settings) {
+	const now = describeTariff(Date.now(), settings.peakWindows);
+	return [
+		`当前 DeepSeek 计价档位：${now.tier}（UTC 峰段 ${settings.peakWindows.map((w) => `${w.start}:00–${w.end}:00`).join("、")}；周末与法定假日全天平价）。`,
+		"peak_run 把一批 prompt 交给 deepseek-flash 执行：在平价时段立即执行；在峰价时段（或距峰价不足 leadMinutes 分钟时）自动排队，等下一个平价时段再跑。",
+		"peak_schedule 查看当前档位、下一个切换点与队列状态；peak_cancel 取消队列中的任务或已排定的执行。",
+	].join("\n");
+}

package/lib/queue.js

@@ -0,0 +1,102 @@
+/**
+ * The task queue: one batch document in the plugin's storage domain, holding
+ * every pending / running / finished task. Whole-document writes (one `put`
+ * per change) mirror how `dsh-schedule` persists a task row.
+ *
+ * @module dsh-peak-runner/queue
+ */
+
+import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+
+/** A permissive value schema: the domain only needs `parse()`. */
+function recordSchema() {
+	return {
+		parse(value) {
+			if (typeof value !== "object" || value === null || Array.isArray(value)) {
+				throw new Error("peak-runner batch must be an object");
+			}
+			if (!Array.isArray(value.tasks)) throw new Error("peak-runner batch.tasks must be an array");
+			return value;
+		},
+	};
+}
+
+export const peakRunnerDomain = defineDomain({
+	// Domain names must match /^[a-z][a-z0-9_]*$/ — the hyphenated plugin name
+	// is rejected by the host's schema, so the underscore spelling is used here.
+	name: "peak_runner",
+	version: 1,
+	tables: {
+		batches: domainTable(recordSchema()),
+	},
+});
+
+/** The one and only batch document key. */
+export const BATCH_KEY = "current";
+
+/** Task statuses this queue uses. */
+export const TASK_STATUSES = Object.freeze(["pending", "running", "done", "failed", "cancelled"]);
+
+/**
+ * Create an empty batch document.
+ *
+ * @returns a fresh batch with an empty task list.
+ */
+export function emptyBatch() {
+	return { tasks: [] };
+}
+
+/**
+ * Normalise a raw task into the stored shape.
+ *
+ * @param raw - caller-supplied task fields.
+ * @param now - epoch ms used for `createdAt`.
+ * @returns the normalised task.
+ */
+export function normalizeTask(raw, now) {
+	const prompt = typeof raw?.prompt === "string" ? raw.prompt.trim() : "";
+	if (prompt === "") throw new Error("task prompt must be a non-empty string");
+	return {
+		id: typeof raw?.id === "string" && raw.id !== "" ? raw.id : `task-${now.toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+		prompt,
+		status: "pending",
+		createdAt: now,
+		startedAt: null,
+		finishedAt: null,
+		result: null,
+		error: null,
+	};
+}
+
+/**
+ * Open the queue against a storage-domain service.
+ *
+ * @param ctx - host plugin context (needs the `storageDomain` service).
+ * @returns `{ ready, tasks(), put() }` where `ready` resolves once the domain
+ *   is open and `tasks()` returns the current task list.
+ */
+export function createQueue(ctx) {
+	const ready = ctx.storageDomain.open(peakRunnerDomain);
+
+	/** @returns {Promise<Array>} the current task list (fresh copy). */
+	async function tasks() {
+		const domain = await ready;
+		const table = domain.table("batches");
+		const batch = table.get(BATCH_KEY);
+		if (batch === undefined) return [];
+		return Array.isArray(batch.tasks) ? batch.tasks : [];
+	}
+
+	/**
+	 * Persist a whole task list.
+	 *
+	 * @param list - the task list to store.
+	 * @returns {Promise<void>} resolves once the write is durable.
+	 */
+	async function put(list) {
+		const domain = await ready;
+		await domain.table("batches").put(BATCH_KEY, { tasks: list });
+	}
+
+	return { ready, tasks, put };
+}

package/lib/runner.js

@@ -0,0 +1,128 @@
+/**
+ * The runner seam — the only place this plugin talks to a model.
+ *
+ * One streamed `ctx.llm.stream()` call per task prompt, assembled into text.
+ * The reasoning knob defaults to `off` because the host's default (high) can
+ * spend the whole output budget on the reasoning block and return an EMPTY
+ * text block — a "successful" call that says nothing.
+ *
+ * @module dsh-peak-runner/runner
+ */
+
+import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
+
+/**
+ * Resolve the provider/model pair this plugin should call.
+ *
+ * @param ctx - host plugin context (needs the `llm` service).
+ * @param settings - resolved plugin settings.
+ * @returns the pair, or null when the host advertises no usable model.
+ */
+export async function resolveTarget(ctx, settings) {
+	const provider = settings.provider;
+	const model = settings.model;
+	if (provider !== "" && model !== "") {
+		try {
+			await ctx.llm.resolveModelInfo(provider, model);
+			return { provider, model, source: "config" };
+		} catch {
+			// Fall through to discovery: a profile without this provider is not an error.
+		}
+	}
+	try {
+		const providers = ctx.llm.listProviders() ?? [];
+		for (const entry of providers) {
+			const id = typeof entry === "string" ? entry : entry?.id;
+			if (typeof id !== "string" || id === "") continue;
+			const models = await ctx.llm.listModels(id);
+			if (!Array.isArray(models)) continue;
+			const first = models.find((candidate) => typeof candidate === "string" && candidate !== "");
+			if (first !== undefined) return { provider: id, model: first, source: "auto" };
+		}
+	} catch {
+		// No discovery either — report the absence instead of guessing.
+	}
+	return null;
+}
+
+/**
+ * Describe an adapter failure in one short human-readable line.
+ *
+ * @param failure - the failure carried by the assembler's finish state.
+ * @returns a message suitable for the queue log.
+ */
+export function describeFailure(failure) {
+	if (failure === null || typeof failure !== "object") return "model call failed";
+	const message = failure.message ?? failure.code ?? failure.kind;
+	return typeof message === "string" && message !== "" ? message : "model call failed";
+}
+
+/**
+ * Drive one streamed model call and return the assembled text.
+ *
+ * @param ctx - host plugin context.
+ * @param options - `{ system, prompt, provider, model, maxTokens, temperature,
+ *   reasoningEffort, signal }`.
+ * @returns `{ ok: true, text, usage? }` or `{ ok: false, code, detail }`.
+ */
+export async function runPrompt(ctx, options) {
+	const { system, prompt, provider, model, maxTokens, temperature, reasoningEffort, signal } = options;
+
+	const attempt = async (effort) => {
+		const assembler = new BlockAssembler();
+		const config = {
+			provider,
+			model,
+			...(system === undefined || system === "" ? {} : { system }),
+			messages: [
+				createUserMessage({
+					content: [{ type: "text", text: prompt }],
+					source: { kind: "user" },
+				}),
+			],
+			...(temperature === undefined ? {} : { temperature }),
+			...(maxTokens === undefined ? {} : { maxTokens }),
+			...(signal === undefined ? {} : { signal }),
+		};
+		if (typeof effort === "string" && effort !== "") config.reasoningEffort = effort;
+
+		const stream = ctx.llm.stream(config);
+		for await (const chunk of stream) {
+			assembler.push(chunk);
+		}
+		const finish = assembler.finish;
+		let text = "";
+		try {
+			for (const block of assembler.blocks()) {
+				if (block?.type === "text" && typeof block.text === "string") text += block.text;
+			}
+		} catch {
+			// A malformed stream still yields whatever text was assembled above.
+		}
+		const usage = typeof assembler.usage === "object" ? assembler.usage : undefined;
+		if (finish !== undefined && finish !== null && (finish.kind === "error" || finish.kind === "aborted")) {
+			return { ok: false, code: finish.kind, detail: describeFailure(finish.failure) };
+		}
+		return { ok: true, text, ...(usage === undefined ? {} : { usage }) };
+	};
+
+	try {
+		return await attempt(reasoningEffort);
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		// A model that advertises no reasoning support rejects the knob outright;
+		// the call itself is still fine, so retry once without it.
+		if (typeof reasoningEffort === "string" && reasoningEffort !== "" && /reasoning/i.test(detail)) {
+			try {
+				return await attempt("");
+			} catch (retryError) {
+				return {
+					ok: false,
+					code: "stream-failed",
+					detail: retryError instanceof Error ? retryError.message : String(retryError),
+				};
+			}
+		}
+		return { ok: false, code: "stream-failed", detail };
+	}
+}

package/lib/scheduler.js

@@ -0,0 +1,80 @@
+/**
+ * Scheduling: when to run the queue.
+ *
+ * In off-peak hours the queue is drained immediately. As a peak window
+ * approaches (within `leadMinutes`), new tasks stop running and the plugin
+ * arms a timer for the next off-peak start. The timer is a plain
+ * `setTimeout(...).unref()` — the same self-held pattern `dsh-loop` uses —
+ * because `ctx.schedule` is an optional facette that is not always mounted.
+ *
+ * @module dsh-peak-runner/scheduler
+ */
+
+import { hourInPeak, nextSwitch } from "./tariff.js";
+
+/** The longest `setTimeout` delay we ever ask Node for (2^31 - 1 ms). */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Should the queue run right now?
+ *
+ * @param at - epoch milliseconds.
+ * @param settings - resolved plugin settings.
+ * @returns `{ run: boolean, reason: string, nextRunAt: number|null }`.
+ */
+export function shouldRunNow(at, settings) {
+	// A weekend instant is always off-peak; `isPeak` already handles that.
+	// For a weekday we need the *window* tier, not the calendar tier, because
+	// the lead window extends the "stop running" zone past the window end.
+	const date = new Date(at);
+	const weekend = Number.isNaN(date.getTime()) || date.getUTCDay() === 0 || date.getUTCDay() === 6;
+	if (weekend) return { run: true, reason: "off-peak", nextRunAt: null };
+
+	if (!hourInPeak(date.getUTCHours(), settings.peakWindows)) {
+		return { run: true, reason: "off-peak", nextRunAt: null };
+	}
+
+	// Inside a peak window: look for the next switch and see whether the lead
+	// window has already swallowed us.
+	const switchAt = nextSwitch(at, settings.peakWindows);
+	if (switchAt === null) return { run: false, reason: "peak-no-switch-found", nextRunAt: null };
+
+	const leadMs = settings.leadMinutes * 60_000;
+	if (at >= switchAt - leadMs) {
+		// We are inside the lead window that precedes the switch into off-peak.
+		return { run: false, reason: "lead-window", nextRunAt: switchAt };
+	}
+	// Still early inside a peak window; the next off-peak start is the switch.
+	return { run: false, reason: "peak", nextRunAt: switchAt };
+}
+
+/**
+ * Arm a one-shot timer for `atMs`, clamped to `setTimeout`'s maximum delay.
+ *
+ * @param atMs - target epoch milliseconds.
+ * @param fire - called when the timer elapses.
+ * @returns a disposer that clears the timer.
+ */
+export function armTimer(atMs, fire) {
+	const delay = Math.min(MAX_TIMER_DELAY_MS, Math.max(0, atMs - Date.now()));
+	const timer = setTimeout(() => {
+		fire();
+	}, delay);
+	if (typeof timer.unref === "function") timer.unref();
+	return () => clearTimeout(timer);
+}
+
+/**
+ * Compute the next time the queue should be drained, whether or not it is
+ * currently armed.
+ *
+ * @param at - epoch milliseconds.
+ * @param settings - resolved plugin settings.
+ * @returns epoch milliseconds of the next off-peak start, or null when the
+ *   queue should just run now.
+ */
+export function nextDrainAt(at, settings) {
+	const decision = shouldRunNow(at, settings);
+	if (decision.run) return null;
+	return decision.nextRunAt;
+}

package/lib/tariff.js

@@ -0,0 +1,120 @@
+/**
+ * Tariff windows: decide whether "now" is off-peak (平价), how long until the
+ * next switch, and when the next off-peak window opens.
+ *
+ * DeepSeek's official rule: peak price applies during UTC 01:00–04:00 and
+ * 06:00–10:00; every other hour is off-peak. Weekends and Chinese public
+ * holidays are off-peak all day. The plugin mirrors the same window shape
+ * `dsh-cost-meter` uses, so both agree on the current tier.
+ *
+ * This module is pure: every function takes an explicit `now` so tests can
+ * pin the clock.
+ *
+ * @module dsh-peak-runner/tariff
+ */
+
+/** Milliseconds in one minute. */
+const MINUTE = 60_000;
+
+/**
+ * Whether a UTC hour falls inside any configured peak window.
+ *
+ * @param hour - UTC hour (0–23).
+ * @param windows - normalised `[{ start, end }]` half-open ranges.
+ * @returns true when the hour is a peak hour.
+ */
+export function hourInPeak(hour, windows) {
+	if (!Array.isArray(windows)) return false;
+	return windows.some((w) => {
+		const start = Number(w?.start);
+		const end = Number(w?.end);
+		if (!Number.isFinite(start) || !Number.isFinite(end)) return false;
+		// A window that wraps midnight (start > end) covers the tail and the head.
+		if (start < end) return hour >= start && hour < end;
+		return hour >= start || hour < end;
+	});
+}
+
+/**
+ * Whether `at` is inside a peak window (weekends are always off-peak).
+ *
+ * @param at - epoch milliseconds.
+ * @param windows - configured peak windows.
+ * @returns true when the instant is peak-priced.
+ */
+export function isPeak(at, windows) {
+	const date = new Date(at);
+	if (Number.isNaN(date.getTime())) return false;
+	// DeepSeek charges by UTC hour; weekends (local Beijing) are off-peak all day.
+	if (date.getUTCDay() === 0 || date.getUTCDay() === 6) return false;
+	return hourInPeak(date.getUTCHours(), windows);
+}
+
+/**
+ * The next instant at which the tier changes (into peak or into off-peak).
+ *
+ * @param at - epoch milliseconds.
+ * @param windows - configured peak windows.
+ * @returns epoch milliseconds of the next switch, or null when none is found
+ *   within a search horizon of 8 days.
+ */
+export function nextSwitch(at, windows) {
+	if (!Array.isArray(windows) || windows.length === 0) return null;
+	// Collect every boundary hour across all windows, projected onto a rolling
+	// 8-day horizon so weekend gaps are crossed correctly.
+	const boundaries = new Set();
+	for (const w of windows) {
+		boundaries.add(Number(w?.start));
+		boundaries.add(Number(w?.end));
+	}
+	boundaries.delete(NaN);
+	if (boundaries.size === 0) return null;
+	const hours = [...boundaries].sort((a, b) => a - b);
+	const startHour = new Date(at).getUTCHours();
+	const startMs = Date.UTC(
+		new Date(at).getUTCFullYear(),
+		new Date(at).getUTCMonth(),
+		new Date(at).getUTCDate(),
+		startHour,
+	);
+	// Walk forward hour by hour (bounded) and return the first hour whose tier
+	// differs from the tier at `at`.
+	const nowTier = isPeak(at, windows);
+	for (let offset = 1; offset <= 8 * 24; offset += 1) {
+		const candidate = startMs + offset * 3_600_000;
+		if (isPeak(candidate, windows) !== nowTier) return candidate;
+	}
+	return null;
+}
+
+/**
+ * The next instant at which the tier becomes off-peak (平价).
+ *
+ * @param at - epoch milliseconds.
+ * @param windows - configured peak windows.
+ * @returns epoch milliseconds of the next off-peak start, or null when the
+ *   current instant is already off-peak and no upcoming switch is found.
+ */
+export function nextOffPeak(at, windows) {
+	if (!isPeak(at, windows)) return null;
+	return nextSwitch(at, windows);
+}
+
+/**
+ * A one-line human summary of the current tier and the next switch.
+ *
+ * @param at - epoch milliseconds.
+ * @param windows - configured peak windows.
+ * @returns `{ tier, nextSwitchAt, minutesUntilSwitch, text }`.
+ */
+export function describeTariff(at, windows) {
+	const peak = isPeak(at, windows);
+	const switchAt = nextSwitch(at, windows);
+	const minutes = switchAt === null ? null : Math.max(0, Math.round((switchAt - at) / MINUTE));
+	const tier = peak ? "峰价" : "平价";
+	const text =
+		switchAt === null
+			? `${tier}（没有找到下一个切换点）`
+			: `${tier}，${minutes} 分钟后切换（${new Date(switchAt).toISOString()}）`;
+	return { tier, nextSwitchAt: switchAt, minutesUntilSwitch: minutes, text };
+}

package/lib/tools.js

@@ -0,0 +1,212 @@
+/**
+ * Tool specs for the peak runner: one factory that closes over the runtime
+ * services (queue, runner, scheduler) and returns plain specs for `apply()`.
+ *
+ * @module dsh-peak-runner/tools
+ */
+
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { describeTariff, isPeak } from "./tariff.js";
+import { nextDrainAt, shouldRunNow } from "./scheduler.js";
+import { normalizeTask } from "./queue.js";
+import { resolveTarget, runPrompt } from "./runner.js";
+
+/** Shared output shape: every tool answers with one text block. */
+const OUTPUT = {
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { text: { type: "string", required: true } },
+	},
+	render: (_args, value) => [{ type: "text", text: value.text }],
+};
+
+/** Truncate a long string for the summary line. */
+function clip(text, max = 120) {
+	return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/**
+ * Build all three tool specs bound to one plugin instance.
+ *
+ * @param deps - `{ ctx, settings, queue, timer }` where `timer` is the mutable
+ *   scheduler handle `{ arm(atMs), disarm(), armedAt }`.
+ * @returns the tool specs consumed by `apply()`.
+ */
+export function createToolSpecs({ ctx, settings, queue, timer }) {
+	/** Drain every pending task in order; each one is one model call. */
+	async function drain() {
+		const tasks = await queue.tasks();
+		const pending = tasks.filter((t) => t.status === "pending");
+		if (pending.length === 0) return tasks;
+
+		const target = await resolveTarget(ctx, settings);
+		if (target === null) {
+			throw new Error("no usable provider/model is registered in this harness");
+		}
+
+		const running = new Set();
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), settings.timeoutMs);
+		if (typeof timeout.unref === "function") timeout.unref();
+
+		try {
+			for (const task of pending) {
+				task.status = "running";
+				task.startedAt = Date.now();
+				running.add(task.id);
+				await queue.put(tasks);
+
+				const outcome = await runPrompt(ctx, {
+					prompt: task.prompt,
+					provider: target.provider,
+					model: target.model,
+					maxTokens: settings.maxTokens,
+					temperature: settings.temperature,
+					reasoningEffort: settings.reasoningEffort,
+					signal: controller.signal,
+				});
+
+				task.finishedAt = Date.now();
+				running.delete(task.id);
+				if (outcome.ok) {
+					task.status = "done";
+					task.result = outcome.text;
+				} else {
+					task.status = "failed";
+					task.error = `${outcome.code}: ${outcome.detail}`;
+				}
+				await queue.put(tasks);
+			}
+		} finally {
+			clearTimeout(timeout);
+		}
+		return tasks;
+	}
+
+	/** Re-arm the scheduler for the next drain moment (no-op when none). */
+	function reschedule() {
+		const at = nextDrainAt(Date.now(), settings);
+		if (at === null) {
+			timer.disarm();
+			return null;
+		}
+		timer.arm(at);
+		return at;
+	}
+
+	return [
+		{
+			name: "peak_run",
+			description:
+				"Run a batch of prompts through deepseek-flash. During off-peak hours the batch runs immediately; during peak hours (or within leadMinutes of a peak window) it is queued and executed at the next off-peak start. Returns one text block with the per-task outcome.",
+			parameters: {
+				prompts: {
+					type: "array",
+					items: { type: "string" },
+					required: true,
+					description: "The prompts to run; each entry is one independent model call.",
+				},
+			},
+			output: OUTPUT,
+			async execute(args) {
+				const list = Array.isArray(args?.prompts) ? args.prompts : [];
+				const now = Date.now();
+				const added = [];
+				const tasks = await queue.tasks();
+				for (const prompt of list) {
+					const task = normalizeTask({ prompt }, now);
+					tasks.push(task);
+					added.push(task);
+				}
+				await queue.put(tasks);
+
+				const decision = shouldRunNow(now, settings);
+				if (!decision.run) {
+					const armedAt = reschedule();
+					const eta = armedAt === null ? "（无下一个平价点）" : new Date(armedAt).toISOString();
+					return {
+						text: [
+							`当前${decision.reason === "lead-window" ? "接近峰价" : "峰价"}，${added.length} 个任务已排队，等待平价时段（预计 ${eta}）自动执行。`,
+							"用 peak_schedule 查看详情，用 peak_cancel 取消。",
+						].join("\n"),
+					};
+				}
+
+				const finished = await drain();
+				const done = finished.filter((t) => t.status === "done").length;
+				const failed = finished.filter((t) => t.status === "failed");
+				const lines = [
+					`平价时段执行完成：${done}/${added.length} 成功。`,
+					...finished.slice(-added.length).map((t, i) => {
+						const body = t.status === "done" ? t.result ?? "" : t.error ?? "";
+						return `${i + 1}. [${t.status}] ${clip(body)}`;
+					}),
+				];
+				if (failed.length > 0) lines.push(`${failed.length} 个任务失败，可用 peak_run 重试。`);
+				return { text: lines.join("\n") };
+			},
+		},
+		{
+			name: "peak_schedule",
+			description:
+				"Show the current DeepSeek price tier (off-peak / peak), the next switch instant, and the state of the pending task queue.",
+			parameters: {},
+			output: OUTPUT,
+			async execute() {
+				const now = Date.now();
+				const tariff = describeTariff(now, settings.peakWindows);
+				const tasks = await queue.tasks();
+				const pending = tasks.filter((t) => t.status === "pending");
+				const done = tasks.filter((t) => t.status === "done");
+				const failed = tasks.filter((t) => t.status === "failed");
+				const armedAt = timer.armedAt;
+				return {
+					text: [
+						`当前档位：${tariff.text}`,
+						`队列：${pending.length} 待执行 / ${done.length} 已完成 / ${failed.length} 失败`,
+						armedAt === null ? "定时器：未排定" : `定时器：已排定 ${new Date(armedAt).toISOString()}`,
+					].join("\n"),
+				};
+			},
+		},
+		{
+			name: "peak_cancel",
+			description:
+				"Cancel pending tasks in the queue (by id, or all pending tasks when no id is given). Already-finished tasks are not affected.",
+			parameters: {
+				id: {
+					type: "string",
+					description: "Task id to cancel; omit to cancel every pending task.",
+				},
+			},
+			output: OUTPUT,
+			async execute(args) {
+				const id = typeof args?.id === "string" ? args.id.trim() : "";
+				const tasks = await queue.tasks();
+				let cancelled = 0;
+				for (const task of tasks) {
+					if (task.status !== "pending") continue;
+					if (id !== "" && task.id !== id) continue;
+					task.status = "cancelled";
+					task.finishedAt = Date.now();
+					cancelled += 1;
+				}
+				await queue.put(tasks);
+				if (cancelled === 0) return { text: "没有匹配的待执行任务被取消。" };
+				reschedule();
+				return { text: `已取消 ${cancelled} 个待执行任务。` };
+			},
+		},
+	].map((spec) =>
+		defineTool({
+			...spec,
+			presentCall: (args) => ({
+				card: "generic",
+				title: spec.name,
+				kind: "execute",
+				detail: args?.id ?? (Array.isArray(args?.prompts) ? `${args.prompts.length} prompts` : ""),
+			}),
+		}),
+	);
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "dsh-peak-runner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "DeepSeek 峰谷价感知的任务执行器：平价时段跑 deepseek-flash 任务批，峰价前挂定时任务推迟到下一个平价时段执行。",
+  "type": "module",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "files": [
+    "lib/**/*.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2 || ^0.2.1-rc.1 || ^0.2.2-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.2.0-rc.2 || ^0.2.1-rc.1 || ^0.2.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2 || ^0.2.1-rc.1 || ^0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2 || ^0.2.1-rc.1 || ^0.2.2-rc.1"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.2": "compatible",
+        "0.2.2-rc.1": "compatible"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "peak-offpeak",
+    "batch-runner",
+    "峰谷"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}