geo-ai-search-optimization 1.4.2 → 2.0.0

package/examples/github-action.yml

@@ -0,0 +1,27 @@
+# Example GitHub Action workflow for GEO CI checks
+# Add this to .github/workflows/geo-ci.yml in your project
+
+name: GEO CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  geo-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install -g geo-ai-search-optimization
+      - name: Run GEO audit
+        run: geo-ai-search-optimization ci . --min-score 40 --json
+      - name: Run GEO audit with baseline
+        if: always()
+        run: |
+          # Optional: compare against a saved baseline
+          # geo-ai-search-optimization ci . --min-score 40 --baseline baseline.json --fail-on-regression
+          echo "Baseline comparison skipped (no baseline file)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "bin",
     "src",
     "resources",
+    "examples",
     "README.md",
     "LICENSE"
   ],
@@ -20,6 +21,7 @@
     "node": ">=18"
   },
   "scripts": {
+    "test": "node --test 'test/**/*.test.js'",
     "postinstall": "node ./src/postinstall.js",
     "check": "node ./src/cli.js --help",
     "scan:self": "node ./src/cli.js scan ./resources/geo-ai-search-optimization"

package/src/audit-diff.js

@@ -0,0 +1,184 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+async function loadAuditJson(filePath) {
+  const resolved = path.resolve(filePath);
+  const raw = await fs.readFile(resolved, "utf8");
+  const data = JSON.parse(raw);
+  if (!data.kind || !data.score || !data.checks) {
+    throw new Error(`${resolved} 不是有效的审计 JSON（缺少 kind / score / checks）`);
+  }
+  return data;
+}
+
+function diffChecks(baselineChecks, currentChecks) {
+  const baselineMap = new Map(baselineChecks.map((c) => [c.key, c]));
+  return currentChecks.map((current) => {
+    const baseline = baselineMap.get(current.key);
+    if (!baseline) {
+      return { ...current, baselinePassed: null, delta: current.pointsAwarded };
+    }
+    return {
+      key: current.key,
+      label: current.label,
+      baselinePassed: baseline.passed,
+      currentPassed: current.passed,
+      baselinePoints: baseline.pointsAwarded,
+      currentPoints: current.pointsAwarded,
+      maxPoints: current.maxPoints,
+      delta: current.pointsAwarded - baseline.pointsAwarded
+    };
+  });
+}
+
+function classifyChanges(checkDiffs) {
+  const improved = [];
+  const regressed = [];
+  const unchanged = [];
+
+  for (const diff of checkDiffs) {
+    if (diff.delta > 0) {
+      improved.push(diff);
+    } else if (diff.delta < 0) {
+      regressed.push(diff);
+    } else {
+      unchanged.push(diff);
+    }
+  }
+
+  return { improved, regressed, unchanged };
+}
+
+function diffAreas(baselineAreas, currentAreas) {
+  if (!baselineAreas || !currentAreas) return [];
+
+  const baselineMap = new Map(baselineAreas.map((a) => [a.key, a]));
+  return currentAreas.map((current) => {
+    const baseline = baselineMap.get(current.key);
+    if (!baseline) {
+      return { key: current.key, title: current.title, baselineSeverity: null, currentSeverity: current.severity, newIssues: current.issues, resolvedIssues: [] };
+    }
+    const baselineIssueSet = new Set(baseline.issues);
+    const currentIssueSet = new Set(current.issues);
+    return {
+      key: current.key,
+      title: current.title,
+      baselineSeverity: baseline.severity,
+      currentSeverity: current.severity,
+      newIssues: current.issues.filter((i) => !baselineIssueSet.has(i)),
+      resolvedIssues: baseline.issues.filter((i) => !currentIssueSet.has(i))
+    };
+  });
+}
+
+export function createAuditDiff(baseline, current) {
+  const scoreDelta = current.score - baseline.score;
+  const checkDiffs = diffChecks(baseline.checks, current.checks);
+  const { improved, regressed, unchanged } = classifyChanges(checkDiffs);
+  const areaDiffs = diffAreas(baseline.areas, current.areas);
+
+  const hasRegression = regressed.length > 0;
+  const allNewIssues = areaDiffs.flatMap((a) => a.newIssues);
+  const allResolvedIssues = areaDiffs.flatMap((a) => a.resolvedIssues);
+
+  let verdict;
+  if (scoreDelta > 0 && !hasRegression) {
+    verdict = "改善";
+  } else if (scoreDelta === 0 && !hasRegression) {
+    verdict = "持平";
+  } else if (scoreDelta > 0 && hasRegression) {
+    verdict = "部分改善（存在回归）";
+  } else if (scoreDelta < 0) {
+    verdict = "退步";
+  } else {
+    verdict = "持平（存在回归）";
+  }
+
+  return {
+    kind: "geo-audit-diff",
+    baseline: {
+      score: baseline.score,
+      maxScore: baseline.maxScore,
+      scoreLabel: baseline.scoreLabel,
+      kind: baseline.kind
+    },
+    current: {
+      score: current.score,
+      maxScore: current.maxScore,
+      scoreLabel: current.scoreLabel,
+      kind: current.kind
+    },
+    scoreDelta,
+    verdict,
+    checkDiffs,
+    improved,
+    regressed,
+    unchanged,
+    areaDiffs,
+    newIssues: allNewIssues,
+    resolvedIssues: allResolvedIssues,
+    hasRegression
+  };
+}
+
+export async function createAuditDiffFromFiles(baselinePath, currentPath) {
+  const baseline = await loadAuditJson(baselinePath);
+  const current = await loadAuditJson(currentPath);
+  return createAuditDiff(baseline, current);
+}
+
+export function renderAuditDiffMarkdown(diff) {
+  const lines = [
+    "# GEO 审计对比",
+    "",
+    `- 判定：**${diff.verdict}**`,
+    `- 基线分数：\`${diff.baseline.score}/${diff.baseline.maxScore}\`（${diff.baseline.scoreLabel}）`,
+    `- 当前分数：\`${diff.current.score}/${diff.current.maxScore}\`（${diff.current.scoreLabel}）`,
+    `- 分数变化：\`${diff.scoreDelta >= 0 ? "+" : ""}${diff.scoreDelta}\``,
+    ""
+  ];
+
+  lines.push("## 评分明细对比", "", "| 检查项 | 基线 | 当前 | 变化 |", "|--------|------|------|------|");
+  for (const check of diff.checkDiffs) {
+    const baseStr = check.baselinePassed === null ? "N/A" : `${check.baselinePassed ? "✓" : "✗"} (${check.baselinePoints})`;
+    const curStr = `${check.currentPassed ? "✓" : "✗"} (${check.currentPoints})`;
+    const deltaStr = check.delta > 0 ? `+${check.delta}` : check.delta === 0 ? "—" : String(check.delta);
+    lines.push(`| ${check.label} | ${baseStr} | ${curStr} | ${deltaStr} |`);
+  }
+
+  if (diff.improved.length > 0) {
+    lines.push("", "## 改善项", "");
+    for (const item of diff.improved) {
+      lines.push(`- ${item.label}：+${item.delta} 分`);
+    }
+  }
+
+  if (diff.regressed.length > 0) {
+    lines.push("", "## ⚠ 回归项", "");
+    for (const item of diff.regressed) {
+      lines.push(`- ${item.label}：${item.delta} 分`);
+    }
+  }
+
+  if (diff.resolvedIssues.length > 0) {
+    lines.push("", "## 已解决问题", "");
+    for (const issue of diff.resolvedIssues) {
+      lines.push(`- ${issue}`);
+    }
+  }
+
+  if (diff.newIssues.length > 0) {
+    lines.push("", "## 新增问题", "");
+    for (const issue of diff.newIssues) {
+      lines.push(`- ${issue}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeAuditDiffOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/batch-page-audit.js

@@ -0,0 +1,140 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { auditPage } from "./page-audit.js";
+import { writeScanOutput } from "./scan.js";
+
+async function runWithConcurrencyLimit(tasks, limit) {
+  const results = [];
+  let index = 0;
+
+  async function worker() {
+    while (index < tasks.length) {
+      const currentIndex = index++;
+      results[currentIndex] = await tasks[currentIndex]();
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+
+export async function batchAuditPages(urls, options = {}) {
+  if (!urls || urls.length === 0) {
+    throw new Error("batch-page-audit 需要至少一个 URL 或文件路径");
+  }
+
+  const concurrency = options.concurrency || 3;
+  const tasks = urls.map((url) => async () => {
+    try {
+      const result = await auditPage(url, {});
+      return { url, success: true, result };
+    } catch (error) {
+      return { url, success: false, error: error.message, result: null };
+    }
+  });
+
+  const results = await runWithConcurrencyLimit(tasks, concurrency);
+
+  const successResults = results.filter((r) => r.success);
+  const failedResults = results.filter((r) => !r.success);
+
+  const scores = successResults.map((r) => r.result.score.score);
+  const averageScore = scores.length > 0 ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length) : 0;
+  const worstPage = successResults.length > 0
+    ? successResults.reduce((worst, current) =>
+        current.result.score.score < worst.result.score.score ? current : worst
+      )
+    : null;
+  const bestPage = successResults.length > 0
+    ? successResults.reduce((best, current) =>
+        current.result.score.score > best.result.score.score ? current : best
+      )
+    : null;
+
+  // Signal coverage matrix
+  const allSignals = new Set();
+  for (const r of successResults) {
+    for (const key of Object.keys(r.result.signals)) {
+      allSignals.add(key);
+    }
+  }
+
+  const signalCoverage = {};
+  for (const signal of allSignals) {
+    const pagesWithSignal = successResults.filter((r) => r.result.signals[signal]?.count > 0).length;
+    signalCoverage[signal] = {
+      pagesWithSignal,
+      totalPages: successResults.length,
+      coveragePercent: successResults.length > 0 ? Math.round((pagesWithSignal / successResults.length) * 100) : 0
+    };
+  }
+
+  return {
+    kind: "geo-batch-page-audit",
+    totalPages: urls.length,
+    successCount: successResults.length,
+    failedCount: failedResults.length,
+    averageScore,
+    maxScore: 100,
+    worstPage: worstPage ? { url: worstPage.url, score: worstPage.result.score.score } : null,
+    bestPage: bestPage ? { url: bestPage.url, score: bestPage.result.score.score } : null,
+    signalCoverage,
+    pages: results.map((r) => ({
+      url: r.url,
+      success: r.success,
+      score: r.success ? r.result.score.score : null,
+      scoreLabel: r.success ? r.result.scoreLabel : null,
+      error: r.success ? null : r.error
+    })),
+    pageResults: successResults.map((r) => r.result),
+    failed: failedResults.map((r) => ({ url: r.url, error: r.error }))
+  };
+}
+
+export function renderBatchPageAuditMarkdown(report) {
+  const lines = [
+    "# GEO 批量页面审计",
+    "",
+    `- 总页面数：\`${report.totalPages}\``,
+    `- 成功审计：\`${report.successCount}\``,
+    `- 失败：\`${report.failedCount}\``,
+    `- 平均分数：\`${report.averageScore}/${report.maxScore}\``,
+    ""
+  ];
+
+  if (report.bestPage) {
+    lines.push(`- 最佳页面：\`${report.bestPage.url}\`（${report.bestPage.score} 分）`);
+  }
+  if (report.worstPage) {
+    lines.push(`- 最差页面：\`${report.worstPage.url}\`（${report.worstPage.score} 分）`);
+  }
+
+  lines.push("", "## 逐页分数", "", "| 页面 | 分数 | 状态 |", "|------|------|------|");
+  for (const page of report.pages) {
+    if (page.success) {
+      lines.push(`| ${page.url} | ${page.score}/${report.maxScore} | ${page.scoreLabel} |`);
+    } else {
+      lines.push(`| ${page.url} | — | 失败：${page.error} |`);
+    }
+  }
+
+  lines.push("", "## 信号覆盖矩阵", "", "| 信号 | 覆盖页数 | 覆盖率 |", "|------|----------|--------|");
+  for (const [signal, coverage] of Object.entries(report.signalCoverage)) {
+    lines.push(`| ${signal} | ${coverage.pagesWithSignal}/${coverage.totalPages} | ${coverage.coveragePercent}% |`);
+  }
+
+  if (report.failed.length > 0) {
+    lines.push("", "## 失败页面", "");
+    for (const f of report.failed) {
+      lines.push(`- ${f.url}：${f.error}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeBatchPageAuditOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/benchmark.js

@@ -0,0 +1,126 @@
+import { auditPage } from "./page-audit.js";
+import { writeScanOutput } from "./scan.js";
+
+export async function runBenchmark(ownUrl, competitorUrls, options = {}) {
+  if (!ownUrl) {
+    throw new Error("benchmark 需要你自己的 URL");
+  }
+  if (!competitorUrls || competitorUrls.length === 0) {
+    throw new Error("benchmark 需要至少一个竞品 URL（使用 --competitors）");
+  }
+
+  const allUrls = [ownUrl, ...competitorUrls];
+  const results = [];
+
+  for (const url of allUrls) {
+    try {
+      const result = await auditPage(url, {});
+      results.push({ url, success: true, result });
+    } catch (error) {
+      results.push({ url, success: false, error: error.message, result: null });
+    }
+  }
+
+  const ownResult = results[0];
+  const competitorResults = results.slice(1);
+
+  // Build comparison matrix
+  const signalKeys = new Set();
+  for (const r of results.filter((r) => r.success)) {
+    for (const key of Object.keys(r.result.signals)) {
+      signalKeys.add(key);
+    }
+  }
+
+  const matrix = [];
+  for (const signal of signalKeys) {
+    const row = {
+      signal,
+      own: ownResult.success ? (ownResult.result.signals[signal]?.count > 0) : null,
+      competitors: competitorResults.map((r) =>
+        r.success ? (r.result.signals[signal]?.count > 0) : null
+      )
+    };
+    matrix.push(row);
+  }
+
+  // Score comparison
+  const scoreComparison = results.map((r) => ({
+    url: r.url,
+    score: r.success ? r.result.score.score : null,
+    scoreLabel: r.success ? r.result.scoreLabel : null,
+    isOwn: r.url === ownUrl
+  }));
+
+  // Gaps: signals competitors have that you don't
+  const gaps = [];
+  if (ownResult.success) {
+    for (const signal of signalKeys) {
+      const ownHas = ownResult.result.signals[signal]?.count > 0;
+      if (!ownHas) {
+        const competitorsWithSignal = competitorResults
+          .filter((r) => r.success && r.result.signals[signal]?.count > 0)
+          .map((r) => r.url);
+        if (competitorsWithSignal.length > 0) {
+          gaps.push({ signal, competitorsWithSignal });
+        }
+      }
+    }
+  }
+
+  return {
+    kind: "geo-benchmark",
+    ownUrl,
+    competitorUrls,
+    scoreComparison,
+    signalMatrix: matrix,
+    gaps,
+    results: results.map((r) => ({
+      url: r.url,
+      success: r.success,
+      score: r.success ? r.result.score.score : null,
+      error: r.success ? null : r.error
+    })),
+    pageResults: results.filter((r) => r.success).map((r) => r.result)
+  };
+}
+
+export function renderBenchmarkMarkdown(report) {
+  const lines = [
+    "# GEO 竞品基准对比",
+    "",
+    `- 你的 URL：\`${report.ownUrl}\``,
+    `- 竞品数量：\`${report.competitorUrls.length}\``,
+    ""
+  ];
+
+  lines.push("## 分数对比", "", "| URL | 分数 | 状态 | 角色 |", "|-----|------|------|------|");
+  for (const entry of report.scoreComparison) {
+    const role = entry.isOwn ? "你的" : "竞品";
+    lines.push(`| ${entry.url} | ${entry.score ?? "—"}/100 | ${entry.scoreLabel ?? "失败"} | ${role} |`);
+  }
+
+  lines.push("", "## 信号覆盖矩阵", "");
+  const headerUrls = report.scoreComparison.map((e) => e.url.replace(/https?:\/\//, "").slice(0, 30));
+  lines.push(`| 信号 | ${headerUrls.join(" | ")} |`);
+  lines.push(`|------${headerUrls.map(() => "|------").join("")}|`);
+  for (const row of report.signalMatrix) {
+    const ownCell = row.own === null ? "—" : row.own ? "✓" : "✗";
+    const compCells = row.competitors.map((c) => c === null ? "—" : c ? "✓" : "✗");
+    lines.push(`| ${row.signal} | ${ownCell} | ${compCells.join(" | ")} |`);
+  }
+
+  if (report.gaps.length > 0) {
+    lines.push("", "## 你的信号缺口（竞品有而你没有）", "");
+    for (const gap of report.gaps) {
+      lines.push(`- **${gap.signal}**：${gap.competitorsWithSignal.join("、")} 有此信号`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeBenchmarkOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/ci.js

@@ -0,0 +1,81 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { auditProject } from "./audit.js";
+import { writeScanOutput } from "./scan.js";
+
+export async function runCiCheck(projectPath, options = {}) {
+  const minScore = options.minScore ?? 40;
+  const failOnRegression = options.failOnRegression ?? false;
+
+  const result = await auditProject(projectPath, {});
+
+  let baselineScore = null;
+  let regression = false;
+
+  if (options.baseline) {
+    const baselinePath = path.resolve(options.baseline);
+    const raw = await fs.readFile(baselinePath, "utf8");
+    const baseline = JSON.parse(raw);
+    baselineScore = baseline.score;
+    if (result.score < baselineScore) {
+      regression = true;
+    }
+  }
+
+  let exitCode = 0;
+  let status;
+
+  if (regression && failOnRegression) {
+    exitCode = 2;
+    status = "回归";
+  } else if (result.score < minScore) {
+    exitCode = 1;
+    status = "低于阈值";
+  } else {
+    status = "通过";
+  }
+
+  return {
+    kind: "geo-ci-check",
+    projectPath,
+    score: result.score,
+    maxScore: result.maxScore,
+    scoreLabel: result.scoreLabel,
+    minScore,
+    baselineScore,
+    regression,
+    failOnRegression,
+    exitCode,
+    status,
+    summary: exitCode === 0
+      ? `CI 检查通过：分数 ${result.score}/${result.maxScore}（阈值 ${minScore}）`
+      : exitCode === 1
+        ? `CI 检查失败：分数 ${result.score} 低于阈值 ${minScore}`
+        : `CI 检查失败：检测到回归（当前 ${result.score}，基线 ${baselineScore}）`,
+    audit: result
+  };
+}
+
+export function renderCiCheckMarkdown(report) {
+  const lines = [
+    "# GEO CI 检查",
+    "",
+    `- 状态：**${report.status}**`,
+    `- 分数：\`${report.score}/${report.maxScore}\`（${report.scoreLabel}）`,
+    `- 阈值：\`${report.minScore}\``,
+    ""
+  ];
+
+  if (report.baselineScore !== null) {
+    lines.push(`- 基线分数：\`${report.baselineScore}\``);
+    lines.push(`- 回归：\`${report.regression}\``);
+    lines.push("");
+  }
+
+  lines.push(report.summary, "");
+  return lines.join("\n");
+}
+
+export async function writeCiCheckOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}