# AGENTS 指南（本仓库）

本仓库用于搭建一套基于 Astro 的内部学习博客站点。目标：TypeScript 严格（拒绝 any）、代码与文档统一格式化、内容格式可扩展（不仅限于 Markdown），图片优先走外部 OSS，不建议把图片直接提交进仓库。

## 工作流原则

- 语言与文档：优先中文说明；代码与注释保持简洁明确。
- TypeScript 严格：启用 `strict` 和 `noImplicitAny`；ESLint 禁止 `any`。
- 格式化：统一使用 Prettier（含 Astro、Markdown）；提交前请执行 `pnpm format` 或启用编辑器保存自动格式化。
- 类型与检查：强制显式函数返回类型，禁止隐式 any；建议在 CI 中执行 `pnpm typecheck` 与 `pnpm lint`。
- 目录结构：见下文“项目结构”。
- 内容来源：默认支持 `md`/`mdx`，并预留可扩展的内容加载层（如将来支持 Typst 等）。
- 图片与静态资源：默认不入库。通过环境变量配置外部 OSS 图床地址，在组件中统一引用。
 - `ref/` 目录仅作临时参考：不纳入版本管理与检查（已在 `.gitignore`、TS 与 ESLint 忽略）。

## 项目结构（约定）

- `src/pages`：页面路由（如首页、文章详情）。
- `src/layouts`：页面与文章的布局模版。
- `src/components`：通用组件（如 `Img.astro`）。
- `src/content`：Astro Content Collections 与文章内容（`posts`）。
- `src/lib/content`：内容加载抽象层，便于未来扩展除 Markdown 以外的格式。
- `public`：公开静态资源（尽量不要放图片）。

## TypeScript 与 ESLint

- `tsconfig.json` 开启：`strict: true`、`noImplicitAny: true`、`noFallthroughCasesInSwitch: true` 等。
- ESLint（使用 Flat Config）：统一使用根目录 `eslint.config.js`，不要新增 `.eslintrc.*` 文件；启用 `@typescript-eslint/no-explicit-any: error` 等类型感知规则，并结合 Astro 插件。

## 格式化

- Prettier 统一代码、Astro 与 Markdown 的格式。
- 命令：`pnpm format` 全量格式化，`pnpm format:check` 校验。

## 内容与多格式扩展

- 文章位于 `src/content/posts`，默认使用 Astro Content Collections（`config.ts`）定义元数据 Schema。
- 已提供 `src/lib/content` 抽象：
  - 通过扩展“加载器（loader）”注册新的后缀（如 `.typ`）。
  - 新增格式时，请实现接口并在注册表中添加映射，无需改动现有渲染逻辑。

## 图片与外部 OSS 配置

- 使用 `PUBLIC_MEDIA_BASE_URL` 指定外部图床（OSS/CDN）前缀。
- 组件 `src/components/Img.astro` 会根据配置拼接完整图片地址。
- 若必须本地存放，建议放置在 `public/images/`，但该目录默认已在 `.gitignore` 中忽略。

## 开发与运行（建议）

- 包管理器：使用 `pnpm`（无需指定具体版本）。
- 常用脚本：
  - `pnpm dev` 启动本地开发（热更新）。
  - `pnpm build` 产出静态文件。
  - `pnpm preview` 预览构建结果。
  - `pnpm lint` 代码检查；`pnpm typecheck` 类型检查；`pnpm format` 统一格式化。

### 依赖版本策略

- 版本范围由 pnpm 写入：不要在 `package.json` 手写 `latest` 或具体版本号。
- 默认使用 caret 范围（`^x.x.x`）：
  - 新增依赖：`pnpm add <pkg>`（由 pnpm 写入 `^` 范围）。
  - 升级依赖：`pnpm up <pkg> -L`（按范围更新到可用最新）。
- Node 版本：`>=20`（见 `package.json` 的 `engines.node`）。
- CI 构建建议使用：`pnpm install --frozen-lockfile` 保证可重复。

## 代码提交规范（简要）

- 小步提交，信息清晰：`feat: ...` / `fix: ...` / `docs: ...` / `chore: ...` 等。
- 不提交大体积二进制与图片，图片走外部 OSS。

## 注意事项

- 任何需要引入新内容格式，请优先在 `src/lib/content` 添加 loader，而不是在页面层做分支判断。
- 若需新增全局配置项，请优先考虑使用 `PUBLIC_` 前缀暴露给客户端，或通过服务器端/构建时注入。
- 路由与 getStaticPaths：对 rest 参数页面（如 `src/pages/posts/[...slug].astro`），`params.slug` 必须是字符串（包含斜杠的完整路径），不能返回数组；推荐将 `getStaticPaths` 放在独立的 TS 文件并显式标注类型（见 `src/pages/posts/getStaticPaths.ts`）。