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 是一個以代理為優先、僅使用標準程式庫的命令列介面，適用於 HubSpot CRM v3 API。它涵蓋完整的問題範圍：記錄、搜尋與管線檢視。
crm/scripts/crm-cli --help # 不需要 token 或網路連線
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）或擷取單一記錄（GET by ID）；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：13 個針對 HubSpot API 樁的確定性測試，包括變更保護與唯讀合約。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 操作。