Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
106 lines (72 loc) · 13.7 KB

CONTRIBUTING.md

File metadata and controls

106 lines (72 loc) · 13.7 KB
Raw

贡献指南 / Contributing

感谢你帮助维护 Awesome DSH Plugin。

Thank you for helping maintain Awesome DSH Plugin.

收录标准 / Inclusion criteria

  • 仓库必须公开，并带有 dsh-plugin GitHub Topic。
  • 仓库必须填写 GitHub 项目简介（description）；没有简介的仓库不予收录，补充简介后会进入待审核队列，经维护者核实后加入。
  • 仓库本身必须是可安装的 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 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（最多 30 条），两个 README 首页只展示最近 10 条预览。规则：

  • 仅限仓库作者或维护者本人提交；一个 PR 只推荐一个仓库。
  • PR 描述中必须附自荐说明：解决什么问题、适合谁（一两句即可，中文或英文任一；不使用无法核实的宣传语）。
  • 仓库须满足上方收录标准（公开、带 dsh-plugin Topic、已填写简介、是真实的 DSH 插件或生态资源）。
  • 自荐仓库的 Star 数必须超过 10 个（stargazers_count > 10）；Star 数不足的仓库暂不收录，请先在社区积累后重新提交。CI 会在每个 PR 上自动核验，不达标的 PR 将被拒绝。
  • PR 标题必须为正常编码的 UTF-8 文本；出现乱码（如 ????）的标题一律拒绝。
  • 改动方式：在 SHOWCASE.md 的「作者自荐」与「Author showcase」两个列表末尾各追加一行（中英对应）即可；若列表已有 30 条，同时移除最旧的一条（先进先出）。两个 README 首页的自荐预览区由脚本自动生成，请不要手工同步、也不要编辑（区域由 <!-- dsh:showcase:start/end --> 标记界定）——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 (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 (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 <!-- dsh:showcase:start/end -->): 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_EN.md）和 SHOWCASE.md 都是人工维护页面（首页的生态全景、热度榜 Top 50 与自荐预览三个区块由 scripts/merge.mjs 生成，勿手工编辑）：直接编辑对应 Markdown，并附上清晰的使用场景和理由（首页内容请同时提供中英文）。热度榜 TOP200.md 由 scripts/top.mjs 从快照生成、CATALOG.md 与 catalog/ 下的各分类分册由 scripts/merge.mjs 生成，两者都受 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_EN.md), and 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 is generated by scripts/top.mjs from the snapshot and CATALOG.md plus the per-category volumes under catalog/ by scripts/merge.mjs; both are gated by 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（目录索引）、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 (the index), catalog/*.md (the per-category volumes), 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:

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：

  1. 脚本只抓原始数据。 每日 update-catalog 工作流运行 scripts/update.mjs：刷新 data/repositories.json 快照与待审核队列 data/review/pending.*。它不生成 CATALOG.md、catalog/ 分册、TOP200.md——新仓库在人工核实前不会出现在任何用户可见页面。
node scripts/update.mjs                 # 从 GitHub 刷新快照 + 待审核队列（需 GITHUB_TOKEN）
node scripts/update.mjs --from-snapshot # 仅用现有快照刷新待审核队列
  1. 审核后合并。 维护者审阅 data/review/pending.md（先看「Star 异常增长」告警节：一天内 +100★ 或突然窜上榜单的仓库要做增强分析，热度并非来自 DSH 插件本身时写入 leaderboard_exclusions），把决定记入 data/approved.json（通过）与 data/curated.json（剔除 / 不进榜单），然后运行：
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 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.
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
  1. 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:
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.