基于 Codex Skills 目录的 Sentry 只读可观测性技能：用 Sentry CLI 排查线上问题-港品优选

基于 Codex Skills 目录的 Sentry 只读可观测性技能：用 Sentry CLI 排查线上问题

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

导读

本文讲解 GitHub 推荐项目精选 skills 仓库中sentry技能（Skill）的完整用法。该技能封装了 Sentry CLI 的只读查询能力，让 AI Agent 在收到"查看 Sentry issue/event、总结近期线上错误、拉取基础健康数据"等请求时，能通过sentry命令自动完成认证、组织/项目探测、分页与重试，并以 JSON 结构化输出结果。读完本文，你将掌握从安装认证、issue/event 查询到 AI 根因分析与修复方案生成的完整实战链路，并能理解该技能在 Codex 中的装配方式与输出规范。

技能定位：Sentry 只读可观测性

sentry技能定义于 skills/.curated/sentry/SKILL.md，属于本仓库 curated（精选）技能目录。其设计目标非常明确：

当用户要求查看 Sentry issues 或 events、总结近期生产错误、拉取基础 Sentry 健康数据时被触发；
所有操作均为只读查询，统一通过sentryCLI 完成；
底层命令自动处理认证、组织/项目探测、分页和重试，Agent 无需自行实现这些繁琐逻辑。

该技能的装配元数据在 skills/.curated/sentry/agents/openai.yaml 中声明：显示名称为 "Sentry (Read-only Observability)"，默认提示词（default_prompt）为"以只读方式调查该 Sentry issue，并报告可能的根因、影响和后续步骤"——这决定了 Agent 被触发后的默认行为模式。

快速开始：认证与安装

1. 认证方式（二选一）

使用前必须先完成 Sentry CLI 的认证，两种方式任选其一：

# 方式一：交互式登录（浏览器授权） sentry auth login # 方式二：设置环境变量（适合 CI / 非交互场景） export SENTRY_AUTH_TOKEN="your-auth-token"

安全红线：绝对不要要求用户把完整 Token 粘贴到聊天中。应让用户在本地自行设置，确认完成后即可继续。在输出中也严禁回显认证 Token。

2. 确认认证状态

sentry auth status

3. 安装 Sentry CLI

如果 CLI 尚未安装，按以下步骤操作：

# 1. 安装 Sentry CLI curl https://cli.sentry.dev/install -fsS | bash # 2. 登录认证 sentry auth login # 3. 确认认证成功 sentry auth status

4. 组织/项目自动探测机制

CLI 会从以下来源自动探测组织（org）与项目（project）：

.env文件中的 DSN；
源码中的 DSN 配置；
配置默认值；
目录名。

只有在自动探测失败或探测到错误目标时，才需要显式指定<org>/<project>。这意味着 Agent 在绝大多数场景下可以直接执行查询命令，无需关心目标地址。

5. 默认参数与 JSON 输出约定

技能内置了三组关键默认值：

参数	默认值	传参方式
时间范围（time_range）	`24h`	`--period 24h`
环境（environment）	`production`	并入`--query`，如`environment:production`
结果条数上限（limit）	20	`--limit 20`

输出约定：

程序化处理输出时始终使用--json；
使用--json --fields只选择需要的字段，减小输出体积；
快速发现可用 API 端点时使用sentry schema <resource>。

核心任务：基于 Sentry CLI 的七类查询

所有查询统一走sentryCLI，且尽量使用--json以获得机器可读输出。以下命令均可直接复制运行。

1. 列出 issues（按最近排序）

查询最近 24 小时内生产环境未解决的 issue，取前 20 条，并只输出指定字段：

sentry issue list \ --query "is:unresolved environment:production" \ --period 24h \ --limit 20 \ --json --fields shortId,title,priority,level,status

如果自动探测未能解析出 org/project，显式传入：

sentry issue list {your-org}/{your-project} \ --query "is:unresolved environment:production" \ --period 24h \ --limit 20 \ --json

2. 将 issue 短 ID 解析为详情

sentry issue view {ABC-123} --json

注意：必须使用短 ID 格式（如ABC-123），而不是数字型 ID。

3. 查看 issue 详情

sentry issue view {ABC-123}

4. 查看 issue 的 events（事件流）

sentry issue events {ABC-123} --limit 20 --json

事件流是理解"该 issue 究竟被哪些请求/堆栈触发过"的关键，--limit控制取样数量。

5. 查看单个 event 详情

sentry event view {your-org}/{your-project}/{event_id} --json

event 详情通常包含 culprit（罪魁祸首位置）、时间戳、环境、release 版本与 URL 等信息，见下文"输出格式规范"。

6. AI 驱动的根因分析（Root Cause Analysis）

sentry issue explain {ABC-123}

该命令借助 AI 能力对 issue 进行根因解释，适合在定位问题时快速获得假设方向。

7. AI 驱动的修复方案生成

sentry issue plan {ABC-123}

在根因明确后，可用该命令生成修复计划，作为后续代码改动的起点。

兜底方案：任意 API 访问与端点发现

对于没有专属 CLI 子命令的端点，使用sentry api直接打 REST 接口：

sentry api /api/0/organizations/{your-org}/ --method GET

使用sentry schema快速发现可用端点：

sentry schema issues

这一兜底路径保证了技能的覆盖面：即使官方 CLI 命令未覆盖某类数据，Agent 仍可通过 OpenAPI schema 发现并调用对应端点，属于技能的可扩展性设计。

输入与默认值详解

技能文档明确定义了可用的输入参数及其处理规则：

输入参数	默认值/取值	说明
`org_slug`/`project_slug`	自动探测	从 DSN、环境变量、目录名探测；失败时用位置参数`{your-org}/{your-project}`覆盖
`time_range`	`24h`	以`--period 24h`传入
`environment`	`production`	作为`--query`的一部分传入，如`environment:production`
`limit`	20	以`--limit`传入
`search_query`	可选	通过`--query`传入，使用 Sentry 搜索语法（如`is:unresolved`、`assigned:me`）
`issue_short_id`	—	直接用于`sentry issue view`

其中search_query支持完整的 Sentry 搜索语法，常用的组合包括is:unresolved（未解决）、is:regressed（回归）、assigned:me（指派给我）、first_seen时间窗口等，可与environment:production等环境过滤条件叠加使用。

输出格式规范：Agent 汇报的硬性要求

为了让 Agent 的汇报结果稳定、可读、合规，技能对输出格式做了明确约定：

Issue 列表（按最近排序）应包含：

title（标题）
short_id（短 ID）
status（状态）
first_seen（首次出现时间）
last_seen（最后出现时间）
count（出现次数）
environments（涉及环境）
top_tags（高频标签）

Event 详情应包含：

culprit（罪魁祸首）
timestamp（时间戳）
environment（环境）
release（发布版本）
url（相关 URL）

行为与安全约束：

若查询无结果，必须明确说明"无结果"，不能含糊带过；
输出时必须对 PII（个人身份信息）脱敏，包括邮箱、IP 地址；
不打印原始堆栈信息；
绝不回显认证 Token。

这些约束与技能"只读可观测"的定位一脉相承：Agent 只负责汇报与辅助分析，不做任何写操作，也不泄露敏感信息。

Golden Test 输入与验收示例

技能内置了用于验收的示例输入与预期输出，可作为复现与自测的标准：

Org: {your-org} Project: {your-project} Issue short ID: {ABC-123}

典型提示词与预期输出：

示例提示词："List the top 10 open issues for prod in the last 24h."预期输出：按最近出现排序的 issue 列表，包含标题、短 ID、出现次数、最后出现时间。

这条验收标准本质上是一份可执行的测试用例，验证 Agent 是否正确执行了"issue list + 排序 + 字段裁剪"的完整链路。

在 Codex 中的装配与安装方式

sentry技能位于本仓库 skills/.curated/ 目录，属于 curated（精选）技能。根据仓库 README.md 的说明：

.system目录下的技能会在最新版 Codex 中自动安装；
curated / experimental 技能需要通过 Codex 内的$skill-installer安装；
精选技能可按名称安装，例如：

$skill-installer sentry

安装完成后重启 Codex 即可生效。单个技能的许可证位于其目录内的LICENSE.txt，sentry 技能的许可证为 skills/.curated/sentry/LICENSE.txt（Apache License 2.0）。

技能目录结构一览

skills/.curated/sentry/ ├── SKILL.md # 技能主体指令（本文讲解的核心） ├── agents/ │ └── openai.yaml # Agent 装配元数据（display_name、default_prompt、图标） ├── assets/ │ ├── sentry-small.svg │ └── sentry.png └── LICENSE.txt # Apache License 2.0

SKILL.md 是技能的行为指令本体；agents/openai.yaml 则定义了它在 Codex 界面中的展示名称、默认提示词与图标，两者共同构成了一个完整可装配的 Agent 技能包。

总结：技能的关键设计要点

只读原则：所有命令均为查询性质，不执行任何写操作，适合作为生产环境的安全观测入口；
自动化优先：认证、org/project 探测、分页、重试全部由 CLI 承担，Agent 只需关注查询语义；
结构化输出：--json+--fields裁剪，配合明确的字段级输出规范，保证下游解析稳定；
AI 能力内置：issue explain与issue plan让"定位问题"与"规划修复"可以一步到位；
安全合规：Token 永不出现在聊天与输出中，PII 必须脱敏，原始堆栈不直接打印；
可扩展：sentry api+sentry schema兜底任意端点，Golden Test 提供可复现的验收基准。

掌握这套技能，Agent 便能在收到"最近生产环境出了什么问题"这类模糊指令时，稳定输出"按最近排序的 issue 列表 + 关键字段 + 根因分析与修复建议"，真正把 Sentry 的只读可观测能力变成可复用的 Agent 能力。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析