# https://github.com/refly-ai/refly 项目说明书 生成时间：2026-05-13 11:54:39 UTC ## 目录 - [Refly 项目介绍](#page-introduction) - [技术栈概览](#page-tech-stack) - [系统整体架构](#page-system-architecture) - [API 模块总览](#page-module-overview) - [工作流系统](#page-workflow-system) - [工具系统](#page-tool-system) - [认证与授权系统](#page-auth-system) - [Canvas 画布组件](#page-canvas-components) - [富文本编辑器系统](#page-editor-system) - [模型提供者系统](#page-provider-system) ## Refly 项目介绍 ### 相关页面 相关主题：[技术栈概览](#page-tech-stack), [系统整体架构](#page-system-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/refly-ai/refly/blob/main/README.md) - [packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md) - [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) - [packages/ai-workspace-common/src/components/canvas/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/index.tsx) - [packages/ai-workspace-common/src/components/pure-copilot/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/pure-copilot/index.tsx) - [packages/stores/src/stores/canvas.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/canvas.ts) - [packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx) - [packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx) - [apps/api/src/modules/voucher/voucher-email-templates.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/voucher/voucher-email-templates.ts)
# Refly 项目介绍 ## 1. 项目概述 Refly 是一个基于 AI 的可视化工作流构建平台，旨在帮助用户通过直观的拖拽式画布界面创建和编排 AI 工作流。该项目采用 Monorepo 架构，包含了前端画布组件、AI Copilot 智能助手、命令行工具、API 服务等多个子包和应用。 Refly 的核心价值在于降低 AI 工作流构建的门槛，让用户无需编写代码即可组合各种 AI 能力，创建复杂的自动化任务流程。 ## 2. 项目架构 ### 2.1 Monorepo 结构概览 ``` refly/ ├── apps/ │ ├── api/ # 后端 API 服务 │ │ └── src/modules/ │ │ ├── workflow-app/ # 工作流相关模块 │ │ └── voucher/ # 优惠券/凭证系统 │ └── web/ # Web 应用 ├── packages/ │ ├── ai-workspace-common/ # AI 工作空间通用组件 │ │ └── src/components/ │ │ ├── canvas/ # 画布核心组件 │ │ │ ├── nodes/ # 节点类型（代码工件、技能响应等） │ │ │ ├── webhook/ # Webhook 配置 │ │ │ └── top-toolbar/ # 顶部工具栏 │ │ ├── pure-copilot/ # 纯 AI 助手组件 │ │ ├── markdown/ # Markdown 渲染 │ │ ├── slideshow/ # 幻灯片展示 │ │ └── resource-view/ # 资源视图 │ ├── stores/ # 状态管理 (Zustand) │ │ └── src/stores/ │ │ ├── canvas.ts # 画布状态 │ │ └── import-resource.ts │ ├── web-core/ # Web 核心功能 │ ├── layout/ # 页面布局组件 │ └── cli/ # 命令行工具 ``` ### 2.2 技术栈 | 层级 | 技术选型 | 说明 | |------|----------|------| | 前端框架 | React + TypeScript | 主要开发语言 | | UI 组件库 | Ant Design | 基础 UI 组件 | | 样式方案 | Tailwind CSS | 原子化 CSS | | 状态管理 | Zustand | 轻量级状态管理 | | 画布引擎 | React Flow | 可视化流程图库 | | 国际化 | i18next | 多语言支持 | | 后端 | Node.js | API 服务 | | CLI | TypeScript | 命令行工具 | ## 3. 核心功能模块 ### 3.1 Canvas 画布系统 Canvas 是 Refly 的核心功能模块，提供可视化的 AI 工作流编辑界面。 #### 3.1.1 画布交互配置 ```typescript ``` #### 3.1.2 画布状态管理 Canvas 状态通过 Zustand store 统一管理： ```typescript // packages/stores/src/stores/canvas.ts const defaultCanvasState = () => ({ config: {}, currentCanvasId: null, initialFitViewCompleted: false, operatingNodeId: null, showEdges: true, nodeSizeMode: 'compact' as const, showTemplates: true, showSlideshow: false, linearThreadMessages: [], tplConfig: null, canvasPage: {}, contextMenuOpenedCanvasId: null, canvasTitle: {}, canvasInitialized: {}, canvasInitializedAt: {}, canvasExecutionId: {}, canvasNodeExecutions: {}, canvasVariables: {}, }); ``` ### 3.2 节点类型系统 Refly 画布支持多种类型的节点，用于构建不同功能的 AI 工作流。 #### 3.2.1 CodeArtifactNode 代码工件节点 用于展示和编辑代码生成结果： ```typescript // packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx {}} showActions={false} /> ``` #### 3.2.2 ActionStep 技能执行步骤 展示 AI 技能执行过程中的日志和状态： ```typescript // packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx items={logs.map((log) => ({ title: t(`${log.key}.title`, { ...log.titleArgs, ns: 'skillLog' }), description: t(`${log.key}.description`, { ...log.descriptionArgs, ns: 'skillLog' }), status: log.status === 'error' ? 'error' : 'finish', }))} ``` ### 3.3 Pure Copilot 智能助手 Pure Copilot 是 Refly 内置的 AI 助手组件，支持自然语言交互和文件处理。 #### 3.3.1 组件功能 - **文件拖拽上传**：支持拖拽文件到输入区域 - **上下文管理**：管理已上传的文件列表 - **消息发送**：支持 @ 提及特定工具集 - **多语言国际化**：内置中文和英文提示文本 ```typescript // packages/ai-workspace-common/src/components/pure-copilot/index.tsx const { query, setQuery, setContextItems, setSelectedToolsets } = useAgentNodeManagement(nodeId); const { connectToUpstreamAgent } = useAgentConnections(); const { data: workflowVariables } = useVariablesManagement(canvasId); ``` ### 3.4 Webhook 集成 Refly 支持 Webhook 配置，允许用户将工作流与其他系统集成。 #### 3.4.1 Webhook 配置界面 ```typescript // packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx
{t('webhook.instructions')}
  • {t('webhook.instruction1')}
  • {t('webhook.instruction2')}
  • {t('webhook.instruction3')}
``` ### 3.5 模板市场与优惠券系统 Refly 包含完整的创作者激励机制，包括模板市场和折扣券系统。 #### 3.5.1 多语言邮件模板 ```typescript // apps/api/src/modules/voucher/voucher-email-templates.ts export function generateVoucherEmail( data: VoucherEmailData, locale?: string, ): { subject: string; html: string } { // 检查语言环境是否为中文 const isChineseLocale = locale?.toLowerCase().startsWith('zh'); if (isChineseLocale) { return generateVoucherEmailZH(data); } return generateVoucherEmailEN(data); } ``` #### 3.5.2 邮件内容结构 | 区域 | 中文内容 | 英文内容 | |------|----------|----------| | 标题 | 恭喜获得专属折扣！ | Congratulations on Your Exclusive Discount! | | 称呼 | ${userName}，您好！ | Hello ${userName}! | | 描述 | 感谢您在 Refly.ai 上发布模板！为表感谢，这是专属于您的折扣奖励。 | Thank you for publishing a template on Refly.ai! As a token of appreciation, here's your exclusive discount reward. | | 底部 | Refly.ai 团队 | Refly.ai Team | ### 3.6 调度系统 (Schedule) Refly 支持工作流的定时调度功能，包含完整的调度限制和模态框交互。 #### 3.6.1 调度限制模态框 ```typescript // packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx setScheduleLimitModalVisible(false)}> {t('common.cancel') || 'Cancel'} , , ]} >

{t('schedule.limitReached.message') || "You've reached the maximum number of scheduled workflows for your plan."}

``` ### 3.7 资源导入系统 支持从多种来源导入资源到工作流中。 ```typescript // packages/stores/src/stores/import-resource.ts interface ImportResourceState { importResourceModalVisible: boolean; extensionModalVisible: boolean; scrapeLinks: LinkMeta[]; copiedTextPayload: { content: string; title: string; url?: string }; fileList: FileItem[]; imageList: ImageItem[]; selectedMenuItem: ImportResourceMenuItem; insertNodePosition: XYPosition; } ``` ## 4. 布局系统 Refly 提供统一的页面布局组件，简化应用开发。 ### 4.1 PrimaryPageLayout 适用于主要功能页面： ```typescript // packages/layout/README.md function DetailPage() { return ( {({ context, onContextChange }) => ( <> Action Button} extra={
Extra Content
} deps={[]} />
Page Content
)} ); } ``` ### 4.2 SecondaryPageLayout 适用于详情页面或子功能页面： ```typescript function DetailPage() { return ( {({ context, onContextChange }) => ( <> history.back()} actions={} deps={[]} />
Detail Page Content
)} ); } ``` ## 5. CLI 命令行工具 Refly 提供命令行工具，支持终端操作和工作流管理。 ### 5.1 主要命令 | 命令 | 功能 | 说明 | |------|------|------| | `refly login` | 用户登录 | 使用 API Key 认证 | | `refly builder start` | 启动构建器 | 创建新的工作流 | | `refly builder validate` | 验证工作流 | 检查 DAG 配置 | | `refly builder commit` | 提交工作流 | 保存工作流配置 | ### 5.2 配置文件 CLI 配置存储在 `~/.refly/config.json`： ```json { "version": 1, "auth": { "apiKey": "...", "expiresAt": "..." }, "api": { "endpoint": "https://api.refly.ai" } } ``` ### 5.3 Claude Code 集成 CLI 支持与 Claude Code 集成，安装技能文件到： - `~/.claude/skills/refly/SKILL.md` - `~/.claude/skills/refly/references/` - `~/.claude/commands/refly-*.md` ### 5.4 错误码 | 错误码 | 描述 | 解决方案 | |--------|------|----------| | AUTH_REQUIRED | 未认证 | 执行 `refly login` | | BUILDER_NOT_STARTED | 构建器未启动 | 执行 `refly builder start` | | VALIDATION_REQUIRED | 需要验证 | 执行 `refly builder validate` | | VALIDATION_ERROR | DAG 验证失败 | 检查错误详情 | | DUPLICATE_NODE_ID | 节点 ID 重复 | 使用唯一 ID | | CYCLE_DETECTED | 检测到循环依赖 | 移除循环 | | WORKFLOW_NOT_FOUND | 工作流不存在 | 检查工作流 ID | ## 6. 国际化 Refly 支持多语言（i18n），使用 i18next 框架实现。 ### 6.1 语言检测 系统自动检测用户语言环境： ```typescript // 检查是否为中文环境 const isChineseLocale = locale?.toLowerCase().startsWith('zh'); ``` ### 6.2 支持的语言 | 语言代码 | 说明 | |----------|------| | `zh` / `zh-CN` / `zh-Hans` | 简体中文 | | `zh-TW` / `zh-Hant` | 繁体中文 | | `en` | 英文 | ## 7. 工作流执行流程 ```mermaid graph TD A[开始] --> B[创建 Canvas] B --> C[添加节点] C --> D[配置节点属性] D --> E[连接节点边] E --> F[保存工作流] F --> G[执行工作流] G --> H{执行状态} H -->|执行中| I[显示 Skill 日志] H -->|成功| J[生成 Artifacts] H -->|失败| K[显示错误信息] I --> J J --> L[完成] K --> M[可重试] M --> G ``` ## 8. 总结 Refly 是一个功能完整的 AI 工作流可视化构建平台，其特点包括： 1. **模块化架构**：清晰的 Monorepo 结构，便于维护和扩展 2. **可视化编辑**：基于 React Flow 的拖拽式画布 3. **丰富的节点类型**：支持代码生成、技能执行、变量管理等多种节点 4. **完善的生态**：包含 CLI 工具、API 服务、Webhook 集成等 5. **国际化支持**：内置中英文等多语言支持 6. **创作者激励**：完整的模板市场和优惠券系统 --- ## 技术栈概览 ### 相关页面 相关主题：[Refly 项目介绍](#page-introduction), [系统整体架构](#page-system-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [apps/api/package.json](https://github.com/refly-ai/refly/blob/main/apps/api/package.json) - [apps/web/package.json](https://github.com/refly-ai/refly/blob/main/apps/web/package.json) - [packages/tsconfig/base.json](https://github.com/refly-ai/refly/blob/main/packages/tsconfig/base.json) - [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) - [packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx) - [packages/skill-template/src/scheduler/utils/context.ts](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts) - [packages/stores/src/stores/import-resource.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts)
# 技术栈概览 Refly 是一个模块化的 AI 工作流构建平台，采用 Monorepo 架构组织代码库。本文档详细介绍 Refly 项目使用的核心技术栈、依赖关系以及架构设计。 ## 核心架构概述 Refly 采用 pnpm workspace 管理的 Monorepo 结构，主要分为以下几类包： | 包类型 | 说明 | |--------|------| | `apps/*` | 可独立部署的应用程序 | | `packages/*` | 供多个应用共享的公共包 | | `packages/skill-template/*` | 技能模板包 | ### Monorepo 结构 ```mermaid graph TD A[refly root] --> B[apps/api] A --> C[apps/web] A --> D[packages/ai-workspace-common] A --> E[packages/web-core] A --> F[packages/cli] A --> G[packages/skill-template] A --> H[packages/stores] A --> I[packages/tsconfig] D --> H E --> H E --> D ``` 资料来源：[packages/tsconfig/base.json:1-20]() ## 前端技术栈 ### React 与 TypeScript Refly 的前端应用基于 React 18+ 和 TypeScript 构建。TypeScript 配置通过 `packages/tsconfig/base.json` 提供基础配置，所有子包继承该配置以保持类型检查的一致性。 **基础 TypeScript 配置特性：** - 严格模式启用 - ES2020+ 目标平台 - React JSX 支持 - 路径别名配置（`@/*`） 资料来源：[packages/tsconfig/base.json:1-30]() ### 状态管理 Refly 使用 Zustand 作为轻量级状态管理解决方案。状态存储位于 `packages/stores` 包中，定义了多个独立的状态切片： ```typescript // 状态管理示例结构 interface ImportResourceState { importResourceModalVisible: boolean; extensionModalVisible: boolean; scrapeLinks: LinkMeta[]; copiedTextPayload: { content: string; title: string; url?: string }; waitingList: WaitingListItem[]; } ``` 资料来源：[packages/stores/src/stores/import-resource.ts:1-50]() ### UI 组件库 #### Ant Design 项目大量使用 Ant Design 作为基础 UI 组件库，提供的组件包括： - `Modal` - 模态对话框 - `Button` - 按钮组件 - `Spin` - 加载状态 - `Divider` - 分隔线 ```typescript // Ant Design 组件使用示例 ``` 资料来源：[packages/web-core/src/pages/page-share/index.tsx:50-70]() #### Tailwind CSS 自定义样式使用 Tailwind CSS 配合 CSS 变量系统实现主题化： ```typescript // CSS 变量使用示例 className="text-refly-text-0 border-[var(--integration-docs-border)] bg-[var(--integration-docs-bg-subtle)]" ``` 资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx:30-45]() ### 国际化 (i18n) Refly 使用 `react-i18next` 实现多语言支持，所有用户界面文本通过翻译键引用： ```typescript // 国际化使用示例 const { t, i18n } = useTranslation(); // 翻译键使用 t('integration.api.errorCode') t('webhook.instruction1') ``` 资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx:10-25]() ## Canvas 工作流系统 ### 节点预览与渲染 Canvas 是 Refly 的核心可视化编辑器，用于构建 AI 工作流。关键组件位于 `packages/ai-workspace-common/src/components/canvas/` 目录下。 ```mermaid graph LR A[Canvas 编辑器] --> B[Node Preview] A --> C[Integration Docs] A --> D[Webhook Config] B --> E[Artifact Renderer] B --> F[Skill Response] ``` ### Artifact 渲染系统 ArtifactRenderer 组件负责渲染代码片段和文档内容，支持多种渲染模式： | 属性 | 说明 | |------|------| | `purePreview` | 纯预览模式 | | `readonly` | 只读模式 | | `isFullscreen` | 全屏模式 | | `isMinimap` | 缩略图模式 | 资料来源：[packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:20-60]() ## 技能系统 (Skill Template) ### 上下文与工具调用 技能模板包 `packages/skill-template` 提供了 AI 代理执行任务的框架。核心类型定义如下： ```typescript // 上下文文件接口 export interface ContextFile { name: string; fileId: string; type: string; summary: string; content: string; variableId?: string; variableName?: string; } // 代理结果接口 export interface AgentResult { resultId: string; title: string; content: string; outputFiles: ContextFileMeta[]; } ``` 资料来源：[packages/skill-template/src/scheduler/utils/context.ts:1-50]() ### 工具调用元数据 ```typescript // 工具调用元数据接口 export interface ToolCallMeta { callId: string; // 用于通过 read_tool_result 检索 toolName: string; // 被调用的工具名称 } ``` ## CLI 工具 Refly CLI 工具位于 `packages/cli` 目录，提供命令行界面与 Refly 平台交互。 ### 主要命令 | 命令 | 功能 | |------|------| | `refly login` | 用户身份验证 | | `refly builder start` | 启动构建器会话 | | `refly builder validate` | 验证 DAG 配置 | | `refly init` | 初始化 Claude Code 集成 | ### 配置文件 CLI 配置存储在 `~/.refly/config.json`： ```json { "version": 1, "auth": { "apiKey": "...", "expiresAt": "..." }, "api": { "endpoint": "https://api.refly.ai" } } ``` ### 环境变量 | 变量名 | 说明 | |--------|------| | `REFLY_API_KEY` | API 认证密钥 | | `REFLY_API_ENDPOINT` | API 端点覆盖 | 资料来源：[packages/cli/README.md:40-70]() ## API 集成 ### Webhook 端点 Webhook 系统允许外部系统接收 Refly 工作流事件。请求体包含以下字段： | 字段名 | 类型 | 必填 | 说明 | |--------|------|------|------| | event | string | 是 | 事件类型 | | data | object | 是 | 事件数据 | | timestamp | number | 是 | 时间戳 | ### API 错误码 | 错误码 | HTTP 状态 | 说明 | 解决建议 | |--------|-----------|------|----------| | AUTH_REQUIRED | 401 | 未认证 | `refly login` | | BUILDER_NOT_STARTED | 400 | 无活动构建会话 | `refly builder start` | | VALIDATION_REQUIRED | 400 | 提交前需验证 | `refly builder validate` | | DUPLICATE_NODE_ID | 409 | 节点 ID 重复 | 使用唯一 ID | | CYCLE_DETECTED | 400 | 检测到循环依赖 | 移除循环 | 资料来源：[packages/cli/README.md:80-95]() ## 资源管理 ### 导入资源模块 资源导入功能使用专门的状态管理： ```typescript // 等待队列项接口 interface WaitingListItem { id: string; url?: string; title?: string; file?: { type: 'image' | 'file'; status: 'uploading'; url?: string; title?: string; }; } ``` 资料来源：[packages/stores/src/stores/import-resource.ts:30-60]() ### 资源视图组件 资源元数据显示包括标题、URL 和创建时间： ```typescript // 资源元数据渲染 {resourceDetail?.data?.url && ( {resourceDetail?.data?.url} )} ``` 资料来源：[packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx:20-40]() ## 构建与部署 ### pnpm Workspace 项目使用 pnpm 管理依赖和 workspaces： ```yaml # pnpm-workspace.yaml packages: - 'apps/*' - 'packages/*' ``` ### Turborepo 使用 Turborepo 进行任务调度和构建缓存，提高增量构建效率。 ## 技术栈总结 | 层级 | 技术选型 | 版本要求 | |------|----------|----------| | 语言 | TypeScript | 5.0+ | | UI 框架 | React | 18.0+ | | 状态管理 | Zustand | latest | | 组件库 | Ant Design | 5.x | | 样式方案 | Tailwind CSS | 3.x | | 国际化 | react-i18next | latest | | 包管理 | pnpm | 8.0+ | | 构建工具 | Turborepo | latest | | 代码规范 | ESLint + Prettier | latest | Refly 的技术栈设计体现了现代化前端开发的最佳实践，通过 Monorepo 架构实现了代码共享和独立部署的平衡，Zustand 提供了轻量且高效的状态管理，而模块化的组件设计则确保了系统的可维护性和可扩展性。 --- ## 系统整体架构 ### 相关页面 相关主题：[API 模块总览](#page-module-overview), [工作流系统](#page-workflow-system)
相关源码文件 以下源码文件用于生成本页说明： - [packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md) - [packages/skill-template/src/scheduler/utils/context.ts](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts) - [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) - [packages/stores/src/stores/import-resource.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts) - [packages/web-core/src/components/layout/ModalContainer.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/components/layout/ModalContainer.tsx) - [packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx) - [packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx)
# 系统整体架构 ## 1. 架构概述 Refly 是一个模块化的 AI 工作空间平台，采用 Monorepo 架构组织代码。系统由多个独立但相互协作的包（packages）组成，通过 pnpm workspace 和 Turbo 构建系统进行统一管理。 ### 1.1 核心设计原则 - **模块化设计**：每个功能模块独立封装，通过明确定义的接口进行通信 - **状态管理集中化**：使用 Zustand store 统一管理全局状态 - **组件懒加载**：Modal 等大型组件采用动态导入（Lazy Loading）优化性能 - **多语言支持**：内置 i18n 国际化方案，支持中英文切换 ## 2. Monorepo 结构 项目采用 pnpm workspace 管理多包结构，核心配置通过 turbo.json 定义构建管道。 ```yaml # pnpm-workspace.yaml 结构 packages: - 'apps/*' # 应用程序层 - 'packages/*' # 共享包层 ``` ### 2.1 应用层（apps） | 应用 | 描述 | 技术栈 | |------|------|--------| | api | 后端 API 服务 | Node.js/TypeScript | | web | 前端 Web 应用 | React/TypeScript | ### 2.2 共享包层（packages） | 包名 | 描述 | |------|------| | layout | 布局组件库 | | skill-template | Skill 模板引擎 | | ai-workspace-common | AI 工作空间通用组件 | | web-core | Web 核心组件 | | stores | 状态管理库 | | cli | 命令行工具 | ## 3. 前端架构 ### 3.1 页面布局系统 Refly 的前端采用分层布局架构，支持多种页面类型： ```tsx // 布局组件使用示例 {({ context, onContextChange }) => ( 操作按钮} extra={
额外内容
} deps={[]} /> )} ``` **布局类型说明：** | 布局组件 | 适用场景 | 核心配置项 | |----------|----------|-----------| | PrimaryPageLayout | 主页面 | title, actions, extra, fixHeight, noPaddingY, noPaddingX | | SecondaryPageLayout | 详情页/子功能页 | title, desc, extra, actions, onBack | 资料来源：[packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md) ### 3.2 组件组织结构 前端组件按功能域划分为多个目录： ``` packages/ai-workspace-common/src/components/ ├── canvas/ # Canvas 相关组件 │ ├── nodes/ # 节点组件 │ ├── launchpad/ # 启动面板 │ ├── webhook/ # Webhook 配置 │ └── integration-docs/ # 集成文档 ├── slideshow/ # 幻灯片组件 ├── pure-copilot/ # Copilot 组件 └── resource-view/ # 资源视图 ``` ### 3.3 Modal 容器架构 Modal 容器采用统一管理 + 懒加载模式，所有 Modal 通过 ModalContainer 集中注册： ```tsx import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({ default: m.ImportResourceModal, })) } /> ``` **已集成的 Modal 组件：** | Modal 名称 | 功能 | 懒加载路径 | |------------|------|-----------| | ImportResourceModal | 导入资源 | import-resource | | CanvasRenameModal | 重命名画布 | canvas-rename | | CanvasDeleteModal | 删除画布 | canvas-delete | | DuplicateCanvasModal | 复制画布 | duplicate-canvas-modal | | ClaimedVoucherPopup | 优惠券领取 | voucher | | EarnedVoucherPopup | 获得优惠券 | voucher | 资料来源：[packages/web-core/src/components/layout/ModalContainer.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/components/layout/ModalContainer.tsx) ## 4. 状态管理 ### 4.1 Store 架构 系统使用 Zustand 进行状态管理，主要 store 位于 `packages/stores/src/stores/` 目录。 **ImportResource Store 结构：** ```typescript interface ImportResourceState { // UI 状态 importResourceModalVisible: boolean; extensionModalVisible: boolean; // 资源数据 scrapeLinks: LinkMeta[]; copiedTextPayload: { content: string; title: string; url?: string }; fileList: FileItem[]; imageList: ImageItem[]; // 等待列表 waitingList: WaitingListItem[]; // 工具集选择 selectedToolsets: Toolset[]; selectedMenuItem: ImportResourceMenuItem; insertNodePosition: XYPosition; } ``` **核心 Actions：** | Action | 功能 | |--------|------| | setImportResourceModalVisible | 控制导入资源弹窗显隐 | | setExtensionModalVisible | 控制扩展弹窗显隐 | | addToWaitingList | 添加等待项 | | removeFromWaitingList | 移除等待项 | | setSelectedMenuItem | 设置选中的菜单项 | | setInsertNodePosition | 设置插入节点位置 | 资料来源：[packages/stores/src/stores/import-resource.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts) ## 5. 技能（Skill）系统 ### 5.1 上下文模型 Skill 系统使用上下文文件（ContextFile）表示输入输出资源： ```typescript export interface ContextFile { name: string; // 文件名 fileId: string; // 文件 ID type: string; // 文件类型 summary: string; // 文件摘要 content: string; // 文件内容 variableId?: string; // 变量 ID variableName?: string; // 变量名 } // 元数据版本（减少 token 使用） export interface ContextFileMeta { name: string; fileId: string; type: string; summary: string; variableId?: string; variableName?: string; } ``` ### 5.2 工具调用元数据 ```typescript export interface ToolCallMeta { callId: string; // 工具调用 ID，用于读取结果 toolName: string; // 被调用的工具名称 } ``` ### 5.3 Skill 安装与卸载 Skill 通过命令行工具管理： ```bash # 安装 Skill refly skill install # 卸载 Skill refly skill uninstall ``` Skill 文件安装位置： - `~/.claude/skills/refly/SKILL.md` - `~/.claude/skills/refly/references/` - `~/.claude/commands/refly-*.md` 资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) ## 6. Webhook 集成 ### 6.1 Webhook 配置界面 ```tsx ``` ### 6.2 Webhook 错误码 | 错误码 | HTTP 状态 | 描述 | |--------|-----------|------| | AUTH_REQUIRED | 401 | 未认证 | | BUILDER_NOT_STARTED | 400 | 构建器未启动 | | VALIDATION_REQUIRED | 400 | 必须先验证 | | VALIDATION_ERROR | 400 | DAG 验证失败 | | DUPLICATE_NODE_ID | 400 | 节点 ID 重复 | | CYCLE_DETECTED | 400 | 检测到循环依赖 | | WORKFLOW_NOT_FOUND | 404 | 工作流不存在 | 资料来源：[packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx) ## 7. Canvas 架构 ### 7.1 节点预览组件 Canvas 中的节点预览支持 Skill 响应展示： ```tsx ``` ### 7.2 Artifact 渲染器 ```tsx ``` **渲染状态：** | 状态 | 描述 | |------|------| | generating | 生成中 | | finish | 完成 | | failed | 失败 | | executing | 执行中 | ## 8. Copilot 集成 Pure Copilot 是系统的主要交互入口，支持文件拖拽和上下文管理： ```tsx ``` **数据交互流程：** 1. 用户输入查询 → ChatInput 组件 2. 文件拖拽 → FileList 组件处理上传 3. Mention 插入 → 工具/资源/代理选择 4. 上下文构建 → ContextItem 添加 ## 9. 配置管理 ### 9.1 CLI 配置 配置文件位置：`~/.refly/config.json` ```json { "version": 1, "auth": { "apiKey": "...", "expiresAt": "..." }, "api": { "endpoint": "https://api.refly.ai" } } ``` ### 9.2 环境变量 | 变量名 | 描述 | |--------|------| | REFLY_API_KEY | API 认证密钥 | | REFLY_API_ENDPOINT | API 端点地址（覆盖默认配置） | ## 10. 国际化 系统支持多语言切换，语言代码通过 i18n 库管理： ```typescript const language = i18n.languages?.[0]; // 'en' | 'zh' ``` 翻译资源使用命名空间（namespace）组织： - `common`: 通用文本 - `skillLog`: 技能日志 - `schedule`: 调度相关 - `integration`: 集成文档 ## 11. 架构流程图 ### 11.1 组件加载流程 ```mermaid graph TD A[用户操作触发 Modal] --> B{检查 visible 状态} B -->|true| C[懒加载组件] C --> D[渲染 Modal] B -->|false| E[不渲染] F[应用启动] --> G[初始化 Zustand Stores] G --> H[注册 Modal 容器] H --> I[按需加载页面组件] ``` ### 11.2 Skill 执行流程 ```mermaid graph TD A[用户发送消息] --> B[ChatInput 处理] B --> C[构建上下文] C --> D[Skill 引擎处理] D --> E[生成 ActionStep] E --> F[渲染结果] G[工具调用] --> H[ToolCallMeta 记录] H --> I[read_tool_result 获取结果] I --> F ``` ### 11.3 资源导入流程 ```mermaid graph TD A[打开导入弹窗] --> B[选择资源类型] B --> C{资源类型} C -->|文件| D[FileList 处理] C -->|工具集| E[Toolset 选中] C -->|代理| F[UpstreamAgent 添加] D --> G[ContextItem 创建] E --> H[SelectedToolsets 更新] F --> I[addToUpstreamAgents] G --> J[等待列表管理] H --> J I --> J ``` ## 12. 总结 Refly 系统采用现代化的前端架构设计： - **Monorepo 组织**：通过 pnpm workspace 和 Turbo 实现高效的包管理 - **分层布局**：统一的布局系统支持多种页面类型 - **集中状态**：Zustand store 管理全局状态 - **懒加载优化**：Modal 和大型组件按需加载 - **Skill 生态**：可扩展的技能系统支持自定义工作流 - **多语言支持**：内置 i18n 国际化能力 --- ## API 模块总览 ### 相关页面 相关主题：[系统整体架构](#page-system-architecture), [工作流系统](#page-workflow-system), [工具系统](#page-tool-system)
相关源码文件 以下源码文件用于生成本页说明： - [apps/api/src/modules](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules) - [apps/api/prisma/schema.prisma](https://github.com/refly-ai/refly/blob/main/apps/api/prisma/schema.prisma) - [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) - [packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx) - [packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx) - [packages/stores/src/stores/import-resource.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts) - [packages/skill-template/src/scheduler/utils/context.ts](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts)
# API 模块总览 ## 1. 模块概述 Refly 的 API 模块是整个平台的核心后端服务，负责处理工作流执行、数据存储、外部集成等关键功能。该模块位于 `apps/api/src/modules` 目录下，采用模块化架构设计，支持 Webhook 事件推送、Skill 执行、调度任务等核心能力。 API 模块通过 RESTful 接口与前端应用（Web Core、AI Workspace Common）进行通信，同时支持 CLI 工具进行本地开发和自动化操作。 ## 2. 核心架构 ### 2.1 模块目录结构 ``` apps/api/ ├── src/ │ ├── modules/ # 业务功能模块 │ │ ├── voucher/ # 凭证与奖励模块 │ │ └── ... # 其他业务模块 │ └── ... ├── prisma/ │ └── schema.prisma # 数据库 schema 定义 └── ... ``` ### 2.2 架构关系图 ```mermaid graph TD A[CLI 客户端] -->|HTTP/HTTPS| B[API Gateway] C[Web 前端] -->|HTTP/HTTPS| B D[Webhook 回调] -->|POST| B B --> E[认证模块] B --> F[工作流模块] B --> G[Webhook 模块] B --> H[调度模块] E --> I[(Prisma DB)] F --> I G --> I H --> I G -->|事件推送| J[外部服务] H -->|定时触发| F ``` ## 3. 数据模型 ### 3.1 数据库 Schema API 模块使用 Prisma ORM 进行数据库操作，数据模型定义在 `apps/api/prisma/schema.prisma` 中。主要实体包括： | 实体名称 | 说明 | 关联关系 | |---------|------|---------| | User | 用户账户信息 | 1:N WorkFlow, 1:N Webhook | | WorkFlow | 工作流定义 | N:1 User, 1:N Node | | Node | 工作流节点 | N:1 WorkFlow | | Webhook | Webhook 配置 | N:1 User | | Schedule | 调度任务 | N:1 User, N:1 WorkFlow | ### 3.2 Context 文件结构 在 Skill 执行和调度上下文中，系统使用 `ContextFile` 结构管理文件资源： ```typescript // 资料来源：packages/skill-template/src/scheduler/utils/context.ts:9-17 export interface ContextFile { name: string; // 文件名称 fileId: string; // 文件唯一标识 type: string; // 文件类型 summary: string; // 文件摘要 content: string; // 文件内容 variableId?: string; variableName?: string; } ``` ### 3.3 元数据精简版本 为减少 Token 消耗，系统提供 `ContextFileMeta` 元数据版本，LLM 可通过 `read_file` 工具获取完整内容： ```typescript // 资料来源：packages/skill-template/src/scheduler/utils/context.ts:20-26 export interface ContextFileMeta { name: string; fileId: string; type: string; summary: string; variableId?: string; variableName?: string; } ``` ## 4. Webhook 模块 ### 4.1 功能概述 Webhook 模块允许用户配置回调端点，接收工作流执行过程中的事件通知。模块支持请求体定义、错误码文档等完整功能。 ### 4.2 Webhook 配置界面 前端组件 `WebhookConfigTab` 提供 Webhook 配置界面： ```tsx // 资料来源：packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx // 功能包括： // - Tab 切换 (webhookConfigTabs) // - 使用说明展示 // - 集成文档链接 ``` ### 4.3 Webhook 请求体结构 Webhook 端点的请求体采用 Schema 定义： | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | event | string | 是 | 事件类型 | | timestamp | number | 是 | 事件时间戳 | | data | object | 是 | 事件数据负载 | ### 4.4 错误码定义 | 错误码 | HTTP 状态码 | 说明 | 处理建议 | |--------|-------------|------|---------| | 400 | 400 | 请求参数错误 | 检查请求格式 | | 401 | 401 | 认证失败 | 验证 API Key | | 404 | 404 | 资源不存在 | 检查 Webhook ID | | 500 | 500 | 服务器内部错误 | 联系技术支持 | 错误码通过 `apiDocsData.errorCodes` 动态渲染，支持国际化文本。 ## 5. 认证与配置 ### 5.1 CLI 认证配置 CLI 工具使用配置文件存储认证信息： ```json // 资料来源：packages/cli/README.md { "version": 1, "auth": { "apiKey": "...", "expiresAt": "..." }, "api": { "endpoint": "https://api.refly.ai" } } ``` ### 5.2 环境变量 | 变量名 | 说明 | 默认值 | |--------|------|--------| | `REFLY_API_KEY` | API 认证密钥 | - | | `REFLY_API_ENDPOINT` | API 端点地址 | https://api.refly.ai | ### 5.3 错误码体系 CLI 和 API 共享统一的错误码体系： | 错误码 | 描述 | 解决提示 | |--------|------|---------| | AUTH_REQUIRED | 未认证 | 执行 `refly login` | | BUILDER_NOT_STARTED | 无活跃的 Builder 会话 | 执行 `refly builder start` | | VALIDATION_REQUIRED | 提交前需验证 | 执行 `refly builder validate` | | VALIDATION_ERROR | DAG 验证失败 | 检查错误详情 | | DUPLICATE_NODE_ID | 节点 ID 已存在 | 使用唯一 ID | | CYCLE_DETECTED | 检测到循环依赖 | 移除循环 | | WORKFLOW_NOT_FOUND | 工作流不存在 | 检查工作流 ID | ## 6. 调度功能 ### 6.1 调度模块概述 调度模块允许用户配置定时执行的工作流任务。系统提供调度限制管理，超出限制时显示提示模态框。 ### 6.2 调度限制管理 ```tsx // 资料来源：packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx // 功能包括： // - 调度数量限制检测 // - 限制达到提示 // - 调度列表管理入口 ``` ### 6.3 调度状态管理 调度状态通过 Zustand Store 管理： ```typescript // 资料来源：packages/stores/src/stores/import-resource.ts // 等待列表操作 addToWaitingList: (item: WaitingListItem) => void; removeFromWaitingList: (id: string) => void; updateWaitingListItem: (id: string, updates: Partial<...>) => void; ``` ## 7. 导入资源模块 ### 7.1 导入流程 导入资源模块处理文件、图片等资源的导入与管理： ```typescript // 资料来源：packages/stores/src/stores/import-resource.ts interface ImportResourceState { importResourceModalVisible: boolean; extensionModalVisible: boolean; scrapeLinks: LinkMeta[]; copiedTextPayload: { content: string; title: string; url?: string }; fileList: FileItem[]; imageList: ImageItem[]; selectedMenuItem: ImportResourceMenuItem; insertNodePosition: XYPosition; waitingList: WaitingListItem[]; } ``` ### 7.2 状态操作方法 | 方法 | 说明 | |------|------| | setImportResourceModalVisible | 控制导入模态框显隐 | | setExtensionModalVisible | 控制扩展模态框显隐 | | setScrapeLinks | 设置抓取的链接列表 | | setFileList | 设置文件列表 | | setImageList | 设置图片列表 | | setSelectedMenuItem | 设置选中的菜单项 | | resetState | 重置所有状态 | ## 8. 工具调用与结果读取 ### 8.1 工具调用元数据 系统在 Agent 执行过程中记录工具调用元数据： ```typescript // 资料来源：packages/skill-template/src/scheduler/utils/context.ts:41-48 export interface ToolCallMeta { /** 工具调用 ID，用于通过 read_tool_result 检索 */ callId: string; /** 被调用工具的名称 */ toolName: string; // ... 其他字段 } ``` ### 8.2 工具结果正则匹配 系统支持匹配 Markdown 代码块格式和独立 XML 标签格式的工具调用： ```typescript // 资料来源：packages/skill-template/src/scheduler/utils/context.ts:1-5 const TOOL_USE_BLOCK_REGEX = /\n*```tool_use(?:_result)?[^\n]*\n[\s\S]*?```\n*/g; const TOOL_USE_TAG_REGEX = //g; ``` ### 8.3 Agent 结果结构 ```typescript // 资料来源：packages/skill-template/src/scheduler/utils/context.ts:28-33 export interface AgentResult { resultId: string; // 结果唯一 ID title: string; // 结果标题 content: string; // 结果内容 outputFiles: ContextFileMeta[]; // 输出文件列表 } ``` ## 9. 集成文档系统 ### 9.1 文档标签页结构 集成文档系统通过模态框展示，包含多个标签页： ```tsx // 资料来源：packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx // 标签页类型：webhook | api | skill ``` ### 9.2 Skill 文档标签页 Skill 文档提供安装和卸载指南： ```tsx // 资料来源：packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx // 安装步骤： // 1. 初始化 refly // 2. 安装 skill // 3. 配置环境 ``` ## 10. 邮件模板模块 ### 10.1 凭证邮件 API 模块包含用于发送凭证和奖励通知的邮件模板： ```typescript // 资料来源：apps/api/src/modules/voucher/voucher-email-templates.ts // 模板类型： // - 创作者奖励通知 // - 专属折扣通知 ``` 邮件模板使用内联 HTML 样式，支持深色模式适配。 ## 11. 页面分享功能 ### 11.1 分享页面布局 分享页面支持窄屏和宽屏两种模式： ```tsx // 资料来源：packages/web-core/src/pages/page-share/index.tsx // 宽屏模式特点： // - Modal 宽度 85% // - 内容区域可滚动 // - 关闭按钮位于右上角 ``` ### 11.2 内容块渲染 分享页面使用内容块组件渲染工作流节点内容，支持动态 ID 匹配和空状态展示。 ## 12. 快速开始 ### 12.1 CLI 基本命令 ```bash # 登录认证 refly login # 初始化项目 refly init # 启动 Builder refly builder start --name "workflow-name" # 验证工作流 refly builder validate # 提交工作流 refly builder commit ``` ### 12.2 API 调用示例 ```bash # 获取认证信息 curl -H "Authorization: Bearer $REFLY_API_KEY" \ https://api.refly.ai/v1/workflows # 创建 Webhook curl -X POST -H "Authorization: Bearer $REFLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://your-endpoint.com/webhook"}' \ https://api.refly.ai/v1/webhooks ``` ## 13. 相关资源 - [API 源码目录](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules) - [数据库 Schema](https://github.com/refly-ai/refly/blob/main/apps/api/prisma/schema.prisma) - [CLI 文档](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) - [集成文档组件](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs) --- ## 工作流系统 ### 相关页面 相关主题：[Canvas 画布组件](#page-canvas-components)
相关源码文件 以下源码文件用于生成本页说明： - [packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx) - [packages/ai-workspace-common/src/components/canvas/workflow-run/preview.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/workflow-run/preview.tsx) - [packages/skill-template/src/scheduler/utils/context.ts](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts) - [packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx) - [apps/api/src/modules/skill-package/skill-package.dto.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/skill-package/skill-package.dto.ts) - [packages/web-core/src/index.ts](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/index.ts) - [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) - [packages/skill-template/src/prompts/templates/copilot-agent-system.md](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/prompts/templates/copilot-agent-system.md) - [apps/api/src/modules/schedule/schedule-email-templates.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/schedule/schedule-email-templates.ts)
# 工作流系统 ## 概述 工作流系统（Workflow System）是 Refly 平台的核心组件，负责管理和自动化复杂任务的执行流程。该系统通过有向无环图（DAG）结构组织任务节点，支持变量传递、条件执行、定时调度以及外部集成（如 Webhook）。 **核心职责：** - 提供可视化的工作流编辑和配置能力 - 管理任务的执行状态和生命周期 - 支持工作流的定时调度和即时运行 - 处理任务间的依赖关系和数据流转 - 集成外部工具集（Toolsets）扩展功能 资料来源：[packages/web-core/src/index.ts:1-50]() ## 架构设计 ### 系统组件架构 ```mermaid graph TD subgraph 前端层 WC[Web Core] AWC[AI Workspace Common] end subgraph 后端服务层 API[API Server] WS[Workflow Service] WP[Workflow Processor] SS[Schedule Service] end subgraph 执行引擎 ST[Skill Template] SCH[Scheduler] EX[Executor] end subgraph 外部集成 TS[Toolsets] WH[Webhooks] end WC --> API AWC --> API API --> WS API --> SS WS --> WP WP --> ST ST --> EX EX --> TS EX --> WH SS --> SCH ``` ### 工作流数据结构 工作流采用 DAG 结构定义，由节点（Nodes）和边（Edges）组成： 资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:1-30]() ```mermaid graph LR subgraph 任务定义 T1[Task 1: 任务节点] T2[Task 2: 任务节点] T3[Task 3: 任务节点] end T1 --> T2 T1 --> T3 T2 --> T3 ``` ### 任务节点结构 | 字段 | 类型 | 描述 | |------|------|------| | id | string | 唯一标识符（如 "task-1"） | | title | string | 简洁的任务名称 | | prompt | string | 详细的执行指令，支持 @ 提及 | | dependentTasks | string[] | 前置任务 ID 数组 | | toolsets | string[] | 工具集 ID 列表 | 资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:1-30]() ## 核心接口与类型定义 ### ContextFile 上下文文件 ```typescript export interface ContextFile { name: string; // 文件名称 fileId: string; // 文件唯一标识 type: string; // 文件类型 summary: string; // 文件摘要 content: string; // 文件内容 variableId?: string; // 关联变量ID variableName?: string; // 关联变量名称 } ``` ### ContextFileMeta 元数据版本 ```typescript /** * 仅包含元数据，不含内容 * 用于减少 token 使用量，LLM 通过 read_file 获取完整内容 */ export interface ContextFileMeta { name: string; fileId: string; type: string; summary: string; variableId?: string; variableName?: string; } ``` ### AgentResult 代理执行结果 ```typescript export interface AgentResult { resultId: string; // 结果唯一ID title: string; // 结果标题 content: string; // 结果内容 outputFiles: ContextFileMeta[]; // 输出文件元数据 } ``` ### ToolCallMeta 工具调用元数据 ```typescript export interface ToolCallMeta { callId: string; // 工具调用ID，用于检索结果 toolName: string; // 被调用工具的名称 } ``` 资料来源：[packages/skill-template/src/scheduler/utils/context.ts:1-60]() ## 工作流执行状态 ### 节点执行状态 | 状态 | 描述 | 触发条件 | |------|------|----------| | waiting | 等待中 | 依赖任务未完成 | | executing | 执行中 | 任务正在运行 | | finished | 已完成 | 任务成功执行 | | failed | 失败 | 执行出错 | ```typescript // 执行状态展示逻辑 {(nodeExecution.status === 'waiting' || nodeExecution.status === 'executing') && (
{t('workflowApp.executionStatus', 'Execution Status')}
{t('workflowApp.status', 'Status')}:
{t(`canvas.workflow.run.nodeStatus.${nodeExecution.status}`, { defaultValue: nodeExecution.status, })}
)} ``` ### 错误处理 ```tsx {nodeExecution.status === 'failed' && (
{t('canvas.workflow.run.executionFailed')}
{errorMessage}
)} ``` 资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:1-50]() ## 工作流运行管理 ### 工作流运行预览 ```tsx export const WorkflowRunPreview = memo(WorkflowRunPreviewComponent); // 预览上下文配置 handleAddToFileLibrary(file, 'runlog')} /> ``` ### 执行流程图 ```mermaid graph TD Start[开始运行] --> CheckDeps{检查依赖} CheckDeps -->|依赖满足| RunNode[执行节点] CheckDeps -->|依赖未满足| Wait[等待中] RunNode -->|成功| NextCheck{还有后续节点?} RunNode -->|失败| ErrorLog[记录错误] NextCheck -->|是| WaitForDeps[等待前置完成] NextCheck -->|否| Complete[工作流完成] WaitForDeps --> RunNode ErrorLog --> NextCheck ``` ### 工作流变量表单 ```tsx ``` 资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/preview.tsx:1-50]() ## 定时调度系统 ### 调度服务 调度系统允许用户配置工作流的自动执行时间，支持： - 一次性执行：在指定时间运行工作流 - 循环执行：按 cron 表达式或固定间隔重复执行 - 失败通知：工作流执行失败时发送邮件通知 ### 邮件通知模板 ```typescript // 失败通知邮件 const subject = 'Scheduled workflow failed to run'; const html = wrapEmail( subject, `

Hi ${data.userName},

Your scheduled workflow "${data.scheduleName}" failed during its most recent run.

Run details
  • Status: Failed
  • Run time: ${data.scheduledAt}
  • Next scheduled run: ${data.nextRunTime}
` ); ``` 资料来源：[apps/api/src/modules/schedule/schedule-email-templates.ts:1-50]() ## Webhook 集成 ### Webhook 配置标签页 ```tsx
{t('webhook.instructions')}
  • {t('webhook.instruction1')}
  • {t('webhook.instruction2')}
  • {t('webhook.instruction3')}
``` ### Webhook 错误码 | 错误码 | HTTP 状态 | 描述 | |--------|-----------|------| | 错误代码 | HTTP 状态码 | 错误消息 | 错误码表格组件： ```tsx {apiDocsData.errorCodes.map((error) => ( ))}
{t('integration.api.errorCode')} {t('integration.api.errorStatus')} {t('integration.api.errorMessage')} {t('integration.api.errorDescription')}
{error.code} {error.httpStatus ?? '-'}
``` 资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx:1-30]() ## Skill Package 工作流导出 ### DTO 定义 ```typescript export interface CreateSkillPackageDto { name: string; version: string; description?: string; icon?: SkillIconDto; triggers?: string[]; tags?: string[]; inputSchema?: Record; outputSchema?: Record; } export interface CreateSkillPackageCliDto extends CreateSkillPackageDto { workflowId?: string; workflowIds?: string[]; workflowQuery?: string; workflowSpec?: { nodes?: Array>; edges?: Array>; }; workflowName?: string; workflowDescription?: string; workflowVariables?: Array>; noWorkflow?: boolean; } ``` ### 响应结构 ```typescript export interface CreateSkillPackageCliResponse { skillId: string; name: string; status: string; createdAt: string; workflowId?: string; workflowIds?: string[]; workflows?: Array<{ workflowId: string; name?: string; description?: string; }>; inputSchema?: Record; outputSchema?: Record; installationId?: string; } ``` 资料来源：[apps/api/src/modules/skill-package/skill-package.dto.ts:1-80]() ## CLI 命令行接口 ### 基础命令 | 命令 | 描述 | |------|------| | `refly init` | 初始化 CLI 并安装 skill 文件 | | `refly login` | 使用 API 密钥认证 | | `refly logout` | 移除凭证 | | `refly status` | 检查配置和认证状态 | | `refly whoami` | 显示当前用户信息 | ### Builder 模式 增量构建工作流： ```bash refly builder start --name "workflow-name" # 启动构建会话 refly builder add-node --node '' # 添加节点 refly builder update-node --id "" --patch '' # 更新节点 refly builder remove-node --id "" # 删除节点 refly builder connect --from "" --to "" # 连接节点 refly builder disconnect --from "" --to "" # 断开连接 refly builder status # 查看状态 refly builder graph [--ascii] # 查看图结构 refly builder validate # 验证工作流 refly builder commit # 提交工作流 refly builder abort # 中止构建 ``` ### 工作流管理 ```bash # 创建工作流 refly workflow create --name "" --spec '' # 列出工作流 refly workflow list [--limit N] # 获取工作流详情 refly workflow get # 编辑工作流 refly workflow edit --ops '' # 删除工作流 refly workflow delete ``` ### 工作流执行 ```bash # 运行工作流 refly workflow run [--input ''] # 查看运行状态 refly workflow run-status # 中止运行 refly workflow abort ``` ### Builder 状态机 ```mermaid graph LR IDLE[IDLE 空闲] --> DRAFT[DRAFT 草稿] DRAFT --> VALIDATED[VALIDATED 已验证] VALIDATED --> COMMITTED[COMMITTED 已提交] DRAFT -->|validate| VALIDATED VALIDATED -->|abort| IDLE IDLE -->|start| DRAFT ``` 资料来源：[packages/cli/README.md:1-100]() ## 错误码参考 | 错误码 | 描述 | 提示 | |--------|------|------| | AUTH_REQUIRED | 未认证 | 执行 `refly login` | | BUILDER_NOT_STARTED | 无活跃的构建会话 | 执行 `refly builder start` | | VALIDATION_REQUIRED | 提交前必须验证 | 执行 `refly builder validate` | | VALIDATION_ERROR | DAG 验证失败 | 检查错误详情 | | DUPLICATE_NODE_ID | 节点 ID 已存在 | 使用唯一 ID | | CYCLE_DETECTED | 检测到循环依赖 | 移除循环 | | WORKFLOW_NOT_FOUND | 工作流不存在 | 检查工作流 ID | 资料来源：[packages/cli/README.md:1-100]() ## 页面路由导出 工作流相关的页面组件通过懒加载方式导出： ```typescript // ========== Group 4: Workflow Public ========== export const WorkflowAppPage = lazy( () => import('./pages/workflow-app'), ); export const WorkflowListPage = lazy( () => import('./pages/workflow-list'), ); export const AppManager = lazy( () => import('./pages/app-manager'), ); export const MarketplacePage = lazy( () => import('./pages/marketplace'), ); export const TemplatePreviewPage = lazy( () => import('./pages/template-preview'), ); // ========== Group 5: Run History ========== export const RunHistoryPage = lazy( () => import('./pages/run-history'), ); export const RunDetailPage = lazy( () => import('./pages/run-detail'), ); ``` 资料来源：[packages/web-core/src/index.ts:1-50]() ## 配置说明 ### 配置文件 配置存储在 `~/.refly/config.json`： ```json { "version": 1, "auth": { "apiKey": "...", "expiresAt": "..." }, "api": { "endpoint": "https://api.refly.ai" } } ``` ### 环境变量 | 变量名 | 描述 | |--------|------| | REFLY_API_KEY | 认证用的 API 密钥 | | REFLY_API_ENDPOINT | 覆盖默认 API 端点 | 资料来源：[packages/cli/README.md:1-100]() ## 工具集依赖检查 ### 工具依赖检查器组件 ```tsx export const ToolsDependencyChecker = ({ canvasData, externalOpen, highlightInstallButtons, onOpenChange, creditUsage, }: { canvasData?: RawCanvasData; externalOpen?: boolean; highlightInstallButtons?: boolean; onOpenChange?: (open: boolean) => void; creditUsage?: number; }) => { // 组件实现... }; ``` ### 工具安装处理 ```tsx {!isInstalled && isLogin && ( )} ``` 资料来源：[packages/ai-workspace-common/src/components/canvas/tools-dependency/index.tsx:1-50]() ## 总结 工作流系统是 Refly 平台的核心能力，通过以下特性实现复杂任务的自动化： 1. **DAG 执行模型**：基于有向无环图的任务编排，确保正确的执行顺序 2. **灵活的工具集成**：支持多种工具集扩展功能 3. **完善的生命周期管理**：支持创建、编辑、验证、提交和运行 4. **定时调度能力**：支持 cron 表达式和循环执行 5. **Webhook 集成**：便于与外部系统对接 6. **丰富的 CLI 支持**：支持本地开发和调试 --- ## 工具系统 ### 相关页面 相关主题：[模型提供者系统](#page-provider-system)
相关源码文件 以下源码文件用于生成本页说明： - [packages/skill-template/src/scheduler/utils/context.ts](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts) - [packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts) - [packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx) - [packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx) - [packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/config-info-display.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/config-info-display.tsx)
# 工具系统 ## 概述 工具系统（Tool System）是 Refly 平台的核心能力之一，它为 AI Agent 提供了与外部世界交互的桥梁。通过工具系统，Agent 可以执行代码、调用 API、操作文件、发送 Webhook 等，从而完成复杂的自动化任务。 工具系统的设计遵循以下核心原则： - **模块化**：工具按功能分类为工具集（Toolsets）和独立工具（Tools） - **按需加载**：通过元数据机制减少上下文大小，LLM 按需读取完整内容 - **权限控制**：支持工具授权管理，确保安全执行 - **类型安全**：完整的 TypeScript 类型定义，支持国际化描述 资料来源：[packages/skill-template/src/scheduler/utils/context.ts:20-30]() ## 核心类型定义 ### 工具调用元数据 工具调用元数据用于在 Agent 结果中提供工具调用的摘要信息，而不需要包含完整的输入输出内容： ```typescript interface ToolCallMeta { /** 工具调用 ID，用于通过 read_tool_result 检索 */ callId: string; /** 被调用工具的名称 */ toolName: string; } ``` 资料来源：[packages/skill-template/src/scheduler/utils/context.ts:30-38]() ### 提及项类型 在用户输入界面中，工具和工具集通过提及（Mention）机制进行选择： ```typescript interface MentionItem { name: string; description: string; source: 'toolsets' | 'tools'; toolset?: Toolset; toolsetId?: string; toolDefinition?: ToolDefinition; isInstalled: boolean; } ``` 资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts:1-100]() ## 工具架构 ### 工具层级结构 ``` 工具系统 ├── Toolset（工具集） │ ├── 工具集定义 (ToolsetDefinition) │ ├── 工具列表 (tools) │ └── 授权状态 (authorized) └── Tool（独立工具） ├── 工具名称 (name) ├── 工具描述 (description) └── 工具定义 (definition) ``` ### 工具集管理 工具集（Toolset）是相关工具的集合，支持以下功能： | 功能 | 说明 | |------|------| | 授权管理 | 通过 `authorized` 属性控制访问权限 | | 动态加载 | 根据用户配置动态加载工具集定义 | | 国际化 | 支持多语言描述 (`descriptionDict`) | | 状态持久化 | 工具选择状态可保存到节点数据 | 资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts:40-70]() ## 工具选择流程 ```mermaid sequenceDiagram participant User as 用户 participant UI as 提及界面 participant Hook as useListMentionItems participant Toolset as 工具集定义 User->>UI: 输入 @ 触发提及 UI->>Hook: 请求工具列表 Hook->>Toolset: 查找工具集定义 Toolset-->>Hook: 返回工具元数据 Hook-->>UI: 返回 MentionItem[] UI-->>User: 显示工具选择列表 User->>UI: 选择工具 UI->>Hook: 添加到已选工具集 ``` ## 工具集集成配置 ### 配置界面 在 Agent 配置界面中，用户可以添加或移除工具集： ```typescript interface ConfigInfoDisplayProps { contextItems: ContextFile[]; // 上下文文件 upstreamAgentNodes: Node[]; // 上游 Agent selectedToolsets: Toolset[]; // 已选工具集 disabled?: boolean; // 是否禁用 } ``` ### 工具集显示组件 工具集以标签项（LabelItem）的形式展示，支持以下交互： - 鼠标悬停高亮显示相关节点 - 关闭按钮移除已选工具集 - 图标区分不同工具类型 资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/config-info-display.tsx:1-80]() ## 工具使用块解析 ### 正则表达式定义 工具使用块支持两种格式：Markdown 代码块格式和独立的 XML 标签格式： ```typescript // 匹配 Markdown 代码块格式和独立 XML 标签 const TOOL_USE_BLOCK_REGEX = /\n*```tool_use(?:_result)?[^\n]*\n[\s\S]*?```\n*/g; const TOOL_USE_TAG_REGEX = //g; ``` 支持的格式： | 格式 | 示例 | |------|------| | Markdown 代码块 | ` ```tool_use\n...\n``` ` | | 带结果的代码块 | ` ```tool_use_result\n...\n``` ` | | 独立 XML 标签 | `...` | 资料来源：[packages/skill-template/src/scheduler/utils/context.ts:1-10]() ## Skill 文档系统 ### Skill 安装 Skill 文档提供了标准的安装流程： ```bash # Skill 安装步骤 1. 浏览可用 Skill 列表 2. 点击安装按钮 3. 配置 Skill 参数 ``` 安装完成后，Skill 文件会复制到本地目录： - `~/.refly/skills/` - Skill 资源目录 - Claude Code 集成：`~/.claude/skills/refly/` 资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx:1-50]() ### Skill 卸载 ```bash # Skill 卸载命令 refly skill uninstall ``` 卸载过程会清理相关配置和资源文件。 ## Webhook 集成 ### Webhook 配置标签页 Webhook 配置界面包含以下区域： | 区域 | 说明 | |------|------| | 端点配置 | 设置 Webhook URL 和认证信息 | | 请求体模式 | 定义传入数据的 JSON Schema | | 错误代码表 | HTTP 状态码与错误信息映射 | ### 请求体字段定义 ```typescript interface RequestBodyField { name: string; // 字段名称 type: string; // 数据类型 required: boolean; // 是否必填 description: string; // 字段描述 } ``` 资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx:1-100]() ## 工具与上下文交互 ### 上下文项创建 从提及项创建上下文项时，系统会提取关键元数据： ```typescript const contextItem: IContextItem = { entityId: item.entityId || item.nodeId || item.variableId || item.name, resourceType: item.resourceType, resourceMeta: item.metadata?.resourceMeta, variableType: 'tool', }; ``` ### 上下文项管理 | 操作 | 说明 | |------|------| | 添加 | 通过 `addToContextItems()` 添加到上下文 | | 移除 | 通过 `handleRemoveContextItem()` 移除 | | 高亮 | 悬停时高亮相关画布节点 | 资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx:1-100]() ## 工具系统状态流 ```mermaid graph TD A[用户输入 @] --> B[显示提及列表] B --> C{选择类型} C -->|工具集| D[添加 Toolset] C -->|工具| E[添加 Tool] C -->|资源| F[创建资源上下文] D --> G[更新 selectedToolsets] E --> H[更新 contextItems] F --> I[关联 DriveFile] G --> J[节点数据持久化] H --> J I --> J J --> K[Agent 执行时加载工具] ``` ## 错误处理 ### 工具调用错误 当工具执行失败时，系统会记录错误日志： ```typescript items={logs.map((log) => ({ title: t(`${log.key}.title`, { ...log.titleArgs, ns: 'skillLog' }), description: t(`${log.key}.description`, { ...log.descriptionArgs, ns: 'skillLog' }), status: log.status === 'error' ? 'error' : 'finish', }))} ``` ### 错误状态分类 | 状态 | 说明 | |------|------| | `error` | 工具执行失败 | | `finish` | 工具执行成功 | | `executing` | 工具执行中 | | `waiting` | 等待工具响应 | 资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:1-60]() ## 国际化支持 工具系统全面支持多语言，通过 `descriptionDict` 配置： ```typescript const toolDefinition = { name: 'read_file', descriptionDict: { en: 'Read file content from specified path', zh: '读取指定路径的文件内容', }, }; ``` 当前支持的语言： - `en` - 英文 - `zh` - 中文 资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts:30-50]() ## 总结 工具系统是 Refly 平台实现 AI Agent 能力扩展的核心架构。它通过： 1. **模块化设计** - 工具集和独立工具的清晰分层 2. **按需加载** - 元数据驱动的上下文优化 3. **权限控制** - 灵活的授权机制 4. **国际化支持** - 多语言描述覆盖 5. **可视化配置** - 直观的提及式选择界面 为开发者提供了强大而灵活的工具集成能力，使得 AI Agent 能够执行各种复杂的外部操作任务。 --- ## 认证与授权系统 ### 相关页面 相关主题：[系统整体架构](#page-system-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md) - [packages/web-core/src/components/login-modal/login-content.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/components/login-modal/login-content.tsx) - [packages/web-core/src/pages/login/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/login/index.tsx)
# 认证与授权系统 ## 系统概述 Refly 平台的认证与授权系统是一套完整的安全机制，支持多种认证方式以满足不同用户场景的需求。该系统涵盖了前端登录界面、后端 API 认证以及 CLI 工具的身份验证三大核心领域。 ### 核心认证方式 | 认证方式 | 适用场景 | 实现位置 | |---------|---------|---------| | OAuth 2.0 (Google/GitHub) | Web 端三方登录 | `packages/web-core/src/pages/login/index.tsx` | | 邮箱密码认证 | 传统用户登录 | `packages/web-core/src/components/login-modal/login-content.tsx` | | API 密钥认证 | CLI 工具与机器间通信 | `packages/cli/README.md` | --- ## 前端认证界面 ### 登录模态框 前端登录界面采用模块化设计，支持多种认证方式的动态展示与切换。系统会根据配置自动显示可用的登录选项，包括 OAuth 提供商和邮箱登录表单。 登录模态框的核心功能包括： - **OAuth 按钮组件**：支持 Google 和 GitHub 两种第三方登录方式 - **邮箱登录表单**：可折叠展开的传统邮箱密码登录方式 - **分隔符设计**：在 OAuth 和邮箱登录之间提供视觉分隔 - **国际化支持**：所有文本标签支持多语言切换 ```typescript // OAuth 登录按钮配置示例 handleLogin('google')} loading={authStore.loginInProgress && authStore.loginProvider === 'google'} buttonText={t('landingPage.loginModal.oauthBtn.google')} /> ``` ### 登录页面架构 登录页面 (`packages/web-core/src/pages/login/index.tsx`) 实现了完整的认证流程控制，包括： 1. **认证状态管理**：通过 `authStore` 集中管理登录进度、提供商信息和错误状态 2. **表单切换逻辑**：支持 OAuth 与邮箱登录表单之间的平滑切换 3. **人机验证集成**：集成 Cloudflare Turnstile 验证码防止自动化攻击 4. **主题适配**：支持亮色和暗色主题的自适应切换 ### 验证码保护机制 为防止恶意自动化登录，系统集成了 Cloudflare Turnstile 验证码服务： - 仅在启用验证码功能时显示 - 支持多语言配置 - 提供验证成功、错误和过期三种回调处理 - 验证码令牌作为邮箱登录的前置条件 --- ## CLI 认证系统 ### 认证命令 CLI 工具提供完整的命令行认证接口： | 命令 | 功能说明 | |-----|---------| | `refly login` | 使用 API 密钥进行身份认证 | | `refly logout` | 清除本地存储的认证凭证 | | `refly status` | 检查当前配置和认证状态 | | `refly whoami` | 显示当前登录用户信息 | ### 配置文件 CLI 认证配置存储在用户主目录下的 `~/.refly/config.json` 文件中： ```json { "version": 1, "auth": { "apiKey": "...", "expiresAt": "..." }, "api": { "endpoint": "https://api.refly.ai" } } ``` ### 环境变量 系统支持通过环境变量覆盖默认配置： | 环境变量 | 用途 | |---------|-----| | `REFLY_API_KEY` | 设置 API 密钥进行认证 | | `REFLY_API_ENDPOINT` | 覆盖默认 API 端点地址 | ### Builder 状态机 CLI 的 Builder 模式与认证系统紧密集成，包含以下状态转换： ``` IDLE → DRAFT → VALIDATED → COMMITTED ↑ ↓ ↓ └────────────────┘ ``` 某些 Builder 操作（如 `refly builder validate` 和 `refly builder commit`）需要用户已通过认证状态。 --- ## 错误处理 ### 认证相关错误码 | 错误码 | 描述 | 处理建议 | |-------|-----|---------| | `AUTH_REQUIRED` | 用户未认证 | 执行 `refly login` 命令 | | `BUILDER_NOT_STARTED` | 无活跃的 Builder 会话 | 执行 `refly builder start` | | `VALIDATION_REQUIRED` | 提交前需验证 | 执行 `refly builder validate` | ### 前端错误展示 前端认证界面通过统一的国际化文本键处理错误展示，确保用户获得一致的错误提示体验。所有错误文本均通过 i18n 机制管理，支持多语言定制。 --- ## 安全机制 ### 令牌管理 - **API 密钥有效期**：存储在配置中的 `expiresAt` 字段用于跟踪令牌过期时间 - **自动刷新**：CLI 工具会在需要时提示用户重新认证 ### 人机验证 Cloudflare Turnstile 的集成提供了额外的安全层： - 非侵入式验证体验 - 支持基于语言的验证界面 - 主题自适应（亮色/暗色） ### OAuth 安全实践 - 使用标准 OAuth 2.0 流程 - 不在客户端存储明文密码 - 重定向 URI 验证 --- ## 集成指南 ### 前端集成 在 React 组件中使用登录功能： ```tsx import { useAuthStore } from '@refly/stores'; function LoginButton() { const { loginInProgress, loginProvider } = useAuthStore(); return ( handleLogin('github')} loading={loginInProgress && loginProvider === 'github'} /> ); } ``` ### CLI 集成 在自动化脚本中使用 API 密钥认证： ```bash export REFLY_API_KEY="your-api-key-here" refly workflow list ``` --- ## 架构图 ### 认证流程概览 ```mermaid sequenceDiagram participant User as 用户 participant Frontend as 前端界面 participant API as API 服务 participant OAuth as OAuth Provider User->>Frontend: 选择登录方式 alt OAuth 登录 Frontend->>OAuth: 重定向到 OAuth 提供商 OAuth-->>User: 显示授权页面 User->>OAuth: 确认授权 OAuth-->>Frontend: 返回授权码 Frontend->>API: 交换令牌 else 邮箱登录 User->>Frontend: 输入邮箱密码 Frontend->>API: 发送认证请求 end API-->>Frontend: 返回认证令牌 Frontend-->>User: 登录成功 ``` ### CLI 认证流程 ```mermaid graph TD A[refly login] --> B{检查配置} B -->|有缓存密钥| C{密钥是否过期} C -->|未过期| D[使用缓存密钥] C -->|已过期| E[提示重新登录] B -->|无缓存密钥| F[请求用户输入] F --> G[保存到配置] G --> D E --> F D --> H[执行目标命令] ``` --- ## 相关文档 - [隐私政策](https://docs.refly.ai/about/privacy-policy) - [服务条款](https://docs.refly.ai/about/terms-of-service) --- ## Canvas 画布组件 ### 相关页面 相关主题：[工作流系统](#page-workflow-system), [富文本编辑器系统](#page-editor-system)
相关源码文件 以下源码文件用于生成本页说明： - [packages/ai-workspace-common/src/components/canvas/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/index.tsx) - [packages/ai-workspace-common/src/components/canvas/nodes/index.ts](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/nodes/index.ts) - [packages/ai-workspace-common/src/components/canvas/copilot/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/copilot/index.tsx) - [packages/canvas-common/src/data.ts](https://github.com/refly-ai/refly/blob/main/packages/canvas-common/src/data.ts) - [packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx) - [packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx) - [packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx) - [packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx)
# Canvas 画布组件 ## 概述 Canvas（画布）组件是 refly 平台的核心编辑器组件，负责构建和管理知识工作空间的可视化编辑界面。该组件为用户提供了一个灵活的节点式编辑环境，支持多种类型的内容节点、实时协作、工作流编排以及与外部系统的集成。 画布组件位于 `packages/ai-workspace-common/src/components/canvas/` 目录下，采用模块化架构设计，包含节点管理、画布渲染、工具栏、文档预览、工作流运行等多个子模块。 ## 架构设计 ### 模块层次结构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Canvas 画布组件 │ ├─────────────────────────────────────────────────────────────┤ │ 顶层组件 │ │ ├── Canvas（主容器） │ │ ├── TopToolbar（顶部工具栏） │ │ └── StatusBar（状态栏） │ ├─────────────────────────────────────────────────────────────┤ │ 节点组件 │ │ ├── AgentNode（智能体节点） │ │ ├── DocumentNode（文档节点） │ │ ├── WorkflowNode（工作流节点） │ │ ├── ArtifactNode（产物节点） │ │ └── SkillResponseNode（技能响应节点） │ ├─────────────────────────────────────────────────────────────┤ │ 交互组件 │ │ ├── RichChatInput（富文本聊天输入） │ │ ├── Copilot（副驾驶助手） │ │ └── PureCopilot（纯净副驾驶） │ ├─────────────────────────────────────────────────────────────┤ │ 工作流运行 │ │ ├── WorkflowNodePanel（工作流节点面板） │ │ ├── ActionStep（执行步骤） │ │ └── ArtifactRenderer（产物渲染器） │ └─────────────────────────────────────────────────────────────┘ ``` ### 核心数据流 ```mermaid graph TD A[用户交互] --> B[Canvas Context] B --> C{节点类型判断} C -->|Agent| D[AgentNode 组件] C -->|Document| E[DocumentNode 组件] C -->|Workflow| F[WorkflowNodePanel] C -->|Artifact| G[ArtifactRenderer] D --> H[AgentNodeManagement] E --> I[DocumentProvider] F --> J[执行状态管理] G --> K[Renderer 组件] H --> L[Tool Store / Variable Store] J --> M[结果输出] K --> N[预览渲染] L --> O[工具调用] M --> P[LastRunTab] N --> Q[只读展示] ``` ## 核心组件 ### Canvas 主组件 Canvas 主组件是整个画布系统的根容器，负责初始化画布上下文并协调各个子组件的渲染。 **组件位置**: `packages/ai-workspace-common/src/components/canvas/index.tsx` Canvas 主组件提供以下核心功能： | 功能 | 描述 | |------|------| | 画布上下文管理 | 通过 React Context 提供全局画布状态 | | 节点渲染协调 | 根据节点类型分发到对应的节点组件 | | 缩放与平移 | 支持画布的缩放和拖拽平移操作 | | 节点连接管理 | 处理节点之间的连线关系 | | 拖拽排序 | 支持节点的拖拽排序功能 | ### 节点组件体系 节点组件是画布上的核心编辑单元，每种节点类型对应不同的功能和交互模式。 #### AgentNode 智能体节点 AgentNode 是画布中用于表示 AI 智能体的节点组件，封装了与大语言模型交互的核心逻辑。 **组件引用**: `packages/ai-workspace-common/src/components/canvas/nodes/index.ts` ```tsx // AgentNode 核心属性 interface AgentNodeProps { nodeId: string; // 节点唯一标识 canvasId: string; // 所属画布 ID readonly?: boolean; // 只读模式 onRequestFix?: () => void; // 修复请求回调 } ``` #### WorkflowNodePanel 工作流节点面板 工作流节点面板用于展示和执行工作流的运行状态，包括执行日志、结果输出和错误信息。 **组件位置**: `packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx` ```tsx // WorkflowNodePanel 核心属性 interface WorkflowNodePanelProps { node: any; // 节点数据 canvasId: string; // 画布 ID resultId?: string; // 执行结果 ID result?: AgentResult; // 执行结果 loading?: boolean; // 加载状态 isStreaming?: boolean; // 是否为流式输出 outputStep?: any; // 输出步骤 query?: string; // 查询参数 title?: string; // 节点标题 selectedToolsets?: any[]; // 选中的工具集 } ``` 工作流节点面板包含以下标签页： | 标签页 | 功能 | 资料来源 | |--------|------|----------| | LastRunTab | 最近运行结果展示 | [workflow-node-panel.tsx:60]() | | 日志标签 | 执行日志查看 | [workflow-node-panel.tsx:61]() | | 输出标签 | 结构化输出展示 | [workflow-node-panel.tsx:62]() | ### ArtifactRenderer 产物渲染器 ArtifactRenderer 负责渲染代码片段、文档和其他产物内容，支持全屏模式和缩略图预览。 **组件位置**: `packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx` ```tsx // ArtifactRenderer 核心属性 interface ArtifactRendererProps { content: string; // 内容文本 type: string; // 内容类型 title?: string; // 标题 language?: string; // 编程语言 readonly?: boolean; // 只读模式 purePreview?: boolean; // 纯净预览模式 onRequestFix?: () => void; // 修复请求 width?: string; // 宽度 height?: string; // 高度 } ``` ArtifactRenderer 支持两种渲染模式： | 模式 | 条件 | 行为 | |------|------|------| | 缩略图模式 | `isMinimap === true` | 以 50% 缩放比例显示在左上角 | | 全屏模式 | `isFullscreen === true` | 占满可用高度区域 | 渲染器通过 memo 的第二个参数实现渲染优化，仅在关键元数据变化时重新渲染： ```tsx (prevProps, nextProps) => { const prevMetadata = prevProps.node.nodeData?.metadata || {}; const nextMetadata = nextProps.node.nodeData?.metadata || {}; return ( prevProps.type === nextProps.type && prevProps.node.entityId === nextProps.node.entityId && prevMetadata.content === nextMetadata.content && prevMetadata.status === nextMetadata.status && prevMetadata.type === nextMetadata.type ); } ``` 资料来源：[ArtifactRenderer.tsx:98-112]() ## 交互组件 ### RichChatInput 富文本聊天输入 RichChatInput 是画布中用于用户输入的核心组件，支持多行文本、文件上传、@提及等功能。 **组件位置**: `packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx` ```tsx // RichChatInput 核心接口 interface RichChatInputProps { readonly?: boolean; handleSendMessage: () => void; onUploadImage?: (file: File) => Promise; onUploadMultipleImages?: (files: File[]) => Promise; onFocus?: () => void; nodeId?: string; placeholder?: string; mentionPosition?: MentionPosition; } ``` RichChatInput 暴露以下方法供父组件调用： ```tsx export interface RichChatInputRef { focus: () => void; // 获取输入框焦点 insertAtSymbol?: () => void; // 插入 @ 符号 } ``` 组件内部集成了以下功能模块： | 模块 | 功能 | |------|------| | useAgentNodeManagement | 节点状态管理 | | useAgentConnections | 智能体连接管理 | | useVariablesManagement | 变量管理 | | useFetchDriveFiles | 云端文件获取 | 资料来源：[rich-chat-input/index.tsx:32-50]() ### ActionStep 执行步骤组件 ActionStep 组件用于展示技能执行的中间步骤和推理过程。 **组件位置**: `packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx` ```tsx // ReasoningContent 组件属性 interface ReasoningContentProps { resultId: string; reasoningContent: string; sources: Source[]; step: ActionStep; status: ActionStatus; } ``` ActionStep 支持以下状态转换： | 状态 | 自动行为 | |------|----------| | `executing` | 展开推理内容 | | `waiting` | 展开推理内容 | | `finish` | 折叠推理内容 | | `failed` | 折叠推理内容 | ```tsx useEffect(() => { if (['executing', 'waiting'].includes(status)) { setCollapsed(false); } else { setCollapsed(true); } }, [status]); ``` 资料来源：[action-step.tsx:56-63]() ### Copilot 副驾驶组件 Copilot 组件是画布中的 AI 助手入口，提供上下文感知的智能辅助功能。 **组件位置**: `packages/ai-workspace-common/src/components/canvas/copilot/index.tsx` ## 状态管理 ### Canvas Context Canvas 使用 React Context 提供全局状态管理，主要包括： ```tsx interface CanvasContextValue { canvasId: string; // 画布唯一标识 readonly?: boolean; // 只读模式标识 // 其他上下文属性 } ``` ### 节点状态管理 节点状态通过 `useAgentNodeManagement` hook 进行管理： ```tsx const { query, setQuery, setContextItems, setSelectedToolsets } = useAgentNodeManagement(nodeId); ``` ### 工作流执行状态 工作流节点面板管理以下执行状态： | 状态 | 描述 | |------|------| | `idle` | 空闲状态 | | `loading` | 加载中 | | `generating` | 生成中 | | `executing` | 执行中 | | `finish` | 执行完成 | | `failed` | 执行失败 | ## 国际化支持 Canvas 组件全面支持国际化，通过 `react-i18next` 实现多语言切换。 ### 关键翻译键 | 翻译键 | 描述 | |--------|------| | `pages.components.artifact.generating` | 产物生成中提示 | | `pages.components.artifact.loading` | 产物加载中提示 | | `pages.components.artifact.notSelected` | 未选择产物提示 | | `pages.components.artifact.code` | 代码类型标识 | | `canvas.workflow.run.executionFailed` | 执行失败提示 | 资料来源：[ArtifactRenderer.tsx:45-70]() 和 [workflow-node-panel.tsx:44]() ## 样式与主题 ### 动态样式类 Canvas 组件使用 Tailwind CSS 实现响应式样式，并支持亮色/暗色主题切换： ```tsx className={`h-full bg-white dark:bg-[var(--refly-bg-content-z2)] ${!isFullscreen ? 'rounded px-4 pb-4' : 'w-full'}`} ``` ### 主题变量 | 变量名 | 用途 | |--------|------| | `--refly-bg-content-z2` | 内容区域背景色 | | `--refly-text-0` | 主文本色 | | `--refly-primary-default` | 主色调 | | `--refly-func-danger-default` | 危险/错误状态色 | ## 组件配置选项 ### PrimaryPageLayout 配置 画布页面使用 PrimaryPageLayout 作为基础布局： | 配置项 | 类型 | 描述 | |--------|------|------| | `title` | string | 页面标题 | | `actions` | ReactNode | 动作按钮区域 | | `extra` | ReactNode | 额外内容区域 | | `fixHeight` | boolean | 是否固定高度 | | `noPaddingY` | boolean | 是否移除垂直内边距 | | `noPaddingX` | boolean | 是否移除水平内边距 | ### SecondaryPageLayout 配置 详情页面使用 SecondaryPageLayout： | 配置项 | 类型 | 描述 | |--------|------|------| | `title` | string | 页面标题 | | `desc` | string | 页面描述 | | `onBack` | function | 返回按钮回调 | | `actions` | ReactNode | 动作按钮区域 | 资料来源：[packages/layout/README.md]() ## 性能优化 ### Memo 优化策略 ArtifactRenderer 通过 memo 的自定义比较函数实现精细化的重渲染控制： ```tsx export const ArtifactRenderer = memo( (props) => { /* 渲染逻辑 */ }, (prevProps, nextProps) => { // 仅在关键属性变化时重渲染 return ( prevProps.type === nextProps.type && prevProps.node.entityId === nextProps.node.entityId && prevMetadata.content === nextMetadata.content && prevMetadata.status === nextMetadata.status && prevMetadata.type === nextMetadata.type ); } ); ``` ### 懒加载策略 工作流节点面板支持懒加载标记： ```tsx onChange={(activeKeys) => { if (Array.isArray(activeKeys) && activeKeys.includes('agent')) { agentNodesLazy.markAsRendered(node.id); } }} ``` ## 相关子模块 ### 文档组件 文档组件为画布提供富文本编辑能力： ```tsx // packages/ai-workspace-common/src/components/document/index.tsx {!canvasReadOnly && } ``` ### 集成文档模块 画布支持通过 IntegrationDocsModal 展示外部集成文档： ```tsx // packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx ``` ### Webhook 配置 Webhook 功能通过 WebhookConfigTab 提供配置界面： | 功能 | 描述 | |------|------| | Webhook URL 配置 | 设置接收数据的端点 | | 请求体预览 | 展示请求数据结构 | | 使用说明 | 提供集成指导 | 资料来源：[webhook-config-tab.tsx]() 和 [webhook-docs-tab.tsx]() ## 总结 Canvas 画布组件是 refly 平台的核心交互界面，采用模块化、组件化的架构设计。通过 AgentNode、WorkflowNode、ArtifactRenderer 等核心组件的协同工作，为用户提供了强大的知识编排和工作流自动化能力。组件支持精细化的状态管理、国际化、主题切换和性能优化，是构建现代 AI 工作空间的重要基础设施。 --- ## 富文本编辑器系统 ### 相关页面 相关主题：[Canvas 画布组件](#page-canvas-components)
相关源码文件 以下源码文件用于生成本页说明： - [packages/ai-workspace-common/src/components/document/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/document/index.tsx) - [packages/ai-workspace-common/src/modules/artifacts/code-runner/render/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/modules/artifacts/code-runner/render/index.tsx) - [packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx) - [packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx)
# 富文本编辑器系统 ## 概述 富文本编辑器系统（Rich Text Editor System）是 refly 平台的核心组件之一，负责管理和渲染多种类型的内容，包括文档编辑、代码片段、思维导图、HTML内容等。该系统采用了基于 Tiptap/ProseMirror 的编辑器架构，支持实时协作和只读预览两种模式。 编辑器的设计理念是将内容创作与内容展示分离，通过统一的渲染接口处理不同类型的内容，同时提供灵活的状态管理和上下文隔离机制。 ## 系统架构 ### 核心组件层次 富文本编辑器系统采用分层架构设计，主要包含以下层次： | 层级 | 组件名称 | 职责说明 | |------|----------|----------| | 视图层 | DocumentEditor | 文档编辑器主容器，处理编辑/只读状态 | | 视图层 | CollaborativeEditor | 实时协作编辑器组件 | | 视图层 | ReadonlyEditor | 只读文档展示组件 | | 渲染层 | Renderer | 通用内容渲染器，根据类型分发 | | 渲染层 | ArtifactRenderer | 制品渲染器，管理多种内容格式 | | 渲染层 | MindMapRenderer | 思维导图专用渲染器 | | 渲染层 | HTMLRenderer | HTML内容渲染器 | | 存储层 | DocumentProvider | 文档上下文提供者 | | 状态层 | DocumentStore | 文档状态管理 | ### 架构流程图 ```mermaid graph TD A[DocumentEditor] --> B[DocumentProvider] B --> C[DocumentStore 状态管理] A --> D{isReadonly} D -->|true| E[ReadonlyEditor] D -->|false| F[CollaborativeEditor] F --> G[Tiptap Editor Core] G --> H[Extensions 扩展系统] H --> I[Table Extension] H --> J[Markdown Extension] H --> K[Custom Extensions] E --> L[Content Render] L --> M[Renderer 组件] M --> N{contentType} N -->|markdown| O[Markdown Renderer] N -->|code| O[Markdown Renderer] N -->|mindmap| P[MindMapRenderer] N -->|html| Q[HTMLRenderer] N -->|application| R[ArtifactRenderer] ``` ## 文档编辑器组件 ### DocumentEditor 主组件 `DocumentEditor` 是文档编辑器的核心入口组件，封装了文档编辑的主要逻辑： ```tsx export const DocumentEditor = memo( ({ docId, shareId, readonly, nodeId, }: { docId: string; shareId?: string; readonly?: boolean; nodeId: string; }) => { const { resetState } = useDocumentStoreShallow((state) => ({ resetState: state.resetState, })); const { readonly: canvasReadOnly } = useCanvasContext(); useEffect(() => { return () => { resetState(docId); }; }, []); return ( {/* Editor Components */} ); } ); ``` **关键特性：** - 基于 `docId` 的文档隔离管理 - 组件卸载时自动清理状态，防止内存泄漏 - 支持 `shareId` 用于文档分享场景 - 与 Canvas 上下文集成，继承只读状态 ### 编辑模式分支 文档编辑器根据 `readonly` 属性决定渲染模式： ```mermaid graph LR A[DocumentEditor] --> B{readonly prop} B -->|false| C[CollaborativeEditor] B -->|true| D[ReadonlyEditor] C --> E[Tiptap Collaborative] D --> F[Static Render] ``` **CollaborativeEditor（协作编辑模式）：** - 启用实时协作功能 - 支持多人同时编辑 - 集成 Tiptap 核心编辑器引擎 **ReadonlyEditor（只读模式）：** - 用于文档预览和分享 - 优化渲染性能 - 禁用编辑交互 ## 内容渲染系统 ### Renderer 组件 Renderer 是统一的内容渲染入口，支持多种内容类型的分发渲染： | 内容类型 | 渲染组件 | 说明 | |----------|----------|------| | `text/markdown` | Markdown | 标准 Markdown 渲染 | | `application/refly.artifacts.code` | Markdown | 代码制品渲染 | | `application/refly.artifacts.mindmap` | MindMapRenderer | 思维导图渲染 | | `text/html` | HTMLRenderer | HTML 内容渲染 | | `application/*` (未知类型) | HTMLRenderer | 默认回退 | ```tsx case 'application/refly.artifacts.mindmap': { return ( ); } case 'text/html': { return ( ); } ``` ### 思维导图渲染 MindMapRenderer 是专门用于思维导图内容的渲染组件，提供以下功能： - **缩放控制**：支持自定义宽高 - **只读/编辑切换**：通过 `readonly` 属性控制 - **变更回调**：通过 `onChange` 回调通知内容更新 - **尺寸自适应**：根据容器自动调整 ### HTML 渲染 HTMLRenderer 处理原生 HTML 内容，支持以下特性： - **预览模式**：通过 `purePreview` 控制预览样式 - **操作按钮**：通过 `showActions` 显示操作按钮 - **尺寸控制**：支持自定义宽高参数 ### ArtifactRenderer 制品渲染器 ArtifactRenderer 是专门处理 AI 生成制品的组件，提供增强的预览体验： ```tsx
``` **制品渲染特性：** - 小地图预览模式：使用 `scale-[0.5]` 和 `w-[200%]` 实现缩略图效果 - 主题适配：自动适配亮色/暗色主题 - 语言感知：根据制品类型显示对应语法高亮 - 修复请求：支持 `onRequestFix` 回调处理修复请求 ## 状态管理 ### DocumentStore 文档状态管理采用 Zustand store 模式，主要职责包括： - **文档内容状态**：存储当前文档的内容数据 - **编辑器状态**：跟踪编辑器的激活状态 - **清理机制**：提供 `resetState` 方法用于组件卸载时清理 ```tsx const { resetState } = useDocumentStoreShallow((state) => ({ resetState: state.resetState, })); useEffect(() => { return () => { resetState(docId); }; }, []); ``` ### DocumentProvider 上下文 DocumentProvider 组件为子组件提供文档上下文信息，包括： - `docId`：文档唯一标识 - `shareId`：分享标识（可选） - `readonly`：只读状态 - `nodeId`：节点标识 ## 渲染状态与条件 ### 加载状态处理 渲染器组件支持完整的加载状态管理： ```tsx if (isLoading) { return (
{t('pages.components.artifact.loading', { type: rendererType === 'document' ? t('common.document').toLowerCase() : t('pages.components.artifact.code').toLowerCase(), })}
); } ``` ### 生成状态处理 对于正在生成的内容（如 AI 生成），渲染器显示生成中的状态： ```tsx if (status === 'generating') { return (
{t('pages.components.artifact.generating', { type: '' })}
); } ``` ### 空内容状态 当没有选中内容时，显示提示信息： ```tsx {t('pages.components.artifact.notSelected', { type: rendererType === 'document' ? t('common.document').toLowerCase() : t('pages.components.artifact.code').toLowerCase(), })} ``` ## 组件 Memoization 优化 Renderer 组件使用自定义相等性检查实现高效的 memoization： ```tsx Renderer.displayName = 'Renderer'; export default memo( RendererComponent, (prevProps, nextProps) => { // Custom equality check for more effective memoization return ( prevProps.content === nextProps.content && prevProps.type === nextProps.type && prevProps.readonly === nextProps.readonly && prevProps.title === nextProps.title && prevProps.language === nextProps.language && prevProps.width === nextProps.width && prevProps.height === nextProps.height && prevProps.onChange === nextProps.onChange && prevProps.showActions === nextProps.showActions && prevProps.purePreview === nextProps.purePreview ); } ); ``` **Memoization 策略：** - 比较所有关键属性，避免不必要的重渲染 - 函数引用比较使用稳定引用 - 支持 props 变更时的精确控制 ## 主题与样式适配 编辑器系统支持亮色/暗色主题自动适配： ```tsx className={`h-full bg-white dark:bg-[var(--refly-bg-content-z2)]`} ``` 样式变量映射： | 亮色主题 | 暗色主题 | 用途 | |----------|----------|------| | `bg-white` | `dark:bg-gray-900` | 主背景色 | | `bg-white` | `dark:bg-[var(--refly-bg-content-z2)]` | 内容区域背景 | | `text-gray-800` | `dark:text-white` | 主文本色 | | `text-gray-500` | `dark:text-gray-400` | 次要文本色 | ## 资源预览集成 编辑器系统与资源视图组件集成，支持文档、元数据展示： ```tsx {resourceDetail?.data?.url && ( {resourceDetail?.data?.url} )} ``` 资源元数据组件提供： - 资源标题显示 - URL 链接展示 - 创建时间展示（相对时间格式） - 多语言时间格式化 ## API 参考 ### DocumentEditor Props | 属性名 | 类型 | 必填 | 说明 | |--------|------|------|------| | `docId` | string | 是 | 文档唯一标识 | | `shareId` | string | 否 | 分享标识 | | `readonly` | boolean | 否 | 是否只读模式 | | `nodeId` | string | 是 | 关联节点标识 | ### Renderer Props | 属性名 | 类型 | 必填 | 说明 | |--------|------|------|------| | `content` | string | 是 | 内容文本 | | `type` | string | 是 | 内容 MIME 类型 | | `title` | string | 否 | 标题 | | `language` | string | 否 | 编程语言类型 | | `readonly` | boolean | 否 | 只读模式 | | `width` | string | 否 | 渲染宽度 | | `height` | string | 否 | 渲染高度 | | `showActions` | boolean | 否 | 显示操作按钮 | | `purePreview` | boolean | 否 | 纯预览模式 | | `onChange` | function | 否 | 内容变更回调 | | `onRequestFix` | function | 否 | 修复请求回调 | ## 总结 富文本编辑器系统是 refly 平台内容创作的核心基础设施，通过分层架构实现了编辑功能与渲染逻辑的解耦。系统支持多种内容类型的统一处理，提供了良好的状态管理和性能优化机制，同时适配亮色/暗色主题，满足不同使用场景的需求。 该系统的设计遵循了以下原则： 1. **关注点分离**：编辑逻辑与渲染逻辑独立 2. **组件化**：每个功能模块都是可复用的组件 3. **状态隔离**：基于 docId 的状态隔离机制 4. **性能优先**：通过 memoization 减少不必要的重渲染 5. **主题适配**：统一的深色模式支持 --- ## 模型提供者系统 ### 相关页面 相关主题：[工具系统](#page-tool-system)
相关源码文件 以下源码文件用于生成本页说明： - [apps/api/src/modules/provider/provider.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/provider/provider.service.ts) - [apps/api/src/modules/provider/auto-model-router.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/provider/auto-model-router.service.ts) - [packages/providers/src/llm/index.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/llm/index.ts) - [packages/providers/src/types.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/types.ts) - [config/provider-catalog.json](https://github.com/refly-ai/refly/blob/main/config/provider-catalog.json)
# 模型提供者系统 ## 概述 模型提供者系统（Model Provider System）是 Refly 平台的核心模块之一，负责管理与协调各类大语言模型（LLM）的接入、调用与路由。该系统通过统一的抽象层，为上层应用提供一致的模型调用接口，同时支持多模型提供商的动态切换与自动路由。 系统的设计目标包括： - **统一抽象**：为不同模型提供商提供一致的调用接口 - **动态路由**：根据任务需求自动选择最合适的模型 - **配置管理**：集中管理模型提供商的配置与凭证 - **成本优化**：支持模型混用以优化成本与性能 --- ## 系统架构 ### 整体架构图 ```mermaid graph TD A[应用层 Application Layer] --> B[模型路由层 Model Router] B --> C[提供者服务层 Provider Service] C --> D[提供商适配器 Provider Adapters] D --> E[OpenAI] D --> F[Anthropic] D --> G[Google] D --> H[自定义 Provider] I[配置层 Config Layer] --> C I --> B J[类型定义 Types] --> B J --> C ``` ### 核心组件 | 组件名称 | 文件路径 | 职责描述 | |---------|---------|---------| | ProviderService | `apps/api/src/modules/provider/provider.service.ts` | 提供者服务的核心逻辑，管理模型实例的生命周期 | | AutoModelRouter | `apps/api/src/modules/provider/auto-model-router.service.ts` | 自动模型路由器，根据条件自动选择最优模型 | | LLM Providers | `packages/providers/src/llm/index.ts` | LLM 提供商的统一导出与初始化 | | Type Definitions | `packages/providers/src/types.ts` | 系统类型定义，包括 Provider、Model 等接口 | | Provider Catalog | `config/provider-catalog.json` | 模型提供商的配置文件，包含可用模型列表 | --- ## 类型系统 系统定义了一套完整的类型体系，用于描述模型提供商的配置与行为。 ### 核心类型定义 资料来源：[packages/providers/src/types.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/types.ts) ```typescript // Provider 配置接口 interface ProviderConfig { provider: string; // 提供商标识符 apiKey?: string; // API 密钥 baseURL?: string; // 自定义端点 models: ModelConfig[]; // 可用模型列表 } // Model 配置接口 interface ModelConfig { name: string; // 模型名称 enabled?: boolean; // 是否启用 maxTokens?: number; // 最大 token 数 temperature?: number; // 温度参数 } ``` ### Provider 枚举类型 系统支持的主要模型提供商包括： | 提供商标识 | 说明 | 官方文档 | |-----------|------|---------| | `openai` | OpenAI GPT 系列 | https://platform.openai.com | | `anthropic` | Anthropic Claude 系列 | https://docs.anthropic.com | | `google` | Google Gemini 系列 | https://ai.google.dev | | `azure` | Azure OpenAI | https://azure.microsoft.com | | `ollama` | 本地 Ollama | https://ollama.ai | --- ## 提供者服务 ### ProviderService 资料来源：[apps/api/src/modules/provider/provider.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/provider/provider.service.ts) ProviderService 是模型提供者系统的核心服务类，负责： - **模型实例管理**：创建、缓存和销毁模型实例 - **配置加载**：从配置文件或数据库加载 Provider 配置 - **凭证管理**：安全存储和检索 API 密钥 - **健康检查**：验证 Provider 连接状态 ```typescript class ProviderService { // 初始化 Provider async initializeProvider(providerId: string): Promise; // 获取模型实例 getModel(providerId: string, modelName: string): LLMModel; // 更新配置 updateConfig(providerId: string, config: Partial): void; // 列出所有可用 Provider listProviders(): Provider[]; } ``` ### 服务初始化流程 ```mermaid sequenceDiagram participant App as 应用启动 participant PS as ProviderService participant Config as 配置中心 participant Adapter as Provider适配器 App->>PS: 初始化请求 PS->>Config: 加载 provider-catalog.json Config-->>PS: 返回提供商配置 PS->>Adapter: 创建适配器实例 Adapter-->>PS: 适配器就绪 PS->>PS: 缓存模型实例 PS-->>App: 服务就绪 ``` --- ## 自动模型路由 ### AutoModelRouter 资料来源：[apps/api/src/modules/provider/auto-model-router.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/provider/auto-model-router.service.ts) 自动模型路由器根据预设规则和运行时条件，自动选择最适合当前任务的模型。 #### 路由策略 | 策略类型 | 说明 | 适用场景 | |---------|------|---------| | `cost-optimized` | 优先选择成本最低的模型 | 日常任务、测试环境 | | `performance-first` | 优先选择性能最佳的模型 | 关键业务场景 | | `balanced` | 平衡成本与性能 | 一般生产环境 | | `latency-sensitive` | 优先选择响应最快的模型 | 实时交互场景 | #### 路由决策流程 ```mermaid graph TD A[请求进入] --> B{检查缓存} B -->|命中| C[返回缓存模型] B -->|未命中| D{路由策略判断} D -->|成本优先| E[按成本排序] D -->|性能优先| F[按性能排序] D -->|均衡| G[综合评分排序] E --> H[选择最优模型] F --> H G --> H H --> I[调用模型] I --> J[缓存结果] ``` #### 路由规则配置 ```json { "routingRules": [ { "condition": "task.type === 'code-generation'", "preferredProvider": "openai", "preferredModel": "gpt-4o" }, { "condition": "task.complexity > 0.8", "fallbackProviders": ["anthropic", "google"] } ] } ``` --- ## LLM 提供商实现 ### 提供商包结构 资料来源：[packages/providers/src/llm/index.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/llm/index.ts) ```typescript // LLM 提供商统一导出 export { OpenAIProvider } from './openai'; export { AnthropicProvider } from './anthropic'; export { GoogleProvider } from './google'; // 工厂函数 export function createProvider(config: ProviderConfig): LLMProvider { switch (config.provider) { case 'openai': return new OpenAIProvider(config); case 'anthropic': return new AnthropicProvider(config); case 'google': return new GoogleProvider(config); default: throw new Error(`Unsupported provider: ${config.provider}`); } } ``` ### 提供商适配器接口 每个模型提供商都实现统一的适配器接口： ```typescript interface LLMProvider { // 模型标识 readonly name: string; // 聊天完成 chat(request: ChatRequest): Promise; // 流式聊天 streamChat(request: ChatRequest): AsyncGenerator; // 获取模型列表 listModels(): Promise; // 健康检查 healthCheck(): Promise; } ``` --- ## 配置管理 ### Provider Catalog 资料来源：[config/provider-catalog.json](https://github.com/refly-ai/refly/blob/main/config/provider-catalog.json) Provider Catalog 是系统配置的核心文件，定义了所有可用的模型提供商及其模型列表。 #### 配置结构 ```json { "version": "1.0", "providers": [ { "id": "openai", "name": "OpenAI", "enabled": true, "models": [ { "id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000, "inputCost": 5.0, "outputCost": 15.0, "capabilities": ["chat", "vision", "function-calling"] } ] } ] } ``` #### 模型成本配置 | 模型 | 上下文窗口 | 输入成本 ($/1M tokens) | 输出成本 ($/1M tokens) | |-----|----------|----------------------|----------------------| | gpt-4o | 128K | $5.00 | $15.00 | | gpt-4o-mini | 128K | $0.15 | $0.60 | | claude-3-5-sonnet | 200K | $3.00 | $15.00 | | claude-3-5-haiku | 200K | $0.80 | $4.00 | | gemini-2.0-flash | 1M | $0.00 | $0.00 | --- ## 使用示例 ### 基本调用流程 ```typescript import { createProvider } from '@refly/providers'; // 1. 创建 Provider 实例 const provider = createProvider({ provider: 'openai', apiKey: process.env.OPENAI_API_KEY, }); // 2. 发送聊天请求 const response = await provider.chat({ model: 'gpt-4o', messages: [ { role: 'system', content: '你是一个有帮助的助手。' }, { role: 'user', content: '请解释什么是模型提供者系统。' } ], temperature: 0.7, }); // 3. 处理响应 console.log(response.content); ``` ### 使用自动路由 ```typescript import { AutoModelRouter } from '@refly/providers'; const router = new AutoModelRouter({ strategy: 'balanced', fallbackEnabled: true, }); // 自动选择最优模型 const result = await router.route({ task: { type: 'reasoning', complexity: 0.8, }, messages: conversationHistory, }); ``` --- ## 最佳实践 ### 1. 模型选择建议 | 任务类型 | 推荐模型 | 原因 | |---------|---------|------| | 代码生成 | GPT-4o, Claude 3.5 Sonnet | 上下文理解能力强 | | 创意写作 | GPT-4o, Claude 3.5 Sonnet | 生成质量高 | | 快速问答 | GPT-4o-mini, Claude 3.5 Haiku | 响应快、成本低 | | 长文本处理 | Claude 3.5 Sonnet, Gemini 2.0 Flash | 上下文窗口大 | ### 2. 错误处理策略 ```typescript async function withFallback( task: Task, messages: Message[] ): Promise { const router = new AutoModelRouter(); try { return await router.route({ task, messages }); } catch (error) { if (error.code === 'RATE_LIMIT') { // 等待后重试或切换模型 await delay(1000); return router.route({ task, messages, preferProvider: 'alternative' }); } throw error; } } ``` ### 3. 成本监控 建议在生产环境中启用成本监控： ```typescript const router = new AutoModelRouter({ onCostCalculated: (cost: CostInfo) => { metrics.track('model_cost', { provider: cost.provider, model: cost.model, inputTokens: cost.inputTokens, outputTokens: cost.outputTokens, totalCost: cost.totalCost, }); }, }); ``` --- ## 相关文档 - [API 参考文档](https://docs.refly.ai/api-reference) - [SDK 安装指南](https://docs.refly.ai/getting-started) - [模型定价说明](https://docs.refly.ai/pricing) - [安全与隐私政策](https://docs.refly.ai/about/privacy-policy) --- --- ## Doramagic 踩坑日志 项目：refly-ai/refly 摘要：发现 22 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Question] Sandbox deployment fails with "AggregateError: All promises were rejected" - Scalebox template and setup inq…。 ## 1. 安全/权限坑 · 来源证据：[Question] Sandbox deployment fails with "AggregateError: All promises were rejected" - Scalebox template and setup inq… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question] Sandbox deployment fails with "AggregateError: All promises were rejected" - Scalebox template and setup inquiry - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_0805b730bc2b4c5787cea36e55a118cd | https://github.com/refly-ai/refly/issues/2088 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：v0.5.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.5.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_0c49752e8b10439aa5eda23446563b9f | https://github.com/refly-ai/refly/releases/tag/v0.5.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：v0.7.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.0 - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_9680da63e17747a5afdc985701b56111 | https://github.com/refly-ai/refly/releases/tag/v0.7.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 4. 安装坑 · 来源证据：v0.8.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.0 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_bde62a80a1994e2b89a9741dabace272 | https://github.com/refly-ai/refly/releases/tag/v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 5. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。 - 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。 - 证据：capability.host_targets | github_repo:759799529 | https://github.com/refly-ai/refly | host_targets=claude, claude_code, cursor ## 6. 配置坑 · 来源证据：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_91f612b63eef439ba150bafe81966117 | https://github.com/refly-ai/refly/issues/2278 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:759799529 | https://github.com/refly-ai/refly | README/documentation is current enough for a first validation pass. ## 8. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | last_activity_observed missing ## 9. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium ## 10. 安全/权限坑 · 存在安全注意事项 - 严重度：medium - 证据强度：source_linked - 发现：No sandbox install has been executed yet; downstream must verify before user use. - 对用户的影响：用户安装前需要知道权限边界和敏感操作。 - 建议检查：转成明确权限清单和安全审查提示。 - 防护动作：安全注意事项必须面向用户前置展示。 - 证据：risks.safety_notes | github_repo:759799529 | https://github.com/refly-ai/refly | No sandbox install has been executed yet; downstream must verify before user use. ## 11. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium ## 12. 安全/权限坑 · 来源证据：Security findings in executable artifacts - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security findings in executable artifacts - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_6f5d63839cda4472b1c2f6cb1213ef5f | https://github.com/refly-ai/refly/issues/2276 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 13. 安全/权限坑 · 来源证据：v0.10.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.10.0 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_eb88a44b5350452dbe311722dc4d806b | https://github.com/refly-ai/refly/releases/tag/v0.10.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 14. 安全/权限坑 · 来源证据：v0.4.2 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.4.2 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_63bd65a5586242c8a4f52bad2217eb37 | https://github.com/refly-ai/refly/releases/tag/v0.4.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 15. 安全/权限坑 · 来源证据：v0.6.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.0 - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_dd65b4699b5d40b994cbe193f304e92e | https://github.com/refly-ai/refly/releases/tag/v0.6.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 16. 安全/权限坑 · 来源证据：v0.7.1 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.1 - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_99e4528065d24170b07db348f8e8a81f | https://github.com/refly-ai/refly/releases/tag/v0.7.1 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 17. 安全/权限坑 · 来源证据：v0.9.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.0 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_9db6c700d2e04aef8d4dadd155fe94d3 | https://github.com/refly-ai/refly/releases/tag/v0.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 18. 安全/权限坑 · 来源证据：v0.9.1 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.1 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_49d03f2d9bf4459fa86662b339f44b6f | https://github.com/refly-ai/refly/releases/tag/v0.9.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 19. 安全/权限坑 · 来源证据：v1.1.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_6417649c1639474087639d2d86d6c84c | https://github.com/refly-ai/refly/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 20. 安全/权限坑 · 来源证据：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_5e73e7f36609413094647d829f738f1e | https://github.com/refly-ai/refly/issues/2271 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 21. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | issue_or_pr_quality=unknown ## 22. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | release_recency=unknown