mangaforg-cli
MangaForge 的命令行客户端，按任务类型分组组织命令，面向脚本化、自动化和 Agent 场景。
安装
未安装 CLI 时，先按安装指南安装并验证：
npm install -g mangaforg-cli
mangaforg --version
概念
- 会话（session）：一次业务上下文，
session_id由调用方生成（例如一次剧本推进、一次 Agent 会话）。同一 session 下可提交多个任务，便于统一追踪。 - 任务（task）：一次具体的生成请求。提交后由后端返回
task_id，可用它查询单个任务状态。 - 模型（model）：每个任务类型下有多个可用模型，模型自带使用限制（时长,分辨率等）和入参 schema（
params字段的结构约束）。提交任务前建议先用<group> models查询目标模型的可用参数。
能力概览
任务提交 / 模型查询（按任务类型两级分组，当前均为 mock 实现，接口签名一致）：
| 任务类型 | 提交任务 | 查询模型 |
|---|---|---|
| 生图 | mangaforg image submit |
mangaforg image models |
| 生视频 | mangaforg video submit |
mangaforg video models |
所有 submit / models 子命令的参数与返回结构在各任务类型间完全一致，见下文「命令详情」小节。
任务查询（跨任务类型统一入口）：
| 命令 | 说明 |
|---|---|
mangaforg task list --sid <id> |
查询某会话下的所有任务 |
mangaforg task list --tid <id> |
查询单个任务 |
配置管理：
| 命令 | 说明 |
|---|---|
mangaforg config show |
查看当前生效的配置 |
mangaforg config set-key <apiKey> |
设置 API Key |
mangaforg config set-url <baseUrl> |
设置后端服务地址 |
认证与配置
CLI 不接受在命令行显式传入 API Key 或后端地址，统一从本地配置读取。
配置文件位置：~/.mangaforg/config.json
配置字段：
| 字段 | 说明 |
|---|---|
apiKey |
API Key，请求时通过 X-API-Key 头传给后端 |
baseUrl |
MangaForge 后端服务地址 |
命令详情
提交任务：image submit / video submit
两类任务的 submit 子命令签名一致，仅调用不同后端接口。
mangaforg <image|video> submit -p <JSON> [-s <SESSION_ID>]
| 参数 | 缩写 | 必填 | 说明 |
|---|---|---|---|
--params |
-p |
是 | 任务参数，必须是 JSON 对象字符串 |
--sid |
-s |
否 | 会话 ID，用于将同一会话下的任务关联；不传则该任务不归属任何会话 |
使用示例：
mangaforg image submit -p '<按目标模型的 params_schema 构造的 JSON>'
mangaforg video submit -p '<按目标模型的 params_schema 构造的 JSON>' -s <SESSION_ID>
-p 的具体字段没有固定结构，一律以目标模型的 params_schema 为准。使用前请先执行 mangaforg <group> models 查询模型清单，从中选定模型并按其 params_schema 的必填 / 可选字段构造 --params。
查询模型：image models / video models
查询某任务类型下所有可用模型，返回每个模型的使用限制与入参 schema。
mangaforg <image|video> models
无参数。返回 models 数组，每个元素包含：
| 字段 | 说明 |
|---|---|
model_id |
模型唯一标识，提交任务时通常在 params.model 中引用 |
name |
展示名 |
description |
简介 |
model_limit |
使用限制，例如 不同模型对于视频的时长的限制不同 |
params_schema |
JSON Schema 描述 submit 时 --params 的可用字段、类型、默认值和取值范围 |
推荐流程：先 <group> models 查看目标模型的 params_schema，据此构造 submit 的 --params。
task list — 查询任务
mangaforg task list -s <SESSION_ID>
mangaforg task list -t <TASK_ID>
| 参数 | 缩写 | 必填 | 说明 |
|---|---|---|---|
--sid |
-s |
二选一 | 按会话 ID 查询该会话下的所有任务 |
--tid |
-t |
二选一 | 按任务 ID 查询单个任务 |
--sid 与 --tid 必须提供其中之一。
使用场景示例
- CI/自动化脚本：按 session 提交批量任务并轮询状态
- Agent 编排：Agent 用同一
session_id提交生图 / 生视频任务，之后统一task list --sid查询整个会话的所有任务
帮助信息
mangaforg --help
mangaforg <group> --help # 如 mangaforg image --help / mangaforg task --help
mangaforg <group> <action> --help