alibabacloud-flink-sql-skill

Alibaba Cloud Flink SQL 技能

此技能通过统一的 CLI，涵盖 Flink SQL 作业的完整生命周期，包括需求分析、SQL 编写、验证、部署、运维、性能评估和故障排查。

快速入口

• 统一命令：python3 scripts/flink_sql_manager.py <command> [args...]。
• 优先使用此技能自带的脚本和参考文档。仅当本地未涵盖所需的工作区操作，或文档所述的本地流程失败时，才回退使用 alibabacloud-flink-workspace-ops；先确认该技能已加载，否则请告知用户安装该技能。
• 进行云端调用前，请阅读 references/manifest.json，并按照 references/configuration.md 中的说明初始化 SKILL_SESSION_ID。缺少或无效的身份数据会阻止云端请求。
• 开始多步骤任务前，请阅读 references/lifecycle.md。
• 进行首次 Ververica OpenAPI 调用前，请按照 references/configuration.md 检查配置，并可选择初始化 Git。
• 仅阅读当前阶段所需的参考文档；不要一次性加载所有文档。
• 如果无法实际运行平台命令，请说明缺少的前置条件，并提供尚待运行的完整命令。切勿将示例命令描述为已执行。

单一生命周期

从用户当前所处的阶段进入，并沿同一生命周期继续：

1. 需求和数据契约：定义计算目标、输入和输出、正确性约束以及运行时要求。
2. SQL 编写和静态审查：将数据契约转化为完整 SQL，并检查语义、配置和版本兼容性。
3. 配置检查和云端验证：确认目标环境、身份和元数据，并在云端环境中验证 SQL。
4. 草稿和部署：维护 Drafts 和 Deployment 资源，同时确保 SQL、配置和已部署版本保持一致。
5. 启动和验收：按照所需的恢复行为启动 Job，并验证其运行状态和用户要求的验收标准。
6. 运维和变更：管理运行中的 Job 实例、状态和配套资源，并通过回读验证安全地完成变更。
7. 性能评估和故障排查：评估运行时行为，根据证据定位瓶颈或故障，并提出处理建议。

仅完成用户目标所需的阶段。未经授权，不要部署、启动、停止或删除资源。有关命令顺序，请参阅 references/lifecycle.md。

平台配置门槛

执行任何 Ververica OpenAPI 操作前，先运行：

python3 scripts/flink_sql_manager.py config_doctor

如果缺少工作区、命名空间或区域，请遵循 references/configuration.md：仅询问缺失的实际范围，并在同一次 config_init 调用中保存用户可选的 Git 设置。初始化后再次运行 config_doctor。只有当它以代码 0 退出并明确报告成功时，才能继续执行云端操作。出现任何其他结果（包括未确认的结果）时，停止后续平台命令，处理实际错误，然后再次运行检查。

对于仅限本地的 SQL 设计、编写或说明，应完成当前阶段，不要因平台配置而受阻。进入云端验证或任何后续阶段时，再应用此门槛。

历史指标使用单独的 Cookie 身份验证，不受 SDK 凭据检查的限制。

始终使用实际资源标识符。如果缺少工作区、命名空间或区域，请使用上述首次初始化流程。如果缺少 Draft ID、Deployment ID 或 Job ID，请从用户提供的信息或只读查询中获取。切勿使用占位 ID 调用 API。除用户提供的历史指标 Cookie 外，不接受 AccessKey ID、AccessKey Secret、令牌或密码。切勿回显或提交凭据。

安全门槛

CLI 要求每条变更命令都带上 --confirm。Agent 还必须遵循以下风险规则：

• 只读：范围明确且 config_doctor 检查成功后，可直接执行。
• 一般变更：创建、更新、验证后部署、启动、注册及类似操作。明确要求执行该操作即表示已获授权；在命令中添加 --confirm。询问可选方案不构成授权。
• 高风险：所有 stop_* 和 delete_* 命令、任何包含停止操作的重启或部署流程，以及 DROP 或 TRUNCATE 等破坏性 execute_sql 语句。仅提出操作请求，不构成对高风险操作的预先确认。如果当前请求明确确认了高风险操作及其影响，且只读查询解析出的实际目标和策略仍在已确认范围内，则报告解析出的目标，并使用 --confirm 执行 CLI，无需再次询问。否则，使用 references/output-schemas.md 重述目标、影响、策略或不可逆后果以及完整命令，然后等待明确确认。

确认（包括预先确认）仅适用于当前请求中的操作和目标。如果匹配到多个目标、范围发生变化，或策略存在实质性歧义，则只询问缺失的信息，不得沿用已有确认。命令失败后，停止执行依赖该命令的后续步骤。切勿捏造 ID、工单、状态或成功结果。

自动 Git 后处理仅在已获授权且成功的 Deployment 变更后执行；它本身不构成对平台变更的授权。Git 操作失败不会回滚平台结果。完整规则请参阅 references/git-sync.md。

按阶段查阅

• 生命周期、部署、更新、启动/停止、验收和故障排查顺序：references/lifecycle.md
• 配置、OAuth、默认凭据链和区域：references/configuration.md
• Git 配置、自动触发器、制品格式和仓库保护：references/git-sync.md
• Agent 执行、安全、失败时停止和报告约束：references/execution-protocol.md
• 高风险确认与验证、部署、启动/停止、诊断和失败结果的模板：references/output-schemas.md
• CLI 命令目录：references/command-reference.md
• 回读和异步结果验证：references/verification.md
• 错误分类和恢复：references/error-handling.md
• RAM 和敏感变量：references/ram-policies.md
• 性能评估和故障排查：references/diagnosis/README.md
• Draft、Deployment、Job、Session Cluster 等资源之间的关系：references/product-model.md
• OpenAPI 映射：references/related-apis.md
• SQL 主题索引：references/sql/README.md

SQL 来源优先级

1. 用户提供的实际架构、SQL、错误、引擎版本和平台响应。
2. 与目标 VVR 版本匹配的 Alibaba Cloud Realtime Compute for Apache Flink 文档。
3. 与相应 Flink 版本匹配的 Apache Flink 文档。
4. references/sql/README.md 下附带的离线参考资料。

用户询问最新行为、在线支持范围或当前 Connector 选项时，请查阅当前官方在线文档。仅凭离线参考资料无法证明平台当前的行为。

输出关卡

在报告平台查询、诊断、操作结果或操作确认之前，请在当前轮次阅读 references/output-schemas.md，严格遵循适用模板，并在发送前核对其字段名称、顺序和必填字段。合并各阶段的结果；高风险确认仍须在操作前进行。

每项结论都必须基于实际命令输出和回读证据。发生失败时，请说明失败阶段、关键错误、已完成和未执行的步骤，以及下一项可执行的恢复操作。不得将已受理的请求、超时、部分完成或未经确认的状态描述为成功完成。

开发与评估

• Agent 评估使用 bash evals/run_skill_up.sh；eval.yaml 和测试用例均使用 Skill Up v1alpha1，并生成 JSON 和 HTML 报告。
• 仅在获得授权时，使用 python3 tests/live_api_e2e.py 运行实时端到端测试。请先显式设置 RUN_LIVE_FLINK_E2E=1，初始化 SKILL_SESSION_ID，并使用测试工作区。