Files
LFSpecs/README.md
T
2026-11-06 15:07:02 +08:00

19 KiB
Raw Blame History

LFSpecs

公开硬件规格库:收录手机、芯片等设备的详细参数,支持横向对比。设计文档见 DESIGN.md。

技术栈

Astro 7(SSR / Node adapter)+ Tailwind CSS 4 + shadcn/ui(React islands)+ SQLite(node:sqlite,无原生依赖)+ sharp(OG 图生成)

本地开发

pnpm install
cp .env.example .env        # Windows: Copy-Item .env.example .env
pnpm db:seed                # 建表 + 写入种子数据(Xiaomi 14 / REDMI K90 Pro Max / OPPO Find X10 Pro Max / 骁龙 8 Gen 3)
pnpm dev                    # http://localhost:4321
pnpm typecheck              # tsc --noEmit

组件自检页:/poc(验证 Button / Card / Dialog 可用,M0 验收后可删)。

编辑后台(M2)

访问 /admin,输入 .env 中的 ADMIN_PASSWORD 登录。登录态是 7 天有效的 HttpOnly 签名 cookie;连续 3 次密码错误会按 IP 限速 1 分钟。

  • 登录后是仪表盘:设备/芯片列表、最近修订记录、新增入口。
  • 设备编辑:/admin/devices/[slug],新增用 /admin/devices/new。新增页只需输入 slug,AI 会多源检索生成初稿并跳转到详细编辑;表单覆盖手机全部规格分组,多摄逐颗编辑,扬声器单元可增删;字段来源徽章与“已核实”勾选会保留。
  • 芯片编辑:/admin/chips/[slug],基础信息、GPU/NPU/内存等结构化字段,CPU 核心簇、跑分、扩展字段用 JSON 编辑。
  • 封面图上传:POST /api/upload,仅 jpg / png / webp / avif,单张 ≤ 10MB;M2 存原图,不做压缩转码。
  • 每次保存写入 revisions 快照(与主表同一事务),编辑页底部展示最近 10 条。

写接口(/api/devices、/api/chips、/api/upload)都要求登录态,并校验 Origin 与 Host / X-Forwarded-Host 同源;读页面完全公开。

生产环境务必替换 ADMIN_PASSWORD 与 SESSION_SECRET,并在 HTTPS 下设置 COOKIE_SECURE=1。 M2 只实现本地图片驱动;S3 驱动仍是接口占位(M4 或需要时再接)。

AI 补全(M3)

编辑页的「AI 补全」会按当前品牌 + 型号调用 POST /api/ai/lookup,返回带置信度的扁平字段。

  • 新增页「AI 快速创建」只需输入 slug:服务端推断品牌 / 型号,多源检索后写入初稿并跳转详细编辑页(POST /api/ai/prospect)。
  • 未配置 Tavily 时使用 Bing / Baidu / DuckDuckGo 公开检索 + ZOL / GSMArena / Kalvo 站内直查,并只抓取白名单站点:厂商官网、ZOL、PConline、Kalvo、GSMArena、IT之家、快科技、Notebookcheck 等;按域名限流并做多源交叉验证。
  • 详细编辑页每个规格分区标题旁有「区块 AI」(POST /api/ai/section),一次检索该区块的全部字段(如屏幕、内存与存储、电池、连接),结果可勾选后应用;比单字段补全多了区块上下文,更容易拿到面板厂商、发光材料等分散信息。
  • 详细编辑页每个规格字段旁有 AI 按钮(POST /api/ai/field),只针对该字段重新检索;适合官网不公开的扬声器单元型号、尺寸、马达型号、体积等。字段旁的「补充参考资料」文本也会参与该字段检索。
  • 「补充参考资料」支持多行 URL:每行一个官网 / ZOL / PConline 链接,服务端会抓取正文并与公开检索结果合并(按 URL 去重);缓存键包含 URL 与补充文本的摘要,二次补全不会命中旧结果。
  • 面向中国大陆:提示词要求简体中文与国行人民币价格,pricing 会过滤 EUR / USD / GBP 与海外版本;officialUrl 从已抓取来源中自动选具体产品页,避免写成品牌首页或系列列表。
  • 字段级补全会复用整机补全已抓取的来源(如 ZOL / PConline),公开检索临时失败时仍能继续;确实没有公开数据时按钮显示 无 并标注「无公开数据」,与真正的检索失败区分。
  • 公开检索按型号做来源筛选;纯数字型号(如 OnePlus 16)改用品牌词排除 iPhone / Meizu 16 等同名干扰。
  • 新增大模型输出截断保护:JSON 被截断时保留已完整的字段对象,避免整批结果丢失。

配置 .env:

AI_BASE_URL=https://api.deepseek.com/v1   # 任何 OpenAI 兼容接口
AI_API_KEY=
AI_MODEL=deepseek-chat
SEARCH_API_KEY=                           # 可选:Tavily 兼容搜索
SEARCH_BASE_URL=https://api.tavily.com
  • 有搜索 key 时:优先走 Tavily,把标题 / URL / 摘要塞进提示词;抓取失败的来源会被跳过。
  • 没有搜索 key 时:使用 Bing / Baidu / DuckDuckGo 公开检索 + ZOL / GSMArena / Kalvo 站内直查,只抓取白名单站点(官网、ZOL、PConline、Kalvo、GSMArena 等),同一域名最多 2 条;页面正文按"规格密度"取窗(优先参数表而非页头导航);检索完全失败才降级为模型知识,并将 high 降为 medium。资料未覆盖但属于公开常识的字段,模型可给 low 置信度并注明「模型知识,待核实」。
  • 字段级与区块级补全走全网自由检索:不限白名单站点(评测、百科、论坛等均可作依据,白名单站仍优先排序),接受的置信度下限为 low;整机补全仍保持白名单交叉验证。
  • 拆机视频通道:三处检索都会附加 site:bilibili.com 机型 拆解 查询,B 站视频页走官方接口获取标题 + 简介;在 .env 配置 BILIBILI_SESSDATA(B 站登录态)后还会拉取字幕全文——马达型号、扬声器单元等官网不公开的细节主要在拆机视频的口播里(如微机分等拆解 UP 主)。未配置 SESSDATA 时字幕接口返回空,来源价值有限。
  • 编辑页「AI 补全」下方提供可选的「补充参考资料」:可粘贴官网参数文本并填写官方链接。最新机型未进模型知识库时,用它可显著提高字段覆盖;补充文本会参与缓存键,避免与无资料结果串缓存。
  • 提示词覆盖全部规格分组与设备补充字段(手机特点 / 影像功能 / 跑分 / 售价 / 官网),摄像头逐颗、扬声器最多 5 个单元;display.refreshNote 用于表达“185Hz 仅部分游戏场景生效”这类附加条件。
  • 只接受白名单路径(src/lib/spec-fields.ts),值类型按路径定义强转;摄像头位置只允许 wide/ultrawide/tele/periscope/macro/depth/mono/color/front。
  • 预览显示「当前值 → AI 值」、置信度徽章与来源,可逐项勾选后应用。
  • 应用后 low 字段阻塞保存;底部提供「确认全部 low」「清空全部 low」,来源区可「全部接受 high」。
  • 结果按 phone|品牌|型号(有补充资料时追加文本哈希)缓存到 ai_cache;勾选「忽略缓存」可强制刷新。字段级检索按 field|品牌|型号|路径 单独缓存。
  • AI 关键配置缺失时接口返回 503,页面会直接显示原因;AI key 只在服务端读取。

M3 验收曾使用本地 mock;本轮已用 DeepSeek 实测:多源检索 OPPO Find X10 Pro Max 时抓取官网 / ZOL / PConline / Kalvo 共 6 个来源,返回 100 个字段;来源不足的机型(如 OnePlus 15)只返回少量字段,说明覆盖度取决于公开资料质量。

对比(M4)

设备列表和详情页的「加入对比」会把机型放进底部固定托盘(最多 4 款,选择保存在 localStorage),托盘里可直接移除或点「开始对比」进入结果页。直接访问 /compare 时是搜索 + 品牌筛选 + 分页的设备选择器,点「+ 加入」加入当前选择;已选 2 款以上时可从顶部「查看对比」进入结果。

  • 差异项高亮并显示圆点,缺失值显示 — 并置灰。
  • 「只看差异」用 ?diff=1 切换,只保留有差异的行。
  • 分组默认展开,可点击分组标题折叠;首列字段名在横向滚动时保持粘性。
  • 重量、屏幕尺寸、亮度、刷新率、电池容量、充电功率等数值字段带相对条形图。

导出与导入(M4)

  • GET /api/export:公开下载全量 JSON,formatVersion: 1,包含 devices 与 chips。
  • /admin/import:登录后粘贴或选择 JSON 导入;按 slug upsert,已存在的 slug 会被覆盖,未出现在文件里的数据不会删除。
  • 导入会先对整批数据跑 zod 校验,只要有一条不合法就整批拒绝,不会写入半份数据。
  • 限制:单次最多 5000 条、请求体 ≤ 20MB。

JSON 不包含图片。迁移或恢复时请同时拷贝 data/app.db(或备份)与 data/uploads/。

从 phonerecommend.top 同步

pnpm sync:phonerecommend                        # 只产出 data/import/phonerecommend-<时间>.json
pnpm sync:phonerecommend -- --write             # 同时按 slug upsert 到 data/app.db
pnpm sync:phonerecommend -- --write --images    # 并下载封面 / 相册到 data/uploads
pnpm sync:phonerecommend -- --brand 华为 --brand 小米
  • 源站列表接口 /api/phones?limit=100&page=N 已包含完整规格组,需要带浏览器 UA 与 Referer。
  • 品牌转英文规范名,中文型号转拼音 slug;输出结构与本项目 formatVersion: 1 一致。
  • 源站个别记录型号只写了品牌(如 OPPO / OPPO),会回退到 product_model 并去掉品牌前缀;同名同发布时间的重复机型会被跳过。
  • 源站缺少的结构化字段(传感器型号、马达体积、无线充电等)会留空,可继续用字段级 AI 补全。
  • 屏幕亮度会区分「典型亮度 / 局部峰值亮度 / 全局峰值亮度」,不再按数字出现顺序猜测;源站 navigation 等文本中混入的商城推荐内容会被截断。
  • --images 会下载封面 / 相册并转成 WebP,落到 data/uploads/devices/<slug>/,页面通过 /uploads/devices/<slug>/... 读取;下载后会清理本地不存在的图片引用。slug 冲突以源站为准覆盖本地记录,执行前建议先 pnpm backup。

从 phonerecommend.top 同步处理器

pnpm sync:processors                    # 只产出 data/import/processors-<时间>.json
pnpm sync:processors -- --write         # 写入 chips,并按芯片名回填设备的 SoC 引用
pnpm sync:processors -- --limit 10      # 只处理前 10 颗
  • 列表接口 /api/processors?limit=100&page=N 共 224 条,按 key 去重后为 203 颗;详情接口补充跑分、别名、来源与官方规格表。
  • chips.detail 新增 overview / cpuBlock / gpuBlock / npuBlock / cameraBlock / displayBlock / connectivityBlock / benchmarkInfo / traits / caveats / sourceUrls / specGroups;芯片列表按档位分与年份排序,详情页展示 CPU 簇、跑分、内存/影像/连接与可折叠的完整规格。
  • --write 会按 specs.platform.chipset 与芯片名称 / 别名匹配,回填 devices.chipRefs.soc,芯片详情页可直接列出搭载机型。
  • 源站对高频请求返回 429 / 403,脚本已内置退避重试与低并发;个别旧处理器详情失败时仍保留列表字段。

从酷安补充 / 覆盖手机参数

pnpm sync:coolapk                    # 只产出 data/import/coolapk-<时间>.json
pnpm sync:coolapk -- --write         # 合并进 data/app.db
pnpm sync:coolapk -- --limit 10      # 只处理前 10 款
pnpm sync:coolapk -- --slug oneplus-16   # 只处理指定 slug(含自动创建的新机型)
  • 先分页读取酷安机型目录(缓存在 data/cache/coolapk-products.json,当前 1505 条,去重后 1504 款),按品牌别名 + 型号匹配本地设备;名称拼接未命中时会再按「推断品牌 + 型号」精确匹配一次。
  • 本地没有的酷安机型也会自动创建:从产品名前缀推断品牌与型号,用拼音生成 slug,读取「发布时间」写入上市 / 发布与状态,并生成列表摘要;封面与相册留空,后续可继续补图。
  • 读取每个机型的版本列表,取基础版本参与每 4 台一组的配置对比,解析完整参数表,再映射到机身、屏幕、平台、内存、电池、网络、马达、扬声器、传感器与摄像头等字段。
  • 覆盖策略:酷安为权威源,但不让低信息度内容覆盖高信息度内容——先比较数字、单位与文本完整度,酷安更完整才覆盖;两边数值明显冲突时视为不一致,采用酷安。分辨率(防止「1.5K」覆盖精确像素)、摄像头像素、长焦焦距、传感器型号、视频规格都有单独的保护规则;频段与传感器清单使用并集。
  • specs.coolapk 只保留产品 ID、配置 ID、价格、同步时间与酷安评分(总评 / 机主 / 续航 / 影像 / 性能 / 屏幕 / 外观质感 / 性价比);原始参数表不再入库,详情页标题下方直接展示评分与同步日期。
  • 执行 --write 前建议先 pnpm backup。

动效、OG 图与打印(M5)

  • 页面动效:Astro <ClientRouter /> + 主内容淡入;列表网格用 CSS reveal-grid 做轻量渐入与 40ms 级联。prefers-reduced-motion: reduce 时全部关闭,未引入 GSAP / Lenis。
  • 黑白主题:右上角按钮切换日间 / 夜间主题;首次访问跟随系统,之后用 localStorage 记住,跨页导航和刷新都保持。打印时强制浅色。
  • 详情页参数 hover:关键参数卡、影像卡和规格表行在鼠标悬停时高亮背景并把字段名切为强调色,便于定位当前参数;顶部参数卡可点击跳转到对应详细分组。
  • OG 图:GET /og/[slug].png 动态生成 1200×630 PNG,设备页自动使用 /og/<slug>.png,其他页面默认 /og/site.png;详情页同时输出 og:*、twitter:card、canonical。
  • 打印:设备详情页有「打印 / 保存 PDF」按钮;@media print 切换浅色配色、隐藏导航/页脚/按钮、取消 sticky 与横向滚动,并尽量避免表格跨页断行。
  • 字体依赖:OG 图文字只使用 Latin 字符,避免容器缺中文字体时出现方框。sharp 通过系统字体渲染,需要 fontconfig + DejaVu:
    • 标准 Dockerfile 已安装 fontconfig / ttf-dejavu。
    • 宿主构建 + node:24-slim 挂载方式会把宿主机的 /usr/share/fonts 与 /etc/fonts 只读挂进容器。

详情页参数展示

  • 标题下方是「配色 + 初始售价」展示带:配色用圆形色块 + 中文色名,售价按版本拆成卡片并高亮起售价;背景渐变取自首个配色,作为该机型的页面色彩主题。色块优先使用 body.colorHexes(与 body.colors 顺序一致,AI / 人工维护);缺失时按中文色名推断(星光→银白、森林→绿、火星→橙等),未知名称用稳定哈希色相。
  • 顶部参数卡分多排展示:SoC、屏幕、电池、主摄、超广角、长焦、影像场景、内存、存储、充电、无线充电、系统、扬声器、马达、Wi-Fi、USB、指纹、重量、防护。卡片高度统一,数值加大加粗,长文本两行截断;电池、充电、Wi-Fi、相机卡使用短值 + 关键副标题,避免整段参数无法阅读。
  • 卡片上方提供分组快捷导航;详细参数按“屏幕与外观 → 性能 → 影像 → 电池与充电 → 音频与振动 → 连接与网络 → 传感器 → 系统与更新 → 发布与补充”排序,每节带编号与分组小标题。
  • 性能节合并 SoC 卡片、平台、内存与存储及跑分;未关联芯片库时显示芯片名与“芯片库暂未收录”,避免空白区块。影像节按后置 / 前置分组,镜头头衔使用中文位置(主摄 / 超广角 / 长焦 / 潜望式长焦 / 色彩镜头等),并显示传感器营销名。
  • 屏幕补充面板厂商(如 TCL 华星)与技术代号(如 C8),并展示挖孔形态、刷新附加说明(如“最高 185Hz 仅部分游戏场景生效”)、瞬时触控采样率、色深、色域、像素密度、OLED 等效 PPI、屏占比、边框、16:9 等效尺寸、屏幕特性与其它说明。
  • 扬声器按 speakers.units[] 任意数量拆行,支持上 / 下 / 中置 / 第三单元等自定义标识,不再限定双扬声器;每单元给出型号、尺寸与功率。马达给出型号、尺寸与实际体积;USB 给出型号、实际速率与视频输出;系统列出出厂版本、当前版本及更新时间线。
  • 前后摄新增传感器营销名(如“光影猎人 900”)与视场角;影像功能、手机特点、设备跑分、官网、备注与耳机接口等补充信息单独展示;初始售价在顶部展示带中呈现。
  • 连接分组内,“移动网络频段”和“卫星通信频段”在 hover / 聚焦时弹出频段面板;卫星面板同时显示运营商(天通 / 北斗等)。
  • 字段级置信度只标记 low:低置信字段旁显示 low 徽章,hover / 聚焦显示字段名、路径、核实状态与来源;high 与 medium 不做常驻标记。页面底部不再展示字段级来源清单,避免信息过载。

部署

小内存服务器(当前 ECS 方案)

ECS 只有 1.6G 内存,Docker 多阶段构建会触发 kcompactd 长时间阻塞(load 飙到 40+)。因此改为「宿主构建 + 容器挂载」:

bash scripts/deploy.sh

脚本依次执行:拉代码 → pnpm install → pnpm build → docker compose up -d --force-recreate。容器用 node:24-slim 镜像,挂载 dist / node_modules / data,只有 ./data 需要持久化。

前提:服务器 Node 装在 /opt/node(脚本会自动加进 PATH),且已存在 .env。

普通机器 / CI

docker compose build && docker compose up -d 仍可用仓库里的 Dockerfile 构建单镜像,不需要挂载。

运维

pnpm backup     # VACUUM INTO 快照 + 打包 uploads 到 backups/<时间戳>/
pnpm db:seed    # 重跑种子数据(幂等,按 slug upsert)
pnpm typecheck  # 类型检查

目录

src/lib/schema/      zod 数据模型(phone / soc / FieldMeta)
src/lib/db.ts        SQLite 连接 + 迁移
src/lib/repo.ts      唯一数据出入口(含修订快照)
src/lib/storage.ts   图片存储驱动(local / s3 接口)
src/lib/auth.ts      登录、签名 cookie、限速、写接口守卫
src/lib/env.ts       运行时读取 .env(standalone / 脚本共用)
src/lib/spec-fields.ts 手机字段注册表 + 路径读写工具(表单 / AI / 对比共用)
src/lib/compare.ts   对比分组、差异判定与数值提取
src/lib/og.ts        OG 卡片 SVG -> PNG(sharp)
src/lib/ai/          搜索、提示词、模型调用、字段校验、置信度与合并规则
src/middleware.ts    /admin/** 登录拦截
src/pages/admin/     登录/仪表盘、设备与芯片编辑页、导入页
src/components/admin/ 编辑表单(React islands,含 AI 差异预览、导入面板)
src/pages/api/       auth / devices / chips / upload / ai / export / import
migrations/          SQL 迁移,按文件名顺序执行
scripts/             seed / backup / sync-phonerecommend / sync-processors / sync-coolapk

在受限沙箱里 pnpm dev 首次 SSR 模块加载可能极慢;可改用 pnpm build && node dist/server/entry.mjs 在本地验证生产路径(设置 HOST / PORT 即可)。