alibabacloud-oos-chatops-agent

阿里云 OOS ChatOps Agent

向 OOS ChatOps Agent 发送自然语言问题，并通过 SSE 接收流式运维答复。

适用场景

• 查询云资源（ECS、RDS、VPC、SLB、安全组等）
• 执行资源操作（启动、停止、重启、扩容）
• 查看监控数据、账单或资源健康状况
• 通过自然语言执行批量运维任务
• 常规阿里云资源管理问题

配置

凭证使用阿里云凭证默认链。请勿定义技能专用的 AccessKey 变量；请使用标准凭证来源，例如环境变量（ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET）、配置文件（~/.aliyun/config.json）、STS、RAM 角色或实例元数据。

变量	必填	描述
OOS_CHATOPS_REGION	否	资源查询的目标地域（默认：cn-hangzhou）
OOS_CHATOPS_TIMEOUT	否	超时时间，单位为秒（默认：300）

预检：

missing=""
[ -z "$ALIBABA_CLOUD_ACCESS_KEY_ID" ] && missing="$missing ALIBABA_CLOUD_ACCESS_KEY_ID"
[ -z "$ALIBABA_CLOUD_ACCESS_KEY_SECRET" ] && missing="$missing ALIBABA_CLOUD_ACCESS_KEY_SECRET"
if [ -n "$missing" ]; then echo "ERROR: Missing credentials:$missing" >&2; exit 1; fi
echo "OK: Credentials configured"

凭证安全限制：

• 绝不运行 cat ~/.aliyun/config.json、env、printenv、echo $ALIBABA_CLOUD_*，或任何会将完整凭证值输出到 stdout/stderr/日志的命令。
• 调试凭证问题时，只能输出脱敏提示（例如 LTAI5t****）。任何输出中都绝不能出现完整的 AK/SK/Token 值。
• 如果凭证不可用，请让用户配置标准阿里云凭证链。绝不能用占位符代替。

调用

[绝对规则] 工具白名单：对于所有云资源查询、运维操作和资源管理任务，唯一允许使用的工具是 scripts/call_oos_chatops_agent.py。任何涉及阿里云资源的场景——包括但不限于 ECS、RDS、SLB、VPC、安全组、监控、账单和批量操作——都必须且只能通过此脚本调用。如果检测到 aliyun CLI、直接 SDK 调用、curl 或任何其他 API 工具，则立即判定任务失败。

所有 Agent 调用都必须使用 --pipe。

pip3 install -r scripts/requirements.txt

# First call (auto-creates conversation)
python3 scripts/call_oos_chatops_agent.py -q "<user question>" --pipe

# Follow-up (MUST reuse ConversationId)
python3 scripts/call_oos_chatops_agent.py --session "<conversation_id>" -q "<follow-up>" --pipe

# Custom region
python3 scripts/call_oos_chatops_agent.py -q "<query>" --region cn-beijing --pipe

# Long-running operations
python3 scripts/call_oos_chatops_agent.py -q "<complex query>" --timeout 600 --pipe

输出格式（PIPE 模式）

CONVERSATION: 04c7922a-86c7-4d11-8b97-96e22662c7f3
=== OOS CHATOPS ANSWER BEGIN ===
(actual answer content)
=== OOS CHATOPS ANSWER END ===

输出解析与验证

处理脚本输出时，必须严格遵守以下规则：

1. 唯一事实来源：只有 === OOS CHATOPS ANSWER BEGIN === 和 === OOS CHATOPS ANSWER END === 之间的文本才是事实答复。这些分隔符之外的所有内容都是元数据或进度信息。
2. 不得臆造数量：如果需要报告资源数量（例如“53 个 ECS 实例”），数字必须来自分隔符之间的文本。绝不能估算，也不能依据已有知识编造数字。
3. 报告前自检：向用户提供最终答复前，请确认每个数据点（实例 ID、数量、状态）都能直接追溯到分隔符内的文本。如果 OOS 答复中写着“53 个实例”，但你无法在文本中找到这个数字，就不要报告。
4. 优先逐字转述：如有疑问，请直接引用 OOS 答复，而不要改写。改写会增加产生幻觉的风险。

对话管理

1. 必须在每次调用后从输出中提取 CONVERSATION: <id> 并立即记录
2. 必须在同一上下文中的所有后续查询中传入 --session "<id>"。省略 --session 即为失败
3. 开始新对话会丢失此前的所有上下文
4. 出现错误或响应为空时：必须使用相同的 --session 重试一次。连续失败两次后，如实向用户说明错误详情。绝不能编造结果，也不能悄然中断对话

示例：

# Query 1
$ python3 scripts/call_oos_chatops_agent.py -q "List ECS instances in Hangzhou" --pipe
CONVERSATION: 04c7922a-86c7-4d11-8b97-96e22662c7f3
=== OOS CHATOPS ANSWER BEGIN ===
53 ECS instances found...
=== OOS CHATOPS ANSWER END ===

# Query 2: reuse conversation
$ python3 scripts/call_oos_chatops_agent.py --session "04c7922a-86c7-4d11-8b97-96e22662c7f3" -q "Show cn-beijing instances" --pipe

命令行选项

标志	描述
-q, --question	必填。 自然语言问题或命令。
--session <id>	多轮对话使用的 ConversationId。后续提问必填。
--region <region>	资源查询的目标区域（默认值：cn-hangzhou）。
--timeout <seconds>	SSE 流超时时间（默认值：300）。
--no-retry	禁用自动重试（默认最多重试 2 次）。
--pipe	必填。 使用分隔符输出结构化结果。
--json	JSONL 输出。与 --pipe 互斥。

行为规则

1. 仅通过脚本执行：所有云资源交互都必须通过 python3 scripts/call_oos_chatops_agent.py 进行。即使环境中有 aliyun CLI，也必须忽略。没有例外。
2. 提供完整上下文：在一个问题中包含区域、资源 ID、时间范围和所需操作。
3. 后续提问始终复用 --session。 新建对话会丢失上下文。
4. 确保输出完整性：仅报告 BEGIN/END 分隔符之间的内容。不得捏造数据。
5. 响应为空：使用相同的 --session 重试一次。如果仍为空，如实报告。
6. 长时间操作：批量操作或全面检查时使用 --timeout 600。
7. 显式传递参数：当用户或任务指定区域、超时时间或其他参数时，必须显式传递相应标志（例如 --region cn-hangzhou、--timeout 600）。绝不能依赖脚本内置默认值。遗漏明确指定的参数会被视为调用失败。

故障排除

错误	解决方法
CredentialError	设置 ALIBABA_CLOUD_ACCESS_KEY_ID 和 SECRET，或配置 ~/.aliyun/config.json
OOSChatTimeoutError	增加 --timeout
OOSChatError	检查 RAM 权限：oos:Chat。参见 references/ram-policies.md
响应为空	使用相同的 --session 重试，或在问题中补充更多上下文
ModuleNotFoundError	运行 pip3 install -r scripts/requirements.txt

可观测性

所有 OOS Chat API HTTP 请求都携带用于追踪的 User-Agent 标头：

AlibabaCloud-Agent-Skills/alibabacloud-oos-chatops-agent/{session-id}

• alibabacloud-oos-chatops-agent — 固定的技能标识符（与 frontmatter 中的 name 字段相匹配）。
• {session-id} — 一个 32 位十六进制字符串，取自 SKILL_SESSION_ID 环境变量。如果未设置，脚本会生成 uuid.uuid4().hex。同一次调用中的所有请求共用同一个 session-id，以便在服务端日志中关联 API 调用。

每次技能调用只生成一个 session-id。如果已设置 SKILL_SESSION_ID，验证其为 32 位十六进制字符后复用该值；否则，通过 uuid4().hex 生成新值，并在本次调用期间设置该值。