weaver-work-cli 0.1.8 → 0.1.20

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

@@ -0,0 +1,890 @@
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { CaizhilianCliError, caizhilianValidationError } from '../../errors.js';
+import { asList, asRecord, buildCreateDocumentBody, fetchCurrentUserInfo, fetchDocBaseInfo, nestedRecord, runCreatePreamble, updateDocBasicField, } from '../api.js';
+import { issueWriteLease } from '../confirm.js';
+import { CONTENT_TYPE_EXT_MAP, EXT_TO_CONTENT_TYPE, OFFICE_ALLOWED_EXT, assertFileUnchanged, readFileMetadata, uploadFileToServer, } from '../files.js';
+import { assertEnum, fingerprint, optionalId, optionalIdList, optionalList, optionalRawText, requireId, requireText, } from '../shared.js';
+import { caizhilianPrepared, caizhilianSuccess } from '../types.js';
+/**
+ * 文档域操作（1:1 对应源 scripts/document_plugins.py 的文档创建/修改部分
+ * + doc-business-operations/fetch_doc_base_info_by_docid.json 响应模板
+ * + search_operations.json 的 fetch_current_user_info）。
+ *
+ * 写操作按 weaver-work-cli 规范拆成 prepare（只读回查 + 组装请求体 + 签发票据）
+ * 与 apply（真正产生副作用），业务请求体与源保持逐字段一致。
+ */
+/** 源 folder_type 取值（build_create_document_body 直接 str() 透传）。 */
+const FOLDER_TYPES = ['company', 'privy', 'sys'];
+/** 源 document_plugins.MARKDOWN_ALLOWED_EXT。 */
+const MARKDOWN_ALLOWED_EXT = ['.md', '.markdown'];
+/** 源 _execute_create_and_extract 的创建接口。 */
+const CREATE_DETAIL_PATH = '/api/doc/document/createDetail';
+/** 源 CreateDocumentByUploadPlugin.MAX_UPLOAD_WORKERS。 */
+const MAX_UPLOAD_WORKERS = 8;
+/** 源 UpdateDocFieldPlugin._FIELD_MAP：field -> (filed, arg_key, allow_empty)。 */
+const FIELD_MAP = {
+    name: { filed: 'name', argKey: 'name', allowEmpty: false },
+    keywords: { filed: 'keywords', argKey: 'keywords', allowEmpty: true },
+    abstract: { filed: 'abstractText', argKey: 'abstract_text', allowEmpty: true },
+    auto_invalid_date: { filed: 'autoInvalidateDate', argKey: 'auto_invalid_date', allowEmpty: true },
+};
+/** 源 sorted(_FIELD_MAP) 的报错文案顺序。 */
+const FIELD_MAP_KEYS_SORTED = Object.keys(FIELD_MAP).sort();
+// ── caizhilian.document.get ───────────────────────────────
+async function getDocument(args, env) {
+    const action = 'caizhilian.document.get';
+    const docId = requireId(args.doc_id, 'doc_id');
+    const info = await fetchDocBaseInfo(env, docId, action);
+    return caizhilianSuccess(action, info);
+}
+// ── caizhilian.user.current ───────────────────────────────
+async function currentUser(_args, env) {
+    const action = 'caizhilian.user.current';
+    return caizhilianSuccess(action, await fetchCurrentUserInfo(env, action));
+}
+// ── 文档创建：入参归一化与前置 ────────────────────────────
+/**
+ * 源 validate_required_params + build_create_document_body 的取值语义：
+ * 必填项按源顺序校验，可选项仅在“真值”时写入（空串/空数组等同未传）。
+ */
+function normalizeCreateArgs(args, required) {
+    const out = {};
+    for (const key of required) {
+        switch (key) {
+            case 'name':
+                out.name = requireText(args.name, 'name');
+                break;
+            case 'folder_id':
+                out.folder_id = requireId(args.folder_id, 'folder_id');
+                break;
+            case 'folder_type':
+                out.folder_type = assertEnum(args.folder_type, FOLDER_TYPES, 'folder_type');
+                break;
+            case 'author_id':
+                out.author_id = requireId(args.author_id, 'author_id');
+                break;
+            case 'file_path':
+                out.file_path = requireText(args.file_path, 'file_path');
+                break;
+            case 'file_paths':
+                out.file_paths = args.file_paths;
+                break;
+            default:
+                if (args[key] === undefined || args[key] === null || args[key] === '') {
+                    throw caizhilianValidationError('field_required', `缺少必填参数: ${key}`);
+                }
+                out[key] = args[key];
+        }
+    }
+    const summary = optionalRawText(args.summary);
+    if (summary !== undefined)
+        out.summary = summary;
+    const abstractText = optionalRawText(args.abstract_text);
+    if (abstractText !== undefined)
+        out.abstract_text = abstractText;
+    const keywords = optionalRawText(args.keywords);
+    if (keywords !== undefined)
+        out.keywords = keywords;
+    const autoInvalidateDate = optionalRawText(args.auto_invalidate_date);
+    if (autoInvalidateDate !== undefined)
+        out.auto_invalidate_date = autoInvalidateDate;
+    const coverPictureId = optionalId(args.cover_picture_id, 'cover_picture_id');
+    if (coverPictureId !== undefined)
+        out.cover_picture_id = coverPictureId;
+    if (args.doc_category !== undefined && args.doc_category !== null && args.doc_category !== '') {
+        const parsed = Number(args.doc_category);
+        if (!Number.isInteger(parsed)) {
+            throw caizhilianValidationError('doc_category_invalid', 'doc_category 必须是整数');
+        }
+        out.doc_category = parsed;
+    }
+    const tags = optionalList(args.tags, 'tags');
+    if (tags)
+        out.tags = tags;
+    const participantIds = optionalIdList(args.participant_ids, 'participant_ids');
+    if (participantIds)
+        out.participant_ids = participantIds;
+    const virtualFolderIds = optionalIdList(args.virtual_folder_ids, 'virtual_folder_ids');
+    if (virtualFolderIds)
+        out.virtual_folder_ids = virtualFolderIds;
+    const filePath = optionalRawText(args.file_path);
+    if (filePath !== undefined)
+        out.file_path = filePath;
+    return out;
+}
+/** 源「文件夹兜底结果被共享兜底覆盖」的可观测告警（1:1 保留源行为，但显式提示）。 */
+const FOLDER_FALLBACK_KEYS = ['participant_ids', 'virtual_folder_ids', 'folder_default_share_new'];
+function droppedFallbackWarnings(preamble) {
+    const dropped = FOLDER_FALLBACK_KEYS.filter((key) => preamble.folderFallbackArgs[key] !== undefined && preamble.args[key] === undefined);
+    if (!dropped.length)
+        return [];
+    return [
+        `源行为 1:1 保留：文件夹默认值兜底结果（${dropped.join('、')}）被默认共享兜底覆盖，未写入创建请求体；`
+            + '如需回填请显式传入 participant_ids / virtual_folder_ids，或改用 caizhilian.document.create-by-upload',
+    ];
+}
+/** 创建类操作 prepare 的统一预览结构。 */
+function createPreview(docType, body) {
+    const doc = asRecord(body.document);
+    return {
+        doc_type: docType,
+        content_type: doc.contentType ?? '',
+        name: doc.name ?? '',
+        folder_id: body.folderId ?? '',
+        folder_type: body.folderType ?? '',
+        author_id: asRecord(doc.author).id ?? '',
+        doc_status_name: doc.docStatusName ?? '',
+        content_length: typeof doc.summary === 'string' ? doc.summary.length : 0,
+        content_file_id: doc.content ?? '',
+        keywords: doc.keywords ?? '',
+        abstract_text: doc.abstractText ?? '',
+        auto_invalidate_date: doc.autoInvalidateDate ?? '',
+        doc_category: doc.docCategory ?? null,
+        cover_picture_id: doc.coverPictureId ?? '',
+        tags_count: asList(doc.tags).length,
+        participant_ids: asList(body.shareList).map((item) => String(asRecord(item).sid ?? '')),
+        virtual_folder_ids: asList(doc.virtualFolders).map((item) => String(asRecord(item).id ?? '')),
+        doc_share_list_count: asList(body.docShareList).length,
+        request: { method: 'POST', path: CREATE_DETAIL_PATH },
+    };
+}
+/** 源 _read_markdown_file：UTF-8 优先，解码失败回退 GBK。 */
+async function readMarkdownFile(filePath) {
+    let buffer;
+    try {
+        buffer = await readFile(filePath);
+    }
+    catch (error) {
+        throw caizhilianValidationError('file_unreadable', `文件读取失败: ${filePath}（${error instanceof Error ? error.message : String(error)}）`);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+    }
+    catch {
+        // 落到 GBK 回退
+    }
+    try {
+        return new TextDecoder('gbk').decode(buffer);
+    }
+    catch {
+        throw caizhilianValidationError('file_encoding_unknown', `文件编码无法识别（已尝试 UTF-8 / GBK）: ${filePath}`);
+    }
+}
+function assertMarkdownExt(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    if (!MARKDOWN_ALLOWED_EXT.includes(ext)) {
+        throw caizhilianValidationError('file_type_not_allowed', `不支持的文件类型 ${ext}，仅支持: ${[...MARKDOWN_ALLOWED_EXT].sort().join(', ')}`);
+    }
+    return ext;
+}
+/** 批量并发（源 ThreadPoolExecutor(max_workers=min(8, n))），保持输入顺序输出。 */
+async function mapWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const runners = new Array(Math.min(limit, items.length)).fill(0).map(async () => {
+        while (cursor < items.length) {
+            const index = cursor;
+            cursor += 1;
+            results[index] = await worker(items[index], index);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
+// ── 写操作 apply 名（continuation 与操作绑定，防跨操作串用）──
+const CREATE_HTML_APPLY = 'caizhilian.document.create-html.apply';
+const CREATE_MARKDOWN_APPLY = 'caizhilian.document.create-markdown.apply';
+const CREATE_OFFICE_APPLY = 'caizhilian.document.create-office.apply';
+const CREATE_BY_UPLOAD_APPLY = 'caizhilian.document.create-by-upload.apply';
+const UPDATE_FIELD_APPLY = 'caizhilian.document.update-field.apply';
+const UPDATE_AUTHOR_APPLY = 'caizhilian.document.update-author.apply';
+const UPDATE_HTML_APPLY = 'caizhilian.document.update-html.apply';
+const REPLACE_CONTENT_APPLY = 'caizhilian.document.replace-content.apply';
+/** 源 _execute_create_and_extract：POST createDetail 后取 data.document.id。 */
+async function executeCreate(env, body, action) {
+    const response = await env.host.request({ method: 'POST', path: CREATE_DETAIL_PATH, body, operation: action });
+    return { doc_id: String(nestedRecord(response, 'data', 'document').id ?? '') };
+}
+/** prepare 票据载荷：目标键 + 请求体指纹（不存正文等大字段）。 */
+function planLeasePayload(plan) {
+    const doc = asRecord(plan.body.document);
+    return {
+        content_type: plan.contentType,
+        folder_id: String(plan.body.folderId ?? ''),
+        author_id: String(asRecord(doc.author).id ?? ''),
+        name: String(doc.name ?? ''),
+        body_fingerprint: fingerprint(plan.body),
+        ...(plan.meta ? { file_path: plan.meta.path, file_md5: plan.meta.md5, file_size: plan.meta.size } : {}),
+    };
+}
+/** apply 前校验请求体与 prepare 快照一致（文件夹默认值/权限变化会让指纹不同）。 */
+function assertPlanUnchanged(lease, plan, action) {
+    const expected = typeof lease.body_fingerprint === 'string' ? lease.body_fingerprint : '';
+    if (!expected)
+        return;
+    if (expected !== fingerprint(plan.body)) {
+        throw caizhilianValidationError('plan_changed', `${action} 的请求体与 prepare 时不一致（文件夹默认值或权限可能已变化），请重新执行 prepare`);
+    }
+}
+/** 本地文件预览（prepare 阶段只读，不上传）。 */
+function filePreview(meta) {
+    return { file_name: meta.name, file_size: meta.size, file_md5: meta.md5, ext_name: meta.extName };
+}
+// ── caizhilian.document.create-html ───────────────────────
+/** 源 CreateHtmlDocumentPlugin.execute。 */
+async function planCreateHtml(args, env, action) {
+    const normalized = normalizeCreateArgs(args, ['name', 'folder_id', 'folder_type', 'author_id']);
+    const preamble = await runCreatePreamble(env, normalized, { docType: 'html', operation: action });
+    return {
+        body: buildCreateDocumentBody(preamble.args, 'html'),
+        contentType: 'html',
+        warnings: droppedFallbackWarnings(preamble),
+    };
+}
+const createHtmlHandler = {
+    targetKeys: ['folder_id', 'author_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.create-html';
+        const plan = await planCreateHtml(args, env, action);
+        const lease = await issueWriteLease(env, CREATE_HTML_APPLY, args, planLeasePayload(plan));
+        return caizhilianPrepared(action, createPreview('html', plan.body), lease, plan.warnings);
+    },
+    async apply(args, env, lease) {
+        const action = CREATE_HTML_APPLY;
+        const plan = await planCreateHtml(args, env, 'caizhilian.document.create-html');
+        assertPlanUnchanged(lease, plan, action);
+        return caizhilianSuccess(action, await executeCreate(env, plan.body, action), {
+            content_type: plan.contentType,
+        }, plan.warnings);
+    },
+};
+// ── caizhilian.document.create-markdown ───────────────────
+/** 源 CreateMarkdownDocumentPlugin.execute：file_path 可选，读入后覆盖 summary。 */
+async function planCreateMarkdown(args, env, action) {
+    const normalized = normalizeCreateArgs(args, ['name', 'folder_id', 'folder_type', 'author_id']);
+    const preamble = await runCreatePreamble(env, normalized, { docType: 'markdown', operation: action });
+    let effective = preamble.args;
+    let meta;
+    const filePath = optionalRawText(effective.file_path);
+    if (filePath !== undefined) {
+        meta = await readFileMetadata(filePath);
+        assertMarkdownExt(meta.path);
+        effective = { ...effective, summary: await readMarkdownFile(meta.path) };
+    }
+    return {
+        body: buildCreateDocumentBody(effective, 'markdown'),
+        contentType: 'markdown',
+        warnings: droppedFallbackWarnings(preamble),
+        ...(meta ? { meta } : {}),
+    };
+}
+const createMarkdownHandler = {
+    targetKeys: ['folder_id', 'author_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.create-markdown';
+        const plan = await planCreateMarkdown(args, env, action);
+        const lease = await issueWriteLease(env, CREATE_MARKDOWN_APPLY, args, planLeasePayload(plan));
+        return caizhilianPrepared(action, { ...createPreview('markdown', plan.body), ...(plan.meta ? filePreview(plan.meta) : {}) }, lease, plan.warnings);
+    },
+    async apply(args, env, lease) {
+        const action = CREATE_MARKDOWN_APPLY;
+        const plan = await planCreateMarkdown(args, env, 'caizhilian.document.create-markdown');
+        if (plan.meta)
+            assertFileUnchanged(plan.meta, lease, 'file_path');
+        assertPlanUnchanged(lease, plan, action);
+        return caizhilianSuccess(action, await executeCreate(env, plan.body, action), {
+            content_type: plan.contentType,
+        }, plan.warnings);
+    },
+};
+// ── caizhilian.document.create-office ─────────────────────
+/** 源 CreateOfficeDocumentPlugin.execute（校验顺序与源一致：扩展名 → 前置 → 名称缺省 → 上传）。 */
+async function planCreateOffice(args, env, action) {
+    const normalized = normalizeCreateArgs(args, ['file_path', 'folder_id', 'folder_type', 'author_id']);
+    const filePath = requireText(normalized.file_path, 'file_path');
+    const ext = extname(filePath).toLowerCase();
+    if (!OFFICE_ALLOWED_EXT.includes(ext)) {
+        throw caizhilianValidationError('file_type_not_allowed', `不支持的文件类型 ${ext}，仅支持: ${[...OFFICE_ALLOWED_EXT].sort().join(', ')}`);
+    }
+    const contentType = EXT_TO_CONTENT_TYPE[ext];
+    const preamble = await runCreatePreamble(env, normalized, { docType: contentType, operation: action });
+    const effective = { ...preamble.args };
+    if (optionalRawText(effective.name) === undefined) {
+        effective.name = basename(filePath, extname(filePath));
+    }
+    const meta = await readFileMetadata(filePath);
+    return {
+        body: buildCreateDocumentBody(effective, contentType),
+        contentType,
+        warnings: droppedFallbackWarnings(preamble),
+        meta,
+    };
+}
+const createOfficeHandler = {
+    targetKeys: ['folder_id', 'author_id', 'file_path'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.create-office';
+        const plan = await planCreateOffice(args, env, action);
+        const lease = await issueWriteLease(env, CREATE_OFFICE_APPLY, args, planLeasePayload(plan));
+        return caizhilianPrepared(action, {
+            ...createPreview(plan.contentType, plan.body),
+            ...filePreview(plan.meta),
+            upload: { path: '/api/file/module/upload', extra_body: { createDoc: 'false' }, deferred_to_apply: true },
+        }, lease, plan.warnings);
+    },
+    async apply(args, env, lease) {
+        const action = CREATE_OFFICE_APPLY;
+        const plan = await planCreateOffice(args, env, 'caizhilian.document.create-office');
+        const meta = plan.meta;
+        assertFileUnchanged(meta, lease, 'file_path');
+        assertPlanUnchanged(lease, plan, action);
+        const uploaded = await uploadFileToServer(env.host, meta.path, {
+            allowedExt: OFFICE_ALLOWED_EXT,
+            extraBody: { createDoc: 'false' },
+            operation: action,
+            preloadedMeta: meta,
+        });
+        plan.body.document.content = String(uploaded.file_id);
+        const data = await executeCreate(env, plan.body, action);
+        return caizhilianSuccess(action, { ...data, file_id: uploaded.file_id }, {
+            content_type: plan.contentType,
+        }, plan.warnings);
+    },
+};
+// ── caizhilian.document.create-by-upload ──────────────────
+/** 源 CreateDocumentByUploadPlugin._normalize_file_paths：兼容字符串/数组，去重保序。 */
+function normalizeFilePaths(raw) {
+    let paths;
+    if (typeof raw === 'string')
+        paths = [raw];
+    else if (Array.isArray(raw))
+        paths = raw;
+    else
+        return [];
+    const seen = new Set();
+    const result = [];
+    for (const item of paths) {
+        const text = item === undefined || item === null ? '' : String(item).trim();
+        if (text && !seen.has(text)) {
+            seen.add(text);
+            result.push(text);
+        }
+    }
+    return result;
+}
+/** 源 CreateDocumentByUploadPlugin.execute 的前置部分（校验 → 前置动作 → 三段 JSON）。 */
+async function planCreateByUpload(args, env, action) {
+    const normalized = normalizeCreateArgs(args, ['file_paths', 'folder_id']);
+    // 源仅校验 folder_type 必填，不校验取值，且创建请求体不使用该字段。
+    normalized.folder_type = requireText(args.folder_type, 'folder_type');
+    const filePaths = normalizeFilePaths(normalized.file_paths);
+    if (!filePaths.length) {
+        throw caizhilianValidationError('list_required', 'file_paths 不能为空');
+    }
+    const authorIdArg = optionalRawText(args.author_id);
+    const preamble = await runCreatePreamble(env, normalized, {
+        needUserInfo: authorIdArg === undefined,
+        includeShareFallback: false,
+        forceQueryShareNew: true,
+        operation: action,
+    });
+    const effective = preamble.args;
+    const authorId = authorIdArg ?? preamble.employeeId ?? '';
+    const properties = {
+        folderId: String(effective.folder_id ?? ''),
+        authorId,
+        publicFormDataId: '',
+        customFormDataId: '',
+        haveVirtualFolder: false,
+        printCount: 0,
+        doccategory: String(optionalRawText(effective.doc_category) ?? 0),
+        isUploadDoc: true,
+        createDocByUpload: true,
+        setCoordinateFlag: false,
+    };
+    if (optionalRawText(effective.keywords) !== undefined)
+        properties.keywords = effective.keywords;
+    if (optionalRawText(effective.auto_invalidate_date) !== undefined) {
+        properties.autoInvalidateDate = effective.auto_invalidate_date;
+    }
+    if (optionalRawText(effective.abstract_text) !== undefined)
+        properties.abstracttext = effective.abstract_text;
+    if (optionalRawText(effective.virtual_folder_ids) !== undefined) {
+        properties.virtualFolderIds = effective.virtual_folder_ids;
+    }
+    if (optionalRawText(effective.tags) !== undefined) {
+        const publicIds = [];
+        const myIds = [];
+        for (const tag of asList(effective.tags)) {
+            if (!tag || typeof tag !== 'object' || Array.isArray(tag))
+                continue;
+            const tagId = String(asRecord(tag).id ?? '');
+            if (!tagId)
+                continue;
+            if (asRecord(tag).privacy)
+                myIds.push(tagId);
+            else
+                publicIds.push(tagId);
+        }
+        if (publicIds.length)
+            properties.publicTagIds = publicIds;
+        if (myIds.length)
+            properties.myTagIds = myIds;
+    }
+    const participants = {
+        entryType: 'user',
+        batchupload: true,
+        module: 'document',
+        createDocByUpload: true,
+        shareType: 'participants',
+        sids: asList(effective.participant_ids).map((pid) => String(pid)).join(','),
+    };
+    const sharers = {
+        departmentIds: '',
+        groupIds: '',
+        subcompanyIds: '',
+        sids: '',
+        map: { canSendMsg: false },
+        module: 'document',
+        shareType: 'sharer',
+        defIds: '',
+        uploadDocAddShareList: [],
+        batchupload: true,
+        isUploadDoc: true,
+        createDocByUpload: true,
+    };
+    const defaultShareNew = asList(effective.folder_default_share_new);
+    if (defaultShareNew.length) {
+        sharers.defIds = defaultShareNew
+            .filter((entry) => asRecord(entry).id !== undefined && asRecord(entry).id !== null)
+            .map((entry) => String(asRecord(entry).id))
+            .join(',');
+    }
+    const folderId = String(effective.folder_id ?? '');
+    const extraBody = {
+        mainlineId: '',
+        folderId,
+        createDocByUpload: 'true',
+        createDocType: 'createContentDoc',
+        properties: JSON.stringify(properties),
+        participants: JSON.stringify(participants),
+        sharers: JSON.stringify(sharers),
+        extraParameters: '{}',
+    };
+    const metas = [];
+    for (const filePath of filePaths)
+        metas.push(await readFileMetadata(filePath));
+    return {
+        filePaths,
+        folderId,
+        authorId,
+        properties,
+        participants,
+        sharers,
+        extraBody,
+        warnings: droppedFallbackWarnings(preamble),
+        metas,
+    };
+}
+function uploadPlanFingerprint(plan) {
+    return fingerprint({
+        folder_id: plan.folderId,
+        author_id: plan.authorId,
+        properties: plan.properties,
+        participants: plan.participants,
+        sharers: plan.sharers,
+    });
+}
+function uploadPlanLeasePayload(plan) {
+    return {
+        folder_id: plan.folderId,
+        author_id: plan.authorId,
+        file_count: plan.metas.length,
+        files: plan.metas.map((meta) => ({ path: meta.path, name: meta.name, size: meta.size, md5: meta.md5 })),
+        plan_fingerprint: uploadPlanFingerprint(plan),
+    };
+}
+function assertUploadPlanUnchanged(lease, plan, action) {
+    const expected = typeof lease.plan_fingerprint === 'string' ? lease.plan_fingerprint : '';
+    if (expected && expected !== uploadPlanFingerprint(plan)) {
+        throw caizhilianValidationError('plan_changed', `${action} 的上传参数与 prepare 时不一致（文件夹默认值或权限可能已变化），请重新执行 prepare`);
+    }
+    const snapshots = asList(lease.files).map((item) => asRecord(item));
+    plan.metas.forEach((meta, index) => {
+        const snapshot = snapshots[index];
+        if (!snapshot)
+            return;
+        assertFileUnchanged(meta, { file_md5: snapshot.md5, file_size: snapshot.size }, `file_paths[${index}]`);
+    });
+}
+/** 源 _upload_one：extra_result_fields=['docId']，返回 doc_id/file_id/name/size/ext_name。 */
+async function uploadOneDocument(env, meta, plan, action) {
+    const uploaded = await uploadFileToServer(env.host, meta.path, {
+        extraBody: plan.extraBody,
+        extraResultFields: ['docId'],
+        operation: action,
+        preloadedMeta: meta,
+    });
+    const docId = uploaded.docId;
+    return {
+        doc_id: docId === undefined || docId === null || docId === 0 || docId === '0' ? '' : String(docId),
+        file_id: uploaded.file_id,
+        name: uploaded.name,
+        size: uploaded.size,
+        ext_name: uploaded.ext_name,
+    };
+}
+function uploadErrorMessage(error) {
+    if (error instanceof Error && error.message)
+        return error.message;
+    return `上传异常: ${String(error)}`;
+}
+const createByUploadHandler = {
+    targetKeys: ['folder_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.create-by-upload';
+        const plan = await planCreateByUpload(args, env, action);
+        const lease = await issueWriteLease(env, CREATE_BY_UPLOAD_APPLY, args, uploadPlanLeasePayload(plan));
+        return caizhilianPrepared(action, {
+            folder_id: plan.folderId,
+            author_id: plan.authorId,
+            file_count: plan.metas.length,
+            files: plan.metas.map((meta) => filePreview(meta)),
+            properties: plan.properties,
+            participants: plan.participants,
+            sharers: plan.sharers,
+            upload: {
+                path: '/api/file/module/upload',
+                extra_result_fields: ['docId'],
+                max_workers: MAX_UPLOAD_WORKERS,
+                deferred_to_apply: true,
+            },
+        }, lease, plan.warnings);
+    },
+    async apply(args, env, lease) {
+        const action = CREATE_BY_UPLOAD_APPLY;
+        const plan = await planCreateByUpload(args, env, 'caizhilian.document.create-by-upload');
+        assertUploadPlanUnchanged(lease, plan, action);
+        if (plan.metas.length === 1) {
+            const data = await uploadOneDocument(env, plan.metas[0], plan, action);
+            return caizhilianSuccess(action, data, { batch: false }, plan.warnings);
+        }
+        const warnings = [...plan.warnings];
+        const results = await mapWithConcurrency(plan.metas, MAX_UPLOAD_WORKERS, async (meta, index) => {
+            try {
+                return await uploadOneDocument(env, meta, plan, action);
+            }
+            catch (error) {
+                const message = uploadErrorMessage(error);
+                warnings.push(`[WARN] 文件上传失败: ${basename(plan.filePaths[index])} -> ${message}`);
+                return { name: basename(plan.filePaths[index]), error: message };
+            }
+        });
+        const successCount = results.filter((item) => item && !('error' in item)).length;
+        const failedCount = results.length - successCount;
+        return caizhilianSuccess(action, { results, summary: { total: results.length, success: successCount, failed: failedCount } }, {
+            batch: true,
+            message: `批量上传完成：共 ${results.length} 个文件，成功 ${successCount} 个，失败 ${failedCount} 个`,
+        }, warnings);
+    },
+};
+// ── caizhilian.document.update-field ──────────────────────
+/** 源 UpdateDocFieldPlugin：field 非法时的文案（sorted(_FIELD_MAP)）。 */
+function assertUpdateField(field) {
+    const text = typeof field === 'string' ? field.trim() : field === undefined || field === null ? '' : String(field);
+    const entry = FIELD_MAP[text];
+    if (!entry) {
+        throw caizhilianValidationError('enum_invalid', `field 必须为 ${FIELD_MAP_KEYS_SORTED.join(', ')} 之一，收到: '${text}'`);
+    }
+    return { field: text, filed: entry.filed, argKey: entry.argKey, allowEmpty: entry.allowEmpty };
+}
+/**
+ * 取值语义：CLI 契约用 `value`；源读 `args[arg_key]`，因此 value 缺省时回落到同名字段
+ * （见待验证项：源与契约字段名不一致）。
+ */
+function resolveFieldValue(args, argKey) {
+    if (args.value !== undefined && args.value !== null)
+        return args.value;
+    if (args[argKey] !== undefined && args[argKey] !== null)
+        return args[argKey];
+    return '';
+}
+/** fetch_doc_base_info_by_docid 模板中可读回的当前值字段（autoInvalidateDate 不在模板内）。 */
+const CURRENT_VALUE_FIELD = {
+    name: 'docName',
+    keywords: 'keywords',
+    abstract: 'abstractText',
+};
+const updateFieldHandler = {
+    targetKeys: ['doc_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.update-field';
+        const field = assertUpdateField(args.field);
+        const docId = requireId(args.doc_id, 'doc_id');
+        const value = resolveFieldValue(args, field.argKey);
+        if (!field.allowEmpty && !String(value ?? '').trim()) {
+            throw caizhilianValidationError('field_empty', `${field.argKey} 不能为空字符串`);
+        }
+        const info = await fetchDocBaseInfo(env, docId, action);
+        const currentKey = CURRENT_VALUE_FIELD[field.field];
+        const lease = await issueWriteLease(env, UPDATE_FIELD_APPLY, args, {
+            doc_id: docId,
+            field: field.field,
+            filed: field.filed,
+            value_fingerprint: fingerprint(value ?? ''),
+        });
+        return caizhilianPrepared(action, {
+            doc_id: docId,
+            doc_name: info.docName ?? null,
+            field: field.field,
+            filed: field.filed,
+            arg_key: field.argKey,
+            allow_empty: field.allowEmpty,
+            value: value ?? '',
+            current_value: currentKey ? (info[currentKey] ?? null) : null,
+            request: { method: 'POST', path: `/api/doc/document/update/${encodeURIComponent(docId)}` },
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = UPDATE_FIELD_APPLY;
+        const field = assertUpdateField(args.field);
+        const docId = requireId(args.doc_id, 'doc_id');
+        const value = resolveFieldValue(args, field.argKey);
+        const expected = typeof lease.value_fingerprint === 'string' ? lease.value_fingerprint : '';
+        if (expected && expected !== fingerprint(value ?? '')) {
+            throw caizhilianValidationError('plan_changed', `${action} 的目标值与 prepare 时不一致，请重新执行 prepare`);
+        }
+        const data = await updateDocBasicField(env, { docId, filed: field.filed, argKey: field.argKey, docField: field.filed, allowEmpty: field.allowEmpty, value }, action);
+        return caizhilianSuccess(action, data);
+    },
+};
+// ── caizhilian.document.update-author ─────────────────────
+const updateAuthorHandler = {
+    targetKeys: ['doc_id', 'user_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.update-author';
+        const docId = requireId(args.doc_id, 'doc_id');
+        const userId = requireText(args.user_id, 'user_id');
+        const info = await fetchDocBaseInfo(env, docId, action);
+        const lease = await issueWriteLease(env, UPDATE_AUTHOR_APPLY, args, { doc_id: docId, user_id: userId });
+        return caizhilianPrepared(action, {
+            doc_id: docId,
+            doc_name: info.docName ?? null,
+            user_id: userId,
+            current_author_id: info.authorId ?? null,
+            current_author_name: info.authorName ?? null,
+            request: {
+                method: 'POST',
+                path: `/api/doc/document/updateAuthor/${encodeURIComponent(docId)}/${encodeURIComponent(userId)}`,
+            },
+        }, lease);
+    },
+    async apply(args, env) {
+        const action = UPDATE_AUTHOR_APPLY;
+        const docId = requireId(args.doc_id, 'doc_id');
+        const userId = requireText(args.user_id, 'user_id');
+        await env.host.request({
+            method: 'POST',
+            path: `/api/doc/document/updateAuthor/${encodeURIComponent(docId)}/${encodeURIComponent(userId)}`,
+            operation: action,
+        });
+        return caizhilianSuccess(action, { doc_id: docId, user_id: userId });
+    },
+};
+// ── caizhilian.document.update-html ───────────────────────
+/** 源 update_doc_html_content 的请求体（filed 拼写沿用源）。 */
+function buildUpdateHtmlBody(docId, summary) {
+    return {
+        id: docId,
+        filed: 'summary',
+        document: { summary, shareOut: false },
+        operateType: 'saveSummary',
+        operation: 'save',
+        createNewVersion: true,
+    };
+}
+function requireSummary(args) {
+    const summary = optionalRawText(args.summary);
+    if (summary === undefined)
+        throw caizhilianValidationError('field_required', '缺少必填参数: summary');
+    return summary;
+}
+const updateHtmlHandler = {
+    targetKeys: ['doc_id'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.update-html';
+        const docId = requireId(args.doc_id, 'doc_id');
+        const summary = requireSummary(args);
+        const info = await fetchDocBaseInfo(env, docId, action);
+        const lease = await issueWriteLease(env, UPDATE_HTML_APPLY, args, {
+            doc_id: docId,
+            summary_length: summary.length,
+            summary_fingerprint: fingerprint(summary),
+        });
+        return caizhilianPrepared(action, {
+            doc_id: docId,
+            doc_name: info.docName ?? null,
+            content_type: info.contentType ?? null,
+            summary_length: summary.length,
+            current_summary_length: typeof info.summary === 'string' ? info.summary.length : 0,
+            create_new_version: true,
+            request: { method: 'POST', path: `/api/doc/document/update/${encodeURIComponent(docId)}` },
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = UPDATE_HTML_APPLY;
+        const docId = requireId(args.doc_id, 'doc_id');
+        const summary = requireSummary(args);
+        const expected = typeof lease.summary_fingerprint === 'string' ? lease.summary_fingerprint : '';
+        if (expected && expected !== fingerprint(summary)) {
+            throw caizhilianValidationError('plan_changed', `${action} 的正文与 prepare 时不一致，请重新执行 prepare`);
+        }
+        await env.host.request({
+            method: 'POST',
+            path: `/api/doc/document/update/${encodeURIComponent(docId)}`,
+            body: buildUpdateHtmlBody(docId, summary),
+            operation: action,
+        });
+        return caizhilianSuccess(action, { doc_id: docId, summary });
+    },
+};
+// ── caizhilian.document.replace-content ───────────────────
+const REPLACE_UPLOAD_PATH = '/api/file/reUpload';
+const REPLACE_NOTIFY_PATH = '/api/doc/document/afterReplaceDocumentContent';
+/** 源 int(old_file_id) 的可解析判定。 */
+function isIntLike(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'string')
+        return false;
+    return /^\s*[-+]?\d+\s*$/.test(value);
+}
+/** 源 coordinate == 1 的判定（数字 1 / true 命中；字符串 '1' 不命中）。 */
+function isCooperative(value) {
+    return (typeof value === 'number' && value === 1) || value === true;
+}
+/** 源 ReplaceDocumentContentPlugin 的三步中的前两步（只读回查 + 校验）。 */
+async function planReplaceContent(args, env, action) {
+    const docId = requireText(args.doc_id, 'doc_id');
+    const meta = await readFileMetadata(args.file_path);
+    let info;
+    try {
+        info = await fetchDocBaseInfo(env, docId, action);
+    }
+    catch (error) {
+        // 「文档不存在」的明确提示直接透传，不要被下面的泛化文案覆盖。
+        if (error instanceof CaizhilianCliError && error.subtype === 'doc_not_found')
+            throw error;
+        throw caizhilianValidationError('doc_info_unavailable', `获取文档信息失败: ${error instanceof Error && error.message ? error.message : String(error)}`);
+    }
+    const oldFileId = info.content;
+    const contentType = info.contentType === undefined ? '' : info.contentType;
+    const permission = asRecord(info.permission);
+    if (isCooperative(info.coordinate)) {
+        throw caizhilianValidationError('coordinate_not_supported', '协同文档不支持替换正文，此功能仅适用于文件型正文的文档');
+    }
+    if (!permission.replaceMainText) {
+        throw caizhilianValidationError('permission_denied', '当前无替换正文权限，请联系文档负责人或管理员确认权限设置');
+    }
+    if (oldFileId === undefined || oldFileId === null || oldFileId === '' || oldFileId === 0) {
+        throw caizhilianValidationError('content_missing', '该文档当前没有正文文件，无法执行替换操作');
+    }
+    if (!isIntLike(oldFileId)) {
+        throw caizhilianValidationError('content_id_invalid', `正文文件ID无效: ${String(oldFileId)}`);
+    }
+    const typeText = typeof contentType === 'string' ? contentType : String(contentType ?? '');
+    let allowedExts;
+    if (CONTENT_TYPE_EXT_MAP[typeText])
+        allowedExts = CONTENT_TYPE_EXT_MAP[typeText];
+    else if (typeText.trim())
+        allowedExts = [`.${typeText.trim().toLowerCase()}`];
+    else
+        throw caizhilianValidationError('content_type_unknown', '文件格式无法识别：文档正文类型为空或未知');
+    const ext = extname(meta.name).toLowerCase();
+    if (!allowedExts.includes(ext)) {
+        throw caizhilianValidationError('file_type_mismatch', `文件格式不匹配：文档正文类型为 ${typeText}，不支持 ${ext} 格式`);
+    }
+    return {
+        docId,
+        docName: typeof info.docName === 'string' ? info.docName : null,
+        contentType,
+        oldFileId: String(oldFileId),
+        allowedExts,
+        meta,
+    };
+}
+const replaceContentHandler = {
+    targetKeys: ['doc_id', 'file_path'],
+    async prepare(args, env) {
+        const action = 'caizhilian.document.replace-content';
+        const plan = await planReplaceContent(args, env, action);
+        const lease = await issueWriteLease(env, REPLACE_CONTENT_APPLY, args, {
+            doc_id: plan.docId,
+            old_file_id: plan.oldFileId,
+            content_type: plan.contentType,
+            file_path: plan.meta.path,
+            file_md5: plan.meta.md5,
+            file_size: plan.meta.size,
+        });
+        return caizhilianPrepared(action, {
+            doc_id: plan.docId,
+            doc_name: plan.docName,
+            content_type: plan.contentType,
+            old_file_id: plan.oldFileId,
+            allowed_exts: plan.allowedExts,
+            ...filePreview(plan.meta),
+            upload: {
+                path: REPLACE_UPLOAD_PATH,
+                extra_body: { authModule: 'document', oldFileId: plan.oldFileId, employeePartTimeId: '' },
+                required_permission: 'reupload',
+                extra_result_fields: ['version'],
+                deferred_to_apply: true,
+            },
+            notify: { method: 'POST', path: REPLACE_NOTIFY_PATH, body: { docId: plan.docId }, failure_is_warning: true },
+        }, lease);
+    },
+    async apply(args, env, lease) {
+        const action = REPLACE_CONTENT_APPLY;
+        const plan = await planReplaceContent(args, env, 'caizhilian.document.replace-content');
+        assertFileUnchanged(plan.meta, lease, 'file_path');
+        if (typeof lease.old_file_id === 'string' && lease.old_file_id && lease.old_file_id !== plan.oldFileId) {
+            throw caizhilianValidationError('plan_changed', `${action} 的正文文件 ID 与 prepare 时不一致（正文可能已被他人替换），请重新执行 prepare`);
+        }
+        const uploaded = await uploadFileToServer(env.host, plan.meta.path, {
+            extraBody: { authModule: 'document', oldFileId: plan.oldFileId, employeePartTimeId: '' },
+            uploadPath: REPLACE_UPLOAD_PATH,
+            requiredPermission: 'reupload',
+            permissionDeniedMessage: '无替换正文上传权限',
+            extraResultFields: ['version'],
+            operation: action,
+            preloadedMeta: plan.meta,
+        });
+        const warnings = [];
+        try {
+            await env.host.request({
+                method: 'POST',
+                path: REPLACE_NOTIFY_PATH,
+                body: { docId: plan.docId },
+                operation: action,
+            });
+        }
+        catch (error) {
+            warnings.push(`[WARN] 替换完成通知发送失败: ${uploadErrorMessage(error)}`);
+        }
+        return caizhilianSuccess(action, uploaded, { doc_id: plan.docId, content_type: plan.contentType }, warnings);
+    },
+};
+// ── 处理器汇总 ────────────────────────────────────────────
+export const caizhilianDocumentHandlers = {
+    'caizhilian.document.get': { execute: getDocument },
+    'caizhilian.user.current': { execute: currentUser },
+    'caizhilian.document.create-html': createHtmlHandler,
+    'caizhilian.document.create-markdown': createMarkdownHandler,
+    'caizhilian.document.create-office': createOfficeHandler,
+    'caizhilian.document.create-by-upload': createByUploadHandler,
+    'caizhilian.document.update-field': updateFieldHandler,
+    'caizhilian.document.update-author': updateAuthorHandler,
+    'caizhilian.document.update-html': updateHtmlHandler,
+    'caizhilian.document.replace-content': replaceContentHandler,
+};