> 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-zhong/agent-observability.md).

# 代理可观测性

让端到端测试可调试的产物捕获层。日志、跟踪、截图。

本文档描述了 artifact-capture 层，它使桌面应用可以通过现有的 WDIO/Appium Chromium harness 被编写代码的代理（Codex、Claude Code、Cursor）检查。

它的范围刻意很窄：一个规范化的引导 + 隐私流程，配有落盘截图、页面源代码转储和模拟后端请求日志。

## 简而言之

```bash
bash app/scripts/e2e-agent-review.sh
```

产物会放在：

```
app/test/e2e/artifacts/<ISO-timestamp>-agent-review/
  01-welcome.png
  01-welcome.source.xml
  02-post-welcome.png
  02-post-welcome.source.xml
  03-post-onboarding.png
  03-post-onboarding.source.xml
  04-privacy-panel.png
  04-privacy-panel.source.xml
  mock-requests-after-welcome.json
  mock-requests-after-onboarding.json
  mock-requests-after-privacy.json
  failure-<test>.png              # 仅在失败时
  failure-<test>.source.xml       # 仅在失败时
  meta.json                       # 运行元数据 + 检查点索引
```

脚本会在最后打印解析后的产物目录。

## 组成部分

| 组成部分    | 路径                                                                                              | 职责                                                                         |
| ------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 辅助工具    | `app/test/e2e/helpers/artifacts.ts`                                                             | 运行目录， `captureCheckpoint`, `captureFailureArtifacts`, `saveMockRequestLog` |
| WDIO 钩子 | `app/test/wdio.conf.ts` (`afterTest`)                                                           | 任何失败测试都会始终转储截图 + 源代码                                                       |
| 规范测试    | `app/test/e2e/specs/agent-review.spec.ts`                                                       | 欢迎页 → 引导 → 隐私面板，并带有命名检查点                                                   |
| 包装脚本    | `app/scripts/e2e-agent-review.sh`                                                               | 构建 + 运行 + 打印产物目录                                                           |
| 稳定选择器   | `data-testid` 位于 `OnboardingNextButton`, `Onboarding` 覆盖层 + 跳过按钮， `WelcomeStep`, `PrivacyPanel` | 适合代理可靠导航的锚点                                                                |

## 环境覆盖变量

| 变量                   | 效果                                                |
| -------------------- | ------------------------------------------------- |
| `E2E_ARTIFACT_DIR`   | 强制指定一个运行目录（跳过自动时间戳命名）                             |
| `E2E_ARTIFACT_ROOT`  | 自动生成运行目录的父目录（默认： `app/test/e2e/artifacts`)        |
| `E2E_ARTIFACT_LABEL` | 自动生成运行目录名称中使用的标签（默认： `run`；包装脚本设置 `agent-review`) |

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

```ts
import { captureCheckpoint, saveMockRequestLog } from "../helpers/artifacts";
import { getRequestLog } from "../mock-server";

await captureCheckpoint("after-connect-click");
saveMockRequestLog("after-connect-click", getRequestLog());
```

`captureCheckpoint` 按数字顺序记录捕获结果，因此运行目录按时间顺序排列。 `captureFailureArtifacts` 被接入到 `wdio.conf.ts` 并会在任何失败测试时自动触发，规范测试不应直接调用它。

## 传输层推断：捕获代理

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

```bash
CAPTURE_ALL=1 pnpm debug capture                # 监听 127.0.0.1:18765
# 然后，在另一个 shell 中，将 core 指向它：
BACKEND_URL=http://127.0.0.1:18765 ./target/debug/openhuman-core run --port 7799
# 或者在用户的 config.toml 中设置 api_url = "http://127.0.0.1:18765"
```

每个推理请求体都会被写入并编号，保存在 `target/debug-logs/inference-sequence/` （包括确切的系统提示、工具 schema 和 `prompt_cache_key` harness 组装出的内容），并且每个响应都会在 `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 响应体会保存在请求转储旁边，因此来自入口控制器的 HTML 503 不会被通用的“模型错误”掩盖。

在一次线程的多轮中要关注什么： `cache_key` 必须保持一致（它是 harness 的稳定前缀指纹和 OpenRouter 的粘性路由键）， `served_by` 不应变化，并且 `cached` 应接近 `prompt` 从第二次调用开始。上述任一项发生漂移都曾是真实 bug（openhuman#6434）。代理仅绑定回环地址，并且除非显式覆盖，否则会拒绝非回环的明文上游，因为它会原样转发 bearer； `--help` 会列出每个 `CAPTURE_*` 开关。

## 有意不在范围内的内容

* 跨每种组件状态的视觉基线 / 图像差异。
* 每次点击都进行截图捕获（太吵）。
* 实时集成（Gmail、Notion、Telegram）；仅使用模拟服务器。
* 新的测试框架 / 报告器。

只有在这个闭环验证通过之后，才扩展到更多流程。