cx-ai-center

AI Center 技能

这是处理 AI/GenAI 应用相关一切事务的工具——既可用于询问其行为（提示词/响应、质量、幻觉、护栏、安全性、成本/令牌、错误、延迟——AI 应用通过其 GenAI span/标签暴露的一切），也可用于管理操作（应用、评估/策略、策略↔应用关联、模型定价）。如果请求涉及 AI 应用或其 GenAI 遥测数据，请使用此技能。

Coralogix AI Center 可观测、评估并防护 GenAI/LLM 应用。此技能通过以下两个来源回答有关 AI 应用的问题：

• 配置（此技能的 cx ai-center 命令）：AI 应用清单、已配置的评估/策略、覆盖情况、自定义评估和模型定价——这些信息都不会出现在 span 遥测数据中。
• 遥测数据（GenAI spans）：用户询问了什么、模型如何回答、成本、令牌、延迟、错误、工具调用以及评估/护栏判定——使用 cx spans '<DataPrime>' 查询。 完整的可运行查询库、span 架构和操作指南，请参阅 references/ai-center-queries.md。

根据问题匹配数据来源：“哪些应用缺少护栏” → 配置（cx ai-center applications list）；“用户在向我的聊天机器人询问什么” → 遥测数据（cx spans '…'，从 GenAI spans 中读取对话）。有些问题需要同时使用两者——例如，“我的聊天机器人的 PII 策略真的能检测到 PII 吗？”，需要结合配置（策略是否已启用）和遥测数据（PII 判定及消息）。

---

破坏性操作安全

所有写入操作（create、update、delete、add、remove、set）都需要交互式确认。ai-center 是高风险命令，因此写入操作还受 ~/.cx/config.toml 中的 allow_risky_commands 限制。若要在脚本中跳过提示，请传入 --yes。

重要：未经用户明确批准，绝不可传入 --yes。 执行任何写入操作之前：

1. 向用户说明具体操作（将创建/修改/删除/关联什么）。
2. 等待用户确认。
3. 只有在用户确认后，才能使用 --yes 执行。

读取操作（list、get、coverage、list-for-application、model-pricing get）无需确认，可以自由执行。

只读模式

使用 --read-only（或 CX_READ_ONLY=1）可在 CLI 层级阻止所有写入操作，适合安全探索。

Agent 模式

在 AI Agent（Claude Code、Cursor、Codex、……）中运行时，cx 会检测到这一点，并且不会显示一个会因无人输入 y/n 而无限期挂起的确认提示，而是立即停止并报错，告知你需要取得用户批准，然后使用 --yes 重新运行。

按设计不提供删除命令

CLI 刻意不为自定义评估策略、AI 应用或模型定价提供删除命令——尽管 AI v3 API 提供了这些删除端点，cx ai-center 并未将其开放。

• **自定义评估策略：**无法删除；若要从某个应用中移除，请使用 custom-evaluations remove 分离该策略（策略对象仍会保留，之后可以重新关联）。
• 模型定价：没有删除命令。它是团队级的（而非针对单个应用），因此若要更改或清除定价，请使用新的映射运行 model-pricing set（空映射 {} 可清除所有覆盖项）——set 会替换整个集合。

---

黄金法则

对于内容问题（质量、幻觉、情感、主题），请阅读实际对话并引用 traceID——不要只依赖判定标签。对话记录遵循以下两种约定之一（gen_ai.input.messages/output.messages，或较旧的索引标签 gen_ai.prompt.<n>/completion.<n>）；请使用查询库中的**读取对话（内容问题）**查询来读取，它们会同时处理这两种约定，并排除系统提示词和工具流量。完整指南： references/ai-center-queries.md。

---

CLI 命令

向用户展示名称；仅在内部使用 UUID。 展示结果时，请使用应用和评估的人类可读名称（应用程序/子系统、评估名称），不要使用原始 UUID。仅在调用按 ID 查询或写入命令时才需要 UUID——请根据匹配的 list 命令自行解析（绝不要猜测，也不要让用户粘贴 UUID）。

应用程序（清单 + 防护状态）

命令	用途
cx ai-center applications list	列出 AI 应用，包括 guardrailsIntegrated（已接入防护）状态
cx ai-center applications list --evaluation-type <TYPE>	筛选使用某种评估类型的应用（可重复指定）
cx ai-center applications list --page-size <N> --page-offset <N>	分页
cx ai-center applications get <application-id>	按 UUID 查询单个应用

评估（应用上配置的策略）

命令	用途
cx ai-center evaluations list	列出所有已配置的评估
cx ai-center evaluations list --application <app> --subsystem <sub>	限定到单个应用（这对参数）
cx ai-center evaluations list --evaluation-type <TYPE>	按类型筛选——<TYPE> 是 API 枚举值（例如 PII、TOXICITY、PROMPT_INJECTION；即 coverage 中的键），不是小写形式
cx ai-center evaluations get <evaluation-id>	按 UUID 查询单个评估
cx ai-center evaluations create --from-file eval.json	创建/启用评估 (写入)
cx ai-center evaluations update <evaluation-id> --from-file patch.json	部分更新 (写入)
cx ai-center evaluations delete <evaluation-id>	从应用中移除评估 (写入)

自定义评估（策略）和应用关联

命令	用途
cx ai-center custom-evaluations list	列出所有自定义评估策略
cx ai-center custom-evaluations list-for-application <application-id>	列出关联到单个应用的策略
cx ai-center custom-evaluations create --from-file policy.json	创建自定义策略 (写入)
cx ai-center custom-evaluations update <id> --from-file patch.json	部分更新 (写入)
cx ai-center custom-evaluations add <evaluation-id> <application-id>	将策略关联到应用 (写入)
cx ai-center custom-evaluations remove <evaluation-id> <application-id>	解除关联（可撤销） (写入)

按 ID 查询仅适用于预置项。 evaluations get <id> 获取的是预置/已配置评估。 自定义策略不支持按 ID 查询——请通过 custom-evaluations list / list-for-application 查找，并按 id/名称匹配。

覆盖范围和模型定价

命令	用途
cx ai-center coverage	映射每种评估类型 → 使用该类型的应用数量（覆盖范围/差距分析）
cx ai-center model-pricing get	团队自定义的每模型定价覆盖项
cx ai-center model-pricing set --from-file prices.json	设置团队定价（适用于整个团队，仅影响新数据） (写入)

evaluations 和 custom-evaluations 的 --from-file 请求体与 AI v3 API 格式完全一致；使用 - 从标准输入读取 JSON。对于 evaluations create，target 为必填项，且必须使用大写形式（PROMPT 或 RESPONSE）；对于 custom-evaluations create，name、instructions 和 policyType 为必填项。例外： model-pricing set 只接受原始的 model→price 映射——cx 会为你将其封装为 {"prices": …}，因此不要包含外层的 prices 封装。每个模型对应一个价格对象；四个字段均为可选的双精度数值（每一百万个 token 的美元价格），不适用的字段可省略：

{
  "gpt-4o": {
    "inputPricePerMillionTokens": 2.5,
    "outputPricePerMillionTokens": 10,
    "cacheReadPricePerMillionTokens": 1.25,
    "cacheWritePricePerMillionTokens": 3.75
  }
}

空映射 {} 会清除所有覆盖项（set 会替换整个集合——适用于整个团队，仅影响新数据）。 model-pricing get 返回封装对象 { "pricing": { "id", "companyId", "prices": { … } } }——每模型的覆盖项位于 prices 下（未设置时为空）。

---

常见工作流

清点应用并发现防护缺口

# Which apps are NOT guarded?
cx ai-center applications list -o json | jq '[.[] | select(.guardrailsIntegrated==false)]'

在应用上启用策略（写入操作 — 先确认！）

# 1. Describe to the user; 2. get approval; 3. then:
cx ai-center evaluations create --from-file eval.json --yes
# eval.json: { "application": "...", "subsystem": "...", "target": "PROMPT", "config": { "<type>": {...} }, "isEnabled": true }
# `target` is REQUIRED and must be UPPERCASE — "PROMPT" or "RESPONSE" (the API rejects lowercase / a missing target).

读取实际对话（遥测数据，而非配置）

使用 cx spans 和 references/ai-center-queries.md 中的查询库，读取消息、成本、 延迟、错误、工具调用和逐用户分析数据。

---

核心原则

• 配置与遥测数据： 清单 / 评估 / 策略 / 覆盖率 / 定价 → cx ai-center； 内容 / 成本 / 延迟 / 错误 / 判定结果 → 通过 cx spans 查询 GenAI spans。不要用其中一类数据回答另一类的问题。
• 写入前先确认。 说明操作内容，获得批准后，再使用 --yes 执行。

---

相关技能

• cx-telemetry-querying — 通用日志 / spans / 指标 / DataPrime 查询（这是此处 cx spans 查询背后的引擎）。
• cx-olly — 对话式 AI 助手（cx olly ask）。