2025-第四十八周

🐛 错误定义：Node.js 中的错误是 Error 对象的实例，包括内置错误类（如 TypeError）和用户通过扩展 Error 类定义的自定义错误。
🚀 错误传递方式：共有四种主要模式：抛出异常（适用于同步操作）、错误优先回调（用于异步操作）、Promise 拒绝（现代异步操作首选）以及事件发射器（适用于长时间运行且可能产生多个错误或结果的操作）。
🧩 错误类型：分为操作错误（程序运行时预期的外部问题，如网络请求失败）和程序员错误（代码中的逻辑或语法错误，即程序缺陷）。
🛡️ 操作错误处理策略：包括将错误上报给调用栈、重试操作、向客户端报告错误以及在遇到无法恢复的系统错误时终止程序。
🔧 预防程序员错误：可通过采用 TypeScript、定义不良参数的行为以及实施自动化测试来减少此类错误的发生。
⚠️ 未捕获异常：对于未捕获的异常和未处理的 Promise 拒绝，不应尝试恢复应用状态，而应记录错误、尝试优雅关闭，然后退出进程。
📊 集中式错误报告：建议使用错误监控服务（如 Honeybadger）来集中记录、分析和警报生产环境中的错误。
✅ 最佳实践：包括始终使用 Error 对象、区分操作错误与程序员错误、绝不忽略错误、使用 async/await 与 try/catch 处理 Promise，以及实施集中式错误处理。
🎯 核心目标：通过一致使用 Error 对象、妥善处理操作错误、识别并修复程序员错误，并利用专业工具进行监控，来保持代码的可靠性和可预测性。

AI 时代的关键思考——艾迪·奥斯马尼著

原文标题: Critical Thinking during the age of AI - by Addy Osmani

在 AI 时代，人类批判性思维的重要性愈发凸显。本文通过"谁、何事、何地、何时、为何、如何"框架，为技术团队提供系统性思考指南，强调在 AI 辅助开发中保持独立判断和证据导向的决策方式。

👥 明确参与者：识别相关利益方并纳入多元视角，避免群体思维，对 AI 输出保持验证态度
🎯 定义真问题：避免解决表面症状，通过证据收集确认核心问题，像科学家般检验假设
🌍 关注上下文：考虑解决方案的运行环境和使用场景，预判可能产生的连锁影响
⏰ 把握时机：区分紧急修复与深度分析，在时间压力下保持关键决策的严谨性
❓ 追溯根源：运用"五个为什么"方法挖掘根本原因，警惕确认偏误和贸然下结论
🔍 系统化实践：采用科学方法验证证据，用数据支撑沟通，建立持续改进的思考习惯

关键帧令牌：跨项目动画标准化 — Smashing Magazine

本文介绍了通过创建统一的关键帧令牌系统来标准化和管理 CSS 动画的方法，解决项目中动画重复定义和全局作用域冲突的问题。

🎯 问题根源：项目中常存在多个相同动画的关键帧重复定义，导致代码冗余和维护困难
🌍 全局冲突：CSS 关键帧始终处于全局作用域，同名动画会被覆盖，造成不可预测的行为
🛠️ 解决方案：建立统一的关键帧令牌文件，使用 kf-前缀命名空间避免冲突
🎨 动态定制：通过 CSS 自定义属性实现动画参数动态调整，如方向、大小等
🔄 动画组合：支持多个动画组合使用，通过 animation-composition 属性处理相同属性冲突
♿ 无障碍支持：内置减少动画偏好支持，提供即时显示和柔和动画替代方案
📝 最佳实践：逐步采用、统一命名、完善文档、保持灵活性、考虑无障碍性
💡 核心价值：将动画从杂乱无章的技巧转变为可预测的设计系统，提升产品一致性和用户体验

una.im | 样式查询的范围语法

原文标题: una.im | Range Syntax for Style Queries

样式查询新增范围语法功能，允许通过比较运算符实现动态样式匹配。

🌟 样式查询现支持范围匹配（>、<、>=、<=），不再局限于精确值匹配
🚀 适用于@container style() 查询和 CSS if() 函数，增强组件响应能力
🌧️ 通过天气卡片示例展示：当降雨概率>45% 时自动切换背景渐变
🔧 支持 attr() 函数转换数据类型，如将 data-rain-percent 属性转为百分比值
🎛️ 在 if() 函数中实现条件样式：根据数据列数动态切换网格背景色
⚡ 已於 Chrome 142 版本实现，可用于网格布局、动画效果等多样化场景

如何打造一个真正好用的简易搜索引擎

概述了构建一个与现有数据库集成、无需外部服务、易于理解和调试的自定义搜索引擎方案。该方案基于简单的分词、存储和匹配机制，通过多级权重系统实现相关度评分。

🚫 避免外部依赖：不依赖 Elasticsearch 或 Algolia 等外部服务，减少 API 学习和基础设施管理的复杂性
🗄️ 数据库集成：直接利用现有数据库结构，通过index_tokens和index_entries两张表存储分词和索引条目
✂️ 多重分词策略：使用词语分词器（权重 20）、前缀分词器（权重 5）和 N-Grams 分词器（权重 1）处理不同类型匹配
⚖️ 三级权重系统：结合字段权重、分词器权重和文档权重，通过字段权重×分词器权重×ceil(sqrt(词元长度))计算最终权重
🔍 统一分词处理：索引和搜索时使用相同的分词器，确保匹配一致性
📊 智能评分算法：综合考虑基础权重、词元多样性、平均权重质量和文档长度惩罚，通过标准化得出 0-1 的相关度分数
🛠️ 易于扩展：通过实现TokenizerInterface和IndexableDocumentInterface接口，可轻松添加新分词器和文档类型
🚀 高效性能：采用批量插入、参数化查询和数据库索引优化，确保搜索速度快且安全

工具

electron-liquid-glass

这是一个为 Electron 应用程序提供现代化 macOS 玻璃效果（毛玻璃效果）的 Node.js 原生模块。它通过直接集成 macOS 的原生 NSGlassEffectView API 来实现真实的视觉效果，而非 CSS 模拟。该模块支持零配置开箱即用、完全自定义，并自动适配系统深色模式，同时为其他平台提供了安全的无操作回退。

🪄 原生集成 - 直接使用 macOS 的 NSGlassEffectView API，提供真实的玻璃效果，而非 CSS 模拟。
⚙️ 易于使用 - 零配置设计，安装后即可在任何 Electron 应用中使用。
🎨 高度可定制 - 支持自定义边角半径、色调颜色和玻璃效果变体。
📦 现代化包 - 提供 ESM/CommonJS 双模式支持，并包含 TypeScript 声明文件。
🔧 预构建二进制文件 - 在标准环境下无需编译即可使用。
🌙 自动深色模式 - 能够自动响应并适配系统外观（如深色/浅色模式）的变化。
🚀 快速安装 - 支持通过 npm、yarn、pnpm 或 bun 进行安装。
⚠️ 平台限制与要求 - 仅适用于 macOS 26+（Tahoe 或更高版本），需要 Electron 30+ 和 Node.js 22+ 环境。
📚 清晰的 API - 提供 addView 等主要 API 以及详细的配置选项（GlassOptions）。
🔬 实验性功能 - 包含一些使用私有 macOS API 的未文档化实验方法，不建议在生产环境中使用。

aria-hidden

该文章介绍了 aria-hidden 库，其核心功能是通过隐藏其他元素来辅助实现可访问性隔离，特别是在模态框等场景中，并提供了对 HTML inert 属性的支持。

🎯 主要功能：隐藏指定节点之外的所有其他元素，使其对 ARIA 可访问工具不可见。
⚙️ 基础用法：调用 hideOthers(targetNode) 来隐藏其他元素，并可通过返回的函数撤销操作。
🌍 作用范围控制：可传入第二个参数限制隐藏效果的作用范围，默认为整个 document.body。
🔄 Inert 支持：提供 inertOthers 函数，不仅隐藏元素还会禁用交互，并导出 suppressOthers 自动选择最佳方法。
🚫 非 Inert 下的交互抑制：通过第三个参数为隐藏元素添加标记，再利用 CSS 禁用其指针事件。
💡 设计灵感：源于 smooth-ui 的模态对话框，并与 inert 属性、react-focus-lock 和 react-scroll-lock 等相关库有联系。

mitsuhiko/vite-console-forward-plugin：将控制台日志转发至vite日志

一个 Vite 插件，可将浏览器控制台日志转发到 Vite 开发服务器控制台，便于在开发过程中进行调试。

🔧 功能作用 - 拦截浏览器控制台日志（包括 log、warn、error 等）并转发到 Vite 开发服务器
🎯 使用场景 - 适用于浏览器开发工具不易访问的环境、移动设备调试、自动化测试等场景
⚙️ 配置选项 - 支持设置启用状态、API 端点路径和要转发的控制台级别
🔄 工作原理 - 通过客户端代码注入、日志缓冲批处理和服务器端中间件实现
📦 安装方式 - 可直接复制插件文件或作为本地依赖安装
📄 开源许可 - 采用 MIT 许可证，项目已获得 138 个星标和 5 个分支

发布 streamdown@1.6.0 · vercel/streamdown · GitHub

streamdown 项目 1.6.0 版本发布的 GitHub 页面概览，主要展示了该版本的功能更新和修复内容。

🚀 发布了 streamdown 1.6.0 版本，包含 32 次提交和多项改进
🔧 移除了对 react-markdown 的依赖，优化项目结构
📱 新增静态模式实现，扩展使用场景
⚡ 进行了多项性能优化，提升运行效率
🎨 重建语法高亮功能，改善代码显示效果
🔗 移除 urlTransform 相关功能，简化配置
🐛 修复代码块中链接终止问题，提高稳定性
🛡️ 解决安全漏洞，增强安全性
📊 支持 Mermaid 图表的自定义错误组件和导出功能（SVG/PNG 格式）
📝 修复列表 CSS 样式问题
🔍 新增 PanZoom 组件，支持缩放和平移操作测试

TanStack 步调器

TanStack Pacer 是一个框架无关的 JavaScript 工具库，提供高性能的时序控制功能，包括防抖、节流、速率限制、队列管理和批处理等核心功能。

🚀 框架无关且类型安全 - 提供直观灵活的 API，支持所有 JavaScript 框架，具备完整的类型安全
⚡ 性能优化工具 - 包含防抖、节流、速率限制、队列管理和批处理等核心功能，减少不必要的操作和资源消耗
🔄 异步同步双模式 - 支持异步或同步执行，内置错误处理、重试机制和中断控制器
📦 功能丰富模块化 - 轻量级、支持 Tree-Shaking，提供队列优先级、暂停/恢复、并发控制等高级功能
🤝 开放合作生态 - 正在寻求合作伙伴共同发展，拥有活跃的 GitHub 社区和持续更新

sindresorhus/open：跨平台打开工具，可打开URL、文件、可执行程序等。

这是一个名为"open"的开源跨平台工具库，用于在命令行工具和脚本中打开 URL、文件和可执行程序。

🌐 跨平台支持，在 macOS 使用 open 命令，Windows 使用 start 命令，Linux 使用 xdg-open
📦 通过 npm 安装，仅支持 ESM 模块，不再提供 CommonJS 导出
🔧 支持打开特定应用程序并传递参数，可等待应用程序退出
🛡️ 使用 spawn 而非 exec，安全性更高
🐧 包含最新的 xdg-open 脚本，支持 WSL 路径
📱 提供预定义的常用应用程序名称，如 Chrome、Firefox 等
⚠️ 不提供安全保证，需要用户自行处理不可信输入

fontaine

Fontaine 是一个通过自动生成本地字体回退和优化的字体度量来减少布局偏移（CLS）的工具，它能够提升网站性能且无需运行时开销。

💪 减少布局偏移：通过使用本地字体回退和精心计算的字体度量来降低累积布局偏移（CLS）。
✨ 自动生成字体度量：自动生成字体度量并覆盖原有设置，优化字体显示效果。
⚡️ 纯 CSS 实现：零运行时开销，完全通过 CSS 实现功能。
📈 性能提升显著：在示例中，启用后 CLS 从 0.24 降至 0.054，性能得分从 92 提升至 100。
🔧 多框架支持：支持 Vite、Next.js、Astro、Docusaurus 和 Gatsby 等多种前端框架。
🛠️ 灵活配置回退策略：支持基于数组、字体系列或字体类别的回退字体配置，优先级明确。
🎯 处理 CSS 变量字体：针对使用 CSS 变量引用自定义字体的场景，提供了特定的调整方案。
🔍 工作原理：扫描 @font-face 规则，生成带有正确度量的回退规则，并自动添加到字体家族中。

更新

Ant Design 6.0 正式发布，这是经过广泛 RFC 讨论和多次 Alpha 版本迭代后的稳定版本。本次升级聚焦深度技术优化，提升对 React 19 及未来版本的兼容性和性能，并完善组件语义化结构和 CSS 变量支持。与 v5 相比，v6 支持平滑迁移，现有 v5 项目可直接升级无需兼容包。v5 分支将进入 1 年维护期。技术升级包括最低 React 版本要求提升至 18、启用 React Compiler、采用纯 CSS 变量样式架构、停止 IE 支持、实现全组件语义化结构。新增 Masonry 组件、Tooltip 平移滑动、InputNumber spinner 模式、Drawer 缩放等功能。未来将优化移动端交互、增强无障碍支持并跟进 React 新特性。

⚛️ 最低 React 版本要求提升至 18，移除旧版兼容逻辑
📦 打包输出中启用 React Compiler 提升性能
🌈 采用纯 CSS 变量样式架构，支持实时主题切换
🚫 完全停止 IE 浏览器支持
🧩 全组件实现语义化 DOM 结构，支持 RTL 布局
🔥 新增 Masonry 瀑布流组件和 Tooltip 平移滑动功能
🆕 InputNumber 支持 spinner 模式，Drawer 支持缩放
🎨 遮罩层默认启用毛玻璃模糊效果
📚 移除 v4 遗留废弃 API，保持 v5 完全兼容
🚀 同步发布 Ant Design X 2.0 面向 AI 场景组件库

Prettier 3.7：提升格式化一致性与新增插件功能！· Prettier

Prettier 3.7 版本发布，主要优化了 TypeScript 和 Flow 的格式化一致性，修复了多项错误，并新增了对 Angular 21 和 GraphQL 16.12 的支持，同时为插件开发者提供了更多 API 控制权。

🎯 统一类和接口的格式化规则，提升 TypeScript 和 Flow 代码的一致性
🐛 修复了 JavaScript 中注释处理、导入属性换行及逻辑表达式打印等多个错误
🔧 新增对 Angular 21 新赋值运算符和正则表达式的支持，以及 GraphQL 可执行描述功能
📦 为插件开发者新增评论附加和忽略节点处理的 API，增强自定义能力
🛠️ 改进了 CSS、SCSS、HTML 等语言的格式化细节，如选择器大小写和事件处理程序
📝 优化了 Markdown 表格对齐和 Front Matter 解析，支持 TOML 格式
⚡ 提升了 CLI 性能，避免在不启用缓存时创建不必要的目录

Immer 11.0.0

本次 Immer 11.0.0 版本的核心是重构了最终化系统，采用回调机制替代了原有的递归树遍历，从而显著提升了性能。此变更是破坏性的，并默认启用了宽松迭代模式。

🔄 重写最终化系统：采用回调方法替代递归树遍历，提升了性能。
💥 默认启用宽松迭代：这是一个破坏性变更，可能会影响现有代码。
⚡ 简化迭代检查：优化了部分迭代检查逻辑。
🚀 性能优化措施：允许在 get/set 工具中传递类型以跳过原型查找，并将 assigned_ 转换为 Map 结构。
🧪 引入最终化回调：移植了 Mutative 库的“最终化回调”方法，为每个创建的草稿添加清理回调，并处理根草稿、赋值及普通值内的递归。
🔧 更新状态创建：状态创建现在返回 [draft, state] 以避免查找，并重写了补丁生成系统以兼容回调机制。
🛠️ 代码优化与重构：更新了自引用测试、应用了代码审查建议、精简了代码（如缩短作用域、字段名和内联函数）。

AI

译：LLM API 其实是个同步问题

本文探讨了当前大语言模型（LLM）API 设计的核心问题，指出其基于消息的抽象方式可能并非底层模型运行机制的正确反映。作者认为，LLM 交互本质上是分布式状态同步问题，而现有 API（如 Completion API 和 Responses API）在隐藏状态管理、缓存复用和同步边界方面存在缺陷。文章建议借鉴本地优先（Local-First）架构中的状态同步思想，重新设计更贴近模型工作原理的 API 标准。

🤖 LLM 核心机制是状态同步问题：模型通过 token 序列处理文本，内部依赖注意力键值缓存（KV Cache）维护派生状态，而当前 API 未能有效抽象这一过程。
🧩 隐藏状态导致同步复杂性：服务商注入的 prompt 模板、工具定义等隐藏上下文无法通过消息接口统一管理，不同提供商以不兼容方式处理这些状态。
📉 Completion API 效率低下：需全量重传对话历史，导致请求数据量二次增长，且服务器计算成本随序列长度呈二次方增加。
🔄 Responses API 的同步局限：虽尝试维护服务器状态，但同步能力有限，易因网络分区或状态分歧导致对话卡死，且缺乏重放机制。
🌐 分布式架构的启发：本地优先运动中的无冲突复制、增量同步和状态检查点等设计，可应用于 LLM 的 KV 缓存与 prompt 日志管理。
⚠️ 当前抽象的风险：若仓促标准化基于消息的 API，可能固化其弱点，未来需优先考虑隐藏状态、同步语义与容错机制的设计。

译：Agent 设计依然很难

本文作者 Armin Ronacher 分享了在构建 AI Agent 过程中的实践经验与挑战。内容涵盖 Agent SDK 的选择、缓存管理、强化机制、失败隔离、状态共享、输出工具设计、模型选型以及测试评估等关键问题，并指出了当前 Agent 开发中的混乱现状与未解难题。

🛠️ 慎用高级 Agent SDK：不同模型差异显著，高层抽象（如 Vercel AI SDK）难以满足灵活需求，推荐直接使用平台原生 SDK 以保持完全控制。
💾 显式缓存管理更优：Anthropic 的显式缓存机制虽需手动管理，但提供了成本可控、上下文分叉和编辑等优势，优于自动缓存。
🔁 强化机制至关重要：在 Agent 循环中注入目标提醒、状态更新或失败提示等强化信息，能显著提升任务完成效果。
🚧 严格隔离失败：通过子代理单独处理易失败任务，或利用上下文编辑隐藏无关失败，避免污染主循环上下文。
📁 虚拟文件系统共享状态：使用类文件系统的共享层（如虚拟文件系统）是实现代码执行与推理工具间数据传递的关键构件。
📤 输出工具设计棘手：专设 Output Tool 用于最终信息传递，但存在调用不稳定、语气控制难等问题，需通过强化消息等方式引导调用。
🤖 模型选择因任务而异：Anthropic 的 Haiku/Sonnet 仍是主循环中优秀的工具调用模型；Gemini 2.5 擅长处理长文档和图像；GPT 系列在作者用例中表现不佳。
🧪 测试评估仍是难题：Agent 的复杂性使得传统评估方法失效，目前缺乏令人满意的测试方案，成为开发过程中的主要痛点。
🔄 编码 Agent 新动向：作者试用 Amp，欣赏其子代理（如 Oracle）与主循环的优雅交互设计，认为其体现了团队对 Agent 的深入思考。
💡 零散洞见：包括对 MCP 过度设计的质疑、小型开源库面临 AI 生成代码的冲击、Tmux 作为与系统交互的优秀技能，以及 LLM API 本质是同步问题等。

我们教会了 AI 编写真实的 PostgreSQL 代码（并开源发布）

本文介绍了 pg-aiguide 这一工具，旨在解决 AI 编码助手生成的 PostgreSQL 代码质量不佳的问题。由于 AI 模型从互联网上混杂的 SQL 示例中学习，其输出的代码虽能运行，但存在数据类型、索引、时区处理等潜在问题，导致长期维护困难。pg-aiguide 通过提供“技能”指导、版本感知的语义搜索和扩展生态文档，帮助 AI 生成符合 PostgreSQL 最佳实践的生产级代码，从而避免常见陷阱，提升开发效率。

🐛 AI 生成的 SQL 代码存在隐患：虽然能运行并通过测试，但隐藏了数据类型混淆、索引错误、时区处理不当等问题，导致后续调试和迁移成本增加。
🌐 问题根源在于训练数据混杂：AI 从多种数据库（如 MySQL、Oracle）和过时教程中学习，导致无法掌握 PostgreSQL 的精准最佳实践。
🛠️ pg-aiguide 的解决方案：通过“技能”库、版本感知的语义搜索和扩展文档，为 AI 提供 PostgreSQL 专属指导，确保生成高质量代码。
📚 技能库的核心作用：提供紧凑、针对性的最佳实践（如使用 BIGINT GENERATED ALWAYS AS IDENTITY 替代 SERIAL），帮助 AI 自动应用正确设计。
⏱️ 版本感知检索的重要性：根据 PostgreSQL 版本（15-18）动态匹配官方文档，避免 AI 幻觉过时或错误语法。
🚀 开源与社区共建：工具完全开源，鼓励社区贡献技能、文档和优化建议，共同提升 AI 的 PostgreSQL 代码质量。
📈 实际效果验证：启用 pg-aiguide 后，AI 生成的表结构更规范（如统一身份列策略、正确处理时区），减少了长期性能隐患。

用 AI 写什么，不写什么

本文作者作为一名文字与代码工作者，探讨了在方案写作、编程和博文撰写中如何有效利用 AI 工具。作者认为，AI 在方案型写作和编程中可以极大提升效率，但在表达型写作（如博文）中应谨慎使用，以保留个人思考与独特性。文章通过分类文本工作，阐述了 AI 在不同场景下的边界与价值，并分享了使用 Notion AI 和编程 AI 的具体工作流程。

💡 方案型写作以逻辑完备为目标：AI 可生成 80% 的内容，但关键的 20%（如问题定义、决策判断）仍需人类基于碎片化上下文完成。
🧠 创造性决策依赖人类思维：AI 能列举选项和优化已知内容，但无法替代从问题到解决方案的创造性跳跃。
🗂️ Notion AI 提升方案写作效率：通过引用积累的上下文（模板、笔记等），快速将模糊想法转化为结构化的初稿。
🔍 AI 作为审稿助手减少错误：逐章节检查逻辑谬误和盲区，充当严苛的审稿人，提升内容质量。
🛠️ AI 简化格式调整体力活：通过口述指令批量修改格式，甚至将混乱文本转化为结构化数据库。
🔄 写作积累形成复利闭环：已完成方案沉淀为高质量上下文，加速后续写作，实现持续优化。
🤖 AI 编程实现从零到一的跨越：帮助非技术人员构建自定义网站、Docker 服务等，但需遵循产品经理式工作流（先文档后执行）。
✍️ 博文写作拒绝 AI 代笔：表达型写作重在锤炼个人思考，避免算法标准化，保留独特性和自我对话价值。
🚗 AI 如同辅助驾驶工具：在标准化场景（如高速路段）提升效率，但人类仍需掌控核心，平衡使用与自主性。

其他

编程是我遇到过的最能抑制傲慢的良药。如果一个人很傲慢，你就让他去编程。

-- tratt.net