Site Forge — 全自动建站部署流水线

02 系统架构全景

┌─────────────────────────────────────────────────────────────────────────┐ │ 用户输入（一次性） │ │ 领域 / 受众 / 域名 / 变现偏好 / 种子内容方向 │ └──────────────────────────────┬──────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ AI Agent（Cursor IDE） │ │ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ SKILL.md │ │ AGENTS.md │ │ SITE-SPEC.md │ │ CHECKLIST.md │ │ │ │ 建站协议 │ │ 项目上下文 │ │ MVP 规格 │ │ 质量标准 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬───────┘ └──────┬───────┘ │ │ └────────────────┴────────────────┴──────────────────┘ │ │ 10 阶段流水线 │ └──────────────────────────────┬──────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ new-site.sh │ │ deploy.sh │ │check-site.sh│ │ 脚手架生成 │ │ Vercel 部署 │ │ 健康检查 │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Monorepo（site-forge） │ │ sites/aitoolpilot/ sites/calcwise/ sites/nocoderadar/ ...（7 站） │ └──────────────────────────────┬──────────────────────────────────────────┘ │ git push ▼ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │ GitHub │─────▶│ Vercel │─────▶│ Live Sites │ │ Monorepo │ │ Auto Deploy │ │ *.vercel.app │ └──────────────┘ └──────────────┘ └───────┬───────┘ │ ┌───────────┼───────────┐ ▼ ▼ ▼ ┌──────────┐ ┌────────┐ ┌──────────┐ │ GSC │ │ GA4 │ │AdSense │ │ 索引监控 │ │ 流量 │ │ 广告变现 │ └──────────┘ └────────┘ └──────────┘

03 AI Agent Skill 工作流

这是整个系统的核心设计：把建站流程编码为 Skill 文件，让 AI Agent 像执行 SOP 一样自主完成全部工作。

什么是 Skill？

Skill 是一份 Markdown 协议文件（.cursor/skills/build-site/SKILL.md），定义了 AI Agent 执行任务的完整规则：输入要求、执行步骤、约束条件、输出格式。当用户说"新建一个站"时，Agent 自动加载这份协议并按序执行。

Skill 驱动的分层架构

层级	文件	职责
全局上下文	`AGENTS.md`	项目定位、技术栈、目录结构、对话触发词 — 每次对话自动加载
执行协议	`SKILL.md`	10 阶段建站流水线的完整 SOP — 用户触发"建站"时按需加载
规格标准	`SITE-SPEC.md`	MVP 页面数/文章数/技术规格/设计标准 — 建站时参考
质量门禁	`CHECKLIST.md`	构建/SEO/性能/安全/合规/交互测试共 40+ 项检查 — Review 阶段逐项执行
运营手册	`PLAYBOOK.md`	选品框架、变现阶梯、内容规范、止损规则 — 站点通过评估后参考

为什么这样设计？将知识和流程"外化"到文件中，而不是依赖 AI 的隐性记忆。好处是：可版本控制、可迭代、可复用、可审计。每次建站的质量是确定性的，不受模型随机性影响。

04 10 阶段无人值守流水线

一次收料、全程自主、交付即上线。用户只需提供 5 项材料（领域/受众/域名/变现偏好/内容方向），AI 自主执行以下 10 个阶段：

规划 — 关键词研究 & 站点架构

根据领域做长尾关键词分析、内容金字塔规划、选择最佳站点结构（博客/工具/目录/对比）

→ sites/<站名>/PLAN.md

搭建 — 脚手架生成 & 工程初始化

执行 new-site.sh 从模板生成项目骨架，或根据站点类型从零搭建（工具站/目录站）。复用工程配置（next.config、eslint、postcss）和基础设施组件（GA、AdSense、Cookie Consent、JSON-LD）

→ 可运行的 Next.js 项目

页面 — 按架构开发全部页面

首页 / 博客列表 / 文章详情 / 关于 / 隐私政策 / 404，按 PLAN.md 的结构开发，移动端优先响应式设计

→ 6-7 个完整页面

内容 — 5 篇 SEO 种子文章

支柱文章 + 对比文章 + 教程指南 + 评测 + 清单，每篇 1500-2500 词，内部互链形成主题簇，去 AI 味润色

→ 5 篇 MDX 文件 (~10,000 词)

Review — CHECKLIST 逐项自检

按 CHECKLIST.md 40+ 项标准检查：构建/SEO/性能/代码质量/响应式/内容/安全/合规，发现问题立即修复

→ 全部检查通过

部署 — 一键上线 Vercel

执行 deploy.sh --create：通过 Vercel API 创建项目 → 链接 Monorepo → 配置环境变量 → 触发生产部署

→ 线上站点 https://xxx.vercel.app

域名校验 — 修正 URL 不一致

查询 Vercel 实际分配的域名，与代码中硬编码的域名比对，不一致则全局替换（sitemap、canonical、JSON-LD、robots.txt）后重新部署

→ 所有 URL 一致

验证 — 健康检查 & 搜索引擎 Ping

执行 check-site.sh 检查所有页面 HTTP 状态码、SEO 标签、文章可达性；执行 ping-search-engines.sh 通知 Google/Bing 抓取 sitemap

→ 交付报告

GSC 接入 — 搜索引擎验证

写入 Google Search Console 验证 meta 标签，重新部署。注意：新站不配 GA4，Day 30 后只给赢家配

→ GSC 验证通过

交付 — 提醒用户提交 Sitemap

输出 DELIVERY_TEMPLATE.md 格式的交付报告，提醒用户去 GSC 手动提交 sitemap（AI 无法代替操作）

→ 完成交付

05 自动化脚本体系

每个脚本都是幂等的、可独立执行的，AI Agent 在流水线中按需调用：

脚本	用途	关键实现
`new-site.sh <slug> <brand> <desc>`	博客型站点脚手架	复制 `templates/starter/` → 全局替换占位符 (`__SLUG__`, `__BRAND__`) → `npm install` → 生成 PLAN.md 骨架
`deploy.sh <站名> --create`	首次部署	Vercel API 创建项目（设置 `rootDirectory` + `gitRepository`）→ 配置环境变量（`SITE_URL`, `GA_ID`, `ADSENSE_ID`）→ 触发部署 → Ping 搜索引擎 → 健康检查
`deploy.sh <站名>`	更新部署	`git add` + `git commit` + `git push` → Vercel 通过 Ignored Build Step 只构建有变更的站点
`check-site.sh <站名>`	健康检查	curl 检测所有页面状态码 + SEO 标签（title/description/OG/JSON-LD）+ 遍历 MDX 目录验证文章可达性
`ping-search-engines.sh <站名>`	搜索引擎通知	HTTP 请求 Google Ping API + Bing Ping API，附带 sitemap URL

# 典型的建站部署全流程（AI Agent 自动执行）

# 1. 脚手架生成
./scripts/new-site.sh aitoolpilot "AIToolPilot" "Your guide to the best AI tools"

# 2. （AI Agent 在此期间自动完成页面开发 + 内容创作 + Self-Review）

# 3. 一键部署到 Vercel
./scripts/deploy.sh aitoolpilot --create

# 4. 健康检查（deploy.sh 末尾自动调用）
./scripts/check-site.sh aitoolpilot

# 5. 搜索引擎 ping（deploy.sh 末尾自动调用）
./scripts/ping-search-engines.sh aitoolpilot
  

06 Monorepo 部署架构

为什么选 Monorepo？

站群场景下，如果每站一个仓库，管理成本会随站点数量线性增长。Monorepo 方案：一个仓库管 7 个站，共享脚本和模板，推一次 git 就触发所有变更站点的自动部署。

site-forge/                      # Monorepo 根
├── AGENTS.md                    # AI 全局上下文
├── .cursor/skills/build-site/   # 建站 Skill 协议
├── strategy/                    # 运营策略文档
├── templates/starter/           # 参考模板
├── scripts/                     # 自动化脚本
│   ├── new-site.sh
│   ├── deploy.sh
│   ├── check-site.sh
│   └── ping-search-engines.sh
└── sites/                       # 所有站点
    ├── aitoolpilot/             # AI 工具评测站
    ├── calcwise/                # 在线计算器工具站
    ├── coursecompass/            # 在线课程导航
    ├── desksetuphq/             # 桌面设置指南
    ├── emailtoolscout/          # 邮件工具评测
    ├── nocoderadar/             # 无代码工具雷达
    └── smartnestguide/          # 智能家居指南
  

Vercel 多项目映射

每个站点在 Vercel 上是独立项目，通过 rootDirectory 指向 sites/<站名>/。关键配置：

配置项	值	作用
`rootDirectory`	`sites/aitoolpilot`	告诉 Vercel 构建入口在哪
`gitRepository`	`github-org/site-forge`	链接到 Monorepo 而不是独立仓库
`commandForIgnoringBuildStep`	`git diff --quiet HEAD~1 HEAD -- .`	只有该站点目录有变更时才触发构建，避免无关 push 浪费构建配额

    效果：修改 sites/aitoolpilot/ 下的文件 → git push → Vercel 只构建 aitoolpilot，其他 6 个站不受影响。部署完全由 git push 触发，无需手动操作 Vercel 后台。
  

07 质量保障与自动验证

质量门禁分三层：静态检查 → 部署后健康检查 → 交互测试。

第一层：CHECKLIST 静态检查（40+ 项）

构建

Build + Lint + TypeScript

npm run build/lint 零错误零警告

SEO

10 项检查

title/description/h1/alt/sitemap/robots/JSON-LD/canonical/OG/互链

性能

Lighthouse > 90

next/image + next/font + Tailwind purge + SSG

合规

Privacy + Cookie + Disclosure

GDPR Cookie 弹窗 + 隐私政策 + 联盟声明

第二层：check-site.sh 健康检查

自动 curl 所有页面，验证 HTTP 200 + SEO 标签存在性 + 文章可达性，输出 pass/fail/warn 汇总。

第三层：Playwright MCP 交互测试

通过 Playwright MCP 工具在真实浏览器中验证：Cookie 弹窗点击 → 导航跳转 → 移动端汉堡菜单 → 客户端组件水合。这层解决了"SSR 看起来正常但事件处理器未绑定"的隐性 bug。

08 数据驱动的 30 天评估

核心指标：GSC 展示量（而非点击量）

新站 30 天内很难有大量点击，但"展示量"说明 Google 已经认为你和某些搜索词相关。展示量是流量的先行指标。

Day 30 展示量	判定	行动
> 500	赢家候选	进入加码期 → 规划 10-20 篇文章 + 申请 AdSense + 注册联盟
100-500	观望	再等 30 天，不追加内容，Day 60 提高标准到 > 1000
< 100	大概率淘汰	停止投入，保留站点 90 天观察
0	直接砍	Niche 不行，不用犹豫

30 天内不追加内容。这不是偷懒，而是科学对照：5 篇种子文章就是实验组。如果全部无展示量，说明 niche 本身有问题，不是内容不够的问题。追加内容会干扰判断。

新站 GA4 策略

Day 0 只配 GSC 验证，不配 GA4。原因：新站前 30 天几乎没有流量，GA4 的数据没有决策价值，反而增加部署复杂度。Day 30 筛出赢家后再配 GA4，把精力花在刀刃上。

09 踩过的坑 & 工程决策

坑 1：Vercel 域名不可预测

Vercel 分配的域名可能不是 <站名>.vercel.app（被占用时会变成 <站名>-xxx.vercel.app）。如果代码里硬编码的域名和实际域名不一致，sitemap、canonical URL、JSON-LD 全部失效，GSC 无法正确抓取。

解决方案：部署后通过 Vercel API 查询实际域名，自动比对并全局替换，然后重新构建部署。这就是流水线第 7 阶段"域名校验"存在的原因。

坑 2：SSR 水合失败导致事件处理器不绑定

SSR 组件用 useState(() => localStorage.getItem(...)) 初始化状态时，服务端渲染的 HTML 和客户端水合后的 DOM 不一致，React 跳过水合，所有 onClick 等事件处理器失效。页面看起来正常但完全不可交互。

解决方案：用 useSyncExternalStore 替代直接调用浏览器 API，确保 SSR 阶段返回安全的默认值。同时引入 Playwright MCP 做交互测试，在真实浏览器中验证事件绑定。

坑 3：为什么不用 output: "export"？

Next.js 的 output: "export" 会生成纯静态 HTML，失去 Vercel 对 Next.js 的原生 SSG/ISR 支持，导致路由重写、middleware、动态路由等功能不可用。Vercel 本身就能完美处理 Next.js SSG，没必要退化到纯静态导出。

决策：为什么选 Monorepo 而不是 Multi-Repo？

Multi-Repo 的问题：每站一个仓库，7 个站 = 7 个仓库 × (CI 配置 + 脚本维护 + 模板同步) = 管理地狱。脚本更新需要手动同步到所有仓库。

Monorepo 的优势：脚本、模板、策略文档只维护一份。Vercel 的 commandForIgnoringBuildStep 解决了"推一次构建所有"的问题，实现了按需构建。唯一的代价是仓库体积增大，但对于内容站来说完全可以接受。

决策：为什么模板不是必须照搬？

templates/starter/ 是博客型参考模板，但站群覆盖多种形态（博客/工具站/目录站/对比站）。强制套模板会让工具站套上博客 UI，不合理。所以设计为"可复用的部分"（工程配置 + 基础设施组件）和"按需定制的部分"（页面结构 + UI），AI 根据领域灵活决定。

10 面试预设问答

Q: 能简单介绍一下这个项目吗？

这是一个全自动建站部署流水线。核心思路是把建站流程编码为 AI Agent 的 Skill 协议，用户只需提供领域和方向等 5 项材料，AI 就能自主完成从脚手架生成、内容创作、SEO 配置、Vercel 部署到搜索引擎接入的全链路工作。目前已经用这套系统建了 7 个不同领域的站点，实现了"零人工干预"的站群批量生产。

Q: "零人工干预"具体是怎么做到的？

关键是把建站 SOP 编码为一份 Skill 文件。它定义了 10 个阶段的执行步骤、质量门禁（40+ 项 Checklist）、约束条件（比如不允许 Lorem Ipsum、不允许硬编码密钥、不允许超过 15 个依赖）以及异常处理（比如域名不一致时的自动修正逻辑）。AI Agent 加载这份协议后，像执行 SOP 一样逐步完成。我只需要在最后去 Google Search Console 手动提交 sitemap，这是 AI 无法代替的操作。

Q: 技术栈是怎么选的？

Next.js SSG + Tailwind + MDX + Vercel。选型逻辑是：SEO 优先（SSG 静态生成、JSON-LD 结构化数据、自动 sitemap）+ 速度优先（Tailwind 开发快、MDX 内容管理轻量、Vercel 部署零配置）+ 成本优先（Vercel Hobby 免费、不引入 CMS 和数据库）。整个站点是纯静态的，没有后端，Lighthouse Performance 保持 90+。

Q: Monorepo 方案怎么处理多站点的构建效率？

靠 Vercel 的 Ignored Build Step 机制。每个站点的 Vercel 项目配置了 git diff --quiet HEAD~1 HEAD -- .，意思是"如果这次 push 没有改动我这个子目录下的文件，就跳过构建"。所以推一次代码，只有真正有变更的站点会触发构建，其他站不受影响。7 个站共享一个仓库，但构建互不干扰。

Q: 如何保证每个站的质量一致？

三层质量门禁：第一层是 CHECKLIST.md 里 40+ 项静态检查（构建/SEO/性能/安全/合规），AI 逐项执行并修复；第二层是 check-site.sh 部署后自动 curl 所有页面做健康检查；第三层是 Playwright MCP 在真实浏览器里做交互测试，验证 Cookie 弹窗、导航、移动端菜单等交互功能。这三层是确定性的检查，不受 AI 模型随机性影响。

Q: 遇到过什么比较棘手的问题？

最典型的是 SSR 水合失败。Cookie 弹窗组件用了 useState(() => localStorage.getItem(...)) 来读取用户之前的选择，但服务端渲染时 localStorage 不存在，导致服务端和客户端渲染结果不一致，React 跳过水合，所有按钮的点击事件都失效了。页面看起来完全正常，但一个按钮都点不了。排查了很久才定位到水合问题，最终用 useSyncExternalStore 解决。这个经历也促使我在流水线中加入了 Playwright 交互测试环节。

Q: 如何衡量一个站点是否成功？

用 Google Search Console 的展示量作为 Day 30 的判定指标。新站 30 天内几乎没有点击量，但展示量能说明 Google 是否已经把你和某些搜索词关联。> 500 展示量是赢家候选，< 100 大概率淘汰，0 直接砍。评估期内不追加任何内容，5 篇种子文章就是对照实验——如果 niche 本身没潜力，加再多内容也没用。

Q: 这个项目最大的收获是什么？

两个层面。技术层面：深入理解了 Next.js SSG/SSR 的水合机制、Vercel 的 Monorepo 部署模式、SEO 结构化数据的最佳实践，以及如何用 AI Agent 的 Skill 机制把复杂流程变成可复用、可版本控制的自动化协议。业务层面：学到了"数据驱动 + 快速迭代"的产品思维——不预判市场，而是用低成本试错 + 数据筛选来找到真正有需求的领域。

Q: 你觉得 AI Agent 做建站和人工建站最大的区别是什么？

不是"更快"，而是确定性。人工建站每次质量参差不齐，取决于状态、经验、细心程度。Skill 协议把质量标准固化为 40+ 项可检查的规则，每次执行都是同样的标准。AI 的价值不是替代程序员，而是把"已知的最佳实践"变成零成本可重复执行的流程。真正需要人来做的是策略判断——选什么领域、什么时候加码什么时候止损。