Files
v2rayA/AGENTS.md
T
Zakk 154f016fdd docs: a contributing guide, an agents file, a pull request template and issue forms
The repository had six markdown issue templates, no pull request template and
no guide, so a report rarely said which version it was and a pull request
rarely said what its author had run.

The issue templates become four GitHub forms, English and Chinese kept apart,
asking for the version and why it is not the latest, the system and install
method, the transparent proxy mode, the steps, the logs and the person who
answers for the report. Usage questions go to Discussions through config.yml,
and blank issues are off. The pull request template, also in two languages,
asks for the change in the author's own words, what was executed and observed,
and a checklist of what the review expects; two of its boxes are true only of
someone who checked the list without reading it, or of an agent submitting
without human review, and checking either one closes the pull request.

CONTRIBUTING.md says where the code lives, what to run before opening a pull
request, that all six locales change together and that no AI attribution goes
into the history. AGENTS.md tells an assistant the same in its own terms, with
the traps that cost a review round: the web files the service embeds, the
locale and documentation directories that are named differently, the escaped
@ in a locale string, the Material colour and type tokens, and what in core/
belongs to v2rayA rather than to xray-core.
2026-09-22 21:54:12 +10:00

4.1 KiB

AGENTS.md

Instructions for a coding assistant working in this repository. A human owns every change you produce: your output is a draft until they have read it, run it, and can answer for it. CONTRIBUTING.md applies to you as written.

What the repository is

service/ is the Go service (API, settings database, transparent proxy, the core config it generates). core/ is v2raya_core, a fork of xray-core carrying the DNS module, the in-core TUN and the extra protocols. gui/ is the web interface: Vue 3, Vuetify 4 on Material 3, vue-i18n, Vitest. install/ is packaging. The service embeds the built web files.

Before you change anything

Read the code you are about to change and the code that calls it. Reuse the components and helpers that exist and follow the neighbouring file's conventions. Do not introduce a parallel implementation or a second convention.

What the change must satisfy

(cd gui     && yarn lint && yarn typecheck && yarn i18n-check && yarn test && yarn build)
(cd service && go build ./... && go vet ./... && go test ./...)
(cd core    && go build ./... && go vet ./...)

Run them yourself, from the repository root, and then exercise the change: for the service, start v2raya and use the feature; for the interface, open the page and use what changed. A description of behaviour you did not observe is worth nothing to the review. TestResolvHijackerConcurrentResetRemove fails for a non-root user; that one is known.

Visible text lives in gui/src/locales/: update all six locales together. yarn i18n-check compares key sets, not whether a translation followed a wording change. The in-app documentation under gui/src/docs/ has the same six.

Traps that cost a review round

  • go build ./... in service/ fails with pattern web: no matching files found while service/server/router/web is empty. yarn --cwd gui build writes to web/ at the root; ./build.sh copies it across.
  • The locale files are en, zh, fa-ir, ko, pt-br, ru; the documentation directories are en, zh, fa, ko, pt, ru. The names differ. Both sets change together.
  • A literal @ in a locale string must be written {'@'}; vue-i18n reads a bare one as a linked message.
  • A key that i18n-check cannot see statically belongs to a prefix listed in gui/scripts/i18n-check.mjs; add the prefix rather than the key.
  • Colours come from the Material scheme: rgb(var(--v-theme-<role>)). Do not write a hex literal in a component; it cannot follow the theme.
  • Type comes from the scale in gui/src/theme/typography.scss (md3-title-large and the rest), which uses weights 400 and 500; do not add 700.
  • core/ is a fork of xray-core. v2rayA's own code is core/dns, core/hint and core/main; leave the rest to upstream. After editing a .proto under core/hint/proxy, regenerate from the module root (protoc --go_out=. --go_opt=paths=source_relative hint/proxy/<name>/config.proto) so the descriptor keeps its path.
  • Read a command's exit code; do not infer success from the end of its output. eslint prints its errors above the summary line.

Code in this repository

Match the file you are editing: its comment density, its naming, its idiom. Comments state what is not evident from the code — a reason, a constraint, a protocol quirk — and stop there; no comment repeats what the next line says.

Reach for what is already there before adding anything: a dependency the module already has, a helper in service/common or gui/src/lib, a Vuetify component before a hand-written one. A new dependency needs a reason a reviewer would accept.

What not to do

  • Do not sign your work: no model Co-Authored-By trailer, no AI signature, no generated-by marker, in a comment, a commit message or pull request text.
  • Do not touch code the change does not require: no reformatting, no renaming, no regenerated lockfiles.
  • Do not present a guess as a result. If you did not run it, say so.
  • Do not open or comment on an issue or a pull request on your own, and do not fill in the field that names who answers for it. The human submits, and answers for what is submitted.