ado-axi

ado-axi

基于 Azure DevOps REST API、便于 Agent 使用的 CLI。通过配置文件管理多个组织；每个配置文件都包含各自的组织、项目和身份验证方式（Azure CLI 登录或个人访问令牌）。

日常使用时，通过 npm install -g @jeffreyhaen/ado-axi 进行全局安装。如果 ado-axi 不在 PATH 中，请在命令前加上 npx -y @jeffreyhaen/ado-axi。

概览

先运行不带参数的 ado-axi。它会显示当前启用的配置文件、未关闭的工作项、项目中处于活动状态的拉取请求（active-pull-requests）以及最近的流水线运行记录。

ado-axi                      # dashboard
ado-axi config list          # configured profiles
ado-axi doctor               # authentication check per profile
ado-axi project list         # projects (30 most recently updated; --name <filter>, --limit N)

选择组织、项目和配置文件

每条命令都接受以下参数，它们不会被视为未知标志：

• --profile <name> — 已配置的配置文件（ado-axi config list）；也可以写在命令前面（ado-axi --profile acme pr list），裸仪表板命令也支持此用法
• --org <org> / --project <project> — 单次覆盖项；若 --org 与某个已配置的配置文件匹配，则会继承该配置文件的身份验证方式。组织根 URL（https://dev.azure.com/<org> 或 https://<org>.visualstudio.com）也可使用；不要包含项目/API 路径
• $ADO_AXI_ORG / $ADO_AXI_PROJECT — 环境变量覆盖项

对于粘贴的 PR 网页 URL，请提取组织、项目、仓库和 ID，并显式传入。 根据任务或特定项目的配置文件确定组织/项目，并在整个会话中沿用。如果缺少项目上下文，请使用 ado-axi project list --org <org>；如果仍无法确定目标项目，请询问用户。切勿随意选择项目，尤其是在执行变更操作时。

工作项

ado-axi work-item list [--state open|all|<State>] [--type <type>] [--assigned-to @me|<name>]
                       [--iteration @current|<path>] [--area <path>] [--tag <tag>] [--search <text>]
                       [--query "<raw WIQL>"] [--limit 30]
ado-axi work-item get <id> [--comments] [--full]       # includes `rev` for compare-and-swap
ado-axi work-item create --type Task --title "..." [--description "..."] [--description-format markdown|html]
                         [--assigned-to <user>] [--parent <id>] [--area <path>] [--iteration <path>] [--tags "a; b"]
ado-axi work-item update <id> [--state <state>] [--title "..."] [--assigned-to <user>]
                              [--description "..."] [--description-format markdown|html]
                              [--add-tags a,b] [--remove-tags c] [--if-rev <n>]
                              [--set '{"Microsoft.VSTS.Common.Priority": 1}']
ado-axi work-item comment <id> [--body "..."] [--format markdown|html]
ado-axi work-item link list <id> [--limit 50]
ado-axi work-item link add <id> (--parent <id> | --child <id> | --related <id> | --pr <id>
                                 | --commit <40-hex> --repo <name> | --branch <name> --repo <name>)
                                [--comment "..."] [--if-rev <n>]

link list 会将层级链接解析为工作项 ID，将制品链接解析为拉取请求 ID、短提交 SHA 和分支名称。link add 会为你构建 vstfs:// 制品 URI — 传入拉取请求 ID，而不是 URL — 如果链接已存在，则不执行任何操作。

list 会为你构建 WIQL；对于标志无法表达的查询，请改用 --query。 --description-format markdown 会以 Markdown 格式呈现描述；仅在提供 HTML 时才使用 html。只有在提供描述时才会应用此格式。 默认情况下，work-item comment 会将评论保存为 Markdown；仅在提供原始 HTML 时才使用 --format html。评论 API 要求版本为 7.1-preview.4 或更高，才能选择此格式。 update 具有幂等性 — 将字段设为当前值时会报告不执行任何操作，并以 0 退出。

安全并发更新

--if-rev <n> 会将更新转为比较并交换操作：补丁会包含 JSON-Patch {"op":"test","path":"/rev"}，因此写入只会应用于完全匹配的修订版本，否则会失败并返回 PRECONDITION_FAILED — 不会发生静默重复认领。通过 work-item get 读取 rev。 --if-rev 也会禁用幂等无操作跳过，因此总会写入指定字段。

--add-tags / --remove-tags 会就地修改标签列表（不区分大小写，并去重），而不是替换 System.Tags，因此不会丢失无关标签。它们不能与会替换整个字符串的 --tags 一起使用。

ado-axi work-item get 4211                  # read `rev` from the output
ado-axi work-item update 4211 --assigned-to [email protected] --add-tags agent-claimed --if-rev 7

拉取请求

ado-axi pr list [--repo <repo>] [--status active|draft|completed|abandoned|all] [--creator @me]
                [--reviewer @me] [--target <branch>] [--limit 30]
ado-axi pr get <id> [--threads] [--full]   # --full = complete description AND comment text
ado-axi pr comments <id> [--full]          # alias for `pr get <id> --threads`
ado-axi pr create --repo <repo> --source <branch> [--target main] --title "..." [--description "..."]
                  [--reviewers a,b] [--draft] [--work-items 1,2]
ado-axi pr update <id> [--title "..."] [--description "..."] [--draft true|false]
                       [--auto-complete true|false]
ado-axi pr complete <id> [--squash true|false] [--delete-source-branch true|false]
ado-axi pr abandon <id>
ado-axi pr checks <id> [--limit 10] [--full]
ado-axi pr diff <id> [--limit 20] [--full]
ado-axi pr reviewer list <id>
ado-axi pr reviewer add|remove <id> --reviewer <identity> [--required]
ado-axi pr approve <id> [--vote approve|approve-with-suggestions|wait-for-author|reject|reset]
ado-axi pr comment <id> [--body "..."] [--file <path> --line <n>] [--thread <id>]
ado-axi pr thread list <id> [--limit 20] [--full]
ado-axi pr thread reply <id> --thread <n> [--body "..."] [--resolve]
ado-axi pr thread resolve|reopen <id> --thread <n> [--status active|fixed|wont-fix|closed|by-design|pending]

使用 pr thread 处理完审查反馈：list 会提供线程 ID 和 unresolved 计数；reply --resolve 会在一次调用中回复并关闭线程；如果 resolve/reopen 的状态已设置，则会报告不执行任何操作。

安全地输入 Shell 内容

对于 Markdown 或多行注释内容，请将带引号的 heredoc 通过管道传递到 stdin，供 work-item comment、pr comment 和 pr thread reply 使用；省略 --body：

ado-axi pr thread reply 812 --thread 5 --resolve <<'EOF'
Fixed in `3f2a1c9`: `$value` is now validated.
EOF

不要对包含反引号、$、! 或引号的标志值使用双引号。Git Bash 会在 ado-axi 启动前展开这些字符，因此 CLI 收到的输入虽然有效，却已被篡改，无法检测到这一问题。--title、--description、--set、--variables、--parameters 和 --query 也同样如此：命令支持时请使用 stdin，否则将完整的 JSON 负载通过管道传递给 ado-axi api。

pr list 会显示评审统计（2/3 approved），无需再调用其他命令来判断状态。省略 --description 时，可以通过管道传递工作项和 PR 的描述。pr update 和评审者变更会将安全检测到的重试报告为无操作。pr complete 使用当前源提交，绝不绕过策略，并将已完成的 PR 视为无操作。pr abandon 将已弃用的 PR 视为无操作。完成 PR 前运行 pr checks，查看简明的策略／状态统计；只有有界的可操作列表不够用时，才使用 --full。

Git Bash 仓库路径

在 Windows 上，即使加了引号，Git Bash 也会转换以 / 开头的仓库路径。请在行内注释命令前加上 MSYS_NO_PATHCONV=1，确保 --file 原样传递给 Azure DevOps。

示例：

MSYS_NO_PATHCONV=1 ado-axi pr comment 812 --file '/src/Project/File.cs' --line 10 --body '...'

如果不加此前缀，CLI 会还原 Git for Windows 转换过的路径。创建线程前，CLI 会拒绝其他 Windows 路径以及 /bin 或 /usr/bin 下的路径。

流水线

ado-axi pipeline list [--name <filter>]
ado-axi pipeline runs [--pipeline <id>] [--branch <branch>] [--result failed] [--limit 20]
ado-axi pipeline run --pipeline <id> [--branch <branch>] [--variables '{"k":"v"}']
ado-axi pipeline logs <run-id> [--log <log-id>] [--tail 120] [--full] [--failed-only]
ado-axi pipeline timeline <run-id> [--limit 20] [--full]
ado-axi pipeline watch <run-id> [--interval 10] [--timeout 1800]

watch 使用秒作为单位，拒绝小于 2 秒的间隔，并在身份验证、HTTP 请求和响应正文处理中执行截止时间限制（默认 30 分钟）。失败、取消、超时和意外结果都会以 TOON 输出并返回非零退出码。

logs 默认返回最近一次日志的末尾内容；要查看特定步骤，请传入 --log <id>。

运行失败时，请先查看 timeline：它会指出失败的阶段／作业／步骤，包含首个错误问题，并提供要读取的日志 id。logs --failed-only 会直接读取该步骤的日志。

测试

ado-axi test results <run-id> [--outcome failed|passed|aborted|not-executed|all] [--limit 20] [--full]
ado-axi test results --run <test-run-id>

<run-id> 是流水线运行 id。所有已发布测试运行的页面都会计入总数；结果计数与 --outcome 相符。--limit 限制显示的结果数，不限制总数。--full 会展开错误消息，但不会提高该限制。构建失败时，test results 通常能回答出了什么问题，而 pipeline logs --failed-only 则能回答为什么。

仓库

ado-axi repo list [--name <filter>]
ado-axi repo branches --repo <name> [--name <filter>]
ado-axi repo file <path> --repo <name> [--ref <branch> | --commit <40-hex>] [--limit <lines>] [--full]
ado-axi ref list --repo <name> [--name <prefix>] [--limit 50] [--full]
ado-axi ref create --repo <name> --name <branch> (--source <branch> | --source-object-id <40-hex>)
ado-axi ref delete --repo <name> --name <branch> [--old-object-id <40-hex>]

repo file 直接从 Azure DevOps 读取单个文件：默认分支、分支最新提交（--ref）或指定修订版本（--commit）。可用它读取工作副本之外的文件，例如其他仓库中的文件，或正在评审的文件在目标分支上的版本。文件夹和二进制文件会被拒绝，路径格式与 pr comment --file 相同，为 /src/Project/File.cs。

创建引用不会覆盖已有分支。删除操作会解析指定分支，并使用其当前对象 ID 作为 Azure DevOps 并发保护；--old-object-id 还会断言先前观察到的版本。分支已指向预期对象或已不存在时，请求均视为无操作。

应急通道

没有专用命令的功能——Wiki、测试计划、代码搜索、构件、安全性——都通过原始 REST 桥接处理：

ado-axi api _apis/wiki/wikis
ado-axi api _apis/testplan/plans --query 'filterActivePlans=true'
ado-axi api POST _apis/search/codesearchresults --host almsearch --body '{"searchText":"TODO"}'
cat payload.bin | ado-axi api POST _apis/wit/attachments --query 'fileName=payload.bin' --content-type application/octet-stream
ado-axi api _apis/projects --no-project           # organization-level path
ado-axi api 'https://vsrm.dev.azure.com/acme/Platform/_apis/release/releases?api-version=7.1'
ado-axi api PATCH _apis/wit/workitems/4211 --content-type json-patch \
  --body '[{"op":"test","path":"/rev","value":7},{"op":"add","path":"/fields/System.State","value":"Active"}]'

相对路径使用 https://dev.azure.com/<org>/<project>/；--host 用于选择 dev（默认）、vsrm、vssps 或 almsearch。这四个主机上的完整 HTTPS REST URL 也可使用：URL 中的组织／项目／主机／查询参数会替代默认上下文，并使用匹配的配置文件进行身份验证。冲突的标志或来自其他组织的 --profile 会被拒绝；请勿覆盖 URL 上下文。带查询参数的 URL 请加引号。省略 --body 且 stdin 有管道输入时，stdin 会原样作为请求正文发送。--content-type 接受简写形式 json（默认）、json-patch、merge-patch、text，也接受任意媒体类型；工作项写入要求使用 json-patch。

约定

• 在 ADO 描述/评论中，#123 表示工作项，!123 表示 Azure DevOps PR； 对于 GitHub PR，请使用完整 URL，绝不要只写 #123 或 !123，即使 Boards/管道在 ADO 中运行也是如此。
• 标准输出为 TOON；错误也以 TOON 格式输出，并附带一个列出后续步骤的 help 列表。
• 退出代码：0 表示成功（包括无操作），1 表示运行时错误，2 表示用法错误。
• 遇到未知标志时会按名称拒绝 — 阅读 help 行并重试一次。
• 列表使用 --limit 和 --fields a,b；详情视图会截断，使用 --full 可查看完整内容。
• 在 Windows/Git Bash 上，切勿通过 .cmd 垫片将较大或多行内容作为内插的 CLI 参数传递，例如 --description "$(cat file)"；cmd.exe 可能会将其截断。 请改用管道：cat file | ado-axi work-item update <id> 或 cat file | ado-axi api POST <path> --content-type <media-type>。
• 会更改实际状态的命令（create、update、complete、reviewer add/remove、ref create/delete、comment、approve、pipeline run）— 仅在用户提出要求时才运行。
• 绝不要使用 PR 完成操作绕过策略，也绝不要删除目标不明确的 ref。