DEVELOPER FIELD GUIDE

从第一条信号,
到你的下一个应用。

统一的输入与输出,让你把时间留给真正要解决的问题。

OpenAPI 3.1完整机器可读合同

演示与真实数据,始终明确区分。演示请求返回固定样本;客户网关支持本地模拟供应商与测试积分结算。当前真实调用和支付保持关闭。

01 · 先运行一个演示

下面的请求按“户外咖啡”搜索演示笔记。X-Guanliu-Mode: demo 明确选择演示模式,无需访问密钥。

TERMINAL / CURL
curl --get 'http://localhost:4401/v1/xiaohongshu/notes/search' \
  -H 'X-Guanliu-Mode: demo' \
  --data-urlencode 'query=户外咖啡' \
  --data-urlencode 'sort=relevance'

不想打开终端?在调试台运行这个能力,或 查看完整参数文档。

在 JavaScript 中调用

JAVASCRIPT / FETCH
const params = new URLSearchParams({
  query: '户外咖啡',
  sort: 'relevance'
});

const response = await fetch(
  'http://localhost:4401/v1/xiaohongshu/notes/search?' + params,
  { headers: { 'X-Guanliu-Mode': 'demo' } }
);
const result = await response.json();

if (!response.ok) {
  throw new Error(result.message || '请求未完成');
}

// 固定演示样本,查看 meta.mode 区分数据来源
console.log(result.data.items, result.meta.mode);

02 · 读懂统一响应

列表能力返回 data.items,详情能力返回 data.item。两种形式共享请求标识、分页与运行信息。

字段用途
request_id定位一次请求,保留它便于排查。
data.items / item规范化后的内容、评论或账号对象。
page.next_cursor下一页游标。作为相同能力下次请求的 cursor 传入。
page.has_more是否还有下一页。为 false 时结束分页。
meta.modedemo 表示固定演示样本;simulated 表示本地模拟供应商;live 为独立的真实供应商模式,当前关闭。
warnings返回结果相关的提示与限制,应用应保留或适当展示。
meta.billing匿名演示为 not_implemented;客户沙盒为 sandbox,credits_debited 表示测试积分,charged=false 表示没有真钱收费。

游标与原请求关联。翻页时保留原关键词、排序和其他参数;不要把一个平台的游标用于另一个平台。没有公开数据时可能返回空列表,不应将它直接等同于网络错误。

03 · 给失败留一个出口

先检查 HTTP 状态,再读取错误对象中的 code、message 与 request_id。不要只检查响应是否为 JSON。

  • 参数不符合合同:根据错误说明修正输入,避免原样重试。
  • 实时服务未配置或鉴权失败:检查服务端配置和客户端访问密钥。
  • 供应商模拟超时:保留原幂等编号查询回执,不自动换编号重发。

错误的具体状态码与结构以 当前 OpenAPI 合同 为准。调试台会展示请求的实际状态与返回内容。

只读账户与用量

客户 Key 可通过 GET /v1/account 读取 TEST 余额、共享预算和当前配额;GET /v1/usage 查询该 Key 已保存的调用,支持状态、能力、UTC 日期及分页。请求使用 Bearer Key 和 X-Guanliu-Mode: simulated,查询不采集、不预留、不扣点。

钱包属于账户,预算属于轮换组,用量只属于当前 Key。轮换后新 Key 的记录从零开始,预算历史保留。在途请求、预检拒绝与重复回执不会各新增一条记录。

SDK 提供 account() 与 usage(filters),MCP 使用 account 工具的 balance / usage。查看可运行示例,或 打开只读 Key 检查。

调用前报价与 Key 预算

客户 Key 可设置日、月、总 TEST 消费上限,成功消耗和在途预留共同占用预算。固定演示与供应商模拟共享预算;轮换 Key 不重置累计消费。可在 密钥管理 创建并查看。

使用客户 Key 请求 GET /v1/quote?capability=x.users.get&username=demo_account,携带 X-Guanliu-Mode: simulated 获取当前只读报价。此步骤不执行供应商、不预留或扣点,实际调用时重新检查。

新调用可加 X-Guanliu-Max-Credits: 1 作为最高单次 TEST 限制;高于上限返回402,非法上限返回400。保持原幂等编号重放已完成请求,不新增扣点。任务总额可用 点数计算器 估算;供应商成本与测试积分分开记录。

04 · 从账户到模拟计费

完整流程,本地运行。

在 注册页 创建本地账户,初始测试余额为 0。打开 账单与支付 创建订单,在模拟收银台选择成功,再到 密钥管理 创建客户 API Key。

客户密钥以 gl_test_ 开头,只显示一次。可以设置能力权限、到期时间和每日成功调用限额。它仅用于客户沙盒,不能开启真实供应商调用。

CURL / 本地客户沙盒
curl --get 'http://localhost:4401/v1/xiaohongshu/notes/search' \
  -H 'X-Guanliu-Mode: sandbox' \
  -H 'Authorization: Bearer <gl_test_customer_key>' \
  --data-urlencode 'query=户外咖啡'

将占位符换成自己的客户密钥。账号类能力每次成功消耗 1 TEST 积分,内容和评论类每次成功消耗 2 点;失败不扣点。返回仍为 meta.mode=demo、provider=fixture,没有真实支付或供应商用量。

重试、限额与账本

同一逻辑请求携带相同 Idempotency-Key。客户沙盒会保存回执,跨重启重放时 meta.replayed=true、credits_debited=0;变更参数须换一个 key。余额不足返回 402,每日成功调用限额用尽返回 429。分页保持原查询,并为新一页使用新的幂等 key。

在 调用记录 查看请求结果,在账单中核对测试积分。密钥撤销或轮换后,旧密钥立即失效;不会因持有旧回执而继续获得权限。

模拟供应商执行与成本

在客户 Key 页选择“供应商模拟”,或携带 X-Guanliu-Mode: simulated、必填的 Idempotency-Key,以及 X-Guanliu-Mock-Scenario: success|failure|timeout。成功先预留、后扣测试积分;失败或超时释放预留。相同请求执行中返回 202,完成后重放只读持久回执,不再执行和扣点。

打开 执行与成本,按状态、能力、Key 和 UTC 日期筛选逻辑请求,查看结算详情并导出 CSV。客户 TEST 积分和虚构供应商 TEST_MICROCREDIT 成本分开显示,未知成本保留为未知;已知成本合计不包含未知项。查询与导出不会触发供应商调用。

已有真实接口的边界

原有本地 API 调试台的真实试用与客户沙盒独立。真实试用会使用供应商额度,客户 TEST 积分不会兑换为供应商余额;公开客户 API 的 live 模式和真实支付都未开放。

05 · 连接 AI 与你的代码

打开 MCP 配置生成器,选择公开演示或客户模拟,填写本机项目路径与端口,再将生成的配置添加到客户端。页面只生成 Key 占位符,完整密钥仅在客户端环境变量 GUANLIU_CUSTOMER_API_KEY 中配置。

客户模拟使用 GUANLIU_MCP_MODE=simulated。call 必填 idempotency_key,可选 scenario=success|failure|timeout;read_more 保留原参数与场景,新一页用新编号,重试同一页保持原编号。匿名 demo 四工具、客户 simulated 七工具,均不自动重试、轮询或翻页。客户另有只读 quote/account,以及创建需显式 confirm:true、读取只读的 run 预算工具。

SDK 固定连接本机模拟网关,凭据只随客户 API 请求发送。将下载文件放在脚本旁,使用 可复制的 JavaScript / Python 示例。成功、失败和 202 都返回 status 与 body,请先判断状态。

结果应用应该怎样处理
200执行已完成。保留 request_id、mode 和测试结算信息;相同编号重放不重复扣点。
202执行仍在进行,尚无最终结果。需要查询时,保留原能力、参数、场景与幂等编号。
400–599读取 body.code 识别参数、权限、余额、限额或模拟执行问题。失败不能当成空数据成功。
GuanliuError配置、传输或协议未完成。JS 的 outcomeUnknown / Python 的 outcome_unknown 为 true 时,不能确认执行结果;保留原编号,避免换号重复执行。

准备流程:创建有对应权限的客户 Key → 通过模拟收银台获得 TEST 点数 → 在客户端发起模拟请求 → 核对执行与成本。真实供应商和支付保持关闭。

06 · 把结果交给下一步

从任务工作流选择模板,在多步任务演练里生成计划、核对总 TEST 预算,再逐步报价和执行。默认匿名 demo;客户 simulated 需要你显式选择并输入自己的客户 Key。

内容与选题库

按关键词获取内容,保留来源、作者与时间,再按自己的研究主题整理。

AI 上下文

把规范化字段作为上下文交给模型,同时保留原始链接与数据来源标记。

脚本与自动化

通过 HTTP 节点调用 API,按分页合同读取结果,处理空数据和失败分支。

07 · 保持一份合同

接口目录、参数文档与 OpenAPI 都从统一能力清单生成。开始自动化接入前,读取当前版本的合同。