内容
# 天真用户
以无视源码、首次使用的身份驱动实时网页应用。一个 AI 代理悬浮、点击并在真实浏览器中输入，观察实际发生的情况，并报告真实用户遇到之前的问题（错误、破碎的预期、用户体验惊喜、辅助功能问题）。
[](LICENSE)
[](#install)
[](https://github.com/microsoft/playwright-mcp)
[](CONTRIBUTING.md)
它弥补了其他三种方法无法覆盖的空白：
- **真实用户** 发现这些问题，但只有在您发布后。
- **您，手动测试，** 知道应用程序如何构建，因此您无法看到新鲜的体验。
- **脚本化端到端测试** 确认您已经知道的流程。它们无法发现您不知道的流程。
代理仅从两个来源形成预期：屏幕上的内容和通用网络约定。它从不读取您的源代码。它在 `qa/naive-user/<app>/` 下构建一个知识库，该知识库独立于代码，就像真实用户的心理模型一样，并且在每次运行中都会累积。
<!-- 在启动前在此添加短的演示 GIF 或截图，然后在设置 > 常规 > 社交预览中设置社交预览图像。两者都能明显提高第一印象。 -->
## 目录
- [您获得的内容](#您获得的内容)
- [要求](#要求)
- [安装](#安装)
- [配置](#配置)
- [用法](#用法)
- [示例输出](#示例输出)
- [它如何发布](#它如何发布)
- [贡献](#贡献)
- [许可证](#许可证)
## 您获得的内容
```
qa/naive-user/<app>/
├── mental-model.md # 天真用户认为应用程序的作用；每次运行都会完善
├── findings/<date>.md # 有日期的空白报告（预期 / 实际 / 观察 / 空白 / 严重性 / 复现）
└── screenshots/ # 前后证据（gitignored）
```
发现结果按严重性排名：`bug`、`broken-expectation`、`ux-gap`、`surprise`、`a11y`。
## 要求
- **Node.js 18+** 是唯一硬性要求。Playwright MCP 服务器在首次使用时提供浏览器。如果您遇到缺少浏览器错误，请运行 `npx playwright install chromium`。
- **正在运行的应用程序**，无论是已经在 URL 上提供服务还是可以通过配置文件中的 `startCommand` 启动。
- **支持的测试框架之一**。每个框架都需要代理工具调用和 Playwright MCP 浏览器工具，因此不针对仅限指令的 IDE 规则主机。
## 安装
### 1. 将插件添加到您的测试框架并连接 Playwright MCP
相同的 MCP 服务器主体，`npx @playwright/mcp@latest`，在任何地方都适用。只有 OpenCode 和 Copilot 修改了形状。
**Claude Code.** 市场安装。插件捆绑了 Playwright MCP，因此它是一个步骤：
```text
/plugin marketplace add TechGardenCode/naive-user # 或本地路径：./naive-user
/plugin install naive-user@naive-user
```
> 不使用插件？复制此存储库的 `.mcp.json` 到您的应用程序存储库根目录，并将 `skills/` 和 `commands/` 放入您的项目的 `.claude/` 中。
**Codex.** 放入插件，然后将 MCP 服务器添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
```
**Gemini CLI.** 作为扩展安装（`gemini-extension.json` 捆绑了 MCP 服务器和技能作为上下文），或将服务器添加到 `~/.gemini/settings.json`：
```json
{
"mcpServers": {
"playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
}
}
```
**GitHub Copilot CLI.** 插件位于 `.github/plugin/plugin.json` 并捆绑了 MCP。要手动连接，请添加到 `~/.copilot/mcp-config.json`：
```json
{
"mcpServers": {
"playwright": { "type": "local", "command": "npx", "args": ["@playwright/mcp@latest"], "tools": ["*"] }
}
}
```
**OpenCode.** `opencode.json` 捆绑了 MCP。请注意 `command` 是一个数组，而 `-y` 避免了交互式 npx 提示：
```json
{
"mcp": {
"playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp@latest"], "enabled": true }
}
}
```
## 配置
### 1. 指向您的应用程序
将 `templates/naive-user.config.json` 复制到您的应用程序存储库的根目录并填写：
```json
{
"app": "myapp",
"baseUrl": "http://localhost:3000",
"startCommand": null,
"auth": { "steps": ["Go to /", "Type the dev username", "Submit"], "critiqueLoginPage": false },
"coverageNotes": "Optional hints, not a script."
}
```
`startCommand` 替换任何“如何启动应用程序”的步骤。设置它，代理运行它。将其设置为 `null`，代理假设应用程序已经在 `baseUrl` 启动。参见 [`examples/notes-app/`](examples/notes-app/) 获取完整的配置。
### 2. 保持知识库可审查
在您的应用程序存储库的 `.gitignore` 中，提交 markdown 但忽略截图证据：
```gitignore
qa/naive-user/*/screenshots/
```
## 用法
```text
/naive-test [app]
```
如果没有参数，它使用 `naive-user.config.json` 中的 `app`。代理加载先前的心理模型，确保应用程序正在运行，通过配置的身份验证步骤登录，探索实时的 UI 源盲区，并编写更新的 `mental-model.md` 和一个有日期的发现报告。根据需要运行它，或将其作为子代理派遣以与并行工作一起运行。
与上次相比的行为变化被标记为 **回归**。
## 示例输出
发现文件以一行摘要和严重性排序的表格开始，然后是每个空白的条目：
```markdown
| # | Severity | Surface | Gap |
|---|----------|---------|-----|
| 1 | bug | Capture | Pressing Enter in the title field reloads the page |
| 2 | a11y | Sidebar | Active nav item has no visible focus ring |
## 1. Pressing Enter reloads instead of saving
- Expected: Enter submits the form (primary-button convention).
- Did: Typed a title, pressed Enter.
- Observed: Full page reload, draft lost.
- Severity: bug
- Repro: 1. Open /. 2. Type in title. 3. Press Enter.
- Screenshot: screenshots/capture-enter-before.png
```
## 它如何发布
核心内容生活一次：
- `skills/naive-user/SKILL.md` 包含源盲测试方法论（配置驱动）。
- `commands/naive-test.md` （以及 OpenCode 的 `.toml`）是 `/naive-test` 入口点。
每个测试框架都有一个薄薄的清单，指向这些文件并声明 Playwright MCP 以该测试框架的原生格式。没有重复内容：
| 测试框架 | 清单 | MCP 在哪里声明 |
|---|---|---|
| Claude Code | `.claude-plugin/plugin.json` （以及 `marketplace.json`） | 插件 `mcpServers` / `.mcp.json` |
| Codex | `.codex-plugin/plugin.json` | `~/.codex/config.toml` |
| Gemini CLI | `gemini-extension.json` | 扩展 `mcpServers` / `settings.json` |
| Copilot CLI | `.github/plugin/plugin.json` | 插件 `mcpServers` / `~/.copilot/mcp-config.json` |
| OpenCode | `opencode.json` | `opencode.json` `mcp` |
## 贡献
问题和拉取请求是欢迎的。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取工作流程，以及 [SECURITY.md](SECURITY.md) 私下报告漏洞。
## 许可证
MIT. 参见 [LICENSE](LICENSE)。
