geo-ai-search-optimization 1.2.11 → 1.2.12

package/README.md

@@ -145,6 +145,26 @@ geo-ai-search-optimization agent-batch-executor ./reports/apply-plan.json --task
 - 批次收尾命令
 - 可直接复制给 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 项目，建议照这个顺序做。
@@ -543,6 +563,7 @@ 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
@@ -613,6 +634,13 @@ 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` 命令
@@ -811,6 +839,7 @@ The installed package now includes a bundled GEO skill pack, including:
 - `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.11",
+  "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

@@ -72,6 +72,16 @@ Best for:
 - 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-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,26 +13,27 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as eighteen 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. `agent-batch-executor`: queue the first few packets, but still advance one packet at a time
-6. `skills`: inspect the bundled skill package
-7. `onboard-url` / `onboard`: first look
-8. `scan`: raw signal check
-9. `audit` / `report`: diagnosis
-10. `fix-plan` / `owner-board`: execution planning
-11. `agent-handoff`: agent takeover package
-12. `apply-plan`: execution loop
-13. `completion-report`: closeout
-14. `handoff-bundle`: all-in-one package
-15. `share-pack`: audience-ready delivery
-16. `export-pack`: folder export
-17. `html-pack` / `publish-pack`: browsable and final delivery output
-18. `pm-brief` / `roadmap`: stakeholder alignment
+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
 
@@ -44,6 +45,7 @@ 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
@@ -57,6 +59,7 @@ 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
@@ -79,6 +82,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `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
@@ -108,6 +112,7 @@ When explaining the tool to a user:
 - 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-progress-tracker.js

@@ -0,0 +1,482 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createApplyPlan } from "./apply-plan.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-progress-tracker 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+function parseCommaList(value) {
+  if (!value) {
+    return [];
+  }
+
+  return String(value)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isUrlInput(input) {
+  return /^https?:\/\//i.test(input);
+}
+
+function buildPseudoApplyPlanFromCompletionReport(report) {
+  return {
+    kind: "geo-apply-plan",
+    source: report.source,
+    sourceType: report.sourceType || "json",
+    executionType: report.executionType || "guided-planning",
+    executionMode: report.executionMode || "mixed",
+    selectedTaskCount: Array.isArray(report.nextRoundTasks) ? report.nextRoundTasks.length : 0,
+    packets: (report.nextRoundTasks || []).map((task) => {
+      const template = (report.completionTemplates || []).find((item) => item.id === task.id);
+      return {
+        id: task.id,
+        title: task.title,
+        owner: task.owner,
+        priority: "P1",
+        executionType: report.executionType || "guided-planning",
+        doneWhen: task.doneWhen || [],
+        validationCommands: report.validationChecklist || [],
+        completionTemplate: template?.template || ""
+      };
+    })
+  };
+}
+
+function buildExecutionContextFromParsedArtifact(parsed, input) {
+  if (parsed?.kind === "geo-apply-plan") {
+    return {
+      source: parsed.source || input,
+      sourceType: parsed.sourceType || "json",
+      artifactKind: parsed.kind,
+      applyPlan: parsed,
+      trackerState: {}
+    };
+  }
+
+  if (parsed?.kind === "geo-agent-runbook" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return {
+      source: parsed.source || parsed.applyPlan.source || input,
+      sourceType: parsed.sourceType || parsed.applyPlan.sourceType || "json",
+      artifactKind: parsed.kind,
+      applyPlan: parsed.applyPlan,
+      trackerState: {}
+    };
+  }
+
+  if (parsed?.kind === "geo-agent-executor" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return {
+      source: parsed.source || parsed.applyPlan.source || input,
+      sourceType: parsed.sourceType || parsed.applyPlan.sourceType || "json",
+      artifactKind: parsed.kind,
+      applyPlan: parsed.applyPlan,
+      trackerState: {
+        currentTaskId: parsed.selectedPacket?.id || null
+      }
+    };
+  }
+
+  if (parsed?.kind === "geo-agent-batch-executor" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return {
+      source: parsed.source || parsed.applyPlan.source || input,
+      sourceType: parsed.sourceType || parsed.applyPlan.sourceType || "json",
+      artifactKind: parsed.kind,
+      applyPlan: parsed.applyPlan,
+      trackerState: {
+        currentTaskId: parsed.packetExecutors?.[0]?.id || null
+      }
+    };
+  }
+
+  if (parsed?.kind === "geo-agent-progress-tracker" && parsed.applyPlan?.kind === "geo-apply-plan") {
+    return {
+      source: parsed.source || parsed.applyPlan.source || input,
+      sourceType: parsed.sourceType || parsed.applyPlan.sourceType || "json",
+      artifactKind: parsed.kind,
+      applyPlan: parsed.applyPlan,
+      trackerState: {
+        currentTaskId: parsed.currentTaskId || parsed.activePacket?.id || null,
+        completedPacketIds: parsed.completedPacketIds || [],
+        blockedReasons: parsed.blockedReasons || []
+      }
+    };
+  }
+
+  if (parsed?.kind === "geo-completion-report") {
+    return {
+      source: parsed.source || input,
+      sourceType: parsed.sourceType || "json",
+      artifactKind: parsed.kind,
+      applyPlan: buildPseudoApplyPlanFromCompletionReport(parsed),
+      trackerState: {}
+    };
+  }
+
+  return null;
+}
+
+async function resolveExecutionContext(input) {
+  if (!input) {
+    throw new Error("agent-progress-tracker 需要一个输入值，可以是项目路径、网站网址或已导出的 JSON 工件。");
+  }
+
+  if (isUrlInput(input)) {
+    const applyPlan = await createApplyPlan(input, { format: "json" });
+    return {
+      source: applyPlan.source,
+      sourceType: applyPlan.sourceType,
+      artifactKind: applyPlan.kind,
+      applyPlan,
+      trackerState: {}
+    };
+  }
+
+  const resolvedPath = path.resolve(input);
+  if (!(await pathExists(resolvedPath))) {
+    const applyPlan = await createApplyPlan(input, { format: "json" });
+    return {
+      source: applyPlan.source,
+      sourceType: applyPlan.sourceType,
+      artifactKind: applyPlan.kind,
+      applyPlan,
+      trackerState: {}
+    };
+  }
+
+  const stat = await fs.stat(resolvedPath);
+  if (stat.isDirectory()) {
+    const applyPlan = await createApplyPlan(resolvedPath, { format: "json" });
+    return {
+      source: applyPlan.source,
+      sourceType: applyPlan.sourceType,
+      artifactKind: applyPlan.kind,
+      applyPlan,
+      trackerState: {}
+    };
+  }
+
+  if (path.extname(resolvedPath).toLowerCase() === ".json") {
+    const raw = await fs.readFile(resolvedPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const resolved = buildExecutionContextFromParsedArtifact(parsed, resolvedPath);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  const applyPlan = await createApplyPlan(resolvedPath, { format: "json" });
+  return {
+    source: applyPlan.source,
+    sourceType: applyPlan.sourceType,
+    artifactKind: applyPlan.kind,
+    applyPlan,
+    trackerState: {}
+  };
+}
+
+function pickCompletedIds(packets, options, trackerState) {
+  const packetIds = new Set((packets || []).map((packet) => packet.id));
+  const requestedIds =
+    options.completedPacketIds != null ? parseCommaList(options.completedPacketIds) : trackerState.completedPacketIds || [];
+
+  return requestedIds.filter((id) => packetIds.has(id));
+}
+
+function pickCurrentTaskId(packets, completedIds, options, trackerState) {
+  const packetIds = new Set((packets || []).map((packet) => packet.id));
+  const completedSet = new Set(completedIds);
+  const requested = options.currentTaskId || trackerState.currentTaskId;
+  if (requested && packetIds.has(requested) && !completedSet.has(requested)) {
+    return requested;
+  }
+
+  const remaining = (packets || []).filter((packet) => !completedSet.has(packet.id));
+  return remaining[0]?.id || null;
+}
+
+function pickBlockedReasons(options, trackerState) {
+  if (options.blockedReasons != null) {
+    return parseCommaList(options.blockedReasons);
+  }
+  return trackerState.blockedReasons || [];
+}
+
+function inferTrackerStatus(totalPackets, completedCount, blockedReasons) {
+  if (blockedReasons.length > 0) {
+    return "blocked";
+  }
+  if (totalPackets === 0) {
+    return "needs-context";
+  }
+  if (completedCount === 0) {
+    return "not-started";
+  }
+  if (completedCount >= totalPackets) {
+    return "completed";
+  }
+  return "in-progress";
+}
+
+function buildStatusSummary(status, activePacket, nextPacket, blockedReasons) {
+  switch (status) {
+    case "blocked":
+      return `当前已识别到阻塞，先处理这些问题再继续：${blockedReasons.join("；")}`;
+    case "needs-context":
+      return "当前还没有足够的执行包，说明需要先补上下文或重新生成 apply-plan。";
+    case "completed":
+      return "当前批次已全部完成，可以进入 completion-report 与交付收尾。";
+    case "in-progress":
+      return activePacket
+        ? `当前正推进 ${activePacket.id}，完成后继续 ${nextPacket?.id || "进入收尾阶段"}。`
+        : "当前已经开始执行，但还没有明确当前包，请先校准执行顺序。";
+    default:
+      return activePacket
+        ? `当前尚未开始，建议先从 ${activePacket.id} 开始。`
+        : "当前尚未开始，先确认执行包和优先级。";
+  }
+}
+
+function buildSuggestedNextCommand(source, status, activePacket, remainingPackets, blockedReasons) {
+  if (status === "blocked") {
+    if (activePacket) {
+      return `geo-ai-search-optimization agent-runbook ${source} --task ${activePacket.id}`;
+    }
+    return `geo-ai-search-optimization agent-session ${source}`;
+  }
+
+  if (status === "completed") {
+    return `geo-ai-search-optimization completion-report ${source}`;
+  }
+
+  if (activePacket) {
+    return `geo-ai-search-optimization agent-executor ${source} --task ${activePacket.id}`;
+  }
+
+  if (remainingPackets.length > 1) {
+    return `geo-ai-search-optimization agent-batch-executor ${source}`;
+  }
+
+  if (blockedReasons.length > 0) {
+    return `geo-ai-search-optimization agent-session ${source}`;
+  }
+
+  return `geo-ai-search-optimization apply-plan ${source}`;
+}
+
+function buildFollowupCommands(source, status, activePacket, nextPacket, remainingPackets) {
+  if (status === "completed") {
+    return [
+      `geo-ai-search-optimization handoff-bundle ${source}`,
+      `geo-ai-search-optimization publish-pack ${source}`
+    ];
+  }
+
+  const commands = [];
+
+  if (nextPacket) {
+    commands.push(`geo-ai-search-optimization agent-batch-executor ${source} --task ${nextPacket.id}`);
+  } else if (remainingPackets.length > 1) {
+    commands.push(`geo-ai-search-optimization agent-batch-executor ${source}`);
+  }
+
+  if (activePacket) {
+    commands.push(`geo-ai-search-optimization agent-progress-tracker ${source} --current ${activePacket.id}`);
+  }
+
+  commands.push(`geo-ai-search-optimization completion-report ${source}`);
+  commands.push(`geo-ai-search-optimization handoff-bundle ${source}`);
+  return commands;
+}
+
+function buildTrackerPrompt(tracker) {
+  const lines = [
+    "你现在进入 GEO 执行进度追踪模式。",
+    `当前输入：${tracker.source}`,
+    `当前状态：${tracker.status}`,
+    `当前总结：${tracker.statusSummary}`,
+    `总任务包：${tracker.totalPackets}`,
+    `已完成：${tracker.completedCount}`,
+    `剩余：${tracker.remainingCount}`
+  ];
+
+  if (tracker.activePacket) {
+    lines.push(`当前执行包：${tracker.activePacket.id}｜${tracker.activePacket.title}`);
+  }
+  if (tracker.nextPacket) {
+    lines.push(`下一包：${tracker.nextPacket.id}｜${tracker.nextPacket.title}`);
+  }
+  if (tracker.blockedReasons.length > 0) {
+    lines.push(`阻塞原因：${tracker.blockedReasons.join("；")}`);
+  }
+
+  lines.push("请输出：");
+  lines.push("1. 当前已完成到哪");
+  lines.push("2. 当前卡点是什么");
+  lines.push("3. 现在该继续哪一包");
+  lines.push("4. 完成这一包后下一步是什么");
+  return lines.join("\n");
+}
+
+function summarizePacket(packet) {
+  if (!packet) {
+    return null;
+  }
+
+  return {
+    id: packet.id,
+    title: packet.title,
+    owner: packet.owner,
+    priority: packet.priority || "P1",
+    doneWhen: packet.doneWhen || [],
+    validationCommands: packet.validationCommands || []
+  };
+}
+
+export async function createAgentProgressTracker(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const context = await resolveExecutionContext(input);
+  const packets = context.applyPlan?.packets || [];
+  const completedPacketIds = pickCompletedIds(packets, options, context.trackerState);
+  const completedSet = new Set(completedPacketIds);
+  const currentTaskId = pickCurrentTaskId(packets, completedPacketIds, options, context.trackerState);
+  const blockedReasons = pickBlockedReasons(options, context.trackerState);
+  const completedPackets = packets.filter((packet) => completedSet.has(packet.id));
+  const remainingPackets = packets.filter((packet) => !completedSet.has(packet.id));
+  const activePacket = summarizePacket(remainingPackets.find((packet) => packet.id === currentTaskId) || remainingPackets[0]);
+  const nextPacket = summarizePacket(
+    activePacket ? remainingPackets.find((packet) => packet.id !== activePacket.id) : remainingPackets[0]
+  );
+  const totalPackets = packets.length;
+  const completedCount = completedPackets.length;
+  const remainingCount = Math.max(totalPackets - completedCount, 0);
+  const progressPercent = totalPackets > 0 ? Math.round((completedCount / totalPackets) * 100) : 0;
+  const status = inferTrackerStatus(totalPackets, completedCount, blockedReasons);
+  const statusSummary = buildStatusSummary(status, activePacket, nextPacket, blockedReasons);
+  const suggestedNextCommand = buildSuggestedNextCommand(
+    context.source,
+    status,
+    activePacket,
+    remainingPackets,
+    blockedReasons
+  );
+  const followupCommands = buildFollowupCommands(context.source, status, activePacket, nextPacket, remainingPackets);
+
+  const tracker = {
+    kind: "geo-agent-progress-tracker",
+    input,
+    source: context.source,
+    sourceType: context.sourceType,
+    artifactKind: context.artifactKind,
+    format,
+    executionType: context.applyPlan?.executionType || "guided-planning",
+    status,
+    statusSummary,
+    totalPackets,
+    completedCount,
+    remainingCount,
+    progressPercent,
+    currentTaskId: activePacket?.id || null,
+    completedPacketIds,
+    blockedReasons,
+    completedPackets: completedPackets.map(summarizePacket),
+    activePacket,
+    nextPacket,
+    remainingPackets: remainingPackets.map(summarizePacket),
+    suggestedNextCommand,
+    followupCommands,
+    trackerPrompt: "",
+    applyPlan: context.applyPlan
+  };
+
+  tracker.trackerPrompt = buildTrackerPrompt(tracker);
+  return tracker;
+}
+
+export function renderAgentProgressTrackerMarkdown(tracker) {
+  const lines = [
+    "# GEO Agent Progress Tracker",
+    "",
+    `- 输入：\`${tracker.source}\``,
+    `- 来源类型：\`${tracker.sourceType}\``,
+    `- 工件类型：\`${tracker.artifactKind}\``,
+    `- 当前状态：\`${tracker.status}\``,
+    `- 执行类型：\`${tracker.executionType}\``,
+    `- 进度：\`${tracker.progressPercent}%\``,
+    `- 已完成：\`${tracker.completedCount}/${tracker.totalPackets}\``,
+    `- 当前总结：${tracker.statusSummary}`,
+    ""
+  ];
+
+  lines.push("## 已完成任务包", "");
+  if (tracker.completedPackets.length === 0) {
+    lines.push("- 当前还没有标记为已完成的任务包。", "");
+  } else {
+    for (const packet of tracker.completedPackets) {
+      lines.push(`- ${packet.id}｜${packet.title}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 当前任务包", "");
+  if (!tracker.activePacket) {
+    lines.push("- 当前还没有可推进的任务包。", "");
+  } else {
+    lines.push(`- ID：\`${tracker.activePacket.id}\``);
+    lines.push(`- 标题：${tracker.activePacket.title}`);
+    lines.push(`- Owner：${tracker.activePacket.owner}`);
+    lines.push(`- 优先级：${tracker.activePacket.priority}`);
+    lines.push("");
+  }
+
+  lines.push("## 下一包", "");
+  if (!tracker.nextPacket) {
+    lines.push("- 当前没有下一包，完成后可进入收尾。", "");
+  } else {
+    lines.push(`- ID：\`${tracker.nextPacket.id}\``);
+    lines.push(`- 标题：${tracker.nextPacket.title}`);
+    lines.push(`- Owner：${tracker.nextPacket.owner}`);
+    lines.push("");
+  }
+
+  lines.push("## 阻塞项", "");
+  if (tracker.blockedReasons.length === 0) {
+    lines.push("- 当前没有手动标记的阻塞项。", "");
+  } else {
+    for (const reason of tracker.blockedReasons) {
+      lines.push(`- ${reason}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 建议下一步命令", "");
+  lines.push(`- \`${tracker.suggestedNextCommand}\``);
+  lines.push("", "## 后续命令", "");
+  for (const command of tracker.followupCommands) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push("", "## 可直接复制给 Agent 的 Progress Prompt", "", "```text", tracker.trackerPrompt, "```");
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentProgressTrackerOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/agent-session.js

@@ -55,6 +55,9 @@ function inferSkillForCommand(commandName, flow) {
   if (commandName === "agent-batch-executor") {
     return "geo-ai-search-optimization-agent-batch-executor";
   }
+  if (commandName === "agent-progress-tracker") {
+    return "geo-ai-search-optimization-agent-progress-tracker";
+  }
   if (commandName === "skills" || commandName === "quick-start") {
     return "geo-ai-search-optimization-usage";
   }
@@ -121,6 +124,8 @@ function inferStepPurpose(commandName, flow) {
       return "把这一轮先做哪一个任务包压成单任务执行入口。";
     case "agent-batch-executor":
       return "把前几包任务排成连续执行顺序，但保持一次只推进一包。";
+    case "agent-progress-tracker":
+      return "追踪当前做到第几包、卡点在哪里，以及下一包该推进什么。";
     case "apply-plan":
       return "把交接结果推进到具体执行包。";
     case "completion-report":
@@ -167,6 +172,8 @@ function inferExpectedArtifact(commandName) {
       return "agent 单任务执行包";
     case "agent-batch-executor":
       return "agent 多任务批次执行包";
+    case "agent-progress-tracker":
+      return "agent 执行进度追踪工件";
     case "apply-plan":
       return "执行包";
     case "completion-report":
@@ -208,6 +215,9 @@ function buildStepInstructions(parsedCommand, flow) {
   if (parsedCommand.commandName === "agent-batch-executor") {
     lines.push("批次模式下也要一次只做一包，上一包通过验证后再进入下一包。");
   }
+  if (parsedCommand.commandName === "agent-progress-tracker") {
+    lines.push("这一步用于校准当前做到哪、当前卡点和下一包，不要跳过状态确认直接进入收尾。");
+  }
   if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
     lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
   }

package/src/auto-flow.js

@@ -47,6 +47,9 @@ function inferTaskTextMode(text) {
   if (/(batch-executor|batch executor|多包|前3包|批次执行|连续推进前几包)/i.test(normalized)) {
     return "execute";
   }
+  if (/(progress-tracker|progress tracker|进度追踪|做到第几包|卡在哪|下一包是什么)/i.test(normalized)) {
+    return "execute";
+  }
   if (/(executor|先做哪一个|先做哪一包|single task|执行第一包|先执行一个任务)/i.test(normalized)) {
     return "execute";
   }
@@ -165,6 +168,7 @@ function resolveEffectiveIntent(intent, detected) {
       "geo-agent-runbook",
       "geo-agent-executor",
       "geo-agent-batch-executor",
+      "geo-agent-progress-tracker",
       "geo-apply-plan",
       "geo-handoff-bundle",
       "geo-fix-plan"
@@ -257,7 +261,9 @@ function buildCommandChain(detected, intent) {
             `geo-ai-search-optimization agent-handoff ${source}`,
             `geo-ai-search-optimization agent-runbook ${source}`,
             `geo-ai-search-optimization agent-executor ${source}`,
-            `geo-ai-search-optimization apply-plan ${source}`
+            `geo-ai-search-optimization apply-plan ${source}`,
+            `geo-ai-search-optimization agent-batch-executor ${source}`,
+            `geo-ai-search-optimization agent-progress-tracker ${source}`
           ]
         : [`geo-ai-search-optimization fix-plan ${source}`, `geo-ai-search-optimization owner-board ${source}`];
     case "geo-url-onboarding":
@@ -272,6 +278,7 @@ function buildCommandChain(detected, intent) {
         `geo-ai-search-optimization agent-runbook ${source}`,
         `geo-ai-search-optimization agent-executor ${source}`,
         `geo-ai-search-optimization agent-batch-executor ${source}`,
+        `geo-ai-search-optimization agent-progress-tracker ${source}`,
         `geo-ai-search-optimization completion-report ${source}`
       ];
     case "geo-agent-handoff":
@@ -279,31 +286,54 @@ function buildCommandChain(detected, intent) {
         `geo-ai-search-optimization agent-runbook ${source}`,
         `geo-ai-search-optimization agent-executor ${source}`,
         `geo-ai-search-optimization agent-batch-executor ${source}`,
+        `geo-ai-search-optimization agent-progress-tracker ${source}`,
         `geo-ai-search-optimization completion-report ${source}`
       ];
     case "geo-agent-runbook":
       return [
         `geo-ai-search-optimization agent-executor ${source}`,
         `geo-ai-search-optimization agent-batch-executor ${source}`,
+        `geo-ai-search-optimization agent-progress-tracker ${source}`,
         `geo-ai-search-optimization completion-report ${source}`,
         `geo-ai-search-optimization handoff-bundle ${source}`
       ];
     case "geo-agent-executor":
       return [
+        `geo-ai-search-optimization agent-progress-tracker ${source}`,
         `geo-ai-search-optimization completion-report ${source}`,
         `geo-ai-search-optimization handoff-bundle ${source}`,
         `geo-ai-search-optimization publish-pack ${source}`
       ];
     case "geo-agent-batch-executor":
       return [
+        `geo-ai-search-optimization agent-progress-tracker ${source}`,
         `geo-ai-search-optimization completion-report ${source}`,
         `geo-ai-search-optimization handoff-bundle ${source}`,
         `geo-ai-search-optimization publish-pack ${source}`
       ];
+    case "geo-agent-progress-tracker":
+      return detected.parsed?.status === "completed"
+        ? [
+            `geo-ai-search-optimization completion-report ${source}`,
+            `geo-ai-search-optimization handoff-bundle ${source}`,
+            `geo-ai-search-optimization publish-pack ${source}`
+          ]
+        : detected.parsed?.currentTaskId
+          ? [
+              `geo-ai-search-optimization agent-executor ${source} --task ${detected.parsed.currentTaskId}`,
+              `geo-ai-search-optimization completion-report ${source}`,
+              `geo-ai-search-optimization handoff-bundle ${source}`
+            ]
+          : [
+              `geo-ai-search-optimization agent-batch-executor ${source}`,
+              `geo-ai-search-optimization completion-report ${source}`,
+              `geo-ai-search-optimization handoff-bundle ${source}`
+            ];
     case "geo-apply-plan":
       return [
         `geo-ai-search-optimization agent-executor ${source}`,
         `geo-ai-search-optimization agent-batch-executor ${source}`,
+        `geo-ai-search-optimization agent-progress-tracker ${source}`,
         `geo-ai-search-optimization completion-report ${source}`,
         `geo-ai-search-optimization handoff-bundle ${source}`
       ];
@@ -374,6 +404,8 @@ function pickSkillName(detected, intent) {
       return "geo-ai-search-optimization-agent-executor";
     case "geo-agent-batch-executor":
       return "geo-ai-search-optimization-agent-batch-executor";
+    case "geo-agent-progress-tracker":
+      return "geo-ai-search-optimization-agent-progress-tracker";
     case "geo-completion-report":
       return "geo-ai-search-optimization-completion-report";
     case "geo-handoff-bundle":
@@ -411,12 +443,14 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
       "geo-agent-runbook",
       "geo-agent-executor",
       "geo-agent-batch-executor",
+      "geo-agent-progress-tracker",
       "geo-apply-plan"
     ].includes(
       detected.artifactKind
     )
   ) {
     names.add("geo-ai-search-optimization-agent-batch-executor");
+    names.add("geo-ai-search-optimization-agent-progress-tracker");
     names.add("geo-ai-search-optimization-agent-executor");
     names.add("geo-ai-search-optimization-agent-runbook");
     names.add("geo-ai-search-optimization-agent-handoff");
@@ -447,6 +481,7 @@ function buildStage(intent, detected) {
       "geo-agent-runbook",
       "geo-agent-executor",
       "geo-agent-batch-executor",
+      "geo-agent-progress-tracker",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -460,6 +495,7 @@ function buildStage(intent, detected) {
       "geo-agent-runbook",
       "geo-agent-executor",
       "geo-agent-batch-executor",
+      "geo-agent-progress-tracker",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -546,6 +582,9 @@ function buildNextAction(detected, intent, commands) {
     return `先运行 \`${commands[0]}\` 生成适合外发或交接的结果。`;
   }
   if (intent === "execute") {
+    if (detected.artifactKind === "geo-agent-progress-tracker") {
+      return `先运行 \`${commands[0]}\`，继续当前执行包或校准下一包。`;
+    }
     return `先运行 \`${commands[0]}\`，把当前输入推进到 agent 可执行状态。`;
   }
   if (intent === "closeout") {

package/src/cli.js

@@ -9,6 +9,11 @@ import {
 } from "./agent-batch-executor.js";
 import { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
 import { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
+import {
+  createAgentProgressTracker,
+  renderAgentProgressTrackerMarkdown,
+  writeAgentProgressTrackerOutput
+} from "./agent-progress-tracker.js";
 import { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
 import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 import { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./auto-flow.js";
@@ -71,6 +76,7 @@ function printHelp() {
       "  geo-ai-search-optimization agent-runbook <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization agent-executor <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization agent-batch-executor <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--task <id>] [--count <count>] [--format <markdown|json>] [--out <file>]",
+      "  geo-ai-search-optimization agent-progress-tracker <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -269,6 +275,34 @@ async function handleAgentBatchExecutor(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentProgressTracker(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-progress-tracker 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+  const tracker = await createAgentProgressTracker(input, {
+    format,
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  const outputJson = tracker.format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(tracker, null, 2)}\n`
+    : renderAgentProgressTrackerMarkdown(tracker);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentProgressTrackerOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent progress tracker：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 function handleWhere() {
   process.stdout.write(
     [
@@ -834,6 +868,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-progress-tracker") {
+    await handleAgentProgressTracker(rest);
+    return;
+  }
+
   if (command === "skills") {
     await handleSkills(rest);
     return;

package/src/index.js

@@ -10,6 +10,11 @@ export { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "
 export { createAgentBatchExecutor, renderAgentBatchExecutorMarkdown, writeAgentBatchExecutorOutput } from "./agent-batch-executor.js";
 export { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
 export { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
+export {
+  createAgentProgressTracker,
+  renderAgentProgressTrackerMarkdown,
+  writeAgentProgressTrackerOutput
+} from "./agent-progress-tracker.js";
 export { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
 export { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 export { createCompletionReport, renderCompletionReportMarkdown, writeCompletionReportOutput } from "./completion-report.js";

package/src/skills.js

@@ -9,6 +9,7 @@ const SKILL_ORDER = [
   "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",
@@ -27,6 +28,7 @@ const SKILL_CATEGORY = {
   "geo-ai-search-optimization-agent-runbook": "execution",
   "geo-ai-search-optimization-agent-executor": "execution",
   "geo-ai-search-optimization-agent-batch-executor": "execution",
+  "geo-ai-search-optimization-agent-progress-tracker": "execution",
   "geo-ai-search-optimization-usage": "guidance",
   "geo-ai-search-optimization-agent-handoff": "execution",
   "geo-ai-search-optimization-repair-loop": "execution",
@@ -164,6 +166,7 @@ export function renderBundledSkillsMarkdown(bundle) {
     "- 如果要给 agent 一份执行手册和检查表，再进入 agent-runbook。",
     "- 如果要直接告诉 agent 这轮先做哪 1 包，再进入 agent-executor。",
     "- 如果要连续推进前 2 到 3 包，但仍然一次只做一包，再进入 agent-batch-executor。",
+    "- 如果要追踪目前做到第几包、卡在哪、下一包是什么，再进入 agent-progress-tracker。",
     "- 再看 usage skill，知道什么时候该跑哪个命令。",
     "- 如果要交给 agent 执行，再进入 handoff / apply / completion 这一条执行链。",
     "- 如果要产出给团队分发，再进入 share / export / html / publish 这一条交付链。",