阿里云skills阿里云 STAROps Agent
通过 STAROps OpenAPI 调用阿里云 STAROps Agent，并接收流式诊断回答。
场景描述
当用户想要以下操作时使用本 Skill：
- 诊断服务错误或异常（根因分析）
- 查询 workspace 拓扑、服务列表或服务指标
- 分析 APM 链路、错误率、延迟或请求量
- 分诊告警或排查事件
- 询问其 STAROps workspace 或服务相关问题
配置
脚本从环境变量和可选 JSON 配置文件读取 STAROps 连接值。环境变量和命令行 flag 覆盖配置文件值。
配置文件按以下顺序加载：
- 用户配置：
~/.starops/config.json - 项目配置：
./.starops/config.json（覆盖用户配置） - 显式配置：
--config <path>或STAROPS_AGENT_CONFIG（覆盖用户/项目配置）
三个必需值（employeeId、workspace、uid）可来自环境变量或配置文件。
| 变量 | 必填 | 说明 |
|---|---|---|
STAROPS_AGENT_EMPLOYEE | 是，除非配置提供 employeeId | STAROps 中的数字员工 ID（来自控制台 → 数字员工列表 → ID 列） |
STAROPS_AGENT_WORKSPACE | 是，除非配置提供 workspace | Workspace 标识符 |
STAROPS_AGENT_UID | 是，除非配置提供 uid | 拥有该 workspace 的阿里云账号 UID |
STAROPS_AGENT_ENDPOINT | 否 | API endpoint（默认：starops.cn-beijing.aliyuncs.com） |
STAROPS_AGENT_PROJECT | 否 | 随每个请求转发的可选 STAROps 项目变量。被 --project 覆盖 |
STAROPS_AGENT_TIMEOUT | 否 | --timeout 的默认值（CreateChat 流总超时秒数；默认 1800） |
STAROPS_AGENT_IDLE_TIMEOUT | 否 | --idle-timeout 的默认值（等待下一个 SSE 事件的最大秒数；默认 60） |
STAROPS_AGENT_CONFIG | 否 | 在用户/项目配置之后加载的显式 JSON 配置文件路径 |
最小配置文件示例：
{
"employeeId": "<your-digital-employee-id>",
"workspace": "<your-workspace-name>",
"uid": "<your-alibaba-cloud-account-uid>"
}可选字段：
{
"endpoint": "starops.cn-beijing.aliyuncs.com",
"project": "optional-project",
"timeout": 1800,
"idleTimeout": 60
}配置文件使用上面显示的精确键名。不要使用 employee、digitalEmployeeId、workspaceName 或 accountUid 等替代别名。
预检——调用脚本前运行此命令确认环境或配置值可用：
missing=""
[ -z "$STAROPS_AGENT_EMPLOYEE" ] && missing="$missing STAROPS_AGENT_EMPLOYEE"
[ -z "$STAROPS_AGENT_WORKSPACE" ] && missing="$missing STAROPS_AGENT_WORKSPACE"
[ -z "$STAROPS_AGENT_UID" ] && missing="$missing STAROPS_AGENT_UID"
config_file_found=""
[ -f ".starops/config.json" ] && config_file_found=1
[ -f "$HOME/.starops/config.json" ] && config_file_found=1
[ -n "$STAROPS_AGENT_CONFIG" ] && [ -f "$STAROPS_AGENT_CONFIG" ] && config_file_found=1
if [ -n "$missing" ] && [ -z "$config_file_found" ]; then
echo "ERROR: Missing required environment variables:$missing and no STAROps config file was found" >&2
exit 1
fi
echo "OK: STAROps configuration is available from environment variables or config file"如果任何必需值仍不可用，请用户提供。绝不要用 example-employee 之类的占位字符串替代。
STAROps 控制台链接使用与 assistantId 相同的数字员工 ID。
凭证使用阿里云凭证默认链。不要定义 Skill 专用的 AccessKey 变量；使用标准阿里云凭证来源，例如环境凭证（ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET）、profile、STS、RAM 角色或实例元数据。
调用
重要：所有调用都必须带 --pipe flag。 它确保结构化输出，包含 THREAD ID、STAROPS_URL 和分隔的回答块，下游 agent 可可靠解析。绝不省略 --pipe。
安装依赖并从本 Skill 根目录运行：
pip3 install -r scripts/requirements.txt
首次调用——自动创建新 thread
python3 scripts/call_starops_agent.py --question "<complete user context>" --pipe
首次调用并指定显式配置文件
python3 scripts/call_starops_agent.py --config ".starops/config.json" --question "<complete user context>" --pipe
后续调用——必须复用之前响应中的 thread ID
python3 scripts/call_starops_agent.py --thread "<thread_id>" --question "<follow-up question>" --pipe
**Thread 管理：**
- 从输出中提取 thread ID
- 当用户需要在 STAROps 控制台检查同一 thread 时，使用打印的 `STAROPS_URL`
- 相关后续问题始终传 `--thread "<id>"` 以保留上下文
示例工作流：查询 1：创建新 thread
$ python3 scripts/call_starops_agent.py --question "Query TOP 5 error applications" --pipe
THREAD: thread-abc123-xyz
STAROPS_URL: https://starops.console.aliyun.com/chat?threadId=thread-abc123-xyz&assistantId=apsara-ops
=== STAROPS ANSWER BEGIN ===
...
查询 2：必须复用 thread 以保留上下文
$ python3 scripts/call_starops_agent.py --thread "thread-abc123-xyz" --question "Deep dive into notification app errors" --pipe
命令行选项
| Flag | 说明 |
|---|---|
--question <text> | 必填。 发送给 STAROps Agent 的自然语言问题。 |
--thread <id> | 现有 STAROps thread ID。后续问题必填，以保留排查上下文。 |
--pipe | Agent 调用必填。 输出结构化内容，含 THREAD、STAROPS_URL 和 === STAROPS ANSWER BEGIN/END === 分隔符，便于可靠解析。 |
--json | 输出机器可读 JSONL 事件。与 --pipe 互斥。不要用于 Agent 调用——--pipe 是受支持的 Agent 格式。 |
--config <path> | 可选 JSON 配置文件。在 ~/.starops/config.json 和 ./.starops/config.json 之后加载。 |
--project <name> | 可选 STAROps 项目变量。覆盖 STAROPS_AGENT_PROJECT。 |
--timeout <seconds> | CreateChat 流总超时秒数。覆盖 STAROPS_AGENT_TIMEOUT（默认 1800）。 |
--idle-timeout <seconds> | 等待下一个 SSE 事件失败前的最大秒数。覆盖 STAROPS_AGENT_IDLE_TIMEOUT（默认 60）。 |
行为说明
- STAROps Agent 调用按设计是长时间运行的。单个
CreateChat流可能启动多个内部诊断步骤并耗时数分钟；默认超时 30 分钟。 - 在一个问题中提供完整上下文：云账号或 workspace 上下文、时间范围、服务或应用名称、告警文本、SLS project/logstore、UModel 对象、地域，以及用户需要什么决策。
- 关键：同一排查中的后续问题始终复用
--thread。启动新 thread 会丢弃所有先前上下文和发现。 - 本 Skill 用于 Agent 推理和诊断，而非直接资源管理。对于直接 ECS、OSS、RDS、SLS 或 RAM 变更，使用相应官方 CLI、SDK 或专用 skill。
- 强制：始终传
--pipe。 工具调用状态和流式诊断报告块写入 stderr，而 stdout 保留可复用的 thread ID 和最终回答，便于解析。省略--pipe会产生无法可靠评测的非结构化输出。 - 如果一段时间内没有 SSE 事件到达，脚本会以清晰的 idle-timeout 错误失败，而非静默等待完整任务超时。仅在排查预期长时间安静时增加
--idle-timeout。 - 输出完整性规则：你的最终报告必须基于
=== STAROPS ANSWER BEGIN ===和=== STAROPS ANSWER END ===之间返回的实际内容。具体而言：
- 引用或转述 STAROps 响应中的具体数据点（HTTP 状态码、服务名、错误路径、指标）。
- 不要推断或捏造 STAROps 输出不支持的诊断结论。
- 如果 STAROps 回答为空（
(No assistant answer was returned.)）、不完整或仅含通用文本，用同一--thread重试一次。如果重试仍无可用数据，如实报告：“STAROps 未返回可操作的诊断数据。请确认 workspace 包含所请求时间范围的相关服务和数据。” - 绝不要用你自己的先验知识替代缺失的 STAROps 证据。例如，如果 STAROps 未提及，不要声称“数据库连接池耗尽”。
可观测性
所有 STAROps OpenAPI HTTP 请求必须使用此 User-Agent 模板声明：
--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}对于本 Skill，具体模板为：
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id}每次 Skill 调用恰好生成一个 session-id，为 32 位十六进制值。如果 SKILL_SESSION_ID 已设置，验证其为 32 位十六进制字符后复用；否则生成 uuid4().hex，设置 SKILL_SESSION_ID，并在所有出站调用中复用它。同一 session-id 必须在调用期间的所有 CLI/SDK/Terraform 和直接 HTTP 请求中保持一致，包括 CreateThread 和 CreateChat；不要为每个请求生成新 session-id。Python 脚本将 HTTP User-Agent header 设置为 AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id}。
故障排查
脚本以错误退出时，按顺序检查以下内容：
- HTTP 401 Unauthorized —— 凭证链未解析为具有 STAROps 权限的有效身份。验证
ALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET（或 STS / RAM 角色）已设置，且身份具有starops:CreateThread和starops:CreateChat权限。见 references/ram-policies.md。 - HTTP 404 Not Found —— 数字员工 ID（
STAROPS_AGENT_EMPLOYEE）或 workspace（STAROPS_AGENT_WORKSPACE）不存在，或 UID（STAROPS_AGENT_UID）与拥有账号不匹配。仔细检查三个环境变量。 - ConfigError: Missing required STAROps configuration values ——
employeeId、workspace或uid中一个或多个在环境变量和配置文件中都缺失。 - CredentialError —— 阿里云凭证 SDK 找不到任何有效凭证来源。确保至少配置了一个凭证提供者（环境变量、
~/.aliyun/config.json、STS、RAM 角色或实例元数据）。 - Idle timeout —— 在
--idle-timeout秒（默认 60）内未收到 SSE 事件。STAROps Agent 可能已停滞。如果已打印 THREAD 行，用同一--thread重试，或为预期安静的排查增加--idle-timeout。 - 流中断 / 网络错误 —— HTTPS 连接被重置或超时。用
--thread重试同一请求以恢复上下文。 - ModuleNotFoundError —— Python 依赖未安装。调用脚本前运行
pip3 install -r scripts/requirements.txt。
API 接口
本 Skill 直接调用 STAROps OpenAPI：
CreateThread：POST /digitalEmployee/{employeeId}/threadCreateChat：POST /chat
◯ 评论 0