geo-ai-search-optimization 1.4.1 → 1.4.2

package/README.md

@@ -100,6 +100,23 @@ geo-ai-search-optimization rewrite-pack ./content/posts/geo-guide.mdx --json --o
 - execution checklist
 - 可直接交给 agent 的 rewrite prompt
 
+## Repo Patch Plan 命令
+
+如果你希望从“页面建议”继续推进到“仓库里先改哪些文件和模板”，可以直接用 `repo-patch-plan`：
+
+```bash
+geo-ai-search-optimization repo-patch-plan ./your-site
+geo-ai-search-optimization repo-patch-plan ./your-site --json --out ./reports/repo-patch-plan.json
+```
+
+它会输出：
+
+- 候选文件区域
+- patch packets
+- likely files
+- execution notes
+- 可直接交给 agent 的 repo-level prompt
+
 ## Agent Resume 命令
 
 如果 GEO 工作已经做过一轮或多轮，你不想让下一个 agent 从头重新判断，而是想让它从最近一个可靠恢复点继续，可以直接用 `agent-resume`：
@@ -988,6 +1005,12 @@ geo-ai-search-optimization help
 - 基于 `page-audit` 继续产出 metadata drafts、章节结构、FAQ questions、schema recommendations 与 execution checklist
 - 让产品从“页面级诊断”继续推进到“页面级改写方案”
 
+## New in 1.4.2
+
+- 新增 `repo-patch-plan`
+- 把 GEO 问题继续收敛到仓库级 likely files、模板入口、metadata / schema / navigation 区域
+- 让 agent 更容易从“页面建议”切到“仓库改动计划”
+
 ## New in 1.2.20
 
 - 新增 `agent-continue`

package/package.json

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

@@ -15,6 +15,7 @@ import {
 import { createLlmsTxt } from "./llms-txt.js";
 import { auditPage, renderPageAuditMarkdown, writePageAuditOutput } from "./page-audit.js";
 import { createQuickStartPlan, renderQuickStartMarkdown, writeQuickStartOutput } from "./quick-start.js";
+import { createRepoPatchPlan, renderRepoPatchPlanMarkdown, writeRepoPatchPlanOutput } from "./repo-patch-plan.js";
 import { createRewritePack, renderRewritePackMarkdown, writeRewritePackOutput } from "./rewrite-pack.js";
 import { renderScanMarkdown, scanProject, writeScanOutput } from "./scan.js";
 import { createSchemaTemplate } from "./schema.js";
@@ -27,6 +28,7 @@ export const SITE_OPS_HELP_LINES = [
   "  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 rewrite-pack <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization repo-patch-plan <project-path> [--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>]",
@@ -109,6 +111,28 @@ const handleRewritePack = createStructuredOutputCommandHandler({
   getOutputJson: (args) => hasFlag(args, "--json")
 });
 
+const handleRepoPatchPlan = createStructuredOutputCommandHandler({
+  commandLabel: "repo patch plan",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) {
+      throw new Error("repo-patch-plan requires a project path");
+    }
+
+    return createRepoPatchPlan(input, {
+      maxFileSize: getFlagValue(args, "--max-file-size")
+        ? parsePositiveInteger(getFlagValue(args, "--max-file-size"), "--max-file-size")
+        : undefined,
+      maxExamples: getFlagValue(args, "--max-examples")
+        ? parsePositiveInteger(getFlagValue(args, "--max-examples"), "--max-examples")
+        : undefined
+    });
+  },
+  renderMarkdown: (report) => `${renderRepoPatchPlanMarkdown(report)}\n`,
+  writeOutput: writeRepoPatchPlanOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
 const handleInitLlms = createActionCommandHandler({
   execute: async (args) =>
     createLlmsTxt({
@@ -189,6 +213,7 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   "onboard-url": handleOnboardUrl,
   "page-audit": handlePageAudit,
   "rewrite-pack": handleRewritePack,
+  "repo-patch-plan": handleRepoPatchPlan,
   "init-llms": handleInitLlms,
   "init-schema": handleInitSchema,
   audit: handleAudit,

package/src/index.js

@@ -42,6 +42,7 @@ export { createOwnerBoard, renderOwnerBoardMarkdown, writeOwnerBoardOutput } fro
 export { createPmBrief, renderPmBriefMarkdown, writePmBriefOutput } from "./pm-brief.js";
 export { renderPublishPackMarkdown, writePublishPack } from "./publish-pack.js";
 export { createQuickStartPlan, renderQuickStartMarkdown, writeQuickStartOutput } from "./quick-start.js";
+export { createRepoPatchPlan, renderRepoPatchPlanMarkdown, writeRepoPatchPlanOutput } from "./repo-patch-plan.js";
 export { generateReport, writeReportOutput } from "./report.js";
 export { createRewritePack, renderRewritePackMarkdown, writeRewritePackOutput } from "./rewrite-pack.js";
 export { createRoadmap, renderRoadmapMarkdown, writeRoadmapOutput } from "./roadmap.js";

package/src/repo-patch-plan.js

@@ -0,0 +1,257 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { auditProject } from "./audit.js";
+import { writeScanOutput } from "./scan.js";
+
+const CANDIDATE_PATTERNS = [
+  {
+    area: "metadata",
+    label: "metadata / SEO helper",
+    test: (filePath) =>
+      /(seo|meta|metadata|head|layout|rootlayout|app\.tsx|app\.jsx|document|helmet)/i.test(filePath)
+  },
+  {
+    area: "schema",
+    label: "schema / structured data",
+    test: (filePath) => /(schema|json-ld|structured-data)/i.test(filePath)
+  },
+  {
+    area: "content-template",
+    label: "content template",
+    test: (filePath) => /(post|article|blog|page|content|docs|template|route|slug)/i.test(filePath)
+  },
+  {
+    area: "navigation",
+    label: "navigation / sitemap / robots",
+    test: (filePath) => /(robots|sitemap|llms|routes|navigation|nav)/i.test(filePath)
+  }
+];
+
+const TEXT_EXTENSIONS = new Set([
+  ".astro",
+  ".html",
+  ".js",
+  ".jsx",
+  ".md",
+  ".mdx",
+  ".mjs",
+  ".svelte",
+  ".ts",
+  ".tsx",
+  ".vue"
+]);
+
+const IGNORE_DIRS = new Set([
+  ".git",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".svelte-kit",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "tmp"
+]);
+
+async function collectRepoFiles(root) {
+  const files = [];
+  const queue = [root];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name)) {
+          queue.push(entryPath);
+        }
+        continue;
+      }
+
+      const extension = path.extname(entry.name).toLowerCase();
+      if (TEXT_EXTENSIONS.has(extension) || entry.name === "robots.txt" || entry.name === "llms.txt") {
+        files.push(entryPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+function rankCandidateFiles(root, files) {
+  return CANDIDATE_PATTERNS.map((pattern) => {
+    const matches = files
+      .filter((filePath) => pattern.test(path.relative(root, filePath)))
+      .slice(0, 6)
+      .map((filePath) => path.relative(root, filePath));
+
+    return {
+      area: pattern.area,
+      label: pattern.label,
+      files: matches
+    };
+  }).filter((entry) => entry.files.length > 0);
+}
+
+function buildPatchPackets(auditReport, candidates) {
+  const packets = [];
+
+  if (auditReport.groups.blockers.length > 0) {
+    packets.push({
+      id: "repo-fix-01",
+      priority: "P0",
+      owner: "工程 / SEO",
+      title: "先修基础抓取与归一入口",
+      targetArea: "抓取与索引",
+      likelyFiles: candidates.find((item) => item.area === "navigation")?.files || [],
+      actions: auditReport.groups.blockers.slice(0, 4),
+      doneWhen: "robots.txt、sitemap、canonical 机制可在仓库中找到明确入口并已接通。"
+    });
+  }
+
+  if (auditReport.groups.highImpactFixes.length > 0) {
+    packets.push({
+      id: "repo-fix-02",
+      priority: "P1",
+      owner: "工程 / 内容 / SEO",
+      title: "补齐页面模板中的 GEO 核心信号",
+      targetArea: "模板与页面结构",
+      likelyFiles: [
+        ...(candidates.find((item) => item.area === "metadata")?.files || []),
+        ...(candidates.find((item) => item.area === "content-template")?.files || [])
+      ].slice(0, 8),
+      actions: auditReport.groups.highImpactFixes.slice(0, 5),
+      doneWhen: "metadata、answer-first opening、作者/时间、来源链接和关键模板入口已能统一治理。"
+    });
+  }
+
+  if (auditReport.groups.supportFixes.length > 0) {
+    packets.push({
+      id: "repo-fix-03",
+      priority: "P2",
+      owner: "工程 / SEO",
+      title: "补模板级辅助信号",
+      targetArea: "模板治理",
+      likelyFiles: [
+        ...(candidates.find((item) => item.area === "schema")?.files || []),
+        ...(candidates.find((item) => item.area === "metadata")?.files || [])
+      ].slice(0, 8),
+      actions: auditReport.groups.supportFixes.slice(0, 4),
+      doneWhen: "模板层的 metadata、breadcrumb、schema 和 comparison 支持已有明确实现入口。"
+    });
+  }
+
+  return packets;
+}
+
+function buildExecutionNotes(auditReport, candidates) {
+  const notes = [];
+
+  if (candidates.find((item) => item.area === "metadata")) {
+    notes.push("优先检查 metadata / head / layout / SEO helper，不要逐页手改。");
+  }
+  if (candidates.find((item) => item.area === "schema")) {
+    notes.push("如果仓库已有 schema 入口，先复用现有 schema builder，再补页面类型逻辑。");
+  }
+  if (candidates.find((item) => item.area === "content-template")) {
+    notes.push("优先改文章页、内容页或动态路由模板，再考虑单页补丁。");
+  }
+  if (auditReport.groups.highImpactFixes.length > 0) {
+    notes.push("先处理高影响 GEO 修复项，再进入支持性优化，避免工程分散。");
+  }
+
+  return notes;
+}
+
+export async function createRepoPatchPlan(rootInput, options = {}) {
+  const root = path.resolve(rootInput);
+  const stat = await fs.stat(root).catch(() => null);
+  if (!stat || !stat.isDirectory()) {
+    throw new Error("repo-patch-plan 需要一个本地项目目录");
+  }
+
+  const [auditReport, repoFiles] = await Promise.all([
+    auditProject(root, options),
+    collectRepoFiles(root)
+  ]);
+
+  const candidates = rankCandidateFiles(root, repoFiles);
+  const patchPackets = buildPatchPackets(auditReport, candidates);
+
+  return {
+    kind: "geo-repo-patch-plan",
+    root,
+    summary: "这份 repo patch plan 会把 GEO 问题尽量落到仓库级模板、metadata、schema 和路由入口，方便 agent 直接开始改代码。",
+    score: {
+      value: auditReport.score,
+      maxScore: auditReport.maxScore,
+      label: auditReport.scoreLabel
+    },
+    candidateFiles: candidates,
+    patchPackets,
+    executionNotes: buildExecutionNotes(auditReport, candidates),
+    auditReport,
+    agentPrompt: [
+      "请把这次 GEO 修复当成仓库级任务处理。",
+      `项目目录：${root}`,
+      `当前 GEO 分数：${auditReport.score}/${auditReport.maxScore}（${auditReport.scoreLabel}）`,
+      `优先包：${patchPackets[0]?.id || "repo-fix-01"}`,
+      "先从 likelyFiles 开始确认 metadata、schema、content template、navigation 入口。",
+      "优先复用模板和 helper，不要只改单个页面。",
+      "完成一包后重新跑 audit 或 page-audit，验证问题是否实际减少。"
+    ].join(" ")
+  };
+}
+
+export function renderRepoPatchPlanMarkdown(plan) {
+  const lines = [
+    "# GEO Repo Patch Plan",
+    "",
+    `- 项目目录：\`${plan.root}\``,
+    `- 当前分数：\`${plan.score.value}/${plan.score.maxScore}\`（${plan.score.label}）`,
+    `- 总结：${plan.summary}`,
+    "",
+    "## 候选文件区域",
+    ""
+  ];
+
+  for (const candidate of plan.candidateFiles) {
+    lines.push(`- ${candidate.label}`);
+    for (const file of candidate.files) {
+      lines.push(`  - ${file}`);
+    }
+  }
+
+  lines.push("", "## Patch Packets", "");
+  for (const packet of plan.patchPackets) {
+    lines.push(`- ${packet.id}｜${packet.priority}｜${packet.owner}｜${packet.title}`);
+    lines.push(`  Target：${packet.targetArea}`);
+    lines.push(`  Done when：${packet.doneWhen}`);
+    if (packet.likelyFiles.length > 0) {
+      lines.push("  Likely files:");
+      for (const file of packet.likelyFiles) {
+        lines.push(`  - ${file}`);
+      }
+    }
+    lines.push("  Actions:");
+    for (const action of packet.actions) {
+      lines.push(`  - ${action}`);
+    }
+  }
+
+  lines.push("", "## Execution Notes", "");
+  for (const note of plan.executionNotes) {
+    lines.push(`- ${note}`);
+  }
+
+  lines.push("", "## Agent Prompt", "", plan.agentPrompt, "");
+  return lines.join("\n");
+}
+
+export async function writeRepoPatchPlanOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}