geo-ai-search-optimization 1.2.13 → 1.2.15

package/README.md

@@ -186,6 +186,46 @@ geo-ai-search-optimization agent-status-board ./reports/agent-progress-tracker.j
 - 建议下一步命令
 - 可直接复制给 agent 的 status board prompt
 
+## Agent Checkpoint 命令
+
+如果你希望在每一轮执行结束时，产出一个明确的阶段决策，而不只是状态展示，可以直接用 `agent-checkpoint`：
+
+```bash
+geo-ai-search-optimization agent-checkpoint ./your-site
+geo-ai-search-optimization agent-checkpoint ./reports/agent-status-board.json --completed fix-01 --current fix-02
+geo-ai-search-optimization agent-checkpoint ./reports/agent-progress-tracker.json --blocked "缺少仓库权限" --format json --out ./reports/agent-checkpoint.json
+```
+
+`agent-checkpoint` 会输出：
+
+- 当前检查点类型
+- 当前决策是继续、解除阻塞还是进入收尾
+- gate checks
+- 决策清单
+- 建议下一步命令
+- 备选命令
+- 交接说明
+- 可直接复制给 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 项目，建议照这个顺序做。
@@ -586,6 +626,8 @@ geo-ai-search-optimization agent-executor ./your-site
 geo-ai-search-optimization agent-batch-executor ./your-site
 geo-ai-search-optimization agent-progress-tracker ./your-site
 geo-ai-search-optimization 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
@@ -656,6 +698,20 @@ 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` 命令
+- 把每一轮执行状态压成 continue / unblock / closeout 的阶段决策工件
+- 支持从 `agent-progress-tracker`、`agent-status-board`、`apply-plan` 等工件继续生成检查点
+- 新增 `geo-ai-search-optimization-agent-checkpoint` skill
+
 ## New in 1.2.13
 
 - 新增 `agent-status-board` 命令
@@ -870,6 +926,8 @@ The installed package now includes a bundled GEO skill pack, including:
 - `geo-ai-search-optimization-agent-batch-executor`
 - `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.13",
+  "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

@@ -92,6 +92,26 @@ Best for:
 - showing done, in-progress, blocked, next, and queued packets in one artifact
 - turning progress tracking into a more shareable coordination output
 
+### `geo-ai-search-optimization-agent-checkpoint`
+
+Use this when the next agent should make a stage decision, not just show the current state.
+
+Best for:
+
+- deciding whether the round should continue, unblock, or close out
+- 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-checkpoint/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: geo-ai-search-optimization-agent-checkpoint
+description: Turn GEO execution state into a stage checkpoint decision. Use when an agent should decide whether the current round should continue, first resolve blockers, or move into closeout, based on progress trackers, status boards, apply-plan artifacts, or related execution outputs.
+---
+
+# GEO Agent Checkpoint
+
+Use this skill when the next agent should make a round-level execution decision, not just summarize state.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- converts current GEO execution state into a checkpoint artifact
+- decides whether to continue, unblock, or close out
+- adds gate checks and a decision checklist
+- produces a handoff note and next command for the next agent
+
+## Best use
+
+- when one execution round ends and the team needs a checkpoint
+- when PM asks whether the team should keep going or stop and unblock first
+- when another agent should take over from a stable checkpoint instead of raw state

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Checkpoint"
+  short_description: "Decide continue, unblock, or closeout for this GEO round"
+  default_prompt: "Use $geo-ai-search-optimization-agent-checkpoint to turn this GEO execution state into a checkpoint decision with gate checks, next command, and handoff note."

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 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
@@ -22,19 +22,21 @@ The package is best explained as twenty layers:
 5. `agent-batch-executor`: queue the first few packets, but still advance one packet at a time
 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. `skills`: inspect the bundled skill package
-9. `onboard-url` / `onboard`: first look
-10. `scan`: raw signal check
-11. `audit` / `report`: diagnosis
-12. `fix-plan` / `owner-board`: execution planning
-13. `agent-handoff`: agent takeover package
-14. `apply-plan`: execution loop
-15. `completion-report`: closeout
-16. `handoff-bundle`: all-in-one package
-17. `share-pack`: audience-ready delivery
-18. `export-pack`: folder export
-19. `html-pack` / `publish-pack`: browsable and final delivery output
-20. `pm-brief` / `roadmap`: stakeholder alignment
+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
 
 ## Recommended command order
 
@@ -48,6 +50,8 @@ npx geo-ai-search-optimization agent-executor https://example.com
 npx geo-ai-search-optimization agent-batch-executor https://example.com
 npx geo-ai-search-optimization agent-progress-tracker https://example.com
 npx geo-ai-search-optimization 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
@@ -63,6 +67,8 @@ npx geo-ai-search-optimization agent-executor ./your-site
 npx geo-ai-search-optimization agent-batch-executor ./your-site
 npx geo-ai-search-optimization agent-progress-tracker ./your-site
 npx geo-ai-search-optimization 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
@@ -87,6 +93,8 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `agent-batch-executor`: line up the first few packets in execution order while preserving one-packet-at-a-time discipline
 - `agent-progress-tracker`: show execution progress, current packet, blockers, and the next packet to advance
 - `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
@@ -118,6 +126,8 @@ When explaining the tool to a user:
 - if the user wants the next agent to continuously advance the first 2 to 3 packets in order, move them to `agent-batch-executor`
 - if the user wants the next agent to explain current progress, blockers, and the next packet, move them to `agent-progress-tracker`
 - 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

@@ -0,0 +1,378 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  createAgentStatusBoard,
+  renderAgentStatusBoardMarkdown,
+  writeAgentStatusBoardOutput
+} from "./agent-status-board.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-checkpoint 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveStatusBoard(input, options = {}) {
+  const resolvedPath = path.resolve(input);
+  if (await pathExists(resolvedPath)) {
+    try {
+      const raw = await fs.readFile(resolvedPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.kind === "geo-agent-checkpoint" && parsed.statusBoard?.kind === "geo-agent-status-board") {
+        return createAgentStatusBoard(parsed.statusBoard.source || input, {
+          format: "json",
+          currentTaskId: options.currentTaskId || parsed.currentPacket?.id || parsed.statusBoard.tracker?.currentTaskId,
+          completedPacketIds:
+            options.completedPacketIds != null
+              ? options.completedPacketIds
+              : (parsed.statusBoard.tracker?.completedPacketIds || []).join(","),
+          blockedReasons:
+            options.blockedReasons != null
+              ? options.blockedReasons
+              : (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
+    }
+  }
+
+  return createAgentStatusBoard(input, {
+    format: "json",
+    currentTaskId: options.currentTaskId,
+    completedPacketIds: options.completedPacketIds,
+    blockedReasons: options.blockedReasons
+  });
+}
+
+function inferDecision(board) {
+  switch (board.boardStatus) {
+    case "blocked":
+      return "resolve-blockers";
+    case "completed":
+      return "move-to-closeout";
+    case "in-progress":
+      return "continue-current-packet";
+    case "not-started":
+      return "start-first-packet";
+    default:
+      return "gather-context";
+  }
+}
+
+function inferCheckpointType(decision) {
+  switch (decision) {
+    case "resolve-blockers":
+      return "blocker-checkpoint";
+    case "move-to-closeout":
+      return "closeout-checkpoint";
+    case "continue-current-packet":
+    case "start-first-packet":
+      return "execution-checkpoint";
+    default:
+      return "context-checkpoint";
+  }
+}
+
+function buildDecisionReason(board, decision) {
+  switch (decision) {
+    case "resolve-blockers":
+      return `当前存在 ${board.columns.blocked.length} 个阻塞项，先解除阻塞，再继续推进 ${board.columns.inProgress[0]?.id || "当前包"}。`;
+    case "move-to-closeout":
+      return "当前执行包已经全部完成，适合进入复盘、交接和交付阶段。";
+    case "continue-current-packet":
+      return `当前已有明确执行包 ${board.columns.inProgress[0]?.id || ""}，且没有阻塞，可以继续推进。`;
+    case "start-first-packet":
+      return `当前尚未开始，但第一包 ${board.columns.inProgress[0]?.id || ""} 已经明确，可以直接启动。`;
+    default:
+      return "当前还缺执行上下文，先补充上下文再做下一步决策。";
+  }
+}
+
+function buildGateChecks(board, decision) {
+  const hasActive = board.columns.inProgress.length > 0;
+  const hasBlockers = board.columns.blocked.length > 0;
+  const canCloseout = board.boardStatus === "completed";
+  const hasNextCommand = Boolean(board.suggestedNextCommand);
+
+  return [
+    {
+      id: "gate-active-packet",
+      label: "当前是否有明确执行包",
+      status: hasActive ? "pass" : "fail",
+      detail: hasActive ? `当前包：${board.columns.inProgress[0].id}` : "当前没有明确执行包。"
+    },
+    {
+      id: "gate-blockers",
+      label: "当前是否无阻塞",
+      status: hasBlockers ? "fail" : "pass",
+      detail: hasBlockers ? `阻塞数：${board.columns.blocked.length}` : "当前没有阻塞。"
+    },
+    {
+      id: "gate-closeout",
+      label: "是否达到收尾条件",
+      status: canCloseout ? "pass" : "warn",
+      detail: canCloseout ? "已可进入 closeout。" : "当前仍处于执行中或待开始。"
+    },
+    {
+      id: "gate-next-command",
+      label: "是否有下一步命令",
+      status: hasNextCommand ? "pass" : "fail",
+      detail: hasNextCommand ? board.suggestedNextCommand : "还没有稳定的下一步命令。"
+    },
+    {
+      id: "gate-decision-fit",
+      label: "当前决策是否匹配状态",
+      status:
+        (decision === "resolve-blockers" && hasBlockers) ||
+        (decision === "move-to-closeout" && canCloseout) ||
+        (decision === "continue-current-packet" && hasActive && !hasBlockers) ||
+        (decision === "start-first-packet" && board.boardStatus === "not-started") ||
+        (decision === "gather-context" && board.boardStatus === "needs-context")
+          ? "pass"
+          : "warn",
+      detail: `当前决策：${decision}`
+    }
+  ];
+}
+
+function buildDecisionChecklist(decision) {
+  switch (decision) {
+    case "resolve-blockers":
+      return [
+        "先确认阻塞是不是会影响当前包验收。",
+        "先补权限、仓库、模板或关键上下文。",
+        "阻塞解除后，重新生成 progress tracker 或 status board。"
+      ];
+    case "move-to-closeout":
+      return [
+        "确认本轮执行包已全部完成。",
+        "进入 completion-report，总结已完成、剩余风险和下一轮任务。",
+        "进入 handoff-bundle 或 publish-pack 进行交接或交付。"
+      ];
+    case "continue-current-packet":
+      return [
+        "继续推进当前执行包，不要切换到其他包。",
+        "先完成当前包的验证与回报，再进入下一包。",
+        "完成后重新生成 progress tracker 或 status board。"
+      ];
+    case "start-first-packet":
+      return [
+        "从第一包开始执行。",
+        "不要同时展开多包任务。",
+        "开始后马上用 progress tracker 记录当前包。"
+      ];
+    default:
+      return [
+        "先补仓库、模板、页面或执行工件上下文。",
+        "补完上下文后重新生成 checkpoint。",
+        "不要假装已经进入执行阶段。"
+      ];
+  }
+}
+
+function buildSuggestedNextCommand(board, decision) {
+  if (decision === "move-to-closeout") {
+    return `geo-ai-search-optimization completion-report ${board.source}`;
+  }
+  if (decision === "gather-context") {
+    return `geo-ai-search-optimization agent-session ${board.source}`;
+  }
+  return board.suggestedNextCommand;
+}
+
+function buildAlternateCommands(board, decision) {
+  const commands = new Set();
+
+  if (decision === "resolve-blockers") {
+    commands.add(board.suggestedNextCommand);
+    commands.add(`geo-ai-search-optimization agent-status-board ${board.source}`);
+    commands.add(`geo-ai-search-optimization agent-progress-tracker ${board.source}`);
+  } else if (decision === "move-to-closeout") {
+    commands.add(`geo-ai-search-optimization handoff-bundle ${board.source}`);
+    commands.add(`geo-ai-search-optimization publish-pack ${board.source}`);
+  } else if (decision === "continue-current-packet" || decision === "start-first-packet") {
+    commands.add(board.suggestedNextCommand);
+    commands.add(`geo-ai-search-optimization agent-progress-tracker ${board.source}`);
+    commands.add(`geo-ai-search-optimization agent-status-board ${board.source}`);
+  } else {
+    commands.add(`geo-ai-search-optimization agent-session ${board.source}`);
+    commands.add(`geo-ai-search-optimization agent-runbook ${board.source}`);
+  }
+
+  return Array.from(commands).filter(Boolean);
+}
+
+function buildHandoffNote(board, decision) {
+  switch (decision) {
+    case "resolve-blockers":
+      return "下一位 agent 先不要继续修代码，先解除阻塞项，再回到当前执行包。";
+    case "move-to-closeout":
+      return "下一位 agent 可以直接进入复盘、交接和交付流程。";
+    case "continue-current-packet":
+      return `下一位 agent 继续当前包 ${board.columns.inProgress[0]?.id || ""}，不要切换任务。`;
+    case "start-first-packet":
+      return `下一位 agent 从第一包 ${board.columns.inProgress[0]?.id || ""} 开始。`;
+    default:
+      return "下一位 agent 先补上下文，不要直接开始修改。";
+  }
+}
+
+function buildCheckpointPrompt(checkpoint) {
+  const lines = [
+    "你现在进入 GEO 阶段检查点模式。",
+    `当前输入：${checkpoint.source}`,
+    `检查点类型：${checkpoint.checkpointType}`,
+    `当前状态：${checkpoint.boardStatus}`,
+    `当前决策：${checkpoint.decision}`,
+    `决策原因：${checkpoint.decisionReason}`
+  ];
+
+  if (checkpoint.currentPacket) {
+    lines.push(`当前包：${checkpoint.currentPacket.id}｜${checkpoint.currentPacket.title}`);
+  }
+  if (checkpoint.nextPacket) {
+    lines.push(`下一包：${checkpoint.nextPacket.id}｜${checkpoint.nextPacket.title}`);
+  }
+  if (checkpoint.blockedItems.length > 0) {
+    lines.push(`阻塞项：${checkpoint.blockedItems.map((item) => item.title).join("；")}`);
+  }
+
+  lines.push("请先回答：现在该继续、该解除阻塞，还是该进入收尾。");
+  lines.push("然后给出本轮 checkpoint 结论、下一步命令和交接说明。");
+  return lines.join("\n");
+}
+
+export async function createAgentCheckpoint(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const statusBoard = await resolveStatusBoard(input, options);
+  const decision = inferDecision(statusBoard);
+
+  const checkpoint = {
+    kind: "geo-agent-checkpoint",
+    input,
+    source: statusBoard.source,
+    sourceType: statusBoard.sourceType,
+    artifactKind: statusBoard.kind,
+    format,
+    checkpointType: inferCheckpointType(decision),
+    boardStatus: statusBoard.boardStatus,
+    decision,
+    decisionReason: buildDecisionReason(statusBoard, decision),
+    progressPercent: statusBoard.progressPercent,
+    currentPacket: statusBoard.columns.inProgress[0] || null,
+    nextPacket: statusBoard.columns.nextUp[0] || null,
+    completedPackets: statusBoard.columns.completed,
+    blockedItems: statusBoard.columns.blocked,
+    gateChecks: buildGateChecks(statusBoard, decision),
+    decisionChecklist: buildDecisionChecklist(decision),
+    suggestedNextCommand: buildSuggestedNextCommand(statusBoard, decision),
+    alternateCommands: buildAlternateCommands(statusBoard, decision),
+    handoffNote: buildHandoffNote(statusBoard, decision),
+    checkpointPrompt: "",
+    statusBoard
+  };
+
+  checkpoint.checkpointPrompt = buildCheckpointPrompt(checkpoint);
+  return checkpoint;
+}
+
+export function renderAgentCheckpointMarkdown(checkpoint) {
+  const lines = [
+    "# GEO Agent Checkpoint",
+    "",
+    `- 输入：\`${checkpoint.source}\``,
+    `- 来源类型：\`${checkpoint.sourceType}\``,
+    `- 工件类型：\`${checkpoint.artifactKind}\``,
+    `- 检查点类型：\`${checkpoint.checkpointType}\``,
+    `- 当前状态：\`${checkpoint.boardStatus}\``,
+    `- 当前决策：\`${checkpoint.decision}\``,
+    `- 进度：\`${checkpoint.progressPercent}%\``,
+    `- 决策原因：${checkpoint.decisionReason}`,
+    ""
+  ];
+
+  if (checkpoint.currentPacket) {
+    lines.push("## 当前包", "");
+    lines.push(`- ${checkpoint.currentPacket.id}｜${checkpoint.currentPacket.title}`);
+    lines.push(`- Owner：${checkpoint.currentPacket.owner}`);
+    lines.push(`- 优先级：${checkpoint.currentPacket.priority}`);
+    lines.push("");
+  }
+
+  if (checkpoint.nextPacket) {
+    lines.push("## 下一包", "");
+    lines.push(`- ${checkpoint.nextPacket.id}｜${checkpoint.nextPacket.title}`);
+    lines.push(`- Owner：${checkpoint.nextPacket.owner}`);
+    lines.push(`- 优先级：${checkpoint.nextPacket.priority}`);
+    lines.push("");
+  }
+
+  lines.push("## Gate Checks", "");
+  for (const gate of checkpoint.gateChecks) {
+    lines.push(`- [${gate.status}] ${gate.label}：${gate.detail}`);
+  }
+
+  lines.push("", "## 决策清单", "");
+  for (const item of checkpoint.decisionChecklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 建议下一步命令", "");
+  lines.push(`- \`${checkpoint.suggestedNextCommand}\``);
+
+  lines.push("", "## 备选命令", "");
+  for (const command of checkpoint.alternateCommands) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push("", "## 交接说明", "");
+  lines.push(`- ${checkpoint.handoffNote}`);
+
+  lines.push("", "## 可直接复制给 Agent 的 Checkpoint Prompt", "", "```text");
+  lines.push(checkpoint.checkpointPrompt);
+  lines.push("```");
+
+  lines.push("", "## 状态看板", "");
+  lines.push(renderAgentStatusBoardMarkdown(checkpoint.statusBoard).trim());
+  lines.push("");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentCheckpointOutput(outputPath, content) {
+  return writeAgentStatusBoardOutput(outputPath, content);
+}