weaver-work-cli 0.1.0 → 0.1.2

package/README.md

@@ -91,7 +91,15 @@ weaver-work-cli skills install invoice
 `skills install invoice` 会同时安装 `weaver-work-cli-shared` 和
 `weaver-work-cli-invoice`。默认目标目录是 `$CODEX_HOME/skills`，未设置
 `CODEX_HOME` 时使用 `~/.codex/skills`；需要自定义时可加
-`--target-dir <path>`。
+`--target-dir <path>`。默认目标面向 Codex CLI；WorkBuddy 等桌面 Agent 的
+用户级 Skill 目录不是默认目标，需显式指定：
+
+```bash
+weaver-work-cli skills install invoice --target-dir ~/.workbuddy/skills
+```
+
+各 Agent 环境的 skill 目录、从本地开发仓库升级到最新版的完整流程与验证
+步骤见 `docs/agent-skill-install.md`。
 
 卸载全局命令：
 
@@ -315,7 +323,10 @@ weaver-work-cli --json invoice download --fid <fid> --file-id <fileId> --output
 写操作固定使用 `prepare -> apply`：
 
 ```bash
-echo '{"file":"./invoice.pdf","validate":false,"syncToOa":false}' \
+echo '{"file":"./invoice.pdf"}' \
+  | weaver-work-cli --json invoice run invoice.ocr.preview --input -
+
+echo '{"file":"./invoice.pdf","validate":true,"syncToOa":true}' \
   | weaver-work-cli --json invoice import prepare --input -
 
 echo '{"file":"./invoice.pdf","continuation":"<prepare返回值>","confirm":true}' \
@@ -324,6 +335,8 @@ echo '{"file":"./invoice.pdf","continuation":"<prepare返回值>","confirm":true
 
 Agent 应优先调用 `weaver-work-cli --json invoice run <operation> --input -`，并读取 `weaver-work-cli invoice schema` 获取 operation 契约。共享、转让和标签接口因缺少稳定 ID 来源和写后回查契约，当前不暴露给 Agent。
 
+输出处理参考飞书 CLI 的 Agent 友好实践，但当前项目仍是轻量输出层：`ctx.output.write` 在 JSON 模式下直接把完整 envelope 打到 stdout，失败写 stderr；暂未提供通用 `--jq`、`--format table/ndjson` 或 `--page-all`。因此业务 Skill 会预先要求 Agent 控制响应量：列表默认 `page_size=10`，按业务分页字段继续；给用户只渲染摘要、关键字段、数量和下一步，超长详情/OCR/调试 JSON 优先落本地文件并返回路径。
+
 如需交付通用 Agent Skill 包：
 
 ```bash

package/dist/internal/e10/auth/commands.js

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import { createServer } from 'node:http';
 import { CliError, ExitCode } from '../../../core/errors.js';
+import { clearInvoiceTokenForSession } from '../../../shortcuts/invoice/host.js';
 import { buildE10CookieHeader, E10AuthSession, clearProfileAuthFile, extractRawSetCookie, findAuthFile, getActiveProfile, getProfileAuthPath, getProfileDir, listProfiles, profileNameFromUrl, readProfileConfig, readTeamsCheckUserInfo, saveAuthFile, saveProfileConfig, setActiveProfile, } from './session.js';
 import { getE10AuthRoot } from './paths.js';
 const DEFAULT_AGENT_TYPE = 'weaver-work-cli';
@@ -83,6 +84,15 @@ function formatLoginResult(result) {
         'authFile: ' + result.authFile,
     ].join('\n');
 }
+async function clearInvoiceTokenCache(profile, authData) {
+    if (!authData.baseUrl || !authData.userId)
+        return;
+    await clearInvoiceTokenForSession({
+        baseUrl: normalizeUrl(authData.baseUrl),
+        profile,
+        userId: authData.userId,
+    }).catch(() => false);
+}
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -118,7 +128,7 @@ async function resolveUserInfo(baseUrl, eteamsId, rawCookie = '', agentType = ''
             'content-type': 'application/json',
             eteamsid: eteamsId,
             cookie: buildE10CookieHeader(rawCookie, eteamsId, agentType),
-            'user-agent': agentType ? `AgentType=${agentType},IsAgent=true` : 'e10-login',
+            'user-agent': agentType ? `AgentType=${agentType},IsAgent=true` : DEFAULT_AGENT_TYPE,
             origin: baseUrl,
         },
         redirect: 'manual',
@@ -201,6 +211,7 @@ async function oidcExchange(code, redirectUri, baseUrl, tenantKeyFallback, agent
     };
     const profile = profileHint || profileNameFromUrl(base);
     setActiveProfile(profile);
+    await clearInvoiceTokenCache(profile, authData);
     const authFile = saveAuthFile(authData, profile);
     saveProfileConfig(base, base, profile, tenantKey);
     return {
@@ -455,6 +466,7 @@ export function registerE10AuthCommands(parent, action) {
             passportUrl,
             cookieSavedAt: Date.now(),
         };
+        await clearInvoiceTokenCache(profile, authData);
         const authFile = saveAuthFile(authData, profile);
         saveProfileConfig(baseUrl, passportUrl, profile, tenantKey);
         const result = {
@@ -475,9 +487,18 @@ export function registerE10AuthCommands(parent, action) {
     auth.command('logout')
         .alias('clear')
         .description('Clear saved E10 auth for the current or selected profile')
-        .action(action((ctx) => {
+        .action(action(async (ctx) => {
         const opts = ctx.getGlobalOptions();
-        const result = clearProfileAuthFile(opts.profile || getActiveProfile());
+        const profile = opts.profile || getActiveProfile();
+        const authFile = getProfileAuthPath(profile);
+        const session = E10AuthSession.fromFile(authFile, opts.baseUrl, opts.passportUrl);
+        if (session) {
+            await clearInvoiceTokenCache(profile, {
+                baseUrl: session.getBaseUrl(),
+                userId: session.userId,
+            });
+        }
+        const result = clearProfileAuthFile(profile);
         const text = result.cleared
             ? 'Cleared E10 auth.\nprofile: ' + result.profile + '\nauthFile: ' + result.authFile
             : 'No E10 auth to clear.\nprofile: ' + result.profile + '\nauthFile: ' + result.authFile;

package/dist/internal/e10/auth/crypto.js

@@ -1,6 +1,5 @@
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { Entry as KeyringEntry } from '@napi-rs/keyring';
 import { writeWithRetry } from '../../../core/write-with-retry.js';
@@ -9,15 +8,11 @@ const ALGORITHM = 'aes-256-gcm';
 const IV_LENGTH = 12;
 const TAG_LENGTH = 16;
 const KEYCHAIN_SERVICE = 'weaver-work-cli';
-const LEGACY_KEYCHAIN_SERVICE = 'e10-cli';
 const KEYCHAIN_ACCOUNT = 'auth-key';
 let encKey = null;
 function getKeyFilePath() {
     return resolve(getE10AuthRoot(), '.key');
 }
-function getLegacyKeyFilePath() {
-    return resolve(homedir(), '.e10-cli', '.key');
-}
 function readKeychainKey(service) {
     try {
         const entry = new KeyringEntry(service, KEYCHAIN_ACCOUNT);
@@ -73,13 +68,6 @@ function getEncKey() {
     writeWithRetry(keyFile, encKey.toString('base64'), { mode: 0o600 });
     return encKey;
 }
-function getDecryptKeys() {
-    const keys = [getEncKey()];
-    const legacyKey = readKeychainKey(LEGACY_KEYCHAIN_SERVICE) || readKeyFile(getLegacyKeyFilePath());
-    if (legacyKey && !keys.some((key) => key.equals(legacyKey)))
-        keys.push(legacyKey);
-    return keys;
-}
 export function encryptAuthData(plaintext) {
     const iv = randomBytes(IV_LENGTH);
     const cipher = createCipheriv(ALGORITHM, getEncKey(), iv, { authTagLength: TAG_LENGTH });
@@ -95,17 +83,14 @@ export function decryptAuthData(wrapper) {
     const iv = combined.subarray(0, IV_LENGTH);
     const tag = combined.subarray(combined.length - TAG_LENGTH);
     const encrypted = combined.subarray(IV_LENGTH, combined.length - TAG_LENGTH);
-    for (const key of getDecryptKeys()) {
-        try {
-            const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: TAG_LENGTH });
-            decipher.setAuthTag(tag);
-            return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf-8');
-        }
-        catch {
-            // Try the next known key.
-        }
+    try {
+        const decipher = createDecipheriv(ALGORITHM, getEncKey(), iv, { authTagLength: TAG_LENGTH });
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf-8');
+    }
+    catch {
+        return null;
     }
-    return null;
 }
 export function parseAuthFile(raw) {
     try {

package/dist/internal/e10/auth/session.js

@@ -254,7 +254,7 @@ export class E10AuthSession {
         return buildE10CookieHeader(raw, this.eteamsId, this.agentType);
     }
     uaHeader() {
-        return this.agentType ? `AgentType=${this.agentType},IsAgent=true` : 'e10-login';
+        return this.agentType ? `AgentType=${this.agentType},IsAgent=true` : 'weaver-work-cli';
     }
     toJSON() {
         return {

package/dist/shortcuts/invoice/host.js

@@ -5,6 +5,7 @@ import { getActiveProfile } from '../../internal/e10/auth/session.js';
 import { InvoiceCliError, invoiceAuthError, invoiceNetworkError, invoiceValidationError, } from './errors.js';
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
 const TOKEN_SERVICE = 'cn.weaver.weaver-work-cli.invoice-token';
+const INVOICE_SESSION_EXPIRED_CODE = '-2';
 function assertPath(requestPath) {
     if (typeof requestPath !== 'string' || !requestPath.startsWith('/') || requestPath.startsWith('//')) {
         throw invoiceValidationError('path_invalid', '请求路径必须是相对绝对路径');
@@ -63,6 +64,10 @@ function responseCode(value) {
     const root = responseRoot(value);
     return root?.ret ?? root?.code;
 }
+function isInvoiceSessionExpired(value) {
+    const code = responseCode(value);
+    return code !== undefined && String(code) === INVOICE_SESSION_EXPIRED_CODE;
+}
 function tokenAccount(session) {
     return createHash('sha256')
         .update(`${session.profile}\n${session.baseUrl}\n${session.userId}`)
@@ -109,6 +114,9 @@ function createInvoiceTokenStore(session) {
         },
     };
 }
+export async function clearInvoiceTokenForSession(session) {
+    return createInvoiceTokenStore(session).clear();
+}
 function inferProfile(ctx) {
     const options = ctx.getGlobalOptions();
     return options.profile || getActiveProfile();
@@ -125,14 +133,16 @@ function requestHeaders(session, invoiceToken) {
         headers.token = invoiceToken;
     return headers;
 }
-export function createInvoiceHost(ctx) {
+export function createInvoiceHost(ctx, dependencies = {}) {
     let e10Session = null;
     let sessionContext = null;
     let invoiceToken = null;
     let tokenStore = null;
+    const requireSession = dependencies.requireSession || requireE10Session;
+    const tokenStoreFactory = dependencies.tokenStoreFactory || createInvoiceTokenStore;
     async function ensureSession() {
         if (!e10Session) {
-            e10Session = await requireE10Session(ctx);
+            e10Session = await requireSession(ctx);
             sessionContext = {
                 baseUrl: e10Session.getBaseUrl(),
                 profile: inferProfile(ctx),
@@ -148,7 +158,7 @@ export function createInvoiceHost(ctx) {
     async function ensureInvoiceToken(timeoutMs = 30_000) {
         await ensureSession();
         const context = await getSession();
-        tokenStore ||= createInvoiceTokenStore(context);
+        tokenStore ||= tokenStoreFactory(context);
         if (invoiceToken)
             return invoiceToken;
         invoiceToken = await tokenStore.load();
@@ -182,7 +192,31 @@ export function createInvoiceHost(ctx) {
         }
         return ensureInvoiceToken(timeoutMs);
     }
-    async function invoiceRequest(request) {
+    async function clearCachedInvoiceToken() {
+        invoiceToken = null;
+        await tokenStore?.clear().catch(() => false);
+    }
+    function businessError(value) {
+        const code = responseCode(value);
+        return new InvoiceCliError('api', 'business_error', responseMessage(value), {
+            code: String(code),
+            details: { ret: code },
+            exitCode: 1,
+        });
+    }
+    async function handleBusinessResponse(value, retry, canRetry) {
+        const code = responseCode(value);
+        if (code === undefined || code === 0 || code === 200)
+            return value;
+        if (isInvoiceSessionExpired(value)) {
+            await clearCachedInvoiceToken();
+            if (canRetry)
+                return retry();
+            throw invoiceAuthError('invoice_session_expired', '发票业务登录态已失效，已清理本地发票 Token；请重新运行 weaver-work-cli auth login --base-url <域名> 后再试', { ret: code });
+        }
+        throw businessError(value);
+    }
+    async function invoiceRequest(request, canRetryExpiredToken = true) {
         const { method = 'POST', path, query, body, needsInvoiceToken = true, timeoutMs = 30_000, } = request;
         assertPath(path);
         const token = await ensureContext(needsInvoiceToken, timeoutMs, path);
@@ -220,118 +254,110 @@ export function createInvoiceHost(ctx) {
                 exitCode: 1,
             });
         }
-        const code = responseCode(value);
-        if (code !== undefined && code !== 0 && code !== 200) {
-            throw new InvoiceCliError('api', 'business_error', responseMessage(value), {
-                code: String(code),
-                details: { ret: code },
+        return handleBusinessResponse(value, () => invoiceRequest(request, false), canRetryExpiredToken && Boolean(token));
+    }
+    async function invoiceMultipartRequest(request, canRetryExpiredToken = true) {
+        const { method = 'POST', path, query, fields = {}, file, needsInvoiceToken = true, timeoutMs = 30_000, } = request;
+        if (!file && !fields.url) {
+            throw invoiceValidationError('input_invalid', 'multipart 请求需要文件或 URL');
+        }
+        assertPath(path);
+        const token = await ensureContext(needsInvoiceToken, timeoutMs, path);
+        const session = await ensureSession();
+        const form = new FormData();
+        for (const [key, value] of Object.entries(fields)) {
+            if (value === undefined || value === null)
+                continue;
+            form.append(key, typeof value === 'string' ? value : JSON.stringify(value));
+        }
+        if (file) {
+            const content = await readFile(file.path);
+            form.append('file', new Blob([content], { type: file.mimeType || 'application/octet-stream' }), file.name);
+        }
+        const response = await fetchWithTimeout(withQuery(session.getBaseUrl(), path, query), {
+            method,
+            headers: requestHeaders(session, token),
+            body: form,
+            redirect: 'manual',
+        }, timeoutMs);
+        const text = await response.text();
+        if (response.status === 401 || response.status === 302) {
+            throw invoiceAuthError('session_expired', 'E10 登录态已失效，请先向用户确认 E10 登录域名，再运行 weaver-work-cli auth login --base-url <域名> 完成登录', { httpStatus: response.status });
+        }
+        let value = {};
+        try {
+            value = text ? JSON.parse(text) : {};
+        }
+        catch {
+            throw invoiceNetworkError('protocol', `接口返回不是合法 JSON（HTTP ${response.status}）`, { retryable: false });
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw new InvoiceCliError('api', 'http_error', `泛微接口 HTTP ${response.status}`, {
+                code: response.status,
+                details: { status: response.status, message: responseMessage(value) },
                 exitCode: 1,
             });
         }
-        return value;
+        return handleBusinessResponse(value, () => invoiceMultipartRequest(request, false), canRetryExpiredToken && Boolean(token));
     }
-    return {
-        invoiceRequest,
-        async invoiceMultipartRequest(request) {
-            const { method = 'POST', path, query, fields = {}, file, needsInvoiceToken = true, timeoutMs = 30_000, } = request;
-            if (!file && !fields.url) {
-                throw invoiceValidationError('input_invalid', 'multipart 请求需要文件或 URL');
-            }
-            assertPath(path);
-            const token = await ensureContext(needsInvoiceToken, timeoutMs, path);
-            const session = await ensureSession();
-            const form = new FormData();
-            for (const [key, value] of Object.entries(fields)) {
-                if (value === undefined || value === null)
-                    continue;
-                form.append(key, typeof value === 'string' ? value : JSON.stringify(value));
-            }
-            if (file) {
-                const content = await readFile(file.path);
-                form.append('file', new Blob([content], { type: file.mimeType || 'application/octet-stream' }), file.name);
-            }
-            const response = await fetchWithTimeout(withQuery(session.getBaseUrl(), path, query), {
-                method,
-                headers: requestHeaders(session, token),
-                body: form,
-                redirect: 'manual',
-            }, timeoutMs);
-            const text = await response.text();
-            if (response.status === 401 || response.status === 302) {
-                throw invoiceAuthError('session_expired', 'E10 登录态已失效，请先向用户确认 E10 登录域名，再运行 weaver-work-cli auth login --base-url <域名> 完成登录', { httpStatus: response.status });
-            }
+    async function invoiceDownload({ id, fid, needLog = false, timeoutMs = 30_000 }, canRetryExpiredToken = true) {
+        const token = await ensureContext(true, timeoutMs, '/api/inc/file/download');
+        const session = await ensureSession();
+        const url = withQuery(session.getBaseUrl(), '/api/inc/file/download', { id, fid, needLog });
+        const response = await fetchWithTimeout(url, {
+            method: 'GET',
+            headers: {
+                ...requestHeaders(session, token),
+                Accept: 'application/octet-stream, application/pdf, */*',
+            },
+            redirect: 'manual',
+        }, timeoutMs);
+        if (response.status === 401 || response.status === 302) {
+            throw invoiceAuthError('session_expired', 'E10 登录态已失效，请先向用户确认 E10 登录域名，再运行 weaver-work-cli auth login --base-url <域名> 完成登录', { httpStatus: response.status });
+        }
+        const contentType = response.headers.get('content-type') || 'application/octet-stream';
+        const declaredLength = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_DOWNLOAD_BYTES) {
+            throw invoiceNetworkError('response_too_large', `下载文件超过 ${MAX_DOWNLOAD_BYTES} 字节限制`, { retryable: false });
+        }
+        const content = Buffer.from(await response.arrayBuffer());
+        const looksLikeJson = /^[\s\r\n]*[\[{]/u.test(content.subarray(0, 64).toString('utf8'));
+        if (response.status < 200 || response.status >= 300 || contentType.includes('json') || looksLikeJson) {
             let value = {};
             try {
-                value = text ? JSON.parse(text) : {};
+                value = JSON.parse(content.toString('utf8'));
             }
             catch {
-                throw invoiceNetworkError('protocol', `接口返回不是合法 JSON（HTTP ${response.status}）`, { retryable: false });
-            }
-            if (response.status < 200 || response.status >= 300) {
-                throw new InvoiceCliError('api', 'http_error', `泛微接口 HTTP ${response.status}`, {
-                    code: response.status,
-                    details: { status: response.status, message: responseMessage(value) },
-                    exitCode: 1,
-                });
-            }
-            const code = responseCode(value);
-            if (code !== undefined && code !== 0 && code !== 200) {
-                throw new InvoiceCliError('api', 'business_error', responseMessage(value), {
-                    code: String(code),
-                    details: { ret: code },
-                    exitCode: 1,
-                });
-            }
-            return value;
-        },
-        async invoiceDownload({ id, fid, needLog = false, timeoutMs = 30_000 }) {
-            const token = await ensureContext(true, timeoutMs, '/api/inc/file/download');
-            const session = await ensureSession();
-            const url = withQuery(session.getBaseUrl(), '/api/inc/file/download', { id, fid, needLog });
-            const response = await fetchWithTimeout(url, {
-                method: 'GET',
-                headers: {
-                    ...requestHeaders(session, token),
-                    Accept: 'application/octet-stream, application/pdf, */*',
-                },
-                redirect: 'manual',
-            }, timeoutMs);
-            if (response.status === 401 || response.status === 302) {
-                throw invoiceAuthError('session_expired', 'E10 登录态已失效，请先向用户确认 E10 登录域名，再运行 weaver-work-cli auth login --base-url <域名> 完成登录', { httpStatus: response.status });
+                value = {};
             }
-            const contentType = response.headers.get('content-type') || 'application/octet-stream';
-            const declaredLength = Number(response.headers.get('content-length'));
-            if (Number.isFinite(declaredLength) && declaredLength > MAX_DOWNLOAD_BYTES) {
-                throw invoiceNetworkError('response_too_large', `下载文件超过 ${MAX_DOWNLOAD_BYTES} 字节限制`, { retryable: false });
+            if (isInvoiceSessionExpired(value)) {
+                await clearCachedInvoiceToken();
+                if (canRetryExpiredToken && token)
+                    return invoiceDownload({ id, fid, needLog, timeoutMs }, false);
+                throw invoiceAuthError('invoice_session_expired', '发票业务登录态已失效，已清理本地发票 Token；请重新运行 weaver-work-cli auth login --base-url <域名> 后再试', { ret: responseCode(value), status: response.status });
             }
-            const content = Buffer.from(await response.arrayBuffer());
-            const looksLikeJson = /^[\s\r\n]*[\[{]/u.test(content.subarray(0, 64).toString('utf8'));
-            if (response.status < 200 || response.status >= 300 || contentType.includes('json') || looksLikeJson) {
-                let value = {};
-                try {
-                    value = JSON.parse(content.toString('utf8'));
-                }
-                catch {
-                    value = {};
-                }
-                throw new InvoiceCliError('api', 'download_failed', responseMessage(value) || `下载失败（HTTP ${response.status}）`, {
-                    code: response.status,
-                    details: { status: response.status, ret: responseCode(value) },
-                    exitCode: 1,
-                });
-            }
-            if (!content.length) {
-                throw invoiceNetworkError('protocol', '下载接口返回空文件', { retryable: false });
-            }
-            if (content.length > MAX_DOWNLOAD_BYTES) {
-                throw invoiceNetworkError('response_too_large', `下载文件超过 ${MAX_DOWNLOAD_BYTES} 字节限制`, { retryable: false });
-            }
-            return { content, contentType };
-        },
+            throw new InvoiceCliError('api', 'download_failed', responseMessage(value) || `下载失败（HTTP ${response.status}）`, {
+                code: response.status,
+                details: { status: response.status, ret: responseCode(value) },
+                exitCode: 1,
+            });
+        }
+        if (!content.length) {
+            throw invoiceNetworkError('protocol', '下载接口返回空文件', { retryable: false });
+        }
+        if (content.length > MAX_DOWNLOAD_BYTES) {
+            throw invoiceNetworkError('response_too_large', `下载文件超过 ${MAX_DOWNLOAD_BYTES} 字节限制`, { retryable: false });
+        }
+        return { content, contentType };
+    }
+    return {
+        invoiceRequest,
+        invoiceMultipartRequest,
+        invoiceDownload,
         getSession,
         invalidateToken() {
             invoiceToken = null;
-            void tokenStore?.clear();
+            void clearCachedInvoiceToken();
         },
     };
 }

package/dist/shortcuts/invoice/index.js

@@ -48,6 +48,11 @@ function intOption(value) {
     const parsed = Number(value);
     return Number.isInteger(parsed) ? parsed : undefined;
 }
+function stringOption(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return String(value);
+}
 function successEnvelope(operation, result) {
     return {
         schemaVersion: 1,
@@ -111,7 +116,7 @@ export const invoiceShortcut = {
                 content: opts.content,
                 page_size: intOption(opts.pageSize),
                 start_pos: intOption(opts.startPos),
-                sreim: intOption(opts.sreim),
+                sreim: stringOption(opts.sreim),
             }));
         }));
         const enterprise = invoice.command('enterprise').description('Enterprise invoice folder commands');
@@ -128,7 +133,7 @@ export const invoiceShortcut = {
                 content: opts.content,
                 page_size: intOption(opts.pageSize),
                 start_pos: intOption(opts.startPos),
-                sreim: intOption(opts.sreim),
+                sreim: stringOption(opts.sreim),
             }));
         }));
         invoice.command('get')

package/dist/shortcuts/invoice/manifest.js

@@ -20,10 +20,10 @@ const listProperties = {
     total_end: { type: 'string', pattern: '^\\d+(\\.\\d{1,2})?$' },
     attribute: { type: 'integer', enum: [0, 1, 2] },
     sreim: {
-        type: 'integer',
-        enum: [0, 1, 2, 3, 4],
-        default: 3,
-        description: '报销状态：0=全部发票，1=发票报销中，2=报销完成，3=未报销发票，4=不可报销',
+        type: 'string',
+        enum: ['0', '1', '2', '3', '4'],
+        default: '3',
+        description: '报销状态筛选。默认不要传本字段，CLI 会使用 "3"=未报销发票；只有用户明确要求全部/报销中/已报销/不可报销时才传。取值："0"=全部发票，"1"=发票报销中，"2"=报销完成，"3"=未报销发票，"4"=不可报销',
     },
     valids: { type: 'array', items: { type: 'integer', enum: [0, 1, 2, 3, 4, 5] } },
     sources: { type: 'array', items: { type: 'integer' } },
@@ -43,21 +43,26 @@ const listProperties = {
             required: ['sort_type', 'sort'],
         },
     },
-    bill_type: { type: 'integer' },
+    bill_type: {
+        type: 'integer',
+        enum: [0, 1],
+        default: 0,
+        description: '票据类型：0=发票，1=凭证。默认不要传本字段，CLI 会使用 0 查询发票；只有用户明确要求查凭证时才传 1。',
+    },
 };
 export const invoiceOperations = [
     {
         name: 'invoice.list',
         risk: 'read',
         scope: 'personal',
-        fixed: { flag: 0, defaultSreim: 3 },
+        fixed: { flag: 0, defaultSreim: '3', defaultBillType: 0 },
         inputSchema: { type: 'object', additionalProperties: false, properties: listProperties },
     },
     {
         name: 'invoice.enterprise.list',
         risk: 'read',
         scope: 'enterprise',
-        fixed: { flag: 6, defaultSreim: 3 },
+        fixed: { flag: 6, defaultSreim: '3', defaultBillType: 0 },
         inputSchema: { type: 'object', additionalProperties: false, properties: listProperties },
     },
     {
@@ -76,7 +81,7 @@ export const invoiceOperations = [
     {
         name: 'invoice.upload',
         risk: 'external-artifact',
-        fixed: { ocr: 1 },
+        fixed: { ocr: 0 },
         inputSchema: {
             type: 'object',
             additionalProperties: false,
@@ -106,7 +111,7 @@ export const invoiceOperations = [
     {
         name: 'invoice.validate.preview',
         risk: 'external-read',
-        fixed: { flag: 100, is_save: 1, needLog: false },
+        fixed: { flag: 100, is_save: 1, needLog: true },
         inputSchema: {
             type: 'object',
             additionalProperties: false,
@@ -125,8 +130,14 @@ export const invoiceOperations = [
             additionalProperties: false,
             properties: {
                 file: { type: 'string', minLength: 1 },
-                validate: { type: 'boolean' },
-                syncToOa: { type: 'boolean' },
+                validate: {
+                    type: 'boolean',
+                    description: '是否在导入时请求服务端查验。正常上传发票流程默认应传 true；只有用户明确要求跳过查验时才传 false。',
+                },
+                syncToOa: {
+                    type: 'boolean',
+                    description: '是否同步到 OA。validate=true 时必须为 true；正常导入推荐传 true。',
+                },
             },
             required: ['file', 'validate', 'syncToOa'],
         },

package/dist/shortcuts/invoice/operations/ocr-preview.js

@@ -1,4 +1,5 @@
 import { InvoiceCliError, invoiceValidationError } from '../errors.js';
+import { toErrorEnvelope } from '../../../core/errors.js';
 import { previewOcr, uploadFromInput, uploadInvoiceFile, workflow } from './shared.js';
 export class InvoiceOcrPreviewOperation {
     name = 'invoice.ocr.preview';
@@ -10,16 +11,18 @@ export class InvoiceOcrPreviewOperation {
             throw invoiceValidationError('input_ambiguous', 'upload 与 file/url 只能选择一种来源');
         }
         const suppliedUpload = uploadFromInput(input);
-        const upload = suppliedUpload || await uploadInvoiceFile(input, host);
+        const upload = suppliedUpload || await uploadInvoiceFile(input, host, { ocr: true });
         let ocr;
         try {
             ocr = await previewOcr(upload, host);
         }
         catch (error) {
             if (!suppliedUpload) {
-                throw new InvoiceCliError('partial', 'artifact_uploaded', '文件已上传但 OCR 预览失败，不能自动重复上传', {
+                const cause = toErrorEnvelope(error);
+                throw new InvoiceCliError('partial', 'artifact_uploaded', `文件已上传但 OCR 预览失败：${cause.message}`, {
+                    code: cause.code,
                     partialData: { upload, workflow: workflow('invoice.ocr.preview', 'OCR_RUNNING') },
-                    details: { stage: 'ocr' },
+                    details: { stage: 'ocr', cause },
                     exitCode: 11,
                 });
             }