genlab 0.1.1 → 0.1.3

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 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 { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { openAsBlob } from "node:fs";
 import { setTimeout } from "node:timers/promises";
 import { homedir } from "node:os";
@@ -14,11 +14,12 @@ 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 { spawn } from "node:child_process";
+import { parseEnv } from "node:util";
 import * as p from "@clack/prompts";
+import spawn$1 from "nano-spawn";
 // package.json
-var version = "0.1.1";
+var version = "0.1.3";
 // src/errors.ts
 /** 面向使用者的预期错误：只输出 message，不带堆栈。 */
 var CliError = class extends Error {
@@ -44,7 +45,7 @@ function loadEnv() {
 function requireEnv(name) {
 	loadEnv();
 	const value = process.env[name]?.trim();
-	if (!value) throw new CliError(`缺少配置 ${name}：在 ${configFile()} 中设置`);
+	if (!value) throw new CliError(`缺少配置 ${name}：运行 genlab init`);
 	return value;
 }
 /** 库的根目录：GENLAB_LIBRARY，支持 ~ 开头，必须是绝对路径。 */
@@ -102,10 +103,15 @@ async function uploadKieFile(filePath) {
 	if (!body.data?.downloadUrl) throw new CliError("kie.ai 上传未返回地址");
 	return body.data.downloadUrl;
 }
+/** 下载被拒绝（4xx，超时与限流除外）：链接已失效或无权访问，再试也拿不到。 */
+var DownloadRejectedError = class extends CliError {};
 /** 下载产物原文件。 */
 async function downloadFile(url) {
 	const response = await fetch(url, { signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS) });
-	if (!response.ok) throw new CliError(`下载产物失败：HTTP ${response.status}`);
+	if (!response.ok) {
+		const { status } = response;
+		throw new (status >= 400 && status < 500 && status !== 408 && status !== 429 ? DownloadRejectedError : CliError)(`下载产物失败：HTTP ${status}`);
+	}
 	return {
 		bytes: new Uint8Array(await response.arrayBuffer()),
 		contentType: response.headers.get("content-type")
@@ -338,6 +344,8 @@ const MEDIA_KINDS = [
 	"video",
 	"audio"
 ];
+/** 识别不出的媒体类型。 */
+var UnsupportedMediaError = class extends CliError {};
 /** 按内容识别不出时，按下载响应的 Content-Type 兜住常见格式。 */
 const MIME_EXTENSIONS = {
 	"image/png": "png",
@@ -364,7 +372,7 @@ async function inspectMedia(bytes, contentType = null) {
 	const mimeType = detected?.mime ?? headerMime;
 	const extension = detected?.ext ?? MIME_EXTENSIONS[headerMime];
 	const kind = kindForMime(mimeType);
-	if (!extension || !kind) throw new CliError(`无法识别的媒体类型：${mimeType || "未知"}`);
+	if (!extension || !kind) throw new UnsupportedMediaError(`无法识别的媒体类型：${mimeType || "未知"}`);
 	return {
 		mimeType,
 		extension,
@@ -405,8 +413,6 @@ async function measure(bytes, kind, mimeType) {
 const ASSET_FILE = "asset.json";
 /** 素材文件夹里存放参考输入副本的子目录，按生成编号分开。 */
 const REFERENCES_DIR = "references";
-/** 库根目录下的项目映射表。 */
-const PROJECT_MAP_FILE = "projects.json";
 const MAX_NAME_BYTES = 255;
 /** 项目、文件夹、素材名：非空，不以 . 开头，不含路径分隔符与控制字符。 */
 function validateName(name, what) {
@@ -441,6 +447,14 @@ function versionFromFileName(fileName) {
 * 素材记录文件：素材、生成、版本的全部信息，是素材的唯一真相（见 ADR-0002）。
 * 写入一律原子替换；修改走 updateAsset，同一素材的读改写互斥。
 */
+/** 第 1 版记录没记分配过的最大号，只能取现有版本的最大号；下次写入时存为第 2 版。 */
+function upgradeV1({ schema: _schema, ...record }) {
+	return {
+		schema: 2,
+		...record,
+		lastVersion: Math.max(0, ...record.versions.map((version) => version.number))
+	};
+}
 function assetFile(assetDir) {
 	return path.join(assetDir, ASSET_FILE);
 }
@@ -453,7 +467,8 @@ async function readAsset(assetDir) {
 		throw error;
 	}
 	const record = JSON.parse(text);
-	if (record.schema !== 1) throw new CliError(`无法识别的素材记录版本：${assetFile(assetDir)}`);
+	if (record.schema === 1) return upgradeV1(record);
+	if (record.schema !== 2) throw new CliError(`无法识别的素材记录版本：${assetFile(assetDir)}`);
 	return record;
 }
 async function writeAsset(assetDir, record) {
@@ -493,8 +508,10 @@ function now() {
 	return (/* @__PURE__ */ new Date()).toISOString();
 }
 // src/library/rules.ts
-function nextVersionNumber(versions) {
-	return Math.max(0, ...versions.map((version) => version.number)) + 1;
+/** 分配新版本号（就地更新 lastVersion）：接着分配过的最大号往后编，删过的号不复用。 */
+function allocateVersion(record) {
+	record.lastVersion += 1;
+	return record.lastVersion;
 }
 function nextGenerationId(generations) {
 	return Math.max(0, ...generations.map((generation) => generation.id)) + 1;
@@ -573,10 +590,11 @@ async function importAsset(project, location, file) {
 		const fileName = versionFileName(1, media.extension);
 		const timestamp = now();
 		const record = {
-			schema: 1,
+			schema: 2,
 			id: randomUUID(),
 			kind: media.kind,
 			currentVersion: 1,
+			lastVersion: 1,
 			createdAt: timestamp,
 			generations: [],
 			versions: [{
@@ -626,7 +644,7 @@ async function setCurrentVersion(location, 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 (!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);
@@ -656,42 +674,10 @@ async function claimAssetDir(project, location) {
 		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 下单并回填任务编号。下单失败的版本直接标失败，可重试。
+* 发起生成：按模型的 schema 校验，上传文件并向 kie 下单，拿到任务编号后才写进记录。
+* 记录里生成中的版本因此都有任务编号；下单失败直接报错，不留下版本。
 */
 const defaultDeps$1 = {
 	upload: uploadKieFile,
@@ -699,13 +685,31 @@ const defaultDeps$1 = {
 };
 /** 一次生成最多并列几个 kie 任务。 */
 const MAX_TASKS = 10;
-/** 新建素材并发起第一次生成；返回新版本号。 */
+/** 新建素材并发起第一次生成；新素材的当前版本取版本号最靠前的版本。 */
 async function createAsset(project, location, options, deps = defaultDeps$1) {
 	const plan = await planGeneration(options, null);
+	const references = await inspectReferences(project.root, plan.input);
 	await claimAssetDir(project, location);
-	let created;
 	try {
-		created = await writeNewAsset(project, location, plan);
+		const orders = await placeOrders(plan.model.model, plan.input, null, plan.tasks, deps);
+		const record = {
+			schema: 2,
+			id: randomUUID(),
+			kind: plan.model.kind,
+			currentVersion: 0,
+			lastVersion: 0,
+			createdAt: now(),
+			generations: [],
+			versions: []
+		};
+		const id = nextGenerationId(record.generations);
+		const versions = appendGeneration(record, id, plan, await copyReferences(location.dir, id, references), orders);
+		record.currentVersion = versions[0];
+		await writeFile(assetFile(location.dir), `${JSON.stringify(record, null, 2)}\n`, { flag: "wx" });
+		return {
+			versions,
+			errors: orders.errors
+		};
 	} catch (error) {
 		await rm(location.dir, {
 			recursive: true,
@@ -713,8 +717,6 @@ async function createAsset(project, location, options, deps = defaultDeps$1) {
 		});
 		throw error;
 	}
-	await dispatch(location.dir, created.generation, created.versions, deps);
-	return created.versions;
 }
 /**
 * 在已有素材里发起生成。from 指定时沿用该版本的模型与 input（重新生成），`-p` 给出的
@@ -745,27 +747,30 @@ async function editVersion(project, location, sourceVersion, options, deps = def
 		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} 不是生成产物，无法重试`);
+	const orders = await placeOrders(generation.model, absoluteTemplate(location.dir, generation.input), sourceFile(location, record, generation.sourceVersion), 1, deps);
 	await updateAsset(location.dir, (latest) => {
 		Object.assign(findVersion(latest, number), {
 			state: "generating",
 			resultIndex: 0,
-			failReason: null,
-			taskId: null,
-			kieRequest: null,
+			taskId: orders.taskIds[0],
+			kieRequest: orders.request,
 			kieRecord: null,
+			failReason: null,
 			credits: null,
 			updatedAt: now()
 		});
 	});
-	await dispatch(location.dir, generation, [number], deps);
-	return [number];
+	return {
+		versions: [number],
+		errors: []
+	};
 }
 /**
 * 解析 `-p` 并与沿用的 input 合并，按模型 schema 校验（值类型就地转换）。
@@ -774,7 +779,7 @@ async function retryVersion(location, number, deps = defaultDeps$1) {
 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}`);
+	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,
@@ -805,30 +810,19 @@ function isLocalFile(text) {
 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 orders = await placeOrders(plan.model.model, plan.input, sourceFile(location, record, plan.sourceVersion), plan.tasks, deps);
+	return {
+		versions: await updateAsset(location.dir, async (latest) => {
+			const id = nextGenerationId(latest.generations);
+			return appendGeneration(latest, id, plan, await copyReferences(location.dir, id, references), orders);
+		}),
+		errors: orders.errors
 	};
-	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;
+}
+/** 源版本产物的绝对路径；没有源版本时为 null。 */
+function sourceFile(location, record, sourceVersion) {
+	const file = sourceVersion == null ? null : findVersion(record, sourceVersion).file;
+	return file ? path.join(location.dir, file) : null;
 }
 /** input 引用的本机文件：识别类型；位于库内某个版本产物时记下出处。 */
 async function inspectReferences(root, input) {
@@ -877,22 +871,12 @@ async function copyReferences(dir, generationId, references) {
 	}
 	return records;
 }
-/** 追加一次生成与它的版本壳（每个任务一个，就地修改 record）；返回新版本号。 */
-function appendGeneration(record, id, plan, references) {
+/** 追加一次生成与它的版本（每个 kie 接受的任务一个，就地修改 record）；返回新版本号。 */
+function appendGeneration(record, id, plan, references, orders) {
 	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;
+	const versions = orders.taskIds.map((taskId, position) => {
+		const number = allocateVersion(record);
 		record.versions.push({
 			number,
 			state: "generating",
@@ -901,8 +885,8 @@ function appendGeneration(record, id, plan, references) {
 			position,
 			resultIndex: 0,
 			sourceVersion: plan.sourceVersion,
-			taskId: null,
-			kieRequest: null,
+			taskId,
+			kieRequest: orders.request,
 			kieRecord: null,
 			failReason: null,
 			credits: null,
@@ -916,60 +900,42 @@ function appendGeneration(record, id, plan, references) {
 			createdAt: timestamp,
 			updatedAt: timestamp
 		});
-		versions.push(number);
-	}
-	record.generations.push(generation);
-	return {
-		generation,
-		versions
-	};
+		return number;
+	});
+	record.generations.push({
+		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
+	});
+	return versions;
 }
 /**
-* 上传 input 引用的文件与源版本换取临时地址（每次下单都重新上传，不保存），每个版本壳
-* 各下一单并回填任务编号。上传或下单失败的版本标失败。
+* 上传 input 引用的文件与源版本换取临时地址（每次下单都重新上传，不保存），再下 count
+* 个任务。全部下单失败时报错；部分失败时返回成功的任务与失败原因。
 */
-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;
+async function placeOrders(model, input, source, count, deps) {
+	const files = new Map(filePaths(input).map((file) => [`@${file}`, file]));
+	if (usesSource(input)) {
+		if (!source) throw new CliError("源版本没有产物文件");
+		files.set(SOURCE_TOKEN, source);
 	}
-	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);
-		}
-	});
+	const urls = new Map(await Promise.all([...files].map(async ([token, file]) => [token, await deps.upload(file)])));
+	const request = {
+		model,
+		input: resolveTokens(input, (token) => urls.get(token))
+	};
+	const results = await Promise.allSettled(Array.from({ length: count }, () => deps.createTask(request)));
+	const taskIds = results.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
+	const errors = [...new Set(results.flatMap((result) => result.status === "rejected" ? [result.reason.message] : []))];
+	if (taskIds.length === 0) throw new CliError(errors[0] ?? "下单失败");
+	return {
+		request,
+		taskIds,
+		errors
+	};
 }
 // src/kie/record.ts
 /**
@@ -1022,40 +988,120 @@ function parseResults(resultJson) {
 	}));
 	return [];
 }
+// 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/sync.ts
 /**
 * 向 kie 求证并收取产物：按任务分组，一次 recordInfo 推进同一任务的全部版本。
 * 产物先下载到素材文件夹里的临时文件，加锁确认版本仍在等待该任务后再就位，
 * 因此多个进程同时收取也只会落一份（幂等）。
+*
+* 收取只在后台收取进程里进行，全库同一时间只有一个（见 ADR-0007）：每条素材命令结束时、
+* 以及开始等待时启动它，收完或超过时限即退出；等待只读记录。
 */
 const defaultDeps = {
 	getRecord: getKieRecord,
 	download: downloadFile
 };
-/** 提交到一半中断（有记录、没任务编号）的版本，超过这个时长按失败处理，可重试。 */
-const STUCK_DISPATCH_MS = 6e5;
 const POLL_INTERVAL_MS = 5e3;
-/** 同步一批素材里所有生成中的版本；返回过程中遇到的问题（不中断其余任务）。 */
+/** 收取者锁：库根目录下的点目录，扫描库时跳过。 */
+const COLLECTOR_LOCK = ".sync.lock";
+/** 后台收取进程最多运行的时长；超过后退出，下一条命令再启动。 */
+const COLLECTOR_MAX_MS = 18e5;
+/**
+* 以全库唯一收取者的身份执行 run；已有收取者时不执行。锁失效（如系统休眠）时可能
+* 短暂出现两个收取者，收取是幂等的，不影响结果。
+*/
+async function asCollector(root, run) {
+	let release;
+	try {
+		release = await lockfile.lock(root, {
+			lockfilePath: path.join(root, COLLECTOR_LOCK),
+			onCompromised: () => {}
+		});
+	} catch (error) {
+		if (error.code === "ELOCKED") return;
+		throw error;
+	}
+	try {
+		await run();
+	} finally {
+		await release().catch((error) => {
+			if (error.code !== "ERELEASED") throw error;
+		});
+	}
+}
+/** 仍有生成中版本的素材；读不出记录的跳过。 */
+async function pendingDirs(dirs) {
+	const pending = await Promise.all(dirs.map(async (dir) => {
+		try {
+			return (await readAsset(dir)).versions.some((version) => version.state === "generating");
+		} catch {
+			return false;
+		}
+	}));
+	return dirs.filter((_, index) => pending[index]);
+}
+/**
+* 后台收取：作为全库唯一的收取者轮询，每轮重新扫描库（包括期间新发起的生成），
+* 全部收完或超过时限后返回；已有收取者时立即返回。
+*/
+async function collectLibrary(root, deps = defaultDeps) {
+	const pending = async () => pendingDirs(await findAssetDirs(root));
+	await asCollector(root, async () => {
+		const deadline = Date.now() + COLLECTOR_MAX_MS;
+		for (;;) {
+			const dirs = await pending();
+			if (dirs.length === 0) return;
+			await syncAssets(dirs, deps);
+			if ((await pending()).length === 0 || Date.now() + POLL_INTERVAL_MS > deadline) return;
+			await setTimeout(POLL_INTERVAL_MS);
+		}
+	});
+}
+/** 收取一批素材里所有生成中的版本；返回过程中遇到的问题（不中断其余任务）。 */
 async function syncAssets(assetDirs, deps = defaultDeps) {
 	return (await Promise.all(assetDirs.map((dir) => syncAsset(dir, deps).catch((error) => [`${dir}：${error.message}`])))).flat();
 }
 /**
-* 轮询直到目标版本全部到达终态或超时；返回是否全部完成与过程中的问题。
-* targets 的 versions 为空表示该素材里所有生成中的版本。
+* 轮询记录，直到目标版本全部到达终态或超时；返回是否全部完成。只读记录，收取由后台
+* 收取进程负责。targets 的 versions 为空表示该素材里所有生成中的版本。
 */
-async function waitForVersions(targets, timeoutMs, deps = defaultDeps) {
+async function waitForVersions(targets, timeoutMs) {
 	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]
-		};
+		if (await allSettled(targets)) return true;
+		if (Date.now() + POLL_INTERVAL_MS > deadline) return false;
 		await setTimeout(POLL_INTERVAL_MS);
 	}
 }
@@ -1065,17 +1111,12 @@ async function allSettled(targets) {
 }
 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 taskIds = [...new Set(record.versions.filter((version) => version.state === "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}`);
+		warnings.push(`${path.basename(dir)} 任务 ${taskId} 收取失败：${error.message}`);
 	}
 	return warnings;
 }
@@ -1098,8 +1139,9 @@ async function syncTask(dir, record, taskId, deps) {
 	await updateAsset(dir, async (latest) => {
 		const waiting = members.filter((member) => stillWaiting(latest, member.number, taskId));
 		const lead = waiting[0];
+		const targets = downloads.map((_, index) => latest.versions.find((version) => version.taskId === taskId && version.resultIndex === index) ?? (lead ? appendResultVersion(latest, lead, index) : null));
 		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);
+			const target = targets[index];
 			if (!target || target.state !== "generating") {
 				if (!("error" in product)) await rm(product.temp, { force: true });
 				continue;
@@ -1126,7 +1168,7 @@ 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),
+		number: allocateVersion(record),
 		state: "generating",
 		position: Math.max(...positions) + 1,
 		resultIndex,
@@ -1136,10 +1178,21 @@ function appendResultVersion(record, lead, resultIndex) {
 	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);
+	let bytes;
+	let media;
+	try {
+		const file = await deps.download(item.url);
+		bytes = file.bytes;
+		media = await inspectMedia(bytes, file.contentType);
+	} catch (error) {
+		if (error instanceof DownloadRejectedError || error instanceof UnsupportedMediaError) return { error: error.message };
+		throw error;
+	}
 	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);
@@ -1155,174 +1208,102 @@ async function downloadProduct(dir, record, taskId, index, item, deps) {
 		}
 	};
 }
-// 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
+// src/project/link.ts
 /**
-* 项目映射：代码项目 → 库里的项目（见 ADR-0004）。有远程仓库的按远程地址识别、
-* 首次自动以仓库名登记；没有的按主仓库位置识别、首次必须指定名字；中途建了远程
-* 仓库的，按位置找到原条目补上远程地址，名字不变。
+* 项目关联：代码项目里的 .genlab 点目录记下它对应库里的哪个项目（见 ADR-0006）。
+* 点目录自带只忽略自身的 .gitignore，不改动代码项目的任何忽略设置。
 */
-/** 远程地址 → 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;
+const LINK_DIR = ".genlab";
+const LINK_FILE = "project.json";
+const GITIGNORE = "# genlab 自动创建\n*\n";
+async function readIfExists(file) {
+	try {
+		return await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
 	}
-	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;
+function parseLink(text, file) {
+	let project;
+	try {
+		project = JSON.parse(text).project;
+	} catch {
+		project = void 0;
 	}
-	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;
+	if (typeof project !== "string") throw new CliError(`关联文件不合法：${file}`);
+	return project;
+}
+/** 从 cwd 逐级向上找最近的关联；都没有时返回 null。 */
+async function findLink(cwd) {
+	for (let dir = path.resolve(cwd);; dir = path.dirname(dir)) {
+		const linkDir = path.join(dir, LINK_DIR);
+		const file = path.join(linkDir, LINK_FILE);
+		const text = await readIfExists(file);
+		if (text != null) return {
+			project: parseLink(text, file),
+			dir: linkDir
+		};
+		if (path.dirname(dir) === dir) return null;
 	}
-	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 });
+/** 在 cwd 写入关联，返回点目录。 */
+async function writeLink(cwd, project) {
+	const linkDir = path.join(path.resolve(cwd), LINK_DIR);
+	await mkdir(linkDir, { recursive: true });
+	await writeFileAtomic(path.join(linkDir, ".gitignore"), GITIGNORE);
+	await writeFileAtomic(path.join(linkDir, LINK_FILE), `${JSON.stringify({ project }, null, 2)}\n`);
+	return linkDir;
+}
+// src/library/context.ts
+/** 命令的运行上下文：库根目录 + 本次使用的项目 + 素材定位。 */
+/** 内置项目：一直存在，放不属于任何代码项目的素材。 */
+const DEFAULT_PROJECT = "default";
+async function isDirectory(dir) {
 	try {
-		await writeFile(file, `${JSON.stringify({ projects: [] }, null, 2)}\n`, { flag: "wx" });
+		return (await stat(dir)).isDirectory();
 	} catch (error) {
-		if (error.code !== "EEXIST") throw error;
+		if (error.code === "ENOENT") return false;
+		throw error;
 	}
-	const release = await lockfile.lock(file, {
-		retries: {
-			retries: 50,
-			minTimeout: 20,
-			maxTimeout: 200
-		},
-		stale: 3e4
-	});
+}
+/** 库里的全部项目（库根目录下的文件夹），default 总在最前。 */
+async function listProjects(root) {
+	let names = [];
 	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();
+		names = (await readdir(root, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
 	}
+	return [DEFAULT_PROJECT, ...names.filter((name) => name !== DEFAULT_PROJECT).sort()];
 }
-// 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
-		};
-	});
+async function projectsHint(root) {
+	return `；已有项目：${(await listProjects(root)).join("、")}`;
+}
+/**
+* 项目必须已存在；default 除外，首次放入素材时自动建好。missing 是项目不存在时的
+* 提示，默认提示新建。
+*/
+async function openProject(root, name, missing) {
+	const validName = validateName(name, "项目名");
+	const dir = path.join(root, validName);
+	if (validName !== "default" && !await isDirectory(dir)) throw new CliError(`${missing ?? `项目不存在：${validName}，运行 genlab project create ${validName} 新建`}${await projectsHint(root)}`);
 	return {
 		root,
-		name,
-		dir: path.join(root, name),
-		codeProject
+		name: validName,
+		dir
 	};
 }
+/** 本次使用的项目：指定的项目优先，否则取 cwd 的关联。 */
+async function resolveProject(root, cwd, override) {
+	if (override != null) return openProject(root, override);
+	const link = await findLink(cwd);
+	if (link == null) throw new CliError(`当前目录未关联项目：运行 genlab project link <项目> 关联，不属于任何项目时用 ${DEFAULT_PROJECT}${await projectsHint(root)}`);
+	return openProject(root, link.project, `当前目录关联的项目不存在：${link.project}，可能已改名或删除；问用户要关联到哪个项目，再运行 genlab project link <项目>`);
+}
+function currentProject(override) {
+	return resolveProject(libraryRoot(), process.cwd(), override);
+}
 function locateAsset(project, assetPath) {
 	const segments = parseAssetPath(assetPath);
 	return {
@@ -1336,10 +1317,11 @@ function locateAsset(project, assetPath) {
 function compact(object) {
 	return Object.fromEntries(Object.entries(object).filter(([, value]) => value != null));
 }
-function presentVersion(dir, version) {
+function presentVersion(dir, record, version) {
 	return compact({
 		version: version.number,
 		state: version.state,
+		model: findGeneration(record, version.generation)?.model,
 		file: version.file ? path.join(dir, version.file) : null,
 		mimeType: version.mimeType,
 		width: version.width,
@@ -1375,7 +1357,7 @@ function presentAsset(project, location, record, versions) {
 		kind: record.kind,
 		current: record.currentVersion,
 		pending: listed.some((version) => version.state === "generating"),
-		versions: listed.map((version) => presentVersion(location.dir, version))
+		versions: listed.map((version) => presentVersion(location.dir, record, version))
 	};
 }
 function presentGenerations(dir, record) {
@@ -1412,33 +1394,58 @@ function action(run) {
 		}
 	};
 }
+// src/commands/sync.ts
+/** 后台收取：启动后台收取进程，以及它运行的隐藏命令 sync（见 ADR-0007）。 */
+/**
+* 启动后台收取进程，不等待它结束；已有收取者时它会立即退出。沿用当前进程的 node 与
+* 启动参数，开发时经 tsx 运行同样适用。
+*/
+function startBackgroundSync() {
+	spawn(process.execPath, [
+		...process.execArgv,
+		process.argv[1],
+		"sync"
+	], {
+		detached: true,
+		stdio: "ignore",
+		windowsHide: true
+	}).on("error", (error) => warn(`后台收取未能启动：${error.message}`)).unref();
+}
+/** 隐藏命令 sync：作为全库唯一的收取者，收完或超过时限后退出。 */
+async function syncCommand() {
+	await collectLibrary(libraryRoot());
+}
 // src/commands/generation.ts
 /** 发起生成与等待结果的命令：create / generate / edit / retry / wait。 */
 function toGenerateOptions(args) {
 	return {
 		model: args.model,
-		params: args.param,
+		params: args.param ?? [],
 		count: args.count
 	};
 }
-/** 按需等待新版本完成，再输出这些版本的状态。 */
-async function finish(project, location, versions, options) {
+/**
+* 部分下单失败的原因作为警告输出；按需等待新版本完成（先启动后台收取，等待只读记录），
+* 再输出这些版本的状态。
+*/
+async function finish(project, location, { versions, errors }, options) {
+	errors.forEach((error) => warn(`部分任务下单失败：${error}`));
 	if (options.wait) {
-		const { warnings } = await waitForVersions([{
+		startBackgroundSync();
+		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 project = await currentProject(args.project);
 	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 project = await currentProject(args.project);
 	const location = locateAsset(project, assetPath);
 	return finish(project, location, await generateInAsset(project, location, {
 		...toGenerateOptions(args),
@@ -1446,18 +1453,18 @@ async function generateCommand(assetPath, args) {
 	}), args);
 }
 async function editCommand(assetPath, version, args) {
-	const project = await currentProject();
+	const project = await currentProject(args.project);
 	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 project = await currentProject(args.project);
 	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 project = await currentProject(args.project);
 	const dirs = assetPath ? [locateAsset(project, assetPath).dir] : await findAssetDirs(project.dir);
 	const targets = [];
 	for (const dir of dirs) {
@@ -1472,19 +1479,23 @@ async function waitCommand(assetPath, args) {
 			versions: record.versions.map((v) => v.number)
 		});
 	}
-	const { warnings } = await waitForVersions(targets, args.timeout * 1e3);
-	warnings.forEach(warn);
+	startBackgroundSync();
+	await waitForVersions(targets, args.timeout * 1e3);
 	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);
+// src/commands/guide.ts
+/** genlab guide：输出给 agent 的完整用法。 */
+/** 手写的使用说明，后附由命令定义生成的命令参考，与已安装的版本一致。 */
+async function guideCommand(program, file) {
+	const guide = await readFile(file, "utf8");
+	const reference = program.createHelp().visibleCommands(program).filter((command) => program.commands.includes(command)).map((command) => command.helpInformation()).join("\n");
+	process.stdout.write(`${guide}\n## 命令参考\n\n\`\`\`text\n${reference}\`\`\`\n`);
 }
+// src/commands/library.ts
+/** 库与元信息命令：models / import / use / delete / show / list。 */
 function parseKind(kind) {
 	if (kind != null && !MEDIA_KINDS.includes(kind)) throw new CliError(`类型可选值：${MEDIA_KINDS.join(", ")}`);
 	return kind;
@@ -1524,43 +1535,26 @@ async function modelsCommand(id, args) {
 	}
 	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();
+async function importCommand(assetPath, file, args) {
+	const project = await currentProject(args.project);
 	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();
+async function useCommand(assetPath, version, args) {
+	const project = await currentProject(args.project);
 	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();
+async function deleteCommand(assetPath, version, args) {
+	const project = await currentProject(args.project);
 	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();
+async function showCommand(assetPath, args) {
+	const project = await currentProject(args.project);
 	const location = locateAsset(project, assetPath);
 	const record = await readAsset(location.dir);
 	return {
@@ -1571,7 +1565,7 @@ async function showCommand(assetPath) {
 }
 async function listCommand(folder, args) {
 	const kind = parseKind(args.kind);
-	const project = await currentProject();
+	const project = await currentProject(args.project);
 	const base = folder ? path.join(project.dir, ...parseAssetPath(folder)) : project.dir;
 	const assets = [];
 	for (const dir of await findAssetDirs(base)) {
@@ -1584,7 +1578,7 @@ async function listCommand(folder, args) {
 			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
+			current: current ? presentVersion(dir, record, current) : null
 		});
 	}
 	return {
@@ -1593,8 +1587,67 @@ async function listCommand(folder, args) {
 		assets
 	};
 }
+// src/commands/skill.ts
+/** genlab skill：经 skills（npx skills）全局安装或卸载本机 agent 的 genlab skill。 */
+/** 固定 skills 的版本，安装行为不随它的新版本变化。 */
+const SKILLS_CLI = "skills@1.7.6";
+const SKILL_SOURCE = "WBBB0730/genlab";
+const SKILL_NAME = "genlab";
+function isInteractive() {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+* 终端里由 skills 询问装到 / 卸载哪些 agent；非终端时加 --yes，作用于检测到的全部
+* agent。skills 的输出写 stderr，stdout 只留给命令结果。
+*/
+async function runSkills(args, interactive) {
+	await spawn$1("npx", [
+		"-y",
+		SKILLS_CLI,
+		...args,
+		"--global",
+		...interactive ? [] : ["--yes"]
+	], {
+		stdin: "inherit",
+		stdout: process.stderr,
+		stderr: "inherit"
+	});
+}
+async function installSkill(interactive) {
+	try {
+		await runSkills([
+			"add",
+			SKILL_SOURCE,
+			"--skill",
+			SKILL_NAME
+		], interactive);
+	} catch (error) {
+		throw new CliError(`安装 skill 失败：可手动运行 npx skills add ${SKILL_SOURCE} -g -s ${SKILL_NAME}`, { cause: error });
+	}
+}
+async function skillAddCommand() {
+	await installSkill(isInteractive());
+	return { installed: SKILL_NAME };
+}
+/** 来源有变化时才更新，沿用安装时选的 agent。 */
+async function skillUpdateCommand() {
+	try {
+		await runSkills(["update", SKILL_NAME], isInteractive());
+	} catch (error) {
+		throw new CliError(`更新 skill 失败：可手动运行 npx skills update ${SKILL_NAME} -g`, { cause: error });
+	}
+	return { updated: SKILL_NAME };
+}
+async function skillRemoveCommand() {
+	try {
+		await runSkills(["remove", SKILL_NAME], isInteractive());
+	} catch (error) {
+		throw new CliError(`卸载 skill 失败：可手动运行 npx skills remove ${SKILL_NAME} -g`, { cause: error });
+	}
+	return { removed: SKILL_NAME };
+}
 // src/commands/init.ts
-/** genlab init：写入配置文件（API Key 与库目录），先验证 Key 可用。 */
+/** genlab init：写入配置文件（API Key 与库目录），先验证 Key 可用；可顺带安装 skill。 */
 const DEFAULT_LIBRARY = "~/GenLab";
 async function readConfig(file) {
 	try {
@@ -1617,7 +1670,8 @@ function expandHome(dir) {
 }
 /**
 * 未通过选项给出的值：终端里交互询问（直接回车沿用已有配置），非终端时沿用已有配置，
-* 都没有就报错。
+* 都没有就报错。未指定 --skill / --no-skill 时终端里询问是否安装 skill，非终端不安装；
+* 安装失败只警告，不影响已写入的配置。
 */
 async function initCommand(args) {
 	const file = configFile();
@@ -1625,6 +1679,7 @@ async function initCommand(args) {
 	const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
 	let key = args.key ?? existing.KIE_API_KEY;
 	let library = args.library ?? existing.GENLAB_LIBRARY;
+	let skill = args.skill;
 	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 : "不能为空"
@@ -1634,6 +1689,7 @@ async function initCommand(args) {
 		initialValue: existing.GENLAB_LIBRARY ?? DEFAULT_LIBRARY,
 		validate: (value) => value ? void 0 : "不能为空"
 	}));
+	if (interactive && skill === void 0) skill = answered(await p.confirm({ message: "安装 skill，让 agent 需要生成媒体时自动想到 genlab？" }));
 	if (!key) throw new CliError("缺少 --key");
 	library ||= DEFAULT_LIBRARY;
 	if (!path.isAbsolute(expandHome(library))) throw new CliError(`库目录必须是绝对路径：${library}`);
@@ -1641,49 +1697,116 @@ async function initCommand(args) {
 	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 });
+	let installed = false;
+	if (skill) try {
+		await installSkill(interactive);
+		installed = true;
+	} catch (error) {
+		warn(error.message);
+	}
 	return {
 		config: file,
 		library: expandHome(library),
-		credits
+		credits,
+		skill: installed ? "genlab" : void 0
+	};
+}
+// src/commands/project.ts
+/** 项目命令：查看当前目录的关联、新建项目、关联当前目录（见 ADR-0006）。 */
+async function projectCommand() {
+	const root = libraryRoot();
+	const link = await findLink(process.cwd());
+	return {
+		project: link?.project,
+		dir: link ? path.join(root, link.project) : void 0,
+		link: link?.dir,
+		projects: await listProjects(root)
+	};
+}
+async function projectCreateCommand(name) {
+	const root = libraryRoot();
+	const validName = validateName(name, "项目名");
+	if (validName === "default") throw new CliError(`${DEFAULT_PROJECT} 是内置项目，无需新建`);
+	const dir = path.join(root, validName);
+	await mkdir(root, { recursive: true });
+	try {
+		await mkdir(dir);
+	} catch (error) {
+		if (error.code === "EEXIST") throw new CliError(`项目已存在：${validName}`);
+		throw error;
+	}
+	return {
+		project: validName,
+		dir
+	};
+}
+/** 在当前目录写入关联：指向已有项目或 default。 */
+async function projectLinkCommand(name) {
+	const project = await openProject(libraryRoot(), name);
+	const link = await writeLink(process.cwd(), project.name);
+	return {
+		project: project.name,
+		dir: project.dir,
+		link
 	};
 }
 // src/cli.ts
-/** 单次命令默认最多等待的秒数：agent 执行命令通常 2 分钟超时。 */
+/**
+* 单次命令默认最多等待的秒数：Claude Code 默认在前台等一条命令 2 分钟，超过转入后台，
+* 留在这之内 agent 能直接拿到结果。
+*/
 const DEFAULT_TIMEOUT_SECONDS = 90;
+/** 使用说明与入口同目录：打包时由 tsdown 复制到 dist。 */
+const GUIDE_FILE = new URL("./guide.md", import.meta.url);
 function positiveInteger(value) {
 	const parsed = Number(value);
 	if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("应为正整数");
 	return parsed;
 }
-function collect(value, previous) {
+/** 可重复的选项：不设默认值，帮助里不显示 (default: [])。 */
+function collect(value, previous = []) {
 	return [...previous, value];
 }
-/** 先收取库里已完成的生成，再执行命令。 */
-function librarySynced(run) {
+/** 执行命令，结束后在后台收取库里未完成的生成，不等待（见 ADR-0007）。 */
+function withBackgroundSync(run) {
 	return action(async (...args) => {
-		await syncLibrary();
-		return run(...args);
+		try {
+			return await run(...args);
+		} finally {
+			startBackgroundSync();
+		}
 	});
 }
-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);
+const program = new Command("genlab").description("用 kie.ai 的模型生成图片、视频、音频，产物与生成记录保存在本机的库里。完整用法：genlab guide").version(version, "-V, --version", "显示版本号").helpOption("-h, --help", "显示帮助").helpCommand("help [command]", "显示命令的帮助").showHelpAfterError();
+function generationOptions(command, modelDescription) {
+	return command.option("-m, --model <id>", modelDescription).option("-p, --param <key=value>", "模型参数，可重复；key:=JSON 传 JSON 值，@<路径> 上传本机文件", collect).option("-n, --count <n>", "并列任务数（1–10，默认 1）", positiveInteger);
+}
+function projectOption(command) {
+	return command.option("--project <name>", "本次使用的项目，不改动当前目录的关联");
 }
 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));
+program.command("guide").description("输出完整用法：概念、流程、参数写法、规则与命令参考").action(() => guideCommand(program, GUIDE_FILE));
+program.command("init").description("写入配置（kie.ai API Key 与库目录），可顺带安装 skill").option("--key <key>", "kie.ai API Key").option("--library <dir>", "库目录（绝对路径，可用 ~ 开头）").option("--skill", "安装 skill，不再询问").option("--no-skill", "不安装 skill").action(action(initCommand));
+const skill = program.command("skill").description("安装、更新或卸载 genlab skill，让 agent 能发现 genlab");
+skill.command("add", { isDefault: true }).description("安装 skill（默认）").action(action(skillAddCommand));
+skill.command("update").description("更新 skill，沿用安装时选的 agent").action(action(skillUpdateCommand));
+skill.command("remove").description("卸载 skill").action(action(skillRemoveCommand));
+program.command("models").description("列出 kie 模型；指定模型时输出价格与参数表").argument("[id]", "模型标识").option("--kind <kind>", "按类型筛选：image / video / audio").option("--search <text>", "按模型标识、供应商、名称筛选").option("--refresh", "忽略缓存，重新获取").action(action(modelsCommand));
+const project = program.command("project").description("查看当前目录关联的项目与库里的全部项目").action(action(projectCommand));
+project.command("create").description("新建项目").argument("<name>", "项目名").action(action(projectCreateCommand));
+project.command("link").description("把当前目录关联到项目；不属于任何代码项目时用 default").argument("<name>", "项目名").action(action(projectLinkCommand));
+projectOption(waitOptions(generationOptions(program.command("create").description("新建素材并发起第一次生成").argument("<asset>", "素材路径：[文件夹/]素材名，如 characters/hero"), "模型标识（必填，见 genlab models）"))).action(withBackgroundSync(createCommand));
+projectOption(waitOptions(generationOptions(program.command("generate").description("在已有素材里发起生成").argument("<asset>", "素材路径").option("--from <version>", "沿用某个版本的生成输入（重新生成）"), "模型标识；用 --from 时默认沿用原模型"))).action(withBackgroundSync(generateCommand));
+projectOption(waitOptions(generationOptions(program.command("edit").description("AI 编辑：以某个就绪版本为源版本发起生成，参数里用 @source 引用它").argument("<asset>", "素材路径").argument("<version>", "源版本号"), "模型标识，默认沿用源版本的模型"))).action(withBackgroundSync(editCommand));
+projectOption(waitOptions(program.command("retry").description("原地重试失败的版本").argument("<asset>", "素材路径").argument("<version>", "版本号，如 3 或 v3"))).action(withBackgroundSync(retryCommand));
+projectOption(program.command("wait").description("等待生成中的版本；不指定素材时等待当前项目的全部").argument("[asset]", "素材路径").option("--timeout <seconds>", "最多等待的秒数", positiveInteger, DEFAULT_TIMEOUT_SECONDS)).action(withBackgroundSync(waitCommand));
+projectOption(program.command("import").description("把外部文件导入为新素材的第一个版本").argument("<asset>", "素材路径").argument("<file>", "要导入的文件")).action(withBackgroundSync(importCommand));
+projectOption(program.command("use").description("把就绪的版本设为当前版本").argument("<asset>", "素材路径").argument("<version>", "版本号，如 3 或 v3")).action(withBackgroundSync(useCommand));
+projectOption(program.command("delete").description("删除没有子版本的版本").argument("<asset>", "素材路径").argument("<version>", "版本号，如 3 或 v3")).action(withBackgroundSync(deleteCommand));
+projectOption(program.command("show").description("查看素材的全部版本、生成输入与文件路径").argument("<asset>", "素材路径")).action(withBackgroundSync(showCommand));
+projectOption(program.command("list").description("列出当前项目的素材").argument("[folder]", "只列这个文件夹下的素材").option("--kind <kind>", "按类型筛选：image / video / audio")).action(withBackgroundSync(listCommand));
+program.command("sync", { hidden: true }).description("后台收取库里未完成的生成（由其他命令自动启动）").action(syncCommand);
 await program.parseAsync();
 export {};