@cloudglab/yapi-cli 0.0.7 → 0.0.9

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { CliApiError, CliValidationError } from '../../core/errors.js';
-import { jsonResult, paginationSchema, optionalIdFilter, projectIdSchema } from '../shared.js';
+import { confirmSchema, jsonResult, paginationSchema, optionalIdFilter, projectIdSchema, runWithPreview } from '../shared.js';
+import { previewOrAssertWriteAllowed } from '../../core/write-guard.js';
 import { createYApiServices } from './utils.js';
 export function registerProjectCommands(registry) {
     // ==================== 项目列表 ====================
@@ -44,6 +45,8 @@ export function registerProjectCommands(registry) {
                 token: p.token,
                 env: p.env,
                 members: p.members?.length ?? 0,
+                isMockOpen: p.is_mock_open,
+                projectMockScript: p.project_mock_script,
             },
         });
     }, '查看项目详情', { costHint: 'low', nextBestTools: ['interface-list', 'project-token', 'env'] });
@@ -60,13 +63,11 @@ export function registerProjectCommands(registry) {
     }, '获取项目 Token', { costHint: 'low', nextBestTools: ['project-get', 'interface-list'] });
     // ==================== 项目环境列表 ====================
     registry.tool('env', {
-        projectId: z.coerce.number().describe('项目 ID，必填。YApi 服务端分配的内部数字 ID，用于查询该项目下的环境列表。'),
+        projectId: z.number().int().positive().describe('项目 ID，必填。YApi 服务端分配的内部数字 ID，用于查询该项目下的环境列表。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.listProjectEnvs(input.projectId);
-        const envs = result.data
-            ? (Array.isArray(result.data) ? result.data : result.data.env ?? [])
-            : [];
+        const envs = result.data ? (Array.isArray(result.data.env) ? result.data.env : []) : [];
         return jsonResult({
             projectId: input.projectId,
             envs: envs.map((e) => ({
@@ -78,7 +79,7 @@ export function registerProjectCommands(registry) {
     }, '列出项目环境', { costHint: 'low', nextBestTools: ['project-get', 'member', 'interface-list'] });
     // ==================== 成员列表 ====================
     registry.tool('member', {
-        projectId: z.coerce.number().describe('项目 ID，必填。返回该项目的成员 uid、username、role、email 等信息。'),
+        projectId: z.number().int().positive().describe('项目 ID，必填。返回该项目的成员 uid、username、role、email 等信息。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.listProjectMembers(input.projectId);
@@ -97,9 +98,7 @@ export function registerProjectCommands(registry) {
     registry.tool('follow', {}, async () => {
         const { api } = createYApiServices();
         const result = await api.listFollowedProjects();
-        const projects = Array.isArray(result.data)
-            ? result.data
-            : result.data?.list ?? [];
+        const projects = Array.isArray(result.data) ? result.data : [];
         return jsonResult({
             projects: projects.map((p) => ({
                 id: p._id,
@@ -112,13 +111,11 @@ export function registerProjectCommands(registry) {
     }, '列出关注的项目', { costHint: 'low', nextBestTools: ['project-list', 'interface-list'] });
     // ==================== 搜索项目 ====================
     registry.tool('project-search', {
-        query: z.string().describe('搜索关键词，必填。按项目名称做模糊匹配，空字符串会被 YApi 服务端忽略或视为列出所有项目。区分大小写由服务端规则决定。'),
+        query: z.string().trim().min(1).describe('搜索关键词，必填。按项目名称做模糊匹配，空字符串会被 YApi 服务端忽略或视为列出所有项目。区分大小写由服务端规则决定。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.searchProjects(input.query);
-        const projects = Array.isArray(result.data)
-            ? result.data
-            : result.data?.list ?? [];
+        const projects = Array.isArray(result.data) ? result.data : [];
         return jsonResult({
             query: input.query,
             total: projects.length,
@@ -135,13 +132,17 @@ export function registerProjectCommands(registry) {
     // ==================== 重新生成项目 Token ====================
     registry.tool('project-token-update', {
         ...projectIdSchema,
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.updateProjectToken(input.projectId);
-        return jsonResult({
-            projectId: input.projectId,
-            token: result.data.token,
-            message: '项目 Token 已重新生成',
+        const payload = input;
+        return runWithPreview('project-token-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.updateProjectToken(input.projectId);
+            return jsonResult({
+                projectId: input.projectId,
+                token: result.data.token,
+                message: '项目 Token 已重新生成',
+            });
         });
     }, '重新生成项目 Token（旧的将失效）', { costHint: 'medium', nextBestTools: ['project-token', 'project-get'] });
     // ==================== 更新项目环境 ====================
@@ -150,110 +151,160 @@ export function registerProjectCommands(registry) {
         envs: z
             .string()
             .describe('环境数组的 JSON 字符串，必填，格式如 [{"name":"prod","domain":"https://api.example.com"}]。每项必须包含字符串类型的 name 和 domain；该命令会整体覆盖现有环境，不会合并。建议先调用 env 获取当前配置，再追加修改。'),
+        ...confirmSchema,
     }, async (input) => {
-        let envs;
-        try {
-            const parsed = JSON.parse(input.envs);
-            if (!Array.isArray(parsed)) {
-                throw new Error('envs 必须是数组');
-            }
-            envs = parsed.map((e) => {
-                if (typeof e !== 'object' ||
-                    e === null ||
-                    typeof e.name !== 'string' ||
-                    typeof e.domain !== 'string') {
-                    throw new Error('envs 数组项必须包含 name 和 domain 字符串字段');
+        const payload = input;
+        return runWithPreview('project-env-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            let envs;
+            try {
+                const parsed = JSON.parse(input.envs);
+                if (!Array.isArray(parsed)) {
+                    throw new Error('envs 必须是数组');
                 }
-                return { name: e.name, domain: e.domain };
+                envs = parsed.map((e) => {
+                    if (typeof e !== 'object' ||
+                        e === null ||
+                        typeof e.name !== 'string' ||
+                        typeof e.domain !== 'string') {
+                        throw new Error('envs 数组项必须包含 name 和 domain 字符串字段');
+                    }
+                    const record = e;
+                    return { name: record.name, domain: record.domain };
+                });
+            }
+            catch (err) {
+                throw new CliValidationError(`envs 解析失败: ${err instanceof Error ? err.message : String(err)}`, '请提供合法的 JSON 数组，例如: --envs \'[{"name":"prod","domain":"https://api.example.com"}]\'');
+            }
+            const { api } = createYApiServices();
+            await api.updateProjectEnv({
+                id: input.projectId,
+                env: envs,
+            });
+            return jsonResult({
+                projectId: input.projectId,
+                envs,
+                message: '项目环境已更新',
             });
-        }
-        catch (err) {
-            throw new CliValidationError(`envs 解析失败: ${err instanceof Error ? err.message : String(err)}`, '请提供合法的 JSON 数组，例如: --envs \'[{"name":"prod","domain":"https://api.example.com"}]\'');
-        }
-        const { api } = createYApiServices();
-        await api.updateProjectEnv({
-            project_id: input.projectId,
-            env: envs,
-        });
-        return jsonResult({
-            projectId: input.projectId,
-            envs,
-            message: '项目环境已更新',
         });
     }, '更新项目环境配置（覆盖现有环境）', { costHint: 'medium', nextBestTools: ['env', 'project-get'] });
     // ==================== 更新项目标签 ====================
     registry.tool('project-tag-update', {
         ...projectIdSchema,
-        tags: z.string().describe('标签列表，逗号分隔的字符串，必填且至少 1 个有效标签，例如: 订单,支付,用户。CLI 会按逗号拆分并 trim 后整体覆盖原标签，不是追加。空字符串会被 CLI 拒绝。'),
+        tags: z.string().trim().min(1).describe('标签列表，必填。支持两种格式：1) 逗号分隔的名称，例如 "订单,支付,用户"；2) JSON 对象数组字符串，例如 \'[{"name":"订单","desc":"订单相关"}]\'。CLI 会整体覆盖原标签，不是追加。'),
+        ...confirmSchema,
     }, async (input) => {
-        const tag = input.tags
-            .split(',')
-            .map((t) => t.trim())
-            .filter((t) => t.length > 0);
-        if (tag.length === 0) {
-            throw new CliValidationError('tags 不能为空', '请提供至少一个标签，例如: --tags 订单,支付');
-        }
-        const { api } = createYApiServices();
-        await api.updateProjectTag({
-            project_id: input.projectId,
-            tag,
-        });
-        return jsonResult({
-            projectId: input.projectId,
-            tags: tag,
-            message: '项目标签已更新',
+        const payload = input;
+        return runWithPreview('project-tag-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            let tag;
+            const raw = input.tags.trim();
+            if (raw.startsWith('[')) {
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (!Array.isArray(parsed)) {
+                        throw new Error('tags 必须是数组');
+                    }
+                    tag = parsed.map((item) => {
+                        if (typeof item === 'string') {
+                            return { name: item.trim() };
+                        }
+                        if (typeof item !== 'object' || item === null || typeof item.name !== 'string') {
+                            throw new Error('标签对象必须包含 name 字符串字段');
+                        }
+                        const record = item;
+                        return {
+                            name: record.name,
+                            desc: record.desc,
+                        };
+                    });
+                }
+                catch (err) {
+                    throw new CliValidationError(`tags JSON 解析失败: ${err instanceof Error ? err.message : String(err)}`, '请提供逗号分隔的名称或 JSON 对象数组');
+                }
+            }
+            else {
+                tag = raw
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0)
+                    .map((name) => ({ name }));
+            }
+            if (tag.length === 0) {
+                throw new CliValidationError('tags 不能为空', '请提供至少一个标签，例如: --tags 订单,支付');
+            }
+            const { api } = createYApiServices();
+            await api.updateProjectTag({
+                id: input.projectId,
+                tag,
+            });
+            return jsonResult({
+                projectId: input.projectId,
+                tags: tag,
+                message: '项目标签已更新',
+            });
         });
     }, '更新项目标签（覆盖现有标签）', { costHint: 'medium', nextBestTools: ['project-get', 'project-list'] });
     // ==================== 删除项目 ====================
     registry.tool('project-delete', {
         ...projectIdSchema,
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        await api.deleteProject(input.projectId);
-        return jsonResult({
-            action: 'delete',
-            projectId: input.projectId,
-            deleted: true,
+        const payload = input;
+        return runWithPreview('project-delete', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            await api.deleteProject(input.projectId);
+            return jsonResult({
+                action: 'delete',
+                projectId: input.projectId,
+                deleted: true,
+            });
         });
     }, '删除项目（不可恢复）', { costHint: 'medium', nextBestTools: ['project-list', 'project-get'] });
     // ==================== 移除项目成员 ====================
     registry.tool('project-member-remove', {
         ...projectIdSchema,
-        uid: z.coerce.number().describe('要移除的成员用户 UID，必填。注意仅解除该成员与项目的关联，不会删除用户本身。'),
+        uid: z.number().int().positive().describe('要移除的成员用户 UID，必填。注意仅解除该成员与项目的关联，不会删除用户本身。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        await api.delProjectMember({
-            project_id: input.projectId,
-            uid: input.uid,
-        });
-        return jsonResult({
-            action: 'remove',
-            projectId: input.projectId,
-            uid: input.uid,
-            removed: true,
+        const payload = input;
+        return runWithPreview('project-member-remove', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            await api.delProjectMember({
+                id: input.projectId,
+                member_uid: input.uid,
+            });
+            return jsonResult({
+                action: 'remove',
+                projectId: input.projectId,
+                uid: input.uid,
+                removed: true,
+            });
         });
     }, '从项目中移除成员', { costHint: 'medium', nextBestTools: ['member', 'project-get'] });
     // ==================== 修改项目成员角色 ====================
     registry.tool('project-member-role', {
         ...projectIdSchema,
-        memberUid: z.coerce.number().describe('要修改角色的成员用户 UID，必填，YApi 内部数字 ID。'),
+        memberUid: z.number().int().positive().describe('要修改角色的成员用户 UID，必填，YApi 内部数字 ID。'),
         role: z
             .enum(['owner', 'dev', 'guest', 'developer', 'viewer'])
             .optional()
             .default('developer')
             .describe('目标角色，可选枚举。默认 developer。YApi 历史插件中 dev 与 developer 同时存在表示相同权限，部分服务端版本只识别其中一个，建议优先用 developer。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        await api.changeProjectMemberRole({
-            project_id: input.projectId,
-            member_uid: input.memberUid,
-            role: input.role,
-        });
-        return jsonResult({
-            action: 'change-role',
-            projectId: input.projectId,
-            uid: input.memberUid,
-            role: input.role,
+        const payload = input;
+        return runWithPreview('project-member-role', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            await api.changeProjectMemberRole({
+                id: input.projectId,
+                member_uid: input.memberUid,
+                role: input.role,
+            });
+            return jsonResult({
+                action: 'change-role',
+                projectId: input.projectId,
+                uid: input.memberUid,
+                role: input.role,
+            });
         });
     }, '修改项目成员角色', { costHint: 'medium', nextBestTools: ['member', 'project-get'] });
     // ==================== 项目 Mock 开关（全局） ====================
@@ -263,77 +314,112 @@ export function registerProjectCommands(registry) {
             .union([z.literal('true'), z.literal('false')])
             .default('true')
             .describe('是否开启项目级全局 Mock，可选枚举 true/false，默认 true。影响该项目的 mock 接口路由是否对外可访问，不影响单接口的 mock_custom_script。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.upSetProject({
-            project_id: input.projectId,
-            is_mock_open: input.open === 'true',
-        });
-        if (result.errcode !== 0) {
-            throw new CliApiError(result.errmsg ?? '切换项目 Mock 开关失败');
-        }
-        return jsonResult({
-            projectId: input.projectId,
-            is_mock_open: input.open === 'true',
-            message: `项目 ${input.projectId} 全局 Mock 已${input.open === 'true' ? '开启' : '关闭'}`,
+        const payload = input;
+        return runWithPreview('project-mock-toggle', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.upSetProject({
+                project_id: input.projectId,
+                is_mock_open: input.open === 'true',
+            });
+            if (result.errcode !== 0) {
+                throw new CliApiError(result.errmsg ?? '切换项目 Mock 开关失败');
+            }
+            return jsonResult({
+                projectId: input.projectId,
+                is_mock_open: input.open === 'true',
+                message: `项目 ${input.projectId} 全局 Mock 已${input.open === 'true' ? '开启' : '关闭'}`,
+            });
         });
     }, '切换项目全局 Mock 开关', { costHint: 'medium', nextBestTools: ['project-mock-script', 'project-get'] });
     // ==================== 项目 Mock 脚本 ====================
     registry.tool('project-mock-script', {
         ...projectIdSchema,
-        script: z.string().describe('项目级 Mock 脚本内容，必填，为 JavaScript 字符串。由 YApi 服务端在 vm 沙箱内执行，对该项目的所有 mock 请求生效。空字符串相当于清空脚本。'),
+        script: z.string().describe('项目级 Mock 脚本内容，必填，为 JavaScript 字符串。由 YApi 服务端在 vm 沙箱内执行，对该项目的所有 mock 请求生效。传空字符串可清空脚本。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.upSetProject({
-            project_id: input.projectId,
-            project_mock_script: input.script,
-        });
-        if (result.errcode !== 0) {
-            throw new CliApiError(result.errmsg ?? '更新项目 Mock 脚本失败');
-        }
-        return jsonResult({
-            projectId: input.projectId,
-            message: `项目 ${input.projectId} Mock 脚本已更新`,
+        const payload = input;
+        return runWithPreview('project-mock-script', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.upSetProject({
+                project_id: input.projectId,
+                project_mock_script: input.script,
+            });
+            if (result.errcode !== 0) {
+                throw new CliApiError(result.errmsg ?? '更新项目 Mock 脚本失败');
+            }
+            return jsonResult({
+                projectId: input.projectId,
+                message: `项目 ${input.projectId} Mock 脚本已更新`,
+            });
         });
     }, '设置项目级 Mock 脚本', { costHint: 'medium', nextBestTools: ['project-mock-toggle', 'project-get'] });
     // ==================== 创建项目 ====================
     registry.tool('project-create', {
-        name: z.string().describe('项目名称，必填。CLI 会做 trim，空字符串会被拒绝。同一分组内不可重名，建议先用 project-check-name 校验。'),
-        groupId: z.coerce.number().describe('所属分组 ID，必填。新建项目必须挂在某个已存在的分组下，可通过 group-list 获取。'),
+        name: z.string().trim().min(1).describe('项目名称，必填。CLI 会做 trim，空字符串会被拒绝。同一分组内不可重名，建议先用 project-check-name 校验。'),
+        groupId: z.number().int().positive().describe('所属分组 ID，必填。新建项目必须挂在某个已存在的分组下，可通过 group-list 获取。'),
         basepath: z.string().optional().describe('项目基础路径，可选，建议以 / 开头，例如 /api。YApi 在拼接 Mock URL 时会把该路径作为前缀，不传时服务端通常默认为 /。'),
         projectType: z.enum(['private', 'public']).optional().default('private').describe('项目类型，可选枚举，默认 private。public 项目会出现在开放接口相关命令中，token 也会公开，谨慎使用。'),
         desc: z.string().optional().describe('项目描述，可选。仅作为展示文案，建议不超过 200 字。'),
         icon: z.string().optional().describe('项目图标代码，可选。具体取值由前端图标库决定，未知值通常会被前端忽略，不会影响接口数据。'),
         color: z.string().optional().describe('项目颜色代码，可选，例如 #RRGGBB 或主题色 key，仅用于前端展示。'),
         tags: z.string().optional().describe('项目标签，可选，逗号分隔字符串，例如 订单,支付。CLI 会按逗号拆分并 trim 后整体写入，不传或空字符串表示不设置标签。'),
+        preScript: z.string().optional().describe('项目级前置脚本，可选。在接口请求前由 YApi 服务端执行（若服务端支持）。'),
+        afterScript: z.string().optional().describe('项目级后置脚本，可选。在接口请求后由 YApi 服务端执行（若服务端支持）。'),
+        env: z.string().optional().describe('项目环境配置 JSON 数组字符串，可选。例如 \'[{"name":"prod","domain":"https://api.example.com"}]\'；若服务端支持，创建时直接写入环境列表。'),
+        ...confirmSchema,
     }, async (input) => {
-        if (!input.name.trim()) {
-            throw new CliValidationError('项目名称不能为空');
-        }
-        const tag = input.tags
-            ? input.tags
-                .split(',')
-                .map((t) => t.trim())
-                .filter((t) => t.length > 0)
-            : undefined;
-        const { api } = createYApiServices();
-        const result = await api.createProject({
-            name: input.name.trim(),
-            group_id: input.groupId,
-            basepath: input.basepath,
-            project_type: input.projectType,
-            desc: input.desc,
-            icon: input.icon,
-            color: input.color,
-            tag,
-        });
-        if (result.errcode !== 0) {
-            throw new CliApiError(result.errmsg ?? '创建项目失败');
-        }
-        return jsonResult({
-            projectId: result.data._id,
-            name: input.name,
-            message: `项目「${input.name}」创建成功`,
+        const payload = input;
+        return runWithPreview('project-create', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            if (!input.name.trim()) {
+                throw new CliValidationError('项目名称不能为空');
+            }
+            const tag = input.tags
+                ? input.tags
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0)
+                : undefined;
+            let envs;
+            if (input.env) {
+                try {
+                    const parsed = JSON.parse(input.env);
+                    if (!Array.isArray(parsed))
+                        throw new Error('env 必须是数组');
+                    envs = parsed.map((e) => {
+                        if (typeof e.name !== 'string' || typeof e.domain !== 'string') {
+                            throw new Error('env 数组项必须包含 name 和 domain 字符串字段');
+                        }
+                        return e;
+                    });
+                }
+                catch (err) {
+                    throw new CliValidationError(`env 解析失败: ${err instanceof Error ? err.message : String(err)}`, '请提供合法的 JSON 数组，例如: --env \'[{"name":"prod","domain":"https://api.example.com"}]\'');
+                }
+            }
+            const { api } = createYApiServices();
+            const result = await api.createProject({
+                name: input.name.trim(),
+                group_id: input.groupId,
+                basepath: input.basepath,
+                project_type: input.projectType,
+                desc: input.desc,
+                icon: input.icon,
+                color: input.color,
+                tag,
+                pre_script: input.preScript,
+                after_script: input.afterScript,
+                env: envs,
+            });
+            if (result.errcode !== 0) {
+                throw new CliApiError(result.errmsg ?? '创建项目失败');
+            }
+            return jsonResult({
+                projectId: result.data._id,
+                name: input.name,
+                message: `项目「${input.name}」创建成功`,
+            });
         });
     }, '创建新项目', { costHint: 'medium', nextBestTools: ['project-get', 'interface-list', 'project-env-update'] });
     // ==================== 更新项目 ====================
@@ -345,48 +431,67 @@ export function registerProjectCommands(registry) {
         icon: z.string().optional().describe('新图标代码，可选。'),
         color: z.string().optional().describe('新颜色代码，可选。'),
         tags: z.string().optional().describe('新标签，可选，逗号分隔字符串。CLI 会按逗号拆分并 trim 后整体覆盖原标签。'),
+        preScript: z.string().optional().describe('项目级前置脚本，可选。传空字符串可清空脚本。'),
+        afterScript: z.string().optional().describe('项目级后置脚本，可选。传空字符串可清空脚本。'),
+        projectMockScript: z.string().optional().describe('项目级全局 Mock 脚本，可选。传空字符串可清空脚本；如需仅开关 Mock 请使用 project-mock-toggle。'),
+        ...confirmSchema,
     }, async (input) => {
-        const tag = input.tags
-            ? input.tags
-                .split(',')
-                .map((t) => t.trim())
-                .filter((t) => t.length > 0)
-            : undefined;
-        const { api } = createYApiServices();
-        await api.updateProject({
-            id: input.projectId,
-            name: input.name,
-            basepath: input.basepath,
-            desc: input.desc,
-            icon: input.icon,
-            color: input.color,
-            tag,
-        });
-        return jsonResult({
-            projectId: input.projectId,
-            message: `项目 ${input.projectId} 已更新`,
+        const payload = input;
+        return runWithPreview('project-update', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const tag = input.tags
+                ? input.tags
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0)
+                : undefined;
+            const { api } = createYApiServices();
+            await api.updateProject({
+                id: input.projectId,
+                name: input.name,
+                basepath: input.basepath,
+                desc: input.desc,
+                icon: input.icon,
+                color: input.color,
+                tag,
+                pre_script: input.preScript,
+                after_script: input.afterScript,
+                project_mock_script: input.projectMockScript,
+            });
+            return jsonResult({
+                projectId: input.projectId,
+                message: `项目 ${input.projectId} 已更新`,
+            });
         });
     }, '更新项目基础信息', { costHint: 'medium', nextBestTools: ['project-get', 'project-list'] });
     // ==================== 复制项目 ====================
     registry.tool('project-copy', {
         ...projectIdSchema,
+        groupId: z.number().int().positive().describe('目标分组 ID，必填。复制后的新项目将挂在该分组下，需要对该分组有编辑权限。'),
         name: z.string().optional().describe('新项目名称，可选。不传时由服务端使用默认命名规则（通常是原名称加后缀）。同分组内仍需保持唯一，建议显式传入。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.copyProject(input.projectId, input.name);
-        if (result.errcode !== 0) {
-            throw new CliApiError(result.errmsg ?? '复制项目失败');
-        }
-        return jsonResult({
-            sourceProjectId: input.projectId,
-            newProjectId: result.data._id,
-            message: `项目 ${input.projectId} 已复制`,
+        const payload = input;
+        return runWithPreview('project-copy', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.copyProject({
+                _id: input.projectId,
+                group_id: input.groupId,
+                name: input.name,
+            });
+            if (result.errcode !== 0) {
+                throw new CliApiError(result.errmsg ?? '复制项目失败');
+            }
+            return jsonResult({
+                sourceProjectId: input.projectId,
+                newProjectId: result.data._id,
+                message: `项目 ${input.projectId} 已复制`,
+            });
         });
     }, '复制项目', { costHint: 'medium', nextBestTools: ['project-get', 'project-list'] });
     // ==================== 检查项目名是否可用 ====================
     registry.tool('project-check-name', {
-        name: z.string().describe('待校验的项目名称，必填。会先做 trim 再传给服务端；同分组内不可重名，建议先于 project-create 调用。'),
-        groupId: z.coerce.number().describe('分组 ID，必填，名称可用性是相对于指定分组的，不同分组下名称可以重复。'),
+        name: z.string().trim().min(1).describe('待校验的项目名称，必填。会先做 trim 再传给服务端；同分组内不可重名，建议先于 project-create 调用。'),
+        groupId: z.number().int().positive().describe('分组 ID，必填，名称可用性是相对于指定分组的，不同分组下名称可以重复。'),
     }, async (input) => {
         const { api } = createYApiServices();
         const result = await api.checkProjectName(input.name, input.groupId);
@@ -399,87 +504,103 @@ export function registerProjectCommands(registry) {
     }, '检查分组下项目名称是否可用', { costHint: 'low', nextBestTools: ['project-create', 'project-list'] });
     // ==================== 获取项目 Swagger URL ====================
     registry.tool('project-swagger-url', {
-        ...projectIdSchema,
+        url: z.string().url().describe('Swagger 数据源的 URL，必填。YApi 服务端会从该 URL 拉取 Swagger JSON 数据并返回，用于导入前的预览或校验。'),
     }, async (input) => {
         const { api } = createYApiServices();
-        const result = await api.getProjectSwaggerUrl(input.projectId);
+        const result = await api.getProjectSwaggerUrl(input.url);
         return jsonResult({
-            projectId: input.projectId,
+            url: input.url,
             data: result.data,
         });
-    }, '获取项目的 Swagger 数据源 URL', { costHint: 'low', nextBestTools: ['project-get', 'interface-list'] });
+    }, '从指定 URL 拉取 Swagger 数据源', { costHint: 'low', nextBestTools: ['project-get', 'interface-list'] });
     // ==================== 添加项目成员 ====================
     registry.tool('project-member-add', {
         ...projectIdSchema,
-        uid: z.coerce.number().describe('要加入的成员用户 UID，必填。需要被加入用户已在 YApi 注册，否则服务端会拒绝。'),
+        uid: z.number().int().positive().describe('要加入的成员用户 UID，必填。需要被加入用户已在 YApi 注册，否则服务端会拒绝。'),
         role: z.string().optional().describe('成员角色，可选。常用值 owner / dev / developer / guest / viewer。具体合法值由服务端决定，传未知值通常会被服务端忽略或拒绝。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.addProjectMember({
-            project_id: input.projectId,
-            uid: input.uid,
-            role: input.role,
-        });
-        if (result.errcode !== 0) {
-            throw new CliApiError(result.errmsg ?? '添加项目成员失败');
-        }
-        return jsonResult({
-            projectId: input.projectId,
-            uid: input.uid,
-            role: input.role,
-            message: `用户 ${input.uid} 已加入项目 ${input.projectId}`,
+        const payload = input;
+        return runWithPreview('project-member-add', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.addProjectMember({
+                id: input.projectId,
+                member_uids: [input.uid],
+                role: input.role,
+            });
+            if (result.errcode !== 0) {
+                throw new CliApiError(result.errmsg ?? '添加项目成员失败');
+            }
+            return jsonResult({
+                projectId: input.projectId,
+                uid: input.uid,
+                role: input.role,
+                message: `用户 ${input.uid} 已加入项目 ${input.projectId}`,
+            });
         });
     }, '添加项目成员', { costHint: 'medium', nextBestTools: ['member', 'project-get'] });
     // ==================== 修改成员邮件通知 ====================
     registry.tool('project-member-email-notice', {
         ...projectIdSchema,
-        uid: z.coerce.number().describe('目标成员的用户 UID，必填。该成员必须是项目成员，否则服务端会返回错误。'),
+        uid: z.number().int().positive().describe('目标成员的用户 UID，必填。该成员必须是项目成员，否则服务端会返回错误。'),
         emailNotice: z
             .union([z.literal('true'), z.literal('false')])
             .default('true')
             .describe('是否开启该成员在项目内的邮件通知，可选枚举 true/false，默认 true。YApi 服务端需要正确配置 SMTP 才有效。'),
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        await api.changeProjectMemberEmailNotice({
-            project_id: input.projectId,
-            uid: input.uid,
-            email_notice: input.emailNotice === 'true',
-        });
-        return jsonResult({
-            projectId: input.projectId,
-            uid: input.uid,
-            emailNotice: input.emailNotice === 'true',
-            message: `成员 ${input.uid} 邮件通知已${input.emailNotice === 'true' ? '开启' : '关闭'}`,
+        const payload = input;
+        return runWithPreview('project-member-email-notice', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            await api.changeProjectMemberEmailNotice({
+                project_id: input.projectId,
+                member_uid: input.uid,
+                notice: input.emailNotice === 'true',
+            });
+            return jsonResult({
+                projectId: input.projectId,
+                uid: input.uid,
+                emailNotice: input.emailNotice === 'true',
+                message: `成员 ${input.uid} 邮件通知已${input.emailNotice === 'true' ? '开启' : '关闭'}`,
+            });
         });
     }, '修改项目成员的邮件通知开关', { costHint: 'medium', nextBestTools: ['member', 'project-get'] });
     // ==================== 关注项目 ====================
     registry.tool('project-follow', {
         ...projectIdSchema,
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.followProject(input.projectId);
-        if (result.errcode !== 0) {
-            throw new CliApiError(result.errmsg ?? '关注项目失败');
-        }
-        return jsonResult({
-            projectId: input.projectId,
-            followed: true,
-            message: `已关注项目 ${input.projectId}`,
+        const payload = input;
+        return runWithPreview('project-follow', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.followProject(input.projectId);
+            if (result.errcode !== 0) {
+                throw new CliApiError(result.errmsg ?? '关注项目失败');
+            }
+            return jsonResult({
+                projectId: input.projectId,
+                followed: true,
+                message: `已关注项目 ${input.projectId}`,
+            });
         });
     }, '关注项目', { costHint: 'medium', nextBestTools: ['project-unfollow', 'follow', 'project-get'] });
     // ==================== 取消关注项目 ====================
     registry.tool('project-unfollow', {
         ...projectIdSchema,
+        ...confirmSchema,
     }, async (input) => {
-        const { api } = createYApiServices();
-        const result = await api.unfollowProject(input.projectId);
-        if (result.errcode !== 0) {
-            throw new CliApiError(result.errmsg ?? '取消关注项目失败');
-        }
-        return jsonResult({
-            projectId: input.projectId,
-            followed: false,
-            message: `已取消关注项目 ${input.projectId}`,
+        const payload = input;
+        return runWithPreview('project-unfollow', payload.confirm, payload, previewOrAssertWriteAllowed, async () => {
+            const { api } = createYApiServices();
+            const result = await api.unfollowProject(input.projectId);
+            if (result.errcode !== 0) {
+                throw new CliApiError(result.errmsg ?? '取消关注项目失败');
+            }
+            return jsonResult({
+                projectId: input.projectId,
+                followed: false,
+                message: `已取消关注项目 ${input.projectId}`,
+            });
         });
     }, '取消关注项目', { costHint: 'medium', nextBestTools: ['project-follow', 'follow', 'project-get'] });
     // ==================== 项目快照（一次调用聚合项目基础信息 + 分类 + 最近接口 + 环境） ====================