commet

Commet 集成

将已安装的 SDK 视为契约。本技能用于安排工作流程；不包含 API 接口的副本。

确认已安装的上下文

更改集成前：

1. 检查依赖清单和锁文件，查找所有 Commet SDK、集成包、CLI、直接 REST 调用，以及明确指定的 API 或 webhook 版本。
2. 确认目标应用实际导入的包。如果安装了多个版本，不要假设正在使用最新版本。
3. 从已安装的构件中解析 docs/manifest.json，读取清单中指定的入口文件，然后只阅读清单列出的相关生成参考文档和 Platform 文档。
4. 如果任务依赖精确的请求、响应、错误或 webhook 结构，请从同一已安装构件中读取生成的类型定义。
5. 如果已安装的构件不含文档，请停止并报告确切的包名和版本。不要擅自用当前在线文档替代较旧的已安装契约。

使用包管理器定位构件，而不是从源码检出目录中查找：

生态系统	已安装的文档
Node	node_modules/@commet/node/docs/ 以及已安装集成包的 README
Python	定位已安装的 commet 模块，然后使用其 docs/ 目录
Go	从 go.mod 中读取 Commet 模块路径，使用 go list -m -f '{{.Dir}}' 定位，然后使用 docs/
Java	定位 co.commet:commet-java 依赖，并从其 JAR 资源中读取 commet/docs/
PHP	vendor/commet/commet-php/docs/

对于未安装 SDK 的新集成，如果用户要求实现，请先安装所需语言的包。然后再阅读该已安装包中的文档，之后才能编写集成代码。

使用 Node 诊断工具

如果存在 commet CLI 可执行文件，请从项目根目录运行：

commet doctor --output agent

即使命令以非零状态退出，也要解析 JSON。使用其中的 status、apiVersion、检查项的 code、evidence、impact 和 action；切勿检查或输出机密值。在依赖集成之前，先解决包、文档、兼容性、API 版本或项目上下文检查失败的问题。

如果已安装 Node 包，但没有 CLI，请报告诊断工具证据不可用，并继续查阅已安装包的文档。不要隐式安装或执行任何包。用户要求添加 CLI 时，请先根据已安装的文档确定兼容的安装方式。

不要仅因 doctor 报告规则过时就运行 commet agents setup。该命令会写入仓库，必须获得用户明确请求。

实现

1. 梳理现有集成，并保留其语言、框架、客户身份、API 版本和幂等性边界。
2. 仅使用已安装清单、生成参考文档和类型定义中存在的操作与字段。
3. 对授权决策，优先直接查询订阅和功能访问权限。webhook 用于异步工作，不要将其用作复制的计费事实来源。
4. 保留调用方拥有的逻辑事件标识符，以及已安装文档要求的显式幂等键。
5. 按照已安装契约处理错误，并准确保留服务器请求 ID，以便支持团队关联查询。
6. 根据更改范围运行仓库的格式化工具、类型检查或编译、测试，以及有针对性的集成检查。

防护措施

检查代码库、编辑代码、构建和本地测试均不需要远程组织上下文。任何创建、更新、删除、推送、迁移、转发或测试 Commet 资源的操作都需要远程组织上下文。

执行远程操作前：

1. 指明确切的组织，以及它是 sandbox 还是 live。
2. 在支持 doctor 的 Node 项目中，要求 PROJECT_CONTEXT_VALID 检查通过，并使用其证据。
3. 否则，必须从明确的项目配置或用户处获取组织和模式；绝不能根据 API 密钥前缀推断模式。
4. 执行前说明目标。除非用户的请求明确授权，否则不要执行会影响 live 的写入操作。
5. 如有文档说明的 dry run 或 sandbox 验证方式，优先使用。不要臆造已安装文档未说明的标志或远程行为。

绝不要在输出、补丁、日志或测试中暴露 API 密钥、Webhook 密钥、授权令牌或完整环境变量值。