TanStack Intent：让 npm 包把”会用它的知识”随版本一起发给 Agent

当 AI Agent 帮你写代码时，最常见的翻车原因之一是用过时的 API：模型脑子里记的还是上一个大版本的用法，而你 node_modules 里装的是新版。TanStack 新推出的 Intent（目前标注 alpha）要解决的就是这件事——它给维护者一条”从源码文档到 Agent Skill”的版本化通道，让依赖包把”该怎么用它”的知识随包一起发到消费方机器上。官方口号是：Your dependency can ship the knowledge required to use it（你的依赖可以把使用它所需的知识一并发货）。

一、背景：Agent 知识从哪来

现在的普遍做法是让 Agent 去读外部文档站点或做 RAG 检索，问题是文档版本和你实际安装的包版本对不上。TanStack 的思路很直接：既然 npm 包本身就带版本号，那就让Skill 和代码用同一个版本发布——包升级了，配套的使用指南也精确地升级到同一版本。

以 TanStack 自家生态为例：@tanstack/react-router 包里附带 skills/tanstack-router/SKILL.md，标注它”用于建模类型化的搜索参数与路由 loader”，并声明来源是 docs/framework/react/guide/search-params.md；@tanstack/react-query、@tanstack/react-table 同理。消费方的工具扫描 workspace 里已安装的依赖与 lockfile，就能发现这些静态文件。

二、消费侧：静态扫描，但信任仍然显式

Intent 最值得说的是它对”从第三方包里读文件”这件事的安全设计。官方把发现流程拆成四步：

1. Scan（扫描）：读取包元数据与静态 skill 文件——不执行任何包代码；
2. Allow（放行）：按包名对照 allowlist 与排除清单，决定哪些包允许贡献指南；
3. Inspect（检视）：保留来源引用与 skill 内容的可见性，让你能审查；
4. Load（加载）：只在当前任务确实需要时，才把相关指南喂给 Agent。

官方同时明确一句关键口径：“Editor and install hooks may streamline discovery. They are not a security boundary.”（编辑器与安装钩子可以简化发现流程，但它们不是安全边界。）也就是说，Intent 靠”只读静态文件、不跑包代码”把供应链风险压到很低，但最终是否采纳某个包提供的指导，仍然是你（allowlist）和 Agent（按需加载）的显式决定，而不是包作者说了算。

三、维护者闭环：代码、文档、Skill 一次发布

维护者侧的流程是：在包附近编写（或生成）SKILL.md 并声明它依赖哪些源文档 → CI 里校验结构与来源引用 → 把文件一起打进 npm 发布产物。这样 npm 版本号就是 Skill 版本号，公网注册表索引后，历史版本的技能都可回溯。

配套的 intent stale 命令解决”文档漂移”：当被引用的源文档（如 search-params.md、query-keys.md）发生变动时，它会把对应 Skill 标记为需要复查。但官方对这个命令的定位极其克制——“A changed source is a review signal, not proof of bad guidance”（源变了只是一个复查信号，并不等于指南一定错了）。Intent 不假装自己能判断语义建议是否过时，拍板的永远是维护者。

四、关键事实与口径

页面展示的体量数字（1.5M 总下载、约 19.9 万周下载、332 stars）是 TanStack 生态包本身的热度，不是 Intent 这个新工具的采用量，引用时不应混淆。

五、评测方法批判与局限

1. Alpha 阶段，机制未定型：它是”built in public”的早期项目，CLI、发现协议、编辑器集成都还在演进，现在把它写进团队流程要承担 API 变动成本。
2. 完全依赖维护者持续投入：Skill 不会自己变对。如果库作者懒得同步，包虽然发了、Skill 却是过期的——intent stale 只能提醒，不能替你改。
3. 提示词注入的新入口：SKILL.md 本质是会被喂给 Agent 的提示词。官方用”静态扫描 + allowlist + 不跑代码”来降风险，但一个恶意或被攻陷的包完全可以在 SKILL.md 里写诱导性指令。这正是官方强调”不是安全边界”的原因——它没有、也不可能替代你对依赖的审查。
4. 没有客观效果基准：官方没有给出”用了 Intent 后 Agent 调用正确 API 的成功率提升 X%“这类数据；它的收益（版本对齐）是机制上成立，实际效果需自测。

六、优势与适用人群

优势：

• 版本对齐：Skill 与代码同版本发布，从根上缓解”Agent 用过时 API”；
• 供应链克制：只读静态文件、不执行包代码，配合 allowlist 风险可控；
• 复用 npm 既有分发与版本历史：不需要另建一套文档分发系统。

适合谁：

• 维护被广泛引用的 TS 库的作者：把使用指南随包发出去，是降低用户与 Agent 困惑的低成本手段；
• 重度依赖 AI Agent 写代码的团队：可以给内部/常用依赖补齐 SKILL.md，让 Agent 更稳地用对 API。

但如果你只是偶尔写几行脚本，这套机制暂时感受不到收益；而对供应链安全要求极高的场景，仍要把第三方包的 SKILL.md 当作”不可信提示词”来审查。

参考来源

• TanStack Intent 官方站点
• Koala 项目库条目