Claude Code Workflow Studio 可视化编排 AI Agent 工作流

Claude Code 本身已经能处理不少编程任务，但当任务变复杂时，单次对话往往不够用。比如一次代码审查可能要经历拉取 Pull Request（拉取请求，PR）信息、扫描代码、判断风险等级、生成修复建议、让用户选择是否继续修改等多个步骤。每一步的角色、输入、输出和失败处理都不一样，如果全部靠手写提示词，很快就会变得难以维护。

Claude Code 原生支持通过 .claude/agents/ 和 .claude/commands/ 组织 Agent 与命令，但手写这些 Markdown 配置需要理解 frontmatter、目录结构、工具权限、模型选择等细节。Claude Code Workflow Studio 的价值就在这里：它把这些配置抽象成一个可视化工作流编辑器，让用户通过拖拽节点、连接路径、配置属性来设计 AI Agent 协作流程，最后导出为 Claude Code 能直接识别的文件。

它的定位不是替代 Claude Code，而是给 Claude Code 增加一层“流程设计器”。

项目概览

它的核心能力可以概括为四件事：

1. 在画布上设计多 Agent 工作流；
2. 把 Prompt、Sub-Agent、Skill、MCP 工具和条件分支连接起来；
3. 使用 AI 辅助修改现有工作流；
4. 将工作流导出到 .claude/agents/ 和 .claude/commands/。

它解决的具体问题

Claude Code 适合做单点任务，但复杂自动化任务通常有几个明显痛点。

它更适合“流程型 AI 任务”，而不是一次性问答。只要一个任务需要拆成多个环节、多个 Agent 或多个决策分支，就可以考虑用可视化工作流来管理。

工作流从设计到运行的整体结构

Claude Code Workflow Studio 的运行链路可以理解为：在 VSCode 里设计工作流，用 JSON 保存设计稿，再导出为 Claude Code 的 Markdown 配置文件，最后由 Claude Code 执行。

flowchart LR
    A[VSCode 中打开 Workflow Studio] --> B[拖拽节点设计工作流]
    B --> C[配置 Prompt、Agent、Skill、MCP 和分支]
    C --> D[保存为 JSON 工作流]
    D --> E[导出 .claude 文件]
    E --> F[.claude/agents/*.md]
    E --> G[.claude/commands/*.md]
    F --> H[Claude Code 执行]
    G --> H

这里有两个文件层面的产物：

JSON 工作流更像“源文件”，.claude 目录里的 Markdown 文件更像“编译输出”。平时可以反复修改 JSON 设计稿，确认流程稳定后再导出给 Claude Code 使用。

核心节点类型

Workflow Studio 的画布由节点和连线组成。节点代表一个处理步骤，连线代表数据流或控制流。

一个典型的工作流不是把所有逻辑塞进一个大 Agent，而是把任务拆小，让每个节点的职责足够清楚。

flowchart TD
    A[Prompt: 收集输入] --> B[Sub-Agent: 分析任务]
    B --> C{IfElse: 是否需要外部工具}
    C -- 是 --> D[MCP: 调用外部工具]
    C -- 否 --> E[Sub-Agent: 直接处理]
    D --> F{AskUserQuestion: 选择输出形式}
    E --> F
    F -- 摘要 --> G[Sub-Agent: 生成摘要]
    F -- 详细报告 --> H[Sub-Agent: 生成报告]

这种结构的好处是，流程的“骨架”非常清楚。之后要增加错误处理、加一个用户确认节点，或者把某个 Agent 换成 Skill，都不需要重写整段提示词。

Prompt 节点：把固定提示词模板化

Prompt 节点用于保存可复用的提示词模板。它支持变量语法，例如：

请分析下面的文件：

文件路径：{{filePath}}
分析目标：{{analysisGoal}}

输出要求：
1. 找出主要问题
2. 给出修改建议
3. 按严重程度排序

{{filePath}} 和 {{analysisGoal}} 是变量。运行时可以由用户输入、上游节点输出或其他配置填充。

Prompt 节点适合处理三类事情：

当提示词越来越长时，把它放进 Prompt 节点比散落在不同 Agent 配置中更容易维护。

Sub-Agent 节点：让不同 Agent 负责不同任务

Sub-Agent 是最常用的节点。它代表一个独立的 AI Agent，可以配置系统提示词、工具权限和模型。

一个代码审查 Agent 可能这样设计：

name: code-reviewer
description: 检查代码质量、安全风险和潜在 bug
tools:
  - Read
  - Grep
  - Glob
model: sonnet
systemPrompt: |
  你是一个代码审查 Agent。
  重点检查：
  1. 明显的 bug
  2. 安全风险
  3. 复杂度过高的函数
  4. 缺少测试的核心逻辑

  输出格式：
  - 问题位置
  - 严重程度
  - 原因
  - 修改建议

不同模型适合不同任务：

工具权限也应该按需开放。比如只需要读取代码时，不要给 Write 或 Bash 权限；需要执行测试时，再考虑开放 Bash。权限越精确，流程越可控。

Skill 节点：复用个人或项目能力

Claude Code Skills 可以理解为可复用能力包。Workflow Studio 能在画布中直接调用这些 Skill。

Skill 分为两类：

如果某个能力只服务个人习惯，比如自己的笔记整理格式，放在 Personal Skills 更合适。如果是团队统一使用的能力，比如项目文档生成规范、内部 API 分析规则，就应该放在 Project Skills，并纳入版本控制。

一个文档处理流程可以这样组织：

flowchart LR
    A[Prompt: 输入 PDF 路径] --> B[Skill: 提取 PDF 文本]
    B --> C{AskUserQuestion: 处理方式}
    C -- 摘要 --> D[Skill: 生成摘要]
    C -- 翻译 --> E[Skill: 翻译文档]
    C -- 分析 --> F[Sub-Agent: 深度分析]
    D --> G[Sub-Agent: 格式化结果]
    E --> G
    F --> G

Skill 节点适合沉淀稳定能力，Sub-Agent 更适合承担当前工作流里的具体任务。

MCP 节点：连接外部工具和服务

MCP 是 Model Context Protocol（模型上下文协议）的缩写，用来让 AI 系统调用外部工具。Workflow Studio 的 MCP 节点可以发现 Claude Code 中已经配置好的 MCP 服务器，并把工具调用放进工作流。

常见 MCP 使用场景包括：

需要注意的是，普通 Prompt、Sub-Agent、Skill 和本地工作流编辑不一定需要网络连接，但 MCP 节点是否联网取决于具体 MCP 服务器。例如 Playwright 访问网页时必然需要网络，内部数据库 MCP 则取决于数据库连接方式。

一个网页自动化流程可以这样设计：

sequenceDiagram
    participant U as 用户
    participant W as Workflow Studio
    participant M as Playwright MCP
    participant A as Sub-Agent

    U->>W: 输入目标 URL
    W->>M: 打开网页
    M-->>W: 返回页面信息
    W->>U: 询问操作类型
    U-->>W: 选择截图、提取文本或点击元素
    W->>M: 执行浏览器操作
    M-->>W: 返回结果
    W->>A: 分析并格式化输出
    A-->>U: 返回最终结果

MCP 节点的优势是把“AI 决策”和“外部工具执行”连接起来。Agent 不只是在文本里给建议，还能调用真实工具完成动作。

条件分支：让工作流具备控制流

复杂任务很少是一路执行到底的。Workflow Studio 提供了三类常见分支节点。

IfElse：二元分支

IfElse 适合只有两个结果的判断：

• 是否通过校验；
• 工具调用是否成功；
• 用户是否确认继续；
• 扫描结果是否存在高危问题。

flowchart TD
    A[Sub-Agent: 校验输入] --> B{IfElse: 校验是否通过}
    B -- 通过 --> C[继续处理]
    B -- 不通过 --> D[Sub-Agent: 生成错误说明]

Switch：多路分支

Switch 适合多个互斥路径，例如根据任务类型分流：

flowchart TD
    A[Prompt: 输入任务] --> B{Switch: 任务类型}
    B -- 代码审查 --> C[Code Review Agent]
    B -- 文档总结 --> D[Document Summary Agent]
    B -- 数据分析 --> E[Data Analysis Agent]
    B -- 测试生成 --> F[Test Writer Agent]

AskUserQuestion：把人工决策放进流程

AskUserQuestion 用于让用户在流程中做选择，通常支持 2 到 4 个选项，也可以设计成多选。它适合处理那些不应该完全交给 AI 自动决定的步骤，比如：

• 代码问题只处理高危项，还是全部处理；
• 文档输出摘要版，还是详细版；
• 自动修复前是否需要用户确认；
• 失败后重试、跳过还是终止。

人工决策节点的意义是让流程既能自动化，又不失控。

安装和打开编辑器

使用 AI 辅助编辑功能前，需要先安装 Claude Code CLI（Command Line Interface，命令行工具）。可以用下面的命令验证：

claude --version

如果命令不存在，需要先安装 Claude Code。

安装 VSCode 扩展有两种方式。

方式一：通过 VSCode 扩展商店安装

1. 打开 VSCode；
2. 按 Ctrl+Shift+X，macOS 使用 Cmd+Shift+X；
3. 搜索 Claude Code Workflow Studio；
4. 点击安装。

方式二：从源码构建 VSIX

git clone https://github.com/breaking-brake/cc-wf-studio.git
cd cc-wf-studio

npm install

cd src/webview
npm install
cd ../..

npm run build
npx vsce package

生成 .vsix 文件后，在 VSCode 中选择 Install from VSIX... 安装。

打开编辑器的方式：

1. 按 Ctrl+Shift+P，macOS 使用 Cmd+Shift+P；
2. 输入 Claude Code Workflow Studio: Open Editor；
3. 回车打开可视化编辑器。

首次打开会出现交互式引导，支持英文、日文、韩文、简体中文和繁体中文。工具栏中的 ? 按钮可以重新启动引导。

设计一个工作流的基本步骤

完整操作链路如下：

flowchart TD
    A[从左侧节点面板选择节点] --> B[拖拽到画布]
    B --> C[点击节点并配置属性]
    C --> D[从输出端口拖线到输入端口]
    D --> E[填写工作流名称]
    E --> F[Save 保存 JSON]
    F --> G[Export 导出 .claude 文件]
    G --> H[在 Claude Code 中使用]

节点面板通常按功能分组：

保存和导出是两个不同动作：

Save   -> 保存画布设计到 .vscode/workflows/
Export -> 生成 Claude Code 使用的 .claude/agents/ 和 .claude/commands/

开发过程中可以频繁 Save，流程确认后再 Export。

示例：数据分析工作流

数据分析任务通常包含数据收集、分析方式选择和报告生成，可以拆成下面的流程：

flowchart LR
    A[Sub-Agent: 收集数据] --> B{AskUserQuestion: 选择分析类型}
    B -- 统计分析 --> C[Sub-Agent: 统计分析]
    B -- 可视化 --> D[Sub-Agent: 数据可视化]
    C --> E[Sub-Agent: 生成报告]
    D --> E

对应的步骤说明：

这种设计比一个大提示词更容易调试。如果可视化效果不稳定，只需要调整 Data Visualization 节点，不会影响其他步骤。

示例：代码审查工作流

代码审查工作流可以加入优先级选择，让用户控制输出范围。

flowchart TD
    A[Sub-Agent: 扫描代码问题] --> B{AskUserQuestion: 审查范围}
    B -- 仅关键问题 --> C[Sub-Agent: 过滤高危问题]
    B -- 所有问题 --> D[Sub-Agent: 整理完整问题列表]
    C --> E[Sub-Agent: 生成修复建议]
    D --> E

这个流程适合处理两类情况：

• 时间紧，只想先解决阻塞合并的关键问题；
• 需要完整审查，希望一次性列出所有风险和改进点。

如果后续要增加自动修复，可以在 Generate Fix Suggestions 后面接一个用户确认节点，再决定是否进入写文件节点。

示例：PR 审查加 MCP 和错误处理

当工作流需要读取 GitHub PR 信息时，可以通过 MCP 调用外部工具。因为外部工具可能失败，所以应该把失败路径显式画出来。

flowchart TD
    A[Prompt: 输入 PR 地址] --> B[MCP: 获取 PR 详情]
    B --> C{IfElse: 获取是否成功}
    C -- 成功 --> D[Sub-Agent: 分析代码变更]
    C -- 失败 --> E[Sub-Agent: 生成错误说明和重试建议]
    D --> F{AskUserQuestion: 输出级别}
    F -- High --> G[Sub-Agent: 只输出高危问题]
    F -- Medium --> H[Sub-Agent: 输出中高风险问题]
    F -- Low --> I[Sub-Agent: 输出完整建议]

这个例子体现了工作流编排里很重要的一点：外部依赖必须有失败路径。没有错误处理的自动化流程，一旦 MCP 工具超时或返回格式变化，就会卡在中间。

AI 辅助修改工作流

Workflow Studio 支持用自然语言修改画布。操作方式是打开或创建工作流后，点击工具栏中的 Edit with AI，输入修改要求，然后应用变更。确认结果符合预期后接受修改，不符合预期则取消。

适合输入给 AI 的请求应该具体、可验证，例如：

Add error handling when the MCP tool fails to fetch PR details.

Add a Sub-Agent node that validates user input before processing.

Connect the error output of the validator to a new error handler Sub-Agent.

Change the AskUserQuestion node to have 3 options instead of 2: High, Medium, Low.

复杂修改最好拆成多个小请求：

1. Add a Skill node that reads PDF files.
2. Connect it after the input Prompt node.
3. Add error handling if the PDF read fails.

更稳妥的拆法是分三次执行：

AI 辅助编辑的准确率和请求清晰度关系很大。像 make it better 这种模糊请求很难得到稳定结果，因为它没有说明要增加节点、修改连接，还是调整配置。更好的写法是明确节点类型、连接关系和目标行为。

AI 辅助编辑的错误处理

使用 AI 修改工作流时，常见错误可以按下面的方式排查。

AI 辅助修改不是越长越好。一次请求只改一小块，确认后再继续，通常比一次性要求重构整个流程更稳定。

适合和不适合的使用场景

可视化工作流的优势是让流程稳定、可复用、可协作。如果任务每次都完全不同，设计工作流反而可能增加额外成本。

使用限制

当前需要注意这些限制：

50 个节点对大多数工作流已经足够。实际使用中，3 到 10 个节点通常就能覆盖一个清晰任务。如果一个流程接近 50 个节点，更应该考虑拆分，而不是继续堆节点。

与手写 .claude 配置的取舍

Workflow Studio 并不禁止手写配置。导出的 .claude 文件本质上仍然是带 frontmatter 的 Markdown，可以继续手动编辑。

一种实用方式是：用 Workflow Studio 搭好主流程和节点关系，再根据需要微调导出的 Markdown 文件。这样既能降低初始设计成本，也保留了 Claude Code 配置本身的灵活性。

技术栈结构

Claude Code Workflow Studio 是一个 VSCode 扩展，前端画布基于 React Flow 构建。

整体结构可以理解为 VSCode 扩展承载一个 Webview 画布，用户在画布上编辑工作流，扩展负责保存 JSON、读取本地 Claude Code 相关目录，并导出 Markdown 配置。

flowchart LR
    A[VSCode Extension] --> B[Webview UI]
    B --> C[React 组件]
    C --> D[React Flow 画布]
    A --> E[本地文件系统]
    E --> F[.vscode/workflows JSON]
    E --> G[.claude/agents Markdown]
    E --> H[.claude/commands Markdown]
    A --> I[Claude Code CLI]

这种实现方式适合本地开发环境：工作流设计、保存、导出都围绕当前项目目录进行，不需要把项目代码上传到第三方服务。

使用建议

几个实践原则可以让工作流更稳定：

一个可维护的 AI 工作流应该像普通程序一样：职责清晰、错误路径明确、复用逻辑集中管理。Workflow Studio 只是把这些工程化原则放到了可视化画布上。

小结

Claude Code Workflow Studio 适合把 Claude Code 的多步骤任务变成可视化、可保存、可导出的工作流。它通过 Prompt、Sub-Agent、Skill、MCP 和条件分支节点，把复杂 AI Agent 协作拆成清楚的流程结构，并生成 Claude Code 能直接使用的 .claude 配置。

如果任务只是一次简单问答，直接使用 Claude Code 更省事；如果任务需要多个 Agent 协作、外部工具调用、用户中途决策或反复迭代优化，可视化工作流会更容易维护。项目地址是：

https://github.com/breaking-brake/cc-wf-studio