geo-ai-search-optimization 1.2.17 → 1.2.18

package/README.md

@@ -42,6 +42,27 @@ geo-ai-search-optimization skills --json
 - agent 执行闭环相关 skills
 - 分享 / 导出 / 最终交付相关 skills
 
+## Agent Orchestrator 命令
+
+如果你希望 agent 不要看长链路，而是直接拿到“现在唯一该跑哪条命令”，可以直接用 `agent-orchestrator`：
+
+```bash
+geo-ai-search-optimization agent-orchestrator "继续这个 GEO 任务"
+geo-ai-search-optimization agent-orchestrator https://example.com
+geo-ai-search-optimization agent-orchestrator ./your-site
+geo-ai-search-optimization agent-orchestrator ./reports/agent-playbook-pack.json --format json --out ./reports/agent-orchestrator.json
+```
+
+它会输出：
+
+- 当前阶段
+- 为什么现在该做这一步
+- 现在只该跑哪条命令
+- 预期产物
+- 什么时候先停下
+- 做完之后下一条是什么
+- 可直接复制给 agent 的 orchestrator prompt
+
 ## Auto Flow 命令
 
 如果你希望 agent 不用自己判断现在该用哪个 skill、该跑哪个命令，可以直接用 `auto-flow`：
@@ -660,6 +681,7 @@ geo-ai-search-optimization onboard --url https://example.com --json --out ./repo
 geo-ai-search-optimization
 geo-ai-search-optimization install
 geo-ai-search-optimization install --target ./tmp/custom-skills --json
+geo-ai-search-optimization agent-orchestrator ./your-site
 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
@@ -741,6 +763,14 @@ geo-ai-search-optimization help
 - 输出 do-now checklist、stop checklist、success checklist、验证命令和回报模板
 - 新增 `geo-ai-search-optimization-agent-executor` skill
 
+## New in 1.2.18
+
+- 新增 `agent-orchestrator`
+- 把 `auto-flow + agent-session` 收敛成一个“现在只该做哪条命令”的总入口
+- 输出固定 contract：`current_stage`、`why_now`、`next_command`、`expected_artifact`、`stop_if`、`after_that`
+- 更适合 PM 把任务直接交给 agent，或 agent 接着前一个工件继续做
+- 新增 `geo-ai-search-optimization-agent-orchestrator` skill
+
 ## New in 1.2.17
 
 - 新增 `agent-playbook-pack`
@@ -978,6 +1008,7 @@ 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-orchestrator`
 - `geo-ai-search-optimization-agent-session`
 - `geo-ai-search-optimization-agent-runbook`
 - `geo-ai-search-optimization-agent-executor`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.2.17",
+  "version": "1.2.18",
   "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-orchestrator`
+
+Use this when the next agent should get one immediate next command instead of reading a full command chain.
+
+Best for:
+
+- deciding the one command to run now
+- returning a short contract with expected artifact, stop conditions, and follow-up command
+- reducing ambiguity for PM-to-agent or agent-to-agent handoffs
+
 ### `geo-ai-search-optimization-agent-session`
 
 Use this when the next agent needs a runnable session plan, not just a routing answer.

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

@@ -0,0 +1,23 @@
+---
+name: geo-ai-search-optimization-agent-orchestrator
+description: Choose the one next GEO command an agent should run right now. Use when an agent, PM, or another workflow has a GEO URL, codebase, task brief, or artifact and wants a single next command, expected artifact, stop conditions, and follow-up command instead of a full chain.
+---
+
+# GEO Agent Orchestrator
+
+Use this skill when the next agent should not browse a long command chain.
+
+`GEO = Generative Engine Optimization`
+
+## What it does
+
+- turns a GEO input into one immediate next command
+- explains why this command should run now
+- shows what artifact should come out of that command
+- tells the next agent when to stop and what to run after that
+
+## Best use
+
+- when PM wants the next agent to start without reading the whole GEO stack
+- when another agent says "just tell me the next command"
+- when GEO work should continue from a URL, codebase, playbook pack, decision log, or other GEO artifact with minimal ambiguity

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Agent Orchestrator"
+  short_description: "Choose the one next GEO command to run now"
+  default_prompt: "Use $geo-ai-search-optimization-agent-orchestrator to pick the one next GEO command to run now, explain why, define the expected artifact, and list stop conditions plus the follow-up command."

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

@@ -13,38 +13,40 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as twenty-four layers:
-
-1. `auto-flow`: auto-select the next skill and command chain
-2. `agent-session`: build a runnable session for the next agent
-3. `agent-runbook`: execution manual and checklist for the next agent
-4. `agent-executor`: choose one packet to execute right now
-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. `agent-checkpoint`: freeze the current round into a continue / unblock / closeout decision
-9. `agent-decision-log`: preserve why each round continued, paused, or closed out
-10. `agent-retrospective`: explain multi-round patterns, lessons, and next-round advice
-11. `agent-playbook-pack`: compress retrospective, decision history, and handoff into one resume entrypoint
-12. `skills`: inspect the bundled skill package
-13. `onboard-url` / `onboard`: first look
-14. `scan`: raw signal check
-15. `audit` / `report`: diagnosis
-16. `fix-plan` / `owner-board`: execution planning
-17. `agent-handoff`: agent takeover package
-18. `apply-plan`: execution loop
-19. `completion-report`: closeout
-20. `handoff-bundle`: all-in-one package
-21. `share-pack`: audience-ready delivery
-22. `export-pack`: folder export
-23. `html-pack` / `publish-pack`: browsable and final delivery output
-24. `pm-brief` / `roadmap`: stakeholder alignment
+The package is best explained as twenty-five layers:
+
+1. `agent-orchestrator`: choose the one next GEO command to run right now
+2. `auto-flow`: auto-select the next skill and command chain
+3. `agent-session`: build a runnable session for the next agent
+4. `agent-runbook`: execution manual and checklist for the next agent
+5. `agent-executor`: choose one packet to execute right now
+6. `agent-batch-executor`: queue the first few packets, but still advance one packet at a time
+7. `agent-progress-tracker`: track which packet is done, which one is active, and what comes next
+8. `agent-status-board`: turn the execution state into a board view for PM and agents
+9. `agent-checkpoint`: freeze the current round into a continue / unblock / closeout decision
+10. `agent-decision-log`: preserve why each round continued, paused, or closed out
+11. `agent-retrospective`: explain multi-round patterns, lessons, and next-round advice
+12. `agent-playbook-pack`: compress retrospective, decision history, and handoff into one resume entrypoint
+13. `skills`: inspect the bundled skill package
+14. `onboard-url` / `onboard`: first look
+15. `scan`: raw signal check
+16. `audit` / `report`: diagnosis
+17. `fix-plan` / `owner-board`: execution planning
+18. `agent-handoff`: agent takeover package
+19. `apply-plan`: execution loop
+20. `completion-report`: closeout
+21. `handoff-bundle`: all-in-one package
+22. `share-pack`: audience-ready delivery
+23. `export-pack`: folder export
+24. `html-pack` / `publish-pack`: browsable and final delivery output
+25. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
 If the user only has a website URL:
 
 ```bash
+npx geo-ai-search-optimization agent-orchestrator https://example.com
 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
@@ -64,6 +66,7 @@ npx geo-ai-search-optimization roadmap https://example.com
 If the user has the website codebase:
 
 ```bash
+npx geo-ai-search-optimization agent-orchestrator ./your-site
 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
@@ -92,6 +95,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 
 ## When to recommend each command
 
+- `agent-orchestrator`: choose the one next GEO command to run now, plus expected artifact, stop conditions, and follow-up 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
 - `agent-runbook`: build a checklist-driven runbook with preflight, validation, and reporting rules
@@ -127,6 +131,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 When explaining the tool to a user:
 
 - prefer telling them which command to run next, not listing every command
+- if the user or next agent wants just one next command, move them to `agent-orchestrator`
 - 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`

package/src/agent-orchestrator.js

@@ -0,0 +1,191 @@
+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-orchestrator 格式：${format}。可选值：${Array.from(VALID_FORMATS).join(", ")}`);
+  }
+  return resolved;
+}
+
+function inferOrchestrationMode(session) {
+  if (session.status === "needs-context") {
+    return "needs-context";
+  }
+  if (session.intent === "share") {
+    return "delivery";
+  }
+  if (session.intent === "closeout") {
+    return "closeout";
+  }
+  if (session.intent === "execute") {
+    return "execution";
+  }
+  if (session.intent === "guide") {
+    return "guidance";
+  }
+  return "diagnosis";
+}
+
+function buildWhyNow(session, nextStep) {
+  if (!nextStep) {
+    return "当前还没有足够上下文来确定下一步命令，先补输入。";
+  }
+
+  if (session.artifactKind === "geo-agent-playbook-pack") {
+    return "当前已经有单入口 playbook，不应该重新规划整条链，直接沿着既有恢复点继续最稳。";
+  }
+  if (session.artifactKind === "geo-agent-decision-log") {
+    return "当前已经有跨轮决策历史，下一步应沿着最近一次决策继续，而不是重新做全量判断。";
+  }
+  if (session.artifactKind === "geo-agent-retrospective") {
+    return "当前已经有多轮复盘，下一步应该把复盘结论转成正式动作，而不是回到最前面的扫描阶段。";
+  }
+  if (session.sourceType === "url" && session.intent === "execute") {
+    return "当前只有公开网址，最重要的是先把建议型执行入口建立好，再决定是否需要仓库上下文。";
+  }
+
+  return `${session.whyThisSkill} 当前最该先跑的是 ${nextStep.commandName}，因为它会直接产出下一阶段需要的关键工件。`;
+}
+
+function buildStopIf(session, nextStep) {
+  const items = [...session.contextNeeded];
+
+  if (session.sourceType === "url" && session.intent === "execute") {
+    items.push("只有网址时，不要宣称已经完成代码级修复。");
+  }
+  if (session.artifactKind === "geo-agent-playbook-pack") {
+    items.push("不要绕开 playbook 重新拆一条新链，除非当前 playbook 已明显过时。");
+  }
+  if (nextStep?.commandName === "agent-executor") {
+    items.push("不要同时展开多个任务包；这一轮先推进当前单包。");
+  }
+  if (nextStep?.commandName === "completion-report") {
+    items.push("如果这一轮还没有完成或没有明确验证结果，不要过早进入 closeout。");
+  }
+  if (nextStep?.commandName === "publish-pack") {
+    items.push("如果前面的 completion-report 或 share 结果还不完整，不要直接产出最终交付包。");
+  }
+
+  return Array.from(new Set(items));
+}
+
+function buildAfterThat(session) {
+  return session.steps[1]?.command || null;
+}
+
+function buildOrchestratorPrompt(orchestrator) {
+  const lines = [
+    `Use $${orchestrator.selectedSkill.name} to continue this GEO task.`,
+    `当前输入：${orchestrator.source}`,
+    `当前阶段：${orchestrator.current_stage}`,
+    `当前模式：${orchestrator.orchestration_mode}`,
+    `为什么现在做这一步：${orchestrator.why_now}`
+  ];
+
+  if (orchestrator.next_command) {
+    lines.push(`现在只运行这一条命令：${orchestrator.next_command}`);
+  }
+  if (orchestrator.expected_artifact) {
+    lines.push(`预期产物：${orchestrator.expected_artifact}`);
+  }
+  if (orchestrator.after_that) {
+    lines.push(`完成后下一条：${orchestrator.after_that}`);
+  }
+  if (orchestrator.stop_if.length > 0) {
+    lines.push("出现以下情况就先停下：");
+    for (const item of orchestrator.stop_if) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  lines.push("输出时先说明为什么执行这一步，再说明得到什么，以及之后怎么继续。");
+  return lines.join("\n");
+}
+
+export async function createAgentOrchestrator(input, options = {}) {
+  const format = normalizeFormat(options.format);
+  const session = await createAgentSession(input, {
+    intent: options.intent
+  });
+  const nextStep = session.steps[0] || null;
+
+  const orchestrator = {
+    kind: "geo-agent-orchestrator",
+    input,
+    source: session.source,
+    sourceType: session.sourceType,
+    artifactKind: session.artifactKind,
+    format,
+    orchestration_mode: inferOrchestrationMode(session),
+    current_stage: session.stage,
+    why_now: buildWhyNow(session, nextStep),
+    next_command: nextStep?.command || null,
+    expected_artifact: nextStep?.expectedArtifact || null,
+    stop_if: buildStopIf(session, nextStep),
+    after_that: buildAfterThat(session),
+    selectedSkill: session.selectedSkill,
+    next_skill: nextStep?.suggestedSkill || session.selectedSkill.name,
+    session_status: session.status,
+    next_action: session.nextAction,
+    session,
+    orchestrator_prompt: ""
+  };
+
+  orchestrator.orchestrator_prompt = buildOrchestratorPrompt(orchestrator);
+  return orchestrator;
+}
+
+export function renderAgentOrchestratorMarkdown(orchestrator) {
+  const lines = [
+    "# GEO Agent Orchestrator",
+    "",
+    `- 输入：\`${orchestrator.source}\``,
+    `- 输入类型：\`${orchestrator.sourceType}\``,
+    `- 工件类型：\`${orchestrator.artifactKind}\``,
+    `- 当前阶段：${orchestrator.current_stage}`,
+    `- orchestration mode：\`${orchestrator.orchestration_mode}\``,
+    `- 当前建议 skill：\`${orchestrator.next_skill}\``,
+    "",
+    "## 为什么现在做这一步",
+    "",
+    `- ${orchestrator.why_now}`,
+    "",
+    "## 现在只做这一条",
+    "",
+    `- 命令：\`${orchestrator.next_command || "先补输入"}\``,
+    `- 预期产物：${orchestrator.expected_artifact || "先明确需要什么上下文"}`,
+    ""
+  ];
+
+  if (orchestrator.after_that) {
+    lines.push("## 做完之后", "", `- 下一条：\`${orchestrator.after_that}\``, "");
+  }
+
+  lines.push("## 什么时候先停下", "");
+  if (orchestrator.stop_if.length === 0) {
+    lines.push("- 当前没有额外 stop 条件。");
+  } else {
+    for (const item of orchestrator.stop_if) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  lines.push(
+    "",
+    "## 可直接复制给 Agent 的 Orchestrator Prompt",
+    "",
+    "```text",
+    orchestrator.orchestrator_prompt,
+    "```"
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeAgentOrchestratorOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/cli.js

@@ -16,6 +16,11 @@ import {
 } from "./agent-progress-tracker.js";
 import { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
 import { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.js";
+import {
+  createAgentOrchestrator,
+  renderAgentOrchestratorMarkdown,
+  writeAgentOrchestratorOutput
+} from "./agent-orchestrator.js";
 import {
   createAgentPlaybookPack,
   renderAgentPlaybookPackMarkdown,
@@ -80,6 +85,7 @@ function printHelp() {
       "Usage:",
       "  geo-ai-search-optimization",
       "  geo-ai-search-optimization install [--target <dir>] [--json]",
+      "  geo-ai-search-optimization agent-orchestrator <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--format <markdown|json>] [--out <file>]",
       "  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>]",
@@ -183,6 +189,32 @@ async function handleAutoFlow(args) {
   process.stdout.write(renderedOutput);
 }
 
+async function handleAgentOrchestrator(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("agent-orchestrator 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
+  }
+
+  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+  const orchestrator = await createAgentOrchestrator(input, {
+    intent: getFlagValue(args, "--intent"),
+    format
+  });
+  const outputJson = orchestrator.format === "json";
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(orchestrator, null, 2)}\n`
+    : renderAgentOrchestratorMarkdown(orchestrator);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeAgentOrchestratorOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 agent-orchestrator 结果：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
 async function handleAgentSession(args) {
   const input = args.find((value) => !value.startsWith("-"));
   if (!input) {
@@ -999,6 +1031,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "agent-orchestrator") {
+    await handleAgentOrchestrator(rest);
+    return;
+  }
+
   if (command === "agent-session") {
     await handleAgentSession(rest);
     return;

package/src/index.js

@@ -7,6 +7,7 @@ export {
 } from "./interactive-onboarding.js";
 export { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./auto-flow.js";
 export { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "./apply-plan.js";
+export { createAgentOrchestrator, renderAgentOrchestratorMarkdown, writeAgentOrchestratorOutput } from "./agent-orchestrator.js";
 export { createAgentBatchExecutor, renderAgentBatchExecutorMarkdown, writeAgentBatchExecutorOutput } from "./agent-batch-executor.js";
 export { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
 export { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.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-orchestrator",
   "geo-ai-search-optimization-agent-session",
   "geo-ai-search-optimization-agent-runbook",
   "geo-ai-search-optimization-agent-executor",
@@ -29,6 +30,7 @@ const SKILL_ORDER = [
 const SKILL_CATEGORY = {
   "geo-ai-search-optimization": "core",
   "geo-ai-search-optimization-auto-flow": "routing",
+  "geo-ai-search-optimization-agent-orchestrator": "routing",
   "geo-ai-search-optimization-agent-session": "routing",
   "geo-ai-search-optimization-agent-runbook": "execution",
   "geo-ai-search-optimization-agent-executor": "execution",
@@ -171,6 +173,7 @@ export function renderBundledSkillsMarkdown(bundle) {
     "## 推荐理解顺序",
     "",
     "- 先看核心 GEO skill。",
+    "- 如果你只想让 agent 立刻知道现在唯一该跑哪条命令，先跑 agent-orchestrator。",
     "- 如果 agent 需要自动选 skill，先跑 auto-flow。",
     "- 如果要给 agent 明确步骤，继续进入 agent-session。",
     "- 如果要给 agent 一份执行手册和检查表，再进入 agent-runbook。",