audit-expo-skill

Clerk Expo 技能审计

将此仓库中的 skills/clerk-expo/ 与实际的 @clerk/expo SDK 源码及其引用的 clerk-docs 内容进行交叉核对。SDK 源码是 API 形态的事实依据；clerk-docs 是推荐模式的事实依据；该技能必须同时与两者保持一致。当两者在事实声明上发生冲突（某个 API 是否存在、签名、默认值、最低版本要求）时，始终以 SDK 源码为准。 只有在源码无法回答的指导性问题上（建议采用哪种流程、示例中的属性放置位置、仪表板前置条件），才以文档为准。

该技能会有意硬编码经过验证的代码片段（参见其新鲜度门禁）。此审计是这项约定的维护环节：在 SDK 发布后运行审计，确保代码片段始终经过验证，而不会沦为未经核实的传言。

输入

• SDK 事实来源：包含 packages/expo/（以及 packages/shared/src/types/ 中登录/注册资源类型）的 clerk/javascript 检出副本。
• 文档事实来源：包含 docs/getting-started/quickstart.expo.mdx、docs/guides/development/custom-flows/authentication/*.mdx 和 docs/reference/expo/** 的 clerk/clerk-docs 检出副本。
• 目标技能：skills/clerk-expo/SKILL.md、references/*.md 和 evals/evals.json。
• 可选的佐证材料：clerk/clerk-expo-quickstart 检出副本（其中包含三个用于验证当前 API 的示例应用）。

源码检出副本解析

按以下顺序解析每个检出副本：

1. 使用提供的 --sdk <path> / --docs <path>。SDK 路径必须包含 packages/expo/package.json；文档路径必须包含 docs/getting-started/quickstart.expo.mdx。
2. 查找此仓库的同级检出副本：../javascript 和 ../clerk-docs（Clerk 项目的标准目录布局），以及用于佐证的 ../clerk-expo-quickstart。
3. 如果设置了 CLERK_JAVASCRIPT_REPO / CLERK_DOCS_REPO，则使用这些路径。
4. 如果缺少检出副本且可以访问网络，则浅克隆到 .context/：

mkdir -p .context && cd .context
git clone --depth 1 https://github.com/clerk/javascript.git
git clone --depth 1 https://github.com/clerk/clerk-docs.git

如果两者都不可用，请停止并向用户询问路径。不要凭记忆或仅依据已安装的 node_modules 副本进行审计；此审计的存在，正是因为记忆会随着时间偏移。

工作流程

1. 确定版本差异

• 从 SKILL.md frontmatter（compatibility:）中读取技能标注的版本及其新鲜度门禁文本。
• 从 packages/expo/package.json 读取当前版本及 peerDependencies（Expo SDK 范围、React Native 最低版本、React 范围），以及内置的原生 SDK 版本（依赖项中的 clerk-ios、clerk-android）。
• 阅读 packages/expo/CHANGELOG.md 中从标注版本到当前版本之间的条目。这是主要的工作清单：每条变更日志条目都必须影响该技能，或被明确标记为无关。

如果标注版本与当前版本相同，且变更日志中没有新内容，则报告“无偏差”并停止。

2. 梳理 SDK 表面

根据源码构建结构化清单（优先查看 src/，而不是 dist/）：

• 导出映射：查看 packages/expo/package.json 的 exports——列出每个子路径（/native、/web、/token-cache、/resource-cache、/secure-store、/local-credentials、/passkeys、/google、/apple、/legacy、/experimental……），并注明新增和移除项。
• Hooks：列出 src/hooks/index.ts 重新导出的所有内容，以及 Expo 专属 Hooks（useSSO、useAuth 扩展、useSignInWithGoogle、useSignInWithApple、useLocalCredentials）。记录签名、返回结构和 @deprecated 标签。
• 自定义流程资源：梳理 packages/shared/src/types/signInFuture.ts 和 signUpFuture.ts 中 SignInFutureResource / SignUpFutureResource 的方法表面（方法名称、参数结构、状态枚举）。技能中的自定义流程参考文档应与此表面保持一致。
• 原生组件：列出 src/native/index.ts 的导出，以及各组件的 props 类型（AuthView.types.ts、UserProfileView、UserButton）。标出技能中提到但已不存在的 prop，以及新的公开 prop。
• 配置插件：查看 src/plugin/withClerkExpo.ts——必需的环境变量、主题选项架构、平台副作用（最低部署目标、URL 方案）。
• Provider：记录 src/provider/ClerkProvider.tsx 的 props，尤其是实验性选项（__experimental_passkeys、__experimental_resourceCache）以及任何新近稳定的名称。
• 开发警告 / 迁移信号：搜索 @deprecated、console.warn 和包迁移通知（例如拆分 @clerk/expo-google-signin）。将其整理成技能中的“即将变更”说明。

3. 梳理文档中的声明

针对技能参考文档中引用的每个规范文档 URL：

• 确认 clerk-docs 中对应的 .mdx 文件仍存在于该路由下（URL 路径 → docs/ 路径）。失效引用属于 drift。
• 重新阅读每篇所引用自定义流程指南中的 Expo 标签页 / 部分，以及 Expo 快速入门。如果文档建议的模式发生变化（新增必需步骤、prop 放置位置变更、新增 Dashboard 前置条件），那么即使技能中的代码仍能编译，对应代码片段也属于 drift。

4. 提取技能中的声明

阅读 SKILL.md、所有 references/*.md 以及 evals/evals.json。提取每项具体声明：

• 版本标记和 peer 依赖范围。
• 每段代码片段（导入、方法调用、props、环境变量名）。
• 所有提及 API 的门槛和注意事项（useSSO 与 useOAuth、resourceCache 与 secureStore、验证码挂载点、treatPendingAsSignedOut 的放置位置）。
• 能力矩阵（Expo Go / dev build / web）。
• 会断言 API 字符串的 Eval 预期。

5. 对比并分类

整理为四类结构化差异：

1. 技能中缺少：SDK / 文档中新增的导出、Hooks、props、流程或前置条件，技能应涵盖这些内容（或明确排除在范围之外）。
2. 技能中过时：与源码或文档相矛盾的声明——重命名 / 移除的 API、变更的默认值、提高或降低的 peer 依赖最低版本、移动位置的 props、失效的文档 URL、断言过时字符串的 evals。
3. 技能中说明不足：虽然已涵盖，但相较于实际容易踩坑的范围，细节不足（例如开发者会遇到的新错误代码）。
4. 过度详述：文档或已安装的 .d.ts 能更好地覆盖这些细节；若精简可降低漂移风险，则提出精简建议。

对第 1、2、3 类中的每项都引用源文件和行号，并注明技能中的目标位置。

6. 提出修改建议

按目标文件分组，给出可直接用于评审的修改建议。每项修改都应包含严重程度（drift、gap 或 polish）、源码引用、目标位置，以及统一 diff 或简洁的修改前 / 修改后对照。只要应用了任何修改，就必须始终包括：

• 将 SKILL.md 中的 compatibility: 标记和 freshness-gate 版本更新为已审计的 SDK 版本。
• 当 Eval 预期引用了变更的 API 时，同步更新 Eval。

不要重写准确的相邻部分。精简技能内容也是有效的建议。

7. 应用或交还

默认：呈现提案并停止，等待审核。

使用 --apply：应用 drift 和 gap 编辑，更新版本戳，列出 polish 供审核，然后验证——JSON 文件可解析，SKILL.md 中的每个相对引用路径都能解析，且每个规范文档 URL 都对应一个现有的 clerk-docs 文件。

防护措施

• 绝不杜撰 API 表面。若文档与 SDK 源码存在事实冲突，以源码为准并据此编写 skill；在“待解决问题”下将差异列为可能需要向上游报告的 clerk-docs 缺陷。只有源码同时支持两种模式，而文档未说明应推荐哪一种这类真正的规范性歧义，才交由人工审核。
• 代码片段必须保持精简（展示 API 形式和控制流，而非样式化界面），并保留其规范文档 URL 引用。
• 保留 skill 的执行门控结构和语气；编辑内容应融入现有章节。
• 只有 SDK 本身重新认可旧版 API 表面时，才可放宽旧版 API 禁令（门控：基于方法的流程，新增代码绝不使用 prepareFirstFactor/setActive）。任何此类变更都应视为重大发现，而非例行编辑。
• 不要将已安装的 node_modules 副本作为依据进行审核；它反映的是上次安装拉取的内容，而非正在审核的版本。
• 不要提交；除非明确要求，否则将暂存和提交留给维护者处理。

输出格式

# clerk-expo skill audit - <YYYY-MM-DD>

## Summary
<stamped vs current version, changelog entries reviewed, counts per bucket, largest drift>

## skills/clerk-expo/SKILL.md
### <section>
- [drift|gap|polish] <one-line description>
  - source: packages/expo/src/<...>:<line> (or docs/<...>.mdx:<line>)
  - target: skills/clerk-expo/SKILL.md:<line>
  - change: <diff or concise before/after>

## skills/clerk-expo/references/<file>.md
...

## skills/clerk-expo/evals/evals.json
...

## Open questions
...

确保结果易于浏览，以便维护者可以逐项批准、拒绝或应用。