melange-cli

Melange CLI

melange 是 Zetic.ai Melange 平台的 CLI（用于设备端 AI 模型部署和基准测试）。它以 Agent 为先：数据输出到 stdout，进度和诊断信息输出到 stderr，退出代码保持稳定，--json 输出精确到机器可读，但有文档说明的组合或脱敏结果除外。等待完成的上传/导入结果会将模型标识与最终状态组合，下载授权 URL 会对凭据进行脱敏。运行 melange help exit-codes 和 melange help formatting，查看权威说明。

MCP 服务替代方案

melange mcp 会将这些相同的操作作为 MCP 工具提供（默认使用 stdio；共享远程部署可使用 --transport http）。如果 Melange MCP 服务已连接到你的会话，对于其目录中的操作，优先使用它的工具，而不是通过 shell 调用 CLI。对于没有对应工具的操作（身份验证管理、将 model download 下载到磁盘、分桶的 .pt2 或 --input-manifest 上传、melange api），或者当服务通过 HTTP 连接且任务需要访问用户本地文件时，请使用 CLI——upload_model 工具仅在 stdio 下可用。权威工具参考——传输方式、各传输方式的身份验证、需确认的工具，以及写入范围拒绝规则——见 CLI 仓库 llms.txt 的 ## melange mcp 部分，以及 melange mcp --help；本文有意不重复这些内容。以下每条规则（非阻塞式转换监控、流水线面板、报告模板）都同样适用于通过 MCP 工具获取的数据。

身份验证

交互式使用时默认采用浏览器 OAuth——melange auth login 会打开浏览器（PKCE loopback、zoa_/zor_、自动刷新）；浏览器/显示环境不可用时，则回退到粘贴 PAT：

melange auth login                          # OAuth recommended (browser)
melange auth login --with-token < token.txt # PAT for CI/headless (ztp_...)
export MELANGE_API_KEY=ztp_...              # PAT env var also overrides stored OAuth
melange auth status --json                  # verify: exit 0 = authenticated

auth status 返回 4 表示未登录或令牌已被拒绝。在服务支持的情况下，auth status 也会显示账户套餐；melange plan 会详细报告套餐信息。 其他方式：MELANGE_API_KEY_FILE=/path/to/token（文件不可读时会明确报错；空文件在 OAuth 模式下会被忽略）、melange auth login --no-browser（为 SSH 输出 URL），或使用 --insecure-storage 将凭据存储在权限为 0600 的 config.yml 中。melange auth token 会输出解析后的令牌（stdout 不包含其他内容）。 设置 MELANGE_HOST 可指定非默认 API 主机。传入 --no-input 可确保不会出现交互式提示。

凭据优先级为 MELANGE_API_KEY > MELANGE_API_KEY_FILE（非空）> OAuth（keyring/config，自动刷新，zoa_/zor_）> PAT keyring > 旧版配置回退。

退出代码——据此分支处理

代码	含义	Agent 操作
0	成功	继续
1	API/网络/命令失败	可能是暂时性故障；CLI 已对幂等请求进行重试
2	用法错误（标志/参数错误）	调用命令时存在问题——修正命令，不要重试
4	身份验证错误（无令牌/令牌被拒绝）	修正凭据，不要重试
130	已中断（Ctrl-C）	已取消；中断的上传会保留其会话

输出契约

• --json：对于由服务端支持的命令，载荷保留 API 响应字节（保留字段名、顺序和未知字段），仅将终止符规范化为恰好一个尾随换行符。文档中说明的例外情况： model upload/import --wait 返回文档所述的 {"model": ..., "status": ...} 组合对象，而 model download 会将已签名的工件 URL 替换为 "<redacted>"。
• --jq EXPR（隐含 --json）：jq 筛选器；筛选后的值会以对象键排序的形式重新序列化；裸字符串会原样输出。
• --template TMPL（隐含 --json）：Go 模板，提供 tablerow、timeago、json 函数。
• 通过 --json/--jq 读取数据。在 TTY 中，供人类查看的数据会显示为对齐表格，表头下带分隔线，末尾附行数（通过管道传入分页器时，--format table 会强制使用该布局）；当 stdout 不是 TTY 时，会输出不带表头的制表符分隔值。单元格中的反斜杠、制表符、回车符和换行符会分别转义为 \\、\t、\r 和 \n；对于 Agent，始终优先使用 --json/--jq。
• 列表命令会输出分页封装对象 {"results": [...], "count": N}，并遵循相同的响应字节契约。--paginate（别名 --all）会将所有页面合并到一个封装对象中（顶层键随后按排序顺序重新序列化）。

标识符——不要混用

标识符	含义	获取方式
ACCOUNT/REPO	Melange 仓库地址	melange repo list
MODEL_KEY	仓库中的一个已转换模型版本	melange model list -R ACCOUNT/REPO
TARGET_ID	一个可下载的已转换工件；不透明的 tm_…/ltm_…	melange model targets MODEL_KEY -R ACCOUNT/REPO

它们按此顺序串联：repo → model key → target id。melange library view 中的 ACCOUNT/NAME 指向公开库模型，并非 MODEL_KEY。切勿用仓库名称、显示名称或 Hugging Face id 替代 MODEL_KEY 或 TARGET_ID，也切勿解析 TARGET_ID。

Hugging Face 模型：导入或工件

LLM 直接从 repo id 导入。通用模型以导出工件的形式提供。模型类型在 repo create 时固定，因此创建仓库前要先分类：

curl -fsSL "https://huggingface.co/api/models/OWNER/NAME" | jq -r .pipeline_tag

text-generation → 导入。其他所有类型（视觉、语音、嵌入、检测）→ 工件。如果标签缺失或含义不明确，请询问用户。

# LLM — import the repo id into an llm repository
llm_repo="$(melange repo create llama-1b --private --model-type llm --jq .full_name)"
melange model import meta-llama/Llama-3.2-1B -R "$llm_repo" --json

# General — export locally, then upload the artifacts to a general repository
gen_repo="$(melange repo create vit-base --private --jq .full_name)"
python export.py   # torch.export.save -> model.pt2; np.save -> input_0.npy
melange model upload -R "$gen_repo" model.pt2 --input input_0.npy --dry-run --json

在首次导出前，告知用户工件路径涉及哪些内容：在本地导出为 .pt2，并生成 .npy 示例输入；此过程会下载权重，需要 PyTorch >= 2.9，并会固定已部署模型可接受的输入形状。然后继续操作。导出代码片段及其必须满足的图约束，请参阅 https://docs.zetic.ai/model-preparation/pytorch-export。

核心工作流：创建仓库 → 上传 → 等待 → 查看状态

# 1. Create a repository (in the account behind your token)
repo="$(melange repo create whisper-tiny --private --jq .full_name)"

# 2. Preview the upload manifest first (no network calls)
melange model upload -R "$repo" model.onnx --input audio.bin --dry-run --json

# 3. Check the upload entitlement immediately before uploading.
#    `remaining` is what the server will actually allow now (spike headroom
#    included; null = unlimited). Preflight on it, not on limit-used.
upload_remaining="$(melange usage quotas --jq '.model_uploads.remaining // "unlimited"')" || exit $?
[ "$upload_remaining" != "0" ] || { echo "No model-upload quota remaining for this account" >&2; exit 1; }

# 4. Upload and wait once; preserve both identity and terminal status
upload_json="$(melange model upload -R "$repo" model.onnx \
  --input audio.bin --wait --json)" || exit $?
model_key="$(printf '%s\n' "$upload_json" | jq -er .model.key)" || exit $?
model_state="$(printf '%s\n' "$upload_json" | jq -er '.status.state')" || exit $?
test "$model_state" = ready || exit 1

# 5. Use the captured identifiers in later structured commands
melange model view "$model_key" -R "$repo" --json

对于分桶的 .pt2 模型，按输入组的相同顺序声明分桶。每个分桶必须包含相同数量的输入；在每个组内，顺序决定 input_index。先在不发起网络请求的情况下验证映射：

melange model upload -R acme/vision model.pt2 \
  --bucket 0:1x3x224x224 --input image224.npy --input mask224.npy \
  --bucket 1:1x3x384x384 --input image384.npy --input mask384.npy \
  --dry-run --json

样本输入是可选的。以下是有效的仅模型预检： melange model upload -R acme/repo model.onnx --dry-run。

过期上传 URL 的重新签发会有意生成新的签名 URL，且不会发送 Idempotency-Key；创建、完成和取消操作仍保留各自的重放密钥。

对于高级工作流，--input-manifest 使用的是 CLI 专用的本地文件文档，而不是公共 API 线缆清单。每个 path 都相对于清单文件解析，因此该文档不受进程 CWD 影响：

{
  "manifest_version": 2,
  "files": [
    {"path": "models/model.onnx", "role": "model"},
    {"path": "samples/audio.npy", "role": "input", "input_index": 0}
  ]
}

path 和 role 为必填项。filename 为可选项。对于输入文件，input_index 为可选项，默认按顺序设置。分桶清单会添加形如 {"index": 0, "dims": [1, 3, 224, 224]} 的 options.buckets 条目，并在每个输入上设置匹配的 bucket_index。然后运行：

melange model upload -R acme/whisper-tiny \
  --input-manifest ./upload/manifest.json --dry-run --json

• 每个 melange model 命令都必须指定 -R ACCOUNT/REPO —— 上传绝不会回退到默认仓库。
• --wait 会持续轮询，直到进入终态（默认 --timeout 30m）； 使用 --wait 时，退出码 1 表示转换失败或已超时。 单独执行 model status 是一次查询，无论状态如何，退出码均为 0。 上述工作流面向脚本编写。有人在等待时，应省略 --wait，改为在后台监控 — 请参阅“向用户展示结果”。
• 浏览仓库：melange repo list --search whisper --paginate、 melange repo list --jq '.results[].full_name'、 melange repo view acme/whisper-tiny --json。

浏览模型和目标

生成工件的运行时引擎不属于公共 API 的一部分。 melange model targets 会报告 precision、quant_type 和 compatibility.ap_types（cpu/gpu/npu），报告记录则使用不透明的 variant 标记代替引擎。切勿解析 variant，也切勿用引擎名称描述目标 —— 你并不知道引擎名称。

模型创建后，可以检查模型及其转换目标：

model_key=$(melange model list -R acme/whisper-tiny --jq '.results[] | select(.is_default) | .key')
melange model view "$model_key" -R acme/whisper-tiny --jq .download_ready
melange deploy guide "$model_key" -R acme/whisper-tiny --language android-kotlin --mode auto
melange model targets "$model_key" -R acme/whisper-tiny --json      # converted targets
melange model set-default "$model_key" -R acme/whisper-tiny         # pin the repo default
melange model import meta-llama/Llama-3.2-1B -R acme/llm --json  # interactive: returns at once, state converting
melange model import meta-llama/Llama-3.2-1B -R acme/llm --wait  # scripts: block until ready or failed
target_id=$(melange model targets "$model_key" -R acme/whisper-tiny --jq '.results[0].target_id')
melange model download "$model_key" -R acme/whisper-tiny --target "$target_id" --output ./models --yes

等待上传和导入的输出具有一种固定结构： {"model": <create/import response>, "status": <final ModelStatusResponse>}。 使用 .model.key 获取标识，使用 .status.state 获取终态结果。 不使用 --wait 时，每个命令都会保留原始的创建/导入响应。

model download 会产生费用，且在不同 CLI 进程间可安全重放 —— 中断后重试会复用已有扣费，而不会再次扣费。请传入 --yes； 否则命令会提示确认。若目标文件已存在，--output 不会覆盖，除非使用 --force；若授权后发现文件名冲突，命令会提示使用 --force， 且不会再次扣费。单个工件可使用 --output -，但切勿与结构化输出标记同时使用。临时工件 GET 请求会自动重试； 连续 30 秒没有字节传输进度就会触发重试，每个数据块都会重置计时器。签名 URL 和访问令牌绝不会被存储。

查看基准测试报告：melange report view

report view MODEL_KEY -R ACCOUNT/REPO 会读取模型的基准测试报告。 --type general|llm|package 用于选择报告；未指定时，CLI 会按 general → llm → package 的顺序探测，并显示第一个存在的报告（若均不存在， 则以退出码 1 报告“无可用报告”）。

model_key=$(melange model list -R acme/whisper-tiny --jq '.results[] | select(.is_default) | .key')

# The dashboard table on a TTY; --mode auto|speed|accuracy picks the cell value
melange report view "$model_key" -R acme/whisper-tiny --mode accuracy

# Agents: take the raw records, not the derived table
melange report view "$model_key" -R acme/whisper-tiny --json \
  --jq '[.records[] | select(.ap_type=="npu" and .metric=="latency_ms")]
        | group_by(.device.marketing_name)[]
        | {device: .[0].device.marketing_name, best: (map(.value)|min)}'

TTY 表格会根据原始记录重新计算仪表板的模式选择（速度 = 延迟最低； 准确率 = SNR 最高，平局时选延迟较低者；自动 = SNR 超过 20 dB 的最快运行， 否则选择速度模式）。非 TTY 输出为每行一条原始记录（包含扁平化的测量字段）——脚本获取的是测量数据，而不是计算后的表格。要获取准确响应，始终使用 --json。

报告涵盖账号可见的所有设备和精度下的整个模型。筛选到单一设备只是一个切片，并非完整报告 — 请参阅下文的“报告模型”。

向用户呈现结果

这些规则约束的是你为人类编写的答复，而不是你调用 CLI 的方式。 只要有人在等你，这些规则就适用；非交互式脚本仍使用阻塞形式。

转换时绝不阻塞

转换在服务端运行，耗时可能达数分钟。model import 和 model upload 不带 --wait 时，会在模型注册后立即返回，状态为 converting。带 --wait 时，则会一直阻塞，直到状态变为 ready 或 failed。在前台阻塞会让用户盯着停滞的命令，却不知道当前运行到哪个阶段。

因此：执行导入或上传时不带 --wait，立即回复流水线面板和剩余步骤，然后在后台轮询。

公开的转换状态机恰好有四种小写状态 — converting → optimizing → ready，或 failed。转换期间 stage 为 convert，优化期间为 benchmark。download_ready 在 optimizing 时变为 true，因此基准测试尚未结束时，模型已经可以使用。没有百分比：progress 始终为 null，因此绝不要编造百分比。非终止状态下，retry_after 是服务器建议的轮询间隔（5 秒）。这些状态不同于大写的上传会话状态 — 不要混用这两套状态名称。

按顺序在后台运行以下两个阶段：

# Stage 1 — returns the moment conversion finishes (~30m ceiling).
i=0
while [ "$i" -lt 360 ]; do
  state="$(melange model status "$model_key" -R "$repo" --jq .state)" || exit $?
  [ "$state" = converting ] || break
  i=$((i + 1)); sleep 5
done
melange model status "$model_key" -R "$repo" --json

报告状态转换，然后将后续工作交给 CLI 自带的等待程序：

# Stage 2 — exit 0 ready, 1 failed or timed out.
melange model status "$model_key" -R "$repo" --wait --timeout 30m --json

如果模型已经处于 converting 之后的状态，阶段 1 会立即返回，因此对于较早开始的转换，它也应作为正确的第一步。

流水线面板

每次导入、上传和检查状态后都要渲染面板，内容取自 .state。图标分别表示：✔ 已完成、◐ 进行中、○ 待处理、✖ 失败。

╭─ Conversion Pipeline ───────────────────────────────╮
│   ✔ CONVERTING   →   ◐ OPTIMIZING   →   ○ READY     │
│     complete           in progress       pending    │
╰─────────────────────────────────────────────────────╯

根据阶段替换图标和说明文字：已到达的阶段用 ✔ complete，当前阶段用 ◐ in progress，后续阶段用 ○ pending；到达 ready 后用 ✔ available；失败时用 ✖ failed，其后的阶段用 ○ blocked。

在面板旁用文字说明当前阶段：处于 converting 时，说明基准测试和打包尚未开始；处于 optimizing 时，说明基准测试结束前模型已可下载；处于 ready 时，指向报告和部署指南。若状态为 failed，根据 .stage 标出失败阶段，逐字引用 .failure_code，不要猜测代码未明确说明的原因。

报告模型

填写模板，并在回复中打印结果：

模型类型	模板
LLM	assets/report-llm.md
其他所有类型	assets/report-general.md

回答前先阅读模板，并保持其章节顺序。模板中包含每项数据对应的已验证 jq 表达式、舍入和缺失值处理规则，以及用户指定单台设备时的报告路径。

仪表板中的可部署性百分比是网页 UI 的阈值组件，背后没有对应的 API 字段。请说明该数据不可用，不要提供数字。

浏览公共库和你的用量

melange library list --task vision --provider Zetic --jq '.results[].full_name'
melange library view zetic/whisper-tiny --json     # includes the full readme
melange library providers --jq '.results[] | select(.model_count>=10) | .name'

melange usage --jq .prompts                        # this period's counters
melange usage quotas --jq .model_uploads.remaining # headroom now; null = unlimited
melange usage quotas --jq .credits                 # advisory credit balance
melange plan --jq .plan                            # legacy tier: free|lite|pro|pro_plus|enterprise
melange plan --jq .tier                            # pricing identity: free|pro|team|enterprise; null = legacy billing

library list 筛选条件会映射到查询参数（--task 可重复；匹配任意任务的模型都会包含在内）。其 --search 会在 name 和 full_name 中进行不区分大小写和分隔符的搜索；连字符、下划线、斜杠和空格均会被忽略。usage quotas 会将每项配额显示为 used/limit (pct%)；如果 limit 为 null，则显示为 unlimited；其 --json/--jq 输出还会为每个计数器提供 remaining，即服务当前实际允许的数量（包括突发余量，最低为 0；null = unlimited）。进行预检时，应优先使用 remaining，而不是 limit - used。

melange plan 会报告两种词汇体系。plan 是配额所依据的旧版套餐（free|lite|pro|pro_plus|enterprise）——也就是服务强制执行的套餐，与控制面板一致；绕过配额限制的账户会报告 pro_plus，且配额为 unlimited。tier 是当前的定价身份（free|pro|team|enterprise），仍采用旧版计费的账户会显示为 null；billing_generation（legacy|v3）表示由哪种系统管理。 max_model_bytes 仅预检套餐自身的模型大小权限——积分和欠款会在转换时单独检查。max_model_bytes 为 null 表示自定义合同，并非 unlimited（与 null 配额上限不同）：积分账本仍会拒绝超出自助服务大小上限的运行。tier 报告的是服务当前强制执行的套餐，因此，已过期的付费订阅会显示为 free，而 billing_generation 仍为 v3——这正是 free 套餐仍因 subscription_past_due 而拒绝请求的组合。

权益说明（必需）

上传模型或声称基准测试覆盖完整之前，请先检查 melange usage quotas --json。如果 model_uploads.remaining == 0，请勿尝试或重试上传：应告知用户当前套餐下已没有剩余上传配额，而不是说 CLI 出了问题。报告记录只包含已认证账户可见的设备；除非已确认完整性，否则绝不可称其为完整基准测试。

套餐身份是可确定的——从 melange plan --jq .plan（定价身份则查看 .tier；若为 null，表示旧版计费）读取。如果 model_uploads.remaining == 0 且套餐为 Free（或 Lite），请说明模型上传被锁定是因为套餐限制；其他套餐则应说明月度上传配额已用尽。不要将配额归零归因于错误原因：应检查 melange plan，而不是根据零上限、筛选后的报告或 HTTP 错误推断为 Free。

积分会限制转换，且仅供参考：使用 melange usage quotas --jq '{credits: .credits.available, debt: .credits.outstanding_debt}' 进行预检。 .credits.available > 0 且 .credits.outstanding_debt == 0 是必要条件，但并非充分条件——每次转换的费用会随模型大小增加，因此即使余额为正，大模型仍可能被拒绝。应根据机器可读的 error.code 分支处理，而不是根据状态码：HTTP 402 billing_error 对应 credit_balance_exhausted（充值，不会扣费）或 subscription_past_due（修复付款方式）；HTTP 409 conflict_error 对应 credit_debt_outstanding（在控制面板结清欠款）；HTTP 413 request_too_large 对应 custom_model_too_large（超出套餐自身的模型大小权限——检查 melange plan）或 credit_model_too_large（超出自助服务大小上限，无法通过任何积分余额提高上限——联系支持）。上传完成请求被拒绝后，会话会保留并可恢复——解决问题后，重新执行： melange model upload --resume SESSION_ID -R ACCOUNT/REPO。

库中的 ACCOUNT/NAME 值标识的是公共仓库，而非已转换的模型键。可直接检查其中现有的模型和报告；这是只读路径，无需导入或上传：

repo=$(melange library list --search QUERY --jq '.results[0].full_name')
key=$(melange model list -R "$repo" --jq '.results | (map(select(.is_default and .state=="ready")) + map(select(.state=="ready")))[0].key // empty')
[ -n "$key" ] || { echo "No ready model is available in $repo" >&2; exit 1; }
melange report view "$key" -R "$repo" --json

读取库模型的公开基准测试无需导入或上传——上述路径就是全部操作。

获取精确的部署代码

使用选定的模型密钥（而非 Hugging Face ID）请求部署代码。 支持的语言为 android-kotlin、android-java、ios-swift、 flutter 和 cpp；推理模式为 auto、speed 和 accuracy。

melange deploy options --json
repo=shinilheo/LFM2.5_350M
key=$(melange model list -R "$repo" --jq '.results | (map(select(.is_default and .state=="ready")) + map(select(.state=="ready")))[0].key // empty')
[ -n "$key" ] || { echo "No ready model is available in $repo" >&2; exit 1; }
melange deploy guide "$key" -R "$repo" --language android-kotlin --mode auto
melange deploy guide "$key" -R "$repo" --language ios-swift --mode speed --json

纯文本指南采用有序 Markdown，包含可复制的 SDK 安装和推理代码片段；--json 则返回结构化响应。仓库坐标、版本、系列、模式和 SDK 语言均已解析。通用模型的张量创建明确留作 TODO——形状和预处理因模型而异，因此请检查张量 I/O 元数据，而不要臆造输入。请使用指南自身列出的 SDK 字段和回调；不要添加指南未提及的内容。

对于在 Android arm64（包括 Qualcomm SW6100）上运行的独立 C++ 程序，请请求 --language cpp --mode auto。指南包含 SDK ZIP 下载链接、构建说明和推理代码。使用 library list 和 model list 查找现有模型；部署库中的模型无需重新导入。合作伙伴开发板必须能够从 Agent 访问，并能够通过 HTTPS 下载。请遵循返回的构建说明，包括共享 C++ 运行时。

每份指南都使用 YOUR_PERSONAL_KEY。命令绝不会插入、打印或持久化当前 PAT。不要在聊天、日志、生成的 JSON 或 shell 历史记录建议中替换此占位符。

中断后继续

中断上传（退出码 130）会在服务端保留会话，CLI 会在 stderr 上打印确切的恢复命令。如果无法再获取该输出，可从会话列表中推导不透明 ID：

session_id=$(melange model upload --sessions -R acme/whisper-tiny --jq '.results | map(select(.state=="CREATED" or .state=="UPLOADING")) | first | .id // empty')
[ -n "$session_id" ] || { echo "No resumable upload session found" >&2; exit 1; }
melange model upload --resume "$session_id" -R acme/whisper-tiny

优先使用中断时打印的确切命令行——已上传的字节绝不会重新发送。清理操作：melange model upload --sessions -R acme/repo 可列出会话。在终端上取消时，系统会提示输入确切的会话 ID；Agent 和其他非交互调用方必须传入 --cancel SESSION_ID --yes。

备用方式：melange api

调用任何尚未由专用命令封装的 /v1 端点。传输方式与其他命令相同：使用已存储的凭据，对 GET/HEAD/PUT 请求以及任何带有 Idempotency-Key 标头的请求自动重试，并采用标准错误封装。原始 PATCH 请求需要带有 Idempotency-Key 才会重试。

melange api /v1/me --jq .account.name          # GET, extract one value
melange api /v1/repos -F name=demo -F is_private=true   # fields => POST
echo '{"name":"demo"}' | melange api /v1/repos --input -  # raw body
melange api /v1/models -F name=demo -H 'Idempotency-Key: 0698c9b1'
melange api -X GET /v1/repos -f search=whisper --include  # query params

路径必须相对于已配置的主机，并解析到 /v1 下（绝对 URL 以及 /v1 之外的任何路径都会被拒绝，退出码为 2——凭据绝不会离开已配置的主机或其公共 API）。-f 添加字符串字段，-F 添加类型化字段（true/false/null/整数；@path 插入文件内容；key[sub]=v 用于嵌套；key[]=v 用于追加数组）。除非传入 -X GET（此时字段会成为查询参数），否则添加字段会将方法切换为 POST。即使响应正文为非 2xx，也会打印到 stdout，并在 stderr 上给出一行摘要；分页和轮询需要由你负责。

注意事项

• 上传前先使用 --dry-run，以低成本验证清单。
• MELANGE_DEBUG=1 会将请求/响应行记录到 stderr（绝不会记录令牌和标头）。
• MELANGE_API_TIMEOUT 限制普通 API 请求的时长（默认值为 30s）；上传无活动超时和转换的 --wait 使用单独的超时标志。
• melange api 只有在完整读取响应正文后才会提交成功输出。对于确实较慢或较大的响应，请增大 MELANGE_API_TIMEOUT；读取失败时 stdout 会保持为空，而不会输出部分数据。
• 当有人在等待时，绝不要在前台运行 --wait；不带该选项执行导入或上传，报告阶段，并在后台监控。
• 绝不要展示响应中未提供的指标。在表格中将其显示为 -，在卡片中显示为 N/A，以明确呈现缺失情况；也绝不要将不同加速器测得的数值进行比较，并把其中一个说成提速结果。
• 报告整个模型，而非单个设备：汇总值是所有设备中的最佳值，因此用设备名称标注会错误归属测量结果。在回复中直接打印报告，不要将其保存到文件。