核心用法
CompanyCam Skill 是 Maton 平台提供的托管式 OAuth 代理服务，面向承包商和建筑行业用户，封装了 CompanyCam 官方 API 的完整功能。用户仅需配置 MATON_API_KEY 环境变量，即可通过 Maton 的代理端点 (api.maton.ai/companycam/v2) 调用原生的项目、照片、用户、标签、分组、文档及 Webhook 管理能力。
核心工作流包含三步：1) 获取 Maton API Key；2) 创建并激活 CompanyCam OAuth 连接（通过返回的 URL 完成授权）；3) 使用标准 REST 风格调用资源端点。支持多连接管理（通过 Maton-Connection 头区分），所有请求自动注入 OAuth Token，无需开发者处理 Token 刷新与存储。
API 覆盖度完整：项目 CRUD、照片上传（支持 URL 引用的外部图片）、Geo 坐标与时间戳标记、标签与分组体系、评论与文档管理、检查清单模板、以及基于事件的 Webhook 订阅。特别针对施工场景优化，如项目归档/恢复、协作者管理、按时间/人员/标签多维过滤照片等。
显著优点
1. 零 OAuth 基础设施：开发者无需实现授权服务器、Token 刷新或密钥轮转，Maton 托管层自动处理 CompanyCam 的 OAuth 2.0 流程。
2. 多租户友好：单 Maton 账号可创建多个 CompanyCam 连接，通过 Header 灵活路由，适合代运营或集团型企业场景。
3. 全功能覆盖：完整支持 CompanyCam V2 API，包括照片批量标签、检查清单模板实例化、文档上传等高级功能。
4. 速率透明：明确的限速策略（GET 240/分钟，写操作 100/分钟），便于客户端实现退避重试。
潜在缺点与局限性
1. 网络依赖：必须保持与 api.maton.ai 及 CompanyCam 原服务的网络连通，无法离线使用。
2. 数据隐私边界：照片与项目数据需流经 Maton 代理层，对极度敏感的客户需评估第三方托管合规性。
3. 速率限制瓶颈：高频写入场景（如批量导入历史照片）可能触发 429 限制，需设计异步队列。
4. 功能绑定：深度依赖 CompanyCam 原生功能，若官方 API 变更或下线，Skill 同步受影响。
适合人群
- 承包商与施工企业：需要数字化管理工地照片、进度文档、检查清单的现场团队。
- SaaS 集成商：为建筑行业客户开发项目管理工具，需快速接入 CompanyCam 而无需自建 OAuth。
- 运维与代运营方：管理多个 CompanyCam 企业账号，需统一 API 入口。
常规风险
- 密钥泄露风险：
MATON_API_KEY泄露将导致关联的 CompanyCam 数据暴露，需严格遵循环境变量管理最佳实践。 - 误操作数据丢失：删除项目、照片为不可逆操作（虽有归档机制），建议开启 Webhook 实时备份关键事件。
- OAuth 会话过期：长期未使用的连接可能进入失效状态，需监控
status字段并设计重连逻辑。