核心用法
Basecamp Skill 是 Maton 平台提供的 Basecamp 4 API 统一网关代理，通过 gateway.maton.ai 中转请求，自动处理 OAuth 2.0 认证与账户 ID 注入。用户需先在 Maton 控制台创建 Basecamp 连接并完成授权，随后使用统一的 MATON_API_KEY 调用所有接口。
关键操作流程
1. 认证管理：在 ctrl.maton.ai 创建/管理 OAuth 连接，获取 connection_id 用于多账户场景
2. 统一网关：所有请求发往 https://gateway.maton.ai/basecamp/{resource}.json，路径必须以 .json 结尾
3. 项目发现：通过 /projects.json 获取项目列表，检查 dock 字段确认可用工具（todoset、message_board、schedule、vault、chat）
4. 资源操作：
- 项目：CRUD 操作、成员管理、模板创建
- 待办：todolist 与 todo 的完整生命周期管理（创建、分配、完成/取消完成）
- 消息：Message Board 公告发布与更新
- 日程：会议与事件安排，支持参与者管理
- 文档：Vault 中 HTML 文档与文件上传管理
- 聊天：Campfire 群聊消息发送
- 评论：所有 recording（可记录内容）的评论系统
技术特性
- 自动注入 account_id 和 OAuth token，无需手动管理 Basecamp 凭据
- 支持多连接管理，通过
Maton-Connection头部指定特定账户 - Link Header 分页，禁止手动构造分页 URL
- 统一错误码：400（连接缺失）、401（API Key 无效）、429（限流）、507（账户限额）
显著优点
| 维度 | 优势 |
|------|------|
| **认证简化** | 托管 OAuth 免去 token 刷新与存储负担，单点登录体验 |
| **全功能覆盖** | 完整映射 Basecamp 4 API，从项目创建到 granular 的 todo 完成状态均可操作 |
| **多账户支持** | 通过 connection_id 灵活切换不同 Basecamp 账户，适合代理/多团队场景 |
| **开发友好** | 提供 Python、JavaScript 等多语言示例，环境变量一键配置 |
| **安全代理** | 真实 token 不暴露给终端用户，降低凭据泄露风险 |
潜在局限与风险
功能边界
- 网关依赖：所有流量必须经过 Maton 网关，存在单点故障与服务可用性绑定
- 实时性限制：非 WebSocket 实时推送，需轮询获取更新（如 Campfire 消息）
- 上传限制：文档/文件上传需额外确认大小限制与存储配额（文档未明确说明）
- 模板能力有限：仅支持从现有模板创建项目，不支持模板本身的 CRUD 管理
运营风险
- 供应商锁定：OAuth 连接与 API 访问深度绑定 Maton 平台，迁移成本较高
- 速率限制：~50 请求/10秒/IP，高频自动化场景需实现指数退避重试
- 文档同步延迟：依赖 Maton 维护 Basecamp API 变更的同步，可能存在版本滞后
适合人群
- 团队协作自动化：需要批量创建项目、同步待办状态、自动化日程安排的团队管理员
- 集成开发者：构建 Basecamp 与内部系统（CRM、BI、IM）双向集成的工程师
- 多账户运营者：代理多家客户或管理多个组织的 Basecamp 工作空间的服务商
- 无后端场景：希望快速调用 Basecamp API 而不自建 OAuth 服务的轻量级应用
常规风险提醒
- 环境变量注入：生产环境需确保
MATON_API_KEY的安全存储，避免日志泄露 - 连接失效处理：OAuth token 可能因用户撤销或过期导致 400 错误，需监控连接状态
- 数据删除不可逆：
DELETE操作直接移至 trash，部分资源无硬删除确认，需谨慎测试 - 并发编辑冲突：Basecamp 本身无乐观锁机制，高频并发更新可能产生覆盖
- 网关迁移注意：若 Maton 调整网关域名或认证方式，需关注官方变更通知