geo-ai-search-optimization 1.2.14 → 1.2.15

package/README.md

@@ -207,6 +207,25 @@ 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
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -608,6 +627,7 @@ 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 skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -678,6 +698,13 @@ geo-ai-search-optimization help
 - 输出 do-now checklist、stop checklist、success checklist、验证命令和回报模板
 - 新增 `geo-ai-search-optimization-agent-executor` 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 +927,7 @@ 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-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.15",
   "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,16 @@ 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
+
 ## 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-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-two 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,20 @@ 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. `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
 
 ## Recommended command order
 
@@ -50,6 +51,7 @@ 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 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 +68,7 @@ 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 scan ./your-site
 npx geo-ai-search-optimization audit ./your-site
 npx geo-ai-search-optimization fix-plan ./your-site
@@ -91,6 +94,7 @@ 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
 - `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 +127,7 @@ 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`
 - 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);
+}

package/src/agent-progress-tracker.js

@@ -168,6 +168,42 @@ function buildExecutionContextFromParsedArtifact(parsed, input) {
     };
   }
 
+  if (parsed?.kind === "geo-agent-decision-log" && parsed.latestCheckpoint?.statusBoard?.tracker?.applyPlan?.kind === "geo-apply-plan") {
+    return {
+      source:
+        parsed.source ||
+        parsed.latestCheckpoint.source ||
+        parsed.latestCheckpoint.statusBoard.source ||
+        parsed.latestCheckpoint.statusBoard.tracker.source ||
+        parsed.latestCheckpoint.statusBoard.tracker.applyPlan.source ||
+        input,
+      sourceType:
+        parsed.sourceType ||
+        parsed.latestCheckpoint.sourceType ||
+        parsed.latestCheckpoint.statusBoard.sourceType ||
+        parsed.latestCheckpoint.statusBoard.tracker.sourceType ||
+        parsed.latestCheckpoint.statusBoard.tracker.applyPlan.sourceType ||
+        "json",
+      artifactKind: parsed.kind,
+      applyPlan: parsed.latestCheckpoint.statusBoard.tracker.applyPlan,
+      trackerState: {
+        currentTaskId:
+          parsed.latestCheckpoint.currentPacket?.id ||
+          parsed.latestCheckpoint.statusBoard.tracker.currentTaskId ||
+          parsed.latestCheckpoint.statusBoard.tracker.activePacket?.id ||
+          null,
+        completedPacketIds:
+          parsed.latestCheckpoint.statusBoard.tracker.completedPacketIds ||
+          parsed.latestCheckpoint.completedPackets?.map((packet) => packet.id) ||
+          [],
+        blockedReasons:
+          parsed.latestCheckpoint.statusBoard.tracker.blockedReasons ||
+          parsed.latestCheckpoint.blockedItems?.map((item) => item.title) ||
+          []
+      }
+    };
+  }
+
   if (parsed?.kind === "geo-completion-report") {
     return {
       source: parsed.source || input,

package/src/agent-session.js

@@ -64,6 +64,9 @@ function inferSkillForCommand(commandName, flow) {
   if (commandName === "agent-checkpoint") {
     return "geo-ai-search-optimization-agent-checkpoint";
   }
+  if (commandName === "agent-decision-log") {
+    return "geo-ai-search-optimization-agent-decision-log";
+  }
   if (commandName === "skills" || commandName === "quick-start") {
     return "geo-ai-search-optimization-usage";
   }
@@ -136,6 +139,8 @@ function inferStepPurpose(commandName, flow) {
       return "把当前执行状态整理成 PM 和 agent 都能直接消费的分栏看板。";
     case "agent-checkpoint":
       return "把当前阶段压成继续 / 阻塞 / 收尾的决策检查点。";
+    case "agent-decision-log":
+      return "把每一轮 checkpoint 沉淀成可继承的决策历史。";
     case "apply-plan":
       return "把交接结果推进到具体执行包。";
     case "completion-report":
@@ -188,6 +193,8 @@ function inferExpectedArtifact(commandName) {
       return "agent 执行状态看板";
     case "agent-checkpoint":
       return "agent 阶段检查点工件";
+    case "agent-decision-log":
+      return "agent 决策历史工件";
     case "apply-plan":
       return "执行包";
     case "completion-report":
@@ -238,6 +245,9 @@ function buildStepInstructions(parsedCommand, flow) {
   if (parsedCommand.commandName === "agent-checkpoint") {
     lines.push("这一步用于明确此刻应该继续、先解除阻塞，还是进入收尾。");
   }
+  if (parsedCommand.commandName === "agent-decision-log") {
+    lines.push("这一步用于保留跨轮决策历史，方便下一位 agent 直接承接上一次判断。");
+  }
   if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
     lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
   }

package/src/agent-status-board.js

@@ -154,6 +154,26 @@ async function resolveTracker(input, options = {}) {
               : (parsed.statusBoard.tracker.blockedReasons || []).join(",")
         });
       }
+      if (parsed?.kind === "geo-agent-decision-log" && parsed.latestCheckpoint?.statusBoard?.tracker?.kind === "geo-agent-progress-tracker") {
+        return createAgentProgressTracker(
+          parsed.latestCheckpoint.statusBoard.tracker.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.statusBoard.tracker.completedPacketIds || []).join(","),
+            blockedReasons:
+              options.blockedReasons != null
+                ? options.blockedReasons
+                : (parsed.latestCheckpoint.statusBoard.tracker.blockedReasons || []).join(",")
+          }
+        );
+      }
     } catch {
       // Fall through to tracker generation
     }

package/src/auto-flow.js

@@ -56,6 +56,9 @@ function inferTaskTextMode(text) {
   if (/(checkpoint|检查点|阶段检查点|继续还是收尾|解除阻塞还是继续)/i.test(normalized)) {
     return "execute";
   }
+  if (/(decision-log|decision log|决策历史|决策日志|为什么这样决定|历史决策)/i.test(normalized)) {
+    return "execute";
+  }
   if (/(executor|先做哪一个|先做哪一包|single task|执行第一包|先执行一个任务)/i.test(normalized)) {
     return "execute";
   }
@@ -177,6 +180,7 @@ function resolveEffectiveIntent(intent, detected) {
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
       "geo-agent-checkpoint",
+      "geo-agent-decision-log",
       "geo-apply-plan",
       "geo-handoff-bundle",
       "geo-fix-plan"
@@ -373,6 +377,32 @@ function buildCommandChain(detected, intent) {
               `geo-ai-search-optimization agent-progress-tracker ${source}`,
               `geo-ai-search-optimization completion-report ${source}`
             ];
+    case "geo-agent-decision-log": {
+      const baseSource = detected.parsed?.latestCheckpoint?.source || detected.parsed?.source || source;
+      const latestDecision = detected.parsed?.latestDecision;
+      const suggestedNext =
+        detected.parsed?.suggestedNextCommand ||
+        detected.parsed?.latestCheckpoint?.suggestedNextCommand ||
+        `geo-ai-search-optimization agent-executor ${baseSource}`;
+
+      return latestDecision === "move-to-closeout"
+        ? [
+            `geo-ai-search-optimization completion-report ${baseSource}`,
+            `geo-ai-search-optimization handoff-bundle ${baseSource}`,
+            `geo-ai-search-optimization publish-pack ${baseSource}`
+          ]
+        : latestDecision === "resolve-blockers"
+          ? [
+              suggestedNext,
+              `geo-ai-search-optimization agent-status-board ${source}`,
+              `geo-ai-search-optimization agent-decision-log ${baseSource} --append-from ${source}`
+            ]
+          : [
+              suggestedNext,
+              `geo-ai-search-optimization agent-progress-tracker ${source}`,
+              `geo-ai-search-optimization agent-decision-log ${baseSource} --append-from ${source}`
+            ];
+    }
     case "geo-apply-plan":
       return [
         `geo-ai-search-optimization agent-executor ${source}`,
@@ -454,6 +484,8 @@ function pickSkillName(detected, intent) {
       return "geo-ai-search-optimization-agent-status-board";
     case "geo-agent-checkpoint":
       return "geo-ai-search-optimization-agent-checkpoint";
+    case "geo-agent-decision-log":
+      return "geo-ai-search-optimization-agent-decision-log";
     case "geo-completion-report":
       return "geo-ai-search-optimization-completion-report";
     case "geo-handoff-bundle":
@@ -494,6 +526,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
       "geo-agent-checkpoint",
+      "geo-agent-decision-log",
       "geo-apply-plan"
     ].includes(
       detected.artifactKind
@@ -503,6 +536,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
     names.add("geo-ai-search-optimization-agent-progress-tracker");
     names.add("geo-ai-search-optimization-agent-status-board");
     names.add("geo-ai-search-optimization-agent-checkpoint");
+    names.add("geo-ai-search-optimization-agent-decision-log");
     names.add("geo-ai-search-optimization-agent-executor");
     names.add("geo-ai-search-optimization-agent-runbook");
     names.add("geo-ai-search-optimization-agent-handoff");
@@ -536,6 +570,7 @@ function buildStage(intent, detected) {
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
       "geo-agent-checkpoint",
+      "geo-agent-decision-log",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -552,6 +587,7 @@ function buildStage(intent, detected) {
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
       "geo-agent-checkpoint",
+      "geo-agent-decision-log",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -641,6 +677,9 @@ function buildNextAction(detected, intent, commands) {
     if (detected.artifactKind === "geo-agent-progress-tracker") {
       return `先运行 \`${commands[0]}\`，继续当前执行包或校准下一包。`;
     }
+    if (detected.artifactKind === "geo-agent-decision-log") {
+      return `先运行 \`${commands[0]}\`，沿着最近一次阶段决策继续推进，而不是重新判断整条链。`;
+    }
     return `先运行 \`${commands[0]}\`，把当前输入推进到 agent 可执行状态。`;
   }
   if (intent === "closeout") {

package/src/cli.js

@@ -15,6 +15,7 @@ import {
   writeAgentProgressTrackerOutput
 } from "./agent-progress-tracker.js";
 import { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
+import { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.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";
@@ -81,6 +82,7 @@ function printHelp() {
       "  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 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 skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -363,6 +365,36 @@ async function handleAgentCheckpoint(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentDecisionLog(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-decision-log 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+  const decisionLog = await createAgentDecisionLog(input, {
+    format,
+    appendFrom: getFlagValue(args, "--append-from"),
+    note: getFlagValue(args, "--note"),
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  const outputJson = decisionLog.format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(decisionLog, null, 2)}\n`
+    : renderAgentDecisionLogMarkdown(decisionLog);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentDecisionLogOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent decision log：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 function handleWhere() {
   process.stdout.write(
     [
@@ -943,6 +975,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-decision-log") {
+    await handleAgentDecisionLog(rest);
+    return;
+  }
+
   if (command === "skills") {
     await handleSkills(rest);
     return;

package/src/index.js

@@ -9,6 +9,7 @@ export { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./a
 export { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "./apply-plan.js";
 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 { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
 export { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
 export {

package/src/skills.js

@@ -12,6 +12,7 @@ const SKILL_ORDER = [
   "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-usage",
   "geo-ai-search-optimization-agent-handoff",
   "geo-ai-search-optimization-repair-loop",
@@ -33,6 +34,7 @@ const SKILL_CATEGORY = {
   "geo-ai-search-optimization-agent-progress-tracker": "execution",
   "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-usage": "guidance",
   "geo-ai-search-optimization-agent-handoff": "execution",
   "geo-ai-search-optimization-repair-loop": "execution",
@@ -173,6 +175,7 @@ export function renderBundledSkillsMarkdown(bundle) {
     "- 如果要追踪目前做到第几包、卡在哪、下一包是什么，再进入 agent-progress-tracker。",
     "- 如果要把当前执行状态直接整理成看板，再进入 agent-status-board。",
     "- 如果要在每轮结束时做继续 / 阻塞 / 收尾决策，再进入 agent-checkpoint。",
+    "- 如果要把多轮决策沉淀成可继承的历史，再进入 agent-decision-log。",
     "- 再看 usage skill，知道什么时候该跑哪个命令。",
     "- 如果要交给 agent 执行，再进入 handoff / apply / completion 这一条执行链。",
     "- 如果要产出给团队分发，再进入 share / export / html / publish 这一条交付链。",