官方知识库对上大模型记忆：谁更懂框架的最新写法

大模型写 Expo 代码时，最典型的失败往往出在版本上：API 明明存在，但它是上一个 SDK 的写法；命令明明合法，但参数已经改名；方案明明可行，但官方在最近三个版本里换了实现路径。这类错误很难靠看代码本身发现，因为生成的代码语法完整、类型也通，只是在你的 SDK 版本上无法运行。

Expo 官方给出的答案是一套结构化技能库：expo/skills。当前 plugins/expo/plugin.json 里版本号是 1.14.2，包含 23 个技能（16 个开源框架技能 + 7 个 EAS 服务技能），另有一个独立分发的实验插件 expo-experiments。它想做的事很明确：把"模型记忆里的 Expo"换成"仓库里可核对、可执行的 Expo"。

这篇文章用仓库源码回答三个问题：知识滞后的时间差到底出在哪、这套知识库靠什么机制补偿、以及它在哪些地方自己也会失效。

三条时间线，决定了 AI 为什么会写错

把"AI 写错框架代码"拆开看，其实是三条不同步的时间线在打架。

第一条：模型的训练截止时间。 这是固定的历史时间点，之后框架的所有变化它都不知道。

第二条：官方文档的更新节奏。 文档每天都在变，且会用版本化路径保留多个 SDK 的写法。仓库里能直接量化这一点——在 plugins/expo/skills 全目录检索 SDK 版本标记，出现次数分别是：SDK 55 出现 55 次、SDK 56 出现 45 次、SDK 57 出现 28 次、SDK 54 出现 11 次、SDK 58 出现 6 次。也就是说，这套技能同时在为五个 SDK 版本写分支说明，而不是只描述"最新版"。

第三条：CLI 的行为变化。 这条最容易被忽略，因为它不体现在文档的 API 页里，而是体现在终端输出里。仓库对此有非常直白的处理方式，plugins/expo/skills/eas-update/SKILL.md 第 75 行写着：

Check the current CLI help before relying on remembered flags:

```bash
npx eas-cli@latest update --help

同一套策略在 `eas-observe` 里更彻底。`plugins/expo/skills/eas-observe/references/queries.md` 开篇定义：

> The CLI changes between releases, so treat `--help` as the source of truth.

`eas-simulator` 则把"命令本身可能消失"写进了技能主体：`simulator:*` 系列是**实验性的隐藏命令**，需要 eas-cli ≥ 20.3.0，并且"the relevant subcommand's `--help` output is authoritative"。

这三条线的区别很关键：训练截止是"不可修的"，文档更新是"可查的"，CLI 行为是"只能现场问的"。模型记忆对三者的处理方式如果一视同仁——都靠回忆——那么第三条线必然出错。知识库的第一价值，不是塞给模型更多知识，而是告诉它**哪些知识不许靠回忆**。

## 模型记忆失效的五种具体形态

抽象的"知识滞后"没有说服力，具体到代码才有。以下每一条都能在仓库里找到对照文件。

### 1. 同一个组件，两个版本的写法不兼容

`plugins/expo/skills/expo-router/references/tabs.md` 开头就是一张兼容性表：

| Aspect | SDK 54 | SDK 55+ |
| --- | --- | --- |
| Import | `import { NativeTabs, Icon, Label, Badge, VectorIcon }` | `import { NativeTabs }` only |
| Icon | `<Icon sf="house.fill" />` | `<NativeTabs.Trigger.Icon sf="house.fill" />` |
| Badge | `<Badge>9+</Badge>` | `<NativeTabs.Trigger.Badge>9+</NativeTabs.Trigger.Badge>` |
| Android icons | `drawable` prop | `md` prop (Material Symbols) |

SDK 55 的写法在 SDK 54 上必然报错，反之亦然。模型如果只记住其中一种，就会生成一份"看起来完全正确、但在当前项目里无法运行"的标签栏代码。技能的做法是：默认给 SDK 55 语法，同时明确写出 SDK 54 的替换规则。

### 2. 导入路径被收编

`plugins/expo/skills/expo-router/SKILL.md` 第 44 行：

> In SDK 56+, never import from `@react-navigation/*` directly — use `expo-router/react-navigation` instead.

这是一个典型的"模型记忆污染"场景：过去几年里，React Navigation 是 Expo 项目里导航相关 `import` 的常态，训练数据里这类代码极多。模型会自然地继续写 `@react-navigation/native`，而官方在 SDK 56 之后要求统一走 `expo-router/react-navigation`。`expo-upgrade` 甚至为此单独配了迁移参考 `plugins/expo/skills/expo-upgrade/references/react-navigation-to-expo-router.md`（含 codemod 与手工映射）。

### 3. 包被拆分了

`plugins/expo/skills/expo-upgrade/SKILL.md` 的弃用表把这件事列得很清楚：

| Old Package | Replacement |
| --- | --- |
| `expo-av` | `expo-audio` and `expo-video` |
| `@expo/vector-icons` | `expo-symbols`（用于 SF Symbols） |
| `AsyncStorage` | `expo-sqlite/localStorage/install` |
| `expo-app-loading` | `expo-splash-screen` |

`expo-av` 曾经是音视频的默认答案，训练数据里此类用法密度极高。官方把它拆成两个包之后，模型仍会推荐 `Audio.Sound`、`Video` 组件。技能里不仅给出替换关系，还配套了 `expo-av-to-audio.md` 与 `expo-av-to-video.md` 两个迁移文件，把 `Audio.Sound` → `useAudioPlayer`、`Audio.Recording` → `useAudioRecorder`、`Video` → `VideoView` + `useVideoPlayer` 的对应关系逐项列出。

### 4. 属性改名与同一功能的弃用

`expo-router/SKILL.md` 第 232 行：`headerLargeTitleEnabled` 是 SDK 56+ 的名称，旧 SDK 用 `headerLargeTitle`，且已在上游弃用。`expo-animation/SKILL.md` 则记录了 Reanimated 4 的变化：`scheduleOnRN(fn, ...args)` 取代了已被弃用的 `runOnJS(fn)(...args)`。

这类改动单个看都很小，但数量极多。这正是模型最容易"自信地写对 90%、错掉关键 10%"的地方。

### 5. 版本里藏着会致命的坑

最典型的一条在 `expo-upgrade/SKILL.md` 第 30 行：

> If upgrading from SDK 55 or earlier, skip SDK 56 and upgrade directly to SDK 57. Don't use `expo@57.0.8` or below. SDK 55 with Hermes V1 enabled, SDK 56, and older SDK 57 releases contain a Hermes V1 memory regression that can drastically increase memory usage when using `react-native-worklets` or `react-native-reanimated`.

这条信息无法从任何 API 文档里推导出来，它是一条"版本区间 + 特定依赖组合"的运行时事故记录。模型不可能凭训练数据知道 `57.0.8` 与 `57.0.9` 的差别。这类知识的唯一来源，就是官方持续维护的知识库。

把五类放在一起看，结论很清楚：**模型记忆擅长的是"一般形态"，而框架演进制造的恰恰是"版本例外"。知识库要解决的，是例外。**

## 官方知识库的补偿机制：四层设计

读仓库可以直接看出这套机制的分层结构，而不是一堆散落的 Markdown。

### 第一层：路由与共享规则

任何 Expo/EAS 任务先加载 `expo-overview`。它的 description 把触发条件写得极严（请求或 `package.json` 中出现 expo 依赖才加载，纯 React Native 项目不加载），正文则定义了五步流程：确认是 Expo/EAS 工作 → 读懂用户目标 → 用 Skill Map 分类 → 模糊时确认意图 → **信任叶子技能，不要自己发挥**。

真正有价值的是它下面的"共享设置规则"，这些规则是跨技能的事实约束：

- **先探测 SDK 版本**：读 `package.json` 里的 `expo` 版本，以及 `app.json` / `app.config.{js,ts}`。规则原话是"Many APIs and defaults differ by SDK"。
- **按 SDK 版本读文档，不要读 `latest`**：使用 `https://docs.expo.dev/versions/v56.0.0/sdk/ui/`，而不是 `.../versions/latest/sdk/ui/`，因为 `latest` 页面跟踪最新 SDK，可能描述项目还没有的 API。
- **装包只用 `npx expo install <pkg>`**，不用裸 `npm`/`yarn add`，以保证与项目 SDK 兼容。
- **区分 managed 与 prebuild**：是否存在已提交的 `ios/`、`android/` 目录，决定 config plugin 与原生配置步骤完全不同。

这几条本质上是在给模型装"前置检查"。模型默认行为是直接开始写代码，而这里强制它先读版本、再动手。

### 第二层：渐进披露（progressive disclosure）

这是整套设计的核心取舍。`CONTRIBUTING.md` 写得很直接：

> When a skill triggers, its whole `SKILL.md` loads into the agent's context. Shorter is better.
> The body is capped at **500 lines** (CI-enforced) — treat that as a ceiling, not a target.

于是有了明确的分层：`SKILL.md` 只放高频、必须立即知道的内容；细节进 `references/*.md` 按需加载；可复用的校验/抓取逻辑进 `scripts/`。

以 `expo-native-ui` 为例，主文件只给出"先试 Expo Go"的判断标准和代码风格，真正的细节分散在七个引用文件里：`controls.md`、`gradients.md`、`icons.md`、`media.md`、`storage.md`、`visual-effects.md`、`webgpu-three.md`。

`eas-workflows` 更进一步，把"获取事实"变成了可执行脚本 `plugins/expo/skills/eas-workflows/scripts/fetch.js`，并在 SKILL.md 里要求：

> When users ask about available options (job types, triggers, runner types, etc.), fetch the schema and derive the answer from it rather than relying on potentially outdated information.

这句话是整套知识库的方法论浓缩：**不要背答案，去取事实。**

### 第三层：把"官方判断"固化成可检查的规则

仓库用两个 CI 脚本，把"知识质量"变成了可失败的构建。

`scripts/check-skill-limits.ts` 强制的不只是长度：

- description 非空且 ≤ 1024 字符，正文 ≤ 500 行；
- 目录名必须是 `expo-*` 或 `eas-*`，且 frontmatter 的 `name` 必须等于目录名；
- 每个技能必须带统一的反馈区块（缺失则提示 `--fix-feedback`）；
- `eas-*` 技能正文必须包含 `**EAS service - costs apply.**` 与 `expo.dev/pricing` 链接；
- 必须存在 `agents/openai.yaml`（Codex 触发元数据）；
- 必须与 `skills.sh.json` 的分组一致，且反向检查：catalog 里列了但目录不存在的技能同样报错。

`scripts/check-overview-routing.ts` 则保证路由完整：它扫描 `plugins/expo/skills` 下所有含 `SKILL.md` 的目录，要求每个名字都以行内代码形式出现在 `expo-overview` 的正文里，否则以退出码 1 结束，并在 job summary 里列出漏掉的技能。

把这两条写进 CI 的意义在于：知识库的"完整性"不再依赖作者自觉，而是构建失败。

### 第四层：实时通道与反馈回路

技能是静态知识，MCP 是动态通道。`plugins/expo/mcp.json` 只做一件事：

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "expo": {
      "type": "streamable-http",
      "url": "https://mcp.expo.dev/mcp"
    }
  }
}

Claude Code / Grok / Cursor 读的是另一份 .mcp.json，传输类型写 "http"——AGENTS.md 第 78 行专门解释了这个差异：Agent Plugins 标准不认 "http" 这个 transport 值。这种细节本身就是"文档比记忆可靠"的又一例证。

MCP 承担的是技能做不到的部分：按需读最新文档、用 npx expo install 装兼容依赖、触发并监控 EAS 构建、从 TestFlight 拉崩溃数据、在模拟器里截图。

反馈回路则写在每个 SKILL.md 的末尾，格式统一：

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-upgrade" "<actionable feedback>"

并且不止收"技能写错了"，还收"Agent 用技能失败了"：

If an agent repeatedly fails at an Expo task or the user has to step in, submit a brief report ... using --category evals.

这一步很关键——它把线上失败样本变成下一版技能的训练输入。知识库因此不是发布一次就结束的产物，而是一个有回写路径的循环。

它自己也会失效：仓库里真实存在的两处裂缝

如果只夸机制，这篇文章就没有信息量。这套知识库有明显的失效点，而且能在源码里指出来。

裂缝一：路由指向了一个不存在的技能

plugins/expo/skills/expo-overview/SKILL.md 的 Skill Map 里有一行：

- `expo-tailwind-setup` — Tailwind / NativeWind styling

但 plugins/expo/skills/ 下并没有 expo-tailwind-setup 目录。也就是说，当用户说"给我的 Expo 项目配 Tailwind"时，路由器会把 Agent 指向一个不存在的 SKILL.md。

为什么 CI 没拦住？看 scripts/check-overview-routing.ts 的检查方向就明白了：

const missing = skillNames.filter((name) => !router.includes(`\`${name}\``));

它只做一件事——目录里有、路由里没有才算失败；路由里有、目录里没有完全不检查。而 check-skill-limits.ts 的反向校验只覆盖 skills.sh.json，expo-tailwind-setup 并不在该 catalog 里，于是两边都漏掉了。

这是一个非常典型的"知识库失效模式"：索引比内容先腐烂。索引坏了比内容旧了更危险，因为 Agent 会顺着索引走进死路，然后再用模型记忆去补——正好回到这套机制想解决的问题。

裂缝二：技能级 version 不能当作新鲜度信号

plugins/expo/skills 下 23 个 SKILL.md 的 frontmatter 版本分布是：1.0.0 出现 15 次，其余为 1.0.1、1.1.0、1.1.1、1.2.0、1.4.0。而插件版本是 1.14.2。

也就是说，expo-upgrade/SKILL.md 里明明写着 SDK 57 的 Hermes 内存回归、expo-router 里明明写着 SDK 56+ 的导入规则，它们的 frontmatter 却仍然是 version: 1.0.0。CI 的版本一致性检查（check-plugin-version-bump.ts）只校验两个 plugin manifest 彼此相等且大于 main，并不管技能级版本。

结论很实用：在这个仓库里，version 字段不代表内容新旧，updatedAt 之类的字段也不存在。判断新鲜度的唯一可靠方式，是看正文里引用的 SDK 版本与 CLI 版本。

顺带一个结构性的小瑕疵：expo-upgrade/SKILL.md 的正文直接从 ## References 开始，没有一级标题，这与 AGENTS.md 里"# Skill Title"的模板约定不一致。它能通过 CI，说明当前检查项覆盖的是元数据与目录一致性，而非文档结构本身。

裂缝的意义不是否定这套设计，而是给出正确的使用姿势：把它当成一份需要被验证的官方资料，而不是一份免检的权威。

开发者该怎么给 AI 补这一课

基于上面的事实，给 AI"补课"有一套可落地的顺序。

1. 先安装，别让技能躺在仓库外面

Claude Code / Codex 走插件市场，更新由市场托管：

claude plugin install expo@claude-plugins-official
codex plugin add expo@openai-curated

Cursor、OpenCode、Copilot、Windsurf、Gemini、Cline 等走 skills CLI：

npx skills@latest add expo/skills --skill '*'

注意 --skill '*' 只选择全部技能，不会替你选全部 Agent；安装位置仍会询问，要直指某个 Agent 就加 --agent <agent>。装完必须重启或刷新会话，Agent 才会重新发现 SKILL.md。

更新是分开的两条路：插件装法走市场，CLI 装法走 npx skills@latest update（单技能可 npx skills@latest update expo-router）。

2. 明确告诉 Agent：先确认 SDK，再写代码

expo-overview 已经内置了这条规则，但如果你的项目不是标准 Expo 结构（比如 brownfield、或者 SDK 版本被锁死），值得在项目自己的 AGENTS.md 里再写一遍：

- Read the `expo` version from package.json before giving version-specific advice.
- Use version-pinned docs: https://docs.expo.dev/versions/v<version>/...
- Install with `npx expo install`, never raw npm add.

expo-upgrade/SKILL.md 的 Housekeeping 里也要求"升级后同步更新 agent 指令文件里的版本化文档链接"——这说明官方也承认：Agent 配置文件本身就是需要随 SDK 一起维护的知识载体。

3. 让"命令"永远现场查

这是最容易被跳过、收益最高的一条。把下面这种要求显式写进工作流：

• 发布 OTA 前跑 npx eas-cli@latest update --help，核对 channel/environment 参数；
• 用 eas observe:* 前跑 eas observe --help；
• 用 eas simulator:* 前确认 eas-cli 版本 ≥ 20.3.0，并读对应子命令的 help。

模型对 CLI 参数的记忆几乎一定过期，因为这不是"版本化的 API"，而是"每次发版都可能变的 oclif 命令树"。

4. 用 MCP 拿事实，用技能定流程

技能教"这件事该怎么做"，MCP 提供"现在是什么状态"。插件安装会自动带上 MCP 配置；skills CLI 装法只装技能，MCP 要单独配。两者配合的典型链路是：技能决定要发布一个预览更新 → MCP 读当前文档与项目状态 → npx expo install 保证依赖与 SDK 对齐 → 触发 EAS 构建 → 在云端模拟器里截图验证。

5. 验证"触发"是否真的发生

这是最反直觉的一点。技能再准，没被加载也等于零。

仓库的 eval 体系暴露了一个真实的坑，写在 scripts/ci.sh 顶部：

Has to be the 1M variant. On 200k, Claude Code drops the skill descriptions from its menu, so nothing triggers and every trigger score reads 0. Nobody documents this, we hit it in CI.

export AGENT_MODEL="${AGENT_MODEL:-sonnet[1m]}"

也就是说，上下文窗口不足会导致技能描述从菜单里消失，触发率直接归零。如果你的 Agent 明明装了技能却像完全没有，先查上下文预算，而不是怀疑内容质量。

同样值得借鉴的是它的评测方法论：scripts/ci.py 计算 fingerprint 时，hashes 覆盖技能内容、eval-harness 版本、PRD/scenario/ground truth、Agent 与模型——任何一个变化都不允许复用缓存结果。这条思路可以直接搬到团队内部：换模型、换提示、换技能版本，评测结果就不可比；不可比就不能复用结论。

谁更懂最新写法

回到标题的问题。大模型记忆和官方知识库不是同一层的东西：模型记忆提供的是"这件事大概怎么做"的通用判断力，官方知识库提供的是"在你这套 SDK、这个 CLI 版本上具体怎么写"的事实约束。

在稳定期，两者答案一致，记忆足够。在演进期，记忆必然滞后，且滞后的方式很隐蔽——代码能编译、风格也对，只是在当前版本上不对。Expo 这套技能库的价值，不在于它比模型更聪明，而在于它把"版本、CLI、迁移路径"这些不可推理的部分，变成了可读取、可执行、可校验的文件，并且用 CI 强制它们保持同步。

但它自己也会腐烂：路由表里指向了不存在的 expo-tailwind-setup，技能级版本号停在 1.0.0 却写着 SDK 57 的事故记录，结构约定也没被完全执行。这些裂缝提醒我们一件事：知识库不是用来替代思考的，它是用来把"猜测"降级成"核对"的。

真正可靠的工作方式只有一种：让 Agent 先读技能决定流程，再读版本决定写法，最后跑 --help 或 MCP 确认现状。三步都做完，它写出的代码才真的属于你的项目，而不是属于它的训练数据。