geo-ai-search-optimization 1.3.1 → 1.3.2

package/README.md

@@ -844,6 +844,13 @@ geo-ai-search-optimization help
 - `auto-flow` 已能识别 `geo-agent-state-pack` 并继续往下路由
 - 新增 `geo-ai-search-optimization-agent-state-pack` skill
 
+## New in 1.3.2
+
+- 进行了 CLI 架构迭代，把 flow/routing 相关命令从主 `cli.js` 拆到独立模块
+- 新增 `src/cli-flow-commands.js`，让 `auto-flow / agent-orchestrator / agent-resume / agent-continue / agent-state-pack / agent-session` 形成一个明确的 adapter 边界
+- 新增 `src/cli-shared.js`，集中处理 flag 解析、输入校验和输出写回，降低后续继续加命令时的耦合
+- 主 `cli.js` 现在更像薄路由层，后续扩充 command family 会更稳
+
 ## New in 1.2.20
 
 - 新增 `agent-continue`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/src/cli-flow-commands.js

@@ -0,0 +1,143 @@
+import { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./auto-flow.js";
+import {
+  createAgentContinue,
+  renderAgentContinueMarkdown,
+  writeAgentContinueOutput
+} from "./agent-continue.js";
+import {
+  createAgentOrchestrator,
+  renderAgentOrchestratorMarkdown,
+  writeAgentOrchestratorOutput
+} from "./agent-orchestrator.js";
+import { createAgentResume, renderAgentResumeMarkdown, writeAgentResumeOutput } from "./agent-resume.js";
+import {
+  createAgentStatePack,
+  renderAgentStatePackMarkdown,
+  writeAgentStatePackOutput
+} from "./agent-state-pack.js";
+import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
+import {
+  getFlagValue,
+  getJsonCapableFormat,
+  getRequiredInput,
+  hasFlag,
+  writeOrPrintArtifact
+} from "./cli-shared.js";
+
+export const FLOW_HELP_LINES = [
+  "  geo-ai-search-optimization agent-orchestrator <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-resume <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-continue <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-state-pack <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--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>]"
+];
+
+async function handleAutoFlow(args) {
+  const input = getRequiredInput(args, "auto-flow");
+  const flow = await createAutoFlow(input, {
+    intent: getFlagValue(args, "--intent")
+  });
+  const outputJson = hasFlag(args, "--json");
+  const renderedOutput = outputJson ? `${JSON.stringify(flow, null, 2)}\n` : renderAutoFlowMarkdown(flow);
+  const outputPath = getFlagValue(args, "--out");
+
+  if (outputPath) {
+    const resolvedOutputPath = await writeAutoFlowOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 auto-flow 结果：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
+async function handleAgentOrchestrator(args) {
+  const input = getRequiredInput(args, "agent-orchestrator");
+  const artifact = await createAgentOrchestrator(input, {
+    intent: getFlagValue(args, "--intent"),
+    format: getJsonCapableFormat(args)
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent-orchestrator",
+    artifact,
+    renderMarkdown: renderAgentOrchestratorMarkdown,
+    writeOutput: writeAgentOrchestratorOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentResume(args) {
+  const input = getRequiredInput(args, "agent-resume");
+  const artifact = await createAgentResume(input, {
+    intent: getFlagValue(args, "--intent"),
+    format: getJsonCapableFormat(args)
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent-resume",
+    artifact,
+    renderMarkdown: renderAgentResumeMarkdown,
+    writeOutput: writeAgentResumeOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentContinue(args) {
+  const input = getRequiredInput(args, "agent-continue");
+  const artifact = await createAgentContinue(input, {
+    intent: getFlagValue(args, "--intent"),
+    format: getJsonCapableFormat(args)
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent-continue",
+    artifact,
+    renderMarkdown: renderAgentContinueMarkdown,
+    writeOutput: writeAgentContinueOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentStatePack(args) {
+  const input = getRequiredInput(args, "agent-state-pack");
+  const artifact = await createAgentStatePack(input, {
+    intent: getFlagValue(args, "--intent"),
+    format: getJsonCapableFormat(args),
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent-state-pack",
+    artifact,
+    renderMarkdown: renderAgentStatePackMarkdown,
+    writeOutput: writeAgentStatePackOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentSession(args) {
+  const input = getRequiredInput(args, "agent-session");
+  const artifact = await createAgentSession(input, {
+    intent: getFlagValue(args, "--intent")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent-session",
+    artifact,
+    renderMarkdown: renderAgentSessionMarkdown,
+    writeOutput: writeAgentSessionOutput,
+    outputJson: hasFlag(args, "--json")
+  });
+}
+
+export const FLOW_COMMAND_HANDLERS = {
+  "auto-flow": handleAutoFlow,
+  "agent-orchestrator": handleAgentOrchestrator,
+  "agent-resume": handleAgentResume,
+  "agent-continue": handleAgentContinue,
+  "agent-state-pack": handleAgentStatePack,
+  "agent-session": handleAgentSession
+};

package/src/cli-shared.js

@@ -0,0 +1,54 @@
+export function getFlagValue(args, flagName) {
+  const index = args.indexOf(flagName);
+  if (index === -1) {
+    return null;
+  }
+  if (index === args.length - 1) {
+    throw new Error(`${flagName} requires a value`);
+  }
+  return args[index + 1];
+}
+
+export function hasFlag(args, ...flagNames) {
+  return flagNames.some((flagName) => args.includes(flagName));
+}
+
+export function parsePositiveInteger(value, flagName) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${flagName} must be a positive integer`);
+  }
+  return parsed;
+}
+
+export function getRequiredInput(args, commandName) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error(`${commandName} 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件`);
+  }
+  return input;
+}
+
+export function getJsonCapableFormat(args) {
+  return getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
+}
+
+export async function writeOrPrintArtifact({
+  args,
+  commandName,
+  artifact,
+  renderMarkdown,
+  writeOutput,
+  outputJson
+}) {
+  const renderedOutput = outputJson ? `${JSON.stringify(artifact, null, 2)}\n` : renderMarkdown(artifact);
+  const outputPath = getFlagValue(args, "--out");
+
+  if (outputPath) {
+    const resolvedOutputPath = await writeOutput(outputPath, renderedOutput);
+    process.stdout.write(`已保存 ${commandName} 结果：${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}

package/src/cli.js

@@ -1,22 +1,14 @@
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { FLOW_COMMAND_HANDLERS, FLOW_HELP_LINES } from "./cli-flow-commands.js";
+import { getFlagValue, hasFlag, parsePositiveInteger } from "./cli-shared.js";
 import { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "./apply-plan.js";
 import {
   createAgentBatchExecutor,
   renderAgentBatchExecutorMarkdown,
   writeAgentBatchExecutorOutput
 } from "./agent-batch-executor.js";
-import {
-  createAgentContinue,
-  renderAgentContinueMarkdown,
-  writeAgentContinueOutput
-} from "./agent-continue.js";
-import {
-  createAgentStatePack,
-  renderAgentStatePackMarkdown,
-  writeAgentStatePackOutput
-} from "./agent-state-pack.js";
 import { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
 import { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
 import {
@@ -26,12 +18,6 @@ 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 { createAgentResume, renderAgentResumeMarkdown, writeAgentResumeOutput } from "./agent-resume.js";
 import {
   createAgentPlaybookPack,
   renderAgentPlaybookPackMarkdown,
@@ -40,8 +26,6 @@ import {
 import { createAgentRetrospective, renderAgentRetrospectiveMarkdown, writeAgentRetrospectiveOutput } from "./agent-retrospective.js";
 import { createAgentStatusBoard, renderAgentStatusBoardMarkdown, writeAgentStatusBoardOutput } from "./agent-status-board.js";
 import { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
-import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
-import { createAutoFlow, renderAutoFlowMarkdown, writeAutoFlowOutput } from "./auto-flow.js";
 import {
   createCompletionReport,
   renderCompletionReportMarkdown,
@@ -96,12 +80,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 agent-resume <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--format <markdown|json>] [--out <file>]",
-      "  geo-ai-search-optimization agent-continue <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--format <markdown|json>] [--out <file>]",
-      "  geo-ai-search-optimization agent-state-pack <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--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>]",
+      ...FLOW_HELP_LINES,
       "  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 agent-executor <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization agent-batch-executor <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--task <id>] [--count <count>] [--format <markdown|json>] [--out <file>]",
@@ -148,29 +127,6 @@ function printHelp() {
   );
 }
 
-function getFlagValue(args, flagName) {
-  const index = args.indexOf(flagName);
-  if (index === -1) {
-    return null;
-  }
-  if (index === args.length - 1) {
-    throw new Error(`${flagName} requires a value`);
-  }
-  return args[index + 1];
-}
-
-function hasFlag(args, ...flagNames) {
-  return flagNames.some((flagName) => args.includes(flagName));
-}
-
-function parsePositiveInteger(value, flagName) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new Error(`${flagName} must be a positive integer`);
-  }
-  return parsed;
-}
-
 async function handleInstall(args) {
   const targetDir = getFlagValue(args, "--target");
   const outputJson = hasFlag(args, "--json");
@@ -181,157 +137,6 @@ async function handleInstall(args) {
   }
 }
 
-async function handleAutoFlow(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("auto-flow 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
-  }
-
-  const flow = await createAutoFlow(input, {
-    intent: getFlagValue(args, "--intent")
-  });
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson ? `${JSON.stringify(flow, null, 2)}\n` : renderAutoFlowMarkdown(flow);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAutoFlowOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 auto-flow 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  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 handleAgentResume(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-resume 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const resume = await createAgentResume(input, {
-    intent: getFlagValue(args, "--intent"),
-    format
-  });
-  const outputJson = resume.format === "json";
-  const renderedOutput = outputJson ? `${JSON.stringify(resume, null, 2)}\n` : renderAgentResumeMarkdown(resume);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentResumeOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent-resume 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentContinue(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-continue 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const artifact = await createAgentContinue(input, {
-    intent: getFlagValue(args, "--intent"),
-    format
-  });
-  const outputJson = artifact.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(artifact, null, 2)}\n`
-    : renderAgentContinueMarkdown(artifact);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentContinueOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent-continue 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentStatePack(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-state-pack 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const artifact = await createAgentStatePack(input, {
-    intent: getFlagValue(args, "--intent"),
-    format,
-    currentTaskId: getFlagValue(args, "--current"),
-    completedPacketIds: getFlagValue(args, "--completed"),
-    blockedReasons: getFlagValue(args, "--blocked")
-  });
-  const outputJson = artifact.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(artifact, null, 2)}\n`
-    : renderAgentStatePackMarkdown(artifact);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentStatePackOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent-state-pack 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  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);
-}
-
 async function handleAgentRunbook(args) {
   const input = args.find((value) => !value.startsWith("-"));
   if (!input) {
@@ -1103,6 +908,7 @@ async function handleRoadmap(args) {
 
 export async function runCli(args = []) {
   const [command = "install", ...rest] = args;
+  const flowHandler = FLOW_COMMAND_HANDLERS[command];
 
   if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -1119,33 +925,8 @@ export async function runCli(args = []) {
     return;
   }
 
-  if (command === "auto-flow") {
-    await handleAutoFlow(rest);
-    return;
-  }
-
-  if (command === "agent-orchestrator") {
-    await handleAgentOrchestrator(rest);
-    return;
-  }
-
-  if (command === "agent-resume") {
-    await handleAgentResume(rest);
-    return;
-  }
-
-  if (command === "agent-continue") {
-    await handleAgentContinue(rest);
-    return;
-  }
-
-  if (command === "agent-state-pack") {
-    await handleAgentStatePack(rest);
-    return;
-  }
-
-  if (command === "agent-session") {
-    await handleAgentSession(rest);
+  if (flowHandler) {
+    await flowHandler(rest);
     return;
   }