add-community-extension

添加社区扩展

处理扩展提交问题，并在社区目录中添加或更新扩展。

适用场景

• 有人提交了新的 [Extension] 问题
• 现有扩展提交了更新问题（新版本、更改元数据）
• 需要在 extensions/catalog.community.json 和 docs/community/extensions.md 中添加或更新社区扩展

流程

1. 获取提交问题

阅读 GitHub 问题，提取所有元数据：

• 扩展 ID、名称、版本、描述、作者
• 仓库 URL、下载 URL、主页、文档、更新日志
• 许可证、所需的 spec-kit 版本、可选工具依赖项
• 命令和钩子的数量
• 标签

2. 根据发布规则进行验证

检查以下所有项目（参见 extensions/EXTENSION-PUBLISHING-GUIDE.md）：

检查项	方法
仓库存在且为公开仓库	访问仓库 URL
存在 extension.yml 清单文件	在仓库文件列表中确认
存在 README.md	在仓库文件列表中确认
存在 LICENSE 文件	在仓库文件列表中确认
存在与版本匹配的 GitHub 发布版本	在仓库页面上检查发布版本
下载 URL 可访问	验证其符合 archive/refs/tags/vX.Y.Z.zip 格式，且发布版本存在
扩展 ID 仅包含小写字母和连字符	正则表达式：^[a-z][a-z0-9-]*$
版本符合语义化版本规范	格式：X.Y.Z
已勾选所有提交检查清单项目	在问题正文中确认

3. 确定是添加还是更新

在 extensions/catalog.community.json 中搜索扩展 ID。

• 未找到 → 这是新增扩展。继续执行第 4 步。
• 已找到 → 这是更新。继续执行第 4 步，但要原位替换现有条目，而不是插入新条目。

4. 添加或更新 extensions/catalog.community.json

新增扩展： 按扩展 ID 的字母顺序插入条目。

更新： 原位替换现有条目。仅更新发生变化的字段（通常是 version、download_url、description、provides、requires、tags、updated_at）。保留现有条目的 created_at 和 downloads/stars。

使用现有条目作为格式模板。必填字段：

{
  "<id>": {
    "name": "<name>",
    "id": "<id>",
    "description": "<description>",
    "author": "<author>",
    "version": "<version>",
    "download_url": "<download_url>",
    "repository": "<repository>",
    "homepage": "<homepage>",
    "documentation": "<documentation>",
    "changelog": "<changelog>",
    "license": "<license>",
    "category": "<category>",
    "effect": "<effect>",
    "requires": {
      "speckit_version": "<speckit_version>"
    },
    "provides": {
      "commands": <N>,
      "hooks": <N>
    },
    "tags": ["<tag1>", "<tag2>"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "<today>T00:00:00Z",
    "updated_at": "<today>T00:00:00Z"
  }
}

Category — 任意字符串；常见值：docs、code、process、integration、visibility Effect — 以下值之一：read-only、read-write

如果扩展存在可选工具依赖项，请在 "requires" 中添加一个 "tools" 数组：

"tools": [{ "name": "<tool>", "required": false }]

同时更新目录顶层的 "updated_at" 时间戳。

编辑后，运行以下命令验证 JSON：

python3 -c "import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')"

5. 添加或更新 docs/community/extensions.md 中的社区扩展表格

新增扩展： 按扩展名称的字母顺序，在 # Community Extensions 表格中插入一行。

更新： 找出现有行，原位更新描述或其他已更改字段。

根据扩展的行为确定类别和效果：

| <Name> | <Description> | `<category>` | <Effect> | [<repo-name>](<repository-url>) |

Category — 任意值；常见值：docs、code、process、integration、visibility Effect — 在 extension.yml 和 catalog.community.json 中使用规范值 read-only 或 read-write；仅在文档表格中使用 Read-only/Read+Write 作为显示内容

6. 提交、推送并创建 PR

新增扩展使用 add-，更新使用 update-：

# New extension
git checkout -b add-<extension-id>-extension

# Update
git checkout -b update-<extension-id>-extension

git add extensions/catalog.community.json docs/community/extensions.md

# New extension
git commit -m "Add <Name> extension to community catalog

Add <id> extension submitted by @<issue-author> to:
- extensions/catalog.community.json (alphabetical order)
- docs/community/extensions.md community extensions table

Closes #<issue-number>"

# Update
git commit -m "Update <Name> extension to v<version>

Update <id> extension submitted by @<issue-author>:
- extensions/catalog.community.json (version, download_url, etc.)
- docs/community/extensions.md community extensions table

Closes #<issue-number>"

git push origin <branch-name>

然后向 upstream（github/spec-kit）创建 PR，内容如下：

• 标题： Add <Name> extension to community catalog（或 Update <Name> extension to v<version>）
• 正文： 包含验证摘要、Closes #<issue-number> 和 cc @<issue-author>
• 分支： <fork-owner>:<branch-name>
• 目标分支： main

常见问题

• 字母顺序很重要——JSON 中的条目必须按 ID 排序，文档表格中的条目必须按名称排序。
• 别忘了更新目录的 updated_at——必须刷新 catalog.community.json 中的顶层时间戳。
• 编辑后验证 JSON——多余的逗号或缺失的花括号都会导致目录出错。
• 使用 Closes，不要使用 Fixes——对于提交问题，正确的关键词是 Closes #N。
• 参照提议的条目，但务必核实——问题中可能包含提议的 JSON 块，但始终要根据仓库的实际状态验证字段值。
• 更新时保留 created_at——保留原始的 created_at 值；只修改 updated_at。
• 更新时保留 downloads 和 stars——这些反映使用情况指标，不得重置。