dsh-web-recorder

dsh plugin --profile web add dsh-web-recorder

dsh-web-recorder

<p align="center">

<a href="https://www.npmjs.com/package/dsh-web-recorder"><img alt="npm" src="https://img.shields.io/npm/v/dsh-web-recorder?label=npm&color=cb3837"></a>

<a href="https://www.npmjs.com/package/dsh-web-recorder"><img alt="downloads" src="https://img.shields.io/npm/dm/dsh-web-recorder?label=downloads&color=brightgreen"></a>

<a href="https://github.com/kakajun/dsh-web-recorder/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/kakajun/dsh-web-recorder/actions/workflows/ci.yml/badge.svg"></a>

<a href="https://github.com/kakajun/dsh-web-recorder/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/kakajun/dsh-web-recorder?style=social"></a>

<a href="https://github.com/kakajun/dsh-web-recorder/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/kakajun/dsh-web-recorder?label=License&color=yellow"></a>

<a href="https://dshfind.com/en/plugins/kakajun/dsh-web-recorder?ref=badge"><img alt="dshfind" src="https://dshfind.com/api/badge/kakajun/dsh-web-recorder"></a>

</p>

语言：简体中文 · [English](README_EN.md)

宿主版本要求：本插件适配 @deepseek-ai/dsh ^0.2.1-rc.2（依赖其 @deepseek-ai/dsh-tools@0.2.1-rc.2），即 profile 的 package.json 需满足 "@deepseek-ai/dsh": "^0.2.1-rc.2"。

网页操作录制器插件：面向「用户手动操作浏览器，插件在后台录制」的场景。它可以 attach 到已打开的浏览器窗口（如带调试端口的 Playwright MCP 浏览器，这个是可选的），也可以自己启动一个有头浏览器窗口（默认本机 Edge）；用户在窗口里正常点网页，插件在后台记录每次点击 / 输入 / 表单提交和每个网络请求 / 响应 / 失败，停止后生成 Markdown 摘要报告。

设计初衷

要让 agent 直接通过接口对接某个业务平台（例如 EIP 类系统），前提是先搞清楚三件事：平台暴露了哪些接口、每个业务步骤对应调用哪个、参数和响应是什么格式。传统做法是查接口文档或逆向前端代码，但文档往往缺失或过时，而且就算有了接口清单，也很难把「用户在页面上的业务操作」和「背后触发的接口调用」一一对上。

本插件换一种思路：不逆向，只留操作依据。开发者先让记录仪就位（recorder_start），再让目标业务流程在一个受监控的有头浏览器窗口里完整跑一遍即可——操作可以由真人手动完成，也可以交给 playwright MCP / browser-use 等浏览器自动化工具按步骤驱动——之后不需要再翻文档，因为这次操作留下的原始数据已经回答了上面三个问题：

• UI 事件线：每一步点击 / 输入 / 表单提交发生在何时、落在哪个元素、填了什么值；
• 网络事件线：每一步操作触发了哪些 xhr/fetch 请求——method、URL、请求头、请求体、响应体、失败原因。

两类事件按时间交错实时写入 events.jsonl，两条线天然对齐：任何一个业务步骤，都能在原始数据里找到「它调了哪个接口、参数怎么填、返回了什么」。停止后生成的 report.md 再把这套操作时间线与请求明细整理成便于阅读的摘要。

得到这些原始依据后，交给大模型做分析：归纳出完整的「业务流程 × 接口调用序列 × 数据契约」，再沉淀为 skill——把流程拆成步骤，注明每步该调哪个接口、请求 / 响应长什么样、出错怎么办——让 agent 之后照着 skill 直接走接口完成任务，整个过程不再依赖人工演示。

一句话概括：页面操作一遍 = 留下可分析的操作依据 = 大模型据此制作接口级 skill 的原料。录制本身只是采集，分析和沉淀交给模型完成。

效果预览

下面是一次真实录制的产物截图（tests/smoke.mjs 冒烟测试在一个本地页面执行「输入关键词 → 查询 → 去第二页」的完整流程）。

① report.md 摘要——统计概览 + 操作时间线 + 网络请求明细，把「业务步骤」和「接口调用」整理在同一张表里：

② events.jsonl 原始事件流——每一行一个事件（导航 / 点击 / 输入 / 请求 / 响应…），按发生时间交错实时落盘，是分析时最完整的操作依据：

两张图对照着看：一次「输入关键词并查询」的操作，在 events.jsonl 里留下了对应的 POST /api/query 请求与 200 响应事件，在 report.md 里则汇总成一行请求明细——这正是设计初衷里「页面操作一遍，留下可分析的操作依据」的直观体现。

🚀 安装

前置：已装好 DSH（dsh web 能正常运行，@deepseek-ai/dsh 需为 ^0.2.1-rc.2），Node.js ≥ 18、pnpm ≥ 8。

dsh plugin --profile web add dsh-web-recorder@latest

装完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可在 DSH 会话工具列表里看到 recorder_* 工具（DSH 对 client 改动热加载，无需重启；仅 host 半更新时需要重启）。

让 DSH 自己装——把下面这段提示词发给任意一个 DSH 会话：

帮我安装 dsh-web-recorder 插件（网页操作录制器），步骤：
1. 执行 dsh plugin --profile web add dsh-web-recorder@latest
2. 完成后提醒我硬刷新浏览器（Cmd/Ctrl+Shift+R）

<details>

<summary><b>更新</b></summary>

dsh plugin --profile web add dsh-web-recorder@latest

更新完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可生效。

</details>

<details>

<summary><b>常见问题</b></summary>

现象 · 原因与解决

报 Ignored build scripts · pnpm 拦截了构建脚本。在 profile 目录（~/.dsh/profiles/web）跑 pnpm approve-builds --all。

报「找不到 profile 目录」 · 先跑一次 dsh web，让它初始化 ~/.dsh/profiles/web。

提示 dsh: command not found · 先安装 DSH；或直接用 npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-web-recorder@latest。

</details>

<details>

<summary><b>从源码安装 / 开发（可选）</b></summary>

调试本地改动时，把依赖指向本地克隆并自行构建：

1. git clone https://github.com/kakajun/dsh-web-recorder.git ~/Code/dsh-web-recorder
   cd ~/Code/dsh-web-recorder && pnpm install && pnpm build
2. ~/.dsh/profiles/web/package.json 的 dependencies 写 "dsh-web-recorder": "link:<克隆目录绝对路径>"
3. 在 ~/.dsh/profiles/web 执行 pnpm install
4. 硬刷新浏览器（Cmd/Ctrl+Shift+R）即可生效

更新：git pull && pnpm install && pnpm build → 硬刷新浏览器即可。

</details>

注册的工具

工具 · 说明

recorder_start(url?, waitSeconds?) · 开始录制：优先 attach 到已有浏览器窗口（cdpUrl / 自动发现本机任何开了调试端口的 Chromium，Playwright MCP 优先），否则启动有头浏览器并可导航到起始 URL。自启窗口自带 CDP 调试端口并在返回里给出 cdpUrl，驱动方可直接连上来接管这个窗口。waitSeconds 可让录制先等 N 秒再记录（跳过登录 / 初始化）；事件实时落盘 events.jsonl。返回时会把本次录制登记为后台任务并返回 jobId

recorder_stop() · 停止录制：生成 report.md 摘要报告；attach 模式只断开录制连接、不关闭外部浏览器，插件自启的窗口才关闭；幂等

recorder_status() · 查询状态：是否在录制、事件分类计数、产物目录、本次录制窗口的 CDP 地址、jobId、上一次收尾结果

用户直接关掉浏览器窗口会自动收尾（reason: browser-closed），已录数据不丢。

录制结束会主动把模型接回来：recorder_start 同时把本次录制登记为宿主的后台任务（ctx.jobs，<jobId> 形如 recorder-1，归属发起调用的 agent）。用户操作完直接关掉浏览器（或调用 recorder_stop）时任务结算，模型在会话内收到完成通知——空闲时被唤醒开新的一轮，繁忙时注入下一步——随后即可用 job_output 取回产物路径与统计并接着总结，不必轮询 recorder_status。宿主未加载后台任务能力（dsh-jobs / dsh-tool-jobs）时自动退化为原行为（无 jobId，仍需 recorder_stop 或用户一句话把结果交给模型）。

使用方法:如何命中本插件

什么时候会命中（触发场景）

插件的 3 个工具会随插件启用出现在 DSH 会话的工具列表里，「命中」发生在模型做工具选择时——依据是工具名与描述。当用户任务属于「查清某个网页业务流程背后调用了哪些接口、参数/响应长什么样，并据此生成接口级流程说明或 skill」时，模型应主动调用 recorder_*。这类任务通常要分步完成：先打开目标页面开始录制，再由驱动方（真人或自动化工具）在页面上完成实际操作，最后基于录制结果分析沉淀。典型任务表述：

• "帮我打开 http://目标地址，开始录制"
• "打开 XX 页面，我操作一遍，你录下来再分析接口调用"
• "我在页面上点『查询』时发了什么请求？帮我录下来看看"
• "打开 http://目标地址，先等我 30 秒，然后再开始录"

如果只是回答不涉及真实页面操作的问题（例如直接查文档就能答），模型通常不会命中本插件。

工具如何可用（加载）

本仓库即 DSH 插件：入口 lib/index.js（源码 src/index.ts），经 `package.json

…(truncated)