内容
[English](README.md) · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md)
---
# UIPin
[](https://github.com/sixtdreanight/UIPin/actions/workflows/ci.yml)
[](LICENSE)
**通用UI标注与反馈工具。** 截图 → 用图钉、箭头、矩形和自由绘制标注 → 通过MCP协议导出给AI。
## 为什么使用UIPin？
传统的UI反馈流程存在问题：截图通过聊天发送、模糊的评论、无尽的反复沟通。UIPin用**AI可以直接消费和处理的视觉标注**取代了这一流程。
## 功能
- **3种捕获模式** — 全屏（`Ctrl+Shift+P`）、区域（`Ctrl+Shift+R`）、窗口（`Ctrl+Shift+W`）
- **4种标注工具** — 图钉、箭头、矩形、自由绘制
- **撤销/重做** — 50步历史记录
- **缩放和平移** — 滚动缩放、Shift+拖动平移
- **MCP服务器** — AI工具（Claude Code、Cursor、Windsurf）可以通过JSON-RPC + SSE实时读取标注
- **导出** — Markdown（带有颜色分析 + 裁剪区域）、JSON、带标注的PNG
- **UIA集成** — 自动检测Windows UI元素名称、类型、类和祖先树
- **国际化** — 简体中文、繁體中文、 日本語
- **系统托盘** — 始终可用、不会遮挡
- **自动更新** — 通过GitHub Releases保持最新
## 快速开始
### 下载
从 [Releases](https://github.com/sixtdreanight/UIPin/releases) 下载最新安装包。
| 平台 | 软件包 |
|----------|---------|
| Windows | `.exe`（NSIS安装程序） |
| macOS | `.dmg` |
| Linux | `.AppImage` |
### 从源码构建
```bash
git clone https://github.com/sixtdreanight/UIPin.git
cd UIPin
npm install
npm run dev # 以开发模式启动
npm run build # 生产环境构建
npm run dist # 打包安装程序
```
**要求：** Node.js ≥ 20, npm ≥ 10
## 使用
### 快捷键
| 全局快捷键 | 操作 |
|----------------|--------|
| `Ctrl+Shift+P` | 捕获全屏 |
| `Ctrl+Shift+R` | 捕获区域 |
| `Ctrl+Shift+W` | 捕获窗口 |
| `Ctrl+Z` / `Ctrl+Shift+Z` | 撤销 / 重做 |
| 应用内快捷键 | 操作 |
|----------------|--------|
| `P` / `A` / `R` / `F` | 切换工具：图钉 / 箭头 / 矩形 / 自由绘制 |
| `Esc` | 取消所有选择 |
| 滚动 | 缩放 |
| Shift + 拖动 | 平移 |
### 工具
- **图钉** — 放置编号标记。点击添加评论。拖动重新定位。
- **箭头** — 从一点绘制到另一点。
- **矩形** — 绘制虚线矩形以突出区域。
- **自由绘制** — 自由绘制自定义突出显示。
### 导出格式
- **复制（Markdown）** — 完整的错误报告，包含坐标、颜色分析、裁剪区域截图和UIA元素树。直接粘贴到AI聊天中。
- **截图（PNG）** — 带有所有标记的注释截图。
- **JSON** — 用于程序化消费的结构化数据。
## MCP协议
UIPin在 `http://127.0.0.1:3846` 上运行本地MCP兼容的JSON-RPC服务器。
### 工具
| 工具 | 描述 |
|------|-------------|
| `list_annotations` | 列出所有活动注释图钉和绘图 |
| `get_screenshot` | 获取当前截图元数据 |
| `resolve_annotation` | 将注释标记为已解决（从列表中删除） |
| `get_context` | 获取AI消费的结构化Markdown上下文 |
### 快速测试
```bash
# 列出可用工具
curl -s http://127.0.0.1:3846/mcp \
-H "Content-Type: application/json" \
-d '{"method":"tools/list","id":1}'
# 获取当前注释
curl -s http://127.0.0.1:3846/mcp \
-H "Content-Type: application/json" \
-d '{"method":"tools/call","id":2,"params":{"name":"list_annotations"}}'
```
### SSE（服务器发送事件）
在 `http://127.0.0.1:3846/sse` 处订阅实时会话更新。
## 架构
```
UIPin/
├── electron/ # Electron主进程
│ ├── main.ts # 窗口、IPC、快捷键、托盘
│ ├── preload.ts # 上下文桥API
│ ├── uia.ts # Windows UIAutomation（PowerShell）
│ ├── updater.ts # 通过electron-updater自动更新
│ ├── logger.ts # 结构化日志记录
│ ├── mcp/ # MCP协议服务器（模块化）
│ │ ├── http-server.ts # HTTP启动、路由、CORS
│ │ ├── handlers.ts # 工具实现
│ │ ├── sse.ts # SSE连接管理
│ │ └── types.ts # 共享类型
│ └── mcp-server.ts # 重新导出门面
├── src/ # React渲染器
│ ├── components/ # UI组件
│ ├── hooks/ # 自定义React钩子
│ ├── lib/ # 纯实用模块
│ ├── i18n/ # 国际化
│ ├── context/ # React上下文 + 减压器
│ └── types/ # TypeScript类型定义
├── resources/ # 图标和图像
└── .github/workflows/ # CI/CD流水线
```
## 开发
```bash
# 安装依赖
npm install
# 启动开发模式
npm run dev
# 类型检查
npm run typecheck
# lint
npm run lint
# 运行测试
npm test
npm run test:watch
npm run test:e2e
# 构建生产环境
npm run build
# 打包分发
npm run dist
```
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
- [简体中文](README.zh-CN.md)
- [繁體中文](README.zh-TW.md)
- [日本語](README.ja.md)
