@kmfe/devflow

@kmfe/devflow

A CLI toolkit for Kanjian Music's development workflows.

@kmfe/devflow 通过统一的 kdev 命令入口提供公司开发工具。当前可用的集成是 GitLab。

安装

要求 Node.js 24.18.0 或更高版本。

npm install --global @kmfe/devflow
kdev --version

也可以不安装，直接通过 npx 运行：

npx --yes @kmfe/devflow --version
npx --yes @kmfe/devflow gitlab --help

在使用旧版 Node.js 的项目中，可以只为当前命令临时使用 Node.js 24：

nvm exec --silent 24.18.0 -- npx --yes @kmfe/devflow -h

nvm exec 只影响本次调用，不会切换当前 shell 的 Node.js 版本。

命令发现

使用逐级 --help 查看当前可用命令和完整参数：

kdev --help
kdev gitlab --help
kdev gitlab project --help

安全写入

所有会修改本地配置或远端资源的命令都支持 --dry-run。建议首次执行写操作时先使用 dry-run，确认目标和预期变更后再执行真实写入。

GitLab

GitLab 集成用于管理公司 GitLab 的鉴权、项目和平台侧配置。

鉴权

首次使用前，先在公司 GitLab 的 Personal Access Tokens 页面创建 Token，并在“选择范围”中至少勾选 api；当前工具不要求其他 scope。然后由用户在交互式终端登录：

kdev gitlab auth login

Token 通过隐藏输入读取，验证成功后保存在本机。CLI 不接受通过命令参数、环境变量或管道传入登录 Token。

命令	说明
kdev gitlab auth login	验证并保存 Token
kdev gitlab auth status	验证当前鉴权并返回用户信息
kdev gitlab auth logout	删除本机保存的鉴权

项目定位

需要已有项目的命令默认读取当前 Git 仓库的 origin。也可以使用 --project 指定项目 ID、namespace/path 或 GitLab URL，使用 --cwd 从其他目录读取 origin。

kdev gitlab project get
kdev gitlab project get --project fe/example
kdev gitlab project get --cwd ../example

项目

命令	说明
kdev gitlab project get	查询项目常用信息
kdev gitlab project create	创建项目
kdev gitlab project edit	修改项目名称、路径或描述

创建项目前可以先执行 dry-run：

kdev gitlab project create \
  --namespace fe \
  --name example \
  --path example \
  --visibility private \
  --initialize-with-readme false \
  --dry-run

Auto DevOps

命令	说明
kdev gitlab project auto-devops get	查询 Auto DevOps 状态和部署策略
kdev gitlab project auto-devops set	修改 Auto DevOps 设置

kdev gitlab project auto-devops set --enabled true --dry-run

合并设置

命令	说明
kdev gitlab project merge-settings get	查询合并方式和合并条件
kdev gitlab project merge-settings set	修改合并设置

kdev gitlab project merge-settings set \
  --project fe/example \
  --merge-method rebase_merge \
  --require-pipeline-success true \
  --dry-run

CI/CD Variables

命令	说明
kdev gitlab variable list	列出项目变量及实际值
kdev gitlab variable get <key>	查询一个变量及实际值
kdev gitlab variable set <key> <value>	创建或更新一个变量
kdev gitlab variable delete <key>	删除一个变量

变量值作为普通业务数据传入。包含空格或 shell 特殊字符时应正确引用：

kdev gitlab variable set NODE_VERSION 24.18.0 \
  --project fe/example --dry-run

新变量使用 GitLab 默认的 env_var 类型。CLI 当前不提供 file 类型选择或从本地文件读取变量值的功能。

list、get 和 set 返回变量实际值。变量的访问范围和敏感数据策略由 GitLab 权限及使用团队负责。

输出

除帮助、版本和登录输入提示外，命令向 stdout 输出一个单行 JSON 对象。

调用方先判断 ok：成功时读取 data 和 meta，失败时使用稳定的 code 判断错误，并结合 message 理解具体原因。

写操作通过 data.action、data.changed 和 meta.dry_run 说明是否存在变更以及本次是否实际写入。目标已经符合要求时，命令成功返回 no-op。