@remixmate/cli 0.9.66 → 0.9.67

package/dist/cli.js

@@ -16,7 +16,7 @@ import { parseArgv } from './argv.js';
 import { runSkill } from './runner.js';
 import { runAuthCommand } from './auth/commands.js';
 import { HOST_VERB, PROJECT_VERB, runHostCommand, runProjectCommand } from './project/commands.js';
-import { INSTALL_VERB, UNINSTALL_VERB, runInstall, runUninstall } from './install.js';
+import { INSTALL_VERB, UNINSTALL_VERB, runInstall, runUninstall, skillInstallHint } from './install.js';
 import { runExec } from './exec.js';
 import { authStatusLine, runDoctor } from './doctor.js';
 import { padDisplay } from './text.js';
@@ -71,6 +71,7 @@ function printUsage() {
     process.stdout.write('  remixmate template preview <name>     Render a draft preview mp4 remotely\n');
     process.stdout.write('  remixmate template publish <name>     Publish as your private template\n');
     process.stdout.write('  remixmate template list               List your private templates\n');
+    process.stdout.write('  remixmate template upgrade            Update the project\'s local check rules (no login)\n');
     process.stdout.write('  remixmate <name> [--flag value ...]   Invoke a skill\n');
     process.stdout.write('  remixmate <name> --help               Show skill-specific help\n');
     process.stdout.write('\nAvailable skills:\n');
@@ -119,6 +120,11 @@ function printList(json) {
 async function printAuthFooter() {
     try {
         process.stderr.write(`\n${await authStatusLine()}\n`);
+        // `npm i -g` 之后第一条命令通常就是 --help / --list：这里提醒一次「还没 remixmate install」，
+        // 代替会被 npm 吞掉输出、且侵入家目录的 postinstall。
+        const hint = skillInstallHint();
+        if (hint)
+            process.stderr.write(`${hint}\n`);
     }
     catch {
         // A diagnostic footer must never be the reason a listing command fails.

package/dist/doctor.js

@@ -20,7 +20,7 @@ import { listCredentials } from './auth/credential-store.js';
 import { resolveTakeKey } from './project/host.js';
 import { readBinding } from './project/store.js';
 import { canAutoAuth, isHeadless } from './auth/environment.js';
-import { installStates } from './install.js';
+import { installStates, skillInstallHint } from './install.js';
 import { padDisplay } from './text.js';
 /**
  * Short auth status suitable for a footer. Never performs network I/O — a
@@ -104,7 +104,8 @@ export async function runDoctor(opts = {}) {
     // 宿主安装状态。这套方案唯一的静默失败模式是漂移：`npm update -g` 只动包，不动
     // 已经铺进 ~/.claude/skills、~/.codex/skills 的副本,用户会拿着旧 SKILL.md 打新
     // 后端,而且第一个症状往往是某个参数「莫名其妙不认」。
-    for (const s of installStates()) {
+    const hostStates = installStates();
+    for (const s of hostStates) {
         checks.push({
             // 只取宿主名的第一段（Claude Code → Claude）——检查名要留在 padDisplay 的
             // 对齐宽度内，宿主目录已经写在 detail 里，不会有歧义。
@@ -170,6 +171,11 @@ export async function runDoctor(opts = {}) {
         // detail 列顶出去，报告看起来像是漏了对齐。
         process.stdout.write(`${ICON[c.status]} ${padDisplay(c.name, 16)}${c.detail}\n`);
     }
+    // 宿主未装 skill 只算 warn（不影响退出码），但它是「agent 说不知道 RemixMate」的头号原因，
+    // 单独在报告末尾点名，避免淹没在一屏 ✅ 里。
+    const installHint = skillInstallHint(hostStates);
+    if (installHint)
+        process.stdout.write(`\n${installHint}\n`);
     const failed = checks.filter((c) => c.status === 'fail');
     if (failed.length === 0) {
         process.stdout.write('\n一切正常。\n');

package/dist/install.d.ts

@@ -59,4 +59,13 @@ export interface InstallState {
  * 用户会拿着旧 SKILL.md 打新后端。doctor 是「为什么跑不起来」的统一入口，检查放这里。
  */
 export declare function installStates(): InstallState[];
+/**
+ * 首次使用提示：检测到了宿主、但还没跑过 `remixmate install`（或装的是旧版）时返回一行提示，
+ * 否则 null。
+ *
+ * 不用 postinstall 做这件事：npm 7+ 默认吞掉生命周期脚本的输出，而在安装期往用户家目录
+ * 写文件太侵入。改为在用户/agent 一定会看到的地方（--list、--help 页脚、template init 的
+ * 下一步、doctor）提示。纯本地读文件，不发网络请求。
+ */
+export declare function skillInstallHint(states?: InstallState[]): string | null;
 export {};

package/dist/install.js

@@ -427,3 +427,22 @@ export function installStates() {
         };
     });
 }
+/**
+ * 首次使用提示：检测到了宿主、但还没跑过 `remixmate install`（或装的是旧版）时返回一行提示，
+ * 否则 null。
+ *
+ * 不用 postinstall 做这件事：npm 7+ 默认吞掉生命周期脚本的输出，而在安装期往用户家目录
+ * 写文件太侵入。改为在用户/agent 一定会看到的地方（--list、--help 页脚、template init 的
+ * 下一步、doctor）提示。纯本地读文件，不发网络请求。
+ */
+export function skillInstallHint(states = installStates()) {
+    const missing = states.filter((s) => s.installedVersion == null).map((s) => s.label);
+    const drifted = states.filter((s) => s.drifted).map((s) => s.label);
+    if (missing.length > 0) {
+        return `💡 检测到 ${missing.join('、')}，但还没装 skill → 运行 remixmate install，重启 agent 后它才能自动发现 RemixMate 的能力`;
+    }
+    if (drifted.length > 0) {
+        return `💡 ${drifted.join('、')} 里的 skill 是旧版本 → 运行 remixmate install 覆盖`;
+    }
+    return null;
+}

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.66",
-  "generatedAt": "2026-10-05T07:09:29.057Z",
+  "version": "0.9.67",
+  "generatedAt": "2026-10-05T10:57:59.113Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -940,10 +940,12 @@
       "title": "Video Template Authoring",
       "summary": "Start authoring a custom video template locally: scaffolds a starter project (Remotion Studio preview, local validation, remote draft preview, publishing as the user's private template) into the given directory. After this, follow the project's AGENTS.md and use `remixmate template check|preview|publish`. Local-only; requires Node >= 18 and npm.",
       "triggers": [
-        "做视频模板",
-        "自定义视频模板",
-        "创建模板 / 新建模板 / 自己写一个视频模板",
-        "预览或发布我本地开发的模板",
+        "做视频模板 / 做视频模版",
+        "自定义视频模板 / 自定义视频模版",
+        "创建模板 / 新建模板 / 创建模版 / 新建模版",
+        "我想创建一个新的视频模版 / 创建一个视频模板",
+        "自己写一个视频模板 / 自己做一个模版",
+        "预览或发布我本地开发的模板 / 模版",
         "template authoring",
         "create video template / build a custom video template",
         "publish my own Remotion template"

package/dist/template/check.js

@@ -8,11 +8,16 @@
  */
 import path from 'node:path';
 import { CHECK_ENTRY } from './constants.js';
-import { requireProjectRoot } from './project.js';
+import { requireProjectRoot, staleRulesHint } from './project.js';
 import { runProcess } from './proc.js';
 /** Run the starter's check script; resolves to its exit code (0 ok / 1 issues / 2 usage). */
 export async function runCheck(opts = {}) {
     const root = requireProjectRoot(opts.cwd);
+    // 规则比 cli 对应的 starter 旧：提示 upgrade（stderr，不影响 --json 的最后一行）。
+    // 只提示不阻断 —— 服务端渲染前还会再扫一遍，旧规则最多让问题晚一点暴露。
+    const hint = staleRulesHint(root);
+    if (hint)
+        process.stderr.write(hint + '\n');
     const args = [path.join(root, CHECK_ENTRY)];
     if (opts.name)
         args.push(opts.name);

package/dist/template/commands.d.ts

@@ -8,7 +8,7 @@
  */
 import { type FlagSpec, type ParsedTemplateArgs } from './args.js';
 export declare const TEMPLATE_VERB = "template";
-export declare const TEMPLATE_SUBCOMMANDS: readonly ["init", "check", "preview", "publish", "list"];
+export declare const TEMPLATE_SUBCOMMANDS: readonly ["init", "check", "preview", "publish", "list", "upgrade"];
 export type TemplateSubcommand = (typeof TEMPLATE_SUBCOMMANDS)[number];
 interface SubSpec {
     flags: FlagSpec;

package/dist/template/commands.js

@@ -10,13 +10,14 @@ import { cleanDiagnosticText } from '../diagnostics.js';
 import { EXIT, SkillError } from '../errors.js';
 import { flagNumber, flagString, parseTemplateArgs, usageError } from './args.js';
 import { runCheck } from './check.js';
+import { runUpgrade } from './upgrade.js';
 import { STARTER_PACKAGE, STARTER_VERSION } from './constants.js';
 import { runInit } from './init.js';
 import { runList } from './list.js';
 import { runPreview } from './preview.js';
 import { runPublish } from './publish.js';
 export const TEMPLATE_VERB = 'template';
-export const TEMPLATE_SUBCOMMANDS = ['init', 'check', 'preview', 'publish', 'list'];
+export const TEMPLATE_SUBCOMMANDS = ['init', 'check', 'preview', 'publish', 'list', 'upgrade'];
 export const SUB_SPECS = {
     init: {
         flags: { force: 'bool', 'skip-install': 'bool' },
@@ -52,6 +53,13 @@ export const SUB_SPECS = {
         maxPositionals: 0,
         usage: 'remixmate template list [--json]\n  列出你发布的私有模板（需登录）。\n',
     },
+    upgrade: {
+        flags: { 'dry-run': 'bool', 'with-docs': 'bool', force: 'bool' },
+        maxPositionals: 0,
+        usage: 'remixmate template upgrade [--dry-run] [--with-docs] [--force] [--json]\n' +
+            `  把工程的本地校验规则（.remixmate/）更新到 ${STARTER_PACKAGE}@${STARTER_VERSION}（无需登录）。\n` +
+            '  不改动 templates/、src/、examples/、package.json；--with-docs 同时刷新 AGENTS.md / CLAUDE.md（旧文件存为 *.orig）。\n',
+    },
 };
 export function templateUsage() {
     return ('Usage: remixmate template <command> [options]\n\n' +
@@ -60,7 +68,8 @@ export function templateUsage() {
         '  check [name]       本地校验（无需登录）\n' +
         '  preview <name>     远程渲染预览 mp4\n' +
         '  publish <name>     发布为私有模板\n' +
-        '  list               列出我的私有模板\n\n' +
+        '  list               列出我的私有模板\n' +
+        '  upgrade            更新工程的本地校验规则（无需登录）\n\n' +
         'Common options: --json  --token <PrivToken>  --api-base-url <url>\n' +
         '环境变量：AB_RENDER_URL（渲染服务地址）、REMIXMATE_STARTER_TARBALL（init 使用本地 starter 包）\n' +
         '运行 remixmate template <command> --help 查看子命令说明。\n');
@@ -114,6 +123,14 @@ async function dispatch(sub, args) {
         case 'list':
             await runList({ json, token, apiBaseUrl });
             return EXIT.OK;
+        case 'upgrade':
+            await runUpgrade({
+                dryRun: flags['dry-run'] === true,
+                withDocs: flags['with-docs'] === true,
+                force: flags.force === true,
+                json,
+            });
+            return EXIT.OK;
     }
 }
 export async function runTemplateCommand(argv) {

package/dist/template/constants.d.ts

@@ -6,7 +6,21 @@
  * the same project on every machine for a given cli version.
  */
 export declare const STARTER_PACKAGE = "@remixmate/template-starter";
-export declare const STARTER_VERSION = "0.1.0";
+/**
+ * 一个 starter 版本 = 一套本地校验规则版本（.remixmate/）。规则更新的发布顺序：
+ * template-library `pnpm publish:sdk --publish` 发新 starter → 改这里 → cli 发版。
+ * publish:sdk 会比对这个常量，对不上就拒发。
+ */
+export declare const STARTER_VERSION = "0.2.0";
+/**
+ * 工程里记录规则版本的文件（starter ≥0.2.0 构建时写入；`template upgrade` 也会写）。
+ * 0.1.0 工程没有它，回落读 package.json 的 version（init 时整份复制自 starter）。
+ */
+export declare const RULES_VERSION_FILE = ".remixmate/version.json";
+/** `template upgrade` 只替换这个目录；用户的 templates/、src/ 等一律不动。 */
+export declare const RULES_DIR = ".remixmate";
+/** `template upgrade --with-docs` 额外刷新的 agent 指南（旧文件备份为 *.orig）。 */
+export declare const DOC_FILES: readonly string[];
 /** Local tarball override (testing a starter before it is published). */
 export declare const STARTER_TARBALL_ENV = "REMIXMATE_STARTER_TARBALL";
 /** Marker file that identifies a starter project root (K3). */

package/dist/template/constants.js

@@ -6,7 +6,21 @@
  * the same project on every machine for a given cli version.
  */
 export const STARTER_PACKAGE = '@remixmate/template-starter';
-export const STARTER_VERSION = '0.1.0';
+/**
+ * 一个 starter 版本 = 一套本地校验规则版本（.remixmate/）。规则更新的发布顺序：
+ * template-library `pnpm publish:sdk --publish` 发新 starter → 改这里 → cli 发版。
+ * publish:sdk 会比对这个常量，对不上就拒发。
+ */
+export const STARTER_VERSION = '0.2.0';
+/**
+ * 工程里记录规则版本的文件（starter ≥0.2.0 构建时写入；`template upgrade` 也会写）。
+ * 0.1.0 工程没有它，回落读 package.json 的 version（init 时整份复制自 starter）。
+ */
+export const RULES_VERSION_FILE = '.remixmate/version.json';
+/** `template upgrade` 只替换这个目录；用户的 templates/、src/ 等一律不动。 */
+export const RULES_DIR = '.remixmate';
+/** `template upgrade --with-docs` 额外刷新的 agent 指南（旧文件备份为 *.orig）。 */
+export const DOC_FILES = ['AGENTS.md', 'CLAUDE.md'];
 /** Local tarball override (testing a starter before it is published). */
 export const STARTER_TARBALL_ENV = 'REMIXMATE_STARTER_TARBALL';
 /** Marker file that identifies a starter project root (K3). */

package/dist/template/init.d.ts

@@ -6,6 +6,7 @@
  * with the system `tar` (bsdtar ships with Windows 10+), then `npm install`ed.
  * No login is needed (requirement 3.5).
  */
+import { Output } from './project.js';
 export interface InitOptions {
     dir: string;
     force?: boolean;
@@ -19,4 +20,9 @@ export interface InitResult {
     starter: string;
     installed: boolean;
 }
+/** Obtain the starter tarball: local override, else `npm pack` into `tmp`. Shared with `upgrade`. */
+export declare function obtainStarterTarball(tmp: string, out: Output): Promise<{
+    file: string;
+    label: string;
+}>;
 export declare function runInit(opts: InitOptions): Promise<InitResult>;

package/dist/template/init.js

@@ -14,6 +14,7 @@ import { emitProgress } from '../progress.js';
 import { STARTER_PACKAGE, STARTER_TARBALL_ENV, STARTER_VERSION } from './constants.js';
 import { Output } from './project.js';
 import { runNpm, runProcess } from './proc.js';
+import { skillInstallHint } from '../install.js';
 function isNonEmptyDir(dir) {
     if (!existsSync(dir))
         return false;
@@ -22,8 +23,8 @@ function isNonEmptyDir(dir) {
     }
     return readdirSync(dir).length > 0;
 }
-/** Obtain the starter tarball: local override, else `npm pack` into `tmp`. */
-async function obtainTarball(tmp, out) {
+/** Obtain the starter tarball: local override, else `npm pack` into `tmp`. Shared with `upgrade`. */
+export async function obtainStarterTarball(tmp, out) {
     const override = (process.env[STARTER_TARBALL_ENV] ?? '').trim();
     if (override) {
         const file = path.resolve(override);
@@ -58,14 +59,17 @@ export async function runInit(opts) {
     const out = new Output(Boolean(opts.json));
     if (!opts.dir)
         throw new SkillError('❌ 缺少目标目录：remixmate template init <dir>', EXIT.USAGE);
-    const dir = path.resolve(opts.dir);
+    // agent 常把 `~/remixmate-templates/x` 加引号传进来，shell 不会展开 —— 这里补上，
+    // 否则会在 cwd 下建一个字面量 `~` 目录。
+    const raw = opts.dir === '~' || /^~[\\/]/.test(opts.dir) ? path.join(os.homedir(), opts.dir.slice(1)) : opts.dir;
+    const dir = path.resolve(raw);
     if (isNonEmptyDir(dir) && !opts.force) {
         throw new SkillError(`❌ 目标目录非空: ${dir}\n   换一个空目录，或确认可以覆盖后加 --force。`, EXIT.USAGE);
     }
     const tmp = mkdtempSync(path.join(os.tmpdir(), 'remixmate-starter-'));
     try {
         emitProgress({ phase: 'template-init:fetch', progress: 0.1 });
-        const { file, label } = await obtainTarball(tmp, out);
+        const { file, label } = await obtainStarterTarball(tmp, out);
         emitProgress({ phase: 'template-init:extract', progress: 0.4 });
         mkdirSync(dir, { recursive: true });
         // npm tarballs are rooted at `package/` — strip it so files land directly in <dir>.
@@ -94,7 +98,9 @@ export async function runInit(opts) {
     }
 }
 function printNextSteps(out, dir, installed) {
-    const rel = path.relative(process.cwd(), dir) || '.';
+    // 相对路径要往上爬两层以上时（init 到了 /tmp 之类），直接给绝对路径更好读。
+    const relRaw = path.relative(process.cwd(), dir) || '.';
+    const rel = relRaw.startsWith(`..${path.sep}..`) ? dir : relRaw;
     out.info('');
     out.info(`✅ 模板工程已创建: ${dir}`);
     out.info('');
@@ -112,4 +118,16 @@ function printNextSteps(out, dir, installed) {
     out.info('  Claude Code         在工程目录打开，agent 会读取 CLAUDE.md（与 AGENTS.md 内容相同）');
     out.info('  TraeWork            只认项目级 skill：在工程目录执行一次 remixmate install --project');
     out.info('  其它宿主若还没装 skill：remixmate install');
+    out.info('  当前会话不在工程目录里时：先读 ' + path.join(dir, 'AGENTS.md') + '，或在该目录重开会话');
+    let hint = null;
+    try {
+        hint = skillInstallHint();
+    }
+    catch {
+        // 提示只是锦上添花，读回执失败不能让 init 失败。
+    }
+    if (hint) {
+        out.info('');
+        out.info(hint);
+    }
 }

package/dist/template/project.d.ts

@@ -23,6 +23,16 @@ export declare function resolveTemplateKey(templateDir: string): {
     existing: boolean;
 };
 export declare function writeIdentity(templateDir: string, identity: TemplateIdentity): void;
+/** Numeric dotted compare (prerelease tags ignored): <0 / 0 / >0. */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * The starter version whose rules this project's `.remixmate/` holds.
+ * `.remixmate/version.json` wins; 0.1.0 projects fall back to package.json
+ * (copied verbatim from the starter at init). null = unknown.
+ */
+export declare function readRulesVersion(root: string): string | null;
+/** Hint line when the project's rules are older than what this cli ships with, else null. */
+export declare function staleRulesHint(root: string): string | null;
 /**
  * Human text goes to stdout by default. With --json it moves to stderr so the
  * last stdout line is the JSON result (progress lines still go to stdout —

package/dist/template/project.js

@@ -5,7 +5,7 @@ import { randomBytes } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { EXIT, SkillError } from '../errors.js';
-import { CHECK_ENTRY, IDENTITY_FILE } from './constants.js';
+import { CHECK_ENTRY, IDENTITY_FILE, RULES_VERSION_FILE, STARTER_PACKAGE, STARTER_VERSION } from './constants.js';
 import { usageError } from './args.js';
 // ── project root ─────────────────────────────────────────────────────────────
 /** Walk up from `start` to the directory holding `.remixmate/check/index.mjs`. */
@@ -85,6 +85,57 @@ export function resolveTemplateKey(templateDir) {
 export function writeIdentity(templateDir, identity) {
     writeFileSync(path.join(templateDir, IDENTITY_FILE), JSON.stringify(identity, null, 2) + '\n', 'utf8');
 }
+// ── rules version (template upgrade) ─────────────────────────────────────────
+/** Numeric dotted compare (prerelease tags ignored): <0 / 0 / >0. */
+export function compareVersions(a, b) {
+    const parse = (v) => v.replace(/^v/, '').split(/[-+]/)[0].split('.').map((n) => Number(n) || 0);
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * The starter version whose rules this project's `.remixmate/` holds.
+ * `.remixmate/version.json` wins; 0.1.0 projects fall back to package.json
+ * (copied verbatim from the starter at init). null = unknown.
+ */
+export function readRulesVersion(root) {
+    const marker = path.join(root, RULES_VERSION_FILE);
+    if (existsSync(marker)) {
+        try {
+            const v = JSON.parse(readFileSync(marker, 'utf8')).starterVersion;
+            if (typeof v === 'string' && v)
+                return v;
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    const pkgFile = path.join(root, 'package.json');
+    if (existsSync(pkgFile)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+            if (pkg.name === STARTER_PACKAGE && typeof pkg.version === 'string')
+                return pkg.version;
+        }
+        catch {
+            /* unknown */
+        }
+    }
+    return null;
+}
+/** Hint line when the project's rules are older than what this cli ships with, else null. */
+export function staleRulesHint(root) {
+    const have = readRulesVersion(root);
+    if (have && compareVersions(have, STARTER_VERSION) >= 0)
+        return null;
+    return (`⚠ 本地校验规则来自 starter ${have ?? '(未知版本)'}，当前 cli 对应 ${STARTER_VERSION}。` +
+        '平台规则可能已更新，本地通过不代表发布能过。运行 remixmate template upgrade 更新规则（不会改动 templates/）。');
+}
 // ── output ───────────────────────────────────────────────────────────────────
 /**
  * Human text goes to stdout by default. With --json it moves to stderr so the

package/dist/template/upgrade.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `remixmate template upgrade [--dry-run] [--with-docs] [--force] [--json]`
+ *
+ * 只更新工程里的本地校验规则（`.remixmate/`：check 脚本、template.schema.json、
+ * template-security-policy.json），来源是本 cli 钉死的 starter 版本（STARTER_VERSION）。
+ *
+ * 为什么需要：starter 在 init 时整份复制进用户工程，之后平台收紧规则，老工程的
+ * 本地 check 还是旧规则 —— 本地通过、服务端拒绝。一个 starter 版本 = 一套规则版本，
+ * 所以升级 cli 后跑一次 upgrade 就能对齐。
+ *
+ * 刻意不动的东西：templates/（用户的模板）、src/、package.json 与依赖、examples/。
+ * core 版本变化只提示不自动改 —— 升 core 可能影响模板渲染，必须是用户的决定。
+ * `--with-docs` 额外刷新 AGENTS.md / CLAUDE.md（内容不同时旧文件备份为 *.orig）。
+ */
+export interface UpgradeOptions {
+    dryRun?: boolean;
+    withDocs?: boolean;
+    /** Re-apply even when the project is already at (or above) this cli's starter version. */
+    force?: boolean;
+    json?: boolean;
+    cwd?: string;
+}
+export interface UpgradeResult {
+    ok: true;
+    from: string | null;
+    to: string;
+    upgraded: boolean;
+    dryRun: boolean;
+    docs: string[];
+    /** Dependency versions the new starter pins that differ from the project's (hint only). */
+    dependencyHints: Array<{
+        name: string;
+        project: string | null;
+        starter: string;
+    }>;
+}
+type Pkg = {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+};
+/** Dependencies whose pinned version the starter changed — reported, never auto-applied. */
+export declare function diffDependencies(project: Pkg, starter: Pkg): UpgradeResult['dependencyHints'];
+export declare function runUpgrade(opts?: UpgradeOptions): Promise<UpgradeResult>;
+export {};

package/dist/template/upgrade.js

@@ -0,0 +1,123 @@
+/**
+ * `remixmate template upgrade [--dry-run] [--with-docs] [--force] [--json]`
+ *
+ * 只更新工程里的本地校验规则（`.remixmate/`：check 脚本、template.schema.json、
+ * template-security-policy.json），来源是本 cli 钉死的 starter 版本（STARTER_VERSION）。
+ *
+ * 为什么需要：starter 在 init 时整份复制进用户工程，之后平台收紧规则，老工程的
+ * 本地 check 还是旧规则 —— 本地通过、服务端拒绝。一个 starter 版本 = 一套规则版本，
+ * 所以升级 cli 后跑一次 upgrade 就能对齐。
+ *
+ * 刻意不动的东西：templates/（用户的模板）、src/、package.json 与依赖、examples/。
+ * core 版本变化只提示不自动改 —— 升 core 可能影响模板渲染，必须是用户的决定。
+ * `--with-docs` 额外刷新 AGENTS.md / CLAUDE.md（内容不同时旧文件备份为 *.orig）。
+ */
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { EXIT, SkillError } from '../errors.js';
+import { emitProgress } from '../progress.js';
+import { DOC_FILES, RULES_DIR, RULES_VERSION_FILE, STARTER_VERSION } from './constants.js';
+import { obtainStarterTarball } from './init.js';
+import { Output, compareVersions, readRulesVersion, requireProjectRoot } from './project.js';
+import { runProcess } from './proc.js';
+/** Dependencies whose pinned version the starter changed — reported, never auto-applied. */
+export function diffDependencies(project, starter) {
+    const mine = { ...project.devDependencies, ...project.dependencies };
+    const theirs = { ...starter.devDependencies, ...starter.dependencies };
+    return Object.entries(theirs)
+        .filter(([name, v]) => mine[name] !== v)
+        .map(([name, v]) => ({ name, project: mine[name] ?? null, starter: v }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function readPkg(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export async function runUpgrade(opts = {}) {
+    const out = new Output(Boolean(opts.json));
+    const root = requireProjectRoot(opts.cwd);
+    const from = readRulesVersion(root);
+    const to = STARTER_VERSION;
+    if (from && compareVersions(from, to) >= 0 && !opts.force) {
+        out.info(`✅ 本地校验规则已是最新（starter ${from}，当前 cli 对应 ${to}）。`);
+        const result = { ok: true, from, to, upgraded: false, dryRun: Boolean(opts.dryRun), docs: [], dependencyHints: [] };
+        out.result({ ...result });
+        return result;
+    }
+    const tmp = mkdtempSync(path.join(os.tmpdir(), 'remixmate-upgrade-'));
+    try {
+        emitProgress({ phase: 'template-upgrade:fetch', progress: 0.2 });
+        const { file, label } = await obtainStarterTarball(tmp, out);
+        const unpacked = path.join(tmp, 'starter');
+        mkdirSync(unpacked, { recursive: true });
+        const tar = await runProcess('tar', ['-xzf', file, '-C', unpacked, '--strip-components=1'], { stdio: 'pipe' });
+        if (tar.code !== 0) {
+            throw new SkillError(`❌ 解压 starter 失败（tar 退出码 ${tar.code}）: ${tar.stderr.trim().slice(0, 300)}`);
+        }
+        const newRules = path.join(unpacked, RULES_DIR);
+        if (!existsSync(path.join(newRules, 'check', 'index.mjs'))) {
+            throw new SkillError(`❌ ${label} 里没有 ${RULES_DIR}/check/index.mjs，不是有效的 starter 包`);
+        }
+        const docs = opts.withDocs
+            ? DOC_FILES.filter((f) => existsSync(path.join(unpacked, f)))
+            : [];
+        const dependencyHints = diffDependencies(readPkg(path.join(root, 'package.json')), readPkg(path.join(unpacked, 'package.json')));
+        out.info(`升级本地校验规则：starter ${from ?? '(未知版本)'} → ${to}（${label}）`);
+        out.info(`  替换 ${RULES_DIR}/（check 脚本、schema、安全策略）`);
+        for (const d of docs)
+            out.info(`  刷新 ${d}（内容不同时旧文件备份为 ${d}.orig）`);
+        out.info('  不改动 templates/、src/、examples/、package.json');
+        if (!opts.dryRun) {
+            emitProgress({ phase: 'template-upgrade:apply', progress: 0.6 });
+            // 先放到旁边再整体换名，避免复制到一半中断留下半新半旧的规则目录。
+            const target = path.join(root, RULES_DIR);
+            const staged = path.join(root, `${RULES_DIR}.upgrading`);
+            const old = path.join(root, `${RULES_DIR}.previous`);
+            rmSync(staged, { recursive: true, force: true });
+            rmSync(old, { recursive: true, force: true });
+            cpSync(newRules, staged, { recursive: true });
+            // 老 starter 包（0.1.0）没有 version.json：补写，之后 cli 才认得出版本。
+            const marker = path.join(staged, path.relative(RULES_DIR, RULES_VERSION_FILE));
+            if (!existsSync(marker)) {
+                writeFileSync(marker, JSON.stringify({ starterVersion: to }, null, 2) + '\n', 'utf8');
+            }
+            if (existsSync(target))
+                renameSync(target, old);
+            renameSync(staged, target);
+            rmSync(old, { recursive: true, force: true });
+            for (const d of docs) {
+                const dest = path.join(root, d);
+                const next = readFileSync(path.join(unpacked, d), 'utf8');
+                if (existsSync(dest)) {
+                    const prev = readFileSync(dest, 'utf8');
+                    if (prev === next)
+                        continue;
+                    writeFileSync(`${dest}.orig`, prev, 'utf8');
+                }
+                writeFileSync(dest, next, 'utf8');
+            }
+        }
+        for (const h of dependencyHints) {
+            out.warn(`  ⚠ 新 starter 钉的 ${h.name}@${h.starter}，你的工程是 ${h.project ?? '(未安装)'}。` +
+                `需要时手动执行 npm i ${h.name}@${h.starter}（升级 core 可能影响模板效果，先 check + preview 再发布）。`);
+        }
+        emitProgress({ phase: 'template-upgrade:done', progress: 1 });
+        out.info(opts.dryRun ? '\n[dry-run] 未写入任何文件。' : '\n✅ 已更新。接着运行 remixmate template check 看新规则下是否还有问题。');
+        const result = { ok: true, from, to, upgraded: !opts.dryRun, dryRun: Boolean(opts.dryRun), docs, dependencyHints };
+        out.result({ ...result });
+        return result;
+    }
+    catch (err) {
+        if (err instanceof SkillError)
+            throw err;
+        throw new SkillError(`❌ 升级失败: ${err.message}`, EXIT.ERROR);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.66",
+  "version": "0.9.67",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",

package/skills/template-authoring/SKILL.md

@@ -4,15 +4,17 @@ description: |
   Create your own reusable video template locally and publish it as a private template on RemixMate.
   Scaffolds a starter project (`remixmate template init <dir>`) with Remotion Studio preview, local validation,
   remote draft preview and one-command publishing. Purely local until preview/publish; no login needed to start.
-  Use this skill whenever the user wants to:
-  - 做视频模板 / 自定义视频模板 / 创建模板 / 自己写一个模板 / 把这个画面做成模板
+  Use this skill whenever the user wants to (「模板」and「模版」are the same word):
+  - 做视频模板 / 做视频模版 / 自定义视频模板 / 创建一个新的视频模版 / 新建模版 / 自己写一个模板 / 把这个画面做成模板
   - template authoring, create a video template, build a custom Remotion template
   - preview or publish a template they are developing locally
 triggers:
-  - 做视频模板
-  - 自定义视频模板
-  - 创建模板 / 新建模板 / 自己写一个视频模板
-  - 预览或发布我本地开发的模板
+  - 做视频模板 / 做视频模版
+  - 自定义视频模板 / 自定义视频模版
+  - 创建模板 / 新建模板 / 创建模版 / 新建模版
+  - 我想创建一个新的视频模版 / 创建一个视频模板
+  - 自己写一个视频模板 / 自己做一个模版
+  - 预览或发布我本地开发的模板 / 模版
   - template authoring
   - create video template / build a custom video template
   - publish my own Remotion template
@@ -30,15 +32,21 @@ fields; take them from that guide and from the bundled examples.
 
 ## Workflow
 
-1. **Create the project** (no login):
+1. **Create the project** (no login). Use an absolute path outside the current repo, e.g.
+   `~/remixmate-templates/<name>`, unless the user names a location:
    ```bash
-   remixmate template init <dir>
+   remixmate template init ~/remixmate-templates/<name>
    ```
    Refuses a non-empty directory unless `--force`. Needs only Node ≥ 18 and npm.
    As a skill call: `remixmate template-authoring --dir <dir> [--force]`.
-2. **Open the project and read `AGENTS.md`** before writing any code. Examples live in
-   `examples/` (read-only — copy one into `templates/<name>/` and edit the copy).
-3. **Develop with live preview**: `npm run dev` opens Remotion Studio.
+   **Needs network**: it runs `npm pack` + `npm install` (a few hundred packages, about a minute).
+   In a sandboxed host (e.g. Codex) request network / escalated permission for this command up
+   front. Exit code 5 or an npm network error = no network — not a bug in the project.
+2. **Open the project and read `<dir>/AGENTS.md`** before writing any code. If the session is not
+   rooted in `<dir>`, read that file by absolute path (or suggest reopening the session there).
+   Examples live in `examples/` (read-only — copy one into `templates/<name>/` and edit the copy).
+3. **Develop with live preview**: `npm run dev` opens Remotion Studio. The first run (and the first
+   local render) downloads a headless Chrome — also needs network, may take a while.
 4. **Validate locally** (no login):
    ```bash
    remixmate template check <name>          # add --json for a machine-readable issue list
@@ -56,12 +64,23 @@ fields; take them from that guide and from the bundled examples.
    ```
    The first publish writes `templates/<name>/.remixmate.json` with the template key; publishing
    again updates the same template. Keep that file.
-7. **Render with it**:
+7. **Render with it** — `render-video` needs a DSL source; `--template-id` alone is rejected.
+   Start from the template's own example (absolute path):
    ```bash
-   remixmate render-video --template-id <templateKey> ...
+   remixmate render-video --dsl "$PWD/templates/<name>/dsl-example.json" --template-id <templateKey>
    ```
    `remixmate template list` shows the user's private templates.
 
+## Keeping the local rules current
+
+The project's check rules (`.remixmate/`) are copied in at init time. When `check` / `preview` /
+`publish` print "本地校验规则来自 starter …" the platform rules have moved on — run:
+```bash
+remixmate template upgrade            # replaces .remixmate/ only; templates/ untouched
+remixmate template upgrade --with-docs  # also refresh AGENTS.md / CLAUDE.md (old copies kept as *.orig)
+```
+Then re-run `check`. Dependency changes (e.g. a newer template-core) are reported, never applied.
+
 ## Notes
 
 - Not logged in → exit code 4: run `remixmate login`. Backend unreachable → exit code 5.

package/skills/template-authoring/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-authoring",
   "repoName": "agent-skill-media-maker",
   "skillId": "pending-template-authoring",
-  "version": "V1",
-  "skillDescription": "Local video-template authoring skill: scaffolds a RemixMate template starter project (`remixmate template init <dir>`), then guides the agent through the project's AGENTS.md, `npm run dev`, `remixmate template check`, `remixmate template preview`, `remixmate template publish`, and rendering with `remixmate render-video --template-id <templateKey>`.\n\nUse this skill whenever the user asks for any of:\n- 做视频模板 / 自定义视频模板 / 创建模板\n- template authoring, create a video template\n- preview or publish a template they develop locally"
+  "version": "V3",
+  "skillDescription": "Local video-template authoring skill: scaffolds a RemixMate template starter project (`remixmate template init <dir>`), then guides the agent through the project's AGENTS.md, `npm run dev`, `remixmate template check`, `remixmate template preview`, `remixmate template publish`, and rendering with `remixmate render-video --template-id <templateKey>`.\n\nUse this skill whenever the user asks for any of:\n- 做视频模板 / 做视频模版 / 自定义视频模板 / 创建模板 / 创建一个新的视频模版 / 新建模版\n- template authoring, create a video template\n- preview or publish a template they develop locally"
 }