Tuyoo DevFlow CLI

Tuyoo DevFlow 是面向 TuyooGame 研发流程的 CLI 工具集，一期聚焦 Jenkins Agent 安装主流程，二期开始补齐 Jenkins Pipeline job 管理能力。

功能范围（一期）

• 跨平台支持：macOS、Windows、Linux
• 前置检查：系统约束、白名单连通性、工具与版本
• Jenkins 端口检查策略：
  • Jenkins URL 为 http:// 时仅检查 80
  • Jenkins URL 为 https:// 时仅检查 443
  • 始终检查 Jenkins 50000（JNLP）
• 依赖准备：Miniconda + pytuyoo-pipeline 虚拟环境
• Agent 产物：
  • Linux 生成 systemd 服务（优先自动安装并立即启动）
  • macOS 默认生成 LaunchAgent plist 并通过 launchctl 管理，也支持通过参数切换为直接脚本启动
  • Windows 生成 start_jenkins_agent.bat
• 安全策略：
  • Jenkins secret 明文写入启动脚本（按简化流程）
  • GitLab token 仅用于本次 clone，完成后不持久化保存
  • clone 完成后会重置 git remote，清理凭据 URL
  • 不在日志明文落盘

功能范围（二期）

• Jenkins Pipeline job 管理：
  • 基于模板 job 创建或更新目标 job
  • 同步 displayName、scriptPath、SCM branch
  • 覆盖 Jenkins 参数默认值
  • 删除 Jenkins 上已经废弃的参数
• Jenkins Pipeline 构建诊断：
  • 给定 build URL 拉取构建信息与 consoleText
  • 提取失败 stage、关键错误、外部日志 URL 与日志尾部
  • 第一批识别 Gradle task 缺失、Python/PyTuyoo 异常、What went wrong 类错误
• 命令边界：
  • job 同步入口为 tdf pipeline sync
  • 构建诊断入口为 tdf pipeline diagnose <build-url>
  • sync 默认 dry-run，只有显式传 --apply 才会写 Jenkins
  • diagnose 为只读命令，不触发或修改 Jenkins job
  • 支持 --remove-param <NAME> 清理 parameterDefinitions 与 declarative tracker 中的废弃参数
• 典型场景：
  • 新增一条渠道流水线
  • 调整已有流水线的 Jenkinsfile 路径或分支
  • 代码删掉参数后，同步清理 Jenkins 参数面板

二期规划

• 当前已落地：
  • pipeline sync 已可用于三国2这类“模板复制 + 参数同步”的场景
  • pipeline diagnose 已可用于“给一个失败构建 URL，快速提取失败原因”的只读排障场景
  • 支持移除废弃参数，避免代码删掉后还要手动去 Jenkins 页面清理
• 下一步建议：
  • 增加 pipeline sync --config <file> 的标准模板示例，沉淀到仓库内
  • 扩充 pipeline diagnose 的错误模式库，例如 Git checkout、Cocos 构建、Nexus 上传、网络白名单失败
  • 补 pipeline trigger，把“同步后触发测试构建”收进同一条命令链路
  • 补 pipeline diff，在 apply 前展示更明确的参数增删改摘要
  • 补 Jenkins 凭据 profile 管理，减少命令行显式传 token 的场景
  • 补项目级 job 模板目录，约定不同业务线的标准脚本路径和默认参数

环境要求

• Node.js >= 20
• Java（OpenJDK 11 / 17 / 21）
• Git >= 2.30
• Miniconda（conda 命令可用）
• Linux 额外要求：
  • 系统必须是 rocky9*
  • 必须存在本次选择的 Linux 运行用户
  • doctor / install 会在 Linux 下提示选择运行用户，也可通过 --linux-user <user> 显式指定
  • 若当前执行账号与目标运行用户不同，需要具备 sudo -u <user> 及 systemd 相关权限

安装与开发

npm install
npm run build

本地调试：

npm run dev -- --help

Pipeline 构建诊断：

tdf pipeline diagnose http://jenkins.example.com/job/foo/123/

常用选项：

tdf pipeline diagnose <build-url> --raw --tail 240
tdf pipeline diagnose <build-url> --json

凭据优先读取 pipeline sync --save-credentials 保存的 Jenkins 用户名和 API Token；也可通过 --username / --token 显式传入。未配置凭据时会先按匿名只读请求访问，适合内部 Jenkins 允许公开查看构建日志的场景。

命令说明

检查模式（只读）：

tdf agent doctor

Linux 如需显式指定运行用户：

tdf agent doctor --linux-user alice

进入后会自动进入交互式页面：

• 先展示当前系统信息
• 再执行 doctor 检查并输出结果
• 若网络白名单存在未通过项，会额外输出一份 OA 申请格式报告，并写入 ~/.tuyoo-devflow/reports/doctor-whitelist-failures.txt
• 若存在缺失工具，提供可勾选的自动安装项

安装模式：

tdf agent install

Linux 如需显式指定运行用户：

tdf agent install --linux-user alice

macOS 默认使用 launchctl 启动；如需改为直接脚本启动，可显式指定：

tdf agent install --mac-start-mode script

当检测到 Git/Java/Miniconda 缺失或版本不满足时，install 会引导自动安装：

• Git：安装最新版本
• Java：可选择安装 OpenJDK 21 / 17 / 11，默认优先 OpenJDK 21（若检测到非 OpenJDK 发行版也会判定失败并引导替换）
• Miniconda：macOS 可选 Homebrew 或 curl + bash，Linux 默认 curl + bash
• 自动安装时会实时输出子进程日志，并每 15 秒输出“仍在安装中”状态提示
• conda 环境准备完成后会自动检测 conda activate 能力，若未初始化会醒目提示并自动执行 conda init

安装时会提示输入：

1. curl -sO .../jnlpJars/agent.jar
2. java -jar agent.jar ...
3. 包含用户名与 Token 的 pytuyoo-pipeline 仓库地址（形如 https://name:[email protected]/liutongqing/pytuyoo-pipeline.git；仅在需要重新 clone/安装依赖时询问，仅用于本次 clone，不持久化保存，clone 后会自动重置 origin 为无凭据地址）

命令缓存机制：

• 首次输入的两行 Agent 命令会保存到本地临时文件
• 再次执行 install 时会询问是否修改（默认不修改，直接复用继续）

卸载模式：

tdf agent uninstall

卸载命令说明：

• 优先读取当前目录下的 agent-install.json 来定位 workDir 与服务名；在哪个 Agent 目录执行就卸载哪个
• 若当前目录没有安装记录，再回退到本地安装命令缓存推断
• 也支持显式指定参数：

tdf agent uninstall --work-dir /path/to/workDir --service-name jenkins-agent-xxx

• Linux 会尝试停止并卸载 systemd 服务，macOS 会尝试卸载 launchctl 服务
• 会删除启动脚本与 agent.jar，并清理本地安装命令缓存

启动 Agent：

# Linux
bash <workDir>/start_jenkins_agent.sh

# macOS（launchctl 默认）
bash <workDir>/start_jenkins_agent.sh
bash <workDir>/start_jenkins_agent.sh restart
bash <workDir>/start_jenkins_agent.sh status
bash <workDir>/start_jenkins_agent.sh status --verbose
bash <workDir>/start_jenkins_agent.sh stop

# macOS（script 模式）
bash <workDir>/start_jenkins_agent.sh

# Windows
<workDir>\\start_jenkins_agent.bat

生成产物

• Linux：
  • ${workDir}/start_jenkins_agent.sh
  • 默认自动安装 /etc/systemd/system/jenkins_agent.service 并执行 systemctl daemon-reload && systemctl enable --now
  • systemd、conda、pytuyoo-pipeline 准备流程都会使用本次选择的 Linux 运行用户
  • 若 jenkins_agent.service 已存在，会提示输入新的 .service 文件名后继续自动安装与启动
  • 同时保留 ${workDir}/<service>.service 本地副本，便于排查
  • 写入 ${workDir}/agent-install.json，记录最终服务名与安装结果，供后续卸载自动识别
• macOS：
  • ${workDir}/start_jenkins_agent.sh
  • launchctl 模式（默认）：
    • ~/Library/LaunchAgents/<service>.plist
    • start_jenkins_agent.sh 可统一管理 start|restart|stop|status
    • status 默认只显示关键状态，status --verbose 显示 launchctl 详情
    • 自动执行 launchctl bootout/bootstrap/kickstart，注册到 gui/<uid>（Aqua），不要加 sudo
    • 重装/卸载会同时尝试按 service target 与 plist path 执行 bootout，规避旧 LaunchAgent 卸不掉导致的 bootstrap 失败
    • 若默认服务名对应的 plist 已被其它 workDir 的 Agent 占用，会提示改名（推荐新建，建议名带 workDir 目录名）或覆盖，避免多个 Agent 共用同名 plist 互相覆盖
    • 若自动安装失败，回落写到 ${workDir}/<service>.plist 并提示手动安装命令
  • script 模式：
    • 仅生成 ${workDir}/start_jenkins_agent.sh
    • 不注册 launchctl 服务，由用户自行执行脚本启动
• Windows：${workDir}/start_jenkins_agent.bat
• 跨平台：安装后会更新 profile 记录，并写入 ${workDir}/agent-install.json
• 启动脚本直接包含完整 java -jar agent.jar ... 命令（含 Jenkins secret）

测试

npm test

发布前自检：

npm run verify
npm run pack:dry

已覆盖：

• Jenkins 启动命令解析（-url / -jnlpUrl）
• 脚本与 systemd/launchd 生成
• 白名单目标构造

常见问题

• Linux 安装 systemd 时会自动尝试 sudo cp/systemctl；若失败，请优先检查当前账号的 sudo 权限与 systemd 环境。
• macOS 首次运行可能触发系统权限弹窗（如辅助功能/屏幕录制等），请在图形会话中按提示授权。
• 白名单检查失败：优先确认 DNS、代理、防火墙与内网访问策略。

CI / 发布

• GitHub Actions
  • CI：.github/workflows/ci.yml
  • 发布：.github/workflows/publish.yml（push tag v* 或手动触发）
  • 发布 Runner：self-hosted + pytuyoo_pipeline
  • Secret：NPM_TOKEN
• GitLab CI
  • CI + 发布：.gitlab-ci.yml
  • 规则：tag 命中 vX.Y.Z 时执行 npm publish
  • Runner tag：pytuyoo_pipeline
  • Variable：NPM_TOKEN

详细发布步骤见 RELEASING.md。