企业官网建设流程全解析

DeepSeek Harness 入门阶段最容易卡住的地方，是给这个 AI 工具接上一双眼睛：主模型默认只处理文本，遇到报错截图、设计稿、测试失败图时，模型只会说“我看不到图片”。想给 AI 配好识图能力，需要把三样东西组合起来：DeepSeek Harness 作为调度外壳，ModLens 插件作为视觉入口，GLM-5.3 Flash 这类轻量多模态模型作为实际读懂图片内容的视觉引擎。下面会从零开始，完成安装 DeepSeek Harness、接入主模型、安装 ModLens 插件、配置视觉密钥、跑通一张图片的完整识别流程，并整理识图失败时最值得检查的排查链路。学完之后，你可以把截图自动诊断、UI 视觉检查和图片内容提取这类能力接进自己的 Agent 工作流。

1. 先分清三个角色：Harness 是调度外壳，ModLens 是眼睛，GLM-5.3 Flash 是视觉神经

1.1 DeepSeek Harness 负责什么：为什么它不直接识图

DeepSeek Harness 是一个以 DeepSeek 模型为核心的本地 Agent Harness 工具，它负责把模型 API、插件、会话上下文、工具调用组织成一条可执行链路。可以把 Harness 理解成“大脑的外壳”：它决定主模型什么时候发言、什么时候调用工具、工具返回结果后如何继续推理。

很多初学者会误以为 Harness 本身具备图片理解能力，实际上 Harness 只是调度层。能不能识图取决于两个条件：主模型是否支持多模态输入，或者是否有插件能把图片转换成主模型能理解的文本。

这里要澄清一个容易混淆的概念：Harness 和 Agent 不是一回事。Agent 更强调自主决策，模型自己决定下一步做什么；Harness 更强调工程化编排，把模型调用、插件、工具、重试、日志这些环节管理起来。在 DeepSeek Harness 的场景里，识图能力是一个典型插件能力，而不是 Harness 的核心职责。理解这一点，后面配置报错时才能快速定位：问题出在 Harness、插件，还是视觉模型。

1.2 ModLens 插件：图片怎么变成主模型能看懂的文本

ModLens 是一个负责“视觉入口”的插件。它做的事情可以概括为一句话：把图片从视觉世界翻译成文本世界。

当你给 Agent 一个图片路径或图片 URL 时，ModLens 会拦截这个输入，读取图片内容，调用视觉模型生成描述文本，再把这段文本拼进对话消息里，让 DeepSeek 主模型基于这段文本继续推理。

这里要理解 ModLens 的设计动机。直接让文本主模型处理图片二进制是行不通的，不仅浪费 tokens，效果也很差。ModLens 的做法是增加一个翻译层：

图片路径/URL -> ModLens 读取图片 -> 调用视觉模型 -> 生成文本描述 -> 回填主模型会话 -> 主模型继续推理

这个设计让主模型不需要具备多模态能力，也能理解图片内容，代价是“看到”的是经过视觉模型转述的内容，而不是原始像素。对报错截图、界面截图、文档截图这类场景，转述粒度完全够用。

1.3 为什么用 GLM-5.3 Flash 这类轻量多模态模型

GLM-5.3 Flash 在当前接入场景里充当视觉理解引擎。选它而不是选一个重型多模态大模型，核心理由是 Agent 循环里的识图调用非常频繁，轻量模型在响应速度、调用成本、上下文占用上更适合这种高频小任务。

需要注意的是，模型名称、接口地址、计费方式都可能随供应商调整。落地前先用一个最简单的请求确认当前支持的模型名、版本和视觉接口参数。下面示例用于说明思路，实际项目要结合自己的模型名、base_url 和密钥调整。

三个组件的角色可以汇总成一张表：

这三个组件可以分别替换：Harness 可以换别的工具，ModLens 可以换其他视觉插件，GLM-5.3 Flash 可以换成任何支持图片输入的视觉模型。理解这个分层，后面配置才不会把自己锁死在某一个固定组合上。

2. 环境准备与基础安装：先把 DeepSeek Harness 跑起来

2.1 环境要求和检查命令

在安装之前，先确认本机环境满足最低要求。视觉模型调用走的是远程 API，本地不需要 GPU，也不需要下载大模型权重，这对没有独立显卡的开发机比较友好。

如果node -v版本偏低，先升级 Node.js 再继续。pnpm 版本过低会直接导致后面安装卡住，这是常见坑之一。

2.2 安装 DeepSeek Harness 并解决卡在 pnpm dsh web 的问题

以命令行方式安装为例：

git clone <仓库地址> deepseek-harness cd deepseek-harness pnpm install pnpm dsh web

仓库地址以你准备使用的版本为准。如果工具同时提供桌面版和 CLI 版，建议先安装 CLI 版跑通流程，再考虑图形界面。

实际安装中最常见的现象是：执行pnpm dsh web后长时间卡住不动。出现这个问题时，按下面的顺序排查：

pnpm -v # 检查 pnpm 版本 corepack enable # 或升级 Node 后重新安装 pnpm pnpm install pnpm build pnpm dsh web

前端构建内存不足也会导致卡住，可以显式提高 Node 内存上限：

NODE_OPTIONS=--max-old-space-size=4096 pnpm build

检查点：启动后浏览器能打开本地端口，命令行里执行dsh status不报错。如果端口被占用，先找到占用进程再重启。

2.3 配置 DeepSeek 主模型 API Key

在项目根目录创建.env文件，写入主模型密钥：

DEEPSEEK_API_KEY=sk-你的主模型密钥 DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 DEEPSEEK_MODEL=deepseek-chat

DEEPSEEK_BASE_URL一般不需要改动；如果通过本地代理转发请求，可以改成代理地址。.env文件务必加入.gitignore，避免密钥泄漏。

2.4 先跑通纯文本对话，再谈识图

识图配置前，先验证主模型链路是通的：

dsh chat "用一句话说明 TCP 三次握手"

预期输出：模型正常返回一段解释。如果这一步失败，先不要往下配 ModLens，因为问题几乎都在密钥、网络或模型名上。检查顺序是：API Key 是否正确、base_url 是否可达、模型名是否在供应商列表里、本地代理是否干扰了请求。

注意：不要只验证命令能执行，要看返回内容是否来自目标模型。如果返回的是本地错误信息或代理错误页，说明请求根本没有到达模型服务。

3. 安装并启用 ModLens 插件：给 Harness 增加视觉入口

3.1 安装插件并确认被识别

先通过命令行安装：

dsh plugin add modlens dsh plugin list

如果当前工具没有插件市场，也可以把 modlens 插件目录放进~/.harness/plugins/或项目plugins/目录，再执行dsh plugin list确认识别情况。具体目录以版本为准。

预期输出：modlens 出现在插件列表中，状态为 disabled。此时还没有真正启用，只是安装完成。

3.2 注册插件并配置视觉参数

在 Harness 配置文件（例如~/.harness/config.yaml）中启用插件，并填写视觉模型相关配置：

plugins: - name: modlens enabled: true vision: provider: glm model: glm-5.3-flash api_key_env: MODLENS_VISION_API_KEY base_url: https://vision-provider.example.com/v1 timeout: 30 max_image_size: 2048 temperature: 0.2

这里有几个关键点：

• api_key_env指向环境变量名，不要直接在配置文件里写明文密钥。
• base_url需要按实际使用的视觉模型服务地址调整。如果服务兼容 OpenAI 风格的/v1接口，直接填对应的 base_url 即可。
• model字段要和供应商实际支持的模型名一致，写法不同会导致 400 或 404。

3.3 视觉密钥为什么要单独配置

所谓“ModLens 使用视觉密钥”，是指 ModLens 调用 GLM-5.3 Flash 视觉接口时，使用独立的MODLENS_VISION_API_KEY，而不是复用 DeepSeek 主模型的密钥。

单独配置的好处：

1. 权限隔离：视觉密钥只能访问视觉模型，即使泄漏也不会影响主模型调用。
2. 配额独立：视觉请求和文本请求分别计量，便于统计成本。
3. 便于轮换：密钥过期或需要更换时，只需要改视觉密钥。
4. 审计清晰：日志里能区分哪次调用来自主模型，哪次来自视觉插件。

设置方法：

export MODLENS_VISION_API_KEY=你的视觉模型密钥

如果工具提供dsh doctor命令，可以执行一次健康检查；没有的话，用dsh plugin list加日志查看密钥是否成功读入。

3.4 识图相关参数速查

temperature是很容易被忽略的参数。识图任务需要稳定输出，建议保持在 0.2 左右；如果模型描述总是遗漏内容，可以尝试调低到 0.1，而不是调高。

3.5 确认插件真正加载

执行：

dsh plugin list dsh log tail --plugin modlens

预期结果：插件状态为 enabled，日志中出现类似modlens initialized的关键字，启动时没有密钥缺失告警。

如果日志里出现MODLENS_VISION_API_KEY is not set，说明环境变量没被进程读取。检查是否在同一终端里执行了 export，或者.env是否被 Harness 自动加载。

4. 用最小案例跑通识图：一张报错截图走完全链路

4.1 准备一张测试图

mkdir -p ~/harness-test # 把一张带文字的截图放到该目录，例如 error.png file ~/harness-test/error.png ls -lh ~/harness-test/error.png

推荐使用带文字的报错截图作为第一张测试图，因为文字内容容易验证识别是否准确。图片不要太大，先控制在 1MB 以内，避免请求体超限。

4.2 用一条命令发起识图

dsh run "请分析 /Users/me/harness-test/error.png 这张图片，逐字输出其中的错误提示，并说明可能原因"

ModLens 插件会拦截包含图片路径的消息，读取图片并调用 GLM-5.3 Flash 生成描述，再把描述交给 DeepSeek 主模型处理。

4.3 预期结果

正常情况：

• 返回图片中的错误文案
• 能结合上下文给出可能原因
• 日志里出现一次视觉模型的成功请求，状态码 200

异常情况：

4.4 从命令行到 API 格式：识图请求的内部样子

如果 Harness 暴露兼容 OpenAI 风格的接口，最终发给视觉模型的请求大致是这样的：

{ "model": "glm-5.3-flash", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "请分析这张截图的错误信息"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,...."}} ] } ], "temperature": 0.2 }

本地图片会被 ModLens 转成 base64 data URL；远程图片可以直接放 URL。如果你在日志里看到类似结构，说明插件已经把图片正确编码并发送给了视觉模型。

4.5 放进工作流：让 Agent 截图后自动诊断

dsh run "先在浏览器打开本地测试页面，截图保存到 /tmp/ui-error.png，再用识图能力分析弹窗里的错误，并给出修复代码"

这里的关键是让 Harness 把“截图工具”和“ModLens 识图”串成一条工具链。第一次跑完整链路时，建议分两步执行：先截图确认文件生成，再识图分析。一次跑完整链路如果失败，很难判断是截图问题还是识图问题。

5. 配置背后的原理：图片是怎么变成主模型推理依据的

5.1 ModLens 的完整调用链路

按顺序拆解一次识图请求：

1. 用户消息包含图片路径或图片 URL。
2. ModLens 校验图片是否存在、大小是否超限。
3. 本地图片转 base64，远程图片保留 URL。
4. ModLens 构造多模态消息，调用 GLM-5.3 Flash。
5. 视觉模型返回描述文本。
6. ModLens 把描述文本作为工具结果回填到主模型会话。
7. DeepSeek 主模型基于文本继续推理并回复。

这个链路决定了几个工程取舍：视觉调用失败时，主模型得不到任何图片信息；描述文本越长，主模型消耗 tokens 越多；图片预处理越差，描述越不准确。

5.2 三种密钥和地址别搞混

一个典型场景是：纯文本对话正常，但识图时报 401。先不要怀疑主模型密钥，优先检查视觉密钥是否配置、是否正确读入。

5.3 为什么识图逻辑不写死到主模型里

三个原因决定了插件加轻量视觉模型的方案更合理：

1. 成本：视觉请求通常按图片和 token 计费，频繁把图片塞给主模型不划算。
2. 延迟：纯文本推理比图像理解快得多，Agent 循环里每多一次慢调用，整个任务耗时都会被拉长。
3. 可替换性：插件方式让视觉模型可以独立升级、替换、灰度，不影响主模型配置。

5.