MetaDig Skills

用 metadig 命令行调用 MetaDig（元界深掘，waytometa.cn）平台生成 AI 图片、视频、语音（TTS）和音乐，产物自动落到用户的网页画布项目。当用户要出图、出片、配音、配乐、批量生成素材、查询可用模型与积分价格、查生成任务进度，或提到 metadig / MetaDig / 元界深掘 / waytometa 时使用。Use when the user wants AI images, videos, speech or music generated through MetaDig, or mentions the metadig CLI.

MetaDig CLI（metadig）

metadig 是 MetaDig（元界深掘，https://waytometa.cn）的命令行工具：登录一次，之后在终端里一行命令提交图片 / 视频 / 语音 / 音乐生成任务。产物默认直接落到用户网页画布项目的节点上（提交即出现「生成中」占位节点，完成后自动回填），用户可以在网页上继续编辑成片。生成消耗账号积分，计费、模型、折扣、会员门禁与网页端完全一致。

本 Skill 只走 metadig 命令。不要自己拼接 waytometa.cn/api 下的接口，也不要猜测模型 ID 或参数——模型、价格、参数档位都以 metadig models 的实时输出为准。

安装与登录（一次性）

先看是否已装好：metadig --version。没有则安装，装完重开终端让 PATH 生效。

bash

# macOS / Linux
curl -fsSL https://waytometa.cn/cli/install.sh | bash

# Windows PowerShell
iwr https://waytometa.cn/cli/install.ps1 -useb | iex

登录走浏览器授权，终端不经手密码：

bash

metadig login          # 打印授权链接并尝试打开浏览器，用户在网页上点「授权登录」
metadig whoami         # 确认账号与积分余额

• 无法打开浏览器（服务器 / 容器 / 远程会话）：metadig login --no-open 只打印链接，让用户在任何已登录设备上打开授权；仍不行时让用户设置环境变量 METADIG_TOKEN（值为访问令牌）或执行 metadig login --token <令牌>。
• 凭证存本机 ~/.metadig/credentials.json（约 30 天有效）。命令报「尚未登录」或「登录已过期」→ 重新 metadig login。
• CLI 登录与用户的网页登录并存，不会把网页登录顶掉。

命令速查

bash

metadig models                       # 全部模型 + 积分价格 + 标签（会员 / 停用 / 新 / 折扣）
metadig models --type video          # 只看视频模型（image / video / tts / music）
metadig models <模型ID>              # 单模型参数档位：比例 / 分辨率 / 时长 / 渠道 / 参考上限
metadig models --json                # 机器可读全量目录（Agent 优先用）

metadig gen image "<提示词>" --ratio 16:9 --resolution 2K -n 2
metadig gen image "<提示词>" -r ./ref.png -m <模型ID>          # 带参考图 = 图生图
metadig gen video "<提示词>" -m <模型ID> --resolution 720p -d 5   # 文生视频
metadig gen video "<提示词>" --first ./cover.png -d 5 -o ./exports # 首帧生视频
metadig gen video "<提示词>" --first a.png --last b.png             # 首尾帧
metadig gen video "<提示词>" -r role.png --ref-video demo.mp4       # 参考生视频
metadig gen speech "<文本>" --voice male-qn-qingse                  # 语音（TTS）
metadig gen music "<风格描述>" --lyrics "<歌词>" -d 40              # 音乐

metadig status <任务ID>                    # 状态 + 产物 URL
metadig status <任务ID> --wait -o ./exports # 等完成并下载
metadig download <任务ID> -o ./exports
metadig history                            # 近 7 天任务（不含 URL）
metadig upload ./a.png ./b.mp4             # 手动上传素材换公网 URL（一般不需要）

metadig project list | create "<名称>" | use <项目ID> | current

生成命令通用参数：-m 模型、-p 项目、-o <目录> 完成后下载、--no-wait 提交即返回、--no-canvas 不建画布节点（只进「历史文件」）、--json 机器可读输出。

关键工作流

出图

1. metadig models --type image --json 看可用模型、每张积分（creditsMap 按分辨率分档）、比例与分辨率档位。
2. 按用户需求选模型；用户没指定就用目录里第一个可用的（目录已按平台推荐排序）。
3. metadig gen image "<提示词>" --ratio <比例> --resolution <档位> -n <张数> --json。有参考图就加 -r <本地文件或 URL>（可重复），CLI 自动上传本地文件。
4. 从 JSON 的 urls 取图片链接，files 是 -o 时的本地路径，nodeId 是画布节点 ID。把链接和「已落到画布」一并告诉用户。

出片（视频）

1. metadig models --type video --json 看模型支持的方式（modes：文生 / 首帧 / 首尾帧 / 参考）、分辨率、时长与价格（creditsMap 键 "<渠道>:<时长>s:<分辨率>" 的值就是该时长总价，带声音另有 creditsMapWithAudio）。
2. 按素材定方式，不用单独指定：无素材 = 文生；一张图 = --first；首尾两张 = --first + --last；要保持人物 / 风格 / 用参考视频 = -r / --ref-video / --ref-audio。--first 与 --ref 系列不能混用。
3. 先报方案再提交：视频一条通常几十积分起，高分辨率、长时长、带参考视频都会加价。把「模型 + 分辨率 + 时长 + 条数 + 预计积分」告诉用户，确认后再跑。
4. metadig gen video "<提示词>" [素材参数] -m <模型ID> --resolution 720p -d 5 --json，默认等待完成（几分钟很正常，进度在 stderr）。多条任务可先 --no-wait 全部提交，再逐个 metadig status <任务ID> --wait --json。

配音与音乐

• 语音：metadig gen speech "<文本>" --voice <音色ID>，按 200 字计价。音色 ID 见 references/generation-guide.md；用户没说就用默认音色。
• 音乐：metadig gen music "<风格描述>" --lyrics "<歌词>" -d 40，纯音乐加 --instrumental。按 5 秒计价的模型可以 -d 改时长（会钳进模型范围），按首计价的模型 -d 会被忽略。

批量生成

先 metadig models 查价并算总积分报给用户，确认后逐条提交。同一批任务用 --no-wait --json 提交后统一等待，避免一条卡住拖住全部。任务失败不扣积分，但不要原样重提——先看 status 里的说明再改参数。

本地素材

-r / --first / --last / --ref-video / --ref-audio 直接给本地路径，CLI 自动上传换成公网 URL；给 http(s):// 则原样使用。只有想提前拿到 URL 复用时才用 metadig upload。

归到指定项目

任务默认进自动创建的「CLI 项目」画布。用户想分项目管理时：metadig project create "<名称>" → metadig project use <项目ID>（绑定当前目录，写 .metadig/project.json，子目录也生效）；单次任务用 -p <项目ID>。

重要规则

1. 生成前先查模型：模型、价格、档位会变，永远以 metadig models 实时输出为准，不凭记忆写模型 ID；-m 传了目录里没有的模型会直接报错并列出可用清单。
2. 机器解析用 --json：结果只在 stdout，进度与提示都在 stderr，管道干净。
3. 视频先报价再跑：批量或高价任务先向用户报方案与预计积分，用户确认后再提交。
4. 失败不扣费，但别原样重试：任务失败 / 取消不扣积分；先看 status 的说明，改参数再试。
5. 提交超时 ≠ 失败：提示「提交请求超时，结果不确定」时任务可能已受理并预扣积分，先 metadig status <任务ID> 查，别重复提交。相同参数在进行中重提会被拦截（「相同内容正在生成中」）。
6. 积分不足不重试：报「积分不足」就停下来告诉用户去网页充值或订阅，CLI 里无法充值。
7. 会员专属 / 维护中：换 metadig models 里其他可用模型；会员专属模型需要用户订阅，不要反复提交。
8. 不拼内部接口：一切能力都经 metadig 命令；命令缺失或行为不符先重跑安装脚本升级 CLI，不要绕过去调 API。
9. 不臆造参数：不确定的 flag 先 metadig <命令> --help 或查 references/。传了不在档位内的比例 / 分辨率 / 时长只会得到 stderr 警告，最终以服务端校验为准。
10. 产物默认进画布：用户不想弄乱画布时加 --no-canvas（产物只进项目「历史文件」）。
11. 只在用户自己的设备上授权：不要把授权链接发给第三方；令牌只放环境变量，不写进文件或对话。

排错速查

• 尚未登录 / 登录已过期或无效 → metadig login；无浏览器 → METADIG_TOKEN。
• 积分不足 → 停止，提醒用户充值。
• 该模型/渠道正在维护中 / 该模型为会员专属 → 换 metadig models 里其他模型。
• 模型 X 不支持<方式> → 该模型不支持这种生成方式，按错误提示里的可用清单换模型。
• --last 需要与 --first 搭配 / --first/--last 与 --ref 系列不能同时使用 → 按素材重新选方式。
• 等待超时（2 小时） → 任务可能仍在生成，稍后 metadig status <任务ID>。
• 想连本地 / 测试环境 → 全局参数 --api-base http://localhost:6603 或环境变量 METADIG_API_BASE。

更多见 references/common-pitfalls.md。

深度指南（references/）

文档	何时阅读
references/cli-command-guide.md	不确定某个命令的完整参数、环境变量、配置文件位置、JSON 输出字段或任务状态含义
references/generation-guide.md	需要按需求选模型、估算积分、确认视频方式与参数约束、音色 ID，或想知道产物如何落画布 / 项目
references/common-pitfalls.md	遇到登录、超时、积分、模型不可用、上传、下载等报错，或行为与预期不符