cargo-segmentation

Cargo CLI — 细分

细分是 Cargo 工作区的受众层：针对一个模型的命名、已保存筛选条件，用于回答“我指的是哪些记录？”下游的所有操作——批量运行、播放触发、CSV 导出、变更动态——都以细分（或形如细分的筛选条件）为输入。

完整的 JSON 响应结构请参阅 references/response-shapes.md。 常见错误及其修复方法请参阅 references/troubleshooting.md。 条件类型和运算符请参阅 ../cargo-orchestration/references/filter-syntax.md——这是筛选 JSON 的唯一可信来源。

初始化

已登录（cargo-ai whoami 返回工作区）？请跳到下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

每条命令都会将 JSON 输出到 stdout；失败时会以非零状态退出，并将 {"error": "...", "status": ..., "body": ...} 输出到 stderr。任何会创建运行或批次的操作都是异步的——请传入 --wait-until-finished，或轮询对应的 get。安装完整技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定要求、令牌范围和仅限管理员使用的功能。

核心概念

术语	含义
筛选条件	一个 JSON 对象（{conjonction, groups[].conditions[]}），用于匹配某个模型的列。单独使用时是临时的。
细分	带有名称、modelUuid 和 slug 的已保存筛选条件。拥有 uuid、实时 recordsCount 和历史记录。播放、批次和导出都引用它。
变更	两次同步之间细分的一次计算差异——added、updated、removed 和 unchanged 记录的数量。所有“有人进入此受众时通知我”操作的基础。
跟踪列	列的子集（--tracking-column-slugs），这些列的值发生变化时，记录会被计为 updated。如果不指定，记录只会被记为新增或移除。

筛选条件与细分——请有意选择。 临时问题（“有多少家公司拥有超过 100 名员工？”）适合使用带内联筛选条件、不创建已保存对象的 segment fetch。如果要针对某个受众执行操作、安排操作或长期跟踪，则应创建真正的 segment create——因为只有已保存的细分才会产生变更。

先发现资源

创建之前务必先列出资源。工作区中通常已经存在你准备复制的细分。

cargo-ai segmentation segment list                    # all segments (uuid, name, slug, modelUuid, recordsCount)
cargo-ai storage model list                           # find the modelUuid a segment must target
cargo-ai storage column list --model-uuid <uuid>      # the column slugs your filter conditions reference

播放自动创建的细分名为 GENERATED_PLAY_SEGMENT，并带有 fromPlay: true——切勿手动编辑或移除这些细分；它们属于创建它们的播放。

**在 UI 中查看：**细分位于模型页面下：app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>。通过 cargo-ai whoami 获取 <WORKSPACE_UUID>。

快速参考

cargo-ai segmentation segment list
cargo-ai segmentation segment get <segment-uuid>
cargo-ai segmentation segment create --name "<name>" --model-uuid <uuid> --filter '<json>'
cargo-ai segmentation segment update --uuid <segment-uuid> --filter '<json>'
cargo-ai segmentation segment remove <segment-uuid>
cargo-ai segmentation segment fetch    --model-uuid <uuid> --filter '<json>' --limit 50
cargo-ai segmentation segment download --model-uuid <uuid> --filter '<json>'
cargo-ai segmentation change list  --segment-uuid <segment-uuid>
cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50
cargo-ai segmentation record fetch --model-uuid <uuid> --ids <id[,id…]>

构建筛选条件

完整的条件目录——所有 kind（string、number、date、boolean、array、object、objectProperty、any、vector、sql、segment、occurrence、enrollment）及其所有运算符——请参阅 ../cargo-orchestration/references/filter-syntax.md。结构如下：

{
  "conjonction": "and",
  "groups": [
    {
      "conjonction": "and",
      "conditions": [
        { "kind": "number", "columnSlug": "employee_count", "operator": "greaterThan", "value": 100 },
        { "kind": "string", "columnSlug": "email", "operator": "isNotEmpty" }
      ]
    }
  ]
}

conjonction，不是 conjunction。 法语拼写是有意为之的，且筛选条件和每个组这两个层级都必须使用此拼写：键名拼错会导致验证失败，API 会返回一个提及 conjonction 的 400 错误。每次调用前，请在 JSON 中搜索 conjunction。

每个组都必须至少包含一个条件。 "conditions": [] 这样的组会被拒绝（Filter groups must contain at least one condition）；若要匹配所有内容，请改用 "groups": []。

匹配所有内容的筛选条件：{"conjonction":"and","groups":[]}。

在构建之前先确定受众规模

计数是免费的；对受众执行任何操作都不是。先确定规模，再做决定。

# 1. How many records match? — inline filter, no saved object, 1 row back; read `count`
cargo-ai segmentation segment fetch \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[{"conjonction":"and","conditions":[
      {"kind":"number","columnSlug":"employee_count","operator":"greaterThan","value":100}]}]}' \
  --fetching-limit 1 --sync false --enrich false

# 2. Happy with the shape? Save it as the real audience.
cargo-ai segmentation segment create \
  --name "Mid-market accounts" \
  --model-uuid <uuid> \
  --filter '<same json>' \
  --column-slugs "name,domain,employee_count" \
  --tracking-column-slugs "employee_count,funding_stage"

segment fetch 会将匹配总数作为 count 返回（使用 --fetching-limit，而不是 --limit：--limit 会限制成员数量，因此 --limit 1 报告的计数是 1）。接着，segment get <uuid> 会报告 recordsCount——这是权威规模。在提议对该分群执行付费操作之前，请引用这个数字，而不是自己的估算。

fetch、download 与 record fetch 的区别

命令	返回内容	用途
segment fetch --model-uuid --filter	内联返回 JSON 格式的记录，支持分页（--fetching-limit、--fetching-offset）	检查少量行、计数、保存筛选条件前预览
segment download --model-uuid --filter	指向完整数据集的签名 URL（urls[]）	将整个受众交给用户或其他工具——参见 ../cargo-analytics/SKILL.md
record fetch --model-uuid --ids <ids>	按 ID 获取特定记录	重新读取变更 Feed 刚通知你的行

segment fetch 会在评估前刷新模型（--sync），并添加 _segments 成员资格列（--enrich）。省略时两者默认开启，会耗费时间，因此检查规模时请传入 --sync false --enrich false。

切勿将大型分群分页载入对话。 使用 --limit 3 查看数据结构，然后用 download 获取其余数据。

变更——增量 Feed

每次分群同步时，Cargo 都会计算一项变更：成员资格如何变动。这使静态列表成为一种信号。

# What deltas exist for this segment?
cargo-ai segmentation change list --segment-uuid <segment-uuid>
# → { "changes": [ { "uuid", "totalRecordsCount", "addedRecordsCount",
#                    "updatedRecordsCount", "removedRecordsCount",
#                    "unchangedRecordsCount", "createdAt" } ] }

# Only the deltas where something entered (or moved, or left)
cargo-ai segmentation change list --segment-uuid <segment-uuid> --has-records added --limit 20

# One delta's counts, by its uuid → { "change": {...} }
cargo-ai segmentation change get <change-uuid>

# Which records actually entered the audience in that delta?
cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50

# The whole delta as files, when it is too big to page → { "urls": [...] }
cargo-ai segmentation change download --uuid <change-uuid> --kinds added,removed

change fetch 必须指定 --kinds，可选值为 added、updated、removed 或 unchanged（以逗号分隔）。返回的行除了模型自身的列外，还带有 _kind、_id、_title 和 _time 元数据列。change download 返回签名 URL 而非行，并接受相同的四种类型（CLI 1.0.128 起支持 unchanged，cargo#6369；此前 API 会拒绝该类型）。

change list --not-empty 只保留添加、更新或移除过记录的增量；--has-records 则接受四种类型中的任意一种。两者都需要 CLI 1.0.128（cargo#6369）：此前 API 会以 400 响应 --not-empty（Unrecognized key: "notEmpty"），并拒绝 --has-records unchanged。因此，在较旧的 CLI 上，请使用 --has-records <kind> 跳过空增量。

除非分群创建时指定了 --tracking-column-slugs，否则 updatedRecordsCount 始终为 0——跟踪列决定了“已更新”的含义。如果分群旨在用于监控工作流，请在创建时设置这些列。

分群最新的增量也会内联显示在 segment list / segment get 的 lastChange 中，因此“发生了什么变动？”通常不需要再调用一次。

分段的用途

分段是输入，而非结果。创建分段后：

• 对分段执行操作 — 对每个成员批量执行连接器操作或工作流：../cargo-orchestration/SKILL.md。批次从分段中添加成员；先抽样 10–20 条记录，并在添加完整受众前获得明确批准。
• 在进入时触发 play — 记录进入受众时，play 会触发。play 由 --model-uuid、--filter 和 --change-kinds 创建，并生成自己的 GENERATED_PLAY_SEGMENT；参见 ../cargo-orchestration/references/examples/plays.md。
• 导出分段 — ../cargo-analytics/SKILL.md（segment download 需要 --model-uuid，而不是 --segment-uuid——这是常见的 400 错误）。
• 监控分段 — 在受众清空、停滞或激增时发出警报：../cargo-observability/SKILL.md。
• 将其用于 GTM 行动 — 信号分段（职位变更、融资、技术意向）可用于 ../cargo-gtm/SKILL.md 中的方案。
• 将其声明为代码 — 如果受众定义应保存在 git 中，请使用 ../cargo-project/SKILL.md 中的 defineSegment。

注意事项

• 只能使用 conjonction，不能使用 conjunction — 否则调用会被拒绝，并返回 400 错误。
• segment download 接受 --model-uuid，不接受 --segment-uuid。 筛选条件会随请求传递；分段 UUID 不是有效输入。
• change fetch 需要 --uuid（change UUID）和 --kinds。 传入分段 UUID 会返回 400 错误。
• change list 需要 --segment-uuid。 直接调用会返回 400 错误，并提示 segmentUuid 未定义。
• 对 change 和 record 子命令使用 --help，显示的是父命令帮助，而非子命令的标志（CLI ≥ 1.0.48）。请使用上方的快速参考；如果问题仍然存在，请提交报告。
• 一个分段只能属于一个模型。 跨模型受众应使用关联关系和联接列上的筛选条件，而不是两个分段。
• fromPlay: true 的分段归 play 所有。 编辑此类分段会改变 play 的目标；移除则会导致 play 无法正常工作。
• 分段上的 --limit 会限制成员数量，它不是显示页大小——--fetching-limit 才是页大小。

CLI 失败时

同一命令尝试失败两次，或行为与本技能说明相矛盾时，请联系团队：

cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<commands run, errorMessage verbatim, expected vs actual, UUIDs>"