crm

HubSpot CRM 操作

使用此技能通过 HubSpot CRM v3 API 读取 HubSpot CRM 数据，并在获得明确确认后更新数据：联系人记录、联系人搜索、交易管道视图和交易阶段变更。这是一个面向单一 CRM 供应商（HubSpot）的工具技能。构建 HubSpot 应用或工作流属于应用开发；此技能负责日常 Agent 工作流：回答“这个联系人是谁？”“管道中有哪些交易？”，以及执行经确认的阶段变更。

操作约定

1. 进行任何变更前，先只读查询。 可以自由列出和搜索联系人、查看交易和管道。随附的 crm-cli 脚本只执行读取操作，不会写入任何内容。
2. 操作前确认目标、范围和回滚路径。 将交易移至新阶段会更改供收入报告读取的共享管道：必须有人明确指示交易和目标阶段，并通过 crm-cli 使用 --dry-run 预览和 --yes 确认。阶段变更可以撤销，但会留下审计记录——操作前务必确认。
3. 遵守读取范围限制。 HubSpot 使用 limit 分页；不要超出任务所需的范围继续翻页。crm-cli --limit 会限制每次列表和搜索的结果数。
4. 控制证据范围。 仅引用简短的姓名、电子邮件地址、金额和阶段标签；切勿在聊天中完整输出记录、令牌或原始负载。
5. 了解对象模型。 联系人和交易是不同的对象，各自具有属性映射；阶段转换必须使用交易所属管道中的阶段 ID（通过 pipelines list 获取），而不是阶段标签。

crm-cli 脚本

scripts/crm-cli 是一个面向 Agent、仅依赖标准库的 CLI，可调用 HubSpot CRM v3 API。它涵盖完整的问题范围：记录、搜索和管道视图。

crm/scripts/crm-cli --help                                # no token or network needed
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   # preview
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes       # confirmed

退出代码：0 表示成功，1 表示 API 错误或检查失败，2 表示用法错误。阶段变更设有防护：如果未使用 --dry-run 或 --yes，脚本会以退出代码 1 拒绝执行，且不会调用 API。读取范围由 --limit 限制（默认值为 20，最大值为 100）。

操作流程

1. 明确问题范围：是查询（CRM 中有哪些人／事），还是变更（移动交易）？使用 contacts search／contacts list 或 deals list 查找对象。
2. 在范围内读取：使用 contacts get 获取单条记录，使用 deals list 查看管道视图（可按管道和阶段筛选），使用 pipelines list 将阶段标签解析为 ID。
3. 梳理答案：将问题对应到证据（联系人详情、交易金额／阶段、管道分布）。
4. 经确认后操作：只有收到人工变更指示后，才能使用 --dry-run 预览并通过 --yes 确认。
5. 验证：重新读取交易（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：用于评估 Agent 运行输出质量的六个用例。

验证边界

声明	最低证据
联系人存在	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 Marketing 功能，而非此技能涵盖的 CRM API。
• 其他 CRM（Salesforce、Pipedrive、Zoho）——每种 CRM 都有自己的 API 和工具；此技能仅涵盖 HubSpot。
• CRM 战略、销售流程设计或管道方法论——这些属于组织/战略工作，而非 API 操作。