| name | bk-job |
| description | 经 APIGW 调用蓝鲸作业平台（BK-Job）开放接口：查搜定时任务、作业模板、执行方案与作业执行历史、实例状态日志，创建执行方案、新建与启停定时任务，到指定机器快速执行脚本，分发文件到目标机器（仅服务器/本地文件），查主机拓扑与执行账号。含写操作确认门禁、先选业务范围、先查主机与账号等规范。当用户提及作业平台、业务、业务集、蓝鲸作业、定时任务、cron、执行方案、作业模板、job_plan、job_instance、执行历史、快速执行脚本、fast_execute_script、文件分发、fast_transfer_file、主机、搜索主机、执行账号、bk_scope、APIGW 调用作业接口时使用。不适用于 Web 界面操作、非 APIGW 调用及 CMDB、监控等其它蓝鲸产品。 |
| compatibility | 依赖 Python 3（标准库即可）；访问令牌优先经 imate 的 ai-hub 命令获取，回退环境变量 BK_JOB_ACCESS_TOKEN；API 网关与页面根 URL、多租户默认 bk_tenant_id 均在技能根目录 config.yaml 中配置；同环境跨租户时可通过 --bk-tenant-id 入参按次覆盖（优先级：CLI > config.yaml > default），部署时修改该文件即可。 |
| metadata | {"version":"1.0.0","bk_skill_code":"bk-job","openclaw":{"displayName":"蓝鲸作业平台","requires":{"env":"[Truncated]"},"primaryEnv":"BK_JOB_ACCESS_TOKEN"}} |
蓝鲸作业平台运维操作
通过技能包内脚本 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 列出该范围可用账号供选择，不要凭空猜账号别名。
- 文件分发仅两种源：只支持「服务器文件」与「本地文件」；第三方文件源（如 COS）未提供接口，不要给该选项，脚本会拒绝。
- 列表先查一页：默认
--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/ 内容，严禁删其它路径。见 临时文件。
- 让用户选择优先用选项卡： 可用且候选 ≤8 时用它发结构化选项（确认门禁用 类型），否则表格呈现；候选过多先收敛再选。见 。
支持的原子能力
| 能力 | 子命令 | 手册 |
|---|
| 范围选择 | 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 | 手册 |
字段级参数见 references/apidocs/，全部参数用 --help 查看。
常用组合工作流程
只是常见示例，非能力边界：可按需用上表原子能力自由组装，但写操作一律走 G1–G4 门禁。各链路步骤见 工作流程手册：快速执行脚本、分发本地/服务器文件、搜方案并启动、查模板建方案、建定时任务并启用、查定时任务与执行历史、查执行历史并下钻。
异常处理
- 关键词歧义：多条匹配时脚本列候选并退出，需补
--cron-id/--job-plan-id，或知情下用 --pick-first。
- 鉴权失败、无历史、状态码含义：见 排障手册。
- 回溯上限：
cron-last-run、instance-list 最多回溯 31 天，超出会截断并提示。
