snowflake-notes/AGENTS.md

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）。