真实 DSH 0.1.0-rc.7 干净 Profile 验收：受管 Vite 应用、原生 Live Preview、稳定 DOM ref、页面状态 200、Console error 为 0、关键 Network failure 为 0，最终报告为 VERIFIED。图片不是设计稿。
## 它不是另一个浏览器工具 | 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。 ```bash 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 成员关系： ```bash 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： ```text 修复这个表单，启动或复用检测到的应用，把 Name 文本框填写为 Ada， 按下 Enter，断言页面出现 “Hello, Ada!”，并且在 live_loop_verify 返回 VERIFIED 且包含截图证据之前不要结束任务。 ``` 失败闭环同样重要： ```text 第一次验证：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 或验证状态。 ```mermaid 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](https://github.com/ChenyuHeee/dsh-browser-playwright) 中已经公开验证的设计经验，也审查了 [dsh-plugin-browser](https://github.com/xu1132/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)。 ## 开发 ```bash 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)。 卸载命令： ```bash dsh plugin --profile web remove dsh-live-loop ``` 随后重启 Profile。卸载插件不会静默删除已经保留的证据。 ## 许可证与项目状态 [MIT](./LICENSE)。这是一个独立社区项目，不是 DeepSeek AI 官方发布，也不代表官方背书。