@xqyz/xq-cli 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# 版本迭代日志
+
+本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)：
+
+- `MAJOR`：存在不兼容变更。
+- `MINOR`：向后兼容的新功能。
+- `PATCH`：向后兼容的修复或维护更新。
+
+发布日期以 npm 官方仓库记录为准。发布前必须先更新本文件，再执行版本发布。
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-10
+
+### 新增
+
+- 新增 `xq-cli directory view --cid <cid>`，通过只读目录树接口查看大纲续写后的完整目录。
+- 支持完整目录的递归编号展示、节点统计、`--json` 结构化输出和 `--out <path>` UTF-8 JSON 导出。
+- 新增 `xq-cli gallery-status`，调用与最新喜鹊前端一致的图库列表接口。
+- 结构化返回 `available` 和 `totalRecords`，供 WorkBuddy 在展示“我的图库”前判断是否可选。
+
+### 文档
+
+- 建立正式版本迭代日志。
+- 增加 npm 发布、验证、清理和故障处理手册。
+- 更新 CLI 帮助、README 和 OpenCLI 使用说明。
+
+### 维护
+
+- 规范 npm `bin` 入口路径，避免发布时由 npm 自动纠正清单。
+- 增加完整目录格式化与只读 API 集成测试。
+
+## [0.1.3] - 2026-08-07
+
+### 新增
+
+- 新增 `xq-cli outline view --cid <cid>`，只读查看已有大纲，不会重新触发大纲生成。
+- 支持通过 `--json` 返回完整大纲数据。
+- 支持通过 `--out <path>` 导出可编辑的大纲 JSON。
+- 新增 `xq-cli outline update --cid <cid> --file <file>`，从完整 JSON 文件更新大纲。
+- 支持修改章节标题、主题、重点程度和章节顺序，以及新增、删除章节。
+- 新增 `--dry-run`，在写入后台前展示新增、修改、删除、排序和重点程度差异。
+
+### 安全性
+
+- 自动校验编辑文件中的任务 CID、章节 ID、重复 ID 和必填字段。
+- 自动根据服务端当前大纲计算 `updateFlag`。
+- 非交互环境必须传入 `--yes` 才能保存修改。
+- 删除已有章节必须额外传入 `--allow-delete`。
+
+### 测试与文档
+
+- 增加大纲差异处理单元测试和模拟 API 集成测试，共 7 项。
+- 更新 CLI 帮助、README 和 OpenCLI 使用说明。
+
+## [0.1.2] - 2026-04-28
+
+### 变更
+
+- 默认使用生产 API 地址 `https://ai.bidfile.qianlima.com/api`。
+- 首次使用可直接执行 `xq-cli login`，不再要求每次显式提供 `--base-url`。
+- 完善本地配置读取与默认值合并，兼容旧配置和配置文件异常场景。
+- 更新生产环境和测试环境登录示例。
+
+## [0.1.1] - 2026-04-27
+
+### 变更
+
+- 增加 npm 官方仓库安装和全局升级说明。
+- 将登录示例从本地地址调整为生产环境地址。
+- 清理示例中的真实账号信息，改为通用占位符。
+
+## [0.1.0] - 2026-04-27
+
+### 新增
+
+- `@xqyz/xq-cli` 首次公开发布。
+- 提供登录、任务初始化、文件解析、大纲生成、正文生成、状态查询和 Word 导出能力。
+- 提供 `wizard` 全流程向导和生成配置选项查询。

package/README.md

@@ -4,6 +4,11 @@ Standalone CLI project for xique brand task workflows.
 
 Project execution rules for agents live in [AGENTS.md](./AGENTS.md). That file defines the mandatory config-confirmation flow before any bid generation run.
 
+Project maintenance documents:
+
+- [Version changelog](./CHANGELOG.md)
+- [Release process](./docs/RELEASING.md)
+
 ## Install from npm
 
 Install the published package from the public npm registry:
@@ -40,7 +45,7 @@ npm pack
 That command produces a `.tgz` tarball which can be shared and installed with:
 
 ```bash
-npm install -g .\xqyz-xq-cli-0.1.2.tgz
+npm install -g .\xqyz-xq-cli-0.1.4.tgz
 ```
 
 ## Usage
@@ -54,6 +59,13 @@ 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 directory view --cid <cid>
+xq-cli directory view --cid <cid> --out D:\output\directory.json
+xq-cli gallery-status --json
 xq-cli write --cid <cid> --wait
 xq-cli status --cid <cid> --content --json
 xq-cli export --cid <cid> --interactive --out D:\output
@@ -64,6 +76,13 @@ Fresh installs default to the production API address `https://ai.bidfile.qianlim
 
 `login` now defaults to browser authorization. If you explicitly pass `--name` and `--password`, the CLI falls back to password login.
 
+`directory view` reads the complete generated directory tree without triggering outline, directory, or content generation. Add `--json` for the raw API structure, or `--out <file-or-directory>` to save a UTF-8 JSON document.
+
+`gallery-status` checks the same `/image/library/query` endpoint as the latest
+frontend. `available=true` means “我的图库” contains at least one image and may
+be enabled for generation; an empty gallery remains unavailable until the user
+uploads an image in the Xique frontend.
+
 When `outline --wait` or `write --wait` hits a required response-basis step, the CLI will pause and ask you to choose `0/1/2` before continuing. It no longer auto-selects a default when you just press Enter.
 
 `write --wait` now also retries `sequelForOutline` when the directory phase stalls at the outline-complete step, and auto-calls `generateAllUnfinished` if the backend reports `100%` but still leaves unfinished chapters behind.
@@ -72,6 +91,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,18 +1,20 @@
 {
   "name": "@xqyz/xq-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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"
+    "xq-cli": "bin/xq-cli.js"
   },
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"

package/src/cli.mjs

@@ -12,6 +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';
+import {
+    buildDirectoryViewDocument,
+    formatDirectoryLines,
+} from './directory-view.mjs';
 
 const APP_DIR = path.join(os.homedir(), '.xq-opencli');
 const CONFIG_FILE = path.join(APP_DIR, 'config.json');
@@ -328,7 +339,29 @@ 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 'directory':
+            if (!parsed._[1] || isOutlineAction(parsed, ['view', 'show'])) {
+                await handleDirectoryView(parsed, state);
+            } else {
+                throw new Error(`Unknown directory action: ${parsed._[1]}`);
+            }
+            return;
+        case 'directory-view':
+            await handleDirectoryView(parsed, state);
             return;
         case 'write':
             await handleWrite(parsed, state);
@@ -342,6 +375,9 @@ async function main() {
         case 'choices':
             handleChoices(parsed);
             return;
+        case 'gallery-status':
+            await handleGalleryStatus(parsed, state);
+            return;
         case 'wizard':
             await handleWizard(parsed, state);
             return;
@@ -359,9 +395,13 @@ 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
+  directory view View the complete generated directory tree without triggering generation
   write         Charge if needed, enter content phase, and trigger content generation
   status        Query task status
   choices       Print selectable outline/export config values
+  gallery-status Check whether My Gallery contains selectable images
   wizard        Run init -> outline -> write -> export with interactive menus
   export        Download the generated docx
 
@@ -373,6 +413,7 @@ Examples
   xq-cli parse-status --cid <cid> --uuid <uuid> --wait
   xq-cli choices
   xq-cli choices outline --json
+  xq-cli gallery-status --json
   xq-cli wizard
   xq-cli wizard --file D:\\bids\\tender.docx
   xq-cli outline --cid <cid> --wait
@@ -382,6 +423,12 @@ 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 directory view --cid <cid>
+  xq-cli directory view --cid <cid> --out D:\\output\\directory.json
   xq-cli write --cid <cid> --type 1 --wait
   xq-cli status --cid <cid> --content
   xq-cli export --cid <cid> --interactive --out D:\\output\\
@@ -396,6 +443,9 @@ Common options
   --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
 
@@ -443,6 +493,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) {
@@ -632,6 +687,29 @@ function handleChoices(args) {
     return payload;
 }
 
+async function handleGalleryStatus(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const response = await postJson(client, '/image/library/query', {
+        pageSize: 1,
+        pageNum: 1,
+    });
+    const rawTotal = Number(response?.data?.pageModel?.totalRecords ?? 0);
+    const totalRecords = Number.isFinite(rawTotal) && rawTotal > 0 ? rawTotal : 0;
+    const resultPayload = {
+        command: 'gallery-status',
+        available: totalRecords > 0,
+        totalRecords,
+    };
+    outputResult(args, resultPayload, [
+        `my gallery: ${resultPayload.available ? 'available' : 'unavailable'}`,
+        `totalRecords: ${totalRecords}`,
+        resultPayload.available
+            ? 'knowledge-img can be enabled.'
+            : 'upload at least one image in the Xique frontend before enabling knowledge-img.',
+    ]);
+    return resultPayload;
+}
+
 async function handleWizard(args, state) {
     const wizardArgs = await collectWizardArgs(args, state);
     writeNotice(args, `wizard config: ${buildWizardSummary(wizardArgs)}`);
@@ -755,6 +833,197 @@ 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 handleDirectoryView(args, state) {
+    const client = createAuthorizedClient(args, state);
+    const cid = resolveCid(args, state);
+    const response = await getJson(
+        client,
+        `/task/directory/tree/${encodeURIComponent(cid)}`,
+        {},
+        { retries: DEFAULT_RETRY_COUNT },
+    );
+    const directoryDetail = response?.data || {};
+    const directoryDocument = buildDirectoryViewDocument(cid, directoryDetail);
+    const savedPath = stringOption(args, 'out')
+        ? writeDirectoryViewFile(stringOption(args, 'out'), cid, directoryDocument)
+        : null;
+
+    const resultPayload = {
+        command: 'directory-view',
+        cid,
+        directoryDetail,
+        directoryDocument: savedPath ? directoryDocument : undefined,
+        savedPath,
+    };
+    outputResult(args, resultPayload, [
+        ...formatDirectoryLines(cid, directoryDetail),
+        savedPath ? `savedPath: ${savedPath}` : 'hint: pass --out <file-or-directory> to save the complete directory JSON.',
+    ]);
+    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;
+}
+
+function writeDirectoryViewFile(outputOption, cid, document) {
+    const resolvedOutput = path.resolve(outputOption);
+    const outputIsDirectory = !path.extname(resolvedOutput);
+    const defaultName = `directory-${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);

package/src/directory-view.mjs

@@ -0,0 +1,89 @@
+export function extractDirectoryNodes(document = {}) {
+    const candidates = [
+        document,
+        document?.directoryNodes,
+        document?.data?.directoryNodes,
+        document?.directoryDetail?.directoryNodes,
+        document?.contentDetail?.directoryNodes,
+    ];
+    for (const candidate of candidates) {
+        if (Array.isArray(candidate)) {
+            return candidate;
+        }
+    }
+    return [];
+}
+
+export function buildDirectoryViewDocument(cid, directoryDetail = {}) {
+    const detail = directoryDetail && typeof directoryDetail === 'object' && !Array.isArray(directoryDetail)
+        ? directoryDetail
+        : {};
+    return {
+        format: 'xq-cli-directory@1',
+        ...detail,
+        cid,
+        directoryNodes: extractDirectoryNodes(detail),
+    };
+}
+
+export function getDirectoryStats(document = {}) {
+    const roots = extractDirectoryNodes(document);
+    let nodes = 0;
+    let maxDepth = 0;
+
+    function visit(rows, depth) {
+        for (const row of rows) {
+            nodes += 1;
+            maxDepth = Math.max(maxDepth, depth);
+            const children = Array.isArray(row?.children) ? row.children : [];
+            visit(children, depth + 1);
+        }
+    }
+
+    visit(roots, 1);
+    return {
+        roots: roots.length,
+        nodes,
+        maxDepth,
+    };
+}
+
+export function formatDirectoryLines(cid, directoryDetail = {}) {
+    const roots = extractDirectoryNodes(directoryDetail);
+    const stats = getDirectoryStats(roots);
+    const lines = [
+        `directory: cid=${cid}`,
+        `title: ${normalizeText(directoryDetail?.title) || '-'}`,
+        `task_status: ${directoryDetail?.task_status ?? '-'}`,
+        `roots: ${stats.roots}`,
+        `nodes: ${stats.nodes}`,
+        `max_depth: ${stats.maxDepth}`,
+    ];
+
+    if (roots.length === 0) {
+        lines.push('directory tree: empty');
+        return lines;
+    }
+
+    lines.push('directory tree:');
+    appendDirectoryRows(lines, roots);
+    return lines;
+}
+
+function appendDirectoryRows(lines, rows, prefix = [], depth = 0) {
+    rows.forEach((row, index) => {
+        const position = [...prefix, index + 1];
+        const text = normalizeText(row?.text || row?.title || row?.name) || '(unnamed directory)';
+        const id = normalizeText(row?.id);
+        lines.push(`${'  '.repeat(depth)}${position.join('.')}. ${text}${id ? ` [id=${id}]` : ''}`);
+        const children = Array.isArray(row?.children) ? row.children : [];
+        appendDirectoryRows(lines, children, position, depth + 1);
+    });
+}
+
+function normalizeText(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    return String(value).trim();
+}

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));
+}