{ "canonical_name": "microsoft/magentic-ui", "compilation_id": "pack_f634e1649f0b4cfebedac89c84159484", "created_at": "2026-05-19T12:11:31.919710+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 `pip install magentic-ui` 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": "pip install magentic-ui", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_cdc662fd813443d3a2587e4e7300f97f" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_84171691db23a3d14db7f72565c5f863", "canonical_name": "microsoft/magentic-ui", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/microsoft/magentic-ui", "slug": "magentic-ui", "source_packet_id": "phit_d663dfedde334fb69f4f57cc96742549", "source_validation_id": "dval_36857acfbba94767984ed9af003c2ae8" }, "merchandising": { "best_for": "需要信息检索与知识管理能力，并使用 local_cli的用户", "github_forks": 978, "github_stars": 9810, "one_liner_en": "A research prototype of a human-centered web agent", "one_liner_zh": "A research prototype of a human-centered web agent", "primary_category": { "category_id": "research-knowledge", "confidence": "medium", "name_en": "Research & Knowledge", "name_zh": "信息检索与知识管理", "reason": "matched_keywords:research, search" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "magentic-ui", "title_zh": "magentic-ui 能力包", "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": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_d663dfedde334fb69f4f57cc96742549", "page_model": { "artifacts": { "artifact_slug": "magentic-ui", "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": "pip install magentic-ui", "label": "Python / pip · 官方安装入口", "source": "https://github.com/microsoft/magentic-ui#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "评测体系" ], "eyebrow": "信息检索与知识管理", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要信息检索与知识管理能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "A research prototype of a human-centered web agent" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "local_cli", "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 社区证据显示该项目存在一个安装相关的待验证问题：Create tutorials and documentation for the codebase", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_c0979f7ebb064422a6a8095561f6a9bd | https://github.com/microsoft/magentic-ui/issues/154 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Create tutorials and documentation for the codebase", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support Podman in place of Docker", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_f88231cc4cad442ca53d92ea3a40a655 | https://github.com/microsoft/magentic-ui/issues/312 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Support Podman in place of Docker", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：magentic-ui can't display all the html element", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_21f19953edd74379ab2d25cedc37ca1b | https://github.com/microsoft/magentic-ui/issues/362 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：magentic-ui can't display all the html element", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Refreshing or restart the web app will make the current Session unavailable", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_83a9cafd59254028853ef84cd1ccc756 | https://github.com/microsoft/magentic-ui/issues/336 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Refreshing or restart the web app will make the current Session unavailable", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:978331188 | https://github.com/microsoft/magentic-ui | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Why not conduct a requirement analysis before the plan?", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_6003a9c2194f40c0865145385cf98c32 | https://github.com/microsoft/magentic-ui/issues/321 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Why not conduct a requirement analysis before the plan?", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Sticked at click the “Shopping Cart” icon and cannot goto check out page", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_7e754869326e42e1a7c57f3a1962ef9e | https://github.com/microsoft/magentic-ui/issues/360 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Sticked at click the “Shopping Cart” icon and cannot goto check out page", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:978331188 | https://github.com/microsoft/magentic-ui | 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:978331188 | https://github.com/microsoft/magentic-ui | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:978331188 | https://github.com/microsoft/magentic-ui | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Settings redesign", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_6a2eeae98b6d4fdab476464d57e64e1d | https://github.com/microsoft/magentic-ui/issues/227 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Settings redesign", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:978331188 | https://github.com/microsoft/magentic-ui | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:978331188 | https://github.com/microsoft/magentic-ui | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Create tutorials and documentation for the codebase。", "title": "踩坑日志" }, "snapshot": { "contributors": 30, "forks": 978, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 9810 }, "source_url": "https://github.com/microsoft/magentic-ui", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "A research prototype of a human-centered web agent", "title": "magentic-ui 能力包", "trial_prompt": "# magentic-ui - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 magentic-ui 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: A research prototype of a human-centered web agent 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. agent-system：代理系统详解。围绕“代理系统详解”模拟一次用户任务，不展示安装或运行结果。\n5. frontend-components：前端组件结构。围绕“前端组件结构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-system\n输入：用户提供的“代理系统详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. frontend-components\n输入：用户提供的“前端组件结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-system：Step 4 必须围绕“代理系统详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / frontend-components：Step 5 必须围绕“前端组件结构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/microsoft/magentic-ui\n- https://github.com/microsoft/magentic-ui#readme\n- README.md\n- TRANSPARENCY_NOTE.md\n- src/magentic_ui/__init__.py\n- TROUBLESHOOTING.md\n- pyproject.toml\n- src/magentic_ui/backend/web/app.py\n- src/magentic_ui/backend/teammanager/teammanager.py\n- src/magentic_ui/task_team.py\n- src/magentic_ui/_docker.py\n- src/magentic_ui/agents/web_surfer/_web_surfer.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 magentic-ui 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Create tutorials and documentation for the codebase（https://github.com/microsoft/magentic-ui/issues/154）；github/github_issue: Settings redesign（https://github.com/microsoft/magentic-ui/issues/227）；github/github_issue: Support Podman in place of Docker（https://github.com/microsoft/magentic-ui/issues/312）；github/github_issue: Why not conduct a requirement analysis before the plan?（https://github.com/microsoft/magentic-ui/issues/321）；github/github_issue: Refreshing or restart the web app will make the current Session unavaila（https://github.com/microsoft/magentic-ui/issues/336）；github/github_issue: Sticked at click the “Shopping Cart” icon and cannot goto check out page（https://github.com/microsoft/magentic-ui/issues/360）；github/github_issue: magentic-ui can't display all the html element（https://github.com/microsoft/magentic-ui/issues/362）；github/github_release: Magentic-UI 0.1.5: \"Tell Me When\" tasks enabled by SentinelSteps（https://github.com/microsoft/magentic-ui/releases/tag/0.1.5）；github/github_release: Magentic-UI 0.1.2（https://github.com/microsoft/magentic-ui/releases/tag/v0.1.2）；github/github_release: Magentic-UI 0.1.1（https://github.com/microsoft/magentic-ui/releases/tag/v0.1.1）；github/github_release: Magentic-UI 0.1.0（https://github.com/microsoft/magentic-ui/releases/tag/v0.1.0）；github/github_release: Magentic-UI v0.0.6（https://github.com/microsoft/magentic-ui/releases/tag/v0.0.6）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Create tutorials and documentation for the codebase", "url": "https://github.com/microsoft/magentic-ui/issues/154" }, { "kind": "github_issue", "source": "github", "title": "Settings redesign", "url": "https://github.com/microsoft/magentic-ui/issues/227" }, { "kind": "github_issue", "source": "github", "title": "Support Podman in place of Docker", "url": "https://github.com/microsoft/magentic-ui/issues/312" }, { "kind": "github_issue", "source": "github", "title": "Why not conduct a requirement analysis before the plan?", "url": "https://github.com/microsoft/magentic-ui/issues/321" }, { "kind": "github_issue", "source": "github", "title": "Refreshing or restart the web app will make the current Session unavaila", "url": "https://github.com/microsoft/magentic-ui/issues/336" }, { "kind": "github_issue", "source": "github", "title": "Sticked at click the “Shopping Cart” icon and cannot goto check out page", "url": "https://github.com/microsoft/magentic-ui/issues/360" }, { "kind": "github_issue", "source": "github", "title": "magentic-ui can't display all the html element", "url": "https://github.com/microsoft/magentic-ui/issues/362" }, { "kind": "github_release", "source": "github", "title": "Magentic-UI 0.1.5: \"Tell Me When\" tasks enabled by SentinelSteps", "url": "https://github.com/microsoft/magentic-ui/releases/tag/0.1.5" }, { "kind": "github_release", "source": "github", "title": "Magentic-UI 0.1.2", "url": "https://github.com/microsoft/magentic-ui/releases/tag/v0.1.2" }, { "kind": "github_release", "source": "github", "title": "Magentic-UI 0.1.1", "url": "https://github.com/microsoft/magentic-ui/releases/tag/v0.1.1" }, { "kind": "github_release", "source": "github", "title": "Magentic-UI 0.1.0", "url": "https://github.com/microsoft/magentic-ui/releases/tag/v0.1.0" }, { "kind": "github_release", "source": "github", "title": "Magentic-UI v0.0.6", "url": "https://github.com/microsoft/magentic-ui/releases/tag/v0.0.6" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "信息检索与知识管理", "desc": "A research prototype of a human-centered web agent", "effort": "安装已验证", "forks": 978, "icon": "search", "name": "magentic-ui 能力包", "risk": "可发布", "slug": "magentic-ui", "stars": 9810, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "评测体系" ], "thumb": "blue", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/microsoft/magentic-ui 项目说明书\n\n生成时间：2026-05-17 13:28:54 UTC\n\n## 目录\n\n- [项目概述](#overview)\n- [快速开始指南](#quick-start)\n- [系统架构](#system-architecture)\n- [代理系统详解](#agent-system)\n- [前端组件结构](#frontend-components)\n- [设置与配置管理](#settings-management)\n- [后端API架构](#backend-api)\n- [WebSocket实时通信](#websocket-communication)\n- [数据管理](#data-management)\n- [浏览器自动化引擎](#browser-automation)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [快速开始指南](#quick-start)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [frontend/src/components/layout.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n- [frontend/src/components/views/chat/runview.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/runview.tsx)\n- [frontend/src/components/features/Plans/PlanCard.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanCard.tsx)\n- [frontend/src/components/features/Plans/PlanList.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanList.tsx)\n- [frontend/src/components/views/chat/progressbar.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/progressbar.tsx)\n- [frontend/src/components/views/chat/detail_viewer.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/detail_viewer.tsx)\n- [frontend/src/components/views/chat/chat.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/chat.tsx)\n- [src/magentic_ui/agents/web_surfer/fara/_prompts.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/agents/web_surfer/fara/_prompts.py)\n
\n\n# 项目概述\n\n## 简介\n\nMagentic-UI 是一个由微软开发的多模态 AI 代理框架，旨在通过自然语言界面实现复杂的自动化任务。该项目将大型语言模型（LLM）的推理能力与浏览器自动化工具相结合，使用户能够通过对话方式控制浏览器、执行搜索、操作网页等任务。系统核心强调**透明性**——用户可以实时监控 AI 的工作过程并在必要时进行干预。资料来源：[frontend/src/components/layout.tsx:1-40]()\n\nMagentic-UI 的主要目标是降低自动化复杂网页操作的门槛，同时确保人类始终保持对 AI 行为的最终控制权。该框架适用于需要执行多步骤网页交互、数据采集、表单填写、跨网站信息整合等场景。\n\n## 核心架构\n\n### 技术栈概览\n\n| 层级 | 技术 | 说明 |\n|------|------|------|\n| 前端框架 | React + TypeScript | 构建交互式用户界面 |\n| UI 组件库 | Ant Design | 提供标准化的 UI 组件 |\n| 样式方案 | Tailwind CSS | 原子化 CSS 框架 |\n| 后端核心 | Python | 处理 LLM 推理和代理逻辑 |\n| 浏览器自动化 | Playwright / noVNC | 浏览器控制和远程显示 |\n| 通信协议 | SSE / Stdio / JSON | 与 MCP 服务器通信 |\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx:1-80]()\n\n### 模块划分\n\nMagentic-UI 的代码库按照功能可分为以下主要模块：\n\n```mermaid\ngraph TD\n A[Magentic-UI 系统] --> B[前端模块 frontend/]\n A --> C[后端模块 src/magentic_ui/]\n \n B --> B1[视图层 views/]\n B --> B2[功能层 features/]\n B --> B3[布局层 layout.tsx]\n \n B1 --> B1a[Chat 聊天视图]\n B1 --> B1b[RunView 运行视图]\n B1 --> B1c[ProgressBar 进度条]\n B1 --> B1d[DetailViewer 详情查看器]\n \n B2 --> B2a[Plans 计划管理]\n B2 --> B2b[McpServersConfig MCP服务器配置]\n \n C --> C1[agents/ 代理模块]\n C --> C2[web_surfer/ 网络冲浪代理]\n```\n\n资料来源：[frontend/src/components/views/chat/chat.tsx:1-100]()\n\n## 关键功能模块\n\n### 会话管理与运行状态\n\n系统采用会话（Session）驱动的执行模型。每个会话关联一个运行实例（Run），运行实例具有以下状态：\n\n| 状态 | 描述 | 用户操作 |\n|------|------|----------|\n| `active` | 运行中 | 可暂停 |\n| `paused` | 已暂停 | 可恢复 |\n| `pausing` | 正在暂停 | 等待完成当前步骤 |\n| `awaiting_input` | 等待用户输入 | 需要用户响应 |\n| `completed` | 已完成 | 可查看结果 |\n\n资料来源：[frontend/src/components/views/chat/chat.tsx:30-50]()\n\n```mermaid\nstateDiagram-v2\n [*] --> active : 开始运行\n active --> paused : 用户暂停\n active --> awaiting_input : 需要输入\n active --> [*] : 完成\n paused --> active : 恢复运行\n awaiting_input --> active : 用户提供输入\n pausing --> paused : 暂停完成\n```\n\n### 计划（Plan）系统\n\n计划系统是 Magentic-UI 的核心功能之一，允许用户创建、保存、复用自动化流程。一个计划由以下要素组成：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 计划唯一标识符 |\n| `task` | string | 计划标题/任务描述 |\n| `steps` | Step[] | 步骤数组 |\n| `created_at` | datetime | 创建时间 |\n\n计划步骤包含标题、详细描述、关联的代理等信息。资料来源：[frontend/src/components/features/Plans/PlanCard.tsx:1-100]()\n\n```mermaid\ngraph LR\n A[创建计划] --> B[编辑步骤]\n B --> C[保存计划]\n C --> D[附加到查询]\n D --> E[执行计划]\n E --> F[监控进度]\n F --> G{完成?}\n G -->|是| H[学习新计划]\n G -->|否| F\n```\n\n### 计划学习功能\n\n系统提供从对话历史中学习并生成可复用计划的能力：\n\n- **触发时机**：当用户完成一个复杂任务后，可点击\"Learn Plan\"按钮\n- **生成逻辑**：分析对话历史中的步骤序列，提取为结构化计划\n- **保存位置**：保存到用户的计划库（Plan Library）中\n- **复用方式**：用户可在新会话中附加已保存的计划\n\n资料来源：[frontend/src/components/features/Plans/LearnPlanButton.tsx:1-60]()\n\n### 进度可视化\n\n系统在执行计划时提供实时进度展示：\n\n```mermaid\ngraph TD\n A[ProgressBar] --> B[计算当前步骤]\n A --> C[显示步骤标记]\n A --> D[显示状态文本]\n \n B --> E{有最终答案?}\n E -->|是| F[显示Task Completed]\n E -->|否| G[显示Step X of Y]\n \n C --> H[工具提示含详细信息]\n D --> I[包含步骤标题]\n```\n\n进度条组件会显示总步骤数、当前步骤、步骤详情提示等信息。资料来源：[frontend/src/components/views/chat/progressbar.tsx:1-100]()\n\n### 详情查看器（DetailViewer）\n\n详情查看器是系统与浏览器交互的核心界面组件：\n\n| 功能 | 说明 |\n|------|------|\n| 实时预览 | 显示浏览器当前页面 |\n| 截图历史 | 查看执行过程中的截图 |\n| 控制权交接 | 用户可接管 AI 的控制权 |\n| 输入响应 | 用户可直接在查看器中输入信息 |\n\n资料来源：[frontend/src/components/views/chat/detail_viewer.tsx:1-80]()\n\n### MCP 服务器集成\n\nMagentic-UI 支持通过 MCP（Model Context Protocol）协议扩展功能。系统支持三种连接方式：\n\n| 连接类型 | 适用场景 | 配置复杂度 |\n|----------|----------|------------|\n| SSE | 需要实时推送的服务器 | 中等 |\n| Stdio | 本地命令行工具 | 简单 |\n| JSON Config | 批量导入复杂配置 | 高 |\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx:1-120]()\n\n## 透明度设计\n\n系统内置多重透明度机制，确保用户始终了解 AI 的行为：\n\n### 实时监控\n\n- 运行状态实时显示在界面上\n- 进度条展示当前执行步骤和总步骤\n- 详情查看器显示浏览器实时画面\n\n### 人工干预\n\n- **暂停功能**：用户可随时暂停 AI 的执行\n- **控制权接管**：用户可直接接管浏览器控制权\n- **输入响应**：在 AI 请求时提供人类判断\n\n### 警告机制\n\n界面底部始终显示免责声明：\n\n> Magentic-UI can make mistakes. Please monitor its work and intervene if necessary.\n\n资料来源：[frontend/src/components/layout.tsx:20-25]()\n\n## 网络冲浪代理\n\n后端的核心代理模块负责执行浏览器操作，其功能通过结构化参数定义：\n\n```python\nparameters = {\n \"action\": {\n \"web_search\": \"执行网络搜索\",\n \"visit_url\": \"访问指定 URL\",\n \"scroll\": \"滚动页面\",\n \"click_element\": \"点击元素\",\n \"fill_input\": \"填写输入框\",\n \"pause_and_memorize_fact\": \"暂停并记忆信息\",\n \"wait\": \"等待指定时间\",\n \"terminate\": \"终止任务\"\n }\n}\n```\n\n资料来源：[src/magentic_ui/agents/web_surfer/fara/_prompts.py:1-80]()\n\n## 用户界面布局\n\n```\n┌─────────────────────────────────────────────────────┐\n│ 顶部导航栏 │\n├───────────────────────┬─────────────────────────────┤\n│ │ │\n│ 聊天视图 │ 详情查看器 │\n│ (Chat View) │ (Detail Viewer) │\n│ │ │\n│ │ │\n├───────────────────────┴─────────────────────────────┤\n│ 进度条 │\n├─────────────────────────────────────────────────────┤\n│ 聊天输入框 │\n└─────────────────────────────────────────────────────┘\n```\n\n- 用户可在收起和展开详情查看器之间切换\n- 详情查看器支持最小化和全屏模式\n- 聊天视图自动调整宽度以适应布局变化\n\n资料来源：[frontend/src/components/views/chat/runview.tsx:1-60]()\n\n## 文件管理\n\n系统提供文件上传和下载功能：\n\n- **上传方式**：通过聊天输入框的附件菜单上传文件\n- **文件预览**：支持图片预览和其他文件类型的图标显示\n- **下载功能**：每个文件卡片提供独立的下载按钮\n\n资料来源：[frontend/src/components/common/filerenderer.tsx:1-80]()\n\n## 错误处理\n\n### 404 页面\n\n当用户访问不存在的路由时，系统显示友好的 404 页面，包含返回首页的链接。\n\n资料来源：[frontend/src/pages/404.tsx:1-40]()\n\n### 表单验证\n\n各配置模块均实现了输入验证：\n\n- 必填字段检查\n- 重复名称检测\n- 字符限制（最大长度 50）\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx:60-80]()\n\n## 技术特性总结\n\n| 特性 | 描述 | 状态 |\n|------|------|------|\n| 多模态交互 | 支持文本、图像、文件等多种输入输出 | ✅ |\n| 计划复用 | 可创建、编辑、导入导出计划 | ✅ |\n| 实时预览 | noVNC 远程浏览器控制 | ✅ |\n| 透明度监控 | 进度条、状态显示、人工干预 | ✅ |\n| MCP 扩展 | 支持 SSE/Stdio/JSON 三种连接方式 | ✅ |\n| 计划学习 | 从对话历史自动生成可复用计划 | ✅ |\n\n## 相关文档\n\n- **部署指南**：了解如何在不同环境中部署 Magentic-UI\n- **API 参考**：深入了解后端代理的参数和返回值\n- **插件开发**：学习如何开发自定义 MCP 服务器\n- **最佳实践**：掌握高效使用 Magentic-UI 的技巧\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[项目概述](#overview)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/microsoft/magentic-ui/blob/main/CONTRIBUTING.md)\n- [frontend/README.md](https://github.com/microsoft/magentic-ui/blob/main/frontend/README.md)\n
\n\n# 快速开始指南\n\n## 概述\n\nMagentic-UI 是一个由 Microsoft 开发的开源项目，旨在提供现代化的用户界面来与 AI Agent 进行交互。本指南将帮助开发者快速搭建开发环境、运行项目，并开始进行开发工作。\n\n## 环境要求\n\n### 系统要求\n\n- **操作系统**: Windows、macOS 或 Linux\n- **Node.js**: 用于前端开发\n- **Python**: 用于后端开发（建议使用虚拟环境）\n\n### 依赖工具\n\n- **Poetry**: Python 包管理工具，用于管理后端依赖\n- **npm/yarn**: Node.js 包管理工具，用于管理前端依赖\n\n## 项目结构\n\n```\nmagentic-ui/\n├── frontend/ # 前端项目（React + TypeScript）\n├── src/ # 后端源代码\n├── pyproject.toml # Python 项目配置\n└── CONTRIBUTING.md # 贡献指南\n```\n\n## 安装步骤\n\n### 1. Fork 和克隆仓库\n\n首先，访问 [Magentic-UI 仓库](https://github.com/microsoft/magentic-ui)，Fork 到您自己的账户，然后克隆到本地：\n\n```bash\ngit clone https://github.com//magentic-ui.git\ncd magentic-ui\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 2. 创建开发分支\n\n使用描述性的分支名称来创建新分支：\n\n```bash\ngit checkout -b fix/session-bug\n# 或\ngit checkout -b feature/file-upload\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 3. 安装后端依赖\n\n项目使用 Poetry 管理 Python 依赖。在项目根目录执行：\n\n```bash\npoetry install\n```\n\n### 4. 安装前端依赖\n\n进入前端目录并安装依赖：\n\n```bash\ncd frontend\nnpm install\n```\n\n## 前端配置\n\n### 环境变量设置\n\n前端项目需要配置环境变量才能正确连接到后端 API。\n\n1. 复制默认环境变量文件：\n\n```bash\ncd frontend\ncp .env.default .env.development\n```\n\n2. 编辑 `.env.development` 文件，配置以下主要变量：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `GATSBY_API_URL` | 后端 API 地址 | `http://localhost:8081/api` |\n\n前端的所有 API 请求将发送到 `http://localhost:8081/api` 端点。\n\n资料来源：[frontend/README.md]()\n\n### 添加新页面\n\n前端使用文件系统路由。要添加新页面（如 `/about`）：\n\n1. 在 `src/pages` 目录下创建新文件夹\n2. 在文件夹中添加 `index.tsx` 文件\n3. 参考 `src/pages/index.tsx` 的内容风格\n\n组件的核心逻辑应写在 `src/components` 文件夹中，然后按需在页面中导入使用。\n\n资料来源：[frontend/README.md]()\n\n## 启动开发服务器\n\n### 启动后端服务\n\n```bash\npoetry run <后端启动命令>\n```\n\n### 启动前端开发服务器\n\n```bash\ncd frontend\nnpm run develop\n```\n\n## 代码检查与测试\n\n### 运行本地检查\n\n在提交代码之前，请务必运行检查命令：\n\n```bash\npoe check\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### 编写测试\n\n新功能或错误修复必须包含相应的测试用例。测试文件位于 `tests` 目录中，可以参考现有测试的编写风格。\n\n资料来源：[CONTRIBUTING.md]()\n\n## 提交代码\n\n### 提交 Pull Request\n\n1. 将代码推送到您 Fork 的仓库\n2. 打开 PR 指向 `main` 分支\n3. 在 PR 描述中引用相关 Issue（如 \"Closes #123\"）\n4. 如果需要签署 CLA，CLA 机器人会引导您完成\n\n资料来源：[CONTRIBUTING.md]()\n\n## 常见问题排查\n\n### 前端无法连接后端\n\n确保 `GATSBY_API_URL` 环境变量配置正确，指向运行中的后端服务地址。\n\n### 依赖安装失败\n\n- Python 依赖：确保 Poetry 已正确安装，尝试运行 `poetry install --no-interaction`\n- Node.js 依赖：确保 Node.js 版本符合要求，尝试删除 `node_modules` 后重新安装\n\n### 检查命令失败\n\n查看错误输出，根据提示修复代码问题。常见问题包括代码格式不规范、TypeScript 类型错误等。\n\n## 下一步\n\n- 查看 [CONTRIBUTING.md](https://github.com/microsoft/magentic-ui/blob/main/CONTRIBUTING.md) 了解详细贡献指南\n- 浏览 [Issues](https://github.com/microsoft/magentic-ui/issues) 寻找待解决的问题\n- 特别关注标记为 `help-wanted` 的 Issue，这些特别欢迎社区贡献\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[代理系统详解](#agent-system), [后端API架构](#backend-api), [前端组件结构](#frontend-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/magentic_ui/backend/web/app.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/app.py)\n- [src/magentic_ui/backend/teammanager/teammanager.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/teammanager/teammanager.py)\n- [src/magentic_ui/task_team.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/task_team.py)\n- [src/magentic_ui/_docker.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/_docker.py)\n- [frontend/src/components/layout.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n- [frontend/src/components/views/chat/runview.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/runview.tsx)\n- [frontend/src/components/views/chat/chatinput.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/chatinput.tsx)\n- [frontend/README.md](https://github.com/microsoft/magentic-ui/blob/main/frontend/README.md)\n\n
\n\n# 系统架构\n\n## 概述\n\nMagentic-UI 是一个基于 Web 的用户界面系统，用于与 AI Agent 团队进行交互式协作。该项目采用前后端分离架构，前端使用 React 构建，后端基于 Python FastAPI 框架。系统核心围绕任务执行、团队协作和状态管理三大模块展开。资料来源：[frontend/README.md](https://github.com/microsoft/magentic-ui/blob/main/frontend/README.md)\n\n## 整体架构\n\nMagentic-UI 采用典型的分层架构设计，包含以下核心层：\n\n| 层级 | 技术栈 | 职责 |\n|------|--------|------|\n| 前端展示层 | React + TypeScript + Ant Design | 用户界面渲染、交互处理 |\n| 前端状态层 | React Context + Hooks | 会话状态、运行状态管理 |\n| 后端 API 层 | FastAPI (Python) | RESTful API 服务 |\n| 核心逻辑层 | Python | Agent 团队管理、任务执行 |\n| 容器化层 | Docker | 环境隔离、资源管理 |\n\n资料来源：[frontend/src/components/layout.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n\n```mermaid\ngraph TD\n A[用户浏览器] --> B[React 前端]\n B --> C[FastAPI 后端]\n C --> D[Agent 团队管理]\n D --> E[任务执行引擎]\n E --> F[Docker 容器]\n F --> G[AI 模型服务]\n```\n\n## 前端架构\n\n### 技术选型\n\n前端项目位于 `frontend/` 目录，使用以下核心技术：\n\n- **React 18**: 核心 UI 框架\n- **TypeScript**: 类型安全\n- **Ant Design**: UI 组件库\n- **Tailwind CSS**: 样式框架\n- **Gatsby**: 静态站点生成器\n\n资料来源：[frontend/README.md](https://github.com/microsoft/magentic-ui/blob/main/frontend/README.md)\n\n### 目录结构\n\n```\nfrontend/src/\n├── components/ # 核心组件\n│ ├── common/ # 通用组件\n│ ├── features/ # 功能组件\n│ │ ├── Plans/ # 计划管理\n│ │ └── McpServersConfig/ # MCP 服务器配置\n│ ├── layout.tsx # 布局组件\n│ └── views/\n│ └── chat/ # 聊天视图\n│ ├── chatinput.tsx # 聊天输入\n│ ├── runview.tsx # 运行视图\n│ ├── progressbar.tsx # 进度条\n│ └── rendermessage.tsx # 消息渲染\n├── pages/ # 页面路由\n└── context/ # React Context\n```\n\n资料来源：[frontend/src/components/layout.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n\n### 状态管理\n\n系统使用 React Context 进行状态管理，主要包含以下上下文：\n\n| Context | 用途 |\n|---------|------|\n| `appContext` | 应用级上下文，包含用户信息 |\n| `sessionContext` | 会话状态管理 |\n| `runContext` | 任务运行状态管理 |\n\n状态流转通过 `SessionManager` 组件统一协调，该组件位于布局的主内容区域。资料来源：[frontend/src/components/layout.tsx:33](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n\n### 关键组件\n\n#### ChatInput 组件\n\n`ChatInput` 是用户与系统交互的核心入口，支持以下功能：\n\n- 文本消息输入\n- 文件上传\n- 计划（Plan）附件\n- 任务暂停控制\n\n组件根据 `runStatus` 状态动态调整 UI 行为：当状态为 `active` 时显示暂停按钮，否则显示发送按钮。资料来源：[frontend/src/components/views/chat/chatinput.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/chatinput.tsx)\n\n#### RunView 组件\n\n`RunView` 是任务执行的主视图，整合了以下子组件：\n\n- **DetailViewer**: 图像/VNC 详情查看\n- **ChatInput**: 消息输入\n- **ApprovalButtons**: 审批按钮组\n- **ProgressBar**: 执行进度条\n\n组件布局支持展开/收起状态，通过 `detailViewerExpanded` 状态控制。资料来源：[frontend/src/components/views/chat/runview.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/runview.tsx)\n\n## 后端架构\n\n### 技术选型\n\n后端项目位于 `src/magentic_ui/backend/`，使用 FastAPI 框架构建 RESTful API 服务。\n\n### API 服务\n\n后端 API 服务通过 `app.py` 定义，提供以下核心端点：\n\n- **会话管理**: 创建、更新、查询会话状态\n- **任务执行**: 启动、暂停、取消任务\n- **计划管理**: 创建、修改、删除计划\n- **文件传输**: 上传下载文件\n\nAPI 默认运行在 `http://localhost:8081/api`，前端通过环境变量 `GATSBY_API_URL` 配置连接地址。资料来源：[frontend/README.md](https://github.com/microsoft/magentic-ui/blob/main/frontend/README.md)\n\n## Agent 团队架构\n\n### 团队管理\n\n系统核心采用团队（Team）模式进行任务协调，团队管理器负责：\n\n- 创建和初始化 Agent 团队\n- 管理团队成员的生命周期\n- 协调团队内部通信\n- 处理团队执行结果\n\n资料来源：[src/magentic_ui/backend/teammanager/teammanager.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/teammanager/teammanager.py)\n\n### 任务团队\n\n`TaskTeam` 是任务执行的核心类，负责：\n\n1. 解析用户输入的任务描述\n2. 生成执行计划（Plan）\n3. 分配子任务给团队成员\n4. 监控执行进度\n5. 汇总最终结果\n\n资料来源：[src/magentic_ui/task_team.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/task_team.py)\n\n### 计划（Plan）系统\n\n计划系统是系统的核心功能模块，允许用户：\n\n- 创建可复用的任务计划\n- 学习并保存执行过的计划\n- 将计划附加到新任务中\n\n#### Plan 数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| task | string | 计划标题 |\n| steps | array | 执行步骤列表 |\n| created_at | datetime | 创建时间 |\n| id | string | 唯一标识 |\n\n资料来源：[frontend/src/components/features/Plans/PlanCard.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanCard.tsx)\n\n#### PlanView 组件\n\n`PlanView` 组件支持两种模式：\n\n- **viewOnly=true**: 只读展示模式，用于消息中渲染计划\n- **viewOnly=false**: 编辑模式，用于创建和修改计划\n\n资料来源：[frontend/src/components/views/chat/rendermessage.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/rendermessage.tsx)\n\n## 容器化架构\n\n### Docker 集成\n\n系统使用 Docker 进行环境隔离和资源管理，核心功能包括：\n\n- 独立的 Agent 执行环境\n- 动态容器创建和销毁\n- 资源配额控制\n\n资料来源：[src/magentic_ui/_docker.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/_docker.py)\n\n### MCP 服务器配置\n\n系统支持 MCP（Model Context Protocol）服务器集成，提供三种连接方式：\n\n| 连接类型 | 说明 |\n|----------|------|\n| SSE | Server-Sent Events 推送 |\n| Stdio | 标准输入输出流 |\n| JSON Config | JSON 配置文件导入 |\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/McpServersConfig/McpConfigModal.tsx)\n\n## 运行状态机\n\n系统定义了完整的任务运行状态机：\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: 创建任务\n pending --> planning: 进入计划阶段\n planning --> awaiting_approval: 等待用户审批\n awaiting_approval --> active: 用户批准\n awaiting_approval --> [*]: 用户拒绝\n active --> paused: 用户暂停\n paused --> active: 恢复执行\n active --> completed: 任务完成\n active --> failed: 执行失败\n completed --> [*]\n failed --> [*]\n```\n\n| 状态 | 说明 |\n|------|------|\n| pending | 任务已创建，等待处理 |\n| planning | 正在生成执行计划 |\n| awaiting_approval | 等待用户审批计划 |\n| awaiting_input | 等待用户输入响应 |\n| active | 任务正在执行 |\n| paused | 任务已暂停 |\n| completed | 任务成功完成 |\n| failed | 任务执行失败 |\n\n资料来源：[frontend/src/components/views/chat/chatinput.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/chatinput.tsx)\n\n## 进度跟踪\n\n### 进度条组件\n\n`ProgressBar` 组件实时显示任务执行进度，支持以下视觉状态：\n\n- **已完成部分**: 绿色（bg-green-600）\n- **当前步骤**: 紫红色（bg-magenta-800）\n- **剩余部分**: 灰色（bg-gray-300）\n\n进度计算公式：\n\n```\n已完成百分比 = (currentStep / totalSteps) * 100\n```\n\n资料来源：[frontend/src/components/views/chat/progressbar.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/progressbar.tsx)\n\n### 状态文本显示\n\n进度条下方的状态文本根据执行状态动态变化：\n\n| 条件 | 显示内容 |\n|------|----------|\n| hasFinalAnswer=true | \"Task Completed\" |\n| 正常执行中 | \"Step X of Y: 步骤标题...\" |\n| 计划模式 | \"Planning...\" |\n\n资料来源：[frontend/src/components/views/chat/progressbar.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/progressbar.tsx)\n\n## 数据流\n\n### 消息渲染流程\n\n```mermaid\ngraph LR\n A[用户输入] --> B[ChatInput]\n B --> C[API 请求]\n C --> D[后端处理]\n D --> E[Agent 执行]\n E --> F[状态更新]\n F --> G[RenderMessage]\n G --> H[UI 渲染]\n```\n\n`RenderMessage` 组件负责将后端返回的消息渲染为可视化内容，支持：\n\n- 纯文本消息\n- 多模态内容（文本 + 附件）\n- 计划卡片展示\n- 文件预览\n\n资料来源：[frontend/src/components/views/chat/rendermessage.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/rendermessage.tsx)\n\n### 文件处理流程\n\n文件通过 `RenderFile` 组件处理，支持的文件类型通过 `IconComponent` 动态映射：\n\n1. 提取文件元数据（类型、大小、名称）\n2. 选择对应的文件图标组件\n3. 渲染文件卡片或缩略图\n4. 支持下载功能\n\n资料来源：[frontend/src/components/common/filerenderer.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/common/filerenderer.tsx)\n\n## 安全与限制\n\n### 访问控制\n\n系统通过 `restricted` 标志控制访问权限：\n\n```typescript\nif (restricted) {\n return (\n \n {(context: any) => {\n if (context.user) {\n return layoutContent;\n }\n return null;\n }}\n \n );\n}\n```\n\n未认证用户只能看到空白页面。资料来源：[frontend/src/components/layout.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n\n### 错误处理\n\n系统底部显示安全提示：\n\n```\nMagentic-UI can make mistakes. Please monitor its work and intervene if necessary.\n```\n\n资料来源：[frontend/src/components/layout.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n\n## 环境配置\n\n### 前端环境变量\n\n创建 `.env.development` 文件，配置以下变量：\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| GATSBY_API_URL | http://localhost:8081/api | 后端 API 地址 |\n\n资料来源：[frontend/README.md](https://github.com/microsoft/magentic-ui/blob/main/frontend/README.md)\n\n### 开发模式\n\n前端开发服务器默认连接到本地后端服务，确保后端在 `localhost:8081` 运行后再启动前端开发服务器。\n\n---\n\n\n\n## 代理系统详解\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [浏览器自动化引擎](#browser-automation)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/magentic_ui/agents/web_surfer/_web_surfer.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/agents/web_surfer/_web_surfer.py)\n- [src/magentic_ui/agents/file_surfer/_file_surfer.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/agents/file_surfer/_file_surfer.py)\n- [src/magentic_ui/agents/_coder.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/agents/_coder.py)\n- [src/magentic_ui/teams/orchestrator/_orchestrator.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/teams/orchestrator/_orchestrator.py)\n- [src/magentic_ui/agents/mcp/_agent.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/agents/mcp/_agent.py)\n
\n\n# 代理系统详解\n\n## 1. 系统概述\n\nMagentic-UI 的代理系统是一个多代理协作框架，旨在通过多个专业化的 AI 代理协同工作来完成复杂任务。该系统基于 Model Context Protocol (MCP) 架构，支持网页浏览、文件操作、代码生成等多种功能。\n\n系统采用**团队协作模式（Group Chat）**，由 Orchestrator（编排器）负责协调多个代理之间的工作分配和消息传递。每个代理都有其特定的专业领域和工具集，通过标准化的消息格式进行通信。\n\n```mermaid\ngraph TD\n A[用户任务] --> B[Orchestrator 编排器]\n B --> C[WebSurfer 代理]\n B --> D[FileSurfer 代理]\n B --> D[CoderAgent 代理]\n B --> E[MCP Agent 代理]\n C --> F[浏览器控制]\n D --> G[文件系统操作]\n E --> H[MCP 服务器]\n```\n\n## 2. 代理类型详解\n\n### 2.1 WebSurfer 代理\n\nWebSurfer 是专门用于网页浏览和交互的代理，能够模拟用户操作浏览器完成任务。\n\n#### 支持的操作类型\n\n| 操作 | 描述 | 必需参数 |\n|------|------|----------|\n| `visit_url` | 访问指定 URL | `url` |\n| `web_search` | 执行网络搜索 | `query` |\n| `history_back` | 返回上一页 | 无 |\n| `pause_and_memorize_fact` | 暂停并记住信息 | `fact` |\n| `wait` | 等待指定秒数 | `time` |\n| `terminate` | 终止任务 | `status` |\n\n#### 鼠标和键盘操作\n\n| 操作 | 描述 | 必需参数 |\n|------|------|----------|\n| `left_click` | 左键点击 | `coordinate` |\n| `right_click` | 右键点击 | `coordinate` |\n| `mouse_move` | 移动鼠标 | `coordinate` |\n| `scroll` | 滚动页面 | `pixels` |\n| `key` | 按键操作 | `keys` |\n| `type` | 输入文本 | `text`, `coordinate` |\n\n#### 配置参数\n\n```python\nweb_surfer = WebSurfer(\n name=\"web_surfer\",\n model_client=model_client_websurfer,\n browser=browser,\n animate_actions=False,\n max_actions_per_step=10,\n start_page=\"about:blank\" if task.url_path == \"\" else task.url_path,\n downloads_folder=os.path.abspath(output_dir),\n debug_dir=os.path.abspath(output_dir),\n model_context_token_limit=model_context_token_limit,\n to_save_screenshots=True,\n)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 代理名称标识 |\n| `model_client` | ModelClient | 模型客户端实例 |\n| `browser` | Browser | 浏览器实例 |\n| `animate_actions` | bool | 是否动画显示操作 |\n| `max_actions_per_step` | int | 每步最大操作数 |\n| `start_page` | string | 起始页面 URL |\n| `downloads_folder` | string | 文件下载目录 |\n| `debug_dir` | string | 调试信息保存目录 |\n| `model_context_token_limit` | int | 上下文 token 限制 |\n| `to_save_screenshots` | bool | 是否保存截图 |\n\n### 2.2 FileSurfer 代理\n\nFileSurfer 代理专门用于文件系统操作，支持文件浏览、读取和修改。\n\n#### 核心功能\n\n- 目录浏览和导航\n- 文件内容读取\n- 文件创建和编辑\n- 路径绑定和安全限制\n\n#### 配置参数\n\n```python\nfile_surfer = FileSurfer(\n name=\"file_surfer\",\n model_client=model_client_file_surfer,\n work_dir=os.path.abspath(output_dir),\n bind_dir=os.path.abspath(output_dir),\n model_context_token_limit=model_context_token_limit,\n)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `work_dir` | string | 工作目录路径 |\n| `bind_dir` | string | 绑定的安全目录（限制访问范围） |\n\n### 2.3 CoderAgent 代理\n\nCoderAgent 专门用于代码生成和修改任务，支持多种编程语言的代码编写。\n\n#### 核心功能\n\n- 根据需求生成代码\n- 代码文件创建和修改\n- 工作目录管理\n\n#### 配置参数\n\n```python\ncoder_agent = CoderAgent(\n name=\"coder_agent\",\n model_client=model_client_coder,\n work_dir=os.path.abspath(output_dir),\n model_context_token_limit=model_context_token_limit,\n)\n```\n\n### 2.4 MCPAgent 代理\n\nMCP Agent 是基于 Model Context Protocol 的扩展代理，用于连接外部 MCP 服务器。\n\n#### 支持的连接方式\n\n| 连接类型 | 说明 |\n|----------|------|\n| SSE | Server-Sent Events 方式连接 |\n| Stdio | 标准输入输出方式连接 |\n| JSON Config | JSON 配置文件方式 |\n\n#### 服务器配置\n\n```typescript\n// 前端 MCP 配置界面\ninterface MCPServerConfig {\n serverName: string; // 服务器名称（仅字母和数字）\n connectionType: 'sse' | 'stdio' | 'json';\n command?: string; // Stdio 连接时的命令\n args?: string[]; // Stdio 连接时的参数\n url?: string; // SSE 连接时的 URL\n env?: Record; // 环境变量\n}\n```\n\n## 3. Orchestrator 编排器\n\nOrchestrator 是系统的核心组件，负责协调多个代理之间的工作流程。\n\n### 3.1 架构设计\n\n```mermaid\ngraph LR\n A[用户输入] --> B[Orchestrator]\n B --> C{任务分析}\n C -->|需要浏览网页| D[WebSurfer]\n C -->|需要文件系统| E[FileSurfer]\n C -->|需要编码| F[CoderAgent]\n D --> G[执行结果]\n E --> G\n F --> G\n G --> B\n B --> H[最终响应]\n```\n\n### 3.2 团队配置\n\n```python\nteam = GroupChat(\n participants=agent_list,\n orchestrator_config=orchestrator_config,\n model_client=model_client_orch,\n termination_condition=termination_condition,\n)\nawait team.lazy_init()\n```\n\n### 3.3 终止条件\n\n系统支持多种终止条件：\n\n| 条件类型 | 说明 |\n|----------|------|\n| `max_steps` | 达到最大步数后终止 |\n| `llm_judged` | LLM 判断任务完成 |\n| `external` | 外部信号终止 |\n\n## 4. 前端集成\n\n### 4.1 运行视图组件\n\n前端通过 `RunView` 组件展示代理运行状态：\n\n```typescript\n// 核心组件结构\n\n```\n\n### 4.2 状态显示\n\n| 状态 | 说明 |\n|------|------|\n| `active` | 正在执行任务 |\n| `awaiting_input` | 等待用户输入 |\n| `paused` | 已暂停 |\n| `pausing` | 正在暂停 |\n| `completed` | 已完成 |\n\n### 4.3 进度条显示\n\n```typescript\n// 进度信息显示逻辑\n{hasFinalAnswer ? (\n \n Task Completed\n \n) : adjustedProgress.plan?.task ? (\n \n Step {adjustedProgress.currentStep + 1} of {adjustedProgress.totalSteps}\n {`: ${adjustedProgress.plan.steps[adjustedProgress.currentStep]?.title?.substring(0, 30)}...`}\n \n) : ...}\n```\n\n## 5. 计划系统\n\n### 5.1 计划数据结构\n\n```typescript\ninterface Plan {\n id: string;\n task: string; // 计划标题\n steps: PlanStep[]; // 步骤列表\n created_at?: string; // 创建时间\n}\n\ninterface PlanStep {\n title: string; // 步骤标题\n description?: string; // 步骤描述\n status?: 'pending' | 'active' | 'completed' | 'failed';\n}\n```\n\n### 5.2 计划视图\n\n- 超过 3 个步骤时显示 \"+ X more steps\" 提示\n- 支持相对时间显示（如 \"2 hours ago\"）\n- 可通过 Modal 编辑计划\n\n## 6. 工具调用格式\n\n### 6.1 函数调用模板\n\n```xml\n\n{tool_definition}\n\n{tool_code}\n\n\n```\n\n### 6.2 响应格式\n\n```xml\n\n{response_content}\n\n```\n\n### 6.3 特殊模式\n\n系统支持 `SPECIAL_CODE_MODE`，当工具名称包含 `CODE_TOOL_PATTERN` 时自动选择特殊模板：\n\n```python\nif SPECIAL_CODE_MODE and any([CODE_TOOL_PATTERN in x for x in tool_names]):\n selected_template = FN_CALL_TEMPLATE_WITH_CI\n```\n\n## 7. 环境配置\n\n### 7.1 后端 API 配置\n\n前端请求后端 API 地址：\n\n```\nhttp://localhost:8081/api\n```\n\n### 7.2 环境变量设置\n\n在 `frontend/.env.development` 中配置：\n\n```bash\nGATSBY_API_URL=http://localhost:8081/api\n```\n\n## 8. 数据模型\n\n### 8.1 消息结构\n\n```typescript\ninterface Message {\n id: string;\n role: 'user' | 'assistant' | 'system' | 'function';\n content: ContentItem[];\n metadata?: {\n type?: 'file' | 'image' | 'plan';\n files?: string; // JSON string of files\n };\n reasoning_content?: string;\n}\n```\n\n### 8.2 会话状态\n\n```typescript\ninterface SessionState {\n messages: Message[];\n session: Session | null;\n sessions: Session[];\n version: string | null;\n connectionId: string;\n}\n```\n\n## 9. 最佳实践\n\n### 9.1 代理选择建议\n\n| 任务类型 | 推荐代理 |\n|----------|----------|\n| 网页信息获取 | WebSurfer |\n| 文件操作 | FileSurfer |\n| 代码生成 | CoderAgent |\n| 外部工具集成 | MCPAgent |\n\n### 9.2 性能优化\n\n- 合理设置 `max_actions_per_step` 避免单步过长\n- 使用 `model_context_token_limit` 控制上下文长度\n- 启用 `to_save_screenshots=True` 便于调试\n\n### 9.3 安全考虑\n\n- FileSurfer 必须设置 `bind_dir` 限制访问范围\n- MCPServer 配置需验证服务器名称格式\n- 敏感操作需用户确认\n\n## 10. 总结\n\nMagentic-UI 的代理系统通过模块化设计实现了高度的可扩展性和灵活性。Orchestrator 作为核心协调器管理多个专业代理的工作流程，每个代理专注于特定功能领域。前端组件提供了良好的用户体验，实时展示任务进度和执行状态。系统支持 MCP 协议扩展，可轻松集成外部工具和服务。\n\n---\n\n\n\n## 前端组件结构\n\n### 相关页面\n\n相关主题：[后端API架构](#backend-api), [设置与配置管理](#settings-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [frontend/src/components/views/chat/chat.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/chat.tsx)\n- [frontend/src/components/views/chat/plan.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/plan.tsx)\n- [frontend/src/components/views/manager.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/manager.tsx)\n- [frontend/src/components/layout.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/layout.tsx)\n- [frontend/src/components/views/chat/runview.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/runview.tsx)\n- [frontend/src/components/views/chat/rendermessage.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/rendermessage.tsx)\n- [frontend/src/components/features/Plans/PlanCard.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanCard.tsx)\n- [frontend/src/components/features/Plans/PlanList.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanList.tsx)\n
\n\n# 前端组件结构\n\n## 概述\n\nMagentic-UI 的前端是一个基于 React 和 TypeScript 构建的现代 Web 应用程序，采用组件化架构。该项目位于 `frontend/` 目录下，使用 Ant Design 作为主要的 UI 组件库，并集成了状态管理、路由导航、文件处理等多种功能模块。\n\n前端的核心职责是提供用户交互界面，包括会话管理、聊天视图、计划创建与执行、文件预览、以及与后端 MCP（Model Context Protocol）服务器的集成。\n\n## 目录结构\n\n```\nfrontend/src/components/\n├── common/ # 通用组件\n│ └── filerenderer.tsx # 文件渲染组件\n├── features/ # 功能模块组件\n│ ├── McpServersConfig/ # MCP 服务器配置\n│ └── Plans/ # 计划相关组件\n├── layout.tsx # 根布局组件\n├── store.tsx # 状态管理\n├── views/ # 视图层组件\n│ └── chat/ # 聊天视图模块\n│ ├── chat.tsx # 聊天主视图\n│ ├── plan.tsx # 计划视图\n│ ├── rendermessage.tsx # 消息渲染\n│ ├── runview.tsx # 运行视图\n│ ├── progressbar.tsx # 进度条\n│ └── relevant_plans.tsx # 相关计划\n└── pages/ # 页面组件\n └── 404.tsx # 404错误页面\n```\n\n## 核心组件架构\n\n### 布局组件（Layout）\n\n`layout.tsx` 是应用的整体布局容器，负责主题配置和会话管理器的挂载。\n\n```mermaid\ngraph TD\n A[MagenticUILayout] --> B[ConfigProvider]\n A --> C[SessionManager]\n B --> D[主题配置
暗色/亮色模式]\n C --> E[视图渲染]\n A --> F[底部免责声明]\n```\n\n关键特性：\n- 使用 Ant Design 的 `ConfigProvider` 实现主题管理，支持 `darkAlgorithm` 和 `defaultAlgorithm`\n- 根据 `restricted` 属性控制用户访问权限\n- 底部显示 \"Magentic-UI can make mistakes\" 免责声明 资料来源：[frontend/src/components/layout.tsx]()\n\n### 会话管理器（Manager）\n\n`manager.tsx` 是核心的状态容器组件，负责管理会话列表、活跃会话和子菜单状态。\n\n| 状态/属性 | 类型 | 说明 |\n|---------|------|------|\n| `sessions` | Session[] | 所有会话列表 |\n| `session` | Session \\| null | 当前活跃会话 |\n| `activeSubMenuItem` | string | 当前子菜单项 |\n| `isEditorOpen` | boolean | 会话编辑器是否打开 |\n\n主要功能：\n- 加载和管理会话列表\n- 处理会话创建、选择和删除\n- 支持从计划创建新会话\n- 渲染 `PlanList` 和聊天视图\n\n资料来源：[frontend/src/components/views/manager.tsx]()\n\n## 聊天视图模块\n\n### Chat 主组件\n\n`chat.tsx` 是聊天功能的核心入口组件，封装了聊天输入、消息列表和会话控制功能。\n\n```mermaid\ngraph TD\n A[ChatInput] -->|提交| B{检查运行状态}\n B -->|awaiting_input/paused| C[handleInputResponse]\n B -->|其他状态| D[runTask]\n C --> E[更新会话]\n D --> F[触发后端任务执行]\n A --> G[SampleTasks]\n G -->|选择示例| D\n```\n\n核心 Props：\n\n| Prop | 类型 | 说明 |\n|------|------|------|\n| `onSubmit` | function | 提交消息处理 |\n| `error` | string | 错误信息 |\n| `onCancel` | function | 取消操作 |\n| `runStatus` | string | 当前运行状态 |\n| `inputRequest` | object | 输入请求 |\n| `isPlanMessage` | boolean | 是否为计划消息 |\n| `onPause` | function | 暂停处理 |\n| `onExecutePlan` | function | 执行计划回调 |\n\n资料来源：[frontend/src/components/views/chat/chat.tsx]()\n\n### 消息渲染组件\n\n`rendermessage.tsx` 负责将消息内容渲染为可交互的 UI 元素。\n\n```mermaid\ngraph LR\n A[Message] --> B{消息类型判断}\n B -->|多模态文本| C[逐项渲染]\n B -->|单文本| D[直接渲染]\n B -->|计划内容| E[PlanView组件]\n```\n\n关键渲染逻辑：\n- 支持多模态内容处理（文本数组）\n- 使用 `break-words` 和 `whitespace-pre-wrap` 保证文本格式\n- 对于计划内容，调用 `PlanView` 组件进行渲染 资料来源：[frontend/src/components/views/chat/rendermessage.tsx]()\n\n### 进度条组件\n\n`progressbar.tsx` 展示任务执行进度，包括已完成、当前和剩余步骤。\n\n```mermaid\ngraph TD\n A[adjustedProgress] --> B{hasFinalAnswer?}\n B -->|是| C[显示100%绿色]\n B -->|否| D[分段显示]\n D --> E[绿色: 已完成]\n D --> F[深色: 当前步骤]\n D --> G[灰色: 剩余步骤]\n```\n\n进度状态显示：\n- **已完成**：绿色进度条，宽度根据 `currentStep / totalSteps` 计算\n- **当前步骤**：深色块，显示步骤数和标题\n- **完成状态**：显示 \"Task Completed\" 绿色文本 资料来源：[frontend/src/components/views/chat/progressbar.tsx]()\n\n## 计划组件模块\n\n### PlanView 组件\n\n`plan.tsx` 是计划视图的核心组件，支持只读和编辑两种模式。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `viewOnly` | boolean | 是否只读模式 |\n| `task` | string | 计划任务描述 |\n| `plan` | IPlan[] | 计划步骤数组 |\n| `setPlan` | function | 更新计划回调 |\n\n关键功能：\n- 哨兵步骤（Sentinel Step）支持循环执行\n- 条件配置：按时间间隔（`sleep_duration`）或次数（`condition`）执行\n- 支持步骤详情编辑和自动调整文本区域 资料来源：[frontend/src/components/views/chat/plan.tsx]()\n\n### 计划卡片（PlanCard）\n\n`PlanCard.tsx` 展示单个计划的摘要信息，支持快速查看和编辑。\n\n```typescript\ninterface Plan {\n id: string;\n name: string;\n steps: PlanStep[];\n created_at?: string;\n}\n```\n\n显示内容：\n- 计划名称和前 3 个步骤预览\n- 创建时间的相对显示（使用 `getRelativeTimeString`）\n- 超过 3 个步骤时显示 \"+ X more steps\"\n- 编辑模式下通过 Modal 展示完整计划编辑器 资料来源：[frontend/src/components/features/Plans/PlanCard.tsx]()\n\n### 计划列表（PlanList）\n\n`PlanList.tsx` 管理用户的保存计划库。\n\n主要功能：\n- 创建新计划（空计划）\n- 从 JSON 文件导入计划\n- 搜索和过滤计划\n- 拖拽导入计划文件\n\n| 功能 | 实现方式 |\n|------|---------|\n| 创建 | PlusOutlined 按钮触发 |\n| 导入 | 文件上传 Input + JSON 解析 |\n| 搜索 | Input 组件 + 状态过滤 |\n\n资料来源：[frontend/src/components/features/Plans/PlanList.tsx]()\n\n## 运行视图（RunView）\n\n`runview.tsx` 是任务执行详情视图的核心容器。\n\n```mermaid\ngraph TD\n A[RunView] --> B[DetailViewer]\n A --> C[RenderMessage列表]\n B --> D{展开状态}\n D -->|最小化| E[仅占50%宽度]\n D -->|展开| F[全宽显示]\n C --> G[ApprovalButtons]\n G --> H{状态判断}\n H -->|pending| I[显示批准/拒绝按钮]\n```\n\n支持的 props：\n- `images` / `imageTitles`: 图片预览数据\n- `novncPort`: VNC 连接端口\n- `onPause` / `onInputResponse`: 交互回调\n- `detailViewerExpanded`: 详情查看器展开状态 资料来源：[frontend/src/components/views/chat/runview.tsx]()\n\n## 文件渲染组件\n\n`filerenderer.tsx` 负责处理和展示各类文件预览。\n\n```mermaid\ngraph TD\n A[RenderFile] --> B{文件类型判断}\n B -->|图片| C[ImageThumbnail]\n B -->|代码/其他| D[FileCard]\n C --> E[点击打开Modal]\n D --> E\n E --> F[显示文件内容]\n F --> G[支持下载]\n```\n\n文件状态管理：\n| 状态 | 类型 | 用途 |\n|------|------|------|\n| `files` | FileInfo[] | 提取的文件列表 |\n| `selectedFile` | FileInfo \\| null | 当前选中文件 |\n| `fileContent` | string \\| null | 文件内容 |\n| `isModalOpen` | boolean | 预览 Modal 开关 | 资料来源：[frontend/src/components/common/filerenderer.tsx]()\n\n## 组件间数据流\n\n```mermaid\ngraph LR\n A[layout.tsx] --> B[Manager]\n B --> C[Chat]\n B --> D[PlanList]\n C --> E[ChatInput]\n C --> F[RenderMessage]\n C --> G[RunView]\n F --> H[PlanView]\n F --> I[RenderFile]\n G --> J[DetailViewer]\n G --> K[ProgressBar]\n K --> L[ApprovalButtons]\n```\n\n## 技术栈总结\n\n| 层级 | 技术/框架 | 用途 |\n|------|---------|------|\n| UI 组件库 | Ant Design | 基础 UI 组件 |\n| 状态管理 | React hooks + Context | 会话和应用状态 |\n| 样式 | Tailwind CSS + CSS Variables | 主题和样式 |\n| 图表 | Mermaid (文档用) | 架构图展示 |\n| 路由 | React Router (隐式) | 页面导航 |\n\n## 总结\n\nMagentic-UI 前端采用分层组件架构：\n\n1. **布局层**：`layout.tsx` 提供应用外壳和主题配置\n2. **管理层**：`manager.tsx` 处理会话生命周期\n3. **视图层**：聊天、计划、运行视图等功能模块\n4. **展示层**：通用组件如文件渲染、进度条等\n\n组件之间通过 props 传递数据和回调函数，保持良好的解耦性。计划系统是该应用的核心特色，支持创建、保存、导入、执行和从对话中学习计划的全生命周期管理。\n\n---\n\n\n\n## 设置与配置管理\n\n### 相关页面\n\n相关主题：[前端组件结构](#frontend-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [frontend/src/hooks/store.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/hooks/store.tsx)\n- [frontend/README.md](https://github.com/microsoft/magentic-ui/blob/main/frontend/README.md)\n- [frontend/src/components/features/McpServersConfig/McpConfigModal.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/McpServersConfig/McpConfigModal.tsx)\n- [frontend/src/components/features/McpServersConfig/McpServerCard.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/McpServersConfig/McpServerCard.tsx)\n- [frontend/src/components/features/Plans/PlanList.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanList.tsx)\n- [frontend/src/components/features/Plans/PlanCard.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanCard.tsx)\n
\n\n# 设置与配置管理\n\n## 概述\n\nMagentic-UI 的设置与配置管理系统负责管理应用程序的全局状态、用户偏好设置、Agent 流程配置以及外部服务（如 MCP 服务器）的连接配置。该系统采用前后端分离的架构，前端使用 React Hooks 进行状态管理，后端通过 RESTful API 提供持久化支持。\n\n配置管理涵盖了以下核心领域：\n\n- **主题与界面配置**：暗色/亮色模式切换\n- **Agent 流程设置**：流向、标签、网格、代币显示等\n- **会话管理**：会话列表、当前会话状态\n- **MCP 服务器配置**：SSE、Stdio、JSON Config 三种连接方式\n- **计划管理**：可复用计划的创建、导入、导出\n\n资料来源：[frontend/src/hooks/store.tsx:1-50]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[前端 React 应用] --> B[Zustand Store 状态管理层]\n B --> C[useConfigStore 配置存储]\n B --> D[持久化层 LocalStorage]\n \n E[MCP 服务器] --> F[MCPConfigModal 配置模态框]\n F --> G[后端 API /api/settings]\n G --> H[服务器端存储]\n \n I[Plan 计划管理] --> J[PlanList 计划列表]\n J --> K[PlanCard 计划卡片]\n K --> L[PlanView 计划视图]\n \n M[主题配置] --> N[Ant Design ConfigProvider]\n N --> O[darkAlgorithm 默认算法]\n```\n\n### 配置状态管理\n\n前端使用 Zustand 库配合 `persist` 中间件实现全局状态管理，配置数据会自动持久化到浏览器的 LocalStorage 中。\n\n```mermaid\ngraph LR\n A[用户操作] --> B[setAgentFlowSettings]\n B --> C[Zustand Store]\n C --> D[persist middleware]\n D --> E[LocalStorage]\n E --> F[页面刷新]\n F --> C\n```\n\n资料来源：[frontend/src/hooks/store.tsx:30-80]()\n\n## Agent 流程设置\n\n### 配置接口定义\n\nAgent 流程设置通过 `IAgentFlowSettings` 接口管理，包含以下配置项：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `direction` | `string` | `\"TB\"` | 流程图方向：TB（从上到下）/ LR（从左到右） |\n| `showLabels` | `boolean` | `true` | 是否显示节点标签 |\n| `showGrid` | `boolean` | `true` | 是否显示网格背景 |\n| `showTokens` | `boolean` | `true` | 是否显示 Token 统计 |\n| `showMessages` | `boolean` | `true` | 是否显示消息流 |\n| `showMiniMap` | `boolean` | `false` | 是否显示小地图 |\n\n```typescript\n// 默认配置定义\nconst DEFAULT_AGENT_FLOW_SETTINGS: IAgentFlowSettings = {\n direction: \"TB\",\n showLabels: true,\n showGrid: true,\n showTokens: true,\n showMessages: true,\n showMiniMap: false,\n};\n```\n\n资料来源：[frontend/src/hooks/store.tsx:20-30]()\n\n### 配置状态接口\n\n完整的配置状态管理包含多个子模块：\n\n```typescript\ninterface IConfigState {\n // 消息状态\n messages: any[];\n setMessages: (messages: any[]) => void;\n \n // 会话状态\n session: any;\n sessions: any[];\n setSession: (session: any) => void;\n setSessions: (sessions: any[]) => void;\n \n // 版本与连接\n version: string | null;\n connectionId: string;\n \n // Header 状态\n header: IHeaderState;\n setHeader: (header: Partial) => void;\n setBreadcrumbs: (breadcrumbs: IBreadcrumb[]) => void;\n \n // 侧边栏状态\n sidebar: ISidebarState;\n setSidebarState: (state: Partial) => void;\n collapseSidebar: () => void;\n expandSidebar: () => void;\n toggleSidebar: () => void;\n \n // Agent 流程设置\n agentFlow: IAgentFlowSettings;\n setAgentFlowSettings: (settings: Partial) => void;\n}\n```\n\n资料来源：[frontend/src/hooks/store.tsx:1-45]()\n\n## MCP 服务器配置\n\n### 连接类型\n\nMCP（Magentic-UI Model Context Protocol）服务器配置支持三种连接方式：\n\n| 连接类型 | 说明 | 使用场景 |\n|----------|------|----------|\n| `SSE` | Server-Sent Events，基于 HTTP 的服务端推送 | 远程服务连接 |\n| `Stdio` | 标准输入输出，通过子进程通信 | 本地命令行工具 |\n| `JSON Config` | JSON 格式的配置文件导入 | 批量配置导入 |\n\n### 配置表单结构\n\n```typescript\n// 配置表单状态\nconst [serverName, setServerName] = useState(\"\");\nconst [activeTab, setActiveTab] = useState<\"sse\" | \"stdio\" | \"json\">(\"sse\");\n```\n\n#### 验证规则\n\n| 字段 | 规则 | 错误提示 |\n|------|------|----------|\n| Server Name | 必填，仅允许字母和数字，最多50字符 | \"Server Name is required and can only contain letters and numbers.\" |\n| Server Name | 不可重复 | \"Server name already exists.\" |\n| Agent Name | 必填 | Agent 名称错误提示 |\n\n配置模态框支持创建和编辑两种模式：\n\n```typescript\n// 根据是否传入 server 对象判断模式\nloading={isSaving}\ndisabled={serverNameError || serverNameDuplicateError || agentNameError}\n>\n {server ? \"Update Server\" : \"Add Server\"}\n\n```\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx:1-100]()\n\n### MCP 服务器卡片\n\n服务器卡片组件展示单个服务器的概要信息：\n\n| 属性 | 说明 |\n|------|------|\n| `server.name` | 服务器名称 |\n| `server.agentDescription` | Agent 描述信息 |\n| `DESCRIPTION_CHAR_LIMIT` | 描述文本截断长度（默认2行） |\n\n```typescript\n
\n \n \n
\n```\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpServerCard.tsx:1-50]()\n\n## 计划（Plan）管理配置\n\n### 计划列表配置\n\n计划列表页面提供以下功能：\n\n```mermaid\ngraph TD\n A[计划列表页面] --> B[搜索功能]\n A --> C[创建计划]\n A --> D[导入计划]\n A --> E[计划详情模态框]\n \n B --> F[按标题搜索]\n C --> G[新建空白计划]\n D --> H[JSON 文件导入]\n E --> I[编辑/保存计划]\n```\n\n### 功能按钮配置\n\n| 操作 | 按钮图标 | 说明 |\n|------|----------|------|\n| 创建计划 | `` | 创建新的空白计划 |\n| 导入计划 | `` | 从 JSON 文件导入 |\n| 搜索 | `` | 按名称过滤计划列表 |\n\n```typescript\n\n \n\n\n\n \n\n```\n\n资料来源：[frontend/src/components/features/Plans/PlanList.tsx:1-80]()\n\n### 计划卡片配置\n\n计划卡片显示单个计划的详细信息：\n\n```typescript\ninterface Plan {\n id: string;\n task: string;\n steps: Step[];\n created_at?: string;\n}\n```\n\n| 显示区域 | 内容 |\n|----------|------|\n| 标题区 | 计划任务名称 |\n| 步骤列表 | 最多显示前3个步骤，超出显示 `+ N more steps` |\n| 时间戳 | 相对时间显示（如\"2小时前\"） |\n\n```typescript\n{steps.length > 3 && (\n
\n + {steps.length - 3} more steps\n
\n)}\n```\n\n资料来源：[frontend/src/components/features/Plans/PlanCard.tsx:1-60]()\n\n### 计划模态框配置\n\n计划编辑通过模态框进行，支持以下配置：\n\n| 配置项 | 说明 |\n|--------|------|\n| `open` | 模态框开关状态 |\n| `onCancel` | 取消回调 |\n| `footer` | 页脚配置（设为 null 隐藏） |\n| `width` | 模态框宽度（800px） |\n| `destroyOnClose` | 关闭时销毁内部状态 |\n\n```typescript\n\n handleSavePlan(updatedSteps, true)}\n />\n\n```\n\n资料来源：[frontend/src/components/features/Plans/PlanCard.tsx:60-90]()\n\n## 环境变量配置\n\n### 前端环境变量\n\n前端配置通过 `.env.development` 文件管理（基于 `.env.default` 模板）：\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `GATSBY_API_URL` | `http://localhost:8081/api` | 后端 API 地址 |\n\n### 配置步骤\n\n1. 复制 `.env.default` 为 `.env.development`\n2. 设置 `GATSBY_API_URL` 为目标后端地址\n3. 前端开发服务器默认连接 `http://localhost:8081/api`\n\n```bash\n# 设置环境变量示例\nGATSBY_API_URL=http://localhost:8081/api\n```\n\n资料来源：[frontend/README.md:1-20]()\n\n## 主题配置\n\n### 暗色模式切换\n\n应用支持暗色/亮色主题切换，通过 Ant Design 的 `ConfigProvider` 实现：\n\n```typescript\n\n
\n \n
\n\n```\n\n### 样式变量\n\n| 变量 | 说明 | 应用组件 |\n|------|------|----------|\n| `--color-bg-secondary` | 次要背景色 | 输入框、卡片 |\n| `--color-text-primary` | 主文本色 | 标题、正文 |\n| `--color-border-primary` | 边框色 | 输入框、卡片边框 |\n\n```typescript\n// 动态文本颜色示例\nconst color = darkMode === \"dark\" \n ? \"var(--color-text-primary)\" \n : \"var(--color-text-primary)\";\n```\n\n资料来源：[frontend/src/components/layout.tsx:1-30]()\n\n## API 集成\n\n### 后端路由\n\n后端提供 `/api/settings` 路由处理配置相关的 HTTP 请求：\n\n```mermaid\nsequenceDiagram\n 前端组件 >> MCPConfigModal: 保存配置\n MCPConfigModal >> fetch API: POST /api/settings\n fetch API >> 后端路由: settingsroute.py\n 后端路由 >> 数据库/存储: 持久化配置\n 数据库/存储 -->> 后端路由: 确认保存\n 后端路由 -->> MCPConfigModal: 200 OK\n```\n\n前端通过标准 Fetch API 与后端通信：\n\n```typescript\nconst response = await fetch('/api/settings', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify(settingsData),\n});\n```\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx:1-50]()\n\n## 状态持久化\n\n### LocalStorage 结构\n\n配置数据通过 Zustand 的 persist 中间件自动保存到浏览器 LocalStorage：\n\n```javascript\n// LocalStorage 中的存储键\n{\n \"configStore\": {\n \"state\": {\n \"agentFlow\": { ... },\n \"sessions\": [ ... ],\n \"messages\": [ ... ]\n },\n \"version\": 0\n }\n}\n```\n\n### 初始化流程\n\n```mermaid\ngraph TD\n A[应用启动] --> B[加载 LocalStorage]\n B --> C{存在配置数据?}\n C -->|是| D[恢复配置状态]\n C -->|否| E[使用默认配置]\n D --> F[渲染应用]\n E --> F\n```\n\n```typescript\nexport const useConfigStore = create()(\n persist(\n (set) => ({\n // 初始状态定义\n agentFlow: DEFAULT_AGENT_FLOW_SETTINGS,\n sessions: [],\n messages: [],\n // ...\n }),\n {\n name: \"configStore\", // LocalStorage 键名\n }\n )\n);\n```\n\n资料来源：[frontend/src/hooks/store.tsx:40-80]()\n\n## 最佳实践\n\n### 配置验证\n\n- MCP 服务器名称仅允许字母和数字\n- 必填字段需添加前端验证\n- 重复检测需在保存前执行\n\n### 性能优化\n\n- 使用 `destroyOnClose` 释放模态框资源\n- 计划列表支持搜索过滤避免全量渲染\n- 消息和会话数据按需加载\n\n### 安全考虑\n\n- 环境变量文件不应提交到版本控制\n- API 请求应使用 HTTPS\n- 敏感配置应加密存储\n\n---\n\n\n\n## 后端API架构\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [WebSocket实时通信](#websocket-communication), [数据管理](#data-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/magentic_ui/backend/web/app.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/app.py)\n- [src/magentic_ui/backend/web/routes/sessions.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/sessions.py)\n- [src/magentic_ui/backend/web/routes/runs.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/runs.py)\n- [src/magentic_ui/backend/web/routes/teams.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/teams.py)\n- [src/magentic_ui/backend/web/routes/plans.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/plans.py)\n- [src/magentic_ui/backend/datamodel/db.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/datamodel/db.py)\n
\n\n# 后端API架构\n\n## 概述\n\nMagentic-UI 的后端API架构是一套基于 FastAPI 构建的 RESTful API 服务，托管在 `src/magentic_ui/backend/` 目录下。该架构负责处理前端请求、管理会话状态、协调多Agent工作流、执行任务运行以及存储计划数据。API 服务默认运行在 `http://localhost:8081/api` 端点，为前端提供所有核心业务逻辑的数据支撑。\n\n## 架构分层\n\n后端采用分层架构设计，核心模块包括：\n\n| 层级 | 模块路径 | 职责说明 |\n|------|----------|----------|\n| 应用层 | `backend/web/app.py` | FastAPI 应用入口，路由注册，中间件配置 |\n| 路由层 | `backend/web/routes/` | 业务路由处理，分为 sessions、runs、teams、plans 等子模块 |\n| 数据层 | `backend/datamodel/` | 数据模型定义，数据库操作封装 |\n| 核心层 | `magentic_ui/agents/` | Agent 逻辑，工具调用，任务执行引擎 |\n\n## 核心路由模块\n\n### 会话管理路由 (`sessions`)\n\n会话路由负责管理用户会话的生命周期，涵盖创建、读取、更新、删除等操作。每个会话包含任务上下文、消息历史和关联的运行记录。\n\n| 端点类型 | 功能描述 |\n|----------|----------|\n| `GET /sessions` | 获取会话列表 |\n| `POST /sessions` | 创建新会话 |\n| `GET /sessions/{id}` | 获取指定会话详情 |\n| `PUT /sessions/{id}` | 更新会话信息 |\n| `DELETE /sessions/{id}` | 删除会话 |\n\n### 运行管理路由 (`runs`)\n\n运行路由处理任务执行相关操作，管理和追踪任务的执行状态。运行状态包括 `active`、`paused`、`awaiting_input` 等多种状态。\n\n### 团队协作路由 (`teams`)\n\n团队路由支持多Agent协作场景，管理团队配置、成员交互和任务分配。Web Surfer Agent 等组件通过此模块与其他Agent进行通信。\n\n### 计划管理路由 (`plans`)\n\n计划路由处理可复用计划的创建、存储和检索。计划包含步骤列表和任务描述，支持从对话中学习生成新计划。\n\n## 数据模型\n\n后端数据模型定义在 `backend/datamodel/db.py` 中，采用结构化数据格式存储关键业务实体。\n\n```mermaid\nerDiagram\n Session ||--o{ Run : contains\n Session {\n string id\n string task\n datetime created_at\n array messages\n }\n Run ||--o| TeamResult : produces\n Run {\n string id\n string session_id\n string status\n string error_message\n InputRequest input_request\n }\n Plan ||--o{ Step : contains\n Plan {\n string id\n string task\n array steps\n datetime created_at\n }\n TeamResult {\n string task_result\n string stop_reason\n }\n```\n\n## API 通信流程\n\n前端与后端通过 JSON 格式进行数据交换，采用 HTTP 请求-响应模式。\n\n```mermaid\nsequenceDiagram\n participant FE as 前端组件\n participant API as FastAPI Backend\n participant DB as 数据库\n participant Agent as Agent Engine\n \n FE->>API: HTTP Request (POST /runs)\n API->>DB: 存储会话上下文\n API->>Agent: 分发任务\n Agent-->>API: 运行状态更新\n API-->>FE: SSE/Polling 响应\n Agent->>DB: 持久化结果\n```\n\n## 任务执行状态机\n\n任务运行遵循严格的状态转换规则：\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: 创建任务\n pending --> active: 开始执行\n active --> paused: 用户暂停\n paused --> active: 恢复执行\n active --> awaiting_input: 请求用户输入\n awaiting_input --> active: 用户响应\n active --> completed: 任务完成\n active --> failed: 执行错误\n completed --> [*]\n failed --> [*]\n```\n\n## 前端集成\n\n前端通过环境变量配置后端地址：\n\n```bash\n# .env.development\nGATSBY_API_URL=http://localhost:8081/api\n```\n\n前端状态管理（`hooks/store.tsx`）维护以下核心状态：\n\n| 状态键 | 类型 | 用途 |\n|--------|------|------|\n| `messages` | array | 当前会话消息列表 |\n| `session` | object | 当前会话对象 |\n| `sessions` | array | 所有会话列表 |\n| `version` | string | API 版本信息 |\n| `connectionId` | uuid | 连接唯一标识 |\n\n## Web Surfer Agent 交互\n\nWeb Surfer Agent 通过专用工具集与浏览器交互，相关工具定义在 `agents/web_surfer/fara/_prompts.py` 中。支持的浏览器操作包括：\n\n| 操作类型 | 功能说明 |\n|----------|----------|\n| `visit_url` | 访问指定URL |\n| `web_search` | 执行网络搜索 |\n| `key` | 模拟键盘按键 |\n| `type` | 输入文本内容 |\n| `mouse_move` | 移动鼠标指针 |\n| `left_click` | 左键点击 |\n| `scroll` | 页面滚动 |\n| `history_back` | 返回历史页面 |\n| `wait` | 等待指定秒数 |\n\n## MCP 服务器配置\n\n后端支持 MCP（Model Context Protocol）服务器集成，允许扩展 Agent 能力。配置通过 `McpConfigModal` 组件进行，支持三种连接方式：\n\n| 连接模式 | 协议类型 | 使用场景 |\n|----------|----------|----------|\n| SSE | Server-Sent Events | 实时单向数据流 |\n| Stdio | 标准输入输出 | 本地进程通信 |\n| JSON Config | JSON配置文件 | 批量配置导入 |\n\n## 安全与限制\n\n后端实现了基础的安全检查机制：\n\n- 会话访问权限验证\n- 用户代理类型过滤\n- 浏览器环境隔离选项\n- Docker 容器运行支持\n\n## 技术栈\n\n| 组件 | 技术选型 |\n|------|----------|\n| Web 框架 | FastAPI |\n| 数据验证 | Pydantic |\n| 数据库 | SQLite (默认) |\n| 异步任务 | Asyncio |\n| API 文档 | OpenAPI/Swagger |\n\n## 扩展指南\n\n### 添加新路由\n\n1. 在 `backend/web/routes/` 创建新的路由文件\n2. 定义 Pydantic 模型用于请求/响应验证\n3. 在 `app.py` 中注册路由\n4. 更新前端 API 客户端调用\n\n### 自定义 Agent\n\nAgent 逻辑定义在 `magentic_ui/agents/` 目录，通过注册机制集成到主应用。新的 Agent 需要实现标准的工具接口以保持兼容性。\n\n---\n\n*本页面内容基于 Magentic-UI 仓库源码自动生成，如有问题请提交 Issue。*\n\n---\n\n\n\n## WebSocket实时通信\n\n### 相关页面\n\n相关主题：[后端API架构](#backend-api), [代理系统详解](#agent-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/magentic_ui/backend/web/managers/connection.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/managers/connection.py)\n- [src/magentic_ui/backend/web/app.py](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/app.py)\n- [frontend/src/components/views/manager.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/manager.tsx)\n- [frontend/src/components/store.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/store.tsx)\n- [frontend/src/components/views/chat/chat.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/chat.tsx)\n
\n\n# WebSocket实时通信\n\n## 概述\n\nWebSocket实时通信是Magentic-UI实现前端与后端双向实时数据交互的核心机制。该系统基于FastAPI的WebSocket框架构建，支持任务执行状态推送、实时消息流转、用户输入响应等关键功能。\n\nWebSocket连接使前端UI能够接收后端Agent任务的实时更新，包括步骤进度、运行状态、输入请求等，同时允许用户中断任务或提供额外输入。资料来源：[src/magentic_ui/backend/web/managers/connection.py:1-50]()\n\n## 架构设计\n\n### 系统组件架构\n\n```mermaid\ngraph TD\n FE[前端 UI] <--> WS[WebSocket 连接]\n WS <--> CM[连接管理器
ConnectionManager]\n CM <--> TM[任务管理器]\n CM <--> IR[输入响应队列
_input_responses]\n WS <--> MSG[消息处理器]\n \n subgraph 后端服务\n CM\n TM\n IR\n MSG\n end\n \n subgraph 前端组件\n FE\n ChatView\n SessionManager\n store\n end\n```\n\n### 核心组件职责\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| ConnectionManager | 管理所有WebSocket连接生命周期 | connection.py |\n| 输入响应队列 | 存储用户输入响应 | connection.py |\n| ChatView | 前端聊天视图，渲染实时消息 | chat.tsx |\n| SessionManager | 会话管理，分配WebSocket | manager.tsx |\n\n资料来源：[src/magentic_ui/backend/web/managers/connection.py:1-30]()\n\n## 连接管理\n\n### ConnectionManager 类\n\nConnectionManager是后端WebSocket通信的核心管理类，负责维护连接状态、处理消息路由和任务流管理。\n\n```python\nclass ConnectionManager:\n def __init__(self):\n self._connections: dict[int, WebSocket] = {}\n self._closed_connections: set[int] = set()\n self._input_responses: dict[int, asyncio.Queue] = {}\n```\n\n**核心属性说明：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `_connections` | dict[int, WebSocket] | 存储活跃的WebSocket连接，键为run_id |\n| `_closed_connections` | set[int] | 已关闭的连接ID集合 |\n| `_input_responses` | dict[int, Queue] | 用户输入响应队列 |\n\n资料来源：[src/magentic_ui/backend/web/managers/connection.py:1-20]()\n\n### 连接建立流程\n\n```mermaid\nsequenceDiagram\n participant 前端\n participant WebSocket\n participant CM as ConnectionManager\n participant 任务流\n \n 前端->>WebSocket: 建立连接\n WebSocket->>CM: connect(websocket, run_id)\n CM->>CM: 接受WebSocket连接\n CM->>CM: 初始化输入队列\n CM-->>前端: 发送系统消息
{type: \"system\", status: \"connected\"}\n 任务流-->>CM: 推送任务状态\n CM-->>前端: 实时状态更新\n```\n\n**connect方法实现：**\n\n```python\nasync def connect(self, websocket: WebSocket, run_id: int) -> bool:\n try:\n await websocket.accept()\n self._connections[run_id] = websocket\n self._closed_connections.discard(run_id)\n # 初始化输入队列\n self._input_responses[run_id] = asyncio.Queue()\n \n await self._send_message(\n run_id,\n {\n \"type\": \"system\",\n \"status\": \"connected\",\n \"timestamp\": datetime.now(timezone.utc).isoformat(),\n },\n )\n return True\n except Exception as e:\n logger.error(f\"连接错误 run {run_id}: {e}\")\n return False\n```\n\n资料来源：[src/magentic_ui/backend/web/managers/connection.py:40-65]()\n\n## 消息协议\n\n### 消息类型定义\n\n系统定义了多种WebSocket消息类型，用于区分不同的通信目的：\n\n| 消息类型 | 方向 | 说明 |\n|----------|------|------|\n| `system` | 后端→前端 | 系统状态消息，如连接成功 |\n| `status` | 后端→前端 | 任务运行状态更新 |\n| `stop` | 前端→后端 | 用户请求停止任务 |\n| `input_response` | 后端→前端 | 请求用户输入 |\n| `text` | 双向 | 文本消息内容 |\n\n### 状态消息结构\n\n```python\n{\n \"type\": \"system\",\n \"status\": \"connected\",\n \"timestamp\": \"2024-01-01T00:00:00+00:00\"\n}\n```\n\n### 任务停止消息格式\n\n前端通过WebSocket发送停止请求：\n\n```python\nws.send(\n JSON.stringify({\n \"type\": \"stop\",\n \"reason\": \"Cancelled by user (sidebar)\",\n })\n);\n```\n\n资料来源：[frontend/src/components/views/manager.tsx:1-30]()\n\n## 任务流启动\n\n### start_stream 方法\n\nstart_stream是启动任务执行流的核心方法，协调连接管理与任务执行：\n\n```python\nasync def start_stream(\n self,\n run_id: int,\n task: str | ChatMessage | Sequence[ChatMessage] | None,\n team_config: Dict[str, Any],\n settings_config: Dict[str, Any],\n user_settings: Settings | None = None,\n) -> None:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| run_id | int | 任务运行ID |\n| task | str/ChatMessage/Sequence | 要执行的任务内容 |\n| team_config | Dict | Agent团队配置 |\n| settings_config | Dict | 设置配置 |\n| user_settings | Settings | 用户设置（可选） |\n\n资料来源：[src/magentic_ui/backend/web/managers/connection.py:67-85]()\n\n## 前端集成\n\n### WebSocket初始化\n\n前端在SessionManager中管理WebSocket连接：\n\n```typescript\nconst getSessionSocket = (\n sessionId: number,\n runId: string,\n fresh_socket: boolean,\n only_retrieve_existing_socket: boolean\n): WebSocket | null\n```\n\n**获取Socket流程：**\n\n1. 检查是否需要新建Socket\n2. 如果需要，返回新WebSocket实例\n3. 否则返回现有连接或null\n\n资料来源：[frontend/src/components/views/chat/chat.tsx:1-30]()\n\n### 状态更新处理\n\n前端通过runStatusChange回调接收运行状态变化：\n\n```typescript\nonRunStatusChange: (sessionId: number, status: BaseRunStatus) => void\n```\n\n**状态流转：**\n\n```mermaid\ngraph LR\n A[pending] --> B[running]\n B --> C[awaiting_input]\n C --> B\n B --> D[paused]\n D --> B\n B --> E[completed]\n B --> F[stopped]\n B --> G[error]\n```\n\n资料来源：[frontend/src/components/views/manager.tsx:30-50]()\n\n### 前端状态存储\n\n使用Zustand管理WebSocket相关状态：\n\n```typescript\nconst useConfigStore = create()(\n persist(\n (set) => ({\n connectionId: uuidv4(),\n sessions: [],\n setSessions: (sessions) => set({ sessions }),\n // ...\n })\n )\n);\n```\n\n资料来源：[frontend/src/components/store.tsx:1-40]()\n\n## API端点\n\n### WebSocket路由配置\n\n在FastAPI应用中注册WebSocket路由：\n\n```python\napi.include_router(\n ws.router,\n prefix=\"/ws\",\n tags=[\"websocket\"],\n responses={404: {\"description\": \"Not found\"}},\n)\n```\n\n### 静态文件服务\n\nWebSocket连接基于API前缀`/api/ws`，而后端同时挂载了静态文件目录用于前端资源服务：\n\n```python\napp.mount(\"/api\", api)\napp.mount(\n \"/files\",\n StaticFiles(directory=initializer.static_root, html=True),\n name=\"files\",\n)\napp.mount(\"/\", StaticFiles(directory=initializer.ui_root, html=True), name=\"ui\")\n```\n\n资料来源：[src/magentic_ui/backend/web/app.py:50-70]()\n\n## 数据流\n\n### 实时消息流\n\n```mermaid\ngraph LR\n subgraph 用户交互\n U[用户输入]\n U2[停止请求]\n end\n \n subgraph 前端\n CI[ChatInput]\n SM[SessionManager]\n end\n \n subgraph 后端\n WS[WebSocket]\n CM[ConnectionManager]\n AG[Agent]\n end\n \n U --> CI --> WS --> CM --> AG\n U2 --> SM --> WS --> CM\n AG --> CM --> WS --> SM --> CI\n```\n\n### 会话Socket管理\n\n前端为每个会话维护独立的WebSocket连接，通过runId进行标识：\n\n```typescript\nconst sessionSockets: Record = {};\n\n// 停止会话时关闭对应Socket\nconst ws = sessionSockets[id]?.socket;\nif (ws && ws.readyState === WebSocket.OPEN) {\n ws.send(\n JSON.stringify({\n type: \"stop\",\n reason: \"Cancelled by user (sidebar)\",\n })\n );\n ws.close();\n}\n```\n\n资料来源：[frontend/src/components/views/manager.tsx:10-25]()\n\n## 错误处理\n\n### 连接错误处理\n\n```python\ntry:\n await websocket.accept()\n self._connections[run_id] = websocket\n # ...\nexcept Exception as e:\n logger.error(f\"连接错误 for run {run_id}: {e}\")\n return False\n```\n\n### 内部错误处理器\n\n```python\n@app.exception_handler(500)\nasync def internal_error_handler(request: Request, exc: Exception):\n logger.error(f\"内部错误: {str(exc)}\")\n return {\n \"status\": False,\n \"message\": \"服务器内部错误\",\n \"detail\": str(exc) if # ...\n }\n```\n\n资料来源：[src/magentic_ui/backend/web/managers/connection.py:60-65]()\n\n## 配置说明\n\n### 环境变量配置\n\n前端WebSocket连接地址通过环境变量配置：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `GATSBY_API_URL` | 后端API地址 | http://localhost:8081/api |\n| `GATSBY_WS_URL` | WebSocket地址 | 与API地址相同 |\n\n开发环境配置示例：\n\n```bash\n# .env.development\nGATSBY_API_URL=http://localhost:8081/api\n```\n\n资料来源：[frontend/README.md:1-20]()\n\n## 最佳实践\n\n1. **连接复用**：同一会话的多个任务应尽可能复用现有WebSocket连接\n2. **状态同步**：前端应根据WebSocket推送的状态消息更新本地状态\n3. **错误恢复**：实现重连机制以处理网络波动导致的连接断开\n4. **输入队列**：每个连接维护独立的输入响应队列，避免消息混淆\n\n## 总结\n\nWebSocket实时通信是Magentic-UI实现流畅用户体验的关键基础设施。通过ConnectionManager的统一管理，系统实现了可靠的连接生命周期管理、任务状态推送和用户交互响应。前端组件与后端服务通过标准化的消息协议进行通信，确保了系统的可维护性和扩展性。\n\n---\n\n\n\n## 数据管理\n\n### 相关页面\n\n相关主题：[后端API架构](#backend-api)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [frontend/src/components/features/Plans/PlanCard.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanCard.tsx)\n- [frontend/src/components/features/Plans/PlanList.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/PlanList.tsx)\n- [frontend/src/components/features/Plans/LearnPlanButton.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/Plans/LearnPlanButton.tsx)\n- [frontend/src/components/common/filerenderer.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/common/filerenderer.tsx)\n- [frontend/src/components/views/chat/chat.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/chat.tsx)\n- [frontend/src/components/views/chat/runview.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/views/chat/runview.tsx)\n- [frontend/src/components/features/McpServersConfig/McpConfigModal.tsx](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/features/McpServersConfig/McpConfigModal.tsx)\n
\n\n# 数据管理\n\nMagentic-UI 的数据管理功能涵盖多个模块，包括计划（Plan）管理、文件管理、会话管理和 MCP 服务器配置管理。这些模块共同构成了系统的核心数据层，支持用户创建、存储、检索和执行各种任务计划。\n\n## 概述\n\nMagentic-UI 的数据管理架构采用前端组件与后端 API 分离的设计模式。前端使用 React 组件构建用户界面，通过 API 与后端通信进行数据持久化。主要数据管理对象包括：\n\n| 数据对象 | 功能描述 | 存储位置 |\n|---------|---------|---------|\n| Plan（计划） | 可复用的任务执行计划 | 后端数据库 |\n| File（文件） | 用户上传的文件和生成的输出 | 文件系统/数据库 |\n| Session（会话） | 用户与 AI 的交互会话 | 后端数据库 |\n| MCP Server Config | MCP 服务器连接配置 | 后端配置 |\n\n## 计划（Plan）管理\n\n计划是 Magentic-UI 的核心数据管理单元，允许用户创建、保存和执行可复用的任务模板。\n\n### 计划数据结构\n\n计划数据包含以下关键字段：\n\n- `id`: 计划唯一标识符\n- `task`: 计划标题/任务名称\n- `steps`: 执行步骤数组\n- `created_at`: 创建时间戳\n- `metadata`: 元数据信息\n\n资料来源：[frontend/src/components/features/Plans/PlanCard.tsx:1-80]()\n\n### 创建计划\n\n用户可以通过两种方式创建计划：\n\n1. **手动创建**：在 PlanCard 组件中通过 Modal 对话框手动编辑计划\n2. **从对话学习**：使用 LearnPlanButton 从成功执行的对话中提取计划\n\n```tsx\n// PlanCard.tsx 中的计划创建流程\n\n {isModalOpen && (\n
\n
\n \n setLocalTask(e.target.value)}\n onPressEnter={() => handleSavePlan(localSteps, false)}\n placeholder=\"Enter plan title\"\n />\n
\n {\n handleSavePlan(updatedSteps, true);\n }}\n />\n
\n )}\n\n```\n\n资料来源：[frontend/src/components/features/Plans/PlanCard.tsx:54-76]()\n\n### 计划列表展示\n\nPlanList 组件负责展示所有已保存的计划，支持搜索过滤功能。\n\n```tsx\n// PlanList.tsx 中的计划列表\n
\n

No plans yet. Create one or import an existing plan.

\n
\n```\n\n资料来源：[frontend/src/components/features/Plans/PlanList.tsx:1-50]()\n\n### 从对话学习计划\n\nLearnPlanButton 组件提供从当前对话会话学习并保存计划的功能：\n\n```tsx\nconst handleLearnPlan = useCallback(() => {\n if (!sessionId || !effectiveUserId) return;\n // 调用保存计划 API\n};\n\nreturn (\n \n \n \n Learn Plan\n \n \n);\n```\n\n资料来源：[frontend/src/components/features/Plans/LearnPlanButton.tsx:1-60]()\n\n### 附加计划到查询\n\n用户可以将现有计划附加到新的查询中，在 chatinput.tsx 中通过下拉菜单选择：\n\n```tsx\n\n {allPlans.length === 0 ? (\n \n No plans available\n \n ) : (\n allPlans.map((plan: any) => (\n handleUsePlan(plan)}\n >\n {plan.task}\n \n ))\n )}\n\n```\n\n资料来源：[frontend/src/components/views/chat/chatinput.tsx:1-100]()\n\n### 计划执行流程\n\n```mermaid\ngraph TD\n A[用户输入任务] --> B{是否附加计划?}\n B -->|是| C[选择已有计划]\n B -->|否| D[创建新计划]\n C --> E[执行计划步骤]\n D --> F[手动创建/学习计划]\n F --> E\n E --> G[显示执行进度]\n G --> H{步骤结果}\n H -->|需要用户输入| I[暂停等待输入]\n H -->|完成| J[任务结束]\n I --> E\n```\n\n## 文件管理\n\nMagentic-UI 支持文件上传、存储和展示功能。\n\n### 文件渲染组件\n\nRenderFile 组件负责解析和展示消息中的文件：\n\n```tsx\nconst RenderFile: React.FC = ({ message }) => {\n const [files, setFiles] = useState([]);\n const [selectedFile, setSelectedFile] = useState(null);\n const [fileContent, setFileContent] = useState(null);\n\n useEffect(() => {\n // 从消息元数据中提取文件信息\n if (message?.metadata?.type === \"file\" && message?.metadata?.files) {\n const parsedFiles = JSON.parse(message.metadata.files);\n // 处理文件以确保正确的类型检测\n }\n }, []);\n};\n```\n\n资料来源：[frontend/src/components/common/filerenderer.tsx:1-100]()\n\n### 文件卡片展示\n\nFileCard 组件提供文件的可视化展示：\n\n```tsx\n\n \n
\n \n {file.name}\n \n
\n \n\n```\n\n资料来源：[frontend/src/components/common/filerenderer.tsx:100-150]()\n\n### 文件上传流程\n\n文件上传通过 Upload 组件集成在聊天输入框中：\n\n```tsx\n\n \n \n \n Attach File\n \n \n\n```\n\n资料来源：[frontend/src/components/views/chat/chatinput.tsx:100-150]()\n\n## MCP 服务器配置管理\n\nMCP（Model Context Protocol）服务器配置允许用户管理外部服务连接。\n\n### 配置类型\n\nMcpConfigModal 支持三种配置方式：\n\n| 配置类型 | 描述 | 使用场景 |\n|---------|------|---------|\n| SSE | Server-Sent Events | 实时数据流服务 |\n| Stdio | 标准输入输出 | 本地进程通信 |\n| JSON Config | JSON 配置文件 | 批量配置导入 |\n\n```tsx\n\n```\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx:1-80]()\n\n### 配置验证\n\n服务器名称验证规则：\n\n```tsx\n\n \n\n```\n\n资料来源：[frontend/src/components/features/McpServersConfig/McpConfigModal.tsx:50-70]()\n\n## 会话管理\n\n会话数据记录用户与 AI 的完整交互历史。\n\n### 会话消息处理\n\nRunView 组件负责渲染会话消息：\n\n```tsx\n