企业官网建设流程全解析

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

本篇技术指南围绕 CC Workflow Studio（cc-wf-studio）内置的cc-workflow-ai-editor技能展开，它让 AI 客户端通过cc-workflow-studioMCP 服务器的get_workflow_schema、get_current_workflow、apply_workflow、update_nodes等工具，以对话方式在画布上创建与编辑可视化 AI Agent 工作流。读完本文，你将掌握六步交互式编辑流程、两套工作流应用策略（整图应用与节点局部更新）的取舍、Group Node（分组容器）的 JSON 结构与校验规则，以及从源码层理解这些工具背后的校验、修订号（revision）冲突检测与 TOON 优化模式传输机制。

技能定位与触发场景

cc-workflow-ai-editor是仓库中.roo/skills/cc-workflow-ai-editor/SKILL.md定义的 Agent 技能。其 frontmatter 明确声明了适用场景：当用户想要在 CC Workflow Studio 中新建工作流、修改既有工作流、或通过内置 MCP 服务器编辑画布时，应启用本技能。技能名称中的 "AI editor" 强调的是"以对话方式驱动画布编辑"——AI 不直接操作鼠标，而是通过 MCP 工具读写工作流 JSON，由 VSCode 扩展或文件适配器把 JSON 落到画布上。

技能还约定了最低依赖：AI 客户端需能访问名为cc-workflow-studio的 MCP 服务器。仓库中的 .roo/mcp.json 展示了这类客户端的典型接入配置：

{ "mcpServers": { "cc-workflow-studio": { "type": "streamable-http", "url": "http://127.0.0.1:6289/mcp" } } }

该 URL 对应 VSCode 扩展内置 HTTP MCP 服务器的流式传输端点（canvas 模式的默认端口为 6282，此处 6289 为实际运行实例采用的端口；端口冲突时扩展会自动回退到系统分配的可用端口，见下文"画布模式"小节）。

六步交互式编辑工作流

技能正文给出的编辑流程是整篇文章的核心骨架，共六步，形成一个"读取 → 确认 → 生成 → 应用 → 反馈"的闭环：

1. 调用get_workflow_schema（经cc-workflow-studioMCP 服务器）——获取工作流结构文档，理解合法的节点/连接/字段形态；
2. 调用get_current_workflow（经同一 MCP 服务器）——读取当前画布上的活动工作流 JSON，作为修改的基线；
3. 询问用户要创建或修改什么——把编辑意图落在具体需求上；
4. 生成工作流 JSON——默认使用内置子代理（builtInType: explore / plan / general-purpose）；仅当用户明确要求使用某个已有自定义子代理时，才调用list_available_agents枚举；
5. 应用变更（经 MCP 服务器）：
   • 新建工作流或结构性变更（增删节点/连线）→ 使用apply_workflow；
   • 对既有节点的局部更新（改名称、位置或 data）→ 使用update_nodes（更省 token）；
   • 出现错误则修复；
6. 征求用户反馈，从第 4 步重复。

这套循环的工程含义是：AI 每次变更都以"先读 schema、再读现状"开局，避免凭记忆生成过期结构；而第 4 步的"默认内置子代理"策略，则是为了减少不必要的 MCP 往返——list_available_agents只有在用户点名要用自定义 agent 时才值得调用。

为什么 get_workflow_schema 返回 TOON 格式

第 1 步获取的 schema 并非普通 JSON，而是经过 TOON 优化的格式。从 packages/core/scripts/generate-toon-schema.ts 可以看到，构建期脚本会把resources/workflow-schema.json编码为workflow-schema.toon，并统计体积缩减比例（脚本打印JSON size、TOON size与Size reduction）。

在 packages/mcp/src/tools.ts 中，get_workflow_schema的实现直接把 TOON schema 作为原始文本返回（{ content: [{ type: 'text', text: result.schema }] }），注释明确写道：这样 AI 客户端可以流式接收 schema，无需解析 JSON 信封。这一设计直接服务于技能第 1 步的"先看结构"诉求——schema 是 AI 生成合法 JSON 的权威依据。

工具全景：MCP 服务器注册的 6 个工具

技能只点名的 4 个工具（schema / current / apply / update），实际 MCP 服务器共注册 6 个工具。packages/mcp/src/tools.ts 中的registerWorkflowTools一次注册了：

get_current_workflow：修订号与陈旧数据标记

get_current_workflow的返回包含success、isStale、revision与workflow。其中isStale为 true 表示编辑器未打开、工作流来自缓存（tools.ts）。revision是两种模式下的不透明修订标识符（packages/mcp/src/types.ts）：

• canvas 适配器：字符串化的数字计数器，如'42'；
• 文件适配器：文件内容的sha256:<hex>哈希。

为什么 AI 编辑流程必须重视 revision？因为apply_workflow/update_nodes都接受可选的revision参数做乐观锁：如果调用方传入的修订号与服务器当前值不一致，应用会被拒绝或给出警告，从而避免"AI 基于旧快照覆盖用户最新修改"的并发冲突。技能第 5 步的"Fix errors if any"同样覆盖这类冲突错误——遇到Revision conflict时应重新调用get_current_workflow拉取最新基线再重试。

apply_workflow：整图应用与校验门禁

apply_workflow接受一个 JSON 字符串形式的完整工作流，应用前会先经过validateAIGeneratedWorkflow校验（tools.ts）。值得注意的两个行为：

• SubAgent 节点自动落盘：工具描述说明"没有commandFilePath的 SubAgent 节点会在.claude/agents/下自动创建.md文件"——这是通过适配器接口planAndPersistSubAgentFiles实现的（types.ts），返回的autoCreatedFiles数组会带给调用方以便透明告知用户。不过该行为依赖适配器：canvas 模式为"视觉优先"返回空数组（文件在 export/run 阶段才物化），文件模式同样返回空数组。
• 审查模式：若用户开启了 review 模式，应用前会弹出 diff 预览，用户接受后变更才落地；被拒绝时返回错误User rejected the changes。所以 AI 应在被拒后停止应用并询问用户意图，而不是盲目重试。

update_nodes：局部更新省 token 的原理

update_nodes内部流程（tools.ts）：先取当前工作流 → 校验所有目标节点 ID 存在（不存在的 ID 会返回Nodes not found: ...并提示用get_current_workflow查可用 ID）→ 深拷贝当前工作流 → 逐节点合并更新 → 校验 → 应用。

其合并语义值得 AI 生成器注意：

• data是浅合并进节点现有 data 的；把某个字段设为null即删除该字段（如{"commandFilePath": null}删除 commandFilePath）；
• 若变更节点 type，则必须同时提供data，且此时 data 是整体替换而非合并（否则返回When changing node type, data must also be provided to match the new type schema）；
• parentId设为null表示把节点移出分组；
• style主要用于 group 节点尺寸。

这就是技能第 5 步"部分更新用 update_nodes"的原因：它不需要 AI 重新生成并传输整张工作流 JSON，只传增量字段，token 消耗显著更低。

list_available_agents：何时才值得调用

该工具扫描用户域（~/.claude/agents/）与项目域（<project-root>/.claude/agents/）下的.mdagent 文件（文件模式的扫描实现在 packages/mcp/src/file-adapter.ts，会解析 frontmatter 的description）。includeContent: true可附带完整 prompt 内容，但默认只返回 name / description / scope / path。技能第 4 步刻意限制其使用频率，正是为了把默认路径收敛到三种内置子代理（见下文），减少上下文占用。

内置子代理：explore / plan / general-purpose

技能第 4 步规定：默认使用builtInType: explore / plan / general-purpose。这三种预设定义在 packages/core/src/constants/built-in-sub-agents.ts：

从 packages/core/src/schema/nodes/sub-agent-schema.ts 的字段定义看，model与tools在设置了builtInType时变为只读（readonlyWhen: isBuiltIn，并提示subAgent.builtIn.controlledByPreset），即模型和工具由 Claude Code 预设接管，AI 不应再为内置子代理自行指定 model/tools。同时校验器规定builtInType与commandFilePath/commandScope互斥（validate-workflow.ts）。

SubAgent 节点 data 中与这些预设相关的完整字段可参见 packages/core/src/types/workflow-definition.ts 的SubAgentData：description、agentDefinition、prompt、model（可选sonnet | opus | haiku | fable | inherit）、tools、memory、color、outputPorts等。其中model与color等为 Claude Code 专属字段，导出到其他 AI 工具时会被省略。

Group Node：画布上的视觉容器

技能后半部分专门讲解了 Group Node，这是 AI 编辑画布时最容易产生无效 JSON 的节点类型之一，规则高度结构化：

规则清单

• Group 节点type固定为"group"，且必须有data.label（显示名）；
• 必须携带style: { width, height }定义可视区域；
• Group 节点不能有任何连线（不能有进出边）；
• 把节点放入分组：设置子节点的parentId为分组节点的id；
• 子节点的position相对分组左上角，而非画布原点；
• Group 节点的name字段不参与校验（可留空或省略）。

官方示例 JSON

技能给出如下示例（原样继承）：

{ "nodes": [ { "id": "group-1", "type": "group", "name": "", "position": { "x": 100, "y": 100 }, "style": { "width": 400, "height": 300 }, "data": { "label": "Data Processing" } }, { "id": "node-1", "type": "subAgent", "name": "fetch-data", "parentId": "group-1", "position": { "x": 50, "y": 50 }, "data": { "description": "Fetch data from API", "outputPorts": 1 } } ] }

注意示例的语义：group-1画布坐标为 (100, 100)，宽 400 高 300；node-1的position是 (50, 50) —— 因为它在组内，实际画布位置约等于 (150, 150)。

源码级佐证：校验器如何执行这些规则

这些规则不是文档层面的"建议"，而是硬性校验逻辑，全部可以在 packages/core/src/utils/validate-workflow.ts 中找到对应实现：

• name 豁免：validateNodes中if (node.type !== NodeType.Group)才检查name的正则/^[a-zA-Z0-9_-]+$/（L293-L302），所以 group 的name可以为空；
• label 必填：GROUP_MISSING_LABEL——Group node must have a label（L367-L377）；
• parentId 指向必须是 group：INVALID_PARENT_TYPE—— 引用非 group 类型节点会报错；引用不存在的节点报INVALID_PARENT_ID（L379-L395）；
• 禁止连线：Group node cannot have output connections与Group node cannot have input connections（L1009-L1024）。

此外，Group 节点的属性 schema 在 packages/core/src/schema/nodes/group-schema.ts 中只有label一个可编辑字段（文本控件），并存在编译期防漂移守卫（GroupSchemaFieldNamesGuard等），确保 UI 面板与校验器使用同一份 zod 定义。

前端渲染与执行高亮

packages/vscode/src/webview/src/components/nodes/GroupNode.tsx 展示了 Group 节点的视觉实现：虚线边框、可拖拽调整尺寸（NodeResizer，最小 200×150）、顶部 label 标题栏，以及高亮态——当highlightedGroupNodeId与节点 id 匹配时，边框变为实线并启用highlightPulse脉冲动画。这正是第 6 个 MCP 工具highlight_group_node的用途：AI 在"执行分组内节点前"调用它，让用户在画布上直观看到当前执行进度（传入空字符串清除高亮）。这也再次印证了技能开头对 Group Node 的定义：它不影响工作流执行，纯粹是视觉组织与执行追踪的容器。

校验与错误修复：AI 生成 JSON 的质量闸门

技能第 5 步提到"Fix errors if any"。apply_workflow/update_nodes在落盘前都会调用validateAIGeneratedWorkflow（validate-workflow.ts），AI 生成器应重点规避以下高频错误码：

• INVALID_FORMAT：工作流name必须是[a-z0-9_-]（小写，跨平台文件系统兼容），版本必须是\d+\.\d+\.\d+；
• MAX_NODES_EXCEEDED：默认上限 100 个节点（VSCode 扩展可传入用户配置值覆盖）；
• MISSING_START_NODE/MULTIPLE_START_NODES/MISSING_END_NODE：必须有且仅有一个 Start 节点、至少一个 End 节点；
• DUPLICATE_NODE_ID/DUPLICATE_CONNECTION_ID：ID 全局唯一；
• INVALID_NODE_NAME：节点名匹配[a-zA-Z0-9_-]（Group 除外）；
• INVALID_PARENT_TYPE：parentId只能指向 group 类型节点；
• INVALID_CONNECTION：连线两端节点必须存在；Start 不能有入边、End 不能有出边、Group 双向禁止连线；
• SELF_CONNECTION：节点不能自连；
• NODE_SCHEMA_VIOLATION：节点 data 字段不符合注册的属性 schema（例如 SubAgent 的model必须是sonnet | opus | haiku | fable | inherit、builtInType必须是三种预设之一）。

一个便于 AI 理解的设计是：校验器对节点 data 字段的检查是保守的——只校验"已存在"的字段，undefined跳过，visibleWhen谓词不满足的字段跳过（L241-L273），这让旧版工作流文件保持可加载，也意味着 AI 生成时应尽量"少填无用字段"。

运行环境：两种 MCP 适配模式

技能所述"经cc-workflow-studioMCP 服务器"实际由两套适配器之一承接（packages/mcp/src/types.ts），理解二者差异有助于判断 AI 编辑流程的边界行为：

画布模式（VSCode 扩展内置）

packages/vscode/src/extension/services/mcp-server-service.ts 中的McpServerManager实现WorkflowIoAdapter：HTTP 服务器默认监听127.0.0.1，端口 6282（被占时回退到系统分配端口），通过 postMessage RPC 驱动实时 webview 画布。关键特性：

• 带 DNS rebinding 防护（校验 Host/Origin 头，非 localhost 拒绝并返回 403）；
• get_current_workflow超时 10 秒；带审查的apply_workflow超时 120 秒；
• 编辑器关闭时返回lastKnownWorkflow缓存并标记isStale: true；
• 默认reviewBeforeApply = true，即 AI 的每次整图应用都会先给用户看 diff。

文件模式（ccwf-mcp / ccwf mcp）

独立 binccwf-mcp（packages/mcp/src/mcp.ts）与 CLI 子命令ccwf mcp --file <path>（packages/cli/src/commands/mcp.ts）都基于 packages/mcp/src/file-adapter.ts 的FileWorkflowAdapter：无画布、无 webview，直接读写单个.json文件。行为差异：

• revision 是文件内容的sha256:<hex>；应用时做原子写（临时文件 + rename），并在expectedRevision不匹配时拒绝写入并返回Revision conflict；
• highlight_group_node是 no-op（返回成功并附带说明highlight_group_node is canvas-only; no-op in file mode）；
• 不自动创建.claude/agents/*.md—— 使用文件模式时，AI 应为 SubAgent 节点提供完整的commandFilePath；
• 通过--project-root指定扫描项目域 agent 的根目录。

文件模式的一个典型接入是把它注册进 Claude Code 的.mcp.json（参见 packages/cli/skills/ccwf-cli/SKILL.md 中的示例）：

{ "mcpServers": { "cc-wf-studio": { "type": "stdio", "command": "npx", "args": ["@cc-wf-studio/cli", "mcp", "--file", ".vscode/workflows/my-workflow.json"] } } }

实战建议与最佳实践

结合技能流程与源码实现，面向 AI Agent 的编辑操作建议如下：

1. 每次编辑会话从 get_workflow_schema 开始：不要凭记忆生成节点结构，TOON schema 是唯一权威；它按 token 优化过，成本可控。
2. 区分 apply_workflow 与 update_nodes 的使用边界：新建/增删节点/改连线用apply_workflow（整图）；仅改名称、位置或 data 字段用update_nodes（增量、更省 token、且自带"节点不存在"前置检查）。
3. 尊重 revision 乐观锁：从get_current_workflow拿到的 revision 尽量回传；遇到Revision conflict或User rejected the changes时停止重试，重新读取现状再协商。
4. 内置子代理优先：builtInType: explore / plan / general-purpose是默认路径，list_available_agents仅在用户点名自定义 agent 时调用；注意内置预设的 model/tools 由 Claude Code 控制，不要与commandFilePath混用。
5. Group Node 三件套：type: "group"+data.label+style；子节点给parentId，且position写组内相对坐标；永远不要给 group 加连线。
6. 应用前自查高频错误：name 小写、版本语义化、恰好一个 Start、至少一个 End、节点/连线 ID 唯一、parentId指向 group。
7. 注意模式的边界：画布模式有审查对话框与高亮能力，文件模式无画布反馈、不自动生成 agent 文件——AI 应根据实际接入模式调整对用户的提示预期。

相关实现文件速查

• 技能定义：.roo/skills/cc-workflow-ai-editor/SKILL.md
• MCP 工具注册：packages/mcp/src/tools.ts
• 适配器接口与结果类型：packages/mcp/src/types.ts
• 画布模式适配器：packages/vscode/src/extension/services/mcp-server-service.ts
• 文件模式适配器：packages/mcp/src/file-adapter.ts
• 工作流校验器：packages/core/src/utils/validate-workflow.ts
• 工作流数据模型与校验规则常量：packages/core/src/types/workflow-definition.ts
• 内置子代理预设：packages/core/src/constants/built-in-sub-agents.ts
• Group 属性 schema：packages/core/src/schema/nodes/group-schema.ts
• SubAgent 属性 schema：packages/core/src/schema/nodes/sub-agent-schema.ts
• Group 画布组件：packages/vscode/src/webview/src/components/nodes/GroupNode.tsx
• TOON schema 生成：packages/core/scripts/generate-toon-schema.ts

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