feat: 初始化 Astro 学习博客骨架

- Astro+TS 严格模式（禁止 any、显式返回类型）
- ESLint Flat Config + Prettier 格式化
- 内容集合（posts）与示例文章
- OSS 图床可配置 Img 组件
- 抽离 posts 数据逻辑（更易类型检查）
- getStaticPaths 修正（rest 路由传字符串）
- README/AGENTS 中文文档与约定
- Gitea CI：typecheck + lint
- 忽略 ref/（仅作临时参考）

AGENTS.md

@@ -0,0 +1,75 @@
+# 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`）。