jk 是一个 Pipeline 原生的 Jenkins 命令行工具，用于在终端中检查和操作 Jenkins Pipeline。
用途
jk 面向 Jenkins Pipeline 的日常操作与排查，主要服务于需要在终端或 AI 编码代理中操作 Jenkins 的场景。它不提供插件、agent、凭据存储、Freestyle 或 Jenkinsfile 编辑等管理命令，只聚焦于流水线本身。
核心模型
Jenkins URL 是主要标识，应使用用户会粘贴到浏览器中的确切 URL。凭据按规范化后的 Jenkins 主机选择。输出稳定且自持，建议对代理解析使用 -o json，对人类阅读使用 YAML，仅在命令明确面向 raw/日志时使用 -o raw。
主要能力
jk 可以检查流水线、触发构建、监视构建、读取日志、查看阶段、查看提交参数，并响应待处理的 Pipeline input 步骤。
使用方式
首次使用时，先检查 jk 是否可用：jk version 或 jk --help。如果命令形态不明确，运行 jk <group> --help 而不是猜测。如果用户未提供足够信息来识别流水线、文件夹或构建，应询问 Jenkins URL。对状态、流水线、参数和阶段检查优先使用 -o json，以便结果可被机器读取。当阶段能定位失败区域时，优先使用阶段范围的日志；仅在失败阶段未知或用户要求完整日志时查看完整日志。
命令参考
jk auth add <jenkins-url-or-host> jk auth list -o json jk pipeline info <pipeline-url> -o json jk pipeline params <pipeline-url> -o json jk pipeline list <folder-url> -o json jk build trigger <pipeline-url> [-p KEY=VALUE ...] [--watch] jk build status <build-url> -o json jk build params <build-url> -o json jk build stages <build-url> -o json jk build logs <build-url> [--stage NAME] [-f] jk build input <build-url> proceed|abort [--input-id ID] [-p KEY=VALUE ...] jk build cancel <build-url> [--wait]
URL 处理
使用 Jenkins URL 而不是自创 job 名称。常见形态包括： https://host/job/pipeline https://host/job/folder/job/pipeline https://host/job/folder/job/sub/job/pipeline https://host/job/multibranch/job/main https://host/job/pipeline/42 https://host/job/pipeline/lastBuild https://host/job/folder/
检查构建的命令通常需要构建 URL，而不仅仅是流水线 URL。如果用户只给出流水线 URL 并询问最新构建，可在适当情况下使用 Jenkins permalink，例如 <pipeline-url>/lastBuild。
可接受的构建 permalink：lastBuild、lastCompletedBuild、lastSuccessfulBuild、lastUnsuccessfulBuild、lastFailedBuild、lastStableBuild、lastUnstableBuild。
常见工作流
检查失败构建：解析目标构建 URL；如果用户给出流水线 URL，从 /lastBuild 开始，或在有歧义时询问具体构建。运行 jk build status <build-url> -o json。运行 jk build stages <build-url> -o json 以找到失败阶段或分支。当阶段能定位失败阶段时，运行 jk build logs <build-url> --stage <failed-stage>；否则检查完整构建日志。报告第一个可操作的失败，而不仅仅是最终失败摘要。
触发并监视构建：当流水线可能参数化时，在触发前检查参数：jk pipeline params <pipeline-url> -o json，然后 jk build trigger <pipeline-url> -p BRANCH=main --watch。使用 --watch 时，将退出码解释为构建结果：0 SUCCESS、1 FAILURE、2 UNSTABLE、3 ABORTED、4 PENDING_INPUT、10 表示 jk 级错误（如 URL、认证、网络、TLS、CSRF 或响应格式错误）。不要将非零 --watch 退出视为通用 CLI 失败；退出码 1 到 4 是 Jenkins 构建状态，应指导后续检查。
处理待处理 input 步骤：对于任何待处理 input 请求，在请求批准或更改状态前先检查门禁。如果用户要求批准待处理 input 但未明确授权 proceed，先用只读检查命令回答，然后请求确认。运行 jk build status <build-url> -o json。检查 pendingInput，包括 ID、允许的参数名、类型和选项。如果有多个 input 待处理，使用 --input-id ID 而不是依赖默认值。如果用户明确批准操作，提交 proceed；如果用户要求停止门禁，提交 abort。除非用户已授权该确切操作，否则在生产、发布、破坏性或部署 input 步骤前先确认。
取消运行中构建：使用 jk build cancel 停止运行中构建，相当于 Jenkins UI 的 Stop 按钮。构建在 Jenkins 完成清理块后标记为 ABORTED。示例：jk build cancel https://jenkins.example.com/job/deploy/42（立即停止，查看请求时刻状态）；jk build cancel https://jenkins.example.com/job/deploy/42 --wait（停止并等待直到 ABORTED，退出码 3）。除非用户明确要求，否则在取消生产或长时间运行构建前先与用户确认。取消后如有需要，用 jk build status 验证。
在文件夹中发现流水线：对文件夹 URL 使用 pipeline list：jk pipeline list https://jenkins.example.com/job/platform/ -o json；jk pipeline info https://jenkins.example.com/job/platform/job/api -o json。如果 pipeline list 提示该 URL 是流水线而非文件夹，则对该 URL 改用 pipeline info。
凭据与 TLS
首次设置使用 jk auth add <host-or-url>。它将凭据存储在 ~/.config/jk/credentials，文件模式 0600，且从不打印令牌。安全规则：如果有交互式终端路径，不要要求用户将 Jenkins 令牌粘贴到聊天中；不要打印凭据文件内容；不要在命令行、日志、issue 评论或摘要中包含令牌；尽可能为私有 CA 使用 SSL_CERT_FILE=/path/to/ca.pem；仅在最后手段使用 --insecure，并说明它会禁用证书验证。
输出处理
对将被解析或摘要的命令优先使用 -o json：jk build status <build-url> -o json、jk build stages <build-url> -o json、jk pipeline params <pipeline-url> -o json。结构化输出以 schemaVersion: "1" 开头。如果围绕 jk 编写自动化，在依赖字段前检查 schema 版本。读取日志时，在识别失败阶段后优先使用 --stage NAME。仅在用户要求监视运行中构建时使用 -f。关注最早的可操作错误，因为 Jenkins 日志在根因之后常包含重复的下游失败。
安全
只读检查默认安全：jk pipeline info ...、jk pipeline params ...、jk pipeline list ...、jk build status ...、jk build params ...、jk build stages ...、jk build logs ...。
更改状态的命令需要明确的用户意图：jk build trigger ...、jk build input ... proceed|abort、jk build cancel ...、jk auth add ... --force、jk auth remove ...。
对于待处理 input 请求，先运行只读检查命令：jk build status <build-url> -o json。使用返回的 pendingInput 详情识别确切门禁。然后，除非用户明确请求该确切操作，否则在生产部署、发布 job、破坏性 job 或批准待处理 input 步骤前，先进行一次简短确认。
错误排查
jk 面向用户的错误通常包含代码、消息和建议。先遵循建议。常见情况：URL 错误或缺少构建号，使用完整 Jenkins URL 并为构建检查附加构建号或 permalink；认证失败，运行 jk auth list -o json 查看已配置主机，然后如有需要运行 jk auth add <host>；未知参数，运行 jk pipeline params <pipeline-url> -o json 并用有效名称重试；TLS 失败，优先使用 SSL_CERT_FILE，除非明确可接受否则避免 --insecure；PENDING_INPUT，检查 pendingInput，有歧义时使用 --input-id，没有用户意图不要自动 proceed。
代理响应模式
向用户报告 Jenkins 发现时：说明检查的 Jenkins 对象（流水线 URL 或构建 URL）；说明构建状态/结果以及已知的失败阶段；提供日志中第一个可操作的错误；建议最小的下一步操作（修复代码/配置、重试构建、提供 input 或更新凭据）；说明检查是否因缺少认证、缺少 URL、jk 不可用或日志截断而受限。
适用场景与限制
适用场景包括：在 AI 编码代理中通过 jk CLI 操作 Jenkins；排查 CI 失败；触发并监视构建；处理待处理 input 步骤；取消运行中构建；在文件夹中发现流水线。限制：该工具是 Pipeline 聚焦的，不提供插件、agent、凭据存储、Freestyle 或 Jenkinsfile 编辑等管理命令。