CLI 参考

darra-studio 是 Darra AI Studio 的命令行入口，无界面跑通项目、模型、数据集、训练、蒸馏、评估、推理、发布、登录态与环境检查。它调用与 Studio 客户端同一套服务层，不是另一条业务链路。

用法以 darra-studio --help 为准；本页给出完整参数表、输出契约与可照抄示例。

备注

命令行不做 GUI 的替代：标注界面、抠图界面这类交互能力仍在 Studio 客户端。命令行覆盖的是可脚本化的建项目 → 导数据 → 训 / 蒸 / 评 / 推 / 发链路。

安装与快速开始

darra-studio.exe 随 AI Studio 应用包交付，与 Darra.AI.Studio.exe 同目录。系统要求与 安装 一致：Windows 10 / 11 x64、.NET 8 Desktop Runtime x64。

把该目录加入 PATH 后可直接敲 darra-studio；不加则用完整路径调用。

# 看版本与总用法
darra-studio --version
darra-studio --help

# 环境就绪检查（转调 darra-env-setup --check，不安装）
darra-studio env

# 登录态与 Studio 客户端共用；商用加密/发布前先确认
darra-studio auth status

darra-studio project new --name demo --dir /d/work
darra-studio model import --file /d/weights/yolov8n.pt
darra-studio infer yolov8n --image /d/photos/a.jpg

全局开关

写在命令组前后均可；--project 也可放在命令组前面。

开关	说明
--json	机器可读结果信封，stdout 只出一份 JSON；进度行走 stderr，不污染结果
--quiet	stdout 只打退出码数字；失败原因仍写 stderr
--project <目录>	目标项目目录。优先于环境变量 DARRA_STUDIO_PROJECT；都没有则用最近打开的项目
--help, -h	显示帮助。命令组后跟 --help 显示该组用法
--version, -v	显示版本

别名：darra-studio login 同 auth login；darra-studio encrypt 同 model encrypt。

项目解析顺序（多数动作依赖当前项目）：--project <目录> → 环境变量 DARRA_STUDIO_PROJECT → 最近打开的项目。按模型 ID / 数据集 ID 查找时必须先解析到项目；直接给权重文件路径的推理不受此限。

提示

脚本集成用 --json 判结构化结果，用退出码判成败；只关心成败时用 --quiet。

命令组总览

命令组	动作	说明
project	new | open | list | save | info	项目管理
model	import(add) | list | info(show) | convert | export | encrypt | delete(remove)	模型管理
dataset	import | list | info | clean | label-auto	数据集管理与自动标注
train	start | stop | status | history	训练
distill	start	蒸馏（教师→学生）
eval	run | report	评估与报告
infer	infer	单图或批量推理
publish	publish	发布模型产物到 GitLab 模型库
auth	status | login	登录态（与 Studio 客户端共用）
env	env	环境就绪检查（转调 darra-env-setup --check）

---

project — 项目

darra-studio project new --name <名称> [--dir <父目录>] [--description <描述>]
darra-studio project open <目录>
darra-studio project list
darra-studio project save
darra-studio project info

动作	说明
new	在父目录下建 <名称> 文件夹并写 project.json，随后设为当前项目
open	打开目录里的项目，并记入最近项目
list	列出最近打开过的项目
save	保存当前项目
info	显示当前项目的元数据

选项	必给	说明
--name <名称>	new	新项目名称，作项目文件夹名
--dir <父目录>	否	新项目建在该父目录下（缺省当前目录）
--description <描述>	否	项目描述
--project <目录>	否	save / info 认的目标项目目录

darra-studio project new --name demo --dir D:\work --description 产线视觉
darra-studio project info --project D:\work\demo

--json 的 data：project / projectName（new、open）；projects[] + count（list）；name / description / schema / createdUtc / modifiedUtc / models / datasets / trainingHistory / inputWidth / inputHeight（info）。

---

model — 模型

darra-studio model import --file <权重文件> [--name <显示名>] [--task <任务类型>]
darra-studio model list
darra-studio model info <模型ID>
darra-studio model convert --model <ID> [--imgsz <尺寸>]
darra-studio model export --model <ID> --to <onnx|engine|openvino> [--out <目录>]
darra-studio model encrypt --model <ID> --password <口令> [--level fast|slice]
darra-studio model encrypt --file <路径> --password - [--level fast|slice]
darra-studio model delete <模型ID>

动作	别名	说明
import	add	从本地权重文件导入项目模型库（.onnx / .pt / .pth 等）
list		列出当前项目的模型
info	show	查看模型基础信息与体检（格式 / 任务 / 保护 / 输入 / 架构 / 类别数 / 可推理性）
convert		.pt / .pth 转 ONNX
export		导出到目标格式
encrypt		商用加密签发 .darmodel
delete	remove	移除项目内模型引用，权重文件保留在磁盘

选项	用于	说明
--file <权重文件>	import / encrypt	本地权重文件路径
--name <显示名>	import	显示名（可选）
--task <任务类型>	import	任务类型（可选）
--model <ID>	convert / export / encrypt / delete	项目内模型 ID
--imgsz <尺寸>	convert	转 ONNX 的输入边长
--to <onnx|engine|openvino>	export	目标格式
--out <目录>	export	导出目录
--password <口令>	encrypt	商用加密口令。--password - 从标准输入读一行，不回显
--level fast|slice	encrypt	加密级别

darra-studio model import --file D:\weights\yolov8n.pt --name 产线检测
darra-studio model list
darra-studio model convert --model m-001
darra-studio model export --model m-001 --to engine --out D:\work\demo\exports
darra-studio model encrypt --model m-001 --password -

备注

• export 目标只有 onnx / engine / openvino；TFLite 转换当前未提供，如实拒绝。
• convert 只做 PT→ONNX。加密容器 / TFLite / RKNN 载体不参与转换，请用明文 ONNX 或 PT 权重。
• encrypt 走与 Studio 同一商用签发链（云端签票 + 签后验票），需登录 + 商用资格。未登录时用 auth status 查看，并在 Darra AI Studio 客户端完成登录后重试。

--json 的 data：modelId / file（import）；models[] + count（list）；modelId / modelName / format / task / protection / inputWidth / inputHeight / inputChannels / classCount / labels / architecture / weightPath / weightFormat / runnable（info）；onnxPath / route（convert）；target / artifactPath / outDir（export）；encryptedModelId / darmodelPath / verified（encrypt）。

---

dataset — 数据集

darra-studio dataset import --dir <数据集目录> [--name <显示名>]
darra-studio dataset list
darra-studio dataset info <数据集ID>
darra-studio dataset clean <数据集ID> [--dry-run]
darra-studio dataset label-auto <数据集ID> --model <模型ID或路径> [--format yolo|coco]

动作	说明
import	把数据集目录复制进项目 datasets/ 并登记（与 Studio 导入同一条实现）
list	列出当前项目已登记的数据集
info	显示数据集元数据（类别 / 划分 / 尺寸 / 标注格式）
clean	先扫问题清单再清理；问题文件移入 _quarantine_ 隔离目录，只移动不删除
label-auto	用模型批量预标注数据集图片，导出 YOLO txt 或 COCO json

选项	用于	说明
--dir <数据集目录>	import	要导入的数据集目录（必给）
--name <显示名>	import	显示名（缺省用元数据里的名字）
--model <模型ID或路径>	label-auto	自动标注用的模型（必给）
--format <yolo|coco>	label-auto	预标注导出格式（缺省 yolo）
--dry-run	clean	只出问题清单不执行清理（--dryrun 同义）

数据集 ID 在 dataset list 的输出里查。

darra-studio dataset import --dir D:\data\line-a --name 产线A
darra-studio dataset clean ds-001 --dry-run
darra-studio dataset label-auto ds-001 --model m-001 --format yolo

--json 的 data：datasets[]（list）；datasetId / displayName / alias / taskType / annotationFormat / sourcePath / datasetDir / trainCount / valCount / testCount / imageWidth / imageHeight / classes / compatibleModelIds（info）；issueCount / dryRun / movedToQuarantine / quarantineDir（clean）；total / succeeded / failed / candidates / outputDir（label-auto）。

---

train — 训练

darra-studio train start [--model <ID>] [--dataset <ID>] [--epochs <N>] [--run <运行名>] [--config <json>]
darra-studio train stop
darra-studio train status
darra-studio train history

动作	说明
start	启动训练（长任务，逐轮打 epoch / loss / mAP；Ctrl+C 取消并停止训练进程，记录收尾不留半成品）
stop	停止训练（见下方跨进程限制）
status	查看当前 / 最近一次训练状态（epoch / loss / mAP / 精确率 / 召回率）
history	查看训练历史（项目训练记录 + 运行目录实测指标）

选项	说明
--model <ID>	项目内模型 ID；缺省取训练参数的 Pretrained 权重源
--dataset <ID>	项目内数据集 ID；缺省取项目训练配置里已保存的数据集路径
--epochs <N>	训练轮数（覆盖参数集，仅本次生效）
--run <运行名>	运行目录名；缺省自动生成 <模型>-<训练ID>
--config <json>	训练参数 JSON（文件路径或内联 JSON；只覆盖给出的字段）

darra-studio train start --model m-001 --dataset ds-001 --epochs 50
darra-studio train status
darra-studio train history

跨进程限制

训练服务层没有锁文件 / PID / 状态文件等跨进程运行标记。train stop 只作用于启动训练的那个进程内的实例，停不了其它进程启动的训练——那种情况请到启动训练的进程里按 Ctrl+C。stop / status 会如实报告各运行的持久化状态。

--json 的 data：run / trainingId / model / dataset（start）；status / epochs / loss / map / primaryMetricName / primaryMetricValue / weights（start 完成）；scope / isRunning / epoch / totalEpochs / loss / map / precision / recall（status，live）或 logTail（status，persisted）；count + runs[]（history）。

---

distill — 蒸馏

darra-studio distill start --teacher <ID> --student <ID> --dataset <ID> [选项]

参数	必给	说明
--teacher <ID>	是	项目内教师模型 ID
--student <ID>	是	项目内学生模型 ID
--dataset <ID>	是	项目内数据集 ID
--epochs <N>	否	训练轮数（缺省：检测 100，其余 50）
--batch-size <N>	否	批大小（缺省：OCR 8，其余 16）
--imgsz <N>	否	训练边长（缺省：教师方形输入边长，否则分类 224 / 其余 640）
--lr <X>	否	初始学习率（缺省 0.001）
--distill-weight <X>	否	蒸馏强度（缺省 0.5；分类未传时保留引擎默认 α=0.7）
--device <cpu|cuda:0>	否	训练设备（缺省：分类 cpu，其余脚本内自动探测）
--mix-ground-truth <bool>	否	分类是否混真值（缺省 true）

引擎路由与产品蒸馏服务同口径：

任务	引擎
classification	软标签（ClassificationLogitsDistiller）
detection	特征对齐（DetectionFeatureDistiller）
ocr / ocr-text-detection	Paddle（PaddleOcrDistiller）
分割 / 姿态 / 旋转框 / 实例分割	不支持命令行蒸馏，请用 Studio 蒸馏页伪标签方式

教师与学生必须为未加密 .pt（OCR 系为 Paddle 模型），品类一致且与数据集品类一致。加密模型仅可用于推理，不能蒸馏。产物登记进项目模型库，失败如实报原因不留半成品。

darra-studio distill start --teacher t-001 --student s-001 --dataset ds-001 --epochs 80

--json 的 data：engine / teacher / student / dataset / taskType / epochs / workRoot（启动）；newModelId / artifactPath（完成）。

---

eval — 评估

darra-studio eval run --model <ID> [--dataset <ID>] [--run <运行名>]
darra-studio eval report [--run <运行名>] [--format json|markdown]

动作	说明
run	按模型任务品类跑评估，指标打进结果 data，报告落盘到运行目录 evaluation/
report	读回已落盘的评估结果，按 --format 导出报告

选项	说明
--model <ID>	项目内模型 ID（run 必给）
--dataset <ID>	项目内数据集 ID；缺省用项目里的第一个数据集（data 里如实写明用了哪个）
--run <运行名>	训练运行名，报告落在 outputs/training/<运行名>/evaluation/；缺省取该模型最近一次训练运行
--format json|markdown	report 的导出格式（缺省 json）

评估按任务品类分派：detection 按输出形状探测走 YOLO / DETR，classification 走 Top-1，segmentation / pose / obb / ocr 各走对应评估器。评估目前只支持 ONNX 模型（OCR 系支持 Paddle 模型目录），其它格式如实拒绝；无评估器的任务品类如实拒绝，不伪造指标。

darra-studio eval run --model m-001 --dataset ds-001
darra-studio eval report --format markdown

--json 的 data：model / dataset / taskType / run / reportJsonPath / reportMarkdownPath（run）；taskType / imageCount / skippedMissingLabelCount 与按任务的指标（top1 / top5，或 map50 / map50_95 / precision / recall，或 meanIou / meanOks）；reportPath（report）。

---

infer — 推理

darra-studio infer <模型> --image <图片>
darra-studio infer <模型> --batch <图片目录> [--out <结果json>] [--threshold <置信度>]

参数 / 选项	说明
<模型>	模型 ID（在当前项目模型里查 Onnx / Pt / Darmodel 权重）或权重文件路径
--image <图片>	单图推理（与 --batch 二选一）
--batch <目录>	批量推理该目录下的全部图片（与 --image 二选一）
--out <结果json>	结果写入 JSON 文件（批量逐张汇总 / 单图单条）
--threshold <置信度>	置信度阈值 0-1（不给或 0 = 用模型声明值 / 引擎默认值）

按模型 ID 查模型需要先解析到项目；权重文件路径可直接用。批量推理是长任务：逐张出进度，Ctrl+C 取消并干净退出。GPU 不可用时降级 CPU 推理并如实提示。

darra-studio infer m-001 --image D:\photos\a.jpg
darra-studio infer D:\weights\best.onnx --batch D:\photos\batch --out D:\photos\batch\result.json --threshold 0.4

--json 的 data：单图 model / modelId / image / success / provider / fallbackOccurred / detections / classifications；批量 batchDir / poolUsed / results[] / summary；写了 --out 时另有 outFile。

---

publish — 发布

darra-studio publish [--dir <导出目录>] [--dry-run]

发布 = 校验 → 本地组装 → GitLab 建项目 → 推送（含 LFS） → 打 tag → 建 release。目标是 Darra Forge（git.darra.xyz）。

选项	必给	说明
--dir <导出目录>	否	要发布的导出目录（缺省 <项目>/exports）
--dry-run	否	试运行：只扫描 + 校验 + 打印将发内容，不真发
--name <发布名>	否	GitLab 项目名（缺省当前项目名）
--version <版本>	否	版本号，即 tag 名（缺省 1.0.0）
--license <许可证key>	是	仓库许可证文本（如 MIT / Apache-2.0 / 商业授权）
--visibility <可见性>	否	public / internal / private（缺省 public）

发布门

真发只需 GitLab 登录态（CLI auth login 或 GITLAB_PAT）。--license 选仓库许可证文本，必须显式选择，不默认替用户定。模型信息公开范围按最小披露（只公开安全基础标识）。

darra-studio publish --license MIT --version 1.2.0 --dry-run
darra-studio publish --license MIT --version 1.2.0

--json 的 data：exportDir / dryRun / projectName / version / visibility / candidates（计划）；url / versionTag / projectId（发布成功）。

---

auth — 登录态

darra-studio auth status
darra-studio auth login [--token <令牌>]

与 Darra AI Studio 客户端共用同一登录态文件。

动作	说明
status	查看当前登录态（显示名 / 账号 / 过期时间，不打印令牌），恒退出 0
login	已登录直接成功；未登录弹出登录窗口。--token 写入既有登录态

未登录时 auth login 会弹出登录窗口。--token 只写入既有登录态，写不进去请改用 auth login。

darra-studio auth status
darra-studio auth login

--json 的 data：loggedIn / displayName / accountId / tokenExpiresAtUtc。

---

env — 环境就绪检查

darra-studio env

转调 darra-env-setup --check（查找顺序：与 darra-studio 同目录 → PATH）。退出码与子进程一致。找不到 darra-env-setup 时退出码 1，需先安装 Darra 环境组件。不带动作参数，也不安装环境。

darra-studio env

--json 时 data 另有 envCheck（子进程 stdout 原文）。装环境仍只走 darra-env-setup --silent --required，详见环境准备。

---

JSON 输出格式

加 --json 时，stdout 只输出一份结果信封（UTF-8，缩进，中文不转义，字段名 camelCase）：

{
  "command": "infer",
  "ok": true,
  "exitCode": 0,
  "message": "推理完成",
  "messages": ["…明细行…"],
  "data": {
    "modelId": "m-001",
    "image": "D:\\photos\\a.jpg",
    "success": true,
    "provider": "onnx-cuda",
    "problems": [],
    "phases": [
      { "command": "infer", "message": "推理完成", "ok": true, "exitCode": 0 }
    ]
  }
}

字段	说明
command	短命令名（help / version / 命令组名，如 infer / project）
ok	各阶段 ok 汇总。失败为 false
exitCode	各阶段退出码取最差（见下节）
message	收尾结论句
messages	明细行；失败项带 ! 前缀
data	结果载荷（各命令的键见上文）；固定含 problems[] 与 phases[]

• 进度不进信封：进度行在 --json 下走 stderr，stdout 保持一份 JSON，管道给 ConvertFrom-Json / jq 一次成功。
• data.problems[] 非空即失败，ok 会翻假。
• 多阶段运行也只有一个信封，阶段按执行顺序排在 data.phases[]。

--quiet 时 stdout 只打退出码数字，失败原因仍写 stderr。

---

退出码语义

码	含义
0	成功 / 就绪 / 校验通过
1	失败 / 未就绪 / 校验不通过 / 业务异常 / 被 Ctrl+C 取消
2	参数错：缺必给参数、未知命令组或动作、参数不合法

• 调用方只依赖 0 与非 0 时：0 = 好，1 = 业务失败，2 = 用法错。
• 业务细分信息不进退出码，进信封 message 与 data。
• 未捕获异常兜底 1；命令没走完就退出按 1 收口（fail-closed，不给假绿）。
• auth status 恒退出 0（只报告登录态）。
• env 的退出码与 darra-env-setup --check 一致。

darra-studio infer m-001 --image a.jpg --json --quiet
if ($LASTEXITCODE -ne 0) { Write-Error "infer failed: $LASTEXITCODE" }

---

架构说明（统一 dispatcher）

darra-studio 是薄壳：只做参数解析 + 调用既有服务 + 渲染输出，不在命令行里写第二套推理 / 训练 / 转换 / 加密 / 验签逻辑。

darra-studio.exe
  │
  ├─ 统一 dispatcher（Program）
  │     全局开关（--json / --quiet / --project / --help / --version）
  │     → 命令组路由（project / model / dataset / train / distill / eval / infer / publish / auth / env）
  │     → 一次结果信封 Flush → 退出码
  │
  ├─ CliArguments      词法解析（位置参数 + 选项 + 布尔开关）
  ├─ CliOutput         文本 / JSON / 静默三种输出契约的唯一出口
  │
  └─ Darra.AI.Studio 服务层（与 Studio 客户端同一份）
        AiToolExecutor / DistillationDispatcher / EvalDispatcher
        TrainingRunner / InferenceService / PublishService / ProjectManager …

要点：

1. 一条路由：所有命令组都经 Program 的统一分发进 Commands/*.cs，输出收口只有 CliOutput.Flush 一次，不会出现「文本有、JSON 没有」的半成品。
2. 编排归 dispatcher：蒸馏走 DistillationDispatcher、评估走 EvalDispatcher，与 GUI 同一条链路；CLI 只做参数校验与输出契约，门与缺省口径不在命令行分叉。
3. 契约同源：CliOutput / 退出码与 darra-env-setup 同一套，三个命令行工具（darra-studio / darra-sdk / darra-env-setup）输出结构一致。
4. 取消不留半成品：长任务（训练 / 批量推理 / 蒸馏）观察 Ctrl+C，取消路径清理进程与临时产物。

---

常见用例

建项目 → 导入 → 训练 → 评估 → 推理 → 发布

# 0) 环境就绪
darra-studio env

# 1) 建项目
darra-studio project new --name demo --dir D:\work
cd D:\work\demo

# 2) 导入数据集与模型
darra-studio dataset import --dir D:\data\line-a --name 产线A
darra-studio model import --file D:\weights\yolov8n.pt --name 基线检测

# 3) 训练（用 list 输出里的 ID 替换下面的 ds-001 / m-001）
darra-studio dataset list
darra-studio model list
darra-studio train start --model m-001 --dataset ds-001 --epochs 50
darra-studio train status

# 4) 评估
darra-studio eval run --model m-001 --dataset ds-001
darra-studio eval report --format markdown

# 5) 推理验证
darra-studio infer m-001 --image D:\photos\a.jpg

# 6) 导出并商用加密出包（需已登录 + 商用授权）
darra-studio model export --model m-001 --to onnx
darra-studio model encrypt --model m-001 --password -

# 7) 发布到模型库（需 GitLab 登录）
darra-studio publish --license MIT --version 1.0.0 --dry-run
darra-studio publish --license MIT --version 1.0.0

脚本集成：只看退出码与信封

darra-studio train start --model m-001 --dataset ds-001 --json
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

# 只判成败
darra-studio infer m-001 --batch D:\photos --quiet
if ($LASTEXITCODE -ne 0) { Write-Error "batch infer failed" }

自动标注 → 二次训练

# 用已有模型批量预标注，再拿标注结果训练
darra-studio dataset label-auto ds-001 --model m-001 --format yolo
darra-studio train start --model m-002 --dataset ds-001

相关页面

• 下载 — 三个命令行工具的交付入口
• 环境准备 — darra-env-setup 与 Provider
• 训练 / 评估 / 发布 — Studio 界面侧的同一链路
• 蒸馏 — 命令行不支持的任务品类在蒸馏页做