@dsh-external/dsh-webrelay

② 把 .tgz 交给使用者，在其机器上执行（路径换成实际位置）

dsh plugin --profile web add /绝对路径/dsh-external-dsh-webrelay-0.1.0.tgz

③ 验证插件已进入配置层

dsh web --dump-config | grep webrelay

**成功判断依据**：第 ② 步以 `Done in …` 结束；第 ③ 步输出含 `dsh-webrelay` 条目。

**该 tarball 的实际内容**（pnpm 11.7.0 实测，共 9 项）：`lib/index.js` + `lib/client.js` 及各自 sourcemap、`sites.default.yml`、`cordis.patch.yml`、`package.json`、`README.md`、`LICENSE`——**不含 `src/`**。安装后 `lib/index.js` 可直接 import（导出 `apply`、`inject: ["webServer"]`、`name`），因为产物已预构建，整个安装过程不会请求构建脚本审批。

### 方式 B：从 npm registry 安装

前提：包已发布到 npm。**当前尚未发布**，且需要先拥有 `@dsh-external` 这个 scope。

```sh
dsh plugin --profile web add @dsh-external/dsh-webrelay

与方式 A 同理：registry tarball 同样自带 lib/，且 registry 安装不会触发 prepare 构建。

方式 C：从 GitHub 直接安装

dsh plugin --profile web add github:Baisbt/dsh-plugin-webrelay

⚠️ 这条路需要额外放行一次构建脚本。 仓库的 lib/ 被 .gitignore 排除，lib/ 是由 package.json 的 prepare: tsdown 在安装时现构建的；而 pnpm 11 默认拦截依赖的构建脚本（strictDepBuilds 默认 true）。因此首次执行会以 ERR_PNPM_IGNORED_BUILDS 失败，同时 pnpm 会把一个占位项写进 profile 的 pnpm-workspace.yaml：

$DSH_HOME/profiles/web/pnpm-workspace.yaml

把 pnpm 打印出来的那个 key 置为 true，再重跑同一条 add 命令即可：

allowBuilds:
  # 键名以 pnpm 实际打印的为准
  
: true

注意键的粒度：pnpm 11 不接受单独写包名来放行 git 来源的依赖，必须精确到解析出的 commit 路径；用仓库 URL 作键是 11.11.0 起才支持的能力。不想处理这一步就用方式 A。

本地开发（link 模式）

# 5. 验证插件已进入配置层
dsh web --dump-config | grep webrelay

### 第 4 步：初始化配置

**目的**：生成本地站点配置文件，供你按需调整。

**操作**：**无需手动操作**——首次运行时插件会自动把出厂默认 `sites.default.yml` 复制为 `$DSH_HOME/webrelay/sites.yml`。之后编辑用户文件即可：

```sh

## 配置说明

用户配置文件为 `$DSH_HOME/webrelay/sites.yml`（首次运行自动从 `sites.default.yml` 复制）。主要配置项：

### `sites.*`：站点定义

| 键 | 说明 |
|----|------|
| `name` | 展示名 |
| `home` | 内置浏览器打开的入口地址 |
| `match` | 站点识别与代理白名单域名（**同时是安全边界**，代理只转发白名单内站点） |
| `experimental` | `true` = 实验性适配（未端到端实测） |
| `hidden` | 从页签隐藏，但识别与代理仍生效 |
| `openIn` | 打开方式：`relay`（内置 iframe）/ `cdp`（专用联动浏览器）/ `system`（当前浏览器新标签页） |
| `browser` | 联动模式绑定的浏览器实例 id（`browsers` 表的键；`null` = 默认实例） |
| `adapter.*` | DOM 适配选择器，全部为**候选选择器链**，按序取第一个命中的元素 |

`adapter` 子项：`input`（对话输入框）、`inputContentEditable`（是否 contenteditable）、`send`（发送按钮候选，可空数组 → 用 Enter 发送）、`sendMode`（`enter` / `click` / `enter-then-click`）、`replies`（助手回复节点候选）、`generating`（生成中标记候选）。

> **站点改版时改这里即可，无需改代码。**

### `relay.*`：反向代理

- `stripHeaders`：从上游响应剥离的响应头（解除 iframe 嵌入与脚本限制）；
- `injectShim`：是否注入运行时 shim（改写 fetch/XHR/EventSource/WebSocket，使 SPA 的同源请求继续走代理）；
- `upstreamTimeoutMs`：单请求上游超时（默认 60000）。

### `optimize.*`：提示词优化与协作

| 键 | 默认 | 说明 |
|----|------|------|
| `provider` / `model` | `null` | 优化用模型；`null` = 自动（client 传入 → 配置 → 第一个可用 provider） |
| `temperature` / `maxTokens` | `0.4` / `4096` | 采样参数 |
| `reasoningEffort` | `off` | 思考链档位（`off` / `low` / `high` / `max`）；`off` 可避免推理 token 耗尽 `maxTokens` |
| `style` | `preserve` | `preserve` 贴着原文语气做小切口改写（结果自然）；`structured` 允许分节结构化重排 |
| `structureHint` | `null` | 追加给优化器的结构偏好（如「输出必须是 JSON schema」），**优先级高于 `style`** |
| `extractProvider` / `extractModel` | `null` | 外部回复二次提取（整理）专用模型；`null` = 沿用上面的设置 |
| `extractTemperature` | `0.2` | 整理温度（低于优化温度，倾向忠实还原） |
| `extractMaxTokens` | `8192` | 整理输出的 token 上限 |
| `relayTimeoutMs` | `120000` | 等待外部 AI 回复的上限（毫秒）；超时不判失败，弹窗可「继续等待」或「采用已抓内容」 |
| `contextLimit` | `40` | 上下文压缩读取的对话条数（越大背景越完整、token 消耗越高） |

### `capture.*`：捕获存档

- `dir`：存档目录；`null` = `$DSH_HOME/webrelay/captures`；
- `recentLimit`：面板历史默认展示条数（默认 30）。

### `cdp.*` / `browsers.*`：专用联动浏览器

- `cdp.port`（默认 9222，仅回环）/ `cdp.browserPath`（`null` = 自动探测 Chrome、Edge）/ `cdp.startupTimeoutMs` / `cdp.headless`（默认 `false`，日常使用建议关闭无头以便正常过站点风控）；
- `browsers`：联动浏览器实例表，每个实例 = 独立进程 + 独立调试端口 + 独立配置子目录。示例：

  ```yaml
  browsers:
    chrome-main: { label: Chrome 主号, type: chrome, profile: Default, port: 9222 }
    edge-work:   { label: Edge 工作号, type: edge, profile: "Profile 1", port: 9223 }

站点管理界面

面板头部「管理」按钮打开站点管理弹窗，配置文件路径显性展示，支持：

• 添加站点：填名称 + 网址即可（域名白名单与 id 自动提取，DOM 适配先用通用候选链，可后续改 YAML 收窄）；
• 排序：↑/↓ 调整页签顺序（写回 YAML，用户层条目优先展示）；
• 隐藏：从页签隐藏但识别与代理仍生效（可随时恢复显示）；
• 打开方式：三档循环切换 内置 / 联动 / 浏览器；
• 删除：自定义站点直接删除；出厂站点写入 deleted: 列表（可「重置」恢复）；
• 恢复全部默认：整份配置还原为出厂模板（含注释）。

注意：除「恢复全部默认」外，管理操作以结构化方式写回 YAML，文件中的手写注释会被覆盖。