Refly 开源实战指南：用 Vibe Workflow 构建可版本化、可分发的 Agent Skills-酒店常州论坛

Refly 开源实战指南：用 Vibe Workflow 构建可版本化、可分发的 Agent Skills

【免费下载链接】reflyThe first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex & more. Build Clawdbot 🦞· APIs for Lovable · Bots for Slack & Lark/Feishu · Skills are infrastructure, not prompts.项目地址: https://gitcode.com/GitHub_Trending/re/refly

本文基于 Refly 开源仓库的官方 README 展开，系统讲解 Refly 作为「Agent Skills Builder」的定位与核心能力：如何自部署并创建第一个工作流，如何通过 REST API、Webhook 和 CLI 把确定性工作流交付到 Lovable、Lark/Feishu、Claude Code 等下游环境，并结合仓库中的 OpenAPI 控制器、API 文档与 CLI 源码，还原从「意图描述」到「可执行技能资产」的完整技术链路。读完本文，你可以独立完成 Refly 的部署、工作流搭建与三种主流集成方式（API / Webhook / Skill 发布）的配置。

一、Refly 是什么：Skills 不是 Prompt，而是基础设施

Refly 的核心理念在 README 中被明确概括为一句："Skills are not prompts. They are durable infrastructure."（技能不是提示词，而是持久化的基础设施）。项目把自己定义为「第一个开源的 Agent Skills Builder 平台」，目标是把企业中混乱的业务逻辑（SOP）编译成稳定、原子化、带版本管理的 Agent 技能，让任意 Agent 运行时都能以确定性方式调用。

README 指出当前 AI Agent 落地生产环境的痛点：多数 Agent 依赖「Vibe-coded」脚本和黑盒逻辑，随着 Claude Code、AutoGen、MCP 等 Agentic 生态演进，瓶颈已经不再是 LLM 本身，而是缺少标准化、可复用的动作层。Refly 的定位正是填补「裸 API」与「智能体」之间的鸿沟——在可视化 IDE 中把业务流程构建成结构化技能，再导出为 MCP Server、标准 API 或可移植工具，供任意 Agent 框架调用。

四大核心能力

README 将 Refly 的能力归纳为四个层次，每一层都对应仓库中的真实实现：

Construct with Vibe（Copilot 驱动的构建）：用自然语言描述业务逻辑，Refly 的 Model-Native DSL 将意图编译为高性能技能。从源码结构看，这一能力由 copilot 模块与 copilot-autogen 模块支撑，CLI 侧也提供了refly workflow generate等命令（见 packages/cli/src/commands/workflow）。
Execute with Control（可干预运行时）：打破 AI 执行的「黑盒」，支持运行中暂停、审计、重新引导。对应到源码，workflow.service.ts 基于 BullMQ（QUEUE_RUN_WORKFLOW/QUEUE_POLL_WORKFLOW队列）与 Redis 实现了有状态的执行轮询与恢复机制，并引入了WorkflowCompletedEvent、WorkflowFailedEvent等事件驱动回调。
Ship to Production（统一 Agent 栈）：统一 MCP 集成、工具、模型与可复用技能为单一执行层，可导出为 API、Webhook 或 Claude Code/Cursor 原生工具，并支持定时调度（对应 schedule 模块）。
Govern as Assets（技能注册中心）：把脆弱脚本变成可治理、可共享的基础设施资产，具备版本管理、共享与团队协作能力（对应 skill 模块与 skill-package 模块）。

README 还用两张对比表（Builder 视角与 Enterprise 视角）将 Refly 与传统工作流工具（n8n、Dify）、代码优先 SDK（LangChain）区分开：交互深度上支持运行中干预，构建上支持Copilot 意图驱动生成，恢复上支持执行中热修复，可移植性上支持导出到 Claude Code、Cursor、Manus 等任意环境。

二、快速开始：自部署与第一个工作流

2.1 自部署

README 的 Quick Start 指向官方自部署文档（使用 Docker 部署到自有服务器，推荐开发者使用），完整 API 参考见 docs/en/guide/api。仓库中提供了完整的 Docker 部署配置，包括基础编排 docker-compose.yml、中间件编排 docker-compose.middleware.yml、自部署开发环境 docker-compose.self-deploy-dev.yml 以及环境变量示例 env.example。

自部署完成后，默认可以通过http://localhost:5700访问 Refly。

2.2 创建第一个工作流

README 给出了三步操作流程，此处完整保留并结合仓库说明：

Step 1：注册与登录

浏览器打开http://localhost:5700；
使用邮箱和密码注册；
配置第一个模型 Provider：
- 点击右上角账户图标 → Settings；
- 添加 Provider（如 OpenAI、Anthropic）；
- 添加第一个聊天模型；
- 将其设为默认模型。

Provider 的支持范围由仓库根目录的 provider-catalog.json 定义，其中为每个 Provider 声明了providerKey、baseUrl、categories（如llm、embedding）与描述等元信息；MCP 服务器目录则由 mcp-catalog.json 维护（例如 GitHub MCP Server 的接入 URL 与apiKey鉴权方式）。

Step 2：创建工作流

在首页点击"New Workflow"；
选择模板或从零开始：
- Blank Canvas：使用可视化节点构建；
- Vibe Mode：用自然语言描述工作流。

README 给出的「产品调研工作流」示例：

1. Add "Web Search" node - searches for product information 2. Add "LLM" node - analyzes search results 3. Add "Output" node - formats the report 4. Connect the nodes 5. Click "Save"

Step 3：测试工作流

点击 "Run" 按钮；
输入测试参数（如一个产品 URL）；
实时查看执行结果；
若失败，检查日志。

从源码结构看，工作流的画布数据（节点、连线、变量）由 canvas 模块与 canvas-common 包共同管理——后者提供了prepareNodeExecutions、sortNodeExecutionsByExecutionOrder等节点执行序准备逻辑，这正是「确定性执行」在代码层面的体现。

三、使用场景一：REST API 集成

目标：从你的应用通过 REST API 调用工作流。

3.1 获取 API 凭据

进入 Settings → API Keys；
点击 "Generate New Key"；
复制并妥善保管你的 API Key。

在官方托管版中，也可以在任意工作流页面点击右上角 "Integration" → "API Key" 标签创建密钥（详见 openapi.md）。

3.2 发起第一次 API 调用

README 给出的示例调用：

curl -X POST https://your-refly-instance.com/api/v1/workflows/{WORKFLOW_ID}/execute \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "product_url": "https://example.com/product" } }'

预期响应：

{ "execution_id": "exec_abc123", "status": "running" }

查询执行状态：

curl https://your-refly-instance.com/api/v1/executions/{execution_id} \ -H "Authorization: Bearer YOUR_API_KEY"

3.3 仓库中的实际端点定义

README 中的示例是简化写法；以仓库自动生成的 API 文档 docs/en/guide/api/openapi.md 为准，实际端点如下：

POST /openapi/workflow/{canvasId}/run：通过 API Key 认证执行工作流，返回executionId与status（枚举值init | executing | finish | failed）。请求体要求把变量放在variables字段下，每个 key 是工作流变量名，值可以是字符串、数字、布尔、对象或数组；文件变量则传/openapi/files/upload返回的fileKey。为向后兼容，也允许把变量作为顶层字段传递，但官方推荐使用variables。
POST /openapi/workflow/{executionId}/abort：中止正在运行的执行。
GET /openapi/workflow/{executionId}/output：获取执行输出（输出节点内容 + Drive 文件）。节点执行中/失败时消息可能只含部分内容，文件仅在节点完成后返回。

这些端点的后端实现在 openapi-workflows.controller.ts 中：控制器挂载在v1/openapi/workflows路由下，统一使用ApiKeyAuthGuard（API Key 鉴权）+RateLimitGuard（限流）两层 Guard，并通过ApiCallTrackingInterceptor记录调用。也就是说，API Key 鉴权、限流与调用追踪是框架级内建能力，而非调用方自行实现。

常见错误码（与 Webhook 共用，见 webhook.md）包括：CANVAS_NOT_FOUND(404)、INSUFFICIENT_CREDITS(402)、INVALID_REQUEST_BODY(400)、WEBHOOK_DISABLED(403)、WEBHOOK_NOT_FOUND(404)、WEBHOOK_RATE_LIMITED(429) 等，集成时应据此做错误分支处理。

四、使用场景二：Lark/Feishu Webhook 触发

目标：当有人在 Lark 发送消息时触发你的工作流。

前置条件

拥有管理员权限的 Lark 工作区；
Refly 中已创建工作流。

配置步骤

在 Refly 中：
- 打开工作流；
- 点击 "Settings" → "Triggers"；
- 启用 "Webhook Trigger"；
- 复制 Webhook URL。
在 Lark/Feishu 中：
- 进入飞书开放平台创建 "自定义应用"（Custom App）；
- 进入 "事件订阅"（Event Subscriptions）；
- 将 Refly Webhook URL 粘贴到 "请求网址"（Request URL）；
- 点击 "添加事件"，选择 "接收消息"（Receive Message）；
- 进入 "版本管理与发布" 并发布应用。
测试：
- 在飞书中搜索你的机器人并发送消息（如analyze report.pdf）；
- 工作流被执行，结果经 Webhook 通道返回。

Webhook 侧的 API 契约见 webhook.md：请求体同样是variables键值对；若需要传文件变量，需先通过/openapi/files/upload（需 API Key）上传获得fileKey，再在 Webhook 请求体中传fileKey或fileKey[]。README 提示该场景的完整图文教程以官方文档为准。

五、使用场景三：把技能发布到 Claude Code

目标：将 Refly 工作流发布为 Claude Code 技能（Skill）。

README 给出的快速开始命令：

# 1. 安装 Refly CLI npm install -g @powerformer/refly-cli # 2. 安装一个技能 # 通过 Refly CLI refly skill install <skill-id> # 或通过 npx npx skills add refly-ai/<skill-name> # 3. 发布一个技能 refly skill publish <skill-id>

发布后，该技能即可在 Claude Code、Cursor 及 MCP 驱动的工作流中被 Agent 作为工具调用。

5.1 CLI 源码层面的参数细节

Refly CLI 的包名确为@powerformer/refly-cli（见 packages/cli/package.json），当前仓库版本为 0.1.26。查看 skill/install.ts 的源码，refly skill install实际支持的参数比 README 示例更完整：

<skillId>：要安装的技能包 ID（必填位置参数）；
--version <version>：安装指定版本；
--share-id <shareId>：私有技能的共享 ID；
--config <json>：以 JSON 字符串传入安装配置，如'{"key": "value"}'（非法 JSON 会返回带修复建议的错误提示）；
--force：已安装时强制重装。

安装成功后，服务端会返回安装记录，包含installationId、installedVersion，以及技能包的元信息——name、version、description、triggers、tags、workflowId、inputSchema、outputSchema。其中inputSchema/outputSchema的存在说明技能包是以带输入/输出 Schema 的契约形式发布的，这正是「技能作为基础设施而非提示词」的具体落地：Agent 依赖的是结构化的能力契约，而不是自然语言描述。

此外，packages/cli/src/commands/skill 目录还包含create、list、search、run、uninstall、unpublish、validate等子命令，覆盖了技能从创建、校验、安装到发布/下架的完整生命周期；workflow 命令集则提供了run、abort、session、run-node-start、run-node-abort等细粒度命令——这与 README 宣称的「可干预运行时」相呼应：即便在 CLI 层，也可以对单次执行的单个节点进行启动与中止操作。

六、生态定位：输入侧与输出侧

README 把 Refly 定位为「企业现有工具链与下一代 Agentic 运行时之间的通用桥梁」：

输入侧（Tooling & Protocols）

3,000+ 原生工具集成（Stripe、Slack、Salesforce、GitHub 等），完整支持范围可查 provider-catalog.json；
完整兼容 MCP（Model Context Protocol）服务器，目录见 mcp-catalog.json；
私有连接器：接入自有数据库、脚本与内部系统。

输出侧（Agent Runtimes & Platforms）

AI 编码工具：Claude Code 原生导出，Cursor 即将支持；
应用构建平台：通过有状态 API 为 Lovable 或自研前端供能；
自动化平台：部署为 Slack、Lark/Feishu 或 Microsoft Teams 的 Webhook；
Agent 框架：兼容 AutoGen、Manus、LangChain 及自研 Python 技术栈。

仓库结构也印证了这种「协议中立」的设计：mcp-server 模块让 Refly 自身可作为 MCP Server 暴露能力，internal-mcp 模块则负责消费外部 MCP 服务器，skill 模块与 skill-package 模块承担技能的调用与打包分发，webhook 模块提供外部触发入口。

七、工程结构速览

对希望深入源码的读者，以下路径是最佳入口：

apps/api：NestJS 后端主应用，业务模块按src/modules/划分（workflow、canvas、skill、schedule、webhook、openapi、credit 等）；
apps/web：前端应用（rsbuild + Tailwind）；
packages/canvas-common：画布数据的纯逻辑层（节点排序、diff、历史、同步），配有data.test.ts、workflow.test.ts等测试；
packages/cli：命令行工具，skill与workflow两个命令族覆盖技能与工作流的终端操作；
packages/openapi-schema：从schema.yml生成的 API 类型定义，是前后端契约的单一来源；
packages/agent-tools 与 packages/providers：Agent 工具集成（GitHub、Gmail、Google Docs 等）与模型 Provider 抽象；
deploy/docker 与 deploy/helm：Docker 与 Helm 两套部署方案；
specs：功能变更规格文档（如 PTC 计费、Auto Model 路由等）。

八、社区、贡献与许可

完整指南与教程以官方文档站为准；Bug 反馈与新功能请求通过仓库 Issues 提交；
代码贡献流程见 CONTRIBUTING.md（含中文版本 CONTRIBUTING_CN.md），项目也在征集非中/英文的文档翻译贡献者；
本仓库采用ReflyAI Open Source License（见 LICENSE），本质上是在 Apache 2.0 基础上附加了额外限制的许可协议，商用前建议仔细阅读条款。

小结

Refly 的技术叙事可以用一条主线串起来：用自然语言描述业务意图（Vibe Mode + Model-Native DSL）→ 编译为带 Schema 契约的原子技能（skill package）→ 在有状态、可干预的运行时上确定性执行（BullMQ + 事件驱动）→ 以 API / Webhook / Skill 三种形态分发到任意 Agent 环境（Claude Code、Lark、Lovable 等）。本文所有端点、CLI 参数与目录结构均取自当前仓库的实际代码与文档，可直接作为二次开发与集成的参考基线。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析