Published on

2025-第二十九周

Authors

该周报主要为各个地方内容的汇总整理

技术

在 Next.js 中添加.md URL 以获取原始 Markdown 内容

本文介绍了如何在 Next.js 博客中通过添加.md后缀来获取原始 Markdown 内容，并详细说明了使用 Next.js 重写功能实现这一特性的步骤。

  • 🚀 更新建议：Vercel CEO 建议使用 Next.js 重写功能替代中间件，提升性能并简化实现。
  • 📝 功能目标：在博客文章 URL 后添加.md（如/posts/my-post.md）以获取原始 Markdown 内容，便于代码分享或内容分析。
  • 🔧 技术实现：
    • 使用Next.js rewrites配置 URL 重定向，将/posts/:slug.md映射到 API 路由/api/posts/:slug/raw。
    • 通过Content Collections库管理内容，支持类型安全和高效开发体验。
  • ⚙️ 配置步骤：
    • 初始化 Next.js 项目并安装依赖（如@content-collections/core）。
    • 配置content-collections.ts定义文章集合结构和转换逻辑。
    • 更新next.config.js添加重写规则和静态生成参数。
  • 📂 内容示例：创建content/hello-world.mdx文件，包含元数据和 Markdown 内容。
  • 📄 页面渲染：
    • 首页（app/page.tsx）按日期排序展示文章列表，并提供原始 Markdown 链接。
    • 文章页（app/posts/[slug]/page.tsx）渲染 MDX 内容并显示原始 Markdown 选项。
  • 🔄 API 路由：app/api/posts/[slug]/raw/route.ts返回原始 Markdown 内容，设置缓存头优化性能。
  • ✅ 测试验证：启动开发服务器后，可通过/posts/hello-world（渲染页）和/posts/hello-world.md（原始内容）访问。
  • 💡 应用场景：适合分享代码示例、调试内容或学习 Markdown 语法，且实现简洁高效。

更好的 Promise.all() —— 实用工具类型与函数

本文介绍了在 TypeScript 中处理嵌套 Promise 的实用工具类型和运行时函数，旨在提升代码的易用性和类型安全性。通过四种核心工具类型（ShallowPromisify、ShallowSettled、DeepAwaited、DeepSettled）和两种运行时函数（deepRecordAll、deepRecordAllSettled），开发者可以更高效地处理浅层/深层的 Promise 结构，同时保持类型推断和错误隔离。

  • 🎯 问题背景

    • 处理嵌套 Promise 时，传统方法需手动映射类型，代码冗长且易出错。

  • 🛠️ 解决方案：工具类型

    • ShallowPromisify：浅层包装值为 Promise，保留原始结构。
    • ShallowSettled：类似浅层包装，但使用PromiseSettledResult处理成功/失败状态。
    • DeepAwaited：递归解析所有嵌套 Promise，返回最终结构类型。
    • DeepSettled：仅对 Promise 值应用PromiseSettledResult，保留非 Promise 值。

  • ⚙️ 运行时函数

    • deepRecordAll：递归解析对象/数组中的所有 Promise，返回完全解析的结构。
    • deepRecordAllSettled：类似但使用Promise.allSettled，支持部分失败场景。

  • 📌 实际用例

    • API 响应处理：自动解析嵌套的异步数据（如用户资料 + 帖子）。
    • 批量操作：通过deepRecordAllSettled实现错误隔离，记录成功/失败结果。
    • 配置加载：合并多个异步配置源并验证。

  • 🛡️ 类型安全优势

    • 编译时验证、完整的 IDE 智能提示、重构安全性提升。

  • ⚡ 性能考量

    • 深层处理可能影响性能，需权衡使用场景。

  • ✨ 核心价值

    • 提供类型安全、错误恢复、灵活性和可维护性，适用于复杂异步数据流。

工具

spectrum-ui

Spectrum UI ⭐ 是一套基于 Aceternity UI Magic UI 与 ShadCN UI 构建的可复用组件库，您可以直接复制粘贴到自己的应用中。

jaaz

AI 设计助手，Lovart 的本地替代方案。具备设计、编辑及生成图像、海报、故事板等功能的智能代理。

mcp-for-next.js

这是一个基于 Next.js 的 MCP 服务器示例项目，使用 Vercel 的 MCP 适配器，允许在 Next.js 项目中快速集成 MCP 服务器功能。项目包含配置说明、部署要求及示例客户端脚本。

  • 🚀 项目用途 - 示例 Next.js MCP 服务器，集成 Vercel 的 MCP 适配器，支持在指定路由部署 MCP 服务。
  • 📂 文件结构 - 包含应用路由、公共资源、脚本及配置文件（如next.config.ts、package.json等）。
  • 🔧 配置要求 - 使用 SSE 传输时需要 Redis（通过process.env.REDIS_URL配置），并需启用 Fluid 计算优化性能。
  • ⏱️ 性能调整 - 建议在 Vercel Pro 或企业账户中调整maxDuration至 800 秒以适配长时运行。
  • 🚀 部署说明 - 提供直接部署 Next.js MCP 模板的指引。
  • 💻 示例客户端 - 包含测试脚本scripts/test-client.mjs，用于调用 MCP 服务端点。

opencode

OpenCode 是一个基于 Go 开发的终端 AI 助手，专为开发者设计，提供智能编码辅助功能。该项目现更名为 Charm，由原开发者 Kujtim Hoxha 继续维护，目前处于早期开发阶段，功能可能不稳定。支持多模型交互、会话管理、代码工具集成等，适合在终端环境中高效完成开发任务。

app-that-builds-apps

一款能够构建真正原生应用和网站的应用及网站平台。基于 Expo Router 与 AI SDK 打造

更新

ReactRouter-Middleware

React Router 的中间件功能目前处于实验阶段，允许在路由处理器执行前后运行代码，支持认证、日志等常见模式，并通过嵌套链式结构执行。

  • 🚧 实验性功能：需通过 future.unstable_middleware 标志启用，可能包含破坏性变更。
  • 🔄 执行顺序：中间件按父路由→子路由顺序执行（“向下”），再反向返回（“向上”）。
  • ⚙️ 快速启用：在 React Router 配置中设置 unstable_middleware: true，并更新全局类型声明。
  • 🔐 认证示例：中间件可验证用户会话，未通过时重定向到登录页。
  • ⏱️ 性能监控：客户端中间件可测量导航耗时并记录日志。
  • 🛡️ 错误处理：捕获并记录错误后重新抛出，由 React Router 处理。
  • 🔗 上下文共享：通过 unstable_createContext 实现类型安全的上下文传递，避免命名冲突。
  • 📡 服务端 vs 客户端：服务端中间件处理文档请求，客户端中间件处理浏览器内导航。
  • 🔄 条件执行：支持基于请求方法（如仅 POST 请求）运行特定中间件逻辑。
  • 🛠️ 迁移指南：从旧版 AppLoadContext 迁移时，需将上下文对象包裹到 Map 中并通过 get 方法访问。

动画合成 - CSS | MDN

CSS 的animation-composition属性用于指定当多个动画同时影响同一属性时的复合操作方式。

  • 🆕 该功能自 2023 年 7 月起在最新设备和浏览器版本中可用，旧版本可能不支持。
  • 🎨 属性语法支持三种复合操作：replace（覆盖默认值）、add（叠加效果）、accumulate（累积值）。
  • 🔄 多动画场景下，属性值按animation-name顺序循环分配。
  • 📊 示例展示了不同值对transform属性的影响：replace会替换基础值，add会叠加变换，accumulate会合并数值。
  • 📚 适用于所有元素，不可继承，默认值为replace。
  • 🌐 兼容性需查看最新浏览器支持情况，相关资源包括 CSS 动画教程和其他动画属性。

AI

a2a-js

Agent2Agent (A2A) 协议官方 JavaScript SDK

译：长上下文为何会失效

本文探讨了大型语言模型中长上下文窗口（context window）带来的潜在问题，分析了四种常见的“上下文失效”模式（投毒、干扰、混淆、冲突），并指出这些失效对智能代理（agent）的负面影响。文章强调，单纯扩展上下文长度并不能提升模型表现，反而可能引发新的失效场景，最后预告了后续解决方案。

  • 🧪 上下文投毒 - 幻觉或错误信息进入上下文后会被反复引用，导致代理执着于错误目标（如 Gemini 玩《宝可梦》时因幻觉制定荒谬策略）。
  • 🎯 上下文干扰 - 上下文过长时，模型过度依赖历史记录而忽略训练知识（如 Gemini 2.5 在超 10 万 token 后重复旧动作而非制定新计划）。
  • 🤯 上下文混淆 - 无关内容污染响应质量（如伯克利实验显示模型调用无关工具，小模型在 46 个工具下完全失效）。
  • ⚔️ 上下文冲突 - 新增信息与原有上下文矛盾（微软实验证明分阶段输入信息会导致模型得分暴跌 39%）。
  • ⚠️ 代理的高风险性 - 代理因多源信息整合、连续工具调用等场景更易遭遇上下文失效。
  • 🔮 解决方案预告 - 动态加载工具、建立上下文隔离区等方法将后续探讨。

译：我是如何使用 LLM 辅助我写代码的

本文作者 Simon Willison 分享了他使用大语言模型（LLM）辅助编程的实践经验，强调了合理预期、上下文管理、测试代码等关键技巧，并通过实际案例展示了如何高效利用 LLM 提升开发速度和学习效率。

  • 🎯 设定合理预期：LLM 本质是高级自动补全工具，需结合开发者技能使用，而非完全依赖。
  • 📅 考虑训练数据截止日期：模型对库的熟悉度受限于训练数据时间，选择稳定且流行的库效果更好。
  • 🗂️ 上下文为王：LLM 的表现高度依赖对话上下文，可通过导入代码或文档优化结果。
  • ❓ 询问选项：在项目初期用 LLM 调研技术方案，快速验证可行性。
  • ✍️ 明确指令：像对待“数字实习生”一样，用详细需求描述生成代码（如函数签名 + 英文说明）。
  • 🧪 必须测试代码：LLM 生成的代码需人工验证，这是开发者不可推卸的责任。
  • 💬 对话式迭代：通过多次反馈修正结果（如“重构这段代码”“按时间排序”）。
  • ⚙️ 使用代码运行工具：如 ChatGPT Code Interpreter 或 Claude Artifacts，在沙箱中实时验证代码。
  • 🎨 Vibe-coding 学习法：通过“凭感觉”快速实验探索模型能力边界。
  • 🚀 开发速度优势：LLM 能实现原本因时间成本被放弃的项目，如半小时内完成版本说明页。
  • 🔍 放大专业知识：LLM 效果与使用者的经验正相关，擅长回答代码库问题（如架构解析）。
  • ⚠️ 随时接管：遇到复杂问题（如 GitHub Actions 配置）时需人工干预。

译：Claude Code 中级指南

本文是一篇关于如何高效使用 Claude Code 的中级用户指南，作者 Gatsby 基于自身学习经验，总结了安装配置、精度优化、工作流技巧等实用方法，帮助用户快速提升 Claude Code 的使用效率。

  • 🚀 安装与初始化

    • 通过 npm 安装 Claude Code，启动会话后优先用 summarize this project 让 Claude 理解项目上下文。
    • 使用 /init 创建 CLAUDE.md 文件存储项目摘要，确保跨会话记忆。

  • 📝 持久化上下文

    • 通过示例提示（如项目功能、技术栈、目录结构等）填充 CLAUDE.md，避免每次会话重置上下文。

  • ⚠️ 避免大段输入

    • 将长文本指令写入文件后让 Claude 读取，而非直接粘贴到提示框，以提高回答质量。

  • 💡 深度思考模式

    • 使用 ultrathink 等关键词提升 Claude 的思考深度（消耗更多 token），适合复杂问题。

  • 🔍 分阶段工作流

    • 按 探索→规划→编码→提交（Explore, Plan, Code, Commit）顺序下达指令，减少偏差。

  • ✅ 测试驱动开发（TDD）

    • 先让 Claude 编写测试代码，再实现功能，最后通过测试，确保代码可靠性。

  • ♻️ 会话管理

    • 使用 /clear 重置混乱的会话，或通过 claude --resume 恢复历史会话。

  • 🔔 任务通知设置

    • 配置任务完成提醒（如终端铃声），避免长时间等待无反馈。

  • 📊 用量监控

    • 运行 npx ccusage 查看每日 token 消耗和费用估算，优化使用效率。

译：我如何 Vibe Coding

本文作者 Xuanwo 分享了他作为开源 Rust 工程师如何将 AI 工具（如 Claude Code）融入日常工作流的经验。他强调了 AI 在代码重构、工具使用和任务规划中的优势，但也指出其局限性，需结合人工审查和明确指导。文章还提供了具体工具配置、工作流设计及实用建议，适合希望高效利用 AI 辅助编程的开发者参考。

  • 🧑💻 作者背景

    • 开源 Rust 工程师，工作环境开放，允许 LLM 直接访问代码上下文。
    • Rust 语言特性（如优秀工具链和文本化代码）与 AI 协作高度适配。

  • 🛠️ 工具集

    • 主要使用 Zed 编辑器 和 Claude Code（通过自定义 Docker 容器运行）。
    • 配置别名 claudex 快速启动 Claude，并挂载代码、配置和笔记目录。

  • 🤖 AI 使用理念

    • 将 LLM 视为初级开发者：擅长结构化任务，但需人工提供上下文、方向和审查。
    • 仅让 AI 编写可掌控的代码（如重构已有模块），避免完全依赖其设计新组件。

  • ⏳ 工作流设计

    • 每日分为 5 小时区块（匹配 Claude 使用限制）：上午规划（用 Obsidian 记录笔记），下午编码与审查。
    • 通过 git worktree 启动多实例协作，依赖 Rust 工具链（cargo check/test）自动化验证代码。

  • 🚨 关键注意事项

    • 警惕 AI 过度自信（如虚构 API），需人工把控公共 API 和复杂逻辑。
    • 反对盲目配置 MCP 服务器，优先利用本地工具链（如 gh CLI）。

  • 💡 实用建议

    • Claude 4 是目前最适合编程的模型（强于规划和工具使用）。
    • 将 AI 融入现有工作流，而非颠覆习惯（如不强制切换 IDE）。

context-engineering-intro

介绍了**上下文工程（Context Engineering）**的模板和使用指南，这是一种为 AI 编程助手提供全面上下文信息的系统化方法，比传统提示工程（Prompt Engineering）和随意编码（Vibe Coding）更高效。文章详细说明了模板结构、操作步骤、最佳实践，并强调了通过示例和文档提升 AI 实现复杂功能的能力。

  • 🚀 快速开始
    • 克隆模板仓库，设置项目规则，添加代码示例，创建初始需求文件（INITIAL.md），生成并执行产品需求提示（PRP）。
  • 📖 什么是上下文工程？
    • 从传统提示工程的“便签式”指令升级为包含文档、示例、规则和验证的完整系统，减少 AI 错误并确保一致性。
  • 🏗️ 模板结构
    • 包含全局规则文件（CLAUDE.md）、示例目录、PRP 生成与执行命令，以及需求描述模板（INITIAL.md）。
  • 🔧 分步指南
    1. 设置全局规则（项目规范、测试要求等）；
    2. 编写详细需求文件；
    3. 生成 PRP（含实现步骤和验证）；
    4. 执行 PRP 自动实现功能。
  • ✍️ 编写有效需求文件
    • 需明确功能描述、示例引用、相关文档链接及其他注意事项（如性能要求、常见陷阱）。
  • 🔄 PRP 工作流程
    • 生成阶段：分析代码库、收集文档、创建详细蓝图；
    • 执行阶段：按计划实现、验证测试、迭代修复。
  • 📂 示例的运用
    • 在examples/目录中提供代码结构、测试模式、集成方案等示例，显著提升 AI 实现质量。
  • ✅ 最佳实践
    • 明确需求、丰富示例、添加验证关卡、定制项目规则（CLAUDE.md），并充分利用文档资源。

其他

AI 就是一种新型的操作系统，帮你完成各种任务。这个系统的 CPU 就是大模型，内存就是模型的上下文窗口，窗口越大能完成的任务规模就越大。

-- Andrej Karpathy，著名 AI 科学家

Discuss on Twitter • View on GitHub