zzpyjenkins/docs/superpowers/specs/2026-03-18-config-file-design.md

配置文件支持设计

概述

修改 zzpyjenkins CLI 的参数传入方式,从配置文件读取 Jenkins 服务器配置,替代原有的 CLI 选项和环境变量方式。

配置文件

路径

~/.config/zzpyjenkins/config.toml

格式

[work]
url = "https://jenkins.work.com"
username = "myuser"
password = "mypassword"

[home]
url = "http://localhost:8080"
username = "admin"
password = "admin123"

每个 section 名称即为服务器名称,包含三个必填字段:

• url: Jenkins 服务器 URL
• username: 用户名
• password: 密码或 Token

CLI 变更

移除选项

• --url / -u
• --username / -U
• --password / -P

新增选项

• --server / -s: 指定使用的服务器配置名,必填

使用示例

# 查看服务器信息
zzpyjenkins -s work info

# 列出任务
zzpyjenkins --server home list

# 触发构建
zzpyjenkins -s work build my-job

错误处理

场景	行为
未指定 -s	显示错误信息,提示必须指定服务器名
配置文件不存在	显示错误信息,提示配置文件路径
TOML 语法错误	显示 Python 解析错误信息
服务器名不存在	显示错误信息,列出可用的服务器名
配置项缺失 (url/username/password)	显示错误信息,指出缺失的字段

实现细节

依赖

使用 Python 3.11+ 内置的 tomllib 模块,无需额外依赖。

代码变更

cli.py:

1. 移除 --url, --username, --password 选项
2. 添加 --server / -s 选项
3. 新增 load_config() 函数:
   • 读取 ~/.config/zzpyjenkins/config.toml
   • 解析 TOML 内容
   • 返回配置字典
4. 修改 get_client() 函数:
   • 调用 load_config() 获取配置
   • 根据 --server 参数选择对应配置
   • 创建 JenkinsClient 实例

jenkins_client.py:

无需修改。

迁移说明

注意: 这是一个破坏性变更,环境变量和 CLI 参数方式将不再支持。

用户需要:

1. 创建配置文件 ~/.config/zzpyjenkins/config.toml
2. 将原有的环境变量或 CLI 参数迁移到配置文件
3. 使用 -s <name> 指定服务器