aidrama-cli 1.0.1 → 1.0.2

package/aidrama.js

@@ -161,35 +161,161 @@ function parseArgs(argv) {
   return { positionals, flags };
 }
 
-const USAGE = `aidrama —— AI 短剧 Agent 流程命令行（飞书登录鉴权，尽量通用）
+const PKG_VERSION = '1.0.2';
 
-用法: aidrama [--base-url URL] [--json] <分组> <命令> [参数...]
+// 全局选项 / 环境变量 / 退出码（帮助文本与 JSON 规格共用）
+const GLOBALS = [
+  ['--base-url <url>', '后端基地址；默认 http://localhost:38000（或环境变量 AI_DRAMA_BASE_URL）'],
+  ['--json', '以紧凑 JSON 输出结果，便于程序/agent 解析'],
+  ['--help', '查看帮助；附在命令后看该命令详情，加 --json 输出机器可读规格'],
+];
+const ENVS = [
+  ['AI_DRAMA_BASE_URL', '后端基地址（优先级低于 --base-url）'],
+  ['AI_DRAMA_TOKEN', '鉴权 token（优先级高于配置文件；适合 CI/agent 无交互鉴权）'],
+  ['AI_DRAMA_CLI_CONFIG', '配置文件路径，默认 ~/.ai-drama-cli.json（登录后 token 存于此）'],
+];
+const EXIT_CODES = '0=成功  1=运行错误(网络/HTTP/参数/未登录)  2=未知命令';
 
-鉴权:
-  auth methods                                查询后端启用的登录方式
-  auth login -u <user> -p <pass>              用户名/密码登录（兼容）
-  auth feishu [--code C --state S | --redirect-url URL]   飞书登录
-  auth me                                     当前用户(含 roles/permissions)
-  auth logout                                 清除本地 token
-配置:
-  config show
-  config set-base-url <url>
-项目/渠道/内容:
-  projects list | projects create <name>
-  providers list [--capability text|image|video]
-  content get <pid> | content set <pid> [--text T | --file F] [--content-type novel]
-Agent 步骤(--wait 触发后轮询到完成):
-  elements run <pid> [--provider-id N] [--wait] | elements list <pid>
-  images run <pid> [--element-id N] [--state-id N] [--provider-id N] [--wait]
-  episodes run <pid> [--provider-id N] [--wait] | episodes list <pid>
-  storyboards run <pid> [--episode-id N] [--provider-id N] [--wait] | storyboards list <pid> [--episode-id N]
-  videos run <pid> --storyboard-ids A B C --provider-id N [--gen-mode multi_ref] [--resolution R] [--wait] | videos list <pid>
-  videos raw --prompt "..." [--provider-id N] [--duration 5] [--aspect-ratio 9:16] [--resolution 720p] [--ref-images URL...] [--ref-videos URL...] [--ref-audios URL...] [--gen-mode multi_ref] [--idempotency-key K] [--wait] [--out FILE]   直连视频渠道(默认 seedance 2.0)生视频, 支持多模态参考(图/视频/音频); --out 自动等待并把成片下载到本地
-会话:
-  session status <sid> | session wait <sid> [--interval 3]
-通用透传:
-  api <GET|POST|PUT|DELETE> <path> [--data JSON] [--query k=v ...]
-`;
+// 命令规格：单一数据源，既渲染人读帮助也输出 JSON 规格。
+// 字段: d=简介, u=用法, opts=[[标志,说明]], ret=返回说明, ex=[示例], auth=是否需登录
+const SPEC = {
+  'auth methods': { d: '查询后端启用的登录方式', u: 'auth methods', auth: false,
+    ret: '{ password: bool, feishu: bool }', ex: ['aidrama auth methods'] },
+  'auth login': { d: '用户名/密码登录（兼容），成功后保存 token', u: 'auth login -u <user> -p <pass>', auth: false,
+    opts: [['-u, --username <user>', '用户名'], ['-p, --password <pass>', '密码']],
+    ret: '{ ok: true, token_prefix }；token 写入配置文件', ex: ['aidrama auth login -u admin -p ******'] },
+  'auth feishu': { d: '飞书登录(OAuth)：无 code 打印授权链接；有 code 换取并保存 token', u: 'auth feishu [--code <c> --state <s> | --redirect-url <url>]', auth: false,
+    opts: [['--code <c>', '飞书回调返回的授权 code'], ['--state <s>', '授权时的 state'], ['--redirect-url <url>', '直接粘贴整个回调 URL，自动解析 code/state']],
+    ret: '无 code: { authorize_url, state }；有 code: { ok, token_prefix }',
+    ex: ['aidrama auth feishu', "aidrama auth feishu --redirect-url 'http://host/cb?code=XXX&state=YYY'"] },
+  'auth me': { d: '查看当前登录用户', u: 'auth me', auth: true, ret: '{ id, username, roles, permissions }' },
+  'auth logout': { d: '清除本地保存的 token', u: 'auth logout', auth: false },
+  'config show': { d: '查看当前配置(路径/base_url/token 前缀)', u: 'config show', auth: false },
+  'config set-base-url': { d: '把默认后端地址写入配置文件', u: 'config set-base-url <url>', auth: false,
+    ex: ['aidrama config set-base-url http://10.0.0.5:38000'] },
+  'projects list': { d: '列出项目', u: 'projects list', auth: true, ret: '项目数组' },
+  'projects create': { d: '创建项目', u: 'projects create <name>', auth: true, ex: ['aidrama projects create 测试项目'] },
+  'providers list': { d: '列出可用 AI 渠道', u: 'providers list [--capability <text|image|video>]', auth: true,
+    opts: [['--capability <c>', '按能力筛选：text/image/video']],
+    ret: '渠道数组 { id, display_name, provider_type, capability }', ex: ['aidrama providers list --capability video'] },
+  'content get': { d: '获取项目原文/内容', u: 'content get <project_id>', auth: true },
+  'content set': { d: '设置项目原文(文本或文件)', u: 'content set <project_id> [--text <t> | --file <path>] [--content-type <type>]', auth: true,
+    opts: [['--text <t>', '直接给原文文本'], ['--file <path>', '从本地文件读取原文'], ['--content-type <type>', '内容类型，默认 novel']],
+    ex: ['aidrama content set 2 --file ./novel.txt'] },
+  'elements run': { d: '元素推理(角色/场景/道具)', u: 'elements run <project_id> [--provider-id N] [--wait]', auth: true,
+    opts: [['--provider-id N', '文本渠道 id(默认后端选)'], ['--wait', '轮询到完成再返回']],
+    ret: '{ session_id, status }；--wait 返回完成的会话' },
+  'elements list': { d: '列出已推理的元素', u: 'elements list <project_id>', auth: true },
+  'images run': { d: '生成元素图片', u: 'images run <project_id> [--element-id N] [--state-id N] [--provider-id N] [--wait]', auth: true,
+    opts: [['--element-id N', '仅生成指定元素'], ['--state-id N', '指定状态'], ['--provider-id N', '图片渠道 id'], ['--wait', '轮询到完成']] },
+  'episodes run': { d: '剧集拆解', u: 'episodes run <project_id> [--provider-id N] [--wait]', auth: true,
+    opts: [['--provider-id N', '文本渠道 id'], ['--wait', '轮询到完成']] },
+  'episodes list': { d: '列出剧集', u: 'episodes list <project_id>', auth: true },
+  'storyboards run': { d: '分镜策划', u: 'storyboards run <project_id> [--episode-id N] [--provider-id N] [--wait]', auth: true,
+    opts: [['--episode-id N', '指定剧集'], ['--provider-id N', '文本渠道 id'], ['--wait', '轮询到完成']] },
+  'storyboards list': { d: '列出分镜', u: 'storyboards list <project_id> [--episode-id N]', auth: true,
+    opts: [['--episode-id N', '按剧集筛选']] },
+  'videos run': { d: '按分镜生成视频', u: 'videos run <project_id> --storyboard-ids <A B C> --provider-id N [--gen-mode <m>] [--resolution R] [--wait]', auth: true,
+    opts: [['--storyboard-ids <A B C>', '分镜 id 列表(空格分隔)'], ['--provider-id N', '视频渠道 id'], ['--gen-mode <m>', 'multi_ref(默认)/first_last_frame'], ['--resolution R', '分辨率'], ['--wait', '轮询到完成']] },
+  'videos list': { d: '列出已生成视频', u: 'videos list <project_id>', auth: true },
+  'videos raw': { d: '直连视频渠道(默认 seedance 2.0)生视频：纯提示词→视频，不依赖分镜，支持多模态参考', u: 'videos raw --prompt <text> [options]', auth: true,
+    opts: [
+      ['--prompt <text>', '【必填】文本提示词'],
+      ['--provider-id N', '视频渠道 id；默认首个启用的视频渠道(如 seedance 2.0)'],
+      ['--duration N', '时长(秒)，默认 5'],
+      ['--aspect-ratio R', '画幅：9:16 / 16:9 / 1:1 / 4:3（建议显式传，否则可能跟随参考图自适应）'],
+      ['--resolution R', '分辨率档：480p / 720p / 1080p'],
+      ['--gen-mode M', 'multi_ref(默认) 或 first_last_frame(首张=首帧、末张=尾帧)'],
+      ['--ref-images URL...', '参考图，可多张(空格分隔)'],
+      ['--ref-videos URL...', '参考视频，可多个'],
+      ['--ref-audios URL...', '参考音色，可多个；须与图/视频同传，不能单独'],
+      ['--negative-prompt <t>', '负面约束(并入提示词文本)'],
+      ['--idempotency-key K', '幂等键→渠道头 Idempotency-Key；同 key 不重复生成'],
+      ['--wait', '轮询到完成再返回'],
+      ['--out FILE', '隐含 --wait，完成后把成片下载到本地文件'],
+    ],
+    ret: '触发: { session_id, status }；--wait: 完成会话(validation_report.video_url 即视频地址)；--out: 另附 saved_to(本地路径)',
+    ex: [
+      'aidrama videos raw --prompt "夜雨霓虹的赛博街道" --aspect-ratio 16:9 --wait',
+      'aidrama videos raw --prompt "她转身微笑" --ref-images https://x/a.png https://x/b.png --out ./out.mp4',
+      'aidrama videos raw --prompt "镜头推进" --ref-videos https://x/ref.mp4 --idempotency-key job-001 --wait',
+    ] },
+  'session status': { d: '查询会话状态(一次)', u: 'session status <session_id>', auth: true,
+    ret: '{ session_id, status, validation_report, items }' },
+  'session wait': { d: '轮询会话直到完成/失败', u: 'session wait <session_id> [--interval 3]', auth: true,
+    opts: [['--interval N', '轮询间隔秒，默认 3']] },
+  'api': { d: '通用透传：直接调用任意后端接口', u: 'api <GET|POST|PUT|DELETE> <path> [--data <json>] [--query k=v ...]', auth: true,
+    opts: [['--data <json>', '请求体 JSON 字符串'], ['--query k=v', '查询参数，可多个']],
+    ret: '后端原始响应',
+    ex: ['aidrama api GET /api/providers --query capability=video', 'aidrama api POST /api/projects --data \'{"name":"x"}\''] },
+};
+
+function pad(s, n) { return s + ' '.repeat(Math.max(1, n - s.length)); }
+
+// 总览帮助（人读）
+function overview() {
+  const L = [];
+  L.push(`aidrama v${PKG_VERSION} —— AI 短剧 Agent 流程命令行（零依赖, 飞书/密码登录, 适合脚本与 agent 调用）`);
+  L.push('');
+  L.push('用法: aidrama [全局选项] <分组> <命令> [参数...]');
+  L.push('命令详情: aidrama <分组> <命令> --help      机器可读规格: aidrama --help --json');
+  L.push('');
+  L.push('全局选项:');
+  for (const [f, d] of GLOBALS) L.push('  ' + pad(f, 16) + d);
+  L.push('');
+  L.push('环境变量:');
+  for (const [f, d] of ENVS) L.push('  ' + pad(f, 22) + d);
+  L.push('');
+  L.push('命令（用 <命令> --help 看详情）:');
+  let grp = '';
+  for (const id of Object.keys(SPEC)) {
+    const g = id.split(' ')[0];
+    if (g !== grp) { grp = g; L.push('  ' + g + ':'); }
+    L.push('    ' + pad(id, 22) + SPEC[id].d);
+  }
+  L.push('');
+  L.push('退出码: ' + EXIT_CODES);
+  return L.join('\n');
+}
+
+// 单命令详情（人读）
+function cmdHelp(id) {
+  const s = SPEC[id];
+  const L = [`aidrama ${id} —— ${s.d}`, '', '用法:', '  aidrama ' + s.u];
+  if (s.opts && s.opts.length) { L.push('', '选项:'); for (const [f, d] of s.opts) L.push('  ' + pad(f, 26) + d); }
+  if (s.auth) L.push('', '需登录（先 auth login / auth feishu，或设环境变量 AI_DRAMA_TOKEN）');
+  if (s.ret) L.push('', '返回: ' + s.ret);
+  if (s.ex && s.ex.length) { L.push('', '示例:'); for (const e of s.ex) L.push('  ' + e); }
+  return L.join('\n');
+}
+
+// 帮助分发：支持总览 / 分组 / 单命令；--json 输出机器可读规格
+function showHelp(positionals, flags) {
+  const g = positionals[0], c = positionals[1];
+  const exact = (g && c && SPEC[`${g} ${c}`]) ? `${g} ${c}` : (g && SPEC[g] ? g : null);
+  if (flags.json) {
+    let payload;
+    if (exact) payload = { command: exact, ...SPEC[exact] };
+    else {
+      const sub = g ? Object.keys(SPEC).filter((k) => k === g || k.startsWith(g + ' ')) : null;
+      if (sub && sub.length) payload = { group: g, commands: Object.fromEntries(sub.map((k) => [k, SPEC[k]])) };
+      else payload = { name: 'aidrama', version: PKG_VERSION, globals: GLOBALS, env: ENVS, exit_codes: EXIT_CODES, commands: SPEC };
+    }
+    console.log(JSON.stringify(payload, null, 0));
+    return;
+  }
+  if (exact) { console.log(cmdHelp(exact)); return; }
+  if (g) {
+    const sub = Object.keys(SPEC).filter((k) => k === g || k.startsWith(g + ' '));
+    if (sub.length) {
+      const L = [`aidrama ${g} —— 命令（用 <命令> --help 看详情）:`, ''];
+      for (const k of sub) L.push('  ' + pad(k, 22) + SPEC[k].d);
+      console.log(L.join('\n'));
+      return;
+    }
+  }
+  console.log(overview());
+}
 
 // ---------------- 命令实现 ----------------
 async function dispatch({ positionals, flags }) {
@@ -351,7 +477,7 @@ async function dispatch({ positionals, flags }) {
   }
   // 未匹配
   eprint(`未知命令: ${group || ''} ${cmd || ''}`.trim());
-  eprint('\n' + USAGE);
+  eprint('\n' + overview());
   process.exit(2);
 }
 
@@ -361,7 +487,7 @@ function reqStr(v) { if (v === undefined) fail('缺少 session_id 参数'); retu
 async function main() {
   const argv = process.argv.slice(2);
   const { positionals, flags } = parseArgs(argv);
-  if (flags.help || positionals.length === 0) { console.log(USAGE); return 0; }
+  if (flags.help || positionals.length === 0) { showHelp(positionals, flags); return 0; }
   await dispatch({ positionals, flags });
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aidrama-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "AI 短剧 Agent 流程命令行（飞书登录鉴权，零三方依赖，Node>=18）",
   "bin": {
     "aidrama": "aidrama.js",