geo-ai-search-optimization 1.2.7 → 1.2.8

package/README.md

@@ -61,6 +61,26 @@ geo-ai-search-optimization auto-flow ./reports/apply-plan.json --json
 - 建议命令顺序
 - 可直接复制给 agent 的 prompt
 
+## Agent Session 命令
+
+如果你希望不只是“选 skill”，而是直接产出一份给 agent 跟着执行的会话包，可以用 `agent-session`：
+
+```bash
+geo-ai-search-optimization agent-session "我想把这份 GEO 结果交给下一个 agent 继续修"
+geo-ai-search-optimization agent-session https://example.com
+geo-ai-search-optimization agent-session ./your-site
+geo-ai-search-optimization agent-session ./reports/apply-plan.json --json
+```
+
+它会输出：
+
+- 当前阶段与会话状态
+- 会话目标
+- 自动选择的 skill
+- 一步步该跑什么命令
+- 每一步的目的与预期产物
+- 可直接复制给 agent 的 session prompt
+
 ## Quick Start
 
 如果你要从 0 到 1 启动一个 GEO 项目，建议照这个顺序做。
@@ -455,6 +475,7 @@ geo-ai-search-optimization
 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 skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
@@ -504,6 +525,13 @@ geo-ai-search-optimization help
 - 输出推荐 skill、命令顺序与可直接复制给 agent 的 prompt
 - 新增 `geo-ai-search-optimization-auto-flow` skill，作为 agent 的自动路由入口
 
+## New in 1.2.8
+
+- 新增 `agent-session` 命令，生成给 agent 跟着执行的会话包
+- 在 `auto-flow` 之上补上步骤级说明、预期产物和 session prompt
+- 新增 `geo-ai-search-optimization-agent-session` skill
+- 更适合把 GEO 任务直接交给下一个 agent 连续推进
+
 ## New in 1.2.5
 
 - 新增 `publish-pack`

package/package.json

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

@@ -32,6 +32,16 @@ Best for:
 - turning one-line task briefs into a concrete command sequence
 - deciding whether the work should move into diagnosis, execution, closeout, or delivery
 
+### `geo-ai-search-optimization-agent-session`
+
+Use this when the next agent needs a runnable session plan, not just a routing answer.
+
+Best for:
+
+- turning `auto-flow` output into a step-by-step execution sequence
+- giving the next agent a first command, second command, and expected artifact list
+- reducing ambiguity at handoff time
+
 ## Usage guide
 
 ### `geo-ai-search-optimization-usage`

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

@@ -0,0 +1,24 @@
+---
+name: geo-ai-search-optimization-agent-session
+description: Turn a GEO input into a step-by-step agent session plan. Use when an agent should not only pick the next GEO skill, but also receive a runnable session sequence with step goals, expected artifacts, and a copyable session prompt.
+---
+
+# GEO Agent Session
+
+Use this skill when the next agent should receive a full GEO session plan instead of only a routing recommendation.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- choose the current GEO stage
+- choose the right next skill
+- build a step-by-step command sequence
+- explain what each step should produce
+- generate a copyable session prompt
+
+## Best use
+
+- start a new agent run from a URL, project directory, or GEO artifact
+- turn `auto-flow` output into an execution-ready session
+- hand another agent a clear “do this first, then this” sequence

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Session"
+  short_description: "Build a runnable GEO session for the next agent"
+  default_prompt: "Use $geo-ai-search-optimization-agent-session to turn this input into a runnable GEO agent session with step order, expected outputs, and a session prompt."

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

@@ -13,22 +13,23 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as fourteen layers:
+The package is best explained as fifteen layers:
 
 1. `auto-flow`: auto-select the next skill and command chain
-2. `skills`: inspect the bundled skill package
-3. `onboard-url` / `onboard`: first look
-4. `scan`: raw signal check
-5. `audit` / `report`: diagnosis
-6. `fix-plan` / `owner-board`: execution planning
-7. `agent-handoff`: agent takeover package
-8. `apply-plan`: execution loop
-9. `completion-report`: closeout
-10. `handoff-bundle`: all-in-one package
-11. `share-pack`: audience-ready delivery
-12. `export-pack`: folder export
-13. `html-pack` / `publish-pack`: browsable and final delivery output
-14. `pm-brief` / `roadmap`: stakeholder alignment
+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
 
 ## Recommended command order
 
@@ -36,6 +37,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 onboard-url https://example.com
 npx geo-ai-search-optimization pm-brief https://example.com
 npx geo-ai-search-optimization roadmap https://example.com
@@ -45,6 +47,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 scan ./your-site
 npx geo-ai-search-optimization audit ./your-site
 npx geo-ai-search-optimization fix-plan ./your-site
@@ -63,6 +66,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 ## When to recommend each command
 
 - `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
 - `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
@@ -88,6 +92,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`
 - 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-session.js

@@ -0,0 +1,297 @@
+import { createAutoFlow } from "./auto-flow.js";
+import { writeScanOutput } from "./scan.js";
+
+function inferSessionStatus(flow) {
+  if (flow.contextNeeded.length > 0) {
+    return "needs-context";
+  }
+  if (flow.intent === "share") {
+    return "delivery-ready";
+  }
+  if (flow.intent === "closeout") {
+    return "closeout-ready";
+  }
+  if (flow.intent === "execute") {
+    return "execution-ready";
+  }
+  return "analysis-ready";
+}
+
+function inferSessionGoal(flow) {
+  if (flow.intent === "share") {
+    return "把当前 GEO 结果整理成适合分享、外发或交接的产物。";
+  }
+  if (flow.intent === "closeout") {
+    return "整理本轮 GEO 执行结果、剩余风险和下一轮任务。";
+  }
+  if (flow.intent === "execute") {
+    return "把当前输入推进到 agent 可接手、可执行、可验证的 GEO 修复链。";
+  }
+  if (flow.intent === "guide") {
+    return "明确现在该用哪个 skill、该跑哪些命令，以及先后顺序。";
+  }
+  return "建立当前 GEO 状态、优先级和下一步执行方向。";
+}
+
+function parseCommand(command) {
+  const parts = String(command).trim().split(/\s+/);
+  const commandName = parts[1] || parts[0] || "";
+  return {
+    raw: command,
+    commandName
+  };
+}
+
+function inferSkillForCommand(commandName, flow) {
+  if (commandName === "auto-flow") {
+    return "geo-ai-search-optimization-auto-flow";
+  }
+  if (commandName === "skills" || commandName === "quick-start") {
+    return "geo-ai-search-optimization-usage";
+  }
+  if (["share-pack"].includes(commandName)) {
+    return "geo-ai-search-optimization-share-pack";
+  }
+  if (["export-pack"].includes(commandName)) {
+    return "geo-ai-search-optimization-export-pack";
+  }
+  if (["html-pack"].includes(commandName)) {
+    return "geo-ai-search-optimization-html-pack";
+  }
+  if (["publish-pack"].includes(commandName)) {
+    return "geo-ai-search-optimization-publish-pack";
+  }
+  if (["agent-handoff"].includes(commandName)) {
+    return "geo-ai-search-optimization-agent-handoff";
+  }
+  if (["apply-plan"].includes(commandName)) {
+    return "geo-ai-search-optimization-repair-loop";
+  }
+  if (["completion-report"].includes(commandName)) {
+    return "geo-ai-search-optimization-completion-report";
+  }
+  if (["handoff-bundle"].includes(commandName)) {
+    return "geo-ai-search-optimization-handoff-bundle";
+  }
+  if (["onboard", "onboard-url", "scan", "audit", "report", "fix-plan", "owner-board", "pm-brief", "roadmap", "meeting-pack", "exec-summary"].includes(commandName)) {
+    return flow.selectedSkill.name === "geo-ai-search-optimization-usage"
+      ? "geo-ai-search-optimization"
+      : flow.selectedSkill.name;
+  }
+  return flow.selectedSkill.name;
+}
+
+function inferStepPurpose(commandName, flow) {
+  switch (commandName) {
+    case "skills":
+      return "先理解当前技能包结构，避免 agent 选错链路。";
+    case "quick-start":
+      return "快速建立从 0 到 1 的执行顺序。";
+    case "onboard":
+    case "onboard-url":
+      return "先从网址或引导流程拿到首轮 GEO 判断。";
+    case "scan":
+      return "先做原始信号扫描，确认基础缺口。";
+    case "audit":
+      return "拿到分数、问题区域和优先级。";
+    case "report":
+      return "把当前结果整理成可读报告。";
+    case "fix-plan":
+      return "把诊断结果转成待办和优先级。";
+    case "owner-board":
+      return "把任务按角色拆开，方便 PM 与执行团队分工。";
+    case "pm-brief":
+      return "先给 PM 一个可快速理解的摘要。";
+    case "roadmap":
+      return "把修复顺序转成阶段计划。";
+    case "agent-handoff":
+      return "把当前结果交接成 agent 可继续执行的工件。";
+    case "apply-plan":
+      return "把交接结果推进到具体执行包。";
+    case "completion-report":
+      return "整理本轮完成项、剩余风险和下一轮动作。";
+    case "handoff-bundle":
+      return "把交接、执行与复盘整成一个总包。";
+    case "share-pack":
+      return "给不同角色生成可直接分享的视图。";
+    case "export-pack":
+      return "把分享结果导出成目录文件。";
+    case "html-pack":
+      return "把产物转成可浏览页面。";
+    case "publish-pack":
+      return "形成最终可交付包。";
+    default:
+      return "推进当前 GEO 会话到下一阶段。";
+  }
+}
+
+function inferExpectedArtifact(commandName) {
+  switch (commandName) {
+    case "onboard":
+    case "onboard-url":
+      return "网址级 onboarding 结果";
+    case "scan":
+      return "基础信号扫描结果";
+    case "audit":
+      return "GEO 审计结果";
+    case "report":
+      return "可读报告";
+    case "fix-plan":
+      return "待办清单与优先级";
+    case "owner-board":
+      return "角色分栏任务板";
+    case "pm-brief":
+      return "PM 摘要";
+    case "roadmap":
+      return "阶段路线图";
+    case "agent-handoff":
+      return "agent 交接工件";
+    case "apply-plan":
+      return "执行包";
+    case "completion-report":
+      return "复盘工件";
+    case "handoff-bundle":
+      return "执行总包";
+    case "share-pack":
+      return "角色化分享包";
+    case "export-pack":
+      return "导出目录";
+    case "html-pack":
+      return "HTML 页面包";
+    case "publish-pack":
+      return "最终可交付包";
+    default:
+      return "阶段性 GEO 输出";
+  }
+}
+
+function buildStepInstructions(parsedCommand, flow) {
+  const lines = [
+    `运行 \`${parsedCommand.raw}\`。`,
+    inferStepPurpose(parsedCommand.commandName, flow),
+    `预期得到：${inferExpectedArtifact(parsedCommand.commandName)}。`
+  ];
+
+  if (parsedCommand.commandName === "publish-pack") {
+    lines.push("完成后把 `START-HERE.md` 和 `AGENT-START.md` 当作最终入口。");
+  }
+  if (parsedCommand.commandName === "apply-plan") {
+    lines.push("执行包出来后，优先从第一包开始，不要同时展开太多任务。");
+  }
+  if (parsedCommand.commandName === "agent-handoff" && flow.intent === "execute") {
+    lines.push("如果还是 advice-only，说明还缺仓库或本地项目上下文。");
+  }
+
+  return lines;
+}
+
+function buildSessionPrompt(flow, steps) {
+  const lines = [
+    `Use $${flow.selectedSkill.name} to continue this GEO session.`,
+    `当前输入：${flow.source}`,
+    `当前阶段：${flow.stage}`,
+    `当前意图：${flow.intent}`,
+    `会话目标：${inferSessionGoal(flow)}`,
+    "请按下面顺序推进，不要跳步骤："
+  ];
+
+  for (const step of steps) {
+    lines.push(`${step.id}. ${step.command}`);
+  }
+
+  if (flow.contextNeeded.length > 0) {
+    lines.push("如果当前缺上下文，请先明确缺什么，不要假装已经完成执行。");
+  }
+
+  lines.push("每一步都要说明：你为什么做、得到什么、下一步是什么。");
+  return lines.join("\n");
+}
+
+export async function createAgentSession(input, options = {}) {
+  const flow = await createAutoFlow(input, { intent: options.intent });
+  const steps = flow.commandChain.map((command, index) => {
+    const parsedCommand = parseCommand(command);
+    return {
+      id: `step-${String(index + 1).padStart(2, "0")}`,
+      command,
+      commandName: parsedCommand.commandName,
+      suggestedSkill: inferSkillForCommand(parsedCommand.commandName, flow),
+      purpose: inferStepPurpose(parsedCommand.commandName, flow),
+      expectedArtifact: inferExpectedArtifact(parsedCommand.commandName),
+      instructions: buildStepInstructions(parsedCommand, flow)
+    };
+  });
+
+  return {
+    kind: "geo-agent-session",
+    input,
+    source: flow.source,
+    sourceType: flow.sourceType,
+    artifactKind: flow.artifactKind,
+    intent: flow.intent,
+    stage: flow.stage,
+    status: inferSessionStatus(flow),
+    goal: inferSessionGoal(flow),
+    selectedSkill: flow.selectedSkill,
+    secondarySkills: flow.secondarySkills,
+    whyThisSkill: flow.whyThisSkill,
+    contextNeeded: flow.contextNeeded,
+    nextAction: flow.nextAction,
+    steps,
+    sessionPrompt: buildSessionPrompt(flow, steps),
+    autoFlow: flow
+  };
+}
+
+export function renderAgentSessionMarkdown(session) {
+  const lines = [
+    "# GEO Agent Session",
+    "",
+    `- 输入：\`${session.source}\``,
+    `- 输入类型：\`${session.sourceType}\``,
+    `- 工件类型：\`${session.artifactKind}\``,
+    `- 当前阶段：${session.stage}`,
+    `- 会话状态：${session.status}`,
+    `- 当前意图：${session.intent}`,
+    `- 目标：${session.goal}`,
+    `- 自动选择的 skill：\`${session.selectedSkill.name}\``,
+    "",
+    "## 为什么这样安排",
+    "",
+    `- ${session.whyThisSkill}`,
+    "",
+    "## 下一步",
+    "",
+    `- ${session.nextAction}`
+  ];
+
+  if (session.contextNeeded.length > 0) {
+    lines.push("", "## 还缺什么", "");
+    for (const item of session.contextNeeded) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  lines.push("", "## 会话步骤", "");
+  for (const step of session.steps) {
+    lines.push(`### ${step.id}｜${step.commandName}`);
+    lines.push("");
+    lines.push(`- 命令：\`${step.command}\``);
+    lines.push(`- 建议 skill：\`${step.suggestedSkill}\``);
+    lines.push(`- 目的：${step.purpose}`);
+    lines.push(`- 预期产物：${step.expectedArtifact}`);
+    lines.push("- 操作说明：");
+    for (const instruction of step.instructions) {
+      lines.push(`  - ${instruction}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("", "## 可直接复制给 Agent 的 Session Prompt", "", "```text", session.sessionPrompt, "```");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentSessionOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

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 { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 import { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./auto-flow.js";
 import {
   createCompletionReport,
@@ -59,6 +60,7 @@ function printHelp() {
       "  geo-ai-search-optimization",
       "  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 skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -151,6 +153,30 @@ async function handleAutoFlow(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentSession(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-session 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
+  }
+
+  const session = await createAgentSession(input, {
+    intent: getFlagValue(args, "--intent")
+  });
+  const outputJson = hasFlag(args, "--json");
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(session, null, 2)}\n`
+    : renderAgentSessionMarkdown(session);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentSessionOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent-session 结果：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 function handleWhere() {
   process.stdout.write(
     [
@@ -696,6 +722,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-session") {
+    await handleAgentSession(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 { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 export { createCompletionReport, renderCompletionReportMarkdown, writeCompletionReportOutput } from "./completion-report.js";
 export { createFixPlan, renderFixPlanMarkdown, writeFixPlanOutput } from "./fix-plan.js";
 export { createHandoffBundle, renderHandoffBundleMarkdown, writeHandoffBundleOutput } from "./handoff-bundle.js";

package/src/skills.js

@@ -5,6 +5,7 @@ import { getPackageRoot } from "./paths.js";
 const SKILL_ORDER = [
   "geo-ai-search-optimization",
   "geo-ai-search-optimization-auto-flow",
+  "geo-ai-search-optimization-agent-session",
   "geo-ai-search-optimization-usage",
   "geo-ai-search-optimization-agent-handoff",
   "geo-ai-search-optimization-repair-loop",
@@ -19,6 +20,7 @@ const SKILL_ORDER = [
 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-usage": "guidance",
   "geo-ai-search-optimization-agent-handoff": "execution",
   "geo-ai-search-optimization-repair-loop": "execution",