内容
# web-element-picker
> **AI 辅助前端开发的精准元素选择工具**
**版本**: 1.5.0 | **许可证**: MIT
---
## 🎯 快速开始
Element Picker 让你可以在浏览器中点击选择页面元素，AI 自动获取精准的源代码位置进行修改。
**核心流程**：
1. 浏览器中选择元素 → 生成唯一 ID（`mcp_elp:XXX` 格式）
2. 复制 ID（自动添加 `#` 前缀）→ `#mcp_elp:067842_a7k9m2`
3. AI 识别 ID → 自动调用 MCP 工具 → 获取源码位置 → 精准修改
**支持的 AI 工具**：Cursor、Cline、Claude Desktop、Roo Code 等所有支持 MCP 协议的工具
### 📖 完整文档
- **[用户使用手册](./docs/用户使用手册.md)** - 详细的使用指南
- **[开发维护手册](./docs/开发维护手册.md)** - 技术文档和维护指南
---
## ✨ 核心特性
- 🎯 **悬浮控制面板** - 浏览器右侧常驻，无需点击扩展图标
- 🔄 **连续多选** - 一次选择多个元素，批量提交
- 🆔 **AI 友好 ID** - 格式 `mcp_elp:XXX`，复制时自动添加 `#` 前缀
- 📦 **会话管理** - 组织相关元素为单一会话
- 📋 **完整功能** - 复制、查看、高亮、删除
- 🌐 **离线优先** - 完全离线可用，本地存储优先
- ⚡ **按需同步** - 用户操作时立即同步，无后台定时器
- 🎨 **精准对话** - 使用 `#mcp_elp:XXX` 精准指定元素
- 📦 **NPM 发布** - 支持 npx 一键集成，无需本地构建
- 💾 **原子性存储** - write-then-rename 确保数据完整性
- 🚀 **智能端口** - 自动查找可用端口（54721-54725）
- 🔄 **端口自愈** - 启动时自动清理孤儿进程，端口始终复用
- 🤝 **多 Agent 支持** - Cursor、Cline、Claude 可同时使用
- 🔄 **自动降级** - 权限问题时降级到内存模式
- ✅ **完整性验证** - 读取时自动验证数据结构
- 🔗 **跨工具共享** - Cline、Roo Code、Cursor 数据一致
---
## 💡 ID 格式说明
### 为什么是 `mcp_elp:XXX` 格式？
**设计考量**：
- `mcp_` - 明确标识为 MCP 工具相关
- `elp` - Element Picker 的缩写
- `:` - 分隔符，类似 CSS 选择器，提高可读性
- 示例：`mcp_elp:067842_a7k9m2`（21 字符）
**复制时自动添加 `#` 前缀**：
- 复制结果：`#mcp_elp:067842_a7k9m2`
- 让 AI 更容易识别这是一个 Element Picker 引用
- 符合常见引用模式（如 CSS `#id`、Markdown `#标题`）
- MCP 工具会自动移除 `#` 前缀进行查找
**健壮性保证**：
- 正则验证：`^mcp_elp:[0-9]{6}_[a-z0-9]{6}$`
- 自动清理：移除 `#`、去除空格
- 容错处理：支持 `#mcp_elp:XXX`、`##mcp_elp:XXX`、` #mcp_elp:XXX ` 等各种变体
---
## 📦 快速安装
### 方式 1：从 NPM 安装（推荐，发布后可用）
```bash
# 1. 安装浏览器扩展
npm install
npm run build:extension
# 2. 加载扩展到浏览器
# - 打开 chrome://extensions/
# - 启用"开发者模式"
# - 加载 packages/browser-extension/dist
# 3. 配置 MCP（无需本地构建）
```
**Cursor/Cline 配置**：
Windows 系统：
```json
{
"mcpServers": {
"web-element-picker-mcp": {
"command": "cmd",
"args": ["/c", "npx", "-y", "web-element-picker-mcp"]
}
}
}
```
macOS/Linux 系统：
```json
{
"mcpServers": {
"web-element-picker-mcp": {
"command": "npx",
"args": ["-y", "web-element-picker-mcp"]
}
}
}
```
✅ **优势**：无需配置路径，自动更新，跨平台兼容
### 方式 2：本地开发安装
```bash
# 1. 构建所有包
npm install
npm run build
# 2. 加载扩展（同上）
# 3. 配置 MCP（本地路径）
```
**配置文件**：`%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
```json
{
"mcpServers": {
"web-element-picker-mcp": {
"command": "node",
"args": ["C:\\完整路径\\packages\\mcp-server\\bin\\mcp-server.js"]
}
}
}
```
**完成！** 🎉
---
## 🚀 基础使用
1. 点击悬浮面板的"开始选择"按钮（或点击扩展图标）
2. 点击要修改的页面元素（可连续点击多个）
3. 点击"✅ 确认"保存选择
4. 点击 📋 复制元素 ID（自动复制为 `#mcp_elp:XXX` 格式）
5. 在 AI 对话中：`#mcp_elp:XXX 改成蓝色`
6. AI 自动识别并调用 MCP 工具，精准修改源代码 ✨
---
## 🏗️ 项目结构
```
web-element-picker/
├── packages/
│ ├── browser-extension/ # 浏览器扩展
│ └── mcp-server/ # MCP 服务器 (端口: 54721-54725)
├── scripts/ # 构建脚本
├── examples/ # 示例应用
├── docs/ # 文档目录
│ ├── 用户使用手册.md
│ └── 开发维护手册.md
└── README.md # 本文件
```
---
## 📊 性能
| 指标 | 数值 |
|------|------|
| 内存占用 | ~300 KB |
| CPU 使用 | <1% |
| 操作响应 | 即时 |
| 同步方式 | 按需同步（无延迟） |
| 端口查找 | 首次 <200ms，缓存命中 <10ms |
---
## 📝 更新日志
### v1.5.0 (2026-01-27)
**精准元素定位优化**：
- ✅ 重构 `highlightBySelection()` - 实现多级定位策略
- ✅ 新增四级定位优先级 - 内存缓存 → 唯一标识符 → CSS筛选 → XPath筛选
- ✅ 增强双重防护机制 - 内层筛选 + 外层验证
- ✅ 修复多个相同组件定位错误 - 通过位置和属性精准区分
- ✅ 完善数据一致性 - elementRegistry 与 DOM 元素完全同步
### v1.4.0 (2026-01-26)
**架构升级**：
- ✅ 新增 Background Script HTTP 代理 - 解决 CSP 限制
- ✅ 优化端口缓存 - 持久化存储，Service Worker 安全
- ✅ 增强请求去重和超时保护
### v1.3.0 (2026-01-24)
**Hash 路由支持**：
- ✅ 智能路由识别 - 同时支持 Hash 和 History 模式
- ✅ 精准元素定位增强 - pageContext、componentInstance、visualPosition
### v1.2.3 (2026-01-23)
**端口自愈功能**：
- ✅ 启动时自动检测并清理孤儿进程
- ✅ 端口隔离 PID 文件，支持多 Agent 同时使用
详细更新记录请查看 [CHANGELOG.md](./CHANGELOG.md)
---
## 🛠️ 端口管理
### 端口自愈功能（v1.2.3+）
**无需手动清理！** 🎉
从 v1.2.3 开始，MCP 服务器具备端口自愈能力：
- ✅ 启动时自动检测并清理孤儿进程
- ✅ 端口始终复用，不会递增
- ✅ 支持多个 AI 工具同时使用
**工作原理**：
1. 每个端口有独立的 PID 文件（`~/.element-picker/port-54721.pid`）
2. 启动时检查 PID 文件，如果进程已死则自动清理
3. 多个 Agent 各占一个端口，互不干扰
### 手动清理（仅在特殊情况下需要）
如果遇到极端情况需要手动清理，可使用：
```bash
# 跨平台方式
npm run cleanup-ports
# Windows PowerShell
powershell -ExecutionPolicy Bypass -File .\scripts\cleanup-ports.ps1
# macOS/Linux
./scripts/cleanup-ports.sh
```
---
## 🤝 贡献
欢迎贡献！请查看 [开发维护手册](./docs/开发维护手册.md) 了解如何开始。
---
## 🔧 技术栈
- **浏览器扩展**: TypeScript + Webpack + Chrome Extension API
- **MCP 服务器**: Node.js + Express + MCP SDK
- **端口**: 54721-54725 (自动端口发现)
- **框架检测**: React Fiber、Vue 2/3、Angular
### 系统要求
- **Node.js**: >= 16.0.0
- **npm**: >= 7.0.0
- **浏览器**: Chrome/Edge 88+ (支持 Manifest V3)
- **操作系统**: Windows/macOS/Linux
> **注意**: 虽然支持 Node 16+，但推荐使用 Node 18 LTS 或 Node 20 LTS 以获得更好的性能和长期支持。
---
## 📄 License
MIT License - 详见 [LICENSE](LICENSE) 文件
---
## 🙏 致谢
感谢所有贡献者和使用者！
---
**开始使用 Element Picker，享受 AI 辅助开发的乐趣！** 🚀
