meegle-cli 0.1.2 → 0.1.4

package/README-en.md

@@ -3,6 +3,22 @@
 CLI for Feishu Project (Meegle).  
 Current mode is `plugin-only`: it supports `plugin_access_token / virtual_plugin_token`, but not `user_access_token`.
 
+## Risk Notes
+
+This CLI can directly create, update, and delete Meegle data.  
+In a B2B environment, the main risks are:
+
+- using the wrong `profile`
+- using the wrong `projectKey`
+- letting scripts or AI tools write to production by mistake
+- running bulk mutations without checking the target scope first
+
+Starting from `0.1.3`:
+
+- write commands print a risk summary first
+- interactive terminals require confirmation
+- non-interactive environments (scripts / AI / CI) must pass `--yes`
+
 ## Install
 
 ```bash
@@ -78,6 +94,7 @@ meegle --profile default workitem get \
 
 ```bash
 meegle --profile default workitem create \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --name "Login improvement" \
@@ -91,6 +108,7 @@ meegle --profile default workitem create \
 
 ```bash
 meegle --profile default comment add \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -165,6 +183,16 @@ meegle --profile default workitem search by-params \
 
 Replace `1234567890` in the example file with the real version work item ID.
 
+## Write Safety
+
+In non-interactive environments, write commands must pass `--yes`.
+
+Example:
+
+```bash
+meegle --profile default --yes workitem update ...
+```
+
 ## Agent Notes
 
 If you use this CLI from an AI agent or automation:
@@ -173,6 +201,7 @@ If you use this CLI from an AI agent or automation:
 2. do not guess request shapes from web URLs
 3. use `workitem search by-params` for custom fields and related fields
 4. `field_value_pairs` is for create/update, not for search
+5. in non-interactive environments, write commands must pass `--yes`
 
 ## Examples
 

package/README.md

@@ -3,6 +3,34 @@
 面向飞书项目（Meegle）的命令行工具。  
 当前版本运行在 `plugin-only` 模式：只支持 `plugin_access_token / virtual_plugin_token`，不支持 `user_access_token`。
 
+## 风险提示
+
+这是一个可直接对空间数据执行增删改的 CLI。  
+在 toB 场景里，误操作成本很高，尤其是：
+
+- 打错 `profile`
+- 打错 `projectKey`
+- 把脚本或 AI 的写操作直接打到线上
+- 批量更新 / 删除目标超出预期
+
+从 `0.1.3` 起：
+
+- 写操作会先输出风险摘要
+- 交互终端里默认要求确认
+- 非交互环境（脚本 / AI / CI）必须显式传 `--yes`
+- 批量目标超过安全阈值时，必须显式传 `--force-batch`
+
+交互终端的目标体验是：
+
+- 人类用户只需要回复简短确认词，例如 `确认删除`
+- Agent / 脚本才需要显式 `--yes`
+
+建议：
+
+1. 先在测试空间验证命令
+2. 再切生产 profile
+3. 对写操作显式确认 `profile / projectKey / id`
+
 ## 适用对象
 
 - 想在终端里查询空间、工作项、视图、评论、子任务
@@ -159,6 +187,7 @@ meegle --profile default workitem get \
 
 ```bash
 meegle --profile default workitem create \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --name "登录优化" \
@@ -172,6 +201,7 @@ meegle --profile default workitem create \
 
 ```bash
 meegle --profile default workitem update \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -183,6 +213,7 @@ meegle --profile default workitem update \
 
 ```bash
 meegle --profile default comment add \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -194,6 +225,7 @@ meegle --profile default comment add \
 
 ```bash
 meegle --profile default comment add \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -205,6 +237,7 @@ meegle --profile default comment add \
 
 ```bash
 meegle --profile default subtask create \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -222,6 +255,7 @@ meegle --profile default subtask create \
 
 ```bash
 meegle --profile default workflow state-change \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -234,6 +268,7 @@ meegle --profile default workflow state-change \
 
 ```bash
 meegle --profile default workflow node-operate \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -377,7 +412,7 @@ meegle --profile default workitem search filter \
 
 示例文件：
 
-- [examples/version-search-filter.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/version-search-filter.json)
+- [examples/version-search-filter.json](./examples/version-search-filter.json)
 
 你要从返回结果里拿到真正的版本实例 `id`。
 
@@ -393,7 +428,7 @@ meegle --profile default workitem search by-params \
 
 示例文件：
 
-- [examples/story-by-planning-version.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/story-by-planning-version.json)
+- [examples/story-by-planning-version.json](./examples/story-by-planning-version.json)
 
 重点：
 
@@ -420,6 +455,8 @@ 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`
@@ -497,6 +534,36 @@ meegle auth init \
 3. 请求体键是不是对
    - `field_value_pairs` 用于创建 / 更新，不是搜索条件
 
+### 6. 写操作在脚本 / Agent 里被拒绝
+
+如果报错类似：
+
+- `非交互环境下，写操作需要显式传 --yes`
+
+说明当前进程不是交互终端。  
+这是预期行为，用来拦截脚本和 AI 的误操作。
+
+处理方式：
+
+```bash
+meegle --profile default --yes workitem update ...
+```
+
+### 7. 批量写操作被拒绝
+
+如果报错类似：
+
+- `BATCH_THRESHOLD_EXCEEDED`
+
+说明目标数量已经超过安全阈值。  
+这类场景默认拒绝，避免一次误伤太多数据。
+
+如果确实要继续，显式传：
+
+```bash
+meegle --profile default --yes --force-batch workitem freeze --ids ...
+```
+
 ## 命令总览
 
 - `auth`: `init`, `status`
@@ -530,10 +597,10 @@ npm test
 
 可直接复制修改的模板在：
 
-- [examples/view-list.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/view-list.json)
-- [examples/view-fix-items.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/view-fix-items.json)
-- [examples/version-search-filter.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/version-search-filter.json)
-- [examples/story-by-planning-version.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/story-by-planning-version.json)
+- [examples/view-list.json](./examples/view-list.json)
+- [examples/view-fix-items.json](./examples/view-fix-items.json)
+- [examples/version-search-filter.json](./examples/version-search-filter.json)
+- [examples/story-by-planning-version.json](./examples/story-by-planning-version.json)
 
 ## AI / Agent 提示
 
@@ -544,3 +611,6 @@ npm test
 3. 自定义字段和关联字段优先走 `workitem search by-params`
 4. `planning_version` 这类关联字段，先查出被关联工作项的 `id`，再筛主工作项
 5. `field_value_pairs` 是写操作格式，不是搜索格式
+6. 非交互环境里，写操作必须显式传 `--yes`
+7. 对批量危险操作，超过阈值时必须显式传 `--force-batch`
+8. 遇到安全错误时，优先读取 `error.code`，不要只匹配自然语言

package/dist/cli.js

@@ -708,6 +708,41 @@ async function buildWorkflowNodeOperateRequest(options) {
         fields: fields.length > 0 ? fields : undefined,
     };
 }
+/**
+ * 删除前先读出目标摘要，能明显降低误删概率。
+ *
+ * @param ctx 守卫上下文
+ * @param args 工作项定位参数
+ */
+async function buildWorkItemRemovePreview(ctx, args) {
+    const workItemId = parseInteger(args.id, 'id');
+    const items = await ctx.client.workItem.query(args.projectKey, args.type, {
+        work_item_ids: [workItemId],
+        fields: ['name'],
+    }, { auth: ctx.auth });
+    const target = items[0];
+    if (!target) {
+        throw new CliError('删除前未找到目标工作项，请先确认 projectKey、type 和 id 是否正确。', 2);
+    }
+    return {
+        lines: [
+            `projectKey: ${args.projectKey}`,
+            `workItemType: ${args.type}`,
+            `workItemId: ${workItemId}`,
+            `workItemName: ${target.name}`,
+        ],
+        confirmPhrase: '确认删除',
+    };
+}
+function buildBatchIdsPreview(action, ids) {
+    return {
+        lines: [
+            `action: ${action}`,
+            `targetIds: ${ids.join(',')}`,
+        ],
+        targetCount: ids.length,
+    };
+}
 function resolveGlobal(program) {
     return program.opts();
 }
@@ -960,7 +995,9 @@ function registerWorkItem(program) {
             id: 'workitem.remove',
             authPolicy: 'PLUGIN_WITH_USER_KEY',
             endpoint: { method: 'DELETE', path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id' },
-        }, global, async (ctx) => ctx.client.workItem.remove(options.projectKey, options.type, parseInteger(options.id, 'id'), { auth: ctx.auth }));
+        }, global, async (ctx) => ctx.client.workItem.remove(options.projectKey, options.type, parseInteger(options.id, 'id'), { auth: ctx.auth }), {
+            riskPreview: async (ctx) => buildWorkItemRemovePreview(ctx, options),
+        });
         printOk(Boolean(global.json));
     });
     workItem
@@ -969,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
@@ -982,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
@@ -2028,6 +2071,8 @@ export function buildCli() {
         .option('--user-key <userKey>', '本次命令覆盖 userKey')
         .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.d.ts

@@ -1,5 +1,6 @@
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 export type AuthPolicy = 'NONE' | 'PLUGIN_WITH_USER_KEY' | 'PLUGIN_OPTIONAL_USER_KEY' | 'USER_TOKEN_REQUIRED';
+export type RiskLevel = 'READ_ONLY' | 'WRITE' | 'DANGEROUS';
 export interface EndpointRef {
     method: HttpMethod;
     path: string;
@@ -12,3 +13,7 @@ export interface CommandMeta {
 export declare function isUserTokenOnlyEndpoint(path: string): boolean;
 export declare function assertCommandSupported(meta: CommandMeta): void;
 export declare function assertEndpointAllowed(endpoint?: EndpointRef): void;
+/**
+ * 风险级别由命令语义决定，比按 HTTP 方法推断更稳定。
+ */
+export declare function getCommandRiskLevel(meta: CommandMeta): RiskLevel;

package/dist/core/auth-policy.js

@@ -1,4 +1,20 @@
 import { CliError } from './cli-error.js';
+const DANGEROUS_COMMAND_PATTERNS = [
+    /^workitem\.(remove|freeze|unfreeze|abort|restore|update-compound)$/,
+    /^view\.delete$/,
+    /^attachment\.delete$/,
+    /^workhour\.delete$/,
+];
+const WRITE_COMMAND_PATTERNS = [
+    /^workitem\.create$/,
+    /^workitem\.update$/,
+    /^workflow\.(state-change|node-operate|node-update)$/,
+    /^comment\.(add|update|remove)$/,
+    /^subtask\.(create|update|remove|operate)$/,
+    /^attachment\.(upload-file|upload)$/,
+    /^workhour\.(create|update)$/,
+    /^view\.(create-fix|update-fix|create-condition|update-condition)$/,
+];
 const USER_TOKEN_ONLY_TEMPLATES = new Set([
     '/open_api/user/search',
     '/open_api/:project_key/user_group',
@@ -24,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) {
@@ -32,6 +54,25 @@ 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,
+            },
+        });
+    }
+}
+/**
+ * 风险级别由命令语义决定，比按 HTTP 方法推断更稳定。
+ */
+export function getCommandRiskLevel(meta) {
+    if (DANGEROUS_COMMAND_PATTERNS.some((pattern) => pattern.test(meta.id))) {
+        return 'DANGEROUS';
+    }
+    if (WRITE_COMMAND_PATTERNS.some((pattern) => pattern.test(meta.id))) {
+        return 'WRITE';
     }
+    return 'READ_ONLY';
 }

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

@@ -5,6 +5,8 @@ export interface RuntimeOptions {
     profile?: string;
     userKey?: string;
     compatAuth?: boolean;
+    yes?: boolean;
+    forceBatch?: boolean;
 }
 export interface GuardContext {
     profileName: string;
@@ -13,4 +15,12 @@ export interface GuardContext {
     auth: AuthContext;
     userKey?: string;
 }
-export declare function runGuarded<T>(meta: CommandMeta, runtime: RuntimeOptions, action: (ctx: GuardContext) => Promise<T>): Promise<T>;
+export interface RiskPreview {
+    lines?: string[];
+    confirmPhrase?: string;
+    targetCount?: number;
+}
+export interface GuardHooks {
+    riskPreview?: (ctx: GuardContext) => Promise<RiskPreview | undefined>;
+}
+export declare function runGuarded<T>(meta: CommandMeta, runtime: RuntimeOptions, action: (ctx: GuardContext) => Promise<T>, hooks?: GuardHooks): Promise<T>;

package/dist/core/command-guard.js

@@ -1,7 +1,10 @@
+import { createInterface } from 'node:readline/promises';
 import { CliError } from './cli-error.js';
-import { assertCommandSupported, assertEndpointAllowed } from './auth-policy.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();
@@ -24,7 +27,121 @@ function buildPluginAuth(userKey, compatAuth) {
         authMode: compatAuth ? 0 : 1,
     };
 }
-export async function runGuarded(meta, runtime, action) {
+function isInteractiveShell() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function isHighRiskProfile(profileName) {
+    return /(^|[-_])(prod|production|live)([-_]|$)/i.test(profileName);
+}
+function escalateRiskLevel(riskLevel, profileName) {
+    if (!isHighRiskProfile(profileName)) {
+        return riskLevel;
+    }
+    if (riskLevel === 'WRITE') {
+        return 'DANGEROUS';
+    }
+    return riskLevel;
+}
+function buildRiskSummary(meta, profileName, riskLevel) {
+    const args = process.argv.slice(2).join(' ');
+    return [
+        `命令: meegle ${args}`,
+        `profile: ${profileName}`,
+        `风险级别: ${riskLevel}`,
+        meta.endpoint ? `接口: ${meta.endpoint.method} ${meta.endpoint.path}` : '接口: N/A',
+    ];
+}
+/**
+ * 在统一守卫里注入风险预览，避免每个高风险命令各自实现一套确认流程。
+ *
+ * @param meta 命令元数据
+ * @param runtime 运行时选项
+ * @param profileName 当前 profile 名称
+ * @param preview 命令特定的风险预览
+ */
+async function confirmWriteRisk(meta, runtime, profileName, preview) {
+    const originalRisk = getCommandRiskLevel(meta);
+    const riskLevel = escalateRiskLevel(originalRisk, profileName);
+    if (riskLevel === 'READ_ONLY') {
+        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`);
+    }
+    if (runtime.yes) {
+        return;
+    }
+    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('已取消执行。', {
+                    exitCode: 2,
+                    code: 'OPERATION_CANCELLED',
+                });
+            }
+            return;
+        }
+        const answer = (await rl.question('确认继续执行写操作？[y/N] ')).trim().toLowerCase();
+        if (answer !== 'y' && answer !== 'yes') {
+            throw new CliError('已取消执行。', {
+                exitCode: 2,
+                code: 'OPERATION_CANCELLED',
+            });
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runGuarded(meta, runtime, action, hooks) {
     assertCommandSupported(meta);
     assertEndpointAllowed(meta.endpoint);
     const { name: profileName, profile } = await getProfile(runtime.profile);
@@ -34,5 +151,8 @@ export async function runGuarded(meta, runtime, action) {
     }
     const client = createClient(profile);
     const auth = buildPluginAuth(userKey, runtime.compatAuth);
-    return action({ profileName, profile, client, auth, userKey });
+    const ctx = { profileName, profile, client, auth, userKey };
+    const preview = hooks?.riskPreview ? await hooks.riskPreview(ctx) : undefined;
+    await confirmWriteRisk(meta, runtime, profileName, preview);
+    return action(ctx);
 }

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.2",
+  "version": "0.1.4",
   "description": "Plugin-only CLI for Feishu Project (Meegle) based on meeglesdk",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
     "README.md",
     "README-en.md",
     "RELEASE.md",
-    "examples"
+    "examples",
+    "skills"
   ],
   "scripts": {
     "clean": "rm -rf dist",

package/skills/meegle-cli-usage/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: meegle-cli-usage
+description: Use the meegle CLI shipped in this package instead of raw SDK or guessed API calls when an agent needs to query spaces, work items, views, PMO baselines, or related-field searches such as planning_version. Use for CLI-based Meegle automation, debugging, and analysis. Includes safety rules for write operations (`--yes` in non-interactive environments), view-type resolution, and relation-ID based filtering.
+---
+
+# Meegle CLI Usage
+
+Use `meegle` as the default entrypoint for Meegle operations in this package. Prefer invoking the CLI over reconstructing request payloads from memory.
+
+## Quick Start
+
+1. Resolve the command path.
+   - Try `meegle --help` first.
+   - If `meegle` is not in PATH, use `which meegle` or `npm bin -g`.
+   - If working inside this package without a global install, use `node_modules/.bin/meegle`.
+2. Resolve the command shape before guessing.
+   - Run `meegle --help` or `<subcommand> --help`.
+3. Separate read and write intent.
+   - Treat read commands as default-safe.
+   - Treat write commands as opt-in only.
+   - In non-interactive environments, only add `--yes` when the user explicitly approved the write.
+
+## Safety Rules
+
+1. Refuse to add `--yes` implicitly.
+2. Prefer read-only discovery before any write.
+3. Echo the target scope in reasoning before running a write:
+   - `profile`
+   - `projectKey`
+   - `workItemType`
+   - target `id` or `ids`
+4. If the task can be solved with `get`, `list`, `search`, or `query`, do that first.
+
+## Choose the Right Command
+
+### Query a view
+
+Do not infer the view type from a page URL.
+
+Always:
+
+1. Run `view list` with the candidate `view_id`
+2. Inspect `view_type`
+3. Use:
+   - `view fix-items` for fixed view (`view_type = 2`)
+   - `view panoramic-items` only when the view is not fixed
+
+### Filter by a related field
+
+For fields such as `planning_version` or `planning_sprint`:
+
+1. Do not use `workitem search filter` with `field_value_pairs`
+2. Resolve the related work item instance ID first
+3. Use `workitem search by-params`
+4. Pass the related work item **ID list**, not the display name
+
+This is the most common agent mistake. `field_value_pairs` belongs to create/update flows, not search flows.
+
+### Build a PMO baseline
+
+For PMO-style analysis:
+
+1. Resolve the target view
+2. Fetch the item IDs from the view
+3. Fetch work item details with selected fields
+4. Summarize:
+   - state distribution
+   - owner distribution
+   - priority coverage
+   - due-date coverage
+   - age / stale updates
+
+Do not replace a view-scoped baseline with the whole space backlog unless the user explicitly asks for that.
+
+## Write Operations
+
+Use write commands only after explicit user approval.
+
+Typical write commands:
+
+- `workitem create`
+- `workitem update`
+- `comment add/update/remove`
+- `subtask create/update/remove/operate`
+- `workflow state-change`
+- `workflow node-operate`
+
+In scripts, CI, or agent runners:
+
+- pass `--yes` only when approved
+- expect non-interactive write rejection if `--yes` is missing
+
+## Use the Bundled Examples
+
+Read [references/command-recipes.md](./references/command-recipes.md) when you need:
+
+- view lookup examples
+- fixed view item queries
+- version lookup by name
+- story lookup by `planning_version`
+- PMO baseline query order
+
+Use the package examples directly when possible:
+
+- `../../examples/view-list.json`
+- `../../examples/view-fix-items.json`
+- `../../examples/version-search-filter.json`
+- `../../examples/story-by-planning-version.json`

package/skills/meegle-cli-usage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Meegle CLI Usage"
+  short_description: "Agent guide for safe meegle-cli usage."
+  default_prompt: "Use $meegle-cli-usage to operate Meegle safely through the CLI."

package/skills/meegle-cli-usage/references/command-recipes.md

@@ -0,0 +1,99 @@
+# Command Recipes
+
+## Resolve a View
+
+Use this first whenever the user gives a page URL or a `view_id`.
+
+```bash
+meegle --profile default view list \
+  --project-key 69zyer \
+  --body-file ./examples/view-list.json \
+  --json
+```
+
+Interpretation:
+
+- `view_type = 2` -> fixed view -> use `view fix-items`
+- otherwise -> inspect whether `view panoramic-items` is the intended path
+
+## Fetch Fixed View Items
+
+```bash
+meegle --profile default view fix-items \
+  --project-key 69zyer \
+  --view-id sypbi-z60 \
+  --query-file ./examples/view-fix-items.json \
+  --json
+```
+
+Use the returned `work_item_id_list` as input to `workitem get`.
+
+## Find a Version Work Item by Name
+
+Use this when the user speaks in business names such as “260312 version” or “gray release”.
+
+```bash
+meegle --profile default workitem search filter \
+  --project-key 69zyer \
+  --body-file ./examples/version-search-filter.json \
+  --json
+```
+
+If multiple version items match:
+
+1. surface the candidates
+2. ask the user to confirm the intended version or pick the exact `id`
+
+## Find Stories by `planning_version`
+
+Never pass the version display name directly into `planning_version`.
+
+Correct flow:
+
+1. resolve the target version work item `id`
+2. place that numeric `id` into `examples/story-by-planning-version.json`
+3. run:
+
+```bash
+meegle --profile default workitem search by-params \
+  --project-key 69zyer \
+  --type story \
+  --body-file ./examples/story-by-planning-version.json \
+  --json
+```
+
+## PMO Baseline Workflow
+
+Use this order:
+
+1. `view list`
+2. `view fix-items` / `view panoramic-items`
+3. `workitem get --fields ...`
+4. summarize the returned dataset
+
+Recommended PMO fields:
+
+- `name`
+- `owner`
+- `priority`
+- `description`
+- `work_item_status`
+- `start_time`
+- `exp_time`
+
+Recommended output dimensions:
+
+- total count
+- state distribution
+- current node distribution
+- owner concentration
+- missing priority
+- missing due date
+- creation/update time range
+
+## Write Command Reminder
+
+In non-interactive environments:
+
+- add `--yes` only when the user explicitly approved a mutation
+- do not silently convert a read request into a write request