组件总览

组件是构成流程的基本单元。 类似应用中的类，每个组件都面向某一种特定用途、处理方式或第三方集成能力而设计。

提示

SkillFlaw 为工作区提供了键盘快捷键。 在页头点击个人头像，进入 Settings，再点击 Shortcuts，即可查看可用快捷键。

向流程中添加组件

要向流程中添加组件，请从 流程组件 或 业务组件 菜单中，将组件拖入工作区。

组件通常按类型或提供商分组，部分组件默认隐藏：

• 流程组件：SkillFlaw 的基础流程组件，按用途分组，例如 输入 / 输出、数据 等。 这些组件要么提供通用能力（如循环、解析），要么提供支持多种第三方集成的单组件能力。
• 业务组件：按服务提供商分组，包含一个或多个面向业务场景的第三方集成组件。
• 遗留组件：默认隐藏。更多说明见遗留组件。

配置组件

把组件拖入流程后，需要配置其参数，并与其他组件建立连接。

每个组件都包含：

• 输入
• 输出
• 参数
• 与该组件用途相关的控制项

默认情况下，只显示必填项和常用项。 如需查看更多设置（包括元设置），请使用组件头部菜单。

组件头部菜单

在工作区中点击组件，即可打开该组件的头部菜单。

当前头部菜单会把高频操作直接放在组件上方，常见入口包括：

• 代码：打开组件开发窗口，查看或修改当前组件的 Python 实现
• 冻结：冻结当前组件及其上游结果，后续运行时直接复用已有输出
• 工具模式：当组件需要作为 Agent 的工具使用时启用

点击最右侧的更多菜单后，还可以看到当前节点相关的扩展操作，例如：

• 技能文档：查看该组件对应的 Skill 文档
• 创建版本：基于当前节点内容创建新的组件版本
• 历史版本：查看历史版本，并把某个历史版本应用到当前选中节点
• 最小化：压缩组件展示区域，便于整理复杂流程
• 下载：下载当前组件定义
• 删除：从当前流程中移除该组件

这些入口围绕“开发 → 文档 → 版本”的完整链路组织，便于在同一个工作区里连续完成组件开发、留痕和版本管理。

技能文档

组件的 技能文档 用来承载组件对应的 Skill 说明与元数据。当前入口会直接打开该组件的 SKILL.md 只读预览，方便你在不离开当前工作流上下文的情况下核对自动生成结果。

技能文档预览对话框主要聚焦生成结果本身，通常会展示：

• 渲染后的 SKILL.md 内容
• 对应的原始 Markdown 视图
• frontmatter 摘要字段，例如组件显示名、类名、UUID、版本与描述
• 复制 / 预览等便于审阅生成结果的辅助动作

当你在流程编辑器里执行 创建版本 时，系统会在保存当前节点版本的同时，同步生成该组件的 Skill 文档。因此，组件版本与技能文档是成对留痕的，而不是彼此独立的两套记录。

重命名组件

如需修改组件名称或描述，请在工作区中点击组件，然后点击 Edit。 组件描述支持 Markdown。

运行单个组件

点击 Run component 可执行单个组件。 当界面显示 Last Run 时，表示该组件已成功运行。

单独运行组件与运行整个流程不同： 单组件运行只会构建并执行当前组件本身，以及编辑器里直接提供给它的输入；它不会自动执行所有上游依赖。

查看组件输出与日志

点击 Inspect 可以查看单个组件的输出与日志。

冻结组件

信息

冻结某个组件时，也会一并冻结该组件的所有上游组件。

如果你预期某个组件以及其全部上游组件的输出稳定不变，并且只需要计算一次，可以使用冻结功能。

冻结后：

• 当前组件及其上游组件不会再次执行
• 系统会保留这些组件的上一次输出结果
• 之后的流程运行将直接复用该输出

操作方式：点击组件打开头部菜单，点击 Show More，再选择 Freeze。

组件端口

每个组件边框周围都有圆形端口图标，例如 。 这些图标表示组件的连接点，也就是端口。

端口会：

• 接受某种输入数据
• 输出某种特定类型的数据

你通常可以通过端口所在字段，或通过端口颜色来判断数据类型。

例如，System Message 字段接受的是 Message 数据，它对应蓝色端口：。

构建流程时，应把输出端口连接到同类型输入端口上，以便在组件之间传递正确的数据。 关于各种数据类型的程序化表示，请参阅SkillFlaw 数据类型。

提示

• 在工作区悬停到端口上，可以查看该端口的连接说明。
• 点击端口后，可以通过 Search 查找兼容组件。
• 如果两个组件的数据类型不兼容，可以使用Type Convert 组件进行转换。

Input 与 Output 的定义

在 SkillFlaw 中，组件的输入与输出分别承担“声明接收什么”和“声明产出什么”的职责。

• Input：组件接收数据或配置的入口。它既可以表现为一个参数字段，也可以表现为一个可连接的输入端口。
• Output：组件对外暴露结果的出口。它决定下游组件可以接收什么结果，以及引用选择器能够引用哪些结果。

从定义结构上看，Input 通常包含以下信息：

• name：稳定字段名，用于保存配置与绑定引用
• display_name：界面展示名
• type / field_type：输入控件类型或输入值类型
• required：是否必填
• input_types：当该输入允许端口连接时，可接收的数据类型列表
• is_list：是否支持数组 / 多值

Output 通常包含以下信息：

• name：稳定输出名，是输出端口与字段引用的基础标识
• display_name：界面展示名
• method：生成该输出的方法名
• types 与 selected：该输出支持的数据类型，以及当前选择的输出类型
• group_outputs：是否同时暴露多个输出端口
• output_fields：该输出可稳定引用的字段定义

因此，Input 解决的是“组件如何接收参数与上游数据”，Output 解决的是“组件如何向下游组件和引用器暴露结果”。

Input 类型与 Output 类型

SkillFlaw 的“类型”分为两层：

1. 端口数据类型：决定端口能否互连，也决定连线颜色与运行时值形态。
2. 输入字段类型：决定组件参数在界面里以什么方式编辑、校验和保存。

端口数据类型

输入端口和输出端口使用同一组数据类型体系。当前文档中稳定可见的主要端口数据类型包括：

• Data
• DataFrame
• Embeddings
• LanguageModel
• Memory
• Message
• Tool
• 未知或多类型

这些类型的含义、结构与典型使用方式，请参阅SkillFlaw 数据类型。

输入字段类型

组件参数本身并不一定都是“端口”。SkillFlaw 还定义了一组输入字段类型，用于描述参数的录入方式、校验规则与可选绑定能力。并不是每一种输入字段类型都会在界面中显示为端口；很多类型只负责参数编辑与保存。

为便于阅读，可以把这些类型理解为两大类：一类用于接收上游结果或显式声明可连接输入，另一类主要用于参数编辑与配置保存。

可连接上游结果的输入类型

类型标识	主要用途
HandleInput	通用句柄型输入基类，用于声明可接收指定数据类型的连接输入
DataInput	接收 Data 类型上游结果
DataFrameInput	接收 DataFrame 类型上游结果
ModelInput	选择模型，或连接上游 LanguageModel / Embeddings 输出
MessageInput	接收完整 Message 对象或可转换为 Message 的值
MessageTextInput	接收消息文本值，常用于文本类输入
PromptInput	普通提示词输入；在支持引用或绑定的场景中也可承接上游值
MustachePromptInput	支持插入引用的提示词输入
TableInput	录入表格型结构数据，适合定义多行 schema、字段清单或批量配置
ToolsInput	录入工具集合，供 Agent 或工具编排场景使用

纯参数编辑型输入类型

类型标识	主要用途
StrInput	单行文本输入
MultilineInput	多行文本输入
MultilineSecretInput	多行密文输入
SecretStrInput	单行密文 / 密钥输入
CodeInput	录入代码片段或脚本内容
IntInput	整数输入
FloatInput	浮点数输入
BoolInput	布尔开关输入
SliderInput	滑块数值输入
DictInput	录入字典 / JSON 对象
NestedDictInput	录入嵌套对象结构
DropdownInput	固定选项下拉选择
MultiselectInput	多选输入
SortableListInput	可排序列表输入
TabInput	Tab 选择型输入
ConnectionInput	录入连接信息，例如连接串或连接配置
AuthInput	录入认证信息
QueryInput	查询 / 搜索表达式输入
FileInput	文件资源输入
McpInput	MCP 资源或配置输入
OpenAPIPluginInput	OpenAPI 插件资源选择输入
SkillInput	Skill 资源选择输入
LinkInput	链接输入
DefaultPromptField	默认提示词场景使用的内部默认字段定义

这些字段类型决定了参数面板中的交互形式。例如：

• DropdownInput 用于固定选项选择
• FileInput 用于文件类资源输入
• TableInput 用于结构化表格配置
• MustachePromptInput 用于支持引用插入的提示词编辑
• DataInput、MessageInput、ModelInput 等既可以接收值，也可以通过端口接收兼容的上游结果

Output 契约与 output_fields

与 Input 一样，Output 也是组件契约的一部分。它不仅决定“组件会产出什么”，还决定“这些结果如何暴露给下游组件、引用器、工具模式与循环控制使用”。

从结构上看，当前输出定义中的关键字段包括：

字段	作用
name	稳定输出名，是输出端口、输出切换与引用路径的基础标识
display_name	界面展示名
method	生成该输出的方法名
types	该输出支持的数据类型列表
selected	当前被选中的输出类型
group_outputs	是否把多个输出同时暴露为多个端口
required_inputs	生成该输出前必须具备的输入
allows_loop	该输出是否允许进入循环语义
loop_types	当启用循环语义时额外允许的类型
tool_mode	该输出是否可用于工具模式
output_fields	输出中可稳定引用的字段定义
options	输出附加选项，例如过滤规则

从使用方式上看，输出通常可以分为以下几类：

输出暴露方式	典型特征	适用场景
单输出单类型	一个输出端口，对应一个稳定结果类型	最常见的标准组件输出
单输出可切换类型	同一个输出名下存在 types 与 selected	用户需要在多种结果形态之间切换
多输出并列暴露	group_outputs = true，界面中同时出现多个输出端口	一个组件需要同时对外暴露多个独立结果
整对象输出	只暴露整个结果对象，不展开稳定字段	结果结构复杂但不适合公开内部字段
字段级输出契约	通过 output_fields 声明稳定字段	下游需要按字段精确引用或消费

这意味着 Output 不只是“返回值说明”，更是前端端口展示、下游连接、变量引用和部分运行时行为的统一契约。

输出类型选择与 group_outputs

当一个组件支持多种输出结果时，系统主要通过两种方式暴露：

• 类型切换：同一个输出位支持多个类型，通过 types 与 selected 决定当前使用哪一种
• 并列输出：多个输出同时显示在节点上，通常对应 group_outputs = true

前者强调“同一出口，不同结果形态”，后者强调“同一组件，同时提供多个独立结果”。

output_fields 与字段级输出

Output 不仅定义“会产出什么类型”，还可以进一步定义“这个输出里有哪些可稳定引用的字段”。这部分结构由 output_fields 描述。

每个 output_fields 条目通常包含：

• name：字段名
• type：字段类型
• description：字段说明
• required：是否必需
• example：示例值

当组件输出适合被下游按字段消费时，SkillFlaw 会把这些字段定义同步到前端节点元数据中。这样一来，引用选择器不仅能引用整个输出，还能继续展开到字段级别。

例如，引用器可以插入：

• 整个输出：{{node.<node_id>.output.<output_name>}}
• 输出字段：{{node.<node_id>.output.<output_name>.<field_name>}}

何时需要 output_fields

output_fields 适用于输出结构稳定、字段语义明确、且希望被下游精确引用的场景，例如：

• 文本型消息输出中暴露 text 等稳定字段
• 结构化抽取结果中暴露业务字段
• Data / DataFrame 输出中暴露经过明确定义的结构字段

如果组件结果本身是一个复杂对象，但内部字段并不稳定或不适合作为公开契约，系统可以只暴露“整个对象”，而不展开其内部字段。

output schema 与结构化输出组件

Structured Output 组件是 output schema 的典型场景。该组件用一个表格来描述结构化输出，每一行对应一个字段，核心列包括：

• name
• description
• type
• multiple

其中：

• type 用于声明字段的基础类型，例如 string、number、boolean、object、array
• multiple = true 表示该字段是数组值

当你修改这个 schema 后，组件会同步更新对应输出的 output_fields。因此，下游组件、引用选择器以及输出检查面板看到的字段定义，会与当前 schema 保持一致。

Input 的值引用

支持引用的输入字段可以直接插入上游节点值、系统变量、工作流参数以及共享变量。引用统一使用 Mustache 形式，即：

{{reference.path}}

当前系统中常见的引用来源如下。

组件 input 引用

用于引用某个节点的输入字段值：

• 语法：{{node.<node_id>.input.<field_name>}}
• 示例：{{node.prompt-1.input.template}}

这类引用适用于复用已有节点的参数值，避免在多个节点中重复维护同一份配置。

组件 output 引用

用于引用某个节点的输出，或输出中的字段：

• 整体输出：{{node.<node_id>.output.<output_name>}}
• 输出字段：{{node.<node_id>.output.<output_name>.<field_name>}}
• 示例：{{node.chat-input-1.output.text}}

其中，字段级引用是否可用，取决于该输出是否声明了 output_fields。

工作流参数（流程变量）引用

工作流参数归属当前工作流，可在引用器中按 workflow.<name> 使用：

• 语法：{{workflow.<name>}}
• 示例：{{workflow.api_key}}

这类值通常用于当前工作流自己的入参约定、模板化占位或可复用配置。

系统变量引用

系统变量由运行时上下文提供，可直接用于提示词与参数绑定。当前系统稳定暴露的字段包括：

• flow_id
• flow_name
• description
• run_id
• session_id
• user_id
• user_name
• tenant_id
• business_id
• project_id
• flow_version
• trigger_source
• now

引用语法为：

• {{sys.flow_id}}
• {{sys.session_id}}
• {{sys.now}}

全局变量（共享变量）引用

共享变量来自系统变量管理能力，按作用域区分为系统、租户、业务域和个人四类。引用时使用统一前缀 global，并在第二段用作用域缩写表示归属：

• 系：系统级共享变量
• 租：租户级共享变量
• 业：业务域共享变量
• 个：个人共享变量

引用语法为：

• {{global.系.<variable_name>}}
• {{global.租.<variable_name>}}
• {{global.业.<variable_name>}}
• {{global.个.<variable_name>}}

例如：

• {{global.租.API_KEY}}
• {{global.业.ENDPOINT_URL}}

在提示词编辑器和参数绑定对话框中，引用选择器会按“系统变量”“工作流参数”“共享变量”“节点输入”“节点输出”分组展示这些来源。

动态端口

某些组件的端口会动态增加或移除。 例如 Prompt Template 组件会识别模板中用大括号包裹的变量，并为这些变量自动打开新的输入端口。

输出类型选择

所有组件都会生成输出，这些输出要么流向流程中的下一个组件，要么作为流程最终结果返回。

某些组件支持多种输出类型：

• 如果组件会同时输出多种类型，编辑器中会显示多个输出端口；在组件代码中，这通常对应 group_outputs=True
• 如果组件一次只输出一种类型，则需要点击输出标签手动切换输出类型；在组件代码中，这通常对应 group_outputs=False 或未显式设置

例如，一个语言模型组件通常可以输出两种结果：

• Model Response：输出 Message
• Language Model：输出 LanguageModel，供其他组件（如 Structured Output）作为驱动模型使用

端口颜色

组件端口颜色代表该端口输入或输出的数据类型。

数据类型	端口颜色	示例
Data	红色
DataFrame	粉色
Embeddings	绿色
LanguageModel	洋红色
Memory	橙色
Message	靛蓝色
Tool	青色
未知或多类型	灰色

组件代码

你既可以在工作区中使用组件，也可以直接查看和编辑其底层代码。 编辑流程时，选中组件并点击 Code，即可查看其 Python 实现。

当前代码开发窗口的标题形如 Develop Component: Agent，主界面分为左右两栏：

• 左侧是代码编辑器，用于直接修改 Python 代码
• 右侧是 AI Component Builder，用于通过自然语言驱动组件生成、修改、解释与问答

AI 编程不是单独的“生成器页面”，而是嵌在组件开发窗口中的协同面板。它会结合：

• 你的当前需求描述
• 编辑器里的现有代码
• 本地历史对话与最近一次操作上下文

自动识别本次请求更适合归类为哪一种意图：

• 生成：根据需求创建新组件
• 修改：在保留现有语义的前提下调整当前代码
• 解释：解释组件结构、行为与风险点
• 问答：围绕当前组件做针对性提问

这意味着多数情况下你不需要手动切换模式：如果编辑器里已经有代码，而你的输入是“修复”“增加”“优化”之类的请求，系统会自动按 修改 处理；如果编辑器为空，而你描述的是一个新的组件需求，系统会自动按 生成 处理；明确的解释类请求和问题类请求，则分别落到 解释 与 问答。

在 AI 编程过程中，右侧面板会持续展示状态与结果，例如：

• 当前状态（规划、流式生成、校验、测试、可应用等）
• 生成说明与风险提示
• 代码差异预览（Patch preview）
• 依赖缺失提示
• 校验结果与 smoke checks

当前 AI 面板更适合“边看边改”的迭代式开发，而不是一次性生成后就结束。你可以在同一个面板中：

• 输入需求后按 Enter 直接执行
• 使用 Shift + Enter 换行
• 查看当前识别意图下的本地历史输入
• 输入 /clear 清空该意图下的本地历史

当 AI 返回的是候选代码时，界面会同时给出状态徽标、自动识别意图、最新输出内容，以及和当前编辑器代码对比后的 Patch 预览。如果暂时不能应用或保存，面板还会明确说明阻塞原因，例如缺失依赖、组件校验失败、smoke check 未通过，或者 Patch 与当前编辑器内容发生冲突。

当生成结果可用时，你可以先查看差异，再把 AI 建议应用回左侧编辑器，然后使用 保存 写回组件定义。

开发窗口本身还提供一组便于长时间编辑的能力：

• Exit / Save 顶部操作
• 左右面板折叠与展开
• 拖拽分栏宽度
• 全屏切换

因此，当前组件开发的推荐路径通常是：先通过 代码 进入开发窗口，再借助 AI Component Builder 完成初稿生成、局部修改、解释排障与最终保存。

组件底层代码会决定：

• 编辑器中显示哪些配置项
• 输入如何校验
• 数据如何处理
• 输出如何传递给下一个组件

所有组件都继承自基础 Component 类。 每个组件的代码通常会定义输入、输出以及对应的方法，这些内容会在工作区中表现为组件端口。

组件版本

组件的版本和状态保存在 SkillFlaw 内部数据库中。 当你把组件加入某个流程时，实际上创建的是一个基于数据库信息的“脱离副本”。

这意味着：

• 组件实例会保留添加进流程那一刻的版本与状态
• 它不会随着 SkillFlaw 升级而自动同步
• 如需升级，需要你显式执行更新

除了数据库中的“组件版本”之外，当前流程编辑器还提供了节点级版本操作：

• 创建版本：基于当前节点内容创建一个新的组件版本
• 历史版本：选择一个历史版本，并仅替换当前选中的节点

其中，创建版本 不只是保存一条版本记录，还会同步生成该节点对应的组件 Skill 文档；而 历史版本 则适合把当前节点快速回退到某个稳定版本，同时不影响流程里的其他节点。

更新组件版本

当编辑器检测到工作区中的组件版本落后于数据库版本时，会提示你更新：

• Update ready：更新不包含破坏性变更
• Update available：更新可能包含破坏性变更

可能的破坏性变更包括：

• 输入变化
• 输出变化
• 连接断开
• 需要重新配置组件参数

更新方式有两种：

• 点击 Update：更新单个组件，适合无破坏性变更
• 点击 Review：先查看全部更新项，并可在更新前创建快照，适合可能有破坏性变更的情况

如果勾选 Create backup flow before updating，系统会先在同一项目文件夹中生成一个带 (backup) 后缀的备份流程。

组合组件

多个组件可以组合成一个可复用组件，这对于整理大型流程很有帮助。

例如，你可以把某个 RAG Agent 与其工具、向量存储组件组合成一个组组件。

操作方式：

1. 按住 Shift，拖动框选你要组合的全部组件
2. 或在 Windows 上按住 Ctrl、在 Mac 上按住 Cmd，逐个点击组件
3. 选中后点击 Group

组合后的组件会作为单一组件进行配置与管理，包括名称、代码与设置。

要取消组合，请点击组件，打开头部菜单，点击 Show More，然后选择 Ungroup。

如果你想在其他流程中复用该组合，可以点击 Save，把它保存到 流程组件 菜单中，作为自定义组件使用。

遗留组件

遗留组件已不再作为当前受支持能力的一部分，未来版本中可能会被移除。 你仍然可以在已有流程中继续使用它们，但建议尽快替换为当前受支持的组件。 若存在明确替代项，通常会在流程中组件卡片上的 遗留 标记、发布说明或 SkillFlaw 文档中给出说明。

如果你暂时不确定该如何替换某个遗留组件，可以先通过 Search 按提供商、服务或组件名称查找。 某些组件可能已经被全新的组件、相似组件，或其他分类下的同类新版本替代。

如果没有直接可见的替代项，也可以判断是否能用其他组件适配你的场景。 例如，许多 流程组件 提供的是可复用于多种提供商和业务场景的通用能力，例如 API Request 组件。

如果上述方式都不适用，你也可以参考遗留组件的实现代码自行封装自定义组件，或前往发起讨论反馈该遗留组件的替代需求。

为了避免在新流程中继续使用这些组件，系统默认会隐藏遗留组件。 在可视化编辑器中，你可以点击 组件设置，切换 遗留 过滤项的显示状态。