weaver-work-cli 0.1.8 → 0.1.20

package/dist/shortcuts/caizhilian/operations/api.js

@@ -0,0 +1,801 @@
+import { CaizhilianCliError, caizhilianValidationError } from '../errors.js';
+import { caizhilianBusinessMessage, isCaizhilianBusinessSuccess } from '../host.js';
+import { timestampToDateStr } from './shared.js';
+/**
+ * 采知连领域 API 组合层：1:1 移植源 Skill `scripts/_plugin_helpers.py` 与
+ * `scripts/response_templates.py` 中与业务合约相关的部分
+ * （权限校验、文件夹默认值兜底、共享条目解析、文档创建请求体组装、
+ * 文档基础字段更新、文档详情响应模板）。
+ *
+ * 与源的唯一系统性差异是错误传递方式：源用 `(data, err)` 元组回传 PluginOutput，
+ * CLI 侧统一抛 CaizhilianCliError，并保留源的 message 文案与 error_type。
+ */
+export function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+export function asList(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** 源 get_nested_value(data, "a.b") 的对象版本：路径不存在或类型不符时返回 {}。 */
+export function nestedRecord(value, ...keys) {
+    let current = value;
+    for (const key of keys) {
+        if (!current || typeof current !== 'object' || Array.isArray(current))
+            return {};
+        current = current[key];
+    }
+    return asRecord(current);
+}
+/** 源 get_nested_value(data, "data.list") 的列表版本：取不到时返回 []。 */
+export function nestedList(value, ...keys) {
+    let current = value;
+    for (const key of keys) {
+        if (!current || typeof current !== 'object')
+            return [];
+        current = current[key];
+    }
+    return asList(current);
+}
+/** 源「权限校验请求失败」分支：error_type=permission_check_failed + 固定文案。 */
+function permissionCheckFailedError(message, details, cause) {
+    return caizhilianValidationError('permission_check_failed', message, {
+        error_type: 'permission_check_failed',
+        ...details,
+        cause: cause instanceof Error ? cause.message : String(cause),
+    });
+}
+// ── fetch_doc_base_info_by_docid（响应模板 FetchDocBaseInfoByDocid）──────────
+/** 源 response_templates.PERMISSION_FIELDS（18 项白名单）。 */
+export const DOC_PERMISSION_FIELDS = [
+    'withEditPermission',
+    'canEditTitle',
+    'canEditContent',
+    'canDelete',
+    'watched',
+    'canDownload',
+    'maxSize',
+    'canUploadFile',
+    'canMove',
+    'canQuote',
+    'canEditPrimary',
+    'canSaveAsDraft',
+    'canEditSharer',
+    'canSubmit',
+    'canPublish',
+    'canFile',
+    'canCancel',
+    'canWatch',
+];
+/** 源 response_templates.PARENT_FOLDER_FIELDS。 */
+export const PARENT_FOLDER_FIELDS = ['id', 'name', 'type', 'namePath'];
+/** 源 response_templates.ATTACHMENT_FIELDS。 */
+export const ATTACHMENT_FIELDS = ['id', 'name', 'createTime', 'extName', 'size'];
+/** 源 response_templates.OMS_KEEP_FIELDS。 */
+export const OMS_KEEP_FIELDS = ['operateMenu', 'operateMenuId'];
+/** 源 OMS_FILTER_SHOW / OMS_FILTER_OPEN_STATUS。 */
+export const OMS_FILTER_SHOW = true;
+export const OMS_FILTER_OPEN_STATUS = 1;
+function pickPresent(source, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (key in source)
+            result[key] = source[key];
+    }
+    return result;
+}
+function omsVisible(item) {
+    const record = asRecord(item);
+    return record.show === OMS_FILTER_SHOW && record.openStatus === OMS_FILTER_OPEN_STATUS;
+}
+/**
+ * GET /api/doc/document/queryInfo?docId&splitInfo=1 + FetchDocBaseInfoByDocid 模板。
+ * 供 caizhilian.document.get 直接使用，也被 replace_document_content / 文档字段修改的
+ * prepare 阶段当作只读回查复用（源 replace_document_content 走 engine.execute 复用同一模板）。
+ */
+export async function fetchDocBaseInfo(env, docId, operation) {
+    const response = await env.host.request({
+        method: 'GET',
+        path: '/api/doc/document/queryInfo',
+        query: { docId, splitInfo: '1' },
+        operation,
+    });
+    const apiData = nestedRecord(response, 'data');
+    const doc = asRecord(apiData.document);
+    // 服务端对不存在的文档返回空对象：核心标识（名称/ID）都缺失即判定为文档不存在。
+    if (!doc.name && !doc.id) {
+        throw caizhilianValidationError('doc_not_found', `文档不存在或已被删除（文档 ID: ${docId}）`);
+    }
+    const result = {};
+    // 1. 文档基础字段
+    const author = asRecord(doc.author);
+    const creator = asRecord(doc.creator);
+    result.docName = doc.name ?? null;
+    result.abstractText = doc.abstractText ?? null;
+    result.authorId = author.id ?? null;
+    result.authorName = author.username ?? null;
+    result.creatorId = creator.id ?? null;
+    result.creatorName = creator.username ?? null;
+    result.docStatus = doc.docStatus ?? null;
+    result.keywords = doc.keywords ?? null;
+    result.summary = doc.summary ?? null;
+    result.createTime = timestampToDateStr(doc.createTime);
+    result.lastUpdateTime = timestampToDateStr(doc.lastUpdateTime);
+    result.contentMainType = doc.contentMainType ?? null;
+    result.content = doc.content ?? null;
+    result.contentType = doc.contentType ?? null;
+    result.coordinate = doc.coordinate ?? null;
+    // 2. 父文件夹列表（仅保留 id/name/type/namePath）
+    result.parentFolders = asList(doc.parentFolders)
+        .filter((item) => !!item && typeof item === 'object' && !Array.isArray(item))
+        .map((item) => pickPresent(asRecord(item), PARENT_FOLDER_FIELDS));
+    // 3. 文档权限标志（18 字段白名单）
+    const docPermission = asRecord(apiData.documentPermission);
+    const permission = {};
+    for (const key of DOC_PERMISSION_FIELDS) {
+        if (key in docPermission)
+            permission[key] = docPermission[key];
+    }
+    // 4. 附件列表（仅保留 id/name/createTime/extName/size）
+    result.attachments = asList(doc.attachments)
+        .filter((item) => !!item && typeof item === 'object' && !Array.isArray(item))
+        .map((item) => pickPresent(asRecord(item), ATTACHMENT_FIELDS));
+    // 5. operateMenuSettings：show===true 且 openStatus===1，仅保留 operateMenu/operateMenuId
+    const oms = asList(apiData.operateMenuSettings);
+    result.operateMenuSettings = oms
+        .filter((item) => !!item && typeof item === 'object' && !Array.isArray(item))
+        .filter(omsVisible)
+        .map((item) => pickPresent(asRecord(item), OMS_KEEP_FIELDS));
+    // 6. 派生 replaceMainText 权限
+    permission.replaceMainText = oms.some((item) => omsVisible(item) && asRecord(item).operateMenuId === 'replaceMainText');
+    result.permission = permission;
+    return result;
+}
+// ── 当前登录人（源 fetch_current_user_info / fetch_current_user_info_cached）──
+/** GET /api/doc/common/userInfo，返回原始响应体（源缓存版返回的也是原始响应体）。 */
+export async function fetchCurrentUserInfoRaw(env, operation) {
+    return env.host.request({ method: 'GET', path: '/api/doc/common/userInfo', operation });
+}
+/** caizhilian.user.current 的输出：employeeId / employeeName。 */
+export async function fetchCurrentUserInfo(env, operation) {
+    const response = await fetchCurrentUserInfoRaw(env, operation);
+    const employee = nestedRecord(response, 'data', 'employee');
+    return {
+        employeeId: employee.id === undefined || employee.id === null ? '' : String(employee.id),
+        employeeName: employee.name === undefined || employee.name === null ? '' : String(employee.name),
+    };
+}
+// ── 权限校验（源 fetch_folder_permissions / check_*）────────────────────────
+/**
+ * POST /api/doc/folderpermission/querySpecifiedPermission。
+ * 返回 { [folderId]: { <field>: boolean, allowDocumentCreateTypes?: string[] } }。
+ */
+export async function fetchFolderPermissions(env, folderIds, permissionFields, operation) {
+    const fields = [...(permissionFields ?? [])];
+    if (!fields.length) {
+        throw caizhilianValidationError('permission_fields_required', '权限查询字段列表不能为空');
+    }
+    const ids = folderIds.map((item) => String(item));
+    const response = await env.host.request({
+        method: 'POST',
+        path: '/api/doc/folderpermission/querySpecifiedPermission',
+        query: { folderIdStr: ids.join(','), typeStr: fields.join(',') },
+        operation,
+    });
+    const resultMap = asRecord(nestedRecord(response, 'data').resultMap);
+    const permissionsMap = {};
+    for (const folderId of ids) {
+        const rawPerms = asRecord(resultMap[folderId]);
+        const perms = {};
+        for (const field of fields) {
+            if (field === 'documentCreateSetting') {
+                perms.allowDocumentCreateTypes = asList(asRecord(rawPerms.documentCreateSetting).allowDocumentCreateTypes);
+            }
+            else {
+                perms[field] = rawPerms[field] ?? false;
+            }
+        }
+        permissionsMap[folderId] = perms;
+    }
+    return permissionsMap;
+}
+function folderIdText(value) {
+    return value === undefined || value === null ? '' : String(value).trim();
+}
+/** 源 check_create_document_permission：isCreateDoc + 允许创建的文档类型。 */
+export async function checkCreateDocumentPermission(env, folderId, docType, operation) {
+    const id = folderIdText(folderId);
+    if (!id)
+        return;
+    let perms;
+    try {
+        const map = await fetchFolderPermissions(env, [id], ['isCreateDoc', 'documentCreateSetting'], operation);
+        perms = map[id] ?? {};
+    }
+    catch (error) {
+        throw permissionCheckFailedError('无法校验文件夹权限，请稍后重试', { folder_id: id }, error);
+    }
+    if (!perms.isCreateDoc) {
+        throw caizhilianValidationError('folder_no_create_permission', '该文件夹没有新建文档权限', {
+            error_type: 'folder_no_create_permission',
+            folder_id: id,
+        });
+    }
+    if (docType) {
+        const allowedTypes = asList(perms.allowDocumentCreateTypes);
+        const matched = allowedTypes.some((item) => typeof item === 'string' && item.toLowerCase() === docType.toLowerCase());
+        if (allowedTypes.length && !matched) {
+            throw caizhilianValidationError('doc_type_not_allowed', `该文件夹不支持创建 ${docType} 类型文档，支持的类型：${allowedTypes.map((item) => String(item)).join(', ')}`, { error_type: 'doc_type_not_allowed', requested_type: docType, allowed_types: allowedTypes });
+        }
+    }
+}
+/** 源 check_create_folder_permission：isCreateFolder。 */
+export async function checkCreateFolderPermission(env, folderId, operation) {
+    const id = folderIdText(folderId);
+    if (!id)
+        return;
+    let perms;
+    try {
+        const map = await fetchFolderPermissions(env, [id], ['isCreateFolder'], operation);
+        perms = map[id] ?? {};
+    }
+    catch (error) {
+        throw permissionCheckFailedError('无法校验文件夹权限，请稍后重试', { folder_id: id }, error);
+    }
+    if (!perms.isCreateFolder) {
+        throw caizhilianValidationError('folder_no_create_folder_permission', '该文件夹没有新建文件夹权限', {
+            error_type: 'folder_no_create_folder_permission',
+            folder_id: id,
+        });
+    }
+}
+/** 源 check_set_folder_permission：isSetting。 */
+export async function checkSetFolderPermission(env, folderId, operation) {
+    const id = folderIdText(folderId);
+    if (!id)
+        return;
+    let perms;
+    try {
+        const map = await fetchFolderPermissions(env, [id], ['isSetting'], operation);
+        perms = map[id] ?? {};
+    }
+    catch (error) {
+        throw permissionCheckFailedError('无法校验文件夹权限，请稍后重试', { folder_id: id }, error);
+    }
+    if (!perms.isSetting) {
+        throw caizhilianValidationError('folder_no_set_default_share_permission', '该文件夹没有设置默认共享权限', {
+            error_type: 'folder_no_set_default_share_permission',
+            folder_id: id,
+        });
+    }
+}
+/** 源 check_doc_share_add_permission：shareentry/list 的 addVisible。 */
+export async function checkDocShareAddPermission(env, docId, operation) {
+    const id = folderIdText(docId);
+    if (!id)
+        return;
+    let inner;
+    try {
+        const response = await env.host.request({
+            method: 'GET',
+            path: '/api/doc/shareentry/list',
+            query: { sourceId: id, permissionId: 'doc_s01', sourceType: '1', docId: id },
+            operation,
+        });
+        inner = nestedRecord(response, 'data');
+    }
+    catch (error) {
+        throw permissionCheckFailedError('无法校验文档共享权限，请稍后重试', { doc_id: id }, error);
+    }
+    if (!inner.addVisible) {
+        throw caizhilianValidationError('doc_no_add_share_permission', '该文档没有添加共享权限', {
+            error_type: 'doc_no_add_share_permission',
+            doc_id: id,
+        });
+    }
+}
+// ── 文件夹默认值兜底（源 apply_folder_default_fallbacks）───────────────────
+/** 源 _plugin_helpers.FOLDER_DEFAULT_FALLBACK_MAP。 */
+export const FOLDER_DEFAULT_FALLBACK_MAP = [
+    { param: 'virtual_folder_ids', source: 'defaultVirtualFolder', field: 'id' },
+    { param: 'participant_ids', source: 'folderDefaultParticipants', field: 'id' },
+];
+/** 源 _plugin_helpers.FOLDER_DEFAULT_SETTINGS_TYPE。 */
+export const FOLDER_DEFAULT_SETTINGS_TYPE = 'folderDefaultShare,folderDefaultParticipants,defaultVirtualFolder';
+/**
+ * 用文件夹默认设置补齐未传参数（participant_ids / virtual_folder_ids），
+ * 并附带 folder_default_share_new（去 avatar）。
+ * 源语义：查询失败静默返回原参数副本，不阻断创建流程。
+ */
+export async function applyFolderDefaultFallbacks(env, args, operation) {
+    const result = { ...args };
+    const forceQueryShareNew = Boolean(args.force_query_folder_default_share_new);
+    const missing = FOLDER_DEFAULT_FALLBACK_MAP.filter((item) => !args[item.param]).map((item) => item.param);
+    if (!missing.length && !forceQueryShareNew)
+        return result;
+    const folderId = folderIdText(args.folder_id);
+    if (!folderId)
+        return result;
+    let dataSection;
+    try {
+        const response = await env.host.request({
+            method: 'POST',
+            path: '/api/doc/folderSetting/getFolderSettings',
+            body: { id: folderId, type: FOLDER_DEFAULT_SETTINGS_TYPE },
+            operation,
+        });
+        dataSection = nestedRecord(response, 'data');
+    }
+    catch {
+        return result;
+    }
+    for (const item of FOLDER_DEFAULT_FALLBACK_MAP) {
+        if (!missing.includes(item.param))
+            continue;
+        const entries = dataSection[item.source];
+        if (!Array.isArray(entries))
+            continue;
+        const values = entries
+            .filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry))
+            .map((entry) => asRecord(entry)[item.field])
+            .filter((value) => value !== undefined && value !== null)
+            .map((value) => String(value));
+        if (values.length)
+            result[item.param] = values;
+    }
+    const shareNew = dataSection.folderDefaultShareNew;
+    if (Array.isArray(shareNew)) {
+        const cleaned = shareNew
+            .filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry))
+            .map((entry) => {
+            const copy = { ...asRecord(entry) };
+            delete copy.avatar;
+            return copy;
+        });
+        if (cleaned.length)
+            result.folder_default_share_new = cleaned;
+    }
+    return result;
+}
+/**
+ * 查询目标文件夹的文档默认共享，用于新建文档请求体的 docShareList（源 apply_doc_share_fallback）。
+ * 直接取原始条目（仅去掉 objectAction），因为创建接口需要原始格式；查询失败静默。
+ */
+export async function applyDocShareFallback(env, args, operation) {
+    const result = { ...args };
+    const folderId = folderIdText(args.folder_id);
+    if (!folderId)
+        return result;
+    let entries;
+    try {
+        const response = await env.host.request({
+            method: 'GET',
+            path: '/api/doc/shareentry/list',
+            query: { folderId },
+            operation,
+        });
+        entries = nestedRecord(response, 'data').data;
+    }
+    catch {
+        return result;
+    }
+    if (!Array.isArray(entries))
+        return result;
+    const shares = entries
+        .filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry))
+        .map((entry) => {
+        const copy = { ...asRecord(entry) };
+        delete copy.objectAction;
+        return copy;
+    });
+    if (shares.length)
+        result.doc_share_list = shares;
+    return result;
+}
+/**
+ * 并发执行文档创建前置：权限校验（失败即错）+ 当前用户信息（可选）+ 文件夹默认值兜底 + 默认共享兜底。
+ *
+ * ⚠️ 1:1 保留源行为：当 includeShareFallback=true 时，`new_args` 取「共享兜底」的返回值，
+ * 「文件夹默认值兜底」的结果被丢弃（源 _plugin_helpers.run_create_preamble 的覆盖写法），
+ * 因此 create-html / create-markdown / create-office 实际不会回填 participant_ids /
+ * virtual_folder_ids；只有 create-by-upload（includeShareFallback=false）会生效。
+ */
+export async function runCreatePreamble(env, args, options) {
+    const includeShareFallback = options.includeShareFallback ?? true;
+    const folderId = folderIdText(args.folder_id);
+    const fallbackArgs = { ...args };
+    if (options.forceQueryShareNew)
+        fallbackArgs.force_query_folder_default_share_new = true;
+    const tasks = [
+        checkCreateDocumentPermission(env, folderId, options.docType, options.operation),
+    ];
+    if (options.needUserInfo)
+        tasks.push(fetchCurrentUserInfoRaw(env, options.operation));
+    tasks.push(applyFolderDefaultFallbacks(env, fallbackArgs, options.operation));
+    if (includeShareFallback)
+        tasks.push(applyDocShareFallback(env, fallbackArgs, options.operation));
+    const settled = await Promise.allSettled(tasks);
+    let index = 0;
+    const permission = settled[index];
+    index += 1;
+    if (permission.status === 'rejected')
+        throw permission.reason;
+    let employeeId;
+    if (options.needUserInfo) {
+        const user = settled[index];
+        index += 1;
+        if (user.status === 'rejected')
+            throw user.reason;
+        employeeId = String(nestedRecord(user.value, 'data', 'employee').id ?? '');
+    }
+    const folderFallback = settled[index];
+    index += 1;
+    if (folderFallback.status === 'rejected')
+        throw folderFallback.reason;
+    const folderFallbackArgs = folderFallback.value;
+    let newArgs = folderFallbackArgs;
+    if (includeShareFallback) {
+        const shareFallback = settled[index];
+        index += 1;
+        if (shareFallback.status === 'rejected')
+            throw shareFallback.reason;
+        // ⚠️ 源行为：共享兜底结果覆盖文件夹兜底结果。
+        newArgs = shareFallback.value;
+    }
+    if (options.needUserInfo && !employeeId) {
+        throw caizhilianValidationError('user_info_unavailable', '未传 author_id 且无法获取当前用户信息');
+    }
+    return { args: newArgs, employeeId, folderFallbackArgs };
+}
+// ── 文档创建请求体（源 build_create_document_body）─────────────────────────
+/** 组装 POST /api/doc/document/createDetail 请求体。 */
+export function buildCreateDocumentBody(args, contentType) {
+    const document = {
+        contentType,
+        name: args.name,
+        author: { id: String(args.author_id) },
+        docStatusName: '草稿',
+        employeePartTimeId: '',
+    };
+    if (args.summary)
+        document.summary = args.summary;
+    if (args.abstract_text)
+        document.abstractText = args.abstract_text;
+    if (args.keywords)
+        document.keywords = args.keywords;
+    if (args.auto_invalidate_date)
+        document.autoInvalidateDate = args.auto_invalidate_date;
+    if (args.cover_picture_id)
+        document.coverPictureId = String(args.cover_picture_id);
+    if (args.doc_category !== undefined && args.doc_category !== null) {
+        const parsed = Number(args.doc_category);
+        if (!Number.isInteger(parsed)) {
+            throw caizhilianValidationError('doc_category_invalid', 'doc_category 必须是整数');
+        }
+        document.docCategory = parsed;
+    }
+    if (args.tags)
+        document.tags = args.tags;
+    if (args.virtual_folder_ids) {
+        document.virtualFolders = asList(args.virtual_folder_ids).map((id) => ({ id: String(id) }));
+    }
+    const body = {
+        document,
+        operateType: 'save',
+        folderId: String(args.folder_id),
+        folderType: String(args.folder_type),
+        mainlineId: '',
+        moduleFolderId: '',
+        effectiveContent: true,
+    };
+    if (args.participant_ids) {
+        body.shareList = asList(args.participant_ids).map((pid) => ({
+            entryType: 'user',
+            granting: true,
+            mask: 3,
+            shareType: 'participants',
+            sid: String(pid),
+        }));
+    }
+    if (args.doc_share_list)
+        body.docShareList = args.doc_share_list;
+    return body;
+}
+/** POST /api/doc/document/update/{docId}，返回 { doc_id, [argKey]: value }。 */
+export async function updateDocBasicField(env, input, operation) {
+    const docId = folderIdText(input.docId);
+    if (!docId)
+        throw caizhilianValidationError('field_required', '缺少必填参数: doc_id');
+    const raw = input.fixedValue !== undefined ? input.fixedValue : input.value ?? '';
+    const value = raw === null || raw === undefined ? '' : raw;
+    if (!input.allowEmpty && !String(value).trim()) {
+        throw caizhilianValidationError('field_empty', `${input.argKey} 不能为空字符串`);
+    }
+    await env.host.request({
+        method: 'POST',
+        path: `/api/doc/document/update/${encodeURIComponent(docId)}`,
+        body: { id: docId, filed: input.filed, document: { [input.docField]: value, shareOut: false } },
+        operation,
+    });
+    return { doc_id: docId, [input.argKey]: value };
+}
+/** 源 object_name 提取顺序：objectAction → fullObject → objectOnly → object。 */
+function shareObjectName(item) {
+    let objectName = '';
+    const objectAction = item.objectAction;
+    if (Array.isArray(objectAction)) {
+        const parts = [];
+        for (const entry of objectAction) {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                continue;
+            const nameValue = asRecord(entry).name;
+            if (nameValue && typeof nameValue === 'object' && !Array.isArray(nameValue)) {
+                const part = asRecord(nameValue).linkName || asRecord(nameValue).name || '';
+                if (part)
+                    parts.push(String(part));
+            }
+            else if (typeof nameValue === 'string' && nameValue) {
+                parts.push(nameValue);
+            }
+        }
+        objectName = parts.join('');
+    }
+    else if (objectAction && typeof objectAction === 'object') {
+        const names = asRecord(objectAction).name || asRecord(objectAction).names || [];
+        objectName = Array.isArray(names) ? names.map((name) => String(name)).join(', ') : String(names);
+    }
+    if (!objectName) {
+        objectName = String(item.fullObject ?? '') || String(item.objectOnly ?? '') || String(item.object ?? '') || '';
+    }
+    return objectName;
+}
+/**
+ * 解析共享条目列表（文档共享 / 文件夹默认共享 / 文件夹权限设置共用）。
+ * can_delete = operates 中 id=='delete' && visible 的索引 → operatesPermission[idx][deleteIdx].visible。
+ */
+export function parseShareItems(items, operates, operatesPermission, options = {}) {
+    let deleteOpIndex = null;
+    if (options.includeCanDelete) {
+        for (let i = 0; i < operates.length; i += 1) {
+            const op = asRecord(operates[i]);
+            if (operates[i] && typeof operates[i] === 'object' && op.id === 'delete' && op.visible) {
+                deleteOpIndex = i;
+                break;
+            }
+        }
+    }
+    const shares = [];
+    for (let idx = 0; idx < items.length; idx += 1) {
+        const raw = items[idx];
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const item = asRecord(raw);
+        const secLevel = item.secLevel;
+        const share = {
+            id: String(item.id ?? ''),
+            object_type: item.objectType ?? '',
+            object_name: shareObjectName(item),
+            share_level: item.shareLevel ?? '',
+            sec_level: secLevel !== undefined && secLevel !== null && secLevel !== '' ? secLevel : '--',
+        };
+        if (options.includeDownload)
+            share.download = item.download ?? '';
+        if (options.includeCanDelete) {
+            let canDelete = false;
+            if (deleteOpIndex !== null && idx < operatesPermission.length) {
+                const permList = operatesPermission[idx];
+                if (Array.isArray(permList) && deleteOpIndex < permList.length) {
+                    const permItem = asRecord(permList[deleteOpIndex]);
+                    if (Array.isArray(permList) && permList[deleteOpIndex] && typeof permList[deleteOpIndex] === 'object' && permItem.visible) {
+                        canDelete = true;
+                    }
+                }
+            }
+            share.can_delete = canDelete;
+        }
+        shares.push(share);
+    }
+    return shares;
+}
+function shareEntryParts(response) {
+    const inner = nestedRecord(response, 'data');
+    return {
+        inner,
+        items: asList(inner.data),
+        operates: asList(inner.operates),
+        operatesPermission: asList(inner.operatesPermission),
+    };
+}
+/** 源 fetch_doc_share_entries：GET /api/doc/shareentry/list（含 download + can_delete）。 */
+export async function fetchDocShareEntries(env, docId, operation) {
+    const id = folderIdText(docId);
+    if (!id)
+        throw caizhilianValidationError('field_empty', 'doc_id 不能为空');
+    const response = await env.host.request({
+        method: 'GET',
+        path: '/api/doc/shareentry/list',
+        query: { sourceId: id, permissionId: 'doc_s01', sourceType: '1', docId: id },
+        operation,
+    });
+    const parts = shareEntryParts(response);
+    return {
+        add_visible: Boolean(parts.inner.addVisible),
+        shares: parseShareItems(parts.items, parts.operates, parts.operatesPermission, {
+            includeDownload: true,
+            includeCanDelete: true,
+        }),
+    };
+}
+/** 源 fetch_folder_default_share_entries：GET /api/doc/shareentry/list?folderId（解析后格式）。 */
+export async function fetchFolderDefaultShareEntries(env, folderId, operation) {
+    const id = folderIdText(folderId);
+    if (!id)
+        throw caizhilianValidationError('field_empty', 'folder_id 不能为空');
+    const response = await env.host.request({
+        method: 'GET',
+        path: '/api/doc/shareentry/list',
+        query: { folderId: id },
+        operation,
+    });
+    const parts = shareEntryParts(response);
+    return { shares: parseShareItems(parts.items, parts.operates, parts.operatesPermission) };
+}
+/** 源 fetch_folder_permission_entries：GET /api/doc/folderSetting/share/list。 */
+export async function fetchFolderPermissionEntries(env, folderId, permissionType, operation) {
+    const id = folderIdText(folderId);
+    if (!id)
+        throw caizhilianValidationError('field_empty', 'folder_id 不能为空');
+    const response = await env.host.request({
+        method: 'GET',
+        path: '/api/doc/folderSetting/share/list',
+        query: {
+            sourceId: id,
+            permissionId: 'doc_s01',
+            sourceType: '1',
+            folderId: id,
+            docSettingType: permissionType,
+            isTemplate: 'false',
+        },
+        operation,
+    });
+    const parts = shareEntryParts(response);
+    return {
+        add_visible: Boolean(parts.inner.addVisible),
+        shares: parseShareItems(parts.items, parts.operates, parts.operatesPermission),
+    };
+}
+// ── 文件夹权限设置（源 _build_folder_permission_add_body 等）───────────────
+/** 源 _plugin_helpers._FOLDER_SETTING_TARGET_TYPE。 */
+export const FOLDER_SETTING_TARGET_TYPE = {
+    resource: 1,
+    department: 3,
+    subcompany: 6,
+    role: 4,
+    position: 5,
+    group: 2,
+    customer: 7,
+    customer_type: 8,
+};
+/** 源 _build_folder_permission_add_body 的可选级联参数。 */
+const PERMISSION_OPTIONAL_PARAMS = ['department_attribute', 'role_level', 'position_level', 'position_attribute'];
+/** 源 _build_folder_permission_add_body 的 obj_id 系列字段（顺序影响 targetId 取值）。 */
+const PERMISSION_ID_FIELDS = [
+    'obj_id',
+    'obj_id_department',
+    'obj_id_subcompany',
+    'obj_id_role',
+    'obj_id_group',
+    'obj_id_position',
+    'obj_id_customer',
+    'obj_id_customer_type',
+    'position_level_department',
+    'position_level_subcompany',
+];
+/** 构建文件夹文档权限设置 add 请求体。 */
+export function buildFolderPermissionAddBody(folderId, permissionType, objType, args) {
+    const body = {
+        sourceId: folderId,
+        permissionId: 'doc_s01',
+        sourceType: 1,
+        folderId,
+        docSettingType: permissionType,
+        isTemplate: false,
+        objType,
+    };
+    for (const key of PERMISSION_OPTIONAL_PARAMS) {
+        if (key in args)
+            body[key] = args[key];
+    }
+    let targetId = null;
+    for (const field of PERMISSION_ID_FIELDS) {
+        if (!(field in args))
+            continue;
+        const value = args[field];
+        if (Array.isArray(value)) {
+            body[field] = value;
+            if (value.length)
+                targetId = String(value[0]);
+        }
+        else if (typeof value === 'string' && value) {
+            body[field] = [value];
+            targetId = value;
+        }
+    }
+    const targetType = FOLDER_SETTING_TARGET_TYPE[objType];
+    if (targetType !== undefined)
+        body.targetType = targetType;
+    if (targetId)
+        body.targetId = targetId;
+    return body;
+}
+/** 源 fetch_folder_permission_auth：GET /api/doc/folderBackstageSetting/docPermission。 */
+export async function fetchFolderPermissionAuth(env, folderId, permissionType, operation) {
+    const id = folderIdText(folderId);
+    if (!id)
+        throw caizhilianValidationError('field_empty', 'folder_id 不能为空');
+    const response = await env.host.request({
+        method: 'GET',
+        path: '/api/doc/folderBackstageSetting/docPermission',
+        query: { folderId: id, type: permissionType, isTemplate: 'false' },
+        operation,
+    });
+    const inner = nestedRecord(response, 'data');
+    // 响应字段名随 permission_type 变化（downloadAuth / deleteAuth ...），源取第一个值。
+    for (const value of Object.values(inner)) {
+        if (typeof value === 'boolean')
+            return String(value).toLowerCase();
+        if (value !== undefined && value !== null)
+            return String(value);
+        return null;
+    }
+    return null;
+}
+/** 源 update_folder_permission_auth 的 _VALUE_FIELD_MAP。 */
+export const PERMISSION_AUTH_VALUE_FIELD_MAP = {
+    downloadPremisstion: 'folderDocIsDown',
+    deletePremisstion: 'folderDocIsDelete',
+    settingPermissionIncludeMaintainPermission: 'settingPermissionIncludeMaintainPermission',
+};
+/** 源 PERMISSION_AUTH 取值范围。 */
+export const PERMISSION_AUTH_VALUES = ['true', 'user', 'false'];
+/** POST /api/doc/folderBackstageSetting/docPermission（设置文件夹权限类型值）。 */
+export async function updateFolderPermissionAuth(env, folderId, permissionType, value, operation) {
+    const id = folderIdText(folderId);
+    if (!id)
+        throw caizhilianValidationError('field_empty', 'folder_id 不能为空');
+    if (!PERMISSION_AUTH_VALUES.includes(value)) {
+        throw caizhilianValidationError('enum_invalid', `value 必须为 true / user / false，收到: ${JSON.stringify(value)}`);
+    }
+    const valueField = PERMISSION_AUTH_VALUE_FIELD_MAP[permissionType] ?? 'folderDocIsDown';
+    await env.host.request({
+        method: 'POST',
+        path: '/api/doc/folderBackstageSetting/docPermission',
+        body: {
+            folderId: id,
+            permissionItemName: permissionType,
+            isTemplate: false,
+            [valueField]: value,
+            folderPermissionItem: '{"USER":"","DEPARTMENT":"","ALL":"","GROUP":"","SUBCOMPANY":""}',
+            synSubordinateFolders: false,
+            keepOldShare: false,
+        },
+        operation,
+    });
+}
+// ── 「已存在」类响应（源 add_doc_share / add_folder_set_default_share）──────
+/** 源 `code == 500 and status` → 「已存在」，视为成功但 added=false。 */
+export function isAlreadyExistsResponse(data) {
+    return data.code === 500 && Boolean(data.status);
+}
+/**
+ * 源这两个 plugin 直接用 client.execute（不过业务成功校验），
+ * CLI 侧在「已存在」分支之外补上业务成功校验，避免把业务失败当成 added=true。
+ */
+export function assertToleratedBusinessSuccess(data, action) {
+    if (isCaizhilianBusinessSuccess(data))
+        return;
+    throw new CaizhilianCliError('api', 'business_error', caizhilianBusinessMessage(data), {
+        code: data.code ?? data.status,
+        details: { action, code: data.code ?? data.status, message: caizhilianBusinessMessage(data) },
+        exitCode: 1,
+    });
+}