外掛程式提交錯誤 – Plugins

提交至公開目錄的外掛程式，必須符合比安裝於工作區的外掛程式更嚴格的標準。提交至目錄的外掛程式必須通過共用套件檢查，以及針對上架資訊欄位、審查資料、MCP 工具、技能、資產和圖片的額外檢查。本參考資料也涵蓋可能在提交入口網站以外出現的共用套件檢查，例如 MCP 伺服器參照檢查。

請使用提交時傳回的錯誤代碼，查找對應的要求。錯誤會阻止提交。警告不會阻止提交，但你應先檢視警告，再繼續操作。

非空值不能只包含空白字元。支援的文字不包含控制字元、Unicode 行分隔符號或段落分隔符號，以及不支援的不可見格式字元。HTTPS 網址必須包含主機，且不得內嵌憑證或包含不支援的字元。

目錄最終提交

套件即使通過上傳驗證，仍可能無法通過目錄最終提交。最終提交會對上架資訊採用更嚴格的限制，並檢查 MCP 組態、技能掃描、測試案例和政策聲明。

欄位	最終提交規則
套件名稱	必填；最多 64 個字元。必須以 ASCII 字母或數字開頭，且只能使用 ASCII 字母、數字、`_` 和 `-`。
版本	必填；使用最多 64 個字元的語意化版本號。
顯示名稱	必填；限單行；最多 30 個字元。
簡短說明	必填；限單行；最多 30 個字元。
詳細說明	必填；最多 4,000 個字元。允許換行。
開發者名稱	必填；限單行；最多 80 個字元。
類別	必填；請選擇「上架資訊與介面錯誤」一節中列出的支援類別。
能力	最多 20 項。每項能力都不得為空，且必須為單行，最多 120 個字元。
起始提示詞	最多 3 個。每個提示詞都不得為空，經 Unicode 和空白字元正規化後不得重複，且必須為單行、最多 128 個字元，不得包含 MCP 伺服器的 `@mention`。
網址	提交遠端 MCP 時必填；以 ZIP 上傳僅含技能的外掛程式時為選填。網站、支援服務、隱私權政策和條款的網址必須使用 HTTPS，且最多 1,024 個字元。
品牌色彩	選填，使用六位數十六進位色碼。淺色色彩與白色的對比度必須至少為 2:1，深色色彩與 `#212121` 的對比度必須至少為 2:1。

每次提交外掛程式還必須符合以下要求：

每個隨附的技能都必須通過安全與安全性掃描。掃描最多可能需要 2 小時。
開發者或企業身分已通過驗證，並提供所有必要的政策聲明。

遠端 MCP 外掛程式的最終提交還必須符合以下要求：

提供符合上述規則的網站、支援服務、隱私權政策和條款網址。
提供示範錄影網址，展示在各個支援平台上的主要使用案例和工具。
提供恰好五個正向測試案例、三個反向測試案例，以及版本資訊。
提供正式環境的 HTTPS MCP 伺服器網址、完成網域驗證挑戰，並成功通過目前有效的工具掃描。
為每個 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 網址。
`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 上傳時，四種刊登資訊網址（網站、隱私權政策、條款和支援）皆為選填。提交遠端 MCP 時則必須提供。套件驗證時，這些網址的長度上限為 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 網址。
`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。對於可攜式套件，匯入程序會產生此檔案和 .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` 不得重複。

技能智慧體中繼資料錯誤

隨附的技能可以在 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

身分識別與身分驗證

工作區存取權、政策與模型

外掛程式與連接器控制措施

使用情況、治理與合規

部署與模型供應商

社群

部落格

社群

部落格