关于 lattice-rest-integration
用于构建 Lattice REST 集成的轻语言技能，帮助开发者判断何时选择 REST，并使用现有语言和文档中的 API，同时验证 Sandbox 中的实际行为。
主要功能
- 01提供 REST 选型指导
- 02使用现有语言或有文档的 REST SDK
- 03涵盖 Entities、Tasks 和 Objects API
- 04核对准确字段、枚举值和 URL 路径
- 05在 Sandbox 中验证集成
适用场景
- 01构建基于 HTTP 和 JSON 的 Sandbox 集成
- 02发布实体并回读验证
- 03创建并验证任务工作流
- 04上传对象并检查实体附件
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/lattice-rest-integration确认已加载。
详细介绍
构建 REST Lattice 集成
当协议选择为 REST 时，使用此技能。本指南刻意淡化语言要求：尽可能沿用用户选择的语言，有该语言的官方 REST SDK 时就使用它，否则直接调用 HTTP API。
何时选择 REST
用户希望实现以下目标时，优先选择 REST：
- 以最快速度完成沙盒集成，
- 使用 HTTP 和 JSON，而不是生成的 protobuf 存根，
- 使用
curl、Postman 或简单脚本进行手动测试， - 进行低频轮询或请求/响应式工作流，
- 或使用 Objects API。
如果集成必须上传、下载或附加文件，请明确指出 Objects 仅提供 REST 接口，并直接选择 REST，或提出 REST + gRPC 混合架构。
工作流
-
选择语言，然后避免不必要的干预。
- 使用代码库现有的语言，或用户指定的语言。
- 如果该语言有文档完善的 REST SDK，优先使用。
- 如果没有，就直接通过 HTTP 调用 OpenAPI 接口，不要强行更换语言。
-
通过 Sandbox 进行身份验证。 使用 ../lattice-sdk-integration/references/auth-and-deployment.md。
- 从环境变量中读取凭据（首选），或从集成程序加载的
.env/config.yml中读取。 - 默认身份验证方式为 环境令牌（
ENVIRONMENT_TOKEN，长期有效的 bearer 令牌）；用户提出要求时，支持 OAuth 客户端凭据。 - Sandbox 请求必须始终包含 Sandbox 授权令牌。
- 如果缺少凭据，请询问用户，不要编造。
- 从环境变量中读取凭据（首选），或从集成程序加载的
-
针对确切的 REST 接口进行开发。 从正确的来源获取确切值：从已安装的 SDK 中获取字段名称和枚举字面值（检查 SDK；若未安装，先安装——使用导入探测，不要搜索文件系统）；从 REST OpenAPI 规范 中获取 REST URL 路径。SDK 中不包含路径——生成的客户端会通过方法封装路径，因此请获取规范。
- Entities：发布、获取、轮询或流式传输，以及覆盖操作均通过 Entities API。
- Tasks：通过 Tasks API 创建、获取、更新状态、取消、查询和流式传输。
- Objects：通过 Objects API 上传、获取、列出对象及其元数据。
-
完整映射源数据。 使用 ../lattice-sdk-integration/references/entity-fields.md。
- 发布前，盘点所有源字段。
- 为源数据确实提供了信息的每个字段赋值。
- 不要为了满足清单要求而编造值。
-
精确对待确切值。 使用 ../lattice-sdk-integration/references/enums.md。
- 不要猜测枚举字面值、字段名称或任务规范 URL。
- 检查已安装的 SDK，确认确切的枚举字面值和字段名称（先安装最新版本；使用导入探测检测，不要搜索文件系统）；枚举快照仅供参考，可能并非最新版本。对于 REST URL 路径，请获取 REST OpenAPI 规范——SDK 中不包含这些路径。
-
在 Sandbox 中进行实时验证。
- 发布或执行真实集成。
- 在单独的验证步骤中重新读取实体、任务或对象。
- 不要只做语法检查或查看本地日志就停止。
语言指南
保持精简实用：
- 如果代码库已有语言和构建系统，就沿用它们。
- 如果用户指定了语言，就使用该语言，除非这种组合确实不受支持。
- 如果用户尚未决定，优先选择有官方文档的 REST SDK 语言，而不是从头编写原始 HTTP 实现。
除非用户明确要求，否则不要进行冗长的语言比较。
REST 专项指南
实体
- 通过 Entities REST 接口发布，并通过单独的回读进行验证。
- 将操作完整性和服务器接收情况视为同等重要。
- 对实时实体使用稳定的
entity_id，并采用心跳或重新发布策略。
任务
- 使用精确的任务类型和任务 URL。
- 对于可执行任务的 Agent，公布正确的任务规范 URL，并确认已分派的任务到达终止状态。
- 即使实现语言与示例不同，也要遵循 ../lattice-sdk-integration/references/task-lifecycle.md 中的任务生命周期规则。
对象
使用 ../lattice-sdk-integration/references/objects-api.md。
- 对象是通过路径寻址的 Blob。
- 仅上传并不足够；请通过回读对象或元数据进行验证。
- 如果将媒体附加到实体，请同时验证对象往返和实体引用。
硬性规则
- 不要自动将“REST”等同于“Python”。
- 不要将本地封装返回的 200 级响应视为完成的标准。
- 不要在此插件中使用生产部署指南。
- 不要省略后验证说明，解释集成使用了哪些 Lattice API。