affaan-m/api-connector-builder

API 连接器构建器

当任务需要添加仓库原生的集成接口，而非仅通用 HTTP 客户端时使用此工具。

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

• 连接器布局
• 配置模式
• 认证模型
• 错误处理
• 测试风格
• 注册/发现机制

使用时机

• "为此项目构建 Jira 连接器"
• "按照现有模式添加 Slack 提供商"
• "为此 API 创建新集成"
• "构建符合仓库连接器风格的插件"

约束条件

• 若仓库已有集成架构，不得自行发明新架构
• 不得仅从供应商文档入手；应优先参考仓库内现有连接器
• 若仓库需要注册机制、测试和文档，不得仅停留在传输代码层面
• 若仓库有更新的当前模式，不得盲目复制旧连接器

工作流程

1. 学习内部风格

检查至少 2 个现有连接器/提供商，并映射：

• 文件布局
• 抽象边界
• 配置模型
• 重试/分页约定
• 注册钩子
• 测试夹具和命名规范

2. 缩小目标集成范围

仅定义仓库实际需要的接口：

• 认证流程
• 关键实体
• 核心读写操作
• 分页和速率限制
• Webhook 或轮询模型

3. 按仓库原生层次构建

典型分层：

• 配置/模式
• 客户端/传输层
• 映射层
• 连接器/提供商入口
• 注册机制
• 测试

4. 对照源模式验证

新连接器应在代码库中显得自然，而非从不同生态导入。

参考模板

提供商风格

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

连接器风格

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