geo-ai-search-optimization 1.2.11 → 1.2.13

package/src/agent-progress-tracker.js

@@ -0,0 +1,496 @@
+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-agent-status-board" && parsed.tracker?.applyPlan?.kind === "geo-apply-plan") {
+    return {
+      source: parsed.source || parsed.tracker.source || parsed.tracker.applyPlan.source || input,
+      sourceType: parsed.sourceType || parsed.tracker.sourceType || parsed.tracker.applyPlan.sourceType || "json",
+      artifactKind: parsed.kind,
+      applyPlan: parsed.tracker.applyPlan,
+      trackerState: {
+        currentTaskId: parsed.tracker.currentTaskId || parsed.tracker.activePacket?.id || null,
+        completedPacketIds: parsed.tracker.completedPacketIds || [],
+        blockedReasons: parsed.tracker.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,12 @@ 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 === "agent-status-board") {
+    return "geo-ai-search-optimization-agent-status-board";
+  }
   if (commandName === "skills" || commandName === "quick-start") {
     return "geo-ai-search-optimization-usage";
   }
@@ -121,6 +127,10 @@ function inferStepPurpose(commandName, flow) {
       return "把这一轮先做哪一个任务包压成单任务执行入口。";
     case "agent-batch-executor":
       return "把前几包任务排成连续执行顺序，但保持一次只推进一包。";
+    case "agent-progress-tracker":
+      return "追踪当前做到第几包、卡点在哪里，以及下一包该推进什么。";
+    case "agent-status-board":
+      return "把当前执行状态整理成 PM 和 agent 都能直接消费的分栏看板。";
     case "apply-plan":
       return "把交接结果推进到具体执行包。";
     case "completion-report":
@@ -167,6 +177,10 @@ function inferExpectedArtifact(commandName) {
       return "agent 单任务执行包";
     case "agent-batch-executor":
       return "agent 多任务批次执行包";
+    case "agent-progress-tracker":
+      return "agent 执行进度追踪工件";
+    case "agent-status-board":
+      return "agent 执行状态看板";
     case "apply-plan":
       return "执行包";
     case "completion-report":
@@ -208,6 +222,12 @@ function buildStepInstructions(parsedCommand, flow) {
   if (parsedCommand.commandName === "agent-batch-executor") {
     lines.push("批次模式下也要一次只做一包，上一包通过验证后再进入下一包。");
   }
+  if (parsedCommand.commandName === "agent-progress-tracker") {
+    lines.push("这一步用于校准当前做到哪、当前卡点和下一包，不要跳过状态确认直接进入收尾。");
+  }
+  if (parsedCommand.commandName === "agent-status-board") {
+    lines.push("这一步用于把当前执行状态转成看板视图，方便 PM 和 agent 对齐当前阶段。");
+  }
   if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
     lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
   }