weaver-work-cli 0.1.23 → 0.1.24

package/dist/shortcuts/caizhilian/file-upload/multipart.js

@@ -0,0 +1,47 @@
+/** Exact-length multipart body with bounded file slices and RFC 5987 UTF-8 filenames. */
+import { randomBytes } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { assertUploadSnapshot, READ_FLAGS } from './metadata.js';
+function quoted(value) { return value.replace(/[\r\n\0]/g, '_').replace(/\\/g, '\\\\').replace(/"/g, '\\"'); }
+function encodedFilename(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+export function uploadMultipart(fields, file) {
+    const boundary = `weaver-${randomBytes(16).toString('hex')}`;
+    const parts = [];
+    for (const [key, value] of Object.entries(fields)) {
+        const text = value === null || value === undefined ? '' : typeof value === 'string' ? value : JSON.stringify(value);
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${quoted(key)}"\r\n\r\n${text}\r\n`));
+    }
+    if (file) {
+        const fallback = quoted(file.meta.name.replace(/[^\x20-\x7e]/g, '_'));
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${fallback}"; `
+            + `filename*=UTF-8''${encodedFilename(file.meta.name)}\r\nContent-Type: ${file.meta.mime_type}\r\n\r\n`));
+    }
+    const tail = Buffer.from(`${file ? '\r\n' : ''}--${boundary}--\r\n`);
+    const body = Readable.from((async function* () {
+        yield* parts;
+        if (file && file.size > 0) {
+            const handle = await open(file.meta.path, READ_FLAGS);
+            try {
+                assertUploadSnapshot(file.meta, await handle.stat());
+                const stream = handle.createReadStream({ start: file.start, end: file.start + file.size - 1, autoClose: false });
+                try {
+                    for await (const bytes of stream)
+                        yield bytes;
+                    assertUploadSnapshot(file.meta, await handle.stat());
+                }
+                finally {
+                    stream.destroy();
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        yield tail;
+    })(), { objectMode: false });
+    return { body, contentType: `multipart/form-data; boundary=${boundary}`,
+        contentLength: parts.reduce((total, bytes) => total + bytes.length, tail.length + (file?.size ?? 0)) };
+}

package/dist/shortcuts/caizhilian/file-upload/protocol.js

@@ -0,0 +1,116 @@
+/** Upload strategy owner, adapted from weaver-file-upload to the CLI-owned authenticated host. */
+import { CaizhilianCliError, caizhilianValidationError } from '../errors.js';
+import { ExitCode } from '../../../core/errors.js';
+import { uploadMultipart } from './multipart.js';
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const invalid = (subtype, message) => { throw caizhilianValidationError(subtype, message); };
+function checkedData(response) {
+    const envelope = object(response);
+    const data = object(envelope.data);
+    const code = envelope.code === undefined || envelope.code === null ? '' : String(envelope.code).toLowerCase();
+    if (code && !['0', '200', 'success'].includes(code))
+        invalid('upload_business_failed', '文件服务未确认操作成功');
+    for (const record of [envelope, data]) {
+        if (record.status === false || record.success === false || record.fail === true) {
+            invalid('upload_business_failed', '文件服务未确认操作成功');
+        }
+    }
+    if (!envelope.data || typeof envelope.data !== 'object' || Array.isArray(envelope.data)) {
+        invalid('upload_response_invalid', '文件服务响应缺少有效数据对象');
+    }
+    return data;
+}
+function fileRecord(data) {
+    const candidates = [[data], [object(data.fileObj)], [object(data.uploadModuleDto)],
+        [object(data.uploadModuleDto?.fileObj), object(data.uploadModuleDto)], [object(data.imUploadInfoDto)],
+        [object(data.imUploadInfoDto?.fileObj), object(data.imUploadInfoDto)]];
+    for (const [record, parent] of candidates) {
+        const id = record.fileId ?? record.fileid;
+        if (typeof id === 'number' && !Number.isSafeInteger(id))
+            invalid('file_id_invalid', '文件 ID 精度不可靠');
+        if ((typeof id === 'string' || typeof id === 'number') && String(id).trim()) {
+            return { id: String(id).trim(), sizes: [record.size, parent?.size, data.size] };
+        }
+    }
+    return undefined;
+}
+function terminal(data, file) {
+    const record = fileRecord(data);
+    if (!record || data.endChunk === false)
+        invalid('upload_not_terminal', '上传未返回已完成的非空文件 ID');
+    for (const reported of record.sizes) {
+        if (reported === undefined || reported === null || reported === '')
+            continue;
+        const size = Number(reported);
+        if (!Number.isSafeInteger(size) || size < 0 || (size !== 0 && size !== file.size)) {
+            invalid('upload_size_mismatch', '服务端文件大小与本地文件不一致');
+        }
+    }
+    return record.id;
+}
+async function send(host, path, fields, timeoutMs, file) {
+    const multipart = uploadMultipart(fields, file);
+    try {
+        return checkedData(await host.request({ method: 'POST', path, query: { sf_request_type: 'ajax' },
+            streamMultipart: multipart, timeoutMs, maxResponseBytes: 4 * 1024 * 1024, requireHttp200: true,
+            tolerateBusinessError: true,
+            operation: 'caizhilian.file-upload.upload.apply' }));
+    }
+    catch (error) {
+        const failure = error;
+        if (file && (failure?.type === 'network' || failure?.subtype === 'http_error')) {
+            throw new CaizhilianCliError('partial', 'write_uncertain', '上传请求已发出，但未确认结果；请勿自动重复上传', {
+                retryable: false, details: { execution_state: 'unknown', retry_safe: false }, exitCode: ExitCode.Partial,
+            });
+        }
+        throw error;
+    }
+    finally {
+        multipart.body.destroy();
+    }
+}
+export async function uploadToFileService(host, file, module, context, timeoutMs) {
+    // Node stat retains fractional milliseconds; E10 parses these fields as integer milliseconds.
+    const lastModified = String(Math.floor(file.mtime_ms));
+    const fields = { ...context.fields, compressImg: 'false', module, name: file.name, size: String(file.size),
+        MD5: file.md5, lastModified, lastModifiedDate: lastModified };
+    const pre = await send(host, '/api/file/preUploadCheck', fields, timeoutMs);
+    const type = pre.uploadType;
+    if (!['second', 'common', 'chunk'].includes(type))
+        invalid('upload_type_invalid', '文件服务返回未知上传策略');
+    if (type === 'second')
+        return { file_id: terminal(pre, file), upload_type: type };
+    if (typeof pre.preUploadId !== 'string' || !pre.preUploadId.trim()) {
+        // E10 may return preUploadId as a safe numeric ID.
+        if (typeof pre.preUploadId !== 'number' || !Number.isSafeInteger(pre.preUploadId) || pre.preUploadId <= 0) {
+            invalid('upload_precheck_invalid', '预上传检查未返回有效 preUploadId');
+        }
+    }
+    const uploadFields = { ...fields, preUploadId: String(pre.preUploadId), uploadType: type };
+    if (type === 'common') {
+        const data = await send(host, '/api/file/module/upload', uploadFields, timeoutMs, { meta: file, start: 0, size: file.size });
+        return { file_id: terminal(data, file), upload_type: type };
+    }
+    const chunkMiB = Number(pre.chunkDto?.chunkSize);
+    if (!Number.isSafeInteger(chunkMiB) || chunkMiB <= 0 || file.size <= 0) {
+        invalid('chunk_size_invalid', '分片上传需要非空文件和正整数 MiB 分片大小');
+    }
+    const chunkSize = chunkMiB * 1024 * 1024;
+    if (!Number.isSafeInteger(chunkSize) || chunkSize <= 0)
+        invalid('chunk_size_invalid', '分片大小必须是有效的正 MiB 值');
+    const count = Math.max(1, Math.ceil(file.size / chunkSize));
+    if (pre.chunkDto?.chunkCount !== undefined && Number(pre.chunkDto.chunkCount) !== count) {
+        invalid('chunk_count_mismatch', '服务端分片数量与本地计算不一致');
+    }
+    for (let index = 0; index < count; index++) {
+        const start = index * chunkSize;
+        const size = Math.min(chunkSize, file.size - start);
+        const data = await send(host, '/api/file/module/upload', { ...uploadFields, chunk: index, chunks: count,
+            uploadShardSize: String(size) }, timeoutMs, { meta: file, start, size });
+        if (index === count - 1)
+            return { file_id: terminal(data, file), upload_type: 'chunk' };
+        if (data.endChunk !== false || fileRecord(data))
+            invalid('chunk_terminal_early', '中间分片缺少明确未完成状态或提前返回文件 ID');
+    }
+    return invalid('upload_not_terminal', '分片上传未确认完成');
+}

package/dist/shortcuts/caizhilian/file-upload/receipt.js

@@ -0,0 +1,37 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { CaizhilianCliError } from '../errors.js';
+import { ExitCode } from '../../../core/errors.js';
+export async function writeUploadReceipt(env, chatId, module, file, context, verified) {
+    const session = await env.host.getSession();
+    const identity = JSON.stringify({ baseUrl: session.baseUrl, userId: session.userId, tenantKey: session.tenantKey });
+    const result = { version: 'weaver_file_upload_result.v1', status: 'completed', business_verified: true,
+        upload_type: verified.upload_type, file: { file_id: verified.file_id, name: file.name, size: file.size,
+            mime_type: file.mime_type, extension: file.extension, is_image: file.is_image },
+        integrity: { md5: file.md5, sha256: file.sha256 },
+        request_evidence: { module, context_keys: context.keys, context_sha256: context.sha256,
+            environment_identity_sha256: createHash('sha256').update(identity).digest('hex'),
+            login_mode: 'weaver-work-cli', automatic_fallback: false } };
+    const configPath = env.ctx.config?.path();
+    const stateRoot = configPath ? dirname(configPath) : env.ctx.env?.WEAVER_WORK_CLI_HOME
+        || env.ctx.env?.WORK_CLI_HOME || resolve(homedir(), '.weaver-work-cli');
+    const directory = resolve(stateRoot, 'caizhilian', 'file-upload', 'runs', chatId, 'receipts');
+    const filename = resolve(directory, `upload-${randomUUID()}.json`);
+    const content = `${JSON.stringify(result, null, 2)}\n`;
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        if (process.platform !== 'win32')
+            await chmod(directory, 0o700);
+        await writeFile(filename, content, { flag: 'wx', mode: 0o600 });
+    }
+    catch {
+        throw new CaizhilianCliError('partial', 'receipt_write_failed', '文件已上传，但本地回执保存失败；请勿重复上传', {
+            retryable: false, partialData: { file_id: verified.file_id, upload_type: verified.upload_type },
+            details: { execution_state: 'completed', retry_safe: false }, exitCode: ExitCode.Partial,
+        });
+    }
+    return { ...result, file_id: verified.file_id, file_name: file.name, size: file.size, ext: file.extension,
+        receipt_ref: filename, receipt_sha256: createHash('sha256').update(content).digest('hex') };
+}

package/dist/shortcuts/caizhilian/host.js

@@ -110,9 +110,13 @@ export function createCaizhilianHost(ctx, dependencies = {}) {
         });
     }
     async function doRequest(request, binary) {
-        const { method, path, query, body, operation, form, multipart, headers: extraHeaders = {}, timeoutMs = CAIZHILAN_TIMEOUT_MS, } = request;
+        const { method, path, query, body, operation, form, multipart, streamMultipart, maxResponseBytes, headers: extraHeaders = {}, timeoutMs = CAIZHILAN_TIMEOUT_MS, } = request;
         assertCaizhilianPath(path);
-        const resolvedMethod = method || (body === undefined && form === undefined && multipart === undefined ? 'GET' : 'POST');
+        const resolvedMethod = method || (body === undefined && form === undefined && multipart === undefined
+            && streamMultipart === undefined ? 'GET' : 'POST');
+        const headers = { 'X-Requested-With': 'XMLHttpRequest', ...extraHeaders, ...(streamMultipart ? {
+                'Content-Type': streamMultipart.contentType, 'Content-Length': String(streamMultipart.contentLength),
+            } : {}) };
         const rt = await runtime();
         const response = binary
             ? await rt.requestBinary({
@@ -124,7 +128,9 @@ export function createCaizhilianHost(ctx, dependencies = {}) {
                 body: multipart === undefined ? body : undefined,
                 form: multipart === undefined && form === undefined ? undefined : formBody(form ?? {}),
                 formData: multipart,
-                headers: { 'X-Requested-With': 'XMLHttpRequest', ...extraHeaders },
+                streamBody: streamMultipart?.body,
+                maxResponseBytes,
+                headers,
                 timeoutMs,
             })
             : await rt.requestJson({
@@ -136,7 +142,9 @@ export function createCaizhilianHost(ctx, dependencies = {}) {
                 body: multipart === undefined ? body : undefined,
                 form: multipart === undefined && form === undefined ? undefined : formBody(form ?? {}),
                 formData: multipart,
-                headers: { 'X-Requested-With': 'XMLHttpRequest', ...extraHeaders },
+                streamBody: streamMultipart?.body,
+                maxResponseBytes,
+                headers,
                 timeoutMs,
             });
         return response;
@@ -156,7 +164,7 @@ export function createCaizhilianHost(ctx, dependencies = {}) {
             }
             throw caizhilianNetworkError('protocol', `接口返回不是合法 JSON（HTTP ${response.status}）`, { retryable: false });
         }
-        if (response.status < 200 || response.status >= 300) {
+        if (response.status < 200 || response.status >= 300 || (request.requireHttp200 && response.status !== 200)) {
             throw new CaizhilianCliError('api', 'http_error', `采知连接口 HTTP ${response.status}`, {
                 code: response.status,
                 details: { status: response.status, message: caizhilianBusinessMessage(response.value) },

package/dist/shortcuts/caizhilian/operations/handlers/file-upload.js

@@ -1,192 +1,85 @@
-/**
- * caizhilian.file-upload — 文件上传（本地文件上传到文件服务）
- *
- * 覆盖本地文件上传到 E10 文件服务的完整流程：
- * - contract: 获取上传接口合约
- * - prepare: 本地文件校验与元数据准备
- * - upload: 上传文件并获取 fileId
- *
- * 接口：
- * - 预检查：POST /api/file/preUploadCheck?sf_request_type=ajax
- * - 上传：POST /api/file/module/upload?sf_request_type=ajax
- */
-import { CaizhilianCliError, caizhilianValidationError } from '../../errors.js';
-import { caizhilianSuccess } from '../types.js';
-import { requireNonEmpty } from '../shared.js';
-import { createHash } from 'node:crypto';
-import { readFileSync, statSync } from 'node:fs';
-import { basename, extname } from 'node:path';
-const ACTION = 'caizhilian.file-upload';
-// ── 接口路径 ──────────────────────────────────────────────
-const PRE_UPLOAD_CHECK_PATH = '/api/file/preUploadCheck?sf_request_type=ajax';
-const UPLOAD_PATH = '/api/file/module/upload?sf_request_type=ajax';
-// ── 辅助函数 ──────────────────────────────────────────────
-function asRecord(value) {
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+/** Weaver file upload integrated with the existing CLI confirmation and authentication boundary. */
+import { caizhilianConfirmationError, caizhilianValidationError } from '../../errors.js';
+import { inspectUploadFile, readUploadContext, RESERVED_CONTEXT_FIELDS, uploadChatId, uploadModule, uploadTimeout } from '../../file-upload/metadata.js';
+import { uploadToFileService } from '../../file-upload/protocol.js';
+import { writeUploadReceipt } from '../../file-upload/receipt.js';
+import { issueWriteLease } from '../confirm.js';
+import { caizhilianPrepared, caizhilianSuccess } from '../types.js';
+const PREFIX = 'caizhilian.file-upload';
+const COMMAND = 'weaver-work-cli --json caizhilian run';
+const CONTEXT_PURPOSES = {
+    source: '上传来源场景', fieldId: '附件字段或控件 ID', sourceRefId: '来源业务对象引用 ID',
+    authModule: '服务端权限校验模块', customParam: '模块扩展参数', refId: '最终关联对象 ID',
+    commonText: '通用场景参数', folderId: '目标文件夹 ID',
+};
+async function getContract() {
+    return caizhilianSuccess(`${PREFIX}.contract`, { contract: {
+            version: 'agent_callable_interface_contract.v1', authentication: 'weaver-work-cli', automatic_fallback: false,
+            upload_strategies: ['second', 'common', 'chunk'],
+            actions: ['contract', 'prepare', 'upload.prepare', 'upload.apply'],
+            canonical_commands: ['contract', 'prepare', 'upload.prepare', 'upload.apply'].map((name) => `${COMMAND} ${PREFIX}.${name}${name === 'contract' ? '' : ' --input-json <businessInputJson>'}`
+                + (name === 'upload.apply' ? ' --continuation <token> --yes' : '')),
+            required: { prepare: ['file_path', 'module'], 'upload.prepare': ['file_path', 'module', 'user_confirmed'],
+                'upload.apply': ['file_path', 'module', 'user_confirmed', 'continuation', 'confirm'] },
+            optional: { prepare: ['context_file', 'chat_id', 'timeout_seconds'],
+                'upload.prepare': ['context_file', 'chat_id', 'timeout_seconds'],
+                'upload.apply': ['context_file', 'chat_id', 'timeout_seconds'] },
+            user_input_guide: { required: [
+                    { name: 'file_path', purpose: '需要上传的本地普通文件绝对路径，直接复用宿主附件路径' },
+                    { name: 'module', purpose: '真实业务模块；不得猜测或使用默认模块' },
+                ], conditionally_required: [], optional: [
+                    { name: 'context_file', purpose: '可选业务上下文 JSON 文件绝对路径，最多 64 KiB' },
+                    { name: 'chat_id', purpose: '隔离对话回执；默认 cli，由宿主注入' },
+                    { name: 'timeout_seconds', purpose: '上传请求及响应读取超时（1–3600 秒，默认 300）' },
+                    ...Object.entries(CONTEXT_PURPOSES).map(([name, purpose]) => ({ name: `context_file.${name}`, purpose })),
+                ] }, reserved_context_fields: RESERVED_CONTEXT_FIELDS,
+            success_evidence: ['business_verified', 'file.file_id', 'receipt_ref', 'receipt_sha256'],
+            login: '登录由 weaver-work-cli auth 托管，本模块不读取其他 Skill 登录态或启动独立浏览器',
+        } });
 }
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+function requireUploadAuthorization(args) {
+    if (args.user_confirmed !== true) {
+        throw caizhilianConfirmationError(`${PREFIX}.upload`, { hint: '上传必须来自当前用户明确授权，并传 user_confirmed=true' });
+    }
 }
-function md5File(filePath) {
-    const content = readFileSync(filePath);
-    return createHash('md5').update(content).digest('hex');
+async function inspect(args) {
+    const module = uploadModule(args.module);
+    const chatId = uploadChatId(args.chat_id);
+    const timeoutMs = uploadTimeout(args.timeout_seconds);
+    const context = await readUploadContext(args.context_file);
+    const file = await inspectUploadFile(args.file_path);
+    return { file, context, module, chatId, timeoutMs };
 }
-function sha256File(filePath) {
-    const content = readFileSync(filePath);
-    return createHash('sha256').update(content).digest('hex');
+function metadataPreview(prepared) {
+    const { file, context, module, chatId } = prepared;
+    return { file_path: file.path, file_name: file.name, ext: file.extension, size: file.size,
+        md5: file.md5, sha256: file.sha256, module, chat_id: chatId, context_keys: context.keys,
+        context_sha256: context.sha256 };
 }
-// ── 获取上传合约 ──────────────────────────────────────────
-async function getContract(args, env) {
-    return caizhilianSuccess(ACTION, {
-        contract: {
-            version: 'agent_callable_interface_contract.v1',
-            actions: ['contract', 'prepare', 'upload'],
-            required: {
-                prepare: ['file_path', 'module'],
-                upload: ['file_path', 'module', 'user_confirmed'],
-            },
-            optional: {
-                prepare: ['context_file'],
-                upload: ['context_file', 'login_mode'],
-            },
-        },
-    });
+async function prepareLocal(args) {
+    return caizhilianSuccess(`${PREFIX}.prepare`, metadataPreview(await inspect(args)));
 }
-// ── 准备上传（prepare/apply）──────────────────────────────────────
 async function prepareUpload(args, env) {
-    const filePath = requireNonEmpty(args.file_path, 'file_path');
-    const module = requireNonEmpty(args.module, 'module');
-    // 校验文件存在
-    let stat;
-    try {
-        stat = statSync(filePath);
-    }
-    catch (error) {
-        throw caizhilianValidationError('file_not_found', `文件不存在: ${filePath}`);
-    }
-    if (!stat.isFile()) {
-        throw caizhilianValidationError('file_not_regular', `不是普通文件: ${filePath}`);
-    }
-    // 计算元数据
-    const fileName = basename(filePath);
-    const ext = extname(filePath).slice(1).toLowerCase();
-    const size = stat.size;
-    const md5 = md5File(filePath);
-    const sha256 = sha256File(filePath);
-    // 签发 continuation
-    const continuation = await env.continuation.issue({
-        operation: 'caizhilian.file-upload.upload.apply',
-        filePath,
-        module,
-        fileName,
-        ext,
-        size,
-        md5,
-        sha256,
-    });
-    return caizhilianSuccess('caizhilian.file-upload.prepare', {
-        file_path: filePath,
-        file_name: fileName,
-        ext,
-        size,
-        md5,
-        sha256,
-        module,
-        continuation,
-    });
+    const prepared = await inspect(args);
+    const lease = await issueWriteLease(env, `${PREFIX}.upload.apply`, args, { file_path: prepared.file.path,
+        module: prepared.module, file: prepared.file, context_sha256: prepared.context.sha256 });
+    return caizhilianPrepared(`${PREFIX}.upload.prepare`, metadataPreview(prepared), lease);
 }
 async function uploadApply(args, env, lease) {
-    const filePath = lease.payload?.filePath;
-    const module = lease.payload?.module;
-    const fileName = lease.payload?.fileName;
-    const ext = lease.payload?.ext;
-    const size = lease.payload?.size;
-    const md5 = lease.payload?.md5;
-    const sha256 = lease.payload?.sha256;
-    // 预检查
-    const preCheckResponse = await env.host.request({
-        method: 'POST',
-        path: PRE_UPLOAD_CHECK_PATH,
-        body: {
-            fileName,
-            fileSize: size,
-            module,
-            md5,
-        },
-        operation: 'caizhilian.file-upload.upload.apply',
-    });
-    const preCheckData = asRecord(preCheckResponse);
-    if (!preCheckData.status && !preCheckData.success) {
-        throw new CaizhilianCliError('api', 'business_error', String(preCheckData.msg || preCheckData.message || '预检查失败'), {
-            code: preCheckData.code ?? preCheckData.status,
-            details: { action: 'caizhilian.file-upload.upload.apply', message: String(preCheckData.msg || preCheckData.message || '预检查失败') },
-            exitCode: 1,
-        });
-    }
-    const preCheckResult = asRecord(preCheckData.data);
-    // 判断上传策略
-    const uploadType = preCheckResult.uploadType || 'common';
-    const preUploadId = preCheckResult.preUploadId;
-    // 如果是 second 策略，直接返回已有 file ID
-    if (uploadType === 'second') {
-        const fileId = preCheckResult.fileId || preCheckResult.fileid || preCheckResult.uploadModuleDto?.fileObj?.fileId;
-        if (!fileId) {
-            throw new CaizhilianCliError('api', 'business_error', 'second 策略未返回 file ID', {
-                details: { action: 'caizhilian.file-upload.upload.apply' },
-                exitCode: 1,
-            });
-        }
-        return caizhilianSuccess('caizhilian.file-upload.upload.apply', {
-            file_id: String(fileId),
-            file_name: fileName,
-            size,
-            ext,
-            upload_type: uploadType,
-        });
-    }
-    // common/chunk 策略：上传文件
-    const fileContent = readFileSync(filePath);
-    const formData = new FormData();
-    formData.append('file', new Blob([fileContent]), fileName);
-    formData.append('preUploadId', preUploadId || '');
-    formData.append('module', module);
-    const uploadResponse = await env.host.request({
-        method: 'POST',
-        path: UPLOAD_PATH,
-        body: formData,
-        operation: 'caizhilian.file-upload.upload.apply',
-    });
-    const uploadData = asRecord(uploadResponse);
-    if (!uploadData.status && !uploadData.success) {
-        throw new CaizhilianCliError('api', 'business_error', String(uploadData.msg || uploadData.message || '上传失败'), {
-            code: uploadData.code ?? uploadData.status,
-            details: { action: 'caizhilian.file-upload.upload.apply', message: String(uploadData.msg || uploadData.message || '上传失败') },
-            exitCode: 1,
-        });
+    const prepared = await inspect(args);
+    if (prepared.file.sha256 !== lease.file?.sha256 || prepared.file.size !== lease.file?.size) {
+        throw caizhilianValidationError('file_changed', '文件与已确认内容不一致，请重新准备上传');
     }
-    const uploadResult = asRecord(uploadData.data);
-    const fileId = uploadResult.fileId || uploadResult.fileid || '';
-    if (!fileId) {
-        throw new CaizhilianCliError('api', 'business_error', '上传未返回 file ID', {
-            details: { action: 'caizhilian.file-upload.upload.apply' },
-            exitCode: 1,
-        });
+    if (prepared.context.sha256 !== lease.context_sha256) {
+        throw caizhilianValidationError('context_changed', '业务上下文与已确认内容不一致，请重新准备上传');
     }
-    return caizhilianSuccess('caizhilian.file-upload.upload.apply', {
-        file_id: String(fileId),
-        file_name: fileName,
-        size,
-        ext,
-        upload_type: uploadType,
-    });
+    const verified = await uploadToFileService(env.host, prepared.file, prepared.module, prepared.context, prepared.timeoutMs);
+    const result = await writeUploadReceipt(env, prepared.chatId, prepared.module, prepared.file, prepared.context, verified);
+    return caizhilianSuccess(`${PREFIX}.upload.apply`, result);
 }
-// ── 处理器汇总 ────────────────────────────────────────────
 export const caizhilianFileUploadHandlers = {
-    'caizhilian.file-upload.contract': { execute: getContract },
-    'caizhilian.file-upload.prepare': { execute: prepareUpload },
-    'caizhilian.file-upload.upload': {
-        prepare: prepareUpload,
-        apply: uploadApply,
-        targetKeys: ['file_path', 'module'],
-    },
+    [`${PREFIX}.contract`]: { execute: getContract },
+    [`${PREFIX}.prepare`]: { execute: prepareLocal },
+    [`${PREFIX}.upload`]: { validateInput: requireUploadAuthorization, prepare: prepareUpload,
+        apply: uploadApply, targetKeys: ['file_path', 'module'] },
 };