genlab 0.0.0-stage → 0.1.1

package/dist/cli.mjs

@@ -0,0 +1,1689 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError } from "commander";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { access, copyFile, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { openAsBlob } from "node:fs";
+import { setTimeout } from "node:timers/promises";
+import { homedir } from "node:os";
+import writeFileAtomic from "write-file-atomic";
+import { dereference } from "@apidevtools/json-schema-ref-parser";
+import Ajv2020 from "ajv/dist/2020.js";
+import localizeZh from "ajv-i18n/localize/zh/index.js";
+import { fileTypeFromBuffer } from "file-type";
+import { imageSize } from "image-size";
+import { parseBuffer } from "music-metadata";
+import lockfile from "proper-lockfile";
+import { execFile } from "node:child_process";
+import { parseEnv, promisify } from "node:util";
+import * as p from "@clack/prompts";
+// package.json
+var version = "0.1.1";
+// src/errors.ts
+/** 面向使用者的预期错误：只输出 message，不带堆栈。 */
+var CliError = class extends Error {
+	name = "CliError";
+};
+// src/config.ts
+/** 配置文件：$XDG_CONFIG_HOME/genlab/.env，默认 ~/.config/genlab/.env。 */
+function configFile() {
+	const base = process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
+	return path.join(base, "genlab", ".env");
+}
+let envLoaded = false;
+/** 读取配置文件；已存在的环境变量优先，文件不存在时只用环境变量。 */
+function loadEnv() {
+	if (envLoaded) return;
+	envLoaded = true;
+	try {
+		process.loadEnvFile(configFile());
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+}
+function requireEnv(name) {
+	loadEnv();
+	const value = process.env[name]?.trim();
+	if (!value) throw new CliError(`缺少配置 ${name}：在 ${configFile()} 中设置`);
+	return value;
+}
+/** 库的根目录：GENLAB_LIBRARY，支持 ~ 开头，必须是绝对路径。 */
+function libraryRoot() {
+	const raw = requireEnv("GENLAB_LIBRARY");
+	const expanded = raw === "~" || raw.startsWith("~/") ? path.join(homedir(), raw.slice(1)) : raw;
+	if (!path.isAbsolute(expanded)) throw new CliError(`GENLAB_LIBRARY 必须是绝对路径：${raw}`);
+	return path.normalize(expanded);
+}
+// src/kie/client.ts
+const API_BASE_URL = "https://api.kie.ai";
+const UPLOAD_BASE_URL = "https://kieai.redpandaai.co";
+/** 接口请求超时；上传与下载按文件大小放宽。 */
+const REQUEST_TIMEOUT_MS = 6e4;
+const TRANSFER_TIMEOUT_MS = 6e5;
+/** 模型目录（models、schema、price、success-rate）共用每秒 1 次的额度。 */
+const DISCOVERY_INTERVAL_MS = 1100;
+async function createKieTask(task) {
+	const body = await kieFetch(`${API_BASE_URL}/api/v1/jobs/createTask`, {
+		method: "POST",
+		body: JSON.stringify(task)
+	});
+	if (!body.data?.taskId) throw new CliError("kie.ai 未返回 taskId");
+	return body.data.taskId;
+}
+async function listKieModels() {
+	return (await discoveryFetch(`${API_BASE_URL}/api/v1/models`)).data?.models ?? [];
+}
+/** 模型的 OpenAPI 文档；kie 尚未同步文档时为 null。模型标识里的斜杠不编码。 */
+async function getKieModelSchema(model) {
+	return (await discoveryFetch(`${API_BASE_URL}/api/v1/models/${model}/schema`)).data?.openapi ?? null;
+}
+/** 账户余额；apiKey 缺省时用配置里的 Key。 */
+async function getKieCredits(apiKey) {
+	return (await kieFetch(`${API_BASE_URL}/api/v1/chat/credit`, void 0, REQUEST_TIMEOUT_MS, apiKey)).data ?? 0;
+}
+/** 任务的原始记录（完整保存进素材记录，解析见 parseKieRecord）。 */
+async function getKieRecord(taskId) {
+	const body = await kieFetch(`${API_BASE_URL}/api/v1/jobs/recordInfo?taskId=${encodeURIComponent(taskId)}`);
+	if (!body.data) throw new CliError("kie.ai 未返回任务记录");
+	return body.data;
+}
+/**
+* 把本机文件上传给 kie，换取模型可访问的临时地址（24 小时后删除，不保存）。
+* 不指定文件名：kie 随机命名，避免同名覆盖。
+*/
+async function uploadKieFile(filePath) {
+	const form = new FormData();
+	form.append("file", await openAsBlob(filePath), path.basename(filePath));
+	form.append("uploadPath", "genlab");
+	const body = await kieFetch(`${UPLOAD_BASE_URL}/api/file-stream-upload`, {
+		method: "POST",
+		body: form
+	}, TRANSFER_TIMEOUT_MS);
+	if (!body.data?.downloadUrl) throw new CliError("kie.ai 上传未返回地址");
+	return body.data.downloadUrl;
+}
+/** 下载产物原文件。 */
+async function downloadFile(url) {
+	const response = await fetch(url, { signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS) });
+	if (!response.ok) throw new CliError(`下载产物失败：HTTP ${response.status}`);
+	return {
+		bytes: new Uint8Array(await response.arrayBuffer()),
+		contentType: response.headers.get("content-type")
+	};
+}
+let lastDiscoveryAt = 0;
+/** 目录类接口：同一进程内保持请求间隔，被限流时等一个间隔再试一次。 */
+async function discoveryFetch(url) {
+	for (let attempt = 0;; attempt++) {
+		const wait = lastDiscoveryAt + DISCOVERY_INTERVAL_MS - Date.now();
+		if (wait > 0) await setTimeout(wait);
+		lastDiscoveryAt = Date.now();
+		try {
+			return await kieFetch(url);
+		} catch (error) {
+			if (attempt > 0 || !(error instanceof KieRateLimitError)) throw error;
+		}
+	}
+}
+var KieRateLimitError = class extends CliError {};
+async function kieFetch(url, init, timeoutMs = REQUEST_TIMEOUT_MS, apiKey = requireEnv("KIE_API_KEY")) {
+	const headers = new Headers(init?.headers);
+	headers.set("Authorization", `Bearer ${apiKey}`);
+	if (typeof init?.body === "string") headers.set("Content-Type", "application/json");
+	const response = await fetch(url, {
+		...init,
+		headers,
+		signal: AbortSignal.timeout(timeoutMs)
+	});
+	let body;
+	try {
+		body = await response.json();
+	} catch {
+		throw new CliError(`kie.ai 请求失败：HTTP ${response.status}`);
+	}
+	if (!response.ok || body.code !== 200) throw new (body.code === 429 ? KieRateLimitError : CliError)(`kie.ai 请求失败（${body.code ?? response.status}）：${body.msg || response.statusText}`);
+	return body;
+}
+// src/catalog/cache.ts
+/** 模型目录与 schema 的本地缓存：$XDG_CACHE_HOME/genlab（默认 ~/.cache/genlab），一天有效。 */
+const TTL_MS = 864e5;
+function cacheDir() {
+	const base = process.env.XDG_CACHE_HOME || path.join(homedir(), ".cache");
+	return path.join(base, "genlab");
+}
+/** 缓存命中且未过期时直接返回，否则调用 load 并写入缓存；refresh 强制重新获取。 */
+async function cached(name, load, refresh = false) {
+	const file = path.join(cacheDir(), name);
+	if (!refresh) try {
+		const entry = JSON.parse(await readFile(file, "utf8"));
+		if (Date.now() - entry.fetchedAt < TTL_MS) return entry.value;
+	} catch (error) {
+		if (!(error instanceof SyntaxError) && error.code !== "ENOENT") throw error;
+	}
+	const value = await load();
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFileAtomic(file, JSON.stringify({
+		fetchedAt: Date.now(),
+		value
+	}));
+	return value;
+}
+// src/catalog/catalog.ts
+/** kie 模型目录：模型列表与产物类型（见 ADR-0005）。 */
+/** 目录的任务类型 → 产物的素材类型；对话模型不产出媒体，不在其中。 */
+const TASK_TYPE_KINDS = {
+	"Text to Image": "image",
+	"Image to Image": "image",
+	"Image Editing": "image",
+	"Text to Video": "video",
+	"Image to Video": "video",
+	"Video to Video": "video",
+	"Video Editing": "video",
+	"Lip Sync": "video",
+	"Speech to Video": "video",
+	"Text to Speech": "audio",
+	"Text to Music": "audio",
+	"Audio to Audio": "audio"
+};
+const CHAT_TASK_TYPE = "Chat";
+/** 产物的素材类型；对话模型返回 null，类型未知或互相矛盾时报错。 */
+function kindForModel(model) {
+	if (model.taskType.includes(CHAT_TASK_TYPE)) return null;
+	const kinds = new Set(model.taskType.map((taskType) => {
+		const kind = TASK_TYPE_KINDS[taskType];
+		if (!kind) throw new CliError(`无法识别模型 ${model.model} 的任务类型：${taskType}`);
+		return kind;
+	}));
+	if (kinds.size !== 1) throw new CliError(`模型 ${model.model} 的产物类型不明确：${model.taskType.join(", ")}`);
+	return [...kinds][0];
+}
+async function listModels(refresh = false) {
+	return cached("models.json", listKieModels, refresh);
+}
+/** 按标识找模型；缓存里没有时刷新一次目录再找。 */
+async function findModel(id) {
+	const model = (await listModels()).find((item) => item.model === id) ?? (await listModels(true)).find((item) => item.model === id);
+	if (!model) throw new CliError(`未知模型：${id}（用 genlab models 查看）`);
+	const kind = kindForModel(model);
+	if (!kind) throw new CliError(`模型 ${id} 是对话模型，不支持`);
+	return {
+		...model,
+		kind
+	};
+}
+// src/catalog/input.ts
+/**
+* 命令行参数 → kie 的 input。`-p key=value` 的值是字符串，`-p key:=<JSON>` 的值按 JSON
+* 解析，同一个键重复出现时合并成数组。字符串值以 `@` 开头表示文件：`@<路径>` 是本机
+* 文件，`@source` 是 AI 编辑的源版本，`@@` 开头表示字面量 `@`。
+*/
+const SOURCE_TOKEN = "@source";
+function parseInputArgs(args) {
+	const input = {};
+	for (const arg of args) {
+		const match = /^([^=:]+)(:?=)([\s\S]*)$/.exec(arg);
+		if (!match) throw new CliError(`参数格式应为 key=value 或 key:=JSON：${arg}`);
+		const [, key, operator, raw] = match;
+		let value = raw;
+		if (operator === ":=") try {
+			value = JSON.parse(raw);
+		} catch {
+			throw new CliError(`参数 ${key} 的 JSON 不合法：${raw}`);
+		}
+		if (key in input) {
+			const previous = input[key];
+			input[key] = Array.isArray(previous) ? [...previous, value] : [previous, value];
+		} else input[key] = value;
+	}
+	return input;
+}
+/** 对 value 里的每个字符串调用 fn，返回替换后的新值（对象与数组递归）。 */
+function mapStrings(value, fn) {
+	if (typeof value === "string") return fn(value);
+	if (Array.isArray(value)) return value.map((item) => mapStrings(item, fn));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, mapStrings(item, fn)]));
+	return value;
+}
+/** 是文件引用（`@source` 或 `@<路径>`）而不是字面量。 */
+function isFileToken(text) {
+	return text.startsWith("@") && !text.startsWith("@@") && text.length > 1;
+}
+/** input 里引用的全部本机文件路径（不含 `@source`），按出现顺序去重。 */
+function filePaths(input) {
+	const paths = [];
+	mapStrings(input, (text) => {
+		if (isFileToken(text) && text !== "@source") paths.push(text.slice(1));
+		return text;
+	});
+	return [...new Set(paths)];
+}
+function usesSource(input) {
+	let found = false;
+	mapStrings(input, (text) => {
+		found ||= text === SOURCE_TOKEN;
+		return text;
+	});
+	return found;
+}
+/** 把文件引用换成 resolve 的结果，`@@` 还原为字面量 `@`。 */
+function resolveTokens(input, resolve) {
+	return mapStrings(input, (text) => {
+		if (text.startsWith("@@")) return text.slice(1);
+		return isFileToken(text) ? resolve(text) : text;
+	});
+}
+// src/catalog/schema.ts
+/** 模型的输入参数定义：取自 kie 的 OpenAPI 文档，用于校验与展示。 */
+const TASK_PATH = "/api/v1/jobs/createTask";
+/** 模型 createTask 请求体里 input 的 JSON Schema（$ref 已展开）。 */
+async function getInputSchema(model, refresh = false) {
+	const doc = await cached(`schemas/${encodeURIComponent(model)}.json`, async () => {
+		const openapi = await getKieModelSchema(model);
+		if (!openapi) throw new CliError(`kie 尚未提供模型 ${model} 的参数定义`);
+		return openapi;
+	}, refresh);
+	const operation = (await dereference(structuredClone(doc), { resolve: { external: false } })).paths?.[TASK_PATH]?.post;
+	if (!operation) throw new CliError(`模型 ${model} 不走任务接口，不支持`);
+	const input = operation.requestBody?.content?.["application/json"]?.schema?.properties?.input;
+	if (!input || typeof input !== "object") throw new CliError(`模型 ${model} 的参数定义缺少 input`);
+	return input;
+}
+const ajv = new Ajv2020({
+	strict: false,
+	allErrors: true,
+	coerceTypes: "array",
+	validateFormats: false
+});
+/** 按 schema 校验并就地转换 input 的值类型；不通过时报错。 */
+function validateInput(schema, input) {
+	const validate = ajv.compile(schema);
+	if (validate(input)) return;
+	localizeZh(validate.errors);
+	const messages = (validate.errors ?? []).map((error) => `${error.instancePath || "input"} ${error.message ?? ""}`.trim());
+	throw new CliError(`参数不符合模型定义：${[...new Set(messages)].join("；")}`);
+}
+const PARAM_KEYS = [
+	"type",
+	"enum",
+	"default",
+	"minimum",
+	"maximum",
+	"maxLength",
+	"items",
+	"description"
+];
+function describeObject(schema) {
+	const properties = schema.properties ?? {};
+	const required = new Set(schema.required ?? []);
+	return Object.entries(properties).map(([name, property]) => {
+		const info = {
+			name,
+			required: required.has(name)
+		};
+		for (const key of PARAM_KEYS) if (property[key] !== void 0) Object.assign(info, { [key]: property[key] });
+		return info;
+	});
+}
+/** 把 input 的 schema 整理成参数表（`genlab models <id>` 的输出）。 */
+function describeInput(schema) {
+	const branches = schema.oneOf ?? schema.anyOf;
+	const description = { params: describeObject(schema) };
+	if (branches) description.variants = branches.map((branch) => ({ params: describeObject(branch) }));
+	return description;
+}
+// src/library/media.ts
+/** 媒体文件识别：类型、扩展名与尺寸/时长。 */
+const MEDIA_KINDS = [
+	"image",
+	"video",
+	"audio"
+];
+/** 按内容识别不出时，按下载响应的 Content-Type 兜住常见格式。 */
+const MIME_EXTENSIONS = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/webp": "webp",
+	"video/mp4": "mp4",
+	"video/quicktime": "mov",
+	"video/webm": "webm",
+	"audio/mpeg": "mp3",
+	"audio/wav": "wav",
+	"audio/x-wav": "wav",
+	"audio/mp4": "m4a",
+	"audio/aac": "aac",
+	"audio/ogg": "ogg",
+	"audio/flac": "flac"
+};
+function kindForMime(mimeType) {
+	const type = mimeType.split("/")[0];
+	return type === "image" || type === "video" || type === "audio" ? type : null;
+}
+async function inspectMedia(bytes, contentType = null) {
+	const detected = await fileTypeFromBuffer(bytes);
+	const headerMime = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+	const mimeType = detected?.mime ?? headerMime;
+	const extension = detected?.ext ?? MIME_EXTENSIONS[headerMime];
+	const kind = kindForMime(mimeType);
+	if (!extension || !kind) throw new CliError(`无法识别的媒体类型：${mimeType || "未知"}`);
+	return {
+		mimeType,
+		extension,
+		kind,
+		...await measure(bytes, kind, mimeType)
+	};
+}
+/** 尺寸与时长：解析失败不阻塞入库，按未知记录。 */
+async function measure(bytes, kind, mimeType) {
+	const unknown = {
+		width: null,
+		height: null,
+		duration: null
+	};
+	try {
+		if (kind === "image") {
+			const size = imageSize(bytes);
+			return {
+				...unknown,
+				width: size.width,
+				height: size.height
+			};
+		}
+		const metadata = await parseBuffer(bytes, { mimeType }, { duration: true });
+		const video = metadata.format.trackInfo.find((track) => track.video)?.video;
+		return {
+			width: video?.pixelWidth ?? null,
+			height: video?.pixelHeight ?? null,
+			duration: metadata.format.duration ?? null
+		};
+	} catch {
+		return unknown;
+	}
+}
+// src/library/paths.ts
+/** 库内命名与路径约定（纯函数）。 */
+/** 素材文件夹里的记录文件：含它的文件夹才是素材。 */
+const ASSET_FILE = "asset.json";
+/** 素材文件夹里存放参考输入副本的子目录，按生成编号分开。 */
+const REFERENCES_DIR = "references";
+/** 库根目录下的项目映射表。 */
+const PROJECT_MAP_FILE = "projects.json";
+const MAX_NAME_BYTES = 255;
+/** 项目、文件夹、素材名：非空，不以 . 开头，不含路径分隔符与控制字符。 */
+function validateName(name, what) {
+	const trimmed = name.trim();
+	if (!trimmed || trimmed !== name || trimmed.startsWith(".") || /[/\\:\p{Cc}]/u.test(trimmed) || Buffer.byteLength(trimmed) > MAX_NAME_BYTES) throw new CliError(`${what}不合法：${JSON.stringify(name)}`);
+	return trimmed;
+}
+/** 「文件夹/…/素材名」→ 各级名字。 */
+function parseAssetPath(input) {
+	const segments = input.split("/");
+	if (segments.some((segment) => segment === "")) throw new CliError(`素材路径不合法：${JSON.stringify(input)}`);
+	return segments.map((segment) => validateName(segment, "素材路径"));
+}
+/** `3` 或 `v3` → 3。 */
+function parseVersionArg(input) {
+	const match = /^v?(\d+)$/i.exec(input.trim());
+	const value = match ? Number(match[1]) : NaN;
+	if (!Number.isSafeInteger(value) || value < 1) throw new CliError(`版本号不合法：${input}`);
+	return value;
+}
+/** 版本产物文件名：v<版本号>.<扩展名>。 */
+function versionFileName(version, extension) {
+	return `v${version}.${extension}`;
+}
+/** 版本产物文件名 → 版本号；不是版本产物返回 null。 */
+function versionFromFileName(fileName) {
+	const match = /^v(\d+)\.[^.]+$/.exec(fileName);
+	return match ? Number(match[1]) : null;
+}
+// src/library/record.ts
+/**
+* 素材记录文件：素材、生成、版本的全部信息，是素材的唯一真相（见 ADR-0002）。
+* 写入一律原子替换；修改走 updateAsset，同一素材的读改写互斥。
+*/
+function assetFile(assetDir) {
+	return path.join(assetDir, ASSET_FILE);
+}
+async function readAsset(assetDir) {
+	let text;
+	try {
+		text = await readFile(assetFile(assetDir), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") throw new CliError(`素材不存在：${assetDir}`);
+		throw error;
+	}
+	const record = JSON.parse(text);
+	if (record.schema !== 1) throw new CliError(`无法识别的素材记录版本：${assetFile(assetDir)}`);
+	return record;
+}
+async function writeAsset(assetDir, record) {
+	await writeFileAtomic(assetFile(assetDir), `${JSON.stringify(record, null, 2)}\n`);
+}
+/**
+* 互斥地读改写一个素材：mutate 就地修改 record 并返回附带结果；返回前写回。
+* 多个 agent 同时操作同一素材时，后到的等待前一个写完。
+*/
+async function updateAsset(assetDir, mutate) {
+	const release = await lockfile.lock(assetFile(assetDir), {
+		retries: {
+			retries: 50,
+			minTimeout: 20,
+			maxTimeout: 200
+		},
+		stale: 3e4
+	});
+	try {
+		const record = await readAsset(assetDir);
+		const result = await mutate(record);
+		await writeAsset(assetDir, record);
+		return result;
+	} finally {
+		await release();
+	}
+}
+function findVersion(record, version) {
+	const found = record.versions.find((item) => item.number === version);
+	if (!found) throw new CliError(`版本不存在：v${version}`);
+	return found;
+}
+function findGeneration(record, id) {
+	return id == null ? void 0 : record.generations.find((generation) => generation.id === id);
+}
+function now() {
+	return (/* @__PURE__ */ new Date()).toISOString();
+}
+// src/library/rules.ts
+function nextVersionNumber(versions) {
+	return Math.max(0, ...versions.map((version) => version.number)) + 1;
+}
+function nextGenerationId(generations) {
+	return Math.max(0, ...generations.map((generation) => generation.id)) + 1;
+}
+/** 来源链叶子：没有任何版本以它为源版本。 */
+function isLeaf(versions, version) {
+	return !versions.some((item) => item.sourceVersion === version);
+}
+/**
+* 当前版本失败后的顺位目标：同一次生成里序号更靠后、尚未失败的版本，取版本号最小者
+* （靠前优先、慢也等它）。没有可用版本时返回 null（指针停在失败版本）。
+*/
+function nextCurrentAfterFailure(versions, failed) {
+	if (failed.generation == null || failed.position == null) return null;
+	return versions.filter((version) => version.generation === failed.generation && version.position != null && version.position > failed.position && version.state !== "failed").sort((a, b) => a.number - b.number)[0]?.number ?? null;
+}
+/**
+* 删除当前版本后的回退目标：源版本（就绪）→ 最新就绪 → 最新生成中（均排除被删
+* 版本）。都没有时返回 null（调用方应据此阻止删除）。
+*/
+function nextCurrentAfterDelete(versions, deleted, sourceVersion) {
+	const others = versions.filter((version) => version.number !== deleted);
+	if (sourceVersion != null) {
+		const source = others.find((version) => version.number === sourceVersion && version.state === "ready");
+		if (source) return source.number;
+	}
+	const byNumberDesc = [...others].sort((a, b) => b.number - a.number);
+	const ready = byNumberDesc.find((version) => version.state === "ready");
+	if (ready) return ready.number;
+	return byNumberDesc.find((version) => version.state === "generating")?.number ?? null;
+}
+// src/library/scan.ts
+/** 扫描库目录找素材：含记录文件的文件夹即素材，不建总索引（见 ADR-0002）。 */
+async function isAssetDir(dir) {
+	try {
+		await access(path.join(dir, ASSET_FILE));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** dir 之下（含 dir）的全部素材文件夹；素材里不再往下找，隐藏目录跳过。 */
+async function findAssetDirs(dir) {
+	if (await isAssetDir(dir)) return [dir];
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	return (await Promise.all(entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => findAssetDirs(path.join(dir, entry.name))))).flat();
+}
+/** 文件所在的素材文件夹（在 root 之内逐级向上找）；不在任何素材里返回 null。 */
+async function findOwningAsset(root, filePath) {
+	const relative = path.relative(root, filePath);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) return null;
+	for (let dir = path.dirname(filePath); dir.startsWith(root) && dir !== root; dir = path.dirname(dir)) if (await isAssetDir(dir)) return dir;
+	return null;
+}
+// src/library/ops.ts
+/** 不经过模型的库操作：导入、设为当前版本、删除版本。 */
+/** 把外部文件导入为新素材的 v1（没有生成输入，入库即就绪）。 */
+async function importAsset(project, location, file) {
+	const source = path.resolve(file);
+	let bytes;
+	try {
+		bytes = await readFile(source);
+	} catch (error) {
+		if (error.code === "ENOENT") throw new CliError(`文件不存在：${file}`);
+		throw error;
+	}
+	const media = await inspectMedia(bytes);
+	await claimAssetDir(project, location);
+	try {
+		const fileName = versionFileName(1, media.extension);
+		const timestamp = now();
+		const record = {
+			schema: 1,
+			id: randomUUID(),
+			kind: media.kind,
+			currentVersion: 1,
+			createdAt: timestamp,
+			generations: [],
+			versions: [{
+				number: 1,
+				state: "ready",
+				origin: "import",
+				generation: null,
+				position: null,
+				resultIndex: null,
+				sourceVersion: null,
+				taskId: null,
+				kieRequest: null,
+				kieRecord: null,
+				failReason: null,
+				credits: null,
+				file: fileName,
+				mimeType: media.mimeType,
+				fileSize: bytes.byteLength,
+				width: media.width,
+				height: media.height,
+				duration: media.duration,
+				importedFrom: path.basename(source),
+				createdAt: timestamp,
+				updatedAt: timestamp
+			}]
+		};
+		await copyFile(source, path.join(location.dir, fileName));
+		await writeFile(assetFile(location.dir), `${JSON.stringify(record, null, 2)}\n`, { flag: "wx" });
+	} catch (error) {
+		await rm(location.dir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+async function setCurrentVersion(location, number) {
+	await updateAsset(location.dir, (record) => {
+		if (findVersion(record, number).state !== "ready") throw new CliError("只能把就绪的版本设为当前版本");
+		record.currentVersion = number;
+	});
+}
+/**
+* 删除来源链叶子版本；素材至少保留一个版本。删除当前版本时指针回到源版本，
+* 没有则回到最新就绪版本。一次生成的版本全删完时，连同它的参考输入副本一起删。
+*/
+async function deleteVersion(location, number) {
+	await updateAsset(location.dir, async (record) => {
+		const version = findVersion(record, number);
+		if (!isLeaf(record.versions, number)) throw new CliError(`v${number} 有派生版本，不能删除`);
+		if (record.versions.length <= 1) throw new CliError("素材至少保留一个版本");
+		if (record.currentVersion === number) {
+			const next = nextCurrentAfterDelete(record.versions, number, version.sourceVersion);
+			if (next == null) throw new CliError("删除后没有可用的当前版本");
+			record.currentVersion = next;
+		}
+		record.versions = record.versions.filter((item) => item.number !== number);
+		if (version.file) await rm(path.join(location.dir, version.file), { force: true });
+		const generation = version.generation;
+		if (generation != null && !record.versions.some((item) => item.generation === generation)) {
+			record.generations = record.generations.filter((item) => item.id !== generation);
+			await rm(path.join(location.dir, REFERENCES_DIR, String(generation)), {
+				recursive: true,
+				force: true
+			});
+		}
+	});
+}
+/** 占用素材文件夹：不能已存在，也不能建在另一个素材里面。 */
+async function claimAssetDir(project, location) {
+	for (let dir = path.dirname(location.dir); dir.length > project.dir.length; dir = path.dirname(dir)) if (await isAssetDir(dir)) throw new CliError(`不能在素材里新建素材：${path.relative(project.dir, dir)}`);
+	await mkdir(path.dirname(location.dir), { recursive: true });
+	try {
+		await mkdir(location.dir);
+	} catch (error) {
+		if (error.code === "EEXIST") throw new CliError(await isAssetDir(location.dir) ? `素材已存在：${location.path}` : `已存在同名文件夹：${location.path}`);
+		throw error;
+	}
+}
+// src/generation/state.ts
+/** 一个 kie 任务对应的版本里，积分只记在结果序号 0 上，避免重复计量。 */
+function creditsFor(version, credits) {
+	return (version.resultIndex ?? 0) === 0 ? credits : null;
+}
+function failVersion(record, number, reason, task = {
+	credits: null,
+	kieRecord: null
+}) {
+	const version = record.versions.find((item) => item.number === number);
+	if (!version || version.state !== "generating") return;
+	version.state = "failed";
+	version.failReason = reason;
+	version.credits = creditsFor(version, task.credits);
+	version.kieRecord = task.kieRecord;
+	version.updatedAt = now();
+	if (record.currentVersion === number) {
+		const next = nextCurrentAfterFailure(record.versions, version);
+		if (next != null) record.currentVersion = next;
+	}
+}
+function fulfillVersion(record, number, product, task) {
+	const version = record.versions.find((item) => item.number === number);
+	if (!version || version.state !== "generating") return;
+	Object.assign(version, product, {
+		state: "ready",
+		failReason: null,
+		credits: creditsFor(version, task.credits),
+		kieRecord: task.kieRecord,
+		updatedAt: now()
+	});
+}
+// src/generation/submit.ts
+/**
+* 发起生成：先按模型的 schema 完成校验，再落记录（版本壳为生成中），最后上传文件、
+* 向 kie 下单并回填任务编号。下单失败的版本直接标失败，可重试。
+*/
+const defaultDeps$1 = {
+	upload: uploadKieFile,
+	createTask: createKieTask
+};
+/** 一次生成最多并列几个 kie 任务。 */
+const MAX_TASKS = 10;
+/** 新建素材并发起第一次生成；返回新版本号。 */
+async function createAsset(project, location, options, deps = defaultDeps$1) {
+	const plan = await planGeneration(options, null);
+	await claimAssetDir(project, location);
+	let created;
+	try {
+		created = await writeNewAsset(project, location, plan);
+	} catch (error) {
+		await rm(location.dir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	await dispatch(location.dir, created.generation, created.versions, deps);
+	return created.versions;
+}
+/**
+* 在已有素材里发起生成。from 指定时沿用该版本的模型与 input（重新生成），`-p` 给出的
+* 键覆盖沿用值；换了模型时不沿用 input。
+*/
+async function generateInAsset(project, location, options, deps = defaultDeps$1) {
+	const record = await readAsset(location.dir);
+	let plan;
+	if (options.from != null) {
+		const base = findGeneration(record, findVersion(record, options.from).generation);
+		if (!base) throw new CliError(`v${options.from} 不是生成产物，无法沿用生成输入`);
+		const modelId = options.model ?? base.model;
+		const inherited = modelId === base.model ? absoluteTemplate(location.dir, base.input) : {};
+		plan = await planGeneration({
+			...options,
+			model: modelId
+		}, base.sourceVersion, inherited);
+	} else plan = await planGeneration(options, null);
+	return appendAndDispatch(project, location, record, plan, deps);
+}
+/** AI 编辑：以某个就绪版本为源版本发起生成，参数里用 `@source` 引用它；未指定模型时沿用该版本的模型。 */
+async function editVersion(project, location, sourceVersion, options, deps = defaultDeps$1) {
+	const record = await readAsset(location.dir);
+	const source = findVersion(record, sourceVersion);
+	if (source.state !== "ready" || !source.file) throw new CliError(`v${sourceVersion} 尚未就绪，不能作为 AI 编辑的源版本`);
+	return appendAndDispatch(project, location, record, await planGeneration({
+		...options,
+		model: options.model ?? findGeneration(record, source.generation)?.model
+	}, sourceVersion), deps);
+}
+/** 原地重试失败的版本：沿用它那次生成的输入发一个新任务，版本号不变。 */
+async function retryVersion(location, number, deps = defaultDeps$1) {
+	const record = await readAsset(location.dir);
+	const version = findVersion(record, number);
+	const generation = findGeneration(record, version.generation);
+	if (version.state !== "failed") throw new CliError("只有失败的版本可以重试");
+	if (!generation) throw new CliError(`v${number} 不是生成产物，无法重试`);
+	await updateAsset(location.dir, (latest) => {
+		Object.assign(findVersion(latest, number), {
+			state: "generating",
+			resultIndex: 0,
+			failReason: null,
+			taskId: null,
+			kieRequest: null,
+			kieRecord: null,
+			credits: null,
+			updatedAt: now()
+		});
+	});
+	await dispatch(location.dir, generation, [number], deps);
+	return [number];
+}
+/**
+* 解析 `-p` 并与沿用的 input 合并，按模型 schema 校验（值类型就地转换）。
+* `@source` 只能用在 AI 编辑（或沿用了 AI 编辑的重新生成）里。
+*/
+async function planGeneration(options, sourceVersion, inherited = {}) {
+	if (!options.model) throw new CliError("缺少 --model");
+	const tasks = options.count ?? 1;
+	if (!Number.isInteger(tasks) || tasks < 1 || tasks > MAX_TASKS) throw new CliError(`count 范围是 1–${MAX_TASKS}`);
+	const model = await findModel(options.model);
+	const input = {
+		...inherited,
+		...absoluteFiles(parseInputArgs(options.params))
+	};
+	const hasSource = usesSource(input);
+	if (sourceVersion == null && hasSource) throw new CliError("@source 只能用于 AI 编辑");
+	if (sourceVersion != null && !hasSource && Object.keys(inherited).length === 0) throw new CliError("AI 编辑需要在参数里用 @source 引用源版本");
+	validateInput(await getInputSchema(model.model), input);
+	return {
+		model,
+		input,
+		sourceVersion: hasSource ? sourceVersion : null,
+		tasks
+	};
+}
+/** 命令行里的文件路径转成绝对路径（相对调用时所在目录）。 */
+function absoluteFiles(input) {
+	return mapStrings(input, (text) => isLocalFile(text) ? `@${path.resolve(text.slice(1))}` : text);
+}
+/** 记录里的 input 模板（文件相对素材文件夹）→ 绝对路径，供重新生成沿用。 */
+function absoluteTemplate(dir, template) {
+	return mapStrings(template, (text) => isLocalFile(text) ? `@${path.join(dir, text.slice(1))}` : text);
+}
+function isLocalFile(text) {
+	return text.startsWith("@") && !text.startsWith("@@") && text !== "@source" && text.length > 1;
+}
+async function appendAndDispatch(project, location, record, plan, deps) {
+	if (plan.model.kind !== record.kind) throw new CliError(`模型 ${plan.model.model} 生成 ${plan.model.kind}，与素材类型 ${record.kind} 不符`);
+	const references = await inspectReferences(project.root, plan.input);
+	const { generation, versions } = await updateAsset(location.dir, async (latest) => {
+		const id = nextGenerationId(latest.generations);
+		return appendGeneration(latest, id, plan, await copyReferences(location.dir, id, references));
+	});
+	await dispatch(location.dir, generation, versions, deps);
+	return versions;
+}
+/** 写入新素材的记录与参考输入副本；新素材的当前版本取版本号最靠前的版本壳。 */
+async function writeNewAsset(project, location, plan) {
+	const references = await inspectReferences(project.root, plan.input);
+	const record = {
+		schema: 1,
+		id: randomUUID(),
+		kind: plan.model.kind,
+		currentVersion: 0,
+		createdAt: now(),
+		generations: [],
+		versions: []
+	};
+	const id = nextGenerationId(record.generations);
+	const appended = appendGeneration(record, id, plan, await copyReferences(location.dir, id, references));
+	record.currentVersion = appended.versions[0];
+	await writeFile(assetFile(location.dir), `${JSON.stringify(record, null, 2)}\n`, { flag: "wx" });
+	return appended;
+}
+/** input 引用的本机文件：识别类型；位于库内某个版本产物时记下出处。 */
+async function inspectReferences(root, input) {
+	return Promise.all(filePaths(input).map(async (file) => {
+		let bytes;
+		try {
+			if (!(await stat(file)).isFile()) throw new CliError(`不是文件：${file}`);
+			bytes = await readFile(file);
+		} catch (error) {
+			if (error.code === "ENOENT") throw new CliError(`文件不存在：${file}`);
+			throw error;
+		}
+		const media = await inspectMedia(bytes);
+		const owner = await findOwningAsset(root, file);
+		const version = versionFromFileName(path.basename(file));
+		return {
+			path: file,
+			name: path.basename(file),
+			kind: media.kind,
+			origin: owner && version != null ? {
+				asset: path.relative(root, owner).split(path.sep).join("/"),
+				version
+			} : null
+		};
+	}));
+}
+/** 参考输入复制到 references/<生成编号>/，保留原文件名，同名时加序号。 */
+async function copyReferences(dir, generationId, references) {
+	if (references.length === 0) return [];
+	const folder = path.join(REFERENCES_DIR, String(generationId));
+	const used = /* @__PURE__ */ new Set();
+	const records = [];
+	await mkdir(path.join(dir, folder), { recursive: true });
+	for (const { path: source, ...reference } of references) {
+		const { name, ext } = path.parse(reference.name);
+		let fileName = reference.name;
+		for (let index = 2; used.has(fileName); index++) fileName = `${name}-${index}${ext}`;
+		used.add(fileName);
+		const file = path.join(folder, fileName).split(path.sep).join("/");
+		await copyFile(source, path.join(dir, file));
+		records.push({
+			...reference,
+			file,
+			source
+		});
+	}
+	return records;
+}
+/** 追加一次生成与它的版本壳（每个任务一个，就地修改 record）；返回新版本号。 */
+function appendGeneration(record, id, plan, references) {
+	const timestamp = now();
+	const copies = new Map(references.map((reference) => [reference.source, reference.file]));
+	const generation = {
+		id,
+		model: plan.model.model,
+		input: mapStrings(plan.input, (text) => isLocalFile(text) && copies.has(text.slice(1)) ? `@${copies.get(text.slice(1))}` : text),
+		references: references.map(({ source: _source, ...reference }) => reference),
+		sourceVersion: plan.sourceVersion,
+		createdAt: timestamp
+	};
+	const base = nextVersionNumber(record.versions);
+	const versions = [];
+	for (let position = 0; position < plan.tasks; position++) {
+		const number = base + position;
+		record.versions.push({
+			number,
+			state: "generating",
+			origin: "generation",
+			generation: id,
+			position,
+			resultIndex: 0,
+			sourceVersion: plan.sourceVersion,
+			taskId: null,
+			kieRequest: null,
+			kieRecord: null,
+			failReason: null,
+			credits: null,
+			file: null,
+			mimeType: null,
+			fileSize: null,
+			width: null,
+			height: null,
+			duration: null,
+			importedFrom: null,
+			createdAt: timestamp,
+			updatedAt: timestamp
+		});
+		versions.push(number);
+	}
+	record.generations.push(generation);
+	return {
+		generation,
+		versions
+	};
+}
+/**
+* 上传 input 引用的文件与源版本换取临时地址（每次下单都重新上传，不保存），每个版本壳
+* 各下一单并回填任务编号。上传或下单失败的版本标失败。
+*/
+async function dispatch(dir, generation, versions, deps) {
+	let task;
+	try {
+		const record = await readAsset(dir);
+		const sourceFile = generation.sourceVersion != null ? findVersion(record, generation.sourceVersion).file : null;
+		const files = new Map(filePaths(generation.input).map((file) => [`@${file}`, path.join(dir, file)]));
+		if (sourceFile && usesSource(generation.input)) files.set(SOURCE_TOKEN, path.join(dir, sourceFile));
+		const urls = new Map(await Promise.all([...files].map(async ([token, file]) => [token, await deps.upload(file)])));
+		task = {
+			model: generation.model,
+			input: resolveTokens(generation.input, (token) => urls.get(token))
+		};
+	} catch (error) {
+		await failVersions(dir, versions, error.message);
+		return;
+	}
+	await Promise.all(versions.map(async (number) => {
+		let taskId;
+		try {
+			taskId = await deps.createTask(task);
+		} catch (error) {
+			await failVersions(dir, [number], error.message, task);
+			return;
+		}
+		await updateAsset(dir, (record) => {
+			const version = record.versions.find((item) => item.number === number);
+			if (version?.state === "generating") {
+				version.taskId = taskId;
+				version.kieRequest = task;
+				version.updatedAt = now();
+			}
+		});
+	}));
+}
+async function failVersions(dir, numbers, reason, task = null) {
+	await updateAsset(dir, (record) => {
+		for (const number of numbers) {
+			const version = record.versions.find((item) => item.number === number);
+			if (version) version.kieRequest = task;
+			failVersion(record, number, reason);
+		}
+	});
+}
+// src/kie/record.ts
+/**
+* 把 kie.ai 的五态任务记录归约成三态。结果在 resultJson 里：图片、视频、语音为
+* `{ resultUrls: [...] }`；Suno（音乐、音效）为 `{ data: [{ audio_url, duration }, ...] }`。
+*/
+function parseKieRecord(record) {
+	const credits = record.creditsConsumed ?? null;
+	if (record.state === "fail") return {
+		state: "failed",
+		results: [],
+		failReason: record.failMsg || "生成失败",
+		credits
+	};
+	if (record.state !== "success") return {
+		state: "pending",
+		results: [],
+		failReason: null,
+		credits
+	};
+	const results = parseResults(record.resultJson);
+	if (results.length === 0) return {
+		state: "failed",
+		results: [],
+		failReason: "生成结果为空",
+		credits
+	};
+	return {
+		state: "succeeded",
+		results,
+		failReason: null,
+		credits
+	};
+}
+/** resultJson → 产物列表；格式异常或为空返回空数组（由调用方按失败处理，避免卡在 pending）。 */
+function parseResults(resultJson) {
+	let parsed;
+	try {
+		parsed = JSON.parse(resultJson ?? "{}");
+	} catch {
+		return [];
+	}
+	if (Array.isArray(parsed.resultUrls)) return parsed.resultUrls.filter((url) => typeof url === "string" && url !== "").map((url) => ({
+		url,
+		duration: null
+	}));
+	if (Array.isArray(parsed.data)) return parsed.data.filter((track) => typeof track?.audio_url === "string" && track.audio_url !== "").map((track) => ({
+		url: track.audio_url,
+		duration: typeof track.duration === "number" ? track.duration : null
+	}));
+	return [];
+}
+// src/generation/sync.ts
+/**
+* 向 kie 求证并收取产物：按任务分组，一次 recordInfo 推进同一任务的全部版本。
+* 产物先下载到素材文件夹里的临时文件，加锁确认版本仍在等待该任务后再就位，
+* 因此多个进程同时收取也只会落一份（幂等）。
+*/
+const defaultDeps = {
+	getRecord: getKieRecord,
+	download: downloadFile
+};
+/** 提交到一半中断（有记录、没任务编号）的版本，超过这个时长按失败处理，可重试。 */
+const STUCK_DISPATCH_MS = 6e5;
+const POLL_INTERVAL_MS = 5e3;
+/** 同步一批素材里所有生成中的版本；返回过程中遇到的问题（不中断其余任务）。 */
+async function syncAssets(assetDirs, deps = defaultDeps) {
+	return (await Promise.all(assetDirs.map((dir) => syncAsset(dir, deps).catch((error) => [`${dir}：${error.message}`])))).flat();
+}
+/**
+* 轮询直到目标版本全部到达终态或超时；返回是否全部完成与过程中的问题。
+* targets 的 versions 为空表示该素材里所有生成中的版本。
+*/
+async function waitForVersions(targets, timeoutMs, deps = defaultDeps) {
+	const deadline = Date.now() + timeoutMs;
+	const warnings = /* @__PURE__ */ new Set();
+	for (;;) {
+		for (const warning of await syncAssets(targets.map((target) => target.dir), deps)) warnings.add(warning);
+		if (await allSettled(targets)) return {
+			done: true,
+			warnings: [...warnings]
+		};
+		if (Date.now() + POLL_INTERVAL_MS > deadline) return {
+			done: false,
+			warnings: [...warnings]
+		};
+		await setTimeout(POLL_INTERVAL_MS);
+	}
+}
+async function allSettled(targets) {
+	for (const target of targets) if ((await readAsset(target.dir)).versions.some((version) => version.state === "generating" && (!target.versions || target.versions.includes(version.number)))) return false;
+	return true;
+}
+async function syncAsset(dir, deps) {
+	const record = await readAsset(dir);
+	const generating = record.versions.filter((version) => version.state === "generating");
+	const stuck = generating.filter((version) => !version.taskId && Date.now() - Date.parse(version.updatedAt) > STUCK_DISPATCH_MS);
+	if (stuck.length > 0) await updateAsset(dir, (latest) => {
+		for (const version of stuck) if (!latest.versions.find((item) => item.number === version.number)?.taskId) failVersion(latest, version.number, "提交中断，可重试");
+	});
+	const taskIds = [...new Set(generating.map((version) => version.taskId).filter((taskId) => taskId != null))];
+	const warnings = [];
+	for (const taskId of taskIds) try {
+		await syncTask(dir, record, taskId, deps);
+	} catch (error) {
+		warnings.push(`${path.basename(dir)} 任务 ${taskId} 同步失败：${error.message}`);
+	}
+	return warnings;
+}
+async function syncTask(dir, record, taskId, deps) {
+	const kieRecord = await deps.getRecord(taskId);
+	const result = parseKieRecord(kieRecord);
+	if (result.state === "pending") return;
+	const members = record.versions.filter((version) => version.state === "generating" && version.taskId === taskId);
+	const task = {
+		credits: result.credits,
+		kieRecord
+	};
+	if (result.state === "failed") {
+		await updateAsset(dir, (latest) => {
+			for (const member of members) if (stillWaiting(latest, member.number, taskId)) failVersion(latest, member.number, result.failReason ?? "生成失败", task);
+		});
+		return;
+	}
+	const downloads = await Promise.all(result.results.map((item, index) => downloadProduct(dir, record, taskId, index, item, deps)));
+	await updateAsset(dir, async (latest) => {
+		const waiting = members.filter((member) => stillWaiting(latest, member.number, taskId));
+		const lead = waiting[0];
+		for (const [index, product] of downloads.entries()) {
+			const target = latest.versions.find((version) => version.taskId === taskId && version.resultIndex === index) ?? (lead ? appendResultVersion(latest, lead, index) : null);
+			if (!target || target.state !== "generating") {
+				if (!("error" in product)) await rm(product.temp, { force: true });
+				continue;
+			}
+			if ("error" in product) failVersion(latest, target.number, product.error, task);
+			else {
+				const file = versionFileName(target.number, product.extension);
+				await rename(product.temp, path.join(dir, file));
+				fulfillVersion(latest, target.number, {
+					...product.info,
+					file
+				}, task);
+			}
+		}
+		for (const member of waiting) if (stillWaiting(latest, member.number, taskId)) failVersion(latest, member.number, "生成结果为空", task);
+	});
+}
+function stillWaiting(record, number, taskId) {
+	const version = record.versions.find((item) => item.number === number);
+	return version?.state === "generating" && version.taskId === taskId;
+}
+/** 一个任务返回多个结果时，为多出来的结果追加同一次生成的新版本（排在该生成末尾）。 */
+function appendResultVersion(record, lead, resultIndex) {
+	const positions = record.versions.filter((version) => version.generation === lead.generation).map((version) => version.position ?? 0);
+	const version = {
+		...lead,
+		number: nextVersionNumber(record.versions),
+		state: "generating",
+		position: Math.max(...positions) + 1,
+		resultIndex,
+		createdAt: now(),
+		updatedAt: now()
+	};
+	record.versions.push(version);
+	return version;
+}
+/** 下载并识别产物；类型与素材不符时返回错误（按失败处理），网络错误直接抛出（下次再收）。 */
+async function downloadProduct(dir, record, taskId, index, item, deps) {
+	const { bytes, contentType } = await deps.download(item.url);
+	const media = await inspectMedia(bytes, contentType);
+	if (media.kind !== record.kind) return { error: `产物类型（${media.kind}）与素材类型（${record.kind}）不符` };
+	const temp = path.join(dir, `.${taskId}-${index}.${process.pid}.part`);
+	await writeFile(temp, bytes);
+	return {
+		temp,
+		extension: media.extension,
+		info: {
+			mimeType: media.mimeType,
+			fileSize: bytes.byteLength,
+			width: media.width,
+			height: media.height,
+			duration: media.duration ?? item.duration
+		}
+	};
+}
+// src/project/identify.ts
+/** 识别调用时所在的代码项目：远程地址 + 主仓库位置（见 ADR-0004）。 */
+const run = promisify(execFile);
+async function git(cwd, args) {
+	try {
+		const { stdout } = await run("git", [
+			"-C",
+			cwd,
+			...args
+		]);
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+async function identifyCodeProject(cwd) {
+	const dir = await realpath(cwd);
+	const commonDir = await git(dir, [
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-common-dir"
+	]);
+	if (!commonDir) return {
+		remote: null,
+		path: dir
+	};
+	const mainPath = path.basename(commonDir) === ".git" ? path.dirname(commonDir) : await git(dir, ["rev-parse", "--show-toplevel"]) ?? dir;
+	return {
+		remote: await remoteUrl(mainPath),
+		path: await realpath(mainPath)
+	};
+}
+/** 优先 origin，否则取第一个远程。 */
+async function remoteUrl(repo) {
+	const remotes = (await git(repo, ["remote"]))?.split("\n") ?? [];
+	const name = remotes.includes("origin") ? "origin" : remotes[0];
+	return name ? git(repo, [
+		"remote",
+		"get-url",
+		name
+	]) : null;
+}
+// src/project/map.ts
+/**
+* 项目映射：代码项目 → 库里的项目（见 ADR-0004）。有远程仓库的按远程地址识别、
+* 首次自动以仓库名登记；没有的按主仓库位置识别、首次必须指定名字；中途建了远程
+* 仓库的，按位置找到原条目补上远程地址，名字不变。
+*/
+/** 远程地址 → host/owner/repo（小写、去掉协议、用户名与 .git），用于判断是否同一仓库。 */
+function normalizeRemote(url) {
+	return remotePath(url).toLowerCase();
+}
+/** 远程仓库名（保留大小写），如 https://github.com/owner/pixel-quest.git → pixel-quest。 */
+function repoName(url) {
+	return remotePath(url).split("/").pop() ?? "";
+}
+function remotePath(url) {
+	const trimmed = url.trim();
+	let location;
+	if (trimmed.includes("://")) {
+		const parsed = new URL(trimmed);
+		location = `${parsed.hostname}${parsed.pathname}`;
+	} else location = trimmed.slice(trimmed.indexOf("@") + 1).replace(":", "/");
+	return location.replace(/\/+$/, "").replace(/\.git$/, "");
+}
+function findEntry(map, project) {
+	if (project.remote) {
+		const remote = normalizeRemote(project.remote);
+		const byRemote = map.projects.find((entry) => entry.remote != null && normalizeRemote(entry.remote) === remote);
+		if (byRemote) return byRemote;
+	}
+	return map.projects.find((entry) => entry.remote == null && entry.path === project.path);
+}
+/**
+* 按位置找到的条目补上新建的远程地址；返回是否有变化。按远程地址识别的条目不再
+* 依赖位置，位置保持登记时的值（同一远程的多个副本不会来回改写）。
+*/
+function refreshEntry(entry, project) {
+	if (project.remote && entry.remote == null) {
+		entry.remote = project.remote;
+		return true;
+	}
+	return false;
+}
+/** 查表；有远程仓库且未登记时自动以仓库名登记。就地修改 map，返回条目与是否有变化。 */
+function resolveProject(map, project) {
+	const existing = findEntry(map, project);
+	if (existing) return {
+		entry: existing,
+		changed: refreshEntry(existing, project)
+	};
+	if (!project.remote) throw new CliError(`当前代码项目未登记，运行 genlab project <名字> 登记：${project.path}`);
+	const name = validateName(repoName(project.remote), "项目名");
+	if (map.projects.some((entry) => entry.name === name)) throw new CliError(`项目名 ${name} 已被其他代码项目使用，运行 genlab project <名字> 指定`);
+	const entry = {
+		name,
+		remote: project.remote,
+		path: project.path
+	};
+	map.projects.push(entry);
+	return {
+		entry,
+		changed: true
+	};
+}
+/** 登记或修改当前代码项目对应的项目名；只改对应关系，不移动素材文件夹。 */
+function assignProject(map, project, name) {
+	const validName = validateName(name, "项目名");
+	if (validName === "projects.json") throw new CliError(`项目名不能是 ${PROJECT_MAP_FILE}`);
+	const existing = findEntry(map, project);
+	if (existing) {
+		refreshEntry(existing, project);
+		existing.name = validName;
+		return existing;
+	}
+	const entry = {
+		name: validName,
+		remote: project.remote,
+		path: project.path
+	};
+	map.projects.push(entry);
+	return entry;
+}
+/** 互斥地读改写库根目录下的映射表；mutate 返回是否需要写回。 */
+async function updateProjectMap(root, mutate) {
+	const file = path.join(root, PROJECT_MAP_FILE);
+	await mkdir(root, { recursive: true });
+	try {
+		await writeFile(file, `${JSON.stringify({ projects: [] }, null, 2)}\n`, { flag: "wx" });
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+	}
+	const release = await lockfile.lock(file, {
+		retries: {
+			retries: 50,
+			minTimeout: 20,
+			maxTimeout: 200
+		},
+		stale: 3e4
+	});
+	try {
+		const map = JSON.parse(await readFile(file, "utf8"));
+		const { result, changed } = mutate(map);
+		if (changed) await writeFileAtomic(file, `${JSON.stringify(map, null, 2)}\n`);
+		return result;
+	} finally {
+		await release();
+	}
+}
+// src/library/context.ts
+/** 命令的运行上下文：库根目录 + 当前代码项目对应的项目 + 素材定位。 */
+async function currentProject(cwd = process.cwd()) {
+	const root = libraryRoot();
+	const codeProject = await identifyCodeProject(cwd);
+	const name = await updateProjectMap(root, (map) => {
+		const { entry, changed } = resolveProject(map, codeProject);
+		return {
+			result: entry.name,
+			changed
+		};
+	});
+	return {
+		root,
+		name,
+		dir: path.join(root, name),
+		codeProject
+	};
+}
+function locateAsset(project, assetPath) {
+	const segments = parseAssetPath(assetPath);
+	return {
+		path: segments.join("/"),
+		dir: path.join(project.dir, ...segments)
+	};
+}
+// src/present.ts
+/** 命令输出的 JSON 形状：路径一律绝对路径，空字段省略。 */
+/** 去掉值为 null / undefined 的字段。 */
+function compact(object) {
+	return Object.fromEntries(Object.entries(object).filter(([, value]) => value != null));
+}
+function presentVersion(dir, version) {
+	return compact({
+		version: version.number,
+		state: version.state,
+		file: version.file ? path.join(dir, version.file) : null,
+		mimeType: version.mimeType,
+		width: version.width,
+		height: version.height,
+		duration: version.duration,
+		fileSize: version.fileSize,
+		credits: version.credits,
+		failReason: version.failReason,
+		generation: version.generation,
+		sourceVersion: version.sourceVersion,
+		importedFrom: version.importedFrom
+	});
+}
+/**
+* 加上与这些版本同一个 kie 任务的版本：一个任务返回多个结果时，多出来的结果在收取时
+* 才追加为新版本。
+*/
+function withTaskSiblings(record, versions) {
+	const taskIds = new Set(record.versions.filter((version) => versions.includes(version.number)).map((version) => version.taskId).filter((taskId) => taskId != null));
+	return record.versions.filter((version) => versions.includes(version.number) || version.taskId != null && taskIds.has(version.taskId)).map((version) => version.number);
+}
+/**
+* versions 指定时只列这些版本（连同同一任务追加出的版本）；pending 表示其中仍有生成中
+* 的版本。
+*/
+function presentAsset(project, location, record, versions) {
+	const wanted = versions && withTaskSiblings(record, versions);
+	const listed = record.versions.filter((version) => !wanted || wanted.includes(version.number));
+	return {
+		project: project.name,
+		asset: location.path,
+		dir: location.dir,
+		kind: record.kind,
+		current: record.currentVersion,
+		pending: listed.some((version) => version.state === "generating"),
+		versions: listed.map((version) => presentVersion(location.dir, version))
+	};
+}
+function presentGenerations(dir, record) {
+	return record.generations.map((generation) => compact({
+		generation: generation.id,
+		model: generation.model,
+		input: generation.input,
+		sourceVersion: generation.sourceVersion,
+		references: generation.references.map((reference) => compact({
+			file: path.join(dir, reference.file),
+			name: reference.name,
+			kind: reference.kind,
+			origin: reference.origin
+		})),
+		createdAt: generation.createdAt
+	}));
+}
+// src/commands/output.ts
+/** 命令输出：结果 JSON 写 stdout，警告与错误 JSON 写 stderr。 */
+function warn(message) {
+	process.stderr.write(`${JSON.stringify({ warning: message })}\n`);
+}
+/** 包装命令动作：输出结果，出错时输出错误并以退出码 1 结束。 */
+function action(run) {
+	return async (...args) => {
+		try {
+			const result = await run(...args);
+			const indent = process.stdout.isTTY ? 2 : void 0;
+			process.stdout.write(`${JSON.stringify(result, null, indent)}\n`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`${JSON.stringify({ error: message })}\n`);
+			process.exitCode = 1;
+		}
+	};
+}
+// src/commands/generation.ts
+/** 发起生成与等待结果的命令：create / generate / edit / retry / wait。 */
+function toGenerateOptions(args) {
+	return {
+		model: args.model,
+		params: args.param,
+		count: args.count
+	};
+}
+/** 按需等待新版本完成，再输出这些版本的状态。 */
+async function finish(project, location, versions, options) {
+	if (options.wait) {
+		const { warnings } = await waitForVersions([{
+			dir: location.dir,
+			versions
+		}], options.timeout * 1e3);
+		warnings.forEach(warn);
+	}
+	return presentAsset(project, location, await readAsset(location.dir), versions);
+}
+async function createCommand(assetPath, args) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	return finish(project, location, await createAsset(project, location, toGenerateOptions(args)), args);
+}
+async function generateCommand(assetPath, args) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	return finish(project, location, await generateInAsset(project, location, {
+		...toGenerateOptions(args),
+		from: args.from == null ? void 0 : parseVersionArg(args.from)
+	}), args);
+}
+async function editCommand(assetPath, version, args) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	return finish(project, location, await editVersion(project, location, parseVersionArg(version), toGenerateOptions(args)), args);
+}
+async function retryCommand(assetPath, version, args) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	return finish(project, location, await retryVersion(location, parseVersionArg(version)), args);
+}
+/** 等待某个素材、或当前项目里全部生成中的版本。 */
+async function waitCommand(assetPath, args) {
+	const project = await currentProject();
+	const dirs = assetPath ? [locateAsset(project, assetPath).dir] : await findAssetDirs(project.dir);
+	const targets = [];
+	for (const dir of dirs) {
+		const record = await readAsset(dir);
+		const versions = record.versions.filter((version) => version.state === "generating").map((version) => version.number);
+		if (versions.length > 0) targets.push({
+			dir,
+			versions
+		});
+		else if (assetPath) targets.push({
+			dir,
+			versions: record.versions.map((v) => v.number)
+		});
+	}
+	const { warnings } = await waitForVersions(targets, args.timeout * 1e3);
+	warnings.forEach(warn);
+	return Promise.all(targets.map(async ({ dir, versions }) => presentAsset(project, {
+		path: path.relative(project.dir, dir).split(path.sep).join("/"),
+		dir
+	}, await readAsset(dir), versions)));
+}
+// src/commands/library.ts
+/** 库与元信息命令：models / project / import / use / delete / show / list。 */
+/** 收取库里所有已完成的生成（每条库命令执行前跑一遍，不等待）。 */
+async function syncLibrary() {
+	(await syncAssets(await findAssetDirs(libraryRoot()))).forEach(warn);
+}
+function parseKind(kind) {
+	if (kind != null && !MEDIA_KINDS.includes(kind)) throw new CliError(`类型可选值：${MEDIA_KINDS.join(", ")}`);
+	return kind;
+}
+/** 模型列表（来自 kie 模型目录），或单个模型的价格与参数表。 */
+async function modelsCommand(id, args) {
+	if (id) {
+		const model = await findModel(id);
+		return {
+			model: model.model,
+			kind: model.kind,
+			taskType: model.taskType,
+			provider: model.provider,
+			price: model.pricingDesc,
+			...describeInput(await getInputSchema(model.model, args.refresh))
+		};
+	}
+	const kind = parseKind(args.kind);
+	const search = args.search?.toLowerCase();
+	const models = [];
+	for (const model of await listModels(args.refresh)) {
+		let modelKind;
+		try {
+			modelKind = kindForModel(model);
+		} catch {
+			continue;
+		}
+		if (!modelKind || kind && modelKind !== kind) continue;
+		const text = `${model.model} ${model.provider ?? ""} ${model.title ?? ""}`;
+		if (search && !text.toLowerCase().includes(search)) continue;
+		models.push({
+			model: model.model,
+			kind: modelKind,
+			taskType: model.taskType,
+			provider: model.provider
+		});
+	}
+	return models;
+}
+async function projectCommand(name) {
+	if (name) {
+		const root = libraryRoot();
+		const codeProject = await identifyCodeProject(process.cwd());
+		await updateProjectMap(root, (map) => ({
+			result: assignProject(map, codeProject, name),
+			changed: true
+		}));
+	}
+	const project = await currentProject();
+	return {
+		project: project.name,
+		dir: project.dir,
+		remote: project.codeProject.remote,
+		codeProject: project.codeProject.path
+	};
+}
+async function importCommand(assetPath, file) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	await importAsset(project, location, file);
+	return presentAsset(project, location, await readAsset(location.dir));
+}
+async function useCommand(assetPath, version) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	await setCurrentVersion(location, parseVersionArg(version));
+	return presentAsset(project, location, await readAsset(location.dir));
+}
+async function deleteCommand(assetPath, version) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	await deleteVersion(location, parseVersionArg(version));
+	return presentAsset(project, location, await readAsset(location.dir));
+}
+async function showCommand(assetPath) {
+	const project = await currentProject();
+	const location = locateAsset(project, assetPath);
+	const record = await readAsset(location.dir);
+	return {
+		...presentAsset(project, location, record),
+		record: assetFile(location.dir),
+		generations: presentGenerations(location.dir, record)
+	};
+}
+async function listCommand(folder, args) {
+	const kind = parseKind(args.kind);
+	const project = await currentProject();
+	const base = folder ? path.join(project.dir, ...parseAssetPath(folder)) : project.dir;
+	const assets = [];
+	for (const dir of await findAssetDirs(base)) {
+		const record = await readAsset(dir);
+		if (kind && record.kind !== kind) continue;
+		const current = record.versions.find((version) => version.number === record.currentVersion);
+		assets.push({
+			asset: path.relative(project.dir, dir).split(path.sep).join("/"),
+			kind: record.kind,
+			versions: record.versions.length,
+			generating: record.versions.filter((v) => v.state === "generating").length,
+			failed: record.versions.filter((v) => v.state === "failed").length,
+			current: current ? presentVersion(dir, current) : null
+		});
+	}
+	return {
+		project: project.name,
+		dir: project.dir,
+		assets
+	};
+}
+// src/commands/init.ts
+/** genlab init：写入配置文件（API Key 与库目录），先验证 Key 可用。 */
+const DEFAULT_LIBRARY = "~/GenLab";
+async function readConfig(file) {
+	try {
+		return parseEnv(await readFile(file, "utf8"));
+	} catch (error) {
+		if (error.code === "ENOENT") return {};
+		throw error;
+	}
+}
+/** 交互输入被取消时退出。 */
+function answered(value) {
+	if (p.isCancel(value)) {
+		p.cancel("已取消");
+		process.exit(1);
+	}
+	return value;
+}
+function expandHome(dir) {
+	return dir === "~" || dir.startsWith("~/") ? path.join(homedir(), dir.slice(1)) : dir;
+}
+/**
+* 未通过选项给出的值：终端里交互询问（直接回车沿用已有配置），非终端时沿用已有配置，
+* 都没有就报错。
+*/
+async function initCommand(args) {
+	const file = configFile();
+	const existing = await readConfig(file);
+	const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	let key = args.key ?? existing.KIE_API_KEY;
+	let library = args.library ?? existing.GENLAB_LIBRARY;
+	if (interactive && !args.key) key = answered(await p.password({
+		message: existing.KIE_API_KEY ? "kie.ai API Key（回车沿用已有）" : "kie.ai API Key（https://kie.ai/api-key）",
+		validate: (value) => value || existing.KIE_API_KEY ? void 0 : "不能为空"
+	})) || existing.KIE_API_KEY;
+	if (interactive && !args.library) library = answered(await p.text({
+		message: "库目录",
+		initialValue: existing.GENLAB_LIBRARY ?? DEFAULT_LIBRARY,
+		validate: (value) => value ? void 0 : "不能为空"
+	}));
+	if (!key) throw new CliError("缺少 --key");
+	library ||= DEFAULT_LIBRARY;
+	if (!path.isAbsolute(expandHome(library))) throw new CliError(`库目录必须是绝对路径：${library}`);
+	const credits = await getKieCredits(key);
+	await mkdir(expandHome(library), { recursive: true });
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFileAtomic(file, `KIE_API_KEY=${JSON.stringify(key)}\nGENLAB_LIBRARY=${JSON.stringify(library)}\n`, { mode: 384 });
+	return {
+		config: file,
+		library: expandHome(library),
+		credits
+	};
+}
+// src/cli.ts
+/** 单次命令默认最多等待的秒数：agent 执行命令通常 2 分钟超时。 */
+const DEFAULT_TIMEOUT_SECONDS = 90;
+function positiveInteger(value) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("应为正整数");
+	return parsed;
+}
+function collect(value, previous) {
+	return [...previous, value];
+}
+/** 先收取库里已完成的生成，再执行命令。 */
+function librarySynced(run) {
+	return action(async (...args) => {
+		await syncLibrary();
+		return run(...args);
+	});
+}
+const program = new Command("genlab").description("AI 媒体生成（kie.ai），产物与生成记录保存在本机的库里").version(version).showHelpAfterError();
+function generationOptions(command, requireModel) {
+	return command.option("-m, --model <id>", requireModel ? "模型（必填，见 genlab models）" : "模型，默认沿用").option("-p, --param <key=value>", "模型参数，可重复；key:=JSON 传 JSON 值，值写 @文件 上传本机文件", collect, []).option("-n, --count <n>", "并列发起几个任务", positiveInteger);
+}
+function waitOptions(command) {
+	return command.option("--no-wait", "提交后立即返回，不等待结果").option("--timeout <seconds>", "最多等待的秒数", positiveInteger, DEFAULT_TIMEOUT_SECONDS);
+}
+program.command("init").description("写入配置（kie.ai API Key 与库目录）").option("--key <key>", "kie.ai API Key").option("--library <dir>", "库目录").action(action(initCommand));
+program.command("models").description("列出 kie 模型；指定模型时输出价格与参数表").argument("[id]", "模型标识").option("--kind <kind>", "按类型筛选：image / video / audio").option("--search <text>", "按模型标识、供应商、标题筛选").option("--refresh", "忽略缓存，重新获取").action(action(modelsCommand));
+program.command("project").description("查看当前代码项目对应的项目；带名字时登记或修改").argument("[name]", "项目名").action(action(projectCommand));
+waitOptions(generationOptions(program.command("create").description("新建素材并发起第一次生成").argument("<asset>", "素材路径，如 角色/主角立绘"), true)).action(librarySynced(createCommand));
+waitOptions(generationOptions(program.command("generate").description("在已有素材里发起生成").argument("<asset>", "素材路径").option("--from <version>", "沿用某个版本的生成输入（重新生成）"), false)).action(librarySynced(generateCommand));
+waitOptions(generationOptions(program.command("edit").description("AI 编辑：以某个就绪版本为源版本发起生成，参数里用 @source 引用它").argument("<asset>", "素材路径").argument("<version>", "源版本号"), false)).action(librarySynced(editCommand));
+waitOptions(program.command("retry").description("原地重试失败的版本").argument("<asset>", "素材路径").argument("<version>", "版本号")).action(librarySynced(retryCommand));
+program.command("wait").description("等待生成中的版本；不指定素材时等待当前项目的全部").argument("[asset]", "素材路径").option("--timeout <seconds>", "最多等待的秒数", positiveInteger, DEFAULT_TIMEOUT_SECONDS).action(action(waitCommand));
+program.command("import").description("把外部文件导入为新素材的第一个版本").argument("<asset>", "素材路径").argument("<file>", "文件").action(librarySynced(importCommand));
+program.command("use").description("设为当前版本").argument("<asset>", "素材路径").argument("<version>", "版本号").action(librarySynced(useCommand));
+program.command("delete").description("删除版本（只能删没有派生版本的版本）").argument("<asset>", "素材路径").argument("<version>", "版本号").action(librarySynced(deleteCommand));
+program.command("show").description("查看素材的全部版本、生成输入与文件路径").argument("<asset>", "素材路径").action(librarySynced(showCommand));
+program.command("list").description("列出当前项目的素材").argument("[folder]", "只列某个文件夹").option("--kind <kind>", "按类型筛选：image / video / audio").action(librarySynced(listCommand));
+await program.parseAsync();
+export {};