接口文档
这一页分两部分:公开可读地址(不需要密钥,搜索引擎与 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_since | 200 |
| /capi/geo/product/info | 单个商品的公开知识视图 | handle | 200 |
| /capi/geo/entity/info | 页面等实体知识的公开视图 | entity_type、entity_id | 200 |
统一返回 { code, message, data },code 为 200 表示成功。只返回已公开的内容:已上架的商品、已发布的页面与文章。
二、连接 AI Agent(skill 通道)
一句话:接口地址 + 站点令牌,两个值填进 Agent 就能用。令牌等同于本站后台权限,只放在请求头里,不要写进 URL、不要提交到代码仓库。
1. 拿到两个值
- 登录后台,打开左侧导航里的「AI 连接」页。
- 页面上有两行:接口地址(本站固定为 /api/skill,完整地址是 https://你的域名/api/skill)与访问令牌(sk_ 开头)。
- 点右侧复制按钮;也可以点「复制接入说明」,一次把地址、鉴权与接口发现方式整段交给 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/capabilities | 200 / 46,063 B | 200 / 45,842 B |
| GET /api/skill/base/init | 200 / 644 B | 200 / 664 B |
| GET /api/skill/product/list?limit=2 | 200 / 25,534 B | 200 / 5,417 B |
| GET /api/skill/analytics/traffic-get | 200 / 3,424 B | 200 / 2,913 B |
| GET /api/skill/plugin/list | 200 / 15,673 B | 200 / 14,681 B |
| GET /api/skill/i18n/list | 200 / 5,275 B | 200 / 5,275 B |
| 同上,但不带令牌 | 401 / 68 B | 401 / 68 B |
结论:两台站的通路都是通的,鉴权都生效,无令牌都被拒(返回「未授权:X-Site-Token 缺失或不匹配」)。体积不同是数据量差异,不是故障。
6. 错误码与处置
| 状态 | 含义 | 怎么处理 |
|---|---|---|
| 401 | 令牌缺失或不匹配 | 检查请求头名是否为 X-Site-Token;令牌是否被重置过 |
| 403 | 被权限矩阵拦截 | 看返回里的 reason;到后台「接口权限」放开对应模块 |
| 404 | 路径不存在 | 先用 capabilities 核对接口名,别凭记忆拼 |
| 503 | 服务端未配置站点令牌 | 后台「AI 连接」页正常打开一次,系统会自动生成 |
7. 三条安全底线
- 令牌不要进 URL,也不要贴进聊天窗口或提交到代码仓库——它等同后台登录态。
- 只给必要的权限:日常运营开只读 + 写入即可,危险类按需临时开。
- 换人或交接时重置令牌,旧令牌立即失效,比逐个回收更可靠。
三、接入 WorkBuddy 的最小步骤
- 后台「AI 连接」→ 复制接口地址与访问令牌(或直接复制整段接入说明)。
- 在 WorkBuddy 的连接器 / 技能配置里填入站点地址,鉴权用 X-Site-Token。
- 让 Agent 先调 capabilities 自描述,再按清单调用具体接口。