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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -7,7 +7,7 @@
 ## 安装
 
 ```sh
-dsh plugin --profile web add @tnnevol/dsh-midscene@0.2.0-rc.2.4
+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.4",
+  "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",
@@ -44,17 +44,6 @@
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "typecheck": "tsc -p tsconfig.json",
-    "check": "pnpm run typecheck && pnpm run test",
-    "prepublishOnly": "pnpm run check",
-    "publish:next": "pnpm publish --tag next --access public",
-    "test": "vitest run --config vitest.config.ts",
-    "test:e2e": "midscene-test --config tests/e2e/midscene.config.ts",
-    "test:bridge": "node --experimental-strip-types scripts/bridge-smoke.ts"
-  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -70,7 +59,7 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "catalog:",
+    "@deepseek-ai/cordis": "^4.0.4",
     "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
     "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
     "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.0-rc.2",
@@ -79,33 +68,45 @@
     "@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": "catalog:",
-    "react": "catalog:"
+    "@deepseek-ai/schemastery": "3.18.4",
+    "react": "^18.3.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "catalog:",
-    "@deepseek-ai/dsh-attachment": "catalog:dsh",
-    "@deepseek-ai/dsh-client-locale": "catalog:dsh",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "catalog:dsh",
-    "@deepseek-ai/dsh-client-ui-renderer": "catalog:dsh",
-    "@deepseek-ai/dsh-client-ui-settings": "catalog:dsh",
-    "@deepseek-ai/dsh-client-ui-slots": "catalog:dsh",
-    "@deepseek-ai/dsh-host-webserver": "catalog:dsh",
-    "@deepseek-ai/dsh-llm": "catalog:dsh",
-    "@deepseek-ai/dsh-settings": "catalog:dsh",
-    "@deepseek-ai/dsh-skill": "catalog:dsh",
-    "@deepseek-ai/schemastery": "catalog:",
-    "@midscene/test": "catalog:",
-    "@midscene/web": "catalog:",
-    "@tnnevol/dsh-e2e-kit": "workspace:*",
-    "@tnnevol/dsh-semi-ui": "workspace:*",
-    "@types/node": "catalog:",
-    "@types/react": "catalog:",
-    "react": "catalog:",
-    "tsdown": "catalog:",
-    "typescript": "catalog:",
-    "vitest": "catalog:"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2",
+    "@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",
+    "@midscene/test": "1.15.1",
+    "@midscene/web": "1.15.1",
+    "@types/node": "^22.20.0",
+    "@types/react": "^18.3.31",
+    "react": "^18.3.1",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8",
+    "@tnnevol/dsh-e2e-kit": "5.7.7",
+    "@tnnevol/dsh-semi-ui": "5.7.7"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc -p tsconfig.json",
+    "check": "pnpm run typecheck && pnpm run test",
+    "publish:next": "pnpm publish --tag next --access public",
+    "test": "vitest run --config vitest.config.ts",
+    "test:e2e": "midscene-test --config tests/e2e/midscene.config.ts",
+    "test:bridge": "node --experimental-strip-types scripts/bridge-smoke.ts"
   }
-}
+}

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` 确认端口，不要默认套用别的实例。