# https://github.com/lavague-ai/LaVague 项目说明书

生成时间：2026-06-23 13:57:40 UTC

## 目录

- [Core Framework Architecture](#page-1)
- [Browser Drivers & LLM Integrations](#page-2)
- [Companion Tools: LaVague QA, Server, Tests, Gradio & Chrome Extension](#page-3)
- [Telemetry, Logging, Token Usage & Customization](#page-4)

<a id='page-1'></a>

## Core Framework Architecture

### 相关页面

相关主题：[Browser Drivers & LLM Integrations](#page-2), [Telemetry, Logging, Token Usage & Customization](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lavague-ai/LaVague/blob/main/README.md)
- [lavague-server/lavague/server/channel.py](https://github.com/lavague-ai/LaVague/blob/main/lavague-server/lavague/server/channel.py)
- [extension_chrome/src/actionSchemas.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/actionSchemas.ts)
- [extension_chrome/src/tools.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/tools.ts)
- [extension_chrome/src/parseactions.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/parseactions.ts)
- [extension_chrome/src/app/component/Logs.tsx](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/app/component/Logs.tsx)
- [lavague-tests/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-tests/README.md)
- [lavague-qa/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-qa/README.md)
- [lavague-integrations/contexts/lavague-contexts-cache/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-integrations/contexts/lavague-contexts-cache/README.md)
</details>

# 核心框架架构

LaVague 是一个面向浏览器自动化任务构建的大型动作模型（Large Action Model）框架。其核心架构由两个协同工作的智能组件构成：**World Model（世界模型）** 与 **Action Engine（动作引擎）**，二者由 **WebAgent** 进行编排，向多种浏览器驱动（Selenium、Playwright、Chrome 扩展）发出指令，以实现自然语言目标到可执行浏览器操作的转换。资料来源：[README.md]()。

## 架构总览与数据流

整个框架遵循"目标 → 规划 → 编译 → 执行"的链式流程。当用户给定一个自然语言目标（例如 "Go on the quicktour of PEFT"）时，World Model 首先结合当前网页状态输出高层指令集；随后 Action Engine 将这些指令"编译"为具体的浏览器代码（如 Selenium 或 Playwright 调用）并予以执行。资料来源：[README.md]()。

```mermaid
flowchart LR
    A[用户目标] --> B[WorldModel]
    B --> C{指令集}
    C --> D[ActionEngine]
    D --> E[PythonEngine<br/>专用执行]
    D --> F[NavigationEngine<br/>XPath 导航]
    D --> G[Driver 层]
    G --> H[Selenium]
    G --> I[Playwright]
    G --> J[Chrome 扩展]
    H --> K[浏览器]
    I --> K
    J --> K
    K -.->|新状态| B
```

这一闭环结构允许智能体在每一步重新感知网页状态，并将多模态视觉语言模型（mm_llm）能力注入到 World Model 的判断中。社区中关于 #272 议题的讨论正是聚焦于如何替换默认的 OpenAI 多模态模型，从而支持 Phi-3 等开源模型实现完全本地化的智能体运行。资料来源：[README.md]()。

## WebAgent 编排层

WebAgent 是整个核心架构的协调者，它将 World Model、Action Engine 和底层 Driver 整合为单一入口。服务器侧通过 `AgentSession.handle_prompt_agent_action` 接收消息，并将 `run`、`run_step`、`get`、`prepare_run` 等类型分派给 WebAgent 对应方法；任务通过 `exe_start_stop` 在独立线程中执行，期间发送 `start`/`stop` 状态信号。资料来源：[lavague-server/lavague/server/channel.py]()。

为提升可观测性，社区 #241 议题建议在 `agent.run` 中新增 `log` 布尔参数，将推理过程、思考链、动作指令和检索到的 HTML 片段持久化到日志目录；这一需求同样在 Chrome 扩展的 `Logs.tsx` 中得到体现——它通过事件总线持续监听来自后端的 `cmd`、`network`、`userprompt`、`agent_log` 类型日志，并在前端折叠展示。资料来源：[extension_chrome/src/app/component/Logs.tsx]()。

## Action Engine 与动作模式

Action Engine 负责把高层指令转换为可执行结构化动作。在 Chrome 扩展实现中，Action Engine 通过 YAML/JSON 解析智能体的回复，并使用 Zod 模式进行强校验，确保每个动作包含合法的 `name`（如 `click`、`get`）和 `args`（如 `xpath`、`value`）。资料来源：[extension_chrome/src/parseactions.ts]()。

可供调用的动作清单由 `actionSchemas.ts` 动态生成文本描述，以便注入到提示中供多模态模型选用。例如，`click` 动作会接收 `xpath` 字符串参数；这种基于 XPath 的标准化输出正是社区 #352 议题的方向：将 `NavigationEngine` 由"任意代码执行"切换为"输出 XPath + 动作类型 + 参数"，从而与 `PythonEngine` 工具调用能力明确分离。资料来源：[extension_chrome/src/actionSchemas.ts]()、社区议题 #352。

社区 #440 议题进一步主张将动作的"生成"与"执行"分离到不同模块，以便统一审计执行路径并支持远程执行；当前核心框架已通过 `PythonEngine`（专门执行任意 Python 工具调用）与 `NavigationEngine`（专门处理 XPath 导航）的职责划分为这一重构奠定基础。资料来源：[README.md]()。

## Driver 层与可观测性

核心框架通过 Driver 抽象层支持多种浏览器控制方式。`SeleniumDriver`、`Playwright` 及 Chrome 扩展驱动都实现了统一接口，但其能力矩阵存在差异：例如，iframe 处理在 Selenium 与 Playwright 均受支持，但 Chrome 扩展尚不支持；多标签页支持在 Chrome 扩展与 Selenium 中可用，而 Playwright 正在开发中。资料来源：[README.md]()。

在调试与测试层面，框架提供 `lavague-test` 测试运行器，它扫描 `lavague-tests/sites/<site>/config.yml` 中的任务定义，针对真实网站执行智能体并输出 HTML、URL、状态、Tab 等字段的成功/失败报告；社区也广泛呼吁进一步强化 Playwright 的 headless 支持（议题 #1）。资料来源：[lavague-tests/README.md]()、社区议题 #1。

此外，`lavague-qa` 子项目基于此核心架构将 Gherkin 规格自动转换为 pytest 测试，配合 `lavague-contexts-cache` 的 LLM/多模态 LLM 响应缓存层，可在目标稳定时实现离线重放、零 token 消耗的回归测试。资料来源：[lavague-qa/README.md]()、[lavague-integrations/contexts/lavague-contexts-cache/README.md]()。

## See Also

- [Quick Tour（快速上手）](https://docs.lavague.ai/en/latest/docs/get-started/quick-tour/)
- [LaVague QA 文档](https://docs.lavague.ai/en/latest/docs/lavague-qa/quick-tour/)
- [Driver 支持矩阵（README.md）](https://github.com/lavague-ai/LaVague/blob/main/README.md)
- [Telemetry 与隐私设置](https://docs.lavague.ai/en/latest/docs/get-started/FAQs/#how-can-i-set-environment-variables)

---

<a id='page-2'></a>

## Browser Drivers & LLM Integrations

### 相关页面

相关主题：[Core Framework Architecture](#page-1), [Companion Tools: LaVague QA, Server, Tests, Gradio & Chrome Extension](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lavague-ai/LaVague/blob/main/README.md)
- [lavague-server/lavague/server/driver.py](https://github.com/lavague-ai/LaVague/blob/main/lavague-server/lavague/server/driver.py)
- [lavague-integrations/contexts/lavague-contexts-cache/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-integrations/contexts/lavague-contexts-cache/README.md)
- [extension_chrome/src/actionSchemas.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/actionSchemas.ts)
- [extension_chrome/src/tools.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/tools.ts)
- [extension_chrome/package.json](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/package.json)
- [lavague-tests/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-tests/README.md)
- [lavague-qa/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-qa/README.md)
</details>

# 浏览器驱动与 LLM 集成

## 概述

LaVague 是一个面向 Web 自动化的"大动作模型"（Large Action Model）框架，将高层目标（objective）转化为浏览器可执行的动作。其核心由两个组件协作：

- **World Model（世界模型）**：接收目标与当前页面状态，输出自然语言指令。
- **Action Engine（动作引擎）**：将这些指令"编译"为可执行代码（Selenium、Playwright 等）并执行。

而**浏览器驱动（Driver）**与 **LLM 上下文（Context）**则分别是 Action Engine 与 World Model 的可插拔底座。`README.md` 明确指出 LaVague 默认使用 OpenAI 的 `gpt-4-o`，但这"完全可自定义"。资料来源：[README.md]()

## 支持的浏览器驱动

LaVague 提供三种浏览器驱动实现，README 中的对比表清晰展示了各驱动的能力差异。资料来源：[README.md]()

| 功能 (Feature)        | Selenium | Playwright | Chrome Extension |
|----------------------|----------|------------|------------------|
| Headless agents      | ✅       | ⏳         | N/A              |
| Handle iframes       | ✅       | ✅         | ❌               |
| Open several tabs    | ✅       | ⏳         | ✅               |
| Highlight elements   | ✅       | ✅         | ✅               |

其中 ✅ = supported，⏳ = coming soon，❌ = not supported。

社区对 Playwright 支持有明确呼声：Issue #1 "Playwright support" 是评论数最高的议题之一，询问是否计划支持 Playwright。资料来源：[README.md](社区上下文)

服务器端 `lavague-server/lavague/server/driver.py` 中展示了驱动返回的结构化动作描述，每个动作由 `name`（如 `click`）、`xpath` 与 `value` 字段构成，用于定位页面元素并传递参数。资料来源：[lavague-server/lavague/server/driver.py]()

## Chrome 扩展驱动

Chrome 扩展作为另一种驱动形态，由 TypeScript/React 实现，依赖 Chakra UI、jQuery、Zod 等。资料来源：[extension_chrome/package.json]()

扩展端的 action schema 使用 Zod 定义，`getAllToolsDescriptions()` 会将所有工具转换为文本描述供 World Model 解析；动作统一形如 `{ name: string, args: object }`，通过 `xpath` 与 `value` 传递参数。资料来源：[extension_chrome/src/actionSchemas.ts]()

`extractWorldModelInstruction()` 函数通过多种正则模式从 World Model 输出中提取"Instruction:"块，兼容单行、多行连字符、多行数字编号以及三反引号包裹的代码块。资料来源：[extension_chrome/src/tools.ts]()

## LLM 上下文集成

LaVague 通过 `lavague-integrations/contexts/` 提供可插拔的 Context 包，每个 Context 负责提供 LLM、多模态 LLM（`mm_llm`）与 Embedding。

### 默认配置

`README.md` 示例使用 `WorldModel()` 与 `ActionEngine(selenium_driver)`，默认走 OpenAI `gpt-4o`，需在本地环境设置 `OPENAI_API_KEY`。资料来源：[README.md]()

### 缓存 Context

`lavague-contexts-cache` 为 LLM、`mm_llm` 与 Embedding 提供缓存层：保证自动化与手工测试结果一致、减少 API token 消耗、加速本地开发、缓存场景可离线重放。使用方式是将 `OpenAI(...)` 等真实模型包装为 `LLMCache`、`MultiModalLLMCache`、`EmbeddingCache`。资料来源：[lavague-integrations/contexts/lavague-contexts-cache/README.md]()

### 本地模型探索（社区）

Issue #272 "Exploration of Phi-3 Medium Vision and Text for fully local agent" 探讨了使用 [Phi-3](https://huggingface.co/microsoft/Phi-3-vision-128k-instruct) 替换 `mm_llm`、摆脱 OpenAI 依赖以实现完全本地化代理的可行性。资料来源：[README.md](社区上下文)

## 集成数据流

目标（Objective）进入 World Model，由 Context 提供的 LLM 驱动推理；World Model 输出指令交给 Action Engine，后者通过 Driver 在浏览器上执行。Driver 抓取新页面状态反馈给 World Model，形成闭环。社区 Issue #440 提出将"动作执行"从 Action Engine 中分离以提升可观测性，Issue #352 建议将"任意代码执行"改为输出 XPath + 动作类型 + 参数的声明式结构。资料来源：[README.md](社区上下文)

## 测试与质量保障

`lavague-tests`（`lavague-test` 命令）提供测试运行器，读取 `lavague-tests/sites/*/config.yml` 中的 `tasks` 列表，对每个任务执行 agent 并根据 `expect` 断言验证结果，输出 `[o]/[x]` 形式的成功/失败报告。资料来源：[lavague-tests/README.md]()

`lavague-qa` 命令将 Gherkin `.feature` 文件转换为 pytest 代码，通过 LaVague 框架在真实网站上执行。资料来源：[lavague-qa/README.md]()

## 常见失败模式

1. **未设置 `OPENAI_API_KEY`**：默认 Context 直接失败，README 明确需在本地环境设置该变量。资料来源：[README.md]()
2. **Playwright 特性缺失**：Headless、多 Tab 在 Playwright 驱动中仍标记为"开发中"。资料来源：[README.md]()
3. **Chrome 扩展无法处理 iframe**：对比表显示该能力未支持。资料来源：[README.md]()
4. **目标含敏感信息**：默认遥测会上报目标与用户数据，建议设置 `LAVAGUE_TELEMETRY=NONE` 完全关闭。资料来源：[README.md]()
5. **缺少 agent 流程日志**：Issue #241 建议为 `agent.run` 增加 `log` 参数并将每步的推理/动作/状态写入日志文件夹以便回溯。资料来源：[README.md](社区上下文)

## 另请参阅

- [快速上手（Quick-tour）](https://docs.lavague.ai/en/latest/docs/get-started/quick-tour/)
- [自定义配置](https://docs.lavague.ai/en/latest/docs/get-started/customization/)
- [Test Runner 使用指南](https://docs.lavague.ai/en/latest/docs/get-started/testing/)
- [Chrome 扩展文档](https://docs.lavague.ai/en/latest/docs/get-started/docs-chrome/)

---

<a id='page-3'></a>

## Companion Tools: LaVague QA, Server, Tests, Gradio & Chrome Extension

### 相关页面

相关主题：[Browser Drivers & LLM Integrations](#page-2), [Telemetry, Logging, Token Usage & Customization](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lavague-ai/LaVague/blob/main/README.md)
- [lavague-qa/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-qa/README.md)
- [lavague-server/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-server/README.md)
- [lavague-server/lavague/server/channel.py](https://github.com/lavague-ai/LaVague/blob/main/lavague-server/lavague/server/channel.py)
- [lavague-server/lavague/server/driver.py](https://github.com/lavague-ai/LaVague/blob/main/lavague-server/lavague/server/driver.py)
- [lavague-tests/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-tests/README.md)
- [extension_chrome/package.json](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/package.json)
- [extension_chrome/src/actionSchemas.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/actionSchemas.ts)
- [extension_chrome/src/tools.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/tools.ts)
- [lavague-integrations/contexts/lavague-contexts-cache/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-integrations/contexts/lavague-contexts-cache/README.md)
</details>

# Companion Tools: LaVague QA、Server、Tests、Gradio 与 Chrome Extension

## 概述

LaVague 主框架围绕 `WorldModel` 与 `ActionEngine` 两大核心抽象构建 Web Agent（资料来源：[README.md:1-4]()）。在主框架之外，仓库还提供一组"配套工具（Companion Tools）"，分别面向 QA 工程化、远程驱动服务、自动化回归测试、交互式演示与浏览器端控制。理解这些配套工具的职责与边界，是将 LaVague 真正落地的关键。

## LaVague QA：Gherkin 转 pytest 的工程化生成器

LaVague QA 是面向 QA 工程师的专用工具，它将 Gherkin 规格描述的测试场景转化为可执行的 pytest 文件。工具通过 `lavague-qa` CLI 暴露入口。

### 关键 CLI 参数

| 参数 | 含义 |
|---|---|
| `-u, --url` | 被测站点的 URL |
| `-f, --feature` | 包含 Gherkin 语法的 `.feature` 文件路径 |
| `-l, --full-llm` | 启用完整 LLM 驱动的 pytest 生成 |
| `-c, --context` | 自定义上下文与 token counter 初始化脚本路径（默认使用 OpenAI GPT-4o） |
| `-h, --headless` | 浏览器以无头模式运行 |
| `-db, --log-to-db` | 将日志写入 SQLite 数据库 |

典型用法（资料来源：[lavague-qa/README.md:1-19]()）：

```bash
lavague-qa --url https://amazon.fr/ --feature features/demo_amazon.feature
```

## LaVague Server：基于 WebSocket 的远程 Agent 服务

`lavague-server` 把 `WebAgent` 暴露为可通过 WebSocket 访问的远程服务，从而支持浏览器端、CLI 端或其它进程的远程驱动。

### 核心组件

- **`AgentSession`（抽象基类）**：维护 `uid` 与执行线程 `_task`，提供 `send_message` / `send_message_for_result` 接口，并通过 `exe_start_stop` 包装 `agent.run` 与 `agent.run_step`，在执行前后向客户端广播 `start` / `stop` 事件（资料来源：[lavague-server/lavague/server/channel.py:1-65]()）。
- **`DriverServer`**：继承自 `BaseDriver`，将浏览器操作（`get_html`、`get_url`、`get` 等）映射为会话的同步命令收发协议，使服务端可驱动远端浏览器（资料来源：[lavague-server/lavague/server/driver.py:1-80]()）。
- **`AgentServer`**：通过注入的 `create_agent(session)` 工厂创建 `WebAgent`，对外提供 `serve()` 入口。

### 消息处理流程

`handle_prompt_agent_action` 依据消息类型分派：包括 `run`、`run_step`、`get`、`prepare_run` 等分支，统

计如下：

```mermaid
flowchart LR
    A[WebSocket 客户端] -->|JSON 消息| B(AgentSession)
    B --> C{消息类型}
    C -->|run| D[agent.run]
    C -->|run_step| E[agent.run_step]
    C -->|get| F[agent.get]
    D & E --> G[exe_start_stop 包装]
    G --> H[start/stop 事件回发]
    H --> A
```

（资料来源：[lavague-server/lavague/server/channel.py:60-90]()）

## LaVague Tests：站点级回归测试运行器

`lavague-tests` 提供 `lavague-test` CLI，在真实网站上执行回归测试并生成报告。CLI 支持以下选项（资料来源：[lavague-tests/README.md:1-30]()）：

- `--directory / -d`：测试目录，默认当前工作目录下的 `lavague-tests/sites`。
- `--site / -s`：指定单个或多个站点，可重复使用。
- `--display`：浏览器非无头运行。

### 任务配置文件结构

每个被测站点是一个包含 `config.yml` 的文件夹，配置示例：

```yaml
type: web
max_steps: 5
n_attempts: 1
tasks:
  - name: HuggingFace navigation
    url: https://huggingface.co/docs
    prompt: Go on the quicktour of PEFT
    expect:
      - URL is https://huggingface.co/docs/peft/quicktour
      - Status is success
```

执行结束后输出 `[o]` / `[x]` 形式的成功失败摘要，并以退出码 `0` / `-1` 表示整体结果（资料来源：[lavague-tests/README.md:32-68]()）。

## Gradio 交互式演示与 Chrome 扩展

### Gradio 界面

`agent.demo("...")` 一行即可启动 Gradio 演示界面，托管在本地 Web UI 中，便于人工观察 WorldModel 与 ActionEngine 的逐步决策（资料来源：[README.md:39-55]()）。

### Chrome 扩展

`extension_chrome/` 是一个独立的 React/TypeScript 应用，用于在用户已登录的浏览器中执行 LaVague 指令。它通过 Webpack 打包，关键依赖包括 `@chakra-ui/react`、`react`、`axios`、`zod` 等（资料来源：[extension_chrome/package.json:1-35]()）。

扩展定义了 `allTools`，每个工具由 Zod schema 描述，序列化后作为 WorldModel 提示词中的可用动作集（资料来源：[extension_chrome/src/actionSchemas.ts:1-25]()）。`extractWorldModelInstruction` 负责从 LLM 输出中解析 `Instruction:` 段落，覆盖多行、代码块与编号多种格式（资料来源：[extension_chrome/src/tools.ts:1-30]()）。

## 常见支持矩阵

`README.md` 给出了 Selenium、Playwright 与 Chrome Extension 三种驱动在 `Headless`、`Handle iframes`、`Open several tabs`、`Highlight elements` 等功能上的支持对照（资料来源：[README.md:87-100]()），与上述配套工具协同工作的能力直接影响测试与演示的可行范围。

## See Also

- [WorldModel 与 ActionEngine 核心抽象](README.md)
- [配置与上下文定制](https://docs.lavague.ai/en/latest/docs/get-started/customization/)
- [Token 用量与成本估算](https://docs.lavague.ai/en/latest/docs/get-started/token-usage/)
- [社区反馈：Playwright 支持（Issue #1）](https://github.com/lavague-ai/LaVague/issues/1)

---

<a id='page-4'></a>

## Telemetry, Logging, Token Usage & Customization

### 相关页面

相关主题：[Core Framework Architecture](#page-1), [Browser Drivers & LLM Integrations](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lavague-ai/LaVague/blob/main/README.md)
- [lavague-tests/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-tests/README.md)
- [lavague-qa/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-qa/README.md)
- [lavague-integrations/contexts/lavague-contexts-cache/README.md](https://github.com/lavague-ai/LaVague/blob/main/lavague-integrations/contexts/lavague-contexts-cache/README.md)
- [extension_chrome/src/tools.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/tools.ts)
- [extension_chrome/src/actionSchemas.ts](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/actionSchemas.ts)
- [lavague-server/lavague/server/driver.py](https://github.com/lavague-ai/LaVague/blob/main/lavague-server/lavague/server/driver.py)
- [lavague-server/lavague/server/channel.py](https://github.com/lavague-ai/LaVague/blob/main/lavague-server/lavague/server/channel.py)
- [extension_chrome/src/app/component/Logs.tsx](https://github.com/lavague-ai/LaVague/blob/main/extension_chrome/src/app/component/Logs.tsx)
</details>

# Telemetry、Logging、Token 使用与定制化

## 概述

LaVague 是一个面向 Web 自动化的大型动作模型框架，内置了完整的可观测性与成本控制机制。本页介绍框架中的遥测（Telemetry）、日志记录（Logging）、Token 使用统计以及定制化（Customization）相关能力。这些功能协同工作，使开发者能够观察代理运行过程、估算 API 成本，并根据场景调整配置。社区中的多个讨论（如 issue #241 关于"Log agent flow / experiments"）反映出用户对代理流程可追溯性的强烈需求。资料来源：[README.md:1-50]()

下图为 LaVague 代理运行时的可观测性数据流：

```mermaid
graph LR
    A[WebAgent] --> B[ActionEngine]
    A --> C[World Model]
    B --> D[Driver / Selenium / Playwright]
    C --> E[Token Counter]
    A --> F[Logger]
    F --> G[Chrome Extension Logs UI]
    A --> H[Telemetry 采集]
    H --> I{LAVAGUE_TELEMETRY}
    I -->|"NONE"| J[关闭]
    I -->|其他值| K[匿名上报]
```

## 遥测（Telemetry）

LaVague 默认开启遥测功能，用于收集代理运行过程中的关键数据。根据 README 描述，遥测会采集以下信息：

| 类别 | 字段 |
|------|------|
| 模型 | 使用的 LLM（默认 `gpt-4o`） |
| 用户 | 随机生成的匿名用户 ID |
| 入口 | CLI（`lavague-qa`）、Gradio 演示或库直调 |
| 任务 | 目标（objective） |
| 推理 | 代理思维链（chain of thoughts） |
| 交互 | 页面交互区域（边界框）、视口大小、当前步骤 |
| 指令 | 生成的指令及使用的引擎 |
| 成本 | Token 成本与使用量 |
| 状态 | 动作执行 URL、是否成功、错误信息、源节点 |

若希望关闭所有遥测，可将环境变量 `LAVAGUE_TELEMETRY` 设置为 `"NONE"`。README 明确警告：切勿在目标或额外用户数据中包含个人信息；若必须包含，强烈建议关闭遥测。资料来源：[README.md:113-145]()

## 日志记录（Logging）

### Chrome 扩展日志组件

Chrome 扩展中实现了完整的日志查看界面，位于 `extension_chrome/src/app/component/Logs.tsx`。该组件定义了四种日志类型：`network`（网络）、`cmd`（命令）、`userprompt`（用户提示）、`agent_log`（代理日志）。`COMMAND_LABELS` 映射表将内部命令翻译为可读形式，涵盖 `get_url`、`get_html`、`get`（导航）、`back`、`get_screenshot`、`execute_script`、`exec_code`、`is_visible`、`get_possible_interactions` 等。资料来源：[extension_chrome/src/app/component/Logs.tsx:15-30]()

### World Model 指令提取

`extension_chrome/src/tools.ts` 中的 `extractWorldModelInstruction` 函数负责从 LLM 输出中提取结构化指令，支持多种格式：多行连字符列表、`### Instruction:` 前缀、多行编号列表、三反引号代码块以及单行指令。提取时会保留最长的匹配项，确保获取完整指令。资料来源：[extension_chrome/src/tools.ts:1-30]()

### Action Schema 描述生成

`extension_chrome/src/actionSchemas.ts` 中的 `schemaToDescription` 函数将 Zod schema 转换为可读的工具描述（名称、描述、参数及类型），最终由 `getAllToolsDescriptions` 拼接为完整文本，供 World Model 推理时参考。资料来源：[extension_chrome/src/actionSchemas.ts:1-30]()

社区 issue #241 建议在 `agent.run` 中新增可选 `log`（boolean）参数并创建日志文件夹，这与上述日志机制的方向一致；issue #440 与 #352 则分别讨论将动作执行与生成解耦、改用结构化 XPath 输出，以便更好地进行可观测性追踪。资料来源：[README.md:1-50]()

### 代理会话与指令下发

`lavague-server/lavague/server/channel.py` 中的 `AgentSession` 抽象类负责接收来自 Chrome 扩展的指令并下发到 `WebAgent`，支持 `run`、`run_step`、`get`、`prepare_run` 等消息类型。`exe_start_stop` 方法管理代理执行生命周期，通过 `send_message` 向客户端发送 `start` 与 `stop` 事件。`lavague-server/lavague/server/driver.py` 中的 `DriverServer` 类则通过 `send_command_and_get_response_sync` 与扩展侧浏览器会话双向通信。资料来源：[lavague-server/lavague/server/channel.py:1-50]()、[lavague-server/lavague/server/driver.py:1-50]()

## Token 使用与定制化

### 缓存层降低 Token 消耗

`lavague-integrations/contexts/lavague-contexts-cache` 提供 LLM、多模态 LLM 与 Embedding 的缓存层，通过 `LLMCache`、`MultiModalLLMCache` 与 `EmbeddingCache` 三个包装类实现：确定性结果（避免相同输入产生不同输出）、降低 API Token 消耗、加速本地开发、支持离线重放。典型用法：

```python
from lavague.contexts.cache import LLMCache
from llama_index.llms.openai import OpenAI

llm = LLMCache(yml_prompts_file="llm.yml", fallback=OpenAI(model="gpt-4o"))
```

资料来源：[lavague-integrations/contexts/lavague-contexts-cache/README.md:1-50]()

### 测试与 QA 工具链

`lavague-tests` 提供 `lavague-test` 命令行工具，支持 `--directory`、`--site`、`--display` 等参数，可批量运行 `config.yml` 中定义的测试任务，并输出成功/失败报告与退出码。`lavague-qa` 则将 Gherkin 规格转换为 pytest 文件，支持 `--url`、`--feature`、`--full-llm`、`--context`、`--headless`、`--log-to-db` 等参数，专为 QA 工程师设计。这两类工具都基于同一 LaVague 核心框架，因此可共享自定义 Context 与 Token 统计配置。资料来源：[lavague-tests/README.md:1-50]()、[lavague-qa/README.md:1-30]()

## 总结

LaVague 在遥测、日志、Token 统计与定制化方面提供了完整支持：开发者可通过 `LAVAGUE_TELEMETRY` 环境变量控制遥测，通过 Chrome 扩展实时观察代理流程，通过缓存层降低 API 成本，并通过 Context 机制替换底层 LLM 与 Embedding。对于希望进一步记录代理运行流程的用户，可参考 issue #241 提出的 `log` 参数方案；对于希望摆脱 OpenAI 依赖的用户，可参考 issue #272 探索 Phi-3 等本地多模态模型。资料来源：[README.md:50-90]()

## See Also

- [README.md](https://github.com/lavague-ai/LaVague/blob/main/README.md)
- [lavague-integrations/contexts/lavague-contexts-cache](https://github.com/lavague-ai/LaVague/tree/main/lavague-integrations/contexts/lavague-contexts-cache)
- [lavague-tests](https://github.com/lavague-ai/LaVague/tree/main/lavague-tests)
- [lavague-qa](https://github.com/lavague-ai/LaVague/tree/main/lavague-qa)
- [extension_chrome](https://github.com/lavague-ai/LaVague/tree/main/extension_chrome)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：lavague-ai/LaVague

摘要：发现 14 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：Cannot import World Model。

## 1. 配置坑 · 来源证据：Cannot import World Model

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Cannot import World Model
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/642 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 能力坑 · 来源证据：Integrate pytest file export from QA example into codebase as export option in a exports.py module

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Integrate pytest file export from QA example into codebase as export option in a exports.py module
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/333 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 运行坑 · 来源证据：Parameterization is not working in Lavague-QA: Variable parameter is passed in to input field as it is, instead of valu…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Parameterization is not working in Lavague-QA: Variable parameter is passed in to input field as it is, instead of values mentioned under "Examples" section of…
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/609 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安全/权限坑 · 来源证据：Handle action code that exceeds the max_tokens by truncating code after last full action and adding three backticks.

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Handle action code that exceeds the max_tokens by truncating code after last full action and adding three backticks.
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/563 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 来源证据：Code execution via eval of LLM output derived from untrusted web-page content (indirect prompt injection to RCE)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Code execution via eval of LLM output derived from untrusted web-page content (indirect prompt injection to RCE)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/650 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：Not able to run any example with Ollama

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Not able to run any example with Ollama
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/640 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/lavague-ai/LaVague | README/documentation is current enough for a first validation pass.

## 8. 运行坑 · 来源证据：Cannot pass the string that includes character backstick into password field

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Cannot pass the string that includes character backstick into password field
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/641 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/lavague-ai/LaVague | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/lavague-ai/LaVague | no_demo; severity=medium

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/lavague-ai/LaVague | no_demo; severity=medium

## 12. 安全/权限坑 · 来源证据：Plasmate for read-only web operations - lighter than Chrome

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Plasmate for read-only web operations - lighter than Chrome
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lavague-ai/LaVague/issues/648 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/lavague-ai/LaVague | issue_or_pr_quality=unknown

## 14. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/lavague-ai/LaVague | release_recency=unknown

<!-- canonical_name: lavague-ai/LaVague; human_manual_source: deepwiki_human_wiki -->