企业官网建设流程全解析

给 DeepSeek Harness 写一个识屏插件，是为了解决一个很具体的痛点：智能体在终端里跑得再快，也看不见屏幕左边那半张设计稿，更读不到你 IDE 里被弹窗遮住的红色报错。Harness 本身承担的是本地运行环境、模型路由、上下文管理和工具调用的职责，它能帮编码智能体连接代码、命令和文件，但屏幕这种非结构化信息，默认并不在它的输入范围内。识屏插件要做的，就是把“屏幕上有什么”转换成“模型能理解的文本上下文”，再回到 Harness 的会话流里。

下面这套流程会从插件设计、模块拆分、核心实现、运行验证到问题排查完整走一遍。读完以后，你自己也能按同样思路，给本地编码智能体扩展截图、OCR、窗口识别一类能力。需要先说明，不同 Harness 版本的插件 API 和配置字段会有差异，文中的代码和配置属于通用实现思路，落到自己项目时要重新核对版本、模型名和插件规范。

1. 先搞清楚：Harness 为什么需要识屏插件

1.1 Harness 到底解决了什么问题

DeepSeek Harness 这类工具，本质上是一个负责承载编码智能体的本地运行框架。你可以把它理解成智能体的“驾驶舱”：它负责加载模型配置、管理多轮会话、调用本地命令、读取文件、执行测试，再把这些结果统一交给模型继续推理。

Harness 与单纯的 Agent 是两层概念。

Agent 强调的是“决策循环”：看到问题、规划步骤、调用工具、观察结果、继续推进。Harness 强调的是“运行环境”：让 Agent 能稳定访问代码库、命令、沙箱、日志和配置。两者不是互斥关系，而是承载关系。没有 Harness，Agent 只是一个会思考但手伸不出去的循环；没有 Agent，Harness 也只是个空壳框架。

在接入 DeepSeek 模型的场景里，Harness 通常还要承担配置下发和请求路由的工作。开发者会配置模型名称、接口地址、API Key、超时时间等参数，Harness 再把这些参数应用到整个智能体会话里。很多报错都发生在这一层，比如模型名配错、接口地址不匹配、多轮消息结构不对，都会导致上游返回 400 或 422。

1.2 智能体“看不见屏幕”的真实场景

文字类工具能读文件、能执行命令，但屏幕上的内容对它来说是盲区。实际开发里，至少这四类信息经常只能靠屏幕传递：

• IDE 右下角弹出的报错弹窗，内容短暂，日志文件里不一定有完整记录。
• 设计稿、原型图、UI 标注，智能体拿到的只是文件路径，看不到视觉布局。
• 终端里正在运行的服务输出，用户想让智能体帮忙分析，但智能体没有实时读取终端画面的权限。
• 视频会议、演示文稿、远程桌面里的信息，用户看到但无法直接复制成文本。

这些场景的共同点是：信息以像素形式存在，而不是以字符串形式存在。识屏插件要做的，就是把像素转成结构化文本，再作为上下文交给模型。

1.3 插件要覆盖的完整链路

一个完整的识屏插件，至少要覆盖六段链路：

1. 捕获：从操作系统获取屏幕图像。
2. 裁剪：只保留用户关心的区域，减少无关信息。
3. 预处理：调整图像清晰度，提升 OCR 识别率。
4. 识别：用 OCR 引擎把图像转成文本。
5. 结构化：给识别结果加来源、时间、区域、置信度字段。
6. 注入：把结果交给 Harness，让它出现在智能体的上下文里。

这六段链路里，最容易被低估的是第 5 步。很多人把 OCR 文本直接拼接进提示词，结果模型分不清哪些是代码、哪些是屏幕文字，上下文乱成一团。正确做法是给屏幕文本打上清晰的标记，让模型知道“这段内容来自屏幕识别，可能包含排版噪声”。

1.4 插件与 Harness 的边界

写插件之前要划清边界：哪些逻辑放插件里，哪些放 Harness 里。

插件只负责“感知屏幕”，不负责“决定下一步做什么”。是否调用识屏工具、什么时候调用、识别结果是否可信，这些决策应该交给模型和 Harness 的调度逻辑。插件也不应该直接修改系统文件或执行高危操作，它只输出一段上下文，最终行为仍然由智能体的主循环控制。

这样做的好处是职责单一、易排查。如果识屏结果有问题，只需要看插件日志；如果模型没有使用识屏结果，只需要看 Harness 的会话日志，不会互相污染。

2. 识屏插件的设计目标与模块拆分

2.1 功能基线：一个最小可用的识屏插件必须包含什么

我最初的想法并不是做一个完整的截图工具，而是让 Harness 里的智能体能看到屏幕上最关键的几类信息：终端报错、IDE 诊断、设计稿、弹窗提示。围绕这个目标，插件被拆成四个模块。

这四个模块串起来以后，插件对外只暴露一个入口。这个入口接收一个参数：截图区域或者截图模式，返回一段结构化文本。Harness 里的智能体只需要调用这个入口，不需要关心底层是 Tesseract 还是别的 OCR 引擎。

2.2 三种接入方式：命令调用、工具注册、上下文注入

Harness 插件常见的接入方式有三种，识屏插件可以根据使用习惯选择。

第一种是命令调用。用户在终端里执行一条命令，比如screen-reader --region 0 0 800 600，插件把识别结果打印到标准输出，再手动复制进对话。这种方式实现最简单，但自动化程度低，适合验证阶段。

第二种是工具注册。把识屏能力注册成 Harness 可调用的工具，模型在需要看屏幕时自己发起调用。这是最推荐的方式，因为模型可以根据任务决定是否使用屏幕信息，而不是每次对话都强行注入大段文本。

第三种是上下文注入。通过 hook 在会话开始或每轮对话结束时，把最近一次识屏结果自动追加到上下文。这种方式会让模型持续感知屏幕状态，但 Token 消耗也最大，适合需要连续监控屏幕的场景。

实际项目里，我建议先把第一种跑通，再做成第二种。工具注册方式能更好地控制识别时机，也更容易做权限和频率限制。

2.3 隐私边界先想清楚，再写代码

屏幕截图是高度敏感的数据。插件一旦跑起来，它能看到用户正在看的一切，包括代码里的密钥、聊天窗口、邮箱、内部系统地址。写代码之前必须先定义隐私边界。

我的做法是三条规则：

• 默认只识别用户显式指定的区域，不做无差别全屏后台扫描。
• 尽可能在本地完成识别，不把原始截图直接上传到模型服务。
• 上下文里过滤邮箱、手机号、密钥路径等敏感模式，必要时用脱敏串替换。

这里要注意，OCR 识别出的文本仍然会随对话请求发送给模型，所以“本地识别”只解决了一部分隐私问题。真正敏感的信息，应该在注入上下文之前就过滤掉。

注意：把屏幕内容转换成文本再交给模型，并不等于数据就安全了。识别结果会进入模型上下文，敏感信息脱敏必须发生在注入之前，而不是模型返回之后。

3. 环境准备与项目骨架

3.1 依赖清单

识屏插件的核心依赖并不复杂，主要分三块：截图库、OCR 引擎、Python 运行时。

安装时建议先装 OCR 引擎本体，再装 Python 依赖。因为 pytesseract 只是调用外部命令的封装，如果系统里没有 Tesseract，即使 pip 安装成功，运行时报错也会让人误以为是 Python 依赖问题。

Ubuntu 环境可以用下面命令安装 Tesseract 和中文语言包：

sudo apt update sudo apt install tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng

macOS 环境可以这样装：

brew install tesseract tesseract-lang

Windows 环境需要从官方发布页下载安装包，安装时勾选中文语言，并把 Tesseract 的安装目录加入 PATH。

Python 依赖用虚拟环境管理：

python3 -m venv .venv source .venv/bin/activate pip install pillow pytesseract

安装完成后，用下面命令确认 OCR 引擎和语言包可用：

tesseract --version tesseract --list-langs

--list-langs输出里应该能看到eng和chi_sim，否则后续中文识别会直接返回空结果。

3.2 项目目录结构

插件项目结构尽量保持简单，核心代码集中在src/screen_plugin下：

screen-helper/ ├── pyproject.toml ├── config/ │ └── plugin.yaml ├── scripts/ │ ├── capture.py │ ├── ocr.py │ └── build_context.py ├── src/ │ └── screen_plugin/ │ ├── __init__.py │ ├── cli.py │ ├── capture.py │ ├── preprocess.py │ ├── ocr.py │ └── context.py ├── tests/ │ └── test_ocr.py └── README.md

scripts目录里的脚本是最初的验证脚本，src里是正式模块。这样拆分的好处是，先写临时脚本把链路跑通，再抽象成可复用模块，避免一开始就陷入类和接口设计里。

3.3 最小配置示例

Harness 所在项目的配置通常包含 provider、model、API Key 等字段。识屏插件本身可以独立配置，用 YAML 挂到 Harness 的插件配置里。

plugin: name: screen-reader enabled: true command: python3 scripts/capture_and_ocr.py default_region: enabled: false x: 0 y: 0 width: 1920 height: 1080 ocr_lang: chi_sim+eng context_tags: - "<screen>" - "</screen>" privacy_filter: email: true phone: true

这里的command是插件给 Harness 的调用入口，context_tags标记注入的屏幕文本范围，privacy_filter决定是否启用脱敏。不同 Harness 的插件规范会有差异，落地前要换成你所用版本的实际字段名。

4. 核心实现：从屏幕像素到模型上下文

4.1 截图模块：支持全屏、区域和活动窗口

截图模块要处理一个核心问题：截哪里。最简单的是使用 Pillow 的ImageGrab，它在 Windows 和 macOS 上体验较好，在 Linux 上会受限。

下面是支持全屏和指定区域截图的实现：

# src/screen_plugin/capture.py from __future__ import annotations import argparse from pathlib import Path from PIL import Image, ImageGrab def capture_all_screens(output: Path) -> Path: image = ImageGrab.grab(all_screens=True) image.save(output, "PNG") return output def capture_region(x0: int, y0: int, x1: int, y1: int, output: Path) -> Path: if x1 <= x0 or y1 <= y0: raise ValueError("invalid region: right/bottom must be greater than left/top") image = ImageGrab.grab(bbox=(x0, y0, x1, y1), all_screens=True) image.save(output, "PNG") return output if __name__ == "__main__": parser = argparse.ArgumentParser(description="capture screen") parser.add_argument("--x0", type=int, default=0) parser.add_argument("--y0", type=int, default=0) parser.add_argument("--x1", type=int, default=1920) parser.add_argument("--y1", type=int, default=1080) args = parser.parse_args() capture_region(args.x0, args.y0, args.x1, args.y1, Path("capture.png"))

关键点是all_screens=True。多显示器环境下，如果漏掉这个参数，只会截到主屏，副屏坐标会偏移。注意bbox的坐标是绝对屏幕坐标，不是相对窗口坐标，跨屏截图时最容易踩这个坑。

4.2 图像预处理：识别率低的问题，一半出在这里

OCR 识别率低，一半是图像质量问题，一半是语言包问题。直接从屏幕截下来的图很少是理想的，字体太小、背景复杂、反色文字、DPI 缩放，都会影响识别结果。

预处理模块至少要做三件事：转灰度、放大、对比度增强。

# src/screen_plugin/preprocess.py from PIL import Image, ImageEnhance, ImageOps def prepare_for_ocr(image: Image.Image, scale: float = 2.0) -> Image.Image: # 转灰度 gray = ImageOps.grayscale(image) # 放大，避免小字号文字识别失败 if scale != 1.0: new_size = (int(gray.width * scale), int(gray.height * scale)) gray = gray.resize(new_size, Image.LANCZOS) # 增强对比度，减少背景噪声 enhancer = ImageEnhance.Contrast(gray) return enhancer.enhance(1.8)

为什么这里用灰度而不是二值化？因为终端和 IDE 里经常有彩色字体、代码高亮、深色背景。直接二值化会让信息大量丢失，灰度加对比度增强更稳妥。如果灰度图识别效果还是不好，再尝试局部阈值二值化。

4.3 OCR 模块：Tesseract 的安装与语言包

OCR 模块负责把处理后的图像转成文本，同时尽量保留文字的位置信息。

# src/screen_plugin/ocr.py from __future__ import annotations from PIL import Image import pytesseract def ocr_image(image: Image.Image, lang: str = "chi_sim+eng") -> str: return pytesseract.image_to_string(image, lang=lang) def ocr_image_with_data(image: Image.Image, lang: str = "chi_sim+eng") -> dict: data = pytesseract.image_to_data(image, lang=lang, output_type=pytesseract.Output.DICT) lines = [] current_line = [] last_block = None for i, text in enumerate(data["text"]): block = data["block_num"][i] if block != last_block and current_line: lines.append(" ".join(current_line)) current_line = [] last_block = block if text.strip(): current_line.append(text.strip()) if current_line: lines.append(" ".join(current_line)) return {"text": "\n".join(lines), "line_count": len(lines)}

image_to_string适合快速验证，image_to_data能拿到每个文字块的位置信息。后续如果要让模型读终端日志、分析报错顺序，按块排列的文本会比整段文本更可用。

4.4 上下文打包：给模型结构化的屏幕文本

识别出的文本不能直接丢给模型。屏幕文本充满断行、噪点和上下文缺失，直接拼接会让模型误以为是用户输入或者代码。

结构化上下文的标准输入输出如下：

# src/screen_plugin/context.py import json import time from dataclasses import asdict, dataclass @dataclass class ScreenContext: source: str region: str captured_at: float ocr_lang: str text: str def build_context(text: str, region: tuple[int, int, int, int], lang: str) -> str: ctx = ScreenContext( source="screen_ocr", region=",".join(str(v) for v in region), captured_at=time.time(), ocr_lang=lang, text=text, ) return json.dumps(asdict(ctx), ensure_ascii=False)

打包完成后，注入时最好加上明确的区域标记：

<screen source="screen_ocr" region="0,0,800,600" lang="chi_sim+eng"> error: failed to load module at /home/user/src/main.ts:12 </screen>

这样模型能明确区分这是屏幕识别文本，不是用户消息，也不是代码文件。上下文结构越清晰，模型越不会把它和真实指令混在一起。

4.5 与 Harness 的集成入口

由于不同 Harness 的插件 API 不同，这里给出一个通用参考结构。思路是：Harness 调用插件入口，插件内部执行 Python 命令，再把结果转成工具可读的返回值。

// integration/screenPlugin.ts import { execFileSync } from "node:child_process"; export interface ScreenInput { region?: [number, number, number, number]; scale?: number; lang?: string; } export function runScreenReader(input: ScreenInput) { const args = ["scripts/capture_and_ocr.py"]; if (input.region) { const [x0, y0, x1, y1] = input.region; args.push("--x0", String(x0), "--y0", String(y0)); args.push("--x1", String(x1), "--y1", String(y1)); } const stdout = execFileSync("python3", args, { encoding: "utf-8", timeout: 15_000, }); return { type: "text", content: stdout.trim() }; }

这段代码的关键点是超时控制。OCR 是 CPU 密集操作，中文识别在低配机器上可能要几秒甚至十几秒。如果 Harness 对工具调用有超时限制，插件必须把单次识别控制在限制时间内，或者把识别结果缓存起来，避免重复识别。

5. 运行验证：从命令行到 Harness 日志

5.1 先验证 CLI 本身

集成到 Harness 之前，先确认命令行自己能跑通。先截取屏幕左上角一个区域：

python3 scripts/capture_and_ocr.py --x0 0 --y0 0 --x1 800 --y1 600

正常输出应该是一个 JSON 对象，里面包含text和line_count字段，而不是把 OCR 文本直接打到屏上。

{ "text": "error: cannot find module 'lodash'\n", "line_count": 1 }

这一步验证的目标是：截图没有黑屏、OCR 识别出了内容、JSON 结构符合预期。只要输出稳定，插件主体就完成了。

5.2 再验证 Harness 能拿到上下文

CLI 验证通过后，再进入 Harness 集成验证。具体方式取决于你选择的接入模式。

如果是命令调用模式，就在 Harness 允许的命令列表里直接调用python3 scripts/capture_and_ocr.py，观察返回结果是否进入对话记录。

如果是工具注册模式，先查看 Harness 的日志，确认工具已注册成功。触发一次调用后，在会话日志里能看到类似这样的工具结果记录：

tool_call: screen-reader tool_result: {"source": "screen_ocr", "text": "..."}

如果日志里出现tool not found或command not found，说明插件没有被正确注册，需要回到配置和命令路径检查。

5.3 端到端指标：延迟、Token、识别准确率

端到端验证阶段要关注三个指标。

第一是单次识屏延迟。从发起调用到上下文返回值，理想情况下应该在 2 到 10 秒之间。超过 20 秒就要检查是不是 OCR 处理了过大的截图区域，或者 CPU 资源不足。

第二是 Token 消耗。一次 OCR 结果可能上千字，如果 Harness 在每轮对话都注入这段文本，Token 消耗会快速增长。用 Harness 的 token 计数功能或者 API 返回的 usage 字段监控。

第三是识别准确率。可以准备一组固定样张，比如终端报错、IDE 诊断、中文弹窗、英文文档，分别测试。用字段缺失率来判断，这里指的是关键信息是否完整，比如报错行号、文件名、错误码，而不是要求一个字都不差。

6. 常见问题与排查链路

6.1 截图黑屏、区域偏移、多屏坐标不对

现象是图片生成成功，但内容是黑屏，或者截图区域不在预期位置。

先检查系统权限。Windows 和 macOS 对屏幕录制有独立授权，程序没有屏幕录制权限时，截图内容通常是黑屏或桌面壁纸，而不是应用程序内容。到系统设置里给终端或 Python 进程授予屏幕录制权限。

再检查多屏坐标。多显示器时，副屏坐标可能是负数，比如-1920,0。如果你用固定0,0作为左上角，永远截不到副屏。使用ImageGrab.grab(all_screens=True)可以获取包含所有屏幕的完整画布，再根据相对坐标裁剪。

最后检查 Linux 桌面环境。Wayland 会话对全局截图的权限限制比 X11 严格，Pillow 的ImageGrab在很多 Wayland 环境下直接拿不到图像。这种情况需要改用桌面环境提供的截图能力，比如gnome-screenshot或grim。

6.2 OCR 识别为空、中文乱码、识别错字

OCR 返回空字符串，最常见的三个原因是：语言包没装、图像区域太小、文字背景复杂。

检查顺序如下：

tesseract --list-langs

如果输出里没有chi_sim，中文就识别不出来。如果语言包没问题，就检查截图的文字是否足够大。屏幕上常见的 DPI 缩放会让实际字体很小，OCR 之前先对图像做 2 倍放大。

中文乱码还有一个常见原因是语言包安装不完整，或者使用了eng单语言去识别中文。推荐用chi_sim+eng混合语言，这样中英文混排的报错信息都能覆盖。

6.3 Harness 不识别插件、命令路径找不到

现象是 Harness 日志里提示命令不存在，或者工具调用失败。

优先检查两点。第一，command配置里写的是相对路径还是绝对路径。Harness 的工作目录可能和你执行命令的目录不同，相对路径很容易失效。建议用项目根目录下的绝对路径或者脚本入口，避免依赖工作目录。

第二，检查 Python 进程是否能找到依赖包。Harness 执行python3时，使用的可能是系统 Python，而不是你创建虚拟环境里的 Python。建议在插件入口脚本里显式指定虚拟环境：

#!/usr/bin/env bash source /path/to/screen-helper/.venv/bin/activate python /path/to/screen-helper/scripts/capture_and_ocr.py "$@"

这样可以避免因环境 PATH 不同导致导入PIL或pytesseract失败。

6.4 thinking 模式报 reasoning_content 400

这是接入 DeepSeek 模型时非常典型的报错。多轮对话进行到第二轮或第三轮时，上游返回 400，关键日志是：

upstream_status: http 400 cause: the `reasoning_content` in the thinking mode must be passed back to the api.

原因是服务开启了 thinking 模式，第一轮响应里会返回reasoning_content字段，下一轮请求要求把上一轮的reasoning_content原样回传。插件在给 Harness 注入上下文时，如果重新组装的请求消息数组丢掉了这个字段，就会触发 400。

排查路径按下面顺序走：

1. 查看请求日志，确认是不是从第二轮开始失败。
2. 查看 Harness 是否在会话持久化里保留了reasoning_content。
3. 查看注入上下文是否重建了整个消息数组，覆盖了原始消息字段。
4. 如果不需要思考过程，在配置里关闭 thinking 模式或让它保持透传。

这个问题的根源通常不在识屏插件本身，而是插件追加上下文消息时破坏了原有多轮消息结构。修改时要注意保留原始消息字段，而不是只追加一条新消息。

注意：给 Harness 增加上下文时，不要直接重建整段消息数组。应该以“追加一条用户侧上下文”的方式，保留原有消息的role、content、reasoning_content等字段。

6.5 上下文超长和 Token 成本问题

屏幕 OCR 结果动辄几百上千字，如果每轮对话都注入，很容易超出模型上下文窗口，造成请求被截断或者费用上涨。

解决思路是给识屏上下文加“有效期”。只在用户主动触发、或者模型明确请求读取屏幕时，才注入本次识屏结果。注入时还可以做文本精简：

• 去掉重复的空白行和装饰性字符。
• 只保留包含关键字（error、warning、fail、module、line）的行。
• 对长文本做摘要，而不是全量注入。

Harness 启动时如果执行pnpm dsh web卡住，通常也是依赖安装或端口占用问题，这一类属于环境问题，不在屏幕插件的职责范围内，但会直接影响插件开发调试。先确认node_modules完整、目标端口未被占用、日志里没有EADDRINUSE，再继续调试插件，避免把环境问题误判成插件问题。

7. 生产环境建议与可复用清单

7.1 生产环境必须做的五件事

如果这个插件不只是自己电脑上用，而是要放进团队工具链，下面五件事不能省。

第一，权限最小化。插件默认只读用户显式指定区域，不启动后台全屏扫描。需要监听屏幕变化时，必须经过用户确认。

第二，敏感信息脱敏。注入上下文前过滤 email、手机号、路径、云凭证等模式。脱敏规则放到独立配置，不要硬编码在插件代码里。

第三，日志审计。识别操作要记录触发时间、截图区域、输出长度，但不记录完整截图内容。日志字段需要经过脱敏检查才能入库。

第四，资源限制。OCR 是 CPU 密集操作，要限制最大分辨率、单次识别超时、并发调用数。给 Harness 的调用入口设置 15 秒到 30 秒超时，避免拖垮主线程。

第五，可回滚。插件配置变更前，保留上一份可用版本。Harness 升级后，先在小样本里回归验证插件命令是否还能被正确调用。

学习环境与生产环境的差异如下：

7.2 发布前检查清单

这个清单可以在接入 Harness 之前逐项勾选，避免上线后反复调试：

• [ ] 截图命令在 Harness 工作目录下能直接执行，不依赖当前终端目录。
• [ ] 截图区域坐标覆盖多显示器场景，不出现负坐标或黑屏。
• [ ] Tesseract 语言包已安装，tesseract --list-langs输出包含目标语言。
• [ ] OCR 结果以结构化 JSON 返回，而不是裸文本。
• [ ] 注入上下文的文本带screen来源标记，模型可区分来源。
• [ ] 敏感信息过滤规则已生效，JSON 输出里看不到明显密钥或手机号。
• [ ] 单次调用延迟在预期范围内。
• [ ] 多轮对话场景下，没有丢失reasoning_content导致 400。
• [ ] Harness 升级后，插件命令仍然在配置的插件列表里被识别。

7.3 扩展方向：多模态、窗口事件、监控模式

识屏插件做到这一步，已经能解决“智能体看不见屏幕”的基础问题。继续扩展有四个方向比较实用。

第一个方向是接入多模态模型。OCR 的瓶颈在于它只能提取文本，丢失了布局、颜色、图表信息。如果使用的模型支持视觉输入，可以直接把截图区域以图片形式传给模型，让模型自己理解界面布局。这样识别精度更高，但 Token 和费用也会更高。

第二个方向是活动窗口识别。通过操作系统 API 获取当前前台窗口的标题、进程名和位置，自动判断用户在看编辑器还是终端，再把识别区域对准目标窗口。

第三个方向是屏幕变化监控。定时截取同一区域的图像，对比像素差异，只在发生变化时触发 OCR。这对开发调试场景很有用，可以实时捕获一闪而过的报错弹窗。

第四个方向是区域收藏与命令绑定。把常用的识别区域存成命名区域，比如terminal、design、browser，插件入口直接收--preset terminal，减少每次输入坐标的成本。

这些扩展的核心判断是：识屏插件只是一个感知层，它的价值不在于 OCR 算法多强，而在于能不能用最小的成本，把屏幕信息准确、安全地变成模型可用的上下文。把基础链路做稳，再按需扩展，是这条路最务实的走法。