geo-ai-search-optimization 1.3.14 → 1.4.0

package/README.md

@@ -63,6 +63,24 @@ geo-ai-search-optimization agent-orchestrator ./reports/agent-playbook-pack.json
 - 做完之后下一条是什么
 - 可直接复制给 agent 的 orchestrator prompt
 
+## Page Audit 命令
+
+如果你不想一次看整站，而是想先判断“这个单页为什么不容易被生成式搜索理解与引用”，可以直接用 `page-audit`：
+
+```bash
+geo-ai-search-optimization page-audit https://example.com/blog/geo-guide
+geo-ai-search-optimization page-audit ./content/posts/geo-guide.mdx
+geo-ai-search-optimization page-audit ./content/posts/geo-guide.mdx --json --out ./reports/page-audit.json
+```
+
+它会输出：
+
+- 单页 GEO 分数
+- 页面级问题区域
+- 推荐新增模块
+- rewrite brief
+- 可直接交给 agent 的 page-level prompt
+
 ## Agent Resume 命令
 
 如果 GEO 工作已经做过一轮或多轮，你不想让下一个 agent 从头重新判断，而是想让它从最近一个可靠恢复点继续，可以直接用 `agent-resume`：
@@ -938,6 +956,13 @@ geo-ai-search-optimization help
 - `agent-handoff / apply-plan / completion-report / handoff-bundle / share-pack / export-pack / html-pack / publish-pack / exec-summary / fix-plan / owner-board / meeting-pack / pm-brief / roadmap / report` 已统一进入 registry
 - CLI 更接近所有命令族都使用显式 registry metadata 的结构
 
+## New in 1.4.0
+
+- 新增 `page-audit`
+- 支持对单个 URL 或本地单页文件做 GEO 页面级审计
+- 输出页面分数、问题区域、推荐新增模块、rewrite brief 与 agent prompt
+- 产品能力从“站点级诊断”扩展到“页面级修复入口”
+
 ## New in 1.2.20
 
 - 新增 `agent-continue`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.3.14",
+  "version": "1.4.0",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/src/cli-site-ops-commands.js

@@ -13,6 +13,7 @@ import {
   writeInteractiveOnboardingOutput
 } from "./interactive-onboarding.js";
 import { createLlmsTxt } from "./llms-txt.js";
+import { auditPage, renderPageAuditMarkdown, writePageAuditOutput } from "./page-audit.js";
 import { createQuickStartPlan, renderQuickStartMarkdown, writeQuickStartOutput } from "./quick-start.js";
 import { renderScanMarkdown, scanProject, writeScanOutput } from "./scan.js";
 import { createSchemaTemplate } from "./schema.js";
@@ -23,6 +24,7 @@ export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization quick-start [--json] [--out <file>]",
   "  geo-ai-search-optimization onboard [--url <website-url>] [--goal <goal>] [--existing-assets <list>] [--json] [--out <file>]",
   "  geo-ai-search-optimization onboard-url <website-url> [--json] [--out <file>]",
+  "  geo-ai-search-optimization page-audit <url-or-file> [--json] [--out <file>]",
   "  geo-ai-search-optimization init-llms [target-dir] [--site-name <name>] [--site-url <url>] [--overwrite] [--json]",
   "  geo-ai-search-optimization init-schema <type> [target-dir] [--site-url <url>] [--overwrite] [--json]",
   "  geo-ai-search-optimization audit <project-path> [--json] [--out <file>] [--max-file-size <bytes>] [--max-examples <count>]",
@@ -75,6 +77,21 @@ const handleOnboardUrl = createStructuredOutputCommandHandler({
   getOutputJson: (args) => hasFlag(args, "--json")
 });
 
+const handlePageAudit = createStructuredOutputCommandHandler({
+  commandLabel: "单页审计",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) {
+      throw new Error("page-audit requires a URL or file path");
+    }
+
+    return auditPage(input, {});
+  },
+  renderMarkdown: (report) => `${renderPageAuditMarkdown(report)}\n`,
+  writeOutput: writePageAuditOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
 const handleInitLlms = createActionCommandHandler({
   execute: async (args) =>
     createLlmsTxt({
@@ -153,6 +170,7 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   "quick-start": handleQuickStart,
   onboard: handleInteractiveOnboard,
   "onboard-url": handleOnboardUrl,
+  "page-audit": handlePageAudit,
   "init-llms": handleInitLlms,
   "init-schema": handleInitSchema,
   audit: handleAudit,

package/src/index.js

@@ -34,6 +34,7 @@ export { installSkill } from "./install-skill.js";
 export { runCli } from "./cli.js";
 export { runDoctor, renderDoctorMarkdown } from "./doctor.js";
 export { createLlmsTxt } from "./llms-txt.js";
+export { auditPage, renderPageAuditMarkdown, writePageAuditOutput } from "./page-audit.js";
 export { createExecSummary, renderExecSummaryMarkdown, writeExecSummaryOutput } from "./exec-summary.js";
 export { createExportPack, renderExportPackMarkdown, writeExportPack } from "./export-pack.js";
 export { createMeetingPack, renderMeetingPackMarkdown, writeMeetingPackOutput } from "./meeting-pack.js";

package/src/page-audit.js

@@ -0,0 +1,464 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SIGNAL_PATTERNS, writeScanOutput } from "./scan.js";
+
+function isUrlInput(input) {
+  return /^https?:\/\//i.test(input);
+}
+
+function normalizeUrl(inputUrl) {
+  const normalizedInput = /^https?:\/\//i.test(inputUrl) ? inputUrl : `https://${inputUrl}`;
+  return new URL(normalizedInput);
+}
+
+async function fetchText(url) {
+  const response = await fetch(url, {
+    redirect: "follow",
+    headers: {
+      "user-agent": "geo-ai-search-optimization/1.4.0"
+    }
+  });
+
+  const text = await response.text();
+  return {
+    ok: response.ok,
+    status: response.status,
+    url: response.url,
+    text
+  };
+}
+
+async function readLocalFile(inputPath) {
+  const resolvedPath = path.resolve(inputPath);
+  const text = await fs.readFile(resolvedPath, "utf8");
+  return {
+    path: resolvedPath,
+    text
+  };
+}
+
+function extractTitle(text) {
+  const htmlMatch = text.match(/<title[^>]*>(.*?)<\/title>/i);
+  if (htmlMatch) {
+    return htmlMatch[1].trim();
+  }
+
+  const markdownMatch = text.match(/^#\s+(.+)$/m);
+  return markdownMatch ? markdownMatch[1].trim() : null;
+}
+
+function extractMetaDescription(text) {
+  const htmlMatch = text.match(/<meta[^>]+name=["']description["'][^>]+content=["']([^"']+)["']/i);
+  if (htmlMatch) {
+    return htmlMatch[1].trim();
+  }
+
+  const markdownMatch = text.match(/^description:\s*["']?(.+?)["']?$/im);
+  return markdownMatch ? markdownMatch[1].trim() : null;
+}
+
+function extractCanonical(text) {
+  const htmlMatch = text.match(/<link[^>]+rel=["']canonical["'][^>]+href=["']([^"']+)["']/i);
+  if (htmlMatch) {
+    return htmlMatch[1].trim();
+  }
+
+  const frontmatterMatch = text.match(/^canonical:\s*["']?(.+?)["']?$/im);
+  return frontmatterMatch ? frontmatterMatch[1].trim() : null;
+}
+
+function extractHeadings(text) {
+  const headings = [];
+  const markdownMatches = text.matchAll(/^(#{1,6})\s+(.+)$/gm);
+  for (const match of markdownMatches) {
+    headings.push({
+      level: match[1].length,
+      text: match[2].trim()
+    });
+  }
+
+  const htmlMatches = text.matchAll(/<h([1-6])[^>]*>(.*?)<\/h\1>/gim);
+  for (const match of htmlMatches) {
+    headings.push({
+      level: Number.parseInt(match[1], 10),
+      text: match[2].replace(/<[^>]+>/g, "").trim()
+    });
+  }
+
+  return headings;
+}
+
+function extractFirstParagraph(text) {
+  const stripped = text
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\r/g, "");
+
+  const paragraphs = stripped
+    .split(/\n\s*\n/)
+    .map((entry) => entry.replace(/\s+/g, " ").trim())
+    .filter(Boolean);
+
+  return paragraphs[0] || null;
+}
+
+function buildSignalSummary(reference, text) {
+  return Object.fromEntries(
+    Object.keys(SIGNAL_PATTERNS).map((signal) => {
+      const matched = SIGNAL_PATTERNS[signal].test(text);
+      return [
+        signal,
+        {
+          count: matched ? 1 : 0,
+          examples: matched ? [reference] : []
+        }
+      ];
+    })
+  );
+}
+
+const PAGE_SCORE_RULES = [
+  {
+    key: "title",
+    label: "页面有清晰 title / 主标题",
+    maxPoints: 12,
+    passed: (page) => Boolean(page.metadata.title)
+  },
+  {
+    key: "metaDescription",
+    label: "页面有摘要描述",
+    maxPoints: 8,
+    passed: (page) => Boolean(page.metadata.metaDescription)
+  },
+  {
+    key: "canonical",
+    label: "页面有 canonical",
+    maxPoints: 8,
+    passed: (page) => Boolean(page.metadata.canonical)
+  },
+  {
+    key: "jsonLd",
+    label: "页面有结构化数据",
+    maxPoints: 12,
+    passed: (page) => page.signals.json_ld.count > 0
+  },
+  {
+    key: "author",
+    label: "页面有作者 / 时间 / 审校信号",
+    maxPoints: 10,
+    passed: (page) => page.signals.author_markers.count > 0
+  },
+  {
+    key: "citations",
+    label: "页面有来源链接",
+    maxPoints: 10,
+    passed: (page) => page.signals.citations.count > 0
+  },
+  {
+    key: "qaHeadings",
+    label: "页面结构适合被提取答案",
+    maxPoints: 12,
+    passed: (page) => page.signals.qa_headings.count > 0 || page.headingStats.questionHeadingCount > 0
+  },
+  {
+    key: "comparison",
+    label: "页面覆盖比较 / 决策信息",
+    maxPoints: 8,
+    passed: (page) => page.signals.comparison_intent.count > 0
+  },
+  {
+    key: "evidence",
+    label: "页面有第一方证据或方法论",
+    maxPoints: 10,
+    passed: (page) => page.signals.original_research.count > 0
+  },
+  {
+    key: "directAnswer",
+    label: "页面开头可快速提取直接答案",
+    maxPoints: 10,
+    passed: (page) => Boolean(page.directAnswerCandidate && page.directAnswerCandidate.length >= 50)
+  }
+];
+
+function evaluatePageScore(page) {
+  const checks = PAGE_SCORE_RULES.map((rule) => {
+    const passed = rule.passed(page);
+    return {
+      key: rule.key,
+      label: rule.label,
+      passed,
+      maxPoints: rule.maxPoints,
+      pointsAwarded: passed ? rule.maxPoints : 0
+    };
+  });
+
+  const score = checks.reduce((sum, check) => sum + check.pointsAwarded, 0);
+  return {
+    score,
+    maxScore: 100,
+    checks
+  };
+}
+
+function getScoreLabel(score) {
+  if (score >= 80) {
+    return "稳固";
+  }
+  if (score >= 60) {
+    return "可优化";
+  }
+  if (score >= 40) {
+    return "偏弱";
+  }
+  return "需要重做";
+}
+
+function buildProblemAreas(page) {
+  const areas = [];
+
+  if (!page.metadata.title || !page.metadata.metaDescription || !page.metadata.canonical) {
+    areas.push({
+      area: "页面元信息",
+      severity: !page.metadata.title ? "高" : "中",
+      issues: [
+        !page.metadata.title ? "缺少 title / 主标题" : null,
+        !page.metadata.metaDescription ? "缺少摘要描述" : null,
+        !page.metadata.canonical ? "缺少 canonical" : null
+      ].filter(Boolean),
+      whyItMatters: "模型和搜索系统需要先理解这页是什么、应该归到哪个 canonical 实体上。"
+    });
+  }
+
+  if (page.signals.json_ld.count === 0 || page.signals.author_markers.count === 0 || page.signals.citations.count === 0) {
+    areas.push({
+      area: "可信度与引用",
+      severity: page.signals.citations.count === 0 ? "高" : "中",
+      issues: [
+        page.signals.json_ld.count === 0 ? "缺少结构化数据" : null,
+        page.signals.author_markers.count === 0 ? "缺少作者 / 更新时间 / 审校信号" : null,
+        page.signals.citations.count === 0 ? "缺少来源链接" : null
+      ].filter(Boolean),
+      whyItMatters: "如果页面没有可信来源、作者和结构化实体，AI 搜索更难放心引用。"
+    });
+  }
+
+  if (page.headingStats.questionHeadingCount === 0 && page.signals.qa_headings.count === 0) {
+    areas.push({
+      area: "答案可提取性",
+      severity: "高",
+      issues: ["缺少问答式或决策式标题", "页面结构不够 answer-first"],
+      whyItMatters: "模型需要在很短上下文里抓到直接答案、适用对象和限制条件。"
+    });
+  }
+
+  if (page.signals.original_research.count === 0 && page.signals.comparison_intent.count === 0) {
+    areas.push({
+      area: "差异化内容",
+      severity: "中",
+      issues: ["缺少方法论 / 第一方证据", "缺少比较与决策内容"],
+      whyItMatters: "如果页面没有独特证据和决策信息，就很难在生成式结果里占据引用位置。"
+    });
+  }
+
+  return areas;
+}
+
+function buildRecommendedBlocks(page) {
+  const blocks = [];
+  if (!page.directAnswerCandidate || page.directAnswerCandidate.length < 50) {
+    blocks.push("在首屏补一个直接答案摘要块，先回答“这是什么 / 适合谁 / 主要限制是什么”。");
+  }
+  if (page.headingStats.questionHeadingCount === 0) {
+    blocks.push("补 2 到 4 个问答式 H2，例如“适合谁”“什么时候不适合”“和替代方案差别是什么”。");
+  }
+  if (page.signals.citations.count === 0) {
+    blocks.push("增加来源链接或证据区块，给关键事实、数据和判断补出处。");
+  }
+  if (page.signals.original_research.count === 0) {
+    blocks.push("补第一方证据区块，例如方法论、流程、案例、截图、基准或内部数据。");
+  }
+  if (page.signals.comparison_intent.count === 0) {
+    blocks.push("增加 comparison / alternatives / trade-offs 模块，帮助模型提取决策信息。");
+  }
+  if (page.signals.json_ld.count === 0) {
+    blocks.push("补与页面可见内容一致的 JSON-LD。");
+  }
+  return blocks;
+}
+
+function buildRewriteBrief(page, problems, recommendedBlocks) {
+  return {
+    objective: "把当前页面改成更容易被生成式搜索引擎理解、提取、引用的 answer-first 页面。",
+    audience: "负责该页面的 PM、内容负责人、SEO 或 agent。",
+    keep: [
+      page.metadata.title ? `保留核心主题：${page.metadata.title}` : "保留当前页面的核心主题，不要改成另一个意图。",
+      "保留事实准确性，不用为了 SEO 或 GEO 添加页面没有证据支撑的说法。"
+    ],
+    change: problems.flatMap((problem) => problem.issues).slice(0, 6),
+    addSections: recommendedBlocks,
+    openingPattern: "用 2 到 4 句先给直接答案，再说明适用对象、关键限制与下一步。",
+    evidencePattern: "给结论补来源链接、案例、方法论、数据或截图说明。",
+    schemaHint:
+      page.signals.json_ld.count > 0
+        ? "保留现有 schema，但确认与页面可见内容一致。"
+        : "优先考虑 Article / FAQPage / Product / Organization 中最贴近页面真实内容的 schema。"
+  };
+}
+
+function buildAgentPrompt(page, rewriteBrief) {
+  return [
+    "请先把这页当成单页 GEO 修复任务处理。",
+    `当前页面：${page.reference}`,
+    `当前分数：${page.score.score}/${page.score.maxScore}（${getScoreLabel(page.score.score)}）`,
+    `优先改动：${rewriteBrief.change.slice(0, 4).join("；") || "补直接答案、证据与结构化信息"}`,
+    "先重写页面 opening，再补问答式标题、来源链接、证据区块和最合适的 schema。",
+    "如果是代码仓库，请优先找模板、metadata helper、schema 生成点，而不是只改单一页面文案。",
+    "完成后重新跑 page-audit，确认分数和问题区域是否改善。"
+  ].join(" ");
+}
+
+function buildSummary(page, problems) {
+  if (page.score.score >= 80) {
+    return "这页已经具备较好的 GEO 基础，下一步重点是增强差异化证据与可引用素材。";
+  }
+
+  if (problems.length === 0) {
+    return "这页没有明显结构性缺口，可以继续加强引用资产和第一方证据。";
+  }
+
+  return `这页当前最需要优先处理的是${problems[0].area}，否则模型很难稳定理解并引用页面内容。`;
+}
+
+export async function auditPage(input, options = {}) {
+  const sourceType = isUrlInput(input) ? "url" : "file";
+  let source;
+
+  if (sourceType === "url") {
+    const url = normalizeUrl(input);
+    const result = await fetchText(url);
+    if (!result.ok) {
+      throw new Error(`抓取失败：${url.toString()}（状态码 ${result.status}）`);
+    }
+    source = {
+      reference: result.url,
+      content: result.text,
+      fetchStatus: result.status
+    };
+  } else {
+    const result = await readLocalFile(input);
+    source = {
+      reference: result.path,
+      content: result.text,
+      fetchStatus: null
+    };
+  }
+
+  const headings = extractHeadings(source.content);
+  const page = {
+    kind: "geo-page-audit",
+    input,
+    sourceType,
+    reference: source.reference,
+    fetchStatus: source.fetchStatus,
+    metadata: {
+      title: extractTitle(source.content),
+      metaDescription: extractMetaDescription(source.content),
+      canonical: extractCanonical(source.content)
+    },
+    directAnswerCandidate: extractFirstParagraph(source.content),
+    headingStats: {
+      totalHeadingCount: headings.length,
+      questionHeadingCount: headings.filter((heading) => heading.text.includes("?") || heading.text.includes("？")).length
+    },
+    headings: headings.slice(0, options.maxHeadings || 12),
+    signals: buildSignalSummary(source.reference, source.content)
+  };
+
+  page.score = evaluatePageScore(page);
+  page.scoreLabel = getScoreLabel(page.score.score);
+  page.problemAreas = buildProblemAreas(page);
+  page.recommendedBlocks = buildRecommendedBlocks(page);
+  page.rewriteBrief = buildRewriteBrief(page, page.problemAreas, page.recommendedBlocks);
+  page.summary = buildSummary(page, page.problemAreas);
+  page.agentPrompt = buildAgentPrompt(page, page.rewriteBrief);
+
+  return page;
+}
+
+export function renderPageAuditMarkdown(report) {
+  const lines = [
+    "# GEO 单页审计",
+    "",
+    `- 输入：\`${report.input}\``,
+    `- 来源类型：\`${report.sourceType}\``,
+    `- 分析对象：\`${report.reference}\``,
+    `- GEO 单页分数：\`${report.score.score}/${report.score.maxScore}\`（${report.scoreLabel}）`,
+    `- 总结：${report.summary}`,
+    ""
+  ];
+
+  if (report.fetchStatus !== null) {
+    lines.push(`- 抓取状态：\`${report.fetchStatus}\``);
+    lines.push("");
+  }
+
+  lines.push("## 页面快照", "");
+  lines.push(`- title：\`${report.metadata.title ?? "缺失"}\``);
+  lines.push(`- meta description：\`${report.metadata.metaDescription ?? "缺失"}\``);
+  lines.push(`- canonical：\`${report.metadata.canonical ?? "缺失"}\``);
+  lines.push(`- 首段直接答案候选：${report.directAnswerCandidate ? report.directAnswerCandidate.slice(0, 180) : "缺失"}`);
+
+  lines.push("", "## 问题区域", "");
+  if (report.problemAreas.length === 0) {
+    lines.push("- 当前没有明显的页面级高风险区域。");
+  } else {
+    for (const area of report.problemAreas) {
+      lines.push(`- ${area.area}｜${area.severity}｜${area.issues.join("、")}`);
+      lines.push(`  ${area.whyItMatters}`);
+    }
+  }
+
+  lines.push("", "## 推荐新增模块", "");
+  for (const item of report.recommendedBlocks) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## Rewrite Brief", "");
+  lines.push(`- 目标：${report.rewriteBrief.objective}`);
+  lines.push(`- Opening pattern：${report.rewriteBrief.openingPattern}`);
+  lines.push(`- Evidence pattern：${report.rewriteBrief.evidencePattern}`);
+  lines.push(`- Schema hint：${report.rewriteBrief.schemaHint}`);
+
+  lines.push("", "## 建议保留", "");
+  for (const item of report.rewriteBrief.keep) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 建议调整", "");
+  for (const item of report.rewriteBrief.change) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 建议新增段落", "");
+  for (const item of report.rewriteBrief.addSections) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 页面标题快照", "");
+  for (const heading of report.headings) {
+    lines.push(`- H${heading.level}：${heading.text}`);
+  }
+
+  lines.push("", "## 评分明细", "");
+  for (const check of report.score.checks) {
+    lines.push(`- ${check.label}：\`${check.passed}\`（${check.pointsAwarded}/${check.maxPoints}）`);
+  }
+
+  lines.push("", "## Agent Prompt", "", report.agentPrompt, "");
+  return lines.join("\n");
+}
+
+export async function writePageAuditOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}