@deepmaid/maid-cron 0.1.0-alpha.1 → 0.1.0-alpha.3

package/lib/index.d.ts

@@ -24,6 +24,12 @@ interface JobDeclaration {
   maidId: string;
   type?: string;
   name?: string;
+  /**
+   * M3f:该 job 的基底模式壳(默认 = maid 的 basePreset ?? preset)。声明为非 maid 自带
+   * preset(如 cordis/standard)时,cron 会话 = 基底壳 + maidComposer 差异层(persona/
+   * anchor/gestures/veil);maidComposer 未挂 → fail-loud 拒绝生成(半人格防线)。
+   */
+  basePreset?: string;
   enabled?: boolean;
   schedule: JobSchedule;
   promptTemplate?: string;
@@ -45,6 +51,7 @@ interface CompiledJob {
   jobId: string;
   type: string;
   maidId: string;
+  basePreset: string | undefined;
   enabled: boolean;
   kind: 'script' | 'llm';
   promptTemplate: string;
@@ -74,12 +81,24 @@ declare function renderBriefingPrompt(template: string, vars: {
 //#endregion
 //#region src/state.d.ts
 type RunStatus = 'ok' | 'ok-silent' | 'script-failed' | 'gen-failed' | 'deliver-failed' | 'misfire-skipped' | 'overlap-skipped';
+/** M3e §4.1:跨版本稳定受控读面(ok=成功/error=执行失败/skipped=未执行)。 */
+type RunOutcome = 'ok' | 'error' | 'skipped';
+/** M3e §4.1:失败分类受控枚举(调用点赋值,不从 lastError 反解析)。 */
+type RunFailureKind = 'script' | 'generation' | 'delivery' | 'timeout' | 'cancelled' | 'unknown';
+type RunSkipReason = 'overlap' | 'misfire';
 interface JobRunState {
   lastRunAt: string | undefined;
   lastStatus: RunStatus | undefined;
   lastError: string | undefined;
   misfireCount: number;
   nextDueAt: number | undefined;
+  /** M3e 可观测:受控三态读面(旧档经 loadState 归一化补水)。 */
+  lastOutcome?: RunOutcome | undefined;
+  failureKind?: RunFailureKind | undefined;
+  skipReason?: RunSkipReason | undefined;
+  lastSuccessAt?: string | undefined;
+  lastFailureAt?: string | undefined;
+  consecutiveFailures?: number | undefined;
 }
 type RunStateMap = Record<string, JobRunState>;
 declare function loadState(file: string): RunStateMap;
@@ -96,7 +115,9 @@ interface RecentMemory {
 //#region src/engine.d.ts
 interface EnginePorts {
   identity: {
-    presetOf(maidId: string): string | undefined;
+    /** M3f:basePreset 合成面——job.basePreset ?? record.basePreset ?? record.preset(job 级覆写进 engine)。 */
+    basePresetOf(maidId: string, jobBasePreset?: string): string | undefined;
+    maidOwnPresetOf(maidId: string): string | undefined;
     addressOf(maidId: string): {
       botId: string;
       targetId: string;
@@ -144,6 +165,9 @@ interface ResolvedCronConfig {
   } | undefined;
   agentSetup: ((agentCtx: unknown) => Promise<void>) | undefined;
   stateFile: string;
+  /** M3e §4.2:连续失败指数退避(base/max,毫秒;缺省不退避 = 行为零变化)。 */
+  failureBackoffBaseMs?: number;
+  failureBackoffMaxMs?: number;
   /** 终局观测回调:每次终局迁移(finish 各终局 + overlap-skipped/misfire-skipped)在 persist 之后触发,携带同一 status/error。 */
   onTerminal?: (jobId: string, status: RunStatus, error: string | undefined) => void;
 }
@@ -158,6 +182,9 @@ declare function createCronEngine(config: ResolvedCronConfig, jobs: readonly Com
 interface MaidCronConfig {
   tickIntervalMs?: number;
   misfireWindowMs?: number;
+  /** M3e §4.2:连续失败指数退避基数/封顶(毫秒);缺省不退避。 */
+  failureBackoffBaseMs?: number;
+  failureBackoffMaxMs?: number;
   recentLimit?: number;
   recentMaxChars?: number;
   timezone?: string;

package/lib/index.js

@@ -794,6 +794,7 @@ function compileJobs(jobs, warn) {
 			jobId,
 			type: decl.type ?? "briefing",
 			maidId: decl.maidId,
+			basePreset: decl.basePreset,
 			enabled: decl.enabled !== false,
 			kind,
 			promptTemplate: decl.promptTemplate ?? "",
@@ -851,13 +852,25 @@ function freshRunState() {
 		lastStatus: void 0,
 		lastError: void 0,
 		misfireCount: 0,
-		nextDueAt: void 0
+		nextDueAt: void 0,
+		lastOutcome: void 0,
+		failureKind: void 0,
+		skipReason: void 0,
+		lastSuccessAt: void 0,
+		lastFailureAt: void 0,
+		consecutiveFailures: 0
 	};
 }
 function loadState(file) {
 	if (!existsSync(file)) return {};
 	try {
-		return JSON.parse(readFileSync(file, "utf8"));
+		const raw = JSON.parse(readFileSync(file, "utf8"));
+		const normalized = {};
+		for (const [jobId, state] of Object.entries(raw)) normalized[jobId] = {
+			...freshRunState(),
+			...state
+		};
+		return normalized;
 	} catch {
 		return {};
 	}
@@ -869,6 +882,47 @@ function saveState(file, map) {
 	renameSync(tmp, file);
 }
 //#endregion
+//#region src/observability.ts
+const iso = (ms) => new Date(ms).toISOString();
+function applyOutcome(state, input) {
+	const { status, now } = input;
+	const next = {
+		...state,
+		lastStatus: status,
+		lastRunAt: iso(now)
+	};
+	if (status === "ok" || status === "ok-silent") {
+		next.lastOutcome = "ok";
+		next.lastSuccessAt = iso(now);
+		next.consecutiveFailures = 0;
+		next.failureKind = void 0;
+		next.lastError = void 0;
+		next.lastFailureAt = void 0;
+		next.skipReason = void 0;
+		return next;
+	}
+	if (status === "overlap-skipped" || status === "misfire-skipped") {
+		next.lastOutcome = "skipped";
+		next.skipReason = status === "overlap-skipped" ? "overlap" : "misfire";
+		next.lastError = void 0;
+		return next;
+	}
+	next.lastOutcome = "error";
+	next.failureKind = input.kind ?? "unknown";
+	next.lastError = input.error;
+	next.lastFailureAt = iso(now);
+	next.consecutiveFailures = (state.consecutiveFailures ?? 0) + 1;
+	next.skipReason = void 0;
+	return next;
+}
+function nextDueWithBackoff(input) {
+	const chained = nextDueAfter(input.schedule, input.due);
+	if (chained === null) return null;
+	if (input.consecutiveFailures <= 0) return Math.max(input.previousNextDueAt ?? 0, chained);
+	const backoff = input.now + Math.min(input.maxMs, input.baseMs * 2 ** (input.consecutiveFailures - 1));
+	return Math.max(input.previousNextDueAt ?? 0, chained, backoff);
+}
+//#endregion
 //#region src/script-runner.ts
 const KILL_GRACE_MS = 5e3;
 /**
@@ -997,12 +1051,25 @@ function createCronEngine(config, jobs, ports) {
 	}
 	async function runJob(job, due) {
 		const state = stateOf(job.jobId);
-		const finish = (status, error, runAt) => {
+		let deliveryPhase = false;
+		const finish = (status, error, runAt, kind) => {
+			const nowMs = ports.now();
+			Object.assign(state, applyOutcome(state, {
+				status,
+				now: nowMs,
+				...kind !== void 0 ? { kind } : {},
+				...error !== void 0 ? { error } : {}
+			}));
 			state.lastRunAt = new Date(runAt).toISOString();
-			state.lastStatus = status;
-			state.lastError = error;
-			const chained = nextDueAfter(job.schedule, due);
-			state.nextDueAt = chained === null ? void 0 : Math.max(state.nextDueAt ?? Number.NEGATIVE_INFINITY, chained);
+			state.nextDueAt = nextDueWithBackoff({
+				schedule: job.schedule,
+				due,
+				now: nowMs,
+				previousNextDueAt: state.nextDueAt,
+				consecutiveFailures: state.consecutiveFailures ?? 0,
+				baseMs: config.failureBackoffBaseMs ?? 0,
+				maxMs: config.failureBackoffMaxMs ?? 0
+			}) ?? void 0;
 			persist();
 			config.onTerminal?.(job.jobId, status, error);
 		};
@@ -1021,13 +1088,13 @@ function createCronEngine(config, jobs, ports) {
 				};
 			})();
 			if (dest === void 0) {
-				finish("gen-failed", `no delivery address for maid '${job.maidId}'`, due);
+				finish("gen-failed", `no delivery address for maid '${job.maidId}'`, due, "generation");
 				return;
 			}
 			if (job.kind === "script") {
 				const res = await runScript(job.script);
 				if (!res.ok) {
-					finish("script-failed", `${res.reason}: ${res.stderrTail}`.slice(0, 500), due);
+					finish("script-failed", `${res.reason}: ${res.stderrTail}`.slice(0, 500), due, "script");
 					return;
 				}
 				if (res.stdout.trim().length === 0) {
@@ -1044,17 +1111,18 @@ function createCronEngine(config, jobs, ports) {
 					finish("ok", void 0, due);
 					return;
 				}
+				deliveryPhase = true;
 				if ((await ports.delivery.send(job.maidId, dest.address, res.stdout)).sent) {
 					finish("ok", void 0, due);
 					return;
 				}
 				if (config.deliverRetryDelayMs > 0) await sleep(config.deliverRetryDelayMs);
 				const second = await ports.delivery.send(job.maidId, dest.address, res.stdout);
-				finish(second.sent ? "ok" : "deliver-failed", second.sent ? void 0 : `delivery failed: ${second.code}`, due);
+				finish(second.sent ? "ok" : "deliver-failed", second.sent ? void 0 : `delivery failed: ${second.code}`, due, second.sent ? void 0 : "delivery");
 				return;
 			}
 			if (config.agent === void 0) {
-				finish("gen-failed", "config.agent (provider/model) required", due);
+				finish("gen-failed", "config.agent (provider/model) required", due, "generation");
 				return;
 			}
 			const limit = job.recentLimit ?? config.recentLimit;
@@ -1063,7 +1131,7 @@ function createCronEngine(config, jobs, ports) {
 			if (job.script !== void 0) {
 				const res = await runScript(job.script);
 				if (!res.ok) {
-					finish("script-failed", `${res.reason}: ${res.stderrTail}`.slice(0, 500), due);
+					finish("script-failed", `${res.reason}: ${res.stderrTail}`.slice(0, 500), due, "script");
 					return;
 				}
 				if (res.stdout.trim().length === 0 && job.skipOnEmptyScriptOutput) {
@@ -1084,7 +1152,8 @@ function createCronEngine(config, jobs, ports) {
 				handle = await ports.agents.create({
 					sessionId,
 					meta: {
-						agentPreset: ports.identity.presetOf(job.maidId),
+						agentPreset: ports.identity.basePresetOf(job.maidId, job.basePreset),
+						maidId: job.maidId,
 						...config.agent.cwd !== void 0 ? { cwd: config.agent.cwd } : {}
 					},
 					agentOptions: {
@@ -1118,12 +1187,12 @@ function createCronEngine(config, jobs, ports) {
 				}, job.genTimeoutMs).unref?.();
 				await handle.agent.whenIdle();
 				if (timedOut) {
-					finish("gen-failed", `generation timeout after ${job.genTimeoutMs}ms`, due);
+					finish("gen-failed", `generation timeout after ${job.genTimeoutMs}ms`, due, "timeout");
 					return;
 				}
 				const text = texts.at(-1);
 				if (text === void 0) {
-					finish("gen-failed", "no assistant output", due);
+					finish("gen-failed", "no assistant output", due, "generation");
 					return;
 				}
 				if (dest.kind === "persist") {
@@ -1136,20 +1205,21 @@ function createCronEngine(config, jobs, ports) {
 					finish("ok", void 0, due);
 					return;
 				}
+				deliveryPhase = true;
 				if ((await ports.delivery.send(job.maidId, dest.address, text)).sent) {
 					finish("ok", void 0, due);
 					return;
 				}
 				if (config.deliverRetryDelayMs > 0) await sleep(config.deliverRetryDelayMs);
 				const second = await ports.delivery.send(job.maidId, dest.address, text);
-				finish(second.sent ? "ok" : "deliver-failed", second.sent ? void 0 : `delivery failed: ${second.code}`, due);
+				finish(second.sent ? "ok" : "deliver-failed", second.sent ? void 0 : `delivery failed: ${second.code}`, due, second.sent ? void 0 : "delivery");
 			} finally {
 				cancels.delete(job.jobId);
 				off();
 				await handle?.dispose();
 			}
 		} catch (error) {
-			finish("gen-failed", error instanceof Error ? error.message : String(error), due);
+			finish("gen-failed", error instanceof Error ? error.message : String(error), due, deliveryPhase ? "delivery" : "generation");
 		}
 	}
 	function tick(nowMs = ports.now()) {
@@ -1160,17 +1230,21 @@ function createCronEngine(config, jobs, ports) {
 			if (nowMs < state.nextDueAt) continue;
 			const due = state.nextDueAt;
 			if (inFlight.has(job.jobId)) {
+				Object.assign(state, applyOutcome(state, {
+					status: "overlap-skipped",
+					now: nowMs
+				}));
 				state.lastRunAt = new Date(nowMs).toISOString();
-				state.lastStatus = "overlap-skipped";
-				state.lastError = void 0;
 				state.nextDueAt = nextDueAfter(job.schedule, due) ?? void 0;
 				persist();
 				config.onTerminal?.(job.jobId, "overlap-skipped", void 0);
 				continue;
 			}
 			if (nowMs - due > config.misfireWindowMs) {
-				state.lastRunAt = new Date(nowMs).toISOString();
-				state.lastStatus = "misfire-skipped";
+				Object.assign(state, applyOutcome(state, {
+					status: "misfire-skipped",
+					now: nowMs
+				}));
 				state.misfireCount += 1;
 				state.nextDueAt = nextDueAfter(job.schedule, nowMs) ?? void 0;
 				persist();
@@ -1194,32 +1268,34 @@ function createCronEngine(config, jobs, ports) {
 	};
 }
 //#endregion
-//#region src/preset-mount.ts
+//#region src/maid-mount.ts
 /** registry 服务消费入口:reflect 免 inject 直读(照 maid-cron maidMemory 同款探测纪律)。 */
 function presetRegistryOf(ctx, serviceName) {
 	return ctx?.reflect.get(serviceName, false);
 }
 /**
-* 包装 agents.create:job 带 meta.agentPreset 时注入 setup 钩子,在 agent 装配期把
-* maid preset 挂进 agent scope(persona/工具/技能目录全部继承);与既有 opts.setup
-* (引擎侧 config.agentSetup)链式组合,挂载在前。
-* - 无 preset id → 不注入,fail-open(无 preset 的 job 与现状同);
-* - registry 缺失 / resolve 抛(未注册) / mount throw → 拒绝 create(fail-loud,
-*   job 以 gen-failed 落 state 可观测)。
+* 包装 agents.create(M3f):meta.maidId 在场且 mountPresets 通道开启时注入 setup 链——
+* registry.mount(meta.agentPreset) → (需差异层时)composer.setup(agentCtx, maidId) →
+* 既有 opts.setup。无 maidId / 无 agentPreset → 不注入(fail-open,现状行为)。
 */
-function createPresetMountingAgents(base, registry) {
-	return async (opts) => {
-		const presetId = opts.meta?.agentPreset;
-		if (typeof presetId !== "string" || presetId.length === 0) return base(opts);
+function createMaidMountingAgents(base, registry, opts) {
+	return async (createOpts) => {
+		const meta = createOpts.meta;
+		const maidId = meta?.maidId;
+		const presetId = meta?.agentPreset;
+		if (typeof maidId !== "string" || maidId.length === 0 || typeof presetId !== "string" || presetId.length === 0) return base(createOpts);
+		const needsComposer = presetId !== opts.maidOwnPresetOf(maidId);
 		if (registry === void 0) throw new Error("maid-cron: mountPresets 开启但 agentPresets registry 服务不可用——0.2.0 起预设须经插件行声明(profile patch 的 preset-doris 行),且宿主组合须含 @deepseek-ai/dsh-agent-preset-registry");
+		if (needsComposer && opts.composer === void 0) throw new Error(`maid-cron: job 声明 basePreset '${presetId}'(≠ maid 自带 preset)但 maidComposer 未挂载——差异层缺位即半人格会话,拒绝生成;请安装 @deepmaid/maid-composer 或改用 maid 自带 preset`);
 		const resolved = await registry.resolve(presetId);
-		const chained = typeof opts.setup === "function" ? opts.setup : void 0;
+		const chained = typeof createOpts.setup === "function" ? createOpts.setup : void 0;
 		const setup = async (agentCtx) => {
 			await registry.mount(agentCtx, resolved.id);
+			if (needsComposer) await opts.composer.setup(agentCtx, maidId);
 			await chained?.(agentCtx);
 		};
 		return base({
-			...opts,
+			...createOpts,
 			setup
 		});
 	};
@@ -1233,6 +1309,8 @@ const apply = (ctx, config) => {
 	const resolved = {
 		tickIntervalMs: config.tickIntervalMs ?? 3e4,
 		misfireWindowMs: config.misfireWindowMs ?? 36e5,
+		...config.failureBackoffBaseMs !== void 0 ? { failureBackoffBaseMs: config.failureBackoffBaseMs } : {},
+		...config.failureBackoffMaxMs !== void 0 ? { failureBackoffMaxMs: config.failureBackoffMaxMs } : {},
 		recentLimit: config.recentLimit ?? 10,
 		recentMaxChars: config.recentMaxChars ?? 1500,
 		timezone: config.timezone ?? "Asia/Shanghai",
@@ -1242,29 +1320,55 @@ const apply = (ctx, config) => {
 		stateFile: config.stateFile,
 		onTerminal: (jobId, status, error) => warn(`maid-cron: ${jobId} → ${status}${error !== void 0 ? ` (${error})` : ""}`)
 	};
-	const maidMemoryService = ctx.reflect.get("maidMemory", false);
-	if (maidMemoryService === void 0) warn("maid-cron: maidMemory 未挂载——晨报将不带记忆摘要");
-	const memory = maidMemoryService === void 0 ? void 0 : {
+	const lazyReflect = (name, onMiss) => {
+		let cached;
+		let warned = false;
+		return () => {
+			if (cached !== void 0) return cached;
+			const found = ctx.reflect.get(name, false);
+			if (found !== void 0) {
+				cached = found;
+				return found;
+			}
+			if (!warned) {
+				warned = true;
+				warn(onMiss);
+			}
+		};
+	};
+	const maidMemoryOf = lazyReflect("maidMemory", "maid-cron: maidMemory 未挂载——晨报将不带记忆摘要");
+	const memory = {
 		recent: (maidId, limit) => {
-			const ns = maidMemoryService.resolveNamespace(ctx.maidIdentity.get(maidId)?.preset);
+			const maidMemoryService = maidMemoryOf();
+			if (maidMemoryService === void 0) return Promise.resolve([]);
+			const ns = maidMemoryService.namespaceForMaid(maidId);
 			return ns === void 0 ? Promise.resolve([]) : maidMemoryService.recent(ns, limit);
 		},
 		markSkip: (sessionId) => {
-			maidMemoryService.markSkipMemory(sessionId);
+			maidMemoryOf()?.markSkipMemory(sessionId);
 		}
 	};
-	const maidVoiceService = ctx.reflect?.get?.("maidVoice", false);
-	if (maidVoiceService === void 0) warn("maid-cron: maidVoice 未挂载——{{nightContext}}/{{overnightSentence}} 将渲染为空");
-	const voice = maidVoiceService === void 0 ? void 0 : {
-		buildNightContext: (maidId) => maidVoiceService.buildNightContext(maidId) ?? "",
-		getMorningSentence: (maidId) => maidVoiceService.getMorningSentence(maidId) ?? ""
+	const maidVoiceOf = lazyReflect("maidVoice", "maid-cron: maidVoice 未挂载——{{nightContext}}/{{overnightSentence}} 将渲染为空");
+	const voice = {
+		buildNightContext: (maidId) => maidVoiceOf()?.buildNightContext(maidId) ?? "",
+		getMorningSentence: (maidId) => maidVoiceOf()?.getMorningSentence(maidId) ?? ""
 	};
 	const baseCreate = (opts) => ctx.agents.create(opts);
 	const presetRegistry = config.mountPresets === true ? presetRegistryOf(ctx, config.presetRegistryService ?? "agentPresets") : void 0;
-	const agentsCreate = config.mountPresets === true ? createPresetMountingAgents(baseCreate, presetRegistry) : baseCreate;
+	const composerOf = lazyReflect("maidComposer", "maid-cron: maidComposer 未挂载");
+	const recordOf = (maidId) => ctx.maidIdentity.get(maidId);
+	const agentsCreate = config.mountPresets === true ? createMaidMountingAgents(baseCreate, presetRegistry, {
+		maidOwnPresetOf: (maidId) => recordOf(maidId)?.preset,
+		composer: { setup: (agentCtx, maidId) => {
+			const c = composerOf();
+			if (c === void 0) throw new Error("maid-cron: maidComposer 未挂载(执行时探测)——差异层缺位,拒绝生成");
+			return c.setup(agentCtx, maidId);
+		} }
+	}) : baseCreate;
 	const engine = createCronEngine(resolved, jobs, {
 		identity: {
-			presetOf: (maidId) => ctx.maidIdentity.get(maidId)?.preset,
+			basePresetOf: (maidId, jobBasePreset) => jobBasePreset ?? recordOf(maidId)?.basePreset ?? recordOf(maidId)?.preset,
+			maidOwnPresetOf: (maidId) => recordOf(maidId)?.preset,
 			addressOf: (maidId) => ctx.maidIdentity.deliveryTargets(maidId)?.[0]
 		},
 		memory,

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@deepmaid/maid-cron",
-  "version": "0.1.0-alpha.1",
-  "license": "MIT",
+  "version": "0.1.0-alpha.3",
   "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {
@@ -28,18 +31,18 @@
     }
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
     "croner": "10.0.1",
-    "@deepmaid/maid-delivery": "0.1.0-alpha.1"
+    "@deepmaid/maid-delivery": "0.1.0-alpha.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/cordis": "4.1.0",
     "tsdown": "0.22.14",
     "typescript": "6.0.3",
-    "@deepmaid/maid-memory": "0.1.0-alpha.1"
-  },
-  "publishConfig": {
-    "access": "public"
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepmaid/maid-memory": "0.1.0-alpha.3"
   },
   "scripts": {
     "build": "tsdown"