tencentblueking 蓝鲸作业平台运维操作
通过技能包内脚本 scripts/job_apigw_client.py 调用蓝鲸 API 网关 上的作业平台接口完成运维操作。
核心概念
- 资源范围：一切操作的前提，由
bk_scope_type（biz业务 /biz_set业务集）与bk_scope_id组成。 - 作业对象关系：模板派生执行方案；方案可直接启动，也可由定时任务周期触发；每次执行产生作业实例，状态与日志按实例 ID 查。
- 渐进式披露：本文件常驻上下文，细节按任务再读手册；包结构与手册索引见 手册 README。
前置检查
- URL 与租户配置：脚本从
config.yaml读apigw_base_url、job_base_url与可选的bk_tenant_id，不读环境变量。租户 ID 优先级：--bk-tenant-id入参 >config.yaml的bk_tenant_id>default；同一作业平台环境需跨租户时，上下文/业务记忆未明确租户 ID 则先向用户确认，确认后给脚本传--bk-tenant-id <ID>（勿凭空猜租户 ID）。 - 访问令牌：脚本按
--access-token→ai-hub（imate）→BK_JOB_ACCESS_TOKEN自动获取，智能体勿自行取令牌或回显。见 鉴权手册。 - 资源范围：无
bk_scope上下文且无业务记忆时，先用list-authorized-scopes列出有权限的业务/业务集供选择，勿擅自猜bk_scope_id；选定后可沉淀业务记忆（写入须确认）。
核心规则（必读）
- 写操作须过 G1–G4 门禁：
plan-execute、fast-execute-script、fast-transfer-file、plan-create、cron-save、cron-update-status（非--dry-run）须先展示确认摘要，再等用户下一条独立回复才执行；「立即执行」只表达意图，不算确认。一次确认只授权一次执行，重复执行（含「相同参数再执行一次」）须重新走门禁，不得跳过。摘要须列全部生效参数：以--dry-run的request_body加defaults_applied为准，未指定项标[默认]并说明后果（如强制模式覆盖同名文件），不得省略。格式与反例见 确认门禁。 - 填主机先查再填：需要目标机（含分发源机）而用户未给
bk_host_id或bk_cloud_id:ip时，先用host-topo-tree、host-search定位，列候选经用户确认，不要凭空猜主机 ID。 - 填账号先查再填：需要执行账号而用户未指定时，先用
account-list列出该范围可用账号供选择，不要凭空猜账号别名。 - 文件分发仅两种源：只支持「服务器文件」与「本地文件」。用户没说文件在哪时，只能在这两项里二选一，不得提供第三方文件源（
file_type=3）、制品库/仓库里的已有文件、COS 等任何第三个选项——接口未提供，脚本会拒绝。引导话术见 文件分发手册 第 2 节。 - 列表先查一页：默认
--length 20并用--keyword缩小，total > length时先说明「本页 N 条，共 M 条」再问翻页；大列表用 jq 过滤，勿把整页 JSON 贴进对话。见 列举与分析。 - 对用户输出：不叙述调脚本/调 API 过程，表格化交付结论；同一轮内不得既给摘要又真实执行。
- 回答须声明当前租户：无论查询还是写操作，回答中都需显式给出本次请求实际生效的租户 ID 及其来源（
--bk-tenant-id入参 /config.yaml/default），便于用户核对是否是他期望的租户。接口返回 4xx、资源不存在或列表为空时，除给出常规排查建议外，附带一句「本次请求的是租户<X>下的资源，如与预期不符可通过--bk-tenant-id指定」，供用户自行判断，不预设租户错配即是原因。 - 临时文件只放技能
tmp/：内联 JSON 在 PowerShell 易转义失败，改用--*-file入参；这类中间文件一律写tmp/，操作触发后即清（本地文件上传成功即清，避免占满磁盘），且只许清tmp/内容，严禁删其它路径。见 临时文件。 - 让用户选择优先用选项卡：
ai-hub-ask-user-input可用且候选 ≤8 时用它发结构化选项（确认门禁用confirm类型），否则表格呈现；候选过多先收敛再选。见 交互选择。 - 主机变量结构因接口而异：
plan-create与plan-execute/cron-save字段名不同，组装前先查手册差异表。 - 切换业务后重查资源：切换业务后必须重新查询拓扑、主机、账号、方案、定时任务，禁止复用上一业务的资源。
- 必给结果链接：无论成败，触发后须以可点击链接交付
job_instance_url（执行类）或job_plan_url（建方案）。
支持的原子能力
| 能力 | 子命令 | 手册 |
|---|---|---|
| 范围选择 | list-authorized-scopes |
手册 |
| 主机查询 | host-topo-tree、host-search |
手册 |
| 账号查询 | account-list |
手册 |
| 定时任务 | cron-search、cron-last-run |
手册 |
| 模板与创建 | template-search、template-detail、plan-create、cron-save、cron-update-status |
手册 |
| 方案与启动 | plan-search、plan-detail、plan-execute |
手册 |
| 快速执行脚本 | fast-execute-script |
手册 |
| 文件分发 | fast-transfer-file、gen-local-upload-url、upload-local-file |
手册 |
| 执行历史与日志 | instance-list、instance-status、get-instance-log |
手册 |
| 业务记忆 | memory-load |
手册 |
字段级参数见 references/apidocs/，全部参数用 --help 查看。
常用组合工作流程
只是常见示例，非能力边界：可按需用上表原子能力自由组装，但写操作一律走 G1–G4 门禁。各链路步骤见 工作流程手册：快速执行脚本、分发本地/服务器文件、搜方案并启动、查模板建方案、建定时任务并启用、查定时任务与执行历史、查执行历史并下钻。
异常处理
- 关键词歧义：多条匹配时脚本列候选并退出，需补
--cron-id/--job-plan-id，或知情下用--pick-first。 - 鉴权失败、无历史、状态码含义：见 排障手册。
- 回溯上限：
cron-last-run、instance-list最多回溯 31 天，超出会截断并提示。