geo-ai-search-optimization 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "2.2.0",
+  "version": "2.3.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

@@ -54,6 +54,9 @@ import { generateAutoFix, renderAutoFixMarkdown, writeAutoFixOutput } from "./au
 import { savePageSnapshot, buildPageTrend, renderPageTrendMarkdown, writePageTrendOutput } from "./page-snapshot.js";
 import { diagnose, renderDiagnoseMarkdown, writeDiagnoseOutput } from "./diagnose.js";
 import { comparePages, renderCompareMarkdown, writeCompareOutput } from "./compare.js";
+import { deepBenchmark, renderDeepBenchmarkMarkdown, writeDeepBenchmarkOutput } from "./deep-benchmark.js";
+import { quickSummary, renderSummaryMarkdown } from "./summary.js";
+import { fullPageAuditToCsv, batchFullPageAuditToCsv, deepBenchmarkToCsv, compareToCsv } from "./csv-export.js";
 
 export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization doctor [--json]",
@@ -99,7 +102,9 @@ export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization auto-fix <url-or-file> [--json] [--out <file>]",
   "  geo-ai-search-optimization page-trend <url-or-file> [--data-dir <dir>] [--last <n>] [--json] [--out <file>]",
   "  geo-ai-search-optimization diagnose <url-or-dir-or-file> [--json] [--out <file>]",
-  "  geo-ai-search-optimization compare <url-or-file-A> <url-or-file-B> [--json] [--out <file>]"
+  "  geo-ai-search-optimization compare <url-or-file-A> <url-or-file-B> [--json] [--csv] [--out <file>]",
+  "  geo-ai-search-optimization deep-benchmark <url> --competitors <url1,url2,...> [--concurrency <n>] [--json] [--csv] [--out <file>]",
+  "  geo-ai-search-optimization summary <url-or-dir-or-file>"
 ];
 
 const passthroughWriteOutput = async (outputPath) => outputPath;
@@ -705,6 +710,40 @@ const handleBatchFullPageAudit = createStructuredOutputCommandHandler({
   getOutputJson: (args) => hasFlag(args, "--json")
 });
 
+const handleDeepBenchmark = createStructuredOutputCommandHandler({
+  commandLabel: "deep benchmark",
+  execute: async (args) => {
+    const ownUrl = args.find((value) => !value.startsWith("-"));
+    if (!ownUrl) throw new Error("deep-benchmark requires your URL as the first argument");
+    const competitorsRaw = getFlagValue(args, "--competitors");
+    if (!competitorsRaw) throw new Error("deep-benchmark requires --competitors <url1,url2,...>");
+    const competitorUrls = competitorsRaw.split(",").map((u) => u.trim()).filter(Boolean);
+    const concurrencyValue = getFlagValue(args, "--concurrency");
+    return deepBenchmark(ownUrl, competitorUrls, {
+      concurrency: concurrencyValue ? parsePositiveInteger(concurrencyValue, "--concurrency") : 2
+    });
+  },
+  renderMarkdown: (report, args) => {
+    if (args && hasFlag(args, "--csv")) return deepBenchmarkToCsv(report);
+    return renderDeepBenchmarkMarkdown(report);
+  },
+  writeOutput: writeDeepBenchmarkOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleSummary = async (args) => {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) throw new Error("summary requires a URL, file path, or directory");
+  const result = await quickSummary(input);
+
+  if (hasFlag(args, "--json")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(renderSummaryMarkdown(result));
+};
+
 const handleDiagnose = createStructuredOutputCommandHandler({
   commandLabel: "diagnose",
   execute: async (args) => {
@@ -724,11 +763,34 @@ const handleCompare = createStructuredOutputCommandHandler({
     if (nonFlags.length < 2) throw new Error("compare requires two URLs or file paths: <A> <B>");
     return comparePages(nonFlags[0], nonFlags[1]);
   },
-  renderMarkdown: renderCompareMarkdown,
+  renderMarkdown: (report) => renderCompareMarkdown(report),
   writeOutput: writeCompareOutput,
-  getOutputJson: (args) => hasFlag(args, "--json")
+  getOutputJson: (args) => {
+    if (hasFlag(args, "--csv")) return false; // Let renderMarkdown handle CSV
+    return hasFlag(args, "--json");
+  }
 });
 
+// Override compare to support --csv
+const _originalCompare = handleCompare;
+const handleCompareCsv = async (args) => {
+  if (hasFlag(args, "--csv")) {
+    const nonFlags = args.filter((value) => !value.startsWith("-"));
+    if (nonFlags.length < 2) throw new Error("compare requires two URLs or file paths: <A> <B>");
+    const result = await comparePages(nonFlags[0], nonFlags[1]);
+    const csv = compareToCsv(result);
+    const outputPath = getFlagValue(args, "--out");
+    if (outputPath) {
+      const resolved = await writeCompareOutput(outputPath, csv);
+      process.stdout.write(`已保存 compare CSV：${resolved}\n`);
+    } else {
+      process.stdout.write(csv + "\n");
+    }
+    return;
+  }
+  return _originalCompare(args);
+};
+
 const handleAutoFix = createStructuredOutputCommandHandler({
   commandLabel: "auto-fix",
   execute: async (args) => {
@@ -851,5 +913,7 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   "auto-fix": handleAutoFix,
   "page-trend": handlePageTrend,
   diagnose: handleDiagnose,
-  compare: handleCompare
+  compare: handleCompareCsv,
+  "deep-benchmark": handleDeepBenchmark,
+  summary: handleSummary
 };

package/src/csv-export.js

@@ -0,0 +1,112 @@
+/**
+ * CSV export utility for structured audit data.
+ */
+
+function escCsv(value) {
+  if (value === null || value === undefined) return "";
+  const str = String(value);
+  if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+function toCsvRow(values) {
+  return values.map(escCsv).join(",");
+}
+
+/**
+ * Convert a full-page-audit result to CSV.
+ */
+export function fullPageAuditToCsv(report) {
+  const rows = [toCsvRow(["Dimension", "Score", "Label", "Weight"])];
+
+  const weights = {
+    base: 15, citability: 12, eeat: 12, readability: 8, headingStructure: 6,
+    internalLinks: 5, socialMeta: 5, platformReady: 8, schema: 7,
+    freshness: 8, security: 7, topics: 7
+  };
+
+  for (const [dim, data] of Object.entries(report.dimensions || {})) {
+    rows.push(toCsvRow([dim, data.score, data.label, `${weights[dim] || 0}%`]));
+  }
+
+  rows.push(toCsvRow(["COMPOSITE", report.compositeScore, report.compositeLabel, "100%"]));
+  return rows.join("\n");
+}
+
+/**
+ * Convert a batch-full-page-audit result to CSV.
+ */
+export function batchFullPageAuditToCsv(report) {
+  const dimKeys = Object.keys(report.dimensionAverages || {});
+  const header = ["URL", "Composite", "Label", ...dimKeys];
+  const rows = [toCsvRow(header)];
+
+  for (const result of report.results || []) {
+    const dimScores = dimKeys.map((k) => result.dimensions?.[k]?.score ?? "");
+    rows.push(toCsvRow([result.input, result.compositeScore, result.compositeLabel, ...dimScores]));
+  }
+
+  // Averages row
+  const avgScores = dimKeys.map((k) => report.dimensionAverages[k] ?? "");
+  rows.push(toCsvRow(["AVERAGE", report.avgScore, "", ...avgScores]));
+
+  return rows.join("\n");
+}
+
+/**
+ * Convert a deep-benchmark result to CSV.
+ */
+export function deepBenchmarkToCsv(report) {
+  // Score board
+  const sections = [];
+
+  sections.push("# Score Board");
+  const boardRows = [toCsvRow(["Rank", "URL", "Composite", "Label", "IsOwn"])];
+  report.scoreBoard.forEach((entry, i) => {
+    boardRows.push(toCsvRow([i + 1, entry.url, entry.composite, entry.label, entry.isOwn]));
+  });
+  sections.push(boardRows.join("\n"));
+
+  // Dimension comparison
+  sections.push("\n# Dimension Comparison");
+  const dimHeader = ["Dimension", "You", "CompetitorAvg", "Delta", "Rank"];
+  const dimRows = [toCsvRow(dimHeader)];
+  for (const [dim, data] of Object.entries(report.dimensionComparison || {})) {
+    dimRows.push(toCsvRow([dim, data.own, data.competitorAvg, data.delta, data.rank]));
+  }
+  sections.push(dimRows.join("\n"));
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Convert a compare result to CSV.
+ */
+export function compareToCsv(report) {
+  const rows = [toCsvRow(["Dimension", "Page A", "Page B", "Delta", "Winner"])];
+
+  for (const [dim, data] of Object.entries(report.dimensions || {})) {
+    rows.push(toCsvRow([dim, data.scoreA, data.scoreB, data.delta, data.winner]));
+  }
+
+  rows.push(toCsvRow(["COMPOSITE", report.compositeA, report.compositeB, report.compositeDelta, report.overallWinner]));
+  return rows.join("\n");
+}
+
+/**
+ * Generic object-array to CSV converter.
+ */
+export function arrayToCsv(items, columns) {
+  if (!items || items.length === 0) return "";
+
+  const keys = columns || Object.keys(items[0]);
+  const rows = [toCsvRow(keys)];
+
+  for (const item of items) {
+    rows.push(toCsvRow(keys.map((k) => item[k])));
+  }
+
+  return rows.join("\n");
+}

package/src/deep-benchmark.js

@@ -0,0 +1,231 @@
+import { writeScanOutput } from "./scan.js";
+import { fullPageAudit } from "./full-page-audit.js";
+
+/**
+ * Deep benchmark: full 12-dimension comparison against N competitors.
+ */
+
+async function auditSafe(url, options) {
+  try {
+    const result = await fullPageAudit(url, options);
+    return { ok: true, url, data: result };
+  } catch (err) {
+    return { ok: false, url, error: err.message };
+  }
+}
+
+export async function deepBenchmark(ownUrl, competitorUrls, options = {}) {
+  const concurrency = options.concurrency || 2;
+  const allUrls = [ownUrl, ...competitorUrls];
+
+  // Audit all URLs with concurrency
+  const results = [];
+  const chunks = [];
+  for (let i = 0; i < allUrls.length; i += concurrency) {
+    chunks.push(allUrls.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    const chunkResults = await Promise.all(chunk.map((url) => auditSafe(url, options)));
+    results.push(...chunkResults);
+  }
+
+  const ownResult = results[0];
+  const competitorResults = results.slice(1);
+  const successful = results.filter((r) => r.ok);
+
+  // Dimension comparison
+  const allDimKeys = new Set();
+  for (const r of successful) {
+    for (const key of Object.keys(r.data.dimensions)) {
+      allDimKeys.add(key);
+    }
+  }
+
+  const dimensionComparison = {};
+  for (const dim of allDimKeys) {
+    const ownScore = ownResult.ok ? (ownResult.data.dimensions[dim]?.score ?? 0) : null;
+    const compScores = competitorResults.map((r) =>
+      r.ok ? (r.data.dimensions[dim]?.score ?? 0) : null
+    );
+    const validCompScores = compScores.filter((s) => s !== null);
+    const avgComp = validCompScores.length > 0
+      ? Math.round(validCompScores.reduce((a, b) => a + b, 0) / validCompScores.length)
+      : null;
+
+    dimensionComparison[dim] = {
+      own: ownScore,
+      competitors: compScores,
+      competitorAvg: avgComp,
+      delta: ownScore !== null && avgComp !== null ? ownScore - avgComp : null,
+      rank: null // Computed below
+    };
+  }
+
+  // Compute ranks per dimension
+  for (const dim of allDimKeys) {
+    const scores = results
+      .filter((r) => r.ok)
+      .map((r) => ({ url: r.url, score: r.data.dimensions[dim]?.score ?? 0 }))
+      .sort((a, b) => b.score - a.score);
+
+    const ownRank = scores.findIndex((s) => s.url === ownUrl) + 1;
+    dimensionComparison[dim].rank = ownRank || null;
+  }
+
+  // Overall scores
+  const scoreBoard = results.map((r) => ({
+    url: r.url,
+    isOwn: r.url === ownUrl,
+    composite: r.ok ? r.data.compositeScore : null,
+    label: r.ok ? r.data.compositeLabel : "Failed",
+    error: r.ok ? null : r.error
+  })).sort((a, b) => (b.composite ?? -1) - (a.composite ?? -1));
+
+  const ownRank = scoreBoard.findIndex((s) => s.isOwn) + 1;
+
+  // Strengths and weaknesses vs competitor average
+  const strengths = [];
+  const weaknesses = [];
+
+  for (const [dim, data] of Object.entries(dimensionComparison)) {
+    if (data.delta === null) continue;
+    if (data.delta >= 10) strengths.push({ dimension: dim, delta: data.delta, rank: data.rank });
+    if (data.delta <= -10) weaknesses.push({ dimension: dim, delta: data.delta, rank: data.rank });
+  }
+
+  strengths.sort((a, b) => b.delta - a.delta);
+  weaknesses.sort((a, b) => a.delta - b.delta);
+
+  // Platform comparison
+  const platformComparison = [];
+  if (ownResult.ok && ownResult.data.platformSummary) {
+    for (const ownPlatform of ownResult.data.platformSummary) {
+      const compPlatformScores = competitorResults
+        .filter((r) => r.ok && r.data.platformSummary)
+        .map((r) => r.data.platformSummary.find((p) => p.platform === ownPlatform.platform)?.score ?? 0);
+      const avgCompPlatform = compPlatformScores.length > 0
+        ? Math.round(compPlatformScores.reduce((a, b) => a + b, 0) / compPlatformScores.length)
+        : 0;
+
+      platformComparison.push({
+        platform: ownPlatform.platform,
+        ownScore: ownPlatform.score,
+        competitorAvg: avgCompPlatform,
+        delta: ownPlatform.score - avgCompPlatform
+      });
+    }
+  }
+
+  // Actionable gaps
+  const gaps = weaknesses.map((w) => ({
+    dimension: w.dimension,
+    gap: Math.abs(w.delta),
+    action: `Improve ${w.dimension} (${Math.abs(w.delta)} points behind competitor average)`
+  }));
+
+  const ownComposite = ownResult.ok ? ownResult.data.compositeScore : 0;
+  const avgCompComposite = successful.length > 1
+    ? Math.round(successful.filter((r) => r.url !== ownUrl).reduce((sum, r) => sum + r.data.compositeScore, 0) / (successful.length - 1))
+    : null;
+
+  return {
+    kind: "geo-deep-benchmark",
+    ownUrl,
+    competitorUrls,
+    ownComposite,
+    competitorAvgComposite: avgCompComposite,
+    compositeDelta: avgCompComposite !== null ? ownComposite - avgCompComposite : null,
+    ownRank,
+    totalCompetitors: competitorUrls.length,
+    scoreBoard,
+    dimensionComparison,
+    strengths,
+    weaknesses,
+    gaps,
+    platformComparison,
+    successful: successful.length,
+    failed: results.length - successful.length,
+    summary: `Deep benchmark: You rank #${ownRank}/${results.length}. Composite: ${ownComposite} vs avg ${avgCompComposite ?? "—"}. ${strengths.length} strength(s), ${weaknesses.length} weakness(es).`
+  };
+}
+
+const DIM_LABELS = {
+  base: "Base", citability: "Citability", eeat: "E-E-A-T", readability: "Readability",
+  headingStructure: "Headings", internalLinks: "Links", socialMeta: "Social",
+  platformReady: "Platforms", schema: "Schema", freshness: "Freshness",
+  security: "Security", topics: "Topics"
+};
+
+export function renderDeepBenchmarkMarkdown(report) {
+  const lines = [
+    "# GEO Deep Benchmark",
+    "",
+    `- Your URL: \`${report.ownUrl}\``,
+    `- Competitors: \`${report.totalCompetitors}\``,
+    `- **Your rank: #${report.ownRank}/${report.scoreBoard.length}**`,
+    `- Your composite: \`${report.ownComposite}/100\` vs competitor avg \`${report.competitorAvgComposite ?? "—"}/100\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Score Board",
+    "",
+    "| Rank | URL | Composite | Label |",
+    "|------|-----|-----------|-------|"
+  ];
+
+  report.scoreBoard.forEach((entry, i) => {
+    const marker = entry.isOwn ? " **← You**" : "";
+    lines.push(`| ${i + 1} | ${entry.url.slice(0, 45)} | ${entry.composite ?? "—"} | ${entry.label}${marker} |`);
+  });
+
+  lines.push(
+    "",
+    "## Dimension Comparison (You vs Competitor Avg)",
+    "",
+    "| Dimension | You | Comp Avg | Δ | Rank |",
+    "|-----------|-----|----------|---|------|"
+  );
+
+  const sorted = Object.entries(report.dimensionComparison)
+    .sort((a, b) => (a[1].delta ?? 0) - (b[1].delta ?? 0));
+
+  for (const [dim, data] of sorted) {
+    const icon = (data.delta ?? 0) >= 5 ? "🟢" : (data.delta ?? 0) <= -5 ? "🔴" : "🟡";
+    lines.push(`| ${icon} ${DIM_LABELS[dim] || dim} | ${data.own ?? "—"} | ${data.competitorAvg ?? "—"} | ${data.delta !== null ? (data.delta >= 0 ? "+" : "") + data.delta : "—"} | #${data.rank ?? "—"} |`);
+  }
+
+  if (report.strengths.length > 0) {
+    lines.push("", "## Your Strengths (vs competitor avg)", "");
+    for (const s of report.strengths) {
+      lines.push(`- 🟢 **${DIM_LABELS[s.dimension] || s.dimension}**: +${s.delta} ahead (rank #${s.rank})`);
+    }
+  }
+
+  if (report.weaknesses.length > 0) {
+    lines.push("", "## Your Weaknesses (vs competitor avg)", "");
+    for (const w of report.weaknesses) {
+      lines.push(`- 🔴 **${DIM_LABELS[w.dimension] || w.dimension}**: ${w.delta} behind (rank #${w.rank})`);
+    }
+  }
+
+  if (report.platformComparison.length > 0) {
+    lines.push("", "## Platform Readiness vs Competitors", "", "| Platform | You | Comp Avg | Δ |", "|----------|-----|----------|---|");
+    for (const p of report.platformComparison) {
+      lines.push(`| ${p.platform} | ${p.ownScore} | ${p.competitorAvg} | ${p.delta >= 0 ? "+" : ""}${p.delta} |`);
+    }
+  }
+
+  if (report.gaps.length > 0) {
+    lines.push("", "## Priority Gaps to Close", "");
+    for (const g of report.gaps) {
+      lines.push(`- **${DIM_LABELS[g.dimension] || g.dimension}**: ${g.gap} points behind → ${g.action}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeDeepBenchmarkOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/fetch-utils.js

@@ -0,0 +1,76 @@
+/**
+ * Shared fetch utilities with retry, timeout, and rate limiting.
+ */
+
+const DEFAULT_TIMEOUT = 10_000;
+const DEFAULT_RETRIES = 2;
+const DEFAULT_RETRY_DELAY = 1000;
+const USER_AGENT = "geo-ai-search-optimization/2.2.1";
+
+export async function fetchWithRetry(url, options = {}) {
+  const timeout = options.timeout || DEFAULT_TIMEOUT;
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  const retryDelay = options.retryDelay || DEFAULT_RETRY_DELAY;
+  const headers = { "user-agent": USER_AGENT, ...options.headers };
+
+  let lastError;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const response = await fetch(url, {
+        redirect: "follow",
+        headers,
+        signal: AbortSignal.timeout(timeout)
+      });
+      return response;
+    } catch (err) {
+      lastError = err;
+      if (attempt < retries) {
+        await new Promise((r) => setTimeout(r, retryDelay * (attempt + 1)));
+      }
+    }
+  }
+
+  throw new Error(`Failed to fetch ${url} after ${retries + 1} attempts: ${lastError.message}`);
+}
+
+export async function fetchText(url, options = {}) {
+  const response = await fetchWithRetry(url, options);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} for ${url}`);
+  }
+  return response.text();
+}
+
+export async function fetchTextSafe(url, options = {}) {
+  try {
+    return { ok: true, text: await fetchText(url, options), url };
+  } catch (err) {
+    return { ok: false, error: err.message, url };
+  }
+}
+
+/**
+ * Run multiple fetches with concurrency control.
+ */
+export async function fetchBatch(urls, fn, options = {}) {
+  const concurrency = options.concurrency || 3;
+  const results = [];
+
+  const chunks = [];
+  for (let i = 0; i < urls.length; i += concurrency) {
+    chunks.push(urls.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    const chunkResults = await Promise.all(chunk.map((url) => fn(url)));
+    results.push(...chunkResults);
+
+    // Rate limit between chunks
+    if (options.delayBetweenChunks && chunks.indexOf(chunk) < chunks.length - 1) {
+      await new Promise((r) => setTimeout(r, options.delayBetweenChunks));
+    }
+  }
+
+  return results;
+}

package/src/index.js

@@ -85,4 +85,8 @@ export { batchFullPageAudit, renderBatchFullPageAuditMarkdown, writeBatchFullPag
 export { generateAutoFix, renderAutoFixMarkdown, writeAutoFixOutput } from "./auto-fix.js";
 export { diagnose, renderDiagnoseMarkdown, writeDiagnoseOutput } from "./diagnose.js";
 export { comparePages, renderCompareMarkdown, writeCompareOutput } from "./compare.js";
+export { deepBenchmark, renderDeepBenchmarkMarkdown, writeDeepBenchmarkOutput } from "./deep-benchmark.js";
+export { quickSummary, renderSummaryMarkdown } from "./summary.js";
+export { fetchWithRetry, fetchText, fetchTextSafe, fetchBatch } from "./fetch-utils.js";
+export { fullPageAuditToCsv, batchFullPageAuditToCsv, deepBenchmarkToCsv, compareToCsv, arrayToCsv } from "./csv-export.js";
 export { savePageSnapshot, listPageSnapshots, loadPageSnapshot, buildPageTrend, renderPageTrendMarkdown, writePageTrendOutput } from "./page-snapshot.js";

package/src/summary.js

@@ -0,0 +1,28 @@
+import { diagnose } from "./diagnose.js";
+
+/**
+ * Quick summary: one-line score output for any input.
+ * Designed for scripting, CI, and quick checks.
+ *
+ * Output format: SCORE/100 LABEL INPUT
+ * Example: 72/100 Moderate https://example.com
+ */
+
+export async function quickSummary(input, options = {}) {
+  const result = await diagnose(input, options);
+
+  return {
+    kind: "geo-summary",
+    input,
+    score: result.score,
+    label: result.scoreLabel,
+    type: result.analysisType,
+    oneLiner: `${result.score}/100 ${result.scoreLabel} ${input}`,
+    topIssue: result.quickWins[0] || null,
+    nextCommand: result.nextCommands[0]?.cmd || null
+  };
+}
+
+export function renderSummaryMarkdown(report) {
+  return `${report.score}/100 (${report.label}) — ${report.input}${report.topIssue ? `\nTop issue: ${report.topIssue}` : ""}\n`;
+}