matvenus CLI 指南

晓鹜开放平台的接入、提交与私有结果。

matvenus CLI 手册

在 Linux、macOS 或 Windows 上使用 matvenus 命令行客户端。本手册只包含终端命令。

01

配置 CLI

使用平台提供的、与操作系统匹配的版本化 matvenus 可执行文件。先验证客户端,再配置 HTTPS API 源地址。

cli-setup复制cli-setup 示例
matvenus version
matvenus config set api-url https://YOUR_PLATFORM
matvenus config show
02

用 API 密钥登录

在浏览器账户中创建密钥,再用 login 将其存入操作系统凭证存储。自动化场景可通过 stdin 提供密钥。绝不要把真实密钥写入共享命令或源文件。

cli-login复制cli-login 示例
matvenus login
matvenus auth status
matvenus whoami

# Automation reads a key from protected stdin.
matvenus login --with-key-stdin
03

查看工具

列出已发布版本,并在创建请求文件前阅读工具契约。

cli-tools复制cli-tools 示例
matvenus tools list
matvenus tools show protein_properties_physicochemical \
  --tool-version 2026-10-14-candidate
matvenus tools schema protein_properties_physicochemical --tool-version 2026-10-14-candidate
04

上传与下载文件

客户端会校验传输。任务请求中使用 READY 文件 ID。下载不会覆盖已存在的输出路径。

cli-files复制cli-files 示例
matvenus files upload ./protein_panel.fasta
matvenus files list --status READY
matvenus files show FILE_UUID
matvenus files download FILE_UUID --output ./downloaded.fasta
05

提交并等待

为每个逻辑任务使用一个明确的提交密钥。把它保存在 CLI 进程之外,以便中断后重试能恢复原任务。

将下方版本化示例中的完整 request.json 保存下来。其中的提交、等待与结果命令使用该确切载荷与版本。

06

跟踪任务并读取结果

本地等待超时或 Ctrl+C 会停止等待,但不会取消远程任务。请继续使用已受理的任务 ID。

jobs download 只适用于声明的输出文件。理化性质示例没有输出文件;请用 jobs result 获取其 JSON。

cli-results复制cli-results 示例
matvenus jobs list --status RUNNING
matvenus jobs show "$JOB_ID"
matvenus jobs wait "$JOB_ID" --timeout 5m
matvenus jobs result "$JOB_ID"
matvenus jobs download "$JOB_ID" \
  --file-id FILE_UUID --output ./result.csv
07

取消任务

该命令只是请求取消。请持续检查任务直到确认停止。按次工具只对成功交付的任务收费。

cli-cancel复制cli-cancel 示例
matvenus jobs cancel "$JOB_ID"
matvenus jobs show "$JOB_ID"
08

JSON 输出与自动化

使用 --json 获取机器可读的 stdout。诊断信息写入 stderr。结果不确定后复用同一提交密钥与载荷。

账户统计使用 /developers/api#usage 中描述的 REST 用量与消费报表。创建期间费用不同于结算期间消费;当前余额与活跃是独立快照。null、零与未核实用量始终区分。请使用已有的余额与任务命令,或经认证的 REST 报表。不提供新的 CLI 统计或整单导出命令。

cli-automation复制cli-automation 示例
matvenus --json balance
matvenus --json jobs show "$JOB_ID"
matvenus --json jobs result "$JOB_ID"
matvenus logout

完整示例:蛋白性质

protein_properties_physicochemical@2026-10-14-candidate

正在检查该示例版本当前是否已发布…

用途与输入规则

从一条蛋白序列计算理化特征:长度、分子量、理论 pI 与氨基酸组成,以 JSON 返回。

该版本只返回理化特征,不生成蛋白结构,也不输出文件。公开示例是教学材料,不是一次新的计算,也不构成质量评估。

  • sequence 与 fasta_file 必须且只能提供一个;另一个请省略或设为 null。同时提供或都不提供都会被拒绝。
  • sequence 不能为空,且只能使用大写 ACDEFGHIKLMNPQRSTVWY。FASTA 必须包含一条非空序列并使用同一字母表;包含多条记录会被拒绝。
  • task_name 固定为 Physical and chemical properties。省略时使用默认值,或按原样传入该常量;不支持其他任务。
  • fasta_file 请使用属于本账户且状态为 READY 的文件。接受的格式为 fasta、fa 与 faa。本地路径不是 file_id。
  • 工具输入上限为 134217728 字节。直接提交 JSON 任务(含元数据)上限为 131072 字节(128 KiB)。序列更大时请改用文件上传与 READY 引用。结构化结果上限为 65536 字节。

版本 2026-10-14-candidate。将下方完整公开请求体保存为 request.json。

将 MATVENUS_API_URL 设为你的 HTTPS 平台基础地址,并把 MATVENUS_API_KEY 放在受保护的环境中(或使用已有 CLI 登录)。为这个逻辑任务设置新的唯一 SUBMISSION_KEY;重试时保留同一密钥与完全相同的请求。新任务需要新密钥。

request.json复制公开序列请求
{
  "tool_id": "protein_properties_physicochemical",
  "tool_version": "2026-10-14-candidate",
  "parameters": {
    "sequence": "ACDEFGHIKLMNPQRSTVWY"
  }
}

matvenus CLI

请逐条执行命令:先核对确切版本并提交 request.json,再将 JOB_ID 设为回执中的 id。超时不会创建新任务;等待 SUCCEEDED 后再读取结果。

CLI · submit and read复制CLI 调用
matvenus --json tools show protein_properties_physicochemical --tool-version 2026-10-14-candidate
matvenus --json jobs submit --input request.json --submission-key "$SUBMISSION_KEY"
matvenus --json jobs show "$JOB_ID"
matvenus --json jobs wait "$JOB_ID" --timeout 5m
matvenus --json jobs result "$JOB_ID"

HTTP 202 表示已受理。即使客户端超时也请保留 Job ID。结果未就绪时返回 409,删除或过期后返回 410。失败或取消的任务可能没有结果。冲突重试返回 409;请检查原任务而非重新提交。

改用 FASTA 文件

将这份公开单记录样本保存为 public-sample.fasta,通过 REST 或 CLI 上传;MCP 不能上传二进制文件。确认返回的文件属于你的账户且状态为 READY。

此处展示的预期 JSON 对应直接序列输入,其 sequence_id 为 temp_sequence。使用 FASTA 输入时,sequence_id 来自记录头;本示例 FASTA 使用 public-sample。序列标识与平台任务 ID 是两回事。

public-sample.fasta复制公开 FASTA 样本
>public-sample
ACDEFGHIKLMNPQRSTVWY

先执行上传命令,再将 FILE_ID 设为返回的 id,并确认文件状态为 READY。

CLI · upload and check READY复制CLI 文件上传
matvenus --json files upload ./public-sample.fasta
matvenus --json files show "$FILE_ID"

将文件 ID 占位符替换为该 READY 的 UUID,再存为 request.json 并用上面的 REST 或 CLI 步骤提交。这个不同的逻辑任务需要使用新的提交密钥。此时省略 sequence。

request.json · READY file variant复制就绪文件请求
{
  "tool_id": "protein_properties_physicochemical",
  "tool_version": "2026-10-14-candidate",
  "parameters": {
    "fasta_file": {
      "file_id": "REPLACE_WITH_READY_FILE_UUID"
    }
  }
}
公开样本来源

仓库中的版本化材料;这些样本不能证明工具当前可用,以启用目录为准。

  • worker_groups/protein-properties-physicochemical/candidate-contract.jsonSHA-256: 17f0d36cc81729a3dcf225813df8253213faf19905ec99409962d1d33632497e
  • worker_groups/protein-properties-physicochemical/public/sequence-request.jsonSHA-256: 83bbe6829d85d48aa0446a8646232b97012af7d058707a232c9057f7b1a1abe4
  • worker_groups/protein-properties-physicochemical/public/expected-sequence-result.jsonSHA-256: 0353c5c39d8d9a9f0ae278655ba536f99611e112a41d3a064d8df885b76cb7f2
  • worker_groups/protein-properties-physicochemical/public/public-sample.fastaSHA-256: 27b4df93ee69cfe9d6d92bc808a99f21a8272c20b3daab602138ec0d94e5df83

理解 JSON 结果

公开序列的完整预期输出。这是已存储的公开样本,不是本页面执行的计算。该版本没有输出文件。

expected-sequence-result.json复制公开预期结果
{
  "data": {
    "sequence_id": "temp_sequence",
    "sequence_length": 20,
    "molecular_weight": 2395.71,
    "theoretical_pI": 6.78,
    "aromaticity": 0.15,
    "instability_index": 84.74,
    "gravy": -0.49,
    "secondary_structure_fraction": {
      "helix": 0.25,
      "turn": 0.25,
      "sheet": 0.35
    },
    "amino_acid_composition": {
      "A": 0.05,
      "C": 0.05,
      "D": 0.05,
      "E": 0.05,
      "F": 0.05,
      "G": 0.05,
      "H": 0.05,
      "I": 0.05,
      "K": 0.05,
      "L": 0.05,
      "M": 0.05,
      "N": 0.05,
      "P": 0.05,
      "Q": 0.05,
      "R": 0.05,
      "S": 0.05,
      "T": 0.05,
      "V": 0.05,
      "W": 0.05,
      "Y": 0.05
    }
  },
  "success": true
}
名称类型必填说明
successtrue是有效的交付结果要求 success=true 且 data 非空。空对象对该工具不是有效结果。 · 固定为 true
dataobject是不允许其他属性
data.sequence_idstring是结果中的序列标识,与平台任务 ID 不同。 · 最短长度 1
data.sequence_lengthinteger是以氨基酸残基计的序列长度。 · 最小值 1
data.molecular_weightnumber是分子量。契约未声明单位,待维护者确认。 · 大于 0
data.theoretical_pInumber是理论等电点(pI),范围 0–14。 · 0–14(含边界)
data.aromaticitynumber是芳香性数值,范围 0–1。以原始比值显示,不是百分比。 · 0–1(含边界)
data.instability_indexnumber是报告的不稳定指数;不推断稳定性评级。
data.gravynumber是报告的 GRAVY 亲水性指数;不推断质量评级。
data.secondary_structure_fraction · 3 个字段 · 必填

螺旋、转角与折叠的占比,各自 0–1。它们不必相加为 1,也不代表已生成的结构。 · 不允许其他属性

名称类型必填说明
data.secondary_structure_fraction.helixnumber是0–1(含边界)
data.secondary_structure_fraction.turnnumber是0–1(含边界)
data.secondary_structure_fraction.sheetnumber是0–1(含边界)
data.amino_acid_composition · 20 个字段 · 必填

二十种氨基酸的占比,各自 0–1。二十个字母键均为必填;0.05 表示占比 5%。 · 不允许其他属性

名称类型必填说明
data.amino_acid_composition.Anumber是0–1(含边界)
data.amino_acid_composition.Cnumber是0–1(含边界)
data.amino_acid_composition.Dnumber是0–1(含边界)
data.amino_acid_composition.Enumber是0–1(含边界)
data.amino_acid_composition.Fnumber是0–1(含边界)
data.amino_acid_composition.Gnumber是0–1(含边界)
data.amino_acid_composition.Hnumber是0–1(含边界)
data.amino_acid_composition.Inumber是0–1(含边界)
data.amino_acid_composition.Knumber是0–1(含边界)
data.amino_acid_composition.Lnumber是0–1(含边界)
data.amino_acid_composition.Mnumber是0–1(含边界)
data.amino_acid_composition.Nnumber是0–1(含边界)
data.amino_acid_composition.Pnumber是0–1(含边界)
data.amino_acid_composition.Qnumber是0–1(含边界)
data.amino_acid_composition.Rnumber是0–1(含边界)
data.amino_acid_composition.Snumber是0–1(含边界)
data.amino_acid_composition.Tnumber是0–1(含边界)
data.amino_acid_composition.Vnumber是0–1(含边界)
data.amino_acid_composition.Wnumber是0–1(含边界)
data.amino_acid_composition.Ynumber是0–1(含边界)