docs: update user-facing docs with real test results from baidu.com verification

fix: guard auto-start server to only run when executed directly, not when imported by tests
feat: add GET /profiles route
2026-08-12 21:42:41 +08:00 · 2026-08-12 21:30:35 +08:00 · 2026-08-12 21:29:47 +08:00 · 2026-08-12 21:28:02 +08:00 · 2026-08-12 21:24:07 +08:00
18 changed files with 801 additions and 247 deletions
@@ -29,7 +29,25 @@ Canvas/WebGL/Audio 指纹、HTTP 请求头、屏幕视口、权限状态、鼠

 ## 技术栈

-TypeScript + Node.js + Playwright + playright-extra + stealth 插件 + 自研 stealth 模块
+TypeScript + Node.js + Playwright + playwright-extra + stealth 插件 + 自研 stealth 模块
+
+## 已验证功能
+
+| 功能 | 状态 | 说明 |
+|------|------|------|
+| 页面打开/关闭/列表 | ✅ | 支持别名引用 |
+| 文本提取 | ✅ | body.innerText |
+| HTML 提取 | ✅ | documentElement.outerHTML |
+| 截图 | ✅ | PNG base64 输出 |
+| JS 执行 | ✅ | 任意代码 eval |
+| 点击/输入/滚动 | ✅ | CSS 选择器定位 |
+| 等待 | ✅ | 选择器或毫秒 |
+| Cookie 管理 | ✅ | 查看/设置/删除 |
+| 网络请求监控 | ✅ | 实时请求/响应日志 |
+| 控制台监控 | ✅ | 实时 console 输出 |
+| 指纹模版切换 | ✅ | 3 套内置配置 |
+| WebSocket 实时推送 | ✅ | 页面事件广播 |
+| 反检测 (navigator/screen/canvas/headers) | ✅ | 7 个 stealth 模块 |

 ## License

@@ -1,143 +1,148 @@
 # VisionL 使用示例

-> 面向智能体和人工用户的典型场景。
+> 基于实际测试验证的场景。

 ## 场景一：搜索引擎查询

 ```bash
 # 1. 打开百度
-visionl page open https://www.baidu.com --alias search
-# → {"ok":true,"data":{"id":"p_1234","alias":"search",...}}
+curl -s -X POST http://127.0.0.1:9527/pages \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://www.baidu.com","alias":"search"}'

-# 2. 输入搜索词
-visionl type search "#kw" "VisionL 浏览器"
+# 2. 获取首页文本
+curl -s http://127.0.0.1:9527/pages/search/text

-# 3. 点击搜索
-visionl click search "#su"
+# 3. 输入搜索词并搜索
+curl -s -X POST http://127.0.0.1:9527/pages/search/type \
+  -H 'Content-Type: application/json' \
+  -d '{"selector":"#kw","text":"VisionL 浏览器"}'
+curl -s -X POST http://127.0.0.1:9527/pages/search/click \
+  -H 'Content-Type: application/json' \
+  -d '{"selector":"#su"}'
+curl -s -X POST http://127.0.0.1:9527/pages/search/wait \
+  -H 'Content-Type: application/json' \
+  -d '{"ms":2000}'

-# 4. 等待结果加载
-visionl wait search --selector "#content_left"
+# 4. 获取搜索结果
+curl -s http://127.0.0.1:9527/pages/search/text

-# 5. 获取页面文本
-visionl text search
-# → {"ok":true,"data":{"text":"搜索结果..."}}
+# 5. 截图保存
+curl -s http://127.0.0.1:9527/pages/search/screenshot | jq -r '.data.base64' | base64 -d > result.png

-# 6. 用完关闭
-visionl page kill search
+# 6. 关闭
+curl -s -X DELETE http://127.0.0.1:9527/pages/search
 ```

 ## 场景二：多页面信息收集

 ```bash
 # 同时打开多个信息源
-visionl page open https://news.ycombinator.com --alias hn
-visionl page open https://www.reddit.com/r/programming --alias reddit
-visionl page open https://github.com/trending --alias gh
+curl -s -X POST http://127.0.0.1:9527/pages \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://www.baidu.com","alias":"baidu"}'
+curl -s -X POST http://127.0.0.1:9527/pages \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://www.bing.com","alias":"bing"}'

 # 分别提取内容
-visionl text hn
-visionl text reddit
-visionl text gh
+curl -s http://127.0.0.1:9527/pages/baidu/text
+curl -s http://127.0.0.1:9527/pages/bing/text

-# 用完批量关闭
-visionl page kill-all
+# 查看所有页面
+curl -s http://127.0.0.1:9527/pages
+
+# 关闭指定页面
+curl -s -X DELETE http://127.0.0.1:9527/pages/baidu
 ```

-## 场景三：表单填写
+## 场景三：Cookie 管理

 ```bash
-# 1. 打开登录页
-visionl page open https://example.com/login --alias login
+# 查看页面 Cookie（百度首页返回 8 个 Cookie）
+curl -s http://127.0.0.1:9527/pages/baidu/cookies

-# 2. 填写表单
-visionl type login "#email" "user@example.com"
-visionl type login "#password" "s3cret"
+# 设置自定义 Cookie
+curl -s -X POST http://127.0.0.1:9527/pages/baidu/cookies \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"session","value":"abc123","domain":".baidu.com"}'

-# 3. 提交
-visionl click login "button[type=submit]"
-
-# 4. 截图验证
-visionl screenshot login -o logged-in.png
+# 删除特定 Cookie
+curl -s -X DELETE http://127.0.0.1:9527/pages/baidu/cookies/session
 ```

-## 场景四：页面截图
+## 场景四：网络请求监控

 ```bash
-# 打开并截图
-visionl page open https://www.example.com --alias page
-visionl wait page --ms 2000       # 等待渲染
-visionl screenshot page -o page.png
+# 打开页面后查看网络请求日志
+curl -s http://127.0.0.1:9527/pages/baidu/network

-# 滚动后截图
-visionl scroll page --down 600
-visionl screenshot page -o page-scrolled.png
+# 返回包含请求 URL、方法、状态码等信息：
+# [{"type":"response","url":"https://pss.bdstatic.com/...","status":200,...}]
 ```

 ## 场景五：JS 数据提取

+```bash
+# 获取页面标题
+curl -s -X POST http://127.0.0.1:9527/pages/baidu/eval \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"document.title"}'
+# {"ok":true,"data":{"result":"百度一下，你就知道"}}
+
+# 获取链接数量
+curl -s -X POST http://127.0.0.1:9527/pages/baidu/eval \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"document.querySelectorAll(\"a\").length"}'
+
+# 获取页面 meta 信息
+curl -s -X POST http://127.0.0.1:9527/pages/baidu/eval \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"document.querySelector(\"meta[name=description]\")?.content"}'
+```
+
+## 场景六：滚动截图
+
+```bash
+# 滚动页面
+curl -s -X POST http://127.0.0.1:9527/pages/baidu/scroll \
+  -H 'Content-Type: application/json' \
+  -d '{"deltaY":500}'
+
+# 滚动到底部
+curl -s -X POST http://127.0.0.1:9527/pages/baidu/scroll \
+  -H 'Content-Type: application/json' \
+  -d '{"toBottom":true}'
+
+# 截图
+curl -s http://127.0.0.1:9527/pages/baidu/screenshot | jq -r '.data.base64' | base64 -d > scrolled.png
+```
+
+## 场景七：切换指纹配置
+
+```bash
+# 查看可用配置
+curl -s http://127.0.0.1:9527/profiles
+
+# 使用 Windows Chrome 指纹打开页面
+curl -s -X POST http://127.0.0.1:9527/pages \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://www.baidu.com","alias":"win","profile":"desktop-windows"}'
+```
+
+## 场景八：页面持久化验证
+
 ```bash
 # 1. 打开页面
-visionl page open https://api.example.com/data --alias data
+curl -s -X POST http://127.0.0.1:9527/pages \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://www.baidu.com","alias":"persistent"}'

-# 2. 执行 JS 提取 JSON 数据
-visionl eval data "JSON.parse(document.body.innerText)"
-# → {"ok":true,"data":{"result":{"items":[...]}}}
+# 2. 关闭 curl 连接（页面不消失）
+# 3. 重新查询 — 页面仍在
+curl -s http://127.0.0.1:9527/pages/persistent
+# {"ok":true,"data":{"id":"p_xxx","status":"active",...}}

-# 3. 获取页面标题
-visionl eval data "document.title"
-# → {"ok":true,"data":{"result":"API Data Page"}}
-```
-
-## 场景六：REST 直通（高级）
-
-```bash
-# 不使用子命令，直接调用 HTTP API
-visionl raw POST /pages '{"url":"https://example.com","alias":"test"}'
-# → {"ok":true,"data":{"id":"p_5678",...}}
-
-visionl raw GET /pages/p_5678/text
-# → {"ok":true,"data":{"text":"..."}}
-
-visionl raw DELETE /pages/p_5678
-# → {"ok":true,"data":null}
-```
-
-## 场景七：智能体自动化工作流
-
-LLM 通过 VisionL 完成机票比价：
-
-```
-1. visionl page open https://flights.example.com --alias flights
-2. visionl type flights "#from" "北京"
-3. visionl type flights "#to" "上海"
-4. visionl type flights "#date" "2026-08-20"
-5. visionl click flights "#search"
-6. visionl wait flights --selector ".results"
-7. visionl text flights
-   → 提取票价信息
-8. visionl eval flights "document.querySelectorAll('.price').length"
-   → 统计结果数量
-9. visionl page kill flights
-```
-
-## 场景八：长时间运行的任务
-
-```bash
-# 打开监控面板
-visionl page open https://monitor.example.com --alias monitor --pretty
-# ✓ 页面已打开
-#   ID:    p_mon_001
-#   URL:   https://monitor.example.com
-#   别名:  monitor
-
-# ... 过了一段时间 ...
-
-# 还是同一个页面
-visionl page list --pretty
-# ✓ 1 个页面
-#   p_mon_001  monitor  https://monitor.example.com  active
-
-# 刷新重新截图
-visionl navigate monitor https://monitor.example.com
-visionl screenshot monitor -o latest.png
+# 4. 只有显式 kill 才关闭
+curl -s -X DELETE http://127.0.0.1:9527/pages/persistent
 ```
@@ -1,138 +1,192 @@
 # 在 LLM 智能体中集成 VisionL

-> 本文档介绍如何让 LLM 通过工具调用使用 VisionL-CLI 操控浏览器。
+> 让 LLM 通过 HTTP API 工具调用操控 VisionL 浏览器。

 ## 原理

-LLM 将 `visionl` 注册为一个系统命令/工具，在需要浏览网页时调用。
-所有命令输出结构化的 JSON，LLM 直接解析结果并决定下一步操作。
+VisionL daemon 提供完整的 REST API。LLM 将 API 调用注册为工具/函数（Function Calling），
+在需要浏览网页时生成对应的 HTTP 请求。所有接口返回结构化 JSON，LLM 直接解析。
+
+## API 总览
+
+| 方法 | 端点 | 功能 |
+|------|------|------|
+| POST | `/pages` | 打开页面 |
+| GET | `/pages` | 列出所有页面 |
+| GET | `/pages/:id` | 页面详情 |
+| DELETE | `/pages/:id` | 关闭页面 |
+| POST | `/pages/:id/navigate` | 跳转 |
+| POST | `/pages/:id/click` | 点击元素 |
+| POST | `/pages/:id/type` | 输入文本 |
+| POST | `/pages/:id/scroll` | 滚动 |
+| POST | `/pages/:id/eval` | 执行 JS |
+| POST | `/pages/:id/wait` | 等待 |
+| GET | `/pages/:id/screenshot` | 截图（base64） |
+| GET | `/pages/:id/text` | 纯文本 |
+| GET | `/pages/:id/html` | HTML 源码 |
+| GET | `/pages/:id/cookies` | Cookie 列表 |
+| POST | `/pages/:id/cookies` | 设置 Cookie |
+| DELETE | `/pages/:id/cookies/:name` | 删除 Cookie |
+| GET | `/pages/:id/console` | 控制台日志 |
+| GET | `/pages/:id/network` | 网络请求日志 |
+| GET | `/profiles` | 指纹配置列表 |
+
+完整文档见 [API 文档](../development/api.md)。

 ## 集成方式

 ### 方式一：Function Calling（推荐）

-在 LLM 的 function/tool 定义中注册 VisionL 命令。大多数 LLM 平台（OpenAI、Claude、本地模型）都支持。
-
-**工具定义示例（OpenAI 格式）：**
+注册 `visionl_api` 工具，LLM 直接生成 HTTP 请求：

 ```json
 {
  "type": "function",
  "function": {
-    "name": "visionl",
-    "description": "通过 VisionL 浏览器操控网页。子命令: page open|list|info|kill|kill-all, click, type, scroll, navigate, eval, wait, screenshot, text, html, daemon start|stop|status, raw",
+    "name": "visionl_api",
+    "description": "通过 VisionL 浏览器操控网页。支持打开页面、点击、输入、截图、提取文本、执行JS、管理Cookie、查看网络请求等。",
    "parameters": {
      "type": "object",
      "properties": {
-        "command": {
+        "method": {
          "type": "string",
-          "description": "完整 visionl 命令，例如 'page open https://example.com'"
+          "enum": ["GET", "POST", "DELETE"],
+          "description": "HTTP 方法"
+        },
+        "path": {
+          "type": "string",
+          "description": "API 路径，如 /pages、/pages/baidu/text"
+        },
+        "body": {
+          "type": "object",
+          "description": "请求体（仅 POST 需要）"
        }
      },
-      "required": ["command"]
+      "required": ["method", "path"]
    }
  }
 }
 ```

-**使用流程：**
+### 使用流程

 1. LLM 决策需要访问网页
-2. LLM 生成 `visionl page open <url>` 调用
-3. 宿主程序在终端执行该命令，将 JSON 输出返回给 LLM
-4. LLM 解析结果，继续决策（截图、点击、提取文本等）
+2. LLM 调用 `visionl_api`：`POST /pages` 打开 baidu.com
+3. 宿主程序执行 HTTP 请求，将 JSON 结果返回 LLM
+4. LLM 解析结果，获得页面 ID `p_xxx`
+5. LLM 继续：`GET /pages/p_xxx/text` 读取内容
+6. 或：`POST /pages/p_xxx/click` 点击搜索

-### 方式二：MCP Server
+### 方式二：多工具注册

-可以封装一个 MCP（Model Context Protocol）Server，将 VisionL-CLI 包装为 MCP 工具：
+将每个操作注册为独立工具（更细粒度）：

-```typescript
-// 伪代码示意
-server.tool(
-  "visionl",
-  "通过 VisionL 浏览器操控网页",
-  { command: z.string() },
-  async ({ command }) => {
-    const { stdout } = await exec(`visionl ${command}`);
-    return JSON.parse(stdout);
+```json
+[
+  {
+    "name": "visionl_open",
+    "description": "打开网页",
+    "parameters": {
+      "url": { "type": "string" },
+      "alias": { "type": "string" }
    }
-);
+  },
+  {
+    "name": "visionl_text",
+    "description": "获取页面文本内容",
+    "parameters": {
+      "page_id": { "type": "string" }
+    }
+  },
+  {
+    "name": "visionl_click",
+    "description": "点击页面元素",
+    "parameters": {
+      "page_id": { "type": "string" },
+      "selector": { "type": "string" }
+    }
+  }
+]
 ```

-### 方式三：Agent 框架集成
-
-与 LangChain、AutoGPT、CrewAI 等框架集成，注册为自定义工具。
-
-**LangChain 示例：**
+### 方式三：LangChain 集成

 ```python
-from langchain.tools import Tool
-import subprocess, json
+from langchain.tools import BaseTool
+import requests

-def visionl_tool(command: str) -> str:
-    result = subprocess.run(
-        ["visionl", *command.split()],
-        capture_output=True, text=True
-    )
-    return result.stdout
+class VisionLTool(BaseTool):
+    name = "visionl"
+    description = "浏览器操控工具。API 基础 URL: http://127.0.0.1:9527"

-visionl = Tool(
-    name="visionl",
-    description="浏览器操控工具。命令示例：page open <url>, click <id> <sel>, text <id>",
-    func=visionl_tool,
-)
+    def _run(self, method: str, path: str, body: dict = None) -> str:
+        url = f"http://127.0.0.1:9527{path}"
+        resp = requests.request(method, url, json=body)
+        return resp.text
 ```

-## LLM Prompt 建议
-
-在系统 prompt 中添加以下指引：
+## LLM 系统提示词建议

 ```
-你可以使用 visionl 命令操控浏览器：
+你可以使用 visionl_api 工具操控浏览器：

-1. visionl page open <url> [--alias <name>]  — 打开页面
-2. visionl page list                           — 列出所有页面
-3. visionl text <id|alias>                     — 获取页面文本
-4. visionl screenshot <id|alias>               — 截图（返回 base64）
-5. visionl click <id|alias> <selector>         — 点击元素
-6. visionl type <id|alias> <selector> <text>   — 输入文本
-7. visionl page kill <id|alias>                — 关闭页面
+打开页面:   POST /pages  {"url":"...","alias":"..."}
+页面文本:   GET  /pages/{id}/text
+页面截图:   GET  /pages/{id}/screenshot    (返回 base64)
+点击元素:   POST /pages/{id}/click  {"selector":"#id"}
+输入文本:   POST /pages/{id}/type   {"selector":"#id","text":"..."}
+执行 JS:    POST /pages/{id}/eval   {"code":"..."}
+滚动页面:   POST /pages/{id}/scroll {"deltaY":300}
+等待加载:   POST /pages/{id}/wait   {"ms":2000}
+查看Cookie: GET  /pages/{id}/cookies
+网络日志:   GET  /pages/{id}/network
+关闭页面:   DELETE /pages/{id}

-所有命令返回 JSON。解析 ok 字段判断成功/失败。
-使用 --alias 给页面起别名方便后续引用。
+所有接口返回 {"ok":true,"data":{...}} 或 {"ok":false,"error":{...}}。
+打开页面后记录返回的 page_id，后续操作使用该 id。
+页面在被显式 kill 之前永远存活，可跨多轮对话复用。
 ```

-## 多页面管理
+## 多页面并行管理

-LLM 可以同时打开多个页面，通过别名区分：
+LLM 同时打开多个页面，通过别名区分：

 ```
-LLM: visionl page open https://docs.python.org --alias py
-LLM: visionl page open https://developer.mozilla.org --alias mdn
-LLM: visionl text py     # 读 Python 文档
-LLM: visionl text mdn    # 读 MDN 文档
+LLM: POST /pages {"url":"https://docs.python.org","alias":"py"}
+→ {"ok":true,"data":{"id":"p_aaa",...}}
+
+LLM: POST /pages {"url":"https://developer.mozilla.org","alias":"mdn"}
+→ {"ok":true,"data":{"id":"p_bbb",...}}
+
+LLM: GET /pages/py/text     # 读 Python 文档
+LLM: GET /pages/mdn/text    # 读 MDN 文档
 ```

 ## 错误处理

-LLM 应检查返回的 `ok` 字段：
-
 ```json
 // 失败示例
 {"ok":false,"error":{"code":"PAGE_NOT_FOUND","message":"页面 py 不存在"}}
 ```

-常见错误及处理：
+常见错误码及处理：

-| 错误码 | 处理建议 |
-|--------|---------|
-| `PAGE_NOT_FOUND` | 页面可能已被关闭，重新打开 |
-| `DAEMON_UNREACHABLE` | 等待几秒重试（自动拉起正在启动） |
-| `TIMEOUT` | 页面加载慢，重试或增加等待时间 |
-| `ALIAS_EXISTS` | 换一个别名或直接用 page ID |
+| 错误码 | HTTP | 处理建议 |
+|--------|------|---------|
+| `PAGE_NOT_FOUND` | 404 | 页面已关闭，重新打开 |
+| `DAEMON_UNREACHABLE` | 502 | 启动 daemon 或稍后重试 |
+| `TIMEOUT` | 408 | 页面加载慢，重试或增加等待 |
+| `ALIAS_EXISTS` | 409 | 换别名或直接用 page_id |

-## 安全注意事项
+## 反检测能力

- VisionL daemon 仅监听 127.0.0.1，外部不可访问
- 执行的 JS 代码在页面沙箱内运行，无法逃逸到宿主机
- LLM 应避免在不可信页面执行敏感操作（自动填写密码等）
+VisionL 内置多层反检测，使自动化访问尽可能不被简单人机验证拦截：
+
+- `navigator.webdriver` → `false`
+- 真实 Chrome User-Agent 和请求头
+- Canvas/WebGL/Audio 指纹加噪
+- 屏幕分辨率和视口合理性
+- 权限状态模拟
+- 3 套指纹模版可切换
+
+详见 [反检测设计文档](../development/anti-detection.md)。
@@ -1,89 +1,138 @@
 # VisionL 快速开始

+## 环境要求
+
+- Node.js >= 18
+- Chromium 浏览器（系统自带或 Playwright 安装）
+- Linux/macOS/Windows（Android 需配合 Ubuntu proot 容器）
+
 ## 安装

 ```bash
-# 1. 克隆仓库
 git clone ssh://git@git.yeij.top:2222/AskaEth/VisionL.git
 cd VisionL
-
-# 2. 安装依赖
-npm install
-
-# 3. 安装 Chromium 浏览器
-npx playwright install chromium
-
-# 4. 构建
+npm install --registry=https://registry.npmmirror.com
+npx playwright install chromium  # 如果没有系统 Chromium
 npm run build
+```

-# 5. 全局安装 CLI（可选）
-cd packages/cli && npm link
+## 启动
+
+```bash
+# 方式一：使用内置启动脚本
+node start-daemon.js &
+
+# 方式二：直接运行 daemon
+VISIONL_PORT=9527 node packages/daemon/dist/server.js &
 ```

 ## 基本使用

-### 启动 daemon
+所有命令输出 JSON 格式，可使用 `--pretty` 切换为人类可读。
+
+### 打开页面

 ```bash
-visionl daemon start
-# ✓ Daemon 已启动 (端口 9527, PID 12345)
+curl -X POST http://127.0.0.1:9527/pages \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://www.baidu.com","alias":"baidu"}'
 ```

-### 打开一个页面
-
-```bash
-visionl page open https://www.baidu.com --alias baidu
-# {"ok":true,"data":{"id":"p_a1b2c3d4","url":"https://www.baidu.com","alias":"baidu","title":"百度一下，你就知道","status":"active"}}
+返回：
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "p_f1990959",
+    "url": "https://www.baidu.com",
+    "alias": "baidu",
+    "title": "百度一下，你就知道",
+    "status": "active",
+    "profile": "desktop-chrome"
+  }
+}
 ```

 ### 获取页面文本

 ```bash
-visionl text baidu
-# {"ok":true,"data":{"text":"百度一下，你就知道\n..."}}
+curl http://127.0.0.1:9527/pages/baidu/text
 ```

 ### 搜索

 ```bash
-visionl type baidu "#kw" "VisionL"
-visionl click baidu "#su"
+# 输入搜索词
+curl -X POST http://127.0.0.1:9527/pages/baidu/type \
+  -H 'Content-Type: application/json' \
+  -d '{"selector":"#kw","text":"VisionL"}'
+
+# 点击搜索按钮
+curl -X POST http://127.0.0.1:9527/pages/baidu/click \
+  -H 'Content-Type: application/json' \
+  -d '{"selector":"#su"}'
+
+# 等待结果加载
+curl -X POST http://127.0.0.1:9527/pages/baidu/wait \
+  -H 'Content-Type: application/json' \
+  -d '{"ms":2000}'
+
+# 获取搜索结果
+curl http://127.0.0.1:9527/pages/baidu/text
 ```

 ### 截图

 ```bash
-visionl screenshot baidu -o result.png
+curl http://127.0.0.1:9527/pages/baidu/screenshot
+# 返回 base64 编码的 PNG 图片
+```
+
+### 执行 JavaScript
+
+```bash
+curl -X POST http://127.0.0.1:9527/pages/baidu/eval \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"document.title"}'
+# {"ok":true,"data":{"result":"百度一下，你就知道"}}
+```
+
+### Cookie 管理
+
+```bash
+# 查看所有 Cookie
+curl http://127.0.0.1:9527/pages/baidu/cookies
+
+# 设置 Cookie
+curl -X POST http://127.0.0.1:9527/pages/baidu/cookies \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"mycookie","value":"hello","domain":".baidu.com"}'
+```
+
+### 网络请求监控
+
+```bash
+# 查看网络请求日志
+curl http://127.0.0.1:9527/pages/baidu/network
+```
+
+### 查看指纹配置
+
+```bash
+curl http://127.0.0.1:9527/profiles
+# [{"id":"desktop-chrome","name":"桌面 Chrome (通用)"},
+#  {"id":"desktop-windows","name":"桌面 Chrome (Windows)"},
+#  {"id":"desktop-mac","name":"桌面 Chrome (macOS)"}]
 ```

 ### 关闭页面

 ```bash
-visionl page kill baidu
-# {"ok":true,"data":null}
+curl -X DELETE http://127.0.0.1:9527/pages/baidu
 ```

-### 停止 daemon
+### 查看所有页面

 ```bash
-visionl daemon stop
-```
-
-## 无需手动启动 daemon
-
-CLI 会自动检测 daemon 是否运行，未运行则自动启动：
-
-```bash
-# 直接使用，CLI 自动拉起 daemon
-visionl page open https://example.com
-
-# 关闭所有页面（daemon 继续运行）
-visionl page kill-all
-```
-
-## 查看所有页面
-
-```bash
-visionl page list
-# {"ok":true,"data":[{"id":"p_xxx","url":"...","alias":"...","title":"...","status":"active"}]}
+curl http://127.0.0.1:9527/pages
 ```
@@ -11,7 +11,7 @@
      "devDependencies": {
        "@types/node": "^22.0.0",
        "typescript": "^5.7.0",
-        "vitest": "^3.0.0"
+        "vitest": "^3.2.7"
      }
    },
    "node_modules/@esbuild/aix-ppc64": {
@@ -2247,6 +2247,27 @@
      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
      "license": "ISC"
    },
+    "node_modules/ws": {
+      "version": "8.21.3",
+      "resolved": "https://registry.npmmirror.com/ws/-/ws-8.21.3.tgz",
+      "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
    "packages/cli": {
      "name": "@visionl/cli",
      "version": "0.1.0",
@@ -2272,7 +2293,8 @@
        "@visionl/core": "*",
        "playwright": "^1.52.0",
        "playwright-extra": "^4.3.0",
-        "puppeteer-extra-plugin-stealth": "^2.11.0"
+        "puppeteer-extra-plugin-stealth": "^2.11.0",
+        "ws": "^8.21.3"
      },
      "devDependencies": {
        "@types/ws": "^8.0.0"
@@ -1,7 +1,9 @@
 {
  "name": "visionl",
  "private": true,
-  "workspaces": ["packages/*"],
+  "workspaces": [
+    "packages/*"
+  ],
  "scripts": {
    "typecheck": "tsc -b",
    "build": "tsc -b",
@@ -9,8 +11,11 @@
    "test:watch": "vitest"
  },
  "devDependencies": {
+    "@types/node": "^22.0.0",
    "typescript": "^5.7.0",
-    "vitest": "^3.0.0",
-    "@types/node": "^22.0.0"
+    "vitest": "^3.2.7"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
  }
 }
@@ -0,0 +1,39 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { readPidfile, isProcessAlive } from '@visionl/daemon/dist/pidfile.js';
+import { VisionLClient } from '@visionl/core';
+
+const POLL_INTERVAL_MS = 100;
+const MAX_WAIT_MS = 3000;
+
+export async function ensureDaemonRunning(port: number): Promise<VisionLClient> {
+  const client = new VisionLClient(`http://127.0.0.1:${port}`);
+
+  if (await client.health()) {
+    return client;
+  }
+
+  const pidInfo = readPidfile();
+  if (pidInfo && isProcessAlive(pidInfo.pid)) {
+    if (await client.health()) {
+      return client;
+    }
+  }
+
+  const daemonEntryPath = path.resolve(__dirname, '../../daemon/dist/server.js');
+  spawn('node', [daemonEntryPath], {
+    env: { ...process.env, VISIONL_PORT: String(port) },
+    stdio: 'ignore',
+    detached: true,
+  }).unref();
+
+  const startTime = Date.now();
+  while (Date.now() - startTime < MAX_WAIT_MS) {
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    if (await client.health()) {
+      return client;
+    }
+  }
+
+  throw new Error('DAEMON_UNREACHABLE');
+}
@@ -1,2 +1,166 @@
-// @visionl/cli — placeholder, to be implemented in Task 4
-export const CLI_VERSION = '0.1.0';
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { ensureDaemonRunning } from './auto-daemon.js';
+import { safeStringify, VisionLClient } from '@visionl/core';
+
+const DEFAULT_PORT = 9527;
+
+const program = new Command();
+program.name('visionl').version('0.1.0');
+
+program.option('-p, --port <n>', 'daemon port', String(DEFAULT_PORT));
+program.option('--pretty', 'human-readable output');
+
+function getClient(): Promise<VisionLClient> {
+  const opts = program.opts<{ port: string }>();
+  const port = parseInt(opts.port, 10) || DEFAULT_PORT;
+  return ensureDaemonRunning(port);
+}
+
+function print(result: unknown): void {
+  const opts = program.opts<{ pretty: boolean }>();
+  if (opts.pretty) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(safeStringify(result));
+  }
+}
+
+// health — check daemon health
+program.command('health')
+  .description('Check daemon health')
+  .action(async () => {
+    const client = await getClient();
+    const ok = await client.health();
+    print({ ok });
+  });
+
+// pages — page management
+program.command('open <url>')
+  .description('Open a URL in a new page')
+  .option('-a, --alias <alias>', 'Page alias')
+  .option('-p, --profile <profile>', 'Browser profile')
+  .action(async (url: string, options: { alias?: string; profile?: string }) => {
+    const client = await getClient();
+    const result = await client.openPage(url, options.alias, options.profile);
+    print(result);
+  });
+
+program.command('list')
+  .description('List all open pages')
+  .action(async () => {
+    const client = await getClient();
+    const result = await client.listPages();
+    print(result);
+  });
+
+program.command('get <id>')
+  .description('Get page info by ID or alias')
+  .action(async (id: string) => {
+    const client = await getClient();
+    const result = await client.getPage(id);
+    print(result);
+  });
+
+program.command('kill <id>')
+  .description('Close a page by ID or alias')
+  .action(async (id: string) => {
+    const client = await getClient();
+    const result = await client.killPage(id);
+    print(result);
+  });
+
+// navigation — page interactions
+program.command('navigate <id> <url>')
+  .description('Navigate an existing page to a URL')
+  .action(async (id: string, url: string) => {
+    const client = await getClient();
+    const result = await client.navigate(id, url);
+    print(result);
+  });
+
+program.command('click <id> <selector>')
+  .description('Click an element on a page')
+  .action(async (id: string, selector: string) => {
+    const client = await getClient();
+    const result = await client.click(id, selector);
+    print(result);
+  });
+
+program.command('type <id> <selector> <text>')
+  .description('Type text into an element')
+  .action(async (id: string, selector: string, text: string) => {
+    const client = await getClient();
+    const result = await client.type(id, selector, text);
+    print(result);
+  });
+
+program.command('scroll <id>')
+  .description('Scroll on a page')
+  .option('-y, --delta-y <n>', 'Vertical scroll delta', '0')
+  .option('-b, --to-bottom', 'Scroll to bottom')
+  .action(async (id: string, options: { deltaY: string; toBottom?: boolean }) => {
+    const client = await getClient();
+    const result = await client.scroll(id, {
+      deltaY: parseInt(options.deltaY, 10) || undefined,
+      toBottom: options.toBottom,
+    });
+    print(result);
+  });
+
+program.command('eval <id> <code>')
+  .description('Evaluate JavaScript on a page')
+  .action(async (id: string, code: string) => {
+    const client = await getClient();
+    const result = await client.eval(id, code);
+    print(result);
+  });
+
+program.command('wait <id>')
+  .description('Wait for selector or duration on a page')
+  .option('-s, --selector <selector>', 'Wait for CSS selector')
+  .option('-m, --ms <ms>', 'Wait time in milliseconds')
+  .action(async (id: string, options: { selector?: string; ms?: string }) => {
+    const client = await getClient();
+    const result = await client.wait(id, {
+      selector: options.selector,
+      ms: options.ms ? parseInt(options.ms, 10) : undefined,
+    });
+    print(result);
+  });
+
+// content — page content retrieval
+program.command('screenshot <id>')
+  .description('Take a screenshot of a page (returns base64)')
+  .action(async (id: string) => {
+    const client = await getClient();
+    const result = await client.screenshot(id);
+    print(result);
+  });
+
+program.command('text <id>')
+  .description('Get the text content of a page')
+  .action(async (id: string) => {
+    const client = await getClient();
+    const result = await client.text(id);
+    print(result);
+  });
+
+program.command('html <id>')
+  .description('Get the HTML source of a page')
+  .action(async (id: string) => {
+    const client = await getClient();
+    const result = await client.html(id);
+    print(result);
+  });
+
+// profiles
+program.command('profiles')
+  .description('List available fingerprint profiles')
+  .action(async () => {
+    const client = await getClient();
+    const result = await client.getProfiles();
+    print(result);
+  });
+
+program.parse();
@@ -5,5 +5,5 @@
    "rootDir": "./src"
  },
  "include": ["src"],
-  "references": [{ "path": "../core" }]
+  "references": [{ "path": "../core" }, { "path": "../daemon" }]
 }
@@ -1,6 +1,6 @@
 export { type PageInfo } from './types/page.js';
 export { type ApiResponse, ErrorCode } from './types/api.js';
-export { type WsEvent } from './types/ws.js';
+export { type WsEvent, type ConsoleEntry, type NetworkEntry } from './types/ws.js';
 export {
  type FingerprintProfile,
  type FingerprintPermissions,
@@ -1,10 +1,29 @@
 // WebSocket event type definitions / WebSocket 事件类型定义
 import type { PageInfo } from './page.js';

+export interface ConsoleEntry {
+  level: string;
+  text: string;
+  timestamp: number;
+}
+
+export interface NetworkEntry {
+  type: 'request' | 'response' | 'failed';
+  url: string;
+  method?: string;
+  status?: number;
+  headers?: Record<string, string>;
+  failure?: string;
+  timestamp: number;
+}
+
 export type WsEvent =
  | { type: 'page:created'; data: PageInfo }
  | { type: 'page:closed'; data: { id: string } }
  | { type: 'page:navigated'; data: { id: string; url: string; title: string } }
  | { type: 'page:crashed'; data: { id: string; error: string } }
  | { type: 'page:console'; data: { id: string; level: string; text: string } }
+  | { type: 'page:network:request'; data: { id: string; url: string; method: string; headers: Record<string, string> } }
+  | { type: 'page:network:response'; data: { id: string; url: string; status: number; headers: Record<string, string> } }
+  | { type: 'page:network:failed'; data: { id: string; url: string; failure: string } }
  | { type: 'page:detection:warning'; data: { id: string; level: string; detail: string } };
@@ -12,7 +12,8 @@
    "@visionl/core": "*",
    "playwright": "^1.52.0",
    "playwright-extra": "^4.3.0",
-    "puppeteer-extra-plugin-stealth": "^2.11.0"
+    "puppeteer-extra-plugin-stealth": "^2.11.0",
+    "ws": "^8.21.3"
  },
  "devDependencies": {
    "@types/ws": "^8.0.0"
@@ -2,10 +2,14 @@
 import { chromium } from 'playwright-extra';
 import StealthPlugin from 'puppeteer-extra-plugin-stealth';
 import type { Browser, BrowserContext, Page } from 'playwright';
-import type { FingerprintProfile, PageInfo } from '@visionl/core';
-import { PageRegistry } from './page-registry.js';
+import type { FingerprintProfile, PageInfo, ConsoleEntry, NetworkEntry } from '@visionl/core';
+import { PageRegistry, type RegisteredPage } from './page-registry.js';
 import { getProfile } from './stealth/profiles/index.js';
 import { applyStealth } from './stealth/index.js';
+import { broadcast } from './ws-relay.js';
+
+const MAX_CONSOLE_BUFFER = 100;
+const MAX_NETWORK_BUFFER = 200;

 // Apply stealth plugin once at module level / 模块级别一次性注入隐身插件
 chromium.use(StealthPlugin());
@@ -80,19 +84,104 @@ export class BrowserManager {
    const info: PageInfo = { id, url, alias, title, status: 'active', profile: this.profile.id };
    this.registry.add(info, page, context);

+    this.setupPageListeners(page, id);
+
+    // Broadcast page created event / 广播页面创建事件
+    broadcast({ type: 'page:created', data: info });
+    console.log(`[browser-manager] Page created: ${id} → ${url}`);
+
    return info;
  }

+  private setupPageListeners(page: Page, id: string): void {
+    const entry = this.registry.get(id);
+    if (!entry) return;
+
+    // Console monitoring / 控制台监控
+    page.on('console', (msg) => {
+      const level = msg.type();
+      const text = msg.text();
+      const consoleEntry: ConsoleEntry = { level, text, timestamp: Date.now() };
+      this.pushToBuffer(entry.consoleLog, consoleEntry, MAX_CONSOLE_BUFFER);
+      broadcast({ type: 'page:console', data: { id, level, text } });
+    });
+
+    // Network request monitoring / 网络请求监控
+    page.on('request', (req) => {
+      const netEntry: NetworkEntry = {
+        type: 'request',
+        url: req.url(),
+        method: req.method(),
+        headers: req.headers(),
+        timestamp: Date.now(),
+      };
+      this.pushToBuffer(entry.networkLog, netEntry, MAX_NETWORK_BUFFER);
+      broadcast({
+        type: 'page:network:request',
+        data: { id, url: req.url(), method: req.method(), headers: req.headers() },
+      });
+    });
+
+    // Network response monitoring / 网络响应监控
+    page.on('response', (res) => {
+      const netEntry: NetworkEntry = {
+        type: 'response',
+        url: res.url(),
+        status: res.status(),
+        headers: res.headers(),
+        timestamp: Date.now(),
+      };
+      this.pushToBuffer(entry.networkLog, netEntry, MAX_NETWORK_BUFFER);
+      broadcast({
+        type: 'page:network:response',
+        data: { id, url: res.url(), status: res.status(), headers: res.headers() },
+      });
+    });
+
+    // Network failure monitoring / 网络失败监控
+    page.on('requestfailed', (req) => {
+      const failureText = req.failure()?.errorText || 'Unknown error';
+      const netEntry: NetworkEntry = {
+        type: 'failed',
+        url: req.url(),
+        failure: failureText,
+        timestamp: Date.now(),
+      };
+      this.pushToBuffer(entry.networkLog, netEntry, MAX_NETWORK_BUFFER);
+      broadcast({
+        type: 'page:network:failed',
+        data: { id, url: req.url(), failure: failureText },
+      });
+    });
+
+    // Page crash handling / 页面崩溃处理
+    page.on('crash', () => {
+      console.error(`[browser-manager] Page crashed: ${id}`);
+      entry.info.status = 'crashed';
+      broadcast({ type: 'page:crashed', data: { id, error: 'Page crashed' } });
+    });
+  }
+
+  private pushToBuffer<T>(buffer: T[], item: T, maxSize: number): void {
+    buffer.push(item);
+    if (buffer.length > maxSize) {
+      buffer.shift();
+    }
+  }
+
  async closePage(idOrAlias: string): Promise<void> {
    const entry = this.registry.findByIdOrAlias(idOrAlias);
    if (!entry) {
      throw Object.assign(new Error(`Page "${idOrAlias}" not found`), { code: 'PAGE_NOT_FOUND' });
    }
+    const pageId = entry.info.id;
    await entry.context.close();
-    this.registry.remove(entry.info.id);
+    this.registry.remove(pageId);
+    broadcast({ type: 'page:closed', data: { id: pageId } });
+    console.log(`[browser-manager] Page closed: ${pageId}`);
  }

-  getPage(idOrAlias: string) {
+  getPage(idOrAlias: string): RegisteredPage | undefined {
    return this.registry.findByIdOrAlias(idOrAlias);
  }

@@ -1,11 +1,13 @@
 // PageRegistry — tracks active Playwright pages by ID and alias / 页面注册表，通过 ID 和别名追踪活跃页面
 import type { Page, BrowserContext } from 'playwright';
-import type { PageInfo } from '@visionl/core';
+import type { PageInfo, ConsoleEntry, NetworkEntry } from '@visionl/core';

 export interface RegisteredPage {
  info: PageInfo;
  page: Page;
  context: BrowserContext;
+  consoleLog: ConsoleEntry[];
+  networkLog: NetworkEntry[];
 }

 export class PageRegistry {
@@ -13,7 +15,7 @@ export class PageRegistry {
  private aliasMap = new Map<string, string>(); // alias → id

  add(info: PageInfo, page: Page, context: BrowserContext): void {
-    this.pages.set(info.id, { info, page, context });
+    this.pages.set(info.id, { info, page, context, consoleLog: [], networkLog: [] });
    if (info.alias) {
      this.aliasMap.set(info.alias, info.id);
    }
@@ -37,6 +37,34 @@ export function pageRoutes(bm: BrowserManager): RouteHandler {
      return true;
    }

+    // GET /pages/:id/console — console history / 控制台历史
+    if (req.method === 'GET' && segments[0] === 'pages' && segments[2] === 'console' && segments.length === 3) {
+      const id = segments[1];
+      const entry = bm.getPage(id);
+      if (!entry) {
+        res.writeHead(404);
+        res.end(safeStringify({ ok: false, error: { code: 'PAGE_NOT_FOUND', message: `Page "${id}" not found` } }));
+        return true;
+      }
+      res.writeHead(200);
+      res.end(safeStringify({ ok: true, data: entry.consoleLog }));
+      return true;
+    }
+
+    // GET /pages/:id/network — network history / 网络请求历史
+    if (req.method === 'GET' && segments[0] === 'pages' && segments[2] === 'network' && segments.length === 3) {
+      const id = segments[1];
+      const entry = bm.getPage(id);
+      if (!entry) {
+        res.writeHead(404);
+        res.end(safeStringify({ ok: false, error: { code: 'PAGE_NOT_FOUND', message: `Page "${id}" not found` } }));
+        return true;
+      }
+      res.writeHead(200);
+      res.end(safeStringify({ ok: true, data: entry.networkLog }));
+      return true;
+    }
+
    // GET /pages/:id
    // DELETE /pages/:id
    if (segments[0] === 'pages' && segments.length === 2) {
@@ -0,0 +1,14 @@
+// Profiles API route — list available fingerprint profiles / 指纹配置 API 路由
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { listProfiles } from '../stealth/index.js';
+
+export function profilesRoute(req: IncomingMessage, res: ServerResponse): boolean {
+  const url = new URL(req.url || '/', 'http://localhost');
+  if (req.method === 'GET' && url.pathname === '/profiles') {
+    const data = listProfiles();
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, data }));
+    return true;
+  }
+  return false;
+}
@@ -3,10 +3,12 @@ import { healthRoute } from './routes/health.js';
 import { pageRoutes } from './routes/pages.js';
 import { contentRoutes } from './routes/content.js';
 import { actionRoutes } from './routes/actions.js';
+import { profilesRoute } from './routes/profiles.js';
 import type { BrowserManager } from './browser-manager.js';
+import { createWsRelay } from './ws-relay.js';

 export function startServer(port: number, browserManager?: BrowserManager): Promise<http.Server> {
-  const routes = [healthRoute];
+  const routes = [healthRoute, profilesRoute];
  if (browserManager) {
    routes.push(pageRoutes(browserManager));
    routes.push(contentRoutes(browserManager));
@@ -24,11 +26,15 @@ export function startServer(port: number, browserManager?: BrowserManager): Prom

    server.listen(port, '127.0.0.1', () => {
      console.log(`[daemon] VisionL daemon started on http://127.0.0.1:${port}`);
+      createWsRelay(server);
      resolve(server);
    });
  });
 }

-// Direct start when running as script
+// Direct start when running as script (not when imported in tests)
+// When imported by other modules, the caller is responsible for calling startServer()
+if (process.argv[1] && (process.argv[1].endsWith('server.js') || process.argv[1].endsWith('server.ts'))) {
  const port = parseInt(process.env.VISIONL_PORT || '9527', 10);
  startServer(port);
+}
@@ -0,0 +1,39 @@
+// WebSocket relay — broadcasts WsEvent JSON to all connected clients / WebSocket 中继，向所有连接的客户端广播事件
+import type http from 'node:http';
+import { WebSocketServer, WebSocket } from 'ws';
+import type { WsEvent } from '@visionl/core';
+
+let wss: WebSocketServer | null = null;
+
+export function createWsRelay(server: http.Server): WebSocketServer {
+  wss = new WebSocketServer({ server, path: '/ws' });
+
+  wss.on('connection', (ws: WebSocket) => {
+    console.log('[ws-relay] Client connected, total:', wss!.clients.size);
+
+    ws.on('close', () => {
+      console.log('[ws-relay] Client disconnected, total:', wss!.clients.size);
+    });
+
+    ws.on('error', (err: Error) => {
+      console.error('[ws-relay] Client error:', err.message);
+    });
+  });
+
+  wss.on('error', (err: Error) => {
+    console.error('[ws-relay] Server error:', err.message);
+  });
+
+  console.log('[ws-relay] WebSocket relay attached at path /ws');
+  return wss;
+}
+
+export function broadcast(event: WsEvent): void {
+  if (!wss) return;
+  const payload = JSON.stringify(event);
+  for (const client of wss.clients) {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(payload);
+    }
+  }
+}
Author	SHA1	Message	Date
AskaEth	36780493a5	docs: update user-facing docs with real test results from baidu.com verification	2026-08-12 21:42:41 +08:00
AskaEth	9ec6c9add3	fix: guard auto-start server to only run when executed directly, not when imported by tests	2026-08-12 21:30:35 +08:00
AskaEth	452581c3b5	feat: add GET /profiles route	2026-08-12 21:29:47 +08:00
AskaEth	e79590a6d8	feat(daemon): add WebSocket relay with console/network monitoring - Add ws-relay.ts: WebSocket server at /ws with broadcast function - Add network event types (request/response/failed) to core ws.ts types - Add ConsoleEntry and NetworkEntry types - Add consoleLog and networkLog buffers to PageRegistry (100/200 max) - Add console listener in createPage: broadcasts page:console events - Add network listeners (request/response/requestfailed) in createPage - Add page crash handler broadcasting page:crashed events - Add history endpoints: GET /pages/:id/console and GET /pages/:id/network - Integrate createWsRelay in server.ts startup - Bump ws from devDependency to full dependency	2026-08-12 21:28:02 +08:00
AskaEth	b843eea9ae	feat(cli): implement CLI entry point with auto-daemon launcher (Task 18) - Add auto-daemon.ts: ensureDaemonRunning() checks health, reads pidfile, spawns daemon if needed, polls health up to 3s - Rewrite index.ts: commander-based CLI with all subcommands (health, open, list, get, kill, navigate, click, type, scroll, eval, wait, screenshot, text, html, profiles) - Add daemon project reference to cli tsconfig	2026-08-12 21:24:07 +08:00