forked from ParadigmEducation/snowflake-notes
93 lines
5.3 KiB
Markdown
93 lines
5.3 KiB
Markdown
# 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` 统一格式化。
|
||
|
||
### 开始工作前（必做）
|
||
|
||
- 同步最新代码：`git fetch --all --prune && git pull --rebase`
|
||
- 浏览近期提交：`git log --oneline --decorate --graph -n 20`
|
||
- 关注分支差异：`git diff --stat origin/$(git rev-parse --abbrev-ref HEAD)...HEAD`
|
||
- 若锁文件变更：`pnpm install`（保持本地依赖与团队一致）
|
||
- 新任务建议开分支：`git switch -c feature/<topic>`；提交信息用中文清晰描述变更意图
|
||
|
||
### 类型生成与 Astro 同步（重要）
|
||
|
||
- Astro 的高保真类型来自 `.astro/types.d.ts`，由 `astro dev` 或 `astro sync` 生成。
|
||
- Node 要求：`>= 18.20.8`（建议 `>= 20`）。Node 版本不足会导致 `astro sync` 失败，类型退化为 `any`（如 `getCollection(...args: any[]): any`）。
|
||
- 操作规范：
|
||
- 在“非沙盒/本机环境”执行：`pnpm astro sync` 或 `pnpm dev`，以生成 `.astro/types.d.ts`。
|
||
- 如在沙盒内执行需要更高权限，请先申请再运行，或直接在沙盒外执行。
|
||
- 若类型仍不生效：删除 `.astro/` 后重跑 `pnpm sync`；确保编辑器使用工作区 TypeScript 版本。
|
||
|
||
### 依赖版本策略
|
||
|
||
- 版本范围由 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`）。
|