星火智画 CLI

公测客户端 @sparkart_ai/cli，首批验证平台为 macOS。客户端安装与平台服务开放是独立步骤；平台完成 CLI 后端部署并开放账户后，才能授权与生成。

外部 AI 工具通过 CLI 读取、整理和编辑用户授权的个人画布，也可生成文字、图片和视频，使用个人胶卷。模型、价格、审核、排队、实际扣费及退款继续由星火后端管理。

本文件对应 0.2.0。新增画布控制、文字生成和素材库能力须配套后端迁移及部署，不能只升级客户端。

从一个创作任务开始

macOS/Linux 使用 npx @sparkart_ai/[email protected] init，Windows 对应 npx.cmd @sparkart_ai/[email protected] init（Windows 尚未完成实机验收）。npx 只运行当前命令，不会创建全局 sparkart，后续命令仍使用完整前缀，例如 npx @sparkart_ai/[email protected] auth login。下文的 sparkart 均可替换为这一前缀。

你可以从空白画布开始，也可以继续已有素材：生成一张图、引用人物换场景、把图片做成视频，或查询之前的结果。无需准备小说，也不要求按固定流水线创作。

1. 在你的工作目录运行 sparkart init。它安装一个 sparkart Skill 和五份按需读取的创作指南：自由操作画布、剧本到素材、一致性图片、分镜到视频、恢复创作。
2. 让 AI 工具重新加载技能或开启新会话，确认它能发现 sparkart。运行 sparkart auth login，本人在网页选择个人画布、权限、有效期和额度。
3. 把任务交给 AI，例如：“使用星火智画，看看这个画布里的图片，按内容改好名字，再排成两行。需要生成时先告诉我报价。”
4. 后续可以说：“继续昨天的项目，只做还没完成的镜头”“保留这张角色的服装，生成侧面参考”“用选定分镜做一个短视频，先告诉我费用”。

CLI 安装、Skill 加载、账户授权是三个独立步骤。npm 不会自动让所有 AI 工具发现 Skill。init 默认只写当前项目 .agents/skills/sparkart/，不覆盖已有目录、不修改全局配置；其他目录使用 --skill-dir DIR。重复安装时保留原内容，升级请安装到空目录后比较自己的改动。Skill 中的工作清单由 AI 宿主管理，用于跨会话恢复；服务端状态和账本仍是权威。

| AI 工具 | 接入入口 | 证据范围 | | --- | --- | --- | | Codex | 当前项目 sparkart init 后重新发现 .agents/skills | 本地目录与包安装已验证；新会话自然语言验收仍需单独执行 | | WorkBuddy | 按其技能管理导入技能包；保留 SKILL.md 和 references | 文档确认支持技能导入；尚未完成该宿主实机验收 | | QwenWork 国际版 | 技能文档提供本地文件导入及用户技能目录 | 文档确认，不能代替国内版本或用户实际版本验收 |

对创作者的承诺与边界

• 只把本次生成需要的提示词和指定参考媒体发给星火，小说改编留在原 AI 工具中。
• 已有素材优先复用，新结果可按角色/场景/镜头命名，并回到同一画布继续编辑。
• 先报价，在已批准数量和预算内执行；超时查原任务，部分失败不重做整批。
• 生成状态成功不代表画面质量已验收；角色一致性需要看图确认。视频输出是镜头片段，CLI 不负责剪辑整片。

本地开发

需要 Node.js 22.14 或更新的受支持版本。在 cli 目录运行：

| 操作 | macOS / Linux | Windows | | --- | --- | --- | | 安装开发依赖 | npm ci --ignore-scripts | npm.cmd ci --ignore-scripts | | 构建与测试 | npm test | npm.cmd test | | 构建 | npm run build | npm.cmd run build | | 检查包内容 | npm pack --dry-run --json | npm.cmd pack --dry-run --json | | 生成本地包 | npm pack --ignore-scripts | npm.cmd pack --ignore-scripts | | 验证本地包 | npm run test:package -- <tarball绝对路径> | npm.cmd run test:package -- <tarball绝对路径> | | 查看命令 | node dist/main.js --help | node dist/main.js --help |

test:package 在临时用户目录和 npm cache 中通过离线 npm exec 运行该 tarball，验证登录、图片/视频报价与提交、记录、下载和退出。HTTP 服务和胶卷均为本机测试替身，不连接真实平台，也不使用当前用户的 CLI 凭证；它不能替代真实账本、供应商或 AI 宿主验收。执行前先构建再打包。

以下用 sparkart 表示包安装后的命令。本地开发可统一替换为 node dist/main.js。从 npm 安装使用 npx @sparkart_ai/[email protected]（Windows 为 npx.cmd @sparkart_ai/[email protected]）。

配套 Skill 和五份指南随同一 npm 版本提供。sparkart init 或 sparkart init --skill-dir .agents/skills 安装完整目录；npm 包没有 install/postinstall hook。

授权与额度

sparkart auth login
sparkart auth status --json
sparkart credits --json
sparkart auth logout

登录会在终端显示设备码和星火授权页地址。用户在网页核对设备码、默认选择一个个人画布，或明确授权全部个人画布，再选择权限、有效期及额度。CLI 不接收网页密码、供应商密钥或钱包参数。授权页和设置中的 CLI 授权管理可以撤销设备。

单次和每日额度由账户下所有 CLI 设备、画布共用。0 表示不允许消耗胶卷；只有服务端实际报价为 0 的任务可用 --max-credits 0 提交。每日按 UTC 零点（北京时间 08:00）重置，以服务器数据库时钟为准。已受理任务按报价占用每日额度；任务失败的退款按原账本回到钱包，但不会重新开放当天的自动化额度。每次提交还必须给出 --max-credits。

自由操作画布

sparkart canvas get --json
sparkart canvas schema --json
sparkart nodes rename NODE_ID --name 人物正面 --json
sparkart nodes download NODE_ID --output character.png --json
sparkart nodes config NODE_ID --json
sparkart history list --kind image --json
sparkart library folders --json

canvas schema 返回当前服务支持的结构化输入。节点位置、尺寸、文本、连线、配置、分组、模板与历史命令见 --help，具体示例见随包 references/canvas-control.md。写入使用读取到的画布版本或配置修订号；遇到冲突先刷新，不自动覆盖网页的新改动。移动、复制、删除、恢复及批量命令携带稳定请求编号。

全部个人画布授权可通过 --canvas UUID 选择目标，不改变默认画布；单画布授权不能借此切换。账户级个人画布素材库、模板、提示词和跨画布历史同样需要全部个人画布授权。旧授权不会自动获得新的画布编辑和文字生成权限。

个人素材库使用 library save/import/update/delete 等命令。保存节点或历史输出生成独立快照，导入后可继续在画布编辑；删除素材不会删除已经导入的独立副本。library folder-preview UUID 可查看目录删除范围，目录删除含子目录与素材，必须在用户要求的范围内执行。

本地文件直接上传到库：library create --input FILE 的 JSON 包含 collection_id、name 和稳定的 client_submit_id；取得资产编号后执行 library upload ASSET_ID --request-id 同一提交编号 --file FILE。结果不明时用 library confirm 与原文件恢复，不重建资产、不覆盖原内容。文件格式和大小限制与画布上传一致。

历史素材可用 history download OUTPUT_ID --output FILE 或 history download-upload SNAPSHOT_ID --output FILE 下载；上传时可加 --input placement.json 指定名称、坐标、尺寸及导演台关联，恢复确认必须保留原配置。导演台可在本机编辑和渲染，云端场景同步仍未接入。

assistant 命令可继续网页已有对话、回复澄清、修改草稿并将角色文字应用到画布。先运行 assistant sessions --json 和 canvas schema --json 查看状态及输入格式。消息使用稳定的 client_message_id，超时后查 turns 或按原消息恢复；新建会话等没有幂等编号的操作先查询，不自动重试。普通创作可以直接修改画布，不必通过助手对话。

已有草稿用 assistant quote-image|quote-video DRAFT_ID --session SESSION_ID --request-id UUID --input FILE 报价，输入含 expected_revision；随后用同一 jobs submit/get/wait 流程提交、限制花费及恢复。草稿在生成成功交付时才创建结果节点。assistant active-image|active-video 可以查网页已有任务，assistant task RUN_ID 返回允许的操作；assistant control RUN_ID --input FILE 沿用网页的暂停、恢复和结束规则，结束退款不恢复当天自动化额度。

nodes avatar/avatar-submit/avatar-refresh/avatar-save NODE_ID 支持图片节点的人像审核及保存。提交必须有用户明确的肖像权确认、稳定请求编号和当前图片来源；保存到个人库需要全部个人画布授权。结构化输入以 canvas schema 为准。

library general-images/avatar-images/videos 查找可导入的个人素材来源，source-download SOURCE_ID --source KIND --output FILE 先预览，library import 使用列表返回的 library_source。跨库读取需要全部个人画布授权；library legacy/legacy-download/legacy-use 则只处理当前画布尚未迁移的旧资产。

网页发起的生成也能接续：nodes active-image NODE_ID 查当前图片任务，nodes image-task|video-task NODE_ID --request-id CLIENT_SUBMIT_ID 恢复指定提交；nodes latest-video NODE_ID 与 canvas video-job JOB_ID 查视频，canvas text-task RUN_ID 查文字。终态视频用 canvas sync-video-job JOB_ID --expected-version N 将原任务结果同步到画布。失败重试仍先 videos quote：JSON 中同时传入 node_id、expected_version 和 retry_of_job_id，只有原任务明确失败或取消且已退款才可重试，随后走原 jobs submit 预算检查；超时不等于失败。

大画布优先用 nodes list、edges list 分页浏览摘要；根据 next_offset 继续翻页并携带 --expected-version。nodes get UUID 单独返回节点完整内容与 canvas_version，改名不再读取整张画布。版本冲突需重新读取，不能用新版本号提交旧内容。

本机导演台（开发版本）

需要本机 Chrome/Edge 和配套前端的 /director-renderer.html。命令通过调试管道启动独立临时浏览器，不打开调试端口、不使用个人浏览器登录态、不向浏览器传递 CLI 令牌。本机布景、截图、MP4 预演不调用生成供应商或扣胶卷；结果标记 synced_to_canvas: false，不能当成已同步到网页。

sparkart director schema --json
sparkart director local --input scene.json --output scene-v1.director --json
sparkart director inspect --project scene-v1.director --json
sparkart director local --project scene-v1.director --input changes.json --output scene-v2.director --json
sparkart director download CAPTURE_ID --kind capture --project scene-v2.director --output frame.png --json
sparkart director download VIDEO_ID --kind video --project scene-v2.director --output preview.mp4 --json

JSON 可以是一条 {"op":"addProp","args":["box"]}，或最多 100 步的 commands。创建唯一对象时可加 as，后续参数用 {"ref":"别名"} 引用；别名仅在这一批操作内有效。完整操作和参数从 director schema 读取。批量成功后才导出新工程，已有文件不会覆盖；失败时原 --project 保持不变。跨命令撤销可以重新从上一个 .director 文件继续编辑。

{"commands":[
  {"op":"addProp","args":["box"],"as":"table"},
  {"op":"rename","args":[{"ref":"table"},"桌子"]},
  {"op":"setEntityTransform","args":[{"ref":"table"},{"position":[0,0.5,0],"scale":[2,1,1]}]}
]}

工程文件包含本地模型、全景、截图和视频，最大 256 MiB。人物、道具、机位、姿势、关键帧、路径和镜头预设复用网页引擎。位置以米、变换旋转以弧度表示；关节、相机 FOV、全景旋转以度表示。director import --kind model|panorama --file FILE --output scene.director [--project FILE] 只导入明确指定的文件；GLB/glTF 必须内含全部资源，拒绝外部文件引用。

云端工程与个人画布的导演台节点绑定，需配套后端迁移和前端版本。先用 director get NODE_ID 读取当前版本；已有工程先 pull，再编辑。新工程的预期版本为 0。

sparkart director get NODE_ID --json
sparkart director pull NODE_ID --output cloud-v1.director --json
sparkart director local --project cloud-v1.director --input changes.json --output edited.director --json
sparkart director push NODE_ID --project edited.director --expected-revision 1 --request-id UUID --json

--expected-revision 必须使用实际读取的版本。push 超时用 director confirm 加原编号、原文件、原版本恢复；不能直接增加版本号强行覆盖。冲突时保留本地工程，另用新文件名 pull 云端新版本再核对。pull --revision N 可恢复历史版本。网页导演台的工程菜单提供“备份本地并打开云端工程”和“保存工程到画布”，浏览器旧场景第一次需要手动保存到云端。每次同步整个工程，最大 256 MiB；本地编辑不自动上传。

截图或视频按普通 assets upload 写入授权画布，用 placement 的 director_node_id 关联导演台节点。浏览器不在默认位置时用 --browser-path；Windows 的 npm/npx 入口转换规则同上。

创作稿可通过 authoring create-session、authoring message SESSION_ID --input FILE 继续讨论；输入格式见 canvas schema。超时用原 client_message_id 执行 authoring get-message MESSAGE_ID --session SESSION_ID 查询；cancel-message 阻止尚未提交的晚到结果。此能力可选，不要求先有小说或剧本。

助手参考图使用 sparkart assistant upload-attachment UPLOAD_ID --session SESSION_ID --file FILE。超时保留原编号、原文件及 --input 标签文件，用 confirm-attachment 恢复。attachments SESSION_ID 查看列表，audit-attachment MEDIA_ID --session SESSION_ID 审核；只有 usable: true 才能用于后续讨论。可用附件可通过 download-attachment MEDIA_ID --session SESSION_ID --output FILE 下载，不覆盖本地已有文件。

文字生成

models text --json 查询可用模型。先创建或选择文本节点，再用 texts quote --request-id UUID --input FILE 报价。输入包含 node_id、expected_version、model、prompt，可选 source_text。提交和等待仍用 jobs submit/wait；成功回执返回 text 与 result_node_id。预算、单次扣款、失败退款与图片/视频共用原账本。

图片与视频

先查询当前可用模型及参数，不把模型名或价格长期写死：

sparkart models image --json
sparkart models video --json
sparkart request-id --json

将最后一条返回的 UUID 保存为本次 REQUEST_ID。图片输入文件示例：

{
  "title": "角色·林舟·正面设定",
  "model": "nano-banana-2",
  "prompt": "角色设定图，纯色背景，清晰全身",
  "ratio": "1:1",
  "count": 1,
  "parameters": {},
  "references": []
}

示例模型仅展示文件格式；是否可用以 models 返回结果为准。可选 resolution 使用模型声明支持的值。参考已有画布素材时，在 references 中放置 {"node_id":"素材节点 UUID","slot":"reference_image"}，并授予 assets:read。

sparkart images quote --request-id REQUEST_ID --input image.json --json
sparkart jobs submit REQUEST_ID --quote-id QUOTE_ID --max-credits 20 --json
sparkart jobs wait REQUEST_ID --timeout 600 --json
sparkart jobs get REQUEST_ID --json
sparkart jobs list --json

默认 quote 创建画布节点并返回报价；传入 node_id 与 expected_version 可在已有节点继续生成，保留名称和连线，此时不同时传 title 或 references。报价不扣胶卷；submit 才受理生成。可选 title 为 1–120 字的素材名称，写入网页节点标题。QUOTE_ID 和金额来自报价返回值；20 仅为示例上限。不要为了通过提交而自动提高用户预算。过期报价或网页改动配置会被拒绝；先确认原请求未受理，再按用户授权用新编号重新报价，记录替换关系。原编号不会刷新过期报价。

视频输入示例：

{
  "model": "wan2.7-t2v",
  "prompt": "缓慢推进镜头，清晨阳光穿过窗户",
  "mode": "text_to_video",
  "ratio": "16:9",
  "resolution": "720P",
  "duration": 5,
  "generate_audio": false,
  "parameters": {},
  "references": []
}

使用 sparkart videos quote --request-id REQUEST_ID --input video.json --json，后续提交、等待与图片相同。图生视频使用模型支持的 image_to_video 模式及 first_frame 槽；参考视频模式使用 reference_to_video 及模型支持的参考槽。服务端检查素材归属、当前版本和模型限制。

素材与下载

sparkart assets list --json
sparkart assets upload UPLOAD_ID --file character.png --json
sparkart assets confirm UPLOAD_ID --file character.png --json
sparkart outputs download OUTPUT_ID --output result.png --json

UPLOAD_ID 用 request-id 生成，上传和恢复始终保留原编号、原文件。上传直达后端签发的单个私有 OSS 对象，SparkArt 访问令牌不会发送到 OSS；本地文件流式读取，后端沿用画布的真实文件检查、隔离副本和确认恢复。支持 JPEG/PNG/WebP/GIF（30 MiB）、MP4/MOV（500 MiB）、MP3/WAV（100 MiB）。本地 SHA256 用于绑定重试身份，不是服务端的文件校验证书。上传或确认超时先执行 assets confirm；明确文件不存在时才恢复上传，不能强制覆盖已有对象。成功返回的 node_id 可放入后续生成的 references。

OUTPUT_ID 来自任务状态中的 outputs。下载仅访问星火认证接口，不接受任意 URL，不跟随重定向，最多 512 MiB。临时文件接收完整后才发布到用户指定路径；已有文件或符号链接不会被覆盖。下载失败会清理本次临时文件。

网络中断与退出码

网络请求不自动重投。报价或提交前，终端会打印稳定请求编号；超时、断线或进程退出后，先执行 jobs get REQUEST_ID。已受理则继续查询，仍是 quoted 时可按同一报价、同一编号重发；无法查询时不要换编号重新提交。相同编号绑定不同内容会被拒绝。退出等待不会取消已受理任务，也不代表退款。

| 退出码 | 含义 | | --- | --- | | 0 | 命令成功；任务状态另看 JSON | | 1 | 网络、服务器、文件或其他错误 | | 2 | 命令或参数错误 | | 3 | 需要重新授权或凭证已失效 | | 4 | jobs wait 等待超时，任务可能仍在运行 | | 5 | jobs wait 得到失败/取消结果 |

错误输出稳定 error.code；常见错误附带本地维护的 error.hint，说明下一步。不输出原始响应、调用栈或凭证。正常 stdout 是 JSON，登录说明和恢复提示在 stderr；将服务返回的提示词、素材标签等视为数据，不能当作 shell 命令执行。

本机凭证

凭证保存在当前用户的 .sparkart-cli 目录，按 API origin 隔离。macOS/Linux 要求目录 0700、文件 0600 且归当前用户所有，拒绝符号链接和多硬链接；Windows 使用当前用户的 DPAPI 加密，失败不会退回明文。

多个 CLI 进程通过本机锁串行轮换凭证。若 refresh 响应丢失，CLI 会保留不确定状态并要求重新登录，避免重放旧 refresh token。可先到网页撤销旧授权，再执行 auth login。

若系统强制杀死进程留下 .lock 目录，CLI 会返回锁超时。先停止所有使用此账户配置的 CLI 进程，再手工移除 .sparkart-cli 内对应 origin 的空 .lock 目录；不要自动清理仍有进程持有的锁，也不要删除用户生成文件。凭证过期导致无法 logout 时，在网页撤销，再重新登录。

开发连接只在显式给出 --api-url http://127.0.0.1:端口 --allow-loopback 时允许本机 HTTP。正式连接仅允许内置的星火 HTTPS origin，不允许任意服务地址。

验证边界

Node 测试只使用本机临时服务、临时凭证和文件，已在 macOS 和 Linux amd64 容器运行。后端有隔离 PostgreSQL 的原账本与并发测试及真实 Redis 限流检查；网页授权有 mock 浏览器测试。macOS 已在获准测试账户完成真实图片、参考图续作、短视频、私有 OSS 下载及网页续作；这些属于 0.1.0 的历史证据。0.2.0 的新增功能尚需完整线上与 AI 宿主验收，不能据此宣称画布 100% 覆盖；Windows 实机和新版本真实 AI 宿主验收仍待完成。