# 贡献指南 / 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」两个列表**末尾各追加一行**(中英对应)即可;若列表已有 30 条,同时移除最旧的一条(先进先出)。**两个 README 首页的自荐预览区由脚本自动生成,请不要手工同步、也不要编辑**(区域由 `` 标记界定)——SHOWCASE.md 变更合入 main 后,`refresh-showcase` 工作流会立即刷新预览(本地可跑 `node scripts/showcase-preview.mjs`),审核合并时 `scripts/merge.mjs` 也会一并生成。不要改动其他人工维护内容,也不要提交生成文件。 - 自荐区最多保留 30 条,区满后先进先出;条目被首页精选推荐收录后会从自荐区移除、不占名额。 - 提交前本地自检:`node scripts/validate-curated.mjs`(会校验 SHOWCASE.md 与两个 README 自荐区格式和同步关系,并通过 GitHub API 确认仓库公开且带 Topic;无 token 或 API 限流时可用 `--from-snapshot` 改用本地快照校验)。PR 上的 CI 还会自动核验**标题编码**与**自荐仓库的 Star 数(>10)**,请提交前自查。自荐预览区**滞后**于 SHOWCASE.md 属预期状态(合入后由 `refresh-showcase` 工作流刷新),本地与 PR 校验只提示警告、不会失败;仅当预览与 SHOWCASE.md 的任何连续片段都对不上(手改/漂移)时才报错。 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), and drop the oldest entry when the list already holds 30 (first in, first out). **The home-page showcase previews are generated by scripts — do not sync or edit them by hand** (the region is delimited by ``): once your SHOWCASE.md change lands on main, the `refresh-showcase` workflow refreshes the previews immediately (locally: `node scripts/showcase-preview.mjs`), and `scripts/merge.mjs` regenerates them at review-merge time too. 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. A showcase preview that **lags** SHOWCASE.md is the expected pre-merge state (the `refresh-showcase` workflow refreshes it right after merge) — local and PR validation only warn about it; validation fails only when the preview matches no contiguous stretch of SHOWCASE.md (a hand edit or drift). ## 推荐一个插件 / Recommending a plugin 首页的精选推荐(场景分组)、入门组合、最近加入([README.md](./README.md) / [README_EN.md](./README_EN.md))和 [SHOWCASE.md](./SHOWCASE.md) 都是人工维护页面(首页的生态全景、热度榜 Top 50 与自荐预览三个区块由 `scripts/merge.mjs` 生成,勿手工编辑):直接编辑对应 Markdown,并附上清晰的使用场景和理由(首页内容请同时提供中英文)。热度榜 [TOP200.md](./TOP200.md) 由 `scripts/top.mjs` 从快照生成、[CATALOG.md](./CATALOG.md) 与 `catalog/` 下的各分类分册由 `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, recently-joined sections ([README.md](./README.md) / [README_EN.md](./README_EN.md)), and [SHOWCASE.md](./SHOWCASE.md) are hand-maintained pages (the ecosystem mindmap, the Top 50 leaderboard, and the showcase preview are generated by `scripts/merge.mjs` — do not edit them by hand): 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) plus the per-category volumes under `catalog/` 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`. **PR 里的生成文件分两类处理。** `CATALOG.md`(目录索引)、`catalog/*.md`(各分类分册)、`TOP200.md` 是**目录页**:只改人工页面(README、SHOWCASE.md 等)的 PR 不要附带它们;但改动 `data/approved.json` / `data/curated.json` 且会影响目录归属的 PR(例如新增分类覆盖或排除)**必须**附上 `node scripts/merge.mjs` 重新生成的目录页——CI 会用 `merge.mjs --check` 核对「哪个仓库在哪一册」,只比对归属,不比对每日变动的星数和日期,所以 PR 跨过每日快照也不会误报。`merge.mjs` 同时会改写 `data/review/pending.*`,提交前请用 `git checkout origin/main -- data/review` 还原。市场 feed(`market-catalog.json` / `packages.json`)由 `publish-npm-feed` 工作流在发布时生成,不提交到仓库,PR 不要附带;`data/repositories.json` 与 `data/review/pending.*` 是每日流水线文件,一律不接受。PR 的 CI 会做**路径白名单**校验:只允许 SHOWCASE.md、README.md / README_EN.md、`data/curated.json`、`data/approved.json`、`data/packages.json`、`data/leaderboard-descriptions-zh.json`、`scripts/`、`.github/` 与仓库元文件,外加上述规则内的生成文件(改动 `scripts/` 的 PR 可附带任何生成文件,用于展示脚本输出变化);其余路径(如自创的 `data/plugins/*.yml`)会被直接拒绝——那不是本仓库的提交通道。维护者可给 PR 打 `ci: allow-any-path` 标签跳过路径检查(打标签会自动重跑校验)。 **Generated files in pull requests come in two kinds.** `CATALOG.md` (the index), `catalog/*.md` (the per-category volumes), and `TOP200.md` are **catalog pages**: a PR that only touches hand-maintained pages (README, SHOWCASE.md, …) must not include them, but a PR that changes `data/approved.json` / `data/curated.json` in a way that moves catalog membership (a new category override or exclusion, say) **must** include the pages regenerated by `node scripts/merge.mjs` — CI checks "which repository sits in which volume" with `merge.mjs --check`, comparing membership only, not the star counts and dates the daily snapshot moves, so a PR that stays open across a snapshot refresh does not fail spuriously. `merge.mjs` also rewrites `data/review/pending.*`; restore those with `git checkout origin/main -- data/review` before committing. The market feed (`market-catalog.json` / `packages.json`) is generated at release time by `publish-npm-feed` and never committed — leave it out of PRs; `data/repositories.json` and `data/review/pending.*` are daily-pipeline files and are never accepted. The PR CI enforces a **path whitelist**: only SHOWCASE.md, README.md / README_EN.md, `data/curated.json`, `data/approved.json`, `data/packages.json`, `data/leaderboard-descriptions-zh.json`, `scripts/`, `.github/`, and repo meta files are accepted, plus generated files under the rules above (a PR that changes `scripts/` may include any generated file to show how the output changes); any other path (e.g. a made-up `data/plugins/*.yml`) is rejected outright — that is not a submission lane in this repository. Maintainers may label a PR `ci: allow-any-path` to skip the path check (labeling re-runs the check automatically). 提交前本地自检 / 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`、`catalog/` 分册、`TOP200.md`——新仓库在人工核实前不会出现在任何用户可见页面。 ```bash node scripts/update.mjs # 从 GitHub 刷新快照 + 待审核队列(需 GITHUB_TOKEN) node scripts/update.mjs --from-snapshot # 仅用现有快照刷新待审核队列 ``` 2. **审核后合并。** 维护者审阅 `data/review/pending.md`(**先看「Star 异常增长」告警节**:一天内 +100★ 或突然窜上榜单的仓库要做增强分析,热度并非来自 DSH 插件本身时写入 `leaderboard_exclusions`),把决定记入 `data/approved.json`(通过)与 `data/curated.json`(剔除 / 不进榜单),然后运行: ```bash node scripts/merge.mjs # 重新生成 CATALOG.md、catalog/ 分册、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` (**start with the Star-growth alerts section**: extra analysis for repos that gained ≥100 stars in a day or leapt onto the board; if the popularity is not from the DSH plugin itself, add `leaderboard_exclusions`), 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. ## 编辑精选与订阅 `data/featured.json` 是编辑精选(顺序 + 中文推荐语)的人工维护来源:每个条目必须填写 `full_name` 和非空 `description`(按目录描述上限清洗),并在 `data/packages.json` 中有安装映射。修改文案时同步更新 `updated_at`,运行 `node scripts/validate-market-catalog.mjs` 校验投影;发布由 `publish-npm-feed` 工作流打包。自动刷新的改名同步会保留这里的引用与文案。 这份数据有两个去处:① 市场目录的 `featured` 块(客户端「精选」页签)——卡片优先采用订阅插件的身份与安装目标,文案用这里的推荐语;即使精选仓库被榜单排除(如 `tw93/Mole`、`bruc3van/bruce-md2word`),也能凭订阅插件或 AI 核对安装出现在精选里;② 官方 format-1 索引的 `featured` 标签(「编辑推荐」)——索引报告核对期望仓库数与实际打标插件数。 编辑推荐来源中的仓库数与订阅插件数分别统计:`expected_repository_count` 是推荐来源的仓库数(当前 50),一个仓库可发布多个合格插件,线上插件数可以多于仓库数。未通过来源核验(tarball 体积上限、private 包、同名重复、无安装映射等)的精选仓不会进索引,但仍在市场「精选」页签中显示(没有一键目标时走 AI 核对安装),因此索引里的 `featured` 插件数可能少于 50——这是可见的差额,不静默改动精选。更新精选时同步维护 `data/featured.json` 与安装映射,并验证市场目录、官方订阅和 npm 分发结果;只改 README 不代表推荐数据已发布。