geo-ai-search-optimization 1.2.10 → 1.2.12

package/README.md

@@ -124,6 +124,47 @@ geo-ai-search-optimization agent-executor ./reports/apply-plan.json --task fix-0
 - 给用户的回报模板
 - 可直接复制给 agent 的 executor prompt
 
+## Agent Batch Executor 命令
+
+如果你希望 agent 不只做 1 包，而是把前 2 到 3 包排成一个连续执行序列，同时仍然保持“一次只推进一包”，可以直接用 `agent-batch-executor`：
+
+```bash
+geo-ai-search-optimization agent-batch-executor ./your-site
+geo-ai-search-optimization agent-batch-executor ./reports/apply-plan.json
+geo-ai-search-optimization agent-batch-executor ./reports/apply-plan.json --task fix-02 --count 3 --format json --out ./reports/agent-batch-executor.json
+```
+
+`agent-batch-executor` 会输出：
+
+- 当前批次先推进哪几包
+- 为什么按这个顺序推进
+- 每一包的 do-now checklist
+- 每一包的 stop checklist
+- 每一包的 success checklist
+- 批次总验证命令
+- 批次收尾命令
+- 可直接复制给 agent 的 batch prompt
+
+## Agent Progress Tracker 命令
+
+如果你希望 agent 不是只拿到执行队列，而是能够明确回答“现在做到第几包、当前卡在哪、下一包是什么”，可以直接用 `agent-progress-tracker`：
+
+```bash
+geo-ai-search-optimization agent-progress-tracker ./your-site
+geo-ai-search-optimization agent-progress-tracker ./reports/apply-plan.json --completed fix-01,fix-02 --current fix-03
+geo-ai-search-optimization agent-progress-tracker ./reports/agent-batch-executor.json --blocked "缺少仓库权限,缺少模板文件" --format json --out ./reports/agent-progress-tracker.json
+```
+
+`agent-progress-tracker` 会输出：
+
+- 当前状态是未开始、进行中、阻塞还是已完成
+- 已完成到哪几包
+- 当前正在推进哪一包
+- 下一包是什么
+- 当前阻塞项
+- 建议下一步命令
+- 可直接复制给 agent 的 progress prompt
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -521,6 +562,8 @@ 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 agent-batch-executor ./your-site
+geo-ai-search-optimization agent-progress-tracker ./your-site
 geo-ai-search-optimization skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -591,6 +634,20 @@ geo-ai-search-optimization help
 - 输出 do-now checklist、stop checklist、success checklist、验证命令和回报模板
 - 新增 `geo-ai-search-optimization-agent-executor` skill
 
+## New in 1.2.12
+
+- 新增 `agent-progress-tracker` 命令
+- 可以从 `apply-plan`、`agent-executor`、`agent-batch-executor` 等工件推导当前执行进度
+- 输出已完成任务、当前包、下一包、阻塞项和建议下一步命令
+- 新增 `geo-ai-search-optimization-agent-progress-tracker` skill
+
+## New in 1.2.11
+
+- 新增 `agent-batch-executor` 命令
+- 让 agent 可以连续推进前几包任务，但仍然保持一次只执行一包
+- 输出批次顺序、每包检查清单、批次总验证命令和收尾命令
+- 新增 `geo-ai-search-optimization-agent-batch-executor` skill
+
 ## New in 1.2.5
 
 - 新增 `publish-pack`
@@ -781,6 +838,8 @@ The installed package now includes a bundled GEO skill pack, including:
 - `geo-ai-search-optimization-agent-session`
 - `geo-ai-search-optimization-agent-runbook`
 - `geo-ai-search-optimization-agent-executor`
+- `geo-ai-search-optimization-agent-batch-executor`
+- `geo-ai-search-optimization-agent-progress-tracker`
 - `geo-ai-search-optimization-usage`
 - `geo-ai-search-optimization-agent-handoff`
 - `geo-ai-search-optimization-repair-loop`

package/package.json

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

@@ -62,6 +62,26 @@ Best for:
 - reducing a runbook into one actionable task
 - giving the next agent a single-task prompt, validation commands, and reply template
 
+### `geo-ai-search-optimization-agent-batch-executor`
+
+Use this when the next agent should continuously advance the first few execution packets, but still only work on one packet at a time.
+
+Best for:
+
+- turning an `apply-plan` into a short execution queue
+- making the next agent finish packet 1 before packet 2 starts
+- giving the next agent a batch-level prompt, per-packet checklists, and final closeout commands
+
+### `geo-ai-search-optimization-agent-progress-tracker`
+
+Use this when the next agent should explain current execution status, not just produce the next queue.
+
+Best for:
+
+- showing which packet is already done
+- clarifying the current active packet and the next packet
+- surfacing blockers before the team moves into closeout or the next batch
+
 ## Usage guide
 
 ### `geo-ai-search-optimization-usage`

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

@@ -0,0 +1,24 @@
+---
+name: geo-ai-search-optimization-agent-batch-executor
+description: Turn a GEO input into a short multi-packet execution queue for the next agent. Use when an agent should continuously advance the first 2 to 3 GEO packets in order, while still executing only one packet at a time, with per-packet checklists, validation commands, and closeout steps.
+---
+
+# GEO Agent Batch Executor
+
+Use this skill when the next agent should not stop at one task, but also should not expand into an uncontrolled multi-task run.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- select the first few execution packets from an apply-plan or equivalent artifact
+- keep the execution order explicit
+- enforce one-packet-at-a-time progress
+- provide per-packet do-now, stop, and success checklists
+- give the next agent one batch prompt plus final closeout commands
+
+## Best use
+
+- when `agent-executor` is too narrow because the next agent should keep going after packet 1
+- when a PM wants “finish the first 2 to 3 packets in order”
+- when the next agent needs a short queue, not a full open-ended plan

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Batch Executor"
+  short_description: "Queue the first GEO packets for one-by-one execution"
+  default_prompt: "Use $geo-ai-search-optimization-agent-batch-executor to choose the first 2 to 3 GEO packets to advance in order, while still executing only one packet at a time."

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

@@ -0,0 +1,23 @@
+---
+name: geo-ai-search-optimization-agent-progress-tracker
+description: Track GEO execution progress from apply-plan, agent-executor, agent-batch-executor, completion-report, or related artifacts. Use when an agent should explain which GEO packet is already done, which one is active, what is blocked, and what command should run next.
+---
+
+# GEO Agent Progress Tracker
+
+Use this skill when the next agent should stop guessing current status and make the execution state explicit.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- reads GEO execution artifacts and infers the current packet state
+- shows completed packets, the active packet, the next packet, and blockers
+- recommends the next command for continuing or closing out the work
+- gives the next agent a progress-tracking prompt instead of another open-ended plan
+
+## Best use
+
+- when a PM asks “现在做到哪了？”
+- when the next agent should explain status before touching the next packet
+- when batch execution is underway and the team needs a stable progress checkpoint

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Progress Tracker"
+  short_description: "Track which GEO packet is done, active, or blocked"
+  default_prompt: "Use $geo-ai-search-optimization-agent-progress-tracker to explain GEO execution progress, blockers, the current packet, and the next command."

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

@@ -13,25 +13,27 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as seventeen layers:
+The package is best explained as nineteen layers:
 
 1. `auto-flow`: auto-select the next skill and command chain
 2. `agent-session`: build a runnable session for the next agent
 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
+5. `agent-batch-executor`: queue the first few packets, but still advance one packet at a time
+6. `agent-progress-tracker`: track which packet is done, which one is active, and what comes next
+7. `skills`: inspect the bundled skill package
+8. `onboard-url` / `onboard`: first look
+9. `scan`: raw signal check
+10. `audit` / `report`: diagnosis
+11. `fix-plan` / `owner-board`: execution planning
+12. `agent-handoff`: agent takeover package
+13. `apply-plan`: execution loop
+14. `completion-report`: closeout
+15. `handoff-bundle`: all-in-one package
+16. `share-pack`: audience-ready delivery
+17. `export-pack`: folder export
+18. `html-pack` / `publish-pack`: browsable and final delivery output
+19. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -42,6 +44,8 @@ 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 agent-batch-executor https://example.com
+npx geo-ai-search-optimization agent-progress-tracker 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
@@ -54,6 +58,8 @@ 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 agent-batch-executor ./your-site
+npx geo-ai-search-optimization agent-progress-tracker ./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
@@ -75,6 +81,8 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `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
+- `agent-batch-executor`: line up the first few packets in execution order while preserving one-packet-at-a-time discipline
+- `agent-progress-tracker`: show execution progress, current packet, blockers, and the next packet to advance
 - `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
@@ -103,6 +111,8 @@ When explaining the tool to a user:
 - 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`
+- if the user wants the next agent to continuously advance the first 2 to 3 packets in order, move them to `agent-batch-executor`
+- if the user wants the next agent to explain current progress, blockers, and the next packet, move them to `agent-progress-tracker`
 - 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-batch-executor.js

@@ -0,0 +1,327 @@
+import { readFile } from "node:fs/promises";
+import { createApplyPlan } from "./apply-plan.js";
+import { createAgentExecutor } from "./agent-executor.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-batch-executor 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+function normalizeCount(count) {
+  if (count == null) {
+    return 3;
+  }
+
+  const parsed = Number.parseInt(count, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error("--count 必须是正整数");
+  }
+
+  return Math.min(parsed, 5);
+}
+
+async function loadApplyPlanArtifact(input) {
+  const raw = await readFile(input, "utf8");
+  const parsed = JSON.parse(raw);
+
+  if (parsed?.kind === "geo-apply-plan") {
+    return parsed;
+  }
+  if (parsed?.kind === "geo-agent-runbook" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return parsed.applyPlan;
+  }
+  if (parsed?.kind === "geo-agent-executor" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return parsed.applyPlan;
+  }
+
+  return null;
+}
+
+async function resolveApplyPlan(input) {
+  const artifact = await loadApplyPlanArtifact(input).catch(() => null);
+  if (artifact) {
+    return artifact;
+  }
+
+  return createApplyPlan(input, {
+    format: "json"
+  });
+}
+
+function selectPackets(applyPlan, count, startTaskId) {
+  const packets = applyPlan?.packets || [];
+  if (packets.length === 0) {
+    return [];
+  }
+
+  let startIndex = 0;
+  if (startTaskId) {
+    startIndex = packets.findIndex((packet) => packet.id === startTaskId);
+    if (startIndex === -1) {
+      throw new Error(`找不到执行包：${startTaskId}`);
+    }
+  }
+
+  return packets.slice(startIndex, startIndex + count);
+}
+
+async function buildPacketExecutors(input, packets, options) {
+  const results = [];
+
+  for (const packet of packets) {
+    const executor = await createAgentExecutor(input, {
+      format: "json",
+      intent: options.intent,
+      taskId: packet.id
+    });
+
+    results.push({
+      position: results.length + 1,
+      id: packet.id,
+      title: packet.title,
+      priority: packet.priority,
+      owner: packet.owner,
+      executorMode: executor.executorMode,
+      doNowChecklist: executor.doNowChecklist,
+      stopChecklist: executor.stopChecklist,
+      successChecklist: executor.successChecklist,
+      validationCommands: executor.validationCommands,
+      userReplyTemplate: executor.userReplyTemplate,
+      executorPrompt: executor.executorPrompt,
+      startCommand: `geo-ai-search-optimization agent-executor ${executor.source} --task ${packet.id}`,
+      nextCommands: executor.nextCommands
+    });
+  }
+
+  return results;
+}
+
+function inferBatchMode(packetExecutors) {
+  if (packetExecutors.length === 0) {
+    return "needs-context";
+  }
+
+  const modes = new Set(packetExecutors.map((packet) => packet.executorMode));
+  if (modes.size === 1) {
+    return packetExecutors[0].executorMode;
+  }
+  return "mixed";
+}
+
+function buildSelectionReason(packets, applyPlan, count, startTaskId) {
+  if (packets.length === 0) {
+    return "当前还没有可批量执行的任务包，说明需要先补上下文或先生成 apply-plan。";
+  }
+
+  if (startTaskId) {
+    return `已从指定任务 ${startTaskId} 开始，连续选出后续 ${packets.length} 包，按顺序推进。`;
+  }
+
+  if (packets.length === 1) {
+    return "当前只拿到 1 个任务包，因此直接把它作为本轮批处理入口。";
+  }
+
+  const available = applyPlan?.packets?.length || packets.length;
+  if (available < count) {
+    return `计划最多取前 ${count} 包，但当前只有 ${available} 包可用，因此按现有顺序推进这 ${packets.length} 包。`;
+  }
+
+  return `已按优先级选出前 ${packets.length} 包，按顺序推进，但一次只执行一包。`;
+}
+
+function buildBatchRules(batchMode) {
+  const items = [
+    "始终一次只推进一包，不要同时展开多个修复包。",
+    "每做完一包，都先检查完成标准和验证命令，再决定是否进入下一包。",
+    "如果上一包没有通过验收，不要直接跳到下一包。"
+  ];
+
+  if (batchMode === "direct-fix") {
+    items.push("每包都优先改复用层，而不是只 patch 单页。");
+  }
+  if (batchMode === "recommendation-only") {
+    items.push("当前更适合给建议，不要伪造已经完成的代码修改。");
+  }
+
+  return items;
+}
+
+function buildQueueSummary(packetExecutors) {
+  return packetExecutors.map((packet, index) => ({
+    position: index + 1,
+    id: packet.id,
+    title: packet.title,
+    priority: packet.priority,
+    owner: packet.owner,
+    startCommand: packet.startCommand,
+    stopIf: packet.stopChecklist[packet.stopChecklist.length - 1] || "当前包未达成完成标准时不要继续。",
+    afterSuccess:
+      index < packetExecutors.length - 1
+        ? `进入下一包：${packetExecutors[index + 1].id}`
+        : "进入 completion-report 与 handoff-bundle 收尾。"
+  }));
+}
+
+function buildValidationRollup(packetExecutors) {
+  const commands = new Set();
+  for (const packet of packetExecutors) {
+    for (const command of packet.validationCommands) {
+      commands.add(command);
+    }
+  }
+  return Array.from(commands);
+}
+
+function buildFinalCommands(source) {
+  return [
+    `geo-ai-search-optimization completion-report ${source}`,
+    `geo-ai-search-optimization handoff-bundle ${source}`,
+    `geo-ai-search-optimization publish-pack ${source}`
+  ];
+}
+
+function buildBatchPrompt(batch) {
+  const lines = [
+    "你现在进入 GEO 多任务批次执行模式。",
+    `当前输入：${batch.source}`,
+    `批次模式：${batch.batchMode}`,
+    `批次目标：${batch.goal}`,
+    `批次选择原因：${batch.selectionReason}`,
+    "请遵守：一次只推进一包，上一包通过验证后再进入下一包。"
+  ];
+
+  if (batch.packetExecutors.length > 0) {
+    lines.push("当前批次顺序：");
+    for (const packet of batch.packetExecutors) {
+      lines.push(`${packet.position}. ${packet.id}｜${packet.title}`);
+    }
+  } else {
+    lines.push("当前还没有可执行包。请先告诉用户缺什么上下文。");
+  }
+
+  lines.push("每一包都要输出：先检查什么、怎么做、如何验证、完成后如何回报。");
+  return lines.join("\n");
+}
+
+export async function createAgentBatchExecutor(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const count = normalizeCount(options.count);
+  const applyPlan = await resolveApplyPlan(input);
+  const selectedPackets = selectPackets(applyPlan, count, options.taskId);
+  const packetExecutors = await buildPacketExecutors(input, selectedPackets, options);
+  const batchMode = inferBatchMode(packetExecutors);
+  const source = packetExecutors[0]?.startCommand ? applyPlan.source || input : applyPlan?.source || input;
+
+  return {
+    kind: "geo-agent-batch-executor",
+    input,
+    source,
+    sourceType: applyPlan?.sourceType || "unknown",
+    artifactKind: applyPlan?.kind || "unknown",
+    format,
+    batchMode,
+    packetCount: packetExecutors.length,
+    goal:
+      packetExecutors.length > 0
+        ? `按顺序推进这 ${packetExecutors.length} 包，但每次只执行一包。`
+        : "当前先补上下文，再进入多任务批次执行。",
+    selectionReason: buildSelectionReason(selectedPackets, applyPlan, count, options.taskId),
+    batchRules: buildBatchRules(batchMode),
+    queueSummary: buildQueueSummary(packetExecutors),
+    packetExecutors,
+    validationRollup: buildValidationRollup(packetExecutors),
+    finalCommands: buildFinalCommands(source),
+    batchPrompt: buildBatchPrompt({
+      source,
+      batchMode,
+      goal:
+        packetExecutors.length > 0
+          ? `按顺序推进这 ${packetExecutors.length} 包，但每次只执行一包。`
+          : "当前先补上下文，再进入多任务批次执行。",
+      selectionReason: buildSelectionReason(selectedPackets, applyPlan, count, options.taskId),
+      packetExecutors
+    }),
+    applyPlan
+  };
+}
+
+export function renderAgentBatchExecutorMarkdown(batch) {
+  const lines = [
+    "# GEO Agent Batch Executor",
+    "",
+    `- 输入：\`${batch.source}\``,
+    `- 来源类型：\`${batch.sourceType}\``,
+    `- 工件类型：\`${batch.artifactKind}\``,
+    `- 批次模式：\`${batch.batchMode}\``,
+    `- 批次数量：\`${batch.packetCount}\``,
+    `- 目标：${batch.goal}`,
+    `- 选择原因：${batch.selectionReason}`,
+    "",
+    "## 批次规则",
+    ""
+  ];
+
+  for (const item of batch.batchRules) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 执行顺序", "");
+  for (const item of batch.queueSummary) {
+    lines.push(`### ${item.position}. ${item.id}｜${item.title}`, "");
+    lines.push(`- 优先级：${item.priority}`);
+    lines.push(`- Owner：${item.owner}`);
+    lines.push(`- 开始命令：\`${item.startCommand}\``);
+    lines.push(`- 继续条件：${item.afterSuccess}`);
+    lines.push(`- 停下条件：${item.stopIf}`);
+    lines.push("");
+  }
+
+  for (const packet of batch.packetExecutors) {
+    lines.push(`## ${packet.position}. ${packet.id}｜${packet.title}`, "");
+    lines.push("- Do now：");
+    for (const item of packet.doNowChecklist) {
+      lines.push(`  - [ ] ${item}`);
+    }
+    lines.push("- 停下条件：");
+    for (const item of packet.stopChecklist) {
+      lines.push(`  - [ ] ${item}`);
+    }
+    lines.push("- 完成标准：");
+    for (const item of packet.successChecklist) {
+      lines.push(`  - [ ] ${item}`);
+    }
+    lines.push("- 验证命令：");
+    for (const command of packet.validationCommands) {
+      lines.push(`  - \`${command}\``);
+    }
+    lines.push("- 回报模板：");
+    lines.push("```text");
+    lines.push(packet.userReplyTemplate);
+    lines.push("```");
+    lines.push("");
+  }
+
+  lines.push("## 批次总验证命令", "");
+  for (const command of batch.validationRollup) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push("", "## 最终收尾命令", "");
+  for (const command of batch.finalCommands) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push("", "## 可直接复制给 Agent 的 Batch Prompt", "", "```text", batch.batchPrompt, "```");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentBatchExecutorOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}