actions

操作

有三种东西都叫这个名字，区分它们就是大部分工作：

• 操作是集成针对一个对象执行的一项操作： “NetSuite upsert customer”“Enrich name”。目录是 actions 资源；每项都有一个 id 和一个 integrationName。
• 操作列是接入表格的操作：包括要执行的操作、它的 params，以及说明该行哪些列为其提供数据的 input 映射。它位于表格的 objectsColumns 中（tables 技能介绍如何添加和更改操作列）。
• 操作运行是针对一行执行一次操作列的操作。 一次尝试结束后就会保存运行记录，因此其状态始终为 COMPLETED 或 FAILED（API 的枚举中也列有 ACTIVE、DELAYED、 WAITING，但不会以这些状态保存运行记录）。运行记录保留 14 天。

你可以通过 RevOS MCP 服务的通用工具访问它们：

调用	作用
api_read { "resource": "actions", "params": { "fields": "id,name,integrationName" } }	操作目录；添加 "onlyUsed": "true"，即可仅查看表格正在使用的操作
api_read { "resource": "actions", "id": "<action id>" }	查看一个操作：name、description、integrationName
api_read { "resource": "actions", "id": "<action id>", "method": "errorInstructions" }	查看此组织针对该操作的错误撰写的说明
api_read { "resource": "action-runs", "params": { … } }	列出运行记录：filter、orderBy、fields、pageSize
api_read { "resource": "action-runs", "id": "<run id>" }	查看一条运行记录及其 input 和 result
api_write { "resource": "action-runs", "data": { "tableId": "…", "columnId": "…" } }	运行一个操作列——请先参阅 references/run.md

本技能中的调用均可直接使用：直接调用即可。 只有在其中某个调用被拒绝，或你需要本技能未提及的筛选条件或字段时， 才使用 api_search 和 api_details。

出现失败：从运行记录入手

这里大多数问题都是“为什么失败了”。请分层排查，找到能回答问题的第一层就停止：如果运行记录的结果已经指出失败原因，就不需要查看表格架构；继续获取只会让用户更慢地得到答案，还会被他们未要求的细节淹没。

查找运行记录。 用户可能会直接提供运行 ID，该 ID 来自 UI 中的操作运行抽屉。更常见的是，用户会提供记录名称，例如“deal 31415926535”、某家公司或某个联系人。该 ID 是行的 objectId：一行通常会带有记录在源系统中的 ID。它并不唯一：同一条记录可以出现在多个表格中，而一行可以有多个操作列（例如，将数据同步到 NetSuite 的操作列旁边还有一个写回 HubSpot 的操作列），每个操作列都有各自的运行记录。因此，请先列出该记录最新的运行记录，不要获取其负载（一条运行记录的 input 和 result 可能占用数千个 token）：

api_read { "resource": "action-runs",
           "params": { "filter": "objectId == \"<record id>\"",
                       "orderBy": "createdAt desc", "pageSize": 5,
                       "fields": "id,actionId,columnId,modelId,objectName,status,createdAt" } }

如果知道表格 ID，可在筛选条件中添加 && modelId == "<table id>"。 然后，选取与问题相关的操作列（modelId、columnId）的最新运行记录，并按 ID 读取该记录。如果状态为 COMPLETED，说明该记录目前已不再失败：请告知用户。如果运行记录涉及多个表格或操作列，而请求没有说明具体是哪一个（例如“到 NetSuite 的操作”），请列出它们并询问用户。

如果既没有运行 ID，也没有记录，请列出失败记录，不要获取负载：

api_read { "resource": "action-runs",
           "params": { "filter": "status == \"FAILED\" && modelId == \"<table id>\"",
                       "orderBy": "createdAt desc", "pageSize": 10,
                       "fields": "id,actionId,columnId,modelId,objectId,objectName,status,attemptsMade,createdAt" } }

modelId 是表格的 ID。如果知道 columnId 或 objectId，可以据此缩小范围。

按 ID 读取运行记录。一次调用即可获取核心信息和两个负载：actionId、columnId、modelId、objectId、objectName、 status、attemptsMade、input 和 result。

读取组织的错误说明，对应运行记录的 actionId。 无论错误看起来多么明显，在读取运行记录后都必须进行此调用：使用该 ID 调用 actions 上的 api_read，并设置 method: "errorInstructions"。说明见下文。这些说明通常会直接将错误消息对应到其原因和解决办法，并指出由谁来修复。 错误所在位置。 没有单独的错误列。result 包含整个运行结果，这是一个由 metadata.success 区分的联合类型。失败时，它包含：

• metadata.error.message — 应当信任并引用的消息。如果它只是一个 HTTP 状态行（"Request failed with status code 400"），供应商自己的消息位于 error.details.response.data；请引用该消息；
• metadata.error.aiMessage — 保存失败时自动生成的 AI 改写内容（付费套餐有每日上限）。表格单元格会显示它，格式为 ❌ <aiMessage>，因此用户从单元格复制的错误文本通常是这段改写，而非系统消息。切勿将其说成系统自己的错误；
• error — 经过规范化的对象，包含 message、code、details、isUnrecoverable 和 retryAfter。

error.isUnrecoverable: true 表示框架已停止重试：任何不是 429 的 HTTP 4xx、未通过验证的输入，或明确表示不可恢复的操作都会导致这种情况。不作修改重新运行仍会以同样方式失败；修复原因后则可能成功。

很多失败在这里就能得到完整解释——目标系统拒绝的凭据、权限问题，或已指出字段和原因的验证消息。如果结合组织的说明阅读 result 后，能得出用户可以采取行动的结论，那就是答案：引用该内容，说明该怎么做，然后停止。

ID 无法解析时。 按 ID 调用 api_read 会返回 data: null，而不是 404。（该 ID 也可能是运行的 jobId，单元格的 metadata.jobId 中会包含它——两者都能解析。）即使其背后的运行已被删除，表格单元格仍会继续显示失败，因此某个 ID 可能指向早于 14 天时间窗口的运行。请说明这一点并停止——任何一页 action-runs 都不会包含它。如果用户引用了错误文本，仍值得向他们复述。然后提出可行的做法：重新运行该操作，并诊断新产生的失败。

仅凭运行结果无法回答时 — 错误涉及缺失、为空或格式错误的值，或用户询问某个值应从何处取得时 — 请继续阅读 references/debug.md：了解映射、数据血缘，以及如何说明故障所在。

组织的错误说明

组织会记录其操作错误的含义及修复方法：某个 NetSuite 错误对他们究竟意味着什么、各类问题由谁修复，以及如何构建指向其 CRM 的链接。诊断每次失败的运行时，请根据运行的 actionId 读取一次：

api_read { "resource": "actions", "id": "<the run's actionId>", "method": "errorInstructions" }

它会返回三段文本；如果没有相关说明，每段都为 null：

• global — 适用于该组织中的所有操作；
• integration — 适用于该操作所属集成中的所有操作；
• action — 仅适用于此操作。

它们会累积生效，而不是互相覆盖：操作级说明默认你已阅读集成级说明。

那些可能让显而易见的建议变得不正确的约定，就记录在这些说明中。如果其中规定了措辞、链接格式或修复负责人，请按其要求处理。如果三者均为 null，说明组织没有为此操作写下任何内容；请继续处理，无需参考这些说明。如果读取操作被拒绝，请勿重试：根据运行结果继续处理，并说明你无法读取这些说明。

运行操作

运行操作会作用于已连接的系统——在客户的 CRM 或 ERP 中创建和更新记录——因此只有在用户提出要求时才运行，并在首次对 action-runs 调用 api_write 前阅读 references/run.md。

同步

“同步”有两种含义：摄取，即连接将源系统拉取到 RevOS 中（“同步 HubSpot”）；以及激活，即操作将一行数据推送出去（“将此交易同步到 NetSuite”）。摄取属于 connections 技能。要根据 ID 或链接立即同步单条记录，请先在其立方体中检查该记录。只有当 RevOS 中没有该记录，或用户刚刚在源系统中更改了它时，才摄取其源数据，然后对该单行运行操作。请阅读 references/sync-now.md 了解详情。

添加或更改操作列

这是对表格的更改，而不是对操作的更改：请查看 tables 技能中的列参考。此处的目录会告诉你要使用哪个 actionId，并通过操作的 description 说明它需要什么输入。

反馈问题

先用用户的说法说明原因，然后说明如何解决以及由谁来解决。如果修复涉及第三方，请逐字引用 metadata.error.message；用户将其转交给该第三方支持团队时，转述过的供应商错误消息毫无用处。使用 objectName 而不是 ID 来标明行。不要倾倒 input 或 result。