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 技术栈

3. 核心功能模块

3.1 Canvas 画布系统

Canvas 是 Refly 的核心功能模块，提供可视化的 AI 工作流编辑界面。

#### 3.1.1 画布交互配置

<ReactFlow
  {...flowConfig}
  selectionMode={SelectionMode.Partial}
  className="!bg-refly-bg-canvas"
  snapToGrid={true}
  snapGrid={[GRID_SIZE, GRID_SIZE]}
  // 统一鼠标和触控板手势配置
  panOnScroll={true}      // 启用滚动平移
  panOnScrollSpeed={0.5}  // 滚动速度
  panOnDrag={true}        // 启用拖拽平移
  zoomOnScroll={true}      // 启用滚轮缩放
  zoomOnPinch={true}      // 启用双指缩放
  zoomOnDoubleClick={false}
  selectNodesOnDrag={true}
  selectionOnDrag={true}
/>

#### 3.1.2 画布状态管理

Canvas 状态通过 Zustand store 统一管理：

// 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 代码工件节点

用于展示和编辑代码生成结果：

// packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx
<Renderer
  content={artifactData?.content || ''}
  type={artifactData?.type}
  title={artifactData?.title}
  language={artifactData?.language}
  onRequestFix={() => {}}
  showActions={false}
/>

#### 3.2.2 ActionStep 技能执行步骤

展示 AI 技能执行过程中的日志和状态：

// 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 组件功能

• 文件拖拽上传：支持拖拽文件到输入区域
• 上下文管理：管理已上传的文件列表
• 消息发送：支持 @ 提及特定工具集
• 多语言国际化：内置中文和英文提示文本

// 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 配置界面

// packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx
<section id="webhook-instructions" className="space-y-2 scroll-mt-4">
  <Text strong>{t('webhook.instructions')}</Text>
  <ul className="list-disc list-inside space-y-1 text-sm text-gray-600">
    <li>{t('webhook.instruction1')}</li>
    <li>{t('webhook.instruction2')}</li>
    <li>{t('webhook.instruction3')}</li>
  </ul>
</section>

3.5 模板市场与优惠券系统

Refly 包含完整的创作者激励机制，包括模板市场和折扣券系统。

#### 3.5.1 多语言邮件模板

// 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 邮件内容结构

3.6 调度系统 (Schedule)

Refly 支持工作流的定时调度功能，包含完整的调度限制和模态框交互。

#### 3.6.1 调度限制模态框

// packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx
<Modal
  title={t('schedule.limitReached.title') || 'Schedule Limit Reached'}
  open={scheduleLimitModalVisible}
  footer={[
    <Button key="cancel" onClick={() => setScheduleLimitModalVisible(false)}>
      {t('common.cancel') || 'Cancel'}
    </Button>,
    <Button key="view-schedules" type="primary" onClick={handleViewSchedulesClick}>
      {t('schedule.viewSchedules') || 'View Schedules'}
    </Button>,
  ]}
>
  <p>
    {t('schedule.limitReached.message') ||
      "You've reached the maximum number of scheduled workflows for your plan."}
  </p>
</Modal>

3.7 资源导入系统

支持从多种来源导入资源到工作流中。

// 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

适用于主要功能页面：

// packages/layout/README.md
function DetailPage() {
  return (
    <PrimaryPageLayout>
      {({ context, onContextChange }) => (
        <>
          <PrimaryPageLayoutContextUpdater
            title="Page Title"
            actions={<Button>Action Button</Button>}
            extra={<div>Extra Content</div>}
            deps={[]}
          />
          <div>Page Content</div>
        </>
      )}
    </PrimaryPageLayout>
  );
}

4.2 SecondaryPageLayout

适用于详情页面或子功能页面：

function DetailPage() {
  return (
    <SecondaryPageLayout>
      {({ context, onContextChange }) => (
        <>
          <SecondaryPageLayoutContextUpdater
            title="Detail Page Title"
            desc="Page description information"
            onBack={() => history.back()}
            actions={<Button>Save</Button>}
            deps={[]}
          />
          <div>Detail Page Content</div>
        </>
      )}
    </SecondaryPageLayout>
  );
}

5. CLI 命令行工具

Refly 提供命令行工具，支持终端操作和工作流管理。

5.1 主要命令

5.2 配置文件

CLI 配置存储在 ~/.refly/config.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 错误码

6. 国际化

Refly 支持多语言（i18n），使用 i18next 框架实现。

6.1 语言检测

系统自动检测用户语言环境：

// 检查是否为中文环境
const isChineseLocale = locale?.toLowerCase().startsWith('zh');

6.2 支持的语言

7. 工作流执行流程

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 采用 pnpm workspace 管理的 Monorepo 结构，主要分为以下几类包：

Monorepo 结构

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 包中，定义了多个独立的状态切片：

// 状态管理示例结构
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 - 分隔线

// Ant Design 组件使用示例
<Modal
  open={wideMode.isActive}
  footer={null}
  onCancel={handleCloseWideMode}
  width="85%"
/>

资料来源：packages/web-core/src/pages/page-share/index.tsx:50-70

#### Tailwind CSS

自定义样式使用 Tailwind CSS 配合 CSS 变量系统实现主题化：

// 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 实现多语言支持，所有用户界面文本通过翻译键引用：

// 国际化使用示例
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/ 目录下。

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 组件负责渲染代码片段和文档内容，支持多种渲染模式：

资料来源：packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:20-60

技能系统 (Skill Template)

上下文与工具调用

技能模板包 packages/skill-template 提供了 AI 代理执行任务的框架。核心类型定义如下：

// 上下文文件接口
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

工具调用元数据

// 工具调用元数据接口
export interface ToolCallMeta {
  callId: string;      // 用于通过 read_tool_result 检索
  toolName: string;   // 被调用的工具名称
}

CLI 工具

Refly CLI 工具位于 packages/cli 目录，提供命令行界面与 Refly 平台交互。

主要命令

配置文件

CLI 配置存储在 ~/.refly/config.json：

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

环境变量

资料来源：packages/cli/README.md:40-70

API 集成

Webhook 端点

Webhook 系统允许外部系统接收 Refly 工作流事件。请求体包含以下字段：

API 错误码

资料来源：packages/cli/README.md:80-95

资源管理

导入资源模块

资源导入功能使用专门的状态管理：

// 等待队列项接口
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 和创建时间：

// 资源元数据渲染
{resourceDetail?.data?.url && (
  <a href={resourceDetail?.data?.url} target="_blank">
    {resourceDetail?.data?.url}
  </a>
)}

资料来源：packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx:20-40

构建与部署

pnpm Workspace

项目使用 pnpm 管理依赖和 workspaces：

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Turborepo

使用 Turborepo 进行任务调度和构建缓存，提高增量构建效率。

技术栈总结

Refly 的技术栈设计体现了现代化前端开发的最佳实践，通过 Monorepo 架构实现了代码共享和独立部署的平衡，Zustand 提供了轻量且高效的状态管理，而模块化的组件设计则确保了系统的可维护性和可扩展性。

1. 架构概述

Refly 是一个模块化的 AI 工作空间平台，采用 Monorepo 架构组织代码。系统由多个独立但相互协作的包（packages）组成，通过 pnpm workspace 和 Turbo 构建系统进行统一管理。

1.1 核心设计原则

• 模块化设计：每个功能模块独立封装，通过明确定义的接口进行通信
• 状态管理集中化：使用 Zustand store 统一管理全局状态
• 组件懒加载：Modal 等大型组件采用动态导入（Lazy Loading）优化性能
• 多语言支持：内置 i18n 国际化方案，支持中英文切换

2. Monorepo 结构

项目采用 pnpm workspace 管理多包结构，核心配置通过 turbo.json 定义构建管道。

# pnpm-workspace.yaml 结构
packages:
  - 'apps/*'      # 应用程序层
  - 'packages/*'  # 共享包层

2.1 应用层（apps）

2.2 共享包层（packages）

3. 前端架构

3.1 页面布局系统

Refly 的前端采用分层布局架构，支持多种页面类型：

// 布局组件使用示例
<PrimaryPageLayout>
  {({ context, onContextChange }) => (
    <PrimaryPageLayoutContextUpdater
      title="页面标题"
      actions={<Button>操作按钮</Button>}
      extra={<div>额外内容</div>}
      deps={[]}
    />
  )}
</PrimaryPageLayout>

布局类型说明：

资料来源：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 集中注册：

<LazyModal
  visible={importResourceModalVisible}
  loader={() =>
    import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({
      default: m.ImportResourceModal,
    }))
  }
/>

已集成的 Modal 组件：

资料来源：packages/web-core/src/components/layout/ModalContainer.tsx

4. 状态管理

4.1 Store 架构

系统使用 Zustand 进行状态管理，主要 store 位于 packages/stores/src/stores/ 目录。

ImportResource Store 结构：

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：

资料来源：packages/stores/src/stores/import-resource.ts

5. 技能（Skill）系统

5.1 上下文模型

Skill 系统使用上下文文件（ContextFile）表示输入输出资源：

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 工具调用元数据

export interface ToolCallMeta {
  callId: string;      // 工具调用 ID，用于读取结果
  toolName: string;    // 被调用的工具名称
}

5.3 Skill 安装与卸载

Skill 通过命令行工具管理：

# 安装 Skill
refly skill install <skill-name>

# 卸载 Skill
refly skill uninstall <skill-name>

Skill 文件安装位置：

• ~/.claude/skills/refly/SKILL.md
• ~/.claude/skills/refly/references/
• ~/.claude/commands/refly-*.md

资料来源：packages/cli/README.md

6. Webhook 集成

6.1 Webhook 配置界面

<WebhookConfigTab
  data={webhookData}
  onChange={setWebhookData}
  webhookUrl={webhookUrl}
  tabItems={tabItems}
/>

6.2 Webhook 错误码

资料来源：packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx

7. Canvas 架构

7.1 节点预览组件

Canvas 中的节点预览支持 Skill 响应展示：

<ActionStep
  step={step}
  logs={logs}
  status={status}
  onCollapse={setCollapsed}
/>

<ReasoningContent
  resultId={resultId}
  reasoningContent={reasoningContent}
  sources={sources}
  step={step}
  status={status}
/>

7.2 Artifact 渲染器

<ArtifactRenderer
  rendererType={rendererType}
  content={content}
  title={title}
  language={language}
  status={status}
  isMinimap={isMinimap}
  isFullscreen={isFullscreen}
/>

渲染状态：

8. Copilot 集成

Pure Copilot 是系统的主要交互入口，支持文件拖拽和上下文管理：

<PureCopilot
  source="frontPage"
  onSendMessage={handleSendMessage}
  onFileUpload={handleFileUpload}
/>

数据交互流程：

1. 用户输入查询 → ChatInput 组件
2. 文件拖拽 → FileList 组件处理上传
3. Mention 插入 → 工具/资源/代理选择
4. 上下文构建 → ContextItem 添加

9. 配置管理

9.1 CLI 配置

配置文件位置：~/.refly/config.json

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

9.2 环境变量

10. 国际化

系统支持多语言切换，语言代码通过 i18n 库管理：

const language = i18n.languages?.[0]; // 'en' | 'zh'

翻译资源使用命名空间（namespace）组织：

• common: 通用文本
• skillLog: 技能日志
• schedule: 调度相关
• integration: 集成文档

11. 架构流程图

11.1 组件加载流程

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 执行流程

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 资源导入流程

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 国际化能力

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 架构关系图

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 中。主要实体包括：

3.2 Context 文件结构

在 Skill 执行和调度上下文中，系统使用 ContextFile 结构管理文件资源：

// 资料来源：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 工具获取完整内容：

// 资料来源：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 配置界面：

// 资料来源：packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx
// 功能包括：
// - Tab 切换 (webhookConfigTabs)
// - 使用说明展示
// - 集成文档链接

4.3 Webhook 请求体结构

Webhook 端点的请求体采用 Schema 定义：

4.4 错误码定义

错误码通过 apiDocsData.errorCodes 动态渲染，支持国际化文本。

5. 认证与配置

5.1 CLI 认证配置

CLI 工具使用配置文件存储认证信息：

// 资料来源：packages/cli/README.md
{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

5.2 环境变量

5.3 错误码体系

CLI 和 API 共享统一的错误码体系：

6. 调度功能

6.1 调度模块概述

调度模块允许用户配置定时执行的工作流任务。系统提供调度限制管理，超出限制时显示提示模态框。

6.2 调度限制管理

// 资料来源：packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx
// 功能包括：
// - 调度数量限制检测
// - 限制达到提示
// - 调度列表管理入口

6.3 调度状态管理

调度状态通过 Zustand Store 管理：

// 资料来源：packages/stores/src/stores/import-resource.ts
// 等待列表操作
addToWaitingList: (item: WaitingListItem) => void;
removeFromWaitingList: (id: string) => void;
updateWaitingListItem: (id: string, updates: Partial<...>) => void;

7. 导入资源模块

7.1 导入流程

导入资源模块处理文件、图片等资源的导入与管理：

// 资料来源：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 状态操作方法

8. 工具调用与结果读取

8.1 工具调用元数据

系统在 Agent 执行过程中记录工具调用元数据：

// 资料来源：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 标签格式的工具调用：

// 资料来源：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 = /<tool_use[\s\S]*?<\/tool_use>/g;

8.3 Agent 结果结构

// 资料来源：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 文档标签页结构

集成文档系统通过模态框展示，包含多个标签页：

// 资料来源：packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx
// 标签页类型：webhook | api | skill

9.2 Skill 文档标签页

Skill 文档提供安装和卸载指南：

// 资料来源：packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx
// 安装步骤：
// 1. 初始化 refly
// 2. 安装 skill
// 3. 配置环境

10. 邮件模板模块

10.1 凭证邮件

API 模块包含用于发送凭证和奖励通知的邮件模板：

// 资料来源：apps/api/src/modules/voucher/voucher-email-templates.ts
// 模板类型：
// - 创作者奖励通知
// - 专属折扣通知

邮件模板使用内联 HTML 样式，支持深色模式适配。

11. 页面分享功能

11.1 分享页面布局

分享页面支持窄屏和宽屏两种模式：

// 资料来源：packages/web-core/src/pages/page-share/index.tsx
// 宽屏模式特点：
// - Modal 宽度 85%
// - 内容区域可滚动
// - 关闭按钮位于右上角

11.2 内容块渲染

分享页面使用内容块组件渲染工作流节点内容，支持动态 ID 匹配和空状态展示。

12. 快速开始

12.1 CLI 基本命令

# 登录认证
refly login

# 初始化项目
refly init

# 启动 Builder
refly builder start --name "workflow-name"

# 验证工作流
refly builder validate

# 提交工作流
refly builder commit

12.2 API 调用示例

# 获取认证信息
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 源码目录
• 数据库 Schema
• CLI 文档
• 集成文档组件

概述

工作流系统（Workflow System）是 Refly 平台的核心组件，负责管理和自动化复杂任务的执行流程。该系统通过有向无环图（DAG）结构组织任务节点，支持变量传递、条件执行、定时调度以及外部集成（如 Webhook）。

核心职责：

• 提供可视化的工作流编辑和配置能力
• 管理任务的执行状态和生命周期
• 支持工作流的定时调度和即时运行
• 处理任务间的依赖关系和数据流转
• 集成外部工具集（Toolsets）扩展功能

资料来源：packages/web-core/src/index.ts:1-50

架构设计

系统组件架构

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

graph LR
    subgraph 任务定义
        T1[Task 1: 任务节点]
        T2[Task 2: 任务节点]
        T3[Task 3: 任务节点]
    end
    
    T1 --> T2
    T1 --> T3
    T2 --> T3

任务节点结构

资料来源：packages/skill-template/src/prompts/templates/copilot-agent-system.md:1-30

核心接口与类型定义

ContextFile 上下文文件

export interface ContextFile {
  name: string;      // 文件名称
  fileId: string;    // 文件唯一标识
  type: string;      // 文件类型
  summary: string;   // 文件摘要
  content: string;   // 文件内容
  variableId?: string;    // 关联变量ID
  variableName?: string;  // 关联变量名称
}

ContextFileMeta 元数据版本

/**
 * 仅包含元数据，不含内容
 * 用于减少 token 使用量，LLM 通过 read_file 获取完整内容
 */
export interface ContextFileMeta {
  name: string;
  fileId: string;
  type: string;
  summary: string;
  variableId?: string;
  variableName?: string;
}

AgentResult 代理执行结果

export interface AgentResult {
  resultId: string;      // 结果唯一ID
  title: string;          // 结果标题
  content: string;       // 结果内容
  outputFiles: ContextFileMeta[];  // 输出文件元数据
}

ToolCallMeta 工具调用元数据

export interface ToolCallMeta {
  callId: string;    // 工具调用ID，用于检索结果
  toolName: string;  // 被调用工具的名称
}

资料来源：packages/skill-template/src/scheduler/utils/context.ts:1-60

工作流执行状态

节点执行状态

// 执行状态展示逻辑
{(nodeExecution.status === 'waiting' || nodeExecution.status === 'executing') && (
  <div className="space-y-2">
    <div className="text-xs font-semibold text-refly-text-1 uppercase tracking-wide">
      {t('workflowApp.executionStatus', 'Execution Status')}
    </div>
    <div className="bg-refly-bg-control-z0 rounded-lg p-3 space-y-2">
      <div className="flex items-start gap-2">
        <div className="text-xs font-medium text-refly-text-2 min-w-0 flex-shrink-0">
          {t('workflowApp.status', 'Status')}:
        </div>
        <div className="text-xs text-refly-text-1 break-words">
          {t(`canvas.workflow.run.nodeStatus.${nodeExecution.status}`, {
            defaultValue: nodeExecution.status,
          })}
        </div>
      </div>
    </div>
  </div>
)}

错误处理

{nodeExecution.status === 'failed' && (
  <div className="space-y-2">
    <div className="flex items-center gap-2">
      <span className="text-sm font-semibold text-refly-func-danger-default">
        {t('canvas.workflow.run.executionFailed')}
      </span>
    </div>
    <div className="text-sm text-refly-text-1 bg-refly-Colorful-red-light rounded-lg p-3">
      {errorMessage}
    </div>
  </div>
)}

资料来源：packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:1-50

工作流运行管理

工作流运行预览

export const WorkflowRunPreview = memo(WorkflowRunPreviewComponent);

// 预览上下文配置
<LastRunTabContext.Provider value={previewContextValue}>
  <ProductCard
    file={currentFile}
    classNames="w-full h-full"
    source="preview"
    onAddToFileLibrary={(file) => handleAddToFileLibrary(file, 'runlog')}
  />
</LastRunTabContext.Provider>

执行流程图

graph TD
    Start[开始运行] --> CheckDeps{检查依赖}
    CheckDeps -->|依赖满足| RunNode[执行节点]
    CheckDeps -->|依赖未满足| Wait[等待中]
    RunNode -->|成功| NextCheck{还有后续节点?}
    RunNode -->|失败| ErrorLog[记录错误]
    NextCheck -->|是| WaitForDeps[等待前置完成]
    NextCheck -->|否| Complete[工作流完成]
    WaitForDeps --> RunNode
    ErrorLog --> NextCheck

工作流变量表单

<WorkflowRunForm
  workflowVariables={workflowVariables ?? []}
  onSubmitVariables={onSubmitVariables}
  loading={loading ?? false}
  executionId={executionId}
  workflowStatus={workflowStatus}
  isPolling={isPolling}
  pollingError={pollingError}
  isRunning={isRunning}
  onRunningChange={setIsRunning}
  canvasId={canvasId}
  creditUsage={isCreditUsageLoading || hasIncompleteNodes 
    ? null 
    : (creditUsageData?.data?.total ?? 0)}
/>

资料来源：packages/ai-workspace-common/src/components/canvas/workflow-run/preview.tsx:1-50

定时调度系统

调度服务

调度系统允许用户配置工作流的自动执行时间，支持：

• 一次性执行：在指定时间运行工作流
• 循环执行：按 cron 表达式或固定间隔重复执行
• 失败通知：工作流执行失败时发送邮件通知

邮件通知模板

// 失败通知邮件
const subject = 'Scheduled workflow failed to run';
const html = wrapEmail(
  subject,
  `
  <h1>Hi ${data.userName},</h1>
  <p>Your scheduled workflow <strong>"${data.scheduleName}"</strong> failed during its most recent run.</p>
  
  <div>Run details</div>
  <ul>
    <li>Status: <span style="color: #F04438;">Failed</span></li>
    <li>Run time: ${data.scheduledAt}</li>
    <li>Next scheduled run: ${data.nextRunTime}</li>
  </ul>
  `
);

资料来源：apps/api/src/modules/schedule/schedule-email-templates.ts:1-50

Webhook 集成

Webhook 配置标签页

<section id="webhook-instructions" className="space-y-2 scroll-mt-4">
  <Text strong>{t('webhook.instructions')}</Text>
  <ul className="list-disc list-inside space-y-1 text-sm text-gray-600">
    <li>{t('webhook.instruction1')}</li>
    <li>{t('webhook.instruction2')}</li>
    <li>{t('webhook.instruction3')}</li>
  </ul>
</section>

Webhook 错误码

错误码表格组件：

<table className={tableClassName}>
  <thead>
    <tr>
      <th className={tableHeaderCellClassName}>{t('integration.api.errorCode')}</th>
      <th className={tableHeaderCellClassName}>{t('integration.api.errorStatus')}</th>
      <th className={tableHeaderCellClassName}>{t('integration.api.errorMessage')}</th>
      <th className={tableHeaderCellClassName}>{t('integration.api.errorDescription')}</th>
    </tr>
  </thead>
  <tbody>
    {apiDocsData.errorCodes.map((error) => (
      <tr key={`webhook-error-${error.code}`}>
        <td className={tableCellClassName}>
          <code className={inlineCodeClassName}>{error.code}</code>
        </td>
        <td className={tableCellClassName}>{error.httpStatus ?? '-'}</td>
      </tr>
    ))}
  </tbody>
</table>

资料来源：packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx:1-30

Skill Package 工作流导出

DTO 定义

export interface CreateSkillPackageDto {
  name: string;
  version: string;
  description?: string;
  icon?: SkillIconDto;
  triggers?: string[];
  tags?: string[];
  inputSchema?: Record<string, unknown>;
  outputSchema?: Record<string, unknown>;
}

export interface CreateSkillPackageCliDto extends CreateSkillPackageDto {
  workflowId?: string;
  workflowIds?: string[];
  workflowQuery?: string;
  workflowSpec?: {
    nodes?: Array<Record<string, unknown>>;
    edges?: Array<Record<string, unknown>>;
  };
  workflowName?: string;
  workflowDescription?: string;
  workflowVariables?: Array<Record<string, unknown>>;
  noWorkflow?: boolean;
}

响应结构

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<string, unknown>;
  outputSchema?: Record<string, unknown>;
  installationId?: string;
}

资料来源：apps/api/src/modules/skill-package/skill-package.dto.ts:1-80

CLI 命令行接口

基础命令

Builder 模式

增量构建工作流：

refly builder start --name "workflow-name"    # 启动构建会话
refly builder add-node --node '<json>'        # 添加节点
refly builder update-node --id "<nodeId>" --patch '<json>'  # 更新节点
refly builder remove-node --id "<nodeId>"     # 删除节点
refly builder connect --from "<nodeId>" --to "<nodeId>"     # 连接节点
refly builder disconnect --from "<nodeId>" --to "<nodeId>" # 断开连接
refly builder status                           # 查看状态
refly builder graph [--ascii]                 # 查看图结构
refly builder validate                        # 验证工作流
refly builder commit                          # 提交工作流
refly builder abort                           # 中止构建

工作流管理

# 创建工作流
refly workflow create --name "<name>" --spec '<json>'

# 列出工作流
refly workflow list [--limit N]

# 获取工作流详情
refly workflow get <workflowId>

# 编辑工作流
refly workflow edit <workflowId> --ops '<json>'

# 删除工作流
refly workflow delete <workflowId>

工作流执行

# 运行工作流
refly workflow run <workflowId> [--input '<json>']

# 查看运行状态
refly workflow run-status <runId>

# 中止运行
refly workflow abort <runId>

Builder 状态机

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

错误码参考

资料来源：packages/cli/README.md:1-100

页面路由导出

工作流相关的页面组件通过懒加载方式导出：

// ========== 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：

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

环境变量

资料来源：packages/cli/README.md:1-100

工具集依赖检查

工具依赖检查器组件

export const ToolsDependencyChecker = ({
  canvasData,
  externalOpen,
  highlightInstallButtons,
  onOpenChange,
  creditUsage,
}: {
  canvasData?: RawCanvasData;
  externalOpen?: boolean;
  highlightInstallButtons?: boolean;
  onOpenChange?: (open: boolean) => void;
  creditUsage?: number;
}) => {
  // 组件实现...
};

工具安装处理

{!isInstalled && isLogin && (
  <Button
    size="middle"
    className="custom-configure-button flex-shrink-0 md:text-sm"
    loading={isPolling || isOpening}
    disabled={isPolling || isOpening}
    onClick={() => handleInstallTool(toolset)}
  >
    {isPolling || isOpening
      ? t('canvas.richChatInput.authorizing', '授权中...')
      : t('canvas.workflowDependency.goToInstall')}
  </Button>
)}

资料来源：packages/ai-workspace-common/src/components/canvas/tools-dependency/index.tsx:1-50

总结

工作流系统是 Refly 平台的核心能力，通过以下特性实现复杂任务的自动化：

1. DAG 执行模型：基于有向无环图的任务编排，确保正确的执行顺序
2. 灵活的工具集成：支持多种工具集扩展功能
3. 完善的生命周期管理：支持创建、编辑、验证、提交和运行
4. 定时调度能力：支持 cron 表达式和循环执行
5. Webhook 集成：便于与外部系统对接
6. 丰富的 CLI 支持：支持本地开发和调试

概述

工具系统（Tool System）是 Refly 平台的核心能力之一，它为 AI Agent 提供了与外部世界交互的桥梁。通过工具系统，Agent 可以执行代码、调用 API、操作文件、发送 Webhook 等，从而完成复杂的自动化任务。

工具系统的设计遵循以下核心原则：

• 模块化：工具按功能分类为工具集（Toolsets）和独立工具（Tools）
• 按需加载：通过元数据机制减少上下文大小，LLM 按需读取完整内容
• 权限控制：支持工具授权管理，确保安全执行
• 类型安全：完整的 TypeScript 类型定义，支持国际化描述

资料来源：packages/skill-template/src/scheduler/utils/context.ts:20-30

核心类型定义

工具调用元数据

工具调用元数据用于在 Agent 结果中提供工具调用的摘要信息，而不需要包含完整的输入输出内容：

interface ToolCallMeta {
  /** 工具调用 ID，用于通过 read_tool_result 检索 */
  callId: string;
  /** 被调用工具的名称 */
  toolName: string;
}

资料来源：packages/skill-template/src/scheduler/utils/context.ts:30-38

提及项类型

在用户输入界面中，工具和工具集通过提及（Mention）机制进行选择：

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）是相关工具的集合，支持以下功能：

资料来源：packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts:40-70

工具选择流程

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 配置界面中，用户可以添加或移除工具集：

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 标签格式：

// 匹配 Markdown 代码块格式和独立 XML 标签
const TOOL_USE_BLOCK_REGEX = /\n*```tool_use(?:_result)?[^\n]*\n[\s\S]*?```\n*/g;
const TOOL_USE_TAG_REGEX = /<tool_use[\s\S]*?<\/tool_use>/g;

支持的格式：

资料来源：packages/skill-template/src/scheduler/utils/context.ts:1-10

Skill 文档系统

Skill 安装

Skill 文档提供了标准的安装流程：

# 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 卸载

# Skill 卸载命令
refly skill uninstall <skill-name>

卸载过程会清理相关配置和资源文件。

Webhook 集成

Webhook 配置标签页

Webhook 配置界面包含以下区域：

请求体字段定义

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

工具与上下文交互

上下文项创建

从提及项创建上下文项时，系统会提取关键元数据：

const contextItem: IContextItem = {
  entityId: item.entityId || item.nodeId || item.variableId || item.name,
  resourceType: item.resourceType,
  resourceMeta: item.metadata?.resourceMeta,
  variableType: 'tool',
};

上下文项管理

资料来源：packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx:1-100

工具系统状态流

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 执行时加载工具]

错误处理

工具调用错误

当工具执行失败时，系统会记录错误日志：

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',
}))}

错误状态分类

资料来源：packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:1-60

国际化支持

工具系统全面支持多语言，通过 descriptionDict 配置：

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 能够执行各种复杂的外部操作任务。

系统概述

Refly 平台的认证与授权系统是一套完整的安全机制，支持多种认证方式以满足不同用户场景的需求。该系统涵盖了前端登录界面、后端 API 认证以及 CLI 工具的身份验证三大核心领域。

核心认证方式

概述

Canvas（画布）组件是 refly 平台的核心编辑器组件，负责构建和管理知识工作空间的可视化编辑界面。该组件为用户提供了一个灵活的节点式编辑环境，支持多种类型的内容节点、实时协作、工作流编排以及与外部系统的集成。

画布组件位于 packages/ai-workspace-common/src/components/canvas/ 目录下，采用模块化架构设计，包含节点管理、画布渲染、工具栏、文档预览、工作流运行等多个子模块。

架构设计

模块层次结构

┌─────────────────────────────────────────────────────────────┐
│                    Canvas 画布组件                           │
├─────────────────────────────────────────────────────────────┤
│  顶层组件                                                    │
│  ├── Canvas（主容器）                                        │
│  ├── TopToolbar（顶部工具栏）                                │
│  └── StatusBar（状态栏）                                     │
├─────────────────────────────────────────────────────────────┤
│  节点组件                                                    │
│  ├── AgentNode（智能体节点）                                 │
│  ├── DocumentNode（文档节点）                                │
│  ├── WorkflowNode（工作流节点）                              │
│  ├── ArtifactNode（产物节点）                                │
│  └── SkillResponseNode（技能响应节点）                       │
├─────────────────────────────────────────────────────────────┤
│  交互组件                                                    │
│  ├── RichChatInput（富文本聊天输入）                         │
│  ├── Copilot（副驾驶助手）                                   │
│  └── PureCopilot（纯净副驾驶）                               │
├─────────────────────────────────────────────────────────────┤
│  工作流运行                                                 │
│  ├── WorkflowNodePanel（工作流节点面板）                    │
│  ├── ActionStep（执行步骤）                                  │
│  └── ArtifactRenderer（产物渲染器）                          │
└─────────────────────────────────────────────────────────────┘

核心数据流

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 主组件提供以下核心功能：

节点组件体系

节点组件是画布上的核心编辑单元，每种节点类型对应不同的功能和交互模式。

#### AgentNode 智能体节点

AgentNode 是画布中用于表示 AI 智能体的节点组件，封装了与大语言模型交互的核心逻辑。

组件引用: packages/ai-workspace-common/src/components/canvas/nodes/index.ts

// 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

// 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[];  // 选中的工具集
}

工作流节点面板包含以下标签页：

ArtifactRenderer 产物渲染器

ArtifactRenderer 负责渲染代码片段、文档和其他产物内容，支持全屏模式和缩略图预览。

组件位置: packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx

// ArtifactRenderer 核心属性
interface ArtifactRendererProps {
  content: string;           // 内容文本
  type: string;              // 内容类型
  title?: string;            // 标题
  language?: string;         // 编程语言
  readonly?: boolean;        // 只读模式
  purePreview?: boolean;     // 纯净预览模式
  onRequestFix?: () => void; // 修复请求
  width?: string;            // 宽度
  height?: string;           // 高度
}

ArtifactRenderer 支持两种渲染模式：

渲染器通过 memo 的第二个参数实现渲染优化，仅在关键元数据变化时重新渲染：

(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

// RichChatInput 核心接口
interface RichChatInputProps {
  readonly?: boolean;
  handleSendMessage: () => void;
  onUploadImage?: (file: File) => Promise<void>;
  onUploadMultipleImages?: (files: File[]) => Promise<void>;
  onFocus?: () => void;
  nodeId?: string;
  placeholder?: string;
  mentionPosition?: MentionPosition;
}

RichChatInput 暴露以下方法供父组件调用：

export interface RichChatInputRef {
  focus: () => void;                    // 获取输入框焦点
  insertAtSymbol?: () => void;          // 插入 @ 符号
}

组件内部集成了以下功能模块：

资料来源：rich-chat-input/index.tsx:32-50

ActionStep 执行步骤组件

ActionStep 组件用于展示技能执行的中间步骤和推理过程。

组件位置: packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx

// ReasoningContent 组件属性
interface ReasoningContentProps {
  resultId: string;
  reasoningContent: string;
  资料来源：Source[];
  step: ActionStep;
  status: ActionStatus;
}

ActionStep 支持以下状态转换：

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 提供全局状态管理，主要包括：

interface CanvasContextValue {
  canvasId: string;           // 画布唯一标识
  readonly?: boolean;         // 只读模式标识
  // 其他上下文属性
}

节点状态管理

节点状态通过 useAgentNodeManagement hook 进行管理：

const { query, setQuery, setContextItems, setSelectedToolsets } =
  useAgentNodeManagement(nodeId);

工作流执行状态

工作流节点面板管理以下执行状态：

国际化支持

Canvas 组件全面支持国际化，通过 react-i18next 实现多语言切换。

关键翻译键

资料来源：ArtifactRenderer.tsx:45-70 和 workflow-node-panel.tsx:44

样式与主题

动态样式类

Canvas 组件使用 Tailwind CSS 实现响应式样式，并支持亮色/暗色主题切换：

className={`h-full bg-white dark:bg-[var(--refly-bg-content-z2)] 
  ${!isFullscreen ? 'rounded px-4 pb-4' : 'w-full'}`}

主题变量

组件配置选项

PrimaryPageLayout 配置

画布页面使用 PrimaryPageLayout 作为基础布局：

SecondaryPageLayout 配置

详情页面使用 SecondaryPageLayout：

资料来源：packages/layout/README.md

性能优化

Memo 优化策略

ArtifactRenderer 通过 memo 的自定义比较函数实现精细化的重渲染控制：

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
    );
  }
);

懒加载策略

工作流节点面板支持懒加载标记：

onChange={(activeKeys) => {
  if (Array.isArray(activeKeys) && activeKeys.includes('agent')) {
    agentNodesLazy.markAsRendered(node.id);
  }
}}

相关子模块

文档组件

文档组件为画布提供富文本编辑能力：

// packages/ai-workspace-common/src/components/document/index.tsx
<DocumentProvider docId={docId} shareId={shareId} readonly={readonly}>
  <DocumentBody docId={docId} nodeId={nodeId} />
  {!canvasReadOnly && <StatusBar docId={docId} />}
</DocumentProvider>

集成文档模块

画布支持通过 IntegrationDocsModal 展示外部集成文档：

// packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx
<IntegrationDocsModal
  open={open}
  onClose={onClose}
  canvasId={canvasId}
  tab={tab}
/>

Webhook 配置

Webhook 功能通过 WebhookConfigTab 提供配置界面：

资料来源：webhook-config-tab.tsx 和 webhook-docs-tab.tsx

总结

Canvas 画布组件是 refly 平台的核心交互界面，采用模块化、组件化的架构设计。通过 AgentNode、WorkflowNode、ArtifactRenderer 等核心组件的协同工作，为用户提供了强大的知识编排和工作流自动化能力。组件支持精细化的状态管理、国际化、主题切换和性能优化，是构建现代 AI 工作空间的重要基础设施。

概述

富文本编辑器系统（Rich Text Editor System）是 refly 平台的核心组件之一，负责管理和渲染多种类型的内容，包括文档编辑、代码片段、思维导图、HTML内容等。该系统采用了基于 Tiptap/ProseMirror 的编辑器架构，支持实时协作和只读预览两种模式。

编辑器的设计理念是将内容创作与内容展示分离，通过统一的渲染接口处理不同类型的内容，同时提供灵活的状态管理和上下文隔离机制。

系统架构

核心组件层次

富文本编辑器系统采用分层架构设计，主要包含以下层次：

架构流程图

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 是文档编辑器的核心入口组件，封装了文档编辑的主要逻辑：

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 (
      <DocumentProvider docId={docId} shareId...>
        {/* Editor Components */}
      </DocumentProvider>
    );
  }
);

关键特性：

• 基于 docId 的文档隔离管理
• 组件卸载时自动清理状态，防止内存泄漏
• 支持 shareId 用于文档分享场景
• 与 Canvas 上下文集成，继承只读状态

编辑模式分支

文档编辑器根据 readonly 属性决定渲染模式：

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 是统一的内容渲染入口，支持多种内容类型的分发渲染：

case 'application/refly.artifacts.mindmap': {
  return (
    <MindMapRenderer
      content={content}
      width={width}
      height={height}
      readonly={readonly}
      onChange={memoizedMindMapOnChange}
    />
  );
}

case 'text/html': {
  return (
    <HTMLRenderer
      htmlContent={content}
      width={width}
      height={height}
      showActions={showActions}
      purePreview={purePreview}
    />
  );
}

思维导图渲染

MindMapRenderer 是专门用于思维导图内容的渲染组件，提供以下功能：

• 缩放控制：支持自定义宽高
• 只读/编辑切换：通过 readonly 属性控制
• 变更回调：通过 onChange 回调通知内容更新
• 尺寸自适应：根据容器自动调整

HTML 渲染

HTMLRenderer 处理原生 HTML 内容，支持以下特性：

• 预览模式：通过 purePreview 控制预览样式
• 操作按钮：通过 showActions 显示操作按钮
• 尺寸控制：支持自定义宽高参数

ArtifactRenderer 制品渲染器

ArtifactRenderer 是专门处理 AI 生成制品的组件，提供增强的预览体验：

<div className="transform scale-[0.5] origin-top-left w-[200%] h-[200%] overflow-hidden bg-white dark:bg-gray-900 rounded shadow-sm">
  <Renderer
    purePreview
    content={content}
    type={currentType}
    title={title}
    language={artifactData?.language || language}
    readonly
    onRequestFix={handleRequestFix}
    width="100%"
    height="100%"
  />
</div>

制品渲染特性：

• 小地图预览模式：使用 scale-[0.5] 和 w-[200%] 实现缩略图效果
• 主题适配：自动适配亮色/暗色主题
• 语言感知：根据制品类型显示对应语法高亮
• 修复请求：支持 onRequestFix 回调处理修复请求

状态管理

DocumentStore

文档状态管理采用 Zustand store 模式，主要职责包括：

• 文档内容状态：存储当前文档的内容数据
• 编辑器状态：跟踪编辑器的激活状态
• 清理机制：提供 resetState 方法用于组件卸载时清理

const { resetState } = useDocumentStoreShallow((state) => ({
  resetState: state.resetState,
}));

useEffect(() => {
  return () => {
    resetState(docId);
  };
}, []);

DocumentProvider 上下文

DocumentProvider 组件为子组件提供文档上下文信息，包括：

• docId：文档唯一标识
• shareId：分享标识（可选）
• readonly：只读状态
• nodeId：节点标识

渲染状态与条件

加载状态处理

渲染器组件支持完整的加载状态管理：

if (isLoading) {
  return (
    <div className="flex h-full w-full grow items-center justify-center">
      <div className="text-gray-500">
        {t('pages.components.artifact.loading', {
          type: rendererType === 'document'
            ? t('common.document').toLowerCase()
            : t('pages.components.artifact.code').toLowerCase(),
        })}
      </div>
    </div>
  );
}

生成状态处理

对于正在生成的内容（如 AI 生成），渲染器显示生成中的状态：

if (status === 'generating') {
  return (
    <div className="flex h-full w-full items-center justify-center">
      <div className="text-gray-500">
        {t('pages.components.artifact.generating', { type: '' })}
      </div>
    </div>
  );
}

空内容状态

当没有选中内容时，显示提示信息：

<span className="text-gray-400">
  {t('pages.components.artifact.notSelected', {
    type: rendererType === 'document'
      ? t('common.document').toLowerCase()
      : t('pages.components.artifact.code').toLowerCase(),
  })}
</span>

组件 Memoization 优化

Renderer 组件使用自定义相等性检查实现高效的 memoization：

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 变更时的精确控制

主题与样式适配

编辑器系统支持亮色/暗色主题自动适配：

className={`h-full bg-white dark:bg-[var(--refly-bg-content-z2)]`}

样式变量映射：

资源预览集成

编辑器系统与资源视图组件集成，支持文档、元数据展示：

{resourceDetail?.data?.url && (
  <a
    className="site-intro-site-url no-underline text-[#0E9F77]"
    href={resourceDetail?.data?.url}
    target="_blank"
    rel="noreferrer"
  >
    {resourceDetail?.data?.url}
  </a>
)}

资源元数据组件提供：

• 资源标题显示
• URL 链接展示
• 创建时间展示（相对时间格式）
• 多语言时间格式化

API 参考

DocumentEditor Props

Renderer Props

总结

富文本编辑器系统是 refly 平台内容创作的核心基础设施，通过分层架构实现了编辑功能与渲染逻辑的解耦。系统支持多种内容类型的统一处理，提供了良好的状态管理和性能优化机制，同时适配亮色/暗色主题，满足不同使用场景的需求。

该系统的设计遵循了以下原则：

1. 关注点分离：编辑逻辑与渲染逻辑独立
2. 组件化：每个功能模块都是可复用的组件
3. 状态隔离：基于 docId 的状态隔离机制
4. 性能优先：通过 memoization 减少不必要的重渲染
5. 主题适配：统一的深色模式支持

概述

模型提供者系统（Model Provider System）是 Refly 平台的核心模块之一，负责管理与协调各类大语言模型（LLM）的接入、调用与路由。该系统通过统一的抽象层，为上层应用提供一致的模型调用接口，同时支持多模型提供商的动态切换与自动路由。

系统的设计目标包括：

• 统一抽象：为不同模型提供商提供一致的调用接口
• 动态路由：根据任务需求自动选择最合适的模型
• 配置管理：集中管理模型提供商的配置与凭证
• 成本优化：支持模型混用以优化成本与性能

Pitfall Log / 踩坑日志

项目：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