波场指南

llms.txt、.well-known与Agent Skills:TronSave如何向AI智能体介绍自己

作者 TronSave 发布于 9 分钟阅读
本页目录

更新:2026年11月7日。MCP与OAuth细节已对照线上服务器(版本1.5.1)核实。

AI智能体进入一个网站时,面临的问题和新来的开发者一样:这是什么、我能调用什么、该如何认证?到2026年,已有一小套约定俗成的文件专门回答这些问题:llms.txt、几个/.well-known/描述文件,以及一份agent skills清单。TronSave全部都有发布。本文逐一介绍每个文件的内容、存在的理由,以及这些文件都无法强制执行的那一条规则。

llms.txt:给人读的摘要

llms.txt放在网站根目录,它对语言模型的作用,就像一份好的README对开发者的作用:先用一段话说明这是什么,再列出精选链接,每个链接附一句说明。它是Markdown而不是schema,这正是关键——它是用来阅读的,而不是用来解析的。

TronSave的llms.txt分为四部分:一行产品摘要;关键页面——首页、市场、工具、FAQ,每个页面都说明里面实际有什么;开发者与AI智能体板块,链接到API参考、API目录、MCP服务器卡片、agent skills索引和认证文档;以及法律信息:条款、隐私和风险提示。

这里真正有用的原则是“精选”。sitemap列出每一个URL;llms.txt只列出最重要的十个,并说明原因。如果您的文件需要滚动条,它就已经失去了作用。

.well-known目录

llms.txt是写给人看的文字,/.well-known/则是机器可读的。共有五个文件,各自回答一个不同的问题:

文件 标准 回答的问题
api-catalog RFC 9727 这里有哪些API?它们的描述在哪里?
oauth-protected-resource RFC 9728 受保护的资源是什么?凭证如何传递?
mcp/server-card.json MCP MCP服务器在哪里?用什么传输方式和认证方式?
agent-skills/index.json agentskills.io 智能体可以加载哪些打包好的技能(skills)?
security.txt RFC 9116 发现漏洞时该联系谁?

api-catalog:机器与人的分工

RFC 9727定义了一种linkset:每个API对应一个锚点(anchor),后面跟着描述它的链接。TronSave发布了两个锚点——REST API v2和MCP端点,每个都同时带有service-desc和service-doc:

{
  "linkset": [
    {
      "anchor": "https://api.tronsave.io/v2",
      "service-desc": [ { "href": ".../api-reference.md",  "type": "text/markdown" } ],
      "service-doc":  [ { "href": ".../api-reference",     "type": "text/html"     } ]
    },
    {
      "anchor": "https://mcp.tronsave.io/mcp",
      "service-desc": [ { "href": ".../mcp/server-card.json", "type": "application/json" } ],
      "service-doc":  [ { "href": ".../api-reference/mcp",    "type": "text/html"        } ]
    }
  ]
}

价值就在于这种区分。service-doc是给人阅读的HTML页面;service-desc是机器可读的描述——这里REST参考用Markdown,MCP卡片用JSON。智能体沿着service-desc走,完全跳过营销页面的外壳。

oauth-protected-resource:API密钥优先,MCP用OAuth

RFC 9728元数据通常与OAuth部署配套。TronSave的REST API本身没有OAuth流程——主要凭证是API密钥或钱包签名——但tronsave.io仍然发布了这个描述文件:它写明了资源、授权服务器和scopes,指向文档,并说明bearer凭证放在请求头中,旁边还有对应的oauth-authorization-server元数据。查找这些文件的客户端会得到答案,而不是404。MCP服务器更进一步:自2026年11月7日起,mcp.tronsave.io为其https://mcp.tronsave.io/oauth/mcp端点提供真正的OAuth登录,拥有自己的受保护资源元数据和授权服务器(带PKCE的授权码、刷新令牌以及客户端注册端点)。Claude和Cursor等应用正是这样连接的:用户在TronSave页面上用API密钥或钱包签名登录,此后应用即完成认证。

auth.md:非OAuth服务的坦诚答案

由于REST API没有可供发现的OAuth流程,真正的认证说明写在一个独立完整的auth.md里。它在真正能为集成者节省时间的地方写得非常具体:

  • REST API通过小写的apikey请求头接收您的密钥。
  • MCP服务器通过authorization请求头、使用ApiKey方案接收密钥。
  • TRON钱包签名是第三种方式——文档明确说明,您永远不需要发送私钥,只需发送签名。

前两条是一个真实的陷阱:同一个凭证,根据调用的接口不同,要用两个不同的请求头和两种不同的大小写。把它写清楚,就是五分钟完成集成和一下午不停遇到401的区别。

这个文件也坦承了不存在的东西:没有可通过程序获取API密钥的OAuth动态注册端点(MCP服务器另行提供的OAuth登录有自己的客户端应用注册端点),因此它说明了人工获取密钥的方式——在网站上连接钱包,或使用Telegram机器人。随后一个agent_auth块以结构化形式概括同样的信息:身份类型为匿名,凭证类型为api_key,并附上注册文档链接。

MCP服务器卡片

这是TronSave MCP服务器的精简描述文件:名称和版本、传输方式(http-streamable)及其端点和方法、声明tools、resources和prompts的能力块(每项都带listChanged)、两种受支持的认证方案及确切的请求头格式,以及快速入门和文档的链接。

声明您不具备的能力并不是凑数。知道没有resources或prompts的智能体,就不会再去找它们。

agent skills清单

这是最新的一层。agent-skills/index.json遵循agentskills.io的发现schema,发布了一个技能tronsave-api,类型为skill-md——一份智能体可以作为工作指令加载的Markdown文档:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "tronsave-api",
      "type": "skill-md",
      "url": "https://tronsave.io/.well-known/agent-skills/tronsave-api/SKILL.md",
      "digest": "sha256:bc8a8647...9141b"
    }
  ]
}

请注意digest。清单中包含技能文件的SHA-256,客户端可以借此验证自己获取的正是网站想要发布的内容。技能是智能体会照着执行的指令,因此值得做完整性校验,而营销页面从来不需要这样做。

任何清单都无法强制执行的规则

上面的每个文件都只是一份快照,而服务一直在变化。

举一个来自这套文件本身的例子。本文于2026年8月首次撰写时,skills清单描述MCP服务器有27个类型化工具,而线上tools/list返回的是29个;服务器卡片在传输方法中列出了GET,但GET其实已被禁用。到2026年10月28日,服务器(版本1.2.0)返回53个工具,服务器卡片也已更正为POST和DELETE,但mcp.tronsave.io/quickstart上的快速入门仍写着25个工具。2026年11月7日,线上服务器报告的版本为1.5.1,工具数仍为53个,而服务器卡片上写的仍是1.2.0。

这些都不是智能体路径上的bug,而是已发布文档与运行中服务之间的正常偏差。这条经验适用于所有此类集成:用清单来发现,以服务器为准。在运行时通过tools/list枚举能力,而不是把从文件里读到的数量写死在代码中;让握手过程协商协议版本,而不是自行假定一个。

智能体应如何处理凭证

发现过程止于认证,而会话模型值得单独一段,因为这部分会带来真实后果。市场数据和报价完全不需要登录:在线上服务器(版本1.5.1,2026年11月7日核实)上,53个工具中有18个是公开的,每个工具都在_meta["io.tronsave/auth"]中声明自己的访问级别。其他操作则需要登录,登录会生成两种权限范围不同的会话之一:ApiKey会话仅限于内部账户操作;签名会话与钱包绑定,用户身份相关工具和大多数平台变更操作都需要它。API密钥不会悄悄获得签名级权限,在这些工具上它只会直接失败。

登录与MCP连接绑定,会话id通过传输层请求头传递,绝不会出现在工具参数中。请把它当作机密。会话id一旦泄露,他人就能在其过期前以该会话的权限进行操作——这正是自主运行时默认应使用权限更窄的ApiKey会话的原因。

如果您要为自己的网站搭建这一套

这套文件很小,一个下午就能上线:

  1. /llms.txt——一段摘要加上附带说明的精选链接,保持简短。
  2. /.well-known/api-catalog——每个API一个锚点,各自带有机器描述和面向人的文档。
  3. /.well-known/oauth-protected-resource——无论主API是否使用OAuth,都发布它。
  4. 一份认证文档——写明确切的请求头名称和大小写,以及人工获取凭证的方式。
  5. 一张MCP服务器卡片(如果您运行服务器)——既声明具备的能力,也声明不具备的能力。
  6. 一份带digest的agent skills清单(如果您发布技能)。
  7. /.well-known/security.txt——设置一个您真的会续期的过期日期。

然后在发布流程中加入一件事:服务一有变化就重新生成这些清单。这些文件发布成本很低,却很容易被遗忘。

FAQ

llms.txt是标准吗?

它是一种被广泛采用的约定,而不是IETF标准。与它并列的/.well-known/文件——api-catalog、受保护资源元数据、security.txt——才是正式的RFC。

发布这些文件对SEO有帮助吗?

没有直接帮助。它们帮助智能体和助手在到达之后正确使用您的服务。请把它们看作放在约定地址上的集成文档,而不是排名因素。

只有一个API,也要发布api-catalog吗?

要。价值在于位置可预测,而不在于条目数量。一个带机器可读描述的锚点就足够了。

没有OAuth,为什么还要发布受保护资源元数据?

因为客户端无论如何都会去找它。用资源标识和凭证传递方式作答,比返回404更有用——即使对您的主API来说,答案是“我们用API密钥,不用OAuth”。TronSave两者兼顾:tronsave.io上提供API密钥元数据,MCP端点则提供完整的OAuth登录。

如何获取TronSave API密钥?

在网站上连接TRON钱包并登录,或使用Telegram机器人的用户信息栏目。API密钥没有程序化注册端点——认证文档明确说明了这一点,而不是让您自己去摸索。通过OAuth登录连接的MCP应用可以跳过这一步:登录页面会要求您输入密钥或进行钱包签名。

如果只想使用API,从哪里开始?

官方SDK提供五种语言的封装,API自动化指南介绍了原始端点。发现文件是为需要自行找路的智能体准备的。

总结

让服务对AI智能体“可读”,与其说是一门新学问,不如说是面向新受众的老功课:说明您是什么,列出您开放了什么,对凭证要精确,并坦承您不支持什么。这些文件都是约定俗成的,工作量也不大。真正需要自律的是让它们保持准确——因为智能体会一直相信您的清单,直到服务器给出不同答案的那一刻。

TronSave运营本博客并发布了文中所述的发现文件。文件内容、工具数量和协议版本反映的是撰写时已发布的内容和线上服务器的返回结果,今后会发生变化——请在运行时枚举,而不要依赖上文引用的数字。本文不构成投资建议。

TronSave
TronSave

TronSave 团队在 tronsave.io 运营波场能量与带宽市场,这些指南基于在波场主网上的实际测试撰写。

相关文章

我们使用 Google Analytics 了解哪些指南对读者有帮助。只有在您允许分析时才会设置 Cookie。本博客不投放广告。 隐私