{
  "markdown": "# HUAT FSAC · Guidance Astro\n\n> 基于 **Astro 7 + Starlight** 构建的 HUAT 方程式赛车队(Formula Student)官方文档站点。\n> 中英双语 · Cloudflare Workers SSR · PWA · 多主题 · Pagefind 搜索 · CSP nonce 加固。\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Deploy](https://img.shields.io/badge/Deploy-Cloudflare%20Workers-orange)](https://huat-fsac.eu.org)\n[![Node](https://img.shields.io/badge/node-22.23.2-brightgreen)](./.nvmrc)\n[![pnpm](https://img.shields.io/badge/pnpm-11.22.0-blue)](https://pnpm.io)\n[![Last commit](https://img.shields.io/github/last-commit/HUAT-FSAC/Guidance-Astro)](https://github.com/HUAT-FSAC/Guidance-Astro/commits/main)\n[![Issues](https://img.shields.io/github/issues/HUAT-FSAC/Guidance-Astro)](https://github.com/HUAT-FSAC/Guidance-Astro/issues)\n[![PRs](https://img.shields.io/github/issues-pr/HUAT-FSAC/Guidance-Astro)](https://github.com/HUAT-FSAC/Guidance-Astro/pulls)\n[![Analytics](https://img.shields.io/badge/Analytics-Umami-blue)](https://cloud.umami.is/share/ADsMBsz2WVJPbqjO)\n\n🇬🇧 [English](./README.en.md) · 🇨🇳 **简体中文**(本文件)\n\n> ⚠️ 线上服务由 **Cloudflare Worker SSR** 提供(`output: server` + `@astrojs/cloudflare`):\n> `wrangler deploy --config dist/server/wrangler.json` 由 GitHub Actions `push main` → `deploy` job 触发(详见 [`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md))。\n> `*.pages.dev` 域返回 404 为预期行为,请勿删除 zone 内的 `huat-fsac.eu.org` DNS 记录。\n\n---\n\n## ✨ 特性\n\n- 🚀 **高性能** — Astro 7 + Vite terser + 代码分割,首屏零 JS\n- 📱 **PWA** — 离线访问 / 安装到桌面,Service Worker 智能缓存\n- 🌐 **国际化** — 中英文双语,`src/content/docs/{zh,en}/`\n- 🎨 **多主题** — 经典橙 / 电竞蓝 / 赛道红 / 科技紫 / 极速绿\n- ♿ **可访问性** — WCAG AA,移动端触摸目标优化\n- 📊 **分析集成** — Umami Analytics 事件追踪\n- 🔍 **全文搜索** — Pagefind 驱动的站内搜索 + 建议 + 高亮\n- 🔒 **安全加固** — CSP(base64url nonce)+ HSTS + 安全响应头 + Worker 边缘配置\n- 🤖 **质量门禁** — Husky + commitlint + lint-staged + Vitest + Playwright + ESLint + Prettier\n\n---\n\n## 🚀 快速开始\n\n### 环境要求\n\n- **Node.js** `22.23.2`(参见 [`.nvmrc`](./.nvmrc),`engines` 要求 `>=22.0.0`)\n- **pnpm** `11.22.0`(`packageManager` 字段)\n- **Wrangler** `4.114.0`(部署用,本地 `dev:worker` 不强制)\n\n### 本地开发\n\n```bash\ngit clone https://github.com/HUAT-FSAC/Guidance-Astro.git\ncd Guidance-Astro\npnpm install\npnpm dev                 # http://localhost:4321\n```\n\n### 常用命令\n\n| 命令                                | 说明                                                              |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `pnpm dev`                          | 启动开发服务器                                                    |\n| `pnpm build`                        | 构建生产版本(产物在 `dist/`)                                      |\n| `pnpm preview`                      | 本地预览构建结果(静态)                                            |\n| `pnpm preview:ssr`                  | 用 Wrangler 本地跑 SSR                                            |\n| `pnpm lint` / `pnpm lint:fix`       | ESLint 检查 / 自动修复                                            |\n| `pnpm format` / `pnpm format:check` | Prettier 格式化 / 校验                                            |\n| `pnpm test:run`                     | Vitest 单元测试(单次)                                             |\n| `pnpm test:coverage`                | 覆盖率报告(70/60/70/70 阈值)                                      |\n| `pnpm test:e2e`                     | Playwright 端到端测试                                             |\n| `pnpm quality:bundle`               | 构建体积预算                                                      |\n| `pnpm quality:theme`                | 主题对比度                                                        |\n| `pnpm quality:lighthouse`           | Lighthouse CI 断言                                                |\n| `pnpm deploy:worker`                | `build` + `wrangler deploy`(需 `CLOUDFLARE_API_TOKEN/ACCOUNT_ID`) |\n| `make help`                         | 列出所有 `make` 快捷命令(`make dev/build/ci/deploy/secret-scan`)  |\n\n---\n\n## 📁 项目结构\n\n```text\nGuidance-Astro/\n├── README.md            # 本文件(中文)\n├── README.en.md         # English version\n├── LICENSE              # MIT\n├── CONTRIBUTING.md      # 贡献指南\n├── CODE_OF_CONDUCT.md   # 行为准则\n├── SUPPORT.md           # 支持渠道\n├── SECURITY.md          # 安全漏洞上报\n├── CHANGELOG.md         # 版本记录\n├── .editorconfig        # 编辑器风格统一\n├── .nvmrc               # Node 版本\n├── .github/             # Issue / PR 模板 + CI + Dependabot\n├── public/              # 静态资源(PWA、favicon、_headers)\n├── src/                 # 站点源码\n│   ├── assets/          # 可优化的图片资源\n│   ├── components/      # Astro 组件\n│   ├── content/docs/    # 站点发布的 MDX(中英文)\n│   ├── data/            # 主页、车辆、Showcase Lab 等数据\n│   └── pages/           # 路由页面\n├── scripts/             # 构建与质量脚本\n├── tests/               # Vitest 单元 + Playwright E2E\n├── docs/                # 仓库文档(部署、ADR、计划、报告)\n└── openwiki/            # 由定时工作流自动生成的证据索引(勿手改)\n```\n\n> 站点正文在 [`src/content/docs/`](./src/content/docs/)。\n> 仓库自身开发文档在 [`docs/`](./docs/)。\n> [`openwiki/`](./openwiki/) 由 GitHub Actions 定时刷新,请勿手改。\n\n---\n\n## 🛠️ 开发指南\n\n### MDX 编写规范\n\n**特殊字符转义**:表格内 `<` 需转义:\n\n- ❌ `| <1A |` · ✅ `| \\<1A |` 或 `| \\`<1A\\` |`\n\n**Aside 组件类型**(Starlight):支持 `note / tip / caution / danger`,**不**支持 `warning`。\n\n### 静态资源管理\n\n文档图片请放在 `src/assets/docs/<年份>/<模块>/`,引用方式:\n\n```mdx\nimport { Image } from 'astro:assets'\nimport myImage from '../../assets/docs/2025/感知/lidar-setup.png'\n\n<Image src={myImage} alt=\"激光雷达安装示意图\" />\n```\n\n### 依赖与构建 (pnpm)\n\n- **删除** `package-lock.json`(避免与 pnpm 冲突)\n- **保留并提交** `pnpm-lock.yaml`\n- `pnpm-workspace.yaml` 中的构建配置**严禁删除**\n\n---\n\n## 🤝 贡献\n\n欢迎贡献!完整流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)。速查:\n\n1. Fork 仓库 → 创建分支 `type/area/desc`\n2. 提交时遵循 [Conventional Commits](https://www.conventionalcommits.org/)\n3. 推送后提 PR,关联 Issue(若有)\n4. 通过 [`docs/WORKFLOW.md §6 质量门禁`](./docs/WORKFLOW.md#6-质量门禁definition-of-done) 后合并\n\n提 PR 前请阅读 [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)。\n\n---\n\n## 📚 文档\n\n| 文件                                                           | 说明                          |\n| -------------------------------------------------------------- | ----------------------------- |\n| [CONTRIBUTING.md](./.github/CONTRIBUTING.md)                   | 如何搭建环境、提交代码与开 PR |\n| [CODE_OF_CONDUCT.md](./.github/CODE_OF_CONDUCT.md)             | 社区行为准则                  |\n| [SUPPORT.md](./.github/SUPPORT.md)                             | 提问、讨论、联系方式          |\n| [SECURITY.md](./.github/SECURITY.md)                           | 安全漏洞的私下上报方式        |\n| [CHANGELOG.md](./CHANGELOG.md)                                 | 版本变更记录                  |\n| [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)                     | 部署说明                      |\n| [docs/WORKFLOW.md](./docs/WORKFLOW.md)                         | 开发流程与质量门禁            |\n| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)                 | 系统架构与目录职责            |\n| [docs/ROADMAP.md](./docs/ROADMAP.md)                           | 路线图与方向性 TODO           |\n| [docs/adr/](./docs/adr/)                                       | 架构决策记录(ADR)             |\n| [docs/CONTRIBUTING-content.md](./docs/CONTRIBUTING-content.md) | MDX/资产/侧边栏 编写规范      |\n\n---\n\n## 🔐 安全\n\n**请勿**在公开 Issue 提交安全漏洞。请用 [GitHub Private Vulnerability Reporting](https://github.com/HUAT-FSAC/Guidance-Astro/security/advisories/new),详见 [SECURITY.md](./.github/SECURITY.md)。\n\n---\n\n## 📄 许可证\n\n[MIT](./LICENSE) © 2026 HUAT FSAC\n\n---\n\n## 🔗 相关链接\n\n- [线上站点](https://huat-fsac.eu.org)\n- [GitHub 组织](https://github.com/HUAT-FSAC)\n- [Astro 文档](https://docs.astro.build/)\n- [Starlight 文档](https://starlight.astro.build/)\n",
  "bytes": 7412,
  "sha": "e5642b2825ff9ba98e879ff46b07e367f2fa6c5b22c4e45c1b476bc0c04321f9",
  "repo_slug": "huat-fsac/guidance-astro",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_huat_fsac_guidance_astro_openwiki_index__01ddf34c/readme"
}