如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

插件提交错误

查找并修复向公共目录提交插件时出现的验证错误

与安装在工作空间中的插件相比,提交到公共目录的插件必须满足更严格的要求。除了通用的软件包检查,提交到目录的插件还必须通过针对目录条目字段、审核材料、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 中,不能用于配置界面。

后续步骤

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