geo-ai-search-optimization 1.4.0 → 1.4.2

package/README.md

@@ -81,6 +81,42 @@ geo-ai-search-optimization page-audit ./content/posts/geo-guide.mdx --json --out
 - rewrite brief
 - 可直接交给 agent 的 page-level prompt
 
+## Rewrite Pack 命令
+
+如果你已经知道某个页面有问题，想直接拿到更接近“改写方案”的产物，可以用 `rewrite-pack`：
+
+```bash
+geo-ai-search-optimization rewrite-pack https://example.com/blog/geo-guide
+geo-ai-search-optimization rewrite-pack ./content/posts/geo-guide.mdx
+geo-ai-search-optimization rewrite-pack ./content/posts/geo-guide.mdx --json --out ./reports/rewrite-pack.json
+```
+
+它会输出：
+
+- metadata drafts
+- 建议章节结构
+- FAQ questions
+- schema recommendations
+- 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`：
@@ -963,6 +999,18 @@ geo-ai-search-optimization help
 - 输出页面分数、问题区域、推荐新增模块、rewrite brief 与 agent prompt
 - 产品能力从“站点级诊断”扩展到“页面级修复入口”
 
+## New in 1.4.1
+
+- 新增 `rewrite-pack`
+- 基于 `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.0",
+  "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,8 @@ 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";
 import { analyzeWebsiteUrl, renderWebsiteOnboardingMarkdown, writeWebsiteOnboardingOutput } from "./url-onboarding.js";
@@ -25,6 +27,8 @@ export const SITE_OPS_HELP_LINES = [
   "  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 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>]",
@@ -92,6 +96,43 @@ const handlePageAudit = createStructuredOutputCommandHandler({
   getOutputJson: (args) => hasFlag(args, "--json")
 });
 
+const handleRewritePack = createStructuredOutputCommandHandler({
+  commandLabel: "rewrite pack",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) {
+      throw new Error("rewrite-pack requires a URL or file path");
+    }
+
+    return createRewritePack(input, {});
+  },
+  renderMarkdown: (report) => `${renderRewritePackMarkdown(report)}\n`,
+  writeOutput: writeRewritePackOutput,
+  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({
@@ -171,6 +212,8 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   onboard: handleInteractiveOnboard,
   "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,7 +42,9 @@ 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";
 export { createSchemaTemplate } from "./schema.js";
 export { scanProject, renderScanMarkdown, writeScanOutput } from "./scan.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);
+}

package/src/rewrite-pack.js

@@ -0,0 +1,198 @@
+import { auditPage, writePageAuditOutput } from "./page-audit.js";
+
+function buildOpeningDraft(report) {
+  const title = report.metadata.title || "这个页面";
+  return [
+    `${title} 是一页需要先用直接答案说明核心价值的内容。`,
+    "这页最适合先讲清楚它是什么、适合谁、什么时候不适合，以及用户下一步应该看什么。",
+    "如果没有这些信息，生成式搜索系统很难稳定提取出可引用的答案。"
+  ].join(" ");
+}
+
+function buildSuggestedHeadings(report) {
+  const headings = [
+    "这是什么",
+    "适合谁",
+    "什么时候不适合",
+    "和其他方案有什么差别",
+    "关键事实与证据",
+    "下一步该怎么做"
+  ];
+
+  if (report.signals.comparison_intent.count > 0) {
+    headings.splice(3, 1, "和替代方案相比有什么差别");
+  }
+
+  return headings.slice(0, 6);
+}
+
+function buildFaqQuestions(report) {
+  return [
+    `${report.metadata.title || "这页的主题"} 适合哪些人？`,
+    "什么时候不应该选择这个方案？",
+    "有哪些限制条件或前提？",
+    "有哪些证据可以支持这页的主张？"
+  ];
+}
+
+function buildSchemaRecommendations(report) {
+  const recommendations = [];
+
+  if (report.signals.qa_headings.count > 0 || report.headingStats.questionHeadingCount > 0) {
+    recommendations.push("FAQPage");
+  }
+
+  if (report.signals.original_research.count > 0) {
+    recommendations.push("Article");
+  }
+
+  if (report.signals.comparison_intent.count > 0) {
+    recommendations.push("Article");
+  }
+
+  if (recommendations.length === 0) {
+    recommendations.push("Article");
+  }
+
+  return Array.from(new Set(recommendations));
+}
+
+function buildMetadataDrafts(report) {
+  const baseTitle = report.metadata.title || "页面主题";
+  return {
+    title: `${baseTitle}｜适合谁、限制与关键信息`,
+    metaDescription: `${baseTitle} 的直接答案、适用对象、限制条件、关键证据与下一步建议。`,
+    canonical: report.metadata.canonical || "请设置到该页面的唯一正式 URL"
+  };
+}
+
+function buildContentSections(report) {
+  return [
+    {
+      name: "Opening summary",
+      goal: "用 2 到 4 句先给直接答案。",
+      draft: buildOpeningDraft(report)
+    },
+    {
+      name: "Decision block",
+      goal: "明确适合谁、什么时候不适合、主要 trade-off。",
+      bullets: [
+        "适合谁",
+        "主要限制",
+        "决策条件",
+        "如果不适合，应该去看哪一页"
+      ]
+    },
+    {
+      name: "Evidence block",
+      goal: "把结论和主张接到来源、案例、方法论或数据。",
+      bullets: [
+        "来源链接",
+        "方法论说明",
+        "案例或截图",
+        "更新时间"
+      ]
+    }
+  ];
+}
+
+function buildExecutionChecklist(report) {
+  return [
+    "先重写 opening summary，让第一屏可以直接回答用户问题。",
+    "补上问答式 H2 和 decision block。",
+    "补来源链接、作者/更新时间和 evidence block。",
+    "补最贴近页面真实内容的 schema。",
+    "完成后重新跑 page-audit，对比分数和问题区域。"
+  ];
+}
+
+export async function createRewritePack(input, options = {}) {
+  const pageAudit = await auditPage(input, options);
+
+  return {
+    kind: "geo-rewrite-pack",
+    input,
+    sourceType: pageAudit.sourceType,
+    reference: pageAudit.reference,
+    summary: `这份 rewrite pack 基于单页审计生成，优先帮助你把页面改成更适合生成式搜索理解与引用的 answer-first 结构。`,
+    currentScore: {
+      score: pageAudit.score.score,
+      maxScore: pageAudit.score.maxScore,
+      label: pageAudit.scoreLabel
+    },
+    pageAudit,
+    metadataDrafts: buildMetadataDrafts(pageAudit),
+    suggestedHeadings: buildSuggestedHeadings(pageAudit),
+    faqQuestions: buildFaqQuestions(pageAudit),
+    schemaRecommendations: buildSchemaRecommendations(pageAudit),
+    contentSections: buildContentSections(pageAudit),
+    executionChecklist: buildExecutionChecklist(pageAudit),
+    agentPrompt: [
+      "请根据这份 rewrite pack 改写页面。",
+      `页面：${pageAudit.reference}`,
+      `当前分数：${pageAudit.score.score}/${pageAudit.score.maxScore}`,
+      `优先处理：${pageAudit.problemAreas.map((item) => item.area).join("、") || "opening summary 与 evidence block"}`,
+      "先改 metadata drafts 和 opening summary，再补 headings、FAQ、evidence block、schema。",
+      "改完后重新跑 page-audit，确认页面级 GEO 分数有提升。"
+    ].join(" ")
+  };
+}
+
+export function renderRewritePackMarkdown(pack) {
+  const lines = [
+    "# GEO Rewrite Pack",
+    "",
+    `- 输入：\`${pack.input}\``,
+    `- 分析对象：\`${pack.reference}\``,
+    `- 当前分数：\`${pack.currentScore.score}/${pack.currentScore.maxScore}\`（${pack.currentScore.label}）`,
+    `- 总结：${pack.summary}`,
+    "",
+    "## Metadata Drafts",
+    "",
+    `- title：${pack.metadataDrafts.title}`,
+    `- meta description：${pack.metadataDrafts.metaDescription}`,
+    `- canonical：${pack.metadataDrafts.canonical}`,
+    "",
+    "## Suggested Headings",
+    ""
+  ];
+
+  for (const heading of pack.suggestedHeadings) {
+    lines.push(`- ${heading}`);
+  }
+
+  lines.push("", "## FAQ Questions", "");
+  for (const question of pack.faqQuestions) {
+    lines.push(`- ${question}`);
+  }
+
+  lines.push("", "## Schema Recommendations", "");
+  for (const schema of pack.schemaRecommendations) {
+    lines.push(`- ${schema}`);
+  }
+
+  lines.push("", "## Content Sections", "");
+  for (const section of pack.contentSections) {
+    lines.push(`- ${section.name}｜${section.goal}`);
+    if (section.draft) {
+      lines.push(`  Draft：${section.draft}`);
+    }
+    if (section.bullets) {
+      for (const bullet of section.bullets) {
+        lines.push(`  - ${bullet}`);
+      }
+    }
+  }
+
+  lines.push("", "## Execution Checklist", "");
+  for (const item of pack.executionChecklist) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## Agent Prompt", "", pack.agentPrompt, "");
+  return lines.join("\n");
+}
+
+export async function writeRewritePackOutput(outputPath, content) {
+  return writePageAuditOutput(outputPath, content);
+}