# 智能体可观测性

本文档描述了工件捕获层，它使桌面应用能够通过现有的 WDIO/Appium/tauri-driver 测试框架被编码代理（Codex、Claude Code、Cursor）检查。

它的范围是刻意收窄的：一个标准化的引导 + 隐私流程，带有落盘截图、页面源码转储和模拟后端请求日志。更广泛的计划请参见 `AGENT_OBSERVABILITY_PLAN.md` ，位于仓库根目录。

## 简而言之

```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` 并会在任何失败的测试中自动触发，因此规范不应直接调用它。

## 刻意不包含的范围

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

只有在这个循环验证成功之后，才扩展到更多流程。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/agent-observability.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.