在使用 deepseek harness 辅助开发的过程中我经常遇到一个很尴尬的场景报错弹窗一闪而过设计稿里的提示文字无法直接复制远程会议里白板上的内容需要手动誊写。虽然可以把截图保存下来再让模型分析但来回切换窗口、保存文件、拖拽上传效率非常低。如果能有一个插件直接截取屏幕内容并交给 DeepSeek 处理整个流程会顺很多。这篇文章就围绕这个需求整理一套给 deepseek harness 编写识屏插件的完整方案。这套方案的核心思路并不复杂截图、OCR 识别、文本整理、调用 DeepSeek API、返回分析结果。难的是把每个环节串成一条稳定可用的链路并且在接回 harness 的时候不产生额外负担。我会从概念讲起逐步拆解架构再给出完整可运行的代码最后整理开发过程中容易遇到的坑。适合有 Python 基础、正在使用或计划接入 DeepSeek 的开发者也适合想给本地 AI 工具扩展能力的同学。1. deepseek harness 与识屏插件的背景1.1 什么是 deepseek harness要理解 deepseek harness得先拆成两个词来看。DeepSeek 是开源大模型和 API 服务的品牌harness 在 AI 工程领域通常指“对模型能力的封装、调度和编排层”。也就是说deepseek harness 并不是一个单一的官方产品而是社区中一类用于把 DeepSeek 模型接入本地开发环境、命令行工具或 IDE 的工作流框架。它解决的问题很实际直接调用 API 时开发者需要自己处理请求构造、上下文管理、多轮对话、工具调用和输出解析。而 harness 把这些能力做成一套可复用的本地服务让用户可以像使用一个“AI 工具链”一样在编码、调试、日常自动化任务中随时调用模型。harness 与 agent 的区别也值得提一下。agent 通常强调自主决策模型自己决定下一步调用什么工具而 harness 更偏重对模型能力的封装和编排用户拥有更明确的控制权。识屏插件本质上就是在给 harness 增加一种新的感知工具让它从“只能读文本”变成“能看懂屏幕”。1.2 为什么需要识屏插件很多开发信息并不在代码里而是存在于屏幕上。例如程序运行时弹出的异常对话框无法直接选中复制。设计图或原型中的 UI 文案需要人工转述给模型。PPT、PDF 中的图表内容想快速提取关键信息。线上会议中共享的屏幕、白板来不及边看边记。某个软件界面上的按钮文字、状态信息需要快速了解。手动处理这些场景的方式是截图保存再打开网页端或本地工具上传图片。这种方式不仅步骤多而且无法接入自动化的开发流程。识屏插件能够把“看到屏幕”这个过程变成一条命令行指令让模型直接分析当前可见内容。1.3 识屏插件可以应用在哪些场景我把识屏插件的常见应用场景整理成了表格应用场景输入内容期望输出报错信息分析异常弹窗、命令行报错截图错误原因、修复建议设计稿辅助开发UI 设计图、原型截图页面结构描述、HTML/CSS 建议文档内容提取PPT、PDF 页面截图关键信息摘要、结构化文本远程会议记录共享屏幕、白板画面会议要点、待办事项界面操作提示软件界面截图功能说明、操作步骤这些场景的共同点是信息以图像形式存在但最终需要模型以文本形式理解和回答。识屏插件相当于给 harness 装了一双眼睛。2. 环境准备与插件架构设计2.1 环境要求在动手写代码之前先把运行环境准备好。本文示例以 Python 为主因为我希望插件本身逻辑清晰、跨平台同时可以独立运行不依赖特定的 harness 版本。环境要求如下操作系统Windows 10/11、macOS 或主流 Linux 发行版。Python 版本建议 3.9 或更高。截图库Pillow或 mss支持多显示器。OCR 库pytesseract Tesseract或 PaddleOCR。HTTP 客户端requests或 openai 官方 SDK。DeepSeek API Key到 DeepSeek 开放平台创建。需要说明的是版本号迭代比较快本文不刻意锁定具体版本。你在运行时如果遇到依赖兼容问题可以按实际环境调整版本重点还是理解配置思路和代码结构。2.2 插件整体架构识屏插件的整体架构可以分为五个模块屏幕采集模块 - OCR 识别模块 - 文本整理模块 - DeepSeek 调用模块 - 结果输出模块屏幕采集模块负责截取全屏或指定区域输出图片OCR 识别模块从图片中提取文字文本整理模块对识别结果做清洗去掉乱码和重复内容DeepSeek 调用模块负责组装 prompt 并请求模型结果输出模块把模型回答打印到终端、写入文件或者传递回 harness 的上层流程。这种分层设计的优点在于解耦。后续如果想把 OCR 换成更强大的模型或者把 DeepSeek 换成其他兼容 OpenAI 接口的大模型只需要修改对应模块整体流程不用变。2.3 工作流程设计实际运行流程如下用户触发插件比如执行命令、按快捷键或收到 harness 的调用请求。插件调用截图模块获取当前屏幕图像。OCR 模块对图像进行文字识别返回原始文本。文本整理模块过滤空白字符、合并短行形成干净的上下文。prompt 模板将识别文本和用户任务包装成模型输入。插件调用 DeepSeek API获取分析结果。结果输出到终端或返回给上层调用方。这个流程的关键点有三个截图质量、OCR 准确率、prompt 质量。后面会逐个展开。3. 核心技术拆解3.1 屏幕截图Pillow 与 mss屏幕截图是识屏插件的第一步。Python 中最简单的方案是使用 Pillow 的ImageGrabfrom PIL import ImageGrab # 截取全屏 image ImageGrab.grab() image.save(screenshot.png)ImageGrab.grab()在 Windows 和 macOS 上表现比较好。如果你需要截取多个显示器Windows 上可以传入all_screensTrueimage ImageGrab.grab(all_screensTrue)在 Linux 上ImageGrab依赖 X11 或 Wayland 的截图能力兼容性不一定理想。如果你需要稳定的多屏截图或者希望减少截图耗时mss 是更专业的方案import mss with mss.mss() as sct: # monitor 1 通常表示主屏幕所有屏幕可以用 sct.monitors screenshot sct.grab(sct.monitors[1]) output mss.tools.to_png(screenshot.rgb, screenshot.size, outputscreenshot.png)mss 的好处是速度快、支持按显示器编号精确截取。在插件的后续版本中你还可以通过参数指定截图区域减少识别无关内容。3.2 OCR 识别Tesseract 与 PaddleOCROCR 决定了插件能读懂多少屏幕内容。轻量方案是 Tesseract它是开源 OCR 引擎配合 Python 的 pytesseract 使用import pytesseract from PIL import Image text pytesseract.image_to_string(Image.open(screenshot.png), langchi_simeng) print(text)使用 Tesseract 前需要先安装 Tesseract 二进制文件。Windows 用户还需要设置路径pytesseract.pytesseract.tesseract_cmd rC:\Program Files\Tesseract-OCR\tesseract.exe中文识别需要额外安装对应的语言包Ubuntu 上通常叫tesseract-ocr-chi-sim。如果你更注重中文识别准确率可以考虑 PaddleOCR。PaddleOCR 对复杂排版、倾斜文字和中文场景支持更好但依赖体积较大模型初始化时间也更长。它的调用方式在不同版本中变化较大下面是一个较常见的使用思路from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue, langch, show_logFalse) result ocr.ocr(screenshot.png) for line in result: for word_info in line: print(word_info[1][0])我的建议是开发阶段先用 Tesseract 跑通流程后续识别率成为瓶颈时再切换到 PaddleOCR或者直接使用多模态大模型进行图片理解。3.3 DeepSeek API 调用DeepSeek API 兼容 OpenAI 的接口协议所以我们可以用 requests 直接调用也可以用 openai 官方 SDK。这里先给出基于 requests 的通用方式import requests API_KEY your-api-key URL https://api.deepseek.com/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { model: deepseek-chat, messages: [ {role: user, content: 请总结这段文字} ], temperature: 0.3 } response requests.post(URL, headersheaders, jsonpayload) data response.json() print(data[choices][0][message][content])注意deepseek-chat是 DeepSeek 的对话模型代号实际模型映射关系以 DeepSeek 开放平台文档为准。请求中常用的参数包括temperature、max_tokens和stream。对于识屏分析任务我建议把temperature控制在 0.3 左右减少模型自由发挥。如果你希望避免非 2xx 状态码引起的程序崩溃可以加上异常处理if response.status_code ! 200: print(API Error:, response.status_code, response.text) else: data response.json() print(data[choices][0][message][content])3.4 Prompt 设计Prompt 是识屏插件中最容易被忽视、却又影响最大的部分。OCR 得到的文本往往是零散的模型需要理解“这是一段屏幕识别结果”而不是一段用户随意输入的话。因此我使用一个固定的模板你是一名屏幕内容分析助手。下面是一段通过 OCR 从屏幕截图中识别出的文本可能包含弹窗、代码、日志、界面文字等。 请根据用户需求进行分析。 【屏幕文本开始】 {ocr_text} 【屏幕文本结束】 用户需求{user_question} 请直接回答不要提及 OCR 识别过程。模板里明确告诉模型这是 OCR 文本可能有乱码或识别错误同时要求模型不要解释识别过程直接回答问题。这样可以减少模型对识别噪声的纠结让输出更聚焦。4. 完整实战实现一个 harness 识屏插件4.1 创建项目结构先建立项目目录deepseek-screen-plugin/ ├── config.json ├── requirements.txt ├── main.py ├── modules/ │ ├── __init__.py │ ├── screen.py │ ├── ocr.py │ └── deepseek_client.pymain.py是入口modules存放三个功能模块config.json保存插件配置。4.2 初始化依赖在requirements.txt中写入pillow mss pytesseract requests然后在项目目录执行安装命令pip install -r requirements.txt如果你在 Windows 上使用 Tesseract还需要单独安装 Tesseract OCR 程序并确认 pytesseract 能找到可执行文件路径。4.3 配置文件config.json用来集中管理 API Key、模型名称、OCR 语言等参数{ api_key: sk-xxxxxxxxxxxxxxxx, base_url: https://api.deepseek.com/chat/completions, model: deepseek-chat, temperature: 0.3, ocr_lang: chi_simeng, screenshot_monitor: 1 }注意api_key不要提交到公共仓库。在真实项目中更推荐从环境变量读取后面章节我会专门讲。4.4 屏幕截图模块modules/screen.py负责截图。这里我同时支持 Pillow 和 mss 两种方式并通过配置文件里的参数选择。import json import os from PIL import ImageGrab def load_config(): config_path os.path.join(os.path.dirname(__file__), .., config.json) with open(config_path, r, encodingutf-8) as f: return json.load(f) def take_screenshot(output_pathscreenshot.png): config load_config() monitor config.get(screenshot_monitor, 1) try: if monitor all: image ImageGrab.grab(all_screensTrue) else: image ImageGrab.grab() image.save(output_path) return output_path except Exception as e: print(f截图失败: {e}) return None这段代码先用load_config读取配置然后调用ImageGrab.grab截图保存为 PNG 图片。单显示器环境下直接截全屏多显示器时可把screenshot_monitor设置为all。4.5 OCR 识别模块modules/ocr.py负责把图片转成文字。核心代码是调用 pytesseract并加入简单的异常处理。import pytesseract from PIL import Image def extract_text(image_path, langchi_simeng): try: image Image.open(image_path) text pytesseract.image_to_string(image, langlang) return clean_text(text) except pytesseract.TesseractNotFoundError: print(未找到 Tesseract请先安装并配置路径) return except Exception as e: print(fOCR 识别失败: {e}) return def clean_text(raw_text): lines [line.strip() for line in raw_text.splitlines()] lines [line for line in lines if line] return \n.join(lines)clean_text的作用是去掉首尾空白和空行。你会注意到这里没有做太复杂的清洗因为模型本身对轻微噪声有一定容忍度过度清洗反而可能丢失信息。4.6 DeepSeek 调用模块modules/deepseek_client.py负责请求 DeepSeek API并返回模型回答。import requests def analyze_text(ocr_text, user_question请分析这段屏幕内容, configNone): if config is None: config {} api_key config.get(api_key, ) base_url config.get(base_url, https://api.deepseek.com/chat/completions) model config.get(model, deepseek-chat) temperature config.get(temperature, 0.3) headers { Authorization: fBearer {api_key}, Content-Type: application/json } prompt f 你是一名屏幕内容分析助手。下面是一段通过 OCR 从屏幕截图中识别出的文本可能包含弹窗、代码、日志、界面文字等。 请根据用户需求进行分析。 【屏幕文本开始】 {ocr_text} 【屏幕文本结束】 用户需求{user_question} 请直接回答不要提及 OCR 识别过程。 payload { model: model, messages: [ {role: user, content: prompt} ], temperature: temperature } try: response requests.post(base_url, headersheaders, jsonpayload, timeout60) if response.status_code 200: data response.json() return data[choices][0][message][content] else: return fAPI 请求失败: {response.status_code} {response.text} except requests.exceptions.Timeout: return API 请求超时请稍后重试 except Exception as e: return f请求异常: {e}这段代码重点处理了三种情况成功返回内容、HTTP 错误、网络超时。调用超时设为 60 秒避免插件长时间卡住。4.7 主程序main.py把三个模块串起来同时支持命令行参数。用户既可以只截图也可以截图后直接分析。import argparse import os from modules.screen import take_screenshot, load_config from modules.ocr import extract_text from modules.deepseek_client import analyze_text def main(): parser argparse.ArgumentParser(descriptiondeepseek harness 识屏插件) parser.add_argument(--screenshot, actionstore_true, help截取当前屏幕) parser.add_argument(--image, typestr, help指定图片文件路径) parser.add_argument(--question, typestr, default请分析这段屏幕内容, help用户需求) parser.add_argument(--output, typestr, defaultscreenshot.png, help截图保存路径) args parser.parse_args() config load_config() image_path args.image if not image_path and args.screenshot: image_path take_screenshot(args.output) if not image_path: print(未获取到有效图片) return if os.path.exists(image_path): print(正在识别屏幕文字...) ocr_text extract_text(image_path, langconfig.get(ocr_lang, chi_simeng)) if not ocr_text: print(未识别到文字可能屏幕内容不是文本或 OCR 失败) return print(OCR 识别结果:) print(ocr_text) print(\n正在调用 DeepSeek 分析...) result analyze_text(ocr_text, args.question, config) print(\n分析结果:) print(result) else: print(f图片不存在: {image_path}) if __name__ __main__: main()--screenshot表示截当前屏幕--image可以直接分析已有图片--question让用户指定分析需求。这个入口设计比较简洁后续可以继续扩展。4.8 运行与验证在项目目录下执行python main.py --screenshot --question 请总结这段报错信息如果一切正常你会先看到 OCR 识别出的原始文字再看到 DeepSeek 的分析结果。第一次运行可能因为 OCR 语言包加载稍慢这是正常现象。如果你希望把输出接入 harness可以考虑在 harness 的自定义命令配置中注册这个脚本。以常见的 JSON 配置型 harness 为例思路如下{ name: screen-analyze, command: python /path/to/deepseek-screen-plugin/main.py --screenshot --question \分析当前屏幕内容\, description: 截屏并调用 DeepSeek 分析屏幕内容 }需要注意不同版本的 harness 配置项并不统一这里的格式只是示意。你应该优先查看自己使用的 harness 文档找到插件或自定义命令的注册方式。总体原则是让 harness 可以通过一条命令调用我们的脚本再把输出回传给模型作为上下文。5. 常见问题与排查思路在开发和使用识屏插件时容易遇到下面这些问题问题现象常见原因解决思路截图黑屏或空白系统权限不足、多屏参数错误检查屏幕录制/截图权限调整screenshot_monitorOCR 中文乱码缺少中文语言包安装tesseract-ocr-chi-sim确认lang参数API 返回 401API Key 错误或未配置检查config.json和环境变量中的 Key请求超时网络不稳定或响应过长设置更长 timeout检查网络连接模型回答与屏幕内容无关prompt 中 OCR 文本被截断增加文本长度限制检查识别结果是否完整接入 harness 后无法调用路径配置错误或环境不一致用绝对路径测试命令确认 Python 环境一致接下来展开几个高频问题。5.1 截图黑屏或权限问题Windows 下通常不存在太大权限问题但 macOS 需要给终端或 Python 进程授予“屏幕录制”权限。Linux 下如果使用精简桌面环境可能需要安装gnome-screenshot或其他截图后端。建议先手动用系统截图工具确认屏幕内容可见再排查插件代码。5.2 OCR 识别率不高怎么办OCR 识别率受图像分辨率、字体大小、背景干扰影响很大。你可以在 OCR 前对图片做灰度化和放大处理例如用 Pillow 把截图转为灰度再将尺寸扩大两倍。屏幕截图本身分辨率较高Tesseract 的默认参数不一定是最优选择。建议先测试几组不同分辨率下的效果找到最适合自己屏幕的设置。5.3 DeepSeek 思考模式相关报错有用户在通过本地服务接入 DeepSeek 时遇到过类似错误upstream_status: http 400 cause: the reasoning_content in the thinking mode must be passed back to the api.这个报错的核心是“思考模式/推理模式”下的多轮请求参数问题。DeepSeek 的某些模型在返回思考过程时会把reasoning_content字段一并返回继续下一次请求时客户端需要按规定把该字段传回给 API否则会返回 400。如果你的本地 harness 或插件代理层遇到这个报错建议检查三点一是确认当前使用的模型是否属于思考模式二是查看上一轮响应中是否包含reasoning_content三是在构造下一轮请求时是否把该字段放入了正确的消息里。如果你不需要思考过程也可以在配置中选择关闭对应的思考模式避免这个字段带来的传参问题。5.4 harness 安装或 Web 面板卡住在部分 harness 版本中启动 Web 面板使用的是pnpm dsh web。这个命令在首次安装依赖时可能因为网络、缓存或 pnpm 版本问题卡住。可以尝试先升级 pnpm清理缓存或者使用国内 npm 镜像源。不过要注意Web 面板和识屏插件并不是强绑定关系插件作为独立脚本也可以直接使用。6. 最佳实践与工程建议6.1 不要把 API Key 写死在代码里我在示例中把 API Key 放进了config.json但这只是便于演示。真实项目中应该通过环境变量读取例如在deepseek_client.py中优先读取环境变量import os api_key os.getenv(DEEPSEEK_API_KEY, config.get(api_key, ))同时在.gitignore中忽略config.json或使用.env文件管理敏感配置。这样即使代码仓库被分享也不会泄露密钥。6.2 注意屏幕隐私与合规屏幕截图可能会包含账号信息、内部文档、客户数据等敏感内容。因为识屏插件会把截图转成文本并发送到远端 API所以要格外谨慎。建议只截取当前活动窗口或指定区域不要在开启插件时长时间运行“循环截图”模式。如果企业内部有数据合规要求需要先确认 DeepSeek API 的使用范围是否合规。6.3 设计稳定的输出格式当插件要接入 harness 时输出格式不能随意。建议让main.py支持一个--json参数将结果输出为 JSON{ ocr_text: 识别出的原始文本, answer: DeepSeek 分析结果 }这样上层 harness 可以直接解析字段而不是用正则去匹配终端文本。稳定输出格式是工程化扩展的重要基础。6.4 增加缓存和重试机制屏幕上的内容经常不变例如某个固定的代码窗口。如果每次截图都调用 API既浪费 token又增加等待时间。可以考虑对 OCR 文本计算哈希值在一定时间内缓存分析结果。API 请求失败时可以设置指数退避重试避免连续快速失败。6.5 日志与可观测性在插件加入日志输出记录截图耗时、OCR 耗时、API 请求耗时和 token 消耗。这样不仅方便排查问题也能帮你评估插件是不是值得继续优化。一个简单的日志格式如下[2024-01-01 10:00:00] screenshot 300ms, ocr 1200ms, api 3500ms, tokens 800积累一定数据后你会更清楚瓶颈在哪个环节。7. 总结与学习路线这篇文章从 deepseek harness 的背景讲起介绍了识屏插件的架构、核心技术、完整代码实现以及常见问题。通过这套方案你可以让本地模型工具读取屏幕上的文本并把分析结果接回自动化流程。核心知识点包括使用 Pillow 或 mss 截图使用 Tesseract 或 PaddleOCR 做文字识别使用 requests 调用 DeepSeek API以及通过 prompt 模板串联起 OCR 文本和用户需求。接下来你可以继续往几个方向深入一是把插件改成指定区域截图减少干扰信息二是用多模态模型直接识别图片绕开 OCR 的精度瓶颈三是研究 DeepSeek 的流式输出让分析结果实时显示四是把插件接入更完整的 harness 工具链例如让模型根据屏幕内容自动执行下一步操作。识屏插件只是开始背后更大的主题是“让 AI 真正看到开发者正在看的东西”。如果你也在使用 deepseek harness或者正在折腾类似的本地 AI 工具可以把这篇文章当作一份基础参考。先跑通最简单的截图分析流程再逐步扩展你会慢慢体会到工具链被自己掌握的感觉。