与安装在工作空间中的插件相比,提交到公共目录的插件必须满足更严格的要求。除了通用的软件包检查,提交到目录的插件还必须通过针对目录条目字段、审核材料、MCP 工具、技能、资源和图像的额外检查。本文也介绍了在提交门户之外可能遇到的通用软件包检查,例如 MCP 服务器引用检查。
根据提交时返回的错误代码查找对应要求。错误会阻止提交。警告不会阻止提交,但请在继续之前查看警告内容。
要求非空的值不能只包含空白字符。支持的文本不包括控制字符、Unicode 行分隔符或段落分隔符,以及不受支持的不可见格式控制字符。HTTPS URL 必须包含主机,且不得包含嵌入的凭据或不受支持的字符。
向目录正式提交插件
即使软件包通过了上传验证,也可能无法通过最终的目录提交检查。最终提交对目录条目有更严格的限制,还会检查 MCP 配置、技能扫描结果、测试用例和政策合规声明。
| 字段 | 最终提交要求 |
|---|---|
| 软件包名称 | 必填,最多 64 个字符。必须以 ASCII 字母或数字开头,且只能包含 ASCII 字母、数字、_ 和 -。 |
| 版本 | 必填,必须使用语义化版本号,最多 64 个字符。 |
| 显示名称 | 必填,只能占一行,最多 30 个字符。 |
| 简短描述 | 必填,只能占一行,最多 30 个字符。 |
| 详细描述 | 必填,最多 4,000 个字符。允许换行。 |
| 开发者名称 | 必填,只能占一行,最多 80 个字符。 |
| 类别 | 必填,请从目录条目和界面错误一节列出的受支持类别中选择。 |
| 功能 | 最多 20 项。每项不能为空,只能占一行,最多 120 个字符。 |
| 起始提示词 | 最多 3 条。每条提示词都不能为空,只能占一行,最多 128 个字符,且不得包含对 MCP 服务器的 @mention。对 Unicode 和空白字符进行规范化后,各条提示词仍须互不重复。 |
| URL | 提交远程 MCP 插件时必填。以 ZIP 格式上传仅含技能的插件时可选。网站、支持、隐私政策和服务条款的 URL 均须使用 HTTPS,每个 URL 最多 1,024 个字符。 |
| 品牌颜色 | 可选,使用六位十六进制颜色值。浅色主题的品牌色与白色的对比度至少为 2:1,深色主题的品牌色与 #212121 的对比度至少为 2:1。 |
提交任何插件时还须满足以下要求:
- 随插件打包的每项技能都必须通过内容安全和信息安全扫描。扫描最长可能需要 2 小时。
- 开发者或企业身份必须通过验证,并提供所有必需的政策合规声明。
正式提交远程 MCP 插件时,还须满足以下要求:
- 提供符合上述规则的网站、支持、隐私政策和服务条款 URL。
- 提供演示录像的 URL,展示插件在各个受支持平台上的主要使用场景和工具。
- 提供恰好 5 个正向测试用例、3 个负向测试用例以及发行说明。
- 提供生产环境 MCP 服务器的 HTTPS URL,完成域名验证挑战,并确保工具扫描已成功完成且结果仍然有效。
- 为每个 MCP 工具明确设置
readOnlyHint、openWorldHint和destructiveHint的值,并逐一说明理由。 - 如果服务器使用 OAuth,请提供审核人员可直接使用的演示凭据。
最终提交时的元数据错误
在以下错误名称中,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 服务器的工具扫描必须已成功完成,且扫描结果仍然有效。 |
domain_verification_required |
必须在 MCP 主机或允许的上级域名主机上,通过生成的 /.well-known/openai-apps-challenge URL 提供完全一致的验证令牌,并通过验证域名检查。 |
frame_domain_explanation_required |
对于 MCP 工具扫描报告的每个外部框架域名,都必须说明界面为什么需要该域名,以及它提供哪些内容。 |
归档文件错误
ZIP 上传错误和警告
门户的仅含技能提交入口接受技能 ZIP 包和获准提交的本地 MCP 插件。获准提交的本地 MCP 插件无需包含技能。错误会阻止上传,出现警告时则需要确认。
| 名称 | 要求 |
|---|---|
plugin_name_mismatch |
更新时,软件包名称必须与现有插件名称一致。 |
plugin_version_unchanged |
发布新版本时,清单中的 version 必须与已发布版本不同。如果复用已发布的版本号,则需要确认。 |
mcp_configuration_excluded |
除非您的组织已获准提交本地 MCP 插件,否则门户会排除 MCP 配置。对于本地 MCP 插件,请联系您的 OpenAI 代表,确认提交插件的组织已列入允许名单。请通过包含 MCP入口提交远程 MCP 服务器。 |
app_configuration_excluded |
上传的 ZIP 包不得包含 apps 或 .app.json。请通过包含 MCP入口提交远程 MCP 服务器。对于本地 MCP 服务器,请遵循仅限桌面端的插件提交说明。 |
claude_format_normalized |
门户会将 .claude-plugin/plugin.json 转换为 .codex-plugin/plugin.json,补上缺失的界面默认值,并写入规范化后的文本字段。 |
manifest_normalized |
门户会将规范化后的清单保存为 .codex-plugin/plugin.json。您需要确认发生变更的字段。 |
developer_name_defaulted |
门户会根据您选择的已验证开发者身份自动设置目录条目中的开发者名称,无论 ZIP 包中填写的是哪个名称。 |
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 包必须包含受支持的插件清单,并至少包含一项有效技能或一个获准提交的本地 MCP 服务器。 |
plugin_root_ambiguous |
ZIP 包必须恰好包含一个插件根目录。该目录可以是归档根目录,也可以是归档中唯一的顶层目录。 |
plugin_root_has_siblings |
如果插件位于 ZIP 包的顶层目录中,该目录旁不能有同级文件。 |
插件清单错误
| 名称 | 要求 |
|---|---|
plugin_manifest_missing |
ZIP 包必须在归档根目录或其唯一的顶层目录中包含以下清单之一:符合受支持的智能体插件模式的根清单 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 最多可包含 3 条提示词。 |
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 清单错误
以下错误适用于兼容性文件 .mcp.json。对于可移植软件包,系统在导入时会生成此文件和 .codex-plugin/plugin.json,所依据的是根目录下的 plugin.json 和 mcp.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 不能重复。 |
技能的智能体元数据错误
随插件打包的技能可以定义自己的 interface,配置文件位于 skills/<skill>/agents/openai.yaml。这项配置决定用户看到的技能展示方式,与插件清单中的 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 |
interface 为必填字段,只要包含 agents/openai.yaml 文件,就必须在其中提供该字段。 |
skill_agent_interface_wrong_type |
interface 在 agents/openai.yaml 中必须是 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 |
依赖项仅支持 dependencies.tools,请在 agents/openai.yaml 中使用该字段。 |
资源路径错误
| 名称 | 要求 |
|---|---|
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 |
根目录下的 .app.json 仅在插件清单中的 apps 字段设为 ./.app.json 时才会导入。 |
undeclared_mcp_manifest_ignored |
根目录下的 .mcp.json 仅在插件清单中的 mcpServers 字段设为 ./.mcp.json 时才会导入。 |
skill_file_ignored |
直接位于 skills/ 下的文件不会作为技能导入。每项技能都必须位于包含 SKILL.md 的目录中。 |
skill_symlink_ignored |
直接位于 skills/ 下的符号链接不会作为技能导入。每项技能都必须位于包含 SKILL.md 的实际目录中。 |
skill_frontmatter_adjusted |
导入技能时,系统会规范化 name 和 description,去除首尾空白并合并内部连续的空白字符。 |
skill_metadata_ignored |
技能界面设置必须使用 interface 映射,该映射位于 agents/openai.yaml 中。metadata 位于 SKILL.md 中,不能用于配置界面。 |
后续步骤
解决所有验证错误后,请返回提交插件页面完成提交。