需要在 HubSpot 中用 CLI 管理自动化工作流时…

当你需要通过 HubSpot agent CLI 列出、查看、创建、更新或删除自动化工作流（v4 flows API），尤其是按名称查找、改流程或删除流程时适用。

适用场景

解决思路

1. 区分两个 CLI：管理自动化工作流使用 HubSpot agent CLI `hubspot` 的 `hubspot workflows list|get|create|update|delete`；不要用开发者 CLI `hs`（`@hubspot/cli`），它用于 themes、modules、serverless functions、UI extensions、private apps 等开发项目，不创建或管理工作流记录。
2. 创建或管理工作流时运行 `hubspot workflows ...`，不要运行 `hs`；若不确定以 `hubspot workflows --help` 和 `hs --help` 为准。
3. 创建/更新 body 形状参考 `resources/workflow-json-reference.md`。
4. 用 `resources/example-contact-flow.json` 作为 `hubspot workflows create --file` 的最小有效 `CONTACT_FLOW` 骨架。
5. 用 `resources/example-branching-flow.json` 理解分支汇聚：两条路径的 `connection.nextActionId` 指向同一个共享下游 action。
6. 记住 `hubspot workflows --help` 只有 `list`、`get`、`create`、`update`、`delete` 五个子命令；没有 `search`，按名称查找用 `list | jq`。
7. 对于 JSONL 管道、分页、破坏性 dry-run/digest/confirm 模式，先重读 `bulk-operations/SKILL.md`。
8. 列出工作流：`hubspot workflows list`，输出 JSONL，包含 id、name、isEnabled、type、objectTypeId、revisionId。
9. 人类扫描用 `hubspot workflows list --format table`。
10. 按名称大小写不敏感子串查找：`hubspot workflows list | jq -c 'select(.name | test("Welcome"; "i"))'`。
11. 按名称精确查找：`hubspot workflows list | jq -c 'select(.name == "MQL Nurture")'`。
12. 分页每页 100，用 `--after` 循环直到 `meta.next` 为空；参考 `bulk-operations/SKILL.md` 的 Pagination，更多 jq 过滤参考 `bulk-operations/resources/json-patterns.md`。
13. 获取单个工作流：`hubspot workflows get 12345678`。
14. 批量位置参数获取：`hubspot workflows get 12345678 87654321`。
15. 批量 stdin 获取：`printf '%s\n' 12345678 87654321 | hubspot workflows get`。
16. 保存工作流 body 用于编辑：`hubspot workflows get 12345678 > workflow.json`。
17. `get` 返回完整 body（`actions`、`enrollmentCriteria`、`revisionId` 等），这是 create/update 所需形状；参考 `resources/workflow-json-reference.md`。
18. 创建前 dry-run：`hubspot workflows create --file workflow.json --dry-run`。
19. 创建：`hubspot workflows create --file workflow.json`。
20. 通过 stdin 创建：`cat workflow.json | hubspot workflows create`。
21. 创建时必须设置 `type`（`CONTACT_FLOW` 或 `PLATFORM_FLOW`）、`flowType`（`WORKFLOW`）、`objectTypeId`（如联系人 `0-1`）。
22. 最简单做法：`get` 一个现有相似工作流作为起点模板，而不是手写 JSON。
23. 注意 `create --dry-run` 不验证 body：它只回显 JSON 并返回 `ok:true`，不调用 API；缺少 `type`/`flowType`/`objectTypeId`/`actions` 的 body 仍可能 `ok:true`，唯一真实验证是实际 `create`；`update --dry-run` 会拒绝缺 `revisionId` 等必填字段的 body。
24. 分支与汇聚：`LIST_BRANCH` action 按筛选条件分叉；每个分支和 `defaultBranch` 通过 `connection` 指向继续的 action；由于 connection 用 `nextActionId` 指向 action，两个分支可指向同一 `actionId` 汇聚到共享下游 action，无需重复；参考 `resources/workflow-json-reference.md` 分支部分和 `resources/example-branching-flow.json`。
25. 更新是全量 PUT 替换：body 必须包含来自 `get` 的 `revisionId` 和 `type`；只读字段 `createdAt`、`updatedAt`、`dataSources` 会自动剥离；更新需先 dry-run，再用 `--digest <hash> --confirm <flowId>`。
26. 更新步骤 1：`hubspot workflows get 12345678 > workflow.json` 拉取当前状态。
27. 更新步骤 2：编辑 `workflow.json`，保留 `revisionId`、`type` 和所有想保留的字段。
28. 更新步骤 3：`hubspot workflows update 12345678 --file workflow.json --dry-run` 生成 digest。
29. 更新步骤 4：`hubspot workflows update 12345678 --file workflow.json --digest blast-xxxxxxxx --confirm 12345678` 应用，`--confirm` 值是 flow id。
30. 更新陷阱：部分 body 会静默清空字段；例如只发送 `actions` 会清掉 `enrollmentCriteria`；始终从完整 `get` 响应开始。
31. 删除步骤 1：`hubspot workflows delete 12345678 --dry-run`，输出 digest 和 confirm 提示。
32. 删除步骤 2：`hubspot workflows delete 12345678 --digest blast-xxxxxxxx --confirm "New lead routing"`，`--confirm` 值是工作流 NAME，不是 id。
33. 删除 dry-run 输出包含 `apply_command_hint`，从中复制准确的 confirm 字符串，避免引号问题。
34. 删除后无法通过 automation API 恢复；用 `hubspot history --since 1h` 查审计记录；完整安全模式（digest、5 分钟过期、history 恢复）见 `bulk-operations/SKILL.md` 的 “Safe destructive workflow”。
35. 已知限制：没有 `hubspot workflows search`，用 `list | jq` 替代。
36. 已知限制：CLI 无 Lists API，基于列表成员的 enrollment triggers 必须在 UI 配置。
37. 已知限制：无 sequences/cadences API；`dataSources` 只读，无法通过 update 重接。

适用边界 · 注意事项

• 你要开发 HubSpot themes、modules、serverless functions、UI extensions、private apps 时，不要用本技能，改用 `hs` 开发者 CLI。
• 你需要 Lists API 的 list-membership enrollment triggers，或 sequences/cadences API 时，CLI 不支持，需改用 UI 或其他方式。
• 没有 HubSpot agent CLI `hubspot` 或没有工作流管理权限时，不能使用本技能。