@remixmate/cli 0.9.15 → 0.9.17

package/README.md

@@ -296,7 +296,7 @@ remixmate template-registry --list-templates
 ### Quick start
 
 ```
-@skills/gen-image/SKILL.md Generate an image of a panda, 9:16, using gemini 3.1, Chinese-painting style + follow this doc strictly
+@skills/gen-image/SKILL.md Generate an image of a panda, 9:16, using gemini, Chinese-painting style + follow this doc strictly
 @skills/gen-video/SKILL.md Generate a video of a panda running in a bamboo forest, 9:16, 6 seconds, using veo + follow this doc strictly
 @skills/gen-voice/SKILL.md Generate a voiceover introducing panda habits, around 100 words + follow this doc strictly
 @skills/gen-digital-human/SKILL.md Get the digital human list + follow this doc strictly

package/README.zh-CN.md

@@ -232,7 +232,7 @@ remixmate template-registry --list-templates
 ### 快速体验
 
 ```
-@skills/gen-image/SKILL.md 生成一张熊猫的图片，9:16，调用gemini 3.1，国画风 + 严格按该文档执行
+@skills/gen-image/SKILL.md 生成一张熊猫的图片，9:16，调用gemini，国画风 + 严格按该文档执行
 @skills/gen-video/SKILL.md 生成一段熊猫在竹林奔跑的视频，9:16，长度6秒，调用veo + 严格按该文档执行
 @skills/gen-voice/SKILL.md 生成一段语音，介绍熊猫的习性，大概100字左右 + 严格按该文档执行
 @skills/gen-digital-human/SKILL.md 获取数字人列表 + 严格按该文档执行

package/dist/capabilities.d.ts

@@ -19,8 +19,12 @@ export interface ModelConstraints {
     durationDefault?: number;
     refImageMax?: number;
     sizes?: string[];
-    /** aspect-ratio → [width, height] pixel preset (Seedream). */
+    /** aspect-ratio → [width, height] pixel preset (Seedream). Per model: the same
+     *  ratio maps to different pixels on different Seedream variants. */
     sizePresets?: Record<string, [number, number]>;
+    /** total-pixel bounds (width × height); the backend rescales sizes outside them. */
+    pixelMin?: number;
+    pixelMax?: number;
 }
 export interface ModelDescriptor {
     id: string;

package/dist/cli.js

@@ -15,6 +15,7 @@ import { loadSkills, SKILLS_DIR } from './registry.js';
 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 { runExec } from './exec.js';
 import { authStatusLine, runDoctor } from './doctor.js';
 import { padDisplay } from './text.js';
@@ -56,6 +57,10 @@ function printUsage() {
     process.stdout.write('  remixmate logout                      Remove stored credentials\n');
     process.stdout.write('  remixmate whoami                      Show the current identity\n');
     process.stdout.write('  remixmate exec -- <cmd> [args...]     Run a command with credentials injected\n');
+    process.stdout.write('  remixmate project list                List your projects\n');
+    process.stdout.write('  remixmate project use <prj> [--global]  Bind output to a project (this dir, or globally)\n');
+    process.stdout.write('  remixmate project show                Show the current project binding\n');
+    process.stdout.write('  remixmate host probe                  Diagnose host detection and take grouping\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');
@@ -132,6 +137,13 @@ async function main() {
         const code = await runAuthCommand(argv[0], argv.slice(1));
         process.exit(code);
     }
+    // Project / host verbs, like the auth verbs, are resolved before skill dispatch.
+    if (argv[0] === PROJECT_VERB) {
+        process.exit(await runProjectCommand(argv.slice(1)));
+    }
+    if (argv[0] === HOST_VERB) {
+        process.exit(await runHostCommand(argv.slice(1)));
+    }
     if (argv[0] === 'exec') {
         // Raw argv (not parsed) — everything after `--` belongs to the child command.
         const code = await runExec(argv.slice(1));

package/dist/doctor.js

@@ -17,6 +17,8 @@ import { resolveApiBaseUrl } from './http.js';
 import { EXIT } from './errors.js';
 import { resolvePrivToken } from './auth/resolve.js';
 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 { padDisplay } from './text.js';
 /**
@@ -98,6 +100,25 @@ export async function runDoctor(opts = {}) {
         detail: playwright ?? '当前解释器下未安装 —— 仅 web-screenshot / web-record 需要，首次运行会自动装',
     });
     checks.push({ name: '后端地址', status: 'ok', detail: apiBaseUrl });
+    // 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.
+    const binding = await readBinding(apiBaseUrl);
+    checks.push({
+        name: '项目归属',
+        status: 'ok',
+        detail: binding
+            ? `${binding.projectId}（${binding.scope === 'path' ? '目录绑定' : '全局绑定'}）`
+            : '未绑定 → 产物落进默认项目「未分类」（remixmate project use <prj> 可改）',
+    });
+    const take = resolveTakeKey(undefined);
+    checks.push({
+        name: 'take 分组',
+        status: take.source === 'none' ? 'warn' : 'ok',
+        detail: take.source === 'none'
+            ? '宿主未提供会话 ID —— 每次渲染各自成为一个 take。可 export REMIXMATE_TAKE_KEY 手动分组，详见 remixmate host probe'
+            : `${take.key}（宿主：${take.host || 'unknown'}，来源：${take.source}）`,
+    });
     const resolved = await resolvePrivToken({ apiBaseUrl });
     const stored = await listCredentials();
     if (resolved) {

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.15",
-  "generatedAt": "2026-08-14T08:23:17.130Z",
+  "version": "0.9.17",
+  "generatedAt": "2026-08-29T15:20:08.872Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -54,7 +54,7 @@
       "tier": "atomic",
       "category": "asset",
       "title": "AI Image Generation",
-      "summary": "AI image generation: produce an image from a text prompt. Supports Seedream and Gemini models, plus image-to-image with reference images.",
+      "summary": "AI image generation: produce an image from a text prompt. Supports the Seedream family (including a high-fidelity 'pro' variant) and Gemini, plus image-to-image with reference images.",
       "triggers": [
         "AI image generation, text-to-image, \"draw me ...\", \"generate an image of ...\"",
         "Image-to-image, reference image, style transfer, image variation",
@@ -247,11 +247,11 @@
       "title": "Web Page Recording",
       "summary": "Drive a headless browser (Playwright Python) to RECORD any URL to a video, then (by default) transcode to mp4, grab a cover frame, upload to VOD and return a playable CDN URL. Modes: fixed-duration recording, condition-triggered stop (element appears / disappears), auto-scroll from top to bottom, custom storyboards, and parameterized templates. Storyboard scenes: highlight / focus / zoom / scroll / virtual-cursor click / type / hover / caption / title-card / arrow / numbered sequence / redact / code-line highlight. For still images (png/jpg) use the web_screenshot tool instead. Use this tool whenever the user wants a video / recording / screencast of a web page: record a page, scroll-through video, page-from-top-to-bottom clip, demo of clicks/typing/hover, storyboard / multi-scene intro video, or a template-based clip.",
       "triggers": [
-        "录屏、网页录制、录制视频、录一段操作、生成 webm、screencast",
-        "滚动录屏、页面从头划到尾的视频",
-        "多场景视频、分镜视频、storyboard、按时间线编排",
-        "演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）",
-        "模板视频一行出片、按顺序编号高亮多个区域并录制"
+        "Screen recording, record a web page, record a video, capture an interaction, produce a webm, screencast",
+        "Scroll recording, a video that pans the page from top to bottom",
+        "Multi-scene video, storyboard video, timeline-sequenced clips",
+        "Animated demos of clicks / typing / hover (virtual cursor + ripple / typewriter / triggering tooltips)",
+        "One-command template clips, numbering and highlighting several regions in sequence and recording it"
       ],
       "entry": {
         "type": "python",
@@ -275,11 +275,11 @@
       "title": "Web Page Screenshot",
       "summary": "Drive a headless browser (Playwright Python) to capture any URL to a local STILL IMAGE (png/jpg): full-page / viewport / element / region screenshots, with device emulation, waiting, hide/mask/redact, and static annotations (highlight / arrow / caption / numbered sequence / redact). Images only — for video / recording / scroll-through / storyboard clips (webm) use the web_record tool instead.",
       "triggers": [
-        "网页截图、网页截屏、整页截图、长截图、full page screenshot",
-        "截某个元素 / 区域、局部截屏、focus 某个区域",
-        "截图前隐藏元素 / 涂盖打码、给静态截图加注释（红框 / 箭头 / 标签）",
-        "高亮某文件的 L5-L20 代码行并截图",
-        "移动端 / 设备模拟截图、带 cookie / 登录态截图"
+        "Web page screenshot, screen capture, full-page screenshot, long screenshot",
+        "Capture a specific element / region, partial screenshot, focus on an area",
+        "Hide or mask elements before capturing, annotate a still screenshot (highlight box / arrow / label)",
+        "Highlight lines L5-L20 of a file and screenshot it",
+        "Mobile / device-emulated screenshot, capture with cookies / a logged-in session"
       ],
       "entry": {
         "type": "python",

package/dist/project/commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `remixmate project ...` and `remixmate host probe`.
+ *
+ * `project use` is the low-friction way to keep CLI output out of 「未分类」:
+ * say it once per repo (or once globally) instead of passing --project on every
+ * call — an agent won't pass a flag it wasn't told about.
+ *
+ * `host probe` exists so onboarding an unknown agent shell is a minute's work
+ * rather than a reverse-engineering session: run it inside the new host, read
+ * off the session variable, add one row to HOST_PROVIDERS.
+ */
+export declare const PROJECT_VERB = "project";
+export declare const HOST_VERB = "host";
+export declare function runProjectCommand(argv: string[]): Promise<number>;
+/**
+ * Report what the CLI can see about its host. Prints variable NAMES only —
+ * an environment dump is a routine way to leak tokens into a chat transcript.
+ */
+export declare function runHostCommand(argv: string[]): Promise<number>;

package/dist/project/commands.js

@@ -0,0 +1,156 @@
+/**
+ * `remixmate project ...` and `remixmate host probe`.
+ *
+ * `project use` is the low-friction way to keep CLI output out of 「未分类」:
+ * say it once per repo (or once globally) instead of passing --project on every
+ * call — an agent won't pass a flag it wasn't told about.
+ *
+ * `host probe` exists so onboarding an unknown agent shell is a minute's work
+ * rather than a reverse-engineering session: run it inside the new host, read
+ * off the session variable, add one row to HOST_PROVIDERS.
+ */
+import { EXIT, SkillError } from '../errors.js';
+import { resolveApiBaseUrl, resolveHttpContext } from '../http.js';
+import { detectHostLabel, probeSessionVarNames, resolveTakeKey } from './host.js';
+import { fetchDefaultProject, listProjects } from './resolve.js';
+import { clearBinding, readBinding, writeBinding, PROJECTS_FILE } from './store.js';
+export const PROJECT_VERB = 'project';
+export const HOST_VERB = 'host';
+function projectLabel(p) {
+    return p.displayName || p.fullName || p.sourceUrl || '(未命名)';
+}
+async function ctxFor(sub) {
+    return await resolveHttpContext(`project-${sub}`);
+}
+async function cmdList() {
+    const ctx = await ctxFor('list');
+    const projects = await listProjects(ctx);
+    if (projects.length === 0) {
+        process.stdout.write('（还没有项目。渲染一次即可自动创建「未分类」）\n');
+        return EXIT.OK;
+    }
+    const bound = await readBinding(ctx.apiBaseUrl);
+    for (const p of projects) {
+        const marks = [p.isDefault ? '默认' : '', bound?.projectId === p.id ? '← 当前绑定' : '']
+            .filter(Boolean)
+            .join(' ');
+        process.stdout.write(`  ${p.id.padEnd(20)} ${projectLabel(p)}${marks ? `  ${marks}` : ''}\n`);
+    }
+    return EXIT.OK;
+}
+async function cmdUse(args) {
+    const global = args.includes('--global');
+    const projectId = args.find((a) => !a.startsWith('-'));
+    if (!projectId) {
+        process.stderr.write('用法: remixmate project use <prj_xxx> [--global]\n');
+        return EXIT.USAGE;
+    }
+    const ctx = await ctxFor('use');
+    // Verify before persisting: a typo'd uid would otherwise sit in the config and
+    // silently send every later render to the default project.
+    const projects = await listProjects(ctx);
+    const match = projects.find((p) => p.id === projectId);
+    if (!match) {
+        process.stderr.write(`❌ 项目不存在或不属于当前账号: ${projectId}\n   用 remixmate project list 查看可用项目。\n`);
+        return EXIT.USAGE;
+    }
+    await writeBinding(ctx.apiBaseUrl, projectId, global ? 'default' : 'path');
+    const scopeText = global ? '全局默认' : `当前目录 (${process.cwd()})`;
+    process.stdout.write(`✅ 已绑定到 ${projectLabel(match)} [${projectId}]\n   作用域: ${scopeText}\n`);
+    if (!global) {
+        // Not a hypothetical: WorkBuddy spawns ~/WorkBuddy/<timestamp> per conversation,
+        // so a path binding made there is gone by the next conversation.
+        process.stdout.write('   提示: 若宿主每次会话都换工作目录，请改用 --global。\n');
+    }
+    return EXIT.OK;
+}
+async function cmdUnuse(args) {
+    const global = args.includes('--global');
+    const apiBaseUrl = resolveApiBaseUrl();
+    const removed = await clearBinding(apiBaseUrl, global ? 'default' : 'path');
+    process.stdout.write(removed ? '✅ 绑定已清除\n' : 'ℹ️  没有可清除的绑定\n');
+    return EXIT.OK;
+}
+async function cmdShow() {
+    const apiBaseUrl = resolveApiBaseUrl();
+    const bound = await readBinding(apiBaseUrl);
+    process.stdout.write(`后端:     ${apiBaseUrl}\n`);
+    process.stdout.write(`配置文件: ${PROJECTS_FILE}\n`);
+    if (bound) {
+        const scope = bound.scope === 'path' ? `目录绑定 (${process.cwd()})` : '全局默认绑定';
+        process.stdout.write(`绑定项目: ${bound.projectId}  [${scope}]\n`);
+    }
+    else {
+        process.stdout.write('绑定项目: (无) — 产物会落进默认项目「未分类」\n');
+    }
+    const envOverride = (process.env.REMIXMATE_PROJECT_ID ?? '').trim();
+    if (envOverride) {
+        process.stdout.write(`⚠️  REMIXMATE_PROJECT_ID=${envOverride} 会覆盖上面的绑定\n`);
+    }
+    return EXIT.OK;
+}
+async function cmdDefault() {
+    const ctx = await ctxFor('default');
+    const p = await fetchDefaultProject(ctx);
+    process.stdout.write(`${p.id}  ${projectLabel(p)}\n`);
+    return EXIT.OK;
+}
+export async function runProjectCommand(argv) {
+    const sub = argv[0] ?? 'show';
+    try {
+        switch (sub) {
+            case 'list':
+                return await cmdList();
+            case 'use':
+                return await cmdUse(argv.slice(1));
+            case 'unuse':
+                return await cmdUnuse(argv.slice(1));
+            case 'show':
+                return await cmdShow();
+            case 'default':
+                return await cmdDefault();
+            default:
+                process.stderr.write(`❌ 未知子命令: ${sub}\n用法: remixmate project <list|use|unuse|show|default>\n`);
+                return EXIT.USAGE;
+        }
+    }
+    catch (err) {
+        if (err instanceof SkillError) {
+            process.stderr.write(err.message + '\n');
+            return err.exitCode;
+        }
+        process.stderr.write(`❌ ${err.message}\n`);
+        return EXIT.ERROR;
+    }
+}
+/**
+ * Report what the CLI can see about its host. Prints variable NAMES only —
+ * an environment dump is a routine way to leak tokens into a chat transcript.
+ */
+export async function runHostCommand(argv) {
+    const sub = argv[0] ?? 'probe';
+    if (sub !== 'probe') {
+        process.stderr.write(`❌ 未知子命令: ${sub}\n用法: remixmate host probe\n`);
+        return EXIT.USAGE;
+    }
+    const host = detectHostLabel();
+    const take = resolveTakeKey(undefined);
+    process.stdout.write(`识别宿主: ${host || '(未识别)'}\n`);
+    process.stdout.write(`分组键:   ${take.key || '(无 — 每次渲染会各自成为一个 take)'}\n`);
+    process.stdout.write(`来源:     ${take.source}\n`);
+    const names = probeSessionVarNames();
+    process.stdout.write('\n环境里疑似会话标识的变量（仅名称，不含取值）:\n');
+    if (names.length === 0) {
+        process.stdout.write('  (无)\n');
+    }
+    else {
+        for (const n of names)
+            process.stdout.write(`  ${n}\n`);
+    }
+    if (!host && names.length > 0) {
+        process.stdout.write('\n宿主未被识别。若上面某个变量在整个会话期间保持不变，可以:\n' +
+            '  1) 临时方案: export REMIXMATE_TAKE_KEY="$该变量"\n' +
+            '  2) 长期方案: 在 src/project/host.ts 的 HOST_PROVIDERS 里加一行\n');
+    }
+    return EXIT.OK;
+}

package/dist/project/host.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Host detection — which agent shell is this CLI running inside, and what is
+ * its conversation id?
+ *
+ * The id is used as the *grouping key* for takes: every render fired from the
+ * same host conversation lands in one VideoProject as successive takes. The
+ * creative loop ("generate → watch → shorten the intro → re-render") spans
+ * multiple skill invocations and multiple render jobs, so the conversation —
+ * not the render job — is its natural boundary.
+ *
+ * Everything here reads the **child process environment only**. We deliberately
+ * do not speak any host's private IPC (Codex exposes its thread id through an
+ * App Server JSON-RPC channel, and finding "the current thread" there means
+ * matching on cwd + status + recency — a heuristic, not an identity lookup,
+ * which would silently group takes wrong). A host that hands us nothing simply
+ * degrades one rung; see resolveTakeKey().
+ *
+ * See docs/cli-project-binding-design.md §5.1 and appendix A.
+ */
+export interface HostSessionProvider {
+    /** Host identifier; becomes the namespace of the grouping key. */
+    host: string;
+    /** First provider whose detect() passes wins — ORDER MATTERS, see below. */
+    detect: (env: NodeJS.ProcessEnv) => boolean;
+    /** Session-level id candidates, most-preferred first. */
+    sessionVars: string[];
+}
+/**
+ * Adding a host is a data-only change: append a row, touch nothing else.
+ * Run `remixmate host probe` inside the new host to discover its variable names.
+ *
+ * ⚠️ ORDER IS LOAD-BEARING. CodeBuddy also sets `CLAUDE_SESSION_ID` (same value
+ * as its own id), while real Claude Code uses the longer `CLAUDE_CODE_*` prefix.
+ * Detecting Claude Code first — or matching on a bare `CLAUDE_` prefix — would
+ * mislabel every CodeBuddy session.
+ *
+ * ⚠️ Prefer the ROOT session over a child/sub-agent one. Claude Code exposes
+ * both (`CLAUDE_CODE_HOST_SESSION_ID` alongside a per-subagent
+ * `CLAUDE_CODE_SESSION_ID`); grouping must follow the root so a render fired
+ * from a subagent still joins the main take.
+ */
+export declare const HOST_PROVIDERS: HostSessionProvider[];
+export interface HostSession {
+    host: string;
+    sessionId: string;
+}
+/** Identify the host and its root session id, or null when unrecognised. */
+export declare function detectHostSession(env?: NodeJS.ProcessEnv): HostSession | null;
+/** Host label for provenance, even when no session id could be read. */
+export declare function detectHostLabel(env?: NodeJS.ProcessEnv): string;
+export interface TakeKey {
+    /** `<host>:<sessionId>`, or '' when nothing groups this invocation. */
+    key: string;
+    host: string;
+    /** Which rung produced the key — surfaced by `doctor` / `host probe`. */
+    source: 'host' | 'env-override' | 'render-job' | 'none';
+}
+/**
+ * Resolve the take grouping key.
+ *
+ *   1. a recognised host's root session id      → "<host>:<id>"
+ *   2. REMIXMATE_TAKE_KEY                       → "custom:<value>"
+ *   3. the render job id                        → "job:<id>"
+ *
+ * Rung 2 is the escape hatch that matters: an unsupported host (or a user on
+ * Codex) can export one variable and get correct grouping without waiting for a
+ * CLI release. Rung 3 keeps the feature working everywhere, at the cost of
+ * splitting one video's iterations across takes — acceptable as a floor, not as
+ * a default.
+ */
+export declare function resolveTakeKey(jobId: number | undefined, env?: NodeJS.ProcessEnv): TakeKey;
+/**
+ * Environment variable names that look like a session/thread identifier.
+ * Used by `remixmate host probe` to onboard an unknown host in a minute.
+ * Returns NAMES ONLY — values may carry tokens and are never printed.
+ */
+export declare function probeSessionVarNames(env?: NodeJS.ProcessEnv): string[];

package/dist/project/host.js

@@ -0,0 +1,106 @@
+/**
+ * Host detection — which agent shell is this CLI running inside, and what is
+ * its conversation id?
+ *
+ * The id is used as the *grouping key* for takes: every render fired from the
+ * same host conversation lands in one VideoProject as successive takes. The
+ * creative loop ("generate → watch → shorten the intro → re-render") spans
+ * multiple skill invocations and multiple render jobs, so the conversation —
+ * not the render job — is its natural boundary.
+ *
+ * Everything here reads the **child process environment only**. We deliberately
+ * do not speak any host's private IPC (Codex exposes its thread id through an
+ * App Server JSON-RPC channel, and finding "the current thread" there means
+ * matching on cwd + status + recency — a heuristic, not an identity lookup,
+ * which would silently group takes wrong). A host that hands us nothing simply
+ * degrades one rung; see resolveTakeKey().
+ *
+ * See docs/cli-project-binding-design.md §5.1 and appendix A.
+ */
+/**
+ * Adding a host is a data-only change: append a row, touch nothing else.
+ * Run `remixmate host probe` inside the new host to discover its variable names.
+ *
+ * ⚠️ ORDER IS LOAD-BEARING. CodeBuddy also sets `CLAUDE_SESSION_ID` (same value
+ * as its own id), while real Claude Code uses the longer `CLAUDE_CODE_*` prefix.
+ * Detecting Claude Code first — or matching on a bare `CLAUDE_` prefix — would
+ * mislabel every CodeBuddy session.
+ *
+ * ⚠️ Prefer the ROOT session over a child/sub-agent one. Claude Code exposes
+ * both (`CLAUDE_CODE_HOST_SESSION_ID` alongside a per-subagent
+ * `CLAUDE_CODE_SESSION_ID`); grouping must follow the root so a render fired
+ * from a subagent still joins the main take.
+ */
+export const HOST_PROVIDERS = [
+    {
+        host: 'codebuddy',
+        detect: (e) => !!e.CODEBUDDY_SESSION_ID || e.CODEBUDDY_HOST != null,
+        sessionVars: ['CODEBUDDY_SESSION_ID'],
+    },
+    {
+        host: 'claude-code',
+        detect: (e) => e.CLAUDECODE === '1' || !!e.CLAUDE_CODE_SESSION_ID,
+        sessionVars: ['CLAUDE_CODE_HOST_SESSION_ID', 'CLAUDE_CODE_SESSION_ID'],
+    },
+    // Untested placeholders — verify with `remixmate host probe` before trusting.
+    { host: 'qoder', detect: (e) => !!e.QODER_SESSION_ID, sessionVars: ['QODER_SESSION_ID'] },
+    { host: 'trae', detect: (e) => !!e.TRAE_SESSION_ID, sessionVars: ['TRAE_SESSION_ID'] },
+];
+/** Identify the host and its root session id, or null when unrecognised. */
+export function detectHostSession(env = process.env) {
+    for (const provider of HOST_PROVIDERS) {
+        if (!provider.detect(env))
+            continue;
+        for (const name of provider.sessionVars) {
+            const value = (env[name] ?? '').trim();
+            if (value)
+                return { host: provider.host, sessionId: value };
+        }
+        // Recognised the host but it gave us no id — don't fall through to a later
+        // provider, that would mislabel. Report the host, leave grouping to a lower rung.
+        return null;
+    }
+    return null;
+}
+/** Host label for provenance, even when no session id could be read. */
+export function detectHostLabel(env = process.env) {
+    return HOST_PROVIDERS.find((p) => p.detect(env))?.host ?? '';
+}
+/**
+ * Resolve the take grouping key.
+ *
+ *   1. a recognised host's root session id      → "<host>:<id>"
+ *   2. REMIXMATE_TAKE_KEY                       → "custom:<value>"
+ *   3. the render job id                        → "job:<id>"
+ *
+ * Rung 2 is the escape hatch that matters: an unsupported host (or a user on
+ * Codex) can export one variable and get correct grouping without waiting for a
+ * CLI release. Rung 3 keeps the feature working everywhere, at the cost of
+ * splitting one video's iterations across takes — acceptable as a floor, not as
+ * a default.
+ */
+export function resolveTakeKey(jobId, env = process.env) {
+    const host = detectHostLabel(env);
+    const detected = detectHostSession(env);
+    if (detected) {
+        return { key: `${detected.host}:${detected.sessionId}`, host: detected.host, source: 'host' };
+    }
+    const override = (env.REMIXMATE_TAKE_KEY ?? '').trim();
+    if (override)
+        return { key: `custom:${override}`, host, source: 'env-override' };
+    if (jobId && jobId > 0)
+        return { key: `job:${jobId}`, host, source: 'render-job' };
+    return { key: '', host, source: 'none' };
+}
+/**
+ * Environment variable names that look like a session/thread identifier.
+ * Used by `remixmate host probe` to onboard an unknown host in a minute.
+ * Returns NAMES ONLY — values may carry tokens and are never printed.
+ */
+export function probeSessionVarNames(env = process.env) {
+    const interesting = /(SESSION|THREAD|CONVERSATION|CHAT|TASK)/i;
+    const secretish = /(TOKEN|KEY|SECRET|AUTH|PASSWORD|COOKIE|CREDENTIAL)/i;
+    return Object.keys(env)
+        .filter((name) => interesting.test(name) && !secretish.test(name))
+        .sort();
+}

package/dist/project/resolve.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Project resolution ladder — which Project does this invocation's output
+ * belong to? First rung that matches wins.
+ *
+ *   0. CONVERSATION_ID already set  → do nothing at all (cloud ab-agent path)
+ *   1. --project prj_xxx            → explicit flag
+ *   2. REMIXMATE_PROJECT_ID         → explicit env
+ *   3. ~/.config/remixmate/projects.json → `project use` binding (byPath → default)
+ *   4. the default project 「未分类」 → lazily created server-side
+ *
+ * Only "explicit" and "fallback" — there is deliberately no inference step in
+ * between. Deriving a project from the git remote reads well until you notice
+ * it *creates* one on every unfamiliar repo (`/project/create` is an upsert),
+ * and that its rules have to keep growing for private remotes, non-GitHub
+ * remotes, monorepos and repos with no origin — each misfire silently filing
+ * output under a project the user never made.
+ *
+ * See docs/cli-project-binding-design.md §3.
+ */
+import { type HttpContext } from '../http.js';
+export interface ResolvedProject {
+    projectId: string;
+    source: 'flag' | 'env' | 'binding-path' | 'binding-default' | 'default-project';
+}
+/** Minimal shape of ab-api's ProjectVO — only what the ladder needs. */
+export interface ProjectSummary {
+    id: string;
+    displayName?: string;
+    fullName?: string;
+    sourceUrl?: string;
+    isDefault?: boolean;
+}
+/** POST /project/default — get-or-lazily-create 「未分类」. */
+export declare function fetchDefaultProject(ctx: HttpContext): Promise<ProjectSummary>;
+/** POST /project/list — for `remixmate project list`. */
+export declare function listProjects(ctx: HttpContext): Promise<ProjectSummary[]>;
+export declare function resolveProject(ctx: HttpContext, opts?: {
+    flagProjectId?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}): Promise<ResolvedProject>;
+/** Human-readable label for `doctor` / `project show`. */
+export declare function describeProjectSource(source: ResolvedProject['source']): string;

package/dist/project/resolve.js

@@ -0,0 +1,65 @@
+/**
+ * Project resolution ladder — which Project does this invocation's output
+ * belong to? First rung that matches wins.
+ *
+ *   0. CONVERSATION_ID already set  → do nothing at all (cloud ab-agent path)
+ *   1. --project prj_xxx            → explicit flag
+ *   2. REMIXMATE_PROJECT_ID         → explicit env
+ *   3. ~/.config/remixmate/projects.json → `project use` binding (byPath → default)
+ *   4. the default project 「未分类」 → lazily created server-side
+ *
+ * Only "explicit" and "fallback" — there is deliberately no inference step in
+ * between. Deriving a project from the git remote reads well until you notice
+ * it *creates* one on every unfamiliar repo (`/project/create` is an upsert),
+ * and that its rules have to keep growing for private remotes, non-GitHub
+ * remotes, monorepos and repos with no origin — each misfire silently filing
+ * output under a project the user never made.
+ *
+ * See docs/cli-project-binding-design.md §3.
+ */
+import { mmPost } from '../http.js';
+import { readBinding } from './store.js';
+/** POST /project/default — get-or-lazily-create 「未分类」. */
+export async function fetchDefaultProject(ctx) {
+    return await mmPost(ctx, '/project/default', {});
+}
+/** POST /project/list — for `remixmate project list`. */
+export async function listProjects(ctx) {
+    const data = await mmPost(ctx, '/project/list', {});
+    if (Array.isArray(data))
+        return data;
+    return data?.list ?? [];
+}
+export async function resolveProject(ctx, opts = {}) {
+    const env = opts.env ?? process.env;
+    const flag = (opts.flagProjectId ?? '').trim();
+    if (flag)
+        return { projectId: flag, source: 'flag' };
+    const fromEnv = (env.REMIXMATE_PROJECT_ID ?? '').trim();
+    if (fromEnv)
+        return { projectId: fromEnv, source: 'env' };
+    const bound = await readBinding(ctx.apiBaseUrl, opts.cwd);
+    if (bound) {
+        return {
+            projectId: bound.projectId,
+            source: bound.scope === 'path' ? 'binding-path' : 'binding-default',
+        };
+    }
+    const fallback = await fetchDefaultProject(ctx);
+    return { projectId: fallback.id, source: 'default-project' };
+}
+/** Human-readable label for `doctor` / `project show`. */
+export function describeProjectSource(source) {
+    switch (source) {
+        case 'flag':
+            return '--project 参数';
+        case 'env':
+            return 'REMIXMATE_PROJECT_ID 环境变量';
+        case 'binding-path':
+            return `${process.cwd()} 的目录绑定`;
+        case 'binding-default':
+            return '全局默认绑定';
+        case 'default-project':
+            return '默认项目「未分类」';
+    }
+}