AI导哈

截图整理工具

基于AI的截图整理工具，支持OCR文本提取和图像分析，自动分类截图并提供自然语言交互界面。

  • by rfergu
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 rfergu/Screenshot_Agent_MCP

使用说明

屏幕截图管理器

AI驱动的截图组织，展示了使用Microsoft agent Framework进行生产AI代理开发。

特性

  • 🔍 智能分析：使用Tesseract OCR进行快速文本提取，GPT-4o Vision进行图像分析
  • 📁 自动组织：将屏幕截图分为代码、错误、文档、设计、通信、表情包或其他
  • 💬 自然语言接口：与GPT-4聊天，以对话方式组织您的屏幕截图
  • ⚡ 快速处理：OCR在<50ms内处理大多数屏幕截图，在<2s内处理视觉模型
  • 🎯 双模式操作:
    • 远程（生产）：具有可靠工具支持的完整AI代理功能
    • 本地（测试）：无需API成本即可快速测试会话流
  • 📊 批处理：一次组织整个截图文件夹
  • 🗂️ 安全文件处理：冲突解决、可选归档和安全文件名生成

快速开始

先决条件

对于远程模式（生产-推荐）：

  • Python 3.11+
  • Azure OpenAI或AI Foundry凭据(获取凭据)
  • Tesseract OCR已安装

对于本地模式（仅测试/调试）：

  • Python 3.11+
  • Azure AI Foundry命令行界面(安装指南)
  • Phi-4迷你版（约2GB下载）

安装

步骤1：核心设置（必填）

# Clone the repository
git clone <repository-url>
cd screenshot-organizer

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

步骤2：安装Tesseract OCR

macOS：

brew install tesseract

Ubuntu/Debian：

sudo apt-get install tesseract-ocr

窗户： 下载地址：https://github.com/UB-Mannheim/tesseract/wiki

步骤3：选择您的模式

选项A：远程模式设置（建议用于生产）

  1. 从获取Azure凭据https://ai.azure.com或Azure门户

  2. 设置环境变量：

export AZURE_AI_CHAT_ENDPOINT=https://your-project.services.ai.azure.com/api/projects/your-project
export AZURE_AI_MODEL_DEPLOYMENT=gpt-4o
export AZURE_AI_CHAT_KEY=your_api_key

支持的端点：

  • AI铸造厂： https://xxx.services.ai.azure.com/api/projects/xxx
  • Azure OpenAI： https://xxx.cognitiveservices.azure.com
  1. 运行：
python -m src.cli_interface  # Remote is default

选项B：本地模式设置（仅测试/调试）

  1. 安装Azure AI Foundry命令行界面：

macOS：

brew install azure/ai-foundry/foundry
foundry --version  # Verify installation

Linux/Windows： 请参阅：https://learn.microsoft.com/azure/ai-foundry/cli/

  1. 下载并设置Phi-4-mini：
# Download model (first time, ~2GB)
foundry model get phi-4-mini

# Start Foundry service
foundry service start

# Load the model
foundry model load phi-4-mini

# Verify it's running
foundry service status
# Should show: Service is running on http://127.0.0.1:<port>
  1. 运行（保持Foundry服务在单独的终端中运行）：
python -m src.cli_interface --local

注： 本地模式仅用于测试对话流，没有屏幕截图分析或文件组织功能。

基本用法

交互式聊天（远程模式）

python -m src.cli_interface  # Starts immediately in remote mode

对话示例：

Assistant: Hi! I'm a Screenshot Organizer agent built with Microsoft Agent Framework.
           I can help you organize chaotic screenshot folders...
           Where do you typically save your screenshots?

You: /Users/me/Desktop/screenshots
Assistant: Perfect! Let me analyze the screenshots in that folder...

配置

配置通过以下方式管理 config/default_config.yaml:

processing:
  ocr_min_words: 10  # Minimum words for OCR to be considered sufficient
  vision_timeout: 30
  batch_size: 50

organization:
  base_folder: "~/Screenshots/organized"
  categories:
    - code
    - errors
    - documentation
    - design
    - communication
    - memes
    - other
  keep_originals: true  # Keep copies in _originals folder

models:
  vision:
    max_tokens: 200
    temperature: 0.3

api:
  openai_model: "gpt-4-turbo-preview"
  max_context_length: 8000

logging:
  level: INFO
  file: screenshot_organizer.log

使用环境变量覆盖设置：

export OPENAI_API_KEY=your_key
export MCP_SERVER_PORT=3000
export LOG_LEVEL=DEBUG

建筑

该项目展示了 带有MCP客户端集成的Microsoft代理框架.

统一架构

Agent Framework (Brain 🧠)
    ↓ contains
MCP Client Wrapper (EMBEDDED)
    ↓ calls via stdio
MCP Server (Hands 🤲)
    ↓ operates on
File System

关键原则： 代理框架有一个嵌入式MCP客户端，它连接到MCP服务器进行所有文件操作。

运作原理

  1. 代理框架（编排器）:

    • 使用GPT-4进行智能决策
    • 理解用户意图
    • 决定分类和命名
    • 协调工具调用

  2. MCP客户端（嵌入式协议桥）:

    • 嵌入代理框架
    • 管理MCP服务器子流程
    • 提供工具包装
    • 处理stdio通信

  3. MCP服务器（工具提供程序）:

    • 作为单独的子进程运行
    • 公开低级文件操作工具
    • 返回事实（而非决定）
    • 调解所有文件系统访问

  4. 加工组件:

    • 光学字符识别：使用Tesseract快速提取文本（~50ms）
    • 视觉：Azure GPT-4o图像理解愿景（~2s）
    • 关键字分类器：回退模式匹配

所有文件系统操作都通过MCP协议 -展示了Agent框架功能和MCP标准化。

有关详细的体系结构文档，请参阅 建筑.md.

发展

运行测试

# Run all tests
pytest -v

# Run specific test suite
pytest tests/test_ocr_processor.py -v

# Run integration tests
pytest tests/test_integration.py -v

# Run performance tests
pytest tests/test_performance.py -v -m performance

项目结构

screenshot-organizer/
├── src/
│   ├── processors/          # OCR and Vision processors
│   ├── classifiers/         # Keyword classification
│   ├── organizers/          # File organization logic
│   ├── utils/               # Config and logging utilities
│   ├── mcp_tools.py         # MCP tool handlers
│   ├── screenshot_mcp_server.py  # MCP server
│   ├── chat_client.py       # GPT-4 chat client
│   ├── cli_interface.py     # Interactive CLI
│   └── session_manager.py   # Session persistence
├── config/
│   └── default_config.yaml
├── tests/
│   ├── test_*.py           # Unit tests
│   ├── test_integration.py # Integration tests
│   └── test_performance.py # Performance tests
├── .env.example
├── requirements.txt
└── README.md

CLI命令

使用交互式聊天界面时：

  • /help -显示帮助消息
  • /clear -清除对话历史记录
  • /stats -显示组织统计信息
  • /quit 或 /exit -退出程序

支持的类别

  • 代码：源代码、编程截图
  • 错误：错误消息、堆栈跟踪、异常
  • 文档：指南、教程、API文档、自述文件
  • 设计：UI模型、线框、设计系统、Figma
  • 沟通：Slack、Discord、电子邮件、聊天消息
  • 梗：有趣的图片、笑话
  • 其他：任何不符合上述类别的东西

绩效目标

  • OCR处理：每张截图<50ms
  • 视觉处理：每张截图<2s
  • 批量吞吐量：>10个文件/秒（带OCR）

故障排除

未找到Tesseract

Error: Tesseract not found

解决方案：安装Tesseract OCR（请参阅安装部分）

OpenAI API错误

Error: OpenAI API key not provided

解决方案：设置OPENAI_API_KEY环境变量或使用 --api-key 旗帜

组织文件时权限被拒绝

解决方案：确保基本组织文件夹可写：

chmod 755 ~/Screenshots/organized

许可证

[在此处添加您的许可证]

贡献

欢迎投稿！请阅读CONTRIBUTING.md了解指南。

致谢

  • Tesseract OCR用于快速文本提取
  • 用于本地测试功能的Microsoft Phi-4-mini
  • Azure OpenAI GPT-4o用于生产AI代理编排和视觉分析
  • 用于统一工具集成的Microsoft代理框架

相关 MCP