UniAPI 文档

Appearance

AGENTS.md (repo-specific guidance) ​

This repository is a VitePress documentation site for UniAPI. Use this file as the canonical “how to work here” reference for agentic coding.

1) Build / Lint / Test commands ​

Prereqs ​

  • Node.js: VitePress requires Node >= 18 (this repo currently builds on Node 22.x).
  • Package manager: repo ships package-lock.json → prefer npm.

Install deps ​

bash
npm ci

Dev server (fast feedback) ​

bash
npm run docs:dev
# default: http://localhost:5173

VitePress CLI flags (preferred for help/flags):

bash
npx vitepress dev --help
npx vitepress dev --port 5173
npx vitepress dev --host

Production build (primary verification) ​

bash
npm run docs:build
# output: .vitepress/dist

Preview built site ​

bash
npm run docs:preview
# default: http://localhost:4173

Lint / Format ​

  • Not configured (no ESLint / Prettier / Biome / etc.).
  • Don’t introduce a linter/formatter as drive-by cleanup.

Tests ​

  • Not configured (no Jest/Vitest/Playwright/etc.).

Running a single test ​

  • N/A (no test runner installed).
  • Validation strategy instead:
    • Markdown/content changes: npm run docs:dev
    • .vitepress/ config/theme changes: npm run docs:build (must pass)

2) Code style guidelines (repo conventions) ​

No enforced formatter: keep diffs minimal and follow the local file’s style.

JavaScript / TypeScript ​

Module system ​

  • package.json has "type": "module" → ESM only (import/export).

Indentation / formatting ​

  • Prefer 2-space indentation where practical.
  • Quotes / semicolons are mixed → follow the file you are editing.
  • Avoid “format churn” (especially in .vitepress/theme/index.ts).

Imports ​

  • Order imports as:
    1. External packages
    2. Local relative imports
    3. Side-effect imports (CSS)
  • Use import type { ... } for type-only imports.

Types / safety ​

  • Prefer explicit types when a value crosses module boundaries.
  • Avoid type suppression (@ts-ignore, @ts-expect-error) unless there is no alternative.

Naming ​

  • Follow existing conventions in the file.
  • Typical expectations:
    • camelCase variables/functions
    • PascalCase Vue components
    • Constants only SCREAMING_SNAKE_CASE if the file already uses it

Error handling ​

  • Avoid empty catch blocks.
  • If you intentionally ignore an error, add a short comment explaining why.

Dynamic operations pages ​

  • operations/[operationId].md reads operationId from route params and renders <OAOperation ... />.
  • operations/[operationId].paths.js generates routes from the spec.

Markdown content conventions ​

Frontmatter ​

Most pages use YAML frontmatter; keep it consistent:

  • title, description, keywords as needed
  • layout: doc
  • outline: deep
  • lastUpdated: true

Language ​

  • Documentation is primarily Simplified Chinese.

Code fences ​

  • Always specify a fence language (bash, json, ts, js, …).
  • Prefer bash over curl as a fence language (build may fall back to txt).

Project layout (what lives where) ​

  • docs/ — main documentation pages
  • integration/ — integration guides
  • .vitepress/config.mts — VitePress site config
  • .vitepress/theme/ — theme customization + CSS vars

Build artifacts (don’t hand-edit):

  • .vitepress/cache
  • .vitepress/dist

Repo-specific gotchas ​

  1. npm run docs:dev -- --help may start the dev server.
    • Prefer: npx vitepress --help / npx vitepress dev --help.
  2. Keep changes in .vitepress/theme/index.ts tightly scoped.
  3. Production build may warn about large chunks or unknown highlight languages; treat as warnings unless it breaks the build.

Cursor / Copilot rules ​

No Cursor/Copilot instruction files were found:

  • .cursorrules: not found
  • .cursor/rules/: not found
  • .github/copilot-instructions.md: not found

If added later, treat them as higher-priority instructions than this file.

Last updated: