企业官网建设流程全解析

• AI 应用
• Agent 工作流
• 开发工具
• MCP 服务

本篇文章以 001-ai-workflow-generation/research.md 为核心骨架，结合仓库内 CLI 执行、Schema 加载、工作流验证与提示词构建等源码实现展开。CC Workflow Studio的 "AI-Assisted Workflow Generation"（001-ai-workflow-generation）特性，允许用户用自然语言描述工作流意图，由本地 Claude Code CLI 一次性（one-shot）生成合法的工作流 JSON 并直接落到画布上。读完本文，你将掌握：如何在 VSCode 扩展中安全地执行外部 AI CLI 进程、如何设计面向 AI 上下文的紧凑 Schema 文档、如何在加入画布前对 AI 输出做多层验证，以及如何构建结构化的提示词与可操作的错误处理策略。

1. 特性背景：从调研到设计的五问框架

该特性源于一个明确的用户诉求：将"把 workflow JSON 文件的规则整理成文档，再让用户用自然语言委托本地 Claude Code 生成工作流"的流程产品化。在设计阶段，团队将全部技术未知点收敛为五个研究问题（Research Questions），每个问题都经历"决策 → 理由 → 备选方案 → 实现要点 → 参考依据"的完整论证：

这份调研的直接产出物已在仓库中落地：CLI 执行服务位于 claude-code-service.ts（注释明确标注 "Based on: /specs/001-ai-workflow-generation/research.md Q1"），验证工具位于 validate-workflow.ts（标注 "Based on: /specs/001-ai-workflow-generation/research.md Q3"），Schema 加载服务位于 schema-loader-service.ts（标注 "Based on: /specs/001-ai-workflow-generation/research.md Q2"）。下文逐一拆解每个决策及其实战形态。

2. Q1：如何在 VSCode 扩展中执行 Claude Code CLI

2.1 决策：spawn()而非exec()/execFile()

调研文档给出的结论非常明确：VSCode 扩展运行在 Node.js 环境中，对child_process模块拥有完整访问权（无沙箱限制），因此：

• spawn()：首选。支持流式输出，能精确控制进程生命周期（stdin/stdout/stderr 均可管道化），可配合AbortController（Node 15+）或手动kill()实现超时；
• exec()：API 简单但会将全部输出缓冲在内存中，不支持流式，不适合可能长时间运行的 AI 请求；
• execFile()：与exec()有类似局限；
• 外部 npm 包（如 execa）：增加依赖但收益有限，内置 API 足够。

调研文档给出了伪代码模式：spawn('claude', ['-p', prompt], { timeout: 30000, stdio: ['ignore','pipe','pipe'] })，通过stdout.on('data')累积输出、process.on('error')处理 ENOENT、process.on('exit')解析结果。

2.2 源码落地：从child_process到nano-spawn

实际实现比调研文档更进一步。由于 Windows 兼容性问题（Issue #79），claude-code-service.ts 使用nano-spawn替代裸child_process.spawn()，实现跨平台进程派生，同时保留了nodeChildProcess（底层 ChildProcess 句柄）以便手动 kill。

核心执行入口executeClaudeCodeCLI()的参数签名：

export async function executeClaudeCodeCLI( prompt: string, timeoutMs = 60000, // 默认 60 秒 requestId?: string, // 支持取消 workingDirectory?: string, model: ClaudeModel = 'sonnet', // 'sonnet' | 'opus' | 'haiku' allowedTools?: string[] ): Promise<ClaudeCodeExecutionResult>

命令构造细节（源码 L127-L147）：

const args = ['-p', '-', '--model', modelName]; if (allowedTools && allowedTools.length > 0) { args.push('--tools', allowedTools.join(',')); args.push('--allowed-tools', allowedTools.join(',')); }

值得注意的两个工程细节：

1. prompt 通过 stdin 传入而非-p参数：-p -表示从 stdin 读取提示词，规避了 Windows 命令行长度限制（注释明确说明）；
2. 模型别名：getCliModelName()将ClaudeModel直接映射为 CLI 接受的别名（sonnet/opus/haiku）。

2.3 流式执行与会话延续

为提升用户体验，仓库还实现了executeClaudeCodeCLIStreaming()（源码 L482），使用--output-format stream-json --verbose获取实时输出，通过for await (const chunk of subprocess.stdout)逐行解析 JSON Lines：

• 从system/init消息提取session_id，供后续--resume会话延续；
• 识别assistant消息中的tool_use内容（Read/Bash/Task/Glob/Grep/Edit/Write），将其作为工具调用指示实时展示；
• 将纯文本内容与工具调用指示分离：displayText（含工具信息，用于界面展示）与explanatoryText（纯解释文本，用于保留到聊天历史）。

2.4 取消机制

cancelGeneration(requestId)（源码 L410）通过activeProcessesMap 登记进行中的子进程：先kill()发送优雅终止（Unix 下为 SIGTERM），500ms 后若进程未退出则强制二次 kill（Windows 下为无条件终止），并返回实际执行耗时。这与功能规格 spec.md 中"用户关闭生成对话框时请求应被优雅取消，不向画布添加半成品"的边界用例一致。

3. Q2：工作流 Schema 文档应该用什么格式

3.1 决策：面向 AI 上下文的精简自定义 JSON

调研文档明确了"不用纯 JSON Schema"：

• 纯 JSON Schema：工业标准但过于冗长——$ref、allOf、definitions会显著膨胀体积，超出 AI 上下文窗口预算（目标 <10KB）；
• TypeScript 定义：不适合 AI 直接消费，需要二次转换；
• 纯文本 Markdown：结构化程度低，难以被程序化解析；
• 自定义 JSON：针对 Claude Code 的工作流领域裁剪，聚焦节点类型、字段、校验规则等关键信息，示例驱动（要求 3 个以上完整示例引导 AI 生成）。

调研文档给出了 Schema 的轮廓结构：schemaVersion+metadata（description / maxNodes / supportedNodeTypes）+nodeTypes（每个节点含 description / fields / constraints）+connectionRules（如 "Start node cannot have input connections"）+validationRules+examples。

3.2 源码落地：真实 Schema 文件解析

仓库中的实际产物是 packages/core/resources/workflow-schema.json，共 1335 行，结构与调研轮廓一一对应：

{ "schemaVersion": "1.0.0", "metadata": { "description": "Workflow schema for CC Workflow Studio", "maxNodes": 100, "supportedNodeTypes": ["start", "end", "prompt", "subAgent", "askUserQuestion", "ifElse", "switch", "skill", "mcp", "subAgentFlow", "codex", "branchSession", "group"] }, "nodeTypes": { ... }, ... }

注意一个有趣的差异：调研阶段设定 maxNodes=50（spec.md 的 FR-003/FR-017 也写 50），但实际VALIDATION_RULES.WORKFLOW.MAX_NODES为100（见 workflow-definition.ts L656-L663），schema 文件的 metadata.maxNodes 也是 100。这体现了从研究到实现的演进——实际上限以源码VALIDATION_RULES为准，VSCode 扩展还会把用户配置的最大节点数作为maxNodes选项传入验证器覆盖默认值（见 validate-workflow.ts L38-L44 的ValidateOptions）。

以prompt节点为例，真实 schema 字段：

"prompt": { "description": "A step executed by the main orchestrator (your current session, where you can talk to the user).", "fields": { "label": { "type": "string", "required": false }, "prompt": { "type": "string", "required": true, "maxLength": 10000 }, "variables": { "type": "object", "required": false } }, "inputPorts": 1, "outputPorts": 1 }

subAgent节点的 model 字段还给出了完整枚举：["sonnet","opus","haiku","fable","inherit"]（默认sonnet），以及agentType（claudeCode/other）、commandFilePath、commandScope等进阶字段——这些枚举值直接约束着 AI 的输出合法性。

3.3 加载与缓存：JSON / TOON 双格式

schema-loader-service.ts 负责加载并缓存 Schema（避免每次请求都读盘），支持两种格式：

• loadWorkflowSchema()：读取resources/workflow-schema.json并JSON.parse，缓存于模块级cachedJsonSchema；
• loadWorkflowSchemaToon()：读取同名.toon文件返回原始字符串（从 json 路径推导：schemaPath.replace('.json', '.toon')）；
• loadWorkflowSchemaByFormat()：按SchemaFormat选择，TOON 加载失败时自动回退到 JSON。

TOON 是该项目采用的紧凑结构化文本格式，注释指出"相比自由文本可减少约 7% token 消耗"（见 refinement-prompt-builder.ts L5），这是对"面向 AI 上下文优化"目标的持续演进。默认 Schema 路径为extensionPath/resources/workflow-schema.json（getDefaultSchemaPath()）。

4. Q3：如何验证 AI 生成的工作流

4.1 决策：复用现有验证逻辑 + AI 特定检查

调研文档给出的策略是"不重复造轮子"：直接复用VALIDATION_RULES常量（节点上限、命名模式、字段约束）与 TypeScript 接口的编译期类型安全，再补充运行时检查：

• 节点数 ≤ 上限；
• 连接合法（无环、无非法源/目标）；
• 每种节点类型的必填字段齐全；
• 字段值在约束范围内（如描述长度、选项数量）。

调研还对比了三个备选方案：ajv等 JSON Schema 校验库（已有 TypeScript 类型则无需引入依赖）、从头手写校验（易错、重复逻辑）、完全不校验（不安全，畸形数据会崩溃 UI）。

4.2 源码落地：validateAIGeneratedWorkflow的完整检查链

实际实现位于 validate-workflow.ts，入口函数validateAIGeneratedWorkflow(workflow: unknown, options)返回{ valid, errors: ValidationError[] }，检查链如下：

其中validateNodeSchemaFields()的实现非常精巧：遍历NODE_PROPERTY_SCHEMAS[node.type]注册表（node-schema-registry.ts），只校验data 上实际存在的字段（undefined跳过，保证旧工作流文件可加载），visibleWhen谓词失败的字段视为非激活跳过。这让校验器与属性面板共享同一份 zod 定义，"零漂移"地保持一致性。

4.3 关键常量速查（来自 workflow-definition.ts L656+）

• WORKFLOW.MAX_NODES = 100，NAME_PATTERN = /^[a-z0-9_-]+$/（全小写，保证跨平台文件系统兼容），VERSION_PATTERN = /^\d+\.\d+\.\d+$/；
• NODE.NAME_PATTERN = /^[a-zA-Z0-9_-]+$/，最长 50 字符；
• SUB_AGENT：description ≤ 200、prompt ≤ 10000、固定 1 个输出端口；
• ASK_USER_QUESTION：问题 ≤ 500、选项 2~4 个、标签 ≤ 50、描述 ≤ 200；
• BRANCH/SWITCH：条件 ≤ 500、分支 2~10 个；IF_ELSE固定 2 分支 2 输出端口；
• SKILL：name pattern/^[a-z0-9-]+$/最长 64、description ≤ 1024、固定 1 输出端口；
• MCP：serverId ≤ 100、toolName ≤ 200、toolDescription ≤ 2048、固定 1 输出端口；
• CODEX：prompt ≤ 10000；BRANCH_SESSION：label ≤ 50。

这些常量既是人工创建工作流的护栏，也是 AI 生成内容通过验证的"分数线"。

5. Q4：构建携带 Schema 的 AI 提示词

5.1 决策：结构化提示词而非最小提示词

调研文档明确否定了三种替代方案：

• 最小提示词（仅用户描述 + Schema）：过于模糊，产出不稳定；
• Few-shot 提示（在提示词中内嵌示例）：增加 token 开销，而 Schema 自带的examples已足够；
• Chain-of-thought（先解释再生成）：更慢，对结构化输出没必要。

最终采用五段式结构化提示词：role（"You are an expert workflow designer for CC Workflow Studio"）→task（生成合法 workflow JSON）→schema reference（内嵌完整 Schema 文档）→output format（"只输出符合 Workflow 接口的合法 JSON，不要解释"）→constraints（maxNodes=50、连接合法、必须含 Start/End、节点 ID 唯一、必填字段齐全）。

调研文档给出的模板（pseudo-code）通过模板字符串注入userDescription与JSON.stringify(workflowSchema, null, 2)，并明确输出格式为{"id": "generated-workflow-{timestamp}", "name": "...", "nodes": [...], "connections": [...]}。

5.2 源码落地：从模板到 TOON 结构化对象

实际实现中，提示词构建已演进为结构化对象 + TOON 编码。以工作流细化（refinement）为例，refinement-prompt-builder.ts 的buildPrompt()将encode(structured)序列化，结构化对象包含：

• role/task/responseLocale；
• currentWorkflow：完整节点（含全部 data，避免 AI 重写未变节点）、连接、subAgentFlows；
• workflowSchema：schemaResult.schemaString || JSON.stringify(schemaResult.schema)（优先 TOON 原始字符串）；
• outputFormat：成功/澄清/错误三种示例（status字段区分）；
• criticalRules：如"必须只输出一个 JSON 对象""不要把 workflow JSON 与 status JSON 分开输出""不要用 ```json 代码块包裹"；
• 条件性的codexNodeConstraints、previousValidationErrors（上次校验失败时的错误恢复指令）。

这与调研文档 Q4 的决策一脉相承：结构化、强约束、单次输出。而 workflow-name-generation.ts 展示了另一条提示词落地路径——WorkflowNamePromptBuilder构建提示词后调用executeClaudeCodeCLI(prompt, timeoutMs, requestId, workspaceRoot, 'haiku')用 haiku 模型生成名字，再经parseName()清洗为 kebab-case（去 markdown 修饰、归一化连字符、截断 64 字符、空值回退untitled-workflow）。

5.3 输出解析：容忍 AI 的各种"答非所问"

AI 不总是严格输出裸 JSON。claude-code-service.ts 的parseClaudeCodeOutput()实现了四级解析策略：

1. 若以```json开头并以```结尾，仅剥离标记后解析；
2. 若以{开头，按裸 JSON 直接解析；
3. 提取全部```json...```块，优先选择含status字段的结构化响应（从末尾往前找，因为结构化响应通常在最后），找不到则取最后一个块；
4. 兜底按原文本JSON.parse。

解析失败返回null，由上层转为用户友好的"Generation failed"错误——对应 spec.md 中"AI 返回畸形 JSON"的边界用例。

6. Q5：Claude Code CLI 未安装怎么办

6.1 决策：惰性检测 + 可操作错误信息

调研文档明确了"不做预检"：在扩展激活时检查 CLI 是否存在会拖慢 VSCode 启动，且对不使用 AI 生成的用户是纯粹干扰。正确做法是用户真正触发生成时才检测（fail-fast），并给出明确错误："Claude Code CLI not found. Please install it..."。检测命令为 Unix 的spawn('which', ['claude'])或 Windows 的spawn('where', ['claude'])。

备选方案均被否定：激活时检查（拖慢启动）、捆绑 Claude Code 到扩展（CLI 独立维护与授权，不可行）、让用户手动填写安装路径（UX 过重）。

6.2 源码落地：三级 CLI 路径探测 + 错误码体系

实际的路径检测比调研文档更精细。claude-cli-path.ts 实现了三级探测顺序：

1. VSCode 默认终端 shell（findExecutableViaDefaultShell('claude')）：通过登录 shell 获取完整 PATH，解决 GUI 启动的 VSCode 不继承用户 shell PATH 的问题（Issue #375），并兼容 mise/nvm 等版本管理器；
2. 直接 PATH 查找（findExecutableInPath('claude')）：作为终端启动 VSCode 场景的兜底；
3. npx 回退：若 claude 不存在，getClaudeSpawnCommand()会尝试通过默认 shell 找到 npx，再回退到 PATH 中的 npx，最终以npx claude ...方式调用。

路径结果带缓存（cachedClaudePath：undefined=未检查、null=未找到、string=可执行路径），并暴露clearClaudeCliPathCache()供测试或用户会话中安装 CLI 后刷新。

执行错误被归一化为ClaudeCodeExecutionResult.error.code枚举（L65-L82）：

超时判定尤其值得注意：nano-spawn 可能只设置exitCode = 143（128 + SIGTERM），因此代码同时检查两种信号以稳健识别超时。此外，流式执行在超时/出错时仍会返回已累积的部分输出（output: accumulated），尽量保住 AI 已生成的内容。

6.3 多 Provider 抽象

随着特性演进，ai-provider.ts 在 Claude Code 之上建立了统一抽象层executeAi()/executeAiStreaming()/cancelAiRequest()，按 provider 路由：

• claude-code→executeClaudeCodeCLI(Streaming)（含 allowedTools、resumeSessionId 会话延续）；
• copilot→ VS Code Language Model API（executeVsCodeLm，要求 VS Code 1.89+，无会话延续能力）；
• codex→executeCodexCLI(Streaming)（OpenAI Codex CLI，含codexModel与codexReasoningEffort）。

isProviderAvailable()中 Claude Code 恒返回可用（CLI 缺失留给运行时错误，正是 Q5 决策的直接体现），而 Copilot/Codex 则做前置可用性检查。这印证了调研的"惰性检测"哲学：对默认主力 CLI 不预检，对需要前置条件（安装扩展/特定版本）的 provider 才检查。

7. 调研结论与实现现状对照

调研文档的 Summary 声明五个技术未知点全部解决，可以进入 Phase 1（Design & Contracts）。将结论与仓库现状逐条对照：

1. CLI 执行：child_process.spawn()+ 超时 + 错误处理 → 落地为 claude-code-service.ts 的 nano-spawn 实现，并扩展出流式输出、会话续延、取消三件套；
2. Schema 格式：面向 AI 上下文的紧凑 JSON（约 5-10KB）→ 落地为 resources/workflow-schema.json（13 种节点类型、schemaVersion 1.0.0），并衍生 TOON 双格式与加载缓存；
3. 验证：复用 TypeScript 类型与验证规则 + AI 特定检查 → 落地为 validate-workflow.ts 的validateAIGeneratedWorkflow（覆盖类型、必填、数量、节点、连接、Start/End、SubAgentFlow 引用全链路）；
4. 提示词工程：结构化提示词（role/task/schema/output format/constraints）→ 落地为 refinement-prompt-builder.ts 的 TOON 结构化对象 + workflow-name-generation.ts 的名称生成链；
5. 错误处理：运行时检测 CLI 缺失 + 可操作信息 → 落地为 claude-cli-path.ts 的三级路径探测与六类错误码体系。

需要留意的两处"研究→实现"差异：其一，最大节点数从调研/规格阶段的50调整为源码常量的100（VALIDATION_RULES.WORKFLOW.MAX_NODES），且 VSCode 扩展可传入用户配置覆盖；其二，调研文档引用的外部资源链接（Node.js 文档、JSON Schema 规范、ReactFlow 校验模式等）属于行业背景参考，实际验证逻辑完全由仓库内 TypeScript 类型、zod 属性注册表与手写检查实现，未引入任何额外校验库依赖——这一点与 Q3 的决策保持一致。

对于想深入源码的读者，建议按此顺序阅读：先读 research.md 与 spec.md 理解需求全貌，再对照 claude-code-service.ts、validate-workflow.ts、schema-loader-service.ts 三个"标注了研究出处"的实现文件，最后用 workflow-schema.json 与 workflow-definition.ts 的VALIDATION_RULES作为校验事实基准。

• AI 应用
• Agent 工作流
• 开发工具
• MCP 服务