CC Workflow Studio 数据模型全解析：从 Workflow 实体到 .claude 导出格式的设计与实现

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

本文是 CC Workflow Studio（一个用于在 VSCode 中可视化设计 Claude Code SlashCommand + Sub-Agent 工作流的扩展项目）数据模型层面的深度技术指南。文章以仓库中 001-cc-wf-studio 数据模型规格 为主干，结合 workflow-definition.ts 等源码实现，系统讲解 Workflow / Node / Connection 三大核心实体及其字段、校验规则、状态迁移，并完整给出.vscode/workflows/*.json与.claude/agents|commands/*.md的存储与导出格式。读完本文，你将能够：理解编辑器（React Flow + Zustand）、持久层（JSON）与运行时（Claude Code 配置）三者之间的数据流转关系，掌握每个字段的取值范围与默认值，并依据校验规则排查工作流定义文件的问题。

1. 数据模型概览：一张图看懂三层结构

CC Workflow Studio 的数据模型（Data Model）定义了一个完整工作流从"画布编辑"到"Claude Code 可执行"的中间表示，分为三层：

1. 编辑层（Editor Model）：工作流在 VSCode Webview 中通过 React Flow 渲染为WorkflowNode（节点）与WorkflowEdge（连线），状态由 Zustand store 统一管理；
2. 持久层（Persisted Model）：保存为.vscode/workflows/{name}.json的 JSON 文件，保留节点位置、连接等全部结构信息，供再次打开编辑；
3. 运行层（Runtime Model）：导出为.claude/agents/*.md（Sub-Agent 配置）与.claude/commands/*.md（SlashCommand），由 Claude Code 直接识别执行。

核心设计意图（规格文档中的设计决策 DD-001）："保存"与"导出"是两个独立操作。JSON 定义文件面向"再编辑"，.claude目录面向"执行"，两者解耦，既保证了可逆编辑，又让生成的 Claude Code 配置保持纯净。

2. 核心实体（Core Entities）

2.1 Workflow：工作流根实体

Workflow 是"由多个节点及其连接关系构成的可执行定义"，是所有数据的根容器。

字段定义

TypeScript 定义

interface Workflow { id: string; name: string; description?: string; version: string; nodes: WorkflowNode[]; connections: Connection[]; createdAt: Date; updatedAt: Date; metadata?: WorkflowMetadata; } interface WorkflowMetadata { tags?: string[]; author?: string; [key: string]: unknown; }

该定义在源码 workflow-definition.ts 中得到了完整落地，并在此基础上扩展了schemaVersion、conversationHistory（AI 辅助精修会话）、subAgentFlows（可复用的子流程）、slashCommandOptions（SlashCommand 导出选项，含 hooks/context/model 等）与tour（导览步骤）等字段——这些是后续版本在 MVP 数据模型之上的增量。

校验规则（Workflow Level）

• name：1-100 字符，仅允许英数字与-、_，且必须可作为合法文件名；
• version：语义化版本格式（如1.0.0、2.1.3）；
• nodes：最大 50 节点（NFR-001）；
• connections：循环引用仅警告（MVP 不检测，见 Edge Cases）。

源码佐证：校验规则被集中定义在VALIDATION_RULES常量中（workflow-definition.ts），其中工作流名称使用NAME_PATTERN: /^[a-z0-9_-]+$/（强制小写，以保证跨平台文件系统兼容性）。保存命令 save-workflow.ts 在落盘前会对id、name、version、节点数量做同样的检查；节点数上限可通过 VSCode 设置cc-wf-studio.workflow.maxNodes调整（见 workflow-settings-service.ts）。

2.2 Node：工作流中的一个处理单元

MVP 数据模型支持2 种节点类型：AgentSkills（Sub-Agent）与AskUserQuestion。

基础节点字段

NodeType 枚举

enum NodeType { AgentSkill = 'agentSkill', AskUserQuestion = 'askUserQuestion' }

Position

interface Position { x: number; // 像素单位 y: number; // 像素单位 }

与源码的差异说明：在 workflow-definition.ts 中，NodeType已演进为包含subAgent、askUserQuestion、branch、ifElse、switch、start、end、prompt、skill、mcp、subAgentFlow、codex、branchSession、group等 14 种类型的完整枚举，其中branch被标注为// Legacy: 后向兼容。MVP 文档定义的agentSkill/askUserQuestion属于该演进的第一阶段，本文后续仍以 MVP 文档中的两个核心节点（Sub-Agent 与 AskUserQuestion）为主线展开。

2.3 SubAgentNode：调用 Claude Code Sub-Agent 的节点

Sub-Agent 节点用于在流程中调用一个 Claude Code Sub-Agent，是 MVP 中"执行单元"的载体。

字段定义

SubAgentData

TypeScript 定义

interface SubAgentNode extends Node { type: 'subAgent'; data: SubAgentData; } interface SubAgentData { description: string; prompt: string; tools?: string; model?: 'sonnet' | 'opus' | 'haiku'; outputPorts: number; }

校验规则

• name：1-50 字符，仅英数字与-、_，转小写后用作文件名；
• description：1-200 字符，用自然语言说明 Sub-Agent 目的；
• prompt：1-10000 字符，不允许纯空白；
• tools：逗号分隔的工具名列表（如"Read,Write,Bash"），省略时拥有全部工具访问权；
• model：sonnet/opus/haiku之一，缺省为sonnet；
• outputPorts：固定值 1（MVP）。

源码佐证：

• VALIDATION_RULES.SUB_AGENT（workflow-definition.ts）精确对应以上约束：DESCRIPTION_MIN_LENGTH: 1、DESCRIPTION_MAX_LENGTH: 200、PROMPT_MAX_LENGTH: 10000、OUTPUT_PORTS: 1。
• Sub-Agent 的属性面板由 schema 驱动（sub-agent-schema.ts），其model字段已扩展为['sonnet', 'opus', 'haiku', 'fable', 'inherit']五选一，其中haiku、fable被标记为仅 Claude Code 支持的模型（CC_ONLY_MODELS）；tools使用tools控件、model使用select控件渲染。
• 画布上 Sub-Agent 节点组件（SubAgentNode.tsx）展示了description（标题）、prompt（两行截断预览）、model/memory/color徽标，以及左侧input输入端口与右侧output输出端口各一个，与outputPorts: 1的模型约束一致。

2.4 AskUserQuestionNode：条件分叉节点

AskUserQuestion 节点借助 Claude Code 的 AskUserQuestion 工具实现基于用户选择的条件分支，是 MVP 中"分支"能力的载体。

字段定义

AskUserQuestionData 与 QuestionOption

TypeScript 定义

interface AskUserQuestionNode extends Node { type: 'askUserQuestion'; data: AskUserQuestionData; } interface AskUserQuestionData { questionText: string; options: QuestionOption[]; outputPorts: number; // 2-4 } interface QuestionOption { label: string; description: string; }

校验规则

• questionText：1-500 字符，建议使用疑问句形式；
• options：2-4 个元素的数组，必填；
• options[].label：1-50 字符；
• options[].description：1-200 字符；
• outputPorts：范围 2-4，且必须与options.length一致。

源码佐证：

• 约束在VALIDATION_RULES.ASK_USER_QUESTION（workflow-definition.ts）中逐一落地：OPTIONS_MIN_COUNT: 2、OPTIONS_MAX_COUNT: 4、QUESTION_MAX_LENGTH: 500、OPTION_LABEL_MAX_LENGTH: 50、OPTION_DESCRIPTION_MAX_LENGTH: 200。
• 属性 schema（ask-user-question-schema.ts）对options数组声明了.min(2).max(4)（编辑器 UI 的增删边界），并提供了deriveAskUserQuestionUpdate归一化函数：当选项增删时自动把outputPorts同步为options.length，从而在数据层保证"端口数 = 选项数"这一约束始终成立。
• 画布节点组件（AskUserQuestionNode.tsx）按options的数量动态渲染右侧branch-0、branch-1……输出端口，端口位置按((i + 1) / (options.length + 1)) * 100%均分——这正是"可変分岐ポート（DD-004：2-4 个）"在 UI 层的实现。
• 加载旧版工作流文件时，若options缺少稳定的id（React key 需要），node-data-normalize.ts 会在反序列化时一次性补齐opt-*形式的 ID，避免在渲染阶段修改状态。

2.5 Connection：节点间的执行顺序

Connection 表示两个节点之间的执行先后关系，是工作流"图"结构的边。

字段定义

TypeScript 定义

interface Connection { id: string; from: string; // Node ID to: string; // Node ID fromPort: string; // Handle ID toPort: string; // Handle ID condition?: string; // Option label for AskUserQuestion branches }

校验规则

• from/to：必须指向工作流中已存在的节点 ID；
• fromPort/toPort：必须是节点实际拥有的端口 ID；
• condition：仅当连接从 AskUserQuestion 节点出发时才设置，且必须与某个选项标签一致；
• 循环引用：MVP 不检测（见 Edge Cases）。

源码佐证：连接校验在 validate-workflow.ts 的validateConnections中实现，除"节点存在性、端口 ID、条件一致"外，还额外拦截自连接（SELF_CONNECTION）、重复连接 ID、Start 节点被连入、End 节点被连出以及 Group 节点的连入/连出等非法情形。React Flow 的 Edge 数据（source/target/sourceHandle/targetHandle）在 workflow-store.ts 的createWorkflowFromCanvas中被转换为Connection时，condition取自edge.data?.condition。

3. React Flow 集成类型：编辑层的桥接

为了与 React Flow 库无缝集成，数据模型定义了专门的桥接类型：

import { Node as RFNode, Edge as RFEdge } from 'reactflow'; // React Flow Node 类型的定制 type WorkflowNode = | RFNode<SubAgentData, 'subAgent'> | RFNode<AskUserQuestionData, 'askUserQuestion'>; // React Flow Edge 类型的定制 type WorkflowEdge = RFEdge<{ label?: string }>; // React Flow State（由 Zustand store 管理） interface ReactFlowState { nodes: WorkflowNode[]; edges: WorkflowEdge[]; }

源码佐证：该设计在 workflow-store.ts 中落地——store 内部直接持有 React Flow 的Node[]/Edge[]，通过onNodesChange、onEdgesChange、onConnect三个回调接收画布交互（拖动、删除、连线）产生的变化；createWorkflowFromCanvas/setActiveWorkflow等函数则负责Node/Edge ↔ Workflow的双向转换。store 使用 Zustand 的temporal中间件（zundo）提供撤销/重做（undo/redo）能力，切换工作流时会清空历史以防止跨工作流撤销。

4. 文件存储格式：JSON 与 .claude 导出

4.1 工作流定义文件（.vscode/workflows/{name}.json）

工作流定义以 JSON 形式保存，完整的规范化示例如下（覆盖 4 节点 + 3 条连接，含 AskUserQuestion 分支）：

{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "sample-workflow", "description": "サンプルワークフロー", "version": "1.0.0", "nodes": [ { "id": "node-1", "type": "subAgent", "name": "data-analysis", "position": { "x": 100, "y": 100 }, "data": { "description": "データ分析を実行するSub-Agent", "prompt": "データ分析を実行してください", "tools": "Read,Write,Bash", "model": "sonnet", "outputPorts": 1 } }, { "id": "node-2", "type": "askUserQuestion", "name": "next-step-selection", "position": { "x": 300, "y": 100 }, "data": { "questionText": "次のステップを選択してください", "options": [ { "label": "レポート作成", "description": "分析結果をレポート化" }, { "label": "データ可視化", "description": "グラフやチャートを作成" } ], "outputPorts": 2 } }, { "id": "node-3", "type": "subAgent", "name": "report-generation", "position": { "x": 500, "y": 50 }, "data": { "description": "レポートを生成するSub-Agent", "prompt": "レポートを生成してください", "model": "sonnet", "outputPorts": 1 } }, { "id": "node-4", "type": "subAgent", "name": "data-visualization", "position": { "x": 500, "y": 150 }, "data": { "description": "データを可視化するSub-Agent", "prompt": "データを可視化してください", "model": "sonnet", "outputPorts": 1 } } ], "connections": [ { "id": "edge-1", "from": "node-1", "to": "node-2", "fromPort": "output", "toPort": "input" }, { "id": "edge-2", "from": "node-2", "to": "node-3", "fromPort": "branch-0", "toPort": "input", "condition": "レポート作成" }, { "id": "edge-3", "from": "node-2", "to": "node-4", "fromPort": "branch-1", "toPort": "input", "condition": "データ可視化" } ], "createdAt": "2025-11-01T00:00:00.000Z", "updatedAt": "2025-11-01T12:00:00.000Z" }

要点解读：

• node-2的options有 2 个选项，因此outputPorts为 2，connections中对应branch-0/branch-1两条输出；
• condition字段的值与选项标签（レポート作成/データ可視化）逐一对应，这是导出时生成分支逻辑的关键；
• 保存路径固定为项目根目录下的.vscode/workflows/（见 file-service.ts 的workflowsDirectory = path.join(workspacePath, '.vscode', 'workflows')），序列化时使用 2 空格缩进（JSON.stringify(workflow, null, 2)，见 save-workflow.ts）。

仓库中另有最小可运行样例 sample-workflow.json（start → prompt → end 三段式，connections可省略fromPort/toPort，对应默认端口），可作为快速验证 CLI 渲染与冒烟测试的参考。

4.2 Claude Code 配置导出格式

工作流导出后生成两类.claude文件，全部为 Markdown + YAML frontmatter 格式，UTF-8 编码。

Sub-Agent 配置文件（.claude/agents/{node-name}.md）

每个 Sub-Agent 节点对应一个文件：

--- name:>--- description: サンプルワークフロー allowed-tools: Task,AskUserQuestion --- まず、Taskツールを使用して「data-analysis」Sub-Agentを実行してください。 次に、AskUserQuestionツールを使用して以下の質問をユーザーに行ってください: - 質問: "次のステップを選択してください" - 選択肢: - "レポート作成" → Taskツールで「report-generation」Sub-Agentを実行 - "データ可視化" → Taskツールで「data-visualization」Sub-Agentを実行 ユーザーの選択に応じて、対応するSub-Agentを実行してください。

执行逻辑的书写方式：

• 使用 Task 工具按顺序调用 Sub-Agent；
• 使用 AskUserQuestion 工具进行分支控制；
• 采用"技术性描述"风格（显式指示工具调用），这是设计决策 DD-003 的体现——相比自然语言描述，技术性描述的执行更严格、可预测，便于调试。

源码佐证：

• 现代版本的导出把 SlashCommand 生成迁移到generateSlashCommandFile（workflow-export.ts）：frontmatter 除description外还可输出allowed-tools、model、context、disable-model-invocation、argument-hint及hooks（PreToolUse/PostToolUse/Stop），正文则包含Mermaid 流程图（generateMermaidFlowchart）与Workflow Execution Guide（generateExecutionInstructions，按节点类型给出执行方法：Sub-Agent 用 Task、分支用 AskUserQuestion 等）。
• 导出后的文件会经过validateClaudeFileFormat做契约校验（frontmatter 完整性、UTF-8 合法性、name/description/model等必填字段存在性、正文非空），校验失败会阻止导出（见 export-workflow.ts）。
• 另外，仓库当前已把工作流入口迁移到.claude/skills/{workflow-name}/SKILL.md（Agent Skills 目录 + SKILL.md 形式，正文仍由generateSlashCommandFile生成）——这是规格文档撰写后随 Claude Code 生态演进产生的存储位置变化，阅读旧文档时应留意。

导出操作与冲突处理（DD-005）

• 目标：.claude配置文件集（Sub-Agent 配置 + SlashCommand）；
• 保存位置：.claude/agents/与.claude/commands/（当前实现为.claude/agents/与.claude/skills/{name}/SKILL.md）；
• 冲突处理：目标文件已存在时弹出覆盖确认对话框，用户选择"覆盖"或"取消"（由checkExistingFiles预先收集已存在文件列表，见 export-service.ts），防止误覆盖手工编辑的 Claude Code 配置。

5. 状态迁移（State Transitions）

数据模型还定义了工作流与节点在生命周期中的状态迁移图。

5.1 工作流生命周期

┌──────────┐ │ Draft │ 初始创建状态 └────┬─────┘ │ save() ▼ ┌──────────┐ │ Saved │ 已保存到文件 └────┬─────┘ │ export() ▼ ┌──────────┐ │ Exported │ 已导出为 .claude 形式 └──────────┘ │ modify() ▼ ┌──────────┐ │ Modified │ 导出后有修改 └────┬─────┘ │ export() ▼ ┌──────────┐ │ Exported │ 重新导出 └──────────┘

四个状态：Draft（新建未保存）→Saved（保存到 JSON）→Exported（导出为 .claude）→Modified（导出后再次编辑）。其中Modified状态是"保存/导出分离"设计的直接产物：导出后继续编辑不会自动同步.claude目录，必须再次显式导出，避免产生"画布与运行配置不一致"的隐性漂移。

5.2 节点编辑状态

┌──────────┐ │ Unselected │ 未选中状态 └────┬───────┘ │ click() ▼ ┌──────────┐ │ Selected │ 选中（属性面板显示） └────┬─────┘ │ edit() ▼ ┌──────────┐ │ Editing │ 编辑中（输入框聚焦） └────┬─────┘ │ blur() ▼ ┌──────────┐ │ Modified │ 有变更（未保存） └────┬─────┘ │ save() ▼ ┌──────────┐ │ Saved │ 已保存 └──────────┘

节点侧的状态迁移：Unselected（未选中）→Selected（选中，右侧属性面板渲染该节点的属性表单）→Editing（编辑中）→Modified（改动未保存）→Saved。这套状态机与 Webview 的交互绑定：点击节点即打开属性面板（见 workflow-store.ts 中setSelectedNodeId会自动openPropertyOverlay），属性面板依据 node-schema-registry.ts 注册的 schema 动态渲染控件（textarea、select、tools、checkbox、objectArray 等）。

6. 校验规则汇总（Validation Summary）

数据模型在各层级定义了可操作的校验矩阵：

工作流层级

• ✅ 工作流名称：1-100 字符，可作为合法文件名；
• ✅ 版本号：语义化版本格式；
• ✅ 节点数量：最多 50 节点；
• ⚠️ 循环引用：MVP 不检测（仅警告）。

节点层级

• ✅ 节点名称：1-50 字符，仅英数字与-、_；
• ✅ AgentSkill 提示词：1-10000 字符，不允许纯空白；
• ✅ AskUserQuestion 提问文本：1-500 字符；
• ✅ AskUserQuestion 选项：2-4 个，每个标签 1-50 字符、说明 1-200 字符。

连接层级

• ✅ 起始/终止节点：必须存在于工作流内；
• ✅ 端口 ID：必须与节点实际拥有的端口一致；
• ✅ 条件：来自 AskUserQuestion 节点的连接，条件必须与某个选项标签一致。

源码佐证：除上述"手写规则"外，validate-workflow.ts 的validateAIGeneratedWorkflow还通过NODE_PROPERTY_SCHEMAS注册表对节点data中已存在的字段做 zod 类型级校验（如model枚举成员、options数组边界等），并支持maxNodes参数覆盖默认节点上限。校验错误以code + message + field结构化返回，导出命令在导出前执行该校验，不通过则终止并列出全部错误（见 export-workflow.ts）。

7. 扩展点（Extension Points / Future）

以下能力在 MVP 中不做实现，但数据模型已在设计上为它们预留了空间：

• 新增节点类型：向NodeType枚举添加成员，并定义对应的NodeData接口；
• 节点特有配置：可在data对象上追加任意字段；
• 工作流元数据：可在metadata对象上添加任意自定义字段；
• 校验规则扩展：为各实体追加新的校验方法；
• 状态管理扩展：向 Zustand store 增加新的 action。

源码佐证：这一"可扩展"设计已被后续演进验证——NodeType从 2 种扩充到 14 种（workflow-definition.ts），Workflow增加了subAgentFlows、slashCommandOptions、tour等可选字段；节点属性 schema 注册表 node-schema-registry.ts 与FieldMeta（field.ts）把"字段的 zod 校验、渲染控件、导出目标适用性"集中声明在一处，新增节点类型时只需"编辑nodes/<type>-schema.ts+ 注册 + 补充 i18n 标签"，并用AssertAssignable编译期守卫保证 schema 与公开接口不漂移。

8. 相关文档索引（References）

本数据模型规格属于001-cc-wf-studio特性分支文档族的一部分，关联文档与实现源码如下：

• 功能规格： spec.md
• 实施计划： plan.md
• 快速上手： quickstart.md
• 调研报告： research.md
• 核心类型实现： workflow-definition.ts
• 节点属性 schema： sub-agent-schema.ts、ask-user-question-schema.ts
• 校验器实现： validate-workflow.ts
• 导出格式实现： workflow-export.ts、workflow-prompt-generator.ts
• 扩展命令实现： save-workflow.ts、export-workflow.ts
• 前端状态与节点组件： workflow-store.ts、SubAgentNode.tsx、AskUserQuestionNode.tsx

结语：数据模型是"画布 ↔ 文件 ↔ 执行"三者的共同契约

CC Workflow Studio 的数据模型不是一份纸面文档，而是编辑器、JSON 持久层与 Claude Code 运行配置共同遵守的一份契约：React Flow 画布上的每一次拖拽最终都会被序列化为nodes/connectionsJSON；而每次导出，都会被转换回Sub-Agent的 frontmatter 与 SlashCommand 的执行指令。理解Workflow/Node/Connection的字段语义与校验边界（名称小写化、选项与端口数同步、condition 与选项标签对应、保存与导出分离），既是排查工作流定义问题的第一把钥匙，也是向项目贡献新节点类型时最值得先读的起点。

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