codearts-cli

README

codearts-cli

华为云 CodeArts 命令行工具，为人类和 AI Agent 而建。覆盖流水线、工作项管理、代码托管三大模块共 10 个接口，配套 4 个 AI Agent Skills。

安装 · AI Agent Skills · 配置 · 命令速查 · 高级用法 · 测试 · 架构 · 贡献

为什么用 codearts-cli？

• Agent-Native 设计 — 4 个结构化 Skills，兼容 Claude Code / Cursor / Codex / Gemini CLI 等主流 AI 工具
• 轻量零依赖 — 不引入 huaweicloud-sdk-go-v3（几十 MB），自研 AK/SK 签名（SDK-HMAC-SHA256），单一二进制 ~3 MB
• 三模块十接口 — 流水线、工作项、代码托管，一条命令触发 CI/CD、管理 Bug、创建 MR
• Debug 友好 — 所有命令支持 --dry-run，预览 method / path / body 不发请求
• 安全可控 — AK/SK 存储 0600 权限，config show 自动脱敏，CI 场景用 --sk-stdin 防泄露
• 开源即用 — MIT 协议，npm install 一行安装

功能概览

模块	命令	API	说明
🚀 流水线	pipeline list	ListPipelines	查询流水线列表
🚀 流水线	pipeline run	RunPipeline	触发流水线
🚀 流水线	pipeline stop	StopPipelineRun	停止流水线实例
📋 工作项	issue list	ListIpdProjectIssues	查询工作项列表
📋 工作项	issue show	ShowIssueDetail	查询工作项详情
📋 工作项	issue create	CreateIpdProjectIssue	创建工作项
📋 工作项	issue batch-update	BatchUpdateIpdIssues	批量更新工作项
🔀 代码托管	repo list	ShowAllRepositoryByTwoProjectId	查询仓库列表
🔀 代码托管	repo mr create	CreateMergeRequest	创建合并请求
🔀 代码托管	repo mr comment	CreateMergeRequestDiscussion	创建 MR 检视意见

安装

前置依赖

• Node.js (npm/npx)
• Go v1.23+（仅从源码构建时需要）

快速开始（人类用户）

AI Agent 提示： 如果你是 AI Agent 正在帮用户安装，直接跳到 快速开始（AI Agent）。

安装

选择一种方式：

方式 1 — npm 安装（推荐）：

# 安装 CLI
npm install -g @autelrobotics/codearts-cli

# 安装 AI Agent Skills（可选但推荐）
npx skills add Lzhtommy/codearts-cli -y -g

方式 2 — 从源码构建：

需要 Go v1.23+。

git clone https://github.com/Lzhtommy/codearts-cli.git
cd codearts-cli
make install PREFIX=$HOME/.local

# 安装 AI Agent Skills（可选）
npx skills add Lzhtommy/codearts-cli -y -g

配置 & 使用

# 1. 配置凭证（交互式，SK 不回显）
codearts-cli config init

# 2. 查看配置
codearts-cli config show

# 3. 开始使用
codearts-cli pipeline run <pipeline_id> --project-id <project_id>
codearts-cli issue list --issue-type Bug

快速开始（AI Agent）

以下步骤面向 AI Agent。部分步骤需要用户在终端中完成交互。

Step 1 — 安装

npm install -g @autelrobotics/codearts-cli
npx skills add Lzhtommy/codearts-cli -y -g

Step 2 — 配置凭证

交互式：用户需要在终端输入 AK、SK（不回显）、Project ID、Region、User ID。

codearts-cli config init

非交互（CI）：

echo "$HW_SK" | codearts-cli config init --ak "$HW_AK" --sk-stdin --project-id <uuid> --user-id <uuid> --yes

Step 3 — 验证

codearts-cli config show
codearts-cli issue list --issue-type Bug --dry-run

Agent Skills

Skill	说明
codearts-shared	配置初始化、凭证管理、通用标志、端点解析、错误处理（被其它 skill 自动引用）
codearts-pipeline	流水线列表 / 启动 / 停止
codearts-issue	工作项查询 / 详情 / 创建 / 批量更新
codearts-repo	仓库列表 / MR 创建 / MR 检视意见

# 安装全部 skills
npx skills add Lzhtommy/codearts-cli -y -g

# 仅安装特定 skill
npx skills add Lzhtommy/codearts-cli -s codearts-pipeline -y -g

配置

config init

交互式初始化，依次输入 5 项：

#	字段	必填	说明
1	AK	是	IAM Access Key ID
2	SK	是	IAM Secret Access Key（输入时不回显）
3	Project ID	默认	CodeArts 项目 UUID（仅工作项接口使用此默认值）
4	Region	默认	如 cn-south-1
5	User ID	可选	IAM user_id（32 位 UUID），issue create 默认 assignee

config set <key> <value>

修改单个字段，无需走完整 init 流程：

codearts-cli config set userId <uuid>
codearts-cli config set region cn-north-4

可用 key：ak / sk / projectId / region / userId

config show / config path

codearts-cli config show    # 打印配置（AK 脱敏、SK 全掩）
codearts-cli config path    # 打印配置文件绝对路径

配置文件：~/.codearts-cli/config.json（权限 0600）。

命令速查

流水线

pipeline list — 查询流水线列表

# 列出项目下所有流水线
codearts-cli pipeline list --project-id <proj>

# 按名称过滤 + 分页
codearts-cli pipeline list --project-id <proj> --name "deploy" --limit 20

Flag	说明
--project-id（必填）	华为云项目 UUID
--name	按名称模糊匹配
--status	按状态过滤（可重复）
--creator-id / --executor-id	按创建人/执行人过滤（可重复）
--offset / --limit	分页
--sort-key / --sort-dir	排序（asc / desc）
--dry-run	预览请求

pipeline run <pipeline_id> — 启动流水线

# 使用默认参数
codearts-cli pipeline run <pid> --project-id <proj>

# 指定源分支
codearts-cli pipeline run <pid> --project-id <proj> \
  --sources '[{"type":"code","params":{"build_type":"branch","target_branch":"main"}}]'

# 注入变量
codearts-cli pipeline run <pid> --project-id <proj> \
  --variables '[{"name":"ENV","value":"staging"}]'

Flag	说明
--project-id（必填）	华为云项目 UUID
--sources / --sources-file	源覆盖 JSON 数组
--variables / --variables-file	变量 JSON 数组
--body / --body-file	完整请求体
--description / --choose-job / --choose-stage	备注 / 指定 job / stage
--dry-run	预览请求

pipeline stop <pipeline_id> <pipeline_run_id> — 停止流水线

codearts-cli pipeline stop <pid> <run_id> --project-id <proj>

工作项管理

工作项命令统一使用 config.json 的 projectId，不支持 --project-id。若未配置，先执行 codearts-cli config set projectId <uuid>。

issue list — 查询列表

codearts-cli issue list --issue-type US,Task --page-no 1 --page-size 50

Flag	说明
--issue-type（必填）	逗号分隔：RR/SF/IR/US/Task/Bug/Epic/FE/SR/AR
--filter / --filter-file	过滤条件 JSON
--page-no / --page-size	分页
--sort-field / --sort-asc	排序

issue show <issue_id> — 查询详情

codearts-cli issue show <id> --issue-type US

issue create — 创建工作项

codearts-cli issue create --title "修复登录超时" --description "..." --category Bug

--assignee 省略时自动取 config 中的 userId。

issue batch-update — 批量更新

codearts-cli issue batch-update --id 111,222,333 --category Bug --attribute '{"priority":"中"}'

代码托管

<repository_id> 必须是正整数（数字仓库 ID），不是 UUID。可通过 repo list 获取。

repo list — 查询仓库列表

# 列出项目下所有仓库（返回每个仓库的 repository_id）
codearts-cli repo list --project-id <proj>

# 按名称搜索
codearts-cli repo list --project-id <proj> --search "backend"

Flag	说明
--project-id（必填）	项目 UUID（可从 git remote -v 提取）
--search	按仓库名或创建人搜索
--page-index / --page-size	分页（默认 20 条/页）
--dry-run	预览请求

repo mr create <repo_id> — 创建合并请求

codearts-cli repo mr create 8147520 \
  --title "feat: x" --source feat/x --target main \
  --reviewers "uid-a,uid-b" --squash --force-remove-source

Flag	说明
--title / --source / --target（必填）	标题 / 源分支 / 目标分支
--reviewers / --assignees	逗号分隔 user_id
--work-item	关联工作项 ID（可重复）
--squash / --force-remove-source	合并选项
--body-json / --body-file	完整 JSON body

repo mr comment <repo_id> <mr_iid> — 检视意见

codearts-cli repo mr comment 8147520 15 --body "LGTM" --severity suggestion

高级用法

Dry Run

所有命令支持 --dry-run，打印 method / path / query / body 但不发请求：

codearts-cli pipeline run <pid> --project-id <proj> --dry-run
codearts-cli issue create --title "x" --description "x" --category Bug --dry-run

端点覆盖

各模块按 region 自动推导端点；需要时用环境变量覆盖（如抓包调试、私有化部署）：

模块	默认主机	环境变量
流水线	cloudpipeline-ext.<region>.myhuaweicloud.com	CODEARTS_PIPELINE_ENDPOINT
工作项管理	projectman-ext.<region>.myhuaweicloud.com	CODEARTS_PROJECTMAN_ENDPOINT
代码托管	codehub-ext.<region>.myhuaweicloud.com	CODEARTS_REPO_ENDPOINT

project-id 作用域

模块	--project-id	config.json projectId
流水线	必填	不读
工作项管理	不支持	必读
代码托管	repo list 必填；mr 命令走 repo_id	repo list 不读

提示：在 CodeArts Repo 克隆的仓库目录下，可从 git remote -v 自动提取 project-id：

PROJECT_ID=$(git remote -v | grep codehub | head -1 | grep -oE '[a-f0-9]{32}' | head -1)

测试

单元测试集中在 tests/ 目录下，按模块组织：

# 运行全部测试
go test ./tests/...

# 运行单个模块
go test ./tests/client/    # 签名 + HTTP 客户端
go test ./tests/core/      # 配置加载/保存/校验
go test ./tests/output/    # JSON 输出格式
go test ./tests/cmd/       # CLI 工具函数

# 带详细输出
go test ./tests/... -v

# 跑完整项目（含 tests/）
go test ./...

测试模块	文件	用例数	覆盖点
tests/client/	signer_test.go	11	HashHex / HmacHex / CanonicalURI / CanonicalQuery / CanonicalHeaders / Sign
tests/client/	client_test.go	7	Do 成功 / 400 / 401 hint / 500 raw / 空响应 / POST body / 缺凭证
tests/core/	config_test.go	10	Validate / Redacted / MaskLeft / Save+Load 往返 / 默认值 / 兼容性
tests/output/	output_test.go	5	PrintJSON / Successf / Errorf / DryRunf
tests/cmd/	helpers_test.go	14	ParseRepoID / ExtractStringFromResp / FirstNonEmpty
合计		47

HTTP 测试使用 httptest.Server 模拟 API，文件 I/O 测试使用 t.TempDir() + 临时 $HOME，不依赖外部服务。

项目结构

codearts-cli/
├── main.go                           # 入口
├── Makefile                          # build / install / dist / npm-link
├── package.json                      # npm 包描述
├── .goreleaser.yml                   # 跨平台编译配置
├── scripts/
│   ├── install.js                    # npm postinstall：下载预编译二进制
│   └── run.js                        # npm bin 入口：exec Go 二进制
├── skills/
│   ├── codearts-shared/SKILL.md      # AI Skill: 配置 / 认证 / 通用
│   ├── codearts-pipeline/SKILL.md    # AI Skill: 流水线
│   ├── codearts-issue/SKILL.md       # AI Skill: 工作项
│   └── codearts-repo/SKILL.md        # AI Skill: 代码托管
├── tests/
│   ├── client/                       # 签名 + HTTP 客户端测试
│   ├── core/                         # 配置测试
│   ├── output/                       # 输出格式测试
│   └── cmd/                          # CLI 工具函数测试
├── cmd/
│   ├── root.go                       # 根命令
│   ├── config.go                     # config init / show / path / set
│   ├── pipeline.go                   # pipeline list / run / stop
│   ├── issue.go                      # issue list / show / create / batch-update
│   └── repo.go                       # repo list / mr create / mr comment
└── internal/
    ├── core/config.go                # 配置加载 / 保存（~/.codearts-cli/config.json）
    ├── client/
    │   ├── signer.go                 # SDK-HMAC-SHA256 AK/SK 签名
    │   ├── client.go                 # HTTP 封装 + 三服务端点推导
    │   ├── pipeline.go               # 流水线 API
    │   ├── projectman.go             # 工作项 API
    │   └── repo.go                   # 代码托管 API
    └── output/output.go              # JSON 输出 + 成功 / 错误消息

扩展新 API

1. 如果是新服务域，在 internal/client/client.go 加 XxxEndpoint() 方法
2. 在 internal/client/*.go 加接口方法，调用 c.Do(ctx, method, endpoint, path, query, body, &out)
3. 在 cmd/ 加 cobra 子命令，参考 --dry-run 模式
4. 在 cmd/root.go 注册

已踩坑记录：

• 华为 APIGW 签名的 CanonicalURI 必须以 / 结尾
• POST 即使无参数也必须发 {}（否则 PARSE_REQUEST_DATA_EXCEPTION）
• 401 APIGW.0301 会回显服务端 canonical_request，直接 diff 即可定位

贡献

欢迎社区贡献！如果发现 Bug 或有功能建议，请提交 Issue 或 Pull Request。

重大变更建议先通过 Issue 讨论。

License

本项目基于 MIT License 开源。运行时调用华为云 CodeArts 平台 API，使用前请遵守 华为云服务协议 和 华为云隐私政策。

Documentation

Overview

codearts-cli — Huawei Cloud CodeArts CLI (Go implementation).

A lightweight CLI wrapping the CodeArts SDK for common CI/CD workflows (currently the CodeArtsPipeline RunPipeline API).