前言¶
線上告警一響，開發者的典型動作往往是：先打開 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/
