{ "canonical_name": "refly-ai/refly", "compilation_id": "pack_a1af753e234f4c9e8025d58e3767481c", "created_at": "2026-05-13T12:12:43.155269+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm install -g @powerformer/refly-cli` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm install -g @powerformer/refly-cli", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_f616d7614e744372951db9fcaf191c94" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_c8a1feb3c1612a3d65eb56dde775abfe", "canonical_name": "refly-ai/refly", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/refly-ai/refly", "slug": "refly", "source_packet_id": "phit_c045e1d55da444589b61fbdfb502931e", "source_validation_id": "dval_80c9c829c5164f4ca671680050d052f2" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 claude的用户", "github_forks": 713, "github_stars": 7292, "one_liner_en": "The first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex & more. Build Clawdbot 🦞· APIs for Lovable · Bots for Slack & Lark/Feishu · Skills are infrastructure, not prompts.", "one_liner_zh": "The first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex & more. Build Clawdbot 🦞· APIs for Lovable · Bots for Slack & Lark/Feishu · Skills are infrastructure, not prompts.", "primary_category": { "category_id": "software-development", "confidence": "high", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, git, cli" }, "target_user": "使用 claude, claude_code, cursor 等宿主 AI 的用户", "title_en": "refly", "title_zh": "refly 能力包", "visible_tags": [ { "label_en": "Knowledge Retrieval", "label_zh": "知识检索", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-knowledge-retrieval", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_c045e1d55da444589b61fbdfb502931e", "page_model": { "artifacts": { "artifact_slug": "refly", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm install -g @powerformer/refly-cli", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/refly-ai/refly#readme", "verified": true } ], "display_tags": [ "知识检索", "知识库问答", "流程自动化", "节点式流程编排", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 claude的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "The first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex & more. Build Clawdbot 🦞· APIs for Lovable · Bots for Slack & Lark/Feishu · Skills are infrastructure, not prompts." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "claude, claude_code, cursor", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inquiry", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_0805b730bc2b4c5787cea36e55a118cd | https://github.com/refly-ai/refly/issues/2088 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inq…", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.5.0", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_0c49752e8b10439aa5eda23446563b9f | https://github.com/refly-ai/refly/releases/tag/v0.5.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.5.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.0", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_9680da63e17747a5afdc985701b56111 | https://github.com/refly-ai/refly/releases/tag/v0.7.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.7.0", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.0", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_bde62a80a1994e2b89a9741dabace272 | https://github.com/refly-ai/refly/releases/tag/v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.8.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | github_repo:759799529 | https://github.com/refly-ai/refly | host_targets=claude, claude_code, cursor" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_91f612b63eef439ba150bafe81966117 | https://github.com/refly-ai/refly/issues/2278 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:759799529 | https://github.com/refly-ai/refly | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "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." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security findings in executable artifacts", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_6f5d63839cda4472b1c2f6cb1213ef5f | https://github.com/refly-ai/refly/issues/2276 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Security findings in executable artifacts", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.10.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_eb88a44b5350452dbe311722dc4d806b | https://github.com/refly-ai/refly/releases/tag/v0.10.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.10.0", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.4.2", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_63bd65a5586242c8a4f52bad2217eb37 | https://github.com/refly-ai/refly/releases/tag/v0.4.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.4.2", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_dd65b4699b5d40b994cbe193f304e92e | https://github.com/refly-ai/refly/releases/tag/v0.6.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.6.0", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.1", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_99e4528065d24170b07db348f8e8a81f | https://github.com/refly-ai/refly/releases/tag/v0.7.1 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.7.1", "user_impact": "可能阻塞安装或首次运行。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 22 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inq…。", "title": "踩坑日志" }, "snapshot": { "contributors": 47, "forks": 713, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 7292 }, "source_url": "https://github.com/refly-ai/refly", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "The first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex & more. Build Clawdbot 🦞· APIs for Lovable · Bots for Slack & Lark/Feishu · Skills are infrastructure, not prompts.", "title": "refly 能力包", "trial_prompt": "# refly - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 refly 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Refly 项目介绍。围绕“Refly 项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-tech-stack：技术栈概览。围绕“技术栈概览”模拟一次用户任务，不展示安装或运行结果。\n3. page-system-architecture：系统整体架构。围绕“系统整体架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-module-overview：API 模块总览。围绕“API 模块总览”模拟一次用户任务，不展示安装或运行结果。\n5. page-workflow-system：工作流系统。围绕“工作流系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Refly 项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-tech-stack\n输入：用户提供的“技术栈概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-system-architecture\n输入：用户提供的“系统整体架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-module-overview\n输入：用户提供的“API 模块总览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-workflow-system\n输入：用户提供的“工作流系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Refly 项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-tech-stack：Step 2 必须围绕“技术栈概览”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-system-architecture：Step 3 必须围绕“系统整体架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-module-overview：Step 4 必须围绕“API 模块总览”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-workflow-system：Step 5 必须围绕“工作流系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/refly-ai/refly\n- https://github.com/refly-ai/refly#readme\n- packages/cli/skill/references/skill.md\n- packages/cli/skill/SKILL.md\n- README.md\n- README_CN.md\n- apps/api/package.json\n- apps/web/package.json\n- packages/tsconfig/base.json\n- apps/api/src/modules/app.module.ts\n- apps/web/src/App.tsx\n- pnpm-workspace.yaml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 refly 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry（https://github.com/refly-ai/refly/issues/2278）；github/github_issue: Security findings in executable artifacts（https://github.com/refly-ai/refly/issues/2276）；github/github_issue: [Question] Sandbox deployment fails with \"AggregateError: All promises w（https://github.com/refly-ai/refly/issues/2088）；github/github_issue: 🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana（https://github.com/refly-ai/refly/issues/2271）；github/github_release: v1.1.0（https://github.com/refly-ai/refly/releases/tag/v1.1.0）；github/github_release: v0.10.0（https://github.com/refly-ai/refly/releases/tag/v0.10.0）；github/github_release: v0.9.1（https://github.com/refly-ai/refly/releases/tag/v0.9.1）；github/github_release: v0.9.0（https://github.com/refly-ai/refly/releases/tag/v0.9.0）；github/github_release: v0.8.0（https://github.com/refly-ai/refly/releases/tag/v0.8.0）；github/github_release: v0.7.1（https://github.com/refly-ai/refly/releases/tag/v0.7.1）；github/github_release: v0.7.0（https://github.com/refly-ai/refly/releases/tag/v0.7.0）；github/github_release: v0.6.0（https://github.com/refly-ai/refly/releases/tag/v0.6.0）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry", "url": "https://github.com/refly-ai/refly/issues/2278" }, { "kind": "github_issue", "source": "github", "title": "Security findings in executable artifacts", "url": "https://github.com/refly-ai/refly/issues/2276" }, { "kind": "github_issue", "source": "github", "title": "[Question] Sandbox deployment fails with \"AggregateError: All promises w", "url": "https://github.com/refly-ai/refly/issues/2088" }, { "kind": "github_issue", "source": "github", "title": "🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana", "url": "https://github.com/refly-ai/refly/issues/2271" }, { "kind": "github_release", "source": "github", "title": "v1.1.0", "url": "https://github.com/refly-ai/refly/releases/tag/v1.1.0" }, { "kind": "github_release", "source": "github", "title": "v0.10.0", "url": "https://github.com/refly-ai/refly/releases/tag/v0.10.0" }, { "kind": "github_release", "source": "github", "title": "v0.9.1", "url": "https://github.com/refly-ai/refly/releases/tag/v0.9.1" }, { "kind": "github_release", "source": "github", "title": "v0.9.0", "url": "https://github.com/refly-ai/refly/releases/tag/v0.9.0" }, { "kind": "github_release", "source": "github", "title": "v0.8.0", "url": "https://github.com/refly-ai/refly/releases/tag/v0.8.0" }, { "kind": "github_release", "source": "github", "title": "v0.7.1", "url": "https://github.com/refly-ai/refly/releases/tag/v0.7.1" }, { "kind": "github_release", "source": "github", "title": "v0.7.0", "url": "https://github.com/refly-ai/refly/releases/tag/v0.7.0" }, { "kind": "github_release", "source": "github", "title": "v0.6.0", "url": "https://github.com/refly-ai/refly/releases/tag/v0.6.0" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "The first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex & more. Build Clawdbot 🦞· APIs for Lovable · Bots for Slack & Lark/Feishu · Skills are infrastructure, not prompts.", "effort": "安装已验证", "forks": 713, "icon": "code", "name": "refly 能力包", "risk": "可发布", "slug": "refly", "stars": 7292, "tags": [ "知识检索", "知识库问答", "流程自动化", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/refly-ai/refly 项目说明书\n\n生成时间：2026-05-13 11:54:39 UTC\n\n## 目录\n\n- [Refly 项目介绍](#page-introduction)\n- [技术栈概览](#page-tech-stack)\n- [系统整体架构](#page-system-architecture)\n- [API 模块总览](#page-module-overview)\n- [工作流系统](#page-workflow-system)\n- [工具系统](#page-tool-system)\n- [认证与授权系统](#page-auth-system)\n- [Canvas 画布组件](#page-canvas-components)\n- [富文本编辑器系统](#page-editor-system)\n- [模型提供者系统](#page-provider-system)\n\n\n\n## Refly 项目介绍\n\n### 相关页面\n\n相关主题：[技术栈概览](#page-tech-stack), [系统整体架构](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/refly-ai/refly/blob/main/README.md)\n- [packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n- [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)\n- [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)\n- [packages/stores/src/stores/canvas.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/canvas.ts)\n- [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)\n- [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)\n- [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)\n
\n\n# Refly 项目介绍\n\n## 1. 项目概述\n\nRefly 是一个基于 AI 的可视化工作流构建平台，旨在帮助用户通过直观的拖拽式画布界面创建和编排 AI 工作流。该项目采用 Monorepo 架构，包含了前端画布组件、AI Copilot 智能助手、命令行工具、API 服务等多个子包和应用。\n\nRefly 的核心价值在于降低 AI 工作流构建的门槛，让用户无需编写代码即可组合各种 AI 能力，创建复杂的自动化任务流程。\n\n## 2. 项目架构\n\n### 2.1 Monorepo 结构概览\n\n```\nrefly/\n├── apps/\n│ ├── api/ # 后端 API 服务\n│ │ └── src/modules/\n│ │ ├── workflow-app/ # 工作流相关模块\n│ │ └── voucher/ # 优惠券/凭证系统\n│ └── web/ # Web 应用\n├── packages/\n│ ├── ai-workspace-common/ # AI 工作空间通用组件\n│ │ └── src/components/\n│ │ ├── canvas/ # 画布核心组件\n│ │ │ ├── nodes/ # 节点类型（代码工件、技能响应等）\n│ │ │ ├── webhook/ # Webhook 配置\n│ │ │ └── top-toolbar/ # 顶部工具栏\n│ │ ├── pure-copilot/ # 纯 AI 助手组件\n│ │ ├── markdown/ # Markdown 渲染\n│ │ ├── slideshow/ # 幻灯片展示\n│ │ └── resource-view/ # 资源视图\n│ ├── stores/ # 状态管理 (Zustand)\n│ │ └── src/stores/\n│ │ ├── canvas.ts # 画布状态\n│ │ └── import-resource.ts\n│ ├── web-core/ # Web 核心功能\n│ ├── layout/ # 页面布局组件\n│ └── cli/ # 命令行工具\n```\n\n### 2.2 技术栈\n\n| 层级 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | React + TypeScript | 主要开发语言 |\n| UI 组件库 | Ant Design | 基础 UI 组件 |\n| 样式方案 | Tailwind CSS | 原子化 CSS |\n| 状态管理 | Zustand | 轻量级状态管理 |\n| 画布引擎 | React Flow | 可视化流程图库 |\n| 国际化 | i18next | 多语言支持 |\n| 后端 | Node.js | API 服务 |\n| CLI | TypeScript | 命令行工具 |\n\n## 3. 核心功能模块\n\n### 3.1 Canvas 画布系统\n\nCanvas 是 Refly 的核心功能模块，提供可视化的 AI 工作流编辑界面。\n\n#### 3.1.1 画布交互配置\n\n```typescript\n\n```\n\n#### 3.1.2 画布状态管理\n\nCanvas 状态通过 Zustand store 统一管理：\n\n```typescript\n// packages/stores/src/stores/canvas.ts\nconst defaultCanvasState = () => ({\n config: {},\n currentCanvasId: null,\n initialFitViewCompleted: false,\n operatingNodeId: null,\n showEdges: true,\n nodeSizeMode: 'compact' as const,\n showTemplates: true,\n showSlideshow: false,\n linearThreadMessages: [],\n tplConfig: null,\n canvasPage: {},\n contextMenuOpenedCanvasId: null,\n canvasTitle: {},\n canvasInitialized: {},\n canvasInitializedAt: {},\n canvasExecutionId: {},\n canvasNodeExecutions: {},\n canvasVariables: {},\n});\n```\n\n### 3.2 节点类型系统\n\nRefly 画布支持多种类型的节点，用于构建不同功能的 AI 工作流。\n\n#### 3.2.1 CodeArtifactNode 代码工件节点\n\n用于展示和编辑代码生成结果：\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx\n {}}\n showActions={false}\n/>\n```\n\n#### 3.2.2 ActionStep 技能执行步骤\n\n展示 AI 技能执行过程中的日志和状态：\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx\nitems={logs.map((log) => ({\n title: t(`${log.key}.title`, { ...log.titleArgs, ns: 'skillLog' }),\n description: t(`${log.key}.description`, { ...log.descriptionArgs, ns: 'skillLog' }),\n status: log.status === 'error' ? 'error' : 'finish',\n}))}\n```\n\n### 3.3 Pure Copilot 智能助手\n\nPure Copilot 是 Refly 内置的 AI 助手组件，支持自然语言交互和文件处理。\n\n#### 3.3.1 组件功能\n\n- **文件拖拽上传**：支持拖拽文件到输入区域\n- **上下文管理**：管理已上传的文件列表\n- **消息发送**：支持 @ 提及特定工具集\n- **多语言国际化**：内置中文和英文提示文本\n\n```typescript\n// packages/ai-workspace-common/src/components/pure-copilot/index.tsx\nconst { query, setQuery, setContextItems, setSelectedToolsets } =\n useAgentNodeManagement(nodeId);\nconst { connectToUpstreamAgent } = useAgentConnections();\nconst { data: workflowVariables } = useVariablesManagement(canvasId);\n```\n\n### 3.4 Webhook 集成\n\nRefly 支持 Webhook 配置，允许用户将工作流与其他系统集成。\n\n#### 3.4.1 Webhook 配置界面\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx\n
\n {t('webhook.instructions')}\n
    \n
  • {t('webhook.instruction1')}
    • \n
  • {t('webhook.instruction2')}
    • \n
  • {t('webhook.instruction3')}
    • \n
\n
\n```\n\n### 3.5 模板市场与优惠券系统\n\nRefly 包含完整的创作者激励机制，包括模板市场和折扣券系统。\n\n#### 3.5.1 多语言邮件模板\n\n```typescript\n// apps/api/src/modules/voucher/voucher-email-templates.ts\nexport function generateVoucherEmail(\n data: VoucherEmailData,\n locale?: string,\n): { subject: string; html: string } {\n // 检查语言环境是否为中文\n const isChineseLocale = locale?.toLowerCase().startsWith('zh');\n \n if (isChineseLocale) {\n return generateVoucherEmailZH(data);\n }\n return generateVoucherEmailEN(data);\n}\n```\n\n#### 3.5.2 邮件内容结构\n\n| 区域 | 中文内容 | 英文内容 |\n|------|----------|----------|\n| 标题 | 恭喜获得专属折扣！ | Congratulations on Your Exclusive Discount! |\n| 称呼 | ${userName}，您好！ | Hello ${userName}! |\n| 描述 | 感谢您在 Refly.ai 上发布模板！为表感谢，这是专属于您的折扣奖励。 | Thank you for publishing a template on Refly.ai! As a token of appreciation, here's your exclusive discount reward. |\n| 底部 | Refly.ai 团队 | Refly.ai Team |\n\n### 3.6 调度系统 (Schedule)\n\nRefly 支持工作流的定时调度功能，包含完整的调度限制和模态框交互。\n\n#### 3.6.1 调度限制模态框\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx\n setScheduleLimitModalVisible(false)}>\n {t('common.cancel') || 'Cancel'}\n ,\n ,\n ]}\n>\n

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

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

Hi ${data.userName},

\n

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

\n \n
Run details
\n
    \n
  • Status: Failed
    • \n
  • Run time: ${data.scheduledAt}
    • \n
  • Next scheduled run: ${data.nextRunTime}
    • \n
\n `\n);\n```\n\n资料来源：[apps/api/src/modules/schedule/schedule-email-templates.ts:1-50]()\n\n## Webhook 集成\n\n### Webhook 配置标签页\n\n```tsx\n
\n {t('webhook.instructions')}\n
    \n
  • {t('webhook.instruction1')}
    • \n
  • {t('webhook.instruction2')}
    • \n
  • {t('webhook.instruction3')}
    • \n
\n
\n```\n\n### Webhook 错误码\n\n| 错误码 | HTTP 状态 | 描述 |\n|--------|-----------|------|\n| 错误代码 | HTTP 状态码 | 错误消息 |\n\n错误码表格组件：\n\n```tsx\n\n \n \n \n \n \n \n \n \n \n {apiDocsData.errorCodes.map((error) => (\n \n \n \n \n ))}\n \n
{t('integration.api.errorCode')}{t('integration.api.errorStatus')}{t('integration.api.errorMessage')}{t('integration.api.errorDescription')}
\n {error.code}\n {error.httpStatus ?? '-'}
\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx:1-30]()\n\n## Skill Package 工作流导出\n\n### DTO 定义\n\n```typescript\nexport interface CreateSkillPackageDto {\n name: string;\n version: string;\n description?: string;\n icon?: SkillIconDto;\n triggers?: string[];\n tags?: string[];\n inputSchema?: Record;\n outputSchema?: Record;\n}\n\nexport interface CreateSkillPackageCliDto extends CreateSkillPackageDto {\n workflowId?: string;\n workflowIds?: string[];\n workflowQuery?: string;\n workflowSpec?: {\n nodes?: Array>;\n edges?: Array>;\n };\n workflowName?: string;\n workflowDescription?: string;\n workflowVariables?: Array>;\n noWorkflow?: boolean;\n}\n```\n\n### 响应结构\n\n```typescript\nexport interface CreateSkillPackageCliResponse {\n skillId: string;\n name: string;\n status: string;\n createdAt: string;\n workflowId?: string;\n workflowIds?: string[];\n workflows?: Array<{\n workflowId: string;\n name?: string;\n description?: string;\n }>;\n inputSchema?: Record;\n outputSchema?: Record;\n installationId?: string;\n}\n```\n\n资料来源：[apps/api/src/modules/skill-package/skill-package.dto.ts:1-80]()\n\n## CLI 命令行接口\n\n### 基础命令\n\n| 命令 | 描述 |\n|------|------|\n| `refly init` | 初始化 CLI 并安装 skill 文件 |\n| `refly login` | 使用 API 密钥认证 |\n| `refly logout` | 移除凭证 |\n| `refly status` | 检查配置和认证状态 |\n| `refly whoami` | 显示当前用户信息 |\n\n### Builder 模式\n\n增量构建工作流：\n\n```bash\nrefly builder start --name \"workflow-name\" # 启动构建会话\nrefly builder add-node --node '' # 添加节点\nrefly builder update-node --id \"\" --patch '' # 更新节点\nrefly builder remove-node --id \"\" # 删除节点\nrefly builder connect --from \"\" --to \"\" # 连接节点\nrefly builder disconnect --from \"\" --to \"\" # 断开连接\nrefly builder status # 查看状态\nrefly builder graph [--ascii] # 查看图结构\nrefly builder validate # 验证工作流\nrefly builder commit # 提交工作流\nrefly builder abort # 中止构建\n```\n\n### 工作流管理\n\n```bash\n# 创建工作流\nrefly workflow create --name \"\" --spec ''\n\n# 列出工作流\nrefly workflow list [--limit N]\n\n# 获取工作流详情\nrefly workflow get \n\n# 编辑工作流\nrefly workflow edit --ops ''\n\n# 删除工作流\nrefly workflow delete \n```\n\n### 工作流执行\n\n```bash\n# 运行工作流\nrefly workflow run [--input '']\n\n# 查看运行状态\nrefly workflow run-status \n\n# 中止运行\nrefly workflow abort \n```\n\n### Builder 状态机\n\n```mermaid\ngraph LR\n IDLE[IDLE 空闲] --> DRAFT[DRAFT 草稿]\n DRAFT --> VALIDATED[VALIDATED 已验证]\n VALIDATED --> COMMITTED[COMMITTED 已提交]\n DRAFT -->|validate| VALIDATED\n VALIDATED -->|abort| IDLE\n IDLE -->|start| DRAFT\n```\n\n资料来源：[packages/cli/README.md:1-100]()\n\n## 错误码参考\n\n| 错误码 | 描述 | 提示 |\n|--------|------|------|\n| AUTH_REQUIRED | 未认证 | 执行 `refly login` |\n| BUILDER_NOT_STARTED | 无活跃的构建会话 | 执行 `refly builder start` |\n| VALIDATION_REQUIRED | 提交前必须验证 | 执行 `refly builder validate` |\n| VALIDATION_ERROR | DAG 验证失败 | 检查错误详情 |\n| DUPLICATE_NODE_ID | 节点 ID 已存在 | 使用唯一 ID |\n| CYCLE_DETECTED | 检测到循环依赖 | 移除循环 |\n| WORKFLOW_NOT_FOUND | 工作流不存在 | 检查工作流 ID |\n\n资料来源：[packages/cli/README.md:1-100]()\n\n## 页面路由导出\n\n工作流相关的页面组件通过懒加载方式导出：\n\n```typescript\n// ========== Group 4: Workflow Public ==========\nexport const WorkflowAppPage = lazy(\n () => import('./pages/workflow-app'),\n);\nexport const WorkflowListPage = lazy(\n () => import('./pages/workflow-list'),\n);\nexport const AppManager = lazy(\n () => import('./pages/app-manager'),\n);\nexport const MarketplacePage = lazy(\n () => import('./pages/marketplace'),\n);\nexport const TemplatePreviewPage = lazy(\n () => import('./pages/template-preview'),\n);\n\n// ========== Group 5: Run History ==========\nexport const RunHistoryPage = lazy(\n () => import('./pages/run-history'),\n);\nexport const RunDetailPage = lazy(\n () => import('./pages/run-detail'),\n);\n```\n\n资料来源：[packages/web-core/src/index.ts:1-50]()\n\n## 配置说明\n\n### 配置文件\n\n配置存储在 `~/.refly/config.json`：\n\n```json\n{\n \"version\": 1,\n \"auth\": {\n \"apiKey\": \"...\",\n \"expiresAt\": \"...\"\n },\n \"api\": {\n \"endpoint\": \"https://api.refly.ai\"\n }\n}\n```\n\n### 环境变量\n\n| 变量名 | 描述 |\n|--------|------|\n| REFLY_API_KEY | 认证用的 API 密钥 |\n| REFLY_API_ENDPOINT | 覆盖默认 API 端点 |\n\n资料来源：[packages/cli/README.md:1-100]()\n\n## 工具集依赖检查\n\n### 工具依赖检查器组件\n\n```tsx\nexport const ToolsDependencyChecker = ({\n canvasData,\n externalOpen,\n highlightInstallButtons,\n onOpenChange,\n creditUsage,\n}: {\n canvasData?: RawCanvasData;\n externalOpen?: boolean;\n highlightInstallButtons?: boolean;\n onOpenChange?: (open: boolean) => void;\n creditUsage?: number;\n}) => {\n // 组件实现...\n};\n```\n\n### 工具安装处理\n\n```tsx\n{!isInstalled && isLogin && (\n handleInstallTool(toolset)}\n >\n {isPolling || isOpening\n ? t('canvas.richChatInput.authorizing', '授权中...')\n : t('canvas.workflowDependency.goToInstall')}\n \n)}\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/tools-dependency/index.tsx:1-50]()\n\n## 总结\n\n工作流系统是 Refly 平台的核心能力，通过以下特性实现复杂任务的自动化：\n\n1. **DAG 执行模型**：基于有向无环图的任务编排，确保正确的执行顺序\n2. **灵活的工具集成**：支持多种工具集扩展功能\n3. **完善的生命周期管理**：支持创建、编辑、验证、提交和运行\n4. **定时调度能力**：支持 cron 表达式和循环执行\n5. **Webhook 集成**：便于与外部系统对接\n6. **丰富的 CLI 支持**：支持本地开发和调试\n\n---\n\n\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[模型提供者系统](#page-provider-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/skill-template/src/scheduler/utils/context.ts](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts)\n- [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)\n- [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)\n- [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)\n- [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)\n
\n\n# 工具系统\n\n## 概述\n\n工具系统（Tool System）是 Refly 平台的核心能力之一，它为 AI Agent 提供了与外部世界交互的桥梁。通过工具系统，Agent 可以执行代码、调用 API、操作文件、发送 Webhook 等，从而完成复杂的自动化任务。\n\n工具系统的设计遵循以下核心原则：\n\n- **模块化**：工具按功能分类为工具集（Toolsets）和独立工具（Tools）\n- **按需加载**：通过元数据机制减少上下文大小，LLM 按需读取完整内容\n- **权限控制**：支持工具授权管理，确保安全执行\n- **类型安全**：完整的 TypeScript 类型定义，支持国际化描述\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts:20-30]()\n\n## 核心类型定义\n\n### 工具调用元数据\n\n工具调用元数据用于在 Agent 结果中提供工具调用的摘要信息，而不需要包含完整的输入输出内容：\n\n```typescript\ninterface ToolCallMeta {\n /** 工具调用 ID，用于通过 read_tool_result 检索 */\n callId: string;\n /** 被调用工具的名称 */\n toolName: string;\n}\n```\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts:30-38]()\n\n### 提及项类型\n\n在用户输入界面中，工具和工具集通过提及（Mention）机制进行选择：\n\n```typescript\ninterface MentionItem {\n name: string;\n description: string;\n source: 'toolsets' | 'tools';\n toolset?: Toolset;\n toolsetId?: string;\n toolDefinition?: ToolDefinition;\n isInstalled: boolean;\n}\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts:1-100]()\n\n## 工具架构\n\n### 工具层级结构\n\n```\n工具系统\n├── Toolset（工具集）\n│ ├── 工具集定义 (ToolsetDefinition)\n│ ├── 工具列表 (tools)\n│ └── 授权状态 (authorized)\n└── Tool（独立工具）\n ├── 工具名称 (name)\n ├── 工具描述 (description)\n └── 工具定义 (definition)\n```\n\n### 工具集管理\n\n工具集（Toolset）是相关工具的集合，支持以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| 授权管理 | 通过 `authorized` 属性控制访问权限 |\n| 动态加载 | 根据用户配置动态加载工具集定义 |\n| 国际化 | 支持多语言描述 (`descriptionDict`) |\n| 状态持久化 | 工具选择状态可保存到节点数据 |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts:40-70]()\n\n## 工具选择流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant UI as 提及界面\n participant Hook as useListMentionItems\n participant Toolset as 工具集定义\n \n User->>UI: 输入 @ 触发提及\n UI->>Hook: 请求工具列表\n Hook->>Toolset: 查找工具集定义\n Toolset-->>Hook: 返回工具元数据\n Hook-->>UI: 返回 MentionItem[]\n UI-->>User: 显示工具选择列表\n User->>UI: 选择工具\n UI->>Hook: 添加到已选工具集\n```\n\n## 工具集集成配置\n\n### 配置界面\n\n在 Agent 配置界面中，用户可以添加或移除工具集：\n\n```typescript\ninterface ConfigInfoDisplayProps {\n contextItems: ContextFile[]; // 上下文文件\n upstreamAgentNodes: Node[]; // 上游 Agent\n selectedToolsets: Toolset[]; // 已选工具集\n disabled?: boolean; // 是否禁用\n}\n```\n\n### 工具集显示组件\n\n工具集以标签项（LabelItem）的形式展示，支持以下交互：\n\n- 鼠标悬停高亮显示相关节点\n- 关闭按钮移除已选工具集\n- 图标区分不同工具类型\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/config-info-display.tsx:1-80]()\n\n## 工具使用块解析\n\n### 正则表达式定义\n\n工具使用块支持两种格式：Markdown 代码块格式和独立的 XML 标签格式：\n\n```typescript\n// 匹配 Markdown 代码块格式和独立 XML 标签\nconst TOOL_USE_BLOCK_REGEX = /\\n*```tool_use(?:_result)?[^\\n]*\\n[\\s\\S]*?```\\n*/g;\nconst TOOL_USE_TAG_REGEX = //g;\n```\n\n支持的格式：\n\n| 格式 | 示例 |\n|------|------|\n| Markdown 代码块 | ` ```tool_use\\n...\\n``` ` |\n| 带结果的代码块 | ` ```tool_use_result\\n...\\n``` ` |\n| 独立 XML 标签 | `...` |\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts:1-10]()\n\n## Skill 文档系统\n\n### Skill 安装\n\nSkill 文档提供了标准的安装流程：\n\n```bash\n# Skill 安装步骤\n1. 浏览可用 Skill 列表\n2. 点击安装按钮\n3. 配置 Skill 参数\n```\n\n安装完成后，Skill 文件会复制到本地目录：\n- `~/.refly/skills/` - Skill 资源目录\n- Claude Code 集成：`~/.claude/skills/refly/`\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/skill-docs-tab.tsx:1-50]()\n\n### Skill 卸载\n\n```bash\n# Skill 卸载命令\nrefly skill uninstall \n```\n\n卸载过程会清理相关配置和资源文件。\n\n## Webhook 集成\n\n### Webhook 配置标签页\n\nWebhook 配置界面包含以下区域：\n\n| 区域 | 说明 |\n|------|------|\n| 端点配置 | 设置 Webhook URL 和认证信息 |\n| 请求体模式 | 定义传入数据的 JSON Schema |\n| 错误代码表 | HTTP 状态码与错误信息映射 |\n\n### 请求体字段定义\n\n```typescript\ninterface RequestBodyField {\n name: string; // 字段名称\n type: string; // 数据类型\n required: boolean; // 是否必填\n description: string; // 字段描述\n}\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx:1-100]()\n\n## 工具与上下文交互\n\n### 上下文项创建\n\n从提及项创建上下文项时，系统会提取关键元数据：\n\n```typescript\nconst contextItem: IContextItem = {\n entityId: item.entityId || item.nodeId || item.variableId || item.name,\n resourceType: item.resourceType,\n resourceMeta: item.metadata?.resourceMeta,\n variableType: 'tool',\n};\n```\n\n### 上下文项管理\n\n| 操作 | 说明 |\n|------|------|\n| 添加 | 通过 `addToContextItems()` 添加到上下文 |\n| 移除 | 通过 `handleRemoveContextItem()` 移除 |\n| 高亮 | 悬停时高亮相关画布节点 |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx:1-100]()\n\n## 工具系统状态流\n\n```mermaid\ngraph TD\n A[用户输入 @] --> B[显示提及列表]\n B --> C{选择类型}\n C -->|工具集| D[添加 Toolset]\n C -->|工具| E[添加 Tool]\n C -->|资源| F[创建资源上下文]\n \n D --> G[更新 selectedToolsets]\n E --> H[更新 contextItems]\n F --> I[关联 DriveFile]\n \n G --> J[节点数据持久化]\n H --> J\n I --> J\n \n J --> K[Agent 执行时加载工具]\n```\n\n## 错误处理\n\n### 工具调用错误\n\n当工具执行失败时，系统会记录错误日志：\n\n```typescript\nitems={logs.map((log) => ({\n title: t(`${log.key}.title`, { ...log.titleArgs, ns: 'skillLog' }),\n description: t(`${log.key}.description`, { ...log.descriptionArgs, ns: 'skillLog' }),\n status: log.status === 'error' ? 'error' : 'finish',\n}))}\n```\n\n### 错误状态分类\n\n| 状态 | 说明 |\n|------|------|\n| `error` | 工具执行失败 |\n| `finish` | 工具执行成功 |\n| `executing` | 工具执行中 |\n| `waiting` | 等待工具响应 |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:1-60]()\n\n## 国际化支持\n\n工具系统全面支持多语言，通过 `descriptionDict` 配置：\n\n```typescript\nconst toolDefinition = {\n name: 'read_file',\n descriptionDict: {\n en: 'Read file content from specified path',\n zh: '读取指定路径的文件内容',\n },\n};\n```\n\n当前支持的语言：\n- `en` - 英文\n- `zh` - 中文\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/hooks/use-list-mention-items.ts:30-50]()\n\n## 总结\n\n工具系统是 Refly 平台实现 AI Agent 能力扩展的核心架构。它通过：\n\n1. **模块化设计** - 工具集和独立工具的清晰分层\n2. **按需加载** - 元数据驱动的上下文优化\n3. **权限控制** - 灵活的授权机制\n4. **国际化支持** - 多语言描述覆盖\n5. **可视化配置** - 直观的提及式选择界面\n\n为开发者提供了强大而灵活的工具集成能力，使得 AI Agent 能够执行各种复杂的外部操作任务。\n\n---\n\n\n\n## 认证与授权系统\n\n### 相关页面\n\n相关主题：[系统整体架构](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n- [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)\n- [packages/web-core/src/pages/login/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/login/index.tsx)\n
\n\n# 认证与授权系统\n\n## 系统概述\n\nRefly 平台的认证与授权系统是一套完整的安全机制，支持多种认证方式以满足不同用户场景的需求。该系统涵盖了前端登录界面、后端 API 认证以及 CLI 工具的身份验证三大核心领域。\n\n### 核心认证方式\n\n| 认证方式 | 适用场景 | 实现位置 |\n|---------|---------|---------|\n| OAuth 2.0 (Google/GitHub) | Web 端三方登录 | `packages/web-core/src/pages/login/index.tsx` |\n| 邮箱密码认证 | 传统用户登录 | `packages/web-core/src/components/login-modal/login-content.tsx` |\n| API 密钥认证 | CLI 工具与机器间通信 | `packages/cli/README.md` |\n\n---\n\n## 前端认证界面\n\n### 登录模态框\n\n前端登录界面采用模块化设计，支持多种认证方式的动态展示与切换。系统会根据配置自动显示可用的登录选项，包括 OAuth 提供商和邮箱登录表单。\n\n登录模态框的核心功能包括：\n\n- **OAuth 按钮组件**：支持 Google 和 GitHub 两种第三方登录方式\n- **邮箱登录表单**：可折叠展开的传统邮箱密码登录方式\n- **分隔符设计**：在 OAuth 和邮箱登录之间提供视觉分隔\n- **国际化支持**：所有文本标签支持多语言切换\n\n```typescript\n// OAuth 登录按钮配置示例\n handleLogin('google')}\n loading={authStore.loginInProgress && authStore.loginProvider === 'google'}\n buttonText={t('landingPage.loginModal.oauthBtn.google')}\n/>\n```\n\n### 登录页面架构\n\n登录页面 (`packages/web-core/src/pages/login/index.tsx`) 实现了完整的认证流程控制，包括：\n\n1. **认证状态管理**：通过 `authStore` 集中管理登录进度、提供商信息和错误状态\n2. **表单切换逻辑**：支持 OAuth 与邮箱登录表单之间的平滑切换\n3. **人机验证集成**：集成 Cloudflare Turnstile 验证码防止自动化攻击\n4. **主题适配**：支持亮色和暗色主题的自适应切换\n\n### 验证码保护机制\n\n为防止恶意自动化登录，系统集成了 Cloudflare Turnstile 验证码服务：\n\n- 仅在启用验证码功能时显示\n- 支持多语言配置\n- 提供验证成功、错误和过期三种回调处理\n- 验证码令牌作为邮箱登录的前置条件\n\n---\n\n## CLI 认证系统\n\n### 认证命令\n\nCLI 工具提供完整的命令行认证接口：\n\n| 命令 | 功能说明 |\n|-----|---------|\n| `refly login` | 使用 API 密钥进行身份认证 |\n| `refly logout` | 清除本地存储的认证凭证 |\n| `refly status` | 检查当前配置和认证状态 |\n| `refly whoami` | 显示当前登录用户信息 |\n\n### 配置文件\n\nCLI 认证配置存储在用户主目录下的 `~/.refly/config.json` 文件中：\n\n```json\n{\n \"version\": 1,\n \"auth\": {\n \"apiKey\": \"...\",\n \"expiresAt\": \"...\"\n },\n \"api\": {\n \"endpoint\": \"https://api.refly.ai\"\n }\n}\n```\n\n### 环境变量\n\n系统支持通过环境变量覆盖默认配置：\n\n| 环境变量 | 用途 |\n|---------|-----|\n| `REFLY_API_KEY` | 设置 API 密钥进行认证 |\n| `REFLY_API_ENDPOINT` | 覆盖默认 API 端点地址 |\n\n### Builder 状态机\n\nCLI 的 Builder 模式与认证系统紧密集成，包含以下状态转换：\n\n```\nIDLE → DRAFT → VALIDATED → COMMITTED\n ↑ ↓ ↓\n └────────────────┘\n```\n\n某些 Builder 操作（如 `refly builder validate` 和 `refly builder commit`）需要用户已通过认证状态。\n\n---\n\n## 错误处理\n\n### 认证相关错误码\n\n| 错误码 | 描述 | 处理建议 |\n|-------|-----|---------|\n| `AUTH_REQUIRED` | 用户未认证 | 执行 `refly login` 命令 |\n| `BUILDER_NOT_STARTED` | 无活跃的 Builder 会话 | 执行 `refly builder start` |\n| `VALIDATION_REQUIRED` | 提交前需验证 | 执行 `refly builder validate` |\n\n### 前端错误展示\n\n前端认证界面通过统一的国际化文本键处理错误展示，确保用户获得一致的错误提示体验。所有错误文本均通过 i18n 机制管理，支持多语言定制。\n\n---\n\n## 安全机制\n\n### 令牌管理\n\n- **API 密钥有效期**：存储在配置中的 `expiresAt` 字段用于跟踪令牌过期时间\n- **自动刷新**：CLI 工具会在需要时提示用户重新认证\n\n### 人机验证\n\nCloudflare Turnstile 的集成提供了额外的安全层：\n\n- 非侵入式验证体验\n- 支持基于语言的验证界面\n- 主题自适应（亮色/暗色）\n\n### OAuth 安全实践\n\n- 使用标准 OAuth 2.0 流程\n- 不在客户端存储明文密码\n- 重定向 URI 验证\n\n---\n\n## 集成指南\n\n### 前端集成\n\n在 React 组件中使用登录功能：\n\n```tsx\nimport { useAuthStore } from '@refly/stores';\n\nfunction LoginButton() {\n const { loginInProgress, loginProvider } = useAuthStore();\n \n return (\n handleLogin('github')}\n loading={loginInProgress && loginProvider === 'github'}\n />\n );\n}\n```\n\n### CLI 集成\n\n在自动化脚本中使用 API 密钥认证：\n\n```bash\nexport REFLY_API_KEY=\"your-api-key-here\"\nrefly workflow list\n```\n\n---\n\n## 架构图\n\n### 认证流程概览\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Frontend as 前端界面\n participant API as API 服务\n participant OAuth as OAuth Provider\n \n User->>Frontend: 选择登录方式\n alt OAuth 登录\n Frontend->>OAuth: 重定向到 OAuth 提供商\n OAuth-->>User: 显示授权页面\n User->>OAuth: 确认授权\n OAuth-->>Frontend: 返回授权码\n Frontend->>API: 交换令牌\n else 邮箱登录\n User->>Frontend: 输入邮箱密码\n Frontend->>API: 发送认证请求\n end\n API-->>Frontend: 返回认证令牌\n Frontend-->>User: 登录成功\n```\n\n### CLI 认证流程\n\n```mermaid\ngraph TD\n A[refly login] --> B{检查配置}\n B -->|有缓存密钥| C{密钥是否过期}\n C -->|未过期| D[使用缓存密钥]\n C -->|已过期| E[提示重新登录]\n B -->|无缓存密钥| F[请求用户输入]\n F --> G[保存到配置]\n G --> D\n E --> F\n D --> H[执行目标命令]\n```\n\n---\n\n## 相关文档\n\n- [隐私政策](https://docs.refly.ai/about/privacy-policy)\n- [服务条款](https://docs.refly.ai/about/terms-of-service)\n\n---\n\n\n\n## Canvas 画布组件\n\n### 相关页面\n\n相关主题：[工作流系统](#page-workflow-system), [富文本编辑器系统](#page-editor-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [packages/canvas-common/src/data.ts](https://github.com/refly-ai/refly/blob/main/packages/canvas-common/src/data.ts)\n- [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)\n- [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)\n- [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)\n- [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)\n
\n\n# Canvas 画布组件\n\n## 概述\n\nCanvas（画布）组件是 refly 平台的核心编辑器组件，负责构建和管理知识工作空间的可视化编辑界面。该组件为用户提供了一个灵活的节点式编辑环境，支持多种类型的内容节点、实时协作、工作流编排以及与外部系统的集成。\n\n画布组件位于 `packages/ai-workspace-common/src/components/canvas/` 目录下，采用模块化架构设计，包含节点管理、画布渲染、工具栏、文档预览、工作流运行等多个子模块。\n\n## 架构设计\n\n### 模块层次结构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Canvas 画布组件 │\n├─────────────────────────────────────────────────────────────┤\n│ 顶层组件 │\n│ ├── Canvas（主容器） │\n│ ├── TopToolbar（顶部工具栏） │\n│ └── StatusBar（状态栏） │\n├─────────────────────────────────────────────────────────────┤\n│ 节点组件 │\n│ ├── AgentNode（智能体节点） │\n│ ├── DocumentNode（文档节点） │\n│ ├── WorkflowNode（工作流节点） │\n│ ├── ArtifactNode（产物节点） │\n│ └── SkillResponseNode（技能响应节点） │\n├─────────────────────────────────────────────────────────────┤\n│ 交互组件 │\n│ ├── RichChatInput（富文本聊天输入） │\n│ ├── Copilot（副驾驶助手） │\n│ └── PureCopilot（纯净副驾驶） │\n├─────────────────────────────────────────────────────────────┤\n│ 工作流运行 │\n│ ├── WorkflowNodePanel（工作流节点面板） │\n│ ├── ActionStep（执行步骤） │\n│ └── ArtifactRenderer（产物渲染器） │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心数据流\n\n```mermaid\ngraph TD\n A[用户交互] --> B[Canvas Context]\n B --> C{节点类型判断}\n C -->|Agent| D[AgentNode 组件]\n C -->|Document| E[DocumentNode 组件]\n C -->|Workflow| F[WorkflowNodePanel]\n C -->|Artifact| G[ArtifactRenderer]\n D --> H[AgentNodeManagement]\n E --> I[DocumentProvider]\n F --> J[执行状态管理]\n G --> K[Renderer 组件]\n H --> L[Tool Store / Variable Store]\n J --> M[结果输出]\n K --> N[预览渲染]\n L --> O[工具调用]\n M --> P[LastRunTab]\n N --> Q[只读展示]\n```\n\n## 核心组件\n\n### Canvas 主组件\n\nCanvas 主组件是整个画布系统的根容器，负责初始化画布上下文并协调各个子组件的渲染。\n\n**组件位置**: `packages/ai-workspace-common/src/components/canvas/index.tsx`\n\nCanvas 主组件提供以下核心功能：\n\n| 功能 | 描述 |\n|------|------|\n| 画布上下文管理 | 通过 React Context 提供全局画布状态 |\n| 节点渲染协调 | 根据节点类型分发到对应的节点组件 |\n| 缩放与平移 | 支持画布的缩放和拖拽平移操作 |\n| 节点连接管理 | 处理节点之间的连线关系 |\n| 拖拽排序 | 支持节点的拖拽排序功能 |\n\n### 节点组件体系\n\n节点组件是画布上的核心编辑单元，每种节点类型对应不同的功能和交互模式。\n\n#### AgentNode 智能体节点\n\nAgentNode 是画布中用于表示 AI 智能体的节点组件，封装了与大语言模型交互的核心逻辑。\n\n**组件引用**: `packages/ai-workspace-common/src/components/canvas/nodes/index.ts`\n\n```tsx\n// AgentNode 核心属性\ninterface AgentNodeProps {\n nodeId: string; // 节点唯一标识\n canvasId: string; // 所属画布 ID\n readonly?: boolean; // 只读模式\n onRequestFix?: () => void; // 修复请求回调\n}\n```\n\n#### WorkflowNodePanel 工作流节点面板\n\n工作流节点面板用于展示和执行工作流的运行状态，包括执行日志、结果输出和错误信息。\n\n**组件位置**: `packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx`\n\n```tsx\n// WorkflowNodePanel 核心属性\ninterface WorkflowNodePanelProps {\n node: any; // 节点数据\n canvasId: string; // 画布 ID\n resultId?: string; // 执行结果 ID\n result?: AgentResult; // 执行结果\n loading?: boolean; // 加载状态\n isStreaming?: boolean; // 是否为流式输出\n outputStep?: any; // 输出步骤\n query?: string; // 查询参数\n title?: string; // 节点标题\n selectedToolsets?: any[]; // 选中的工具集\n}\n```\n\n工作流节点面板包含以下标签页：\n\n| 标签页 | 功能 | 资料来源 |\n|--------|------|----------|\n| LastRunTab | 最近运行结果展示 | [workflow-node-panel.tsx:60]() |\n| 日志标签 | 执行日志查看 | [workflow-node-panel.tsx:61]() |\n| 输出标签 | 结构化输出展示 | [workflow-node-panel.tsx:62]() |\n\n### ArtifactRenderer 产物渲染器\n\nArtifactRenderer 负责渲染代码片段、文档和其他产物内容，支持全屏模式和缩略图预览。\n\n**组件位置**: `packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx`\n\n```tsx\n// ArtifactRenderer 核心属性\ninterface ArtifactRendererProps {\n content: string; // 内容文本\n type: string; // 内容类型\n title?: string; // 标题\n language?: string; // 编程语言\n readonly?: boolean; // 只读模式\n purePreview?: boolean; // 纯净预览模式\n onRequestFix?: () => void; // 修复请求\n width?: string; // 宽度\n height?: string; // 高度\n}\n```\n\nArtifactRenderer 支持两种渲染模式：\n\n| 模式 | 条件 | 行为 |\n|------|------|------|\n| 缩略图模式 | `isMinimap === true` | 以 50% 缩放比例显示在左上角 |\n| 全屏模式 | `isFullscreen === true` | 占满可用高度区域 |\n\n渲染器通过 memo 的第二个参数实现渲染优化，仅在关键元数据变化时重新渲染：\n\n```tsx\n(prevProps, nextProps) => {\n const prevMetadata = prevProps.node.nodeData?.metadata || {};\n const nextMetadata = nextProps.node.nodeData?.metadata || {};\n \n return (\n prevProps.type === nextProps.type &&\n prevProps.node.entityId === nextProps.node.entityId &&\n prevMetadata.content === nextMetadata.content &&\n prevMetadata.status === nextMetadata.status &&\n prevMetadata.type === nextMetadata.type\n );\n}\n```\n\n资料来源：[ArtifactRenderer.tsx:98-112]()\n\n## 交互组件\n\n### RichChatInput 富文本聊天输入\n\nRichChatInput 是画布中用于用户输入的核心组件，支持多行文本、文件上传、@提及等功能。\n\n**组件位置**: `packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx`\n\n```tsx\n// RichChatInput 核心接口\ninterface RichChatInputProps {\n readonly?: boolean;\n handleSendMessage: () => void;\n onUploadImage?: (file: File) => Promise;\n onUploadMultipleImages?: (files: File[]) => Promise;\n onFocus?: () => void;\n nodeId?: string;\n placeholder?: string;\n mentionPosition?: MentionPosition;\n}\n```\n\nRichChatInput 暴露以下方法供父组件调用：\n\n```tsx\nexport interface RichChatInputRef {\n focus: () => void; // 获取输入框焦点\n insertAtSymbol?: () => void; // 插入 @ 符号\n}\n```\n\n组件内部集成了以下功能模块：\n\n| 模块 | 功能 |\n|------|------|\n| useAgentNodeManagement | 节点状态管理 |\n| useAgentConnections | 智能体连接管理 |\n| useVariablesManagement | 变量管理 |\n| useFetchDriveFiles | 云端文件获取 |\n\n资料来源：[rich-chat-input/index.tsx:32-50]()\n\n### ActionStep 执行步骤组件\n\nActionStep 组件用于展示技能执行的中间步骤和推理过程。\n\n**组件位置**: `packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx`\n\n```tsx\n// ReasoningContent 组件属性\ninterface ReasoningContentProps {\n resultId: string;\n reasoningContent: string;\n sources: Source[];\n step: ActionStep;\n status: ActionStatus;\n}\n```\n\nActionStep 支持以下状态转换：\n\n| 状态 | 自动行为 |\n|------|----------|\n| `executing` | 展开推理内容 |\n| `waiting` | 展开推理内容 |\n| `finish` | 折叠推理内容 |\n| `failed` | 折叠推理内容 |\n\n```tsx\nuseEffect(() => {\n if (['executing', 'waiting'].includes(status)) {\n setCollapsed(false);\n } else {\n setCollapsed(true);\n }\n}, [status]);\n```\n\n资料来源：[action-step.tsx:56-63]()\n\n### Copilot 副驾驶组件\n\nCopilot 组件是画布中的 AI 助手入口，提供上下文感知的智能辅助功能。\n\n**组件位置**: `packages/ai-workspace-common/src/components/canvas/copilot/index.tsx`\n\n## 状态管理\n\n### Canvas Context\n\nCanvas 使用 React Context 提供全局状态管理，主要包括：\n\n```tsx\ninterface CanvasContextValue {\n canvasId: string; // 画布唯一标识\n readonly?: boolean; // 只读模式标识\n // 其他上下文属性\n}\n```\n\n### 节点状态管理\n\n节点状态通过 `useAgentNodeManagement` hook 进行管理：\n\n```tsx\nconst { query, setQuery, setContextItems, setSelectedToolsets } =\n useAgentNodeManagement(nodeId);\n```\n\n### 工作流执行状态\n\n工作流节点面板管理以下执行状态：\n\n| 状态 | 描述 |\n|------|------|\n| `idle` | 空闲状态 |\n| `loading` | 加载中 |\n| `generating` | 生成中 |\n| `executing` | 执行中 |\n| `finish` | 执行完成 |\n| `failed` | 执行失败 |\n\n## 国际化支持\n\nCanvas 组件全面支持国际化，通过 `react-i18next` 实现多语言切换。\n\n### 关键翻译键\n\n| 翻译键 | 描述 |\n|--------|------|\n| `pages.components.artifact.generating` | 产物生成中提示 |\n| `pages.components.artifact.loading` | 产物加载中提示 |\n| `pages.components.artifact.notSelected` | 未选择产物提示 |\n| `pages.components.artifact.code` | 代码类型标识 |\n| `canvas.workflow.run.executionFailed` | 执行失败提示 |\n\n资料来源：[ArtifactRenderer.tsx:45-70]() 和 [workflow-node-panel.tsx:44]()\n\n## 样式与主题\n\n### 动态样式类\n\nCanvas 组件使用 Tailwind CSS 实现响应式样式，并支持亮色/暗色主题切换：\n\n```tsx\nclassName={`h-full bg-white dark:bg-[var(--refly-bg-content-z2)] \n ${!isFullscreen ? 'rounded px-4 pb-4' : 'w-full'}`}\n```\n\n### 主题变量\n\n| 变量名 | 用途 |\n|--------|------|\n| `--refly-bg-content-z2` | 内容区域背景色 |\n| `--refly-text-0` | 主文本色 |\n| `--refly-primary-default` | 主色调 |\n| `--refly-func-danger-default` | 危险/错误状态色 |\n\n## 组件配置选项\n\n### PrimaryPageLayout 配置\n\n画布页面使用 PrimaryPageLayout 作为基础布局：\n\n| 配置项 | 类型 | 描述 |\n|--------|------|------|\n| `title` | string | 页面标题 |\n| `actions` | ReactNode | 动作按钮区域 |\n| `extra` | ReactNode | 额外内容区域 |\n| `fixHeight` | boolean | 是否固定高度 |\n| `noPaddingY` | boolean | 是否移除垂直内边距 |\n| `noPaddingX` | boolean | 是否移除水平内边距 |\n\n### SecondaryPageLayout 配置\n\n详情页面使用 SecondaryPageLayout：\n\n| 配置项 | 类型 | 描述 |\n|--------|------|------|\n| `title` | string | 页面标题 |\n| `desc` | string | 页面描述 |\n| `onBack` | function | 返回按钮回调 |\n| `actions` | ReactNode | 动作按钮区域 |\n\n资料来源：[packages/layout/README.md]()\n\n## 性能优化\n\n### Memo 优化策略\n\nArtifactRenderer 通过 memo 的自定义比较函数实现精细化的重渲染控制：\n\n```tsx\nexport const ArtifactRenderer = memo(\n (props) => { /* 渲染逻辑 */ },\n (prevProps, nextProps) => {\n // 仅在关键属性变化时重渲染\n return (\n prevProps.type === nextProps.type &&\n prevProps.node.entityId === nextProps.node.entityId &&\n prevMetadata.content === nextMetadata.content &&\n prevMetadata.status === nextMetadata.status &&\n prevMetadata.type === nextMetadata.type\n );\n }\n);\n```\n\n### 懒加载策略\n\n工作流节点面板支持懒加载标记：\n\n```tsx\nonChange={(activeKeys) => {\n if (Array.isArray(activeKeys) && activeKeys.includes('agent')) {\n agentNodesLazy.markAsRendered(node.id);\n }\n}}\n```\n\n## 相关子模块\n\n### 文档组件\n\n文档组件为画布提供富文本编辑能力：\n\n```tsx\n// packages/ai-workspace-common/src/components/document/index.tsx\n\n \n {!canvasReadOnly && }\n\n```\n\n### 集成文档模块\n\n画布支持通过 IntegrationDocsModal 展示外部集成文档：\n\n```tsx\n// packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx\n\n```\n\n### Webhook 配置\n\nWebhook 功能通过 WebhookConfigTab 提供配置界面：\n\n| 功能 | 描述 |\n|------|------|\n| Webhook URL 配置 | 设置接收数据的端点 |\n| 请求体预览 | 展示请求数据结构 |\n| 使用说明 | 提供集成指导 |\n\n资料来源：[webhook-config-tab.tsx]() 和 [webhook-docs-tab.tsx]()\n\n## 总结\n\nCanvas 画布组件是 refly 平台的核心交互界面，采用模块化、组件化的架构设计。通过 AgentNode、WorkflowNode、ArtifactRenderer 等核心组件的协同工作，为用户提供了强大的知识编排和工作流自动化能力。组件支持精细化的状态管理、国际化、主题切换和性能优化，是构建现代 AI 工作空间的重要基础设施。\n\n---\n\n\n\n## 富文本编辑器系统\n\n### 相关页面\n\n相关主题：[Canvas 画布组件](#page-canvas-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n
\n\n# 富文本编辑器系统\n\n## 概述\n\n富文本编辑器系统（Rich Text Editor System）是 refly 平台的核心组件之一，负责管理和渲染多种类型的内容，包括文档编辑、代码片段、思维导图、HTML内容等。该系统采用了基于 Tiptap/ProseMirror 的编辑器架构，支持实时协作和只读预览两种模式。\n\n编辑器的设计理念是将内容创作与内容展示分离，通过统一的渲染接口处理不同类型的内容，同时提供灵活的状态管理和上下文隔离机制。\n\n## 系统架构\n\n### 核心组件层次\n\n富文本编辑器系统采用分层架构设计，主要包含以下层次：\n\n| 层级 | 组件名称 | 职责说明 |\n|------|----------|----------|\n| 视图层 | DocumentEditor | 文档编辑器主容器，处理编辑/只读状态 |\n| 视图层 | CollaborativeEditor | 实时协作编辑器组件 |\n| 视图层 | ReadonlyEditor | 只读文档展示组件 |\n| 渲染层 | Renderer | 通用内容渲染器，根据类型分发 |\n| 渲染层 | ArtifactRenderer | 制品渲染器，管理多种内容格式 |\n| 渲染层 | MindMapRenderer | 思维导图专用渲染器 |\n| 渲染层 | HTMLRenderer | HTML内容渲染器 |\n| 存储层 | DocumentProvider | 文档上下文提供者 |\n| 状态层 | DocumentStore | 文档状态管理 |\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[DocumentEditor] --> B[DocumentProvider]\n B --> C[DocumentStore 状态管理]\n A --> D{isReadonly}\n D -->|true| E[ReadonlyEditor]\n D -->|false| F[CollaborativeEditor]\n F --> G[Tiptap Editor Core]\n G --> H[Extensions 扩展系统]\n H --> I[Table Extension]\n H --> J[Markdown Extension]\n H --> K[Custom Extensions]\n E --> L[Content Render]\n L --> M[Renderer 组件]\n M --> N{contentType}\n N -->|markdown| O[Markdown Renderer]\n N -->|code| O[Markdown Renderer]\n N -->|mindmap| P[MindMapRenderer]\n N -->|html| Q[HTMLRenderer]\n N -->|application| R[ArtifactRenderer]\n```\n\n## 文档编辑器组件\n\n### DocumentEditor 主组件\n\n`DocumentEditor` 是文档编辑器的核心入口组件，封装了文档编辑的主要逻辑：\n\n```tsx\nexport const DocumentEditor = memo(\n ({\n docId,\n shareId,\n readonly,\n nodeId,\n }: {\n docId: string;\n shareId?: string;\n readonly?: boolean;\n nodeId: string;\n }) => {\n const { resetState } = useDocumentStoreShallow((state) => ({\n resetState: state.resetState,\n }));\n const { readonly: canvasReadOnly } = useCanvasContext();\n\n useEffect(() => {\n return () => {\n resetState(docId);\n };\n }, []);\n\n return (\n \n {/* Editor Components */}\n \n );\n }\n);\n```\n\n**关键特性：**\n\n- 基于 `docId` 的文档隔离管理\n- 组件卸载时自动清理状态，防止内存泄漏\n- 支持 `shareId` 用于文档分享场景\n- 与 Canvas 上下文集成，继承只读状态\n\n### 编辑模式分支\n\n文档编辑器根据 `readonly` 属性决定渲染模式：\n\n```mermaid\ngraph LR\n A[DocumentEditor] --> B{readonly prop}\n B -->|false| C[CollaborativeEditor]\n B -->|true| D[ReadonlyEditor]\n C --> E[Tiptap Collaborative]\n D --> F[Static Render]\n```\n\n**CollaborativeEditor（协作编辑模式）：**\n- 启用实时协作功能\n- 支持多人同时编辑\n- 集成 Tiptap 核心编辑器引擎\n\n**ReadonlyEditor（只读模式）：**\n- 用于文档预览和分享\n- 优化渲染性能\n- 禁用编辑交互\n\n## 内容渲染系统\n\n### Renderer 组件\n\nRenderer 是统一的内容渲染入口，支持多种内容类型的分发渲染：\n\n| 内容类型 | 渲染组件 | 说明 |\n|----------|----------|------|\n| `text/markdown` | Markdown | 标准 Markdown 渲染 |\n| `application/refly.artifacts.code` | Markdown | 代码制品渲染 |\n| `application/refly.artifacts.mindmap` | MindMapRenderer | 思维导图渲染 |\n| `text/html` | HTMLRenderer | HTML 内容渲染 |\n| `application/*` (未知类型) | HTMLRenderer | 默认回退 |\n\n```tsx\ncase 'application/refly.artifacts.mindmap': {\n return (\n \n );\n}\n\ncase 'text/html': {\n return (\n \n );\n}\n```\n\n### 思维导图渲染\n\nMindMapRenderer 是专门用于思维导图内容的渲染组件，提供以下功能：\n\n- **缩放控制**：支持自定义宽高\n- **只读/编辑切换**：通过 `readonly` 属性控制\n- **变更回调**：通过 `onChange` 回调通知内容更新\n- **尺寸自适应**：根据容器自动调整\n\n### HTML 渲染\n\nHTMLRenderer 处理原生 HTML 内容，支持以下特性：\n\n- **预览模式**：通过 `purePreview` 控制预览样式\n- **操作按钮**：通过 `showActions` 显示操作按钮\n- **尺寸控制**：支持自定义宽高参数\n\n### ArtifactRenderer 制品渲染器\n\nArtifactRenderer 是专门处理 AI 生成制品的组件，提供增强的预览体验：\n\n```tsx\n
\n \n
\n```\n\n**制品渲染特性：**\n\n- 小地图预览模式：使用 `scale-[0.5]` 和 `w-[200%]` 实现缩略图效果\n- 主题适配：自动适配亮色/暗色主题\n- 语言感知：根据制品类型显示对应语法高亮\n- 修复请求：支持 `onRequestFix` 回调处理修复请求\n\n## 状态管理\n\n### DocumentStore\n\n文档状态管理采用 Zustand store 模式，主要职责包括：\n\n- **文档内容状态**：存储当前文档的内容数据\n- **编辑器状态**：跟踪编辑器的激活状态\n- **清理机制**：提供 `resetState` 方法用于组件卸载时清理\n\n```tsx\nconst { resetState } = useDocumentStoreShallow((state) => ({\n resetState: state.resetState,\n}));\n\nuseEffect(() => {\n return () => {\n resetState(docId);\n };\n}, []);\n```\n\n### DocumentProvider 上下文\n\nDocumentProvider 组件为子组件提供文档上下文信息，包括：\n\n- `docId`：文档唯一标识\n- `shareId`：分享标识（可选）\n- `readonly`：只读状态\n- `nodeId`：节点标识\n\n## 渲染状态与条件\n\n### 加载状态处理\n\n渲染器组件支持完整的加载状态管理：\n\n```tsx\nif (isLoading) {\n return (\n
\n
\n {t('pages.components.artifact.loading', {\n type: rendererType === 'document'\n ? t('common.document').toLowerCase()\n : t('pages.components.artifact.code').toLowerCase(),\n })}\n
\n
\n );\n}\n```\n\n### 生成状态处理\n\n对于正在生成的内容（如 AI 生成），渲染器显示生成中的状态：\n\n```tsx\nif (status === 'generating') {\n return (\n
\n
\n {t('pages.components.artifact.generating', { type: '' })}\n
\n
\n );\n}\n```\n\n### 空内容状态\n\n当没有选中内容时，显示提示信息：\n\n```tsx\n\n {t('pages.components.artifact.notSelected', {\n type: rendererType === 'document'\n ? t('common.document').toLowerCase()\n : t('pages.components.artifact.code').toLowerCase(),\n })}\n\n```\n\n## 组件 Memoization 优化\n\nRenderer 组件使用自定义相等性检查实现高效的 memoization：\n\n```tsx\nRenderer.displayName = 'Renderer';\n\nexport default memo(\n RendererComponent,\n (prevProps, nextProps) => {\n // Custom equality check for more effective memoization\n return (\n prevProps.content === nextProps.content &&\n prevProps.type === nextProps.type &&\n prevProps.readonly === nextProps.readonly &&\n prevProps.title === nextProps.title &&\n prevProps.language === nextProps.language &&\n prevProps.width === nextProps.width &&\n prevProps.height === nextProps.height &&\n prevProps.onChange === nextProps.onChange &&\n prevProps.showActions === nextProps.showActions &&\n prevProps.purePreview === nextProps.purePreview\n );\n }\n);\n```\n\n**Memoization 策略：**\n\n- 比较所有关键属性，避免不必要的重渲染\n- 函数引用比较使用稳定引用\n- 支持 props 变更时的精确控制\n\n## 主题与样式适配\n\n编辑器系统支持亮色/暗色主题自动适配：\n\n```tsx\nclassName={`h-full bg-white dark:bg-[var(--refly-bg-content-z2)]`}\n```\n\n样式变量映射：\n\n| 亮色主题 | 暗色主题 | 用途 |\n|----------|----------|------|\n| `bg-white` | `dark:bg-gray-900` | 主背景色 |\n| `bg-white` | `dark:bg-[var(--refly-bg-content-z2)]` | 内容区域背景 |\n| `text-gray-800` | `dark:text-white` | 主文本色 |\n| `text-gray-500` | `dark:text-gray-400` | 次要文本色 |\n\n## 资源预览集成\n\n编辑器系统与资源视图组件集成，支持文档、元数据展示：\n\n```tsx\n{resourceDetail?.data?.url && (\n \n {resourceDetail?.data?.url}\n \n)}\n```\n\n资源元数据组件提供：\n\n- 资源标题显示\n- URL 链接展示\n- 创建时间展示（相对时间格式）\n- 多语言时间格式化\n\n## API 参考\n\n### DocumentEditor Props\n\n| 属性名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `docId` | string | 是 | 文档唯一标识 |\n| `shareId` | string | 否 | 分享标识 |\n| `readonly` | boolean | 否 | 是否只读模式 |\n| `nodeId` | string | 是 | 关联节点标识 |\n\n### Renderer Props\n\n| 属性名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `content` | string | 是 | 内容文本 |\n| `type` | string | 是 | 内容 MIME 类型 |\n| `title` | string | 否 | 标题 |\n| `language` | string | 否 | 编程语言类型 |\n| `readonly` | boolean | 否 | 只读模式 |\n| `width` | string | 否 | 渲染宽度 |\n| `height` | string | 否 | 渲染高度 |\n| `showActions` | boolean | 否 | 显示操作按钮 |\n| `purePreview` | boolean | 否 | 纯预览模式 |\n| `onChange` | function | 否 | 内容变更回调 |\n| `onRequestFix` | function | 否 | 修复请求回调 |\n\n## 总结\n\n富文本编辑器系统是 refly 平台内容创作的核心基础设施，通过分层架构实现了编辑功能与渲染逻辑的解耦。系统支持多种内容类型的统一处理，提供了良好的状态管理和性能优化机制，同时适配亮色/暗色主题，满足不同使用场景的需求。\n\n该系统的设计遵循了以下原则：\n\n1. **关注点分离**：编辑逻辑与渲染逻辑独立\n2. **组件化**：每个功能模块都是可复用的组件\n3. **状态隔离**：基于 docId 的状态隔离机制\n4. **性能优先**：通过 memoization 减少不必要的重渲染\n5. **主题适配**：统一的深色模式支持\n\n---\n\n\n\n## 模型提供者系统\n\n### 相关页面\n\n相关主题：[工具系统](#page-tool-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/api/src/modules/provider/provider.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/provider/provider.service.ts)\n- [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)\n- [packages/providers/src/llm/index.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/llm/index.ts)\n- [packages/providers/src/types.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/types.ts)\n- [config/provider-catalog.json](https://github.com/refly-ai/refly/blob/main/config/provider-catalog.json)\n
\n\n# 模型提供者系统\n\n## 概述\n\n模型提供者系统（Model Provider System）是 Refly 平台的核心模块之一，负责管理与协调各类大语言模型（LLM）的接入、调用与路由。该系统通过统一的抽象层，为上层应用提供一致的模型调用接口，同时支持多模型提供商的动态切换与自动路由。\n\n系统的设计目标包括：\n\n- **统一抽象**：为不同模型提供商提供一致的调用接口\n- **动态路由**：根据任务需求自动选择最合适的模型\n- **配置管理**：集中管理模型提供商的配置与凭证\n- **成本优化**：支持模型混用以优化成本与性能\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[应用层 Application Layer] --> B[模型路由层 Model Router]\n B --> C[提供者服务层 Provider Service]\n C --> D[提供商适配器 Provider Adapters]\n \n D --> E[OpenAI]\n D --> F[Anthropic]\n D --> G[Google]\n D --> H[自定义 Provider]\n \n I[配置层 Config Layer] --> C\n I --> B\n \n J[类型定义 Types] --> B\n J --> C\n```\n\n### 核心组件\n\n| 组件名称 | 文件路径 | 职责描述 |\n|---------|---------|---------|\n| ProviderService | `apps/api/src/modules/provider/provider.service.ts` | 提供者服务的核心逻辑，管理模型实例的生命周期 |\n| AutoModelRouter | `apps/api/src/modules/provider/auto-model-router.service.ts` | 自动模型路由器，根据条件自动选择最优模型 |\n| LLM Providers | `packages/providers/src/llm/index.ts` | LLM 提供商的统一导出与初始化 |\n| Type Definitions | `packages/providers/src/types.ts` | 系统类型定义，包括 Provider、Model 等接口 |\n| Provider Catalog | `config/provider-catalog.json` | 模型提供商的配置文件，包含可用模型列表 |\n\n---\n\n## 类型系统\n\n系统定义了一套完整的类型体系，用于描述模型提供商的配置与行为。\n\n### 核心类型定义\n\n资料来源：[packages/providers/src/types.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/types.ts)\n\n```typescript\n// Provider 配置接口\ninterface ProviderConfig {\n provider: string; // 提供商标识符\n apiKey?: string; // API 密钥\n baseURL?: string; // 自定义端点\n models: ModelConfig[]; // 可用模型列表\n}\n\n// Model 配置接口\ninterface ModelConfig {\n name: string; // 模型名称\n enabled?: boolean; // 是否启用\n maxTokens?: number; // 最大 token 数\n temperature?: number; // 温度参数\n}\n```\n\n### Provider 枚举类型\n\n系统支持的主要模型提供商包括：\n\n| 提供商标识 | 说明 | 官方文档 |\n|-----------|------|---------|\n| `openai` | OpenAI GPT 系列 | https://platform.openai.com |\n| `anthropic` | Anthropic Claude 系列 | https://docs.anthropic.com |\n| `google` | Google Gemini 系列 | https://ai.google.dev |\n| `azure` | Azure OpenAI | https://azure.microsoft.com |\n| `ollama` | 本地 Ollama | https://ollama.ai |\n\n---\n\n## 提供者服务\n\n### ProviderService\n\n资料来源：[apps/api/src/modules/provider/provider.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/provider/provider.service.ts)\n\nProviderService 是模型提供者系统的核心服务类，负责：\n\n- **模型实例管理**：创建、缓存和销毁模型实例\n- **配置加载**：从配置文件或数据库加载 Provider 配置\n- **凭证管理**：安全存储和检索 API 密钥\n- **健康检查**：验证 Provider 连接状态\n\n```typescript\nclass ProviderService {\n // 初始化 Provider\n async initializeProvider(providerId: string): Promise;\n \n // 获取模型实例\n getModel(providerId: string, modelName: string): LLMModel;\n \n // 更新配置\n updateConfig(providerId: string, config: Partial): void;\n \n // 列出所有可用 Provider\n listProviders(): Provider[];\n}\n```\n\n### 服务初始化流程\n\n```mermaid\nsequenceDiagram\n participant App as 应用启动\n participant PS as ProviderService\n participant Config as 配置中心\n participant Adapter as Provider适配器\n\n App->>PS: 初始化请求\n PS->>Config: 加载 provider-catalog.json\n Config-->>PS: 返回提供商配置\n PS->>Adapter: 创建适配器实例\n Adapter-->>PS: 适配器就绪\n PS->>PS: 缓存模型实例\n PS-->>App: 服务就绪\n```\n\n---\n\n## 自动模型路由\n\n### AutoModelRouter\n\n资料来源：[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)\n\n自动模型路由器根据预设规则和运行时条件，自动选择最适合当前任务的模型。\n\n#### 路由策略\n\n| 策略类型 | 说明 | 适用场景 |\n|---------|------|---------|\n| `cost-optimized` | 优先选择成本最低的模型 | 日常任务、测试环境 |\n| `performance-first` | 优先选择性能最佳的模型 | 关键业务场景 |\n| `balanced` | 平衡成本与性能 | 一般生产环境 |\n| `latency-sensitive` | 优先选择响应最快的模型 | 实时交互场景 |\n\n#### 路由决策流程\n\n```mermaid\ngraph TD\n A[请求进入] --> B{检查缓存}\n B -->|命中| C[返回缓存模型]\n B -->|未命中| D{路由策略判断}\n D -->|成本优先| E[按成本排序]\n D -->|性能优先| F[按性能排序]\n D -->|均衡| G[综合评分排序]\n E --> H[选择最优模型]\n F --> H\n G --> H\n H --> I[调用模型]\n I --> J[缓存结果]\n```\n\n#### 路由规则配置\n\n```json\n{\n \"routingRules\": [\n {\n \"condition\": \"task.type === 'code-generation'\",\n \"preferredProvider\": \"openai\",\n \"preferredModel\": \"gpt-4o\"\n },\n {\n \"condition\": \"task.complexity > 0.8\",\n \"fallbackProviders\": [\"anthropic\", \"google\"]\n }\n ]\n}\n```\n\n---\n\n## LLM 提供商实现\n\n### 提供商包结构\n\n资料来源：[packages/providers/src/llm/index.ts](https://github.com/refly-ai/refly/blob/main/packages/providers/src/llm/index.ts)\n\n```typescript\n// LLM 提供商统一导出\nexport { OpenAIProvider } from './openai';\nexport { AnthropicProvider } from './anthropic';\nexport { GoogleProvider } from './google';\n\n// 工厂函数\nexport function createProvider(config: ProviderConfig): LLMProvider {\n switch (config.provider) {\n case 'openai':\n return new OpenAIProvider(config);\n case 'anthropic':\n return new AnthropicProvider(config);\n case 'google':\n return new GoogleProvider(config);\n default:\n throw new Error(`Unsupported provider: ${config.provider}`);\n }\n}\n```\n\n### 提供商适配器接口\n\n每个模型提供商都实现统一的适配器接口：\n\n```typescript\ninterface LLMProvider {\n // 模型标识\n readonly name: string;\n \n // 聊天完成\n chat(request: ChatRequest): Promise;\n \n // 流式聊天\n streamChat(request: ChatRequest): AsyncGenerator;\n \n // 获取模型列表\n listModels(): Promise;\n \n // 健康检查\n healthCheck(): Promise;\n}\n```\n\n---\n\n## 配置管理\n\n### Provider Catalog\n\n资料来源：[config/provider-catalog.json](https://github.com/refly-ai/refly/blob/main/config/provider-catalog.json)\n\nProvider Catalog 是系统配置的核心文件，定义了所有可用的模型提供商及其模型列表。\n\n#### 配置结构\n\n```json\n{\n \"version\": \"1.0\",\n \"providers\": [\n {\n \"id\": \"openai\",\n \"name\": \"OpenAI\",\n \"enabled\": true,\n \"models\": [\n {\n \"id\": \"gpt-4o\",\n \"name\": \"GPT-4o\",\n \"contextWindow\": 128000,\n \"inputCost\": 5.0,\n \"outputCost\": 15.0,\n \"capabilities\": [\"chat\", \"vision\", \"function-calling\"]\n }\n ]\n }\n ]\n}\n```\n\n#### 模型成本配置\n\n| 模型 | 上下文窗口 | 输入成本 ($/1M tokens) | 输出成本 ($/1M tokens) |\n|-----|----------|----------------------|----------------------|\n| gpt-4o | 128K | $5.00 | $15.00 |\n| gpt-4o-mini | 128K | $0.15 | $0.60 |\n| claude-3-5-sonnet | 200K | $3.00 | $15.00 |\n| claude-3-5-haiku | 200K | $0.80 | $4.00 |\n| gemini-2.0-flash | 1M | $0.00 | $0.00 |\n\n---\n\n## 使用示例\n\n### 基本调用流程\n\n```typescript\nimport { createProvider } from '@refly/providers';\n\n// 1. 创建 Provider 实例\nconst provider = createProvider({\n provider: 'openai',\n apiKey: process.env.OPENAI_API_KEY,\n});\n\n// 2. 发送聊天请求\nconst response = await provider.chat({\n model: 'gpt-4o',\n messages: [\n { role: 'system', content: '你是一个有帮助的助手。' },\n { role: 'user', content: '请解释什么是模型提供者系统。' }\n ],\n temperature: 0.7,\n});\n\n// 3. 处理响应\nconsole.log(response.content);\n```\n\n### 使用自动路由\n\n```typescript\nimport { AutoModelRouter } from '@refly/providers';\n\nconst router = new AutoModelRouter({\n strategy: 'balanced',\n fallbackEnabled: true,\n});\n\n// 自动选择最优模型\nconst result = await router.route({\n task: {\n type: 'reasoning',\n complexity: 0.8,\n },\n messages: conversationHistory,\n});\n```\n\n---\n\n## 最佳实践\n\n### 1. 模型选择建议\n\n| 任务类型 | 推荐模型 | 原因 |\n|---------|---------|------|\n| 代码生成 | GPT-4o, Claude 3.5 Sonnet | 上下文理解能力强 |\n| 创意写作 | GPT-4o, Claude 3.5 Sonnet | 生成质量高 |\n| 快速问答 | GPT-4o-mini, Claude 3.5 Haiku | 响应快、成本低 |\n| 长文本处理 | Claude 3.5 Sonnet, Gemini 2.0 Flash | 上下文窗口大 |\n\n### 2. 错误处理策略\n\n```typescript\nasync function withFallback(\n task: Task,\n messages: Message[]\n): Promise {\n const router = new AutoModelRouter();\n \n try {\n return await router.route({ task, messages });\n } catch (error) {\n if (error.code === 'RATE_LIMIT') {\n // 等待后重试或切换模型\n await delay(1000);\n return router.route({ task, messages, preferProvider: 'alternative' });\n }\n throw error;\n }\n}\n```\n\n### 3. 成本监控\n\n建议在生产环境中启用成本监控：\n\n```typescript\nconst router = new AutoModelRouter({\n onCostCalculated: (cost: CostInfo) => {\n metrics.track('model_cost', {\n provider: cost.provider,\n model: cost.model,\n inputTokens: cost.inputTokens,\n outputTokens: cost.outputTokens,\n totalCost: cost.totalCost,\n });\n },\n});\n```\n\n---\n\n## 相关文档\n\n- [API 参考文档](https://docs.refly.ai/api-reference)\n- [SDK 安装指南](https://docs.refly.ai/getting-started)\n- [模型定价说明](https://docs.refly.ai/pricing)\n- [安全与隐私政策](https://docs.refly.ai/about/privacy-policy)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：refly-ai/refly\n\n摘要：发现 22 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inq…。\n\n## 1. 安全/权限坑 · 来源证据：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inq…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inquiry\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0805b730bc2b4c5787cea36e55a118cd | https://github.com/refly-ai/refly/issues/2088 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v0.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c49752e8b10439aa5eda23446563b9f | https://github.com/refly-ai/refly/releases/tag/v0.5.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9680da63e17747a5afdc985701b56111 | https://github.com/refly-ai/refly/releases/tag/v0.7.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bde62a80a1994e2b89a9741dabace272 | https://github.com/refly-ai/refly/releases/tag/v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:759799529 | https://github.com/refly-ai/refly | host_targets=claude, claude_code, cursor\n\n## 6. 配置坑 · 来源证据：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91f612b63eef439ba150bafe81966117 | https://github.com/refly-ai/refly/issues/2278 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:759799529 | https://github.com/refly-ai/refly | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：Security findings in executable artifacts\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security findings in executable artifacts\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6f5d63839cda4472b1c2f6cb1213ef5f | https://github.com/refly-ai/refly/issues/2276 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v0.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.10.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eb88a44b5350452dbe311722dc4d806b | https://github.com/refly-ai/refly/releases/tag/v0.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：v0.4.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.4.2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_63bd65a5586242c8a4f52bad2217eb37 | https://github.com/refly-ai/refly/releases/tag/v0.4.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.6.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dd65b4699b5d40b994cbe193f304e92e | https://github.com/refly-ai/refly/releases/tag/v0.6.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v0.7.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.1\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_99e4528065d24170b07db348f8e8a81f | https://github.com/refly-ai/refly/releases/tag/v0.7.1 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9db6c700d2e04aef8d4dadd155fe94d3 | https://github.com/refly-ai/refly/releases/tag/v0.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.9.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49d03f2d9bf4459fa86662b339f44b6f | https://github.com/refly-ai/refly/releases/tag/v0.9.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6417649c1639474087639d2d86d6c84c | https://github.com/refly-ai/refly/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5e73e7f36609413094647d829f738f1e | https://github.com/refly-ai/refly/issues/2271 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | release_recency=unknown\n\n\n", "markdown_key": "refly", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:759799529", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/refly-ai/refly" }, { "evidence_id": "art_5616340c4bee475bb1f0aec0f82e5f79", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/refly-ai/refly#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "refly 说明书", "toc": [ "https://github.com/refly-ai/refly 项目说明书", "目录", "Refly 项目介绍", "1. 项目概述", "2. 项目架构", "3. 核心功能模块", "4. 布局系统", "5. CLI 命令行工具", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "330c01b123b85c8245d2e093eca4bb71585bbc6f", "repo_inspection_error": null, "repo_inspection_files": [ "pnpm-lock.yaml", "package.json", "README.md", "docs/index.md", "docs/pnpm-lock.yaml", "docs/package.json", "docs/README.md", "docs/scripts/convert-webp.js", "docs/.vitepress/config.ts", "docs/zh/index.md", "docs/.vitepress/theme/index.ts", "docs/zh/about/privacy-policy.md", "docs/zh/about/terms-of-service.md", "docs/zh/community/contact-us.md", "docs/zh/changelog/v0.4.2.md", "docs/zh/changelog/v0.7.0.md", "docs/zh/changelog/v0.2.3.md", "docs/zh/changelog/v0.4.0.md", "docs/zh/changelog/v1.1.0.md", "docs/zh/changelog/v0.2.2.md", "docs/zh/changelog/v0.4.1.md", "docs/zh/changelog/v0.5.0.md", "docs/zh/changelog/v0.7.1.md", "docs/zh/changelog/v0.2.1.md", "docs/zh/changelog/v0.1.1.md", "docs/zh/changelog/v0.6.0.md", "docs/zh/changelog/v0.2.4.md", "docs/zh/changelog/v0.1.2.md", "docs/zh/changelog/v0.8.0.md", "docs/zh/changelog/v0.9.0.md", "docs/zh/changelog/v0.2.0.md", "docs/zh/changelog/v0.3.0.md", "docs/zh/changelog/v0.10.0.md", "docs/zh/guide/api/webhook.md", "docs/zh/guide/api/openapi.md", "docs/zh/community-version/self-deploy/index.md", "docs/zh/community-version/self-deploy/faq-ip-access.md", "docs/en/about/privacy-policy.md", "docs/en/about/terms-of-service.md", "docs/en/community/contact-us.md" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# refly-monorepo - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 refly-monorepo 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`packages/cli/skill/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`packages/cli/skill/references/skill.md`, `packages/cli/skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/cli/README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `curl -X POST https://your-refly-instance.com/api/v1/workflows/{WORKFLOW_ID}/execute \\` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `curl https://your-refly-instance.com/api/v1/executions/{execution_id} \\` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install -g @powerformer/refly-cli` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx skills add refly-ai/` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npm install -g @refly/cli` 证据：`packages/cli/README.md` Claim：`clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`packages/cli/skill/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`packages/cli/skill/references/skill.md`, `packages/cli/skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/cli/README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`packages/cli/skill/SKILL.md`, `packages/cli/skill/references/skill.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/cli/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`packages/cli/skill/SKILL.md`, `packages/cli/skill/references/skill.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/cli/README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/cli/README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`packages/cli/skill/references/skill.md`, `packages/cli/skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/cli/README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1940\n- 重要文件覆盖：40/1940\n- 证据索引条目：80\n- 角色 / Skill 条目：2\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 refly-monorepo 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 refly-monorepo 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 refly-monorepo 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 2 个角色 / Skill / 项目文档条目。\n\n- **refly**（skill）：Base skill for Refly ecosystem: creates, discovers, and runs domain-specific skills bound to workflows. Routes user intent to matching domain skills via symlinks, delegates execution to Refly backend. Use when user asks to: create skills, run workflows, automate multi-step tasks, or manage pipelines. Triggers: refly, skill, workflow, run skill, create skill, automation, pipeline. Requires: @refly/cli installed and a… 激活提示：当用户任务与“refly”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/skill/SKILL.md`\n- **Skill Reference**（skill）：bash List skill packages refly skill list options --status Filter: draft, published, deprecated --mine Show only my packages --tags Filter by tags comma-separated --page Page number default: 1 --page-size Page size default: 20 激活提示：当用户任务与“Skill Reference”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/skill/references/skill.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Refly.AI Documentation**（documentation）：This repository contains the official documentation for Refly.AI https://refly.ai , an AI-native content creation platform built on the concept of \"Free Canvas\". The documentation site is built using VitePress https://vitepress.dev/ , a static site generator powered by Vue. 证据：`docs/README.md`\n- **Refly — Agent Skills Builder Powered by Vibe Workflow**（documentation）：Refly — Agent Skills Builder Powered by Vibe Workflow English · 中文 证据：`README.md`\n- **Refly API**（documentation）：Visit minio console on http://localhost:9001, with username and password specified in docker-compose.yml. 证据：`apps/api/README.md`\n- **Vector Search Service**（documentation）：A flexible, backend-agnostic vector search service that supports multiple vector database backends including Qdrant and LanceDB. 证据：`apps/api/src/modules/common/vector-search/README.md`\n- **Enhanced VectorFilter System**（documentation）：This document describes the enhanced VectorFilter system that provides compatibility with both Qdrant and LanceDB vector search backends. 证据：`apps/api/src/modules/common/vector-search/backend/README.md`\n- **Trace Stack - Local Observability Infrastructure**（documentation）：Trace Stack - Local Observability Infrastructure 证据：`deploy/docker/trace/README.md`\n- **React + TypeScript + Vite**（documentation）：This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. 证据：`packages/ai-workspace-common/README.md`\n- **@refly/cli**（documentation）：Refly CLI - Workflow orchestration for Claude Code 证据：`packages/cli/README.md`\n- **@refly/layout**（documentation）：A core layout component package for Refly AI Workspace, providing a complete page layout solution. This package adopts a slot-based rendering mode, supporting flexible layout configuration and context management. 证据：`packages/layout/README.md`\n- **@refly/utils**（documentation）：Refly Code Utils - A collection of utility functions for the Refly project. 证据：`packages/utils/README.md`\n- **Refly CLI One-Click Deployment**（documentation）：This directory contains scripts for quickly deploying and setting up Refly CLI for local development. 证据：`scripts/cli-deploy/README.md`\n- **PTC Debug Scripts**（documentation）：Python scripts for inspecting PTC Programmatic Tool Calling agent runs in the Refly database. 证据：`specs/current/ptc/scripts/README.md`\n- **Package**（package_manifest）：{ \"name\": \"refly-docs\", \"private\": true, \"type\": \"module\", \"scripts\": { \"dev\": \"vitepress dev\", \"build\": \"vitepress build\", \"preview\": \"vitepress preview\", \"convert-images\": \"node scripts/convert-webp.js\" }, \"devDependencies\": { \"@biomejs/biome\": \"^1.9.0\", \"sharp\": \"^0.33.5\", \"vitepress\": \"^1.5.0\" }, \"packageManager\": \"pnpm@10.30.2\" } 证据：`docs/package.json`\n- **Package**（package_manifest）：{ \"name\": \"refly-monorepo\", \"description\": \"Refly AI Monorepo\", \"version\": \"0.8.0\", \"private\": true, \"engines\": { \"pnpm\": \" =10\", \"node\": \" =24.0.0\" }, \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/refly-ai/refly.git\" }, \"scripts\": { \"commit\": \"cz\", \"dev\": \"turbo run dev\", \"start\": \"turbo run start\", \"build\": \"turbo run build\", \"build:api\": \"turbo run build --filter=@refly/api\", \"build:api:fast\": \"turbo run build:fast --filter=@refly/api\", \"build:web\": \"turbo run build --filter=@refly/web\", \"copy-package-dist\": \"node scripts/copy-package-dist.js\", \"copy-env\": \"turbo run copy-env\", \"copy-env:develop\": \"turbo run copy-env:develop\", \"codegen\": \"turbo run codegen\", \"generate:doc… 证据：`package.json`\n- **CONTRIBUTING**（documentation）：So you're looking to contribute to Refly - that's awesome, we can't wait to see what you do. Refly is the first open-source platform for building stable, atomic, and versioned agent skills. As an AI-native creation engine, we provide an intuitive free-form canvas interface to codify business logic into structured agent skills that any agent can invoke with 100% reliability. Any help from the community counts, truly. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@refly/api\", \"version\": \"0.8.0\", \"description\": \"API server for Refly\", \"author\": \"\", \"private\": true, \"license\": \"ReflyAI OpenSource License\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/refly-ai/refly.git\" }, \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"files\": \"dist/\", \"prisma/\", \"seed-data/\", \"scripts/\", \".env.development\", \".env.example\", \".node-options\", \".swcrc\" , \"scripts\": { \"copy-env\": \"ncp .env.example .env\", \"copy-env:develop\": \"ncp .env.development .env\", \"build\": \"prisma generate && node scripts/build.js --verbose && ncp prisma/ dist/prisma/\", \"build:fast\": \"prisma generate && node scripts/build.js --fast && ncp prisma/ dist/prisma/\", \"prisma:… 证据：`apps/api/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/web\", \"version\": \"1.0.0\", \"private\": true, \"type\": \"module\", \"scripts\": { \"build\": \"rsbuild build && npm run generate:sitemap\", \"build:analyze\": \"ANALYZE=true rsbuild build\", \"dev\": \"rsbuild dev\", \"preview\": \"rsbuild preview\", \"update:tokens\": \"node token/generate-css.cjs\", \"copy-env\": \"ncp .env.example .env\", \"copy-env:develop\": \"ncp .env.example .env\", \"generate:sitemap\": \"node scripts/generate-sitemap.js\", \"analyze:chunks\": \"node scripts/analyze-chunks.cjs\" }, \"dependencies\": { \"@ant-design/cssinjs\": \"^1.23.0\", \"@refly/stores\": \"workspace: \", \"@refly/telemetry-web\": \"workspace: \", \"@refly/ui-kit\": \"workspace: \", \"@refly/utils\": \"workspace: \", \"@refly/web-core\": \"workspa… 证据：`apps/web/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/agent-tools\", \"version\": \"0.1.0\", \"description\": \"Agent tools used by Refly\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"clean\": \"rimraf dist\", \"test\": \"vitest run\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@langchain/core\": \"1.1.4\", \"@notionhq/client\": \"^5.1.0\", \"@refly/common-types\": \"workspace: \", \"@refly/openapi-schema\": \"workspace: \", \"@refly/canvas-common\": \"workspace: \", \"@refly/utils\": \"workspace: \", \"apify-client\": \"^2.19.0\", \"zod\": \"^3.25.76\" }, \"devDependencies\": { \"@types/node\": \"^20.19.0\" } } 证据：`packages/agent-tools/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/ai-workspace-common\", \"private\": true, \"version\": \"0.8.0\", \"description\": \"Common components for Refly AI Workspace\", \"type\": \"module\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"sideEffects\": \" .css\", \" .scss\", \" .less\", \" .sass\", \" / .css\", \" / .scss\", \" / .less\", \" / .sass\" , \"exports\": { \".\": \"./src/index.ts\", \"./components\": \"./src/components/index.ts\", \"./components/ \": \"./src/components/ /index.ts\", \"./components/sider/ \": \"./src/components/sider/ .tsx\", \"./components/common/ \": \"./src/components/common/ .tsx\", \"./components/settings\": \"./src/components/settings/index.tsx\", \"./components/settings/ \": \"./src/components/settings/ .tsx\", \"./components/canvas\": \"… 证据：`packages/ai-workspace-common/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/canvas-common\", \"version\": \"0.7.0\", \"description\": \"Common canvas utilitized shared by UI and server\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"clean\": \"rimraf dist\", \"test\": \"vitest run\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@dagrejs/dagre\": \"^1.1.4\", \"@refly/common-types\": \"workspace: \", \"@refly/openapi-schema\": \"workspace: \", \"@refly/utils\": \"workspace: \", \"@xyflow/react\": \"^12.3.5\", \"zod\": \"^3.25.76\" }, \"devDependencies\": { \"@types/react\": \"^18.2.56\" } } 证据：`packages/canvas-common/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@powerformer/refly-cli\", \"version\": \"0.1.26\", \"description\": \"Refly CLI - Command-line interface for Refly workflow orchestration\", \"bin\": { \"refly\": \"./dist/bin/refly.js\" }, \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"scripts\": { \"build\": \"tsup\", \"build:dev\": \"REFLY BUILD ENV=dev tsup\", \"build:test\": \"REFLY BUILD ENV=test tsup\", \"build:staging\": \"REFLY BUILD ENV=staging tsup\", \"build:prod\": \"REFLY BUILD ENV=production tsup\", \"dev\": \"tsup --watch\", \"clean\": \"rimraf dist\", \"typecheck\": \"tsc --noEmit\", \"test\": \"vitest run\", \"prepublishOnly\": \"pnpm run build\" }, \"keywords\": \"refly\", \"cli\", \"workflow\", \"automation\" , \"author\": \"Refly AI\", \"license\": \"MIT\", \"dependencies\": {… 证据：`packages/cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/common-types\", \"version\": \"0.8.0\", \"description\": \"Refly Common Types\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@refly/openapi-schema\": \"workspace: \" }, \"devDependencies\": { \"react-scripts\": \"^5.0.1\" } } 证据：`packages/common-types/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/errors\", \"version\": \"0.8.0\", \"description\": \"Refly Predefined Errors\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"clean\": \"rimraf dist\", \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": {}, \"devDependencies\": {} } 证据：`packages/errors/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/i18n\", \"version\": \"0.8.0\", \"description\": \"Refly product translations\", \"author\": \"\", \"license\": \"ISC\", \"exports\": { \"./en-US\": { \"import\": \"./src/en-US/index.ts\", \"require\": \"./src/en-US/index.ts\", \"types\": \"./src/en-US/index.ts\" }, \"./zh-Hans\": { \"import\": \"./src/zh-Hans/index.ts\", \"require\": \"./src/zh-Hans/index.ts\", \"types\": \"./src/zh-Hans/index.ts\" } } } 证据：`packages/i18n/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/layout\", \"private\": true, \"version\": \"0.0.1\", \"description\": \"Layout for Refly AI Workspace\", \"type\": \"module\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"dependencies\": { \"react\": \"^18.2.0\", \"react-dom\": \"^18.2.0\", \"react-router-dom\": \"^6.22.1\", \"antd\": \"^5.20.0\", \"clsx\": \"^2.1.0\", \"@sentry/react\": \"^9.1.0\" }, \"devDependencies\": { \"@types/react\": \"^18.2.56\", \"@types/react-dom\": \"^18.2.19\", \"@refly/tsconfig\": \"workspace: \" } } 证据：`packages/layout/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/observability\", \"version\": \"0.1.0\", \"description\": \"Observability package for Refly with Langfuse integration\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsc --watch\", \"clean\": \"rm -rf dist\" }, \"dependencies\": { \"@langfuse/langchain\": \"^4.4.2\", \"@nestjs/common\": \"~10.3.9\", \"@opentelemetry/api\": \"^1.8.0\", \"@paralleldrive/cuid2\": \"^2.2.2\", \"langfuse\": \"^3.30.0\" }, \"peerDependencies\": { \"@langchain/core\": \" =0.3.0\" } } 证据：`packages/observability/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/openapi-schema\", \"version\": \"0.8.0\", \"description\": \"Refly OpenAPI Schema\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"dev\": \"nodemon\", \"codegen\": \"openapi-ts && tsc --build --verbose\", \"generate:docs\": \"tsx scripts/generate-docs.ts\", \"clean\": \"rimraf dist && rimraf tsconfig.tsbuildinfo\", \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\", \"postinstall\": \"tsc --build --verbose\" }, \"devDependencies\": { \"@hey-api/openapi-ts\": \"0.53.8\", \"tsx\": \"^4.19.4\", \"yaml\": \"^2.6.1\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@hey-api/client-fetch\": \"0.4.0\" } } 证据：`packages/openapi-schema/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/providers\", \"version\": \"0.8.0\", \"description\": \"Implementation of Refly providers\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"clean\": \"rimraf dist && rimraf tsconfig.tsbuildinfo\", \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@langchain/aws\": \"1.1.0\", \"@langchain/community\": \"0.3.50\", \"@langchain/core\": \"1.1.4\", \"@langchain/ollama\": \"^0.2.0\", \"@langchain/openai\": \"0.6.7\", \"@langchain/google-vertexai\": \"^2.1.2\", \"@refly/errors\": \"workspace: \", \"@refly/openapi-schema\": \"workspace: \", \"@refly/utils\": \"workspace: \", \"langfuse\": \"^3.6.0\" } } 证据：`packages/providers/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/sandbox-agent\", \"version\": \"1.0.0\", \"description\": \"TypeScript implementation of code interpreter with LangChain\", \"main\": \"dist/src/index.js\", \"types\": \"dist/src/index.d.ts\", \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsx watch src/index.ts\", \"start\": \"node dist/index.js\", \"test\": \"jest\", \"lint\": \"eslint . --ext .ts\", \"format\": \"prettier --write \\\" / .ts\\\"\", \"run-example\": \"tsx ./examples/example.ts\" }, \"keywords\": \"code-interpreter\", \"langchain\", \"typescript\", \"ai\", \"llm\" , \"author\": \"\", \"license\": \"MIT\", \"dependencies\": { \"@langchain/anthropic\": \"0.3.33\", \"@langchain/core\": \"1.1.4\", \"@langchain/openai\": \"0.6.7\", \"axios\": \"^1.7.0\", \"dotenv\": \"^16.4.0\", \"langchain\": \"0.3.30\", \"… 证据：`packages/sandbox-agent/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/skill-template\", \"version\": \"0.8.0\", \"description\": \"Refly Skill Template\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"scripts\": { \"clean\": \"rimraf dist && rimraf tsconfig.tsbuildinfo\", \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@dmitryrechkin/json-schema-to-zod\": \"^1.0.1\", \"@langchain/core\": \"1.1.4\", \"@langchain/langgraph\": \"0.2.45\", \"@langchain/openai\": \"0.6.7\", \"@modelcontextprotocol/sdk\": \"^1.10.1\", \"@refly/agent-tools\": \"workspace: \", \"@refly/openapi-schema\": \"workspace: \", \"@refly/providers\": \"workspace: \", \"@refly/utils\": \"workspace: \", \"debug\": \"^4.3.5\", \"eventsource\": \"^3.0.6\", \"… 证据：`packages/skill-template/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/stores\", \"private\": true, \"version\": \"0.0.1\", \"description\": \"Stores for Refly AI Workspace\", \"type\": \"module\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"dependencies\": { \"@refly/common-types\": \"workspace: \", \"@refly/openapi-schema\": \"workspace: \", \"@refly/canvas-common\": \"workspace: \", \"zustand\": \"~4.5.1\", \"immer\": \"^10.1.1\", \"react\": \"^18.2.0\", \"@xyflow/react\": \"^12.3.5\" }, \"devDependencies\": { \"@refly/tsconfig\": \"workspace: \", \"@types/react\": \"^18.2.66\", \"typescript\": \"^5.4.5\" } } 证据：`packages/stores/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/telemetry-node\", \"private\": true, \"version\": \"0.0.1\", \"description\": \"Telemetry utilities for Refly.AI Node.js App\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"dependencies\": { \"@statsig/statsig-node-core\": \"^0.6.1\" }, \"devDependencies\": { \"@refly/tsconfig\": \"workspace: \" } } 证据：`packages/telemetry-node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/telemetry-web\", \"private\": true, \"version\": \"0.0.1\", \"description\": \"Telemetry utilities for Refly.AI Web App\", \"type\": \"module\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"dependencies\": { \"@refly/utils\": \"workspace: \", \"@statsig/js-client\": \"^3.19.0\", \"@statsig/session-replay\": \"^3.19.0\", \"@statsig/web-analytics\": \"^3.19.0\", \"js-cookie\": \"^3.0.5\" }, \"devDependencies\": { \"@refly/tsconfig\": \"workspace: \", \"@types/js-cookie\": \"^3.0.6\" } } 证据：`packages/telemetry-web/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/tsconfig\", \"version\": \"0.0.0\", \"private\": true, \"license\": \"MIT\", \"publishConfig\": { \"access\": \"public\" }, \"devDependencies\": {} } 证据：`packages/tsconfig/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/ui-kit\", \"private\": true, \"version\": \"0.0.1\", \"description\": \"UI Kit for Refly AI Workspace\", \"type\": \"module\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"dependencies\": { \"@ant-design/cssinjs\": \"^1.23.0\", \"@ant-design/icons\": \"^5.5.2\", \"@refly/common-types\": \"workspace: \", \"@refly/utils\": \"workspace: \", \"antd\": \"^5.21.5\", \"clsx\": \"^2.1.0\", \"react\": \"^18.2.0\", \"react-dom\": \"^18.2.0\", \"react-i18next\": \"^15.6.0\", \"react-use\": \"^17.5.0\", \"zustand\": \"~4.5.1\" }, \"devDependencies\": { \"@refly/tsconfig\": \"workspace: \", \"@types/react\": \"^18.2.56\", \"@types/react-dom\": \"^18.2.19\" } } 证据：`packages/ui-kit/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/utils\", \"version\": \"0.8.0\", \"description\": \"Refly Code Utils\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"exports\": { \".\": \"./src/index.ts\", \"./token\": \"./src/token.ts\" }, \"typesVersions\": { \" \": { \"token\": \"src/token.ts\" } }, \"scripts\": { \"clean\": \"rimraf dist && rimraf tsconfig.tsbuildinfo\", \"test\": \"vitest run\", \"test:run\": \"vitest run\", \"test:coverage\": \"vitest run --coverage\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@paralleldrive/cuid2\": \"^2.2.2\", \"@refly/common-types\": \"workspace: \", \"@refly/openapi-schema\": \"workspace: \", \"@tiptap/pm\": \"2.7.4\", \"cheerio\": \"~1.0.0\", \"clsx\": \"^2.1.0\", \"deepmerge\": \"^4.3.1\", \"linkify-it\": \"^5.0.0\", \"m… 证据：`packages/utils/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@refly/web-core\", \"private\": true, \"version\": \"0.0.1\", \"description\": \"Web Core for Refly AI Workspace\", \"type\": \"module\", \"main\": \"src/index.ts\", \"types\": \"src/index.ts\", \"sideEffects\": \" .css\", \" .scss\", \" .less\", \" .sass\", \" / .css\", \" / .scss\", \" / .less\", \" / .sass\" , \"dependencies\": { \"@ant-design/icons\": \"^5.5.2\", \"@refly/canvas-common\": \"workspace: \", \"@rjsf/validator-ajv8\": \"^6.1.1\", \"@rjsf/utils\": \"^6.1.1\", \"@refly/common-types\": \"workspace: \", \"@refly/errors\": \"workspace: \", \"@refly/i18n\": \"workspace: \", \"@refly/openapi-schema\": \"workspace: \", \"@refly/stores\": \"workspace: \", \"@refly/telemetry-web\": \"workspace: \", \"@refly/ui-kit\": \"workspace: \", \"@refly/utils\": \"workspa… 证据：`packages/web-core/package.json`\n- **Refly**（skill_instruction）：1. CLI only - Use refly , never call API directly. 2. Trust JSON - Only trust CLI JSON ok , payload , error , hint . 3. No fabricated IDs - Never invent workflow/run/node IDs. 4. No tokens - Never print or request auth tokens. 5. Stop on error - If ok=false , stop and show hint . 证据：`packages/cli/skill/SKILL.md`\n- **Skill Reference**（skill_instruction）：bash List skill packages refly skill list options --status Filter: draft, published, deprecated --mine Show only my packages --tags Filter by tags comma-separated --page Page number default: 1 --page-size Page size default: 20 证据：`packages/cli/skill/references/skill.md`\n- **Open Source License**（source_file）：Refly is licensed under the Apache License 2.0, with the following additional conditions: 证据：`LICENSE`\n- **Refly — The First Open-Source Agent Skills Builder Powered by Vibe Workflow**（documentation）：! Refly Cover /images/refly-cover.webp 证据：`docs/index.md`\n- **FAQ: Accessing via IP address**（documentation）：If you are deploying Refly on a cloud server and accessing it via http:// :5700 , you might encounter issues with redirection after login. This is caused by mismatched Cookie domain configurations. 证据：`docs/community-version/self-deploy/faq-ip-access.md`\n- **Self Deploy**（documentation）：Hardware Requirements { hardware-requirements} 证据：`docs/community-version/self-deploy/index.md`\n- **Refly AI Privacy Policy**（documentation）：Effective Date: September 26, 2025 Last Updated: October 16, 2025 Updated for Google Workspace Restricted Scopes Review 证据：`docs/en/about/privacy-policy.md`\n- **Terms of Service**（documentation）：Please read these Terms of Service \"Terms\" carefully before using the Refly AI Content Creation Engine the \"Service\" operated by ReflyAI \"us\", \"we\", \"our\", or \"Company\" . 证据：`docs/en/about/terms-of-service.md`\n- **v0.1.1 Release Notes**（documentation）：- Canvas Management in Sidebar : The sidebar now supports the deletion of canvases and can expand to display up to 10 canvases. It also includes hover functionality to display list element menus. - Node Connection Management : Default node connections can be hidden, with connections still visible when hovering over a node. Users can toggle node connections on or off to reduce clutter on the canvas. - Canvas Update Synchronization : The canvas now displays update synchronization status, reducing user concerns about unclear data saving. - Enhanced Text Import : The limit for plain text copy and paste import has been increased from 6,000 to 100,000 characters, supporting the import of larger t… 证据：`docs/en/changelog/v0.1.1.md`\n- **v0.1.2 Release Notes**（documentation）：- Supports deleting canvases from the sidebar and expanding to display up to 10 canvases, with hover display of list element menus. - Supports default hiding of node connections, with connections still visible when hovering over nodes, and toggleable node connections to reduce canvas clutter. - Supports displaying the update synchronization status of canvases to alleviate user concerns about data saving. - Supports expanding the import of plain text from 6,000 to 100,000 characters, enabling the import of larger text content. 证据：`docs/en/changelog/v0.1.2.md`\n- **🚀 Refly 0.10.0 Release Notes**（documentation）：A milestone update focused on seamless creativity, intelligent workflows, and uninterrupted creation. 证据：`docs/en/changelog/v0.10.0.md`\n- **v0.2.0 Release Notes**（documentation）：Refly is about to release a new major version v0.2.0, which supports 8+ significant new capabilities. It fully supports AI + canvas for a more intuitive and easy-to-understand operation experience, and greatly optimizes the canvas performance, aiming to match the usage experience of Native/local Apps. Here are some introductions to the core capabilities: 证据：`docs/en/changelog/v0.2.0.md`\n- **v0.2.1 Release Notes**（documentation）：Refly has released 5+ new features in version 0.2.1, optimized 10+ core key issues, and resolved 7+ basic problems/Bugs. The core focus of this release is: the official launch of tiered paid subscription features Free/Pro/Max , with a 2-month gift for the first year and an additional 50% discount 🔥, unlimited use of Claude 3.5 Sonnet/GPT-4o for just $8.3 per month, time is limited, so those who need it can hurry up and subscribe 🐛; at the same time, the AI interaction capabilities of Memo nodes have been significantly enhanced, multiple user experiences have been optimized such as multi-select nodes, canvas renaming, etc. , and key issues such as login status, network connection, and white… 证据：`docs/en/changelog/v0.2.1.md`\n- **v0.2.2 Release Notes**（documentation）：Refly has introduced several important updates in version 0.2.2, including product pricing, documentation experience, and core functionality optimizations . 证据：`docs/en/changelog/v0.2.2.md`\n- **v0.2.2 Release Notes**（documentation）：🌟 Completely upgraded product onboarding experience, optimized pricing plans, and provided more intuitive knowledge base display, while fixing multiple core usage issues to make the product simpler and more stable! 证据：`docs/en/changelog/v0.2.3.md`\n- **v0.2.4 Release Notes**（documentation）：🌟 Introducing the powerful DeepSeek R1 inference model, enhancing knowledge Q&A, AI deep search, and document generation capabilities. Special offer: Subscribe now to lock in permanent discount pricing! 证据：`docs/en/changelog/v0.2.4.md`\n- **v0.3.0 Changelog**（documentation）：🎉 Major Refly update! Comprehensive upgrades include enhanced knowledge base file processing supporting 7+ mainstream formats , AI multimodal interaction supporting multiple image inputs , new DeepSeek R1 chain-of-thought visualization, and improved canvas editing with undo/redo . Experience smoother and more efficient knowledge management and content creation! 证据：`docs/en/changelog/v0.3.0.md`\n- **v0.4.0 Release Notes**（documentation）：::: warning ⚠️ Important Notice: Refly Price Adjustment Coming Soon! Buy Now for Better Value! 证据：`docs/en/changelog/v0.4.0.md`\n- **v0.4.1 Release Notes**（documentation）：🚀 Experience the power of next-generation AI creation with Refly v0.4.1! This game-changing update revolutionizes how you interact with AI through: 证据：`docs/en/changelog/v0.4.1.md`\n- **v0.4.2 Release Notes**（documentation）：🚀 Refly v0.4.2 has arrived with major feature upgrades and experience improvements: 证据：`docs/en/changelog/v0.4.2.md`\n- **v0.5.0 Release Notes**（documentation）：Refly Major Update: Added 2+ open source contributors, 10+ practical templates, comprehensive upgrades to knowledge base partition management, linear conversations, mind maps, and document outline features, while optimizing canvas performance to support dozens of nodes with smooth operation, creating a more powerful AI-native creation platform! 证据：`docs/en/changelog/v0.5.0.md`\n- **v0.6.0 Release Notes**（documentation）：Refly Major Update: Added custom model configuration, one-click cloud deployment, redesigned homepage, presentation functionality, batch image processing and document export features, while optimizing performance and user experience to create a more efficient and stable AI-native creation platform! 证据：`docs/en/changelog/v0.6.0.md`\n- **v0.7.0 Release Notes**（documentation）：We're thrilled to announce the official release of Refly v0.7.0, marking an exciting new chapter for our platform! 🎉 证据：`docs/en/changelog/v0.7.0.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `README.md`, `apps/api/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `README.md`, `apps/api/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Refly 项目介绍**：importance `high`\n - source_paths: README.md, README_CN.md\n- **技术栈概览**：importance `high`\n - source_paths: apps/api/package.json, apps/web/package.json, packages/tsconfig/base.json\n- **系统整体架构**：importance `high`\n - source_paths: apps/api/src/modules/app.module.ts, apps/web/src/App.tsx, pnpm-workspace.yaml, turbo.json\n- **API 模块总览**：importance `high`\n - source_paths: apps/api/src/modules, apps/api/prisma/schema.prisma\n- **工作流系统**：importance `high`\n - source_paths: apps/api/src/modules/workflow/workflow.service.ts, apps/api/src/modules/workflow/workflow.processor.ts, apps/api/src/modules/schedule/schedule.service.ts, packages/canvas-common/src/workflow.ts\n- **工具系统**：importance `high`\n - source_paths: apps/api/src/modules/tool/tool.service.ts, apps/api/src/modules/tool/ptc/ptc-sdk.service.ts, apps/api/src/modules/tool/sandbox/scalebox.service.ts, apps/api/src/modules/tool/handlers/handlers.module.ts, packages/agent-tools/src/index.ts\n- **认证与授权系统**：importance `high`\n - source_paths: apps/api/src/modules/auth/auth.service.ts, apps/api/src/modules/auth/api-key.service.ts, apps/api/src/modules/auth/strategy/google-oauth.strategy.ts, apps/api/src/modules/auth/guard/jwt-auth.guard.ts\n- **Canvas 画布组件**：importance `high`\n - source_paths: packages/ai-workspace-common/src/components/canvas/index.tsx, packages/ai-workspace-common/src/components/canvas/nodes/index.ts, packages/ai-workspace-common/src/components/canvas/copilot/index.tsx, packages/canvas-common/src/data.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `330c01b123b85c8245d2e093eca4bb71585bbc6f`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/index.md`, `docs/pnpm-lock.yaml`, `docs/package.json`, `docs/README.md`, `docs/scripts/convert-webp.js`, `docs/.vitepress/config.ts`, `docs/zh/index.md`, `docs/.vitepress/theme/index.ts`, `docs/zh/about/privacy-policy.md`, `docs/zh/about/terms-of-service.md`, `docs/zh/community/contact-us.md`, `docs/zh/changelog/v0.4.2.md`, `docs/zh/changelog/v0.7.0.md`, `docs/zh/changelog/v0.2.3.md`, `docs/zh/changelog/v0.4.0.md`, `docs/zh/changelog/v1.1.0.md`, `docs/zh/changelog/v0.2.2.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inq…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inquiry\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_0805b730bc2b4c5787cea36e55a118cd | https://github.com/refly-ai/refly/issues/2088 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：v0.5.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.5.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0c49752e8b10439aa5eda23446563b9f | https://github.com/refly-ai/refly/releases/tag/v0.5.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v0.7.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_9680da63e17747a5afdc985701b56111 | https://github.com/refly-ai/refly/releases/tag/v0.7.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.8.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_bde62a80a1994e2b89a9741dabace272 | https://github.com/refly-ai/refly/releases/tag/v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:759799529 | https://github.com/refly-ai/refly | host_targets=claude, claude_code, cursor\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_91f612b63eef439ba150bafe81966117 | https://github.com/refly-ai/refly/issues/2278 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:759799529 | https://github.com/refly-ai/refly | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: 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.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：refly-ai/refly\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：claude, claude_code, cursor\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Question] Sandbox deployment fails with \"AggregateError: All promises were rejected\" - Scalebox template and setup inq…（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v0.5.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.7.0（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.8.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/refly-ai/refly 项目说明书\n\n生成时间：2026-05-13 11:54:39 UTC\n\n## 目录\n\n- [Refly 项目介绍](#page-introduction)\n- [技术栈概览](#page-tech-stack)\n- [系统整体架构](#page-system-architecture)\n- [API 模块总览](#page-module-overview)\n- [工作流系统](#page-workflow-system)\n- [工具系统](#page-tool-system)\n- [认证与授权系统](#page-auth-system)\n- [Canvas 画布组件](#page-canvas-components)\n- [富文本编辑器系统](#page-editor-system)\n- [模型提供者系统](#page-provider-system)\n\n\n\n## Refly 项目介绍\n\n### 相关页面\n\n相关主题：[技术栈概览](#page-tech-stack), [系统整体架构](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/refly-ai/refly/blob/main/README.md)\n- [packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n- [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)\n- [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)\n- [packages/stores/src/stores/canvas.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/canvas.ts)\n- [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)\n- [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)\n- [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)\n
\n\n# Refly 项目介绍\n\n## 1. 项目概述\n\nRefly 是一个基于 AI 的可视化工作流构建平台，旨在帮助用户通过直观的拖拽式画布界面创建和编排 AI 工作流。该项目采用 Monorepo 架构，包含了前端画布组件、AI Copilot 智能助手、命令行工具、API 服务等多个子包和应用。\n\nRefly 的核心价值在于降低 AI 工作流构建的门槛，让用户无需编写代码即可组合各种 AI 能力，创建复杂的自动化任务流程。\n\n## 2. 项目架构\n\n### 2.1 Monorepo 结构概览\n\n```\nrefly/\n├── apps/\n│ ├── api/ # 后端 API 服务\n│ │ └── src/modules/\n│ │ ├── workflow-app/ # 工作流相关模块\n│ │ └── voucher/ # 优惠券/凭证系统\n│ └── web/ # Web 应用\n├── packages/\n│ ├── ai-workspace-common/ # AI 工作空间通用组件\n│ │ └── src/components/\n│ │ ├── canvas/ # 画布核心组件\n│ │ │ ├── nodes/ # 节点类型（代码工件、技能响应等）\n│ │ │ ├── webhook/ # Webhook 配置\n│ │ │ └── top-toolbar/ # 顶部工具栏\n│ │ ├── pure-copilot/ # 纯 AI 助手组件\n│ │ ├── markdown/ # Markdown 渲染\n│ │ ├── slideshow/ # 幻灯片展示\n│ │ └── resource-view/ # 资源视图\n│ ├── stores/ # 状态管理 (Zustand)\n│ │ └── src/stores/\n│ │ ├── canvas.ts # 画布状态\n│ │ └── import-resource.ts\n│ ├── web-core/ # Web 核心功能\n│ ├── layout/ # 页面布局组件\n│ └── cli/ # 命令行工具\n```\n\n### 2.2 技术栈\n\n| 层级 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | React + TypeScript | 主要开发语言 |\n| UI 组件库 | Ant Design | 基础 UI 组件 |\n| 样式方案 | Tailwind CSS | 原子化 CSS |\n| 状态管理 | Zustand | 轻量级状态管理 |\n| 画布引擎 | React Flow | 可视化流程图库 |\n| 国际化 | i18next | 多语言支持 |\n| 后端 | Node.js | API 服务 |\n| CLI | TypeScript | 命令行工具 |\n\n## 3. 核心功能模块\n\n### 3.1 Canvas 画布系统\n\nCanvas 是 Refly 的核心功能模块，提供可视化的 AI 工作流编辑界面。\n\n#### 3.1.1 画布交互配置\n\n```typescript\n\n```\n\n#### 3.1.2 画布状态管理\n\nCanvas 状态通过 Zustand store 统一管理：\n\n```typescript\n// packages/stores/src/stores/canvas.ts\nconst defaultCanvasState = () => ({\n config: {},\n currentCanvasId: null,\n initialFitViewCompleted: false,\n operatingNodeId: null,\n showEdges: true,\n nodeSizeMode: 'compact' as const,\n showTemplates: true,\n showSlideshow: false,\n linearThreadMessages: [],\n tplConfig: null,\n canvasPage: {},\n contextMenuOpenedCanvasId: null,\n canvasTitle: {},\n canvasInitialized: {},\n canvasInitializedAt: {},\n canvasExecutionId: {},\n canvasNodeExecutions: {},\n canvasVariables: {},\n});\n```\n\n### 3.2 节点类型系统\n\nRefly 画布支持多种类型的节点，用于构建不同功能的 AI 工作流。\n\n#### 3.2.1 CodeArtifactNode 代码工件节点\n\n用于展示和编辑代码生成结果：\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx\n {}}\n showActions={false}\n/>\n```\n\n#### 3.2.2 ActionStep 技能执行步骤\n\n展示 AI 技能执行过程中的日志和状态：\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx\nitems={logs.map((log) => ({\n title: t(`${log.key}.title`, { ...log.titleArgs, ns: 'skillLog' }),\n description: t(`${log.key}.description`, { ...log.descriptionArgs, ns: 'skillLog' }),\n status: log.status === 'error' ? 'error' : 'finish',\n}))}\n```\n\n### 3.3 Pure Copilot 智能助手\n\nPure Copilot 是 Refly 内置的 AI 助手组件，支持自然语言交互和文件处理。\n\n#### 3.3.1 组件功能\n\n- **文件拖拽上传**：支持拖拽文件到输入区域\n- **上下文管理**：管理已上传的文件列表\n- **消息发送**：支持 @ 提及特定工具集\n- **多语言国际化**：内置中文和英文提示文本\n\n```typescript\n// packages/ai-workspace-common/src/components/pure-copilot/index.tsx\nconst { query, setQuery, setContextItems, setSelectedToolsets } =\n useAgentNodeManagement(nodeId);\nconst { connectToUpstreamAgent } = useAgentConnections();\nconst { data: workflowVariables } = useVariablesManagement(canvasId);\n```\n\n### 3.4 Webhook 集成\n\nRefly 支持 Webhook 配置，允许用户将工作流与其他系统集成。\n\n#### 3.4.1 Webhook 配置界面\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx\n
\n {t('webhook.instructions')}\n
    \n
  • {t('webhook.instruction1')}
    • \n
  • {t('webhook.instruction2')}
    • \n
  • {t('webhook.instruction3')}
    • \n
\n
\n```\n\n### 3.5 模板市场与优惠券系统\n\nRefly 包含完整的创作者激励机制，包括模板市场和折扣券系统。\n\n#### 3.5.1 多语言邮件模板\n\n```typescript\n// apps/api/src/modules/voucher/voucher-email-templates.ts\nexport function generateVoucherEmail(\n data: VoucherEmailData,\n locale?: string,\n): { subject: string; html: string } {\n // 检查语言环境是否为中文\n const isChineseLocale = locale?.toLowerCase().startsWith('zh');\n \n if (isChineseLocale) {\n return generateVoucherEmailZH(data);\n }\n return generateVoucherEmailEN(data);\n}\n```\n\n#### 3.5.2 邮件内容结构\n\n| 区域 | 中文内容 | 英文内容 |\n|------|----------|----------|\n| 标题 | 恭喜获得专属折扣！ | Congratulations on Your Exclusive Discount! |\n| 称呼 | ${userName}，您好！ | Hello ${userName}! |\n| 描述 | 感谢您在 Refly.ai 上发布模板！为表感谢，这是专属于您的折扣奖励。 | Thank you for publishing a template on Refly.ai! As a token of appreciation, here's your exclusive discount reward. |\n| 底部 | Refly.ai 团队 | Refly.ai Team |\n\n### 3.6 调度系统 (Schedule)\n\nRefly 支持工作流的定时调度功能，包含完整的调度限制和模态框交互。\n\n#### 3.6.1 调度限制模态框\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx\n setScheduleLimitModalVisible(false)}>\n {t('common.cancel') || 'Cancel'}\n ,\n ,\n ]}\n>\n

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

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

Hi ${data.userName},

\n

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

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