geo-ai-search-optimization 1.2.14 → 1.2.16

package/README.md

@@ -207,6 +207,45 @@ geo-ai-search-optimization agent-checkpoint ./reports/agent-progress-tracker.jso
 - 交接说明
 - 可直接复制给 agent 的 checkpoint prompt
 
+## Agent Decision Log 命令
+
+如果你希望把每一轮 checkpoint 累积成“为什么之前这样决定”的历史，而不是只保留单轮状态，可以直接用 `agent-decision-log`：
+
+```bash
+geo-ai-search-optimization agent-decision-log ./your-site
+geo-ai-search-optimization agent-decision-log ./reports/agent-checkpoint.json --note "本轮先解除模板缺失问题"
+geo-ai-search-optimization agent-decision-log ./your-site --append-from ./reports/agent-decision-log.json --blocked "缺少模板文件" --format json --out ./reports/agent-decision-log.json
+```
+
+`agent-decision-log` 会输出：
+
+- 当前累计决策次数
+- 最新检查点类型与决策
+- 当前重点与开放阻塞
+- 决策时间线
+- 最新建议下一步命令
+- 可直接复制给 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 项目，建议照这个顺序做。
@@ -608,6 +647,8 @@ geo-ai-search-optimization agent-batch-executor ./your-site
 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
@@ -678,6 +719,20 @@ 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` 命令
+- 把多轮 checkpoint 沉淀成可继承的决策历史，而不是只有单轮阶段判断
+- 支持从 `agent-checkpoint`、`agent-status-board`、`agent-progress-tracker`、目录、网址等输入继续生成或追加决策记录
+- 新增 `geo-ai-search-optimization-agent-decision-log` skill
+
 ## New in 1.2.14
 
 - 新增 `agent-checkpoint` 命令
@@ -900,6 +955,8 @@ The installed package now includes a bundled GEO skill pack, including:
 - `geo-ai-search-optimization-agent-progress-tracker`
 - `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.14",
+  "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

@@ -102,6 +102,26 @@ Best for:
 - producing a clean handoff note at the end of one execution round
 - giving PM and the next agent one checkpoint artifact to align on
 
+### `geo-ai-search-optimization-agent-decision-log`
+
+Use this when the next agent should inherit decision history, not just one checkpoint.
+
+Best for:
+
+- preserving why previous rounds continued, paused, or moved to closeout
+- 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-decision-log/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: geo-ai-search-optimization-agent-decision-log
+description: Turn GEO checkpoints into a reusable decision history. Use when an agent or PM should preserve why each GEO round continued, paused for blockers, or moved to closeout, so the next agent can inherit the reasoning instead of re-evaluating the entire chain from scratch.
+---
+
+# GEO Agent Decision Log
+
+Use this skill when the team needs durable decision memory across multiple GEO execution rounds.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- converts the current GEO round into a loggable decision entry
+- preserves why the round continued, paused for blockers, or moved to closeout
+- keeps the latest checkpoint, current packet, next packet, blockers, and handoff note together
+- gives the next agent a stable history instead of isolated one-round artifacts
+
+## Best use
+
+- when one checkpoint is not enough and the next agent should see decision history
+- when PM asks why the team chose to continue, unblock, or close out in previous rounds
+- when you want to append a new decision to an existing GEO execution history

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Decision Log"
+  short_description: "Preserve GEO round decisions as reusable history"
+  default_prompt: "Use $geo-ai-search-optimization-agent-decision-log to turn this GEO execution state into a reusable decision history with latest checkpoint, rationale, and next command."

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-one 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
@@ -23,19 +23,21 @@ The package is best explained as twenty-one layers:
 6. `agent-progress-tracker`: track which packet is done, which one is active, and what comes next
 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. `skills`: inspect the bundled skill package
-10. `onboard-url` / `onboard`: first look
-11. `scan`: raw signal check
-12. `audit` / `report`: diagnosis
-13. `fix-plan` / `owner-board`: execution planning
-14. `agent-handoff`: agent takeover package
-15. `apply-plan`: execution loop
-16. `completion-report`: closeout
-17. `handoff-bundle`: all-in-one package
-18. `share-pack`: audience-ready delivery
-19. `export-pack`: folder export
-20. `html-pack` / `publish-pack`: browsable and final delivery output
-21. `pm-brief` / `roadmap`: stakeholder alignment
+9. `agent-decision-log`: preserve why each round continued, paused, or closed out
+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
 
@@ -50,6 +52,8 @@ 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 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
@@ -66,6 +70,8 @@ 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 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
@@ -91,6 +97,8 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `agent-progress-tracker`: show execution progress, current packet, blockers, and the next packet to advance
 - `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
@@ -123,6 +131,8 @@ When explaining the tool to a user:
 - if the user wants the next agent to explain current progress, blockers, and the next packet, move them to `agent-progress-tracker`
 - 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-checkpoint.js

@@ -45,6 +45,26 @@ async function resolveStatusBoard(input, options = {}) {
               : (parsed.statusBoard.tracker?.blockedReasons || []).join(",")
         });
       }
+      if (parsed?.kind === "geo-agent-decision-log" && parsed.latestCheckpoint?.statusBoard?.kind === "geo-agent-status-board") {
+        return createAgentStatusBoard(
+          parsed.latestCheckpoint.statusBoard.source || parsed.latestCheckpoint.source || input,
+          {
+            format: "json",
+            currentTaskId:
+              options.currentTaskId ||
+              parsed.latestCheckpoint.currentPacket?.id ||
+              parsed.latestCheckpoint.statusBoard.tracker?.currentTaskId,
+            completedPacketIds:
+              options.completedPacketIds != null
+                ? options.completedPacketIds
+                : (parsed.latestCheckpoint.completedPackets || []).map((packet) => packet.id).join(","),
+            blockedReasons:
+              options.blockedReasons != null
+                ? options.blockedReasons
+                : (parsed.latestCheckpoint.blockedItems || []).map((item) => item.title).join(",")
+          }
+        );
+      }
     } catch {
       // Fall through to status board generation
     }

package/src/agent-decision-log.js

@@ -0,0 +1,368 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createAgentCheckpoint } from "./agent-checkpoint.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-decision-log 格式：${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) {
+  if (!record || typeof record !== "object") {
+    return record;
+  }
+
+  return {
+    ...record,
+    format
+  };
+}
+
+function buildEntryId(index) {
+  return `decision-${String(index).padStart(2, "0")}`;
+}
+
+function buildDecisionNote(options) {
+  return options.note || options.decisionNote || null;
+}
+
+function buildRecommendedFocus(checkpoint) {
+  switch (checkpoint.decision) {
+    case "resolve-blockers":
+      return `先解除 ${checkpoint.blockedItems.length || 1} 个阻塞项，再继续当前包。`;
+    case "move-to-closeout":
+      return "进入复盘、交接和交付，不要再扩展新任务。";
+    case "continue-current-packet":
+      return `继续推进当前包 ${checkpoint.currentPacket?.id || ""}，不要切换任务。`.trim();
+    case "start-first-packet":
+      return `启动第一包 ${checkpoint.currentPacket?.id || ""}，建立第一轮执行节奏。`.trim();
+    default:
+      return "先补执行上下文，再进入下一轮。";
+  }
+}
+
+function buildLogSummary(entries, checkpoint) {
+  if (entries.length === 1) {
+    return `目前已有 1 次阶段决策，最新结论是 ${checkpoint.decision}。`;
+  }
+
+  return `目前已累计 ${entries.length} 次阶段决策，最新结论是 ${checkpoint.decision}，当前重点是：${buildRecommendedFocus(checkpoint)}`;
+}
+
+function buildEntry(checkpoint, note, index) {
+  return {
+    id: buildEntryId(index),
+    createdAt: new Date().toISOString(),
+    checkpointType: checkpoint.checkpointType,
+    decision: checkpoint.decision,
+    boardStatus: checkpoint.boardStatus,
+    progressPercent: checkpoint.progressPercent,
+    decisionReason: checkpoint.decisionReason,
+    currentPacket: checkpoint.currentPacket
+      ? {
+          id: checkpoint.currentPacket.id,
+          title: checkpoint.currentPacket.title,
+          owner: checkpoint.currentPacket.owner,
+          priority: checkpoint.currentPacket.priority
+        }
+      : null,
+    nextPacket: checkpoint.nextPacket
+      ? {
+          id: checkpoint.nextPacket.id,
+          title: checkpoint.nextPacket.title,
+          owner: checkpoint.nextPacket.owner,
+          priority: checkpoint.nextPacket.priority
+        }
+      : null,
+    blockedItems: checkpoint.blockedItems.map((item) => ({
+      id: item.id,
+      title: item.title,
+      owner: item.owner,
+      priority: item.priority
+    })),
+    suggestedNextCommand: checkpoint.suggestedNextCommand,
+    alternateCommands: checkpoint.alternateCommands,
+    handoffNote: checkpoint.handoffNote,
+    note: note || null
+  };
+}
+
+function buildLogPrompt(log) {
+  const latest = log.latestCheckpoint;
+  const lines = [
+    "你现在进入 GEO 决策历史模式。",
+    `当前输入：${log.source}`,
+    `已累计决策次数：${log.totalEntries}`,
+    `最新检查点类型：${latest.checkpointType}`,
+    `最新决策：${latest.decision}`,
+    `最新决策原因：${latest.decisionReason}`,
+    `当前重点：${log.recommendedFocus}`
+  ];
+
+  if (latest.currentPacket) {
+    lines.push(`当前包：${latest.currentPacket.id}｜${latest.currentPacket.title}`);
+  }
+  if (latest.nextPacket) {
+    lines.push(`下一包：${latest.nextPacket.id}｜${latest.nextPacket.title}`);
+  }
+  if (latest.blockedItems.length > 0) {
+    lines.push(`当前阻塞：${latest.blockedItems.map((item) => item.title).join("；")}`);
+  }
+
+  lines.push("请先说明最近几轮是如何决策的，再给出这一轮应该继续、解阻还是收尾。");
+  lines.push("最后输出下一步命令、交接说明，以及是否需要追加一条新的决策记录。");
+  return lines.join("\n");
+}
+
+async function readJsonIfExists(targetPath) {
+  if (!(await pathExists(targetPath))) {
+    return null;
+  }
+
+  const raw = await fs.readFile(targetPath, "utf8");
+  return JSON.parse(raw);
+}
+
+async function resolveExistingLog(options = {}) {
+  const appendFrom = options.appendFrom || options.appendPath;
+  if (!appendFrom) {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(appendFrom);
+  const parsed = await readJsonIfExists(resolvedPath);
+  if (!parsed || parsed.kind !== "geo-agent-decision-log") {
+    throw new Error(`append-from 需要指向一个 geo-agent-decision-log JSON 工件：${resolvedPath}`);
+  }
+
+  return {
+    path: resolvedPath,
+    log: parsed
+  };
+}
+
+function shouldReuseDecisionLog(parsed, options = {}) {
+  return (
+    parsed?.kind === "geo-agent-decision-log" &&
+    !options.appendFrom &&
+    !options.appendPath &&
+    !options.currentTaskId &&
+    !options.completedPacketIds &&
+    !options.blockedReasons &&
+    !buildDecisionNote(options)
+  );
+}
+
+function getCheckpointSourceFromLog(parsed, fallbackInput) {
+  return (
+    parsed?.latestCheckpoint?.source ||
+    parsed?.latestCheckpoint?.statusBoard?.source ||
+    parsed?.source ||
+    fallbackInput
+  );
+}
+
+async function resolveCheckpoint(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 (shouldReuseDecisionLog(parsed, options)) {
+        return {
+          reuseLog: cloneForFormat(parsed, normalizeFormat(options.format)),
+          checkpoint: parsed.latestCheckpoint || null
+        };
+      }
+
+      if (parsed?.kind === "geo-agent-decision-log" && parsed.latestCheckpoint?.kind === "geo-agent-checkpoint") {
+        const checkpointSource = getCheckpointSourceFromLog(parsed, resolvedInput);
+        const checkpoint = await createAgentCheckpoint(checkpointSource, {
+          format: "json",
+          currentTaskId: options.currentTaskId || parsed.latestCheckpoint.currentPacket?.id,
+          completedPacketIds:
+            options.completedPacketIds != null
+              ? options.completedPacketIds
+              : (parsed.latestCheckpoint.completedPackets || []).map((packet) => packet.id).join(","),
+          blockedReasons:
+            options.blockedReasons != null
+              ? options.blockedReasons
+              : (parsed.latestCheckpoint.blockedItems || []).map((item) => item.title).join(",")
+        });
+
+        return {
+          reuseLog: null,
+          checkpoint
+        };
+      }
+    } catch {
+      // Fall through to checkpoint generation.
+    }
+  }
+
+  return {
+    reuseLog: null,
+    checkpoint: await createAgentCheckpoint(input, {
+      format: "json",
+      currentTaskId: options.currentTaskId,
+      completedPacketIds: options.completedPacketIds,
+      blockedReasons: options.blockedReasons
+    })
+  };
+}
+
+export async function createAgentDecisionLog(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const existing = await resolveExistingLog(options);
+  const { reuseLog, checkpoint } = await resolveCheckpoint(input, {
+    ...options,
+    format: "json"
+  });
+
+  if (reuseLog) {
+    return reuseLog;
+  }
+
+  if (!checkpoint) {
+    throw new Error("无法从当前输入生成 agent checkpoint，因此不能创建 decision log。");
+  }
+
+  const note = buildDecisionNote(options);
+  const previousEntries = existing?.log?.entries || [];
+  const entries = [
+    ...previousEntries,
+    buildEntry(checkpoint, note, previousEntries.length + 1)
+  ];
+
+  const log = {
+    kind: "geo-agent-decision-log",
+    input,
+    source: checkpoint.source,
+    sourceType: checkpoint.sourceType,
+    artifactKind: checkpoint.kind,
+    format,
+    updatedAt: new Date().toISOString(),
+    totalEntries: entries.length,
+    latestDecision: checkpoint.decision,
+    latestDecisionReason: checkpoint.decisionReason,
+    latestCheckpointType: checkpoint.checkpointType,
+    latestBoardStatus: checkpoint.boardStatus,
+    currentPacket: checkpoint.currentPacket,
+    nextPacket: checkpoint.nextPacket,
+    openBlockers: checkpoint.blockedItems,
+    recommendedFocus: buildRecommendedFocus(checkpoint),
+    logSummary: buildLogSummary(entries, checkpoint),
+    suggestedNextCommand: checkpoint.suggestedNextCommand,
+    alternateCommands: checkpoint.alternateCommands,
+    entries,
+    latestCheckpoint: checkpoint,
+    logPrompt: ""
+  };
+
+  log.logPrompt = buildLogPrompt(log);
+  return log;
+}
+
+export function renderAgentDecisionLogMarkdown(log) {
+  const lines = [
+    "# GEO Agent Decision Log",
+    "",
+    `- 输入：\`${log.source}\``,
+    `- 来源类型：\`${log.sourceType}\``,
+    `- 最新工件类型：\`${log.artifactKind}\``,
+    `- 决策次数：\`${log.totalEntries}\``,
+    `- 最新检查点类型：\`${log.latestCheckpointType}\``,
+    `- 最新状态：\`${log.latestBoardStatus}\``,
+    `- 最新决策：\`${log.latestDecision}\``,
+    `- 当前重点：${log.recommendedFocus}`,
+    `- 总结：${log.logSummary}`,
+    ""
+  ];
+
+  if (log.currentPacket) {
+    lines.push("## 当前包", "", `- ${log.currentPacket.id}｜${log.currentPacket.title}`);
+    lines.push(`- Owner：${log.currentPacket.owner}`);
+    lines.push(`- 优先级：${log.currentPacket.priority}`);
+    lines.push("");
+  }
+
+  if (log.nextPacket) {
+    lines.push("## 下一包", "", `- ${log.nextPacket.id}｜${log.nextPacket.title}`);
+    lines.push(`- Owner：${log.nextPacket.owner}`);
+    lines.push(`- 优先级：${log.nextPacket.priority}`);
+    lines.push("");
+  }
+
+  lines.push("## 当前阻塞", "");
+  if (log.openBlockers.length === 0) {
+    lines.push("- 当前没有阻塞。", "");
+  } else {
+    for (const blocker of log.openBlockers) {
+      lines.push(`- ${blocker.id}｜${blocker.title}`);
+      lines.push(`  - Owner：${blocker.owner}`);
+      lines.push(`  - 优先级：${blocker.priority}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 决策时间线", "");
+  for (const entry of [...log.entries].reverse()) {
+    lines.push(`### ${entry.id}`);
+    lines.push("");
+    lines.push(`- 时间：\`${entry.createdAt}\``);
+    lines.push(`- 检查点类型：\`${entry.checkpointType}\``);
+    lines.push(`- 决策：\`${entry.decision}\``);
+    lines.push(`- 状态：\`${entry.boardStatus}\``);
+    lines.push(`- 进度：\`${entry.progressPercent}%\``);
+    lines.push(`- 原因：${entry.decisionReason}`);
+    if (entry.currentPacket) {
+      lines.push(`- 当前包：${entry.currentPacket.id}｜${entry.currentPacket.title}`);
+    }
+    if (entry.nextPacket) {
+      lines.push(`- 下一包：${entry.nextPacket.id}｜${entry.nextPacket.title}`);
+    }
+    if (entry.blockedItems.length > 0) {
+      lines.push(`- 阻塞：${entry.blockedItems.map((item) => item.title).join("；")}`);
+    }
+    if (entry.note) {
+      lines.push(`- 备注：${entry.note}`);
+    }
+    lines.push(`- 建议命令：\`${entry.suggestedNextCommand}\``);
+    lines.push(`- 交接说明：${entry.handoffNote}`);
+    lines.push("");
+  }
+
+  lines.push("## 建议下一步命令", "", `- \`${log.suggestedNextCommand}\``);
+
+  if (log.alternateCommands.length > 0) {
+    lines.push("", "## 备选命令", "");
+    for (const command of log.alternateCommands) {
+      lines.push(`- \`${command}\``);
+    }
+  }
+
+  lines.push("", "## 最新检查点", "", "```text", log.latestCheckpoint.checkpointPrompt, "```");
+  lines.push("", "## 可直接复制给 Agent 的 Decision Log Prompt", "", "```text", log.logPrompt, "```");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentDecisionLogOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}