Imported from NWYLZW/model-pulse (AGENTS.md). Install upstream with npx skills add NWYLZW/model-pulse. Copyright stays with the author.

Model Pulse Agent Guide

本文件是本仓库的数据采集、整理和展示口径。修改模型数据、榜单快照、时间轴或指标映射前，必须先遵守这里的规则。

基本原则

• 不猜测、不补造榜单数据。没有可复核来源的值使用 null，不要用 0 代替。
• 每条公开数据必须能追溯到来源、快照时间和原始字段。
• 公开榜单快照、人工整理数据和演示/预测数据必须明确分层，不能混称为真实榜单数据。
• 模型只能从公开发布日期当天开始出现在时间轴中，不能把当前榜单结果倒灌到模型发布之前。
• 不把不同评测体系的原始分数直接相加、求平均或互相换算。跨体系只能分别展示。
• 页面内的过滤、缩放、聚合和异常值处理只影响展示，不得修改底层原始快照。

数据可信等级

数据按以下等级管理：

1. snapshot：从公开榜单页面在明确时间下载并由脚本抽取的数据。
2. curated：从多个公开来源人工交叉核对、整理或归一化的数据。
3. prototype：为验证交互而构造、推演或尚未取得公开证据的数据。

src/artificialAnalysisSnapshot.ts 和 src/arenaSnapshot.ts 属于 snapshot。src/data.ts 中手工维护的模型和月度点位属于 curated 或 prototype，不能仅凭其存在就宣称为公开事实。尤其是未来模型、未来发布日期、未来性能、速度和价格，必须标为 prototype，不得混入公开榜单口径。

新数据结构应增加可机器读取的来源类型，例如 provenance: 'snapshot' | 'curated' | 'prototype'。在完成该字段改造前，维护者必须依据本节判断并在 UI 文案中如实说明。

公开来源

来源网页持续变化。任何刷新都必须记录实际下载日期或榜单 cutoff，不能只写“最新”。若网页无法访问或字段含义不明确，应保留缺失值并记录问题，不得推断数值。

Artificial Analysis 快照

• 原始页面保存到 /tmp/artificial-models.html。
• 使用 node work/extract-artificial-analysis.mjs 生成 src/artificialAnalysisSnapshot.ts。
• 当前脚本抽取字段：
  • name
  • shortName
  • slug
  • releaseDate
  • organization
  • intelligenceIndex -> intelligence
  • codingIndex -> coding
  • price1mBlended0To3To1 -> price
  • medianOutputTokensPerSecond -> speed
• 当前时间窗口为 2025-01-01 至 2026-09-08，两端均包含。
• 以 slug 去重；同一 slug 只保留第一次匹配到的记录。
• 输出按发布日期倒序排列，同日再按综合智能指数倒序排列。
• 少于 100 条时脚本必须失败，防止页面结构变化后静默生成残缺数据。
• 生成文件必须包含快照下载日期，且不得手工编辑。

修改时间窗口时，应把日期提取为显式配置并同步更新生成文件头部，不能只改其中一处。

LMArena 快照

• 原始页面保存到 /tmp/arena-text.html。
• 使用 node work/extract-arena-snapshot.mjs 生成 src/arenaSnapshot.ts。
• 当前脚本只取 Text Leaderboard 前 100 条。
• 抽取字段：
  • rank
  • modelKey -> key
  • modelDisplayName -> name
  • modelOrganization -> organization
  • rating
  • inputPricePerMillion -> inputPrice
  • outputPricePerMillion -> outputPrice
• 当前快照 cutoff 为 2026-09-02T21:00:00.000Z；在此日期之前，页面不得展示该快照为当时已有的数据。
• 必须恰好抽取 100 条，否则脚本失败。
• 生成文件必须包含 cutoff，且不得手工编辑。

指标口径

价格

• 单位为 USD / 1M tokens。
• Artificial Analysis 使用来源字段 price1mBlended0To3To1。
• LMArena 输入/输出价转换为混合价格时使用：(inputPrice * 3 + outputPrice) / 4，即输入:输出为 3:1。
• null 表示没有可靠价格数据。
• 来源中的 0 只表示来源/API 列价为 0 或缺少可计费价格，不代表部署、算力或自托管成本为零。
• 价格上限过滤时，null 和小于等于 0 的价格不应被当作满足条件的免费模型。

速度

• 单位为输出 tokens / second。
• 使用来源的 median output tokens per second，不用首 Token 延迟替代。
• 没有可匹配速度时使用 null，不得取同厂商或相近型号的速度填充。

分数

• intelligence 与 coding 优先使用 Artificial Analysis 对应字段。
• arena 使用当前 LMArena 快照中的 Rating/Elo，并应在界面上明确标注单位。
• reasoning 当前来自 src/data.ts 的策划数据，不得描述为已由单一公开榜单直接抽取。
• 归一化分仅用于同一评测体系内部比较，不能解释为跨榜单的绝对能力差距。
• 不得把 Arena Elo、Artificial Analysis 指数、SWE-bench、LiveCodeBench、GPQA、AIME 或 LiveBench 原始分数直接相加。

日期与时间轴

• 日期统一存为 ISO YYYY-MM-DD，比较和格式化使用 UTC，避免本地时区导致跨日。
• 模型的首次可见日期必须等于或晚于其公开发布日期。
• 某日没有新公开数据时，可以沿用该日之前最近一次公开快照，但必须在 UI 中说明“沿用最近一次公开快照”。
• 沿用快照只代表页面状态延续，不代表来源在每一天都重新评测过。
• 不允许使用未来快照重建过去排名，也不允许用月底数据填充整个月。
• 无可靠发布日期的模型不能通过发布时间过滤；需要先补齐来源或保持不可见。

名称匹配与去重

• Artificial Analysis 快照以 slug 为稳定主键。
• LMArena 快照以 modelKey 为稳定主键。
• 跨来源匹配当前会将名称转为小写并移除非字母数字字符，再尝试匹配 Artificial Analysis 的 slug 或 shortName。
• 自动匹配结果必须人工抽查。名称相似但版本、推理强度、上下文长度或 fallback 配置不同的模型不得合并。
• 同一模型的别名应维护显式 alias，而不是扩大模糊匹配规则。
• 网格中的视觉合并不等于数据去重；hover/tabs 仍须保留该格内全部原始模型。

厂商标准化

当前标准化规则如下：

• SpaceXAI -> xAI
• Bytedance -> ByteDance
• ByteDance Seed -> ByteDance
• Z AI -> Z.ai
• Kimi -> Moonshot
• Thinking Machines / Thinky -> Thinking Machines
• 空厂商 -> Other

添加 alias 前必须确认确属同一组织。不要把合作方、模型托管方或 API 分销方自动视为模型厂商。

缺失值与异常值

• 缺失字段保持 null；不得以 0、均值、相邻日期或相似模型进行填补。
• 图表需要完整的坐标字段时，可以暂不展示该模型，但 tooltip、排行榜或数据说明应保留“无数据”的语义。
• 极高价格、速度或分数等离散点可以从自动缩放范围计算中排除，但不能从数据集删除。
• 当前价格范围使用正数的对数空间 IQR 上界识别离散点；此规则只用于视图尺度。
• 对速度颜色映射做分位数截断同样只影响视觉对比，不改变真实速度值。

刷新流程

1. 从公开来源下载完整原始页面，并记录 UTC 下载时间、页面 URL 和可见榜单名称。
2. 将原始 HTML 放到对应的 /tmp/*.html 路径。
3. 运行对应提取脚本，禁止直接修改生成的 TypeScript 快照。
4. 检查条目数、日期范围、空值比例、重复主键、异常价格与异常速度。
5. 抽查榜首、榜尾、新发布模型、同名变体和厂商映射。
6. 查看生成文件 diff，确认没有因网页结构变化造成字段错位。
7. 运行 pnpm run build。
8. 更新页面数据说明中的快照日期、cutoff 和来源用途。

若刷新脚本依赖的网页结构变化，应先修复解析器并保留失败保护；不要为了让脚本通过而降低数量校验或吞掉解析错误。

修改检查清单

• 是否给每个新数据集记录了来源 URL 和精确快照时间？
• 是否区分了 snapshot、curated 与 prototype？
• 是否保证模型不会早于公开发布日期出现？
• 是否保留 null，没有把未知数据写成 0？
• 是否避免跨评测体系直接合成分数？
• 是否检查了模型版本、推理档位和 fallback 配置，避免错误去重？
• 是否同步更新厂商 alias、图标和颜色映射？
• 是否运行生成脚本、检查 diff 并通过 pnpm run build？