ticket-resolution

先阅读 bulk-operations/SKILL.md——JSONL 管道传输、批量读取、分页、dry-run/digest/confirm，以及 hubspot history 恢复流程都在其中。hubspot <command> --help 是权威说明。工单使用 tickets 对象类型（复数，例如 tickets:45123）。

1. 发现管道和阶段（每次会话都要针对门户运行）

每个门户的阶段 ID 都不同——切勿硬编码。

hubspot pipelines list --type tickets --format table
hubspot pipelines stages --type tickets --pipeline <pipeline_id> --format table

阶段表会打印每个阶段的 ID 和 Label（“New”“Waiting on contact”“Closed”等）。pipelines list/get 也会在 jsonl/json 中返回每个管道的完整 stages 数组，因此只需调用一次，就能将 hs_pipeline_stage 值映射到对应标签。

2. 验证此门户的枚举选项值

hs_ticket_priority、hs_ticket_category 和 hs_resolution 都是 enumeration 属性——选项值可由门户配置。使用 properties options-list 直接列出允许的选项（旧的 objects update … --property hs_resolution=__probe__ 探测方式已不可用——现在更新操作受 digest 门控）。如果想同时获取值和标签，properties get 会内联返回相同的 options 数组：

# List the allowed option values for each enum
hubspot properties options-list --type tickets hs_ticket_priority | jq -r '.value'
hubspot properties options-list --type tickets hs_ticket_category | jq -r '.value'
hubspot properties options-list --type tickets hs_resolution      | jq -r '.value'
# each row: {"value":"ISSUE_FIXED","label":"Issue fixed","displayOrder":0,"hidden":false}

# Fallback — read values already in use on live records:
hubspot objects list --type tickets --limit 10 \
  --properties hs_ticket_priority,hs_ticket_category,hs_resolution

切勿假设 HubSpot 默认值——应读取门户中的值。

3. 创建工单并建立关联

subject 是实际使用中唯一必需的属性。跳过 hs_pipeline/hs_pipeline_stage 会将工单放入默认管道的第一个阶段。

hubspot objects create --type tickets \
  --property subject="Login error on mobile app" \
  --property content="User reports 401 since v3.2 release." \
  --property hs_pipeline=<pipeline_id> \
  --property hs_pipeline_stage=<new_stage_id> \
  --property hs_ticket_priority=<value_from_step_2> \
  --property hs_ticket_category=<value_from_step_2>
# Capture the "id" from the output JSON.

hubspot associations create --from tickets:<ticket_id> --to contacts:<contact_id>
hubspot associations create --from tickets:<ticket_id> --to companies:<company_id>

从 JSONL 队列批量录入（重塑模式请参阅 bulk-operations/resources/json-patterns.md）：

cat support_requests.jsonl \
| jq -c '{properties:{subject:.subject, content:.description,
    hs_pipeline:"<pipeline_id>", hs_pipeline_stage:"<new_stage_id>",
    hs_ticket_priority:"<priority>", hs_ticket_category:"<category>"}}' \
| hubspot objects create --type tickets

4. 分类查询

# Open tickets by priority
hubspot objects search --type tickets \
  --filter "hs_pipeline_stage=<open_stage_id> AND hs_ticket_priority=HIGH" \
  --properties subject,hubspot_owner_id,createdate

# Unassigned
hubspot objects search --type tickets \
  --filter "!hubspot_owner_id AND hs_pipeline_stage=<open_stage_id>" \
  --properties subject,hs_ticket_priority,createdate

使用 hubspot_owner_id=<id> 按负责人筛选（通过 hubspot owners list --format table 查找 ID）。

5. 推进工单阶段（根据搜索结果批量更新）

hubspot objects search --type tickets \
  --filter "hs_ticket_category=BILLING_ISSUE AND hs_pipeline_stage=<new_stage_id>" \
| jq -c '{id, properties:{hs_pipeline_stage:"<waiting_stage_id>"}}' \
| hubspot objects update --type tickets --dry-run

objects update 操作不可逆，因此请使用从预览行中取得的 --digest/--confirm，重新运行相同的搜索并通过管道传入——无论行数多少都必须提供，而不仅仅是超过 100 行时（批次的 confirm = 行数）。请参阅 bulk-operations/SKILL.md 中的 --digest/--confirm 流程（“Safe destructive workflow”）。批量重新分配的操作方式相同，使用 {hubspot_owner_id:"<new>"} 即可。

6. 记录解决说明

活动创建方式请参阅 sales-execution/SKILL.md（备注/通话/会议/任务）。在那里创建备注后，将其关联起来：hubspot associations create --from notes:<note_id> --to tickets:<ticket_id>。

7. 关闭工单

hs_resolution 是一个枚举——传入第 2 步中列出的允许选项值，而不是自由文本。随后 HubSpot 会计算 hs_is_closed=true、closed_date 和 time_to_close。

objects update 操作不可逆——先执行 dry-run，然后使用 digest 和 --confirm <ticket_id> 重新运行：

hubspot objects update --type tickets <ticket_id> \
  --property hs_pipeline_stage=<closed_stage_id> \
  --property hs_resolution=<allowed_resolution_value> --dry-run
hubspot objects update --type tickets <ticket_id> \
  --property hs_pipeline_stage=<closed_stage_id> \
  --property hs_resolution=<allowed_resolution_value> --digest <hash> --confirm <ticket_id>

已知限制

• 枚举选项：使用 hubspot properties options-list --type tickets <property> 列出（备用方法：读取实时记录）。
• 聊天/收件箱：hubspot conversations 可读取收件箱、渠道、会话串和消息——例如，hubspot conversations threads list --inbox-id <id> --associated-ticket-id <ticket_id> 会拉取工单背后的聊天会话串。运行 hubspot conversations --help 查看完整功能。