使用 AI 辅助集成

本页说明如何把 NI PaaS 文档中心与机器可读契约交给 AI 编码助手（Claude Code、Cursor、Copilot 等），让助手在生成接入代码时直接引用真实的接口定义，而不是猜测字段。

与参照站的关系

栏目位置对标参照站「使用 AI 集成」，内容为本项目自有产物与流程。

可喂给 AI 的机器可读产物​

产物路径内容用途
OpenAPI 3.1/docs/assets/openapi-v1.json全部服务端 Open API 的路径、参数、响应与错误码生成 REST 客户端 / 让助手补全请求示例
Postman 集合/docs/assets/postman-collection.json按能力域分组的请求集合与前置脚本手工调试与回归
文档 Markdown每个页面 查看 Markdown / .md与 HTML 同源的正文（生成器双写）作为检索语料或直接贴进对话
SDK 公开面/docs/<platform>-imlib/api-reference/sdk-surface各端导出符号与签名约束助手只调用真实存在的 API
搜索索引/docs/search-index.json页面标题、锚点与正文摘要本地检索/自建 RAG

推荐工作流​

  1. 先定契约

    让助手只依据 openapi-v1.json 与 IDL 生成请求/响应类型，不允许自造字段；类型名以 SDK 公开面为准。

  2. 缩小上下文

    按能力域选择页面（如用户、消息、群组），用页面的 Markdown 版本作为上下文，避免把整站塞进提示词。

  3. 生成可运行示例

    参考 服务端集成 的签名规则；示例必须能在本地服务端跑通（见 快速开始）。

  4. 用门禁验证

    生成代码后，用 错误码 与 服务端集成 的请求/响应字段逐项校验：路径、必填参数、鉴权头与失败分支都要对得上，确保没有引用不存在的操作或字段。

提示词模板​

prompt
你是 NI PaaS IM 的接入工程师。只能使用我提供的 OpenAPI 文档中的路径与字段。
任务：用 Node.js 实现「注册用户 → 签发 Token → 发送单聊消息」。
约束：签名算法按 /docs/platform-chat-api/auth；错误码按 /docs/platform-chat-api/code 处理；
输出可直接运行的脚本与 package.json。

边界与注意事项​

  • AI 生成的代码仍需人工评审：签名、鉴权头与错误处理是最容易出错的部分；
  • 不要把 appSecret/X-Admin-Secret 写进提示词或提交到仓库；
  • 文档正文与 OpenAPI 都由 IDL 生成，若与助手记忆冲突，以生成物为准；
  • 接口语义与限制见 API 语义与限制。