@xqyz/xq-cli 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -10,6 +10,76 @@
 
 ## [Unreleased]
 
+### 正文阶段安全闸门复核
+
+- 大纲和目录实际保存前强制读取喜鹊后台权威任务状态，不再因为本机没有任务缓存而绕过“正文已开始/已完成”保护。
+- 状态校验放在 `--dry-run` 和用户确认之后、写接口之前，保留离线差异预览能力，同时覆盖确认后发生的并发状态变化。
+- 新增回归测试：无本地缓存的已完成任务不会调用大纲或目录保存接口；纯预览不会额外依赖任务详情接口。
+- 该修复当前属于未发布改动；npm 上的 `@xqyz/xq-cli@0.3.5` 和已发布 WorkBuddy Plugin `0.10.14` 尚未包含它，发布前必须递增 xq-cli 补丁版本并同步 Plugin 依赖。
+
+### WorkBuddy Plugin 0.10.14 / SkillHub 1.0.11 发布记录
+
+- 安装器不再把“`mcp.json` 已写入”误报为已升级：会固定写入 `0.10.14`，启动同一版本 MCP 完成 `initialize` 烟囱验证；验证失败会恢复原配置并输出 Node/npm 与 MCP 错误。
+- SkillHub 更新规则明确区分“Skill 已复制”和“WorkBuddy 已加载”：旧 Plugin、旧 xq-cli、缺失版本或 MCP 启动失败都必须执行升级，完全重启 WorkBuddy 后再次核对实际 `pluginVersion`、`cliVersion` 和登录状态。
+- macOS/Linux 安装路径改用兼容 BSD/macOS 的版本选择逻辑，去除 `sort -V` 和 npx 参数分隔符依赖，统一使用 `--yes --package <包> xique-workbuddy-mcp`；MCP 启动超时提高到 180 秒。
+- Windows MCP 启动验证会正确引用带空格的 `npx.cmd` / `*.bat` 路径，系统 Node 位于 `C:\Program Files` 时也能完成握手。
+- Connector、插件市场清单、SkillHub Skill 和安装脚本统一指向 WorkBuddy Plugin `0.10.14`；xq-cli 继续固定 `0.3.5`。
+- `@xqyz/workbuddy-plugin-xique@0.10.14` 已发布到 npm，`latest` 已指向 `0.10.14`；已生成 `output/skillhub-xique-bid-1.0.11.zip`，SkillHub 仍待手动上传。
+
+### WorkBuddy Plugin 0.10.13 / SkillHub 1.0.10 发布记录
+
+- 图片设置分组默认展开，用户打开配置卡即可选择图片来源和流程图样式；图片尺寸、页边距仍默认收起。
+- Plugin、Connector、SkillHub Skill 和本机 WorkBuddy Skill 已同步到本轮版本基线。
+- npm Plugin 已发布到 `latest`；SkillHub 上传包只在本机生成，不通过浏览器代发布，由发布人手动上传生成的 zip。
+
+### WorkBuddy 旧版本升级校验
+
+- `xique_runtime_status` 新增实际加载的 `pluginVersion`，用于区分“配置文件已写入”和“WorkBuddy 已加载新 MCP”。
+- SkillHub 更新时检测到旧版 Plugin 会执行固定版本升级；普通生成请求不会静默修改本机环境。
+- 安装后必须完全重启 WorkBuddy，并复核 `pluginVersion`、`cliVersion`、运行状态和登录状态，未通过复核不得报告安装成功。
+- 增加旧 `0.10.11` 配置升级到 `0.10.12` 的回归测试，保留其他 MCP、环境变量和备份文件。
+
+### SkillHub 1.0.9 上传包准备
+
+- 保持既有 Skill slug `xique-bid` 和显示名称“喜鹊标书”，不创建第二个同功能 Skill。
+- 上传内容同步旧 Plugin 版本探测、升级授权、重启后版本复核和失败停止重试规则。
+- 发布前必须确认 npm 已存在 `@xqyz/workbuddy-plugin-xique@0.10.12`，再上传 SkillHub `1.0.9`。
+
+### WorkBuddy 配置卡布局优化
+
+- 图片设置（来源、流程图样式和图片尺寸）与页边距改为默认收起的分组；默认值继续随配置提交，用户只有需要自定义排版时才展开。
+- 模板5的编号起始值和完整编号规则紧跟导出模板显示，选择模板5后自动展开，避免用户误以为是无关的后置导出参数。
+- MCP App 调整分组卡片、响应式网格和标题层级，减少长页面中的重复边框并改善窄屏可读性。
+- 增加配置分组、排序和默认收起状态的回归测试。
+
+### SkillHub 1.0.8 上传包准备
+
+- 已生成 `output/skillhub-xique-bid-1.0.8.zip`，保持既有 Skill slug `xique-bid` 和显示名称“喜鹊标书”。
+- 上传包同步本轮折叠分组、模板5编号紧邻展开和布局优化规则；正式发布前必须先发布 npm Plugin `0.10.12`。
+
+### WorkBuddy 配置卡补齐导出设置
+
+- 首次“喜鹊标书配置”卡增加图片来源、页边距和图片尺寸字段，默认值与喜鹊前端一致，提交后会随导出配置保存。
+- 选择“模板5｜自定义编号”后动态展开完整可视化编号设置：五级标题的编号格式、目录级别、字体、字号、对齐、加粗、分页/换行，正文四级编号及正文样式、起始编号。
+- 模板1-4 不显示也不要求填写自定义编号字段；模板5生成的结构化配置继续通过 `customNumbering` 传递，不要求用户输入 JSON。
+- 增加配置卡字段、模板切换显隐、默认值和完整配置数量回归测试。
+
+### WorkBuddy 配置卡稳定性修复
+
+- `xique_generation_status` 在解析完成进入 `bid-config` 或旧任务 `special-config` 时只返回权威阶段状态，不再直接返回没有 MCP App 元数据的配置卡结果。
+- Skill 会在状态进入配置阶段后立即显式调用带 UI 元数据的 `xique_bid_configuration` / `xique_special_project_selection`，避免 WorkBuddy 先显示普通文字、用户追问后才出现卡片。
+- 增加回归测试，确认同一 `runId` 下真实多标包仍能在显式配置卡中正常展示。
+
+## [0.3.5 / WorkBuddy Plugin 0.10.12] - 2026-08-20（npm 已发布）
+
+### 配置卡首次渲染修复
+
+- `xique_generation_status` 进入 `bid-config` 或旧任务 `special-config` 时只返回权威状态，不再直接返回没有 MCP App UI 元数据的 `selectionUi`。
+- Skill、命令和 Connector 指引改为在状态进入配置阶段后立即显式调用带 UI 元数据的配置工具，避免 WorkBuddy 首次只显示状态文本、用户追问后才出现配置卡。
+- 新增回归测试验证状态查询不产生卡片，但显式 `xique_bid_configuration` 仍能展示同一解析任务的真实多标包信息。
+- `xique_runtime_status` 返回实际加载的 `pluginVersion`；旧版本升级必须在重启 WorkBuddy 后复核版本、CLI 和登录状态。
+- 已发布 `@xqyz/workbuddy-plugin-xique@0.10.12`，npm `latest` 已指向该版本。
+
 ## [0.3.5 / WorkBuddy Plugin 0.10.11] - 2026-08-20（待发布）
 
 ### 文件解析与多标包统一配置

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xqyz/xq-cli",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "CLI for xique bid-book task workflows",
   "type": "module",
   "scripts": {

package/src/cli.mjs

@@ -23,6 +23,11 @@ import {
     buildDirectoryViewDocument,
     formatDirectoryLines,
 } from './directory-view.mjs';
+import {
+    assertContentCompleted,
+    assertContentGenerationAllowed,
+    assertPreContentMutationAllowed,
+} from './task-safety.mjs';
 
 const APP_DIR = path.join(os.homedir(), '.xq-opencli');
 const CONFIG_FILE = path.join(APP_DIR, 'config.json');
@@ -816,6 +821,8 @@ async function handlePeriodStatus(args, state) {
 async function handlePeriodConfirm(args, state) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, '确认工期');
     const contractPeriod = numberOption(args, 'contractPeriod');
     if (!Number.isInteger(contractPeriod) || contractPeriod <= 0) {
         throw new Error('Option --contract-period expects a positive integer.');
@@ -939,6 +946,16 @@ async function handleWizard(args, state) {
 }
 
 async function handlePlan(args, state) {
+    const action = String(args?._?.[1] || 'status').trim().toLowerCase();
+    const readOnly = new Set(['status', 'show', 'outline-view', 'directory-view']);
+    if (!readOnly.has(action)) {
+        const cid = resolveCid(args, state);
+        return withGenerationLock(cid, 'generation', () => handlePlanUnlocked(args, state));
+    }
+    return handlePlanUnlocked(args, state);
+}
+
+async function handlePlanUnlocked(args, state) {
     const action = String(args?._?.[1] || 'status').trim().toLowerCase();
     switch (action) {
         case 'status':
@@ -1081,6 +1098,8 @@ async function handlePlanFeedback(args, state) {
 async function handlePlanReferenceSelection(args, state) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, '提交响应依据');
     const referenceType = parseOutlineReferenceType(stringOption(args, 'referenceType'));
     if (referenceType === null) {
         throw new Error('plan reference-select requires --reference-type 0, 1, 2, merge, format, or score.');
@@ -1140,6 +1159,8 @@ async function handlePlanReferenceSelection(args, state) {
 async function handlePlanOutlineConfirmation(args, state) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, '确认或重新生成大纲');
     const snapshot = await hydrateTaskSnapshot(client, state, cid);
     const params = buildOutlineParams(snapshot, { ...args, planMode: 'planning' });
     const regenerating = booleanOption(args, 'regenerate') || normalizePlanModePhase(snapshot.plan_mode_phase) >= 1;
@@ -1195,6 +1216,8 @@ async function handlePlanOutlineConfirmation(args, state) {
 async function handlePlanAiOutlineAdjust(args, state) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, '请求 AI 调整大纲');
     const prompt = requiredOption(args, 'prompt').trim();
     if (!prompt) {
         throw new Error('Option --prompt cannot be empty.');
@@ -1279,6 +1302,8 @@ async function handlePlanAiOutlineApply(args, state) {
 async function handlePlanDirectoryGenerate(args, state, regenerating) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, regenerating ? '重新生成目录' : '生成目录');
     const snapshot = await hydrateTaskSnapshot(client, state, cid);
     ensurePlanningTask(snapshot);
     const currentPhase = normalizePlanModePhase(snapshot.plan_mode_phase);
@@ -1342,9 +1367,16 @@ async function handlePlanDirectoryGenerate(args, state, regenerating) {
 }
 
 async function handleOutline(args, state) {
+    const cid = resolveCid(args, state);
+    return withGenerationLock(cid, 'generation', () => handleOutlineUnlocked(args, state));
+}
+
+async function handleOutlineUnlocked(args, state) {
     validateOutlineReferenceTypeOption(args);
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, '重新生成大纲');
     const snapshot = await hydrateTaskSnapshot(client, state, cid);
     const outlineSnapshot = {
         ...snapshot,
@@ -1536,6 +1568,11 @@ async function handleOutlineUpdate(args, state) {
         return resultPayload;
     }
 
+    // Re-check the backend immediately before the write. Do not rely on the
+    // local task cache: a fresh machine may have no snapshot, and another
+    // process may have started body generation after the preview was read.
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, '修改大纲');
     const response = await postJson(client, '/c/updateOutLine', requestData);
     saveTaskSnapshot(state, cid, {
         outlineUpdatedAt: new Date().toISOString(),
@@ -1644,6 +1681,10 @@ async function handleDirectoryUpdate(args, state) {
         outputResult(args, { ...resultPayload, reason: 'cancelled' }, [`directory update cancelled: cid=${cid}`]);
         return { ...resultPayload, reason: 'cancelled' };
     }
+    // The local state file is only a cache. Always use the backend status for
+    // the final mutation so completed/in-flight content cannot be overwritten.
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid);
+    assertPreContentMutationAllowed(authoritativeState, '修改目录');
     const response = await postJson(client, '/task/updateDirectory', requestPreview);
     const payload = { ...resultPayload, applied: true, response };
     saveTaskSnapshot(state, cid, { directoryUpdatedAt: new Date().toISOString() });
@@ -1713,8 +1754,17 @@ function writeDirectoryViewFile(outputOption, cid, document) {
 }
 
 async function handleWrite(args, state) {
+    const cid = resolveCid(args, state);
+    return withGenerationLock(cid, 'generation', () => handleWriteUnlocked(args, state));
+}
+
+async function handleWriteUnlocked(args, state) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
+    // Check before directory polling so a completed/in-flight task cannot
+    // trigger a sequel request while a repeated write is being rejected.
+    const earlyTaskState = await fetchAuthoritativeTaskState(client, cid);
+    assertContentGenerationAllowed(earlyTaskState, '生成正文');
     const type = numberOption(args, 'type', 1);
     const directoryWaitResult = await ensureDirectoryReadyForWrite(client, state, cid, args);
 
@@ -1738,6 +1788,7 @@ async function handleWrite(args, state) {
     const contentDetail = {
         data: directoryWaitResult.contentDetail,
     };
+    assertContentGenerationAllowed(contentDetail.data, '生成正文');
     saveTaskSnapshot(state, cid, pickTaskSnapshot(contentDetail.data));
 
     const writePreparation = await prepareContentGeneration(client, state, cid, contentDetail, args);
@@ -1755,6 +1806,17 @@ async function handleWrite(args, state) {
     if (booleanOption(args, 'wait')) {
         status = await pollContentUntilReady(client, state, cid, args);
     }
+    if (status && status.task_status !== undefined) {
+        try {
+            assertContentCompleted(status, '确认正文完成');
+            saveTaskSnapshot(state, cid, {
+                contentGenerationCompletedAt: new Date().toISOString(),
+            });
+        } catch {
+            // The poller is the authoritative completion check; do not turn a
+            // successful backend response into a local-only failure marker.
+        }
+    }
 
     const resultPayload = {
         command: 'write',
@@ -1823,7 +1885,14 @@ async function handleStatus(args, state) {
 async function handleExport(args, state) {
     const client = createAuthorizedClient(args, state);
     const cid = resolveCid(args, state);
-    const snapshot = await hydrateTaskSnapshot(client, state, cid);
+    const cachedSnapshot = await hydrateTaskSnapshot(client, state, cid);
+    const authoritativeState = await fetchAuthoritativeTaskState(client, cid, { content: true });
+    assertContentCompleted(authoritativeState, '导出');
+    const snapshot = {
+        ...cachedSnapshot,
+        ...pickTaskSnapshot(authoritativeState),
+    };
+    saveTaskSnapshot(state, cid, snapshot);
     const effectiveArgs = booleanOption(args, 'interactive')
         ? await collectExportInteractiveArgs(args, snapshot)
         : args;
@@ -1859,7 +1928,12 @@ async function handleExport(args, state) {
     };
     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);
+    const savedPath = writeDownloadFile(effectiveArgs.out, fileName, response.data, {
+        protectedPaths: [
+            CONFIG_FILE,
+            ...(Array.isArray(snapshot.localFiles) ? snapshot.localFiles : []),
+        ],
+    });
     saveTaskSnapshot(state, cid, {
         tableColor,
         tableStyle,
@@ -1905,6 +1979,24 @@ async function hydrateTaskSnapshot(client, state, cid) {
     return snapshot;
 }
 
+async function fetchAuthoritativeTaskState(client, cid, options = {}) {
+    const taskResponse = await getJson(
+        client,
+        `/task/getTaskDetail/${encodeURIComponent(cid)}`,
+        {},
+        { retries: DEFAULT_RETRY_COUNT },
+    );
+    const taskData = taskResponse?.data || {};
+    if (!options.content) {
+        return taskData;
+    }
+    const contentResponse = await fetchContentDetail(client, cid);
+    return {
+        ...taskData,
+        ...(contentResponse?.data || {}),
+    };
+}
+
 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);
@@ -2854,6 +2946,7 @@ async function ensureDirectoryReadyForWrite(client, state, cid, args) {
 
 async function prepareContentGeneration(client, state, cid, contentDetailResponse, args) {
     const contentDetail = contentDetailResponse?.data || {};
+    assertContentGenerationAllowed(contentDetail, '生成正文');
     const viewStep = Number(contentDetail.viewStep);
     const taskStatus = Number(contentDetail.task_status);
     const contentPortionStatus = Number(contentDetail.content_portion_status);
@@ -4706,7 +4799,15 @@ function readState() {
 
 function writeState(state) {
     fs.mkdirSync(APP_DIR, { recursive: true });
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(state, null, 2), 'utf8');
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(state, null, 2), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    try {
+        fs.chmodSync(CONFIG_FILE, 0o600);
+    } catch {
+        // Windows ACLs may ignore POSIX mode bits; keep the user-scoped path.
+    }
 }
 
 function saveTaskSnapshot(state, cid, patch) {
@@ -4723,6 +4824,55 @@ function saveTaskSnapshot(state, cid, patch) {
     return state.tasks[cid];
 }
 
+async function withGenerationLock(cid, operation, work) {
+    const lockDirectory = path.join(APP_DIR, 'generation-locks');
+    fs.mkdirSync(lockDirectory, { recursive: true });
+    const lockPath = path.join(
+        lockDirectory,
+        encodeURIComponent(String(cid)) + '-' + encodeURIComponent(String(operation)) + '.lock',
+    );
+    let descriptor;
+    try {
+        descriptor = fs.openSync(lockPath, 'wx', 0o600);
+        fs.writeFileSync(descriptor, JSON.stringify({
+            cid: String(cid),
+            operation: String(operation),
+            pid: process.pid,
+            createdAt: new Date().toISOString(),
+        }), 'utf8');
+    } catch (error) {
+        if (error?.code === 'EEXIST') {
+            try {
+                const ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+                if (ageMs > 7 * 24 * 60 * 60 * 1000) {
+                    fs.unlinkSync(lockPath);
+                    return withGenerationLock(cid, operation, work);
+                }
+            } catch {
+                // Keep the fail-closed lock decision below when the lock cannot be inspected.
+            }
+            throw new Error('[GENERATION_LOCKED] 当前任务已有同一生成操作正在执行；请查询 status，不要并发重试。');
+        }
+        throw error;
+    } finally {
+        if (descriptor !== undefined) {
+            fs.closeSync(descriptor);
+        }
+    }
+
+    try {
+        return await work();
+    } finally {
+        try {
+            fs.unlinkSync(lockPath);
+        } catch (error) {
+            if (error?.code !== 'ENOENT') {
+                // A stale lock is safer than hiding the original generation result.
+            }
+        }
+    }
+}
+
 function pickTaskSnapshot(source) {
     return compactObject({
         cid: source.cid,
@@ -4771,6 +4921,8 @@ function pickTaskSnapshot(source) {
         outlineTriggeredAt: source.outlineTriggeredAt,
         triggerMode: source.triggerMode,
         writeTriggeredAt: source.writeTriggeredAt,
+        contentGenerationStartedAt: source.contentGenerationStartedAt,
+        contentGenerationCompletedAt: source.contentGenerationCompletedAt,
     });
 }
 
@@ -4801,10 +4953,21 @@ function normalizeDownloadFileName(value) {
     return String(value).replace(/[<>:"/\\|?*\u0000-\u001F]/g, '_').trim();
 }
 
-function writeDownloadFile(outputOption, fileName, fileContent) {
+function writeDownloadFile(outputOption, fileName, fileContent, options = {}) {
     const resolvedOutput = outputOption ? path.resolve(outputOption) : process.cwd();
     const outputIsDirectory = !path.extname(resolvedOutput);
     const finalPath = outputIsDirectory ? path.join(resolvedOutput, fileName) : resolvedOutput;
+    const protectedPaths = (options.protectedPaths || [])
+        .filter(Boolean)
+        .map(value => path.resolve(String(value)));
+    const normalizedFinalPath = path.resolve(finalPath);
+    if (protectedPaths.some(value => value === normalizedFinalPath)) {
+        throw new Error('[UNSAFE_OUTPUT_PATH] 输出文件不能覆盖源文件或 xq-cli 凭据/状态文件。请指定新的输出目录。');
+    }
+    if (normalizedFinalPath === path.resolve(APP_DIR)
+        || normalizedFinalPath.startsWith(path.resolve(APP_DIR) + path.sep)) {
+        throw new Error('[UNSAFE_OUTPUT_PATH] 输出文件不能写入 xq-cli 内部状态目录。请指定用户输出目录。');
+    }
     fs.mkdirSync(path.dirname(finalPath), { recursive: true });
     fs.writeFileSync(finalPath, Buffer.from(fileContent));
     return finalPath;

package/src/task-safety.mjs

@@ -0,0 +1,127 @@
+const CONTENT_VIEW_STEP = 101;
+
+export class TaskSafetyError extends Error {
+    constructor(code, message, details = {}) {
+        super('[' + code + '] ' + message);
+        this.name = 'TaskSafetyError';
+        this.code = code;
+        this.details = details;
+    }
+}
+
+function finiteNumber(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * Normalize the backend's mixed task/content status fields into a conservative
+ * decision. A missing status is intentionally not treated as "not started".
+ */
+export function classifyContentState(detail = {}) {
+    const taskStatus = finiteNumber(detail.task_status);
+    const contentPortionStatus = finiteNumber(detail.content_portion_status);
+    const viewStep = finiteNumber(detail.viewStep);
+    const percentage = finiteNumber(detail.percentage);
+    const completedChapter = finiteNumber(detail.completedChapter);
+    const totalChapter = finiteNumber(detail.totalChapter);
+    const statusKnown = [taskStatus, contentPortionStatus, viewStep, percentage, completedChapter, totalChapter]
+        .some(value => value !== null);
+    const complete = percentage !== null && percentage >= 100
+        || taskStatus === 5
+        || (totalChapter !== null && totalChapter > 0
+            && completedChapter !== null && completedChapter >= totalChapter)
+        || (taskStatus === 4 && contentPortionStatus === 1);
+    const failed = taskStatus === 7 || contentPortionStatus === 7;
+    const started = complete
+        || viewStep === CONTENT_VIEW_STEP
+        || (taskStatus !== null && (taskStatus === 4 || taskStatus === 5))
+        || (contentPortionStatus !== null && contentPortionStatus > 0)
+        || (percentage !== null && percentage > 0)
+        || (completedChapter !== null && completedChapter > 0);
+
+    return {
+        statusKnown,
+        complete,
+        failed,
+        started,
+        inFlight: started && !complete && !failed,
+        taskStatus,
+        contentPortionStatus,
+        viewStep,
+        percentage,
+        completedChapter,
+        totalChapter,
+    };
+}
+
+export function assertContentGenerationAllowed(detail, operation = '生成正文') {
+    const state = classifyContentState(detail);
+    if (!state.statusKnown) {
+        throw new TaskSafetyError(
+            'CONTENT_STATUS_UNKNOWN',
+            '无法确认当前任务正文状态，已拒绝' + operation + '。请先查询 status，确认后台状态后再重试。',
+            { state },
+        );
+    }
+    if (state.complete) {
+        throw new TaskSafetyError(
+            'CONTENT_ALREADY_COMPLETED',
+            '该任务正文已经生成完成，禁止再次生成；如需新文件请使用 export 重新导出。',
+            { state },
+        );
+    }
+    if (state.failed) {
+        throw new TaskSafetyError(
+            'CONTENT_GENERATION_FAILED',
+            '该任务的正文生成已失败，已拒绝自动重试以避免重复扣费或覆盖结果；请查询 status 后创建新的任务。',
+            { state },
+        );
+    }
+    if (state.started) {
+        throw new TaskSafetyError(
+            'CONTENT_GENERATION_IN_PROGRESS',
+            '该任务正文已经启动或正在生成，禁止重复触发；请继续查询 status。',
+            { state },
+        );
+    }
+    return state;
+}
+
+export function assertContentCompleted(detail, operation = '导出') {
+    const state = classifyContentState(detail);
+    if (!state.statusKnown) {
+        throw new TaskSafetyError(
+            'CONTENT_STATUS_UNKNOWN',
+            '无法确认当前任务正文状态，已拒绝' + operation + '。请先查询 status。',
+            { state },
+        );
+    }
+    if (!state.complete) {
+        throw new TaskSafetyError(
+            'CONTENT_NOT_COMPLETED',
+            '正文尚未生成完成，不能' + operation + '。请继续查询 status。',
+            { state },
+        );
+    }
+    return state;
+}
+
+export function assertPreContentMutationAllowed(detail, operation) {
+    const state = classifyContentState(detail);
+    if (!state.statusKnown) {
+        throw new TaskSafetyError(
+            'TASK_STATUS_UNKNOWN',
+            '无法确认当前任务阶段，已拒绝' + operation + '。请先查询 status。',
+            { state },
+        );
+    }
+    if (state.complete || state.started || state.failed) {
+        throw new TaskSafetyError(
+            'TASK_CONTENT_PHASE_LOCKED',
+            '正文阶段已经开始或已经结束，禁止' + operation + '；只能查看状态或重新导出。',
+            { state },
+        );
+    }
+    return state;
+}