关于 work
通过 HubSpot Work 命令行界面查看和更新项目跟踪表、文档及自动化的技能。它帮助团队在操作前理解表结构与权限,并为记录更新和完成操作提供预览。
主要功能
- 01浏览工作区与项目
- 02查看表结构和记录
- 03读取项目文档与 Agent
- 04创建、更新和完成记录
- 05预览写入并检查权限
适用场景
- 01查找项目计划、状态与自动化
- 02确认表字段及其完成状态值
- 03预览后更新或完成记录
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ hubspot/ agent-cli-skills --skill work安装后在 Claude Code 中输入/work确认已加载。
详细介绍
HubSpot Work
hubspot work --help 和各命令的 --help 会说明标志、输入行和输出格式,并且会及时更新。如果命令拒绝了参数,其 --help 会显示确切的格式;许多命令直接将 ID 作为参数(tables get 7-123),而不是使用标志。本技能介绍你要操作的内容及其重要性,帮助你把“把 Pat 在启动看板上完成的所有事项都收尾”这样的请求,转化为正确的读取和写入操作,以及该如何向对方说明。
| 要了解或更改的内容 | 命令(位置参数中的 ID 用大写表示) |
|---|---|
| 内容所在位置 | projects list、projects get PROJECT_ID(其表和 Agent)、workspaces list |
| 对方指的是哪个表 | tables search --query WORDS、tables list --project ID |
| 表有哪些列、选项和分组 | tables get TABLE_ID;选项较多时使用 tables options TABLE_ID --column NAME |
| 表中有哪些内容 | records search --table ID(--filter、--group、--parent;其 --help 中有筛选语法)、records get --table ID RECORD_ID |
| 某条记录上的对话 | comments list --table ID --record ID |
| 计划和决策 | docs list --project ID、docs get DOCUMENT_ID |
| 哪些内容会自动运行 | agents list --project ID、agents get AGENT_ID |
| 某人的身份 | users search --query NAME --table ID;使用 hubspot whoami 查询“我” |
| 更改记录 | records create / records update --table ID(JSONL)、records complete --table ID RECORD_ID...、comments create --table ID --record ID --message TEXT |
什么是 Work
Work 是 HubSpot 的项目管理产品:团队的计划、跟踪器及其自动化功能,与 CRM 并列。目前处于公开测试阶段,因此某些账户可能尚未启用。
Workspace a team's area ("Marketing Ops") and its sharing
└── Project one initiative ("Q3 launch"): its tables, documents and agents
├── Table (7-123) a typed tracker; each row is a record
│ ├── Item a row, in one group
│ │ └── Subitem a child row of one item, with its own columns
│ └── Group a bucket of items: a phase, a week, a board column
├── Document the project's written context: briefs, plans, notes
└── Agent automation for the project: a goal plus the workflows that pursue it
- 工作区和项目是人们组织工作的方式,不只是文件夹。 项目是团队集中管理某项计划的跟踪器、书面计划和自动化功能的地方。有人问“启动项目进展如何?”时,答案分散在项目的各个表(状态)、文档(意图和决策)以及 Agent(自动运行的内容)中。总结之前,请先全部查看。
- 表是团队自行设计的跟踪器。 表中的列、选项和分组由团队自行定义。“已完成”可能是名为“已发布”或“已关闭”的选项;“受阻”可能是状态选项或分组;“负责人”可能是指派人列,也可能是带有自定义标签的人员类型列。解读、筛选或写入之前,先查看表的架构(
tables get);切勿根据标签猜测内部名称。 - 表示已完成的选项由表设置决定。 团队可能将“已发布”视为已完成,而“草稿已完成”不算。
tables get会说明具体设置:状态列的选项带有isDone,而doneValue是records complete写入的值。判断、筛选和报告“已完成”时,应依据此设置,而不是根据标签的字面含义。 - 分组和状态是不同的概念。 分组表示某项所在的位置(阶段、迭代或看板列);状态则是列值。有些团队通过在分组间移动事项来表示进度,另一些团队只更改状态。决定对方指的是哪一种之前,请根据分组和几条记录,了解该表的实际用法。
- 子项有各自独立的架构。 表的子项拥有自己的列(
subitemColumns),与事项的列相互独立。一个子项只属于一个事项,且自身没有分组。 - Agent 是项目的自动化功能。 Agent 有目标和指令,并通过响应表事件的工作流运行:创建事项、更改列、将事项移入分组、到达指定日期或按计划运行。
agents get会显示每个工作流的触发条件、执行操作、是否启用,以及 HubSpot(而非人员)暂停 Agent 时显示的pausedBecause。Work 的自动化功能由 Work Agent 管理,而不是由 CRM 工作流管理。
值、标签和 ID
每次读取都会给出记录的两种视图。values 是 Work 存储的内容(选项值、用户 ID、以 epoch 毫秒表示的日期),也是写入时可原样传回的内容。labels 是用户在屏幕上看到的内容。判断和写入时使用 values;与用户交流时使用 labels。在应该填写值的地方写入标签会失败,甚至可能存入筛选条件无法匹配的文本。
这种区分适用于所有地方:列的 name(work_col_3)与其标签(“截止日期”)、选项的 value 与其标签,以及组的 name(group_1)与其标签。7-123 这样的 ID(表格)是稳定的标识符;名称并不唯一,而且可能会变更。
人员使用用户 ID。所有者、受派人及其他人员列,以及 comments create --mention,都需要使用从 users search 获取的 HubSpot 用户 ID。只有能打开记录的人,才能在记录上发挥作用;因此,分配人员时,请将搜索范围限定到该表格:即使受派人无法查看表格,系统仍会保存此分配并发出警告,但在有人与其共享表格之前,他们无法打开记录。只容纳一人的人员列会替换当前人员,因此请说明要从记录中移除谁,而不只是说明要添加谁。
hasWorkAccess: false 表示此人在此账户中完全没有 Work 访问权限。
访问权限与缺失内容
每条 work 命令都会以运行 hubspot auth login 的用户身份执行,并使用其 Work 访问权限:他们能看到什么,你就能看到什么;你写入的内容也会通过 HubSpot Agent CLI 归属于他们。将记录称为“你的”或“分配给你”之前,请先确认该用户是谁(hubspot whoami),不要想当然。系统会有意拒绝服务密钥:每次 Work 读取和写入都会根据某个用户的访问权限进行检查。
- 没有找到某项内容,并不能证明它不存在。 用户无法查看的表格、项目和记录不会显示出来,而且表格搜索采用模糊匹配。请说“我找不到你能查看的名为 X 的表格”,而不要说“没有名为 X 的表格”,并提出改用其他关键词搜索或浏览项目。stderr 中的提示会说明列表是否不完整。
- 请阅读错误信息,其中会告诉你该怎么做。 拒绝操作时会说明原因:账户尚未启用 HubSpot Work(错误信息会链接到 Product Updates 中的 Beta 页面,请转发该链接);登录缺少 Work 的读取或写入权限(运行
hubspot auth login --force并授予相应权限);或者用户无法访问该工作区、项目或表格(只有其所有者才能共享)。请告知用户如何解决;不要重试,也不要绕过限制。 - 评论会进行第二次权限检查。 用户只要能看到表格,就可以读取或编辑记录;但发表评论会通过 HubSpot 的评论服务进行,该服务可能需要一两分钟才能识别刚创建的表格。如果用户明确有权访问某个表格,但评论被拒绝,通常是因为服务延迟:请等待一分钟后重试,再判断是否为权限问题。
写入内容会展示给相关人员
Work 表是共享的实时团队数据。更改会立即对所有能查看该表的人显示,出现在记录的活动中,还可能触发其他操作:
- 写入可能触发自动化。 创建条目、更改列或将条目移到某个分组,都可能触发 Agent 的工作流:发送通知、新建子条目、更新另一条记录,或写入 CRM。批量更改前,请查看项目的 Agent,了解更改会触发什么,并告知相关人员。
- 提及和分配会通知相关人员。 使用
--mention添加评论会通知被提及的人;分配给某人的条目会出现在其所有项目中的「我的工作」列表里。评论措辞应符合对方希望看到的方式,不要提及或分配给对方未指定的人。 - 通过 CLI 添加的评论无法撤回。 此处无法编辑或删除评论或记录。如需移除内容,请将记录的
url发给对方,让其在 HubSpot 中操作。
因此,records update 和 records complete 会要求先预览。--dry-run 会显示每条记录的当前值和新值,并生成摘要;使用该摘要应用更改时,会重新检查每条记录。如果队友期间编辑了某条记录,应用操作就会被拒绝,你需要重新预览。请按预览的用途使用它:向对方展示将要更改的内容(使用标签,并注明数量),确认与对方的要求一致,然后再应用。当请求范围较大(例如「将所有内容标记为已完成」或「移动 Pat 的所有条目」)时,务必先确认筛选条件符合意图,再进行任何更改,例如检查部分匹配记录。
查找和阅读
- 从对方提到的对象入手。
tables search会在对方能查看的所有项目中,按名称关键词查找表;对方提到项目或不知道表名时,可以用projects list和projects get浏览。projects get一次读取即可返回项目的表和 Agent;docs list则会列出其文档。 - 搜索前先了解表。
tables get会告诉你哪一列存储状态、截止日期或负责人,各选项的值是什么,以及有哪些分组。然后使用存储值(--filter)进行筛选,而不是根据标签筛选。 - 有些列不可写,有些选项列表不完整。 标记为
readOnly的列(系统字段、计算字段、汇总字段,以及不允许编辑的引用字段)会拒绝写入,因此不要计划修改这些列;请改为更改其来源,或告知对方。当列的optionsSource为PAGED或EXTERNAL(负责人、用户、人员、管道阶段)时,tables get只会列出部分选项或不列出选项:tables options会分页列出并搜索完整列表,并提供用于写入的每个选项的value和用于说明的label。 - 总结前先完整读取。 列表、搜索结果和文档每次只返回一页,默认的 jsonl 输出也只会打印行,因此被截断的页面看起来可能完整。如果答案需要涵盖全部内容(例如数量、「没有逾期事项」或计划摘要),请使用
--format json读取,并通过--after跟进meta.next,直到其值为 null。 - 说明读取到的事实,并标明推断。「Launch email 的状态是 Blocked」是数据中的内容;「因此发布会延期」则是你的解读。请将两者区分开,让对方可以信任事实并判断推断。
- 提供链接。 记录、表、文档和 Agent 都带有
url。请将你找到或更改的内容链接发给对方,以便其在 HubSpot 中查看。
写入
- 只编辑要求修改的内容。 根据记录的
id和recordType,以及你要修改的values,构建每一行更新数据;省略的字段会保留原值。发送整行记录会重写你原本不打算改动的字段。 - 创建时必须指定位置。 新项目需要归属一个分组(选择用户指定的分组;如果用户未指定,则选择表格中的第一个分组);新子项目需要指定其父项目。
- 完成状态以表格的定义为准。
records complete会设置每个表格各自的完成状态,因此优先使用它,而不是自行写入状态值。 - 每次调用最多处理 100 条记录。 较大的更改应分批处理,逐批预览,并以通俗的方式报告进度。
- 查看写入报告。 写入操作会返回更新后的记录,以及
skipped(记录已处于目标状态,未作更改)和warnings(例如,某位受分配者无法查看该表格)。请告知用户这两项信息。
不属于 Work 的内容
联系人、公司、交易、工单和 CRM 任务都是 CRM 记录,各自有对应的技能;尽管 Work 表格可以通过关联列与它们建立链接。CRM 工作流与 Work Agent 是不同的产品。HubSpot 开发者项目(hs project)与 Work 项目无关。