设想一次前端故障排查：Agent 读完组件代码，判断按钮应该正常显示；测试同事发来截图，按钮却被弹窗遮住。继续追问，Agent 又根据代码描述了一张架构图，可实际请求已经绕过旧网关。三个人讨论的是同一个系统，手里拿的却是三个版本的事实。
问题不全在模型推理。代码描述设计，浏览器呈现运行状态，截图保存某个瞬间，架构图则帮助人理解关系。缺少其中一环，Agent 容易把"按道理应该如此"当成"刚才确实如此"。让它多想一分钟，未必比补一张正确的截图更有效。
Archify、BrowserSkill 和 ModLens，分别补上架构表达、浏览器操作和图片理解能力。它们不是三个同类看图插件，也不是一套安装后自动串起来的流水线。理解各自的输入、输出和依赖，才知道该把哪一个接进 DeepSeek Harness，简称 DSH。
三种缺口，三种接入方式
遇到"线上页面不对"，首先需要复现操作和观察页面，BrowserSkill 更合适；只有同事发来的截图，需要提取报错文字和界面布局，ModLens 才对题；已经弄清系统关系，希望交付能讨论、能点开的架构说明，则轮到 Archify。
共同点是增强 Agent 的工作能力，区别在于能力落在哪里。Archify 主要交付工作方法，BrowserSkill 提供原生浏览器工具，ModLens 提供视觉转换工具及模型接入方式。把它们统称为插件没有问题，但不能据此推断它们具有相同的后台服务或权限边界。
架构需要回答三个问题：插件提供什么，执行依赖在哪里，结果由谁保存或使用。Archify 把表达规则交给宿主；BrowserSkill 连接宿主与本地浏览器环境；ModLens 在宿主入口与视觉后端之间提供转换能力。图中按职责归类，具体依赖关系由各自的模块图表达。
Archify：把系统关系变成可讨论的架构产物
它解决的是表达成本
仓库里有接口、队列、数据库和外部服务，不代表团队已经拥有一张好用的架构图。让 Agent 罗列目录通常很快，让它区分主链路、外围依赖、运行边界和不确定关系，则需要明确的表达规则。
Archify 将这种规则组织成 Skill，帮助 Agent 把结构化架构规格转换为可交互的独立 HTML。适合接手旧项目、准备技术评审、解释一次复杂改造，也适合把"白板上大家都懂"的关系保存成可重复打开的文件。
它并不因为装进 DSH，就自动拥有一台持续扫描仓库的架构分析服务器。DSH 适配器当前发布版的关键职责，是让 Agent 发现并使用随包提供的 Skill。理解材料、调用普通工具、形成规格及交付文件，仍发生在 Agent 的工作流程里。
总体架构：插件提供规则，宿主负责执行
从模块职责看，Archify 的 DSH 适配器属于Skill 提供型插件。它把架构表达方法交给宿主使用，任务执行仍依靠 DSH 的 Agent 和常规工具。图中是逻辑职责划分，不是源码目录或内部类的复刻。
| 组成部分 | 所属位置 | 主要职责 |
|---|---|---|
| DSH 适配器 | Archify 插件包 | 提供宿主发现 Skill 的接入机制 |
| Skill 资源 | Archify 插件包 | 保存架构表达规则与配套资源；自身不承担常驻服务职责 |
| Agent 与常规工具 | DSH 宿主 | 分析材料，按规则使用 shell 和文件系统完成生成与校验 |
| 项目材料、JSON 与 HTML | 工作区的数据和产物 | 分别承担分析依据、结构规格和展示结果的角色，不是三个运行服务 |
这里有两个容易混淆的边界。Skill 是任务规则，不是常驻服务；插件包不等于一个独立扫描、渲染和托管平台。产物也不属于插件运行时：JSON 与 HTML 写出后是文件，打开 HTML 阅读架构，并不意味着它会持续同步仓库变化。
插件包是能力的交付单位，宿主是执行这些规则的环境，工作区是材料和产物所在的位置。更新 Skill 不会自动重画已有 HTML；重新生成也需要重新核对材料。图中的读写关系表示宿主工具访问文件，不代表浏览器中的展示文件拥有任意项目访问权限。
这个设计的好处是结果容易携带，不必为了讨论一张架构图再部署展示服务。代价是文件交付需要说清楚：该适配器没有额外提供原生渲染工具，也不会保证普通 shell 写出的文件自动出现在 Web 界面的 Produced Files 区域。要求 Agent 返回实际路径，比一直刷新附件栏更直接。
图的可信度取决于材料和判断。代码里存在一个支付客户端，只能证明有相关实现，不能证明线上每笔交易都走这条调用链。对于无法确认的边，应该标注"待核实"，而不是让漂亮的箭头替推断签字。
一个实用的分析范围是"订单创建到支付结果回写"。入口、订单服务、支付适配层、消息队列和数据库，可以成为核心组件；日志格式、工具函数和每个字段的转换，则放进卡片细节。这样读者先看到业务路径，需要确认实现时再展开，不会在第一眼就被几十个方框拦住。
如果产物用于变更评审，还可以要求区分现状与方案：哪些边来自已有实现，哪些是计划增加的调用，哪些只是候选设计。将三者混画，比少画一个组件更危险，因为评审者很可能把愿望读成事实。Archify 降低的是表达与交付成本，材料真实性和方案责任仍需要团队承担。
安装与第一次使用
GitHub：Archify 的 DeepSeek Harness 集成。
已发布的适配器版本为 0.1.0，捆绑 Archify Skill 2.14.0，官方标注实验性兼容 DSH 0.1.0-rc.6。Node 要求为 ^22.19.0 || >=24.0.0。仓库还描述了待发布版本的目标，不能据此承诺旧包支持所有新版 DSH。
在已有 DSH 环境中执行：
dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0dsh --profile web不要把仓库根目录当成可直接安装的 DSH bundle。仓库里有多种集成，发布包才是这里使用的入口。进入对应 profile 后，可以这样提出任务：
使用 archify skill 展示当前仓库的运行时架构。保留 8 至 12 个核心组件、一条主要请求链路、外部依赖和信任边界。把实现细节放入组件卡片；无法从材料确认的调用关系标为待核实。生成并校验规格 JSON 和独立 HTML，返回两个文件的实际路径。
验收时先看图回答了什么问题：请求从哪里进入，数据最终写到哪里，哪个外部系统失败会影响主流程。随后核对少量关键组件和连线，最后才评价配色。把全部目录塞进一张图，通常只会得到一份需要放大很多倍的文件清单。
如果找不到 Skill，先确认启动的是安装插件的 profile；如果图已生成但界面没有附件，检查 Agent 返回的文件路径；如果结构不对，收紧目标和证据范围。重复安装并不能修复错误的分析前提。
BrowserSkill：让 Agent 在真实浏览器里观察和操作
从"给步骤"到"看到操作结果"
浏览器问题常常藏在状态里：用户是否登录、弹窗是否出现、页面是否加载完、某个按钮是否真的可点击。只读 HTML 或让用户不断截图，都会丢掉一部分上下文。
BrowserSkill 通过浏览器扩展连接 Chrome 或 Edge，让 Agent 在可见的 Agent Window 中工作。它能导航、检查页面、截图、点击和填写，也能管理标签页。适合前端问题复现、网页资料整理，以及需要观察真实交互结果的任务。
"能操作"不等于"总能继续"。登录、验证码和需要用户判断的环节，可以请求人工协助。把这些节点留在任务说明里，比让 Agent 在同一个登录框前反复点击更省时间。
总体架构：宿主适配、本地通信与浏览器执行
BrowserSkill 更接近一个分布在本机不同运行环境中的控制系统。DSH 插件、CLI、daemon 与浏览器扩展各有职责，不能把 npm 包等同于整个浏览器执行环境。图中的区域表示部署与职责边界，同一区域不代表所有组件处于同一进程。
| 架构区域 | 核心组成 | 主要职责 |
|---|---|---|
| DSH 侧 | 原生工具与会话归属约束 | 向 Agent 暴露能力；会话归属是插件的约束职责，不代表独立权限服务 |
| Web 展示侧 | 会话观察入口 | 呈现浏览器会话，帮助用户查看当前状态 |
| 本地进程侧 | bsk CLI、daemon |
CLI 适配调用，经进程间通信 IPC 联系 daemon；daemon 通过 WebSocket 连接扩展 |
| 浏览器侧 | 扩展、Agent Window 与标签页 | 扩展连接浏览器能力，窗口承载页面与登录状态 |
操作入口与观察入口承担不同职责。browser_* 工具用于发出操作或读取状态，Web 侧栏用于观察会话。图中实线突出主要调用关系，实际通信还包括结果返回；虚线只表达观察关系，不指定其内部传输协议。窗口、会话归属约束与通信进程属于不同类型的架构元素。
这套拆分也决定了故障归属：工具不可发现查 DSH 插件，CLI 无法启动查本地环境，扩展断连查通信链路，页面状态不符则回到浏览器侧。浏览器登录态位于实际浏览器环境，会话归属约束不等于账号隔离；这些组件分别升级，也就可能出现版本不配套的问题。
工具分为六组：会话、页面导航、页面检查、交互、标签页和辅助操作。检查能力包括快照、HTML、截图以及控制台和网络信息；交互能力覆盖点击、悬停、填写、选择和按键。分组能减少工具描述混杂，但不意味着开放了任意页面脚本执行或完整的交互录制能力。
插件默认可以按需加载工具，并提供浏览器会话的实时观察入口。Web 界面优先使用原生侧栏，也有浮层回退，不要求额外安装 Better Sidebar。观察端点对本地访问有约束，不能默认认为局域网反向代理也受支持。
安装：先接通浏览器，再加插件
GitHub：BrowserSkill；DSH 插件目录。
准备可工作的 DSH、pnpm 和 Chrome 或 Edge。浏览器链路还需要 bsk CLI 与对应扩展。官方提供以下 CLI 安装方式；这些命令会执行远程安装脚本，应在确认来源后运行。
macOS 或 Linux：
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | shexport PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"Windows PowerShell：
irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex通过项目 README 中的 Chrome Web Store 或 Edge Add-ons 链接安装扩展，打开扩展面板，确认连接状态。然后在 DSH 将使用的终端环境里检查：
bsk --version bsk doctor dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin@0.3.0dsh --profile web DSH 插件已包含 browser-skill，无需再为 DSH 单独运行 bsk install-skill。如果插件找不到 CLI，检查 DSH 进程的 PATH；刚安装后，原有进程可能仍保留旧环境。也可以通过插件配置指定 bskPath。
先用公开页面做最小验收：
/browser-skill open example.com and summarize the page. 再将任务改为真实场景："打开测试站点，进入商品详情，记录加入购物车之前和之后的页面状态；遇到登录请求人工协助，不提交订单。"验收重点是导航、观察、交互及结果能否对应起来，而非只看 Agent 是否回复了"完成"。
会话边界与常见故障
插件实例只能操作自己拥有的会话，默认会话上限为 5，卸载实例时会停止所属会话。这能约束会话使用范围，但不是账号凭据隔离承诺；浏览器里实际登录了谁、可访问哪些数据，仍要单独考虑。
网页观察也需要节奏。点击后立即读取页面，拿到的可能仍是加载中的旧状态；按钮文字正确，也不代表业务请求已经成功。可以要求 Agent 在关键操作后等待明确的页面变化，再检查提示、网络结果或相关元素。等待条件应对应任务结果，不能把固定等待几秒当成所有网站通用的完成标准。
复现失败时，值得保存失败的那一次观察，而不是只保留最后成功的截图。例如，同一页面在窄窗口出现遮挡、宽窗口没有问题，窗口尺寸就是证据的一部分；相同按钮在不同登录状态下跳转不同，账号状态也是必要上下文。这些记录并不要求插件具备录制功能，Agent 可以按任务把观察结果整理出来。
如果只能调工具却看不到浏览器，先查扩展和 daemon 的连接；如果人工终端可用、DSH 不可用，优先查 PATH 或 bskPath；如果新能力表现不一致，比较 CLI、daemon、扩展和插件版本。它们分别升级，更新 npm 插件不会自动替你更新整条链路。
ModLens：为文本模型补一座视觉信息桥
图片到达了，不代表模型看到了
把截图贴进聊天框，界面出现缩略图，很容易让人误以为底层模型已经理解图片。对于纯文本模型，传入一段图片路径或者文件名，并不会凭空产生视觉能力。真正缺的是把像素内容转成模型能消费的信息。
ModLens 为这个问题提供视觉桥接。它调用可用的视觉引擎，将图片里的文字、布局、实体及关系转成结构化证据，再交给文本模型继续推理。报错截图、界面布局和图表说明是典型场景。
它不负责点击浏览器，也不是分析代码模块依赖的工具。截图从哪里来，可以是用户粘贴，也可以是其他工具产生；识别结果如何参与排查，则由 Agent 根据任务决定。这个职责边界直接决定了安装后应该测试什么。
总体架构：宿主入口、视觉桥接与模型后端
ModLens 的架构重点是把宿主接入与视觉服务选择分开。原生工具和 vision 模型入口面向 DSH；包内 CLI 与引擎配置负责接入可用的视觉能力；视觉后端和最终进行推理的文本后端则承担不同任务。下列模块是职责视图，不表示它们都是独立进程。
| 组成部分 | 所属边界 | 主要职责 |
|---|---|---|
| 原生工具与 vision 模型入口 | DSH 集成侧 | 为符合条件的会话提供图片读取或模型调用前的视觉转换入口 |
| 包内 CLI | ModLens 本地侧 | 承接图像读取工具的视觉调用；不据此假设所有接入入口都以同一方式启动 CLI |
| 共享引擎配置 | ModLens 的配置数据 | 保存后端选择及必要凭据，可跨宿主共享；配置文件不是执行模块 |
| 视觉后端 | 所配置的 API 或 CLI 后端 | 识别图片内容，提供文字、布局与语义等信息；使用本地 CLI 不自动等于离线推理 |
| 结构化结果 | 交付宿主的数据 | 作为工具 JSON 或模型调用前的证据，描述识别内容 |
| 文本后端 | 后续推理侧 | 消费证据并结合任务推理；不承担原始图片的视觉识别 |
两个接入入口解决的是不同的集成问题。原生 modlens_read_image 工具显式读取图片并返回结果；带有 (modlens vision) 标记的入口把转换放在文本模型调用之前。图片粘贴在符合条件的会话中可以经私有临时路径进入工具，但这不是对所有模型通用的接管机制。
配置边界与数据边界需要分别看。共享引擎配置不会因为切换 DSH profile 自动隔离；图片则可能越过本地边界发送到视觉服务，提取后的文字也可能进入文本服务。图中把两种后端分开，是为了区分识别与推理职责，不意味着两者一定由不同服务商部署。
图中的无箭头连线表示模块协作，不规定请求顺序。集成侧提交读取任务，本地桥接组织视觉调用，再把识别内容交回宿主使用。自动发现和包装受模型模态元数据等条件控制，不能由界面出现缩略图推断任意模型已经获得视觉能力。
结构化输出的价值，在于把 OCR、布局和语义拆开，使后续推理更容易定位依据。它也有边界：JSON 格式正确，只能证明结果能被解析，不能证明文字识别、元素关系和图表解释一定正确。
例如，截图里一个红色提示位于提交按钮上方，可靠输出应先记录可辨认文字和位置关系；"接口权限不足"则需要文字或日志支持，不能仅凭红色就下判断。对于坐标图，还应核对单位、坐标轴和图例。图形趋势看起来向上，不代表数值一定增长，反向坐标和双轴图都可能改变含义。
图片质量同样决定结果上限。压缩后的长截图可能让小字难以辨认，裁剪过窄又可能丢失标题、单位或上下文。必要时提供一张全景图加关键区域清晰图，既保留关系，也让细节可读。应让模型明确指出不能确认的区域，而不是要求它"尽可能给出完整答案"，迫使缺失信息被猜测补齐。
安装与后端配置
GitHub：ModLens；Harness 配置文档。
已核实的包版本为 3.26.1，Node 要求不低于 22.19.0。在目标 profile 中安装并启动：
dsh plugin --profile web add @liustack/modlens@3.26.1 dsh --pro、file web随后进入 Settings → Plugins → Plugin configuration → ModLens，配置可用的视觉引擎、接口地址、模型和必要凭据。也可按官方文档复用支持的本地 CLI。应明确究竟由哪个后端读取图片；所谓便捷接入，不代表图片识别必然离线、免费或无需凭据。
引擎设置保存在 ~/.modlens/config.json，可在不同宿主间共享，不是简单写进当前 profile 的 cordis.patch.yml。因此，更换 DSH profile 不等于得到完全独立的一套视觉服务配置，排障时也不要只盯着 DSH 插件列表。
第一次使用，选择符合条件的文本模型或相应的 vision 包装入口，粘贴一张不含敏感信息的界面截图，再提出有限任务：
读取截图，分别列出可辨认文字、主要区域及相对位置、明确可见的异常。看不清的字段标为不确定，不根据界面样式猜测后端错误；保留事实与推测的区别。
用原图逐项核对输出。只有基础识别可靠后，再让 Agent 结合日志和代码分析原因。若后端失败，应检查凭据、配额、网络和所选引擎；发生回退时，可结合结果中的 meta.attempts 判断实际调用过程，而不是仅凭最终出现一段文字就认定首选模型工作正常。
敏感图片可能被发送给视觉服务商。支付信息、客户资料和生产后台截图应按团队的数据规则处理。结构化文字也可能继续进入模型上下文，所以仅删除原图，并不意味着识别出的敏感字段已经消失。
把三种能力用在同一个排障任务里
假设商品详情页的按钮偶尔被遮挡。先用 BrowserSkill 在测试环境复现，记录页面地址、操作顺序和截图；需要文本模型分析图片时，再通过 ModLens 提取界面证据，并回看原图确认遮挡关系；确认组件、接口与状态变化后，才让 Archify 画出相关链路，解释修复为什么影响这个页面。
这是可以人工组织的工作方式，不是三个仓库承诺的自动联动功能。尤其要明确交接材料：浏览器里的页面状态不会自动成为永久证据，一张截图不能证明整个请求过程，架构图也不能反向证明线上行为。保存什么、传给谁、何时需要重新观察，都应该由任务来决定。
不必一次装满三个插件。经常卡在网页操作，优先打通 BrowserSkill；大量工作来自别人发来的截图，优先评估 ModLens；信息已经掌握，困难在评审和解释，则先试 Archify。每次验收一个明确结果，更容易判断收益来自哪里。
安装前，先检查当前 DSH 和 Node 版本，再确认目标 profile。包能下载、插件能加载、任务能完成，是三个不同阶段；只有第三阶段通过，才说明这套组合满足当前需求。升级时记录原版本和一项可重复的小任务，重新验收同样的输入输出，比依赖一次复杂对话的主观感受更稳妥。
成本也应按路径核算。Archify 的主要开销来自 Agent 分析与生成过程，BrowserSkill 增加本地组件的维护工作，ModLens 则可能增加视觉服务调用和图片处理开销。仓库热度不会替团队支付这些成本；能否减少一次人工交接、一次重复复现或一次架构误解，才是更贴近工作现场的判断标准。
团队采用时，还应把验收材料一起保存：BrowserSkill 记录复现动作与当时状态，ModLens 保留原图与不确定字段，Archify 保留规格和可阅读产物。记录版本及失败原因，能避免升级之后把兼容变化误判成模型退化。真正可复用的不是一句"这个插件很好用"，而是一条能重复得到结果的工作路径。
三种能力最终服务于同一件事：让结论有来处。浏览器把动作连接到状态，视觉桥接把图片连接到可用证据，架构表达把证据和系统关系连接到人的理解。Agent 的回答可以更流畅，但工程判断最需要的，仍然是能回头核对的事实。