ecosystem-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🌐 API Domain Ecosystem

🌐 API领域生态系统

Welcome to the

api

domain ecosystem. This directory contains specialized agentic skills for designing, scaling, securing, and evolving Application Programming Interfaces (REST, GraphQL, gRPC).

For Orchestrator Agents (
task-decomposer
,
parallel-planner
): When asked to plan an API-related task, you MUST consult the workflows below. Do not hallucinate steps; map your plan strictly to these available skills in the order defined.

欢迎来到

api

领域生态系统。本目录包含用于设计、扩展、保障安全以及演进应用程序接口（REST、GraphQL、gRPC）的专业化Agent技能。

面向编排Agent（
task-decomposer
、
parallel-planner
）：当需要规划API相关任务时，你必须参考下方的工作流。不得虚构步骤；严格按照定义的顺序，将你的计划映射到这些可用技能上。

🔄 Standard Workflows & Handoffs

🔄 标准工作流与任务交接

1. OpenAPI-First Design Flow

1. OpenAPI优先设计流程

When the user asks to "design a new API", "create endpoints", or "build an API from scratch", execute these skills sequentially:

```
@contract-first-designer
```
-> Designs the OpenAPI/Swagger specification or GraphQL schema.
```
@api-mock-designer
```
-> Generates mock servers and fake data responses based on the contract.
```
@sdk-scaffolder
```
-> Generates client SDKs or typed interfaces (e.g., TypeScript interfaces) from the contract.

当用户提出“设计新API”、“创建端点”或“从零构建API”时，按顺序执行以下技能：

```
@contract-first-designer
```
-> 设计OpenAPI/Swagger规范或GraphQL schema。
```
@api-mock-designer
```
-> 根据契约生成模拟服务器和虚假数据响应。
```
@sdk-scaffolder
```
-> 从契约生成客户端SDK或类型化接口（如TypeScript接口）。

2. API Security & Scale Flow

2. API安全与扩展流程

When the user asks to "secure the API" or "prepare the API for high traffic":

```
@protocol-selector
```
-> Evaluates REST vs. GraphQL vs. gRPC needs if not yet decided.
```
@auth-flow-designer
```
-> Designs OAuth2, JWT, or Session-based authentication and authorization mechanisms.
```
@rate-limit-strategist
```
-> Prevents abuse by designing throttling, rate-limiting, and quota rules.

当用户提出“保障API安全”或“为高流量场景准备API”时：

```
@protocol-selector
```
-> 若尚未确定协议，评估REST、GraphQL与gRPC的适配需求。
```
@auth-flow-designer
```
-> 设计基于OAuth2、JWT或会话的身份认证与授权机制。
```
@rate-limit-strategist
```
-> 通过设计限流、速率限制与配额规则防止滥用。

3. API Evolution Flow

3. API演进流程

When the user asks to "update the API", "release v2", or "change endpoints":

```
@breaking-change-detector
```
-> Analyzes the new contract against the old one to flag backward-incompatible changes.
```
@changelog-generator
```
-> Compiles developer-friendly release notes mapping the API changes.

当用户提出“更新API”、“发布v2版本”或“修改端点”时：

```
@breaking-change-detector
```
-> 对比新旧契约，分析并标记向后不兼容的变更。
```
@changelog-generator
```
-> 编译面向开发者的版本说明，梳理API变更内容。

4. Production Readiness Flow

4. 生产就绪流程

When the user asks to "make the API production-ready" or "add webhooks":

If webhooks/event-driven architecture is needed: use
```
@webhook-architect
```
If monitoring is needed: use
```
@api-observability-planner
```
to define logging, tracing, and metric alerts.

当用户提出“让API具备生产环境就绪能力”或“添加webhooks”时：

若需要webhooks/事件驱动架构：使用
```
@webhook-architect
```
若需要监控：使用
```
@api-observability-planner
```
定义日志、追踪与指标告警。

🧠 Core Philosophy

🧠 核心理念

API development is contract-driven and security-first. Every skill in this domain is programmed to defend against breaking changes for API consumers and ensure robust security boundaries. Never prioritize speed over backward compatibility in a public API environment.

API开发遵循契约驱动与安全优先原则。本领域内的每一项技能都旨在避免对API消费者造成破坏性变更，并确保稳固的安全边界。在公开API环境中，绝不能为了速度而牺牲向后兼容性。

🚀 Installation & Orchestration Instructions

🚀 安装与编排说明

As an AI Agent reading this ecosystem file, you must actively guide the user to install the missing skills for the selected workflow.

To install all skills within this ecosystem at once, you must execute or instruct the user to execute the provided installation script:

bash

python skills/ecosystem-api/scripts/install_all.py

Execution Rule: Do not attempt to perform the tasks of these skills yourself. Your job is to install them and hand off the execution to the appropriate skill, or instruct the user to trigger the newly installed skills in order.

作为读取本生态系统文件的AI Agent，你必须主动引导用户安装所选工作流中缺失的技能。

要一次性安装本生态系统内的所有技能，你必须执行或指导用户执行提供的安装脚本：

bash

python skills/ecosystem-api/scripts/install_all.py

执行规则： 不得尝试自行执行这些技能的任务。你的职责是安装它们，并将执行权交接给对应的技能，或指导用户按顺序触发新安装的技能。