yunti-browser-runtime 0.1.1 → 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
 ```
 
@@ -79,8 +87,38 @@ npm run doctor
 npm run doctor:json
 ```
 
+## 复制给 Agent 的安装引导
+
+把下面这段话复制给你正在使用的 Agent，让它一步步引导你安装和验证：
+
+```text
+请帮我安装并接入 Yunti Browser Runtime。它是一个本地浏览器运行时，让你通过 MCP 操作我本机 Chrome/Edge 页面。
+
+请按步骤引导我完成，不要跳步：
+
+1. 确认我本机有 Node.js 22+。
+2. 执行：npm install -g yunti-browser-runtime
+3. 执行：yunti-browser-runtime print-config -- --agent 当前Agent名称 --human
+4. 根据输出，把 MCP server 配置加入当前 Agent 的 MCP 配置。
+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，不需要打开 popup，也不需要保存设置。
+8. 打开任意 http/https 页面并刷新。
+9. 执行：yunti-browser-runtime doctor
+10. 如果 doctor 正常，再调用 yunti_list_browser_targets 或 yunti_get_tool_usage_hints 验证你能看到浏览器页面。
+
+注意：Chrome 扩展不能由 npm 静默安装，必须由我手动在浏览器扩展页加载。扩展加载完成后默认立即可用，不要要求我填写 token、打开 popup 或保存设置；除非 doctor 明确提示 bridge 未运行，才让我单独执行 yunti-browser-runtime bridge。
+```
+
 ## 安装浏览器扩展
 
+npm 全局安装后，扩展目录通常是：
+
+```bash
+$(npm root -g)/yunti-browser-runtime/extension
+```
+
 开发加载方式：
 
 1. 打开 `chrome://extensions` 或 `edge://extensions`。
@@ -88,10 +126,12 @@ npm run doctor:json
 3. 点击“加载已解压的扩展程序”。
 4. 选择本项目的 `extension/` 目录。
 5. 打开任意 `http` 或 `https` 页面。
-6. 点击扩展图标，确认 bridge 地址为 `http://127.0.0.1:48887`，保存设置。
-7. 刷新目标页面，确认页面已连接。
+6. 刷新目标页面即可连接。
 
-扩展只负责把页面注册到本地 bridge，并执行 Agent 发来的浏览器动作。
+扩展默认使用 `http://127.0.0.1:48887`，本地安装不需要 token，不需要打开 popup，
+也不需要保存设置。扩展 popup 首屏只显示连接状态；自定义 bridge URL、页面匹配或
+可选 token 都收在高级设置里。扩展只负责把页面注册到本地 bridge，并执行 Agent
+发来的浏览器动作。
 
 也可以生成 zip 包用于分发或归档：
 
@@ -255,7 +295,8 @@ token。
 
 ## 发布状态与后续事项
 
-- `yunti-browser-runtime@0.1.1` 已发布到官方 npm registry。
-- `0.1.1` 将本地默认使用路径改为免 bridge token。
+- `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

@@ -56,6 +56,8 @@
 | P4.18 | 已完成 | npm 发布后验证命令 |
 | P4.19 | 已完成 | npm 正式发布执行 |
 | P5.1 | 已完成 | 本地默认免 bridge token |
+| P5.2 | 已完成 | 扩展 popup 与安装引导简化 |
+| P5.3 | 已完成 | 扩展首屏零配置 |
 
 ## P0.1 bridge token + CORS 收紧
 
@@ -1297,6 +1299,77 @@ metadata 与当前 `package.json` 一致。
 - `npm run release:publish` 成功发布 `yunti-browser-runtime@0.1.1`。
 - `npm run release:verify-published` 返回 0。
 
+## P5.2 扩展 popup 与安装引导简化
+
+状态：已完成（2026-07-03）
+
+实现摘要：
+
+- 扩展 popup 首屏不再展示 Bridge Token 输入框，避免用户误以为本地默认安装需要填写
+  token。
+- Bridge Token 移入“高级设置”，并标注为可选；如果用户已有 token 配置，高级设置会
+  自动展开。
+- popup 默认状态文案改为“默认无需设置，打开或刷新 http/https 页面即可”。
+- README 增加“复制给 Agent 的安装引导”，让用户可以把一段话交给 Agent，由 Agent
+  分步骤带用户完成 npm 安装、MCP 配置、扩展加载和 doctor 验证。
+- README / INSTALL 明确：加载扩展后默认不需要保存设置，不需要 token。
+- package 和 extension 版本同步提升到 `0.1.2`。
+
+### 目标
+
+让用户在安装扩展后尽量立即可用：默认无需填写 token、无需保存 popup 设置；需要
+自定义 bridge URL、页面匹配或 token 时再进入高级/设置路径。
+
+### 验收标准
+
+- popup 首屏不出现 Bridge Token 输入框。
+- popup 仍保留可选 token 配置能力。
+- README 包含可复制给 Agent 的安装引导词。
+- README / INSTALL 不再要求默认本地安装时点击 popup 保存 token 或保存设置。
+- `npm run release:check` 通过。
+- `npm run release:publish` 发布 `yunti-browser-runtime@0.1.2`，并通过
+  `npm run release:verify-published` 验证。
+
+### 验收记录
+
+- `npm run release:check` 通过。
+- `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
@@ -1318,10 +1391,11 @@ rg "/U[s]ers|C[o]deg|x[y]y|y[b]m100" README.md docs skills package.json
 
 ## 当前下一步
 
-P0.1-P5.1 已完成，`yunti-browser-runtime@0.1.1` 已发布到官方 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 默认不需要用户保存设置；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:
@@ -54,12 +63,14 @@ Development loading:
 2. Enable developer mode.
 3. Choose "Load unpacked".
 4. Select the project `extension/` directory.
-5. Click the extension icon and confirm the bridge URL is `http://127.0.0.1:48887`.
-6. Open any `http` or `https` page and click the extension icon to confirm the
-   page is connected.
-
-The extension registers browser pages with the local bridge. It does not create
-agent conversations or depend on a remote workspace.
+5. Open or refresh any `http` or `https` page.
+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, 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,10 @@
 
 ## Current Phase
 
-Patch release `yunti-browser-runtime@0.1.1` is complete. The local loopback
-bridge no longer requires a token by default, and the published package is
-verified with `npm run release:verify-published`.
+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 settings as a first-run task, and the published package is verified with
+`npm run release:verify-published`.
 
 ## Current State
 
@@ -42,7 +43,9 @@ verified with `npm run release:verify-published`.
 - `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.1` is published on the official npm registry.
+- `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`.
@@ -248,6 +251,18 @@ verified with `npm run release:verify-published`.
   real-browser smoke skipped by configuration; `npm run check` and
   `npm run release:check` passed; `npm run release:publish` published
   `yunti-browser-runtime@0.1.1`; `npm run release:verify-published` returned 0.
+- P5.2 extension popup and onboarding simplification is complete: Bridge Token
+  is now optional under advanced settings, README contains a copyable Agent
+  installation prompt, and default extension loading no longer asks users to
+  save popup settings.
+- 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.0` 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.1",
+  "version": "0.1.3",
   "description": "Local browser runtime for AI agents through MCP.",
   "permissions": [
     "activeTab",

package/extension/popup.css

@@ -34,6 +34,27 @@ label {
   font-size: 12px;
 }
 
+details {
+  display: grid;
+  gap: 6px;
+  color: #334155;
+  font-size: 12px;
+}
+
+summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+details label {
+  margin-top: 6px;
+}
+
+details button {
+  width: 100%;
+  margin-top: 6px;
+}
+
 input,
 textarea {
   width: 100%;
@@ -59,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,20 +10,23 @@
     <main>
       <h1>Yunti Browser Runtime</h1>
       <p id="status">正在读取状态...</p>
-      <label>
-        Bridge URL
-        <input id="bridgeUrl" autocomplete="off" />
-      </label>
-      <label>
-        Bridge Token
-        <input id="bridgeToken" autocomplete="off" type="password" />
-      </label>
-      <label>
-        页面匹配
-        <textarea id="platformMatches" rows="3"></textarea>
-      </label>
-      <button id="save">保存设置</button>
       <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>
     </main>
     <script type="module" src="popup.js"></script>
   </body>

package/extension/popup.js

@@ -2,6 +2,8 @@ const statusEl = document.querySelector("#status")
 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)
 
@@ -14,11 +16,7 @@ async function refresh() {
     return
   }
   renderSettings(state.settings || {})
-  setStatus(
-    state.activeSession
-      ? `页面已连接\n${state.activeSession.title || state.activeSession.url}`
-      : "请打开任意 http/https 页面，并确认本地 bridge 已启动。"
-  )
+  setStatus(statusText(state))
 }
 
 async function save() {
@@ -35,15 +33,30 @@ async function save() {
     return
   }
   renderSettings(state.settings || {})
-  setStatus("设置已保存，请刷新目标页面完成重新注册。")
+  setStatus("设置已保存。请刷新目标页面完成重新注册。")
 }
 
 function renderSettings(settings) {
-  bridgeUrlEl.value = settings.bridgeUrl || "http://127.0.0.1:48887"
+  bridgeUrlEl.value = settings.bridgeUrl || defaultBridgeUrl
   bridgeTokenEl.value = 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.1",
+  "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(", ")}`,