api-connector-builder

用途

API Connector Builder 用于在目标代码仓库中新增一个“仓库原生”的集成面（integration surface），而不是一个通用的 HTTP 客户端。它的核心判断标准是：新连接器应当与宿主仓库已有的集成模式完全一致，使其在代码库中看起来自然、显而易见，而不是从其他生态直接搬来的产物。

主要能力

该技能围绕“匹配宿主仓库模式”展开，覆盖以下方面：

连接器布局（connector layout）
配置 schema（config schema）
认证模型（auth model）
错误处理（error handling）
测试风格（test style）
注册/发现接线（registration/discovery wiring）

使用方式

触发场景

“为这个项目构建一个 Jira 连接器”
“按照现有模式添加一个 Slack provider”
“为这个 API 创建一个新的集成”
“构建一个匹配仓库连接器风格的插件”

工作流程

学习内部风格：检查至少 2 个已有的连接器/provider，梳理文件布局、抽象边界、配置模型、重试/分页约定、注册钩子、测试夹具与命名。
收窄目标集成范围：只定义仓库真正需要的接口面，包括认证流程、关键实体、核心读写操作、分页与速率限制、webhook 或轮询模型。
按仓库原生分层构建：典型切片包括配置/schema、客户端/传输层、映射层、连接器/provider 入口、注册、测试。
对照源模式验证：新连接器应当与代码库风格一致，而非来自不同生态。

参考结构形态

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

适用场景

适用于需要在已有仓库中新增集成、且该仓库已经存在一套明确的连接器/provider 模式的情况。典型如为项目添加 Jira 连接器、按现有模式新增 Slack provider、为某 API 创建新集成、构建符合仓库风格的插件。

限制与护栏

当仓库已有集成架构时，不要发明新的集成架构。
不要仅从厂商文档出发；应先从仓库内已有的连接器入手。
如果仓库期望注册接线、测试和文档，不要只停留在传输层代码。
如果仓库已有更新的当前模式，不要照搬旧连接器。

质量检查清单

匹配仓库内已有的集成模式
存在配置校验
认证与错误处理明确
分页/重试行为遵循仓库规范
注册/发现接线完整
测试与宿主仓库风格一致
如仓库有要求，更新文档/示例

技能介绍

用途