DpsManagerServer/旧的java项目/AGENTS.md

AGENTS.md for this repository

Purpose

• This document guides agent-like contributors (human or AI) on how to build, lint, test, and style the codebase.
• It also captures preferences or constraints used by the team and by automated agents operating in this repo.

Scope

• Build, test, and lint commands for common environments (Node/TS, Python, Go, Rust, Java).
• Code style guidelines: imports, formatting, types, naming, error handling, tests, and documentation.
• Cursor rules and Copilot rules inclusion if present in the repo.
• How to handle running a single test and how to extend tests locally.

1. Quick start: common commands

• Build (preferred entry point):
  • Node/TypeScript: npm run build (or yarn build)
  • Python: python -m build or your project-specific build script
  • Go: go build ./...
  • Rust: cargo build
• Lint:
  • Node/TypeScript: npm run lint (or yarn lint)
  • Python: ruff check . | flake8 or your project’s linter
  • Go: golangci-lint run
  • Rust: cargo clippy
• Test:
  • Node/TS: npm test (or yarn test)
  • Python: pytest
  • Go: go test ./...
  • Rust: cargo test
• Note: If your repo uses a mixed tech stack, prefer using the language-specific script in package.json or equivalent courier scripts.

2. Run a single test (typical patterns)

• Node / Jest
  • Run a specific test by name: npm test -- -t "should render the component"
  • Run a specific file: npm test -- path/to/file.test.js
• Python / Pytest
  • Run tests matching a keyword: pytest -k "test_name_substring" -q
  • Run a specific file: pytest tests/test_module.py -q
• Go
  • Run a single test by name: go test -run TestName ./...
• Rust / Cargo
  • Exact test: cargo test -- --exact TestName
  • Run a file-like subset: cargo test -- 'pattern'
• Java / Maven or Gradle
  • Maven: mvn -Dtest=MyTest#testMethod test
  • Gradle: ./gradlew test --tests "com.example.MyTest.testMethod"

3. Code style guidelines <A) Imports and modules>

• Group imports into three blocks: standard library, third-party, and first-party modules.
• Order blocks alphabetically within each group; separate blocks with a newline.
• Avoid wildcard imports; prefer explicit imports.
• For TS/JS, prefer absolute/alias imports over relative when it improves clarity.

<B) Formatting and tooling>

• Use the project’s formatter (Prettier, gofmt, black, etc.) with the configured settings.
• Respect the repository’s line length (commonly 100-120 chars). Break long lines at logical points.
• Use semicolons consistently if the project enforces them; otherwise adhere to the established style.
• Enable and respect lint rules; fix all autofixable issues during code edits.

<C) Types and APIs>

• In TypeScript, enable strict type checking; prefer interfaces for public APIs and type aliases for shapes.
• Use readonly modifiers where possible to express intent and optimize immutability guarantees.
• Prefer explicit return types for exported functions and public APIs.
• Avoid any where possible; if necessary, use unknown with proper checks.

<D) Naming conventions>

• Variables and functions: camelCase
• Classes and types: PascalCase
• Constants: UPPER_SNAKE_CASE
• File and module names: kebab-case or snake_case, consistent with project convention

<E) Error handling>

• Do not swallow errors; attach context when rethrowing (e.g., throw new Error(Context: ${err.message})).
• Propagate errors to callers with meaningful messages.
• Use try/catch around IO-bound or network-bound operations and ensure resources are released in finally or via finally-like blocks.

<F) Async/Promises>

• Prefer async/await syntax for readability.
• Handle rejections at the call site when possible; avoid unhandled promises.
• Use Promise.all when performing independent async tasks, but catch and handle failures gracefully.

<G) Tests>

• Tests should be fast, deterministic, and hermetic.
• Use descriptive test names and structure (Arrange-Act-Assert patterns where helpful).
• Isolate external dependencies; mock/stub network/db calls effectively.
• Include tests for error paths and boundary conditions.

<H) Documentation and comments>

• Document non-obvious logic with concise comments; avoid obvious boilerplate.
• Public APIs should have JSDoc / TSdoc-style comments describing inputs, outputs, and side effects.
• Update or add READMEs where necessary to reflect changes in behavior.

<I) Security and compliance>

• Do not log sensitive data; mask secrets in logs.
• Validate inputs and sanitize outputs where appropriate.
• Treat untrusted data carefully; avoid code paths that execute untrusted input without validation.

4. Cursor and Copilot rules

• Cursor rules: If this repo uses Cursor tooling, its rules can live under .cursor/rules/ or .cursorrules. Copy or adapt them into this document when agents are created.
• Copilot rules: If there is .github/copilot-instructions.md, follow its guidance and ensure code generation adheres to the outlined constraints.
• If the repo contains these files, consider linking to them here and summarizing any special constraints applicable to agents.

5. Git workflow and contribution notes

• Do not modify dependencies without explicit approval.
• Keep commits small and focused; write 1-2 sentence messages describing why a change was made, not just what changed.
• For AGENTS.md updates, include a short rationale in the commit message.
• Prefer small, reviewed edits over sweeping rewrites.

6. Local integration guidance

• Run: npm install or yarn to install deps before building/tests.
• For multi-language repos, ensure the local environment has language runtimes and tooling installed (Node, Python, Go, Rust, etc.).
• Use a clean environment (e.g., nvm, virtualenv) to avoid cross-project contamination.

7. Example usage scenarios

• A single-file feature: create a minimal unit test, run npm test -- -t "feature X" to validate.
• A refactor: run lint and then a subset of tests; fix issues flagged by lints before merging.
• A CI-like dry run: run npm ci; npm run build; npm test; and report failures with minimal noise.

Notes

• If you want me to tailor this file to the exact repo, I can incorporate the actual existing AGENTS.md content (if present) or sync with Cursor/Copilot rules after inspecting the repo. Right now this is a solid, language-agnostic baseline.