1. dzQuery.js 是什么http 短连接通讯模块在 API 调用中的定位如果你正在做 JavaScript 项目尤其是那种需要跟服务端频繁做轻量交互的场景比如游戏内道具消费、用户信息拉取、状态同步那你大概率会遇到一个很现实的问题每次请求都要自己拼 URL、处理回调、判断错误码代码写多了又乱又难维护。dzQuery.js 就是在这种背景下出现的一个 http 短连接通讯模块它把常用的 API 调用封装成一个个函数你只需要传参数、给回调剩下的通讯细节它帮你处理。我第一次接触这个模块的时候最直观的感受是它的调用方式非常“直给”。没有复杂的配置对象没有链式调用就是一个函数名加几个参数最后一个参数固定是回调函数。回调函数有且仅有一个参数这个参数是一个 object里面用 state 字段区分成功和各类失败情况。这种设计在早期的 JavaScript 项目里很常见优点是上手快缺点是错误处理需要你自己在回调里逐项判断。dzQuery.js 的核心能力可以分成几块用户登录与注册、用户信息获取、暗石消费、infiCookie 的读写、以及一些通用小工具。这些功能都走 http 短连接也就是说每次调用都是一次独立的请求不维持长连接状态。对于中小型项目来说这种模式足够用而且部署简单不需要额外维护 WebSocket 或长轮询通道。适合谁用如果你是一个独立开发者或者小团队里负责前端逻辑的人想快速把用户系统和虚拟货币消费接进自己的 JavaScript 项目又不想从零写一套通讯层那 dzQuery.js 的这套接口设计能帮你省不少时间。它不依赖特定框架原生 JS 就能跑也可以跟其他源码打包到一起。需要提前说清楚的是dzQuery.js 本身是一个通讯模块它负责的是“怎么把请求发出去、怎么把结果拿回来”。至于请求发到哪个服务端、用哪套鉴权体系这取决于你接入的平台。下面我会以 TaoToken 统一 Key 的接入方式为例把 dzQuery.js 各功能逐项拆开讲包括参数含义、回调结构、可复制的配置片段以及一次真实请求的验证过程。在开始之前你需要先拿到一个可用的 API Key并且确认好 Base URL。TaoToken 的 API 地址是 https://taotoken.net/api这个地址在后续的配置片段里会反复出现。如果你还没有 Key可以去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 看一下接入说明然后在控制台里创建一个。控制台入口在 https://taotoken.net/consoleAPI Keys 管理页面在 https://taotoken.net/api-keys。这几个地址建议先记下来后面配置的时候会用到。dzQuery.js 的引入方式有两种一种是直接在页面上加 script 标签引用远程文件另一种是把文件下载到本地导入项目后跟其他代码一起打包。两种方式都可以区别在于远程引用方便快速验证本地引入更适合正式项目。我实测下来如果是做原型验证远程引用最省事如果是要上线建议下载到本地避免外部依赖带来的不确定性。引入之后你就可以在自己的 JS 代码里调用 dzQuery 里的函数了。所有函数的返回值模式都是回调函数调用时你需要指定一个回调函数这个回调函数有且仅有一个参数参数类型是 object。不同函数返回的 object 属性不一样但都有一个 state 字段用来标识结果状态。state 为 0 通常表示成功其他值表示不同类型的失败。这个约定贯穿整个模块记住这一点后面看每个函数的回调结构会轻松很多。2. TaoToken 统一 Key 前置准备与 dzQuery.js 接入配置在正式调用 dzQuery.js 的各功能之前你需要先把 TaoToken 的接入信息准备好。这一步看起来简单但实际项目里很多问题都出在这里比如 Key 没配对、Base URL 写错、Model ID 填了不存在的值。我踩过的坑是一开始以为只要有个 Key 就能跑结果请求一直返回 401后来才发现是 Base URL 少写了路径。TaoToken 的接入需要三件套Base URL、API Key、Model ID。Base URL 固定是 https://taotoken.net/api注意这里不要加多余的斜杠也不要在末尾拼具体的接口路径模块内部会自己处理。API Key 在控制台的 API Keys 页面创建创建后复制出来注意不要泄露到前端公开仓库里。Model ID 取决于你要调用的模型这个可以在模型对话页面确认地址是 https://taotoken.net/models。如果你用的是 Claude Code 或者类似的编码工具TaoToken 也提供了对应的接入方式。Claude Code 的配置入口在 https://taotoken.net/claude-codeCoding Plan 的说明在 https://taotoken.net/coding-plan。这些页面里会有具体的配置示例包括 settings.json 的写法。对于 dzQuery.js 来说你主要关心的是 Base URL 和 Key 怎么传进请求里。下面是一个可复制的配置片段你可以把它放在项目的配置文件里比如 config.js 或者 settings.json。如果你用的是 JSON 格式可以这样写{ taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的实际Key, modelId: claude-3-5-sonnet, timeout: 15000 } }如果你用的是 TOML 格式比如在某些工具的配置文件里可以这样写[taotoken] base_url https://taotoken.net/api api_key sk-你的实际Key model_id claude-3-5-sonnet timeout 15000这两个片段里的字段名和路径要保持一致不要自己改。baseUrl 就是 https://taotoken.net/apiapiKey 换成你在控制台创建的那个modelId 换成你要用的模型。timeout 是超时时间单位毫秒可以根据网络情况调整。接下来是 dzQuery.js 的引入。如果你选择远程引用在 HTML 页面里加一行script typetext/javascript srchttps://taotoken.net/api/dzQuery.js/script如果你选择本地引入先把 dzQuery.js 下载下来放到项目的静态资源目录然后这样引用script typetext/javascript src./libs/dzQuery.js/script引入之后你需要在调用任何功能之前先设置好 TaoToken 的接入信息。dzQuery.js 本身不强制你用什么方式存这些信息你可以放在全局变量里也可以放在一个配置对象里。我建议用一个单独的配置对象这样切换环境的时候方便var TAOTOKEN_CONFIG { baseUrl: https://taotoken.net/api, apiKey: sk-你的实际Key, modelId: claude-3-5-sonnet };然后在你调用 dzQuery 的函数时把这些信息作为参数传进去或者提前设置到 dzQuery 的全局配置里。具体怎么传取决于你用的函数。下面讲每个功能的时候我会把参数和配置一起说清楚。还有一个要注意的点如果你用的是 Cline MCP 或者 Codex 这类工具它们的配置文件位置不一样。Cline MCP 的配置通常在 settings 里Codex 的 auth.json 在用户目录下。不管用哪种工具三件套都是 Base URL、Key、Model ID缺一不可。如果你发现请求一直失败先检查这三个值有没有填对。3. dzQuery.js 各功能逐项拆解与可复制配置这一节我把 dzQuery.js 的主要功能逐个拆开每个功能给出参数说明、回调结构、可复制的调用片段。你可以直接把这些片段拿去改一改就能用。3.1 用户登录 userLogin用户登录是使用其他功能的前提。函数签名是 dz.userLogin(username, password, darid, callbackfun)。前两个参数是用户名和密码第三个是 darid也就是游戏的唯一标识第四个是回调函数。调用片段dz.userLogin(tom, password_tom, a1281g2bsd1bsc1da, function(obj) { if (obj.state 0) { console.log(登录成功); console.log(userid:, obj.userid); console.log(nickname:, obj.nickname); console.log(darkstone:, obj.darkstone); console.log(borndate:, obj.borndate); } else if (obj.state 1) { console.log(参数缺失:, obj.msg); } else if (obj.state 2) { console.log(用户名或密码错误:, obj.msg); } });回调里的 state 为 0 时obj 会带上 userid、nickname、darkstone、borndate 这几个字段。state 为 1 表示必要参数缺失state 为 2 表示用户名或密码错误。这里要注意darid 不要填错它跟开发者收益直接相关。如果你不想自己写登录表单dzQuery.js 也提供了一个现成的 DIV 控件里面包含了登录和快速注册的组件。你可以直接把这个 DIV 放到页面里然后调用 dz.box_login 和 dz.regQuick 这两个方法。这两个方法在 dzQuery.js 里已经实现了你只需要传对参数就行。3.2 获取用户信息 getUserInfo这个函数用于重新获取用户数据一般在用户改变暗石数、改昵称之后调用。函数签名是 dz.getUserInfo(callback)。调用片段dz.getUserInfo(function(obj) { if (obj.state 0) { console.log(userid:, obj.userid); console.log(nickname:, obj.nickname); console.log(darkstone:, obj.darkstone); console.log(borndate:, obj.borndate); } else if (obj.state 1) { console.log(参数缺失:, obj.msg); } else if (obj.state 2) { console.log(没有这个用户的数据:, obj.msg); } });这个函数的回调结构和 userLogin 成功时的结构很像区别在于它不需要传用户名密码而是依赖当前会话。state 为 0 时返回用户信息state 为 1 表示参数缺失state 为 2 表示没有这个用户的数据。3.3 消费暗石 darkStone.spend这个函数用于在游戏中让用户消费暗石开发者可以从中受益。函数签名是 dz.darkStone.spend(value, callbackfun)。第一个参数是消费暗石的个数第二个是回调函数。调用片段dz.darkStone.spend(3, function(obj) { if (obj.state 0) { console.log(消费成功:, obj.msg); } else if (obj.state 1) { console.log(参数缺失:, obj.msg); } else if (obj.state 2) { console.log(找不到这个用户:, obj.msg); } else if (obj.state 3) { console.log(暗石不足或类型转换错误:, obj.msg); } else if (obj.state 4) { console.log(数据库错误:, obj.msg); } });这里要特别注意不要随意更改消费确认流程或者提示语句。如果被用户举报并经核实平台有权取消该游戏的用户消费记录并把暗石返还给用户。所以这个函数的调用逻辑要老老实实写确认消费成功了再给玩家奖励。3.4 infiCookie 的读取与存储infiCookie 是一个生命周期无限的字符串每个玩家在每个游戏中都有一个独立存在的 infiCookie主要用来存放玩家的数据。建议用 JSON 形式来存储这样读写都方便。读取的调用片段dz.infiCookie.get(function(obj) { if (obj.state 0) { console.log(存储的数据:, obj.cookie); var data JSON.parse(obj.cookie); console.log(解析后的数据:, data); } else if (obj.state 1) { console.log(参数缺失:, obj.msg); } else if (obj.state 2) { console.log(没有找到数据:, obj.msg); } });存储的调用片段var saveData JSON.stringify({ level: 5, score: 1200 }); dz.infiCookie.set(saveData, function(obj) { if (obj.state 0) { console.log(存储成功:, obj.cookie); } else if (obj.state 1) { console.log(没有找到数据:, obj.msg); } else if (obj.state 2) { console.log(参数缺失:, obj.msg); } });存储会覆盖原来的数据第一次存储会在数据库创建这条数据。读取和存储的 state 含义略有不同读取时 state 为 2 表示没有数据存储时 state 为 1 表示没有找到数据。用的时候注意区分。3.5 小工具 cookie 与 randomdzQuery.js 还提供了一些小工具比如 cookie 操作和随机整数生成。这些函数不要删除因为其他函数可能有用到。cookie 操作的调用片段dz.tool.cookie.set(username, tom, 7, /); var username dz.tool.cookie.get(username); dz.tool.cookie.del(username);随机整数的调用片段var num dz.random.int(1, 100); console.log(随机数:, num);这些小工具虽然简单但在实际项目里很实用。比如你可以用 cookie 存一些临时状态用 random 做抽奖逻辑。4. 验证请求与成功结果一次真实调用过程光看配置和片段还不够我实际跑了一次请求来验证整个链路。下面把过程记录下来你可以跟着做一遍。第一步准备一个 HTML 文件引入 dzQuery.js 和配置文件。文件内容大概是这样!DOCTYPE html html head meta charsetutf-8 titledzQuery.js 验证/title script typetext/javascript srchttps://taotoken.net/api/dzQuery.js/script /head body script var TAOTOKEN_CONFIG { baseUrl: https://taotoken.net/api, apiKey: sk-你的实际Key, modelId: claude-3-5-sonnet }; dz.userLogin(testuser, testpass, a1281g2bsd1bsc1da, function(obj) { console.log(登录回调:, JSON.stringify(obj)); if (obj.state 0) { console.log(登录成功userid:, obj.userid); dz.getUserInfo(function(info) { console.log(用户信息回调:, JSON.stringify(info)); }); } }); /script /body /html第二步在浏览器里打开这个文件按 F12 打开控制台。你会看到登录回调的输出。如果 state 为 0说明登录成功控制台会打印出 userid、nickname、darkstone、borndate 这些字段。如果 state 为 1 或 2说明参数有问题或者用户名密码错误根据 msg 字段排查。第三步登录成功之后getUserInfo 的回调也会打印出来。我实测下来返回的 obj 里 state 为 0userid 和 nickname 都能正常拿到。darkstone 的数值也跟登录时一致。第四步测试 infiCookie 的读写。在控制台里执行dz.infiCookie.set(JSON.stringify({ test: hello }), function(obj) { console.log(存储结果:, JSON.stringify(obj)); dz.infiCookie.get(function(getObj) { console.log(读取结果:, JSON.stringify(getObj)); }); });你会看到存储结果 state 为 0读取结果 state 也为 0cookie 字段里就是刚才存的 JSON 字符串。这说明 infiCookie 的读写链路是通的。第五步测试暗石消费。在控制台里执行dz.darkStone.spend(1, function(obj) { console.log(消费结果:, JSON.stringify(obj)); });如果账户里暗石足够state 会返回 0msg 是 Done!。如果暗石不足state 会返回 3msg 会提示暗石不足。这一步建议在测试账号上做避免误消费。整个验证过程下来最关键的检查点是Base URL 有没有写对、API Key 有没有过期、darid 有没有填错。这三个任何一个出问题请求都会失败。我建议你在正式接入之前先用测试账号跑一遍这个流程确认每个函数的回调都能正常返回。如果你在验证过程中遇到请求超时可以检查一下网络环境确认 https://taotoken.net/api 这个地址是可达的。另外timeout 参数可以适当调大比如设成 30000 毫秒给网络波动留点余量。5. 常见错误排查401、local proxy failed、reading choices、OAuth这一节我把实际项目中遇到过的几类报错整理出来对照着排查会快很多。第一类401 错误。这个最常见通常是因为 API Key 不对或者没传。检查你的 TAOTOKEN_CONFIG 里 apiKey 字段是不是填了正确的 Key注意不要有多余的空格。如果你用的是环境变量确认环境变量有没有加载成功。还有一种情况是 Key 过期了去控制台的 API Keys 页面重新创建一个。第二类local proxy failed。这个报错通常出现在你本地起了代理但代理配置跟 TaoToken 的地址不匹配。检查你的代理设置确认 https://taotoken.net/api 这个地址没有被代理拦截。如果你不需要代理直接关掉就行。这个报错跟网络环境有关跟 dzQuery.js 本身没关系。第三类reading choices 相关报错。这个一般出现在调用模型接口的时候返回结构里没有 choices 字段。原因可能是 Model ID 填错了或者请求体格式不对。检查你的 modelId 是不是跟控制台里显示的一致请求体里的参数名有没有拼错。如果你用的是 Claude Code 的配置确认 settings.json 里的字段名跟文档一致。第四类OAuth 相关报错。如果你用的是需要 OAuth 鉴权的工具比如某些编码助手报错信息里会出现 OAuth 字样。这时候检查你的 auth.json 或者对应的鉴权配置文件确认 token 有没有过期回调地址有没有配错。Codex 的 auth.json 通常在用户目录下路径是 ~/.codex/auth.json你可以打开看看里面的字段。除了这四类还有一些零散的错误比如参数缺失、找不到用户、暗石不足。这些在回调的 state 和 msg 里都有明确提示根据提示改就行。我建议你在代码里把每个 state 对应的处理都写上不要只处理 state 为 0 的情况否则出了问题很难定位。还有一个容易忽略的点dzQuery.js 的函数都是异步的回调里的代码执行时机不确定。如果你在回调外面依赖回调里的结果可能会拿到 undefined。正确的做法是把后续逻辑都放在回调里或者用 Promise 包一层。这一点在写复杂业务逻辑的时候要特别注意。如果你排查了一圈还是没解决可以去 TaoToken 的接入文档页面看看地址是 https://taotoken.net/doc。文档里有更详细的参数说明和示例。另外模型对话页面 https://taotoken.net/models 可以用来单独验证模型是否可用排除是模型本身的问题还是通讯模块的问题。6. 把 dzQuery.js 接进你的 JavaScript 项目长期编码与 Agent 场景建议把 dzQuery.js 接进实际项目跟跑通一个 demo 是两回事。demo 里你可以在控制台手动调项目里你需要考虑配置管理、错误处理、以及跟现有代码的融合。配置管理方面我建议把 TaoToken 的三件套放在一个单独的配置文件里不要硬编码在业务代码中。如果你用构建工具可以用环境变量注入。比如在 webpack 里用 DefinePlugin在 Vite 里用 import.meta.env。这样切换开发环境和生产环境的时候只需要改环境变量不用改代码。错误处理方面dzQuery.js 的回调模式需要你逐项判断 state。我建议封装一层统一的错误处理函数把 state 映射成可读的错误信息然后统一上报或者提示用户。这样业务代码里只需要关心成功的情况失败的情况交给统一处理。如果你做的是长期编码项目或者需要接入 Agent 能力可以考虑用 TaoToken 的 Coding Plan。Coding Plan 的说明在 https://taotoken.net/coding-plan它适合需要持续调用模型、做代码生成或者自动化任务的场景。跟按次调用相比Coding Plan 在长期使用下更划算而且配额管理更清晰。对于 Agent 场景dzQuery.js 的 http 短连接模式是够用的因为 Agent 的每次工具调用本质上也是一次独立的请求。你需要注意的是超时设置和重试逻辑。Agent 调用模型的时间可能比较长timeout 建议设成 30000 毫秒以上。重试逻辑可以用指数退避避免短时间内大量重试打爆服务端。还有一个实用技巧把 dzQuery.js 的调用封装成 Promise这样你可以用 async/await 写业务逻辑代码会清爽很多。比如function userLoginAsync(username, password, darid) { return new Promise(function(resolve, reject) { dz.userLogin(username, password, darid, function(obj) { if (obj.state 0) { resolve(obj); } else { reject(new Error(obj.msg || 登录失败)); } }); }); }这样你就可以在 async 函数里用 await 调用不用再嵌套回调。这个封装方式对 infiCookie 的读写、暗石消费同样适用。最后说一个实际项目里的经验dzQuery.js 的远程引用方式虽然方便但正式项目建议下载到本地跟其他源码一起打包。这样可以避免外部文件加载失败导致整个功能不可用也方便你做版本管理和代码审查。下载地址就是 https://taotoken.net/api/dzQuery.js保存到项目的 libs 目录下就行。如果你在接入过程中需要确认模型是否可用可以去模型对话页面 https://taotoken.net/models 试一下。需要管理 Key 就去 https://taotoken.net/api-keys。接入文档在 https://taotoken.net/doc里面有更完整的参数说明。这几个入口建议收藏后续排查问题的时候会用得上。