sentry-miniapp: Instructions file for Codex

AGENTS.md - Agent 入场清单

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

本文件是 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、集成插件或事件构建时扩大验证范围。