audience-targeting

基础

先阅读 bulk-operations/SKILL.md——了解分页、JSONL 管道传递和破坏性操作安全规范。在 bulk-operations/resources/json-patterns.md 中查找重塑数据的配方。资源：resources/contact-segmentation-filters.md 是筛选表达式手册（生命周期、潜在客户状态、邮件互动、活动、交易、所有者）。

筛选语法速查

权威信息来源：hubspot objects search --help。

• 一个 --filter 标志 = 一个 AND 组：--filter "lifecyclestage=lead AND !hubspot_owner_id"。
• 多个 --filter 标志之间按 OR 处理。用于枚举值之间的 OR。
• 运算符：=、!=、>、>=、<、<=、~（CONTAINS_TOKEN——匹配完整单词，而非子字符串）、@=（IN）、@!=（NOT_IN）。
• HAS_PROPERTY：裸写 name 或写作 name?。NOT_HAS_PROPERTY：!name。日期格式：YYYY-MM-DD。
• 限制（CRM 搜索 API）： 最多 5 个 --filter 标志，每个标志最多 6 个条件，总计最多 18 个条件。枚举值列表优先使用 @= / @!=——lifecyclestage@=lead,customer 是一个条件，而 --filter "lifecyclestage=lead" --filter "lifecyclestage=customer" 是两个组。
• “这些都不是，或者为空”需要两个组——@!= 会跳过未设置该属性的记录，因此要增加一个 !name 组，并在两个组中重复共有条件： --filter "hubspot_owner_id=123 AND lifecyclestage@!=customer,evangelist" --filter "hubspot_owner_id=123 AND !lifecyclestage"

~ 的注意事项：jobtitle~director 匹配的是 token“director”，而非任意子字符串。没有正则运算符——先扩大搜索范围，再用 jq 进行后续筛选。

此技能会启用的属性

完整的实时列表：hubspot properties list --type contacts。枚举选项：hubspot properties options-list --type contacts <name> | jq -r '.value'。作为备用方案（例如，查看实际使用了哪些值），读取实时记录：hubspot objects list --type contacts --properties <name> --limit 100 --format json | jq -r '.data[].properties.<name> // empty' | sort -u。

此处使用的核心字段：lifecyclestage、hubspot_owner_id（裸写/! 分别表示有所有者/无所有者；运行 hubspot owners list 查看 ID）、hs_email_optout（!=true 会排除已退订的联系人）、hs_email_last_open_date / notes_last_contacted（近期情况）、jobtitle / country / city（字符串 = 或 ~）、num_associated_deals（0 表示净新增，>=1 表示有销售管道）。

公司概况字段（industry、numberofemployees、annualrevenue）位于 companies 对象上——请参阅跨对象部分。

常见细分群体

# Recent leads (this quarter, not yet owned)
hubspot objects search --type contacts \
  --filter "lifecyclestage=lead AND createdate>2026-01-01 AND !hubspot_owner_id" \
  --properties email,firstname,lastname,createdate

# Decision-makers by jobtitle (OR across tokens)
hubspot objects search --type contacts \
  --filter "jobtitle~director" --filter "jobtitle~vp" --filter "jobtitle~chief" \
  --properties email,jobtitle,company

# Engaged but not yet MQL (opened recently, still lead, opted in)
hubspot objects search --type contacts \
  --filter "lifecyclestage=lead AND hs_email_last_open_date>2026-04-01 AND hs_email_optout!=true" \
  --properties email,firstname,hs_email_last_open_date

# Geographic — US contacts opted in
hubspot objects search --type contacts \
  --filter "country=United States AND hs_email_optout!=true" \
  --properties email,state,city

更多模式（潜在客户状态、交易、所有者、组合 AND/OR）请参阅 resources/contact-segmentation-filters.md。

跨对象：按行业筛选公司 → 获取其联系人

industry / numberofemployees / annualrevenue 位于公司对象上。先构建公司集合，再遍历——绝不要对每家公司使用 xargs -I{} hubspot objects get。associations list 会输出 {"id":"...","labels":[...],"associationTypes":[...]}——{id} 可直接传入一次批量 objects get。

# Step 1: target companies. Industry options are portal-specific — discover with:
#   hubspot objects list --type companies --properties industry --limit 100 --format json \
#   | jq -r '.data[].properties.industry // empty' | sort -u
hubspot objects search --type companies \
  --filter "industry=SOFTWARE AND numberofemployees>=100" \
  --properties name,industry,numberofemployees \
  > target_companies.jsonl

# Step 2: gather association IDs (associations list has no batch --from), then ONE batched
# objects get for all contacts. Page each company with --limit/--after — a company with >100
# associated contacts truncates silently on a single call.
while read -r cid; do
  after=""
  while :; do
    page=$(hubspot associations list --from "companies:$cid" --to contacts --limit 100 ${after:+--after "$after"} --format json)
    echo "$page" | jq -c '.data[]?'
    after=$(echo "$page" | jq -r '.meta.next // empty')
    [ -z "$after" ] && break
  done
done \
  < <(jq -r '.id' target_companies.jsonl) \
| jq -c '{id}' | sort -u \
| hubspot objects get --type contacts --properties email,firstname,jobtitle,hs_email_optout \
> target_contacts.jsonl

# Optional: drop opted-out
jq -c 'select(.properties.hs_email_optout != "true")' target_contacts.jsonl > campaign_audience.jsonl

保存并复用细分群体

细分群体是一个 JSONL 文件。可复用于更新、导出或重新获取数据：

# Save
hubspot objects search --type contacts \
  --filter "lifecyclestage=lead AND hs_email_optout!=true" \
  --properties email,firstname,lastname,jobtitle \
  > segments/opted_in_leads.jsonl

# Assign owner (dry-run first per bulk-operations/SKILL.md)
jq -c '{id, properties:{hubspot_owner_id:"12345"}}' segments/opted_in_leads.jsonl \
| hubspot objects update --type contacts --dry-run

# Re-fetch with different properties later
jq -c '{id}' segments/opted_in_leads.jsonl \
| hubspot objects get --type contacts --properties email,lifecyclestage,hs_lead_status

对已保存的细分群体执行破坏性操作时，请遵循 bulk-operations/SKILL.md 中的 dry-run → 摘要 → 确认流程。

保存为 HubSpot 列表或视图

JSONL 细分群体便于移植，但也可以在 HubSpot 中保存受众：

• 列表——hubspot segments create 可保存列表；使用 segments get / list 查看列表；使用 segments members-list 读取成员；使用 segments members-add / members-remove 管理成员。使用 segments update-filters 设置动态列表的筛选条件。
• 视图——hubspot views create --type <t> --name "..." --columns a,b [--filters-file filters.json] [--sort prop:asc] 可将筛选条件保存为可复用的对象视图；使用 views list / get / update / replace-field / delete 进行管理。
• 先估算规模——hubspot objects count --type contacts --filter "..." 无需分页即可返回 {"object_type":"contacts","total":N}，便于在保存或导出前估算受众规模。

相关只读信号（用于定位的上下文）

• hubspot buyer-intent — 访问公司的意向信号（只读）。需要通过 OAuth 登录（hubspot auth login）；不支持服务密钥。
• hubspot analytics traffic sources — 会话／联系人来源，用于按来源细分。
• hubspot marketing forms list — 表单定义，可按联系人通过转化的表单进行细分。

运行每个命令的 --help 查看完整功能。

已知限制

• ~ 用于匹配令牌，不是子字符串匹配。没有正则运算符。
• 枚举选项：hubspot properties options-list --type contacts <name>（备用方法：通过 objects list + jq 读取实时记录）。
• associations list 不支持批量 --from，且每次调用只返回一页（默认 100 条）。循环收集 ID，并通过 --limit／--after 翻页，直到 .meta.next 为 null，然后批量执行下游 objects get；否则，关联联系人超过 100 个的公司会被静默截断。
• 结果超过 100 条时，使用 bulk-operations/SKILL.md 中的分页循环。