bk-job

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。

前置检查

1. 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）。
2. 访问令牌：脚本按 --access-token → ai-hub（imate）→ BK_JOB_ACCESS_TOKEN 自动获取，智能体勿自行取令牌或回显。见 鉴权手册。
3. 资源范围：无 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 天，超出会截断并提示。