STAROps Skill 集成

配置凭据

Skill 使用阿里云 Credentials SDK 默认链解析凭据，不需要配置 Skill 专属的 AccessKey 变量。推荐通过阿里云 CLI 配置凭据，Skill 自动复用。

aliyun configure

aliyun sts GetCallerIdentity

# 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

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

提示词最佳实践

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、日志）继续推理，避免重复扫描数据，也保持结论一致。

是否需要在控制台预先创建 Thread？

不需要。Skill 首次调用时会自动通过 CreateThread 创建会话 Thread，并打印 STAROPS_URL，可直接在 STAROps 控制台跳转查看同一 Thread 的全部消息与工具调用记录。

如何配置阿里云账号凭据？

推荐通过阿里云 CLI 配置凭据（执行 aliyun configure），Skill 会自动读取 ~/.aliyun/config.json 中的凭据信息。详细步骤参见上方"配置凭据"章节。

如果使用其他凭据来源，优先级从高到低为：

1. 阿里云 CLI 配置文件（~/.aliyun/config.json）：推荐方式，执行 aliyun configure 即可完成配置。

2. 环境变量：设置 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET，适用于 CI / 临时调试。

3. STS Token：由平台注入临时凭据，适用于 CI / 沙箱环境。

4. 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/ 子目录而非项目根目录。