geo-ai-search-optimization 1.2.8 → 1.2.10

package/README.md

@@ -81,6 +81,49 @@ geo-ai-search-optimization agent-session ./reports/apply-plan.json --json
 - 每一步的目的与预期产物
 - 可直接复制给 agent 的 session prompt
 
+## Agent Runbook 命令
+
+如果你希望 agent 拿到的不只是会话步骤，而是一份更稳定的执行手册和检查清单，可以直接用 `agent-runbook`：
+
+```bash
+geo-ai-search-optimization agent-runbook "我想把这份 GEO 结果交给下一个 agent 继续修"
+geo-ai-search-optimization agent-runbook https://example.com
+geo-ai-search-optimization agent-runbook ./your-site
+geo-ai-search-optimization agent-runbook ./reports/apply-plan.json --json
+```
+
+它会输出：
+
+- 开始前检查
+- 工作规则
+- 需要停下来的情况
+- 命令执行清单
+- 重点执行包
+- 验证清单
+- 回报清单
+- 可直接复制给 agent 的 runbook prompt
+
+## Agent Executor 命令
+
+如果你希望 agent 不只是拿到 runbook，而是直接得到“这一轮先执行哪 1 个任务”的入口，可以直接用 `agent-executor`：
+
+```bash
+geo-ai-search-optimization agent-executor ./your-site
+geo-ai-search-optimization agent-executor ./reports/apply-plan.json
+geo-ai-search-optimization agent-executor ./reports/apply-plan.json --task fix-02 --json
+```
+
+它会输出：
+
+- 当前先做哪一包
+- 为什么先做这一包
+- do-now checklist
+- stop checklist
+- success checklist
+- 验证命令
+- 给用户的回报模板
+- 可直接复制给 agent 的 executor prompt
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -476,6 +519,8 @@ geo-ai-search-optimization install
 geo-ai-search-optimization install --target ./tmp/custom-skills --json
 geo-ai-search-optimization auto-flow "audit this site and tell me the next skill"
 geo-ai-search-optimization agent-session ./your-site
+geo-ai-search-optimization agent-runbook ./your-site
+geo-ai-search-optimization agent-executor ./your-site
 geo-ai-search-optimization skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -532,6 +577,20 @@ geo-ai-search-optimization help
 - 新增 `geo-ai-search-optimization-agent-session` skill
 - 更适合把 GEO 任务直接交给下一个 agent 连续推进
 
+## New in 1.2.9
+
+- 新增 `agent-runbook` 命令
+- 把 `agent-session` 继续推进成给 agent 使用的执行手册和检查清单
+- 输出开始前检查、工作规则、停止条件、验证清单、回报清单
+- 新增 `geo-ai-search-optimization-agent-runbook` skill
+
+## New in 1.2.10
+
+- 新增 `agent-executor` 命令
+- 把 runbook 再收敛成“这一轮先做哪 1 包”的单任务入口
+- 输出 do-now checklist、stop checklist、success checklist、验证命令和回报模板
+- 新增 `geo-ai-search-optimization-agent-executor` skill
+
 ## New in 1.2.5
 
 - 新增 `publish-pack`
@@ -715,10 +774,22 @@ Override with:
 
 ## Resource contents
 
-The installed package now includes two bundled skills:
+The installed package now includes a bundled GEO skill pack, including:
 
 - `geo-ai-search-optimization`
+- `geo-ai-search-optimization-auto-flow`
+- `geo-ai-search-optimization-agent-session`
+- `geo-ai-search-optimization-agent-runbook`
+- `geo-ai-search-optimization-agent-executor`
 - `geo-ai-search-optimization-usage`
+- `geo-ai-search-optimization-agent-handoff`
+- `geo-ai-search-optimization-repair-loop`
+- `geo-ai-search-optimization-completion-report`
+- `geo-ai-search-optimization-handoff-bundle`
+- `geo-ai-search-optimization-share-pack`
+- `geo-ai-search-optimization-export-pack`
+- `geo-ai-search-optimization-html-pack`
+- `geo-ai-search-optimization-publish-pack`
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/resources/geo-ai-search-optimization/references/skill-bundle-map.md

@@ -42,6 +42,26 @@ Best for:
 - giving the next agent a first command, second command, and expected artifact list
 - reducing ambiguity at handoff time
 
+### `geo-ai-search-optimization-agent-runbook`
+
+Use this when the next agent needs an execution manual, not just a session sequence.
+
+Best for:
+
+- turning a GEO session into a checklist-driven runbook
+- telling the next agent what to check before acting
+- defining stop conditions, validation checklist, and reporting checklist
+
+### `geo-ai-search-optimization-agent-executor`
+
+Use this when the next agent should stop planning and start one concrete execution packet.
+
+Best for:
+
+- selecting the first packet to execute now
+- reducing a runbook into one actionable task
+- giving the next agent a single-task prompt, validation commands, and reply template
+
 ## Usage guide
 
 ### `geo-ai-search-optimization-usage`

package/resources/geo-ai-search-optimization-agent-executor/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: geo-ai-search-optimization-agent-executor
+description: Turn a GEO input into a single-task execution entrypoint for the next agent. Use when an agent should stop planning and start one concrete GEO packet now, with a selected task, do-now checklist, validation commands, success criteria, and a reply template.
+---
+
+# GEO Agent Executor
+
+Use this skill when the next agent should execute one packet now, not keep expanding the plan.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- select the first or requested execution packet
+- compress the runbook into one task entrypoint
+- define do-now, stop, and success checklists
+- provide validation commands and a reply template
+- make the next agent focus on one packet at a time
+
+## Best use
+
+- when `agent-runbook` is still too broad
+- when a PM or another agent asks “this round, what should we do first?”
+- when execution should start from one concrete packet

package/resources/geo-ai-search-optimization-agent-executor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Executor"
+  short_description: "Start one GEO execution packet right now"
+  default_prompt: "Use $geo-ai-search-optimization-agent-executor to choose the first GEO packet to execute now, with a do-now checklist, validation commands, and a reply template."

package/resources/geo-ai-search-optimization-agent-runbook/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: geo-ai-search-optimization-agent-runbook
+description: Turn a GEO input into an execution runbook for the next agent. Use when an agent needs more than routing or a session plan, and should receive a checklist-driven manual with preflight checks, stop conditions, validation steps, reporting expectations, and optional execution packets.
+---
+
+# GEO Agent Runbook
+
+Use this skill when the next agent should receive a practical runbook, not just a list of commands.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- turn a GEO input into a checklist-driven execution manual
+- define what to check before acting
+- define what should stop execution
+- define how validation and reporting should work
+- carry the next agent from session planning into disciplined execution
+
+## Best use
+
+- when `agent-session` is still too light and the next agent needs a more operational checklist
+- when a PM or another agent wants a stable “follow this runbook” artifact
+- when execution needs preflight, validation, and reporting rules

package/resources/geo-ai-search-optimization-agent-runbook/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Runbook"
+  short_description: "Build a checklist-driven GEO execution manual"
+  default_prompt: "Use $geo-ai-search-optimization-agent-runbook to turn this input into a GEO runbook with preflight checks, execution checklist, validation steps, and reporting guidance."

package/resources/geo-ai-search-optimization-usage/SKILL.md

@@ -13,23 +13,25 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as fifteen layers:
+The package is best explained as seventeen layers:
 
 1. `auto-flow`: auto-select the next skill and command chain
 2. `agent-session`: build a runnable session for the next agent
-3. `skills`: inspect the bundled skill package
-4. `onboard-url` / `onboard`: first look
-5. `scan`: raw signal check
-6. `audit` / `report`: diagnosis
-7. `fix-plan` / `owner-board`: execution planning
-8. `agent-handoff`: agent takeover package
-9. `apply-plan`: execution loop
-10. `completion-report`: closeout
-11. `handoff-bundle`: all-in-one package
-12. `share-pack`: audience-ready delivery
-13. `export-pack`: folder export
-14. `html-pack` / `publish-pack`: browsable and final delivery output
-15. `pm-brief` / `roadmap`: stakeholder alignment
+3. `agent-runbook`: execution manual and checklist for the next agent
+4. `agent-executor`: choose one packet to execute right now
+5. `skills`: inspect the bundled skill package
+6. `onboard-url` / `onboard`: first look
+7. `scan`: raw signal check
+8. `audit` / `report`: diagnosis
+9. `fix-plan` / `owner-board`: execution planning
+10. `agent-handoff`: agent takeover package
+11. `apply-plan`: execution loop
+12. `completion-report`: closeout
+13. `handoff-bundle`: all-in-one package
+14. `share-pack`: audience-ready delivery
+15. `export-pack`: folder export
+16. `html-pack` / `publish-pack`: browsable and final delivery output
+17. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -38,6 +40,8 @@ If the user only has a website URL:
 ```bash
 npx geo-ai-search-optimization auto-flow https://example.com
 npx geo-ai-search-optimization agent-session https://example.com
+npx geo-ai-search-optimization agent-runbook https://example.com
+npx geo-ai-search-optimization agent-executor https://example.com
 npx geo-ai-search-optimization onboard-url https://example.com
 npx geo-ai-search-optimization pm-brief https://example.com
 npx geo-ai-search-optimization roadmap https://example.com
@@ -48,6 +52,8 @@ If the user has the website codebase:
 ```bash
 npx geo-ai-search-optimization auto-flow ./your-site
 npx geo-ai-search-optimization agent-session ./your-site
+npx geo-ai-search-optimization agent-runbook ./your-site
+npx geo-ai-search-optimization agent-executor ./your-site
 npx geo-ai-search-optimization scan ./your-site
 npx geo-ai-search-optimization audit ./your-site
 npx geo-ai-search-optimization fix-plan ./your-site
@@ -67,6 +73,8 @@ npx geo-ai-search-optimization roadmap ./your-site
 
 - `auto-flow`: auto-select the next skill and command order from a task brief, URL, project path, or GEO artifact
 - `agent-session`: build a step-by-step session packet for the next agent from the same kinds of inputs
+- `agent-runbook`: build a checklist-driven runbook with preflight, validation, and reporting rules
+- `agent-executor`: select one packet to execute now and package it into a single-task entrypoint
 - `onboard-url`: first-time website check from a live URL
 - `onboard`: interactive first-time onboarding
 - `skills`: list the bundled skills and decide which skill or command chain fits the task
@@ -93,6 +101,8 @@ When explaining the tool to a user:
 - prefer telling them which command to run next, not listing every command
 - if the user or the next agent is unsure where to start, move them to `auto-flow` first
 - if the user wants something the next agent can follow step by step, move them to `agent-session`
+- if the user wants the next agent to follow a checklist and execution manual, move them to `agent-runbook`
+- if the user wants the next agent to start one concrete task now, move them to `agent-executor`
 - explain the result in PM language, not implementation jargon
 - if the user sounds new, start with `onboard-url` or `quick-start`
 - if the user wants another agent to take over, move them to `agent-handoff`

package/src/agent-executor.js

@@ -0,0 +1,319 @@
+import { readFile } from "node:fs/promises";
+import { createApplyPlan } from "./apply-plan.js";
+import { createAgentRunbook } from "./agent-runbook.js";
+import { writeScanOutput } from "./scan.js";
+
+const VALID_FORMATS = new Set(["markdown", "json"]);
+
+function normalizeFormat(format) {
+  const resolved = (format || "markdown").toLowerCase();
+  if (!VALID_FORMATS.has(resolved)) {
+    throw new Error(`不支持的 agent-executor 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+async function loadJsonArtifact(input) {
+  const raw = await readFile(input, "utf8");
+  return JSON.parse(raw);
+}
+
+async function resolveRunbookAndPlan(input, options = {}) {
+  const runbook = await createAgentRunbook(input, {
+    format: "json",
+    intent: options.intent,
+    taskId: options.taskId
+  });
+
+  if (runbook.applyPlan?.kind === "geo-apply-plan") {
+    return {
+      runbook,
+      applyPlan: runbook.applyPlan
+    };
+  }
+
+  if (runbook.sourceType === "json") {
+    const parsed = await loadJsonArtifact(input).catch(() => null);
+    if (parsed?.kind === "geo-apply-plan") {
+      return {
+        runbook,
+        applyPlan: parsed
+      };
+    }
+    if (parsed?.kind === "geo-agent-runbook" && parsed.applyPlan?.kind === "geo-apply-plan") {
+      return {
+        runbook,
+        applyPlan: parsed.applyPlan
+      };
+    }
+  }
+
+  try {
+    const applyPlan = await createApplyPlan(input, {
+      format: "json",
+      taskId: options.taskId
+    });
+    return {
+      runbook,
+      applyPlan
+    };
+  } catch {
+    return {
+      runbook,
+      applyPlan: null
+    };
+  }
+}
+
+function inferExecutorMode(runbook, applyPlan) {
+  if (!applyPlan?.packets?.length) {
+    if (runbook.contextNeeded?.length) {
+      return "needs-context";
+    }
+    return "planning-only";
+  }
+  return applyPlan.executionType || "guided-planning";
+}
+
+function selectPacket(applyPlan, taskId) {
+  if (!applyPlan?.packets?.length) {
+    return null;
+  }
+
+  if (taskId) {
+    const selected = applyPlan.packets.find((packet) => packet.id === taskId);
+    if (!selected) {
+      throw new Error(`找不到执行包：${taskId}`);
+    }
+    return selected;
+  }
+
+  return applyPlan.packets[0];
+}
+
+function buildSelectionReason(packet, applyPlan, taskId) {
+  if (!packet) {
+    return "当前还没有可执行任务包，说明需要先补上下文或先生成 apply-plan。";
+  }
+  if (taskId) {
+    return `已按指定任务 ID 选中：${taskId}。`;
+  }
+  if (applyPlan?.selectedTaskCount > 1) {
+    return "默认选择第一包，代表当前优先级最高、最适合立刻开始的一项任务。";
+  }
+  return "当前只有一个任务包，因此直接将它作为本轮执行入口。";
+}
+
+function buildDoNowChecklist(packet, executorMode) {
+  if (!packet) {
+    return [];
+  }
+
+  const items = [
+    `先锁定任务范围：${packet.title}`,
+    ...packet.inspectTargets.slice(0, 3).map((item) => `先检查：${item}`),
+    ...packet.editPlan.slice(0, 3).map((item) => `执行动作：${item}`)
+  ];
+
+  if (executorMode === "direct-fix") {
+    items.push("开始修改前先确认会影响整类页面的复用层，而不是只 patch 单页。");
+  }
+
+  return items;
+}
+
+function buildStopChecklist(runbook, packet, executorMode) {
+  const items = [...(runbook.stopConditions || [])];
+
+  if (!packet) {
+    items.push("还没有拿到执行包时，不要假装已经进入真正修复阶段。");
+    return items;
+  }
+
+  if (executorMode === "recommendation-only") {
+    items.push("如果当前只有网址或建议上下文，不要输出伪造的代码修改结果。");
+  }
+
+  items.push("如果执行中发现这不是最高优先级任务，应先说明原因，再决定是否切换。");
+  return items;
+}
+
+function buildSuccessChecklist(packet) {
+  if (!packet) {
+    return [];
+  }
+
+  return [
+    ...packet.doneWhen,
+    "你已经能用 PM 可读的方式说明：改了什么、为什么改、验证结果是什么。"
+  ];
+}
+
+function buildNextCommands(runbook, packet, input) {
+  if (!packet) {
+    return runbook.nextCommands || [`geo-ai-search-optimization agent-runbook ${input}`];
+  }
+
+  const source = runbook.source;
+  return [
+    `geo-ai-search-optimization completion-report ${source}`,
+    `geo-ai-search-optimization handoff-bundle ${source}`
+  ];
+}
+
+function buildUserReplyTemplate(packet, executorMode) {
+  if (!packet) {
+    return [
+      "结论：我还不能直接执行，因为当前缺少足够上下文。",
+      "我目前确认到的情况：",
+      "- ",
+      "我还需要你补充：",
+      "- ",
+      "拿到这些之后，我会先执行：",
+      "- "
+    ].join("\n");
+  }
+
+  const closingLine =
+    executorMode === "direct-fix"
+      ? "我已经完成这一包可直接落地的部分，并附上复测结果。"
+      : executorMode === "recommendation-only"
+        ? "我已经完成这一包的建议版执行，但还需要更多上下文才能继续实际修改。"
+        : "我已经把这一包的执行顺序和阻塞项整理好，下一步可以继续推进。";
+
+  return [
+    `任务：${packet.title}`,
+    `结论：${closingLine}`,
+    "这次我先做了什么：",
+    "- ",
+    "我检查了哪些文件 / 页面 / 模板：",
+    "- ",
+    "我实际修改或建议了什么：",
+    "- ",
+    "验证结果：",
+    "- ",
+    "剩余风险或下一步：",
+    "- "
+  ].join("\n");
+}
+
+function buildExecutorPrompt(runbook, packet, executorMode, selectionReason) {
+  const lines = [
+    "你现在进入 GEO 单任务执行模式。",
+    `当前输入：${runbook.source}`,
+    `当前阶段：${runbook.stage}`,
+    `执行模式：${executorMode}`,
+    `任务选择原因：${selectionReason}`
+  ];
+
+  if (packet) {
+    lines.push(`本轮只做这一包：${packet.title}`);
+    lines.push("请你按这个顺序输出：");
+    lines.push("1. 先检查什么");
+    lines.push("2. 你准备如何执行这一包");
+    lines.push("3. 你会如何验证");
+    lines.push("4. 完成后如何向用户回报");
+  } else {
+    lines.push("当前还不能执行具体任务。请先明确缺什么上下文，再告诉用户下一步要补什么。");
+  }
+
+  lines.push("一次只推进一包，不要在同一轮同时展开多个任务。");
+  return lines.join("\n");
+}
+
+export async function createAgentExecutor(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const { runbook, applyPlan } = await resolveRunbookAndPlan(input, options);
+  const executorMode = inferExecutorMode(runbook, applyPlan);
+  const packet = selectPacket(applyPlan, options.taskId);
+  const selectionReason = buildSelectionReason(packet, applyPlan, options.taskId);
+
+  return {
+    kind: "geo-agent-executor",
+    input,
+    source: runbook.source,
+    sourceType: runbook.sourceType,
+    artifactKind: runbook.artifactKind,
+    format,
+    intent: runbook.intent,
+    stage: runbook.stage,
+    executorMode,
+    goal: packet ? `先完成这一包：${packet.title}` : runbook.goal,
+    selectionReason,
+    selectedSkill: {
+      name: "geo-ai-search-optimization-agent-executor",
+      displayName: "GEO Agent Executor",
+      shortDescription: "Start one GEO execution packet right now"
+    },
+    selectedPacket: packet,
+    doNowChecklist: buildDoNowChecklist(packet, executorMode),
+    stopChecklist: buildStopChecklist(runbook, packet, executorMode),
+    successChecklist: buildSuccessChecklist(packet),
+    validationCommands: packet?.validationCommands || runbook.validationChecklist || [],
+    userReplyTemplate: buildUserReplyTemplate(packet, executorMode),
+    nextCommands: buildNextCommands(runbook, packet, input),
+    executorPrompt: buildExecutorPrompt(runbook, packet, executorMode, selectionReason),
+    agentRunbook: runbook,
+    applyPlan
+  };
+}
+
+export function renderAgentExecutorMarkdown(executor) {
+  const lines = [
+    "# GEO Agent Executor",
+    "",
+    `- 输入：\`${executor.source}\``,
+    `- 输入类型：\`${executor.sourceType}\``,
+    `- 工件类型：\`${executor.artifactKind}\``,
+    `- 当前阶段：${executor.stage}`,
+    `- 执行模式：\`${executor.executorMode}\``,
+    `- 本轮目标：${executor.goal}`,
+    `- 任务选择原因：${executor.selectionReason}`,
+    "",
+    "## 现在先做什么",
+    ""
+  ];
+
+  for (const item of executor.doNowChecklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  if (executor.selectedPacket) {
+    lines.push("", "## 当前任务包", "");
+    lines.push(`- ID：\`${executor.selectedPacket.id}\``);
+    lines.push(`- 标题：${executor.selectedPacket.title}`);
+    lines.push(`- 优先级：${executor.selectedPacket.priority}`);
+    lines.push(`- Owner：${executor.selectedPacket.owner}`);
+    lines.push(`- 执行类型：\`${executor.selectedPacket.executionType}\``);
+    lines.push("");
+    lines.push("### 验证命令", "");
+    for (const command of executor.validationCommands) {
+      lines.push(`- \`${command}\``);
+    }
+  }
+
+  lines.push("", "## 需要停下来的情况", "");
+  for (const item of executor.stopChecklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 完成标准", "");
+  for (const item of executor.successChecklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 完成后怎么回报用户", "", "```text", executor.userReplyTemplate, "```");
+
+  lines.push("", "## 下一步推荐命令", "");
+  for (const command of executor.nextCommands) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push("", "## 可直接复制给 Agent 的 Executor Prompt", "", "```text", executor.executorPrompt, "```");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentExecutorOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}