处理 TeamCity CI/CD 或排查构建失败时用…

当处理 TeamCity CI/CD 或用户提供 TeamCity 构建 URL 时，使用 teamcity CLI 执行构建、日志、任务、队列、代理、池、项目和流水线操作。

适用场景

解决思路

1. 用 `teamcity auth status` 检查认证。
2. 用 `teamcity run list --status failure` 查找失败构建。
3. 用 `teamcity run log <id> --failed --raw` 获取完整失败诊断。
4. 不要猜测 flags 或语法；使用 references/commands.md 或 `teamcity <command> --help`。
5. 记住构建是 runs（`teamcity run`）；构建配置是 jobs（`teamcity job`）。
6. 永远不要使用 `--count`；使用 `--limit`（或 `-n`）。
7. 复合构建日志为空时，深入子构建获取实际失败。
8. 构建链自底向上失败时，最深的失败依赖是根因；使用 `teamcity run tree <id>`。
9. `--local-changes` 不包含 Kotlin DSL；运行前推送 `.teamcity/` 更改。
10. 仅设置 `TEAMCITY_URL` 会绕过存储的认证；同时设置 `TEAMCITY_URL` 和 `TEAMCITY_TOKEN`，或者都不设置。
11. 处理日志时使用 `--raw` 并转储到临时文件；启动构建时使用 `--watch`。
12. VCS 触发器不一定接好；推送修复后可能需要手动启动构建。
13. `pipeline push` 不验证；总是先执行 `teamcity pipeline validate`。
14. GitHub VCS roots 使用 GitHub App 连接；绝不要通过 `--auth password` 粘贴 PAT；见 references/workflows.md。
15. 认证命令：`auth login`、`auth logout`、`auth status`。
16. 构建命令：`run list`、`run view`、`run start`、`run watch`、`run log`、`run cancel`、`run restart`、`run tests`、`run changes`、`run tree`。
17. 制品命令：`run artifacts`、`run download`。
18. 元数据命令：`run pin/unpin`、`run tag/untag`、`run comment`。
19. 任务命令：`job list`、`job view`、`job create`、`job tree`、`job pause/resume`、`job step list/view/add/delete`、`job param list/get/set/delete`、`job settings list/get/set`。
20. 项目命令：`project list`、`project view`、`project create`、`project tree`、`project param`、`project token put/get`、`project settings export/status`。
21. VCS/连接命令：`project vcs list/view/create/delete`、`project connection list/create/authorize/delete`。
22. 队列命令：`queue list`、`queue approve`、`queue remove`、`queue top`。
23. 代理命令：`agent list`、`agent view`、`agent enable/disable`、`agent authorize/deauthorize`、`agent exec`、`agent term`、`agent reboot`、`agent move`。
24. 池命令：`pool list`、`pool view`、`pool link/unlink`。
25. 流水线命令：`pipeline list`、`pipeline view`、`pipeline create`、`pipeline validate`、`pipeline pull`、`pipeline push`、`pipeline schema`、`pipeline delete`。
26. API：`teamcity api <endpoint>` 进行原始 REST 访问。
27. 链接：`teamcity link` 通过 `teamcity.toml` 绑定仓库。
28. 调查失败：`run list --status failure` → `run log <id> --failed --raw` → `run tests <id> --failed`。
29. 调试构建链：`run tree <id>` → 深入到最深的失败子构建。
30. 修复并验证：编辑 → 推送 → `run start --watch`（个人构建使用 `--local-changes`）。
31. 流水线生命周期：`pipeline pull <id>` → 编辑 → `pipeline validate` → `pipeline push <id>`；用 `pipeline schema` 从服务器获取实际 schema。
32. GitHub VCS：`connection create github-app` → `connection authorize` → 在仓库安装 App → `vcs create --auth token --connection-id <id>`。
33. Docker registry：`echo $TOKEN | connection create docker -p <id> --name X --url https://ghcr.io --username U --stdin`。
34. 参考文档：references/commands.md 包含所有命令和 flags。
35. 参考文档：references/workflows.md 包含失败调查、构建链、连接、流水线。
36. 参考文档：references/output.md 包含 JSON、纯文本、脚本输出格式。

适用边界 · 注意事项

• 未安装并认证 `teamcity` CLI 或没有可访问的 TeamCity 实例时。
• 处理非 TeamCity CI/CD 系统（如 Jenkins、GitHub Actions、GitLab CI）时。
• 无法设置或提供 `TEAMCITY_URL` 和 `TEAMCITY_TOKEN` 认证时。