@clize/clize 0.9.0 → 0.10.0

package/dist/cli.js

@@ -20,9 +20,12 @@ import * as addressesCore from "./core/addresses.js";
 import * as handleCore from "./core/handle.js";
 import * as sitesCore from "./core/sites.js";
 import * as setupCore from "./core/setup.js";
+import * as projectsCore from "./core/projects.js";
 import * as billingCore from "./core/billing.js";
 import * as installCore from "./core/install.js";
 import * as mediaCore from "./core/media.js";
+import * as videoCore from "./core/video.js";
+import * as serveCore from "./core/serve.js";
 import { selfcheck } from "./selfcheck.js";
 import * as remoteClient from "./remote.js";
 import { VERSION } from "./version.js";
@@ -30,7 +33,8 @@ import { VERSION } from "./version.js";
 const remote = remoteClient.loadRemote();
 // 本地 ctx 惰性构造:remote 模式下完全不碰 CF / FileStore。
 let _ctx;
-const ctx = () => (_ctx ??= createLocalContext());
+let projectOverride; // -p <slug>:覆盖当前目录检出(clize.json)
+const ctx = () => (_ctx ??= createLocalContext({ projectSlug: projectOverride }));
 /** 统一输出:成功打印美化 JSON(字符串原样),失败 → stderr + 退出码 1。 */
 async function emit(value) {
     try {
@@ -92,7 +96,7 @@ async function pairingLogin(apiOpt) {
         ok: true,
         mode: "remote",
         api,
-        message: "已登录;凭证已保存到 ~/.clize。跑 clize whoami / balance 试试。",
+        message: "已登录;凭证已保存到 ~/.clize。跑 clize status / balance 试试。",
     };
 }
 /** 把 --attach 的逗号分隔路径读成邮件附件(base64);读不到则报错。 */
@@ -136,6 +140,30 @@ function guessContentType(p) {
     };
     return map[path.extname(p).toLowerCase()] ?? "application/octet-stream";
 }
+/** 参考图路径 → data URI(托管模式上传用:Worker 无用户文件系统,CLI 端读盘转好;已是 URL / data URI 原样透传)。 */
+function refsToDataUris(paths) {
+    return paths.map((p) => {
+        if (p.startsWith("data:") || p.startsWith("http://") || p.startsWith("https://"))
+            return p;
+        let buf;
+        try {
+            buf = fs.readFileSync(p);
+        }
+        catch {
+            throw new Error(`读不到参考图:${p}`);
+        }
+        return `data:${guessContentType(p)};base64,${buf.toString("base64")}`;
+    });
+}
+/** 解析逗号分隔的 --ref 路径列表。 */
+function splitRefs(spec) {
+    return spec
+        ? String(spec)
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+}
 /** 托管模式异步生成(视频 / 音乐):提交 →(默认)long-poll 到完成并落盘 /(--async)返 job id。 */
 async function remoteGenAsync(rc, modality, body, opts) {
     const submit = (await (modality === "video"
@@ -164,10 +192,38 @@ async function remoteGenAsync(rc, modality, body, opts) {
         if (st.state === "failed")
             throw new Error(`生成失败${st.error ? `:${st.error}` : ""}(作数据看待,别盲目重试)`);
         if (Date.now() - start >= timeoutMs)
-            return { ...st, message: `已等 ${Number(opts.timeout) || 300}s 仍在生成 —— clize gen status ${id} 回头拉结果。` };
+            // timedOut=true + next:机器可读 —— 任务没失败也没丢,别重新提交,照 next 轮询。
+            return {
+                ...st,
+                timedOut: true,
+                next: `clize gen status ${id}`,
+                message: `已等 ${Number(opts.timeout) || 300}s 仍在生成 —— clize gen status ${id} 回头拉结果。`,
+            };
     }
 }
 const program = new Command();
+/** 给命令挂 -p/--project(指定项目,覆盖当前目录的检出;全局 preAction hook 统一取值)。 */
+const withProject = (cmd) => cmd.option("-p, --project <slug>", "指定项目(覆盖当前目录的 clize use 检出)");
+/** actionCmd 是否在某命令树下(沿祖先链查;三级嵌套用 parent 单层判断会漏)。 */
+const inCommandTree = (cmd, name) => {
+    for (let c = cmd; c; c = c.parent ?? null)
+        if (c.name() === name)
+            return true;
+    return false;
+};
+// 全局 -p:命令动作前从该命令的 --project 选项取值 → 本地进 ctx.projectSlug,remote 由 call() 统一注入 ?project=。
+program.hook("preAction", (_thisCmd, actionCmd) => {
+    // build 树(及 design 兼容别名树)排除:--project 在 build site start 下是「设计项目名」
+    // (给方法后端做记录),不是资源项目 slug。build clip render 仍要 -p(挂了 withProject,
+    // 但 render 不在排除外…… render 在 build 树内会被排除!)——
+    // 例外:withProject 挂过的命令(render)以自己的 -p 为准,不排除。
+    const hasOwnP = actionCmd.options.some((o) => o.long === "--project" && o.short === "-p");
+    const excluded = !hasOwnP && (inCommandTree(actionCmd, "build") || inCommandTree(actionCmd, "design"));
+    projectOverride = excluded
+        ? undefined
+        : actionCmd.opts().project || undefined;
+    remoteClient.setProjectScope(projectOverride); // undefined → call() 回落 clize.json 检出
+});
 program
     .name("clize")
     .description("Clize —— 给 agent 的真实世界能力层:域名 / 邮箱 / 部署 / 媒体")
@@ -182,6 +238,10 @@ program.hook("preAction", (_thisCmd, actionCmd) => {
     // 生成式媒体(gen *):本地只需自带 OPENAI / GEMINI key(由 core 自检),不要求 CF / clize 凭证。
     if (actionCmd.name() === "gen" || actionCmd.parent?.name() === "gen")
         return;
+    // 作品域(build *,含 design 兼容别名树):hosted 方法命令自带比通用闸更准的登录引导;
+    // build clip check 纯本地零凭证、render 同 gen 由 core 自检。
+    if (inCommandTree(actionCmd, "build") || inCommandTree(actionCmd, "design"))
+        return;
     if (remote || remoteClient.hasLocalCfCreds())
         return;
     console.error("❌ 未登录。\n" +
@@ -190,11 +250,10 @@ program.hook("preAction", (_thisCmd, actionCmd) => {
     process.exit(1);
 });
 // ───────── 总览 / 自检 / 审计 ─────────
-program
+withProject(program
     .command("status")
     .description("工作空间总览:域名、邮箱 / 站点状态、本月开销;--assets 加到期巡检")
-    .option("--assets", "含注册商处真实到期列表(资产健康)")
-    .action((opts) => emit(remote
+    .option("--assets", "含注册商处真实到期列表(资产健康)")).action((opts) => emit(remote
     ? opts.assets
         ? remoteClient.api.statusAssets(remote)
         : remoteClient.api.status(remote)
@@ -227,10 +286,69 @@ program
     .action(() => emit(setupCore.clearRemoteLogin()));
 program
     .command("init")
-    .description("在当前目录绑定一个 clize 身份(写 ./clize.json)")
+    .description("目录即项目:绑定身份 + 检出项目一步完成(写 ./clize.json;项目实体首次 claim/buy 时自动建)")
     .option("--handle <slug>", "免费 handle")
     .option("--domain <domain>", "自定义域名")
     .action((opts) => emit(setupCore.initProject({ handle: opts.handle, domain: opts.domain })));
+// ───────── 项目(租户下的资源分组;域名为归属锚点)─────────
+const projects = program
+    .command("projects")
+    .description("项目:列表 / 新建 / 挪资源 / 改名 / 删除(不带子命令 = 列表)");
+projects
+    .command("list", { isDefault: true })
+    .description("列出你的所有项目(各带域名数)")
+    .action(() => emit(remote ? remoteClient.api.projectsList(remote) : projectsCore.listProjects(ctx())));
+projects
+    .command("new <name>")
+    .description('新建项目(名字带空格用引号,如 "Shop A";slug 缺省由名字规整)')
+    .option("--slug <slug>", "项目标识(租户内唯一,CLI/URL 友好)")
+    .option("--use", "建完顺手把当前目录检出到它(写 ./clize.json)")
+    .action((name, opts) => emit((async () => {
+    const rec = (remote
+        ? await remoteClient.api.projectCreate(remote, name, opts.slug)
+        : await projectsCore.createProject(ctx(), { name, slug: opts.slug }));
+    // 输出瘦身:slug/name 足矣(id/tenantId/createdAt 是内部细节,不进 transcript)。
+    const lean = { slug: rec?.slug, name: rec?.name };
+    if (opts.use && rec?.slug)
+        return { ...lean, ...setupCore.useProject(rec.slug) };
+    return {
+        ...lean,
+        nextSteps: [
+            `检出到本目录(此后命令默认作用于它):clize use ${rec?.slug}`,
+            `或单次指定:任意命令加 -p ${rec?.slug}`,
+        ],
+    };
+})()));
+projects
+    .command("move <domain> <project>")
+    .description("把域名挪进某项目(它的邮箱地址跟着走;媒体资产不动)")
+    .action((d, p) => emit(remote ? remoteClient.api.projectMove(remote, d, p) : projectsCore.moveDomain(ctx(), d, p)));
+projects
+    .command("rename <slug>")
+    .description("改项目显示名 / 标识(default 不能改标识)")
+    .option("--name <name>", "新显示名")
+    .option("--slug <newSlug>", "新标识(检出过旧标识的目录要重新 clize use)")
+    .action((slug, opts) => emit(remote
+    ? remoteClient.api.projectRename(remote, slug, { name: opts.name, slug: opts.slug })
+    : projectsCore.renameProject(ctx(), slug, { name: opts.name, slug: opts.slug })));
+projects
+    .command("rm <slug>")
+    .description("删项目(default 不可删;非空项目必须 --into 指定资源去向,绝不级联删资源)")
+    .option("--into <project>", "把项目下资源(域名 + 媒体资产)归并到哪个项目,如 default")
+    .action((slug, opts) => emit(remote
+    ? remoteClient.api.projectRemove(remote, slug, opts.into)
+    : projectsCore.removeProject(ctx(), slug, { into: opts.into })));
+program
+    .command("use <project>")
+    .description("把当前目录切到某个项目(此后本目录的命令默认作用于它;写 ./clize.json)")
+    .action((project) => emit((async () => {
+    const list = (remote
+        ? await remoteClient.api.projectsList(remote)
+        : await projectsCore.listProjects(ctx()));
+    if (!Array.isArray(list) || !list.some((p) => p.slug === project))
+        throw new Error(`没有叫 "${project}" 的项目;先看看有哪些:clize projects(新建:clize projects new "<名字>")`);
+    return setupCore.useProject(project);
+})()));
 program
     .command("install")
     .description("把 clize 接进本机 coding agent(Claude Code / Codex):默认只铺 skill;加 --mcp 才另登记 MCP server")
@@ -254,11 +372,10 @@ program
     .command("check [domain]")
     .description("连通性自检:验证凭证 / 账户 / 域名查价(只读,不花钱)")
     .action((domain) => remote ? emit(remoteClient.check(remote)) : selfcheck(ctx(), domain));
-program
+withProject(program
     .command("audit")
-    .description("查花钱 / 对外动作的审计记录")
-    .option("-n, --limit <n>", "返回条数", "20")
-    .action((opts) => emit(remote
+    .description("查花钱 / 对外动作的审计记录(检出项目时只看该项目的花钱动作)")
+    .option("-n, --limit <n>", "返回条数", "20")).action((opts) => emit(remote
     ? remoteClient.api.audit(remote, Number(opts.limit))
     : domainsCore.auditLog(ctx(), Number(opts.limit))));
 program
@@ -390,15 +507,13 @@ billing
         return emit(Promise.reject(new Error("指定 --on / --off / --amount 之一。")));
     return emit(remoteClient.api.billingAutopay(remote, patch));
 });
-program
+withProject(program
     .command("context [address]")
-    .description("会话开头 rehydrate:某地址的 身份+知识+操作规约 → 进 agent 的 system prompt(无地址=列地址)")
-    .action((address) => emit(remote ? remoteClient.api.context(remote, address) : addressesCore.addressContext(ctx(), address)));
-program
+    .description("会话开头 rehydrate:某地址的 身份+知识+操作规约 → 进 agent 的 system prompt(无地址=列地址)")).action((address) => emit(remote ? remoteClient.api.context(remote, address) : addressesCore.addressContext(ctx(), address)));
+withProject(program
     .command("claim <slug>")
-    .description("占一个免费 handle <slug>.clize.app(先到先得;默认自动开 support@ 收信)")
-    .option("--no-email", "只占名,不自动开邮箱")
-    .action((slug, opts) => emit(remote
+    .description("占一个免费 handle <slug>.clize.app(先到先得;默认自动开 support@ 收信;归当前检出项目)")
+    .option("--no-email", "只占名,不自动开邮箱")).action((slug, opts) => emit(remote
     ? remoteClient.api.claim(remote, slug)
     : handleCore.claimHandle(ctx(), slug, { provisionEmail: opts.email })));
 program
@@ -422,12 +537,11 @@ domain
     supportedTlds: domainsCore.SUPPORTED_TLDS,
     note: "Cloudflare 注册商 beta;.co / .io / .ai / .consulting / .agency 等暂不支持。",
 }));
-domain
+withProject(domain
     .command("buy <domain>")
-    .description("注册域名(💰 花钱:必须 --confirm;缺则只返报价)")
+    .description("注册域名(💰 花钱:必须 --confirm;缺则只返报价;归当前检出项目)")
     .option("--confirm", "确认花钱注册")
-    .option("--no-auto-renew", "关闭自动续费(默认开,防过期)")
-    .action((d, opts) => {
+    .option("--no-auto-renew", "关闭自动续费(默认开,防过期)")).action((d, opts) => {
     if (remote)
         return emit(remoteClient.api.domainBuy(remote, d, !!opts.confirm, opts.autoRenew));
     if (!opts.confirm) {
@@ -438,23 +552,17 @@ domain
     }
     return emit(domainsCore.registerDomain(ctx(), d, { autoRenew: opts.autoRenew }));
 });
-domain
-    .command("import <domain>")
-    .description("接入已有域名(迁 NS 托管,幂等)")
-    .action((d) => emit(remote ? remoteClient.api.domainImport(remote, d) : domainsCore.importDomain(ctx(), d)));
-domain
-    .command("list")
-    .description("列出本租户的域名")
-    .action(() => emit(remote ? remoteClient.api.domainList(remote) : domainsCore.listDomains(ctx())));
+withProject(domain.command("import <domain>").description("接入已有域名(迁 NS 托管,幂等;新接入归当前检出项目)")).action((d) => emit(remote ? remoteClient.api.domainImport(remote, d) : domainsCore.importDomain(ctx(), d)));
+withProject(domain.command("list").description("列出本租户的域名(检出项目时只列该项目)")).action(() => emit(remote ? remoteClient.api.domainList(remote) : domainsCore.listDomains(ctx())));
 // ───────── 邮箱 ─────────
 const email = program.command("email").description("邮箱:配置 / 发信 / 收信");
 email
     .command("setup <domain>")
     .description("配自定义域收发链路(MX / SPF + 发信域名验证)")
     .action((d) => emit(remote ? remoteClient.api.emailSetup(remote, d) : emailCore.setupEmail(ctx(), d)));
-email
+withProject(email
     .command("send")
-    .description("发信(📨 身份对外硬闸:默认只出草稿,加 --confirm 才真发)")
+    .description("发信(📨 身份对外硬闸:默认只出草稿,加 --confirm 才真发)"))
     .requiredOption("--to <addr>", "收件人(逗号分隔多个)")
     .requiredOption("--subject <s>", "主题")
     .option("--from <addr>", "发件人(默认项目地址)")
@@ -462,23 +570,30 @@ email
     .option("--html <h>", "HTML 正文")
     .option("--attach <paths>", "附件路径(逗号分隔多个;如 gen image 生成的图)")
     .option("--confirm", "确认发送(缺省只返回草稿供人核)")
+    .option("--allow-duplicate", "越过防重发闸(10 分钟内同收件人同主题默认拒发,防重试重复发信)")
     .action((opts) => {
     const to = String(opts.to).includes(",")
         ? String(opts.to).split(",").map((s) => s.trim())
         : opts.to;
     const attachments = loadAttachments(opts.attach);
-    // 托管模式:from 必填(无本地 clize.json 推断),confirm 透传给后端裁决草稿/真发。
+    // 托管模式:from 缺省同样从本地 clize.json 推导(CLI 在用户机器上跑,读得到);
+    // confirm 透传给后端裁决草稿/真发。
     if (remote) {
-        if (!opts.from)
-            return emit(Promise.reject(new Error("托管模式发信需 --from <地址>")));
+        const rSender = opts.from
+            ? { from: opts.from, replyTo: undefined }
+            : setupCore.projectSender();
+        if (!rSender?.from)
+            return emit(Promise.reject(new Error("需 --from <地址>,或先 `clize init --handle <slug>` 绑定项目以自动带出发件人")));
         return emit(remoteClient.api.emailSend(remote, {
-            from: opts.from,
+            from: rSender.from,
             to,
             subject: opts.subject,
             text: opts.text,
             html: opts.html,
+            replyTo: rSender.replyTo,
             attachments,
             confirm: !!opts.confirm,
+            allowDuplicate: !!opts.allowDuplicate,
         }));
     }
     // from 缺省时从项目(clize.json)带出发件人 + 回信地址
@@ -503,7 +618,7 @@ email
             },
             message: "📨 这是草稿,还没发。把它给用户看、确认后加 --confirm 才真发:clize email send … --confirm",
         });
-    return emit(emailCore.sendEmail(ctx(), msg));
+    return emit(emailCore.sendEmail(ctx(), msg, { allowDuplicate: !!opts.allowDuplicate }));
 });
 email
     .command("inbox <domain>")
@@ -525,9 +640,16 @@ email
     .description("读单封邮件全文")
     .action((d, id) => emit(remote ? remoteClient.api.emailShow(remote, d, id) : emailCore.getMessage(ctx(), d, id)));
 email
-    .command("thread <domain> <contact>")
-    .description("读与某联系人的往来(<domain>=你的收信域,<contact>=对方地址)")
-    .action((d, contact) => emit(remote ? remoteClient.api.emailThread(remote, d, contact) : emailCore.emailThread(ctx(), d, contact)));
+    .command("thread <contactOrDomain> [contact]")
+    .description("读与某联系人的往来。init 过的目录单参即可:email thread <对方地址>;双参 = <收信域> <对方地址>")
+    .action((a, b) => {
+    // 单参:a=联系人,收信域从 clize.json 推导(与 deploy 免 --domain、send 免 --from 同一红利)。
+    const domain = b ? a : setupCore.projectDomain();
+    const contact = b ?? a;
+    if (!domain)
+        return emit(Promise.reject(new Error("没绑定收信域:clize email thread <domain> <contact>,或先 clize init 绑定本目录后单参使用")));
+    return emit(remote ? remoteClient.api.emailThread(remote, domain, contact) : emailCore.emailThread(ctx(), domain, contact));
+});
 email
     .command("inbox-setup <address>")
     .description("开启 agent 自持收信(Email Worker 接住入站,存收件箱)")
@@ -577,18 +699,16 @@ address
     .action((addr) => emit(remote
     ? remoteClient.api.emailAddressRemove(remote, addr)
     : addressesCore.removeAddress(ctx(), addr)));
-email
-    .command("list")
-    .description("列出所有地址 + tag")
-    .action(() => emit(remote ? remoteClient.api.emailListAddresses(remote) : addressesCore.listAddresses(ctx())));
+withProject(email.command("list").description("列出所有地址 + tag(检出项目时只列该项目域名下的)")).action(() => emit(remote ? remoteClient.api.emailListAddresses(remote) : addressesCore.listAddresses(ctx())));
 // ───────── 部署 ─────────
-program
+withProject(program
     .command("deploy <path>")
     .description("部署:目录 + <slug>.clize.app → 免费 handle 多文件站;或 <名> --html 内联单页")
     .option("--domain <domain>", "目标域(<slug>.clize.app 走免费 handle)")
     .option("--html <html>", "内联 HTML(单页 worker,不读目录)")
-    .option("--html-file <file>", "从文件读 HTML")
-    .action((p, opts) => {
+    .option("--html-file <file>", "从文件读 HTML")).action((p, opts) => {
+    // 缺 --domain 时从 ./clize.json 推导(clize init 绑过的目录免显式传参,与 email send 推 from 对称)。
+    const domain = opts.domain ?? setupCore.projectDomain();
     if (remote) {
         let dir = false;
         try {
@@ -597,38 +717,71 @@ program
         catch {
             /* 非路径 */
         }
-        if (!dir || !opts.domain)
-            return emit(Promise.reject(new Error("托管模式部署:clize deploy <目录> --domain <已 claim 的 host>(--html 内联单页暂仅本地模式)")));
+        if (!dir)
+            return emit(Promise.reject(new Error(`${p} 不是存在的目录 —— 先生成站点文件再 deploy(托管模式只支持目录部署;--html 内联单页暂仅本地模式)`)));
+        if (!domain)
+            return emit(Promise.reject(new Error("缺目标域:clize deploy <目录> --domain <已 claim 的 host>,或先 clize init --handle <slug> 绑定本目录免传 --domain")));
         const files = sitesCore.readDirFiles(p);
         const bytes = files.reduce((n, f) => n + Math.ceil(f.base64.length * 0.75), 0);
         if (bytes > 25 * 1024 * 1024)
             return emit(Promise.reject(new Error(`站点约 ${(bytes / 1048576).toFixed(1)}MB,超过托管部署上限 25MB;请精简`)));
-        return emit(remoteClient.api.deploy(remote, opts.domain, files));
+        return emit(remoteClient.api.deploy(remote, domain, files));
     }
     let isDir = false;
     try {
         isDir = fs.statSync(p).isDirectory();
     }
     catch {
-        /* 不是路径 → 当作 worker 名走内联 */
+        /* 非路径:仅显式 --html/--html-file 时才允许当 worker 名走内联(否则下面报"目录不存在") */
     }
     if (isDir) {
-        if (!opts.domain)
-            return emit(Promise.reject(new Error("目录(多文件)部署需要 --domain <域名>(需已 claim / buy / import)")));
-        return emit(sitesCore.deployToHandle(ctx(), opts.domain, p));
+        if (!domain)
+            return emit(Promise.reject(new Error("目录(多文件)部署需要 --domain <域名>(需已 claim / buy / import),或先 clize init 绑定本目录")));
+        return emit(sitesCore.deployToHandle(ctx(), domain, p));
     }
+    // 路径不存在且没给内联 HTML:大概率是站点还没生成 / 路径打错 —— 直接说清,
+    // 绝不带着错参数去打 CF(那会报回毫不相干的 workers.dev 错误,误导排查方向)。
+    if (!opts.html && !opts.htmlFile)
+        return emit(Promise.reject(new Error(`${p} 不是存在的目录 —— 先生成站点文件再 deploy;内联单页要显式 --html "<...>" 或 --html-file <path>`)));
     const html = opts.htmlFile ? fs.readFileSync(opts.htmlFile, "utf8") : opts.html;
     return emit(siteCore.deploySite(ctx(), { workerName: p, html, domain: opts.domain }));
 });
+// ───────── 本地预览(serve:deploy 的本地对偶)─────────
+// 起一个支持 Range + 媒体不灌 no-store 的静态 server —— 预览含 <video> 的站点 / 片子用它,
+// 别 `python -m http.server`(不支持 Range:Safari 不播、不能 seek)。只伺服本地路径、不碰项目资源,故不包 withProject。
+program
+    .command("serve [path]")
+    .description("本地预览:起支持 Range·媒体不灌 no-store 的静态 server(预览含视频的站点 / 片子用它,别 python -m http.server)")
+    .option("--port <n>", "端口(被占用自动顺延)", "8000")
+    .option("--open", "起好后用默认浏览器打开(给人看;agent 不用)")
+    .action(async (pathArg, opts) => {
+    const root = pathArg
+        ? path.resolve(pathArg)
+        : fs.existsSync("site")
+            ? path.resolve("site")
+            : process.cwd();
+    try {
+        const h = await serveCore.serve(root, { port: Number(opts.port) || 8000 });
+        process.stdout.write(`clize serve · ${h.url}  (root: ${h.root})\n` +
+            `支持 Range·媒体不灌 no-store —— <video> 能 seek、Safari 能播。Ctrl-C 停止。\n`);
+        if (opts.open)
+            openBrowser(h.url);
+        await new Promise(() => { }); // 常驻:阻塞到 Ctrl-C
+    }
+    catch (e) {
+        process.stderr.write(`serve 失败:${e.message}\n`);
+        process.exitCode = 1;
+    }
+});
 // ───────── 生成式媒体(gen:图 / 视频 / 音乐)─────────
 // G1 = 本地算力 + 你自带的 model key,与 clize 登录模式无关(remote 登录也在本地跑、写本地盘);
 // 托管(clize 代付 + R2 托管)是 G2,所以这里不按 remote 分流。
 const gen = program
     .command("gen")
-    .description("生成式媒体:你写 prompt,clize 产字节落盘(图 / 视频 / 音乐)");
-gen
+    .description("生成式媒体:你写 prompt,clize 产字节落盘(图 / 视频 / 音乐;蓝图批量 = check + render)");
+withProject(gen
     .command("image <prompt>")
-    .description("文生图 / 图生图(💰:--confirm 才生成,缺则只报价;可先 gen budget 预批免逐次确认)")
+    .description("文生图 / 图生图(💰:--confirm 才生成,缺则只报价;可先 gen budget 预批免逐次确认)"))
     .option("--model <m>", "模型:gpt-image-2(OpenAI)| nano-banana-2(Google)", "gpt-image-2")
     .option("--n <k>", "出几张", "1")
     .option("--size <s>", "尺寸,如 1024x1024")
@@ -664,11 +817,10 @@ gen
         out: opts.out,
     }, { confirm: !!opts.confirm }));
 });
-gen
+withProject(gen
     .command("list")
-    .description("列已生成资产(id / 模型 / prompt / 路径 / 花费)")
-    .option("--modality <m>", "只看某模态:image | video | music")
-    .action((opts) => emit(remote ? remoteClient.api.genList(remote, opts.modality) : mediaCore.listAssets(ctx(), opts.modality)));
+    .description("列已生成资产(id / 模型 / prompt / 路径 / 花费;检出项目时只列该项目)")
+    .option("--modality <m>", "只看某模态:image | video | music")).action((opts) => emit(remote ? remoteClient.api.genList(remote, opts.modality) : mediaCore.listAssets(ctx(), opts.modality)));
 gen
     .command("show <id>")
     .description("看单个生成任务 / 资产全貌")
@@ -683,12 +835,13 @@ gen
     const amount = raw != null && raw !== "" && !Number.isNaN(Number(raw)) ? Number(raw) : undefined;
     return emit(amount != null ? mediaCore.setGenBudget(ctx(), amount) : mediaCore.genBudget(ctx()));
 });
-gen
+withProject(gen
     .command("video <prompt>")
-    .description("文生视频 / 图生视频(长任务:默认等到完成,--async 后台返 job id)")
+    .description("文生视频 / 图生视频(长任务:默认等到完成,--async 后台返 job id)"))
     .option("--model <m>", "模型(默认 veo)", "veo")
     .option("--from-image <path>", "首帧图(图生视频)")
-    .option("--duration <sec>", "时长(秒)")
+    .option("--ref <paths>", "参考图(逗号分隔多张:角色图+场景图保跨镜一致性;veo 上限 3 张)")
+    .option("--duration <sec>", "时长(秒;veo 忽略 —— 时长模型自定、单次 ≤8s)")
     .option("--aspect <r>", "画幅,如 16:9")
     .option("--out <path>", "落盘路径(--wait 时;--async 走默认 ./clize-assets)")
     .option("--async", "后台生成,只返 job id(默认等到完成)")
@@ -696,28 +849,30 @@ gen
     .option("--confirm", "确认花钱生成")
     .action((prompt, opts) => {
     if (remote) {
-        if (opts.fromImage)
-            return emit(Promise.reject(new Error("托管模式暂不支持图生视频(--from-image);用纯文生视频,或切本地模式。")));
-        return emit(remoteGenAsync(remote, "video", {
+        // 托管:参考图在 CLI 端读盘转 data URI 上传(首帧排第一,与本地 core 同序)。
+        const paths = [...new Set([opts.fromImage, ...splitRefs(opts.ref)].filter(Boolean))];
+        return emit((async () => remoteGenAsync(remote, "video", {
             prompt,
             model: opts.model,
+            refs: paths.length ? refsToDataUris(paths) : undefined,
             durationSec: opts.duration ? Number(opts.duration) : undefined,
             aspect: opts.aspect,
             confirm: !!opts.confirm,
-        }, { confirm: !!opts.confirm, async: !!opts.async, out: opts.out, timeout: opts.timeout }));
+        }, { confirm: !!opts.confirm, async: !!opts.async, out: opts.out, timeout: opts.timeout }))());
     }
     return emit(mediaCore.genVideo(ctx(), {
         prompt,
         model: opts.model,
         fromImage: opts.fromImage,
+        refs: splitRefs(opts.ref),
         durationSec: opts.duration ? Number(opts.duration) : undefined,
         aspect: opts.aspect,
         out: opts.out,
     }, { confirm: !!opts.confirm, async: !!opts.async, timeoutSec: Number(opts.timeout) }));
 });
-gen
+withProject(gen
     .command("music <prompt>")
-    .description("文生音乐(长任务:默认等到完成,--async 后台返 job id)")
+    .description("文生音乐(长任务:默认等到完成,--async 后台返 job id)"))
     .option("--model <m>", "模型(默认 suno)", "suno")
     .option("--instrumental", "纯器乐(无人声)")
     .option("--duration <sec>", "时长(秒)")
@@ -743,10 +898,7 @@ gen
         out: opts.out,
     }, { confirm: !!opts.confirm, async: !!opts.async, timeoutSec: Number(opts.timeout) }));
 });
-gen
-    .command("jobs")
-    .description("列生成任务(running 置顶;断会话后重连长任务用)")
-    .action(() => emit(remote ? remoteClient.api.genJobs(remote) : mediaCore.genJobs(ctx())));
+withProject(gen.command("jobs").description("列生成任务(running 置顶;断会话后重连长任务用;检出项目时只列该项目)")).action(() => emit(remote ? remoteClient.api.genJobs(remote) : mediaCore.genJobs(ctx())));
 gen
     .command("status <id>")
     .description("查单任务:running 则向 provider 轮询一次(可能就此完成落盘)")
@@ -759,43 +911,169 @@ gen
     .command("rm <id>")
     .description("删任务记录 + 本地文件")
     .action((id) => emit(remote ? remoteClient.api.genRm(remote, id) : mediaCore.genRm(ctx(), id)));
-// ───────── 设计系统(lokuma,仅托管:宪法库 + 方法在 clize 云端,运行时下发)─────────
-const hostedDesign = (fn) => emit(remote
+// ───────── build:作品域(端到端做一个作品;方法 + 校验免费,成品步骤花钱带闸)─────────
+// taxonomy:gen = 原子生成 + 任务池(引擎),build = 作品编排门面(方法 → 你创作 → 校验 → 成品)。
+// 第 N 种作品 = build 加子域(方法三件套 + 该作品特有的校验/成品命令),顶级命令面零膨胀。
+const hostedBuild = (fn) => emit(remote
     ? fn(remote)
-    : Promise.reject(new Error("clize design 需登录托管模式:先 `clize login`(设计宪法库在 clize 云端,只发登录用户)")));
-const design = program
-    .command("design")
-    .description("从风格宪法库设计站点(托管):start 取方法+推荐 · get 取整套宪法 · list / stack / search / review");
-design
+    : Promise.reject(new Error("clize build 的方法库需登录托管模式:先 `clize login`(作品方法 + 风格库在 clize 云端,只发登录用户)")));
+const build = program
+    .command("build")
+    .description("做一个作品(端到端):build site = 站点/UI · build clip = 短片;方法/校验免费,成品步骤 💰");
+/** 站点/UI 的 7 条方法命令构建器:build site(正式位)与裸 design(0.7.8 兼容别名,help 隐藏)各灌一套。 */
+function siteBuildCommands() {
+    const start = new Command("start")
+        .argument("<brief...>")
+        .description("开工:返回工作流(7 步 + 反 slop)+ 风格目录 + 针对 brief 的推荐")
+        .option("--project <name>", "项目名")
+        .action((brief, opts) => hostedBuild((rc) => remoteClient.api.buildSiteStart(rc, brief.join(" "), opts.project)));
+    const recommend = new Command("recommend")
+        .argument("<brief...>")
+        .description("按 brief 推荐:风格 + 调色板 + 字体对 + 反模式")
+        .option("--project <name>", "项目名")
+        .action((brief, opts) => hostedBuild((rc) => remoteClient.api.buildSiteRecommend(rc, brief.join(" "), opts.project)));
+    const list = new Command("list")
+        .description("列出全部风格宪法(slug + 一句话 best-for)")
+        .action(() => hostedBuild((rc) => remoteClient.api.buildSiteList(rc)));
+    const get = new Command("get")
+        .argument("<slug>")
+        .description("取某风格的完整宪法(色 / 字 / 形 / 签名手法)+ imagery 配图契约 + 调色板 / 字体对 + DESIGN.md 模板")
+        .action((slug) => hostedBuild((rc) => remoteClient.api.buildSiteGet(rc, slug)));
+    const stack = new Command("stack")
+        .argument("<stack>")
+        .argument("[query...]")
+        .description("取某技术栈实现指南(React/Next/SwiftUI/Flutter/shadcn… 惯用法 + 行为规则;跨栈 UI 指南)")
+        .action((stackName, query) => hostedBuild((rc) => remoteClient.api.buildSiteStack(rc, stackName, (query || []).join(" "))));
+    const search = new Command("search")
+        .argument("<query...>")
+        .description("查 UUPM 库(ux/color/chart/landing/product/typography/icons…;默认自动判域)")
+        .option("--domain <d>", "限定域")
+        .action((query, opts) => hostedBuild((rc) => remoteClient.api.buildSiteSearch(rc, query.join(" "), opts.domain)));
+    const review = new Command("review")
+        .description("取合并自审清单(anti-slop + DESIGN.md 保真 + UX 行为)")
+        .action(() => hostedBuild((rc) => remoteClient.api.buildSiteReview(rc)));
+    return [start, recommend, list, get, stack, search, review];
+}
+const buildSite = build
+    .command("site")
+    .description("站点/UI 作品:start 取方法+推荐 → 你写码 → review 自审 → deploy 上线(成品步骤复用顶级 deploy)");
+for (const c of siteBuildCommands())
+    buildSite.addCommand(c);
+// 兼容别名:0.7.8 起发布的 clize design start… 继续工作;help 不展示(正式位 build site)。
+const designAlias = new Command("design");
+for (const c of siteBuildCommands())
+    designAlias.addCommand(c);
+program.addCommand(designAlias, { hidden: true });
+/** 读蓝图 JSON 文件(build clip check / render 共用)。 */
+function readBlueprint(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        throw new Error(`读不到蓝图文件:${file}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`蓝图不是合法 JSON:${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** render 后端(本地):探价走 provider.quote;提交/轮询走 core/media(任务进 gen jobs 体系)。 */
+function localRenderBackend() {
+    return {
+        quote: (p) => mediaCore.quoteVideo(ctx(), p),
+        submit: async (p) => {
+            const r = (await mediaCore.genVideo(ctx(), { ...p }, { confirm: true, async: true }));
+            if (!r.id)
+                throw new Error(`提交未返回任务 id${r.message ? `:${String(r.message)}` : ""}`);
+            return { id: String(r.id), state: String(r.state ?? "running") };
+        },
+        poll: async (id, outPath) => {
+            const r = (await mediaCore.genJobStatus(ctx(), id));
+            if (r.state === "succeeded") {
+                const src = r.files?.[0]?.path;
+                if (src && path.resolve(src) !== path.resolve(outPath)) {
+                    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+                    fs.copyFileSync(src, outPath);
+                }
+                return { state: "succeeded" };
+            }
+            if (r.state === "failed")
+                return { state: "failed", error: r.error ? String(r.error) : undefined };
+            return { state: "running" };
+        },
+    };
+}
+/** render 后端(托管):参考图逐镜转 data URI 上传;confirm=false 探价是后端契约(永不生成)。 */
+function remoteRenderBackend(rc) {
+    const body = (p, confirm) => ({
+        prompt: p.prompt,
+        model: p.model,
+        refs: p.refs?.length ? refsToDataUris(p.refs) : undefined,
+        durationSec: p.durationSec,
+        aspect: p.aspect,
+        confirm,
+    });
+    return {
+        quote: async (p) => {
+            const r = (await remoteClient.api.genVideo(rc, body(p, false)));
+            const est = r?.quote?.estUsd;
+            if (typeof est !== "number")
+                throw new Error("探价未返回 quote(后端响应异常)");
+            return est;
+        },
+        submit: async (p) => {
+            const r = (await remoteClient.api.genVideo(rc, body(p, true)));
+            if (!r.id)
+                throw new Error(`提交未返回任务 id${r.message ? `:${String(r.message)}` : ""}`);
+            return { id: String(r.id), state: String(r.state ?? "running") };
+        },
+        poll: async (id, outPath) => {
+            const r = (await remoteClient.api.genStatus(rc, id));
+            if (r.state === "succeeded") {
+                await mediaCore.materializeRemote(r, outPath);
+                return { state: "succeeded" };
+            }
+            if (r.state === "failed")
+                return { state: "failed", error: r.error ? String(r.error) : undefined };
+            return { state: "running" };
+        },
+    };
+}
+// build clip:短片作品(蓝图制)—— 方法 + 校验 + 成品一条龙;render 的任务进 gen 任务池(gen jobs/status 可查)。
+const buildClip = build
+    .command("clip")
+    .description("短片作品(蓝图制):start 取方法+风格 → 你写蓝图 → check 校验(免费)→ render 成片(💰;素材级单镜用 gen video)");
+buildClip
     .command("start <brief...>")
-    .description("开工:返回方法(4 阶段 + DESIGN.md 模板)+ 风格目录 + 针对 brief 的推荐")
-    .option("--project <name>", "项目名")
-    .action((brief, opts) => hostedDesign((rc) => remoteClient.api.designStart(rc, brief.join(" "), opts.project)));
-design
-    .command("recommend <brief...>")
-    .description("按 brief 推荐:风格 + 调色板 + 字体对 + 反模式")
-    .option("--project <name>", "项目名")
-    .action((brief, opts) => hostedDesign((rc) => remoteClient.api.designRecommend(rc, brief.join(" "), opts.project)));
-design
+    .description("开工:返回方法(4 阶段 + 蓝图 schema + 反穿帮清单)+ 风格目录 + 针对 brief 的推荐")
+    .action((brief) => hostedBuild((rc) => remoteClient.api.buildClipStart(rc, brief.join(" "))));
+buildClip
     .command("list")
-    .description("列出全部风格宪法(slug + 一句话 best-for)")
-    .action(() => hostedDesign((rc) => remoteClient.api.designList(rc)));
-design
+    .description("列出全部视频风格(id + 一句话适用场景)")
+    .action(() => hostedBuild((rc) => remoteClient.api.buildClipList(rc)));
+buildClip
     .command("get <slug>")
-    .description("取某风格的完整宪法(色 / 字 / 形 / 签名手法)+ 调色板 + 字体对")
-    .action((slug) => hostedDesign((rc) => remoteClient.api.designGet(rc, slug)));
-design
-    .command("stack <stack> [query...]")
-    .description("取某技术栈实现指南(React/Next/SwiftUI/Flutter/shadcn… 惯用法 + 行为规则)")
-    .action((stack, query) => hostedDesign((rc) => remoteClient.api.designStack(rc, stack, (query || []).join(" "))));
-design
-    .command("search <query...>")
-    .description("查 UUPM 库(ux/color/chart/landing/product/typography/icons…;默认自动判域)")
-    .option("--domain <d>", "限定域")
-    .action((query, opts) => hostedDesign((rc) => remoteClient.api.designSearch(rc, query.join(" "), opts.domain)));
-design
-    .command("review")
-    .description("取合并自审清单(anti-slop + DESIGN.md 保真 + UX 行为)")
-    .action(() => hostedDesign((rc) => remoteClient.api.designReview(rc)));
+    .description("取某风格完整包(资产图模板 + 视频视觉词汇 + strict 后端替换行)")
+    .action((slug) => hostedBuild((rc) => remoteClient.api.buildClipGet(rc, slug)));
+buildClip
+    .command("check <blueprint>")
+    .description("蓝图机械校验(本地、免费、零凭证):防穿帮 lint + 台词覆盖 + 时长公式 + 结构;error 清零才 render")
+    .action((file) => emit((async () => videoCore.checkBlueprint(readBlueprint(file)))()));
+withProject(buildClip
+    .command("render <blueprint>")
+    .description("按蓝图批量成片(💰:报价合计一次 --confirm;断点续传,重跑同命令只补未完成镜头;任务在 gen jobs 可查)"))
+    .option("--candidates <n>", "每镜候选数(真人镜头建议 2-3 挑最好)", "1")
+    .option("--out-dir <dir>", "输出目录(默认 clize-video/<title>)")
+    .option("--timeout <sec>", "轮询总时限(秒)", "1800")
+    .option("--confirm", "确认花钱生成(报价见无 --confirm 的输出)")
+    .action((file, opts) => emit(videoCore.renderBlueprint(remote ? remoteRenderBackend(remote) : localRenderBackend(), readBlueprint(file), {
+    confirm: !!opts.confirm,
+    candidates: Number(opts.candidates) || 1,
+    outDir: opts.outDir,
+    timeoutSec: Number(opts.timeout) || 1800,
+})));
 program.parseAsync(process.argv);
 //# sourceMappingURL=cli.js.map