pipefy-html-interfaces

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTML interfaces

HTML 界面

MCP clients: read references/mcp.md. CLI users: read references/cli.md.

An HTML interface is a page whose single element is a

customCode

element holding one HTML document. The element can declare data sources (pipes or tables) that the HTML reads by source id. Writing the HTML publishes it: there is no draft.

MCP 客户端：阅读 references/mcp.md。CLI 用户：阅读 references/cli.md。

HTML 界面是一个页面，其唯一元素是

customCode

元素，该元素包含一个 HTML 文档。该元素可以声明数据源（Pipe 或 table），HTML 会按 source id 读取这些数据源。写入 HTML 即会发布：不存在草稿。

When to use

何时使用

"Build a page that shows our open requests", "make a dashboard page from this pipe."
"Change the layout / copy / colors of my HTML interface."
"Add the table X as a data source to my page."
"List my HTML interfaces", "show me the HTML of page Y."

If the user asks for a "page" and it is unclear whether they mean a standalone HTML page or a page inside their main portal, ask before doing anything.

When not to use: the main portal, its grid-layout pages and elements, and sub-portals live in

pipefy-portal-setup

(

list_portals

and

get_portal

cover those, and

get_interface_html

refuses them). Pipes, fields, and cards themselves live in

pipefy-pipes-and-cards

. Never change an HTML interface with the portal page or element tools: they accept its

customCode

element, but they replace its metadata and sources without the checks the tools here make.

"构建一个展示未结请求的页面"、"根据这个 Pipe 制作一个仪表盘页面。"
"更改我的 HTML 界面的布局、文案或颜色。"
"将 table X 添加为页面的数据源。"
"列出我的 HTML 界面"、"显示页面 Y 的 HTML。"

如果用户要求创建"页面"，但不清楚其指的是独立 HTML 页面还是主门户中的页面，请先询问，再执行任何操作。

何时不应使用： 主门户、其网格布局页面和元素以及子门户由

pipefy-portal-setup

处理（

list_portals

和

get_portal

涵盖这些内容，而

get_interface_html

会拒绝处理它们）。Pipe、字段和 Card 本身由

pipefy-pipes-and-cards

处理。绝不要使用门户页面或元素工具修改 HTML 界面：这些工具虽然接受其

customCode

元素，却会在不执行此处工具所做检查的情况下替换其 metadata 和 sources。

Prerequisites

前置条件

HTML interfaces enabled on the organization. Pipefy enables them per organization; organization admins cannot turn them on. If a call fails because the feature is not enabled, stop and tell the user to ask Pipefy to enable HTML interfaces for their organization. No tool can enable them.
Organization id.
```
list_interface_repos
```
accepts only the numeric organization id;
```
create_html_interface
```
and
```
list_interfaces
```
accept the numeric id or the uuid. Users usually give the uuid or the name, so look up the numeric id with
```
list_organizations
```
(its
```
id
```
) and use it everywhere.
Admin access to the pipes and tables the page shows.
```
list_interface_repos
```
lists only published pipes and tables the caller administers.

组织已启用 HTML interfaces。 Pipefy 按组织启用该功能；组织管理员无法自行开启。如果某个调用因未启用该功能而失败，请停止操作，并告知用户让 Pipefy 为其组织启用 HTML interfaces。没有任何工具可以启用它。
组织 id。
```
list_interface_repos
```
只接受数字组织 id；
```
create_html_interface
```
和
```
list_interfaces
```
接受数字 id 或 uuid。用户通常会提供 uuid 或名称，因此请使用
```
list_organizations
```
（其
```
id
```
）查找数字 id，并在所有位置使用该 id。
对页面所展示的 Pipe 和 table 具有管理员访问权限。
```
list_interface_repos
```
仅列出调用者管理的已发布 Pipe 和 table。

Operations

操作

Operation	Read-only	Purpose
`get_interface_html_guidelines`	Yes	The rules the HTML must follow, the `data-pfy-*` vocabulary for binding data, and the filter format; with `include_design_system` , also a design-system catalog.
`list_interface_repos`	Yes	Pipes and tables that can be a data source.
`get_interface_repo_fields`	Yes	A pipe's or table's custom fields, to pick a source's `fieldKeys` .
`list_interfaces`	Yes	The organization's HTML interfaces, with their `visibility` .
`get_interface_html`	Yes	One interface's pages, elements, data sources, and live HTML.
`create_html_interface`	No	Create an interface and write its first page, with optional sources.
`set_interface_sources`	No	Replace an element's data sources.
`write_interface_html`	No	Replace and publish an element's HTML.

操作	只读	用途
`get_interface_html_guidelines`	是	HTML 必须遵循的规则、用于绑定数据的 `data-pfy-*` 词汇表以及筛选器格式；设置 `include_design_system` 时还会返回设计系统目录。
`list_interface_repos`	是	可作为数据源的 Pipe 和 table。
`get_interface_repo_fields`	是	Pipe 或 table 的自定义字段，用于选择数据源的 `fieldKeys` 。
`list_interfaces`	是	组织的 HTML 界面及其 `visibility` 。
`get_interface_html`	是	一个界面的页面、元素、数据源和实时 HTML。
`create_html_interface`	否	创建界面并写入其第一个页面，可选择添加数据源。
`set_interface_sources`	否	替换元素的数据源。
`write_interface_html`	否	替换并发布元素的 HTML。

Rules that hold in every flow

适用于所有流程的规则

Read the guidelines first. Call
```
get_interface_html_guidelines
```
before writing any HTML, and follow it. This skill does not repeat the rules: the guidelines are their single source, and they change with the platform. By default it leaves out
```
designSystem
```
, a component catalog several times the size of the rules. Ask for it with
```
include_design_system
```
only when styling the page.
Bind data exactly as
dataPfyVocabulary
says. It says what each
```
data-pfy-*
```
attribute does, for most which element it goes on, and the value it takes. The validator only checks that an attribute is allowed, so it accepts a binding in the wrong place.
Every write is live.
```
create_html_interface
```
,
```
write_interface_html
```
, and
```
set_interface_sources
```
change what visitors see at once. A specific request from the user ("rename the heading to X") is approval for that change. Before anything beyond it, such as rewriting markup they did not mention or removing a source they still use, show the user the change and get their approval.
Keep the live page reading only declared sources. HTML that reads a source id the element does not declare renders blank, with no error. Add a source before writing the HTML that reads it. Remove or rename a source only after the live HTML no longer reads it.
Fix every violation before writing again. A rejected write stores nothing and lists every violation. Fix all of them in one pass, then write again. If the HTML came from the user, show them the violations and a version that follows the rules, and publish only once they agree.

先阅读指南。 编写任何 HTML 前都要调用
```
get_interface_html_guidelines
```
并遵循其要求。本 skill 不重复这些规则：指南是唯一依据，且会随平台变化。默认情况下，指南不包含
```
designSystem
```
——这是一个比规则大数倍的组件目录。仅在需要为页面设置样式时，才使用
```
include_design_system
```
获取它。
严格按照
dataPfyVocabulary
绑定数据。它会说明每个
```
data-pfy-*
```
属性的作用、适用于哪些元素以及要采用的取值。验证器只检查属性是否在允许列表中，因此即使绑定位置错误也会通过检查。
每次写入都会立即生效。
```
create_html_interface
```
、
```
write_interface_html
```
和
```
set_interface_sources
```
会立即改变访客看到的内容。用户提出的具体请求（"将标题重命名为 X"）即构成对该更改的授权。对于超出该范围的任何操作，例如重写用户未提及的标记，或删除仍在使用的数据源，请向用户展示更改并取得其批准。
确保实时页面只读取已声明的数据源。 如果 HTML 读取了元素未声明的 source id，页面会呈现空白且不会报错。在写入读取该 id 的 HTML 前，先添加数据源。只有在实时 HTML 不再读取某个数据源后，才能删除或重命名它。
再次写入前修复所有违规项。 被拒绝的写入不会存储任何内容，并会列出每项违规。一次性修复全部问题，然后再次写入。如果 HTML 来自用户，请向他们展示违规项以及符合规则的版本，只有在他们同意后才发布。

Steps — create a page

步骤——创建页面

Read the rules, and the design-system catalog if you will style the page:

text

get_interface_html_guidelines
get_interface_html_guidelines include_design_system=true

Check the name is free. If an interface with that name exists, ask the user whether to change it (see the next section) or create another.
text
```
list_interfaces organization_uuid=<org_id> search_term=<name>
```
Pick the data (skip for a page without live data). List candidate repos, then the fields of each one you use:
text
```
list_interface_repos organization_id=<org_id> repo_name=<name_fragment>
get_interface_repo_fields repo_uuid=<repo_uuid>
```
A source is
```
{"id", "name", "repoId", "fieldKeys", "filters"}
```
.
```
repoId
```
is the repo's
```
uuid
```
.
```
fieldKeys
```
holds 1 to 30 keys: a custom field's
```
uuid
```
(not its
```
id
```
), or a built-in key such as
```
title
```
(the guidelines list built-in keys under
```
filters.fixedColumnNames
```
).
```
filters
```
is optional and follows the guidelines' filter format.
```
id
```
and
```
name
```
are unique within the element; the HTML reads the source by
```
id
```
. An element holds at most 10 sources.
Write the HTML against the guidelines, binding each source by its
```
id
```
with the
```
dataPfyVocabulary
```
attributes.

Create the interface with its sources and HTML in one call:

text

create_html_interface organization_uuid=<org_id> name="Open requests" html=<document> data_sources=[{"id": "requests", "name": "Open requests", "repoId": <repo_uuid>, "fieldKeys": ["title", <field_uuid>]}]

The result carries the new interface's

uuid

and its page and element ids. Tell the user the interface's name and

uuid

阅读规则；如果将对页面设置样式，还要阅读设计系统目录：

text

get_interface_html_guidelines
get_interface_html_guidelines include_design_system=true

检查名称是否可用。 如果已有同名界面，请询问用户是更改现有界面（见下一节）还是另建一个。
text
```
list_interfaces organization_uuid=<org_id> search_term=<name>
```
选择数据（不包含实时数据的页面可跳过）。先列出候选 repo，再列出所使用的每个 repo 的字段：
text
```
list_interface_repos organization_id=<org_id> repo_name=<name_fragment>
get_interface_repo_fields repo_uuid=<repo_uuid>
```
数据源的结构为
```
{"id", "name", "repoId", "fieldKeys", "filters"}
```
。
```
repoId
```
是 repo 的
```
uuid
```
。
```
fieldKeys
```
包含 1 到 30 个键：自定义字段的
```
uuid
```
（不是其
```
id
```
），或内置键，例如
```
title
```
（指南在
```
filters.fixedColumnNames
```
下列出内置键）。
```
filters
```
是可选的，并遵循指南中的筛选器格式。
```
id
```
和
```
name
```
在元素内必须唯一；HTML 按
```
id
```
读取数据源。一个元素最多包含 10 个数据源。
根据指南编写 HTML，使用
```
dataPfyVocabulary
```
属性按
```
id
```
绑定每个数据源。

创建界面，在一次调用中传入数据源和 HTML：

text

create_html_interface organization_uuid=<org_id> name="Open requests" html=<document> data_sources=[{"id": "requests", "name": "Open requests", "repoId": <repo_uuid>, "fieldKeys": ["title", <field_uuid>]}]

结果会返回新界面的

uuid

以及其页面和元素 id。请告知用户界面的名称和

uuid

。

Steps — change an existing page

步骤——更改现有页面

Find it and read it:

text

list_interfaces organization_uuid=<org_id> search_term=<name_fragment>
get_interface_html interface_uuid=<interface_uuid>

Use the element whose

type

customCode

on the page the user means. If the interface has more than one page or

customCode

element, list them and ask which one. Take

page_id

from

pages[].uuid

element_id

from

pages[].elements[].uuid

, the current sources from the element's

dataSources

, and note its

htmlDocument.contentHash

Add sources if the new HTML needs more data. For a field the page does not read yet, find its uuid with
```
get_interface_repo_fields
```
on the source's
```
repoId
```
. Send the complete list, the current sources plus the new ones: it replaces the element's sources, and
```
[]
```
removes them all. Sources read with
```
get_interface_html
```
can be sent back as read. Keep the
```
id
```
of every source you keep.
text
```
set_interface_sources interface_uuid=<interface_uuid> page_id=<page_id> element_id=<element_id> data_sources=[...]
```
Write the new HTML, starting from the document you read. Right before writing, read the interface again: if
```
contentHash
```
changed, someone else edited the page, so start again from the new document and show the user the change.
text
```
write_interface_html page_id=<page_id> element_id=<element_id> content=<document>
```
Remove or rename sources the new HTML no longer reads, if the user wants them gone, with one more
```
set_interface_sources
```
call that sends the complete list.

查找并读取它：

text

list_interfaces organization_uuid=<org_id> search_term=<name_fragment>
get_interface_html interface_uuid=<interface_uuid>

使用用户所指页面中

type

为

customCode

的元素。如果界面有多个页面或

customCode

元素，请将它们列出并询问用户是哪一个。从

pages[].uuid

获取

page_id

，从

pages[].elements[].uuid

获取

element_id

，从该元素的

dataSources

获取当前数据源，并记下其

htmlDocument.contentHash

。

如果新 HTML 需要更多数据，则添加数据源。 对于页面尚未读取的字段，使用
```
get_interface_repo_fields
```
并传入该数据源的
```
repoId
```
，查找其 uuid。发送完整列表，即当前数据源加新数据源：该调用会替换元素的数据源，而
```
[]
```
会移除全部数据源。通过
```
get_interface_html
```
读取的数据源可以按原样发回。保留每个保留数据源的
```
id
```
。
text
```
set_interface_sources interface_uuid=<interface_uuid> page_id=<page_id> element_id=<element_id> data_sources=[...]
```
写入新的 HTML，以读取到的文档为起点。写入前请再次读取界面：如果
```
contentHash
```
已变化，说明其他人编辑了该页面，请从新文档重新开始，并向用户展示该更改。
text
```
write_interface_html page_id=<page_id> element_id=<element_id> content=<document>
```
如果用户希望移除或重命名新 HTML 不再读取的数据源，请再进行一次
```
set_interface_sources
```
调用，并发送完整列表。

Success criteria

成功标准

The create or write returns success, with no violations.
```
get_interface_html
```
shows the new document and the expected
```
dataSources
```
on the element.
Every source id the HTML reads is in the element's
```
dataSources
```
.

创建或写入操作返回成功，且没有任何违规项。
```
get_interface_html
```
显示新文档以及元素上预期的
```
dataSources
```
。
HTML 读取的每个 source id 都包含在元素的
```
dataSources
```
中。

Failure modes

失败模式

The create succeeded but the write failed. The interface exists with a blank page, and the error gives its
```
uuid
```
,
```
page_id
```
, and
```
element_id
```
. Resolve the error (fix the HTML for a rejection), then call
```
write_interface_html
```
with those ids. Do not call
```
create_html_interface
```
again: it would create a second, orphaned interface.
The create returned no page to write into. The interface may exist anyway, and the error gives its
```
uuid
```
. Check it with
```
get_interface_html
```
before doing anything else, and never retry the create blindly.
The create failed and the error has no
uuid
. The interface may exist anyway. Search for it with
```
list_interfaces
```
by name before any retry, and create again only if no new interface with that name appears.
The HTML was rejected on a write. Nothing was stored. Fix every listed violation against the guidelines and write again.
A write failed without listing violations. Read the page with
```
get_interface_html
```
to see what is stored, then write again once. If it fails again, stop and tell the user.
The page renders blank sections. The HTML reads a source id that the element does not declare, or one that was renamed or removed. Compare the HTML with
```
dataSources
```
from
```
get_interface_html
```
, then fix the sources or the HTML.
A duplicate interface exists. Show the user both, with names and uuids. With their approval, delete the extra one with
```
delete_portal
```
, which takes the interface's uuid as
```
portal_uuid
```
and asks for confirmation.
A repo is missing from
list_interface_repos
. It is unpublished, or the caller is not its admin. An empty list can also mean the organization id is wrong: the listing does not report an unknown organization or interface.
get_interface_html
refuses the interface. It is a grid-layout portal or sub-portal; use
```
pipefy-portal-setup
```
.
Unsure what a source update stored.
```
set_interface_sources
```
returns the sources as sent, not as stored. Read them back with
```
get_interface_html
```
.

创建成功但写入失败。 界面已存在且页面为空白，错误中会提供其
```
uuid
```
、
```
page_id
```
和
```
element_id
```
。解决错误（若因 HTML 被拒绝，则修复 HTML），然后使用这些 id 调用
```
write_interface_html
```
。不要再次调用
```
create_html_interface
```
：那会创建第二个孤立界面。
创建后没有可写入的页面。 界面仍可能已经存在，错误中会提供其
```
uuid
```
。先用
```
get_interface_html
```
检查，然后再执行任何操作；绝不要盲目重试创建。
创建失败且错误中没有
uuid
。界面仍可能已经存在。重试前，先按名称使用
```
list_interfaces
```
搜索；只有未出现新的同名界面时，才再次创建。
写入时 HTML 被拒绝。 不会存储任何内容。根据指南修复列出的每项违规，然后再次写入。
写入失败但未列出违规项。 使用
```
get_interface_html
```
读取页面以查看已存储的内容，然后再次写入一次。如果再次失败，请停止操作并告知用户。
页面的部分区域呈现空白。 HTML 读取了元素未声明的数据源 id，或者该 id 已被重命名或移除。将 HTML 与
```
get_interface_html
```
返回的
```
dataSources
```
进行比较，然后修复数据源或 HTML。
存在重复界面。 向用户展示两者及其名称和 uuid。获得用户批准后，使用
```
delete_portal
```
删除多余界面；该工具将界面的 uuid 作为
```
portal_uuid
```
，并要求确认。
list_interface_repos
中缺少某个 repo。它可能尚未发布，或者调用者不是其管理员。空列表也可能意味着组织 id 错误：该列表不会报告未知组织或未知界面。
get_interface_html
拒绝处理该界面。它是网格布局门户或子门户；请使用
```
pipefy-portal-setup
```
。
不确定数据源更新存储了什么。
```
set_interface_sources
```
返回的是发送的数据源，而非实际存储的数据源。使用
```
get_interface_html
```
读回确认。

另请参阅

```
pipefy-portal-setup
```
: the main portal, its grid-layout pages and elements, and sub-portals.
```
pipefy-pipes-and-cards
```
: create the pipes and fields a page reads.

```
pipefy-portal-setup
```
：主门户、其网格布局页面和元素，以及子门户。
```
pipefy-pipes-and-cards
```
：创建页面读取的 Pipe 和字段。

pipefy-html-interfaces

Original

Translation

HTML interfaces

HTML 界面

When to use

何时使用

Prerequisites

前置条件

Operations

操作

Rules that hold in every flow

适用于所有流程的规则

Steps — create a page

步骤——创建页面

Steps — change an existing page

步骤——更改现有页面

Success criteria

成功标准

Failure modes

失败模式

See also

另请参阅