prismatic-integrations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Build a Prismatic integration

构建 Prismatic 集成

Start from the user's request and current project. Extend the current CNI when present; otherwise scaffold one with
prism integrations:init <name>
. Use
prism --llms
and command
--help
or
--schema
to discover current capabilities. Prefer Prism's generated project and toolchain over custom scaffolding.
Research the connected services in their official documentation. Before choosing an architecture, consult Prismatic's documentation index for relevant patterns and prefer Prismatic's documented approaches when they fit the request and existing project. Use Prismatic's CNI docs, CNI examples, installed manifest documentation, and installed
@prismatic-io/spectral
public types to verify the chosen approach.
Translate the request into triggers, source and destination operations, deployer-owned configuration, expected volume, customer-specific mapping, and retry behavior. Infer technical choices from the service contracts and project. Ask only about missing business decisions that materially change the result.
Check that the chosen event represents the requested business change; filter a broader event where supported or explain the limitation. For lifecycle-managed resources, keep remote IDs tied to their issuing service/account, and check that repeated setup, changed configuration, and cleanup converge on the intended resources without affecting unrelated ones. When requests are idempotent, key or reconcile them according to the desired operation and its change semantics. Use documented provider-managed guarantees where sufficient; report cleanup limits when access is unavailable.
Prefer existing Prismatic components when they fit, but a direct authenticated client is equally valid. Expose credentials and customer-owned choices through the configuration wizard. Do not hard-code tenant IDs, resource selections, mappings, or secrets.
Design large or incremental workloads so each execution is bounded and progress is resumable. Ground pagination and checkpoint behavior in the selected API or component contract, and make retried writes idempotent or define their duplicate policy. When customer schemas vary, make object and field selection configurable and test mapping logic without live credentials.
For a reused trigger or client, verify the selected operation's contract from official documentation and the installed interface. Derive representative local checks from that contract, preserving response wrappers, wire types, and continuation data while keeping relevant request construction under test. Where event selection or persisted progress matters, check recovery after downstream failure. If an abstraction omits information the request needs, use a supported boundary that exposes it; when constructing queries, follow the provider's literal rules.
Install dependencies and run the generated project's typecheck, lint, tests, and production build when those scripts exist. After building, run
prism integrations validate
from the project directory to check that Prism can load the compiled CNI and validate its local definition before importing it. Loading executes the project module, so use it only with trusted projects. This local check does not publish the integration or run flows; platform verification still establishes remote acceptance and behavior. For lifecycle hooks or polling triggers, consult SDK registration boundaries.
Before importing a requested separate copy, read platform verification and establish fresh integration and generated component identities, including inherited publishing metadata. Preserve the flow and configuration identities needed within the copy. Omitting an import ID does not establish that the original will remain unchanged.
Carry implementation through platform verification when it is within the user's request. Use the selected development or test environment and existing authorization to import, publish versions, configure or deploy test instances, execute flows, and run smoke tests as needed. Continue ordinary repair and verification cycles without asking for permission again. Preserve explicit local-only requests; if the target, credentials, or allowed external effects are unclear, resolve that gap while continuing independent work. Authentication alone does not identify the intended target or authorize production changes.
For platform work, follow platform verification. Fix observed failures, rebuild and update the target, then repeat relevant checks until the requested behavior is demonstrated or a concrete blocker prevents further progress. Report the project path, architecture, deployer configuration, assumptions, validation evidence, and any remaining operational work.
从用户请求和当前项目开始。如果项目中已有 CNI,则对其进行扩展;否则,使用
prism integrations:init <name>
初始化一个 CNI。使用
prism --llms
以及各命令的
--help
或
--schema
了解当前能力。应优先使用 Prism 生成的项目和工具链,而非自定义脚手架。
在相关服务的官方文档中调研所连接的服务。在选择 architecture 之前,查阅 Prismatic 的文档索引 中与需求相关的模式;如果这些文档化方法适合请求和现有项目,应优先采用。使用 Prismatic 的 CNI 文档、CNI 示例、已安装的 manifest 文档以及已安装的
@prismatic-io/spectral
公共类型,验证所选方案。
将请求转化为 triggers、source 和 destination operations、deployer 负责的配置、预期数据量、客户特定 mapping 以及 retry behavior。根据服务 contracts 和项目推断技术选择。只询问那些缺失且会实质改变结果的业务决策。
确认所选 event 能够表示请求的业务变更;如果支持,应过滤范围更广的 event,否则说明限制。对于 lifecycle 管理的资源,确保 remote IDs 与签发它们的 service/account 保持关联,并检查重复 setup、配置变更和 cleanup 是否收敛到预期资源,且不会影响无关资源。当请求是幂等的,应根据目标 operation 及其 change semantics 对其进行 key 或 reconcile。在文档化的 provider 管理保证足够时,应采用这些保证;无法访问时,应报告 cleanup 限制。
如果现有 Prismatic components 适用,应优先使用;但直接使用经过身份验证的 client 同样有效。通过 configuration wizard 暴露 credentials 和客户自行决定的选项。不得硬编码 tenant IDs、resource selections、mappings 或 secrets。
对于大型或增量式 workloads,应确保每次 execution 都有明确边界,且进度可恢复。以所选 API 或 component contract 为依据设计 pagination 和 checkpoint 行为,并让重试的 writes 具备幂等性,或明确定义其 duplicate policy。当客户 schemas 存在差异时,应使 object 和 field 的选择可配置,并无需使用实时 credentials 即可测试 mapping 逻辑。
对于复用的 trigger 或 client,应根据官方文档和已安装的 interface 验证所选 operation 的 contract。依据该 contract 设计有代表性的本地检查,在测试相关 request construction 的同时,保留 response wrappers、wire types 和 continuation data。若 event selection 或持久化进度很重要,应检查 downstream failure 后的恢复情况。如果 abstraction 遗漏了请求所需的信息,应使用能够公开该信息的受支持 boundary;构造 queries 时,应严格遵循 provider 的字面规则。
安装 dependencies;如果生成的项目中存在相应脚本,则运行 typecheck、lint、tests 和 production build。构建完成后,在项目目录中运行
prism integrations validate
,检查 Prism 是否能够加载已编译的 CNI,并在导入前验证其本地 definition。加载过程会执行项目 module,因此只能对可信项目使用。此本地检查不会发布 integration,也不会运行 flows;远程 acceptance 和 behavior 仍需通过 platform verification 确认。对于 lifecycle hooks 或 polling triggers,请查阅 SDK registration boundaries。
在导入用户要求的独立副本之前,请阅读 platform verification,并建立全新的 integration 和生成 component 的 identities,包括继承的 publishing metadata。保留副本内所需的 flow 和 configuration identities。省略 import ID 并不能确保原始对象保持不变。
如果 platform verification 属于用户请求范围,应将实现一直推进到完成 platform verification。使用选定的 development 或 test environment 以及现有 authorization,按需执行 import、发布 versions、配置或部署 test instances、执行 flows 和运行 smoke tests。继续正常的修复和验证循环,无需再次请求许可。应保留明确仅限本地的请求;如果 target、credentials 或允许的外部副作用不明确,应在继续独立工作的同时消除该歧义。仅通过 authentication 并不能确定目标 environment,也不能授权 production changes。
对于 platform 工作,请遵循 platform verification。修复观察到的 failures,重新构建并更新 target,然后重复相关检查,直到证明请求的行为已实现,或出现具体 blocker 阻止进一步进展。报告 project path、architecture、deployer configuration、assumptions、validation evidence,以及任何剩余的 operational work。