api-connector-builder

name	api-connector-builder
description	通过精确匹配目标仓库现有的集成模式，构建新的 API 连接器 (Connector) 或提供者 (Provider)。当需要增加一个集成点而不发明第二套架构时使用。
origin	ECC direct-port adaptation
version	1.0.0

API 连接器构建器 (API Connector Builder)

当任务是添加仓库原生的集成界面，而不仅仅是一个通用的 HTTP 客户端时，请使用此技能。

关键点在于匹配宿主仓库的既有模式：

• 连接器布局 (Connector layout)
• 配置模式 (Config schema)
• 认证模型 (Auth model)
• 错误处理 (Error handling)
• 测试风格 (Test style)
• 注册与发现机制 (Registration/discovery wiring)

何时使用

• “为此项目构建一个 Jira 连接器”
• “按照现有模式添加一个 Slack 提供者 (Provider)”
• “为此 API 创建一个新的集成点”
• “构建一个匹配该仓库连接器风格的插件”

准则

• 当仓库已有集成架构时，不要发明新的集成架构。
• 不要仅依赖厂商提供的文档；首先参考仓库内现有的连接器。
• 如果仓库期望包含注册关联、测试和文档，不要仅仅停留在传输层代码的编写。
• 如果仓库有更新的当前模式，不要生搬硬套旧连接器的做法。

工作流

1. 学习项目风格

检查至少 2 个现有的连接器/提供者，并理清以下内容：

• 文件布局
• 抽象边界
• 配置模型
• 重试与分页约定
• 注册钩子 (Registry hooks)
• 测试固件 (Test fixtures) 与命名规范

2. 明确目标集成范围

仅定义仓库实际需要的界面：

• 认证流 (Auth flow)
• 关键实体
• 核心读/写操作
• 分页与速率限制 (Rate limits)
• Webhook 或轮询模型

3. 构建仓库原生的各层级

典型的切片包括：

• 配置/模式 (Config/Schema)
• 客户端/传输层 (Client/Transport)
• 映射层 (Mapping layer)
• 连接器/提供者入口点
• 注册关联
• 测试

4. 针对原始模式进行验证

新的连接器在代码库中应该显得顺理成章，而不是看起来像从不同的生态系统中搬运过来的。

参考形态

提供者 (Provider) 风格

providers/
  existing_provider/
    __init__.py
    provider.py
    config.py

连接器 (Connector) 风格

integrations/
  existing/
    client.py
    models.py
    connector.py

TypeScript 插件风格

src/integrations/
  existing/
    index.ts
    client.ts
    types.ts
    test.ts

质量检查清单

• 匹配仓库内现有的集成模式
• 存在配置验证逻辑
• 认证和错误处理是显式的
• 分页/重试行为遵循仓库规范
• 注册/发现机制关联完整
• 测试镜像了宿主仓库的风格
• 如果仓库有要求，文档/示例已同步更新

相关技能

• backend-patterns
• mcp-server-patterns
• github-ops