@xqyz/xq-cli 0.1.1 → 0.1.3

package/README.md

@@ -40,26 +40,31 @@ npm pack
 That command produces a `.tgz` tarball which can be shared and installed with:
 
 ```bash
-npm install -g .\xqyz-xq-cli-0.1.1.tgz
+npm install -g .\xqyz-xq-cli-0.1.3.tgz
 ```
 
 ## Usage
 
 ```bash
-xq-cli login --base-url https://ai.bidfile.qianlima.com/api
-xq-cli login --base-url https://ai.bidfile.qianlima.com/api --name your-account --password your-password
+xq-cli login
+xq-cli login --name your-account --password your-password
+xq-cli login --base-url https://xqai.atest.qianlima.com/api --browser
 xq-cli wizard
 xq-cli wizard --file D:\bids\tender.docx
 xq-cli init --file D:\bids\tender.docx --wait
 xq-cli outline --cid <cid> --interactive --wait
 xq-cli outline --cid <cid> --wait
+xq-cli outline view --cid <cid>
+xq-cli outline view --cid <cid> --out D:\output\outline.json
+xq-cli outline update --cid <cid> --file D:\output\outline.json --dry-run --json
+xq-cli outline update --cid <cid> --file D:\output\outline.json --yes
 xq-cli write --cid <cid> --wait
 xq-cli status --cid <cid> --content --json
 xq-cli export --cid <cid> --interactive --out D:\output
 xq-cli export --cid <cid> --out D:\output
 ```
 
-Fresh installs do not ship with a saved API address. Users must run `login` once to save the target `--base-url`.
+Fresh installs default to the production API address `https://ai.bidfile.qianlima.com/api`. Use `--base-url` only when you need to target another environment such as `https://xqai.atest.qianlima.com/api`.
 
 `login` now defaults to browser authorization. If you explicitly pass `--name` and `--password`, the CLI falls back to password login.
 
@@ -71,6 +76,43 @@ When `outline --wait` or `write --wait` hits a required response-basis step, the
 
 `order/charge -> c/viewStep(101) -> task/autoGenerateContent`
 
+## View and update an existing outline
+
+View the complete current outline without triggering outline generation:
+
+```bash
+xq-cli outline view --cid <cid>
+xq-cli outline view --cid <cid> --json
+```
+
+Export an editable JSON copy:
+
+```bash
+xq-cli outline view --cid <cid> --out D:\output\outline.json
+```
+
+Edit the `outLine` array in that file. Keep an existing chapter's `id`, change `text`, `theme`, or `important`, reorder the array to reorder chapters, add a chapter without an `id`, and remove a chapter from the array to delete it. `important` accepts `1` (key chapter) or `2` (normal chapter).
+
+Always preview the server-side diff first:
+
+```bash
+xq-cli outline update --cid <cid> --file D:\output\outline.json --dry-run
+```
+
+Apply after reviewing the preview:
+
+```bash
+xq-cli outline update --cid <cid> --file D:\output\outline.json --yes
+```
+
+Deleting existing chapters has an additional protection flag:
+
+```bash
+xq-cli outline update --cid <cid> --file D:\output\outline.json --yes --allow-delete
+```
+
+The update command automatically calculates `updateFlag` by comparing the edited file with the latest server outline. Changes to chapter titles or themes may cause the backend to regenerate affected child directories asynchronously.
+
 ## Interactive menus
 
 Use the full wizard if you want a CLI flow close to the frontend configuration panel:

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@xqyz/xq-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for xique bid-book task workflows",
   "type": "module",
   "scripts": {
-    "pack": "npm pack"
+    "pack": "npm pack",
+    "test": "node --test"
   },
   "bin": {
     "xq-cli": "./bin/xq-cli.js"

package/src/cli.mjs

@@ -12,9 +12,17 @@ import axios from 'axios';
 import FormData from 'form-data';
 import { templateData } from './templateData.mjs';
 import { AI_PURPOSE_MAP, detectFileType } from './fileTypeConfig.mjs';
+import {
+    buildEditableOutlineDocument,
+    extractOutlineRows,
+    formatOutlineDiffLines,
+    formatOutlineLines,
+    prepareOutlineUpdate,
+} from './outline-edit.mjs';
 
 const APP_DIR = path.join(os.homedir(), '.xq-opencli');
 const CONFIG_FILE = path.join(APP_DIR, 'config.json');
+const DEFAULT_BASE_URL = 'https://ai.bidfile.qianlima.com/api';
 const DEFAULT_PARSE_INTERVAL_MS = 10_000;
 const DEFAULT_TASK_INTERVAL_MS = 10_000;
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
@@ -327,7 +335,19 @@ async function main() {
             await handleParseStatus(parsed, state);
             return;
         case 'outline':
-            await handleOutline(parsed, state);
+            if (isOutlineAction(parsed, ['view', 'show'])) {
+                await handleOutlineView(parsed, state);
+            } else if (isOutlineAction(parsed, ['update', 'edit'])) {
+                await handleOutlineUpdate(parsed, state);
+            } else {
+                await handleOutline(parsed, state);
+            }
+            return;
+        case 'outline-view':
+            await handleOutlineView(parsed, state);
+            return;
+        case 'outline-update':
+            await handleOutlineUpdate(parsed, state);
             return;
         case 'write':
             await handleWrite(parsed, state);
@@ -358,6 +378,8 @@ Commands
   init          Upload files and initialize a task
   parse-status  Query or wait for parse completion
   outline       Pre-set task params and trigger outline generation
+  outline view  View the current outline without triggering generation
+  outline update Update the current outline from an edited JSON file
   write         Charge if needed, enter content phase, and trigger content generation
   status        Query task status
   choices       Print selectable outline/export config values
@@ -365,9 +387,9 @@ Commands
   export        Download the generated docx
 
 Examples
-  xq-cli login --base-url https://ai.bidfile.qianlima.com/api
-  xq-cli login --base-url https://ai.bidfile.qianlima.com/api --name your-account --password your-password
-  xq-cli login --base-url https://ai.bidfile.qianlima.com/api --browser
+  xq-cli login
+  xq-cli login --name your-account --password your-password
+  xq-cli login --base-url https://xqai.atest.qianlima.com/api --browser
   xq-cli init --file D:\\bids\\tender.docx --wait
   xq-cli parse-status --cid <cid> --uuid <uuid> --wait
   xq-cli choices
@@ -381,6 +403,10 @@ Examples
   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 outline view --cid <cid>
+  xq-cli outline view --cid <cid> --out D:\\output\\outline.json
+  xq-cli outline update --cid <cid> --file D:\\output\\outline.json --dry-run --json
+  xq-cli outline update --cid <cid> --file D:\\output\\outline.json --yes
   xq-cli write --cid <cid> --type 1 --wait
   xq-cli status --cid <cid> --content
   xq-cli export --cid <cid> --interactive --out D:\\output\\
@@ -389,12 +415,15 @@ Examples
 
 Common options
   --json             Print machine-readable JSON output
-  --base-url <url>   Override the saved base URL
+  --base-url <url>   Override the default or 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
+  --dry-run          Preview an outline update without saving it
+  --yes              Confirm an outline update without an interactive prompt
+  --allow-delete     Allow an outline update that removes existing chapters
   --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
 
@@ -442,6 +471,11 @@ Export style
 `.trim());
 }
 
+function isOutlineAction(args, actions) {
+    const action = String(args?._?.[1] || '').trim().toLowerCase();
+    return actions.includes(action);
+}
+
 async function handleLogin(args, state) {
     const baseUrl = normalizeBaseUrl(stringOption(args, 'baseUrl', state.baseUrl));
     if (!baseUrl) {
@@ -754,6 +788,158 @@ async function handleOutline(args, state) {
     return resultPayload;
 }
 
+async function handleOutlineView(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const response = await fetchOutlineDetail(client, cid);
+    const outlineDetail = response?.data || {};
+    const editableDocument = buildEditableOutlineDocument(cid, outlineDetail);
+    const savedPath = stringOption(args, 'out')
+        ? writeOutlineEditFile(stringOption(args, 'out'), cid, editableDocument)
+        : null;
+
+    const resultPayload = {
+        command: 'outline-view',
+        cid,
+        outlineDetail,
+        editableDocument: savedPath ? editableDocument : undefined,
+        savedPath,
+    };
+    outputResult(args, resultPayload, [
+        ...formatOutlineLines(cid, outlineDetail),
+        savedPath ? `savedPath: ${savedPath}` : 'hint: pass --out <file-or-directory> to save an editable JSON file.',
+    ]);
+    return resultPayload;
+}
+
+async function handleOutlineUpdate(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const filePath = path.resolve(requiredOption(args, 'file'));
+    const editDocument = readOutlineEditFile(filePath);
+    validateOutlineEditCid(editDocument, cid, filePath);
+
+    const currentResponse = await fetchOutlineDetail(client, cid);
+    const currentOutlineDetail = currentResponse?.data || {};
+    const proposedRows = extractOutlineRows(editDocument);
+    const prepared = prepareOutlineUpdate(getOutlineRows(currentOutlineDetail), proposedRows);
+    const requestData = {
+        cid,
+        outLine: prepared.payload,
+        source: 2,
+    };
+    const baseResult = {
+        command: 'outline-update',
+        cid,
+        file: filePath,
+        dryRun: booleanOption(args, 'dryRun'),
+        applied: false,
+        hasChanges: prepared.hasChanges,
+        diff: prepared.diff,
+        requestPreview: requestData,
+    };
+    const diffLines = formatOutlineDiffLines(prepared.diff);
+
+    if (!prepared.hasChanges) {
+        const resultPayload = {
+            ...baseResult,
+            reason: 'no_changes',
+        };
+        outputResult(args, resultPayload, [
+            `outline unchanged: cid=${cid}`,
+            ...diffLines,
+        ]);
+        return resultPayload;
+    }
+
+    if (booleanOption(args, 'dryRun')) {
+        const resultPayload = {
+            ...baseResult,
+            reason: 'dry_run',
+        };
+        outputResult(args, resultPayload, [
+            `outline update preview: cid=${cid}`,
+            ...diffLines,
+            'dry-run only: no server data was changed.',
+            prepared.diff.deleted.length > 0
+                ? 'delete protection: the real update also requires --allow-delete.'
+                : 'hint: rerun with --yes to apply this update.',
+        ]);
+        return resultPayload;
+    }
+
+    if (prepared.diff.deleted.length > 0 && !booleanOption(args, 'allowDelete')) {
+        throw new Error(`Outline update would delete ${prepared.diff.deleted.length} existing chapter(s). Review with --dry-run, then pass --allow-delete to confirm that deletion scope.`);
+    }
+
+    const confirmed = booleanOption(args, 'yes') || await confirmOutlineUpdate(args, cid, prepared.diff);
+    if (!confirmed) {
+        const resultPayload = {
+            ...baseResult,
+            reason: 'cancelled',
+        };
+        outputResult(args, resultPayload, [
+            `outline update cancelled: cid=${cid}`,
+            ...diffLines,
+        ]);
+        return resultPayload;
+    }
+
+    const response = await postJson(client, '/c/updateOutLine', requestData);
+    saveTaskSnapshot(state, cid, {
+        outlineUpdatedAt: new Date().toISOString(),
+    });
+    const resultPayload = {
+        ...baseResult,
+        applied: true,
+        response,
+    };
+    outputResult(args, resultPayload, [
+        `outline update accepted: cid=${cid}`,
+        ...diffLines,
+        'note: changed chapters may trigger asynchronous directory regeneration on the server.',
+        `next: xq-cli outline view --cid ${cid}`,
+    ]);
+    return resultPayload;
+}
+
+async function confirmOutlineUpdate(args, cid, diff) {
+    if (!supportsInteractivePrompt()) {
+        throw new Error('Outline update changes server data. Review it with --dry-run, then rerun with --yes.');
+    }
+    return runPromptSession(args, async context => {
+        context.promptStream.write(`\n${formatOutlineDiffLines(diff).join('\n')}\n`);
+        return promptYesNo(context, `Apply this outline update to cid=${cid}`, false);
+    });
+}
+
+function readOutlineEditFile(filePath) {
+    ensureFileExists(filePath);
+    try {
+        const raw = fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
+        return JSON.parse(raw);
+    } catch (error) {
+        throw new Error(`Failed to parse outline JSON: ${filePath}`);
+    }
+}
+
+function validateOutlineEditCid(document, cid, filePath) {
+    const documentCid = document && !Array.isArray(document) ? String(document.cid || '').trim() : '';
+    if (documentCid && documentCid !== cid) {
+        throw new Error(`Outline file cid (${documentCid}) does not match --cid (${cid}): ${filePath}`);
+    }
+}
+
+function writeOutlineEditFile(outputOption, cid, document) {
+    const resolvedOutput = path.resolve(outputOption);
+    const outputIsDirectory = !path.extname(resolvedOutput);
+    const defaultName = `outline-${normalizeDownloadFileName(cid) || 'task'}.json`;
+    const finalPath = outputIsDirectory ? path.join(resolvedOutput, defaultName) : resolvedOutput;
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    fs.writeFileSync(finalPath, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+    return finalPath;
+}
+
 async function handleWrite(args, state) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
@@ -3193,26 +3379,34 @@ function normalizeBaseUrl(value) {
     return String(value).replace(/\/+$/, '');
 }
 
+function createDefaultState() {
+    return {
+        baseUrl: DEFAULT_BASE_URL,
+        token: '',
+        user: {},
+        lastCid: '',
+        tasks: {},
+    };
+}
+
 function readState() {
+    const defaultState = createDefaultState();
     if (!fs.existsSync(CONFIG_FILE)) {
-        return {
-            baseUrl: '',
-            token: '',
-            user: {},
-            lastCid: '',
-            tasks: {},
-        };
+        return defaultState;
     }
     try {
-        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
-    } catch (error) {
+        const parsed = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
         return {
-            baseUrl: '',
-            token: '',
-            user: {},
-            lastCid: '',
-            tasks: {},
+            ...defaultState,
+            ...parsed,
+            baseUrl: normalizeBaseUrl(parsed?.baseUrl || defaultState.baseUrl),
+            token: parsed?.token || '',
+            user: parsed?.user && typeof parsed.user === 'object' ? parsed.user : {},
+            lastCid: parsed?.lastCid || '',
+            tasks: parsed?.tasks && typeof parsed.tasks === 'object' ? parsed.tasks : {},
         };
+    } catch (error) {
+        return defaultState;
     }
 }
 

package/src/outline-edit.mjs

@@ -0,0 +1,298 @@
+const CHAPTER_PREFIX_PATTERNS = [
+    /^\s*第[零〇一二三四五六七八九十百千万两\d]+章\s*/u,
+    /^\s*\d+\s*[、.．]\s*/u,
+];
+
+export function extractOutlineRows(document) {
+    const candidates = [
+        document,
+        document?.outLine,
+        document?.data?.outLine,
+        document?.outlineDetail?.outLine,
+        document?.waitResult?.outlineDetail?.outLine,
+    ];
+    const rows = candidates.find(Array.isArray);
+    if (!rows) {
+        throw new Error('Outline JSON must be an array or contain an outLine array.');
+    }
+    return rows;
+}
+
+export function buildEditableOutlineDocument(cid, outlineDetail = {}) {
+    return {
+        format: 'xq-cli-outline@1',
+        cid,
+        outlineStatus: Boolean(outlineDetail.outline_status),
+        outLine: extractOutlineRows(outlineDetail).map(row => compactObject({
+            id: normalizeOptionalString(row?.id),
+            text: normalizeText(row?.text),
+            theme: normalizeTheme(row?.theme),
+            important: normalizeImportant(row?.important, 2),
+        })),
+    };
+}
+
+export function prepareOutlineUpdate(currentRows, proposedRows) {
+    if (!Array.isArray(currentRows)) {
+        throw new Error('Current outline data is invalid: outLine must be an array.');
+    }
+    if (!Array.isArray(proposedRows) || proposedRows.length === 0) {
+        throw new Error('Updated outline must contain at least one chapter.');
+    }
+
+    const current = currentRows.map((row, index) => normalizeCurrentRow(row, index));
+    const currentById = new Map(current.filter(row => row.id).map(row => [row.id, row]));
+    const seenIds = new Set();
+
+    const proposed = proposedRows.map((row, index) => {
+        if (!row || typeof row !== 'object' || Array.isArray(row)) {
+            throw new Error(`Outline chapter ${index + 1} must be a JSON object.`);
+        }
+
+        const id = normalizeOptionalString(row.id);
+        if (id) {
+            if (seenIds.has(id)) {
+                throw new Error(`Duplicate outline chapter id: ${id}`);
+            }
+            if (!currentById.has(id)) {
+                throw new Error(`Outline chapter id does not belong to the current task: ${id}`);
+            }
+            seenIds.add(id);
+        }
+
+        const text = normalizeText(row.text);
+        if (!stripChapterPrefix(text)) {
+            throw new Error(`Outline chapter ${index + 1} has an empty text field.`);
+        }
+
+        const existing = id ? currentById.get(id) : null;
+        const important = normalizeImportant(row.important, existing?.important ?? 2, index);
+        const theme = normalizeTheme(row.theme);
+        const sequelFlag = normalizeSequelFlag(row.sequelFlag, index);
+        return {
+            id,
+            text,
+            theme,
+            important,
+            sequelFlag,
+            index,
+            existing,
+        };
+    });
+
+    const added = [];
+    const updated = [];
+    const importanceChanged = [];
+    const moved = [];
+    const sequelRequested = [];
+    const payload = proposed.map(row => {
+        const existing = row.existing;
+        const changedFields = existing
+            ? collectChangedFields(existing, row)
+            : [];
+        const contentChanged = changedFields.includes('text') || changedFields.includes('theme');
+
+        if (!existing) {
+            added.push(describeAddedRow(row));
+        } else {
+            if (contentChanged) {
+                updated.push(describeUpdatedRow(existing, row, changedFields));
+            }
+            if (existing.important !== row.important) {
+                importanceChanged.push({
+                    id: row.id,
+                    text: row.text,
+                    before: existing.important,
+                    after: row.important,
+                });
+            }
+            if (existing.index !== row.index) {
+                moved.push({
+                    id: row.id,
+                    text: row.text,
+                    from: existing.index + 1,
+                    to: row.index + 1,
+                });
+            }
+        }
+        if (row.sequelFlag === 1) {
+            sequelRequested.push({ id: row.id || null, text: row.text, index: row.index + 1 });
+        }
+
+        return compactObject({
+            id: row.id,
+            text: row.text,
+            theme: row.theme,
+            updateFlag: contentChanged ? 1 : 0,
+            important: row.important,
+            sequelFlag: row.sequelFlag === 1 ? 1 : undefined,
+        });
+    });
+
+    const proposedIds = new Set(proposed.map(row => row.id).filter(Boolean));
+    const deleted = current
+        .filter(row => row.id && !proposedIds.has(row.id))
+        .map(row => ({
+            id: row.id,
+            text: row.text,
+            index: row.index + 1,
+        }));
+
+    const diff = {
+        added,
+        updated,
+        deleted,
+        moved,
+        importanceChanged,
+        sequelRequested,
+    };
+    return {
+        payload,
+        diff,
+        hasChanges: Object.values(diff).some(items => items.length > 0),
+    };
+}
+
+export function formatOutlineLines(cid, outlineDetail = {}) {
+    const rows = Array.isArray(outlineDetail?.outLine) ? outlineDetail.outLine : [];
+    const lines = [
+        `outline: cid=${cid}`,
+        `outline_status: ${outlineDetail?.outline_status ? 'ready' : 'not-ready'}`,
+        `chapters: ${rows.length}`,
+    ];
+    rows.forEach((row, index) => {
+        const id = normalizeOptionalString(row?.id);
+        const important = normalizeImportant(row?.important, 2) === 1 ? '重点' : '普通';
+        lines.push(`${index + 1}. ${normalizeText(row?.text) || '(未命名章节)'} [${important}${id ? `, id=${id}` : ''}]`);
+        const themeLines = normalizeTheme(row?.theme)
+            .split(/\r?\n/)
+            .map(line => line.trim())
+            .filter(Boolean);
+        if (themeLines.length === 0) {
+            lines.push('   主题: -');
+        } else {
+            lines.push('   主题:');
+            themeLines.forEach(line => lines.push(`     - ${line}`));
+        }
+    });
+    return lines;
+}
+
+export function formatOutlineDiffLines(diff = {}) {
+    const added = diff.added || [];
+    const updated = diff.updated || [];
+    const deleted = diff.deleted || [];
+    const moved = diff.moved || [];
+    const importanceChanged = diff.importanceChanged || [];
+    const sequelRequested = diff.sequelRequested || [];
+    const lines = [
+        `changes: added=${added.length}, updated=${updated.length}, deleted=${deleted.length}, moved=${moved.length}, importance=${importanceChanged.length}, sequel=${sequelRequested.length}`,
+    ];
+    added.forEach(item => lines.push(`  + ${item.index}. ${item.text}`));
+    updated.forEach(item => lines.push(`  ~ ${item.index}. ${item.text} (${item.fields.join(', ')})`));
+    deleted.forEach(item => lines.push(`  - ${item.index}. ${item.text} [id=${item.id}]`));
+    moved.forEach(item => lines.push(`  ⇅ ${item.text}: ${item.from} -> ${item.to}`));
+    importanceChanged.forEach(item => lines.push(`  ! ${item.text}: important ${item.before} -> ${item.after}`));
+    sequelRequested.forEach(item => lines.push(`  > ${item.index}. ${item.text}: request sequel`));
+    return lines;
+}
+
+function normalizeCurrentRow(row, index) {
+    return {
+        id: normalizeOptionalString(row?.id),
+        text: normalizeText(row?.text),
+        theme: normalizeTheme(row?.theme),
+        important: normalizeImportant(row?.important, 2),
+        index,
+    };
+}
+
+function collectChangedFields(existing, proposed) {
+    const fields = [];
+    if (stripChapterPrefix(existing.text) !== stripChapterPrefix(proposed.text)) {
+        fields.push('text');
+    }
+    if (existing.theme.trim() !== proposed.theme.trim()) {
+        fields.push('theme');
+    }
+    return fields;
+}
+
+function describeAddedRow(row) {
+    return {
+        id: null,
+        text: row.text,
+        index: row.index + 1,
+    };
+}
+
+function describeUpdatedRow(existing, row, fields) {
+    return {
+        id: row.id,
+        text: row.text,
+        index: row.index + 1,
+        fields,
+        before: {
+            text: existing.text,
+            theme: existing.theme,
+        },
+        after: {
+            text: row.text,
+            theme: row.theme,
+        },
+    };
+}
+
+function normalizeText(value) {
+    return value === undefined || value === null ? '' : String(value).trim();
+}
+
+function normalizeTheme(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => String(item).trim()).filter(Boolean).join('\n');
+    }
+    return value === undefined || value === null ? '' : String(value).trim();
+}
+
+function normalizeOptionalString(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const normalized = String(value).trim();
+    return normalized || undefined;
+}
+
+function normalizeImportant(value, fallback, index = null) {
+    if (value === undefined || value === null || value === '') {
+        return fallback;
+    }
+    const parsed = Number(value);
+    if (parsed !== 1 && parsed !== 2) {
+        const location = index === null ? '' : ` for chapter ${index + 1}`;
+        throw new Error(`Outline important${location} must be 1 (重点) or 2 (普通).`);
+    }
+    return parsed;
+}
+
+function normalizeSequelFlag(value, index) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (parsed !== 0 && parsed !== 1) {
+        throw new Error(`Outline sequelFlag for chapter ${index + 1} must be 0 or 1.`);
+    }
+    return parsed;
+}
+
+function stripChapterPrefix(value) {
+    let normalized = normalizeText(value).replace(/<[^>]+>/g, '').trim();
+    for (const pattern of CHAPTER_PREFIX_PATTERNS) {
+        normalized = normalized.replace(pattern, '').trim();
+    }
+    return normalized;
+}
+
+function compactObject(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}