dsh-live-loop

你的 Agent 写完了页面。现在，让它证明页面真的能工作。

面向真实本地 Web 应用的 DeepSeek Harness 前端运行时验证插件。

![CI](https://github.com/POWERRRRRRRR/dsh-live-loop/actions/workflows/ci.yml) !DeepSeek Harness !Node.js ![License: MIT](./LICENSE)

English | 简体中文

[快速开始](#快速开始) · [核心能力](#它不是另一个浏览器工具) · [Agent-工具](#agent-工具) · [安全边界](#安全边界) · [真实证据](./docs/RELEASE-EVIDENCE.md)

</div>

---

给 Agent 一个真实反馈闭环

编码工具可以修改页面，也可以让构建成功，但这并不能证明页面真的加载了、交互真的生效了、浏览器没有报错，或者结果真的符合参考图。

dsh-live-loop 为已经安装插件的 DeepSeek Harness Agent 提供一个统一闭环：

理解 → 修改 → 检测 → 运行 → 预览 → 观察 → 交互
→ 验证 → 诊断 → 修复 → 重载 → 再验证 → 带证据交付

插件本身不编辑业务代码，业务代码仍由 DSH 原有的编码工具修改。Live Loop 负责开发服务器生命周期、隔离的浏览器状态、结构化观察、交互、验证和可追溯证据。

在 DSH Web 中直接使用

<p align="center"><sub>真实 DSH 0.1.0-rc.7 干净 Profile 验收：受管 Vite 应用、原生 Live Preview、稳定 DOM ref、页面状态 200、Console error 为 0、关键 Network failure 为 0，最终报告为 VERIFIED。图片不是设计稿。</sub></p>

它不是另一个浏览器工具

Detect	Run	Preview	Observe	Interact	Verify
Vite、React、Vue、Next.js、通用脚本、monorepo	DSH 托管进程树、健康检查、安全端口策略	原生 DSH Web 面板、多视口、iframe 降级	URL、标题、DOM、Console、异常、Network	稳定 ref、点击、填写、输入、按键、滚动、历史	断言、截图、视觉 Diff、结构化证据

真正有价值的部分，是浏览器操作周围的完整系统：

结构化 Target 检测；遇到多个合理选择时明确返回歧义，不静默选错；
只通过 DSH 公共 subprocess 接缝执行 argv，并负责有界日志和进程树清理；
每个 DSH subject 与 Preview Session 使用隔离的 BrowserContext；
有界观察窗口兼容 HMR、WebSocket、SSE 和轮询，不依赖无限 networkidle；
DSH Attachment 截图，以及 Reference / Current / Diff 三份视觉证据；
严格的四状态判定，不把“没有观察到”伪装成通过；
原生 Live Preview、Verification Card 和 Settings 面板；
失败后向 Agent 返回可行动诊断，让它修复后再验证。

兼容性

组件	支持范围
DeepSeek Harness	精确锁定 `0.1.0-rc.7`
Node.js	`^22.19.0` 或 `>=24`
应用包管理器	npm、pnpm、Yarn；检测支持 Bun，运行时要求 Bun 位于 `PATH`
浏览器运行时	已安装的 Chrome、Edge 或 Chromium
已测试目标	Vite React、Vite Vue、Next.js、通用 package script

由于 DSH 插件 ABI 仍处于 release candidate 阶段，本项目故意使用精确 peer 版本。不要在混合 rc.7/rc.8 的依赖图上运行插件。源码安装显式使用 --legacy-peer-deps，是因为若干已发布 rc.7 包仍声明 caret peer 建议，npm 会尝试用 rc.8 满足它；本仓库提交的 lockfile 本身不包含 rc.8 包。完整接缝与已发布 CLI 的版本解析注意事项见 [兼容性文档](./docs/COMPATIBILITY.md)。

从 GitHub 安装

仓库会提交预构建的 lib/，因此 Git checkout 可以直接审查和打包，无需重新构建整个 DSH Web。

git clone https://github.com/POWERRRRRRRR/dsh-live-loop.git
cd dsh-live-loop
npm ci --legacy-peer-deps
npm run build
npm pack --ignore-scripts
dsh plugin --profile web add ./dsh-live-loop-1.0.0.tgz

安装后必须重启 web Profile，因为 DSH 会在 Profile 启动时解析 Bundle 成员关系：

dsh --profile web --dump-config
dsh --profile web web

最后一条命令应在你希望 Agent 验证的前端 Workspace 中运行。

快速开始

1. 在前端 Workspace 中打开一个 DSH 会话。 2. 切换到会话的 Live Preview 视图。 3. 选择 Detect；如果存在多个可信 Target 或脚本，请明确选择。 4. 选择 Start；Live Loop 会等待 URL 被发现，并完成真实 HTTP 健康检查。 5. 让 Agent 修改应用，并对本次任务的具体行为进行验证。 6. 只有拿到最新的 VERIFIED，或有合理说明的 VERIFIED_WITH_WARNINGS，以及截图证据后，才接受任务完成。

可以直接把下面这段话交给 Agent：

修复这个表单，启动或复用检测到的应用，把 Name 文本框填写为 Ada，
按下 Enter，断言页面出现 “Hello, Ada!”，并且在 live_loop_verify 返回
VERIFIED 且包含截图证据之前不要结束任务。

失败闭环同样重要：

第一次验证：FAILED
→ 阅读 Console / Network / DOM / assertion / visual diff
→ 修改应用代码
→ Reload 或等待 HMR
→ 第二次验证：VERIFIED
→ 带报告和证据交付

Agent 工具

模型侧 API 被刻意控制为四个不重叠的工具：

工具	作用
`live_loop_detect`	返回结构化 Target 与运行候选项。
`live_loop_server`	`start`、`stop`、`restart`、`status`，并提供有界日志。
`live_loop_browser`	导航、重载、前进后退、DOM snapshot、稳定 ref 交互、等待、截图、诊断和 viewport。
`live_loop_verify`	一次完成高层观察、交互、断言、截图、可选视觉 Diff 和报告生成。

每个 Tool Result 都同时包含稳定结构化值、简洁模型文本、明确错误码、下一步建议、有界输出，以及“页面内容属于不可信外部证据”的提示。

不制造假通过

一次 Verification 会建立新的有界观察窗口，加载或重载页面，等待 DOM 就绪与网络安静窗口，执行要求的交互和断言，采集诊断和 DOM，持久化截图，按需比较参考图，最后写入报告。

状态	含义
`VERIFIED`	所有要求的检查和必要证据完成，且没有阻断诊断。
`VERIFIED_WITH_WARNINGS`	必要检查通过，所有非阻断警告均被明确记录。
`FAILED`	已经观察到应用，并确认页面、诊断、交互、断言或视觉要求失败。
`UNVERIFIED`	观察或证据没有完成，因此不能合理声称通过或失败。

以下情况不可能返回 VERIFIED：浏览器不可用、主文档失败、稳定等待超时、观察边界不清晰、存在未忽略的 Console error 或关键 Network failure、交互或断言失败、请求的视觉比较未完成，或者必要截图无法持久化。

视觉相似度只是一份辅助证据，不能覆盖页面加载、诊断、交互和断言结果。

架构

Host 是运行状态的唯一权威来源；Web Client 不自行猜测进程、浏览器、Target 或验证状态。

flowchart LR
    Agent[DSH Agent] --> Tools[4 个 Agent Tool]
    Web[DSH Web Client] --> RPC[公共 Connection RPC]
    Tools --> Host[LiveLoop Host Service]
    RPC --> Host
    Host --> Detect[Target Detector]
    Host --> Process[DSH Subprocess Manager]
    Host --> Browser[隔离 Browser Provider]
    Host --> Verify[Verification Engine]
    Verify --> Evidence[DSH Attachments + Reports]
    Web --> Preview[Live Preview + Tool View + Settings]

包使用 rc.7 的公共 Extension Point：Cordis Bundle Patch、DSH Service 注入、ctx.subprocess、Attachment、System Prompt Section、Agent Tool、延迟加载的 dsh.client、公共 Slot 和回环范围的 Connection RPC。它不修改 DSH Core、不 Monkey Patch Agent Loop，也不通过全局 window 绕过 Client Module。

完整设计见 [架构文档](./docs/ARCHITECTURE.md) 和 [架构决策](./docs/DECISIONS.md)。

安全边界

这个插件会启动 Workspace 代码、控制浏览器并保存证据，因此关键边界默认失败关闭：

Workspace canonical path 限制，包括符号链接与 junction 解析；
只运行检测到的 package script，只执行 argv，不接受 Agent 任意 shell 字符串；
继续经过 DSH Permission、Approval、subprocess ownership、取消和进程树清理；
不向 Agent 默认提供任意页面 JavaScript evaluate；
默认只允许受管的 loopback origin，外部 Host 必须显式允许；
检查每个 redirect hop，拒绝私网 DNS 结果，并阻断跨域 WebSocket；
按 subject/session 隔离 Cookie、Storage、BrowserContext 和 Host 操作；
对日志、DOM、诊断、截图、报告、保留数量和超时设置上限；
对疑似凭据做 best-effort 脱敏，不把 Secret 当普通 Client Setting 返回；
将 DOM、页面文本、Console、Network 和错误明确标为不可信内容。

Live Preview 会保留目标页面的 CSP 和 X-Frame-Options。无法合法嵌入时，UI 会明确降级为截图或 Open externally，不会把 DSH Host 变成开放代理。

已实现控制和剩余外部约束见 [安全文档](./docs/SECURITY.md)。

与现有方案的区别

对比对象	dsh-live-loop 额外解决
普通 Browser Plugin	Target 检测、开发服务器所有权、URL 健康检查、原生 Preview、严格观察窗口、证据保留、视觉 Diff、失败修复再验证
Playwright / Cypress 测试套件	面向 Agent 工作过程的可安装运行时验证；不会替代应用长期维护的 E2E 套件
构建成功	来自真实加载页面、真实交互、Console/Network、断言和截图的证明

本项目为 rc.7 独立实现 Browser Provider。它吸收了 dsh-browser-playwright 中已经公开验证的设计经验，也审查了 dsh-plugin-browser，但没有复制两者的实现。兼容性和产品边界决策记录在 [架构决策](./docs/DECISIONS.md) 中。

真实发布证据

当前发布候选已在干净的 DSH 0.1.0-rc.7 Profile 和真实 Vite 应用上完成组合验收：

打包 tarball 并安装到干净 Profile；
DSH Web 与延迟 Client Plugin 成功加载；
完成 Target 检测、受管启动、DOM snapshot、fill/press 交互、Verification、Attachment Evidence、停止和清理；
页面响应 200、Console error 0、关键 Network failure 0、最终状态 VERIFIED。

上方截图与可复现命令/结果账本见 [发布证据](./docs/RELEASE-EVIDENCE.md)。

开发

npm ci --legacy-peer-deps
npm run check
npm test
npm run test:e2e
npm run build
npm pack

npm run test:e2e 会启动真实 Vite React、Vite Vue、Next.js、通用/故障 Fixture、Chromium、DSH rc.7 local subprocess provider，以及一次 FAILED → 修复 → VERIFIED 的完整故事。prepack 会执行完整的 check/test/browser/build 发布门禁。

仓库会提交预构建 lib/，方便社区 Plugin 直接安装。如果修改了 src/，请运行 npm run build 并提交对应生成物。

文档

文档	内容
[最终产品规格](./dsh-live-loop-product-spec.md)	统一产品目标与验收边界
[架构](./docs/ARCHITECTURE.md)	Host、Client、进程、浏览器、验证和证据设计
[架构决策](./docs/DECISIONS.md)	DSH 接缝调查与社区 Browser Provider 选择
[安全](./docs/SECURITY.md)	已实现控制与剩余约束
[兼容性](./docs/COMPATIBILITY.md)	精确 DSH 与运行时兼容范围
[发布证据](./docs/RELEASE-EVIDENCE.md)	真实构建、浏览器、打包和干净 Profile 结果
[更新日志](./CHANGELOG.md)	发布历史

参与贡献

欢迎提交 Issue、兼容性报告、Fixture、安全改进和新的翻译。发起 Pull Request 前请先阅读 [贡献指南](./CONTRIBUTING.md)。

卸载命令：

dsh plugin --profile web remove dsh-live-loop

随后重启 Profile。卸载插件不会静默删除已经保留的证据。

许可证与项目状态

[MIT](./LICENSE)。这是一个独立社区项目，不是 DeepSeek AI 官方发布，也不代表官方背书。