platform-api

平台 API 提取技能

概述

此技能提供 jq 查询模式，用于从 Genesys Cloud Platform API Swagger 2.0 架构中提取 API 端点信息。该架构包含 1,900 多个端点和 4,305 个定义，文件大小超过 19 MB。

架构：首次使用前，必须下载 schema.json。在此技能所在目录中运行下载脚本：

./scripts/download-schema.sh

如需了解区域选项和用法详情，请参阅下载脚本。

运行任何查询前，请确定此 SKILL.md 文件所在目录的绝对路径，并设置架构路径变量：

SCHEMA="<resolved-skill-directory>/schema.json"

以下所有示例均使用 "$SCHEMA" 引用此文件。

---

强制工作流

重要：绝不要在未经验证的情况下推荐端点！

当用户询问某个端点或 API 操作时，必须遵循以下 4 步工作流：

性能要求：并行执行查询

步骤 1-3 是相互独立的查询。请在同一条消息中使用多个 Bash 工具调用并行执行。

步骤 1：搜索并验证

搜索匹配的端点（始终将结果限制在 15-20 条）：

jq -r '.paths | keys | map(select(test("KEYWORD"; "i"))) | .[0:15] | .[]' "$SCHEMA"

常见模式：“查找所有 X” -> /api/v2/X$”，“获取特定 X” -> /api/v2/X/{id}`

详细搜索模式请参阅 references/search-operations.md。

步骤 2：确认确切端点存在

jq '.paths["/api/v2/exact/path"] | keys' "$SCHEMA"

如果返回 null，则该端点不存在。不要继续。

步骤 3：提取完整操作详情

jq '.paths["/api/v2/exact/path"]["METHOD"] | {
  operationId,
  summary,
  description,
  permissions: ."x-inin-requires-permissions",
  parameters: [.parameters[]? | {name, in, required, type, description}]
}' "$SCHEMA"

将 METHOD 替换为：get、post、put、patch 或 delete。

完整提取模式请参阅 references/jq-query-patterns.md，解析 $ref 引用请参阅 references/schema-resolution.md。

步骤 4：整理并回复用户

使用架构中的实际结果完成步骤 1-3 后，按以下结构回复：

## Recommended Endpoint

**Endpoint:** `[METHOD] /api/v2/path`
**Operation ID:** `operationId`
**Summary:** Brief description

### Permissions
- Type: ALL/ANY (or "No special permissions required" if null)
- Required: permission list

### Key Parameters
- List path/query/body parameters with required status

### Usage Notes
- Brief guidance on how to use this endpoint
- Any important caveats or considerations

---

禁止行为

• 根据 REST 模式假设端点存在
• 未经验证就猜测端点路径
• 未运行验证查询就推荐端点
• 根据常见 API 约定提供信息
• 可以并行运行时仍按顺序执行查询
• 返回不受限制的搜索结果（始终限制为 15-20 条）

必须遵循的行为

• 每次推荐前始终运行验证查询
• 在同一条消息中使用多个 Bash 工具调用并行执行独立查询
• 在回复中使用实际架构数据
• 使用 .[0:15] 或类似语法限制搜索结果
• 验证失败时明确说明不确定性（“架构中不存在该端点”）
• 如果未找到所搜索的端点，请提供替代方案
• 使用结构化模板整理回复

---

完整工作流示例

用户询问：“可使用哪个 API 端点查找所有用户？”

并行执行步骤 1-3（在同一条消息中使用 3 次 Bash 工具调用）：

# Tool Call 1: Search for user endpoints
jq -r '.paths | keys | map(select(test("user"; "i"))) | .[0:15] | .[]' "$SCHEMA"

# Tool Call 2: Verify /api/v2/users exists
jq '.paths["/api/v2/users"] | keys' "$SCHEMA"

# Tool Call 3: Get full details for GET /api/v2/users
jq '.paths["/api/v2/users"]["get"] | {
  operationId,
  summary,
  description,
  permissions: ."x-inin-requires-permissions",
  parameters: [.parameters[]? | {name, in, required, type, description}]
}' "$SCHEMA"

步骤 4：按结构化格式回复

## Recommended Endpoint

**Endpoint:** `GET /api/v2/users`
**Operation ID:** `getUsers`
**Summary:** Get the list of available users.

### Permissions
- Type: No special permissions required (permissions is null)

### Key Parameters
- `pageSize` (query, optional): Page size
- `pageNumber` (query, optional): Page number
- `id` (query, optional): A list of user IDs to fetch by bulk
- `sortOrder` (query, optional): Ascending or descending sort order
- `state` (query, optional): Only list users of this state

### Usage Notes
- This endpoint supports pagination via pageSize and pageNumber
- You can fetch specific users by providing an array of IDs in the id parameter
- Use expand parameter to include additional user information

---

资源

参考文档：

• references/jq-query-patterns.md - 全面的 jq 语法、高级筛选和变量链式处理
• references/search-operations.md - 所有搜索技巧、先计数再获取的模式
• references/schema-resolution.md - 定义解析、嵌套引用和属性提取
• references/complete-examples.md - 常见任务的分步工作流示例

外部资源：

• Swagger 2.0 规范：https://swagger.io/specification/v2/
• jq 手册：https://jqlang.github.io/jq/manual/