提交至公開目錄的外掛程式須符合比安裝在工作區的外掛程式更嚴格的標準。提交至目錄時,除了通過套件的共通檢查,上架欄位、審查資料、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 中,無法用來設定介面。 |
後續步驟
修正所有驗證錯誤後,請返回提交外掛程式頁面,完成提交作業。