Back to Details

actions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Actions

Actions

Three things share the name, and telling them apart is most of the work:
  • An action is one operation of an integration against one object: "NetSuite upsert customer", "Enrich name". The catalogue is the 
    actions
    resource; each has an 
    id
    and an 
    integrationName
    .
  • An action column is an action wired into a table: which action, its 
    params
    , and the 
    input
    mapping that says which of the row's columns feed it. It lives in the table's 
    objectsColumns
    (the tables skill covers adding and changing one).
  • An action run is one execution of one action column against one row. Its status is one of 
    ACTIVE
    , 
    DELAYED
    , 
    WAITING
    , 
    COMPLETED
    , 
    FAILED
    . Runs are kept for 14 days.
You reach them through the RevOS MCP server's generic tools:
CallWhat it does
api_read { "resource": "actions", "params": { "fields": "id,name,integrationName" } }
the catalogue; add 
"onlyUsed": "true"
for the ones a table uses
api_read { "resource": "actions", "id": "<action id>" }
one action: 
name
, 
description
, 
integrationName
api_read { "resource": "action-runs", "params": { … } }
list runs: 
filter
, 
orderBy
, 
fields
, 
pageSize
api_read { "resource": "action-runs", "id": "<run id>" }
one run, with its 
input
and 
result
api_write { "resource": "action-runs", "data": { "tableId": "…", "columnId": "…" } }
run an action column — see references/run.md first
api_details({ resource: "action-runs" })
is the authority on the filter and field names; this skill covers what that schema can't tell you.
三个概念都使用这个名字，而区分它们是这项工作的核心：
  • action 是某个 integration 针对一个对象执行的一项操作： “NetSuite upsert customer”、“Enrich name”。action 目录是 
    actions
    resource；每个 action 都有 
    id
    和 
    integrationName
    。
  • action column 是接入 table 的 action：包括使用哪个 action、它的 
    params
    ，以及指定 table 中哪些列为其提供输入的 
    input
    mapping。它位于 table 的 
    objectsColumns
    中（添加和修改 action column 由 tables skill 负责）。
  • action run 是某个 action column 针对某一行的一次执行。 状态可以是 
    ACTIVE
    、
    DELAYED
    、
    WAITING
    、
    COMPLETED
    、 
    FAILED
    。执行记录会保留 14 天。
可以通过 RevOS MCP server 的通用工具访问它们：
CallWhat it does
api_read { "resource": "actions", "params": { "fields": "id,name,integrationName" } }
action 目录；加上 
"onlyUsed": "true"
可获取 table 使用的 actions
api_read { "resource": "actions", "id": "<action id>" }
单个 action：
name
、
description
、
integrationName
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": "…" } }
运行 action column——请先阅读 references/run.md
api_details({ resource: "action-runs" })
是 filter 和 field 名称的权威来源；本 skill 补充 schema 无法说明的信息。

Something failed: start from the run

出现失败时：从 run 开始

Most questions here are "why did this fail". Work in levels and stop at the first one that answers the question: a failure whose cause is already named in the run's own result doesn't need the table's schema, and pulling it anyway costs the user a slower answer buried in detail they didn't ask for.
Find the run. The user may hand you a run id straight from the action-run drawer in the UI. Otherwise list, without the payloads:
json
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
is the table's id. Narrow with 
columnId
or 
objectId
when you know them.
Read the run by id. One call, and it carries the spine as well as both payloads: 
actionId
, 
columnId
, 
modelId
, 
objectId
, 
objectName
, 
status
, 
attemptsMade
, 
input
and 
result
.
Where the error lives. There is no separate error column. 
result
holds the whole run result, a union discriminated by 
metadata.success
. On a failure it carries:
  • metadata.error.message
    — the message to trust and to quote;
  • metadata.error.aiMessage
    — a generated rewording, present only if the explain-error flow ran. Never present it as the system's own error;
  • error
    — a normalized object with 
    message
    , 
    code
    , 
    details
    , 
    isUnrecoverable
    and 
    retryAfter
    .
error.isUnrecoverable: true
means the framework deliberately stopped retrying: the condition is permanent (rejected credentials, a validation the target system will never accept), so suggesting a re-run unchanged is wrong.
A large share of failures are fully explained right here — credentials the target system rejected, a rate limit, a permission, a validation message that already names the field and the reason. When 
result
says something the user can act on, that is the answer: quote it, say what to do, stop.
When the id doesn't resolve. A table cell goes on showing a failure long after the run behind it was removed, so an id can name a run older than the 14-day window. Say so and stop — no page of 
action-runs
can contain it. If the user quoted the error text, that text is still worth reading back to them. Then offer what does work: re-run the action and diagnose the fresh failure.
When the run alone doesn't answer — the error is about a value that was missing, empty or malformed, or the user asks where a value should have come from — go on to references/debug.md: the mapping, the lineage, and how to say where the fault is.
这里的大多数问题都是“为什么失败了”。应逐层排查，并在第一个能够回答问题的层级停止：如果失败原因已经在 run 自身的 result 中明确指出，就不需要 table 的 schema；额外获取只会让答案变得更慢，并让用户淹没在并未询问的细节中。
查找 run。 用户可能会直接从 UI 的 action-run 抽屉中提供 run id。否则，在不获取 payload 的情况下列出记录：
json
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
是 table 的 id。已知时，可以使用 
columnId
或 
objectId
进一步缩小范围。
按 id 读取 run。 只需一次调用，即可获得核心信息以及两个 payload：
actionId
、
columnId
、
modelId
、
objectId
、
objectName
、
status
、
attemptsMade
、
input
和 
result
。
错误位于何处。 没有单独的 error column。
result
保存完整的 run result，它是一个以 
metadata.success
作为判别字段的联合类型。失败时，其中包含：
  • metadata.error.message
    ——应信任并直接引用的 message；
  • metadata.error.aiMessage
    ——重新生成的措辞，仅在 explain-error flow 已运行时存在。绝不能将其表述为系统自身的错误；
  • error
    ——一个规范化对象，包含 
    message
    、
    code
    、
    details
    、
    isUnrecoverable
    和 
    retryAfter
    。
error.isUnrecoverable: true
表示框架已主动停止重试：该情况是永久性的（例如凭证被拒绝，或目标系统永远不会接受的校验结果），因此建议原样重新运行是错误的。
很大一部分失败在这里已经得到充分解释——目标系统拒绝了凭证、触发了速率限制、缺少权限，或者校验消息已经指明了字段和原因。当 
result
中包含用户可以据此采取行动的信息时，这就是答案：引用它，说明该做什么，然后停止。
当 id 无法解析时。 在其背后的 run 被删除后，table cell 仍可能持续显示失败，因此 id 指向的 run 可能早于 14 天保留窗口。说明这一点并停止——任何 
action-runs
页面都不可能包含它。如果用户引用了 error 文本，仍应将这段文本读回给他们。然后提供可行的方案：重新运行 action，并诊断新产生的失败。
当仅凭 run 无法回答问题时——错误涉及缺失、空值或格式错误的 value，或者用户询问某个 value 应从哪里来——继续阅读 references/debug.md：其中介绍了 mapping、lineage，以及如何指出故障所在。

The organization's own instructions

组织自己的说明

Organizations write down how their integrations behave: what a particular NetSuite error really means for them, who fixes what, how a link to their CRM is built. These are served by the same MCP server as skills named 
org/…
, at three breadths:
  • org/global
    — applies to everything in this organization;
  • org/<integrationName>
    — everything involving that integration;
  • org/<integrationName>/<actionId>
    — that one action.
Take 
integrationName
from the action (
api_read
on 
actions
with the run's 
actionId
). Call 
skills_list
, then 
skills_read
on every one of the three that exists for the run's scope. They add up rather than override one another: the action-level text assumes you've read the integration-level one.
Read them once you know which action is involved and before you tell the user what to do. They are where a convention that makes your obvious recommendation wrong lives, and they often map an error message straight to its cause and fix. When they give wording, a link format, or an owner for the fix, use theirs.
If the server has no 
skills_list
tool, or lists nothing under 
org/
, there are no such instructions; carry on without them.
组织会记录其 integrations 的行为方式：某个特定的 NetSuite error 对他们而言实际意味着什么、由谁负责修复，以及如何构建指向 CRM 的链接。这些内容由同一个 MCP server 以名为 
org/…
的 skills 提供，分为三个范围：
  • org/global
    ——适用于该组织中的所有内容；
  • org/<integrationName>
    ——适用于与该 integration 有关的所有内容；
  • org/<integrationName>/<actionId>
    ——适用于那一个 action。
从 action 获取 
integrationName
（使用 run 的 
actionId
对 
actions
执行 
api_read
）。调用 
skills_list
，然后对 run 范围内三个作用域中每一个存在的说明调用 
skills_read
。这些说明是叠加关系，而不是相互覆盖：action-level 文本默认你已经阅读了 integration-level 文本。
确定涉及的 action 后，在告诉用户该怎么做之前阅读这些说明。它们可能包含让显而易见的建议变得错误的内部约定，而且经常能把 error message 直接映射到原因和修复方法。当它们提供了特定措辞、链接格式或修复负责人时，应采用它们的内容。
如果服务器没有 
skills_list
工具，或者在 
org/
下没有列出任何内容，就表示不存在这类说明；直接继续即可。

Running an action

运行 action

Running acts on connected systems — it creates and updates records in the customer's CRM or ERP — so only do it when the user asks, and read references/run.md before the first 
api_write
on 
action-runs
.
运行 action 会操作已连接的系统——在客户的 CRM 或 ERP 中创建和更新 records——因此只有在用户明确要求时才能执行，并且在对 
action-runs
进行第一次 
api_write
前，必须阅读 references/run.md。

Adding or changing an action column

添加或修改 action column

That is a change to the table, not to the action: the tables skill, its column reference. The catalogue here tells you which 
actionId
to use and, through the action's 
description
, what input it expects.
这是对 table 的修改，而不是对 action 的修改：应使用 tables skill 及其 column reference。本目录说明应使用哪个 
actionId
，并通过 action 的 
description
说明它需要什么 input。

Reporting back

反馈结果

Lead with the cause in the user's terms, then what to do about it and who does it. Quote 
metadata.error.message
verbatim when the fix involves a third party — a paraphrased vendor error is worse than useless when the user takes it to that vendor's support. Name the row by 
objectName
, not by id. Don't dump 
input
or 
result
.
先用用户能够理解的说法直接说明原因，然后说明该做什么以及由谁处理。当修复涉及第三方时，逐字引用 
metadata.error.message
——当用户将改写后的 vendor error 带给 vendor support 时，这种转述不仅没用，反而更糟。用 
objectName
称呼该行，而不是使用 id。不要倾倒 
input
或 
result
。