各版本的主要变更
原本借 Appica 的十个部件改建在 Base UI 等引擎上,整个组件库从同一份契约取曲线;顺带修好了被弹层挡住的 toast。
toast、select、switch、加载指示、轮播、日历、日期/时间/数字字段改建在 Base UI、react-day-picker 与 Embla 上,共用一份动效与样式契约,字段与输入框、按钮同在 28 / 32 / 36 阶梯。实验室参数面板里,开关的滑块离开轨道边缘并带上对勾,select 的高亮在选项间滑动。
对话框从中心弹出,侧栏从边缘滑入,浮层、提示与菜单同一条曲线;菜单、组合框与单选切换组共用一枚滑动高亮,勾选标记渐入而非跳变,折叠面板展开有高度动画,标签页指示条滑动。提示延迟 400ms 出现,实时状态点改为呼吸;减少动态效果时一律收敛。
搜索框有了清除按钮,按 Esc 也能清空;条件签行末尾的「清除」把检索词算作一个条件并一并清掉;结果数会读给屏幕阅读器。成功与错误色由翠绿、玫红改为绿、红。
侧栏或对话框打开时弹出的提示,过去落在遮罩后面,看不清也点不到关闭与重试;长链接也会在卡片内换行,不再溢出。
Wallhaven 与 SEC EDGAR 两个实验室页改为按请求渲染——它们的查询要访问本站 API,而构建时 API 并不存在。
从组件引擎借来的字段,现在每一档都落在本系统的尺寸阶梯上,而不只是中间那一档。
select、日期、时间、数字字段的小号与大号一直还是引擎的尺寸;五个字段 seam 现在共用一把尺子——28 / 32 / 36,禁用态边框与「图标 + 文字」的值一并修正。
一个宽表格曾经能把整页连同吸顶栏一起推出视口,而不是自己在容器里滚。外壳少了一个类。
flex 子项的自动最小尺寸是内容的 min-content 宽度,而外壳那一层装着整个页面——于是任何本该自己滚的宽区域都变成了页面的宽度,吸顶栏也跟着跑。现在它按给定的空间排,宽区域各自滚各自的。
每页标题上方那行站名,说的是你已经知道的事。
「VPN 下有的慢、有的报错」拆成两件事各自解决:每次请求有了 20 秒期限,失败带着名字上屏且不再对无法恢复的状况重试;附带实验室面板不再躲在两条吸顶带下面,以及 toast 与 slider 两处缝合层修正。
默认 20 秒,`timeoutMs` 可改、`null` 可退出(长轮询与流)。超时以 code=timeout 到达且不重试——重试三次就是三倍骨架屏时间说同一句话;network_error 仍可重试,人手边始终有 ErrorState 的重试按钮。调用方信号与期限用 AbortSignal.any 合并,取消的查询依然不是失败的查询。
ApiError 尊重错误体里的 retryable 字段,AsyncBoundary 的错误描述可以是错误的函数;五个实验室九处边界全部把失败文案透传。被企业代理永久屏蔽的主机现在一次请求就说清楚,而不是三次静默重试加一句通用话。
一个光秃秃的 500 背后藏着两种不同的失败:被替换的 TLS 证书链,以及网关自己的 HTML 拦截页。上游请求加 15 秒期限、响应体手工解析,失败以六个有名字的代码之一离开,并把拦截页标题引回来。浏览器端错误日志不再是 {}。
五个实验页手抄的 lg:top-4 让面板顶部 212px 躲在应用头与页面带之下,过高的面板永远露不出最后一节。现在偏移与高度上限统一由 --app-header-height 与 --page-band-height 推导,超高的面板在自身内部滚动。
自动消失的倒计时从可选的底边进度条移到 tone 图标外圈并默认显示;图标、操作钮与关闭钮对齐到同一条中线,暗色下表面浮在页面之上,Retry 是本项目的 28px 按钮。与 yBlocks 0.84.1 同步。
自 Base UI 迁移起圆钮被 overflow-hidden 的轨道切成 4px 薄片。裁切已去、Control 加内边距、圆钮回到 16px,每条 slider 的命中区都是 32px。与 yBlocks 0.84.2 同步。
「Frankfurter 能商用吗」这一问,查出三层答案、一个登记簿此前不知道的 v2,以及判词里一个错了 10 倍的数字。
可以商用,分三层:代码 MIT 且可自托管;托管服务直答放开,并把数据许可责任交回使用者;v1 供给的 ECB 数据允许免费再利用、含商业用途,条件是标注来源且不修改统计数据。真正的陷阱不是许可而是用途 —— ECB 明确参考汇率仅供信息参考,不建议用于交易结算,所以展示、开票、报表可以,按它成交不是它的用途。
这一页在公网渲染 ECB 数据,标注来源因此是义务而非礼貌。新增「来源与许可」卡,含 Source: ECB statistics.、用途警告,以及「非 EUR 基准的交叉汇率是厂商换算而非 ECB 原值」——后者关系到「不修改统计数据」这一条。
Frankfurter 另有一套 API 与我们用的 v1 并存:84 家央行、165 种货币、最早 1948 年,响应形状也不同。其中只有 29 家公布了再利用条款,即默认混合汇率里有 55 家条款未知 —— 这是商用场景必须钉住版本号的理由。probe 现在普查两者,v1 哪天不再是 ECB 单一来源、或那个 29 变动,它会先变红。
判词原写「base=JPY 给 USD 0.0064,精度 1.56%」。次日同一调用返回 0.00646 —— 前一天那个值其实是 0.00640,尾零被 JSON 去掉了,于是按位数计数的测量少读一位、把误差高估了十倍。改法:辅助函数明确文档化为上界,判词改为陈述两个方向的比值而不给单点数字,断言也从固定阈值改成比值(阈值那版写下当天成立、次日就红)。绝对量改由极值承担,IDR → GBP 末位值 2.38%、两向相差 569 倍,并加成试验场预设,好让粗糙警示可被亲手点出来。
连线原本比节点图标低 8px:每个节点是「图标 + 标签」的纵向组合,而行内居中把 1px 的线对齐到了整列的中心而非图标的中心。标签改为绝对定位后,节点列的高度就等于图标本身,两者落在同一条中轴上,且与标签行高无关。
登记簿第一次向前登记:此前十一条都是从已经在吃的产品回填的,这三条是因为「值得知道」而先被 probe 的。三条都是机构级来源、无需 key,而三条各自藏着一种不同的静默失真。
最贵的一条是精度:交叉汇率在服务端换算且按绝对值舍入,所以精度取决于问法 —— base=USD 给 JPY 156.25(末位值 0.0064%),base=JPY 给 USD 0.0064(末位值 1.56%),同一货币对差 244 倍。规则是让大单位当 base 再做除法。另有一条:请求非工作日会向后解析并返回 200,只有 date 字段变了。
藏着目前登记簿里最阴的陷阱:fields 投影会静默去重,而 total-count 跟着报去重后的数字 —— rates_of_exchange 只投影 record_date,18,981 行变成 102 行。行不是被截断而是被合并,于是投影上算出的任何平均、求和、计数都是错的。客户端为每次投影自动补上行标识,让塌缩无法表达。另外,缺失值是四字符字符串「null」而不是 JSON null,debt_to_penny 有 35% 的行如此,直接 Number() 会静默得到 NaN。
frames 一次返回 6,136 家公司的同一指标,全市场筛选免费可得。条目存在的理由却是门口那道闸:官方说要「声明 User-Agent」,实际执行的是三层拒绝名单 —— 把仓库地址写进请求头本身就是 403,而 Node 的裸默认值放行。另有列式数组(十六个平行数组,下标 i 才是一条申报)与同一条记录里按类型分裂的缺失值。
每条各得一页,而且都是实验而非数据浏览器:Frankfurter 那页把同一货币对两个方向的精度并排并算出误差带;FiscalData 那页用三个计数展示投影塌缩,并可用 filter 直接筛出带「null」字符串的行;SEC 那页是一台闸门台 —— 逐字符改请求头,预测先出现、状态码后到,九个预设各隔离一层规则。
三条由「已探测」升为「已验证」:分类判据要求「已有页面以其真实数据渲染」,现在为真。probe 覆盖 5 / 14。
壳层没有任何元素声明 container-type,所以页面里的 @md: / @2xl: 无从解析。Wallhaven 试验场的结果网格写着三列四列,实际一直是两列 —— 两列看上去像是故意的,所以一直没被发现。页面布局改用视口断点。
首屏两行大字由「登记簿 / 试验场」改为「Best API Playground」,直接说明这个地方是做什么的;拉丁字体恢复 look 原本的字距。
yApis 有了公网地址。落地页、登记簿与两个试验场此前只存在于仓库里;现在部署在 Vercel,自动随 main 分支更新。
apis.catforest.dev 指向 Vercel 上的生产部署。选 Vercel 而非 Cloudflare Workers,是因为 /api/wallhaven 是请求期路由,而矩阵的 Cloudflare 试点只验证过静态站。规范域名同时成为站点 URL 的代码级默认值:环境变量缺失时,元数据不再静默退回 localhost。
`vercel --prod` 会上传工作目录且不参照 .gitignore,首次生产构建因此载入了本地的 WALLHAVEN_API_KEY——密钥从不回显给浏览器,但 Wallhaven 试验场报出 keyed: true,而这一页存在的意义正是演示匿名路径。补 .vercelignore 后重新部署,线上已回到 keyed: false。
中英 README 删去 9 月 4 日「只有脚手架」的说明,改为列出登记簿、两个 probe、两个试验场与落地页,并以同样直白的措辞写明有意未做的部分。
`/` 不再重定向到 /apis,而是一张简介落地页:说清这个工具是什么、怎样把「用过」变成可复核的记录。工具本身仍住在 /apis。
视觉取自 yLookbook 的 cognitive-topology look:骨白工程排版、氧化红信号、标题背后一枚 Three.js 二十面体。首屏控制台的三个处理格是 probe 契约的三个文件(Schema / Client / Probe),骨白台账就是登记簿本身——十一行全部来自注册表,成熟度条按 status 轴取值,点选一行展开 slug、计费、鉴权、probe 与试验场入口;运行原则一节是这个项目写给整个职业生涯的三条规则。页面上的每一个数字都从注册表派生,不会与 /apis 的 KPI 相左。
全局与壳内 404 页的「返回登记簿」明确指向 /apis;侧栏 logo 仍回到首页,即落地页。
Wallhaven 补齐 probe 与试验场页;更值得一读的是判词的修正——原来那句「匿名只能拿到 SFW」是错的。
`pnpm probe:wallhaven` 以登记簿自身的客户端与 schema 发起真实请求,逐条断言条目的说法:匿名可达哪些纯度、per_page 被接受但忽略(每页恒为 24)、meta.query 在精确 tag 搜索时变为对象、ratio 是字符串,以及接口不返回任何 CORS 头。probe 覆盖达到 2 / 11。
`/apis/wallhaven` 刻意不做成壁纸浏览器,而是一次对照实验:同时发出你选择的 purity 与清除 nsfw 位的对照请求,把两个 total 并排展示。差值为零就是结论本身。因厂商不返回 CORS 头,页面经新增的 /api/wallhaven 代理访问,API key 也因此只存在于服务端。
原判词称匿名请求会被静默过滤成 SFW,这是错的:sketchy 匿名完全可以访问,只有 nsfw 需要 key。证据是总数的精确相加——匿名 purity=110 恰好等于 100 与 010 之和。此前的误判源于匿名 111 首页全是 sfw,而那只是因为 sfw 数量约为 sketchy 的 50 倍且按时间排序。陷阱依然存在但范围更窄:nsfw 位一无所获,且接口对此只字不提。
钳制改为只清除 nsfw 位(原先钉死 SFW 会白白隐藏数百条可正常获取的结果),只请求 nsfw 又无 key 时直接报错而非返回空页。鉴权词表新增「可选 key」并用于 Wallhaven——「匿名可用、key 只是扩大范围」与 Pixabay、Pexels 那种「无 key 一无所获」是两回事,这个区别决定了能否充当兜底数据源。
所有界面文本改为中文:页面标题与元数据、指标标签、工具栏与视图面板、分类词表、卡片与表格、空状态与错误提示、侧栏分区、试验场与更新日志。
yApis 是自用工具,英文界面来自模板而非选择,每次阅读都要多一层转换。现全部改为中文,并按产品文案的书面语体撰写。
登记条目的判词与能力描述保留原文——它们是判断本身,翻译会使来之不易的事实失真;设置面板同样保留,它是各姊妹项目逐字共享的主题面板,词汇沿用 shadcn 原有术语。
顶栏的语言选择器是模板遗留的占位控件,背后没有 i18n 运行时,三个选项中仅一个实际生效。单语言工具无需保留无法生效的控件。
登记簿成为完整的数据视图:布局、排序与筛选可持久保存,每条登记配有状态轨,已探测的 API 可从侧栏直达。
支持网格与列表两种布局,可按登记时间、成熟度或名称排序,按类型与计费筛选,并可隐藏判词或采用方标记。视图设置会被记住,生效中的筛选以可移除的标签展示,列表支持按列排序。
每张卡片顶部以「候选 → 已探测 → 已验证 → 已采用」链路展示 API 的推进阶段,已到达的节点与连接段高亮并带脉冲动效——将登记簿的核心维度直观呈现。
probe 通过的 API 在侧栏独占一行,直接跳转至对应试验场页;侧栏因此成为登记簿的可信目录。
简介固定两行、判词固定四行,网格中各卡片的文本区域在同一基线结束;被截断的判词可通过悬停查看全文。
列表布局的表格此前会撑开整个页面导致横向滚动,现改为在卡片内部滚动。
登记簿不再只是清单:Iconify 获得 typed probe,可复核判词中的断言并冻结响应样本,并配有可实时运行的试验场页。这套契约将适用于后续所有登记。
以登记簿自身的客户端与 schema 发起真实请求,逐项断言判词中可验证的事实——数量参数的 [32, 999] 服务端限制、currentColor 单色 SVG、按图标集返回署名——并冻结一份符合 schema 的 sample.json。KPI 据此显示 1 / 11。
`/apis/iconify` 提供实时调试界面:调整关键词与数量参数,在响应中观察服务端的参数限制行为;结果按图标集分组并附带许可证与作者信息;报文卡片展示完整的请求 URL 与解析后的 JSON。
Wallhaven、Pixabay、Openverse、Pexels 与 Iconify 纳入登记簿,判词来自 yAssets 生产环境客户端的实际经验。登记总数达到 11 条。
外观设置新增开关:关闭后,页面标题栏随内容滚动而非固定,为小屏幕释放纵向空间。顶部导航栏始终保持固定。
v0.1.0 仅是 yTemplate 脚手架的副本。本版本重新同步模板、确立项目定位,并交付首个核心功能——API 登记簿。
`/apis` 收录经手过的每一个外部 API:提供什么、如何计费、矩阵中哪些项目可能用到。首批六条来自矩阵已在依赖的服务。
引入页面类套件、共享设计规范、CI,以及此前缺失的设置与主题系统。未丢失任何项目独有内容:仅存于本仓的文件均为模板已移除的组件。
包名与 README 此前仍沿用 ytemplate。端口调整为 4389,设置的存储键随项目名同步更新——此前在此选择过主题的浏览器将恢复默认。
仓库为 yTemplate 脚手架加项目台账,尚未包含 yApis 专属功能。
Next.js 16(App Router + React Compiler)、TypeScript、Tailwind v4、shadcn/ui、Biome 及标准运行时库,附带仪表盘外壳与演示页面。
`.roadmap/features.yaml` 记录发布模块与应用功能,由 yPulse 中枢定期收集。