{
"canonical_name": "hangwin/mcp-chrome",
"compilation_id": "pack_6796b084cc164357bab97b658b99fb40",
"created_at": "2026-05-13T12:03:03.495114+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, 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 mcp-chrome-bridge` 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 mcp-chrome-bridge",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_1a65d5bed20b442b96b8d64c89709e37"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_ab38dd86b62d6e551031fd52eb98cdcc",
"canonical_name": "hangwin/mcp-chrome",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/hangwin/mcp-chrome",
"slug": "mcp-chrome",
"source_packet_id": "phit_97e77b470a2841a9a4e0566988aa9539",
"source_validation_id": "dval_a6d83c5a87334dad90fad29e067b04a9"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 1044,
"github_stars": 11608,
"one_liner_en": "Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.",
"one_liner_zh": "Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "mcp-chrome",
"title_zh": "mcp-chrome 能力包",
"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": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"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_97e77b470a2841a9a4e0566988aa9539",
"page_model": {
"artifacts": {
"artifact_slug": "mcp-chrome",
"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 mcp-chrome-bridge",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/hangwin/mcp-chrome#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ba76885913a744f0832665f5c62d0f1d | https://github.com/hangwin/mcp-chrome/issues/321 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_4ac5f778b292489482bfdb7953190f96 | https://github.com/hangwin/mcp-chrome/issues/319 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_559f34b86ade48e598dac510e9341b9e | https://github.com/hangwin/mcp-chrome/issues/339 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：mcp-chrome-bridge 无法使用",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5f19fb6526174af2abe5c1eab67e25ff | https://github.com/hangwin/mcp-chrome/issues/333 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：mcp-chrome-bridge 无法使用",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_2b32536c95a7456788ba78e1fc705116 | https://github.com/hangwin/mcp-chrome/issues/342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.6",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_035dffafcbe64f4ea112f20258430e71 | https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.0.6",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | 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:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：issue",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_82ad93635a5e4ff5aeb2b35e36cbd02e | https://github.com/hangwin/mcp-chrome/issues/330 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：issue",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | 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:998796026 | https://github.com/hangwin/mcp-chrome | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 15 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 17,
"forks": 1044,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 11608
},
"source_url": "https://github.com/hangwin/mcp-chrome",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.",
"title": "mcp-chrome 能力包",
"trial_prompt": "# mcp-chrome - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-chrome 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想把一个主题变成可发布的内容方案，并判断标题、结构和转化路径。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. chrome-extension-structure：Chrome 扩展架构。围绕“Chrome 扩展架构”模拟一次用户任务，不展示安装或运行结果。\n5. native-server-architecture：本地服务器架构。围绕“本地服务器架构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. chrome-extension-structure\n输入：用户提供的“Chrome 扩展架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. native-server-architecture\n输入：用户提供的“本地服务器架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / chrome-extension-structure：Step 4 必须围绕“Chrome 扩展架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / native-server-architecture：Step 5 必须围绕“本地服务器架构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/hangwin/mcp-chrome\n- https://github.com/hangwin/mcp-chrome#readme\n- README.md\n- README_zh.md\n- app/chrome-extension/package.json\n- app/native-server/package.json\n- app/native-server/install.md\n- docs/ARCHITECTURE.md\n- docs/ARCHITECTURE_zh.md\n- app/chrome-extension/entrypoints/background/index.ts\n- app/native-server/src/index.ts\n- app/chrome-extension/entrypoints/content.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-chrome 的核心服务。\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: 🐛 Status indicator stuck on yellow - Service shows as \"not started\" afte（https://github.com/hangwin/mcp-chrome/issues/342）；github/github_issue: Bug: Singleton McpServer causes 'Already connected to a transport' on HT（https://github.com/hangwin/mcp-chrome/issues/321）；github/github_issue: Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed t（https://github.com/hangwin/mcp-chrome/issues/319）；github/github_issue: Codex CLI setup guide still points to ~/.codex/config.json and a port-on（https://github.com/hangwin/mcp-chrome/issues/339）；github/github_issue: mcp-chrome-bridge 无法使用（https://github.com/hangwin/mcp-chrome/issues/333）；github/github_issue: issue（https://github.com/hangwin/mcp-chrome/issues/330）；github/github_release: v0.0.6（https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "🐛 Status indicator stuck on yellow - Service shows as \"not started\" afte",
"url": "https://github.com/hangwin/mcp-chrome/issues/342"
},
{
"kind": "github_issue",
"source": "github",
"title": "Bug: Singleton McpServer causes 'Already connected to a transport' on HT",
"url": "https://github.com/hangwin/mcp-chrome/issues/321"
},
{
"kind": "github_issue",
"source": "github",
"title": "Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed t",
"url": "https://github.com/hangwin/mcp-chrome/issues/319"
},
{
"kind": "github_issue",
"source": "github",
"title": "Codex CLI setup guide still points to ~/.codex/config.json and a port-on",
"url": "https://github.com/hangwin/mcp-chrome/issues/339"
},
{
"kind": "github_issue",
"source": "github",
"title": "mcp-chrome-bridge 无法使用",
"url": "https://github.com/hangwin/mcp-chrome/issues/333"
},
{
"kind": "github_issue",
"source": "github",
"title": "issue",
"url": "https://github.com/hangwin/mcp-chrome/issues/330"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.0.6",
"url": "https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6"
}
],
"status": "已收录 7 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.",
"effort": "安装已验证",
"forks": 1044,
"icon": "link",
"name": "mcp-chrome 能力包",
"risk": "可发布",
"slug": "mcp-chrome",
"stars": 11608,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/hangwin/mcp-chrome 项目说明书\n\n生成时间：2026-05-13 11:45:57 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [快速开始](#quick-start)\n- [系统架构设计](#architecture)\n- [Chrome 扩展架构](#chrome-extension-structure)\n- [本地服务器架构](#native-server-architecture)\n- [浏览器工具集](#browser-tools)\n- [录制回放系统 (V3)](#record-replay-v3)\n- [可视化编辑器](#visual-editor)\n- [语义搜索与向量数据库](#semantic-search)\n- [AI Agent 集成](#agent-integration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [系统架构设计](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n- [app/chrome-extension/entrypoints/welcome/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/welcome/index.html)\n- [app/chrome-extension/entrypoints/builder/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/builder/index.html)\n- [app/chrome-extension/entrypoints/sidepanel/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/index.html)\n- [app/chrome-extension/entrypoints/popup/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/popup/index.html)\n- [app/chrome-extension/entrypoints/options/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/options/index.html)\n- [app/chrome-extension/utils/indexeddb-client.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/indexeddb-client.ts)\n- [app/chrome-extension/utils/lru-cache.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/lru-cache.ts)\n \n\n# 项目介绍\n\n## 概述\n\nmcp-chrome 是一个基于 Chrome 扩展实现的 **MCP (Model Context Protocol) Server**，它将 Chrome 浏览器的控制能力以标准化的工具接口暴露给 AI 助手使用。通过这个项目，AI 可以直接操控浏览器完成网页自动化、网页内容提取、用户脚本管理等多种复杂任务。资料来源：[README.md]()\n\n### 核心特性\n\n| 特性 | 描述 |\n|------|------|\n| MCP 协议支持 | 遵循 Model Context Protocol 标准，与各类 AI 助手无缝集成 |\n| 浏览器完全控制 | 提供标签页管理、导航控制、截图等完整功能 |\n| 工作流自动化 | 支持录制、回放自定义浏览器操作工作流 |\n| 网页内容分析 | AI 语义搜索、HTML 内容提取、交互元素识别 |\n| 网络监控 | 支持 webRequest 和 Debugger API 进行网络请求分析 |\n\n资料来源：[README.md]()\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"AI 助手层\"\n AI[AI Assistant]\n end\n \n subgraph \"MCP 协议层\"\n MCP[MCP Server]\n end\n \n subgraph \"Chrome 扩展层\"\n subgraph \"后台脚本\"\n BG[Background Script]\n RR[Record-Replay Engine]\n end\n \n subgraph \"入口点\"\n POP[Popup]\n SP[Side Panel]\n BLD[Builder]\n WEL[Welcome]\n OPT[Options]\n end\n \n subgraph \"注入脚本\"\n EM[Element Marker]\n WF[Web Fetcher]\n end\n end\n \n subgraph \"浏览器 API 层\"\n TABS[Chrome Tabs API]\n NR[Network APIs]\n DB[IndexedDB]\n end\n \n AI --> MCP\n MCP --> BG\n BG --> RR\n BG --> TABS\n BG --> NR\n BG --> DB\n POP --> BG\n SP --> BG\n BLD --> BG\n EM --> WF\n WF --> TABS\n```\n\n### 扩展入口点架构\n\n项目定义了多个独立的扩展入口点，每个入口点对应不同的用户界面和功能场景。资料来源：[app/chrome-extension/entrypoints/welcome/index.html]()、[app/chrome-extension/entrypoints/sidepanel/index.html]()、[app/chrome-extension/entrypoints/builder/index.html]()\n\n| 入口点 | 类型 | 功能描述 |\n|--------|------|----------|\n| welcome | unlisted_page | 欢迎页面，Chrome MCP Server 启动引导 |\n| sidepanel | side_panel | 工作流管理侧边栏 |\n| builder | unlisted_page | 工作流编辑器，支持拖拽式工作流设计 |\n| popup | browser_action | 浏览器动作弹出窗口 |\n| options | options_page | Userscripts 脚本管理器 |\n| offscreen | offscreen | 后台离屏文档，用于音频播放等后台任务 |\n\n资料来源：[app/chrome-extension/entrypoints/popup/index.html]()、[app/chrome-extension/entrypoints/options/index.html]()、[app/chrome-extension/entrypoints/offscreen/index.html]()\n\n---\n\n## 工具功能体系\n\n### 浏览器控制工具\n\n项目提供 6 个浏览器控制类工具，覆盖标签页管理、导航控制、脚本注入等场景。资料来源：[README.md]()\n\n| 工具名称 | 功能 | 输入参数 |\n|----------|------|----------|\n| chrome_manage_tabs | 打开、创建、重新加载标签页 | action, url, tabId |\n| chrome_viewport_control | 控制视口缩放和滚动 | zoom, scrollX, scrollY |\n| chrome_switch_tab | 切换当前活动标签页 | tabId |\n| chrome_close_tabs | 关闭指定标签页或窗口 | tabIds, windowId |\n| chrome_go_back_or_forward | 浏览器导航前进/后退 | direction |\n| chrome_inject_script | 向网页注入内容脚本 | script |\n| chrome_send_command_to_inject_script | 向注入脚本发送命令 | command |\n\n### 交互操作工具\n\n提供 3 个用户交互模拟工具，支持模拟真实用户行为。资料来源：[README.md]()\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| chrome_click_element | 使用 CSS 选择器点击页面元素 |\n| chrome_fill_or_select | 填写表单字段或选择下拉选项 |\n| chrome_keyboard | 模拟键盘输入和快捷键组合 |\n\n### 截图与视觉工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| chrome_screenshot | 高级截图捕获，支持元素定位、全页面截图和自定义尺寸 |\n\n### 数据管理工具\n\n提供 5 个书签和历史记录管理工具。资料来源：[README.md]()\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| chrome_history | 按时间范围搜索浏览器历史记录 |\n| chrome_bookmark_search | 按关键词搜索书签 |\n| chrome_bookmark_add | 添加新书签，支持文件夹分类 |\n| chrome_bookmark_delete | 删除指定书签 |\n\n### 网络监控工具\n\n支持 4 种网络监控方式，基于 Chrome 扩展的网络 API 实现。资料来源：[README.md]()\n\n| 工具名称 | API 来源 | 功能 |\n|----------|----------|------|\n| chrome_network_capture_start/stop | webRequest API | 拦截网络请求 |\n| chrome_network_debugger_start/stop | Debugger API | 带响应体的深度调试 |\n| chrome_network_request | - | 发送自定义 HTTP 请求 |\n\n### 内容分析工具\n\n提供 4 个 AI 辅助内容分析工具。资料来源：[README.md]()\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| search_tabs_content | AI 语义搜索跨标签页内容 |\n| chrome_get_web_content | 提取网页 HTML 或文本内容 |\n| chrome_get_interactive_elements | 识别页面可点击交互元素 |\n| chrome_console | 捕获并获取浏览器控制台输出 |\n\n---\n\n## 工作流引擎\n\n### Record-Replay 架构\n\n项目包含完整的工作流录制与回放引擎，支持复杂浏览器自动化场景。引擎采用节点图结构定义工作流，通过调度器执行。资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/runners/subflow-runner.ts]()\n\n```mermaid\ngraph LR\n subgraph \"工作流定义\"\n S1[Step 节点]\n S2[Step 节点]\n E1[边 - Default]\n E2[边 - On Error]\n end\n \n subgraph \"执行引擎\"\n SCH[Scheduler]\n RUN[Subflow Runner]\n end\n \n S1 --> E1 --> S2\n S1 --> E2 --> SCH\n SCH --> RUN\n```\n\n### 节点类型与边\n\n引擎使用 `indeg` (入度) 和 `outEdges` (出边) 管理节点图结构，通过以下规则确定执行顺序：\n\n1. **根节点识别**：查找入度为 0 且非 TRIGGER 类型的节点作为首个可执行节点\n2. **边标签选择**：DEFAULT 标签表示默认执行路径，ON_ERROR 标签表示错误处理路径\n3. **迭代保护**：通过 MAX_ITERATIONS 限制最大执行次数，防止循环工作流导致的死循环\n\n资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/scheduler.ts]()\n\n### 消息分类处理\n\n引擎通过 `useAgentThreads` composable 对 AI 消息进行分类，识别不同类型的操作意图。资料来源：[app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts]()\n\n| 工具类型 | 识别规则 | 显示标签 |\n|----------|----------|----------|\n| Edit | 包含 'edit'、'apply_patch'、'patch_file' | Edit |\n| Write | 包含 'write'、'create_file' | Write |\n| Run | 'bash'、'shell'、以 'Running:'/'Ran:' 开头 | Run |\n| Grep | 'grep'、'search'、有 pattern 参数 | Grep |\n\n---\n\n## 数据存储\n\n### IndexedDB 客户端\n\n项目实现了统一的 IndexedDB 客户端封装，提供 Promise 化的数据库操作接口。资料来源：[app/chrome-extension/utils/indexeddb-client.ts]()\n\n| 方法 | 模式 | 功能 |\n|------|------|------|\n| getAll | readonly | 获取指定仓库所有数据 |\n| get | readonly | 根据 key 获取单条数据 |\n| put | readwrite | 插入或更新数据 |\n| delete | readwrite | 删除指定 key 的数据 |\n| clear | readwrite | 清空指定仓库 |\n| putMany | readwrite | 批量插入数据 |\n\n### LRU 缓存\n\n项目实现了线程安全的 LRU (Least Recently Used) 缓存模块。资料来源：[app/chrome-extension/utils/lru-cache.ts]()\n\n```typescript\nclass LRUNode {\n key: K;\n value: V;\n prev: LRUNode | null;\n next: LRUNode | null;\n frequency: number; // 访问频率\n lastAccessed: number; // 最近访问时间戳\n}\n```\n\n缓存策略结合访问频率和最近访问时间进行淘汰判定，容量默认值为 100。\n\n---\n\n## 元素标注系统\n\n### Element Marker 组件\n\nElement Marker 是一个嵌入到网页中的交互式元素选择器组件，支持两种选择模式。资料来源：[app/chrome-extension/inject-scripts/element-marker.js]()\n\n| 选择模式 | 功能 | 支持格式 |\n|----------|------|----------|\n| 单选模式 | 选择单个元素 | CSS Selector / XPath |\n| 列表模式 | 批量标注相似元素 | 仅 CSS Selector |\n\n### 选择器类型\n\n| 类型 | 示例 | 说明 |\n|------|------|------|\n| CSS Selector | `#__em_selector_type` | 通过 CSS 选择器定位 |\n| XPath | `//button[@id='submit']` | 通过 XML 路径定位 |\n\n---\n\n## Web 内容获取\n\n### Web Fetcher Helper\n\n内容提取算法基于 Readability 算法改进，通过多维度评分机制识别页面主体内容。资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js]()\n\n#### 内容评分规则\n\n| 评分因素 | 权重说明 |\n|----------|----------|\n| 标签类型 | article、section、div 等不同标签基础分不同 |\n| 段落文本长度 | 每 100 字符加 1 分，最多 3 分 |\n| 逗号分隔 | 每增加一个逗号加 1 分 |\n| 链接密度 | 高链接密度的内容会降低最终得分 |\n| 祖先节点层级 | 父节点不除、祖节点除 2、曾祖节点及以上乘 3 |\n\n#### 候选节点处理流程\n\n```mermaid\ngraph TD\n A[遍历所有节点] --> B{是否为候选内容节点?}\n B -->|是| C[初始化 Readability 分数]\n B -->|否| D[跳过]\n C --> E[计算内容分数]\n E --> F[向祖先节点累加加权分数]\n F --> G{还有祖先节点?}\n G -->|是| F\n G -->|否| H[收集所有候选节点]\n H --> I[计算最终分数]\n I --> J[按链接密度调整]\n J --> K[返回最高分节点]\n```\n\n---\n\n## 应用示例\n\n### 场景一：AI 辅助网页摘要与图表绘制\n\nAI 可以先分析当前页面内容，提取关键信息后自动控制 Excalidraw 等绘图工具生成图表。资料来源：[README.md]()\n\n**提示词示例：**\n> Help me summarize the current page content, then draw a diagram to aid my understanding.\n\n### 场景二：图像分析与复现\n\nAI 可以分析网页中的图像内容，然后结合分析结果和图像本身复制图像。资料来源：[README.md]()\n\n**流程：**\n1. 接收图像 URL\n2. 使用 content-analize 工具分析图像内容\n3. 通过 Excalidraw 工具复现图像\n\n### 场景三：浏览器自动化工作流\n\n通过录制用户操作生成工作流，实现复杂浏览器自动化任务。\n\n---\n\n## 技术栈\n\n| 层级 | 技术选型 |\n|------|----------|\n| 前端框架 | Vue 3 (Composition API) |\n| 扩展框架 | WXT (Modern Chrome Extension Framework) |\n| 协议 | Model Context Protocol (MCP) |\n| 存储 | IndexedDB |\n| 构建工具 | Vite |\n| 语言 | TypeScript |\n\n---\n\n## 快速开始\n\n### 安装步骤\n\n1. 克隆项目仓库\n2. 安装依赖：`pnpm install`\n3. 构建扩展：`pnpm build`\n4. 在 Chrome 中加载 `dist/chrome-extension` 目录\n\n### 配置 MCP Server\n\n在 AI 助手的 MCP 配置中添加以下配置：\n\n```json\n{\n \"mcpServers\": {\n \"chrome\": {\n \"command\": \"path/to/mcp-chrome-server\",\n \"args\": []\n }\n }\n}\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/package.json)\n- [app/native-server/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/package.json)\n- [app/native-server/install.md](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/install.md)\n- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n- [app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n \n\n# 快速开始\n\n本文档为 **mcp-chrome** 项目提供完整的快速上手指南，帮助你在最短时间内完成环境搭建并开始使用 Chrome MCP Server。\n\n## 项目概述\n\nmcp-chrome 是一个基于 Chrome 扩展和本地原生消息（Native Messaging）通信协议的 MCP（Model Context Protocol）服务器实现。它允许 AI 模型通过标准化的接口直接控制 Chrome 浏览器，完成网页交互、内容提取、网络监控等任务。\n\n## 系统架构\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[AI Model / Claude]\n B[MCP Client SDK]\n end\n \n subgraph \"Chrome Extension\"\n C[Side Panel UI]\n D[Background Service Worker]\n E[Content Scripts]\n end\n \n subgraph \"Native Server\"\n F[MCP Server Core]\n G[Browser Controller]\n H[Native Messaging Host]\n end\n \n subgraph \"Browser\"\n I[Chrome Browser]\n J[Extension API]\n end\n \n A --> B\n B --> C\n C --> D\n D --> E\n E --> J\n D --> H\n H --> F\n F --> G\n G --> J\n J --> I\n \n style A fill:#e1f5fe\n style I fill:#fff3e0\n style H fill:#f3e5f5\n```\n\n## 前置要求\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Node.js | ≥ 18.0.0 | 本地服务器运行环境 |\n| npm / pnpm | 最新稳定版 | 包管理工具 |\n| Chrome / Chromium | ≥ 120 | 目标浏览器 |\n| 支持的操作系统 | Windows / macOS / Linux | 完整支持三大平台 |\n\n资料来源：[app/native-server/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/package.json)\n\n## 安装步骤\n\n### 步骤 1：安装原生服务器\n\n原生服务器负责处理 AI 模型与 Chrome 浏览器之间的原生消息通信。\n\n```bash\n# 克隆项目\ngit clone https://github.com/hangwin/mcp-chrome.git\ncd mcp-chrome\n\n# 进入原生服务器目录\ncd app/native-server\n\n# 安装依赖\npnpm install\n# 或\nnpm install\n```\n\n### 步骤 2：构建项目\n\n```bash\n# 构建原生服务器\npnpm build\n\n# 构建 Chrome 扩展\ncd ../chrome-extension\npnpm install\npnpm build\n```\n\n资料来源：[app/chrome-extension/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/package.json)\n\n### 步骤 3：注册原生消息主机\n\n根据你的操作系统和浏览器，需要配置 Native Messaging Host 清单文件。\n\n#### Windows 系统\n\n```powershell\n# 用户级注册（推荐）\n.\\dist\\cli.js register --browser chrome\n\n# 或系统级注册（需要管理员权限）\n.\\dist\\cli.js register --browser chrome --system\n```\n\n#### macOS 系统\n\n```bash\n# 用户级注册\n./dist/cli.js register --browser chrome\n\n# 系统级注册（需要 sudo）\nsudo ./dist/cli.js register --browser chrome --system\n```\n\n#### Linux 系统\n\n```bash\n# 用户级注册\n./dist/cli.js register --browser chrome\n\n# 系统级注册\nsudo ./dist/cli.js register --browser chrome --system\n```\n\n资料来源：[app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n\n### 步骤 4：安装 Chrome 扩展\n\n1. 打开 Chrome，访问 `chrome://extensions/`\n2. 开启右上角的「开发者模式」\n3. 点击「加载已解压的扩展程序」\n4. 选择 `app/chrome-extension/dist` 目录\n\n## 清单文件路径配置\n\n不同平台和浏览器的 Native Messaging Host 清单文件路径如下：\n\n| 平台 | 浏览器 | 用户级路径 | 系统级路径 |\n|------|--------|------------|------------|\n| Windows | Chrome | `%APPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions\\...` | `%ProgramFiles%\\Google\\Chrome\\NativeMessagingHosts\\` |\n| Windows | Chromium | `%APPDATA%\\Chromium\\User Data\\Default\\Extensions\\...` | `%ProgramFiles%\\Chromium\\NativeMessagingHosts\\` |\n| macOS | Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` | `/Library/Google/Chrome/NativeMessagingHosts/` |\n| macOS | Chromium | `~/Library/Application Support/Chromium/NativeMessagingHosts/` | `/Library/Application Support/Chromium/NativeMessagingHosts/` |\n| Linux | Chrome | `~/.config/google-chrome/NativeMessagingHosts/` | `/etc/opt/chrome/native-messaging-hosts/` |\n| Linux | Chromium | `~/.config/chromium/NativeMessagingHosts/` | `/etc/chromium/native-messaging-hosts/` |\n\n资料来源：[app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n\n## 验证安装\n\n使用诊断命令检查安装状态：\n\n```bash\ncd app/native-server\npnpm doctor\n```\n\n诊断脚本会检查以下项目：\n\n1. **Node.js 版本** - 确认 Node 环境正确\n2. **原生服务器可执行文件** - 验证 `mcp-chrome` 可执行文件存在\n3. **清单文件** - 检查各平台 Native Messaging Host 配置\n4. **Windows 注册表**（仅 Windows）- 验证注册表项正确设置\n5. **浏览器连接** - 确认扩展与服务器可以正常通信\n\n资料来源：[app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)\n\n### 常见诊断结果\n\n| 检查项 | 状态 | 说明 |\n|--------|------|------|\n| manifest.chrome | ok | Chrome 清单文件正确 |\n| manifest.chrome | error | 清单文件不存在或配置错误 |\n| windowsRegistry | ok | 注册表项正确（仅 Windows） |\n\n## MCP 客户端配置\n\n安装完成后，在你的 MCP 客户端配置文件中添加以下配置：\n\n```json\n{\n \"mcpServers\": {\n \"chrome\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-chrome/app/native-server/dist/index.js\"]\n }\n }\n}\n```\n\n## 可用工具一览\n\n安装成功后，以下工具将自动可用：\n\n### 🌐 标签页管理（5 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_search_tabs` | 跨标签页内容语义搜索 |\n| `chrome_get_web_content` | 提取网页 HTML/文本内容 |\n| `chrome_get_interactive_elements` | 获取页面可交互元素 |\n| `chrome_console` | 获取浏览器控制台输出 |\n| `chrome_screenshot` | 页面截图（支持元素定位） |\n\n### 🔧 浏览器控制（7 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_navigate` | 导航到指定 URL |\n| `chrome_scroll` | 控制页面滚动 |\n| `chrome_viewport` | 调整视口大小 |\n| `chrome_switch_tab` | 切换浏览器标签页 |\n| `chrome_close_tabs` | 关闭指定标签页 |\n| `chrome_go_back_or_forward` | 浏览器前进/后退 |\n| `chrome_inject_script` | 注入内容脚本 |\n\n### 🎯 页面交互（3 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_click_element` | 点击页面元素（CSS 选择器） |\n| `chrome_fill_or_select` | 表单填充和选项选择 |\n| `chrome_keyboard` | 模拟键盘输入和快捷键 |\n\n### 📚 数据管理（5 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_history` | 搜索浏览器历史记录 |\n| `chrome_bookmark_search` | 搜索书签 |\n| `chrome_bookmark_add` | 添加书签 |\n| `chrome_bookmark_delete` | 删除书签 |\n\n### 🌐 网络监控（4 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_network_capture_start/stop` | 网络请求捕获（webRequest API） |\n| `chrome_network_debugger_start/stop` | 网络调试（响应体捕获） |\n| `chrome_network_request` | 发送自定义 HTTP 请求 |\n\n资料来源：[README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n\n## 安全配置\n\nChrome 扩展在生产环境中启用了以下安全策略：\n\n```json\n{\n \"cross_origin_embedder_policy\": \"require-corp\",\n \"cross_origin_opener_policy\": \"same-origin\",\n \"content_security_policy\": {\n \"extension_pages\": \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\"\n }\n}\n```\n\n开发环境下这些策略会被禁用，以允许 Vite 开发服务器的正常资源加载。\n\n资料来源：[app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n\n## 故障排除\n\n### 1. 清单文件未找到\n\n```bash\n# 自动检测并注册\npnpm run register --detect\n```\n\n### 2. 浏览器无法连接\n\n确保 Chrome 扩展已正确加载，并且原生服务器正在运行：\n\n```bash\n# 检查服务器状态\npnpm doctor\n```\n\n### 3. 权限问题（Linux/macOS）\n\n```bash\n# 确保可执行文件有运行权限\nchmod +x dist/cli.js\nchmod +x dist/index.js\n```\n\n## 下一步\n\n- 查看 [使用示例](../examples/) 了解常见场景\n- 阅读 [API 文档](../api/) 深入了解各工具的参数\n- 参考 [架构设计](../architecture/) 理解内部实现\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[Chrome 扩展架构](#chrome-extension-structure), [本地服务器架构](#native-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/ARCHITECTURE.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/ARCHITECTURE.md)\n- [docs/ARCHITECTURE_zh.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/ARCHITECTURE_zh.md)\n- [app/chrome-extension/entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)\n- [app/native-server/src/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/index.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)\n- [app/native-server/src/agent/session-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/session-service.ts)\n- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n \n\n# 系统架构设计\n\n## 概述\n\nmcp-chrome 是一个将 Chrome 浏览器与 AI 大模型深度集成的开源项目，通过 Model Context Protocol (MCP) 协议实现浏览器自动化控制与智能交互。该项目由 **Chrome 扩展端** 和 **本地服务（Native Server）端** 两大部分组成，采用主从架构设计，通过 Chrome Native Messaging 原生消息通信机制实现双向通信。\n\n**核心目标**：\n- 为 AI Agent 提供完整的浏览器控制能力\n- 支持网页内容提取、交互、截图、网络监控等操作\n- 实现跨平台的 Chrome 浏览器自动化\n\n资料来源：[docs/ARCHITECTURE_zh.md]()\n\n## 整体架构\n\n```mermaid\ngraph TB\n subgraph \"客户端层 (Client)\"\n AI_Agent[AI Agent / Claude Code]\n MCP_Client[MCP Client SDK]\n end\n\n subgraph \"本地服务层 (Native Server)\"\n MCP_Server[MCP Server]\n Session_Manager[Session Manager]\n Engine_Adapter[Engine Adapter
Claude / Codex]\n Native_Messaging[Native Messaging Host]\n end\n\n subgraph \"Chrome 扩展层 (Chrome Extension)\"\n Background_Script[Background Script]\n Sidepanel[Sidepanel UI]\n Popup[Popup UI]\n Content_Script[Content Scripts]\n Inject_Scripts[Inject Scripts]\n end\n\n subgraph \"浏览器层 (Browser)\"\n Chrome_Runtime[Chrome Runtime API]\n Tabs_Management[标签页管理]\n Network_Monitor[网络监控]\n Console[控制台捕获]\n end\n\n AI_Agent --> MCP_Client\n MCP_Client --> MCP_Server\n MCP_Server --> Session_Manager\n MCP_Server --> Engine_Adapter\n Engine_Adapter --> Native_Messaging\n Native_Messaging --> Background_Script\n Background_Script --> Content_Script\n Background_Script --> Tabs_Management\n Background_Script --> Network_Monitor\n Background_Script --> Chrome_Runtime\n Content_Script --> Inject_Scripts\n```\n\n## 核心组件\n\n### 1. 本地服务层 (Native Server)\n\n本地服务层是整个系统的核心引擎，负责处理 AI 请求、管理会话、调用浏览器扩展功能。\n\n#### 1.1 MCP Server\n\nMCP Server 是基于 Model Context Protocol 协议实现的服务端，负责接收来自 AI Agent 的请求并路由到对应的处理模块。\n\n**主要职责**：\n- 协议解析与消息编解码\n- 工具（Tools）注册与调用分发\n- 会话生命周期管理\n- 错误处理与重试机制\n\n资料来源：[app/native-server/src/index.ts]()\n\n#### 1.2 Session Manager\n\n会话管理器负责管理 AI Agent 的执行会话，包括会话状态、上下文信息、配置参数等。\n\n```typescript\ninterface SessionConfig {\n mcpServers?: Record;\n outputFormat?: Record;\n enableFileCheckpointing?: boolean;\n sandbox?: Record;\n env?: Record;\n codexConfig?: Partial;\n}\n```\n\n**关键特性**：\n- 支持多种引擎配置（Claude、Codex）\n- 会话元数据缓存（Management Info）\n- 插件和技能管理\n- 输出格式自定义\n\n资料来源：[app/native-server/src/agent/session-service.ts:1-80]()\n\n#### 1.3 Engine Adapter\n\n引擎适配器层封装了不同 AI 引擎的调用接口，目前支持 Claude 和 Codex 两种引擎。\n\n**Claude Engine 实现**：\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Engine as Claude Engine\n participant Chrome as Chrome Extension\n \n Client->>Engine: 发送消息\n Engine->>Engine: 构建消息结构\n Engine->>Chrome: dispatchToolMessage\n Chrome-->>Engine: 工具执行结果\n Engine->>Engine: 处理 content_block_stop\n Engine->>Client: 返回响应\n```\n\n**工具消息分类**：\n| 消息类型 | 说明 | 严重级别 |\n|---------|------|---------|\n| `edit` | 文件编辑操作 | error/success |\n| `run` | 命令执行操作 | error/success/info |\n| `grep` | 搜索操作 | error/info |\n| `agent` | Agent 相关操作 | error/info |\n\n资料来源：[app/native-server/src/agent/engines/claude.ts:1-80]()\n\n#### 1.4 Native Messaging Host\n\nNative Messaging Host 是 Chrome 扩展与本地服务通信的桥梁，支持跨平台的消息传递。\n\n**平台特定路径配置**：\n\n| 操作系统 | 用户级路径 | 系统级路径 |\n|---------|-----------|-----------|\n| Windows | `%APPDATA%\\Google\\Chrome\\NativeMessagingHosts\\` | `%ProgramFiles%\\Google\\Chrome\\NativeMessagingHosts\\` |\n| macOS | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` | `/Library/Google/Chrome/NativeMessagingHosts/` |\n| Linux | `~/.config/google-chrome/NativeMessagingHosts/` | `/etc/opt/chrome/native-messaging-hosts/` |\n\n**功能**：\n- 消息序列化与反序列化\n- 进程间通信管理\n- 心跳检测与断线重连\n\n资料来源：[app/native-server/src/scripts/browser-config.ts:1-100]()\n资料来源：[app/native-server/src/scripts/utils.ts:1-80]()\n\n---\n\n### 2. Chrome 扩展层\n\nChrome 扩展是系统的执行端，负责实际的浏览器操作和页面交互。\n\n#### 2.1 扩展入口点\n\n| 入口点 | 文件路径 | 功能说明 |\n|-------|---------|---------|\n| Background Script | `entrypoints/background/index.ts` | 后台服务脚本，处理 Native Messaging 通信 |\n| Sidepanel | `entrypoints/sidepanel/` | 侧边栏 UI，用于工作流管理 |\n| Popup | `entrypoints/popup/` | 浏览器工具栏弹窗 |\n| Options | `entrypoints/options/` | 扩展设置页面 |\n| Builder | `entrypoints/builder/` | 工作流编辑器 |\n| Welcome | `entrypoints/welcome/` | 欢迎页面 |\n\n资料来源：[app/chrome-extension/entrypoints/background/index.ts]()\n资料来源：[app/chrome-extension/entrypoints/sidepanel/index.html]()\n资料来源：[app/chrome-extension/entrypoints/popup/index.html]()\n\n#### 2.2 扩展配置\n\n扩展使用 WXT 框架构建，配置包括资源访问策略和内容安全策略。\n\n**Web 可访问资源**：\n```typescript\nweb_accessible_resources: [\n {\n resources: [\n '/models/*', // AI 模型文件\n '/workers/*', // Web Worker 文件\n '/inject-scripts/*' // 注入脚本\n ],\n matches: ['']\n }\n]\n```\n\n**内容安全策略（CSP）**：\n```typescript\ncontent_security_policy: {\n extension_pages: \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\"\n}\n```\n\n资料来源：[app/chrome-extension/wxt.config.ts:1-50]()\n\n#### 2.3 核心功能模块\n\n**Content Indexer（内容索引器）**\n\n内容索引器负责自动提取和索引浏览器标签页的内容，支持语义搜索功能。\n\n```mermaid\ngraph LR\n A[页面加载完成] --> B{自动索引启用?}\n B -->|是| C{语义引擎就绪?}\n C -->|是| D[延迟 2 秒]\n D --> E[提取页面内容]\n E --> F[存储索引]\n C -->|否| G[跳过]\n B -->|否| G\n```\n\n**URL 过滤规则**：\n```typescript\nconst excludePatterns = [\n /^chrome:\\/\\//,\n /^chrome-extension:\\/\\//,\n /^edge:\\/\\//,\n /^about:/,\n /^moz-extension:\\/\\//,\n /^file:\\/\\//\n];\n```\n\n资料来源：[app/chrome-extension/utils/content-indexer.ts:1-80]()\n\n**Web Fetcher Helper（网页内容提取）**\n\n通过内容脚本注入到网页中，提取页面元数据和正文内容。\n\n**提取的元数据字段**：\n| 字段 | 来源优先级 |\n|-----|----------|\n| `title` | JSON-LD → og:title → twitter:title |\n| `byline` | JSON-LD → author → article:author |\n| `excerpt` | JSON-LD → dc:description → og:description |\n| `siteName` | JSON-LD → og:site_name |\n| `publishedTime` | JSON-LD → article:published_time |\n\n资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js:1-100]()\n\n---\n\n## 工具能力体系\n\n### 工具分类总览\n\n| 类别 | 工具数量 | 主要功能 |\n|-----|---------|---------|\n| 标签页管理 | 6 | 开关标签页、切换、导航控制 |\n| 交互操作 | 3 | 元素点击、表单填充、键盘输入 |\n| 数据管理 | 5 | 历史记录、书签增删改查 |\n| 截图视觉 | 1 | 高级截图（元素/全页/自定义尺寸） |\n| 网络监控 | 4 | Request API、Debugger API、自定义请求 |\n| 内容分析 | 4 | 语义搜索、内容提取、交互元素、控制台 |\n\n### 核心工具详解\n\n#### 网络监控工具\n\n```mermaid\ngraph TD\n A[网络监控工具] --> B[chrome_network_capture]\n A --> C[chrome_network_debugger]\n A --> D[chrome_network_request]\n \n B --> B1[webRequest API]\n B1 --> B2[无响应体]\n \n C --> C1[Debugger API]\n C1 --> C2[完整响应体]\n \n D --> D1[自定义 HTTP 请求]\n D1 --> D2[拦截响应]\n```\n\n**对比表**：\n\n| 特性 | capture | debugger | request |\n|-----|---------|----------|---------|\n| API 来源 | webRequest | Debugger | fetch |\n| 响应体 | ✗ | ✓ | ✓ |\n| 性能开销 | 低 | 高 | 中 |\n| 使用场景 | 快速记录 | 详细调试 | 自定义请求 |\n\n资料来源：[README.md]()\n资料来源：[docs/ARCHITECTURE_zh.md]()\n\n---\n\n## 通信机制\n\n### Native Messaging 通信流程\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant MCPServer as MCP Server\n participant NativeHost as Native Messaging Host\n participant Background as Background Script\n participant Content as Content Script\n participant Page as Web Page\n\n Agent->>MCPServer: MCP JSON-RPC 请求\n MCPServer->>MCPServer: 解析工具调用\n MCPServer->>NativeHost: 序列化消息\n NativeHost->>Background: Chrome.runtime.sendNativeMessage\n Background->>Background: 处理请求\n Background->>Content: chrome.tabs.sendMessage\n Content->>Page: 执行脚本\n Page-->>Content: 返回结果\n Content-->>Background: 发送结果\n Background-->>NativeHost: 返回响应\n NativeHost-->>MCPServer: 解析响应\n MCPServer-->>Agent: MCP JSON-RPC 响应\n```\n\n### 消息类型定义\n\n**工具调用消息**：\n```typescript\n{\n method: 'tools/call',\n params: {\n name: 'chrome_screenshot',\n arguments: {\n tabId: 123,\n fullPage: true\n }\n }\n}\n```\n\n**结果返回消息**：\n```typescript\n{\n method: 'tools/call/result',\n result: {\n success: true,\n data: { screenshot: 'base64...' }\n }\n}\n```\n\n资料来源：[app/native-server/src/index.ts]()\n资料来源：[app/chrome-extension/entrypoints/background/index.ts]()\n\n---\n\n## 安全策略\n\n### 权限控制\n\nChrome 扩展声明的权限范围决定了其能访问的 API 和资源：\n\n```json\n{\n \"permissions\": [\n \"tabs\",\n \"storage\",\n \"activeTab\",\n \"scripting\",\n \"nativeMessaging\",\n \"webNavigation\",\n \"webRequest\"\n ],\n \"host_permissions\": [\"\"]\n}\n```\n\n### 内容安全策略\n\n生产环境启用以下安全策略：\n\n| 策略 | 值 | 说明 |\n|-----|-----|-----|\n| `cross_origin_embedder_policy` | require-corp | 要求跨域资源支持 CORP |\n| `cross_origin_opener_policy` | same-origin | 防止跨域窗口访问 |\n| `script-src` | 'self' 'wasm-unsafe-eval' | 允许自身脚本和 WebAssembly |\n| `object-src` | 'self' | 仅允许自身对象资源 |\n| `style-src` | 'self' 'unsafe-inline' | 允许内联样式（Vite 构建） |\n\n开发环境使用 WXT 默认策略，避免阻断 dev server 资源加载。\n\n资料来源：[app/chrome-extension/wxt.config.ts:20-35]()\n\n---\n\n## 安装与配置\n\n### 本地服务安装\n\n1. **自动安装**：\n ```bash\n npx mcp-chrome-bridge install\n ```\n\n2. **注册表/Manifest 配置**：\n - Windows：写入 `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\`\n - macOS：创建 `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/`\n - Linux：创建 `~/.config/google-chrome/NativeMessagingHosts/`\n\n3. **验证安装**：\n ```bash\n mcp-chrome-bridge doctor\n ```\n\n### MCP Server 配置\n\n在 MCP 客户端配置文件中添加：\n\n```json\n{\n \"mcpServers\": {\n \"chrome\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-chrome-bridge\"]\n }\n }\n}\n```\n\n资料来源：[app/native-server/install.md]()\n\n---\n\n## 扩展组件清单\n\n| 组件类型 | 文件夹路径 | 功能说明 |\n|---------|-----------|---------|\n| 入口点 | `entrypoints/*/` | 各类型扩展页面的入口 |\n| 组件 | `components/` | Vue 组件库 |\n| 工具函数 | `utils/` | 通用工具函数 |\n| 注入脚本 | `inject-scripts/` | 注入到网页的 JavaScript |\n| 内容脚本 | `content/` | 页面内容脚本 |\n| 类型定义 | `types/` | TypeScript 类型定义 |\n\n资料来源：[app/chrome-extension/wxt.config.ts]()\n\n---\n\n## 总结\n\nmcp-chrome 采用分层架构设计，将复杂的浏览器自动化能力抽象为标准化的 MCP 工具接口：\n\n1. **Native Server 层** 处理 AI 逻辑和会话管理，通过 Native Messaging 与浏览器通信\n2. **Chrome Extension 层** 实际执行浏览器操作，包括标签页管理、网络监控、内容提取等\n3. **通信层** 基于 Chrome Native Messaging 协议实现跨进程、跨语言的可靠消息传递\n\n该架构具有良好的可扩展性，支持后续添加更多 AI 引擎适配器和浏览器工具，同时通过权限管理和 CSP 策略保障安全性。\n\n---\n\n\n\n## Chrome 扩展架构\n\n### 相关页面\n\n相关主题：[系统架构设计](#architecture), [浏览器工具集](#browser-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)\n- [app/chrome-extension/entrypoints/content.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/content.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [app/chrome-extension/common/constants.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/common/constants.ts)\n- [app/chrome-extension/entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n \n\n# Chrome 扩展架构\n\n## 概述\n\nmcp-chrome 是一个基于 Chrome 扩展的 MCP（Model Context Protocol）服务器实现，旨在为 AI 提供完整的浏览器控制能力。该扩展通过 WXT 框架构建，采用多入口点架构，涵盖后台脚本、内容脚本、侧边栏、弹出窗口等多种扩展页面类型。\n\n## 整体架构\n\n```mermaid\ngraph TB\n subgraph \"扩展页面层\"\n Popup[\"弹出窗口
popup/\"]\n Sidepanel[\"侧边栏
sidepanel/\"]\n Builder[\"工作流编辑器
builder/\"]\n Welcome[\"欢迎页
welcome/\"]\n Options[\"选项页
options/\"]\n end\n \n subgraph \"核心服务层\"\n Background[\"后台脚本
background/\"]\n Content[\"内容脚本
content.ts\"]\n end\n \n subgraph \"功能模块层\"\n RecordReplay[\"录制回放引擎
record-replay/\"]\n ContentIndexer[\"内容索引器
content-indexer.ts\"]\n ToolRegistry[\"工具注册表\"]\n TriggerEngine[\"触发器引擎\"]\n end\n \n subgraph \"注入脚本层\"\n WebFetcher[\"网页内容提取
web-fetcher-helper.js\"]\n DOMObserver[\"DOM 观察器
dom-observer.js\"]\n InjectBridge[\"注入桥接
inject-bridge.js\"]\n AccessibilityTree[\"无障碍树辅助
accessibility-tree-helper\"]\n end\n \n subgraph \"外部通信\"\n NativeServer[\"原生服务器
native-server/\"]\n MCPServer[\"MCP 服务器\"]\n end\n \n Popup --> Background\n Sidepanel --> Background\n Builder --> Background\n Options --> Background\n Background --> Content\n Background --> RecordReplay\n Background --> ContentIndexer\n Background --> ToolRegistry\n Background --> TriggerEngine\n Content --> WebFetcher\n Content --> DOMObserver\n Content --> InjectBridge\n Content --> AccessibilityTree\n Background --> NativeServer\n Background --> MCPServer\n```\n\n## 入口点架构\n\n### 入口点清单\n\n| 入口点 | 路径 | 用途 | manifest.type |\n|--------|------|------|---------------|\n| 后台脚本 | `background/index.ts` | 核心业务逻辑、MCP 协议处理 | service_worker |\n| 内容脚本 | `content.ts` | 页面交互、DOM 操作 | content_script |\n| 弹出窗口 | `popup/index.html` | 快速操作入口 | browser_action |\n| 侧边栏 | `sidepanel/index.html` | 工作流管理 | side_panel |\n| 工作流编辑器 | `builder/index.html` | 可视化工作流设计 | unlisted_page |\n| 欢迎页 | `welcome/index.html` | 用户引导 | unlisted_page |\n| 选项页 | `options/index.html` | 用户脚本管理 | - |\n\n资料来源：[wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n\n### manifest.json 配置\n\n扩展采用 WXT 框架自动生成 manifest.json，关键配置包括：\n\n```typescript\nmanifest: {\n permissions: [\n 'tabs',\n 'storage',\n 'webNavigation',\n 'webRequest',\n 'scripting',\n 'nativeMessaging'\n ],\n host_permissions: [''],\n web_accessible_resources: [\n '/models/*',\n '/workers/*',\n '/inject-scripts/*'\n ]\n}\n```\n\n## 后台脚本架构\n\n### 后台脚本职责\n\n后台脚本（Service Worker）是扩展的核心中枢，负责：\n\n1. **MCP 协议通信** - 与原生服务器建立 Native Messaging 连接\n2. **工具注册与分发** - 管理所有可用工具的定义和调用\n3. **标签页管理** - 协调多标签页间的通信\n4. **状态维护** - 管理扩展的全局状态\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP 客户端\n participant BG as 后台脚本\n participant Content as 内容脚本\n participant Tab as 目标页面\n \n MCP->>BG: 工具调用请求\n BG->>BG: 解析工具名称与参数\n BG->>Content: chrome.tabs.sendMessage\n Content->>Tab: 执行脚本注入\n Tab-->>Content: 执行结果\n Content-->>BG: 响应消息\n BG-->>MCP: JSON-RPC 响应\n```\n\n资料来源：[entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)\n\n### 工具分类体系\n\n| 类别 | 工具数量 | 功能描述 |\n|------|----------|----------|\n| 网络监控 | 4 | 请求捕获、调试、发送自定义请求 |\n| 内容分析 | 4 | 语义搜索、内容提取、元素定位、控制台捕获 |\n| 浏览器控制 | 6 | 标签管理、导航控制、视图切换 |\n| 交互操作 | 3 | 元素点击、表单填充、键盘模拟 |\n| 数据管理 | 5 | 书签管理、历史记录搜索 |\n| 截图 | 1 | 高级截图功能 |\n\n## 内容脚本架构\n\n### 内容脚本职责\n\n内容脚本运行在网页上下文中，主要负责：\n\n- 直接访问和操作页面 DOM\n- 注入用户脚本\n- 收集页面信息\n- 响应后台脚本的消息\n\n### 注入脚本层次\n\n```mermaid\ngraph TD\n Page[\"网页页面\"]\n IS[\"注入脚本层 (ISOLATED)\"]\n CS[\"内容脚本层 (ISOLATED)\"]\n \n subgraph \"内容脚本\"\n InjectBridge[\"inject-bridge.js\"]\n AccessibilityTree[\"accessibility-tree-helper\"]\n end\n \n subgraph \"注入脚本\"\n WebFetcher[\"web-fetcher-helper.js\"]\n DOMObserver[\"dom-observer.js\"]\n end\n \n Page --> IS\n IS --> WebFetcher\n IS --> DOMObserver\n Page --> CS\n CS --> InjectBridge\n CS --> AccessibilityTree\n```\n\n### Web Fetcher 辅助脚本\n\n`web-fetcher-helper.js` 负责从网页中提取结构化数据：\n\n```javascript\n// 元数据提取流程\nmetadata.title // 从 JSON-LD、Open Graph、Twitter Card 获取\nmetadata.byline // 作者信息\nmetadata.excerpt // 文章摘要\nmetadata.siteName // 网站名称\nmetadata.publishedTime // 发布时间\n```\n\n支持的元数据源优先级：\n1. JSON-LD 结构化数据\n2. Open Graph 标签 (`og:*`)\n3. Twitter Card 标签 (`twitter:*`)\n4. Dublin Core 标签 (`dc:*`, `dcterm:*`)\n5. 通用 meta 标签\n\n资料来源：[inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n\n## 内容索引系统\n\n### ContentIndexer 模块\n\n`content-indexer.ts` 实现了自动化的标签页内容索引功能：\n\n```typescript\nclass ContentIndexer {\n private options: {\n autoIndex: boolean; // 是否自动索引\n maxContentLength: number; // 最大内容长度\n }\n \n // 核心方法\n indexTabContent(tabId: number): Promise\n removeTabIndex(tabId: number): Promise\n shouldIndexUrl(url: string): boolean\n extractTabContent(tabId): Promise<{ textContent, title }>\n}\n```\n\n### URL 过滤规则\n\n以下 URL 模式被排除在索引之外：\n\n| 模式 | 说明 |\n|------|------|\n| `chrome://*` | Chrome 内部页面 |\n| `chrome-extension://*` | 扩展页面 |\n| `edge://*` | Edge 内部页面 |\n| `about:*` | about 协议页面 |\n| `moz-extension://*` | Firefox 扩展页面 |\n| `file:///*` | 本地文件 |\n\n### 索引触发时机\n\n```mermaid\ngraph LR\n A[\"页面加载完成
status=complete\"] --> B{自动索引开启?}\n B -->|是| C{语义引擎就绪?}\n B -->|否| D[\"跳过\"]\n C -->|是| E[\"延迟 2 秒\"]\n C -->|否| D\n E --> F[\"执行索引\"]\n F --> G[\"存储索引数据\"]\n \n H[\"标签页关闭\"] --> I[\"移除索引\"]\n \n J[\"页面导航\"] --> K{\"frameId === 0?\"}\n K -->|是| L[\"移除旧索引\"]\n```\n\n资料来源：[utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n\n## 录制回放引擎\n\n### 引擎架构\n\n`record-replay/index.ts` 实现了 DOM 触发器驱动的自动化录制回放系统：\n\n```typescript\ninterface TriggerConfig {\n type: 'dom' | 'network' | 'custom';\n selector?: string; // DOM 选择器\n appear?: boolean; // 出现时触发\n once?: boolean; // 仅触发一次\n debounceMs?: number; // 防抖延迟\n enabled?: boolean;\n}\n```\n\n### 触发器类型\n\n| 类型 | 说明 | 配置项 |\n|------|------|--------|\n| DOM | DOM 元素变化触发 | selector, appear, once, debounceMs |\n| Network | 网络请求触发 | urlPattern, method |\n| Custom | 自定义触发器 | - |\n\n### 触发器工作流程\n\n```mermaid\nsequenceDiagram\n participant Ext as 扩展\n participant Tab as 标签页\n participant Observer as DOM Observer\n participant Trigger as 触发器\n \n Ext->>Tab: 注入 dom-observer.js\n Tab->>Observer: 创建 MutationObserver\n Observer->>Trigger: 检测到变化\n Trigger->>Trigger: 防抖处理\n Trigger->>Tab: 发送 set_dom_triggers\n Tab-->>Ext: 触发事件响应\n```\n\n### 初始化流程\n\n1. 从 storage 加载触发器配置\n2. 过滤启用的 DOM 类型触发器\n3. 遍历所有标签页注入脚本\n4. 发送触发器配置到各标签页\n\n资料来源：[entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)\n\n## 安全策略\n\n### Content Security Policy\n\n生产环境启用严格 CSP 策略：\n\n```typescript\ncontent_security_policy: {\n extension_pages: \n \"script-src 'self' 'wasm-unsafe-eval'; \" +\n \"object-src 'self'; \" +\n \"style-src 'self' 'unsafe-inline'; \" +\n \"img-src 'self' data: blob:;\"\n}\n```\n\n### 跨域隔离策略\n\n```typescript\ncross_origin_embedder_policy: { value: 'require-corp' },\ncross_origin_opener_policy: { value: 'same-origin' }\n```\n\n### Web Accessible Resources\n\n| 资源路径 | 用途 | 匹配范围 |\n|----------|------|----------|\n| `/models/*` | AI 模型文件 | `` |\n| `/workers/*` | Web Worker 文件 | `` |\n| `/inject-scripts/*` | 注入脚本辅助文件 | `` |\n\n## 技术栈\n\n| 组件 | 技术选型 |\n|------|----------|\n| 扩展框架 | WXT |\n| UI 框架 | Vue 3 |\n| 样式 | TailwindCSS v4 |\n| 图标 | SVG 组件自动注册 |\n| 构建工具 | Vite |\n| 脚本类型 | TypeScript |\n\n资料来源：[wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n\n## 扩展生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 安装: 首次安装\n 安装 --> 就绪: 初始化完成\n 就绪 --> 活跃: 用户操作\n 活跃 --> 等待: 空闲超时\n 等待 --> 活跃: 新操作\n 活跃 --> 更新: manifest 更新\n 更新 --> 就绪: 重新初始化\n 就绪 --> [*]: 卸载\n```\n\n## 常量定义\n\n扩展使用集中式常量管理：\n\n```typescript\n// 存储键名\nconst STORAGE_KEYS = {\n RR_TRIGGERS: 'rr_triggers',\n // ... 其他键\n}\n\n// 消息类型\nconst CONTENT_MESSAGE_TYPES = {\n ACCESSIBILITY_TREE_HELPER_PING: '...',\n // ... 其他类型\n}\n```\n\n资料来源：[common/constants.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/common/constants.ts)\n\n## 总结\n\nmcp-chrome 扩展采用现代化的多入口点架构，通过 WXT 框架简化了 manifest 管理。核心设计特点包括：\n\n1. **分层架构** - 清晰的后台脚本、内容脚本、注入脚本分层\n2. **工具化设计** - 丰富的浏览器控制工具集\n3. **自动化索引** - 智能的内容索引系统\n4. **录制回放** - 基于触发器的自动化引擎\n5. **安全优先** - 严格的 CSP 和跨域策略\n\n---\n\n\n\n## 本地服务器架构\n\n### 相关页面\n\n相关主题：[系统架构设计](#architecture), [AI Agent 集成](#agent-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/native-server/src/server/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/server/index.ts)\n- [app/native-server/src/mcp/mcp-server.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/mcp/mcp-server.ts)\n- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)\n- [app/native-server/src/agent/tool-bridge.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/tool-bridge.ts)\n- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n- [app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n \n\n# 本地服务器架构\n\n## 概述\n\nmcp-chrome 的本地服务器（Native Server）是整个系统的核心后端组件，负责在 AI 代理（如 Claude）和 Chrome 浏览器之间建立双向通信桥梁。该模块采用 Node.js/TypeScript 实现，通过 Native Messaging 协议与 Chrome 扩展进行交互，同时集成了 AI 引擎来完成复杂的浏览器自动化任务。\n\n本地服务器的核心职责包括：\n\n- **协议转换**：将 MCP（Model Context Protocol）协议转换为 Chrome 扩展可理解的命令\n- **工具编排**：管理 AI 引擎调用的各类工具（tool），包括浏览器操作、内容获取、网络请求等\n- **状态维护**：维护跨会话的浏览器状态和索引信息\n- **安全通信**：通过原生消息机制确保安全的进程间通信\n\n资料来源：[app/native-server/src/server/index.ts:1-50]()\n\n## 整体架构\n\nmcp-chrome 采用分层架构设计，各层之间通过定义良好的接口进行通信：\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Claude AI / MCP Client]\n end\n \n subgraph 本地服务器层\n B[MCP Server]\n C[Agent Engine]\n D[Tool Bridge]\n end\n \n subgraph 通信层\n E[Native Messaging]\n F[Chrome Extension Runtime]\n end\n \n subgraph 浏览器层\n G[Chrome Extension]\n H[Content Scripts]\n I[Inject Scripts]\n end\n \n A -->|MCP Protocol| B\n B --> C\n C --> D\n D -->|Native Message| E\n E --> F\n F --> G\n G --> H\n G --> I\n \n J[Web Content] --> I\n```\n\n## 核心组件\n\n### MCP 服务器\n\nMCP 服务器是整个架构的入口点，负责：\n\n- 初始化并管理 MCP 协议会话\n- 处理来自 AI 客户端的请求\n- 调度工具执行并返回结果\n- 管理会话生命周期\n\n| 组件 | 职责 | 关键文件 |\n|------|------|----------|\n| Session Manager | 管理多个并发会话 | mcp-server.ts |\n| Request Handler | 处理 MCP 请求/响应 | server/index.ts |\n| Tool Registry | 注册和管理可用工具 | tool-bridge.ts |\n\n资料来源：[app/native-server/src/mcp/mcp-server.ts:1-100]()\n\n### Agent 引擎\n\nAgent 引擎负责协调 AI 模型与工具系统之间的交互。当前实现支持 Claude 模型，未来可扩展支持其他模型。\n\n```mermaid\ngraph LR\n A[User Request] --> B[Parse Intent]\n B --> C{Requires Tools?}\n C -->|Yes| D[Tool Bridge]\n C -->|No| E[Direct Response]\n D --> F[Execute Tool]\n F --> G[Format Result]\n G --> H[Return to AI]\n E --> H\n```\n\n关键特性包括：\n\n- **流式处理**：支持流式输出和工具调用的交错处理\n- **错误恢复**：工具执行失败时的自动重试和错误报告\n- **上下文管理**：维护对话上下文和工具调用历史\n\n资料来源：[app/native-server/src/agent/engines/claude.ts:1-150]()\n\n### 工具桥接器\n\n工具桥接器（Tool Bridge）是连接 AI 引擎与 Chrome 扩展的枢纽，负责：\n\n- 工具发现和元数据管理\n- 参数验证和转换\n- 执行结果格式化\n- 错误处理和重试\n\n| 工具类别 | 数量 | 示例 |\n|----------|------|------|\n| 标签页管理 | 5 | chrome_tabs_query, chrome_tabs_create, chrome_tabs_update, chrome_tabs_close, chrome_tabs_move |\n| 导航控制 | 3 | chrome_navigate, chrome_go_back_or_forward, chrome_reload |\n| 内容获取 | 4 | chrome_get_web_content, chrome_screenshot, chrome_get_interactive_elements, search_tabs_content |\n| 网络操作 | 6 | chrome_network_capture_start, chrome_network_debugger_start, chrome_network_request 等 |\n| 书签管理 | 4 | chrome_bookmark_search, chrome_bookmark_add, chrome_bookmark_delete 等 |\n| 脚本注入 | 2 | chrome_inject_script, chrome_send_command_to_inject_script |\n\n资料来源：[app/native-server/src/agent/tool-bridge.ts:1-80]()\n\n## 通信机制\n\n### Native Messaging 协议\n\nmcp-chrome 使用 Chrome 的 Native Messaging 协议实现与扩展的安全通信。该协议基于标准输入/输出流进行 JSON 消息交换。\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant Chrome as Chrome Extension\n participant Native as Native Host\n \n MCP->>Native: 启动进程\n Native->>Chrome: 发送连接消息\n Chrome->>Native: 初始化握手\n Native->>MCP: 握手完成\n MCP->>Native: JSON-RPC 请求\n Native->>Chrome: 转发请求\n Chrome->>Native: 执行结果\n Native->>MCP: JSON-RPC 响应\n```\n\n消息格式遵循以下结构：\n\n```json\n{\n \"id\": \"unique-message-id\",\n \"method\": \"tool_name\",\n \"params\": {\n \"tabId\": 123,\n \"selector\": \"#element\"\n }\n}\n```\n\n### 跨平台支持\n\n本地服务器支持多个操作系统和浏览器组合的 Native Messaging 配置：\n\n| 平台 | 浏览器 | 配置路径 |\n|------|--------|----------|\n| Windows | Chrome | `%APPDATA%\\Google\\Chrome\\NativeMessagingHosts\\` |\n| Windows | Chromium | `%APPDATA%\\Chromium\\NativeMessagingHosts\\` |\n| macOS | Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` |\n| macOS | Chromium | `~/Library/Application Support/Chromium/NativeMessagingHosts/` |\n| Linux | Chrome | `~/.config/google-chrome/NativeMessagingHosts/` |\n| Linux | Chromium | `~/.config/chromium/NativeMessagingHosts/` |\n\n资料来源：[app/native-server/src/scripts/browser-config.ts:30-90]()\n\n## 内容索引系统\n\n### 语义搜索引擎\n\ncontent-indexer 模块提供了对浏览器标签页内容进行语义搜索的能力，这对于 AI 代理理解用户当前浏览内容至关重要。\n\n```mermaid\ngraph TD\n A[Tab Load Complete] --> B{Is Excluded URL?}\n B -->|chrome://| C[Skip]\n B -->|chrome-extension://| C\n B -->|about:| C\n B -->|file://| C\n B -->|Yes| D[Process Content]\n \n D --> E[Wait 2 seconds]\n E --> F[Inject Web Fetcher]\n F --> G[Extract Text + Metadata]\n G --> H[Index with Semantic Engine]\n H --> I[Store in Vector DB]\n \n C --> J[End]\n I --> J\n```\n\n关键配置参数：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| autoIndex | true | 页面加载完成后自动索引 |\n| indexDelay | 2000ms | 等待页面完全加载的延迟 |\n| excludePatterns | 5种 | 排除的 URL 模式（chrome://、file:// 等） |\n\n资料来源：[app/chrome-extension/utils/content-indexer.ts:40-80]()\n\n### 元数据提取\n\nweb-fetcher-helper.js 负责从网页中提取结构化元数据，支持多种数据源优先级：\n\n1. **JSON-LD** 结构化数据\n2. **Open Graph** 元标签\n3. **Twitter Card** 元标签\n4. **Dublin Core** 元标签\n5. **标准 HTML** 元标签\n\n提取的元数据字段：\n\n- `title` - 文章标题\n- `byline` - 作者信息\n- `excerpt` - 描述/摘要\n- `siteName` - 网站名称\n- `publishedTime` - 发布时间\n- `image` - 主图 URL\n\n资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js:1-100]()\n\n## 诊断系统\n\n### 健康检查流程\n\ndoctor.ts 提供了完整的系统诊断功能，确保本地服务器正确安装和配置：\n\n```mermaid\ngraph TD\n A[Run Diagnostics] --> B[Check Native Host]\n B --> C{Host Found?}\n C -->|No| D[Show Install Instructions]\n C -->|Yes| E[Check Manifest]\n \n E --> F{Manifest Valid?}\n F -->|No| G[Run Register Command]\n F -->|Yes| H[Check Permissions]\n \n H --> I{Permissions OK?}\n I -->|No| J[Show Permission Guide]\n I -->|Yes| K[All Checks Passed]\n \n D --> L[End]\n G --> L\n J --> L\n K --> L\n```\n\n### 诊断检查项\n\n| 检查项 | 状态标识 | 失败处理 |\n|--------|----------|----------|\n| 原生主机可执行文件 | `host.binary` | 提示安装步骤 |\n| 用户级 Manifest | `manifest.user` | `register --browser` |\n| 系统级 Manifest | `manifest.system` | 需要管理员权限 |\n| Windows 注册表 | `registry` | 自动修复注册 |\n| 允许来源 | `allowed_origins` | 重新注册扩展 ID |\n\n诊断报告会生成 Markdown 格式的输出，包含：\n\n- 各检查项的详细状态\n- 预期路径与实际路径对比\n- 修复建议和命令\n\n资料来源：[app/native-server/src/scripts/doctor.ts:100-200]()\n\n## 工作流程示例\n\n### 完整工具调用流程\n\n当 AI 代理需要执行浏览器操作时，整个调用流程如下：\n\n```mermaid\nsequenceDiagram\n participant AI as Claude AI\n participant MCP as MCP Server\n participant Engine as Agent Engine\n participant Bridge as Tool Bridge\n participant Ext as Chrome Extension\n \n AI->>MCP: tool_use request\n MCP->>Engine: dispatch tool call\n Engine->>Bridge: validate & prepare\n Bridge->>Ext: native message\n Ext->>Ext: execute in browser\n Ext-->>Bridge: result message\n Bridge->>Engine: format result\n Engine->>MCP: tool result\n MCP-->>AI: tool result response\n```\n\n### 状态管理\n\n工具执行过程中的状态流转：\n\n| 阶段 | 状态 | 说明 |\n|------|------|------|\n| 接收请求 | `pending` | 等待工具调度 |\n| 验证参数 | `validating` | 检查参数合法性 |\n| 发送消息 | `sending` | 写入 Native Message |\n| 等待响应 | `waiting` | 阻塞等待浏览器响应 |\n| 处理结果 | `processing` | 解析返回数据 |\n| 完成 | `completed` / `error` | 最终状态 |\n\n资料来源：[app/native-server/src/agent/engines/claude.ts:80-120]()\n\n## 安全考虑\n\n### Content Security Policy\n\n生产环境中启用严格的安全策略：\n\n```typescript\ncontent_security_policy: {\n extension_pages: \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\"\n}\n```\n\n### Web Accessible Resources\n\n受限的资源访问模式：\n\n- `/models/*` - AI 模型文件（需明确声明）\n- `/workers/*` - Web Worker 脚本\n- `/inject-scripts/*` - 内容脚本辅助文件\n\n资料来源：[app/chrome-extension/wxt.config.ts:20-40]()\n\n## 扩展性设计\n\n### 添加新工具\n\n在 tool-bridge.ts 中注册新工具的流程：\n\n1. 定义工具的 schema（名称、参数、返回值）\n2. 实现工具执行逻辑\n3. 注册到工具注册表\n4. 扩展 Chrome 扩展端的处理逻辑\n\n### 添加新 AI 引擎\n\nAgent 引擎采用策略模式设计，添加新引擎只需：\n\n1. 实现 `BaseEngine` 接口\n2. 在引擎工厂中注册\n3. 配置相应的 API 端点和认证\n\n## 总结\n\nmcp-chrome 的本地服务器架构通过清晰的层次划分和标准化的通信协议，实现了 AI 代理与浏览器之间的高效协作。核心优势包括：\n\n- **模块化设计**：各组件职责明确，易于测试和维护\n- **跨平台兼容**：支持 Windows、macOS、Linux 三大平台\n- **流式处理**：支持实时交互的低延迟响应\n- **可扩展性**：工具系统和引擎系统均支持灵活扩展\n\n该架构为构建智能化的浏览器自动化应用提供了坚实的技术基础。\n\n---\n\n\n\n## 浏览器工具集\n\n### 相关页面\n\n相关主题：[Chrome 扩展架构](#chrome-extension-structure), [可视化编辑器](#visual-editor)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/TOOLS.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS.md)\n- [docs/TOOLS_zh.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS_zh.md)\n- [app/chrome-extension/entrypoints/background/tools/browser/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/index.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/interaction.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/interaction.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts)\n \n\n# 浏览器工具集\n\n## 概述\n\n浏览器工具集是 mcp-chrome 项目中负责与 Chrome 浏览器进行交互的核心功能模块。通过 MCP（Model Context Protocol）协议，该工具集允许 AI Agent 能够感知、操控和分析浏览器状态，从而实现自动化浏览器操作、网页内容提取、网络请求监控等高级功能。\n\n工具集位于 `app/chrome-extension/entrypoints/background/tools/browser/` 目录下，采用模块化架构设计，每个工具类别对应独立的功能文件。资料来源：[app/chrome-extension/entrypoints/background/tools/browser/index.ts:1-50]()\n\n## 架构设计\n\n### 整体架构\n\n浏览器工具集采用分层架构，底层通过 Chrome Extension API 与浏览器内核交互，上层通过 MCP 协议暴露标准化的工具接口。\n\n```mermaid\ngraph TD\n A[MCP Client / AI Agent] --> B[Chrome Extension Background]\n B --> C[Browser Tools 模块]\n C --> D[chrome.tabs API]\n C --> E[chrome.webNavigation API]\n C --> F[chrome.webRequest API]\n C --> G[chrome.debugger API]\n C --> H[chrome.scripting API]\n \n D --> I[浏览器 Tab 管理]\n E --> J[页面导航监控]\n F --> K[网络请求拦截]\n G --> L[响应体调试]\n H --> M[脚本注入执行]\n```\n\n### 工具分类\n\n| 类别 | 工具数量 | 主要功能 |\n|------|----------|----------|\n| 标签页管理 | 4 | 创建、切换、关闭标签页 |\n| 导航控制 | 2 | 前进/后退、URL 跳转 |\n| 视图控制 | 2 | 缩放、视口调整 |\n| 截图 | 1 | 页面和元素截图 |\n| 网络监控 | 4 | 请求捕获、调试、自定义请求 |\n| 内容分析 | 4 | 内容提取、元素查找、控制台捕获 |\n| 交互操作 | 3 | 元素点击、表单填充、键盘输入 |\n\n资料来源：[docs/TOOLS.md:1-30]()\n\n## 标签页管理\n\n### 功能列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_create_tab` | 创建新的浏览器标签页 |\n| `chrome_switch_tab` | 切换当前活动标签页 |\n| `chrome_close_tabs` | 关闭指定标签页或窗口 |\n| `chrome_get_tabs` | 获取当前所有标签页列表 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/index.ts:50-100]()\n\n### 创建标签页\n\n`chrome_create_tab` 工具支持以下参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `url` | string | 是 | 目标 URL |\n| `active` | boolean | 否 | 是否激活新标签页（默认 true） |\n| `index` | number | 否 | 标签页位置索引 |\n| `windowId` | number | 否 | 指定窗口 ID |\n\n### 标签页切换与关闭\n\n- `chrome_switch_tab` 支持通过标签页 ID 或 URL 模式切换\n- `chrome_close_tabs` 支持关闭单个标签页、多个标签页或整个窗口\n- 所有操作均返回更新后的标签页状态\n\n## 导航控制\n\n### 前进/后退\n\n`chrome_go_back_or_forward` 工具提供浏览器历史导航功能：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `direction` | \"back\" \\| \"forward\" | 是 | 导航方向 |\n| `tabId` | number | 否 | 指定标签页（默认当前活动标签页） |\n| `steps` | number | 否 | 步进数量（默认 1） |\n\n### 视图控制\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_set_viewport` | 设置页面缩放比例和视口尺寸 |\n| `chrome_zoom` | 调整页面缩放级别 |\n\n## 截图功能\n\n### chrome_screenshot\n\n高级截图工具，支持多种截图模式：\n\n```typescript\ninterface ScreenshotOptions {\n tabId?: number; // 指定标签页\n fullPage?: boolean; // 全页面截图\n elementSelector?: string; // 特定元素截图\n width?: number; // 自定义宽度\n height?: number; // 自定义高度\n format?: 'png' | 'jpeg'; // 输出格式\n quality?: number; // 图片质量（1-100）\n}\n```\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts:1-50]()\n\n### 截图模式\n\n1. **标签页截图**：捕获指定标签页的可见区域\n2. **全页面截图**：通过滚动拼接获取整个页面\n3. **元素截图**：通过 CSS 选择器定位并截取特定元素\n\n### 技术实现\n\n截图功能通过 `chrome.tabs.captureVisibleTab` API 实现，对于全页面截图需要：\n\n1. 获取页面原始尺寸\n2. 设置视口为页面总高度\n3. 滚动页面并多次截图\n4. 拼接图像片段\n\n## 网络监控\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_network_capture_start` | 启动 webRequest API 网络捕获 |\n| `chrome_network_capture_stop` | 停止网络捕获 |\n| `chrome_network_debugger_start` | 启动 Debugger API 调试 |\n| `chrome_network_debugger_stop` | 停止调试模式 |\n| `chrome_network_request` | 发送自定义 HTTP 请求 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts:1-60]()\n\n### webRequest API 模式\n\n使用 `chrome.webRequest` API 监听网络请求：\n\n- 支持请求过滤（URL 模式、类型、状态码）\n- 可记录请求头、响应头、请求时间\n- 适合高并发场景的性能监控\n\n### Debugger API 模式\n\n使用 `chrome.debugger` API 获取完整响应体：\n\n- 支持拦截并修改请求/响应\n- 可以获取二进制响应内容\n- 适合需要深度分析 HTTP 流量的场景\n\n### 自定义请求\n\n`chrome_network_request` 支持构造完整的 HTTP 请求：\n\n```typescript\ninterface NetworkRequestOptions {\n url: string; // 请求 URL\n method?: string; // HTTP 方法\n headers?: object; // 请求头\n body?: string; // 请求体\n timeout?: number; // 超时时间\n}\n```\n\n## 内容分析\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `search_tabs_content` | 跨标签页语义搜索 |\n| `chrome_get_web_content` | 提取网页 HTML/文本内容 |\n| `chrome_get_interactive_elements` | 获取可交互元素列表 |\n| `chrome_console` | 捕获页面控制台输出 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts:1-80]()\n\n### search_tabs_content\n\n基于语义的内容搜索工具，支持：\n\n- 跨多个浏览器标签页进行全文搜索\n- 使用向量嵌入进行语义匹配\n- 返回匹配结果及其上下文片段\n\n### chrome_get_web_content\n\n网页内容提取工具：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `tabId` | number | 是 | 目标标签页 ID |\n| `format` | \"html\" \\| \"text\" | 否 | 输出格式（默认 text） |\n| `selectors` | string[] | 否 | CSS 选择器过滤 |\n\n### 交互元素获取\n\n`chrome_get_interactive_elements` 返回页面的可点击元素：\n\n```typescript\ninterface InteractiveElement {\n tagName: string; // 元素标签名\n id?: string; // 元素 ID\n className?: string; // 样式类名\n textContent?: string; // 文本内容\n attributes: object; // 所有属性\n boundingRect: object; // 位置坐标\n selector: string; // 唯一选择器\n}\n```\n\n## 交互操作\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_click_element` | 通过 CSS 选择器点击元素 |\n| `chrome_fill_or_select` | 填写表单或选择选项 |\n| `chrome_keyboard` | 模拟键盘输入和快捷键 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/interaction.ts:1-50]()\n\n### 元素点击\n\n`chrome_click_element` 通过 DOM 选择器定位并点击元素：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `selector` | string | 是 | CSS 选择器 |\n| `tabId` | number | 否 | 目标标签页 |\n| `button` | \"left\" \\| \"right\" \\| \"middle\" | 否 | 鼠标按钮 |\n| `clickCount` | number | 否 | 点击次数 |\n\n### 表单操作\n\n`chrome_fill_or_select` 支持多种表单输入：\n\n- **文本输入**：直接设置 input 值并触发 change 事件\n- **下拉选择**：通过 value 或文本选择选项\n- **复选框/单选框**：设置 checked 状态\n- **文件上传**：设置文件路径\n\n### 键盘模拟\n\n`chrome_keyboard` 支持：\n\n- 普通文本输入\n- 快捷键组合（如 `Command+Shift+P`）\n- 特殊键序列\n\n## 脚本注入\n\n### chrome_inject_script\n\n在网页上下文中执行自定义 JavaScript：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `tabId` | number | 是 | 目标标签页 |\n| `script` | string | 是 | JavaScript 代码 |\n| `args` | any[] | 否 | 传递给脚本的参数 |\n\n### chrome_send_command_to_inject_script\n\n向已注入的内容脚本发送命令，实现双向通信：\n\n```mermaid\nsequenceDiagram\n participant A as MCP Client\n participant B as Background Script\n participant C as Content Script\n \n A->>B: send_command_to_inject_script\n B->>C: chrome.tabs.sendMessage\n C-->>B: 消息响应\n B-->>A: 返回结果\n```\n\n## 数据模型\n\n### 工具返回格式\n\n所有工具遵循统一的响应格式：\n\n```typescript\ninterface ToolResponse {\n success: boolean; // 操作是否成功\n data?: T; // 返回数据\n error?: string; // 错误信息\n metadata?: { // 元数据\n tabId?: number;\n timestamp: number;\n duration?: number;\n };\n}\n```\n\n### 标签页模型\n\n```typescript\ninterface ChromeTab {\n id: number;\n windowId: number;\n index: number;\n url: string;\n title: string;\n active: boolean;\n pinned: boolean;\n status: 'loading' | 'complete';\n incognito: boolean;\n}\n```\n\n## 配置与扩展\n\n### 安全策略\n\n浏览器工具集在 Chrome Extension 中运行，需要配置适当的安全策略：\n\n资料来源：[app/chrome-extension/wxt.config.ts:1-30]()\n\n```typescript\ncontent_security_policy: {\n extension_pages: \n \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\",\n}\n```\n\n### 权限声明\n\n工具集需要在 `manifest.json` 中声明所需权限：\n\n- `tabs`：标签页管理\n- `webNavigation`：导航监控\n- `webRequest`：网络请求拦截\n- `debugger`：调试功能\n- `scripting`：脚本注入\n- ``：全网站访问\n\n## 最佳实践\n\n### 性能优化\n\n1. **批量操作**：多个标签页操作时使用 Promise.all 并行执行\n2. **按需截图**：仅在需要时进行全页面截图，避免频繁滚动\n3. **网络过滤**：使用精确的 URL 模式过滤减少事件监听开销\n\n### 错误处理\n\n1. 标签页操作前检查标签页是否存在\n2. 网络请求设置合理的超时时间\n3. 脚本注入前验证目标页面是否加载完成\n\n### 安全考虑\n\n1. 避免在不可信页面执行未验证的脚本\n2. 网络请求监控注意敏感信息保护\n3. 脚本注入仅在必要时使用\n\n## 相关资源\n\n- [工具文档（英文）](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS.md)\n- [工具文档（中文）](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS_zh.md)\n- [Chrome Extension API 文档](https://developer.chrome.com/docs/extensions/reference/)\n\n---\n\n\n\n## 录制回放系统 (V3)\n\n### 相关页面\n\n相关主题：[Chrome 扩展架构](#chrome-extension-structure), [浏览器工具集](#browser-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)\n- [app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts)\n- [app/chrome-extension/entrypoints/background/record-replay/recording/browser-event-listener.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/recording/browser-event-listener.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/common.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/common.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n \n\n# 录制回放系统 (V3)\n\n> **注意**：查询中请求的 `record-replay-v3` 目录下的源码文件未在当前上下文环境中检索到。以下文档基于现有的 `record-replay` 目录中的代码进行说明，涵盖了录制回放系统的核心架构与实现细节。\n\n## 概述\n\n录制回放系统是 Chrome MCP 扩展中用于记录用户浏览器操作并在需要时进行自动化回放的模块。该系统通过监听浏览器事件、捕获 DOM 变化、记录网络请求等方式，实现对用户操作流程的完整复现。\n\n系统设计目标包括：\n\n- **操作录制**：自动捕获用户的导航、点击、表单填写等交互行为\n- **智能触发**：支持基于 URL、DOM 变化、时间等多种触发条件\n- **流程回放**：精确还原录制时的操作序列\n- **状态同步**：在回放过程中处理页面状态变化和异步操作\n\n## 系统架构\n\n### 核心组件\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| BrowserEventListener | 监听并捕获浏览器事件 | `browser-event-listener.ts` |\n| Flow | 流程数据模型定义 | `domain/flow.ts` |\n| Kernel | 回放引擎核心 | `engine/kernel/kernel.ts` |\n| Triggers | 触发器管理 | `engine/triggers/index.ts` |\n| WaitPolicies | 等待策略（网络空闲检测等） | `engine/policies/wait.ts` |\n\n### 架构图\n\n```mermaid\ngraph TD\n subgraph 录制阶段\n BEL[BrowserEventListener]\n BEL -->|捕获事件| NE[导航事件]\n BEL -->|捕获事件| CE[点击事件]\n BEL -->|捕获事件| FE[表单事件]\n NE -->|记录| FL[Flow]\n CE -->|记录| FL\n FE -->|记录| FL\n end\n \n subgraph 回放阶段\n K[Kernel]\n K -->|读取| FL\n K -->|执行| IE[交互引擎]\n K -->|检测| WP[WaitPolicies]\n WP -->|等待条件| K\n K -->|触发| TR[Triggers]\n end\n \n subgraph 事件监听\n BEL -->|onCommitted| WN[webNavigation]\n BEL -->|onUpdated| TU[tabs.onUpdated]\n BEL -->|onRemoved| TRU[tabs.onRemoved]\n end\n```\n\n## 事件监听机制\n\n### 导航事件捕获\n\n系统通过 `chrome.webNavigation` API 监听页面导航事件，这是录制回放系统的核心数据来源。\n\n```typescript\nchrome.webNavigation.onCommitted.addListener(async (details) => {\n if (details.frameId !== 0) return;\n // 确保核心内容脚本已注入\n await ensureCoreInjected(details.tabId);\n // 获取存储的 DOM 触发器\n const { [STORAGE_KEYS.RR_TRIGGERS]: stored } = \n await chrome.storage.local.get(STORAGE_KEYS.RR_TRIGGERS);\n // ... 触发器处理逻辑\n});\n```\n\n**关键事件类型**：\n\n| 事件 | 触发条件 | 录制价值 |\n|------|----------|----------|\n| `onCommitted` | 导航提交时 | 记录初始 URL 变化 |\n| `onCompleted` | 页面加载完成 | 标记加载结束 |\n| `onHistoryStateUpdated` | 历史状态更新 | SPA 路由变化 |\n\n### 标签页事件监听\n\n```typescript\nchrome.tabs.onUpdated.addListener((updatedId, change, tab) => {\n if (updatedId !== tabId) return;\n // 检测 loading 状态\n if (change.status === 'loading') mark();\n // 检测 URL 变化\n if (typeof change.url === 'string' && (!prevUrl || change.url !== prevUrl)) mark();\n});\n```\n\n### 导航类型过滤\n\n系统会过滤特定的导航类型，只录制有意义的用户操作：\n\n```typescript\nconst shouldRecord =\n t === 'reload' ||\n t === 'typed' ||\n t === 'generated' ||\n t === 'auto_bookmark' ||\n t === 'keyword' ||\n t === 'form_submit'; // 捕获回车搜索行为\n```\n\n**不录制的类型**：`link`（纯链接点击由其他机制处理）\n\n## 流程数据模型\n\n### Flow 结构\n\nFlow 是录制回放系统的核心数据结构，用于存储录制过程中捕获的所有操作信息。\n\n```typescript\ninterface Flow {\n id: string; // 唯一标识\n steps: FlowStep[]; // 操作步骤列表\n metadata: FlowMeta; // 元数据\n triggers?: Trigger[]; // 关联的触发器\n}\n\ninterface FlowStep {\n type: 'navigation' | 'click' | 'input' | 'wait' | 'screenshot';\n timestamp: number;\n data: Record;\n}\n```\n\n### 导航步骤\n\n导航步骤记录页面 URL 变化和相关上下文：\n\n```typescript\nif (flow && url) {\n addNavigationStep(flow, url);\n}\n```\n\n## 触发器系统\n\n### 触发器类型\n\n| 类型 | 描述 | 适用场景 |\n|------|------|----------|\n| `url` | URL 模式匹配 | 特定页面触发 |\n| `dom` | DOM 元素检测 | 元素出现时触发 |\n| `timer` | 定时触发 | 周期性任务 |\n| `manual` | 手动触发 | 调试/测试 |\n\n### DOM 触发器配置\n\n```typescript\nconst domTriggers = triggers\n .filter((x) => x.type === 'dom' && x.enabled !== false)\n .map((x: any) => ({\n id: x.id,\n selector: x.selector, // CSS 选择器\n appear: x.appear !== false, // 出现/消失\n once: x.once !== false, // 单次/重复\n debounceMs: x.debounceMs ?? 800, // 防抖延迟\n }));\n```\n\n## 等待策略\n\n系统在回放过程中使用多种等待策略来确保页面状态就绪。\n\n### 网络空闲检测\n\n```typescript\nexport async function waitForNetworkIdle(\n tabId: number,\n sniffMs: number = 500,\n finish: () => void\n): Promise {\n let mark: () => void;\n let timer: ReturnType;\n\n const getLogger = (): ((...args: unknown[]) => void) => {\n return (...args: unknown[]) => console.log('[NetworkIdle]', ...args);\n };\n\n const isIdle = (): boolean => {\n // 检测逻辑\n };\n\n const wait = (): Promise =>\n new Promise((resolve) => {\n mark = resolve;\n const startedAt = Date.now();\n let prevUrl: string | undefined;\n\n const onCommitted = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n\n const onCompleted = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n\n const onHistoryStateUpdated = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n\n const onUpdated = (updatedId: number, change: chrome.tabs.TabChangeInfo) => {\n if (updatedId !== tabId) return;\n if (change.status === 'loading') mark();\n if (typeof change.url === 'string' && (!prevUrl || change.url !== prevUrl)) mark();\n };\n\n chrome.webNavigation.onCommitted.addListener(onCommitted);\n chrome.webNavigation.onCompleted.addListener(onCompleted);\n chrome.tabs.onUpdated.addListener(onUpdated);\n timer = setTimeout(finish, sniffMs);\n });\n}\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `tabId` | number | - | 目标标签页 ID |\n| `sniffMs` | number | 500 | 空闲检测时间窗口（毫秒） |\n| `finish` | function | - | 超时完成回调 |\n\n## 内容脚本注入\n\n系统通过 `chrome.scripting.executeScript` API 向目标页面注入脚本，以获取页面内容或执行特定操作。\n\n```typescript\nawait chrome.scripting.executeScript({\n target: { tabId: details.tabId, allFrames: true },\n files: ['inject-scripts/dom-observer.js'],\n world: 'ISOLATED',\n});\n```\n\n### 注入脚本类型\n\n| 脚本 | 用途 | 作用域 |\n|------|------|--------|\n| `web-fetcher-helper.js` | 页面内容提取 | ISOLATED |\n| `dom-observer.js` | DOM 变化监听 | ISOLATED |\n\n### 消息通信\n\n```typescript\nawait chrome.tabs.sendMessage(details.tabId, {\n action: 'setTriggers',\n triggers: domTriggers,\n});\n```\n\n## 录制状态管理\n\n### 会话状态\n\n```typescript\ninterface Session {\n getStatus(): 'idle' | 'recording' | 'replaying';\n getFlow(): Flow | null;\n getActiveTabs(): number[];\n}\n```\n\n### 状态转换\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: 初始化\n Idle --> Recording: 开始录制\n Recording --> Replaying: 执行回放\n Replaying --> Idle: 回放完成\n Recording --> Idle: 停止录制\n Idle --> [*]: 清理\n```\n\n### 活动标签页管理\n\n```typescript\n// 录制开始时记录活动标签页\nsession.addActiveTab(tabId);\n\n// 标签页关闭时移除\nchrome.tabs.onRemoved.addListener((tabId) => {\n if (session.getStatus() !== 'recording') return;\n session.removeActiveTab(tabId);\n});\n```\n\n## 与其他模块的交互\n\n### 与工具系统的集成\n\n录制回放系统通过 MCP 工具协议暴露功能：\n\n```typescript\n// 注册命令处理器\nchrome.commands.onCommand.addListener(async (command) => {\n const t = commands.find((k) => k.command === command);\n if (!t || t.enabled === false) return;\n \n const flow = await getFlow(t.flowId);\n if (!flow) return;\n \n await runFlow(flow, { args: t.args || {}, returnLogs: false });\n});\n```\n\n### 与内容索引器的协同\n\n系统与 `ContentIndexer` 模块共享部分事件监听器：\n\n```typescript\nif (chrome.webNavigation) {\n chrome.webNavigation.onCommitted.addListener(async (details) => {\n if (details.frameId === 0) {\n await this.removeTabIndex(details.tabId);\n }\n });\n}\n```\n\n## 安全考虑\n\n### 跨域隔离策略\n\n在生产环境中，系统启用以下安全策略：\n\n```typescript\ncross_origin_embedder_policy: { value: 'require-corp' as const },\ncross_origin_opener_policy: { value: 'same-origin' as const },\n```\n\n### 内容安全策略\n\n```typescript\ncontent_security_policy: {\n extension_pages:\n \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\",\n}\n```\n\n## 最佳实践\n\n1. **触发器防抖**：DOM 触发器建议设置 `debounceMs >= 800ms` 避免误触发\n2. **资源访问控制**：通过 `web_accessible_resources` 限制可访问资源范围\n3. **错误处理**：关键操作使用 try-catch 包装，防止单点故障影响整体录制\n4. **标签页清理**：及时移除关闭的标签页 ID，避免无效广播\n\n## 相关文档\n\n- [工具系统概览](../tools/overview.md)\n- [内容索引系统](./content-indexer.md)\n- [MCP 协议文档](../protocol/index.md)\n\n---\n\n\n\n## 可视化编辑器\n\n### 相关页面\n\n相关主题：[浏览器工具集](#browser-tools), [录制回放系统 (V3)](#record-replay-v3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n- [app/chrome-extension/entrypoints/background/web-editor/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/web-editor/index.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [app/chrome-extension/entrypoints/builder/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/builder/index.html)\n- [app/chrome-extension/entrypoints/sidepanel/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/index.html)\n \n\n# 可视化编辑器\n\n## 概述\n\n可视化编辑器（Visual Editor）是 mcp-chrome 项目中用于网页元素编辑的核心功能模块。该编辑器允许 AI Agent 通过自然语言指令直接操作网页上的元素，实现自动化网页交互与编辑功能。\n\nmcp-chrome 的可视化编辑器采用双版本架构，支持 **WebEditor V1**（旧版）与 **WebEditor V2**（新版）两种实现方式，通过 `USE_WEB_EDITOR_V2` 配置开关进行切换。资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:1-100]()\n\n## 架构设计\n\n### 双版本架构\n\n可视化编辑器采用 V1 和 V2 两个版本并行运行的架构设计：\n\n| 版本 | 标识常量 | 脚本路径 | 说明 |\n|------|----------|----------|------|\n| V1 | `USE_WEB_EDITOR_V2 = false` | `V1_SCRIPT_PATH` | 传统版本，稳定兼容 |\n| V2 | `USE_WEB_EDITOR_V2 = true` | `V2_SCRIPT_PATH` | 新版增强版本 |\n\n两个版本使用不同的 action 名称来避免冲突：\n\n- **V1 动作**：`web_editor_ping`、`web_editor_toggle` 等\n- **V2 动作**：`web_editor_ping_v2`、`web_editor_toggle_v2` 等\n\n资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:200-230]()\n\n### 组件层次结构\n\n```\nmcp-chrome 扩展\n├── Background Script (web-editor/index.ts)\n│ ├── 上下文菜单注册\n│ ├── 脚本注入管理\n│ └── 消息通信处理\n├── Content Script (注入脚本)\n│ ├── 元素标记器 (element-marker.js)\n│ └── 交互处理器\n└── Sidepanel UI\n ├── Agent Chat (时间线视图)\n └── 工作流编辑器\n```\n\n资料来源：[app/chrome-extension/wxt.config.ts:1-50]()\n\n## 核心功能\n\n### 元素标记与选择\n\n编辑器提供可视化的元素标记功能，用户可以通过点击或按空格键选择页面元素：\n\n- 高亮显示可交互元素\n- 显示元素信息面板\n- 支持 Shift 键多选模式\n- 元素检查器集成\n\n资料来源：[app/chrome-extension/inject-scripts/element-marker.js:1-100]()\n\n### 上下文菜单集成\n\n编辑器通过 Chrome 扩展的上下文菜单 API 注册快捷入口：\n\n```typescript\nawait chrome.contextMenus.create({\n id: CONTEXT_MENU_ID,\n title: '切换网页编辑模式',\n contexts: ['all'],\n});\n```\n\n该菜单项支持在任意页面通过右键调用\"切换网页编辑模式\"功能。资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:150-170]()\n\n### 脚本注入机制\n\n编辑器支持将脚本动态注入到目标页面，注入过程如下：\n\n```mermaid\nsequenceDiagram\n participant BG as Background Script\n participant Tab as Target Tab\n participant Script as Injected Script\n \n BG->>BG: ensureEditorInjected(tabId)\n BG->>BG: 获取版本对应脚本路径\n BG->>Tab: chrome.scripting.executeScript\n Tab->>Script: 加载编辑器脚本\n Script->>BG: 返回注入确认\n BG->>Tab: 发送初始化命令\n```\n\n资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:230-260]()\n\n## 交互流程\n\n### 编辑模式切换\n\n1. 用户通过上下文菜单或快捷键触发切换\n2. Background Script 检查目标 Tab 是否已注入编辑器脚本\n3. 如未注入，调用 `ensureEditorInjected()` 注入脚本\n4. 发送 `web_editor_toggle` 或 `web_editor_toggle_v2` 命令\n5. Content Script 接收命令，切换页面编辑状态\n\n### 动作响应函数\n\n根据版本不同，编辑器支持以下核心动作：\n\n| 动作名称 | V1 | V2 | 功能描述 |\n|----------|----|----|----------|\n| `web_editor_ping` | ✓ | ✓ | 检测编辑器连接状态 |\n| `web_editor_toggle` | ✓ | ✗ | 切换编辑模式 |\n| `web_editor_toggle_v2` | ✗ | ✓ | 切换编辑模式（V2） |\n| `web_editor_apply` | ✓ | ✓ | 应用变更 |\n\n资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:200-250]()\n\n## 状态管理\n\n### 等待策略\n\n编辑器内置网络空闲等待策略，用于确保页面完全加载后再进行操作：\n\n```typescript\nfunction waitForNetworkIdle(tabId: number, sniffMs = 2000): Promise {\n // 监听网络请求完成\n // 监听标签页更新\n // 监听 URL 变化\n // 超时自动结束\n}\n```\n\n资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts:1-50]()\n\n### 设计令牌\n\n编辑器使用设计令牌系统统一管理样式变量，确保界面一致性：\n\n```typescript\n// 设计令牌示例\nexport const tokens = {\n colors: {\n primary: '#xxx',\n secondary: '#xxx',\n },\n spacing: {\n small: '8px',\n medium: '16px',\n },\n};\n```\n\n## 扩展集成\n\n### 入口点配置\n\nmcp-chrome 扩展定义了多个入口点，编辑器作为 Sidepanel 页面的一部分运行：\n\n| 入口点 | 文件路径 | 用途 |\n|--------|----------|------|\n| sidepanel | `entrypoints/sidepanel/index.html` | 工作流管理主界面 |\n| builder | `entrypoints/builder/index.html` | 工作流编辑器 |\n| options | `entrypoints/options/index.html` | 用户脚本管理器 |\n| background | `entrypoints/background/` | 后台服务脚本 |\n\n资料来源：[app/chrome-extension/entrypoints/sidepanel/index.html:1-15]()\n\n### Web Accessible Resources\n\n编辑器通过 `web_accessible_resources` 配置允许注入脚本访问资源：\n\n```typescript\nweb_accessible_resources: [\n {\n resources: [\n '/models/*',\n '/workers/*',\n '/inject-scripts/*',\n ],\n matches: [''],\n },\n]\n```\n\n资料来源：[app/chrome-extension/wxt.config.ts:20-30]()\n\n## 使用示例\n\n### AI 辅助网页编辑\n\n用户可以让 AI Agent 帮助编辑当前网页：\n\n1. 打开目标网页\n2. 在 Sidepanel 中启动 AI 对话\n3. 使用 AgentChat 时间线追踪操作\n4. AI 通过 MCP 协议调用编辑器工具\n5. 编辑器将变更应用到页面\n\n### 工作流构建\n\n编辑器支持工作流模式，允许用户预先定义操作序列：\n\n1. 在 Builder 入口点创建工作流\n2. 定义触发条件和操作步骤\n3. 保存工作流配置\n4. 在需要时触发执行\n\n## 安全策略\n\n编辑器在生产环境启用以下安全策略：\n\n| 策略 | 配置值 | 用途 |\n|------|--------|------|\n| `cross_origin_embedder_policy` | `require-corp` | 跨源隔离 |\n| `cross_origin_opener_policy` | `same-origin` | 同源策略 |\n| `content_security_policy` | 定制规则 | 内容安全限制 |\n\n开发环境使用 WXT 默认策略，避免阻断开发服务器资源加载。资料来源：[app/chrome-extension/wxt.config.ts:35-50]()\n\n## 总结\n\n可视化编辑器是 mcp-chrome 项目的核心交互模块，通过结合 Chrome 扩展 API、MCP 协议和 AI Agent 技术，实现了自然语言驱动的网页编辑能力。其双版本架构确保了向后兼容性和持续演进，丰富的上下文菜单集成和脚本注入机制提供了灵活的使用方式。\n\n---\n\n\n\n## 语义搜索与向量数据库\n\n### 相关页面\n\n相关主题：[浏览器工具集](#browser-tools), [AI Agent 集成](#agent-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/utils/vector-database.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/vector-database.ts)\n- [app/chrome-extension/utils/semantic-similarity-engine.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/semantic-similarity-engine.ts)\n- [app/chrome-extension/utils/text-chunker.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/text-chunker.ts)\n- [app/chrome-extension/utils/simd-math-engine.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/simd-math-engine.ts)\n- [packages/wasm-simd/src/lib.rs](https://github.com/hangwin/mcp-chrome/blob/main/packages/wasm-simd/src/lib.rs)\n \n\n# 语义搜索与向量数据库\n\n## 概述\n\nmcp-chrome 扩展中的语义搜索与向量数据库模块为浏览器标签页内容提供了基于语义理解的智能搜索能力。该模块将网页文本内容转换为高维向量嵌入（Embedding），存储在本地向量数据库中，并支持通过语义相似度进行跨标签页内容检索。\n\n此功能的核心价值在于突破传统关键词搜索的局限性——用户可以使用自然语言描述来查找曾经访问过的内容，而无需记忆具体词汇或页面标题。\n\n## 核心架构\n\n### 模块组成\n\n| 模块 | 文件路径 | 主要职责 |\n|------|----------|----------|\n| 向量数据库 | `utils/vector-database.ts` | 存储和管理文本块向量嵌入 |\n| 语义相似度引擎 | `utils/semantic-similarity-engine.ts` | 生成文本嵌入并执行相似度计算 |\n| 文本分块器 | `utils/text-chunker.ts` | 将长文本分割为可管理的块 |\n| SIMD数学引擎 | `utils/simd-math-engine.ts` | 提供SIMD优化的向量运算 |\n| WASM SIMD模块 | `packages/wasm-simd/src/lib.rs` | Rust实现的SIMD计算后端 |\n\n### 架构图\n\n```mermaid\ngraph TD\n A[网页内容] --> B[内容索引器
content-indexer.ts]\n B --> C[文本分块器
text-chunker.ts]\n C --> D[语义相似度引擎
semantic-similarity-engine.ts]\n D --> E[SIMD数学引擎
simd-math-engine.ts]\n E --> F[WASM SIMD模块
Rust lib.rs]\n F --> G[向量数据库
vector-database.ts]\n G --> H[语义搜索查询]\n \n B -.->|网络请求| I[Inject Script
web-fetcher-helper.js]\n I --> B\n```\n\n## 工作流程\n\n### 内容索引流程\n\n当用户访问网页并完成加载后，系统自动触发以下索引流程：\n\n```mermaid\ngraph LR\n A[Tab加载完成] --> B{语义引擎就绪?}\n B -->|否| C[跳过索引]\n B -->|是| D[等待2秒缓冲]\n D --> E[提取页面内容]\n E --> F[执行web-fetcher-helper.js]\n F --> G[获取文本和标题]\n G --> H[文本分块]\n H --> I[生成向量嵌入]\n I --> J[存储至向量数据库]\n \n K[Tab关闭/导航] --> L[删除相关索引]\n```\n\n### URL过滤机制\n\n系统内置URL过滤规则，排除以下类型的地址不进行索引：\n\n```typescript\nconst excludePatterns = [\n /^chrome:\\/\\//, // Chrome内部页面\n /^chrome-extension:\\/\\//, // 扩展页面\n /^edge:\\/\\//, // Edge内部页面\n /^about:/, // about页面\n /^moz-extension:\\/\\//, // Firefox扩展\n /^file:\\/\\//, // 本地文件\n];\n```\n\n资料来源：[content-indexer.ts:55-61]()\n\n### 语义搜索流程\n\n```mermaid\ngraph TD\n A[用户查询] --> B[转换为向量]\n B --> C[向量数据库检索]\n C --> D[计算余弦相似度]\n D --> E[排序结果]\n E --> F[返回相关内容片段]\n```\n\n## 向量数据库\n\n向量数据库模块负责管理所有已索引内容的向量表示。每个向量条目包含以下信息：\n\n- **文本块内容**：原始文本片段\n- **向量嵌入**：由语义相似度引擎生成的高维向量\n- **元数据**：来源标签页ID、URL、时间戳等\n\n### 核心操作\n\n| 操作 | 说明 |\n|------|------|\n| 插入 | 添加新的向量条目 |\n| 删除 | 移除指定标签页的所有条目 |\n| 搜索 | 基于向量相似度返回相关内容 |\n| 更新 | 修改现有条目（通常不常用） |\n\n## 语义相似度引擎\n\n语义相似度引擎是将文本转换为向量嵌入的核心组件。它使用预训练的Transformer模型将任意文本映射到一个稠密的向量空间，使得语义相似的文本在该空间中距离较近。\n\n### 主要功能\n\n1. **嵌入生成**：将文本块转换为固定维度的浮点数向量\n2. **相似度计算**：使用余弦相似度或点积计算向量间的语义相似程度\n3. **批处理支持**：支持一次性处理多个文本块以提高效率\n\n## 文本分块器\n\n由于网页内容可能非常长，直接对整页内容生成单一向量会导致精度下降。文本分块器将长文本分割为适当大小的块，每个块独立生成向量。\n\n### 分块策略考量\n\n- **块大小**：需要在语义完整性和向量容量之间取得平衡\n- **重叠**：相邻块之间可能存在一定重叠，以避免边界语义丢失\n- **上下文保留**：分块时考虑句子和段落的自然边界\n\n## SIMD数学引擎\n\n为了在浏览器环境中实现高性能的向量运算，系统使用SIMD（单指令多数据）技术加速计算。\n\n### WASM SIMD模块\n\nRust实现的SIMD计算后端通过WebAssembly提供以下能力：\n\n- 向量点积计算\n- 向量归一化\n- 余弦相似度计算\n- 批量矩阵运算\n\n### 性能优化\n\n```mermaid\ngraph LR\n A[JavaScript向量运算] -->|慢| B[串行计算]\n A -->|快| C[SIMD向量化]\n C --> D[并行处理多条数据]\n D --> E[显著提升吞吐量]\n```\n\n使用SIMD指令集，单条CPU指令可以同时处理多个数据元素，这对于大规模向量运算（如搜索10万条记录）尤为重要。\n\n## 搜索标签页内容功能\n\n语义搜索系统的主要应用场景是跨标签页的语义检索。\n\n### 使用方式\n\n用户可以通过自然语言描述来搜索之前访问过的标签页内容。例如：\n\n- \"查找我昨天看的关于机器学习的文章\"\n- \"搜索包含Python代码示例的页面\"\n- \"找出讨论过向量数据库的标签\"\n\n### 技术实现\n\n1. 用户输入查询文本\n2. 系统将查询转换为向量\n3. 在向量数据库中执行相似度搜索\n4. 返回最相关的标签页和内容片段\n5. 提供快速跳转链接\n\n## 配置与状态管理\n\n### 引擎状态\n\n语义引擎维护以下状态：\n\n| 状态 | 说明 |\n|------|------|\n| 未初始化 | 引擎尚未加载 |\n| 初始化中 | 正在加载模型 |\n| 就绪 | 可接受索引和搜索请求 |\n| 错误 | 引擎发生错误 |\n\n### 自动索引控制\n\n```typescript\nif (this.options.autoIndex && changeInfo.status === 'complete' && tab.url) {\n setTimeout(() => {\n if (!this.isSemanticEngineReady() && !this.isSemanticEngineInitializing()) {\n return; // 跳过\n }\n this.indexTabContent(tabId);\n }, 2000);\n}\n```\n\n资料来源：[content-indexer.ts:27-40]()\n\n## 安全与隔离\n\n### 扩展页面隔离\n\n生产环境中启用以下安全策略：\n\n```typescript\ncross_origin_embedder_policy: { value: 'require-corp' },\ncross_origin_opener_policy: { value: 'same-origin' },\n```\n\n资料来源：[wxt.config.ts:44-47]()\n\n这些策略确保向量数据库和语义引擎的数据不会被恶意网页访问。\n\n### Web资源访问控制\n\n只有明确指定的资源可以被网页内容脚本访问：\n\n```typescript\nweb_accessible_resources: [\n '/models/*', // AI模型文件\n '/workers/*', // Web Workers\n '/inject-scripts/*' // 注入脚本\n]\n```\n\n资料来源：[wxt.config.ts:25-33]()\n\n## 性能优化策略\n\n### 延迟索引\n\n系统在页面加载完成2秒后才开始索引，避免阻塞页面渲染：\n\n```typescript\nsetTimeout(() => {\n this.indexTabContent(tabId);\n}, 2000);\n```\n\n资料来源：[content-indexer.ts:33]()\n\n### 条件索引\n\n只有当语义引擎完全就绪时才执行索引操作，避免因引擎未准备好而产生错误。\n\n### 导航事件监听\n\n系统监听多种导航事件以保持索引同步：\n\n- `tabs.onUpdated`：检测页面加载状态变化\n- `tabs.onRemoved`：删除关闭标签页的索引\n- `webNavigation.onCommitted`：检测主帧导航\n- `webNavigation.onHistoryStateUpdated`：检测SPA路由变化\n\n## 总结\n\nmcp-chrome的语义搜索与向量数据库模块为浏览器标签页提供了强大的语义理解能力。通过将网页内容转换为向量嵌入并存储在本地向量数据库中，用户可以使用自然语言进行跨标签页搜索。SIMD优化的数学引擎确保了计算性能，而完善的索引管理机制保证了搜索结果的实时性和准确性。\n\n---\n\n\n\n## AI Agent 集成\n\n### 相关页面\n\n相关主题：[本地服务器架构](#native-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/native-server/src/agent/engines/types.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/types.ts)\n- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)\n- [app/native-server/src/agent/engines/codex.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/codex.ts)\n- [app/native-server/src/agent/chat-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/chat-service.ts)\n- [app/native-server/src/agent/session-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/session-service.ts)\n- [app/chrome-extension/entrypoints/sidepanel/composables/useAgentChat.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/composables/useAgentChat.ts)\n- [app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts)\n \n\n# AI Agent 集成\n\n## 概述\n\nAI Agent 集成是 mcp-chrome 项目中连接浏览器扩展与本地 AI 引擎的核心模块。该系统支持多种 AI 引擎（包括 Claude 和 Codex），通过统一的接口抽象，为浏览器扩展提供智能代理能力。用户可以在浏览器侧边栏中与 AI Agent 对话，执行自动化工作流、网页内容分析和浏览器控制等任务。\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n subgraph 浏览器扩展\n A[Sidepanel UI] --> B[useAgentChat]\n A --> C[useAgentThreads]\n B --> D[MCP Tools]\n C --> D\n end\n \n subgraph 本地服务\n D --> E[ChromeMcpServer]\n E --> F[ChatService]\n E --> G[SessionService]\n F --> H[Engine Adapter]\n G --> H\n end\n \n subgraph AI 引擎\n H --> I[Claude Engine]\n H --> J[Codex Engine]\n end\n```\n\n### 核心组件关系\n\n| 组件 | 层级 | 职责 | 源码位置 |\n|------|------|------|----------|\n| `useAgentChat` | 前端 | 管理聊天状态、消息流、引擎选择 | `useAgentChat.ts` |\n| `useAgentThreads` | 前端 | 管理 Agent 线程和工具调用可视化 | `useAgentThreads.ts` |\n| `ChatService` | 服务层 | 协调 AI 引擎与 MCP 工具的交互 | `chat-service.ts` |\n| `SessionService` | 服务层 | 管理会话生命周期和元数据 | `session-service.ts` |\n| `ClaudeEngine` | 引擎层 | Claude API 集成实现 | `engines/claude.ts` |\n| `CodexEngine` | 引擎层 | Codex CLI 集成实现 | `engines/codex.ts` |\n\n## 引擎类型定义\n\n### 引擎基类与类型\n\n项目定义了统一的引擎抽象接口，支持多引擎并行：\n\n```typescript\nexport interface AgentEngine {\n name: string;\n provider: string;\n readonly: boolean;\n \n chat(options: ChatOptions): Promise>;\n destroy(): Promise;\n}\n```\n\n资料来源：[engines/types.ts:1-10]()\n\n### 支持的引擎类型\n\n| 引擎 | Provider | 说明 |\n|------|----------|------|\n| Claude | Anthropic | 使用 Claude SDK 进行对话 |\n| Codex | OpenAI | 使用 Codex CLI 进行代码任务 |\n\n## 会话管理\n\n### SessionService 功能\n\n`SessionService` 负责管理 AI Agent 会话的生命周期，提供了丰富的会话元数据管理能力。\n\n#### 管理信息接口\n\n```typescript\nexport interface ManagementInfo {\n models?: Array<{ value: string; displayName: string; description: string }>;\n commands?: Array<{ name: string; description: string; argumentHint: string }>;\n account?: { email?: string; organization?: string; subscriptionType?: string };\n mcpServers?: Array<{ name: string; status: string }>;\n tools?: string[];\n agents?: string[];\n plugins?: Array<{ name: string; path?: string }>;\n skills?: string[];\n slashCommands?: string[];\n model?: string;\n permissionMode?: string;\n cwd?: string;\n outputStyle?: string;\n betas?: string[];\n claudeCodeVersion?: string;\n apiKeySource?: string;\n lastUpdated?: string;\n}\n```\n\n资料来源：[session-service.ts:46-69]()\n\n#### 会话预览元数据\n\n```typescript\nexport interface AgentSessionPreviewMeta {\n displayText?: string;\n clientMeta?: {\n kind?: string;\n // 扩展元数据\n };\n}\n```\n\n资料来源：[session-service.ts:82-88]()\n\n### 会话配置选项\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `model` | string | 指定使用的模型 |\n| `mcpServers` | Record | MCP 服务器配置 |\n| `outputFormat` | Record | 输出格式配置 |\n| `enableFileCheckpointing` | boolean | 启用文件检查点 |\n| `sandbox` | Record | 沙箱环境配置 |\n| `env` | Record | 环境变量 |\n| `codexConfig` | Partial | Codex 特定配置覆盖 |\n\n## ChatService 协调层\n\n### 核心职责\n\n`ChatService` 作为中间协调层，负责：\n1. 接收来自扩展的聊天请求\n2. 路由到对应的 AI 引擎\n3. 处理工具调用和结果回传\n4. 管理会话状态\n\n### 消息流处理\n\n```mermaid\nsequenceDiagram\n participant EXT as 浏览器扩展\n participant CHAT as ChatService\n participant ENGINE as AI 引擎\n participant MCP as MCP Tools\n \n EXT->>CHAT: 发送用户消息\n CHAT->>ENGINE: 转发消息流\n ENGINE->>ENGINE: AI 处理\n ENGINE-->>CHAT: 返回 ChatProgress 流\n CHAT-->>EXT: 流式响应\n Note over ENGINE,MCP: 工具调用时\n ENGINE->>MCP: 请求工具执行\n MCP-->>ENGINE: 返回执行结果\n```\n\n## Claude 引擎集成\n\n### ClaudeEngine 实现\n\nClaude 引擎通过官方 Claude SDK 实现对话功能：\n\n```typescript\nexport class ClaudeEngine implements AgentEngine {\n name = 'claude';\n provider = 'anthropic';\n readonly = false;\n \n async *chat(options: ChatOptions): AsyncIterable {\n // SDK 集成实现\n }\n}\n```\n\n### 关键能力\n\n| 功能 | 支持 | 说明 |\n|------|------|------|\n| 流式输出 | ✅ | 支持实时流式响应 |\n| 工具调用 | ✅ | 支持 MCP 工具集成 |\n| 多模态 | ✅ | 支持图像输入 |\n| 会话保持 | ✅ | 维护对话上下文 |\n\n## Codex 引擎集成\n\n### CodexEngine 特性\n\nCodex 引擎通过 Codex CLI 实现，特别适用于代码任务：\n\n```typescript\nexport class CodexEngine implements AgentEngine {\n name = 'codex';\n provider = 'openai';\n readonly = false;\n \n async *chat(options: ChatOptions): AsyncIterable {\n // CLI 集成实现\n }\n}\n```\n\n### 配置参数\n\nCodex 引擎支持丰富的配置选项：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `include_apply_patch_tool` | boolean | true | 包含 apply_patch 工具 |\n| `include_plan_tool` | boolean | true | 包含计划工具 |\n| `enableWebSearch` | boolean | false | 启用网页搜索 |\n| `use_experimental_streamable_shell_tool` | boolean | - | 实验性流式 Shell 工具 |\n\n资料来源：[engines/codex.ts:buildCodexConfigArgs()]()\n\n### 项目上下文处理\n\nCodex 引擎自动检测项目目录结构：\n\n```typescript\n// 读取目录内容，排除 .git 和 AGENTS.md\nconst visible = entries\n .filter((entry) => !entry.name.startsWith('.git') && entry.name !== 'AGENTS.md')\n .map((entry) => entry.name);\n\n// 注入到系统提示\nreturn `${baseInstruction}\n\nCurrent files in project directory: ${visible.sort().join(', ')}\nWork directly in the current directory.\n`;\n```\n\n资料来源：[engines/codex.ts:appendProjectContext()]()\n\n## 前端集成\n\n### useAgentChat Composable\n\n`useAgentChat` 是前端与 AI Agent 通信的核心 Hook：\n\n```typescript\nexport function useAgentChat() {\n // 聊天状态管理\n // 消息发送与接收\n // 引擎切换\n // 流式响应处理\n}\n```\n\n#### 核心功能\n\n| 功能 | 方法 | 说明 |\n|------|------|------|\n| 发送消息 | `sendMessage()` | 发送用户消息 |\n| 流式接收 | 响应迭代器 | 处理 AI 流式输出 |\n| 引擎管理 | `switchEngine()` | 动态切换 AI 引擎 |\n| 中断控制 | `abort()` | 中断正在进行的请求 |\n\n### useAgentThreads Composable\n\n`useAgentThreads` 提供 Agent 线程管理，包括工具调用的可视化展示：\n\n```typescript\nexport function useAgentThreads() {\n // 线程列表管理\n // 工具调用记录\n // 状态追踪\n}\n```\n\n#### 工具调用分类\n\n系统根据工具名称和内容自动分类工具调用：\n\n| 类型 | 标签 | 判定规则 |\n|------|------|----------|\n| 计划 | Plan | toolName 包含 'plan' 或 'todo' |\n| 编辑 | Edit | toolName 包含 'edit' 或 'patch' |\n| 写入 | Write | toolName 包含 'write' 或 'create_file' |\n| 命令 | Run | toolName 包含 'bash' 或 'shell' |\n| 搜索 | Grep | toolName 包含 'grep' 或 'search' |\n\n资料来源：[useAgentThreads.ts:工具分类规则]()\n\n#### DiffStats 结构\n\n```typescript\ninterface DiffStats {\n added?: number;\n removed?: number;\n unchanged?: number;\n filesChanged?: number;\n}\n```\n\n资料来源：[useAgentThreads.ts:buildDiffStats()]()\n\n## 工具调用可视化\n\n### 消息元数据结构\n\n每个工具调用消息包含丰富的元数据：\n\n```typescript\ninterface ToolCallMeta {\n toolName?: string;\n filePath?: string;\n command?: string;\n commandDescription?: string;\n pattern?: string;\n searchPath?: string;\n isError?: boolean;\n files?: string[];\n planPhase?: string;\n todoCount?: number;\n output?: string;\n}\n```\n\n### 严重性级别\n\n| 级别 | 触发条件 | 显示样式 |\n|------|----------|----------|\n| success | 工具成功执行且 phase === 'result' | 绿色 |\n| error | is_error === true 或内容以 'Error:' 开头 | 红色 |\n| info | 工具执行中或普通信息 | 蓝色 |\n| warning | 子流超过最大迭代次数 | 黄色 |\n\n资料来源：[useAgentThreads.ts:severity 判断逻辑]()\n\n## 配置与扩展\n\n### 引擎配置优先级\n\n```\n命令行参数 > 环境变量 > 配置文件 > 默认值\n```\n\n### 可扩展性设计\n\n项目采用适配器模式支持新引擎：\n\n```typescript\n// 注册新引擎\nexport function registerEngine(engine: AgentEngine): void;\n\n// 创建引擎工厂\nexport function createEngine(type: EngineType, config: EngineConfig): AgentEngine;\n```\n\n## 最佳实践\n\n### 1. 引擎选择建议\n\n| 场景 | 推荐引擎 | 原因 |\n|------|----------|------|\n| 通用对话 | Claude | 对话能力强 |\n| 代码任务 | Codex | CLI 集成更紧密 |\n| 快速原型 | Claude | 配置简单 |\n\n### 2. 会话管理建议\n\n- 定期清理不活跃会话以节省存储\n- 使用 `displayText` 提供有意义的会话预览\n- 通过 `clientMeta` 标记特殊会话类型\n\n### 3. 错误处理\n\n```typescript\nconst isError =\n meta.is_error === true ||\n meta.isError === true ||\n (typeof msg.content === 'string' && msg.content.trimStart().startsWith('Error:'));\n```\n\n确保前端能正确处理和展示错误状态。\n\n## 总结\n\nAI Agent 集成模块通过统一的接口抽象和多引擎支持，为 mcp-chrome 提供了灵活且强大的 AI 能力。该架构设计遵循了开闭原则，便于后续添加新的 AI 引擎。前端组件 `useAgentChat` 和 `useAgentThreads` 提供了良好的用户交互体验，而服务层的 `ChatService` 和 `SessionService` 则确保了业务逻辑的清晰分离。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：hangwin/mcp-chrome\n\n摘要：发现 15 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint。\n\n## 1. 安装坑 · 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba76885913a744f0832665f5c62d0f1d | https://github.com/hangwin/mcp-chrome/issues/321 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ac5f778b292489482bfdb7953190f96 | https://github.com/hangwin/mcp-chrome/issues/319 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_559f34b86ade48e598dac510e9341b9e | https://github.com/hangwin/mcp-chrome/issues/339 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：mcp-chrome-bridge 无法使用\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：mcp-chrome-bridge 无法使用\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f19fb6526174af2abe5c1eab67e25ff | https://github.com/hangwin/mcp-chrome/issues/333 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b32536c95a7456788ba78e1fc705116 | https://github.com/hangwin/mcp-chrome/issues/342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | host_targets=mcp_host, claude\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:998796026 | https://github.com/hangwin/mcp-chrome | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：v0.0.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_035dffafcbe64f4ea112f20258430e71 | https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：issue\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：issue\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82ad93635a5e4ff5aeb2b35e36cbd02e | https://github.com/hangwin/mcp-chrome/issues/330 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 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:998796026 | https://github.com/hangwin/mcp-chrome | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | release_recency=unknown\n\n\n",
"markdown_key": "mcp-chrome",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:998796026",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/hangwin/mcp-chrome"
},
{
"evidence_id": "art_cb521702df06461cb0d74036692bd3d5",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/hangwin/mcp-chrome#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mcp-chrome 说明书",
"toc": [
"https://github.com/hangwin/mcp-chrome 项目说明书",
"目录",
"项目介绍",
"概述",
"系统架构",
"工具功能体系",
"工作流引擎",
"数据存储",
"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": "f48e71751e00bc09725c7e173423cff4f2ccd12a",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/ISSUE.md",
"docs/VisualEditor.md",
"docs/TROUBLESHOOTING.md",
"docs/mcp-cli-config.md",
"docs/ARCHITECTURE.md",
"docs/TOOLS.md",
"docs/ARCHITECTURE_zh.md",
"docs/TROUBLESHOOTING_zh.md",
"docs/WINDOWS_INSTALL_zh.md",
"docs/CONTRIBUTING.md",
"docs/VisualEditor_zh.md",
"docs/CONTRIBUTING_zh.md",
"docs/TOOLS_zh.md",
"docs/CHANGELOG.md",
"packages/wasm-simd/Cargo.toml",
"packages/wasm-simd/package.json",
"packages/wasm-simd/README.md",
"packages/wasm-simd/BUILD.md",
"packages/shared/package.json",
"packages/shared/tsconfig.json",
"packages/shared/src/node-spec.ts",
"packages/shared/src/tools.ts",
"packages/shared/src/constants.ts",
"packages/shared/src/node-spec-registry.ts",
"packages/shared/src/index.ts",
"packages/shared/src/types.ts",
"packages/shared/src/rr-graph.ts",
"packages/shared/src/agent-types.ts",
"packages/shared/src/step-types.ts",
"packages/shared/src/labels.ts",
"packages/shared/src/node-specs-builtin.ts"
],
"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": "# mcp-chrome-bridge-monorepo - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 mcp-chrome-bridge-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_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g mcp-chrome-bridge` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\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_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` 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- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：652\n- 重要文件覆盖：40/652\n- 证据索引条目：52\n- 角色 / Skill 条目：26\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请基于 mcp-chrome-bridge-monorepo 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 mcp-chrome-bridge-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请基于 mcp-chrome-bridge-monorepo 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 26 个角色 / Skill / 项目文档条目。\n\n- **Contributing Guide 🤝**（project_doc）：Thank you for your interest in contributing to Chrome MCP Server! This document provides guidelines and information for contributors. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONTRIBUTING.md`\n- **Chrome MCP Server 🚀**（project_doc）：! Stars https://img.shields.io/github/stars/hangwin/mcp-chrome https://img.shields.io/github/stars/hangwin/mcp-chrome ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! TypeScript https://img.shields.io/badge/TypeScript-5.8+-blue.svg https://www.typescriptlang.org/ ! Chrome Extension https://img.shields.io/badge/Chrome-Extension-green.svg https://developer.chrome… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Chrome MCP Server Extension - Latest Release**（project_doc）：Chrome MCP Server Extension - Latest Release 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`releases/README.md`\n- **WXT + Vue 3**（project_doc）：This template should help get you started developing with Vue 3 in WXT. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`app/chrome-extension/README.md`\n- **Fastify Chrome Native Messaging服务**（project_doc）：这是一个基于Fastify的TypeScript项目，用于与Chrome扩展进行原生通信。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`app/native-server/README.md`\n- **@chrome-mcp/wasm-simd**（project_doc）：SIMD-optimized WebAssembly math functions for high-performance vector operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/wasm-simd/README.md`\n- **Chrome MCP Bridge 安装指南**（project_doc）：本文档详细说明了 Chrome MCP Bridge 的安装和注册流程。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`app/native-server/install.md`\n- **Chrome MCP Server Architecture 🏗️**（project_doc）：This document provides a detailed technical overview of the Chrome MCP Server architecture, design decisions, and implementation details. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ARCHITECTURE.md`\n- **Chrome MCP Server 架构设计 🏗️**（project_doc）：本文档提供 Chrome MCP Server 架构、设计决策和实现细节的详细技术概述。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ARCHITECTURE_zh.md`\n- **Changelog**（project_doc）：All notable changes to this project will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CHANGELOG.md`\n- **贡献指南 🤝**（project_doc）：感谢您对 Chrome MCP Server 项目的贡献兴趣！本文档为贡献者提供指南和信息。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONTRIBUTING_zh.md`\n- **Issues 总览**（project_doc）：- 总Issue数 : 183 - 开放中 : 116 - 已关闭 : 67 - 关闭率 : 36.6% - 最后更新 : 2025-10-11 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ISSUE.md`\n- **Chrome MCP Server API Reference 📚**（project_doc）：Complete reference for all available tools and their parameters. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS.md`\n- **Chrome MCP Server API 参考 📚**（project_doc）：- 浏览器管理 浏览器管理 - 截图和视觉 截图和视觉 - 网络监控 网络监控 - 内容分析 内容分析 - 交互操作 交互操作 - 数据管理 数据管理 - 响应格式 响应格式 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS_zh.md`\n- **🚀 Installation and Connection Issues**（project_doc）：🚀 Installation and Connection Issues 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.md`\n- **🚀 安装和连接问题**（project_doc）：bash 打印 Markdown 报告到终端（复制粘贴到 GitHub Issue） mcp-chrome-bridge report 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING_zh.md`\n- **A Visual Editor for Claude Code & Codex**（project_doc）：A Visual Editor for Claude Code & Codex 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/VisualEditor.md`\n- **让Claude Code/Codex也能使用的可视化编辑器**（project_doc）：如何开启： 右键 chrome mcp server 切换网页编辑模式 或者快捷键： cmd/ctrl + shift + o 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/VisualEditor_zh.md`\n- **windows 安装指南 🔧**（project_doc）：Chrome MCP Server 在windows电脑的详细安装和配置步骤 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/WINDOWS_INSTALL_zh.md`\n- **CLI MCP Configuration Guide**（project_doc）：This guide explains how to configure Codex CLI and Claude Code to connect to the Chrome MCP Server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/mcp-cli-config.md`\n- **Chrome MCP Server 🚀**（project_doc）：! 许可证: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! TypeScript https://img.shields.io/badge/TypeScript-5.8+-blue.svg https://www.typescriptlang.org/ ! Chrome 扩展 https://img.shields.io/badge/Chrome-Extension-green.svg https://developer.chrome.com/docs/extensions/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README_zh.md`\n- **Role:**（project_doc）：- 背景 : 拥有超过10年的内容分析与信息设计经验。 - 专长 : 1. 认知简化 : 能将复杂、零散的知识快速转化为结构清晰、易于理解的框架。 2. 逻辑提炼 : 擅长识别信息背后的核心逻辑、因果关系和层级结构。 3. 视觉叙事 : 是Excalidraw的顶级专家，精通利用其简洁的工具集构建富有表现力和洞察力的视觉化图表。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`prompt/content-analize.md`\n- **角色**（project_doc）：你是一位顶级的解决方案架构师，不仅精通复杂的系统设计，更是Excalidraw的专家级用户。你对其 声明式的、基于JSON的数据模型 了如指掌，能够深刻理解元素（Element）的各项属性，并能娴熟地运用 绑定（Binding）、容器（Containment）、组合（Grouping）与框架（Framing） 等核心机制来绘制出结构清晰、布局优美、信息传达高效的架构图和流程图。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`prompt/excalidraw-prompt.md`\n- **Role:**（project_doc）：- 背景 : 超过10年的前端开发经验，尤其在Chrome/Firefox扩展开发、Content Scripts编写和DOM性能优化方面有深厚造诣。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`prompt/modify-web.md`\n- **Property Panel UI 重构计划**（project_doc）：当前属性面板的 UI 实现与设计稿 attr-ui.html 存在较大差异。本文档详细规划了重构任务，按照优先级从高到低排列，目标是让属性面板的视觉效果和交互体验与设计稿一致。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`app/chrome-extension/entrypoints/web-editor-v2/attr-ui-refactor.md`\n- **WASM SIMD 构建指南**（project_doc）：bash 安装 Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs sh 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/wasm-simd/BUILD.md`\n\n## 证据索引\n\n- 共索引 52 条证据。\n\n- **Contributing Guide 🤝**（documentation）：Thank you for your interest in contributing to Chrome MCP Server! This document provides guidelines and information for contributors. 证据：`docs/CONTRIBUTING.md`\n- **Chrome MCP Server 🚀**（documentation）：! Stars https://img.shields.io/github/stars/hangwin/mcp-chrome https://img.shields.io/github/stars/hangwin/mcp-chrome ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! TypeScript https://img.shields.io/badge/TypeScript-5.8+-blue.svg https://www.typescriptlang.org/ ! Chrome Extension https://img.shields.io/badge/Chrome-Extension-green.svg https://developer.chrome.com/docs/extensions/ ! Release https://img.shields.io/github/v/release/hangwin/mcp-chrome.svg https://img.shields.io/github/v/release/hangwin/mcp-chrome.svg 证据：`README.md`\n- **Chrome MCP Server Extension - Latest Release**（documentation）：Chrome MCP Server Extension - Latest Release 证据：`releases/README.md`\n- **WXT + Vue 3**（documentation）：This template should help get you started developing with Vue 3 in WXT. 证据：`app/chrome-extension/README.md`\n- **Fastify Chrome Native Messaging服务**（documentation）：这是一个基于Fastify的TypeScript项目，用于与Chrome扩展进行原生通信。 证据：`app/native-server/README.md`\n- **@chrome-mcp/wasm-simd**（documentation）：SIMD-optimized WebAssembly math functions for high-performance vector operations. 证据：`packages/wasm-simd/README.md`\n- **Package**（package_manifest）：{ \"name\": \"mcp-chrome-bridge-monorepo\", \"version\": \"1.0.0\", \"private\": true, \"author\": \"hangye\", \"type\": \"module\", \"scripts\": { \"build:shared\": \"pnpm --filter chrome-mcp-shared build\", \"build:native\": \"pnpm --filter mcp-chrome-bridge build\", \"build:extension\": \"pnpm --filter chrome-mcp-server build\", \"build:wasm\": \"pnpm --filter @chrome-mcp/wasm-simd build && pnpm run copy:wasm\", \"build\": \"pnpm -r --filter='!@chrome-mcp/wasm-simd' build\", \"copy:wasm\": \"cp ./packages/wasm-simd/pkg/simd math.js ./packages/wasm-simd/pkg/simd math bg.wasm ./app/chrome-extension/workers/\", \"dev:shared\": \"pnpm --filter chrome-mcp-shared dev\", \"dev:native\": \"pnpm --filter mcp-chrome-bridge dev\", \"dev:extension\": \"… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"chrome-mcp-server\", \"description\": \"a chrome extension to use your own chrome as a mcp server\", \"author\": \"hangye\", \"private\": true, \"version\": \"1.0.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"wxt\", \"dev:firefox\": \"wxt -b firefox\", \"build\": \"wxt build\", \"build:firefox\": \"wxt build -b firefox\", \"zip\": \"wxt zip\", \"zip:firefox\": \"wxt zip -b firefox\", \"compile\": \"vue-tsc --noEmit\", \"postinstall\": \"wxt prepare\", \"lint\": \"npx eslint .\", \"lint:fix\": \"npx eslint . --fix\", \"format\": \"npx prettier --write .\", \"format:check\": \"npx prettier --check .\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.11.0\", \"@vue-flow/background\": \"^1.3.2\", \"@… 证据：`app/chrome-extension/package.json`\n- **Package**（package_manifest）：{ \"name\": \"mcp-chrome-bridge\", \"version\": \"1.0.29\", \"description\": \"Chrome Native-Messaging host Node \", \"main\": \"dist/index.js\", \"bin\": { \"mcp-chrome-bridge\": \"./dist/cli.js\", \"chrome-mcp-bridge\": \"./dist/cli.js\", \"mcp-chrome-stdio\": \"./dist/mcp/mcp-server-stdio.js\" }, \"scripts\": { \"dev\": \"nodemon --watch src --ext ts,js,json --ignore dist/ --exec \\\"npm run build && npm run register:dev\\\"\", \"build\": \"ts-node src/scripts/build.ts\", \"test\": \"jest\", \"test:watch\": \"jest --watch\", \"lint\": \"eslint 'src/ / .{js,ts}'\", \"lint:fix\": \"eslint 'src/ / .{js,ts}' --fix\", \"format\": \"prettier --write 'src/ / .{js,ts,json}'\", \"register:dev\": \"node dist/scripts/register-dev.js\", \"postinstall\": \"node dist/scr… 证据：`app/native-server/package.json`\n- **Package**（package_manifest）：{ \"name\": \"chrome-mcp-shared\", \"version\": \"1.0.1\", \"author\": \"hangye\", \"main\": \"dist/index.js\", \"module\": \"./dist/index.mjs\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"import\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.mjs\" }, \"require\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" } } }, \"scripts\": { \"build\": \"tsup src/index.ts --format cjs,esm --dts --clean\", \"dev\": \"tsup src/index.ts --format cjs,esm --dts --watch\", \"lint\": \"npx eslint 'src/ / .{js,ts}'\", \"lint:fix\": \"npx eslint 'src/ / .{js,ts}' --fix\", \"format\": \"prettier --write 'src/ / .{js,ts,json}'\" }, \"files\": \"dist\" , \"devDependencies\": { \"@types/node\": \"^18.0.0\", \"@typescript-eslint/parser\":… 证据：`packages/shared/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@chrome-mcp/wasm-simd\", \"version\": \"0.1.0\", \"description\": \"SIMD-optimized WebAssembly math functions for Chrome MCP\", \"main\": \"pkg/simd math.js\", \"types\": \"pkg/simd math.d.ts\", \"files\": \"pkg/\" , \"scripts\": { \"build\": \"wasm-pack build --target web --out-dir pkg --release\", \"build:dev\": \"wasm-pack build --target web --out-dir pkg --dev\", \"clean\": \"rimraf pkg/\", \"test\": \"wasm-pack test --headless --firefox\" }, \"keywords\": \"wasm\", \"simd\", \"webassembly\", \"math\", \"cosine-similarity\", \"vector-operations\" , \"author\": \"hangye\", \"license\": \"MIT\", \"devDependencies\": { \"rimraf\": \"^5.0.0\" }, \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/your-repo/chrome-mcp-server.git\", \"dire… 证据：`packages/wasm-simd/package.json`\n- **Chrome MCP Bridge 安装指南**（documentation）：本文档详细说明了 Chrome MCP Bridge 的安装和注册流程。 证据：`app/native-server/install.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`app/chrome-extension/LICENSE`\n- **Chrome MCP Server Architecture 🏗️**（documentation）：This document provides a detailed technical overview of the Chrome MCP Server architecture, design decisions, and implementation details. 证据：`docs/ARCHITECTURE.md`\n- **Chrome MCP Server 架构设计 🏗️**（documentation）：本文档提供 Chrome MCP Server 架构、设计决策和实现细节的详细技术概述。 证据：`docs/ARCHITECTURE_zh.md`\n- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`docs/CHANGELOG.md`\n- **贡献指南 🤝**（documentation）：感谢您对 Chrome MCP Server 项目的贡献兴趣！本文档为贡献者提供指南和信息。 证据：`docs/CONTRIBUTING_zh.md`\n- **Issues 总览**（documentation）：- 总Issue数 : 183 - 开放中 : 116 - 已关闭 : 67 - 关闭率 : 36.6% - 最后更新 : 2025-10-11 证据：`docs/ISSUE.md`\n- **Chrome MCP Server API Reference 📚**（documentation）：Complete reference for all available tools and their parameters. 证据：`docs/TOOLS.md`\n- **Chrome MCP Server API 参考 📚**（documentation）：- 浏览器管理 浏览器管理 - 截图和视觉 截图和视觉 - 网络监控 网络监控 - 内容分析 内容分析 - 交互操作 交互操作 - 数据管理 数据管理 - 响应格式 响应格式 证据：`docs/TOOLS_zh.md`\n- **🚀 Installation and Connection Issues**（documentation）：🚀 Installation and Connection Issues 证据：`docs/TROUBLESHOOTING.md`\n- **🚀 安装和连接问题**（documentation）：bash 打印 Markdown 报告到终端（复制粘贴到 GitHub Issue） mcp-chrome-bridge report 证据：`docs/TROUBLESHOOTING_zh.md`\n- **A Visual Editor for Claude Code & Codex**（documentation）：A Visual Editor for Claude Code & Codex 证据：`docs/VisualEditor.md`\n- **让Claude Code/Codex也能使用的可视化编辑器**（documentation）：如何开启： 右键 chrome mcp server 切换网页编辑模式 或者快捷键： cmd/ctrl + shift + o 证据：`docs/VisualEditor_zh.md`\n- **windows 安装指南 🔧**（documentation）：Chrome MCP Server 在windows电脑的详细安装和配置步骤 证据：`docs/WINDOWS_INSTALL_zh.md`\n- **CLI MCP Configuration Guide**（documentation）：This guide explains how to configure Codex CLI and Claude Code to connect to the Chrome MCP Server. 证据：`docs/mcp-cli-config.md`\n- **Chrome MCP Server 🚀**（documentation）：! 许可证: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! TypeScript https://img.shields.io/badge/TypeScript-5.8+-blue.svg https://www.typescriptlang.org/ ! Chrome 扩展 https://img.shields.io/badge/Chrome-Extension-green.svg https://developer.chrome.com/docs/extensions/ 证据：`README_zh.md`\n- **Role:**（documentation）：- 背景 : 拥有超过10年的内容分析与信息设计经验。 - 专长 : 1. 认知简化 : 能将复杂、零散的知识快速转化为结构清晰、易于理解的框架。 2. 逻辑提炼 : 擅长识别信息背后的核心逻辑、因果关系和层级结构。 3. 视觉叙事 : 是Excalidraw的顶级专家，精通利用其简洁的工具集构建富有表现力和洞察力的视觉化图表。 证据：`prompt/content-analize.md`\n- **角色**（documentation）：你是一位顶级的解决方案架构师，不仅精通复杂的系统设计，更是Excalidraw的专家级用户。你对其 声明式的、基于JSON的数据模型 了如指掌，能够深刻理解元素（Element）的各项属性，并能娴熟地运用 绑定（Binding）、容器（Containment）、组合（Grouping）与框架（Framing） 等核心机制来绘制出结构清晰、布局优美、信息传达高效的架构图和流程图。 证据：`prompt/excalidraw-prompt.md`\n- **Role:**（documentation）：- 背景 : 超过10年的前端开发经验，尤其在Chrome/Firefox扩展开发、Content Scripts编写和DOM性能优化方面有深厚造诣。 证据：`prompt/modify-web.md`\n- **Property Panel UI 重构计划**（documentation）：当前属性面板的 UI 实现与设计稿 attr-ui.html 存在较大差异。本文档详细规划了重构任务，按照优先级从高到低排列，目标是让属性面板的视觉效果和交互体验与设计稿一致。 证据：`app/chrome-extension/entrypoints/web-editor-v2/attr-ui-refactor.md`\n- **WASM SIMD 构建指南**（documentation）：bash 安装 Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs sh 证据：`packages/wasm-simd/BUILD.md`\n- **.Prettierrc**（structured_config）：{ \"semi\": true, \"singleQuote\": true, \"tabWidth\": 2, \"printWidth\": 100, \"endOfLine\": \"auto\", \"proseWrap\": \"preserve\", \"htmlWhitespaceSensitivity\": \"strict\" } 证据：`.prettierrc.json`\n- **Messages**（structured_config）：{ \"extensionName\": { \"message\": \"chrome-mcp-server\", \"description\": \"Erweiterungsname\" }, \"extensionDescription\": { \"message\": \"Stellt Browser-Funktionen mit Ihrem eigenen Chrome zur Verfügung\", \"description\": \"Erweiterungsbeschreibung\" }, \"nativeServerConfigLabel\": { \"message\": \"Native Server-Konfiguration\", \"description\": \"Hauptabschnittstitel für Native Server-Einstellungen\" }, \"semanticEngineLabel\": { \"message\": \"Semantische Engine\", \"description\": \"Hauptabschnittstitel für semantische Engine\" }, \"embeddingModelLabel\": { \"message\": \"Embedding-Modell\", \"description\": \"Hauptabschnittstitel für Modellauswahl\" }, \"indexDataManagementLabel\": { \"message\": \"Index-Datenverwaltung\", \"description… 证据：`app/chrome-extension/_locales/de/messages.json`\n- **Messages**（structured_config）：{ \"extensionName\": { \"message\": \"chrome-mcp-server\", \"description\": \"Extension name\" }, \"extensionDescription\": { \"message\": \"Exposes browser capabilities with your own chrome\", \"description\": \"Extension description\" }, \"nativeServerConfigLabel\": { \"message\": \"Native Server Configuration\", \"description\": \"Main section header for native server settings\" }, \"semanticEngineLabel\": { \"message\": \"Semantic Engine\", \"description\": \"Main section header for semantic engine\" }, \"embeddingModelLabel\": { \"message\": \"Embedding Model\", \"description\": \"Main section header for model selection\" }, \"indexDataManagementLabel\": { \"message\": \"Index Data Management\", \"description\": \"Main section header for data… 证据：`app/chrome-extension/_locales/en/messages.json`\n- **Messages**（structured_config）：{ \"extensionName\": { \"message\": \"Chrome MCPサーバー\" }, \"extensionDescription\": { \"message\": \"自身のChromeブラウザの機能を外部に公開します\" }, \"nativeServerConfigLabel\": { \"message\": \"ネイティブサーバー設定\" }, \"semanticEngineLabel\": { \"message\": \"セマンティックエンジン\" }, \"embeddingModelLabel\": { \"message\": \"埋め込みモデル\" }, \"indexDataManagementLabel\": { \"message\": \"インデックスデータ管理\" }, \"modelCacheManagementLabel\": { \"message\": \"モデルキャッシュ管理\" }, \"statusLabel\": { \"message\": \"ステータス\" }, \"runningStatusLabel\": { \"message\": \"実行ステータス\" }, \"connectionStatusLabel\": { \"message\": \"接続ステータス\" }, \"lastUpdatedLabel\": { \"message\": \"最終更新:\" }, \"connectButton\": { \"message\": \"接続\" }, \"disconnectButton\": { \"message\": \"切断\" }, \"connectingStatus\": { \"message\": \"接続中...\" }… 证据：`app/chrome-extension/_locales/ja/messages.json`\n- **Messages**（structured_config）：{ \"extensionName\": { \"message\": \"chrome-mcp-server\", \"description\": \"확장 프로그램 이름\" }, \"extensionDescription\": { \"message\": \"크롬 브라우저와 연동하여 브라우저 기능을 제어하는 MCP 서버입니다.\", \"description\": \"확장 프로그램 설명\" }, \"nativeServerConfigLabel\": { \"message\": \"네이티브 서버 설정\", \"description\": \"네이티브 서버 설정의 주 섹션 제목\" }, \"semanticEngineLabel\": { \"message\": \"시맨틱 엔진\", \"description\": \"시맨틱 엔진의 주 섹션 제목\" }, \"embeddingModelLabel\": { \"message\": \"임베딩 모델\", \"description\": \"모델 선택의 주 섹션 제목\" }, \"indexDataManagementLabel\": { \"message\": \"인덱스 데이터 관리\", \"description\": \"데이터 관리의 주 섹션 제목\" }, \"modelCacheManagementLabel\": { \"message\": \"모델 캐시 관리\", \"description\": \"캐시 관리의 주 섹션 제목\" }, \"statusLabel\": { \"message\": \"상태\", \"description\": \"일반 상태 레이블\" }, \"run… 证据：`app/chrome-extension/_locales/ko/messages.json`\n- **Messages**（structured_config）：{ \"extensionName\": { \"message\": \"chrome-mcp-server\", \"description\": \"扩展名称\" }, \"extensionDescription\": { \"message\": \"使用你自己的 Chrome 浏览器暴露浏览器功能\", \"description\": \"扩展描述\" }, \"nativeServerConfigLabel\": { \"message\": \"Native Server 配置\", \"description\": \"本地服务器设置的主要节标题\" }, \"semanticEngineLabel\": { \"message\": \"语义引擎\", \"description\": \"语义引擎的主要节标题\" }, \"embeddingModelLabel\": { \"message\": \"Embedding模型\", \"description\": \"模型选择的主要节标题\" }, \"indexDataManagementLabel\": { \"message\": \"索引数据管理\", \"description\": \"数据管理的主要节标题\" }, \"modelCacheManagementLabel\": { \"message\": \"模型缓存管理\", \"description\": \"缓存管理的主要节标题\" }, \"statusLabel\": { \"message\": \"状态\", \"description\": \"通用状态标签\" }, \"runningStatusLabel\": { \"message\": \"运行状态\", \"descriptio… 证据：`app/chrome-extension/_locales/zh_CN/messages.json`\n- **Messages**（structured_config）：{ \"extensionName\": { \"message\": \"chrome-mcp-server\", \"description\": \"擴充功能名稱\" }, \"extensionDescription\": { \"message\": \"使用您自己的 Chrome 瀏覽器暴露瀏覽器功能\", \"description\": \"擴充功能描述\" }, \"nativeServerConfigLabel\": { \"message\": \"原生伺服器設定\", \"description\": \"本機伺服器設定的主要區段標題\" }, \"semanticEngineLabel\": { \"message\": \"語意引擎\", \"description\": \"語意引擎的主要區段標題\" }, \"embeddingModelLabel\": { \"message\": \"Embedding 模型\", \"description\": \"模型選擇的主要區段標題\" }, \"indexDataManagementLabel\": { \"message\": \"索引資料管理\", \"description\": \"資料管理主要區段標題\" }, \"modelCacheManagementLabel\": { \"message\": \"模型快取管理\", \"description\": \"快取管理主要區段標題\" }, \"statusLabel\": { \"message\": \"狀態\", \"description\": \"通用狀態標籤\" }, \"runningStatusLabel\": { \"message\": \"執行狀態\", \"description… 证据：`app/chrome-extension/_locales/zh_TW/messages.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"./.wxt/tsconfig.json\" } 证据：`app/chrome-extension/tsconfig.json`\n- **Stdio Config**（structured_config）：{ \"url\": \"http://127.0.0.1:12306/mcp\" } 证据：`app/native-server/src/mcp/stdio-config.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2018\", \"module\": \"NodeNext\", \"moduleResolution\": \"NodeNext\", \"lib\": \"ES2018\", \"DOM\" , \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"esModuleInterop\": true, \"forceConsistentCasingInFileNames\": true, \"skipLibCheck\": true, \"declaration\": true, \"sourceMap\": true, \"resolveJsonModule\": true, \"baseUrl\": \".\", \"paths\": { \"chrome-devtools-frontend/ \": \"src/shims/devtools.d.ts\" } }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \" / .spec.ts\", \" / .test.ts\" } 证据：`app/native-server/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2020\", \"module\": \"NodeNext\", \"moduleResolution\": \"NodeNext\", \"esModuleInterop\": true, \"declaration\": true, \"outDir\": \"./dist\", \"strict\": true, \"skipLibCheck\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\" } 证据：`packages/shared/tsconfig.json`\n- **.gitattributes**（source_file）：.onnx filter=lfs diff=lfs merge=lfs -text 证据：`.gitattributes`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log pnpm-debug.log lerna-debug.log 证据：`.gitignore`\n- **Commit Msg**（source_file）：npx --no -- commitlint --edit \"$1\" 证据：`.husky/commit-msg`\n- **Pre Commit**（source_file）：npx lint-staged 证据：`.husky/pre-commit`\n- **构建输出目录**（source_file）：编辑器配置 .vscode !.vscode/extensions.json .idea 证据：`.prettierignore`\n- **Commitlint.Config**（source_file）：module.exports = { extends: '@commitlint/config-conventional' , }; 证据：`commitlint.config.cjs`\n- **Eslint.Config**（source_file）：import globals from 'globals'; import js from '@eslint/js'; import tseslint from 'typescript-eslint'; import eslintConfigPrettier from 'eslint-config-prettier'; 证据：`eslint.config.js`\n- **Pnpm Workspace**（source_file）：packages: - 'app/ ' - 'packages/ ' 证据：`pnpm-workspace.yaml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/CONTRIBUTING.md`, `README.md`, `releases/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/CONTRIBUTING.md`, `README.md`, `releases/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- **项目介绍**：importance `high`\n - source_paths: README.md, README_zh.md\n- **快速开始**：importance `high`\n - source_paths: app/chrome-extension/package.json, app/native-server/package.json, app/native-server/install.md\n- **系统架构设计**：importance `high`\n - source_paths: docs/ARCHITECTURE.md, docs/ARCHITECTURE_zh.md, app/chrome-extension/entrypoints/background/index.ts, app/native-server/src/index.ts\n- **Chrome 扩展架构**：importance `high`\n - source_paths: app/chrome-extension/entrypoints/background/index.ts, app/chrome-extension/entrypoints/content.ts, app/chrome-extension/wxt.config.ts, app/chrome-extension/common/constants.ts\n- **本地服务器架构**：importance `high`\n - source_paths: app/native-server/src/server/index.ts, app/native-server/src/mcp/mcp-server.ts, app/native-server/src/agent/engines/claude.ts, app/native-server/src/agent/tool-bridge.ts\n- **浏览器工具集**：importance `high`\n - source_paths: docs/TOOLS.md, docs/TOOLS_zh.md, app/chrome-extension/entrypoints/background/tools/browser/index.ts, app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts, app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts\n- **录制回放系统 (V3)**：importance `medium`\n - source_paths: app/chrome-extension/entrypoints/background/record-replay-v3/index.ts, app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/kernel.ts, app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/index.ts, app/chrome-extension/entrypoints/background/record-replay-v3/domain/flow.ts\n- **可视化编辑器**：importance `medium`\n - source_paths: docs/VisualEditor.md, docs/VisualEditor_zh.md, app/chrome-extension/entrypoints/web-editor-v2/core/editor.ts, app/chrome-extension/entrypoints/web-editor-v2/ui/property-panel/property-panel.ts, app/chrome-extension/entrypoints/web-editor-v2/core/design-tokens/index.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `f48e71751e00bc09725c7e173423cff4f2ccd12a`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/ISSUE.md`, `docs/VisualEditor.md`, `docs/TROUBLESHOOTING.md`, `docs/mcp-cli-config.md`, `docs/ARCHITECTURE.md`, `docs/TOOLS.md`, `docs/ARCHITECTURE_zh.md`, `docs/TROUBLESHOOTING_zh.md`, `docs/WINDOWS_INSTALL_zh.md`, `docs/CONTRIBUTING.md`, `docs/VisualEditor_zh.md`, `docs/CONTRIBUTING_zh.md`, `docs/TOOLS_zh.md`, `docs/CHANGELOG.md`, `packages/wasm-simd/Cargo.toml`, `packages/wasm-simd/package.json`, `packages/wasm-simd/README.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: 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ba76885913a744f0832665f5c62d0f1d | https://github.com/hangwin/mcp-chrome/issues/321 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4ac5f778b292489482bfdb7953190f96 | https://github.com/hangwin/mcp-chrome/issues/319 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_559f34b86ade48e598dac510e9341b9e | https://github.com/hangwin/mcp-chrome/issues/339 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：mcp-chrome-bridge 无法使用\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：mcp-chrome-bridge 无法使用\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5f19fb6526174af2abe5c1eab67e25ff | https://github.com/hangwin/mcp-chrome/issues/333 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_2b32536c95a7456788ba78e1fc705116 | https://github.com/hangwin/mcp-chrome/issues/342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 可能修改宿主 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:998796026 | https://github.com/hangwin/mcp-chrome | host_targets=mcp_host, claude\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:998796026 | https://github.com/hangwin/mcp-chrome | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v0.0.6\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.6\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_035dffafcbe64f4ea112f20258430e71 | https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 维护活跃度未知\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:998796026 | https://github.com/hangwin/mcp-chrome | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | 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项目：hangwin/mcp-chrome\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 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：mcp-chrome-bridge 无法使用（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection（medium）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\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/hangwin/mcp-chrome 项目说明书\n\n生成时间：2026-05-13 11:45:57 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [快速开始](#quick-start)\n- [系统架构设计](#architecture)\n- [Chrome 扩展架构](#chrome-extension-structure)\n- [本地服务器架构](#native-server-architecture)\n- [浏览器工具集](#browser-tools)\n- [录制回放系统 (V3)](#record-replay-v3)\n- [可视化编辑器](#visual-editor)\n- [语义搜索与向量数据库](#semantic-search)\n- [AI Agent 集成](#agent-integration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [系统架构设计](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n- [app/chrome-extension/entrypoints/welcome/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/welcome/index.html)\n- [app/chrome-extension/entrypoints/builder/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/builder/index.html)\n- [app/chrome-extension/entrypoints/sidepanel/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/index.html)\n- [app/chrome-extension/entrypoints/popup/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/popup/index.html)\n- [app/chrome-extension/entrypoints/options/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/options/index.html)\n- [app/chrome-extension/utils/indexeddb-client.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/indexeddb-client.ts)\n- [app/chrome-extension/utils/lru-cache.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/lru-cache.ts)\n \n\n# 项目介绍\n\n## 概述\n\nmcp-chrome 是一个基于 Chrome 扩展实现的 **MCP (Model Context Protocol) Server**，它将 Chrome 浏览器的控制能力以标准化的工具接口暴露给 AI 助手使用。通过这个项目，AI 可以直接操控浏览器完成网页自动化、网页内容提取、用户脚本管理等多种复杂任务。资料来源：[README.md]()\n\n### 核心特性\n\n| 特性 | 描述 |\n|------|------|\n| MCP 协议支持 | 遵循 Model Context Protocol 标准，与各类 AI 助手无缝集成 |\n| 浏览器完全控制 | 提供标签页管理、导航控制、截图等完整功能 |\n| 工作流自动化 | 支持录制、回放自定义浏览器操作工作流 |\n| 网页内容分析 | AI 语义搜索、HTML 内容提取、交互元素识别 |\n| 网络监控 | 支持 webRequest 和 Debugger API 进行网络请求分析 |\n\n资料来源：[README.md]()\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"AI 助手层\"\n AI[AI Assistant]\n end\n \n subgraph \"MCP 协议层\"\n MCP[MCP Server]\n end\n \n subgraph \"Chrome 扩展层\"\n subgraph \"后台脚本\"\n BG[Background Script]\n RR[Record-Replay Engine]\n end\n \n subgraph \"入口点\"\n POP[Popup]\n SP[Side Panel]\n BLD[Builder]\n WEL[Welcome]\n OPT[Options]\n end\n \n subgraph \"注入脚本\"\n EM[Element Marker]\n WF[Web Fetcher]\n end\n end\n \n subgraph \"浏览器 API 层\"\n TABS[Chrome Tabs API]\n NR[Network APIs]\n DB[IndexedDB]\n end\n \n AI --> MCP\n MCP --> BG\n BG --> RR\n BG --> TABS\n BG --> NR\n BG --> DB\n POP --> BG\n SP --> BG\n BLD --> BG\n EM --> WF\n WF --> TABS\n```\n\n### 扩展入口点架构\n\n项目定义了多个独立的扩展入口点，每个入口点对应不同的用户界面和功能场景。资料来源：[app/chrome-extension/entrypoints/welcome/index.html]()、[app/chrome-extension/entrypoints/sidepanel/index.html]()、[app/chrome-extension/entrypoints/builder/index.html]()\n\n| 入口点 | 类型 | 功能描述 |\n|--------|------|----------|\n| welcome | unlisted_page | 欢迎页面，Chrome MCP Server 启动引导 |\n| sidepanel | side_panel | 工作流管理侧边栏 |\n| builder | unlisted_page | 工作流编辑器，支持拖拽式工作流设计 |\n| popup | browser_action | 浏览器动作弹出窗口 |\n| options | options_page | Userscripts 脚本管理器 |\n| offscreen | offscreen | 后台离屏文档，用于音频播放等后台任务 |\n\n资料来源：[app/chrome-extension/entrypoints/popup/index.html]()、[app/chrome-extension/entrypoints/options/index.html]()、[app/chrome-extension/entrypoints/offscreen/index.html]()\n\n---\n\n## 工具功能体系\n\n### 浏览器控制工具\n\n项目提供 6 个浏览器控制类工具，覆盖标签页管理、导航控制、脚本注入等场景。资料来源：[README.md]()\n\n| 工具名称 | 功能 | 输入参数 |\n|----------|------|----------|\n| chrome_manage_tabs | 打开、创建、重新加载标签页 | action, url, tabId |\n| chrome_viewport_control | 控制视口缩放和滚动 | zoom, scrollX, scrollY |\n| chrome_switch_tab | 切换当前活动标签页 | tabId |\n| chrome_close_tabs | 关闭指定标签页或窗口 | tabIds, windowId |\n| chrome_go_back_or_forward | 浏览器导航前进/后退 | direction |\n| chrome_inject_script | 向网页注入内容脚本 | script |\n| chrome_send_command_to_inject_script | 向注入脚本发送命令 | command |\n\n### 交互操作工具\n\n提供 3 个用户交互模拟工具，支持模拟真实用户行为。资料来源：[README.md]()\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| chrome_click_element | 使用 CSS 选择器点击页面元素 |\n| chrome_fill_or_select | 填写表单字段或选择下拉选项 |\n| chrome_keyboard | 模拟键盘输入和快捷键组合 |\n\n### 截图与视觉工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| chrome_screenshot | 高级截图捕获，支持元素定位、全页面截图和自定义尺寸 |\n\n### 数据管理工具\n\n提供 5 个书签和历史记录管理工具。资料来源：[README.md]()\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| chrome_history | 按时间范围搜索浏览器历史记录 |\n| chrome_bookmark_search | 按关键词搜索书签 |\n| chrome_bookmark_add | 添加新书签，支持文件夹分类 |\n| chrome_bookmark_delete | 删除指定书签 |\n\n### 网络监控工具\n\n支持 4 种网络监控方式，基于 Chrome 扩展的网络 API 实现。资料来源：[README.md]()\n\n| 工具名称 | API 来源 | 功能 |\n|----------|----------|------|\n| chrome_network_capture_start/stop | webRequest API | 拦截网络请求 |\n| chrome_network_debugger_start/stop | Debugger API | 带响应体的深度调试 |\n| chrome_network_request | - | 发送自定义 HTTP 请求 |\n\n### 内容分析工具\n\n提供 4 个 AI 辅助内容分析工具。资料来源：[README.md]()\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| search_tabs_content | AI 语义搜索跨标签页内容 |\n| chrome_get_web_content | 提取网页 HTML 或文本内容 |\n| chrome_get_interactive_elements | 识别页面可点击交互元素 |\n| chrome_console | 捕获并获取浏览器控制台输出 |\n\n---\n\n## 工作流引擎\n\n### Record-Replay 架构\n\n项目包含完整的工作流录制与回放引擎，支持复杂浏览器自动化场景。引擎采用节点图结构定义工作流，通过调度器执行。资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/runners/subflow-runner.ts]()\n\n```mermaid\ngraph LR\n subgraph \"工作流定义\"\n S1[Step 节点]\n S2[Step 节点]\n E1[边 - Default]\n E2[边 - On Error]\n end\n \n subgraph \"执行引擎\"\n SCH[Scheduler]\n RUN[Subflow Runner]\n end\n \n S1 --> E1 --> S2\n S1 --> E2 --> SCH\n SCH --> RUN\n```\n\n### 节点类型与边\n\n引擎使用 `indeg` (入度) 和 `outEdges` (出边) 管理节点图结构，通过以下规则确定执行顺序：\n\n1. **根节点识别**：查找入度为 0 且非 TRIGGER 类型的节点作为首个可执行节点\n2. **边标签选择**：DEFAULT 标签表示默认执行路径，ON_ERROR 标签表示错误处理路径\n3. **迭代保护**：通过 MAX_ITERATIONS 限制最大执行次数，防止循环工作流导致的死循环\n\n资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/scheduler.ts]()\n\n### 消息分类处理\n\n引擎通过 `useAgentThreads` composable 对 AI 消息进行分类，识别不同类型的操作意图。资料来源：[app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts]()\n\n| 工具类型 | 识别规则 | 显示标签 |\n|----------|----------|----------|\n| Edit | 包含 'edit'、'apply_patch'、'patch_file' | Edit |\n| Write | 包含 'write'、'create_file' | Write |\n| Run | 'bash'、'shell'、以 'Running:'/'Ran:' 开头 | Run |\n| Grep | 'grep'、'search'、有 pattern 参数 | Grep |\n\n---\n\n## 数据存储\n\n### IndexedDB 客户端\n\n项目实现了统一的 IndexedDB 客户端封装，提供 Promise 化的数据库操作接口。资料来源：[app/chrome-extension/utils/indexeddb-client.ts]()\n\n| 方法 | 模式 | 功能 |\n|------|------|------|\n| getAll | readonly | 获取指定仓库所有数据 |\n| get | readonly | 根据 key 获取单条数据 |\n| put | readwrite | 插入或更新数据 |\n| delete | readwrite | 删除指定 key 的数据 |\n| clear | readwrite | 清空指定仓库 |\n| putMany | readwrite | 批量插入数据 |\n\n### LRU 缓存\n\n项目实现了线程安全的 LRU (Least Recently Used) 缓存模块。资料来源：[app/chrome-extension/utils/lru-cache.ts]()\n\n```typescript\nclass LRUNode {\n key: K;\n value: V;\n prev: LRUNode | null;\n next: LRUNode | null;\n frequency: number; // 访问频率\n lastAccessed: number; // 最近访问时间戳\n}\n```\n\n缓存策略结合访问频率和最近访问时间进行淘汰判定，容量默认值为 100。\n\n---\n\n## 元素标注系统\n\n### Element Marker 组件\n\nElement Marker 是一个嵌入到网页中的交互式元素选择器组件，支持两种选择模式。资料来源：[app/chrome-extension/inject-scripts/element-marker.js]()\n\n| 选择模式 | 功能 | 支持格式 |\n|----------|------|----------|\n| 单选模式 | 选择单个元素 | CSS Selector / XPath |\n| 列表模式 | 批量标注相似元素 | 仅 CSS Selector |\n\n### 选择器类型\n\n| 类型 | 示例 | 说明 |\n|------|------|------|\n| CSS Selector | `#__em_selector_type` | 通过 CSS 选择器定位 |\n| XPath | `//button[@id='submit']` | 通过 XML 路径定位 |\n\n---\n\n## Web 内容获取\n\n### Web Fetcher Helper\n\n内容提取算法基于 Readability 算法改进，通过多维度评分机制识别页面主体内容。资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js]()\n\n#### 内容评分规则\n\n| 评分因素 | 权重说明 |\n|----------|----------|\n| 标签类型 | article、section、div 等不同标签基础分不同 |\n| 段落文本长度 | 每 100 字符加 1 分，最多 3 分 |\n| 逗号分隔 | 每增加一个逗号加 1 分 |\n| 链接密度 | 高链接密度的内容会降低最终得分 |\n| 祖先节点层级 | 父节点不除、祖节点除 2、曾祖节点及以上乘 3 |\n\n#### 候选节点处理流程\n\n```mermaid\ngraph TD\n A[遍历所有节点] --> B{是否为候选内容节点?}\n B -->|是| C[初始化 Readability 分数]\n B -->|否| D[跳过]\n C --> E[计算内容分数]\n E --> F[向祖先节点累加加权分数]\n F --> G{还有祖先节点?}\n G -->|是| F\n G -->|否| H[收集所有候选节点]\n H --> I[计算最终分数]\n I --> J[按链接密度调整]\n J --> K[返回最高分节点]\n```\n\n---\n\n## 应用示例\n\n### 场景一：AI 辅助网页摘要与图表绘制\n\nAI 可以先分析当前页面内容，提取关键信息后自动控制 Excalidraw 等绘图工具生成图表。资料来源：[README.md]()\n\n**提示词示例：**\n> Help me summarize the current page content, then draw a diagram to aid my understanding.\n\n### 场景二：图像分析与复现\n\nAI 可以分析网页中的图像内容，然后结合分析结果和图像本身复制图像。资料来源：[README.md]()\n\n**流程：**\n1. 接收图像 URL\n2. 使用 content-analize 工具分析图像内容\n3. 通过 Excalidraw 工具复现图像\n\n### 场景三：浏览器自动化工作流\n\n通过录制用户操作生成工作流，实现复杂浏览器自动化任务。\n\n---\n\n## 技术栈\n\n| 层级 | 技术选型 |\n|------|----------|\n| 前端框架 | Vue 3 (Composition API) |\n| 扩展框架 | WXT (Modern Chrome Extension Framework) |\n| 协议 | Model Context Protocol (MCP) |\n| 存储 | IndexedDB |\n| 构建工具 | Vite |\n| 语言 | TypeScript |\n\n---\n\n## 快速开始\n\n### 安装步骤\n\n1. 克隆项目仓库\n2. 安装依赖：`pnpm install`\n3. 构建扩展：`pnpm build`\n4. 在 Chrome 中加载 `dist/chrome-extension` 目录\n\n### 配置 MCP Server\n\n在 AI 助手的 MCP 配置中添加以下配置：\n\n```json\n{\n \"mcpServers\": {\n \"chrome\": {\n \"command\": \"path/to/mcp-chrome-server\",\n \"args\": []\n }\n }\n}\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/package.json)\n- [app/native-server/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/package.json)\n- [app/native-server/install.md](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/install.md)\n- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n- [app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n \n\n# 快速开始\n\n本文档为 **mcp-chrome** 项目提供完整的快速上手指南，帮助你在最短时间内完成环境搭建并开始使用 Chrome MCP Server。\n\n## 项目概述\n\nmcp-chrome 是一个基于 Chrome 扩展和本地原生消息（Native Messaging）通信协议的 MCP（Model Context Protocol）服务器实现。它允许 AI 模型通过标准化的接口直接控制 Chrome 浏览器，完成网页交互、内容提取、网络监控等任务。\n\n## 系统架构\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[AI Model / Claude]\n B[MCP Client SDK]\n end\n \n subgraph \"Chrome Extension\"\n C[Side Panel UI]\n D[Background Service Worker]\n E[Content Scripts]\n end\n \n subgraph \"Native Server\"\n F[MCP Server Core]\n G[Browser Controller]\n H[Native Messaging Host]\n end\n \n subgraph \"Browser\"\n I[Chrome Browser]\n J[Extension API]\n end\n \n A --> B\n B --> C\n C --> D\n D --> E\n E --> J\n D --> H\n H --> F\n F --> G\n G --> J\n J --> I\n \n style A fill:#e1f5fe\n style I fill:#fff3e0\n style H fill:#f3e5f5\n```\n\n## 前置要求\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Node.js | ≥ 18.0.0 | 本地服务器运行环境 |\n| npm / pnpm | 最新稳定版 | 包管理工具 |\n| Chrome / Chromium | ≥ 120 | 目标浏览器 |\n| 支持的操作系统 | Windows / macOS / Linux | 完整支持三大平台 |\n\n资料来源：[app/native-server/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/package.json)\n\n## 安装步骤\n\n### 步骤 1：安装原生服务器\n\n原生服务器负责处理 AI 模型与 Chrome 浏览器之间的原生消息通信。\n\n```bash\n# 克隆项目\ngit clone https://github.com/hangwin/mcp-chrome.git\ncd mcp-chrome\n\n# 进入原生服务器目录\ncd app/native-server\n\n# 安装依赖\npnpm install\n# 或\nnpm install\n```\n\n### 步骤 2：构建项目\n\n```bash\n# 构建原生服务器\npnpm build\n\n# 构建 Chrome 扩展\ncd ../chrome-extension\npnpm install\npnpm build\n```\n\n资料来源：[app/chrome-extension/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/package.json)\n\n### 步骤 3：注册原生消息主机\n\n根据你的操作系统和浏览器，需要配置 Native Messaging Host 清单文件。\n\n#### Windows 系统\n\n```powershell\n# 用户级注册（推荐）\n.\\dist\\cli.js register --browser chrome\n\n# 或系统级注册（需要管理员权限）\n.\\dist\\cli.js register --browser chrome --system\n```\n\n#### macOS 系统\n\n```bash\n# 用户级注册\n./dist/cli.js register --browser chrome\n\n# 系统级注册（需要 sudo）\nsudo ./dist/cli.js register --browser chrome --system\n```\n\n#### Linux 系统\n\n```bash\n# 用户级注册\n./dist/cli.js register --browser chrome\n\n# 系统级注册\nsudo ./dist/cli.js register --browser chrome --system\n```\n\n资料来源：[app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n\n### 步骤 4：安装 Chrome 扩展\n\n1. 打开 Chrome，访问 `chrome://extensions/`\n2. 开启右上角的「开发者模式」\n3. 点击「加载已解压的扩展程序」\n4. 选择 `app/chrome-extension/dist` 目录\n\n## 清单文件路径配置\n\n不同平台和浏览器的 Native Messaging Host 清单文件路径如下：\n\n| 平台 | 浏览器 | 用户级路径 | 系统级路径 |\n|------|--------|------------|------------|\n| Windows | Chrome | `%APPDATA%\\Google\\Chrome\\User Data\\Default\\Extensions\\...` | `%ProgramFiles%\\Google\\Chrome\\NativeMessagingHosts\\` |\n| Windows | Chromium | `%APPDATA%\\Chromium\\User Data\\Default\\Extensions\\...` | `%ProgramFiles%\\Chromium\\NativeMessagingHosts\\` |\n| macOS | Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` | `/Library/Google/Chrome/NativeMessagingHosts/` |\n| macOS | Chromium | `~/Library/Application Support/Chromium/NativeMessagingHosts/` | `/Library/Application Support/Chromium/NativeMessagingHosts/` |\n| Linux | Chrome | `~/.config/google-chrome/NativeMessagingHosts/` | `/etc/opt/chrome/native-messaging-hosts/` |\n| Linux | Chromium | `~/.config/chromium/NativeMessagingHosts/` | `/etc/chromium/native-messaging-hosts/` |\n\n资料来源：[app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n\n## 验证安装\n\n使用诊断命令检查安装状态：\n\n```bash\ncd app/native-server\npnpm doctor\n```\n\n诊断脚本会检查以下项目：\n\n1. **Node.js 版本** - 确认 Node 环境正确\n2. **原生服务器可执行文件** - 验证 `mcp-chrome` 可执行文件存在\n3. **清单文件** - 检查各平台 Native Messaging Host 配置\n4. **Windows 注册表**（仅 Windows）- 验证注册表项正确设置\n5. **浏览器连接** - 确认扩展与服务器可以正常通信\n\n资料来源：[app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)\n\n### 常见诊断结果\n\n| 检查项 | 状态 | 说明 |\n|--------|------|------|\n| manifest.chrome | ok | Chrome 清单文件正确 |\n| manifest.chrome | error | 清单文件不存在或配置错误 |\n| windowsRegistry | ok | 注册表项正确（仅 Windows） |\n\n## MCP 客户端配置\n\n安装完成后，在你的 MCP 客户端配置文件中添加以下配置：\n\n```json\n{\n \"mcpServers\": {\n \"chrome\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-chrome/app/native-server/dist/index.js\"]\n }\n }\n}\n```\n\n## 可用工具一览\n\n安装成功后，以下工具将自动可用：\n\n### 🌐 标签页管理（5 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_search_tabs` | 跨标签页内容语义搜索 |\n| `chrome_get_web_content` | 提取网页 HTML/文本内容 |\n| `chrome_get_interactive_elements` | 获取页面可交互元素 |\n| `chrome_console` | 获取浏览器控制台输出 |\n| `chrome_screenshot` | 页面截图（支持元素定位） |\n\n### 🔧 浏览器控制（7 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_navigate` | 导航到指定 URL |\n| `chrome_scroll` | 控制页面滚动 |\n| `chrome_viewport` | 调整视口大小 |\n| `chrome_switch_tab` | 切换浏览器标签页 |\n| `chrome_close_tabs` | 关闭指定标签页 |\n| `chrome_go_back_or_forward` | 浏览器前进/后退 |\n| `chrome_inject_script` | 注入内容脚本 |\n\n### 🎯 页面交互（3 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_click_element` | 点击页面元素（CSS 选择器） |\n| `chrome_fill_or_select` | 表单填充和选项选择 |\n| `chrome_keyboard` | 模拟键盘输入和快捷键 |\n\n### 📚 数据管理（5 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_history` | 搜索浏览器历史记录 |\n| `chrome_bookmark_search` | 搜索书签 |\n| `chrome_bookmark_add` | 添加书签 |\n| `chrome_bookmark_delete` | 删除书签 |\n\n### 🌐 网络监控（4 个工具）\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_network_capture_start/stop` | 网络请求捕获（webRequest API） |\n| `chrome_network_debugger_start/stop` | 网络调试（响应体捕获） |\n| `chrome_network_request` | 发送自定义 HTTP 请求 |\n\n资料来源：[README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n\n## 安全配置\n\nChrome 扩展在生产环境中启用了以下安全策略：\n\n```json\n{\n \"cross_origin_embedder_policy\": \"require-corp\",\n \"cross_origin_opener_policy\": \"same-origin\",\n \"content_security_policy\": {\n \"extension_pages\": \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\"\n }\n}\n```\n\n开发环境下这些策略会被禁用，以允许 Vite 开发服务器的正常资源加载。\n\n资料来源：[app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n\n## 故障排除\n\n### 1. 清单文件未找到\n\n```bash\n# 自动检测并注册\npnpm run register --detect\n```\n\n### 2. 浏览器无法连接\n\n确保 Chrome 扩展已正确加载，并且原生服务器正在运行：\n\n```bash\n# 检查服务器状态\npnpm doctor\n```\n\n### 3. 权限问题（Linux/macOS）\n\n```bash\n# 确保可执行文件有运行权限\nchmod +x dist/cli.js\nchmod +x dist/index.js\n```\n\n## 下一步\n\n- 查看 [使用示例](../examples/) 了解常见场景\n- 阅读 [API 文档](../api/) 深入了解各工具的参数\n- 参考 [架构设计](../architecture/) 理解内部实现\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[Chrome 扩展架构](#chrome-extension-structure), [本地服务器架构](#native-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/ARCHITECTURE.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/ARCHITECTURE.md)\n- [docs/ARCHITECTURE_zh.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/ARCHITECTURE_zh.md)\n- [app/chrome-extension/entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)\n- [app/native-server/src/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/index.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)\n- [app/native-server/src/agent/session-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/session-service.ts)\n- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n \n\n# 系统架构设计\n\n## 概述\n\nmcp-chrome 是一个将 Chrome 浏览器与 AI 大模型深度集成的开源项目，通过 Model Context Protocol (MCP) 协议实现浏览器自动化控制与智能交互。该项目由 **Chrome 扩展端** 和 **本地服务（Native Server）端** 两大部分组成，采用主从架构设计，通过 Chrome Native Messaging 原生消息通信机制实现双向通信。\n\n**核心目标**：\n- 为 AI Agent 提供完整的浏览器控制能力\n- 支持网页内容提取、交互、截图、网络监控等操作\n- 实现跨平台的 Chrome 浏览器自动化\n\n资料来源：[docs/ARCHITECTURE_zh.md]()\n\n## 整体架构\n\n```mermaid\ngraph TB\n subgraph \"客户端层 (Client)\"\n AI_Agent[AI Agent / Claude Code]\n MCP_Client[MCP Client SDK]\n end\n\n subgraph \"本地服务层 (Native Server)\"\n MCP_Server[MCP Server]\n Session_Manager[Session Manager]\n Engine_Adapter[Engine Adapter
Claude / Codex]\n Native_Messaging[Native Messaging Host]\n end\n\n subgraph \"Chrome 扩展层 (Chrome Extension)\"\n Background_Script[Background Script]\n Sidepanel[Sidepanel UI]\n Popup[Popup UI]\n Content_Script[Content Scripts]\n Inject_Scripts[Inject Scripts]\n end\n\n subgraph \"浏览器层 (Browser)\"\n Chrome_Runtime[Chrome Runtime API]\n Tabs_Management[标签页管理]\n Network_Monitor[网络监控]\n Console[控制台捕获]\n end\n\n AI_Agent --> MCP_Client\n MCP_Client --> MCP_Server\n MCP_Server --> Session_Manager\n MCP_Server --> Engine_Adapter\n Engine_Adapter --> Native_Messaging\n Native_Messaging --> Background_Script\n Background_Script --> Content_Script\n Background_Script --> Tabs_Management\n Background_Script --> Network_Monitor\n Background_Script --> Chrome_Runtime\n Content_Script --> Inject_Scripts\n```\n\n## 核心组件\n\n### 1. 本地服务层 (Native Server)\n\n本地服务层是整个系统的核心引擎，负责处理 AI 请求、管理会话、调用浏览器扩展功能。\n\n#### 1.1 MCP Server\n\nMCP Server 是基于 Model Context Protocol 协议实现的服务端，负责接收来自 AI Agent 的请求并路由到对应的处理模块。\n\n**主要职责**：\n- 协议解析与消息编解码\n- 工具（Tools）注册与调用分发\n- 会话生命周期管理\n- 错误处理与重试机制\n\n资料来源：[app/native-server/src/index.ts]()\n\n#### 1.2 Session Manager\n\n会话管理器负责管理 AI Agent 的执行会话，包括会话状态、上下文信息、配置参数等。\n\n```typescript\ninterface SessionConfig {\n mcpServers?: Record;\n outputFormat?: Record;\n enableFileCheckpointing?: boolean;\n sandbox?: Record;\n env?: Record;\n codexConfig?: Partial;\n}\n```\n\n**关键特性**：\n- 支持多种引擎配置（Claude、Codex）\n- 会话元数据缓存（Management Info）\n- 插件和技能管理\n- 输出格式自定义\n\n资料来源：[app/native-server/src/agent/session-service.ts:1-80]()\n\n#### 1.3 Engine Adapter\n\n引擎适配器层封装了不同 AI 引擎的调用接口，目前支持 Claude 和 Codex 两种引擎。\n\n**Claude Engine 实现**：\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Engine as Claude Engine\n participant Chrome as Chrome Extension\n \n Client->>Engine: 发送消息\n Engine->>Engine: 构建消息结构\n Engine->>Chrome: dispatchToolMessage\n Chrome-->>Engine: 工具执行结果\n Engine->>Engine: 处理 content_block_stop\n Engine->>Client: 返回响应\n```\n\n**工具消息分类**：\n| 消息类型 | 说明 | 严重级别 |\n|---------|------|---------|\n| `edit` | 文件编辑操作 | error/success |\n| `run` | 命令执行操作 | error/success/info |\n| `grep` | 搜索操作 | error/info |\n| `agent` | Agent 相关操作 | error/info |\n\n资料来源：[app/native-server/src/agent/engines/claude.ts:1-80]()\n\n#### 1.4 Native Messaging Host\n\nNative Messaging Host 是 Chrome 扩展与本地服务通信的桥梁，支持跨平台的消息传递。\n\n**平台特定路径配置**：\n\n| 操作系统 | 用户级路径 | 系统级路径 |\n|---------|-----------|-----------|\n| Windows | `%APPDATA%\\Google\\Chrome\\NativeMessagingHosts\\` | `%ProgramFiles%\\Google\\Chrome\\NativeMessagingHosts\\` |\n| macOS | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` | `/Library/Google/Chrome/NativeMessagingHosts/` |\n| Linux | `~/.config/google-chrome/NativeMessagingHosts/` | `/etc/opt/chrome/native-messaging-hosts/` |\n\n**功能**：\n- 消息序列化与反序列化\n- 进程间通信管理\n- 心跳检测与断线重连\n\n资料来源：[app/native-server/src/scripts/browser-config.ts:1-100]()\n资料来源：[app/native-server/src/scripts/utils.ts:1-80]()\n\n---\n\n### 2. Chrome 扩展层\n\nChrome 扩展是系统的执行端，负责实际的浏览器操作和页面交互。\n\n#### 2.1 扩展入口点\n\n| 入口点 | 文件路径 | 功能说明 |\n|-------|---------|---------|\n| Background Script | `entrypoints/background/index.ts` | 后台服务脚本，处理 Native Messaging 通信 |\n| Sidepanel | `entrypoints/sidepanel/` | 侧边栏 UI，用于工作流管理 |\n| Popup | `entrypoints/popup/` | 浏览器工具栏弹窗 |\n| Options | `entrypoints/options/` | 扩展设置页面 |\n| Builder | `entrypoints/builder/` | 工作流编辑器 |\n| Welcome | `entrypoints/welcome/` | 欢迎页面 |\n\n资料来源：[app/chrome-extension/entrypoints/background/index.ts]()\n资料来源：[app/chrome-extension/entrypoints/sidepanel/index.html]()\n资料来源：[app/chrome-extension/entrypoints/popup/index.html]()\n\n#### 2.2 扩展配置\n\n扩展使用 WXT 框架构建，配置包括资源访问策略和内容安全策略。\n\n**Web 可访问资源**：\n```typescript\nweb_accessible_resources: [\n {\n resources: [\n '/models/*', // AI 模型文件\n '/workers/*', // Web Worker 文件\n '/inject-scripts/*' // 注入脚本\n ],\n matches: ['']\n }\n]\n```\n\n**内容安全策略（CSP）**：\n```typescript\ncontent_security_policy: {\n extension_pages: \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\"\n}\n```\n\n资料来源：[app/chrome-extension/wxt.config.ts:1-50]()\n\n#### 2.3 核心功能模块\n\n**Content Indexer（内容索引器）**\n\n内容索引器负责自动提取和索引浏览器标签页的内容，支持语义搜索功能。\n\n```mermaid\ngraph LR\n A[页面加载完成] --> B{自动索引启用?}\n B -->|是| C{语义引擎就绪?}\n C -->|是| D[延迟 2 秒]\n D --> E[提取页面内容]\n E --> F[存储索引]\n C -->|否| G[跳过]\n B -->|否| G\n```\n\n**URL 过滤规则**：\n```typescript\nconst excludePatterns = [\n /^chrome:\\/\\//,\n /^chrome-extension:\\/\\//,\n /^edge:\\/\\//,\n /^about:/,\n /^moz-extension:\\/\\//,\n /^file:\\/\\//\n];\n```\n\n资料来源：[app/chrome-extension/utils/content-indexer.ts:1-80]()\n\n**Web Fetcher Helper（网页内容提取）**\n\n通过内容脚本注入到网页中，提取页面元数据和正文内容。\n\n**提取的元数据字段**：\n| 字段 | 来源优先级 |\n|-----|----------|\n| `title` | JSON-LD → og:title → twitter:title |\n| `byline` | JSON-LD → author → article:author |\n| `excerpt` | JSON-LD → dc:description → og:description |\n| `siteName` | JSON-LD → og:site_name |\n| `publishedTime` | JSON-LD → article:published_time |\n\n资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js:1-100]()\n\n---\n\n## 工具能力体系\n\n### 工具分类总览\n\n| 类别 | 工具数量 | 主要功能 |\n|-----|---------|---------|\n| 标签页管理 | 6 | 开关标签页、切换、导航控制 |\n| 交互操作 | 3 | 元素点击、表单填充、键盘输入 |\n| 数据管理 | 5 | 历史记录、书签增删改查 |\n| 截图视觉 | 1 | 高级截图（元素/全页/自定义尺寸） |\n| 网络监控 | 4 | Request API、Debugger API、自定义请求 |\n| 内容分析 | 4 | 语义搜索、内容提取、交互元素、控制台 |\n\n### 核心工具详解\n\n#### 网络监控工具\n\n```mermaid\ngraph TD\n A[网络监控工具] --> B[chrome_network_capture]\n A --> C[chrome_network_debugger]\n A --> D[chrome_network_request]\n \n B --> B1[webRequest API]\n B1 --> B2[无响应体]\n \n C --> C1[Debugger API]\n C1 --> C2[完整响应体]\n \n D --> D1[自定义 HTTP 请求]\n D1 --> D2[拦截响应]\n```\n\n**对比表**：\n\n| 特性 | capture | debugger | request |\n|-----|---------|----------|---------|\n| API 来源 | webRequest | Debugger | fetch |\n| 响应体 | ✗ | ✓ | ✓ |\n| 性能开销 | 低 | 高 | 中 |\n| 使用场景 | 快速记录 | 详细调试 | 自定义请求 |\n\n资料来源：[README.md]()\n资料来源：[docs/ARCHITECTURE_zh.md]()\n\n---\n\n## 通信机制\n\n### Native Messaging 通信流程\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant MCPServer as MCP Server\n participant NativeHost as Native Messaging Host\n participant Background as Background Script\n participant Content as Content Script\n participant Page as Web Page\n\n Agent->>MCPServer: MCP JSON-RPC 请求\n MCPServer->>MCPServer: 解析工具调用\n MCPServer->>NativeHost: 序列化消息\n NativeHost->>Background: Chrome.runtime.sendNativeMessage\n Background->>Background: 处理请求\n Background->>Content: chrome.tabs.sendMessage\n Content->>Page: 执行脚本\n Page-->>Content: 返回结果\n Content-->>Background: 发送结果\n Background-->>NativeHost: 返回响应\n NativeHost-->>MCPServer: 解析响应\n MCPServer-->>Agent: MCP JSON-RPC 响应\n```\n\n### 消息类型定义\n\n**工具调用消息**：\n```typescript\n{\n method: 'tools/call',\n params: {\n name: 'chrome_screenshot',\n arguments: {\n tabId: 123,\n fullPage: true\n }\n }\n}\n```\n\n**结果返回消息**：\n```typescript\n{\n method: 'tools/call/result',\n result: {\n success: true,\n data: { screenshot: 'base64...' }\n }\n}\n```\n\n资料来源：[app/native-server/src/index.ts]()\n资料来源：[app/chrome-extension/entrypoints/background/index.ts]()\n\n---\n\n## 安全策略\n\n### 权限控制\n\nChrome 扩展声明的权限范围决定了其能访问的 API 和资源：\n\n```json\n{\n \"permissions\": [\n \"tabs\",\n \"storage\",\n \"activeTab\",\n \"scripting\",\n \"nativeMessaging\",\n \"webNavigation\",\n \"webRequest\"\n ],\n \"host_permissions\": [\"\"]\n}\n```\n\n### 内容安全策略\n\n生产环境启用以下安全策略：\n\n| 策略 | 值 | 说明 |\n|-----|-----|-----|\n| `cross_origin_embedder_policy` | require-corp | 要求跨域资源支持 CORP |\n| `cross_origin_opener_policy` | same-origin | 防止跨域窗口访问 |\n| `script-src` | 'self' 'wasm-unsafe-eval' | 允许自身脚本和 WebAssembly |\n| `object-src` | 'self' | 仅允许自身对象资源 |\n| `style-src` | 'self' 'unsafe-inline' | 允许内联样式（Vite 构建） |\n\n开发环境使用 WXT 默认策略，避免阻断 dev server 资源加载。\n\n资料来源：[app/chrome-extension/wxt.config.ts:20-35]()\n\n---\n\n## 安装与配置\n\n### 本地服务安装\n\n1. **自动安装**：\n ```bash\n npx mcp-chrome-bridge install\n ```\n\n2. **注册表/Manifest 配置**：\n - Windows：写入 `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\`\n - macOS：创建 `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/`\n - Linux：创建 `~/.config/google-chrome/NativeMessagingHosts/`\n\n3. **验证安装**：\n ```bash\n mcp-chrome-bridge doctor\n ```\n\n### MCP Server 配置\n\n在 MCP 客户端配置文件中添加：\n\n```json\n{\n \"mcpServers\": {\n \"chrome\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-chrome-bridge\"]\n }\n }\n}\n```\n\n资料来源：[app/native-server/install.md]()\n\n---\n\n## 扩展组件清单\n\n| 组件类型 | 文件夹路径 | 功能说明 |\n|---------|-----------|---------|\n| 入口点 | `entrypoints/*/` | 各类型扩展页面的入口 |\n| 组件 | `components/` | Vue 组件库 |\n| 工具函数 | `utils/` | 通用工具函数 |\n| 注入脚本 | `inject-scripts/` | 注入到网页的 JavaScript |\n| 内容脚本 | `content/` | 页面内容脚本 |\n| 类型定义 | `types/` | TypeScript 类型定义 |\n\n资料来源：[app/chrome-extension/wxt.config.ts]()\n\n---\n\n## 总结\n\nmcp-chrome 采用分层架构设计，将复杂的浏览器自动化能力抽象为标准化的 MCP 工具接口：\n\n1. **Native Server 层** 处理 AI 逻辑和会话管理，通过 Native Messaging 与浏览器通信\n2. **Chrome Extension 层** 实际执行浏览器操作，包括标签页管理、网络监控、内容提取等\n3. **通信层** 基于 Chrome Native Messaging 协议实现跨进程、跨语言的可靠消息传递\n\n该架构具有良好的可扩展性，支持后续添加更多 AI 引擎适配器和浏览器工具，同时通过权限管理和 CSP 策略保障安全性。\n\n---\n\n\n\n## Chrome 扩展架构\n\n### 相关页面\n\n相关主题：[系统架构设计](#architecture), [浏览器工具集](#browser-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)\n- [app/chrome-extension/entrypoints/content.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/content.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [app/chrome-extension/common/constants.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/common/constants.ts)\n- [app/chrome-extension/entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n \n\n# Chrome 扩展架构\n\n## 概述\n\nmcp-chrome 是一个基于 Chrome 扩展的 MCP（Model Context Protocol）服务器实现，旨在为 AI 提供完整的浏览器控制能力。该扩展通过 WXT 框架构建，采用多入口点架构，涵盖后台脚本、内容脚本、侧边栏、弹出窗口等多种扩展页面类型。\n\n## 整体架构\n\n```mermaid\ngraph TB\n subgraph \"扩展页面层\"\n Popup[\"弹出窗口
popup/\"]\n Sidepanel[\"侧边栏
sidepanel/\"]\n Builder[\"工作流编辑器
builder/\"]\n Welcome[\"欢迎页
welcome/\"]\n Options[\"选项页
options/\"]\n end\n \n subgraph \"核心服务层\"\n Background[\"后台脚本
background/\"]\n Content[\"内容脚本
content.ts\"]\n end\n \n subgraph \"功能模块层\"\n RecordReplay[\"录制回放引擎
record-replay/\"]\n ContentIndexer[\"内容索引器
content-indexer.ts\"]\n ToolRegistry[\"工具注册表\"]\n TriggerEngine[\"触发器引擎\"]\n end\n \n subgraph \"注入脚本层\"\n WebFetcher[\"网页内容提取
web-fetcher-helper.js\"]\n DOMObserver[\"DOM 观察器
dom-observer.js\"]\n InjectBridge[\"注入桥接
inject-bridge.js\"]\n AccessibilityTree[\"无障碍树辅助
accessibility-tree-helper\"]\n end\n \n subgraph \"外部通信\"\n NativeServer[\"原生服务器
native-server/\"]\n MCPServer[\"MCP 服务器\"]\n end\n \n Popup --> Background\n Sidepanel --> Background\n Builder --> Background\n Options --> Background\n Background --> Content\n Background --> RecordReplay\n Background --> ContentIndexer\n Background --> ToolRegistry\n Background --> TriggerEngine\n Content --> WebFetcher\n Content --> DOMObserver\n Content --> InjectBridge\n Content --> AccessibilityTree\n Background --> NativeServer\n Background --> MCPServer\n```\n\n## 入口点架构\n\n### 入口点清单\n\n| 入口点 | 路径 | 用途 | manifest.type |\n|--------|------|------|---------------|\n| 后台脚本 | `background/index.ts` | 核心业务逻辑、MCP 协议处理 | service_worker |\n| 内容脚本 | `content.ts` | 页面交互、DOM 操作 | content_script |\n| 弹出窗口 | `popup/index.html` | 快速操作入口 | browser_action |\n| 侧边栏 | `sidepanel/index.html` | 工作流管理 | side_panel |\n| 工作流编辑器 | `builder/index.html` | 可视化工作流设计 | unlisted_page |\n| 欢迎页 | `welcome/index.html` | 用户引导 | unlisted_page |\n| 选项页 | `options/index.html` | 用户脚本管理 | - |\n\n资料来源：[wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n\n### manifest.json 配置\n\n扩展采用 WXT 框架自动生成 manifest.json，关键配置包括：\n\n```typescript\nmanifest: {\n permissions: [\n 'tabs',\n 'storage',\n 'webNavigation',\n 'webRequest',\n 'scripting',\n 'nativeMessaging'\n ],\n host_permissions: [''],\n web_accessible_resources: [\n '/models/*',\n '/workers/*',\n '/inject-scripts/*'\n ]\n}\n```\n\n## 后台脚本架构\n\n### 后台脚本职责\n\n后台脚本（Service Worker）是扩展的核心中枢，负责：\n\n1. **MCP 协议通信** - 与原生服务器建立 Native Messaging 连接\n2. **工具注册与分发** - 管理所有可用工具的定义和调用\n3. **标签页管理** - 协调多标签页间的通信\n4. **状态维护** - 管理扩展的全局状态\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP 客户端\n participant BG as 后台脚本\n participant Content as 内容脚本\n participant Tab as 目标页面\n \n MCP->>BG: 工具调用请求\n BG->>BG: 解析工具名称与参数\n BG->>Content: chrome.tabs.sendMessage\n Content->>Tab: 执行脚本注入\n Tab-->>Content: 执行结果\n Content-->>BG: 响应消息\n BG-->>MCP: JSON-RPC 响应\n```\n\n资料来源：[entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)\n\n### 工具分类体系\n\n| 类别 | 工具数量 | 功能描述 |\n|------|----------|----------|\n| 网络监控 | 4 | 请求捕获、调试、发送自定义请求 |\n| 内容分析 | 4 | 语义搜索、内容提取、元素定位、控制台捕获 |\n| 浏览器控制 | 6 | 标签管理、导航控制、视图切换 |\n| 交互操作 | 3 | 元素点击、表单填充、键盘模拟 |\n| 数据管理 | 5 | 书签管理、历史记录搜索 |\n| 截图 | 1 | 高级截图功能 |\n\n## 内容脚本架构\n\n### 内容脚本职责\n\n内容脚本运行在网页上下文中，主要负责：\n\n- 直接访问和操作页面 DOM\n- 注入用户脚本\n- 收集页面信息\n- 响应后台脚本的消息\n\n### 注入脚本层次\n\n```mermaid\ngraph TD\n Page[\"网页页面\"]\n IS[\"注入脚本层 (ISOLATED)\"]\n CS[\"内容脚本层 (ISOLATED)\"]\n \n subgraph \"内容脚本\"\n InjectBridge[\"inject-bridge.js\"]\n AccessibilityTree[\"accessibility-tree-helper\"]\n end\n \n subgraph \"注入脚本\"\n WebFetcher[\"web-fetcher-helper.js\"]\n DOMObserver[\"dom-observer.js\"]\n end\n \n Page --> IS\n IS --> WebFetcher\n IS --> DOMObserver\n Page --> CS\n CS --> InjectBridge\n CS --> AccessibilityTree\n```\n\n### Web Fetcher 辅助脚本\n\n`web-fetcher-helper.js` 负责从网页中提取结构化数据：\n\n```javascript\n// 元数据提取流程\nmetadata.title // 从 JSON-LD、Open Graph、Twitter Card 获取\nmetadata.byline // 作者信息\nmetadata.excerpt // 文章摘要\nmetadata.siteName // 网站名称\nmetadata.publishedTime // 发布时间\n```\n\n支持的元数据源优先级：\n1. JSON-LD 结构化数据\n2. Open Graph 标签 (`og:*`)\n3. Twitter Card 标签 (`twitter:*`)\n4. Dublin Core 标签 (`dc:*`, `dcterm:*`)\n5. 通用 meta 标签\n\n资料来源：[inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n\n## 内容索引系统\n\n### ContentIndexer 模块\n\n`content-indexer.ts` 实现了自动化的标签页内容索引功能：\n\n```typescript\nclass ContentIndexer {\n private options: {\n autoIndex: boolean; // 是否自动索引\n maxContentLength: number; // 最大内容长度\n }\n \n // 核心方法\n indexTabContent(tabId: number): Promise\n removeTabIndex(tabId: number): Promise\n shouldIndexUrl(url: string): boolean\n extractTabContent(tabId): Promise<{ textContent, title }>\n}\n```\n\n### URL 过滤规则\n\n以下 URL 模式被排除在索引之外：\n\n| 模式 | 说明 |\n|------|------|\n| `chrome://*` | Chrome 内部页面 |\n| `chrome-extension://*` | 扩展页面 |\n| `edge://*` | Edge 内部页面 |\n| `about:*` | about 协议页面 |\n| `moz-extension://*` | Firefox 扩展页面 |\n| `file:///*` | 本地文件 |\n\n### 索引触发时机\n\n```mermaid\ngraph LR\n A[\"页面加载完成
status=complete\"] --> B{自动索引开启?}\n B -->|是| C{语义引擎就绪?}\n B -->|否| D[\"跳过\"]\n C -->|是| E[\"延迟 2 秒\"]\n C -->|否| D\n E --> F[\"执行索引\"]\n F --> G[\"存储索引数据\"]\n \n H[\"标签页关闭\"] --> I[\"移除索引\"]\n \n J[\"页面导航\"] --> K{\"frameId === 0?\"}\n K -->|是| L[\"移除旧索引\"]\n```\n\n资料来源：[utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n\n## 录制回放引擎\n\n### 引擎架构\n\n`record-replay/index.ts` 实现了 DOM 触发器驱动的自动化录制回放系统：\n\n```typescript\ninterface TriggerConfig {\n type: 'dom' | 'network' | 'custom';\n selector?: string; // DOM 选择器\n appear?: boolean; // 出现时触发\n once?: boolean; // 仅触发一次\n debounceMs?: number; // 防抖延迟\n enabled?: boolean;\n}\n```\n\n### 触发器类型\n\n| 类型 | 说明 | 配置项 |\n|------|------|--------|\n| DOM | DOM 元素变化触发 | selector, appear, once, debounceMs |\n| Network | 网络请求触发 | urlPattern, method |\n| Custom | 自定义触发器 | - |\n\n### 触发器工作流程\n\n```mermaid\nsequenceDiagram\n participant Ext as 扩展\n participant Tab as 标签页\n participant Observer as DOM Observer\n participant Trigger as 触发器\n \n Ext->>Tab: 注入 dom-observer.js\n Tab->>Observer: 创建 MutationObserver\n Observer->>Trigger: 检测到变化\n Trigger->>Trigger: 防抖处理\n Trigger->>Tab: 发送 set_dom_triggers\n Tab-->>Ext: 触发事件响应\n```\n\n### 初始化流程\n\n1. 从 storage 加载触发器配置\n2. 过滤启用的 DOM 类型触发器\n3. 遍历所有标签页注入脚本\n4. 发送触发器配置到各标签页\n\n资料来源：[entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)\n\n## 安全策略\n\n### Content Security Policy\n\n生产环境启用严格 CSP 策略：\n\n```typescript\ncontent_security_policy: {\n extension_pages: \n \"script-src 'self' 'wasm-unsafe-eval'; \" +\n \"object-src 'self'; \" +\n \"style-src 'self' 'unsafe-inline'; \" +\n \"img-src 'self' data: blob:;\"\n}\n```\n\n### 跨域隔离策略\n\n```typescript\ncross_origin_embedder_policy: { value: 'require-corp' },\ncross_origin_opener_policy: { value: 'same-origin' }\n```\n\n### Web Accessible Resources\n\n| 资源路径 | 用途 | 匹配范围 |\n|----------|------|----------|\n| `/models/*` | AI 模型文件 | `` |\n| `/workers/*` | Web Worker 文件 | `` |\n| `/inject-scripts/*` | 注入脚本辅助文件 | `` |\n\n## 技术栈\n\n| 组件 | 技术选型 |\n|------|----------|\n| 扩展框架 | WXT |\n| UI 框架 | Vue 3 |\n| 样式 | TailwindCSS v4 |\n| 图标 | SVG 组件自动注册 |\n| 构建工具 | Vite |\n| 脚本类型 | TypeScript |\n\n资料来源：[wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n\n## 扩展生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 安装: 首次安装\n 安装 --> 就绪: 初始化完成\n 就绪 --> 活跃: 用户操作\n 活跃 --> 等待: 空闲超时\n 等待 --> 活跃: 新操作\n 活跃 --> 更新: manifest 更新\n 更新 --> 就绪: 重新初始化\n 就绪 --> [*]: 卸载\n```\n\n## 常量定义\n\n扩展使用集中式常量管理：\n\n```typescript\n// 存储键名\nconst STORAGE_KEYS = {\n RR_TRIGGERS: 'rr_triggers',\n // ... 其他键\n}\n\n// 消息类型\nconst CONTENT_MESSAGE_TYPES = {\n ACCESSIBILITY_TREE_HELPER_PING: '...',\n // ... 其他类型\n}\n```\n\n资料来源：[common/constants.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/common/constants.ts)\n\n## 总结\n\nmcp-chrome 扩展采用现代化的多入口点架构，通过 WXT 框架简化了 manifest 管理。核心设计特点包括：\n\n1. **分层架构** - 清晰的后台脚本、内容脚本、注入脚本分层\n2. **工具化设计** - 丰富的浏览器控制工具集\n3. **自动化索引** - 智能的内容索引系统\n4. **录制回放** - 基于触发器的自动化引擎\n5. **安全优先** - 严格的 CSP 和跨域策略\n\n---\n\n\n\n## 本地服务器架构\n\n### 相关页面\n\n相关主题：[系统架构设计](#architecture), [AI Agent 集成](#agent-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/native-server/src/server/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/server/index.ts)\n- [app/native-server/src/mcp/mcp-server.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/mcp/mcp-server.ts)\n- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)\n- [app/native-server/src/agent/tool-bridge.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/tool-bridge.ts)\n- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)\n- [app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)\n \n\n# 本地服务器架构\n\n## 概述\n\nmcp-chrome 的本地服务器（Native Server）是整个系统的核心后端组件，负责在 AI 代理（如 Claude）和 Chrome 浏览器之间建立双向通信桥梁。该模块采用 Node.js/TypeScript 实现，通过 Native Messaging 协议与 Chrome 扩展进行交互，同时集成了 AI 引擎来完成复杂的浏览器自动化任务。\n\n本地服务器的核心职责包括：\n\n- **协议转换**：将 MCP（Model Context Protocol）协议转换为 Chrome 扩展可理解的命令\n- **工具编排**：管理 AI 引擎调用的各类工具（tool），包括浏览器操作、内容获取、网络请求等\n- **状态维护**：维护跨会话的浏览器状态和索引信息\n- **安全通信**：通过原生消息机制确保安全的进程间通信\n\n资料来源：[app/native-server/src/server/index.ts:1-50]()\n\n## 整体架构\n\nmcp-chrome 采用分层架构设计，各层之间通过定义良好的接口进行通信：\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Claude AI / MCP Client]\n end\n \n subgraph 本地服务器层\n B[MCP Server]\n C[Agent Engine]\n D[Tool Bridge]\n end\n \n subgraph 通信层\n E[Native Messaging]\n F[Chrome Extension Runtime]\n end\n \n subgraph 浏览器层\n G[Chrome Extension]\n H[Content Scripts]\n I[Inject Scripts]\n end\n \n A -->|MCP Protocol| B\n B --> C\n C --> D\n D -->|Native Message| E\n E --> F\n F --> G\n G --> H\n G --> I\n \n J[Web Content] --> I\n```\n\n## 核心组件\n\n### MCP 服务器\n\nMCP 服务器是整个架构的入口点，负责：\n\n- 初始化并管理 MCP 协议会话\n- 处理来自 AI 客户端的请求\n- 调度工具执行并返回结果\n- 管理会话生命周期\n\n| 组件 | 职责 | 关键文件 |\n|------|------|----------|\n| Session Manager | 管理多个并发会话 | mcp-server.ts |\n| Request Handler | 处理 MCP 请求/响应 | server/index.ts |\n| Tool Registry | 注册和管理可用工具 | tool-bridge.ts |\n\n资料来源：[app/native-server/src/mcp/mcp-server.ts:1-100]()\n\n### Agent 引擎\n\nAgent 引擎负责协调 AI 模型与工具系统之间的交互。当前实现支持 Claude 模型，未来可扩展支持其他模型。\n\n```mermaid\ngraph LR\n A[User Request] --> B[Parse Intent]\n B --> C{Requires Tools?}\n C -->|Yes| D[Tool Bridge]\n C -->|No| E[Direct Response]\n D --> F[Execute Tool]\n F --> G[Format Result]\n G --> H[Return to AI]\n E --> H\n```\n\n关键特性包括：\n\n- **流式处理**：支持流式输出和工具调用的交错处理\n- **错误恢复**：工具执行失败时的自动重试和错误报告\n- **上下文管理**：维护对话上下文和工具调用历史\n\n资料来源：[app/native-server/src/agent/engines/claude.ts:1-150]()\n\n### 工具桥接器\n\n工具桥接器（Tool Bridge）是连接 AI 引擎与 Chrome 扩展的枢纽，负责：\n\n- 工具发现和元数据管理\n- 参数验证和转换\n- 执行结果格式化\n- 错误处理和重试\n\n| 工具类别 | 数量 | 示例 |\n|----------|------|------|\n| 标签页管理 | 5 | chrome_tabs_query, chrome_tabs_create, chrome_tabs_update, chrome_tabs_close, chrome_tabs_move |\n| 导航控制 | 3 | chrome_navigate, chrome_go_back_or_forward, chrome_reload |\n| 内容获取 | 4 | chrome_get_web_content, chrome_screenshot, chrome_get_interactive_elements, search_tabs_content |\n| 网络操作 | 6 | chrome_network_capture_start, chrome_network_debugger_start, chrome_network_request 等 |\n| 书签管理 | 4 | chrome_bookmark_search, chrome_bookmark_add, chrome_bookmark_delete 等 |\n| 脚本注入 | 2 | chrome_inject_script, chrome_send_command_to_inject_script |\n\n资料来源：[app/native-server/src/agent/tool-bridge.ts:1-80]()\n\n## 通信机制\n\n### Native Messaging 协议\n\nmcp-chrome 使用 Chrome 的 Native Messaging 协议实现与扩展的安全通信。该协议基于标准输入/输出流进行 JSON 消息交换。\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant Chrome as Chrome Extension\n participant Native as Native Host\n \n MCP->>Native: 启动进程\n Native->>Chrome: 发送连接消息\n Chrome->>Native: 初始化握手\n Native->>MCP: 握手完成\n MCP->>Native: JSON-RPC 请求\n Native->>Chrome: 转发请求\n Chrome->>Native: 执行结果\n Native->>MCP: JSON-RPC 响应\n```\n\n消息格式遵循以下结构：\n\n```json\n{\n \"id\": \"unique-message-id\",\n \"method\": \"tool_name\",\n \"params\": {\n \"tabId\": 123,\n \"selector\": \"#element\"\n }\n}\n```\n\n### 跨平台支持\n\n本地服务器支持多个操作系统和浏览器组合的 Native Messaging 配置：\n\n| 平台 | 浏览器 | 配置路径 |\n|------|--------|----------|\n| Windows | Chrome | `%APPDATA%\\Google\\Chrome\\NativeMessagingHosts\\` |\n| Windows | Chromium | `%APPDATA%\\Chromium\\NativeMessagingHosts\\` |\n| macOS | Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` |\n| macOS | Chromium | `~/Library/Application Support/Chromium/NativeMessagingHosts/` |\n| Linux | Chrome | `~/.config/google-chrome/NativeMessagingHosts/` |\n| Linux | Chromium | `~/.config/chromium/NativeMessagingHosts/` |\n\n资料来源：[app/native-server/src/scripts/browser-config.ts:30-90]()\n\n## 内容索引系统\n\n### 语义搜索引擎\n\ncontent-indexer 模块提供了对浏览器标签页内容进行语义搜索的能力，这对于 AI 代理理解用户当前浏览内容至关重要。\n\n```mermaid\ngraph TD\n A[Tab Load Complete] --> B{Is Excluded URL?}\n B -->|chrome://| C[Skip]\n B -->|chrome-extension://| C\n B -->|about:| C\n B -->|file://| C\n B -->|Yes| D[Process Content]\n \n D --> E[Wait 2 seconds]\n E --> F[Inject Web Fetcher]\n F --> G[Extract Text + Metadata]\n G --> H[Index with Semantic Engine]\n H --> I[Store in Vector DB]\n \n C --> J[End]\n I --> J\n```\n\n关键配置参数：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| autoIndex | true | 页面加载完成后自动索引 |\n| indexDelay | 2000ms | 等待页面完全加载的延迟 |\n| excludePatterns | 5种 | 排除的 URL 模式（chrome://、file:// 等） |\n\n资料来源：[app/chrome-extension/utils/content-indexer.ts:40-80]()\n\n### 元数据提取\n\nweb-fetcher-helper.js 负责从网页中提取结构化元数据，支持多种数据源优先级：\n\n1. **JSON-LD** 结构化数据\n2. **Open Graph** 元标签\n3. **Twitter Card** 元标签\n4. **Dublin Core** 元标签\n5. **标准 HTML** 元标签\n\n提取的元数据字段：\n\n- `title` - 文章标题\n- `byline` - 作者信息\n- `excerpt` - 描述/摘要\n- `siteName` - 网站名称\n- `publishedTime` - 发布时间\n- `image` - 主图 URL\n\n资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js:1-100]()\n\n## 诊断系统\n\n### 健康检查流程\n\ndoctor.ts 提供了完整的系统诊断功能，确保本地服务器正确安装和配置：\n\n```mermaid\ngraph TD\n A[Run Diagnostics] --> B[Check Native Host]\n B --> C{Host Found?}\n C -->|No| D[Show Install Instructions]\n C -->|Yes| E[Check Manifest]\n \n E --> F{Manifest Valid?}\n F -->|No| G[Run Register Command]\n F -->|Yes| H[Check Permissions]\n \n H --> I{Permissions OK?}\n I -->|No| J[Show Permission Guide]\n I -->|Yes| K[All Checks Passed]\n \n D --> L[End]\n G --> L\n J --> L\n K --> L\n```\n\n### 诊断检查项\n\n| 检查项 | 状态标识 | 失败处理 |\n|--------|----------|----------|\n| 原生主机可执行文件 | `host.binary` | 提示安装步骤 |\n| 用户级 Manifest | `manifest.user` | `register --browser` |\n| 系统级 Manifest | `manifest.system` | 需要管理员权限 |\n| Windows 注册表 | `registry` | 自动修复注册 |\n| 允许来源 | `allowed_origins` | 重新注册扩展 ID |\n\n诊断报告会生成 Markdown 格式的输出，包含：\n\n- 各检查项的详细状态\n- 预期路径与实际路径对比\n- 修复建议和命令\n\n资料来源：[app/native-server/src/scripts/doctor.ts:100-200]()\n\n## 工作流程示例\n\n### 完整工具调用流程\n\n当 AI 代理需要执行浏览器操作时，整个调用流程如下：\n\n```mermaid\nsequenceDiagram\n participant AI as Claude AI\n participant MCP as MCP Server\n participant Engine as Agent Engine\n participant Bridge as Tool Bridge\n participant Ext as Chrome Extension\n \n AI->>MCP: tool_use request\n MCP->>Engine: dispatch tool call\n Engine->>Bridge: validate & prepare\n Bridge->>Ext: native message\n Ext->>Ext: execute in browser\n Ext-->>Bridge: result message\n Bridge->>Engine: format result\n Engine->>MCP: tool result\n MCP-->>AI: tool result response\n```\n\n### 状态管理\n\n工具执行过程中的状态流转：\n\n| 阶段 | 状态 | 说明 |\n|------|------|------|\n| 接收请求 | `pending` | 等待工具调度 |\n| 验证参数 | `validating` | 检查参数合法性 |\n| 发送消息 | `sending` | 写入 Native Message |\n| 等待响应 | `waiting` | 阻塞等待浏览器响应 |\n| 处理结果 | `processing` | 解析返回数据 |\n| 完成 | `completed` / `error` | 最终状态 |\n\n资料来源：[app/native-server/src/agent/engines/claude.ts:80-120]()\n\n## 安全考虑\n\n### Content Security Policy\n\n生产环境中启用严格的安全策略：\n\n```typescript\ncontent_security_policy: {\n extension_pages: \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\"\n}\n```\n\n### Web Accessible Resources\n\n受限的资源访问模式：\n\n- `/models/*` - AI 模型文件（需明确声明）\n- `/workers/*` - Web Worker 脚本\n- `/inject-scripts/*` - 内容脚本辅助文件\n\n资料来源：[app/chrome-extension/wxt.config.ts:20-40]()\n\n## 扩展性设计\n\n### 添加新工具\n\n在 tool-bridge.ts 中注册新工具的流程：\n\n1. 定义工具的 schema（名称、参数、返回值）\n2. 实现工具执行逻辑\n3. 注册到工具注册表\n4. 扩展 Chrome 扩展端的处理逻辑\n\n### 添加新 AI 引擎\n\nAgent 引擎采用策略模式设计，添加新引擎只需：\n\n1. 实现 `BaseEngine` 接口\n2. 在引擎工厂中注册\n3. 配置相应的 API 端点和认证\n\n## 总结\n\nmcp-chrome 的本地服务器架构通过清晰的层次划分和标准化的通信协议，实现了 AI 代理与浏览器之间的高效协作。核心优势包括：\n\n- **模块化设计**：各组件职责明确，易于测试和维护\n- **跨平台兼容**：支持 Windows、macOS、Linux 三大平台\n- **流式处理**：支持实时交互的低延迟响应\n- **可扩展性**：工具系统和引擎系统均支持灵活扩展\n\n该架构为构建智能化的浏览器自动化应用提供了坚实的技术基础。\n\n---\n\n\n\n## 浏览器工具集\n\n### 相关页面\n\n相关主题：[Chrome 扩展架构](#chrome-extension-structure), [可视化编辑器](#visual-editor)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/TOOLS.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS.md)\n- [docs/TOOLS_zh.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS_zh.md)\n- [app/chrome-extension/entrypoints/background/tools/browser/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/index.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/interaction.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/interaction.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts)\n \n\n# 浏览器工具集\n\n## 概述\n\n浏览器工具集是 mcp-chrome 项目中负责与 Chrome 浏览器进行交互的核心功能模块。通过 MCP（Model Context Protocol）协议，该工具集允许 AI Agent 能够感知、操控和分析浏览器状态，从而实现自动化浏览器操作、网页内容提取、网络请求监控等高级功能。\n\n工具集位于 `app/chrome-extension/entrypoints/background/tools/browser/` 目录下，采用模块化架构设计，每个工具类别对应独立的功能文件。资料来源：[app/chrome-extension/entrypoints/background/tools/browser/index.ts:1-50]()\n\n## 架构设计\n\n### 整体架构\n\n浏览器工具集采用分层架构，底层通过 Chrome Extension API 与浏览器内核交互，上层通过 MCP 协议暴露标准化的工具接口。\n\n```mermaid\ngraph TD\n A[MCP Client / AI Agent] --> B[Chrome Extension Background]\n B --> C[Browser Tools 模块]\n C --> D[chrome.tabs API]\n C --> E[chrome.webNavigation API]\n C --> F[chrome.webRequest API]\n C --> G[chrome.debugger API]\n C --> H[chrome.scripting API]\n \n D --> I[浏览器 Tab 管理]\n E --> J[页面导航监控]\n F --> K[网络请求拦截]\n G --> L[响应体调试]\n H --> M[脚本注入执行]\n```\n\n### 工具分类\n\n| 类别 | 工具数量 | 主要功能 |\n|------|----------|----------|\n| 标签页管理 | 4 | 创建、切换、关闭标签页 |\n| 导航控制 | 2 | 前进/后退、URL 跳转 |\n| 视图控制 | 2 | 缩放、视口调整 |\n| 截图 | 1 | 页面和元素截图 |\n| 网络监控 | 4 | 请求捕获、调试、自定义请求 |\n| 内容分析 | 4 | 内容提取、元素查找、控制台捕获 |\n| 交互操作 | 3 | 元素点击、表单填充、键盘输入 |\n\n资料来源：[docs/TOOLS.md:1-30]()\n\n## 标签页管理\n\n### 功能列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_create_tab` | 创建新的浏览器标签页 |\n| `chrome_switch_tab` | 切换当前活动标签页 |\n| `chrome_close_tabs` | 关闭指定标签页或窗口 |\n| `chrome_get_tabs` | 获取当前所有标签页列表 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/index.ts:50-100]()\n\n### 创建标签页\n\n`chrome_create_tab` 工具支持以下参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `url` | string | 是 | 目标 URL |\n| `active` | boolean | 否 | 是否激活新标签页（默认 true） |\n| `index` | number | 否 | 标签页位置索引 |\n| `windowId` | number | 否 | 指定窗口 ID |\n\n### 标签页切换与关闭\n\n- `chrome_switch_tab` 支持通过标签页 ID 或 URL 模式切换\n- `chrome_close_tabs` 支持关闭单个标签页、多个标签页或整个窗口\n- 所有操作均返回更新后的标签页状态\n\n## 导航控制\n\n### 前进/后退\n\n`chrome_go_back_or_forward` 工具提供浏览器历史导航功能：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `direction` | \"back\" \\| \"forward\" | 是 | 导航方向 |\n| `tabId` | number | 否 | 指定标签页（默认当前活动标签页） |\n| `steps` | number | 否 | 步进数量（默认 1） |\n\n### 视图控制\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_set_viewport` | 设置页面缩放比例和视口尺寸 |\n| `chrome_zoom` | 调整页面缩放级别 |\n\n## 截图功能\n\n### chrome_screenshot\n\n高级截图工具，支持多种截图模式：\n\n```typescript\ninterface ScreenshotOptions {\n tabId?: number; // 指定标签页\n fullPage?: boolean; // 全页面截图\n elementSelector?: string; // 特定元素截图\n width?: number; // 自定义宽度\n height?: number; // 自定义高度\n format?: 'png' | 'jpeg'; // 输出格式\n quality?: number; // 图片质量（1-100）\n}\n```\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts:1-50]()\n\n### 截图模式\n\n1. **标签页截图**：捕获指定标签页的可见区域\n2. **全页面截图**：通过滚动拼接获取整个页面\n3. **元素截图**：通过 CSS 选择器定位并截取特定元素\n\n### 技术实现\n\n截图功能通过 `chrome.tabs.captureVisibleTab` API 实现，对于全页面截图需要：\n\n1. 获取页面原始尺寸\n2. 设置视口为页面总高度\n3. 滚动页面并多次截图\n4. 拼接图像片段\n\n## 网络监控\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_network_capture_start` | 启动 webRequest API 网络捕获 |\n| `chrome_network_capture_stop` | 停止网络捕获 |\n| `chrome_network_debugger_start` | 启动 Debugger API 调试 |\n| `chrome_network_debugger_stop` | 停止调试模式 |\n| `chrome_network_request` | 发送自定义 HTTP 请求 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts:1-60]()\n\n### webRequest API 模式\n\n使用 `chrome.webRequest` API 监听网络请求：\n\n- 支持请求过滤（URL 模式、类型、状态码）\n- 可记录请求头、响应头、请求时间\n- 适合高并发场景的性能监控\n\n### Debugger API 模式\n\n使用 `chrome.debugger` API 获取完整响应体：\n\n- 支持拦截并修改请求/响应\n- 可以获取二进制响应内容\n- 适合需要深度分析 HTTP 流量的场景\n\n### 自定义请求\n\n`chrome_network_request` 支持构造完整的 HTTP 请求：\n\n```typescript\ninterface NetworkRequestOptions {\n url: string; // 请求 URL\n method?: string; // HTTP 方法\n headers?: object; // 请求头\n body?: string; // 请求体\n timeout?: number; // 超时时间\n}\n```\n\n## 内容分析\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `search_tabs_content` | 跨标签页语义搜索 |\n| `chrome_get_web_content` | 提取网页 HTML/文本内容 |\n| `chrome_get_interactive_elements` | 获取可交互元素列表 |\n| `chrome_console` | 捕获页面控制台输出 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts:1-80]()\n\n### search_tabs_content\n\n基于语义的内容搜索工具，支持：\n\n- 跨多个浏览器标签页进行全文搜索\n- 使用向量嵌入进行语义匹配\n- 返回匹配结果及其上下文片段\n\n### chrome_get_web_content\n\n网页内容提取工具：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `tabId` | number | 是 | 目标标签页 ID |\n| `format` | \"html\" \\| \"text\" | 否 | 输出格式（默认 text） |\n| `selectors` | string[] | 否 | CSS 选择器过滤 |\n\n### 交互元素获取\n\n`chrome_get_interactive_elements` 返回页面的可点击元素：\n\n```typescript\ninterface InteractiveElement {\n tagName: string; // 元素标签名\n id?: string; // 元素 ID\n className?: string; // 样式类名\n textContent?: string; // 文本内容\n attributes: object; // 所有属性\n boundingRect: object; // 位置坐标\n selector: string; // 唯一选择器\n}\n```\n\n## 交互操作\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `chrome_click_element` | 通过 CSS 选择器点击元素 |\n| `chrome_fill_or_select` | 填写表单或选择选项 |\n| `chrome_keyboard` | 模拟键盘输入和快捷键 |\n\n资料来源：[app/chrome-extension/entrypoints/background/tools/browser/interaction.ts:1-50]()\n\n### 元素点击\n\n`chrome_click_element` 通过 DOM 选择器定位并点击元素：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `selector` | string | 是 | CSS 选择器 |\n| `tabId` | number | 否 | 目标标签页 |\n| `button` | \"left\" \\| \"right\" \\| \"middle\" | 否 | 鼠标按钮 |\n| `clickCount` | number | 否 | 点击次数 |\n\n### 表单操作\n\n`chrome_fill_or_select` 支持多种表单输入：\n\n- **文本输入**：直接设置 input 值并触发 change 事件\n- **下拉选择**：通过 value 或文本选择选项\n- **复选框/单选框**：设置 checked 状态\n- **文件上传**：设置文件路径\n\n### 键盘模拟\n\n`chrome_keyboard` 支持：\n\n- 普通文本输入\n- 快捷键组合（如 `Command+Shift+P`）\n- 特殊键序列\n\n## 脚本注入\n\n### chrome_inject_script\n\n在网页上下文中执行自定义 JavaScript：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `tabId` | number | 是 | 目标标签页 |\n| `script` | string | 是 | JavaScript 代码 |\n| `args` | any[] | 否 | 传递给脚本的参数 |\n\n### chrome_send_command_to_inject_script\n\n向已注入的内容脚本发送命令，实现双向通信：\n\n```mermaid\nsequenceDiagram\n participant A as MCP Client\n participant B as Background Script\n participant C as Content Script\n \n A->>B: send_command_to_inject_script\n B->>C: chrome.tabs.sendMessage\n C-->>B: 消息响应\n B-->>A: 返回结果\n```\n\n## 数据模型\n\n### 工具返回格式\n\n所有工具遵循统一的响应格式：\n\n```typescript\ninterface ToolResponse {\n success: boolean; // 操作是否成功\n data?: T; // 返回数据\n error?: string; // 错误信息\n metadata?: { // 元数据\n tabId?: number;\n timestamp: number;\n duration?: number;\n };\n}\n```\n\n### 标签页模型\n\n```typescript\ninterface ChromeTab {\n id: number;\n windowId: number;\n index: number;\n url: string;\n title: string;\n active: boolean;\n pinned: boolean;\n status: 'loading' | 'complete';\n incognito: boolean;\n}\n```\n\n## 配置与扩展\n\n### 安全策略\n\n浏览器工具集在 Chrome Extension 中运行，需要配置适当的安全策略：\n\n资料来源：[app/chrome-extension/wxt.config.ts:1-30]()\n\n```typescript\ncontent_security_policy: {\n extension_pages: \n \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\",\n}\n```\n\n### 权限声明\n\n工具集需要在 `manifest.json` 中声明所需权限：\n\n- `tabs`：标签页管理\n- `webNavigation`：导航监控\n- `webRequest`：网络请求拦截\n- `debugger`：调试功能\n- `scripting`：脚本注入\n- ``：全网站访问\n\n## 最佳实践\n\n### 性能优化\n\n1. **批量操作**：多个标签页操作时使用 Promise.all 并行执行\n2. **按需截图**：仅在需要时进行全页面截图，避免频繁滚动\n3. **网络过滤**：使用精确的 URL 模式过滤减少事件监听开销\n\n### 错误处理\n\n1. 标签页操作前检查标签页是否存在\n2. 网络请求设置合理的超时时间\n3. 脚本注入前验证目标页面是否加载完成\n\n### 安全考虑\n\n1. 避免在不可信页面执行未验证的脚本\n2. 网络请求监控注意敏感信息保护\n3. 脚本注入仅在必要时使用\n\n## 相关资源\n\n- [工具文档（英文）](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS.md)\n- [工具文档（中文）](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS_zh.md)\n- [Chrome Extension API 文档](https://developer.chrome.com/docs/extensions/reference/)\n\n---\n\n\n\n## 录制回放系统 (V3)\n\n### 相关页面\n\n相关主题：[Chrome 扩展架构](#chrome-extension-structure), [浏览器工具集](#browser-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)\n- [app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts)\n- [app/chrome-extension/entrypoints/background/record-replay/recording/browser-event-listener.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/recording/browser-event-listener.ts)\n- [app/chrome-extension/entrypoints/background/tools/browser/common.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/common.ts)\n- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)\n \n\n# 录制回放系统 (V3)\n\n> **注意**：查询中请求的 `record-replay-v3` 目录下的源码文件未在当前上下文环境中检索到。以下文档基于现有的 `record-replay` 目录中的代码进行说明，涵盖了录制回放系统的核心架构与实现细节。\n\n## 概述\n\n录制回放系统是 Chrome MCP 扩展中用于记录用户浏览器操作并在需要时进行自动化回放的模块。该系统通过监听浏览器事件、捕获 DOM 变化、记录网络请求等方式，实现对用户操作流程的完整复现。\n\n系统设计目标包括：\n\n- **操作录制**：自动捕获用户的导航、点击、表单填写等交互行为\n- **智能触发**：支持基于 URL、DOM 变化、时间等多种触发条件\n- **流程回放**：精确还原录制时的操作序列\n- **状态同步**：在回放过程中处理页面状态变化和异步操作\n\n## 系统架构\n\n### 核心组件\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| BrowserEventListener | 监听并捕获浏览器事件 | `browser-event-listener.ts` |\n| Flow | 流程数据模型定义 | `domain/flow.ts` |\n| Kernel | 回放引擎核心 | `engine/kernel/kernel.ts` |\n| Triggers | 触发器管理 | `engine/triggers/index.ts` |\n| WaitPolicies | 等待策略（网络空闲检测等） | `engine/policies/wait.ts` |\n\n### 架构图\n\n```mermaid\ngraph TD\n subgraph 录制阶段\n BEL[BrowserEventListener]\n BEL -->|捕获事件| NE[导航事件]\n BEL -->|捕获事件| CE[点击事件]\n BEL -->|捕获事件| FE[表单事件]\n NE -->|记录| FL[Flow]\n CE -->|记录| FL\n FE -->|记录| FL\n end\n \n subgraph 回放阶段\n K[Kernel]\n K -->|读取| FL\n K -->|执行| IE[交互引擎]\n K -->|检测| WP[WaitPolicies]\n WP -->|等待条件| K\n K -->|触发| TR[Triggers]\n end\n \n subgraph 事件监听\n BEL -->|onCommitted| WN[webNavigation]\n BEL -->|onUpdated| TU[tabs.onUpdated]\n BEL -->|onRemoved| TRU[tabs.onRemoved]\n end\n```\n\n## 事件监听机制\n\n### 导航事件捕获\n\n系统通过 `chrome.webNavigation` API 监听页面导航事件，这是录制回放系统的核心数据来源。\n\n```typescript\nchrome.webNavigation.onCommitted.addListener(async (details) => {\n if (details.frameId !== 0) return;\n // 确保核心内容脚本已注入\n await ensureCoreInjected(details.tabId);\n // 获取存储的 DOM 触发器\n const { [STORAGE_KEYS.RR_TRIGGERS]: stored } = \n await chrome.storage.local.get(STORAGE_KEYS.RR_TRIGGERS);\n // ... 触发器处理逻辑\n});\n```\n\n**关键事件类型**：\n\n| 事件 | 触发条件 | 录制价值 |\n|------|----------|----------|\n| `onCommitted` | 导航提交时 | 记录初始 URL 变化 |\n| `onCompleted` | 页面加载完成 | 标记加载结束 |\n| `onHistoryStateUpdated` | 历史状态更新 | SPA 路由变化 |\n\n### 标签页事件监听\n\n```typescript\nchrome.tabs.onUpdated.addListener((updatedId, change, tab) => {\n if (updatedId !== tabId) return;\n // 检测 loading 状态\n if (change.status === 'loading') mark();\n // 检测 URL 变化\n if (typeof change.url === 'string' && (!prevUrl || change.url !== prevUrl)) mark();\n});\n```\n\n### 导航类型过滤\n\n系统会过滤特定的导航类型，只录制有意义的用户操作：\n\n```typescript\nconst shouldRecord =\n t === 'reload' ||\n t === 'typed' ||\n t === 'generated' ||\n t === 'auto_bookmark' ||\n t === 'keyword' ||\n t === 'form_submit'; // 捕获回车搜索行为\n```\n\n**不录制的类型**：`link`（纯链接点击由其他机制处理）\n\n## 流程数据模型\n\n### Flow 结构\n\nFlow 是录制回放系统的核心数据结构，用于存储录制过程中捕获的所有操作信息。\n\n```typescript\ninterface Flow {\n id: string; // 唯一标识\n steps: FlowStep[]; // 操作步骤列表\n metadata: FlowMeta; // 元数据\n triggers?: Trigger[]; // 关联的触发器\n}\n\ninterface FlowStep {\n type: 'navigation' | 'click' | 'input' | 'wait' | 'screenshot';\n timestamp: number;\n data: Record;\n}\n```\n\n### 导航步骤\n\n导航步骤记录页面 URL 变化和相关上下文：\n\n```typescript\nif (flow && url) {\n addNavigationStep(flow, url);\n}\n```\n\n## 触发器系统\n\n### 触发器类型\n\n| 类型 | 描述 | 适用场景 |\n|------|------|----------|\n| `url` | URL 模式匹配 | 特定页面触发 |\n| `dom` | DOM 元素检测 | 元素出现时触发 |\n| `timer` | 定时触发 | 周期性任务 |\n| `manual` | 手动触发 | 调试/测试 |\n\n### DOM 触发器配置\n\n```typescript\nconst domTriggers = triggers\n .filter((x) => x.type === 'dom' && x.enabled !== false)\n .map((x: any) => ({\n id: x.id,\n selector: x.selector, // CSS 选择器\n appear: x.appear !== false, // 出现/消失\n once: x.once !== false, // 单次/重复\n debounceMs: x.debounceMs ?? 800, // 防抖延迟\n }));\n```\n\n## 等待策略\n\n系统在回放过程中使用多种等待策略来确保页面状态就绪。\n\n### 网络空闲检测\n\n```typescript\nexport async function waitForNetworkIdle(\n tabId: number,\n sniffMs: number = 500,\n finish: () => void\n): Promise {\n let mark: () => void;\n let timer: ReturnType;\n\n const getLogger = (): ((...args: unknown[]) => void) => {\n return (...args: unknown[]) => console.log('[NetworkIdle]', ...args);\n };\n\n const isIdle = (): boolean => {\n // 检测逻辑\n };\n\n const wait = (): Promise =>\n new Promise((resolve) => {\n mark = resolve;\n const startedAt = Date.now();\n let prevUrl: string | undefined;\n\n const onCommitted = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n\n const onCompleted = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n\n const onHistoryStateUpdated = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n\n const onUpdated = (updatedId: number, change: chrome.tabs.TabChangeInfo) => {\n if (updatedId !== tabId) return;\n if (change.status === 'loading') mark();\n if (typeof change.url === 'string' && (!prevUrl || change.url !== prevUrl)) mark();\n };\n\n chrome.webNavigation.onCommitted.addListener(onCommitted);\n chrome.webNavigation.onCompleted.addListener(onCompleted);\n chrome.tabs.onUpdated.addListener(onUpdated);\n timer = setTimeout(finish, sniffMs);\n });\n}\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `tabId` | number | - | 目标标签页 ID |\n| `sniffMs` | number | 500 | 空闲检测时间窗口（毫秒） |\n| `finish` | function | - | 超时完成回调 |\n\n## 内容脚本注入\n\n系统通过 `chrome.scripting.executeScript` API 向目标页面注入脚本，以获取页面内容或执行特定操作。\n\n```typescript\nawait chrome.scripting.executeScript({\n target: { tabId: details.tabId, allFrames: true },\n files: ['inject-scripts/dom-observer.js'],\n world: 'ISOLATED',\n});\n```\n\n### 注入脚本类型\n\n| 脚本 | 用途 | 作用域 |\n|------|------|--------|\n| `web-fetcher-helper.js` | 页面内容提取 | ISOLATED |\n| `dom-observer.js` | DOM 变化监听 | ISOLATED |\n\n### 消息通信\n\n```typescript\nawait chrome.tabs.sendMessage(details.tabId, {\n action: 'setTriggers',\n triggers: domTriggers,\n});\n```\n\n## 录制状态管理\n\n### 会话状态\n\n```typescript\ninterface Session {\n getStatus(): 'idle' | 'recording' | 'replaying';\n getFlow(): Flow | null;\n getActiveTabs(): number[];\n}\n```\n\n### 状态转换\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: 初始化\n Idle --> Recording: 开始录制\n Recording --> Replaying: 执行回放\n Replaying --> Idle: 回放完成\n Recording --> Idle: 停止录制\n Idle --> [*]: 清理\n```\n\n### 活动标签页管理\n\n```typescript\n// 录制开始时记录活动标签页\nsession.addActiveTab(tabId);\n\n// 标签页关闭时移除\nchrome.tabs.onRemoved.addListener((tabId) => {\n if (session.getStatus() !== 'recording') return;\n session.removeActiveTab(tabId);\n});\n```\n\n## 与其他模块的交互\n\n### 与工具系统的集成\n\n录制回放系统通过 MCP 工具协议暴露功能：\n\n```typescript\n// 注册命令处理器\nchrome.commands.onCommand.addListener(async (command) => {\n const t = commands.find((k) => k.command === command);\n if (!t || t.enabled === false) return;\n \n const flow = await getFlow(t.flowId);\n if (!flow) return;\n \n await runFlow(flow, { args: t.args || {}, returnLogs: false });\n});\n```\n\n### 与内容索引器的协同\n\n系统与 `ContentIndexer` 模块共享部分事件监听器：\n\n```typescript\nif (chrome.webNavigation) {\n chrome.webNavigation.onCommitted.addListener(async (details) => {\n if (details.frameId === 0) {\n await this.removeTabIndex(details.tabId);\n }\n });\n}\n```\n\n## 安全考虑\n\n### 跨域隔离策略\n\n在生产环境中，系统启用以下安全策略：\n\n```typescript\ncross_origin_embedder_policy: { value: 'require-corp' as const },\ncross_origin_opener_policy: { value: 'same-origin' as const },\n```\n\n### 内容安全策略\n\n```typescript\ncontent_security_policy: {\n extension_pages:\n \"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;\",\n}\n```\n\n## 最佳实践\n\n1. **触发器防抖**：DOM 触发器建议设置 `debounceMs >= 800ms` 避免误触发\n2. **资源访问控制**：通过 `web_accessible_resources` 限制可访问资源范围\n3. **错误处理**：关键操作使用 try-catch 包装，防止单点故障影响整体录制\n4. **标签页清理**：及时移除关闭的标签页 ID，避免无效广播\n\n## 相关文档\n\n- [工具系统概览](../tools/overview.md)\n- [内容索引系统](./content-indexer.md)\n- [MCP 协议文档](../protocol/index.md)\n\n---\n\n\n\n## 可视化编辑器\n\n### 相关页面\n\n相关主题：[浏览器工具集](#browser-tools), [录制回放系统 (V3)](#record-replay-v3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)\n- [app/chrome-extension/entrypoints/background/web-editor/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/web-editor/index.ts)\n- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)\n- [app/chrome-extension/entrypoints/builder/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/builder/index.html)\n- [app/chrome-extension/entrypoints/sidepanel/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/index.html)\n \n\n# 可视化编辑器\n\n## 概述\n\n可视化编辑器（Visual Editor）是 mcp-chrome 项目中用于网页元素编辑的核心功能模块。该编辑器允许 AI Agent 通过自然语言指令直接操作网页上的元素，实现自动化网页交互与编辑功能。\n\nmcp-chrome 的可视化编辑器采用双版本架构，支持 **WebEditor V1**（旧版）与 **WebEditor V2**（新版）两种实现方式，通过 `USE_WEB_EDITOR_V2` 配置开关进行切换。资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:1-100]()\n\n## 架构设计\n\n### 双版本架构\n\n可视化编辑器采用 V1 和 V2 两个版本并行运行的架构设计：\n\n| 版本 | 标识常量 | 脚本路径 | 说明 |\n|------|----------|----------|------|\n| V1 | `USE_WEB_EDITOR_V2 = false` | `V1_SCRIPT_PATH` | 传统版本，稳定兼容 |\n| V2 | `USE_WEB_EDITOR_V2 = true` | `V2_SCRIPT_PATH` | 新版增强版本 |\n\n两个版本使用不同的 action 名称来避免冲突：\n\n- **V1 动作**：`web_editor_ping`、`web_editor_toggle` 等\n- **V2 动作**：`web_editor_ping_v2`、`web_editor_toggle_v2` 等\n\n资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:200-230]()\n\n### 组件层次结构\n\n```\nmcp-chrome 扩展\n├── Background Script (web-editor/index.ts)\n│ ├── 上下文菜单注册\n│ ├── 脚本注入管理\n│ └── 消息通信处理\n├── Content Script (注入脚本)\n│ ├── 元素标记器 (element-marker.js)\n│ └── 交互处理器\n└── Sidepanel UI\n ├── Agent Chat (时间线视图)\n └── 工作流编辑器\n```\n\n资料来源：[app/chrome-extension/wxt.config.ts:1-50]()\n\n## 核心功能\n\n### 元素标记与选择\n\n编辑器提供可视化的元素标记功能，用户可以通过点击或按空格键选择页面元素：\n\n- 高亮显示可交互元素\n- 显示元素信息面板\n- 支持 Shift 键多选模式\n- 元素检查器集成\n\n资料来源：[app/chrome-extension/inject-scripts/element-marker.js:1-100]()\n\n### 上下文菜单集成\n\n编辑器通过 Chrome 扩展的上下文菜单 API 注册快捷入口：\n\n```typescript\nawait chrome.contextMenus.create({\n id: CONTEXT_MENU_ID,\n title: '切换网页编辑模式',\n contexts: ['all'],\n});\n```\n\n该菜单项支持在任意页面通过右键调用\"切换网页编辑模式\"功能。资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:150-170]()\n\n### 脚本注入机制\n\n编辑器支持将脚本动态注入到目标页面，注入过程如下：\n\n```mermaid\nsequenceDiagram\n participant BG as Background Script\n participant Tab as Target Tab\n participant Script as Injected Script\n \n BG->>BG: ensureEditorInjected(tabId)\n BG->>BG: 获取版本对应脚本路径\n BG->>Tab: chrome.scripting.executeScript\n Tab->>Script: 加载编辑器脚本\n Script->>BG: 返回注入确认\n BG->>Tab: 发送初始化命令\n```\n\n资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:230-260]()\n\n## 交互流程\n\n### 编辑模式切换\n\n1. 用户通过上下文菜单或快捷键触发切换\n2. Background Script 检查目标 Tab 是否已注入编辑器脚本\n3. 如未注入，调用 `ensureEditorInjected()` 注入脚本\n4. 发送 `web_editor_toggle` 或 `web_editor_toggle_v2` 命令\n5. Content Script 接收命令，切换页面编辑状态\n\n### 动作响应函数\n\n根据版本不同，编辑器支持以下核心动作：\n\n| 动作名称 | V1 | V2 | 功能描述 |\n|----------|----|----|----------|\n| `web_editor_ping` | ✓ | ✓ | 检测编辑器连接状态 |\n| `web_editor_toggle` | ✓ | ✗ | 切换编辑模式 |\n| `web_editor_toggle_v2` | ✗ | ✓ | 切换编辑模式（V2） |\n| `web_editor_apply` | ✓ | ✓ | 应用变更 |\n\n资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:200-250]()\n\n## 状态管理\n\n### 等待策略\n\n编辑器内置网络空闲等待策略，用于确保页面完全加载后再进行操作：\n\n```typescript\nfunction waitForNetworkIdle(tabId: number, sniffMs = 2000): Promise {\n // 监听网络请求完成\n // 监听标签页更新\n // 监听 URL 变化\n // 超时自动结束\n}\n```\n\n资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts:1-50]()\n\n### 设计令牌\n\n编辑器使用设计令牌系统统一管理样式变量，确保界面一致性：\n\n```typescript\n// 设计令牌示例\nexport const tokens = {\n colors: {\n primary: '#xxx',\n secondary: '#xxx',\n },\n spacing: {\n small: '8px',\n medium: '16px',\n },\n};\n```\n\n## 扩展集成\n\n### 入口点配置\n\nmcp-chrome 扩展定义了多个入口点，编辑器作为 Sidepanel 页面的一部分运行：\n\n| 入口点 | 文件路径 | 用途 |\n|--------|----------|------|\n| sidepanel | `entrypoints/sidepanel/index.html` | 工作流管理主界面 |\n| builder | `entrypoints/builder/index.html` | 工作流编辑器 |\n| options | `entrypoints/options/index.html` | 用户脚本管理器 |\n| background | `entrypoints/background/` | 后台服务脚本 |\n\n资料来源：[app/chrome-extension/entrypoints/sidepanel/index.html:1-15]()\n\n### Web Accessible Resources\n\n编辑器通过 `web_accessible_resources` 配置允许注入脚本访问资源：\n\n```typescript\nweb_accessible_resources: [\n {\n resources: [\n '/models/*',\n '/workers/*',\n '/inject-scripts/*',\n ],\n matches: [''],\n },\n]\n```\n\n资料来源：[app/chrome-extension/wxt.config.ts:20-30]()\n\n## 使用示例\n\n### AI 辅助网页编辑\n\n用户可以让 AI Agent 帮助编辑当前网页：\n\n1. 打开目标网页\n2. 在 Sidepanel 中启动 AI 对话\n3. 使用 AgentChat 时间线追踪操作\n4. AI 通过 MCP 协议调用编辑器工具\n5. 编辑器将变更应用到页面\n\n### 工作流构建\n\n编辑器支持工作流模式，允许用户预先定义操作序列：\n\n1. 在 Builder 入口点创建工作流\n2. 定义触发条件和操作步骤\n3. 保存工作流配置\n4. 在需要时触发执行\n\n## 安全策略\n\n编辑器在生产环境启用以下安全策略：\n\n| 策略 | 配置值 | 用途 |\n|------|--------|------|\n| `cross_origin_embedder_policy` | `require-corp` | 跨源隔离 |\n| `cross_origin_opener_policy` | `same-origin` | 同源策略 |\n| `content_security_policy` | 定制规则 | 内容安全限制 |\n\n开发环境使用 WXT 默认策略，避免阻断开发服务器资源加载。资料来源：[app/chrome-extension/wxt.config.ts:35-50]()\n\n## 总结\n\n可视化编辑器是 mcp-chrome 项目的核心交互模块，通过结合 Chrome 扩展 API、MCP 协议和 AI Agent 技术，实现了自然语言驱动的网页编辑能力。其双版本架构确保了向后兼容性和持续演进，丰富的上下文菜单集成和脚本注入机制提供了灵活的使用方式。\n\n---\n\n\n\n## 语义搜索与向量数据库\n\n### 相关页面\n\n相关主题：[浏览器工具集](#browser-tools), [AI Agent 集成](#agent-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/chrome-extension/utils/vector-database.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/vector-database.ts)\n- [app/chrome-extension/utils/semantic-similarity-engine.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/semantic-similarity-engine.ts)\n- [app/chrome-extension/utils/text-chunker.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/text-chunker.ts)\n- [app/chrome-extension/utils/simd-math-engine.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/simd-math-engine.ts)\n- [packages/wasm-simd/src/lib.rs](https://github.com/hangwin/mcp-chrome/blob/main/packages/wasm-simd/src/lib.rs)\n \n\n# 语义搜索与向量数据库\n\n## 概述\n\nmcp-chrome 扩展中的语义搜索与向量数据库模块为浏览器标签页内容提供了基于语义理解的智能搜索能力。该模块将网页文本内容转换为高维向量嵌入（Embedding），存储在本地向量数据库中，并支持通过语义相似度进行跨标签页内容检索。\n\n此功能的核心价值在于突破传统关键词搜索的局限性——用户可以使用自然语言描述来查找曾经访问过的内容，而无需记忆具体词汇或页面标题。\n\n## 核心架构\n\n### 模块组成\n\n| 模块 | 文件路径 | 主要职责 |\n|------|----------|----------|\n| 向量数据库 | `utils/vector-database.ts` | 存储和管理文本块向量嵌入 |\n| 语义相似度引擎 | `utils/semantic-similarity-engine.ts` | 生成文本嵌入并执行相似度计算 |\n| 文本分块器 | `utils/text-chunker.ts` | 将长文本分割为可管理的块 |\n| SIMD数学引擎 | `utils/simd-math-engine.ts` | 提供SIMD优化的向量运算 |\n| WASM SIMD模块 | `packages/wasm-simd/src/lib.rs` | Rust实现的SIMD计算后端 |\n\n### 架构图\n\n```mermaid\ngraph TD\n A[网页内容] --> B[内容索引器
content-indexer.ts]\n B --> C[文本分块器
text-chunker.ts]\n C --> D[语义相似度引擎
semantic-similarity-engine.ts]\n D --> E[SIMD数学引擎
simd-math-engine.ts]\n E --> F[WASM SIMD模块
Rust lib.rs]\n F --> G[向量数据库
vector-database.ts]\n G --> H[语义搜索查询]\n \n B -.->|网络请求| I[Inject Script
web-fetcher-helper.js]\n I --> B\n```\n\n## 工作流程\n\n### 内容索引流程\n\n当用户访问网页并完成加载后，系统自动触发以下索引流程：\n\n```mermaid\ngraph LR\n A[Tab加载完成] --> B{语义引擎就绪?}\n B -->|否| C[跳过索引]\n B -->|是| D[等待2秒缓冲]\n D --> E[提取页面内容]\n E --> F[执行web-fetcher-helper.js]\n F --> G[获取文本和标题]\n G --> H[文本分块]\n H --> I[生成向量嵌入]\n I --> J[存储至向量数据库]\n \n K[Tab关闭/导航] --> L[删除相关索引]\n```\n\n### URL过滤机制\n\n系统内置URL过滤规则，排除以下类型的地址不进行索引：\n\n```typescript\nconst excludePatterns = [\n /^chrome:\\/\\//, // Chrome内部页面\n /^chrome-extension:\\/\\//, // 扩展页面\n /^edge:\\/\\//, // Edge内部页面\n /^about:/, // about页面\n /^moz-extension:\\/\\//, // Firefox扩展\n /^file:\\/\\//, // 本地文件\n];\n```\n\n资料来源：[content-indexer.ts:55-61]()\n\n### 语义搜索流程\n\n```mermaid\ngraph TD\n A[用户查询] --> B[转换为向量]\n B --> C[向量数据库检索]\n C --> D[计算余弦相似度]\n D --> E[排序结果]\n E --> F[返回相关内容片段]\n```\n\n## 向量数据库\n\n向量数据库模块负责管理所有已索引内容的向量表示。每个向量条目包含以下信息：\n\n- **文本块内容**：原始文本片段\n- **向量嵌入**：由语义相似度引擎生成的高维向量\n- **元数据**：来源标签页ID、URL、时间戳等\n\n### 核心操作\n\n| 操作 | 说明 |\n|------|------|\n| 插入 | 添加新的向量条目 |\n| 删除 | 移除指定标签页的所有条目 |\n| 搜索 | 基于向量相似度返回相关内容 |\n| 更新 | 修改现有条目（通常不常用） |\n\n## 语义相似度引擎\n\n语义相似度引擎是将文本转换为向量嵌入的核心组件。它使用预训练的Transformer模型将任意文本映射到一个稠密的向量空间，使得语义相似的文本在该空间中距离较近。\n\n### 主要功能\n\n1. **嵌入生成**：将文本块转换为固定维度的浮点数向量\n2. **相似度计算**：使用余弦相似度或点积计算向量间的语义相似程度\n3. **批处理支持**：支持一次性处理多个文本块以提高效率\n\n## 文本分块器\n\n由于网页内容可能非常长，直接对整页内容生成单一向量会导致精度下降。文本分块器将长文本分割为适当大小的块，每个块独立生成向量。\n\n### 分块策略考量\n\n- **块大小**：需要在语义完整性和向量容量之间取得平衡\n- **重叠**：相邻块之间可能存在一定重叠，以避免边界语义丢失\n- **上下文保留**：分块时考虑句子和段落的自然边界\n\n## SIMD数学引擎\n\n为了在浏览器环境中实现高性能的向量运算，系统使用SIMD（单指令多数据）技术加速计算。\n\n### WASM SIMD模块\n\nRust实现的SIMD计算后端通过WebAssembly提供以下能力：\n\n- 向量点积计算\n- 向量归一化\n- 余弦相似度计算\n- 批量矩阵运算\n\n### 性能优化\n\n```mermaid\ngraph LR\n A[JavaScript向量运算] -->|慢| B[串行计算]\n A -->|快| C[SIMD向量化]\n C --> D[并行处理多条数据]\n D --> E[显著提升吞吐量]\n```\n\n使用SIMD指令集，单条CPU指令可以同时处理多个数据元素，这对于大规模向量运算（如搜索10万条记录）尤为重要。\n\n## 搜索标签页内容功能\n\n语义搜索系统的主要应用场景是跨标签页的语义检索。\n\n### 使用方式\n\n用户可以通过自然语言描述来搜索之前访问过的标签页内容。例如：\n\n- \"查找我昨天看的关于机器学习的文章\"\n- \"搜索包含Python代码示例的页面\"\n- \"找出讨论过向量数据库的标签\"\n\n### 技术实现\n\n1. 用户输入查询文本\n2. 系统将查询转换为向量\n3. 在向量数据库中执行相似度搜索\n4. 返回最相关的标签页和内容片段\n5. 提供快速跳转链接\n\n## 配置与状态管理\n\n### 引擎状态\n\n语义引擎维护以下状态：\n\n| 状态 | 说明 |\n|------|------|\n| 未初始化 | 引擎尚未加载 |\n| 初始化中 | 正在加载模型 |\n| 就绪 | 可接受索引和搜索请求 |\n| 错误 | 引擎发生错误 |\n\n### 自动索引控制\n\n```typescript\nif (this.options.autoIndex && changeInfo.status === 'complete' && tab.url) {\n setTimeout(() => {\n if (!this.isSemanticEngineReady() && !this.isSemanticEngineInitializing()) {\n return; // 跳过\n }\n this.indexTabContent(tabId);\n }, 2000);\n}\n```\n\n资料来源：[content-indexer.ts:27-40]()\n\n## 安全与隔离\n\n### 扩展页面隔离\n\n生产环境中启用以下安全策略：\n\n```typescript\ncross_origin_embedder_policy: { value: 'require-corp' },\ncross_origin_opener_policy: { value: 'same-origin' },\n```\n\n资料来源：[wxt.config.ts:44-47]()\n\n这些策略确保向量数据库和语义引擎的数据不会被恶意网页访问。\n\n### Web资源访问控制\n\n只有明确指定的资源可以被网页内容脚本访问：\n\n```typescript\nweb_accessible_resources: [\n '/models/*', // AI模型文件\n '/workers/*', // Web Workers\n '/inject-scripts/*' // 注入脚本\n]\n```\n\n资料来源：[wxt.config.ts:25-33]()\n\n## 性能优化策略\n\n### 延迟索引\n\n系统在页面加载完成2秒后才开始索引，避免阻塞页面渲染：\n\n```typescript\nsetTimeout(() => {\n this.indexTabContent(tabId);\n}, 2000);\n```\n\n资料来源：[content-indexer.ts:33]()\n\n### 条件索引\n\n只有当语义引擎完全就绪时才执行索引操作，避免因引擎未准备好而产生错误。\n\n### 导航事件监听\n\n系统监听多种导航事件以保持索引同步：\n\n- `tabs.onUpdated`：检测页面加载状态变化\n- `tabs.onRemoved`：删除关闭标签页的索引\n- `webNavigation.onCommitted`：检测主帧导航\n- `webNavigation.onHistoryStateUpdated`：检测SPA路由变化\n\n## 总结\n\nmcp-chrome的语义搜索与向量数据库模块为浏览器标签页提供了强大的语义理解能力。通过将网页内容转换为向量嵌入并存储在本地向量数据库中，用户可以使用自然语言进行跨标签页搜索。SIMD优化的数学引擎确保了计算性能，而完善的索引管理机制保证了搜索结果的实时性和准确性。\n\n---\n\n\n\n## AI Agent 集成\n\n### 相关页面\n\n相关主题：[本地服务器架构](#native-server-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [app/native-server/src/agent/engines/types.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/types.ts)\n- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)\n- [app/native-server/src/agent/engines/codex.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/codex.ts)\n- [app/native-server/src/agent/chat-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/chat-service.ts)\n- [app/native-server/src/agent/session-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/session-service.ts)\n- [app/chrome-extension/entrypoints/sidepanel/composables/useAgentChat.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/composables/useAgentChat.ts)\n- [app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts)\n \n\n# AI Agent 集成\n\n## 概述\n\nAI Agent 集成是 mcp-chrome 项目中连接浏览器扩展与本地 AI 引擎的核心模块。该系统支持多种 AI 引擎（包括 Claude 和 Codex），通过统一的接口抽象，为浏览器扩展提供智能代理能力。用户可以在浏览器侧边栏中与 AI Agent 对话，执行自动化工作流、网页内容分析和浏览器控制等任务。\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n subgraph 浏览器扩展\n A[Sidepanel UI] --> B[useAgentChat]\n A --> C[useAgentThreads]\n B --> D[MCP Tools]\n C --> D\n end\n \n subgraph 本地服务\n D --> E[ChromeMcpServer]\n E --> F[ChatService]\n E --> G[SessionService]\n F --> H[Engine Adapter]\n G --> H\n end\n \n subgraph AI 引擎\n H --> I[Claude Engine]\n H --> J[Codex Engine]\n end\n```\n\n### 核心组件关系\n\n| 组件 | 层级 | 职责 | 源码位置 |\n|------|------|------|----------|\n| `useAgentChat` | 前端 | 管理聊天状态、消息流、引擎选择 | `useAgentChat.ts` |\n| `useAgentThreads` | 前端 | 管理 Agent 线程和工具调用可视化 | `useAgentThreads.ts` |\n| `ChatService` | 服务层 | 协调 AI 引擎与 MCP 工具的交互 | `chat-service.ts` |\n| `SessionService` | 服务层 | 管理会话生命周期和元数据 | `session-service.ts` |\n| `ClaudeEngine` | 引擎层 | Claude API 集成实现 | `engines/claude.ts` |\n| `CodexEngine` | 引擎层 | Codex CLI 集成实现 | `engines/codex.ts` |\n\n## 引擎类型定义\n\n### 引擎基类与类型\n\n项目定义了统一的引擎抽象接口，支持多引擎并行：\n\n```typescript\nexport interface AgentEngine {\n name: string;\n provider: string;\n readonly: boolean;\n \n chat(options: ChatOptions): Promise>;\n destroy(): Promise;\n}\n```\n\n资料来源：[engines/types.ts:1-10]()\n\n### 支持的引擎类型\n\n| 引擎 | Provider | 说明 |\n|------|----------|------|\n| Claude | Anthropic | 使用 Claude SDK 进行对话 |\n| Codex | OpenAI | 使用 Codex CLI 进行代码任务 |\n\n## 会话管理\n\n### SessionService 功能\n\n`SessionService` 负责管理 AI Agent 会话的生命周期，提供了丰富的会话元数据管理能力。\n\n#### 管理信息接口\n\n```typescript\nexport interface ManagementInfo {\n models?: Array<{ value: string; displayName: string; description: string }>;\n commands?: Array<{ name: string; description: string; argumentHint: string }>;\n account?: { email?: string; organization?: string; subscriptionType?: string };\n mcpServers?: Array<{ name: string; status: string }>;\n tools?: string[];\n agents?: string[];\n plugins?: Array<{ name: string; path?: string }>;\n skills?: string[];\n slashCommands?: string[];\n model?: string;\n permissionMode?: string;\n cwd?: string;\n outputStyle?: string;\n betas?: string[];\n claudeCodeVersion?: string;\n apiKeySource?: string;\n lastUpdated?: string;\n}\n```\n\n资料来源：[session-service.ts:46-69]()\n\n#### 会话预览元数据\n\n```typescript\nexport interface AgentSessionPreviewMeta {\n displayText?: string;\n clientMeta?: {\n kind?: string;\n // 扩展元数据\n };\n}\n```\n\n资料来源：[session-service.ts:82-88]()\n\n### 会话配置选项\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `model` | string | 指定使用的模型 |\n| `mcpServers` | Record | MCP 服务器配置 |\n| `outputFormat` | Record | 输出格式配置 |\n| `enableFileCheckpointing` | boolean | 启用文件检查点 |\n| `sandbox` | Record | 沙箱环境配置 |\n| `env` | Record | 环境变量 |\n| `codexConfig` | Partial | Codex 特定配置覆盖 |\n\n## ChatService 协调层\n\n### 核心职责\n\n`ChatService` 作为中间协调层，负责：\n1. 接收来自扩展的聊天请求\n2. 路由到对应的 AI 引擎\n3. 处理工具调用和结果回传\n4. 管理会话状态\n\n### 消息流处理\n\n```mermaid\nsequenceDiagram\n participant EXT as 浏览器扩展\n participant CHAT as ChatService\n participant ENGINE as AI 引擎\n participant MCP as MCP Tools\n \n EXT->>CHAT: 发送用户消息\n CHAT->>ENGINE: 转发消息流\n ENGINE->>ENGINE: AI 处理\n ENGINE-->>CHAT: 返回 ChatProgress 流\n CHAT-->>EXT: 流式响应\n Note over ENGINE,MCP: 工具调用时\n ENGINE->>MCP: 请求工具执行\n MCP-->>ENGINE: 返回执行结果\n```\n\n## Claude 引擎集成\n\n### ClaudeEngine 实现\n\nClaude 引擎通过官方 Claude SDK 实现对话功能：\n\n```typescript\nexport class ClaudeEngine implements AgentEngine {\n name = 'claude';\n provider = 'anthropic';\n readonly = false;\n \n async *chat(options: ChatOptions): AsyncIterable {\n // SDK 集成实现\n }\n}\n```\n\n### 关键能力\n\n| 功能 | 支持 | 说明 |\n|------|------|------|\n| 流式输出 | ✅ | 支持实时流式响应 |\n| 工具调用 | ✅ | 支持 MCP 工具集成 |\n| 多模态 | ✅ | 支持图像输入 |\n| 会话保持 | ✅ | 维护对话上下文 |\n\n## Codex 引擎集成\n\n### CodexEngine 特性\n\nCodex 引擎通过 Codex CLI 实现，特别适用于代码任务：\n\n```typescript\nexport class CodexEngine implements AgentEngine {\n name = 'codex';\n provider = 'openai';\n readonly = false;\n \n async *chat(options: ChatOptions): AsyncIterable {\n // CLI 集成实现\n }\n}\n```\n\n### 配置参数\n\nCodex 引擎支持丰富的配置选项：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `include_apply_patch_tool` | boolean | true | 包含 apply_patch 工具 |\n| `include_plan_tool` | boolean | true | 包含计划工具 |\n| `enableWebSearch` | boolean | false | 启用网页搜索 |\n| `use_experimental_streamable_shell_tool` | boolean | - | 实验性流式 Shell 工具 |\n\n资料来源：[engines/codex.ts:buildCodexConfigArgs()]()\n\n### 项目上下文处理\n\nCodex 引擎自动检测项目目录结构：\n\n```typescript\n// 读取目录内容，排除 .git 和 AGENTS.md\nconst visible = entries\n .filter((entry) => !entry.name.startsWith('.git') && entry.name !== 'AGENTS.md')\n .map((entry) => entry.name);\n\n// 注入到系统提示\nreturn `${baseInstruction}\n\nCurrent files in project directory: ${visible.sort().join(', ')}\nWork directly in the current directory.\n`;\n```\n\n资料来源：[engines/codex.ts:appendProjectContext()]()\n\n## 前端集成\n\n### useAgentChat Composable\n\n`useAgentChat` 是前端与 AI Agent 通信的核心 Hook：\n\n```typescript\nexport function useAgentChat() {\n // 聊天状态管理\n // 消息发送与接收\n // 引擎切换\n // 流式响应处理\n}\n```\n\n#### 核心功能\n\n| 功能 | 方法 | 说明 |\n|------|------|------|\n| 发送消息 | `sendMessage()` | 发送用户消息 |\n| 流式接收 | 响应迭代器 | 处理 AI 流式输出 |\n| 引擎管理 | `switchEngine()` | 动态切换 AI 引擎 |\n| 中断控制 | `abort()` | 中断正在进行的请求 |\n\n### useAgentThreads Composable\n\n`useAgentThreads` 提供 Agent 线程管理，包括工具调用的可视化展示：\n\n```typescript\nexport function useAgentThreads() {\n // 线程列表管理\n // 工具调用记录\n // 状态追踪\n}\n```\n\n#### 工具调用分类\n\n系统根据工具名称和内容自动分类工具调用：\n\n| 类型 | 标签 | 判定规则 |\n|------|------|----------|\n| 计划 | Plan | toolName 包含 'plan' 或 'todo' |\n| 编辑 | Edit | toolName 包含 'edit' 或 'patch' |\n| 写入 | Write | toolName 包含 'write' 或 'create_file' |\n| 命令 | Run | toolName 包含 'bash' 或 'shell' |\n| 搜索 | Grep | toolName 包含 'grep' 或 'search' |\n\n资料来源：[useAgentThreads.ts:工具分类规则]()\n\n#### DiffStats 结构\n\n```typescript\ninterface DiffStats {\n added?: number;\n removed?: number;\n unchanged?: number;\n filesChanged?: number;\n}\n```\n\n资料来源：[useAgentThreads.ts:buildDiffStats()]()\n\n## 工具调用可视化\n\n### 消息元数据结构\n\n每个工具调用消息包含丰富的元数据：\n\n```typescript\ninterface ToolCallMeta {\n toolName?: string;\n filePath?: string;\n command?: string;\n commandDescription?: string;\n pattern?: string;\n searchPath?: string;\n isError?: boolean;\n files?: string[];\n planPhase?: string;\n todoCount?: number;\n output?: string;\n}\n```\n\n### 严重性级别\n\n| 级别 | 触发条件 | 显示样式 |\n|------|----------|----------|\n| success | 工具成功执行且 phase === 'result' | 绿色 |\n| error | is_error === true 或内容以 'Error:' 开头 | 红色 |\n| info | 工具执行中或普通信息 | 蓝色 |\n| warning | 子流超过最大迭代次数 | 黄色 |\n\n资料来源：[useAgentThreads.ts:severity 判断逻辑]()\n\n## 配置与扩展\n\n### 引擎配置优先级\n\n```\n命令行参数 > 环境变量 > 配置文件 > 默认值\n```\n\n### 可扩展性设计\n\n项目采用适配器模式支持新引擎：\n\n```typescript\n// 注册新引擎\nexport function registerEngine(engine: AgentEngine): void;\n\n// 创建引擎工厂\nexport function createEngine(type: EngineType, config: EngineConfig): AgentEngine;\n```\n\n## 最佳实践\n\n### 1. 引擎选择建议\n\n| 场景 | 推荐引擎 | 原因 |\n|------|----------|------|\n| 通用对话 | Claude | 对话能力强 |\n| 代码任务 | Codex | CLI 集成更紧密 |\n| 快速原型 | Claude | 配置简单 |\n\n### 2. 会话管理建议\n\n- 定期清理不活跃会话以节省存储\n- 使用 `displayText` 提供有意义的会话预览\n- 通过 `clientMeta` 标记特殊会话类型\n\n### 3. 错误处理\n\n```typescript\nconst isError =\n meta.is_error === true ||\n meta.isError === true ||\n (typeof msg.content === 'string' && msg.content.trimStart().startsWith('Error:'));\n```\n\n确保前端能正确处理和展示错误状态。\n\n## 总结\n\nAI Agent 集成模块通过统一的接口抽象和多引擎支持，为 mcp-chrome 提供了灵活且强大的 AI 能力。该架构设计遵循了开闭原则，便于后续添加新的 AI 引擎。前端组件 `useAgentChat` 和 `useAgentThreads` 提供了良好的用户交互体验，而服务层的 `ChatService` 和 `SessionService` 则确保了业务逻辑的清晰分离。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：hangwin/mcp-chrome\n\n摘要：发现 15 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint。\n\n## 1. 安装坑 · 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba76885913a744f0832665f5c62d0f1d | https://github.com/hangwin/mcp-chrome/issues/321 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ac5f778b292489482bfdb7953190f96 | https://github.com/hangwin/mcp-chrome/issues/319 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_559f34b86ade48e598dac510e9341b9e | https://github.com/hangwin/mcp-chrome/issues/339 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：mcp-chrome-bridge 无法使用\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：mcp-chrome-bridge 无法使用\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f19fb6526174af2abe5c1eab67e25ff | https://github.com/hangwin/mcp-chrome/issues/333 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b32536c95a7456788ba78e1fc705116 | https://github.com/hangwin/mcp-chrome/issues/342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | host_targets=mcp_host, claude\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:998796026 | https://github.com/hangwin/mcp-chrome | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：v0.0.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_035dffafcbe64f4ea112f20258430e71 | https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：issue\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：issue\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82ad93635a5e4ff5aeb2b35e36cbd02e | https://github.com/hangwin/mcp-chrome/issues/330 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 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:998796026 | https://github.com/hangwin/mcp-chrome | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | 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项目：hangwin/mcp-chrome\n\n摘要：发现 15 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint。\n\n## 1. 安装坑 · 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba76885913a744f0832665f5c62d0f1d | https://github.com/hangwin/mcp-chrome/issues/321 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ac5f778b292489482bfdb7953190f96 | https://github.com/hangwin/mcp-chrome/issues/319 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_559f34b86ade48e598dac510e9341b9e | https://github.com/hangwin/mcp-chrome/issues/339 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：mcp-chrome-bridge 无法使用\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：mcp-chrome-bridge 无法使用\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f19fb6526174af2abe5c1eab67e25ff | https://github.com/hangwin/mcp-chrome/issues/333 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Status indicator stuck on yellow - Service shows as \"not started\" after connection\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b32536c95a7456788ba78e1fc705116 | https://github.com/hangwin/mcp-chrome/issues/342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | host_targets=mcp_host, claude\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:998796026 | https://github.com/hangwin/mcp-chrome | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：v0.0.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_035dffafcbe64f4ea112f20258430e71 | https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：issue\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：issue\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82ad93635a5e4ff5aeb2b35e36cbd02e | https://github.com/hangwin/mcp-chrome/issues/330 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 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:998796026 | https://github.com/hangwin/mcp-chrome | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mcp-chrome - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-chrome 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想把一个主题变成可发布的内容方案，并判断标题、结构和转化路径。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. chrome-extension-structure：Chrome 扩展架构。围绕“Chrome 扩展架构”模拟一次用户任务，不展示安装或运行结果。\n5. native-server-architecture：本地服务器架构。围绕“本地服务器架构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. chrome-extension-structure\n输入：用户提供的“Chrome 扩展架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. native-server-architecture\n输入：用户提供的“本地服务器架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / chrome-extension-structure：Step 4 必须围绕“Chrome 扩展架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / native-server-architecture：Step 5 必须围绕“本地服务器架构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/hangwin/mcp-chrome\n- https://github.com/hangwin/mcp-chrome#readme\n- README.md\n- README_zh.md\n- app/chrome-extension/package.json\n- app/native-server/package.json\n- app/native-server/install.md\n- docs/ARCHITECTURE.md\n- docs/ARCHITECTURE_zh.md\n- app/chrome-extension/entrypoints/background/index.ts\n- app/native-server/src/index.ts\n- app/chrome-extension/entrypoints/content.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-chrome 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：hangwin/mcp-chrome\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g mcp-chrome-bridge\n```\n\n来源：https://github.com/hangwin/mcp-chrome#readme\n\n## 来源\n\n- repo: https://github.com/hangwin/mcp-chrome\n- docs: https://github.com/hangwin/mcp-chrome#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_a6d83c5a87334dad90fad29e067b04a9"
}