geo-ai-search-optimization 1.4.2 → 2.2.0

package/action.yml

@@ -0,0 +1,130 @@
+name: "GEO AI Search Optimization"
+description: "Run GEO audit in CI/CD. Check your site's AI search readiness score and fail on regression."
+author: "geo-ai-search-optimization"
+
+inputs:
+  project-path:
+    description: "Path to the project to audit"
+    required: true
+    default: "."
+  min-score:
+    description: "Minimum GEO score to pass (0-100)"
+    required: false
+    default: "40"
+  baseline:
+    description: "Path to baseline audit JSON for regression detection"
+    required: false
+  fail-on-regression:
+    description: "Fail if score drops compared to baseline"
+    required: false
+    default: "false"
+  output-format:
+    description: "Output format: json or markdown"
+    required: false
+    default: "markdown"
+  save-snapshot:
+    description: "Save audit snapshot for trend tracking"
+    required: false
+    default: "false"
+
+outputs:
+  score:
+    description: "GEO audit score (0-100)"
+    value: ${{ steps.audit.outputs.score }}
+  score-label:
+    description: "Human-readable score label"
+    value: ${{ steps.audit.outputs.score-label }}
+  passed:
+    description: "Whether the audit passed (true/false)"
+    value: ${{ steps.audit.outputs.passed }}
+  report-path:
+    description: "Path to the generated report file"
+    value: ${{ steps.audit.outputs.report-path }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "18"
+
+    - name: Install geo-ai-search-optimization
+      shell: bash
+      run: npm install -g geo-ai-search-optimization
+
+    - name: Run GEO Audit
+      id: audit
+      shell: bash
+      run: |
+        PROJ_PATH="${{ inputs.project-path }}"
+        BASELINE="${{ inputs.baseline }}"
+        MIN_SCORE="${{ inputs.min-score }}"
+
+        ARGS=("$PROJ_PATH" "--json")
+
+        if [ -n "$BASELINE" ]; then
+          ARGS+=("--baseline" "$BASELINE")
+        fi
+
+        if [ "${{ inputs.fail-on-regression }}" = "true" ]; then
+          ARGS+=("--fail-on-regression")
+        fi
+
+        ARGS+=("--min-score" "$MIN_SCORE")
+
+        RESULT=$(geo-ai-search-optimization ci "${ARGS[@]}" 2>geo-audit-stderr.log) || true
+        echo "$RESULT" > geo-audit-result.json
+
+        SCORE=$(echo "$RESULT" | node -e "
+          const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+          console.log(data.audit?.score ?? data.score ?? 0);
+        " 2>/dev/null || echo "0")
+
+        LABEL=$(echo "$RESULT" | node -e "
+          const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+          console.log(data.audit?.scoreLabel ?? data.scoreLabel ?? 'unknown');
+        " 2>/dev/null || echo "unknown")
+
+        PASSED=$(echo "$RESULT" | node -e "
+          const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+          console.log(data.passed ?? (data.exitCode === 0));
+        " 2>/dev/null || echo "false")
+
+        echo "score=$SCORE" >> $GITHUB_OUTPUT
+        echo "score-label=$LABEL" >> $GITHUB_OUTPUT
+        echo "passed=$PASSED" >> $GITHUB_OUTPUT
+        echo "report-path=geo-audit-result.json" >> $GITHUB_OUTPUT
+
+    - name: Save Snapshot
+      if: inputs.save-snapshot == 'true'
+      shell: bash
+      run: |
+        geo-ai-search-optimization audit "${{ inputs.project-path }}" --save --json > /dev/null 2>&1 || true
+
+    - name: Generate Markdown Report
+      if: inputs.output-format == 'markdown'
+      shell: bash
+      run: |
+        geo-ai-search-optimization audit "${{ inputs.project-path }}" --out geo-audit-report.md || true
+
+    - name: Post Summary
+      if: always()
+      shell: bash
+      run: |
+        echo "### GEO Audit Results" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "- **Score:** ${{ steps.audit.outputs.score }}/100 (${{ steps.audit.outputs.score-label }})" >> $GITHUB_STEP_SUMMARY
+        echo "- **Passed:** ${{ steps.audit.outputs.passed }}" >> $GITHUB_STEP_SUMMARY
+        echo "- **Min Score:** ${{ inputs.min-score }}" >> $GITHUB_STEP_SUMMARY
+
+    - name: Check Result
+      if: steps.audit.outputs.passed == 'false'
+      shell: bash
+      run: |
+        echo "::error::GEO audit failed. Score: ${{ steps.audit.outputs.score }}/100 (minimum: ${{ inputs.min-score }})"
+        exit 1
+
+branding:
+  icon: "search"
+  color: "blue"

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,18 +1,24 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.4.2",
+  "version": "2.2.0",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {
     "geo-ai-search-optimization": "bin/geo-ai-search-optimization.js"
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
+  "types": "./src/index.d.ts",
   "files": [
     "bin",
     "src",
     "resources",
+    "examples",
+    "action.yml",
     "README.md",
     "LICENSE"
   ],
@@ -20,6 +26,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"
@@ -32,7 +39,14 @@
     "codex-skill",
     "chatgpt",
     "perplexity",
-    "gemini"
+    "gemini",
+    "llms-txt",
+    "schema-validation",
+    "eeat",
+    "citability",
+    "ai-crawler",
+    "aeo",
+    "ai-optimization"
   ],
   "license": "MIT"
 }

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);
+}