geo-ai-search-optimization 1.3.1 → 1.3.3

package/README.md

@@ -844,6 +844,20 @@ 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.3.3
+
+- 继续做 CLI 架构迭代，把 agent execution family 也从主 `cli.js` 拆出
+- 新增 `src/cli-agent-execution-commands.js`，接管 `agent-runbook / agent-executor / agent-batch-executor / agent-progress-tracker / agent-status-board / agent-checkpoint / agent-decision-log / agent-retrospective / agent-playbook-pack`
+- 主 `cli.js` 进一步收敛成更薄的 command router
+- 现在 flow family 和 execution family 都有独立 adapter 模块，后续继续拆 planning / delivery 会更顺
+
 ## 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.3",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/src/cli-agent-execution-commands.js

@@ -0,0 +1,210 @@
+import {
+  createAgentBatchExecutor,
+  renderAgentBatchExecutorMarkdown,
+  writeAgentBatchExecutorOutput
+} from "./agent-batch-executor.js";
+import { createAgentExecutor, renderAgentExecutorMarkdown, writeAgentExecutorOutput } from "./agent-executor.js";
+import {
+  createAgentProgressTracker,
+  renderAgentProgressTrackerMarkdown,
+  writeAgentProgressTrackerOutput
+} from "./agent-progress-tracker.js";
+import { createAgentCheckpoint, renderAgentCheckpointMarkdown, writeAgentCheckpointOutput } from "./agent-checkpoint.js";
+import { createAgentDecisionLog, renderAgentDecisionLogMarkdown, writeAgentDecisionLogOutput } from "./agent-decision-log.js";
+import {
+  createAgentPlaybookPack,
+  renderAgentPlaybookPackMarkdown,
+  writeAgentPlaybookPackOutput
+} from "./agent-playbook-pack.js";
+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 {
+  getFlagValue,
+  getJsonCapableFormat,
+  getRequiredInput,
+  writeOrPrintArtifact
+} from "./cli-shared.js";
+
+export const AGENT_EXECUTION_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>]",
+  "  geo-ai-search-optimization agent-progress-tracker <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-status-board <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-checkpoint <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-decision-log <input> [--append-from <file>] [--note <text>] [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-retrospective <input> [--format <markdown|json>] [--out <file>]",
+  "  geo-ai-search-optimization agent-playbook-pack <input> [--task <id>] [--format <markdown|json>] [--out <file>]"
+];
+
+async function handleAgentRunbook(args) {
+  const input = getRequiredInput(args, "agent-runbook");
+  const format = getFlagValue(args, "--format");
+  const artifact = await createAgentRunbook(input, {
+    intent: getFlagValue(args, "--intent"),
+    format,
+    taskId: getFlagValue(args, "--task")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent runbook",
+    artifact,
+    renderMarkdown: renderAgentRunbookMarkdown,
+    writeOutput: writeAgentRunbookOutput,
+    outputJson: format === "json"
+  });
+}
+
+async function handleAgentExecutor(args) {
+  const input = getRequiredInput(args, "agent-executor");
+  const format = getFlagValue(args, "--format");
+  const artifact = await createAgentExecutor(input, {
+    intent: getFlagValue(args, "--intent"),
+    format,
+    taskId: getFlagValue(args, "--task")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent executor",
+    artifact,
+    renderMarkdown: renderAgentExecutorMarkdown,
+    writeOutput: writeAgentExecutorOutput,
+    outputJson: format === "json"
+  });
+}
+
+async function handleAgentBatchExecutor(args) {
+  const input = getRequiredInput(args, "agent-batch-executor");
+  const artifact = await createAgentBatchExecutor(input, {
+    intent: getFlagValue(args, "--intent"),
+    format: getJsonCapableFormat(args),
+    taskId: getFlagValue(args, "--task"),
+    count: getFlagValue(args, "--count")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent batch executor",
+    artifact,
+    renderMarkdown: renderAgentBatchExecutorMarkdown,
+    writeOutput: writeAgentBatchExecutorOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentProgressTracker(args) {
+  const input = getRequiredInput(args, "agent-progress-tracker");
+  const artifact = await createAgentProgressTracker(input, {
+    format: getJsonCapableFormat(args),
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent progress tracker",
+    artifact,
+    renderMarkdown: renderAgentProgressTrackerMarkdown,
+    writeOutput: writeAgentProgressTrackerOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentStatusBoard(args) {
+  const input = getRequiredInput(args, "agent-status-board");
+  const artifact = await createAgentStatusBoard(input, {
+    format: getJsonCapableFormat(args),
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent status board",
+    artifact,
+    renderMarkdown: renderAgentStatusBoardMarkdown,
+    writeOutput: writeAgentStatusBoardOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentCheckpoint(args) {
+  const input = getRequiredInput(args, "agent-checkpoint");
+  const artifact = await createAgentCheckpoint(input, {
+    format: getJsonCapableFormat(args),
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent checkpoint",
+    artifact,
+    renderMarkdown: renderAgentCheckpointMarkdown,
+    writeOutput: writeAgentCheckpointOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentDecisionLog(args) {
+  const input = getRequiredInput(args, "agent-decision-log");
+  const artifact = await createAgentDecisionLog(input, {
+    format: getJsonCapableFormat(args),
+    appendFrom: getFlagValue(args, "--append-from"),
+    note: getFlagValue(args, "--note"),
+    currentTaskId: getFlagValue(args, "--current"),
+    completedPacketIds: getFlagValue(args, "--completed"),
+    blockedReasons: getFlagValue(args, "--blocked")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent decision log",
+    artifact,
+    renderMarkdown: renderAgentDecisionLogMarkdown,
+    writeOutput: writeAgentDecisionLogOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentRetrospective(args) {
+  const input = getRequiredInput(args, "agent-retrospective");
+  const artifact = await createAgentRetrospective(input, {
+    format: getJsonCapableFormat(args)
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent retrospective",
+    artifact,
+    renderMarkdown: renderAgentRetrospectiveMarkdown,
+    writeOutput: writeAgentRetrospectiveOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+async function handleAgentPlaybookPack(args) {
+  const input = getRequiredInput(args, "agent-playbook-pack");
+  const artifact = await createAgentPlaybookPack(input, {
+    format: getJsonCapableFormat(args),
+    taskId: getFlagValue(args, "--task")
+  });
+  return writeOrPrintArtifact({
+    args,
+    commandName: "agent playbook pack",
+    artifact,
+    renderMarkdown: renderAgentPlaybookPackMarkdown,
+    writeOutput: writeAgentPlaybookPackOutput,
+    outputJson: artifact.format === "json"
+  });
+}
+
+export const AGENT_EXECUTION_COMMAND_HANDLERS = {
+  "agent-runbook": handleAgentRunbook,
+  "agent-executor": handleAgentExecutor,
+  "agent-batch-executor": handleAgentBatchExecutor,
+  "agent-progress-tracker": handleAgentProgressTracker,
+  "agent-status-board": handleAgentStatusBoard,
+  "agent-checkpoint": handleAgentCheckpoint,
+  "agent-decision-log": handleAgentDecisionLog,
+  "agent-retrospective": handleAgentRetrospective,
+  "agent-playbook-pack": handleAgentPlaybookPack
+};

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,47 +1,14 @@
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { createApplyPlan, renderApplyPlanMarkdown, writeApplyPlanOutput } from "./apply-plan.js";
-import {
-  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";
+  AGENT_EXECUTION_COMMAND_HANDLERS,
+  AGENT_EXECUTION_HELP_LINES
+} from "./cli-agent-execution-commands.js";
+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 { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput } from "./agent-handoff.js";
-import {
-  createAgentProgressTracker,
-  renderAgentProgressTrackerMarkdown,
-  writeAgentProgressTrackerOutput
-} 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,
-  writeAgentPlaybookPackOutput
-} from "./agent-playbook-pack.js";
-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,21 +63,8 @@ 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>]",
-      "  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>]",
-      "  geo-ai-search-optimization agent-progress-tracker <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
-      "  geo-ai-search-optimization agent-status-board <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
-      "  geo-ai-search-optimization agent-checkpoint <input> [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
-      "  geo-ai-search-optimization agent-decision-log <input> [--append-from <file>] [--note <text>] [--current <id>] [--completed <id,id>] [--blocked <reason,reason>] [--format <markdown|json>] [--out <file>]",
-      "  geo-ai-search-optimization agent-retrospective <input> [--format <markdown|json>] [--out <file>]",
-      "  geo-ai-search-optimization agent-playbook-pack <input> [--task <id>] [--format <markdown|json>] [--out <file>]",
+      ...FLOW_HELP_LINES,
+      ...AGENT_EXECUTION_HELP_LINES,
       "  geo-ai-search-optimization skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
@@ -148,29 +102,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,404 +112,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) {
-    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);
-}
-
-async function handleAgentExecutor(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-executor 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format");
-  const executor = await createAgentExecutor(input, {
-    intent: getFlagValue(args, "--intent"),
-    format,
-    taskId: getFlagValue(args, "--task")
-  });
-  const outputJson = format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(executor, null, 2)}\n`
-    : renderAgentExecutorMarkdown(executor);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentExecutorOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent executor：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentBatchExecutor(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-batch-executor 需要一个输入值，可以是任务描述、项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const batch = await createAgentBatchExecutor(input, {
-    intent: getFlagValue(args, "--intent"),
-    format,
-    taskId: getFlagValue(args, "--task"),
-    count: getFlagValue(args, "--count")
-  });
-  const outputJson = batch.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(batch, null, 2)}\n`
-    : renderAgentBatchExecutorMarkdown(batch);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentBatchExecutorOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent batch executor：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentProgressTracker(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-progress-tracker 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const tracker = await createAgentProgressTracker(input, {
-    format,
-    currentTaskId: getFlagValue(args, "--current"),
-    completedPacketIds: getFlagValue(args, "--completed"),
-    blockedReasons: getFlagValue(args, "--blocked")
-  });
-  const outputJson = tracker.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(tracker, null, 2)}\n`
-    : renderAgentProgressTrackerMarkdown(tracker);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentProgressTrackerOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent progress tracker：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentStatusBoard(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-status-board 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const board = await createAgentStatusBoard(input, {
-    format,
-    currentTaskId: getFlagValue(args, "--current"),
-    completedPacketIds: getFlagValue(args, "--completed"),
-    blockedReasons: getFlagValue(args, "--blocked")
-  });
-  const outputJson = board.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(board, null, 2)}\n`
-    : renderAgentStatusBoardMarkdown(board);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentStatusBoardOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent status board：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentCheckpoint(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-checkpoint 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const checkpoint = await createAgentCheckpoint(input, {
-    format,
-    currentTaskId: getFlagValue(args, "--current"),
-    completedPacketIds: getFlagValue(args, "--completed"),
-    blockedReasons: getFlagValue(args, "--blocked")
-  });
-  const outputJson = checkpoint.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(checkpoint, null, 2)}\n`
-    : renderAgentCheckpointMarkdown(checkpoint);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentCheckpointOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent checkpoint：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentDecisionLog(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-decision-log 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const decisionLog = await createAgentDecisionLog(input, {
-    format,
-    appendFrom: getFlagValue(args, "--append-from"),
-    note: getFlagValue(args, "--note"),
-    currentTaskId: getFlagValue(args, "--current"),
-    completedPacketIds: getFlagValue(args, "--completed"),
-    blockedReasons: getFlagValue(args, "--blocked")
-  });
-  const outputJson = decisionLog.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(decisionLog, null, 2)}\n`
-    : renderAgentDecisionLogMarkdown(decisionLog);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentDecisionLogOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent decision log：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentRetrospective(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-retrospective 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const retrospective = await createAgentRetrospective(input, {
-    format
-  });
-  const outputJson = retrospective.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(retrospective, null, 2)}\n`
-    : renderAgentRetrospectiveMarkdown(retrospective);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentRetrospectiveOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent retrospective：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleAgentPlaybookPack(args) {
-  const input = args.find((value) => !value.startsWith("-"));
-  if (!input) {
-    throw new Error("agent-playbook-pack 需要一个输入值，可以是项目路径、网站网址或已导出的工件");
-  }
-
-  const format = getFlagValue(args, "--format") || (hasFlag(args, "--json") ? "json" : undefined);
-  const pack = await createAgentPlaybookPack(input, {
-    format,
-    taskId: getFlagValue(args, "--task")
-  });
-  const outputJson = pack.format === "json";
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(pack, null, 2)}\n`
-    : renderAgentPlaybookPackMarkdown(pack);
-
-  const outputPath = getFlagValue(args, "--out");
-  if (outputPath) {
-    const resolvedOutputPath = await writeAgentPlaybookPackOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 agent playbook pack：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
 function handleWhere() {
   process.stdout.write(
     [
@@ -1103,6 +636,8 @@ async function handleRoadmap(args) {
 
 export async function runCli(args = []) {
   const [command = "install", ...rest] = args;
+  const flowHandler = FLOW_COMMAND_HANDLERS[command];
+  const agentExecutionHandler = AGENT_EXECUTION_COMMAND_HANDLERS[command];
 
   if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -1119,33 +654,13 @@ 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);
+  if (flowHandler) {
+    await flowHandler(rest);
     return;
   }
 
-  if (command === "agent-session") {
-    await handleAgentSession(rest);
+  if (agentExecutionHandler) {
+    await agentExecutionHandler(rest);
     return;
   }