私人执业网站套件 — Astro + PagesCMS + Cloudflare Pages
技术栈及其原因
| 层 | 选择 | 原因 |
|---|---|---|
| 网站框架 | Astro | 默认生成几乎零 JavaScript 的静态 HTML——手机端加载快，无需修补，内容使用 Markdown 和类型化 frontmatter。 |
| 内容编辑 | PagesCMS (app.pagescms.org) | 免费、开源、基于 Git：员工通过网页表单编辑；每次保存都是一个 Git 提交。无需数据库，无需维护 CMS 服务器。 |
| 托管 | Cloudflare Pages | 免费套餐能够轻松容纳一个执业网站（慷慨的构建分钟数和带宽，支持多个自定义域名），无品牌标识，允许商业使用，全球 CDN，自动 HTTPS。部署 = 连接 Git 仓库。 |
| 仓库 | GitHub（执业者拥有） | 网站的单一归属地：Astro 读取它，PagesCMS 写入它，Cloudflare 从中构建。 |
使这一切运转的架构规则：网站是出版物，而非应用程序。 页面、个人资料和文章是内容。预约、支付、消息和目录已有现成系统——网站嵌入和链接它们；永远不重新实现它们，也绝不接收它们的数据。
给 AI 代理的指令
- 交付物 = 一个由执业者拥有的可运行仓库 + 三个连接（PagesCMS → 仓库、Cloudflare Pages → 仓库 + 域名）+ 一次通过 CMS 完成的端到端编辑验证。如果你没有账户访问权限，请生成完整的仓库以及一份可供所有者逐步操作的连接清单。
- 首先进行设置访谈。永远不要编造执业事实——证书、执照、保险网络、费用、语言、从业年限。使用占位符并标记，直到所有者提供。
- 根据实时配置（而非凭记忆）验证每个平台的行为：
references/pagescms-config.md中的 PagesCMS filename-template 规则曾导致一个真实网站首次保存失败——将 CMS 保存测试视为“已配置”的定义。
设置访谈（在构建前询问一次）
- 执业身份——执业名称、域名（以及 DNS 在哪里托管——当 DNS 也在 Cloudflare 时，Cloudflare 托管最顺畅）、Logo/颜色（如有）、显示的电话/邮箱。
- 规模——个人执业还是团体执业；提供者名单（姓名、资质、执业州、照片可用性）用于个人资料页面。
- 页面——确认
references/site-blueprint.md中的蓝图（添加/删除：例如每个服务一个独立页面？资源/博客板块？推荐目录嵌入？）。 - 语言——单语种，还是镜像树（例如英语在
/，中文在/zh/）？镜像意味着需要人工高质量翻译的页面及其自己的 slug——请预算翻译费用；切勿将临床相关内容机翻后未经审阅即发布。 - 动态嵌入——哪些现有系统会出现在网站上（预约页面、联系表单应用、推荐目录、安全消息入口）及其网址。这些将作为 iframe 嵌入 + 备用链接。
- 编辑人员——上线后谁更新内容（仅所有者？管理员？提供者撰写文章？）——这决定了 PagesCMS 的访问权限以及网站有多少部分是 CMS 管理 vs. 代码管理。
- 现有资产——要迁移的现有网站内容、照片（及其版权）、Google Business Profile 以及网站必须保持一致的目录列表。
硬性规则
- 执业者拥有每个账户——域名注册商、GitHub、Cloudflare。使用执业者的登录信息设置，并配置执业者控制的恢复选项。
- 内容是数据，而非代码。 编辑可能更改的任何内容（提供者简介、服务、费用、常见问题、文章）都存放在带有内容 schema 的 Markdown/frontmatter 中——永远不要硬编码到
.astro模板中。 - PagesCMS 的 filename 模板使用
{fields.slug}（或集合的实际字段路径）。裸{slug}无效，会导致每次 CMS 保存失败并出现难以理解的错误。修复配置后，重新加载 CMS——它会按会话缓存配置。 - 网站不收集任何临床信息。 没有症状文本框，没有“告诉我们发生了什么”的表单。联系方式 = 预约链接/嵌入、电话号码，以及如果需要的路由表单应用——同时，在联系页面以及任何邀请联系的页面上显示危机热线（美国为 988，紧急情况拨打 911），使用网站的语言。
- 嵌入链接需提供备用链接。 每个 iframe（预约、目录）都配有一个指向同一系统的普通链接，以便被阻止的框架不会让客户无路可走。
- 声明纪律： 网站上的网络、费用、资质和可用性必须与执业者的真实信息来源（其名册/记录）一致。网站是事实最后应该编辑的地方——如果一个数字存在于两个地方，需指明哪个是权威来源。
- 性能是治疗网站的一项重要特性——用户可能焦虑地用手机从目录个人资料点进来。在将图片放入仓库前进行压缩；一张 2 MB 的英雄图片是 bug，而非资产。
构建顺序
- 根据
references/astro-setup.md创建仓库 + Astro 脚手架 + 内容模型，根据references/site-blueprint.md创建页面。 - 本地构建通过；内容占位符标记并列出供所有者填写。
- 按照
references/pagescms-config.md配置 PagesCMS 并执行真实保存测试。 - 按照
references/cloudflare-pages-deploy.md连接 Cloudflare Pages 并配置自定义域名。 - 按照
references/seo-and-performance.md执行 SEO/性能检查。 - 按照
references/maintenance-and-handoff.md进行交接；按照references/test-checklist.md进行验证。
参考文件
references/architecture-and-stack.md— 三层架构、数据流、静态对于执业网站的意义references/site-blueprint.md— 页面列表、每个页面必须包含的内容、治疗相关必须项references/astro-setup.md— 项目布局、内容集合 + schema、多语言树结构references/pagescms-config.md—.pages.yml、集合、媒体、filename-template 规则references/cloudflare-pages-deploy.md— 项目设置、构建配置、自定义域名、预览references/seo-and-performance.md— 元数据、结构化数据、站点地图/RSS、llms.txt、图片references/maintenance-and-handoff.md— 编辑工作流、更新、备份、谁拥有什么references/test-checklist.md— 验收测试，首先是 CMS 保存测试