Back to Details

prismatic-components

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Prismatic components

Prismatic 组件

A custom connector is a Spectral TypeScript component whose connections, actions, and triggers appear in Prismatic's low-code designer.
Start from the user's request and the current project. Before implementing the change, record concrete acceptance cases: inputs, relevant prior state, and expected outcomes derived from the user workflow and authoritative contract. Use these expectations in tests or registered-metadata checks; do not derive expected results from the implementation. Extend an existing component when present, preserving existing keys and behavior outside the requested change; otherwise scaffold with 
prism components init <name>
. Use 
prism --llms
and command 
--help
or 
--schema
to discover capabilities and options, including OpenAPI generation. Prefer Prism's commands and generated toolchain over custom scaffolding or publishing scripts. Treat generated code as a starting point: keep actions that serve the requested workflow, remove unrelated generated actions and unused supporting code, and shape labels, inputs, and outputs around the builder's task. Do not retain the whole API merely because it was generated. When editing, preserve existing integration contracts unless the user requests their removal.
Use the supplied specification for the requested API version as the service contract, filling gaps from official documentation. When a supported official SDK already implements a multi-step service protocol, prefer its operation over reimplementing that protocol, unless it cannot meet the requested behavior or project constraints. Verify the relevant SDK version and keep its request-building under test. Check generated authentication and parameter serialization against it; defaults and other connectors' examples may target a different API. Verify claims about unsupported capabilities against official sources. Use 
prism components search
and 
prism components get
to find existing connectors and the designer-facing shape of comparable actions, triggers, and connections. Use Prismatic's connector docs and production components for SDK conventions and relevant examples. An existing connector can inform a custom implementation without replacing the user's request. When documentation does not cover a capability, inspect the installed Spectral types and relevant SDK source rather than guessing its contract.
Infer technical choices from the documentation and project. Ask only about missing business requirements that change the result, in terms the user can answer. Continue independent work while those details are unresolved.
Expose credentials through Spectral connections, and operations through labeled inputs and outputs usable in the designer. Implement the requested trigger using the service's supported event or polling mechanism, including setup and state needed across executions. Verify endpoints and payload fields against service docs or SDK source; if a mechanism cannot be verified, use a supported alternative. For trigger work, read Trigger contracts. Lifecycle callbacks differ from normal executions; SDK types alone may not express which state is available at runtime.
For a requested designer interaction, verify the registered structure and behavior that provides it; descriptive labels or the outgoing API shape do not establish that interaction. Before publication or handoff, check each acceptance case against an actual test or inspection result. For the requested behavior, challenge passing tests against the contract: if a plausible wrong behavior would still pass, tighten the relevant fixture or assertion and rerun it. Choose boundary cases that distinguish correct behavior from a plausible mistake:
  • Check the registered metadata and relationships that make the requested connections, inputs, actions, and triggers usable in the designer, including required/optional inputs and data-source references. For optional inputs relevant to the requested behavior, exercise registered SDK defaults as well as supplied values; explicitly passing 
    undefined
    may not represent an unset designer input. Use Prism's member-inspection commands (
    --help
    or 
    --schema
    ) to verify published configuration.
  • For behavior tests, prefer Spectral 
    testing.createHarness(component)
    and its action or trigger entrypoint so registered input cleaning, defaults, and callback wrappers remain active. Mock transport or the remote service, keeping request construction under test. For callbacks the helper does not expose, preserve the SDK/runtime context and persistence contracts. Check outgoing requests, returned data, a relevant API failure, and contract-derived boundary values, including URL-reserved characters in identifier tests where the contract permits them. For JSON inputs that permit arbitrary values, test nested non-string values. For binary file transfers, compare exact bytes (for example, 
    Buffer.from([0x00, 0xff, 0x80])
    ).
  • For stateful behavior, verify which state is available, its scope and ownership, and how changes persist against the SDK's actual contracts. Test repeated calls and recovery after failure in fresh invocations, including initialization when it differs from normal operation. When storage is shared, verify that independent owners remain separate. Mocks must not invent state unavailable to the callback.
For edits, rerun existing tests and verify the requested change while preserving unaffected behavior. Run the project's build, typecheck, and tests on the final source; resolve failures before publication or handoff. Distinguish local verification from live testing: 
prism components dev
commands can execute actions and create remote resources. Publish or test against the platform when that is within the user's requested scope. When publishing a separate component, a new key can still conflict with an existing display label. Resolve naming conflicts on the authorized new artifact and retry, preserving required user-facing names and integration contracts. Do not rename or delete other components; ask if resolving the conflict would change the intended target or scope. Publish the final verified build, rebuilding after any source changes.
Explain what the user can now do in the low-code designer, any setup still needed, and what was actually tested. Name credentials still needed and the relevant connection, trigger, and action setup; distinguish new setup from configuration the user can keep.
自定义连接器是一个 Spectral TypeScript component，其 connections、actions 和 triggers 会显示在 Prismatic 的 low-code designer 中。
从用户请求和当前项目入手。实施变更前，应根据用户 workflow 和权威契约 记录具体的验收用例：输入、相关的先前状态以及预期结果。将这些预期用于 测试或注册 metadata 检查；不要从实现中推导预期结果。若项目中已有相应的 component，则扩展现有 component，并保留现有 key 以及请求变更之外的行为； 否则，使用 
prism components init <name>
创建脚手架。 使用 
prism --llms
以及命令的 
--help
或 
--schema
选项来发现功能和选项， 其中包括 OpenAPI 生成。相较于自定义脚手架或发布脚本，应优先使用 Prism 的 命令和生成的工具链。
将生成代码视为起点：保留服务于请求 workflow 的 actions，移除无关的生成 actions 和未使用的支撑代码，并围绕 builder 的任务调整 labels、inputs 和 outputs。不要仅因为整个 API 是生成的，就将其全部保留。编辑时，除非用户 要求删除，否则保留现有集成契约。
将针对所请求 API 版本的给定 specification 作为服务契约，并用官方文档 补齐缺失内容。当受支持的官方 SDK 已经实现多步骤服务协议时，应优先使用其 operation，而不是重新实现该协议，除非它无法满足请求的行为或项目约束。 核实相关 SDK 版本，并确保 request-building 纳入测试。对照该 SDK 检查生成的 authentication 和 parameter serialization；默认值及其他连接器的示例可能面向 不同的 API。有关不支持能力的说法，应通过官方来源验证。 使用 
prism components search
和 
prism components get
查找现有连接器，以及 可比较的 actions、triggers 和 connections 面向 designer 的结构。使用 Prismatic 连接器文档和 生产级 components 了解 SDK 约定和相关示例。现有连接器可以为自定义实现提供参考，但不应取代 用户的请求。当文档未涵盖某项能力时，应检查已安装的 Spectral 类型及相关 SDK 源码，而不是猜测其契约。
根据文档和项目推断技术选择。只就那些会改变结果且用户能够回答的缺失业务 需求进行提问。在这些问题尚未解决时，继续推进可独立完成的工作。
通过 Spectral connections 暴露 credentials，并通过带标签且可供 designer 使用的 inputs 和 outputs 暴露 operations。使用服务支持的 event 或 polling 机制实现请求的 trigger，包括跨多次执行所需的 setup 和 state。根据服务文档 或 SDK 源码验证 endpoints 和 payload 字段；如果某项机制无法验证，则采用 受支持的替代方案。 对于 trigger 工作，请阅读 Trigger 契约。Lifecycle callbacks 与正常执行有所不同；仅凭 SDK 类型可能无法表达 runtime 中有哪些 state 可用。
对于请求的 designer 交互，验证提供该交互的已注册结构和行为；仅有描述性 labels 或输出 API 的结构，并不能证明存在该交互。
在发布或交付之前，针对实际测试或检查结果核对每个验收用例。对于请求的 行为，应依据契约审查通过的测试：如果一种看似合理但错误的行为仍能通过测试， 则收紧相关 fixture 或 assertion 并重新运行。选择能够区分正确行为与看似合理 之错误的边界用例：
  • 检查已注册 metadata 及其关系，这些 metadata 和关系使请求的 connections、 inputs、actions 和 triggers 可在 designer 中使用，包括必填/可选 inputs 和 data-source 引用。对于与请求行为相关的可选 inputs，既要测试已注册的 SDK 默认值，也要测试提供的值；显式传入 
    undefined
    未必表示 designer 中未设置的 input。使用 Prism 的成员检查命令（
    --help
    或 
    --schema
    ）验证已发布的 configuration。
  • 对于行为测试，优先使用 Spectral 
    testing.createHarness(component)
    及其 action 或 trigger 入口，以便已注册的 input 清理、默认值和 callback 包装器 仍然生效。Mock transport 或远程服务，同时确保 request construction 纳入 测试。对于 helper 未暴露的 callbacks，保留 SDK/runtime context 与 persistence 契约。检查发出的请求、返回数据、相关 API 失败，以及根据契约 推导出的边界值；对于契约允许的 identifier 测试，还应包括 URL 保留字符。 对于允许任意值的 JSON inputs，测试嵌套的非字符串值。对于二进制文件传输， 比较完全一致的字节（例如 
    Buffer.from([0x00, 0xff, 0x80])
    ）。
  • 对于有状态行为，验证有哪些状态可用、其作用域和所有权，以及状态变更如何 依据 SDK 的实际契约持久化。测试重复调用，以及在全新调用中失败后的恢复， 包括初始化方式不同于正常操作的情况。当存储共享时，验证彼此独立的所有者 仍保持隔离。Mock 不得虚构 callback 无法访问的状态。
对于编辑，重新运行现有测试，并在保留不受影响行为的同时验证请求的变更。 在最终源码上运行项目的 build、typecheck 和 tests；发布或交付前解决所有失败。
区分本地验证与 live testing：
prism components dev
命令可以执行 actions 并创建远程资源。当用户的请求范围包含此操作时，针对平台发布或测试。发布独立 component 时，新 key 仍可能与现有 display label 冲突。针对已获授权的新 artifact 解决命名冲突并重试，同时保留必需的用户可见名称和集成契约。不得重命名或 删除其他 components；如果解决冲突会改变预期 target 或 scope，则先询问用户。
发布最终验证通过的 build；每次源码变更后都要重新构建。
说明用户现在能在 low-code designer 中做什么、仍需完成哪些 setup，以及实际 测试了什么。明确列出仍需的 credentials，以及相关 connection、trigger 和 action 的设置；区分新 setup 与用户可以保留的 configuration。