git:20261024.585e15a to git:20261103.8060cb9

7 added, 0 removed. Audit A to A.

# AGENTS.md - Agent 入场清单

sentry-miniapp 是基于 `@sentry/core` 的跨端小程序 Sentry SDK，覆盖微信、支付宝、字节跳动、钉钉、QQ、百度、快手，并兼容 Taro / uni-app 等跨端框架。所有功能改动都要优先保护跨端兼容性、降级路径和现有 SDK 使用方式。

本文件是 [agents.md](https://agents.md) 开放标准约定的多 agent 入场清单，跨 Claude Code / Codex / Cursor / Aider / Gemini CLI 等工具通用。Claude Code 用户：本仓库的 `CLAUDE.md` 通过 `@AGENTS.md` import 同一份内容，无需重复维护。

## 开工先做

- 涉及 commit、PR、分支或发版时，先看 `CONTRIBUTING.md`。

- 涉及 SDK 功能或 Core 依赖改造时，先看 `ARCHITECTURE.md` 的职责边界和验证不变量。

- 功能改造前确认对所有已支持平台的影响；如果使用某个平台特有 API，必须提供条件判断或回退机制。

- 交付前默认跑 `yarn run lint` 和 `yarn run test`（Vitest 单测）；涉及构建产物或跨端行为时，再跑 `yarn run build`。

- 新增测试前先检查能否强化现有用例；参数组合优先参数化，跨层重复须保护不同接缝，不以用例数量作为验收指标。具体准则见 `CONTRIBUTING.md` 的 Testing。

- 代码改造完成后，必须检查并更新相关文档，如 `README.md`、`docs/README.en.md`、`website/` 或示例工程文档。

- 文档改动对照当前源码、默认值和实际命令；官网改动运行 `yarn run docs:build` 并核对链接／锚点。用户指南讲当前行为，旧配置放迁移页，版本审查证据保留在维护记录；文档索引见 `docs/README.md`。

## 硬规则

- 遵守 GitHub Flow：`master` 是唯一长期分支；feature / fix / docs / chore 从最新 `master` 切短分支，通过 PR 回 `master`。

- 不要直接在 `master` 上提交；不要引入 `develop` 或其它长期集成分支。

- commit 格式必须使用 Conventional Commits，并用中文 subject，例如 `feat: 新增网络请求体抓取功能`。推荐 scope 使用稳定模块名，如 `sdk` / `cross-platform` / `integrations` / `transports` / `docs` / `agents-md` / `release`。

- 遵循现有 ESLint 规范，优先使用 TypeScript。

+ ## Sentry Core 升级收尾

+ - 处理 `@sentry/core` 升级 PR 时，同时查找本仓库跟踪该目标版本的 open Issue，包括更新检查 Action 自动创建的 Issue。

+ - 关联 Issue 的收尾属于升级任务的一部分，无需再次询问。确认 PR 已合并至默认分支、该分支已使用目标版本且必需 CI 通过后，将对应 Issue 关闭为 completed。

+ - 合并前优先在 PR 描述中加入 `Closes #<issue>`；PR 已合并时直接关闭对应 Issue。仅关闭而未合并的 PR、失败或未完成的升级，不视为 Issue 已解决；不关闭无关或目标版本尚未安装的 Issue。

+ - 最终同时报告 PR 与关联 Issue 的状态，两者均核对完成后才能宣布升级任务完成。

## 用户视角的文档

- README、官网和对外介绍中的核心能力与适用场景，必须先说明用户遇到的问题、适合的项目或场景，以及接入后能获得的结果。

- 使用用户能理解的语言。API 名称、协议字段和实现机制放在对应接入、配置或架构文档中；介绍中只保留影响用户选择或操作的技术细节。

- 能力与收益必须对照当前实现，保留必要的启用条件、平台差异和使用限制，避免把可选采集写成默认能力，或承诺完整捕获、必定送达、自动合规等无法保证的结果。

## 跨端兼容性

- 改平台能力时，同时考虑微信、支付宝、字节跳动、钉钉、QQ、百度、快手。

- 新增平台特有 API 前，先查现有 `src/crossPlatform.ts`、`src/types.ts` 和相关 integration / transport 的抽象方式。

- 没有同等能力的平台要有明确回退：跳过、降级、特性检测或保守默认值，避免运行期直接报错。

- 小游戏（微信 / 抖音 / 快手小游戏）没有 `App()`/`Page()`/路由；用 `crossPlatform.isMinigame()` 区分并检测实际平台 API，依赖 App/Page 的能力须守卫 no-op。2.0 的小游戏生命周期默认按宿主检测启用，首帧只测 SDK 安装至首次 rAF；FPS 默认关闭，使用 `enableMinigameFrameRate: true` 显式启用。公共集成使用 factories，不恢复旧 class 或伪造完整冷启动测量。

- 测试应覆盖平台差异入口；窄改动至少补对应单测，影响 SDK 初始化、transport、集成插件或事件构建时扩大验证范围。

## sentry-miniapp 自带 skill 安装（跨 agent）

仓库根 `.agents/skills/sentry-miniapp-sdk/` 是 sentry-miniapp 智能代理 skill 的**单一来源**，采用中性的 [Agent Skills](https://agentskills.io) 目录：

- **Codex**：原生加载 `.agents/skills/sentry-miniapp-sdk/`，clone 仓库即可使用。

- **Claude Code**：通过软链 `.claude/skills/sentry-miniapp-sdk` → `.agents/skills/sentry-miniapp-sdk` 加载，无需重复维护。

需要在其它项目全局复用时，可把同一目录拷到 agent 工具约定的 skill 根目录：

```bash

# Codex

cp -r .agents/skills/sentry-miniapp-sdk ~/.agents/skills/sentry-miniapp-sdk

# Cursor / Aider / Gemini CLI 等

# 按各工具文档，把 .agents/skills/sentry-miniapp-sdk 放到对应 skill 目录即可

```

除上述受版本控制的 skill 外，`.agents/` 和 `.codex/` 下的本地 hook、配置及安装副本仍不进仓库。不要在其它目录提交 skill 内容的第二份副本。

## 常用命令

> 开发环境要求：Node 20.x ≥ 20.19、22.x ≥ 22.13 或 ≥ 24，满足当前 Core、Vite、Vitest、ESLint 的共同范围；Yarn 4（由 `package.json` 的 `packageManager` 固定）。发布包 `engines.node` 的 SDK 依赖范围另与固定的 Core 一致。首次先跑 `corepack enable`，让仓库内的 `yarn` 自动对齐到固定版本。

- `yarn install` - 安装依赖

- `yarn run lint` - 代码检查

- `yarn run typecheck` - 严格检查源码与测试代码的 TypeScript 类型

- `yarn run test` - 运行单元测试（Vitest）

- `yarn run test:coverage` - 运行单元测试并检查覆盖率门槛

- `yarn run test:shuffle` - 随机化用例顺序，检查测试隔离性

- `yarn run build` - 构建项目

- `yarn run build:miniapp` - 生成并检查微信示例使用的独立 bundle

- `yarn run dev:miniapp` - 监听源码并持续构建微信示例 bundle

## 参考

- 用户入口：`README.md` / `docs/README.en.md`

- 维护者架构与设计取舍：`ARCHITECTURE.md`

- 用户文档站：`website/`（接入、配置、平台能力与排障内容的主入口）

- 英文用户入口、对外文章与媒体素材：`docs/`（文章索引见 `docs/articles/README.md`）

- 设计补充和版本审查记录索引：`docs/README.md`

- 示例工程：`examples/wxapp/`

- sentry-miniapp skill 入场：`.agents/skills/sentry-miniapp-sdk/SKILL.md`（单一来源，见上节）

- 分支 / 贡献细节：`CONTRIBUTING.md`