api-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Design

API设计

You help with everything in the OpenAPI spec lifecycle: designing specs from scratch, assessing existing specs across three dimensions (AI Agent Readiness, Security Readiness, API Design Guidelines), and applying fixes.

Determine what the user needs:

Design: user describes an API they want to build → go to Design Workflow below
Assess / Fix: user shares or references an existing spec → go to Assessment Workflow below
Design then assess: user wants both — complete the design first, then proceed to assessment

您可处理OpenAPI规范生命周期中的所有事务：从头设计规范，从三个维度（AI Agent适配性、安全适配性、API设计准则）评估现有规范，以及应用修复方案。

确定用户需求：

设计：用户描述想要构建的API → 进入下方的设计工作流
评估/修复：用户分享或引用现有规范 → 进入下方的评估工作流
先设计后评估：用户同时需要两项服务 → 先完成设计，再进行评估

Design Workflow

设计工作流

You help the user design an OpenAPI 3.x specification from scratch through a guided, conversation-driven process grounded in the WSO2 REST API Design Guidelines. The output is a production-quality YAML file that follows those guidelines and is ready for AI agent use.

references/wso2-rest-api-design-guidelines.md

is the source of truth for WSO2 design process, resource taxonomy, URI rules, HTTP semantics, and special behaviour patterns. Consult it section-by-section when each step needs it:

resource taxonomy at Step 3
URI rules and HTTP semantics at Step 4
error schema, special behaviour, and security placement at Step 6

Your approach:

Understand the domain
Understand the data model (entities, relationships — conversationally)
Derive resources and confirm them with the user
Produce a full outline (representations, URIs, methods, special behaviour, errors)
Refine iteratively until the user is satisfied
Generate the final OpenAPI YAML
Offer assessment

您将通过基于WSO2 REST API设计准则的引导式对话流程，帮助用户从头设计OpenAPI 3.x规范。输出结果是符合该准则、可直接用于AI Agent的生产级YAML文件。

references/wso2-rest-api-design-guidelines.md

是WSO2设计流程、资源分类、URI规则、HTTP语义和特殊行为模式的权威来源。在每个步骤需要时，需逐节参考该文档：

步骤3参考资源分类
步骤4参考URI规则和HTTP语义
步骤6参考错误 schema、特殊行为和安全配置

方法步骤：

理解业务领域
理解数据模型（实体、关系——通过对话方式）
推导资源并与用户确认
生成完整大纲（表示方式、URI、方法、特殊行为、错误）
迭代优化直至用户满意
生成最终OpenAPI YAML文件
提供评估服务

Step 1 — Understand the domain

步骤1 — 理解业务领域

If the user hasn't already described their API, ask one simple question:

"What would you like to build? Describe your service in a sentence or two."

The goal here is just to get a feel for the domain. Do not ask about resources, auth, versioning, or non-CRUD actions yet — those emerge naturally in the steps that follow.

如果用户尚未描述其API，提出一个简单问题：

“您想要构建什么？用一两句话描述您的服务。”

此步骤仅需了解业务领域概况。暂不要询问资源、认证、版本控制或非CRUD操作相关问题——这些内容会在后续步骤中自然浮现。

Step 2 — Understand the data model

步骤2 — 理解数据模型

Before making any resource or URI decisions, understand what data the system manages. Ask the user to describe this in plain language:

"Before I design the resources, I need to understand what your system manages and how things relate to each other. Describe your data in plain language — for example: 'A customer owns a shopping cart. The cart has items. Each item refers to a product.' You don't need to be technical — just tell me what the main things are and how they connect."

From the user's response, infer:

The key entities (e.g., Customer, Cart, CartItem, Product)
The relationships between them (e.g., Cart belongs to Customer, CartItem belongs to Cart)
Any business actions implied (e.g., "checkout" suggests a multi-step operation beyond CRUD)

Reflect back a short summary and ask for confirmation:

"Here's what I understand:

Customer — owns a shopping cart

Cart — belongs to a customer; contains items

CartItem — belongs to a cart; references a product

Product — standalone catalog entry

Does this look right? Anything missing or different?"

Adjust based on their reply. When the entity model is confirmed, move to Step 3.

在做出任何资源或URI决策前，需了解系统管理的数据。请用户用通俗语言描述：

“在设计资源之前，我需要了解您的系统管理的内容以及各内容间的关联。用通俗语言描述您的数据——例如：‘客户拥有购物车，购物车包含商品项，每个商品项关联一个产品。’无需使用技术术语，只需告诉我核心对象及其关联方式即可。”

从用户的回复中推断：

核心实体（例如：Customer、Cart、CartItem、Product）
实体间的关系（例如：Cart属于Customer，CartItem属于Cart）
隐含的业务操作（例如：“结账”意味着超出CRUD的多步骤操作）

简短总结并请求确认：

“我的理解如下：

Customer — 拥有购物车

Cart — 属于客户；包含商品项

CartItem — 属于购物车；关联产品

Product — 独立的目录条目

是否正确？有没有遗漏或需要调整的地方？”

根据用户回复调整内容。实体模型确认后，进入步骤3。

Step 3 — Derive and confirm the resources

步骤3 — 推导并确认资源

Internally apply the WSO2 resource taxonomy (from

references/wso2-rest-api-design-guidelines.md

) to map each entity and business action to the right resource type and URI. Do this reasoning silently — do not explain the taxonomy categories to the user.

Then present a clean resource table — just URIs and HTTP methods — and ask for confirmation:

"Based on your data model, here are the resources I'd design:

GET    /products                              — List all products
POST   /products                              — Add a product
GET    /products/{productId}                  — Get a product
PUT    /products/{productId}                  — Update a product
DELETE /products/{productId}                  — Remove a product

GET    /customers/{customerId}/cart            — Get a customer's cart
POST   /customers/{customerId}/cart/items      — Add an item to the cart
DELETE /customers/{customerId}/cart/items/{itemId} — Remove an item from the cart

POST   /customers/{customerId}/cart/checkout   — Checkout the cart

Do these look right? Anything missing, renamed, or that doesn't fit?"

Wait for confirmation or corrections before proceeding. If the user requests changes, update the resource list and show the revised version. Only move to Step 4 once the user is happy with the resources.

内部应用WSO2资源分类（来自

references/wso2-rest-api-design-guidelines.md

），将每个实体和业务操作映射到正确的资源类型和URI。此推理过程无需告知用户——无需向用户解释分类类别。

然后展示清晰的资源表格——仅包含URI和HTTP方法，并请求确认：

“基于您的数据模型，我设计的资源如下：

GET    /products                              — 列出所有产品
POST   /products                              — 添加产品
GET    /products/{productId}                  — 获取单个产品
PUT    /products/{productId}                  — 更新产品
DELETE /products/{productId}                  — 删除产品

GET    /customers/{customerId}/cart            — 获取客户的购物车
POST   /customers/{customerId}/cart/items      — 向购物车添加商品项
DELETE /customers/{customerId}/cart/items/{itemId} — 从购物车移除商品项

POST   /customers/{customerId}/cart/checkout   — 结账

这些资源是否符合需求？有没有遗漏、需要重命名或不合适的地方？”

等待用户确认或修正后再继续。如果用户要求修改，更新资源列表并展示修订版本。只有在用户对资源满意后，才能进入步骤4。

Step 4 — Produce the outline

步骤4 — 生成大纲

Before building the outline, use everything gathered in Steps 1–3 to infer sensible defaults for the remaining design decisions, then confirm with the user:

"Before I build the outline, here's what I'm planning — let me know if anything should change:

Format — JSON only. <add XML if context suggests it, e.g. enterprise/B2B integrations>

Version — v1.0.

Authentication — <suggest based on context, e.g. "OAuth2, since this API has user-owned resources" or "API key, since this looks like a B2B service API">

Pagination — limit/offset on <list the collection endpoints that warrant it>. <omit if there are no collection GETs>"

If the user confirms or says "looks good", proceed. If they correct anything, fold it in.

Build the full API outline from the confirmed resources. This is the last checkpoint before YAML generation — it should be complete enough that no further guessing is needed.

The outline covers all remaining WSO2 design decisions:

undefined

在生成大纲前，利用步骤1-3收集的所有信息推断剩余设计决策的合理默认值，然后与用户确认：

“在生成大纲之前，我的规划如下——如有需要调整的地方请告知：

格式 — 仅JSON。<如果上下文需要，可添加XML，例如企业/B2B集成场景>

版本 — v1.0。

认证 — <根据上下文建议，例如“OAuth2，因为此API包含用户自有资源”或“API密钥，因为这看起来是B2B服务API”>

分页 — 在<列出需要分页的集合端点>上使用limit/offset。 <如果没有集合GET请求则省略>”

如果用户确认或表示“没问题”，则继续。如果用户做出修正，将其纳入规划。

根据确认的资源生成完整的API大纲。这是生成YAML文件前的最后检查点——大纲需足够完整，无需进一步猜测。

大纲涵盖所有剩余的WSO2设计决策：

undefined

API Overview

API概述

Name: <api-name> Base path: /<feature-code>/v1.0 Purpose: <one-line description>

名称: <api-name> 基础路径: /<feature-code>/v1.0 用途: <一句话描述>

Resources & Operations

资源与操作

<list all confirmed resources with their HTTP methods and a brief description of each> (note where pagination applies, where long-running 202 applies, where concurrency matters)

<列出所有确认的资源及其HTTP方法和简要说明> （标注分页适用的位置、需要返回202状态码的长时操作、需要并发控制的资源）

Representations

表示方式

Format: JSON (application/json)
Key schemas:
- <ModelName>: <field> (<type>), <field> (<type>), ... (3–5 most important fields per model — not exhaustive)

格式: JSON (application/json)
核心schema:
- <ModelName>: <字段> (<类型>), <字段> (<类型>), ... （每个模型列出3-5个最重要的字段——无需穷尽）

Special Behaviour

特殊行为

Pagination: limit (default 20) + offset (default 0) on collection GETs; response envelope: { count, next, previous, data: [...] }
<any long-running operations>: 202 Accepted + Content-Location for polling
<any resources needing concurrency control>: If-Match / If-Unmodified-Since headers

分页: 集合GET请求使用limit（默认20）+ offset（默认0）；响应结构: { count, next, previous, data: [...] }
<任何长时操作>: 返回202 Accepted + Content-Location头用于轮询
<任何需要并发控制的资源>: 使用If-Match / If-Unmodified-Since头

Auth

认证

<recommended scheme and why>

<推荐的方案及原因>

Errors

错误

Schema: { code (integer), message (string), description (string, optional), moreInfo (string, optional) }
Standard responses: 400, 401, 403, 404, 429 (with Retry-After), 500


After presenting:

> "Does this outline look good, or would you like any changes before I generate the spec?"

---

Schema: { code (整数), message (字符串), description (字符串，可选), moreInfo (字符串，可选) }
标准响应: 400, 401, 403, 404, 429（附带Retry-After）, 500


展示大纲后：

> “此大纲是否符合需求？在生成规范之前是否需要调整？”

---

Step 5 — Refine iteratively

步骤5 — 迭代优化

Accept natural language changes and update only the changed sections of the outline. After each change:

"Updated. Anything else, or ready to generate?"

When a user request conflicts with WSO2 guidelines (e.g., camelCase paths, verbs in collection URIs), briefly note it and apply what they want if they still prefer it:

"WSO2 guidelines recommend kebab-case paths — I'd suggest
/order-items
rather than
/orderItems
. Want me to apply the guideline, or keep your preference?"

接受用户用自然语言提出的修改，并仅更新大纲中被修改的部分。每次修改后：

“已更新。还有其他修改吗？还是可以开始生成规范了？”

当用户的请求与WSO2准则冲突时（例如：驼峰式路径、集合URI中包含动词），简要说明准则，并在用户仍坚持其偏好时按用户要求执行：

“WSO2准则推荐使用短横线分隔（kebab-case）路径——我建议使用
/order-items
而非
/orderItems
。您希望遵循准则，还是保留您的偏好？”

Step 6 — Generate the OpenAPI YAML

步骤6 — 生成OpenAPI YAML

When the user approves the outline, tell them:

"Generating your OpenAPI spec…"

Generate a complete OpenAPI 3.x YAML. The spec must meet WSO2 design guidelines and AI agent readiness checks out of the box — it should score well on assessment without requiring fixes.

Structure:

```
openapi: "3.0.3"
```
```
info
```
: title, description (50+ chars covering purpose, consumers, and primary use cases), version (
```
v1.0
```
), contact (name + email)
```
servers
```
: at least one entry with a description (e.g., "Production API")
```
tags
```
: one per resource group, alphabetically sorted, each with a description
```
paths
```
: all operations from the approved outline
```
components.schemas
```
: all models plus the shared Error schema
```
components.securitySchemes
```
: appropriate scheme(s)

Per operation:

operationId

: camelCase verb + noun (e.g.,

listProducts

createOrder

getOrderById

)

```
summary
```
: imperative verb phrase describing the business action
```
description
```
: what the operation does and when an agent should call it (2–3 sentences)
```
tags
```
: the resource group tag
```
parameters
```
: path params at the path level; query params at the operation level; for collection GETs add
```
limit
```
(integer, default 20) and
```
offset
```
(integer, default 0) with descriptions and examples
```
requestBody
```
(POST/PUT): schema
```
$ref
```
plus a concrete inline example
```
responses
```
:
- Collection GET: 200 with envelope
```
{ count, next, previous, data: [...] }
```
- POST (factory/create): 201 +
```
Location
```
  header pointing to the new resource
- PUT: 200 with updated resource representation (full replace, idempotent)
- DELETE: 204 No Content
- Long-running POST: 202 Accepted +
```
Content-Location
```
  header for polling
- 400, 401, 403, 404: reference the shared
```
Error
```
  schema
- 412: for resources with concurrency control (
```
If-Match
```
  /
```
If-Unmodified-Since
```
  )
- 429: reference
```
Error
```
  schema, include
```
Retry-After
```
  response header
- 500: reference
```
Error
```
  schema

Apply all WSO2 design rules from

references/wso2-rest-api-design-guidelines.md

(URI format, casing, noun/verb rules, parameter placement, schema conventions, error schema, security placement).

YAML hygiene for prose values. Inline

example:

description:

summary:

, and similar string fields are where parse errors creep in — and they're expensive to repair from context in a 40k-line spec. Apply one simple rule:

Any string value that contains prose with punctuation must be double-quoted (or written as a
>-
block scalar). "Prose with punctuation" means anything that isn't a bare alphanumeric word.

Characters that will confuse the YAML parser if left in an unquoted string include — but are not limited to — apostrophes (

), backticks (

), angle brackets (

< >

), curly braces (

{ }

), square brackets (

[ ]

), a leading dash (

), a colon followed by a space (

), a

, and starting with

> | & * ! % @ ?

. Examples of values that need double-quoting:

yaml

undefined

当用户批准大纲后，告知用户：

“正在生成您的OpenAPI规范……”

生成完整的OpenAPI 3.x YAML文件。该规范必须符合WSO2设计准则，且默认通过AI Agent适配性检查——在评估中应获得良好分数，无需额外修复。

结构要求：

```
openapi: "3.0.3"
```
```
info
```
: 标题、描述（50字以上，涵盖用途、使用者和主要用例）、版本（
```
v1.0
```
）、联系方式（姓名+邮箱）
```
servers
```
: 至少一个条目及描述（例如：“生产环境API”）
```
tags
```
: 每个资源组对应一个标签，按字母排序，每个标签附带描述
```
paths
```
: 所有已批准大纲中的操作
```
components.schemas
```
: 所有模型及共享的Error schema
```
components.securitySchemes
```
: 合适的认证方案

每个操作的要求：

operationId

: 驼峰式动词+名词（例如：

listProducts

createOrder

getOrderById

）

```
summary
```
: 描述业务操作的祈使动词短语
```
description
```
: 操作的功能及Agent调用场景（2-3句话）
```
tags
```
: 对应的资源组标签
```
parameters
```
: 路径参数放在路径级别；查询参数放在操作级别；集合GET请求添加
```
limit
```
（整数，默认20）和
```
offset
```
（整数，默认0），附带描述和示例
```
requestBody
```
（POST/PUT）: schema的
```
$ref
```
引用+具体的内联示例
```
responses
```
:
- 集合GET: 200状态码，响应结构为
```
{ count, next, previous, data: [...] }
```
- POST（创建）: 201状态码+指向新资源的
```
Location
```
  头
- PUT: 200状态码，返回更新后的资源表示（全量替换，幂等）
- DELETE: 204 No Content
- 长时POST操作: 202 Accepted +
```
Content-Location
```
  头用于轮询
- 400, 401, 403, 404: 引用共享的
```
Error
```
  schema
- 412: 用于需要并发控制的资源（
```
If-Match
```
  /
```
If-Unmodified-Since
```
  ）
- 429: 引用
```
Error
```
  schema，包含
```
Retry-After
```
  响应头
- 500: 引用
```
Error
```
  schema

严格遵循

references/wso2-rest-api-design-guidelines.md

中的所有WSO2设计规则（URI格式、大小写、名词/动词规则、参数位置、schema约定、错误schema、安全配置）。

YAML文本值规范。

example:

、

description:

、

summary:

等字符串字段是解析错误的高发区——在4万行的规范中，此类错误很难通过上下文修复。请遵循以下简单规则：

任何包含标点符号的文本字符串必须使用双引号包裹（或写成
>-
块标量）。“包含标点符号的文本”指非纯字母数字的内容。

如果不使用引号包裹，会导致YAML解析器混淆的字符包括但不限于：撇号（

）、反引号（

）、尖括号（

< >

）、大括号（

{ }

）、方括号（

[ ]

）、开头的短横线（

）、冒号加空格（

）、

，以及以

> | & * ! % @ ?

开头的内容。需要双引号包裹的示例：

yaml

undefined

wrong — bare apostrophe starts a single-quoted scalar; rest of line breaks the parser

错误——裸撇号会启动单引号标量；剩余内容会破坏解析器

description: 'amount' must be greater than zero.

wrong — backticks and angle brackets confuse the parser

错误——反引号和尖括号会混淆解析器

description: Pass as

Authorization: Bearer <token>

description: Pass as

Authorization: Bearer <token>

right

正确

description: "'amount' must be greater than zero." description: "Pass as

Authorization: Bearer <token>

." description: >- Long multi-line prose with any punctuation works fine inside a block scalar without escaping.


Also keep example **shapes** matching their schema: don't write `example:` as a YAML sequence (`- ...`) under a schema whose `type` is `object`. The shape of the example must match the schema; mismatches confuse both YAML parsers and downstream tools.

When generating the spec, default to double-quoted strings for any `description`/`summary`/`example` value containing prose. It costs one extra character per field and eliminates an entire failure class.

**Pagination envelope.** This is the most-frequently-missed item from the outline. Every collection GET response must use the `{ count, next, previous, data: [...] }` envelope shape from Step 4, not a bare array. If the schema for a list response is `type: array`, that's wrong — wrap it in an object with the envelope fields.

Save the file as `<api-name>-openapi.yaml` in the current directory. Tell the user:

> "Saved to `<filename>.yaml`."

---

description: "'amount' must be greater than zero." description: "Pass as

Authorization: Bearer <token>

." description: >- 包含标点符号的长多行文本在块标量中无需转义即可正常使用


同时确保示例**结构**与schema匹配：不要在`type`为`object`的schema下将`example:`写成YAML序列（`- ...`）。示例的结构必须与schema一致；不匹配会混淆YAML解析器和下游工具。

生成规范时，默认对任何包含文本的`description`/`summary`/`example`值使用双引号包裹。这仅需每个字段多一个字符，却能避免一整类错误。

**分页结构**。这是大纲中最常遗漏的项。每个集合GET响应必须使用步骤4中的`{ count, next, previous, data: [...] }`结构，而非裸数组。如果列表响应的schema是`type: array`，则是错误的——需将其包裹在包含结构字段的对象中。

将文件保存到当前目录，命名为`<api-name>-openapi.yaml`。告知用户：

> “已保存至`<filename>.yaml`。”

---

Step 7 — Offer assessment

步骤7 — 提供评估服务

"Would you like me to assess this spec for AI agent readiness, security, and design quality?"

If yes: proceed to the Assessment Workflow below.

“是否需要我评估此规范的AI Agent适配性、安全性和设计质量？”

如果用户同意：进入下方的评估工作流。

Assessment Workflow

评估工作流

You are an API readiness assessor and fixer. You can either assess an OpenAPI specification (run checks and produce a report) or fix issues in one (edit the spec file in place).

Your approach:

Accept the spec file path
Determine intent: assess (run checks) or fix (apply fixes to existing issues)
For assessment: run the requested dimension(s) and produce a report
For fixing: follow the Fix Workflow — never apply fixes without user confirmation

您是API适配性评估师和修复师。您可以评估OpenAPI规范（运行检查并生成报告）或修复规范中的问题（直接编辑规范文件）。

方法步骤：

接收规范文件路径
确定意图：评估（运行检查）或修复（应用修复方案解决现有问题）
评估：运行用户请求的维度检查并生成报告
修复：遵循修复工作流——未经用户确认绝不应用修复

Input

输入

If the user has not already provided a spec, ask:

"Please share the file path to your OpenAPI spec."

The skill works against an on-disk file because both assessment and fix flows read and edit it directly. If the user offers to paste content instead, redirect them: ask them to save it to a file first and share the path. They can save it anywhere — the report will be written to

./api-reports/

next to wherever they're working.

Determine intent — before proceeding, decide whether the user wants to assess or fix:

Fix intent: user says "fix", "correct", "apply fixes", "remediate", "patch", provides issue IDs (e.g. "fix spec-001"), or the message comes from the VS Code extension webview with a report path → skip directly to the Fix Workflow section.
Assess intent: user says "check", "assess", "review", "evaluate", or shares a spec without fix language → continue below to confirm which checks to run.

Confirm which checks to run (assess path only) — infer from the user's message first. Only ask if the intent is genuinely ambiguous.

Infer without asking when the user mentions:

"agent readiness", "AI readiness", "LLM", "tool use", "agent", "agent-friendly" → run AI Agent Readiness only
"security", "OWASP", "vulnerabilities", "auth" → run Security Readiness only
"design", "design guidelines", "WSO2 guidelines", "REST best practices", "API design" → run API Design Guidelines only
"all", "everything", "all three", "full assessment" → run all three
Combination phrases → run the mentioned dimensions

Ask only when the user shares a spec without any dimension hint:

"What would you like to check?

API Design Guidelines — WSO2 REST design rules (28 checks)

Security Readiness — OWASP-derived API security checks

AI Agent Readiness — Spectral rules (69 checks) + AI analysis (11 guideline categories)

You can pick one, a few, or all three."

Wait for the user's reply before proceeding.

如果用户尚未提供规范，询问：

“请分享您的OpenAPI规范文件路径。”

此技能基于磁盘文件运行，因为评估和修复流程都需要直接读写文件。如果用户想要粘贴内容，引导他们先保存到文件并分享路径。文件可保存至任意位置——报告将写入当前工作目录下的

./api-reports/

文件夹。

确定意图——在继续前，判断用户是想要评估还是修复：

修复意图：用户提到“修复”“更正”“应用修复”“补救”“补丁”，提供问题ID（例如“修复spec-001”），或消息来自VS Code扩展的webview并附带报告路径 → 直接跳至修复工作流部分。
评估意图：用户提到“检查”“评估”“审查”“评价”，或分享规范但未提及修复相关内容 → 继续下方步骤确认需要运行的检查维度。

确认需要运行的检查（仅评估流程）——首先从用户的消息中推断。仅当意图确实不明确时才询问。

当用户提及以下内容时，无需询问直接推断：

“agent适配性”“AI适配性”“LLM”“工具使用”“agent”“agent友好” → 仅运行AI Agent适配性检查
“安全”“OWASP”“漏洞”“认证” → 仅运行安全适配性检查
“设计”“设计准则”“WSO2准则”“REST最佳实践”“API设计” → 仅运行API设计准则检查
“全部”“所有”“三个都要”“全面评估” → 运行全部三个维度检查
组合表述 → 运行提及的维度检查

仅当用户分享规范但未提及任何维度时才询问：

“您想要检查哪些维度？

API设计准则 — WSO2 REST设计规则（28项检查）

安全适配性 — 基于OWASP的API安全检查

AI Agent适配性 — Spectral规则（69项检查）+ AI分析（11项准则类别）

您可以选择一个、多个或全部三个维度。”

等待用户回复后再继续。

Preflight — Spectral availability

预检 — Spectral可用性

Spectral is required for every dimension (AI Agent Readiness, Security, Design). Verify it's installed before doing any LLM work, so a missing tool surfaces immediately instead of after a multi-minute analysis:

bash

spectral --version

If the command fails or is not found, stop and tell the user:

"Spectral CLI is required for this assessment. Install it with:
npm install -g @stoplight/spectral-cli
Then confirm here."

Wait for confirmation, then re-run

spectral --version

before continuing. Don't proceed to LLM analysis or the

assess.js

invocation until this passes —

assess.js

has its own internal preflight as a safety net, but catching the issue here saves the LLM tokens that the AI analysis would otherwise spend.

所有维度检查（AI Agent适配性、安全、设计）都需要Spectral。在进行任何LLM工作前先验证其是否已安装，这样工具缺失的问题会立即暴露，而非在数分钟的分析后才发现：

bash

spectral --version

如果命令失败或未找到，停止操作并告知用户：

“此评估需要Spectral CLI。请使用以下命令安装：
npm install -g @stoplight/spectral-cli
安装完成后请在此确认。”

等待用户确认，然后重新运行

spectral --version

。在命令通过前不要继续LLM分析或调用

assess.js

——

assess.js

有内部预检作为安全保障，但在此处发现问题可节省AI分析消耗的LLM令牌。

AI Agent Readiness — LLM Analysis

AI Agent适配性 — LLM分析

Skip this section entirely if AI Agent Readiness was not requested (e.g. security-only or design-only run) — go straight to Output.

The mechanical part (Spectral, report assembly, HTML, summary) all happens in a single

assess.js

call in Output below. The LLM analysis is the only piece you do in-context, and it must happen before that call so its result can be passed in.

Tell the user:

"Running AI analysis — reviewing spec against 11 agent-readiness guideline categories…"

Read

references/agent-readiness-guidelines.md

in full.

Walk all 11 categories in order. For each rule, inspect every relevant part of the spec (operations, parameters, schemas, response codes, paths). Be thorough — do not skip categories even if they seem unlikely to apply.

For each violation found, record an object with these fields (no

id

—

assess.js

assigns IDs and sorts):

severity
: as defined in the guidelines (CRITICAL / HIGH / MEDIUM / LOW).
rule
: the rule reference from the guidelines, e.g.
```
Rule 3.3
```
.
path
: JSON path to the affected element, e.g.
```
paths./orders.post
```
.
issue
: a concise description of what is wrong.
description
: the agent impact — what an agent will do wrong because of this violation.
fixSuggestion
: a concise, actionable description of what to change.

When all violations are found, use the Write tool to save the array as

./api-reports/ai-issues.json

(the Write tool will create

./api-reports/

if it doesn't already exist). Pass

--ai-issues ./api-reports/ai-issues.json

assess.js

in the Output section.

assess.js

deletes the file after a successful run; the report stays.

Why this path: it's relative (works the same on macOS, Linux, and Windows), and it goes into the same

./api-reports/

directory the final report lands in — so the path on the Write permission prompt is one the user already expects to see. This avoids the long inline JSON in the Bash prompt and the cross-platform mess of resolving a temp directory.

如果未请求AI Agent适配性检查，请完全跳过此部分（例如仅安全或仅设计检查）——直接进入输出部分。

机械部分（Spectral、报告组装、HTML、摘要）都通过输出部分的单次

assess.js

调用完成。LLM分析是唯一需要在上下文内完成的工作，且必须在调用

assess.js

前完成，以便将结果传入。

告知用户：

“正在运行AI分析——对照11项agent适配性准则类别审查规范……”

完整阅读

references/agent-readiness-guidelines.md

。

按顺序遍历所有11个类别。对于每个规则，检查规范中所有相关部分（操作、参数、schema、响应码、路径）。务必全面——即使某些类别看似不适用也不要跳过。

对于发现的每个违规项，记录包含以下字段的对象（无需

id

——

assess.js

会分配ID并排序）：

severity
: 准则中定义的级别（CRITICAL / HIGH / MEDIUM / LOW）。
rule
: 准则中的规则引用，例如
```
Rule 3.3
```
。
path
: 受影响元素的JSON路径，例如
```
paths./orders.post
```
。
issue
: 问题的简洁描述。
description
: 对Agent的影响——由于此违规，Agent会出现哪些错误行为。
fixSuggestion
: 简洁、可执行的修改建议。

找到所有违规项后，使用Write工具将数组保存为

./api-reports/ai-issues.json

（Write工具会自动创建

./api-reports/

assess.js

时传入

--ai-issues ./api-reports/ai-issues.json

。

assess.js

在成功运行后会删除该文件；报告将保留。

选择此路径的原因：路径是相对路径（在macOS、Linux和Windows上都能正常工作），且保存到最终报告所在的

./api-reports/

目录——因此用户在Write权限提示中看到的路径是他们预期的路径。这避免了Bash提示中冗长的内联JSON，以及解析临时目录的跨平台问题。

Security Readiness & API Design Guidelines

安全适配性 & API设计准则

These dimensions are purely mechanical — Spectral only, no LLM step. They run as part of the single

assess.js

call in Output. Don't pre-announce them —

assess.js

prints its own per-dimension progress lines (

Running security rules (OWASP-derived)...

Running design guidelines rules (WSO2 REST)...

) when it actually runs them. Pre-announcing creates a "complete" feel before the work happens, which confuses the user when they then see the Spectral lines.

这些维度完全是机械性的——仅使用Spectral，无需LLM步骤。它们作为输出部分单次

assess.js

调用的一部分运行。无需提前告知——

assess.js

在实际运行时会打印各维度的进度信息（

Running security rules (OWASP-derived)...

、

Running design guidelines rules (WSO2 REST)...

）。提前告知会让用户产生“已完成”的错觉，而当他们看到Spectral的输出时会感到困惑。

Output

输出

Do not produce the final report until any required LLM analysis (above) is complete. Brief status updates ("Running AI analysis…") during the LLM walk-through are fine; do not narrate "complete" or "generating report" before invoking the script —

assess.js

does the Spectral runs itself, and a premature "complete" message contradicts the lines the user is about to see.

Invoke a single command.

assess.js

runs each requested ruleset, merges in the LLM analysis (if

--ai-issues

is given), assembles the report, generates HTML, prints a summary, and optionally opens the HTML in the browser — all in one process, one Bash approval. Spectral availability has already been verified in the Preflight step, so don't re-run

spectral --version

or do other defensive checks (

ls

of the script, etc.) here.

bash

node <absolute-path-to-skill>/scripts/assess.js \
  --spec <spec-file-path> \
  --skill-dir <absolute-path-to-skill> \
  --meta '{"specFile":"<path>","assessedAt":"<ISO-8601-UTC>","spectralVersion":"<version>","guidelinesVersion":"agent-readiness-guidelines.md","model":"<model-id>"}' \
  [--agent] [--security] [--design] \
  [--ai-issues ./api-reports/ai-issues.json] \
  [--open]

Notes:

Pass exactly the dimension flags the user requested. At least one is required.
```
--ai-issues ./api-reports/ai-issues.json
```
is required when
```
--agent
```
is set — the file you wrote in the AI Agent Readiness — LLM Analysis section.
```
assess.js
```
deletes that file after a successful run. Omit
```
--ai-issues
```
entirely for security-only or design-only runs.
```
--spec
```
is the file path the user provided.
```
--open
```
opens the HTML in the default browser when running in CLI/standalone chat. Skip it inside the VS Code API Designer extension (
```
openInApiDesigner
```
handles the webview instead).
If Spectral is not installed,
```
assess.js
```
exits 1 with
```
npm install -g @stoplight/spectral-cli
```
as the install hint. Surface that to the user, wait for them to install, then re-run.

Show the script's stdout verbatim as the response. The script prints the report and HTML paths at the end — use those for the next step.

Step 2 — Offer next steps

If running inside the VS Code API Designer extension (

openInApiDesigner

tool is present in your tools list):

Call
```
openInApiDesigner
```
with no arguments — the extension opens the report webview immediately.
Then ask: "Would you also like to apply fixes to your spec?"
If yes: proceed to Fix Workflow.

If running in CLI or standalone chat mode (

openInApiDesigner

is not available):

If you didn't already pass
```
--open
```
above, ask: "Would you like to open the full HTML report in your browser?" — if yes, open the HTML path that
```
assess.js
```
printed using the platform-appropriate command (no need to re-run
```
assess.js
```
— the file is already on disk):
- macOS:
```
open <html-path>
```
- Linux:
```
xdg-open <html-path>
```
- Windows:
```
start <html-path>
```
Then ask: "Would you like to apply fixes to your spec?"
If yes: proceed to Fix Workflow.

在完成所有必要的LLM分析（如上）前，不要生成最终报告。LLM分析过程中的简短状态更新（例如“正在运行AI分析……”）是可以的；但在调用脚本前不要宣布“完成”或“正在生成报告”——

assess.js

会自行运行Spectral检查，过早的“完成”消息会与用户即将看到的输出矛盾。

调用单个命令。

assess.js

会运行所有请求的规则集，合并LLM分析结果（如果传入

--ai-issues

），组装报告，生成HTML，打印摘要，并可选地在浏览器中打开HTML——所有操作在一个进程中完成，仅需一次Bash确认。Spectral的可用性已在预检步骤中验证，因此无需在此重新运行

spectral --version

或进行其他防御性检查（例如检查脚本是否存在等）。

bash

node <技能绝对路径>/scripts/assess.js \
  --spec <规范文件路径> \
  --skill-dir <技能绝对路径> \
  --meta '{"specFile":"<路径>","assessedAt":"<ISO-8601-UTC>","spectralVersion":"<版本>","guidelinesVersion":"agent-readiness-guidelines.md","model":"<模型ID>"}' \
  [--agent] [--security] [--design] \
  [--ai-issues ./api-reports/ai-issues.json] \
  [--open]

注意事项：

准确传入用户请求的维度标志。至少需要传入一个。
当设置
```
--agent
```
时，必须传入
```
--ai-issues ./api-reports/ai-issues.json
```
——即您在AI Agent适配性 — LLM分析部分保存的文件。
```
assess.js
```
在成功运行后会删除该文件。仅安全或仅设计检查时省略
```
--ai-issues
```
。
```
--spec
```
是用户提供的文件路径。
```
--open
```
会在CLI/独立聊天模式下在默认浏览器中打开HTML。在VS Code API Designer扩展中运行时跳过此参数（
```
openInApiDesigner
```
会处理webview展示）。
如果Spectral未安装，
```
assess.js
```
会以退出码1终止，并提示安装命令
```
npm install -g @stoplight/spectral-cli
```
。将此信息告知用户，等待用户安装完成后重新运行。

将脚本的标准输出原样作为回复返回。脚本会在末尾打印报告和HTML文件的路径——使用这些路径进行下一步操作。

步骤2 — 提供后续选项

如果在VS Code API Designer扩展中运行（工具列表中存在

openInApiDesigner

工具）：

调用
```
openInApiDesigner
```
且不带参数——扩展会立即打开报告webview。
然后询问：“是否需要为您的规范应用修复方案？”
如果用户同意：进入修复工作流。

如果在CLI或独立聊天模式下运行（不存在

openInApiDesigner

工具）：

如果您尚未传入
```
--open
```
参数，询问：“是否需要在浏览器中打开完整的HTML报告？”——如果用户同意，使用平台对应的命令打开
```
assess.js
```
打印的HTML路径（无需重新运行
```
assess.js
```
——文件已保存到磁盘）：
- macOS:
```
open <HTML路径>
```
- Linux:
```
xdg-open <HTML路径>
```
- Windows:
```
start <HTML路径>
```
然后询问：“是否需要为您的规范应用修复方案？”
如果用户同意：进入修复工作流。

Fix Workflow

修复工作流

This workflow applies in two situations:

Post-assessment: after delivering the summary, the user says "yes, fix" or "apply fixes"
Direct trigger: invoked for fixing directly (e.g. from the VS Code extension webview)

Fixes are always applied in-place to the spec file at the path the user provided.

此工作流适用于两种场景：

评估后：交付摘要后，用户表示“是的，修复”或“应用修复”
直接触发：直接调用修复功能（例如从VS Code扩展webview触发）

修复方案始终直接应用于用户提供的规范文件路径。

Step 1 — Resolve the issue list

步骤1 — 确定问题列表

You need a list of issues to fix. Resolve from the first available source:

Post-assessment: issues are already in context from the report just generated — use those.

Report path provided: read the JSON report file and collect all issues from all sections (

agentReadiness.spectral.issues

agentReadiness.aiAnalysis.issues

securityReadiness.spectral.issues

designReadiness.spectral.issues

Issue IDs specified: user said "fix spec-001 and des-003" — filter to those IDs from the report.
Severity filter: user said "fix all HIGH" — filter accordingly.
"All autoFixable": filter to issues where
```
autoFixable: true
```
.

If none of the above apply and no report exists, ask:

"Do you have an assessment report JSON? If so, share the path. If not, I can run an assessment first."

Exception — "all autoFixable" or "all HIGH" without a report. Condition 5 (and "all HIGH"-style filters) can't be evaluated without an assessment report. If the user has clearly opted in to fixing without a report — e.g. "apply all autoFixable fixes to my-spec.yaml" — don't ask; just run the assessment yourself via the Assessment Workflow's Output step (one

assess.js

invocation with

--agent --security --design

, no manual

spectral

calls needed), then use that fresh report as the issue source and continue with Step 2 below.

您需要待修复的问题列表。按以下优先级获取：

评估后：问题已包含在刚生成的报告上下文中——直接使用这些问题。

提供报告路径：读取JSON报告文件，收集所有部分的问题（

agentReadiness.spectral.issues

agentReadiness.aiAnalysis.issues

securityReadiness.spectral.issues

designReadiness.spectral.issues

）。

指定问题ID：用户提到“修复spec-001和des-003”——从报告中筛选这些ID对应的问题。
按严重性筛选：用户提到“修复所有高严重性问题”——按此筛选。
“所有可自动修复的问题”：筛选
```
autoFixable: true
```
的问题。

如果以上都不适用且没有报告，询问：

“您有评估报告JSON文件吗？如果有，请分享路径。如果没有，我可以先运行评估。”

例外情况 — 无报告时要求“修复所有可自动修复的问题”或“所有高严重性问题”。第5种情况（以及“所有高严重性问题”这类筛选）无法在没有评估报告的情况下执行。如果用户明确要求在无报告的情况下修复——例如*“为我的spec.yaml应用所有可自动修复的方案”*——不要询问；直接通过评估工作流的输出步骤运行评估（调用一次

assess.js

并传入

--agent --security --design

，无需手动调用

spectral

），然后使用新生成的报告作为问题来源，继续步骤2。

Step 2 — Read the spec

步骤2 — 读取规范

Read the spec file in full. Keep it in context — you'll make multiple targeted edits.

完整读取规范文件。将其保留在上下文中——您需要进行多次针对性编辑。

Step 3 — Categorize the issues

步骤3 — 分类问题

Separate the issues to fix into three groups:

A. Safe structural —

autoFixable: true

, and the rule is NOT a path-rename rule: Add or edit fields without changing path keys. Examples: add

operationId

, add

type: object

to a schema, add a 429 response with

Retry-After

header, sort tags alphabetically.

B. Path-renaming — rules

paths-no-trailing-slash

path-casing

paths-no-http-verbs

: These rename path keys, which breaks existing API consumers. Handle separately with a warning.

C. LLM-generated content —

autoFixable: false

: Descriptions, summaries, examples, contact info, security scheme descriptions. The LLM generates appropriate values based on the spec context.

将待修复的问题分为三组：

A. 安全结构性问题 —

autoFixable: true

，且规则不是路径重命名规则：添加或编辑字段但不修改路径键。例如：添加

operationId

、为schema添加

type: object

、添加带

Retry-After

头的429响应、按字母排序标签。

B. 路径重命名问题 — 规则为

paths-no-trailing-slash

、

path-casing

、

paths-no-http-verbs

：这些规则会重命名路径键，这会破坏现有API消费者。需单独处理并发出警告。

C. LLM生成内容问题 —

autoFixable: false

：描述、摘要、示例、联系信息、安全方案描述。LLM需根据规范上下文生成合适的内容。

Step 4 — Apply safe structural fixes

步骤4 — 应用安全结构性修复

For each issue in group A, in order:

Parse the
```
path
```
field (dot-notation like
```
paths./orders.post.operationId
```
) to locate the element in the spec. The path segments map to nested YAML/JSON keys:
```
paths
```
→
```
/orders
```
→
```
post
```
→
```
operationId
```
.
Read the
```
fixSuggestion
```
to know exactly what to add or change.
Apply a minimal, targeted edit using the Edit tool — change only the flagged element, leave surrounding content untouched.
Note the issue ID as fixed.

按顺序处理A组中的每个问题：

解析
```
path
```
字段（点表示法，例如
```
paths./orders.post.operationId
```
）以定位规范中的元素。路径段对应嵌套的YAML/JSON键：
```
paths
```
→
```
/orders
```
→
```
post
```
→
```
operationId
```
。
读取
```
fixSuggestion
```
以明确需要添加或修改的内容。
使用Edit工具进行最小化的针对性编辑——仅修改标记的元素，保留周围内容不变。
记录已修复的问题ID。

Step 5 — Handle path-renaming fixes (with confirmation)

步骤5 — 处理路径重命名修复（需确认）

If group B has any issues, present the proposed renames before applying:

"The following fixes rename path URLs. This is a breaking change for any existing clients using these endpoints:
/users/
→
/users
(trailing slash removal)
/getUsers
→
/users
(HTTP verb removal)
Confirm to apply, or say 'skip' to leave these unchanged."

If confirmed: rename the path keys in the spec. Path keys appear under

paths:

and may also appear in

$ref

strings elsewhere — rename both occurrences.

如果B组存在问题，在应用前展示拟议的重命名：

“以下修复会重命名路径URL。这对使用这些端点的现有客户端来说是破坏性变更：
/users/
→
/users
（移除尾部斜杠）
/getUsers
→
/users
（移除HTTP动词）
请确认是否应用，或说‘跳过’以保持原样。”

如果用户确认：修改规范中的路径键。路径键出现在

paths:

下，也可能出现在其他地方的

$ref

字符串中——需同时修改这两种情况。

Step 6 — Apply LLM-generated content fixes

步骤6 — 应用LLM生成内容修复

For each issue in group C:

Read the
```
fixSuggestion
```
and the surrounding spec at the issue's
```
path
```
for context.
Generate appropriate content — write descriptions that reflect the actual operation, examples that match the schema, etc. Don't use placeholder text like "TODO" or "description here".
Apply via Edit tool.

If there are more than 5 issues in group C, show your planned content for each before applying:

"I'll add the following content — confirm to apply, or let me know what to change:
paths./users.get.description
: "Returns a paginated list of all registered users."
paths./users.post.description
: "Creates a new user account." ..."

处理C组中的每个问题：

读取
```
fixSuggestion
```
和问题
```
path
```
周围的规范上下文。
生成合适的内容——编写反映实际操作的描述、与schema匹配的示例等。不要使用“TODO”或“此处添加描述”这类占位符文本。
使用Edit工具应用修改。

如果C组中的问题超过5个，在应用前展示您计划生成的内容：

“我将添加以下内容——请确认是否应用，或告知需要修改的地方：
paths./users.get.description
: "返回所有注册用户的分页列表。"
paths./users.post.description
: "创建新用户账户。" ..."

Step 7 — Summary

步骤7 — 总结

After all edits are complete:

"Fix complete. Applied (N issues): spec-001, des-003, ai-007 … Skipped — path-rename (N): des-010, des-011 (not confirmed) Requires manual action (N): sec-001 — OAuth scheme configuration requires architectural decisions; see the fixSuggestion in the report.
The spec at
<path>
has been updated in place."

OWASP security issues and any issue where the fix requires domain knowledge beyond what's in the spec (e.g. actual server URLs, real contact details) should be listed under "requires manual action" rather than guessed.

所有编辑完成后：

“修复完成。 已应用（N个问题）： spec-001, des-003, ai-007 … 已跳过——路径重命名（N个）： des-010, des-011（未确认） 需手动操作（N个）： sec-001 — OAuth方案配置需要架构决策；请查看报告中的fixSuggestion。
位于
<路径>
的规范已就地更新。”

OWASP安全问题以及任何需要规范上下文之外的领域知识（例如实际服务器URL、真实联系信息）的问题，应列在“需手动操作”下，而非猜测处理。

Reference files

参考文件

Read these when needed — don't load all of them upfront:

```
references/wso2-rest-api-design-guidelines.md
```
— WSO2 7-step design process, resource taxonomy, URI rules, HTTP semantics, special behaviour, errors; read at the start of the Design Workflow
```
references/agent-readiness-guidelines.md
```
— 11 LLM analysis categories for AI Agent Readiness (Phase 2)
```
references/ai-readiness-metadata.json
```
— metadata for 69 Spectral AI-readiness rules
```
references/owasp-top-10-metadata.json
```
— metadata for the OWASP-derived API security rules

references/wso2-design-guidelines-metadata.json

— metadata for WSO2 REST design rules

```
references/report-schema.md
```
— JSON report structure documentation

按需读取——无需预先加载所有文件：

```
references/wso2-rest-api-design-guidelines.md
```
— WSO2 7步设计流程、资源分类、URI规则、HTTP语义、特殊行为、错误；在设计工作流开始时读取
```
references/agent-readiness-guidelines.md
```
— AI Agent适配性的11项LLM分析类别（第二阶段）
```
references/ai-readiness-metadata.json
```
— 69项Spectral AI适配性规则的元数据
```
references/owasp-top-10-metadata.json
```
— 基于OWASP的API安全规则的元数据

references/wso2-design-guidelines-metadata.json

— WSO2 REST设计规则的元数据

```
references/report-schema.md
```
— JSON报告结构文档