Skip to content

[break]unify input parameter suffix from params to options #579

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qiuguohua wants to merge 5 commits into
base: main
Choose a base branch
from
Open

[break]unify input parameter suffix from params to options #579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bbf12d0
add prefab test
qiuguohua May 15, 2026
00e2f6b
unify input parameter suffix from params to options
qiuguohua May 19, 2026
8a9e240
revert cocos.config.json
qiuguohua May 25, 2026
c2779b0
update dts-snapshot.test.ts.snap
qiuguohua May 25, 2026
8cd3e8e
update interface parameters
qiuguohua May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions e2e/mcp/api/component.e2e.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ describe('MCP Component API', () => {
it('should add component successfully', async () => {
// 添加Label组件
const addResult = await mcpClient.callTool('scene-add-component', {
addComponentInfo: {
options: {
nodePath: testNodePath,
component: 'cc.Label',
},
Expand All @@ -95,7 +95,7 @@ describe('MCP Component API', () => {
it('should query component successfully', async () => {
// 先添加组件
const addResult = await mcpClient.callTool('scene-add-component', {
addComponentInfo: {
options: {
nodePath: testNodePath,
component: 'cc.Label',
},
Expand All @@ -108,7 +108,7 @@ describe('MCP Component API', () => {

// 查询组件
const queryResult = await mcpClient.callTool('scene-query-component', {
component: { path: componentPath }
options: { path: componentPath }
});
expect(queryResult.code).toBe(200);
expect(queryResult.data).toBeDefined();
Expand All @@ -122,7 +122,7 @@ describe('MCP Component API', () => {
it('should set component property successfully', async () => {
// 先添加组件
const addResult = await mcpClient.callTool('scene-add-component', {
addComponentInfo: {
options: {
nodePath: testNodePath,
component: 'cc.Label',
},
Expand All @@ -135,7 +135,7 @@ describe('MCP Component API', () => {

// 查询组件初始属性
const queryResult = await mcpClient.callTool('scene-query-component', {
component: { path: componentPath }
options: { path: componentPath }
});
expect(queryResult.code).toBe(200);
expect(queryResult.data).toBeDefined();
Expand All @@ -144,7 +144,7 @@ describe('MCP Component API', () => {

// 设置组件属性
const setResult = await mcpClient.callTool('scene-set-component-property', {
setPropertyOptions: {
options: {
componentPath: componentPath,
properties: {
string: 'Hello World'
Expand All @@ -155,7 +155,7 @@ describe('MCP Component API', () => {

// 验证属性已更改
const queryAfterSet = await mcpClient.callTool('scene-query-component', {
component: { path: componentPath }
options: { path: componentPath }
});
expect(queryAfterSet.code).toBe(200);
expect(queryAfterSet.data).toBeDefined();
Expand All @@ -166,7 +166,7 @@ describe('MCP Component API', () => {
it('should delete component successfully', async () => {
// 先添加组件
const addResult = await mcpClient.callTool('scene-add-component', {
addComponentInfo: {
options: {
nodePath: testNodePath,
component: 'cc.Label',
},
Expand All @@ -178,13 +178,13 @@ describe('MCP Component API', () => {

// 删除组件
const deleteResult = await mcpClient.callTool('scene-delete-component', {
component: { path: componentPath }
options: { path: componentPath }
});
expect(deleteResult.code).toBe(200);

// 验证组件已删除 - 查询应该返回null或失败
const queryAfterDelete = await mcpClient.callTool('scene-query-component', {
component: { path: componentPath }
options: { path: componentPath }
});
// 组件删除后查询应该失败或返回null
expect(queryAfterDelete.code).not.toBe(200);
Expand All @@ -199,7 +199,7 @@ describe('MCP Component API', () => {
// 添加多个不同类型的组件
for (const componentType of componentTypes) {
const addResult = await mcpClient.callTool('scene-add-component', {
addComponentInfo: {
options: {
nodePath: testNodePath,
component: componentType,
},
Expand All @@ -212,7 +212,7 @@ describe('MCP Component API', () => {

// 验证组件已添加
const queryResult = await mcpClient.callTool('scene-query-component', {
component: { path: addResult.data.path }
options: { path: addResult.data.path }
});
expect(queryResult.code).toBe(200);
expect(queryResult.data).toBeDefined();
Expand All @@ -223,7 +223,7 @@ describe('MCP Component API', () => {
// 清理添加的组件
for (const componentPath of addedComponents) {
await mcpClient.callTool('scene-delete-component', {
component: { path: componentPath }
options: { path: componentPath }
});
}
});
Expand Down
12 changes: 6 additions & 6 deletions src/api/scene/component-schema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@ import { SchemaComponentIdentifier } from '../base/schema-identifier';
import { SchemaCompPrefabInfo } from './prefab-info-schema';

// Create component information // 创建组件信息
export const SchemaAddComponentInfo = z.object({
export const SchemaAddComponentOptions = z.object({
nodePath: z.string().describe('Node path'), // 节点路径
component: z.string().describe('Component name, supports component name, component resource URL and UUID'), // 组件名称，支持组件名称、组件资源的 URL 与 UUID
}).describe('Information for adding a component'); // 添加组件的信息

// Remove component // 移除组件
export const SchemaRemoveComponent = z.object({
export const SchemaRemoveComponentOptions = z.object({
path: z.string().describe('Path of the component, including node path'), // 组件的路径，包含节点路径
}).describe('Information required to remove a component'); // 移除组件需要的信息

// Query component // 查询组件
export const SchemaQueryComponent = z.object({
export const SchemaQueryComponentOptions = z.object({
path: z.string().describe('Path of the component, including node path'), // 组件的路径，包含节点路径
}).describe('Information required to query a component'); // 查询组件需要的信息

Expand Down Expand Up @@ -123,10 +123,10 @@ export const SchemaComponentResult = z.union([SchemaComponent, z.null()]).descri
export const SchemaBooleanResult = z.boolean().describe('Interface return result'); // 接口返回结果

// Type export // 类型导出
export type TAddComponentInfo = z.infer<typeof SchemaAddComponentInfo>;
export type TAddComponentOptions = z.infer<typeof SchemaAddComponentOptions>;
export type TComponentIdentifier = z.infer<typeof SchemaComponentIdentifier>;
export type TRemoveComponentOptions = z.infer<typeof SchemaRemoveComponent>;
export type TQueryComponentOptions = z.infer<typeof SchemaQueryComponent>;
export type TRemoveComponentOptions = z.infer<typeof SchemaRemoveComponentOptions>;
export type TQueryComponentOptions = z.infer<typeof SchemaQueryComponentOptions>;
export type TSetPropertyOptions = z.infer<typeof SchemaSetPropertyOptions>;
export type TComponentResult = z.infer<typeof SchemaComponentResult>;
export type TQueryAllComponentResult = z.infer<typeof SchemaQueryAllComponentResult>;
Expand Down
28 changes: 14 additions & 14 deletions src/api/scene/component.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
import {
SchemaAddComponentInfo,
SchemaAddComponentOptions,
SchemaSetPropertyOptions,
SchemaComponentResult,
SchemaBooleanResult,
SchemaQueryAllComponentResult,
SchemaQueryComponent,
SchemaRemoveComponent,
SchemaQueryComponentOptions,
SchemaRemoveComponentOptions,

TAddComponentInfo,
TAddComponentOptions,
TSetPropertyOptions,
TComponentResult,
TQueryAllComponentResult,
Expand All @@ -18,7 +18,7 @@ import {
import { description, param, result, title, tool } from '../decorator/decorator.js';
import { COMMON_STATUS, CommonResultType } from '../base/schema-base';
import { Scene, IComponentInfo } from '../../core/scene';
import { ISetPropertyOptionsInfo } from '../../core/scene/common/cli/component';
import { ISetComponentPropertyOptions } from '../../core/scene/common/cli/component';

export class ComponentApi {

Expand All @@ -29,9 +29,9 @@ export class ComponentApi {
@title('Add component') // 添加组件
@description('Add component to node, input node name, component type, built-in or custom component. Returns all component details on success. Can query all component names via scene-query-all-component') // 添加组件到节点中，输入节点名，组件类型，内置组件或自定义组件, 成功返回所有的组件详细信息，可以通过 scene-query-all-component 查询到所有组件的名称
@result(SchemaComponentResult)
async addComponent(@param(SchemaAddComponentInfo) addComponentInfo: TAddComponentInfo): Promise<CommonResultType<TComponentResult>> {
async addComponent(@param(SchemaAddComponentOptions) options: TAddComponentOptions): Promise<CommonResultType<TComponentResult>> {
try {
const component = await Scene.Component.add({ nodePath: addComponentInfo.nodePath, component: addComponentInfo.component });
const component = await Scene.Component.add({ nodePath: options.nodePath, component: options.component });
return {
code: COMMON_STATUS.SUCCESS,
data: component
Expand All @@ -51,9 +51,9 @@ export class ComponentApi {
@title('Remove component') // 删除组件
@description('Remove node component, returns true on success, false on failure') // 删除节点组件，移除成功返回 true， 移除失败返回 false
@result(SchemaBooleanResult)
async removeComponent(@param(SchemaRemoveComponent) component: TRemoveComponentOptions): Promise<CommonResultType<boolean>> {
async removeComponent(@param(SchemaRemoveComponentOptions) options: TRemoveComponentOptions): Promise<CommonResultType<boolean>> {
try {
const result = await Scene.Component.remove(component);
const result = await Scene.Component.remove(options);
return {
code: COMMON_STATUS.SUCCESS,
data: result
Expand All @@ -73,11 +73,11 @@ export class ComponentApi {
@title('Query component') // 查询组件
@description('Query component info, returns all properties of the component') // 查询组件信息，返回组件的所有属性
@result(SchemaComponentResult)
async queryComponent(@param(SchemaQueryComponent) component: TQueryComponentOptions): Promise<CommonResultType<TComponentResult | null>> {
async queryComponent(@param(SchemaQueryComponentOptions) options: TQueryComponentOptions): Promise<CommonResultType<TComponentResult | null>> {
try {
const componentInfo = await Scene.Component.query(component);
const componentInfo = await Scene.Component.query(options);
if (!componentInfo) {
throw new Error(`component not found: ${component.path}`);
throw new Error(`component not found: ${options.path}`);
}
return {
code: COMMON_STATUS.SUCCESS,
Expand All @@ -98,9 +98,9 @@ export class ComponentApi {
@title('Set component property') // 设置组件属性
@description('Set component property. Input component path (unique index of component), property name, property value to modify corresponding property info. Property types can be queried via scene-query-component') // 设置组件属性，输入组件path（唯一索引的组件）、属性名称、属性值，修改对应属性的信息，属性的类型可以通过 scene-query-component 查询到
@result(SchemaBooleanResult)
async setProperty(@param(SchemaSetPropertyOptions) setPropertyOptions?: TSetPropertyOptions): Promise<CommonResultType<boolean>> {
async setProperty(@param(SchemaSetPropertyOptions) options?: TSetPropertyOptions): Promise<CommonResultType<boolean>> {
try {
const result = await Scene.Component.setProperty(setPropertyOptions as ISetPropertyOptionsInfo);
const result = await Scene.Component.setProperty(options as ISetComponentPropertyOptions);
return {
code: COMMON_STATUS.SUCCESS,
data: result
Expand Down
20 changes: 10 additions & 10 deletions src/api/scene/node-schema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ export const SchemaNodeSearch = SchemaNodeIdentifier.extend({
}).describe('Query options for nodes, the result is the intersection of the passed information'); // 查询节点的选项参数，查询结果是传入的信息的交集

// 查询节点的参数
export const SchemaNodeQuery = z.object({
export const SchemaNodeQueryOptions = z.object({
path: z.string().describe('Node path, root path is "/"'), // 节点路径
queryChildren: z.boolean().default(false).describe('Whether to query child node information'), // 是否查询子节点信息
queryComponent: z.boolean().default(false).describe('Whether to query component`s detailed information, the child component only returns concise information.'), // 是否查询组件信息,子节点只返回简易的信息
Expand All @@ -55,7 +55,7 @@ export const SchemaNodeQuery = z.object({
export const SchemaNodeQueryResult: z.ZodType<INodeInfo> = SchemaNode;

//节点更新的参数
export const SchemaNodeUpdate = z.object({
export const SchemaNodeUpdateOptions = z.object({
path: z.string().describe('Relative path of the node'), // 节点相对路径
name: z.string().optional().describe('Name of the node to update'), // 更新的节点名称
properties: SchemaNodeProperty.partial().optional().describe('Node properties to update, can update partial properties'), // 要更新的节点属性，可以只更新部分属性
Expand All @@ -72,7 +72,7 @@ export const SchemaNodeDeleteResult = z.object({
});

// 删除节点的参数
export const SchemaNodeDelete = z.object({
export const SchemaNodeDeleteOptions = z.object({
path: z.string().describe('Relative path of the node'), // 节点相对路径
keepWorldTransform: z.boolean().optional().describe('Keep world transform'), // 保持世界变换
}).describe('To configure options for node deletion, the Scene must be open first.'); // 删除节点的选项参数，需先打开场景
Expand All @@ -86,20 +86,20 @@ const SchemaNodeCreateBase = z.object({
canvasRequired: z.boolean().optional().describe('Whether Canvas is required'), // 是否需要 Canvas
}).describe('To configure options for node creation, the Scene must be open first.'); // 创建节点的选项参数, 需先打开场景;

export const SchemaNodeCreateByAsset = SchemaNodeCreateBase.extend({
export const SchemaNodeCreateByAssetOptions = SchemaNodeCreateBase.extend({
dbURL: SchemaUrl.describe('Prefab asset path, if created from a prefab, please pass this parameter, format is custom db path e.g. db://assets/abc.prefab'), // 预制体资源路径，如果是从某个预制体创建，请传入这个参数，格式为自定义的db 路径比如 db://assets/abc.prefab
});

export const SchemaNodeCreateByType = SchemaNodeCreateBase.extend({
export const SchemaNodeCreateByTypeOptions = SchemaNodeCreateBase.extend({
nodeType: z.enum(Object.values(NodeType) as [string, ...string[]]).describe('Node type'), // 节点类型
});

// 类型导出
export type TDeleteNodeOptions = z.infer<typeof SchemaNodeDelete>;
export type TUpdateNodeOptions = z.infer<typeof SchemaNodeUpdate>;
export type TCreateNodeByAssetOptions = z.infer<typeof SchemaNodeCreateByAsset>;
export type TCreateNodeByTypeOptions = z.infer<typeof SchemaNodeCreateByType>;
export type TQueryNodeOptions = z.infer<typeof SchemaNodeQuery>;
export type TDeleteNodeOptions = z.infer<typeof SchemaNodeDeleteOptions>;
export type TUpdateNodeOptions = z.infer<typeof SchemaNodeUpdateOptions>;
export type TCreateNodeByAssetOptions = z.infer<typeof SchemaNodeCreateByAssetOptions>;
export type TCreateNodeByTypeOptions = z.infer<typeof SchemaNodeCreateByTypeOptions>;
export type TQueryNodeOptions = z.infer<typeof SchemaNodeQueryOptions>;
export type TNodeDetail = z.infer<typeof SchemaNodeQueryResult>;
export type TNodeUpdateResult = z.infer<typeof SchemaNodeUpdateResult>;
export type TNodeDeleteResult = z.infer<typeof SchemaNodeDeleteResult>;
Expand Down
Loading
Loading