HubSpot CRM 开放平台 Skill
HubSpot 用一套统一的 crm/objects/{objectType} 端点管理联系人、公司、交易和自定义对象，但最容易踩的坑是关联——它从来不是记录上的字段，而是独立的 API 调用；HubSpot 自己的创建联系人示例里甚至保留了一个叫 company 的纯文本陷阱属性，写进去只是存了字符串，不会建立任何真实关联。这份 skill 还标出了文档里自相矛盾的两处限流数字，以及 2026-09 起新出现、尚未经真实调用验证的写操作校验规则。
安装
选你用的 Agent，复制命令。
npx -y skills add fxp/skillify --skill hubspot --agent claude-code --yes装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。
npx -y skills add fxp/skillify --skill hubspot --agent codex --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill hubspot --agent cursor --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill hubspot --agent opencode --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill hubspot --agent gemini-cli --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill hubspot --agent github-copilot --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill hubspot --agent trae --yes装到项目的 .trae/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill hubspot --agent windsurf --yes装到项目的 .windsurf/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill hubspot --agent qwen-code --yes把 --agent 换成你用的 Agent 标识，可以一次写多个。skills CLI 1.5.25 共支持 79 个，例如 qwen-code、kimi-code-cli、trae-cn、qoder、lingma、cline、roo。
或者让 Agent 自己装
读 https://github.com/fxp/skillify/blob/main/skills/hubspot/prompt.md 并照它执行装对了的标志：references/ 下有 6 份文档。
装好后，可以这样问你的 Agent
这份 Skill 覆盖的典型任务。点一下复制。
6 类能力
每类能力对应一份 reference，Agent 按任务只打开需要的那份。
鉴权
私有应用 access token / Service Key（beta）/ OAuth 应用怎么选，scopes 命名模式，已弃用的 hapikey
对象 CRUD 与属性
contacts / companies / deals / 自定义对象的统一增删改查、内部名 vs 显示标签、自定义对象 Schemas API
关联
关联是独立的 API 调用而非记录字段、创建时内联关联、单条与批量关联端点、默认关联类型 ID 表
搜索
filterGroups 的 AND/OR 语义、过滤操作符、按关联搜索、排序与分页上限
批量操作
批量创建/读取/更新/upsert/归档、100 条硬上限、objectWriteTraceId 定位失败项、423 锁冲突的退避建议
错误与限流
错误响应结构与常见状态码、burst+daily 双重限流、文档自相矛盾的加购上限、限流响应头与重试策略
当前事实
整理自官方文档（抓取于 2026-09-21），还没有用真实凭证验证。
| 项 | 值 |
|---|---|
| Base URL | https://api.hubapi.com，所有 CRM 端点都在这个域名下；developers.hubspot.com 只是文档站，不能拿来发请求 |
| 鉴权 | Authorization: Bearer <token>，token 来自私有应用或 Service Key（beta），格式类似 pat-na1-xxxxxxxx-...；旧式 hapikey query 参数已不适用于 CRM 对象 API |
| 属性名 | 读写属性只认内部名 name（如 amount），和 UI 显示的 label（如 *Deal Amount*）经常对不上，先查 GET /crm/properties/v3/{objectType} |
| 批量上限 | 对象 batch/* 端点硬上限 100 条/请求，超出直接报错而不是自动分页；关联的 batch 端点是另一套上限（读 1000、建 2000） |
| 限流 | 同时有 burst（每 10 秒）和 daily 两套限制，具体数字按 token 类型与 Tier 而定；Search 端点是独立的 每秒 5 次，且响应不带任何限流头 |
照通用经验写容易错的 6 件事
来自官方文档，还没有用真实凭证验证。
- 关联（association）不是记录字段，是独立的 API 调用。创建联系人时传入的
company: "HubSpot"只是纯文本属性，不会让这条记录出现在任何公司详情页的关联列表里；真正建立关联要在associations数组里传id+associationTypeId，或事后调用PUT /crm/objects/v3/contacts/{id}/associations/companies/{companyId}/{typeId}。 - filterGroups 之间是 OR，组内 filters 之间是 AND，方向极易记反。记反不会报错，只会静默返回一个偏小甚至为空的结果集；每个
filterGroups最多 6 个filters，总数上限 18 个，最多 5 个 filterGroups，超限才会报VALIDATION_ERROR。 - 对象 batch 端点硬上限 100 条，不会自动分页。
batch/create、batch/read、batch/update、batch/upsert、batch/archive一律 100 条/请求，超出直接报错，需要客户端自己切批；关联 batch 端点是另一套上限（读 1000、建 2000、归档 100），不要混用。 - 属性内部名和 UI 标签经常对不上。UI 上的 *Deal Amount* 实际内部名是
amount，照界面文字直接拼字段名大概率错；下拉/单选的取值也是内部值（如生命周期阶段marketingqualifiedlead，自定义阶段甚至是纯数字字符串），先调GET /crm/properties/v3/{objectType}核对。 - 官方文档自己也说不清购买加购后的 burst 上限是多少。私有应用总览页写
200 次/10秒，限流总页写250 次/10秒，两页抓取时都是当前有效版本；不要硬编码任一数字，改成读响应头X-HubSpot-RateLimit-Max做动态节流。 - 2026-09 起写操作可能被账号管理员配置的校验规则拦下。从 2026-09-08
/2026-09/API 版本 GA 开始，HubSpot 会对 CRM 写路径强制执行管理员配置的校验规则，但文档没说清是只影响/2026-09/前缀还是也影响 legacyv3路径——之前能跑通的PATCH/POST可能因此突然报错，与代码本身无关。