seo-audit-report

SEO 审计报告（脚手架说明）

当用户希望在浏览器中反复检查 Search Console 导出数据或连接数据，并生成交互式客户端报告时，请使用此技能。

上下文与预检

在开始探索或实施之前，先运行 ../docs/credentials-and-tooling.md 中的共享预检。如果 .seo-context.md 已存在，请复用它。根据可访问的 URL 前缀和 sc-domain: 变体，确定项目的规范 GSC 媒体资源。记录尚未解决的假设，不要臆造业务优先级或编辑权限。

所需输入

• 项目目录名称。
• 数据源：实时连接的 GSC 数据，或从已连接的 MCP 创建的导出文件。
• 持久化目标：保存在浏览器 IndexedDB 中的序列化 sql.js 数据库。

工具与凭据

• 认证模式：mcp
• 要求：通过所需 MCP 连接 GSC
• 输入路径：实时 GSC 数据，或物化为 JSON/CSV 的 MCP 导出文件
• 回退方案：无

工作流

1. 搭建项目脚手架

   • 运行 npm create vite@latest <project-name> -- --template react-ts（如果更偏好 Bun，也可以运行 bun create vite@latest ...）。
   • 进入新目录并安装依赖（npm install/bun install）。
   • 除非报告需要不同的路由或入口点，否则保留生成的项目结构。

2. 添加依赖

   • 安装 react、react-dom（如果尚未安装）以及 zod。
   • 安装运行时辅助库：用于浏览器内 SQLite 引擎的 sql.js，以及用于持久化导出数据库字节的 idb-keyval。
   • 使 typescript + vite 开发依赖与模板保持一致。

3. 实现数据层

   • 使用 sql-wasm.wasm 包配置 sql.js，并将初始化封装在可复用的辅助函数中。
   • 将 CSV 和 JSON 输入解析为 { date, query, page, clicks, impressions, ctr, position }，转换数值字段，并一致地处理缺失的可选值。
   • 将规范化后的行存入 gsc_rows 表，并为 date、query 和 page 建立索引。
   • 导入后将数据库导出为字节，并使用 idb-keyval 持久化；应用加载时恢复这些字节。

4. 实现报告视图

   • 展示总点击量、展示次数、CTR 和加权排名，同时展示热门查询、热门网页和 CTR 差距机会。
   • 将机会阈值和日期/网页/查询筛选器设为可见且可调整，不要将它们隐藏在查询代码中。
   • 包含文件导入、从 /gsc/latest.json 获取数据的可选功能、自定义筛选器和重置控件。

5. 完善并记录脚手架

   • 使用 CSS 变量和卡片/网格布局美化页面，并以易读性为先，包括粘性页眉、提示框和窄文本宽度。
   • 如有助于展示流程，可添加小型示例导出文件，例如 public/gsc/latest.json。
   • 在 README 或附近的注释中说明接受的导入架构、持久化模型和 CTR 机会启发式规则。

6. 运行并验证

   • 使用 npm run dev 或 bun run dev 启动开发服务器，并加载具有代表性的 CSV/JSON 导出文件。
   • 测试导入、重新加载后的持久化、筛选、重置以及可选的 /gsc/latest.json 获取路径。检查浏览器控制台是否有 worker/WASM 或 IndexedDB 错误。
   • 运行项目提供的类型检查、lint 和构建命令。在 README 中说明已运行的命令，以及实时 GSC 或浏览器方面的限制。
   • 请注意，sql.js 会在浏览器中执行 SQLite；IndexedDB 存储的是序列化数据库字节，而不是 SQLite 引擎。