新增 cx CLI 命令或 Coralogix API…

在 cx CLI 中添加新子命令或封装 Coralogix API 时，判断原型并完成 API 层、命令模块、CLI 接线、测试、技能与验证。

适用场景

解决思路

1. 阅读 docs/adding-a-command.md，它包含每一步的可复制代码模板；与工作流一起使用。
2. 先确定命令属于两种原型之一：A DataPrime-based 或 B REST-based，然后按对应步骤执行。
3. Step 0：写代码前先明确领域：要封装哪个 Coralogix API？找到 API 文档或示例响应，理解数据模型——有哪些实体、字段、支持哪些操作。
4. Step 0：明确用户应能做什么：列出子命令（如 list、get、create）以及合理的 flags。
5. Step 0：判断是否应归入 wrapper group。CLI 将相关命令组织为 wrapper groups；创建顶层命令前先检查现有分组：cx alerts（alert definitions + schedulers）、cx notifications（connectors、routers、presets、test）、cx webhooks（outgoing webhooks + actions）、cx enrichments（enrichment rules + custom enrichment tables）、cx integrations（integrations + extensions、contextual-data）、cx iam（api-keys、roles、scopes、users、groups、ip-access）。运行 cx schema 查看完整命令树 JSON。
6. Step 0：判断原型：A DataPrime-based——查询 logs、spans 或任何 DataPrime 源，参考实现 src/commands/logs/mod.rs；B REST-based——封装 Coralogix REST API（大多数新命令），参考实现 src/commands/alerts/api.rs + src/commands/alerts/mod.rs。
7. Step 0：理解原型差异：DataPrime 命令委托给共享 pipeline，代码量最小（约 130 行）；REST 命令构建完整 pipeline（API client、fan-out、merge、render），代码更多但控制力更强。
8. Step 0：所有 API 集成必须使用 REST（HTTP）。CLI 按设计仅支持 HTTP——不要使用 gRPC。
9. Step 1：写代码前先阅读参考实现以吸收现有模式；这一步很关键——先读现有代码的 agent 会产出一致实现，而不是发明新模式。
10. Step 1 必读：src/main.rs——研究 Commands enum 如何组织 variant，以及 match cli.command 分发块中新 variant 应放在哪里；注意哪些命令 early-exit（无需凭据），哪些走完整配置解析流程；注意 wrapper groups（如 Notifications、Iam、Webhooks、Integrations）是带嵌套子命令 enum 的顶层命令；如果命令属于现有分组，就把新 variant 加到该分组的子命令 enum，而不是创建顶层命令。
11. Step 1 必读：src/commands/mod.rs——查看现有模块注册，在正确位置添加你的模块。
12. Step 1 必读：docs/adding-a-command.md——两种原型的完整指南和代码模板。
13. Step 1 DataPrime 原型另读：src/commands/logs/mod.rs——一个完整 DataPrime 命令；注意共享 pipeline 承担主要工作，因此代码很少。
14. Step 1 DataPrime 原型另读：src/commands/dataprime/mod.rs——你的命令将委托的共享 pipeline；理解 run_query() 签名及其处理内容（fan-out、merge、spilling、agents output）。
15. Step 1 REST 原型另读：src/commands/alerts/api.rs——查看响应类型如何组织、API struct 如何借用 &CxClient、反序列化测试如何写。
16. Step 1 REST 原型另读：src/commands/alerts/mod.rs——查看 handler 如何声明 pub mod api; 以及如何通过 use api::{...}; 导入类型。
17. Step 1 REST 原型另读：src/commands/dashboards/mod.rs——查看使用 render::* helper 的 fan-out/merge/render 模式，以及三种输出格式如何处理。
18. Step 2（仅 REST）：DataPrime 命令跳过此步。创建 src/commands/<domain>/api.rs；完整模板见 docs/adding-a-command.md § "Archetype B, Step 1"。
19. Step 2：在响应类型上使用 #[serde(rename_all = "camelCase")]——Coralogix API 使用 camelCase JSON key。
20. Step 2：在 Vec 字段上使用 #[serde(default)]——API 有时完全省略空数组而不是发送 []，这可防止反序列化失败。
21. Step 2：对可能缺失的字段使用 Option<T>——保持防御性，API 会演进且字段可能因 tier 不同而变化。
22. Step 2：API struct 借用 &CxClient（不要拥有它）——client 在 fan-out 中共享，且必须比单次 API 调用活得更久。
23. Step 2：使用 const BASE_PATH 作为 endpoint 前缀——保持 URL DRY。
24. Step 2：反序列化测试是强制要求——测试 happy-path 和边缘情况（空列表、缺失可选字段），因为这些是生产中最容易出问题的场景。
25. Step 3：创建 src/commands/<domain>/mod.rs。对于 REST 命令，在顶部声明 pub mod api;，以便 handler 可以从同级 api.rs 使用 use api::{...}; 类型。完整模板见 docs/adding-a-command.md。
26. Step 3 DataPrime 原型：提供文本渲染器 pub fn render_<domain>_text(merged: &MergedResults) -> Result<()>——仅在 OutputFormat::Text 时调用；JSON 和 Agents 输出由共享 pipeline 处理。
27. Step 3 DataPrime 原型：提供薄 run() wrapper，用你的 DataPrime source name 调用 super::dataprime::run_query()。
28. Step 3 REST 原型：构建完整 fan-out/merge/render pipeline。
29. Step 3 REST 原型：文本输出用 render::render_table——传入列标题（不含 "Profile"）和行，行第一个元素是 profile name；helper 根据 include_profile 有条件包含 Profile 列；无需重复定义 struct。
30. Step 3 REST 原型：JSON 输出用 render::render_json——pretty-print &[Value] 数组。
31. Step 3 REST 原型：使用 let include_profile = targets.len() > 1;——这个单一 boolean 控制所有多 profile 行为（文本中的 Profile 列、JSON 中的 "profile" key）。
32. Step 3 REST 原型：fan-out 错误是非致命的——打印到 stderr 并继续，因为一个配置错误的 profile 不应阻塞其他 profile 的结果。
33. Step 3 REST 原型：状态消息发到 stderr（eprintln!）——stdout 保留给数据，避免污染管道输出。
34. Step 3 REST 原型：Agents 输出由命令自己负责——每个命令在后处理后直接调用 toon_encode，因为不同命令可能以不同方式转换数据后再编码。
35. Step 3：在 src/commands/mod.rs 注册模块。
36. Step 4：在 src/main.rs 添加三样东西；见 docs/adding-a-command.md § "CLI Wiring" 模板。
37. Step 4：添加 Commands enum variant——DataPrime 命令使用 inline args；REST 命令引用一个子命令 enum。
38. Step 4：添加 Subcommand enum（仅 REST）——定义 List、Get 等。
39. Step 4：添加 Dispatch match arm——在 match cli.command 块内。大多数命令走完整配置解析流程；只有无需凭据的命令（如 profiles、cleanup）才 early-exit。
40. Step 5：每个新命令必须添加三层测试；见 docs/adding-a-command.md § "Testing" 的代码模板和示例。
41. Step 5：Unit 测试位于 src/**/<file>.rs 的 #[cfg(test)]；验证纯逻辑——反序列化（REST 强制）、helper、transform。
42. Step 5：Integration 测试位于 tests/<command>/main.rs（wiremock）；用 mocked HTTP 端到端验证 command runner。
43. Step 5：E2E 测试位于 tests/e2e/<command>/mod.rs（assert_cmd，#[ignore]d）；用真实 cx binary 对 Coralogix test team 运行。
44. Step 5：不要为 mutating 命令（create/delete/enable/disable）添加 e2e，除非有配对的 undo 计划——它们会触碰共享 test team 状态；像 tests/e2e/alerts/mod.rs 那样用注释标记为故意未覆盖。
45. Step 5：如果子命令需要 test team 的 ID（例如 get <id>），在 e2e 测试模块中添加本地 discover_* fn，参照 tests/e2e/alerts/mod.rs 的 discover_alert_id；通过 OnceLock 缓存，并在 test team 无数据时优雅跳过——不要 panic。
46. Step 5：不要忘记在 tests/e2e.rs 中通过 #[path = "e2e/your_domain/mod.rs"] mod your_domain; 声明新的 e2e 模块。
47. Step 6：每个命令都需要在 skills/ 中有对应用户技能，让 AI agent 知道如何使用它；使用 add-skill workflow 创建，该流程包括阅读参考实现、写有效触发描述、验证。
48. Step 7：运行 cargo build、cargo test（unit + integration）、cargo clippy、cargo fmt --check；提交前修复所有问题。
49. Step 7：如果配置了 test team 凭据，运行 e2e suite：cargo test --test e2e -- --ignored --test-threads=1。
50. Step 7：冒烟测试所有三种输出格式（text、json、agents）和多 profile（-p profile1 -p profile2）。
51. Step 7：查看 docs/adding-a-command.md § "PR Checklist"，把完整 checklist 放进 PR 描述。

适用边界 · 注意事项

• 不适用于非 cx CLI 或非 Coralogix API 的通用 CLI 开发；该流程依赖 cx 代码库、Coralogix API 与内部约定。
• 不要为 DataPrime 查询类命令创建 REST API 层，应走共享 DataPrime pipeline。
• 不要为新增 API 集成使用 gRPC；cx CLI 设计为 HTTP-only。