genlab 0.1.2 → 0.1.4

package/README.md

@@ -1,60 +1,73 @@
-# genlab
+# GenLab
 
-给本地 agent（Claude Code、Codex 等）用的 AI 媒体生成命令行工具。通过 [kie.ai](https://kie.ai) 生成图片、视频、音频（音乐、音效、语音），产物与完整生成记录保存在本机的库里。
+给本地 agent（Claude Code、Codex 等）用的 AI 媒体生成命令行工具。通过 [Kie.ai](https://kie.ai) 生成图片、视频、音频（音乐、音效、语音），产物与完整生成记录保存在本机的库里。
 
-## 安装
+## 安装与配置
 
-需要 Node.js 22.19 及以上。
+需要 Node.js 22.19 及以上。推荐用 npx 运行，每次都是最新版本；下文的 `genlab` 均可写作 `npx -y genlab@latest`。也可 `npm install -g genlab` 全局安装，需自行更新。
 
 ```bash
-npm install -g genlab   # 或直接 npx genlab <命令>
+genlab init                                          # 交互填写 API Key 与库目录
+genlab init --key <KIE_API_KEY> --library ~/GenLab   # 或直接给出
 ```
 
-初始化配置（API Key 与库目录，写入 `~/.config/genlab/.env`，同名环境变量优先）：
+配置写入 `~/.config/genlab/.env`，同名环境变量优先。
 
-```bash
-genlab init
-# 或：genlab init --key <KIE_API_KEY> --library ~/GenLab
-```
+## 给 agent 使用
+
+agent 使用前先运行 `genlab guide`：它输出完整用法（概念、流程、参数写法、命令参考），内容总与当前版本一致。
 
-给 agent 安装使用说明（skill）：
+可选安装 GenLab skill，`genlab init` 时会询问，也可单独管理：
 
 ```bash
-npx skills add WBBB0730/genlab -g -s genlab
+genlab skill          # 安装
+genlab skill update   # 更新
+genlab skill remove   # 卸载
 ```
 
-## 用法
+库目录在代码项目之外。agent 在沙箱里运行时，需要允许它读写库目录与 `~/.cache/genlab`，并访问网络。
+
+## 示例
 
 ```bash
+# 新建项目，把当前目录关联到它
+genlab project create pixel-quest
+genlab project link pixel-quest
+
+# 找模型，查看价格与参数表
 genlab models --kind image --search gpt-image
-genlab models gpt-image-2-5-sunburst-text-to-image      # 价格与参数表
-genlab create 角色/主角立绘 -m gpt-image-2-5-sunburst-text-to-image -p prompt="像素风骑士立绘" -n 4
-genlab edit 角色/主角立绘 2 -m gpt-image-2-5-sunburst-image-to-image -p prompt="盔甲改成蓝色" -p input_urls=@source
-genlab use 角色/主角立绘 3
-genlab create 片头/镜头 -m wan/3-0-video -p prompt="骑士转身拔剑" -p first_frame_url=@<库>/<项目>/角色/主角立绘/v3.png
-genlab list
+genlab models gpt-image-2-5-sunburst-text-to-image
+
+# 新建素材，一次出 4 张（v1–v4）
+genlab create characters/hero -m gpt-image-2-5-sunburst-text-to-image -p prompt="像素风骑士立绘" -n 4
+
+# 对 v2 做 AI 编辑（产出 v5），把 v3 设为当前版本
+genlab edit characters/hero 2 -m gpt-image-2-5-sunburst-image-to-image -p prompt="盔甲改成蓝色" -p input_urls=@source
+genlab use characters/hero 3
+
+# 以 v3 为首帧生成视频
+genlab create intro/shot -m wan/3-0-video -p prompt="骑士转身拔剑" -p first_frame_url=@<库目录>/pixel-quest/characters/hero/v3.png
 ```
 
-参数用 `-p key=value`（`key:=JSON` 传 JSON 值，同键重复即数组）；值写 `@<路径>` 上传本机文件，`@source` 引用 AI 编辑的源版本。
+参数用 `-p key=value`（`key:=JSON` 传 JSON 值，同键重复即数组），参数名以 `genlab models <模型>` 的参数表为准；值写 `@<路径>` 上传本机文件，`@source` 引用 AI 编辑的源版本。
+
+## 项目与库
 
-完整命令见 `genlab --help` 与 [skills/genlab/SKILL.md](skills/genlab/SKILL.md)。
+代码项目用 `genlab project link <项目>` 关联到库里的项目，关联记在代码项目的 `.genlab/` 里（自带忽略文件，不会被 git 提交）。未关联时素材命令会报错；不属于任何代码项目的素材放进内置项目 `default`。
 
-## 库
+库就是普通文件夹，可以直接在文件管理器里浏览、改名、移动、删除：
 
 ```
-<GENLAB_LIBRARY>/
-  projects.json                 代码项目 → 项目的映射
+<库目录>/
   <项目>/<文件夹…>/<素材>/
     asset.json                  素材、生成、版本的完整记录
     v1.png  v2.png …            各版本产物
     references/<生成编号>/      参考输入副本
 ```
 
-项目由当前代码项目自动确定：有远程仓库时取仓库名，没有时用 `genlab project <名字>` 登记一次。
-
 ## 模型
 
-模型清单与参数实时取自 kie 的模型目录与 schema（缓存一天，`genlab models --refresh` 强制刷新），覆盖 kie 上全部图片、视频、音频模型。
+模型清单与参数取自 Kie.ai 的模型目录，本地缓存一天，`genlab models --refresh` 强制刷新。支持 Kie.ai 上的图片、视频、音频生成模型，不支持对话模型。
 
 ## 开发
 
@@ -64,16 +77,18 @@ pnpm dev <命令>      # 直接运行源码
 pnpm test
 pnpm lint
 pnpm typecheck
+pnpm check           # 检查格式
+pnpm format          # 格式化并自动修复
 pnpm build
 pnpm link --global   # 本机全局使用开发版
 ```
 
 ## 发布
 
-推送 `v*` tag 后由 GitHub Actions 发布到 npm，tag 含 `-beta` 时以 `beta` 标签发布。首次使用前需在 npmjs.com 为本包配置 Trusted Publishing，指向 `.github/workflows/publish.yml`。
-
 ```bash
 pnpm release   # bumpp：改版本号、提交、打 tag 并推送
 ```
 
-设计文档：[CONTEXT.md](CONTEXT.md)、[DESIGN.md](DESIGN.md)、[docs/prd](docs/prd)、[docs/adr](docs/adr)。
+推送 `v*` tag 后由 GitHub Actions 经 npm Trusted Publishing 发布，tag 含 `-beta` 时以 `beta` 标签发布。
+
+设计文档：术语表 [CONTEXT.md](CONTEXT.md)、命令行约定 [DESIGN.md](DESIGN.md)、需求 [docs/prd](docs/prd)、架构决策 [docs/adr](docs/adr)。

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.2";
+var version = "0.1.4";
 // 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，支持 ~ 开头，必须是绝对路径。 */
@@ -67,7 +68,7 @@ async function createKieTask(task) {
 		method: "POST",
 		body: JSON.stringify(task)
 	});
-	if (!body.data?.taskId) throw new CliError("kie.ai 未返回 taskId");
+	if (!body.data?.taskId) throw new CliError("Kie.ai 未返回 taskId");
 	return body.data.taskId;
 }
 async function listKieModels() {
@@ -84,7 +85,7 @@ async function getKieCredits(apiKey) {
 /** 任务的原始记录（完整保存进素材记录，解析见 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 未返回任务记录");
+	if (!body.data) throw new CliError("Kie.ai 未返回任务记录");
 	return body.data;
 }
 /**
@@ -99,13 +100,18 @@ async function uploadKieFile(filePath) {
 		method: "POST",
 		body: form
 	}, TRANSFER_TIMEOUT_MS);
-	if (!body.data?.downloadUrl) throw new CliError("kie.ai 上传未返回地址");
+	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")
@@ -139,9 +145,9 @@ async function kieFetch(url, init, timeoutMs = REQUEST_TIMEOUT_MS, apiKey = requ
 	try {
 		body = await response.json();
 	} catch {
-		throw new CliError(`kie.ai 请求失败：HTTP ${response.status}`);
+		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}`);
+	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
@@ -279,7 +285,7 @@ const TASK_PATH = "/api/v1/jobs/createTask";
 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} 的参数定义`);
+		if (!openapi) throw new CliError(`Kie.ai 尚未提供模型 ${model} 的参数定义`);
 		return openapi;
 	}, refresh);
 	const operation = (await dereference(structuredClone(doc), { resolve: { external: false } })).paths?.[TASK_PATH]?.post;
@@ -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);
@@ -675,10 +693,11 @@ async function createAsset(project, location, options, deps = defaultDeps$1) {
 	try {
 		const orders = await placeOrders(plan.model.model, plan.input, null, plan.tasks, deps);
 		const record = {
-			schema: 1,
+			schema: 2,
 			id: randomUUID(),
 			kind: plan.model.kind,
 			currentVersion: 0,
+			lastVersion: 0,
 			createdAt: now(),
 			generations: [],
 			versions: []
@@ -760,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,
@@ -856,9 +875,8 @@ async function copyReferences(dir, generationId, references) {
 function appendGeneration(record, id, plan, references, orders) {
 	const timestamp = now();
 	const copies = new Map(references.map((reference) => [reference.source, reference.file]));
-	const base = nextVersionNumber(record.versions);
 	const versions = orders.taskIds.map((taskId, position) => {
-		const number = base + position;
+		const number = allocateVersion(record);
 		record.versions.push({
 			number,
 			state: "generating",
@@ -921,7 +939,7 @@ async function placeOrders(model, input, source, count, deps) {
 }
 // src/kie/record.ts
 /**
-* 把 kie.ai 的五态任务记录归约成三态。结果在 resultJson 里：图片、视频、语音为
+* 把 Kie.ai 的五态任务记录归约成三态。结果在 resultJson 里：图片、视频、语音为
 * `{ resultUrls: [...] }`；Suno（音乐、音效）为 `{ data: [{ audio_url, duration }, ...] }`。
 */
 function parseKieRecord(record) {
@@ -1007,33 +1025,83 @@ function fulfillVersion(record, number, product, task) {
 * 向 kie 求证并收取产物：按任务分组，一次 recordInfo 推进同一任务的全部版本。
 * 产物先下载到素材文件夹里的临时文件，加锁确认版本仍在等待该任务后再就位，
 * 因此多个进程同时收取也只会落一份（幂等）。
+*
+* 收取只在后台收取进程里进行，全库同一时间只有一个（见 ADR-0007）：每条素材命令结束时、
+* 以及开始等待时启动它，收完或超过时限即退出；等待只读记录。
 */
 const defaultDeps = {
 	getRecord: getKieRecord,
 	download: downloadFile
 };
 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);
 	}
 }
@@ -1048,7 +1116,7 @@ async function syncAsset(dir, deps) {
 	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;
 }
@@ -1071,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;
@@ -1099,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,
@@ -1109,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);
@@ -1128,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 {
@@ -1309,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,
@@ -1348,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) {
@@ -1385,34 +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, 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),
@@ -1420,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) {
@@ -1446,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;
@@ -1498,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 {
@@ -1545,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)) {
@@ -1558,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 {
@@ -1567,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 {
@@ -1589,75 +1668,159 @@ function answered(value) {
 function expandHome(dir) {
 	return dir === "~" || dir.startsWith("~/") ? path.join(homedir(), dir.slice(1)) : dir;
 }
+/** 验证 Key 后建好库目录、写入配置，返回余额。 */
+async function writeConfig(file, key, library) {
+	if (!key) throw new CliError("缺少 --key");
+	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 credits;
+}
 /**
 * 未通过选项给出的值：终端里交互询问（直接回车沿用已有配置），非终端时沿用已有配置，
-* 都没有就报错。
+* 都没有就报错。未指定 --skill / --no-skill 时终端里询问是否安装 skill，非终端不安装；
+* 安装失败只警告，不影响已写入的配置。有询问时以 intro 开始，配置写入成败作为结尾。
 */
 async function initCommand(args) {
 	const file = configFile();
 	const existing = await readConfig(file);
 	const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	const asking = interactive && (!args.key || !args.library || args.skill === void 0);
 	let key = args.key ?? existing.KIE_API_KEY;
 	let library = args.library ?? existing.GENLAB_LIBRARY;
+	let skill = args.skill;
+	if (asking) p.intro("genlab init");
 	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）",
+		message: existing.KIE_API_KEY ? "请输入 Kie.ai API Key（留空沿用已保存的 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: "库目录",
+		message: "请输入库目录（存放所有项目与素材）：",
 		initialValue: existing.GENLAB_LIBRARY ?? DEFAULT_LIBRARY,
 		validate: (value) => value ? void 0 : "不能为空"
 	}));
-	if (!key) throw new CliError("缺少 --key");
+	if (interactive && skill === void 0) skill = answered(await p.confirm({ message: "是否为本机 agent 安装 GenLab skill？" }));
 	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 });
+	let credits;
+	try {
+		credits = await writeConfig(file, key, library);
+	} catch (error) {
+		if (asking) p.cancel("配置未写入");
+		throw error;
+	}
+	if (asking) p.outro("配置已写入");
+	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");
+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.ai 模型；指定模型时输出价格与参数表").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 {};

package/dist/guide.md

@@ -0,0 +1,49 @@
+# GenLab 使用说明
+
+用 Kie.ai 的模型生成图片、视频、音频，产物与完整生成记录保存在本机的库里。
+
+下文的 `genlab` 均可写作 `npx -y genlab@latest`（推荐，每次都用最新版本）。
+
+## 准备
+
+- 报错「缺少配置」时，请用户在终端运行 `genlab init`，填写 Kie.ai API Key 与库目录。
+- 库目录在代码项目之外。在沙箱里运行时，需要允许读写库目录与 `~/.cache/genlab`（模型目录缓存），并允许访问网络。
+
+## 概念
+
+- **项目**：库里最外层的分组。当前目录用 `genlab project link` 关联到一个项目后，素材命令都作用于它；`--project` 临时指定其他项目，不改关联。
+- **默认项目**：内置的 `default`，一直存在，放不属于任何代码项目的素材。
+- **素材**：项目里的一个创作单元，用「文件夹/素材名」指定，文件夹可省略（如 `characters/hero`、`logo`）。类型为 image / video / audio，由第一次生成的模型或导入的文件决定，之后的生成须用同类型的模型。
+- **版本**：素材的一个产物。版本号在素材内递增，删过的号不复用；状态为 generating / ready / failed。
+- **当前版本**：素材选定的那一版。新素材默认取版本号最小、没有失败的版本（还在生成中也等它）；用 `genlab use` 改选。
+- **AI 编辑**：以某个就绪版本为源版本、按要求修改，新版本仍属于同一素材。
+
+## 流程
+
+1. `genlab project` 查看当前目录关联的项目。没有关联时先关联：
+   - 属于某个代码项目：关联到对应的项目，库里还没有就先 `genlab project create`。
+   - 不属于任何代码项目（家目录、临时目录、下载目录等）：关联到 `default`。
+   - 判断不了：问用户。不要为了省事把属于某个项目的素材放进 `default`。
+   - 关联的项目不存在（可能已改名或删除）：问用户要关联到哪个，不要新建同名项目。
+2. `genlab list` 查看已有素材与文件夹，新素材沿用已有的文件夹分法。
+3. `genlab models --kind <类型> [--search <关键词>]` 找模型，`genlab models <模型>` 查看价格与参数表。参数名以参数表为准，不凭记忆填。文生与图生常是两个模型（`…-text-to-image` / `…-image-to-image`），按是否带输入图选择。
+4. 用户没指定模型时，为新素材的第一次生成挑 2–3 个候选（模型、价格、特点）请用户选；同一素材之后的生成默认沿用该模型（需要带输入图时换成同系列的图生模型），不再询问。
+5. `create` 新建素材，`generate` 在已有素材里生成，`edit` 做 AI 编辑，`retry` 重试失败的版本。命令默认最多等 90 秒；输出 `"pending": true` 时用 `genlab wait` 继续等。同时为多个素材发起生成时加 `--no-wait`，再用 `genlab wait` 一起等。
+6. 生成完向用户汇报使用的模型（版本的 `model`）、消耗的积分（各版本 `credits` 之和）与折合美元（Kie.ai 基础价 1 积分 = $0.005）。
+7. 每个版本的 `file` 是产物的绝对路径；一个任务可能产出多个版本（如一次出两首的音乐模型）。用户选定后用 `genlab use` 设为当前版本；需要放进代码项目时自行复制该文件。
+
+## 模型参数（-p）
+
+- `key=value`：字符串；数字、布尔、数组按参数表自动转换。
+- `key:=<JSON>`：JSON 值，如 `-p duration:=5`。
+- 同键重复即数组，如 `-p input_urls=@a.png -p input_urls=@b.png`。
+- `@<路径>`：本机文件（相对当前目录），自动上传；引用库里的产物时直接用它的 `file` 路径。
+- `@source`：AI 编辑的源版本文件，只能用在 `edit`。
+- `@@`：字面量 `@`。
+
+## 规则
+
+- 生成消耗 Kie.ai 积分：先看价格，任务数、分辨率、时长按需设置。
+- 不手动修改库里的 `asset.json`；改名、移动、删除整个素材由用户在文件管理器里操作。
+- 项目、文件夹、素材的名字用英文。
+- 结果为 JSON；错误写 stderr 的 `{"error": ...}`，警告为 `{"warning": ...}`。

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "genlab",
   "type": "module",
-  "version": "0.1.2",
-  "description": "给本地 agent 用的 AI 媒体生成命令行工具（kie.ai），产物与完整生成记录保存在本机",
+  "version": "0.1.4",
+  "description": "给本地 agent 用的 AI 媒体生成命令行工具（Kie.ai），产物与完整生成记录保存在本机",
   "author": "WBBB",
   "license": "MIT",
   "homepage": "https://github.com/WBBB0730/genlab#readme",
@@ -42,6 +42,7 @@
     "file-type": "^22.3.0",
     "image-size": "^2.0.4",
     "music-metadata": "^12.3.4",
+    "nano-spawn": "^2.1.0",
     "proper-lockfile": "^4.1.2",
     "write-file-atomic": "^7.0.1"
   },