> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/agent-observability.md).

# 代理可观测性

如何查看应用和代理做了什么：E2E 产物、推理捕获代理，以及 Langfuse traces。

本页介绍三种查看 OpenHuman 做了什么的方式。E2E 产物让编码代理（Codex、Claude Code、Cursor）可以通过 Playwright 检查浏览器隐私流程，并通过 WDIO 检查仅限宿主机的桌面断言（见 [E2E 测试](/openhuman/zh/kai-fa/e2e-testing.md)）。捕获代理展示 core 发送给推理的内容。Langfuse 跟踪覆盖真实的代理运行。

浏览器审查用例涵盖 shell 就绪状态和隐私面板。它会在每个检查点附加截图、页面源码 HTML 和模拟后端请求日志。原生 WDIO 负责实时桌面窗口和仅限 Tauri 的行为；它不会重复浏览器隐私流程。

## 快速开始

```bash
bash app/scripts/e2e-web-shards.sh --lane=1 --lanes=4
```

Playwright 附件会随测试结果写入到 `app/test-results/`。要直接运行审查用例：

```bash
bash app/scripts/e2e-web-session.sh test/playwright/specs/agent-review.spec.ts
```

产物包括：

```
app/test-results/<run>/<test>/
  01-shell-ready.png
  01-shell-ready.html
  01-shell-ready.mock-requests.json
  02-privacy-panel.png
  02-privacy-panel.html
  02-privacy-panel.mock-requests.json
```

脚本会在末尾打印解析出的产物目录。

## 组成部分

| 部分            | 路径                                                                         | 作用                   |
| ------------- | -------------------------------------------------------------------------- | -------------------- |
| 辅助工具          | `app/test/playwright/specs/agent-review.spec.ts`                           | 附加截图、页面源码和模拟请求日志     |
| Playwright 负责 | `app/test/playwright/specs/agent-review.spec.ts`                           | shell 就绪状态和隐私面板标签/切换 |
| 稳定选择器         | `chat-message-input`, `settings-privacy-panel`, `privacy-analytics-toggle` | 对代理可靠的就绪锚点           |

## 环境覆盖项

| 变量                    | 效果                          |
| --------------------- | --------------------------- |
| `OPENHUMAN_WORKSPACE` | Playwright 会话使用的隔离 core 工作区 |

## 在新规范中使用该辅助工具

```ts
await testInfo.attach("after-connect.png", { body: await page.screenshot(), contentType: "image/png" });
```

`captureCheckpoint` 会对捕获进行编号，使运行目录按时间顺序读取。 `captureFailureArtifacts` 已接入 `wdio.conf.ts` 并会在任何失败的测试上自动触发。规范不应直接调用它。

## 在线推理：捕获代理

日志只会告诉你某一轮很慢。它们不会告诉你 harness 发送了什么，或者是哪个端点响应了。 `scripts/debug/capture-first-inference.mjs` (`pnpm debug capture`) 是 core 与其推理后端之间的回环代理，会记录双方内容：

```bash
CAPTURE_ALL=1 pnpm debug capture                # listens on 127.0.0.1:18765
# then, in another shell, point a core at it:
BACKEND_URL=http://127.0.0.1:18765 ./target/debug/openhuman-core run --port 7799
# or set api_url = "http://127.0.0.1:18765" in the user's config.toml
```

每个推理请求体都会被写入并编号，保存在 `target/debug-logs/inference-sequence/` （确切的系统提示词、工具 schema 以及 `prompt_cache_key` 由 harness 组装的内容），且每个响应都会在以下位置生成一条摘要行和一条 JSONL 记录： `target/debug-logs/inference-capture.jsonl`:

```
[capture] #000 200 model=z-ai/glm-5.3-flash msgs=2 tools=19 served_by=StreamLake ttfb=7.38s total=8.43s prompt=12344 cached=12288 cache_key=tap-25675927a3f2160d
```

`CAPTURE_UPSTREAM=https://openrouter.ai` 捕获的是直接的 BYOK OpenRouter 路由，而不是托管后端。非 2xx 响应体会与请求转储一起保存，这样来自 ingress 的 HTML 503 就不会被笼统的“模型错误”掩盖。

在同一线程的多轮交互中，检查三件事。 `cache_key` 必须保持一致，因为它是 harness 的稳定前缀指纹，也是 OpenRouter 的粘性路由键。 `served_by` 不应改变。 `cached` 应接近 `prompt` 从第二次调用开始。它们中的任何一个发生漂移都曾是真实的 bug。

该代理仅绑定回环地址。除非你覆盖此限制，否则它会拒绝明文的非回环上游，因为它会原样转发 bearer token。 `--help` 列出所有 `CAPTURE_*` 选项。

## 生产环境代理跟踪

以上内容都关于本地产物。对于真实的代理运行，core 也可以将 trace span 导出到 Langfuse：当 `observability.share_usage_data` 开启时（默认），已完成运行的 spans 会通过 OTLP/HTTP JSON 发送到 OpenHuman 后端的 Langfuse 代理， `/telemetry/langfuse/otel/v1/traces`并使用与其他所有后端调用相同的会话 bearer。后端会在每个 span 上标记已登录用户，在服务器端注入项目密钥，并转发到 Langfuse v4 的 `/api/public/otel/v1/traces` 使用 `x-langfuse-ingestion-version: 4`。客户端从不直接持有 Langfuse 凭据。Flow 运行会通过以下方式导出其图观察： `crates/openhuman-core/src/agent/progress_tracing/flow_export.rs`; `crates/openhuman-core/src/flows/ops/execution.rs` 适配引擎日志。

Langfuse v4 没有自己的 trace 记录，而是直接过滤 observations，因此导出器会将 trace 名称、会话、标签、发布版本、环境和 trace 元数据复制到每个 span 上，并把运行的整体输入和输出放到根 observation 上。每个已完成的 span 只导出一次；v4 会重复它收到两次的 span id。Langfuse Cloud 会移除旧的 `/api/public/ingestion` trace 路径，时间是 2026-11-16，而 core 中没有任何东西会向那里发送 traces。提示词和回复文本只会在以下情况下随之传输： `observability.agent_tracing.capture_content` 也开启；将其关闭会保留元数据（名称、时序、token 和成本数字），但会丢弃内容。参见 `crates/openhuman-core/src/core/observability/progress_tracing/` 和 `crates/openhuman-core/src/config/schema/observability.rs`.

## 超出 E2E 层范围

* 覆盖每个组件状态的视觉基线和图像差异。
* 每次点击都截图（太吵）。
* 实时集成（Gmail、Notion、Telegram）；仅限模拟服务器。
* 新的测试框架或报告器。

只有在这个循环经受住验证后，才添加更多流程。