meegle-cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,2056 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { Command } from 'commander';
+import { runGuarded } from './core/command-guard.js';
+import { upsertProfile } from './core/config-store.js';
+import { readJsonFile } from './core/json-file.js';
+import { printData } from './core/output.js';
+import { CliError } from './core/cli-error.js';
+const DEFAULT_BASE_URL = 'https://project.feishu.cn';
+function parseCsv(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function parseNumber(raw, label) {
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new CliError(`${label} 必须是数字`, 2);
+    }
+    return value;
+}
+function parseInteger(raw, label) {
+    const value = parseNumber(raw, label);
+    if (!Number.isInteger(value)) {
+        throw new CliError(`${label} 必须是整数`, 2);
+    }
+    return value;
+}
+function parseTokenType(raw) {
+    const value = Number(raw);
+    if (value !== 0 && value !== 1) {
+        throw new CliError('tokenType 仅支持 0 或 1', 2);
+    }
+    return value;
+}
+function parseNumberList(raw, label) {
+    const values = parseCsv(raw).map((item) => parseInteger(item, label));
+    if (values.length === 0) {
+        throw new CliError(`${label} 不能为空`, 2);
+    }
+    return values;
+}
+function parseOptionalInteger(raw, label) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    return parseInteger(raw, label);
+}
+function parseOptionalNumber(raw, label) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    return parseNumber(raw, label);
+}
+function parseBoolean(raw, label) {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === 'true') {
+        return true;
+    }
+    if (normalized === 'false') {
+        return false;
+    }
+    throw new CliError(`${label} 仅支持 true 或 false`, 2);
+}
+function parseTimestamp(raw, label) {
+    const trimmed = raw.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return parseInteger(trimmed, label);
+    }
+    const timestamp = Date.parse(trimmed);
+    if (Number.isNaN(timestamp)) {
+        throw new CliError(`${label} 必须是毫秒时间戳或可解析日期`, 2);
+    }
+    return timestamp;
+}
+function parseAction(raw, label) {
+    if (raw === 'confirm' || raw === 'rollback') {
+        return raw;
+    }
+    throw new CliError(`${label} 仅支持 confirm 或 rollback`, 2);
+}
+/**
+ * commander 默认会覆盖重复参数，这里统一改成累加，避免字段赋值场景只能保留最后一个值。
+ */
+function collectOptionValue(value, previous = []) {
+    return [...previous, value];
+}
+async function readOptionalJsonFile(filePath) {
+    if (!filePath) {
+        return undefined;
+    }
+    return readJsonFile(filePath);
+}
+/**
+ * 统一处理内联 JSON 与文件输入，避免每个命令重复维护同一套解析分支。
+ */
+async function readJsonInput(args) {
+    if (args.inlineJson && args.filePath) {
+        throw new CliError(`--${args.label} 与 --${args.label}-file 不能同时使用`, 2);
+    }
+    if (args.inlineJson) {
+        try {
+            return JSON.parse(args.inlineJson);
+        }
+        catch {
+            throw new CliError(`--${args.label} 不是合法 JSON`, 2);
+        }
+    }
+    return readOptionalJsonFile(args.filePath);
+}
+/**
+ * 大段文本更适合放文件里，这里统一收口，避免每个命令重复处理互斥逻辑。
+ */
+async function readTextInput(args) {
+    if (args.inlineText !== undefined && args.filePath) {
+        throw new CliError(`--${args.label} 与 --${args.label}-file 不能同时使用`, 2);
+    }
+    if (args.inlineText !== undefined) {
+        return args.inlineText;
+    }
+    if (!args.filePath) {
+        return undefined;
+    }
+    return readFile(args.filePath, 'utf8');
+}
+/**
+ * 统一约束“快捷参数”和“原始请求体”只能二选一，避免隐式合并导致结果不可预测。
+ */
+function assertInputMode(args) {
+    if (args.shortcutUsed && args.rawBodyUsed) {
+        throw new CliError(`命令 "${args.commandId}" 不能同时使用快捷参数和 --body/--body-file，请二选一。`, 2);
+    }
+}
+/**
+ * 统一处理空值兜底，避免初始化命令把环境变量、显式参数和默认值分散在多处。
+ */
+function pickFirstDefined(...values) {
+    for (const value of values) {
+        if (value?.trim()) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+/**
+ * 用户在命令行里更容易写“看起来像 JSON 的值”，这里统一做宽松解析，减少不必要的引号负担。
+ */
+function parseCliValue(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return '';
+    }
+    const looksLikeJson = trimmed.startsWith('{') ||
+        trimmed.startsWith('[') ||
+        trimmed.startsWith('"') ||
+        trimmed === 'true' ||
+        trimmed === 'false' ||
+        trimmed === 'null' ||
+        /^-?\d+(\.\d+)?$/.test(trimmed);
+    if (!looksLikeJson) {
+        return raw;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * `--field key=value` 是写操作里最通用的表达方式，统一解析后其他命令都能复用。
+ */
+function parseFieldAssignments(rawFields) {
+    return (rawFields ?? []).map((rawField) => {
+        const separatorIndex = rawField.indexOf('=');
+        if (separatorIndex <= 0) {
+            throw new CliError('字段赋值格式必须是 field_key=value', 2);
+        }
+        const fieldKey = rawField.slice(0, separatorIndex).trim();
+        const rawValue = rawField.slice(separatorIndex + 1);
+        if (!fieldKey) {
+            throw new CliError('字段 key 不能为空', 2);
+        }
+        return {
+            field_key: fieldKey,
+            field_value: parseCliValue(rawValue),
+        };
+    });
+}
+/**
+ * 简单场景下让用户直接写 `P2` 或 `高:high`，避免为了单选字段再手写完整对象。
+ */
+function parseSelectLikeValue(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new CliError('priority 不能为空', 2);
+    }
+    if (trimmed.startsWith('{')) {
+        const parsed = parseCliValue(trimmed);
+        if (typeof parsed === 'object' && parsed !== null) {
+            return parsed;
+        }
+        throw new CliError('priority JSON 必须是对象', 2);
+    }
+    const pMatch = /^P(\d+)$/i.exec(trimmed);
+    if (pMatch) {
+        return { label: trimmed.toUpperCase(), value: pMatch[1] };
+    }
+    const separatorIndex = trimmed.indexOf(':');
+    if (separatorIndex > 0) {
+        const label = trimmed.slice(0, separatorIndex).trim();
+        const value = trimmed.slice(separatorIndex + 1).trim();
+        if (!label || !value) {
+            throw new CliError('priority 格式必须是 label:value', 2);
+        }
+        return { label, value };
+    }
+    return { label: trimmed, value: trimmed };
+}
+function getFieldIdentifier(field) {
+    if (field.field_key?.trim()) {
+        return `field_key:${field.field_key.trim()}`;
+    }
+    if (field.field_alias?.trim()) {
+        return `field_alias:${field.field_alias.trim()}`;
+    }
+    return undefined;
+}
+/**
+ * 快捷参数与自定义字段如果指向同一字段，最终结果会高度不可预测，这里直接拒绝。
+ */
+function assertNoFieldConflicts(commandId, shortcutFields, customFields) {
+    const shortcutIdentifiers = new Set(shortcutFields.map(getFieldIdentifier).filter(Boolean));
+    for (const field of customFields) {
+        const identifier = getFieldIdentifier(field);
+        if (!identifier) {
+            continue;
+        }
+        if (shortcutIdentifiers.has(identifier)) {
+            throw new CliError(`命令 "${commandId}" 的快捷参数与 --field 指向了同一字段，请保留一种写法。`, 2);
+        }
+    }
+}
+function buildCommonShortcutFields(args) {
+    const shortcutFields = [];
+    if (args.desc !== undefined) {
+        shortcutFields.push({ field_key: 'description', field_value: args.desc });
+    }
+    if (args.owner?.trim()) {
+        shortcutFields.push({ field_key: 'owner', field_value: args.owner.trim() });
+    }
+    if (args.priority?.trim()) {
+        shortcutFields.push({
+            field_key: 'priority',
+            field_value: parseSelectLikeValue(args.priority),
+        });
+    }
+    const customFields = parseFieldAssignments(args.customFields);
+    assertNoFieldConflicts(args.commandId, shortcutFields, customFields);
+    return [...shortcutFields, ...customFields];
+}
+/**
+ * 排期字段在多个命令里都长得一样，集中解析后可以保证日期与估分语义一致。
+ */
+function buildSchedule(args) {
+    const estimateStartDate = args.start ? parseTimestamp(args.start, 'start') : undefined;
+    const estimateEndDate = args.end ? parseTimestamp(args.end, 'end') : undefined;
+    const points = parseOptionalNumber(args.points, 'points');
+    const isAuto = args.isAuto ? parseBoolean(args.isAuto, 'auto') : undefined;
+    if (estimateStartDate === undefined &&
+        estimateEndDate === undefined &&
+        points === undefined &&
+        isAuto === undefined) {
+        return undefined;
+    }
+    return {
+        estimate_start_date: estimateStartDate,
+        estimate_end_date: estimateEndDate,
+        points,
+        is_auto: isAuto,
+    };
+}
+/**
+ * 把初始化所需的关键参数集中解析，避免调用方理解“哪些值能从环境变量补齐”。
+ */
+function resolveAuthInitOptions(options) {
+    const pluginId = pickFirstDefined(options.pluginId, process.env.MEEGLE_PLUGIN_ID);
+    const pluginSecret = pickFirstDefined(options.pluginSecret, process.env.MEEGLE_PLUGIN_SECRET);
+    const baseUrl = pickFirstDefined(options.baseUrl, process.env.MEEGLE_BASE_URL) ?? DEFAULT_BASE_URL;
+    const tokenTypeRaw = pickFirstDefined(options.tokenType, process.env.MEEGLE_TOKEN_TYPE) ?? '0';
+    const defaultUserKey = pickFirstDefined(options.defaultUserKey, process.env.MEEGLE_DEFAULT_USER_KEY, process.env.MEEGLE_USER_KEY);
+    if (!pluginId) {
+        throw new CliError('缺少 pluginId。请传 --plugin-id 或设置环境变量 MEEGLE_PLUGIN_ID。', 2);
+    }
+    if (!pluginSecret) {
+        throw new CliError('缺少 pluginSecret。请传 --plugin-secret 或设置环境变量 MEEGLE_PLUGIN_SECRET。', 2);
+    }
+    return {
+        pluginId,
+        pluginSecret,
+        baseUrl,
+        tokenType: parseTokenType(tokenTypeRaw),
+        defaultUserKey,
+        targetProfile: options.targetProfile,
+    };
+}
+/**
+ * 为高频读操作生成默认请求体，避免普通查询也要手写 SDK 原始结构。
+ */
+function buildSpaceDetailRequest(options, userKey) {
+    const shortcutUsed = Boolean(options.projectKey || options.projectKeys || options.simpleName || options.simpleNames);
+    const rawBodyUsed = Boolean(options.body || options.bodyFile);
+    assertInputMode({ commandId: 'space.get', shortcutUsed, rawBodyUsed });
+    if (!shortcutUsed) {
+        throw new CliError('space get 至少需要 --project-key / --project-keys / --simple-name / --simple-names 之一，或传 --body/--body-file。', 2);
+    }
+    const projectKeys = [
+        ...(options.projectKey ? [options.projectKey.trim()] : []),
+        ...parseCsv(options.projectKeys),
+    ].filter(Boolean);
+    const simpleNames = [
+        ...(options.simpleName ? [options.simpleName.trim()] : []),
+        ...parseCsv(options.simpleNames),
+    ].filter(Boolean);
+    if (projectKeys.length === 0 && simpleNames.length === 0) {
+        throw new CliError('space get 的快捷参数不能为空', 2);
+    }
+    return {
+        project_keys: projectKeys.length > 0 ? projectKeys : undefined,
+        simple_names: simpleNames.length > 0 ? simpleNames : undefined,
+        user_key: userKey,
+    };
+}
+/**
+ * 为最常见的“按 ID 查工作项”场景补一层直观参数，避免用户理解底层 QueryWorkItemRequest。
+ */
+function buildWorkItemQueryRequest(options) {
+    const shortcutUsed = Boolean(options.id || options.ids || options.fields || options.expand);
+    const rawBodyUsed = Boolean(options.body || options.bodyFile);
+    assertInputMode({ commandId: 'workitem.get', shortcutUsed, rawBodyUsed });
+    if (!shortcutUsed) {
+        throw new CliError('workitem get 需要 --id/--ids，或传 --body/--body-file。', 2);
+    }
+    const workItemIds = [
+        ...(options.id ? [parseInteger(options.id, 'id')] : []),
+        ...(options.ids ? parseNumberList(options.ids, 'ids') : []),
+    ];
+    if (workItemIds.length === 0) {
+        throw new CliError('workitem get 至少需要一个工作项 ID', 2);
+    }
+    let expand;
+    if (options.expand) {
+        try {
+            expand = JSON.parse(options.expand);
+        }
+        catch {
+            throw new CliError('--expand 不是合法 JSON', 2);
+        }
+    }
+    const fields = parseCsv(options.fields);
+    return {
+        work_item_ids: workItemIds,
+        fields: fields.length > 0 ? fields : undefined,
+        expand,
+    };
+}
+/**
+ * 创建和更新工作项最终都落到字段值对，这里抽一层避免每个命令重复拼装字段结构。
+ */
+async function buildWorkItemWriteFields(args) {
+    const desc = await readTextInput({
+        inlineText: args.desc,
+        filePath: args.descFile,
+        label: 'desc',
+    });
+    return buildCommonShortcutFields({
+        commandId: args.commandId,
+        desc,
+        owner: args.owner,
+        priority: args.priority,
+        customFields: args.customFields,
+    });
+}
+/**
+ * 常用创建场景只需要少量语义化参数，这里把它们稳定映射到 SDK 原始请求体。
+ */
+async function buildWorkItemCreateRequest(options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const shortcutFields = await buildWorkItemWriteFields({
+        commandId: 'workitem.create',
+        desc: options.desc,
+        descFile: options.descFile,
+        owner: options.owner,
+        priority: options.priority,
+        customFields: options.field,
+    });
+    const shortcutUsed = options.type !== undefined ||
+        options.name !== undefined ||
+        options.templateId !== undefined ||
+        options.requiredMode !== undefined ||
+        shortcutFields.length > 0;
+    assertInputMode({
+        commandId: 'workitem.create',
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    if (!shortcutUsed) {
+        throw new CliError('workitem create 需要 --type，并结合 --name/--desc/--field 等快捷参数，或传 --body/--body-file。', 2);
+    }
+    const workItemTypeKey = options.type?.trim();
+    if (!workItemTypeKey) {
+        throw new CliError('workitem create 使用快捷参数时必须提供 --type', 2);
+    }
+    const name = options.name?.trim();
+    if (options.name !== undefined && !name) {
+        throw new CliError('name 不能为空', 2);
+    }
+    if (name) {
+        assertNoFieldConflicts('workitem.create', [{ field_key: 'name', field_value: name }], shortcutFields);
+    }
+    return {
+        work_item_type_key: workItemTypeKey,
+        name: name || undefined,
+        template_id: parseOptionalInteger(options.templateId, 'template-id'),
+        required_mode: parseOptionalInteger(options.requiredMode, 'required-mode'),
+        field_value_pairs: shortcutFields.length > 0 ? shortcutFields : undefined,
+    };
+}
+/**
+ * 更新命令需要保留“最少改哪些字段”这个语义，避免用户为了改单个标题就手写整段 update_fields。
+ */
+async function buildWorkItemUpdateRequest(options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const fields = await buildWorkItemWriteFields({
+        commandId: 'workitem.update',
+        desc: options.desc,
+        descFile: options.descFile,
+        owner: options.owner,
+        priority: options.priority,
+        customFields: options.field,
+    });
+    const name = options.name?.trim();
+    if (options.name !== undefined && !name) {
+        throw new CliError('name 不能为空', 2);
+    }
+    if (name) {
+        const nameField = { field_key: 'name', field_value: name };
+        assertNoFieldConflicts('workitem.update', [nameField], fields);
+        fields.unshift(nameField);
+    }
+    const shortcutUsed = options.name !== undefined || fields.length > 0;
+    assertInputMode({
+        commandId: 'workitem.update',
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    if (fields.length === 0) {
+        throw new CliError('workitem update 需要至少一个更新内容，例如 --name/--desc/--field，或传 --body/--body-file。', 2);
+    }
+    return {
+        update_fields: fields,
+    };
+}
+/**
+ * 评论输入如果允许多种来源同时生效，会出现一部分内容被静默覆盖，这里统一做强约束。
+ */
+async function buildCommentRequestBody(commandId, options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const content = await readTextInput({
+        inlineText: options.content,
+        filePath: options.contentFile,
+        label: 'content',
+    });
+    const richText = await readJsonInput({
+        inlineJson: options.richText,
+        filePath: options.richTextFile,
+        label: 'rich-text',
+    });
+    const normalizedRichText = richText;
+    const shortcutUsed = content !== undefined || normalizedRichText !== undefined;
+    assertInputMode({
+        commandId,
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    if (!shortcutUsed) {
+        throw new CliError(`${commandId} 需要 --content/--content-file/--rich-text/--rich-text-file，或传 --body/--body-file。`, 2);
+    }
+    if (content !== undefined && normalizedRichText !== undefined) {
+        throw new CliError(`${commandId} 不能同时传纯文本和富文本，请二选一。`, 2);
+    }
+    return {
+        content,
+        rich_text: normalizedRichText,
+    };
+}
+async function buildSubtaskWriteShared(args) {
+    const note = await readTextInput({
+        inlineText: args.note,
+        filePath: args.noteFile,
+        label: 'note',
+    });
+    return {
+        note,
+        assignee: parseCsv(args.assignee),
+        schedule: buildSchedule({
+            start: args.start,
+            end: args.end,
+            points: args.points,
+        }),
+        fields: parseFieldAssignments(args.field),
+    };
+}
+/**
+ * 子任务创建和更新共享了同一类字段，但请求结构不同，统一在这里分叉能避免命令层再次复制业务规则。
+ */
+async function buildSubtaskCreateRequest(options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const shared = await buildSubtaskWriteShared(options);
+    const shortcutUsed = options.nodeId !== undefined ||
+        options.name !== undefined ||
+        shared.note !== undefined ||
+        shared.assignee.length > 0 ||
+        shared.schedule !== undefined ||
+        shared.fields.length > 0;
+    assertInputMode({
+        commandId: 'subtask.create',
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    if (!shortcutUsed) {
+        throw new CliError('subtask create 需要 --node-id、--name 等快捷参数，或传 --body/--body-file。', 2);
+    }
+    const nodeId = options.nodeId?.trim();
+    const name = options.name?.trim();
+    if (!nodeId) {
+        throw new CliError('subtask create 使用快捷参数时必须提供 --node-id', 2);
+    }
+    if (!name) {
+        throw new CliError('subtask create 使用快捷参数时必须提供 --name', 2);
+    }
+    return {
+        node_id: nodeId,
+        name,
+        assignee: shared.assignee.length > 0 ? shared.assignee : undefined,
+        schedule: shared.schedule,
+        note: shared.note,
+        field_value_pairs: shared.fields.length > 0 ? shared.fields : undefined,
+    };
+}
+async function buildSubtaskUpdateRequest(options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const shared = await buildSubtaskWriteShared(options);
+    const name = options.name?.trim();
+    if (options.name !== undefined && !name) {
+        throw new CliError('name 不能为空', 2);
+    }
+    const shortcutUsed = options.name !== undefined ||
+        shared.note !== undefined ||
+        shared.assignee.length > 0 ||
+        shared.schedule !== undefined ||
+        shared.fields.length > 0;
+    assertInputMode({
+        commandId: 'subtask.update',
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    if (!shortcutUsed) {
+        throw new CliError('subtask update 需要至少一个更新内容，例如 --name/--note/--assignee/--field，或传 --body/--body-file。', 2);
+    }
+    return {
+        name: name || undefined,
+        assignee: shared.assignee.length > 0 ? shared.assignee : undefined,
+        schedule: shared.schedule,
+        note: shared.note,
+        update_fields: shared.fields.length > 0 ? shared.fields : undefined,
+    };
+}
+async function buildSubtaskOperateRequest(options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const shortcutUsed = options.nodeId !== undefined || options.taskId !== undefined || options.action !== undefined;
+    assertInputMode({
+        commandId: 'subtask.operate',
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    if (!shortcutUsed) {
+        throw new CliError('subtask operate 需要 --node-id/--task-id/--action，或传 --body/--body-file。', 2);
+    }
+    const nodeId = options.nodeId?.trim();
+    if (!nodeId) {
+        throw new CliError('subtask operate 使用快捷参数时必须提供 --node-id', 2);
+    }
+    return {
+        node_id: nodeId,
+        task_id: parseInteger(options.taskId ?? '', 'task-id'),
+        action: parseAction(options.action ?? '', 'action'),
+    };
+}
+async function buildWorkflowStateChangeRequest(options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const fields = parseFieldAssignments(options.field);
+    const shortcutUsed = options.transitionId !== undefined || fields.length > 0;
+    assertInputMode({
+        commandId: 'workflow.state-change',
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    const transitionId = parseOptionalInteger(options.transitionId, 'transition-id');
+    if (transitionId === undefined) {
+        throw new CliError('workflow state-change 使用快捷参数时必须提供 --transition-id', 2);
+    }
+    return {
+        transition_id: transitionId,
+        fields: fields.length > 0 ? fields : undefined,
+    };
+}
+async function buildWorkflowNodeOperateRequest(options) {
+    const rawBody = await readJsonInput({
+        inlineJson: options.body,
+        filePath: options.bodyFile,
+        label: 'body',
+    });
+    const fields = parseFieldAssignments(options.field);
+    const schedule = buildSchedule({
+        start: options.start,
+        end: options.end,
+        points: options.points,
+    });
+    const nodeOwners = parseCsv(options.nodeOwners);
+    const shortcutUsed = options.action !== undefined ||
+        options.rollbackReason !== undefined ||
+        nodeOwners.length > 0 ||
+        schedule !== undefined ||
+        fields.length > 0;
+    assertInputMode({
+        commandId: 'workflow.node-operate',
+        shortcutUsed,
+        rawBodyUsed: rawBody !== undefined,
+    });
+    if (rawBody) {
+        return rawBody;
+    }
+    const action = options.action ? parseAction(options.action, 'action') : undefined;
+    if (!action) {
+        throw new CliError('workflow node-operate 使用快捷参数时必须提供 --action', 2);
+    }
+    if (action === 'rollback' && !options.rollbackReason?.trim()) {
+        throw new CliError('workflow node-operate 在 rollback 时必须提供 --rollback-reason', 2);
+    }
+    return {
+        action,
+        rollback_reason: options.rollbackReason?.trim() || undefined,
+        node_owners: nodeOwners.length > 0 ? nodeOwners : undefined,
+        node_schedule: schedule,
+        fields: fields.length > 0 ? fields : undefined,
+    };
+}
+function resolveGlobal(program) {
+    return program.opts();
+}
+function printOk(asJson) {
+    printData({ ok: true }, asJson);
+}
+function registerAuth(program) {
+    const auth = program.command('auth').description('认证与 profile 管理');
+    auth
+        .command('init')
+        .description('初始化或更新 plugin 凭证 (plugin-only)')
+        .option('--plugin-id <pluginId>', 'Plugin ID，未传时读取 MEEGLE_PLUGIN_ID')
+        .option('--plugin-secret <pluginSecret>', 'Plugin Secret，未传时读取 MEEGLE_PLUGIN_SECRET')
+        .option('--base-url <baseURL>', `API 域名，默认 ${DEFAULT_BASE_URL}`)
+        .option('--token-type <tokenType>', '0=plugin_access_token, 1=virtual_plugin_token，默认 0')
+        .option('--default-user-key <userKey>', '默认 userKey，未传时读取 MEEGLE_DEFAULT_USER_KEY / MEEGLE_USER_KEY')
+        .option('--target-profile <name>', '写入的 profile 名称，默认 default', 'default')
+        .addHelpText('after', `
+环境变量：
+  MEEGLE_PLUGIN_ID
+  MEEGLE_PLUGIN_SECRET
+  MEEGLE_BASE_URL
+  MEEGLE_TOKEN_TYPE
+  MEEGLE_DEFAULT_USER_KEY
+  MEEGLE_USER_KEY
+`)
+        .action(async (options) => {
+        const resolved = resolveAuthInitOptions(options);
+        await upsertProfile(resolved.targetProfile, {
+            pluginId: resolved.pluginId,
+            pluginSecret: resolved.pluginSecret,
+            baseURL: resolved.baseUrl,
+            tokenType: resolved.tokenType,
+            defaultUserKey: resolved.defaultUserKey,
+        });
+        console.log(`已写入 profile "${resolved.targetProfile}"，并设为当前 active profile。`);
+        console.log('下一步：');
+        console.log(`  meegle --profile ${resolved.targetProfile} auth status`);
+        console.log(`  meegle --profile ${resolved.targetProfile} space list`);
+    });
+    auth
+        .command('status')
+        .description('校验 plugin token 是否可获取')
+        .action(async () => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'auth.status',
+            authPolicy: 'NONE',
+            endpoint: { method: 'POST', path: '/open_api/authen/plugin_token' },
+        }, global, async (ctx) => {
+            const token = await ctx.client.auth.getPluginToken();
+            const tokenPreview = token.length > 12 ? `${token.slice(0, 8)}...${token.slice(-4)}` : token;
+            return {
+                profile: ctx.profileName,
+                baseURL: ctx.profile.baseURL,
+                tokenType: ctx.profile.tokenType,
+                tokenPreview,
+                ok: true,
+            };
+        });
+        printData(result, Boolean(global.json));
+    });
+}
+function registerSpace(program) {
+    const space = program.command('space').description('空间相关命令');
+    space
+        .command('list')
+        .description('列出当前用户可见空间')
+        .option('--order <fields>', '排序字段，逗号分隔', '-last_visited')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'space.list',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/projects' },
+        }, global, async (ctx) => ctx.client.space.listSpace({
+            user_key: ctx.userKey,
+            order: parseCsv(options.order),
+        }, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    space
+        .command('get')
+        .description('获取空间详情')
+        .option('--project-key <projectKey>', '单个空间 key')
+        .option('--project-keys <projectKeys>', '多个空间 key，逗号分隔')
+        .option('--simple-name <simpleName>', '单个空间简称')
+        .option('--simple-names <simpleNames>', '多个空间简称，逗号分隔')
+        .option('--body <json>', '内联 JSON，请求体对应 GetProjectDetailRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 GetProjectDetailRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'space.get',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/projects/detail' },
+        }, global, async (ctx) => {
+            const rawBody = await readJsonInput({
+                inlineJson: options.body,
+                filePath: options.bodyFile,
+                label: 'body',
+            });
+            const body = rawBody ??
+                buildSpaceDetailRequest(options, ctx.userKey);
+            return ctx.client.space.getSpaceDetail({
+                ...body,
+                user_key: body.user_key ?? ctx.userKey,
+            }, { auth: ctx.auth });
+        });
+        printData(result, Boolean(global.json));
+    });
+    space
+        .command('types')
+        .description('获取空间下工作项类型')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'space.types',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'GET', path: '/open_api/:project_key/work_item/all-types' },
+        }, global, async (ctx) => ctx.client.space.listWorkItemTypes(options.projectKey, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    space
+        .command('team-members')
+        .description('获取空间下团队成员')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'space.team-members',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'GET', path: '/open_api/:project_key/teams/all' },
+        }, global, async (ctx) => ctx.client.space.listTeamMembers(options.projectKey, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+}
+function registerWorkItem(program) {
+    const workItem = program.command('workitem').description('工作项命令');
+    workItem
+        .command('get')
+        .description('获取工作项详情')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .option('--id <workItemId>', '单个工作项 ID，最常用')
+        .option('--ids <workItemIds>', '多个工作项 ID，逗号分隔')
+        .option('--fields <fieldKeys>', '仅返回这些字段，逗号分隔')
+        .option('--expand <json>', '内联 JSON，对应 QueryWorkItemRequest.expand')
+        .option('--body <json>', '内联 JSON，请求体对应 QueryWorkItemRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 QueryWorkItemRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'workitem.get',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/work_item/:work_item_type_key/query' },
+        }, global, async (ctx) => {
+            const body = (await readJsonInput({
+                inlineJson: options.body,
+                filePath: options.bodyFile,
+                label: 'body',
+            })) ?? buildWorkItemQueryRequest(options);
+            return ctx.client.workItem.query(options.projectKey, options.type, body, { auth: ctx.auth });
+        });
+        printData(result, Boolean(global.json));
+    });
+    workItem
+        .command('meta')
+        .description('获取创建工作项元数据')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'workitem.meta',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'GET', path: '/open_api/:project_key/work_item/:work_item_type_key/meta' },
+        }, global, async (ctx) => ctx.client.workItem.getMeta(options.projectKey, options.type, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    workItem
+        .command('create')
+        .description('创建工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .option('--type <workItemTypeKey>', '工作项类型 key；快捷模式必填')
+        .option('--name <name>', '工作项标题')
+        .option('--desc <text>', '描述文本，映射到 description')
+        .option('--desc-file <path>', '从文件读取描述文本')
+        .option('--owner <userKey>', '负责人 userKey')
+        .option('--priority <priority>', '优先级，支持 P2、label:value 或 JSON 对象')
+        .option('--field <fieldSpec>', '字段赋值，格式 field_key=value；可重复', collectOptionValue, [])
+        .option('--template-id <templateId>', '流程模板 ID')
+        .option('--required-mode <mode>', '必填校验模式，0=跳过，1=校验')
+        .option('--body <json>', '内联 JSON，请求体对应 CreateWorkItemRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 CreateWorkItemRequest')
+        .addHelpText('after', `
+示例：
+  meegle workitem create --project-key demo --type story --name "登录优化" --desc "补齐错误提示"
+  meegle workitem create --project-key demo --type story --field tags='[{"label":"测试","value":"test"}]'
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildWorkItemCreateRequest(options);
+        const result = await runGuarded({
+            id: 'workitem.create',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/work_item/create' },
+        }, global, async (ctx) => ctx.client.workItem.create(options.projectKey, body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    workItem
+        .command('update')
+        .description('更新工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--name <name>', '工作项标题')
+        .option('--desc <text>', '描述文本，映射到 description')
+        .option('--desc-file <path>', '从文件读取描述文本')
+        .option('--owner <userKey>', '负责人 userKey')
+        .option('--priority <priority>', '优先级，支持 P2、label:value 或 JSON 对象')
+        .option('--field <fieldSpec>', '字段赋值，格式 field_key=value；可重复', collectOptionValue, [])
+        .option('--body <json>', '内联 JSON，请求体对应 UpdateWorkItemRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 UpdateWorkItemRequest')
+        .addHelpText('after', `
+示例：
+  meegle workitem update --project-key demo --type story --id 1 --name "标题已更新"
+  meegle workitem update --project-key demo --type story --id 1 --field owner=u_demo
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildWorkItemUpdateRequest(options);
+        await runGuarded({
+            id: 'workitem.update',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'PUT', path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id' },
+        }, global, async (ctx) => ctx.client.workItem.update(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    workItem
+        .command('remove')
+        .description('删除工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            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 }));
+        printOk(Boolean(global.json));
+    });
+    workItem
+        .command('freeze')
+        .description('冻结工作项（可批量）')
+        .requiredOption('--ids <ids>', '工作项 ID，逗号分隔')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        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 }));
+        printOk(Boolean(global.json));
+    });
+    workItem
+        .command('unfreeze')
+        .description('解冻工作项（可批量）')
+        .requiredOption('--ids <ids>', '工作项 ID，逗号分隔')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        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 }));
+        printOk(Boolean(global.json));
+    });
+    workItem
+        .command('abort')
+        .description('终止工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--reason <reason>', '终止原因')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'workitem.abort',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'PUT',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/abort',
+            },
+        }, global, async (ctx) => ctx.client.workItem.abort(options.projectKey, options.type, parseInteger(options.id, 'id'), options.reason, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    workItem
+        .command('restore')
+        .description('恢复工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--reason <reason>', '恢复原因')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'workitem.restore',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'PUT',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/abort',
+            },
+        }, global, async (ctx) => ctx.client.workItem.restore(options.projectKey, options.type, parseInteger(options.id, 'id'), options.reason, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    workItem
+        .command('op-records')
+        .description('获取工作项操作记录')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 GetOperationRecordsRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workitem.op-records',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/op_record/work_item/list' },
+        }, global, async (ctx) => ctx.client.workItem.getOperationRecords(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    workItem
+        .command('update-compound')
+        .description('按组更新复合字段值')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 UpdateCompoundFieldRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        await runGuarded({
+            id: 'workitem.update-compound',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/work_item/field_value/update_compound_field' },
+        }, global, async (ctx) => ctx.client.workItem.updateCompoundField(body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    const search = workItem.command('search').description('工作项搜索命令');
+    search
+        .command('filter')
+        .description('单空间筛选')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 FilterWorkItemsRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workitem.search.filter',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/work_item/filter' },
+        }, global, async (ctx) => ctx.client.workItem.search.filter(options.projectKey, body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    search
+        .command('filter-across')
+        .description('跨空间筛选')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 FilterWorkItemsAcrossProjectRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workitem.search.filter-across',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/work_items/filter_across_project' },
+        }, global, async (ctx) => ctx.client.workItem.search.filterAcrossProject(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    search
+        .command('by-params')
+        .description('复杂条件搜索')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 SearchWorkItemsByParamsRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workitem.search.by-params',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/search/params',
+            },
+        }, global, async (ctx) => ctx.client.workItem.search.searchByParams(options.projectKey, options.type, body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    search
+        .command('by-relation')
+        .description('关联工作项搜索')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 SearchByRelationRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workitem.search.by-relation',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/search_by_relation',
+            },
+        }, global, async (ctx) => ctx.client.workItem.search.searchByRelation(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    search
+        .command('compositive')
+        .description('全局搜索')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 CompositiveSearchRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workitem.search.compositive',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/compositive_search' },
+        }, global, async (ctx) => ctx.client.workItem.search.compositiveSearch(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    search
+        .command('universal')
+        .description('通用搜索（字段按需）')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 UniversalSearchRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workitem.search.universal',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/view_search/universal_search' },
+        }, global, async (ctx) => ctx.client.workItem.search.universalSearch(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+}
+function registerWorkflow(program) {
+    const workflow = program.command('workflow').description('工作流命令');
+    workflow
+        .command('query')
+        .description('获取工作流详情')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'workflow.query',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/workflow/query',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workflow.query(options.projectKey, options.type, parseInteger(options.id, 'id'), undefined, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    workflow
+        .command('state-change')
+        .description('状态流转')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--transition-id <transitionId>', '目标流转 ID')
+        .option('--field <fieldSpec>', '字段赋值，格式 field_key=value；可重复', collectOptionValue, [])
+        .option('--body <json>', '内联 JSON，请求体对应 StateChangeRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 StateChangeRequest')
+        .addHelpText('after', `
+示例：
+  meegle workflow state-change --project-key demo --type story --id 1 --transition-id 12345
+  meegle workflow state-change --project-key demo --type story --id 1 --transition-id 12345 --field description="补充流转说明"
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildWorkflowStateChangeRequest(options);
+        await runGuarded({
+            id: 'workflow.state-change',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/workflow/:work_item_type_key/:work_item_id/node/state_change',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workflow.stateChange(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    workflow
+        .command('node-operate')
+        .description('节点完成/回滚')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--node-id <nodeId>', '节点 ID')
+        .option('--action <action>', 'confirm=完成，rollback=回滚')
+        .option('--rollback-reason <reason>', '回滚原因，action=rollback 时必填')
+        .option('--node-owners <userKeys>', '节点负责人，逗号分隔')
+        .option('--points <n>', '节点估分')
+        .option('--start <dateOrTimestamp>', '节点排期开始时间')
+        .option('--end <dateOrTimestamp>', '节点排期结束时间')
+        .option('--field <fieldSpec>', '字段赋值，格式 field_key=value；可重复', collectOptionValue, [])
+        .option('--body <json>', '内联 JSON，请求体对应 NodeOperateRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 NodeOperateRequest')
+        .addHelpText('after', `
+示例：
+  meegle workflow node-operate --project-key demo --type story --id 1 --node-id dev --action confirm
+  meegle workflow node-operate --project-key demo --type story --id 1 --node-id dev --action rollback --rollback-reason "需要返工"
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildWorkflowNodeOperateRequest(options);
+        await runGuarded({
+            id: 'workflow.node-operate',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/workflow/:work_item_type_key/:work_item_id/node/:node_id/operate',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workflow.operateNode(options.projectKey, options.type, parseInteger(options.id, 'id'), options.nodeId, body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    workflow
+        .command('node-update')
+        .description('更新节点信息')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--node-id <nodeId>', '节点 ID')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 UpdateNodeRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        await runGuarded({
+            id: 'workflow.node-update',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'PUT',
+                path: '/open_api/:project_key/workflow/:work_item_type_key/:work_item_id/node/:node_id',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workflow.updateNode(options.projectKey, options.type, parseInteger(options.id, 'id'), options.nodeId, body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    workflow
+        .command('required-info')
+        .description('获取流转所需必填信息')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 TransitionRequiredInfoRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workflow.required-info',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/work_item/transition_required_info/get' },
+        }, global, async (ctx) => ctx.client.workItem.workflow.getTransitionRequiredInfo(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    workflow
+        .command('wbs')
+        .description('获取 WBS 工作流详情')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--query-file <path>', 'JSON 文件，内容对应 WbsViewQueryParams')
+        .option('--body-file <path>', 'JSON 文件，内容对应 WbsViewRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const query = await readOptionalJsonFile(options.queryFile);
+        const body = await readOptionalJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workflow.wbs',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'GET',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/wbs_view',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workflow.getWbsView(options.projectKey, options.type, parseInteger(options.id, 'id'), { query, body }, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+}
+function registerComment(program) {
+    const comment = program.command('comment').description('评论命令');
+    comment
+        .command('list')
+        .description('查询评论')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--query-file <path>', 'JSON 文件，内容对应 ListCommentsQuery')
+        .option('--page-num <n>', '页码')
+        .option('--page-size <n>', '每页条数')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const query = (await readOptionalJsonFile(options.queryFile)) ?? {};
+        if (options.pageNum) {
+            query.page_num = parseInteger(options.pageNum, 'page-num');
+        }
+        if (options.pageSize) {
+            query.page_size = parseInteger(options.pageSize, 'page-size');
+        }
+        const result = await runGuarded({
+            id: 'comment.list',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'GET',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/comments',
+            },
+        }, global, async (ctx) => ctx.client.workItem.comment.list(options.projectKey, options.type, parseInteger(options.id, 'id'), query, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    comment
+        .command('add')
+        .description('添加评论')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--content <text>', '纯文本评论')
+        .option('--content-file <path>', '从文件读取纯文本评论')
+        .option('--rich-text <json>', '富文本 JSON，内容对应 CreateCommentRequest.rich_text')
+        .option('--rich-text-file <path>', '从文件读取富文本 JSON')
+        .option('--body <json>', '内联 JSON，请求体对应 CreateCommentRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 CreateCommentRequest')
+        .addHelpText('after', `
+示例：
+  meegle comment add --project-key demo --type story --id 1 --content "收到，开始处理"
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildCommentRequestBody('comment.add', options);
+        const result = await runGuarded({
+            id: 'comment.add',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/comment/create',
+            },
+        }, global, async (ctx) => ctx.client.workItem.comment.create(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    comment
+        .command('update')
+        .description('更新评论')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--comment-id <commentId>', '评论 ID')
+        .option('--content <text>', '纯文本评论')
+        .option('--content-file <path>', '从文件读取纯文本评论')
+        .option('--rich-text <json>', '富文本 JSON，内容对应 UpdateCommentRequest.rich_text')
+        .option('--rich-text-file <path>', '从文件读取富文本 JSON')
+        .option('--body <json>', '内联 JSON，请求体对应 UpdateCommentRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 UpdateCommentRequest')
+        .addHelpText('after', `
+示例：
+  meegle comment update --project-key demo --type story --id 1 --comment-id 123 --content "已修正"
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildCommentRequestBody('comment.update', options);
+        await runGuarded({
+            id: 'comment.update',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'PUT',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/comment/:comment_id',
+            },
+        }, global, async (ctx) => ctx.client.workItem.comment.update(options.projectKey, options.type, parseInteger(options.id, 'id'), options.commentId, body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    comment
+        .command('remove')
+        .description('删除评论')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--comment-id <commentId>', '评论 ID')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'comment.remove',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'DELETE',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/comment/:comment_id',
+            },
+        }, global, async (ctx) => ctx.client.workItem.comment.remove(options.projectKey, options.type, parseInteger(options.id, 'id'), options.commentId, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+}
+function registerSubtask(program) {
+    const subtask = program.command('subtask').description('子任务命令');
+    subtask
+        .command('list')
+        .description('获取子任务列表')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--query-file <path>', 'JSON 文件，内容对应 GetSubtasksQuery')
+        .option('--node-id <nodeId>', '节点 ID')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const query = (await readOptionalJsonFile(options.queryFile)) ?? {};
+        if (options.nodeId) {
+            query.node_id = options.nodeId;
+        }
+        const result = await runGuarded({
+            id: 'subtask.list',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'GET',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/workflow/task',
+            },
+        }, global, async (ctx) => ctx.client.workItem.subtask.list(options.projectKey, options.type, parseInteger(options.id, 'id'), query, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    subtask
+        .command('search')
+        .description('跨空间搜索子任务')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 SearchSubtasksRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'subtask.search',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/work_item/subtask/search' },
+        }, global, async (ctx) => ctx.client.workItem.subtask.search(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    subtask
+        .command('create')
+        .description('创建子任务')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--node-id <nodeId>', '目标节点 ID')
+        .option('--name <name>', '子任务名称')
+        .option('--note <text>', '备注文本')
+        .option('--note-file <path>', '从文件读取备注文本')
+        .option('--assignee <userKeys>', '负责人 userKey，逗号分隔')
+        .option('--points <n>', '估分')
+        .option('--start <dateOrTimestamp>', '排期开始时间')
+        .option('--end <dateOrTimestamp>', '排期结束时间')
+        .option('--field <fieldSpec>', '字段赋值，格式 field_key=value；可重复', collectOptionValue, [])
+        .option('--body <json>', '内联 JSON，请求体对应 CreateSubtaskRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 CreateSubtaskRequest')
+        .addHelpText('after', `
+示例：
+  meegle subtask create --project-key demo --type story --id 1 --node-id doing --name "需求分析"
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildSubtaskCreateRequest(options);
+        const result = await runGuarded({
+            id: 'subtask.create',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/workflow/task',
+            },
+        }, global, async (ctx) => ctx.client.workItem.subtask.create(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    subtask
+        .command('update')
+        .description('更新子任务')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--node-id <nodeId>', '节点 ID')
+        .requiredOption('--task-id <taskId>', '子任务 ID')
+        .option('--name <name>', '子任务名称')
+        .option('--note <text>', '备注文本')
+        .option('--note-file <path>', '从文件读取备注文本')
+        .option('--assignee <userKeys>', '负责人 userKey，逗号分隔')
+        .option('--points <n>', '估分')
+        .option('--start <dateOrTimestamp>', '排期开始时间')
+        .option('--end <dateOrTimestamp>', '排期结束时间')
+        .option('--field <fieldSpec>', '字段赋值，格式 field_key=value；可重复', collectOptionValue, [])
+        .option('--body <json>', '内联 JSON，请求体对应 UpdateSubtaskRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 UpdateSubtaskRequest')
+        .addHelpText('after', `
+示例：
+  meegle subtask update --project-key demo --type story --id 1 --node-id doing --task-id 10 --name "需求分析-已更新"
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildSubtaskUpdateRequest(options);
+        await runGuarded({
+            id: 'subtask.update',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/workflow/:node_id/task/:task_id',
+            },
+        }, global, async (ctx) => ctx.client.workItem.subtask.update(options.projectKey, options.type, parseInteger(options.id, 'id'), options.nodeId, parseInteger(options.taskId, 'task-id'), body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    subtask
+        .command('remove')
+        .description('删除子任务')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--task-id <taskId>', '子任务 ID')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'subtask.remove',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'DELETE',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/task/:task_id',
+            },
+        }, global, async (ctx) => ctx.client.workItem.subtask.remove(options.projectKey, options.type, parseInteger(options.id, 'id'), parseInteger(options.taskId, 'task-id'), { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    subtask
+        .command('operate')
+        .description('完成/回滚子任务')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .option('--node-id <nodeId>', '节点 ID')
+        .option('--task-id <taskId>', '子任务 ID')
+        .option('--action <action>', 'confirm=完成，rollback=回滚')
+        .option('--body <json>', '内联 JSON，请求体对应 CompleteRollbackSubtaskRequest')
+        .option('--body-file <path>', 'JSON 文件，内容对应 CompleteRollbackSubtaskRequest')
+        .addHelpText('after', `
+示例：
+  meegle subtask operate --project-key demo --type story --id 1 --node-id doing --task-id 10 --action confirm
+`)
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await buildSubtaskOperateRequest(options);
+        await runGuarded({
+            id: 'subtask.operate',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/subtask/modify',
+            },
+        }, global, async (ctx) => ctx.client.workItem.subtask.completeOrRollback(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+}
+function registerAttachment(program) {
+    const attachment = program.command('attachment').description('附件命令');
+    attachment
+        .command('upload-file')
+        .description('通用文件上传（富文本图片等）')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--file <path>', '本地文件路径')
+        .option('--file-name <name>', '上传文件名')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const file = await readFile(options.file);
+        const result = await runGuarded({
+            id: 'attachment.upload-file',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/file/upload' },
+        }, global, async (ctx) => ctx.client.workItem.attachment.uploadFile(options.projectKey, { file, fileName: options.fileName }, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    attachment
+        .command('upload')
+        .description('添加附件到工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--file <path>', '本地文件路径')
+        .option('--file-name <name>', '上传文件名')
+        .option('--field-key <fieldKey>', '附件字段 key')
+        .option('--field-alias <fieldAlias>', '附件字段 alias')
+        .option('--index <index>', '复合字段索引')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const file = await readFile(options.file);
+        await runGuarded({
+            id: 'attachment.upload',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/file/upload',
+            },
+        }, global, async (ctx) => ctx.client.workItem.attachment.uploadAttachment(options.projectKey, options.type, parseInteger(options.id, 'id'), {
+            file,
+            fileName: options.fileName,
+            field_key: options.fieldKey,
+            field_alias: options.fieldAlias,
+            index: options.index,
+        }, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    attachment
+        .command('download')
+        .description('下载附件')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--uuid <uuid>', '附件 UUID')
+        .requiredOption('--out <path>', '输出文件路径')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'attachment.download',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/file/download',
+            },
+        }, global, async (ctx) => {
+            const data = await ctx.client.workItem.attachment.downloadAttachment(options.projectKey, options.type, parseInteger(options.id, 'id'), { uuid: options.uuid }, { auth: ctx.auth });
+            await writeFile(options.out, Buffer.from(data));
+        });
+        printData({ ok: true, output: options.out }, Boolean(global.json));
+    });
+    attachment
+        .command('delete')
+        .description('删除附件')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 DeleteAttachmentRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        await runGuarded({
+            id: 'attachment.delete',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/file/delete' },
+        }, global, async (ctx) => ctx.client.workItem.attachment.deleteAttachment(body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+}
+function registerWorkHour(program) {
+    const workHour = program.command('workhour').description('工时命令');
+    workHour
+        .command('list')
+        .description('获取工时记录列表')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 ListWorkHourRecordsRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workhour.list',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/work_item/man_hour/records' },
+        }, global, async (ctx) => ctx.client.workItem.workHour.list(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    workHour
+        .command('create')
+        .description('创建工时记录')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 CreateWorkHourRecordRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'workhour.create',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'POST',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/work_hour_record',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workHour.create(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    workHour
+        .command('update')
+        .description('更新工时记录')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 UpdateWorkHourRecordRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        await runGuarded({
+            id: 'workhour.update',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'PUT',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/work_hour_record',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workHour.update(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    workHour
+        .command('delete')
+        .description('删除工时记录')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--id <workItemId>', '工作项 ID')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 DeleteWorkHourRecordRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        await runGuarded({
+            id: 'workhour.delete',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: {
+                method: 'DELETE',
+                path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id/work_hour_record',
+            },
+        }, global, async (ctx) => ctx.client.workItem.workHour.deleteRecords(options.projectKey, options.type, parseInteger(options.id, 'id'), body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+}
+function registerView(program) {
+    const view = program.command('view').description('视图命令');
+    view
+        .command('list')
+        .description('获取视图列表及配置')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 ViewConfListRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'view.list',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/view_conf/list' },
+        }, global, async (ctx) => ctx.client.view.query.listConfigs(options.projectKey, body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    view
+        .command('fix-items')
+        .description('获取固定视图下工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--view-id <viewId>', '视图 ID')
+        .option('--query-file <path>', 'JSON 文件，内容对应 FixViewQueryParams')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const query = await readOptionalJsonFile(options.queryFile);
+        const result = await runGuarded({
+            id: 'view.fix-items',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'GET', path: '/open_api/:project_key/fix_view/:view_id' },
+        }, global, async (ctx) => ctx.client.view.query.getFixViewItems(options.projectKey, options.viewId, query, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    view
+        .command('panoramic-items')
+        .description('获取全景视图下工作项')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--view-id <viewId>', '视图 ID')
+        .option('--body-file <path>', 'JSON 文件，内容对应 PanoramicViewQueryParams')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readOptionalJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'view.panoramic-items',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/view/:view_id' },
+        }, global, async (ctx) => ctx.client.view.query.listPanoramicItems(options.projectKey, options.viewId, body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    view
+        .command('create-fix')
+        .description('创建固定视图')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 CreateFixViewRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'view.create-fix',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/:work_item_type_key/fix_view' },
+        }, global, async (ctx) => ctx.client.view.createFixView(options.projectKey, options.type, body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    view
+        .command('update-fix')
+        .description('更新固定视图')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--type <workItemTypeKey>', '工作项类型 key')
+        .requiredOption('--view-id <viewId>', '视图 ID')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 UpdateFixViewRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        await runGuarded({
+            id: 'view.update-fix',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/:work_item_type_key/fix_view/:view_id' },
+        }, global, async (ctx) => ctx.client.view.updateFixView(options.projectKey, options.type, options.viewId, body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    view
+        .command('delete')
+        .description('删除视图')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--view-id <viewId>', '视图 ID')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'view.delete',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'DELETE', path: '/open_api/:project_key/fix_view/:view_id' },
+        }, global, async (ctx) => ctx.client.view.deleteView(options.projectKey, options.viewId, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+    view
+        .command('create-condition')
+        .description('创建条件视图')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 CreateConditionViewRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'view.create-condition',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/view/v1/create_condition_view' },
+        }, global, async (ctx) => ctx.client.view.createConditionView(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    view
+        .command('update-condition')
+        .description('更新条件视图')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 UpdateConditionViewRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        await runGuarded({
+            id: 'view.update-condition',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/view/v1/update_condition_view' },
+        }, global, async (ctx) => ctx.client.view.updateConditionView(body, { auth: ctx.auth }));
+        printOk(Boolean(global.json));
+    });
+}
+function registerMeasure(program) {
+    const measure = program.command('measure').description('度量命令');
+    measure
+        .command('charts')
+        .description('按视图查询图表列表')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 MeasureChartsByViewRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const body = await readJsonFile(options.bodyFile);
+        const result = await runGuarded({
+            id: 'measure.charts',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/measure/charts' },
+        }, global, async (ctx) => ctx.client.measure.query.listChartsByView(body, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    measure
+        .command('chart-data')
+        .description('获取图表明细数据')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--chart-id <chartId>', '图表 ID')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'measure.chart-data',
+            authPolicy: 'PLUGIN_WITH_USER_KEY',
+            endpoint: { method: 'GET', path: '/open_api/:project_key/measure/:chart_id' },
+        }, global, async (ctx) => ctx.client.measure.getChartData(options.projectKey, options.chartId, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+}
+function registerTenant(program) {
+    const tenant = program.command('tenant').description('租户命令');
+    tenant
+        .command('info')
+        .description('获取商业租户信息')
+        .requiredOption('--tenant-key <tenantKey>', '租户 key')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'tenant.info',
+            authPolicy: 'PLUGIN_OPTIONAL_USER_KEY',
+            endpoint: { method: 'GET', path: '/open_api/commercial/tenant' },
+        }, global, async (ctx) => ctx.client.tenant.getInfo(options.tenantKey, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    tenant
+        .command('entitlement')
+        .description('查询租户权益')
+        .requiredOption('--tenant-key <tenantKey>', '租户 key')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'tenant.entitlement',
+            authPolicy: 'PLUGIN_OPTIONAL_USER_KEY',
+            endpoint: { method: 'GET', path: '/open_api/commercial/product/tenant_entitlement' },
+        }, global, async (ctx) => ctx.client.tenant.getEntitlement(options.tenantKey, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    tenant
+        .command('spaces')
+        .description('获取租户安装空间列表')
+        .requiredOption('--tenant-key <tenantKey>', '租户 key')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'tenant.spaces',
+            authPolicy: 'PLUGIN_OPTIONAL_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/tenant/projects/install/list' },
+        }, global, async (ctx) => ctx.client.tenant.listInstalledSpaces(options.tenantKey, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+}
+function registerUser(program) {
+    const user = program.command('user').description('用户相关命令');
+    user
+        .command('query')
+        .description('按 user_key/out_id/email 查询用户详情')
+        .option('--self', '直接查询当前 userKey 对应的用户')
+        .option('--user-keys <userKeys>', '逗号分隔')
+        .option('--out-ids <outIds>', '逗号分隔')
+        .option('--emails <emails>', '逗号分隔')
+        .option('--tenant-key <tenantKey>', '跨租户邮件查询使用')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'user.query',
+            authPolicy: 'PLUGIN_OPTIONAL_USER_KEY',
+            endpoint: { method: 'POST', path: '/open_api/user/query' },
+        }, global, async (ctx) => {
+            const userKeys = [
+                ...(options.self && ctx.userKey ? [ctx.userKey] : []),
+                ...parseCsv(options.userKeys),
+            ];
+            const outIds = parseCsv(options.outIds);
+            const emails = parseCsv(options.emails);
+            if (userKeys.length === 0 && outIds.length === 0 && emails.length === 0) {
+                throw new CliError('user query 至少需要 --self / --user-keys / --out-ids / --emails 之一', 2);
+            }
+            return ctx.client.user.query({
+                user_keys: userKeys.length > 0 ? userKeys : undefined,
+                out_ids: outIds.length > 0 ? outIds : undefined,
+                emails: emails.length > 0 ? emails : undefined,
+                tenant_key: options.tenantKey,
+            }, { auth: ctx.auth });
+        });
+        printData(result, Boolean(global.json));
+    });
+    user
+        .command('search')
+        .description('搜索租户内用户（仅支持 user_access_token，plugin-only 会拒绝）')
+        .requiredOption('--query <query>', '搜索关键词')
+        .option('--project-key <projectKey>', '空间 key')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        const result = await runGuarded({
+            id: 'user.search',
+            authPolicy: 'USER_TOKEN_REQUIRED',
+            endpoint: { method: 'POST', path: '/open_api/user/search' },
+        }, global, async (ctx) => ctx.client.user.search({
+            query: options.query,
+            project_key: options.projectKey,
+        }, { auth: ctx.auth }));
+        printData(result, Boolean(global.json));
+    });
+    const group = user.command('group').description('用户组命令（当前 plugin-only 拒绝）');
+    group
+        .command('create')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 CreateUserGroupRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'user.group.create',
+            authPolicy: 'USER_TOKEN_REQUIRED',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/user_group' },
+        }, global, async (ctx) => {
+            const body = await readJsonFile(options.bodyFile);
+            return ctx.client.user.group.create(options.projectKey, body, { auth: ctx.auth });
+        });
+    });
+    group
+        .command('update-members')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 UpdateUserGroupMembersRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'user.group.update-members',
+            authPolicy: 'USER_TOKEN_REQUIRED',
+            endpoint: { method: 'PATCH', path: '/open_api/:project_key/user_group/members' },
+        }, global, async (ctx) => {
+            const body = await readJsonFile(options.bodyFile);
+            return ctx.client.user.group.updateMembers(options.projectKey, body, { auth: ctx.auth });
+        });
+    });
+    group
+        .command('query-members')
+        .requiredOption('--project-key <projectKey>', '空间 key')
+        .requiredOption('--body-file <path>', 'JSON 文件，内容对应 QueryUserGroupMembersRequest')
+        .action(async (options) => {
+        const global = resolveGlobal(program);
+        await runGuarded({
+            id: 'user.group.query-members',
+            authPolicy: 'USER_TOKEN_REQUIRED',
+            endpoint: { method: 'POST', path: '/open_api/:project_key/user_groups/members/page' },
+        }, global, async (ctx) => {
+            const body = await readJsonFile(options.bodyFile);
+            return ctx.client.user.group.queryMembers(options.projectKey, body, { auth: ctx.auth });
+        });
+    });
+}
+export function buildCli() {
+    const program = new Command();
+    program
+        .name('meegle')
+        .description('Meegle plugin-only CLI (基于 meeglesdk)')
+        .option('--profile <name>', 'profile 名称，默认 active profile')
+        .option('--user-key <userKey>', '本次命令覆盖 userKey')
+        .option('--compat-auth', '读接口使用兼容模式 (x-auth-mode=0)，默认严格模式')
+        .option('--json', '输出 JSON')
+        .addHelpText('after', `
+常用示例：
+  meegle auth init --target-profile demo --plugin-id <id> --plugin-secret <secret> --default-user-key <userKey>
+  meegle --profile demo auth status
+  meegle --profile demo space list
+  meegle --profile demo user query --self
+  meegle --profile demo workitem get --project-key <projectKey> --type story --id 6300034462
+  meegle --profile demo workitem create --project-key <projectKey> --type story --name "登录优化"
+  meegle --profile demo comment add --project-key <projectKey> --type story --id 6300034462 --content "收到"
+  meegle --profile demo subtask create --project-key <projectKey> --type story --id 6300034462 --node-id doing --name "需求分析"
+  meegle --profile demo workflow state-change --project-key <projectKey> --type story --id 6300034462 --transition-id 12345
+`);
+    registerAuth(program);
+    registerSpace(program);
+    registerWorkItem(program);
+    registerWorkflow(program);
+    registerComment(program);
+    registerSubtask(program);
+    registerAttachment(program);
+    registerWorkHour(program);
+    registerView(program);
+    registerMeasure(program);
+    registerTenant(program);
+    registerUser(program);
+    return program;
+}