Jenkins CLI

VS Code / Cursor 扩展（市场 ID：ts-org.jenkins-cli）：可视化编辑 jenkins-cli.yaml，并连接 Jenkins 选择 Job、建议构建参数。

适用版本

配置 Schema 以仓库根目录 schemas/jenkins.json 为准，构建时会复制到扩展包内。Schema 若有破坏性变更，需同时升级 CLI 与扩展，并更新本文档与根 README 中的互注版本。

更完整的功能说明与内网 Jenkins 调试清单见 DEBUG.md。

功能

表单编辑器

打开 jenkins-cli.yaml 时默认是文本；点文件顶部 CodeLens Open Config Form Editor、右下状态栏同名按钮，或命令面板进入表单。

Cursor 2.1+ 默认把编辑器标题栏图标收进右上角 ···；可在 ··· → Configure Icon Visibility 勾选显示。

• 表单改动会自动写回 YAML（不保留行内注释；会保留或写入 schema 注释头）

apiToken 格式与 CLI 相同：

http(s)://username:token@host:port

Jenkins 连通

YAML 增强（纯文本模式）

默认以文本打开 jenkins-cli.yaml。可用：

• 状态栏：Open Config Form Editor（打开该文件时显示）
• Schema 校验（jsonValidation + 文件头 $schema 注释）
• path:exportName 转到定义
• 诊断：引用文件/导出不存在；保留字 branch / mode / modes；凭证 Hint
• 补全：在 job / modes / choices / when 等字段补全工作区内的导出符号

命令面板

编辑器标题栏在打开 jenkins-cli.yaml 时也会提供表单入口。

开发调试

在仓库根目录执行：

pnpm install
pnpm --filter jenkins-cli build

1. 用 Cursor / VS Code 打开本仓库作为工作区
2. 运行和调试 → Run Jenkins CLI Extension（或按 F5）
3. 会启动 Extension Development Host；请在该窗口中测试，不要在父 IDE 里测

热更新：

pnpm --filter jenkins-cli watch

改完代码后如未自动生效，在 Host 窗口执行 Developer: Reload Window。

快速自测

不连 Jenkins 也可测

1. F5 启动 Host
2. 打开 jenkins-cli.yaml → 看到表单
3. 改 modes / configs → 自动/手动 Save → 文本核对 YAML
4. 纯文本下对 jenkins-cli.ts:dynamicJob 做 Go to Definition
5. 故意把某 config 的 name 设为 branch，Problems 应报错

连上公司内网 Jenkins 后

1. 表单填入真实 apiToken → Test Connection 成功
2. Job 下拉有数据；选 Job 后 configs 的 name 有参数建议
3. 错误 token 应明确提示 401/403，不能静默失败

逐步勾选清单见 DEBUG.md §3。

打包安装

pnpm --filter jenkins-cli package

生成：jenkins-cli-0.1.0.vsix

# VS Code
code --install-extension ./jenkins-cli-0.1.0.vsix

# Cursor（若 CLI 为 cursor）
cursor --install-extension ./jenkins-cli-0.1.0.vsix

目录结构

vscode-extension/
├── package.json                 # 扩展清单、命令、Custom Editor、schema
├── README.md                    # 本说明
├── DEBUG.md                     # 功能细节 + 内网调试清单
├── scripts/build.mjs            # esbuild 打包，并 copy schemas
├── src/
│   ├── extension.ts             # 激活入口
│   ├── jenkins/client.ts        # 薄 Jenkins 客户端（独立于 CLI）
│   ├── editor/
│   │   ├── configEditor.ts      # CustomTextEditorProvider
│   │   └── webview/html.ts      # 表单 UI
│   ├── io/document.ts           # YAML 读写与引用解析
│   └── yaml/                    # 定义跳转 / 诊断 / 补全
└── schemas/jenkins.json         # 构建产物（源文件在仓库根 schemas/）

注意事项

1. 密钥：apiToken 含账号与 Token，勿提交到 Git；表单使用密码输入框。
2. 注释：表单保存会重写 YAML，不保留原有行内注释（v1）。
3. 默认编辑器：jenkins-cli.yaml 默认打开文本；用状态栏按钮打开表单（Cursor 标题栏图标默认藏在 ··· 里）。
4. 自签证书：扩展在 Node 宿主发请求，无浏览器 CORS；证书问题按 TLS 错误提示处理，v1 不做绕过 UI。
5. 与 CLI 分工：扩展只管配置；触发构建、停构建、看日志等仍用 jenkins-cli / jc。

相关文档

• DEBUG.md — 功能地图与验收清单
• 仓库根 README — CLI 用法与配置说明
• CLAUDE.md — 仓库架构与扩展版本同步约定
• .cursor/rules/vscode-extension.mdc — Cursor 常驻规则
• .cursor/rules/cli-extension-compat.mdc — CLI ↔ 扩展版本互注