SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场write-provider-skill

write-provider-skill

智能体与模型

查看项目

更新于 10-16 06:27

技能介绍

用途

write-provider-skill 用于指导编写 treg provider skill。Provider skill 是一个由文档构成的 MCP 服务器。MCP 服务器向模型提供工具列表和带类型的参数，但无法为每个平台都发布一个服务器，因此技能以散文形式承载同样的信息：哪些端点重要、参数的真实含义，以及 API 在哪些地方会误导你。第三部分（API 的误导之处）是 MCP 无法提供的，也是几乎全部价值所在。

编写规则

决定内容取舍的规则是：记录那些会产生错误答案却不产生错误的文档。按对智能体的价值排序：

  • 静默错误答案：智能体自信地报告错误结果，单独无法恢复。例如 GA4 中不兼容的维度+指标每行返回 "0" 而非错误，读起来像“没有收入”。
  • 形状错误的错误：错误不描述真实原因，导致重试走偏。例如 GA4 中错误路径返回 Google HTML 404 页面而非 JSON，JSON 解析会抛出无关错误。
  • 无法猜测的标识符：智能体编造 ID 并永远得到 403/404。例如 GA4 需要 properties/123456789；GSC 需要 sc-domain:x.com 对比 https://x.com/。
  • 主机拆分：端点存在但不在绑定的主机上。例如 GA4 Admin API 是 analyticsadmin，工具绑定到 analyticsdata 则返回 404。
  • 能力限制：智能体尝试范围无法完成的工作。例如 GA4 连接是只读的。
  • 端点列表：可在官方文档中找到。

对于最后一行（端点列表），链接到文档即可，不要复述。一个转述 API 参考的技能比一个 URL 更糟——它会过时且更长。

验证协议（不可协商）

技能中的每个端点和每个示例请求体都必须被执行过。不是从文档改编，不是看起来合理——而是实际运行。

scripts/dev-local.sh up
scripts/dev-local.sh cli connections ls          # confirm health + resource_ref
scripts/dev-local.sh cli call <provider> <path>  # always via /call/, never direct

通过 /call/ 调用而非带 token 的 curl：这样可以检验绑定注入、token 刷新和审计追踪，这些正是 treg 缺陷暴露的地方。

将每个端点标记为 ✅ 已验证或 ⚠️ 未验证，并给技能标注日期。允许存在未验证的端点——但不允许未标记的端点。

当出现 404 时读取审计日志。它记录确切的上游 URL，可以捕获终端输出隐藏的客户端路径篡改：

sqlite3 treg-dev.db "select method,path,status_code from callrecord order by id desc limit 5"

这就是发现下面 zsh :r 缺陷的方式：终端显示了一个看似合理的 Google 错误，审计日志显示请求发往了 ...123456789unRealtimeReport。

写入端测试

读取端点：可自由调用。写入端点会向真实账户发布真实内容且不可逆。在任何创建内容或花钱的 POST/PUT/DELETE 之前：

  • 从人类获取明确指定的目标（一次性账户、沙盒广告账户）
  • 获取每个 provider 的明确许可
  • 如果两者都不存在，将端点标记为 ⚠️ 未验证，并根据 API 参考记录

绝不要为了满足复选框而向生产账户发布。

技能结构

遵循以下顺序——它匹配智能体在时间压力下实际阅读的方式：

  • frontmatter：name + description（description = 触发器；列出用户会说的词）
  • # <Platform> via treg
    • 一行：你通过 treg 的代理调用 X，你从不持有凭证
    • "All examples verified live on <date>"
  • ## Setup (once per team) — 连接命令，你获得什么能力
  • ## Which <resource> to use — 如何读取 id，绝不猜测
  • ## The endpoints — 表格：path | method | purpose | verified?
  • ## Common jobs — 4-6 个真实任务，完整可运行的请求体
  • ## Reading the response — 形状陷阱（位置数组、字符串而非数字、时区）
  • ## Pitfalls — 静默错误答案列表。最有价值的部分。
  • ## Full documentation — 链接出去

跨 provider 反复出现的陷阱类别

构建新技能时明确检查每一项。已在 GA4 确认；在其他平台预期但未确认，直到测试。

  • 主机拆分——是否存在与数据 API 不同主机名的管理/管理 API？工具的 base_url 绑定一个主机；另一个无法通过 /call/ 访问。预计在 Google Ads（googleads 对比 googleadsapi 表面）和 Meta（graph 对比 business）上出现。
  • 资源 id 格式——确切前缀、确切编码。从 treg connections ls → resource_ref 读取。如果为空，treg connections resources <id> 然后 treg connections use。
  • 位置响应数组——表头和值按索引匹配，而非按名称。
  • 数字作为字符串——算术前先转换。
  • 时区/货币——报告以属性的时区呈现。在解释“今天”之前从响应中读取它。
  • 静默截断——默认行限制、高基数维度的 (other) 桶、看起来像完成的分页令牌。
  • Shell 引用——在 zsh 中，$VAR:runReport 触发 :r 历史修饰符并静默损坏路径。使用 ${VAR}:runReport。适用于任何带 :action 路径后缀的 API。
  • 范围与能力——连接实际授予的内容（treg connections ls → scopes, capabilities, missing_capabilities），而非平台提供的内容。

同时记录 treg 摩擦

这个练习同时是 treg 测试。当智能体可能对 treg 自身接口做出合理错误猜测时，记录下来——那些是产品缺陷，不是技能内容。目前发现：

  • treg connections list 无效；子命令是 ls
  • treg connections resources 接受数字 id，而非 provider 名称

检查清单

  • 通过真实 OAuth 连接；connections ls 显示 health: ok
  • 每个端点通过 /call/ 执行；每个标记为已验证/未验证
  • 故意探测静默错误答案（错误字段名、不兼容组合）
  • 确认连接实际具有的能力
  • 检查主机拆分
  • 写入端点要么已授权+测试，要么标记为未验证
  • 链接出去而非复述参考
  • treg 摩擦与平台摩擦分开记录