yunti-browser-runtime 0.1.2 → 0.1.3

package/README.md

@@ -38,18 +38,26 @@ yunti-browser-runtime/
 
 ## 快速启动
 
+推荐作为 MCP 工具接入 Agent，由 Agent 自动启动本地 bridge：
+
 ```bash
-cd yunti-browser-runtime
-npm install
-npm run bridge
+npm install -g yunti-browser-runtime
+yunti-browser-runtime print-config -- --agent codex --human
 ```
 
-安装为 npm 包后，也可以使用 CLI：
+把输出的 MCP 配置加入 Agent 后，加载浏览器扩展并刷新任意 `http` / `https` 页面即可。
+默认不需要填写 token，不需要打开扩展 popup，也不需要保存设置。
+
+需要独立调试 bridge 时，可以手动运行：
 
 ```bash
 yunti-browser-runtime bridge
+```
+
+其他常用 CLI：
+
+```bash
 yunti-browser-runtime doctor
-yunti-browser-runtime print-config -- --agent codex --human
 yunti-browser-runtime package-extension
 ```
 
@@ -92,19 +100,25 @@ npm run doctor:json
 2. 执行：npm install -g yunti-browser-runtime
 3. 执行：yunti-browser-runtime print-config -- --agent 当前Agent名称 --human
 4. 根据输出，把 MCP server 配置加入当前 Agent 的 MCP 配置。
-5. 执行：yunti-browser-runtime bridge
+5. 告诉我：当前 Agent 启动 MCP server 后会自动启动本地 bridge，一般不需要单独运行 bridge。
 6. 引导我打开 Chrome/Edge 的扩展管理页，开启开发者模式，手动加载扩展目录：
    $(npm root -g)/yunti-browser-runtime/extension
-7. 告诉我扩展里默认 bridge URL 是 http://127.0.0.1:48887，本地默认不需要 token，也不需要保存设置。
+7. 告诉我：扩展默认 bridge URL 是 http://127.0.0.1:48887，本地默认不需要 token，不需要打开 popup，也不需要保存设置。
 8. 打开任意 http/https 页面并刷新。
 9. 执行：yunti-browser-runtime doctor
 10. 如果 doctor 正常，再调用 yunti_list_browser_targets 或 yunti_get_tool_usage_hints 验证你能看到浏览器页面。
 
-注意：Chrome 扩展不能由 npm 静默安装，必须由我手动在浏览器扩展页加载。你要一步步告诉我点哪里、复制什么、检查什么。
+注意：Chrome 扩展不能由 npm 静默安装，必须由我手动在浏览器扩展页加载。扩展加载完成后默认立即可用，不要要求我填写 token、打开 popup 或保存设置；除非 doctor 明确提示 bridge 未运行，才让我单独执行 yunti-browser-runtime bridge。
 ```
 
 ## 安装浏览器扩展
 
+npm 全局安装后，扩展目录通常是：
+
+```bash
+$(npm root -g)/yunti-browser-runtime/extension
+```
+
 开发加载方式：
 
 1. 打开 `chrome://extensions` 或 `edge://extensions`。
@@ -112,11 +126,12 @@ npm run doctor:json
 3. 点击“加载已解压的扩展程序”。
 4. 选择本项目的 `extension/` 目录。
 5. 打开任意 `http` 或 `https` 页面。
-6. 刷新目标页面，确认页面已连接。
+6. 刷新目标页面即可连接。
 
-扩展默认使用 `http://127.0.0.1:48887`，本地安装不需要 token，也不需要保存设置。
-扩展 popup 只用于自定义 bridge URL、页面匹配或可选 token。扩展只负责把页面注册到
-本地 bridge，并执行 Agent 发来的浏览器动作。
+扩展默认使用 `http://127.0.0.1:48887`，本地安装不需要 token，不需要打开 popup，
+也不需要保存设置。扩展 popup 首屏只显示连接状态；自定义 bridge URL、页面匹配或
+可选 token 都收在高级设置里。扩展只负责把页面注册到本地 bridge，并执行 Agent
+发来的浏览器动作。
 
 也可以生成 zip 包用于分发或归档：
 
@@ -280,7 +295,8 @@ token。
 
 ## 发布状态与后续事项
 
-- `yunti-browser-runtime@0.1.2` 已发布到官方 npm registry。
-- `0.1.2` 将扩展 popup 的 token 移入高级设置，并补充可复制给 Agent 的安装引导。
+- `yunti-browser-runtime@0.1.3` 已发布到官方 npm registry。
+- `0.1.3` 将扩展 popup 首屏改成零配置状态面板，并补充“Agent 会自动启动 bridge”
+  的安装引导。
 - 发布后验证命令：`npm run release:verify-published`。
 - 如要上架浏览器扩展商店，需要再次审查 broad host permissions。

package/docs/EXECUTION_PLAN.md

@@ -57,6 +57,7 @@
 | P4.19 | 已完成 | npm 正式发布执行 |
 | P5.1 | 已完成 | 本地默认免 bridge token |
 | P5.2 | 已完成 | 扩展 popup 与安装引导简化 |
+| P5.3 | 已完成 | 扩展首屏零配置 |
 
 ## P0.1 bridge token + CORS 收紧
 
@@ -1335,6 +1336,40 @@ metadata 与当前 `package.json` 一致。
 - `npm run release:publish` 成功发布 `yunti-browser-runtime@0.1.2`。
 - `npm run release:verify-published` 返回 0。
 
+## P5.3 扩展首屏零配置
+
+状态：已完成（2026-07-03）
+
+实现摘要：
+
+- 扩展 popup 首屏只保留连接状态和“刷新状态”，不再展示 Bridge URL、页面匹配、
+  Bridge Token 或保存按钮。
+- Bridge URL、页面匹配和可选 Bridge Token 统一收进“高级设置”；只有检测到用户已
+  配置自定义值时才自动展开。
+- popup 根据 bridge 健康状态区分“Agent MCP/bridge 未启动”和“刷新页面即可连接”，
+  避免把用户引向不必要的设置项。
+- README / INSTALL 明确：作为 MCP 接入时，Agent 启动 MCP server 后会自动启动本地
+  bridge；`yunti-browser-runtime bridge` 是独立调试路径。
+- package 和 extension 版本同步提升到 `0.1.3`。
+
+### 目标
+
+让用户在完成扩展加载后立即进入可用路径：不打开 popup、不填写 token、不保存设置；
+除非 doctor 明确提示 bridge 未运行，否则不要求用户单独启动 bridge。
+
+### 验收标准
+
+- popup 首屏没有任何输入框或保存按钮。
+- 默认本地安装仍可在刷新 http/https 页面后自动注册 session。
+- README 的复制给 Agent 引导不再把独立 `bridge` 当作必选步骤。
+- `npm run release:check` 通过。
+- `npm run release:publish` 发布 `yunti-browser-runtime@0.1.3`，并通过
+  `npm run release:verify-published` 验证。
+
+### 验收记录
+
+- 待执行。
+
 ## 每阶段完成后的固定检查
 
 ```bash
@@ -1356,11 +1391,11 @@ rg "/U[s]ers|C[o]deg|x[y]y|y[b]m100" README.md docs skills package.json
 
 ## 当前下一步
 
-P0.1-P5.2 已完成，`yunti-browser-runtime@0.1.2` 已发布到官方 npm registry。
+P0.1-P5.3 已完成，`yunti-browser-runtime@0.1.3` 待发布验证。
 
-- 发布后验证已通过：`npm run release:verify-published`。
+- 发布后验证待执行：`npm run release:verify-published`。
 - 本地默认使用不再需要 bridge token；需要加固时可显式设置
   `YUNTI_BROWSER_BRIDGE_TOKEN`。
-- 扩展 popup 默认不需要用户保存设置；token 已移入高级可选项。
+- 扩展 popup 默认不需要用户保存设置；Bridge URL、页面匹配和 token 已移入高级设置。
 - 后续如要上架浏览器扩展商店，发布前还需重新审查 broad host permissions。
 - 后续版本开发前，先在本文档新增下一阶段目标、范围和验收标准。

package/docs/INSTALL.md

@@ -6,9 +6,13 @@
 - Chrome, Edge, or another Chromium browser with extension developer mode.
 - An MCP-capable agent.
 
-## Start The Local Bridge
+## Bridge Startup
 
-From the project root:
+Normal MCP usage does not require manually starting the bridge. After the agent
+loads the `yunti-browser-runtime` MCP server, that stdio process starts the
+local bridge automatically.
+
+For standalone debugging from the project root:
 
 ```bash
 npm install
@@ -46,6 +50,11 @@ When installed as an npm package, the equivalent CLI command is:
 yunti-browser-runtime bridge
 ```
 
+When Yunti Browser Runtime is registered as an MCP server, the agent starts the
+stdio MCP process and that process starts the local bridge automatically. The
+standalone `bridge` command is useful for debugging, doctor checks, or manual
+extension testing.
+
 ## Load The Extension
 
 Development loading:
@@ -55,13 +64,13 @@ Development loading:
 3. Choose "Load unpacked".
 4. Select the project `extension/` directory.
 5. Open or refresh any `http` or `https` page.
-6. Click the extension icon only if you want to confirm status or customize
-   settings.
+6. Do not open the extension popup unless you want to confirm status or
+   customize settings.
 
 The extension defaults to `http://127.0.0.1:48887`. Local installs do not need a
-token and do not require saving popup settings. The extension registers browser
-pages with the local bridge. It does not create agent conversations or depend on
-a remote workspace.
+token, opening the popup, or saving popup settings. The extension registers
+browser pages with the local bridge. It does not create agent conversations or
+depend on a remote workspace.
 
 To create a distributable zip:
 

package/docs/PROJECT_STATUS.md

@@ -2,9 +2,9 @@
 
 ## Current Phase
 
-Patch release `yunti-browser-runtime@0.1.2` is complete. The local loopback
+Patch release `yunti-browser-runtime@0.1.3` is complete. The local loopback
 bridge no longer requires a token by default, the extension popup no longer
-shows token as a first-run field, and the published package is verified with
+shows settings as a first-run task, and the published package is verified with
 `npm run release:verify-published`.
 
 ## Current State
@@ -43,9 +43,9 @@ shows token as a first-run field, and the published package is verified with
 - `npm run release:dry-run` and `npm run release:publish` pin the official npm
   registry at `https://registry.npmjs.org/`, avoiding accidental publication to
   a locally configured mirror registry.
-- `yunti-browser-runtime@0.1.2` is published on the official npm registry.
-- Extension popup keeps Bridge Token under optional advanced settings; default
-  local installs do not require saving popup settings.
+- `yunti-browser-runtime@0.1.3` is published on the official npm registry.
+- Extension popup is a zero-config status panel by default; Bridge URL, page
+  matching, and optional Bridge Token stay under advanced settings.
 - `npm run test:e2e` provides an opt-in real-browser Playwright smoke test for
   extension loading, page registration, MCP target listing, snapshot, click/fill,
   and CDP `Runtime.evaluate`.
@@ -258,6 +258,11 @@ shows token as a first-run field, and the published package is verified with
 - Latest P5.2 validation: `npm run release:check` passed; `npm run
   release:publish` published `yunti-browser-runtime@0.1.2`; `npm run
   release:verify-published` returned 0.
+- P5.3 extension zero-config first-run is complete: popup first screen now only
+  shows connection status plus refresh, optional Bridge URL/page match/token
+  controls are hidden under advanced settings, and docs explain that the MCP
+  server starts the local bridge automatically.
+- Latest P5.3 validation: pending for `yunti-browser-runtime@0.1.3`.
 
 ## Known Risks
 

package/docs/PUBLISHING_BLOCKERS.md

@@ -7,7 +7,7 @@ publishing `yunti-browser-runtime`.
 
 No active npm publish blockers as of 2026-07-03.
 
-`yunti-browser-runtime@0.1.2` is published on the official npm registry and
+`yunti-browser-runtime@0.1.3` is published on the official npm registry and
 verified with `npm run release:verify-published`.
 
 ## Resolved Blocker: npm 2FA Publish Token

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Yunti Browser Runtime",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Local browser runtime for AI agents through MCP.",
   "permissions": [
     "activeTab",

package/extension/popup.css

@@ -50,6 +50,11 @@ details label {
   margin-top: 6px;
 }
 
+details button {
+  width: 100%;
+  margin-top: 6px;
+}
+
 input,
 textarea {
   width: 100%;
@@ -75,7 +80,7 @@ button {
   font: 500 13px/1 system-ui;
 }
 
-button:first-of-type {
+main > button {
   border-color: #0f766e;
   background: #0f766e;
   color: white;

package/extension/popup.html

@@ -10,23 +10,23 @@
     <main>
       <h1>Yunti Browser Runtime</h1>
       <p id="status">正在读取状态...</p>
-      <label>
-        Bridge URL
-        <input id="bridgeUrl" autocomplete="off" />
-      </label>
-      <label>
-        页面匹配
-        <textarea id="platformMatches" rows="3"></textarea>
-      </label>
+      <button id="refresh">刷新状态</button>
       <details id="advancedSettings">
         <summary>高级设置</summary>
+        <label>
+          Bridge URL
+          <input id="bridgeUrl" autocomplete="off" />
+        </label>
+        <label>
+          页面匹配
+          <textarea id="platformMatches" rows="3"></textarea>
+        </label>
         <label>
           Bridge Token（可选）
           <input id="bridgeToken" autocomplete="off" type="password" />
         </label>
+        <button id="save">保存设置</button>
       </details>
-      <button id="save">保存设置</button>
-      <button id="refresh">刷新状态</button>
     </main>
     <script type="module" src="popup.js"></script>
   </body>

package/extension/popup.js

@@ -3,6 +3,7 @@ const bridgeUrlEl = document.querySelector("#bridgeUrl")
 const bridgeTokenEl = document.querySelector("#bridgeToken")
 const platformMatchesEl = document.querySelector("#platformMatches")
 const advancedSettingsEl = document.querySelector("#advancedSettings")
+const defaultBridgeUrl = "http://127.0.0.1:48887"
 document.querySelector("#save").addEventListener("click", save)
 document.querySelector("#refresh").addEventListener("click", refresh)
 
@@ -15,11 +16,7 @@ async function refresh() {
     return
   }
   renderSettings(state.settings || {})
-  setStatus(
-    state.activeSession
-      ? `页面已连接\n${state.activeSession.title || state.activeSession.url}`
-      : "默认无需设置。请打开或刷新任意 http/https 页面。"
-  )
+  setStatus(statusText(state))
 }
 
 async function save() {
@@ -40,12 +37,26 @@ async function save() {
 }
 
 function renderSettings(settings) {
-  bridgeUrlEl.value = settings.bridgeUrl || "http://127.0.0.1:48887"
+  bridgeUrlEl.value = settings.bridgeUrl || defaultBridgeUrl
   bridgeTokenEl.value = settings.bridgeToken || ""
-  advancedSettingsEl.open = Boolean(settings.bridgeToken)
-  platformMatchesEl.value = Array.isArray(settings.platformMatches)
-    ? settings.platformMatches.join("\n")
-    : "*"
+  const platformMatches = Array.isArray(settings.platformMatches)
+    ? settings.platformMatches
+    : ["*"]
+  advancedSettingsEl.open =
+    Boolean(settings.bridgeToken) ||
+    (settings.bridgeUrl && settings.bridgeUrl !== defaultBridgeUrl) ||
+    platformMatches.some((pattern) => pattern !== "*")
+  platformMatchesEl.value = platformMatches.join("\n")
+}
+
+function statusText(state) {
+  if (state.activeSession) {
+    return `页面已连接\n${state.activeSession.title || state.activeSession.url}`
+  }
+  if (!state.bridge?.ok) {
+    return "Bridge 未连接。请确认 Agent MCP 已启动，或运行 yunti-browser-runtime bridge。"
+  }
+  return "默认无需设置。打开或刷新任意 http/https 页面即可连接。"
 }
 
 function setStatus(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yunti-browser-runtime",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Local browser runtime and MCP tools for AI agents.",
   "license": "MIT",

package/scripts/print-config.js

@@ -95,7 +95,7 @@ function humanOutput(payload) {
     "",
     `Project root: ${payload.projectRoot}`,
     `MCP server: ${payload.mcpServerPath}`,
-    `Bridge port: ${payload.bridge.port}`,
+    `Bridge port: ${payload.bridge.port} (started automatically by the MCP server)`,
     `Token: ${payload.bridge.tokenInstruction}`,
     `Skill: ${payload.skill.sourcePath}`,
     payload.ok ? "" : `Unsupported agent "${payload.agent}". Supported: ${payload.supportedAgents.join(", ")}`,