{ "canonical_name": "refly-ai/refly", "compilation_id": "pack_92c006a1400d4693b96eb4ba2dffe72e", "created_at": "2026-05-19T05:22:34.879386+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": "tool-integrations", "confidence": "high", "name_en": "Tool Integrations", "name_zh": "工具连接与集成", "reason": "strong category phrase match from project identity and outcome" }, "target_user": "使用 claude, claude_code, cursor 等宿主 AI 的用户", "title_en": "refly", "title_zh": "refly 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Natural-language Web Actions", "label_zh": "自然语言网页操作", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-natural-language-web-actions", "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": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "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": [ "浏览器 Agent", "网页任务自动化", "自然语言网页操作", "节点式流程编排", "评测体系" ], "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_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": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.9.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_9db6c700d2e04aef8d4dadd155fe94d3 | https://github.com/refly-ai/refly/releases/tag/v0.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.9.0", "user_impact": "可能影响授权、密钥配置或安全边界。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 21 个潜在踩坑项，其中 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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for refly-ai/refly.\n\nProject:\n- Name: refly\n- Repository: https://github.com/refly-ai/refly\n- Summary: 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.\n- Host target: claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 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.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. project-introduction: Project Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. quick-start-guide: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. workflow-engine: Workflow Engine. Produce one small intermediate artifact and wait for confirmation.\n5. skill-management: Skill Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- packages/skill-template/src/base.ts\n- docs/community-version/self-deploy/index.md\n- packages/cli/src/commands/workflow/index.ts\n- apps/api/src/app.module.ts\n- apps/api/src/main.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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": "link", "name": "refly 能力包", "risk": "可发布", "slug": "refly", "stars": 7292, "tags": [ "浏览器 Agent", "网页任务自动化", "自然语言网页操作", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/refly-ai/refly 项目说明书\n\n生成时间：2026-05-15 13:25:24 UTC\n\n## 目录\n\n- [Project Introduction](#project-introduction)\n- [Quick Start Guide](#quick-start-guide)\n- [System Architecture](#system-architecture)\n- [Project Structure](#project-structure)\n- [Workflow Engine](#workflow-engine)\n- [Skill Management](#skill-management)\n- [Canvas Component](#canvas-component)\n- [Copilot Integration](#copilot-integration)\n- [API Modules](#api-modules)\n- [Authentication and Authorization](#authentication)\n\n\n\n## Project Introduction\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Quick Start Guide](#quick-start-guide)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/refly-ai/refly/blob/main/README.md)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n- [packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\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- [apps/api/src/modules/workflow-app/email-templates.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow-app/email-templates.ts)\n
\n\n# Project Introduction\n\n## Overview\n\nRefly.ai is a comprehensive workflow automation platform designed for developers and creators. The platform enables users to build, schedule, and automate workflows through a visual canvas interface combined with AI-powered capabilities. Refly.ai provides integrations with popular development tools and supports programmatic access through REST APIs and a Command Line Interface (CLI).\n\n资料来源：[README.md](https://github.com/refly-ai/refly/blob/main/README.md)\n\n## Architecture\n\nThe platform follows a modular monorepo architecture with multiple packages organized under a unified structure.\n\n### Package Structure\n\n| Package | Description |\n|---------|-------------|\n| `packages/layout` | Reusable page layout components for consistent UI structure |\n| `packages/cli` | Command-line interface for workflow management and integration |\n| `packages/ai-workspace-common` | Shared UI components for canvas, nodes, and integrations |\n| `packages/web-core` | Core web application components |\n| `packages/stores` | State management using Zustand |\n| `apps/api` | Backend REST API service |\n\n资料来源：[packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n\n## Core Features\n\n### Visual Workflow Canvas\n\nThe workspace provides a drag-and-drop canvas interface for building workflows. Users can:\n\n- Add and configure various node types including code artifacts\n- Connect nodes to define workflow dependencies\n- Preview artifacts and outputs directly within the canvas\n- Share workflow configurations\n\n```mermaid\ngraph TD\n A[User Canvas] --> B[Canvas Nodes]\n A --> C[Resource Import]\n A --> D[Integration Docs]\n B --> E[Code Artifact]\n B --> F[Skill Execution]\n E --> G[Renderer]\n F --> H[Action Steps]\n G --> I[Preview Output]\n```\n\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\n### Layout System\n\nThe application provides two primary layout components:\n\n**PrimaryPageLayout**: Used for main application pages\n- Configuration options include title, actions, extra content\n- Supports `fixHeight`, `noPaddingY`, `noPaddingX` options\n\n**SecondaryPageLayout**: Designed for detail pages and sub-functional pages\n- Includes title, description, and back button support\n- Ideal for nested views and detail information\n\n```tsx\n\n {({ context, onContextChange }) => (\n <>\n Action Button}\n deps={[]}\n />\n
Page Content
\n \n )}\n\n```\n\n资料来源：[packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n\n### Scheduled Workflows\n\nThe platform supports scheduled workflow execution with configurable limits based on user subscription plans.\n\n| Feature | Description |\n|---------|-------------|\n| Schedule Creation | Create time-based automated workflows |\n| Limit Management | Enforced limits per subscription tier |\n| Schedule Management | View, edit, and disable existing schedules |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n### Template Marketplace\n\nRefly.ai includes a template marketplace where users can publish and discover workflow templates. The platform rewards creators with discount vouchers for publishing templates.\n\n**Email Notification Flow**:\n\n```mermaid\ngraph LR\n A[User Publishes Template] --> B[Generate Voucher]\n B --> C{Locale Detection}\n C -->|zh| D[Chinese Email Template]\n C -->|en| E[English Email Template]\n D --> F[Send Email]\n E --> F\n F --> G[Creator Receives Discount]\n```\n\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## Integrations\n\n### Claude Code Integration\n\nAfter running `refly init`, skill files are installed to Claude Code's directory structure:\n\n| IDE | Path |\n|-----|------|\n| Claude Code | `~/.claude/skills/refly/` |\n| Antigravity | `~/.antigravity/skills/` |\n| OpenCode | `~/.opencode/skills/` |\n| Cursor | `~/.cursor/skills/` |\n| VS Code | `~/.vscode/skills/` |\n| Trae | `~/.trae/skills/` |\n\nThis enables AI assistants to:\n- Understand Refly workflow concepts\n- Use builder mode correctly\n- Handle state transitions\n- Output deterministic results\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n### Webhook Support\n\nThe platform provides webhook integration capabilities with comprehensive error handling:\n\n| Error Code | HTTP Status | Description |\n|------------|-------------|-------------|\n| AUTH_REQUIRED | 401 | Not authenticated |\n| BUILDER_NOT_STARTED | 400 | No active builder session |\n| VALIDATION_REQUIRED | 400 | Must validate before commit |\n| VALIDATION_ERROR | 422 | DAG validation failed |\n| DUPLICATE_NODE_ID | 409 | Node ID already exists |\n| CYCLE_DETECTED | 422 | Circular dependency detected |\n| WORKFLOW_NOT_FOUND | 404 | Workflow does not exist |\n\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\n## CLI Tool\n\nThe Refly CLI provides command-line access to workflow management:\n\n### Installation\n\n```bash\nnpm install -g @refly/cli\n```\n\n### Configuration\n\nConfiguration is stored in `~/.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### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `REFLY_API_KEY` | API key for authentication |\n| `REFLY_API_ENDPOINT` | Override API endpoint |\n\n### Key Commands\n\n| Command | Description |\n|---------|-------------|\n| `refly login` | Authenticate with the platform |\n| `refly builder start` | Start a new builder session |\n| `refly builder validate` | Validate workflow DAG |\n| `refly init` | Initialize Claude Code integration |\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n## State Management\n\nThe application uses Zustand for state management across the workspace:\n\n**Import Resource Store**: Manages modal visibility, file lists, image lists, and waiting list items.\n\n```typescript\ninterface ImportResourceState {\n importResourceModalVisible: boolean;\n extensionModalVisible: boolean;\n fileList: FileItem[];\n imageList: ImageItem[];\n selectedMenuItem: ImportResourceMenuItem;\n waitingList: WaitingListItem[];\n scrapeLinks: LinkMeta[];\n}\n```\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## API Endpoint\n\nThe platform exposes a REST API at:\n\n```\nhttps://api.refly.ai\n```\n\nPublic file access:\n```\nhttps://api.refly.ai/v1/drive/file/public/{fileId}\n```\n\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## Internationalization\n\nThe platform supports multiple locales including:\n- English (en)\n- Chinese Simplified (zh-CN)\n- Chinese Traditional (zh-TW, zh-HK)\n- And other locales detected via browser settings\n\nLanguage detection is used for:\n- Email template selection\n- UI text rendering\n- User-facing notifications\n\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\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Project Introduction](#project-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n- [scripts/cli-deploy/README.md](https://github.com/refly-ai/refly/blob/main/scripts/cli-deploy/README.md)\n- [packages/cli/src/commands/workflow/index.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/commands/workflow/index.ts)\n- [packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\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
\n\n# Quick Start Guide\n\n## Overview\n\nThe Quick Start Guide provides developers and users with the essential steps to begin using Refly, an AI-powered workflow automation platform. This guide covers CLI installation, authentication, workflow creation using Builder mode, workflow execution, and core concepts necessary to start building automated workflows.\n\nRefly's architecture consists of three primary layers: a Command Line Interface (CLI) for local development, a web-based workspace for visual workflow design, and a cloud API for execution and scheduling. The CLI enables developers to build workflows incrementally with local state management, while the web interface provides a graphical canvas for complex workflow design.\n\n资料来源：[packages/cli/README.md:1-20]()\n\n## Prerequisites\n\nBefore starting with Refly, ensure the following requirements are met:\n\n| Requirement | Description |\n|-------------|-------------|\n| Node.js | Version 18 or higher |\n| Package Manager | pnpm (recommended) or npm |\n| Docker | Required for local development services |\n| API Key | Generated from the Refly dashboard |\n\n资料来源：[scripts/cli-deploy/README.md:1-30]()\n\n## Installation\n\n### Installing the CLI\n\nThe Refly CLI can be installed via npm or pnpm. After installation, initialize the CLI to set up configuration files and install skill files for Claude Code integration.\n\n```bash\nnpm install -g @refly/cli\n# or\npnpm add -g @refly/cli\n```\n\n### Initializing the CLI\n\nRun the initialization command to set up the CLI and install skill files:\n\n```bash\nrefly init\n```\n\nThis command performs the following actions:\n\n1. Creates the configuration directory at `~/.refly/`\n2. Generates the initial `config.json` file\n3. Installs skill files to `~/.claude/skills/refly/`\n4. Sets up command shortcuts if the commands directory exists\n\n资料来源：[packages/cli/README.md:1-15]()\n\n## Authentication\n\n### Logging In\n\nAuthenticate with the Refly API using your API key:\n\n```bash\nrefly login\n```\n\nThis command stores your credentials in `~/.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### Checking Authentication Status\n\nVerify your authentication status and view current user information:\n\n```bash\nrefly status\nrefly whoami\n```\n\n### Environment Variables\n\nOverride default configuration using environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `REFLY_API_KEY` | API key for authentication | - |\n| `REFLY_API_ENDPOINT` | Override API endpoint | `https://api.refly.ai` |\n\n资料来源：[packages/cli/README.md:25-45]()\n\n## Core Concepts\n\n### Builder Mode\n\nBuilder mode enables incremental workflow construction with local state management. It uses a deterministic state machine to track workflow progress through defined stages.\n\n```mermaid\ngraph TD\n IDLE[\"IDLE\"] --> DRAFT[\"DRAFT\"]\n DRAFT --> VALIDATED[\"VALIDATED\"]\n VALIDATED --> COMMITTED[\"COMMITTED\"]\n COMMITTED --> IDLE\n DRAFT --> IDLE\n \n style IDLE fill:#e1f5fe\n style DRAFT fill:#fff3e0\n style VALIDATED fill:#e8f5e9\n style COMMITTED fill:#c8e6c9\n```\n\n### Workflow States\n\n| State | Description | Can Transition To |\n|-------|-------------|-------------------|\n| IDLE | No active builder session | DRAFT |\n| DRAFT | Workflow being constructed | IDLE, VALIDATED |\n| VALIDATED | DAG validation passed | IDLE, COMMITTED |\n| COMMITTED | Workflow saved to server | IDLE |\n\n资料来源：[packages/cli/README.md:48-65]()\n\n### Workflow Components\n\nRefly workflows consist of nodes and connections:\n\n| Component | Description |\n|-----------|-------------|\n| Nodes | Individual units of work (agents, tools, data transformations) |\n| Edges | Connections defining data flow between nodes |\n| Variables | Input/output parameters for workflow execution |\n| Schedules | Cron-based triggers for automated execution |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:1-30]()\n\n## Building a Workflow\n\n### Starting a Builder Session\n\nBegin a new workflow or edit an existing one:\n\n```bash\nrefly builder start --name \"my-workflow\"\n```\n\n### Adding Nodes\n\nAdd nodes to define workflow steps:\n\n```bash\nrefly builder add-node --node ''\n```\n\nNode JSON structure:\n\n```json\n{\n \"id\": \"node-001\",\n \"type\": \"agent\",\n \"config\": {\n \"model\": \"gpt-4\",\n \"prompt\": \"Analyze the input document\"\n }\n}\n```\n\n### Connecting Nodes\n\nEstablish data flow between nodes:\n\n```bash\nrefly builder connect --from \"node-001\" --to \"node-002\"\n```\n\n### Viewing the Graph\n\nVisualize the current workflow structure:\n\n```bash\nrefly builder graph\nrefly builder graph --ascii\n```\n\n### Validating the Workflow\n\nBefore committing, validate the workflow's DAG structure:\n\n```bash\nrefly builder validate\n```\n\nThis checks for:\n- Circular dependencies\n- Missing required inputs\n- Invalid node configurations\n- Orphan nodes without connections\n\n### Committing the Workflow\n\nSave the validated workflow to the server:\n\n```bash\nrefly builder commit\n```\n\n### Aborting Changes\n\nDiscard all changes and return to IDLE state:\n\n```bash\nrefly builder abort\n```\n\n资料来源：[packages/cli/README.md:47-80]()\n\n## Workflow Management\n\n### Creating Workflows\n\nCreate a workflow using the CLI:\n\n```bash\nrefly workflow create --name \"\" --spec ''\n```\n\n### Listing Workflows\n\nView all available workflows:\n\n```bash\nrefly workflow list [--limit N]\n```\n\n### Retrieving Workflow Details\n\nGet detailed information about a specific workflow:\n\n```bash\nrefly workflow get \n```\n\n### Editing Workflows\n\nModify an existing workflow:\n\n```bash\nrefly workflow edit --ops ''\n```\n\n### Deleting Workflows\n\nRemove a workflow from the system:\n\n```bash\nrefly workflow delete \n```\n\n资料来源：[packages/cli/src/commands/workflow/index.ts:1-50]()\n\n## Workflow Execution\n\n### Running a Workflow\n\nExecute a workflow with optional input data:\n\n```bash\nrefly workflow run [--input '']\n```\n\nExample with input:\n\n```bash\nrefly workflow run wf-abc123 --input '{\"documentUrl\": \"https://example.com/doc.pdf\"}'\n```\n\n### Monitoring Execution Status\n\nTrack the progress of a running workflow:\n\n```bash\nrefly workflow run-status \n```\n\n### Aborting Execution\n\nStop a running workflow:\n\n```bash\nrefly workflow abort \n```\n\n### Node Debugging\n\nTest individual node types independently:\n\n```bash\nrefly node types [--category ]\nrefly node run --type \"\" --input ''\n```\n\n资料来源：[packages/cli/README.md:82-100]()\n\n## Scheduling Workflows\n\nWorkflows can be scheduled for automated execution using cron-based triggers.\n\n### Schedule Limits\n\nDifferent plans have varying limits on scheduled workflows:\n\n| Plan | Maximum Schedules |\n|------|-------------------|\n| Free | 5 |\n| Pro | 25 |\n| Enterprise | Unlimited |\n\n### Managing Schedules\n\nWhen scheduling limits are reached, users can:\n\n1. View existing schedules\n2. Disable unused schedules\n3. Upgrade to a higher plan\n\nThe schedule management interface provides modals for viewing and deactivating schedules.\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx:1-60]()\n\n## Local Development Setup\n\n### Quick Start Deployment\n\nFor developers with an existing repository clone:\n\n```bash\n./scripts/cli-deploy/quick-start.sh\n```\n\nThis script performs:\n\n1. Building the CLI package\n2. Starting Docker services (PostgreSQL, Redis)\n3. Running database migrations\n4. Seeding global tools data\n5. Starting the API server\n6. Guiding through OAuth login\n7. Generating an API key\n\n### Full Deployment\n\nFor a complete fresh deployment:\n\n```bash\n./scripts/cli-deploy/deploy-cli.sh\n```\n\n### Deployment Options\n\n| Option | Description |\n|--------|-------------|\n| `--skip-build` | Skip building CLI |\n| `--skip-services` | Skip Docker services |\n| `--skip-seed` | Skip seeding data |\n| `--skip-api` | Skip starting API |\n| `--skip-auth` | Skip authentication |\n| `--refly-dir` | Custom installation directory |\n| `--branch` | Use specific Git branch |\n\n资料来源：[scripts/cli-deploy/README.md:10-50]()\n\n## Error Handling\n\n### Common Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| AUTH_REQUIRED | Not authenticated | Run `refly login` |\n| BUILDER_NOT_STARTED | No active builder session | Run `refly builder start` |\n| VALIDATION_REQUIRED | Must validate before commit | Run `refly builder validate` |\n| VALIDATION_ERROR | DAG validation failed | Check error details |\n| DUPLICATE_NODE_ID | Node ID already exists | Use unique ID |\n| CYCLE_DETECTED | Circular dependency | Remove cycle |\n| WORKFLOW_NOT_FOUND | Workflow does not exist | Check workflow ID |\n\n### Builder State Transitions\n\nThe builder enforces strict state transitions:\n\n```mermaid\ngraph LR\n A[IDLE] -->|start| B[DRAFT]\n B -->|validate| C[VALIDATED]\n C -->|commit| D[COMMITTED]\n B -->|abort| A\n C -->|abort| A\n D -->|start| B\n```\n\n资料来源：[packages/cli/README.md:100-120]()\n\n## Next Steps\n\nAfter completing this quick start guide, explore the following topics:\n\n1. **Advanced Workflows** - Implement conditional logic, loops, and parallel execution\n2. **Custom Nodes** - Create reusable node types for specialized tasks\n3. **Integration APIs** - Connect external services and APIs\n4. **Team Collaboration** - Share workflows and manage permissions\n5. **Monitoring & Analytics** - Track workflow performance and costs\n\n### Additional Resources\n\n| Resource | Link |\n|----------|------|\n| Documentation | https://docs.refly.ai |\n| GitHub Discussions | https://github.com/refly-ai/refly-skills/discussions |\n| Issue Tracker | https://github.com/refly-ai/refly-skills/issues |\n| Discord Community | https://discord.gg/refly |\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Project Structure](#project-structure), [API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\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- [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/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.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/pure-copilot/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/pure-copilot/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- [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/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/web-core/src/pages/page-share/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/index.tsx)\n- [packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n
\n\n# System Architecture\n\n## Overview\n\nRefly is a modular AI workspace platform built with a distributed architecture that separates concerns across multiple packages. The system comprises a monorepo structure using pnpm workspaces, organized into application layers (API, web-core) and shared package libraries (canvas-common, stores, skill-template, ai-workspace-common, layout).\n\nThe architecture follows a modular design pattern where each package encapsulates specific functionality, enabling loose coupling between components while maintaining type-safe inter-package communication.\n\n## Package Architecture\n\nThe repository is organized into the following main packages:\n\n| Package | Purpose | Key Dependencies |\n|---------|---------|------------------|\n| `apps/api` | Backend API server | NestJS framework |\n| `apps/web-core` | Frontend application | React 18, TypeScript |\n| `packages/canvas-common` | Shared canvas types and utilities | - |\n| `packages/stores` | Global state management (Zustand) | React |\n| `packages/skill-template` | Skill execution templates | - |\n| `packages/ai-workspace-common` | Reusable UI components | Ant Design, Tailwind CSS |\n| `packages/layout` | Page layout components | React |\n\n资料来源：[packages/stores/src/stores/import-resource.ts:1-50](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts)\n\n## State Management Architecture\n\n### Global Store Structure\n\nThe application uses Zustand for centralized state management through the `packages/stores` package. The store is organized into functional slices with clear action boundaries.\n\n```mermaid\ngraph TD\n A[Root Store] --> B[Import Resource Store]\n A --> C[Canvas Store]\n A --> D[User Store]\n A --> E[UI Store]\n \n B --> B1[importResourceModalVisible]\n B --> B2[extensionModalVisible]\n B --> B3[scrapeLinks]\n B --> B4[waitingList]\n B --> B5[fileList / imageList]\n \n C --> C1[selectedMenuItem]\n C --> C2[insertNodePosition]\n```\n\n### Store Actions Pattern\n\nState updates follow a consistent pattern using Zustand's `set` function with immutable state updates:\n\n```typescript\nsetFileList: (fileList: FileItem[]) => set((state) => ({ ...state, fileList })),\nsetImageList: (imageList: ImageItem[]) => set((state) => ({ ...state, imageList })),\nsetSelectedMenuItem: (menuItem: ImportResourceMenuItem) =>\n set((state) => ({ ...state, selectedMenuItem: menuItem })),\nsetInsertNodePosition: (position: XYPosition) =>\n set((state) => ({ ...state, insertNodePosition: position })),\n```\n\n资料来源：[packages/stores/src/stores/import-resource.ts:1-30](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts)\n\n### Waiting List Management\n\nThe store implements a waiting list feature for handling pending operations:\n\n```typescript\naddToWaitingList: (item: WaitingListItem) =>\n set((state) => ({ ...state, waitingList: [...state.waitingList, item] })),\nremoveFromWaitingList: (id: string) =>\n set((state) => ({\n ...state,\n waitingList: state.waitingList.filter((item) => item.id !== id),\n })),\nupdateWaitingListItem: (id: string, updates: Partial) =>\n set((state) => ({\n ...state,\n waitingList: state.waitingList.map((item) =>\n item.id === id ? { ...item, ...updates } : item\n ),\n })),\n```\n\n资料来源：[packages/stores/src/stores/import-resource.ts:30-45](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts)\n\n## Canvas System Architecture\n\n### Canvas Overview\n\nThe canvas is the central workspace component where users build workflows by connecting nodes. It supports multiple node types including skills, webhooks, documents, and integrations.\n\n### Node Types\n\n| Node Type | Description | Source Component |\n|-----------|-------------|------------------|\n| Skill Node | Executes AI-powered skills | `action-step.tsx` |\n| Webhook Node | HTTP callback endpoints | `webhook-config-tab.tsx` |\n| Document Node | Rich content rendering | `ArtifactRenderer.tsx` |\n| Integration Node | External service connections | `integration-docs-modal.tsx` |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:1-60](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx)\n\n### Artifact Rendering System\n\nThe `ArtifactRenderer` component handles rendering different content types within the canvas:\n\n```typescript\nconst ArtifactRenderer = memo(\n ({ node, type, content, title, language, status }) => {\n // Renders based on rendererType: 'document' or other\n // Supports purePreview mode for clean rendering\n // Implements custom width/height scaling\n },\n (prevProps, nextProps) => {\n // Custom comparison for memo optimization\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 );\n }\n);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:1-120](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx)\n\n### Action Step Execution Flow\n\nSkills execute through a structured action step system:\n\n```mermaid\ngraph TD\n A[Skill Node] --> B[ActionStep Component]\n B --> C{Status Check}\n C -->|executing| D[Show Progress Logs]\n C -->|waiting| E[Show Pending Indicator]\n C -->|finish| F[Show Results]\n C -->|failed| G[Show Error Logs]\n \n D --> H[ReasoningContent]\n E --> H\n F --> I[Collapsed View]\n G --> J[Error Details]\n```\n\nThe component manages status transitions automatically:\n\n```typescript\nuseEffect(() => {\n if (['executing', 'waiting'].includes(status)) {\n setCollapsed(false);\n } else {\n setCollapsed(true);\n }\n}, [status]);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:50-80](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx)\n\n## Integration System Architecture\n\n### Integration Docs Modal\n\nThe integration system provides a unified interface for configuring external services:\n\n```typescript\ncase 'webhook':\n return (\n \n );\ncase 'api':\n return ;\ncase 'skill':\n return ;\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx:1-80](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx)\n\n### Webhook Documentation Tab\n\nThe webhook documentation provides usage instructions and error handling guidance:\n\n```typescript\n
\n {t('webhook.instructions')}\n
    \n
  • {t('webhook.instruction1')}
    • \n
  • {t('webhook.instruction2')}
    • \n
  • {t('webhook.instruction3')}
    • \n
\n
\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx:1-30](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx)\n\n### Webhook Error Codes\n\n| Error Code | HTTP Status | Description |\n|------------|-------------|-------------|\n| AUTH_REQUIRED | 401 | Not authenticated |\n| VALIDATION_ERROR | 400 | DAG validation failed |\n| DUPLICATE_NODE_ID | 409 | Node ID already exists |\n| CYCLE_DETECTED | 400 | Circular dependency |\n| WORKFLOW_NOT_FOUND | 404 | Workflow does not exist |\n\n## Skill Template System\n\n### Context Management\n\nThe skill template system uses a context-based architecture for passing data between skill execution steps:\n\n```typescript\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\nexport interface ContextFileMeta {\n // Metadata-only version (without content)\n name: string;\n fileId: string;\n type: string;\n summary: string;\n variableId?: string;\n variableName?: string;\n}\n```\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts:1-50](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts)\n\n### Tool Use Pattern\n\nSkills use a standardized tool calling format:\n\n```typescript\n// Matches markdown code block format\nconst TOOL_USE_BLOCK_REGEX = /\\n*```tool_use(?:_result)?[^\\n]*\\n[\\s\\S]*?```\\n*/g;\n\n// Matches standalone XML tags\nconst TOOL_USE_TAG_REGEX = //g;\n```\n\n### Agent Result Structure\n\n```typescript\nexport interface AgentResult {\n resultId: string;\n title: string;\n content: string;\n outputFiles: ContextFileMeta[];\n}\n\nexport interface ToolCallMeta {\n callId: string; // For retrieval via read_tool_result\n toolName: string; // Tool that was called\n}\n```\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts:40-80](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts)\n\n## Copilot Integration\n\n### Pure Copilot Component\n\nThe copilot provides an AI-powered interface for interacting with the workspace:\n\n```typescript\nconst PureCopilot = ({\n source,\n canvasId,\n onQueryChange,\n}: {\n source: 'frontPage' | 'onboarding';\n canvasId?: string;\n onQueryChange?: (query: string) => void;\n}) => {\n // Supports drag-and-drop file handling\n // Integrates with ChatInput component\n // Manages file uploads and context items\n};\n```\n\n资料来源：[packages/ai-workspace-common/src/components/pure-copilot/index.tsx:1-50](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/pure-copilot/index.tsx)\n\n### Drag and Drop Support\n\n```typescript\n\n```\n\nThe copilot glow effect varies based on source location:\n\n```typescript\nsource === 'frontPage'\n ? cn('border-refly-primary-default my-2')\n : 'border-transparent pure-copilot-glow-effect'\n```\n\n## Modal Architecture\n\n### Modal Container Pattern\n\nThe application uses a centralized modal container with lazy loading:\n\n```typescript\n\n import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({\n default: m.ImportResourceModal,\n }))\n }\n/>\n```\n\n资料来源：[packages/web-core/src/components/layout/ModalContainer.tsx:1-80](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/components/layout/ModalContainer.tsx)\n\n### Modal Types\n\n| Modal | Purpose | Source |\n|-------|---------|--------|\n| ImportResourceModal | Import external resources | `import-resource.ts` |\n| CanvasRenameModal | Rename canvas | `canvas-rename.tsx` |\n| CanvasDeleteModal | Delete canvas | `canvas-delete.tsx` |\n| DuplicateCanvasModal | Duplicate canvas | `duplicate-canvas-modal.tsx` |\n| ClaimedVoucherPopup | Show claimed voucher | `voucher` |\n| EarnedVoucherPopup | Show earned voucher | `voucher` |\n\n## Schedule System\n\n### Schedule Button Component\n\nThe schedule system manages automated workflow execution:\n\n```typescript\n\n \n\n\n{t('common.cancel')},\n ,\n ]}\n>\n {/* Limit reached message */}\n\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx:1-60](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n### Schedule Modal Features\n\n| Feature | Description |\n|---------|-------------|\n| Schedule Limit Modal | Shown when user exceeds plan limits |\n| Deactivate Confirmation | Confirm before disabling schedules |\n| View Schedules | Navigate to schedule management |\n\n## Page Layout System\n\n### Layout Components\n\nThe layout system provides consistent page structures:\n\n```typescript\n// PrimaryPageLayout - Main application pages\n\n {({ context, onContextChange }) => (\n <>\n Action}\n />\n
Content
\n \n )}\n\n\n// SecondaryPageLayout - Detail/sub-pages\n\n {({ context, onContextChange }) => (\n <>\n history.back()}\n />\n
Content
\n \n )}\n\n```\n\n### Layout Configuration Options\n\n| Option | Description |\n|--------|-------------|\n| `title` | Page title |\n| `desc` | Page description |\n| `actions` | Action button area |\n| `extra` | Extra content area |\n| `fixHeight` | Fix content height |\n| `noPaddingX` | Remove horizontal padding |\n| `noPaddingY` | Remove vertical padding |\n\n## Wide Mode Feature\n\nThe page share feature includes a wide mode for expanded content viewing:\n\n```typescript\n{wideMode.isActive && (\n \n
\n {wideMode.nodeId && nodes.find((n) => n.nodeId === wideMode.nodeId)}\n
\n \n)}\n```\n\n资料来源：[packages/web-core/src/pages/page-share/index.tsx:1-80](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/index.tsx)\n\n## Component Rendering Optimization\n\n### Memo Strategy\n\nComponents use React's `memo` with custom comparison functions to optimize re-renders:\n\n```typescript\nexport const ArtifactRenderer = memo(\n Component,\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\n资料来源：[packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:100-120](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx)\n\n## API Error Handling\n\n### Error Response Structure\n\nThe API returns structured error responses:\n\n```typescript\n{\n code: string; // Error code (e.g., \"AUTH_REQUIRED\")\n httpStatus: number; // HTTP status code\n message: string; // Error message\n description: string // Detailed description\n}\n```\n\n### Common Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| AUTH_REQUIRED | Authentication missing | Run `refly login` |\n| BUILDER_NOT_STARTED | No builder session | Run `refly builder start` |\n| VALIDATION_REQUIRED | Validation pending | Run `refly builder validate` |\n| VALIDATION_ERROR | DAG validation failed | Check node connections |\n| DUPLICATE_NODE_ID | ID collision | Use unique identifiers |\n| CYCLE_DETECTED | Circular dependency | Remove cycles from graph |\n\n## Conclusion\n\nThe Refly system architecture demonstrates a well-structured monorepo design with clear separation of concerns across multiple packages. The architecture supports:\n\n- **Scalable State Management**: Centralized Zustand stores with typed actions\n- **Modular UI Components**: Reusable components in ai-workspace-common\n- **Flexible Integration System**: Extensible webhook and API integrations\n- **Optimized Rendering**: Strategic use of React.memo for performance\n- **Type-Safe Communication**: Consistent TypeScript interfaces across packages\n\n---\n\n\n\n## Project Structure\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [pnpm-workspace.yaml](https://github.com/refly-ai/refly/blob/main/pnpm-workspace.yaml)\n- [turbo.json](https://github.com/refly-ai/refly/blob/main/turbo.json)\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/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.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- [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- [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/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/web-core/src/pages/page-share/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/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/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- [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/integration-docs/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.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/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/markdown/plugins/link/render.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx)\n
\n\n# Project Structure\n\n## Overview\n\nRefly is a modern monorepo built with pnpm workspaces and Turborepo for optimized build performance. The repository follows a structured approach to organize code across multiple packages and applications, enabling shared dependencies and consistent development practices across the entire codebase.\n\nThe project architecture separates concerns into discrete packages under the `packages/` directory and applications under the `apps/` directory, with each package serving a specific domain of functionality.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Apps Layer\"\n API[apps/api
Backend API Service]\n WEB[apps/web-core
Web Application]\n end\n\n subgraph \"Packages Layer\"\n STORES[packages/stores
Zustand State Management]\n LAYOUT[packages/layout
Layout Components]\n WORKSPACE[packages/ai-workspace-common
Workspace Components]\n CLI[packages/cli
Command Line Interface]\n end\n\n API --> STORES\n WEB --> STORES\n WEB --> LAYOUT\n WEB --> WORKSPACE\n CLI --> API\n```\n\n## Directory Structure\n\n```\nrefly/\n├── apps/\n│ ├── api/ # Backend API application\n│ │ └── src/\n│ │ └── modules/ # API modules (voucher, workflows, etc.)\n│ └── web/ # Web application entry\n├── packages/\n│ ├── stores/ # State management with Zustand\n│ ├── ai-workspace-common/ # Shared AI workspace components\n│ ├── layout/ # Page layout components\n│ ├── web-core/ # Core web components\n│ └── cli/ # CLI tool\n├── pnpm-workspace.yaml # pnpm workspace configuration\n└── turbo.json # Turborepo configuration\n```\n\n## Applications\n\n### apps/api\n\nThe backend API service built with Node.js. The API module structure follows a modular pattern:\n\n```\napps/api/src/modules/\n├── voucher/ # Voucher/coupon management\n│ └── voucher-email-templates.ts\n└── ... (additional modules)\n```\n\n**Key Characteristics:**\n- Handles business logic and data persistence\n- Provides REST API endpoints for the frontend\n- Contains email template logic for notifications\n- Manages voucher rewards and creator incentives\n\n资料来源：[apps/api/src/modules](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules)\n\n### apps/web-core\n\nThe main web application entry point, responsible for rendering the user interface and handling client-side routing.\n\n## Packages\n\n### packages/stores\n\nState management layer using Zustand. Provides centralized state stores for various application features.\n\n**Primary Store Files:**\n\n| Store File | Purpose |\n|------------|---------|\n| `import-resource.ts` | Manages import resource modal visibility and file lists |\n| `waiting-list.ts` | Handles waiting list state and operations |\n| `scraper-links.ts` | Manages scraped link metadata |\n\n**Key Store Patterns:**\n\n```typescript\n// Store action pattern\nsetImportResourceModalVisible: (visible: boolean) =>\n set((state) => ({ ...state, importResourceModalVisible: visible })),\n\n// Waiting list operations\naddToWaitingList: (item: WaitingListItem) =>\n set((state) => ({ ...state, waitingList: [...state.waitingList, item] })),\n\nremoveFromWaitingList: (id: string) =>\n set((state) => ({\n ...state,\n waitingList: state.waitingList.filter((item) => item.id !== id),\n })),\n```\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### packages/ai-workspace-common\n\nThe core component library for the AI workspace functionality. This package contains the majority of UI components and business logic for the application.\n\n#### Component Organization\n\n```\npackages/ai-workspace-common/src/components/\n├── canvas/ # Canvas-based workflow components\n│ ├── nodes/ # Custom node types\n│ ├── top-toolbar/ # Toolbar components\n│ ├── node-preview/ # Node preview panels\n│ ├── integration-docs/ # Integration documentation\n│ ├── webhook/ # Webhook configuration\n│ └── launchpad/ # Launchpad interface\n├── resource-view/ # Resource display components\n├── pure-copilot/ # Copilot chat interface\n├── slideshow/ # Presentation/slideshow components\n└── markdown/ # Markdown rendering plugins\n```\n\n#### Canvas Components\n\nThe canvas system is a node-based workflow editor:\n\n| Component | Purpose |\n|-----------|---------|\n| `CodeArtifactNode` | Renders code artifacts within canvas nodes |\n| `ArtifactRenderer` | Renders various artifact types (documents, code) |\n| `RichChatInput` | Multi-feature chat input with mentions and uploads |\n| `SkillResponse` | Displays skill execution logs and reasoning |\n| `ActionStep` | Renders individual action steps with status |\n\n**Canvas Node Rendering:**\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx\nexport const CodeArtifactNode = memo(\n ({ id, data, isPreview, selected, hideHandles, onNodeClick }: CodeArtifactNodeProps) => {\n const [isHovered, setIsHovered] = useState(false);\n const { edges } = useCanvasData();\n const { getNode } = useReactFlow();\n // ... node rendering logic\n },\n (prevProps, nextProps) =>\n prevProps.entityId === nextProps.entityId &&\n prevProps?.status === nextProps?.status &&\n prevProps.legacyData?.content === nextProps.legacyData?.content\n);\n```\n\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\n#### Skill Response & Action Steps\n\nThe skill response system displays AI agent execution logs:\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx\nconst ReasoningContent = memo(\n ({\n resultId,\n reasoningContent,\n sources,\n step,\n status,\n }: {\n resultId: string;\n reasoningContent: string;\n sources: Source[];\n step: ActionStep;\n status: ActionStatus;\n }) => {\n const [collapsed, setCollapsed] = useState(status !== 'executing');\n \n // Auto-collapse when step status changes from executing to finish\n useEffect(() => {\n if (['executing', 'waiting'].includes(status)) {\n setCollapsed(false);\n } else {\n setCollapsed(true);\n }\n }, [status]);\n // ...\n }\n);\n```\n\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#### Resource View System\n\nDisplays resource metadata and details:\n\n```typescript\n// packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx\n{resourceDetail?.data?.url && (\n \n {resourceDetail?.data?.url}\n \n)}\n{resourceDetail?.createdAt && (\n

\n {time(resourceDetail?.createdAt, language as LOCALE)\n .utc()\n .fromNow()}\n

\n)}\n```\n\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#### Integration Documentation\n\nWeb-based documentation and configuration interfaces:\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx\n\n {t('schedule.viewSchedules') || 'View Schedules'}\n\n\n setScheduleLimitModalVisible(false)}>\n {t('common.cancel') || 'Cancel'}\n ,\n // ...\n ]}\n>\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n#### Artifact Rendering\n\nSupports multiple artifact types with preview capabilities:\n\n```typescript\n// packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx\n
\n \n
\n```\n\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\n#### Markdown Link Rendering\n\nCustom markdown plugin for rendering links with preview functionality:\n\n```typescript\n// packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx\n\n```\n\n资料来源：[packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx)\n\n### packages/web-core\n\nCore web components including modal management and page layouts.\n\n#### Modal Container\n\nCentralized modal management system:\n\n```typescript\n// packages/web-core/src/components/layout/ModalContainer.tsx\n\n import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({\n default: m.ImportResourceModal,\n }))\n }\n/>\n\n\n import('@refly-packages/ai-workspace-common/components/canvas/modals/canvas-rename').then(\n (m) => ({ default: m.CanvasRenameModal }),\n )\n }\n/>\n```\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#### Page Share Module\n\nHandles public page sharing functionality:\n\n```typescript\n// packages/web-core/src/pages/page-share/index.tsx\n{wideMode.isActive && (\n \n
\n {/* Wide mode content */}\n
\n \n)}\n```\n\n资料来源：[packages/web-core/src/pages/page-share/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/index.tsx)\n\n### packages/layout\n\nPage layout component library providing consistent layout patterns.\n\n#### Layout Components\n\n| Component | Description |\n|-----------|-------------|\n| `PrimaryPageLayout` | Main application pages with title, actions, and extra content areas |\n| `SecondaryPageLayout` | Detail pages with back navigation |\n| `Header` | Reusable header with left/right action areas |\n\n**Primary Layout Usage:**\n\n```tsx\nimport { PrimaryPageLayout, PrimaryPageLayoutContextUpdater } from '@refly/layout';\n\nfunction MainPage() {\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**Configuration Options:**\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `title` | string | Page title displayed in header |\n| `actions` | ReactNode | Action button area |\n| `extra` | ReactNode | Extra content area |\n| `fixHeight` | boolean | Whether to fix height |\n| `noPaddingY` | boolean | Remove vertical padding |\n| `noPaddingX` | boolean | Remove horizontal padding |\n\n资料来源：[packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n\n### packages/cli\n\nCommand-line interface for Refly operations.\n\n#### CLI Features\n\n| Feature | Description |\n|---------|-------------|\n| `refly login` | Authenticate with API key |\n| `refly builder` | Workflow builder commands |\n| `refly workflow` | Workflow execution and management |\n| `refly init` | Initialize Claude Code integration |\n\n**Configuration Storage:**\n\nConfiguration is stored in `~/.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**Environment Variables:**\n\n| Variable | Description |\n|----------|-------------|\n| `REFLY_API_KEY` | API key for authentication |\n| `REFLY_API_ENDPOINT` | Override API endpoint |\n\n#### Claude Code Integration\n\nAfter `refly init`, skill files are installed to:\n- `~/.claude/skills/refly/SKILL.md`\n- `~/.claude/skills/refly/references/`\n- `~/.claude/commands/refly-*.md`\n\n#### Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| AUTH_REQUIRED | Not authenticated | Run `refly login` |\n| BUILDER_NOT_STARTED | No active builder session | Run `refly builder start` |\n| VALIDATION_REQUIRED | Must validate before commit | Run `refly builder validate` |\n| VALIDATION_ERROR | DAG validation failed | Check error details |\n| DUPLICATE_NODE_ID | Node ID already exists | Use unique ID |\n| CYCLE_DETECTED | Circular dependency | Remove cycle |\n| WORKFLOW_NOT_FOUND | Workflow does not exist | Check workflow ID |\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n## Build System\n\n### pnpm Workspaces\n\nThe project uses pnpm workspaces for monorepo management:\n\n```yaml\n# pnpm-workspace.yaml\npackages:\n - 'apps/*'\n - 'packages/*'\n```\n\n### Turborepo\n\nBuild orchestration with Turborepo:\n\n```json\n// turbo.json (inferred from usage)\n{\n \"pipeline\": {\n \"build\": {\n \"dependsOn\": [\"^build\"],\n \"outputs\": [\"dist/**\"]\n }\n }\n}\n```\n\n## Component Communication Flow\n\n```mermaid\ngraph LR\n subgraph \"State Layer\"\n STORES[packages/stores
Zustand Stores]\n end\n\n subgraph \"UI Layer\"\n WEB_CORE[packages/web-core
Modal Container]\n WORKSPACE[packages/ai-workspace-common
Components]\n end\n\n subgraph \"Layout Layer\"\n LAYOUT[packages/layout
Page Layouts]\n end\n\n STORES -->|State Updates| WEB_CORE\n STORES -->|State Updates| WORKSPACE\n WORKSPACE -->|Lazy Loaded| WEB_CORE\n LAYOUT -->|Wraps| WEB_CORE\n```\n\n## Internationalization\n\nThe project uses i18n for translations with namespace support:\n\n```typescript\nconst { t } = useTranslation();\n\n{t('schedule.title') || 'Schedule'}\n{t('schedule.limitReached.title', { ns: 'schedule' })}\n```\n\nTranslation namespaces include:\n- `common` - Common UI strings\n- `schedule` - Schedule-related strings\n- `skillLog` - Skill execution logs\n- `webhook` - Webhook configuration\n- `integration` - Integration documentation\n\n## Key Development Patterns\n\n### Lazy Loading\n\nComponents are lazy-loaded for performance:\n\n```typescript\n\n import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({\n default: m.ImportResourceModal,\n }))\n }\n/>\n```\n\n### Memoization\n\nHeavy components use React.memo for optimization:\n\n```typescript\nexport const CodeArtifactNode = memo(\n ({ id, data, isPreview, selected }: CodeArtifactNodeProps) => {\n // component logic\n },\n (prevProps, nextProps) =>\n prevProps.entityId === nextProps.entityId &&\n prevProps?.status === nextProps?.status\n);\n```\n\n### Custom Hooks\n\nDomain-specific hooks encapsulate business logic:\n\n- `useCanvasData()` - Canvas state access\n- `useAgentNodeManagement()` - Agent node operations\n- `useVariablesManagement()` - Workflow variables\n- `useFetchDriveFiles()` - File fetching\n\n## Development Commands\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Watch mode for development\npnpm dev\n\n# Run API locally\nnode dist/bin/refly.js\n\n---\n\n\n\n## Workflow Engine\n\n### 相关页面\n\n相关主题：[Skill Management](#skill-management), [API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/api/src/modules/workflow/workflow.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow/workflow.service.ts)\n- [apps/api/src/modules/workflow/workflow.processor.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow/workflow.processor.ts)\n- [apps/api/src/modules/schedule/schedule.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow/schedule.service.ts)\n- [packages/canvas-common/src/workflow.ts](https://github.com/refly-ai/refly/blob/main/packages/canvas-common/src/workflow.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- [apps/api/src/modules/skill/skill-invoker.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/skill/skill-invoker.service.ts)\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/pages/workflow-app/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/workflow-app/index.tsx)\n
\n\n# Workflow Engine\n\n## Overview\n\nThe Workflow Engine is the core execution runtime of the refly platform. It orchestrates the execution of workflow graphs composed of interconnected nodes, where each node represents a discrete unit of work executed by specialized agents. The engine handles workflow lifecycle management, from creation through execution, monitoring, and completion.\n\nThe Workflow Engine serves as the backbone for:\n\n- **Workflow Graph Execution**: Parsing and executing directed acyclic graphs (DAGs) of workflow tasks\n- **Node Agent Orchestration**: Invoking skill agents for individual task execution\n- **Variable Management**: Managing workflow-level and node-level variables\n- **Execution State Tracking**: Tracking node status, handling retries, and managing abort signals\n- **Scheduled Execution**: Supporting time-based workflow triggers\n\n## Architecture\n\nThe Workflow Engine follows a layered architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"API Layer\"\n WS[Workflow Service]\n SS[Schedule Service]\n end\n \n subgraph \"Core Engine\"\n WP[Workflow Processor]\n SI[Skill Invoker]\n end\n \n subgraph \"Execution Layer\"\n NA[Node Agents]\n ST[Skill Templates]\n end\n \n subgraph \"State Management\"\n DB[(Database)]\n EV[Event Bus]\n end\n \n WS --> WP\n SS --> WP\n WP --> SI\n SI --> NA\n NA --> ST\n WP <--> DB\n WP <--> EV\n```\n\n### Key Components\n\n| Component | Package | Responsibility |\n|-----------|---------|----------------|\n| `WorkflowService` | apps/api | Workflow CRUD, execution triggering |\n| `WorkflowProcessor` | apps/api | Core DAG execution, state management |\n| `SkillInvokerService` | apps/api | Skill agent invocation, result handling |\n| `ScheduleService` | apps/api | Time-based workflow triggers |\n| `WorkflowRunForm` | ai-workspace-common | Variable input UI for workflow execution |\n\n## Data Models\n\n### Workflow Graph Structure\n\nThe workflow is defined as a graph with nodes and edges:\n\n```typescript\ninterface WorkflowSpec {\n nodes?: Array>;\n edges?: Array>;\n}\n```\n\n资料来源：[apps/api/src/modules/skill-package/skill-package.dto.ts:26]()\n\n### Node Types\n\nWorkflows support multiple node types:\n\n| Node Type | Description |\n|-----------|-------------|\n| `skillResponse` | Skill agent execution nodes |\n| `start` | Entry point node |\n| `end` | Termination node |\n\n资料来源：[packages/web-core/src/pages/workflow-app/index.tsx:142]()\n\n### Task Structure\n\nTasks represent individual units of work within a workflow:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Unique identifier (e.g., \"task-1\") |\n| `title` | string | Concise task name |\n| `prompt` | string | Detailed execution instructions with @ mentions |\n| `dependentTasks` | string[] | Task IDs that must complete first |\n| `toolsets` | string[] | Toolset IDs from Available Tools |\n\n资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:67]()\n\n### Context Files\n\nContext files provide input/output data flow between workflow nodes:\n\n```typescript\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资料来源：[packages/skill-template/src/scheduler/utils/context.ts:14]()\n\n### Agent Results\n\nAgent results encapsulate task execution outcomes:\n\n```typescript\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:27]()\n\n## Workflow Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: workflow.create\n Created --> Running: workflow.run\n Running --> Completed: all nodes finish\n Running --> Failed: unhandled error\n Running --> Aborted: user abort\n Failed --> Running: retry\n Aborted --> [*]\n Completed --> [*]\n```\n\n### Execution States\n\nEach node in a workflow can be in one of the following states:\n\n| Status | Description |\n|--------|-------------|\n| `waiting` | Node is waiting for dependencies to complete |\n| `executing` | Node is currently running |\n| `finish` | Node completed successfully |\n| `failed` | Node execution failed |\n\n资料来源：[packages/ai-workspace-common/src/components/workflow-app/run-logs.tsx:78]()\n\n## Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant API\n participant Processor\n participant Invoker\n participant Agent\n \n User->>API: workflow.run(workflowId, input)\n API->>Processor: processWorkflowExecution()\n Processor->>Processor: Initialize execution context\n Processor->>Processor: Resolve task dependencies (DAG)\n \n loop For each ready node\n Processor->>Invoker: invokeSkillNode(node)\n Invoker->>Agent: Execute skill agent\n Agent-->>Invoker: AgentResult\n Invoker-->>Processor: NodeExecutionResult\n Processor->>Processor: Update execution state\n end\n \n Processor-->>API: WorkflowExecutionResult\n API-->>User: Execution ID + status\n```\n\n## Variable Management\n\nWorkflow variables enable data passing between nodes and external input:\n\n### Variable Input Schema\n\n```typescript\ninterface WorkflowVariable {\n id: string;\n name: string;\n type: string;\n required: boolean;\n defaultValue?: unknown;\n}\n```\n\nVariables can be defined at the workflow level and referenced in node prompts using the format `@{type=variable,id=,name=}`.\n\n资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:73]()\n\n## Scheduled Execution\n\nThe Workflow Engine supports time-based triggers through the Schedule Service:\n\n```mermaid\ngraph LR\n S[Schedule] -->|trigger| WP[Workflow Processor]\n WP -->|execute| W[Workflow]\n S -->|email| U[User Notification]\n```\n\n### Schedule Configuration\n\n| Field | Description |\n|-------|-------------|\n| `cronExpression` | Cron expression for timing |\n| `workflowId` | Target workflow to execute |\n| `input` | Input variables for the workflow |\n\n## Skill Invocation\n\nThe Skill Invoker Service handles the execution of skill agents within workflow nodes:\n\n### Invocation Flow\n\n1. **Skill Node Triggered**: Processor identifies ready skill node\n2. **Input Preparation**: Gather context files and variables\n3. **Agent Invocation**: Call skill agent with prepared context\n4. **Result Processing**: Parse agent output, extract files and results\n5. **State Update**: Update node execution status\n\n### Abort Handling\n\nThe engine supports graceful abort of executing nodes:\n\n```typescript\n// Abort signal propagation\nconst abortSignal = new AbortController();\nskillInvoker.invokeSkill({\n executionId,\n nodeId,\n signal: abortSignal.signal,\n});\n```\n\n资料来源：[apps/api/src/modules/skill/skill-invoker.service.ts:1]()\n\n## Error Handling\n\n### Retry Mechanism\n\nFailed nodes can be retried using the retry handler:\n\n```typescript\nconst handleRetry = createRetryHandler(node, resultId);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:52]()\n\n### Error Display\n\nExecution errors are displayed with appropriate styling:\n\n```typescript\n\n {t('canvas.workflow.run.executionFailed')}\n\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:32]()\n\n## Workflow Generation\n\nThe copilot agent can generate workflows dynamically using the `generate_workflow` and `patch_workflow` tools:\n\n| Tool | Use Case |\n|------|----------|\n| `generate_workflow` | Creating new workflows from scratch |\n| `patch_workflow` | Modifying existing workflows |\n\n资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:49]()\n\n### Workflow Plan Structure\n\n```typescript\ninterface WorkflowPlanRecord {\n tasks: Array<{\n id: string;\n title: string;\n prompt: string;\n dependentTasks: string[];\n toolsets: string[];\n }>;\n // ...\n}\n```\n\n## CLI Integration\n\nThe refly CLI provides workflow management commands:\n\n```bash\n# Create workflow\nrefly workflow create --name \"\" --spec ''\n\n# Run workflow\nrefly workflow run [--input '']\n\n# Check status\nrefly workflow run-status \n\n# Abort execution\nrefly workflow abort \n```\n\n资料来源：[packages/cli/README.md:1]()\n\n## Credit Usage Tracking\n\nThe engine tracks credit consumption during workflow execution:\n\n```typescript\ncreditUsage={\n isCreditUsageLoading || hasIncompleteNodes\n ? null\n : (creditUsageData?.data?.total ?? 0)\n}\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/preview.tsx:45]()\n\n## Webhook Integration\n\nWorkflows can trigger external webhooks:\n\n```mermaid\ngraph LR\n W[Workflow Complete] -->|POST| H[Webhook Endpoint]\n H -->|Response| W\n```\n\nWebhook configuration includes error codes and status mappings for reliable integration.\n\n## Public Workflow Pages\n\nThe workflow engine powers multiple page types exported from the web-core package:\n\n| Page | Route | Purpose |\n|------|-------|---------|\n| `WorkflowAppPage` | `/workflow-app` | Main workflow execution UI |\n| `WorkflowListPage` | `/workflow-list` | Browse and manage workflows |\n| `RunHistoryPage` | `/run-history` | View past executions |\n| `RunDetailPage` | `/run-detail` | Detailed execution analysis |\n| `MarketplacePage` | `/marketplace` | Discover workflow templates |\n\n资料来源：[packages/web-core/src/index.ts:1]()\n\n## Summary\n\nThe Workflow Engine is the central orchestration layer that transforms workflow specifications into executable task graphs. It leverages the skill system for node execution, manages complex variable dependencies, and provides comprehensive execution tracking with support for real-time monitoring, scheduled runs, and graceful error handling. The engine's design emphasizes extensibility through toolsets, reliability through retry mechanisms, and observability through detailed execution logging.\n\n---\n\n\n\n## Skill Management\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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/cli/src/skill/loader.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/skill/loader.ts)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n
\n\n# Skill Management\n\n## Overview\n\nThe Skill Management system in Refly provides a modular, extensible framework for creating, installing, updating, and uninstalling reusable workflow snippets called \"Skills.\" Skills enable users to package and share reusable automation logic across the Refly ecosystem, including integration with various IDE environments such as Claude Code, Cursor, VS Code, and others.\n\nSkills are defined using markdown files with frontmatter metadata and can be loaded, validated, and executed through the CLI or API components. The system supports a registry-based distribution model where skills are hosted in the [refly-skills GitHub repository](https://github.com/refly-ai/refly-skills) and can be installed to local IDE environments.\n\n资料来源：[skill-docs-tab.tsx:1-150]()\n\n## Architecture\n\nThe Skill Management system is composed of three primary layers:\n\n| Layer | Component | Purpose |\n|-------|-----------|---------|\n| CLI | `packages/cli/src/skill/loader.ts` | Skill loading, validation, and metadata extraction |\n| UI | `skill-docs-tab.tsx` | User-facing documentation and installation guides |\n| Registry | `refly-skills` repository | Central repository for skill distribution |\n\n```mermaid\ngraph TD\n A[User] --> B[CLI Command
refly skill install]\n A --> C[Web UI
Integration Docs Tab]\n B --> D[Skill Loader
packages/cli/src/skill/loader.ts]\n C --> E[Skill Registry
github.com/refly-ai/refly-skills]\n E --> D\n D --> F[Local Skill Storage
~/.{ide}/skills/]\n D --> G[Symlink Validation]\n G --> H[SKILL.md Loading]\n H --> I[Metadata Extraction]\n I --> J[LoadedSkill Object]\n```\n\n资料来源：[loader.ts:1-60]()\n\n## Skill File Structure\n\nEach skill consists of a standardized directory structure with a mandatory `SKILL.md` file at its root. The skill directory is installed to environment-specific locations based on the target IDE.\n\n### Directory Layout\n\n| File/Folder | Description |\n|-------------|-------------|\n| `SKILL.md` | Main skill definition with frontmatter metadata and content |\n| `references/` | Additional reference files for context (installed for Claude Code) |\n| `commands/` | CLI command definitions (optional, installed for Claude Code) |\n\n资料来源：[skill-docs-tab.tsx:150-200]()\n\n### Supported IDE Installation Paths\n\nSkills are installed to the following locations based on the target IDE:\n\n| IDE | Installation Path |\n|-----|-------------------|\n| Claude Code | `~/.claude/skills/refly/` |\n| Antigravity | `~/.antigravity/skills/` |\n| OpenCode | `~/.opencode/skills/` |\n| Cursor | `~/.cursor/skills/` |\n| VS Code | `~/.vscode/skills/` |\n| Trae | `~/.trae/skills/` |\n\n资料来源：[skill-docs-tab.tsx:200-230]()\n\n## Skill Loading\n\n### The Loader Module\n\nThe skill loader (`packages/cli/src/skill/loader.ts`) provides core functionality for loading and validating skills from the local filesystem.\n\n```typescript\nexport function loadSkill(name: string): LoadedSkill {\n // Loads skill with symlink validation\n // Returns LoadedSkill object with metadata\n}\n```\n\n资料来源：[loader.ts:20-40]()\n\n### Loading Process\n\n```mermaid\ngraph TD\n A[loadSkill name] --> B{Check Symlink Status}\n B -->|Symlink Invalid| C[Error: Symlink Broken]\n B -->|Symlink Valid| D{Skill Directory Exists?}\n D -->|No| E[Error: SKILL_DIR_NOT_FOUND]\n D -->|Yes| F{SKILL.md Exists?}\n F -->|No| G[Error: SKILL_NOT_FOUND]\n F -->|Yes| H[Load Skill Metadata]\n H --> I[Extract Frontmatter]\n I --> J[Validate Frontmatter]\n J --> K[Return LoadedSkill]\n```\n\n### Safe Loading with tryLoadSkill\n\nThe `tryLoadSkill` function provides a safe loading mechanism that returns `null` instead of throwing errors when a skill is not found:\n\n```typescript\nexport function tryLoadSkill(name: string): LoadedSkill | null {\n try {\n return loadSkill(name);\n } catch (err) {\n if (\n (err as { code?: string }).code === SkillErrorCode.SKILL_DIR_NOT_FOUND ||\n (err as { code?: string }).code === SkillErrorCode.SKILL_NOT_FOUND\n ) {\n return null;\n }\n throw err;\n }\n}\n```\n\n资料来源：[loader.ts:70-90]()\n\n## Metadata Extraction\n\n### Frontmatter Parsing\n\nThe `extractSkillMetadata` function allows extraction of skill metadata without fully loading from disk, which is useful for validation and preview operations:\n\n```typescript\nexport function extractSkillMetadata(content: string): {\n frontmatter: SkillFrontmatter | null;\n issues: ValidationIssue[];\n content: string;\n}\n```\n\nThe function performs the following steps:\n\n1. Parses frontmatter from markdown content\n2. Validates frontmatter against schema\n3. Returns extracted metadata and any validation issues\n\n资料来源：[loader.ts:100-120]()\n\n### Validation Issues\n\nWhen frontmatter validation fails, the system returns an array of `ValidationIssue` objects describing each problem. This ensures skills meet the required schema before installation.\n\n## Skill Operations\n\n### Installation from Repository\n\nThe installation process follows these steps:\n\n1. Downloads the skill from the registry repository\n2. Creates the skill directory structure\n3. Validates and installs symlinks to IDE-specific locations\n\n```bash\nrefly skill install \n```\n\n资料来源：[skill-docs-tab.tsx:250-280]()\n\n### Uninstallation\n\nUninstallation removes the skill directory and cleans up all symlinks:\n\n1. Removes skill files from the local directory\n2. Cleans up environment-specific symlinks\n3. Updates skill registry\n\n```bash\nrefly skill uninstall \n```\n\n资料来源：[skill-docs-tab.tsx:100-150]()\n\n### Updating Skills\n\nUpdate operations fetch the latest version from the registry and replace existing files while preserving local customizations.\n\n### Creating New Skills\n\nThe `refly skill create` command initializes a new skill with the standard directory structure:\n\n```bash\nrefly skill create \n```\n\n资料来源：[skill-docs-tab.tsx:300-350]()\n\n## CLI Integration\n\n### Configuration Storage\n\nThe Refly CLI stores configuration at `~/.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资料来源：[packages/cli/README.md:20-40]()\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `REFLY_API_KEY` | API key for authentication |\n| `REFLY_API_ENDPOINT` | Override API endpoint URL |\n\n### Claude Code Integration\n\nAfter running `refly init`, skill files are automatically installed to Claude Code locations:\n\n- `~/.claude/skills/refly/SKILL.md`\n- `~/.claude/skills/refly/references/`\n- `~/.claude/commands/refly-*.md` (if commands directory exists)\n\nThis integration enables Claude Code to:\n\n- Understand Refly workflow concepts\n- Use builder mode correctly\n- Handle state transitions\n- Output deterministic results\n\n资料来源：[packages/cli/README.md:45-60]()\n\n## Error Handling\n\n### Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| `AUTH_REQUIRED` | Not authenticated | Run `refly login` |\n| `BUILDER_NOT_STARTED` | No active builder session | Run `refly builder start` |\n| `VALIDATION_REQUIRED` | Must validate before commit | Run `refly builder validate` |\n| `VALIDATION_ERROR` | DAG validation failed | Check error details |\n| `DUPLICATE_NODE_ID` | Node ID already exists | Use unique ID |\n| `CYCLE_DETECTED` | Circular dependency | Remove cycle |\n| `WORKFLOW_NOT_FOUND` | Workflow does not exist | Check workflow ID |\n| `SKILL_DIR_NOT_FOUND` | Skill directory missing | Reinstall the skill |\n| `SKILL_NOT_FOUND` | SKILL.md file missing | The skill may be corrupted |\n\n资料来源：[packages/cli/README.md:65-75]()\n\n### Error Recovery Suggestions\n\nThe loader provides contextual suggestions for error recovery:\n\n```typescript\nthrow createSkillError(\n SkillErrorCode.SKILL_DIR_NOT_FOUND,\n `Skill '${name}' symlink exists but SKILL.md file is missing`,\n {\n suggestions: [\n 'The skill directory may be corrupted',\n 'Try reinstalling the skill with `refly skill install`',\n ],\n }\n);\n```\n\n资料来源：[loader.ts:30-50]()\n\n## Skill Registry\n\nThe official skill registry is hosted at [github.com/refly-ai/refly-skills](https://github.com/refly-ai/refly-skills). Users can browse available skills at:\n\n```\nhttps://github.com/refly-ai/refly-skills/tree/main/skills\n```\n\n资料来源：[skill-docs-tab.tsx:20-30]()\n\n## Summary\n\nThe Skill Management system provides a complete lifecycle for reusable automation snippets:\n\n- **Creation**: Scaffold new skills with standard structure\n- **Installation**: Fetch from registry and install to IDE environments\n- **Loading**: Validate and parse skill metadata\n- **Execution**: Integrate with Claude Code and other IDEs\n- **Updates**: Fetch latest versions from registry\n- **Uninstallation**: Clean removal with symlink cleanup\n\nThe modular architecture separates concerns between the CLI loader, UI documentation components, and the registry, enabling maintainable and extensible skill management across the Refly ecosystem.\n\n---\n\n\n\n## Canvas Component\n\n### 相关页面\n\n相关主题：[Copilot Integration](#copilot-integration), [System Architecture](#system-architecture)\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/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/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/launchpad/rich-chat-input/mentionList.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx)\n- [packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.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- [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/canvas-resources/share/file-overview.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/canvas-resources/share/file-overview.tsx)\n- [packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx)\n- [packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n- [packages/stores/src/stores/sider.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/sider.ts)\n
\n\n# Canvas Component\n\n## Overview\n\nThe Canvas Component is the core visual workspace system in the Refly AI platform. It provides an interactive, node-based environment for building and executing AI-powered workflows. The Canvas enables users to create, configure, and orchestrate complex AI workflows through a visual interface that combines drag-and-drop node composition with real-time execution monitoring.\n\nThe Canvas system supports multiple node types including agent nodes, tool nodes, document renderers, and webhook integrations. It serves as the primary workspace where users define workflow logic, manage context items, connect to upstream agents, and execute AI-driven processes.\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\n## Architecture\n\n### Component Hierarchy\n\nThe Canvas architecture follows a modular composition pattern with multiple layered components working together to provide the complete workspace experience.\n\n```mermaid\ngraph TD\n A[Canvas Workspace] --> B[Canvas Container]\n A --> C[Top Toolbar]\n A --> D[Side Panel]\n B --> E[Rich Chat Input]\n B --> F[Node System]\n B --> G[Workflow Runner]\n C --> H[Schedule Button]\n C --> I[Integration Docs]\n D --> J[Resource Library]\n D --> K[Sider Store]\n F --> L[Agent Nodes]\n F --> M[Tool Nodes]\n G --> N[Workflow Node Panel]\n G --> O[Action Steps]\n```\n\n### Directory Structure\n\nThe Canvas components are organized in the following structure within `packages/ai-workspace-common/src/components/canvas/`:\n\n| Directory | Purpose |\n|-----------|---------|\n| `nodes/` | Node type definitions and implementations |\n| `workflow-run/` | Workflow execution and monitoring components |\n| `launchpad/rich-chat-input/` | Chat input with @mentions and file handling |\n| `node-preview/` | Node preview and skill response rendering |\n| `top-toolbar/` | Top navigation toolbar components |\n| `webhook/` | Webhook configuration interfaces |\n| `integration-docs/` | Integration documentation modal |\n| `canvas-resources/` | File and resource management |\n| `front-page/` | Recent workflows display |\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\n## Core Components\n\n### Canvas Context\n\nThe Canvas uses React Context to provide global state and utilities across all child components. The context exposes canvas-specific operations including context item management, toolset selection, and agent connections.\n\n```typescript\nconst { canvasId } = useCanvasContext();\n```\n\nThe Canvas context is consumed by multiple sub-components to access shared state such as the current canvas identifier and related workflow metadata. This enables components throughout the canvas tree to access and modify workflow state without prop drilling.\n\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\n### Rich Chat Input\n\nThe Rich Chat Input component provides the primary user interaction mechanism for communicating with AI agents within the Canvas. It supports advanced features including file attachments, @mentions, and real-time message composition.\n\n```typescript\nexport interface RichChatInputRef {\n focus: () => void;\n insertAtSymbol?: () => void;\n}\n```\n\n**Key Features:**\n\n| Feature | Description |\n|---------|-------------|\n| File Upload | Support for single and multiple image uploads |\n| @Mentions | Context-aware mentions for files, agents, and tools |\n| Auto-resize | Dynamic textarea height adjustment |\n| Drag-and-Drop | File drag-and-drop interface support |\n| Tool Store Integration | Access to external tool marketplace |\n\nThe component integrates with the `useAgentNodeManagement` hook to manage query state, context items, and selected toolsets. It also connects to `useAgentConnections` for upstream agent communication.\n\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\n### Mention List\n\nThe mention system provides context-aware suggestions when users type @ symbols in the chat input. It supports multiple mention types with distinct rendering behaviors.\n\n**Mention Types:**\n\n| Type | Source | Rendering |\n|------|--------|-----------|\n| Files | Drive files | File icon with filename |\n| Agents | Skill responses | Skill response icon |\n| Tools | Tool registry | Tool icon |\n| Variables | Canvas variables | Variable type icon (text, image, resource) |\n\n```typescript\nagents: {\n nodeIconProps: (item: MentionItem) => {\n if (item.source === 'agents') {\n return {\n type: 'skillResponse' as CanvasNodeType,\n small: true,\n };\n } else {\n return {\n type: item.variableType as CanvasNodeType,\n small: true,\n url: item.variableType === 'image' ? item.metadata?.imageUrl : undefined,\n };\n }\n },\n emptyStateKey: 'noAgents',\n},\n```\n\nThe mention list automatically formats variable values for display, truncating long text values to 20 characters with an ellipsis indicator.\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx)\n\n## Node System\n\n### Workflow Node Panel\n\nThe Workflow Node Panel provides the execution interface for individual nodes within a workflow. It displays node status, results, and allows users to interact with running workflows.\n\n```typescript\n\n```\n\n**Panel States:**\n\n| State | Description |\n|-------|-------------|\n| Idle | Node not yet executed |\n| Running | Node currently executing with streaming output |\n| Finished | Node completed successfully |\n| Failed | Node execution encountered an error |\n\nThe panel automatically logs events when users expand agent nodes, tracking canvas and node identifiers for analytics purposes:\n\n```typescript\nlogEvent('runlog_agent_expand', null, {\n canvasId,\n nodeId: node.id,\n resultId,\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\n### Action Steps\n\nAction Steps display individual execution steps within skill responses. They render logs with titles and descriptions, supporting status indicators for execution progress.\n\n```typescript\nitems={logs.map((log) => ({\n title: t(`${log.key}.title`, {\n ...log.titleArgs,\n ns: 'skillLog',\n defaultValue: log.key,\n }),\n description: t(`${log.key}.description`, {\n ...log.descriptionArgs,\n ns: 'skillLog',\n defaultValue: '',\n }),\n status: log.status === 'error' ? 'error' : 'finish',\n}))}\n```\n\n**Status Types:**\n\n| Status | Badge Color | Meaning |\n|--------|-------------|---------|\n| `executing` | Blue/Active | Currently running |\n| `waiting` | Yellow | Waiting for input |\n| `finish` | Green | Completed successfully |\n| `error` | Red | Execution failed |\n\nAction steps automatically collapse when execution status changes from `executing` or `waiting` to a terminal state.\n\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## Integration System\n\n### Integration Docs Modal\n\nThe Integration Docs Modal provides a comprehensive interface for viewing and managing canvas integrations. It includes API key management, webhook configuration, and documentation display.\n\n```typescript\n\n setApiKeyModalOpen(false)} />\n setOutputModalOpen(false)}\n canvasId={canvasId}\n/>\n```\n\n**Modal Components:**\n\n| Component | Purpose |\n|-----------|---------|\n| IntegrationDocsModal | Main integration documentation interface |\n| ApiKeyModal | API key management and configuration |\n| ApiOutputModal | API output and testing results |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx)\n\n### Webhook Configuration\n\nThe Webhook Configuration system enables external systems to trigger canvas workflows. It provides a structured interface for managing webhook endpoints and payloads.\n\n```typescript\n
\n {t('webhook.instructions')}\n
    \n
  • {t('webhook.instruction1')}
    • \n
  • {t('webhook.instruction2')}
    • \n
  • {t('webhook.instruction3')}
    • \n
\n
\n```\n\n**Webhook Features:**\n\n- Request body schema definition\n- Parameter documentation with types and descriptions\n- Required field indicators\n- Markdown-formatted descriptions\n\nThe webhook documentation tab renders request body fields in a structured table format with columns for name, type, requirement status, and description.\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## Scheduling System\n\nThe Schedule Button enables users to configure automated workflow execution at specified intervals. It provides a popover interface for schedule management with modal dialogs for limit warnings.\n\n```typescript\nconst handleViewSchedulesClick = () => {\n // Navigate to schedule management\n};\n\n setScheduleLimitModalVisible(false)}>\n {t('common.cancel')}\n ,\n ,\n ]}\n>\n

{t('schedule.limitReached.message')}

\n\n```\n\n**Schedule Features:**\n\n| Feature | Description |\n|---------|-------------|\n| Interval Configuration | Set recurring execution intervals |\n| Limit Detection | Alert when schedule limit is reached |\n| Schedule Management | View and manage existing schedules |\n| Plan Integration | Respects user plan limitations |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n## Resource Management\n\n### File Overview\n\nThe File Overview component provides a grid-based interface for managing canvas resources. It includes search functionality and supports both empty and populated states.\n\n```typescript\n
\n \n
\n```\n\n**Features:**\n\n- Searchable file list with keyword filtering\n- Empty state with \"new resource\" call-to-action\n- Read-only mode support for shared canvases\n- Border-styled input with filled variant\n\nThe component displays a search input field above the file list, allowing users to filter resources by name or metadata.\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/canvas-resources/share/file-overview.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/canvas-resources/share/file-overview.tsx)\n\n### Recent Workflows\n\nThe Recent Workflow component displays a grid of recently accessed workflows on the canvas front page. Each workflow card shows the workflow name, used toolsets, and last update timestamp.\n\n```typescript\n
handleEditCanvas(canvas.id)}>\n
\n
\n
\n {canvas.name || t('common.untitled')}\n
\n \n
\n \n
\n
\n```\n\n**Card Display:**\n\n| Field | Content |\n|-------|---------|\n| Title | Workflow name (truncated to single line) |\n| Toolsets | Visual indicator of used toolsets |\n| Timestamp | Relative time (e.g., \"2 hours ago\") |\n| Actions | Dropdown menu for canvas operations |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx)\n\n## State Management\n\n### Sider Store\n\nThe Canvas state is partially managed through the global Sider Store, which maintains UI state for sidebars, modals, and canvas lists.\n\n```typescript\nexport const useSiderStore = create()(\n devtools((set) => ({\n collapse: false,\n collapseState: 'expanded',\n isManualCollapse: false,\n showSiderDrawer: false,\n canvasList: [],\n projectsList: [],\n sourceList: [],\n showLibraryModal: false,\n showCanvasListModal: false,\n showSettingModal: false,\n showInvitationModal: false,\n settingsModalActiveTab: null,\n }))\n);\n```\n\n**Store Actions:**\n\n| Action | Description |\n|--------|-------------|\n| `setCollapse` | Toggle sidebar collapse state |\n| `setShowSiderDrawer` | Control drawer visibility |\n| `setCanvasList` | Update canvas list data |\n| `setShowLibraryModal` | Toggle library modal |\n| `updateCanvasTitle` | Update canvas title by ID |\n\n资料来源：[packages/stores/src/stores/sider.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/sider.ts)\n\n## Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant RichChatInput\n participant AgentNode\n participant WorkflowPanel\n participant ActionStep\n \n User->>RichChatInput: Submit query with context\n RichChatInput->>AgentNode: Execute agent with toolsets\n AgentNode->>WorkflowPanel: Stream execution status\n WorkflowPanel->>ActionStep: Render logs and progress\n ActionStep-->>User: Display execution steps\n AgentNode-->>RichChatInput: Return result\n WorkflowPanel->>User: Show final output and metrics\n```\n\n## Component Configuration Reference\n\n### Primary Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `title` | string | - | Page title for layout |\n| `actions` | ReactNode | - | Action buttons area |\n| `extra` | ReactNode | - | Extra content area |\n| `fixHeight` | boolean | false | Fix container height |\n| `noPaddingY` | boolean | false | Remove vertical padding |\n| `noPaddingX` | boolean | false | Remove horizontal padding |\n\n### Secondary Layout Configuration\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `title` | string | Detail page title |\n| `desc` | string | Page description |\n| `actions` | ReactNode | Action buttons |\n| `extra` | ReactNode | Extra content |\n| `onBack` | () => void | Back button callback |\n\n## Best Practices\n\n### Node Implementation\n\n1. Always provide unique node identifiers for event tracking\n2. Use the `logEvent` function for analytics when nodes expand or collapse\n3. Implement proper cleanup in `useEffect` return functions\n4. Handle all execution states including idle, running, finished, and failed\n\n### State Management\n\n1. Use Canvas Context for shared state across components\n2. Leverage Sider Store for global UI state\n3. Implement proper lazy loading for performance optimization\n4. Use dependency arrays (`deps`) to trigger context updates when needed\n\n### Integration Development\n\n1. Define clear API schemas for webhook request bodies\n2. Provide localized strings for all user-facing text\n3. Implement proper error handling and user feedback\n4. Support both read-only and editable modes for shared canvases\n\n---\n\n\n\n## Copilot Integration\n\n### 相关页面\n\n相关主题：[Canvas Component](#canvas-component), [API Modules](#api-modules)\n\n
\nRelevant Source Files\n\nThe following source files are referenced in this documentation:\n\n- [apps/api/src/modules/copilot/copilot.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/copilot/copilot.service.ts)\n- [apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/copilot-autogen/copilot-autogen.service.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/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/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/launchpad/rich-chat-input/mentionList.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.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/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n
\n\n# Copilot Integration\n\n## Overview\n\nThe Copilot Integration in Refly represents the core conversational AI interface that enables users to interact with Refly's agentic workflow capabilities. It provides a natural language interface where users can describe intent, attach files, mention workflow variables, and send messages to trigger agent actions within canvas workflows.\n\nThe integration spans both frontend UI components and backend services, creating a bidirectional communication channel between the user interface and the agent execution engine.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph Frontend\n PC[PureCopilot Component]\n CO[Canvas Copilot]\n RCI[RichChatInput]\n ML[MentionList]\n end\n \n subgraph Hooks\n ANM[useAgentNodeManagement]\n AC[useAgentConnections]\n VM[useVariablesManagement]\n end\n \n subgraph Backend\n CS[Copilot Service]\n CAS[CopilotAutogen Service]\n end\n \n subgraph Data Layer\n CF[Context Files]\n AR[Agent Results]\n TC[Tool Calls]\n end\n \n PC --> RCI\n CO --> RCI\n RCI --> ML\n RCI --> ANM\n RCI --> AC\n RCI --> VM\n ANM --> CS\n AC --> CS\n CS --> CAS\n CAS --> CF\n CAS --> AR\n AR --> TC\n```\n\n## Core Components\n\n### PureCopilot Component\n\nThe `PureCopilot` component (`packages/ai-workspace-common/src/components/pure-copilot/index.tsx`) serves as the standalone chat interface for copilot interactions. It handles file attachments, drag-and-drop uploads, and message composition.\n\n**Key Features:**\n- File upload and management via `FileList` component\n- Drag-and-drop support with visual feedback (`handleDragEnter`, `handleDragLeave`, `handleDragOver`, `handleDrop`)\n- Context item management for attached files\n- Source-aware styling (supports `frontPage` and `onboarding` modes)\n\n**Component Props:**\n| Prop | Type | Description |\n|------|------|-------------|\n| `source` | `string` | Context source for styling: `'frontPage'` or `'onboarding'` |\n| `currentCanvasId` | `string` | Active canvas identifier |\n| `contextItems` | `ContextItem[]` | Attached files and context |\n| `relevantUploads` | `Upload[]` | Upload queue items |\n\n资料来源：[packages/ai-workspace-common/src/components/pure-copilot/index.tsx]()()\n\n### RichChatInput Component\n\nThe `RichChatInput` component (`packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx`) provides the primary input interface within canvas workflows. It extends basic chat input with advanced features like variable mentions, tool references, and OAuth integrations.\n\n**Component Interface:**\n```typescript\nexport interface RichChatInputProps {\n readonly?: boolean;\n handleSendMessage: (message: string) => void;\n onUploadImage?: (file: File) => Promise;\n onUploadMultipleImages?: (files: File[]) => Promise;\n onFocus?: () => void;\n placeholder?: string;\n mentionPosition?: MentionPosition;\n nodeId?: string;\n}\n\nexport interface RichChatInputRef {\n focus: () => void;\n insertAtSymbol?: () => void;\n}\n```\n\n**Internal State Management:**\n- `isDragging`: Tracks drag-over state for file drops\n- `isFocused`: Tracks focus state for UI styling\n- `isLogin`: Authentication state from `useUserStoreShallow`\n- `isMentionListVisible`: Controls mention dropdown visibility\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx]()()\n\n### MentionList Component\n\nThe `MentionList` component (`packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx`) provides context-aware suggestions for variables, tools, and other workflow entities during chat composition.\n\n**Mention Types:**\n| Source | Description |\n|--------|-------------|\n| `variables` | Workflow variables available in current canvas |\n| `toolset` | Available tool integrations |\n| `oauth` | OAuth-connected services |\n\n**Keyboard Navigation States:**\n```typescript\ntype FocusLevel = 'first' | 'second';\nconst [focusLevel, setFocusLevel] = useState('first');\nconst [firstLevelIndex, setFirstLevelIndex] = useState(0);\nconst [secondLevelIndex, setSecondLevelIndex] = useState(0);\n```\n\n**Height Tracking:**\nThe component tracks nested list heights for keyboard navigation:\n```typescript\nconst [firstLevelHeight, setFirstLevelHeight] = useState(0);\nconst [secondLevelHeight, setSecondLevelHeight] = useState(0);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx]()()\n\n## Context Management System\n\n### ContextFile Model\n\nThe copilot system uses structured context files to manage files and data passed to agents:\n\n```typescript\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 * Metadata-only version of ContextFile (without content)\n * Used in ContextBlock to reduce token usage - LLM should use read_file to get full content\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### Agent Results\n\nAgent execution produces structured results:\n\n```typescript\nexport interface AgentResult {\n resultId: string;\n title: string;\n content: string;\n outputFiles: ContextFileMeta[];\n}\n```\n\n### Tool Call Metadata\n\nTool calls within agent results are tracked for retrieval:\n\n```typescript\nexport interface ToolCallMeta {\n callId: string;\n toolName: string;\n}\n```\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts]()()\n\n## Backend Services\n\n### Copilot Service\n\nThe backend copilot service handles message processing, agent dispatch, and response streaming.\n\n**Service Location:** `apps/api/src/modules/copilot/copilot.service.ts`\n\n### Copilot Autogen Service\n\nThe `CopilotAutogen` service (`apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts`) manages automatic skill generation and agent orchestration.\n\n**Key Responsibilities:**\n- Generate skills based on user intent\n- Manage skill lifecycle (create, update, delete)\n- Handle skill installation to Claude Code environments\n\n**Skill Installation Path:**\n```\n~/.claude/skills/refly/SKILL.md\n~/.claude/skills/refly/references/\n~/.claude/commands/refly-*.md\n```\n\n资料来源：[apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts]()()\n资料来源：[packages/cli/README.md]()()\n\n## Integration Hooks\n\n### useAgentNodeManagement\n\nManages the agent node state and message handling for a specific node:\n\n```typescript\nconst { query, setQuery, setContextItems, setSelectedToolsets } =\n useAgentNodeManagement(nodeId);\n```\n\n### useAgentConnections\n\nManages connections between agents:\n\n```typescript\nconst { connectToUpstreamAgent } = useAgentConnections();\n```\n\n### useVariablesManagement\n\nManages workflow variables for the current canvas:\n\n```typescript\nconst { data: workflowVariables } = useVariablesManagement(canvasId);\n```\n\n### useVariableView\n\nProvides variable viewing functionality:\n\n```typescript\nconst { handleVariableView } = useVariableView(canvasId);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx]()()\n\n## User Interaction Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant RCI as RichChatInput\n participant ML as MentionList\n participant ANM as useAgentNodeManagement\n participant CS as Copilot Service\n \n User->>RCI: Type message\n RCI->>ML: Check for @ trigger\n ML-->>RCI: Show suggestion dropdown\n User->>ML: Select mention\n ML-->>RCI: Insert mention into query\n User->>RCI: Send message\n RCI->>ANM: handleSendMessage(query)\n ANM->>CS: Process message\n CS-->>ANM: Agent result\n ANM-->>RCI: Update state\n RCI-->>User: Display result\n```\n\n## Configuration Options\n\n### ChatInput Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `readonly` | `boolean` | `false` | Disable input |\n| `autoFocus` | `boolean` | `false` | Focus on mount |\n| `minRows` | `number` | `2` | Minimum input height |\n| `inputClassName` | `string` | - | Custom input styling |\n| `placeholder` | `string` | i18n key | Placeholder text |\n\n### Mention Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placement` | `'bottom'` / `'bottom-start'` | `'bottom-start'` | Dropdown position |\n| `query` | `string` | `''` | Current mention query |\n| `isPolling` | `boolean` | `false` | Enable polling mode |\n| `isOpening` | `boolean` | `false` | Handle OAuth popup |\n\n## Styling and Theming\n\nThe copilot components use CSS custom properties for theming:\n\n```css\n/* Primary copilot styling */\n.pure-copilot-glow-effect {\n box-shadow: var(--copilot-glow-color);\n}\n\n/* Input area */\n.bg-refly-bg-content-z2 {\n background-color: var(--refly-bg-content);\n}\n\n/* Text hierarchy */\n.text-refly-text-0 { color: var(--refly-text-primary); }\n.text-refly-text-1 { color: var(--refly-text-secondary); }\n```\n\n### Source-Specific Styling\n\n```typescript\nclassName={cn(\n 'w-full px-4 py-3 rounded-[12px] border-[1px] border-solid bg-refly-bg-content-z2 transition-all duration-300 relative z-20',\n source === 'frontPage'\n ? cn('border-refly-primary-default my-2')\n : 'border-transparent pure-copilot-glow-effect',\n)}\n```\n\n## Internationalization\n\nThe copilot interface supports i18n with namespace-based translations:\n\n| Namespace | Usage |\n|-----------|-------|\n| `copilot` | Main copilot UI strings |\n| `skillLog` | Skill execution logs |\n| `common` | Shared strings |\n\n**Example Translation Keys:**\n```typescript\nt('copilot.greeting.title')\nt('copilot.pureCopilotPlaceholder')\nt('skillLog.error.title')\n```\n\n## Error Handling\n\n### File Upload Errors\n\nFiles can fail upload with retry capability:\n\n```typescript\nconst { onRemove, onRetry } = useFileUpload({\n uploads: relevantUploads,\n canvasId: currentCanvasId,\n});\n```\n\n### OAuth Popup Handling\n\nThe mention list supports OAuth integration:\n\n```typescript\nopenOAuthPopup?: (toolsetKey: string) => Promise;\n```\n\n## Related Documentation\n\n- [Canvas Integration](canvas-integration) - Workflow canvas features\n- [Skills System](skills-system) - Agent skill management\n- [API Documentation](api-reference) - Backend service APIs\n- [CLI Integration](cli-integration) - Claude Code skill installation\n\n---\n\n\n\n## API Modules\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Authentication and Authorization](#authentication)\n\n
\nRelated Source Files\n\nThe following source files were referenced for generating this documentation:\n\n- [apps/api/src/modules/tool/tool.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/tool/tool.service.ts)\n- [apps/api/src/modules/tool/ptc/tool-execution.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/tool/ptc/tool-execution.service.ts)\n- [apps/api/src/modules/webhook/webhook.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/webhook/webhook.service.ts)\n- [apps/api/src/modules/openapi/openapi.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/openapi/openapi.service.ts)\n\n**Note:** The source files listed above were not available in the context retrieved for this analysis. The following documentation is based on the available context files that reference API module functionality, including UI components and integration documentation.\n\n
\n\n# API Modules\n\nThe Refly API Modules form the backend service layer that handles tool execution, webhook integration, OpenAPI specification management, and skill orchestration. These modules operate within the `apps/api/src/modules/` directory and expose functionality through REST endpoints consumed by the frontend workspace components.\n\n## Overview\n\nThe API modules provide a structured backend architecture for the Refly platform's core capabilities:\n\n| Module | Purpose | Key Files |\n|--------|---------|-----------|\n| **Tool** | Tool registration, management, and execution | `tool.service.ts`, `tool-execution.service.ts` |\n| **Webhook** | Webhook configuration and event delivery | `webhook.service.ts` |\n| **OpenAPI** | OpenAPI specification handling and integration | `openapi.service.ts` |\n| **Skill** | Skill registry and lifecycle management | `skill.service.ts` |\n\n## Tool Module\n\nThe Tool module manages the lifecycle of tools and tool execution within the Refly workspace. Tools are reusable components that can be invoked by agents during workflow execution.\n\n### Tool Service\n\nThe `ToolService` handles tool registration, retrieval, and metadata management. Tools in Refly can belong to toolsets, which group related functionality together.\n\n### Tool Execution Service (PTC)\n\nThe Prompt-Tool-Calling (PTC) execution service manages the runtime execution of tools during agent reasoning. This service:\n\n- Coordinates tool invocation based on agent decisions\n- Manages input/output schemas for tools\n- Handles tool result serialization and context injection\n\n## Webhook Module\n\nThe Webhook module enables event-driven integrations by allowing external services to receive notifications when specific events occur in Refly workflows.\n\n### Webhook Configuration\n\nWebhook configuration includes:\n\n- **Endpoint URL**: The target URL for webhook delivery\n- **Event Types**: Specific events to subscribe to\n- **Authentication**: Headers and secrets for security\n- **Retry Policy**: Configuration for failed delivery attempts\n\n### Webhook Event Delivery\n\n```mermaid\ngraph TD\n A[Workflow Event] --> B[WebhookService]\n B --> C{Event Type Match?}\n C -->|Yes| D[Prepare Payload]\n C -->|No| E[Skip Delivery]\n D --> F{HTTP POST}\n F --> G{Response 2xx?}\n G -->|Success| H[Log Success]\n G -->|Failure| I{Retry Count?}\n I -->|< Max| J[Retry with Backoff]\n J --> F\n I -->|>= Max| K[Mark Failed]\n```\n\n### Webhook Error Codes\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `WEBHOOK_DELIVERY_FAILED` | 500 | Failed to deliver webhook |\n| `WEBHOOK_TIMEOUT` | 504 | Request timed out |\n| `WEBHOOK_INVALID_URL` | 400 | URL format invalid |\n| `WEBHOOK_AUTH_FAILED` | 401 | Authentication failed |\n\n## OpenAPI Module\n\nThe OpenAPI module provides integration with OpenAPI specifications, enabling Refly to:\n\n- Parse and validate OpenAPI documents\n- Generate tool definitions from specifications\n- Support API schema introspection\n\n### Request Body Schema\n\nOpenAPI integration follows standard OpenAPI 3.x conventions for request body definitions:\n\n```typescript\ninterface RequestBodySchema {\n description?: string;\n descriptionKey?: string; // i18n key for localization\n required?: boolean;\n schema: {\n type: string;\n properties: Record;\n };\n}\n```\n\n## Integration with Frontend Components\n\nThe API modules communicate with frontend components through:\n\n1. **Context Files** (`packages/skill-template/src/scheduler/utils/context.ts`): Define data structures for tool and result metadata\n2. **UI Components**: Consume API responses for display in the workspace interface\n\n### Data Flow\n\n```mermaid\ngraph LR\n A[Frontend UI] -->|API Request| B[API Module]\n B --> C[Service Logic]\n C --> D[External Service/Tool]\n D --> E[Response]\n C --> F[Context Metadata]\n F --> G[Frontend Render]\n```\n\n## Module Configuration\n\nAPI modules are configured through:\n\n| Configuration | Location | Description |\n|---------------|----------|-------------|\n| API Endpoint | `~/.refly/config.json` | Base URL for API calls |\n| API Key | Environment `REFLY_API_KEY` | Authentication token |\n| Module-specific | Per-module configuration | Varies by module |\n\n## Skill Module Integration\n\nSkills extend the API module functionality by providing pre-built integrations. The skill system references external skill repositories at `https://github.com/refly-ai/refly-skills` for community-contributed tools and workflows.\n\n## Error Handling\n\nStandard error codes returned by API modules:\n\n| Code | Module | Description |\n|------|--------|-------------|\n| `AUTH_REQUIRED` | All | Authentication required |\n| `TOOL_NOT_FOUND` | Tool | Requested tool does not exist |\n| `WEBHOOK_NOT_CONFIGURED` | Webhook | Webhook endpoint not set |\n| `OPENAPI_INVALID_SPEC` | OpenAPI | Invalid OpenAPI specification |\n| `SKILL_NOT_INSTALLED` | Skill | Requested skill not found |\n\n---\n\n\n\n## Authentication and Authorization\n\n### 相关页面\n\n相关主题：[API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/commands/login.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/commands/login.ts)\n- [packages/cli/src/api/client.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/api/client.ts)\n- [packages/cli/src/commands/status.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/commands/status.ts)\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- [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- [apps/api/src/modules/config/app.config.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/config/app.config.ts)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n
\n\n# Authentication and Authorization\n\n## Overview\n\nThe Refly platform implements a comprehensive authentication and authorization system that supports multiple authentication methods across both CLI and web interfaces. The system provides secure access control through OAuth 2.0 flows, API key authentication, and email/password credentials.\n\n## Architecture Overview\n\nThe authentication system is designed with two primary entry points:\n\n- **CLI Authentication**: Device-based OAuth authorization with optional API key authentication\n- **Web Authentication**: OAuth providers (GitHub, Google) combined with email/password registration and login\n\n```mermaid\ngraph TD\n subgraph \"CLI Authentication\"\n CLI[refly CLI] --> LOGIN[refly login]\n LOGIN --> DEVICE[Device Authorization]\n DEVICE --> POLL[Polling for Auth]\n POLL --> SUCCESS{Authorized?}\n SUCCESS -->|Yes| TOKEN[Access Token]\n SUCCESS -->|No| POLL\n end\n \n subgraph \"Web Authentication\"\n WEB[Web App] --> OAUTH[OAuth Providers]\n WEB --> EMAIL[Email/Password]\n OAUTH --> GH[GitHub]\n OAUTH --> GGL[Google]\n end\n \n subgraph \"API Layer\"\n TOKEN --> API[API Request]\n API --> GUARD[Auth Guard]\n APIKEY[API Key] --> GUARD\n end\n```\n\n## CLI Authentication\n\n### Device Authorization Flow\n\nThe CLI implements a device authorization flow for OAuth authentication. When a user runs `refly login`, the CLI initiates a device authorization request and displays a verification URL for the user to complete authentication in a browser.\n\n**Flow Steps:**\n\n1. CLI generates a unique device ID\n2. CLI polls the authorization server at regular intervals (2 seconds)\n3. User completes authorization in browser\n4. CLI receives access token upon successful authorization\n\n```mermaid\nsequenceDiagram\n participant CLI\n participant Browser\n participant Server\n \n CLI->>Server: Request device code\n Server-->>CLI: Device code, user code, verification URL\n CLI->>Browser: Open verification URL\n CLI->>Server: Poll for authorization status\n Browser->>Server: User authenticates\n Server-->>CLI: Authorization granted\n CLI->>Server: Exchange for access token\n Server-->>CLI: Access token + refresh token\n```\n\n**Key Implementation Details:**\n\n| Parameter | Purpose |\n|-----------|---------|\n| `device_id` | Unique identifier for the device session |\n| `cli_version` | CLI version for server-side validation |\n| `host` | Hostname for session tracking |\n| `pollInterval` | 2000ms polling interval |\n\n资料来源：[packages/cli/src/commands/login.ts:1-100]()\n\n### API Key Authentication\n\nFor programmatic access, the CLI supports API key authentication. Users can authenticate by setting their API key through environment variables or configuration files.\n\n**Environment Variable:**\n```\nREFLY_API_KEY=\n```\n\n**Configuration File:** `~/.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资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n### Token Management\n\nThe CLI manages OAuth tokens with automatic refresh capability. When an access token expires, the system automatically attempts to refresh it before making API requests.\n\n**Token Storage Components:**\n\n| Field | Description |\n|-------|-------------|\n| `accessToken` | Current OAuth access token |\n| `refreshToken` | Token for refreshing expired access tokens |\n| `expiresAt` | Expiration timestamp for the access token |\n\n**Refresh Logic:**\n\n```typescript\nif (expiresAt && new Date(expiresAt) < new Date()) {\n logger.debug('Access token expired, refreshing...');\n try {\n accessToken = await refreshAccessToken();\n } catch (error) {\n throw new AuthError('Session expired, please login again');\n }\n}\n```\n\n资料来源：[packages/cli/src/api/client.ts:1-80]()\n\n### CLI Status Command\n\nThe `refly status` command provides comprehensive authentication status information including:\n\n| Field | Description |\n|-------|-------------|\n| `cli_version` | Installed CLI version |\n| `config_dir` | Configuration directory path |\n| `api_endpoint` | API endpoint URL |\n| `auth_status` | Authentication status (`valid`, `expired`, `invalid`) |\n| `auth_method` | Authentication method used (`oauth`, `apikey`) |\n| `auth_details` | Provider or API key information |\n| `user` | Authenticated user object |\n| `skill` | Skill installation status |\n\n资料来源：[packages/cli/src/commands/status.ts:1-90]()\n\n## Web Authentication\n\n### Supported Authentication Methods\n\nThe web interface supports multiple authentication providers configured at the server level:\n\n| Provider | Type | Description |\n|----------|------|-------------|\n| GitHub | OAuth 2.0 | GitHub OAuth application integration |\n| Google | OAuth 2.0 | Google OAuth integration |\n| Email | Password | Email/password credentials with validation |\n\n**Fallback Behavior:** Email authentication is always enabled as a fallback, regardless of server configuration.\n\n资料来源：[packages/web-core/src/pages/login/index.tsx:1-80]()\n\n### OAuth Flow Implementation\n\n```mermaid\ngraph LR\n A[Login Page] --> B{Check Provider Enabled}\n B -->|GitHub| C[GitHub OAuth]\n B -->|Google| D[Google OAuth]\n B -->|Email| E[Email Form]\n C --> F[Redirect to /v1/auth/provider]\n D --> F\n E --> G[Form Validation]\n G --> H[Email Signup/Login API]\n```\n\n**OAuth URL Construction:**\n\n```typescript\nwindow.location.href = `${serverOrigin}/v1/auth/${provider}`;\n```\n\n**Login Handler:**\n\n```typescript\nconst handleLogin = useCallback((provider: 'github' | 'google') => {\n logEvent('auth::oauth_login_click', provider);\n authStore.setLoginInProgress(true);\n authStore.setLoginProvider(provider);\n storePendingRedirect();\n window.location.href = `${serverOrigin}/v1/auth/${provider}`;\n}, [authStore]);\n```\n\n资料来源：[packages/web-core/src/pages/login/index.tsx:80-120]()\n\n### Email/Password Authentication\n\nEmail authentication includes comprehensive validation rules:\n\n| Rule | Condition | Error Message |\n|------|-----------|---------------|\n| Required | Field is empty | Field is required |\n| Email Format | Invalid email format | Invalid email address |\n| Password Required | Empty password | Password is required |\n| Password Min Length | Less than 8 characters | Password must be at least 8 characters |\n| Password Confirmation | Does not match | Passwords do not match |\n\n**Password Validation Implementation:**\n\n```typescript\nrules={[\n {\n required: true,\n message: t('verifyRules.passwordRequired'),\n },\n ...(authStore.isSignUpMode\n ? [\n {\n min: 8,\n message: t('verifyRules.passwordMin'),\n },\n ]\n : []),\n]}\n```\n\n资料来源：[packages/web-core/src/components/login-modal/login-content.tsx:1-100]()\n\n### Authentication State Management\n\nThe authentication system maintains state through an auth store that tracks:\n\n| State Property | Type | Description |\n|----------------|------|-------------|\n| `loginInProgress` | boolean | Authentication request in progress |\n| `loginProvider` | string | Currently authenticating provider |\n| `isSignUpMode` | boolean | Toggle between sign-in and sign-up forms |\n\n**Email Signup Request:**\n\n```typescript\nconst { data } = await getClient().emailSignup({\n body: {\n email: values.email,\n password: values.password,\n },\n});\n```\n\n资料来源：[packages/web-core/src/pages/login/index.tsx:120-180]()\n\n## Server-Side Configuration\n\n### Application Auth Config\n\nThe API server provides configurable authentication options through environment variables:\n\n| Environment Variable | Type | Default | Description |\n|---------------------|------|---------|-------------|\n| `AUTH_REQUIRE_INVITATION_CODE` | boolean | false | Require invitation code for registration |\n| `INVITATION_MAX_CODES_PER_USER` | number | 20 | Max invitation codes per user |\n| `INVITATION_INVITER_CREDIT_AMOUNT` | number | 500 | Credits awarded to inviter |\n| `INVITATION_INVITEE_CREDIT_AMOUNT` | number | 500 | Credits awarded to invitee |\n| `REGISTRATION_BONUS_CREDIT_AMOUNT` | number | 500 | New user registration bonus |\n\n资料来源：[apps/api/src/modules/config/app.config.ts:1-50]()\n\n### OAuth Provider Configuration\n\nOAuth providers are configured with client credentials:\n\n```typescript\ntwitter: {\n enabled: process.env.TWITTER_AUTH_ENABLED === 'true' || false,\n clientId: process.env.TWITTER_CLIENT_ID || 'test',\n clientSecret: process.env.TWITTER_CLIENT_SECRET || 'test',\n callbackUrl: process.env.TWITTER_CALLBACK_URL || 'test',\n},\nnotion: {\n enabled: process.env.NOTION_AUTH_ENABLED === 'true' || false,\n clientId: process.env.NOTION_CLIENT_ID || 'test',\n clientSecret: process.env.NOTION_CLIENT_SECRET || 'test',\n callbackUrl: process.env.NOTION_CALLBACK_URL || 'test',\n},\n```\n\n资料来源：[apps/api/src/modules/config/app.config.ts:50-80]()\n\n## Authentication Methods Summary\n\n| Method | Use Case | Token Storage | Refresh |\n|--------|----------|---------------|---------|\n| OAuth (CLI Device) | Interactive CLI login | config.json | Automatic |\n| OAuth (Web) | Web application login | HTTP-only cookies | Automatic |\n| API Key | Scripting/CI-CD | Environment/config | N/A |\n| Email/Password | Web registration | HTTP-only cookies | Automatic |\n\n## Error Handling\n\n### CLI Error Codes\n\n| Code | Description | Hint |\n|------|-------------|------|\n| `AUTH_REQUIRED` | Not authenticated | refly login |\n| `INVALID_CREDENTIALS` | Invalid login | Check credentials |\n| `SESSION_EXPIRED` | Token expired | Run refly login again |\n\n### Web Error Handling\n\nThe web interface implements form validation with user-friendly error messages and loading states:\n\n```typescript\nconst handleEmailAuth = useCallback(async () => {\n let values: FormValues;\n try {\n values = await form.validateFields();\n } catch (error) {\n console.error('Error validating form fields', error);\n return;\n }\n \n authStore.setLoginProvider('email');\n authStore.setLoginInProgress(true);\n // ... authentication logic\n}, []);\n```\n\n## Best Practices\n\n1. **CLI Authentication**: Use `refly login` for interactive sessions; use API keys for automated workflows\n2. **Token Refresh**: The CLI automatically handles token refresh; ensure network connectivity for re-authentication\n3. **Security**: Never commit API keys to version control; use environment variables\n4. **Session Management**: Use `refly logout` to clear stored credentials when done\n\n## Related Commands\n\n```bash\nrefly login # Authenticate with OAuth or API key\nrefly logout # Remove stored credentials\nrefly status # Check authentication status\nrefly whoami # Display current user information\n```\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：refly-ai/refly\n\n摘要：发现 21 个潜在踩坑项，其中 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_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：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## 12. 安全/权限坑 · 来源证据：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## 13. 安全/权限坑 · 来源证据：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## 14. 安全/权限坑 · 来源证据：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## 15. 安全/权限坑 · 来源证据：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## 16. 安全/权限坑 · 来源证据：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## 17. 安全/权限坑 · 来源证据：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## 18. 安全/权限坑 · 来源证据：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## 19. 安全/权限坑 · 来源证据：🤖 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## 20. 维护坑 · 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## 21. 维护坑 · 发布节奏不明确\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 项目说明书", "目录", "Project Introduction", "Overview", "Architecture", "Core Features", "Integrations", "CLI Tool", "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- **Project Introduction**：importance `high`\n - source_paths: README.md, packages/skill-template/src/base.ts\n- **Quick Start Guide**：importance `high`\n - source_paths: docs/community-version/self-deploy/index.md, packages/cli/src/commands/workflow/index.ts\n- **System Architecture**：importance `high`\n - source_paths: apps/api/src/app.module.ts, apps/api/src/main.ts, packages/canvas-common/src/types.ts\n- **Project Structure**：importance `medium`\n - source_paths: pnpm-workspace.yaml, turbo.json, apps/api/src/modules, packages\n- **Workflow Engine**：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- **Skill Management**：importance `high`\n - source_paths: apps/api/src/modules/skill-package/skill-package.service.ts, apps/api/src/modules/skill-package/skill-execution.service.ts, packages/skill-template/src/engine/index.ts, packages/cli/src/commands/skill/index.ts\n- **Canvas Component**：importance `high`\n - source_paths: packages/ai-workspace-common/src/components/canvas/index.tsx, packages/ai-workspace-common/src/components/canvas/nodes, packages/canvas-common/src/layout.ts\n- **Copilot Integration**：importance `medium`\n - source_paths: apps/api/src/modules/copilot/copilot.service.ts, packages/ai-workspace-common/src/components/canvas/copilot/index.tsx, apps/api/src/modules/copilot-autogen/copilot-autogen.service.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_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium\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-15 13:25:24 UTC\n\n## 目录\n\n- [Project Introduction](#project-introduction)\n- [Quick Start Guide](#quick-start-guide)\n- [System Architecture](#system-architecture)\n- [Project Structure](#project-structure)\n- [Workflow Engine](#workflow-engine)\n- [Skill Management](#skill-management)\n- [Canvas Component](#canvas-component)\n- [Copilot Integration](#copilot-integration)\n- [API Modules](#api-modules)\n- [Authentication and Authorization](#authentication)\n\n\n\n## Project Introduction\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Quick Start Guide](#quick-start-guide)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/refly-ai/refly/blob/main/README.md)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n- [packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\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- [apps/api/src/modules/workflow-app/email-templates.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow-app/email-templates.ts)\n
\n\n# Project Introduction\n\n## Overview\n\nRefly.ai is a comprehensive workflow automation platform designed for developers and creators. The platform enables users to build, schedule, and automate workflows through a visual canvas interface combined with AI-powered capabilities. Refly.ai provides integrations with popular development tools and supports programmatic access through REST APIs and a Command Line Interface (CLI).\n\n资料来源：[README.md](https://github.com/refly-ai/refly/blob/main/README.md)\n\n## Architecture\n\nThe platform follows a modular monorepo architecture with multiple packages organized under a unified structure.\n\n### Package Structure\n\n| Package | Description |\n|---------|-------------|\n| `packages/layout` | Reusable page layout components for consistent UI structure |\n| `packages/cli` | Command-line interface for workflow management and integration |\n| `packages/ai-workspace-common` | Shared UI components for canvas, nodes, and integrations |\n| `packages/web-core` | Core web application components |\n| `packages/stores` | State management using Zustand |\n| `apps/api` | Backend REST API service |\n\n资料来源：[packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n\n## Core Features\n\n### Visual Workflow Canvas\n\nThe workspace provides a drag-and-drop canvas interface for building workflows. Users can:\n\n- Add and configure various node types including code artifacts\n- Connect nodes to define workflow dependencies\n- Preview artifacts and outputs directly within the canvas\n- Share workflow configurations\n\n```mermaid\ngraph TD\n A[User Canvas] --> B[Canvas Nodes]\n A --> C[Resource Import]\n A --> D[Integration Docs]\n B --> E[Code Artifact]\n B --> F[Skill Execution]\n E --> G[Renderer]\n F --> H[Action Steps]\n G --> I[Preview Output]\n```\n\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\n### Layout System\n\nThe application provides two primary layout components:\n\n**PrimaryPageLayout**: Used for main application pages\n- Configuration options include title, actions, extra content\n- Supports `fixHeight`, `noPaddingY`, `noPaddingX` options\n\n**SecondaryPageLayout**: Designed for detail pages and sub-functional pages\n- Includes title, description, and back button support\n- Ideal for nested views and detail information\n\n```tsx\n\n {({ context, onContextChange }) => (\n <>\n Action Button}\n deps={[]}\n />\n
Page Content
\n \n )}\n\n```\n\n资料来源：[packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n\n### Scheduled Workflows\n\nThe platform supports scheduled workflow execution with configurable limits based on user subscription plans.\n\n| Feature | Description |\n|---------|-------------|\n| Schedule Creation | Create time-based automated workflows |\n| Limit Management | Enforced limits per subscription tier |\n| Schedule Management | View, edit, and disable existing schedules |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n### Template Marketplace\n\nRefly.ai includes a template marketplace where users can publish and discover workflow templates. The platform rewards creators with discount vouchers for publishing templates.\n\n**Email Notification Flow**:\n\n```mermaid\ngraph LR\n A[User Publishes Template] --> B[Generate Voucher]\n B --> C{Locale Detection}\n C -->|zh| D[Chinese Email Template]\n C -->|en| E[English Email Template]\n D --> F[Send Email]\n E --> F\n F --> G[Creator Receives Discount]\n```\n\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## Integrations\n\n### Claude Code Integration\n\nAfter running `refly init`, skill files are installed to Claude Code's directory structure:\n\n| IDE | Path |\n|-----|------|\n| Claude Code | `~/.claude/skills/refly/` |\n| Antigravity | `~/.antigravity/skills/` |\n| OpenCode | `~/.opencode/skills/` |\n| Cursor | `~/.cursor/skills/` |\n| VS Code | `~/.vscode/skills/` |\n| Trae | `~/.trae/skills/` |\n\nThis enables AI assistants to:\n- Understand Refly workflow concepts\n- Use builder mode correctly\n- Handle state transitions\n- Output deterministic results\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n### Webhook Support\n\nThe platform provides webhook integration capabilities with comprehensive error handling:\n\n| Error Code | HTTP Status | Description |\n|------------|-------------|-------------|\n| AUTH_REQUIRED | 401 | Not authenticated |\n| BUILDER_NOT_STARTED | 400 | No active builder session |\n| VALIDATION_REQUIRED | 400 | Must validate before commit |\n| VALIDATION_ERROR | 422 | DAG validation failed |\n| DUPLICATE_NODE_ID | 409 | Node ID already exists |\n| CYCLE_DETECTED | 422 | Circular dependency detected |\n| WORKFLOW_NOT_FOUND | 404 | Workflow does not exist |\n\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\n## CLI Tool\n\nThe Refly CLI provides command-line access to workflow management:\n\n### Installation\n\n```bash\nnpm install -g @refly/cli\n```\n\n### Configuration\n\nConfiguration is stored in `~/.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### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `REFLY_API_KEY` | API key for authentication |\n| `REFLY_API_ENDPOINT` | Override API endpoint |\n\n### Key Commands\n\n| Command | Description |\n|---------|-------------|\n| `refly login` | Authenticate with the platform |\n| `refly builder start` | Start a new builder session |\n| `refly builder validate` | Validate workflow DAG |\n| `refly init` | Initialize Claude Code integration |\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n## State Management\n\nThe application uses Zustand for state management across the workspace:\n\n**Import Resource Store**: Manages modal visibility, file lists, image lists, and waiting list items.\n\n```typescript\ninterface ImportResourceState {\n importResourceModalVisible: boolean;\n extensionModalVisible: boolean;\n fileList: FileItem[];\n imageList: ImageItem[];\n selectedMenuItem: ImportResourceMenuItem;\n waitingList: WaitingListItem[];\n scrapeLinks: LinkMeta[];\n}\n```\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## API Endpoint\n\nThe platform exposes a REST API at:\n\n```\nhttps://api.refly.ai\n```\n\nPublic file access:\n```\nhttps://api.refly.ai/v1/drive/file/public/{fileId}\n```\n\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## Internationalization\n\nThe platform supports multiple locales including:\n- English (en)\n- Chinese Simplified (zh-CN)\n- Chinese Traditional (zh-TW, zh-HK)\n- And other locales detected via browser settings\n\nLanguage detection is used for:\n- Email template selection\n- UI text rendering\n- User-facing notifications\n\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\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Project Introduction](#project-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n- [scripts/cli-deploy/README.md](https://github.com/refly-ai/refly/blob/main/scripts/cli-deploy/README.md)\n- [packages/cli/src/commands/workflow/index.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/commands/workflow/index.ts)\n- [packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\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
\n\n# Quick Start Guide\n\n## Overview\n\nThe Quick Start Guide provides developers and users with the essential steps to begin using Refly, an AI-powered workflow automation platform. This guide covers CLI installation, authentication, workflow creation using Builder mode, workflow execution, and core concepts necessary to start building automated workflows.\n\nRefly's architecture consists of three primary layers: a Command Line Interface (CLI) for local development, a web-based workspace for visual workflow design, and a cloud API for execution and scheduling. The CLI enables developers to build workflows incrementally with local state management, while the web interface provides a graphical canvas for complex workflow design.\n\n资料来源：[packages/cli/README.md:1-20]()\n\n## Prerequisites\n\nBefore starting with Refly, ensure the following requirements are met:\n\n| Requirement | Description |\n|-------------|-------------|\n| Node.js | Version 18 or higher |\n| Package Manager | pnpm (recommended) or npm |\n| Docker | Required for local development services |\n| API Key | Generated from the Refly dashboard |\n\n资料来源：[scripts/cli-deploy/README.md:1-30]()\n\n## Installation\n\n### Installing the CLI\n\nThe Refly CLI can be installed via npm or pnpm. After installation, initialize the CLI to set up configuration files and install skill files for Claude Code integration.\n\n```bash\nnpm install -g @refly/cli\n# or\npnpm add -g @refly/cli\n```\n\n### Initializing the CLI\n\nRun the initialization command to set up the CLI and install skill files:\n\n```bash\nrefly init\n```\n\nThis command performs the following actions:\n\n1. Creates the configuration directory at `~/.refly/`\n2. Generates the initial `config.json` file\n3. Installs skill files to `~/.claude/skills/refly/`\n4. Sets up command shortcuts if the commands directory exists\n\n资料来源：[packages/cli/README.md:1-15]()\n\n## Authentication\n\n### Logging In\n\nAuthenticate with the Refly API using your API key:\n\n```bash\nrefly login\n```\n\nThis command stores your credentials in `~/.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### Checking Authentication Status\n\nVerify your authentication status and view current user information:\n\n```bash\nrefly status\nrefly whoami\n```\n\n### Environment Variables\n\nOverride default configuration using environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `REFLY_API_KEY` | API key for authentication | - |\n| `REFLY_API_ENDPOINT` | Override API endpoint | `https://api.refly.ai` |\n\n资料来源：[packages/cli/README.md:25-45]()\n\n## Core Concepts\n\n### Builder Mode\n\nBuilder mode enables incremental workflow construction with local state management. It uses a deterministic state machine to track workflow progress through defined stages.\n\n```mermaid\ngraph TD\n IDLE[\"IDLE\"] --> DRAFT[\"DRAFT\"]\n DRAFT --> VALIDATED[\"VALIDATED\"]\n VALIDATED --> COMMITTED[\"COMMITTED\"]\n COMMITTED --> IDLE\n DRAFT --> IDLE\n \n style IDLE fill:#e1f5fe\n style DRAFT fill:#fff3e0\n style VALIDATED fill:#e8f5e9\n style COMMITTED fill:#c8e6c9\n```\n\n### Workflow States\n\n| State | Description | Can Transition To |\n|-------|-------------|-------------------|\n| IDLE | No active builder session | DRAFT |\n| DRAFT | Workflow being constructed | IDLE, VALIDATED |\n| VALIDATED | DAG validation passed | IDLE, COMMITTED |\n| COMMITTED | Workflow saved to server | IDLE |\n\n资料来源：[packages/cli/README.md:48-65]()\n\n### Workflow Components\n\nRefly workflows consist of nodes and connections:\n\n| Component | Description |\n|-----------|-------------|\n| Nodes | Individual units of work (agents, tools, data transformations) |\n| Edges | Connections defining data flow between nodes |\n| Variables | Input/output parameters for workflow execution |\n| Schedules | Cron-based triggers for automated execution |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:1-30]()\n\n## Building a Workflow\n\n### Starting a Builder Session\n\nBegin a new workflow or edit an existing one:\n\n```bash\nrefly builder start --name \"my-workflow\"\n```\n\n### Adding Nodes\n\nAdd nodes to define workflow steps:\n\n```bash\nrefly builder add-node --node ''\n```\n\nNode JSON structure:\n\n```json\n{\n \"id\": \"node-001\",\n \"type\": \"agent\",\n \"config\": {\n \"model\": \"gpt-4\",\n \"prompt\": \"Analyze the input document\"\n }\n}\n```\n\n### Connecting Nodes\n\nEstablish data flow between nodes:\n\n```bash\nrefly builder connect --from \"node-001\" --to \"node-002\"\n```\n\n### Viewing the Graph\n\nVisualize the current workflow structure:\n\n```bash\nrefly builder graph\nrefly builder graph --ascii\n```\n\n### Validating the Workflow\n\nBefore committing, validate the workflow's DAG structure:\n\n```bash\nrefly builder validate\n```\n\nThis checks for:\n- Circular dependencies\n- Missing required inputs\n- Invalid node configurations\n- Orphan nodes without connections\n\n### Committing the Workflow\n\nSave the validated workflow to the server:\n\n```bash\nrefly builder commit\n```\n\n### Aborting Changes\n\nDiscard all changes and return to IDLE state:\n\n```bash\nrefly builder abort\n```\n\n资料来源：[packages/cli/README.md:47-80]()\n\n## Workflow Management\n\n### Creating Workflows\n\nCreate a workflow using the CLI:\n\n```bash\nrefly workflow create --name \"\" --spec ''\n```\n\n### Listing Workflows\n\nView all available workflows:\n\n```bash\nrefly workflow list [--limit N]\n```\n\n### Retrieving Workflow Details\n\nGet detailed information about a specific workflow:\n\n```bash\nrefly workflow get \n```\n\n### Editing Workflows\n\nModify an existing workflow:\n\n```bash\nrefly workflow edit --ops ''\n```\n\n### Deleting Workflows\n\nRemove a workflow from the system:\n\n```bash\nrefly workflow delete \n```\n\n资料来源：[packages/cli/src/commands/workflow/index.ts:1-50]()\n\n## Workflow Execution\n\n### Running a Workflow\n\nExecute a workflow with optional input data:\n\n```bash\nrefly workflow run [--input '']\n```\n\nExample with input:\n\n```bash\nrefly workflow run wf-abc123 --input '{\"documentUrl\": \"https://example.com/doc.pdf\"}'\n```\n\n### Monitoring Execution Status\n\nTrack the progress of a running workflow:\n\n```bash\nrefly workflow run-status \n```\n\n### Aborting Execution\n\nStop a running workflow:\n\n```bash\nrefly workflow abort \n```\n\n### Node Debugging\n\nTest individual node types independently:\n\n```bash\nrefly node types [--category ]\nrefly node run --type \"\" --input ''\n```\n\n资料来源：[packages/cli/README.md:82-100]()\n\n## Scheduling Workflows\n\nWorkflows can be scheduled for automated execution using cron-based triggers.\n\n### Schedule Limits\n\nDifferent plans have varying limits on scheduled workflows:\n\n| Plan | Maximum Schedules |\n|------|-------------------|\n| Free | 5 |\n| Pro | 25 |\n| Enterprise | Unlimited |\n\n### Managing Schedules\n\nWhen scheduling limits are reached, users can:\n\n1. View existing schedules\n2. Disable unused schedules\n3. Upgrade to a higher plan\n\nThe schedule management interface provides modals for viewing and deactivating schedules.\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx:1-60]()\n\n## Local Development Setup\n\n### Quick Start Deployment\n\nFor developers with an existing repository clone:\n\n```bash\n./scripts/cli-deploy/quick-start.sh\n```\n\nThis script performs:\n\n1. Building the CLI package\n2. Starting Docker services (PostgreSQL, Redis)\n3. Running database migrations\n4. Seeding global tools data\n5. Starting the API server\n6. Guiding through OAuth login\n7. Generating an API key\n\n### Full Deployment\n\nFor a complete fresh deployment:\n\n```bash\n./scripts/cli-deploy/deploy-cli.sh\n```\n\n### Deployment Options\n\n| Option | Description |\n|--------|-------------|\n| `--skip-build` | Skip building CLI |\n| `--skip-services` | Skip Docker services |\n| `--skip-seed` | Skip seeding data |\n| `--skip-api` | Skip starting API |\n| `--skip-auth` | Skip authentication |\n| `--refly-dir` | Custom installation directory |\n| `--branch` | Use specific Git branch |\n\n资料来源：[scripts/cli-deploy/README.md:10-50]()\n\n## Error Handling\n\n### Common Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| AUTH_REQUIRED | Not authenticated | Run `refly login` |\n| BUILDER_NOT_STARTED | No active builder session | Run `refly builder start` |\n| VALIDATION_REQUIRED | Must validate before commit | Run `refly builder validate` |\n| VALIDATION_ERROR | DAG validation failed | Check error details |\n| DUPLICATE_NODE_ID | Node ID already exists | Use unique ID |\n| CYCLE_DETECTED | Circular dependency | Remove cycle |\n| WORKFLOW_NOT_FOUND | Workflow does not exist | Check workflow ID |\n\n### Builder State Transitions\n\nThe builder enforces strict state transitions:\n\n```mermaid\ngraph LR\n A[IDLE] -->|start| B[DRAFT]\n B -->|validate| C[VALIDATED]\n C -->|commit| D[COMMITTED]\n B -->|abort| A\n C -->|abort| A\n D -->|start| B\n```\n\n资料来源：[packages/cli/README.md:100-120]()\n\n## Next Steps\n\nAfter completing this quick start guide, explore the following topics:\n\n1. **Advanced Workflows** - Implement conditional logic, loops, and parallel execution\n2. **Custom Nodes** - Create reusable node types for specialized tasks\n3. **Integration APIs** - Connect external services and APIs\n4. **Team Collaboration** - Share workflows and manage permissions\n5. **Monitoring & Analytics** - Track workflow performance and costs\n\n### Additional Resources\n\n| Resource | Link |\n|----------|------|\n| Documentation | https://docs.refly.ai |\n| GitHub Discussions | https://github.com/refly-ai/refly-skills/discussions |\n| Issue Tracker | https://github.com/refly-ai/refly-skills/issues |\n| Discord Community | https://discord.gg/refly |\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Project Structure](#project-structure), [API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\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- [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/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.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/pure-copilot/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/pure-copilot/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- [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/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/web-core/src/pages/page-share/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/index.tsx)\n- [packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n
\n\n# System Architecture\n\n## Overview\n\nRefly is a modular AI workspace platform built with a distributed architecture that separates concerns across multiple packages. The system comprises a monorepo structure using pnpm workspaces, organized into application layers (API, web-core) and shared package libraries (canvas-common, stores, skill-template, ai-workspace-common, layout).\n\nThe architecture follows a modular design pattern where each package encapsulates specific functionality, enabling loose coupling between components while maintaining type-safe inter-package communication.\n\n## Package Architecture\n\nThe repository is organized into the following main packages:\n\n| Package | Purpose | Key Dependencies |\n|---------|---------|------------------|\n| `apps/api` | Backend API server | NestJS framework |\n| `apps/web-core` | Frontend application | React 18, TypeScript |\n| `packages/canvas-common` | Shared canvas types and utilities | - |\n| `packages/stores` | Global state management (Zustand) | React |\n| `packages/skill-template` | Skill execution templates | - |\n| `packages/ai-workspace-common` | Reusable UI components | Ant Design, Tailwind CSS |\n| `packages/layout` | Page layout components | React |\n\n资料来源：[packages/stores/src/stores/import-resource.ts:1-50](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts)\n\n## State Management Architecture\n\n### Global Store Structure\n\nThe application uses Zustand for centralized state management through the `packages/stores` package. The store is organized into functional slices with clear action boundaries.\n\n```mermaid\ngraph TD\n A[Root Store] --> B[Import Resource Store]\n A --> C[Canvas Store]\n A --> D[User Store]\n A --> E[UI Store]\n \n B --> B1[importResourceModalVisible]\n B --> B2[extensionModalVisible]\n B --> B3[scrapeLinks]\n B --> B4[waitingList]\n B --> B5[fileList / imageList]\n \n C --> C1[selectedMenuItem]\n C --> C2[insertNodePosition]\n```\n\n### Store Actions Pattern\n\nState updates follow a consistent pattern using Zustand's `set` function with immutable state updates:\n\n```typescript\nsetFileList: (fileList: FileItem[]) => set((state) => ({ ...state, fileList })),\nsetImageList: (imageList: ImageItem[]) => set((state) => ({ ...state, imageList })),\nsetSelectedMenuItem: (menuItem: ImportResourceMenuItem) =>\n set((state) => ({ ...state, selectedMenuItem: menuItem })),\nsetInsertNodePosition: (position: XYPosition) =>\n set((state) => ({ ...state, insertNodePosition: position })),\n```\n\n资料来源：[packages/stores/src/stores/import-resource.ts:1-30](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts)\n\n### Waiting List Management\n\nThe store implements a waiting list feature for handling pending operations:\n\n```typescript\naddToWaitingList: (item: WaitingListItem) =>\n set((state) => ({ ...state, waitingList: [...state.waitingList, item] })),\nremoveFromWaitingList: (id: string) =>\n set((state) => ({\n ...state,\n waitingList: state.waitingList.filter((item) => item.id !== id),\n })),\nupdateWaitingListItem: (id: string, updates: Partial) =>\n set((state) => ({\n ...state,\n waitingList: state.waitingList.map((item) =>\n item.id === id ? { ...item, ...updates } : item\n ),\n })),\n```\n\n资料来源：[packages/stores/src/stores/import-resource.ts:30-45](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/import-resource.ts)\n\n## Canvas System Architecture\n\n### Canvas Overview\n\nThe canvas is the central workspace component where users build workflows by connecting nodes. It supports multiple node types including skills, webhooks, documents, and integrations.\n\n### Node Types\n\n| Node Type | Description | Source Component |\n|-----------|-------------|------------------|\n| Skill Node | Executes AI-powered skills | `action-step.tsx` |\n| Webhook Node | HTTP callback endpoints | `webhook-config-tab.tsx` |\n| Document Node | Rich content rendering | `ArtifactRenderer.tsx` |\n| Integration Node | External service connections | `integration-docs-modal.tsx` |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:1-60](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx)\n\n### Artifact Rendering System\n\nThe `ArtifactRenderer` component handles rendering different content types within the canvas:\n\n```typescript\nconst ArtifactRenderer = memo(\n ({ node, type, content, title, language, status }) => {\n // Renders based on rendererType: 'document' or other\n // Supports purePreview mode for clean rendering\n // Implements custom width/height scaling\n },\n (prevProps, nextProps) => {\n // Custom comparison for memo optimization\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 );\n }\n);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:1-120](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx)\n\n### Action Step Execution Flow\n\nSkills execute through a structured action step system:\n\n```mermaid\ngraph TD\n A[Skill Node] --> B[ActionStep Component]\n B --> C{Status Check}\n C -->|executing| D[Show Progress Logs]\n C -->|waiting| E[Show Pending Indicator]\n C -->|finish| F[Show Results]\n C -->|failed| G[Show Error Logs]\n \n D --> H[ReasoningContent]\n E --> H\n F --> I[Collapsed View]\n G --> J[Error Details]\n```\n\nThe component manages status transitions automatically:\n\n```typescript\nuseEffect(() => {\n if (['executing', 'waiting'].includes(status)) {\n setCollapsed(false);\n } else {\n setCollapsed(true);\n }\n}, [status]);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:50-80](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx)\n\n## Integration System Architecture\n\n### Integration Docs Modal\n\nThe integration system provides a unified interface for configuring external services:\n\n```typescript\ncase 'webhook':\n return (\n \n );\ncase 'api':\n return ;\ncase 'skill':\n return ;\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx:1-80](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx)\n\n### Webhook Documentation Tab\n\nThe webhook documentation provides usage instructions and error handling guidance:\n\n```typescript\n
\n {t('webhook.instructions')}\n
    \n
  • {t('webhook.instruction1')}
    • \n
  • {t('webhook.instruction2')}
    • \n
  • {t('webhook.instruction3')}
    • \n
\n
\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx:1-30](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx)\n\n### Webhook Error Codes\n\n| Error Code | HTTP Status | Description |\n|------------|-------------|-------------|\n| AUTH_REQUIRED | 401 | Not authenticated |\n| VALIDATION_ERROR | 400 | DAG validation failed |\n| DUPLICATE_NODE_ID | 409 | Node ID already exists |\n| CYCLE_DETECTED | 400 | Circular dependency |\n| WORKFLOW_NOT_FOUND | 404 | Workflow does not exist |\n\n## Skill Template System\n\n### Context Management\n\nThe skill template system uses a context-based architecture for passing data between skill execution steps:\n\n```typescript\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\nexport interface ContextFileMeta {\n // Metadata-only version (without content)\n name: string;\n fileId: string;\n type: string;\n summary: string;\n variableId?: string;\n variableName?: string;\n}\n```\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts:1-50](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts)\n\n### Tool Use Pattern\n\nSkills use a standardized tool calling format:\n\n```typescript\n// Matches markdown code block format\nconst TOOL_USE_BLOCK_REGEX = /\\n*```tool_use(?:_result)?[^\\n]*\\n[\\s\\S]*?```\\n*/g;\n\n// Matches standalone XML tags\nconst TOOL_USE_TAG_REGEX = //g;\n```\n\n### Agent Result Structure\n\n```typescript\nexport interface AgentResult {\n resultId: string;\n title: string;\n content: string;\n outputFiles: ContextFileMeta[];\n}\n\nexport interface ToolCallMeta {\n callId: string; // For retrieval via read_tool_result\n toolName: string; // Tool that was called\n}\n```\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts:40-80](https://github.com/refly-ai/refly/blob/main/packages/skill-template/src/scheduler/utils/context.ts)\n\n## Copilot Integration\n\n### Pure Copilot Component\n\nThe copilot provides an AI-powered interface for interacting with the workspace:\n\n```typescript\nconst PureCopilot = ({\n source,\n canvasId,\n onQueryChange,\n}: {\n source: 'frontPage' | 'onboarding';\n canvasId?: string;\n onQueryChange?: (query: string) => void;\n}) => {\n // Supports drag-and-drop file handling\n // Integrates with ChatInput component\n // Manages file uploads and context items\n};\n```\n\n资料来源：[packages/ai-workspace-common/src/components/pure-copilot/index.tsx:1-50](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/pure-copilot/index.tsx)\n\n### Drag and Drop Support\n\n```typescript\n\n```\n\nThe copilot glow effect varies based on source location:\n\n```typescript\nsource === 'frontPage'\n ? cn('border-refly-primary-default my-2')\n : 'border-transparent pure-copilot-glow-effect'\n```\n\n## Modal Architecture\n\n### Modal Container Pattern\n\nThe application uses a centralized modal container with lazy loading:\n\n```typescript\n\n import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({\n default: m.ImportResourceModal,\n }))\n }\n/>\n```\n\n资料来源：[packages/web-core/src/components/layout/ModalContainer.tsx:1-80](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/components/layout/ModalContainer.tsx)\n\n### Modal Types\n\n| Modal | Purpose | Source |\n|-------|---------|--------|\n| ImportResourceModal | Import external resources | `import-resource.ts` |\n| CanvasRenameModal | Rename canvas | `canvas-rename.tsx` |\n| CanvasDeleteModal | Delete canvas | `canvas-delete.tsx` |\n| DuplicateCanvasModal | Duplicate canvas | `duplicate-canvas-modal.tsx` |\n| ClaimedVoucherPopup | Show claimed voucher | `voucher` |\n| EarnedVoucherPopup | Show earned voucher | `voucher` |\n\n## Schedule System\n\n### Schedule Button Component\n\nThe schedule system manages automated workflow execution:\n\n```typescript\n\n \n\n\n{t('common.cancel')},\n ,\n ]}\n>\n {/* Limit reached message */}\n\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx:1-60](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n### Schedule Modal Features\n\n| Feature | Description |\n|---------|-------------|\n| Schedule Limit Modal | Shown when user exceeds plan limits |\n| Deactivate Confirmation | Confirm before disabling schedules |\n| View Schedules | Navigate to schedule management |\n\n## Page Layout System\n\n### Layout Components\n\nThe layout system provides consistent page structures:\n\n```typescript\n// PrimaryPageLayout - Main application pages\n\n {({ context, onContextChange }) => (\n <>\n Action}\n />\n
Content
\n \n )}\n\n\n// SecondaryPageLayout - Detail/sub-pages\n\n {({ context, onContextChange }) => (\n <>\n history.back()}\n />\n
Content
\n \n )}\n\n```\n\n### Layout Configuration Options\n\n| Option | Description |\n|--------|-------------|\n| `title` | Page title |\n| `desc` | Page description |\n| `actions` | Action button area |\n| `extra` | Extra content area |\n| `fixHeight` | Fix content height |\n| `noPaddingX` | Remove horizontal padding |\n| `noPaddingY` | Remove vertical padding |\n\n## Wide Mode Feature\n\nThe page share feature includes a wide mode for expanded content viewing:\n\n```typescript\n{wideMode.isActive && (\n \n
\n {wideMode.nodeId && nodes.find((n) => n.nodeId === wideMode.nodeId)}\n
\n \n)}\n```\n\n资料来源：[packages/web-core/src/pages/page-share/index.tsx:1-80](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/index.tsx)\n\n## Component Rendering Optimization\n\n### Memo Strategy\n\nComponents use React's `memo` with custom comparison functions to optimize re-renders:\n\n```typescript\nexport const ArtifactRenderer = memo(\n Component,\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\n资料来源：[packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:100-120](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx)\n\n## API Error Handling\n\n### Error Response Structure\n\nThe API returns structured error responses:\n\n```typescript\n{\n code: string; // Error code (e.g., \"AUTH_REQUIRED\")\n httpStatus: number; // HTTP status code\n message: string; // Error message\n description: string // Detailed description\n}\n```\n\n### Common Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| AUTH_REQUIRED | Authentication missing | Run `refly login` |\n| BUILDER_NOT_STARTED | No builder session | Run `refly builder start` |\n| VALIDATION_REQUIRED | Validation pending | Run `refly builder validate` |\n| VALIDATION_ERROR | DAG validation failed | Check node connections |\n| DUPLICATE_NODE_ID | ID collision | Use unique identifiers |\n| CYCLE_DETECTED | Circular dependency | Remove cycles from graph |\n\n## Conclusion\n\nThe Refly system architecture demonstrates a well-structured monorepo design with clear separation of concerns across multiple packages. The architecture supports:\n\n- **Scalable State Management**: Centralized Zustand stores with typed actions\n- **Modular UI Components**: Reusable components in ai-workspace-common\n- **Flexible Integration System**: Extensible webhook and API integrations\n- **Optimized Rendering**: Strategic use of React.memo for performance\n- **Type-Safe Communication**: Consistent TypeScript interfaces across packages\n\n---\n\n\n\n## Project Structure\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [pnpm-workspace.yaml](https://github.com/refly-ai/refly/blob/main/pnpm-workspace.yaml)\n- [turbo.json](https://github.com/refly-ai/refly/blob/main/turbo.json)\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/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.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- [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- [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/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/web-core/src/pages/page-share/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/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/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- [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/integration-docs/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.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/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/markdown/plugins/link/render.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx)\n
\n\n# Project Structure\n\n## Overview\n\nRefly is a modern monorepo built with pnpm workspaces and Turborepo for optimized build performance. The repository follows a structured approach to organize code across multiple packages and applications, enabling shared dependencies and consistent development practices across the entire codebase.\n\nThe project architecture separates concerns into discrete packages under the `packages/` directory and applications under the `apps/` directory, with each package serving a specific domain of functionality.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Apps Layer\"\n API[apps/api
Backend API Service]\n WEB[apps/web-core
Web Application]\n end\n\n subgraph \"Packages Layer\"\n STORES[packages/stores
Zustand State Management]\n LAYOUT[packages/layout
Layout Components]\n WORKSPACE[packages/ai-workspace-common
Workspace Components]\n CLI[packages/cli
Command Line Interface]\n end\n\n API --> STORES\n WEB --> STORES\n WEB --> LAYOUT\n WEB --> WORKSPACE\n CLI --> API\n```\n\n## Directory Structure\n\n```\nrefly/\n├── apps/\n│ ├── api/ # Backend API application\n│ │ └── src/\n│ │ └── modules/ # API modules (voucher, workflows, etc.)\n│ └── web/ # Web application entry\n├── packages/\n│ ├── stores/ # State management with Zustand\n│ ├── ai-workspace-common/ # Shared AI workspace components\n│ ├── layout/ # Page layout components\n│ ├── web-core/ # Core web components\n│ └── cli/ # CLI tool\n├── pnpm-workspace.yaml # pnpm workspace configuration\n└── turbo.json # Turborepo configuration\n```\n\n## Applications\n\n### apps/api\n\nThe backend API service built with Node.js. The API module structure follows a modular pattern:\n\n```\napps/api/src/modules/\n├── voucher/ # Voucher/coupon management\n│ └── voucher-email-templates.ts\n└── ... (additional modules)\n```\n\n**Key Characteristics:**\n- Handles business logic and data persistence\n- Provides REST API endpoints for the frontend\n- Contains email template logic for notifications\n- Manages voucher rewards and creator incentives\n\n资料来源：[apps/api/src/modules](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules)\n\n### apps/web-core\n\nThe main web application entry point, responsible for rendering the user interface and handling client-side routing.\n\n## Packages\n\n### packages/stores\n\nState management layer using Zustand. Provides centralized state stores for various application features.\n\n**Primary Store Files:**\n\n| Store File | Purpose |\n|------------|---------|\n| `import-resource.ts` | Manages import resource modal visibility and file lists |\n| `waiting-list.ts` | Handles waiting list state and operations |\n| `scraper-links.ts` | Manages scraped link metadata |\n\n**Key Store Patterns:**\n\n```typescript\n// Store action pattern\nsetImportResourceModalVisible: (visible: boolean) =>\n set((state) => ({ ...state, importResourceModalVisible: visible })),\n\n// Waiting list operations\naddToWaitingList: (item: WaitingListItem) =>\n set((state) => ({ ...state, waitingList: [...state.waitingList, item] })),\n\nremoveFromWaitingList: (id: string) =>\n set((state) => ({\n ...state,\n waitingList: state.waitingList.filter((item) => item.id !== id),\n })),\n```\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### packages/ai-workspace-common\n\nThe core component library for the AI workspace functionality. This package contains the majority of UI components and business logic for the application.\n\n#### Component Organization\n\n```\npackages/ai-workspace-common/src/components/\n├── canvas/ # Canvas-based workflow components\n│ ├── nodes/ # Custom node types\n│ ├── top-toolbar/ # Toolbar components\n│ ├── node-preview/ # Node preview panels\n│ ├── integration-docs/ # Integration documentation\n│ ├── webhook/ # Webhook configuration\n│ └── launchpad/ # Launchpad interface\n├── resource-view/ # Resource display components\n├── pure-copilot/ # Copilot chat interface\n├── slideshow/ # Presentation/slideshow components\n└── markdown/ # Markdown rendering plugins\n```\n\n#### Canvas Components\n\nThe canvas system is a node-based workflow editor:\n\n| Component | Purpose |\n|-----------|---------|\n| `CodeArtifactNode` | Renders code artifacts within canvas nodes |\n| `ArtifactRenderer` | Renders various artifact types (documents, code) |\n| `RichChatInput` | Multi-feature chat input with mentions and uploads |\n| `SkillResponse` | Displays skill execution logs and reasoning |\n| `ActionStep` | Renders individual action steps with status |\n\n**Canvas Node Rendering:**\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx\nexport const CodeArtifactNode = memo(\n ({ id, data, isPreview, selected, hideHandles, onNodeClick }: CodeArtifactNodeProps) => {\n const [isHovered, setIsHovered] = useState(false);\n const { edges } = useCanvasData();\n const { getNode } = useReactFlow();\n // ... node rendering logic\n },\n (prevProps, nextProps) =>\n prevProps.entityId === nextProps.entityId &&\n prevProps?.status === nextProps?.status &&\n prevProps.legacyData?.content === nextProps.legacyData?.content\n);\n```\n\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\n#### Skill Response & Action Steps\n\nThe skill response system displays AI agent execution logs:\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx\nconst ReasoningContent = memo(\n ({\n resultId,\n reasoningContent,\n sources,\n step,\n status,\n }: {\n resultId: string;\n reasoningContent: string;\n sources: Source[];\n step: ActionStep;\n status: ActionStatus;\n }) => {\n const [collapsed, setCollapsed] = useState(status !== 'executing');\n \n // Auto-collapse when step status changes from executing to finish\n useEffect(() => {\n if (['executing', 'waiting'].includes(status)) {\n setCollapsed(false);\n } else {\n setCollapsed(true);\n }\n }, [status]);\n // ...\n }\n);\n```\n\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#### Resource View System\n\nDisplays resource metadata and details:\n\n```typescript\n// packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx\n{resourceDetail?.data?.url && (\n \n {resourceDetail?.data?.url}\n \n)}\n{resourceDetail?.createdAt && (\n

\n {time(resourceDetail?.createdAt, language as LOCALE)\n .utc()\n .fromNow()}\n

\n)}\n```\n\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#### Integration Documentation\n\nWeb-based documentation and configuration interfaces:\n\n```typescript\n// packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx\n\n {t('schedule.viewSchedules') || 'View Schedules'}\n\n\n setScheduleLimitModalVisible(false)}>\n {t('common.cancel') || 'Cancel'}\n ,\n // ...\n ]}\n>\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n#### Artifact Rendering\n\nSupports multiple artifact types with preview capabilities:\n\n```typescript\n// packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx\n
\n \n
\n```\n\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\n#### Markdown Link Rendering\n\nCustom markdown plugin for rendering links with preview functionality:\n\n```typescript\n// packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx\n\n```\n\n资料来源：[packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx)\n\n### packages/web-core\n\nCore web components including modal management and page layouts.\n\n#### Modal Container\n\nCentralized modal management system:\n\n```typescript\n// packages/web-core/src/components/layout/ModalContainer.tsx\n\n import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({\n default: m.ImportResourceModal,\n }))\n }\n/>\n\n\n import('@refly-packages/ai-workspace-common/components/canvas/modals/canvas-rename').then(\n (m) => ({ default: m.CanvasRenameModal }),\n )\n }\n/>\n```\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#### Page Share Module\n\nHandles public page sharing functionality:\n\n```typescript\n// packages/web-core/src/pages/page-share/index.tsx\n{wideMode.isActive && (\n \n
\n {/* Wide mode content */}\n
\n \n)}\n```\n\n资料来源：[packages/web-core/src/pages/page-share/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/page-share/index.tsx)\n\n### packages/layout\n\nPage layout component library providing consistent layout patterns.\n\n#### Layout Components\n\n| Component | Description |\n|-----------|-------------|\n| `PrimaryPageLayout` | Main application pages with title, actions, and extra content areas |\n| `SecondaryPageLayout` | Detail pages with back navigation |\n| `Header` | Reusable header with left/right action areas |\n\n**Primary Layout Usage:**\n\n```tsx\nimport { PrimaryPageLayout, PrimaryPageLayoutContextUpdater } from '@refly/layout';\n\nfunction MainPage() {\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**Configuration Options:**\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `title` | string | Page title displayed in header |\n| `actions` | ReactNode | Action button area |\n| `extra` | ReactNode | Extra content area |\n| `fixHeight` | boolean | Whether to fix height |\n| `noPaddingY` | boolean | Remove vertical padding |\n| `noPaddingX` | boolean | Remove horizontal padding |\n\n资料来源：[packages/layout/README.md](https://github.com/refly-ai/refly/blob/main/packages/layout/README.md)\n\n### packages/cli\n\nCommand-line interface for Refly operations.\n\n#### CLI Features\n\n| Feature | Description |\n|---------|-------------|\n| `refly login` | Authenticate with API key |\n| `refly builder` | Workflow builder commands |\n| `refly workflow` | Workflow execution and management |\n| `refly init` | Initialize Claude Code integration |\n\n**Configuration Storage:**\n\nConfiguration is stored in `~/.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**Environment Variables:**\n\n| Variable | Description |\n|----------|-------------|\n| `REFLY_API_KEY` | API key for authentication |\n| `REFLY_API_ENDPOINT` | Override API endpoint |\n\n#### Claude Code Integration\n\nAfter `refly init`, skill files are installed to:\n- `~/.claude/skills/refly/SKILL.md`\n- `~/.claude/skills/refly/references/`\n- `~/.claude/commands/refly-*.md`\n\n#### Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| AUTH_REQUIRED | Not authenticated | Run `refly login` |\n| BUILDER_NOT_STARTED | No active builder session | Run `refly builder start` |\n| VALIDATION_REQUIRED | Must validate before commit | Run `refly builder validate` |\n| VALIDATION_ERROR | DAG validation failed | Check error details |\n| DUPLICATE_NODE_ID | Node ID already exists | Use unique ID |\n| CYCLE_DETECTED | Circular dependency | Remove cycle |\n| WORKFLOW_NOT_FOUND | Workflow does not exist | Check workflow ID |\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n## Build System\n\n### pnpm Workspaces\n\nThe project uses pnpm workspaces for monorepo management:\n\n```yaml\n# pnpm-workspace.yaml\npackages:\n - 'apps/*'\n - 'packages/*'\n```\n\n### Turborepo\n\nBuild orchestration with Turborepo:\n\n```json\n// turbo.json (inferred from usage)\n{\n \"pipeline\": {\n \"build\": {\n \"dependsOn\": [\"^build\"],\n \"outputs\": [\"dist/**\"]\n }\n }\n}\n```\n\n## Component Communication Flow\n\n```mermaid\ngraph LR\n subgraph \"State Layer\"\n STORES[packages/stores
Zustand Stores]\n end\n\n subgraph \"UI Layer\"\n WEB_CORE[packages/web-core
Modal Container]\n WORKSPACE[packages/ai-workspace-common
Components]\n end\n\n subgraph \"Layout Layer\"\n LAYOUT[packages/layout
Page Layouts]\n end\n\n STORES -->|State Updates| WEB_CORE\n STORES -->|State Updates| WORKSPACE\n WORKSPACE -->|Lazy Loaded| WEB_CORE\n LAYOUT -->|Wraps| WEB_CORE\n```\n\n## Internationalization\n\nThe project uses i18n for translations with namespace support:\n\n```typescript\nconst { t } = useTranslation();\n\n{t('schedule.title') || 'Schedule'}\n{t('schedule.limitReached.title', { ns: 'schedule' })}\n```\n\nTranslation namespaces include:\n- `common` - Common UI strings\n- `schedule` - Schedule-related strings\n- `skillLog` - Skill execution logs\n- `webhook` - Webhook configuration\n- `integration` - Integration documentation\n\n## Key Development Patterns\n\n### Lazy Loading\n\nComponents are lazy-loaded for performance:\n\n```typescript\n\n import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({\n default: m.ImportResourceModal,\n }))\n }\n/>\n```\n\n### Memoization\n\nHeavy components use React.memo for optimization:\n\n```typescript\nexport const CodeArtifactNode = memo(\n ({ id, data, isPreview, selected }: CodeArtifactNodeProps) => {\n // component logic\n },\n (prevProps, nextProps) =>\n prevProps.entityId === nextProps.entityId &&\n prevProps?.status === nextProps?.status\n);\n```\n\n### Custom Hooks\n\nDomain-specific hooks encapsulate business logic:\n\n- `useCanvasData()` - Canvas state access\n- `useAgentNodeManagement()` - Agent node operations\n- `useVariablesManagement()` - Workflow variables\n- `useFetchDriveFiles()` - File fetching\n\n## Development Commands\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Watch mode for development\npnpm dev\n\n# Run API locally\nnode dist/bin/refly.js\n\n---\n\n\n\n## Workflow Engine\n\n### 相关页面\n\n相关主题：[Skill Management](#skill-management), [API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/api/src/modules/workflow/workflow.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow/workflow.service.ts)\n- [apps/api/src/modules/workflow/workflow.processor.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow/workflow.processor.ts)\n- [apps/api/src/modules/schedule/schedule.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/workflow/schedule.service.ts)\n- [packages/canvas-common/src/workflow.ts](https://github.com/refly-ai/refly/blob/main/packages/canvas-common/src/workflow.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- [apps/api/src/modules/skill/skill-invoker.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/skill/skill-invoker.service.ts)\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/pages/workflow-app/index.tsx](https://github.com/refly-ai/refly/blob/main/packages/web-core/src/pages/workflow-app/index.tsx)\n
\n\n# Workflow Engine\n\n## Overview\n\nThe Workflow Engine is the core execution runtime of the refly platform. It orchestrates the execution of workflow graphs composed of interconnected nodes, where each node represents a discrete unit of work executed by specialized agents. The engine handles workflow lifecycle management, from creation through execution, monitoring, and completion.\n\nThe Workflow Engine serves as the backbone for:\n\n- **Workflow Graph Execution**: Parsing and executing directed acyclic graphs (DAGs) of workflow tasks\n- **Node Agent Orchestration**: Invoking skill agents for individual task execution\n- **Variable Management**: Managing workflow-level and node-level variables\n- **Execution State Tracking**: Tracking node status, handling retries, and managing abort signals\n- **Scheduled Execution**: Supporting time-based workflow triggers\n\n## Architecture\n\nThe Workflow Engine follows a layered architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"API Layer\"\n WS[Workflow Service]\n SS[Schedule Service]\n end\n \n subgraph \"Core Engine\"\n WP[Workflow Processor]\n SI[Skill Invoker]\n end\n \n subgraph \"Execution Layer\"\n NA[Node Agents]\n ST[Skill Templates]\n end\n \n subgraph \"State Management\"\n DB[(Database)]\n EV[Event Bus]\n end\n \n WS --> WP\n SS --> WP\n WP --> SI\n SI --> NA\n NA --> ST\n WP <--> DB\n WP <--> EV\n```\n\n### Key Components\n\n| Component | Package | Responsibility |\n|-----------|---------|----------------|\n| `WorkflowService` | apps/api | Workflow CRUD, execution triggering |\n| `WorkflowProcessor` | apps/api | Core DAG execution, state management |\n| `SkillInvokerService` | apps/api | Skill agent invocation, result handling |\n| `ScheduleService` | apps/api | Time-based workflow triggers |\n| `WorkflowRunForm` | ai-workspace-common | Variable input UI for workflow execution |\n\n## Data Models\n\n### Workflow Graph Structure\n\nThe workflow is defined as a graph with nodes and edges:\n\n```typescript\ninterface WorkflowSpec {\n nodes?: Array>;\n edges?: Array>;\n}\n```\n\n资料来源：[apps/api/src/modules/skill-package/skill-package.dto.ts:26]()\n\n### Node Types\n\nWorkflows support multiple node types:\n\n| Node Type | Description |\n|-----------|-------------|\n| `skillResponse` | Skill agent execution nodes |\n| `start` | Entry point node |\n| `end` | Termination node |\n\n资料来源：[packages/web-core/src/pages/workflow-app/index.tsx:142]()\n\n### Task Structure\n\nTasks represent individual units of work within a workflow:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Unique identifier (e.g., \"task-1\") |\n| `title` | string | Concise task name |\n| `prompt` | string | Detailed execution instructions with @ mentions |\n| `dependentTasks` | string[] | Task IDs that must complete first |\n| `toolsets` | string[] | Toolset IDs from Available Tools |\n\n资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:67]()\n\n### Context Files\n\nContext files provide input/output data flow between workflow nodes:\n\n```typescript\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资料来源：[packages/skill-template/src/scheduler/utils/context.ts:14]()\n\n### Agent Results\n\nAgent results encapsulate task execution outcomes:\n\n```typescript\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:27]()\n\n## Workflow Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: workflow.create\n Created --> Running: workflow.run\n Running --> Completed: all nodes finish\n Running --> Failed: unhandled error\n Running --> Aborted: user abort\n Failed --> Running: retry\n Aborted --> [*]\n Completed --> [*]\n```\n\n### Execution States\n\nEach node in a workflow can be in one of the following states:\n\n| Status | Description |\n|--------|-------------|\n| `waiting` | Node is waiting for dependencies to complete |\n| `executing` | Node is currently running |\n| `finish` | Node completed successfully |\n| `failed` | Node execution failed |\n\n资料来源：[packages/ai-workspace-common/src/components/workflow-app/run-logs.tsx:78]()\n\n## Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant API\n participant Processor\n participant Invoker\n participant Agent\n \n User->>API: workflow.run(workflowId, input)\n API->>Processor: processWorkflowExecution()\n Processor->>Processor: Initialize execution context\n Processor->>Processor: Resolve task dependencies (DAG)\n \n loop For each ready node\n Processor->>Invoker: invokeSkillNode(node)\n Invoker->>Agent: Execute skill agent\n Agent-->>Invoker: AgentResult\n Invoker-->>Processor: NodeExecutionResult\n Processor->>Processor: Update execution state\n end\n \n Processor-->>API: WorkflowExecutionResult\n API-->>User: Execution ID + status\n```\n\n## Variable Management\n\nWorkflow variables enable data passing between nodes and external input:\n\n### Variable Input Schema\n\n```typescript\ninterface WorkflowVariable {\n id: string;\n name: string;\n type: string;\n required: boolean;\n defaultValue?: unknown;\n}\n```\n\nVariables can be defined at the workflow level and referenced in node prompts using the format `@{type=variable,id=,name=}`.\n\n资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:73]()\n\n## Scheduled Execution\n\nThe Workflow Engine supports time-based triggers through the Schedule Service:\n\n```mermaid\ngraph LR\n S[Schedule] -->|trigger| WP[Workflow Processor]\n WP -->|execute| W[Workflow]\n S -->|email| U[User Notification]\n```\n\n### Schedule Configuration\n\n| Field | Description |\n|-------|-------------|\n| `cronExpression` | Cron expression for timing |\n| `workflowId` | Target workflow to execute |\n| `input` | Input variables for the workflow |\n\n## Skill Invocation\n\nThe Skill Invoker Service handles the execution of skill agents within workflow nodes:\n\n### Invocation Flow\n\n1. **Skill Node Triggered**: Processor identifies ready skill node\n2. **Input Preparation**: Gather context files and variables\n3. **Agent Invocation**: Call skill agent with prepared context\n4. **Result Processing**: Parse agent output, extract files and results\n5. **State Update**: Update node execution status\n\n### Abort Handling\n\nThe engine supports graceful abort of executing nodes:\n\n```typescript\n// Abort signal propagation\nconst abortSignal = new AbortController();\nskillInvoker.invokeSkill({\n executionId,\n nodeId,\n signal: abortSignal.signal,\n});\n```\n\n资料来源：[apps/api/src/modules/skill/skill-invoker.service.ts:1]()\n\n## Error Handling\n\n### Retry Mechanism\n\nFailed nodes can be retried using the retry handler:\n\n```typescript\nconst handleRetry = createRetryHandler(node, resultId);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:52]()\n\n### Error Display\n\nExecution errors are displayed with appropriate styling:\n\n```typescript\n\n {t('canvas.workflow.run.executionFailed')}\n\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:32]()\n\n## Workflow Generation\n\nThe copilot agent can generate workflows dynamically using the `generate_workflow` and `patch_workflow` tools:\n\n| Tool | Use Case |\n|------|----------|\n| `generate_workflow` | Creating new workflows from scratch |\n| `patch_workflow` | Modifying existing workflows |\n\n资料来源：[packages/skill-template/src/prompts/templates/copilot-agent-system.md:49]()\n\n### Workflow Plan Structure\n\n```typescript\ninterface WorkflowPlanRecord {\n tasks: Array<{\n id: string;\n title: string;\n prompt: string;\n dependentTasks: string[];\n toolsets: string[];\n }>;\n // ...\n}\n```\n\n## CLI Integration\n\nThe refly CLI provides workflow management commands:\n\n```bash\n# Create workflow\nrefly workflow create --name \"\" --spec ''\n\n# Run workflow\nrefly workflow run [--input '']\n\n# Check status\nrefly workflow run-status \n\n# Abort execution\nrefly workflow abort \n```\n\n资料来源：[packages/cli/README.md:1]()\n\n## Credit Usage Tracking\n\nThe engine tracks credit consumption during workflow execution:\n\n```typescript\ncreditUsage={\n isCreditUsageLoading || hasIncompleteNodes\n ? null\n : (creditUsageData?.data?.total ?? 0)\n}\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/workflow-run/preview.tsx:45]()\n\n## Webhook Integration\n\nWorkflows can trigger external webhooks:\n\n```mermaid\ngraph LR\n W[Workflow Complete] -->|POST| H[Webhook Endpoint]\n H -->|Response| W\n```\n\nWebhook configuration includes error codes and status mappings for reliable integration.\n\n## Public Workflow Pages\n\nThe workflow engine powers multiple page types exported from the web-core package:\n\n| Page | Route | Purpose |\n|------|-------|---------|\n| `WorkflowAppPage` | `/workflow-app` | Main workflow execution UI |\n| `WorkflowListPage` | `/workflow-list` | Browse and manage workflows |\n| `RunHistoryPage` | `/run-history` | View past executions |\n| `RunDetailPage` | `/run-detail` | Detailed execution analysis |\n| `MarketplacePage` | `/marketplace` | Discover workflow templates |\n\n资料来源：[packages/web-core/src/index.ts:1]()\n\n## Summary\n\nThe Workflow Engine is the central orchestration layer that transforms workflow specifications into executable task graphs. It leverages the skill system for node execution, manages complex variable dependencies, and provides comprehensive execution tracking with support for real-time monitoring, scheduled runs, and graceful error handling. The engine's design emphasizes extensibility through toolsets, reliability through retry mechanisms, and observability through detailed execution logging.\n\n---\n\n\n\n## Skill Management\n\n### 相关页面\n\n相关主题：[Workflow Engine](#workflow-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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/cli/src/skill/loader.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/skill/loader.ts)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n
\n\n# Skill Management\n\n## Overview\n\nThe Skill Management system in Refly provides a modular, extensible framework for creating, installing, updating, and uninstalling reusable workflow snippets called \"Skills.\" Skills enable users to package and share reusable automation logic across the Refly ecosystem, including integration with various IDE environments such as Claude Code, Cursor, VS Code, and others.\n\nSkills are defined using markdown files with frontmatter metadata and can be loaded, validated, and executed through the CLI or API components. The system supports a registry-based distribution model where skills are hosted in the [refly-skills GitHub repository](https://github.com/refly-ai/refly-skills) and can be installed to local IDE environments.\n\n资料来源：[skill-docs-tab.tsx:1-150]()\n\n## Architecture\n\nThe Skill Management system is composed of three primary layers:\n\n| Layer | Component | Purpose |\n|-------|-----------|---------|\n| CLI | `packages/cli/src/skill/loader.ts` | Skill loading, validation, and metadata extraction |\n| UI | `skill-docs-tab.tsx` | User-facing documentation and installation guides |\n| Registry | `refly-skills` repository | Central repository for skill distribution |\n\n```mermaid\ngraph TD\n A[User] --> B[CLI Command
refly skill install]\n A --> C[Web UI
Integration Docs Tab]\n B --> D[Skill Loader
packages/cli/src/skill/loader.ts]\n C --> E[Skill Registry
github.com/refly-ai/refly-skills]\n E --> D\n D --> F[Local Skill Storage
~/.{ide}/skills/]\n D --> G[Symlink Validation]\n G --> H[SKILL.md Loading]\n H --> I[Metadata Extraction]\n I --> J[LoadedSkill Object]\n```\n\n资料来源：[loader.ts:1-60]()\n\n## Skill File Structure\n\nEach skill consists of a standardized directory structure with a mandatory `SKILL.md` file at its root. The skill directory is installed to environment-specific locations based on the target IDE.\n\n### Directory Layout\n\n| File/Folder | Description |\n|-------------|-------------|\n| `SKILL.md` | Main skill definition with frontmatter metadata and content |\n| `references/` | Additional reference files for context (installed for Claude Code) |\n| `commands/` | CLI command definitions (optional, installed for Claude Code) |\n\n资料来源：[skill-docs-tab.tsx:150-200]()\n\n### Supported IDE Installation Paths\n\nSkills are installed to the following locations based on the target IDE:\n\n| IDE | Installation Path |\n|-----|-------------------|\n| Claude Code | `~/.claude/skills/refly/` |\n| Antigravity | `~/.antigravity/skills/` |\n| OpenCode | `~/.opencode/skills/` |\n| Cursor | `~/.cursor/skills/` |\n| VS Code | `~/.vscode/skills/` |\n| Trae | `~/.trae/skills/` |\n\n资料来源：[skill-docs-tab.tsx:200-230]()\n\n## Skill Loading\n\n### The Loader Module\n\nThe skill loader (`packages/cli/src/skill/loader.ts`) provides core functionality for loading and validating skills from the local filesystem.\n\n```typescript\nexport function loadSkill(name: string): LoadedSkill {\n // Loads skill with symlink validation\n // Returns LoadedSkill object with metadata\n}\n```\n\n资料来源：[loader.ts:20-40]()\n\n### Loading Process\n\n```mermaid\ngraph TD\n A[loadSkill name] --> B{Check Symlink Status}\n B -->|Symlink Invalid| C[Error: Symlink Broken]\n B -->|Symlink Valid| D{Skill Directory Exists?}\n D -->|No| E[Error: SKILL_DIR_NOT_FOUND]\n D -->|Yes| F{SKILL.md Exists?}\n F -->|No| G[Error: SKILL_NOT_FOUND]\n F -->|Yes| H[Load Skill Metadata]\n H --> I[Extract Frontmatter]\n I --> J[Validate Frontmatter]\n J --> K[Return LoadedSkill]\n```\n\n### Safe Loading with tryLoadSkill\n\nThe `tryLoadSkill` function provides a safe loading mechanism that returns `null` instead of throwing errors when a skill is not found:\n\n```typescript\nexport function tryLoadSkill(name: string): LoadedSkill | null {\n try {\n return loadSkill(name);\n } catch (err) {\n if (\n (err as { code?: string }).code === SkillErrorCode.SKILL_DIR_NOT_FOUND ||\n (err as { code?: string }).code === SkillErrorCode.SKILL_NOT_FOUND\n ) {\n return null;\n }\n throw err;\n }\n}\n```\n\n资料来源：[loader.ts:70-90]()\n\n## Metadata Extraction\n\n### Frontmatter Parsing\n\nThe `extractSkillMetadata` function allows extraction of skill metadata without fully loading from disk, which is useful for validation and preview operations:\n\n```typescript\nexport function extractSkillMetadata(content: string): {\n frontmatter: SkillFrontmatter | null;\n issues: ValidationIssue[];\n content: string;\n}\n```\n\nThe function performs the following steps:\n\n1. Parses frontmatter from markdown content\n2. Validates frontmatter against schema\n3. Returns extracted metadata and any validation issues\n\n资料来源：[loader.ts:100-120]()\n\n### Validation Issues\n\nWhen frontmatter validation fails, the system returns an array of `ValidationIssue` objects describing each problem. This ensures skills meet the required schema before installation.\n\n## Skill Operations\n\n### Installation from Repository\n\nThe installation process follows these steps:\n\n1. Downloads the skill from the registry repository\n2. Creates the skill directory structure\n3. Validates and installs symlinks to IDE-specific locations\n\n```bash\nrefly skill install \n```\n\n资料来源：[skill-docs-tab.tsx:250-280]()\n\n### Uninstallation\n\nUninstallation removes the skill directory and cleans up all symlinks:\n\n1. Removes skill files from the local directory\n2. Cleans up environment-specific symlinks\n3. Updates skill registry\n\n```bash\nrefly skill uninstall \n```\n\n资料来源：[skill-docs-tab.tsx:100-150]()\n\n### Updating Skills\n\nUpdate operations fetch the latest version from the registry and replace existing files while preserving local customizations.\n\n### Creating New Skills\n\nThe `refly skill create` command initializes a new skill with the standard directory structure:\n\n```bash\nrefly skill create \n```\n\n资料来源：[skill-docs-tab.tsx:300-350]()\n\n## CLI Integration\n\n### Configuration Storage\n\nThe Refly CLI stores configuration at `~/.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资料来源：[packages/cli/README.md:20-40]()\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `REFLY_API_KEY` | API key for authentication |\n| `REFLY_API_ENDPOINT` | Override API endpoint URL |\n\n### Claude Code Integration\n\nAfter running `refly init`, skill files are automatically installed to Claude Code locations:\n\n- `~/.claude/skills/refly/SKILL.md`\n- `~/.claude/skills/refly/references/`\n- `~/.claude/commands/refly-*.md` (if commands directory exists)\n\nThis integration enables Claude Code to:\n\n- Understand Refly workflow concepts\n- Use builder mode correctly\n- Handle state transitions\n- Output deterministic results\n\n资料来源：[packages/cli/README.md:45-60]()\n\n## Error Handling\n\n### Error Codes\n\n| Code | Description | Resolution |\n|------|-------------|------------|\n| `AUTH_REQUIRED` | Not authenticated | Run `refly login` |\n| `BUILDER_NOT_STARTED` | No active builder session | Run `refly builder start` |\n| `VALIDATION_REQUIRED` | Must validate before commit | Run `refly builder validate` |\n| `VALIDATION_ERROR` | DAG validation failed | Check error details |\n| `DUPLICATE_NODE_ID` | Node ID already exists | Use unique ID |\n| `CYCLE_DETECTED` | Circular dependency | Remove cycle |\n| `WORKFLOW_NOT_FOUND` | Workflow does not exist | Check workflow ID |\n| `SKILL_DIR_NOT_FOUND` | Skill directory missing | Reinstall the skill |\n| `SKILL_NOT_FOUND` | SKILL.md file missing | The skill may be corrupted |\n\n资料来源：[packages/cli/README.md:65-75]()\n\n### Error Recovery Suggestions\n\nThe loader provides contextual suggestions for error recovery:\n\n```typescript\nthrow createSkillError(\n SkillErrorCode.SKILL_DIR_NOT_FOUND,\n `Skill '${name}' symlink exists but SKILL.md file is missing`,\n {\n suggestions: [\n 'The skill directory may be corrupted',\n 'Try reinstalling the skill with `refly skill install`',\n ],\n }\n);\n```\n\n资料来源：[loader.ts:30-50]()\n\n## Skill Registry\n\nThe official skill registry is hosted at [github.com/refly-ai/refly-skills](https://github.com/refly-ai/refly-skills). Users can browse available skills at:\n\n```\nhttps://github.com/refly-ai/refly-skills/tree/main/skills\n```\n\n资料来源：[skill-docs-tab.tsx:20-30]()\n\n## Summary\n\nThe Skill Management system provides a complete lifecycle for reusable automation snippets:\n\n- **Creation**: Scaffold new skills with standard structure\n- **Installation**: Fetch from registry and install to IDE environments\n- **Loading**: Validate and parse skill metadata\n- **Execution**: Integrate with Claude Code and other IDEs\n- **Updates**: Fetch latest versions from registry\n- **Uninstallation**: Clean removal with symlink cleanup\n\nThe modular architecture separates concerns between the CLI loader, UI documentation components, and the registry, enabling maintainable and extensible skill management across the Refly ecosystem.\n\n---\n\n\n\n## Canvas Component\n\n### 相关页面\n\n相关主题：[Copilot Integration](#copilot-integration), [System Architecture](#system-architecture)\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/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/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/launchpad/rich-chat-input/mentionList.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx)\n- [packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.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- [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/canvas-resources/share/file-overview.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/canvas-resources/share/file-overview.tsx)\n- [packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx)\n- [packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n- [packages/stores/src/stores/sider.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/sider.ts)\n
\n\n# Canvas Component\n\n## Overview\n\nThe Canvas Component is the core visual workspace system in the Refly AI platform. It provides an interactive, node-based environment for building and executing AI-powered workflows. The Canvas enables users to create, configure, and orchestrate complex AI workflows through a visual interface that combines drag-and-drop node composition with real-time execution monitoring.\n\nThe Canvas system supports multiple node types including agent nodes, tool nodes, document renderers, and webhook integrations. It serves as the primary workspace where users define workflow logic, manage context items, connect to upstream agents, and execute AI-driven processes.\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\n## Architecture\n\n### Component Hierarchy\n\nThe Canvas architecture follows a modular composition pattern with multiple layered components working together to provide the complete workspace experience.\n\n```mermaid\ngraph TD\n A[Canvas Workspace] --> B[Canvas Container]\n A --> C[Top Toolbar]\n A --> D[Side Panel]\n B --> E[Rich Chat Input]\n B --> F[Node System]\n B --> G[Workflow Runner]\n C --> H[Schedule Button]\n C --> I[Integration Docs]\n D --> J[Resource Library]\n D --> K[Sider Store]\n F --> L[Agent Nodes]\n F --> M[Tool Nodes]\n G --> N[Workflow Node Panel]\n G --> O[Action Steps]\n```\n\n### Directory Structure\n\nThe Canvas components are organized in the following structure within `packages/ai-workspace-common/src/components/canvas/`:\n\n| Directory | Purpose |\n|-----------|---------|\n| `nodes/` | Node type definitions and implementations |\n| `workflow-run/` | Workflow execution and monitoring components |\n| `launchpad/rich-chat-input/` | Chat input with @mentions and file handling |\n| `node-preview/` | Node preview and skill response rendering |\n| `top-toolbar/` | Top navigation toolbar components |\n| `webhook/` | Webhook configuration interfaces |\n| `integration-docs/` | Integration documentation modal |\n| `canvas-resources/` | File and resource management |\n| `front-page/` | Recent workflows display |\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\n## Core Components\n\n### Canvas Context\n\nThe Canvas uses React Context to provide global state and utilities across all child components. The context exposes canvas-specific operations including context item management, toolset selection, and agent connections.\n\n```typescript\nconst { canvasId } = useCanvasContext();\n```\n\nThe Canvas context is consumed by multiple sub-components to access shared state such as the current canvas identifier and related workflow metadata. This enables components throughout the canvas tree to access and modify workflow state without prop drilling.\n\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\n### Rich Chat Input\n\nThe Rich Chat Input component provides the primary user interaction mechanism for communicating with AI agents within the Canvas. It supports advanced features including file attachments, @mentions, and real-time message composition.\n\n```typescript\nexport interface RichChatInputRef {\n focus: () => void;\n insertAtSymbol?: () => void;\n}\n```\n\n**Key Features:**\n\n| Feature | Description |\n|---------|-------------|\n| File Upload | Support for single and multiple image uploads |\n| @Mentions | Context-aware mentions for files, agents, and tools |\n| Auto-resize | Dynamic textarea height adjustment |\n| Drag-and-Drop | File drag-and-drop interface support |\n| Tool Store Integration | Access to external tool marketplace |\n\nThe component integrates with the `useAgentNodeManagement` hook to manage query state, context items, and selected toolsets. It also connects to `useAgentConnections` for upstream agent communication.\n\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\n### Mention List\n\nThe mention system provides context-aware suggestions when users type @ symbols in the chat input. It supports multiple mention types with distinct rendering behaviors.\n\n**Mention Types:**\n\n| Type | Source | Rendering |\n|------|--------|-----------|\n| Files | Drive files | File icon with filename |\n| Agents | Skill responses | Skill response icon |\n| Tools | Tool registry | Tool icon |\n| Variables | Canvas variables | Variable type icon (text, image, resource) |\n\n```typescript\nagents: {\n nodeIconProps: (item: MentionItem) => {\n if (item.source === 'agents') {\n return {\n type: 'skillResponse' as CanvasNodeType,\n small: true,\n };\n } else {\n return {\n type: item.variableType as CanvasNodeType,\n small: true,\n url: item.variableType === 'image' ? item.metadata?.imageUrl : undefined,\n };\n }\n },\n emptyStateKey: 'noAgents',\n},\n```\n\nThe mention list automatically formats variable values for display, truncating long text values to 20 characters with an ellipsis indicator.\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx)\n\n## Node System\n\n### Workflow Node Panel\n\nThe Workflow Node Panel provides the execution interface for individual nodes within a workflow. It displays node status, results, and allows users to interact with running workflows.\n\n```typescript\n\n```\n\n**Panel States:**\n\n| State | Description |\n|-------|-------------|\n| Idle | Node not yet executed |\n| Running | Node currently executing with streaming output |\n| Finished | Node completed successfully |\n| Failed | Node execution encountered an error |\n\nThe panel automatically logs events when users expand agent nodes, tracking canvas and node identifiers for analytics purposes:\n\n```typescript\nlogEvent('runlog_agent_expand', null, {\n canvasId,\n nodeId: node.id,\n resultId,\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\n### Action Steps\n\nAction Steps display individual execution steps within skill responses. They render logs with titles and descriptions, supporting status indicators for execution progress.\n\n```typescript\nitems={logs.map((log) => ({\n title: t(`${log.key}.title`, {\n ...log.titleArgs,\n ns: 'skillLog',\n defaultValue: log.key,\n }),\n description: t(`${log.key}.description`, {\n ...log.descriptionArgs,\n ns: 'skillLog',\n defaultValue: '',\n }),\n status: log.status === 'error' ? 'error' : 'finish',\n}))}\n```\n\n**Status Types:**\n\n| Status | Badge Color | Meaning |\n|--------|-------------|---------|\n| `executing` | Blue/Active | Currently running |\n| `waiting` | Yellow | Waiting for input |\n| `finish` | Green | Completed successfully |\n| `error` | Red | Execution failed |\n\nAction steps automatically collapse when execution status changes from `executing` or `waiting` to a terminal state.\n\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## Integration System\n\n### Integration Docs Modal\n\nThe Integration Docs Modal provides a comprehensive interface for viewing and managing canvas integrations. It includes API key management, webhook configuration, and documentation display.\n\n```typescript\n\n setApiKeyModalOpen(false)} />\n setOutputModalOpen(false)}\n canvasId={canvasId}\n/>\n```\n\n**Modal Components:**\n\n| Component | Purpose |\n|-----------|---------|\n| IntegrationDocsModal | Main integration documentation interface |\n| ApiKeyModal | API key management and configuration |\n| ApiOutputModal | API output and testing results |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx)\n\n### Webhook Configuration\n\nThe Webhook Configuration system enables external systems to trigger canvas workflows. It provides a structured interface for managing webhook endpoints and payloads.\n\n```typescript\n
\n {t('webhook.instructions')}\n
    \n
  • {t('webhook.instruction1')}
    • \n
  • {t('webhook.instruction2')}
    • \n
  • {t('webhook.instruction3')}
    • \n
\n
\n```\n\n**Webhook Features:**\n\n- Request body schema definition\n- Parameter documentation with types and descriptions\n- Required field indicators\n- Markdown-formatted descriptions\n\nThe webhook documentation tab renders request body fields in a structured table format with columns for name, type, requirement status, and description.\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## Scheduling System\n\nThe Schedule Button enables users to configure automated workflow execution at specified intervals. It provides a popover interface for schedule management with modal dialogs for limit warnings.\n\n```typescript\nconst handleViewSchedulesClick = () => {\n // Navigate to schedule management\n};\n\n setScheduleLimitModalVisible(false)}>\n {t('common.cancel')}\n ,\n ,\n ]}\n>\n

{t('schedule.limitReached.message')}

\n\n```\n\n**Schedule Features:**\n\n| Feature | Description |\n|---------|-------------|\n| Interval Configuration | Set recurring execution intervals |\n| Limit Detection | Alert when schedule limit is reached |\n| Schedule Management | View and manage existing schedules |\n| Plan Integration | Respects user plan limitations |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx)\n\n## Resource Management\n\n### File Overview\n\nThe File Overview component provides a grid-based interface for managing canvas resources. It includes search functionality and supports both empty and populated states.\n\n```typescript\n
\n \n
\n```\n\n**Features:**\n\n- Searchable file list with keyword filtering\n- Empty state with \"new resource\" call-to-action\n- Read-only mode support for shared canvases\n- Border-styled input with filled variant\n\nThe component displays a search input field above the file list, allowing users to filter resources by name or metadata.\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/canvas-resources/share/file-overview.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/canvas-resources/share/file-overview.tsx)\n\n### Recent Workflows\n\nThe Recent Workflow component displays a grid of recently accessed workflows on the canvas front page. Each workflow card shows the workflow name, used toolsets, and last update timestamp.\n\n```typescript\n
handleEditCanvas(canvas.id)}>\n
\n
\n
\n {canvas.name || t('common.untitled')}\n
\n \n
\n \n
\n
\n```\n\n**Card Display:**\n\n| Field | Content |\n|-------|---------|\n| Title | Workflow name (truncated to single line) |\n| Toolsets | Visual indicator of used toolsets |\n| Timestamp | Relative time (e.g., \"2 hours ago\") |\n| Actions | Dropdown menu for canvas operations |\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx)\n\n## State Management\n\n### Sider Store\n\nThe Canvas state is partially managed through the global Sider Store, which maintains UI state for sidebars, modals, and canvas lists.\n\n```typescript\nexport const useSiderStore = create()(\n devtools((set) => ({\n collapse: false,\n collapseState: 'expanded',\n isManualCollapse: false,\n showSiderDrawer: false,\n canvasList: [],\n projectsList: [],\n sourceList: [],\n showLibraryModal: false,\n showCanvasListModal: false,\n showSettingModal: false,\n showInvitationModal: false,\n settingsModalActiveTab: null,\n }))\n);\n```\n\n**Store Actions:**\n\n| Action | Description |\n|--------|-------------|\n| `setCollapse` | Toggle sidebar collapse state |\n| `setShowSiderDrawer` | Control drawer visibility |\n| `setCanvasList` | Update canvas list data |\n| `setShowLibraryModal` | Toggle library modal |\n| `updateCanvasTitle` | Update canvas title by ID |\n\n资料来源：[packages/stores/src/stores/sider.ts](https://github.com/refly-ai/refly/blob/main/packages/stores/src/stores/sider.ts)\n\n## Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant RichChatInput\n participant AgentNode\n participant WorkflowPanel\n participant ActionStep\n \n User->>RichChatInput: Submit query with context\n RichChatInput->>AgentNode: Execute agent with toolsets\n AgentNode->>WorkflowPanel: Stream execution status\n WorkflowPanel->>ActionStep: Render logs and progress\n ActionStep-->>User: Display execution steps\n AgentNode-->>RichChatInput: Return result\n WorkflowPanel->>User: Show final output and metrics\n```\n\n## Component Configuration Reference\n\n### Primary Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `title` | string | - | Page title for layout |\n| `actions` | ReactNode | - | Action buttons area |\n| `extra` | ReactNode | - | Extra content area |\n| `fixHeight` | boolean | false | Fix container height |\n| `noPaddingY` | boolean | false | Remove vertical padding |\n| `noPaddingX` | boolean | false | Remove horizontal padding |\n\n### Secondary Layout Configuration\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `title` | string | Detail page title |\n| `desc` | string | Page description |\n| `actions` | ReactNode | Action buttons |\n| `extra` | ReactNode | Extra content |\n| `onBack` | () => void | Back button callback |\n\n## Best Practices\n\n### Node Implementation\n\n1. Always provide unique node identifiers for event tracking\n2. Use the `logEvent` function for analytics when nodes expand or collapse\n3. Implement proper cleanup in `useEffect` return functions\n4. Handle all execution states including idle, running, finished, and failed\n\n### State Management\n\n1. Use Canvas Context for shared state across components\n2. Leverage Sider Store for global UI state\n3. Implement proper lazy loading for performance optimization\n4. Use dependency arrays (`deps`) to trigger context updates when needed\n\n### Integration Development\n\n1. Define clear API schemas for webhook request bodies\n2. Provide localized strings for all user-facing text\n3. Implement proper error handling and user feedback\n4. Support both read-only and editable modes for shared canvases\n\n---\n\n\n\n## Copilot Integration\n\n### 相关页面\n\n相关主题：[Canvas Component](#canvas-component), [API Modules](#api-modules)\n\n
\nRelevant Source Files\n\nThe following source files are referenced in this documentation:\n\n- [apps/api/src/modules/copilot/copilot.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/copilot/copilot.service.ts)\n- [apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/copilot-autogen/copilot-autogen.service.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/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/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/launchpad/rich-chat-input/mentionList.tsx](https://github.com/refly-ai/refly/blob/main/packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.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/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n
\n\n# Copilot Integration\n\n## Overview\n\nThe Copilot Integration in Refly represents the core conversational AI interface that enables users to interact with Refly's agentic workflow capabilities. It provides a natural language interface where users can describe intent, attach files, mention workflow variables, and send messages to trigger agent actions within canvas workflows.\n\nThe integration spans both frontend UI components and backend services, creating a bidirectional communication channel between the user interface and the agent execution engine.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph Frontend\n PC[PureCopilot Component]\n CO[Canvas Copilot]\n RCI[RichChatInput]\n ML[MentionList]\n end\n \n subgraph Hooks\n ANM[useAgentNodeManagement]\n AC[useAgentConnections]\n VM[useVariablesManagement]\n end\n \n subgraph Backend\n CS[Copilot Service]\n CAS[CopilotAutogen Service]\n end\n \n subgraph Data Layer\n CF[Context Files]\n AR[Agent Results]\n TC[Tool Calls]\n end\n \n PC --> RCI\n CO --> RCI\n RCI --> ML\n RCI --> ANM\n RCI --> AC\n RCI --> VM\n ANM --> CS\n AC --> CS\n CS --> CAS\n CAS --> CF\n CAS --> AR\n AR --> TC\n```\n\n## Core Components\n\n### PureCopilot Component\n\nThe `PureCopilot` component (`packages/ai-workspace-common/src/components/pure-copilot/index.tsx`) serves as the standalone chat interface for copilot interactions. It handles file attachments, drag-and-drop uploads, and message composition.\n\n**Key Features:**\n- File upload and management via `FileList` component\n- Drag-and-drop support with visual feedback (`handleDragEnter`, `handleDragLeave`, `handleDragOver`, `handleDrop`)\n- Context item management for attached files\n- Source-aware styling (supports `frontPage` and `onboarding` modes)\n\n**Component Props:**\n| Prop | Type | Description |\n|------|------|-------------|\n| `source` | `string` | Context source for styling: `'frontPage'` or `'onboarding'` |\n| `currentCanvasId` | `string` | Active canvas identifier |\n| `contextItems` | `ContextItem[]` | Attached files and context |\n| `relevantUploads` | `Upload[]` | Upload queue items |\n\n资料来源：[packages/ai-workspace-common/src/components/pure-copilot/index.tsx]()()\n\n### RichChatInput Component\n\nThe `RichChatInput` component (`packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx`) provides the primary input interface within canvas workflows. It extends basic chat input with advanced features like variable mentions, tool references, and OAuth integrations.\n\n**Component Interface:**\n```typescript\nexport interface RichChatInputProps {\n readonly?: boolean;\n handleSendMessage: (message: string) => void;\n onUploadImage?: (file: File) => Promise;\n onUploadMultipleImages?: (files: File[]) => Promise;\n onFocus?: () => void;\n placeholder?: string;\n mentionPosition?: MentionPosition;\n nodeId?: string;\n}\n\nexport interface RichChatInputRef {\n focus: () => void;\n insertAtSymbol?: () => void;\n}\n```\n\n**Internal State Management:**\n- `isDragging`: Tracks drag-over state for file drops\n- `isFocused`: Tracks focus state for UI styling\n- `isLogin`: Authentication state from `useUserStoreShallow`\n- `isMentionListVisible`: Controls mention dropdown visibility\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx]()()\n\n### MentionList Component\n\nThe `MentionList` component (`packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx`) provides context-aware suggestions for variables, tools, and other workflow entities during chat composition.\n\n**Mention Types:**\n| Source | Description |\n|--------|-------------|\n| `variables` | Workflow variables available in current canvas |\n| `toolset` | Available tool integrations |\n| `oauth` | OAuth-connected services |\n\n**Keyboard Navigation States:**\n```typescript\ntype FocusLevel = 'first' | 'second';\nconst [focusLevel, setFocusLevel] = useState('first');\nconst [firstLevelIndex, setFirstLevelIndex] = useState(0);\nconst [secondLevelIndex, setSecondLevelIndex] = useState(0);\n```\n\n**Height Tracking:**\nThe component tracks nested list heights for keyboard navigation:\n```typescript\nconst [firstLevelHeight, setFirstLevelHeight] = useState(0);\nconst [secondLevelHeight, setSecondLevelHeight] = useState(0);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx]()()\n\n## Context Management System\n\n### ContextFile Model\n\nThe copilot system uses structured context files to manage files and data passed to agents:\n\n```typescript\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 * Metadata-only version of ContextFile (without content)\n * Used in ContextBlock to reduce token usage - LLM should use read_file to get full content\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### Agent Results\n\nAgent execution produces structured results:\n\n```typescript\nexport interface AgentResult {\n resultId: string;\n title: string;\n content: string;\n outputFiles: ContextFileMeta[];\n}\n```\n\n### Tool Call Metadata\n\nTool calls within agent results are tracked for retrieval:\n\n```typescript\nexport interface ToolCallMeta {\n callId: string;\n toolName: string;\n}\n```\n\n资料来源：[packages/skill-template/src/scheduler/utils/context.ts]()()\n\n## Backend Services\n\n### Copilot Service\n\nThe backend copilot service handles message processing, agent dispatch, and response streaming.\n\n**Service Location:** `apps/api/src/modules/copilot/copilot.service.ts`\n\n### Copilot Autogen Service\n\nThe `CopilotAutogen` service (`apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts`) manages automatic skill generation and agent orchestration.\n\n**Key Responsibilities:**\n- Generate skills based on user intent\n- Manage skill lifecycle (create, update, delete)\n- Handle skill installation to Claude Code environments\n\n**Skill Installation Path:**\n```\n~/.claude/skills/refly/SKILL.md\n~/.claude/skills/refly/references/\n~/.claude/commands/refly-*.md\n```\n\n资料来源：[apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts]()()\n资料来源：[packages/cli/README.md]()()\n\n## Integration Hooks\n\n### useAgentNodeManagement\n\nManages the agent node state and message handling for a specific node:\n\n```typescript\nconst { query, setQuery, setContextItems, setSelectedToolsets } =\n useAgentNodeManagement(nodeId);\n```\n\n### useAgentConnections\n\nManages connections between agents:\n\n```typescript\nconst { connectToUpstreamAgent } = useAgentConnections();\n```\n\n### useVariablesManagement\n\nManages workflow variables for the current canvas:\n\n```typescript\nconst { data: workflowVariables } = useVariablesManagement(canvasId);\n```\n\n### useVariableView\n\nProvides variable viewing functionality:\n\n```typescript\nconst { handleVariableView } = useVariableView(canvasId);\n```\n\n资料来源：[packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx]()()\n\n## User Interaction Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant RCI as RichChatInput\n participant ML as MentionList\n participant ANM as useAgentNodeManagement\n participant CS as Copilot Service\n \n User->>RCI: Type message\n RCI->>ML: Check for @ trigger\n ML-->>RCI: Show suggestion dropdown\n User->>ML: Select mention\n ML-->>RCI: Insert mention into query\n User->>RCI: Send message\n RCI->>ANM: handleSendMessage(query)\n ANM->>CS: Process message\n CS-->>ANM: Agent result\n ANM-->>RCI: Update state\n RCI-->>User: Display result\n```\n\n## Configuration Options\n\n### ChatInput Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `readonly` | `boolean` | `false` | Disable input |\n| `autoFocus` | `boolean` | `false` | Focus on mount |\n| `minRows` | `number` | `2` | Minimum input height |\n| `inputClassName` | `string` | - | Custom input styling |\n| `placeholder` | `string` | i18n key | Placeholder text |\n\n### Mention Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placement` | `'bottom'` / `'bottom-start'` | `'bottom-start'` | Dropdown position |\n| `query` | `string` | `''` | Current mention query |\n| `isPolling` | `boolean` | `false` | Enable polling mode |\n| `isOpening` | `boolean` | `false` | Handle OAuth popup |\n\n## Styling and Theming\n\nThe copilot components use CSS custom properties for theming:\n\n```css\n/* Primary copilot styling */\n.pure-copilot-glow-effect {\n box-shadow: var(--copilot-glow-color);\n}\n\n/* Input area */\n.bg-refly-bg-content-z2 {\n background-color: var(--refly-bg-content);\n}\n\n/* Text hierarchy */\n.text-refly-text-0 { color: var(--refly-text-primary); }\n.text-refly-text-1 { color: var(--refly-text-secondary); }\n```\n\n### Source-Specific Styling\n\n```typescript\nclassName={cn(\n 'w-full px-4 py-3 rounded-[12px] border-[1px] border-solid bg-refly-bg-content-z2 transition-all duration-300 relative z-20',\n source === 'frontPage'\n ? cn('border-refly-primary-default my-2')\n : 'border-transparent pure-copilot-glow-effect',\n)}\n```\n\n## Internationalization\n\nThe copilot interface supports i18n with namespace-based translations:\n\n| Namespace | Usage |\n|-----------|-------|\n| `copilot` | Main copilot UI strings |\n| `skillLog` | Skill execution logs |\n| `common` | Shared strings |\n\n**Example Translation Keys:**\n```typescript\nt('copilot.greeting.title')\nt('copilot.pureCopilotPlaceholder')\nt('skillLog.error.title')\n```\n\n## Error Handling\n\n### File Upload Errors\n\nFiles can fail upload with retry capability:\n\n```typescript\nconst { onRemove, onRetry } = useFileUpload({\n uploads: relevantUploads,\n canvasId: currentCanvasId,\n});\n```\n\n### OAuth Popup Handling\n\nThe mention list supports OAuth integration:\n\n```typescript\nopenOAuthPopup?: (toolsetKey: string) => Promise;\n```\n\n## Related Documentation\n\n- [Canvas Integration](canvas-integration) - Workflow canvas features\n- [Skills System](skills-system) - Agent skill management\n- [API Documentation](api-reference) - Backend service APIs\n- [CLI Integration](cli-integration) - Claude Code skill installation\n\n---\n\n\n\n## API Modules\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Authentication and Authorization](#authentication)\n\n
\nRelated Source Files\n\nThe following source files were referenced for generating this documentation:\n\n- [apps/api/src/modules/tool/tool.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/tool/tool.service.ts)\n- [apps/api/src/modules/tool/ptc/tool-execution.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/tool/ptc/tool-execution.service.ts)\n- [apps/api/src/modules/webhook/webhook.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/webhook/webhook.service.ts)\n- [apps/api/src/modules/openapi/openapi.service.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/openapi/openapi.service.ts)\n\n**Note:** The source files listed above were not available in the context retrieved for this analysis. The following documentation is based on the available context files that reference API module functionality, including UI components and integration documentation.\n\n
\n\n# API Modules\n\nThe Refly API Modules form the backend service layer that handles tool execution, webhook integration, OpenAPI specification management, and skill orchestration. These modules operate within the `apps/api/src/modules/` directory and expose functionality through REST endpoints consumed by the frontend workspace components.\n\n## Overview\n\nThe API modules provide a structured backend architecture for the Refly platform's core capabilities:\n\n| Module | Purpose | Key Files |\n|--------|---------|-----------|\n| **Tool** | Tool registration, management, and execution | `tool.service.ts`, `tool-execution.service.ts` |\n| **Webhook** | Webhook configuration and event delivery | `webhook.service.ts` |\n| **OpenAPI** | OpenAPI specification handling and integration | `openapi.service.ts` |\n| **Skill** | Skill registry and lifecycle management | `skill.service.ts` |\n\n## Tool Module\n\nThe Tool module manages the lifecycle of tools and tool execution within the Refly workspace. Tools are reusable components that can be invoked by agents during workflow execution.\n\n### Tool Service\n\nThe `ToolService` handles tool registration, retrieval, and metadata management. Tools in Refly can belong to toolsets, which group related functionality together.\n\n### Tool Execution Service (PTC)\n\nThe Prompt-Tool-Calling (PTC) execution service manages the runtime execution of tools during agent reasoning. This service:\n\n- Coordinates tool invocation based on agent decisions\n- Manages input/output schemas for tools\n- Handles tool result serialization and context injection\n\n## Webhook Module\n\nThe Webhook module enables event-driven integrations by allowing external services to receive notifications when specific events occur in Refly workflows.\n\n### Webhook Configuration\n\nWebhook configuration includes:\n\n- **Endpoint URL**: The target URL for webhook delivery\n- **Event Types**: Specific events to subscribe to\n- **Authentication**: Headers and secrets for security\n- **Retry Policy**: Configuration for failed delivery attempts\n\n### Webhook Event Delivery\n\n```mermaid\ngraph TD\n A[Workflow Event] --> B[WebhookService]\n B --> C{Event Type Match?}\n C -->|Yes| D[Prepare Payload]\n C -->|No| E[Skip Delivery]\n D --> F{HTTP POST}\n F --> G{Response 2xx?}\n G -->|Success| H[Log Success]\n G -->|Failure| I{Retry Count?}\n I -->|< Max| J[Retry with Backoff]\n J --> F\n I -->|>= Max| K[Mark Failed]\n```\n\n### Webhook Error Codes\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `WEBHOOK_DELIVERY_FAILED` | 500 | Failed to deliver webhook |\n| `WEBHOOK_TIMEOUT` | 504 | Request timed out |\n| `WEBHOOK_INVALID_URL` | 400 | URL format invalid |\n| `WEBHOOK_AUTH_FAILED` | 401 | Authentication failed |\n\n## OpenAPI Module\n\nThe OpenAPI module provides integration with OpenAPI specifications, enabling Refly to:\n\n- Parse and validate OpenAPI documents\n- Generate tool definitions from specifications\n- Support API schema introspection\n\n### Request Body Schema\n\nOpenAPI integration follows standard OpenAPI 3.x conventions for request body definitions:\n\n```typescript\ninterface RequestBodySchema {\n description?: string;\n descriptionKey?: string; // i18n key for localization\n required?: boolean;\n schema: {\n type: string;\n properties: Record;\n };\n}\n```\n\n## Integration with Frontend Components\n\nThe API modules communicate with frontend components through:\n\n1. **Context Files** (`packages/skill-template/src/scheduler/utils/context.ts`): Define data structures for tool and result metadata\n2. **UI Components**: Consume API responses for display in the workspace interface\n\n### Data Flow\n\n```mermaid\ngraph LR\n A[Frontend UI] -->|API Request| B[API Module]\n B --> C[Service Logic]\n C --> D[External Service/Tool]\n D --> E[Response]\n C --> F[Context Metadata]\n F --> G[Frontend Render]\n```\n\n## Module Configuration\n\nAPI modules are configured through:\n\n| Configuration | Location | Description |\n|---------------|----------|-------------|\n| API Endpoint | `~/.refly/config.json` | Base URL for API calls |\n| API Key | Environment `REFLY_API_KEY` | Authentication token |\n| Module-specific | Per-module configuration | Varies by module |\n\n## Skill Module Integration\n\nSkills extend the API module functionality by providing pre-built integrations. The skill system references external skill repositories at `https://github.com/refly-ai/refly-skills` for community-contributed tools and workflows.\n\n## Error Handling\n\nStandard error codes returned by API modules:\n\n| Code | Module | Description |\n|------|--------|-------------|\n| `AUTH_REQUIRED` | All | Authentication required |\n| `TOOL_NOT_FOUND` | Tool | Requested tool does not exist |\n| `WEBHOOK_NOT_CONFIGURED` | Webhook | Webhook endpoint not set |\n| `OPENAPI_INVALID_SPEC` | OpenAPI | Invalid OpenAPI specification |\n| `SKILL_NOT_INSTALLED` | Skill | Requested skill not found |\n\n---\n\n\n\n## Authentication and Authorization\n\n### 相关页面\n\n相关主题：[API Modules](#api-modules)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/commands/login.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/commands/login.ts)\n- [packages/cli/src/api/client.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/api/client.ts)\n- [packages/cli/src/commands/status.ts](https://github.com/refly-ai/refly/blob/main/packages/cli/src/commands/status.ts)\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- [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- [apps/api/src/modules/config/app.config.ts](https://github.com/refly-ai/refly/blob/main/apps/api/src/modules/config/app.config.ts)\n- [packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n
\n\n# Authentication and Authorization\n\n## Overview\n\nThe Refly platform implements a comprehensive authentication and authorization system that supports multiple authentication methods across both CLI and web interfaces. The system provides secure access control through OAuth 2.0 flows, API key authentication, and email/password credentials.\n\n## Architecture Overview\n\nThe authentication system is designed with two primary entry points:\n\n- **CLI Authentication**: Device-based OAuth authorization with optional API key authentication\n- **Web Authentication**: OAuth providers (GitHub, Google) combined with email/password registration and login\n\n```mermaid\ngraph TD\n subgraph \"CLI Authentication\"\n CLI[refly CLI] --> LOGIN[refly login]\n LOGIN --> DEVICE[Device Authorization]\n DEVICE --> POLL[Polling for Auth]\n POLL --> SUCCESS{Authorized?}\n SUCCESS -->|Yes| TOKEN[Access Token]\n SUCCESS -->|No| POLL\n end\n \n subgraph \"Web Authentication\"\n WEB[Web App] --> OAUTH[OAuth Providers]\n WEB --> EMAIL[Email/Password]\n OAUTH --> GH[GitHub]\n OAUTH --> GGL[Google]\n end\n \n subgraph \"API Layer\"\n TOKEN --> API[API Request]\n API --> GUARD[Auth Guard]\n APIKEY[API Key] --> GUARD\n end\n```\n\n## CLI Authentication\n\n### Device Authorization Flow\n\nThe CLI implements a device authorization flow for OAuth authentication. When a user runs `refly login`, the CLI initiates a device authorization request and displays a verification URL for the user to complete authentication in a browser.\n\n**Flow Steps:**\n\n1. CLI generates a unique device ID\n2. CLI polls the authorization server at regular intervals (2 seconds)\n3. User completes authorization in browser\n4. CLI receives access token upon successful authorization\n\n```mermaid\nsequenceDiagram\n participant CLI\n participant Browser\n participant Server\n \n CLI->>Server: Request device code\n Server-->>CLI: Device code, user code, verification URL\n CLI->>Browser: Open verification URL\n CLI->>Server: Poll for authorization status\n Browser->>Server: User authenticates\n Server-->>CLI: Authorization granted\n CLI->>Server: Exchange for access token\n Server-->>CLI: Access token + refresh token\n```\n\n**Key Implementation Details:**\n\n| Parameter | Purpose |\n|-----------|---------|\n| `device_id` | Unique identifier for the device session |\n| `cli_version` | CLI version for server-side validation |\n| `host` | Hostname for session tracking |\n| `pollInterval` | 2000ms polling interval |\n\n资料来源：[packages/cli/src/commands/login.ts:1-100]()\n\n### API Key Authentication\n\nFor programmatic access, the CLI supports API key authentication. Users can authenticate by setting their API key through environment variables or configuration files.\n\n**Environment Variable:**\n```\nREFLY_API_KEY=\n```\n\n**Configuration File:** `~/.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资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n### Token Management\n\nThe CLI manages OAuth tokens with automatic refresh capability. When an access token expires, the system automatically attempts to refresh it before making API requests.\n\n**Token Storage Components:**\n\n| Field | Description |\n|-------|-------------|\n| `accessToken` | Current OAuth access token |\n| `refreshToken` | Token for refreshing expired access tokens |\n| `expiresAt` | Expiration timestamp for the access token |\n\n**Refresh Logic:**\n\n```typescript\nif (expiresAt && new Date(expiresAt) < new Date()) {\n logger.debug('Access token expired, refreshing...');\n try {\n accessToken = await refreshAccessToken();\n } catch (error) {\n throw new AuthError('Session expired, please login again');\n }\n}\n```\n\n资料来源：[packages/cli/src/api/client.ts:1-80]()\n\n### CLI Status Command\n\nThe `refly status` command provides comprehensive authentication status information including:\n\n| Field | Description |\n|-------|-------------|\n| `cli_version` | Installed CLI version |\n| `config_dir` | Configuration directory path |\n| `api_endpoint` | API endpoint URL |\n| `auth_status` | Authentication status (`valid`, `expired`, `invalid`) |\n| `auth_method` | Authentication method used (`oauth`, `apikey`) |\n| `auth_details` | Provider or API key information |\n| `user` | Authenticated user object |\n| `skill` | Skill installation status |\n\n资料来源：[packages/cli/src/commands/status.ts:1-90]()\n\n## Web Authentication\n\n### Supported Authentication Methods\n\nThe web interface supports multiple authentication providers configured at the server level:\n\n| Provider | Type | Description |\n|----------|------|-------------|\n| GitHub | OAuth 2.0 | GitHub OAuth application integration |\n| Google | OAuth 2.0 | Google OAuth integration |\n| Email | Password | Email/password credentials with validation |\n\n**Fallback Behavior:** Email authentication is always enabled as a fallback, regardless of server configuration.\n\n资料来源：[packages/web-core/src/pages/login/index.tsx:1-80]()\n\n### OAuth Flow Implementation\n\n```mermaid\ngraph LR\n A[Login Page] --> B{Check Provider Enabled}\n B -->|GitHub| C[GitHub OAuth]\n B -->|Google| D[Google OAuth]\n B -->|Email| E[Email Form]\n C --> F[Redirect to /v1/auth/provider]\n D --> F\n E --> G[Form Validation]\n G --> H[Email Signup/Login API]\n```\n\n**OAuth URL Construction:**\n\n```typescript\nwindow.location.href = `${serverOrigin}/v1/auth/${provider}`;\n```\n\n**Login Handler:**\n\n```typescript\nconst handleLogin = useCallback((provider: 'github' | 'google') => {\n logEvent('auth::oauth_login_click', provider);\n authStore.setLoginInProgress(true);\n authStore.setLoginProvider(provider);\n storePendingRedirect();\n window.location.href = `${serverOrigin}/v1/auth/${provider}`;\n}, [authStore]);\n```\n\n资料来源：[packages/web-core/src/pages/login/index.tsx:80-120]()\n\n### Email/Password Authentication\n\nEmail authentication includes comprehensive validation rules:\n\n| Rule | Condition | Error Message |\n|------|-----------|---------------|\n| Required | Field is empty | Field is required |\n| Email Format | Invalid email format | Invalid email address |\n| Password Required | Empty password | Password is required |\n| Password Min Length | Less than 8 characters | Password must be at least 8 characters |\n| Password Confirmation | Does not match | Passwords do not match |\n\n**Password Validation Implementation:**\n\n```typescript\nrules={[\n {\n required: true,\n message: t('verifyRules.passwordRequired'),\n },\n ...(authStore.isSignUpMode\n ? [\n {\n min: 8,\n message: t('verifyRules.passwordMin'),\n },\n ]\n : []),\n]}\n```\n\n资料来源：[packages/web-core/src/components/login-modal/login-content.tsx:1-100]()\n\n### Authentication State Management\n\nThe authentication system maintains state through an auth store that tracks:\n\n| State Property | Type | Description |\n|----------------|------|-------------|\n| `loginInProgress` | boolean | Authentication request in progress |\n| `loginProvider` | string | Currently authenticating provider |\n| `isSignUpMode` | boolean | Toggle between sign-in and sign-up forms |\n\n**Email Signup Request:**\n\n```typescript\nconst { data } = await getClient().emailSignup({\n body: {\n email: values.email,\n password: values.password,\n },\n});\n```\n\n资料来源：[packages/web-core/src/pages/login/index.tsx:120-180]()\n\n## Server-Side Configuration\n\n### Application Auth Config\n\nThe API server provides configurable authentication options through environment variables:\n\n| Environment Variable | Type | Default | Description |\n|---------------------|------|---------|-------------|\n| `AUTH_REQUIRE_INVITATION_CODE` | boolean | false | Require invitation code for registration |\n| `INVITATION_MAX_CODES_PER_USER` | number | 20 | Max invitation codes per user |\n| `INVITATION_INVITER_CREDIT_AMOUNT` | number | 500 | Credits awarded to inviter |\n| `INVITATION_INVITEE_CREDIT_AMOUNT` | number | 500 | Credits awarded to invitee |\n| `REGISTRATION_BONUS_CREDIT_AMOUNT` | number | 500 | New user registration bonus |\n\n资料来源：[apps/api/src/modules/config/app.config.ts:1-50]()\n\n### OAuth Provider Configuration\n\nOAuth providers are configured with client credentials:\n\n```typescript\ntwitter: {\n enabled: process.env.TWITTER_AUTH_ENABLED === 'true' || false,\n clientId: process.env.TWITTER_CLIENT_ID || 'test',\n clientSecret: process.env.TWITTER_CLIENT_SECRET || 'test',\n callbackUrl: process.env.TWITTER_CALLBACK_URL || 'test',\n},\nnotion: {\n enabled: process.env.NOTION_AUTH_ENABLED === 'true' || false,\n clientId: process.env.NOTION_CLIENT_ID || 'test',\n clientSecret: process.env.NOTION_CLIENT_SECRET || 'test',\n callbackUrl: process.env.NOTION_CALLBACK_URL || 'test',\n},\n```\n\n资料来源：[apps/api/src/modules/config/app.config.ts:50-80]()\n\n## Authentication Methods Summary\n\n| Method | Use Case | Token Storage | Refresh |\n|--------|----------|---------------|---------|\n| OAuth (CLI Device) | Interactive CLI login | config.json | Automatic |\n| OAuth (Web) | Web application login | HTTP-only cookies | Automatic |\n| API Key | Scripting/CI-CD | Environment/config | N/A |\n| Email/Password | Web registration | HTTP-only cookies | Automatic |\n\n## Error Handling\n\n### CLI Error Codes\n\n| Code | Description | Hint |\n|------|-------------|------|\n| `AUTH_REQUIRED` | Not authenticated | refly login |\n| `INVALID_CREDENTIALS` | Invalid login | Check credentials |\n| `SESSION_EXPIRED` | Token expired | Run refly login again |\n\n### Web Error Handling\n\nThe web interface implements form validation with user-friendly error messages and loading states:\n\n```typescript\nconst handleEmailAuth = useCallback(async () => {\n let values: FormValues;\n try {\n values = await form.validateFields();\n } catch (error) {\n console.error('Error validating form fields', error);\n return;\n }\n \n authStore.setLoginProvider('email');\n authStore.setLoginInProgress(true);\n // ... authentication logic\n}, []);\n```\n\n## Best Practices\n\n1. **CLI Authentication**: Use `refly login` for interactive sessions; use API keys for automated workflows\n2. **Token Refresh**: The CLI automatically handles token refresh; ensure network connectivity for re-authentication\n3. **Security**: Never commit API keys to version control; use environment variables\n4. **Session Management**: Use `refly logout` to clear stored credentials when done\n\n## Related Commands\n\n```bash\nrefly login # Authenticate with OAuth or API key\nrefly logout # Remove stored credentials\nrefly status # Check authentication status\nrefly whoami # Display current user information\n```\n\n资料来源：[packages/cli/README.md](https://github.com/refly-ai/refly/blob/main/packages/cli/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：refly-ai/refly\n\n摘要：发现 21 个潜在踩坑项，其中 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_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：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## 12. 安全/权限坑 · 来源证据：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## 13. 安全/权限坑 · 来源证据：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## 14. 安全/权限坑 · 来源证据：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## 15. 安全/权限坑 · 来源证据：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## 16. 安全/权限坑 · 来源证据：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## 17. 安全/权限坑 · 来源证据：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## 18. 安全/权限坑 · 来源证据：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## 19. 安全/权限坑 · 来源证据：🤖 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## 20. 维护坑 · 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## 21. 维护坑 · 发布节奏不明确\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摘要：发现 21 个潜在踩坑项，其中 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_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：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## 12. 安全/权限坑 · 来源证据：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## 13. 安全/权限坑 · 来源证据：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## 14. 安全/权限坑 · 来源证据：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## 15. 安全/权限坑 · 来源证据：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## 16. 安全/权限坑 · 来源证据：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## 17. 安全/权限坑 · 来源证据：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## 18. 安全/权限坑 · 来源证据：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## 19. 安全/权限坑 · 来源证据：🤖 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## 20. 维护坑 · 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## 21. 维护坑 · 发布节奏不明确\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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for refly-ai/refly.\n\nProject:\n- Name: refly\n- Repository: https://github.com/refly-ai/refly\n- Summary: 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.\n- Host target: claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 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.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. project-introduction: Project Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. quick-start-guide: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. workflow-engine: Workflow Engine. Produce one small intermediate artifact and wait for confirmation.\n5. skill-management: Skill Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- packages/skill-template/src/base.ts\n- docs/community-version/self-deploy/index.md\n- packages/cli/src/commands/workflow/index.ts\n- apps/api/src/app.module.ts\n- apps/api/src/main.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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" }