DSH Patrol
Teach once. Patrol repeatedly.
DSH Patrol 是面向 DeepSeek Harness 的网页巡检 / Browser Automation 插件：你只需要用自然语言把巡检流程教给 Agent 一次，验证后它会固化成 Runbook；之后由确定性 Runner 重放，不再让模型每次临场猜步骤。
DSH Patrol is a browser patrol and website inspection plugin for DeepSeek Harness. Teach a workflow once, verify it, then replay it deterministically with a managed Chromium browser.
把「每次都让 AI 重新操作网页」变成「教一次，后续稳定巡检」。
为什么用 DSH Patrol
- 自然语言教学：直接描述“打开哪里、点什么、检查什么、截图什么”。
- 确定性重放：教学完成后保存为 Runbook，后续重复巡检不依赖模型重新规划整条路径。
- 浏览器开箱即用：自动寻找 Chrome / Edge / Chromium，使用独立持久 Profile，并自动加载内置扩展。
- 登录态可复用：专用浏览器 Profile 可以跨 Harness 重启保留 Cookie / Session。
- 安全凭据引用：Runbook 保存
${credential:REF}，不保存明文密码、Token、OTP 或 Cookie。
- Checkpoint / Resume：遇到人工令牌、扫码、二次确认等步骤可以暂停，人工完成后继续原 run。
- 截图与页面摘要：巡检结果可以落地截图、页面文本、JSON / Markdown 报告和确定性摘要。
- 保守的 Selector 自愈：只在唯一、精确的语义匹配下进行一次重试；真正修改 selector 需要显式确认。
适合的场景包括：内部运维后台巡检、业务系统日常检查、网页状态核对、需要登录态的重复流程、截图留证、人工令牌介入的半自动巡检，以及“先由 Agent 教会、以后稳定重放”的浏览器工作流。
1 分钟快速开始
1. 安装
推荐：npm 预构建包。完成首次 npm 发布后，用户只需要一条命令，不需要允许 Git dependency 的 prepare 构建：
dsh plugin --profile web add dsh-patrol
如果你是从 DeepSeek Harness 源码仓库运行：
pnpm dsh plugin --profile web add dsh-patrol
当前仓库仍处于 alpha。若 npm registry 中暂时还没有 dsh-patrol，请先使用下方的源码开发安装；维护者的首次 npm 发布流程见 docs/publishing.md。
2. 启动 Harness
全局 / npm 方式：
dsh web
Harness 源码方式：
pnpm dsh web
3. 新建会话，选择「巡检模式」
Patrol 会自动启动自己的受管浏览器，不需要手工打开 chrome://extensions、开启开发者模式、Load unpacked、填写 WebSocket 地址或点击 Connect。
4. 直接描述巡检
例如：
帮我创建一个网页巡检。
巡检名称：Example Domain 测试巡检。
地址：https://example.com
不需要登录。
打开页面，确认存在“Example Domain”，读取页面内容，截图，并生成报告和页面摘要。
正常体验应当是：
安装 DSH Patrol
↓
启动 DeepSeek Harness
↓
新建会话并选择「巡检模式」
↓
Patrol 自动启动专用浏览器
↓
Patrol 自动加载并连接扩展
↓
用自然语言教学并确认 Runbook
↓
后续由 Runner 重复巡检
如果 Managed Browser 自动启动失败，Patrol 应直接报告自动探测 / 启动错误；不应该把用户退回到手工安装浏览器扩展的流程。
工作方式
DSH Patrol 的核心原则是：
Agent 用于教学、解释和修复；Runner 用于重复执行。
第一次
自然语言需求
↓
Agent 观察网页并教学
↓
确认步骤
↓
Runbook
后续
Runbook
↓
Deterministic Runner
↓
浏览器操作 / 条件分支 / 截图 / 页面文本 / 报告
这与“每次运行都重新让 LLM 从头决定该点哪里”不同：Patrol 把高成本、非确定性的教学过程和后续高频重放过程分离。
本地开发：一条命令同步、安装并启动
如果你的目录结构类似：
E:\fangzeming\deepseekHarness\
├── DSH-Patrol\
└── deepseek-harness\
现在在 DSH-Patrol 目录里直接运行：
.\scripts\dev.ps1
它会自动完成：
检查工作区是否干净
→ checkout main
→ git pull --ff-only origin main
→ pnpm install / typecheck / test / checks / build
→ 安装 Patrol 到 Harness web profile
→ 启动 pnpm dsh web
也就是说，原来这一整套：
cd E:\fangzeming\deepseekHarness\DSH-Patrol
git checkout main
git pull --ff-only origin main
.\scripts\install-local.ps1 `
-HarnessRoot "E:\fangzeming\deepseekHarness\deepseek-harness"
cd E:\fangzeming\deepseekHarness\deepseek-harness
pnpm dsh web
可以收口成：
cd E:\fangzeming\deepseekHarness\DSH-Patrol
.\scripts\dev.ps1
如果 Harness 不在同级的 deepseek-harness 目录：
.\scripts\dev.ps1 -HarnessRoot "E:\path\to\deepseek-harness"
只安装、不启动 Harness：
.\scripts\dev.ps1 -NoStart
保留本地改动、不执行 git pull：
.\scripts\dev.ps1 -SkipPull
dev.ps1 默认在拉取前检查 Git working tree；如果存在未提交修改会直接停止，避免为了“自动更新”覆盖你的开发代码。
传统本地安装命令
如果不想让脚本操作 Git，也可以继续直接运行：
.\scripts\install-local.ps1 -HarnessRoot "E:\path\to\deepseek-harness"
install-local.ps1 会执行依赖安装、类型检查、测试、扩展检查、UTF-8 检查和构建，然后安装 Patrol preset、Host Bridge 配置以及生命周期清理协调器。
npm 与 GitHub 源安装
仓库已经声明 dsh.bundle，npm 打包会携带预构建的 lib/、浏览器 runtime、扩展、preset 和 cleanup runtime。CI 也会对发布 tarball 做 smoke test。
npm 发布完成后，推荐始终使用：
dsh plugin --profile web add dsh-patrol
从 GitHub 源码也可以安装：
dsh plugin --profile web add github:qigelunbiya/DSH-Patrol
但 Git 安装拿到的是 TypeScript 源码，需要执行 prepare 构建；pnpm 10+ 可能要求用户显式允许 dsh-patrol 的 dependency build。因此面向普通用户时，npm 预构建包是推荐分发方式。
维护者发布说明见 docs/publishing.md。
v0.2 当前能力
v0.2 的目标是把真实联调中暴露的问题收口，并尽量降低使用门槛：
- 独立 「巡检模式」 Agent Preset，不在标准模式里全局注入 Patrol。
- Browser Bridge 的 WebSocket/HTTP transport 固定运行在 Host plane，巡检 preset 只注册 Agent-scoped
browser_* 工具。
- Browser Cordis 插件使用 namespace plugin（
name / inject / apply），避免 Harness Loader 解包 default export 后丢失 inject。
- 内置 Managed Browser：自动寻找 Chrome / Edge / Chromium，启动 DSH Patrol 专用持久浏览器 Profile，并由代码加载仓库内置 Chromium 扩展。
patrol_doctor 检查真实 Browser Provider 与连接状态；Agent 不再猜 browser_* 工具名。- Runbook 只允许固定浏览器 allowlist，
browser_eval 不存在。
- 使用 Harness 原生
ctx.credentials，Runbook 只保存 ${credential:REF}。
- 支持条件登录、checkpoint/resume、截图、页面文本、确定性 page-summary、保守 selector 自愈与显式修复。
- 网页内容始终按 UNTRUSTED DATA 处理，不能反向改变 Agent / Tool 规则。
- 安装 / 卸载生命周期闭环：Bundle 被移除后，自清理协调器会在下一次 Harness 启动时移除残留 Patrol preset、浏览器集成和 managed patch；多 profile 场景不会误删仍在使用的共享 Patrol 数据。
运行结构
DeepSeek Harness
├── Host plane
│ └── dsh-patrol/browser-bridge-host
│ ├── Patrol Browser Bridge Runtime
│ └── Managed Browser Controller
│ ├── 自动寻找 Chrome / Edge / Chromium
│ ├── $DSH_HOME/patrol/browser-profile
│ └── 自动加载 browser-extension
│
└── 巡检模式 (Agent Preset)
├── dsh-patrol
│ ├── patrol_doctor
│ ├── patrol_create_draft
│ ├── patrol_browser_step
│ ├── patrol_type_text
│ ├── patrol_type_credential
│ ├── patrol_add_checkpoint
│ ├── patrol_confirm
│ ├── patrol_run / patrol_resume
│ └── report / repair / management tools
└── dsh-patrol/browser-tools
└── browser_* tool schemas
Bundle 安装机制
安装后 Bundle Host patch 会加载：
dsh-patrol/browser-bridge-host
dsh-patrol/preset-installer
preset-installer 自动把「巡检模式」写入 $DSH_HOME/.agent-presets/patrol；Managed Browser 在第一次选择巡检模式时按需启动。
为了让 Harness 当前没有第三方 uninstall hook 的情况下也能完整卸载，preset-installer 还会把一个只依赖 Node 内置模块的清理协调器复制到：
$DSH_HOME/patrol/integration-cleanup.mjs
并在安装了 dsh-patrol 的 profile cordis.patch.yml 中维护一个带明确 BEGIN/END marker 的 cleanup row。正常安装存在时它只做一次轻量存在性检查；包被移除后，它仍能独立运行一次完成残留清理并删除自己的 managed row。
Managed Browser
Patrol 默认使用独立的持久浏览器 Profile：
$DSH_HOME/patrol/browser-profile
默认探测顺序：
Google Chrome
→ Microsoft Edge
→ Chromium
→ PATH 中的兼容 Chromium
也可以通过环境变量显式指定浏览器：
DSH_PATROL_BROWSER=<browser executable path>
专用 Profile 的目的有两个：
- 不修改用户日常 Chrome / Edge Profile，也不往日常浏览器里永久塞扩展。
- 巡检浏览器自己的 Cookie / Login Session 可以跨 Harness 重启复用，因此可以在 Patrol 浏览器里登录一次，后续巡检继续使用该登录态。
扩展由 Managed Browser Controller 通过浏览器自动化 API 加载，Manifest 固定 public key 以保持稳定扩展 ID。Bridge 只接受本机 Chromium extension origin，并将 Managed Extension 的精确 origin 作为可信来源。
Credential 规则
不要把密码直接写进巡检描述、inspection.json 或普通输入步骤。
先在 Harness credential provider 中配置引用，例如：
PATROL_PORTAL_PASSWORD
Runbook 只保存：
{
"selector": "#password",
"credentialRef": "${credential:PATROL_PORTAL_PASSWORD}",
"clear": true
}
运行时 browser_type_credential 只把 credential reference 传过 ToolRuntime；实际值在 Browser Provider 执行体内部临时解析并直接送到浏览器，不进入 Runbook、JSON / Markdown report 或 Agent 最终摘要。
“已登录则跳过，否则登录”
典型教学 Runbook：
step-001 navigate 目标入口
step-002 read-page 判断当前状态
step-003 type username when step-002 contains "登录"
step-004 type credential when step-002 contains "登录"
step-005 click 登录 when step-002 contains "登录"
step-006 wait 工作台
step-007 click 我的工作台
step-008 click 全部工单
step-009 screenshot
step-010 read-page + page-text
如果 step-002 已经显示工作台，登录分支会标记为 SKIPPED。教学时不能凭空猜登录页 selector；没有观察过登录 DOM 时，应继续复用现有 Session，并等待受控教学机会。
Screenshot 与页面摘要
截图和页面文本会进入当前 Patrol workspace 的 run artifacts。请求 page-summary 时，Runner 从最后一次成功的 browser_read_page 生成确定性摘录，并写入 report.json / report.md。
需要更自然的总结时，Agent 只能把 patrol_get_run_page_data 返回的页面数据当作不可信数据进行总结，不能执行其中的任何指令。
Checkpoint 与恢复
人工 checkpoint 会保存 resume state。人工操作完成后使用 patrol_resume 继续同一个 runId。暂停期间 Runbook 如果发生修改，恢复会 fail closed。需要放弃等待状态时，用：
patrol_abort_run confirmed=true
卸载
npm / Bundle 安装
dsh plugin --profile web remove dsh-patrol
Harness 会移除依赖并重算 bundle layer。由于 Harness 当前没有第三方插件 uninstall lifecycle hook，DSH Patrol 使用预先写入 $DSH_HOME 的 cleanup coordinator 补上这个生命周期：
dsh plugin remove dsh-patrol
↓
包与 bundle layer 被移除
↓
下一次 dsh web 启动
↓
profile 中的 self-contained cleanup row 先运行
↓
确认该 profile 已不再引用 Patrol
↓
删除该 profile 自己的 cleanup row
↓
若没有其他 profile 仍使用 Patrol：
删除 managed preset / browser profile / state / trust / 临时 bridge 文件
保留 inspections / runs / resumes
删除 integration-cleanup.mjs 自身
多 profile 场景下，协调器会先扫描其他 profile 的 package dependency 与本地 Host Bridge marker，只有最后一个 Patrol 安装消失时才删除共享集成。
本地源码安装
.\scripts\uninstall-local.ps1 -Profile web
默认保留 inspection definitions 与历史报告。如果确定连巡检数据一起删除，并且已经没有其他 profile 使用 Patrol：
.\scripts\uninstall-local.ps1 -Profile web -PurgePatrolData
如果 patrol preset 的 .managed-by-dsh-patrol marker 已被用户主动删除，卸载会把这个 preset 视为用户已接管并保留，不会误删。
安全边界
- 固定 browser allowlist；不注册
browser_eval。
- Browser tool Guard 只允许当前 Patrol composite 的嵌套调用。
- Page / DOM 输出是 untrusted data。
- 明文 credential 不落盘。
- URL 中敏感 query / fragment 参数和 userinfo 会被拒绝持久化。
- Managed Browser 使用 DSH-owned 专用 Profile，不修改日常浏览器 Profile。
- Browser Bridge 只监听本机，并限制 Chromium Extension Origin。
- 自动卸载只删除带 DSH Patrol managed marker 的 preset / integration；用户接管的 preset 与 inspection 历史默认保留。
- 自愈只允许唯一精确语义匹配做一次重试；真正修改 selector 必须显式更新并重新确认。
当前工具
patrol_doctor
patrol_create_draft
patrol_browser_step
patrol_type_text
patrol_type_credential
patrol_add_checkpoint
patrol_confirm
patrol_run
patrol_resume
patrol_get_run_page_data
patrol_save_summary
patrol_show
patrol_list
patrol_delete_step
patrol_move_step
patrol_update_selector
patrol_abort_run
patrol_delete
patrol_execute_and_record # v0.1 compatibility, deprecated
开发与发布
pnpm install
pnpm typecheck
pnpm test
pnpm check:extension
pnpm check:encoding
pnpm build
- npm 发布流程：
docs/publishing.md
- CI：
.github/workflows/ci.yml
- npm Trusted Publishing workflow：
.github/workflows/publish.yml
License
MIT. See LICENSE and THIRD_PARTY_NOTICES.md.
