@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.4

package/docs/templates/init-managed-agents.md

@@ -80,9 +80,19 @@ loop-agent init update --repo-root . --apply-safe
 当用户要求初始化 loop-agent（“初始化 loop-agent”“loop agent 初始化”“loop agent初始化”“loop-agent 初始化”），或发现 `README.md` / `__LOOP_AGENT_GOVERNANCE_ROOT__/verification-matrix.md` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。
 
 1. 运行 `loop-agent init instructions --repo-root .`。
-2. 运行 `loop-agent init --repo-root . --profile full --merge`。
-3. 基于真实项目文件补全根 `README.md`、`__LOOP_AGENT_GOVERNANCE_ROOT__/verification-matrix.md`，必要时适配 `scripts/ci-tests.sh`。
-4. 运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect`、`loop-agent docs audit` 并完成 quick verification。
+2. 运行 `loop-agent init model-catalog --repo-root . --json`。loop-agent 不直接打开或解析认证文件原文，只让 Pi/OpenCode 自己的 runtime 加载其配置，并输出白名单模型元数据、Pi setup 状态、Pi 兼容性与 credential-ready 布尔值；token、headers、URL、原始命令输出和认证路径不会进入 catalog。
+3. 先处理 `piSetup`：如果没有模型定义，向用户索取无法推断的 provider/model id、API/base URL、上下文窗口、最大输出、输入/推理能力、成本约束和凭据方式，帮助按 Pi 原生 schema 合并 `~/.pi/agent/models.json`；不得让用户把凭据值写入对话、harness 或报告，优先 Pi 登录/auth storage 或环境变量引用。如果已有定义但凭据未就绪，只修复认证。随后重跑 catalog，未出现 credential-ready Pi model 前不得继续初始化。
+4. 对已有 `harness.json`，逐档保留仍存在于 Pi 的 LOW/MED/HIGH 原值；只为已移除或缺失的档位重新选择。结合目标项目实际技术栈、模型能力、成本与上下文窗口，从 `eligibleForHarness=true` 的候选中自主选择，并直接运行带完整三档参数的 init/update；代码会拒绝改动仍有效的档位。三档可以相同。只有凭据、成本、合规或可用性存在无法推断的实质歧义时才询问用户；OpenCode-only 候选不能证明 Pi executor 可用。
+5. 基于真实项目文件补全根 `README.md`、`__LOOP_AGENT_GOVERNANCE_ROOT__/verification-matrix.md`，必要时适配 `scripts/ci-tests.sh`。
+6. 运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect`、`loop-agent docs audit` 并完成 quick verification；doctor 未确认 Pi model matrix 时不得开始 DAG。
+
+```bash
+loop-agent init --repo-root . --profile full --merge \
+  --low-model <provider/model> --med-model <provider/model> --high-model <provider/model>
+# 已初始化项目只替换失效档位；仍有效档位在完整参数中保持当前引用
+loop-agent init update --repo-root . --apply-safe \
+  --low-model <current-or-selected> --med-model <current-or-selected> --high-model <current-or-selected>
+```
 
 信息不足时写明尚未识别到的事实；不要留下泛化占位符。
 

package/harness.json

@@ -82,9 +82,9 @@
   "executors": {
     "pi": {
       "description": "Pi 负责规划、评审、诊断；当 DAG toolProfile=write 时也可做有界写入。模型按复杂度三档配置，支持 provider/model 字符串或带 thinking 的对象；斜杠前为 Pi provider，后为 modelId，勿只写裸 modelId。",
-      "LOW": "wizard-local/minimax-m3",
-      "MED": "wizard-local/grok-4.6",
-      "HIGH": "wizard-local/gpt-5.6-sol"
+      "LOW": "deepseek/deepseek-v4-flash",
+      "MED": "deepseek/deepseek-v4-flash",
+      "HIGH": "deepseek/deepseek-v4-flash"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-beta.2",
+  "version": "0.39.0-beta.4",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -33,6 +33,9 @@
     "scripts/kb-graph-materialize.mjs",
     "scripts/kb-graph-promote.mjs",
     "scripts/kb-graph-incremental-prepare.mjs",
+    "scripts/next-info.mjs",
+    "scripts/next-publish-gate.mjs",
+    "scripts/release-source-binding.mjs",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -58,6 +61,7 @@
     "test": "node scripts/run-tests.mjs",
     "test:host": "vitest run test/init-upgrade.test.ts --maxWorkers=1 -t \"records and reuses|controller-authorized semantic merge|authority-sensitive\"",
     "test:fast": "vitest run --config vitest.fast.config.ts",
+    "test:io-heavy": "vitest run --config vitest.io-heavy.config.ts",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "docs:dev": "npm --prefix website start",
     "docs:build": "npm --prefix website run build",

package/scripts/next-info.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+/**
+ * next-info: read-only report of the current npm `next` binding.
+ *
+ * Resolves the moving git ref `npm-next` (local, then origin) and the
+ * published tarball build stamp. Does not write the repo, move dist-tags,
+ * or call GitHub APIs.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import {
+	commandLaunch,
+	defaultRun,
+	isAncestor,
+	normalizeCommandArgs,
+	npmViewDistTags,
+} from "./next-publish-gate.mjs";
+import {
+	downloadNpmTarball,
+	readTarballBuildStamp,
+} from "./release-source-binding.mjs";
+
+export const UNPUBLISHED_COMMIT_LIMIT_DEFAULT = 50;
+const GIT_REF_CANDIDATES = ["refs/heads/npm-next", "origin/npm-next"];
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {string} [cwd]
+ */
+function runWithCwd(cmd, args, cwd) {
+	const launch = commandLaunch(cmd, normalizeCommandArgs(cmd, args));
+	return execFileSync(launch.cmd, launch.args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+		cwd,
+	});
+}
+
+function scriptEntryHref(argv1) {
+	try {
+		return argv1 ? new URL(`file://${argv1}`).href : "";
+	} catch {
+		return "";
+	}
+}
+
+function trimSha(value) {
+	if (typeof value !== "string") return null;
+	const sha = value.trim();
+	return sha ? sha : null;
+}
+
+function equalSha(left, right) {
+	if (!left || !right) return false;
+	return left.toLowerCase() === right.toLowerCase();
+}
+
+function tryRevParse(run, ref) {
+	try {
+		return trimSha(run("git", ["rev-parse", ref]));
+	} catch {
+		return null;
+	}
+}
+
+function resolveGitRefSha(run) {
+	for (const ref of GIT_REF_CANDIDATES) {
+		const sha = tryRevParse(run, ref);
+		if (sha) return { ref, sha };
+	}
+	return null;
+}
+
+function readStampBuiltAt(tarballPath, run) {
+	try {
+		const listing = run("tar", ["-tzf", tarballPath]);
+		const stampEntry = String(listing)
+			.split("\n")
+			.map((line) => line.trim())
+			.find((line) => /\/dist\/build-stamp\.json$/.test(line));
+		if (!stampEntry) return null;
+		const stampJson = run("tar", ["-xzf", tarballPath, "-O", stampEntry]);
+		const parsed = JSON.parse(String(stampJson));
+		return typeof parsed.builtAt === "string" ? parsed.builtAt : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Download the published next tarball and read gitSha + builtAt. */
+export function defaultNextStampProbe(version, run = defaultRun) {
+	const dir = mkdtempSync(join(tmpdir(), "loop-agent-next-info-"));
+	try {
+		const tarball = downloadNpmTarball(version, dir, run);
+		const stamp = readTarballBuildStamp(tarball, run);
+		return {
+			gitSha: stamp.gitSha,
+			version: stamp.version ?? null,
+			builtAt: readStampBuiltAt(tarball, run),
+		};
+	} catch {
+		return null;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+function emptyResult(overrides) {
+	return {
+		ok: false,
+		exitCode: 1,
+		npmNextVersion: null,
+		gitSha: null,
+		gitRef: null,
+		gitRefSha: null,
+		stampSha: null,
+		builtAt: null,
+		source: null,
+		aheadBy: null,
+		aheadByReason: null,
+		unpublishedCommits: [],
+		unpublishedTruncated: false,
+		unpublishedLimit: UNPUBLISHED_COMMIT_LIMIT_DEFAULT,
+		drift: false,
+		error: null,
+		...overrides,
+	};
+}
+
+function collectAheadState(gitSha, run) {
+	if (!gitSha) {
+		return {
+			aheadBy: null,
+			aheadByReason: "no gitSha to compare against HEAD",
+			unpublishedCommits: [],
+			unpublishedTruncated: false,
+		};
+	}
+	const headSha = tryRevParse(run, "HEAD");
+	if (!headSha) {
+		return {
+			aheadBy: null,
+			aheadByReason: "HEAD is unavailable",
+			unpublishedCommits: [],
+			unpublishedTruncated: false,
+		};
+	}
+	let unpublishedCommits = [];
+	let unpublishedTruncated = false;
+	try {
+		const log = run("git", ["log", "--oneline", `${gitSha}..HEAD`]);
+		const lines = String(log ?? "")
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean);
+		unpublishedTruncated = lines.length > UNPUBLISHED_COMMIT_LIMIT_DEFAULT;
+		unpublishedCommits = lines.slice(0, UNPUBLISHED_COMMIT_LIMIT_DEFAULT);
+	} catch {
+		unpublishedCommits = [];
+	}
+	if (!isAncestor(gitSha, headSha, run)) {
+		return {
+			aheadBy: null,
+			aheadByReason: "gitSha is not an ancestor of HEAD",
+			unpublishedCommits,
+			unpublishedTruncated,
+		};
+	}
+	try {
+		const count = Number(
+			String(run("git", ["rev-list", "--count", `${gitSha}..HEAD`])).trim(),
+		);
+		if (!Number.isFinite(count)) {
+			return {
+				aheadBy: null,
+				aheadByReason: "rev-list count is not a number",
+				unpublishedCommits,
+				unpublishedTruncated,
+			};
+		}
+		return {
+			aheadBy: count,
+			aheadByReason: null,
+			unpublishedCommits,
+			unpublishedTruncated,
+		};
+	} catch {
+		return {
+			aheadBy: null,
+			aheadByReason: "rev-list failed",
+			unpublishedCommits,
+			unpublishedTruncated,
+		};
+	}
+}
+
+/**
+ * Pure-ish collector. Tests inject `run` / `viewDistTags` / `stampProbe`
+ * so this never hits the real npm registry.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   run?: (cmd: string, args: string[]) => string,
+ *   viewDistTags?: () => Record<string, string>,
+ *   stampProbe?: (version: string) =>
+ *     | { gitSha?: string, builtAt?: string | null }
+ *     | null,
+ * }} [deps]
+ */
+export function collectNextInfo(deps = {}) {
+	const run =
+		deps.run ??
+		((cmd, args) =>
+			deps.cwd ? runWithCwd(cmd, args, deps.cwd) : defaultRun(cmd, args));
+	const viewDistTags = deps.viewDistTags ?? (() => npmViewDistTags(run));
+	const stampProbe =
+		deps.stampProbe ?? ((version) => defaultNextStampProbe(version, run));
+
+	let distTags = {};
+	try {
+		distTags = viewDistTags() ?? {};
+	} catch {
+		distTags = {};
+	}
+	const npmNextVersion = distTags.next ? String(distTags.next) : null;
+	const gitRef = resolveGitRefSha(run);
+	const gitRefSha = gitRef?.sha ?? null;
+	let stamp = null;
+	if (npmNextVersion) {
+		try {
+			stamp = stampProbe(npmNextVersion);
+		} catch {
+			stamp = null;
+		}
+	}
+	const stampSha = trimSha(stamp?.gitSha);
+	const builtAt = typeof stamp?.builtAt === "string" ? stamp.builtAt : null;
+
+	if (!gitRefSha && !stampSha) {
+		const error = npmNextVersion
+			? `no npm-next git ref and tarball stamp unreadable for next=${npmNextVersion}`
+			: "no npm-next git ref and no dist-tags.next";
+		return emptyResult({ error, npmNextVersion });
+	}
+
+	let source;
+	let gitSha;
+	let drift = false;
+	let error = null;
+	let ok = true;
+	let exitCode = 0;
+
+	if (gitRefSha && stampSha) {
+		source = "both";
+		if (!equalSha(gitRefSha, stampSha)) {
+			drift = true;
+			ok = false;
+			exitCode = 1;
+			error =
+				`npm-next git ref (${gitRefSha}) does not match tarball stamp gitSha (${stampSha})`;
+		}
+		gitSha = gitRefSha;
+	} else if (gitRefSha) {
+		source = "git-ref";
+		gitSha = gitRefSha;
+	} else {
+		source = "tarball-stamp";
+		gitSha = stampSha;
+	}
+
+	const ahead = collectAheadState(gitSha, run);
+	return {
+		ok,
+		exitCode,
+		npmNextVersion,
+		gitSha,
+		gitRef: gitRef?.ref ?? null,
+		gitRefSha,
+		stampSha,
+		builtAt,
+		source,
+		aheadBy: ahead.aheadBy,
+		aheadByReason: ahead.aheadByReason,
+		unpublishedCommits: ahead.unpublishedCommits,
+		unpublishedTruncated: ahead.unpublishedTruncated,
+		unpublishedLimit: UNPUBLISHED_COMMIT_LIMIT_DEFAULT,
+		drift,
+		error,
+	};
+}
+
+export function formatNextInfo(result, { json = false } = {}) {
+	if (json) {
+		return `${JSON.stringify(result, null, 2)}\n`;
+	}
+	const lines = [];
+	if (result.npmNextVersion) {
+		lines.push(`npm next: ${result.npmNextVersion}`);
+	} else {
+		lines.push("npm next: (no dist-tags.next)");
+	}
+	if (result.gitSha) {
+		lines.push(`gitSha: ${result.gitSha} (source: ${result.source})`);
+	} else {
+		lines.push("gitSha: (unavailable)");
+	}
+	if (result.gitRefSha && result.stampSha && result.drift) {
+		lines.push(`git-ref SHA: ${result.gitRefSha}`);
+		lines.push(`tarball stamp SHA: ${result.stampSha}`);
+	}
+	if (result.builtAt) {
+		lines.push(`builtAt: ${result.builtAt}`);
+	}
+	if (result.aheadBy === null) {
+		lines.push(
+			`aheadBy: null${result.aheadByReason ? ` (${result.aheadByReason})` : ""}`,
+		);
+	} else {
+		lines.push(`aheadBy: ${result.aheadBy}`);
+	}
+	const commits = result.unpublishedCommits ?? [];
+	if (commits.length === 0) {
+		lines.push("unpublishedCommits: (none)");
+	} else {
+		lines.push("unpublishedCommits:");
+		for (const commit of commits) lines.push(`  ${commit}`);
+		if (result.unpublishedTruncated) {
+			lines.push(
+				`  … truncated to ${result.unpublishedLimit} commits`,
+			);
+		}
+	}
+	if (result.error) {
+		lines.push(`error: ${result.error}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function main(argv = process.argv.slice(2)) {
+	const json = argv.includes("--json");
+	const result = collectNextInfo();
+	process.stdout.write(formatNextInfo(result, { json }));
+	process.exit(result.ok ? 0 : result.exitCode || 1);
+}
+
+const invokedAsScript =
+	Boolean(process.argv[1]) &&
+	import.meta.url === scriptEntryHref(process.argv[1]);
+
+if (invokedAsScript) {
+	main();
+}

package/scripts/next-publish-gate.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * next-publish-gate: throttle main -> npm `next` publishing.
+ *
+ * Every main push used to publish a new next build. With this gate a
+ * push-triggered run only publishes when HEAD is at least COMMIT_THRESHOLD
+ * commits ahead of the commit that produced the current dist-tags.next
+ * build (read from the published tarball's dist/build-stamp.json).
+ *
+ * Bypasses (publish regardless of the count):
+ *   - workflow_dispatch runs (manual trigger, e.g. right before cutting a
+ *     release line); the workflow passes --force for those.
+ *   - recovery: HEAD already IS the source of the current next build, so
+ *     re-publishing would be the same version anyway.
+ *   - unknown last-published SHA (no npm history / unreadable stamp /
+ *     SHA not an ancestor of HEAD): fail open — a missed next build is
+ *     cheap, permanently stuck publishing is not.
+ *
+ * Exit codes: 0 = publish, 2 = skip (gate), 1 = hard error. The workflow
+ * maps skip to a successful early exit so non-publishing runs are green.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { readTarballBuildStamp } from "./release-source-binding.mjs";
+
+export const COMMIT_THRESHOLD_DEFAULT = 5;
+const SKIP_EXIT_CODE = 2;
+
+/** Run a command and return trimmed stdout; injected for tests. */
+function normalizeWindowsTarArg(value) {
+	const match = /^([A-Za-z]):[\\/](.*)$/.exec(String(value));
+	if (!match) return value;
+	return `/${match[1].toLowerCase()}/${match[2].replaceAll("\\", "/")}`;
+}
+
+export function normalizeCommandArgs(cmd, args, platform = process.platform) {
+	if (platform !== "win32" || cmd !== "tar") return args;
+	return args.map(normalizeWindowsTarArg);
+}
+
+export function commandLaunch(cmd, args, platform = process.platform) {
+	if (platform === "win32" && cmd === "npm") {
+		return {
+			cmd: process.env.ComSpec || "cmd.exe",
+			args: ["/d", "/s", "/c", "npm", ...args],
+		};
+	}
+	return { cmd, args };
+}
+
+export function defaultRun(cmd, args) {
+	const launch = commandLaunch(cmd, normalizeCommandArgs(cmd, args));
+	return execFileSync(launch.cmd, launch.args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+}
+
+export function npmViewDistTags(run = defaultRun) {
+	const out = run("npm", [
+		"view",
+		"@tea-agent/loop-agent",
+		"dist-tags",
+		"--json",
+	]);
+	const trimmed = String(out ?? "").trim();
+	if (!trimmed) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		return {};
+	}
+	return parsed && typeof parsed === "object" ? parsed : {};
+}
+
+/** Download the exact published next version and read its build stamp. */
+export function defaultStampProbe(version) {
+	const dir = mkdtempSync(join(tmpdir(), "loop-agent-next-gate-"));
+	try {
+		defaultRun("npm", [
+			"pack",
+			`@tea-agent/loop-agent@${version}`,
+			"--pack-destination",
+			dir,
+		]);
+		const file = readdirSync(dir).find((entry) => entry.endsWith(".tgz"));
+		if (!file) return null;
+		try {
+			return readTarballBuildStamp(join(dir, file), defaultRun);
+		} catch {
+			return null;
+		}
+	} catch {
+		return null;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+export function isAncestor(sha, head, run = defaultRun) {
+	try {
+		run("git", ["merge-base", "--is-ancestor", sha, head]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Pure decision. Inputs:
+ *   - threshold: minimum commits ahead of lastPublishedSha to publish
+ *   - aheadBy: commits between lastPublishedSha and headSha (null = unknown)
+ *   - lastPublishedSha / headSha: for the recovery equality check
+ * Returns { publish, reason, aheadBy }.
+ */
+export function shouldPublishNext({
+	threshold = COMMIT_THRESHOLD_DEFAULT,
+	lastPublishedSha,
+	headSha,
+	aheadBy,
+	force = false,
+}) {
+	if (force) {
+		return { publish: true, reason: "force-bypass", aheadBy };
+	}
+	if (!headSha) {
+		return { publish: true, reason: "head-unknown-fail-open", aheadBy };
+	}
+	if (!lastPublishedSha) {
+		return {
+			publish: true,
+			reason: "last-published-sha-unknown-fail-open",
+			aheadBy,
+		};
+	}
+	const last = String(lastPublishedSha).toLowerCase();
+	const head = String(headSha).toLowerCase();
+	if (last === head) {
+		return { publish: true, reason: "same-commit-recovery", aheadBy: 0 };
+	}
+	if (aheadBy === null || aheadBy === undefined || !Number.isFinite(aheadBy)) {
+		return { publish: true, reason: "ahead-unknown-fail-open", aheadBy: null };
+	}
+	const normalizedThreshold = Number(threshold);
+	if (!Number.isFinite(normalizedThreshold) || normalizedThreshold <= 0) {
+		return { publish: true, reason: "threshold-invalid-fail-open", aheadBy };
+	}
+	if (aheadBy >= normalizedThreshold) {
+		return { publish: true, reason: "ahead-threshold-met", aheadBy };
+	}
+	return { publish: false, reason: "below-threshold-skip", aheadBy };
+}
+
+function parseArgs(argv) {
+	return Object.fromEntries(
+		argv
+			.filter((arg) => arg.startsWith("--"))
+			.map((arg) => {
+				const [key, ...value] = arg.replace(/^--/, "").split("=");
+				return [key, value.join("=") || "true"];
+			}),
+	);
+}
+
+function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const threshold = Number(args.threshold || COMMIT_THRESHOLD_DEFAULT);
+	const distTags = npmViewDistTags();
+	const currentNext = distTags.next ? String(distTags.next) : null;
+	let lastPublishedSha = null;
+	let currentNextNote = "no dist-tags.next";
+	if (currentNext) {
+		const stamp = defaultStampProbe(currentNext);
+		if (stamp && stamp.gitSha) {
+			lastPublishedSha = stamp.gitSha;
+			currentNextNote = `next=${currentNext} from ${stamp.gitSha.slice(0, 10)}`;
+		} else {
+			currentNextNote = `next=${currentNext} (stamp unreadable)`;
+		}
+	}
+	let headSha = null;
+	let aheadBy = null;
+	try {
+		headSha = defaultRun("git", ["rev-parse", "HEAD"]).trim();
+	} catch {
+		headSha = null;
+	}
+	if (headSha && lastPublishedSha) {
+		if (!isAncestor(lastPublishedSha, headSha)) {
+			aheadBy = null;
+		} else {
+			aheadBy = Number(
+				defaultRun("git", [
+					"rev-list",
+					"--count",
+					`${lastPublishedSha}..${headSha}`,
+				]).trim(),
+			);
+		}
+	}
+	const decision = shouldPublishNext({
+		threshold,
+		lastPublishedSha,
+		headSha,
+		aheadBy,
+		force: args.force === "true",
+	});
+	process.stdout.write(
+		`next-publish-gate: ${currentNextNote}\n` +
+			`next-publish-gate: head=${headSha ? headSha.slice(0, 10) : "unknown"} ` +
+			`aheadBy=${aheadBy === null ? "unknown" : aheadBy} ` +
+			`threshold=${threshold}\n` +
+			`next-publish-gate: ${decision.publish ? "PUBLISH" : "SKIP"} ` +
+			`(${decision.reason})\n`,
+	);
+	process.exit(decision.publish ? 0 : SKIP_EXIT_CODE);
+}
+
+// CLI 入口安全判断（argv[1] 非合法 file: URL 时 new URL 会抛异常）
+function scriptEntryHref(argv1) {
+	try {
+		return argv1 ? new URL(`file://${argv1}`).href : "";
+	} catch {
+		return "";
+	}
+}
+
+const invokedAsScript =
+	Boolean(process.argv[1]) &&
+	import.meta.url === scriptEntryHref(process.argv[1]);
+
+if (invokedAsScript) {
+	main();
+}