STAROps Skill 整合 - STAROps

alibabacloud-starops-chat 是一個 Agent Skill，支援在 AI Agent 中通過自然語言調用阿里雲 STAROps 數字員工，完成根因分析、APM 指標查詢、鏈路追蹤、警示分診等 AIOps 診斷任務。安裝後，Agent 自動將營運問題封裝為 STAROps OpenAPI 呼叫，並以流式方式返回結構化診斷結論。

適用情境

情境	說明	樣本提示詞
服務報錯根因分析	圍繞指定服務分析報錯根因，結合調用鏈、日誌、指標進行多步推理。	幫我排查 inventory 服務報錯的根因是什麼。
Workspace / 服務查詢	查詢當前 workspace 下的服務列表、數量、語言分布等中繼資料。	當前 workspace 中有多少個 APM 服務。
APM 指標分析	分析請求量、錯誤率、延遲等 APM 指標，按維度排序或 Top-N。	查詢請求量最高的服務是哪個。
服務拓撲與分類	查看服務的程式設計語言、上下遊依賴、資源狀態等拓撲資訊。	幫我查看當前 workspace 下有哪些不同語言的服務。
多輪排查	在同一 thread 內基於上一輪診斷結論繼續追問，逐步收斂。	針對剛才定位到的 notification 逾時，看一下它的錯誤記錄檔。

前提條件

已開通阿里雲 STAROps 服務，並已建立數字員工。
數字員工已配置可訪問的 APM、SLS、UModel 等資料來源。未接入資料來源時，診斷會因缺少證據而無法給出有效結論。
已擷取可訪問目標 Workspace 的阿里雲帳號憑據，並具備以下 RAM 許可權：
API 名稱
Action
Resource
CreateThread
starops:CreateThread
acs:starops:<region>:<uid>:digitalemployee/<employee_name>
CreateChat
starops:CreateChat
acs:starops:<region>:<uid>:digitalemployee/<employee_name>
已安裝/更新 CLI並完成憑據配置（推薦）。Skill 內部使用阿里雲 Credentials SDK 預設鏈解析憑據，會自動讀取阿里雲 CLI 的設定檔 ~/.aliyun/config.json，無需重複配置。
重要
為防止憑據泄露，不要在 Agent 對話中粘貼 AccessKey ID 或 AccessKey Secret。建議優先通過阿里雲 CLI 設定檔管理認證，Skill 會自動複用 CLI 的憑據配置。
本機已安裝 Python 3 運行環境，用於執行 Skill 內建的診斷呼叫指令碼。

支援的 Agent

alibabacloud-starops-chat Skill 基於開放的 Skill 規範構建，不綁定任何特定 Agent。主流編碼智能體均可直接安裝並使用該 Skill，例如：Qwen Code、Claude Code、Codex、Qoder、OpenClaw等等。

任何支援 Skill 規範的自建智能體同樣可以使用本 Skill。Skill 規範要求 Agent 具備以下能力：

1. 能夠解析 `SKILL.md` 描述檔案，擷取 Skill 的元資訊、指令和工具定義。

2. 支援通過 Bash 工具調用執行 Skill 內建指令碼。

3. 能夠按照 `SKILL.md` 中聲明的環境變數和憑據要求完成配置注入。

滿足以上條件的自建 Agent（如基於 LangChain、AutoGen、Dify 等架構搭建的智能體），只需將 Skill 檔案放置到其可識別的 skills 目錄下，即可載入並調用 STAROps 診斷能力。不支援 Skill 規範的智能體無法使用本 Skill。

安裝 Skill

alibabacloud-starops-chat 已在阿里雲 Skill和 ClawHub 發布，可參考其中的安裝引導進行安裝。

配置環境變數

Skill 通過以下三個環境變數定位目標數字員工與 Workspace。如執行平台未自動注入，需在調用前手動設定：

變數名	是否必選	說明	擷取方式
`STAROPS_AGENT_EMPLOYEE`	是	數字員工ID	STAROps 控制台 → 數字員工列表→ 數字員工ID
`STAROPS_AGENT_WORKSPACE`	是	Workspace 標識	CMS2.0 控制台 → 選擇Workspace
`STAROPS_AGENT_UID`	是	Workspace 所屬阿里雲帳號 UID	阿里雲控制台 → 帳號管理 → 帳號 ID
`STAROPS_AGENT_ENDPOINT`	否	自訂 Endpoint	預設：`starops.cn-beijing.aliyuncs.com`
`STAROPS_AGENT_REGION`	否	Region	預設 `cn-beijing`

export STAROPS_AGENT_EMPLOYEE="<數字員工 ID>"
export STAROPS_AGENT_WORKSPACE="<workspace 標識>"
export STAROPS_AGENT_UID="<阿里雲帳號 UID>"

配置憑據

Skill 使用阿里雲 Credentials SDK 預設鏈解析憑據，不需要配置 Skill 專屬的 AccessKey 變數。推薦通過阿里雲 CLI 配置憑據，Skill 自動複用。

方式一（推薦）：通過阿里雲 CLI 配置

如果本機尚未安裝阿里雲 CLI，請參考安裝阿里雲 CLI 完成安裝，然後執行以下命令配置憑據：

aliyun configure

按提示輸入 AccessKey ID、AccessKey Secret 和預設 Region ID。配置完成後憑據儲存在 ~/.aliyun/config.json 中，Skill 會自動讀取。

可通過以下命令驗證 CLI 配置是否生效：

aliyun sts GetCallerIdentity

如果返回帳號 UID 和身份資訊，說明憑據配置正確。

阿里雲 CLI 支援多種憑據模式，可通過 --mode 參數指定：

# AK 模式（預設）
aliyun configure --mode AK

# STS Token 模式（臨時憑據）
aliyun configure --mode StsToken

# RAM Role（ECS 執行個體角色）
aliyun configure --mode EcsRamRole

# RAM Role ARN（角色扮演）
aliyun configure --mode RamRoleArn

詳情參考配置與管理身份憑證。

方式二：通過環境變數配置

如果不使用阿里雲 CLI，也可以直接設定標準環境變數：

export ALIBABA_CLOUD_ACCESS_KEY_ID="<YOUR-ACCESS-KEY-ID>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<YOUR-ACCESS-KEY-SECRET>"

此方式適用於 CI / 臨時調試情境，生產環境不推薦。

方式三：其他憑據來源

Credentials SDK 預設鏈還支援以下來源（按優先順序從高到低）：

環境變數（ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET）
阿里雲 CLI 設定檔（~/.aliyun/config.json）
STS Token
RAM Role（ECS / 容器執行個體中繼資料）

本地開發環境如不需要執行個體中繼資料尋找，可設定 export ALIBABA_CLOUD_ECS_METADATA_DISABLED=true 避免不必要的逾時等待。

調用 STAROps Agent

安裝並配置完成後，在 Agent 中直接描述營運診斷需求即可觸發該 Skill。Agent 自動執行以下流程：

檢查環境變數與憑據鏈是否就緒。
調用 CreateThread 建立一次會話 Thread，返回 threadId 與 STAROps 控制台跳轉連結。
調用 CreateChat 發送使用者問題，訂閱 SSE 流式響應。
即時輸出工具調用狀態（[tool:started] / [tool:running] / [tool:done]）和診斷報告片段到 stderr。
在 stdout 輸出 === STAROPS ANSWER BEGIN === 與 === STAROPS ANSWER END === 之間的最終診斷結論。

首次調用時，Agent 會引導完成 Python 依賴安裝（pip3 install -r scripts/requirements.txt）和環境變數配置。

提示詞最佳實務

STAROps Agent 是一個長任務推理引擎，單次診斷可能持續數分鐘並觸發多個內部工具調用。提示詞的完整性直接決定診斷品質。建議在提示詞中包含以下資訊：

目標 Workspace 與服務名稱（或應用、組件、APM Service）。
明確的診斷意圖。例如"分析根因""列出可能影響面""給出止血建議"。
時間範圍。例如"最近 30 分鐘"或"2026-05-19 10:00 到 11:00，北京時間"。
已有線索（如警示內容、TraceID、錯誤關鍵詞、SLS Project / Logstore）。
期望決策。例如"是否需要擴容""是否復原發布""是否需要聯絡上遊"。

為保證 Thread 內容相關的連貫性，請遵循以下兩條硬性規則：

同一次排查的所有追問必須複用首次返回的 threadId。建立 Thread 會丟棄之前所有的診斷證據和中間結論。
呼叫指令碼必須始終帶 --pipe。否則輸出無 === STAROPS ANSWER BEGIN === 分隔字元，下遊無法穩定解析。

情境一：查詢 APM 服務數量

提示詞

當前 workspace 中有多少個 APM 服務

Agent 輸出樣本

當前 workspace rca-benchmark 中共有 49 個 APM 服務。

按語言分布概覽：

| 語言 | 數量 |
|------|------|
| Java | 最多（ad, fraud-detection, accounting 等） |
| Go | 多個（product-catalog, checkout 等） |
| Node.js | 多個（frontend, frontend-web 等） |
| .NET | 多個（cart, accounting 等） |
| Python / Rust / PHP / Ruby / C++ | 各若干 |

這些服務覆蓋了電商/金融情境的完整鏈路，包括 frontend、product-catalog、cart、
checkout、payment、shipping、fraud-detection 等核心微服務。

情境二：查看不同語言的服務分布

提示詞

幫我查看當前 workspace 下有哪些不同語言的服務

Agent 輸出樣本

當前 workspace rca-benchmark 下共有 49 個 APM 服務，按程式設計語言分類如下：

| 語言 | 服務數量 | 服務列表 |
|------|---------|---------|
| Java | 28 | ad, fraud-detection, inventory, loyalty, review, promotion, wishlist, notification, warehouse, risk-scoring, search, pricing, user-profile, refund, coupon, order, audit-trail, payment-router, ... |
| Golang | 3 | product-catalog, flagd, checkout |
| Node.js | 3 | frontend, payment, loadgenerator |
| .NET | 2 | cart, accounting |
| Python | 1 | recommendation |
| C++ | 1 | currency |
| Rust | 1 | shipping |
| PHP | 1 | quote |
| Ruby | 1 | email |
| WebJS | 1 | frontend-web |
| 未標註 | 2 | image-provider, frontend-proxy |

總計覆蓋 10 種程式設計語言，其中 Java 服務佔比最高（28 個），是主要的後端開發語言。

情境三：排查服務報錯根因

提示詞

幫我排查 inventory 服務報錯的根因是什麼

Agent 輸出樣本

## inventory 服務 5xx 報錯根因分析報告

### 結論

根因：inventory 服務調用下遊 notification 服務時發生逾時（5秒），導致級聯 5xx 錯誤。

### 證據鏈

#### 1. 調用鏈分析（Trace）

對 61 個錯誤 trace 進行診斷分析，所有錯誤均指向同一環節：

| 錯誤 Span | 服務 | 耗時 | 診斷結果 |
|-----------|------|------|----------|
| notification POST | notification | ~5000ms | error_and_slow |
| checkout orders publish | checkout | 1366-1927ms | slow |

調用鏈路徑：
frontend-proxy → frontend → checkout → inventory → notification (逾時 5s)

所有錯誤 trace 中，notification 服務的 POST 調用均耗時約 5000ms（達到逾時閾值），
statusCode=2 表示錯誤。

#### 2. 關聯警示

最近 30 分鐘觸發的相關警示：
- [Health Rule] latency_avg_threshold_critical (CRITICAL): checkout 服務平均耗時 3.6 秒
- frontend 介面響應慢警示 (CRITICAL): frontend 服務 POST 介面平均回應時間 > 1000ms
- 容器記憶體使用量率超過 85% (CRITICAL): kafka 容器記憶體使用量率 88.52%

#### 3. notification 服務資源狀態

| 指標 | 值 | 狀態 |
|------|-----|------|
| Pod 狀態 | Running | 正常 |
| 記憶體使用量/限制 | 66.6% | 正常 |
| 記憶體使用量/請求 | 133.2% | ⚠️ 超出請求值 |

### 可能原因

1. notification 服務下遊依賴異常：Kafka 容器記憶體使用量率偏高（88.52%）可能導致訊息處理延遲
2. notification 服務資源不足：記憶體使用量超過 request 值的 133%，可能在流量高峰時觸發 GC
3. 網路連接問題：inventory 到 notification 的網路連接可能存在延遲或串連池耗盡

### 止血建議

1. 檢查 notification 服務日誌和 Kafka 叢集狀態
2. 臨時擴容 notification 服務（增加 resources.limits.memory）
3. 在 inventory 服務中設定更合理的逾時時間和熔斷策略，避免級聯影響

情境四：基於診斷結論多輪追問

STAROps Skill 支援多輪互動。基於前一輪 Thread 持續追問，可逐步收斂排查範圍。

第一輪提示詞

幫我排查 inventory 服務報錯的根因是什麼

第二輪提示詞（沿用同一 thread）

針對剛才定位到的 notification 服務逾時，進一步看一下 notification 服務自身最近 30 分鐘的錯誤記錄檔，
確認是它自己的問題還是它下遊 Kafka 的問題。

第三輪提示詞（繼續下鑽）

Kafka 容器記憶體使用量率 88.52%，給出擴容建議和臨時止血方案。

複用同一 threadId 的多輪追問可讓 STAROps Agent 直接基於此前累積的工具調用結果（指標、Trace、日誌）繼續推理，避免重複掃描資料，也保持結論一致。

資料安全與隱私

STAROps Skill 通過阿里雲 OpenAPI 呼叫 STAROps 數字員工，過程遵循以下安全原則：

所有請求通過 HTTPS 與 ACS3-HMAC-SHA256 簽名傳輸；診斷資料不經過第三方服務。
憑據資訊（AccessKey、STS Token、RAM Role）通過阿里雲 Credentials 預設鏈解析，不會出現在 Agent 對話或指令碼輸出中。
Skill 僅建立診斷 Thread 與發送對話請求，不直接修改 ECS、OSS、RDS、SLS、RAM 等雲資源。STAROps Agent 給出的處置動作仍需走使用者日常的變更審批次程序。
當指令碼返回 401 / 403 鑒權錯誤時，Skill 會立即停止並報告給使用者，不會自動用其他憑據重試，也不會基於先驗知識偽造診斷結論。

使用限制

限制項	說明
任務時間長度	單次診斷預設任務逾時 30 分鐘；如長時間無 SSE 事件，Skill 會按 `--idle-timeout`（預設 60 秒）拋出 idle 錯誤。
資料來源	STAROps Agent 的診斷品質依賴 Workspace 中接入的 APM、SLS、UModel 資料；未接入或資料缺失的部分無法被分析。
資源管理	Skill 僅做推理與診斷，不直接執行 ECS / OSS / RDS / SLS / RAM 等資源變更操作。
運行環境	需要 Python 3，並已通過 `pip3 install -r scripts/requirements.txt` 安裝依賴。

常見問題

是否需要在控制台預先建立 Thread？

不需要。Skill 首次調用時會自動通過 CreateThread 建立會話 Thread，並列印 STAROPS_URL，可直接在 STAROps 控制台跳轉查看同一 Thread 的全部訊息與工具調用記錄。

如何配置阿里雲帳號憑據？

推薦通過阿里雲 CLI 配置憑據（執行 aliyun configure），Skill 會自動讀取 ~/.aliyun/config.json 中的憑據資訊。詳細步驟參見上方"配置憑據"章節。

如果使用其他憑據來源，優先順序從高到低為：

阿里雲 CLI 設定檔（~/.aliyun/config.json）：推薦方式，執行 aliyun configure 即可完成配置。
環境變數：設定 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET，適用於 CI / 臨時調試。
STS Token：由平台注入臨時憑據，適用於 CI / 沙箱環境。
RAM Role：ECS / 容器工作負載通過執行個體中繼資料擷取憑據。

是否支援自訂 Endpoint？

支援。設定環境變數 STAROPS_AGENT_ENDPOINT=<網域名稱> 即可指定專屬或私網 Endpoint。

診斷結果不夠具體怎麼辦？

可從以下方面最佳化：

在提示詞中補充服務名、時間範圍、TraceID、警示原文等關鍵證據。
檢查 Workspace 是否已接入 APM、SLS、UModel 資料來源；缺失資料來源會導致 STAROps Agent 無法擷取證據。
複用 --thread 進行多輪追問，讓 STAROps Agent 基於已有結論繼續下鑽，而不是重新發起新會話。
若 STAROps 返回 (No assistant answer was returned.) 或僅有泛化回答，可使用同一 thread 重試一次；若仍無結果，應如實告知使用者"STAROps 未返回有效診斷資料"，不要用先驗知識偽造結論。

故障排查

報錯 HTTP 401 Unauthorized

憑據鏈未解析到具備 STAROps 許可權的身份。

解決方案：

確認 Credentials 預設鏈能解析到 STS Token、RAM Role、CLI Profile 或執行個體中繼資料中至少一項。
確認該身份的 RAM 策略包含 starops:CreateThread 與 starops:CreateChat 許可權。
若使用 STS Token，確認 Token 未到期且被代入的角色包含上述許可權。
鑒權失敗時 Skill 會立即終止且不重試，需使用者授權後再重新發起請求。

報錯 HTTP 404 Not Found

數字員工名 / Workspace / UID 三者之一與實際不匹配。

解決方案：核對 STAROPS_AGENT_EMPLOYEE、STAROPS_AGENT_WORKSPACE 與 STAROPS_AGENT_UID 是否對應到同一組實際資源；其中 UID 必須是 Workspace 所屬帳號的主帳號 UID。

報錯 ConfigError: Missing required STAROps environment variables

STAROPS_AGENT_EMPLOYEE、STAROPS_AGENT_WORKSPACE、STAROPS_AGENT_UID 中存在未設定或為空白的變數。

解決方案：執行 SKILL.md 中的 pre-flight 檢查指令碼確認變數已設定，再重新調用。

報錯 CredentialError

阿里雲 Credentials SDK 未找到任何可用憑據源。

解決方案：推薦執行 aliyun configure 完成阿里雲 CLI 憑據配置，Skill 會自動讀取 ~/.aliyun/config.json。也可以通過環境變數、STS Token 或 RAM Role 提供憑據。本地開發環境若不需要執行個體中繼資料，可以設定 export ALIBABA_CLOUD_ECS_METADATA_DISABLED=true 減少逾時延遲。

報錯 Idle timeout

在 --idle-timeout 時間內未收到任何 SSE 事件，可能是 STAROps Agent 卡住。

解決方案：複用同一 --thread 重試一次；若屬於預期長時間靜默的複雜任務，可適當調大 --idle-timeout。

報錯 ModuleNotFoundError

Python 依賴未安裝。

解決方案：在 Skill 根目錄執行 pip3 install -r scripts/requirements.txt。注意依賴檔案位於 scripts/ 子目錄而非專案根目錄。

API 名稱	Action	Resource
CreateThread	`starops:CreateThread`	`acs:starops:<region>:<uid>:digitalemployee/<employee_name>`
CreateChat	`starops:CreateChat`	`acs:starops:<region>:<uid>:digitalemployee/<employee_name>`