Skip to content

AGENTS.md

Latest commit

 

History

History
95 lines (73 loc) · 6.88 KB

AGENTS.md

File metadata and controls

95 lines (73 loc) · 6.88 KB
Raw

AGENTS.md

This file gives coding agents repository-specific guidance for working on Bilibili Evolved. Read CONTRIBUTING.md first, then use this file as the practical checklist for implementation and verification.

Project Structure

  • src/ contains the userscript core, built-in components, shared runtime APIs, settings UI, and other code shipped with the main script.
  • registry/lib/components/ contains installable components. New components should be placed under the appropriate category directory and use index.ts as the webpack entry.
  • registry/lib/plugins/ contains plugins. Use a plugin when the feature only makes sense as an extension of another component.
  • Third-party components that are meant to remain outside the main repository should be added through registry/lib/docs/third-party.ts instead of mixing external component registration with in-repo source changes.
  • dist/ and registry/dist/ are build outputs. Development branches should not keep generated dist files; release output branches such as preview, master, and master-cdn get them from CI builds.
  • Feature documentation outputs under doc/features/ are generated from metadata. Update them only when the task is explicitly about generated docs or release preparation.

Development Setup

  • The package manager is pnpm.
  • Install root dependencies with pnpm install.
  • Install registry dependencies from registry/ when building registry features.
  • Use the VS Code tasks from .vscode/tasks.json as the source of truth for local task commands when in doubt.

Common commands:

pnpm run type
pnpm run lint-check
pnpm run build-core
pnpm tsx dev-tools/dev-server/index.ts
pnpm tsx dev-tools/dev-server/command.ts sessions

The dev server serves the local userscript and registry feature URLs for browser testing. HTTP serves core outputs from disk, while registry feature URLs are virtual build-on-request outputs served from memory. WebSocket is the command and event control plane; use dev-tools/dev-server/command.ts for single-feature build, watch, stop, start-debug, stop-debug, and scaffold commands. See dev-tools/dev-server/README.md for protocol details and CONTRIBUTING.md for Tampermonkey setup details.

Component And Plugin Guidelines

  • Define components with defineComponentMetadata.
  • Follow existing plugin definitions for code under registry/lib/plugins/.
  • New components should include author metadata.
  • Component name values should be specific and camelCase. Display names and option names should clearly describe the feature instead of using generic labels.
  • If a component has an index.md, do not duplicate the same description in metadata unless the existing pattern for that component requires it.
  • Use urlInclude and urlExclude for page matching instead of manually repeating page checks in entry.
  • Keep entry focused on the work that must happen when the component starts.
  • Do not rely on the return value of entry for cleanup. Put teardown logic in unload; use reload together with unload when a component must support disable and re-enable behavior.
  • Use existing helpers such as styledComponentEntry, toggleStyle, shared core APIs, component APIs, and plugin APIs before adding new infrastructure.
  • Put fixed component styles in SCSS files instead of constructing style text in business logic. Use instantStyles, styledComponentEntry, or toggleStyle so styles are only applied when intended.
  • When writing SCSS, check shared Sass files before adding local helpers. For example, ui/_common.scss is available through @import "common" and provides common mixins such as fullscreen and centering helpers.
  • For options, follow existing defineOptionsMetadata and options patterns so defaults, labels, and validators stay close to metadata.
  • Model exclusive choices as one option, usually with an enum or dropdown, instead of multiple mutually exclusive boolean options.
  • If settings need to control CSS, prefer toggling a class on html or body and writing SCSS against that class.

Code Style

  • Follow the repository ESLint and Prettier configuration.
  • Use named exports except in files covered by the existing ESLint overrides, such as Vue single-file components and build-related files.
  • Keep control-flow bodies braced.
  • Preserve the existing TypeScript, Vue 2, and SCSS conventions around the code being changed.
  • Avoid unnecessary defensive branches, empty error handling, duplicated state, and one-off abstractions.
  • Prefer existing Bilibili API wrappers, request helpers, settings helpers, observer utilities, style utilities, and UI components over reimplementing equivalent behavior.
  • Prefer stable Bilibili APIs and existing wrappers over reading page-internal globals or framework internals when the data is available from an API.
  • Scope DOM selectors to the nearest stable parent class or page region. Avoid broad selectors that can match unrelated Bilibili UI.
  • Keep names and types aligned with behavior. If a function starts returning a broader shape, update the type and name instead of overloading a misleading contract.
  • Be careful with data units and API failure states. Do not cache a failed request as if it were a successful value, and keep byte, bit, count, id, and URL semantics explicit.

Generated Files

  • Do not manually edit generated docs or dist outputs as part of ordinary feature or bug-fix work.
  • If generated files must be updated, use the project’s existing build or docs generation workflow and include only the intended generated changes.
  • Do not commit unrelated cache, profile, local debug, or package-manager output files.

Validation

Choose validation based on the risk and scope of the change.

  • Run pnpm run type for TypeScript type checking.
  • Run pnpm run lint-check for lint validation.
  • Run pnpm run build-core for core userscript changes.
  • Run pnpm exec tsc -p dev-tools/dev-server/tsconfig.json for dev server TypeScript changes.
  • For browser-facing behavior, verify the changed feature in a real browser with the local userscript installed.
  • For API-shape or Bilibili-rollout-dependent changes, record what page or account state was actually self-tested.

The pull request workflow runs:

  1. pnpm run type
  2. pnpm run lint-check
  3. pnpm run build-core
  4. install dependencies in registry/
  5. pnpm run build-features

When a change affects page behavior, also check the browser console for new runtime errors and test the relevant Bilibili page type, such as video, bangumi, live, feeds, space, settings panel, or the affected component area.

Branches And Commits

  • Use preview-features as the base for new features.
  • Use preview-fixes as the base for bug fixes.
  • Commit messages only need to clearly describe the change; the repository does not require a strict conventional commit format.
  • Do not create release tags, push release branches, or perform release steps unless the task is explicitly about releasing.