Pelican Test

评测“鹈鹕骑自行车”HTML/SVG 的 CLI：分析已有输出，或调用本机 Codex 生成后自动评分。 评分使用固定规则，不调用评分模型。

使用 CLI

需要 Node.js（版本要求见 package.json），通过自带的 npm/npx 即可运行，无需克隆仓库。 开发者从源码运行见从源码运行。按需求选择一种用法即可。

已有文件，直接评分（支持 HTML、SVG 或包含 HTML 代码块的模型回复，无需 Codex）：

npx @ryqdev/pelican-test@latest analyze result.html

使用镜像 registry（如 npmmirror）时，若镜像尚未同步导致 E404， 添加 --registry=https://registry.npmjs.org 后重试。

让本机 Codex 生成，再自动评分：

npx @ryqdev/pelican-test@latest run

run 需要本机已安装并配置好 Codex，默认使用其模型配置和内置提示词，无需填写参数。

不指定 --model 时，runner 在相同环境和临时工作目录中，通过 Codex App Server 的 临时线程读取已解析的模型，再用 --model 固定本次运行的模型。读取步骤不发起生成。 报告保留 codex.requestedModel（用户指定值，可为空）、codex.resolvedModel （传给测试进程的模型）及 codex.modelSource（explicit 或 local-codex）。 连接器只向网页传递这些模型元数据，不上传本机配置、登录凭证或 App Server 日志。

自动读取失败时测试会明确失败；可以更新 Codex 或显式指定 --model 后重试。 使用 --ignore-user-config 时必须同时指定 --model。这里记录的是本地 Codex 选择的 模型 ID，不是第三方网关后端模型的证明，也不读取其他运行中会话的临时模型覆盖。

每次启动一个新会话、生成一次，会使用当前账号或 provider 的额度。

run 的结果默认保存在当前目录的 .pelican/runs/<run-id>/，包括评分报告 report.json、 生成页面 output.html、原始回复 response.txt 和运行日志。

# 遇到 Codex 环境问题时检查（可选）
npx @ryqdev/pelican-test@latest doctor

# 批量评分，输出 JSON
npx @ryqdev/pelican-test@latest analyze result-a.html result-b.html --json

# 设置质量门槛：低于 80 分或出现硬失败时，退出码为 3
npx @ryqdev/pelican-test@latest analyze result.html --fail-under 80

# 指定模型、推理强度和超时（YOUR_MODEL 替换为可用的模型 ID）
npx @ryqdev/pelican-test@latest run --model YOUR_MODEL --effort medium --timeout 600

# 自定义 prompt 和输出目录（目录必须尚不存在）
npx @ryqdev/pelican-test@latest run --prompt-file prompt.txt --output .pelican/my-run

# 查看全部参数和退出码
npx @ryqdev/pelican-test@latest --help

推理档位支持 low、medium、high、xhigh、max、ultra，同时保留 none 和 minimal 以兼容支持它们的模型。可用档位取决于所选模型； CLI 会原样传递请求的档位，不会自动替换成其他值。

网页连接本机（测试版）

在本机终端的任意可写目录运行，无需克隆仓库、安装 pnpm 或手动构建：

npx @ryqdev/pelican-test@latest connect --site https://pelican-connect-test.vercel.app

在 Codex Pulse 中，复制的命令跟随页面语言，测评提示词也使用相应语言：

# 英文页面：英文提示词
npx --yes @ryqdev/pelican-test@latest connect --site https://codex-pulse.com/ --lang en --port 0

# 中文页面：中文提示词
npx --yes @ryqdev/pelican-test@latest connect --site https://codex-pulse.com/zh/ --lang zh --port 0

--lang en|zh 同时选择连接器提示语言和默认测评语言。省略时，--site 的 /zh 路径使用中文，其余路径使用英文。支持语言切换的网页可为每次测试指定语言，已有结果保留 原语言。截图直接来自生成的 HTML，提示词不限定画面文字语言或 HTML 的 lang 属性。 报告通过 prompt.language、prompt.version 和 prompt.sha256 记录实际测试条件。 当前内置版本为 pelican-bicycle-cli-v2-en 和 pelican-bicycle-cli-v2-zh。

直接运行 run --lang en 或 run --lang zh 也可选择提示词语言；run 省略参数时仍默认中文。 自定义 --prompt-file 优先，报告标记为 custom，不自动翻译内容。

打开测试网页。命令会打开一次性配对链接。 点击“连接这台电脑”后，就能在网页开始/取消测评、查看评分、 预览动画和下载报告。保留连接器终端，浏览器若提示本地网络访问权限，请选择允许。 这版配对当前浏览器与本机，尚未绑定网站账号；结果直接从本机返回网页，不上传到 Vercel。

首次运行时 npx 会提示下载 Pelican；测评结果保存在运行目录的 .pelican/runs/ 中。 web/ 提供可部署到 Vercel 的测试页面。本地开发运行 pnpm web:dev，并将 --site 设为 http://127.0.0.1:4173。 部署和协议细节见 网页连接说明。

安装和使用 Skill

codex-pulse Skill 已迁移到独立的公开仓库，可以让 Codex 调用 CLI、解释评分和比较报告。 Skill 通过 npx skills add 安装；使用时由 Codex 通过 npx 调用 Pelican CLI。 CLI 已发布到 npm，只需 Node.js 和 npm/npx，无需克隆源码、安装 pnpm、构建或手动创建软链接。

1. 安装 Skill

通过 Skills CLI 安装到 Codex：

npx skills add ryqdev/codex-pulse-skill --skill codex-pulse --agent codex -g

-g 表示全局安装，去掉则只安装到当前项目。Skill 在独立仓库中维护，本仓库不再内置副本。 已从旧仓库安装 codex-pulse 的用户，重新执行上面的命令并确认覆盖，即可切换安装来源。 此前安装了旧名 pelican-test 的用户，请移除旧 Skill 后安装 codex-pulse； 如果 Codex 未发现 Skill，重启后再试。

2. 在 Codex 对话中使用

$codex-pulse 分析 result.html，并解释主要扣分项。
$codex-pulse 用当前 Codex 配置跑一次评测，返回评分和报告路径。
$codex-pulse 解读 .pelican/runs/<run-id>/report.json。

文件路径和输出目录均相对于当前项目。分析已有文件、读取报告不会调用模型；新评测使用本机 Codex， 不代表调用 Skill 的当前对话模型。

从源码运行

开发 CLI 或测试尚未发布的改动时，准备 Node.js 和 pnpm（版本见 package.json），然后执行：

git clone https://github.com/ryqdev/pelican-test.git
cd pelican-test
pnpm install --frozen-lockfile
pnpm build
pnpm pelican --help

在仓库中将上述 npx @ryqdev/pelican-test@latest 换成 pnpm pelican 即可。 使用 Skill 时告诉 Codex 使用本地源码 CLI，并提供仓库路径，例如：

$codex-pulse 使用 /绝对路径/pelican-test 中的本地 CLI 分析 result.html。

Skill 会在当前项目目录通过绝对路径执行该 CLI。仅此用法需要保留源码、依赖和构建产物， 源码更新后重新执行 pnpm build。

评分说明

总分 100：完整性 25、SVG 丰富度 35、动画 25、工程质量 15。 评分仅基于静态 HTML/SVG，不执行页面，不能单独证明模型降智或画面、动画正确。

开发检查：pnpm check。发布流程见 RELEASING.md，许可证见 LICENSE。