本文档面向希望在 Trae、Claude Code、OpenClaw、Codex 等 AI Agent 中使用 Volcano Serverless Flink 的用户，说明如何安装 volc-flink CLI、安装 byted-serverlessflink-volc-flink Skill，并通过自然语言完成 Flink SQL、JAR、CDC 任务开发、任务运维、异常诊断和资源池分析。

1. 概述 #

byted-serverlessflink-volc-flink 是围绕 volc-flink CLI 构建的 Agent Skill。它不会替代 CLI，而是让 Agent 能够理解用户意图、选择合适的子 Skill、组织 CLI 命令、解析 JSON 输出，并把结果总结成可执行建议。

典型能力包括：

• CLI 安装、版本检查、命令发现和 schema 查询。
• 登录状态、Profile、Project、Catalog、资源池等上下文检查。
• Flink SQL、Flink JAR、Flink CDC、Batch SQL/JAR 草稿创建、更新、校验、发布和启动。
• Job 查询、启动、停止、重启、扩缩容、删除，以及 Session 集群操作。
• Job Instance、事件、日志、Pod、指标查询。
• 失败根因诊断、性能分析和资源池容量观察。

Skill 的总入口是 byted-serverlessflink-volc-flink，它会根据意图路由到不同子 Skill：

工作原则 #

• Agent 通过 volc-flink command list --output json 和 volc-flink schema <command.id> --output json 确认当前 CLI 能力。
• 默认使用 --output json 便于解析；日志跟随场景使用 --output ndjson。
• 涉及发布、启动、停止、重启、删除、扩缩容等变更动作时，Agent 应先说明目标和影响，再获取确认。
• 登录命令由用户本地执行，Agent 不应在对话中索要或展示 AK/SK、Token 等敏感信息。

2. CLI 安装 #

2.1 安装 Flink Cli 工具 #

推荐方式：

npm install -g @volcflink/volc-flink
volc-flink --version
volc-flink --help

更多 Cli 的安装文档可以参考 火山 Flink Cli 工具。

2.2 初始化登录和项目上下文 #

安装后先检查 CLI 可用性：

volc-flink --version
volc-flink command list --output json

登录由用户在本机执行，需要按照指引输入火山 Flink 的 Region、AK、SK、项目等认证信息：

# 登录火山 Flink 平台
volc-flink auth login
# 检验登录状态
volc-flink auth status --output json

3. Skill 安装 #

Skill 页面，支持火山 Find Skill 平台进行安装。

3.1 在 Trae 中使用 #

建议使用安装脚本安装 Flink Skill ：

npx skills add https://skills.volces.com/skills/volcengine/serverlessflink -s byted-serverlessflink-volc-flink --agent trae

另外，Trae 支持 Agent / Skill / MCP 类扩展时，可以通过 FindSkills MCP 搜索并下载安装 byted-serverlessflink-volc-flink。安装后请确保 Trae 的运行环境 PATH 中可以访问 volc-flink。

3.2 在 Claude Code 中使用 #

建议使用安装脚本安装 Flink Skill ：

npx skills add https://skills.volces.com/skills/volcengine/serverlessflink -s byted-serverlessflink-volc-flink --agent claude-code

使用示意图：

3.3 在 Codex 中使用 #

建议使用安装脚本安装 Flink Skill ：

npx skills add https://skills.volces.com/skills/volcengine/serverlessflink -s byted-serverlessflink-volc-flink --agent codex

使用示意图

3.4 在 OpenClaw 中使用 #

建议使用安装脚本安装 Flink Skill ：

npx skills add https://skills.volces.com/skills/volcengine/serverlessflink -s byted-serverlessflink-volc-flink --agent openclaw

3.5 安装后验证 #

在任意 Agent 中让它执行或指导执行：

帮我使用 byted-serverlessflink-volc-flink 技能检查 volc-flink 工具的版本，介绍工具相关功能。
帮我查看火山 Flink 平台有哪些项目。
帮我查看 XXX 项目下有哪些 Flink 资源池。
帮我查看有哪些 Flink 草稿。
帮我查看有哪些运行中的 Flink 任务。

如果 command list 可返回命令清单，且 auth status、project current 能正确显示上下文，说明 CLI 和 Skill 的基础链路已可用。

4. 使用场景 #

4.1 开发 Flink 任务 #

4.1.1 Flink SQL 任务

适合场景：

• 生成或修改 Flink SQL。
• 创建流式或批式 SQL 草稿。
• 校验 SQL 草稿。
• 发布草稿并启动 Job。

Agent 提示词示例：

使用 byted-serverlessflink-volc-flink Skill 创建 Flink SQL 任务。
任务名 demo_sql_order_stat，目录 /demo，Engine 版本 1.17。
请先检查当前 profile、project、资源池和草稿目录。
SQL 文件在 ./sql/order_stat.sql。
创建后帮我 validate，但不要发布，除非我确认。

底层命令参考：

volc-flink auth status --output json
volc-flink profile list --output json
volc-flink project current --output json
volc-flink draft directory list --output json
volc-flink draft create --name demo_sql_order_stat --directory-id <dir-id> --job-type FLINK_STREAMING_SQL --engine-version FLINK_VERSION_1_17 --sql-file ./sql/order_stat.sql --output json
volc-flink draft get --id <draft-id> --output json
volc-flink draft validate --id <draft-id> --output json

发布并启动：

volc-flink resource-pool list --output json
volc-flink draft publish --id <draft-id> --resource-pool-id <pool-id> --yes --output json
volc-flink job start --id <job-id> --from new --yes --output json

4.1.2 Flink JAR 任务

适合场景：

• 上传或引用本地 / TOS / 文件资源中的 JAR。
• 指定 Main Class 和 Main Args。
• 创建、更新、发布、启动 JAR 任务。

Agent 提示词示例：

使用 byted-serverlessflink-volc-flink Skill 创建 JAR 任务。
JAR 路径是 ./target/order-job.jar，Main Class 是 com.example.OrderJob。
任务类型是流式 JAR，Engine 版本 1.17，参数是 --env prod --topic order_events。
请先确认资源目录和草稿目录，再创建草稿。创建后只做 draft get 验证。

底层命令参考：

volc-flink draft create --name order_jar_job --directory-id <dir-id> --job-type FLINK_STREAMING_JAR --engine-version FLINK_VERSION_1_17 --jar ./target/order-job.jar --resource-dir-id <resource-dir-id> --main-class com.example.OrderJob --args "--env prod --topic order_events" --output json
volc-flink draft get --id <draft-id> --output json

发布并启动：

volc-flink draft publish --id <draft-id> --resource-pool-id <pool-id> --yes --output json
volc-flink job start --id <job-id> --from new --yes --output json

4.1.3 Flink CDC 任务

适合场景：

• 生成 MySQL、Kafka、Paimon、Doris、StarRocks、ByteHouse CDW 等 CDC YAML 模板。
• 创建或更新 CDC 草稿。
• 发布并启动 CDC Job。

Agent 提示词示例：

使用 byted-serverlessflink-volc-flink Skill 生成 CDC YAML。
源端是 MySQL，目标端是 Paimon，保留凭据占位符，不要执行任何 CLI 变更。
生成后解释 sources、sink、pipeline、route、transform 各部分需要我补充什么。

创建 CDC 草稿：

volc-flink draft create --name mysql_to_paimon_cdc --directory-id <dir-id> --job-type FLINK_CDC_JAR --engine-version FLINK_VERSION_1_17 --cdc-version v3.4 --cdc-file ./cdc/mysql-to-paimon.yml --output json
volc-flink draft get --id <draft-id> --output json

更新 CDC 草稿：

volc-flink draft update --id <draft-id> --cdc-version v3.4 --cdc-file ./cdc/mysql-to-paimon.yml --output json
volc-flink draft get --id <draft-id> --output json

4.2 运维 Flink 任务 #

适合场景：

• 查询 Job 列表和详情。
• 启动、停止、重启 Job。
• 从最新 checkpoint 或 savepoint 恢复。
• 对运行中任务扩缩容。
• 操作 Session 集群。

只读查询提示词：

使用 byted-serverlessflink-volc-flink Skill 查询 Job 状态。
请列出当前项目下的 Job，找到名称包含 order 的任务，展示状态、版本、资源池、并发、最近事件和当前实例。
不要执行任何变更操作。

底层命令参考：

volc-flink job list --output json
volc-flink job get --id <job-id> --output json
volc-flink job events --id <job-id> --output json
volc-flink job instance list --job-id <job-id> --output json

启动任务：

volc-flink job start --id <job-id> --from new --yes --output json

从最新 checkpoint 重启：

volc-flink job restart --id <job-id> --from latest --yes --output json

从 savepoint 重启：

volc-flink job restart --id <job-id> --from savepoint --savepoint-id <savepoint-id> --yes --output json

停止任务并创建 savepoint：

volc-flink job stop --id <job-id> --with-savepoint --yes --output json

运行中扩缩容：

volc-flink job rescale --id <job-id> --parallelism 10 --tm-vcore 2 --tm-memory 8192 --slots-per-tm 4 --jm-vcore 1 --jm-memory 4096 --yes --output json

注意：

• 用户给出的 s-... 通常是运行实例 ID，不一定是稳定 Job ID。Agent 应先用 job instance get 映射到 job_id。
• 对运行中任务扩缩容应使用 job rescale，不要通过修改草稿参数再发布来完成扩缩容。
• job restart 不接收运行时资源参数；需要资源变更时使用 job rescale。

4.3 诊断 Flink 任务 #

适合场景：

• Job 失败、反复重启、长时间处于异常状态。
• 日志中出现 ERROR / WARN。
• TaskManager、JobManager、Pod 异常。
• 性能问题，如反压、延迟升高、吞吐下降、资源不足。

诊断提示词：

使用 byted-serverlessflink-volc-flink Skill 诊断 job <job-id>。
请只执行只读命令。
依次查询 job get、job events、最新 instance、ERROR 日志、Pod、health metrics。
输出根因、证据、置信度和下一步建议。

底层命令参考：

volc-flink job get --id <job-id> --output json
volc-flink job events --id <job-id> --output json
volc-flink job instance list --job-id <job-id> --output json
volc-flink job instance get --id <instance-id> --output json
volc-flink job instance logs --id <instance-id> --level ERROR --limit 200 --output json
volc-flink job instance pods --id <instance-id> --output json
volc-flink job instance metrics --id <instance-id> --preset health --output json

性能分析提示词：

使用 byted-serverlessflink-volc-flink Skill 分析 job <job-id> 最近 2 小时性能问题。
请对齐 metrics、WARN/ERROR 日志和事件时间线。
重点看吞吐、延迟、反压、checkpoint、CPU、内存和重启事件。
不要执行扩缩容或重启，只给建议。

日志时间范围可以使用 RFC3339 或 Unix 秒：

volc-flink job instance logs --id <instance-id> --since 2026-05-22T10:00:00+08:00 --until 2026-05-22T12:00:00+08:00 --level WARN --limit 200 --output json

日志跟随：

volc-flink job instance logs --id <instance-id> --follow --output ndjson

4.4 资源池资源分析 #

适合场景：

• 发布任务前选择资源池。
• 查看资源池状态、容量和使用量。
• 分析资源池是否可能成为任务启动失败或性能瓶颈原因。

Agent 提示词：

使用 byted-serverlessflink-volc-flink Skill 分析当前项目资源池。
请只执行只读命令。
列出资源池 ID、名称、类型、计费类型、状态、容量、已用资源、创建时间。
如果是按量资源池，关注使用 CU 数量和总 CU 数量。
如果是包月或混合资源池，关注 CPU 和内存字段。
最后推荐适合发布新任务的资源池候选。

底层命令参考：

volc-flink resource-pool list --output json
volc-flink resource-pool get --id <pool-id> --output json

发布任务前选择资源池

volc-flink resource-pool list --output json
volc-flink draft publish --id <draft-id> --resource-pool-id <pool-id> --yes --output json

资源池分析输出建议包含：

5. 常用 Agent 提示词模板 #

5.1 只读预检 #

使用 byted-serverlessflink-volc-flink Skill。
请只执行只读命令，检查当前 auth、profile、project、command list。
输出当前上下文和可用命令摘要，不要执行任何创建、更新、发布、启动、停止或删除操作。

5.2 创建任务但不发布 #

使用 byted-serverlessflink-volc-flink Skill 创建草稿，但不要发布。
请先解析目标目录和项目上下文，创建后执行 draft get 和 draft validate。
如果需要创建目录或上传文件，请先说明计划并等待我确认。

5.3 发布并启动 #

使用 byted-serverlessflink-volc-flink Skill 发布并启动草稿 <draft-id>。
请先列出资源池候选并让我选择。
发布前展示 draft id、资源池 id、启动方式。
只有我确认后才执行 draft publish 和 job start。

5.4 故障诊断 #

使用 byted-serverlessflink-volc-flink Skill 诊断 <job-id>。
请只读查询 job 详情、事件、最新实例、ERROR 日志、Pod 和 health metrics。
输出：现象、证据、可能原因、置信度、建议下一步。

6. 安全和最佳实践 #

• 严格控制登录 AK 的权限，避免开放过大的权限，导致发生意外损失。
• 大模型的幻觉问题难以完全避免，所有重要的参数配置和执行命令都需要仔细检查和确认。
• 不要在聊天中粘贴 AK/SK、Token、数据库密码、连接串明文。
• Connector YAML、SQL WITH 参数中的敏感字段应使用占位符。
• 所有变更操作都应先确认目标 ID，优先使用 ID，不要依赖模糊名称。
• 发布、启动、停止、重启、扩缩容、删除命令建议始终保留 --output json，方便 Agent 验证结果。
• 任务诊断和性能分析默认只读；只有用户明确要求时才进入 SRE 变更流程。
• 使用 volc-flink schema <command.id> --output json 校验当前 CLI 支持的参数，避免使用过期命令或旧参数。