alibabacloud-starops-chat

Alibaba Cloud STAROps Agent

通过 STAROps OpenAPI 调用 Alibaba Cloud STAROps Agent，并接收流式诊断回答。

场景说明

当用户希望执行以下操作时，请使用此技能：

• 诊断服务错误或异常（根因分析）
• 查询工作区拓扑、服务列表或服务指标
• 分析 APM 跟踪、错误率、延迟或请求量
• 对告警进行分类或调查事件
• 询问有关其 STAROps 工作区或服务的问题

配置

脚本从环境变量和可选的 JSON 配置文件中读取 STAROps 连接值。环境变量和命令行标志会覆盖配置文件中的值。

配置文件按以下顺序加载：

1. 用户配置：~/.starops/config.json
2. 项目配置：./.starops/config.json（覆盖用户配置）
3. 显式指定的配置：--config <path> 或 STAROPS_AGENT_CONFIG（覆盖用户／项目配置）

三个必需值（employeeId、workspace、uid）可以来自环境变量或配置文件。

变量	必需	说明
STAROPS_AGENT_EMPLOYEE	是，除非配置中提供 employeeId	STAROps 中的数字员工 ID（可在控制台 → 数字员工列表 → ID 列中查看）
STAROPS_AGENT_WORKSPACE	是，除非配置中提供 workspace	工作区标识符
STAROPS_AGENT_UID	是，除非配置中提供 uid	拥有该工作区的 Alibaba Cloud 账户 UID
STAROPS_AGENT_ENDPOINT	否	API 端点（默认值：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。

凭据使用 Alibaba Cloud Credentials 默认链。请勿定义技能专用的 AccessKey 变量；请使用标准 Alibaba Cloud 凭据来源，例如环境凭据（ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET）、配置文件、STS、RAM 角色或实例元数据。

调用

重要：所有调用都必须使用 --pipe 标志。 该标志可确保输出包含结构化内容，包括 THREAD ID、STAROPS_URL 和带分隔符的回答块，方便下游 Agent 可靠解析。切勿省略 --pipe。

安装依赖项，并从此技能的根目录运行：

pip3 install -r scripts/requirements.txt

# First call - creates a new thread automatically
python3 scripts/call_starops_agent.py --question "<complete user context>" --pipe

# First call with an explicit config file
python3 scripts/call_starops_agent.py --config ".starops/config.json" --question "<complete user context>" --pipe

# Follow-up calls - MUST reuse the thread ID from previous response
python3 scripts/call_starops_agent.py --thread "<thread_id>" --question "<follow-up question>" --pipe

线程管理：

• 从输出中提取线程 ID
• 用户需要在 STAROps 控制台中查看同一线程时，请使用输出的 STAROPS_URL
• 对相关的后续问题，始终传递 --thread "<id>" 以保留上下文

工作流示例：

# Query 1: Creates new 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 ===
...

# Query 2: MUST reuse thread for context
$ python3 scripts/call_starops_agent.py --thread "thread-abc123-xyz" --question "Deep dive into notification app errors" --pipe

命令行选项

标志	描述
--question <text>	必填。 要发送给 STAROps Agent 的自然语言问题。
--thread <id>	现有 STAROps 线程 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）。

行为说明

1. STAROps Agent 调用按设计需要长时间运行。单个 CreateChat 流可能会启动多个内部诊断步骤，并耗时数分钟；默认超时时间为 30 分钟。
2. 在一个问题中提供完整上下文：云账户或工作区上下文、时间范围、服务或应用名称、告警文本、SLS 项目/日志库、UModel 对象、地域，以及用户需要做出的决策。
3. 重要：在同一项调查中，后续问题始终复用 --thread。启动新线程会丢弃所有先前的上下文和发现。
4. 使用此技能进行 Agent 推理和诊断，而非直接管理资源。对于直接修改 ECS、OSS、RDS、SLS 或 RAM 资源的操作，请使用相应的官方 CLI、SDK 或专用技能。
5. 必须：始终传入 --pipe。 工具调用状态和流式诊断报告片段会写入 stderr，而 stdout 会保留可复用的线程 ID 和最终答案，便于解析。省略 --pipe 会产生无法可靠评估的非结构化输出。
6. 如果一段时间内没有收到 SSE 事件，脚本会清楚地报告空闲超时错误，而不是默默等待任务超时。只有在预期调查会长时间没有活动时，才增加 --idle-timeout。
7. 输出完整性规则：最终报告必须基于 === STAROPS ANSWER BEGIN === 与 === STAROPS ANSWER END === 之间实际返回的内容。具体来说：
   • 引用或转述 STAROps 响应中的具体数据点（HTTP 状态码、服务名称、错误路径、指标）。
   • 不要推断或编造 STAROps 输出未支持的诊断结论。
   • 如果 STAROps 的回答为空（(No assistant answer was returned.)）、不完整，或只包含泛泛的内容，请使用相同的 --thread 重试一次。如果重试仍未返回可采取行动的数据，请如实报告：“STAROps 未返回可采取行动的诊断数据。请确认工作区中存在与所请求时间范围相关的服务和数据。”
   • 绝不要用你自己的先验知识替代缺失的 STAROps 证据。例如，如果 STAROps 未提及“数据库连接池耗尽”，就不要声称存在此问题。

可观测性

所有 STAROps OpenAPI HTTP 请求都必须使用以下 User-Agent 模板声明：

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

对于此技能，具体模板为：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id}

每次技能调用只生成一个 session-id，其值为 32 位十六进制数。如果已设置 SKILL_SESSION_ID，验证其为 32 位十六进制数后复用该值；否则生成 uuid4().hex，设置 SKILL_SESSION_ID，并将其用于所有出站调用。在本次调用期间，通过 CLI/SDK/Terraform 发出的请求与直接 HTTP 请求（包括 CreateThread 和 CreateChat）必须使用相同的 session-id；不要为每个请求生成新的 session-id。Python 脚本会将 HTTP User-Agent 标头设置为 AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id}。

故障排除

脚本退出并报错时，请按以下顺序检查：

1. HTTP 401 Unauthorized — 凭证链未能解析出具有 STAROps 权限的有效身份。请确认已设置 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET（或 STS / RAM 角色），并且该身份具有 starops:CreateThread 和 starops:CreateChat 权限。请参阅 references/ram-policies.md。
2. HTTP 404 Not Found — Digital Employee ID（STAROPS_AGENT_EMPLOYEE）或工作空间（STAROPS_AGENT_WORKSPACE）不存在，或者 UID（STAROPS_AGENT_UID）与所属账号不匹配。请仔细检查这三个环境变量。
3. ConfigError: Missing required STAROps configuration values — 环境变量和配置文件中都缺少 employeeId、workspace 或 uid 中的一个或多个值。
4. CredentialError — Alibaba Cloud Credentials SDK 未能找到任何有效的凭证来源。请确保至少配置了一个凭证提供方（环境变量、~/.aliyun/config.json、STS、RAM 角色或实例元数据）。
5. 空闲超时 — 在 --idle-timeout 秒内（默认值为 60）未收到 SSE 事件。STAROps Agent 可能已停滞。如果已打印 THREAD 行，请使用相同的 --thread 重试；对于预期会静默运行的调查任务，请增大 --idle-timeout。
6. 流中断 / 网络错误 — HTTPS 连接已重置或超时。请使用 --thread 重试相同的请求，以恢复上下文。
7. ModuleNotFoundError — 尚未安装 Python 依赖项。调用脚本前请运行 pip3 install -r scripts/requirements.txt。

API 接口

此技能直接调用 STAROps OpenAPI：

• CreateThread：POST /digitalEmployee/{employeeId}/thread
• CreateChat：POST /chat

请参阅 references/api-reference.md 和 references/ram-policies.md。