geo-ai-search-optimization 1.3.6 → 1.3.8

package/README.md

@@ -879,6 +879,21 @@ geo-ai-search-optimization help
 - 主 `cli.js` 现在只保留 `version / help / command routing`
 - CLI 已经形成 `shell / flow / execution / planning-delivery / site-ops / shared` 六层 command adapter 结构
 
+## New in 1.3.7
+
+- 开始把重复的 artifact 编排从 adapter 中抽成共享组合器
+- `src/cli-shared.js` 新增 `createArtifactCommandHandler` 和 `createPackCommandHandler`
+- `src/cli-agent-execution-commands.js` 与 `src/cli-planning-delivery-commands.js` 现在改用声明式组合，减少重复的 `create / render / write` handler 模板代码
+- CLI 架构从“按命令族拆文件”进一步推进到“adapter + shared composition”模式
+
+## New in 1.3.8
+
+- 继续把共享组合器推广到 `flow` 与 `site-ops` 两层
+- `src/cli-shared.js` 新增 `createStructuredOutputCommandHandler`
+- `src/cli-flow-commands.js` 现在统一通过组合器编排 `auto-flow / agent-orchestrator / agent-resume / agent-continue / agent-state-pack / agent-session`
+- `src/cli-site-ops-commands.js` 现在统一通过组合器编排 `doctor / quick-start / onboard / onboard-url / audit / scan`
+- CLI 架构进一步收敛到“命令族 adapter + shared composition primitives”的模式
+
 ## New in 1.2.20
 
 - 新增 `agent-continue`

package/package.json

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

@@ -20,10 +20,9 @@ import { createAgentRetrospective, renderAgentRetrospectiveMarkdown, writeAgentR
 import { createAgentStatusBoard, renderAgentStatusBoardMarkdown, writeAgentStatusBoardOutput } from "./agent-status-board.js";
 import { createAgentRunbook, renderAgentRunbookMarkdown, writeAgentRunbookOutput } from "./agent-runbook.js";
 import {
+  createArtifactCommandHandler,
   getFlagValue,
-  getJsonCapableFormat,
-  getRequiredInput,
-  writeOrPrintArtifact
+  getJsonCapableFormat
 } from "./cli-shared.js";
 
 export const AGENT_EXECUTION_HELP_LINES = [
@@ -38,164 +37,126 @@ export const AGENT_EXECUTION_HELP_LINES = [
   "  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, {
+const handleAgentRunbook = createArtifactCommandHandler({
+  commandName: "agent-runbook",
+  commandLabel: "agent runbook",
+  createArtifact: createAgentRunbook,
+  renderMarkdown: renderAgentRunbookMarkdown,
+  writeOutput: writeAgentRunbookOutput,
+  getOptions: (args) => ({
     intent: getFlagValue(args, "--intent"),
-    format,
+    format: getFlagValue(args, "--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, {
+const handleAgentExecutor = createArtifactCommandHandler({
+  commandName: "agent-executor",
+  commandLabel: "agent executor",
+  createArtifact: createAgentExecutor,
+  renderMarkdown: renderAgentExecutorMarkdown,
+  writeOutput: writeAgentExecutorOutput,
+  getOptions: (args) => ({
     intent: getFlagValue(args, "--intent"),
-    format,
+    format: getFlagValue(args, "--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, {
+const handleAgentBatchExecutor = createArtifactCommandHandler({
+  commandName: "agent-batch-executor",
+  commandLabel: "agent batch executor",
+  createArtifact: createAgentBatchExecutor,
+  renderMarkdown: renderAgentBatchExecutorMarkdown,
+  writeOutput: writeAgentBatchExecutorOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentProgressTracker = createArtifactCommandHandler({
+  commandName: "agent-progress-tracker",
+  commandLabel: "agent progress tracker",
+  createArtifact: createAgentProgressTracker,
+  renderMarkdown: renderAgentProgressTrackerMarkdown,
+  writeOutput: writeAgentProgressTrackerOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentStatusBoard = createArtifactCommandHandler({
+  commandName: "agent-status-board",
+  commandLabel: "agent status board",
+  createArtifact: createAgentStatusBoard,
+  renderMarkdown: renderAgentStatusBoardMarkdown,
+  writeOutput: writeAgentStatusBoardOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentCheckpoint = createArtifactCommandHandler({
+  commandName: "agent-checkpoint",
+  commandLabel: "agent checkpoint",
+  createArtifact: createAgentCheckpoint,
+  renderMarkdown: renderAgentCheckpointMarkdown,
+  writeOutput: writeAgentCheckpointOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentDecisionLog = createArtifactCommandHandler({
+  commandName: "agent-decision-log",
+  commandLabel: "agent decision log",
+  createArtifact: createAgentDecisionLog,
+  renderMarkdown: renderAgentDecisionLogMarkdown,
+  writeOutput: writeAgentDecisionLogOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentRetrospective = createArtifactCommandHandler({
+  commandName: "agent-retrospective",
+  commandLabel: "agent retrospective",
+  createArtifact: createAgentRetrospective,
+  renderMarkdown: renderAgentRetrospectiveMarkdown,
+  writeOutput: writeAgentRetrospectiveOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentPlaybookPack = createArtifactCommandHandler({
+  commandName: "agent-playbook-pack",
+  commandLabel: "agent playbook pack",
+  createArtifact: createAgentPlaybookPack,
+  renderMarkdown: renderAgentPlaybookPackMarkdown,
+  writeOutput: writeAgentPlaybookPackOutput,
+  getOptions: (args) => ({
     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,

package/src/cli-flow-commands.js

@@ -17,11 +17,12 @@ import {
 } from "./agent-state-pack.js";
 import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 import {
+  createArtifactCommandHandler,
+  createStructuredOutputCommandHandler,
   getFlagValue,
   getJsonCapableFormat,
   getRequiredInput,
-  hasFlag,
-  writeOrPrintArtifact
+  hasFlag
 } from "./cli-shared.js";
 
 export const FLOW_HELP_LINES = [
@@ -33,105 +34,80 @@ export const FLOW_HELP_LINES = [
   "  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);
-}
+const handleAutoFlow = createStructuredOutputCommandHandler({
+  commandLabel: "auto-flow",
+  execute: async (args) => {
+    const input = getRequiredInput(args, "auto-flow");
+    return createAutoFlow(input, {
+      intent: getFlagValue(args, "--intent")
+    });
+  },
+  renderMarkdown: renderAutoFlowMarkdown,
+  writeOutput: writeAutoFlowOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
 
-async function handleAgentOrchestrator(args) {
-  const input = getRequiredInput(args, "agent-orchestrator");
-  const artifact = await createAgentOrchestrator(input, {
+const handleAgentOrchestrator = createArtifactCommandHandler({
+  commandName: "agent-orchestrator",
+  commandLabel: "agent-orchestrator",
+  createArtifact: createAgentOrchestrator,
+  renderMarkdown: renderAgentOrchestratorMarkdown,
+  writeOutput: writeAgentOrchestratorOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentResume = createArtifactCommandHandler({
+  commandName: "agent-resume",
+  commandLabel: "agent-resume",
+  createArtifact: createAgentResume,
+  renderMarkdown: renderAgentResumeMarkdown,
+  writeOutput: writeAgentResumeOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentContinue = createArtifactCommandHandler({
+  commandName: "agent-continue",
+  commandLabel: "agent-continue",
+  createArtifact: createAgentContinue,
+  renderMarkdown: renderAgentContinueMarkdown,
+  writeOutput: writeAgentContinueOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentStatePack = createArtifactCommandHandler({
+  commandName: "agent-state-pack",
+  commandLabel: "agent-state-pack",
+  createArtifact: createAgentStatePack,
+  renderMarkdown: renderAgentStatePackMarkdown,
+  writeOutput: writeAgentStatePackOutput,
+  getOptions: (args) => ({
     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, {
+const handleAgentSession = createArtifactCommandHandler({
+  commandName: "agent-session",
+  commandLabel: "agent-session",
+  createArtifact: createAgentSession,
+  renderMarkdown: renderAgentSessionMarkdown,
+  writeOutput: writeAgentSessionOutput,
+  getOptions: (args) => ({
     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,

package/src/cli-planning-delivery-commands.js

@@ -17,7 +17,13 @@ import { renderPublishPackMarkdown, writePublishPack } from "./publish-pack.js";
 import { generateReport, writeReportOutput } from "./report.js";
 import { createRoadmap, renderRoadmapMarkdown, writeRoadmapOutput } from "./roadmap.js";
 import { createSharePack, renderSharePackMarkdown, writeSharePackOutput } from "./share-pack.js";
-import { getFlagValue, getRequiredInput, parsePositiveInteger, writeOrPrintArtifact } from "./cli-shared.js";
+import {
+  createArtifactCommandHandler,
+  createPackCommandHandler,
+  getFlagValue,
+  getRequiredInput,
+  parsePositiveInteger
+} from "./cli-shared.js";
 
 export const PLANNING_DELIVERY_HELP_LINES = [
   "  geo-ai-search-optimization agent-handoff <input> [--format <markdown|json>] [--out <file>]",
@@ -37,196 +43,160 @@ export const PLANNING_DELIVERY_HELP_LINES = [
   "  geo-ai-search-optimization report <input> [--mode <auto|audit|onboarding|scan>] [--format <markdown|html|json>] [--out <file>]"
 ];
 
-async function handleAgentHandoff(args) {
-  const input = getRequiredInput(args, "agent-handoff");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createAgentHandoff(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "agent handoff",
-    artifact,
-    renderMarkdown: renderAgentHandoffMarkdown,
-    writeOutput: writeAgentHandoffOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleApplyPlan(args) {
-  const input = getRequiredInput(args, "apply-plan");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createApplyPlan(input, {
-    format,
+const handleAgentHandoff = createArtifactCommandHandler({
+  commandName: "agent-handoff",
+  commandLabel: "agent handoff",
+  createArtifact: createAgentHandoff,
+  renderMarkdown: renderAgentHandoffMarkdown,
+  writeOutput: writeAgentHandoffOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
+
+const handleApplyPlan = createArtifactCommandHandler({
+  commandName: "apply-plan",
+  commandLabel: "apply plan",
+  createArtifact: createApplyPlan,
+  renderMarkdown: renderApplyPlanMarkdown,
+  writeOutput: writeApplyPlanOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format"),
     taskId: getFlagValue(args, "--task")
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "apply plan",
-    artifact,
-    renderMarkdown: renderApplyPlanMarkdown,
-    writeOutput: writeApplyPlanOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleCompletionReport(args) {
-  const input = getRequiredInput(args, "completion-report");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createCompletionReport(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "completion report",
-    artifact,
-    renderMarkdown: renderCompletionReportMarkdown,
-    writeOutput: writeCompletionReportOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleHandoffBundle(args) {
-  const input = getRequiredInput(args, "handoff-bundle");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createHandoffBundle(input, {
-    format,
+  })
+});
+
+const handleCompletionReport = createArtifactCommandHandler({
+  commandName: "completion-report",
+  commandLabel: "completion report",
+  createArtifact: createCompletionReport,
+  renderMarkdown: renderCompletionReportMarkdown,
+  writeOutput: writeCompletionReportOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
+
+const handleHandoffBundle = createArtifactCommandHandler({
+  commandName: "handoff-bundle",
+  commandLabel: "handoff bundle",
+  createArtifact: createHandoffBundle,
+  renderMarkdown: renderHandoffBundleMarkdown,
+  writeOutput: writeHandoffBundleOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format"),
     taskId: getFlagValue(args, "--task")
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "handoff bundle",
-    artifact,
-    renderMarkdown: renderHandoffBundleMarkdown,
-    writeOutput: writeHandoffBundleOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleSharePack(args) {
-  const input = getRequiredInput(args, "share-pack");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createSharePack(input, {
-    format,
+  })
+});
+
+const handleSharePack = createArtifactCommandHandler({
+  commandName: "share-pack",
+  commandLabel: "share pack",
+  createArtifact: createSharePack,
+  renderMarkdown: renderSharePackMarkdown,
+  writeOutput: writeSharePackOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format"),
     taskId: getFlagValue(args, "--task")
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "share pack",
-    artifact,
-    renderMarkdown: renderSharePackMarkdown,
-    writeOutput: writeSharePackOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleExportPack(args) {
-  const input = getRequiredInput(args, "export-pack");
-  const pack = await writeExportPack(input, {
+  })
+});
+
+const handleExportPack = createPackCommandHandler({
+  commandName: "export-pack",
+  writePack: writeExportPack,
+  renderMarkdown: renderExportPackMarkdown,
+  getOptions: (args) => ({
     format: getFlagValue(args, "--format"),
     taskId: getFlagValue(args, "--task"),
     outputDir: getFlagValue(args, "--out-dir")
-  });
-  process.stdout.write(renderExportPackMarkdown(pack));
-}
-
-async function handleHtmlPack(args) {
-  const input = getRequiredInput(args, "html-pack");
-  const pack = await writeHtmlPack(input, {
+  })
+});
+
+const handleHtmlPack = createPackCommandHandler({
+  commandName: "html-pack",
+  writePack: writeHtmlPack,
+  renderMarkdown: renderHtmlPackMarkdown,
+  getOptions: (args) => ({
     taskId: getFlagValue(args, "--task"),
     outputDir: getFlagValue(args, "--out-dir")
-  });
-  process.stdout.write(renderHtmlPackMarkdown(pack));
-}
-
-async function handlePublishPack(args) {
-  const input = getRequiredInput(args, "publish-pack");
-  const pack = await writePublishPack(input, {
+  })
+});
+
+const handlePublishPack = createPackCommandHandler({
+  commandName: "publish-pack",
+  writePack: writePublishPack,
+  renderMarkdown: renderPublishPackMarkdown,
+  getOptions: (args) => ({
     taskId: getFlagValue(args, "--task"),
     outputDir: getFlagValue(args, "--out-dir")
-  });
-  process.stdout.write(renderPublishPackMarkdown(pack));
-}
-
-async function handleExecSummary(args) {
-  const input = getRequiredInput(args, "exec-summary");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createExecSummary(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "exec summary",
-    artifact,
-    renderMarkdown: renderExecSummaryMarkdown,
-    writeOutput: writeExecSummaryOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleFixPlan(args) {
-  const input = getRequiredInput(args, "fix-plan");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createFixPlan(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "fix plan",
-    artifact,
-    renderMarkdown: renderFixPlanMarkdown,
-    writeOutput: writeFixPlanOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleOwnerBoard(args) {
-  const input = getRequiredInput(args, "owner-board");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createOwnerBoard(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "owner board",
-    artifact,
-    renderMarkdown: renderOwnerBoardMarkdown,
-    writeOutput: writeOwnerBoardOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleMeetingPack(args) {
-  const input = getRequiredInput(args, "meeting-pack");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createMeetingPack(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "meeting pack",
-    artifact,
-    renderMarkdown: renderMeetingPackMarkdown,
-    writeOutput: writeMeetingPackOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handlePmBrief(args) {
-  const input = getRequiredInput(args, "pm-brief");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createPmBrief(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "PM brief",
-    artifact,
-    renderMarkdown: renderPmBriefMarkdown,
-    writeOutput: writePmBriefOutput,
-    outputJson: format === "json"
-  });
-}
-
-async function handleRoadmap(args) {
-  const input = getRequiredInput(args, "roadmap");
-  const format = getFlagValue(args, "--format");
-  const artifact = await createRoadmap(input, { format });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "roadmap",
-    artifact,
-    renderMarkdown: renderRoadmapMarkdown,
-    writeOutput: writeRoadmapOutput,
-    outputJson: format === "json"
-  });
-}
+  })
+});
+
+const handleExecSummary = createArtifactCommandHandler({
+  commandName: "exec-summary",
+  commandLabel: "exec summary",
+  createArtifact: createExecSummary,
+  renderMarkdown: renderExecSummaryMarkdown,
+  writeOutput: writeExecSummaryOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
+
+const handleFixPlan = createArtifactCommandHandler({
+  commandName: "fix-plan",
+  commandLabel: "fix plan",
+  createArtifact: createFixPlan,
+  renderMarkdown: renderFixPlanMarkdown,
+  writeOutput: writeFixPlanOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
+
+const handleOwnerBoard = createArtifactCommandHandler({
+  commandName: "owner-board",
+  commandLabel: "owner board",
+  createArtifact: createOwnerBoard,
+  renderMarkdown: renderOwnerBoardMarkdown,
+  writeOutput: writeOwnerBoardOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
+
+const handleMeetingPack = createArtifactCommandHandler({
+  commandName: "meeting-pack",
+  commandLabel: "meeting pack",
+  createArtifact: createMeetingPack,
+  renderMarkdown: renderMeetingPackMarkdown,
+  writeOutput: writeMeetingPackOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
+
+const handlePmBrief = createArtifactCommandHandler({
+  commandName: "pm-brief",
+  commandLabel: "PM brief",
+  createArtifact: createPmBrief,
+  renderMarkdown: renderPmBriefMarkdown,
+  writeOutput: writePmBriefOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
+
+const handleRoadmap = createArtifactCommandHandler({
+  commandName: "roadmap",
+  commandLabel: "roadmap",
+  createArtifact: createRoadmap,
+  renderMarkdown: renderRoadmapMarkdown,
+  writeOutput: writeRoadmapOutput,
+  getOptions: (args) => ({
+    format: getFlagValue(args, "--format")
+  })
+});
 
 async function handleReport(args) {
   const input = getRequiredInput(args, "report");

package/src/cli-shared.js

@@ -52,3 +52,64 @@ export async function writeOrPrintArtifact({
 
   process.stdout.write(renderedOutput);
 }
+
+export function createArtifactCommandHandler({
+  commandName,
+  commandLabel,
+  createArtifact,
+  renderMarkdown,
+  writeOutput,
+  getOptions
+}) {
+  return async function artifactCommandHandler(args) {
+    const input = getRequiredInput(args, commandName);
+    const options = getOptions ? getOptions(args) : {};
+    const artifact = await createArtifact(input, options);
+    const outputJson = options.format === "json" || hasFlag(args, "--json");
+
+    return writeOrPrintArtifact({
+      args,
+      commandName: commandLabel,
+      artifact,
+      renderMarkdown,
+      writeOutput,
+      outputJson
+    });
+  };
+}
+
+export function createPackCommandHandler({
+  commandName,
+  writePack,
+  renderMarkdown,
+  getOptions
+}) {
+  return async function packCommandHandler(args) {
+    const input = getRequiredInput(args, commandName);
+    const pack = await writePack(input, getOptions ? getOptions(args) : {});
+    process.stdout.write(renderMarkdown(pack));
+  };
+}
+
+export function createStructuredOutputCommandHandler({
+  commandLabel,
+  execute,
+  renderMarkdown,
+  writeOutput,
+  getOutputJson
+}) {
+  return async function structuredOutputCommandHandler(args) {
+    const result = await execute(args);
+    const outputJson = getOutputJson ? getOutputJson(args, result) : hasFlag(args, "--json");
+    const renderedOutput = outputJson ? `${JSON.stringify(result, null, 2)}\n` : renderMarkdown(result);
+    const outputPath = getFlagValue(args, "--out");
+
+    if (outputPath) {
+      const resolvedOutputPath = await writeOutput(outputPath, renderedOutput);
+      process.stdout.write(`已保存 ${commandLabel} 结果：${resolvedOutputPath}\n`);
+      return;
+    }
+
+    process.stdout.write(renderedOutput);
+  };
+}

package/src/cli-site-ops-commands.js

@@ -1,5 +1,10 @@
 import { auditProject, renderAuditMarkdown, writeAuditOutput } from "./audit.js";
-import { getFlagValue, hasFlag, parsePositiveInteger } from "./cli-shared.js";
+import {
+  createStructuredOutputCommandHandler,
+  getFlagValue,
+  hasFlag,
+  parsePositiveInteger
+} from "./cli-shared.js";
 import { renderDoctorMarkdown, runDoctor } from "./doctor.js";
 import {
   renderInteractiveOnboardingMarkdown,
@@ -23,74 +28,51 @@ export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization scan <project-path> [--json] [--out <file>] [--max-file-size <bytes>] [--max-examples <count>]"
 ];
 
-async function handleDoctor(args) {
-  const report = await runDoctor();
-  if (hasFlag(args, "--json")) {
-    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-    return;
-  }
-
-  process.stdout.write(renderDoctorMarkdown(report));
-}
-
-async function handleQuickStart(args) {
-  const outputJson = hasFlag(args, "--json");
-  const plan = createQuickStartPlan({});
-  const renderedOutput = outputJson ? `${JSON.stringify(plan, null, 2)}\n` : renderQuickStartMarkdown(plan);
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeQuickStartOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 quick start 输出：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleInteractiveOnboard(args) {
-  const report = await runInteractiveOnboarding({
-    url: getFlagValue(args, "--url"),
-    goal: getFlagValue(args, "--goal"),
-    existingAssets: getFlagValue(args, "--existing-assets")
-  });
-
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(report, null, 2)}\n`
-    : renderInteractiveOnboardingMarkdown(report);
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeInteractiveOnboardingOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存交互式 onboarding 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleOnboardUrl(args) {
-  const inputUrl = args.find((value) => !value.startsWith("-"));
-  if (!inputUrl) {
-    throw new Error("onboard-url requires a website URL");
-  }
-
-  const report = await analyzeWebsiteUrl(inputUrl, {});
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(report, null, 2)}\n`
-    : `${renderWebsiteOnboardingMarkdown(report)}\n`;
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeWebsiteOnboardingOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 onboarding 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
+const passthroughWriteOutput = async (outputPath) => outputPath;
+
+const handleDoctor = createStructuredOutputCommandHandler({
+  commandLabel: "doctor",
+  execute: async () => runDoctor(),
+  renderMarkdown: renderDoctorMarkdown,
+  writeOutput: passthroughWriteOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleQuickStart = createStructuredOutputCommandHandler({
+  commandLabel: "quick start",
+  execute: async () => createQuickStartPlan({}),
+  renderMarkdown: renderQuickStartMarkdown,
+  writeOutput: writeQuickStartOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleInteractiveOnboard = createStructuredOutputCommandHandler({
+  commandLabel: "交互式 onboarding",
+  execute: async (args) =>
+    runInteractiveOnboarding({
+      url: getFlagValue(args, "--url"),
+      goal: getFlagValue(args, "--goal"),
+      existingAssets: getFlagValue(args, "--existing-assets")
+    }),
+  renderMarkdown: renderInteractiveOnboardingMarkdown,
+  writeOutput: writeInteractiveOnboardingOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleOnboardUrl = createStructuredOutputCommandHandler({
+  commandLabel: "onboarding",
+  execute: async (args) => {
+    const inputUrl = args.find((value) => !value.startsWith("-"));
+    if (!inputUrl) {
+      throw new Error("onboard-url requires a website URL");
+    }
+
+    return analyzeWebsiteUrl(inputUrl, {});
+  },
+  renderMarkdown: (report) => `${renderWebsiteOnboardingMarkdown(report)}\n`,
+  writeOutput: writeWebsiteOnboardingOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
 
 async function handleInitLlms(args) {
   const targetDir = args.find((value) => !value.startsWith("-")) || ".";
@@ -133,61 +115,48 @@ async function handleInitSchema(args) {
   process.stdout.write(`Created ${result.schemaType} schema template at ${result.outputPath}\n`);
 }
 
-async function handleAudit(args) {
-  const projectPath = args.find((value) => !value.startsWith("-"));
-  if (!projectPath) {
-    throw new Error("audit requires a project path");
-  }
-
-  const report = await auditProject(projectPath, {
-    maxFileSize: getFlagValue(args, "--max-file-size")
-      ? parsePositiveInteger(getFlagValue(args, "--max-file-size"), "--max-file-size")
-      : undefined,
-    maxExamples: getFlagValue(args, "--max-examples")
-      ? parsePositiveInteger(getFlagValue(args, "--max-examples"), "--max-examples")
-      : undefined
-  });
-
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(report, null, 2)}\n`
-    : `${renderAuditMarkdown(report)}\n`;
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeAuditOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存审计结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleScan(args) {
-  const projectPath = args.find((value) => !value.startsWith("-"));
-  if (!projectPath) {
-    throw new Error("scan requires a project path");
-  }
-
-  const maxFileSizeValue = getFlagValue(args, "--max-file-size");
-  const maxExamplesValue = getFlagValue(args, "--max-examples");
-  const summary = await scanProject(projectPath, {
-    maxFileSize: maxFileSizeValue ? parsePositiveInteger(maxFileSizeValue, "--max-file-size") : undefined,
-    maxExamples: maxExamplesValue ? parsePositiveInteger(maxExamplesValue, "--max-examples") : undefined
-  });
-
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson ? `${JSON.stringify(summary, null, 2)}\n` : renderScanMarkdown(summary);
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeScanOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存扫描结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
+const handleAudit = createStructuredOutputCommandHandler({
+  commandLabel: "审计",
+  execute: async (args) => {
+    const projectPath = args.find((value) => !value.startsWith("-"));
+    if (!projectPath) {
+      throw new Error("audit requires a project path");
+    }
+
+    return auditProject(projectPath, {
+      maxFileSize: getFlagValue(args, "--max-file-size")
+        ? parsePositiveInteger(getFlagValue(args, "--max-file-size"), "--max-file-size")
+        : undefined,
+      maxExamples: getFlagValue(args, "--max-examples")
+        ? parsePositiveInteger(getFlagValue(args, "--max-examples"), "--max-examples")
+        : undefined
+    });
+  },
+  renderMarkdown: (report) => `${renderAuditMarkdown(report)}\n`,
+  writeOutput: writeAuditOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleScan = createStructuredOutputCommandHandler({
+  commandLabel: "扫描",
+  execute: async (args) => {
+    const projectPath = args.find((value) => !value.startsWith("-"));
+    if (!projectPath) {
+      throw new Error("scan requires a project path");
+    }
+
+    const maxFileSizeValue = getFlagValue(args, "--max-file-size");
+    const maxExamplesValue = getFlagValue(args, "--max-examples");
+
+    return scanProject(projectPath, {
+      maxFileSize: maxFileSizeValue ? parsePositiveInteger(maxFileSizeValue, "--max-file-size") : undefined,
+      maxExamples: maxExamplesValue ? parsePositiveInteger(maxExamplesValue, "--max-examples") : undefined
+    });
+  },
+  renderMarkdown: renderScanMarkdown,
+  writeOutput: writeScanOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
 
 export const SITE_OPS_COMMAND_HANDLERS = {
   doctor: handleDoctor,