@remixmate/cli 0.9.21 → 0.9.23

package/README.md

@@ -11,32 +11,44 @@ AI media generation skills for Claude Code / Codex.
 ## Install
 
 ```bash
-npm install -g @remixmate/cli
-remixmate --help
-remixmate --list
+npm install -g @remixmate/cli && remixmate install
 ```
 
-## Use in Claude Code
+`npm install` gives you the `remixmate` binary. `remixmate install` is what makes an
+agent *discover* the skills on its own: it copies the bundled `skills/` into every
+agent home it finds. All of these hosts read the same `SKILL.md` format, so one
+`skills/` directory serves all of them:
 
-Copy the bundled `skills/` into your project-level or global `.claude/skills/` directory and Claude Code will pick them up:
+| Host | User-level | Project-level | Override |
+| --- | --- | --- | --- |
+| Claude Code | `~/.claude/skills` | `./.claude/skills` | `CLAUDE_CONFIG_DIR` |
+| Codex | `~/.codex/skills` | — | `CODEX_HOME` |
+| WorkBuddy | `~/.workbuddy/skills` | `./.workbuddy/skills` | — |
+| CodeBuddy | `~/.codebuddy/skills` | `./.codebuddy/skills` | — |
+| Trae / TraeWork | — | `./.trae/skills` | — |
 
-```bash
-# project-level
-mkdir -p .claude/skills
-cp -R "$(npm root -g)/@remixmate/cli/skills/." .claude/skills/
+Trae CN and TraeWork CN share `~/.trae-cn` and only define a workspace location (`.trae/skills/<name>/`, per its own built-in
+`skill-creator`), so it is installed per project — a plain `remixmate install` reports
+it and tells you to re-run with `--project` inside the repo. Restart the agent
+afterwards.
 
-# or global
-mkdir -p ~/.claude/skills
-cp -R "$(npm root -g)/@remixmate/cli/skills/." ~/.claude/skills/
+```bash
+remixmate install --host workbuddy  # only one host
+remixmate install --project         # ./<config-dir>/skills (not Codex — it has none)
+remixmate install --dir <path>      # explicit target, for a host not listed above
+remixmate uninstall                 # remove exactly what was installed
 ```
 
-## Use in Codex
-
-Codex does not load `SKILL.md` natively. Tell Codex about the CLI in your system prompt and let it invoke `remixmate <skill> ...` when it needs media generation:
-
-> When you need AI media generation (image / video / voice / talking-head / Jianying export), prefer running `remixmate <skill-id> --help` first to discover the flags, then `remixmate <skill-id> --json-output ...` to execute. Available skills: `remixmate --list`.
+The install is *managed*, not a `cp -R`: each skills directory gets a
+`.remixmate-install.json` receipt recording the version and the skill list. That is
+what lets a re-run upgrade in place, lets `uninstall` remove only our own directories,
+and lets `remixmate doctor` warn when a global `npm update` has left the installed
+copies behind. A same-named skill that this CLI did not install is never overwritten
+without `--force`.
 
-See the full intro page (Claude Code / Codex setup, env vars, end-to-end workflow examples) at the project homepage.
+Without installing, the CLI still works — you just have to name it (`remixmate --list`,
+or tell the agent to run `remixmate <skill> --help`). The agent will not reach for it
+unprompted.
 
 ## Authentication
 

package/README.zh-CN.md

@@ -11,32 +11,39 @@
 ## 安装
 
 ```bash
-npm install -g @remixmate/cli
-remixmate --help
-remixmate --list
+npm install -g @remixmate/cli && remixmate install
 ```
 
-## 在 Claude Code 中使用
+`npm install` 装的是 `remixmate` 这个命令；`remixmate install` 才让 agent **自己发现**
+这些 skill —— 它把内置的 `skills/` 铺进检测到的每个 agent 目录。下面这些宿主用的是
+同一套 `SKILL.md` 格式，所以一份 `skills/` 全都能喂：
 
-把内置的 `skills/` 拷贝到项目级或全局的 `.claude/skills/` 目录，Claude Code 会自动识别：
+| 宿主 | 用户级 | 项目级 | 可用环境变量改位置 |
+| --- | --- | --- | --- |
+| Claude Code | `~/.claude/skills` | `./.claude/skills` | `CLAUDE_CONFIG_DIR` |
+| Codex | `~/.codex/skills` | — | `CODEX_HOME` |
+| WorkBuddy | `~/.workbuddy/skills` | `./.workbuddy/skills` | — |
+| CodeBuddy | `~/.codebuddy/skills` | `./.codebuddy/skills` | — |
+| Trae / TraeWork | — | `./.trae/skills` | — |
 
-```bash
-# 项目级
-mkdir -p .claude/skills
-cp -R "$(npm root -g)/@remixmate/cli/skills/." .claude/skills/
+Trae CN 与 TraeWork CN 共用 `~/.trae-cn`，且只定义了工作区位置（`.trae/skills/<name>/`，依据是它自带的 `skill-creator`），
+所以只能按项目装 —— 直接跑 `remixmate install` 会提示你进项目目录加 `--project` 重跑。
+装完重启 agent 生效。
 
-# 或全局
-mkdir -p ~/.claude/skills
-cp -R "$(npm root -g)/@remixmate/cli/skills/." ~/.claude/skills/
+```bash
+remixmate install --host workbuddy  # 只装某一个宿主
+remixmate install --project         # 装到 ./<配置目录>/skills（Codex 没有项目级目录）
+remixmate install --dir <path>      # 指定目录，用于上表之外的宿主
+remixmate uninstall                 # 按装机记录精确卸载
 ```
 
-## 在 Codex 中使用
-
-Codex 不会原生加载 `SKILL.md`。在系统提示里告诉 Codex 这个 CLI，让它在需要媒体生成时调用 `remixmate <skill> ...`：
-
-> 当你需要 AI 媒体生成（图片 / 视频 / 语音 / 数字人 / 剪映导出）时，先运行 `remixmate <skill-id> --help` 查看参数，再用 `remixmate <skill-id> --json-output ...` 执行。可用技能：`remixmate --list`。
+这里的安装是**受管**的，不是 `cp -R`：每个 skills 目录下会写一份
+`.remixmate-install.json` 回执，记录版本与本次铺下去的 skill 名单。靠它，重跑即原地升级、
+`uninstall` 只删自己装的目录、`remixmate doctor` 能在 `npm update -g` 之后提示铺出去的副本
+已经落后。同名但不是本 CLI 装的 skill，不加 `--force` 绝不覆盖。
 
-完整介绍页（Claude Code / Codex 配置、环境变量、端到端工作流示例）见项目主页。
+不装也能用，只是得点名（`remixmate --list`，或让 agent 去跑 `remixmate <skill> --help`）；
+agent 不会主动想到它。
 
 ## 认证
 

package/dist/cli.js

@@ -16,6 +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 { runExec } from './exec.js';
 import { authStatusLine, runDoctor } from './doctor.js';
 import { padDisplay } from './text.js';
@@ -51,6 +52,8 @@ function printUsage() {
     const skills = loadSkills(resolveBaseDir());
     process.stdout.write('Usage:\n');
     process.stdout.write('  remixmate --list                      List all skills\n');
+    process.stdout.write('  remixmate install [--host <h>]        Install the skills into Claude Code / Codex\n');
+    process.stdout.write('  remixmate uninstall                   Remove skills installed by this CLI\n');
     process.stdout.write('  remixmate doctor                      Diagnose environment, credentials, backend\n');
     process.stdout.write('  remixmate login                       Authorize this CLI via the browser\n');
     process.stdout.write('  remixmate login --start | --wait      Non-blocking authorization (for agent hosts)\n');
@@ -128,6 +131,14 @@ async function main() {
             await printAuthFooter();
         process.exit(EXIT.OK);
     }
+    // Host-install verbs, like the auth verbs, resolve before skill dispatch so a
+    // future skill named `install` could never shadow them.
+    if (argv[0] === INSTALL_VERB) {
+        process.exit(runInstall(argv.slice(1)));
+    }
+    if (argv[0] === UNINSTALL_VERB) {
+        process.exit(runUninstall(argv.slice(1)));
+    }
     if (argv[0] === 'doctor') {
         const code = await runDoctor({ skipNetwork: argv.includes('--offline') });
         process.exit(code);

package/dist/doctor.js

@@ -20,6 +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 { padDisplay } from './text.js';
 /**
  * Short auth status suitable for a footer. Never performs network I/O — a
@@ -100,6 +101,22 @@ export async function runDoctor(opts = {}) {
         detail: playwright ?? '当前解释器下未安装 —— 仅 web-screenshot / web-record 需要，首次运行会自动装',
     });
     checks.push({ name: '后端地址', status: 'ok', detail: apiBaseUrl });
+    // 宿主安装状态。这套方案唯一的静默失败模式是漂移：`npm update -g` 只动包，不动
+    // 已经铺进 ~/.claude/skills、~/.codex/skills 的副本,用户会拿着旧 SKILL.md 打新
+    // 后端,而且第一个症状往往是某个参数「莫名其妙不认」。
+    for (const s of installStates()) {
+        checks.push({
+            // 只取宿主名的第一段（Claude Code → Claude）——检查名要留在 padDisplay 的
+            // 对齐宽度内，宿主目录已经写在 detail 里，不会有歧义。
+            name: `${s.label.split(' ')[0]} skill`,
+            status: s.installedVersion == null ? 'warn' : s.drifted ? 'warn' : 'ok',
+            detail: s.installedVersion == null
+                ? `未安装 —— 该 agent 不会自动发现这些 skill（remixmate install 可安装到 ${s.skillsDir}）`
+                : s.drifted
+                    ? `已装 ${s.installedVersion}，当前包 ${s.currentVersion} → 运行 remixmate install 覆盖`
+                    : `${s.installedVersion}（${s.skillsDir}）`,
+        });
+    }
     // Where will this machine's renders land, and will repeated renders group?
     // Both were previously invisible — the first sign of trouble was a finished
     // video that appeared nowhere in the web app.
@@ -149,7 +166,9 @@ export async function runDoctor(opts = {}) {
     if (!opts.skipNetwork)
         checks.push(await checkBackend(apiBaseUrl));
     for (const c of checks) {
-        process.stdout.write(`${ICON[c.status]} ${padDisplay(c.name, 14)}${c.detail}\n`);
+        // 16 而不是 14：宿主检查名最长是「WorkBuddy skill」，窄一格就会把那两行的
+        // detail 列顶出去，报告看起来像是漏了对齐。
+        process.stdout.write(`${ICON[c.status]} ${padDisplay(c.name, 16)}${c.detail}\n`);
     }
     const failed = checks.filter((c) => c.status === 'fail');
     if (failed.length === 0) {

package/dist/install.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `remixmate install` / `remixmate uninstall` — 把包内 skills/ 铺进 agent 宿主。
+ *
+ * 为什么需要一条命令，而不是让站点给出 `cp -R "$(npm root -g)/…/skills/." ~/.claude/skills/`：
+ *
+ *   1. 目标已经不止一个。Claude Code 与 Codex 现在用同一套 SKILL.md 格式
+ *      （Codex 装到 $CODEX_HOME/skills/<name>），手工 cp 的心智成本直接翻倍。
+ *   2. 拷贝出去的副本没有主人。`npm update -g` 之后包升了级、副本停在旧版；
+ *      `npm uninstall -g` 之后副本原地变成孤儿。两种都是静默的 —— 本项目作者机器上
+ *      就留着一批 5 月建的、指向早已不存在路径的 skill 目录，没有任何东西负责清理。
+ *
+ * 所以这里的安装是**受管**的：每个宿主的 skills 目录下写一份装机回执
+ * (.remixmate-install.json)，记下版本、来源与这次铺下去的 skill 名单。升级照名单
+ * 覆盖、卸载照名单删除、doctor 照名单比对版本 —— 三件事都不靠猜目录里哪些是我们的。
+ *
+ * 刻意不做的两件事：
+ *   - 不挂 npm postinstall。`npm i -g` 时往 ~/.claude、~/.codex 写东西太越界，
+ *     且 `--ignore-scripts` 下会静默失效。安装必须是用户显式发起的动作。
+ *   - 不用软链。指向 $(npm root -g) 看着优雅，但 node 版本管理器一切换路径就变，
+ *     全部断掉且极难排查。拷贝 + 回执 + doctor 漂移检查更稳。
+ */
+export declare const INSTALL_VERB = "install";
+export declare const UNINSTALL_VERB = "uninstall";
+export type HostId = 'claude' | 'codex' | 'workbuddy' | 'codebuddy' | 'trae';
+interface Host {
+    id: HostId | 'custom';
+    label: string;
+    /** skill 的父目录 —— 安装写到 <skillsDir>/<skill-name>/。 */
+    skillsDir: string;
+}
+/** 已检测到、且**有用户级位置**的宿主。 */
+export declare function detectHosts(): Host[];
+/**
+ * 检测到了、但只能项目级安装的宿主（当前只有 Trae）。
+ *
+ * 单独拎出来是为了别把它们**静默**跳过：用户装了 Trae 却在全局 install 的输出里
+ * 完全看不到它，只会以为这个 CLI 不支持 —— 正是这次 WorkBuddy 的翻车方式。
+ */
+export declare function projectOnlyHosts(): HostId[];
+export declare function installUsage(): void;
+export declare function uninstallUsage(): void;
+export declare function runInstall(argv: string[]): number;
+export declare function runUninstall(argv: string[]): number;
+export interface InstallState {
+    label: string;
+    skillsDir: string;
+    /** 回执里的版本；null = 该宿主下没有本 CLI 的安装。 */
+    installedVersion: string | null;
+    /** 当前包的版本，供报告直接引用。 */
+    currentVersion: string;
+    /** 回执版本与当前包版本不一致。 */
+    drifted: boolean;
+}
+/**
+ * 供 doctor 使用：每个宿主的安装状态。
+ *
+ * 漂移是这套方案唯一的静默失败模式 —— `npm update -g` 只动包，不动铺出去的副本，
+ * 用户会拿着旧 SKILL.md 打新后端。doctor 是「为什么跑不起来」的统一入口，检查放这里。
+ */
+export declare function installStates(): InstallState[];
+export {};

package/dist/install.js

@@ -0,0 +1,429 @@
+/**
+ * `remixmate install` / `remixmate uninstall` — 把包内 skills/ 铺进 agent 宿主。
+ *
+ * 为什么需要一条命令，而不是让站点给出 `cp -R "$(npm root -g)/…/skills/." ~/.claude/skills/`：
+ *
+ *   1. 目标已经不止一个。Claude Code 与 Codex 现在用同一套 SKILL.md 格式
+ *      （Codex 装到 $CODEX_HOME/skills/<name>），手工 cp 的心智成本直接翻倍。
+ *   2. 拷贝出去的副本没有主人。`npm update -g` 之后包升了级、副本停在旧版；
+ *      `npm uninstall -g` 之后副本原地变成孤儿。两种都是静默的 —— 本项目作者机器上
+ *      就留着一批 5 月建的、指向早已不存在路径的 skill 目录，没有任何东西负责清理。
+ *
+ * 所以这里的安装是**受管**的：每个宿主的 skills 目录下写一份装机回执
+ * (.remixmate-install.json)，记下版本、来源与这次铺下去的 skill 名单。升级照名单
+ * 覆盖、卸载照名单删除、doctor 照名单比对版本 —— 三件事都不靠猜目录里哪些是我们的。
+ *
+ * 刻意不做的两件事：
+ *   - 不挂 npm postinstall。`npm i -g` 时往 ~/.claude、~/.codex 写东西太越界，
+ *     且 `--ignore-scripts` 下会静默失效。安装必须是用户显式发起的动作。
+ *   - 不用软链。指向 $(npm root -g) 看着优雅，但 node 版本管理器一切换路径就变，
+ *     全部断掉且极难排查。拷贝 + 回执 + doctor 漂移检查更稳。
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SKILLS_DIR } from './registry.js';
+import { EXIT } from './errors.js';
+import { padDisplay } from './text.js';
+export const INSTALL_VERB = 'install';
+export const UNINSTALL_VERB = 'uninstall';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+/** 装机回执。升级 / 卸载 / 漂移检查都只认它。 */
+const RECEIPT = '.remixmate-install.json';
+const PACKAGE_NAME = '@remixmate/cli';
+/**
+ * 支持的 agent 宿主。
+ *
+ * 共同点是 skill 的格式：`<某个目录>/skills/<name>/SKILL.md`，frontmatter 都是
+ * name + description —— 一份 skills/ 能喂给所有宿主。这张表记的是各家把那个「某个
+ * 目录」放在哪、能不能被环境变量改、有没有用户级 / 项目级。
+ *
+ * 每一条的依据：
+ *   - Claude Code / Codex：各自的官方安装位置（Codex 见其内置 skill-installer，
+ *     原话是装到 $CODEX_HOME/skills）。
+ *   - WorkBuddy / CodeBuddy：WorkBuddy 内置的 find-skills skill 给了两条路径,
+ *     它按 __CFBundleIdentifier 区分。这里不做那个区分 —— 检测到哪个装哪个,
+ *     两个都在就都装,比猜「当前跑在哪个客户端里」稳。
+ *   - Trae：内置的 skill-creator skill 只给了一个位置 —— 工作区的
+ *     `.trae/skills/<name>/`。注意它的应用数据目录叫 ~/.trae-cn(国内版),
+ *     跟 skill 目录名 .trae 不是一个东西,而且 ~/.trae-cn/skills 并不存在。
+ *     没有任何证据表明存在用户级位置,所以 userDirName 留空:Trae 只能项目级装。
+ */
+const HOSTS = [
+    {
+        id: 'claude',
+        label: 'Claude Code',
+        detectDirNames: ['.claude'],
+        homeEnv: 'CLAUDE_CONFIG_DIR',
+        userDirName: '.claude',
+        projectDirName: '.claude',
+    },
+    {
+        id: 'codex',
+        label: 'Codex',
+        detectDirNames: ['.codex'],
+        homeEnv: 'CODEX_HOME',
+        userDirName: '.codex',
+    },
+    {
+        id: 'workbuddy',
+        label: 'WorkBuddy',
+        detectDirNames: ['.workbuddy'],
+        userDirName: '.workbuddy',
+        projectDirName: '.workbuddy',
+    },
+    {
+        id: 'codebuddy',
+        label: 'CodeBuddy',
+        detectDirNames: ['.codebuddy'],
+        userDirName: '.codebuddy',
+        projectDirName: '.codebuddy',
+    },
+    {
+        id: 'trae',
+        // Trae CN 与 TraeWork CN（安装出来叫 TRAE SOLO CN.app，bundle id cn.trae.solo.app）
+        // 共用 ~/.trae-cn —— 后者的内置 skill(dynamic-ui 等)就躺在那底下的
+        // builtin/*/skills/，所以一条 host 覆盖两个客户端。
+        label: 'Trae / TraeWork',
+        detectDirNames: ['.trae-cn', '.trae'],
+        projectDirName: '.trae',
+    },
+];
+const HOST_IDS = HOSTS.map((h) => h.id);
+function spec(id) {
+    return HOSTS.find((h) => h.id === id);
+}
+/**
+ * 用户级 skills 目录；宿主没有用户级位置时返回 null。声明了环境变量的宿主要跟着
+ * 变量走 —— 否则把 CODEX_HOME 指到别处的用户会看到「未检测到 Codex」。
+ */
+function userSkillsDir(id) {
+    const h = spec(id);
+    if (!h.userDirName)
+        return null;
+    const override = h.homeEnv ? process.env[h.homeEnv] : undefined;
+    return path.join(override || path.join(os.homedir(), h.userDirName), 'skills');
+}
+/** 检测用的候选目录 —— 存在任意一个就算这台机器上装了这个 agent。 */
+function detectDirs(id) {
+    const h = spec(id);
+    const override = h.homeEnv ? process.env[h.homeEnv] : undefined;
+    if (override)
+        return [override];
+    return h.detectDirNames.map((d) => path.join(os.homedir(), d));
+}
+function isInstalled(id) {
+    return detectDirs(id).some((d) => existsSync(d));
+}
+function hostOf(id) {
+    const dir = userSkillsDir(id);
+    return dir ? { id, label: spec(id).label, skillsDir: dir } : null;
+}
+/** 项目级安装目标：当前目录下的 ./<projectDirName>/skills。 */
+function projectHostOf(id) {
+    const h = spec(id);
+    if (!h.projectDirName)
+        return null;
+    return {
+        id,
+        label: `${h.label}（项目级）`,
+        skillsDir: path.join(process.cwd(), h.projectDirName, 'skills'),
+    };
+}
+/** 已检测到、且**有用户级位置**的宿主。 */
+export function detectHosts() {
+    return HOST_IDS.filter(isInstalled)
+        .map(hostOf)
+        .filter((h) => h !== null);
+}
+/**
+ * 检测到了、但只能项目级安装的宿主（当前只有 Trae）。
+ *
+ * 单独拎出来是为了别把它们**静默**跳过：用户装了 Trae 却在全局 install 的输出里
+ * 完全看不到它，只会以为这个 CLI 不支持 —— 正是这次 WorkBuddy 的翻车方式。
+ */
+export function projectOnlyHosts() {
+    return HOST_IDS.filter((id) => isInstalled(id) && !spec(id).userDirName);
+}
+function packageVersion() {
+    try {
+        const raw = readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8');
+        return JSON.parse(raw).version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * 包内可安装的 skill 名单。
+ *
+ * 用 SKILLS_DIR 而不是 resolveBaseDir()：install 铺的永远是**本包自带**的那份，
+ * SKILL_BASE_DIR 是给 ab-agent 之类宿主在运行期改 skill 树用的，不该改变安装来源。
+ */
+function bundledSkills() {
+    if (!existsSync(SKILLS_DIR))
+        return [];
+    return readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(path.join(SKILLS_DIR, e.name, 'SKILL.md')))
+        .map((e) => e.name)
+        .sort();
+}
+function readReceipt(skillsDir) {
+    const file = path.join(skillsDir, RECEIPT);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        // 回执损坏时按「没装过」处理:那样只会退化成需要 --force,而不是把用户的目录删错。
+        return null;
+    }
+}
+const nonNull = (h) => h !== null;
+function parseArgs(argv, verb) {
+    const out = { hosts: [], force: false, help: false };
+    const picked = [];
+    let all = false;
+    let dir = '';
+    let project = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const eq = a.indexOf('=');
+        const key = eq > 0 ? a.slice(0, eq) : a;
+        const inline = eq > 0 ? a.slice(eq + 1) : null;
+        const next = () => inline ?? argv[++i] ?? '';
+        switch (key) {
+            case '--host': {
+                const v = next();
+                // `all` 是「所有**适用**的宿主」，不是「表里每一行」—— 展开成后者会让
+                // `--host all` 撞上 Trae 这种只有项目级的宿主而整条命令失败。
+                if (v === 'all')
+                    all = true;
+                else if (HOST_IDS.includes(v))
+                    picked.push(v);
+                else {
+                    out.error = `未知参数: --host ${v}`;
+                    return out;
+                }
+                break;
+            }
+            case '--dir':
+                dir = next();
+                break;
+            case '--project':
+                project = true;
+                break;
+            case '--force':
+                out.force = true;
+                break;
+            case '-h':
+            case '--help':
+                out.help = true;
+                return out;
+            default:
+                out.error = `未知参数: ${a}`;
+                return out;
+        }
+    }
+    if (dir) {
+        out.hosts = [{ id: 'custom', label: '自定义目录', skillsDir: path.resolve(dir) }];
+        return out;
+    }
+    if (project) {
+        // Codex 的官方安装位置只有 $CODEX_HOME/skills（见其内置 skill-installer），
+        // 没有项目级约定,不臆造一个 —— 点名 --host codex --project 直接报错,
+        // 不声不响装到一个宿主永远不会读的目录才是最糟的。
+        const chosen = all
+            ? HOST_IDS.filter((id) => spec(id).projectDirName)
+            : picked.length > 0
+                ? [...new Set(picked)]
+                : HOST_IDS.filter((id) => isInstalled(id) && spec(id).projectDirName);
+        const unsupported = chosen.filter((id) => !spec(id).projectDirName);
+        if (unsupported.length > 0) {
+            out.error = `${unsupported.map((id) => spec(id).label).join('、')} 没有项目级 skill 目录，不能和 --project 一起用`;
+            return out;
+        }
+        out.hosts = chosen.map(projectHostOf).filter(nonNull);
+        return out;
+    }
+    if (all) {
+        out.hosts = HOST_IDS.map(hostOf).filter(nonNull);
+        return out;
+    }
+    if (picked.length > 0) {
+        const chosen = [...new Set(picked)];
+        // 点名了一个只有项目级的宿主(Trae)却没给 --project:报错而不是默默装到别处。
+        const userless = chosen.filter((id) => !spec(id).userDirName);
+        if (userless.length > 0) {
+            out.error =
+                `${userless.map((id) => spec(id).label).join('、')} 只有项目级 skill 目录 —— ` +
+                    '进到项目根目录后加 --project 重跑。';
+            return out;
+        }
+        out.hosts = chosen.map(hostOf).filter(nonNull);
+    }
+    else {
+        // 卸载时不做检测:配置目录可能已经随 agent 一起被删掉,而我们铺出去的副本还在。
+        out.hosts = verb === UNINSTALL_VERB ? HOST_IDS.map(hostOf).filter(nonNull) : detectHosts();
+    }
+    return out;
+}
+export function installUsage() {
+    process.stdout.write('Usage: remixmate install [options]\n' +
+        '\n' +
+        '把本包自带的 skill 装进已检测到的 agent 宿主，让它们能自动发现这些能力。\n' +
+        '重复运行即升级。支持的宿主：\n' +
+        HOSTS.map((h) => `  ${padDisplay(h.label, 14)}${h.userDirName ? `~/${h.userDirName}/skills` : '（仅项目级）'}${h.projectDirName ? `   项目级 ./${h.projectDirName}/skills` : ''}\n`).join('') +
+        '\n' +
+        'Options:\n' +
+        `  --host <${HOST_IDS.join('|')}|all>\n` +
+        '                             只装指定宿主（默认：装到所有检测到的宿主）\n' +
+        '  --project                  装到当前目录 ./<配置目录>/skills（Codex 不支持）\n' +
+        '  --dir <path>               自定义 skills 父目录（覆盖上面两者）\n' +
+        '  --force                    覆盖同名的、非本 CLI 安装的 skill 目录\n');
+}
+export function uninstallUsage() {
+    process.stdout.write('Usage: remixmate uninstall [options]\n' +
+        '\n' +
+        '按装机回执删除本 CLI 装过的 skill —— 只删回执里列出的目录，不碰其它 skill。\n' +
+        '\n' +
+        'Options:\n' +
+        `  --host <${HOST_IDS.join('|')}|all>\n` +
+        '                             只卸载指定宿主（默认：所有宿主都查）\n' +
+        '  --project                  卸载当前目录 ./.claude/skills 下的安装\n' +
+        '  --dir <path>               自定义 skills 父目录\n');
+}
+function installInto(host, names, version, force) {
+    const prev = readReceipt(host.skillsDir);
+    const owned = new Set(prev?.skills ?? []);
+    // 目录已存在、又不在上一次的回执里 —— 那是别人的 skill(同名很容易撞:gen-image
+    // 这种名字一点也不独特)。默认拒绝而不是覆盖,让用户显式 --force。
+    const conflicts = names.filter((n) => existsSync(path.join(host.skillsDir, n)) && !owned.has(n));
+    if (conflicts.length > 0 && !force) {
+        return (`${host.skillsDir} 下已存在同名目录，且不是本 CLI 装的：${conflicts.join('、')}\n` +
+            '   确认可以覆盖后加 --force 重跑。');
+    }
+    mkdirSync(host.skillsDir, { recursive: true });
+    // 上一版装过、这一版没有了的 skill（上游改名或下线）要一并清掉，否则宿主会一直
+    // 加载一个已经没有后端支撑的 SKILL.md。
+    for (const stale of owned) {
+        if (!names.includes(stale))
+            rmSync(path.join(host.skillsDir, stale), { recursive: true, force: true });
+    }
+    for (const name of names) {
+        const dest = path.join(host.skillsDir, name);
+        // 先删再拷:直接覆盖会把上一版多出来的文件留在原地,攒出一个既非旧版也非新版的目录。
+        rmSync(dest, { recursive: true, force: true });
+        cpSync(path.join(SKILLS_DIR, name), dest, { recursive: true });
+    }
+    const receipt = {
+        package: PACKAGE_NAME,
+        version,
+        installedAt: new Date().toISOString(),
+        source: SKILLS_DIR,
+        skills: names,
+    };
+    writeFileSync(path.join(host.skillsDir, RECEIPT), JSON.stringify(receipt, null, 2) + '\n', 'utf-8');
+    return null;
+}
+export function runInstall(argv) {
+    const opts = parseArgs(argv, INSTALL_VERB);
+    if (opts.help) {
+        installUsage();
+        return EXIT.OK;
+    }
+    if (opts.error) {
+        process.stderr.write(`❌ ${opts.error}\n`);
+        installUsage();
+        return EXIT.USAGE;
+    }
+    const names = bundledSkills();
+    if (names.length === 0) {
+        process.stderr.write(`❌ 包内没有可安装的 skill（${SKILLS_DIR}）\n`);
+        return EXIT.ERROR;
+    }
+    const projectOnly = projectOnlyHosts();
+    if (opts.hosts.length === 0) {
+        // 只检测到项目级宿主(比如只装了 Trae)时,这不是「没检测到」,而是「装法不同」。
+        if (projectOnly.length > 0) {
+            process.stderr.write(`❌ 只检测到 ${projectOnly.map((id) => spec(id).label).join('、')}，` +
+                '它只有项目级 skill 目录。\n' +
+                '   进到项目根目录后运行：remixmate install --project\n');
+            return EXIT.USAGE;
+        }
+        process.stderr.write('❌ 没有检测到任何 agent 宿主。找过这些位置：\n' +
+            HOST_IDS.map((id) => `     ${padDisplay(spec(id).label, 14)}${detectDirs(id).join('、')}\n`).join('') +
+            '   先把 agent 装好再重跑，或用 --dir <path> 指定目录。\n');
+        return EXIT.USAGE;
+    }
+    const version = packageVersion();
+    let failures = 0;
+    for (const host of opts.hosts) {
+        const err = installInto(host, names, version, opts.force);
+        if (err) {
+            failures += 1;
+            process.stderr.write(`❌ ${padDisplay(host.label, 16)}${err}\n`);
+            continue;
+        }
+        process.stdout.write(`✅ ${padDisplay(host.label, 16)}${host.skillsDir}（${names.length} 个 skill，${version}）\n`);
+    }
+    if (failures > 0)
+        return EXIT.ERROR;
+    // 检测到了但这一轮装不了的宿主要说出来 —— 静默跳过会让用户以为不支持。
+    if (projectOnly.length > 0 && !opts.hosts.some((h) => projectOnly.includes(h.id))) {
+        process.stdout.write(`\nℹ️  还检测到 ${projectOnly.map((id) => spec(id).label).join('、')}，` +
+            '它只有项目级 skill 目录 —— 在项目根目录里运行 remixmate install --project 即可。\n');
+    }
+    process.stdout.write('\n重启 agent 后即可生效。升级后重跑 remixmate install 覆盖即可。\n');
+    return EXIT.OK;
+}
+export function runUninstall(argv) {
+    const opts = parseArgs(argv, UNINSTALL_VERB);
+    if (opts.help) {
+        uninstallUsage();
+        return EXIT.OK;
+    }
+    if (opts.error) {
+        process.stderr.write(`❌ ${opts.error}\n`);
+        uninstallUsage();
+        return EXIT.USAGE;
+    }
+    let removed = 0;
+    for (const host of opts.hosts) {
+        const receipt = readReceipt(host.skillsDir);
+        if (!receipt)
+            continue;
+        for (const name of receipt.skills) {
+            rmSync(path.join(host.skillsDir, name), { recursive: true, force: true });
+        }
+        rmSync(path.join(host.skillsDir, RECEIPT), { force: true });
+        removed += 1;
+        process.stdout.write(`✅ ${padDisplay(host.label, 16)}已移除 ${receipt.skills.length} 个 skill（${host.skillsDir}）\n`);
+    }
+    if (removed === 0) {
+        process.stdout.write('没有找到本 CLI 的装机记录，无需卸载。\n');
+    }
+    return EXIT.OK;
+}
+/**
+ * 供 doctor 使用：每个宿主的安装状态。
+ *
+ * 漂移是这套方案唯一的静默失败模式 —— `npm update -g` 只动包，不动铺出去的副本，
+ * 用户会拿着旧 SKILL.md 打新后端。doctor 是「为什么跑不起来」的统一入口，检查放这里。
+ */
+export function installStates() {
+    const current = packageVersion();
+    return detectHosts().map((h) => {
+        const receipt = readReceipt(h.skillsDir);
+        return {
+            label: h.label,
+            skillsDir: h.skillsDir,
+            installedVersion: receipt?.version ?? null,
+            currentVersion: current,
+            drifted: receipt != null && receipt.version !== current,
+        };
+    });
+}

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.21",
-  "generatedAt": "2026-09-05T08:18:35.420Z",
+  "version": "0.9.23",
+  "generatedAt": "2026-09-06T12:35:46.901Z",
   "skills": [
     {
       "id": "export-jianying",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.21",
+  "version": "0.9.23",
   "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",