add the query bypass function

Author: AMOS144

.gitignore

@@ -40,7 +40,6 @@ htmlcov/
 .nox/
 
 # Project
-zerotoken_adaptive.db
 trajectories/
 *.db
 *.sqlite3

CLAUDE.md

@@ -130,7 +130,7 @@ AI Agent (ReAct 模式)
 ## MCP 工具列表
 
 ### Browser Tools
-- `browser_init` - 初始化浏览器；可选 **stealth**（默认 false）：为 true 时启用反检测（启动参数 + 指纹伪装），适合易被云盾/反爬拦截的场景
+- `browser_init` - 初始化浏览器；可选 **stealth**（默认 false）：为 true 时启用反检测，包含：启动参数（--disable-blink-features=AutomationControlled 等）、navigator 指纹伪装（webdriver、plugins、languages、platform、hardwareConcurrency、deviceMemory、maxTouchPoints）、Sec-CH-UA 等 HTTP 头、WebGL 指纹伪装（UNMASKED_VENDOR/RENDERER），适合易被云盾/反爬拦截的场景（如 B 站、小红书）
 - `browser_close` - 关闭浏览器
 - `browser_open` / `browser_click` / `browser_input` / `browser_get_text` / `browser_get_html` / `browser_wait_for` / `browser_extract_data` - 原子操作，返回 OperationRecord
 - 上述返回 record 的工具支持可选参数 **include_screenshot**（默认 true）；设为 false 时响应中不包含截图，可减少 token
@@ -141,7 +141,7 @@ AI Agent (ReAct 模式)
 - `trajectory_start` - 开始轨迹记录
 - `trajectory_complete` - 完成轨迹并导出（含 fuzzy_point 的 AI 提示）
 - `trajectory_get` - 获取当前未结束轨迹（format: json | ai_prompt）
-- `trajectory_list` - 列出已保存轨迹（可选 limit、since），返回 task_id、goal、operations_count、file、saved_at
+- `trajectory_list` - 列出已保存轨迹（可选 limit、since），返回 id、task_id、goal、created_at
 - `trajectory_load` - 按 task_id 加载已保存轨迹（format: ai_prompt | json），供 Skill 生成脚本等使用
 - `trajectory_delete` - 按 task_id 删除已保存轨迹，防止记录过多；建议先 `trajectory_list` 再对不需要的 task_id 调用
 
@@ -171,7 +171,7 @@ ai_prompt = result["ai_prompt"]
 
 # 事后按需获取已保存轨迹（供 Skill 等使用）
 list_result = await mcp_call("trajectory_list", {"limit": 20})
-# list_result["trajectories"]: [{ task_id, goal, operations_count, file, saved_at }, ...]
+# list_result["trajectories"]: [{ id, task_id, goal, created_at }, ...]
 load_result = await mcp_call("trajectory_load", {"task_id": "login_demo", "format": "ai_prompt"})
 # load_result["ai_prompt"] 或 load_result["trajectory"]（format=json 时）
 ```
@@ -187,7 +187,7 @@ load_result = await mcp_call("trajectory_load", {"task_id": "login_demo", "forma
 - BrowserController 必须保持单例
 - 截图数据较大时，可传 `include_screenshot: false` 减少响应体积；轨迹仍会完整记录
 - 建议通过 `trajectory_list` 查看已保存轨迹，对不需要的 `task_id` 调用 `trajectory_delete`，避免本地记录过多
-- 自适应定位：对关键元素首次操作时传 `auto_save: true`，网站改版后同一选择器失效时传 `adaptive: true` 可自动按指纹重定位；指纹存于本地 SQLite（默认 `zerotoken_adaptive.db`）
+- 自适应定位：对关键元素首次操作时传 `auto_save: true`，网站改版后同一选择器失效时传 `adaptive: true` 可自动按指纹重定位；指纹存于主库 `zerotoken.db` 的 fingerprints 表
 
 ## 扩展方向
 

README.md

@@ -1,5 +1,7 @@
 # ZeroToken
 
+<!-- mcp-name: io.github.AMOS144/zerotoken -->
+
 [![CI](https://github.com/AMOS144/zerotoken/actions/workflows/ci.yml/badge.svg)](https://github.com/AMOS144/zerotoken/actions/workflows/ci.yml)
 
 **ZeroToken - Record once, automate forever.**
@@ -12,14 +14,14 @@
 
 ZeroToken 推荐与 OpenClaw 搭配，用作浏览器执行层与轨迹重放引擎。
 
-- **MCP 已通过 Marketplace 安装时**：在支持 MCP 的客户端（如 Cursor / OpenClaw）中启用名为 `zerotoken` 的 MCP server，然后在 OpenClaw 安装 `zerotoken-openclaw` Skill（见 `docs/skills.md`），即可在工作流中直接使用 ZeroToken 的浏览器工具和轨迹脚本。
+- **MCPorter / ClawHub 安装**：通过 MCPorter 或 OpenClaw 的 ClawHub 安装 ZeroToken MCP，配置会自动写入 `openclaw.json`。安装后启用名为 `zerotoken` 的 MCP server，再安装 `zerotoken-openclaw` Skill（见 `docs/skills.md`）即可使用。
+- **MCP 已通过 Marketplace 安装时**：在支持 MCP 的客户端（如 Cursor / OpenClaw）中启用名为 `zerotoken` 的 MCP server，然后在 OpenClaw 安装 `zerotoken-openclaw` Skill，即可在工作流中直接使用 ZeroToken 的浏览器工具和轨迹脚本。
 - **本地开发 / 调试场景**：按照下文「安装」「快速开始」章节启动本地 `mcp_server.py`，并在客户端中将其注册为 id 为 `zerotoken` 的 MCP server，再搭配 `zerotoken-openclaw` Skill 使用。
 
 典型工作流示例和脚本格式说明见：
 
 - `docs/skills.md`：OpenClaw Skill 安装与约定
 - `skills/zerotoken-openclaw/SKILL.md`：教会 Agent 何时录制轨迹、何时生成脚本、如何以低 Token 成本重放
-- `docs/examples/*.md`：基础示例与稳定性测试示例
 
 ## 核心理念
 
@@ -171,6 +173,36 @@ graph TB
 
 ## 安装
 
+### 通过 MCPorter 安装（OpenClaw 推荐）
+
+ZeroToken 提供 `server.json`，与 MCP Registry 及 MCPorter 兼容。通过 MCPorter 可自动发现、安装并配置到 OpenClaw：
+
+```bash
+# 安装 MCPorter
+npm install -g mcporter
+
+# 搜索并安装 ZeroToken（安装到 OpenClaw）
+mcporter search zerotoken
+mcporter install zerotoken --target openclaw --configure
+```
+
+若 MCPorter 暂未收录，可手动在 `~/.openclaw/openclaw.json` 的 `mcpServers` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "zerotoken": {
+      "command": "zerotoken-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+安装后需执行 `playwright install chromium` 安装浏览器依赖。若使用 uv，将 `command` 改为 `uv`、`args` 改为 `["run", "zerotoken-mcp"]`。
+
+### 本地开发 / pip 安装
+
 ```bash
 # 克隆项目
 git clone https://github.com/AMOS144/zerotoken.git
@@ -179,6 +211,9 @@ cd zerotoken
 # 安装依赖
 uv sync
 
+# 或 pip 安装
+pip install zerotoken
+
 # 安装 Playwright 浏览器
 playwright install chromium
 ```
@@ -335,9 +370,8 @@ zerotoken/
 │   ├── selector.py           # SmartSelector - 智能选择器
 │   ├── wait_strategy.py      # SmartWait - 等待策略
 │   └── recovery.py           # ErrorRecovery - 错误恢复
-├── trajectories/             # 轨迹文件存储
+├── zerotoken.db              # SQLite 数据库（脚本/轨迹/会话，运行时生成）
 ├── mcp_server.py             # MCP Server 入口
-├── examples.py               # 使用示例
 └── README.md
 ```
 
@@ -348,8 +382,6 @@ zerotoken/
 3. **数据采集** - 定时抓取网页数据
 4. **自动化测试** - 记录测试步骤并回放
 
-更多示例见根目录 `examples.py`、`examples_stability.py`。
-
 **OpenClaw 配套 Skill**：见 [docs/skills.md](docs/skills.md)，用于定时/重复任务时按轨迹重放、降低 Token 消耗。
 
 ## 参与贡献