@cloudglab/yapi-cli 0.0.7 → 0.0.9

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

@@ -1,14 +1,15 @@
 import { z } from 'zod';
 import { CliConfigError, CliError, CliNetworkError, CliValidationError } from '../../core/errors.js';
-import { jsonResult, optionalTrimmedText, httpMethodEnum, paginationSchema, projectIdSchema, optionalIdFilter, } from '../shared.js';
-import { createYApiServices, formatMethod, truncate } from './utils.js';
-import { loadConfig, YAPI_HOME, YApiAuthService, YApiService } from '../../services/yapi/index.js';
+import { confirmSchema, jsonResult, optionalTrimmedText, httpMethodEnum, paginationSchema, projectIdSchema, optionalIdFilter, runWithPreview, } from '../shared.js';
+import { previewOrAssertWriteAllowed } from '../../core/write-guard.js';
+import { createYApiServices, formatMethod, getAuthService, truncate, buildJsonSchemaFlags, parseJsonArrayParam, inferInterfaceStyle } from './utils.js';
+import { loadConfig } from '../../services/yapi/index.js';
 export function registerInterfaceCommands(registry) {
     // ==================== 搜索接口 ====================
     registry.tool('search', {
-        q: z.string().describe('搜索关键词，必填。YApi 服务端在接口标题和路径上做模糊匹配，区分大小写由服务端决定。空字符串可能返回空结果或报错。'),
+        q: z.string().trim().min(1).describe('搜索关键词，必填。YApi 服务端在接口标题和路径上做模糊匹配，区分大小写由服务端决定。空字符串可能返回空结果或报错。'),
         ...optionalIdFilter,
-        limit: z.coerce.number().optional().default(20).describe('返回接口数量上限，默认 20。YApi 服务端有上限保护，建议不超过 50；与 groupId/projectId 联用时可缩小搜索范围。'),
+        limit: z.number().int().positive().optional().default(20).describe('返回接口数量上限，默认 20。YApi 服务端有上限保护，建议不超过 50；与 groupId/projectId 联用时可缩小搜索范围。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.searchInterfaces({
@@ -61,7 +62,7 @@ export function registerInterfaceCommands(registry) {
     }, '列出项目中的接口', { costHint: 'low', nextBestTools: ['interface-get', 'project-get', 'category-list'] });
     // ==================== 接口详情 ====================
     registry.tool('interface-get', {
-        interfaceId: z.coerce.number().describe('接口 ID，必填。返回接口完整字段，请求/响应体仅返回前 500 字符，长内容可用 interface-snapshot。'),
+        interfaceId: z.number().int().positive().describe('接口 ID，必填。返回接口完整字段，请求/响应体会原样返回。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.getInterfaceDetail(input.interfaceId);
@@ -80,25 +81,26 @@ export function registerInterfaceCommands(registry) {
                 reqQuery: iface.req_query,
                 reqHeaders: iface.req_headers,
                 reqBodyType: iface.req_body_type,
-                reqBody: iface.req_body_other ? truncate(iface.req_body_other, 500) : undefined,
+                reqBody: iface.req_body_other || undefined,
                 resBodyType: iface.res_body_type,
-                resBody: iface.res_body ? truncate(iface.res_body, 500) : undefined,
+                resBody: iface.res_body || undefined,
+                isMockOpen: iface.is_mock_open,
+                mockCustomScript: iface.mock_custom_script,
             },
         });
     }, '查看接口详情', { costHint: 'low', nextBestTools: ['interface-list', 'log', 'request'] });
     // ==================== 原始请求 ====================
     registry.tool('request', {
-        path: z.string().describe('YApi API 路径，必填，例如 /api/project/list。可以传以 / 开头或不带 / 的路径，CLI 内部会统一补齐前导 /。'),
+        path: z.string().trim().min(1).describe('YApi API 路径，必填，例如 /api/project/list。可以传以 / 开头或不带 / 的路径，CLI 内部会统一补齐前导 /。'),
         method: httpMethodEnum.optional().default('GET').describe('HTTP 方法，可选枚举 GET/POST/PUT/DELETE/PATCH，默认 GET。YApi 私有接口通常要求 GET 或 POST，其他方法可能被服务端拒绝。'),
         body: optionalTrimmedText.describe('请求体 JSON 字符串，可选。仅在 method 为 POST/PUT/PATCH 时会真正发送到服务端，其他方法传入会被忽略。需是合法 JSON，空字符串视为未传。'),
-        projectId: z.coerce.number().optional().describe('项目 ID，可选，YApi 内部数字 ID。当 YApi 接口要求 _yapi_token 或需要注入项目专属 Authorization 时使用，不传时仅使用全局登录 token。'),
+        projectId: z.number().int().positive().optional().describe('项目 ID，可选，YApi 内部数字 ID。当 YApi 接口要求 _yapi_token 或需要注入项目专属 Authorization 时使用，不传时仅使用全局登录 token。'),
     }, async (input) => {
         const config = loadConfig();
         if (!config) {
             throw new CliConfigError('请先运行 `yapi config-init` 初始化配置');
         }
-        const auth = new YApiAuthService(YAPI_HOME);
-        const api = new YApiService(config.url, () => auth.getAuthHeaders(), () => auth.getToken() ?? '');
+        const auth = getAuthService();
         const path = input.path.startsWith('/') ? input.path : `/${input.path}`;
         const url = `${config.url.replace(/\/+$/, '')}${path}`;
         const headers = {
@@ -112,17 +114,26 @@ export function registerInterfaceCommands(registry) {
         if (input.body && (input.method === 'POST' || input.method === 'PUT' || input.method === 'PATCH')) {
             parsedBody = input.body;
         }
+        // 加 30s 超时，避免裸 fetch 在服务端无响应时无限挂起
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30000);
         let response;
         try {
             response = await fetch(url, {
                 method: input.method,
                 headers,
                 body: parsedBody,
+                signal: controller.signal,
             });
         }
         catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new CliNetworkError(`请求超时（30s）: ${url}`);
+            }
             throw new CliNetworkError(`请求失败: ${error instanceof Error ? error.message : String(error)}`);
         }
+        clearTimeout(timeoutId);
         const text = await response.text();
         let data;
         try {
@@ -139,36 +150,85 @@ export function registerInterfaceCommands(registry) {
     // ==================== 接口创建 ====================
     registry.tool('interface-create', {
         ...projectIdSchema,
-        catId: z.coerce.number().describe('接口所属分类 ID，必填，可通过 category-list 获取。同分类下接口不可重复 path+method。'),
-        title: z.string().describe('接口标题，必填，YApi 前端展示用，建议带业务前缀，例如 用户登录-手机号密码。'),
-        path: z.string().describe('接口路径，必填，例如 /api/user/list。建议以 / 开头，YApi 在生成 Mock URL 时会拼上项目 basepath。'),
-        method: httpMethodEnum.default('GET').describe('HTTP 方法，必填枚举，默认 GET。可选值 GET/POST/PUT/DELETE/PATCH。'),
-        desc: optionalTrimmedText.describe('接口描述，可选。仅作为展示文案，YApi 后端不做格式校验，建议补充参数/返回值/错误码等关键信息。'),
-        status: z.enum(['done', 'undone']).optional().default('undone').describe('开发状态，可选枚举 done/undone，默认 undone。done 表示接口已联调通过，undone 表示仅完成设计。'),
-        reqBodyType: z.string().optional().describe('请求体类型，可选。常用值 json / form / file / raw 等，具体合法值由 YApi 服务端决定。'),
-        reqBody: optionalTrimmedText.describe('请求体示例，可选。reqBodyType 为 json 时建议传入合法 JSON 字符串，其他类型为示例字符串。'),
-        resBodyType: z.string().optional().describe('响应体类型，可选，常用 json。建议与 reqBodyType 保持一致以便阅读。'),
-        resBody: optionalTrimmedText.describe('响应体示例，可选，JSON 字符串。建议写入一个最小可用的返回示例，便于联调对照。'),
+        catId: z.number().int().positive().describe('接口所属分类 ID，必填，可通过 category-list 获取。CLI 会拉取该分类下已有接口分析风格（路径前缀、method 偏好、请求/响应体字段结构），作为新接口的参考。'),
+        title: z.string().trim().min(1).describe('接口标题，必填，YApi 前端展示用。CLI 会参考该分类下已有接口的命名风格给出建议，建议按「业务模块-接口名」格式。'),
+        path: z.string().trim().min(1).describe('接口路径，必填，例如 /api/user/list。CLI 会参考该分类下已有接口的公共路径前缀，建议保持一致。'),
+        method: httpMethodEnum.default('GET').describe('HTTP 方法，必填枚举，默认 GET。可选值 GET/POST/PUT/DELETE/PATCH。CLI 会按该分类下最常用的 method 设置默认值。'),
+        desc: optionalTrimmedText.describe('接口描述，可选。仅作为展示文案，建议补充参数/返回值/错误码等关键信息。'),
+        status: z.enum(['done', 'undone']).optional().default('undone').describe('开发状态，可选枚举 done/undone，默认 undone。done 表示接口已联调通过。'),
+        tags: z.string().optional().describe('标签，可选，逗号分隔字符串。CLI 会按逗号拆分并 trim 后整体写入，不传或空字符串表示不设置标签。'),
+        reqQuery: z.string().optional().describe('请求查询参数 JSON 数组字符串，可选。例如 \'[{"name":"page","example":"1","desc":"页码","required":"1"}]\'。'),
+        reqHeaders: z.string().optional().describe('请求头 JSON 数组字符串，可选。例如 \'[{"name":"Authorization","value":"Bearer xxx","desc":"认证令牌"}]\'。'),
+        reqParams: z.string().optional().describe('URL 路径参数 JSON 数组字符串，可选。例如 \'[{"name":"id","example":"123","desc":"用户ID"}]\'。'),
+        reqBodyType: z.string().optional().describe('请求体类型，可选。常用值 json / form / file / raw 等。'),
+        reqBodyForm: z.string().optional().describe('请求体表单字段 JSON 数组字符串，可选（reqBodyType=form 时使用）。例如 \'[{"name":"username","type":"string","required":"1","desc":"用户名"}]\'。'),
+        reqBody: optionalTrimmedText.describe('请求体示例，可选。reqBodyType 为 json 时建议传入合法 JSON 字符串。CLI 会参考该分类下已有接口的请求体字段结构。'),
+        resBodyType: z.string().optional().describe('响应体类型，可选，常用 json。建议与 reqBodyType 保持一致。'),
+        resBody: optionalTrimmedText.describe('响应体示例，可选，JSON 字符串。CLI 会参考该分类下已有接口的响应体字段结构。'),
+        markdown: z.string().optional().describe('接口文档 Markdown 字符串，可选。YApi 会将其渲染为富文本说明。'),
+        apiOpened: z.boolean().optional().describe('是否对外开放此接口，可选。对外开放后可通过 Open API 访问。'),
+        ...confirmSchema,
     }, async (input) => {
+        const payload = input;
         const { api } = createYApiServices();
-        const result = await api.createInterface({
-            project_id: input.projectId,
-            catid: input.catId,
-            title: input.title,
-            path: input.path,
-            method: input.method,
-            status: input.status,
-            desc: input.desc,
-            req_body_type: input.reqBodyType,
-            req_body_other: input.reqBody,
-            res_body_type: input.resBodyType,
-            res_body: input.resBody,
-        });
-        return jsonResult({
-            interfaceId: result.data._id,
-            message: `接口「${input.title}」创建成功`,
+        const styleHints = await inferInterfaceStyle(api, input.projectId, input.catId, 10);
+        if (styleHints) {
+            payload._styleHints = {
+                commonPathPrefix: styleHints.commonPathPrefix,
+                commonMethod: styleHints.commonMethod,
+                reqBodyFields: styleHints.reqBodyFields,
+                resBodyFields: styleHints.resBodyFields,
+                catName: styleHints.catName,
+            };
+        }
+        return runWithPreview('interface-create', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const tag = input.tags
+                ? input.tags
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0)
+                : undefined;
+            let reqQuery;
+            let reqHeaders;
+            let reqParams;
+            let reqBodyForm;
+            try {
+                reqQuery = parseJsonArrayParam(input.reqQuery);
+                reqHeaders = parseJsonArrayParam(input.reqHeaders);
+                reqParams = parseJsonArrayParam(input.reqParams);
+                reqBodyForm = parseJsonArrayParam(input.reqBodyForm);
+            }
+            catch (err) {
+                throw new CliValidationError(err instanceof Error ? err.message : String(err));
+            }
+            const result = await api.createInterface({
+                project_id: input.projectId,
+                catid: input.catId,
+                title: input.title,
+                path: input.path,
+                method: input.method,
+                status: input.status,
+                tag,
+                desc: input.desc,
+                req_query: reqQuery,
+                req_headers: reqHeaders,
+                req_params: reqParams,
+                req_body_type: input.reqBodyType,
+                req_body_form: reqBodyForm,
+                req_body_other: input.reqBody,
+                res_body_type: input.resBodyType,
+                res_body: input.resBody,
+                markdown: input.markdown,
+                api_opened: input.apiOpened,
+                ...buildJsonSchemaFlags(input.reqBodyType, input.resBodyType),
+            });
+            return jsonResult({
+                interfaceId: result.data._id,
+                styleHints,
+                message: `接口「${input.title}」创建成功`,
+            });
         });
-    }, '创建新接口', { costHint: 'medium', nextBestTools: ['interface-list', 'interface-get', 'category-list'] });
+    }, '创建新接口（CLI 会自动分析目标分类风格，作为命名和字段参考）', { costHint: 'medium', nextBestTools: ['interface-list', 'interface-get', 'category-list'] });
     // ==================== 分类列表 ====================
     registry.tool('category-list', {
         ...projectIdSchema,
@@ -186,8 +246,8 @@ export function registerInterfaceCommands(registry) {
     }, '列出项目中的分类（目录）', { costHint: 'low', nextBestTools: ['interface-list', 'interface-get'] });
     // ==================== 接口变更日志 ====================
     registry.tool('log', {
-        interfaceId: z.coerce.number().describe('接口 ID，必填，YApi 内部数字 ID。'),
-        projectId: z.coerce.number().describe('项目 ID，必填，YApi 内部数字 ID。YApi 服务端的接口日志接口要求同时传接口和所属项目，缺一会被拒绝。'),
+        interfaceId: z.number().int().positive().describe('接口 ID，必填，YApi 内部数字 ID。'),
+        projectId: z.number().int().positive().describe('项目 ID，必填，YApi 内部数字 ID。YApi 服务端的接口日志接口要求同时传接口和所属项目，缺一会被拒绝。'),
         ...paginationSchema,
     }, async (input) => {
         const { api } = createYApiServices();
@@ -244,65 +304,75 @@ export function registerInterfaceCommands(registry) {
     }, '获取项目的自定义字段配置', { costHint: 'low', nextBestTools: ['project-get', 'interface-list', 'interface-get'] });
     // ==================== 更新接口排序 ====================
     registry.tool('interface-up-index', {
-        id: z.coerce.number().describe('接口 ID，必填。'),
-        index: z.coerce.number().describe('新排序索引，必填整数。在所属分类内的相对排序，YApi 通常按数字升序展示，越小越靠前。'),
+        id: z.number().int().positive().describe('接口 ID，必填。'),
+        index: z.number().int().positive().describe('新排序索引，必填整数。在所属分类内的相对排序，YApi 通常按数字升序展示，越小越靠前。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.upInterfaceIndex({
-            id: input.id,
-            index: input.index,
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '更新接口排序失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            id: input.id,
-            index: input.index,
-            message: `接口 ${input.id} 排序已更新为 ${input.index}`,
+        const payload = input;
+        return runWithPreview('interface-up-index', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.upInterfaceIndex([
+                { id: input.id, index: input.index },
+            ]);
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '更新接口排序失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                id: input.id,
+                index: input.index,
+                message: `接口 ${input.id} 排序已更新为 ${input.index}`,
+            });
         });
     }, '更新接口排序', { costHint: 'medium', nextBestTools: ['interface-list', 'interface-get'] });
     // ==================== 更新分类排序 ====================
     registry.tool('interface-up-cat-index', {
-        catid: z.coerce.number().describe('分类 ID，必填。'),
-        index: z.coerce.number().describe('分类的新排序索引，必填整数。作用于项目内分类列表，YApi 按升序展示，越小越靠前。'),
+        catid: z.number().int().positive().describe('分类 ID，必填。'),
+        index: z.number().int().positive().describe('分类的新排序索引，必填整数。作用于项目内分类列表，YApi 按升序展示，越小越靠前。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.upCatIndex({
-            catid: input.catid,
-            index: input.index,
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '更新分类排序失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            catid: input.catid,
-            index: input.index,
-            message: `分类 ${input.catid} 排序已更新为 ${input.index}`,
+        const payload = input;
+        return runWithPreview('interface-up-cat-index', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.upCatIndex([
+                { id: input.catid, index: input.index },
+            ]);
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '更新分类排序失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                catid: input.catid,
+                index: input.index,
+                message: `分类 ${input.catid} 排序已更新为 ${input.index}`,
+            });
         });
     }, '更新分类排序', { costHint: 'medium', nextBestTools: ['interface-list', 'category-list'] });
     // ==================== 导入接口 ====================
     registry.tool('interface-upload', {
         ...projectIdSchema,
-        content: z.string().describe('导入内容，必填，JSON/Swagger 字符串。可以是 raw 字符串也可以是 URL 服务端拉取，内容过长时建议走文件后再粘贴。CLI 内部不做格式校验，YApi 服务端按 type 解析。'),
+        content: z.string().trim().min(1).describe('导入内容，必填，JSON/Swagger 字符串。可以是 raw 字符串也可以是 URL 服务端拉取，内容过长时建议走文件后再粘贴。CLI 内部不做格式校验，YApi 服务端按 type 解析。'),
         type: z.string().optional().default('swagger').describe('导入类型，可选，默认 swagger。常用值 swagger / json / har / postman，YApi 服务端按值路由到对应解析器。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (!input.content.trim()) {
-            throw new CliError('导入内容不能为空', 9, 'VALIDATION_ERROR');
-        }
-        const { api } = createYApiServices();
-        const result = await api.interUpload({
-            project_id: input.projectId,
-            content: input.content,
-            type: input.type ?? 'swagger',
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '导入接口失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            projectId: input.projectId,
-            type: input.type ?? 'swagger',
-            data: result.data,
-            message: '接口导入完成',
+        const payload = input;
+        return runWithPreview('interface-upload', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (!input.content.trim()) {
+                throw new CliError('导入内容不能为空', 9, 'VALIDATION_ERROR');
+            }
+            const { api } = createYApiServices();
+            const result = await api.interUpload({
+                project_id: input.projectId,
+                content: input.content,
+                type: input.type ?? 'swagger',
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '导入接口失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                projectId: input.projectId,
+                type: input.type ?? 'swagger',
+                data: result.data,
+                message: '接口导入完成',
+            });
         });
     }, '导入接口（支持 swagger/json 等格式）', { costHint: 'medium', nextBestTools: ['interface-list', 'project-get'] });
     // ==================== 下载浏览器扩展 CRX ====================
@@ -317,47 +387,55 @@ export function registerInterfaceCommands(registry) {
     }, '接口工具：下载浏览器扩展 CRX 安装包', { costHint: 'low', nextBestTools: ['install', 'interface-get'] });
     // ==================== 接口 Mock 开关 ====================
     registry.tool('interface-mock-toggle', {
-        interfaceId: z.coerce.number().describe('接口 ID，必填。'),
+        interfaceId: z.number().int().positive().describe('接口 ID，必填。'),
         open: z
             .union([z.literal('true'), z.literal('false')])
             .default('true')
             .describe('是否开启该接口的 Mock，可选枚举 true/false，默认 true。受项目级 is_mock_open 父开关影响，父开关关闭时本开关即使开启也不生效。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.updateInterface({
-            id: input.interfaceId,
-            is_mock_open: input.open === 'true',
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '切换 Mock 开关失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            interfaceId: input.interfaceId,
-            is_mock_open: input.open === 'true',
-            message: `接口 ${input.interfaceId} Mock 已${input.open === 'true' ? '开启' : '关闭'}`,
+        const payload = input;
+        return runWithPreview('interface-mock-toggle', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.updateInterface({
+                id: input.interfaceId,
+                is_mock_open: input.open === 'true',
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '切换 Mock 开关失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                interfaceId: input.interfaceId,
+                is_mock_open: input.open === 'true',
+                message: `接口 ${input.interfaceId} Mock 已${input.open === 'true' ? '开启' : '关闭'}`,
+            });
         });
     }, '切换接口 Mock 开关', { costHint: 'medium', nextBestTools: ['interface-mock-script', 'interface-get'] });
     // ==================== 接口 Mock 脚本 ====================
     registry.tool('interface-mock-script', {
-        interfaceId: z.coerce.number().describe('接口 ID，必填。'),
-        script: z.string().describe('Mock 脚本内容，必填，JavaScript 字符串。由 YApi 服务端在 vm 沙箱内执行，作用于该接口的所有 mock 请求。空字符串相当于清空脚本。'),
+        interfaceId: z.number().int().positive().describe('接口 ID，必填。'),
+        script: z.string().describe('Mock 脚本内容，必填，JavaScript 字符串。由 YApi 服务端在 vm 沙箱内执行，作用于该接口的所有 mock 请求。传空字符串可清空脚本。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.updateInterface({
-            id: input.interfaceId,
-            mock_custom_script: input.script,
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '更新 Mock 脚本失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            interfaceId: input.interfaceId,
-            message: `接口 ${input.interfaceId} Mock 脚本已更新`,
+        const payload = input;
+        return runWithPreview('interface-mock-script', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.updateInterface({
+                id: input.interfaceId,
+                mock_custom_script: input.script,
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '更新 Mock 脚本失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                interfaceId: input.interfaceId,
+                message: `接口 ${input.interfaceId} Mock 脚本已更新`,
+            });
         });
     }, '设置接口自定义 Mock 脚本', { costHint: 'medium', nextBestTools: ['interface-mock-toggle', 'interface-get'] });
     // ==================== 分类详情 ====================
     registry.tool('category-get', {
-        catId: z.coerce.number().describe('分类 ID，必填。返回该分类的 id/name/desc/projectId 与接口数量。'),
+        catId: z.number().int().positive().describe('分类 ID，必填。返回该分类的 id/name/desc/projectId 与接口数量。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.getCategory(input.catId);
@@ -374,76 +452,90 @@ export function registerInterfaceCommands(registry) {
     // ==================== 创建分类 ====================
     registry.tool('category-create', {
         ...projectIdSchema,
-        name: z.string().describe('分类名称'),
+        name: z.string().trim().min(1).describe('分类名称'),
         desc: z.string().optional().describe('分类描述'),
+        ...confirmSchema,
     }, async (input) => {
-        if (!input.name.trim()) {
-            throw new CliValidationError('分类名称不能为空');
-        }
-        const { api } = createYApiServices();
-        const result = await api.addCategory({
-            name: input.name.trim(),
-            project_id: input.projectId,
-            desc: input.desc,
-        });
-        if (result.errcode !== 0) {
-            throw new CliError(result.errmsg ?? '创建分类失败', 14, 'API_ERROR');
-        }
-        return jsonResult({
-            catId: result.data._id,
-            name: input.name,
-            message: `分类「${input.name}」创建成功`,
+        const payload = input;
+        return runWithPreview('category-create', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (!input.name.trim()) {
+                throw new CliValidationError('分类名称不能为空');
+            }
+            const { api } = createYApiServices();
+            const result = await api.addCategory({
+                name: input.name.trim(),
+                project_id: input.projectId,
+                desc: input.desc,
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '创建分类失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                catId: result.data._id,
+                name: input.name,
+                message: `分类「${input.name}」创建成功`,
+            });
         });
     }, '创建接口分类（目录）', { costHint: 'medium', nextBestTools: ['category-list', 'interface-create'] });
     // ==================== 更新分类 ====================
     registry.tool('category-update', {
-        catId: z.coerce.number().describe('分类 ID，必填。'),
-        name: z.string().optional().describe('新名称，可选。name/desc/status 至少传一个，否则 CLI 会拒绝请求。'),
+        catId: z.number().int().positive().describe('分类 ID，必填。'),
+        name: z.string().optional().describe('新名称，可选。name 和 desc 至少传一个，否则 CLI 会拒绝请求。'),
         desc: z.string().optional().describe('新描述，可选。'),
-        status: z.enum(['open', 'closed']).optional().describe('状态，可选枚举。open 表示开放编辑，closed 表示只读。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (input.name === undefined && input.desc === undefined && input.status === undefined) {
-            throw new CliValidationError('至少需要提供 name、desc 或 status 中的一个');
-        }
-        const { api } = createYApiServices();
-        await api.updateCategory({
-            catid: input.catId,
-            name: input.name,
-            desc: input.desc,
-            status: input.status,
-        });
-        return jsonResult({
-            catId: input.catId,
-            message: `分类 ${input.catId} 已更新`,
+        const payload = input;
+        return runWithPreview('category-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (input.name === undefined && input.desc === undefined) {
+                throw new CliValidationError('至少需要提供 name 或 desc 中的一个');
+            }
+            const { api } = createYApiServices();
+            await api.updateCategory({
+                catid: input.catId,
+                name: input.name,
+                desc: input.desc,
+            });
+            return jsonResult({
+                catId: input.catId,
+                message: `分类 ${input.catId} 已更新`,
+            });
         });
     }, '更新分类信息', { costHint: 'medium', nextBestTools: ['category-get', 'category-list'] });
     // ==================== 删除分类 ====================
     registry.tool('category-delete', {
-        catId: z.coerce.number().describe('分类 ID，必填。删除会同时清理该分类下所有接口，YApi 服务端不会二次确认，建议先用 interface-list-by-cat 查看影响。'),
+        catId: z.number().int().positive().describe('分类 ID，必填。删除会同时清理该分类下所有接口，YApi 服务端不会二次确认，建议先用 interface-list-by-cat 查看影响。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        await api.deleteCategory(input.catId);
-        return jsonResult({
-            action: 'delete',
-            catId: input.catId,
-            deleted: true,
+        const payload = input;
+        return runWithPreview('category-delete', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            await api.deleteCategory(input.catId);
+            return jsonResult({
+                action: 'delete',
+                catId: input.catId,
+                deleted: true,
+            });
         });
     }, '删除分类（不可恢复）', { costHint: 'medium', nextBestTools: ['category-list', 'category-get'] });
     // ==================== 删除接口 ====================
     registry.tool('interface-delete', {
-        interfaceId: z.coerce.number().describe('接口 ID，必填。删除不可恢复，YApi 同时会清理关联的测试集合用例。'),
+        interfaceId: z.number().int().positive().describe('接口 ID，必填。删除不可恢复，YApi 同时会清理关联的测试集合用例。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        await api.deleteInterface(input.interfaceId);
-        return jsonResult({
-            action: 'delete',
-            interfaceId: input.interfaceId,
-            deleted: true,
+        const payload = input;
+        return runWithPreview('interface-delete', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            await api.deleteInterface(input.interfaceId);
+            return jsonResult({
+                action: 'delete',
+                interfaceId: input.interfaceId,
+                deleted: true,
+            });
         });
     }, '删除接口（不可恢复）', { costHint: 'medium', nextBestTools: ['interface-list', 'interface-get'] });
     // ==================== 按分类列出接口 ====================
     registry.tool('interface-list-by-cat', {
-        catId: z.coerce.number().describe('分类 ID，必填。返回该分类下的接口列表（不含分页）。'),
+        catId: z.number().int().positive().describe('分类 ID，必填。返回该分类下的接口列表（不含分页）。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.listInterfacesByCategory(input.catId);
@@ -460,58 +552,196 @@ export function registerInterfaceCommands(registry) {
             })),
         });
     }, '按分类 ID 列出接口', { costHint: 'low', nextBestTools: ['category-get', 'interface-list'] });
+    // ==================== 更新接口（部分更新） ====================
+    registry.tool('interface-update', {
+        interfaceId: z.number().int().positive().describe('接口 ID，必填。目标接口必须已存在，可用 interface-get 先确认。本命令走 /interface/up 部分更新语义，未传字段保持原值，不会覆盖。'),
+        title: z.string().optional().describe('接口标题，可选。'),
+        path: z.string().optional().describe('接口路径，可选，例如 /api/user/list。建议以 / 开头。'),
+        method: httpMethodEnum.optional().describe('HTTP 方法，可选枚举 GET/POST/PUT/DELETE/PATCH。不传则保持原值。'),
+        catid: z.number().int().positive().optional().describe('分类 ID，可选。移动接口到其它分类时使用。'),
+        status: z.enum(['done', 'undone']).optional().describe('开发状态，可选枚举 done/undone。'),
+        tags: z.string().optional().describe('标签，可选，逗号分隔字符串。CLI 按逗号拆分并 trim 后整体写入；传空串会清空标签。'),
+        desc: optionalTrimmedText.describe('接口描述，可选。'),
+        reqQuery: z.string().optional().describe('请求查询参数 JSON 数组字符串，可选。会整体覆盖现有 req_query（不是追加）。'),
+        reqHeaders: z.string().optional().describe('请求头 JSON 数组字符串，可选。会整体覆盖现有 req_headers。'),
+        reqParams: z.string().optional().describe('URL 路径参数 JSON 数组字符串，可选。会整体覆盖现有 req_params。'),
+        reqBodyType: z.string().optional().describe('请求体类型，可选，常用 json / form / file / raw。'),
+        reqBodyForm: z.string().optional().describe('请求体表单字段 JSON 数组字符串，可选（reqBodyType=form 时覆盖）。'),
+        reqBody: optionalTrimmedText.describe('请求体示例，可选。reqBodyType 为 json 时建议传入合法 JSON 字符串。'),
+        resBodyType: z.string().optional().describe('响应体类型，可选，常用 json。'),
+        resBody: optionalTrimmedText.describe('响应体示例，可选 JSON 字符串。YApi 后端会原样存储，建议先 interface-get 取当前 resBody 用 jq fromjson 展开、修改后再整体回传。'),
+        markdown: z.string().optional().describe('接口文档 Markdown 字符串，可选。覆盖现有 markdown 说明。'),
+        apiOpened: z.boolean().optional().describe('是否对外开放此接口，可选。'),
+        customFieldValue: z.string().optional().describe('自定义字段值，可选。仅项目启用了自定义字段时有效。'),
+        switchNotice: z.boolean().optional().describe('更新时是否发送变更通知给关注者，可选。需要服务端配置消息通知。'),
+        message: z.string().optional().describe('更新备注信息，可选。会记录在接口变更日志中。'),
+        ...confirmSchema,
+    }, async (input) => {
+        const payload = input;
+        return runWithPreview('interface-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const provided = [
+                input.title, input.path, input.method, input.catid,
+                input.status, input.tags, input.desc,
+                input.reqQuery, input.reqHeaders, input.reqParams,
+                input.reqBodyType, input.reqBody, input.reqBodyForm,
+                input.resBodyType, input.resBody,
+                input.markdown, input.apiOpened, input.customFieldValue,
+                input.switchNotice, input.message,
+            ];
+            if (provided.every((v) => v === undefined || v === '')) {
+                throw new CliValidationError('至少需要提供 title/path/method/catid/status/tags/desc 或请求/响应相关参数中的一个');
+            }
+            const tag = input.tags !== undefined
+                ? input.tags
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0)
+                : undefined;
+            let reqQuery;
+            let reqHeaders;
+            let reqParams;
+            let reqBodyForm;
+            try {
+                reqQuery = parseJsonArrayParam(input.reqQuery);
+                reqHeaders = parseJsonArrayParam(input.reqHeaders);
+                reqParams = parseJsonArrayParam(input.reqParams);
+                reqBodyForm = parseJsonArrayParam(input.reqBodyForm);
+            }
+            catch (err) {
+                throw new CliValidationError(err instanceof Error ? err.message : String(err));
+            }
+            const { api } = createYApiServices();
+            const result = await api.updateInterface({
+                id: input.interfaceId,
+                title: input.title,
+                path: input.path,
+                method: input.method,
+                catid: input.catid,
+                status: input.status,
+                tag,
+                desc: input.desc,
+                req_query: reqQuery,
+                req_headers: reqHeaders,
+                req_params: reqParams,
+                req_body_type: input.reqBodyType,
+                req_body_form: reqBodyForm,
+                req_body_other: input.reqBody,
+                res_body_type: input.resBodyType,
+                res_body: input.resBody,
+                markdown: input.markdown,
+                api_opened: input.apiOpened,
+                custom_field_value: input.customFieldValue,
+                switch_notice: input.switchNotice,
+                message: input.message,
+                ...buildJsonSchemaFlags(input.reqBodyType, input.resBodyType, !!input.reqBody),
+            });
+            if (result.errcode !== 0) {
+                throw new CliError(result.errmsg ?? '更新接口失败', 14, 'API_ERROR');
+            }
+            return jsonResult({
+                interfaceId: input.interfaceId,
+                action: 'update',
+                message: `接口 ${input.interfaceId} 已更新`,
+            });
+        });
+    }, '更新接口（部分更新，未传字段保持原值）', { costHint: 'medium', nextBestTools: ['interface-get', 'interface-list', 'interface-save'] });
     // ==================== 保存接口（upsert） ====================
     registry.tool('interface-save', {
         ...projectIdSchema,
-        interfaceId: z.coerce.number().optional().describe('接口 ID，可选。提供则走更新分支，不提供则走创建分支。CLI 不校验 ID 是否已存在，服务端按 ID 命中后覆盖。'),
-        catId: z.coerce.number().describe('接口所属分类 ID，必填。'),
-        title: z.string().describe('接口标题，必填。'),
-        path: z.string().describe('接口路径，必填，例如 /api/user/list。建议以 / 开头。'),
+        interfaceId: z.number().int().positive().optional().describe('接口 ID，可选。提供则走更新分支，不提供则走创建分支。'),
+        catId: z.number().int().positive().describe('接口所属分类 ID，必填。'),
+        title: z.string().trim().min(1).describe('接口标题，必填。'),
+        path: z.string().trim().min(1).describe('接口路径，必填，例如 /api/user/list。建议以 / 开头。'),
         method: httpMethodEnum.default('GET').describe('HTTP 方法，必填枚举，默认 GET。'),
         status: z.enum(['done', 'undone']).optional().default('undone').describe('开发状态，可选枚举，默认 undone。'),
         tags: z.string().optional().describe('标签，可选，逗号分隔字符串。CLI 会按逗号拆分并 trim 后整体写入。'),
         desc: optionalTrimmedText.describe('接口描述，可选。'),
+        reqQuery: z.string().optional().describe('请求查询参数 JSON 数组字符串，可选。例如 \'[{"name":"page","example":"1","required":"1"}]\'。'),
+        reqHeaders: z.string().optional().describe('请求头 JSON 数组字符串，可选。'),
+        reqParams: z.string().optional().describe('URL 路径参数 JSON 数组字符串，可选。'),
         reqBodyType: z.string().optional().describe('请求体类型，可选，常用 json / form。'),
+        reqBodyForm: z.string().optional().describe('请求体表单字段 JSON 数组字符串，可选。'),
         reqBody: optionalTrimmedText.describe('请求体示例，可选，reqBodyType 为 json 时建议传入合法 JSON。'),
         resBodyType: z.string().optional().describe('响应体类型，可选，常用 json。'),
         resBody: optionalTrimmedText.describe('响应体示例，可选 JSON 字符串。'),
+        markdown: z.string().optional().describe('接口文档 Markdown 字符串，可选。'),
+        apiOpened: z.boolean().optional().describe('是否对外开放此接口，可选。'),
+        customFieldValue: z.string().optional().describe('自定义字段值，可选。'),
+        ...confirmSchema,
     }, async (input) => {
-        const tag = input.tags
-            ? input.tags
-                .split(',')
-                .map((t) => t.trim())
-                .filter((t) => t.length > 0)
-            : undefined;
+        const payload = input;
         const { api } = createYApiServices();
-        const result = await api.saveInterface({
-            id: input.interfaceId,
-            project_id: input.projectId,
-            catid: input.catId,
-            title: input.title,
-            path: input.path,
-            method: input.method,
-            status: input.status,
-            tag,
-            desc: input.desc,
-            req_body_type: input.reqBodyType,
-            req_body_other: input.reqBody,
-            res_body_type: input.resBodyType,
-            res_body: input.resBody,
-        });
-        return jsonResult({
-            interfaceId: result.data?._id ?? input.interfaceId,
-            action: input.interfaceId ? 'update' : 'create',
-            message: input.interfaceId
-                ? `接口 ${input.interfaceId} 已保存`
-                : `接口「${input.title}」创建成功`,
+        const styleHints = !input.interfaceId
+            ? await inferInterfaceStyle(api, input.projectId, input.catId, 5)
+            : null;
+        if (styleHints) {
+            payload._styleHints = {
+                commonPathPrefix: styleHints.commonPathPrefix,
+                commonMethod: styleHints.commonMethod,
+                reqBodyFields: styleHints.reqBodyFields,
+                resBodyFields: styleHints.resBodyFields,
+                catName: styleHints.catName,
+            };
+        }
+        return runWithPreview('interface-save', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const tag = input.tags
+                ? input.tags
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0)
+                : undefined;
+            let reqQuery;
+            let reqHeaders;
+            let reqParams;
+            let reqBodyForm;
+            try {
+                reqQuery = parseJsonArrayParam(input.reqQuery);
+                reqHeaders = parseJsonArrayParam(input.reqHeaders);
+                reqParams = parseJsonArrayParam(input.reqParams);
+                reqBodyForm = parseJsonArrayParam(input.reqBodyForm);
+            }
+            catch (err) {
+                throw new CliValidationError(err instanceof Error ? err.message : String(err));
+            }
+            const result = await api.saveInterface({
+                id: input.interfaceId,
+                project_id: input.projectId,
+                catid: input.catId,
+                title: input.title,
+                path: input.path,
+                method: input.method,
+                status: input.status,
+                tag,
+                desc: input.desc,
+                req_query: reqQuery,
+                req_headers: reqHeaders,
+                req_params: reqParams,
+                req_body_type: input.reqBodyType,
+                req_body_form: reqBodyForm,
+                req_body_other: input.reqBody,
+                res_body_type: input.resBodyType,
+                res_body: input.resBody,
+                markdown: input.markdown,
+                api_opened: input.apiOpened,
+                custom_field_value: input.customFieldValue,
+                ...buildJsonSchemaFlags(input.reqBodyType, input.resBodyType),
+            });
+            return jsonResult({
+                interfaceId: result.data?._id ?? input.interfaceId,
+                action: input.interfaceId ? 'update' : 'create',
+                styleHints,
+                message: input.interfaceId
+                    ? `接口 ${input.interfaceId} 已保存`
+                    : `接口「${input.title}」创建成功`,
+            });
         });
-    }, '保存接口（存在则更新，不存在则创建）', { costHint: 'medium', nextBestTools: ['interface-get', 'interface-list'] });
+    }, '保存接口（存在则更新，不存在则创建；新建时自动分析目标分类风格）', { costHint: 'medium', nextBestTools: ['interface-get', 'interface-list'] });
     // ==================== 公开项目接口列表 ====================
     registry.tool('interface-list-public', {
         ...projectIdSchema,
         keyword: z.string().optional().describe('搜索关键词，可选。在公开项目的接口标题/路径上做模糊匹配，大小写敏感由服务端决定。'),
-        page: z.coerce.number().optional().default(1).describe('页码，可选，从 1 开始，默认 1。'),
-        limit: z.coerce.number().optional().default(20).describe('每页条数，可选，默认 20。建议不超过 50。'),
+        page: z.number().int().positive().optional().default(1).describe('页码，可选，从 1 开始，默认 1。'),
+        limit: z.number().int().positive().optional().default(20).describe('每页条数，可选，默认 20。建议不超过 50。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.listPublicInterfaces({
@@ -534,20 +764,24 @@ export function registerInterfaceCommands(registry) {
     }, '列出公开项目的接口（无需登录）', { costHint: 'low', nextBestTools: ['interface-list', 'interface-get'] });
     // ==================== schema 转 JSON ====================
     registry.tool('schema-to-json', {
-        schema: z.string().describe('JSON Schema 字符串，必填。由 YApi 服务端转换为 JSON 示例，CLI 不做本地解析，空字符串会被 CLI 拒绝。'),
+        schema: z.string().trim().min(1).describe('JSON Schema 字符串，必填。由 YApi 服务端转换为 JSON 示例，CLI 不做本地解析，空字符串会被 CLI 拒绝。'),
+        required: z.boolean().optional().describe('是否生成必填字段的示例值，可选。默认按服务端逻辑（通常默认生成）。对应后端 schema2json 的 required 参数。'),
     }, async (input) => {
         if (input.schema.trim().length === 0) {
             throw new CliValidationError('schema 不能为空');
         }
         const { api } = createYApiServices();
-        const result = await api.schemaToJson(input.schema);
+        const result = await api.schemaToJson({
+            schema: input.schema,
+            required: input.required,
+        });
         return jsonResult({
             schema: result.data,
         });
     }, '将 JSON Schema 转换为 JSON 示例', { costHint: 'low', nextBestTools: ['interface-create', 'interface-save'] });
     // ==================== 接口快照（一次调用聚合接口详情 + 最近变更） ====================
     registry.tool('interface-snapshot', {
-        interfaceId: z.coerce.number().describe('接口 ID，必填。返回接口摘要信息、请求/响应摘要与最近变更日志，请求/响应体若为 json 会截断到 300 字符，其他类型仅返回长度信息。'),
+        interfaceId: z.number().int().positive().describe('接口 ID，必填。返回接口摘要信息、请求/响应摘要与最近变更日志，请求/响应体若为 json 会截断到 300 字符，其他类型仅返回长度信息。'),
         logLimit: z.coerce
             .number()
             .int()