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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 看一下接入说明，然后在控制台里创建一个。控制台入口在 https://taotoken.net/console，API 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-code，Coding 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/api，apiKey 换成你在控制台创建的那个，modelId 换成你要用的模型。timeout 是超时时间，单位毫秒，可以根据网络情况调整。
接下来是 dzQuery.js 的引入。如果你选择远程引用，在 HTML 页面里加一行：
<script type="text/javascript" src="https://taotoken.net/api/dzQuery.js"></script>如果你选择本地引入，先把 dzQuery.js 下载下来，放到项目的静态资源目录，然后这样引用：
<script type="text/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 与 random
dzQuery.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 charset="utf-8"> <title>dzQuery.js 验证</title> <script type="text/javascript" src="https://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 为 0，userid 和 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 也为 0，cookie 字段里就是刚才存的 JSON 字符串。这说明 infiCookie 的读写链路是通的。
第五步，测试暗石消费。在控制台里执行：
dz.darkStone.spend(1, function(obj) { console.log("消费结果:", JSON.stringify(obj)); });如果账户里暗石足够，state 会返回 0，msg 是 Done!。如果暗石不足，state 会返回 3，msg 会提示暗石不足。这一步建议在测试账号上做，避免误消费。
整个验证过程下来，最关键的检查点是：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，里面有更完整的参数说明。这几个入口建议收藏，后续排查问题的时候会用得上。
