AGENTS.md · diff
git:20260824.e161515 to git:20260825.2b28c93
10 added, 7 removed. Audit A to A.
# Repository instructions
This repository is the **plugin catalog**: the awesome list (`catalog/plugins/*.json`),
the plugin submission review/merge workflow, and the generated README directories. The
DSH 1024Store application — the deepseek1024.com site, its Worker, and the `dsh1024` npm
package — lives in [imsai-sh/dsh-1024store](https://github.com/imsai-sh/dsh-1024store).
## The submission gate is the product
- The public PR gate accepts changes to `catalog/plugins/*.json` only; everything else is
maintainer-bypass territory. `scripts/review-plugin-submission.mjs` is the trusted
reviewer: it always runs from the base branch and treats the submitted checkout as data.
- The `allow-unsafe-pr-checkout: true` flag in `.github/workflows/plugin-review.yml` must
never be removed — without it every fork PR fails silently with no comment.
- Verdicts are three-state: exactly one new entry on a non-draft PR auto-merges;
updates/removals go green but wait for a maintainer; anything else fails with a comment.
A failed review never closes the PR.
- `skills/submit-dsh-plugin/` must stay in lockstep with the live submission spec: any
change to CONTRIBUTING.md, the schema or categories, the PR template, the review
workflow or scripts, or the merge flow updates the skill, its references, scripts,
tests, and README install instructions in the same change.
## Generated files
- `README.md` and `catalog/README.md` are bot-generated by `scripts/build-readme.mjs`.
Never hand-edit them; change the generator and run `npm run readme:build`. The
catalog-sync workflow regenerates and force-pushes them via the `CATALOG_DEPLOY_KEY`
deploy key, which is also the documented branch-protection bypass.
- The README hero screenshot lives on the orphan `assets` branch of THIS repository,
force-pushed by the catalog-sync workflow. Do not repoint it elsewhere.
- The WeChat group QR image is `docs/assets/wechat-group.jpg` in this repository (the
site serves its own copy from the other repo).
## Cross-repo contracts (no CI spans both repositories)
The deployed Worker's source lives in dsh-1024store; these pairs drift silently, so check
the other repo whenever you touch one side:
- - `scripts/lib/catalog-entry.mjs` id validation ↔ `apps/web/worker/lib/plugin-id.ts` and
- the sync endpoint's `ENTRY_ID`/`ENTRY_KEYS` in `apps/web/worker/app.ts` (dsh-1024store).
+ - `scripts/lib/catalog-entry.mjs` id validation ↔ `web/worker/lib/plugin-id.ts` and
+ the sync endpoint's `ENTRY_ID`/`ENTRY_KEYS` in `web/worker/app.ts` (dsh-1024store).
Drift means a PR passes review here but the sync endpoint rejects it there.
- - `catalog/categories.json` here is the source of truth; dsh-1024store carries a vendored
- mirror bundled into the Worker. A category change lands in both repositories and only
- reaches the site when that Worker is redeployed.
+ - Categories are data, not vendored code. `catalog/categories.json` here stays the human
+ source of truth — submission validation and README generation read it — and the
+ catalog-sync workflow posts the full ordered list to the Worker in the `categories`
+ field of `POST /api/v1/catalog/sync`, which reconciles its `catalog_categories` D1 table
+ to exactly that list. A category change ships from this repository alone; no coordinated
+ deploy of dsh-1024store is needed.
- `scripts/review-plugin-submission.mjs` `classifyGitInstall` ↔
- `apps/web/worker/lib/install-methods.ts` (dsh-1024store).
+ `web/worker/lib/install-methods.ts` (dsh-1024store).
- `scripts/build-readme.mjs`'s unclassified label ↔ `UNCLASSIFIED_CATEGORY` in
- `apps/web/worker/lib/categories.ts` (dsh-1024store).
+ `web/worker/lib/categories.ts` (dsh-1024store).
- `scripts/sync-catalog.mjs` POSTs to `https://deepseek1024.com/api/v1/catalog/sync` with
`Bearer CATALOG_SYNC_TOKEN`. The token value must match between this repo's Actions
secret and the Worker secret in dsh-1024store; rotating it is a coordinated change.
- This repo's CI (catalog-sync) reads the live site: `npm run readme:build` pages
`/api/v2/plugins`, and the screenshot step captures the deployed homepage. A bad deploy
from dsh-1024store turns catalog-sync red or stale — that is expected, not a bug here.
## Permanent URLs
- `docs/install-analytics.md` is a permanent redirect stub: already-published `dsh1024`
versions print that URL in their telemetry notice. Never delete or rename it.
- The skill install slug `imsai-sh/awesome-deepseek-harness-plugins` and the store's own
plugin id (same string) are public identity. The id keys live D1 rows and
`/api/v1/self/update` in the other repo; leave the catalog self-entry
(`catalog/plugins/imsai-sh--awesome-deepseek-harness-plugins.json`) byte-stable unless
a coordinated migration is planned.