@xqyz/xq-cli 0.1.0

package/src/cli.mjs

@@ -0,0 +1,3349 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import http from 'http';
+import https from 'https';
+import os from 'os';
+import path from 'path';
+import readline from 'readline/promises';
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import axios from 'axios';
+import FormData from 'form-data';
+import { templateData } from './templateData.mjs';
+import { AI_PURPOSE_MAP, detectFileType } from './fileTypeConfig.mjs';
+
+const APP_DIR = path.join(os.homedir(), '.xq-opencli');
+const CONFIG_FILE = path.join(APP_DIR, 'config.json');
+const DEFAULT_PARSE_INTERVAL_MS = 10_000;
+const DEFAULT_TASK_INTERVAL_MS = 10_000;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_SOURCE_FROM = 'xique';
+const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_EXPORT_TEMPLATE_INDEX = 1;
+const DEFAULT_PAGE_SCOPE_CODE = 1;
+const DEFAULT_BASE = '0';
+const DEFAULT_THEME_STYLE = 4;
+const DEFAULT_TABLE_QUANTITY = 2;
+const DEFAULT_TABLE_COLOR = 'BLUE';
+const DEFAULT_TABLE_STYLE = 1;
+const DEFAULT_MERMAID_STYLE = 1;
+const DEFAULT_PLAN_MODE = 0;
+const DEFAULT_INFO_IMG = 0;
+const DEFAULT_SCENE_IMG = 0;
+const DEFAULT_ONLINE_IMG = 0;
+const DEFAULT_MERMAID_IMG = 0;
+const DEFAULT_KNOWLEDGE_IMG = 0;
+const DEFAULT_AUTO_NUMBER = 1;
+const DEFAULT_ADD_MARK = 0;
+const CONTENT_VIEW_STEP = 101;
+const DIRECTORY_PORTION_STATUS = {
+    OUTLINE_GENERATING: 0,
+    OUTLINE_COMPLETED: 1,
+    SEQUEL_GENERATING: 2,
+    SEQUEL_COMPLETED: 3,
+    OUTLINE_BASE_COMPLETED: 4,
+    OUTLINE_ADDITIONAL_GENERATING: 5,
+};
+const DEFAULT_RETRY_COUNT = 3;
+const DIRECTORY_SEQUEL_RETRY_INTERVAL_MS = 60_000;
+const GENERATE_UNFINISHED_RETRY_INTERVAL_MS = 60_000;
+const RETRYABLE_NETWORK_CODES = new Set(['ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'EAI_AGAIN']);
+const SOFT_CONTENT_TRIGGER_CODES = new Set([411, 429]);
+const BROWSER_LOGIN_CALLBACK_PATH = '/callback';
+const HTTP_AGENT = new http.Agent({ keepAlive: true });
+const HTTPS_AGENT = new https.Agent({ keepAlive: true });
+const AUTO_IGNORE_ISSUE_CONFIG = {
+    requirement_judgement: {
+        optionKey: 'ignoreShortRequirement',
+        hint: '--ignore-short-requirement',
+        buildPayload: uuid => ({
+            uuid,
+            requirement: '',
+            score: '',
+            type: 'requirement_short',
+        }),
+    },
+    billOfQuantities_judgement: {
+        optionKey: 'ignoreMissingBill',
+        hint: '--ignore-missing-bill',
+        buildPayload: uuid => ({
+            uuid,
+            requirement: '',
+            score: '',
+            type: 'billOfQuantities',
+        }),
+    },
+    score_judgement: {
+        optionKey: 'ignoreMissingScore',
+        hint: '--ignore-missing-score',
+        buildPayload: uuid => ({
+            uuid,
+            requirement: '',
+            score: '',
+            type: 'score',
+        }),
+    },
+    directory_judgement: {
+        optionKey: 'ignoreDirectoryBasis',
+        hint: '--ignore-directory-basis',
+        buildPayload: uuid => ({
+            uuid,
+            requirement: '',
+            score: '',
+            directory: '',
+            modify: 0,
+            type: 'directory',
+        }),
+    },
+};
+const DEFAULT_THEME_STYLE_SETTING = {
+    tableBolderColorOfSkeleton: '#1276C1',
+    imgTitleColor: '#1276C1',
+    heading4Color: '#49A3E7',
+    heading5Color: '#DFF7FF',
+    contentTitleColor: '#EEFBFF',
+    contentColor: '#FFFFFF',
+    heading4TextColor: '#000000',
+    heading5TextColor: '#000000',
+    contentTitleTextColor: '#000000',
+    imgTitleTextColor: '#FFFFFF',
+};
+const DEFAULT_PAGE_MARGIN_SETTING = {
+    topMargin: 2.54,
+    bottomMargin: 2.54,
+    leftMargin: 3.18,
+    rightMargin: 3.18,
+};
+const OUTLINE_REFERENCE_OPTIONS = [
+    {
+        value: 0,
+        label: '融合评分与格式要求响应',
+        shortLabel: '融合响应',
+        outlineKey: 'planAndRatingOutline',
+        aliases: ['0', 'merge', 'merged', 'combined', 'all'],
+        recommended: true,
+    },
+    {
+        value: 1,
+        label: '仅响应格式要求',
+        shortLabel: '格式要求',
+        outlineKey: 'planOutline',
+        aliases: ['1', 'format', 'plan'],
+        recommended: false,
+    },
+    {
+        value: 2,
+        label: '仅响应评分要求',
+        shortLabel: '评分要求',
+        outlineKey: 'ratingOutline',
+        aliases: ['2', 'score', 'rating'],
+        recommended: false,
+    },
+];
+const PAGE_SCOPE_OPTIONS = [
+    { value: -1, label: 'mini', description: '50-100 pages', aliases: ['-1', 'mini'] },
+    { value: 0, label: 'extra-short', description: '100-200 pages', aliases: ['0', 'extra-short', 'xshort'] },
+    { value: 1, label: 'short', description: '200-350 pages', aliases: ['1', 'short'] },
+    { value: 2, label: 'medium', description: '350-500 pages', aliases: ['2', 'medium'] },
+    { value: 3, label: 'medium-long', description: '500-800 pages', aliases: ['3', 'medium-long', 'mlong'] },
+    { value: 4, label: 'long', description: '800-1200 pages', aliases: ['4', 'long'] },
+    { value: 5, label: 'extra-long', description: '1200-1500 pages', aliases: ['5', 'extra-long', 'xlong'] },
+];
+const BASE_OPTIONS = [
+    { value: '0', label: 'standard', description: 'standard writing', aliases: ['0', 'standard', 'default'] },
+    { value: '1', label: 'expert', description: 'expert polish / public knowledge reference', aliases: ['1', 'expert', 'polish'] },
+];
+const THEME_STYLE_OPTIONS = [
+    { value: 1, label: 'enhanced', description: 'enhanced image-rich layout', aliases: ['1', 'enhanced'] },
+    { value: 2, label: 'table', description: 'table-first layout', aliases: ['2', 'table', 'table-first'] },
+    { value: 3, label: 'rich', description: 'rich mixed media layout', aliases: ['3', 'rich'] },
+    { value: 4, label: 'basic', description: 'basic illustrated layout', aliases: ['4', 'basic', 'base'] },
+    { value: 5, label: 'text', description: 'text only', aliases: ['5', 'text', 'text-only'] },
+];
+const TABLE_QUANTITY_OPTIONS = [
+    { value: 0, label: 'none', description: 'no tables', aliases: ['0', 'none'] },
+    { value: 1, label: 'few', description: 'about one table every 4 pages', aliases: ['1', 'few', 'light'] },
+    { value: 2, label: 'rich', description: 'about one table every 2 pages', aliases: ['2', 'rich', 'dense'] },
+];
+const TABLE_COLOR_OPTIONS = [
+    { value: 'BLACK', label: 'black', aliases: ['black'] },
+    { value: 'BLUE', label: 'blue', aliases: ['blue'] },
+    { value: 'RED', label: 'red', aliases: ['red'] },
+    { value: 'GREEN', label: 'green', aliases: ['green'] },
+    { value: 'PURPLE', label: 'purple', aliases: ['purple'] },
+    { value: 'CYAN', label: 'cyan', aliases: ['cyan'] },
+    { value: 'ORANGE', label: 'orange', aliases: ['orange'] },
+];
+const TABLE_STYLE_OPTIONS = [
+    { value: 1, label: 'plain', description: 'plain table style', aliases: ['1', 'plain', 'clean'] },
+    { value: 2, label: 'header', description: 'strong header style', aliases: ['2', 'header', 'header-strong'] },
+    { value: 3, label: 'zebra', description: 'zebra stripes', aliases: ['3', 'zebra', 'striped'] },
+    { value: 4, label: 'filled', description: 'filled cells with white borders', aliases: ['4', 'filled', 'full-fill'] },
+];
+const MERMAID_STYLE_OPTIONS = [
+    { value: 1, label: 'gray', aliases: ['1', 'gray', 'grey'] },
+    { value: 2, label: 'purple', aliases: ['2', 'purple'] },
+    { value: 3, label: 'blue', aliases: ['3', 'blue'] },
+    { value: 4, label: 'green', aliases: ['4', 'green'] },
+    { value: 5, label: 'orange', aliases: ['5', 'orange'] },
+    { value: 6, label: 'red', aliases: ['6', 'red'] },
+];
+const PLAN_MODE_OPTIONS = [
+    { value: 0, label: 'quick', description: 'quick mode', aliases: ['0', 'quick'] },
+    { value: 1, label: 'planning', description: 'planning mode', aliases: ['1', 'planning', 'plan'] },
+];
+const LAYOUT_OPTIONS = [
+    { value: 0, label: 'normal', description: 'regular layout', aliases: ['0', 'normal', 'default'] },
+    { value: 1, label: 'table', description: 'full table layout', aliases: ['1', 'table'] },
+    { value: 2, label: 'enhanced', description: 'enhanced / refined mixed layout', aliases: ['2', 'enhanced', 'refined'] },
+];
+const BINARY_OPTIONS = [
+    { value: 0, label: 'off', aliases: ['0', 'false', 'no', 'off'] },
+    { value: 1, label: 'on', aliases: ['1', 'true', 'yes', 'on'] },
+];
+const THEME_STYLE_SETTING_FIELDS = [
+    { key: 'tableBolderColorOfSkeleton', optionKeys: ['tableBolderColorOfSkeleton', 'skeletonColor'], description: 'table skeleton accent color' },
+    { key: 'imgTitleColor', optionKeys: ['imgTitleColor'], description: 'image title background color' },
+    { key: 'heading4Color', optionKeys: ['heading4Color'], description: 'heading level 4 background color' },
+    { key: 'heading5Color', optionKeys: ['heading5Color'], description: 'heading level 5 background color' },
+    { key: 'contentTitleColor', optionKeys: ['contentTitleColor'], description: 'content title background color' },
+    { key: 'contentColor', optionKeys: ['contentColor'], description: 'content background color' },
+    { key: 'heading4TextColor', optionKeys: ['heading4TextColor'], description: 'heading level 4 text color' },
+    { key: 'heading5TextColor', optionKeys: ['heading5TextColor'], description: 'heading level 5 text color' },
+    { key: 'contentTitleTextColor', optionKeys: ['contentTitleTextColor'], description: 'content title text color' },
+    { key: 'imgTitleTextColor', optionKeys: ['imgTitleTextColor'], description: 'image title text color' },
+];
+const PAGE_MARGIN_FIELDS = [
+    { key: 'topMargin', optionKeys: ['topMargin', 'marginTop'] },
+    { key: 'bottomMargin', optionKeys: ['bottomMargin', 'marginBottom'] },
+    { key: 'leftMargin', optionKeys: ['leftMargin', 'marginLeft'] },
+    { key: 'rightMargin', optionKeys: ['rightMargin', 'marginRight'] },
+];
+const EXPORT_TEMPLATE_OPTIONS = templateData.map((template, index) => ({
+    value: index + 1,
+    label: `template-${index + 1}`,
+    description: template.custom ? 'custom baseline template' : 'built-in template',
+}));
+const EPC_ENGINEER_TYPE_ALIAS_MAP = {
+    all: '\u975EEPC',
+    full: '\u975EEPC',
+    construction: '\u65BD\u5DE5',
+    build: '\u65BD\u5DE5',
+    design: '\u8BBE\u8BA1',
+    'not-epc': '\u975EEPC2',
+    'non-epc': '\u975EEPC2',
+};
+const PAGE_SCOPE_PROMPT_LABELS = {
+    [-1]: '\u6781\u77ed\u7BC7 (50-100\u9875)',
+    0: '\u8D85\u77ED\u7BC7 (100-200\u9875)',
+    1: '\u77ED\u7BC7 (200-350\u9875)',
+    2: '\u4E2D\u7BC7 (350-500\u9875)',
+    3: '\u4E2D\u957F\u7BC7 (500-800\u9875)',
+    4: '\u957F\u7BC7 (800-1200\u9875)',
+    5: '\u8D85\u957F\u7BC7 (1200-1500\u9875)',
+};
+const BASE_PROMPT_LABELS = {
+    0: '\u6807\u51C6\u5199\u4F5C',
+    1: '\u4E13\u5BB6\u667A\u7B14',
+};
+const THEME_STYLE_PROMPT_LABELS = {
+    1: '\u589E\u5F3A\u56FE\u6587',
+    2: '\u5168\u8868\u683C\u5F0F',
+    3: '\u4E30\u5BCC\u56FE\u6587',
+    4: '\u57FA\u7840\u914D\u56FE',
+    5: '\u7EAF\u6587\u5B57',
+};
+const TABLE_QUANTITY_PROMPT_LABELS = {
+    0: '\u65E0\u8868\u683C',
+    1: '\u5C11\u91CF\u8868\u683C',
+    2: '\u4E30\u5BCC\u8868\u683C',
+};
+const TABLE_COLOR_PROMPT_LABELS = {
+    BLACK: '\u9ED1\u8272',
+    BLUE: '\u84DD\u8272',
+    RED: '\u7EA2\u8272',
+    GREEN: '\u7EFF\u8272',
+    PURPLE: '\u7D2B\u8272',
+    CYAN: '\u9752\u8272',
+    ORANGE: '\u6A59\u8272',
+};
+const TABLE_STYLE_PROMPT_LABELS = {
+    1: '\u7EAF\u51C0\u7248',
+    2: '\u8868\u5934\u5F3A\u5316',
+    3: '\u6591\u9A6C\u6761\u7EB9',
+    4: '\u5168\u5E95\u8272\u767D\u6846',
+};
+const MERMAID_STYLE_PROMPT_LABELS = {
+    1: '\u7070\u8272',
+    2: '\u7D2B\u8272',
+    3: '\u84DD\u8272',
+    4: '\u7EFF\u8272',
+    5: '\u6A59\u8272',
+    6: '\u7EA2\u8272',
+};
+const PLAN_MODE_PROMPT_LABELS = {
+    0: '\u5FEB\u901F\u6A21\u5F0F',
+    1: '\u89C4\u5212\u6A21\u5F0F',
+};
+const LAYOUT_PROMPT_LABELS = {
+    0: '\u5E38\u89C4\u6392\u7248',
+    1: '\u5168\u8868\u683C\u5F0F',
+    2: '\u7CBE\u6392/\u589E\u5F3A\u56FE\u6587',
+};
+const IMAGE_TOGGLE_PROMPT_OPTIONS = [
+    { key: 'knowledgeImg', label: '\u6211\u7684\u56FE\u5E93', defaultValue: DEFAULT_KNOWLEDGE_IMG },
+    { key: 'sceneImg', label: '\u5B9E\u62CD\u98CE\u683C\u56FE', defaultValue: DEFAULT_SCENE_IMG },
+    { key: 'onlineImg', label: '\u8054\u7F51\u641C\u56FE', defaultValue: DEFAULT_ONLINE_IMG },
+    { key: 'infoImg', label: 'PPT\u5F0F\u63D2\u56FE', defaultValue: DEFAULT_INFO_IMG },
+    { key: 'mermaidImg', label: '\u6D41\u7A0B\u56FE', defaultValue: DEFAULT_MERMAID_IMG },
+];
+const EPC_ENGINEER_PROMPT_OPTIONS = [
+    { value: '', label: '\u4FDD\u6301\u5F53\u524D/\u4E0D\u8BBE\u7F6E' },
+    { value: '\u975EEPC', label: '\u5168\u90E8\u7F16\u5199' },
+    { value: '\u65BD\u5DE5', label: '\u53EA\u5199\u65BD\u5DE5' },
+    { value: '\u8BBE\u8BA1', label: '\u53EA\u5199\u8BBE\u8BA1' },
+    { value: '\u975EEPC2', label: '\u8FD9\u4E0D\u662FEPC\u9879\u76EE' },
+];
+
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    const command = parsed._[0] || 'help';
+    const state = readState();
+
+    switch (command) {
+        case 'help':
+        case '--help':
+        case '-h':
+            printHelp();
+            return;
+        case 'login':
+            await handleLogin(parsed, state);
+            return;
+        case 'init':
+            await handleInit(parsed, state);
+            return;
+        case 'parse-status':
+            await handleParseStatus(parsed, state);
+            return;
+        case 'outline':
+            await handleOutline(parsed, state);
+            return;
+        case 'write':
+            await handleWrite(parsed, state);
+            return;
+        case 'status':
+            await handleStatus(parsed, state);
+            return;
+        case 'export':
+            await handleExport(parsed, state);
+            return;
+        case 'choices':
+            handleChoices(parsed);
+            return;
+        case 'wizard':
+            await handleWizard(parsed, state);
+            return;
+        default:
+            throw new Error(`Unsupported command: ${command}. Run "xq-cli help" to see available commands.`);
+    }
+}
+
+function printHelp() {
+    console.log(`
+xq-cli: xique brand task CLI
+
+Commands
+  login         Save xique account token locally
+  init          Upload files and initialize a task
+  parse-status  Query or wait for parse completion
+  outline       Pre-set task params and trigger outline generation
+  write         Charge if needed, enter content phase, and trigger content generation
+  status        Query task status
+  choices       Print selectable outline/export config values
+  wizard        Run init -> outline -> write -> export with interactive menus
+  export        Download the generated docx
+
+Examples
+  xq-cli login --base-url http://localhost:9021/api
+  xq-cli login --base-url http://localhost:9021/api --name demo --password secret
+  xq-cli login --base-url http://localhost:9021/api --browser
+  xq-cli init --file D:\\bids\\tender.docx --wait
+  xq-cli parse-status --cid <cid> --uuid <uuid> --wait
+  xq-cli choices
+  xq-cli choices outline --json
+  xq-cli wizard
+  xq-cli wizard --file D:\\bids\\tender.docx
+  xq-cli outline --cid <cid> --wait
+  xq-cli outline --cid <cid> --interactive --wait
+  xq-cli outline --cid <cid> --uuid <uuid> --wait
+  xq-cli outline --cid <cid> --wait --ignore-short-requirement
+  xq-cli outline --cid <cid> --wait --ignore-missing-bill
+  xq-cli outline --cid <cid> --wait --reference-type 0
+  xq-cli outline --cid <cid> --page-scope 3 --base expert --theme-style 4 --table-quantity rich --plan-mode quick --wait
+  xq-cli write --cid <cid> --type 1 --wait
+  xq-cli status --cid <cid> --content
+  xq-cli export --cid <cid> --interactive --out D:\\output\\
+  xq-cli export --cid <cid> --template 2 --layout enhanced --table-color green --table-style zebra --out D:\\output\\
+  xq-cli export --cid <cid> --out D:\\output\\
+
+Common options
+  --json             Print machine-readable JSON output
+  --base-url <url>   Override the saved base URL
+  --timeout-sec <n>  Poll timeout in seconds, default 600
+  --interval-sec <n> Poll interval in seconds, default 10
+  --reference-type <0|1|2>  Outline reference choice: 0=merge, 1=format only, 2=score only
+  --browser          Force browser authorization login; browser is the default when credentials are not provided
+  --interactive      Open prompt menus for the current command
+  --ignore-short-requirement  Follow the frontend ignore/continue path for requirement_judgement=0
+  --ignore-missing-bill       Follow the frontend ignore/continue path for billOfQuantities_judgement=0
+
+Outline config
+  --page-scope <code>         Full-length preset. See "xq-cli choices outline"
+  --page-scope-code <code>    Alias of --page-scope
+  --base <0|1|standard|expert>
+  --theme-style <1|2|3|4|5|enhanced|table|rich|basic|text>
+  --table-quantity <0|1|2|none|few|rich>
+  --table-color <black|blue|red|green|purple|cyan|orange>
+  --table-style <1|2|3|4|plain|header|zebra|filled>
+  --info-img <0|1>            PPT-style infographic toggle
+  --scene-img <0|1>           real-photo style image toggle
+  --online-img <0|1>          online image search toggle
+  --mermaid-img <0|1>         flowchart toggle
+  --knowledge-img <0|1>       knowledge-base image toggle
+  --mermaid-style <1|2|3|4|5|6|gray|purple|blue|green|orange|red>
+  --plan-mode <0|1|quick|planning>
+  --multi-bid-id <id>         override the selected bid package when needed
+  --multi-bid-type <text>     persist the selected bid package type
+  --epc-engineer-type <text>  accepts raw backend value or aliases: all, construction, design, not-epc
+
+Export style
+  --template <1-${templateData.length}>       Same template order as the frontend download drawer
+  --style-json <file>         Advanced export style JSON with startIndex/directorySettings/contentSettings
+  --start-index <n>           Override the template heading numbering start index
+  --auto-number <0|1>         Toggle Word auto numbering
+  --add-mark <0|1>            Add suggest-modify marks
+  --layout <0|1|2|normal|table|enhanced>
+  --top-margin <cm>           Page top margin
+  --bottom-margin <cm>        Page bottom margin
+  --left-margin <cm>          Page left margin
+  --right-margin <cm>         Page right margin
+  --skeleton-color <hex>      Alias of --table-bolder-color-of-skeleton
+  --img-title-color <hex>
+  --heading4-color <hex>
+  --heading5-color <hex>
+  --content-title-color <hex>
+  --content-color <hex>
+  --heading4-text-color <hex>
+  --heading5-text-color <hex>
+  --content-title-text-color <hex>
+  --img-title-text-color <hex>
+  note: write follows the frontend content flow: order/charge -> c/viewStep(101) -> task/autoGenerateContent
+`.trim());
+}
+
+async function handleLogin(args, state) {
+    const baseUrl = normalizeBaseUrl(stringOption(args, 'baseUrl', state.baseUrl));
+    if (!baseUrl) {
+        throw new Error('Missing base URL. Pass --base-url <url>.');
+    }
+    const sourceFrom = stringOption(args, 'sourceFrom', DEFAULT_SOURCE_FROM);
+    const loginMode = resolveLoginMode(args);
+    const result = loginMode === 'browser'
+        ? await loginWithBrowser(baseUrl, sourceFrom, args)
+        : await loginWithPassword(baseUrl, sourceFrom, args);
+
+    saveLoginState(state, {
+        baseUrl,
+        name: stringOption(args, 'name', result.data?.user?.username || ''),
+        sourceFrom,
+        result,
+    });
+
+    outputResult(args, {
+        command: 'login',
+        mode: loginMode,
+        baseUrl,
+        username: state.user.username,
+        tokenSaved: true,
+    }, [
+        `login success: ${state.user.username}`,
+        `mode: ${loginMode}`,
+        `baseUrl: ${baseUrl}`,
+        `config: ${CONFIG_FILE}`,
+    ]);
+}
+
+function resolveLoginMode(args) {
+    if (booleanOption(args, 'browser')) {
+        return 'browser';
+    }
+    const hasName = stringOption(args, 'name');
+    const hasPassword = stringOption(args, 'password');
+    return hasName || hasPassword ? 'password' : 'browser';
+}
+
+async function loginWithPassword(baseUrl, sourceFrom, args) {
+    const name = requiredOption(args, 'name');
+    const password = requiredOption(args, 'password');
+    const client = createClient(baseUrl);
+    return postJson(client, '/user/login', {
+        name,
+        password,
+        sourceFrom,
+    });
+}
+
+async function loginWithBrowser(baseUrl, sourceFrom, args) {
+    const client = createClient(baseUrl);
+    const loginState = randomUUID();
+    const timeoutMs = secondsToMs(numberOption(args, 'timeoutSec', DEFAULT_LOGIN_TIMEOUT_MS / 1000));
+    const callbackServer = await startBrowserLoginServer();
+    const authorizeUrl = buildBrowserAuthorizeUrl(baseUrl, callbackServer.redirectUri, loginState, sourceFrom);
+
+    writeNotice(args, `browser login url: ${authorizeUrl}`);
+    if (openBrowser(authorizeUrl)) {
+        writeNotice(args, 'browser login: waiting for authorization callback');
+    } else {
+        writeNotice(args, 'browser login: automatic open failed, paste the URL above into a browser on this machine');
+    }
+
+    try {
+        const callback = await withTimeout(
+            callbackServer.result,
+            timeoutMs,
+            `Browser login timed out after ${Math.round(timeoutMs / 1000)} seconds.`,
+        );
+        if (callback.state !== loginState) {
+            throw new Error('Browser login state validation failed.');
+        }
+        return await postJson(client, '/user/cli/token', {
+            code: callback.code,
+            state: callback.state,
+        });
+    } finally {
+        await callbackServer.close();
+    }
+}
+
+function writeNotice(args, message) {
+    if (booleanOption(args, 'json')) {
+        console.error(message);
+        return;
+    }
+    console.log(message);
+}
+
+async function handleInit(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const files = resolveFileArgs(args);
+    if (files.length === 0) {
+        throw new Error('At least one file is required. Use --file <path>.');
+    }
+
+    const fileMeta = buildFileMetadata(files, args);
+    const annexIds = splitCsvOption(args.annexIds);
+    const knowledgeProductIds = splitCsvOption(args.knowledgeProductIds);
+    const formData = new FormData();
+
+    for (const filePath of files) {
+        ensureFileExists(filePath);
+        formData.append('files', fs.createReadStream(filePath), path.basename(filePath));
+    }
+    formData.append('sourceFrom', stringOption(args, 'sourceFrom', DEFAULT_SOURCE_FROM));
+    formData.append('types', fileMeta.types.join(','));
+    formData.append('purposes', fileMeta.purposesPayload);
+    appendOptionalField(formData, 'useframework', args.useframework);
+    appendOptionalField(formData, 'annexIds', annexIds.join(','));
+    appendOptionalField(formData, 'knowledgeProductIds', knowledgeProductIds.join(','));
+    appendOptionalField(formData, 'originType', args.originType);
+
+    const result = await postForm(client, '/task/init', formData);
+    const cid = result.data.cid;
+    const snapshot = pickTaskSnapshot({
+        ...result.data,
+        cid,
+        sourceFrom: stringOption(args, 'sourceFrom', DEFAULT_SOURCE_FROM),
+        annexIds,
+        knowledgeProductIds,
+        localFiles: files,
+        fileTypes: fileMeta.types,
+        filePurposes: fileMeta.purposes,
+        originType: numberOption(args, 'originType'),
+    });
+    saveTaskSnapshot(state, cid, snapshot);
+
+    let finalParse = null;
+    if (booleanOption(args, 'wait')) {
+        finalParse = await pollParseUntilReady(client, state, cid, snapshot.uuid, args);
+    }
+
+    const resultPayload = {
+        command: 'init',
+        cid,
+        uuid: snapshot.uuid,
+        title: snapshot.projectName || snapshot.title,
+        files,
+        fileTypes: fileMeta.types,
+        parseResult: finalParse,
+    };
+    outputResult(args, resultPayload, [
+        `init success: cid=${cid}`,
+        `uuid: ${snapshot.uuid || '-'}`,
+        `title: ${snapshot.projectName || snapshot.title || '-'}`,
+        `files: ${files.map(item => path.basename(item)).join(', ')}`,
+        booleanOption(args, 'wait') && finalParse
+            ? `parse ready: success=${finalParse.success}`
+            : 'parse polling: run parse-status --wait to continue',
+    ].filter(Boolean));
+    return resultPayload;
+}
+
+async function handleParseStatus(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const snapshot = await hydrateTaskSnapshot(client, state, cid);
+    const uuid = stringOption(args, 'uuid', snapshot.uuid);
+    if (!uuid) {
+        throw new Error(`No uuid found for task ${cid}. Pass --uuid explicitly or run init first.`);
+    }
+
+    const result = booleanOption(args, 'wait')
+        ? await pollParseUntilReady(client, state, cid, uuid, args)
+        : await fetchParseStatus(client, state, cid, uuid);
+
+    outputResult(args, {
+        command: 'parse-status',
+        cid,
+        uuid,
+        ...result,
+    }, [
+        `parse status: cid=${cid}`,
+        `uuid: ${uuid}`,
+        `success: ${result.success}`,
+    ]);
+}
+
+function handleChoices(args) {
+    const scope = normalizeChoicesScope(args._[1] || 'all');
+    const payload = buildChoicesPayload(scope);
+    outputResult(args, payload, renderChoicesLines(payload));
+    return payload;
+}
+
+async function handleWizard(args, state) {
+    const wizardArgs = await collectWizardArgs(args, state);
+    writeNotice(args, `wizard config: ${buildWizardSummary(wizardArgs)}`);
+
+    const initResult = await handleInit({
+        ...wizardArgs,
+        _: ['init'],
+        wait: true,
+        interactive: false,
+    }, state);
+    const cid = initResult.cid;
+
+    const outlineResult = await handleOutline({
+        ...wizardArgs,
+        _: ['outline'],
+        cid,
+        uuid: initResult.uuid,
+        wait: true,
+        interactive: false,
+    }, state);
+
+    const writeResult = await handleWrite({
+        ...wizardArgs,
+        _: ['write'],
+        cid,
+        wait: true,
+        interactive: false,
+    }, state);
+
+    const exportResult = await handleExport({
+        ...wizardArgs,
+        _: ['export'],
+        cid,
+        interactive: false,
+    }, state);
+
+    const resultPayload = {
+        command: 'wizard',
+        cid,
+        initResult,
+        outlineResult,
+        writeResult,
+        exportResult,
+    };
+    outputResult(args, resultPayload, [
+        `wizard success: cid=${cid}`,
+        `outline: ${outlineResult?.triggerMode || '-'}`,
+        `content: ${writeResult?.waitResult?.task_status ?? '-'}`,
+        `savedPath: ${exportResult?.savedPath || '-'}`,
+    ]);
+    return resultPayload;
+}
+
+async function handleOutline(args, state) {
+    validateOutlineReferenceTypeOption(args);
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const snapshot = await hydrateTaskSnapshot(client, state, cid);
+    const outlineSnapshot = {
+        ...snapshot,
+        uuid: stringOption(args, 'uuid', snapshot.uuid),
+    };
+    const effectiveArgs = booleanOption(args, 'interactive')
+        ? await collectOutlineInteractiveArgs(args, outlineSnapshot)
+        : args;
+    const params = buildOutlineParams(outlineSnapshot, effectiveArgs);
+
+    const triggerMode = await triggerOutlineGeneration(client, outlineSnapshot, params);
+    saveTaskSnapshot(state, cid, {
+        ...outlineSnapshot,
+        ...pickTaskSnapshot(params),
+        triggerMode,
+        outlineTriggeredAt: new Date().toISOString(),
+    });
+
+    let waitResult = null;
+    if (booleanOption(effectiveArgs, 'wait')) {
+        waitResult = await waitForOutlineReady(client, state, cid, outlineSnapshot.uuid, effectiveArgs);
+    }
+
+    const summaryLines = [
+        `outline triggered: cid=${cid}`,
+        `pageScopeCode: ${params.pageScopeCode}`,
+        `base: ${params.base}`,
+        `config: ${buildOutlineConfigSummary(params)}`,
+        `triggerMode: ${triggerMode}`,
+    ];
+
+    if (waitResult?.phase === 'ready') {
+        summaryLines.push(`outline ready: rootChapters=${countOutlineRoots(waitResult)}`);
+    } else if (waitResult?.phase === 'supplement_required') {
+        summaryLines.push(`outline blocked: supplement required (${waitResult.issues.join(', ')})`);
+        for (const hint of collectIssueHints(waitResult.issues, args)) {
+            summaryLines.push(hint);
+        }
+    } else if (waitResult?.phase === 'reference_selection_required') {
+        summaryLines.push('outline blocked: reference selection required');
+        summaryLines.push('hint: rerun with --wait in an interactive terminal, or pass --reference-type <0|1|2>.');
+    } else if (waitResult?.phase === 'failed') {
+        summaryLines.push(`outline failed: task_status=${waitResult.taskDetail?.task_status ?? '-'}`);
+    } else {
+        summaryLines.push('outline generation started');
+    }
+
+    if (triggerMode === 'multiBiddingChoice' && !booleanOption(args, 'wait') && args.referenceType !== undefined) {
+        summaryLines.push('hint: --reference-type is applied during --wait polling; rerun with --wait to auto-submit the choice.');
+    }
+
+    const resultPayload = {
+        command: 'outline',
+        cid,
+        pageScopeCode: params.pageScopeCode,
+        base: params.base,
+        config: pickOutlineConfig(params),
+        triggerMode,
+        waitResult,
+    };
+    outputResult(args, resultPayload, [
+        ...summaryLines,
+    ]);
+    return resultPayload;
+}
+
+async function handleWrite(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const type = numberOption(args, 'type', 1);
+    const directoryWaitResult = await ensureDirectoryReadyForWrite(client, state, cid, args);
+
+    if (directoryWaitResult.phase !== 'ready') {
+        outputResult(args, {
+            command: 'write',
+            cid,
+            type,
+            directoryWaitResult,
+            waitResult: null,
+        }, [
+            `content generation blocked: cid=${cid}`,
+            directoryWaitResult.phase === 'reference_selection_required'
+                ? 'directory blocked: reference selection required'
+                : `directory blocked: phase=${directoryWaitResult.phase}`,
+            'hint: rerun in an interactive terminal, or pass --reference-type <0|1|2>.',
+        ]);
+        return;
+    }
+
+    const contentDetail = {
+        data: directoryWaitResult.contentDetail,
+    };
+    saveTaskSnapshot(state, cid, pickTaskSnapshot(contentDetail.data));
+
+    const writePreparation = await prepareContentGeneration(client, state, cid, contentDetail, args);
+    let triggerResult = null;
+    if (writePreparation.shouldTrigger) {
+        triggerResult = await triggerContentGeneration(client, cid, type, args);
+    }
+
+    saveTaskSnapshot(state, cid, {
+        writeTriggeredAt: new Date().toISOString(),
+        viewStep: writePreparation.viewStep,
+    });
+
+    let status = null;
+    if (booleanOption(args, 'wait')) {
+        status = await pollContentUntilReady(client, state, cid, args);
+    }
+
+    const resultPayload = {
+        command: 'write',
+        cid,
+        type,
+        directoryWaitResult,
+        writePreparation,
+        triggerResult,
+        waitResult: status,
+    };
+    outputResult(args, resultPayload, [
+        `directory ready: status=${directoryWaitResult.contentDetail?.directory_portion_status ?? '-'}`,
+        directoryWaitResult.directoryAction === 'triggered'
+            ? 'directory sequel: triggered'
+            : `directory sequel: ${directoryWaitResult.directoryAction}`,
+        `content generation prepared: cid=${cid}`,
+        writePreparation.chargeAction === 'charged'
+            ? 'charge: success'
+            : `charge: skipped (${writePreparation.chargeReason})`,
+        writePreparation.viewStepUpdated
+            ? `viewStep: set to ${CONTENT_VIEW_STEP}`
+            : `viewStep: keep ${writePreparation.viewStep ?? '-'}`,
+        triggerResult
+            ? `trigger: ${triggerResult.status}${triggerResult.softError ? ` (code=${triggerResult.softError.code})` : ''}`
+            : 'trigger: skipped (content already started or finished)',
+        `type: ${type}`,
+        status?.autoCompletionAction === 'generateAllUnfinished'
+            ? 'unfinished chapters: auto-triggered'
+            : 'unfinished chapters: none',
+        status
+            ? `content ready: task_status=${status.task_status}, content_portion_status=${status.content_portion_status ?? '-'}` 
+            : (triggerResult ? 'content generation started' : 'content generation not re-triggered'),
+    ]);
+    return resultPayload;
+}
+
+async function handleStatus(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const detail = await getJson(client, `/task/getTaskDetail/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT });
+    const contentDetail = booleanOption(args, 'content')
+        ? await getJson(client, '/c/getContentDetail', { cid, lite: true }, { retries: DEFAULT_RETRY_COUNT })
+        : null;
+
+    saveTaskSnapshot(state, cid, pickTaskSnapshot({
+        ...detail.data,
+        ...(contentDetail?.data || {}),
+    }));
+
+    outputResult(args, {
+        command: 'status',
+        cid,
+        taskDetail: detail.data,
+        contentDetail: contentDetail?.data || null,
+    }, [
+        `status: cid=${cid}`,
+        `title: ${detail.data.title || detail.data.projectName || '-'}`,
+        `task_status: ${detail.data.task_status ?? '-'}`,
+        `viewStep: ${contentDetail?.data?.viewStep ?? detail.data.viewStep ?? '-'}`,
+        `percentage: ${contentDetail?.data?.percentage ?? detail.data.percentage ?? '-'}`,
+    ]);
+}
+
+async function handleExport(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const snapshot = await hydrateTaskSnapshot(client, state, cid);
+    const effectiveArgs = booleanOption(args, 'interactive')
+        ? await collectExportInteractiveArgs(args, snapshot)
+        : args;
+    const templateIndex = numberOption(effectiveArgs, 'template', DEFAULT_EXPORT_TEMPLATE_INDEX);
+    if (!Number.isInteger(templateIndex) || templateIndex < 1 || templateIndex > templateData.length) {
+        throw new Error(`Unknown template index: ${templateIndex}`);
+    }
+    const template = templateData[templateIndex - 1];
+
+    const taskTitle = stringOption(effectiveArgs, 'title', snapshot.title || snapshot.projectName || `xique-${cid}`);
+    const layout = resolveExportLayout(snapshot, effectiveArgs);
+    const tableColor = enumOption(effectiveArgs, 'tableColor', TABLE_COLOR_OPTIONS, snapshot.tableColor || DEFAULT_TABLE_COLOR);
+    const tableStyle = enumOption(effectiveArgs, 'tableStyle', TABLE_STYLE_OPTIONS, snapshot.tableStyle ?? DEFAULT_TABLE_STYLE);
+    const themeStyleSetting = buildThemeStyleSetting(snapshot, effectiveArgs);
+    const pageMarginSetting = buildPageMarginSetting(snapshot, effectiveArgs);
+    const templatePostData = buildTemplatePostData(template, effectiveArgs);
+    const requestData = {
+        cid,
+        title: taskTitle,
+        addMark: binaryOption(effectiveArgs, 'addMark', DEFAULT_ADD_MARK),
+        autoNumber: binaryOption(effectiveArgs, 'autoNumber', DEFAULT_AUTO_NUMBER),
+        layout,
+        tableSettings: {
+            tableColor,
+            tableStyle,
+        },
+        themeStyleSetting,
+        pageMarginSetting,
+        t: Date.now(),
+        ...templatePostData,
+    };
+    const response = await postBinary(client, '/c/downWithStyle', requestData);
+    const fileName = parseFileName(response.headers['content-disposition']) || `${taskTitle}.docx`;
+    const savedPath = writeDownloadFile(effectiveArgs.out, fileName, response.data);
+    saveTaskSnapshot(state, cid, {
+        tableColor,
+        tableStyle,
+        themeStyleSetting,
+        pageMarginSetting,
+    });
+    const exportConfig = pickExportConfig(requestData, templateIndex);
+
+    const resultPayload = {
+        command: 'export',
+        cid,
+        fileName,
+        savedPath,
+        config: exportConfig,
+    };
+    outputResult(args, resultPayload, [
+        `export success: cid=${cid}`,
+        `fileName: ${fileName}`,
+        `config: ${buildExportConfigSummary(exportConfig)}`,
+        `savedPath: ${savedPath}`,
+    ]);
+    return resultPayload;
+}
+
+async function hydrateTaskSnapshot(client, state, cid) {
+    const cached = state.tasks?.[cid] || {};
+    let detailData = {};
+    try {
+        const detail = await getJson(client, `/task/getTaskDetail/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT });
+        detailData = detail.data || {};
+    } catch (error) {
+        if (!cached.cid) {
+            throw error;
+        }
+    }
+    const snapshot = pickTaskSnapshot({
+        ...cached,
+        ...detailData,
+        cid,
+    });
+    saveTaskSnapshot(state, cid, snapshot);
+    return snapshot;
+}
+
+function buildOutlineParams(snapshot, args) {
+    const pageScopeCode = enumOption(args, ['pageScope', 'pageScopeCode'], PAGE_SCOPE_OPTIONS, snapshot.pageScopeCode ?? DEFAULT_PAGE_SCOPE_CODE);
+    const base = enumOption(args, 'base', BASE_OPTIONS, snapshot.base ?? DEFAULT_BASE);
+    const uuid = snapshot.uuid;
+    const title = stringOption(args, 'title', snapshot.projectName || snapshot.title);
+    const plan = stringOption(args, 'plan', snapshot.plan || '');
+    const requirement = stringOption(args, 'requirement', snapshot.requirement || '');
+    const rating = stringOption(args, 'rating', snapshot.rating || '');
+
+    if (!uuid) {
+        throw new Error('Missing uuid for outline generation. Run init first or make sure the task snapshot contains uuid.');
+    }
+    if (!title) {
+        throw new Error('Missing title for outline generation.');
+    }
+
+    return compactObject({
+        cid: snapshot.cid,
+        themeStyle: enumOption(args, 'themeStyle', THEME_STYLE_OPTIONS, snapshot.themeStyle),
+        tableQuantity: enumOption(args, 'tableQuantity', TABLE_QUANTITY_OPTIONS, snapshot.tableQuantity),
+        mermaidStyle: enumOption(args, 'mermaidStyle', MERMAID_STYLE_OPTIONS, snapshot.mermaidStyle),
+        tableColor: enumOption(args, 'tableColor', TABLE_COLOR_OPTIONS, snapshot.tableColor),
+        tableStyle: enumOption(args, 'tableStyle', TABLE_STYLE_OPTIONS, snapshot.tableStyle),
+        annexIds: snapshot.annexIds || [],
+        knowledgeProductIds: snapshot.knowledgeProductIds || [],
+        base: pageScopeCode <= 0 ? '0' : base,
+        bidFileIds: [uuid],
+        directoryNodes: [],
+        generateType: 1,
+        pageScopeCode,
+        plan,
+        rating,
+        requirement,
+        title,
+        infoImg: binaryOption(args, 'infoImg', snapshot.infoImg),
+        sceneImg: binaryOption(args, 'sceneImg', snapshot.sceneImg),
+        onlineImg: binaryOption(args, 'onlineImg', snapshot.onlineImg),
+        mermaidImg: binaryOption(args, 'mermaidImg', snapshot.mermaidImg),
+        knowledgeImg: binaryOption(args, 'knowledgeImg', snapshot.knowledgeImg),
+        themeStyleSetting: snapshot.themeStyleSetting,
+        pageMarginSetting: snapshot.pageMarginSetting,
+        multiBidId: stringOption(args, 'multiBidId', snapshot.multiBidId),
+        multiBidType: stringOption(args, 'multiBidType', snapshot.multiBidType),
+        planMode: enumOption(args, 'planMode', PLAN_MODE_OPTIONS, snapshot.planMode ?? 0),
+        epcEngineerType: normalizeEpcEngineerType(stringOption(args, 'epcEngineerType', snapshot.epcEngineerType)),
+    });
+}
+
+async function triggerOutlineGeneration(client, snapshot, params) {
+    await postJson(client, '/task/preSet', params);
+
+    const hasTaskStatus = snapshot.task_status !== undefined && snapshot.task_status !== null;
+    if (hasTaskStatus && Number(snapshot.task_status) !== 0) {
+        await getJson(client, '/proxy/multiBiddingChoice', compactObject({
+            uuid: snapshot.uuid,
+            multiBidId: params.multiBidId ?? snapshot.multiBidId,
+            epcEngineerType: normalizeEpcEngineerTypeForProxy(params.epcEngineerType ?? snapshot.epcEngineerType),
+        }));
+        return 'multiBiddingChoice';
+    }
+
+    await postJson(client, '/task/generateByRequirement', params);
+    return 'generateByRequirement';
+}
+
+function buildFileMetadata(files, args) {
+    const typeValues = ensureArray(args.type);
+    const purposeValues = ensureArray(args.purpose);
+    if (typeValues.length > 1 && typeValues.length !== files.length) {
+        throw new Error('When passing multiple --type values, the count must match the number of files.');
+    }
+    if (purposeValues.length > 1 && purposeValues.length !== files.length) {
+        throw new Error('When passing multiple --purpose values, the count must match the number of files.');
+    }
+
+    const types = files.map((filePath, index) => {
+        if (typeValues.length === files.length) {
+            return typeValues[index];
+        }
+        if (typeValues.length === 1) {
+            return typeValues[0];
+        }
+        const detected = detectFileType(path.basename(filePath));
+        if (detected) {
+            return detected;
+        }
+        return index === 0 ? 'BDOC01' : 'QT0000';
+    });
+
+    const purposes = files.map((filePath, index) => {
+        if (purposeValues.length === files.length) {
+            return purposeValues[index];
+        }
+        if (purposeValues.length === 1) {
+            return purposeValues[0];
+        }
+        return AI_PURPOSE_MAP[types[index]] || '';
+    });
+
+    const purposesPayload = purposes.map((purpose, index) => `[${types[index]}]${purpose || ''}`).join('@@@');
+    return {
+        types,
+        purposes,
+        purposesPayload,
+    };
+}
+
+async function pollParseUntilReady(client, state, cid, uuid, args) {
+    return pollUntil(async () => {
+        const result = await fetchParseStatus(client, state, cid, uuid);
+        return {
+            done: isParseReadyForNextStep(result.success),
+            data: result,
+            progressLabel: `success=${result.success}`,
+        };
+    }, {
+        intervalMs: secondsToMs(numberOption(args, 'intervalSec', DEFAULT_PARSE_INTERVAL_MS / 1000)),
+        timeoutMs: secondsToMs(numberOption(args, 'timeoutSec', DEFAULT_TIMEOUT_MS / 1000)),
+        quiet: booleanOption(args, 'json'),
+        waitingText: 'waiting parse result',
+    });
+}
+
+function isParseReadyForNextStep(success) {
+    const parsed = Number(success);
+    return parsed === 1 || parsed === 4;
+}
+
+async function pollTaskUntil(client, state, cid, args, isDone, formatProgress) {
+    return pollUntil(async () => {
+        const detail = await getJson(client, `/task/getTaskDetail/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT });
+        saveTaskSnapshot(state, cid, pickTaskSnapshot(detail.data));
+        return {
+            done: isDone(detail.data),
+            data: detail.data,
+            progressLabel: formatProgress(detail.data),
+        };
+    }, {
+        intervalMs: secondsToMs(numberOption(args, 'intervalSec', DEFAULT_TASK_INTERVAL_MS / 1000)),
+        timeoutMs: secondsToMs(numberOption(args, 'timeoutSec', DEFAULT_TIMEOUT_MS / 1000)),
+        quiet: booleanOption(args, 'json'),
+        waitingText: 'waiting task status',
+    });
+}
+
+async function waitForOutlineReady(client, state, cid, uuid, args) {
+    const handledIssues = new Set();
+    let submittedReferenceType = null;
+
+    return pollUntil(async () => {
+        const [taskDetail, outlineDetail, referenceStatus] = await Promise.all([
+            getJson(client, `/task/getTaskDetail/${encodeURIComponent(cid)}`),
+            fetchOutlineDetail(client, cid),
+            fetchReferenceStatusSafe(client, cid),
+        ]);
+        saveTaskSnapshot(state, cid, pickTaskSnapshot(taskDetail.data));
+
+        const outlineData = outlineDetail?.data || {};
+        const hasOutline = isOutlineReadyForCli(outlineData);
+        const referenceData = referenceStatus?.data || {};
+        const referencePhase = normalizeReferenceStatus(referenceData.status);
+        if (referencePhase !== null) {
+            saveTaskSnapshot(state, cid, {
+                referenceStatus: referencePhase,
+            });
+        }
+
+        if (Number(taskDetail.data?.task_status) === 7) {
+            return {
+                done: true,
+                data: {
+                    phase: 'failed',
+                    taskDetail: taskDetail.data,
+                    outlineDetail: outlineData,
+                },
+                progressLabel: 'task_status=7',
+            };
+        }
+
+        const forcedReferenceSubmission = await submitExplicitReferenceTypeIfNeeded(
+            client,
+            cid,
+            args,
+            taskDetail.data,
+            submittedReferenceType,
+        );
+        if (forcedReferenceSubmission !== null) {
+            submittedReferenceType = forcedReferenceSubmission;
+            saveTaskSnapshot(state, cid, {
+                outlineReferenceType: submittedReferenceType,
+            });
+            return {
+                done: false,
+                data: null,
+                progressLabel: `referenceType=${submittedReferenceType} submitted from directory status, waiting outline`,
+            };
+        }
+
+        if (hasOutline) {
+            return {
+                done: true,
+                data: {
+                    phase: 'ready',
+                    taskDetail: taskDetail.data,
+                    outlineDetail: outlineData,
+                },
+                progressLabel: `rootChapters=${countOutlineRoots({ outlineDetail: outlineData, taskDetail: taskDetail.data })}`,
+            };
+        }
+
+        if (referencePhase === 1) {
+            if (submittedReferenceType !== null) {
+                return {
+                    done: false,
+                    data: null,
+                    progressLabel: `reference_status=1, referenceType=${submittedReferenceType}, waiting confirmation`,
+                };
+            }
+
+            const selection = await resolveOutlineReferenceSelection(args, referenceData);
+            if (!selection.ready) {
+                return {
+                    done: true,
+                    data: {
+                        phase: 'reference_selection_required',
+                        taskDetail: taskDetail.data,
+                        outlineDetail: outlineData,
+                        referenceDetail: referenceData,
+                        options: buildOutlineReferenceChoices(referenceData),
+                    },
+                    progressLabel: 'reference_selection_required',
+                };
+            }
+
+            await submitOutlineReferenceType(client, cid, selection.referenceType);
+            submittedReferenceType = selection.referenceType;
+            saveTaskSnapshot(state, cid, {
+                outlineReferenceType: selection.referenceType,
+            });
+            return {
+                done: false,
+                data: null,
+                progressLabel: `referenceType=${selection.referenceType} submitted, waiting outline`,
+            };
+        }
+
+        if (uuid) {
+            const parseStatus = await fetchParseStatus(client, state, cid, uuid);
+            const parseSuccess = Number(parseStatus.success);
+            const issues = collectParseIssues(parseStatus);
+
+            if (parseSuccess === 4 && issues.length > 0) {
+                const autoIgnore = resolveAutoIgnoreIssue(issues, args, uuid, handledIssues);
+
+                if (autoIgnore) {
+                    await submitIntermediateChoice(client, autoIgnore.payload);
+                    handledIssues.add(autoIgnore.issue);
+                    return {
+                        done: false,
+                        data: null,
+                        progressLabel: `ignored ${autoIgnore.issue}, waiting outline`,
+                    };
+                }
+
+                return {
+                    done: true,
+                    data: {
+                        phase: 'supplement_required',
+                        issues,
+                        parseStatus,
+                        taskDetail: taskDetail.data,
+                        outlineDetail: outlineData,
+                    },
+                    progressLabel: `supplement_required=${issues.join(',')}`,
+                };
+            }
+
+            return {
+                done: false,
+                data: null,
+                progressLabel: `success=${parseSuccess}, task_status=${taskDetail.data?.task_status ?? '-'}, directory_status=${taskDetail.data?.directory_portion_status ?? '-'}, outline_roots=${countOutlineRoots({ outlineDetail: outlineData })}, outline_status=${outlineData.outline_status ? 1 : 0}, reference_status=${referencePhase ?? '-'}`,
+            };
+        }
+
+        return {
+            done: false,
+            data: null,
+            progressLabel: `task_status=${taskDetail.data?.task_status ?? '-'}, directory_status=${taskDetail.data?.directory_portion_status ?? '-'}, outline_roots=${countOutlineRoots({ outlineDetail: outlineData })}, outline_status=${outlineData.outline_status ? 1 : 0}, reference_status=${referencePhase ?? '-'}`,
+        };
+    }, {
+        intervalMs: secondsToMs(numberOption(args, 'intervalSec', DEFAULT_TASK_INTERVAL_MS / 1000)),
+        timeoutMs: secondsToMs(numberOption(args, 'timeoutSec', DEFAULT_TIMEOUT_MS / 1000)),
+        quiet: booleanOption(args, 'json'),
+        waitingText: 'waiting outline generation',
+    });
+}
+
+async function pollContentUntilReady(client, state, cid, args) {
+    let unfinishedTriggered = false;
+    let lastUnfinishedTriggerAt = 0;
+
+    return pollUntil(async () => {
+        const detail = await fetchContentDetail(client, cid);
+        const contentData = detail.data || {};
+        saveTaskSnapshot(state, cid, pickTaskSnapshot(contentData));
+
+        const taskStatus = Number(contentData.task_status);
+        const contentPortionStatus = Number(contentData.content_portion_status);
+        const completedChapter = numberOrDefault(contentData.completedChapter, 0);
+        const totalChapter = numberOrDefault(contentData.totalChapter, 0);
+        const percentage = numberOrDefault(contentData.percentage, 0);
+
+        if (isContentComplete(contentData)) {
+            return {
+                done: true,
+                data: {
+                    ...contentData,
+                    autoCompletionAction: unfinishedTriggered ? 'generateAllUnfinished' : 'none',
+                },
+                progressLabel: `task_status=${taskStatus}, content_portion_status=${contentPortionStatus}, completed=${completedChapter}/${totalChapter}, percentage=${percentage}`,
+            };
+        }
+
+        if (shouldTriggerGenerateAllUnfinished(contentData)) {
+            const now = Date.now();
+            if (!unfinishedTriggered || now - lastUnfinishedTriggerAt >= GENERATE_UNFINISHED_RETRY_INTERVAL_MS) {
+                await triggerGenerateAllUnfinished(client, cid);
+                unfinishedTriggered = true;
+                lastUnfinishedTriggerAt = now;
+                saveTaskSnapshot(state, cid, {
+                    generateAllUnfinishedTriggeredAt: new Date(now).toISOString(),
+                });
+                return {
+                    done: false,
+                    data: null,
+                    progressLabel: `generateAllUnfinished triggered, completed=${completedChapter}/${totalChapter}, percentage=${percentage}`,
+                };
+            }
+        }
+
+        const done = (taskStatus === 5 || (taskStatus === 4 && contentPortionStatus === 1))
+            && !hasUnfinishedChapters(contentData);
+        return {
+            done,
+            data: done
+                ? {
+                    ...contentData,
+                    autoCompletionAction: unfinishedTriggered ? 'generateAllUnfinished' : 'none',
+                }
+                : contentData,
+            progressLabel: `task_status=${taskStatus}, content_portion_status=${contentPortionStatus}, completed=${completedChapter}/${totalChapter}, percentage=${percentage}`,
+        };
+    }, {
+        intervalMs: secondsToMs(numberOption(args, 'intervalSec', DEFAULT_TASK_INTERVAL_MS / 1000)),
+        timeoutMs: secondsToMs(numberOption(args, 'timeoutSec', DEFAULT_TIMEOUT_MS / 1000)),
+        quiet: booleanOption(args, 'json'),
+        waitingText: 'waiting content generation',
+    });
+}
+
+async function fetchOutlineDetail(client, cid) {
+    return getJson(client, '/c/getOutLineDetail', { cid }, { retries: DEFAULT_RETRY_COUNT });
+}
+
+async function fetchReferenceStatusSafe(client, cid) {
+    try {
+        return await getJson(client, `/task/directory/checkReference/${encodeURIComponent(cid)}`, {}, { retries: DEFAULT_RETRY_COUNT });
+    } catch (error) {
+        return null;
+    }
+}
+
+async function fetchContentDetail(client, cid) {
+    return getJson(client, '/c/getContentDetail', {
+        cid,
+        lite: true,
+    }, { retries: DEFAULT_RETRY_COUNT });
+}
+
+async function fetchParseStatus(client, state, cid, uuid) {
+    const result = await getJson(client, '/proxy/getFileAsyncResult', {
+        cid,
+        uuid,
+    }, { retries: DEFAULT_RETRY_COUNT });
+    saveTaskSnapshot(state, cid, {
+        uuid,
+        parseSuccess: result.data?.success,
+        parseStatusFetchedAt: new Date().toISOString(),
+    });
+    return result.data || {};
+}
+
+async function submitIntermediateChoice(client, payload) {
+    return postJson(client, '/proxy/inputTextExtend', payload);
+}
+
+async function submitOutlineReferenceType(client, cid, referenceType) {
+    return postJson(client, '/task/directory/generateByReferenceType', {
+        cid,
+        referenceType,
+    });
+}
+
+async function submitExplicitReferenceTypeIfNeeded(client, cid, args, detail, submittedReferenceType) {
+    if (submittedReferenceType !== null) {
+        return null;
+    }
+    const explicitRaw = stringOption(args, 'referenceType');
+    if (explicitRaw === undefined) {
+        return null;
+    }
+    const referenceType = parseOutlineReferenceType(explicitRaw);
+    if (referenceType === null) {
+        return null;
+    }
+    const directoryStatus = normalizeDirectoryPortionStatus(detail?.directory_portion_status);
+    if (directoryStatus !== DIRECTORY_PORTION_STATUS.OUTLINE_BASE_COMPLETED) {
+        return null;
+    }
+    await submitOutlineReferenceType(client, cid, referenceType);
+    return referenceType;
+}
+
+async function triggerDirectorySequel(client, cid) {
+    return getJson(client, `/task/sequelForOutline/${encodeURIComponent(cid)}`);
+}
+
+async function triggerGenerateAllUnfinished(client, cid) {
+    return postJson(client, '/task/generateAllUnfinished', { cid });
+}
+
+async function ensureDirectoryReadyForWrite(client, state, cid, args) {
+    let submittedReferenceType = null;
+    let sequelTriggered = false;
+    let lastSequelTriggerAt = 0;
+
+    return pollUntil(async () => {
+        const [taskDetail, outlineDetail, contentDetail, referenceStatus] = await Promise.all([
+            getJson(client, `/task/getTaskDetail/${encodeURIComponent(cid)}`),
+            fetchOutlineDetail(client, cid),
+            fetchContentDetail(client, cid),
+            fetchReferenceStatusSafe(client, cid),
+        ]);
+
+        const taskData = taskDetail?.data || {};
+        const outlineData = outlineDetail?.data || {};
+        const contentData = contentDetail?.data || {};
+        const effectiveContentData = {
+            ...taskData,
+            ...contentData,
+        };
+        const referenceData = referenceStatus?.data || {};
+        const referencePhase = normalizeReferenceStatus(referenceData.status);
+
+        saveTaskSnapshot(state, cid, pickTaskSnapshot({
+            ...taskData,
+            ...contentData,
+        }));
+        if (referencePhase !== null) {
+            saveTaskSnapshot(state, cid, {
+                referenceStatus: referencePhase,
+            });
+        }
+
+        if (isDirectoryReadyForWrite(effectiveContentData)) {
+            return {
+                done: true,
+                data: {
+                    phase: 'ready',
+                    taskDetail: taskData,
+                    outlineDetail: outlineData,
+                    contentDetail: effectiveContentData,
+                    referenceDetail: referenceData,
+                    directoryAction: sequelTriggered ? 'triggered' : 'already_ready',
+                },
+                progressLabel: `directory_status=${effectiveContentData.directory_portion_status}, nodes=${countDirectoryRoots(effectiveContentData)}`,
+            };
+        }
+
+        const forcedReferenceSubmission = await submitExplicitReferenceTypeIfNeeded(
+            client,
+            cid,
+            args,
+            effectiveContentData,
+            submittedReferenceType,
+        );
+        if (forcedReferenceSubmission !== null) {
+            submittedReferenceType = forcedReferenceSubmission;
+            saveTaskSnapshot(state, cid, {
+                outlineReferenceType: submittedReferenceType,
+            });
+            return {
+                done: false,
+                data: null,
+                progressLabel: `referenceType=${submittedReferenceType} submitted from directory status, waiting outline`,
+            };
+        }
+
+        if (referencePhase === 1) {
+            if (submittedReferenceType !== null) {
+                return {
+                    done: false,
+                    data: null,
+                    progressLabel: `reference_status=1, referenceType=${submittedReferenceType}, waiting outline`,
+                };
+            }
+
+            const selection = await resolveOutlineReferenceSelection(args, referenceData);
+            if (!selection.ready) {
+                return {
+                    done: true,
+                    data: {
+                        phase: 'reference_selection_required',
+                        taskDetail: taskData,
+                        outlineDetail: outlineData,
+                        contentDetail: contentData,
+                        referenceDetail: referenceData,
+                        options: buildOutlineReferenceChoices(referenceData),
+                        directoryAction: sequelTriggered ? 'triggered' : 'not_started',
+                    },
+                    progressLabel: 'reference_selection_required',
+                };
+            }
+
+            await submitOutlineReferenceType(client, cid, selection.referenceType);
+            submittedReferenceType = selection.referenceType;
+            saveTaskSnapshot(state, cid, {
+                outlineReferenceType: selection.referenceType,
+            });
+            return {
+                done: false,
+                data: null,
+                progressLabel: `referenceType=${selection.referenceType} submitted, waiting outline`,
+            };
+        }
+
+        const directoryStatus = normalizeDirectoryPortionStatus(
+            effectiveContentData.directory_portion_status,
+        );
+        if (directoryStatus === DIRECTORY_PORTION_STATUS.OUTLINE_COMPLETED) {
+            const now = Date.now();
+            if (!sequelTriggered || now - lastSequelTriggerAt >= DIRECTORY_SEQUEL_RETRY_INTERVAL_MS) {
+                const isInitialTrigger = !sequelTriggered;
+                await triggerDirectorySequel(client, cid);
+                sequelTriggered = true;
+                lastSequelTriggerAt = now;
+                saveTaskSnapshot(state, cid, {
+                    directorySequelTriggeredAt: new Date(now).toISOString(),
+                });
+                return {
+                    done: false,
+                    data: null,
+                    progressLabel: isInitialTrigger
+                        ? 'sequelForOutline triggered, waiting directory'
+                        : 'sequelForOutline retried, waiting directory',
+                };
+            }
+            return {
+                done: false,
+                data: null,
+                progressLabel: 'directory_status=1, waiting sequel',
+            };
+        }
+
+        if (directoryStatus === DIRECTORY_PORTION_STATUS.SEQUEL_GENERATING) {
+            sequelTriggered = true;
+        }
+
+        return {
+            done: false,
+            data: null,
+            progressLabel: `directory_status=${directoryStatus ?? '-'}, directory_nodes=${countDirectoryRoots(effectiveContentData)}, outline_roots=${countOutlineRoots({ outlineDetail: outlineData })}, outline_status=${outlineData.outline_status ? 1 : 0}, reference_status=${referencePhase ?? '-'}`,
+        };
+    }, {
+        intervalMs: secondsToMs(numberOption(args, 'intervalSec', DEFAULT_TASK_INTERVAL_MS / 1000)),
+        timeoutMs: secondsToMs(numberOption(args, 'timeoutSec', DEFAULT_TIMEOUT_MS / 1000)),
+        quiet: booleanOption(args, 'json'),
+        waitingText: 'waiting directory phase',
+    });
+}
+
+async function prepareContentGeneration(client, state, cid, contentDetailResponse, args) {
+    const contentDetail = contentDetailResponse?.data || {};
+    const viewStep = Number(contentDetail.viewStep);
+    const taskStatus = Number(contentDetail.task_status);
+    const contentPortionStatus = Number(contentDetail.content_portion_status);
+    const contentAlreadyStarted = isContentStarted(contentDetail);
+
+    let chargeAction = 'skipped';
+    let chargeReason = '';
+    let viewStepUpdated = false;
+
+    if (viewStep === CONTENT_VIEW_STEP) {
+        chargeReason = 'already_in_content_phase';
+    } else if (contentAlreadyStarted) {
+        chargeReason = 'content_already_started';
+    } else {
+        await chargeForContent(client, cid);
+        chargeAction = 'charged';
+        chargeReason = 'charged_before_write';
+        await setContentViewStep(client, cid);
+        viewStepUpdated = true;
+    }
+
+    const shouldTrigger = !isContentRunningOrDone(contentDetail);
+    const snapshotPatch = compactObject({
+        cid,
+        viewStep: viewStepUpdated ? CONTENT_VIEW_STEP : contentDetail.viewStep,
+        task_status: Number.isFinite(taskStatus) ? taskStatus : undefined,
+        content_portion_status: Number.isFinite(contentPortionStatus) ? contentPortionStatus : undefined,
+        chargeAction,
+        chargeReason,
+    });
+    saveTaskSnapshot(state, cid, snapshotPatch);
+
+    return {
+        chargeAction,
+        chargeReason,
+        viewStep: viewStepUpdated ? CONTENT_VIEW_STEP : contentDetail.viewStep,
+        viewStepUpdated,
+        shouldTrigger,
+        taskStatus,
+        contentPortionStatus,
+    };
+}
+
+async function chargeForContent(client, cid) {
+    return postJson(client, '/order/charge', { cid });
+}
+
+async function setContentViewStep(client, cid) {
+    return postJson(client, '/c/viewStep', {
+        cid,
+        viewStep: CONTENT_VIEW_STEP,
+    });
+}
+
+async function triggerContentGeneration(client, cid, type, args) {
+    const maxRetries = 1;
+    let retryCount = 0;
+
+    while (retryCount <= maxRetries) {
+        try {
+            const result = await getJson(client, `/task/autoGenerateContent/${encodeURIComponent(cid)}/${type}`);
+            return {
+                status: 'triggered',
+                retryCount,
+                response: result.data || null,
+                softError: null,
+            };
+        } catch (error) {
+            const errorCode = Number(error?.code);
+            if (errorCode === 429 && retryCount < maxRetries) {
+                retryCount += 1;
+                if (!booleanOption(args, 'json')) {
+                    console.log('content trigger busy: retrying in 30 seconds');
+                }
+                await sleep(30_000);
+                continue;
+            }
+            if (SOFT_CONTENT_TRIGGER_CODES.has(errorCode)) {
+                return {
+                    status: 'accepted_with_soft_error',
+                    retryCount,
+                    response: null,
+                    softError: {
+                        code: errorCode,
+                        message: error.message,
+                    },
+                };
+            }
+            throw error;
+        }
+    }
+
+    return {
+        status: 'skipped',
+        retryCount,
+        response: null,
+        softError: null,
+    };
+}
+
+function isContentStarted(detail) {
+    return Number(detail?.viewStep) === CONTENT_VIEW_STEP || isContentRunningOrDone(detail);
+}
+
+function isContentRunningOrDone(detail) {
+    const taskStatus = Number(detail?.task_status);
+    const contentPortionStatus = Number(detail?.content_portion_status);
+    return taskStatus >= 4 || contentPortionStatus > 0;
+}
+
+async function pollUntil(checkFn, options) {
+    const startedAt = Date.now();
+    while (true) {
+        const result = await checkFn();
+        if (result.done) {
+            return result.data;
+        }
+        if (options.timeoutMs > 0 && Date.now() - startedAt >= options.timeoutMs) {
+            throw new Error(`${options.waitingText} timed out after ${Math.round(options.timeoutMs / 1000)} seconds.`);
+        }
+        if (!options.quiet) {
+            console.log(`${options.waitingText}: ${result.progressLabel}`);
+        }
+        await sleep(options.intervalMs);
+    }
+}
+
+function outputResult(args, jsonPayload, lines) {
+    if (booleanOption(args, 'json')) {
+        console.log(JSON.stringify(jsonPayload, null, 2));
+        return;
+    }
+    for (const line of lines) {
+        console.log(line);
+    }
+}
+
+function collectParseIssues(result) {
+    const issueKeys = [
+        'requirement_exist',
+        'requirement_judgement',
+        'billOfQuantities_judgement',
+        'score_judgement',
+        'directory_judgement',
+        'scoreAndDirectory_judgement',
+        'bidderIdentity_judgement',
+    ];
+
+    return issueKeys.filter(key => {
+        const directValue = result[key];
+        const nestedValue = result.judgement_status?.[key.replace('_judgement', '')];
+        return String(directValue ?? nestedValue ?? '1') === '0';
+    });
+}
+
+function normalizeReferenceStatus(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+
+function parseOutlineReferenceType(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const normalized = String(value).trim().toLowerCase();
+    const option = OUTLINE_REFERENCE_OPTIONS.find(item => item.aliases.includes(normalized));
+    return option ? option.value : null;
+}
+
+function validateOutlineReferenceTypeOption(args) {
+    const explicitRaw = stringOption(args, 'referenceType');
+    if (explicitRaw === undefined) {
+        return;
+    }
+    if (parseOutlineReferenceType(explicitRaw) === null) {
+        throw new Error('Option --reference-type expects 0, 1, 2, merge, format, or score.');
+    }
+}
+
+function normalizeChoicesScope(value) {
+    const normalized = String(value || 'all').trim().toLowerCase();
+    if (['all', 'outline', 'export'].includes(normalized)) {
+        return normalized;
+    }
+    throw new Error('choices expects an optional section: all, outline, or export.');
+}
+
+function buildChoicesPayload(scope) {
+    const payload = {
+        command: 'choices',
+        scope,
+    };
+    if (scope === 'all' || scope === 'outline') {
+        payload.outline = {
+            pageScope: PAGE_SCOPE_OPTIONS,
+            base: BASE_OPTIONS,
+            themeStyle: THEME_STYLE_OPTIONS,
+            tableQuantity: TABLE_QUANTITY_OPTIONS,
+            tableColor: TABLE_COLOR_OPTIONS,
+            tableStyle: TABLE_STYLE_OPTIONS,
+            imageToggles: ['infoImg', 'sceneImg', 'onlineImg', 'mermaidImg', 'knowledgeImg'],
+            mermaidStyle: MERMAID_STYLE_OPTIONS,
+            planMode: PLAN_MODE_OPTIONS,
+            multiBid: ['--multi-bid-id', '--multi-bid-type'],
+            epcEngineerType: {
+                option: '--epc-engineer-type',
+                aliases: Object.keys(EPC_ENGINEER_TYPE_ALIAS_MAP),
+            },
+        };
+    }
+    if (scope === 'all' || scope === 'export') {
+        payload.export = {
+            template: EXPORT_TEMPLATE_OPTIONS,
+            autoNumber: BINARY_OPTIONS,
+            addMark: BINARY_OPTIONS,
+            layout: LAYOUT_OPTIONS,
+            tableColor: TABLE_COLOR_OPTIONS,
+            tableStyle: TABLE_STYLE_OPTIONS,
+            advancedStyle: {
+                option: '--style-json',
+                fields: ['startIndex', 'directorySettings', 'contentSettings'],
+            },
+            pageMargins: PAGE_MARGIN_FIELDS.map(field => `--${toKebabCase(field.optionKeys[0])}`),
+            themeColors: THEME_STYLE_SETTING_FIELDS.map(field => field.optionKeys.map(key => `--${toKebabCase(key)}`).join('/')),
+        };
+    }
+    return payload;
+}
+
+function renderChoicesLines(payload) {
+    const lines = [
+        `choices: scope=${payload.scope}`,
+    ];
+    if (payload.outline) {
+        lines.push('outline:');
+        lines.push(`  page-scope: ${formatChoiceOptions(PAGE_SCOPE_OPTIONS)}`);
+        lines.push(`  base: ${formatChoiceOptions(BASE_OPTIONS)}`);
+        lines.push(`  theme-style: ${formatChoiceOptions(THEME_STYLE_OPTIONS)}`);
+        lines.push(`  table-quantity: ${formatChoiceOptions(TABLE_QUANTITY_OPTIONS)}`);
+        lines.push(`  table-color: ${formatChoiceOptions(TABLE_COLOR_OPTIONS)}`);
+        lines.push(`  table-style: ${formatChoiceOptions(TABLE_STYLE_OPTIONS)}`);
+        lines.push(`  mermaid-style: ${formatChoiceOptions(MERMAID_STYLE_OPTIONS)}`);
+        lines.push(`  plan-mode: ${formatChoiceOptions(PLAN_MODE_OPTIONS)}`);
+        lines.push('  image toggles: --info-img, --scene-img, --online-img, --mermaid-img, --knowledge-img (0|1)');
+        lines.push('  multi-bid override: --multi-bid-id <id>, --multi-bid-type <text>');
+        lines.push(`  epc-engineer-type: --epc-engineer-type <text>; aliases=${Object.keys(EPC_ENGINEER_TYPE_ALIAS_MAP).join(', ')}`);
+    }
+    if (payload.export) {
+        lines.push('export:');
+        lines.push(`  template: ${formatChoiceOptions(EXPORT_TEMPLATE_OPTIONS)}`);
+        lines.push(`  layout: ${formatChoiceOptions(LAYOUT_OPTIONS)}`);
+        lines.push(`  table-color: ${formatChoiceOptions(TABLE_COLOR_OPTIONS)}`);
+        lines.push(`  table-style: ${formatChoiceOptions(TABLE_STYLE_OPTIONS)}`);
+        lines.push('  binary toggles: --auto-number, --add-mark (0|1)');
+        lines.push('  advanced style: --style-json <file> with startIndex, directorySettings, contentSettings');
+        lines.push(`  margins: ${PAGE_MARGIN_FIELDS.map(field => `--${toKebabCase(field.optionKeys[0])}`).join(', ')}`);
+        lines.push(`  theme colors: ${THEME_STYLE_SETTING_FIELDS.map(field => field.optionKeys.map(key => `--${toKebabCase(key)}`).join('/')).join(', ')}`);
+    }
+    return lines;
+}
+
+function formatChoiceOptions(options) {
+    return options
+        .map(option => {
+            const desc = option.description ? ` (${option.description})` : '';
+            return `${option.value}=${option.label}${desc}`;
+        })
+        .join('; ');
+}
+
+async function collectWizardArgs(args, state) {
+    return runPromptSession(args, async context => {
+        const wizardArgs = {
+            ...args,
+            file: stringOption(args, 'file'),
+            out: stringOption(args, 'out'),
+        };
+        context.promptStream.write('\n\u6B22\u8FCE\u4F7F\u7528 xq-cli \u5168\u6D41\u7A0B\u5411\u5BFC\u3002\u8FD9\u4E2A\u5411\u5BFC\u4F1A\u4F9D\u6B21\u6267\u884C init -> outline -> write -> export\u3002\n');
+
+        const existingFiles = resolveFileArgs(wizardArgs);
+        if (existingFiles.length > 0) {
+            wizardArgs.file = existingFiles[0];
+        } else {
+            wizardArgs.file = await promptText(context, {
+                title: '\n[1/3] \u9009\u62E9\u62DB\u6807\u6587\u4EF6',
+                question: '\u8BF7\u8F93\u5165\u62DB\u6807\u6587\u4EF6\u8DEF\u5F84',
+                required: true,
+                transform: value => path.resolve(value),
+                validate: value => fs.existsSync(value) ? null : `\u6587\u4EF6\u4E0D\u5B58\u5728: ${value}`,
+            });
+        }
+
+        const outlineDefaults = buildInteractiveSnapshotDefaults(wizardArgs);
+        const outlineArgs = await collectOutlineInteractiveArgs(wizardArgs, outlineDefaults, context, {
+            header: '\n[2/3] \u8BBE\u7F6E\u5927\u7EB2/\u6B63\u6587\u751F\u6210\u53C2\u6570',
+        });
+        Object.assign(wizardArgs, outlineArgs);
+
+        const exportSnapshot = {
+            ...outlineDefaults,
+            ...pickOutlineConfig(buildOutlineParams({
+                ...outlineDefaults,
+                cid: 'wizard-preview',
+                uuid: 'wizard-preview',
+                title: 'wizard-preview',
+                projectName: 'wizard-preview',
+            }, outlineArgs)),
+        };
+        const exportArgs = await collectExportInteractiveArgs({
+            ...wizardArgs,
+            out: stringOption(wizardArgs, 'out', buildWizardDefaultOutputPath()),
+        }, exportSnapshot, context, {
+            header: '\n[3/3] \u8BBE\u7F6E\u5BFC\u51FA\u53C2\u6570',
+        });
+        Object.assign(wizardArgs, exportArgs);
+
+        context.promptStream.write(`\n\u5C06\u8981\u6267\u884C: ${buildWizardSummary(wizardArgs)}\n`);
+        const confirmed = await promptYesNo(context, '\u662F\u5426\u7ACB\u5373\u5F00\u59CB\u6267\u884C\u5168\u6D41\u7A0B', true);
+        if (!confirmed) {
+            throw new Error('Wizard cancelled by user.');
+        }
+
+        wizardArgs.wait = true;
+        wizardArgs.interactive = false;
+        wizardArgs._ = args._;
+        return wizardArgs;
+    });
+}
+
+async function collectOutlineInteractiveArgs(args, snapshot, context = null, options = {}) {
+    const promptFn = async promptContext => {
+        const nextArgs = { ...args };
+        const defaults = buildInteractiveSnapshotDefaults(snapshot);
+        if (options.header) {
+            promptContext.promptStream.write(`${options.header}\n`);
+        }
+
+        const pageScopeCode = await promptChoice(promptContext, {
+            title: '\u5168\u6587\u7BC7\u5E45',
+            question: '\u8BF7\u9009\u62E9\u7BC7\u5E45\u7F16\u53F7',
+            options: PAGE_SCOPE_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: PAGE_SCOPE_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, ['pageScope', 'pageScopeCode'], PAGE_SCOPE_OPTIONS, defaults.pageScopeCode),
+        });
+        nextArgs.pageScope = pageScopeCode;
+
+        if (pageScopeCode <= 0) {
+            promptContext.promptStream.write('\u5DF2\u9009\u62E9\u77ED\u7BC7\u6A21\u5F0F\uFF0C\u5199\u4F5C\u6A21\u5F0F\u5C06\u56FA\u5B9A\u4E3A\u201C\u6807\u51C6\u5199\u4F5C\u201D\u3002\n');
+            nextArgs.base = '0';
+        } else {
+            nextArgs.base = await promptChoice(promptContext, {
+                title: '\u5199\u4F5C\u6A21\u5F0F',
+                question: '\u8BF7\u9009\u62E9\u5199\u4F5C\u6A21\u5F0F',
+                options: BASE_OPTIONS.map(option => ({
+                    ...option,
+                    promptLabel: BASE_PROMPT_LABELS[option.value] || option.label,
+                })),
+                defaultValue: enumOption(args, 'base', BASE_OPTIONS, defaults.base),
+            });
+        }
+
+        nextArgs.themeStyle = await promptChoice(promptContext, {
+            title: '\u98CE\u683C\u8BBE\u7F6E',
+            question: '\u8BF7\u9009\u62E9\u98CE\u683C\u7F16\u53F7',
+            options: THEME_STYLE_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: THEME_STYLE_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'themeStyle', THEME_STYLE_OPTIONS, defaults.themeStyle),
+        });
+        nextArgs.tableQuantity = await promptChoice(promptContext, {
+            title: '\u8868\u683C\u6570\u91CF',
+            question: '\u8BF7\u9009\u62E9\u8868\u683C\u6570\u91CF',
+            options: TABLE_QUANTITY_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: TABLE_QUANTITY_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'tableQuantity', TABLE_QUANTITY_OPTIONS, defaults.tableQuantity),
+        });
+        nextArgs.tableColor = await promptChoice(promptContext, {
+            title: '\u8868\u683C\u4E3B\u9898\u8272',
+            question: '\u8BF7\u9009\u62E9\u8868\u683C\u989C\u8272',
+            options: TABLE_COLOR_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: TABLE_COLOR_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'tableColor', TABLE_COLOR_OPTIONS, defaults.tableColor),
+        });
+        nextArgs.tableStyle = await promptChoice(promptContext, {
+            title: '\u8868\u683C\u6837\u5F0F',
+            question: '\u8BF7\u9009\u62E9\u8868\u683C\u6837\u5F0F',
+            options: TABLE_STYLE_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: TABLE_STYLE_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'tableStyle', TABLE_STYLE_OPTIONS, defaults.tableStyle),
+        });
+        nextArgs.planMode = await promptChoice(promptContext, {
+            title: '\u751F\u6210\u6A21\u5F0F',
+            question: '\u8BF7\u9009\u62E9\u751F\u6210\u6A21\u5F0F',
+            options: PLAN_MODE_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: PLAN_MODE_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'planMode', PLAN_MODE_OPTIONS, defaults.planMode),
+        });
+
+        const customizeImages = await promptYesNo(
+            promptContext,
+            '\u662F\u5426\u8981\u81EA\u5B9A\u4E49\u56FE\u7247/\u6D41\u7A0B\u56FE\u5F00\u5173',
+            hasAnyOption(args, IMAGE_TOGGLE_PROMPT_OPTIONS.map(option => option.key)) || hasSnapshotImageOverrides(defaults),
+        );
+        if (customizeImages) {
+            for (const option of IMAGE_TOGGLE_PROMPT_OPTIONS) {
+                const currentValue = binaryOption(args, option.key, defaults[option.key] ?? option.defaultValue);
+                nextArgs[option.key] = await promptBinaryChoice(promptContext, option.label, currentValue);
+            }
+            if (Number(nextArgs.mermaidImg) === 1) {
+                nextArgs.mermaidStyle = await promptChoice(promptContext, {
+                    title: '\u6D41\u7A0B\u56FE\u989C\u8272',
+                    question: '\u8BF7\u9009\u62E9\u6D41\u7A0B\u56FE\u98CE\u683C',
+                    options: MERMAID_STYLE_OPTIONS.map(option => ({
+                        ...option,
+                        promptLabel: MERMAID_STYLE_PROMPT_LABELS[option.value] || option.label,
+                    })),
+                    defaultValue: enumOption(args, 'mermaidStyle', MERMAID_STYLE_OPTIONS, defaults.mermaidStyle),
+                });
+            }
+        }
+
+        const customizeBidInfo = await promptYesNo(
+            promptContext,
+            '\u662F\u5426\u8981\u8986\u76D6\u591A\u6807\u6BB5 / EPC \u53C2\u6570',
+            hasAnyOption(args, ['multiBidId', 'multiBidType', 'epcEngineerType']) || Boolean(defaults.multiBidId || defaults.multiBidType || defaults.epcEngineerType),
+        );
+        if (customizeBidInfo) {
+            nextArgs.multiBidId = await promptText(promptContext, {
+                title: '\u591A\u6807\u6BB5 ID',
+                question: '\u8BF7\u8F93\u5165 multiBidId (\u53EF\u7559\u7A7A)',
+                defaultValue: stringOption(args, 'multiBidId', defaults.multiBidId || ''),
+                required: false,
+            });
+            nextArgs.multiBidType = await promptText(promptContext, {
+                title: '\u591A\u6807\u6BB5\u7C7B\u578B',
+                question: '\u8BF7\u8F93\u5165 multiBidType (\u53EF\u7559\u7A7A)',
+                defaultValue: stringOption(args, 'multiBidType', defaults.multiBidType || ''),
+                required: false,
+            });
+            nextArgs.epcEngineerType = await promptChoice(promptContext, {
+                title: 'EPC \u7C7B\u578B',
+                question: '\u8BF7\u9009\u62E9 EPC \u53C2\u6570',
+                options: EPC_ENGINEER_PROMPT_OPTIONS,
+                defaultValue: normalizeEpcEngineerType(stringOption(args, 'epcEngineerType', defaults.epcEngineerType || '')),
+                allowCustomValue: true,
+            });
+        }
+
+        nextArgs.interactive = false;
+        return nextArgs;
+    };
+    return context ? promptFn(context) : runPromptSession(args, promptFn);
+}
+
+async function collectExportInteractiveArgs(args, snapshot, context = null, options = {}) {
+    const promptFn = async promptContext => {
+        const nextArgs = { ...args };
+        const defaults = buildInteractiveSnapshotDefaults(snapshot);
+        if (options.header) {
+            promptContext.promptStream.write(`${options.header}\n`);
+        }
+
+        nextArgs.template = await promptChoice(promptContext, {
+            title: '\u5BFC\u51FA\u6A21\u677F',
+            question: '\u8BF7\u9009\u62E9\u5BFC\u51FA\u6A21\u677F',
+            options: EXPORT_TEMPLATE_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: `\u6A21\u677F${option.value}`,
+            })),
+            defaultValue: numberOption(args, 'template', DEFAULT_EXPORT_TEMPLATE_INDEX),
+        });
+        nextArgs.layout = await promptChoice(promptContext, {
+            title: '\u4E0B\u8F7D\u6392\u7248',
+            question: '\u8BF7\u9009\u62E9\u6392\u7248\u65B9\u5F0F',
+            options: LAYOUT_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: LAYOUT_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'layout', LAYOUT_OPTIONS, resolveExportLayout(defaults, args)),
+        });
+        nextArgs.tableColor = await promptChoice(promptContext, {
+            title: '\u5BFC\u51FA\u8868\u683C\u989C\u8272',
+            question: '\u8BF7\u9009\u62E9\u8868\u683C\u989C\u8272',
+            options: TABLE_COLOR_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: TABLE_COLOR_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'tableColor', TABLE_COLOR_OPTIONS, defaults.tableColor),
+        });
+        nextArgs.tableStyle = await promptChoice(promptContext, {
+            title: '\u5BFC\u51FA\u8868\u683C\u6837\u5F0F',
+            question: '\u8BF7\u9009\u62E9\u8868\u683C\u6837\u5F0F',
+            options: TABLE_STYLE_OPTIONS.map(option => ({
+                ...option,
+                promptLabel: TABLE_STYLE_PROMPT_LABELS[option.value] || option.label,
+            })),
+            defaultValue: enumOption(args, 'tableStyle', TABLE_STYLE_OPTIONS, defaults.tableStyle),
+        });
+        nextArgs.autoNumber = await promptBinaryChoice(
+            promptContext,
+            'Word \u81EA\u52A8\u7F16\u53F7',
+            binaryOption(args, 'autoNumber', DEFAULT_AUTO_NUMBER),
+        );
+        nextArgs.addMark = await promptBinaryChoice(
+            promptContext,
+            '\u5EFA\u8BAE\u4FEE\u6539\u6807\u8BB0',
+            binaryOption(args, 'addMark', DEFAULT_ADD_MARK),
+        );
+
+        const customizeMargins = await promptYesNo(
+            promptContext,
+            '\u662F\u5426\u8981\u81EA\u5B9A\u4E49\u9875\u8FB9\u8DDD',
+            hasAnyOption(args, PAGE_MARGIN_FIELDS.flatMap(field => field.optionKeys)),
+        );
+        if (customizeMargins) {
+            for (const field of PAGE_MARGIN_FIELDS) {
+                nextArgs[field.optionKeys[0]] = await promptNumber(promptContext, {
+                    title: `\u9875\u8FB9\u8DDD: ${field.key}`,
+                    question: `\u8BF7\u8F93\u5165 ${field.key} (\u5355\u4F4D cm)`,
+                    defaultValue: numberOptionAny(args, field.optionKeys, defaults.pageMarginSetting?.[field.key] ?? DEFAULT_PAGE_MARGIN_SETTING[field.key]),
+                    min: 0,
+                });
+            }
+        }
+
+        const useStyleJson = await promptYesNo(
+            promptContext,
+            '\u662F\u5426\u8981\u6302\u8F7D\u9AD8\u7EA7\u6837\u5F0F JSON',
+            Boolean(stringOption(args, 'styleJson')),
+        );
+        if (useStyleJson) {
+            nextArgs.styleJson = await promptText(promptContext, {
+                title: '\u9AD8\u7EA7\u6837\u5F0F JSON',
+                question: '\u8BF7\u8F93\u5165 style JSON \u8DEF\u5F84',
+                defaultValue: stringOption(args, 'styleJson', ''),
+                required: true,
+                transform: value => path.resolve(value),
+                validate: value => fs.existsSync(value) ? null : `\u6587\u4EF6\u4E0D\u5B58\u5728: ${value}`,
+            });
+        }
+
+        nextArgs.out = await promptText(promptContext, {
+            title: '\u5BFC\u51FA\u8DEF\u5F84',
+            question: '\u8BF7\u8F93\u5165\u5BFC\u51FA\u76EE\u5F55\u6216\u6587\u4EF6\u8DEF\u5F84',
+            defaultValue: stringOption(args, 'out', buildWizardDefaultOutputPath()),
+            required: true,
+            transform: value => path.resolve(value),
+        });
+
+        nextArgs.interactive = false;
+        return nextArgs;
+    };
+    return context ? promptFn(context) : runPromptSession(args, promptFn);
+}
+
+function buildInteractiveSnapshotDefaults(source = {}) {
+    return {
+        pageScopeCode: source.pageScopeCode ?? DEFAULT_PAGE_SCOPE_CODE,
+        base: source.base ?? DEFAULT_BASE,
+        themeStyle: source.themeStyle ?? DEFAULT_THEME_STYLE,
+        tableQuantity: source.tableQuantity ?? DEFAULT_TABLE_QUANTITY,
+        tableColor: source.tableColor ?? DEFAULT_TABLE_COLOR,
+        tableStyle: source.tableStyle ?? DEFAULT_TABLE_STYLE,
+        infoImg: source.infoImg ?? DEFAULT_INFO_IMG,
+        sceneImg: source.sceneImg ?? DEFAULT_SCENE_IMG,
+        onlineImg: source.onlineImg ?? DEFAULT_ONLINE_IMG,
+        mermaidImg: source.mermaidImg ?? DEFAULT_MERMAID_IMG,
+        knowledgeImg: source.knowledgeImg ?? DEFAULT_KNOWLEDGE_IMG,
+        mermaidStyle: source.mermaidStyle ?? DEFAULT_MERMAID_STYLE,
+        planMode: source.planMode ?? DEFAULT_PLAN_MODE,
+        multiBidId: source.multiBidId ?? '',
+        multiBidType: source.multiBidType ?? '',
+        epcEngineerType: source.epcEngineerType ?? '',
+        pageMarginSetting: source.pageMarginSetting ?? DEFAULT_PAGE_MARGIN_SETTING,
+        themeStyleSetting: source.themeStyleSetting ?? DEFAULT_THEME_STYLE_SETTING,
+    };
+}
+
+function hasSnapshotImageOverrides(snapshot) {
+    return IMAGE_TOGGLE_PROMPT_OPTIONS.some(option => Number(snapshot?.[option.key] ?? option.defaultValue) !== Number(option.defaultValue))
+        || Number(snapshot?.mermaidStyle ?? DEFAULT_MERMAID_STYLE) !== DEFAULT_MERMAID_STYLE;
+}
+
+function buildWizardDefaultOutputPath() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '-').slice(0, 19);
+    return path.join(process.cwd(), 'output', 'doc', `wizard-${stamp}`);
+}
+
+function buildWizardSummary(args) {
+    const file = resolveFileArgs(args)[0];
+    return [
+        file ? `file=${path.basename(file)}` : null,
+        `outline=${buildOutlineConfigSummary(buildOutlineParams({
+            ...buildInteractiveSnapshotDefaults(args),
+            cid: 'wizard-preview',
+            uuid: 'wizard-preview',
+            title: 'wizard-preview',
+            projectName: 'wizard-preview',
+        }, args))}`,
+        `export=template${numberOption(args, 'template', DEFAULT_EXPORT_TEMPLATE_INDEX)}, out=${stringOption(args, 'out', '-')}`,
+    ].filter(Boolean).join(', ');
+}
+
+function buildOutlineReferenceChoices(referenceData = {}) {
+    return OUTLINE_REFERENCE_OPTIONS.map(option => {
+        const nodes = ensureArray(referenceData[option.outlineKey]);
+        return {
+            value: option.value,
+            label: option.label,
+            shortLabel: option.shortLabel,
+            recommended: option.recommended,
+            rootChapters: nodes.length,
+            preview: summarizeOutlinePreview(nodes),
+        };
+    });
+}
+
+function summarizeOutlinePreview(nodes) {
+    const titles = ensureArray(nodes)
+        .map(node => node?.text || node?.title || '')
+        .filter(Boolean)
+        .slice(0, 3);
+    return titles.join(' / ');
+}
+
+async function resolveOutlineReferenceSelection(args, referenceData) {
+    const explicitRaw = stringOption(args, 'referenceType');
+    if (explicitRaw !== undefined) {
+        const explicit = parseOutlineReferenceType(explicitRaw);
+        return {
+            ready: true,
+            referenceType: explicit,
+            source: 'arg',
+        };
+    }
+
+    if (!canPromptForInput()) {
+        return {
+            ready: false,
+            referenceType: null,
+            source: 'unavailable',
+        };
+    }
+
+    const choices = buildOutlineReferenceChoices(referenceData);
+    const promptStream = booleanOption(args, 'json') ? process.stderr : process.stdout;
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: promptStream,
+    });
+
+    try {
+        promptStream.write('检测到需要确认“响应依据”后才能继续生成大纲。\n');
+        for (const choice of choices) {
+            const suffix = choice.recommended ? ' (推荐)' : '';
+            const preview = choice.preview ? `；预览：${choice.preview}` : '';
+            promptStream.write(`  ${choice.value}) ${choice.label}${suffix}；一级章节数=${choice.rootChapters}${preview}\n`);
+        }
+        promptStream.write('请输入你要采用的响应依据编号，CLI 会在你明确选择后继续。\n');
+        while (true) {
+            const answer = await rl.question('请选择响应依据 [0/1/2，输入 q 取消本次等待]: ');
+            const normalized = answer.trim().toLowerCase();
+            if (!normalized) {
+                promptStream.write('尚未选择响应依据，请输入 0、1 或 2。\n');
+                continue;
+            }
+            if (normalized === 'q' || normalized === 'quit' || normalized === 'exit') {
+                return {
+                    ready: false,
+                    referenceType: null,
+                    source: 'prompt_cancelled',
+                };
+            }
+            const parsed = parseOutlineReferenceType(normalized);
+            if (parsed !== null) {
+                return {
+                    ready: true,
+                    referenceType: parsed,
+                    source: 'prompt',
+                };
+            }
+            promptStream.write('输入无效，请输入 0、1、2，或输入 q 取消。\n');
+        }
+    } finally {
+        rl.close();
+    }
+}
+
+function canPromptForInput() {
+    return Boolean(process.stdin.isTTY && (process.stdout.isTTY || process.stderr.isTTY));
+}
+
+function ensurePromptAvailable() {
+    if (!canPromptForInput()) {
+        throw new Error('Interactive prompts require a TTY terminal. Please rerun this command in an interactive terminal.');
+    }
+}
+
+async function runPromptSession(args, handler) {
+    ensurePromptAvailable();
+    const promptStream = booleanOption(args, 'json') ? process.stderr : process.stdout;
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: promptStream,
+    });
+    try {
+        return await handler({ rl, promptStream, args });
+    } finally {
+        rl.close();
+    }
+}
+
+async function promptChoice(context, config) {
+    const options = config.options || [];
+    if (options.length === 0) {
+        throw new Error(`Prompt "${config.title || config.question}" has no options.`);
+    }
+    const defaultIndex = findPromptDefaultIndex(options, config.defaultValue);
+    context.promptStream.write(`\n${config.title}\n`);
+    options.forEach((option, index) => {
+        const label = option.promptLabel || option.label || String(option.value);
+        const desc = option.description ? ` - ${option.description}` : '';
+        const suffix = defaultIndex === index ? ' [default]' : '';
+        context.promptStream.write(`  ${index + 1}) ${label}${desc}${suffix}\n`);
+    });
+    if (config.allowCustomValue) {
+        context.promptStream.write('  You can also type a raw value directly.\n');
+    }
+    while (true) {
+        const defaultHint = defaultIndex >= 0 ? ` [default ${defaultIndex + 1}]` : '';
+        const answer = await context.rl.question(`${config.question}${defaultHint}: `);
+        const normalized = answer.trim();
+        if (!normalized) {
+            if (defaultIndex >= 0) {
+                return options[defaultIndex].value;
+            }
+            context.promptStream.write('Input required. Please choose one option.\n');
+            continue;
+        }
+        if (isPromptCancelAnswer(normalized)) {
+            throw new Error('Interactive prompt cancelled.');
+        }
+        const optionByIndex = tryPickPromptOptionByIndex(options, normalized);
+        if (optionByIndex) {
+            return optionByIndex.value;
+        }
+        const optionByAlias = tryPickPromptOptionByAlias(options, normalized);
+        if (optionByAlias) {
+            return optionByAlias.value;
+        }
+        if (config.allowCustomValue) {
+            return normalized;
+        }
+        context.promptStream.write('Invalid choice. Please enter the option number shown above.\n');
+    }
+}
+
+async function promptYesNo(context, question, defaultValue) {
+    const defaultHint = defaultValue ? ' [Y/n]' : ' [y/N]';
+    while (true) {
+        const answer = await context.rl.question(`${question}${defaultHint}: `);
+        const normalized = answer.trim().toLowerCase();
+        if (!normalized) {
+            return defaultValue;
+        }
+        if (isPromptCancelAnswer(normalized)) {
+            throw new Error('Interactive prompt cancelled.');
+        }
+        if (['y', 'yes', '1', 'true'].includes(normalized)) {
+            return true;
+        }
+        if (['n', 'no', '0', 'false'].includes(normalized)) {
+            return false;
+        }
+        context.promptStream.write('Please answer y or n.\n');
+    }
+}
+
+async function promptBinaryChoice(context, label, defaultValue) {
+    const enabled = await promptYesNo(context, `${label}: enable?`, Number(defaultValue) === 1);
+    return enabled ? 1 : 0;
+}
+
+async function promptText(context, config) {
+    if (config.title) {
+        context.promptStream.write(`\n${config.title}\n`);
+    }
+    while (true) {
+        const defaultHint = config.defaultValue ? ` [default: ${config.defaultValue}]` : '';
+        const answer = await context.rl.question(`${config.question}${defaultHint}: `);
+        const normalized = answer.trim();
+        if (!normalized) {
+            if (config.defaultValue !== undefined) {
+                return config.defaultValue;
+            }
+            if (!config.required) {
+                return '';
+            }
+            context.promptStream.write('Input required.\n');
+            continue;
+        }
+        if (isPromptCancelAnswer(normalized)) {
+            throw new Error('Interactive prompt cancelled.');
+        }
+        const transformed = config.transform ? config.transform(normalized) : normalized;
+        const validationMessage = config.validate ? config.validate(transformed) : null;
+        if (validationMessage) {
+            context.promptStream.write(`${validationMessage}\n`);
+            continue;
+        }
+        return transformed;
+    }
+}
+
+async function promptNumber(context, config) {
+    const value = await promptText(context, {
+        ...config,
+        defaultValue: config.defaultValue !== undefined ? String(config.defaultValue) : undefined,
+        validate: rawValue => {
+            const parsed = Number(rawValue);
+            if (!Number.isFinite(parsed)) {
+                return 'Please enter a valid number.';
+            }
+            if (config.min !== undefined && parsed < config.min) {
+                return `Number must be greater than or equal to ${config.min}.`;
+            }
+            if (config.max !== undefined && parsed > config.max) {
+                return `Number must be less than or equal to ${config.max}.`;
+            }
+            return config.validate ? config.validate(parsed) : null;
+        },
+        transform: rawValue => Number(rawValue),
+    });
+    return value;
+}
+
+function findPromptDefaultIndex(options, defaultValue) {
+    if (defaultValue === undefined || defaultValue === null || defaultValue === '') {
+        return -1;
+    }
+    return options.findIndex(option => String(option.value) === String(defaultValue));
+}
+
+function tryPickPromptOptionByIndex(options, answer) {
+    const parsed = Number(answer);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > options.length) {
+        return null;
+    }
+    return options[parsed - 1];
+}
+
+function tryPickPromptOptionByAlias(options, answer) {
+    const normalized = String(answer).trim().toLowerCase();
+    return options.find(option => {
+        const aliases = [option.value, option.label, ...(option.aliases || [])];
+        return aliases.some(alias => String(alias).trim().toLowerCase() === normalized);
+    }) || null;
+}
+
+function isPromptCancelAnswer(value) {
+    const normalized = String(value).trim().toLowerCase();
+    return normalized === 'q' || normalized === 'quit' || normalized === 'exit';
+}
+
+function hasAnyOption(args, keys) {
+    return ensureArray(keys).some(key => args[key] !== undefined && args[key] !== null && args[key] !== '');
+}
+
+function countOutlineRoots(result) {
+    return getOutlineRows(result?.outlineDetail).length;
+}
+
+function getOutlineRows(outlineDetail) {
+    return Array.isArray(outlineDetail?.outLine) ? outlineDetail.outLine : [];
+}
+
+function hasOutlineThemes(outlineRows) {
+    return outlineRows.length > 0 && outlineRows.every(item => String(item?.theme || '').trim().length > 0);
+}
+
+function isOutlineReadyForCli(outlineDetail) {
+    const outlineRows = getOutlineRows(outlineDetail);
+    if (outlineRows.length === 0) {
+        return false;
+    }
+    return Boolean(outlineDetail?.outline_status) || hasOutlineThemes(outlineRows);
+}
+
+function normalizeDirectoryPortionStatus(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+
+function countDirectoryRoots(contentDetail) {
+    return Array.isArray(contentDetail?.directoryNodes) ? contentDetail.directoryNodes.length : 0;
+}
+
+function isDirectoryReadyForWrite(contentDetail) {
+    return normalizeDirectoryPortionStatus(contentDetail?.directory_portion_status) === DIRECTORY_PORTION_STATUS.SEQUEL_COMPLETED
+        && countDirectoryRoots(contentDetail) > 0;
+}
+
+function numberOrDefault(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function hasUnfinishedChapters(contentDetail) {
+    const totalChapter = numberOrDefault(contentDetail?.totalChapter, 0);
+    if (totalChapter <= 0) {
+        return false;
+    }
+    const completedChapter = numberOrDefault(contentDetail?.completedChapter, 0);
+    return completedChapter < totalChapter;
+}
+
+function isContentComplete(contentDetail) {
+    const totalChapter = numberOrDefault(contentDetail?.totalChapter, 0);
+    if (totalChapter > 0) {
+        return !hasUnfinishedChapters(contentDetail);
+    }
+    const taskStatus = numberOrDefault(contentDetail?.task_status, -1);
+    const contentPortionStatus = numberOrDefault(contentDetail?.content_portion_status, -1);
+    return taskStatus === 5 || (taskStatus === 4 && contentPortionStatus === 1);
+}
+
+function shouldTriggerGenerateAllUnfinished(contentDetail) {
+    if (!hasUnfinishedChapters(contentDetail)) {
+        return false;
+    }
+    const percentage = numberOrDefault(contentDetail?.percentage, 0);
+    const taskStatus = numberOrDefault(contentDetail?.task_status, -1);
+    return percentage >= 100 || taskStatus === 4 || taskStatus === 5;
+}
+
+function resolveAutoIgnoreIssue(issues, args, uuid, handledIssues) {
+    for (const issue of issues) {
+        const config = AUTO_IGNORE_ISSUE_CONFIG[issue];
+        if (!config || handledIssues.has(issue)) {
+            continue;
+        }
+        if (!booleanOption(args, config.optionKey)) {
+            continue;
+        }
+        return {
+            issue,
+            payload: config.buildPayload(uuid),
+        };
+    }
+    return null;
+}
+
+function collectIssueHints(issues, args) {
+    const hints = [];
+    for (const issue of issues) {
+        const config = AUTO_IGNORE_ISSUE_CONFIG[issue];
+        if (!config || booleanOption(args, config.optionKey)) {
+            continue;
+        }
+        hints.push(`hint: rerun with ${config.hint} to follow the frontend ignore/continue path for ${issue}.`);
+    }
+    return hints;
+}
+
+function saveLoginState(state, options) {
+    const username = options.result.data?.user?.username || options.name || '';
+    state.baseUrl = options.baseUrl;
+    state.token = options.result.data.token;
+    state.user = {
+        name: options.name || username,
+        username,
+        userId: options.result.data?.user?.userId || '',
+        sourceFrom: options.sourceFrom,
+        loggedInAt: new Date().toISOString(),
+    };
+    writeState(state);
+}
+
+function buildBrowserAuthorizeUrl(baseUrl, redirectUri, state, sourceFrom) {
+    const query = new URLSearchParams({
+        redirect_uri: redirectUri,
+        state,
+        sourceFrom,
+    });
+    return `${baseUrl}/user/cli/authorize?${query.toString()}`;
+}
+
+async function startBrowserLoginServer() {
+    let settled = false;
+    let resolveResult;
+    let rejectResult;
+    const result = new Promise((resolve, reject) => {
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    const server = http.createServer((request, response) => {
+        const origin = server.address();
+        const requestUrl = new URL(request.url || '/', `http://127.0.0.1:${origin?.port || 0}`);
+        const pathname = requestUrl.pathname;
+
+        if (pathname === '/favicon.ico') {
+            response.writeHead(204);
+            response.end();
+            return;
+        }
+        if (pathname !== BROWSER_LOGIN_CALLBACK_PATH) {
+            response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            response.end('Not found');
+            return;
+        }
+
+        const code = requestUrl.searchParams.get('code');
+        const state = requestUrl.searchParams.get('state');
+        if (!code || !state) {
+            response.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+            response.end(renderBrowserLoginResultPage('登录未完成', '缺少 code 或 state，返回 CLI 重新执行登录即可。'));
+            if (!settled) {
+                settled = true;
+                rejectResult(new Error('Browser login callback missing code or state.'));
+            }
+            return;
+        }
+
+        response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        response.end(renderBrowserLoginResultPage('登录成功', '授权已完成，现在可以回到 CLI 继续使用了。'));
+        if (!settled) {
+            settled = true;
+            resolveResult({ code, state });
+        }
+    });
+    server.on('error', error => {
+        if (!settled) {
+            settled = true;
+            rejectResult(error);
+        }
+    });
+
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+
+    const address = server.address();
+    const redirectUri = `http://127.0.0.1:${address.port}${BROWSER_LOGIN_CALLBACK_PATH}`;
+    return {
+        redirectUri,
+        result,
+        close: () => closeServer(server),
+    };
+}
+
+function renderBrowserLoginResultPage(title, message) {
+    return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escapeHtml(title)}</title>
+  <style>
+    body{font-family:Segoe UI,Microsoft YaHei,sans-serif;background:#f5f7fb;margin:0;padding:40px;color:#1f2937;}
+    .card{max-width:420px;margin:0 auto;background:#fff;border-radius:16px;padding:28px;box-shadow:0 16px 48px rgba(15,23,42,.12);}
+    h1{margin:0 0 12px;font-size:24px;}
+    p{margin:0;color:#64748b;line-height:1.7;}
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>${escapeHtml(title)}</h1>
+    <p>${escapeHtml(message)}</p>
+  </div>
+</body>
+</html>`;
+}
+
+function escapeHtml(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+function openBrowser(url) {
+    try {
+        if (process.platform === 'win32') {
+            const child = spawn('rundll32', ['url.dll,FileProtocolHandler', url], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.once('error', () => {});
+            child.unref();
+            return true;
+        }
+        if (process.platform === 'darwin') {
+            const child = spawn('open', [url], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.once('error', () => {});
+            child.unref();
+            return true;
+        }
+        const child = spawn('xdg-open', [url], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.once('error', () => {});
+        child.unref();
+        return true;
+    } catch (error) {
+        return false;
+    }
+}
+
+async function closeServer(server) {
+    if (!server.listening) {
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        server.close(error => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+
+async function withTimeout(promise, timeoutMs, message) {
+    let timer = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(message));
+                }, timeoutMs);
+            }),
+        ]);
+    } finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+
+function createAuthorizedClient(args, state) {
+    const baseUrl = normalizeBaseUrl(stringOption(args, 'baseUrl', state.baseUrl));
+    if (!baseUrl) {
+        throw new Error('Missing base URL. Run login first or pass --base-url.');
+    }
+    if (!state.token) {
+        throw new Error('Missing local token. Run login first.');
+    }
+    return createClient(baseUrl, state.token);
+}
+
+function createClient(baseUrl, token = '') {
+    return axios.create({
+        baseURL: baseUrl,
+        timeout: 1_200_000,
+        maxBodyLength: Infinity,
+        maxContentLength: Infinity,
+        httpAgent: HTTP_AGENT,
+        httpsAgent: HTTPS_AGENT,
+        headers: token
+            ? {
+                  Authorization: token,
+              }
+            : {},
+        validateStatus: () => true,
+    });
+}
+
+async function getJson(client, url, params = {}, options = {}) {
+    const response = await requestWithRetry(async () => {
+        return client.get(url, { params });
+    }, options);
+    return unwrapApiResponse(response);
+}
+
+async function postJson(client, url, data = {}) {
+    const response = await client.post(url, data);
+    return unwrapApiResponse(response);
+}
+
+async function postForm(client, url, formData) {
+    const response = await client.post(url, formData, {
+        headers: formData.getHeaders(),
+    });
+    return unwrapApiResponse(response);
+}
+
+async function postBinary(client, url, data = {}) {
+    const response = await client.post(url, data, {
+        responseType: 'arraybuffer',
+    });
+    const contentType = `${response.headers['content-type'] || ''}`.toLowerCase();
+    if (contentType.includes('application/json')) {
+        const json = JSON.parse(Buffer.from(response.data).toString('utf8'));
+        throw new Error(json.message || 'Binary download failed.');
+    }
+    if (response.status >= 400) {
+        throw new Error(`Download request failed with status ${response.status}.`);
+    }
+    return response;
+}
+
+async function requestWithRetry(requestFn, options = {}) {
+    const retries = Number.isFinite(options.retries) ? options.retries : 0;
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        try {
+            return await requestFn();
+        } catch (error) {
+            lastError = error;
+            if (!isRetryableNetworkError(error) || attempt === retries) {
+                throw error;
+            }
+            await sleep((attempt + 1) * 1_000);
+        }
+    }
+
+    throw lastError;
+}
+
+function isRetryableNetworkError(error) {
+    const code = String(error?.code || '').toUpperCase();
+    const message = String(error?.message || '');
+    if (RETRYABLE_NETWORK_CODES.has(code)) {
+        return true;
+    }
+    return /socket disconnected|econnreset|tls connection|network error|timeout/i.test(message);
+}
+
+function unwrapApiResponse(response) {
+    const payload = response.data || {};
+    if (response.status >= 400) {
+        throw createApiError(payload.message || `Request failed with status ${response.status}.`, {
+            code: payload.code,
+            payload,
+            response,
+        });
+    }
+    if (payload.code !== 200) {
+        throw createApiError(payload.message || `Request failed with business code ${payload.code}.`, {
+            code: payload.code,
+            payload,
+            response,
+        });
+    }
+    return payload;
+}
+
+function createApiError(message, options = {}) {
+    const error = new Error(message);
+    error.code = options.code;
+    error.payload = options.payload;
+    error.status = options.response?.status;
+    return error;
+}
+
+function resolveCid(args, state) {
+    const cid = stringOption(args, 'cid', state.lastCid);
+    if (!cid) {
+        throw new Error('Missing cid. Pass --cid <cid> or run init first.');
+    }
+    return cid;
+}
+
+function resolveFileArgs(args) {
+    const optionFiles = ensureArray(args.file);
+    if (optionFiles.length > 0) {
+        return optionFiles.map(item => path.resolve(item));
+    }
+    return args._.slice(1).map(item => path.resolve(item));
+}
+
+function resolveExportLayout(snapshot, args) {
+    const explicit = enumOption(args, 'layout', LAYOUT_OPTIONS);
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    switch (Number(snapshot.themeStyle)) {
+        case 1:
+            return 2;
+        case 2:
+            return 1;
+        default:
+            return 0;
+    }
+}
+
+function parseArgs(argv) {
+    const result = { _: [] };
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith('--')) {
+            result._.push(token);
+            continue;
+        }
+
+        const [rawKey, inlineValue] = token.slice(2).split('=');
+        const key = normalizeOptionKey(rawKey);
+        if (inlineValue !== undefined) {
+            pushOption(result, key, inlineValue);
+            continue;
+        }
+
+        const next = argv[index + 1];
+        if (!next || next.startsWith('--')) {
+            pushOption(result, key, true);
+            continue;
+        }
+
+        pushOption(result, key, next);
+        index += 1;
+    }
+    return result;
+}
+
+function normalizeOptionKey(value) {
+    return value.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+
+function pushOption(target, key, value) {
+    if (target[key] === undefined) {
+        target[key] = value;
+        return;
+    }
+    if (Array.isArray(target[key])) {
+        target[key].push(value);
+        return;
+    }
+    target[key] = [target[key], value];
+}
+
+function ensureArray(value) {
+    if (value === undefined || value === null || value === '') {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}
+
+function firstOptionKey(keys) {
+    return Array.isArray(keys) ? keys[0] : keys;
+}
+
+function optionValue(args, keys, fallback = undefined) {
+    for (const key of ensureArray(keys)) {
+        const value = args[key];
+        if (value === undefined || value === null || value === '') {
+            continue;
+        }
+        return Array.isArray(value) ? value[0] : value;
+    }
+    return fallback;
+}
+
+function requiredOption(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null || value === '') {
+        throw new Error(`Missing required option: --${toKebabCase(key)}`);
+    }
+    return Array.isArray(value) ? value[0] : value;
+}
+
+function stringOption(args, key, fallback = undefined) {
+    const value = args[key];
+    if (value === undefined || value === null || value === '') {
+        return fallback;
+    }
+    return Array.isArray(value) ? value[0] : value;
+}
+
+function stringOptionAny(args, keys, fallback = undefined) {
+    const value = optionValue(args, keys, fallback);
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    return String(value);
+}
+
+function numberOption(args, key, fallback = undefined) {
+    const value = stringOption(args, key, fallback);
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Option --${toKebabCase(key)} expects a number.`);
+    }
+    return parsed;
+}
+
+function numberOptionAny(args, keys, fallback = undefined) {
+    const value = optionValue(args, keys, fallback);
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Option --${toKebabCase(firstOptionKey(keys))} expects a number.`);
+    }
+    return parsed;
+}
+
+function booleanOption(args, key, fallback = false) {
+    const value = args[key];
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const normalized = String(Array.isArray(value) ? value[0] : value).toLowerCase();
+    if (['false', '0', 'no'].includes(normalized)) {
+        return false;
+    }
+    return true;
+}
+
+function enumOption(args, keys, options, fallback = undefined) {
+    const value = optionValue(args, keys, fallback);
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const normalized = String(value).trim().toLowerCase();
+    const match = options.find(option => {
+        const aliases = [option.value, ...(option.aliases || [])];
+        return aliases.some(alias => String(alias).trim().toLowerCase() === normalized);
+    });
+    if (!match) {
+        throw new Error(`Option --${toKebabCase(firstOptionKey(keys))} expects one of: ${options.map(option => option.value).join(', ')}.`);
+    }
+    return match.value;
+}
+
+function binaryOption(args, keys, fallback = undefined) {
+    return enumOption(args, keys, BINARY_OPTIONS, fallback);
+}
+
+function colorOption(args, keys, fallback = undefined) {
+    const value = stringOptionAny(args, keys, fallback);
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = normalizeHexColor(value);
+    if (!normalized) {
+        throw new Error(`Option --${toKebabCase(firstOptionKey(keys))} expects a 6-digit hex color like #1276C1.`);
+    }
+    return normalized;
+}
+
+function normalizeHexColor(value) {
+    const trimmed = String(value).trim();
+    if (!trimmed) {
+        return '';
+    }
+    const withHash = trimmed.startsWith('#') ? trimmed : `#${trimmed}`;
+    return /^#[0-9a-fA-F]{6}$/.test(withHash) ? withHash.toUpperCase() : '';
+}
+
+function buildThemeStyleSetting(snapshot, args) {
+    const themeStyleSetting = {
+        ...DEFAULT_THEME_STYLE_SETTING,
+        ...(snapshot.themeStyleSetting || {}),
+    };
+    for (const field of THEME_STYLE_SETTING_FIELDS) {
+        const color = colorOption(args, field.optionKeys);
+        if (color !== undefined) {
+            themeStyleSetting[field.key] = color;
+        }
+    }
+    return themeStyleSetting;
+}
+
+function buildPageMarginSetting(snapshot, args) {
+    const pageMarginSetting = {
+        ...DEFAULT_PAGE_MARGIN_SETTING,
+        ...(snapshot.pageMarginSetting || {}),
+    };
+    for (const field of PAGE_MARGIN_FIELDS) {
+        const margin = numberOptionAny(args, field.optionKeys);
+        if (margin === undefined) {
+            continue;
+        }
+        if (!Number.isFinite(margin) || margin < 0) {
+            throw new Error(`Option --${toKebabCase(field.optionKeys[0])} expects a non-negative number.`);
+        }
+        pageMarginSetting[field.key] = margin;
+    }
+    return pageMarginSetting;
+}
+
+function buildTemplatePostData(template, args) {
+    const styleJsonPath = stringOption(args, 'styleJson');
+    let styleJson = {};
+    if (styleJsonPath) {
+        const resolvedPath = path.resolve(styleJsonPath);
+        ensureFileExists(resolvedPath);
+        try {
+            styleJson = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+        } catch (error) {
+            throw new Error(`Failed to parse style JSON: ${resolvedPath}`);
+        }
+        if (!styleJson || Array.isArray(styleJson) || typeof styleJson !== 'object') {
+            throw new Error('Option --style-json expects a JSON object.');
+        }
+        if (styleJson.directorySettings !== undefined && !Array.isArray(styleJson.directorySettings)) {
+            throw new Error('Option --style-json expects directorySettings to be an array.');
+        }
+        if (styleJson.contentSettings !== undefined && (Array.isArray(styleJson.contentSettings) || typeof styleJson.contentSettings !== 'object' || styleJson.contentSettings === null)) {
+            throw new Error('Option --style-json expects contentSettings to be an object.');
+        }
+    }
+    const startIndex = numberOption(args, 'startIndex', styleJson.startIndex ?? template.postData.startIndex ?? 1);
+    if (!Number.isInteger(startIndex) || startIndex < 1) {
+        throw new Error('Option --start-index expects an integer greater than or equal to 1.');
+    }
+    return {
+        ...template.postData,
+        ...compactObject({
+            directorySettings: styleJson.directorySettings,
+            contentSettings: styleJson.contentSettings,
+        }),
+        startIndex,
+    };
+}
+
+function normalizeEpcEngineerType(value) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const normalized = String(value).trim();
+    const alias = EPC_ENGINEER_TYPE_ALIAS_MAP[normalized.toLowerCase()];
+    return alias || normalized;
+}
+
+function normalizeEpcEngineerTypeForProxy(value) {
+    if (value === '\u975EEPC2') {
+        return '\u975EEPC';
+    }
+    return value;
+}
+
+function describeEnumValue(options, value) {
+    const match = options.find(option => option.value === value);
+    return match ? `${match.value}:${match.label}` : String(value);
+}
+
+function pickOutlineConfig(params) {
+    return compactObject({
+        pageScopeCode: params.pageScopeCode,
+        base: params.base,
+        themeStyle: params.themeStyle,
+        tableQuantity: params.tableQuantity,
+        tableColor: params.tableColor,
+        tableStyle: params.tableStyle,
+        infoImg: params.infoImg,
+        sceneImg: params.sceneImg,
+        onlineImg: params.onlineImg,
+        mermaidImg: params.mermaidImg,
+        knowledgeImg: params.knowledgeImg,
+        mermaidStyle: params.mermaidStyle,
+        planMode: params.planMode,
+        multiBidId: params.multiBidId,
+        multiBidType: params.multiBidType,
+        epcEngineerType: params.epcEngineerType,
+    });
+}
+
+function buildOutlineConfigSummary(params) {
+    return [
+        `pageScope=${describeEnumValue(PAGE_SCOPE_OPTIONS, params.pageScopeCode)}`,
+        `base=${describeEnumValue(BASE_OPTIONS, params.base)}`,
+        params.themeStyle !== undefined ? `themeStyle=${describeEnumValue(THEME_STYLE_OPTIONS, params.themeStyle)}` : null,
+        params.tableQuantity !== undefined ? `tableQuantity=${describeEnumValue(TABLE_QUANTITY_OPTIONS, params.tableQuantity)}` : null,
+        params.tableColor !== undefined ? `tableColor=${describeEnumValue(TABLE_COLOR_OPTIONS, params.tableColor)}` : null,
+        params.tableStyle !== undefined ? `tableStyle=${describeEnumValue(TABLE_STYLE_OPTIONS, params.tableStyle)}` : null,
+        `planMode=${describeEnumValue(PLAN_MODE_OPTIONS, params.planMode)}`,
+    ].filter(Boolean).join(', ');
+}
+
+function pickExportConfig(requestData, templateIndex) {
+    return {
+        template: templateIndex,
+        startIndex: requestData.startIndex,
+        autoNumber: requestData.autoNumber,
+        addMark: requestData.addMark,
+        layout: requestData.layout,
+        tableColor: requestData.tableSettings.tableColor,
+        tableStyle: requestData.tableSettings.tableStyle,
+        directorySettings: requestData.directorySettings,
+        contentSettings: requestData.contentSettings,
+        pageMarginSetting: requestData.pageMarginSetting,
+        themeStyleSetting: requestData.themeStyleSetting,
+    };
+}
+
+function buildExportConfigSummary(config) {
+    const margins = config.pageMarginSetting;
+    return [
+        `template=${config.template}`,
+        `startIndex=${config.startIndex}`,
+        `layout=${describeEnumValue(LAYOUT_OPTIONS, config.layout)}`,
+        `tableColor=${describeEnumValue(TABLE_COLOR_OPTIONS, config.tableColor)}`,
+        `tableStyle=${describeEnumValue(TABLE_STYLE_OPTIONS, config.tableStyle)}`,
+        `autoNumber=${config.autoNumber}`,
+        `addMark=${config.addMark}`,
+        `margins=${margins.topMargin}/${margins.bottomMargin}/${margins.leftMargin}/${margins.rightMargin}`,
+    ].join(', ');
+}
+
+function splitCsvOption(value) {
+    if (value === undefined || value === null || value === '') {
+        return [];
+    }
+    const items = ensureArray(value)
+        .flatMap(item => String(item).split(','))
+        .map(item => item.trim())
+        .filter(Boolean);
+    return [...new Set(items)];
+}
+
+function appendOptionalField(formData, key, value) {
+    if (value === undefined || value === null || value === '') {
+        return;
+    }
+    formData.append(key, String(value));
+}
+
+function ensureFileExists(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+}
+
+function normalizeBaseUrl(value) {
+    if (!value) {
+        return '';
+    }
+    return String(value).replace(/\/+$/, '');
+}
+
+function readState() {
+    if (!fs.existsSync(CONFIG_FILE)) {
+        return {
+            baseUrl: '',
+            token: '',
+            user: {},
+            lastCid: '',
+            tasks: {},
+        };
+    }
+    try {
+        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    } catch (error) {
+        return {
+            baseUrl: '',
+            token: '',
+            user: {},
+            lastCid: '',
+            tasks: {},
+        };
+    }
+}
+
+function writeState(state) {
+    fs.mkdirSync(APP_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(state, null, 2), 'utf8');
+}
+
+function saveTaskSnapshot(state, cid, patch) {
+    const current = state.tasks?.[cid] || {};
+    state.tasks = state.tasks || {};
+    state.tasks[cid] = compactObject({
+        ...current,
+        ...patch,
+        cid,
+        updatedAt: new Date().toISOString(),
+    });
+    state.lastCid = cid;
+    writeState(state);
+    return state.tasks[cid];
+}
+
+function pickTaskSnapshot(source) {
+    return compactObject({
+        cid: source.cid,
+        uuid: source.uuid,
+        title: source.title,
+        projectName: source.projectName,
+        requirement: source.requirement,
+        rating: source.rating,
+        plan: source.plan,
+        base: source.base,
+        pageScopeCode: source.pageScopeCode,
+        task_status: source.task_status,
+        viewStep: source.viewStep,
+        percentage: source.percentage,
+        content_portion_status: source.content_portion_status,
+        directory_portion_status: source.directory_portion_status,
+        annexIds: source.annexIds,
+        knowledgeProductIds: source.knowledgeProductIds,
+        sourceFrom: source.sourceFrom,
+        localFiles: source.localFiles,
+        fileTypes: source.fileTypes,
+        filePurposes: source.filePurposes,
+        originType: source.originType,
+        infoImg: source.infoImg,
+        sceneImg: source.sceneImg,
+        onlineImg: source.onlineImg,
+        mermaidImg: source.mermaidImg,
+        knowledgeImg: source.knowledgeImg,
+        mermaidStyle: source.mermaidStyle,
+        themeStyle: source.themeStyle,
+        tableColor: source.tableColor,
+        tableStyle: source.tableStyle,
+        tableQuantity: source.tableQuantity,
+        planMode: source.planMode,
+        multiBidId: source.multiBidId,
+        multiBidType: source.multiBidType,
+        epcEngineerType: source.epcEngineerType,
+        outlineReferenceType: source.outlineReferenceType,
+        referenceStatus: source.referenceStatus,
+        themeStyleSetting: source.themeStyleSetting,
+        pageMarginSetting: source.pageMarginSetting,
+        outlineTriggeredAt: source.outlineTriggeredAt,
+        triggerMode: source.triggerMode,
+        writeTriggeredAt: source.writeTriggeredAt,
+    });
+}
+
+function parseFileName(contentDisposition) {
+    if (!contentDisposition) {
+        return '';
+    }
+    const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;]+)/i);
+    if (utf8Match) {
+        return normalizeDownloadFileName(decodeFileNameSafe(utf8Match[1]));
+    }
+    const plainMatch = contentDisposition.match(/filename="?([^";]+)"?/i);
+    if (plainMatch) {
+        return normalizeDownloadFileName(decodeFileNameSafe(plainMatch[1]));
+    }
+    return '';
+}
+
+function decodeFileNameSafe(value) {
+    try {
+        return decodeURIComponent(value);
+    } catch (error) {
+        return value;
+    }
+}
+
+function normalizeDownloadFileName(value) {
+    return String(value).replace(/[<>:"/\\|?*\u0000-\u001F]/g, '_').trim();
+}
+
+function writeDownloadFile(outputOption, fileName, fileContent) {
+    const resolvedOutput = outputOption ? path.resolve(outputOption) : process.cwd();
+    const outputIsDirectory = !path.extname(resolvedOutput);
+    const finalPath = outputIsDirectory ? path.join(resolvedOutput, fileName) : resolvedOutput;
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    fs.writeFileSync(finalPath, Buffer.from(fileContent));
+    return finalPath;
+}
+
+function compactObject(value) {
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined) {
+            continue;
+        }
+        result[key] = entry;
+    }
+    return result;
+}
+
+function sleep(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+
+function secondsToMs(value) {
+    return Number(value) * 1000;
+}
+
+function toKebabCase(value) {
+    return value.replace(/[A-Z]/g, char => `-${char.toLowerCase()}`);
+}
+
+main().catch(error => {
+    console.error(error.message || String(error));
+    process.exit(1);
+});