VS Code / Cursor 扩展（市场 ID：ts-org.jenkins-cli）：可视化编辑 jenkins-cli.yaml，并连接 Jenkins 选择 Job、建议构建参数。
适用版本
| 组件 | 包名 / 路径 | 版本 | 状态 |
|---|---|---|---|
| 本扩展 | Jenkins CLI — jenkins-cli（本目录） |
0.1.0 | preview |
| CLI | @ts-org/jenkins-cli（仓库根目录） |
>= 3.1.5 | stable |
配置 Schema 以仓库根目录 schemas/jenkins.json 为准，构建时会复制到扩展包内。Schema 若有破坏性变更，需同时升级 CLI 与扩展，并更新本文档与根 README 中的互注版本。
更完整的功能说明与内网 Jenkins 调试清单见 DEBUG.md。
功能
表单编辑器
打开 jenkins-cli.yaml 时默认是文本；点文件顶部 CodeLens Open Config Form Editor、右下状态栏同名按钮，或命令面板进入表单。
Cursor 2.1+ 默认把编辑器标题栏图标收进右上角
···；可在···→ Configure Icon Visibility 勾选显示。
| 区块 | 说明 |
|---|---|
| Connection | 填写 apiToken（密码框）、测试连接、刷新 Job 列表 |
| Job | 静态 Job 名（可从 Jenkins 下拉），或 path:exportName 动态引用 |
| Modes | 环境列表（标签增删），或动态引用 |
| Configs | 额外交互参数卡片：type / name / message / offset / default / choices / when / validate / filter / transformer |
- 表单改动会自动写回 YAML（不保留行内注释；会保留或写入 schema 注释头）
apiToken 格式与 CLI 相同：
http(s)://username:token@host:port
Jenkins 连通
| 能力 | 说明 |
|---|---|
| 测试连接 | 调用 whoAmI，显示当前用户与 Job 数量 |
| Job 列表 | 连接成功后填充下拉 / datalist |
| 参数名建议 | 选中静态 Job 后拉取 parameterDefinitions，供 configs[].name 使用 |
YAML 增强（纯文本模式）
默认以文本打开 jenkins-cli.yaml。可用：
- 状态栏：Open Config Form Editor（打开该文件时显示）
- Schema 校验（
jsonValidation+ 文件头$schema注释） path:exportName转到定义- 诊断：引用文件/导出不存在；保留字
branch/mode/modes；凭证 Hint - 补全：在
job/modes/choices/when等字段补全工作区内的导出符号
命令面板
| 命令 | 作用 |
|---|---|
| Jenkins CLI: Open Config Form Editor | 用表单打开配置 |
| Jenkins CLI: Test Jenkins Connection | 测试 apiToken（读当前/工作区配置，否则手动输入） |
| Jenkins CLI: Create jenkins-cli.yaml | 在工作区根目录生成初始配置 |
编辑器标题栏在打开 jenkins-cli.yaml 时也会提供表单入口。
开发调试
在仓库根目录执行：
pnpm install
pnpm --filter jenkins-cli build
- 用 Cursor / VS Code 打开本仓库作为工作区
- 运行和调试 → Run Jenkins CLI Extension（或按 F5）
- 会启动 Extension Development Host；请在该窗口中测试，不要在父 IDE 里测
热更新：
pnpm --filter jenkins-cli watch
改完代码后如未自动生效，在 Host 窗口执行 Developer: Reload Window。
快速自测
不连 Jenkins 也可测
- F5 启动 Host
- 打开
jenkins-cli.yaml→ 看到表单 - 改 modes / configs → 自动/手动 Save → 文本核对 YAML
- 纯文本下对
jenkins-cli.ts:dynamicJob做 Go to Definition - 故意把某 config 的
name设为branch，Problems 应报错
连上公司内网 Jenkins 后
- 表单填入真实
apiToken→ Test Connection 成功 - Job 下拉有数据；选 Job 后 configs 的 name 有参数建议
- 错误 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/）
注意事项
- 密钥：
apiToken含账号与 Token，勿提交到 Git；表单使用密码输入框。 - 注释：表单保存会重写 YAML，不保留原有行内注释（v1）。
- 默认编辑器：
jenkins-cli.yaml默认打开文本；用状态栏按钮打开表单（Cursor 标题栏图标默认藏在···里）。 - 自签证书：扩展在 Node 宿主发请求，无浏览器 CORS；证书问题按 TLS 错误提示处理，v1 不做绕过 UI。
- 与 CLI 分工：扩展只管配置；触发构建、停构建、看日志等仍用
jenkins-cli/jc。
相关文档
- DEBUG.md — 功能地图与验收清单
- 仓库根 README — CLI 用法与配置说明
- CLAUDE.md — 仓库架构与扩展版本同步约定
.cursor/rules/vscode-extension.mdc— Cursor 常驻规则.cursor/rules/cli-extension-compat.mdc— CLI ↔ 扩展版本互注