docs(hagitask): expand community package guide

Add repository boundary and release pipeline overview, published task ID table, file-to-catalog mapping, and validation failure guidance to the community page.

Co-Authored-By: Hagicode <noreply@hagicode.com>
Signed-off-by: newbe36524 <newbe36524@qq.com>

Author: newbe36524

src/content/docs/guides/hagitask/community.mdx

@@ -11,7 +11,19 @@ description: 创建、校验、版本化并提交 HagiTask Community Packages 
 - 能初始化该仓库的嵌套 `hagitask` checkout。
 - 了解 JSON、Markdown 和 Git Pull Request。
 
-本页是面向贡献者的完整操作入口。`hagitask-community-packages` README 保留技术契约和命令，但不再复制本页的完整说明。
+本页是面向贡献者的完整操作入口。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 和仓库
 
@@ -28,6 +40,19 @@ npm install
 
 新任务放在 `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。
+
 ```text
 data/<taskId>/
   manifest.json
@@ -50,6 +75,20 @@ data/<taskId>/
 
 `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：
@@ -58,7 +97,8 @@ data/<taskId>/
 https://tasks.hagicode.com/schemas/task-preset-plugin/<schema>.schema.json
 ```
 
-具体文件对应关系以 Community Packages README 和 `hagitask/schemas/task-preset-plugin/` 为准。`manifest.json` 要声明任务 ID、版本、发布者、本地化 bundle 以及前端/后端资源路径。locale 文件应保持相同的键集合。
+具体文件对应关系以 `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` 放在英文页面，因为发布站点从英文页面生成分类和标签。
 
@@ -74,6 +114,8 @@ 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 中运行：
 
 ```bash
@@ -84,10 +126,23 @@ 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](/guides/hagitask/installation) 或[使用 HagiTask](/guides/hagitask/usage)。