页面

接口文档

这一页分两部分:公开可读地址(不需要密钥,搜索引擎与 AI 检索器直接读)和连接 AI Agent 的 skill 通道(需要站点令牌,供 WorkBuddy 这类 Agent 读写本站)。

一、公开地址:不用密钥

地址用途参数实测状态
/sitemap.xml全站公开页面索引无200
/robots.txt抓取规则说明无200
/llms.txt面向 AI 检索器的站点说明与公开地址目录无200
/api/geo/v1/capabilities声明本站可读字段与公开地址清单无200
/capi/geo/list列出公开内容(商品 / 分类 / 页面 / 文章)type、page、pageSize、updated_since200
/capi/geo/product/info单个商品的公开知识视图handle200
/capi/geo/entity/info页面等实体知识的公开视图entity_type、entity_id200

统一返回 { code, message, data },code 为 200 表示成功。只返回已公开的内容:已上架的商品、已发布的页面与文章。

二、连接 AI Agent(skill 通道)

一句话:接口地址 + 站点令牌,两个值填进 Agent 就能用。令牌等同于本站后台权限,只放在请求头里,不要写进 URL、不要提交到代码仓库。

1. 拿到两个值

  1. 登录后台,打开左侧导航里的「AI 连接」页。
  2. 页面上有两行:接口地址(本站固定为 /api/skill,完整地址是 https://你的域名/api/skill)与访问令牌(sk_ 开头)。
  3. 点右侧复制按钮;也可以点「复制接入说明」,一次把地址、鉴权与接口发现方式整段交给 Agent。

重置令牌会让旧令牌立刻失效,已在用的 Agent 必须同步更新,否则所有调用都会返回 401。

2. 怎么鉴权

所有 skill 接口只认一个请求头:X-Site-Token: 你的令牌。不支持把令牌放进 URL 参数——URL 会进访问日志、Referer 与浏览器历史,等于把后台权限公开。

一次最小调用(把域名与令牌换成你自己的):

curl -s https://你的域名/api/skill/capabilities \
-H "X-Site-Token: sk_你的令牌"

3. 先问「你会什么」,再调具体接口

不要一开始就去猜接口名。两个自助接口永远可用,Agent 靠它们自己发现能力:

  • GET /api/skill/capabilities —— 完整能力清单:接口路径、方法、读写类型、参数说明,以及本站的鉴权方式与版本号。
  • GET /api/skill/base/init —— 站点基本信息:站点类型(B2B / B2C)、当前主题、可用主题、语言与货币。

其余接口按模块划分,常见的有:/api/skill/product/list(商品)、/api/skill/plugin/list(插件)、/api/skill/i18n/list(多语言词条)、/api/skill/analytics/traffic-get(流量)、/api/skill/b2c-order/list(订单,B2C 站)。

4. 权限矩阵:默认全开,可按模块收紧

后台「接口权限」有两档:全部允许(默认,与开通时行为一致)和按模块限制(逐模块开关读 / 写 / 危险三类操作)。

类别含义建议
只读查询商品、内容、流量、插件状态默认开启
写入新增或修改商品、内容、装修需要 Agent 代运营时开启
危险删除、整站覆盖、发布类操作只在明确需要时开启

「接口清单(capabilities)」与「站点初始化(base/init)」两个只读接口始终放行,不受权限表影响——否则 Agent 连「为什么连不上」都查不到。保存后立即生效,Agent 侧不需要改任何配置;被禁止的接口会返回 403 并说明原因。

5. 实测记录(2026-10-19,两台客户站各测一遍)

用各站自己的真实令牌逐个调用,结果如下(不做修饰,就是当时的返回):

接口B2B 站B2C 站
GET /api/skill/capabilities200 / 46,063 B200 / 45,842 B
GET /api/skill/base/init200 / 644 B200 / 664 B
GET /api/skill/product/list?limit=2200 / 25,534 B200 / 5,417 B
GET /api/skill/analytics/traffic-get200 / 3,424 B200 / 2,913 B
GET /api/skill/plugin/list200 / 15,673 B200 / 14,681 B
GET /api/skill/i18n/list200 / 5,275 B200 / 5,275 B
同上,但不带令牌401 / 68 B401 / 68 B

结论:两台站的通路都是通的,鉴权都生效,无令牌都被拒(返回「未授权:X-Site-Token 缺失或不匹配」)。体积不同是数据量差异,不是故障。

6. 错误码与处置

状态含义怎么处理
401令牌缺失或不匹配检查请求头名是否为 X-Site-Token;令牌是否被重置过
403被权限矩阵拦截看返回里的 reason;到后台「接口权限」放开对应模块
404路径不存在先用 capabilities 核对接口名,别凭记忆拼
503服务端未配置站点令牌后台「AI 连接」页正常打开一次,系统会自动生成

7. 三条安全底线

  1. 令牌不要进 URL,也不要贴进聊天窗口或提交到代码仓库——它等同后台登录态。
  2. 只给必要的权限:日常运营开只读 + 写入即可,危险类按需临时开。
  3. 换人或交接时重置令牌,旧令牌立即失效,比逐个回收更可靠。

三、接入 WorkBuddy 的最小步骤

  1. 后台「AI 连接」→ 复制接口地址与访问令牌(或直接复制整段接入说明)。
  2. 在 WorkBuddy 的连接器 / 技能配置里填入站点地址,鉴权用 X-Site-Token。
  3. 让 Agent 先调 capabilities 自描述,再按清单调用具体接口。