AGENTS.md ​

This file defines the working contract for agents operating in this repository.

Scope ​

• Scope: the entire repository rooted at this directory.
• Primary stack: VitePress 1.x, Vue 3, Vercel serverless functions, Node.js scripts.
• Package manager: prefer pnpm because pnpm-lock.yaml is present. npm can run scripts if needed, but do not switch lockfiles casually.

Environment Baseline ​

• Node.js: >=20
• npm: >=10
• Local dev server: pnpm dev
• Production build: pnpm build
• Preview build: pnpm preview
• Lint and autofix: pnpm lint
• Format repo: pnpm format

Repository Map ​

• .vitepress/config.mjs: main VitePress config and build pipeline entry.
• .vitepress/init.mjs: theme config loading/initialization.
• .vitepress/theme/: custom theme source.
• .vitepress/theme/components/: Vue components used by the theme.
• .vitepress/theme/views/: page-level Vue views rendered from markdown wrapper pages.
• .vitepress/theme/assets/themeConfig.mjs: site/theme data source.
• .vitepress/theme/utils/: markdown, RSS, post-data, helper utilities.
• posts/: blog posts. URL path follows file path.
• pages/: standalone pages, often thin markdown wrappers around Vue views.
• public/: static assets and generated data consumed at runtime.
• api/: Vercel serverless endpoints.
• scripts/: one-off or maintenance scripts.

Generated And Derived Files ​

• public/data/postData.json is generated from .vitepress/config.mjs during config evaluation. Do not hand-edit unless the user explicitly asks for it.
• .vitepress/dist/ is build output. Do not edit manually.
• .vitepress/cache/ is cache output. Do not edit manually.
• .vitepress/auto-imports.d.ts and .vitepress/components.d.ts are generated declaration files. Avoid manual edits unless generation is unavailable and the user explicitly wants a direct patch.

Content Conventions ​

• New articles belong in posts/.
• New standalone pages belong in pages/.
• Article URLs are file-path driven, so rename and move files carefully.
• Posts should use frontmatter. Common fields seen in this repo include:
  • title
  • description
  • date
  • categories
  • tags
  • summary
• summary may also be consumed by article-side UI features, not just SEO metadata.
• Wrapper pages in pages/ may embed Vue SFCs using <script setup> and render a view component directly.

Code Style ​

• Follow existing lint/format rules instead of introducing new style conventions.
• Prettier:
  • double quotes
  • semicolons
  • trailing commas
  • printWidth: 100
• ESLint:
  • airbnb-base
  • plugin:vue/vue3-essential
  • import/extensions disabled
  • console allowed
• Preserve the repository's existing style even where comments or strings contain mixed languages.

Working Rules ​

• Prefer minimal, targeted edits. Do not reformat the entire repository for a local change.
• Avoid editing unrelated user changes already present in the worktree.
• When touching theme code, preserve the current information architecture and route structure unless the task explicitly requires changing it.
• When touching content files, preserve frontmatter shape and existing permalink behavior.
• When touching themeConfig.mjs, treat it as user-owned site configuration, not a place for broad refactors.
• Keep secrets out of source files. Use .env for environment-specific values.

Validation Rules ​

• For theme/component/config changes, run:
  • pnpm build
• For JS/TS/Vue logic changes, run:
  • pnpm lint
  • pnpm build
• For content-only changes, at minimum run:
  • pnpm build
• For script changes, run the smallest relevant command if safe, then pnpm build if the script affects site data.
• If a task depends on .env values, state clearly when verification is partial because secrets are not available.

Vercel And API Notes ​

• api/ contains Vercel functions and must stay compatible with the Vercel runtime declared by dependencies/config.
• vercel.json rewrites sitemap.xml, feed.xml, and /redirect; do not break these routes unintentionally.
• Be careful with cache headers and external API dependencies in serverless handlers.

Search And Shell Notes ​

• Prefer rg/rg --files for search if available.
• In environments where rg is unavailable, use PowerShell alternatives such as Get-ChildItem and Select-String.

Safe Change Strategy ​

• Before editing, inspect the relevant config, view, or content path to understand whether it is source, generated output, or user content.
• If a change may affect routing, RSS, sitemap, post-data generation, or page wrappers, verify with a build.
• If a change introduces new environment variables, document them in the final response and keep names consistent with existing .env usage.