PageLens 是供 Codex 使用的 Windows 网页内容提取 Skill。它从静态 HTML、JavaScript 页面和需要人工验证的页面中提取完整正文，转换为 Markdown，并默认生成 PixelRAG 视觉切片。
当前版本为 1.0.0，版本号以仓库根目录的 VERSION 为准。项目目前只支持 Windows。
在 Codex 中，可以让 $skill-installer 从 MiPoNianYou/PageLens 安装。没有 Skill 安装器时，手动克隆到个人 Skills 目录：
git clone https://github.com/MiPoNianYou/PageLens.git "$env:USERPROFILE\.agents\skills\pagelens"
Set-Location "$env:USERPROFILE\.agents\skills\pagelens"
scripts\pagelens.cmd setup首次 setup 会先说明哪些数据会发送到 html-to-markdown.com。只有在本地终端输入 AGREE 后，PageLens 才会验证并保存 API Key。Key 使用隐藏输入并写入 Windows Credential Manager。CI 或无界面环境可以只在当前进程中设置 PAGELENS_API_KEY；环境变量本身视为已经获得调用方授权，不会写入凭据存储。
$env:PAGELENS_API_KEY = "your-api-key"
scripts\pagelens.cmd --url "https://example.com/article"PageLens 会在 %LOCALAPPDATA%\PageLens\runtime 准备 PageLens 专用的 Python 3.12 和 PixelRAG 运行时，不修改系统 PATH。Python 依赖来自带 SHA-256 的 requirements.lock，运行时目录按锁文件摘要区分。uv 使用固定版本下载并校验官方 SHA-256。桌面运行优先复用 Codex 自带的 Playwright；GitHub Actions 使用 package-lock.json 锁定的 playwright-core 配合 runner 上的 Chrome。
URL 模式依次尝试：
- 下载服务端 HTML，提取正文。
- 内容不足时，用 PageLens 自己启动的 Chromium 渲染。
- 对已支持的站点读取文章接口响应，避免把应用外壳当正文。
- 遇到验证码时，使用
--interactive打开可见浏览器，由用户手动完成验证。 - 仍拿不到完整正文就失败；只有明确传入
--allow-preview才输出带标记的分享预览。
PageLens 不支持登录态网页抓取。交互浏览器只用于验证码或访问验证，请不要输入账号密码。
| 输入 | 参数 | 说明 |
|---|---|---|
| 公开网页 | --url |
只允许 HTTP/HTTPS，默认端口 80 或 443 |
| 短 HTML | --html |
直接传入 HTML 片段 |
| 本地文件 | --input |
读取 UTF-8 HTML 文件 |
| 标准输入 | 无 | 接收管道中的 HTML |
# JavaScript 页面
scripts\pagelens.cmd --url "https://example.com/app" --render-timeout 45
# 人工完成验证码
scripts\pagelens.cmd --url "https://example.com/article" --interactive
# 明确允许一个额外的公开端口
scripts\pagelens.cmd --url "https://example.com:8443/article" --allow-port 8443
# 本地 HTML；视觉捕获可读取该文件同目录资源
scripts\pagelens.cmd --input page.html --domain "https://example.com" --plugin table --output page.md
# 只要 Markdown
scripts\pagelens.cmd --url "https://example.com/article" --no-pixelrag
# 环境检查
scripts\pagelens.cmd --doctor
scripts\pagelens.cmd --doctor --json
scripts\pagelens.cmd --doctor --onlineURL 模式使用最终页面地址解析相对链接。非 URL 输入需要解析相对链接时，传入 --domain。strikethrough 和 table 可以重复使用；CommonMark 始终启用。
抓取 URL 时不用传 --output。PageLens 会按站点名和当前时间保存到：
pagelens-artifacts/retrieved/
└── wechat-260806-070600/
├── article.md
├── manifest.json
├── tiles.json
├── tile_*.jpg
└── pagelens-result.json
如果同一站点在一秒内保存多次，目录名会加上 -02、-03 等后缀。想自己定文件名时再用 --output。处理 HTML、本地文件或标准输入时，如果没有传 --output，Markdown 仍会写到标准输出。
传入 --output article.md 后，文件会放在：
article/
├── article.md
├── manifest.json
├── tiles.json
├── tile_*.jpg
└── pagelens-result.json
退出码：0 表示 Markdown 和截图都已生成；1 表示没有取得可用内容；2 表示 Markdown 已保存，但截图没有生成完整。
- 主请求、跳转、浏览器子资源和 PixelRAG 视觉页都会拦截本机、内网、链路本地、保留地址、云元数据地址和混合公私网 DNS 结果。每次连接都会重新校验并固定到已通过检查的 IP。
- 默认只允许公开地址的 80 和 443 端口；
--allow-port一次只能额外允许一个端口。 - 动态渲染和 PixelRAG 都使用 PageLens 启动的 Chromium，并强制启用 Chromium 沙箱。PixelRAG 通过 CDP 附着到这个浏览器，不再自行启动带
--no-sandbox的 Chrome。 - 本地 HTML 通过临时只读服务提供给视觉捕获。它不列目录，只允许读取输入文件同目录中的普通文件，并阻止路径穿越和符号链接逃逸。行内 HTML 和标准输入使用单独的临时目录。
PAGELENS_API_KEY不会传给浏览器、PixelRAG 或依赖安装子进程，只会用于正文转换请求。
只有 --interactive 成功完成验证后，PageLens 才会保存该站点可用的第一方 Cookie 和当前来源的 localStorage。状态保存在 %USERPROFILE%\.codex\state\pagelens，使用当前 Windows 用户的 DPAPI 加密，连续 30 天未使用会自动删除。PageLens 不读取日常浏览器的密码、扩展、历史记录或配置文件。
Markdown 转换依赖 html-to-markdown.com。发送内容包括提取后的 HTML、用于解析相对链接的基准地址和转换选项，不包括浏览器 Cookie 或保存的验证状态。不要处理密码、令牌、私人文档或其他不应发送给第三方服务的内容。转换结果仍应视为不受信任文本；以后转成 HTML 显示时，必须在渲染前清理。
首次准备状态写入 %LOCALAPPDATA%\PageLens\state\bootstrap-result.json。如需重建运行时，运行 scripts\pagelens.cmd --reset-runtime 后输入 RESET。默认超时为：API Key 校验 30 秒、uv 下载 300 秒、依赖同步 15 分钟、并发锁等待 2 分钟。
排查问题时请同时提供当前代码版本：
git rev-parse HEAD不要附上 API Key、Cookie、加密状态文件或私人网页结果。安全漏洞请按 SECURITY.md 私下报告。
python -m unittest discover -s tests -v
python -m py_compile scripts/convert_html.py scripts/network_policy.py
node --test 'tests/*.mjs'
Get-ChildItem scripts -Filter *.mjs | ForEach-Object { node --check $_.FullName }Pull Request 运行离线检查。main 的每次推送还会使用仓库 Secret PAGELENS_API_KEY，对公开测试页执行真实 Markdown 转换和 PixelRAG 捕获；Secret 缺失，或实际转换和视觉捕获失败时，CI 会失败。
PageLens 以 MIT License 发布。第三方依赖说明见 THIRD_PARTY_NOTICES.md，贡献方式见 CONTRIBUTING.md。