geo-ai-search-optimization 1.2.8 → 1.2.9

package/README.md

@@ -81,6 +81,28 @@ geo-ai-search-optimization agent-session ./reports/apply-plan.json --json
 - 每一步的目的与预期产物
 - 可直接复制给 agent 的 session prompt
 
+## Agent Runbook 命令
+
+如果你希望 agent 拿到的不只是会话步骤，而是一份更稳定的执行手册和检查清单，可以直接用 `agent-runbook`：
+
+```bash
+geo-ai-search-optimization agent-runbook "我想把这份 GEO 结果交给下一个 agent 继续修"
+geo-ai-search-optimization agent-runbook https://example.com
+geo-ai-search-optimization agent-runbook ./your-site
+geo-ai-search-optimization agent-runbook ./reports/apply-plan.json --json
+```
+
+它会输出：
+
+- 开始前检查
+- 工作规则
+- 需要停下来的情况
+- 命令执行清单
+- 重点执行包
+- 验证清单
+- 回报清单
+- 可直接复制给 agent 的 runbook prompt
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -476,6 +498,7 @@ geo-ai-search-optimization install
 geo-ai-search-optimization install --target ./tmp/custom-skills --json
 geo-ai-search-optimization auto-flow "audit this site and tell me the next skill"
 geo-ai-search-optimization agent-session ./your-site
+geo-ai-search-optimization agent-runbook ./your-site
 geo-ai-search-optimization skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -532,6 +555,13 @@ geo-ai-search-optimization help
 - 新增 `geo-ai-search-optimization-agent-session` skill
 - 更适合把 GEO 任务直接交给下一个 agent 连续推进
 
+## New in 1.2.9
+
+- 新增 `agent-runbook` 命令
+- 把 `agent-session` 继续推进成给 agent 使用的执行手册和检查清单
+- 输出开始前检查、工作规则、停止条件、验证清单、回报清单
+- 新增 `geo-ai-search-optimization-agent-runbook` skill
+
 ## New in 1.2.5
 
 - 新增 `publish-pack`
@@ -715,10 +745,21 @@ Override with:
 
 ## Resource contents
 
-The installed package now includes two bundled skills:
+The installed package now includes a bundled GEO skill pack, including:
 
 - `geo-ai-search-optimization`
+- `geo-ai-search-optimization-auto-flow`
+- `geo-ai-search-optimization-agent-session`
+- `geo-ai-search-optimization-agent-runbook`
 - `geo-ai-search-optimization-usage`
+- `geo-ai-search-optimization-agent-handoff`
+- `geo-ai-search-optimization-repair-loop`
+- `geo-ai-search-optimization-completion-report`
+- `geo-ai-search-optimization-handoff-bundle`
+- `geo-ai-search-optimization-share-pack`
+- `geo-ai-search-optimization-export-pack`
+- `geo-ai-search-optimization-html-pack`
+- `geo-ai-search-optimization-publish-pack`
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "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

@@ -42,6 +42,16 @@ Best for:
 - giving the next agent a first command, second command, and expected artifact list
 - reducing ambiguity at handoff time
 
+### `geo-ai-search-optimization-agent-runbook`
+
+Use this when the next agent needs an execution manual, not just a session sequence.
+
+Best for:
+
+- turning a GEO session into a checklist-driven runbook
+- telling the next agent what to check before acting
+- defining stop conditions, validation checklist, and reporting checklist
+
 ## Usage guide
 
 ### `geo-ai-search-optimization-usage`

package/resources/geo-ai-search-optimization-agent-runbook/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: geo-ai-search-optimization-agent-runbook
+description: Turn a GEO input into an execution runbook for the next agent. Use when an agent needs more than routing or a session plan, and should receive a checklist-driven manual with preflight checks, stop conditions, validation steps, reporting expectations, and optional execution packets.
+---
+
+# GEO Agent Runbook
+
+Use this skill when the next agent should receive a practical runbook, not just a list of commands.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- turn a GEO input into a checklist-driven execution manual
+- define what to check before acting
+- define what should stop execution
+- define how validation and reporting should work
+- carry the next agent from session planning into disciplined execution
+
+## Best use
+
+- when `agent-session` is still too light and the next agent needs a more operational checklist
+- when a PM or another agent wants a stable “follow this runbook” artifact
+- when execution needs preflight, validation, and reporting rules

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Runbook"
+  short_description: "Build a checklist-driven GEO execution manual"
+  default_prompt: "Use $geo-ai-search-optimization-agent-runbook to turn this input into a GEO runbook with preflight checks, execution checklist, validation steps, and reporting guidance."

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

@@ -13,23 +13,24 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as fifteen layers:
+The package is best explained as sixteen layers:
 
 1. `auto-flow`: auto-select the next skill and command chain
 2. `agent-session`: build a runnable session for the next agent
-3. `skills`: inspect the bundled skill package
-4. `onboard-url` / `onboard`: first look
-5. `scan`: raw signal check
-6. `audit` / `report`: diagnosis
-7. `fix-plan` / `owner-board`: execution planning
-8. `agent-handoff`: agent takeover package
-9. `apply-plan`: execution loop
-10. `completion-report`: closeout
-11. `handoff-bundle`: all-in-one package
-12. `share-pack`: audience-ready delivery
-13. `export-pack`: folder export
-14. `html-pack` / `publish-pack`: browsable and final delivery output
-15. `pm-brief` / `roadmap`: stakeholder alignment
+3. `agent-runbook`: execution manual and checklist for the next agent
+4. `skills`: inspect the bundled skill package
+5. `onboard-url` / `onboard`: first look
+6. `scan`: raw signal check
+7. `audit` / `report`: diagnosis
+8. `fix-plan` / `owner-board`: execution planning
+9. `agent-handoff`: agent takeover package
+10. `apply-plan`: execution loop
+11. `completion-report`: closeout
+12. `handoff-bundle`: all-in-one package
+13. `share-pack`: audience-ready delivery
+14. `export-pack`: folder export
+15. `html-pack` / `publish-pack`: browsable and final delivery output
+16. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -38,6 +39,7 @@ If the user only has a website URL:
 ```bash
 npx geo-ai-search-optimization auto-flow https://example.com
 npx geo-ai-search-optimization agent-session https://example.com
+npx geo-ai-search-optimization agent-runbook 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
@@ -48,6 +50,7 @@ If the user has the website codebase:
 ```bash
 npx geo-ai-search-optimization auto-flow ./your-site
 npx geo-ai-search-optimization agent-session ./your-site
+npx geo-ai-search-optimization agent-runbook ./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
@@ -67,6 +70,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 
 - `auto-flow`: auto-select the next skill and command order from a task brief, URL, project path, or GEO artifact
 - `agent-session`: build a step-by-step session packet for the next agent from the same kinds of inputs
+- `agent-runbook`: build a checklist-driven runbook with preflight, validation, and reporting rules
 - `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
@@ -93,6 +97,7 @@ When explaining the tool to a user:
 - prefer telling them which command to run next, not listing every command
 - if the user or the next agent is unsure where to start, move them to `auto-flow` first
 - if the user wants something the next agent can follow step by step, move them to `agent-session`
+- if the user wants the next agent to follow a checklist and execution manual, move them to `agent-runbook`
 - 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-runbook.js

@@ -0,0 +1,438 @@
+import { readFile } from "node:fs/promises";
+import { createApplyPlan } from "./apply-plan.js";
+import { createAgentSession } from "./agent-session.js";
+import { writeScanOutput } from "./scan.js";
+
+const VALID_FORMATS = new Set(["markdown", "json"]);
+
+function normalizeFormat(format) {
+  const resolved = (format || "markdown").toLowerCase();
+  if (!VALID_FORMATS.has(resolved)) {
+    throw new Error(`不支持的 agent-runbook 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+async function tryCreateExecutionPlan(input, options, session) {
+  if (session.sourceType === "json" && session.artifactKind === "geo-apply-plan") {
+    const parsed = JSON.parse(await readFile(input, "utf8"));
+    if (parsed?.kind === "geo-apply-plan") {
+      return parsed;
+    }
+  }
+
+  if (session.sourceType === "task-text" || session.intent === "guide") {
+    return null;
+  }
+
+  try {
+    return await createApplyPlan(input, {
+      format: "json",
+      taskId: options.taskId
+    });
+  } catch {
+    return null;
+  }
+}
+
+function inferRunbookMode(session, executionPlan) {
+  if (session.intent === "share") {
+    return "delivery-support";
+  }
+  if (session.intent === "closeout") {
+    return "closeout-support";
+  }
+  if (executionPlan?.executionType === "direct-fix") {
+    return "hands-on-fix";
+  }
+  if (executionPlan?.executionType === "recommendation-only") {
+    return "advisory-runbook";
+  }
+  if (executionPlan?.executionType === "guided-planning") {
+    return "guided-preparation";
+  }
+  if (session.intent === "execute") {
+    return "execution-preparation";
+  }
+  return "diagnostic-runbook";
+}
+
+function buildModeSummary(mode) {
+  switch (mode) {
+    case "hands-on-fix":
+      return "当前已经接近可直接动手修复的状态，runbook 应优先帮助 agent 在仓库里按检查表推进。";
+    case "advisory-runbook":
+      return "当前更适合输出结构化建议和修复手册，不要假装已经拥有仓库写入权限。";
+    case "guided-preparation":
+      return "当前已有部分执行工件，但还需要一个更稳定的执行手册来控制顺序和验收。";
+    case "delivery-support":
+      return "当前重点是把 GEO 结果整理成交付物，而不是重新做大范围诊断。";
+    case "closeout-support":
+      return "当前重点是整理完成情况、剩余风险和下一轮动作。";
+    case "execution-preparation":
+      return "当前需要把诊断结果继续推进成 agent 可执行的链路和检查表。";
+    default:
+      return "当前仍以诊断和建立执行方向为主，runbook 用于稳定下一步顺序。";
+  }
+}
+
+function buildPreflightChecklist(session, executionPlan, mode) {
+  const items = [
+    `确认当前输入 \`${session.source}\` 是最新的，而不是过期工件。`,
+    `确认这轮目标仍然是：${session.goal}`
+  ];
+
+  if (session.sourceType === "directory") {
+    items.push("确认当前目录就是可编辑的网站项目根目录，并且可以运行 CLI 复测命令。");
+  } else if (session.sourceType === "url") {
+    items.push("确认当前只有公开网址可见，不要把线上观察误写成已经完成代码修改。");
+  } else if (session.sourceType === "json" || session.sourceType === "file") {
+    items.push("确认当前工件和目标站点版本一致，避免基于旧结果继续执行。");
+  }
+
+  if (executionPlan?.executionType === "direct-fix") {
+    items.push("开始前先找模板层、metadata helper、schema 输出点，不要一上来只 patch 单页。");
+  }
+
+  if (session.contextNeeded.length > 0) {
+    for (const item of session.contextNeeded) {
+      items.push(`补齐上下文：${item}`);
+    }
+  }
+
+  if (mode === "delivery-support") {
+    items.push("确认这轮重点是整理对外产物，不要重复打开无关的诊断分支。");
+  }
+
+  return items;
+}
+
+function buildOperatingRules(session, executionPlan, mode) {
+  const items = [
+    "所有输出都要保持 PM 可读，避免只给技术术语不给业务含义。",
+    "每完成一步，都说明为什么这样做、得到什么、下一步是什么。",
+    "优先修复可复用模板、metadata helper、schema 生成逻辑，而不是只修一页。",
+    "如果没有仓库或写入权限，不要声称已经完成代码修改。"
+  ];
+
+  if (executionPlan?.executionType === "direct-fix") {
+    items.push("每做完一轮修改，就要立刻复跑至少一条 GEO CLI 验证命令。");
+  }
+
+  if (mode === "delivery-support") {
+    items.push("交付阶段以整理和包装结果为主，不要在没有必要时重新定义优先级。");
+  }
+
+  if (mode === "closeout-support") {
+    items.push("收尾阶段必须清楚区分：已完成、未完成、待验证、下一轮任务。");
+  }
+
+  return items;
+}
+
+function buildStopConditions(session, executionPlan) {
+  const items = [
+    "找不到当前输入对应的网站、项目目录或工件，无法确认执行对象。",
+    "CLI 输出与当前假设冲突，例如问题区域和已有工件不一致。",
+    "无法给出明确验收标准时，不要继续扩大范围。"
+  ];
+
+  if (executionPlan?.executionType === "direct-fix") {
+    items.push("明明需要直接修复，但拿不到仓库、模板或关键文件时，应先停下并说明缺的上下文。");
+  }
+
+  if (session.sourceType === "url") {
+    items.push("只有网址没有仓库时，不要进入假想修复，应切回建议模式。");
+  }
+
+  return items;
+}
+
+function buildCommandChecklist(steps) {
+  return steps.map((step, index) => {
+    const doneWhen = [
+      `已经运行或明确评估：\`${step.command}\``,
+      `已经拿到或确认：${step.expectedArtifact}`,
+      "已经记录本步结论，并说明下一步是否需要继续"
+    ];
+
+    if (index === 0) {
+      doneWhen.push("已经确认第一步不是跑偏，而是符合当前会话阶段。");
+    }
+
+    return {
+      id: step.id,
+      command: step.command,
+      commandName: step.commandName,
+      suggestedSkill: step.suggestedSkill,
+      purpose: step.purpose,
+      expectedArtifact: step.expectedArtifact,
+      instructions: step.instructions,
+      doneWhen
+    };
+  });
+}
+
+function buildExecutionPackets(executionPlan) {
+  if (!executionPlan) {
+    return [];
+  }
+
+  return executionPlan.packets.map((packet) => ({
+    id: packet.id,
+    title: packet.title,
+    priority: packet.priority,
+    owner: packet.owner,
+    executionType: packet.executionType,
+    inspectTargets: packet.inspectTargets,
+    editPlan: packet.editPlan,
+    validationCommands: packet.validationCommands,
+    deliverables: packet.deliverables,
+    doneWhen: packet.doneWhen
+  }));
+}
+
+function buildValidationChecklist(session, executionPlan) {
+  const items = [];
+
+  if (executionPlan?.packets?.length) {
+    const commands = Array.from(
+      new Set(executionPlan.packets.flatMap((packet) => packet.validationCommands || []))
+    );
+    for (const command of commands) {
+      items.push(`复跑验证命令：\`${command}\``);
+    }
+  } else if (session.steps.length > 0) {
+    items.push(`至少重新确认第一条关键命令是否已达成预期：\`${session.steps[0].command}\``);
+  }
+
+  items.push("确认最高优先级问题是否真的下降，而不是只改变了表述。");
+  items.push("确认输出仍然能解释：哪里被修复、哪里还没修、下一步是什么。");
+
+  if (session.sourceType === "url") {
+    items.push("如果只有网址，验证重点应放在公开可观察信号和建议质量，而不是虚构代码变更。");
+  }
+
+  return items;
+}
+
+function buildReportingChecklist(session, executionPlan) {
+  const items = [
+    "总结这轮做了什么，按问题区域或任务包分组，而不是只贴命令输出。",
+    "明确剩余风险、未完成项和下一轮最该先做的 1 到 3 件事。",
+    "告诉用户下一位 agent 或下一轮流程应该从哪个命令继续。"
+  ];
+
+  if (executionPlan?.executionType === "direct-fix") {
+    items.push("回报时带上复测命令和结果，说明这次修复是否真的改变了 GEO 状态。");
+  } else {
+    items.push("回报时明确哪些建议还需要仓库、权限或更多页面上下文才能继续落地。");
+  }
+
+  if (session.intent === "share") {
+    items.push("如果这轮目标是交付，回报里要说明应该把结果发给谁，以及推荐使用哪个分享包。");
+  }
+
+  return items;
+}
+
+function buildNextCommands(session, executionPlan) {
+  if (session.intent === "share") {
+    return [
+      `geo-ai-search-optimization share-pack ${session.source}`,
+      `geo-ai-search-optimization publish-pack ${session.source}`
+    ];
+  }
+
+  if (session.intent === "closeout") {
+    return [
+      `geo-ai-search-optimization completion-report ${session.source}`,
+      `geo-ai-search-optimization handoff-bundle ${session.source}`
+    ];
+  }
+
+  if (executionPlan) {
+    return [
+      `geo-ai-search-optimization apply-plan ${session.source}`,
+      `geo-ai-search-optimization completion-report ${session.source}`
+    ];
+  }
+
+  return session.steps.slice(0, 2).map((step) => step.command);
+}
+
+function buildRunbookPrompt(session, runbookMode, executionPackets) {
+  const lines = [
+    `Use $geo-ai-search-optimization-agent-runbook to continue this GEO task.`,
+    `当前输入：${session.source}`,
+    `当前阶段：${session.stage}`,
+    `当前意图：${session.intent}`,
+    `runbook 模式：${runbookMode}`,
+    `目标：${session.goal}`,
+    "请按下面顺序推进：",
+    "1. 先执行开始前检查。",
+    "2. 再按命令执行清单推进。",
+    "3. 如果有重点执行包，优先做最高优先级那一包。",
+    "4. 每完成一轮动作，都做验证清单。",
+    "5. 最后按回报清单整理给用户的结果。"
+  ];
+
+  if (executionPackets.length > 0) {
+    lines.push("当前重点执行包：");
+    for (const packet of executionPackets) {
+      lines.push(`- ${packet.priority}｜${packet.title}`);
+    }
+  }
+
+  if (session.contextNeeded.length > 0) {
+    lines.push("如果上下文不足，必须先明确缺什么，再决定是否继续。");
+  }
+
+  return lines.join("\n");
+}
+
+export async function createAgentRunbook(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const session = await createAgentSession(input, {
+    intent: options.intent
+  });
+  const executionPlan = await tryCreateExecutionPlan(input, options, session);
+  const runbookMode = inferRunbookMode(session, executionPlan);
+  const commandChecklist = buildCommandChecklist(session.steps);
+  const executionPackets = buildExecutionPackets(executionPlan);
+
+  return {
+    kind: "geo-agent-runbook",
+    input,
+    source: session.source,
+    sourceType: session.sourceType,
+    artifactKind: session.artifactKind,
+    format,
+    intent: session.intent,
+    stage: session.stage,
+    status: session.status,
+    runbookMode,
+    modeSummary: buildModeSummary(runbookMode),
+    goal: session.goal,
+    selectedSkill: session.selectedSkill,
+    secondarySkills: session.secondarySkills,
+    whyThisSkill: session.whyThisSkill,
+    nextAction: session.nextAction,
+    preflightChecklist: buildPreflightChecklist(session, executionPlan, runbookMode),
+    operatingRules: buildOperatingRules(session, executionPlan, runbookMode),
+    stopConditions: buildStopConditions(session, executionPlan),
+    commandChecklist,
+    executionPackets,
+    validationChecklist: buildValidationChecklist(session, executionPlan),
+    reportingChecklist: buildReportingChecklist(session, executionPlan),
+    nextCommands: buildNextCommands(session, executionPlan),
+    runbookPrompt: buildRunbookPrompt(session, runbookMode, executionPackets),
+    agentSession: session,
+    applyPlan: executionPlan
+  };
+}
+
+export function renderAgentRunbookMarkdown(runbook) {
+  const lines = [
+    "# GEO Agent Runbook",
+    "",
+    `- 输入：\`${runbook.source}\``,
+    `- 输入类型：\`${runbook.sourceType}\``,
+    `- 工件类型：\`${runbook.artifactKind}\``,
+    `- 当前阶段：${runbook.stage}`,
+    `- 当前状态：${runbook.status}`,
+    `- runbook 模式：\`${runbook.runbookMode}\``,
+    `- 模式说明：${runbook.modeSummary}`,
+    `- 目标：${runbook.goal}`,
+    `- 当前主 skill：\`${runbook.selectedSkill.name}\``,
+    "",
+    "## 开始前检查",
+    ""
+  ];
+
+  for (const item of runbook.preflightChecklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 工作规则", "");
+  for (const item of runbook.operatingRules) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 需要停下来的情况", "");
+  for (const item of runbook.stopConditions) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 命令执行清单", "");
+  for (const item of runbook.commandChecklist) {
+    lines.push(`### ${item.id}｜${item.commandName}`, "");
+    lines.push(`- 命令：\`${item.command}\``);
+    lines.push(`- 建议 skill：\`${item.suggestedSkill}\``);
+    lines.push(`- 目的：${item.purpose}`);
+    lines.push(`- 预期产物：${item.expectedArtifact}`);
+    lines.push("- 操作说明：");
+    for (const instruction of item.instructions) {
+      lines.push(`  - ${instruction}`);
+    }
+    lines.push("- 完成标准：");
+    for (const doneWhen of item.doneWhen) {
+      lines.push(`  - [ ] ${doneWhen}`);
+    }
+    lines.push("");
+  }
+
+  if (runbook.executionPackets.length > 0) {
+    lines.push("## 重点执行包", "");
+    for (const packet of runbook.executionPackets) {
+      lines.push(`### ${packet.id}｜${packet.title}`, "");
+      lines.push(`- 优先级：${packet.priority}`);
+      lines.push(`- Owner：${packet.owner}`);
+      lines.push(`- 执行类型：\`${packet.executionType}\``);
+      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 item of packet.deliverables) {
+        lines.push(`  - ${item}`);
+      }
+      lines.push("- Done when：");
+      for (const item of packet.doneWhen) {
+        lines.push(`  - [ ] ${item}`);
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push("## 验证清单", "");
+  for (const item of runbook.validationChecklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 回报清单", "");
+  for (const item of runbook.reportingChecklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+
+  lines.push("", "## 下一步推荐命令", "");
+  for (const command of runbook.nextCommands) {
+    lines.push(`- \`${command}\``);
+  }
+
+  lines.push("", "## 可直接复制给 Agent 的 Runbook Prompt", "", "```text", runbook.runbookPrompt, "```");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentRunbookOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/agent-session.js

@@ -46,6 +46,9 @@ function inferSkillForCommand(commandName, flow) {
   if (commandName === "auto-flow") {
     return "geo-ai-search-optimization-auto-flow";
   }
+  if (commandName === "agent-runbook") {
+    return "geo-ai-search-optimization-agent-runbook";
+  }
   if (commandName === "skills" || commandName === "quick-start") {
     return "geo-ai-search-optimization-usage";
   }
@@ -106,6 +109,8 @@ function inferStepPurpose(commandName, flow) {
       return "把修复顺序转成阶段计划。";
     case "agent-handoff":
       return "把当前结果交接成 agent 可继续执行的工件。";
+    case "agent-runbook":
+      return "把当前链路整理成 agent 可照着执行的手册和检查表。";
     case "apply-plan":
       return "把交接结果推进到具体执行包。";
     case "completion-report":
@@ -146,6 +151,8 @@ function inferExpectedArtifact(commandName) {
       return "阶段路线图";
     case "agent-handoff":
       return "agent 交接工件";
+    case "agent-runbook":
+      return "agent 执行手册";
     case "apply-plan":
       return "执行包";
     case "completion-report":
@@ -178,6 +185,9 @@ function buildStepInstructions(parsedCommand, flow) {
   if (parsedCommand.commandName === "apply-plan") {
     lines.push("执行包出来后，优先从第一包开始，不要同时展开太多任务。");
   }
+  if (parsedCommand.commandName === "agent-runbook") {
+    lines.push("先用 runbook 稳定顺序、检查项和回报方式，再开始真正执行。");
+  }
   if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
     lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
   }

package/src/auto-flow.js

@@ -44,6 +44,9 @@ function inferTaskTextMode(text) {
   if (/(share-pack|export-pack|html-pack|publish-pack|分享|导出|交付|外发|报告包)/i.test(normalized)) {
     return "share";
   }
+  if (/(runbook|checklist|playbook|执行手册|检查清单|操作手册)/i.test(normalized)) {
+    return "execute";
+  }
   if (/(apply-plan|handoff|接手|交给.*agent|继续修|继续做|修复|执行|修改|落地|repair|implement|fix)/i.test(normalized)) {
     return "execute";
   }
@@ -147,7 +150,9 @@ function resolveEffectiveIntent(intent, detected) {
     return "share";
   }
   if (
-    ["geo-agent-handoff", "geo-apply-plan", "geo-handoff-bundle", "geo-fix-plan"].includes(detected.artifactKind)
+    ["geo-agent-handoff", "geo-agent-runbook", "geo-apply-plan", "geo-handoff-bundle", "geo-fix-plan"].includes(
+      detected.artifactKind
+    )
   ) {
     return "execute";
   }
@@ -197,7 +202,8 @@ function buildCommandChain(detected, intent) {
       return [
         `geo-ai-search-optimization onboard-url ${source}`,
         `geo-ai-search-optimization fix-plan ${source}`,
-        `geo-ai-search-optimization agent-handoff ${source}`
+        `geo-ai-search-optimization agent-handoff ${source}`,
+        `geo-ai-search-optimization agent-runbook ${source}`
       ];
     }
     return [
@@ -213,6 +219,7 @@ function buildCommandChain(detected, intent) {
         `geo-ai-search-optimization audit ${source}`,
         `geo-ai-search-optimization fix-plan ${source}`,
         `geo-ai-search-optimization agent-handoff ${source}`,
+        `geo-ai-search-optimization agent-runbook ${source}`,
         `geo-ai-search-optimization apply-plan ${source}`
       ];
     }
@@ -230,6 +237,7 @@ function buildCommandChain(detected, intent) {
         ? [
             `geo-ai-search-optimization fix-plan ${source}`,
             `geo-ai-search-optimization agent-handoff ${source}`,
+            `geo-ai-search-optimization agent-runbook ${source}`,
             `geo-ai-search-optimization apply-plan ${source}`
           ]
         : [`geo-ai-search-optimization fix-plan ${source}`, `geo-ai-search-optimization owner-board ${source}`];
@@ -243,15 +251,24 @@ function buildCommandChain(detected, intent) {
     case "geo-fix-plan":
       return [
         `geo-ai-search-optimization agent-handoff ${source}`,
+        `geo-ai-search-optimization agent-runbook ${source}`,
         `geo-ai-search-optimization apply-plan ${source}`
       ];
     case "geo-agent-handoff":
       return [
+        `geo-ai-search-optimization agent-runbook ${source}`,
         `geo-ai-search-optimization apply-plan ${source}`,
         `geo-ai-search-optimization completion-report ${source}`
       ];
+    case "geo-agent-runbook":
+      return [
+        `geo-ai-search-optimization apply-plan ${source}`,
+        `geo-ai-search-optimization completion-report ${source}`,
+        `geo-ai-search-optimization handoff-bundle ${source}`
+      ];
     case "geo-apply-plan":
       return [
+        `geo-ai-search-optimization agent-runbook ${source}`,
         `geo-ai-search-optimization apply-plan ${source}`,
         `geo-ai-search-optimization completion-report ${source}`,
         `geo-ai-search-optimization handoff-bundle ${source}`
@@ -313,10 +330,11 @@ function pickSkillName(detected, intent) {
     case "geo-report:onboarding":
       return intent === "execute" ? "geo-ai-search-optimization-agent-handoff" : "geo-ai-search-optimization";
     case "geo-fix-plan":
-    case "geo-agent-handoff":
       return "geo-ai-search-optimization-agent-handoff";
+    case "geo-agent-handoff":
+    case "geo-agent-runbook":
     case "geo-apply-plan":
-      return "geo-ai-search-optimization-repair-loop";
+      return "geo-ai-search-optimization-agent-runbook";
     case "geo-completion-report":
       return "geo-ai-search-optimization-completion-report";
     case "geo-handoff-bundle":
@@ -346,7 +364,11 @@ function buildSecondarySkillNames(primarySkill, intent, detected) {
     names.add("geo-ai-search-optimization-share-pack");
     names.add("geo-ai-search-optimization-publish-pack");
   }
-  if (intent === "execute" || ["geo-fix-plan", "geo-agent-handoff", "geo-apply-plan"].includes(detected.artifactKind)) {
+  if (
+    intent === "execute" ||
+    ["geo-fix-plan", "geo-agent-handoff", "geo-agent-runbook", "geo-apply-plan"].includes(detected.artifactKind)
+  ) {
+    names.add("geo-ai-search-optimization-agent-runbook");
     names.add("geo-ai-search-optimization-agent-handoff");
     names.add("geo-ai-search-optimization-repair-loop");
   }
@@ -369,11 +391,17 @@ function buildStage(intent, detected) {
     return "执行复盘";
   }
   if (intent === "execute") {
-    return ["geo-fix-plan", "geo-agent-handoff", "geo-apply-plan", "geo-handoff-bundle"].includes(detected.artifactKind)
+    return ["geo-fix-plan", "geo-agent-handoff", "geo-agent-runbook", "geo-apply-plan", "geo-handoff-bundle"].includes(
+      detected.artifactKind
+    )
       ? "Agent 执行"
       : "执行准备";
   }
-  if (["geo-fix-plan", "geo-agent-handoff", "geo-apply-plan", "geo-handoff-bundle"].includes(detected.artifactKind)) {
+  if (
+    ["geo-fix-plan", "geo-agent-handoff", "geo-agent-runbook", "geo-apply-plan", "geo-handoff-bundle"].includes(
+      detected.artifactKind
+    )
+  ) {
     return "Agent 执行";
   }
   return "诊断规划";

package/src/cli.js

@@ -3,6 +3,7 @@ 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 { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
 import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 import { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./auto-flow.js";
 import {
@@ -61,6 +62,7 @@ function printHelp() {
       "  geo-ai-search-optimization install [--target <dir>] [--json]",
       "  geo-ai-search-optimization auto-flow <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--json] [--out <file>]",
       "  geo-ai-search-optimization agent-session <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--json] [--out <file>]",
+      "  geo-ai-search-optimization agent-runbook <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -177,6 +179,33 @@ async function handleAgentSession(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentRunbook(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-runbook 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format");
+  const runbook = await createAgentRunbook(input, {
+    intent: getFlagValue(args, "--intent"),
+    format,
+    taskId: getFlagValue(args, "--task")
+  });
+  const outputJson = format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(runbook, null, 2)}\n`
+    : renderAgentRunbookMarkdown(runbook);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentRunbookOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent runbook：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 function handleWhere() {
   process.stdout.write(
     [
@@ -727,6 +756,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-runbook") {
+    await handleAgentRunbook(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 { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
+export { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
 export { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 export { createCompletionReport, renderCompletionReportMarkdown, writeCompletionReportOutput } from "./completion-report.js";
 export { createFixPlan, renderFixPlanMarkdown, writeFixPlanOutput } from "./fix-plan.js";

package/src/skills.js

@@ -6,6 +6,7 @@ const SKILL_ORDER = [
   "geo-ai-search-optimization",
   "geo-ai-search-optimization-auto-flow",
   "geo-ai-search-optimization-agent-session",
+  "geo-ai-search-optimization-agent-runbook",
   "geo-ai-search-optimization-usage",
   "geo-ai-search-optimization-agent-handoff",
   "geo-ai-search-optimization-repair-loop",
@@ -21,6 +22,7 @@ const SKILL_CATEGORY = {
   "geo-ai-search-optimization": "core",
   "geo-ai-search-optimization-auto-flow": "routing",
   "geo-ai-search-optimization-agent-session": "routing",
+  "geo-ai-search-optimization-agent-runbook": "execution",
   "geo-ai-search-optimization-usage": "guidance",
   "geo-ai-search-optimization-agent-handoff": "execution",
   "geo-ai-search-optimization-repair-loop": "execution",
@@ -154,6 +156,8 @@ export function renderBundledSkillsMarkdown(bundle) {
     "",
     "- 先看核心 GEO skill。",
     "- 如果 agent 需要自动选 skill，先跑 auto-flow。",
+    "- 如果要给 agent 明确步骤，继续进入 agent-session。",
+    "- 如果要给 agent 一份执行手册和检查表，再进入 agent-runbook。",
     "- 再看 usage skill，知道什么时候该跑哪个命令。",
     "- 如果要交给 agent 执行，再进入 handoff / apply / completion 这一条执行链。",
     "- 如果要产出给团队分发，再进入 share / export / html / publish 这一条交付链。",