webapp — React 目录站模板

SHA-256: 7632354a1df39de3da244b5796a47381baec6c1a524664441ddb0e68b5f5fe3e

2026-10-01T04:09:54.042Z

# Webapp

![License](https://img.shields.io/github/license/agents-repo/webapp) ![PR baseline checks](https://github.com/agents-repo/webapp/actions/workflows/pr-baseline.yml/badge.svg?event=pull_request) [![Quality gate status](https://sonarcloud.io/api/project_badges/measure?project=agents-repo_webapp&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=agents-repo_webapp) ![Release](https://img.shields.io/github/v/release/agents-repo/webapp?sort=semver) ![Stars](https://img.shields.io/github/stars/agents-repo/webapp?style=flat) <!-- markdownlint-disable-line MD013 -->

![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-FE5196?style=flat&logo=conventionalcommits&logoColor=white) ![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg) ![Top language](https://img.shields.io/github/languages/top/agents-repo/webapp) ![Node.js](https://img.shields.io/badge/Node.js-24-339933?style=flat&logo=nodedotjs&logoColor=white) ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white) ![React](https://img.shields.io/badge/React-19-61DAFB?style=flat&logo=react&logoColor=black) ![Vite](https://img.shields.io/badge/Vite-646CFF?style=flat&logo=vite&logoColor=white) [![site agents-repo.org](https://img.shields.io/badge/site-agents--repo.org-blue?style=flat)](https://agents-repo.org) <!-- markdownlint-disable-line MD013 -->

---

Web interface for browsing, searching, and downloading agents and flows from
the registry.

## Purpose

This repository contains the frontend application for the agents registry.
It is a Vite + React + TypeScript project with Bootstrap-based styling and an
AI-first contributor workflow.

## Stack

- React 19
- TypeScript
- Vite
- Bootstrap, SCSS, React Bootstrap, and Font Awesome React
- Bootstrap 5.3 color modes with a header dropdown for light, dark, and auto
- PWA service worker runtime caching through `vite-plugin-pwa`
- In-app 24h registry JSON/markdown cache using IndexedDB (`idb`) plus a
  lightweight in-memory LRU; preferences stay in localStorage
- ESLint for code linting
- markdownlint for Markdown quality checks

## Getting Started

Use the pinned toolchain where possible:

- Node.js 24.x, with `.nvmrc` pinned to `24.18.0`
- npm 12.x, with `packageManager` pinned to `[email protected]`

Install dependencies and start the app:

```bash
npm install
npm run dev
```

## Common Commands

```bash
npm run env:check
npm run lint:all
npm run test
npm run test:watch
npm run test:e2e
npm run typecheck
npm run build
npm run build:pages
npm run test:crawl-files
npm run slides:check
```

Accessibility-focused checks (local only, not in PR baseline CI):

```bash
npm run test:a11y
npm run a11y:ci
```

See [docs/accessibility.md](docs/accessibility.md) for patterns and the public
statement at `/accessibility`.

Public privacy notices: `/privacy/` (English default) and localized paths such as
`/pt-br/privacy/`. Legacy `/privacidade` redirects to pt-BR.
See [docs/privacy.md](docs/privacy.md) for consent, GTM, and contributor guidance.
See [docs/i18n.md](docs/i18n.md) for locale routing.

See [docs/seo.md](docs/seo.md) for search and social-preview metadata patterns.

See [docs/testing.md](docs/testing.md) for unit test conventions, coverage map,
and the prioritized test backlog. Playwright E2E (local-only) is documented in
[docs/e2e-testing.md](docs/e2e-testing.md).

## Registry Source Configuration

The app resolves the registry source URL with runtime-first precedence:

1. Browser runtime override saved from Website settings in the header (cog icon)
2. Build-time Vite `VITE_...` environment variables
3. Repository defaults

Build-time variables remain:

- `VITE_REGISTRY_REPOSITORY_URL`: source URL input. This may be a GitHub
  repository URL or a direct source endpoint URL. Default:
  `https://registry.agents-repo.org?ref=v2.x`
- `VITE_REGISTRY_BASE_URL`: optional direct base URL override for fetches.
  If omitted, the source URL is used as the base URL (GitHub URLs are normalized to raw content).
- `VITE_REGISTRY_INDEX_PATH`: relative index path. Default:
  `packages/index.json`
- `VITE_REGISTRY_GITHUB_REPOSITORY_URL`: GitHub repository URL used for
  **View on GitHub** on package detail pages. Default:
  `https://github.com/agents-repo/registry/tree/v2.x`

GitHub repository URLs and `/tree/<ref>` or `/blob/<ref>` URLs are normalized
to `raw.githubusercontent.com`. When a tree/blob URL includes additional
repository path segments (for example `/tree/main/packages`), only the first
ref segment is used for derivation. To use slash refs, provide an explicit ref
form such as `/tree/refs/heads/feature/foo`.

With defaults, the configured source uses the `v2.x` major-version line alias.
At catalog load time this resolves to the latest stable release tag (for example
`v2.0.0`). Before resolution, the index URL is composed as:

`https://registry.agents-repo.org/packages/index.json?ref=v2.x`

Query parameters on the source URL are preserved when composing the index URL,
except when GitHub URLs are normalized to raw content URLs.

Major-version line refs such as `1.x` or `v1.x` can be used in proxy `?ref=`
values or GitHub `/tree/<ref>` URLs. The app resolves these aliases to the latest
stable release tag from the registry repository using registry-proxy `GET /tags`
when the fetch source is a proxy URL, or the GitHub tags API as a fallback for
GitHub-only source URLs. Tag selection uses [`semver`](https://www.npmjs.com/package/semver).
Resolved refs are shown in website settings and catalog status notes as
`v2.x → v2.0.0`.

At runtime, users can set custom registry URLs in the header settings modal:

- **Registry base URL override** — catalog fetching (GitHub URLs auto-normalized,
  raw URLs and other base URLs used as-is). Empty resets to configured defaults.
- **GitHub repository URL** — **View on GitHub** on package detail pages; opens
  `github.com/.../tree/{ref}/packages/{namespace}/{package-id}`. Independent
  from the fetch override. Empty resets to `VITE_REGISTRY_GITHUB_REPOSITORY_URL`.

Fetch defaults (proxy) and browse defaults (GitHub repository) serve different
purposes. A proxy fetch URL cannot be converted into a GitHub tree browse link.

Note: URL format flexibility does not change the expected registry layout. The
resolved base URL must expose a compatible registry structure, including a
valid `packages/index.json` (or the configured `VITE_REGISTRY_INDEX_PATH`)
that matches the app's registry catalog contract.

## Caching and Offline Behavior

Registry catalog loading now uses two coordinated cache layers:

- App-layer cache contract:
  - 24h freshness window for `index.json` and package `detail.json`
  - Fresh cache is used before network fetches
  - A package index or detail URL missing from that fresh cache triggers one
    forced catalog reload (re-resolve `v2.x`, bypass tag cache) before
    **Package not found**
  - Website settings include **Clear cache and reload catalog** to reset the
    IndexedDB registry stores (`catalog`, `package-detail`, `tags`,
    `chat-manifest`, `chat-markdown`) and force a catalog reload (does
    not purge Cloudflare proxy cache or the browser HTTP `max-age=300` cache)
  - If remote refresh fails, stale cached catalog is used when available
  - If refresh fails and no cached catalog exists, the app shows an error alert
- Service worker runtime cache:
  - HTML document navigations use NetworkFirst (1-day offline fallback)
  - Same-origin static assets use StaleWhileRevalidate (7 days)
  - HTTP `Cache-Control` stays GitHub Pages defaults (typically `max-age=600`)

This keeps registry freshness decisions in app logic while still improving
offline resilience for app HTML and assets.

## GitHub CLI

This repository prefers GitHub communication through `gh` CLI for issue and
pull request workflows.

Verify availability and authentication:

```bash
gh --version
gh auth status
```

If `gh auth status` reports no login, run `gh auth login`.

Common commands used in this workflow:

```bash
# inspect issue scope
gh issue view <number> --repo agents-repo/webapp

# open a draft PR with template-aligned content
gh pr create --repo agents-repo/webapp --draft --title "..." --body-file <file>
```

See `.github/CONTRIBUTING.md` **Required Workflow** for the canonical policy
(issue → branch → push → draft PR before implementation).

Issue categories in this repository are:

- bug or inconsistency
- spec change
- feature proposal
- task or chore

Documentation-only work uses the task/chore issue category and a
`docs/<issue-number>-<slug>` branch name.

## Release Workflow

- Release versions follow Semantic Versioning `MAJOR.MINOR.PATCH` sourced from
  <https://semver.org>.
- Pushes to `main` (post-merge integration via pull request, not direct push)
  run release validation checks and then execute `semantic-release`.
- A release is published only when commit history includes releasable changes
  per the commit-to-version mapping below.
- `workflow_dispatch` remains available for operational checks.
- `dry_run` defaults to `true`; set `dry_run=false` only when intentionally
  running a manual publish from `main`.
- Git tags use `v<MAJOR>.<MINOR>.<PATCH>` format.

### Commit-To-Version Mapping

- `type!:` or `BREAKING CHANGE:` => `MAJOR`
- `feat:` => `MINOR`
- `fix:`, `perf:`, and `revert:` => `PATCH`

Commit types not listed above do not trigger an automated release.

### GitHub Pages

App-source merges to `main` deploy the built webapp to:

- <https://agents-repo.org/>

The **Deploy Webapp** workflow publishes production builds. The **Release**
workflow handles SemVer tags and GitHub Releases only. See
[docs/deployment.md](docs/deployment.md) for PAT setup, redeploy, and rollback
instructions.

## IDE Setup

This repository commits IDE instruction mirrors and registry workflow packages
so contributors get agent guidance on clone without manual setup.

### Project guidelines

| Install target | Path |
| --- | --- |
| Cursor | `.cursor/rules/agents-webapp.mdc` (canonical) |
| GitHub Copilot | `.github/copilot-instructions.md` (generated) |
| Claude Code | `CLAUDE.md` |
| OpenAI Codex | `AGENTS.md` |

Regenerate after editing `.cursor/rules/`:

```bash
npm run sync:ide-instructions
```

Do not edit generated mirror files directly.

### Registry workflow packages (org hub)

This repository does not commit `agents.json`. Shared planning/review packages
install in [agents-repo/.github](https://github.com/agents-repo/.github). Open
[agents-repo.code-workspace](https://github.com/agents-repo/.github/blob/main/agents-repo.code-workspace)
from the `.github` sibling clone. See
[org-workspace-and-agents.md](https://github.com/agents-repo/.github/blob/main/docs/org-workspace-and-agents.md)
and [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#registry-workflow-packages-org-hub).

## Organization

This app is the public UI for the agents-repo platform. The catalog lives in
[registry](https://github.com/agents-repo/registry); default fetches go through
[registry-proxy](https://github.com/agents-repo/registry-proxy). Install packages
with [cli](https://github.com/agents-repo/cli). See the organization [Ecosystem
overview](https://github.com/agents-repo/.github/blob/main/docs/ecosystem.md)
for diagrams and contributor flows.

## Docs and repository pages

For user guides and cross-repo documentation, see
[agents-repo.org/docs/](https://agents-repo.org/docs/).
For this repository's overview on the public site, see
[agents-repo.org/repositories/webapp/](https://agents-repo.org/repositories/webapp/).

When you change a user-facing or contributor workflow in this
repository, update the corresponding page(s) in
[agents-repo/webapp](https://github.com/agents-repo/webapp) under
`src/content/docs/` in the same PR or an immediate follow-up.

## Project Docs

- Development workflow: [docs/development.md](docs/development.md)
- Architecture map: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- Testing guide: [docs/testing.md](docs/testing.md)
- Deployment and Pages: [docs/deployment.md](docs/deployment.md)
- Presentation slides: [docs/slides/README.md](docs/slides/README.md)
- AI collaboration guidance: [docs/ai-collaboration.md](docs/ai-collaboration.md)
- Styling and technology decisions: [docs/styling-and-technology.md](docs/styling-and-technology.md)
- Architecture and DDD decision: [docs/architecture/ddd-decision.md](docs/architecture/ddd-decision.md)
- Accessibility guide: [docs/accessibility.md](docs/accessibility.md)
- Privacy and analytics guide: [docs/privacy.md](docs/privacy.md)
- SEO guide: [docs/seo.md](docs/seo.md)
- Public accessibility statement: `/accessibility` route in the deployed app
- Public privacy policies: locale-prefixed `/privacy/` routes (see [docs/i18n.md](docs/i18n.md))
- Contributor guide: [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md)
- GitHub Copilot project instructions:
  [.cursor/rules/agents-webapp.mdc](.cursor/rules/agents-webapp.mdc)

## Automation

- **PR Baseline Checks** — lint, typecheck, test, and Pages build on pull requests.
- **Deploy Webapp** — lint, test, build, and publish `dist/` to
  `agents-repo.github.io` on app-source pushes to `main`.
- **Release** — validation plus `semantic-release` on pushes to `main`
  (versioning only; no Pages deploy).
- **Pages Deploy** — manual redeploy or rollback of a specific `v*` release tag.