@soulspacex/cli 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @soulspacex/cli
+
+让 AI Agent 直接在 SoulSpaceX 的画布上创作：建节点、连线、生成图片和视频，产物自动落回画布。
+
+```bash
+npx @soulspacex/cli login
+```
+
+不用先安装——`npx` 直接跑。要常驻就 `npm i -g @soulspacex/cli`，命令名是 `ssx`。
+
+## 五分钟跑通
+
+```bash
+ssx login                                  # 浏览器授权这台设备
+ssx workflow create "短剧第一集"             # 建画布，自动绑定到当前目录
+
+ssx node create "剧本" -t textNode \
+    --prompt "写一段赛博朋克短剧的开场" \
+    --set llmModelId=3 --run                # 建完立刻生成，阻塞到出结果
+
+ssx node create "主视觉" -t imageNode \
+    --left 剧本 --set imageModelId=4 --run   # --left 接上游，剧本的输出成为它的提示词
+
+ssx node list                              # 看看都生成完了没
+```
+
+最后一步之后，画布链接就在输出里，用户在网页上打开能继续编辑。
+
+## 给 Agent 的几条硬约定
+
+- **结果走 stdout（JSON），进度和提示走 stderr。** 可以放心 `ssx node list | jq`。
+- **`status` / `result` / `assetId` 这类字段由生成结果回写，不要自己设**，服务端会拒。拼 `--set` 之前先跑 `ssx schema` 看有哪些字段可以设。
+- **生成默认阻塞到出结果**（最长 55 秒）。不要自己写 while 循环轮询——每轮一次都是一次模型调用，token 是用户在付。要立刻返回就 `--wait 0`。
+- **节点可以用名字指代**，重名时才需要用 id。
+- **命令行创作按积分计费，不使用无限模式额度。**
+
+## 命令
+
+跑 `ssx --help` 看全部。常用的：
+
+| 命令 | 作用 |
+| --- | --- |
+| `ssx login` / `logout` / `whoami` | 授权、登出（连带吊销服务端授权）、看余额 |
+| `ssx workflow create/list/use/show` | 画布 |
+| `ssx node create/list/update/run/delete` | 节点 |
+| `ssx node connect/disconnect`、`update --left` | 连线（`--left` 是「入边就是这些」，重跑幂等） |
+| `ssx generate <kind> --model <名> --prompt <描述>` | 不走画布的一次性生成 |
+| `ssx model list` / `ssx model search <词>` | 可用模型与计价 |
+| `ssx schema` | 节点字段契约 |
+| `ssx upload <文件>` / `ssx download <url>` | 素材进出 |
+
+## 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `SOULSPACEX_API_KEY` | 直接给凭据。CI 与容器里没法交互登录，用它代替 `ssx login` |
+| `SOULSPACEX_BASE_URL` | 服务地址，默认 `https://soulspacex.com` |
+| `SOULSPACEX_CONFIG_DIR` | 凭据目录，默认 `~/.soulspacex` |
+
+## 本地状态
+
+- `~/.soulspacex/credentials`（0600）——凭据，跟人走。
+- `<项目>/.soulspacex/workflow.json`——画布绑定，跟目录走，会像 git 那样逐级向上找。
+
+## 谁能用
+
+订阅卡、会员、无限模式用户。成员（子）账号不支持。会员过期后凭据即失效，续费后同一把凭据自动恢复，不用重新授权。
+
+一个账号同时只保留一台授权设备，新设备授权会让旧设备失效。

package/dist/api.js

@@ -0,0 +1,75 @@
+import { baseUrl, readApiKey } from './config.js';
+import { fail } from './output.js';
+export async function request(method, path, init = {}) {
+    const { body, auth = true, formData } = init;
+    const headers = {};
+    if (auth) {
+        const key = readApiKey();
+        if (!key) {
+            fail('尚未登录', '执行 ssx login 完成授权，或设置环境变量 SOULSPACEX_API_KEY');
+        }
+        headers.Authorization = `Bearer ${key}`;
+    }
+    if (body !== undefined && !formData) {
+        headers['Content-Type'] = 'application/json';
+    }
+    let res;
+    try {
+        res = await fetch(baseUrl() + path, {
+            method,
+            headers,
+            body: formData ?? (body === undefined ? undefined : JSON.stringify(body)),
+        });
+    }
+    catch (e) {
+        return fail(`连不上 ${baseUrl()}：${e.message}`, '检查网络，或用 SOULSPACEX_BASE_URL 指定服务地址');
+    }
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // 最常见的原因是 Nginx 没配 /openapi/ 的 location，请求落到了前端，返回一坨 HTML。
+        // 直接把「JSON 解析失败」抛给用户完全指不到这个原因，所以在这里点破。
+        return fail(`服务端返回的不是 JSON（HTTP ${res.status}）`, `请确认 ${baseUrl()} 是 SoulSpaceX 的服务地址，且 /openapi/ 已正确反代`);
+    }
+    if (!parsed.success) {
+        return fail(parsed.message || `请求失败（${parsed.code}）`);
+    }
+    return parsed.data;
+}
+/**
+ * 失败不退出的变体，返回 null。
+ *
+ * {@link request} 遇到业务错误会直接 `process.exit(1)`——那是对的，命令失败就该
+ * 用非零退出码告诉 agent。但有一种情况相反：`ssx logout` 里吊销服务端 key 失败了，
+ * **本地凭据仍然必须删掉**，否则用户敲了登出、钥匙却还留在这台机器上。
+ * 那种「尽力而为」的调用走这个。
+ */
+export async function requestSoft(method, path) {
+    const key = readApiKey();
+    if (!key)
+        return false;
+    try {
+        const res = await fetch(baseUrl() + path, {
+            method,
+            headers: { Authorization: `Bearer ${key}` },
+        });
+        if (!res.ok)
+            return false;
+        // 只看 success 标志，不看 data：吊销这类接口成功时 data 本来就是 null，
+        // 拿 data 判成败会把每一次成功都读成失败
+        const parsed = JSON.parse(await res.text());
+        return parsed.success === true;
+    }
+    catch {
+        return false;
+    }
+}
+export const api = {
+    get: (path) => request('GET', path),
+    post: (path, body) => request('POST', path, { body }),
+    postPublic: (path, body) => request('POST', path, { body, auth: false }),
+    upload: (path, formData) => request('POST', path, { formData }),
+};

package/dist/args.js

@@ -0,0 +1,97 @@
+/**
+ * 极小的参数解析。没用 commander 之类的库是为了保持零运行时依赖——
+ * `npx @soulspacex/cli` 每次冷启动都要下载整棵依赖树，少一个包就快一点，
+ * 而 CLI 要解析的东西就这么多。
+ */
+/** 允许重复出现、需要保留顺序的选项。其余重复出现时后者覆盖前者。 */
+const REPEATABLE = new Set(['set', 'update', 'left', 'left-add', 'left-rm', 'right', 'ref']);
+export function parseArgs(argv) {
+    const positional = [];
+    const options = {};
+    const repeated = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('-')) {
+            positional.push(arg);
+            continue;
+        }
+        const raw = arg.startsWith('--') ? arg.slice(2) : arg.slice(1);
+        // 支持 --key=value 与 --key value 两种写法：agent 两种都会写
+        const eq = raw.indexOf('=');
+        let key = eq >= 0 ? raw.slice(0, eq) : raw;
+        let value = eq >= 0 ? raw.slice(eq + 1) : true;
+        if (value === true) {
+            const next = argv[i + 1];
+            // 下一个不是选项就当成值。`--wait` 这种纯开关后面往往直接跟位置参数，
+            // 所以只在下一项不以 - 开头、且当前 key 不在已知开关表里时才吃掉它
+            if (next !== undefined && !next.startsWith('-') && !SWITCHES.has(key)) {
+                value = next;
+                i++;
+            }
+        }
+        key = ALIASES[key] ?? key;
+        if (REPEATABLE.has(key)) {
+            ;
+            (repeated[key] ??= []).push(String(value));
+        }
+        else {
+            options[key] = value;
+        }
+    }
+    return { positional, options, repeated };
+}
+/**
+ * 纯开关，后面跟的东西不属于它。
+ *
+ * `wait` 刻意不在这里：`--wait 0`（立刻返回，不阻塞）是文档里写明的用法，
+ * 归进开关会把 0 解析成 true，等于永远按默认时长阻塞。
+ */
+const SWITCHES = new Set(['run', 'json', 'help', 'version', 'open', 'force']);
+const ALIASES = {
+    t: 'type',
+    s: 'set',
+    u: 'update',
+    f: 'file',
+    n: 'name',
+    p: 'project',
+    w: 'workflow',
+    m: 'model',
+    o: 'output',
+    h: 'help',
+    v: 'version',
+};
+/** `k=v` 拆成键值对，值按 JSON 猜类型（数字/布尔/数组保持原类型，其余当字符串）。 */
+export function parseKeyValues(pairs) {
+    const out = {};
+    for (const pair of pairs ?? []) {
+        const eq = pair.indexOf('=');
+        if (eq < 0)
+            continue;
+        const key = pair.slice(0, eq);
+        const raw = pair.slice(eq + 1);
+        out[key] = coerce(raw);
+    }
+    return out;
+}
+/**
+ * 把命令行上的字符串还原成合适的类型。
+ * `count=2` 要变成数字 2 而不是字符串 "2"——后端的严格档会按 schema 校验类型，
+ * 传字符串会被指名道姓地拒掉。
+ */
+function coerce(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (raw !== '' && !Number.isNaN(Number(raw)))
+        return Number(raw);
+    if (raw.startsWith('[') || raw.startsWith('{')) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return raw;
+}

package/dist/commands/login.js

@@ -0,0 +1,84 @@
+import { execFile } from 'node:child_process';
+import { api, requestSoft } from '../api.js';
+import { baseUrl, clearApiKey, credentialsPath, readApiKey, writeApiKey } from '../config.js';
+import { emit, fail, log } from '../output.js';
+/**
+ * 设备码登录。
+ *
+ * 为什么不是「浏览器登录后回调 localhost」：agent 经常跑在 SSH 会话、Docker、CI 里，
+ * 既没有浏览器也没有可绑的回环端口。设备码把两端解耦，这边只需要能发 HTTP 出去。
+ */
+export async function login(parsed) {
+    const code = await api.postPublic('/openapi/device/code', {
+        clientName: clientName(),
+    });
+    const url = `${code.verificationUri}?code=${encodeURIComponent(code.userCode)}`;
+    log(`请在浏览器打开：${url}`);
+    log(`验证码：${code.userCode}`);
+    if (parsed.options.open !== false) {
+        openBrowser(url);
+    }
+    log('等待网页确认授权…');
+    const deadline = Date.now() + code.expiresIn * 1000;
+    let interval = Math.max(code.interval, 1) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        const res = await api.postPublic('/openapi/device/token', { deviceCode: code.deviceCode });
+        if (res.status === 'approved' && res.apiKey) {
+            writeApiKey(res.apiKey);
+            const balance = await api.get('/openapi/balance');
+            log(`已登录，凭据写入 ${credentialsPath()}`);
+            emit({ loggedIn: true, remainingQuota: balance.remainingQuota });
+            return;
+        }
+        if (res.status === 'expired') {
+            fail('验证码已过期', '重新执行 ssx login');
+        }
+        // slow_down 说明轮太快了，退一步再问
+        if (res.status === 'slow_down')
+            interval += 1000;
+    }
+    fail('等待授权超时', '重新执行 ssx login');
+}
+/**
+ * 登出 = 吊销服务端那把 key + 删本地凭据。
+ *
+ * **顺序不能反，而且服务端失败也要继续删本地。** 用户敲 logout 想要的首先是
+ * 「这台机器上别留着我的钥匙」——网络不通就把文件留在那儿，等于没登出。
+ */
+export async function logout() {
+    const had = readApiKey() !== null;
+    if (!had) {
+        log('本来就没有登录');
+        emit({ loggedOut: true, revoked: false });
+        return;
+    }
+    // 这里必须用 requestSoft：普通的 request 遇到业务错误会 process.exit，
+    // 那样本地凭据就删不掉了——而删本地恰恰是登出最要紧的那一半
+    const revoked = await requestSoft('DELETE', '/openapi/key');
+    clearApiKey();
+    log(revoked ? '已登出，这台设备的授权已吊销，本地凭据已删除' : '本地凭据已删除；服务端吊销没成功，可以去个人中心的「开发者」里补一次');
+    emit({ loggedOut: true, revoked });
+}
+export async function whoami() {
+    const balance = await api.get('/openapi/balance');
+    log(`服务地址：${baseUrl()}`);
+    if (balance.unlimitedActive) {
+        // 买了无限模式的人一定会问这件事，先说在前面
+        log('注意：命令行创作按积分计费，不使用无限模式额度');
+    }
+    emit(balance);
+}
+function clientName() {
+    // 让用户在「已授权设备」列表里认得出是哪台机器、哪个 agent
+    const agent = process.env.CLAUDE_CODE ? 'Claude Code' : process.env.TERM_PROGRAM || 'CLI';
+    return `${agent} on ${process.env.HOSTNAME || process.env.HOST || 'unknown'}`;
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    // 打不开浏览器不算失败：上面已经把链接打出来了，用户自己复制也行
+    execFile(cmd, [url], () => { });
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/commands/misc.js

@@ -0,0 +1,133 @@
+import { createWriteStream } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { api } from '../api.js';
+import { emit, fail, log } from '../output.js';
+import { parseKeyValues } from '../args.js';
+export async function model(parsed) {
+    // 类型只认 --type。位置参数留给关键词：`ssx model search nano` 里的 nano 是要搜的词，
+    // 不是模型类型——把它当成 type 会让后端过滤出空列表，而 agent 看到空列表会以为没有可用模型
+    const type = parsed.options.type;
+    const query = type && type !== true ? `?type=${encodeURIComponent(String(type))}` : '';
+    const models = await api.get(`/openapi/models${query}`);
+    const keyword = parsed.positional[1] === 'search' ? parsed.positional[2] : undefined;
+    const filtered = keyword
+        ? models.filter((m) => m.name.toLowerCase().includes(String(keyword).toLowerCase()))
+        : models;
+    emit(filtered.map((m) => ({ name: m.name, type: m.type, pricing: m.pricing })));
+}
+/** 节点契约。agent 拼参数之前该先看这个，而不是猜字段名。 */
+export async function schema() {
+    emit(await api.get('/openapi/schema'));
+}
+export async function balance() {
+    emit(await api.get('/openapi/balance'));
+}
+/** 不走画布的单步生成。适合「就要一张图」这种一次性需求。 */
+export async function generate(parsed) {
+    const kind = parsed.positional[1];
+    if (!kind) {
+        fail('要指定生成类型', '用法：ssx generate text2img --model "模型名" --prompt "描述"');
+    }
+    const modelName = parsed.options.model;
+    if (!modelName || modelName === true) {
+        fail('要指定模型', '可用模型见 ssx model list');
+    }
+    const prompt = parsed.options.prompt;
+    const params = parseKeyValues(parsed.repeated.set);
+    log('已提交，等待生成…');
+    const g = await api.post('/openapi/generations', {
+        kind,
+        model: String(modelName),
+        prompt: prompt === true ? undefined : prompt,
+        params,
+    });
+    const terminal = await poll(g);
+    const url = terminal.result?.assets?.[0]?.url;
+    if (terminal.status === 'done') {
+        log(`完成，扣了 ${terminal.cost} 积分`);
+        // 出图就顺手存到本地：agent 拿到本地路径才能接着做别的事，
+        // 只给一个 URL 它还得自己再写一段下载代码
+        if (url && parsed.options.output !== false) {
+            const file = await download(url, parsed.options.output === true ? undefined : String(parsed.options.output ?? ''));
+            emit({ generationId: terminal.id, status: terminal.status, cost: terminal.cost, url, file });
+            return;
+        }
+    }
+    else if (terminal.status === 'failed') {
+        log(`失败：${terminal.error ?? '未知原因'}`);
+    }
+    emit({
+        generationId: terminal.id,
+        status: terminal.status,
+        cost: terminal.cost,
+        result: url ?? terminal.result?.text,
+    });
+}
+export async function upload(parsed) {
+    const path = parsed.options.file !== true && parsed.options.file ? String(parsed.options.file) : parsed.positional[1];
+    if (!path) {
+        fail('要指定文件', '用法：ssx upload ./ref.png');
+    }
+    const abs = resolve(path);
+    const bytes = await readFile(abs).catch(() => fail(`读不到文件 ${abs}`));
+    const form = new FormData();
+    // Blob 不带 type 的话 multipart 的 Content-Type 就是 application/octet-stream，
+    // 服务端按 MIME 判类型，会直接拒掉——本地按扩展名推一个出来
+    form.append('file', new Blob([bytes], { type: mimeOf(abs) }), basename(abs));
+    const asset = await api.upload('/openapi/assets/upload', form);
+    emit({ assetId: asset.id, url: asset.url });
+}
+export async function downloadCommand(parsed) {
+    const url = parsed.positional[1];
+    if (!url) {
+        fail('要指定要下载的 URL', '用法：ssx download <url> [-o 文件名]');
+    }
+    const out = parsed.options.output;
+    const file = await download(url, out === true || !out ? undefined : String(out));
+    emit({ file });
+}
+const MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    gif: 'image/gif',
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    m4a: 'audio/mp4',
+};
+function mimeOf(path) {
+    const ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+    return MIME[ext] ?? 'application/octet-stream';
+}
+async function download(url, out) {
+    const name = out || basename(new URL(url).pathname) || 'output';
+    const target = resolve(name);
+    const res = await fetch(url);
+    if (!res.ok || !res.body) {
+        return fail(`下载失败（HTTP ${res.status}）：${url}`);
+    }
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(target));
+    log(`已保存到 ${target}`);
+    return target;
+}
+/** 轮到终态。间隔 3 秒，与后端的实际出图节奏匹配，太密只是白发请求。 */
+async function poll(g) {
+    let current = g;
+    const deadline = Date.now() + 10 * 60 * 1000;
+    while (Date.now() < deadline) {
+        if (current.status === 'done' || current.status === 'failed' || current.status === 'canceled') {
+            return current;
+        }
+        await new Promise((r) => setTimeout(r, 3000));
+        current = await api.get(`/openapi/generations/${g.id}`);
+    }
+    log('等了 10 分钟还没结束，任务仍在后台跑');
+    return current;
+}

package/dist/commands/node.js

@@ -0,0 +1,271 @@
+import { randomUUID } from 'node:crypto';
+import { api } from '../api.js';
+import { emit, fail, log } from '../output.js';
+import { parseKeyValues } from '../args.js';
+import { canvasUrl, resolveWorkflowId } from './workflow.js';
+const RUNNABLE = new Set(['textNode', 'imageNode', 'storyVideo']);
+export async function node(parsed) {
+    const sub = parsed.positional[1] ?? 'list';
+    switch (sub) {
+        case 'list':
+            return list(parsed);
+        case 'create':
+            return create(parsed);
+        case 'update':
+            return update(parsed);
+        case 'run':
+            return run(parsed);
+        case 'delete':
+            return remove(parsed);
+        case 'connect':
+            return connect(parsed);
+        case 'disconnect':
+            return disconnect(parsed);
+        default:
+            fail(`未知的子命令 ${sub}`, '可用：list / create / update / run / delete / connect / disconnect');
+    }
+}
+async function list(parsed) {
+    const id = resolveWorkflowId(parsed);
+    const canvas = await api.get(`/openapi/workflows/${id}`);
+    emit(canvas.nodes.map((n) => ({
+        id: n.id,
+        type: n.type,
+        name: n.data?.title ?? undefined,
+        status: n.data?.status ?? 'idle',
+        hasResult: Boolean(n.data?.result),
+    })));
+}
+async function create(parsed) {
+    const workflowId = resolveWorkflowId(parsed);
+    const type = String(parsed.options.type ?? '');
+    if (!type) {
+        fail('建节点要指定类型', '用法：ssx node create <名字> -t imageNode，类型清单见 ssx schema');
+    }
+    const name = parsed.positional[2];
+    const data = parseKeyValues(parsed.repeated.set);
+    Object.assign(data, parseKeyValues(parsed.repeated.update));
+    if (name)
+        data.title = name;
+    if (parsed.options.prompt && parsed.options.prompt !== true)
+        data.prompt = parsed.options.prompt;
+    const nodeId = randomUUID();
+    await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, {
+        action: 'create',
+        creates: [{ id: nodeId, type, position: position(parsed), data }],
+    });
+    // 连上游：--left 可以给多个，值是上游节点的名字或 id
+    const lefts = parsed.repeated.left ?? [];
+    if (lefts.length) {
+        const canvas = await api.get(`/openapi/workflows/${workflowId}`);
+        // 去重：同一个上游写两次 --left 不该连出两条线
+        const sources = new Set(lefts.map((ref) => locate(canvas.nodes, ref).id));
+        for (const source of sources) {
+            await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, {
+                action: 'createEdge',
+                edge: { id: randomUUID(), source, target: nodeId },
+            });
+        }
+        log(`已连接 ${sources.size} 个上游`);
+    }
+    if (parsed.options.run) {
+        return runNode(workflowId, nodeId, waitSeconds(parsed));
+    }
+    emit({ id: nodeId, type, name, workflowId, url: canvasUrl(workflowId) });
+}
+async function update(parsed) {
+    const workflowId = resolveWorkflowId(parsed);
+    const target = await find(workflowId, parsed.positional[2]);
+    const data = parseKeyValues(parsed.repeated.set);
+    Object.assign(data, parseKeyValues(parsed.repeated.update));
+    if (parsed.options.prompt && parsed.options.prompt !== true)
+        data.prompt = parsed.options.prompt;
+    if (parsed.options.name && parsed.options.name !== true)
+        data.title = parsed.options.name;
+    const edgeChanges = await applyEdges(workflowId, target.id, parsed);
+    if (!Object.keys(data).length && !edgeChanges) {
+        fail('没有要改的字段', '用法：ssx node update <节点> --set prompt="新的提示词"，或 --left 改连线');
+    }
+    if (Object.keys(data).length) {
+        await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, {
+            action: 'update',
+            id: target.id,
+            data,
+        });
+    }
+    if (parsed.options.run) {
+        return runNode(workflowId, target.id, waitSeconds(parsed));
+    }
+    emit({ id: target.id, updated: Object.keys(data) });
+}
+/**
+ * 改入边。三种模式，一次只能用一种：
+ *
+ * - `--left A --left B`：**确保**入边正好是 A 和 B——缺的补上、多的剪掉。
+ *   agent 描述目标状态比描述增量容易，重跑同一条命令也不会叠出重复的边。
+ * - `--left-add X`：只加
+ * - `--left-rm X`：只删
+ *
+ * @return 是否动过连线
+ */
+async function applyEdges(workflowId, nodeId, parsed) {
+    const ensure = parsed.repeated.left;
+    const add = parsed.repeated['left-add'];
+    const remove = parsed.repeated['left-rm'];
+    if (!ensure && !add && !remove)
+        return false;
+    if (ensure && (add || remove)) {
+        fail('--left 与 --left-add / --left-rm 不能一起用', '--left 是「入边就是这些」，另两个是增量，选一种');
+    }
+    const canvas = await api.get(`/openapi/workflows/${workflowId}`);
+    const incoming = canvas.edges.filter((e) => e.target === nodeId);
+    const idOf = (ref) => locate(canvas.nodes, ref).id;
+    const toAdd = [];
+    const toRemove = [];
+    if (ensure) {
+        const want = new Set(ensure.map(idOf));
+        for (const source of want) {
+            if (!incoming.some((e) => e.source === source))
+                toAdd.push(source);
+        }
+        for (const edge of incoming) {
+            if (!want.has(edge.source))
+                toRemove.push(edge.id);
+        }
+    }
+    for (const ref of add ?? []) {
+        const source = idOf(ref);
+        if (!incoming.some((e) => e.source === source))
+            toAdd.push(source);
+    }
+    for (const ref of remove ?? []) {
+        const source = idOf(ref);
+        for (const edge of incoming) {
+            if (edge.source === source)
+                toRemove.push(edge.id);
+        }
+    }
+    for (const source of toAdd) {
+        await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, {
+            action: 'createEdge',
+            edge: { id: randomUUID(), source, target: nodeId },
+        });
+    }
+    if (toRemove.length) {
+        await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, { action: 'deleteEdge', ids: toRemove });
+    }
+    if (toAdd.length || toRemove.length) {
+        log(`连线：+${toAdd.length} -${toRemove.length}`);
+    }
+    return true;
+}
+/** 断开两个节点之间的连线。agent 手里只有节点名，不知道边的 id。 */
+async function disconnect(parsed) {
+    const workflowId = resolveWorkflowId(parsed);
+    const canvas = await api.get(`/openapi/workflows/${workflowId}`);
+    const source = locate(canvas.nodes, parsed.positional[2]);
+    const target = locate(canvas.nodes, parsed.positional[3]);
+    const hit = canvas.edges.filter((e) => e.source === source.id && e.target === target.id);
+    if (!hit.length) {
+        fail(`「${parsed.positional[2]}」和「${parsed.positional[3]}」之间没有连线`, '现有连线见 ssx workflow show');
+    }
+    await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, {
+        action: 'deleteEdge',
+        ids: hit.map((e) => e.id),
+    });
+    emit({ disconnected: [source.id, target.id], removed: hit.length });
+}
+async function run(parsed) {
+    const workflowId = resolveWorkflowId(parsed);
+    const target = await find(workflowId, parsed.positional[2]);
+    if (!RUNNABLE.has(target.type)) {
+        fail(`${target.type} 不支持直接触发生成`, `目前支持：${[...RUNNABLE].join(' / ')}`);
+    }
+    await runNode(workflowId, target.id, waitSeconds(parsed));
+}
+async function remove(parsed) {
+    const workflowId = resolveWorkflowId(parsed);
+    const target = await find(workflowId, parsed.positional[2]);
+    await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, { action: 'delete', ids: [target.id] });
+    emit({ deleted: target.id });
+}
+async function connect(parsed) {
+    const workflowId = resolveWorkflowId(parsed);
+    const canvas = await api.get(`/openapi/workflows/${workflowId}`);
+    const source = locate(canvas.nodes, parsed.positional[2]);
+    const target = locate(canvas.nodes, parsed.positional[3]);
+    // 幂等：服务端的 createEdge 是直接 add，不去重。agent 重试很常见，
+    // 不挡一下的话同一对节点之间会叠出好几条线
+    const existing = canvas.edges.find((e) => e.source === source.id && e.target === target.id);
+    if (existing) {
+        emit({ connected: [source.id, target.id], created: false });
+        return;
+    }
+    await api.post(`/openapi/workflows/${workflowId}/nodes:batch`, {
+        action: 'createEdge',
+        edge: { id: randomUUID(), source: source.id, target: target.id },
+    });
+    emit({ connected: [source.id, target.id], created: true });
+}
+/**
+ * 触发生成。默认阻塞等终态——agent 每轮询一次都是一次模型调用，token 是用户在付，
+ * 让它自己写 while 循环等于让它一直烧钱。要立刻返回就传 --wait 0。
+ */
+async function runNode(workflowId, nodeId, wait) {
+    log(wait > 0 ? `已提交，最多等 ${wait} 秒…` : '已提交');
+    const g = await api.post(`/openapi/workflows/${workflowId}/nodes/${nodeId}:run?waitSeconds=${wait}`);
+    const url = g.result?.assets?.[0]?.url;
+    const text = g.result?.text;
+    if (g.status === 'done') {
+        log(`完成，扣了 ${g.cost} 积分`);
+    }
+    else if (g.status === 'failed') {
+        log(`失败：${g.error ?? '未知原因'}`);
+    }
+    else {
+        log(`还在生成中，稍后用 ssx node list 看状态，或去画布看：${canvasUrl(workflowId)}`);
+    }
+    emit({
+        generationId: g.id,
+        status: g.status,
+        cost: g.cost,
+        result: url ?? text,
+        nodeId,
+        url: canvasUrl(workflowId),
+    });
+}
+/** 支持按名字或 id 定位。agent 记名字比记 uuid 容易，这一点对它的可用性影响很大。 */
+async function find(workflowId, ref) {
+    const canvas = await api.get(`/openapi/workflows/${workflowId}`);
+    return locate(canvas.nodes, ref);
+}
+function locate(nodes, ref) {
+    if (!ref) {
+        fail('要指定节点', '用节点名或 id，列表见 ssx node list');
+    }
+    const byId = nodes.find((n) => n.id === ref);
+    if (byId)
+        return byId;
+    const byName = nodes.filter((n) => n.data?.title === ref);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        fail(`有 ${byName.length} 个节点都叫「${ref}」`, `用 id 指定：${byName.map((n) => n.id).join(' / ')}`);
+    }
+    return fail(`找不到节点「${ref}」`, '列表见 ssx node list');
+}
+function position(parsed) {
+    return {
+        x: Number(parsed.options.x ?? 0) || 0,
+        y: Number(parsed.options.y ?? 0) || 0,
+    };
+}
+function waitSeconds(parsed) {
+    const raw = parsed.options.wait;
+    if (raw === undefined)
+        return 55;
+    if (raw === true)
+        return 55;
+    const n = Number(raw);
+    return Number.isNaN(n) ? 55 : Math.max(0, Math.min(n, 55));
+}

package/dist/commands/workflow.js

@@ -0,0 +1,80 @@
+import { api } from '../api.js';
+import { clearBinding, readBinding, writeBinding } from '../config.js';
+import { emit, fail, log } from '../output.js';
+export async function workflow(parsed) {
+    const sub = parsed.positional[1] ?? 'show';
+    switch (sub) {
+        case 'list':
+            return list();
+        case 'create':
+            return create(parsed);
+        case 'use':
+            return use(parsed);
+        case 'unuse':
+            return unuse();
+        case 'show':
+            return show(parsed);
+        default:
+            fail(`未知的子命令 ${sub}`, '可用：list / create / use / unuse / show');
+    }
+}
+async function list() {
+    const page = await api.get('/openapi/workflows?limit=50');
+    emit(page.items.map((w) => ({ id: w.id, title: w.title, updatedAt: w.updatedAt })));
+}
+async function create(parsed) {
+    const title = parsed.positional[2] ?? String(parsed.options.title ?? '');
+    const created = await api.post('/openapi/workflows', { title: title || undefined });
+    // 新建即绑定：agent 建完画布下一句多半就是建节点，让它不用再传一次 id
+    const file = writeBinding({ workflowId: created.id, title: created.title });
+    log(`已创建并绑定到当前目录（${file}）`);
+    emit({ id: created.id, title: created.title, url: canvasUrl(created.id) });
+}
+function use(parsed) {
+    const raw = parsed.positional[2];
+    const id = Number(raw);
+    if (!raw || Number.isNaN(id)) {
+        fail('需要画布 id', '用法：ssx workflow use <画布id>，画布列表见 ssx workflow list');
+    }
+    const file = writeBinding({ workflowId: id });
+    log(`已绑定画布 ${id}（${file}）`);
+    emit({ workflowId: id, url: canvasUrl(id) });
+}
+function unuse() {
+    const removed = clearBinding();
+    log(removed ? '已解除当前目录的画布绑定' : '当前目录本来就没有绑定');
+    emit({ unbound: removed });
+}
+async function show(parsed) {
+    const id = resolveWorkflowId(parsed);
+    const canvas = await api.get(`/openapi/workflows/${id}`);
+    emit({
+        workflowId: id,
+        url: canvasUrl(id),
+        nodes: canvas.nodes.map((n) => ({
+            id: n.id,
+            type: n.type,
+            name: n.data?.title ?? undefined,
+            status: n.data?.status ?? 'idle',
+            result: n.data?.result,
+        })),
+        edges: canvas.edges,
+    });
+}
+/** 命令行显式给的 > 当前目录绑定的。两者都没有就报错并指路。 */
+export function resolveWorkflowId(parsed) {
+    const explicit = parsed.options.workflow ?? parsed.options.project;
+    if (explicit && explicit !== true) {
+        const id = Number(explicit);
+        if (!Number.isNaN(id))
+            return id;
+    }
+    const bound = readBinding();
+    if (bound)
+        return bound.workflowId;
+    return fail('没有指定画布', '先 ssx workflow use <画布id> 绑定，或加 --workflow <画布id>');
+}
+export function canvasUrl(id) {
+    const base = (process.env.SOULSPACEX_BASE_URL ?? 'https://soulspacex.com').replace(/\/+$/, '');
+    return `${base}/editor/${id}`;
+}

package/dist/config.js

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * 两份本地状态，作用域刻意不同：
+ *
+ * - **凭据**在 `~/.soulspacex/credentials`，跟人走，一台机器一份。
+ * - **画布绑定**在当前目录的 `.soulspacex/workflow.json`，跟项目走。
+ *   agent 在一个项目目录里连续操作时不用反复传画布 id——这是抄 liblib 的做法，
+ *   也是 git 的做法。
+ */
+const CONFIG_DIR = process.env.SOULSPACEX_CONFIG_DIR ?? join(homedir(), '.soulspacex');
+const CREDENTIALS_FILE = join(CONFIG_DIR, 'credentials');
+const PROJECT_DIR = '.soulspacex';
+const PROJECT_FILE = 'workflow.json';
+export const DEFAULT_BASE_URL = 'https://soulspacex.com';
+export function baseUrl() {
+    return (process.env.SOULSPACEX_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+}
+// ---- 凭据 ----
+export function readApiKey() {
+    // 环境变量优先：CI 和容器里没法交互登录，直接注入 key 是唯一可行的路
+    const fromEnv = process.env.SOULSPACEX_API_KEY;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    if (!existsSync(CREDENTIALS_FILE))
+        return null;
+    const content = readFileSync(CREDENTIALS_FILE, 'utf8').trim();
+    return content || null;
+}
+export function writeApiKey(key) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    // 0600：这把 key 能花用户的积分，不该让同机器的其他用户读到
+    writeFileSync(CREDENTIALS_FILE, key + '\n', { mode: 0o600 });
+}
+export function clearApiKey() {
+    if (existsSync(CREDENTIALS_FILE))
+        rmSync(CREDENTIALS_FILE);
+}
+export function credentialsPath() {
+    return CREDENTIALS_FILE;
+}
+/** 从当前目录逐级向上找，与 git 找 .git 的方式一致——在子目录里也能用。 */
+export function readBinding(from = process.cwd()) {
+    let dir = resolve(from);
+    for (;;) {
+        const file = join(dir, PROJECT_DIR, PROJECT_FILE);
+        if (existsSync(file)) {
+            try {
+                return JSON.parse(readFileSync(file, 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function writeBinding(binding, at = process.cwd()) {
+    const dir = join(at, PROJECT_DIR);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, PROJECT_FILE);
+    writeFileSync(file, JSON.stringify(binding, null, 2) + '\n');
+    return file;
+}
+export function clearBinding(at = process.cwd()) {
+    const file = join(at, PROJECT_DIR, PROJECT_FILE);
+    if (!existsSync(file))
+        return false;
+    rmSync(file);
+    return true;
+}

package/dist/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { parseArgs } from './args.js';
+import { fail, log } from './output.js';
+import { login, logout, whoami } from './commands/login.js';
+import { workflow } from './commands/workflow.js';
+import { node } from './commands/node.js';
+import { balance, downloadCommand, generate, model, schema, upload } from './commands/misc.js';
+const VERSION = '0.1.0';
+/**
+ * 这段 help 的第一读者是 AI Agent，不是人。
+ *
+ * Agent 遇到不会用的命令会自己跑 `--help`，然后照着上面写的拼参数——所以这里的措辞
+ * 直接决定它用得对不对。示例要能照抄，约束要写死（哪些字段不能自己设、上游怎么接），
+ * 别指望它去猜。
+ */
+const HELP = `ssx — SoulSpaceX 命令行工具
+
+在画布上创作：文本、图片、视频节点互相连线，上游的产物自动成为下游的输入。
+
+用法
+  ssx <命令> [子命令] [参数]
+
+开始
+  ssx login                     浏览器授权这台设备（需要订阅卡 / 会员 / 无限模式）
+  ssx whoami                    看当前身份与积分余额
+  ssx logout                    吊销这台设备的授权并删除本地凭据
+
+画布
+  ssx workflow create "短剧第一集"   新建画布并绑定到当前目录
+  ssx workflow list                 我的画布
+  ssx workflow use <画布id>         把当前目录绑到某张画布
+  ssx workflow show                 看当前画布的节点与连线
+
+节点
+  ssx node create "剧本" -t textNode --prompt "写一段赛博朋克开场" --run
+  ssx node create "主视觉" -t imageNode --left 剧本 --set count=1 --run
+  ssx node list                     列出节点（名字、状态、有没有产物）
+  ssx node update 剧本 --set prompt="改后的提示词" --run
+  ssx node run 主视觉               触发生成，默认阻塞到出结果
+  ssx node connect 剧本 主视觉      连一条线（上游 → 下游），重复连不会叠出多条
+  ssx node disconnect 剧本 主视觉   断开
+  ssx node update 主视觉 --left 剧本 --left 参考图
+                                    改入边：结果就是这两个，缺的补、多的剪
+  ssx node update 主视觉 --left-add 配乐   只加
+  ssx node update 主视觉 --left-rm 参考图  只删
+  ssx node delete 主视觉
+
+  节点类型：textNode（文本）imageNode（图片）storyVideo（视频）
+           audioNode / agentNode / director3dNode 可以建，但暂不支持 run
+  -t 指定类型，--set 写生成参数（模型、比例、时长…），--left 接上游，--run 建完立刻生成
+  节点可以用名字指代，重名时才需要用 id
+
+不走画布的一次性生成
+  ssx generate text2img --model "模型名" --prompt "一只赛博朋克的猫"
+  ssx model list                    可用模型（带计价）
+  ssx model search nano             按名字搜
+
+素材
+  ssx upload ./ref.png              上传参考图，拿到可用的 URL
+  ssx download <url> -o out.png     下载产物到本地
+
+其他
+  ssx schema                        节点字段契约。拼 --set 之前先看这个，别猜字段名
+  ssx balance                       积分余额
+
+约定
+  · 结果走 stdout（JSON），进度和提示走 stderr——可以放心 ssx ... | jq
+  · status / result / assetId 这类字段由生成结果回写，不要自己设，会被拒
+  · 命令行创作按积分计费，不使用无限模式额度
+  · 生成默认阻塞到出结果（最长 55 秒），--wait 0 可以立刻返回
+
+环境变量
+  SOULSPACEX_API_KEY        直接给凭据，CI 与容器里用它代替 ssx login
+  SOULSPACEX_BASE_URL       服务地址，默认 https://soulspacex.com
+`;
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    const command = parsed.positional[0];
+    if (parsed.options.version) {
+        log(VERSION);
+        return;
+    }
+    if (!command || parsed.options.help) {
+        process.stderr.write(HELP);
+        return;
+    }
+    switch (command) {
+        case 'login':
+            return login(parsed);
+        case 'logout':
+            return logout();
+        case 'whoami':
+        case 'account':
+            return whoami();
+        case 'workflow':
+        case 'canvas':
+            return workflow(parsed);
+        case 'node':
+            return node(parsed);
+        case 'model':
+            return model(parsed);
+        case 'schema':
+            return schema();
+        case 'balance':
+            return balance();
+        case 'generate':
+            return generate(parsed);
+        case 'upload':
+            return upload(parsed);
+        case 'download':
+            return downloadCommand(parsed);
+        case 'help':
+            process.stderr.write(HELP);
+            return;
+        default:
+            fail(`未知命令 ${command}`, '可用命令见 ssx --help');
+    }
+}
+main().catch((e) => {
+    fail(e instanceof Error ? e.message : String(e));
+});

package/dist/output.js

@@ -0,0 +1,24 @@
+/**
+ * 输出分流：**stdout 只放业务 JSON，进度与提示一律走 stderr**。
+ *
+ * Agent 会把 stdout 直接喂给下一条命令或自己解析，混进一行「正在生成…」就会让它解析失败。
+ * 这条约定和 liblib 的 CLI 一致，是被实践验证过的。
+ */
+/** 业务结果。唯一往 stdout 写东西的地方。 */
+export function emit(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+/** 进度、状态、提示。人和 agent 都会看，但不会被当成结果解析。 */
+export function log(message) {
+    process.stderr.write(message + '\n');
+}
+/**
+ * 失败。message 会被 agent 原样转述给用户，所以要写清楚下一步做什么，
+ * 而不是只说「出错了」。
+ */
+export function fail(message, hint) {
+    process.stderr.write(`错误：${message}\n`);
+    if (hint)
+        process.stderr.write(`${hint}\n`);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@soulspacex/cli",
+  "version": "0.1.0",
+  "description": "SoulSpaceX 命令行工具——让 AI Agent 直接在画布上创作",
+  "bin": {
+    "ssx": "dist/index.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "dev": "node --experimental-strip-types src/index.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "image-generation",
+    "video-generation"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://soulspacex.com/cli"
+}