參與 HagiTask 社群貢獻

適用對象： HagiTask 社群任務貢獻者和維護者。

前置條件：

已複製 hagitask-community-packages 儲存庫，並準備好 Node.js/npm。
能初始化該儲存庫內嵌的 hagitask checkout。
了解 JSON、Markdown 和 Git Pull Request。

本頁是貢獻者的完整操作入口。Community Packages README 僅保留儲存庫界線、目錄和指令參考。

儲存庫界線和發布流程

Community Packages 是社群任務定義的權威來源（source of truth）。貢獻者編輯 data/<taskId>/；HagiTask 維護共用套件 Schema；HagiTask Site 讀取 Community Packages 的特定提交，進行正規化並產生：

/index.json：用於探索任務的精簡目錄。
/tasks/<taskId>.json：包含完整資源和相容性資訊的詳細資料文件。
/packages/<taskId>.zip：供應用程式安裝的封存檔。

這些 JSON 和 ZIP 是產生的成果，不要在 Community Packages 中手動建立或修改。封存檔包含整個 data/<taskId>/ 目錄，因此目錄內新增的資源都會隨套件發布。

1. 準備 Schema 和儲存庫

在 Community Packages 儲存庫執行：

git submodule update --init --recursive
npm install

共用套件 Schema 的權威來源是 repos/hagitask/schemas/task-preset-plugin/，Community Packages 透過內嵌的 checkout 使用它。不要在 Community Packages 或 HagiTask Site 中複製或修改 Schema。

2. 建立任務套件

新任務放在 data/<taskId>/。taskId 必須是穩定且唯一的 lowercase kebab-case，並且始終與 manifest.json 中的 taskPresetId 完全一致；變更目錄名稱會改變已發布的詳細資料和封存檔 URL。

目前已發布的正式 ID 包括：

顯示名稱	`taskId`
UI Master	`ui-master`
AgentsMD	`claude-md-update`
Last 30 Days	`last30days`
Ponytail	`ponytail`
Goal	`goal`
OpenSpec Spec Compress	`openspec-spec-compress`

agentsmd 和 portytail 只是人類可讀別名，不是協定中的任務 ID。

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # 有命令目錄時才需要
  backend/
    task-preset.json
    prompts.json
    templates/<locale>/
      system.md
      user.hbs
  locales/
    en-US.json
    zh-CN.json
  store-page/
    index.en-US.md
    index.zh-CN.md

manifest.json、frontend/panel.json、backend/task-preset.json、backend/prompts.json、英文和中文 locale、兩份 store page，以及每個宣告語言的 prompt 範本都是必要資源。只有套件確實提供命令目錄時，才需要加入 commands.json。

檔案如何影響目錄

來源檔案	發布結果
`manifest.json` 的 `version`	目錄和詳細資料中的版本
`manifest.json` 的 `owner`	發布者
`manifest.json` 的 `localization`	用戶端載入的 locale bundle
`backend/task-preset.json` 的 `requirements`	任務需求和衍生的相容性資訊
store page 的 `title` / `summary`	多語言名稱、摘要和描述
英文 store page 的 `catalog` / `tags`	分類和標籤

如果英文頁面沒有 catalog，分類會退回使用第一個 tag，再退回使用 General。只有英文頁面的 catalog 和 tags 會參與目錄分類的產生。

3. 參照 Schema 並填寫資源

每個 JSON 檔案都必須保留對應的 $schema，並使用公開的 Schema URL：

https://tasks.hagicode.com/schemas/task-preset-plugin/<schema>.schema.json

各檔案的對應關係以 hagitask/schemas/task-preset-plugin/ 為準。manifest.json 必須宣告任務 ID、版本、發布者、本地化 bundle，以及前端／後端資源路徑。locale 檔案應保持相同的鍵集合。

store-page/index.en-US.md 和 index.zh-CN.md 至少需要 locale、slug、title 和 summary frontmatter。catalog 與 tags 應放在英文頁面，因為發布網站會從英文頁面產生分類和標籤。

4. 版本和驗證

每次已發布內容變更，都必須依語意化版本規則修改 manifest.json 的 version。不要重複使用舊版本號，否則目錄中繼資料和套件摘要會產生歧義。

執行現有驗證：

npm run validate

驗證程式會檢查正式 ID、Schema、資源宣告、本地化涵蓋範圍、prompt 範本和 store-page frontmatter。失敗時應修正 data/<taskId>/ 中的來源檔案，不可編輯 /index.json、/tasks/<taskId>.json 或 /packages/<taskId>.zip；這些都是 HagiTask Site 每次發布時產生的成果。

驗證工作流程會在修改套件內容的 Pull Request 和推送至 main 時執行；驗證失敗會阻止套件合併。

若需進一步確認發布契約，可在 hagitask-site checkout 中執行：

npm install
npm run typecheck
npm run build
npm run stage:schemas
npm run verify

網站建置時會再次執行正規化和發布 Schema 驗證。建置成功表示產生的目錄和詳細資料符合 community-index-v1 與 community-task-detail-v1 契約。

5. 提交 Pull Request

將 Pull Request 提交至 hagitask-community-packages，而不是 hagitask-site 或 hagitask。合併後，HagiTask Site 會更新至 Community Packages 的特定提交，並重新產生索引、詳細資料和 ZIP 封存檔。

hagitask 負責共用 Schema 和內建預設；如果套件格式契約本身需要變更，應另行在 HagiTask 儲存庫提出 Schema 變更。Community Packages 只維護 data/ 來源資料，網站只發布產生的結果。

驗證失敗時

依照錯誤訊息修正 data/<taskId>/ 中的來源檔案：

套件 Schema 錯誤：修正對應的 JSON，不要刪除 $schema 或放寬驗證。
資源或 locale 缺失：更新 manifest、locale、prompt template 或 store page，使宣告與實際檔案一致。
目錄詳細資料或封存檔 Schema 錯誤：檢查來源套件和網站正規化輸入，不要修補產生的 JSON。

如果 Schema 契約本身有問題，應在 HagiTask 儲存庫提出契約變更，而不是在本儲存庫複製一份 Schema。

下一步： 安裝 HagiTask 或使用 HagiTask。