# dsh-live-loop 最终产品定义

## 唯一目标

> **dsh-live-loop 是 DeepSeek Harness 的前端运行时验证系统。它使 Agent 能够启动真实应用、观察真实页面、执行真实交互、比较视觉结果、生成可追溯证据，并在验证失败后继续修改和重新验证，直到通过或明确报告无法验证。**

本项目不设置阶段性产品边界。本文定义的是同一个可安装社区插件必须完成的整体能力与验收标准。

## 要解决的问题

DSH Agent 已经能读取和修改前端代码，但以下结论都不能证明页面实际正确：

- 代码看起来合理；
- TypeScript 或构建通过；
- 开发服务器打印了 URL；
- 端口正在监听；
- iframe 出现了内容；
- Agent 截了一张图但没有清晰的观察窗口和断言。

Live Loop 将开发过程闭合为：

```text
Understand → Edit → Detect → Run → Preview → Observe → Interact
→ Verify → Diagnose → Fix → Reload → Re-verify → Deliver with evidence
```

业务代码仍由 DSH 现有编码工具修改。插件只负责运行环境、浏览器、观察、交互、验证、证据、诊断和闭环行为提示。

## 产品边界

目标是现代 Web 前端的自主验证闭环，覆盖 Vite、React、Vue、Next.js、通用 package script、npm/pnpm/Yarn、常见 monorepo 子目录和 Chromium。

产品不宣称替代仓库自己的 Playwright/Cypress 测试套件，也不覆盖 Lighthouse、多浏览器矩阵、原生应用、视频录制或任意互联网浏览。它不是通用反向代理，也不修改 DSH Core。

## 完整能力

### Detect

检测结果结构化返回 `targetId`、`framework`、`cwd`、`packageManager`、候选脚本、已选脚本、预期端口、置信度、选择理由和诊断。判断综合 manifest、依赖、脚本命令、锁文件、workspace 声明、框架文件和端口参数。存在合理歧义时由 Agent 或 Web UI 明确选择。

### Run

开发服务器通过 DSH `ctx.subprocess` 以 argv 启动。cwd 经过真实路径校验并限制在 Workspace 内；同一目标去重；日志、等待和清理有界；停止会等待完整进程树；卸载、Session 清理和 DSH 退出不遗留受管进程。端口冲突不会杀死陌生进程，只允许失败、明确采用健康的既有服务，或使用框架已知的安全端口参数。

### Preview

DSH Web 通过公开 Client Slot 加载 Live Preview。Host 是 Target、PID、URL、浏览器和验证状态的唯一权威来源。UI 提供 Target、命令、状态、URL、Desktop/Tablet/Mobile、Reload、Verify、Stop/Restart、外部打开、Console/Network 数量、最近报告、直接 iframe 或明确标记的截图回退。

### Observe

每个 DSH 主体拥有独立、随机的 Preview Session 和 BrowserContext，隔离 Cookie、Local Storage 与页面状态。观察包括 URL、title、DOMContentLoaded、主文档状态、Console error、uncaught exception、unhandled rejection、request failed、HTTP 4xx/5xx、DOM/可访问性摘要、白屏信号与截图。

### Interact

支持 snapshot、click、fill/type、press、scroll、navigate、back、forward、wait。默认使用可见节点和 generation-scoped ref，不要求模型猜 selector。新 snapshot 使旧 ref 失效；同名元素要求消歧；iframe/canvas 边界明确；操作后返回新摘要。Agent 不获得任意 `evaluate`。

### Verify

`live_loop_verify` 一次调用建立新的观察窗口，reload/navigate，执行有界稳定等待、可选交互、可选断言、Console/Network/DOM 收集、截图附件、可选视觉比较和报告持久化。

最终状态只有：

```text
VERIFIED | VERIFIED_WITH_WARNINGS | FAILED | UNVERIFIED
```

浏览器不可用、页面未加载、超时、主文档失败、白屏、未忽略 Console error、关键 Network failure、必要交互/断言失败、请求的 Diff 未完成、必要截图附件失败或观察窗口不明确，都不能返回 `VERIFIED`。

### Evidence 与 Visual Diff

证据包含 `evidenceId`、`previewSessionId`、`verificationId`、URL、viewport、时间、DSH screenshot attachment、Console/Network 摘要、交互/断言、视觉结果与本地报告。Reference 模式产生可查看的 Reference、Current、Diff 三个附件和尺寸/差异/相似度/阈值。视觉指标只作辅助证据，不能覆盖功能失败。

### Diagnose / Fix / Re-verify

Tool description、System Prompt section、结构化错误和 next action 共同指导 Agent：先读取失败诊断，修改业务代码，再 reload/verify，而不是盲目重复截图。rc.7 公开 API 能实现的是软行为指导，不是不可绕过的 Agent Loop 门禁；文档和 UI 不把它描述成硬门禁。

## DSH 集成约束

目标版本是 `0.1.0-rc.7`。Host 使用公开的 `ctx.tools`、`ctx.subprocess`、`ctx.attachments`、`ctx.systemPrompt.section`、Settings 与 Connection RPC。Client 以 `dsh.client` lazy CJS artifact 加载，并贡献 `conversation.view`、`tool.call.toolview` 和 `settings.section`。

rc.7 没有适合树外插件追加任意内容的通用 `details` 列表入口，因此不替换单所有者 details surface；Live Preview 使用公开且可安装的 `conversation.view`。这是一项经源码核实的兼容性选择，不是通过 Core 修改或全局运行时导入绕过。

## 安全不变量

- 不接受任意 shell、cwd、环境变量或页面 JavaScript；
- HTTP 顶层导航只允许受管回环 origin；
- CDP Request-stage 在发送前检查每个 HTTP 请求和重定向跳；
- 外部 Host 默认拒绝，显式 allowlist 仍需 DNS 公网结果且 DNS 超时失败关闭；
- 跨 origin WebSocket 拒绝，同 origin HMR 保留；
- BrowserContext 隔离，Service Worker/WebRTC/WebTransport 关闭；
- RPC、Preview、Evidence 和进程操作检查 Session/Preview 所有权；
- 日志、DOM、诊断、图片、报告、保留数量均有上限；
- 凭据型文本尽力脱敏，不采集响应 body；
- 页面产生的所有文字均是不可信外部内容，不是系统指令；
- 副作用经 DSH Tool/Permission/Approval 路径执行，Client 不直接启动进程。

## 单次最终验收

最终产品必须同时满足：

- 产品文档只定义上述一个目标；
- Detect / Run / Preview / Observe / Interact / Verify 全部真实可用；
- Console、Network、DOM、Screenshot attachment、Reference/Current/Diff 可追溯；
- Verify 不产生已知假 PASS；
- 生命周期、并发、取消、超时、边界和清理有实现与测试；
- Host/Client 只使用目标 DSH 版本公开接缝；
- 单元、真实框架集成、故障矩阵、失败修复闭环全部通过；
- 构建产物可以 pack、安装到干净 DSH Profile、加载真实 DSH Web Client；
- README、配置、兼容性、安全、社区方案关系和发布元数据完整。