# 贡献指南 / Contributing

感谢你帮助维护 Awesome DSH Plugin。

Thank you for helping maintain Awesome DSH Plugin.

## 收录标准 / Inclusion criteria

- 仓库必须公开，并带有 `dsh-plugin` GitHub Topic。
- 仓库必须填写 GitHub 项目简介（description）；没有简介的仓库不予收录，补充简介后会进入[待审核队列](./data/review/pending.md)，经维护者核实后加入。
- 仓库本身必须是可安装的 DSH 插件（或明确的 DSH 生态资源），而不是另一个插件目录/榜单站点，也不是蹭 `dsh-plugin` Topic 的其他 Agent 工具或无关项目（即使带了 `dsh-plugin` Topic）。明显不符合的仓库可以登记在 `data/curated.json` 的 `excluded_repos` 中并注明原因。
- 项目说明应准确、简洁，不使用无法核实的宣传语。
- 请披露归档、许可证缺失或明显安全风险等重要状态。
- A repository must be public and carry the `dsh-plugin` GitHub topic.
- A repository must have a GitHub description set; repositories without one are excluded until a description is added, then enter the [review queue](./data/review/pending.md) and are included after the maintainer verifies them.
- The repository must be an installable DSH plugin itself (or a clear DSH ecosystem resource), not another plugin directory/leaderboard site, and not another agent tool or unrelated project riding the `dsh-plugin` topic for reach. Clear mismatches can be listed with a reason in `excluded_repos` in `data/curated.json`.
- Descriptions should be accurate and concise, without unverifiable marketing claims.
- Important status such as archival, missing license, or evident security risk should be disclosed.

## 作者自荐 / Self-promotion

「作者自荐」区是插件作者自行提交的推荐位：**不经编辑部审核**，但仍须满足上方收录标准。完整列表在 [SHOWCASE.md](./SHOWCASE.md)（最多 30 条），两个 README 首页只展示**最近 10 条**预览。规则：

- 仅限仓库作者或维护者本人提交；一个 PR 只推荐一个仓库。
- PR 描述中必须附**自荐说明**：解决什么问题、适合谁（一两句即可，中文或英文任一；不使用无法核实的宣传语）。
- 仓库须满足上方收录标准（公开、带 `dsh-plugin` Topic、已填写简介、是真实的 DSH 插件或生态资源）。
- 自荐仓库的 Star 数必须**超过 10 个**（`stargazers_count > 10`）；Star 数不足的仓库暂不收录，请先在社区积累后重新提交。CI 会在每个 PR 上自动核验，不达标的 PR 将被拒绝。
- PR 标题必须为正常编码的 UTF-8 文本；出现乱码（如 `????`）的标题一律拒绝。
- 改动方式：在 [SHOWCASE.md](./SHOWCASE.md) 的「作者自荐」与「Author showcase」两个列表**末尾各追加一行**（中英对应），并把两个 README 首页的自荐预览区同步为列表**末尾最近 10 条**；若列表已有 30 条，同时移除最旧的一条（先进先出）。不要改动其他人工维护内容，也不要提交生成文件。
- 自荐区最多保留 30 条，区满后先进先出；条目被首页精选推荐收录后会从自荐区移除、不占名额。
- 提交前本地自检：`node scripts/validate-curated.mjs`（会校验 SHOWCASE.md 与两个 README 自荐区格式和同步关系，并通过 GitHub API 确认仓库公开且带 Topic；无 token 或 API 限流时可用 `--from-snapshot` 改用本地快照校验）。PR 上的 CI 还会自动核验**标题编码**与**自荐仓库的 Star 数（>10）**，请提交前自查。

The Author showcase is a self-submission lane for plugin owners: **no editorial review**, but the inclusion criteria above still apply. The complete list lives in [SHOWCASE.md](./SHOWCASE.md) (at most 30 entries); the two README home pages show only a preview of the **10 most recent** entries.

- Only the repository owner or a maintainer may submit; one repository per pull request.
- The PR description must include a short **self-recommendation**: what problem it solves and for whom (one or two sentences, Chinese or English; no unverifiable marketing claims).
- The repository must meet the inclusion criteria above (public, `dsh-plugin` topic, description set, a real DSH plugin or ecosystem resource).
- The self-promoted repository must have **more than 10 stars** (`stargazers_count > 10`); repositories below the threshold are not listed — resubmit after the community has grown. CI verifies this on every PR and rejects submissions that fall short.
- The PR title must be properly encoded UTF-8 text; garbled titles (e.g. `????`) are rejected outright.
- How to change it: append exactly one line to the end of both the "作者自荐" and "Author showcase" lists in [SHOWCASE.md](./SHOWCASE.md) (Chinese and English), sync the home-page showcase previews in both READMEs to the **10 most recent entries** at the end of the list, and drop the oldest entry when the list already holds 30 (first in, first out). Do not touch other hand-maintained content or commit generated files.
- At most 30 entries are kept — first in, first out; entries promoted to the home page's featured picks are removed from the showcase without using a slot.
- Validate locally before submitting: `node scripts/validate-curated.mjs` (it checks the SHOWCASE.md and README showcase sections for format and sync, and confirms repositories are public and carry the topic through the GitHub API; without a token or under API rate limits, add `--from-snapshot` to validate references against the stored snapshot instead). CI on the PR additionally verifies the **title encoding** and the **self-promoted repository's star count (>10)** — check both before you submit.

## 推荐一个插件 / Recommending a plugin

首页的精选推荐（场景分组）、入门组合、热度榜摘要、最近加入（[README.md](./README.md) / [README_EN.md](./README_EN.md)）和 [SHOWCASE.md](./SHOWCASE.md) 都是人工维护页面：直接编辑对应 Markdown，并附上清晰的使用场景和理由（首页内容请同时提供中英文）。热度榜 [TOP200.md](./TOP200.md) 由 `scripts/top.mjs` 从快照生成、[CATALOG.md](./CATALOG.md) 由 `scripts/merge.mjs` 生成，两者都受 [data/approved.json](./data/approved.json) 门控（新仓库经核实后才出现），不要直接编辑；要把某仓库排除出榜单，请登记到 `data/curated.json` 的 `leaderboard_exclusions`（保留在目录、但不参与榜单排序）。分类覆盖、蹭 Topic 排除名单与榜单排除也写在 `data/curated.json`。

The home-page featured picks, starter kits, leaderboard summary, recently-joined sections ([README.md](./README.md) / [README_EN.md](./README_EN.md)), and [SHOWCASE.md](./SHOWCASE.md) are hand-maintained pages: edit the corresponding Markdown directly and include a clear use case and rationale (bilingual wording for the home pages). The leaderboard [TOP200.md](./TOP200.md) is generated by `scripts/top.mjs` from the snapshot and [CATALOG.md](./CATALOG.md) by `scripts/merge.mjs`; both are gated by [data/approved.json](./data/approved.json) (new repositories appear only after verification) — do not edit them directly. To keep a repository out of the board, register it under `leaderboard_exclusions` in `data/curated.json` (it stays in the catalog but does not rank). Category overrides, the topic-rider exclusion list, and board exclusions live in `data/curated.json`.

**提交人工页面或 `data/curated.json` 的 PR 不要提交生成文件。** `CATALOG.md`、`TOP200.md` 由 `scripts/merge.mjs` 在审核合并时生成；`data/repositories.json` 与 `data/review/` 由每日 `update-catalog` 工作流统一刷新。随 PR 附带它们会产生大量噪音 diff，并与自动提交冲突。

**Pull requests touching the hand-maintained pages or `data/curated.json` should not include generated files.** `CATALOG.md` and `TOP200.md` are generated by `scripts/merge.mjs` at review merge time; `data/repositories.json` and `data/review/` are refreshed by the daily `update-catalog` workflow. Committing them alongside a curation change creates a large noise diff and conflicts with the automated commit.

提交前本地自检 / Check your change locally before submitting:

```bash
node scripts/validate-curated.mjs
```

它会校验分类名和 `owner/repo` 引用格式，并通过 GitHub API 确认分类覆盖引用的仓库公开存在且带有 `dsh-plugin` Topic。同样的检查会在 PR 上自动运行。

It validates category names and `owner/repo` reference formats, and confirms through the GitHub API that category-override repositories are public and carry the `dsh-plugin` topic. The same check runs automatically on pull requests.

## 更新数据 / Refreshing data

流水线分为两段，约定见 [data/review/README.md](./data/review/README.md)：

1. **脚本只抓原始数据。** 每日 `update-catalog` 工作流运行 `scripts/update.mjs`：刷新 `data/repositories.json` 快照与待审核队列 `data/review/pending.*`。它不生成 `CATALOG.md`、`TOP200.md`——新仓库在人工核实前不会出现在任何用户可见页面。

```bash
node scripts/update.mjs                 # 从 GitHub 刷新快照 + 待审核队列（需 GITHUB_TOKEN）
node scripts/update.mjs --from-snapshot # 仅用现有快照刷新待审核队列
```

2. **审核后合并。** 维护者审阅 `data/review/pending.md`，把决定记入 `data/approved.json`（通过）与 `data/curated.json`（剔除 / 不进榜单），然后运行：

```bash
node scripts/merge.mjs   # 重新生成 CATALOG.md、TOP200.md 与待审核队列
node scripts/top.mjs     # 单独重新生成 TOP200.md（同样受 approved 门控）
```

原始快照保留 Topic 下的全部仓库（含未填简介和已列入排除名单的条目），过滤与门控只发生在目录页与榜单页渲染阶段，便于人工分析时看到完整数据。刚创建的仓库会晚于 `data/repositories.json` 快照，因此 `--from-snapshot` 重建的队列看不到它；这属于正常现象，用完整的 `node scripts/update.mjs` 验证即可。

The pipeline has two stages — see [data/review/README.md](./data/review/README.md) for the convention:

1. **Scripts only fetch raw data.** The daily `update-catalog` workflow runs `scripts/update.mjs`: it refreshes the `data/repositories.json` snapshot and the review queue `data/review/pending.*`. It does not generate `CATALOG.md` or `TOP200.md` — a new repository never appears on a user-facing page before a human has verified it.

```bash
node scripts/update.mjs                 # refresh snapshot + review queue from GitHub (needs GITHUB_TOKEN)
node scripts/update.mjs --from-snapshot # refresh the review queue from the stored snapshot only
```

2. **Merge after review.** The maintainer reviews `data/review/pending.md`, records decisions in `data/approved.json` (approve) and `data/curated.json` (exclude / keep out of the board), then runs:

```bash
node scripts/merge.mjs   # regenerate CATALOG.md, TOP200.md, and the review queue
node scripts/top.mjs     # regenerate TOP200.md alone (same approval gate)
```

The raw snapshot keeps every repository under the topic (including those without a description and those on the exclusion list); filtering and approval only happen when rendering the catalog and board pages, so manual analysis always sees the complete picture. A newly created repository is younger than the stored `data/repositories.json` snapshot, so it does not appear in a `--from-snapshot` rebuild — that is expected; verify with a full `node scripts/update.mjs` run instead.

## 修改生成逻辑 / Changing the generator

改动 `scripts/` 时，请在 PR 中附带 `node scripts/merge.mjs` 重新生成的 `CATALOG.md` 和 `TOP200.md`，以便审阅者看到输出变化。

When changing `scripts/`, include the `CATALOG.md` and `TOP200.md` regenerated by `node scripts/merge.mjs` in the pull request so reviewers can see how the output changes.