Refly.AI 架构学习指南

嘿，欢迎来到 Refly 的世界！ 👋
这份指南会像一位经验丰富的老师一样，带你从零开始深入理解 Refly 这个 AI 原生工作流平台。别担心，我们会一步一步来，让复杂的架构变得清晰易懂。

第一部分：项目架构深度解析（像架构师一样俯瞰全景）🔍

本部分目标： 帮助你建立对 Refly 架构的整体认知，理解"为什么这样设计"而不仅仅是"这是什么"。

1. 项目架构概览

用一个类比来理解 Refly 💡

想象 Refly 就像一个智能乐高积木工厂：

乐高底板（Canvas）：用户在可视化画布上自由组织工作流
智能积木块（Nodes）：每个节点都是一个预封装的 AI Agent，可以是搜索工具、代码生成器、数据处理器等
自动组装机器人（Workflow Engine）：根据你的设计自动执行整个流程
智能助手（Copilot）：你用自然语言描述需求，它帮你自动搭建工作流
积木市场（Marketplace）：创作者可以发布自己的工作流模板，其他人一键使用并支付费用

这种设计让非技术用户也能像搭积木一样构建强大的 AI 自动化流程，而不需要编写代码。

核心设计特征

Refly 采用了Monorepo + 模块化微服务的混合架构：

refly/
├── apps/                    # 应用层（2个主应用）
│   ├── api/                # NestJS 后端服务（30+ 业务模块）
│   └── web/                # React 前端应用（基于 Rsbuild）
├── packages/               # 共享包层（20+ 工具包）
│   ├── ai-workspace-common/  # AI 工作空间通用组件
│   ├── canvas-common/        # Canvas 核心逻辑
│   ├── skill-template/       # AI 技能模板引擎
│   ├── providers/            # LLM 提供商抽象层
│   ├── stores/              # 全局状态管理
│   └── ...                  # 更多工具包
└── deploy/                 # 部署配置（Docker, K8s）

架构设计亮点：

Monorepo 管理：使用 pnpm + Turborepo 实现高效的代码共享和增量构建
领域驱动设计：后端按业务领域划分模块（auth, workflow, canvas, rag, knowledge 等）
前后端分离：通过 RESTful API + WebSocket 实现实时通信
插件化架构：AI 技能、工具、MCP 服务器都采用插件式设计，易于扩展

技术栈分析

后端核心技术栈（基于 apps/api/package.json）：

技术组件	版本	作用	设计考量
NestJS	10.3.9	企业级 Node.js 框架	模块化架构、依赖注入、装饰器语法，适合复杂业务系统
Prisma	5.16.1	类型安全的 ORM	自动生成 TypeScript 类型，Schema 即文档，迁移管理优雅
LangChain	0.3.30	LLM 应用框架	统一的 LLM 调用接口，支持链式推理、工具调用、记忆管理
Hocuspocus + Yjs	2.15.0	实时协作引擎	CRDT 算法保证多人同时编辑的一致性，类似 Google Docs
BullMQ	5.34.4	任务队列	基于 Redis 的分布式任务调度，支持优先级、延迟、重试
Qdrant	1.9.0	向量数据库	语义搜索、RAG 检索的核心，支持高效的向量相似度计算
LanceDB	0.19.1	嵌入式向量数据库	本地存储方案，适合桌面版和小规模部署
Redis	4.6.13	缓存 + 会话 + 队列	多用途：缓存热数据、WebSocket 会话、分布式锁
Stripe	14.19.0	支付网关	订阅计费、Webhook 事件处理
OpenTelemetry	0.208.0	可观测性	全链路追踪（Tempo + Grafana）+ LLM 专用追踪（Langfuse）
Sentry	7.113.0	错误监控	生产环境异常捕获和性能分析

前端核心技术栈（基于 apps/web/package.json）：

技术组件	版本	作用	设计考量
React	18.3.1	UI 框架	组件化、虚拟 DOM、丰富的生态
Ant Design	5.21.5	企业级 UI 组件库	开箱即用的高质量组件，主题定制能力强
Rsbuild	1.4.6	构建工具	基于 Rspack，比 Webpack 快 10 倍
TanStack Query	5.61.3	数据获取和缓存	自动缓存、后台重新验证、乐观更新
Framer Motion	12.23.6	动画库	声明式动画、手势交互、布局动画
Monaco Editor	4.7.0	代码编辑器	VS Code 同款编辑器，支持语法高亮、智能补全
i18next	25.3.2	国际化	支持中英文切换，动态加载翻译

外部系统集成

Refly 依赖以下中间件服务（通过 Docker Compose 启动）：

graph TB
    Refly[Refly 应用]

    subgraph "数据存储层"
        PG[(PostgreSQL<br/>主数据库)]
        Redis[(Redis Stack<br/>缓存+队列)]
        Qdrant[(Qdrant<br/>向量数据库)]
        MinIO[(MinIO<br/>对象存储)]
    end

    subgraph "搜索层"
        SearxNG[SearxNG<br/>元搜索引擎]
    end

    subgraph "可观测性层"
        Langfuse[Langfuse<br/>LLM 追踪]
        Tempo[Tempo<br/>分布式追踪]
    end

    Refly --> PG
    Refly --> Redis
    Refly --> Qdrant
    Refly --> MinIO
    Refly --> SearxNG
    Refly -.-> Langfuse
    Refly -.-> Tempo

各组件职责：

PostgreSQL：存储用户、项目、工作流、Canvas 数据等结构化数据
Redis：缓存、WebSocket 会话、BullMQ 任务队列
Qdrant：存储文档向量嵌入，支持语义搜索和 RAG
MinIO：S3 兼容的对象存储，保存上传的文件和媒体资源
SearxNG：聚合多个搜索引擎（Google, Bing 等）的结果，保护隐私
Langfuse（可选）：专门追踪 LLM 调用的 token 消耗、延迟、成本
Tempo + Grafana（可选）：APM 性能监控和分布式追踪

架构流程描述

让我们追踪一个典型的用户执行工作流的完整流程：

sequenceDiagram
    participant User as 用户浏览器
    participant Web as Web 前端
    participant API as API 服务
    participant Queue as BullMQ 队列
    participant Worker as Workflow Worker
    participant LLM as LLM 提供商
    participant DB as PostgreSQL
    participant Vector as Qdrant

    User->>Web: 1. 在 Canvas 上设计工作流
    Web->>API: 2. POST /v1/workflow/initialize
    API->>DB: 3. 创建 WorkflowExecution 记录
    API->>Queue: 4. 加入执行任务到队列
    API-->>Web: 5. 返回 executionId

    Queue->>Worker: 6. 分发任务
    Worker->>DB: 7. 获取 Canvas 数据和节点定义

    loop 按拓扑顺序执行每个节点
        Worker->>Worker: 8. 准备节点输入
        alt 节点类型是 AI Skill
            Worker->>Vector: 9. 检索相关知识（RAG）
            Worker->>LLM: 10. 调用 LLM API
            LLM-->>Worker: 11. 返回生成结果
        else 节点类型是 Tool
            Worker->>Worker: 12. 执行工具逻辑
        end
        Worker->>DB: 13. 保存节点执行结果
        Worker->>Web: 14. WebSocket 推送进度更新
    end

    Worker->>DB: 15. 标记工作流完成
    Worker->>Web: 16. WebSocket 推送完成事件
    Web->>User: 17. 展示最终结果

关键步骤解析：

前端交互：用户在可视化 Canvas 上拖拽节点，配置参数（或让 Copilot 自动生成）
初始化：API 验证权限后创建 WorkflowExecution 记录，生成唯一的 executionId
异步执行：任务加入 BullMQ 队列，立即返回给前端（避免长时间阻塞）
节点编排：Worker 根据节点的依赖关系（有向无环图 DAG）按拓扑顺序执行
AI 增强：如果节点是 Skill，会先通过 Qdrant 检索知识库（RAG），然后调用 LLM
实时反馈：通过 WebSocket 向前端推送每个节点的执行进度和结果
结果持久化：所有中间结果和最终输出都保存到数据库，支持回溯和调试

2. 目录结构与核心流程

目录组织逻辑

后端目录结构（apps/api/src/）：

apps/api/src/
├── main.ts                 # 应用入口，启动 NestJS 服务
├── modules/                # 业务模块（按领域划分）
│   ├── app.module.ts      # 根模块，导入所有子模块
│   │
│   ├── auth/              # 认证授权
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── guard/         # JWT、OAuth 守卫
│   │   └── strategy/      # Passport 策略
│   │
│   ├── workflow/          # ⭐ 工作流引擎（核心！）
│   │   ├── workflow.controller.ts   # API 端点
│   │   ├── workflow.service.ts      # 业务逻辑
│   │   ├── workflow.processor.ts    # BullMQ 任务处理器
│   │   └── workflow.dto.ts          # 数据传输对象
│   │
│   ├── canvas/            # Canvas 画布管理
│   ├── skill/             # AI 技能执行
│   ├── copilot/           # Copilot 助手
│   ├── rag/               # ⭐ 检索增强生成
│   ├── knowledge/         # 知识库管理
│   ├── search/            # 搜索功能
│   ├── collab/            # 实时协作（Hocuspocus）
│   ├── tool/              # 工具管理
│   ├── action/            # Action 执行
│   ├── provider/          # AI 提供商配置
│   ├── mcp-server/        # MCP 服务器集成
│   ├── subscription/      # 订阅和支付
│   └── user/              # 用户管理
│
├── utils/                 # 工具函数
│   ├── filters/           # 全局异常过滤器
│   ├── interceptors/      # HTTP 拦截器
│   ├── middleware/        # 中间件（Trace ID 等）
│   └── adapters/          # WebSocket 适配器
│
└── scripts/               # 脚本工具
    └── sync-db-schema.ts  # 数据库迁移

前端目录结构（apps/web/src/）：

apps/web/src/
├── index.tsx              # 应用入口
├── App.tsx                # 根组件
├── routes/                # 路由配置
│   └── index.tsx          # React Router 路由定义
│
├── pages/                 # 页面组件（按功能）
│   ├── workspace/         # ⭐ 工作空间（Canvas 主界面）
│   ├── workflow/          # 工作流管理
│   ├── workflow-app/      # 工作流应用运行页
│   ├── marketplace/       # 工作流市场
│   ├── project/           # 项目管理
│   ├── login/             # 登录页
│   └── ...
│
├── components/            # 全局组件
│   ├── ErrorFallback.tsx  # 错误边界
│   └── GlobalSEO.tsx      # SEO 元数据
│
└── config/                # 配置文件
    └── layout.ts          # 布局配置

共享包目录（packages/）：

packages/
├── canvas-common/         # ⭐ Canvas 核心逻辑
│   ├── workflow.ts        # 工作流执行算法
│   ├── node-executor.ts   # 节点执行器
│   ├── diff.ts            # Canvas 差异计算
│   └── types.ts           # 类型定义
│
├── ai-workspace-common/   # AI 工作空间通用组件
│   ├── components/        # 549+ React 组件
│   ├── hooks/             # 113+ React Hooks
│   └── modules/           # 功能模块
│
├── skill-template/        # AI 技能模板引擎
│   ├── engine/            # 执行引擎
│   ├── scheduler/         # 调度器
│   └── skills/            # 内置技能
│
├── providers/             # LLM 提供商抽象层
│   └── src/               # OpenAI, Anthropic 等实现
│
├── stores/                # Zustand 全局状态
│   └── src/stores/        # 各模块 Store
│
└── common-types/          # 共享 TypeScript 类型
    └── src/               # 接口定义

关键文件定位

第一个应该阅读的文件（后端）：

apps/api/src/main.ts - 了解应用启动流程、中间件、全局配置
apps/api/src/modules/app.module.ts - 查看所有业务模块的导入关系
apps/api/src/modules/workflow/workflow.controller.ts - 工作流的 API 端点定义
apps/api/src/modules/workflow/workflow.service.ts - 工作流执行的核心逻辑

第一个应该阅读的文件（前端）：

apps/web/src/index.tsx - 应用入口和全局 Provider
apps/web/src/routes/index.tsx - 路由配置，了解页面结构
packages/web-core/src/pages/workspace/index.tsx - 工作空间主界面
packages/canvas-common/src/workflow.ts - Canvas 数据结构和算法

模块依赖关系

基于代码分析，核心模块的依赖关系如下（单向依赖，无循环）：

graph TD
    subgraph "应用层"
        API[apps/api]
        Web[apps/web]
    end

    subgraph "业务逻辑层"
        Canvas[packages/canvas-common]
        AIWorkspace[packages/ai-workspace-common]
        SkillTemplate[packages/skill-template]
        Stores[packages/stores]
    end

    subgraph "基础设施层"
        Providers[packages/providers]
        CommonTypes[packages/common-types]
        Utils[packages/utils]
        Errors[packages/errors]
    end

    API --> Canvas
    API --> SkillTemplate
    API --> Providers
    API --> CommonTypes
    API --> Utils

    Web --> AIWorkspace
    Web --> Stores
    Web --> CommonTypes
    Web --> Utils

    Canvas --> CommonTypes
    AIWorkspace --> Canvas
    AIWorkspace --> Stores
    SkillTemplate --> Providers
    Stores --> CommonTypes

    Providers --> CommonTypes

    style Canvas fill:#ff9999
    style SkillTemplate fill:#ff9999
    style AIWorkspace fill:#99ccff

依赖关系说明：

自底向上：基础设施层 → 业务逻辑层 → 应用层
关键发现：
- canvas-common 是核心包，被前后端共同依赖
- common-types 定义了整个系统的类型契约
- skill-template 是 AI 能力的模板引擎，相对独立

典型业务流程：用户创建并执行工作流

让我们选择"用户通过 Copilot 创建工作流并执行"这个核心场景进行深入分析。

流程概述：

用户在 Canvas 上输入自然语言需求："帮我写一篇关于 AI 的博客"
Copilot 分析需求，自动生成工作流（包含搜索、总结、写作等节点）
用户点击"运行"，后端按拓扑顺序执行节点
前端实时展示每个节点的执行进度和结果
工作流完成，用户可以查看完整输出

详细流程图：

sequenceDiagram
    participant U as 用户
    participant C as Canvas 前端
    participant Copilot as Copilot API
    participant WF as Workflow API
    participant Q as BullMQ
    participant W as Worker
    participant LLM as LLM 服务
    participant DB as 数据库

    U->>C: 1. 输入："帮我写一篇关于 AI 的博客"
    C->>Copilot: 2. POST /v1/copilot/generate-workflow
    Copilot->>LLM: 3. 分析需求，生成节点结构
    LLM-->>Copilot: 4. 返回工作流 JSON
    Copilot->>DB: 5. 保存 Canvas 数据
    Copilot-->>C: 6. 返回生成的工作流
    C->>C: 7. 渲染工作流到 Canvas

    U->>C: 8. 点击"运行"按钮
    C->>WF: 9. POST /v1/workflow/initialize
    WF->>DB: 10. 创建 WorkflowExecution
    WF->>Q: 11. 加入任务到队列
    WF-->>C: 12. 返回 executionId

    Q->>W: 13. 分发任务给 Worker
    W->>DB: 14. 读取 Canvas 节点定义

    loop 节点1: 搜索资料
        W->>LLM: 15. 调用搜索工具
        LLM-->>W: 16. 返回搜索结果
        W->>DB: 17. 保存节点执行结果
        W->>C: 18. WebSocket 推送进度
    end

    loop 节点2: 总结要点
        W->>LLM: 19. 调用 LLM 总结
        LLM-->>W: 20. 返回总结内容
        W->>DB: 21. 保存执行结果
        W->>C: 22. WebSocket 推送进度
    end

    loop 节点3: 撰写博客
        W->>LLM: 23. 调用 LLM 写作
        LLM-->>W: 24. 返回博客全文
        W->>DB: 25. 保存最终结果
        W->>C: 26. WebSocket 推送完成
    end

    W->>DB: 27. 标记工作流完成
    C->>U: 28. 展示完整博客内容

实现文件索引：

步骤	实现文件	说明
1-7	`packages/ai-workspace-common/src/components/canvas/`	Canvas 渲染和交互逻辑
2-6	`apps/api/src/modules/copilot/copilot.service.ts`	Copilot 工作流生成
9-12	`apps/api/src/modules/workflow/workflow.controller.ts`	初始化工作流
10	`apps/api/src/modules/workflow/workflow.service.ts`	创建执行记录
13-27	`apps/api/src/modules/workflow/workflow.processor.ts`	BullMQ 任务处理器
14	`packages/canvas-common/src/workflow.ts`	节点拓扑排序算法
15-24	`apps/api/src/modules/skill/skill-invoker.service.ts`	技能调用封装
18,22,26	`apps/api/src/modules/collab/collab.gateway.ts`	WebSocket 推送

3. 代码结构观察

代码组织模式

通过分析 apps/api/src/modules/workflow/workflow.service.ts，我们可以看到 Refly 遵循了典型的 NestJS 最佳实践：

观察到的设计模式：

依赖注入：通过构造函数注入服务依赖，便于测试和解耦

@Injectable()
export class WorkflowService {
   
  constructor(
    private readonly prisma: PrismaService,
    private readonly redis: RedisService,
    private readonly skillService: SkillService,
    private readonly canvasService: CanvasService,
    @InjectQueue(QUEUE_RUN_WORKFLOW) private readonly runWorkflowQueue?: Queue,
  ) {
   }
}

策略模式：不同类型的节点（Skill, Tool, Action）有不同的执行策略
观察者模式：通过 WebSocket 向前端推送执行状态变更
工厂模式：动态创建不同类型的 AI 提供商实例

设计模式识别

在 packages/canvas-common/src/ 中识别到的核心模式：

// 策略模式：节点执行器
export interface NodeExecutor {
   
  canExecute(node: CanvasNode): boolean;
  execute(node: CanvasNode, context: ExecutionContext): Promise<NodeResult>;
}

// 工厂模式：创建不同类型的节点执行器
export class NodeExecutorFactory {
   
  static create(nodeType: string): NodeExecutor {
   
    switch (nodeType) {
   
      case 'skill': return new SkillExecutor();
      case 'tool': return new ToolExecutor();
      case 'action': return new ActionExecutor();
      default: throw new Error(`Unknown node type: ${
     nodeType}`);
    }
  }
}

// 建造者模式：构建复杂的工作流执行计划
export class WorkflowPlanBuilder {
   
  private nodes: CanvasNode[] = [];
  private edges: Edge[] = [];

  withNodes(nodes: CanvasNode[]): this {
   
    this.nodes = nodes;
    return this;
  }

  withEdges(edges: Edge[]): this {
   
    this.edges = edges;
    return this;
  }

  build(): WorkflowPlan {
   
    return new WorkflowPlan(this.nodes, this.edges);
  }
}

代码质量观察

优点：

✅ 类型安全：全项目使用 TypeScript，充分利用类型系统防止错误
✅ 模块化：业务逻辑按领域清晰划分，单一职责原则执行良好
✅ 测试覆盖：关键模块有对应的 .test.ts 文件（如 workflow.test.ts）
✅ 错误处理：自定义异常类（@refly/errors），错误信息清晰
✅ 日志规范：使用 Pino 结构化日志，包含 Trace ID 便于追踪

可以关注的学习重点：

💡 函数复杂度：workflow.service.ts 中的 initializeWorkflowExecution 方法较长（约 100+ 行），可以思考如何进一步拆分
💡 类型复用：大量使用 Partial<T>、Pick<T, K> 等工具类型，值得学习
💡 异步处理：合理使用 Promise.all 并行执行独立任务，提升性能

潜在改进点（学习机会）

通过搜索代码中的 TODO 和 FIXME 注释，我发现了一些值得探索的重构机会：

性能优化点：
- 🔍 批量查询优化：在 workflow.service.ts 中，节点执行结果的查询可以考虑批量加载
- 🔍 缓存策略：AI 提供商的配置可以增加缓存层，减少数据库查询
代码复用机会：
- 🔍 公共逻辑提取：多个 Service 中都有权限校验逻辑，可以抽取为装饰器或守卫
- 🔍 类型定义统一：部分类型定义散落在不同文件，可以集中到 common-types
测试增强：
- 🔍 集成测试：工作流执行的端到端测试可以补充
- 🔍 边界情况：节点执行超时、LLM 调用失败等异常场景的测试覆盖

注意： 这些不是"代码问题"，而是学习 Refly 时可以深入思考的方向，帮助你理解架构设计的权衡。

第二部分：技能需求清单（你的学习弹药库）📚

本部分目标： 明确学习 Refly 需要掌握哪些技能，以及达到什么程度。

1. 基础技能要求

编程语言和框架

必须掌握：

技能	最低要求	推荐掌握程度
TypeScript	5.3.3 语法	熟练使用泛型、装饰器、类型推导；理解 `Partial`, `Pick`, `Omit` 等工具类型
Node.js	v20.19.0 (LTS)	理解事件循环、异步编程（Promise, async/await）；熟悉 `fs`, `path` 等核心模块
NestJS	10.3.9	理解依赖注入、模块系统、装饰器；会使用 Controller, Service, Guard, Interceptor
React	18.3.1	熟练使用 Hooks（useState, useEffect, useCallback, useMemo）；理解组件生命周期
SQL	基础	能读懂 Prisma Schema；理解增删改查、索引、外键

具体版本要求（来自 package.json）：

{
   
  "engines": {
   
    "node": ">=20.19.0",
    "pnpm": ">=9"
  },
  "dependencies": {
   
    "@nestjs/common": "~10.3.9",
    "react": "^18.3.1",
    "typescript": "5.3.3"
  }
}

⚠️ 版本兼容性提示：Refly 使用的 TypeScript 5.3.3 支持最新的装饰器语法，但与 5.0 之前的版本有不兼容变更，请确保使用正确的版本。

基础工具和概念

✅ Git 版本控制：熟悉分支管理、PR 流程
✅ Docker：理解镜像、容器、网络、数据卷概念；会使用 docker-compose
✅ pnpm：Monorepo 包管理工具，比 npm/yarn 更高效
✅ Turborepo：Monorepo 构建工具，支持增量构建和缓存
✅ REST API：理解 HTTP 方法、状态码、请求/响应结构
✅ WebSocket：理解全双工通信、心跳保活机制

2. 进阶技能要求

架构模式和设计原则

领域驱动设计（DDD）：

Refly 后端按业务领域划分模块（如 workflow, canvas, knowledge）
理解聚合根、实体、值对象、领域服务的概念

SOLID 原则：

单一职责：每个 Service 只负责一个业务领域
开闭原则：通过接口和抽象类扩展功能（如 NodeExecutor 接口）
依赖倒置：高层模块不依赖低层模块（如 WorkflowService 依赖 SkillService 接口而非实现）

事件驱动架构（EDA）：

BullMQ 任务队列实现异步处理
WebSocket 实现事件推送

领域特定知识

AI 和 LLM 相关：

概念	说明	在 Refly 中的应用
LangChain	LLM 应用开发框架	统一调用不同 LLM 提供商，支持链式推理
RAG（检索增强生成）	从知识库检索相关内容后再生成回答	`rag` 模块实现语义搜索 + LLM 生成
向量嵌入（Embedding）	将文本转为高维向量，用于语义相似度计算	使用 OpenAI Embeddings 生成向量
Prompt Engineering	设计高质量的 LLM 输入提示	`skill-template` 中定义各种 Prompt 模板
Token 计数	统计 LLM 输入/输出的 Token 数量，用于计费	使用 `gpt-tokenizer` 库

实时协作技术：

概念	说明	在 Refly 中的应用
CRDT（无冲突复制数据类型）	多人同时编辑时保证最终一致性	Yjs 实现 CRDT 算法
Hocuspocus	Yjs 的 WebSocket 后端服务器	处理多人协作的同步逻辑
Operational Transform（OT）	另一种协作算法（Google Docs 使用）	Refly 选择了 CRDT 而非 OT

工作流编排：

概念	说明	在 Refly 中的应用
DAG（有向无环图）	节点之间的依赖关系不能形成环	Canvas 的节点连线必须是 DAG
拓扑排序	按依赖顺序执行节点	`canvas-common/src/workflow.ts` 中实现
并行执行	无依赖关系的节点可以同时执行	使用 `Promise.all` 并行调用 LLM

3. 技能掌握程度建议

对于初学者（0-1年经验）

学习重点：

先掌握 TypeScript 基础语法（类型系统、接口、泛型）
学习 React Hooks（通过官方教程）
理解 NestJS 的依赖注入和模块系统
熟悉 Git 基本操作（clone, branch, commit, push, pull）

达到的目标：

能读懂 Refly 的代码结构
能修改简单的 UI 组件或添加新的 API 端点
能在本地成功运行项目

对于有经验的开发者（1-3年）

学习重点：

深入理解 LangChain 的核心概念（Chains, Agents, Tools）
学习 向量数据库的使用（Qdrant 或 Pinecone）
掌握 Prisma ORM（Schema 定义、迁移、关系查询）
理解 BullMQ 任务队列的工作机制

达到的目标：

能独立实现一个新的工作流节点类型
能优化现有的 RAG 检索逻辑
能设计并实现一个新的业务模块

对于意欲贡献代码的进阶者（3年+）

学习重点：

研究 CRDT 算法和 Yjs 的实现原理
学习 OpenTelemetry的分布式追踪（Trace, Span, Context）
掌握 Monorepo 最佳实践（依赖管理、版本控制）
理解 LLM 的成本优化策略（Prompt 压缩、缓存、流式输出）

达到的目标：

能进行架构级别的优化（如性能瓶颈分析、数据库查询优化）
能设计新的 AI 能力（如新的 RAG 策略、多模态支持）
能参与核心模块的重构和演进

第三部分：学习路径规划（你的专属教练计划）🎯

本部分目标： 提供清晰、可操作的阶梯式学习路径，让你从零到精通。

1. 项目运行入口定位（快速上手）

一键启动指南 ⚡

前置条件检查：

# 1. 检查 Docker 是否安装
docker --version
# 期望输出：Docker version 20.10.0 或更高

# 2. 检查 Node.js 版本
node -v
# 期望输出：v20.19.0 或更高

# 3. 检查 pnpm 是否可用
pnpm -v
# 期望输出：9.15.9
# 如果没有安装，运行：corepack enable

步骤 1：克隆项目

# 克隆官方仓库（或你 Fork 的仓库）
git clone https://github.com/refly-ai/refly.git
cd refly

步骤 2：启动中间件服务（预计耗时：5-10 分钟，取决于网络速度）

# 启动 PostgreSQL, Redis, Qdrant, MinIO, SearxNG
docker compose -f deploy/docker/docker-compose.middleware.yml -p refly up -d

# 检查容器健康状态
docker ps | grep refly_

✅ 验证成功标志： 所有容器的 STATUS 列显示 healthy 或 Up（某些容器可能没有健康检查）

⚠️ 常见陷阱：

端口冲突：如果你本地已有 PostgreSQL（默认 5432），会冲突。解决方案：修改 docker-compose.middleware.yml 中的端口映射
磁盘空间不足：Docker 镜像约需 2-3GB 空间
网络问题：某些镜像可能需要科学上网，建议配置 Docker 镜像加速

步骤 3：安装依赖（预计耗时：3-5 分钟）

# 启用 pnpm（如果尚未安装）
corepack enable

# 安装所有依赖
pnpm install

步骤 4：配置环境变量

# 从模板复制环境变量文件
pnpm copy-env:develop

# ⚠️ 重要：配置 AI 提供商密钥
# 编辑 apps/api/.env 文件，添加你的 OpenAI API Key：
# OPENAI_API_KEY=sk-your-key-here

💡 提示：如果暂时没有 OpenAI API Key，可以先跳过，部分功能将无法使用。

步骤 5：构建项目（预计耗时：5-10 分钟）

# 首次构建所有包
pnpm build

步骤 6：启动开发服务器

# 方式 1：同时启动前后端（推荐）
pnpm dev

# 方式 2：分别启动（用于调试）
# 终端 1：
cd apps/api && pnpm dev

# 终端 2：
cd apps/web && pnpm dev

✅ 验证成功标志：

API 服务：访问 http://localhost:3000/api 看到 {"message": "Hello World!"}
Web 前端：访问 http://localhost:5173 看到登录页面

步骤 7：创建首个账户

打开浏览器访问 http://localhost:5173
点击「注册」，使用邮箱注册账号
登录后即可看到工作空间

🎉 恭喜！ 你已经成功运行了 Refly，可以开始探索了！

环境配置清单

最常见的配置陷阱及解决方案：

问题	症状	解决方案
端口冲突	`Error: Port 35432 already in use`	修改 `docker-compose.middleware.yml` 中的端口映射，或停止本地 PostgreSQL
数据库连接失败	`PrismaClientInitializationError`	检查 `apps/api/.env` 中的 `DATABASE_URL` 是否正确
Redis 连接失败	`Error: connect ECONNREFUSED 127.0.0.1:36379`	确认 Redis 容器正在运行：`docker ps	grep refly_redis`
Qdrant 连接失败	`Failed to connect to Qdrant`	检查 Qdrant 容器健康状态，可能需要等待 30 秒初始化
MinIO 权限错误	`AccessDenied`	访问 http://localhost:39001 用 `minioadmin/minioadmin` 登录，创建 bucket
Node 版本不匹配	`SyntaxError: Unexpected token`	确保使用 Node.js >= 20.19.0，推荐使用 nvm 管理版本
pnpm 依赖安装失败	`ERR_PNPM_NO_MATCHING_VERSION`	清理缓存：`pnpm store prune && pnpm install`
Prisma 迁移失败	`Migration failed`	手动执行：`cd apps/api && pnpm prisma migrate deploy`

环境变量重要参数说明（apps/api/.env）：

# 数据库连接（PostgreSQL）
DATABASE_URL=postgresql://refly:test@localhost:35432/refly

# Redis 连接
REDIS_URL=redis://localhost:36379

# Qdrant 向量数据库
QDRANT_URL=http://localhost:36333

# MinIO 对象存储
MINIO_ENDPOINT=localhost
MINIO_PORT=39000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

# OpenAI API（核心，必须配置）
OPENAI_API_KEY=sk-your-api-key-here

# 可选：其他 LLM 提供商
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=

# SearxNG 搜索引擎
SEARXNG_URL=http://localhost:38080

# 应用配置
PORT=3000
WS_PORT=3001
NODE_ENV=development
ORIGIN=http://localhost:5173

# JWT 密钥（自动生成，无需修改）
JWT_SECRET=auto-generated-secret

2. 循序渐进学习计划（四阶段法）

阶段一：环境搭建和项目启动（1-2 天）💪

目标： 成功运行项目并能打断点调试。

任务清单：

[ ] 完成上述"一键启动指南"的所有步骤
[ ] 在 VS Code 中打开项目，安装推荐的扩展（TypeScript, Prisma, ESLint）
[ ] 在 apps/api/src/modules/workflow/workflow.controller.ts 的第 33 行打断点
[ ] 使用 VS Code 的调试功能（F5）启动 API 服务
[ ] 在前端触发工作流执行，观察断点被命中

学习资源：

阅读 CONTRIBUTING.md 了解完整的开发流程
观看 VS Code 调试 Node.js 的视频教程

验证标准：
✅ 能在 10 分钟内重新启动整个项目
✅ 能使用 Chrome DevTools 调试前端代码
✅ 能使用 VS Code 断点调试后端代码

阶段二：核心流程理解（3-5 天）🔍

目标： 追踪一个完整的工作流执行流程，理解数据流转。

任务清单：

[ ] 任务 1：理解 Canvas 数据结构
- 阅读 packages/canvas-common/src/types.ts
- 在数据库中查看 Canvas 表的数据（使用 Prisma Studio：cd apps/api && pnpm prisma studio）
- 理解节点（Node）、边（Edge）、变量（Variable）的关系
[ ] 任务 2：追踪工作流初始化
- 在 workflow.controller.ts 的 initializeWorkflow 方法打断点
- 在前端创建一个简单工作流（只有 1 个节点）并运行
- 单步调试，观察 WorkflowExecution 记录的创建
- 查看 BullMQ 任务是如何加入队列的
[ ] 任务 3：理解节点执行逻辑
- 找到 workflow.processor.ts 文件
- 理解 @Process() 装饰器的作用
- 追踪一个节点从"待执行"到"执行完成"的全过程
- 观察 WebSocket 是如何推送进度的
[ ] 任务 4：画出你自己的流程图
- 用 draw.io 或 Mermaid 画出工作流执行的完整流程
- 标注每个步骤涉及的文件和函数
- 与本文档第一部分的流程图对比，看是否有遗漏

学习资源：

LangChain 官方文档：搜索 "LangChain Concepts"
BullMQ 官方文档：搜索 "BullMQ Guide"
Prisma Studio 使用指南

验证标准：
✅ 能说出工作流从创建到完成的 8 个关键步骤
✅ 能指出每个步骤对应的代码文件
✅ 能自己画出完整的序列图

阶段三：模块深入和定制开发（1-2 周）🛠️

目标： 能修改或扩展一个现有功能。

任务清单：

[ ] 任务 1：创建自定义 AI 技能
- 阅读 packages/skill-template/src/skills/ 中的示例
- 创建一个新的技能（如"情感分析"）
- 定义输入输出 Schema
- 编写 Prompt 模板
- 在前端添加该技能的节点
[ ] 任务 2：扩展 RAG 检索能力
- 研究 apps/api/src/modules/rag/ 模块
- 理解向量嵌入的生成过程
- 尝试调整检索的相似度阈值
- 测试不同 Top-K 值对结果的影响
[ ] 任务 3：优化前端交互
- 修改 Canvas 的节点样式
- 添加一个新的快捷键（如 Ctrl+S 保存）
- 优化工作流执行时的加载动画
[ ] 任务 4：实现一个小功能
- 例如：添加"工作流执行历史"的筛选功能
- 前端：添加日期选择器
- 后端：修改查询逻辑
- 测试：确保功能正常工作

学习资源：

Ant Design 组件库文档
Qdrant 向量数据库教程：搜索 "Qdrant Quickstart"
React Query 官方文档：搜索 "TanStack Query Guide"

验证标准：
✅ 能独立完成一个端到端的功能开发（前端 + 后端 + 数据库）
✅ 能编写基本的单元测试
✅ 能提交一个符合规范的 Pull Request

阶段四：架构理解和贡献指南（2 周+）🚀

目标： 理解技术选型的原因，能参与架构级别的讨论。

任务清单：

[ ] 任务 1：研究 CRDT 和实时协作
- 阅读 Yjs 的论文或博客
- 理解 Hocuspocus 如何处理多人同步
- 尝试在本地打开两个浏览器窗口，测试协作编辑
[ ] 任务 2：深入 LangChain 和 Agent
- 研究 skill-template 中的 Prompt 设计
- 理解 ReAct（Reasoning + Acting）模式
- 尝试使用 LangChain 的 Tools 和 Agents
[ ] 任务 3：性能优化实践
- 使用 Chrome DevTools 的 Performance 面板分析前端性能
- 使用 OpenTelemetry 追踪后端 API 的延迟
- 找到一个性能瓶颈并优化（如数据库 N+1 查询）
[ ] 任务 4：贡献开源
- 在 GitHub Issues 中找到一个 good first issue
- 与维护者沟通实现方案
- 提交 PR 并参与 Code Review

学习资源：

Yjs 官方文档：搜索 "Yjs Documentation"
LangChain Agent 教程：搜索 "LangChain Agents"
OpenTelemetry 入门指南：搜索 "OpenTelemetry JavaScript"

验证标准：
✅ 能解释为什么 Refly 选择 Yjs 而不是 OT 算法
✅ 能独立设计一个新的 AI Agent 工作流
✅ 至少有 1 个 PR 被合并到主分支

3. 学习路径流程图

graph TB
    Start([开始学习 Refly])

    subgraph "阶段一：环境搭建 1-2天"
        A1[克隆项目]
        A2[启动 Docker 中间件]
        A3[安装依赖]
        A4[配置环境变量]
        A5[首次运行项目]
        A6[配置 IDE 调试]
    end

    subgraph "阶段二：核心流程 3-5天"
        B1[理解 Canvas 数据结构]
        B2[追踪工作流初始化]
        B3[理解节点执行逻辑]
        B4[画出完整流程图]
    end

    subgraph "阶段三：模块深入 1-2周"
        C1[创建自定义技能]
        C2[扩展 RAG 检索]
        C3[优化前端交互]
        C4[实现一个小功能]
    end

    subgraph "阶段四：架构理解 2周+"
        D1[研究 CRDT 协作]
        D2[深入 LangChain]
        D3[性能优化实践]
        D4[贡献开源代码]
    end

    Start --> A1
    A1 --> A2
    A2 --> A3
    A3 --> A4
    A4 --> A5
    A5 --> A6

    A6 -.遇到问题?.- Troubleshoot{查看常见陷阱<br/>或提 Issue}
    Troubleshoot -.解决后.- A6

    A6 --> B1
    B1 --> B2
    B2 --> B3
    B3 --> B4

    B4 -.需要补充知识?.- LearnBasics[学习 NestJS/LangChain 基础]
    LearnBasics --> B4

    B4 --> C1
    C1 --> C2
    C2 --> C3
    C3 --> C4

    C4 --> D1
    D1 --> D2
    D2 --> D3
    D3 --> D4

    D4 --> End([成为 Refly 贡献者 🎉])

    style Start fill:#90EE90
    style End fill:#FFD700
    style Troubleshoot fill:#FF6B6B
    style LearnBasics fill:#87CEEB

关键决策点：

阶段一遇到问题：不要死磕，先查看"环境配置清单"，如果 30 分钟内没解决，去 Discord 或 GitHub Issues 提问
阶段二感到困惑：正常现象！复杂系统需要时间消化，建议先学习 NestJS 和 LangChain 的基础教程
阶段三选择方向：根据兴趣选择深入前端（UI/UX）还是后端（AI/数据）
阶段四进阶：考虑是否要深入特定领域（如协作算法、向量数据库、LLM 优化）

第四部分：实践建议和进阶指导（从会用到精通）💡

本部分目标： 提供实用的调试技巧、练习题和贡献指南。

1. 调试技巧和常见陷阱

后端调试技巧

方法 1：VS Code 断点调试（推荐）

在 .vscode/launch.json 中添加配置：

{
   
  "version": "0.2.0",
  "configurations": [
    {
   
      "type": "node",
      "request": "launch",
      "name": "Debug API",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["--filter", "@refly/api", "dev"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal",
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

按 F5 启动调试，在代码中打断点即可。

方法 2：日志调试

Refly 使用 Pino 结构化日志，推荐格式：

this.logger.log(`[WORKFLOW_EXEC] executionId=${
     executionId} status=${
     status}`);

在生产环境会输出 JSON，便于日志聚合工具（如 Grafana Loki）解析。

方法 3：OpenTelemetry 追踪

查看分布式追踪：

启动 Tempo（可选）：docker compose -f deploy/docker/trace/docker-compose.yml up -d
访问 Grafana：http://localhost:3001
搜索 Trace ID（在响应头或日志中找到）

前端调试技巧

方法 1：React DevTools

安装浏览器扩展：搜索 "React Developer Tools"

方法 2：Redux DevTools

Refly 使用 Zustand，但支持 Redux DevTools：

import {
    devtools } from 'zustand/middleware';

export const useStore = create(
  devtools((set) => ({
   
    // ...
  }))
);

方法 3：网络请求调试

在 Chrome DevTools 的 Network 面板中：

筛选 XHR/Fetch 请求
查看 Request Payload 和 Response
复制为 cURL 在终端重放

新人常见的 5 个陷阱

陷阱	表现	原因	解决方案
1. Docker 容器未启动	API 无法连接数据库	忘记执行 `docker-compose up`	运行 `docker ps` 检查容器状态
2. 环境变量未配置	`OPENAI_API_KEY is not defined`	未执行 `pnpm copy-env:develop`	复制 `.env.example` 并填写密钥
3. Prisma Schema 未同步	`Unknown arg 'newField'`	修改了 Schema 但未重新生成	运行 `pnpm prisma generate`
4. 端口被占用	`EADDRINUSE: address already in use`	之前的进程未关闭	杀死进程或更换端口
5. 依赖版本冲突	某个包无法安装	pnpm lockfile 过期	删除 `node_modules` 和 `pnpm-lock.yaml` 后重新安装

2. 扩展练习建议

这里提供 10 个从易到难的练习，帮助你巩固所学知识。

🌟 初级练习（1-3 小时完成）

练习 1：修改 Canvas 节点颜色

目标：让所有"Skill"类型的节点显示为蓝色
提示：找到 packages/ai-workspace-common/src/components/canvas/ 中的节点渲染组件
验证：刷新页面后节点颜色改变

练习 2：添加工作流执行时间统计

目标：在工作流完成后显示总耗时
提示：修改 WorkflowExecution 表，添加 startTime 和 endTime 字段
验证：在前端展示"执行耗时：XX 秒"

练习 3：自定义欢迎消息

目标：用户首次登录时显示欢迎弹窗
提示：在 apps/web/src/App.tsx 中检查用户是否第一次登录
验证：创建新账户后看到弹窗

🌟🌟 中级练习（3-8 小时完成）

练习 4：实现工作流模板收藏功能

目标：用户可以收藏喜欢的工作流模板
提示：
- 后端：添加 FavoriteTemplate 表
- API：实现 POST /v1/template/:id/favorite
- 前端：添加收藏按钮和图标
验证：收藏后在"我的收藏"页面显示

练习 5：优化 RAG 检索结果展示

目标：在节点执行结果中显示检索到的知识片段
提示：修改 rag.service.ts 的返回值，包含 sourceDocuments
验证：在前端能看到"参考资料"区域

练习 6：添加工作流执行进度条

目标：实时显示"已完成 3/5 个节点"
提示：通过 WebSocket 推送进度百分比
验证：执行时看到动态进度条

🌟🌟🌟 高级练习（8+ 小时完成）

练习 7：实现条件分支节点

目标：根据条件（如"情感 > 0.5"）选择不同的执行路径
提示：
- 扩展 CanvasNode 类型，添加 condition 字段
- 修改拓扑排序算法，支持条件跳转
验证：创建包含 if-else 分支的工作流

练习 8：集成新的 LLM 提供商（如 DeepSeek）

目标：支持调用 DeepSeek API
提示：
- 在 packages/providers/ 中实现新的 Provider
- 遵循 LangChain 的 BaseChatModel 接口
验证：在设置中选择 DeepSeek 并成功调用

练习 9：实现工作流版本控制

目标：保存工作流的历史版本，支持回滚
提示：
- 添加 CanvasVersion 表
- 每次修改时自动创建快照
验证：在历史记录中查看和恢复旧版本

练习 10：性能优化：批量加载节点执行结果

目标：减少数据库查询次数，使用 DataLoader 模式
提示：
- 使用 Promise.all 批量查询
- 添加 Redis 缓存层
验证：使用 OpenTelemetry 对比优化前后的查询次数

3. 参与贡献的途径

寻找适合新人的 Issue

访问 Refly GitHub Issues
筛选标签：
- good first issue：适合新人的简单任务
- help wanted：需要社区帮助的问题
- documentation：文档改进（最容易上手）

代码规范要求

Refly 使用 Biome 进行代码检查和格式化（比 ESLint + Prettier 快 10 倍）。

提交前必须执行：

# 检查并自动修复问题
pnpm check:fix

# 格式化代码
pnpm format

命名规范（来自 .cursor/rules/01-code-style.mdc）：

变量名：小驼峰 userProfile
类名：大驼峰 WorkflowService
常量：大写下划线 MAX_RETRY_COUNT
文件名：kebab-case workflow-executor.ts

注释要求（来自 .cursor/rules/00-language-priority.mdc）：

⚠️ 所有代码注释必须使用英文！ 这是强制要求。

// ✅ Good: Clear English comment
// Fetch user profile from database

// ❌ Bad: Chinese comment
// 从数据库获取用户资料

提交流程

Fork 项目 → 在 GitHub 上点击 Fork 按钮
创建分支 → git checkout -b feat/my-new-feature
开发并测试 → 确保通过 pnpm test
提交代码 → 使用规范的 Commit Message（见下方）
推送到 Fork → git push origin feat/my-new-feature
创建 Pull Request → 在 GitHub 上点击"New Pull Request"
等待 Code Review → 维护者会审查代码并提出修改建议

Commit Message 规范（Conventional Commits）：

<type>(<scope>): <subject>

<body>

<footer>

示例：

feat(workflow): add conditional branch node

- Implement condition evaluation logic
- Add UI component for condition editor
- Update workflow execution engine

Closes #123

Type 类型：

feat：新功能
fix：Bug 修复
docs：文档更新
style：代码格式（不影响逻辑）
refactor：重构（既非新功能也非修复）
test：测试相关
chore：构建工具、依赖更新

获得帮助的渠道

Discord 社区：搜索 "Refly Discord" 加入实时聊天
GitHub Discussions：https://github.com/refly-ai/refly/discussions
官方文档：https://docs.refly.ai

第五部分：技术栈学习指引（你的知识地图）🌐

本部分旨在：为前面识别出的关键技能，提供精准、高质量的学习路径指引。

1. 官方文档定位（学习的基石）

核心技术栈文档

技术	官方文档名称	重点学习章节	优先级
NestJS	NestJS Documentation	Fundamentals → Controllers, Providers, Modules, Middleware, Guards	⭐⭐⭐
React	React Docs (Beta)	Learn React → Hooks, useEffect, useCallback, Context	⭐⭐⭐
Prisma	Prisma Documentation	Concepts → Data model, Relations, Queries, Migrations	⭐⭐⭐
LangChain	LangChain JS/TS Docs	Core Concepts → Chains, Agents, Tools, Memory	⭐⭐⭐
TypeScript	TypeScript Handbook	Handbook → Generics, Decorators, Utility Types	⭐⭐
Ant Design	Ant Design Components	Components → Form, Table, Modal, Message	⭐⭐
TanStack Query	TanStack Query Docs	Guides → Queries, Mutations, Caching	⭐⭐
BullMQ	BullMQ Documentation	Guide → Queues, Jobs, Processors, Events	⭐⭐
Qdrant	Qdrant Documentation	Tutorials → Quick Start, Collections, Search	⭐⭐
Yjs	Yjs Documentation	Getting Started, Shared Types, Awareness	⭐
Hocuspocus	Hocuspocus Guide	Extensions, Authentication, Webhooks	⭐
OpenTelemetry	OpenTelemetry JS Docs	Manual → Tracing, Context, Exporters	⭐

学习顺序建议：

第一周：NestJS + React + TypeScript 基础
第二周：Prisma + LangChain 入门
第三周：TanStack Query + Ant Design 实战
第四周：BullMQ + Qdrant + Yjs 进阶

项目自身文档

必读：README.md - 项目简介和快速开始
必读：CONTRIBUTING.md - 开发环境搭建和贡献指南
推荐：deploy/docker/README.md - Docker 部署说明
推荐：.cursor/rules/ 目录下的所有规范文件

优先级：

先读 README.md 和 CONTRIBUTING.md（30 分钟）
再读 .cursor/rules/01-code-style.mdc（了解代码风格）
根据需要查阅其他规范文件

权威技术书籍

书名	作者	适用阶段	说明
《Node.js 设计模式》	Mario Casciaro	进阶	深入理解 Node.js 异步编程和设计模式
《深入浅出 React 和 Redux》	程墨	中级	React 生态系统全面讲解（虽然 Refly 用 Zustand，但原理相通）
《TypeScript 编程》	Boris Cherny	中级	TypeScript 类型系统深度解析
《设计数据密集型应用》	Martin Kleppmann	高级	理解分布式系统、数据库、消息队列的设计原理

2. 学习路径建议（社区智慧）

技能学习顺序

对于后端方向：

graph LR
    A[TypeScript 基础] --> B[NestJS 核心概念]
    B --> C[Prisma ORM]
    C --> D[LangChain 入门]
    D --> E[向量数据库 Qdrant]
    E --> F[BullMQ 任务队列]
    F --> G[OpenTelemetry 追踪]

    style A fill:#90EE90
    style D fill:#FFD700
    style G fill:#FF6B6B

对于前端方向：

graph LR
    A[React Hooks] --> B[Zustand 状态管理]
    B --> C[TanStack Query]
    C --> D[Ant Design 组件]
    D --> E[Canvas 渲染优化]
    E --> F[WebSocket 实时通信]
    F --> G[Yjs 协作编辑]

    style A fill:#90EE90
    style E fill:#FFD700
    style G fill:#FF6B6B

核心概念优先级

立即学习（必须掌握）：

TypeScript 类型系统：interface, type, generics, utility types
NestJS 依赖注入：@Injectable(), providers, modules
React Hooks：useState, useEffect, useCallback, useMemo
Prisma Schema：model, relation, migration

1 个月内学习（重要）：

LangChain Chains：LLMChain, SequentialChain
LangChain Tools：自定义工具，工具调用
向量检索：Embedding, Similarity Search
BullMQ：Queue, Job, Processor

3 个月内学习（进阶）：

CRDT 算法：Yjs 的实现原理
OpenTelemetry：Trace, Span, Context Propagation
LangChain Agents：ReAct, Plan-and-Execute
性能优化：数据库索引、查询优化、缓存策略

实践项目推荐

类似项目（代码学习参考）：

n8n：工作流自动化平台（搜索 "n8n GitHub"）
- 学习重点：节点系统、工作流执行引擎
- 对比：Refly 的节点更智能（AI Agent），n8n 更通用
Flowise：LangChain 可视化工具（搜索 "FlowiseAI GitHub"）
- 学习重点：LangChain 的可视化封装
- 对比：Flowise 专注于 LLM 链，Refly 是完整的工作流平台
Activepieces：开源自动化工具（搜索 "Activepieces GitHub"）
- 学习重点：插件系统、触发器设计
- 对比：Refly 有更强的 AI 能力和协作功能

学习建议：

不要完整阅读这些项目的代码（太大）
聚焦于你想实现的功能，搜索相关文件
对比不同项目的设计决策，思考优劣

3. 工具与环境配置指南

开发环境搭建

推荐 IDE：VS Code

必装扩展（搜索 VS Code Extensions）：

Prisma：Prisma Schema 语法高亮和自动补全
ESLint：虽然 Refly 用 Biome，但某些包可能还用 ESLint
Biome：代码格式化和检查
Docker：管理 Docker 容器
Thunder Client：API 测试（类似 Postman）
GitLens：Git 增强工具

配置建议（settings.json）：

{
   
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "editor.codeActionsOnSave": {
   
    "quickfix.biome": "explicit"
  },
  "[prisma]": {
   
    "editor.defaultFormatter": "Prisma.prisma"
  }
}

常用工具使用

Prisma Studio（数据库可视化）：

cd apps/api
pnpm prisma studio
# 访问 http://localhost:5555

Redis Commander（Redis 可视化）：

docker run --rm -it -p 8081:8081 --network refly_network \
  rediscommander/redis-commander \
  --redis-host refly_redis --redis-port 6379
# 访问 http://localhost:8081

MinIO Console（对象存储管理）：

直接访问 http://localhost:39001，使用 minioadmin/minioadmin 登录。

4. 进阶拓展方向

技术博客与专家观点

推荐关注的技术博客：

Refly 官方博客：搜索 "Refly Blog"（如果有）
LangChain 官方博客：搜索 "LangChain Blog" - 了解 LLM 应用最佳实践
Prisma 博客：搜索 "Prisma Blog" - 数据库设计和 ORM 优化
Vercel 博客：搜索 "Vercel Blog" - 前端性能和部署优化

核心维护者（如果公开）：

查看 CONTRIBUTING.md 中的团队成员列表
在 GitHub Commit 历史中找到活跃贡献者

社区与论坛

官方社区：

Discord：搜索 "Refly Discord" - 实时聊天，快速获取帮助
GitHub Discussions：https://github.com/refly-ai/refly/discussions - 长期讨论，提问和分享
Twitter/X：搜索 "@reflyai" - 关注产品动态

相关技术社区：

LangChain Discord：搜索 "LangChain Discord" - LLM 开发问题
NestJS Discord：搜索 "NestJS Discord" - 后端架构问题
React Subreddit：Reddit r/reactjs - React 生态讨论
Stack Overflow：使用标签 langchain, nestjs, prisma, react 提问

各平台特点：

平台	适用场景	响应速度
Discord	实时提问、快速讨论	< 1 小时
GitHub Discussions	深度讨论、功能建议	1-3 天
Stack Overflow	技术问题、可被搜索到	几小时到几天
Twitter	关注动态、分享成果	不定

总结与下一步行动 🎯

恭喜你读到这里！😊 这份指南涵盖了从环境搭建到架构理解的完整路径。

下一步，你应该：

✅ 立即行动：按照"一键启动指南"运行项目（今天就开始！）
📚 制定计划：根据四阶段学习计划，设定每周目标
🤝 加入社区：在 Discord 上介绍自己，认识其他学习者
💪 完成练习：从初级练习开始，逐步挑战高级任务
🚀 贡献代码：找到一个 good first issue，迈出第一步

记住：

学习复杂系统就像爬山，刚开始会很陡峭，但每登上一个台阶，你都会看到更美的风景。遇到困难时，回到这份指南，查阅相关章节，或者去社区寻求帮助。我们都是从新手走过来的，你不是一个人在战斗！💪

祝你在 Refly 的学习之旅中收获满满！🎉

附录：快速参考卡片

常用命令速查

# 启动中间件
docker compose -f deploy/docker/docker-compose.middleware.yml -p refly up -d

# 安装依赖
pnpm install

# 配置环境
pnpm copy-env:develop

# 构建项目
pnpm build

# 启动开发服务器
pnpm dev

# 代码检查和格式化
pnpm check:fix

# 运行测试
pnpm test

# Prisma 操作
cd apps/api
pnpm prisma studio        # 可视化数据库
pnpm prisma generate      # 生成 Client
pnpm prisma migrate dev   # 执行迁移

重要端口速查

服务	端口	用途
Web 前端	5173	React 开发服务器
API 后端	3000	NestJS HTTP 服务
WebSocket	3001	实时通信
PostgreSQL	35432	主数据库
Redis	36379	缓存和队列
Redis UI	38001	Redis Stack 管理界面
Qdrant	36333	向量数据库
MinIO	39000	对象存储 API
MinIO Console	39001	对象存储管理界面
SearxNG	38080	元搜索引擎

目录快速导航

# 后端核心模块
apps/api/src/modules/workflow/      # 工作流引擎
apps/api/src/modules/rag/           # RAG 检索
apps/api/src/modules/skill/         # AI 技能
apps/api/src/modules/copilot/       # Copilot

# 前端核心页面
apps/web/src/pages/workspace/       # 工作空间
packages/ai-workspace-common/       # AI 组件库

# 共享核心包
packages/canvas-common/             # Canvas 逻辑
packages/skill-template/            # 技能模板
packages/providers/                 # LLM 提供商

反馈渠道： 如有任何问题或建议，请在 GitHub Issues 中提出！

Refly.AI （AI工作流）架构学习指南

Refly.AI 架构学习指南

第一部分：项目架构深度解析（像架构师一样俯瞰全景）🔍

1. 项目架构概览

用一个类比来理解 Refly 💡

核心设计特征

同类项目参考

技术栈分析

外部系统集成

架构流程描述

2. 目录结构与核心流程

目录组织逻辑

关键文件定位

模块依赖关系

典型业务流程：用户创建并执行工作流

3. 代码结构观察

代码组织模式

设计模式识别

代码质量观察

潜在改进点（学习机会）

第二部分：技能需求清单（你的学习弹药库）📚

1. 基础技能要求

编程语言和框架

基础工具和概念

2. 进阶技能要求

架构模式和设计原则

领域特定知识

3. 技能掌握程度建议

对于初学者（0-1年经验）

对于有经验的开发者（1-3年）

对于意欲贡献代码的进阶者（3年+）

第三部分：学习路径规划（你的专属教练计划）🎯

1. 项目运行入口定位（快速上手）

一键启动指南 ⚡

环境配置清单

2. 循序渐进学习计划（四阶段法）

阶段一：环境搭建和项目启动（1-2 天）💪

阶段二：核心流程理解（3-5 天）🔍

阶段三：模块深入和定制开发（1-2 周）🛠️

阶段四：架构理解和贡献指南（2 周+）🚀

3. 学习路径流程图

第四部分：实践建议和进阶指导（从会用到精通）💡

1. 调试技巧和常见陷阱

后端调试技巧

前端调试技巧

新人常见的 5 个陷阱

2. 扩展练习建议

🌟 初级练习（1-3 小时完成）

🌟🌟 中级练习（3-8 小时完成）

🌟🌟🌟 高级练习（8+ 小时完成）

3. 参与贡献的途径

寻找适合新人的 Issue

代码规范要求

提交流程

获得帮助的渠道

第五部分：技术栈学习指引（你的知识地图）🌐

1. 官方文档定位（学习的基石）

核心技术栈文档

项目自身文档

权威技术书籍

2. 学习路径建议（社区智慧）

技能学习顺序

核心概念优先级

实践项目推荐

3. 工具与环境配置指南

开发环境搭建

常用工具使用

4. 进阶拓展方向

技术博客与专家观点

相关技术大会

社区与论坛

总结与下一步行动 🎯

附录：快速参考卡片

常用命令速查

重要端口速查

目录快速导航

通义大模型

热门文章

最新文章

相关电子书