integrate-context-matic

API 集成

当用户要求集成第三方 API，或实现任何涉及外部 API 或 SDK 的功能时，请遵循此工作流。不要依赖自身知识来判断可用的 API 或其能力 —— 始终使用 context-matic MCP 服务。

适用场景

当用户出现以下情况时，应用此技能：

• 要求集成第三方 API
• 希望为外部服务添加客户端或 SDK
• 请求实现依赖外部 API 的功能
• 提到某个具体 API（例如 PayPal、Twilio）以及实现或集成

工作流

1. 确保准则与技能已存在

1a. 检测项目的主要语言

在检查准则或技能之前，先通过检查工作区来识别项目的主要编程语言：

文件 / 模式	语言
*.csproj、*.sln	csharp
包含 "typescript" 依赖的 package.json 或 .ts 文件	typescript
requirements.txt、pyproject.toml、*.py	python
go.mod、*.go	go
pom.xml、build.gradle、*.java	java
Gemfile、*.rb	ruby
composer.json、*.php	php

在后续所有需要 language 的步骤中，都使用检测到的语言。

1b. 检查已有的准则与技能

通过在工作区中查找相关文件，检查是否已为此项目添加准则和技能。

• {language}-conventions 是由 add_skills 生成的技能。
• {language}-security-guidelines.md 和 {language}-test-guidelines.md 是由 add_guidelines 生成的语言专属准则文件。
• update-activity-workflow.md 是由 add_guidelines 生成的工作流准则文件（它不是语言专属的）。
• 请分别独立检查这些文件。不要因为其中一组存在就认定另一组也已存在。
• 如果此项目缺少任何必需的准则文件： 调用 add_guidelines。
• 如果项目对应语言缺少 {language}-conventions： 调用 add_skills。
• 如果所有必需的准则文件和 {language}-conventions 都已存在： 跳过此步骤并继续执行步骤 2。

2. 发现可用的 API

调用 fetch_api 来查找可用的 API —— 始终从这里开始。

• 始终使用步骤 1a 中检测到的语言提供 language 参数。
• 始终提供 key 参数：传入用户请求中的 API 名称/键（例如 "paypal"、"twilio"）。
• 如果用户未提供 API 名称/键，询问他们想要集成哪个 API，然后用该值调用 fetch_api。
• 该工具在精确匹配时只返回匹配的 API；在没有精确匹配时返回完整的 API 目录（名称、描述和 key）。
• 根据名称和描述，识别与用户请求匹配的 API。
• 在继续之前，提取用户所请求 API 的正确 key。此 key 将用于后续所有与该 API 相关的工具调用。

如果请求的 API 不在列表中：

• 告知用户此 API 当前在此插件（context-matic）中不可用，并停止。
• 向用户请求有关如何继续该 API 集成的指导。

3. 获取集成指导

• 为 ask 提供：language、key（来自步骤 2）以及你的 query。
• 将复杂问题拆分为更小、更聚焦的查询以获得最佳结果：
  • "我该如何进行身份验证？"
  • "我该如何创建一笔支付？"
  • "有哪些速率限制？"

4. 查找 SDK 模型与端点（按需）

这些工具只返回定义 —— 它们不会调用 API 或生成代码。

• model_search —— 查找模型/对象定义。
  • 提供：language、key，以及精确或部分区分大小写的模型名称作为 query（例如 availableBalance、TransactionId）。
• endpoint_search —— 查找端点方法的详细信息。
  • 提供：language、key，以及精确或部分区分大小写的方法名称作为 query（例如 createUser、get_account_balance）。

5. 记录里程碑

每当以下某一项在代码或基础设施中切实达成时（而不仅仅是提及或计划），调用 update_activity（并传入相应的 milestone）：

里程碑	何时传入
sdk_setup	项目中已安装 SDK 包（例如 npm install、pip install、go get 已运行并成功）。
auth_configured	API 凭据已明确写入项目的运行时环境（例如存在于 .env 文件、密钥管理器或配置文件中）并且在实际代码中被引用。
first_call_made	首次 API 调用代码已编写并执行
error_encountered	开发者报告了 bug、错误响应或调用失败
error_resolved	已应用修复，并确认 API 调用正常工作

检查清单

• 已检测项目的首要语言（步骤 1a）
• 如果缺少指南文件，则已调用 add_guidelines，否则跳过
• 如果缺少 {language}-conventions，则已调用 add_skills，否则跳过
• 已使用正确的 language 和 key（API 名称）调用 fetch_api
• 已为所请求的 API 确定正确的 key（如果未找到，则告知用户）
• 仅在代码/基础设施中切实达成里程碑时才调用 update_activity——绝不因问题、搜索或工具查找而调用
• 在每个集成里程碑处已使用相应的 milestone 调用 update_activity
• 已使用 ask 获取集成指南和代码示例
• 已按需使用 model_search / endpoint_search 获取 SDK 详细信息
• 每次修改代码后项目均可编译

说明

• 未找到 API：如果 fetch_api 中缺少某个 API，不要猜测 SDK 的用法——应告知用户该 API 当前在此插件中不可用，并停止操作。
• update_activity 与 fetch_api：fetch_api 是 API 发现，不是集成——不要在调用它之前调用 update_activity。