插件提交错误 – Plugins

提交到公共目录的插件须满足比安装在工作空间中的插件更高的标准。目录提交必须通过通用软件包检查，以及针对目录展示字段、审查材料、MCP 工具、技能、资源和图像的额外检查。本参考资料还涵盖提交门户之外也可能出现的通用软件包检查，例如 MCP 服务器引用检查。

请根据提交时返回的错误代码查找对应要求。错误会阻止提交。警告不会阻止提交，但您应在继续之前审查这些警告。

非空值不能仅包含空白字符。支持的文本不包括控制字符、Unicode 行分隔符或段落分隔符，以及不受支持的不可见格式字符。HTTPS URL 必须包含主机，且不得包含嵌入的凭据或不受支持的字符。

最终目录提交

软件包即使通过上传验证，仍可能无法通过最终目录提交。最终提交对目录展示信息采用更严格的限制，并检查 MCP 配置、技能扫描、测试用例和政策合规声明。

字段	最终提交规则
软件包名称	必填；最多 64 个字符。须以 ASCII 字母或数字开头，且只能使用 ASCII 字母、数字、`_` 和 `-`。
版本	必填；使用最多 64 个字符的语义化版本号。
显示名称	必填；单行；最多 30 个字符。
简短描述	必填；单行；最多 30 个字符。
详细描述	必填；最多 4,000 个字符。允许换行。
开发者名称	必填；单行；最多 80 个字符。
类别	必填；请选择目录展示信息和界面错误一节中列出的受支持类别。
能力	最多 20 项。每项能力必须为非空单行文本，且最多 120 个字符。
入门提示	最多 3 条。每条提示必须为非空单行文本，经过 Unicode 和空白字符规范化后不得重复，最多 128 个字符，且不得包含 MCP 服务器的 `@mention`。
URL	远程 MCP 提交时必填；通过 ZIP 上传仅包含技能的插件时为可选项。网站、支持、隐私政策和条款 URL 必须使用 HTTPS，且最多 1,024 个字符。
品牌颜色	可选，使用六位十六进制颜色值。浅色版本的颜色与白色的对比度必须至少为 2:1，深色版本的颜色与 `#212121` 的对比度必须至少为 2:1。

每次插件提交还必须满足以下要求：

每个随附技能均须通过安全性和信息安全扫描。扫描最多可能需要 2 小时。
经过验证的开发者或企业身份，以及所有必需的政策合规声明。

对于远程 MCP 插件，最终提交还必须提供：

符合上述规则的网站、支持、隐私政策和条款 URL。
演示录像 URL，展示各受支持平台上的主要使用场景和工具。
恰好五个正向测试用例、三个反向测试用例，以及发行说明。
生产环境的 HTTPS MCP 服务器 URL、已完成的域名验证质询，以及成功且仍有效的工具扫描结果。
为每个 MCP 工具明确设置 readOnlyHint、openWorldHint 和 destructiveHint 的值，并说明每个值的设置依据。
如果服务器使用 OAuth，须提供可供审查人员直接使用的演示凭据。
仅当 MCP 服务器提供自定义 UI 时才可添加截图。如果您添加截图，请为每条入门提示提供一张 PNG 或 JPEG 图像。每张截图的宽度必须恰好为 706 像素，高度必须为 400–860 像素。

最终元数据错误

在这些错误名称中，subtitle 表示简短描述，description 表示详细描述。

名称	要求
`submission_display_name_required`	显示名称为必填项，必须为非空单行文本。
`submission_display_name_too_long`	显示名称不得超过 30 个字符。
`submission_display_name_character_unsupported`	显示名称必须使用受支持的文本，且只能占一行。
`submission_subtitle_required`	简短描述为必填项，必须为非空单行文本。
`submission_subtitle_too_long`	简短描述不得超过 30 个字符。
`submission_subtitle_character_unsupported`	简短描述必须使用受支持的文本，且只能占一行。
`submission_description_required`	详细描述为必填项，且不能为空。允许换行。
`submission_description_too_long`	详细描述不得超过 4,000 个字符。
`submission_description_character_unsupported`	详细描述必须使用受支持的文本。允许换行。
`submission_developer_name_required`	开发者名称为必填项，必须为非空单行文本。
`submission_developer_name_too_long`	开发者名称不得超过 80 个字符。
`submission_developer_name_character_unsupported`	开发者名称必须使用受支持的文本，且只能占一行。
`plugin_capability_invalid`	每项能力必须为非空文本，使用受支持的文本，只能占一行，且不得超过 120 个字符。
`plugin_default_prompt_mention`	入门提示不得包含 MCP 服务器的 `@mentions`。
`plugin_default_prompt_duplicate`	入门提示经过 Unicode 和空白字符规范化后不得重复。

MCP 和审查错误

这些错误适用于远程 MCP 提交。

名称	要求
`annotations_required`	每个 MCP 工具都必须准确设置 `readOnlyHint`、`openWorldHint` 和 `destructiveHint`。
`justification_required`	每个 MCP 工具注解都必须说明其只读、开放世界或破坏性行为的依据。
`scan_required`	MCP 工具必须具有针对生产环境 MCP 服务器的成功扫描结果，且结果仍然有效。
`domain_verification_required`	必须在 MCP 主机或允许的父级主机上生成的 `/.well-known/openai-apps-challenge` URL 处托管完全一致的验证 Token，并且必须通过验证域名检查。
`frame_domain_explanation_required`	对于 MCP 工具扫描报告的每个外部框架域名，都必须说明 UI 为什么需要它，以及它提供什么内容。
`screenshots_not_allowed`	只有当前 MCP 工具扫描报告了 UI 输出模板时，才允许提供截图。

归档文件错误

ZIP 上传错误和警告

门户的 仅技能 提交流程接受技能 ZIP 包。错误会阻止上传；警告则需要确认。

名称	要求
`plugin_name_mismatch`	更新时的包名称必须与现有插件名称一致。
`plugin_version_unchanged`	新版本必须在清单中使用不同的 `version`；复用已发布的版本需要确认。
`mcp_configuration_excluded`	仅包含技能的上传内容不包含 `mcpServers`、`mcp.json` 和 `.mcp.json`。请通过包含 MCP提交流程提交远程 MCP 服务器。
`app_configuration_excluded`	仅包含技能的 ZIP 上传内容不得包含 `apps` 或 `.app.json`；带有 MCP 服务器的插件必须使用包含 MCP提交流程。
`screenshot_configuration_excluded`	仅包含技能的 ZIP 上传内容不得包含 `interface.screenshots`；提供截图需要使用包含 MCP 提交流程，且插件必须具有自定义 UI。
`claude_format_normalized`	`.claude-plugin/plugin.json` 会转换为 `.codex-plugin/plugin.json`，门户会补充缺失的界面默认值并添加规范化后的文本字段。
`manifest_normalized`	门户会将规范化后的清单保存为 `.codex-plugin/plugin.json`；更改过的字段需要确认。
`developer_name_defaulted`	`author.name` 和 `interface.developerName` 必须一致，否则会在确认后将两者均设为所选的已验证身份。

ZIP 结构和限制错误

名称	要求
`archive_empty`	归档文件不得为空。
`archive_too_large`	压缩后的 ZIP 大小不得超过 100 MB。
`archive_format_not_zip`	归档文件必须是有效且未损坏的 ZIP 文件。
`archive_member_path_empty`	归档条目路径不得为空。
`archive_member_path_has_outer_whitespace`	归档条目路径不得以空白字符开头或结尾。
`archive_member_path_has_backslash`	归档条目路径必须使用 `/`，不得使用反斜杠。
`archive_member_path_absolute`	归档条目路径必须是相对于归档根目录的路径。
`archive_member_path_has_empty_segment`	归档条目路径不得包含空路径段。
`archive_member_path_has_parent_segment`	归档条目路径不得包含 `..` 路径段。
`archive_member_path_too_deep`	归档条目路径最多可包含 20 个路径段，包括文件名。
`archive_member_path_too_long`	归档条目路径必须在支持的路径长度限制内。
`archive_member_path_normalization_collision`	归档条目路径在经过大小写和 Unicode 规范化后必须仍然唯一。
`archive_member_type_unsupported`	归档条目必须是普通文件或目录。
`archive_member_too_large`	归档条目大小不得超过 100 MiB。
`archive_member_path_duplicate`	归档条目路径必须唯一。
`archive_member_path_type_conflict`	文件路径不得同时作为目录，也不得包含其他归档条目。
`archive_too_many_entries`	归档文件包含的条目不得超过 5,000 个。
`archive_uncompressed_too_large`	解压后的归档文件大小不得超过 512 MiB。
`archive_member_unreadable`	每个归档条目都必须可读取、未加密，并且使用受支持的压缩方式。

插件根目录错误

名称	要求
`plugin_root_missing`	所选路径必须存在，且必须是包含插件的目录。
`archive_plugin_files_missing`	仅包含技能的 ZIP 必须包含受支持的插件清单和至少一个有效技能。
`plugin_root_ambiguous`	ZIP 必须有且仅有一个插件根目录，位于归档根目录或一个顶层目录中。
`plugin_root_has_siblings`	如果 ZIP 中有顶层插件目录，则不得包含与该目录同级的文件。

插件清单错误

名称	要求
`plugin_manifest_missing`	ZIP 必须在其根目录或唯一的顶层目录中包含以下文件之一：使用受支持的 Agent Plugins 模式的根级 `plugin.json`、`.codex-plugin/plugin.json`、`.agent-plugin/plugin.json` 或 `.claude-plugin/plugin.json`。
`plugin_manifest_not_file`	插件清单必须是普通 JSON 文件。
`plugin_manifest_unreadable`	插件清单必须是可读取的 UTF-8 文本。
`plugin_manifest_json_malformed`	插件清单必须包含有效的 JSON；报告语法格式错误时会附带行号。
`plugin_manifest_root_not_object`	插件清单的顶层必须是 JSON 对象。
`codex_manifest_parent_not_directory`	`.codex-plugin` 必须是目录。
`codex_manifest_path_not_file`	`.codex-plugin/plugin.json` 必须是普通 JSON 文件。
`plugin_id_wrong_type`	如果提供 `id`，其值必须是字符串。
`plugin_id_empty`	如果提供 `id`，其值不得为空。
`plugin_name_missing`	必须提供 `name`。
`plugin_name_wrong_type`	`name` 必须是字符串。
`plugin_name_empty`	`name` 不得为空。
`plugin_name_too_long`	`name` 不得超过 64 个字符。
`plugin_name_format`	`name` 必须以 ASCII 字母或数字开头，且只能包含 ASCII 字母、数字、`_` 或 `-`。
`plugin_version_missing`	必须提供 `version`。
`plugin_version_wrong_type`	`version` 必须是字符串。
`plugin_version_empty`	`version` 必须是非空的语义化版本字符串，例如 `1.0.0`。
`plugin_version_not_semver`	`version` 必须采用语义化版本格式，例如 `1.0.0`。
`plugin_version_too_long`	`version` 不得超过 64 个字符。
`plugin_description_missing`	必须提供 `description`。
`plugin_description_wrong_type`	`description` 必须是字符串。
`plugin_description_empty`	`description` 不得为空。
`plugin_description_too_long`	`description` 不得超过 1,024 个字符。
`plugin_description_character_unsupported`	`description` 必须使用受支持的文本。允许换行。
`plugin_developer_missing`	必须提供 `author.name`。`interface.developerName` 也必须提供，其错误会单独报告。
`plugin_author_wrong_type`	`author` 必须是对象。
`plugin_author_name_wrong_type`	`author.name` 必须是字符串。
`plugin_author_name_empty`	`author.name` 不得为空。
`plugin_author_name_too_long`	`author.name` 不得超过 120 个字符。
`plugin_author_name_character_unsupported`	`author.name` 必须使用受支持的文本。
`plugin_author_email_wrong_type`	如果提供 `author.email`，其值必须是字符串。
`plugin_author_email_empty`	如果提供 `author.email`，其值不得为空。
`plugin_author_email_too_long`	`author.email` 不得超过 320 个字符。
`plugin_author_email_character_unsupported`	`author.email` 必须使用受支持的文本。
`plugin_author_url_wrong_type`	如果提供 `author.url`，其值必须是字符串。
`plugin_author_url_empty`	如果提供 `author.url`，其值不得为空。
`plugin_author_url_not_https`	`author.url` 必须是 HTTPS URL。
`plugin_author_url_has_credentials`	`author.url` 不得包含凭据。
`plugin_author_url_too_long`	`author.url` 不得超过 2,048 个字符。
`plugin_author_url_character_unsupported`	`author.url` 必须使用受支持的文本。

目录展示信息和界面错误

插件清单中的 interface 对象定义了向用户展示的公开目录信息。该对象位于 .codex-plugin/plugin.json 中，使用的字段包括 displayName 和 shortDescription：

{
  "interface": {
    "displayName": "Example Plugin",
    "shortDescription": "Summarize documents",
    "longDescription": "Summarize and organize documents.",
    "developerName": "Example",
    "category": "Productivity",
    "capabilities": ["Summarize documents"]
  }
}

对于仅包含技能的插件，通过 ZIP 上传时，四个目录展示 URL（网站、隐私政策、条款和支持）均为可选项。提交远程 MCP 时，这些 URL 为必填项。包验证时，每个 URL 的长度上限为 2,048 个字符；最终提交到目录时，上限为 1,024 个字符。

名称	要求
`plugin_interface_wrong_type`	插件清单中的 `interface` 字段必须是 JSON 对象。
`plugin_display_name_wrong_type`	`interface.displayName` 必须是字符串。
`plugin_display_name_empty`	必须提供 `interface.displayName`，且其值不得为空。
`plugin_display_name_too_long`	包验证时，`interface.displayName` 不得超过 80 个字符；最终提交到目录时，不得超过 30 个字符。
`plugin_display_name_character_unsupported`	`interface.displayName` 必须使用受支持的文本。
`plugin_short_description_missing`	必须提供 `interface.shortDescription`，且内容必须为单行。包验证时，不得超过 240 个字符；最终提交到目录时，不得超过 30 个字符。
`plugin_short_description_wrong_type`	`interface.shortDescription` 必须是字符串。
`plugin_short_description_empty`	`interface.shortDescription` 不得为空。
`plugin_short_description_too_long`	包验证时，`interface.shortDescription` 不得超过 240 个字符；最终提交到目录时，不得超过 30 个字符。
`plugin_short_description_character_unsupported`	`interface.shortDescription` 必须使用受支持的文本。
`plugin_long_description_wrong_type`	`interface.longDescription` 必须是字符串。
`plugin_long_description_empty`	必须提供 `interface.longDescription`，且其值不得为空。
`plugin_long_description_too_long`	`interface.longDescription` 不得超过 4,000 个字符。
`plugin_long_description_character_unsupported`	`interface.longDescription` 必须使用受支持的文本。允许换行。
`plugin_developer_name_wrong_type`	`interface.developerName` 必须是字符串。
`plugin_developer_name_empty`	必须提供 `interface.developerName`，且其值不得为空。
`plugin_developer_name_too_long`	包验证时，`interface.developerName` 不得超过 120 个字符；最终提交到目录时，不得超过 80 个字符。
`plugin_developer_name_character_unsupported`	`interface.developerName` 必须使用受支持的文本。
`plugin_category_wrong_type`	`interface.category` 必须是字符串。
`plugin_category_empty`	如果提供 `interface.category`，其值不得为空；省略该字段即可使用 `Other`。
`plugin_category_unknown`	`interface.category` 必须是 `Productivity`、`Creativity`、`Developer Tools`、`Business & Operations`、`Data & Analytics`、`Communication`、`Education & Research`、`Security`、`Finance`、`Healthcare`、`Travel`、`Entertainment` 或 `Other`。
`plugin_category_character_unsupported`	`interface.category` 必须使用受支持的文本。
`plugin_capabilities_wrong_type`	`interface.capabilities` 必须是字符串列表。
`plugin_capabilities_too_many`	`interface.capabilities` 不得包含超过 20 个条目。
`plugin_capability_wrong_type`	`interface.capabilities` 中的每个条目都必须是字符串。
`plugin_capability_empty`	提供的每个 `interface.capabilities` 条目都不得为空。
`plugin_capability_too_long`	`interface.capabilities` 中的每个条目都不得超过 120 个字符。
`plugin_capability_character_unsupported`	`interface.capabilities` 中的每个条目都必须使用受支持的文本。
`plugin_website_url_wrong_type`	如果提供 `interface.websiteURL`，其值必须是字符串。
`plugin_website_url_empty`	如果提供 `interface.websiteURL`，其值不得为空。
`plugin_website_url_format`	`interface.websiteURL` 必须是 HTTPS URL。
`plugin_website_url_too_long`	`interface.websiteURL` 必须符合上架信息中 URL 的长度限制。
`plugin_privacy_policy_url_wrong_type`	如果提供 `interface.privacyPolicyURL`，其值必须是字符串。
`plugin_privacy_policy_url_empty`	如果提供 `interface.privacyPolicyURL`，其值不能为空。
`plugin_privacy_policy_url_format`	`interface.privacyPolicyURL` 必须是 HTTPS URL。
`plugin_privacy_policy_url_too_long`	`interface.privacyPolicyURL` 必须符合上架信息中 URL 的长度限制。
`plugin_terms_of_service_url_wrong_type`	如果提供 `interface.termsOfServiceURL`，其值必须是字符串。
`plugin_terms_of_service_url_empty`	如果提供 `interface.termsOfServiceURL`，其值不能为空。
`plugin_terms_of_service_url_format`	`interface.termsOfServiceURL` 必须是 HTTPS URL。
`plugin_terms_of_service_url_too_long`	`interface.termsOfServiceURL` 必须符合上架信息中 URL 的长度限制。
`plugin_support_url_wrong_type`	如果提供 `interface.supportURL`，其值必须是字符串。
`plugin_support_url_empty`	如果提供 `interface.supportURL`，其值不能为空。
`plugin_support_url_format`	`interface.supportURL` 必须是 HTTPS URL。
`plugin_support_url_too_long`	`interface.supportURL` 必须符合上架信息中 URL 的长度限制。
`plugin_homepage_wrong_type`	如果提供 `homepage`，其值必须是字符串。
`plugin_homepage_empty`	如果提供 `homepage`，其值不能为空。
`plugin_homepage_format`	`homepage` 必须是 HTTPS URL。
`plugin_homepage_too_long`	`homepage` 不得超过 2,048 个字符。
`plugin_brand_color_wrong_type`	如果提供 `interface.brandColor`，其值必须是字符串。
`plugin_brand_color_empty`	如果提供 `interface.brandColor`，其值不能为空。
`plugin_brand_color_format`	`interface.brandColor` 必须是六位十六进制颜色值，例如 `#1ABCFE`。
`plugin_brand_color_dark_wrong_type`	如果提供 `interface.brandColorDark`，其值必须是字符串。
`plugin_brand_color_dark_empty`	如果提供 `interface.brandColorDark`，其值不能为空。
`plugin_brand_color_dark_format`	`interface.brandColorDark` 必须是六位十六进制颜色值，例如 `#1ABCFE`。
`plugin_brand_color_contrast`	`interface.brandColor` 与白色的对比度必须至少为 2:1。
`plugin_brand_color_dark_contrast`	`interface.brandColorDark` 与 `#212121` 的对比度必须至少为 2:1。
`plugin_default_prompt_wrong_type`	`interface.defaultPrompt` 必须是字符串或字符串列表。
`plugin_default_prompt_too_many`	`interface.defaultPrompt` 最多只能包含三条提示。
`plugin_default_prompt_entry_wrong_type`	`interface.defaultPrompt` 中的每个条目都必须是字符串。
`plugin_default_prompt_empty`	如果提供 `interface.defaultPrompt` 中的条目，每个条目都不能为空。
`plugin_default_prompt_too_long`	包验证时，`interface.defaultPrompt` 中的每个条目不得超过 512 个字符；最终提交到目录时，每个条目不得超过 128 个字符。
`plugin_default_prompt_character_unsupported`	`interface.defaultPrompt` 中的每个条目都必须使用受支持的文本，且只能占一行。

插件内容错误

名称	要求
`plugin_skills_path_wrong_type`	`skills` 必须是指向根目录下 `skills/` 目录的路径字符串。
`plugin_skills_path_empty`	如果提供 `skills`，其值必须是指向根目录下 `skills/` 目录的非空路径。
`plugin_skills_path_unsupported`	`skills` 必须解析为根目录下的 `skills/` 目录。
`plugin_skills_directory_missing`	声明的根目录下的 `skills/` 目录必须存在。
`plugin_skills_path_not_directory`	如果声明了根目录下的 `skills/`，它必须是目录。
`plugin_apps_path_wrong_type`	`apps` 必须是指向根目录下 `.app.json` 的路径字符串。
`plugin_apps_path_empty`	如果提供 `apps`，其值必须是指向根目录下 `.app.json` 的非空路径。
`plugin_apps_path_unsupported`	`apps` 必须解析为根目录下的 `.app.json`。
`plugin_apps_file_missing`	声明的根目录下的 `.app.json` 文件必须存在。
`plugin_apps_path_not_file`	如果声明了根目录下的 `.app.json`，它必须是普通文件。
`plugin_mcp_path_wrong_type`	`mcpServers` 必须是指向根目录下 `.mcp.json` 的路径字符串。
`plugin_mcp_path_empty`	`mcpServers` 必须是非空路径。请将其设置为 `./.mcp.json`，或移除该字段。
`plugin_mcp_path_unsupported`	`mcpServers` 必须解析为根目录下的 `.mcp.json`。
`plugin_mcp_file_missing`	`mcpServers` 声明了根目录下的 `.mcp.json`，但该文件不存在。
`plugin_mcp_path_not_file`	根目录下的 `.mcp.json` 必须是普通文件。
`plugin_runtime_surface_missing`	仅包含技能的 ZIP 必须包含至少一个有效技能。本地包和工作空间包也可以引用符合条件的 MCP 服务器。

MCP 清单错误

这些错误适用于兼容性文件 .mcp.json。对于可移植包，导入过程会根据根目录下的 plugin.json 和 mcp.json 生成此文件及 .codex-plugin/plugin.json。上述组件路径错误也可能指向这些生成的文件。请修正源可移植配置；不要仅因兼容性诊断提到了某个文件名，就将 mcp.json 重命名为 .mcp.json。

名称	要求
`mcp_manifest_unreadable`	`.mcp.json` 必须是可读取的 UTF-8 文本。
`mcp_manifest_json_malformed`	`.mcp.json` 必须包含有效的 JSON；报告语法错误时会附上行号。
`mcp_manifest_wrong_type`	`.mcp.json` 的顶层必须是 JSON 对象。
`mcp_servers_missing`	`.mcp.json` 必须包含顶层字段 `mcpServers`。
`mcp_servers_wrong_type`	`mcpServers` 必须是对象。
`mcp_server_name_empty`	每个 MCP 服务器名称都必须包含至少一个非空白字符。
`mcp_server_wrong_type`	每个 `mcpServers.<server-name>` 的值都必须是包含该服务器声明的对象。

技能错误

名称	要求
`skill_manifest_missing`	技能必须包含 `SKILL.md` 文件。
`skill_bundle_too_large`	每个压缩后的技能包都不得超过错误信息中报告的 MiB 大小限制。
`skill_directory_hidden`	技能目录名不得以 `.` 开头。
`skill_manifest_nested`	每个技能目录都必须是 `skills/` 的直接子目录。
`skill_manifest_not_regular_file`	`SKILL.md` 必须是普通文件。
`skill_manifest_unreadable`	`SKILL.md` 必须可读。
`skill_manifest_invalid_utf8`	`SKILL.md` 的内容必须采用有效的 UTF-8 编码。
`skill_frontmatter_missing`	`SKILL.md` 必须以 YAML 前置元数据开头，且元数据必须位于两行 `---` 之间。
`skill_frontmatter_unclosed`	`SKILL.md` 的 YAML 前置元数据必须以 `---` 结尾。
`skill_frontmatter_yaml_malformed`	`SKILL.md` 的前置元数据必须包含有效的 YAML。
`skill_frontmatter_wrong_type`	`SKILL.md` 的前置元数据必须包含 YAML 映射。
`skill_name_missing`	`name` 为必填项，且不得为空。
`skill_name_wrong_type`	`name` 必须是字符串。
`skill_name_empty`	`name` 不得为空。
`skill_name_character_unsupported`	技能前置元数据中的 `name` 必须使用受支持的文本。
`skill_description_missing`	`description` 为必填项，且不得为空。
`skill_description_wrong_type`	`description` 必须是字符串。
`skill_description_empty`	`description` 不得为空。
`skill_description_too_long`	`description` 不得超过 1,024 个字符。
`skill_description_character_unsupported`	技能前置元数据中的 `description` 必须使用受支持的文本。
`skill_body_empty`	技能指令不得为空。
`skill_identity_too_long`	插件名称与技能名称组合后的名称（`plugin-name:skill-name`）不得超过 64 个字符。
`skill_identity_duplicate`	每个技能的 `name` 在插件内必须唯一。

技能智能体元数据错误

随插件打包的技能可以在 skills/<skill>/agents/openai.yaml 中定义自己的 interface。这决定了技能向用户呈现的方式，与插件清单中的 interface 相互独立。技能界面字段使用 snake_case 命名方式：

interface:
  display_name: "Summarize documents"
  short_description: "Summarize a document"
  icon_small: "./assets/icon.png"
  default_prompt: "Summarize the selected document."

名称	要求
`skill_agent_not_regular_file`	`agents/openai.yaml` 必须是普通文件。
`skill_agent_unreadable`	`agents/openai.yaml` 必须可读。
`skill_agent_invalid_utf8`	`agents/openai.yaml` 的内容必须采用有效的 UTF-8 编码。
`skill_agent_yaml_malformed`	`agents/openai.yaml` 必须包含有效的 YAML。
`skill_agent_top_level_wrong_type`	`agents/openai.yaml` 的顶层必须包含 YAML 映射。
`skill_agent_interface_missing`	如果包含 `agents/openai.yaml` 文件，该文件中必须提供 `interface`。
`skill_agent_interface_wrong_type`	`agents/openai.yaml` 中的 `interface` 必须是 YAML 映射。
`skill_agent_display_name_missing`	`interface.display_name` 为必填项，且不得为空。
`skill_agent_display_name_wrong_type`	`interface.display_name` 必须是字符串。
`skill_agent_display_name_empty`	`interface.display_name` 不得为空。
`skill_agent_short_description_missing`	`interface.short_description` 为必填项，且不得为空。
`skill_agent_short_description_wrong_type`	`interface.short_description` 必须是字符串。
`skill_agent_short_description_empty`	`interface.short_description` 不得为空。
`skill_agent_icon_small_wrong_type`	如果提供 `interface.icon_small`，其值必须是非空的相对文件路径。
`skill_agent_icon_small_empty`	如果提供 `interface.icon_small`，其值必须是非空的相对文件路径，例如 `assets/icon.png`。
`skill_agent_icon_large_wrong_type`	如果提供 `interface.icon_large`，其值必须是非空的相对文件路径。
`skill_agent_icon_large_empty`	如果提供 `interface.icon_large`，其值必须是非空的相对文件路径，例如 `assets/icon.png`。
`skill_agent_brand_color_wrong_type`	如果提供 `interface.brand_color`，其值必须是字符串。
`skill_agent_brand_color_empty`	如果提供 `interface.brand_color`，其值必须是非空的六位十六进制颜色值，例如 `#1ABCFE`。
`skill_agent_brand_color_format`	`interface.brand_color` 必须是六位十六进制颜色值，例如 `#1ABCFE`。
`skill_agent_default_prompt_wrong_type`	如果提供 `interface.default_prompt`，其值必须是字符串。
`skill_agent_default_prompt_empty`	如果提供 `interface.default_prompt`，其值不得为空。
`skill_agent_policy_wrong_type`	如果提供 `policy`，其值必须是 YAML 映射。
`skill_agent_allow_implicit_invocation_wrong_type`	`policy` 只能包含 `products` 和 `allow_implicit_invocation`。`products` 必须包含 `CHAT`、`CODEX` 或两者，且 `allow_implicit_invocation` 必须为 `true` 或 `false`。
`skill_agent_dependencies_wrong_type`	`dependencies` 必须是 YAML 映射；仅支持 `tools`。
`skill_agent_dependency_unsupported`	`agents/openai.yaml` 中仅支持 `dependencies.tools`。

资源路径错误

名称	要求
`declared_asset_path_wrong_type`	指定资源字段的值必须是文件路径字符串。
`declared_asset_path_empty`	指定资源字段的值不得为空。
`declared_asset_path_has_outer_whitespace`	指定资源字段的值不得以空白字符开头或结尾。
`declared_asset_path_has_control_character`	指定资源字段的值不得包含 U+0000–U+001F 或 U+007F 字符。
`branding_asset_path_missing_root_prefix`	指定资源字段的值必须以 `./` 开头。
`declared_asset_path_unsafe`	指定资源字段的值必须是插件内部的相对路径，不得包含绝对路径、驱动器前缀或 `..` 路径遍历段。
`declared_asset_path_outside_package`	指定资源字段必须引用插件内部的文件。
`declared_asset_file_missing`	指定资源字段引用的文件不存在。
`declared_asset_not_regular_file`	指定的资源字段必须引用普通文件，不能引用目录或特殊文件。

图像错误

目录中的品牌图像必须使用受支持的文件类型，并符合以下文件大小和尺寸限制。这些规则适用于打包的品牌资源；起始提示的屏幕截图适用上文单独列出的门户限制。

名称	要求
`plugin_logo_path_missing`	`interface.logo` 为必填项，且必须引用正方形图像。
`plugin_composer_icon_path_missing`	`interface.composerIcon` 为必填项，且必须引用正方形图像。
`image_file_unreadable`	图像文件必须可读。
`image_file_too_large`	图像大小不得超过 5 MiB。
`image_file_format_unsupported`	图像文件名必须以 `.png`、`.jpg`、`.jpeg`、`.webp` 或 `.svg` 结尾。
`raster_image_decode_failed`	光栅图像必须是可安全解码的 PNG、JPEG 或 WebP 文件。
`raster_image_extension_content_mismatch`	图像文件的扩展名必须与检测到的图像格式一致。
`raster_image_not_square`	图像必须为正方形。
`raster_image_dimensions_too_small`	图像尺寸必须至少为 48×48 像素。
`raster_image_dimensions_too_large`	图像尺寸不得超过 4,096×4,096 像素。
`svg_xml_malformed`	SVG 必须包含有效的 UTF-8 编码 XML。
`svg_root_element_invalid`	SVG 的根元素必须为 `<svg>`。
`svg_dimensions_missing`	SVG 必须定义数值形式的 `viewBox`，或同时定义数值形式的 `width` 和 `height`。
`svg_dimensions_not_numeric`	SVG 尺寸必须使用数值，不得包含单位或百分比。
`svg_dimensions_not_positive`	SVG 的宽度和高度必须为有限正数。
`svg_dimensions_not_square`	SVG 的宽度和高度必须相等。
`svg_dimensions_too_small`	SVG 尺寸必须至少为 48×48 像素。

MCP 服务器引用错误

当插件引用已注册的 MCP 服务器时，通用包检查会验证 .app.json。提交门户不会发布对现有集成的引用。通过 仅技能 上传时会移除 .app.json。请使用 包含 MCP 直接提交 MCP 服务器。

对于本地包或工作空间包，顶层 apps 对象将每个 MCP 服务器别名映射到已注册的服务器条目。这些配置名称和错误代码保留 app 的原始拼写。

名称	要求
`app_manifest_unreadable`	`.app.json` 必须是可读的 UTF-8 文本。
`app_manifest_json_malformed`	`.app.json` 在报告的行附近包含格式错误的 JSON。
`app_manifest_wrong_type`	`.app.json` 的顶层必须是 JSON 对象。
`app_entries_missing`	`apps` 为必填项。
`app_entries_wrong_type`	`apps` 必须是对象。
`app_entry_wrong_type`	每个服务器条目必须是对象。
`app_id_missing`	每个服务器条目都必须提供 `id`。
`app_id_wrong_type`	每个服务器条目的 `id` 必须是字符串。
`app_id_format`	每个服务器条目的 `id` 必须以 `asdk_app_`、`connector_` 或 `templated_apps_` 开头，紧接一个字母或数字，之后只能包含字母、数字、`_` 或 `-`。
`app_entry_optional_wrong_type`	如果提供了服务器条目的 `optional`，其值必须为 `true` 或 `false`。
`app_entry_required_wrong_type`	如果提供了服务器条目的 `required`，其值必须为 `true` 或 `false`。
`app_not_eligible`	本地包或工作空间包必须引用符合条件且可用的 MCP 服务器。提交到目录时，必须使用包含 MCP 直接提交 MCP 服务器。

包警告

这些警告指出验证过程中会忽略或规范化的包内容。它们不会阻止提交。请检查这些警告，确认提交的插件包含预期的文件和设置。

名称	要求
`duplicate_app_reference`	`.app.json` 中的每个服务器 ID 必须仅被引用一次；重复引用会被视为同一台服务器。
`undeclared_app_manifest_ignored`	只有当插件清单中的 `apps` 字段设为 `./.app.json` 时，才会导入根目录下的 `.app.json`。
`undeclared_mcp_manifest_ignored`	只有当插件清单中的 `mcpServers` 字段设为 `./.mcp.json` 时，才会导入根目录下的 `.mcp.json`。
`skill_file_ignored`	直接位于 `skills/` 下的文件不会作为技能导入；每项技能都必须位于包含 `SKILL.md` 的目录中。
`skill_symlink_ignored`	直接位于 `skills/` 下的符号链接不会作为技能导入；每项技能都必须是包含 `SKILL.md` 的真实目录。
`skill_frontmatter_adjusted`	导入时，会移除技能 `name` 和 `description` 首尾的空白字符，并合并内部连续的空白字符，以完成规范化。
`skill_metadata_ignored`	技能界面设置必须使用 `agents/openai.yaml` 中的 `interface` 映射；`SKILL.md` 中的 `metadata` 不用于配置界面。

后续步骤

解决所有验证错误后，请返回提交插件完成提交。

建议

开始使用

核心概念

SDK 与 CLI

资源

旧版 API

选择模型

文本与代码

提示词

推理

图像与视频

实时交互与音频

专用模型

智能体 API

智能体 SDK

ChatKit

搜索与检索

连接工具与数据

构建工具工作流

计算机与代码

媒体

GPT-Live

Realtime API

构建语音应用

连接

音频处理

上线

性能与质量

成本与吞吐量

安全与治理

基础设施与访问

运营

核心概念

规划

构建

测试与发布

转化规范

指南

资源

开始使用

指南

File Upload

API

Measurement

Advertiser API

API 参考

开始使用

基础

探索

可用平台

发布

工作流

能力

参考资料

自定义

配置文件

智能体配置

扩展 ChatGPT 和 Codex 的功能

Linux

Windows

开发工作流

扩展并实现自动化

环境

使用 Codex 构建

第三方集成

参考资料

权限

Codex Security

网络安全

入门

ChatGPT Work

身份与身份验证

工作空间访问权限、策略和模型

插件和连接器控制

使用情况、治理与合规

部署和模型提供商

社区

博客

社区

博客