@remixmate/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,10 +1,12 @@
 # @remixmate/cli
 
-> 原名 `ab-skill-cli`（bin `ab-skill`），现已更名为 **`@remixmate/cli`**（bin **`remixmate`**）。旧包已在 npm 标记弃用，请迁移到新包。
+English | [简体中文](./README.zh-CN.md)
+
+> Formerly `ab-skill-cli` (bin `ab-skill`), now renamed to **`@remixmate/cli`** (bin **`remixmate`**). The old package is deprecated on npm — please migrate to the new one.
 
 AI media generation skills for Claude Code / Codex.
 
-9 skills covering the full short-video production pipeline: image / video / voice / digital-human asset generation, script planning, template binding, Remotion rendering, and Jianying (CapCut) draft export.
+11 skills covering the full short-video production pipeline: image / video / voice / digital-human asset generation, web page capture, script planning, template binding, Remotion rendering, Jianying (CapCut) draft export, and video deconstruction.
 
 ## Install
 
@@ -46,121 +48,136 @@ cp .env.example .env
 source .env
 ```
 
-Python skills (6 of 9) require `python3 >= 3.10`. `video-parser` additionally requires `ffmpeg`.
-
----
+Python skills (6 of 11) require `python3 >= 3.10`. `web-capture` requires Playwright (auto-installs chromium on first run). `ffmpeg` is only needed for `video-parser`'s optional local tool (`deconstruct_video.py`); the default `video-parser` entry runs server-side via ab-render and needs no local ffmpeg.
 
-## AI 媒体生成 Agent Skills（中文）
+## Skills
 
-本项目包含 9 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
+This project contains 11 AI media generation skills covering the full pipeline from asset generation, script orchestration, template binding, and video rendering to Jianying export.
 
-### 技能分层
+### Skill layers
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ 编排层 Skills                                                │
-│  gen-script           主题 → Video DSL（脚本生成）           │
-│  template-bind        DSL → TemplateBinding（模板列表）      │
-│  prepare-video-assets DSL + Binding → 素材补齐（Phase 1）    │
-│  render-video         RenderPlan → Remotion 渲染（Phase 3）  │
-│  export-jianying      素材 → 剪映草稿 ZIP                    │
+│ Orchestration Skills                                         │
+│  gen-script           Topic → Video DSL (script generation) │
+│  template-registry        DSL → TemplateBinding (template list) │
+│  prepare-video-assets DSL + Binding → asset resolve (Phase1)│
+│  render-video         RenderPlan → Remotion render (Phase 3)│
+│  export-jianying      Assets → Jianying draft ZIP           │
 ├─────────────────────────────────────────────────────────────┤
-│ 原子层 Skills                                                │
-│  gen-image         文生图 / 图生图（Seedream / Gemini）      │
-│  gen-video         文生视频（Seedance / Veo）                │
-│  gen-voice         语音合成（Minimax TTS）                   │
-│  gen-digital-human 数字人口播（即梦 / 飞影）                 │
+│ Atomic Skills                                                │
+│  gen-image         Text/Image-to-image (Seedream / Gemini)  │
+│  gen-video         Text-to-video (Seedance / Veo)           │
+│  gen-voice         Text-to-speech (Minimax TTS)             │
+│  gen-digital-human Talking-head (Jimeng / Feiying)          │
 ├─────────────────────────────────────────────────────────────┤
-│ 工具层 Skills                                                │
-│  video-parser      视频解构（音频提取 / ASR / 关键帧）       │
+│ Tool Skills                                                  │
+│  video-parser      Video deconstruction (audio / ASR / kf)  │
+│  web-capture       Web page screenshot / scroll-record      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### 目录结构
+### Directory structure
 
 ```
 ├── docs/
-│   └── video-production-architecture.md   # 架构文档
+│   └── video-production-architecture.md   # architecture docs
+├── src/                        # TypeScript CLI + http/builtin handlers
 ├── skills/
-│   ├── gen-image/              # 原子: AI 生图
-│   ├── gen-video/              # 原子: AI 生视频
-│   ├── gen-voice/              # 原子: 语音合成
-│   ├── gen-digital-human/      # 原子: 数字人口播
-│   ├── gen-script/             # 编排: 主题 → Video DSL
-│   ├── template-bind/          # 编排: 模板列表（含模板注册表 + DSL Schema）
-│   ├── prepare-video-assets/   # 编排: Phase 1 素材准备（thin wrapper）
-│   ├── render-video/           # 编排: Phase 3 Remotion 渲染（含 render_video.py 实现）
-│   ├── export-jianying/        # 编排: 导出剪映草稿 ZIP
-│   └── video-parser/           # 工具: 视频解构与分析
+│   ├── gen-image/              # atomic: AI image generation (http handler)
+│   ├── gen-video/              # atomic: AI video generation (http handler)
+│   ├── gen-voice/              # atomic: text-to-speech (http handler)
+│   ├── gen-digital-human/      # atomic: talking-head video (http handler)
+│   ├── gen-script/             # orchestration: Topic → Video DSL
+│   ├── template-registry/          # orchestration: template list (python list_templates.py)
+│   ├── prepare-video-assets/   # orchestration: Phase 1 asset prep (thin wrapper)
+│   ├── render-video/           # orchestration: Phase 3 Remotion render (canonical render_video.py)
+│   ├── export-jianying/        # orchestration: export Jianying draft ZIP
+│   ├── video-parser/           # tool: video deconstruction & analysis
+│   └── web-capture/            # tool: headless-browser screenshot / recording
 └── README.md
 ```
 
-### 技能说明
+### Skill reference
 
-| 技能 | 类型 | 说明 | 核心脚本 |
-|------|------|------|----------|
-| gen-image | 原子 | 文生图 / 图生图（Seedream、Gemini） | `gen_image.py` |
-| gen-video | 原子 | 文生视频（Seedance、Veo） | `gen_video.py` |
-| gen-voice | 原子 | 语音合成（Minimax TTS） | `gen_voice.py` |
-| gen-digital-human | 原子 | 数字人口播（即梦 / 飞影） | `gen_digital_human_video.py` |
-| gen-script | 编排 | 主题 → Video DSL JSON | `gen_script.py` |
-| template-bind | 编排 | 模板列表（绑定逻辑内嵌于 prepare-video-assets） | `match_template.py` |
-| prepare-video-assets | 编排 | DSL + Binding → 素材补齐 → 落库 RenderPlan | `render_video.py --resolve-only`（wrapper） |
-| render-video | 编排 | job_id → Remotion 渲染 → 上传 | `render_video.py` |
-| export-jianying | 编排 | 素材 URL → 剪映草稿 ZIP（支持从 RenderPlan 自动转换） | `gen_jianying_draft.py` |
-| video-parser | 工具 | 视频 → 音频 + ASR + 关键帧 + 场景分段 | `deconstruct_video.py` |
+| Skill | Type | Description | Runtime / entry |
+|-------|------|-------------|-----------------|
+| gen-image | atomic | Text/Image-to-image (Seedream, Gemini) | http handler |
+| gen-video | atomic | Text-to-video (Seedance, Veo) | http handler |
+| gen-voice | atomic | Text-to-speech (Minimax TTS) | http handler |
+| gen-digital-human | atomic | Talking-head (Jimeng / Feiying) | http handler |
+| gen-script | orchestration | Topic → Video DSL JSON | python `scripts/gen_script.py` |
+| template-registry | orchestration | Template list (binding logic embedded in prepare-video-assets) | python `scripts/list_templates.py` |
+| prepare-video-assets | orchestration | DSL + Binding → asset resolve → persist RenderPlan | python `scripts/prepare_video_assets.py` (wraps `render_video.py --resolve-only`) |
+| render-video | orchestration | job_id → Remotion render → upload | python `scripts/render_video.py` |
+| export-jianying | orchestration | Asset URLs → Jianying draft ZIP (auto-converts from RenderPlan) | python `scripts/gen_jianying_draft.py` |
+| video-parser | tool | Video → audio + ASR + keyframes + scene segmentation | python `scripts/parse_via_render.py` |
+| web-capture | tool | Web page screenshot / scroll-record / storyboard video | python `scripts/screenshot.py`, `scripts/record.py` |
 
-### 核心链路
+### Core workflows
 
-详见 [视频内容生产架构文档](docs/video-production-architecture.md) 和 [编排流程指南](docs/orchestration-guide.md)。
+See the [video production architecture doc](docs/video-production-architecture.md) and the [orchestration guide](docs/orchestration-guide.md).
 
-**链路 A：主题 → Remotion 视频**
+**Workflow A: Topic → Remotion video**
 ```
-gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
-→ ✅用户确认素材 → render-video(--job-id) → MP4
+gen-script → ✅ user confirms script → prepare-video-assets(--template-id)
+→ ✅ user confirms assets → render-video(--job-id) → MP4
 ```
 
-**链路 B：主题 → 剪映草稿**
+**Workflow B: Topic → Jianying draft**
 ```
-gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
-→ ✅用户确认素材 → export-jianying(--from-job-id) → 剪映 ZIP
+gen-script → ✅ user confirms script → prepare-video-assets(--template-id)
+→ ✅ user confirms assets → export-jianying(--from-job-id) → Jianying ZIP
 ```
 
-### 测试
+### Testing
 
 ```bash
-# 各脚本 --help 可正常运行
-python3 skills/gen-image/scripts/gen_image.py --help
-python3 skills/gen-video/scripts/gen_video.py --help
-python3 skills/gen-voice/scripts/gen_voice.py --help
-python3 skills/gen-digital-human/scripts/gen_digital_human_video.py --help
-python3 skills/gen-script/scripts/gen_script.py --help
-python3 skills/template-bind/scripts/match_template.py --help
-python3 skills/render-video/scripts/render_video.py --help
-python3 skills/prepare-video-assets/scripts/prepare_video_assets.py --help
-python3 skills/export-jianying/scripts/gen_jianying_draft.py --help
-python3 skills/video-parser/scripts/deconstruct_video.py --help
-
-# 查看可用音色
-python3 skills/gen-voice/scripts/gen_voice.py --list-voices
-
-# 查看可用模板
-python3 skills/template-bind/scripts/match_template.py --list-templates
+# List all skills (name, tool, entry type)
+remixmate --list
+
+# Offline registry smoke + spec guards
+npm run smoke
+
+# CLI unit tests (argv parser + skill schema)
+npm run test:cli
+
+# Python skills forward --help to the underlying script:
+remixmate gen-script --help
+remixmate prepare-video-assets --help
+remixmate render-video --help
+remixmate export-jianying --help
+remixmate video-parser --help
+remixmate web-capture --help
+remixmate template-registry --help
+
+# http skills (gen-image, gen-video, gen-voice, gen-digital-human) take no
+# python --help; their flags live in each SKILL.md / skill.json.
+
+# List available voices
+remixmate gen-voice --list-voices
+
+# List available templates
+remixmate template-registry --list-templates
 ```
 
-### 开发流程
+### Development
 
-- 克隆此项目到本地
-- 在 skills 目录下各技能文件夹中开发
-- 每个技能包含 `SKILL.md`（技能说明）、`version.json`（元数据）和 `scripts/`（脚本）
+- Clone this project locally
+- Develop inside each skill folder under `skills/`
+- Each skill contains `SKILL.md` (skill docs), `version.json` (metadata), and `scripts/` (scripts)
 
-### 快速体验
+### Quick start
 
 ```
-@skills/gen-image/SKILL.md 生成一张熊猫的图片，9:16，调用gemini 3.1，国画风 + 严格按该文档执行
-@skills/gen-video/SKILL.md 生成一段熊猫在竹林奔跑的视频，9:16，长度6秒，调用veo + 严格按该文档执行
-@skills/gen-voice/SKILL.md 生成一段语音，介绍熊猫的习性，大概100字左右 + 严格按该文档执行
-@skills/gen-digital-human/SKILL.md 获取数字人列表 + 严格按该文档执行
-@skills/template-bind/SKILL.md 获取模版列表 + 严格按该文档执行
-@skills/gen-script/SKILL.md 基于模版 image-slide，创作一个关于AI学习方法的视频 + 严格按该文档执行
+@skills/gen-image/SKILL.md Generate an image of a panda, 9:16, using gemini 3.1, Chinese-painting style + follow this doc strictly
+@skills/gen-video/SKILL.md Generate a video of a panda running in a bamboo forest, 9:16, 6 seconds, using veo + follow this doc strictly
+@skills/gen-voice/SKILL.md Generate a voiceover introducing panda habits, around 100 words + follow this doc strictly
+@skills/gen-digital-human/SKILL.md Get the digital human list + follow this doc strictly
+@skills/template-registry/SKILL.md Get the template list + follow this doc strictly
+@skills/gen-script/SKILL.md Based on the image-slide template, create a video about AI learning methods + follow this doc strictly
 ```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,183 @@
+# @remixmate/cli
+
+[English](./README.md) | 简体中文
+
+> 原名 `ab-skill-cli`（bin `ab-skill`），现已更名为 **`@remixmate/cli`**（bin **`remixmate`**）。旧包已在 npm 标记弃用，请迁移到新包。
+
+面向 Claude Code / Codex 的 AI 媒体生成技能集。
+
+包含 11 个技能，覆盖完整的短视频生产链路：图片 / 视频 / 语音 / 数字人素材生成、网页捕获、脚本编排、模板绑定、Remotion 渲染、剪映（CapCut）草稿导出，以及视频解构。
+
+## 安装
+
+```bash
+npm install -g @remixmate/cli
+remixmate --help
+remixmate --list
+```
+
+## 在 Claude Code 中使用
+
+把内置的 `skills/` 拷贝到项目级或全局的 `.claude/skills/` 目录，Claude Code 会自动识别：
+
+```bash
+# 项目级
+mkdir -p .claude/skills
+cp -R "$(npm root -g)/@remixmate/cli/skills/." .claude/skills/
+
+# 或全局
+mkdir -p ~/.claude/skills
+cp -R "$(npm root -g)/@remixmate/cli/skills/." ~/.claude/skills/
+```
+
+## 在 Codex 中使用
+
+Codex 不会原生加载 `SKILL.md`。在系统提示里告诉 Codex 这个 CLI，让它在需要媒体生成时调用 `remixmate <skill> ...`：
+
+> 当你需要 AI 媒体生成（图片 / 视频 / 语音 / 数字人 / 剪映导出）时，先运行 `remixmate <skill-id> --help` 查看参数，再用 `remixmate <skill-id> --json-output ...` 执行。可用技能：`remixmate --list`。
+
+完整介绍页（Claude Code / Codex 配置、环境变量、端到端工作流示例）见项目主页。
+
+## 环境
+
+多数技能通过 `PRIV_TOKEN` 向 ab-api 鉴权。没有有效 token（以及访问 ab-api 的网络）时，模板 / 媒体生成类技能不可用——代码是开源的，但生成能力托管在 ab-api 服务上。运行前把 `.env.example` 拷为 `.env` 并 source：
+
+```bash
+cp .env.example .env
+# 修改其中的值
+source .env
+```
+
+Python 技能（11 个中的 6 个）需要 `python3 >= 3.10`。`web-capture` 需要 Playwright（首次运行自动安装 chromium）。`ffmpeg` 仅 `video-parser` 的可选本地工具（`deconstruct_video.py`）需要；`video-parser` 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。
+
+## 技能
+
+本项目包含 11 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
+
+### 技能分层
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 编排层 Skills                                                │
+│  gen-script           主题 → Video DSL（脚本生成）           │
+│  template-registry        DSL → TemplateBinding（模板列表）      │
+│  prepare-video-assets DSL + Binding → 素材补齐（Phase 1）    │
+│  render-video         RenderPlan → Remotion 渲染（Phase 3）  │
+│  export-jianying      素材 → 剪映草稿 ZIP                    │
+├─────────────────────────────────────────────────────────────┤
+│ 原子层 Skills                                                │
+│  gen-image         文生图 / 图生图（Seedream / Gemini）      │
+│  gen-video         文生视频（Seedance / Veo）                │
+│  gen-voice         语音合成（Minimax TTS）                   │
+│  gen-digital-human 数字人口播（即梦 / 飞影）                 │
+├─────────────────────────────────────────────────────────────┤
+│ 工具层 Skills                                                │
+│  video-parser      视频解构（音频提取 / ASR / 关键帧）       │
+│  web-capture       网页截图 / 滚动录屏 / 分镜视频            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 目录结构
+
+```
+├── docs/
+│   └── video-production-architecture.md   # 架构文档
+├── src/                        # TypeScript CLI + http/builtin handlers
+├── skills/
+│   ├── gen-image/              # 原子: AI 生图（http handler）
+│   ├── gen-video/              # 原子: AI 生视频（http handler）
+│   ├── gen-voice/              # 原子: 语音合成（http handler）
+│   ├── gen-digital-human/      # 原子: 数字人口播（http handler）
+│   ├── gen-script/             # 编排: 主题 → Video DSL
+│   ├── template-registry/          # 编排: 模板列表（python list_templates.py）
+│   ├── prepare-video-assets/   # 编排: Phase 1 素材准备（thin wrapper）
+│   ├── render-video/           # 编排: Phase 3 Remotion 渲染（含 render_video.py 实现）
+│   ├── export-jianying/        # 编排: 导出剪映草稿 ZIP
+│   ├── video-parser/           # 工具: 视频解构与分析
+│   └── web-capture/            # 工具: 无头浏览器截图 / 录屏
+└── README.md
+```
+
+### 技能说明
+
+| 技能 | 类型 | 说明 | 运行方式 / entry |
+|------|------|------|------------------|
+| gen-image | 原子 | 文生图 / 图生图（Seedream、Gemini） | http handler |
+| gen-video | 原子 | 文生视频（Seedance、Veo） | http handler |
+| gen-voice | 原子 | 语音合成（Minimax TTS） | http handler |
+| gen-digital-human | 原子 | 数字人口播（即梦 / 飞影） | http handler |
+| gen-script | 编排 | 主题 → Video DSL JSON | python `scripts/gen_script.py` |
+| template-registry | 编排 | 模板列表（绑定逻辑内嵌于 prepare-video-assets） | python `scripts/list_templates.py` |
+| prepare-video-assets | 编排 | DSL + Binding → 素材补齐 → 落库 RenderPlan | python `scripts/prepare_video_assets.py`（包装 `render_video.py --resolve-only`） |
+| render-video | 编排 | job_id → Remotion 渲染 → 上传 | python `scripts/render_video.py` |
+| export-jianying | 编排 | 素材 URL → 剪映草稿 ZIP（支持从 RenderPlan 自动转换） | python `scripts/gen_jianying_draft.py` |
+| video-parser | 工具 | 视频 → 音频 + ASR + 关键帧 + 场景分段 | python `scripts/parse_via_render.py` |
+| web-capture | 工具 | 网页截图 / 滚动录屏 / 分镜视频 | python `scripts/screenshot.py`、`scripts/record.py` |
+
+### 核心链路
+
+详见 [视频内容生产架构文档](docs/video-production-architecture.md) 和 [编排流程指南](docs/orchestration-guide.md)。
+
+**链路 A：主题 → Remotion 视频**
+```
+gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
+→ ✅用户确认素材 → render-video(--job-id) → MP4
+```
+
+**链路 B：主题 → 剪映草稿**
+```
+gen-script → ✅用户确认脚本 → prepare-video-assets(--template-id)
+→ ✅用户确认素材 → export-jianying(--from-job-id) → 剪映 ZIP
+```
+
+### 测试
+
+```bash
+# 列出所有技能（名称、tool、entry 类型）
+remixmate --list
+
+# 离线注册表 smoke + 规范守卫
+npm run smoke
+
+# CLI 单元测试（argv 解析器 + skill schema）
+npm run test:cli
+
+# Python 技能会把 --help 透传给底层脚本：
+remixmate gen-script --help
+remixmate prepare-video-assets --help
+remixmate render-video --help
+remixmate export-jianying --help
+remixmate video-parser --help
+remixmate web-capture --help
+remixmate template-registry --help
+
+# http 技能（gen-image、gen-video、gen-voice、gen-digital-human）没有
+# python --help；参数见各自的 SKILL.md / skill.json。
+
+# 查看可用音色
+remixmate gen-voice --list-voices
+
+# 查看可用模板
+remixmate template-registry --list-templates
+```
+
+### 开发流程
+
+- 克隆此项目到本地
+- 在 skills 目录下各技能文件夹中开发
+- 每个技能包含 `SKILL.md`（技能说明）、`version.json`（元数据）和 `scripts/`（脚本）
+
+### 快速体验
+
+```
+@skills/gen-image/SKILL.md 生成一张熊猫的图片，9:16，调用gemini 3.1，国画风 + 严格按该文档执行
+@skills/gen-video/SKILL.md 生成一段熊猫在竹林奔跑的视频，9:16，长度6秒，调用veo + 严格按该文档执行
+@skills/gen-voice/SKILL.md 生成一段语音，介绍熊猫的习性，大概100字左右 + 严格按该文档执行
+@skills/gen-digital-human/SKILL.md 获取数字人列表 + 严格按该文档执行
+@skills/template-registry/SKILL.md 获取模版列表 + 严格按该文档执行
+@skills/gen-script/SKILL.md 基于模版 image-slide，创作一个关于AI学习方法的视频 + 严格按该文档执行
+```
+
+## 许可证
+
+MIT

package/dist/handlers/gen-digital-human.d.ts

@@ -0,0 +1,12 @@
+/**
+ * gen-digital-human handler — talking-head video, three modes:
+ *   --list-avatars true                  → POST /digital-human/avatar/page (list)
+ *   --check-status --generation-id <id>  → POST /digital-human/video/status (one-shot)
+ *   default (--avatar-id <id> ...)       → generate: resolve avatar → submit → poll
+ *
+ * Ported from `scripts/gen_digital_human_video.py` (python → http) so it shares
+ * auth / base-URL / business-code handling with the other generators via
+ * http.ts. Endpoints and payloads match the backend DigitalHumanVideoGenerateDTO.
+ */
+import type { HandlerContext, HandlerInput } from './index.js';
+export declare function genDigitalHuman(input: HandlerInput, ctxIn: HandlerContext): Promise<void>;

package/dist/handlers/gen-digital-human.js

@@ -0,0 +1,157 @@
+/**
+ * gen-digital-human handler — talking-head video, three modes:
+ *   --list-avatars true                  → POST /digital-human/avatar/page (list)
+ *   --check-status --generation-id <id>  → POST /digital-human/video/status (one-shot)
+ *   default (--avatar-id <id> ...)       → generate: resolve avatar → submit → poll
+ *
+ * Ported from `scripts/gen_digital_human_video.py` (python → http) so it shares
+ * auth / base-URL / business-code handling with the other generators via
+ * http.ts. Endpoints and payloads match the backend DigitalHumanVideoGenerateDTO.
+ */
+import { mmPost, pollUntil, resolveHttpContext, SkillError } from '../http.js';
+import { emitProgress } from '../progress.js';
+import { isTrue, toNumber } from './shared.js';
+const VALID_SOURCES = new Set(['jimeng', 'hifly']);
+const DEFAULT_VOICE_ID = 'male-qn-qingse';
+async function listAvatars(ctx, input) {
+    const payload = { current: 1, pageSize: 100 };
+    if (input.source)
+        payload.source = String(input.source);
+    if (input.gender)
+        payload.gender = String(input.gender);
+    if (isTrue(input.mine))
+        payload.mine = true;
+    if (input.name)
+        payload.name = String(input.name);
+    const data = await mmPost(ctx, '/digital-human/avatar/page', payload, { timeoutMs: 30_000 });
+    const avatars = data.list ?? [];
+    if (isTrue(input.json_output)) {
+        process.stdout.write(JSON.stringify({ avatars }) + '\n');
+        return;
+    }
+    if (avatars.length === 0) {
+        process.stdout.write('⚠️  No avatars available\n');
+        return;
+    }
+    process.stdout.write(`\n${'ID'.padEnd(8)} ${'Name'.padEnd(16)} ${'Source'.padEnd(10)} ${'Gender'.padEnd(8)} Ratio\n`);
+    process.stdout.write(`${'-'.repeat(8)} ${'-'.repeat(16)} ${'-'.repeat(10)} ${'-'.repeat(8)} ${'-'.repeat(10)}\n`);
+    for (const a of avatars) {
+        process.stdout.write(`${String(a.id ?? '').padEnd(8)} ${String(a.name ?? '').padEnd(16)} ${String(a.source ?? '').padEnd(10)} ${String(a.gender ?? '').padEnd(8)} ${a.aspectRatio ?? ''}\n`);
+    }
+    process.stdout.write(`\n${avatars.length} avatar(s) available\n`);
+    process.stdout.write('💡 Use --avatar-id <ID> to pick an avatar for generation\n');
+}
+/** Look up one avatar's metadata; checks the normal page then `mine: true`. */
+async function fetchAvatarInfo(ctx, avatarId) {
+    for (const extra of [{}, { mine: true }]) {
+        const data = await mmPost(ctx, '/digital-human/avatar/page', { current: 1, pageSize: 100, ...extra }, { timeoutMs: 30_000 });
+        const found = (data.list ?? []).find((a) => String(a.id) === String(avatarId));
+        if (found)
+            return found;
+    }
+    throw new SkillError(`❌ avatar_id=${avatarId} not found; use --list-avatars [--mine] to see what is available`);
+}
+function resolveSource(explicit, avatar) {
+    const src = (explicit ?? '').trim() || (avatar.source ?? '').trim();
+    if (!VALID_SOURCES.has(src)) {
+        throw new SkillError('❌ Could not determine a valid source (jimeng/hifly). Pass --source, or confirm the avatar carries a source field.');
+    }
+    return src;
+}
+async function checkStatus(ctx, generationId, json) {
+    const data = await mmPost(ctx, '/digital-human/video/status', { generationId }, { timeoutMs: 30_000 });
+    const status = data.status ?? 'unknown';
+    if (json) {
+        process.stdout.write(JSON.stringify({ status, url: data.videoUrl ?? null, generationId }) + '\n');
+        return;
+    }
+    process.stdout.write(`\ntask status: ${status}\n`);
+    if (data.videoUrl)
+        process.stdout.write(`   video URL: ${data.videoUrl}\n`);
+    if (status === 'failed') {
+        const err = data.errorMessage ?? data.error ?? data.message ?? 'unknown error';
+        process.stdout.write(`   failure reason: ${err}\n`);
+    }
+}
+async function pollVideoStatus(ctx, generationId) {
+    const url = await pollUntil(async () => {
+        const data = await mmPost(ctx, '/digital-human/video/status', { generationId }, { timeoutMs: 30_000 });
+        const status = data.status ?? 'unknown';
+        emitProgress({ phase: 'gen-digital-human:poll', generationId, status });
+        if (status === 'completed')
+            return data.videoUrl ?? '';
+        if (status === 'failed') {
+            const err = data.errorMessage ?? data.error ?? data.message ?? 'unknown error';
+            throw new SkillError(`❌ video generation failed: ${err}`);
+        }
+        return null;
+    }, { intervalMs: 5_000, timeoutMs: 600_000 });
+    return url;
+}
+export async function genDigitalHuman(input, ctxIn) {
+    const ctx = resolveHttpContext(ctxIn.skillName, {
+        apiBaseUrl: input.api_base_url,
+        privateToken: input.priv_token,
+    });
+    // ── Mode 1: list avatars ────────────────────────────────────────────────
+    if (isTrue(input.list_avatars)) {
+        return listAvatars(ctx, input);
+    }
+    // ── Mode 3: check status ────────────────────────────────────────────────
+    if (isTrue(input.check_status)) {
+        const generationId = toNumber(input.generation_id, 'generation_id');
+        if (generationId === undefined) {
+            throw new SkillError('❌ check-status mode requires --generation-id');
+        }
+        return checkStatus(ctx, generationId, isTrue(input.json_output));
+    }
+    // ── Mode 2: generate (default) ──────────────────────────────────────────
+    const avatarId = toNumber(input.avatar_id, 'avatar_id');
+    if (avatarId === undefined) {
+        throw new SkillError('❌ provide --avatar-id to pick the avatar (use --list-avatars to see available avatars)');
+    }
+    const audioUrl = (input.audio_url ?? '').trim();
+    const text = input.text ?? '';
+    if (!audioUrl) {
+        if (!text.trim()) {
+            throw new SkillError('❌ in TTS mode provide --text, or use --audio-url for audio-driven mode');
+        }
+    }
+    emitProgress({ phase: 'gen-digital-human:resolve-avatar', avatarId });
+    const avatar = await fetchAvatarInfo(ctx, avatarId);
+    const source = resolveSource(input.source, avatar);
+    const payload = { avatarId, source };
+    if (audioUrl) {
+        payload.audioUrl = audioUrl;
+        if (text.trim())
+            payload.text = text.trim();
+    }
+    else {
+        payload.text = text;
+        payload.voiceId = input.voice_id ?? DEFAULT_VOICE_ID;
+        if (input.voice_name)
+            payload.voiceName = String(input.voice_name);
+    }
+    const aspectRatio = input.aspect_ratio ?? avatar.aspectRatio;
+    if (aspectRatio)
+        payload.aspectRatio = aspectRatio;
+    if (input.prompt)
+        payload.prompt = String(input.prompt);
+    emitProgress({ phase: 'gen-digital-human:request', avatarId, source, mode: audioUrl ? 'audio' : 'tts' });
+    const data = await mmPost(ctx, '/digital-human/video/generate', payload, { timeoutMs: 60_000 });
+    const generationId = data.generationId;
+    if (!generationId) {
+        throw new SkillError(`❌ could not parse generationId; API returned: ${JSON.stringify(data)}`);
+    }
+    emitProgress({ phase: 'gen-digital-human:async', generationId });
+    const videoUrl = await pollVideoStatus(ctx, generationId);
+    if (!videoUrl) {
+        throw new SkillError(`❌ video generated but no URL was returned; rerun --check-status --generation-id ${generationId} later`);
+    }
+    if (isTrue(input.json_output)) {
+        process.stdout.write(JSON.stringify({ url: videoUrl, generationId }) + '\n');
+        return;
+    }
+    process.stdout.write(`\n🔗 Video URL (renders directly, no download needed):\n${videoUrl}\n`);
+    process.stdout.write('\n🎉 Digital-human video generation done!\n');
+}