weaver-work-cli 0.1.7 → 0.1.20

package/dist/shortcuts/caizhilian/operations/handlers/fileops.js

@@ -0,0 +1,570 @@
+import { randomUUID } from 'node:crypto';
+import { caizhilianValidationError } from '../../errors.js';
+import { updateDocBasicField } from '../api.js';
+import { issueWriteLease } from '../confirm.js';
+import { IMAGE_ALLOWED_EXT, assertAllowedExt, assertFileUnchanged, downloadAttachment, readFileMetadata, resolveSavePathArg, uploadFileToServer, } from '../files.js';
+import { fingerprint, isPlainObject, pyBool, timestampToDateStr, validateRequiredParams } from '../shared.js';
+import { caizhilianPrepared, caizhilianSuccess } from '../types.js';
+/**
+ * 文件域操作（1:1 对应源 scripts/document_plugins.py 的附件/封面部分
+ * + scripts/doc_compare_plugins.py 的文件对象查询/上传/比对提交部分）：
+ * UploadAttachmentToDocPlugin、ReplaceDocumentAttachmentPlugin、
+ * DownloadDocAttachmentPlugin、DownloadDocAttachmentToPdfPlugin、
+ * SetDocCoverPlugin、RemoveDocCoverPlugin、UploadCoverImagePlugin、
+ * DocCompareQueryFileObjectsPlugin、DocCompareUploadFilePlugin、DocCompareUploadComparedPlugin。
+ *
+ * 写操作按 weaver-work-cli 规范拆成 prepare（只读本地文件元数据 + 组装上传表单 + 签发票据）
+ * 与 apply（真正产生副作用：上传 / 更新文档字段 / 提交比对），
+ * 上传表单字段与源 upload_file_to_server 的 extra_body 逐字段一致。
+ */
+// ── 源常量 ────────────────────────────────────────────────
+/** 源 upload_file_to_server 的默认 upload_path。 */
+const MODULE_UPLOAD_PATH = '/api/file/module/upload';
+/** 源 ReplaceDocumentAttachmentPlugin 的 upload_path。 */
+const REUPLOAD_PATH = '/api/file/reUpload';
+/** 源附件上传固定字段 customParam。 */
+const FROM_PC_DOC_PARAM = '{"fromPCDoc":1}';
+/** 源 SetDocCoverPlugin / UploadCoverImagePlugin 的 extra_body。 */
+const COVER_UPLOAD_EXTRA_BODY = { createDoc: 'false' };
+/** 源 DocCompareUploadFilePlugin 的 extra_body。 */
+const COMPARE_UPLOAD_EXTRA_BODY = { module: 'docCompared' };
+const QUERY_FILE_OBJECTS_PATH = '/api/file/queryFileObjects';
+const COMPARE_SUBMIT_PATH = '/api/docCompare/uploadCompared';
+const TO_PDF_CHECK_PATH = '/api/file/download/toPdf';
+const DOC_UPDATE_PATH = '/api/doc/document/update';
+/** 源 doc_compare_plugins._COMPARE_OPTIONS：13 个比对选项全部固定为 0（键序与源一致）。 */
+const COMPARE_OPTIONS = {
+    ignoreImages: 0,
+    ignorePageHeader: 0,
+    ignoreSpace: 0,
+    ignorePunctuation: 0,
+    conversionAngle: 0,
+    conversionStyle: 0,
+    conversionSpecialSymbols: 0,
+    ignoreWatermark: 0,
+    ignoreSeals: 0,
+    parseTable: 0,
+    ignoreHandwriting: 0,
+    toLowerCase: 0,
+    ignoreAddendum: 0,
+};
+const ATTACHMENT_UPLOAD_APPLY = 'caizhilian.attachment.upload.apply';
+const ATTACHMENT_REPLACE_APPLY = 'caizhilian.attachment.replace.apply';
+const COVER_UPLOAD_APPLY = 'caizhilian.cover.upload.apply';
+const COVER_SET_APPLY = 'caizhilian.cover.set.apply';
+const COVER_REMOVE_APPLY = 'caizhilian.cover.remove.apply';
+const COMPARE_UPLOAD_APPLY = 'caizhilian.compare.upload-file.apply';
+const COMPARE_SUBMIT_APPLY = 'caizhilian.compare.submit.apply';
+// ── Python 语义小工具（源脚本直译）────────────────────────
+/** 源 `str(args.get(key) or "")`：Python 假值 → 空串，其余 str() 原样（不 strip）。 */
+function pyArgOrEmpty(args, key) {
+    const value = args[key];
+    return pyBool(value) ? String(value) : '';
+}
+/** 源 `str(args.get(key) or "").strip()`。 */
+function pyArgText(args, key) {
+    return pyArgOrEmpty(args, key).trim();
+}
+/**
+ * 源 `str(args.get(key, "")).strip()`（下载/比对类插件写法）：
+ * 键缺失按空串处理；CLI schema 已禁止 null，故不复刻 Python 的 str(None)='None'。
+ */
+function pyArgStripped(args, key) {
+    const value = args[key];
+    return value === undefined || value === null ? '' : String(value).trim();
+}
+/** 源 get_nested_value(data, "a.b")：路径不存在时返回 undefined。 */
+function nestedValue(response, ...keys) {
+    let current = response;
+    for (const key of keys) {
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/** 本地文件预览（prepare 阶段只读，不上传）。 */
+function filePreview(meta) {
+    return { file_name: meta.name, file_size: meta.size, file_md5: meta.md5, ext_name: meta.extName };
+}
+/** apply 前校验上传表单与 prepare 快照一致（CLI 侧防漂移，源无此保护）。 */
+function assertBodyUnchanged(lease, body, action) {
+    const expected = typeof lease.body_fingerprint === 'string' ? lease.body_fingerprint : '';
+    if (expected && expected !== fingerprint(body)) {
+        throw caizhilianValidationError('plan_changed', `${action} 的请求体与 prepare 时不一致，请重新执行 prepare`);
+    }
+}
+/** prepare 阶段的上传预览（真正上传延后到 apply）。 */
+function uploadPreview(extraBody, options = {}) {
+    return {
+        path: options.uploadPath ?? MODULE_UPLOAD_PATH,
+        extra_body: extraBody,
+        ...(options.allowedExt ? { allowed_ext: [...options.allowedExt].sort() } : {}),
+        ...(options.requiredPermission ? { required_permission: options.requiredPermission } : {}),
+        ...(options.permissionDeniedMessage ? { permission_denied_message: options.permissionDeniedMessage } : {}),
+        ...(options.extraResultFields ? { extra_result_fields: options.extraResultFields } : {}),
+        deferred_to_apply: true,
+    };
+}
+// ── caizhilian.attachment.download / download-as-pdf ──────
+const DOWNLOAD_ACTION = 'caizhilian.attachment.download';
+const DOWNLOAD_PDF_ACTION = 'caizhilian.attachment.download-as-pdf';
+/** 源 DownloadDocAttachmentPlugin / DownloadDocAttachmentToPdfPlugin 的公共入参解析。 */
+function resolveDownloadArgs(args) {
+    const attachmentId = pyArgStripped(args, 'attachment_id');
+    const docId = pyArgStripped(args, 'doc_id');
+    validateRequiredParams(args, ['attachment_id', 'doc_id']);
+    return { attachmentId, docId };
+}
+/** 源 DownloadDocAttachmentPlugin.execute。 */
+async function downloadAttachmentHandler(args, env) {
+    const { attachmentId, docId } = resolveDownloadArgs(args);
+    const savePath = resolveSavePathArg(args.save_path);
+    const result = await downloadAttachment(env.host, {
+        attachmentId,
+        docId,
+        savePath,
+        operation: DOWNLOAD_ACTION,
+    });
+    return caizhilianSuccess(DOWNLOAD_ACTION, result, { doc_id: docId, attachment_id: attachmentId });
+}
+/** 源 `to_pdf is True or to_pdf in ("1", "true", 1, True)`。 */
+function isPdfCapable(value) {
+    return value === true || value === 1 || value === '1' || value === 'true';
+}
+/** 源 DownloadDocAttachmentToPdfPlugin.execute：先 toPdf 预检，再带 downloadToPdf=true 下载。 */
+async function downloadAsPdfHandler(args, env) {
+    const { attachmentId, docId } = resolveDownloadArgs(args);
+    const savePath = resolveSavePathArg(args.save_path);
+    const encodedId = attachmentId.includes('%') ? attachmentId : encodeURIComponent(attachmentId);
+    const check = await env.host.request({
+        method: 'GET',
+        path: `${TO_PDF_CHECK_PATH}?fileId=${encodedId}`,
+        operation: DOWNLOAD_PDF_ACTION,
+    });
+    if (!isPdfCapable(nestedValue(check, 'data', 'toPdf'))) {
+        throw caizhilianValidationError('pdf_not_supported', '该附件不支持转为 PDF');
+    }
+    const result = await downloadAttachment(env.host, {
+        attachmentId,
+        docId,
+        savePath,
+        extraQuery: { downloadToPdf: 'true' },
+        operation: DOWNLOAD_PDF_ACTION,
+    });
+    return caizhilianSuccess(DOWNLOAD_PDF_ACTION, result, { doc_id: docId, attachment_id: attachmentId });
+}
+/** 源 UploadAttachmentToDocPlugin.execute 的入参解析 + extra_body 组装。 */
+async function planAttachmentUpload(args) {
+    validateRequiredParams(args, ['doc_id', 'file_path']);
+    const filePath = pyArgText(args, 'file_path');
+    const docId = pyArgText(args, 'doc_id');
+    /** 源 folder_id 不做 strip。 */
+    const folderId = pyArgOrEmpty(args, 'folder_id');
+    const meta = await readFileMetadata(filePath);
+    return {
+        docId,
+        folderId,
+        meta,
+        extraBody: {
+            docId,
+            customParam: FROM_PC_DOC_PARAM,
+            authModule: 'document',
+            refId: docId,
+            folderId,
+        },
+    };
+}
+const attachmentUploadHandler = {
+    targetKeys: ['doc_id', 'file_path'],
+    async prepare(args, env) {
+        const action = 'caizhilian.attachment.upload';
+        const plan = await planAttachmentUpload(args);
+        const lease = await issueWriteLease(env, ATTACHMENT_UPLOAD_APPLY, args, {
+            doc_id: plan.docId,
+            folder_id: plan.folderId,
+            file_path: plan.meta.path,
+            file_md5: plan.meta.md5,
+            file_size: plan.meta.size,
+            body_fingerprint: fingerprint(plan.extraBody),
+        });
+        return caizhilianPrepared(action, {
+            doc_id: plan.docId,
+            folder_id: plan.folderId,
+            ...filePreview(plan.meta),
+            upload: uploadPreview(plan.extraBody, {
+                requiredPermission: 'upload',
+                permissionDeniedMessage: '无上传权限：当前用户无权向该文档上传附件',
+                extraResultFields: ['uploadTime'],
+            }),
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = ATTACHMENT_UPLOAD_APPLY;
+        const plan = await planAttachmentUpload(args);
+        assertFileUnchanged(plan.meta, lease, 'file_path');
+        assertBodyUnchanged(lease, plan.extraBody, action);
+        const uploaded = await uploadFileToServer(env.host, plan.meta.path, {
+            extraBody: plan.extraBody,
+            requiredPermission: 'upload',
+            permissionDeniedMessage: '无上传权限：当前用户无权向该文档上传附件',
+            extraResultFields: ['uploadTime'],
+            operation: action,
+            preloadedMeta: plan.meta,
+        });
+        // 源 data["upload_time"] = data.pop("uploadTime", 0)：改名并保持键序在最后。
+        const { uploadTime, ...rest } = uploaded;
+        return caizhilianSuccess(action, { ...rest, upload_time: uploadTime ?? 0 }, { doc_id: plan.docId });
+    },
+};
+/** 源 ReplaceDocumentAttachmentPlugin.execute：三个 ID 逐个校验（源不校验 file_path）。 */
+async function planAttachmentReplace(args) {
+    const filePath = pyArgOrEmpty(args, 'file_path');
+    const docId = pyArgOrEmpty(args, 'doc_id');
+    const attachmentId = pyArgOrEmpty(args, 'attachment_id');
+    const folderId = pyArgOrEmpty(args, 'folder_id');
+    if (!docId)
+        throw caizhilianValidationError('field_required', '缺少必填参数: doc_id');
+    if (!attachmentId)
+        throw caizhilianValidationError('field_required', '缺少必填参数: attachment_id');
+    if (!folderId)
+        throw caizhilianValidationError('field_required', '缺少必填参数: folder_id');
+    const meta = await readFileMetadata(filePath);
+    return {
+        docId,
+        attachmentId,
+        folderId,
+        meta,
+        extraBody: {
+            docId,
+            editLinkType: 'editPage',
+            customParam: FROM_PC_DOC_PARAM,
+            authModule: 'document',
+            refId: docId,
+            employeePartTimeId: '',
+            folderId,
+            folderIdForStorageRule: 'true',
+            oldFileId: attachmentId,
+        },
+    };
+}
+const attachmentReplaceHandler = {
+    targetKeys: ['doc_id', 'attachment_id', 'file_path'],
+    async prepare(args, env) {
+        const action = 'caizhilian.attachment.replace';
+        const plan = await planAttachmentReplace(args);
+        const lease = await issueWriteLease(env, ATTACHMENT_REPLACE_APPLY, args, {
+            doc_id: plan.docId,
+            attachment_id: plan.attachmentId,
+            folder_id: plan.folderId,
+            file_path: plan.meta.path,
+            file_md5: plan.meta.md5,
+            file_size: plan.meta.size,
+            body_fingerprint: fingerprint(plan.extraBody),
+        });
+        return caizhilianPrepared(action, {
+            doc_id: plan.docId,
+            attachment_id: plan.attachmentId,
+            folder_id: plan.folderId,
+            ...filePreview(plan.meta),
+            upload: uploadPreview(plan.extraBody, {
+                uploadPath: REUPLOAD_PATH,
+                requiredPermission: 'reupload',
+                permissionDeniedMessage: '无替换附件上传权限',
+                extraResultFields: ['version'],
+            }),
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = ATTACHMENT_REPLACE_APPLY;
+        const plan = await planAttachmentReplace(args);
+        assertFileUnchanged(plan.meta, lease, 'file_path');
+        assertBodyUnchanged(lease, plan.extraBody, action);
+        const uploaded = await uploadFileToServer(env.host, plan.meta.path, {
+            extraBody: plan.extraBody,
+            uploadPath: REUPLOAD_PATH,
+            requiredPermission: 'reupload',
+            permissionDeniedMessage: '无替换附件上传权限',
+            extraResultFields: ['version'],
+            operation: action,
+            preloadedMeta: plan.meta,
+        });
+        return caizhilianSuccess(action, uploaded, { doc_id: plan.docId, attachment_id: plan.attachmentId });
+    },
+};
+// ── caizhilian.cover.upload / cover.set / cover.remove ────
+/** 源 UploadCoverImagePlugin / SetDocCoverPlugin 的图片读取 + 扩展名校验。 */
+async function planCoverImage(args) {
+    const meta = await readFileMetadata(args.file_path);
+    assertAllowedExt(meta, IMAGE_ALLOWED_EXT);
+    return meta;
+}
+const coverUploadHandler = {
+    targetKeys: ['file_path'],
+    async prepare(args, env) {
+        const action = 'caizhilian.cover.upload';
+        const meta = await planCoverImage(args);
+        const lease = await issueWriteLease(env, COVER_UPLOAD_APPLY, args, {
+            file_path: meta.path,
+            file_md5: meta.md5,
+            file_size: meta.size,
+            body_fingerprint: fingerprint(COVER_UPLOAD_EXTRA_BODY),
+        });
+        return caizhilianPrepared(action, {
+            ...filePreview(meta),
+            upload: uploadPreview(COVER_UPLOAD_EXTRA_BODY, { allowedExt: IMAGE_ALLOWED_EXT }),
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = COVER_UPLOAD_APPLY;
+        const meta = await planCoverImage(args);
+        assertFileUnchanged(meta, lease, 'file_path');
+        assertBodyUnchanged(lease, COVER_UPLOAD_EXTRA_BODY, action);
+        const uploaded = await uploadFileToServer(env.host, meta.path, {
+            allowedExt: IMAGE_ALLOWED_EXT,
+            extraBody: COVER_UPLOAD_EXTRA_BODY,
+            operation: action,
+            preloadedMeta: meta,
+        });
+        return caizhilianSuccess(action, uploaded);
+    },
+};
+/** 源 SetDocCoverPlugin.execute：doc_id 空值文案是「doc_id 不能为空」。 */
+async function planCoverSet(args) {
+    const docId = pyArgText(args, 'doc_id');
+    if (!docId)
+        throw caizhilianValidationError('field_required', 'doc_id 不能为空');
+    const meta = await planCoverImage(args);
+    return { docId, meta };
+}
+/** 源 _update_doc_basic_field 的请求体（封面字段固定为 coverPictureId）。 */
+function coverUpdateBody(docId, coverPictureId) {
+    return {
+        id: docId,
+        filed: 'coverPictureId',
+        document: { coverPictureId, shareOut: false },
+    };
+}
+const coverSetHandler = {
+    targetKeys: ['doc_id', 'file_path'],
+    async prepare(args, env) {
+        const action = 'caizhilian.cover.set';
+        const plan = await planCoverSet(args);
+        const lease = await issueWriteLease(env, COVER_SET_APPLY, args, {
+            doc_id: plan.docId,
+            file_path: plan.meta.path,
+            file_md5: plan.meta.md5,
+            file_size: plan.meta.size,
+            body_fingerprint: fingerprint(COVER_UPLOAD_EXTRA_BODY),
+        });
+        return caizhilianPrepared(action, {
+            doc_id: plan.docId,
+            ...filePreview(plan.meta),
+            upload: uploadPreview(COVER_UPLOAD_EXTRA_BODY, { allowedExt: IMAGE_ALLOWED_EXT }),
+            update: {
+                method: 'POST',
+                path: `${DOC_UPDATE_PATH}/${encodeURIComponent(plan.docId)}`,
+                filed: 'coverPictureId',
+                doc_field: 'coverPictureId',
+                value_source: 'upload.file_id',
+                deferred_to_apply: true,
+            },
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = COVER_SET_APPLY;
+        const plan = await planCoverSet(args);
+        assertFileUnchanged(plan.meta, lease, 'file_path');
+        assertBodyUnchanged(lease, COVER_UPLOAD_EXTRA_BODY, action);
+        const uploaded = await uploadFileToServer(env.host, plan.meta.path, {
+            allowedExt: IMAGE_ALLOWED_EXT,
+            extraBody: COVER_UPLOAD_EXTRA_BODY,
+            operation: action,
+            preloadedMeta: plan.meta,
+        });
+        await updateDocBasicField(env, {
+            docId: plan.docId,
+            filed: 'coverPictureId',
+            argKey: 'cover_picture_id',
+            docField: 'coverPictureId',
+            allowEmpty: true,
+            fixedValue: String(uploaded.file_id),
+        }, action);
+        return caizhilianSuccess(action, { doc_id: plan.docId, file_id: uploaded.file_id, name: uploaded.name }, { body: coverUpdateBody(plan.docId, String(uploaded.file_id)) });
+    },
+};
+/** 源 RemoveDocCoverPlugin.execute：只有 doc_id 一个入参，封面字段置空串。 */
+const coverRemoveHandler = {
+    targetKeys: ['doc_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.cover.remove';
+        validateRequiredParams(args, ['doc_id']);
+        const docId = pyArgStripped(args, 'doc_id');
+        const lease = await issueWriteLease(env, COVER_REMOVE_APPLY, args, { doc_id: docId });
+        return caizhilianPrepared(action, {
+            doc_id: docId,
+            update: {
+                method: 'POST',
+                path: `${DOC_UPDATE_PATH}/${encodeURIComponent(docId)}`,
+                body: coverUpdateBody(docId, ''),
+            },
+        }, lease);
+    },
+    async apply(args, env, _lease) {
+        const action = COVER_REMOVE_APPLY;
+        validateRequiredParams(args, ['doc_id']);
+        const result = await updateDocBasicField(env, {
+            docId: args.doc_id,
+            filed: 'coverPictureId',
+            argKey: 'cover_picture_id',
+            docField: 'coverPictureId',
+            allowEmpty: true,
+            fixedValue: '',
+        }, action);
+        return caizhilianSuccess(action, result);
+    },
+};
+// ── caizhilian.compare.list-file-objects ──────────────────
+const LIST_FILE_OBJECTS_ACTION = 'caizhilian.compare.list-file-objects';
+/** 源 DocCompareQueryFileObjectsPlugin.execute。 */
+async function listFileObjectsHandler(args, env) {
+    validateRequiredParams(args, ['doc_id']);
+    const docId = pyArgStripped(args, 'doc_id');
+    const response = await env.host.request({
+        method: 'POST',
+        path: QUERY_FILE_OBJECTS_PATH,
+        body: [{ docId: String(docId) }],
+        operation: LIST_FILE_OBJECTS_ACTION,
+    });
+    const rawList = nestedValue(response, 'data');
+    if (!Array.isArray(rawList)) {
+        throw caizhilianValidationError('response_shape', '响应结构异常: data 段应为文件对象列表');
+    }
+    const attachments = [];
+    for (const item of rawList) {
+        if (!isPlainObject(item))
+            continue;
+        attachments.push({
+            docId: item.docId ?? null,
+            file_id: item.attachmentId ?? null,
+            ext_name: item.type ?? null,
+            file_name: item.fileName ?? null,
+            size: item.size ?? null,
+            updateTime: timestampToDateStr(item.updateTime),
+        });
+    }
+    return caizhilianSuccess(LIST_FILE_OBJECTS_ACTION, { attachments }, { doc_id: docId });
+}
+// ── caizhilian.compare.upload-file ────────────────────────
+/** 源 DocCompareUploadFilePlugin.execute 的入参解析。 */
+async function planCompareUpload(args) {
+    validateRequiredParams(args, ['file_path']);
+    return readFileMetadata(pyArgStripped(args, 'file_path'));
+}
+const compareUploadFileHandler = {
+    targetKeys: ['file_path'],
+    async prepare(args, env) {
+        const action = 'caizhilian.compare.upload-file';
+        const meta = await planCompareUpload(args);
+        const lease = await issueWriteLease(env, COMPARE_UPLOAD_APPLY, args, {
+            file_path: meta.path,
+            file_md5: meta.md5,
+            file_size: meta.size,
+            body_fingerprint: fingerprint(COMPARE_UPLOAD_EXTRA_BODY),
+        });
+        return caizhilianPrepared(action, {
+            ...filePreview(meta),
+            upload: uploadPreview(COMPARE_UPLOAD_EXTRA_BODY, {
+                requiredPermission: 'upload',
+                permissionDeniedMessage: '无上传权限：当前用户无权向文档比对模块上传文件',
+            }),
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = COMPARE_UPLOAD_APPLY;
+        const meta = await planCompareUpload(args);
+        assertFileUnchanged(meta, lease, 'file_path');
+        assertBodyUnchanged(lease, COMPARE_UPLOAD_EXTRA_BODY, action);
+        const uploaded = await uploadFileToServer(env.host, meta.path, {
+            extraBody: COMPARE_UPLOAD_EXTRA_BODY,
+            requiredPermission: 'upload',
+            permissionDeniedMessage: '无上传权限：当前用户无权向文档比对模块上传文件',
+            operation: action,
+            preloadedMeta: meta,
+        });
+        return caizhilianSuccess(action, uploaded);
+    },
+};
+// ── caizhilian.compare.submit ─────────────────────────────
+/** 源 doc_compare_plugins._generate_queueing_uuid。 */
+function generateQueueingUuid() {
+    const raw = randomUUID().replace(/-/g, '').toUpperCase();
+    return `GUID_${raw.slice(0, 8)}_${raw.slice(8, 12)}_${raw.slice(12, 16)}_${raw.slice(16, 20)}_${raw.slice(20)}`;
+}
+/** 源 DocCompareUploadComparedPlugin 的请求体（键序与源一致）。 */
+function buildCompareSubmitBody(leftFileId, rightFileId, queueingUuid) {
+    return {
+        leftEntryIds: String(leftFileId),
+        rightEntryIds: String(rightFileId),
+        queueingUUID: queueingUuid,
+        ...COMPARE_OPTIONS,
+    };
+}
+/** 源 DocCompareUploadComparedPlugin.execute 的入参解析。 */
+function planCompareSubmit(args) {
+    validateRequiredParams(args, ['left_file_id', 'right_file_id']);
+    return {
+        leftFileId: pyArgStripped(args, 'left_file_id'),
+        rightFileId: pyArgStripped(args, 'right_file_id'),
+    };
+}
+const compareSubmitHandler = {
+    targetKeys: ['left_file_id', 'right_file_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.compare.submit';
+        const plan = planCompareSubmit(args);
+        const queueingUuid = generateQueueingUuid();
+        const body = buildCompareSubmitBody(plan.leftFileId, plan.rightFileId, queueingUuid);
+        const lease = await issueWriteLease(env, COMPARE_SUBMIT_APPLY, args, {
+            left_file_id: plan.leftFileId,
+            right_file_id: plan.rightFileId,
+            queueing_uuid: queueingUuid,
+            body_fingerprint: fingerprint(body),
+        });
+        return caizhilianPrepared(action, {
+            left_file_id: plan.leftFileId,
+            right_file_id: plan.rightFileId,
+            request: { method: 'POST', path: COMPARE_SUBMIT_PATH, body },
+            note: '比对结果链接为外部制品（compare_link），CLI 只返回链接，不代下载',
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = COMPARE_SUBMIT_APPLY;
+        const plan = planCompareSubmit(args);
+        const queueingUuid = typeof lease.queueing_uuid === 'string' && lease.queueing_uuid ? lease.queueing_uuid : generateQueueingUuid();
+        const body = buildCompareSubmitBody(plan.leftFileId, plan.rightFileId, queueingUuid);
+        assertBodyUnchanged(lease, body, action);
+        const response = await env.host.request({
+            method: 'POST',
+            path: COMPARE_SUBMIT_PATH,
+            body,
+            operation: action,
+        });
+        const raw = nestedValue(response, 'data', 'compareLink');
+        const compareLink = pyBool(raw) ? raw : '';
+        return caizhilianSuccess(action, { compare_link: compareLink }, { left_file_id: plan.leftFileId, right_file_id: plan.rightFileId });
+    },
+};
+// ── 处理器汇总 ────────────────────────────────────────────
+export const caizhilianFileopsHandlers = {
+    'caizhilian.attachment.upload': attachmentUploadHandler,
+    'caizhilian.attachment.replace': attachmentReplaceHandler,
+    'caizhilian.attachment.download': { execute: downloadAttachmentHandler },
+    'caizhilian.attachment.download-as-pdf': { execute: downloadAsPdfHandler },
+    'caizhilian.cover.upload': coverUploadHandler,
+    'caizhilian.cover.set': coverSetHandler,
+    'caizhilian.cover.remove': coverRemoveHandler,
+    'caizhilian.compare.list-file-objects': { execute: listFileObjectsHandler },
+    'caizhilian.compare.upload-file': compareUploadFileHandler,
+    'caizhilian.compare.submit': compareSubmitHandler,
+};