参与 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。