geo-ai-search-optimization 1.2.13 → 1.2.14

package/README.md

@@ -186,6 +186,27 @@ 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
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -586,6 +607,7 @@ 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 skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -656,6 +678,13 @@ geo-ai-search-optimization help
 - 输出 do-now checklist、stop checklist、success checklist、验证命令和回报模板
 - 新增 `geo-ai-search-optimization-agent-executor` 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 +899,7 @@ 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-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.14",
   "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,16 @@ 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
+
 ## 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-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-one 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,20 @@ 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. `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
 
 ## Recommended command order
 
@@ -48,6 +49,7 @@ 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 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 +65,7 @@ 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 scan ./your-site
 npx geo-ai-search-optimization audit ./your-site
 npx geo-ai-search-optimization fix-plan ./your-site
@@ -87,6 +90,7 @@ 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
 - `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 +122,7 @@ 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`
 - 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,358 @@
+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(",")
+        });
+      }
+    } 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);
+}

package/src/agent-progress-tracker.js

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

package/src/agent-session.js

@@ -61,6 +61,9 @@ function inferSkillForCommand(commandName, flow) {
   if (commandName === "agent-status-board") {
     return "geo-ai-search-optimization-agent-status-board";
   }
+  if (commandName === "agent-checkpoint") {
+    return "geo-ai-search-optimization-agent-checkpoint";
+  }
   if (commandName === "skills" || commandName === "quick-start") {
     return "geo-ai-search-optimization-usage";
   }
@@ -131,6 +134,8 @@ function inferStepPurpose(commandName, flow) {
       return "追踪当前做到第几包、卡点在哪里，以及下一包该推进什么。";
     case "agent-status-board":
       return "把当前执行状态整理成 PM 和 agent 都能直接消费的分栏看板。";
+    case "agent-checkpoint":
+      return "把当前阶段压成继续 / 阻塞 / 收尾的决策检查点。";
     case "apply-plan":
       return "把交接结果推进到具体执行包。";
     case "completion-report":
@@ -181,6 +186,8 @@ function inferExpectedArtifact(commandName) {
       return "agent 执行进度追踪工件";
     case "agent-status-board":
       return "agent 执行状态看板";
+    case "agent-checkpoint":
+      return "agent 阶段检查点工件";
     case "apply-plan":
       return "执行包";
     case "completion-report":
@@ -228,6 +235,9 @@ function buildStepInstructions(parsedCommand, flow) {
   if (parsedCommand.commandName === "agent-status-board") {
     lines.push("这一步用于把当前执行状态转成看板视图，方便 PM 和 agent 对齐当前阶段。");
   }
+  if (parsedCommand.commandName === "agent-checkpoint") {
+    lines.push("这一步用于明确此刻应该继续、先解除阻塞，还是进入收尾。");
+  }
   if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
     lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
   }

package/src/agent-status-board.js

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

package/src/auto-flow.js

@@ -53,6 +53,9 @@ function inferTaskTextMode(text) {
   if (/(status-board|status board|状态看板|执行看板|看板视图|board 视图)/i.test(normalized)) {
     return "execute";
   }
+  if (/(checkpoint|检查点|阶段检查点|继续还是收尾|解除阻塞还是继续)/i.test(normalized)) {
+    return "execute";
+  }
   if (/(executor|先做哪一个|先做哪一包|single task|执行第一包|先执行一个任务)/i.test(normalized)) {
     return "execute";
   }
@@ -173,6 +176,7 @@ function resolveEffectiveIntent(intent, detected) {
       "geo-agent-batch-executor",
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
+      "geo-agent-checkpoint",
       "geo-apply-plan",
       "geo-handoff-bundle",
       "geo-fix-plan"
@@ -351,6 +355,24 @@ function buildCommandChain(detected, intent) {
               `geo-ai-search-optimization completion-report ${source}`,
               `geo-ai-search-optimization handoff-bundle ${source}`
             ];
+    case "geo-agent-checkpoint":
+      return detected.parsed?.decision === "move-to-closeout"
+        ? [
+            `geo-ai-search-optimization completion-report ${source}`,
+            `geo-ai-search-optimization handoff-bundle ${source}`,
+            `geo-ai-search-optimization publish-pack ${source}`
+          ]
+        : detected.parsed?.decision === "resolve-blockers"
+          ? [
+              detected.parsed.suggestedNextCommand || `geo-ai-search-optimization agent-runbook ${source}`,
+              `geo-ai-search-optimization agent-status-board ${source}`,
+              `geo-ai-search-optimization agent-progress-tracker ${source}`
+            ]
+          : [
+              detected.parsed?.suggestedNextCommand || `geo-ai-search-optimization agent-executor ${source}`,
+              `geo-ai-search-optimization agent-progress-tracker ${source}`,
+              `geo-ai-search-optimization completion-report ${source}`
+            ];
     case "geo-apply-plan":
       return [
         `geo-ai-search-optimization agent-executor ${source}`,
@@ -430,6 +452,8 @@ function pickSkillName(detected, intent) {
       return "geo-ai-search-optimization-agent-progress-tracker";
     case "geo-agent-status-board":
       return "geo-ai-search-optimization-agent-status-board";
+    case "geo-agent-checkpoint":
+      return "geo-ai-search-optimization-agent-checkpoint";
     case "geo-completion-report":
       return "geo-ai-search-optimization-completion-report";
     case "geo-handoff-bundle":
@@ -469,6 +493,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
       "geo-agent-batch-executor",
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
+      "geo-agent-checkpoint",
       "geo-apply-plan"
     ].includes(
       detected.artifactKind
@@ -477,6 +502,7 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
     names.add("geo-ai-search-optimization-agent-batch-executor");
     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-executor");
     names.add("geo-ai-search-optimization-agent-runbook");
     names.add("geo-ai-search-optimization-agent-handoff");
@@ -509,6 +535,7 @@ function buildStage(intent, detected) {
       "geo-agent-batch-executor",
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
+      "geo-agent-checkpoint",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)
@@ -524,6 +551,7 @@ function buildStage(intent, detected) {
       "geo-agent-batch-executor",
       "geo-agent-progress-tracker",
       "geo-agent-status-board",
+      "geo-agent-checkpoint",
       "geo-apply-plan",
       "geo-handoff-bundle"
     ].includes(detected.artifactKind)

package/src/cli.js

@@ -14,6 +14,7 @@ import {
   renderAgentProgressTrackerMarkdown,
   writeAgentProgressTrackerOutput
 } from "./agent-progress-tracker.js";
+import { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.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";
@@ -79,6 +80,7 @@ function printHelp() {
       "  geo-ai-search-optimization agent-batch-executor <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--task <id>] [--count <count>] [--format <markdown|json>] [--out <file>]",
       "  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 skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -333,6 +335,34 @@ async function handleAgentStatusBoard(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentCheckpoint(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-checkpoint 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+  const checkpoint = await createAgentCheckpoint(input, {
+    format,
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  const outputJson = checkpoint.format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(checkpoint, null, 2)}\n`
+    : renderAgentCheckpointMarkdown(checkpoint);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentCheckpointOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent checkpoint：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 function handleWhere() {
   process.stdout.write(
     [
@@ -908,6 +938,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-checkpoint") {
+    await handleAgentCheckpoint(rest);
+    return;
+  }
+
   if (command === "skills") {
     await handleSkills(rest);
     return;

package/src/index.js

@@ -8,6 +8,7 @@ export {
 export { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./auto-flow.js";
 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 { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
 export { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
 export {

package/src/skills.js

@@ -11,6 +11,7 @@ const SKILL_ORDER = [
   "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-usage",
   "geo-ai-search-optimization-agent-handoff",
   "geo-ai-search-optimization-repair-loop",
@@ -31,6 +32,7 @@ const SKILL_CATEGORY = {
   "geo-ai-search-optimization-agent-batch-executor": "execution",
   "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-usage": "guidance",
   "geo-ai-search-optimization-agent-handoff": "execution",
   "geo-ai-search-optimization-repair-loop": "execution",
@@ -170,6 +172,7 @@ export function renderBundledSkillsMarkdown(bundle) {
     "- 如果要连续推进前 2 到 3 包，但仍然一次只做一包，再进入 agent-batch-executor。",
     "- 如果要追踪目前做到第几包、卡在哪、下一包是什么，再进入 agent-progress-tracker。",
     "- 如果要把当前执行状态直接整理成看板，再进入 agent-status-board。",
+    "- 如果要在每轮结束时做继续 / 阻塞 / 收尾决策，再进入 agent-checkpoint。",
     "- 再看 usage skill，知道什么时候该跑哪个命令。",
     "- 如果要交给 agent 执行，再进入 handoff / apply / completion 这一条执行链。",
     "- 如果要产出给团队分发，再进入 share / export / html / publish 这一条交付链。",