meegle-cli 0.1.3 → 0.1.4

package/README.md

@@ -18,6 +18,7 @@
 - 写操作会先输出风险摘要
 - 交互终端里默认要求确认
 - 非交互环境（脚本 / AI / CI）必须显式传 `--yes`
+- 批量目标超过安全阈值时，必须显式传 `--force-batch`
 
 交互终端的目标体验是：
 
@@ -455,6 +456,7 @@ meegle --profile default workitem search by-params \
 - 常用查询优先走直接参数，不强制写 JSON 文件
 - 常用写操作优先走直接参数，例如 `--name`、`--desc`、`--content`
 - 非交互环境下，写操作必须显式传 `--yes`
+- 超大批量写操作必须显式传 `--force-batch`
 - 复杂请求体可使用 `--body <json>` 或 `--body-file <path>`
 - 复杂查询参数可使用 `--query-file <path>`
 - 自定义字段统一使用 `--field field_key=value`
@@ -547,6 +549,21 @@ meegle auth init \
 meegle --profile default --yes workitem update ...
 ```
 
+### 7. 批量写操作被拒绝
+
+如果报错类似：
+
+- `BATCH_THRESHOLD_EXCEEDED`
+
+说明目标数量已经超过安全阈值。  
+这类场景默认拒绝，避免一次误伤太多数据。
+
+如果确实要继续，显式传：
+
+```bash
+meegle --profile default --yes --force-batch workitem freeze --ids ...
+```
+
 ## 命令总览
 
 - `auth`: `init`, `status`
@@ -595,3 +612,5 @@ npm test
 4. `planning_version` 这类关联字段，先查出被关联工作项的 `id`，再筛主工作项
 5. `field_value_pairs` 是写操作格式，不是搜索格式
 6. 非交互环境里，写操作必须显式传 `--yes`
+7. 对批量危险操作，超过阈值时必须显式传 `--force-batch`
+8. 遇到安全错误时，优先读取 `error.code`，不要只匹配自然语言

package/dist/cli.js

@@ -734,6 +734,15 @@ async function buildWorkItemRemovePreview(ctx, args) {
         confirmPhrase: '确认删除',
     };
 }
+function buildBatchIdsPreview(action, ids) {
+    return {
+        lines: [
+            `action: ${action}`,
+            `targetIds: ${ids.join(',')}`,
+        ],
+        targetCount: ids.length,
+    };
+}
 function resolveGlobal(program) {
     return program.opts();
 }
@@ -997,11 +1006,14 @@ function registerWorkItem(program) {
         .requiredOption('--ids <ids>', '工作项 ID，逗号分隔')
         .action(async (options) => {
         const global = resolveGlobal(program);
+        const ids = parseNumberList(options.ids, 'ids');
         await runGuarded({
             id: 'workitem.freeze',
             authPolicy: 'PLUGIN_WITH_USER_KEY',
             endpoint: { method: 'PUT', path: '/open_api/work_item/freeze' },
-        }, global, async (ctx) => ctx.client.workItem.freeze(parseNumberList(options.ids, 'ids'), true, { auth: ctx.auth }));
+        }, global, async (ctx) => ctx.client.workItem.freeze(ids, true, { auth: ctx.auth }), {
+            riskPreview: async () => buildBatchIdsPreview('freeze', ids),
+        });
         printOk(Boolean(global.json));
     });
     workItem
@@ -1010,11 +1022,14 @@ function registerWorkItem(program) {
         .requiredOption('--ids <ids>', '工作项 ID，逗号分隔')
         .action(async (options) => {
         const global = resolveGlobal(program);
+        const ids = parseNumberList(options.ids, 'ids');
         await runGuarded({
             id: 'workitem.unfreeze',
             authPolicy: 'PLUGIN_WITH_USER_KEY',
             endpoint: { method: 'PUT', path: '/open_api/work_item/freeze' },
-        }, global, async (ctx) => ctx.client.workItem.freeze(parseNumberList(options.ids, 'ids'), false, { auth: ctx.auth }));
+        }, global, async (ctx) => ctx.client.workItem.freeze(ids, false, { auth: ctx.auth }), {
+            riskPreview: async () => buildBatchIdsPreview('unfreeze', ids),
+        });
         printOk(Boolean(global.json));
     });
     workItem
@@ -2057,6 +2072,7 @@ export function buildCli() {
         .option('--compat-auth', '读接口使用兼容模式 (x-auth-mode=0)，默认严格模式')
         .option('--json', '输出 JSON')
         .option('--yes', '跳过写操作确认，脚本 / AI / CI 使用')
+        .option('--force-batch', '批量目标超过安全阈值时，显式确认继续执行')
         .addHelpText('after', `
 常用示例：
   meegle auth init --target-profile demo --plugin-id <id> --plugin-secret <secret> --default-user-key <userKey>

package/dist/core/auth-policy.js

@@ -40,7 +40,13 @@ export function isUserTokenOnlyEndpoint(path) {
 }
 export function assertCommandSupported(meta) {
     if (meta.authPolicy === 'USER_TOKEN_REQUIRED') {
-        throw new CliError(`命令 "${meta.id}" 依赖 user_access_token，当前 CLI 运行在 plugin-only 模式，已拒绝执行。`, 2);
+        throw new CliError(`命令 "${meta.id}" 依赖 user_access_token，当前 CLI 运行在 plugin-only 模式，已拒绝执行。`, {
+            exitCode: 2,
+            code: 'USER_TOKEN_REQUIRED',
+            details: {
+                command: meta.id,
+            },
+        });
     }
 }
 export function assertEndpointAllowed(endpoint) {
@@ -48,7 +54,14 @@ export function assertEndpointAllowed(endpoint) {
         return;
     }
     if (isUserTokenOnlyEndpoint(endpoint.path)) {
-        throw new CliError(`接口 ${endpoint.method} ${endpoint.path} 在文档中标注为仅支持 user_access_token，plugin-only 模式已拒绝。`, 2);
+        throw new CliError(`接口 ${endpoint.method} ${endpoint.path} 在文档中标注为仅支持 user_access_token，plugin-only 模式已拒绝。`, {
+            exitCode: 2,
+            code: 'ENDPOINT_REQUIRES_USER_TOKEN',
+            details: {
+                method: endpoint.method,
+                path: endpoint.path,
+            },
+        });
     }
 }
 /**

package/dist/core/cli-error.d.ts

@@ -1,4 +1,11 @@
+export interface CliErrorOptions {
+    exitCode?: number;
+    code?: string;
+    details?: Record<string, unknown>;
+}
 export declare class CliError extends Error {
     readonly exitCode: number;
-    constructor(message: string, exitCode?: number);
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, exitCodeOrOptions?: number | CliErrorOptions);
 }

package/dist/core/cli-error.js

@@ -1,9 +1,16 @@
 export class CliError extends Error {
     exitCode;
-    constructor(message, exitCode = 1) {
+    code;
+    details;
+    constructor(message, exitCodeOrOptions = 1) {
         super(message);
         this.name = 'CliError';
-        this.exitCode = exitCode;
+        const options = typeof exitCodeOrOptions === 'number'
+            ? { exitCode: exitCodeOrOptions }
+            : exitCodeOrOptions;
+        this.exitCode = options.exitCode ?? 1;
+        this.code = options.code ?? 'CLI_ERROR';
+        this.details = options.details;
         Object.setPrototypeOf(this, CliError.prototype);
     }
 }

package/dist/core/command-guard.d.ts

@@ -6,6 +6,7 @@ export interface RuntimeOptions {
     userKey?: string;
     compatAuth?: boolean;
     yes?: boolean;
+    forceBatch?: boolean;
 }
 export interface GuardContext {
     profileName: string;
@@ -17,6 +18,7 @@ export interface GuardContext {
 export interface RiskPreview {
     lines?: string[];
     confirmPhrase?: string;
+    targetCount?: number;
 }
 export interface GuardHooks {
     riskPreview?: (ctx: GuardContext) => Promise<RiskPreview | undefined>;

package/dist/core/command-guard.js

@@ -3,6 +3,8 @@ import { CliError } from './cli-error.js';
 import { assertCommandSupported, assertEndpointAllowed, getCommandRiskLevel, } from './auth-policy.js';
 import { getProfile } from './config-store.js';
 import { createClient } from './client-factory.js';
+const BATCH_WARNING_THRESHOLD = 20;
+const BATCH_FORCE_THRESHOLD = 100;
 function resolveUserKey(runtimeUserKey, defaultUserKey) {
     if (runtimeUserKey?.trim()) {
         return runtimeUserKey.trim();
@@ -64,6 +66,42 @@ async function confirmWriteRisk(meta, runtime, profileName, preview) {
         return;
     }
     const summary = [...buildRiskSummary(meta, profileName, riskLevel), ...(preview?.lines ?? [])];
+    const targetCount = preview?.targetCount;
+    if (typeof targetCount === 'number') {
+        summary.push(`targetCount: ${targetCount}`);
+        if (targetCount > BATCH_WARNING_THRESHOLD) {
+            summary.push(`批量目标超过 ${BATCH_WARNING_THRESHOLD} 条，请再次确认范围。`);
+        }
+        if (targetCount > BATCH_FORCE_THRESHOLD && !runtime.forceBatch) {
+            throw new CliError(`批量目标达到 ${targetCount} 条，已超过安全阈值 ${BATCH_FORCE_THRESHOLD}。如确认继续，请显式传 --force-batch。`, {
+                exitCode: 2,
+                code: 'BATCH_THRESHOLD_EXCEEDED',
+                details: {
+                    target_count: targetCount,
+                    threshold: BATCH_FORCE_THRESHOLD,
+                    command: meta.id,
+                },
+            });
+        }
+    }
+    if (!isInteractiveShell()) {
+        if (runtime.yes) {
+            process.stderr.write('即将执行写操作：\n');
+            for (const line of summary) {
+                process.stderr.write(`- ${line}\n`);
+            }
+            return;
+        }
+        throw new CliError('非交互环境下，写操作需要显式传 --yes。', {
+            exitCode: 2,
+            code: 'WRITE_CONFIRMATION_REQUIRED',
+            details: {
+                command: meta.id,
+                risk_level: riskLevel,
+                risk_summary: summary,
+            },
+        });
+    }
     process.stderr.write('即将执行写操作：\n');
     for (const line of summary) {
         process.stderr.write(`- ${line}\n`);
@@ -71,25 +109,32 @@ async function confirmWriteRisk(meta, runtime, profileName, preview) {
     if (runtime.yes) {
         return;
     }
-    if (!isInteractiveShell()) {
-        throw new CliError('非交互环境下，写操作需要显式传 --yes。', 2);
-    }
     const rl = createInterface({
         input: process.stdin,
         output: process.stderr,
     });
     try {
+        process.stderr.write('即将执行写操作：\n');
+        for (const line of summary) {
+            process.stderr.write(`- ${line}\n`);
+        }
         if (riskLevel === 'DANGEROUS') {
             const confirmPhrase = preview?.confirmPhrase ?? '确认执行';
             const answer = (await rl.question(`危险操作。请输入“${confirmPhrase}”确认继续执行: `)).trim();
             if (answer !== confirmPhrase) {
-                throw new CliError('已取消执行。', 2);
+                throw new CliError('已取消执行。', {
+                    exitCode: 2,
+                    code: 'OPERATION_CANCELLED',
+                });
             }
             return;
         }
         const answer = (await rl.question('确认继续执行写操作？[y/N] ')).trim().toLowerCase();
         if (answer !== 'y' && answer !== 'yes') {
-            throw new CliError('已取消执行。', 2);
+            throw new CliError('已取消执行。', {
+                exitCode: 2,
+                code: 'OPERATION_CANCELLED',
+            });
         }
     }
     finally {

package/dist/core/error-handler.js

@@ -2,51 +2,122 @@ import { CommanderError } from 'commander';
 import { ErrorCodes, MeegoError } from 'meeglesdk';
 import { CliError } from './cli-error.js';
 const TOKEN_TYPE_WRONG = 1000052755;
-function print(message) {
+function isJsonMode() {
+    return process.argv.includes('--json');
+}
+function printJson(payload) {
+    process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+function printText(message) {
     process.stderr.write(`${message}\n`);
 }
+/**
+ * 让 Agent 能稳定识别错误类型，比只输出自然语言更容易做重试和纠偏。
+ */
+function printStructuredError(payload) {
+    if (isJsonMode()) {
+        printJson({
+            ok: false,
+            error: {
+                code: payload.code,
+                message: payload.message,
+                ...(payload.details ?? {}),
+            },
+        });
+        return;
+    }
+    printText(`[${payload.code}] ${payload.message}`);
+    if (payload.details?.log_id) {
+        printText(`log_id: ${String(payload.details.log_id)}`);
+    }
+}
 function handleMeegoError(error) {
     switch (error.errCode) {
         case TOKEN_TYPE_WRONG:
-            print('接口仅支持 user_access_token；当前 CLI 为 plugin-only 模式，命令已拒绝。');
+            printStructuredError({
+                code: 'USER_TOKEN_REQUIRED',
+                message: '接口仅支持 user_access_token；当前 CLI 为 plugin-only 模式，命令已拒绝。',
+                details: {
+                    err_code: error.errCode,
+                    log_id: error.logId,
+                },
+            });
             return 2;
         case ErrorCodes.PLUGIN_TOKEN_MUST_HAVE_USER_KEY:
-            print('缺少 userKey。请传 --user-key 或在 auth init 中配置 defaultUserKey。');
+            printStructuredError({
+                code: 'USER_KEY_REQUIRED',
+                message: '缺少 userKey。请传 --user-key 或在 auth init 中配置 defaultUserKey。',
+                details: {
+                    err_code: error.errCode,
+                    log_id: error.logId,
+                },
+            });
             return 2;
         case ErrorCodes.X_USER_KEY_WRONG:
-            print('X-User-Key 无效。请检查 --user-key 是否正确。');
+            printStructuredError({
+                code: 'INVALID_USER_KEY',
+                message: 'X-User-Key 无效。请检查 --user-key 是否正确。',
+                details: {
+                    err_code: error.errCode,
+                    log_id: error.logId,
+                },
+            });
             return 2;
         case ErrorCodes.CHECK_TOKEN_FAILED:
         case ErrorCodes.TOKEN_NOT_EXIST:
         case ErrorCodes.CHECK_TOKEN_PERM_FAILED:
-            print(`鉴权失败(${error.errCode})：${error.errMsg}`);
+            printStructuredError({
+                code: 'AUTH_FAILED',
+                message: `鉴权失败(${error.errCode})：${error.errMsg}`,
+                details: {
+                    err_code: error.errCode,
+                    log_id: error.logId,
+                },
+            });
             return 3;
         default:
-            print(`API 错误(${error.errCode})：${error.errMsg}`);
-            if (error.logId) {
-                print(`log_id: ${error.logId}`);
-            }
+            printStructuredError({
+                code: 'API_ERROR',
+                message: `API 错误(${error.errCode})：${error.errMsg}`,
+                details: {
+                    err_code: error.errCode,
+                    log_id: error.logId,
+                },
+            });
             return 1;
     }
 }
 export function handleCliError(error) {
     if (error instanceof CommanderError) {
         if (error.code !== 'commander.helpDisplayed') {
-            print(error.message);
+            printStructuredError({
+                code: 'COMMAND_ARGUMENT_ERROR',
+                message: error.message,
+            });
         }
         return error.exitCode;
     }
     if (error instanceof CliError) {
-        print(error.message);
+        printStructuredError({
+            code: error.code,
+            message: error.message,
+            details: error.details,
+        });
         return error.exitCode;
     }
     if (error instanceof MeegoError) {
         return handleMeegoError(error);
     }
     if (error instanceof Error) {
-        print(error.message);
+        printStructuredError({
+            code: 'UNEXPECTED_ERROR',
+            message: error.message,
+        });
         return 1;
     }
-    print('未知错误');
+    printStructuredError({
+        code: 'UNKNOWN_ERROR',
+        message: '未知错误',
+    });
     return 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meegle-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Plugin-only CLI for Feishu Project (Meegle) based on meeglesdk",
   "type": "module",
   "bin": {