前言¶
线上告警一响，开发者的典型动作往往是：先打开 Sentry 看 Issue 列表，再切回终端或 IDE 查日志、对代码、写修复方案。Dashboard 和对话窗口来回切换，上下文容易断；如果只是问 AI「最近生产有什么未解决的错误」，它通常拿不到你 Sentry 项目里的实时数据，只能给泛泛的建议。
sentry 是 OpenAI 在 openai/skills 仓库 .curated 目录下维护的一个 Agent Skill。它把 Sentry 官方 CLI 的只读查询能力写进 Skill 指令里，让 Cursor、Codex CLI 等支持 Agent Skills 的工具，在用户提出「查 Issue、汇总生产错误、拉基础健康数据」这类需求时，能按规范调用 sentry 命令，而不是凭空猜测。
下面按「是什么 → 能做什么 → 怎么装 → 怎么用 → 注意什么」的顺序说明。文中命令与参数均来自官方 SKILL.md 与 Sentry CLI 文档 的交叉核实。
这是什么¶
sentry Skill 的定位可以概括为：通过 Sentry CLI 做只读的可观测性查询。
- 出品方：Skill 指令由 OpenAI 维护，收录于
skills/.curated/sentry；底层依赖 Sentry 官方的sentryCLI（cli.sentry.dev）。 - 触发场景（写在 SKILL.md 的
description里）：用户要求检查 Sentry Issue 或 Event、汇总近期生产错误、拉取基础健康数据时启用。 - 能力边界：以 只读查询 为主；认证、组织/项目识别、分页与重试交给 CLI 处理，Agent 侧重组织查询与呈现结果。
Skill 遵循通用的 SKILL.md 格式（Agent Skills 开放标准），同一套文件夹可在不同 AI 编程工具中复用。
核心功能与亮点¶
1. 围绕 Issue 的完整只读链路¶
Skill 把常用 CLI 子命令整理成固定工作流，主要包括：
| 任务 | 命令示例 |
|---|---|
| 列出 Issue（默认最近、可筛选） | sentry issue list |
| 查看单个 Issue 详情 | sentry issue view {ABC-123} |
| 查看 Issue 下的事件列表 | sentry issue events {ABC-123} |
| 查看单个 Event 详情 | sentry event view {org}/{project}/{event_id} |
| AI 根因分析 | sentry issue explain {ABC-123} |
| AI 修复计划 | sentry issue plan {ABC-123} |
Issue 使用 短 ID（如 ABC-123），不是数字 ID。列表查询支持 Sentry 搜索语法，例如 is:unresolved environment:production。
2. 自动识别 org / project¶
CLI 会从 .env 中的 DSN、源码、配置默认值、目录名等自动推断目标项目；推断失败时再显式传入 {your-org}/{your-project}。这对 monorepo 或多服务项目比较省事。
3. 面向 Agent 的 JSON 输出约定¶
程序化处理时 Skill 要求使用 --json；需要精简字段时配合 --json --fields。未覆盖的 API 可走 sentry api，用 sentry schema 发现可用端点。
4. 内置安全与呈现规范¶
Skill 明确要求：
- 未认证时引导用户本地执行
sentry auth login，或设置SENTRY_AUTH_TOKEN环境变量；不要在对话里粘贴完整 Token。 - 输出中脱敏 PII（邮箱、IP 等），不打印原始完整堆栈；不回显认证凭据。
- 无结果时要明确说明，Issue 列表需展示标题、short_id、状态、时间、计数等关键字段。
5. 默认查询参数¶
Skill 约定的默认值（可在命令中覆盖）：
- 时间范围：
24h（--period 24h） - 环境：生产（查询里写
environment:production） - 条数上限：
20（--limit 20）
安装与启用¶
Skill 本体是一个目录（至少包含 SKILL.md）。使用前还需在本机安装 Sentry CLI 并完成认证。
第一步：安装 Sentry CLI¶
官方安装方式（Skill 原文）：
curl https://cli.sentry.dev/install -fsS | bash
认证与确认：
sentry auth login
sentry auth status
也可通过环境变量 SENTRY_AUTH_TOKEN 完成认证，Token 仅在本地配置，不要发给 Agent。
第二步：安装 sentry Skill¶
Codex CLI（官方文档核实）：在 Codex 对话中使用 $skill-installer 安装 curated 技能，例如：
$skill-installer sentry
或指定 GitHub 目录 URL：
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/sentry
安装后重启 Codex 以加载新 Skill。OpenAI 文档也说明，也可将 Skill 目录放到仓库或用户目录下的 .agents/skills 路径供 Codex 扫描发现。
Cursor：将 skills/.curated/sentry 目录复制到项目的 .cursor/skills/sentry/（或用户级 Skill 目录），保证其中包含 SKILL.md 即可。Cursor 会在 Agent 上下文中按 Skill 的 name 与 description 匹配任务。
说明：openai/skills 仓库 README 标注该仓库已 deprecated，后续 Codex 插件示例迁移至 OpenAI Plugins；但 sentry 的 SKILL.md 内容与 Sentry CLI 命令仍可直接使用，安装方式以各工具当前文档为准。
典型用法示例¶
列出最近 24 小时未解决的生产 Issue¶
Skill 中的标准示例（与 issue list 文档 一致）：
sentry issue list \
--query "is:unresolved environment:production" \
--period 24h \
--limit 20 \
--json --fields shortId,title,priority,level,status
自动识别失败时显式指定 org/project：
sentry issue list my-org/my-project \
--query "is:unresolved environment:production" \
--period 24h \
--limit 20 \
--json
查看 Issue 详情与事件¶
sentry issue view ABC-123 --json
sentry issue events ABC-123 --limit 20 --json
借助 Sentry 内置 AI 做根因与修复建议¶
sentry issue explain ABC-123
sentry issue plan ABC-123
这两条命令依赖 Sentry 侧能力，需账号与项目权限满足 CLI 要求。
在 Agent 对话中的提示词¶
Skill 自带的 Golden test 示例：
List the top 10 open issues for prod in the last 24h.
中文场景可类似表述：「列出过去 24 小时生产环境前 10 个未解决的 Sentry Issue，按最近活跃排序。」启用 sentry Skill 后，Agent 应走 CLI 查询并结构化汇总，而不是编造 Issue 列表。
适用场景与注意事项¶
适合谁用
- 需要把 线上故障排查 嵌进 AI 工作流的开发、SRE、DevOps 同学。
- 已在项目里接入 Sentry，希望 Agent 能 只读 拉 Issue/Event，辅助值班、复盘、写 incident 摘要。
- 希望统一「查 Sentry → 解释 → 给修复方向」话术，减少每次手写 CLI 的心智负担。
使用注意
- 只读边界：Skill 描述强调 read-only 查询；修改 Issue 状态、发版等写操作不在 Skill 核心流程内，勿误以为 Agent 会自动改 Sentry 配置。
- CLI 必须先就绪：Skill 不会代替你安装 CLI；未安装时应按 Quick start 给出安装与认证步骤。
- 权限与数据安全：生产数据可能含敏感信息，Skill 要求脱敏与克制输出；团队策略若禁止 Agent 访问 Sentry，应在工具层禁用该 Skill 或 Token。
- 默认值可被覆盖：默认
24h/production/limit 20适合快速巡检；跨环境或更长周期需自己在--query、--period里调整。 - 仓库状态：curated 技能仍托管在
openai/skills；长期分发可关注 OpenAI Plugins 与 Codex Skills 文档 的更新。
小结¶
sentry Skill 的价值在于：把 Sentry 官方 CLI 的 Issue 查询、事件查看、AI 解释与修复计划，封装成 Agent 可重复执行的指令集。线上出了问题，不必再在 Dashboard 和聊天框之间反复拷贝粘贴——在本地配好 CLI 与 Token，让 Agent 按 Skill 规范去查、去汇总、去脱敏呈现即可。
官方 Skill 目录：https://github.com/openai/skills/tree/main/skills/.curated/sentry
Sentry CLI 文档：https://cli.sentry.dev/
