pipefy-html-interfaces

HTML 界面

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

HTML 界面是一个页面，其中唯一的元素是一个 customCode 元素，内含一份 HTML 文档。该元素可以声明数据源（管道或表格），供 HTML 按来源 ID 读取。写入 HTML 即会发布：没有草稿。

适用场景

• “构建一个显示我们未处理请求的页面”“用这个管道创建一个仪表板页面。”
• “更改我的 HTML 界面的布局／文案／颜色。”
• “将表格 X 添加为我页面的数据源。”
• “列出我的 HTML 界面”“显示页面 Y 的 HTML。”

如果用户提到“页面”，但不清楚他们指的是独立 HTML 页面还是主门户中的页面，请先询问再采取任何操作。

**不适用场景：**主门户、其中采用网格布局的页面和元素，以及子门户都由 pipefy-portal-setup 管理（list_portals 和 get_portal 可处理这些内容，而 get_interface_html 会拒绝处理）。管道、字段和卡片本身由 pipefy-pipes-and-cards 管理。切勿使用门户页面或元素工具更改 HTML 界面：这些工具虽然接受其 customCode 元素，但会替换其元数据和数据源，且不会执行此处工具所做的检查。

前提条件

• 组织已启用 HTML 界面。 Pipefy 按组织启用此功能；组织管理员无法自行启用。如果调用因未启用此功能而失败，请停止操作，并告知用户联系 Pipefy 为其组织启用 HTML 界面。没有任何工具可以启用此功能。
• 组织 ID。 list_interface_repos 仅接受数字组织 ID；create_html_interface 和 list_interfaces 接受数字 ID 或 UUID。用户通常会提供 UUID 或名称，因此请使用 list_organizations 查询数字 ID（其 id 字段），并在所有地方使用该 ID。
• 对页面所显示的管道和表格具有管理员访问权限。 list_interface_repos 仅列出调用者有权管理的已发布管道和表格。

操作

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

适用于所有流程的规则

• 先阅读指南。 编写任何 HTML 前，先调用 get_interface_html_guidelines，并遵循指南。本技能不会重复这些规则：指南是规则的唯一来源，且会随平台变化。默认情况下，指南会省略 designSystem，因为组件目录的篇幅是规则的数倍。只有在为页面设置样式时，才通过 include_design_system 请求它。
• 严格按照 dataPfyVocabulary 绑定数据。 它说明了每个 data-pfy-* 属性的作用、大多数属性应放在哪个元素上，以及属性应采用什么值。验证器只检查属性是否获准，因此即使绑定位置错误也会通过。
• 每次写入都会立即生效。 create_html_interface、write_interface_html 和 set_interface_sources 会立即更改访客看到的内容。用户的具体请求（例如“将标题重命名为 X”）即表示用户批准了该更改。在进行超出请求范围的操作之前，例如重写用户未提及的标记，或移除用户仍在使用的数据源，请先向用户展示更改并取得批准。
• 确保线上页面只读取已声明的数据源。 如果 HTML 读取了元素未声明的数据源 ID，页面会空白显示，且不会报错。先添加数据源，再编写读取它的 HTML。只有在线 HTML 不再读取某个数据源后，才能移除或重命名该数据源。
• 再次写入前，修复所有违规项。 被拒绝的写入不会保存任何内容，并会列出所有违规项。一次性修复全部问题，再重新写入。如果 HTML 来自用户，请向用户展示违规项以及符合规则的版本，并且仅在用户同意后发布。

步骤——创建页面

1. 阅读规则；如果要为页面设置样式，也要阅读设计系统目录：

   get_interface_html_guidelines
   get_interface_html_guidelines include_design_system=true
   

2. 检查名称是否可用。 如果已存在同名界面，请询问用户是要更改它（见下一节）还是创建另一个界面。

   list_interfaces organization_uuid=<org_id> search_term=<name>
   

3. 选择数据（无实时数据的页面可跳过此步）。列出候选 repo，然后列出每个所用 repo 的字段：

   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 个数据源。

4. 编写 HTML，遵循指南，并使用 dataPfyVocabulary 属性，通过各数据源的 id 进行绑定。

5. 在一次调用中创建界面，同时传入其数据源和 HTML：

   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。

步骤 — 更改现有页面

1. 查找并阅读：

   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。

2. 如果新 HTML 需要更多数据，添加数据源。对于页面尚未读取的字段，使用该数据源的 repoId 调用 get_interface_repo_fields 查找其 uuid。发送完整列表，即当前数据源加上新增数据源：这会替换元素的数据源；发送 [] 则会移除全部数据源。通过 get_interface_html 读取的数据源可以原样发送回去。保留所有要继续使用的数据源的 id。

   set_interface_sources interface_uuid=<interface_uuid> page_id=<page_id> element_id=<element_id> data_sources=[...]
   

3. 编写新 HTML，以读取到的文档为基础。写入前，重新读取界面：如果 contentHash 已更改，说明有人编辑了页面，请基于新文档重新开始，并向用户展示更改。

   write_interface_html page_id=<page_id> element_id=<element_id> content=<document>
   

4. 如果用户希望移除不再被新 HTML 读取的数据源，或为其重命名，请再调用一次 set_interface_sources 并发送完整列表。

成功标准

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

失败情况

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

另请参阅

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