How we chose APIs for WorkBuddy我们如何评选 WorkBuddy API
This is a use-case ranking, not a universal vendor benchmark. WorkBuddy already organizes agent capabilities and workflows; an external API is valuable only when it closes a concrete gap: fresh information, authoritative business state, or a controlled external action. We prioritized structured responses, explicit authentication, narrow resource scopes, stable documentation, testable failures, and useful read-only modes.
The official WorkBuddy handbook documents capabilities, workflows, agent documentation, and activity summaries through its MCP gateway. That makes API selection a governance question as much as a compatibility question. A callable tool still needs credential isolation, input validation, result limits, human approval for consequential writes, and an observable outcome.
这是一份按场景排序的榜单，不是宣称某家厂商在所有方面都更强。WorkBuddy 本身用于组织智能体能力与工作流；只有当外部 API 能补齐明确缺口——最新信息、权威业务状态或受控外部操作——才值得接入。我们重点考察结构化响应、明确认证、细粒度资源范围、稳定文档、可测试的失败路径，以及可用的只读模式。
WorkBuddy 官方手册记录了通过 MCP 网关使用能力、工作流、智能体文档与活动摘要的方式。因此，选择 API 不只是兼容性问题，也是治理问题。工具即使可以调用，仍需做好凭证隔离、输入校验、结果限额、高影响写入审批与结果核验。
The 6 best APIs to use with WorkBuddy适合 WorkBuddy 的 6 类最佳 API
QVeris API & MCP
Best for cross-provider tool discovery跨服务商工具发现首选Use QVeris when WorkBuddy needs several live data capabilities but you do not want a separate adapter for every provider. The practical pattern is discover, inspect, then call: find a relevant operation, review its parameters and source, and execute only after the input is bounded. This fits research, enrichment, market monitoring, location, and other evidence-led tasks.当 WorkBuddy 需要多种实时数据能力，而你不想为每家服务商维护独立适配器时，可使用 QVeris。实用模式是“发现—检查—调用”：先找出相关操作，核对参数与来源，再在输入范围明确后执行。它适合研究、数据补全、市场监测、位置查询等证据驱动任务。
Read the QVeris API documentation阅读 QVeris API 文档 · inspect available tools检查可用工具
Google Workspace APIs
Best for document-centered operations文档型办公流程首选Drive, Docs, Sheets, and Calendar APIs can give WorkBuddy structured access to the material where teams plan and report. Strong workflows include summarizing a named folder, extracting decisions from a document set, preparing a meeting brief, or writing an approved table into a designated sheet. Use separate OAuth scopes and resource allowlists rather than broad account access.Drive、Docs、Sheets 与 Calendar API 可让 WorkBuddy 结构化访问团队规划与汇报资料。典型流程包括汇总指定文件夹、从文档集中提取决策、准备会议简报，或把获批表格写入指定 Sheet。应拆分 OAuth scope，并使用资源白名单，而不是开放整个账户。
Review official Google Workspace developer documentation查看 Google Workspace 官方开发文档.
Slack Web API
Best for team communication团队沟通首选Slack is useful when the workflow begins or ends with a team conversation: collect messages from approved channels, produce a cited digest, draft a response, or post an approved status update. Read and write are different trust classes. Keep posting behind confirmation, avoid private-message access unless essential, and include source permalinks in summaries.当工作流从团队对话开始或以团队通知结束时，Slack 很有价值：读取获准频道、生成带来源的摘要、拟写回复，或发布已批准的状态更新。读取和写入属于不同信任等级；发消息应保留确认，不必要时不要访问私信，摘要中应附原消息链接。
Linear GraphQL API
Best for structured task workflows结构化任务流程首选Linear turns project state into typed issues, projects, cycles, and comments. WorkBuddy can summarize overdue work, connect meeting decisions to existing issues, prepare a triage queue, or create a draft issue after approval. Search before creation to avoid duplicates, preserve the original requester and evidence, and constrain writes to named teams.Linear 可把项目状态表示为类型明确的 Issue、Project、Cycle 与评论。WorkBuddy 可汇总逾期任务、把会议决策关联到现有 Issue、准备分流队列，或经批准后创建草稿任务。创建前应先搜索防止重复，并保留原始请求者与证据，同时把写入限制在指定团队。
Inspect Linear's official GraphQL API reference查看 Linear 官方 GraphQL API 参考.
Airtable Web API
Best for lightweight operational data轻量运营数据首选Airtable suits teams whose operational source of truth is a structured base rather than a full application database. WorkBuddy can retrieve records with formulas, prepare weekly rollups, identify incomplete entries, and propose normalized updates. Lock the integration to named bases and tables, validate field types, paginate results, and treat attachments as separate untrusted inputs.如果团队的运营事实来源是结构化 Base，而不是完整应用数据库，Airtable 很合适。WorkBuddy 可按公式检索记录、整理周报、识别缺失项并提出规范化更新。接入应限定在指定 Base 与 Table，校验字段类型，处理分页，并把附件视作独立的不可信输入。
Read Airtable's official Web API introduction阅读 Airtable Web API 官方介绍.
Sentry API
Best for workflow observability工作流可观测性首选Sentry helps when WorkBuddy supports engineering or business processes that must distinguish a completed call from a successful outcome. The API can retrieve issues, events, releases, and project health for diagnosis and reporting. Start with read-only projects, redact personal data, and link every generated conclusion to the underlying event or issue.当 WorkBuddy 支持工程或业务流程，且必须区分“调用完成”和“结果成功”时，Sentry 很有帮助。其 API 可获取 Issue、Event、Release 与项目健康信息，用于诊断和报告。建议从项目只读权限开始，脱敏个人数据，并让每项结论都能回链到对应事件或 Issue。
Review the official Sentry API documentation查看 Sentry API 官方文档.
Three useful WorkBuddy workflow recipes三种实用的 WorkBuddy 工作流组合
| Outcome目标 | API stackAPI 组合 | Human checkpoint人工检查点 |
|---|---|---|
| Weekly market brief每周市场简报 | QVeris + Google Docs | Approve sources and final narrative审核来源与最终表述 |
| Meeting-to-execution从会议到执行 | Google Docs + Linear + Slack | Confirm owners and issue creation确认负责人和任务创建 |
| Incident digest故障摘要 | Sentry + Slack + Linear | Approve external update and remediation tasks批准外部通知与修复任务 |
Why combinations beat one “universal” API为什么组合优于“万能”API
A dependable workflow separates evidence, state, action, and notification. For example, QVeris may collect current evidence, Google Docs holds the approved narrative, Linear tracks the work, and Slack communicates the result. Each boundary can use a different credential and approval rule. This is easier to audit than giving one connector broad access to everything.可靠工作流应把证据、状态、操作与通知分开。例如，QVeris 收集最新证据，Google Docs 保存获批表述，Linear 跟踪任务，Slack 负责通知。每条边界都可使用不同凭证和审批规则，比让一个连接器获得全局权限更容易审计。
A safe rollout pattern for WorkBuddy APIsWorkBuddy API 的安全上线模式
1. Define one outcome1. 定义单一结果
Write the expected input, output, source of truth, and success evidence before choosing an API.选 API 前写清输入、输出、事实来源与成功证据。
2. Start read-only2. 从只读开始
Grant only named resources and operations. Keep secrets outside prompts and shared workflow text.只开放指定资源与操作；密钥不得进入提示词或共享工作流文本。
3. Test negative paths3. 测试异常路径
Exercise expired credentials, rate limits, empty results, partial data, timeouts, and denied actions.测试凭证过期、限流、空结果、数据不全、超时与拒绝操作。
4. Verify the outcome4. 核验业务结果
Do not treat HTTP success as task success. Confirm the record, message, or artifact exists as intended.不要把 HTTP 成功等同于任务成功；需确认记录、消息或产物符合预期。
Decision checklist决策清单
- Does the API close a repeated capability gap rather than duplicate existing WorkBuddy context?该 API 是否补齐重复出现的能力缺口，而不是重复 WorkBuddy 已有上下文？
- Can authentication be limited by operation, resource, team, workspace, or project?认证能否按操作、资源、团队、工作区或项目收敛？
- Are responses structured, bounded, attributable, and independently verifiable?响应是否结构化、有边界、可归因且可独立核验？
- Can reads and writes use separate credentials and approval policies?读取和写入能否使用不同凭证与审批策略？
- Is there a timeout, retry, deduplication, rate-limit, and disable strategy?是否具备超时、重试、去重、限流与停用策略？
- Will logs capture tool identity, arguments, decision, result status, and latency without unnecessary personal data?日志能否记录工具身份、参数、决策、结果状态与延迟，同时避免无必要的个人数据？
Frequently asked questions常见问题
What is the best API to add to WorkBuddy first?WorkBuddy 最先应接入哪个 API？
Start with the narrowest API that closes a repeated information gap. QVeris is a strong first layer when you need multiple current data capabilities; Google Workspace is more appropriate when the source of truth is already in team documents.从能补齐重复信息缺口的最小 API 开始。需要多种实时数据能力时，QVeris 是合适的第一层；如果事实来源已经在团队文档中，则优先考虑 Google Workspace。
Does WorkBuddy support MCP tools?WorkBuddy 支持 MCP 工具吗？
WorkBuddy's official handbook documents capabilities and workflows exposed through its MCP gateway. Exact availability depends on the installed version and configuration, so verify the current handbook and inspect the exposed tool surface before granting access.WorkBuddy 官方手册记录了通过 MCP 网关暴露的能力与工作流。具体可用性取决于安装版本和配置，因此授权前应核对当前手册并检查实际暴露的工具面。
How many APIs should a WorkBuddy workflow use?一个 WorkBuddy 工作流应使用多少个 API？
There is no fixed number. Two or three specialized APIs are often enough for one outcome. The stack is too broad when tools overlap, routing becomes unreliable, permissions are hard to explain, or failure diagnosis requires checking many unrelated systems.没有固定数量。一个目标通常用两到三个专用 API 就够了。当工具重叠、路由不稳定、权限难以解释，或故障诊断要检查很多无关系统时，技术栈就过宽了。
Should WorkBuddy be allowed to write through APIs automatically?是否应允许 WorkBuddy 自动通过 API 写入？
Only for narrow, reversible, well-tested actions with clear deduplication. Publishing, deletion, payments, identity changes, external messages, and production changes should retain explicit approval and post-action verification.只应对范围窄、可逆、充分测试且具有去重机制的操作自动写入。发布、删除、支付、身份变更、外部消息与生产变更应保留明确审批，并在操作后核验。
Build a smaller, verifiable WorkBuddy stack构建更精简、可验证的 WorkBuddy 技术栈
Choose one missing capability, inspect the tool contract, test with representative data, and expand only after the whole outcome is observable.先选择一个缺失能力，检查工具契约，用代表性数据测试；只有完整结果可观测后再扩大范围。