docs: 统一文档为 pnpm astro sync，避免误导；同步提交 env/tsconfig 调整

.gitignore

@@ -9,5 +9,8 @@ dist/
 public/images/
 ref/    
 
+# Environment variables
+.env
+
 # Miscellaneous
 .DS_Store

AGENTS.md

@@ -67,7 +67,7 @@
 - Astro 的高保真类型来自 `.astro/types.d.ts`，由 `astro dev` 或 `astro sync` 生成。
 - Node 要求：`>= 18.20.8`（建议 `>= 20`）。Node 版本不足会导致 `astro sync` 失败，类型退化为 `any`（如 `getCollection(...args: any[]): any`）。
 - 操作规范：
-  - 在“非沙盒/本机环境”执行：`astro sync` 或 `pnpm dev`，以生成 `.astro/types.d.ts`。
+  - 在“非沙盒/本机环境”执行：`pnpm astro sync` 或 `pnpm dev`，以生成 `.astro/types.d.ts`。
   - 如在沙盒内执行需要更高权限，请先申请再运行，或直接在沙盒外执行。
   - 若类型仍不生效：删除 `.astro/` 后重跑 `pnpm sync`；确保编辑器使用工作区 TypeScript 版本。
 

README.md

@@ -20,10 +20,11 @@
 - 通用组件：`src/components/`（如 `Img.astro` 支持外部图床）
 - 内容扩展抽象：`src/lib/content/`（为未来 Typst 等格式预留）
 
-## 配置
+## 配置与类型
 
 - `PUBLIC_MEDIA_BASE_URL`：外部图床前缀（避免图片入库）
 - `PUBLIC_SITE_URL`：站点地址（可选，用于 canonical 等）
+- 修改内容集合（src/content/config.ts）后，需在本机运行 `pnpm astro sync`（Node >= 18.20.8，建议 >= 20），以生成 `.astro/types.d.ts`，否则类型可能退化为 any。
 
 ## 约定
 

src/env.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />
 
 interface ImportMetaEnv {
   readonly PUBLIC_MEDIA_BASE_URL?: string;
@@ -8,4 +9,3 @@ interface ImportMetaEnv {
 interface ImportMeta {
   readonly env: ImportMetaEnv;
 }
-

tsconfig.base.json

@@ -17,7 +17,7 @@
   },
   "include": [
     "src",
-    "env.d.ts",
+    "src/env.d.ts",
     "astro.config.mjs",
     ".astro/types.d.ts"
   ],