企业官网建设流程全解析

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

CC Workflow Studio 通过 MCP 工具get_workflow_schema将workflow-schema.json（TOON 版）作为运行时规范直接交付给 AI 编辑器，决定 AI 如何选择节点类型、如何组装工作流。本文基于仓库内 workflow-schema-tuning/SKILL.md 的调优方法论，系统讲解 Schema 的真实作用、设计哲学、构建流水线与偏差审计清单，并给出可直接执行的修改、验证与提交流程，帮助你精准校准 AI 生成工作流的行为倾向。

认识 workflow-schema.json：交付给 AI 的"提示规范"而非运行时校验器

在动手修改 Schema 之前，必须先建立正确的认知模型：Schema 不是类型定义，而是提示工程（prompt engineering）。

workflow-schema.json 是 CC Workflow Studio 在 AI 编辑会话中通过 MCP 工具get_workflow_schema交付给 AI 的主要规范。它的作用不是对工作流做运行时校验——实际上运行时几乎不做校验。Schema 里写什么，AI 就信什么，因此对 Schema 的任何修改都应被视为在修改 AI 的行为提示，而不是在修正类型系统。

这一点有清晰的源码佐证：在 packages/mcp/src/tools.ts 中，registerGetWorkflowSchema将 Schema 以原始文本（raw text）形式返回，注释明确指出"这样 AI 客户端无需解析 JSON 信封即可流式接收"，且工具描述写着"Get the workflow schema documentation in optimized TOON format"。而在 packages/mcp/src/file-adapter.ts 中，getWorkflowSchemaToon通过import.meta.resolve('@cc-wf-studio/core/resources/workflow-schema.toon')直接读取 TOON 文件内容。

从另一个角度印证：apply_workflow工具在应用前调用的是validateAIGeneratedWorkflow（见 tools.ts），它校验的是生成结果的结构完整性，而 Schema 文本本身影响的是AI 的决策倾向。两者职责完全不同。

核心设计原则：校准方向，而非规定规则

SKILL.md 反复强调的核心原则是align direction, do not prescribe rules（校准方向，而非规定规则）：

AI 已经直觉性地知道如何在节点类型之间做选择（例如何时委派给子代理、何时在上下文中直接处理）。修复糟糕输出的方法几乎从来不是"加更多规则"，而是"移除把 AI 往错误方向偏置的内容"。

默认做法（Defaults）

• 优先使用极简的 description 文本，只陈述每个节点的位置角色（立ち位置）。例如："由主编排代理执行的步骤"对比"由隔离子代理执行的步骤"——对比本身就在起作用（The contrast does the work）。
• 避免编写aiGenerationGuidance式的"何时使用 / 何时不用 / 反模式"清单。这类清单把 AI 当作规则引擎，膨胀 token 消耗，并且在未预见的场景下失效。
• 先测试极简方案：只有在出现具体失败、且极简修改被证明不足时，才添加额外的指导。

反模式（Anti-pattern）

写详细的upgradeToSubAgentWhen/stayInPromptWhen列表属于反模式。如果你发现自己写了 3 条以上解释"何时使用某节点"的要点，那多半是 description 本身就写错了。

这一哲学在 Schema 实例中可以直接对照：看 workflow-schema.json 中prompt节点的描述——"A step executed by the main orchestrator (your current session, where you can talk to the user)."，而subAgent的描述是 "An isolated sub-agent invocation (e.g., Claude Code's Task tool)."。两者都只有一句话，靠角色对比让 AI 自行判断，而不是给出一大段规则。

Schema 架构与构建流水线：.json → .toon

SKILL.md 给出了 Schema 的四文件架构：

在仓库中，这些文件的实际位置为：JSON 源在 packages/core/resources/workflow-schema.json，TOON 产物在 packages/core/resources/workflow-schema.toon，技能模板在 packages/vscode/resources/ai-editing-skill-template.md，生成器在 packages/core/scripts/generate-toon-schema.ts。

TOON 生成器的底层逻辑

generate-toon-schema.ts 的流程非常直接：

1. 读取workflow-schema.json（第 15-17 行定义了RESOURCES_DIR、JSON_SCHEMA_PATH、TOON_SCHEMA_PATH）；
2. 用@toon-format/toon的encode()把整个 JSON 对象编码为 TOON 格式（第 28 行）；
3. 写入workflow-schema.toon（第 31 行）；
4. 计算并打印体积对比（第 34-41 行）：JSON size、TOON size与Size reduction %。

TOON 产物在 workflow-schema.toon 中可见：它以缩进的键值对形式展开，例如supportedNodeTypes[13]: start,end,prompt,subAgent,...用方括号标出数组长度，大幅削减了 JSON 的花括号与引号开销。

重新生成 TOON 的命令

编辑.json后，在packages/core目录下执行：

pnpm run generate:toon

在核心包中该命令定义为tsx scripts/generate-toon-schema.ts（见 packages/core/package.json）。完整的构建pnpm run build会自动把generate:toon作为第一步执行（"build": "pnpm run generate:toon && tsc"），随后才编译 TypeScript。

VSCode 扩展侧还通过sync:schema脚本（packages/vscode/package.json）把 JSON 与 TOON 同步到扩展的resources/目录，作为构建的一部分。

偏差藏身之处：五级审查清单

当 AI 持续选错节点类型时，按以下优先级顺序检查（这也是 SKILL.md 给出的审计清单）：

1.ai-editing-skill-template.md第 4 步——最强的牵引力

技能模板是 AI 编辑器启动时加载的，其中的指令会覆盖 Schema 里的所有其他信号。在 ai-editing-skill-template.md 的第 4 步可以看到这样的表述：

Generate workflow JSON: choose each node type based on its role description in the schema. When asubAgentis the right choice, use a built-inbuiltInType(explore/plan/general-purpose).

如果这一行被改成"默认使用内置子代理"之类的偏向性措辞，它就会压过 Schema 中所有中立的描述。保持该模板中性是审计的第一步。

2.nodeTypes.<type>.description——AI 对每个节点的第一印象

这是 AI 理解"每个节点是什么意思"的第一手信息。要求：简短、对比式、聚焦角色。参照上文prompt与subAgent的对比写法。

3.nodeTypes.<type>.aiGenerationGuidance——存在时会被细读

当该字段存在时，AI 会仔细阅读。审计其中是否存在过时的"默认"框架或已不再适用的反模式。例如 subAgent 节点的 aiGenerationGuidance 包含builtInAgents的 explore/plan/general-purpose 能力说明、steps步骤指引和示例，这类内容需要随产品演进定期复核。

4.examples[]——AI 从示例中学习很强

如果每个示例都用同一种节点类型，输出就会被该类型主导。查看 workflow-schema.json 的三个内置示例——"Simple Data Analysis"、"Code Review with Priority"、"Document Processing Pipeline"——可以看到subAgent节点占据了绝大多数步骤。这意味着 AI 在生成时会强烈倾向于把每个步骤都做成子代理。审计示例的节点分布本身就是调优工作。

5. 顶层约束——可能编码了虚假约束

connections.overview.forbidden、exportValidationRules、postGenerationChecklist这些顶层约束（见 workflow-schema.json）可能编码了不存在的约束。例如"禁止循环"——当运行时本身允许循环（因为运行时是一个使用判断力的 AI，而不是确定性执行器）时，这条约束就是虚假的。移除虚假约束本身就是一个有效的改进。

这一点在 Schema 中有现实对照：connections.overview.forbidden只列了三条（Start 无输入、End 无输出、无自连接），required也只要求"每个输出端口至少一条出边、恰一个 Start、至少一个 End"等——并没有禁止一般的循环结构，说明设计者刻意没有把编程式约束搬进 Schema。

修改工作流：七步闭环

SKILL.md 给出了完整的修改流程：

1. 诊断（Diagnose）：识别症状——选错节点类型、AI 推理中引用了虚假约束等。
2. 定位偏差（Locate the bias）：按上面的审计清单逐项排查，在添加新内容之前先找一个把 AI 拉向错误方向的单一来源。
3. 极简修改（Minimal edit）：优先删除有偏文本或修正一条 description，而不是新增章节。
4. 重新生成 TOON：pnpm run generate:toon。
5. 验证（Validate）：pnpm run check && pnpm run build（check即tsc --noEmit，见 packages/core/package.json）。
6. 测试（Test）：npm run debug会启动一个新的 Extension Development Host（在 packages/vscode/package.json 中定义为npm run build && code --extensionDevelopmentPath=. --new-window）。用与节点类型无关的提示词（不要给"为 X 使用子代理"这类暗示）触发 AI 编辑器，检查生成的工作流。
7. 迭代（Iterate）：如果极简修改不足，添加最小的额外信号——而不是一个指导章节。

重要约束：多 Agent 中立与"AI 运行时"认知

框架是多 Agent 的，Schema 文本必须 Agent 无关

CC Workflow Studio 的框架面向多 Agent（Claude Code、Codex、"other"）。Schema 文本必须与 Agent 无关：避免 Claude 特有的措辞，例如"isolated Claude session"应改写为 "isolated AI agent session" 或 "isolated sub-agent"。在 workflow-schema.json 中可以看到subAgent的描述恰好写成 "An isolated sub-agent invocation (e.g., Claude Code's Task tool)."，括号里只是举例而非约束；而agentType字段的枚举是["claudeCode", "other"]，天然支持多运行时。

运行时是 AI Agent，不是确定性程序

在代码世界里合理的约束（禁止循环、禁止无限循环）在这里往往不适用。在把编程式约束誊写进 Schema 之前，先验证它是否真的成立。

生成后必须确认改动生效

执行generate:toon之后，用 grep 在workflow-schema.toon中确认相关字符串确实出现——因为 MCP 交付给 AI 的是 TOON 而不是 JSON。如果你只改了.json而忘了重新生成，AI 拿到的还是旧内容，一切调优都等于没做。

提交规范：Schema 变更的 Conventional Commit 约定

按项目的 conventional commit 规范（对应 docs/release-flow.md 描述的发布策略）：

• 描述修正 / 偏差移除→improvement:（patch 级别 bump）
• 仅构建 / 工具链改动→chore:（不触发发布）
• 主题（subject）≤50 字符；正文 3-5 条要点，只写"改了什么"
• 把不相关的关注点拆成独立提交，保持 diff 可审查

附：Schema 关键参数速查（来自 workflow-schema.json）

以下是调优时最常涉及的顶层参数，全部来自 packages/core/resources/workflow-schema.json 的实际内容：

• schemaVersion：1.0.0；metadata.maxNodes：100。
• metadata.supportedNodeTypes（13 种）：start、end、prompt、subAgent、askUserQuestion、ifElse、switch、skill、mcp、subAgentFlow、codex、branchSession、group。
• 节点命名规则（validationRules.node）：nameMaxLength: 50，正则^[a-zA-Z0-9_-]+$，只允许 ASCII 字母数字、连字符与下划线，禁止空格和非 ASCII 字符。
• 工作流命名规则（workflowStructure.fields.name）：maxLength: 100，正则^[a-z0-9_-]+$，只允许小写字母。
• 端口命名（connections.portNamingRules）：线性节点（start/end/prompt/subAgent/skill/mcp/subAgentFlow/codex/branchSession）统一input→output；ifElse用branch-0（true/if）、branch-1（false/else）；switch用branch-0 … branch-N；askUserQuestion单选用branch-0 … branch-N，启用useAiSuggestions或multiSelect时收敛为单一output端口。
• 导出校验规则（connections.completenessRules.exportValidationRules，8 条强制项）：恰一个 Start、至少一个 End、Start 输出必须连通、至少一个 End 有入边、所有节点从 Start 可达、所有路径通向 End、连接引用的节点必须存在、条件节点所有分支必须有出边。
• postGenerationChecklist：9 条"✓"自查项，是 AI 返回结果前的快速核对清单。

结语

CC Workflow Studio 的 Schema 调优本质上是一场针对 AI 的提示工程：Schema 不是校验器，而是 AI 的行为说明书。掌握"校准方向而非规定规则"的设计哲学、四文件架构与.json → .toon构建流水线、五级偏差审计清单和七步修改闭环，你就能系统性地修正 AI 生成工作流时的节点类型偏好，让生成结果更符合真实意图。相关文件可在 .claude/skills/workflow-schema-tuning/SKILL.md、packages/core/resources/workflow-schema.json 与 packages/core/scripts/generate-toon-schema.ts 中继续深入研读。

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