用途
add-command 是一个面向开发者(及 AI 代理)的工作流技能,用于向 Coralogix 的 cx CLI 添加新命令。触发条件包括用户要求“添加一个命令”“实现 cx <某功能>”“新子命令”“扩展 CLI”“集成 Coralogix API”等;即使用户描述的功能隐含需要新命令而未明确说“命令”,也应使用本技能。
主要能力与流程
技能提供了一条从需求理解到验证提交的端到端工作流,每一步都有对应说明,并指向 docs/adding-a-command.md 中可复制粘贴的代码模板。
Step 0:理解要构建的内容
在写代码前先厘清领域:要封装哪个 Coralogix API、其数据模型(实体、字段、支持的操作);用户应能做什么(列出子命令如 list、get、create 及合理的标志);命令是否应归入已有的包装组,例如:
cx alerts- 告警定义 +schedulerscx notifications-connectors、routers、presets、testcx webhooks- 出站 webhook +actionscx enrichments- 富化规则 +custom富化表cx integrations- 集成 +extensions、contextual-datacx iam-api-keys、roles、scopes、users、groups、ip-access
可运行 cx schema 以 JSON 形式查看完整命令树。
之后判断适合哪种命令原型:
| 原型 | 适用场景 | 参考实现 |
|---|---|---|
| A:基于 DataPrime | 查询日志、span 或任何 DataPrime 数据源 | src/commands/logs/mod.rs |
| B:基于 REST | 封装 Coralogix REST API(大多数新命令) | src/commands/alerts/api.rs + src/commands/alerts/mod.rs |
DataPrime 命令委托给共享管线,代码量极少(约 130 行);REST 命令需构建完整管线(API 客户端、扇出、合并、渲染),代码更多但控制力更强。所有 API 集成必须使用 REST(HTTP),CLI 按设计仅支持 HTTP,不使用 gRPC。
Step 1:阅读参考实现
写代码前先阅读现有文件以吸收既有模式,这是关键步骤,可避免发明新模式而导致实现与代码库不一致。必读:src/main.rs(Commands 枚举、分发块、哪些命令提前退出、包装组结构)、src/commands/mod.rs、docs/adding-a-command.md。DataPrime 原型还需读 src/commands/logs/mod.rs 与 src/commands/dataprime/mod.rs;REST 原型还需读 src/commands/alerts/api.rs、src/commands/alerts/mod.rs、src/commands/dashboards/mod.rs。
Step 2:创建 API 层(仅 REST)
DataPrime 命令跳过此步。创建 src/commands/<domain>/api.rs,关键约定包括:响应类型使用 #[serde(rename_all = "camelCase")];Vec 字段加 #[serde(default)];可能缺失的字段用 Option<T>;API 结构借用 &CxClient;用 const BASE_PATH 定义端点前缀;反序列化测试为必需,覆盖正常路径与边界情况(空列表、缺失可选字段)。
Step 3:创建命令模块
创建 src/commands/<domain>/mod.rs。DataPrime 原型需提供一个文本渲染器 pub fn render_<domain>_text(merged: &MergedResults) -> Result<()> 和一个调用 super::dataprime::run_query() 的薄 run() 包装。REST 原型需构建完整的扇出/合并/渲染管线,关键模式包括:render::render_table 用于文本输出;render::render_json 用于 JSON 输出;let include_profile = targets.len() > 1; 控制多 profile 行为;扇出错误非致命(打印到 stderr 并继续);状态消息写入 stderr;Agents 输出由命令自己负责调用 toon_encode。最后在 src/commands/mod.rs 注册模块。
Step 4:接入 CLI
在 src/main.rs 添加三处内容:Commands 枚举变体、子命令枚举(仅 REST)、分发 match 分支。大多数命令走完整配置解析流程,只有不需要凭据的命令(如 profiles、cleanup)提前退出。
Step 5:添加测试
每个新命令需在三个层面添加测试:单元测试(src/**/<file>.rs 的 #[cfg(test)],验证纯逻辑与反序列化)、集成测试(tests/<command>/main.rs,使用 wiremock 端到端验证)、E2E 测试(tests/e2e/<command>/mod.rs,使用 assert_cmd 且标记 #[ignore])。注意:变更型命令(create/delete/enable/disable)不要添加 e2e,除非有配对的撤销方案;若子命令需要测试团队的 ID,可添加本地 discover_* 函数并用 OnceLock 缓存;别忘了在 tests/e2e.rs 中声明新的 e2e 模块。
Step 6:创建面向用户的技能
每个命令都需要在 skills/ 中有一个对应的技能,以便 AI 代理知道如何使用它。使用 add-skill 工作流创建。
Step 7:验证
运行 cargo build、cargo test(单元 + 集成)、cargo clippy、cargo fmt --check 并修复问题。若配置了测试团队凭据,可运行 e2e 套件:
cargo test --test e2e -- --ignored --test-threads=1
并对三种输出格式(text、json、agents)以及多 profile(-p profile1 -p profile2)做冒烟测试。完整的 PR 检查清单见 docs/adding-a-command.md 的 PR Checklist 一节。
适用场景
适用于需要在 cx CLI 中新增命令、扩展 CLI 功能、封装新的 Coralogix REST API,或调整命令原型与测试结构的开发场景。
限制
所有 API 集成必须使用 REST(HTTP),不使用 gRPC;变更型命令默认不添加 e2e 测试;e2e 测试默认被 #[ignore] 标记并在有测试团队凭据时手动运行。关于费用、价格、平台支持等信息本文档暂未提供。