# DESIGN.md — dsh-webrelay 产品设计

## 1. 一句话定位

dsh-webrelay 是 DeepSeek Harness (DSH) 的 Web 插件：在 DSH 界面右侧提供内置浏览器（同源中继嵌入外部 AI 对话网页），并在聊天输入框模型选择器左侧提供「闪电」按钮，一键完成 **提示词优化** 与 **把对话流上下文 + 优化提示词中继发送给外部 AI 并抓取回复存档**，让外部 AI 分担推理、DSH 会话直接引用结果，减少当前智能体的思考量。

## 2. 需求背景与目标

- 用户日常同时使用多个 AI 在线服务（DeepSeek、ChatGPT、豆包、通义千问、Gemini），频繁地复制粘贴上下文、切换窗口。
- 目标：
  1. 不离开 DSH 即可打开并操作外部 AI 网页；
  2. 用一个按钮把「当前 DSH 会话的背景 + 我想说的话」整理成高质量提示词，发给外部 AI；
  3. 外部 AI 的回复自动抓取并归档，可一键引用回 DSH，避免智能体重复推理相同内容。
- 非目标（本期不做）：绕过登录/验证码、多账号管理、绕过站点反爬的风控对抗、非 Web 端（桌面客户端）支持。

## 3. 用户与核心场景

主要用户：在 DSH Web UI（127.0.0.1:3080）工作的个人用户，已在外部 AI 站点拥有账号并在浏览器里登录过。

| # | 场景 | 流程 |
|---|------|------|
| S1 | 打开内置浏览器 | 点击输入框右侧的「显示器」小按钮 → 右侧滑出浏览器面板 → 站点页签（来自配置文件）→ 页面经 relay 代理同源显示 |
| S2 | 优化提示词（不发送） | 在 DSH 输入框写草稿 → 点 ⚡ → 「优化提示词」→ 弹窗流式显示优化结果（可编辑）→ [撤回] 关闭即弃 / [重新生成] / [插入输入框]（仅写入草稿，不发送） |
| S3 | 中继发送 | 点 ⚡ → 「发送到浏览器中的 AI」→ 插件整理对话流背景 + 草稿 → 优化 → 弹窗预览完整消息（可编辑，[撤回] [重新生成]）→ 确认「发送」→ 在内置浏览器识别到的站点对话框中自动填入并发送 → 等待生成结束 → 弹窗展示抓取到的回复（可编辑）→ [保存] / [插入输入框] / [复制] |
| S4 | 引用历史捕获 | 浏览器面板「捕获历史」列表 → 点击一条 → 查看 / 复制 / 插入 DSH 输入框；DSH 会话中智能体可通过 `webrelay_captures` 工具检索历史捕获 |

## 4. 功能需求清单

| 编号 | 需求 | 验收标准 |
|------|------|----------|
| F1 | 右侧内置浏览器 | 面板可开合、可拖拽宽度；iframe 经 `/dsh-webrelay/proxy/...` 同源加载外部站点 |
| F2 | 站点识别 | iframe 当前 URL 的域名匹配配置文件 `sites.*.match` 时，面板与闪电菜单显示「已识别：XX」；未识别时禁用中继发送并提示 |
| F3 | 闪电按钮 | 渲染在模型选择器左侧（`conversation.input.right` 槽）；点击弹出两项菜单：优化提示词 / 发送到浏览器 |
| F4 | 选项一：优化不发送 | 调用 DSH 宿主 LLM；结果仅在弹窗中展示（可编辑），提供 撤回 / 重新生成 / 插入输入框 三个动作；绝不自动发送 |
| F5 | 选项二：中继发送 | 完整流程 S3；弹窗确认前不触碰外部网页；发送后等待回复完成再抓取 |
| F6 | 撤回与重新生成 | 两个选项的弹窗都支持撤回（丢弃，不写不存）与重新生成（重新调用优化） |
| F7 | 回复抓取与保存 | 抓取文本经用户确认/编辑后保存为 Markdown 文件（`$DSH_HOME/webrelay/captures/`），面板历史可查看 |
| F8 | 智能体工具 | 注册 `webrelay_captures` 工具：列出 / 读取捕获，供会话智能体引用 |
| F9 | 配置化 | 五个站点的地址与 DOM 选择器全部在 `sites.yml`，用户可改；站点改版无需改代码 |
| F10 | 降级 | 站点嵌入失败（盾/登录墙/改版）时，面板提供「在系统浏览器打开」按钮 |

## 5. 边界与约束

- 遵守 DSH 官方插件机制（`dsh.bundle.patch` + `dsh.client`、`dsh plugin add/remove`、`dsh web --dump-config` 验证），不 patch 宿主源码，不覆盖其他插件占用的槽位。
- 兼容性：只使用 additive 槽位（`conversation.input.right`、`shell.overlay`），路由与样式全部 `dsh-webrelay-*` 命名空间隔离；卸载后宿主无残留。
- 安全：relay 代理仅监听回环、校验 Origin 同源、目标域名白名单（配置 `match`），不做通用开放代理；凭据不落盘（Cookie 仅内存 per-会话 jar）。
- 合规：自动向外部网站发送内容由用户确认触发；README 声明用户需遵守目标网站条款，风险自担。

## 6. 交互原型（文字版）

```
输入框工具行右侧（模型选择器左边）：
  [⚡] [🖥]   …   [deepseek-v4.1-flash Off ▾] [↑]

⚡ 菜单：
  ┌──────────────────────────────┐
  │ ✨ 优化提示词（不发送）         │
  │ ⚡ 整理上下文并发送到浏览器      │
  └──────────────────────────────┘

中继弹窗（选项二，确认前）：
  ┌─ 中继发送预览 ────────────────┐
  │ 目标：DeepSeek（chat.deepseek.com）│
  │ ┌──────────────────────────┐ │
  │ │ [对话流背景摘要]            │ │
  │ │ [优化后的提示词]  ← 可编辑   │ │
  │ └──────────────────────────┘ │
  │        [撤回] [重新生成] [发送] │
  └──────────────────────────────┘

捕获弹窗（发送后）：
  ┌─ 外部 AI 回复 ───────────────┐
  │ [抓取到的回复文本] ← 可编辑     │
  │   [保存] [插入输入框] [复制] [关闭] │
  └──────────────────────────────┘
```

## 7. 里程碑

| 里程碑 | 内容 | 状态 |
|--------|------|------|
| M0 | 文档 + 脚手架 + 构建安装验证链路 | 进行中 |
| M1 | 闪电按钮 + 浏览器面板 + relay 代理（DeepSeek 同源显示） | 待办 |
| M2 | 选项一：提示词优化 + 撤回/重新生成 | 待办 |
| M3 | 选项二全链路（DeepSeek 实测） | 待办 |
| M4 | ChatGPT 实测 + 三站实验性 + 智能体工具 + README | 待办 |