HubSpot CRM 操作
使用此技能，通过 HubSpot CRM v3 API 读取以及（在获得明确确认后）更新 HubSpot CRM 数据：联系人记录、联系人搜索、交易管道视图以及交易阶段变更。这是一个面向单一 CRM 供应商（HubSpot）的工具技能。构建 HubSpot 应用程序或工作流属于应用开发；此技能负责日常的代理工作流：回答“这个联系人是谁？”、“管道里有什么？”，以及执行确认后的阶段变更。
运营契约
- 在任何变更操作之前，先进行只读探索。 自由地列出和搜索联系人、查看交易和管道。包含的
crm-cli脚本仅执行读取，不会写入任何数据。 - 在操作前确认目标、范围及回滚路径。 将交易移至新阶段会更改一个共享管道，该管道被收入报告所读取：这需要一个明确的人类指令，指明交易名称和目标阶段，并通过
crm-cli执行--dry-run预览和--yes确认。阶段移动是可逆的，但会留下审计历史记录——操作前必须先确认。 - 尊重有边界的读取。 HubSpot 使用
limit进行分页；切勿读取超出任务所需的分页数量。crm-cli --limit限制每次列出和搜索的结果。 - 保持证据简洁。 引用简短的名字、邮箱、金额和阶段标签；绝不要在聊天中转储完整的记录、令牌或原始负载。
- 了解对象模型。 联系人和交易是具有属性映射的不同对象；阶段转换必须使用交易所在管道中的阶段 ID（通过
pipelines list获取），而不是阶段标签。
crm-cli 脚本
scripts/crm-cli 是一个面向代理、仅依赖标准库的 CLI，用于调用 HubSpot CRM v3 API。它涵盖了全部功能范围：记录管理、搜索和管道视图。
crm/scripts/crm-cli --help # 无需令牌或网络
crm/scripts/crm-cli --json --limit 20 contacts list
crm/scripts/crm-cli --json contacts get --id 51
crm/scripts/crm-cli --json contacts search --query "ada"
crm/scripts/crm-cli --json --limit 20 deals list
crm/scripts/crm-cli --json deals list --pipeline default --stage appointmentscheduled
crm/scripts/crm-cli --json pipelines list
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --dry-run # 预览
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes # 已确认
退出码：0 成功，1 API 错误或检查失败，2 使用错误。阶段变更受到保护：如果没有 --dry-run 或 --yes，脚本会以退出码 1 拒绝执行，并且绝不会调用 API。读取受 --limit（默认 20，最大 100）限制。
操作循环
- 界定问题范围：是查询（CRM 中谁/有什么）还是变更（移动交易）？使用
contacts search/contacts list或deals list定位对象。 - 有边界的读取：使用
contacts get获取单条记录，使用deals list查看管道视图（可按管道和阶段过滤），使用pipelines list将阶段标签解析为 ID。 - 分析答案：将问题映射到证据（联系人详情、交易金额/阶段、管道分布）。
- 确认后执行：仅当有人类变更指令时，通过
--dry-run预览和--yes确认。 - 验证：重新读取交易（
deals list --stage <target>）并确认阶段已移动。
记录、搜索、管道视图
- 联系人记录 (
/objects/contacts)：列表（GET）或检索单条（按 ID 的 GET）；CLI 摘要显示姓氏/名字、邮箱、公司和创建日期。搜索 (POST /objects/contacts/search) 通过查询文本查找联系人，受--limit限制。 - 交易管道视图 (
/objects/deals)：列出交易及其金额、管道和阶段，可选择按一个管道或阶段进行过滤。pipelines list(/pipelines/deals) 返回各管道及其阶段 ID 和标签——在过滤或更新时使用阶段 ID。 - 阶段变更 (
PATCH /objects/deals/{id})：一个受保护的变更操作，用于设置dealstage属性。使用--dry-run预览目标阶段，使用--yes确认，并通过后续读取进行验证。仅阶段移动在范围内；其他交易属性编辑属于应用工作。
访问模型
- HubSpot 私有应用访问令牌 (
pat_...) 按对象和读写分别授权。读取需要crm.objects.contacts.read和crm.objects.deals.read；阶段更新需要crm.objects.deals.write。 - 记录携带一个
properties映射，键为属性名（例如dealstage、dealname、amount）。属性值为字符串；CLI 对此技能使用的字段进行摘要。 - 令牌是凭证：存储在
HUBSPOT_TOKEN中，绝不要放在代码、聊天记录或提交中。如果令牌泄露，请在私有应用设置中轮换它。
参考路由
| 装载条件 | 参考文档 |
|---|---|
| 来源、范围表、刷新过程 | references/00-source-index.md |
| 端点、分页、对象模型、阶段更新、错误 | references/01-hubspot-crm-operations.md |
包含的工件
scripts/crm-cli：有边界的、仅依赖标准库的 CLI（联系人列表/获取/搜索，交易列表/更新阶段，管道列表；--json；--limit；变更受--dry-run/--yes保护）。tests/test_crm_cli.py：针对模拟 HubSpot API 的 13 个确定性测试，包括变更保护门和只读契约。references/：带日期的来源索引 + HubSpot CRM 操作参考。evals/evals.json：六个代理运行的输出质量评估用例。
验证边界
| 断言 | 最低证据 |
|---|---|
| 某个联系人存在 | crm-cli contacts search --query ... --json 或 contacts get 返回该记录 |
| 管道视图准确 | crm-cli deals list --json 返回带有阶段 ID 和所应用过滤器的交易 |
| 阶段标签映射到 ID | crm-cli pipelines list --json 返回管道阶段映射 |
| 阶段变更已生效 | crm-cli deals update-stage --yes 退出码为 0，并且后续的 deals list --stage 显示该交易 |
| 变更可以安全运行 | crm-cli deals update-stage --dry-run 打印出确切的交易信息 + 目标阶段 |
硬性边界
- 未经人类指令、
--dry-run预览和--yes确认，绝不要移动交易——管道变更会影响收入报告和审计历史。 - 当令牌可能缺少对象作用域时，绝不要断言某记录缺失；请先检查访问模型。
- 绝不要读取超过
--limit限制的分页；绝不要在聊天中转储完整的记录、令牌或原始负载。 - 此技能操作的是 HubSpot CRM API。它不构建 HubSpot 应用程序，也不涵盖其他 CRM。
何时不使用
- 构建 HubSpot 应用程序、工作流自动化或自定义对象——这属于 HubSpot 应用开发；有关服务设计，请参阅 backend-engineering。
- HubSpot 中的营销、序列和邮件自动化——这属于 HubSpot 营销面，而非此技能所涵盖的 CRM API。
- 其他 CRM（Salesforce、Pipedrive、Zoho）——每个都有各自的 API 和工具；此技能仅涵盖 HubSpot。
- CRM 策略、销售流程设计或管道方法论——这属于组织/战略工作，而非 API 操作。