# dsh-jenkins
**dsh-jenkins** 是基于 DeepSeek Harness(DSH)宿主的 Jenkins 服务器管理插件,
集中管理多台服务器与 Job,快速完成构建发布。
- **多服务器 / 多 Job 管理**:集中配置、统一管理多台 Jenkins 服务器及其 Job
- **一键发布**:参数化构建触发,实时跟踪「排队 → 构建中 → 结果」状态
- **日志与运维**:随时查看构建日志,支持停止 / 取消构建
- **中英双语**:界面跟随主界面语言切换
自 DSH 0.2.2-rc.1 起,UI 入口统一收进设置弹框左侧菜单(另提供模型工具)。
[English](README.md)
## 预览
设置页入口与发布 / 记录 / 二级弹框的截图:见 [preview.md](preview.md)(截图为 0.2.2 改版前布局)。
## 功能
- **设置 → Jenkins 配置** 页(`settings.section`,唯一的 UI 入口):设置弹框左侧菜单
新增「Jenkins 配置」一格(含 Jenkins logo 导航图标),页面内嵌四个 tab ——
**发布 / 配置 / 本机记录 / 历史记录**。标题行右侧是任务状态胶囊(构建中 / 成功未读 /
「有更新」新版本提示)与**工作区选择器**(默认跟随当前会话所属工作区,可手动切换)。
「配置」tab 支持多服务器增删改查、测试连接、跳过 TLS 校验,仅 **服务器地址** 与
**Token** 必填(用户名为选填,缺省 `admin`)。构建日志 / 服务器编辑 / 项目配置 /
更新日志等二级弹框以视口顶层蒙版渲染,不受设置面板裁切。
- **项目配置**(`$DSH_HOME/dsh-jenkins-map.json`):所有项目的发布目标集中在一个文件里
—— 项目名 → 发布目标数组,元素结构与工作区配置文件完全一致
(`{ name?, job, server, environments }`)。每个环境可用 **`name` 起显示名**
(如 `uat环境` / `prod灰度` / `prod环境`),**环境数量不限**(留空按下标回退
UAT / 生产 / 环境 N)。**各项目根目录的 `dsh-jenkins.json/js/ts` 会被自动发现**
(以文件夹名为项目名,只补缺失、不覆盖已有项目),因此通常无需手工维护;
需要手改时,「配置」tab 的**项目配置**一行点「编辑 map」即可(表单 / JSON 双模式)。
详见下文「[项目配置(dsh-jenkins-map.json)](#项目配置dsh-jenkins-mapjson)」。
- **发布 tab**(设置页内):只有三行——**项目 → 服务器 → Job**,随后是参数表单回显 →
提交构建 → 轮询状态(排队 → 构建中 → 结果,10 分钟超时)。
**环境不单独占一行**:项目配置里每个环境本来就对应一台服务器,所以环境选择就落在
【服务器】字段上 —— **下拉标签只显示插件里的服务器名**(不混入配置里的环境名,
避免两套命名交叉显示),选中服务器即切到该环境对应的 Job / 参数。
服务器按 **名称 / id / 完整地址 / 域名** 依次匹配配置里的 `server`(域名一级忽略协议、
端口与上下文路径);下拉取「项目配置引用过的服务器 ∩ 插件已配置服务器」的交集。
上次发布的参数按项目记住,下次打开自动回显。
- **模型工具**(docs/develop/basic/tool):`dsh_jenkins_build`、`dsh_jenkins_status`。
- **配置**(docs/develop/basic/config):Schemastery `Config` + 插件数据文件
`$DSH_HOME/dsh-jenkins.json`(服务器 Token 以 `$DSH_HOME/dsh-jenkins.key`
机器绑定密钥加密,缓存明文);项目配置是独立文件
`$DSH_HOME/dsh-jenkins-map.json`(明文,可直接编辑)。DSH 0.2.2-rc.1 起旧
`settings.yaml` 由宿主框架自行迁移,插件不再读写设置文档(数据文件缺失时以组合
入口 `config.servers` 播种);旧版写在
`dsh-jenkins.json` 的 `projects` 字段也会自动迁到新文件(只补缺失)。
- **打包**(docs/develop/basic/publish):`dsh.bundle` + `dsh.client`(web) manifest。
## 文件结构
```
├── src/host/*.ts # 宿主半边源码:index.ts(入口)、jenkins.ts(curl 核心)、ops.ts(op 分发)、project-map.ts(项目配置文件)、projects.ts(归一化/合并)、workspace-config.ts、types.ts
├── src/client/*.tsx # 浏览器半边源码(React TSX 组件):设置页入口(settings.section 内嵌四 tab)、发布/记录 tab、项目配置等二级弹框
├── lib/index.js # 宿主半边构建产物(tsdown,ESM),提交 git 以支持 git 安装
├── lib/client.js # 浏览器半边构建产物(tsdown → __ModuleLoader__ 工厂),提交 git
├── lib/types/ # 类型声明(tsc -b 生成)
├── scripts/ # verify-client.mjs(模拟宿主 seed 表校验产物)+ 隔离测试
├── examples/ # 示例配置:dsh-jenkins.json(工作区数组格式)、dsh-jenkins-map.json(集中 map)
├── tsdown.config.ts # tsdown 构建配置(node half + client bundle banner 包装)
├── tsconfig.json # solution:引用 tsconfig.host.json / tsconfig.client.json
├── cordis.patch.yml # 组合包 patch:按包名引用插件行(无路径)
├── package.json # dsh.bundle + dsh.client(web) manifest + peerDependencies
├── README.md # 英文文档(默认)
├── README.zh.md # 本文档
└── preview.md # 截图预览(引用 assets/preview/*.png)
```
## 工作区配置文件(dsh-jenkins.json / .js / .ts)
放在**工作区根目录**,**数组形式**,每个元素 = 一个发布目标(job + server +
environments 参数)。`.json` 直接解析;`.js` / `.ts` 经 node 求值
(`module.exports` 或 `export default`):
```json
[
{
"job": "build-app",
"server": "http://uat.example.com",
"environments": { "BRANCH": "main", "DEPLOY": false }
},
{
"job": "build-app",
"server": "http://prod.example.com",
"environments": { "BRANCH": "release-1.0", "DEPLOY": true }
}
]
```
- 每个元素必填 `job`(Jenkins 任务路径,如 `build-app` 或 `folder/build-app`)与
`server`(对应 设置 → Jenkins 里的服务器 name / id / 地址)。
- `environments`(选填):该发布目标的参数键值(布尔值渲染为勾选框,其余为文本框)。
- 这类文件现在是**发现式配置**:插件会把它读进 [项目配置](#项目配置dsh-jenkins-mapjson),
以**工作区文件夹名**作为项目名(只补缺失,不覆盖已有项目)。「发布」tab 直接选该项目即可,
服务器 / Job / 参数都会按当前环境自动带出。
## 项目配置(dsh-jenkins-map.json)
一份配置集中管理所有项目:**项目名 → 发布目标数组**。每个环境可选带一个
**`name` 显示名**(如 `uat环境` / `prod灰度` / `prod环境`),**环境数量不限**
(第 1 项为默认环境,通常写 UAT);留空时界面按下标回退显示 `UAT` / `生产` / `环境 N`。
元素结构与工作区配置文件同构,可直接互相搬运:
```json
{
"health-check-ui": [
{
"name": "uat环境",
"job": "system3_Front_docker3",
"server": "https://dev-jenkins-tx.whale-plus.com",
"environments": {
"project": "health-check-ui",
"branch": "uat5",
"NodeVersion": "v24.12.0",
"INSTALL_COMMAND_ACTIVE": "pnpm i --registry=https://repo.huaweicloud.com/repository/npm/",
"BUILD_COMMAND_ACTIVE": "pnpm build:uat"
}
},
{
"name": "prod灰度",
"job": "pro_system3_Front_docker3_gray",
"server": "https://jenkins-tx.whale-plus.com",
"environments": {
"project": "health-check-ui",
"branch": "release/gray",
"NodeVersion": "v24.12.0",
"BUILD_COMMAND_ACTIVE": "pnpm build:gray"
}
},
{
"name": "prod环境",
"job": "pro_system3_Front_docker3",
"server": "https://jenkins-tx.whale-plus.com",
"environments": {
"project": "health-check-ui",
"branch": "master5",
"NodeVersion": "v24.12.0",
"BUILD_COMMAND_ACTIVE": "pnpm build:prod"
}
}
]
}
```
- **存储位置**:独立文件 **`$DSH_HOME/dsh-jenkins-map.json`**(裸 map,无包装层,
明文;缺失时按空 map 处理,损坏时备份 `.bak` 后按空处理)。旧版把项目配置写在
`dsh-jenkins.json` 的 `projects` 字段,首次启动会自动迁到新文件(只补缺失)。
- **name(环境显示名)**:选填;写空串等于不写(不会落 `"name": ""`)。
发布时它出现在【服务器】下拉标签与「本机记录」里,一眼看出这次发的是哪个环境。
- **环境数量不限**:一个项目可以有任意多个发布目标(UAT / 灰度 / 生产 / 海外…),
数组顺序即显示顺序,第 1 项为默认环境。
- **发现式配置**:打开「配置」/「发布」tab 时会扫描**所有已打开工作区**根目录的
`dsh-jenkins.json/js/ts`,以**文件夹名**作为项目名合并进 map ——
**默认只补缺失、不覆盖已有项目**;手改过的同名项目不会被冲掉。
需要按工作区里的最新配置更新时,在弹框底部勾选「覆盖同名项目」再点「重新发现」。
- **编辑**:「配置」tab 一行的**项目配置**(`dsh-jenkins-map.json · N 个项目`)点
「编辑 map」打开弹框:
- **表单**:项目列表,每个环境一行 = 环境名(选填,placeholder 显示回退名)+ Job +
服务器 + 「N 项参数」(点开编辑参数键值对,值可指定文本·数字·布尔)+ 逐行删除;
「添加环境」不设上限,可增删项目 / 环境 / 参数;
- **JSON**:整个 map 的 JSON 直接编辑(可整段粘贴你自己的配置),「应用 JSON」写回表单。
- **server 写法与匹配**:可写服务器**名称 / id / 完整地址 / 纯域名**;与 设置 → Jenkins
里配置的服务器按 **名称 → id → 完整地址(去尾部斜杠)→ 域名** 依次匹配 ——
域名一级忽略协议、端口与上下文路径(`http://jenkins-tx.example.com:8080/jenkins`
与配置里的 `https://jenkins-tx.example.com` 视为同一台)。一台都没匹配上时,发布 tab
在服务器行下方给出提示,下拉退化为全部服务器。
- **一键发布**:「发布」tab 的**项目下拉**列出 map 里的项目;选中后**环境由【服务器】下拉
直接切换**(下拉标签就是插件里的服务器名,不显示配置里的环境名),Job 与参数随该环境的
发布目标自动带出,直接「提交构建」。发布记录按「项目配置:项目名」归组在「本机记录」tab
(可按该项目筛选 / 清空),每条记录还会标出发布的环境名。
- **手工编辑**:文件本身就是 map,可直接用编辑器打开改;保存后回到界面即生效
(每次读取都重新解析文件)。
## 安装
```sh
# 本地开发
dsh plugin --profile web add ./dsh-jenkins
# 发布后:npm / tarball / GitHub
dsh plugin --profile web add dsh-jenkins
dsh plugin --profile web add ./dsh-jenkins-0.1.4.tgz
dsh plugin --profile web add github:you/dsh-jenkins#
dsh --profile web --dump-config # 验证配置层
dsh --profile web # 启动(宿主半边需重启才生效)
```
> **本地开发依赖**:宿主加载 `index.js` 时按 Node 原生 ESM 解析 `@deepseek-ai/schemastery`、
> `@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-settings`,因此插件目录内必须有可解析的
> `node_modules`(已被 `.gitignore` 忽略)。两种做法任选其一:
> 1. 在插件目录执行 `pnpm install`(这三个包已声明为 devDependencies);
> 2. 或把宿主扁平回退目录对应包链接进来,如:
> ```powershell
> New-Item -ItemType Directory "$PWD\node_modules\@deepseek-ai" -Force
> foreach ($p in 'schemastery','dsh-tools','dsh-settings') {
> New-Item -ItemType Junction "$PWD\node_modules\@deepseek-ai\$p" -Target "$env:DSH_HOME\profiles\node_modules\@deepseek-ai\$p"
> }
> ```
静态默认服务器也可写在 profile 的 `cordis.patch.yml`:
```yaml
- insert:
- id: dsh-jenkins
name: dsh-jenkins
config:
servers:
- id: prod
name: 生产环境
baseUrl: https://jenkins.example.com
username: admin
token:
insecure: false
```
## 发布
构建工具为 **tsc + tsdown**(与 `@lemcae/dsh-balance` 等同类插件一致,不使用
vite):`tsc -b` 做类型检查并生成声明文件,`tsdown`(rolldown 内核)分别打包
宿主半边(`lib/index.js`,ESM)与浏览器半边(`lib/client.js`,CJS 单文件
`__ModuleLoader__` 工厂,banner 自动包装)。依赖管理使用 **pnpm 10**(Node
26,lock 提交 `pnpm-lock.yaml`,CI 以 `--frozen-lockfile` 严格安装):
```sh
pnpm install # 安装依赖(按 pnpm-lock.yaml)
pnpm run build # 清理 lib → tsc -b(类型 + 声明)→ tsdown(两半产物)
pnpm run verify # 模拟宿主模块表校验 lib/client.js 可加载(可选)
pnpm publish # 或 pnpm pack / git push origin main(lib/ 已提交,git 安装无需构建)
```
### 自动发布(GitHub Actions)
推送 `v*` tag(`pnpm run release` 会升级 patch 版本、重建产物并自动打标签)触发
[`.github/workflows/publish.yml`](.github/workflows/publish.yml):
- **release job**:Setup Node 26 → `pnpm install --frozen-lockfile` →
`pnpm run check`(tsc -b)→ `pnpm run build`(tsc -b && tsdown)→
`pnpm pack` → 创建 GitHub Release(自动生成 changelog,附 tarball);
- **publish-npm job**:发布到 npm,需要仓库配置 Secret `NPM_TOKEN`
(Settings → Secrets and variables → Actions),缺失时快速失败并给出提示。
## 开发
环境要求:**Node ≥ 26 + pnpm 10**(`package.json` 的 `packageManager` 字段固定
pnpm 版本)。
```sh
pnpm install # 安装 devDependencies(typescript、tsdown、@types/react、@deepseek-ai/* 类型包等)
pnpm run check # 全仓 TypeScript 类型检查(tsc -b)
pnpm run build # 修改源码后重建两半产物(tsc -b && tsdown)
pnpm run watch # tsdown 监听模式(改 src/client 自动重建)
pnpm run verify # 模拟宿主 seed 表校验 lib/client.js 可加载
pnpm run test # 隔离测试:curl -D 输出解析(含代理 CONNECT 隧道块)+ 失败日志 + 参数解析 + 项目配置
pnpm run test:params # 参数解析:内置类型 / uno-choice / Extended Choice / 构建页选项兜底
pnpm run test:store # 数据文件往返:token 加密 / 迁移 / 保留 Token 语义
```
- 宿主半边源码在 `src/host/`,浏览器半边在 `src/client/`(构建入口
`src/client/index.ts`,直接导出 `{ name, inject, apply }`);
- 浏览器半边产物 `lib/client.js` 由 tsdown 的 banner/intro/footer 生成
`window.__ModuleLoader__.load` 工厂包装(无需手写 wrap 脚本);
- 构建产物外部依赖(`react`、`@deepseek-ai/dsh-client-ui-primitives` 等)保持
external,运行时解析自宿主模块表(seed)。
## 任务参数识别
「发布」tab 的参数表单按 Jenkins 服务端的参数定义渲染:
| 服务端类型 | 界面 |
| --- | --- |
| `StringParameterDefinition` / uno-choice 动态引用 | 单行文本 |
| `TextParameterDefinition` | 多行文本 |
| `BooleanParameterDefinition` | 勾选框 |
| `PasswordParameterDefinition` / `CredentialsParameterDefinition` / `FileParameterDefinition` | 密码框 / 文本框 |
| `ChoiceParameterDefinition`(classic)、uno-choice `ChoiceParameter` / `CascadeChoiceParameter`、Extended Choice 单选 | 可搜索下拉 |
| Extended Choice 多选 / uno-choice `MultiSelectParameter` | 勾选列表(按分隔符拼接提交) |
- **脚本生成的选项**(Active Choices / uno-choice 的 `ChoiceParameter`、`CascadeChoiceParameter`)在
REST `/api/json` 里只有 `_class` + 默认值,选项要渲染时才由 Groovy 算出来。这类参数会**自动回落到
构建页 HTML**(`job//build`)解析 `