# page-explorer

**Repository Path**: zhy2026/page-explorer

## Basic Information

- **Project Name**: page-explorer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Page Explorer

> `/page-explorer` 是一个面向测试产出的网页探索 skill。  
> 它基于用户真实页面操作，沉淀两份高价值产物：
> 1. 产品需求规格说明书 `.md`
> 2. 元素地图 `.yaml`

项目目标不是做通用网页摘要，也不是做重型浏览器录制平台，而是为后续 AI 生成测试用例与 UI 自动化脚本提供高可信输入。

---

## 核心定位

`page-explorer` 的职责是：

- 让用户走真实业务主链路
- 让助手记录页面、弹窗、抽屉、下拉、页签切换等关键结构证据
- 先生成结构化元素地图
- 再基于元素地图生成更像产品需求规格说明书的 `.md`
- 严格约束命名一致性，避免后续 AI 写测试脚本时“张冠李戴”

它不追求：

- 全站自动爬取
- 重型录屏或视频回放
- 脱离用户业务语义的纯 DOM 扫描
- 凭经验脑补页面元素或业务规则

---

## 默认产物

探索完成后默认只生成两份结果：

| 文件 | 作用 | 主要使用者 |
|------|------|------|
| `*.md` | 产品需求规格说明书 | 产品、测试、研发、后续用例生成 AI |
| `*.yaml` | 元素地图（定位资产） | UI 自动化脚本、脚本生成 AI |

说明：

- `.md` 用于表达业务目标、功能规格、状态规则、异常与待确认事项
- `.yaml` 用于表达页面、分区、元素、流程、弹窗、抽屉及定位信息
- 默认不生成 `.json` 和 `.spec.ts`
- `yaml` 模板结构固定，不在运行时变更

---

## 设计原则

本项目围绕下面 5 条原则工作：

1. 证据优先：没有真实观察证据，不进入正式事实。
2. YAML 优先：先生成 `element-map.yaml`，再生成 `requirement-spec.md`。
3. 命名受控：`.md` 中的页面名、分区名、流程名、弹窗名必须来自 YAML。
4. 路径内完整：不追求全站完整，但对用户真实走过的路径尽量完整记录。
5. 技术轻量：只做会话级记录与关键结构补采，不演化成重型录制平台。

补充说明：

- 默认按单主体、单会话探索
- 只有在真实操作中出现登录态变化、退出重登、新无痕窗口、另一登录主体接续流程等信号时，才进入多会话增强模式

---

## 快速开始

### 1. 准备 Node.js

需要 `Node.js >= 18`。

```bash
node -v
```

### 2. 克隆仓库并安装 skill

```bash
git clone git@github.com:<your-org>/page-explorer.git
cd page-explorer
```

安装脚本会自动把 skill 安装到已识别的助手目录中：

```bash
# macOS / Linux / WSL
bash scripts/install.sh

# Windows PowerShell
.\scripts\install.ps1
```

### 3. 安装 Playwright MCP

```bash
npm install -g @playwright/mcp
```

如果你使用 Claude Code，还需要配置 MCP：

```bash
# 项目级
claude mcp add playwright --scope project -- npx @playwright/mcp@latest

# 或用户级
claude mcp add playwright --scope user -- npx @playwright/mcp@latest
```

Reasonix / Codex 环境如果已经内置该 MCP，可跳过这一步。

### 4. 验证安装

在任意工作目录中打开助手，输入：

```text
/page-explorer
```

如果 skill 被正确识别，说明安装成功。

---

## 使用方式

推荐通过以下方式触发：

```text
/page-explorer https://example.com/admin
```

```text
/page-explorer https://example.com/admin 用户管理
```

兼容旧入口：

```text
/page-explorer --observe https://example.com/admin
```

说明：

- 裸 URL 默认不触发此 skill
- 用户明确给出 URL 后，默认从当前 URL 所在业务区域开始
- 若未特别声明“全量”或“多个区域”，skill 不会主动扩展成全站探索

---

## 推荐工作流

这是当前唯一推荐的主流程：

### 1. 助手先做开始前确认

开始前会说明两件事：

- 本次会默认生成 `.md` 和 `.yaml`
- 如后续补充探索需要验证完整流程，可能会新建、编辑或删除带标记的测试数据

用户确认后才开始探索。

### 2. 用户走真实业务主链路

用户按平时真实使用方式操作页面：

- 切换页面
- 打开弹窗
- 展开下拉
- 切换页签
- 填写表单
- 查看详情
- 走完关键业务闭环

### 3. 助手后台记录关键证据

记录重点包括：

- 页面跳转
- 登录态或主体上下文变化
- 独立浏览器会话变化
- 多页签切换
- 按钮点击
- 字段输入
- 弹窗/抽屉结构
- 下拉选项
- 状态变化

### 4. 用户说“结束探索”

结束后助手统一分析，而不是边操作边频繁打断。

### 5. 助手先生成 YAML，再生成 MD

生成顺序固定：

1. `element-map.yaml`
2. `requirement-spec.md`

`.md` 中的页面名、分区名、流程名、弹窗名必须从 YAML 复用，不允许另起别名。

### 6. 如有缺口，再做局部补采

如果缺的是：

- 某个下拉没展开
- 某个弹窗没完整打开
- 某个新页签里的关键操作没被覆盖

只补这个局部，不要求用户重走整条链路。

### 7. 多会话是可选增强，不是默认前提

如果探索过程中出现以下情况，助手会自动切换到“多会话增强模式”：

- 用户退出当前账号并重新登录
- 用户新开无痕窗口，用另一个账号继续操作
- 同一条业务链路天然需要另一登录主体接续完成
- 当前页面权限发生明显变化，说明主体上下文已变化

在这种模式下：

- 助手优先识别“会话变化”和“权限变化”
- 默认不会先要求用户提供精确角色名
- 会先确认是否需要新开独立浏览器会话
- 需求规格说明书会明确记录权限差异和主体协作
- 元素地图只做轻量的 `actor_id / session_id` 可选增强

---

## 为什么采用“先 YAML 后 MD”

因为这两份产物承担的职责不同：

- `yaml` 是结构化测试资产，负责页面结构、元素、流程、定位符
- `md` 是规格语义文档，负责业务目标、功能规格、状态规则、异常边界

如果先写 `.md`，再回头“尽量对齐” YAML，很容易出现：

- 页面名不一致
- 分区名不一致
- 流程名对不上
- 弹窗名写成别名
- 文档里出现 YAML 中不存在的对象

因此当前实现要求：

- YAML 是唯一命名词典
- MD 必须以后者为锚点生成

---

## 产物质量标准

### 对 `.yaml` 的要求

- 模板结构固定不变
- 只写已观察到或明确标记待确认的内容
- 页面、分区、元素、流程、弹窗、抽屉信息足够支撑 UI 自动化
- locator 与 fallback 同时存在
- 风险项与未稳定映射项表达清楚
- 多会话场景下允许增加 `actors / actor_id / session_id` 这类可选增强字段，但不改变主结构

### 对 `.md` 的要求

- 更像产品需求规格说明书，而不是探索总结
- 正文重点是功能规格、业务规则、状态与异常
- 页面名、分区名、流程名、弹窗名与 YAML 保持一致
- 不把未观察到的内容写成正式事实
- 待确认内容单独进入待确认章节
- 当存在多个登录主体或多个独立会话时，必须明确记录权限差异与主体协作关系

---

## 输出目录与命名

默认输出到当前工作目录的 `output/` 下。

命名规则：

```text
<范围名>_<yyyyMMddHHmm>.md
<范围名>_<yyyyMMddHHmm>.yaml
```

示例：

```text
数据广场_202607061530.md
数据广场_202607061530.yaml
```

```text
数据广场&工作台_202607061530.md
数据广场&工作台_202607061530.yaml
```

补充说明：

- 同一分钟重复执行时可追加秒数避免覆盖
- 默认新增文件，不覆盖历史结果
- 探索过程中的会话截图等中间资料可放在 `output/_sessions/` 下

---

## 当前实现重点

当前版本重点保证以下能力：

- 用户主导探索，助手不替代真实业务语义
- 多页签跟踪
- 新页签自动补注入，关闭页签自动移出活跃集合
- 关键弹窗/抽屉/下拉结构捕获
- 记录主业务流程与页面状态变化
- 先 YAML 后 MD
- 需求与元素命名强一致

当前版本明确不追求：

- 全站自动 DFS 爬取
- 视频级录制
- 全量 DOM 历史仓库
- 独立 trace viewer
- 网络请求语义分析平台

---

## 项目结构

```text
page-explorer/
├── AGENTS.md
├── README.md
├── skills/
│   └── page-explorer/
│       └── SKILL.md
├── .reasonix/
│   └── skills/
│       └── page-explorer/
│           └── SKILL.md
├── templates/
│   ├── requirement-spec.md
│   └── element-map.md
├── knowledge/
│   └── login-patterns.md
└── scripts/
    ├── install.sh
    ├── install.ps1
    ├── uninstall.sh
    ├── uninstall.ps1
    ├── detect-mcp.sh
    └── detect-mcp.ps1
```

说明：

- `skills/page-explorer/SKILL.md` 与 `.reasonix/skills/page-explorer/SKILL.md` 需要保持同步
- `templates/element-map.md` 为固定 YAML 结构模板
- `templates/requirement-spec.md` 定义规格说明书结构

---

## 更新

仓库更新后，重新运行安装脚本同步 skill：

```bash
git pull

# macOS / Linux / WSL
bash scripts/install.sh

# Windows PowerShell
.\scripts\install.ps1
```

---

## 卸载

```bash
# macOS / Linux / WSL
bash scripts/uninstall.sh

# Windows PowerShell
.\scripts\uninstall.ps1
```

---

## License

MIT