一个维护着300条迁移对照表的开发者，最近给自己挖了个新坑：他发现人类读文档的方式，和AI查代码的方式，完全是两码事。
Geoff Rich的「Migrate to Svelte 5」站点原本是个对照手册——React的useState对应Svelte的$state，Vue的watch对应$effect，诸如此类。开发者有困惑时来查，这叫"拉取式"交互。但他和Claude Code协作时反复遇到另一种场景：想让AI主动扫描代码库，找出哪些旧写法该升级。数据全在站点里，却没有机器能消费的格式。
迁移指南回答"怎么写"，但AI需要"去哪找"。
Rich的第一版尝试是/llms-whatsnew.txt，自定义了SEARCH FOR / REPLACE WITH区块。能用，但是个假标准——llms.txt规范只定义了两个文件，自创的.txt格式每次都要跟AI解释。他换了个思路：如果有人在零文档的情况下发现这个接口，能直接用吗？
JSON Feed 1.1成了答案。任何订阅器都能解析，同时结构足够承载代码迁移所需的数据。
34条可搜索的语法指纹
每条模式现在是一个SveltePattern对象，包含since字段标记版本（如svelte@5.29.0）、grep友好的search_signatures数组、以及replacement字段的现代写法。举个具体例子：当Svelte 5推出$state类替代writable() store时，search_signatures里会包含writable(、.set(、.update(等字符串，AI拿到后可以直接在代码库里全局搜索。
Rich把34个Svelte 5以来的新特性全部结构化，分成syntax、architecture、ecosystem、tooling四类。框架迁移者看的是"你的useState是我的$state"；存量代码维护者看的是"这12个文件还在用writable()，这是$state class的替换方案"。
同一个数据源，两种消费姿势。
这个设计有个反直觉的点：对人类来说"有点麻烦"的事，对AI恰好是"短工"。让人去grep十几个文件、比对语法差异、再手写替换，愿意干的人不多。但把结构化feed丢给Claude Code或Cursor，几十秒出结果。
Rich在实现里埋了个细节：每个pattern带release_url指向GitHub发布页，docs数组挂官方文档链接。这不是给AI看的，是给AI的回复里塞给人看的——当AI说"建议替换"时，人能一键溯源。
从"我读文档"到"文档读我"
这个项目的转折点在于意识到：文档站的传统假设是"人有问题来找答案"，但AI代理的工作流是"我主动扫描你的上下文，推送你该知道的事"。迁移指南的300条对照是静态知识，JSON feed是动态探针。
有个具体场景能说明差别。Svelte 5.29.0新增了某个语法糖，人类开发者可能三个月后逛文档站才发现；但配置了feed的AI代理会在版本发布当天标记出代码库里所有可升级点，附带exact code patterns。
Rich没有造新协议，而是复用了已有的JSON Feed标准。这个选择本身是种产品判断：基础设施层的创新成本极高，应用层的创新应该寄生在成熟协议上。
开源社区的反馈闭环
站点现在同时服务两种用户：浏览器里翻对照表的人类，和调用/feed.json的AI代理。Rich在博客里提到，他最初只想解决自己和Claude Code的协作摩擦，但结构化数据一旦公开，用途会超出设计预期。
比如，有人可能拿这个feed做CI/CD钩子：每次Svelte发新版本，自动扫描团队代码库生成迁移报告。或者做IDE插件：实时高亮当前文件里可替换的旧写法。这些都不是Rich自己实现的，但JSON feed让第三方可以零摩擦接入。
34个pattern的版本跨度从Svelte 5.0到最新release，每个都带date_added和since字段。这个数据粒度让消费端可以自行决定策略：激进派跟进每个minor版本，保守派只关注LTS相关的breaking changes。
Rich在文末抛了个问题：当框架文档开始原生支持机器可读格式，开发者的工作流会变成什么样？他现在的站点是个手工维护的过渡方案，但如果Svelte官方直接提供结构化changelog，这种第三方聚合层还有存在价值吗——还是说，价值恰恰在于"跨框架对照"这个官方不会做的视角？
热门跟贴