geo-ai-search-optimization 1.2.15 → 1.2.16

package/README.md

@@ -226,6 +226,26 @@ geo-ai-search-optimization agent-decision-log ./your-site --append-from ./report
 - 最新建议下一步命令
 - 可直接复制给 agent 的 decision log prompt
 
+## Agent Retrospective 命令
+
+如果你希望不只是看多轮决策历史，而是直接总结“为什么这几轮顺利 / 为什么总卡住”，可以直接用 `agent-retrospective`：
+
+```bash
+geo-ai-search-optimization agent-retrospective ./your-site
+geo-ai-search-optimization agent-retrospective ./reports/agent-decision-log.json
+geo-ai-search-optimization agent-retrospective ./reports/agent-decision-log.json --format json --out ./reports/agent-retrospective.json
+```
+
+`agent-retrospective` 会输出：
+
+- 当前复盘状态
+- 重复阻塞与重复任务包
+- 关键学习
+- 下一轮建议
+- 决策分布
+- 多轮时间线
+- 可直接复制给 agent 的 retrospective prompt
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -628,6 +648,7 @@ geo-ai-search-optimization agent-progress-tracker ./your-site
 geo-ai-search-optimization agent-status-board ./your-site
 geo-ai-search-optimization agent-checkpoint ./your-site
 geo-ai-search-optimization agent-decision-log ./your-site
+geo-ai-search-optimization agent-retrospective ./your-site
 geo-ai-search-optimization skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -698,6 +719,13 @@ geo-ai-search-optimization help
 - 输出 do-now checklist、stop checklist、success checklist、验证命令和回报模板
 - 新增 `geo-ai-search-optimization-agent-executor` skill
 
+## New in 1.2.16
+
+- 新增 `agent-retrospective` 命令
+- 把多轮 decision log 压成复盘视图，识别重复阻塞、重复任务包和反复出现的决策模式
+- 支持从 `agent-decision-log`、`agent-checkpoint`、目录、网址等输入继续生成 retrospective
+- 新增 `geo-ai-search-optimization-agent-retrospective` skill
+
 ## New in 1.2.15
 
 - 新增 `agent-decision-log` 命令
@@ -928,6 +956,7 @@ The installed package now includes a bundled GEO skill pack, including:
 - `geo-ai-search-optimization-agent-status-board`
 - `geo-ai-search-optimization-agent-checkpoint`
 - `geo-ai-search-optimization-agent-decision-log`
+- `geo-ai-search-optimization-agent-retrospective`
 - `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.15",
+  "version": "1.2.16",
   "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

@@ -112,6 +112,16 @@ Best for:
 - giving PM and the next agent a reusable decision history across rounds
 - appending a fresh checkpoint onto an existing GEO execution history
 
+### `geo-ai-search-optimization-agent-retrospective`
+
+Use this when the next agent or PM should understand the pattern across several rounds, not just inherit the last decision.
+
+Best for:
+
+- explaining why the same blocker or packet kept recurring
+- turning decision history into lessons learned and next-round advice
+- producing a cross-round retrospective before meetings, closeout, or final delivery
+
 ## Usage guide
 
 ### `geo-ai-search-optimization-usage`

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

@@ -0,0 +1,23 @@
+---
+name: geo-ai-search-optimization-agent-retrospective
+description: Turn GEO decision history into a multi-round retrospective. Use when an agent or PM should understand why prior GEO rounds kept advancing, stalled on blockers, or reached closeout, and needs recurring patterns, lessons learned, and next-round guidance instead of a single checkpoint.
+---
+
+# GEO Agent Retrospective
+
+Use this skill when one checkpoint or one decision log is not enough, and the team needs to understand the pattern across rounds.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- reads GEO decision history across multiple rounds
+- highlights recurring blockers, repeated packets, and repeated decisions
+- explains what changed from round to round
+- turns history into lessons learned and next-round advice
+
+## Best use
+
+- when PM asks why the team keeps getting blocked in the same place
+- when the next agent should inherit not only the latest decision, but the pattern behind it
+- when the team wants a reusable retrospective before closeout, meetings, or final delivery

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Retrospective"
+  short_description: "Summarize cross-round GEO patterns and lessons"
+  default_prompt: "Use $geo-ai-search-optimization-agent-retrospective to turn this GEO decision history into a multi-round retrospective with recurring patterns, lessons learned, and next-round guidance."

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

@@ -13,7 +13,7 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as twenty-two layers:
+The package is best explained as twenty-three layers:
 
 1. `auto-flow`: auto-select the next skill and command chain
 2. `agent-session`: build a runnable session for the next agent
@@ -24,19 +24,20 @@ The package is best explained as twenty-two layers:
 7. `agent-status-board`: turn the execution state into a board view for PM and agents
 8. `agent-checkpoint`: freeze the current round into a continue / unblock / closeout decision
 9. `agent-decision-log`: preserve why each round continued, paused, or closed out
-10. `skills`: inspect the bundled skill package
-11. `onboard-url` / `onboard`: first look
-12. `scan`: raw signal check
-13. `audit` / `report`: diagnosis
-14. `fix-plan` / `owner-board`: execution planning
-15. `agent-handoff`: agent takeover package
-16. `apply-plan`: execution loop
-17. `completion-report`: closeout
-18. `handoff-bundle`: all-in-one package
-19. `share-pack`: audience-ready delivery
-20. `export-pack`: folder export
-21. `html-pack` / `publish-pack`: browsable and final delivery output
-22. `pm-brief` / `roadmap`: stakeholder alignment
+10. `agent-retrospective`: explain multi-round patterns, lessons, and next-round advice
+11. `skills`: inspect the bundled skill package
+12. `onboard-url` / `onboard`: first look
+13. `scan`: raw signal check
+14. `audit` / `report`: diagnosis
+15. `fix-plan` / `owner-board`: execution planning
+16. `agent-handoff`: agent takeover package
+17. `apply-plan`: execution loop
+18. `completion-report`: closeout
+19. `handoff-bundle`: all-in-one package
+20. `share-pack`: audience-ready delivery
+21. `export-pack`: folder export
+22. `html-pack` / `publish-pack`: browsable and final delivery output
+23. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -52,6 +53,7 @@ npx geo-ai-search-optimization agent-progress-tracker https://example.com
 npx geo-ai-search-optimization agent-status-board https://example.com
 npx geo-ai-search-optimization agent-checkpoint https://example.com
 npx geo-ai-search-optimization agent-decision-log https://example.com
+npx geo-ai-search-optimization agent-retrospective 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
@@ -69,6 +71,7 @@ npx geo-ai-search-optimization agent-progress-tracker ./your-site
 npx geo-ai-search-optimization agent-status-board ./your-site
 npx geo-ai-search-optimization agent-checkpoint ./your-site
 npx geo-ai-search-optimization agent-decision-log ./your-site
+npx geo-ai-search-optimization agent-retrospective ./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
@@ -95,6 +98,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `agent-status-board`: present the current execution state as a board with done, in-progress, blocked, next, and queued columns
 - `agent-checkpoint`: convert the current round into a checkpoint decision for continue, unblock, or closeout
 - `agent-decision-log`: preserve multiple rounds of checkpoint history so the next agent can inherit the reasoning
+- `agent-retrospective`: explain why the last few rounds advanced or stalled, and turn that into lessons and next-round guidance
 - `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
@@ -128,6 +132,7 @@ When explaining the tool to a user:
 - if the user wants the next agent to present execution state as a board for PM and agent coordination, move them to `agent-status-board`
 - if the user wants a per-round decision artifact that says continue, unblock, or close out, move them to `agent-checkpoint`
 - if the user wants cross-round decision memory and not just one checkpoint, move them to `agent-decision-log`
+- if the user wants to understand why multiple rounds kept advancing or getting stuck, move them to `agent-retrospective`
 - 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-retrospective.js

@@ -0,0 +1,452 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createAgentDecisionLog } from "./agent-decision-log.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-retrospective 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function cloneForFormat(record, format) {
+  return {
+    ...record,
+    format
+  };
+}
+
+function incrementMapCount(map, key) {
+  if (!key) {
+    return;
+  }
+  map.set(key, (map.get(key) || 0) + 1);
+}
+
+function toSortedFrequencyList(map, formatter) {
+  return [...map.entries()]
+    .sort((left, right) => right[1] - left[1] || String(left[0]).localeCompare(String(right[0])))
+    .map(([key, count]) => formatter(key, count));
+}
+
+async function resolveDecisionLog(input, options = {}) {
+  const resolvedInput = path.resolve(input);
+  if (await pathExists(resolvedInput)) {
+    try {
+      const raw = await fs.readFile(resolvedInput, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.kind === "geo-agent-retrospective" && !options.forceRefresh) {
+        return {
+          retrospective: cloneForFormat(parsed, normalizeFormat(options.format)),
+          decisionLog: parsed.decisionLog || null
+        };
+      }
+      if (parsed?.kind === "geo-agent-decision-log") {
+        return {
+          retrospective: null,
+          decisionLog: parsed
+        };
+      }
+    } catch {
+      // Fall through to log generation.
+    }
+  }
+
+  return {
+    retrospective: null,
+    decisionLog: await createAgentDecisionLog(input, { format: "json" })
+  };
+}
+
+function analyzeProgressTrend(entries) {
+  if (entries.length === 0) {
+    return {
+      progressDelta: 0,
+      firstProgress: 0,
+      latestProgress: 0
+    };
+  }
+
+  return {
+    progressDelta: (entries.at(-1)?.progressPercent || 0) - (entries[0]?.progressPercent || 0),
+    firstProgress: entries[0]?.progressPercent || 0,
+    latestProgress: entries.at(-1)?.progressPercent || 0
+  };
+}
+
+function inferRetrospectiveStatus(log, blockerFrequency, decisionCounts, progressTrend) {
+  if (log.latestDecision === "move-to-closeout") {
+    return "ready-for-closeout";
+  }
+  if (
+    log.latestDecision === "resolve-blockers" &&
+    blockerFrequency.length > 0 &&
+    blockerFrequency[0].count >= 2
+  ) {
+    return "repeated-blocker";
+  }
+  if (log.latestDecision === "resolve-blockers") {
+    return "blocked-this-round";
+  }
+  if ((decisionCounts["start-first-packet"] || 0) >= 2) {
+    return "restarting-too-often";
+  }
+  if (progressTrend.progressDelta > 0) {
+    return "advancing";
+  }
+  if (log.totalEntries <= 1) {
+    return "early-cycle";
+  }
+  return "stable-but-flat";
+}
+
+function buildKeyLearnings(log, blockerFrequency, packetFrequency, decisionCounts, progressTrend) {
+  const learnings = [];
+
+  if (blockerFrequency[0]?.count >= 2) {
+    learnings.push(`阻塞「${blockerFrequency[0].title}」重复出现 ${blockerFrequency[0].count} 次，说明进入执行前的上下文准备还不够稳定。`);
+  }
+  if ((decisionCounts["start-first-packet"] || 0) >= 2) {
+    learnings.push("多轮都回到 start-first-packet，说明执行连续性不足，团队还在反复重启。");
+  }
+  if (packetFrequency[0]?.count >= 2) {
+    learnings.push(`当前包 ${packetFrequency[0].id} 在多轮里重复出现，说明这一包是整条链最容易卡住的地方。`);
+  }
+  if (progressTrend.progressDelta > 0) {
+    learnings.push(`整体进度从 ${progressTrend.firstProgress}% 提升到 ${progressTrend.latestProgress}%，说明执行链并非停滞，而是在缓慢推进。`);
+  }
+  if (log.latestDecision === "move-to-closeout") {
+    learnings.push("最新决策已经进入 closeout，下一步重点不是再开新包，而是整理复盘与交付。");
+  }
+  if (log.latestDecision === "resolve-blockers" && blockerFrequency[0]?.count === 1) {
+    learnings.push("当前阻塞是本轮新出现的问题，适合先快速排除，再继续当前包。");
+  }
+
+  if (learnings.length === 0) {
+    learnings.push("当前决策链整体稳定，但还没有足够多的轮次来识别更强的模式。");
+  }
+
+  return learnings;
+}
+
+function buildRepeatedPatterns(blockerFrequency, packetFrequency, decisionCounts) {
+  const patterns = [];
+
+  if (blockerFrequency[0] && blockerFrequency[0].count >= 2) {
+    patterns.push({
+      type: "blocker",
+      label: `重复阻塞：${blockerFrequency[0].title}`,
+      count: blockerFrequency[0].count
+    });
+  }
+  if (packetFrequency[0] && packetFrequency[0].count >= 2) {
+    patterns.push({
+      type: "packet",
+      label: `反复卡在同一包：${packetFrequency[0].id}｜${packetFrequency[0].title}`,
+      count: packetFrequency[0].count
+    });
+  }
+  for (const [decision, count] of Object.entries(decisionCounts)) {
+    if (count >= 2) {
+      patterns.push({
+        type: "decision",
+        label: `重复决策：${decision}`,
+        count
+      });
+    }
+  }
+
+  return patterns.sort((left, right) => right.count - left.count || left.label.localeCompare(right.label));
+}
+
+function buildNextRoundAdvice(log, status, blockerFrequency) {
+  const advice = [];
+
+  if (status === "repeated-blocker") {
+    advice.push("下一轮不要先做页面修改，先把重复出现的阻塞前置清掉。");
+    advice.push("把权限、模板、数据源或生成链问题单独列成 preflight checklist。");
+  } else if (status === "blocked-this-round") {
+    advice.push("这一轮先解除当前阻塞，再回到当前包继续推进。");
+  } else if (status === "ready-for-closeout") {
+    advice.push("下一轮不需要再开新执行包，应直接整理 closeout、meeting pack 和交付包。");
+  } else if (status === "restarting-too-often") {
+    advice.push("下一轮要保持执行连续性，不要再从第一包重新开始。");
+    advice.push("优先沿着最近一次 current packet 继续，而不是重新生成新的执行队列。");
+  } else if (status === "advancing") {
+    advice.push("执行链在推进，下一轮重点是保留当前节奏并继续当前包。");
+  } else {
+    advice.push("下一轮先延续最近一次决策，不要同时改变执行顺序和目标。");
+  }
+
+  if (blockerFrequency[0]?.count >= 2) {
+    advice.push(`把「${blockerFrequency[0].title}」变成固定的进入执行前检查项，避免下一轮再次卡住。`);
+  }
+
+  if (log.currentPacket) {
+    advice.push(`当前最优先仍是 ${log.currentPacket.id}｜${log.currentPacket.title}`);
+  }
+
+  return advice;
+}
+
+function buildSuggestedNextCommand(log, status) {
+  if (status === "ready-for-closeout") {
+    return `geo-ai-search-optimization completion-report ${log.source}`;
+  }
+  if (status === "repeated-blocker" || status === "blocked-this-round") {
+    return log.suggestedNextCommand || `geo-ai-search-optimization agent-runbook ${log.source}`;
+  }
+  if (log.latestDecision === "start-first-packet" || log.latestDecision === "continue-current-packet") {
+    return log.suggestedNextCommand || `geo-ai-search-optimization agent-executor ${log.source}`;
+  }
+  return `geo-ai-search-optimization agent-decision-log ${log.source}`;
+}
+
+function buildFollowupCommands(log, status) {
+  if (status === "ready-for-closeout") {
+    return [
+      `geo-ai-search-optimization completion-report ${log.source}`,
+      `geo-ai-search-optimization meeting-pack ${log.source}`,
+      `geo-ai-search-optimization publish-pack ${log.source}`
+    ];
+  }
+
+  return [
+    buildSuggestedNextCommand(log, status),
+    `geo-ai-search-optimization agent-status-board ${log.source}`,
+    `geo-ai-search-optimization agent-decision-log ${log.source}`
+  ].filter(Boolean);
+}
+
+function buildRoundNarrative(entries) {
+  return entries.map((entry, index) => {
+    const previous = entries[index - 1];
+    let whatChanged = "这是目前的起始轮次。";
+
+    if (previous) {
+      if (previous.decision !== entry.decision) {
+        whatChanged = `决策从 ${previous.decision} 切换到 ${entry.decision}。`;
+      } else if ((previous.progressPercent || 0) !== (entry.progressPercent || 0)) {
+        whatChanged = `进度从 ${previous.progressPercent || 0}% 变化到 ${entry.progressPercent || 0}%。`;
+      } else if ((previous.blockedItems?.length || 0) !== (entry.blockedItems?.length || 0)) {
+        whatChanged = `阻塞数从 ${previous.blockedItems?.length || 0} 变化到 ${entry.blockedItems?.length || 0}。`;
+      } else {
+        whatChanged = "当前轮次延续了上一轮的总体判断。";
+      }
+    }
+
+    return {
+      id: entry.id,
+      createdAt: entry.createdAt,
+      decision: entry.decision,
+      checkpointType: entry.checkpointType,
+      currentPacket: entry.currentPacket,
+      note: entry.note,
+      whatChanged,
+      decisionReason: entry.decisionReason
+    };
+  });
+}
+
+function buildRetrospectivePrompt(report) {
+  const lines = [
+    "你现在进入 GEO 多轮复盘模式。",
+    `当前输入：${report.source}`,
+    `轮次数：${report.totalRounds}`,
+    `当前复盘状态：${report.retrospectiveStatus}`,
+    `最新决策：${report.latestDecision}`,
+    `复盘结论：${report.retrospectiveSummary}`
+  ];
+
+  if (report.recurringBlockers.length > 0) {
+    lines.push(`重复阻塞：${report.recurringBlockers.map((item) => `${item.title} (${item.count})`).join("；")}`);
+  }
+  if (report.currentPacket) {
+    lines.push(`当前包：${report.currentPacket.id}｜${report.currentPacket.title}`);
+  }
+
+  lines.push("请先解释这几轮里发生了什么变化，再给出下一轮最该避免的错误和最该保留的节奏。");
+  lines.push("最后输出建议下一步命令，以及对 PM 和下一位 agent 的简短建议。");
+  return lines.join("\n");
+}
+
+export async function createAgentRetrospective(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const { retrospective, decisionLog } = await resolveDecisionLog(input, { ...options, format });
+
+  if (retrospective) {
+    return retrospective;
+  }
+
+  if (!decisionLog) {
+    throw new Error("无法从当前输入生成 decision log，因此不能创建 retrospective。");
+  }
+
+  const entries = decisionLog.entries || [];
+  const decisionCounts = entries.reduce((accumulator, entry) => {
+    accumulator[entry.decision] = (accumulator[entry.decision] || 0) + 1;
+    return accumulator;
+  }, {});
+
+  const blockerMap = new Map();
+  const packetMap = new Map();
+
+  for (const entry of entries) {
+    for (const blocker of entry.blockedItems || []) {
+      incrementMapCount(blockerMap, blocker.title);
+    }
+    if (entry.currentPacket?.id) {
+      incrementMapCount(packetMap, `${entry.currentPacket.id}|||${entry.currentPacket.title}`);
+    }
+  }
+
+  const recurringBlockers = toSortedFrequencyList(blockerMap, (title, count) => ({
+    title,
+    count
+  }));
+  const repeatedPackets = toSortedFrequencyList(packetMap, (packedValue, count) => {
+    const [id, title] = String(packedValue).split("|||");
+    return { id, title, count };
+  });
+  const progressTrend = analyzeProgressTrend(entries);
+  const retrospectiveStatus = inferRetrospectiveStatus(decisionLog, recurringBlockers, decisionCounts, progressTrend);
+  const keyLearnings = buildKeyLearnings(decisionLog, recurringBlockers, repeatedPackets, decisionCounts, progressTrend);
+  const repeatedPatterns = buildRepeatedPatterns(recurringBlockers, repeatedPackets, decisionCounts);
+  const nextRoundAdvice = buildNextRoundAdvice(decisionLog, retrospectiveStatus, recurringBlockers);
+  const followupCommands = buildFollowupCommands(decisionLog, retrospectiveStatus);
+
+  const report = {
+    kind: "geo-agent-retrospective",
+    input,
+    source: decisionLog.source,
+    sourceType: decisionLog.sourceType,
+    artifactKind: decisionLog.kind,
+    format,
+    totalRounds: decisionLog.totalEntries,
+    retrospectiveStatus,
+    latestDecision: decisionLog.latestDecision,
+    latestDecisionReason: decisionLog.latestDecisionReason,
+    latestCheckpointType: decisionLog.latestCheckpointType,
+    currentPacket: decisionLog.currentPacket,
+    nextPacket: decisionLog.nextPacket,
+    progressTrend,
+    decisionCounts,
+    recurringBlockers,
+    repeatedPackets,
+    repeatedPatterns,
+    retrospectiveSummary: `${decisionLog.logSummary} 当前更适合：${nextRoundAdvice[0]}`,
+    keyLearnings,
+    nextRoundAdvice,
+    suggestedNextCommand: buildSuggestedNextCommand(decisionLog, retrospectiveStatus),
+    followupCommands,
+    roundNarrative: buildRoundNarrative(entries),
+    decisionLog,
+    retrospectivePrompt: ""
+  };
+
+  report.retrospectivePrompt = buildRetrospectivePrompt(report);
+  return report;
+}
+
+export function renderAgentRetrospectiveMarkdown(report) {
+  const lines = [
+    "# GEO Agent Retrospective",
+    "",
+    `- 输入：\`${report.source}\``,
+    `- 来源类型：\`${report.sourceType}\``,
+    `- 决策工件：\`${report.artifactKind}\``,
+    `- 轮次数：\`${report.totalRounds}\``,
+    `- 当前复盘状态：\`${report.retrospectiveStatus}\``,
+    `- 最新决策：\`${report.latestDecision}\``,
+    `- 最新检查点类型：\`${report.latestCheckpointType}\``,
+    `- 复盘总结：${report.retrospectiveSummary}`,
+    ""
+  ];
+
+  if (report.currentPacket) {
+    lines.push("## 当前包", "", `- ${report.currentPacket.id}｜${report.currentPacket.title}`);
+    lines.push(`- Owner：${report.currentPacket.owner}`);
+    lines.push(`- 优先级：${report.currentPacket.priority}`);
+    lines.push("");
+  }
+
+  if (report.nextPacket) {
+    lines.push("## 下一包", "", `- ${report.nextPacket.id}｜${report.nextPacket.title}`);
+    lines.push(`- Owner：${report.nextPacket.owner}`);
+    lines.push(`- 优先级：${report.nextPacket.priority}`);
+    lines.push("");
+  }
+
+  lines.push("## 重复模式", "");
+  if (report.repeatedPatterns.length === 0) {
+    lines.push("- 当前还没有明显重复模式。", "");
+  } else {
+    for (const pattern of report.repeatedPatterns) {
+      lines.push(`- ${pattern.label}｜出现 ${pattern.count} 次`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 关键学习", "");
+  for (const item of report.keyLearnings) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 下一轮建议", "");
+  for (const item of report.nextRoundAdvice) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 决策分布", "");
+  for (const [decision, count] of Object.entries(report.decisionCounts)) {
+    lines.push(`- ${decision}：${count} 次`);
+  }
+
+  lines.push("", "## 轮次时间线", "");
+  for (const round of report.roundNarrative) {
+    lines.push(`### ${round.id}`);
+    lines.push("");
+    lines.push(`- 时间：\`${round.createdAt}\``);
+    lines.push(`- 决策：\`${round.decision}\``);
+    lines.push(`- 检查点类型：\`${round.checkpointType}\``);
+    lines.push(`- 原因：${round.decisionReason}`);
+    lines.push(`- 变化：${round.whatChanged}`);
+    if (round.currentPacket) {
+      lines.push(`- 当前包：${round.currentPacket.id}｜${round.currentPacket.title}`);
+    }
+    if (round.note) {
+      lines.push(`- 备注：${round.note}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 建议下一步命令", "", `- \`${report.suggestedNextCommand}\``);
+
+  if (report.followupCommands.length > 0) {
+    lines.push("", "## 后续命令", "");
+    for (const command of report.followupCommands) {
+      lines.push(`- \`${command}\``);
+    }
+  }
+
+  lines.push("", "## 可直接复制给 Agent 的 Retrospective Prompt", "", "```text", report.retrospectivePrompt, "```");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentRetrospectiveOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/agent-session.js

@@ -67,6 +67,9 @@ function inferSkillForCommand(commandName, flow) {
   if (commandName === "agent-decision-log") {
     return "geo-ai-search-optimization-agent-decision-log";
   }
+  if (commandName === "agent-retrospective") {
+    return "geo-ai-search-optimization-agent-retrospective";
+  }
   if (commandName === "skills" || commandName === "quick-start") {
     return "geo-ai-search-optimization-usage";
   }
@@ -141,6 +144,8 @@ function inferStepPurpose(commandName, flow) {
       return "把当前阶段压成继续 / 阻塞 / 收尾的决策检查点。";
     case "agent-decision-log":
       return "把每一轮 checkpoint 沉淀成可继承的决策历史。";
+    case "agent-retrospective":
+      return "把多轮决策历史压成复盘结论、重复模式和下一轮建议。";
     case "apply-plan":
       return "把交接结果推进到具体执行包。";
     case "completion-report":
@@ -195,6 +200,8 @@ function inferExpectedArtifact(commandName) {
       return "agent 阶段检查点工件";
     case "agent-decision-log":
       return "agent 决策历史工件";
+    case "agent-retrospective":
+      return "agent 多轮复盘工件";
     case "apply-plan":
       return "执行包";
     case "completion-report":
@@ -248,6 +255,9 @@ function buildStepInstructions(parsedCommand, flow) {
   if (parsedCommand.commandName === "agent-decision-log") {
     lines.push("这一步用于保留跨轮决策历史，方便下一位 agent 直接承接上一次判断。");
   }
+  if (parsedCommand.commandName === "agent-retrospective") {
+    lines.push("这一步用于总结为什么前几轮卡住或推进顺利，并把这些模式转成下一轮建议。");
+  }
   if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
     lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
   }

package/src/auto-flow.js

@@ -59,6 +59,9 @@ function inferTaskTextMode(text) {
   if (/(decision-log|decision log|决策历史|决策日志|为什么这样决定|历史决策)/i.test(normalized)) {
     return "execute";
   }
+  if (/(retrospective|retro|多轮复盘|执行复盘|为什么总卡住|经验总结|回顾前几轮)/i.test(normalized)) {
+    return "closeout";
+  }
   if (/(executor|先做哪一个|先做哪一包|single task|执行第一包|先执行一个任务)/i.test(normalized)) {
     return "execute";
   }
@@ -159,6 +162,9 @@ function resolveEffectiveIntent(intent, detected) {
   if (detected.artifactKind === "geo-completion-report") {
     return "closeout";
   }
+  if (detected.artifactKind === "geo-agent-retrospective") {
+    return "closeout";
+  }
   if (
     [
       "geo-share-pack",
@@ -403,6 +409,12 @@ function buildCommandChain(detected, intent) {
               `geo-ai-search-optimization agent-decision-log ${baseSource} --append-from ${source}`
             ];
     }
+    case "geo-agent-retrospective":
+      return [
+        `geo-ai-search-optimization completion-report ${source}`,
+        `geo-ai-search-optimization meeting-pack ${source}`,
+        `geo-ai-search-optimization publish-pack ${source}`
+      ];
     case "geo-apply-plan":
       return [
         `geo-ai-search-optimization agent-executor ${source}`,
@@ -486,6 +498,8 @@ function pickSkillName(detected, intent) {
       return "geo-ai-search-optimization-agent-checkpoint";
     case "geo-agent-decision-log":
       return "geo-ai-search-optimization-agent-decision-log";
+    case "geo-agent-retrospective":
+      return "geo-ai-search-optimization-agent-retrospective";
     case "geo-completion-report":
       return "geo-ai-search-optimization-completion-report";
     case "geo-handoff-bundle":
@@ -544,6 +558,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
   }
   if (intent === "closeout") {
     names.add("geo-ai-search-optimization-completion-report");
+    names.add("geo-ai-search-optimization-agent-retrospective");
   }
 
   names.delete(primarySkill);
@@ -571,6 +586,7 @@ function buildStage(intent, detected) {
       "geo-agent-status-board",
       "geo-agent-checkpoint",
       "geo-agent-decision-log",
+      "geo-agent-retrospective",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -588,6 +604,7 @@ function buildStage(intent, detected) {
       "geo-agent-status-board",
       "geo-agent-checkpoint",
       "geo-agent-decision-log",
+      "geo-agent-retrospective",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -683,6 +700,9 @@ function buildNextAction(detected, intent, commands) {
     return `先运行 \`${commands[0]}\`，把当前输入推进到 agent 可执行状态。`;
   }
   if (intent === "closeout") {
+    if (detected.artifactKind === "geo-agent-retrospective") {
+      return `先运行 \`${commands[0]}\`，把多轮复盘结论整理成正式 closeout 与交付结果。`;
+    }
     return `先运行 \`${commands[0]}\`，整理本轮完成情况和剩余风险。`;
   }
   if (intent === "guide") {

package/src/cli.js

@@ -16,6 +16,7 @@ import {
 } from "./agent-progress-tracker.js";
 import { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
 import { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.js";
+import { createAgentRetrospective, renderAgentRetrospectiveMarkdown, writeAgentRetrospectiveOutput } from "./agent-retrospective.js";
 import { createAgentStatusBoard, renderAgentStatusBoardMarkdown, writeAgentStatusBoardOutput } from "./agent-status-board.js";
 import { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
 import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
@@ -83,6 +84,7 @@ function printHelp() {
       "  geo-ai-search-optimization agent-status-board <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization agent-checkpoint <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization agent-decision-log <input> [--append-from <file>] [--note <text>] [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
+      "  geo-ai-search-optimization agent-retrospective <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -395,6 +397,31 @@ async function handleAgentDecisionLog(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentRetrospective(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-retrospective 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+  const retrospective = await createAgentRetrospective(input, {
+    format
+  });
+  const outputJson = retrospective.format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(retrospective, null, 2)}\n`
+    : renderAgentRetrospectiveMarkdown(retrospective);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentRetrospectiveOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent retrospective：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 function handleWhere() {
   process.stdout.write(
     [
@@ -980,6 +1007,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-retrospective") {
+    await handleAgentRetrospective(rest);
+    return;
+  }
+
   if (command === "skills") {
     await handleSkills(rest);
     return;

package/src/index.js

@@ -10,6 +10,7 @@ export { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "
 export { createAgentBatchExecutor, renderAgentBatchExecutorMarkdown, writeAgentBatchExecutorOutput } from "./agent-batch-executor.js";
 export { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
 export { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.js";
+export { createAgentRetrospective, renderAgentRetrospectiveMarkdown, writeAgentRetrospectiveOutput } from "./agent-retrospective.js";
 export { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
 export { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
 export {

package/src/skills.js

@@ -13,6 +13,7 @@ const SKILL_ORDER = [
   "geo-ai-search-optimization-agent-status-board",
   "geo-ai-search-optimization-agent-checkpoint",
   "geo-ai-search-optimization-agent-decision-log",
+  "geo-ai-search-optimization-agent-retrospective",
   "geo-ai-search-optimization-usage",
   "geo-ai-search-optimization-agent-handoff",
   "geo-ai-search-optimization-repair-loop",
@@ -35,6 +36,7 @@ const SKILL_CATEGORY = {
   "geo-ai-search-optimization-agent-status-board": "execution",
   "geo-ai-search-optimization-agent-checkpoint": "execution",
   "geo-ai-search-optimization-agent-decision-log": "execution",
+  "geo-ai-search-optimization-agent-retrospective": "execution",
   "geo-ai-search-optimization-usage": "guidance",
   "geo-ai-search-optimization-agent-handoff": "execution",
   "geo-ai-search-optimization-repair-loop": "execution",
@@ -176,6 +178,7 @@ export function renderBundledSkillsMarkdown(bundle) {
     "- 如果要把当前执行状态直接整理成看板，再进入 agent-status-board。",
     "- 如果要在每轮结束时做继续 / 阻塞 / 收尾决策，再进入 agent-checkpoint。",
     "- 如果要把多轮决策沉淀成可继承的历史，再进入 agent-decision-log。",
+    "- 如果要总结多轮为什么推进顺利或反复卡住，再进入 agent-retrospective。",
     "- 再看 usage skill，知道什么时候该跑哪个命令。",
     "- 如果要交给 agent 执行，再进入 handoff / apply / completion 这一条执行链。",
     "- 如果要产出给团队分发，再进入 share / export / html / publish 这一条交付链。",