geo-ai-search-optimization 1.1.8 → 1.2.0

package/README.md

@@ -147,6 +147,48 @@ geo-ai-search-optimization agent-handoff https://example.com
 - 让 agent 先基于当前工件给出结构化建议
 - 让 PM 把 GEO 问题变成交接包，而不是临时口头说明
 
+## Apply Plan 命令
+
+如果你希望 agent 不只是“接手”，而是直接进入执行闭环，现在可以用 `apply-plan`：
+
+```bash
+geo-ai-search-optimization apply-plan ./your-site
+geo-ai-search-optimization apply-plan ./your-site --task fix-01 --format json --out ./reports/apply-plan.json
+geo-ai-search-optimization apply-plan https://example.com
+```
+
+`apply-plan` 会输出：
+
+- 本轮应该先执行哪些任务
+- 每个任务先检查什么
+- 建议怎么改
+- 该跑哪些验证命令
+- 完成后怎么向用户回报
+
+这适合：
+
+- 让 agent 直接开始修复
+- 让 agent 在每个任务完成后有一致的回报格式
+- 把 GEO workflow 从“分析”推进到“执行 + 验证 + 回报”
+
+## Completion Report 命令
+
+如果你希望 agent 在完成一轮修复或建议后，自动产出复盘、剩余风险和下一轮任务，现在可以用 `completion-report`：
+
+```bash
+geo-ai-search-optimization completion-report ./your-site
+geo-ai-search-optimization completion-report ./reports/apply-plan.json --format json --out ./reports/completion-report.json
+geo-ai-search-optimization completion-report https://example.com
+```
+
+`completion-report` 会输出：
+
+- 本轮已完成什么
+- 当前还剩哪些风险
+- 下一轮建议先做哪些任务
+- 建议复测命令
+- 可直接复用的完成回报模板
+
 ## Fix Plan 命令
 
 如果你已经跑过 `audit`、`report` 或 `onboard-url`，下一步就可以直接把结果转成 PM 待办清单：
@@ -298,6 +340,8 @@ geo-ai-search-optimization init-schema organization ./site --site-url "https://e
 geo-ai-search-optimization init-schema faq-page ./site --json
 geo-ai-search-optimization audit ./my-site
 geo-ai-search-optimization agent-handoff ./my-site
+geo-ai-search-optimization apply-plan ./my-site
+geo-ai-search-optimization completion-report ./my-site
 geo-ai-search-optimization exec-summary ./my-site
 geo-ai-search-optimization fix-plan ./my-site
 geo-ai-search-optimization owner-board ./my-site
@@ -313,6 +357,20 @@ geo-ai-search-optimization version
 geo-ai-search-optimization help
 ```
 
+## New in 1.2.0
+
+- 新增 `completion-report`
+- 让 agent 在完成一轮 GEO 修复或建议后自动产出 closeout report
+- 会输出本轮完成项、剩余风险、下一轮任务、复测命令和完成回报模板
+- 新增 `geo-ai-search-optimization-completion-report` skill，帮助 agent 稳定产出复盘
+
+## New in 1.1.9
+
+- 新增 `apply-plan`
+- 让 agent-handoff 继续进入执行闭环，而不是停在交接阶段
+- 会输出任务执行包、验证指令、Done 定义、完成回报模板
+- 新增 `geo-ai-search-optimization-repair-loop` skill，帮助 agent 继续做修复、验证和回报
+
 ## New in 1.1.8
 
 - 新增 `agent-handoff`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "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/quick-start.md

@@ -43,6 +43,8 @@ geo-ai-search-optimization report ./your-site --mode audit --format html --out .
 geo-ai-search-optimization exec-summary ./your-site --out ./reports/exec-summary.md
 geo-ai-search-optimization fix-plan ./your-site --format json --out ./reports/fix-plan.json
 geo-ai-search-optimization agent-handoff ./your-site --out ./reports/agent-handoff.md
+geo-ai-search-optimization apply-plan ./your-site --out ./reports/apply-plan.md
+geo-ai-search-optimization completion-report ./your-site --out ./reports/completion-report.md
 geo-ai-search-optimization owner-board ./your-site --out ./reports/owner-board.md
 geo-ai-search-optimization meeting-pack ./your-site --out ./reports/meeting-pack.md
 geo-ai-search-optimization pm-brief ./your-site --out ./reports/pm-brief.md
@@ -57,7 +59,9 @@ geo-ai-search-optimization roadmap ./your-site --out ./reports/roadmap.md
 2. 再补 llms.txt / schema / author / freshness
 3. 再做 FAQ / comparison / methodology / evidence 页面
 4. 需要交接给 agent 时，生成 agent-handoff 工件
-5. 重跑 scan / audit / report 验证是否改善
+5. 需要 agent 直接开始做时，生成 apply-plan
+6. 完成一轮后生成 completion-report
+7. 重跑 scan / audit / report 验证是否改善
 
 ## 推荐节奏
 

package/resources/geo-ai-search-optimization-completion-report/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: geo-ai-search-optimization-completion-report
+description: Create GEO completion reports after an execution round. Use when an agent has already produced fixes or recommendations and needs to summarize what was completed, what risks remain, what should happen next, and how to report the outcome back to PM or stakeholders.
+---
+
+# GEO Completion Report
+
+Use this skill when GEO work is no longer at the planning stage and the user needs a closeout report for the round.
+
+`GEO = Generative Engine Optimization`
+
+## What this skill is for
+
+Create a clear post-execution report that answers:
+
+1. what got done this round
+2. what still remains risky
+3. what should happen in the next round
+4. what validation should be rerun
+5. how the agent should report completion back
+
+## Preferred input order
+
+Prefer these artifacts in order:
+
+1. `completion-report`
+2. `apply-plan`
+3. `agent-handoff`
+4. `fix-plan` or `report`
+
+If only a repo path or URL is available, derive the report from the latest GEO execution context.
+
+## Response order
+
+Always return:
+
+1. round summary
+2. completed this round
+3. residual risks
+4. next-round tasks
+5. validation commands
+
+Read [references/completion-patterns.md](references/completion-patterns.md) when you need concrete closeout patterns.

package/resources/geo-ai-search-optimization-completion-report/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Completion Report"
+  short_description: "Summarize what was completed, what remains, and what comes next"
+  default_prompt: "Use $geo-ai-search-optimization-completion-report to produce a closeout report for this GEO execution round."

package/resources/geo-ai-search-optimization-completion-report/references/completion-patterns.md

@@ -0,0 +1,25 @@
+# GEO Completion Patterns
+
+## Good completion report shape
+
+1. round summary
+2. completed this round
+3. residual risks
+4. next-round tasks
+5. validation rerun commands
+
+## If the round was direct implementation
+
+Emphasize:
+
+- what changed
+- what was verified
+- what still needs monitoring
+
+## If the round was recommendation only
+
+Emphasize:
+
+- what was clarified
+- what context is still missing
+- what must happen before implementation can start

package/resources/geo-ai-search-optimization-repair-loop/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: geo-ai-search-optimization-repair-loop
+description: Execute GEO repair work from apply-plan and agent-handoff artifacts. Use when an agent should move past recommendations and actually perform a fix, validate the result, and report completion in a PM-readable format.
+---
+
+# GEO Repair Loop
+
+Use this skill when a GEO artifact is no longer just for reading or planning, and the user expects the agent to continue through execution, validation, and completion reporting.
+
+`GEO = Generative Engine Optimization`
+
+## Preferred flow
+
+When possible, use this order:
+
+1. read `agent-handoff` to understand the task and mode
+2. read `apply-plan` to get the execution packet
+3. perform the fix or produce the next-best structured recommendation
+4. rerun the suggested GEO CLI validation commands
+5. generate `completion-report`
+6. report back using the completion template
+
+## Execution rules
+
+- if the artifact says `implementation-ready`, prefer direct code changes over advice-only text
+- if the artifact says `advice-only`, do not pretend code was changed
+- if the artifact says `artifact-guided`, explain what additional repo or page context is needed before direct implementation
+- keep outputs PM-readable while still naming the specific files, templates, or systems you inspected
+
+## Completion reporting
+
+Always include:
+
+1. what you checked
+2. what you changed or recommended
+3. what validation you ran
+4. whether the task can be marked done
+5. what remains next
+
+Read [references/repair-loop-patterns.md](references/repair-loop-patterns.md) when you need concrete execution patterns.

package/resources/geo-ai-search-optimization-repair-loop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Repair Loop"
+  short_description: "Execute GEO fixes from apply-plan and validate completion"
+  default_prompt: "Use $geo-ai-search-optimization-repair-loop to continue from this apply-plan or handoff artifact and complete the next GEO repair task."

package/resources/geo-ai-search-optimization-repair-loop/references/repair-loop-patterns.md

@@ -0,0 +1,33 @@
+# GEO Repair Loop Patterns
+
+## If you have a local project directory
+
+Do:
+
+- inspect reusable templates, metadata helpers, schema generators, and content models first
+- fix the shared layer before patching individual pages where possible
+- rerun the validation commands from `apply-plan`
+- report completion using the provided completion template
+
+## If you only have a public URL
+
+Do:
+
+- give structured recommendations
+- identify the smallest set of pages or templates the user should share next
+- keep the output close to implementation, but do not claim code changes were made
+
+## If you have only exported artifacts
+
+Do:
+
+- use them to determine order, dependencies, and done criteria
+- state clearly when repo access is required for the next step
+
+## Good completion report shape
+
+1. checked
+2. changed or recommended
+3. validation run
+4. done or not done
+5. next step

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

@@ -13,14 +13,16 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as six layers:
+The package is best explained as eight layers:
 
 1. `onboard-url` / `onboard`: first look
 2. `scan`: raw signal check
 3. `audit` / `report`: diagnosis
 4. `fix-plan` / `owner-board`: execution planning
 5. `agent-handoff`: agent takeover package
-6. `pm-brief` / `roadmap`: stakeholder alignment
+6. `apply-plan`: execution loop
+7. `completion-report`: closeout
+8. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -39,6 +41,8 @@ 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
 npx geo-ai-search-optimization agent-handoff ./your-site
+npx geo-ai-search-optimization apply-plan ./your-site
+npx geo-ai-search-optimization completion-report ./your-site
 npx geo-ai-search-optimization owner-board ./your-site
 npx geo-ai-search-optimization roadmap ./your-site
 ```
@@ -52,6 +56,8 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `report`: export audit/onboarding/scan into readable files
 - `fix-plan`: turn issues into backlog-ready tasks
 - `agent-handoff`: turn GEO findings into an artifact an agent can directly continue from
+- `apply-plan`: turn handoff into execution packets with validation commands and completion template
+- `completion-report`: summarize what the agent finished, residual risks, and next-round work
 - `owner-board`: group tasks by PM / engineering / SEO / content
 - `pm-brief`: prepare a PM summary for meetings and prioritization
 - `roadmap`: turn tasks into a 2-week / 4-week execution sequence
@@ -64,6 +70,8 @@ When explaining the tool to a user:
 - 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`
+- if the user wants the next agent to start executing, move them to `apply-plan`
+- if the user wants a closeout summary after one round, move them to `completion-report`
 - if the user already has a report, move them to `fix-plan`, `owner-board`, or `roadmap`
 
 Read [references/usage-patterns.md](references/usage-patterns.md) when you need response patterns and command selection examples.

package/resources/geo-ai-search-optimization-usage/references/usage-patterns.md

@@ -59,6 +59,34 @@ If they only have a URL:
 npx geo-ai-search-optimization agent-handoff https://example.com
 ```
 
+## If the user says "我想让 agent 直接开始执行"
+
+Recommend:
+
+```bash
+npx geo-ai-search-optimization apply-plan ./your-site
+```
+
+If they only have a URL:
+
+```bash
+npx geo-ai-search-optimization apply-plan https://example.com
+```
+
+## If the user says "我想看这一轮做完后的复盘"
+
+Recommend:
+
+```bash
+npx geo-ai-search-optimization completion-report ./your-site
+```
+
+If they only have a URL:
+
+```bash
+npx geo-ai-search-optimization completion-report https://example.com
+```
+
 ## If the user says "我要开会同步"
 
 Recommend:

package/src/apply-plan.js

@@ -0,0 +1,303 @@
+import { createAgentHandoff, writeAgentHandoffOutput } from "./agent-handoff.js";
+
+const VALID_FORMATS = new Set(["markdown", "json"]);
+
+function normalizeFormat(format) {
+  const resolved = (format || "markdown").toLowerCase();
+  if (!VALID_FORMATS.has(resolved)) {
+    throw new Error(`不支持的 apply-plan 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+function slugifyTaskTitle(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/gi, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function inferExecutionType(mode) {
+  if (mode === "implementation-ready") {
+    return "direct-fix";
+  }
+  if (mode === "advice-only") {
+    return "recommendation-only";
+  }
+  return "guided-planning";
+}
+
+function buildInspectTargets(task, mode) {
+  const targets = [];
+
+  if (mode === "implementation-ready") {
+    targets.push("站点全局 layout、SEO metadata helper、head 输出逻辑。");
+    targets.push("会影响该问题区域的可复用页面模板，而不是只看单页。");
+  } else {
+    targets.push("首页与最关键的 1 到 3 个落地页。");
+    targets.push("能体现该问题的模板类型、导航层级或内容模块。");
+  }
+
+  if (task.title.includes("robots.txt")) {
+    targets.push("robots.txt 生成逻辑、静态文件目录或部署输出目录。");
+  }
+  if (task.title.includes("sitemap")) {
+    targets.push("sitemap.xml 生成逻辑、路由清单或内容集合。");
+  }
+  if (task.title.includes("canonical")) {
+    targets.push("canonical 计算逻辑、metadata 映射层、URL 归一策略。");
+  }
+  if (task.title.includes("llms.txt")) {
+    targets.push("llms.txt 文件、站点导航概览、核心页面入口。");
+  }
+  if (task.title.includes("JSON-LD") || task.title.includes("schema")) {
+    targets.push("JSON-LD 输出逻辑、结构化数据模板、页面可见内容是否匹配。");
+  }
+  if (task.title.includes("meta description") || task.title.includes("标题")) {
+    targets.push("title / meta description 模板、字段来源、默认值与覆盖逻辑。");
+  }
+  if (task.title.includes("breadcrumb")) {
+    targets.push("站点层级、breadcrumb 组件或 breadcrumb schema 输出点。");
+  }
+
+  return Array.from(new Set(targets));
+}
+
+function buildEditPlan(task, mode) {
+  const steps = [];
+
+  if (mode === "implementation-ready") {
+    steps.push("先定位复用层，再判断是否能一次修复整类页面。");
+    steps.push("优先改模板、helper、内容模型或生成逻辑，避免只 patch 单页。");
+  } else if (mode === "advice-only") {
+    steps.push("先输出页面层、模板层、流程层三层建议。");
+    steps.push("把需要工程、SEO、内容团队补充的前置条件写清楚。");
+  } else {
+    steps.push("先把任务拆成可执行顺序，再明确哪一步需要代码仓库。");
+    steps.push("把实施前必须补齐的上下文列出来。");
+  }
+
+  steps.push(`围绕任务「${task.title}」设计最小可落地改动，不要把范围扩散到整站重构。`);
+  steps.push("完成后一定要回到验收标准，确认问题真的被修掉，而不是只做表面调整。");
+
+  return steps;
+}
+
+function buildValidationCommands(source, mode) {
+  if (mode === "implementation-ready") {
+    return [
+      `geo-ai-search-optimization audit ${source}`,
+      `geo-ai-search-optimization fix-plan ${source}`,
+      `geo-ai-search-optimization agent-handoff ${source}`
+    ];
+  }
+
+  if (mode === "advice-only") {
+    return [
+      `geo-ai-search-optimization onboard-url ${source}`,
+      `geo-ai-search-optimization pm-brief ${source}`,
+      `geo-ai-search-optimization report ${source} --mode onboarding --format markdown`
+    ];
+  }
+
+  return [
+    `geo-ai-search-optimization agent-handoff ${source}`,
+    `geo-ai-search-optimization meeting-pack ${source}`
+  ];
+}
+
+function buildDeliverables(task, executionType) {
+  const deliverables = [
+    "当前问题摘要",
+    "你检查过的页面、模板或文件",
+    "实际修改或建议动作",
+    "验收结果",
+    "下一步建议"
+  ];
+
+  if (executionType === "direct-fix") {
+    deliverables.push("修改后的验证结果和剩余风险");
+  } else if (executionType === "recommendation-only") {
+    deliverables.push("用户还需要提供的仓库、页面或权限");
+  } else {
+    deliverables.push("进入直接修复前的补充上下文清单");
+  }
+
+  return deliverables;
+}
+
+function buildCompletionTemplate(task, executionType) {
+  const closingLine =
+    executionType === "direct-fix"
+      ? "我已经完成可直接落地的部分，并附上复测结果。"
+      : executionType === "recommendation-only"
+        ? "我已经给出建议路径，下一步需要用户提供更多上下文后再继续落地。"
+        : "我已经把后续执行顺序整理好，待补齐仓库或页面上下文后可进入直接实施。";
+
+  return [
+    `任务：${task.title}`,
+    `结论：${closingLine}`,
+    "我先做了什么：",
+    "- ",
+    "我检查了哪些页面 / 文件 / 模板：",
+    "- ",
+    "我实际修改或建议了什么：",
+    "- ",
+    "验收结果：",
+    "- ",
+    "剩余风险或下一步：",
+    "- "
+  ].join("\n");
+}
+
+function buildExecutionPrompt(task, handoff, executionType, source) {
+  return [
+    "你现在进入 GEO 修复执行阶段。",
+    `任务：${task.title}`,
+    `执行类型：${executionType}`,
+    `输入来源：${source}`,
+    `本轮目标：${handoff.primaryObjective}`,
+    "请你按以下顺序输出：",
+    "1. 先检查什么",
+    "2. 你准备如何执行",
+    "3. 你会如何验证",
+    "4. 完成后如何向用户回报",
+    "",
+    "必须遵守：",
+    executionType === "direct-fix"
+      ? "如果已经有仓库访问权限，优先直接修复。"
+      : "如果没有仓库访问权限，不要假装已经完成代码修改。",
+    "输出要保持 PM 可读，同时明确技术执行动作。"
+  ].join("\n");
+}
+
+function buildGlobalWorkflow(mode) {
+  if (mode === "implementation-ready") {
+    return [
+      "先找复用模板和 metadata / schema 输出点。",
+      "按优先级修复 1 到 3 个最高价值任务。",
+      "每完成一轮修改就复跑 GEO CLI 验证。"
+    ];
+  }
+  if (mode === "advice-only") {
+    return [
+      "先用当前网址确认最高优先级问题。",
+      "给出结构化建议，并说明需要哪些工程上下文。",
+      "拿到仓库后再切换到直接修复。"
+    ];
+  }
+  return [
+    "先用工件整理顺序和依赖关系。",
+    "确认哪些任务可先给建议，哪些任务必须等仓库。",
+    "当用户补充仓库后，转成 implementation-ready 再执行。"
+  ];
+}
+
+export async function createApplyPlan(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const handoff = await createAgentHandoff(input, { format: "json" });
+  const executionType = inferExecutionType(handoff.executionMode);
+  const requestedTaskId = options.taskId || null;
+  const selectedTasks = requestedTaskId
+    ? handoff.tasks.filter((task) => task.id === requestedTaskId)
+    : handoff.tasks.slice(0, 3);
+
+  if (selectedTasks.length === 0) {
+    throw new Error(`找不到任务：${requestedTaskId}`);
+  }
+
+  const executionPackets = selectedTasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    packetSlug: `${task.id}-${slugifyTaskTitle(task.title)}`,
+    priority: task.priority,
+    owner: task.owner,
+    executionType,
+    inspectTargets: buildInspectTargets(task, handoff.executionMode),
+    editPlan: buildEditPlan(task, handoff.executionMode),
+    validationCommands: buildValidationCommands(handoff.source, handoff.executionMode),
+    deliverables: buildDeliverables(task, executionType),
+    doneWhen: task.acceptanceCriteria,
+    completionTemplate: buildCompletionTemplate(task, executionType),
+    executionPrompt: buildExecutionPrompt(task, handoff, executionType, handoff.source)
+  }));
+
+  return {
+    kind: "geo-apply-plan",
+    source: handoff.source,
+    sourceType: handoff.sourceType,
+    format,
+    executionMode: handoff.executionMode,
+    executionType,
+    summary: handoff.summary,
+    primaryObjective: handoff.primaryObjective,
+    workflow: buildGlobalWorkflow(handoff.executionMode),
+    selectedTaskCount: executionPackets.length,
+    packets: executionPackets
+  };
+}
+
+export function renderApplyPlanMarkdown(plan) {
+  const lines = [
+    "# GEO Apply Plan",
+    "",
+    `- 输入来源：\`${plan.source}\``,
+    `- 来源类型：\`${plan.sourceType}\``,
+    `- 执行模式：\`${plan.executionMode}\``,
+    `- 执行类型：\`${plan.executionType}\``,
+    `- 当前总结：${plan.summary}`,
+    `- 本轮目标：${plan.primaryObjective}`,
+    "",
+    "## 全局执行顺序",
+    ""
+  ];
+
+  for (const step of plan.workflow) {
+    lines.push(`- ${step}`);
+  }
+
+  lines.push("", "## 执行包", "");
+
+  for (const packet of plan.packets) {
+    lines.push(`### ${packet.id}｜${packet.title}`);
+    lines.push("");
+    lines.push(`- 负责人：${packet.owner}`);
+    lines.push(`- 执行类型：${packet.executionType}`);
+    lines.push(`- 包标识：\`${packet.packetSlug}\``);
+    lines.push("- 先检查：");
+    for (const target of packet.inspectTargets) {
+      lines.push(`  - ${target}`);
+    }
+    lines.push("- 执行步骤：");
+    for (const step of packet.editPlan) {
+      lines.push(`  - ${step}`);
+    }
+    lines.push("- 验证指令：");
+    for (const command of packet.validationCommands) {
+      lines.push(`  - \`${command}\``);
+    }
+    lines.push("- 交付物：");
+    for (const deliverable of packet.deliverables) {
+      lines.push(`  - ${deliverable}`);
+    }
+    lines.push("- Done 定义：");
+    for (const criterion of packet.doneWhen) {
+      lines.push(`  - ${criterion}`);
+    }
+    lines.push("- 执行提示词：");
+    lines.push("```text");
+    lines.push(packet.executionPrompt);
+    lines.push("```");
+    lines.push("- 完成回报模板：");
+    lines.push("```text");
+    lines.push(packet.completionTemplate);
+    lines.push("```");
+    lines.push("");
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeApplyPlanOutput(outputPath, content) {
+  return writeAgentHandoffOutput(outputPath, content);
+}

package/src/cli.js

@@ -1,7 +1,13 @@
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "./apply-plan.js";
 import { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
+import {
+  createCompletionReport,
+  renderCompletionReportMarkdown,
+  writeCompletionReportOutput
+} from "./completion-report.js";
 import { installSkill } from "./install-skill.js";
 import { getBundledSkillPath, getInstalledSkillPath, getSkillName, getSkillsDir } from "./paths.js";
 import { renderScanMarkdown, scanProject, writeScanOutput } from "./scan.js";
@@ -54,6 +60,8 @@ function printHelp() {
       "  geo-ai-search-optimization init-schema <type> [target-dir] [--site-url <url>] [--overwrite] [--json]",
       "  geo-ai-search-optimization audit <project-path> [--json] [--out <file>] [--max-file-size <bytes>] [--max-examples <count>]",
       "  geo-ai-search-optimization agent-handoff <input> [--format <markdown|json>] [--out <file>]",
+      "  geo-ai-search-optimization apply-plan <input> [--task <id>] [--format <markdown|json>] [--out <file>]",
+      "  geo-ai-search-optimization completion-report <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization exec-summary <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization fix-plan <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization owner-board <input> [--format <markdown|json>] [--out <file>]",
@@ -360,6 +368,55 @@ async function handleAgentHandoff(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleApplyPlan(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("apply-plan 需要一个输入值，可以是项目路径、网站网址或已导出的 JSON 报告");
+  }
+
+  const format = getFlagValue(args, "--format");
+  const plan = await createApplyPlan(input, {
+    format,
+    taskId: getFlagValue(args, "--task")
+  });
+  const outputJson = format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(plan, null, 2)}\n`
+    : renderApplyPlanMarkdown(plan);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeApplyPlanOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 apply plan：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
+async function handleCompletionReport(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("completion-report 需要一个输入值，可以是项目路径、网站网址或已导出的 JSON 工件");
+  }
+
+  const format = getFlagValue(args, "--format");
+  const report = await createCompletionReport(input, { format });
+  const outputJson = format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(report, null, 2)}\n`
+    : renderCompletionReportMarkdown(report);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeCompletionReportOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 completion report：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 async function handleExecSummary(args) {
   const input = args.find((value) => !value.startsWith("-"));
   if (!input) {
@@ -538,6 +595,16 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "apply-plan") {
+    await handleApplyPlan(rest);
+    return;
+  }
+
+  if (command === "completion-report") {
+    await handleCompletionReport(rest);
+    return;
+  }
+
   if (command === "exec-summary") {
     await handleExecSummary(rest);
     return;

package/src/completion-report.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createApplyPlan, writeApplyPlanOutput } from "./apply-plan.js";
+
+const VALID_FORMATS = new Set(["markdown", "json"]);
+
+function normalizeFormat(format) {
+  const resolved = (format || "markdown").toLowerCase();
+  if (!VALID_FORMATS.has(resolved)) {
+    throw new Error(`不支持的 completion-report 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isUrlInput(input) {
+  return /^https?:\/\//i.test(input);
+}
+
+function inferProgressStatus(plan) {
+  if (plan.executionType === "direct-fix") {
+    return "已进入执行与验证阶段";
+  }
+  if (plan.executionType === "recommendation-only") {
+    return "已完成建议输出，待补仓库上下文";
+  }
+  return "已完成计划整理，待进入直接实施";
+}
+
+function buildCompletedThisRound(plan) {
+  if (plan.executionType === "direct-fix") {
+    return [
+      "已整理本轮最优先执行的任务包。",
+      "已明确每个任务先检查哪些模板、页面或系统。",
+      "已为每个任务准备验证命令与完成回报模板。"
+    ];
+  }
+  if (plan.executionType === "recommendation-only") {
+    return [
+      "已确认当前网址级问题与首批建议任务。",
+      "已准备好建议型执行包，避免在没有仓库时误报已修复。",
+      "已整理下一步需要用户提供的仓库或页面上下文。"
+    ];
+  }
+  return [
+    "已把现有工件整理成执行顺序。",
+    "已明确哪些任务可先建议，哪些需要仓库后再落地。",
+    "已为下一阶段实施准备验证与回报结构。"
+  ];
+}
+
+function buildResidualRisks(plan) {
+  if (plan.executionType === "direct-fix") {
+    return [
+      "如果只修单页、不修模板，问题可能会在其他页面重复出现。",
+      "如果修完后没有重跑 GEO CLI，团队无法确认问题是否真正下降。",
+      "如果结构化数据与页面可见内容不一致，可能造成新的理解偏差。"
+    ];
+  }
+  if (plan.executionType === "recommendation-only") {
+    return [
+      "当前仍缺少代码仓库或 CMS 上下文，暂时不能确认修复会落在哪些模板。",
+      "如果只停留在建议层，没有工程落地，问题不会真正消失。",
+      "仅凭首页和公开页面可能无法覆盖深层模板问题。"
+    ];
+  }
+  return [
+    "当前还是工件驱动阶段，尚未确认具体模板或文件路径。",
+    "没有仓库权限前，无法验证修复动作是否会影响整类页面。",
+    "如果不补齐上下文，执行顺序再清楚也无法进入真正落地。"
+  ];
+}
+
+function buildNextRoundTasks(plan) {
+  return plan.packets.map((packet) => ({
+    id: packet.id,
+    title: packet.title,
+    owner: packet.owner,
+    nextAction:
+      plan.executionType === "direct-fix"
+        ? "按执行包完成修改并立刻复测。"
+        : plan.executionType === "recommendation-only"
+          ? "先补仓库或页面上下文，再把建议转成直接实施。"
+          : "先补上下文，再切到 implementation-ready 模式执行。",
+    doneWhen: packet.doneWhen
+  }));
+}
+
+function buildManagementSummary(plan) {
+  if (plan.executionType === "direct-fix") {
+    return "团队已经具备直接执行条件，重点是尽快完成首批高优先级修复并验证结果。";
+  }
+  if (plan.executionType === "recommendation-only") {
+    return "当前更适合先完成建议与对齐，拿到仓库或 CMS 访问后再进入正式修复。";
+  }
+  return "当前已经明确下一轮执行顺序，但仍需要额外上下文才能真正进入修复。";
+}
+
+async function resolveApplyPlan(input) {
+  if (!input) {
+    throw new Error("completion-report 需要一个输入值，可以是项目路径、网站网址或已导出的 JSON 工件。");
+  }
+
+  if (isUrlInput(input)) {
+    return createApplyPlan(input, { format: "json" });
+  }
+
+  const resolvedPath = path.resolve(input);
+  const exists = await pathExists(resolvedPath);
+  if (!exists) {
+    return createApplyPlan(input, { format: "json" });
+  }
+
+  const stat = await fs.stat(resolvedPath);
+  if (stat.isDirectory()) {
+    return createApplyPlan(resolvedPath, { format: "json" });
+  }
+
+  const raw = await fs.readFile(resolvedPath, "utf8");
+  const parsed = JSON.parse(raw);
+
+  if (parsed.kind === "geo-apply-plan") {
+    return parsed;
+  }
+
+  return createApplyPlan(resolvedPath, { format: "json" });
+}
+
+export async function createCompletionReport(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const plan = await resolveApplyPlan(input);
+
+  return {
+    kind: "geo-completion-report",
+    source: plan.source,
+    sourceType: plan.sourceType,
+    format,
+    executionMode: plan.executionMode,
+    executionType: plan.executionType,
+    progressStatus: inferProgressStatus(plan),
+    summary: plan.summary,
+    managementSummary: buildManagementSummary(plan),
+    completedThisRound: buildCompletedThisRound(plan),
+    residualRisks: buildResidualRisks(plan),
+    nextRoundTasks: buildNextRoundTasks(plan),
+    validationChecklist: Array.from(new Set(plan.packets.flatMap((packet) => packet.validationCommands))),
+    completionTemplates: plan.packets.map((packet) => ({
+      id: packet.id,
+      title: packet.title,
+      template: packet.completionTemplate
+    }))
+  };
+}
+
+export function renderCompletionReportMarkdown(report) {
+  const lines = [
+    "# GEO Completion Report",
+    "",
+    `- 输入来源：\`${report.source}\``,
+    `- 来源类型：\`${report.sourceType}\``,
+    `- 执行模式：\`${report.executionMode}\``,
+    `- 执行类型：\`${report.executionType}\``,
+    `- 当前进度：${report.progressStatus}`,
+    `- 当前总结：${report.summary}`,
+    `- 管理层摘要：${report.managementSummary}`,
+    "",
+    "## 本轮已完成",
+    ""
+  ];
+
+  for (const item of report.completedThisRound) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push("", "## 剩余风险", "");
+  for (const risk of report.residualRisks) {
+    lines.push(`- ${risk}`);
+  }
+
+  lines.push("", "## 下一轮任务", "");
+  for (const task of report.nextRoundTasks) {
+    lines.push(`### ${task.id}｜${task.title}`);
+    lines.push("");
+    lines.push(`- 负责人：${task.owner}`);
+    lines.push(`- 下一步：${task.nextAction}`);
+    lines.push("- 完成标准：");
+    for (const criterion of task.doneWhen) {
+      lines.push(`  - ${criterion}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## 建议复测指令", "");
+  for (const command of report.validationChecklist) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push("", "## 完成回报模板", "");
+  for (const template of report.completionTemplates) {
+    lines.push(`### ${template.id}｜${template.title}`);
+    lines.push("```text");
+    lines.push(template.template);
+    lines.push("```");
+    lines.push("");
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeCompletionReportOutput(outputPath, content) {
+  return writeApplyPlanOutput(outputPath, content);
+}

package/src/index.js

@@ -5,7 +5,9 @@ export {
   runInteractiveOnboarding,
   writeInteractiveOnboardingOutput
 } from "./interactive-onboarding.js";
+export { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "./apply-plan.js";
 export { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
+export { createCompletionReport, renderCompletionReportMarkdown, writeCompletionReportOutput } from "./completion-report.js";
 export { createFixPlan, renderFixPlanMarkdown, writeFixPlanOutput } from "./fix-plan.js";
 export { installSkill } from "./install-skill.js";
 export { runCli } from "./cli.js";

package/src/quick-start.js

@@ -58,7 +58,9 @@ function buildSteps() {
       goal: "让 PM、工程、内容、SEO 各自知道先做什么。",
       commands: [
         "geo-ai-search-optimization fix-plan ./your-site --out ./reports/fix-plan.md",
-        "geo-ai-search-optimization agent-handoff ./your-site --out ./reports/agent-handoff.md"
+        "geo-ai-search-optimization agent-handoff ./your-site --out ./reports/agent-handoff.md",
+        "geo-ai-search-optimization apply-plan ./your-site --out ./reports/apply-plan.md",
+        "geo-ai-search-optimization completion-report ./your-site --out ./reports/completion-report.md"
       ]
     },
     {