@cloudglab/yapi-cli 0.0.7 → 0.0.9

package/dist/tools/yapi/register-util.js

@@ -1,10 +1,9 @@
-import { existsSync, mkdirSync, copyFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { CliConfigError, CliError, CliValidationError } from '../../core/errors.js';
 import { parseYApiPageUrl } from '../../core/url-parser.js';
-import { exportFormatEnum, jsonResult, optionalBool, paginationSchema, projectIdSchema } from '../shared.js';
+import { installSkill } from '../../install.js';
+import { exportFormatEnum, jsonResult, optionalBool, paginationSchema, projectIdSchema, confirmSchema, runWithPreview } from '../shared.js';
+import { previewOrAssertWriteAllowed } from '../../core/write-guard.js';
 import { createYApiServices } from './utils.js';
 import { CLI_VERSION } from '../../version.js';
 import { syncDocsToProject, watchAndSync, formatSyncResult } from './docs-sync.js';
@@ -15,6 +14,13 @@ const userBaseSchema = {
 const colBaseSchema = {
     ...projectIdSchema,
 };
+/** 类型守卫：从 unknown 中提取带 list 数组字段的对象。 */
+function isRecordWithList(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const list = value.list;
+    return Array.isArray(list);
+}
 export function registerUtilCommands(registry) {
     registry.tool('url-parse', {
         url: z.string().url().describe('浏览器里的 YApi 页面 URL，必填。CLI 会优先用当前配置的 YApi 服务器地址做匹配，再解析其中的 projectId / interfaceId / catId / colId / caseId / groupId / uid。'),
@@ -123,7 +129,7 @@ export function registerUtilCommands(registry) {
         nextBestTools: ['user-search', 'project-list'],
     });
     registry.tool('user-search', {
-        query: z.string().describe('搜索关键词，必填。通常按用户名或邮箱做模糊匹配，大小写与命中规则由服务端决定。'),
+        query: z.string().trim().min(1).describe('搜索关键词，必填。通常按用户名或邮箱做模糊匹配，大小写与命中规则由服务端决定。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.searchUsers(input.query);
@@ -142,20 +148,29 @@ export function registerUtilCommands(registry) {
     });
     registry.tool('export', {
         ...projectIdSchema,
-        format: exportFormatEnum.describe('导出格式，可选枚举 json / swagger / openapi3，默认 json。不同格式返回的数据结构不同。'),
+        format: exportFormatEnum.describe('导出格式，可选枚举 json / swagger / openapi3 / html / markdown，默认 json。html/markdown 走标准 YApi 导出插件；json/swagger/openapi3 走 GTest 扩展导出接口。'),
+        status: z.string().optional().describe('按接口状态过滤，可选。仅在 html/markdown/json（插件导出）格式下生效，常用值 done / undone。'),
     }, async (input) => {
         const { api } = createYApiServices();
-        const data = input.format === 'json'
-            ? await api.exportProjectJson(input.projectId)
-            : input.format === 'swagger'
-                ? await api.exportProjectSwagger(input.projectId)
-                : await api.exportProjectOpenAPI3(input.projectId);
+        let data;
+        if (input.format === 'html' || input.format === 'markdown') {
+            data = await api.exportProjectData(input.projectId, input.format, input.status);
+        }
+        else if (input.format === 'json') {
+            data = await api.exportProjectJson(input.projectId);
+        }
+        else if (input.format === 'swagger') {
+            data = await api.exportProjectSwagger(input.projectId);
+        }
+        else {
+            data = await api.exportProjectOpenAPI3(input.projectId);
+        }
         return jsonResult({
             projectId: input.projectId,
             format: input.format,
             data,
         });
-    }, '导出项目数据（JSON/Swagger/OpenAPI3）', {
+    }, '导出项目数据（JSON/Swagger/OpenAPI3/HTML/Markdown）', {
         costHint: 'low',
         nextBestTools: ['interface-list', 'project-get'],
     });
@@ -176,7 +191,7 @@ export function registerUtilCommands(registry) {
     });
     registry.tool('col-cases', {
         ...projectIdSchema,
-        colId: z.coerce.number().describe('集合 ID，必填。返回该集合下的用例摘要列表，不会自动展开完整请求体。'),
+        colId: z.number().int().positive().describe('集合 ID，必填。返回该集合下的用例摘要列表，不会自动展开完整请求体。'),
     }, async (input) => {
         if (Number.isNaN(input.colId)) {
             throw new CliValidationError('无效的集合 ID', '请使用 --col-id <number>');
@@ -198,96 +213,121 @@ export function registerUtilCommands(registry) {
     });
     registry.tool('col-create', {
         ...projectIdSchema,
-        name: z.string().describe('集合名称，必填。建议按场景或环境命名，例如 回归冒烟-生产。'),
+        name: z.string().trim().min(1).describe('集合名称，必填。建议按场景或环境命名，例如 回归冒烟-生产。'),
         desc: z.string().optional().describe('集合描述，可选，纯文本展示，用于说明这组用例的用途。'),
-    }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.createCollection({
-            project_id: input.projectId,
-            name: input.name,
-            desc: input.desc,
-        });
-        return jsonResult({
-            action: 'create',
-            projectId: input.projectId,
-            colId: result.data._id,
-            name: input.name,
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('col-create', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.createCollection({
+                project_id: input.projectId,
+                name: input.name,
+                desc: input.desc,
+            });
+            return jsonResult({
+                action: 'create',
+                projectId: input.projectId,
+                colId: result.data._id,
+                name: input.name,
+            });
         });
     }, '测试集合管理：创建集合', {
         costHint: 'medium',
         nextBestTools: ['col-list', 'col-cases'],
     });
     registry.tool('col-delete', {
-        colId: z.coerce.number().describe('集合 ID，必填。删除后该集合与集合内用例的关联会被清理。'),
+        colId: z.number().int().positive().describe('集合 ID，必填。删除后该集合与集合内用例的关联会被清理。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (Number.isNaN(input.colId)) {
-            throw new CliValidationError('无效的集合 ID', '请使用 --col-id <number>');
-        }
-        const { api } = createYApiServices();
-        await api.deleteCollection(input.colId);
-        return jsonResult({
-            action: 'delete',
-            colId: input.colId,
-            deleted: true,
+        const payload = input;
+        return runWithPreview('col-delete', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (Number.isNaN(input.colId)) {
+                throw new CliValidationError('无效的集合 ID', '请使用 --col-id <number>');
+            }
+            const { api } = createYApiServices();
+            await api.deleteCollection(input.colId);
+            return jsonResult({
+                action: 'delete',
+                colId: input.colId,
+                deleted: true,
+            });
         });
     }, '测试集合管理：删除集合', {
         costHint: 'medium',
         nextBestTools: ['col-list', 'col-cases'],
     });
     registry.tool('case-add', {
-        colId: z.coerce.number().describe('集合 ID，必填。新用例会被添加到这个测试集合。'),
-        method: z.string().optional().default('GET').describe('HTTP 方法，默认 GET，作为该测试用例保存的请求方法。'),
-        url: z.string().optional().describe('请求路径，可选，保存到用例的 req_url 字段，通常填写接口相对路径或完整 URL。'),
-    }, async (input) => {
-        if (Number.isNaN(input.colId)) {
-            throw new CliValidationError('无效的集合 ID', '请使用 --col-id <number>');
-        }
-        const { api } = createYApiServices();
-        const result = await api.addTestCase({
-            col_id: input.colId,
-            req_method: input.method,
-            req_url: input.url,
-        });
-        return jsonResult({
-            action: 'add',
-            colId: input.colId,
-            caseId: result.data._id,
-            method: input.method,
-            url: input.url,
+        ...projectIdSchema,
+        colId: z.number().int().positive().describe('集合 ID，必填。新用例会被添加到这个测试集合。'),
+        interfaceId: z.number().int().positive().describe('接口 ID，必填。测试用例关联的接口，YApi 会复用该接口的请求定义。'),
+        name: z.string().trim().min(1).describe('用例名称，必填。'),
+        env: z.string().optional().describe('用例环境标识，可选。对应接口所在项目的环境 name。'),
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('case-add', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (Number.isNaN(input.colId)) {
+                throw new CliValidationError('无效的集合 ID', '请使用 --col-id <number>');
+            }
+            const { api } = createYApiServices();
+            const result = await api.addTestCase({
+                project_id: input.projectId,
+                col_id: input.colId,
+                interface_id: input.interfaceId,
+                casename: input.name,
+                case_env: input.env,
+            });
+            return jsonResult({
+                action: 'add',
+                projectId: input.projectId,
+                colId: input.colId,
+                interfaceId: input.interfaceId,
+                caseId: result.data._id,
+                name: input.name,
+            });
         });
     }, '测试用例管理：添加用例', {
         costHint: 'medium',
         nextBestTools: ['col-cases', 'case-run'],
     });
     registry.tool('case-delete', {
-        caseId: z.coerce.number().describe('用例 ID，必填。仅删除单条测试用例，不会删除所属集合。'),
+        caseId: z.number().int().positive().describe('用例 ID，必填。仅删除单条测试用例，不会删除所属集合。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (Number.isNaN(input.caseId)) {
-            throw new CliValidationError('无效的用例 ID', '请使用 --case-id <number>');
-        }
-        const { api } = createYApiServices();
-        await api.deleteTestCase(input.caseId);
-        return jsonResult({
-            action: 'delete',
-            caseId: input.caseId,
-            deleted: true,
+        const payload = input;
+        return runWithPreview('case-delete', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (Number.isNaN(input.caseId)) {
+                throw new CliValidationError('无效的用例 ID', '请使用 --case-id <number>');
+            }
+            const { api } = createYApiServices();
+            await api.deleteTestCase(input.caseId);
+            return jsonResult({
+                action: 'delete',
+                caseId: input.caseId,
+                deleted: true,
+            });
         });
     }, '测试用例管理：删除用例', {
         costHint: 'medium',
         nextBestTools: ['col-cases', 'case-run'],
     });
     registry.tool('case-run', {
-        colId: z.coerce.number().describe('集合 ID，必填。会执行该集合绑定的测试脚本或用例。'),
+        colId: z.number().int().positive().describe('集合 ID，必填。会执行该集合绑定的测试脚本或用例。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (Number.isNaN(input.colId)) {
-            throw new CliValidationError('无效的集合 ID', '请使用 --col-id <number>');
-        }
-        const { api } = createYApiServices();
-        const result = await api.runTestCaseScript({ col_id: input.colId });
-        return jsonResult({
-            action: 'run',
-            colId: input.colId,
-            result: result.data,
+        const payload = input;
+        return runWithPreview('case-run', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (Number.isNaN(input.colId)) {
+                throw new CliValidationError('无效的集合 ID', '请使用 --col-id <number>');
+            }
+            const { api } = createYApiServices();
+            const result = await api.runTestCaseScript({ col_id: input.colId });
+            return jsonResult({
+                action: 'run',
+                colId: input.colId,
+                result: result.data,
+            });
         });
     }, '测试用例管理：运行集合脚本', {
         costHint: 'high',
@@ -296,6 +336,8 @@ export function registerUtilCommands(registry) {
     registry.tool('self-update', {
         channel: z.enum(['latest', 'next']).optional().default('latest').describe('npm 发布渠道'),
     }, async (input) => {
+        // self-update 只查询 npm registry 最新版本号，不执行任何写入，
+        // 因此不走写保护（confirmSchema / runWithPreview），避免误导调用方确认。
         const currentVersion = CLI_VERSION;
         const packageName = '@cloudglab/yapi-cli';
         const url = `https://registry.npmjs.org/${packageName}/${input.channel}`;
@@ -324,77 +366,79 @@ export function registerUtilCommands(registry) {
         nextBestTools: ['install', 'version'],
     });
     registry.tool('docs-sync', {
-        file: z.string().describe('Markdown 文档路径'),
-        projectId: z.coerce.number().describe('目标项目 ID'),
-        catId: z.coerce.number().describe('目标分类（目录）ID'),
+        file: z.string().trim().min(1).describe('Markdown 文档路径'),
+        projectId: z.number().int().positive().describe('目标项目 ID'),
+        catId: z.number().int().positive().describe('目标分类（目录）ID'),
         merge: z.enum(['create', 'update', 'skip']).default('create').describe('已有接口处理策略'),
         watch: optionalBool.describe('监听文件变更'),
-    }, async (input) => {
-        const { api } = createYApiServices();
-        if (input.watch) {
-            process.stdout.write(`开始监听 ${input.file} ...\n`);
-            await watchAndSync(api, input.projectId, input.catId, input.file, (result) => {
-                process.stdout.write(`\n[${new Date().toLocaleTimeString()}] 同步完成:\n`);
-                process.stdout.write(`${formatSyncResult(result)}\n`);
-            });
-            const first = await syncDocsToProject(api, input.projectId, input.catId, input.file, input.merge);
-            process.stdout.write(`首次同步完成:\n${formatSyncResult(first)}\n`);
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('docs-sync', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            if (input.watch) {
+                process.stdout.write(`开始监听 ${input.file} ...\n`);
+                const stopWatching = await watchAndSync(api, input.projectId, input.catId, input.file, (result) => {
+                    process.stdout.write(`\n[${new Date().toLocaleTimeString()}] 同步完成:\n`);
+                    process.stdout.write(`${formatSyncResult(result)}\n`);
+                });
+                const first = await syncDocsToProject(api, input.projectId, input.catId, input.file, input.merge);
+                process.stdout.write(`首次同步完成:\n${formatSyncResult(first)}\n`);
+                // 保存 disposer：Ctrl+C 退出时清理 watcher，避免文件描述符泄漏
+                process.on('SIGINT', () => {
+                    try {
+                        stopWatching();
+                    }
+                    catch {
+                        // 忽略清理错误
+                    }
+                    process.exit(0);
+                });
+                return jsonResult({
+                    watching: true,
+                    message: `正在监听 ${input.file}，按 Ctrl+C 停止`,
+                    syncResult: first,
+                });
+            }
+            const result = await syncDocsToProject(api, input.projectId, input.catId, input.file, input.merge);
             return jsonResult({
-                watching: true,
-                message: `正在监听 ${input.file}，按 Ctrl+C 停止`,
-                syncResult: first,
+                details: result,
+                message: formatSyncResult(result),
             });
-        }
-        const result = await syncDocsToProject(api, input.projectId, input.catId, input.file, input.merge);
-        return jsonResult({
-            details: result,
-            message: formatSyncResult(result),
         });
     }, '同步 Markdown 文档到 YApi 项目', {
         costHint: 'medium',
         nextBestTools: ['self-update', 'interface-list'],
     });
     registry.tool('install-skill', {
-        skillPath: z.string().optional().describe('自定义 skill 文件路径'),
+        skillPath: z.string().optional().describe('自定义本地 skill 目录路径，省略则从已安装包安装'),
         yes: z.coerce.boolean().optional().default(false).describe('覆盖已有配置'),
-    }, async (input) => {
-        const moduleDir = dirname(fileURLToPath(import.meta.url));
-        const opencodeAgentDir = join(process.env.HOME || '', '.opencode', 'agent');
-        if (input.skillPath) {
-            const target = join(opencodeAgentDir, 'yapi-cli.md');
-            if (!existsSync(dirname(target))) {
-                mkdirSync(dirname(target), { recursive: true });
-            }
-            copyFileSync(input.skillPath, target);
-            return jsonResult({ message: `Skill 已安装到: ${target}` });
-        }
-        const possiblePaths = [
-            join(moduleDir, '..', '..', '..', 'skills', 'yapi-cli', 'SKILL.md'),
-            join(moduleDir, '..', '..', 'skills', 'yapi-cli', 'SKILL.md'),
-        ];
-        for (const skillPath of possiblePaths) {
-            try {
-                if (existsSync(skillPath)) {
-                    const target = join(opencodeAgentDir, 'yapi-cli.md');
-                    if (!existsSync(dirname(target))) {
-                        mkdirSync(dirname(target), { recursive: true });
-                    }
-                    copyFileSync(skillPath, target);
-                    return jsonResult({ message: `Skill 已安装到: ${target}` });
-                }
-            }
-            catch {
-                continue;
-            }
-        }
-        throw new CliValidationError('未找到内置 skill 文件。可通过 --skillPath 指定路径');
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('install-skill', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const options = {
+                cliOnly: false,
+                skillOnly: true,
+                skillSource: 'local',
+                skillLocalPath: input.skillPath,
+                yes: input.yes,
+                keepConfig: false,
+            };
+            await installSkill('安装', options);
+            return jsonResult({
+                message: input.skillPath
+                    ? `已从 ${input.skillPath} 安装 yapi skill 到全局`
+                    : '已安装 yapi skill 到全局',
+            });
+        });
     }, '安装 OpenCode skill 文件', {
         costHint: 'medium',
         nextBestTools: ['self-update', 'config-init'],
     });
     // ==================== 用户详情 ====================
     registry.tool('user-get', {
-        uid: z.coerce.number().describe('用户 UID'),
+        uid: z.number().int().positive().describe('用户 UID'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.findUserById(input.uid);
@@ -409,20 +453,24 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 修改密码 ====================
     registry.tool('user-change-password', {
-        oldPassword: z.string().describe('旧密码'),
-        newPassword: z.string().describe('新密码'),
-    }, async (input) => {
-        if (input.oldPassword.length === 0 || input.newPassword.length === 0) {
-            throw new CliValidationError('旧密码和新密码不能为空', '请同时提供 --old-password 和 --new-password');
-        }
-        const { api } = createYApiServices();
-        await api.changePassword({
-            old_password: input.oldPassword,
-            new_password: input.newPassword,
-        });
-        return jsonResult({
-            action: 'change-password',
-            message: '密码已更新',
+        oldPassword: z.string().trim().min(1).describe('旧密码'),
+        newPassword: z.string().trim().min(1).describe('新密码'),
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('user-change-password', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.oldPassword.length === 0 || input.newPassword.length === 0) {
+                throw new CliValidationError('旧密码和新密码不能为空', '请同时提供 --old-password 和 --new-password');
+            }
+            const { api } = createYApiServices();
+            await api.changePassword({
+                old_password: input.oldPassword,
+                new_password: input.newPassword,
+            });
+            return jsonResult({
+                action: 'change-password',
+                message: '密码已更新',
+            });
         });
     }, '用户管理：修改当前用户密码', {
         costHint: 'medium',
@@ -430,37 +478,41 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 用户注册 ====================
     registry.tool('user-register', {
-        username: z.string().describe('用户名'),
-        password: z.string().describe('密码'),
+        username: z.string().trim().min(1).describe('用户名'),
+        password: z.string().trim().min(1).describe('密码'),
         email: z.string().email().describe('邮箱'),
         role: z
             .enum(['admin', 'owner', 'dev', 'guest', 'viewer'])
             .optional()
             .describe('角色（admin/owner/dev/guest/viewer）'),
+        ...confirmSchema,
     }, async (input) => {
-        if (input.username.length === 0) {
-            throw new CliValidationError('用户名不能为空', '请提供 --username');
-        }
-        if (input.password.length === 0) {
-            throw new CliValidationError('密码不能为空', '请提供 --password');
-        }
-        const { api } = createYApiServices();
-        const result = await api.userRegister({
-            username: input.username,
-            password: input.password,
-            email: input.email,
-            role: input.role,
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '用户注册失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            action: 'user-register',
-            userId: result.data?._id,
-            username: input.username,
-            email: input.email,
-            role: input.role,
-            message: `用户 ${input.username} 注册成功`,
+        const payload = input;
+        return runWithPreview('user-register', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.username.length === 0) {
+                throw new CliValidationError('用户名不能为空', '请提供 --username');
+            }
+            if (input.password.length === 0) {
+                throw new CliValidationError('密码不能为空', '请提供 --password');
+            }
+            const { api } = createYApiServices();
+            const result = await api.userRegister({
+                username: input.username,
+                password: input.password,
+                email: input.email,
+                role: input.role,
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '用户注册失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                action: 'user-register',
+                userId: result.data?._id,
+                username: input.username,
+                email: input.email,
+                role: input.role,
+                message: `用户 ${input.username} 注册成功`,
+            });
         });
     }, '用户管理：注册新用户（需要管理员权限）', {
         costHint: 'medium',
@@ -468,14 +520,18 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 用户删除 ====================
     registry.tool('user-delete', {
-        uid: z.coerce.number().describe('用户 UID'),
+        uid: z.number().int().positive().describe('用户 UID'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        await api.userDelete(input.uid);
-        return jsonResult({
-            action: 'user-delete',
-            uid: input.uid,
-            message: `用户 ${input.uid} 已删除`,
+        const payload = input;
+        return runWithPreview('user-delete', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            await api.userDelete(input.uid);
+            return jsonResult({
+                action: 'user-delete',
+                uid: input.uid,
+                message: `用户 ${input.uid} 已删除`,
+            });
         });
     }, '用户管理：删除用户（需要管理员权限，不可恢复）', {
         costHint: 'medium',
@@ -483,20 +539,24 @@ export function registerUtilCommands(registry) {
     });
     // ==================== Token 登录 ====================
     registry.tool('login-by-token', {
-        token: z.string().describe('YApi 用户 token，必填。用于直接校验 token 是否有效，并按当前实现写入本地认证上下文。'),
+        token: z.string().trim().min(1).describe('YApi 用户 token，必填。用于直接校验 token 是否有效，并按当前实现写入本地认证上下文。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (input.token.length === 0) {
-            throw new CliValidationError('token 不能为空', '请提供 --token');
-        }
-        const { api } = createYApiServices();
-        const result = await api.loginByToken(input.token);
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? 'token 登录失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            action: 'login-by-token',
-            user: result.data,
-            message: `token 验证通过：${result.data?.username ?? ''}`,
+        const payload = input;
+        return runWithPreview('login-by-token', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.token.length === 0) {
+                throw new CliValidationError('token 不能为空', '请提供 --token');
+            }
+            const { api } = createYApiServices();
+            const result = await api.loginByToken(input.token);
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? 'token 登录失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                action: 'login-by-token',
+                user: result.data,
+                message: `token 验证通过：${result.data?.username ?? ''}`,
+            });
         });
     }, '用户管理：使用 token 静默登录（校验 token 有效性）', {
         costHint: 'low',
@@ -504,7 +564,7 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 用户头像 ====================
     registry.tool('user-avatar', {
-        uid: z.coerce.number().describe('用户 UID，必填。返回该用户当前头像地址或头像资源信息。'),
+        uid: z.number().int().positive().describe('用户 UID，必填。返回该用户当前头像地址或头像资源信息。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.getUserAvatar(input.uid);
@@ -519,24 +579,28 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 上传头像 ====================
     registry.tool('user-upload-avatar', {
-        uid: z.coerce.number().describe('用户 UID，必填。通常只能更新当前用户或管理员可见用户。'),
-        base64: z.string().describe('图片 base64 编码，必填，不含 data:image/...;base64, 前缀。建议传纯图片内容，避免额外前缀导致服务端解析失败。'),
-    }, async (input) => {
-        if (input.base64.length === 0) {
-            throw new CliValidationError('base64 不能为空', '请提供 --base64');
-        }
-        const { api } = createYApiServices();
-        const result = await api.uploadUserAvatar({
-            uid: input.uid,
-            base64: input.base64,
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '上传头像失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            action: 'user-upload-avatar',
-            uid: input.uid,
-            message: '头像上传成功',
+        uid: z.number().int().positive().describe('用户 UID，必填。通常只能更新当前用户或管理员可见用户。'),
+        base64: z.string().trim().min(1).describe('图片 base64 编码，必填，不含 data:image/...;base64, 前缀。建议传纯图片内容，避免额外前缀导致服务端解析失败。'),
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('user-upload-avatar', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.base64.length === 0) {
+                throw new CliValidationError('base64 不能为空', '请提供 --base64');
+            }
+            const { api } = createYApiServices();
+            const result = await api.uploadUserAvatar({
+                uid: input.uid,
+                basecode: input.base64,
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '上传头像失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                action: 'user-upload-avatar',
+                uid: input.uid,
+                message: '头像上传成功',
+            });
         });
     }, '用户管理：上传用户头像', {
         costHint: 'medium',
@@ -546,9 +610,7 @@ export function registerUtilCommands(registry) {
     registry.tool('user-projects', {}, async () => {
         const { api } = createYApiServices();
         const result = await api.listUserProjects();
-        const projects = Array.isArray(result.data)
-            ? result.data
-            : result.data?.list ?? [];
+        const projects = Array.isArray(result.data) ? result.data : [];
         return jsonResult({
             action: 'user-projects',
             total: projects.length,
@@ -566,19 +628,19 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 动态日志（按更新时间） ====================
     registry.tool('log-list-by-update', {
-        apid: z.coerce.number().describe('接口 ID，必填。用于定位要查询日志的目标接口。'),
+        apid: z.number().int().positive().describe('接口 ID，必填。用于定位要查询日志的目标接口。'),
         type: z.string().optional().default('interface').describe('日志类型，默认 interface。若服务端支持其他类型，可按后端要求传值。'),
-        limit: z.coerce.number().optional().describe('返回条数限制，可选。值越大返回的日志越多，但结构化输出也会更长。'),
+        limit: z.number().int().positive().optional().describe('返回条数限制，可选。值越大返回的日志越多，但结构化输出也会更长。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.listLogsByUpdate({
             type: input.type,
-            apid: input.apid,
+            typeid: input.apid,
             limit: input.limit,
         });
         return jsonResult({
             action: 'logs-by-update',
-            apid: input.apid,
+            typeid: input.apid,
             type: input.type,
             logs: result.data,
         });
@@ -589,7 +651,7 @@ export function registerUtilCommands(registry) {
     // ==================== 用例列表（按变量参数过滤） ====================
     registry.tool('col-case-list-by-var-params', {
         ...projectIdSchema,
-        colId: z.coerce.number().describe('集合 ID'),
+        colId: z.number().int().positive().describe('集合 ID'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.getCaseListByVariableParams(input.colId);
@@ -605,23 +667,27 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 用例排序 ====================
     registry.tool('col-case-up-index', {
-        colId: z.coerce.number().describe('集合 ID'),
-        ids: z.string().describe('用例 ID 列表（逗号分隔，例如: 1,2,3）'),
-    }, async (input) => {
-        const parsed = input.ids
-            .split(',')
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0)
-            .map((s) => Number(s));
-        if (parsed.length === 0 || parsed.some((n) => Number.isNaN(n))) {
-            throw new CliValidationError('ids 必须是合法的逗号分隔数字', '请提供 --ids 例如: --ids 1,2,3');
-        }
-        const { api } = createYApiServices();
-        await api.upCaseIndex({ col_id: input.colId, ids: parsed });
-        return jsonResult({
-            action: 'case-up-index',
-            colId: input.colId,
-            ids: parsed,
+        colId: z.number().int().positive().describe('集合 ID'),
+        ids: z.string().trim().min(1).describe('用例 ID 列表（逗号分隔，例如: 1,2,3）'),
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('col-case-up-index', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const parsed = input.ids
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+                .map((s) => Number(s));
+            if (parsed.length === 0 || parsed.some((n) => Number.isNaN(n))) {
+                throw new CliValidationError('ids 必须是合法的逗号分隔数字', '请提供 --ids 例如: --ids 1,2,3');
+            }
+            const { api } = createYApiServices();
+            await api.upCaseIndex({ col_id: input.colId, ids: parsed });
+            return jsonResult({
+                action: 'case-up-index',
+                colId: input.colId,
+                ids: parsed,
+            });
         });
     }, '测试用例：调整用例排序', {
         costHint: 'medium',
@@ -630,22 +696,26 @@ export function registerUtilCommands(registry) {
     // ==================== 集合排序 ====================
     registry.tool('col-up-index', {
         ...projectIdSchema,
-        ids: z.string().describe('集合 ID 列表（逗号分隔，例如: 1,2,3）'),
-    }, async (input) => {
-        const parsed = input.ids
-            .split(',')
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0)
-            .map((s) => Number(s));
-        if (parsed.length === 0 || parsed.some((n) => Number.isNaN(n))) {
-            throw new CliValidationError('ids 必须是合法的逗号分隔数字', '请提供 --ids 例如: --ids 1,2,3');
-        }
-        const { api } = createYApiServices();
-        await api.upColIndex({ project_id: input.projectId, ids: parsed });
-        return jsonResult({
-            action: 'col-up-index',
-            projectId: input.projectId,
-            ids: parsed,
+        ids: z.string().trim().min(1).describe('集合 ID 列表（逗号分隔，例如: 1,2,3）'),
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('col-up-index', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const parsed = input.ids
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+                .map((s) => Number(s));
+            if (parsed.length === 0 || parsed.some((n) => Number.isNaN(n))) {
+                throw new CliValidationError('ids 必须是合法的逗号分隔数字', '请提供 --ids 例如: --ids 1,2,3');
+            }
+            const { api } = createYApiServices();
+            await api.upColIndex({ project_id: input.projectId, ids: parsed });
+            return jsonResult({
+                action: 'col-up-index',
+                projectId: input.projectId,
+                ids: parsed,
+            });
         });
     }, '测试集合：调整集合排序', {
         costHint: 'medium',
@@ -653,22 +723,26 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 更新集合 ====================
     registry.tool('col-update', {
-        colId: z.coerce.number().describe('集合 ID，必填。'),
+        colId: z.number().int().positive().describe('集合 ID，必填。'),
         name: z.string().optional().describe('新名称，可选。name 与 desc 至少需要传一个。'),
         desc: z.string().optional().describe('新描述，可选。name 与 desc 至少需要传一个。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (input.name === undefined && input.desc === undefined) {
-            throw new CliValidationError('至少需要提供 name 或 desc 中的一个');
-        }
-        const { api } = createYApiServices();
-        await api.updateCollection({
-            id: input.colId,
-            name: input.name,
-            desc: input.desc,
-        });
-        return jsonResult({
-            colId: input.colId,
-            message: `集合 ${input.colId} 已更新`,
+        const payload = input;
+        return runWithPreview('col-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.name === undefined && input.desc === undefined) {
+                throw new CliValidationError('至少需要提供 name 或 desc 中的一个');
+            }
+            const { api } = createYApiServices();
+            await api.updateCollection({
+                col_id: input.colId,
+                name: input.name,
+                desc: input.desc,
+            });
+            return jsonResult({
+                colId: input.colId,
+                message: `集合 ${input.colId} 已更新`,
+            });
         });
     }, '测试集合：更新集合信息', {
         costHint: 'medium',
@@ -676,7 +750,7 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 用例详情 ====================
     registry.tool('case-get', {
-        caseId: z.coerce.number().describe('用例 ID，必填。返回该用例保存的请求方法、URL、脚本等完整信息。'),
+        caseId: z.number().int().positive().describe('用例 ID，必填。返回该用例保存的请求方法、URL、脚本等完整信息。'),
     }, async (input) => {
         if (Number.isNaN(input.caseId)) {
             throw new CliValidationError('无效的用例 ID', '请使用 --case-id <number>');
@@ -693,24 +767,28 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 更新用例 ====================
     registry.tool('case-update', {
-        caseId: z.coerce.number().describe('用例 ID，必填。'),
+        caseId: z.number().int().positive().describe('用例 ID，必填。'),
         caseType: z.string().optional().describe('用例类型，可选，如 col/test。具体取值由服务端字段约束决定。'),
         method: z.string().optional().describe('HTTP 方法，可选。仅更新该用例的 req_method 字段。'),
         url: z.string().optional().describe('请求路径，可选。仅更新该用例的 req_url 字段。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (Number.isNaN(input.caseId)) {
-            throw new CliValidationError('无效的用例 ID', '请使用 --case-id <number>');
-        }
-        const { api } = createYApiServices();
-        await api.updateTestCase({
-            id: input.caseId,
-            case_type: input.caseType,
-            req_method: input.method,
-            req_url: input.url,
-        });
-        return jsonResult({
-            caseId: input.caseId,
-            message: `用例 ${input.caseId} 已更新`,
+        const payload = input;
+        return runWithPreview('case-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (Number.isNaN(input.caseId)) {
+                throw new CliValidationError('无效的用例 ID', '请使用 --case-id <number>');
+            }
+            const { api } = createYApiServices();
+            await api.updateTestCase({
+                id: input.caseId,
+                case_type: input.caseType,
+                req_method: input.method,
+                req_url: input.url,
+            });
+            return jsonResult({
+                caseId: input.caseId,
+                message: `用例 ${input.caseId} 已更新`,
+            });
         });
     }, '测试用例：更新用例信息', {
         costHint: 'medium',
@@ -718,32 +796,36 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 批量添加用例 ====================
     registry.tool('case-add-list', {
-        colId: z.coerce.number().describe('集合 ID，必填。批量添加的所有用例都会进入该集合。'),
+        colId: z.number().int().positive().describe('集合 ID，必填。批量添加的所有用例都会进入该集合。'),
         ...projectIdSchema,
-        caseList: z.string().describe('用例数组 JSON 字符串，必填，例如: [{"req_method":"GET","req_url":"/api/demo"}]。CLI 会先校验它是 JSON 数组，再整体提交给服务端。'),
+        caseList: z.string().trim().min(1).describe('用例数组 JSON 字符串，必填，例如: [{"req_method":"GET","req_url":"/api/demo"}]。CLI 会先校验它是 JSON 数组，再整体提交给服务端。'),
+        ...confirmSchema,
     }, async (input) => {
-        let caseList;
-        try {
-            const parsed = JSON.parse(input.caseList);
-            if (!Array.isArray(parsed)) {
-                throw new Error('caseList 必须是数组');
+        const payload = input;
+        return runWithPreview('case-add-list', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            let caseList;
+            try {
+                const parsed = JSON.parse(input.caseList);
+                if (!Array.isArray(parsed)) {
+                    throw new Error('caseList 必须是数组');
+                }
+                caseList = parsed;
             }
-            caseList = parsed;
-        }
-        catch (err) {
-            throw new CliValidationError(`caseList 解析失败: ${err instanceof Error ? err.message : String(err)}`, '请提供合法的 JSON 数组，例如: --case-list \'[{"req_method":"GET","req_url":"/api/demo"}]\'');
-        }
-        const { api } = createYApiServices();
-        const result = await api.addTestCaseList({
-            col_id: input.colId,
-            project_id: input.projectId,
-            case_list: caseList,
-        });
-        return jsonResult({
-            colId: input.colId,
-            projectId: input.projectId,
-            count: result.data?.count ?? caseList.length,
-            message: `已批量添加 ${caseList.length} 个用例`,
+            catch (err) {
+                throw new CliValidationError(`caseList 解析失败: ${err instanceof Error ? err.message : String(err)}`, '请提供合法的 JSON 数组，例如: --case-list \'[{"req_method":"GET","req_url":"/api/demo"}]\'');
+            }
+            const { api } = createYApiServices();
+            const result = await api.addTestCaseList({
+                col_id: input.colId,
+                project_id: input.projectId,
+                case_list: caseList,
+            });
+            return jsonResult({
+                colId: input.colId,
+                projectId: input.projectId,
+                count: result.data?.count ?? caseList.length,
+                message: `已批量添加 ${caseList.length} 个用例`,
+            });
         });
     }, '测试用例：批量添加用例到集合', {
         costHint: 'medium',
@@ -751,22 +833,26 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 克隆用例列表 ====================
     registry.tool('col-case-clone', {
-        colId: z.coerce.number().describe('目标集合 ID，必填。克隆出的用例会写入这个集合。'),
+        colId: z.number().int().positive().describe('目标集合 ID，必填。克隆出的用例会写入这个集合。'),
         ...projectIdSchema,
-        srcColId: z.coerce.number().describe('源集合 ID，必填。会从这个集合复制现有用例。'),
-    }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.cloneTestCaseList({
-            col_id: input.colId,
-            project_id: input.projectId,
-            src_col_id: input.srcColId,
-        });
-        return jsonResult({
-            srcColId: input.srcColId,
-            colId: input.colId,
-            projectId: input.projectId,
-            count: result.data?.count ?? 0,
-            message: `已从集合 ${input.srcColId} 克隆用例到 ${input.colId}`,
+        srcColId: z.number().int().positive().describe('源集合 ID，必填。会从这个集合复制现有用例。'),
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('col-case-clone', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.cloneTestCaseList({
+                col_id: input.colId,
+                project_id: input.projectId,
+                src_col_id: input.srcColId,
+            });
+            return jsonResult({
+                srcColId: input.srcColId,
+                colId: input.colId,
+                projectId: input.projectId,
+                count: result.data?.count ?? 0,
+                message: `已从集合 ${input.srcColId} 克隆用例到 ${input.colId}`,
+            });
         });
     }, '测试集合：从另一个集合克隆用例列表', {
         costHint: 'medium',
@@ -774,7 +860,7 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 用例环境变量列表 ====================
     registry.tool('case-env-list', {
-        caseId: z.coerce.number().describe('用例 ID，必填。返回该用例关联的环境变量列表。'),
+        caseId: z.number().int().positive().describe('用例 ID，必填。返回该用例关联的环境变量列表。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.getTestCaseEnvList(input.caseId);
@@ -789,33 +875,37 @@ export function registerUtilCommands(registry) {
     // ==================== 导入数据 ====================
     registry.tool('import', {
         ...projectIdSchema,
-        type: z.string().describe('导入类型，必填，如 swagger/json/har/postman。需要与 content 的真实格式一致。'),
-        content: z.string().describe('导入内容，必填，JSON/Swagger 字符串。CLI 不做格式解析，直接交给服务端按 type 处理。'),
+        type: z.string().trim().min(1).describe('导入类型，必填，如 swagger/json/har/postman。需要与 content 的真实格式一致。'),
+        content: z.string().trim().min(1).describe('导入内容，必填，JSON/Swagger 字符串。CLI 不做格式解析，直接交给服务端按 type 处理。'),
         merge: z
             .enum(['normal', 'good', 'merge'])
             .optional()
             .default('normal')
             .describe('同名接口合并策略，可选枚举 normal/good/merge，默认 normal。是否真正覆盖或合并由服务端实现决定。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (input.content.trim().length === 0) {
-            throw new CliValidationError('content 不能为空');
-        }
-        const { api } = createYApiServices();
-        const result = await api.importData({
-            project_id: input.projectId,
-            type: input.type,
-            content: input.content,
-            merge: input.merge,
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '导入数据失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            projectId: input.projectId,
-            type: input.type,
-            merge: input.merge,
-            data: result.data,
-            message: '导入完成',
+        const payload = input;
+        return runWithPreview('import', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.content.trim().length === 0) {
+                throw new CliValidationError('content 不能为空');
+            }
+            const { api } = createYApiServices();
+            const result = await api.importData({
+                project_id: input.projectId,
+                type: input.type,
+                content: input.content,
+                merge: input.merge,
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '导入数据失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                projectId: input.projectId,
+                type: input.type,
+                merge: input.merge,
+                data: result.data,
+                message: '导入完成',
+            });
         });
     }, '导入数据到项目（支持 swagger/json/har/postman 等格式）', {
         costHint: 'medium',
@@ -823,27 +913,31 @@ export function registerUtilCommands(registry) {
     });
     // ==================== 更新用户 ====================
     registry.tool('user-update', {
-        uid: z.coerce.number().describe('用户 UID'),
+        uid: z.number().int().positive().describe('用户 UID'),
         username: z.string().optional().describe('新用户名'),
         email: z.string().email().optional().describe('新邮箱'),
         role: z
             .enum(['admin', 'owner', 'dev', 'guest', 'viewer'])
             .optional()
             .describe('新角色（admin/owner/dev/guest/viewer）'),
+        ...confirmSchema,
     }, async (input) => {
-        if (input.username === undefined && input.email === undefined && input.role === undefined) {
-            throw new CliValidationError('至少需要提供 username、email 或 role 中的一个');
-        }
-        const { api } = createYApiServices();
-        await api.updateUser({
-            id: input.uid,
-            username: input.username,
-            email: input.email,
-            role: input.role,
-        });
-        return jsonResult({
-            uid: input.uid,
-            message: `用户 ${input.uid} 已更新`,
+        const payload = input;
+        return runWithPreview('user-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.username === undefined && input.email === undefined && input.role === undefined) {
+                throw new CliValidationError('至少需要提供 username、email 或 role 中的一个');
+            }
+            const { api } = createYApiServices();
+            await api.updateUser({
+                id: input.uid,
+                username: input.username,
+                email: input.email,
+                role: input.role,
+            });
+            return jsonResult({
+                uid: input.uid,
+                message: `用户 ${input.uid} 已更新`,
+            });
         });
     }, '用户管理：更新用户信息（需要管理员权限）', {
         costHint: 'medium',