如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
總覽 智慧體存取權 ChatGPT 與 Codex 使用者文件 使用案例

外掛程式提交錯誤

查找並修正外掛程式提交至公開目錄時出現的驗證錯誤

提交至公開目錄的外掛程式須符合比安裝在工作區的外掛程式更嚴格的標準。提交至目錄時,除了通過套件的共通檢查,上架欄位、審查資料、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,請提供審查人員可直接使用的示範帳號認證資訊。

最終提交的中繼資料錯誤

在下列錯誤名稱中,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 網址提供完全相符的驗證權杖,並通過驗證網域檢查。
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 網址。
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 必須符合上架網址的長度限制。
plugin_privacy_policy_url_wrong_type 如有提供 interface.privacyPolicyURL,其值必須是字串。
plugin_privacy_policy_url_empty 如有提供 interface.privacyPolicyURL,其值不得為空。
plugin_privacy_policy_url_format interface.privacyPolicyURL 必須是 HTTPS 網址。
plugin_privacy_policy_url_too_long interface.privacyPolicyURL 必須符合上架網址的長度限制。
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 網址。
plugin_terms_of_service_url_too_long interface.termsOfServiceURL 必須符合上架網址的長度限制。
plugin_support_url_wrong_type 如有提供 interface.supportURL,其值必須是字串。
plugin_support_url_empty 如有提供 interface.supportURL,其值不得為空。
plugin_support_url_format interface.supportURL 必須是 HTTPS 網址。
plugin_support_url_too_long interface.supportURL 必須符合上架網址的長度限制。
plugin_homepage_wrong_type 如有提供 homepage,其值必須是字串。
plugin_homepage_empty 如有提供 homepage,其值不得為空。
plugin_homepage_format homepage 必須是 HTTPS 網址。
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 資訊清單錯誤

下列錯誤適用於相容性檔案 .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 中,無法用來設定介面。

後續步驟

修正所有驗證錯誤後,請返回提交外掛程式頁面,完成提交作業。