feat: 对齐云端转换参数并改进 CLI 体验

将 cloud params 限制为 API 实际支持的字段，移除过时的 cloud-only 选项；按当前模式调整字体嵌入提示；升级 @deckops/sdk 并增强 API 错误输出与 space-id 配置。

Author: zhaoxiongfei

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deckflow/deckhtml",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Convert HTML to PPTX, PDF, or PNG presentations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,7 +40,7 @@
   "homepage": "https://github.com/deckflow/deckhtml#readme",
   "license": "MIT",
   "dependencies": {
-    "@deckops/sdk": "^0.7.0",
+    "@deckops/sdk": "^0.7.2",
     "commander": "^11.1.0",
     "jszip": "^3.10.1",
     "mathml2omml": "^0.5.0",

pnpm-lock.yaml

@@ -62,7 +62,9 @@ async function main(): Promise<void> {
     }
     outputError(
       error instanceof Error ? error : new Error(String(error)),
-      ctx.jsonOutput
+      ctx.jsonOutput,
+      'ERROR',
+      { apiBase: ctx.config.apiBase }
     );
     process.exit(ExitCode.ERROR);
   }

src/cli.ts

@@ -7,7 +7,7 @@ export function registerConfigCommands(program: Command, ctx: Context): void {
   config
     .command('set')
     .description('Set a configuration value')
-    .argument('<key>', 'api-key | webhook | retention-hours')
+    .argument('<key>', 'api-key | space-id | webhook | retention-hours')
     .argument('<value>', 'Configuration value')
     .action(async (key: string, value: string) => {
       try {
@@ -19,6 +19,14 @@ export function registerConfigCommands(program: Command, ctx: Context): void {
               () => 'API key set successfully'
             );
             break;
+          case 'space-id':
+            await ctx.config.setSpaceId(value);
+            ctx.resetDeck();
+            ctx.output(
+              { key, value, message: 'Space ID set successfully' },
+              () => `Space ID set to ${value}`
+            );
+            break;
           case 'webhook':
             await ctx.config.set('webhook', value);
             ctx.output(
@@ -40,7 +48,7 @@ export function registerConfigCommands(program: Command, ctx: Context): void {
           }
           default:
             throw new Error(
-              `Unknown config key: ${key}. Supported: api-key, webhook, retention-hours`
+              `Unknown config key: ${key}. Supported: api-key, space-id, webhook, retention-hours`
             );
         }
       } catch (error) {

src/cli/commands/config.ts

@@ -30,24 +30,18 @@ import {
 import { resolveMode, validateCloudOnlyFlags } from '../utils/mode';
 import { resolveViewport } from '../utils/size';
 
-const DEFAULT_RENDER_WAIT = 3;
 const DEFAULT_TIMEOUT = 600;
 
 const VALID_PLATFORMS = ['win', 'mac', 'ios', 'android', 'linux'] as const;
+type CloudPlatform = 'mac' | 'win';
 
 export interface ConvertOptions {
   output?: string;
   mode: string;
   format: string;
   width?: string;
   platform?: string;
-  renderWait: string;
-  rebuildSvg?: boolean;
-  rebuildChart?: boolean;
   embedFonts?: boolean;
-  mapMotion?: boolean;
-  webhook?: string;
-  retentionHours?: string;
   report?: boolean;
 }
 
@@ -63,45 +57,25 @@ function resolvePlatformOption(platform?: string): PlatformTarget {
   return platform as PlatformTarget;
 }
 
-function parsePositiveInt(value: string, flag: string): number {
-  const n = parseInt(value, 10);
-  if (!Number.isFinite(n) || n < 0) {
-    throw new Error(`Invalid ${flag}: ${value}`);
-  }
-  return n;
+function toCloudPlatform(platform: PlatformTarget): CloudPlatform {
+  return platform === 'mac' || platform === 'ios' ? 'mac' : 'win';
 }
 
 function buildCloudParams(
-  ctx: Context,
   options: ConvertOptions,
-  platform: PlatformTarget,
+  platform: CloudPlatform,
   viewport?: { width: number; height: number }
 ): Record<string, unknown> {
-  const retentionHours = options.retentionHours
-    ? parsePositiveInt(options.retentionHours, '--retention-hours')
-    : ctx.config.retentionHours;
-
-  if (retentionHours < 0 || retentionHours > 99) {
-    throw new Error('--retention-hours must be between 0 and 99');
-  }
-
   const params: Record<string, unknown> = {
     needEmbedFonts: Boolean(options.embedFonts),
-    renderWait: parsePositiveInt(options.renderWait, '--render-wait'),
-    rebuildSvg: Boolean(options.rebuildSvg),
-    rebuildChart: Boolean(options.rebuildChart),
-    mapMotion: Boolean(options.mapMotion),
-    webhook: options.webhook ?? ctx.config.get('webhook'),
-    retentionHours,
+    platform,
   };
 
   if (viewport) {
     params.width = viewport.width;
     params.height = viewport.height;
   }
 
-  params.platform = platform;
-
   return params;
 }
 
@@ -177,41 +151,33 @@ async function runCloudConvert(
 
   const deck = await ctx.getDeck();
   const spaceId = ctx.config.get('spaceId');
-  if (!spaceId) {
-    throw new Error(
-      'Space ID is missing. Run `deckhtml auth login` first or ensure your API key includes workspace context.'
-    );
-  }
 
-  const params = buildCloudParams(ctx, options, platform, viewport);
+  const params = buildCloudParams(options, toCloudPlatform(platform), viewport);
   const taskName = path.basename(inputPaths[0]!, path.extname(inputPaths[0]!));
 
+  logVerbose(ctx.verbose, ctx.quiet, `API base: ${ctx.config.apiBase}`);
+  logVerbose(
+    ctx.verbose,
+    ctx.quiet,
+    spaceId ? `Space ID: ${spaceId}` : 'Space ID: auto (GET /user/self)'
+  );
   logProgress(ctx.quiet, `Uploading ${inputPaths.length} file(s)...`);
 
-  let task;
-  if (format === 'png') {
-    task = await deck.convertHtmlToPng({
-      spaceId,
-      files: inputPaths,
-      name: taskName,
-      params: params as never,
-      upload: {
-        onProgress: (p: number) =>
-          logProgress(ctx.quiet, `Uploading: ${(p * 100).toFixed(1)}%`),
-      },
-    });
-  } else {
-    task = await deck.convertHtmlToPptx({
-      spaceId,
-      files: inputPaths,
-      name: taskName,
-      params: params as never,
-      upload: {
-        onProgress: (p: number) =>
-          logProgress(ctx.quiet, `Uploading: ${(p * 100).toFixed(1)}%`),
-      },
-    });
-  }
+  const taskInput = {
+    ...(spaceId ? { spaceId } : {}),
+    files: inputPaths,
+    name: taskName,
+    params: params as never,
+    upload: {
+      onProgress: (p: number) =>
+        logProgress(ctx.quiet, `Uploading: ${(p * 100).toFixed(1)}%`),
+    },
+  };
+
+  const task =
+    format === 'png'
+      ? await deck.convertHtmlToPng(taskInput)
+      : await deck.convertHtmlToPptx(taskInput);
 
   logProgress(ctx.quiet, `Task created: ${task.id}`);
   logProgress(ctx.quiet, 'Converting...');
@@ -271,19 +237,9 @@ export function registerConvertCommand(program: Command, ctx: Context): void {
     )
     .option(
       '--platform <platform>',
-      'Target platform for generic font mapping: win, mac, ios, android, linux (default: current OS; script/lang auto-detected from text)'
-    )
-    .option(
-      '--render-wait <seconds>',
-      'Per-page wait before capture (cloud)',
-      String(DEFAULT_RENDER_WAIT)
+      'Target platform: local supports win, mac, ios, android, linux; cloud uses mac or win (ios→mac, others→win)'
     )
-    .option('--rebuild-svg', 'Rebuild SVG objects (cloud only)', false)
-    .option('--rebuild-chart', 'Rebuild chart objects (cloud only)', false)
     .option('--embed-fonts', 'Embed fonts (cloud only)', false)
-    .option('--map-motion', 'Map animations (cloud only)', false)
-    .option('--webhook <url>', 'Callback URL (cloud)')
-    .option('--retention-hours <n>', 'Cloud file retention hours (0-99)')
     .option('--report', 'Generate conversion report next to output', false)
     .action(async (inputs: string[], options: ConvertOptions) => {
       if (inputs.length === 0) {
@@ -321,10 +277,7 @@ export function registerConvertCommand(program: Command, ctx: Context): void {
           );
 
           validateCloudOnlyFlags(mode, {
-            rebuildSvg: options.rebuildSvg,
-            rebuildChart: options.rebuildChart,
             embedFonts: options.embedFonts,
-            mapMotion: options.mapMotion,
           });
 
           const platform = resolvePlatformOption(options.platform);

src/cli/commands/convert.ts

@@ -9,6 +9,10 @@ import {
   runLoginFlow,
   DEFAULT_PORT,
 } from './core/auth';
+import {
+  installApiErrorCapture,
+  shouldLogHttpRequests,
+} from './utils/api-error';
 import { ExitCode, outputError } from './utils/errors';
 
 export class Context {
@@ -46,6 +50,9 @@ export class Context {
     }
 
     if (!this.deck) {
+      await installApiErrorCapture({
+        logRequests: shouldLogHttpRequests(this.verbose),
+      });
       const { createDeck } = await import('@deckops/sdk');
       this.deck = createDeck({
         root: this.config.apiBase,
@@ -146,7 +153,7 @@ export class Context {
   error(input: unknown, code = 'ERROR', exitCode: number = ExitCode.ERROR): never {
     const err =
       input instanceof Error ? input : new Error(String(input ?? 'Unknown error'));
-    outputError(err, this.jsonOutput, code);
+    outputError(err, this.jsonOutput, code, { apiBase: this.config.apiBase });
     process.exit(exitCode);
   }