drama CLI

Drama Studio 官方命令行工具：登录、文生图/参考图生图、Seedance 全能参考生视频，以及剧本/小说内容评估。

独立于主项目的小包（非 pnpm workspace），依赖单独安装，对主项目零侵入。

安装与构建

cd cli
pnpm install
pnpm build          # 产出 dist/index.js（可执行）
pnpm link --global  # 可选：全局注册 `drama` 命令

开发期直接跑源码：pnpm dev -- <command>（等价于 tsx src/index.ts <command>）。

快速开始

# 1. 登录（Device Flow：自动打开浏览器，在已登录的页面里点 Approve）
drama login                                    # 默认连线上 https://www.kvread.com
drama login --base_url http://localhost:3000   # 本地联调

# 2. 文生图 / 参考图生图（提交后打印 task_id 即退出）
drama generate_image --prompt "a cat portrait" --ratio 1:1
drama generate_image --prompt "same cat, cyberpunk style" --ref ./cat.png

# 3. Seedance 全能参考生视频（文生视频 / 图片视频音频参考）
drama generate_video --prompt "the cat walks in the rain" --duration 8
drama generate_video --prompt "animate this" --ref ./cat.png --ref ./bgm.mp3 --ratio 9:16

# 4. 查询结果 / 下载产物（唯一取结果入口）
drama query_result --task_id <id>
drama query_result --task_id <id> --wait --download_path ./out

# 5. 退出登录
drama logout

命令

| 命令 | 说明 | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | login [--base_url <url>] [--headless] | OAuth Device Flow 登录 | | logout | 清除本地登录态 | | generate_image | 提交后打印 task_id 即退出；--prompt（必填）--ref <file_or_url...> --model（默认 seedream-5-lite）--ratio --resolution | | generate_video | 提交后打印 task_id 即退出；--prompt（必填）--ref <file_or_url...> --model seedance\|seedance-fast --ratio --resolution --duration 4\|8\|12（强制生成音频） | | query_result | 查结果的唯一入口；--task_id <id>（必填）--wait 轮询到终态 --download_path <dir> 完成时下载产物到该目录 | | evaluation_skills | 查询剧本或小说评估 Skill；--type novel\|script（必填）--keyword --page_size --json | | evaluate | 创建剧本或小说评估；--type、--file <path...>、--skill（必填），可选 --model、--wait、--interval、--timeout、--report_path、--json | | evaluation_result | 查询或等待评估结果；--evaluation_id（必填），可选 --wait、--report_path、--include_history、--json | | evaluation_list | 分页查询评估历史；--type（必填），可选关键词、评级、结论、时间范围和 --json |

服务地址优先级：--base_url > 环境变量 DRAMA_BASE_URL > 登录时保存的地址 > 线上 https://www.kvread.com。

内容评估快速开始

以下以小说评估为例：

# 1. 查询小说评估 Skill，记下需要使用的 skill UUID
drama evaluation_skills --type novel

# 2. 一条命令提交小说、等待评估完成，并把报告下载到 ./reports
drama evaluate --type novel --file "./book.docx" --skill <skill-uuid> --wait --report_path ./reports

# 也可以一次提交多个文件，等待全部任务结束后下载成功任务的报告
drama evaluate --type novel --file "./book.docx" "./book-2.txt" --skill <skill-uuid> --wait --report_path ./reports

# 也可指定评估模型；省略 --model 时由服务端使用默认模型
drama evaluate --type novel --file "./book.docx" --skill <skill-uuid> --model <modelId>

# 3. 如果不想持续等待，可先提交任务，成功后会输出 evaluation_id
drama evaluate --type novel --file "./book.docx" --skill <skill-uuid>

# 稍后使用 evaluation_id 继续等待并下载报告
drama evaluation_result --evaluation_id <evaluation-id> --wait --report_path ./reports

# 4. 查看当前账号的小说评估记录
drama evaluation_list --type novel

文件路径含空格或括号时必须使用引号包裹。支持 .docx、.pdf、.txt、.md 和 .markdown，单文件最大 10 MiB，单次最多 20 个文件。报告使用 <title>-评估报告.md 命名；目标目录存在同名文件时自动追加 (1)、 (2)，不覆盖原文件。等待超时不会取消服务端任务，可再次执行 evaluation_result 续查。退出码 0 表示成功，1 表示参数、网络或鉴权错误，2 表示评估失败，3 表示本地等待超时。

剧本评估使用 --type script：将上述 evaluation_skills、evaluate 和 evaluation_list 命令中的 --type novel 替换为 --type script 即可。

登录原理

1. CLI 调 POST /api/cli/device-code 拿 device_code / user_code，打印并自动打开 verification_uri。
2. 用户在已登录的浏览器打开 /cli-auth?user_code=... 页面点击 Approve，服务端把该用户 token 绑定到设备码（不依赖 Java 后端可达）。
3. CLI 轮询 POST /api/cli/token 兑换 token，落盘本地后所有请求带 Authorization 头。

生成链路

与 web 生成页完全同一条链路，任务会进入 /generate 的统一图片/视频结果流：

1. 参考素材（本地文件或 URL）经 Java GET /server/oss/getSignatureByUser 签名后 PostObject 直传用户 OSS 空间，content 里传 ossPath 对象键。
2. POST /server/ai-gen/submit 提交任务（taskType 1=视频 2=图片），拿 taskId。
3. POST /server/ai-gen/status 轮询到终态（1=pending 2=running 3=completed 4=failed 5=timeout），从 result.imageList / result.videoList 取产物 URL 下载。