work

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HubSpot Work

hubspot work --help

and each command's

--help

document the flags, input lines and output shapes, and they are kept current. When a command rejects its arguments, its

--help

shows the exact form; many take the id itself as an argument (

tables get 7-123

) rather than a flag. This skill is about what you are touching and why it matters, so you can turn a request like "close out everything Pat finished on the launch board" into the right reads, the right writes, and the right thing to tell the person.

To learn or change	Command (positional ids in caps)
where things live	`projects list` , `projects get PROJECT_ID` (its tables and agents), `workspaces list`
which table someone means	`tables search --query WORDS` , `tables list --project ID`
what a table's columns, options and groups are	`tables get TABLE_ID` ; `tables options TABLE_ID --column NAME` for long option lists
what is in it	`records search --table ID` ( `--filter` , `--group` , `--parent` ; its `--help` has the filter grammar), `records get --table ID RECORD_ID`
the conversation on a record	`comments list --table ID --record ID`
the plan and decisions	`docs list --project ID` , `docs get DOCUMENT_ID`
what runs on its own	`agents list --project ID` , `agents get AGENT_ID`
who someone is	`users search --query NAME --table ID` , `hubspot whoami` for "me"
change records	`records create` / `records update --table ID` (JSONL), `records complete --table ID RECORD_ID...` , `comments create --table ID --record ID --message TEXT`

hubspot work --help

以及每个命令的

--help

会记录各种参数选项、输入行和输出结构，并保持最新。命令拒绝参数时，其

--help

会给出准确用法；许多命令将 id 本身作为位置参数（例如

tables get 7-123

），而不是作为选项。这个 skill 关注的是你正在操作什么，以及这为什么重要，从而能把“关闭发布看板上 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`

What Work is

Work 是什么

Work is HubSpot's project management product: a team's plans, trackers and the automation around them, living next to its CRM. It is in public beta, so an account may not have it yet.

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

Workspaces and projects are how people organize, not just folders. A project is where a team keeps one initiative's tracker, its written plan and its automation together. When someone asks "what's going on with the launch?", the answer is spread across the project's tables (status), documents (intent and decisions) and agents (what runs on its own). Read all three before summarizing.
A table is a tracker the team designed. Its columns, options and groups mean whatever that team decided. "Done" might be an option called "Shipped" or "Closed", "blocked" might be a status option or a group, and "owner" might be an assignee column or a person-type column with a custom label. Read the table's schema (
```
tables get
```
) before you interpret, filter or write; never guess internal names from labels.
Which option means done is the table's setting. A team might count "Published" as done and "Draft done" as not.
```
tables get
```
says which: a status column's options carry
```
isDone
```
, and its
```
doneValue
```
is the value
```
records complete
```
writes. Count, filter and report "done" by that, not by what a label sounds like.
Groups and statuses are different things. A group is where an item sits (a phase, a sprint, a board column); a status is a column value. Some teams move items between groups to show progress, others only change status. Look at how this table is actually used, from its groups and a few records, before deciding which one the person means.
Subitems are a second schema. A table's subitems have their own columns (
```
subitemColumns
```
), separate from the items' columns. A subitem belongs to exactly one item and has no group of its own.
Agents are a project's automation. An agent has a goal and instructions, and runs through workflows that fire on table events: an item created, a column changed, an item moved to a group, a date reached, or a schedule.
```
agents get
```
shows what triggers each workflow and what it does, whether it is enabled, and
```
pausedBecause
```
when HubSpot (not a person) paused it. Work's automation lives on Work agents, not in CRM workflows.

Work 是 HubSpot 的项目管理产品：团队的计划、tracker 及其自动化功能都位于 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

工作区和项目不只是文件夹，而是人们组织工作的方式。 一个项目是团队集中存放某项工作的 tracker、书面计划和自动化的位置。当有人问“发布进展如何？”时，答案分散在项目的表格（状态）、文档（意图和决策）和 Agent（自动运行的内容）中。汇总前先读取这三类内容。
表格是团队自行设计的 tracker。 其列、选项和分组的含义由团队自行决定。“Done”可能是名为“Shipped”或“Closed”的选项，“blocked”可能是状态选项，也可能是分组，而“owner”可能是 assignee 列，也可能是带自定义标签的人员类型列。解读、筛选或写入前先读取表格 schema（
```
tables get
```
）；绝不根据标签猜测内部名称。
哪个选项表示完成，取决于表格设置。 团队可能将“Published”视为完成，而将“Draft done”视为未完成。
```
tables get
```
会明确说明：状态列的选项带有
```
isDone
```
，其
```
doneValue
```
是
```
records complete
```
写入的值。统计、筛选和报告“已完成”时，应依据该设置，而不是标签听起来像什么。
分组和状态不是同一概念。 分组表示事项所在的位置（阶段、sprint、看板列）；状态则是列中的一个值。有些团队通过在分组间移动事项来体现进度，有些则只更改状态。判断用户指的是哪一种之前，先查看该表实际如何使用这些概念，包括其分组和若干记录。
子项采用第二套 schema。 表格的子项拥有自己的列（
```
subitemColumns
```
），与事项自身的列相互独立。子项恰好属于一个事项，且没有自己的分组。
Agent 是项目的自动化机制。 每个 Agent 都有一个目标和一组指令，并通过工作流运行；这些工作流会在表格事件发生时触发：创建事项、更改列、将事项移至分组、到达某个日期或按计划触发。
```
agents get
```
会显示每个工作流的触发条件和执行内容、是否已启用，以及 HubSpot（而非人员）暂停它时的
```
pausedBecause
```
。Work 的自动化机制位于 Work Agent 中，而不是 CRM workflows 中。

Values, labels and ids

值、标签和 id

Every read gives you two views of a record.

values

are what Work stores (option values, user ids, dates as epoch milliseconds), exactly what a write accepts back.

labels

are what a person sees on screen. Reason and write with

values

; speak to the person in

labels

. Writing a label where a value belongs fails, or worse, stores text nobody's filter matches.

The same split applies everywhere: column

name

(

work_col_3

) versus its label ("Due date"), an option's

value

versus its label, a group's

name

(

group_1

) versus its label. Ids such as

7-123

(a table) are stable handles; names are not unique and can change.

People are user ids. Owner, assignee and other person columns, and

comments create --mention

, take a HubSpot user id from

users search

. A person is only useful on a record they can open, so when assigning someone, scope the search to that table: an assignee who can't see the table is still saved, with a warning, but they can't open the record until someone shares the table with them. A person column that holds one person replaces whoever is there, so say who you'd be taking off the record, not just who you'd be adding.

hasWorkAccess: false

means the person has no Work access in this account at all.

每次读取都会提供记录的两个视图。

values

是 Work 存储的内容（选项值、用户 id、以 epoch 毫秒表示的日期），也正是写入时可原样传回的值。

labels

是用户在屏幕上看到的内容。判断和写入时使用

values

；与用户交流时使用

labels

。在应写

value

的位置传入 label 会失败，更糟的是会存入一段任何筛选条件都无法匹配的文本。

这种区分适用于所有地方：列的

name

（

work_col_3

）与其标签（“Due date”）、选项的

value

与其标签、分组的

name

（

group_1

）与其标签。诸如

7-123

这样的 id（表示表格）是稳定句柄；名称则不唯一，而且可能发生变化。

人员以用户 id 表示。Owner、assignee 和其他人员列，以及

comments create --mention

，都需要使用从

users search

获取的 HubSpot 用户 id。某个人只有在能打开记录时才真正有用，因此分配人员时应将搜索范围限定到该表：无法看到表格的 assignee 仍可能被保存，并伴随警告，但在有人与表格共享权限之前，他们无法打开记录。容纳单个人员的列会替换原有人员，因此要明确说明将从记录中移除谁，而不只是要添加谁。

hasWorkAccess: false

表示该人员在此账户中完全没有 Work 访问权限。

Access and absence

访问权限与未找到的内容

Every

work

command runs as the person who ran

hubspot auth login

, with their Work access: what they can see is what you can see, and what you write is attributed to them, through the HubSpot Agent CLI. Before calling a record "yours" or "assigned to you", check who that is (

hubspot whoami

) rather than assuming. Service keys are refused on purpose: every Work read and write is checked against one person's access.

Not finding something is not proof it doesn't exist. Tables, projects and records the person can't see are left out, and table search is fuzzy. Say "I couldn't find a table called X that you can see" rather than "there is no table X", and offer to search by another word or browse a project. Notes on stderr say when a list is incomplete.
Read the error, it tells you what to do. A refusal names its cause: the account doesn't have HubSpot Work yet (it links to the beta in Product Updates, so pass that link on), the login lacks Work's read or write permission (
```
hubspot auth login --force
```
and grant it), or the person can't access that workspace, project or table (only its owner can share it). Pass the remedy on; don't retry or work around it.
Comments run a second permission check. Reading or editing a record works as soon as the person can see the table, but commenting goes through HubSpot's commenting service, which can take a minute or two to recognize a table that was only just created. A comment refused on a table the person clearly has access to is usually that delay: wait a minute and try again before calling it a permissions problem.

每个

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 评论服务，该服务可能需要一两分钟才能识别刚创建的表格。如果用户显然有权访问表格，但评论仍被拒绝，通常原因是这一延迟：等待一分钟后重试，再将其视为权限问题。

Writes land in front of people

写入会立即呈现在人们面前

A Work table is shared, live team data. Changes appear immediately to everyone who can see the table, show up in the record's activity, and can set other things in motion:

Writes can trigger automation. Creating an item, changing a column, or moving an item to a group can fire an agent's workflow: a notification, a new subitem, an update to another record, a CRM write. Before a bulk change, check the project's agents to see what that change will kick off, and tell the person.
Mentions and assignments reach people. A comment with
```
--mention
```
notifies that person, and an item assigned to someone lands on their My work list across every project. Write comments as the person would want them read, and don't mention or assign anyone they didn't ask you to.
Comments are permanent from the CLI. There is no edit or delete for comments or records here. To remove something, send the person the record's
```
url
```
to do it in HubSpot.

That is why

records update

and

records complete

make you preview first.

--dry-run

shows each record's current and new values and gives a digest; applying with that digest re-checks every record, so if a teammate edited one in between, the apply refuses and you preview again. Use the preview the way it is meant: show the person what will change (in labels, with counts), confirm it matches what they asked for, and only then apply. When a request is broad ("mark everything done", "move all of Pat's items"), make sure the filter matches the intent before anything changes, for example by checking a sample of the matching records.

Work 表格是共享的实时团队数据。更改会立即显示给所有有权查看表格的人，记录的活动记录中也会出现这些更改，并且可能触发其他操作：

写入可能触发自动化。 创建事项、更改列或将事项移至分组，都可能触发 Agent 的工作流，例如发送通知、创建子项、更新另一条记录或写入 CRM。批量更改前，先检查项目的 Agent，确认该更改会触发什么，并告知用户。
提及和分配会触达相关人员。 带有
```
--mention
```
的评论会通知对应人员，而分配给某人的事项会出现在其所有项目的 My work 列表中。评论应写成对方希望看到的样子；不要提及或分配用户未要求提及或分配的人。
通过 CLI 创建的评论是永久性的。 这里无法编辑或删除评论或记录。若要移除某项内容，请把记录的
```
url
```
发给用户，让其在 HubSpot 中操作。

正因如此，

records update

和

records complete

要求先预览。

--dry-run

会显示每条记录的当前值和新值，并给出摘要；使用该摘要执行应用时会重新检查每条记录，因此如果在此期间队友编辑了其中一条，应用操作会被拒绝，并要求再次预览。应按预览的用途使用它：向用户展示将发生的变化（使用 labels，并附上数量），确认这与他们的要求一致，然后才执行。对于范围较大的请求（“将所有事项标记为完成”“移动 Pat 的所有事项”），在任何更改发生前都要确认筛选条件符合请求意图，例如抽样检查匹配的记录。

Finding and reading

查找与读取

Start from what the person named.
```
tables search
```
finds a table by words in its name across every project they can see;
```
projects list
```
and
```
projects get
```
let you browse when they name a project or don't know the table's name.
```
projects get
```
returns the project's tables and agents in one read;
```
docs list
```
gives its documents.
Learn the table before searching it.
```
tables get
```
tells you which column holds the status, the due date or the owner, each option's value, and which groups exist. Then filter on stored values (
```
--filter
```
), not on what the labels say.
Some columns can't be written, and some option lists are partial. A column marked
```
readOnly
```
(system fields, calculations, rollups, references that don't allow editing) rejects writes, so don't plan an edit to it; change its source instead, or tell the person. When a column's
```
optionsSource
```
is
```
PAGED
```
or
```
EXTERNAL
```
(owners, users, people, pipeline stages),
```
tables get
```
lists only some of its options or none:
```
tables options
```
pages and searches the full list and gives you each option's
```
value
```
to write and
```
label
```
to say.
Read all of it before you summarize. Lists, searches and documents return a page at a time, and the default jsonl output prints only the rows, so a cut-off page looks complete. When the answer needs everything (a count, a "nothing is overdue", a summary of a plan), read with
```
--format json
```
and follow
```
meta.next
```
with
```
--after
```
until it is null.
Say what you read, and mark what you infer. "Launch email is Blocked" is in the data; "so the launch will slip" is your reading of it. Keep the two apart, so the person can trust the facts and judge the inferences.
Link back. Records, tables, documents and agents come with a
```
url
```
. Give the person links to what you found or changed so they can see it in HubSpot.

从用户明确提到的对象开始。
```
tables search
```
可按名称中的词，在其可见的所有项目中查找表格；当用户提到某个项目或不知道表格名称时，可使用
```
projects list
```
和
```
projects get
```
浏览。
```
projects get
```
一次读取即可返回项目的表格和 Agent；
```
docs list
```
则返回其文档。
搜索表格之前，先了解表格。
```
tables get
```
会指出哪一列保存状态、截止日期或 owner，各选项的值，以及存在哪些分组。然后根据存储的值（
```
--filter
```
）筛选，而不是根据标签。
有些列不能写入，有些选项列表并不完整。 标记为
```
readOnly
```
的列（系统字段、计算值、rollup、不允许编辑的引用）会拒绝写入，因此不要计划编辑这类列；应改为修改其来源，或告知用户。当某列的
```
optionsSource
```
为
```
PAGED
```
或
```
EXTERNAL
```
（owner、users、people、pipeline stages）时，
```
tables get
```
只会列出部分选项，也可能一个都不列：
```
tables options
```
可分页搜索完整列表，并给出每个选项应写入的
```
value
```
和应展示的
```
label
```
。
汇总前先读取全部内容。 列表、搜索和文档一次只返回一页，默认 jsonl 输出仅打印各行，因此截断的一页看起来会像完整结果。当答案需要全部数据（计数、“没有逾期事项”、计划摘要）时，使用
```
--format json
```
读取，并按照
```
meta.next
```
配合
```
--after
```
持续请求，直到
```
meta.next
```
为 null。
说明你读取了什么，并标明哪些属于推断。 “Launch email is Blocked”是数据中的事实；“因此发布会延期”则是你的解读。务必将二者分开，让用户能够信任事实，并自行判断推断。
提供回链。 记录、表格、文档和 Agent 都带有
```
url
```
。将你找到或更改的内容链接发给用户，方便其在 HubSpot 中查看。

Writing

写入

Edit only what was asked. Build each update line from a record's
```
id
```
and
```
recordType
```
plus only the
```
values
```
you mean to change; fields you leave out keep their values. Sending back a whole record row rewrites fields you never meant to touch.
Creating needs a place. A new item needs a group (pick the one the person meant, or the table's first group if they didn't say); a new subitem needs its parent item.
Marking done is the table's notion of done.
```
records complete
```
sets each table's own done status, so prefer it over writing a status value yourself.
One call takes up to 100 records. Split larger changes into batches, preview each, and report progress in plain terms.
Read the write's report. A write returns the records as they now are, plus
```
skipped
```
(already in that state, nothing changed) and
```
warnings
```
(such as an assignee who can't see the table). Tell the person about both.

只编辑用户要求的内容。 每个更新行都由记录的
```
id
```
和
```
recordType
```
构成，并且只包含你确实要更改的
```
values
```
；省略的字段会保留原值。将整条记录行原样写回，会重写你根本无意触碰的字段。
创建时必须指定位置。 新事项需要一个分组（选择用户所指的那个；若用户未说明，则选表格的第一个分组）；新子项需要其父事项。
标记完成时，以该表对完成的定义为准。
```
records complete
```
会设置各表自身的完成状态，因此优先使用它，而不是自行写入状态值。
一次调用最多处理 100 条记录。 更改量更大时，请拆分为多个批次，逐批预览，并用通俗语言报告进度。
读取写入报告。 写入操作会返回记录当前的状态，以及
```
skipped
```
（已处于该状态，未发生更改）和
```
warnings
```
（例如 assignee 无法查看表格）。两者都要告知用户。

Not Work

不属于 Work 的内容

Contacts, companies, deals, tickets and CRM tasks are CRM records, with their own skills, even though a Work table can link to them through association columns. CRM workflows are a different product from Work agents. HubSpot developer projects (

hs project

) are unrelated to Work projects.

联系人、公司、交易、工单和 CRM 任务是 CRM 记录，即使 Work 表格可通过 association 列关联到它们，它们也各自有对应的 skill。CRM workflows 与 Work Agent 是不同的产品。HubSpot 开发者项目（

hs project

）与 Work 项目无关。