@tnnevol/dsh-midscene 0.2.0-rc.2.5 → 0.2.0-rc.2.6

package/README.md

@@ -7,7 +7,7 @@
 ## 安装
 
 ```sh
-dsh plugin --profile web add @tnnevol/dsh-midscene@0.2.0-rc.2.5
+dsh plugin --profile web add @tnnevol/dsh-midscene@0.2.0-rc.2.6
 ```
 
 安装后重启 DSH Web profile。

package/compatibility.json

@@ -14,6 +14,7 @@
       "@deepseek-ai/dsh-client-ui-slots",
       "@deepseek-ai/dsh-host-webserver",
       "@deepseek-ai/dsh-llm",
+      "@deepseek-ai/dsh-session",
       "@deepseek-ai/dsh-settings",
       "@deepseek-ai/dsh-skill",
       "@deepseek-ai/schemastery"

package/lib/client.js

@@ -42662,7 +42662,7 @@ onKeyDown: (e) => this.foundation._handleKeyDown(e) });
 			sectionTitle: "Midscene 接入设置",
 			sectionHint: "Midscene 通过本地桥接服务使用 DSH 已配置的模型，无需任何模型 API 密钥。",
 			apiKeyLabel: "接入密钥",
-			apiKeyHint: "桥接服务的接入密钥，不是模型密钥。重新生成后需要同步更新 Midscene 的 .env。",
+			apiKeyHint: "桥接服务的接入密钥，不是模型密钥。重新生成后需要同步更新下面的接入配置（命令行 .env 与浏览器扩展两处）。",
 			regenerate: "随机重新生成",
 			regenerating: "生成中…",
 			customKey: "自定义密钥",
@@ -42682,9 +42682,9 @@ onKeyDown: (e) => this.foundation._handleKeyDown(e) });
 			modelsUnavailable: "DSH 当前没有可用于 Midscene 的识图模型。请先在 DSH 中安装并登录一个提供方（模型需具备图片输入能力），然后回到本页重新加载。",
 			addModel: "添加模型",
 			removeModel: "移除",
-			envLabel: "Midscene .env",
-			envHint: "在运行 Midscene 的工作目录保存为 .env 即可；换模型不需要修改这里。",
-			envCopy: "复制 .env 内容",
+			envLabel: "接入配置（命令行 .env 或 Midscene 浏览器扩展）",
+			envHint: "两条路都用这四行：跑命令行时保存为工作目录的 .env；用 Chrome 里的 Midscene 扩展时，打开它的侧边栏设置把这段粘进去。模型跟随当前 DSH 会话，不需要任何第三方模型密钥。",
+			envCopy: "复制接入配置",
 			loading: "正在读取当前设置…",
 			loadFailed: "读取设置失败",
 			saveFailed: "保存失败",
@@ -42695,7 +42695,7 @@ onKeyDown: (e) => this.foundation._handleKeyDown(e) });
 			sectionTitle: "Midscene bridge settings",
 			sectionHint: "Midscene drives DSH-configured models through the local bridge — no model API key needed.",
 			apiKeyLabel: "Bridge access key",
-			apiKeyHint: "Access key for the bridge, not a model key. Regenerating requires updating the Midscene .env.",
+			apiKeyHint: "Access key for the bridge, not a model key. Regenerating requires updating the access config below (both the CLI .env and the browser extension).",
 			regenerate: "Regenerate",
 			regenerating: "Generating…",
 			customKey: "Custom key",
@@ -42715,9 +42715,9 @@ onKeyDown: (e) => this.foundation._handleKeyDown(e) });
 			modelsUnavailable: "DSH has no vision-capable model available for Midscene. Install and sign in to a provider in DSH first (the model needs image input), then reload this page.",
 			addModel: "Add model",
 			removeModel: "Remove",
-			envLabel: "Midscene .env",
-			envHint: "Save as .env in the directory where you run Midscene; changing models does not require editing it.",
-			envCopy: "Copy .env contents",
+			envLabel: "Access config (CLI .env or Midscene browser extension)",
+			envHint: "Both paths use these four lines: save them as .env in the directory where you run the CLI, or open the Midscene browser extension sidebar settings and paste them there. The model follows the current DSH session — no third-party model key is needed.",
+			envCopy: "Copy access config",
 			loading: "Reading current settings…",
 			loadFailed: "Failed to read settings",
 			saveFailed: "Failed to save",

package/lib/index.js

@@ -1,6 +1,7 @@
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { createServer } from "node:http";
+import { SessionId } from "@deepseek-ai/dsh-session";
 import { existsSync } from "node:fs";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
@@ -1296,6 +1297,18 @@ var BridgeServer = class {
 	#server;
 	/** 实际监听端口；启动成功前为 undefined。 */
 	#port;
+	/**
+	* 桥自身的会话标识，随每次请求下发给模型层。
+	*
+	* 部分提供方要求「按会话路由」的请求头（如 opencode 的 `x-opencode-session`），
+	* 而 DSH 正是从 `GenerateOptions.sessionId` 生成该头。桥原先不传这个字段，
+	* 于是**只要会话模型属于这类提供方，桥就整体不可用**（502 `MissingSessionID`）——
+	* 与「DSH 会话能正常请求的模型，桥也应该能正常发送」直接冲突。
+	*
+	* 取值稳定（每个桥实例一个）：既满足按会话路由的要求，也让支持提示缓存的
+	* 提供方拿到稳定的缓存键；不支持的提供方会忽略它，因此对所有提供方都安全。
+	*/
+	#sessionId = SessionId(randomUUID());
 	catalog;
 	/**
 	* @param deps - 运行依赖。
@@ -1594,6 +1607,7 @@ var BridgeServer = class {
 		const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
 		const stream = this.deps.llm.stream({
 			...options,
+			sessionId: this.#sessionId,
 			signal: controller.signal
 		});
 		try {
@@ -1690,9 +1704,20 @@ var BridgeServer = class {
 * Midscene 技能，无需另行执行技能安装命令。注册随 Cordis 效果注销：插件卸载
 * 或 HMR 时技能同步消失（AC-03）。
 *
-* **不写入用户技能目录**（需求行为约束）：技能只在注册表里存在，宿主自己的
-* 发现优先级负责共存——项目目录 > 用户目录 > 插件注册，因此用户自行安装的
-* 同名技能天然胜出（AC-04），插件不覆盖也不重复提示。
+* **不写入用户技能目录**（需求行为约束）：技能只在注册表里存在，由宿主自己的
+* 发现优先级负责共存，插件不往用户目录里写文件、也不重复提示。
+*
+* **同名冲突时插件保持最高优先级**（AC-04）：插件分发的是**本环境的权威版本**
+* ——包内技能带环境说明（模型由桥提供、不索要密钥），而用户目录里的同名副本
+* 通常是没有这段说明的上游原文。一旦被后者遮蔽，agent 就会不知道插件的作用，
+* 转而向用户索要模型密钥（实测事故：会话里 agent 翻了 9 步环境、最后仍让用户
+* 提供 `MIDSCENE_MODEL_API_KEY`）。因此候选统一用 `rank: 0`（数值最小者胜）。
+*
+* ⚠️ **层序优先于 rank**：宿主按 `[global, ...作用域链]` 逐层合并同名技能，
+* **后面的层直接覆盖前面的层**，rank 只在同一层内决定胜负。插件在 profile 启动时
+* 注册（global 层），而 `~/.agents/skills` 落在作用域链里（更靠后）——**这种情况
+* 下 rank 再小也赢不了**。所以另有一条兜底：插件自有的入口技能 `dsh-midscene`
+* 用**独占名字**，不参与任何同名冲突。
 */
 /** SkillProvider 在注册表里的名字。 */
 const SKILL_PROVIDER_NAME = "dsh-midscene";
@@ -1717,6 +1742,11 @@ const BRIDGE_PRELUDE = `> **本环境说明（由 DSH Midscene 插件注入，
 > - **不要向用户索要模型 API key，也不要引导用户去申请第三方模型。** 本文档中出现的服务商、
 >   模型与 key 示例仅作背景知识；实际使用哪个模型由桥决定。
 > - 需要浏览器桥接模式时同样走桥：Midscene 侧的模型配置始终是上面这四行。
+> - **浏览器交互用用户的主 Chrome**：走扩展桥接（\`--bridge\` / \`AgentOverChromeBridge\`），
+>   复用用户真实浏览器的登录态，而不是另起一个干净 profile。用户只需**一次性**把上面四行
+>   粘进 **Midscene 扩展的侧边栏设置**（扩展的 Playground 靠它接上 DSH 的模型）。
+>   **要主动把这一步讲给用户** —— 少了它扩展用不上 DSH 的模型，用户就会被引向申请第三方
+>   key，而那正是本插件要消除的成本。不要反过来让用户「先配好模型再来」。
 >
 > **静默操作（不打断用户）**：用 Bridge 模式驱动用户浏览器时，连接标签页应传
 > \`activate: false\`，否则会把用户正在看的页面切走、让浏览器变成测试画布。JS SDK 路径：

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tnnevol/dsh-midscene",
   "displayName": "Midscene Bridge",
   "type": "module",
-  "version": "0.2.0-rc.2.5",
+  "version": "0.2.0-rc.2.6",
   "description": "Hosts a loopback OpenAI-compatible bridge that exposes every model configured in DSH (official routes, plugin routes, and user-declared providers) so Midscene browser automation can drive pages with natural language without holding any credential itself.",
   "author": "tnnevol",
   "license": "Apache-2.0",
@@ -68,6 +68,7 @@
     "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
     "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
     "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
     "@deepseek-ai/dsh-skill": "0.2.0-rc.2",
     "@deepseek-ai/schemastery": "3.18.4",
@@ -83,6 +84,7 @@
     "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
     "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
     "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
     "@deepseek-ai/dsh-skill": "0.2.0-rc.2",
     "@deepseek-ai/schemastery": "3.18.4",
@@ -94,8 +96,8 @@
     "tsdown": "^0.22.2",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@tnnevol/dsh-e2e-kit": "5.7.6",
-    "@tnnevol/dsh-semi-ui": "5.7.6"
+    "@tnnevol/dsh-e2e-kit": "5.7.7",
+    "@tnnevol/dsh-semi-ui": "5.7.7"
   },
   "scripts": {
     "build": "tsdown",

package/skills/SOURCE.md

@@ -1,9 +1,11 @@
 # 内置技能来源
 
-本目录内置 **7 个技能**，来自两个上游。**所有技能文件都与上游逐字节一致，不含任何本地补丁。**
+本目录内置 **8 个技能**：**7 个来自上游**（与上游逐字节一致，不含任何本地补丁），
+外加 **1 个插件自有技能** `dsh-midscene`（**不是**上游内容，不参与上游同步）。
 
 | 技能 | 上游 | 定位 |
 | --- | --- | --- |
+| **`dsh-midscene`** | **插件自有** | **本环境入口**：模型由插件的桥提供、不索要密钥、优先用用户自己的 Chrome |
 | `browser-automation` | [`web-infra-dev/midscene-skills`](https://github.com/web-infra-dev/midscene-skills) | 浏览器自动化（Puppeteer / CDP / Bridge 三种模式） |
 | `computer-automation` | 同上 | 桌面控制（macOS / Windows / Linux，本地模式会接管真实鼠标键盘） |
 | `android-automation` | 同上 | Android 设备控制（ADB） |

package/skills/dsh-midscene/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: dsh-midscene
+description: |
+  DSH 环境里做 Midscene 浏览器/设备自动化时的**入口技能**：模型由 DSH 的
+  dsh-midscene 插件经本地桥提供，**不需要任何第三方模型密钥**。
+
+  只要任务涉及以下任一项，**先加载本技能**再动手：
+  - Midscene、@midscene/web、@midscene/test、MIDSCENE_MODEL_*、GUI Agent、视觉驱动 UI 自动化
+  - 用**真实 Chrome** 做端到端测试、点击/输入/断言、浏览器取证、截图
+  - Bridge 模式、Chrome 扩展、连接**用户自己的浏览器**
+  - Playwright / Puppeteer 集成、Midscene Test、midscene.config.ts
+  - 用户说「用 midscene 插件」「连上 chrome 测试」「浏览器自动化」「帮我点一下页面」
+
+  本技能是**本环境的权威入口**：与上游 Midscene 文档冲突时，以本技能为准。
+---
+
+# DSH Midscene 插件（本环境的唯一入口）
+
+## 一句话
+
+**模型由 DSH 提供，不要向用户索要任何模型密钥。**
+
+DSH 装了 `@tnnevol/dsh-midscene` 插件，它在本地起一个 OpenAI 兼容的桥，把 Midscene 的
+模型请求转发给**当前 DSH 会话正在用的模型**（凭据留在 DSH 的提供方插件里，桥不接触）。
+所以在本环境里：
+
+- ✅ 配置是**固定四行**，一条命令就能拿到，**开箱可用**
+- ❌ **不要**让用户提供 `MIDSCENE_MODEL_API_KEY`、模型名或服务商
+- ❌ **不要**让用户写 `.env`，也不要自己去翻 `~/.zshrc`、`~/.midscene`、npx 缓存找配置
+- ❌ **不要**建议用户「先配好模型再来」——那正是本插件要消除的成本
+
+## 第一步：取配置（一条命令）
+
+```sh
+curl -s "http://127.0.0.1:<端口>/v1/midscene-env"
+```
+
+端口以 `GET /v1/health` 的 `port` 字段为准（默认 `8787`，被占用会跳号）。
+返回 JSON 的 `content` 字段就是那四行，**直接可用**：
+
+| 去处 | 怎么用 |
+| --- | --- |
+| 跑命令行 | 存成**运行目录**的 `.env`（Midscene 只加载当前目录的 `.env`） |
+| Midscene 浏览器扩展 | 打开扩展的**侧边栏设置**粘进去（扩展的 Playground 靠它接上 DSH 的模型） |
+
+同一份配置，两个去处，内容完全相同。
+
+## 第二步：优先用用户自己的 Chrome（Bridge 模式）
+
+用户要的是**他自己的浏览器**——真实登录态、已装扩展、可见窗口，**不是**另起的 headless 实例：
+
+```sh
+npx -y @midscene/web@1 --bridge connect --url "<目标地址>"
+```
+
+- 需要用户已安装 **Midscene 浏览器扩展**；首次连接时在扩展弹窗点 **Allow**
+- **静默操作**：连接标签页传 `activate: false`，否则会把用户正在看的页面切走
+- 只有用户明确要「无头跑」「隔离环境」时才用 CDP / Puppeteer 路径
+
+## 第三步：按需操作并给出证据
+
+需要「看」→ `take_screenshot`；需要「动手」→ `act` / `assert`（或测试框架里的 `aiAct` / `aiAssert`）。
+报告结果时**附证据**（截图路径、断言输出、接口返回），不要只说「已完成」。
+
+## 常见弯路（都不要走）
+
+| 弯路 | 为什么错 |
+| --- | --- |
+| 向用户索要模型 key | 桥已经提供；模型就是当前 DSH 会话的模型 |
+| 翻 `~/.zshrc` / `~/.midscene` / npx 缓存找配置 | 那里不该有配置，翻也翻不到 |
+| 自己起 Puppeteer/Chrome 实例 | 用户要的是**他本人的**浏览器与登录态 |
+| 引用上游文档断言「插件不提供 env」 | 上游文档不知道本插件的桥存在，**以本技能为准** |
+| 先花十几步探索环境再动手 | 第一步就是上面那条 `curl`，配置立刻到手 |
+
+## 端口与多实例
+
+同一台机器可能有多个 DSH 实例，各自一个桥、端口不同（`8787`、`8788`…）。
+**以当前会话所属实例的桥为准**：从该实例的设置页或 `/v1/health` 确认端口，不要默认套用别的实例。