全球代理 AI 工具使用指南（Skills + MCP）
全球代理 AI 工具让你在 AI 客户端中，用自然语言查询余额、产品、价格和子账号，并在确认后完成购买、续费或管理操作。动态住宅、静态住宅和数据中心产品都使用同一套安装配置。
MCP 负责调用接口，Skill 指导 AI 按产品规则完成操作。 推荐一起安装；只配置 MCP 也能调用工具，但只有 Skill、没有 MCP 时无法操作真实账户。
项目名为 quanqiudaili-agent-tools，客户端中的服务名和 Skill 名均为 quanqiudaili。当前包含 38 个工具：20 个只读、18 个写操作，实际可用功能以安装版本和客户端加载结果为准。
1. 使用前准备
准备一个全球代理账号、支持本地 MCP 的 AI 客户端，以及以下环境：
- Node.js 20 或更新版本，可以使用
node、npm、npx。 - Git，并能访问 GitHub、npm 和全球代理接口。
在终端检查：
node --version
npm --version
git --version
本项目使用 stdio / 本地命令，由 AI 客户端启动，不提供可直接填写的远程 MCP HTTP 地址。
获取 API Key
登录网站，在 API Keys 页面创建并复制 Key，获取方式见官方说明。
QQDL_TOKEN 就是网站 API Key，安装和运行时必填，只读模式也需要。 请在本地安装器或客户端配置中填写，不要发送到聊天或公开仓库。
2. 一次安装 Skills 与 MCP
以下两种方式任选其一。
方式一：自动下载并安装
在终端执行：
npx -y github:empty-byte/quanqiudaili-agent-tools install
npx 会自动下载项目、安装依赖并构建，无需另外克隆源码。保留末尾的 install；不带它只会启动 MCP，不会安装 Skill 或配置客户端。
方式二：下载源码后安装
希望自己管理源码目录时，依次执行：
git clone https://github.com/empty-byte/quanqiudaili-agent-tools.git
cd quanqiudaili-agent-tools
npm ci
node dist/src/index.js install
npm ci 要在项目根目录运行，会安装依赖并自动构建。已有源码时进入对应目录即可，不必重新克隆。
按提示完成安装
- 选择一个或多个客户端。
- 选择安装范围，首次使用通常选择用户级。
- 输入 API Key，等待验证和安装完成。
Key 输入内容可见；安装器通过只读用户信息接口验证后才写入文件，不会下单或修改业务账号。验证失败可重新输入或取消；网络异常、超时也会阻止安装。
项目级会安装到运行命令时所在的目录。需要装到自己的业务项目时，先进入该项目，再运行 npx 安装命令。
支持的客户端
| 客户端 | --agents 名称 | 安装范围 |
|---|---|---|
| Claude Code | claude-code | 用户级、项目级。 |
| Cursor | cursor | 用户级、项目级。 |
| Codex | codex | 用户级、项目级。 |
| Gemini CLI | gemini-cli | 用户级、项目级。 |
| OpenCode | opencode | 用户级、项目级。 |
| GitHub Copilot CLI | github-copilot-cli | 用户级、项目级。 |
| VS Code / Copilot | vscode | 用户级、项目级。 |
| Windsurf | windsurf | 仅用户级。 |
| Kiro CLI | kiro-cli | 用户级、项目级。 |
| Zed | zed | 用户级、项目级。 |
| Cline | cline | 仅用户级。 |
Claude Desktop 使用后文的手动 MCP 配置，不在一体安装列表中。Claude Code 与 Copilot CLI 同时安装时，请采用用户级，避免项目级配置冲突。客户端是否加载 Skill，还取决于其版本与设置。
常用安装选项
例如，同时安装到 Claude Code、Cursor 和 Codex：
npx -y github:empty-byte/quanqiudaili-agent-tools install --agents claude-code,cursor,codex --scope user
| 选项 | 用途 |
|---|---|
--agents codex,cursor | 指定客户端，省略时交互选择。 |
--scope user / --scope project | 用户级或当前项目级安装。 |
--readonly | 只加载 20 个查询工具，仍安装 Skill。 |
--dry-run | 预览目标和冲突，不写配置、不验证 Key；npx 下载仍可能联网。 |
--replace | 替换冲突的同名服务或 Skill，使用前先核对。 |
--list / --help | 查看客户端列表或安装帮助。 |
源码方式把前面的 npx 命令换成 node dist/src/index.js install，其余选项相同。非交互安装须指定 --agents，并通过环境变量 QQDL_TOKEN 或 --token-stdin 提供 Key；install 不支持 --token 参数。
Key 以明文保存在本地客户端配置中，修改前产生的 .qqdl-backup-… 备份也可能含 Key，不要提交或分享这些文件。安装器默认保留其他服务，遇到手工修改的同名内容会停止；TOML 改写会重新排版并移除注释，原文保存在备份中。
3. 验证安装结果
重新加载客户端，确认 quanqiudaili Skill 已被识别、MCP 已连接，并允许当前对话使用工具。安装成功不代表客户端已经加载配置。
先发送一次只读请求：
请使用全球代理工具查询我的账户余额，不执行任何修改。
查看 AI 是否实际调用工具并返回余额。接着可以尝试：
使用 quanqiudaili 技能查询我的子账号，按产品分类，每类先显示前 20 个，并说明是否还有下一页。
如果 AI 只给出说明而没有调用工具，请检查 Agent 模式、MCP 连接和工具权限。手动配置 MCP 的用户没有自动安装 Skill，但仍可验证工具调用。
4. 可以让 AI 做什么
配套 Skill 用一个入口组织五类流程。描述产品、目标账号、数量、地区和时长即可，不需要记忆接口参数。
| 场景 | 可以直接发送的示例 |
|---|---|
| 产品与购买 | 我想买 5 个美国静态住宅原生 IP，使用 30 天。先查库存、价格和余额，列出方案，等我确认后下单。 |
| 账号与流量 | 查询指定动态住宅子账号上个月的每日流量，再检查当前限额，先不要修改。 |
| 续费与带宽 | 找出即将到期的账号，说明续费费用和自动续费设置；如果需要升级带宽，先试算再确认。 |
| 删除与退单 | 检查这个订单能否退单，说明退款和账号后续处理，等我确认后再申请。 |
| 代理连接 | 用已有动态住宅账号生成 3 个美国出口、期望保持 10 分钟的会话，只生成配置，不新建账号或测试流量。 |
修改或批量操作前，先让 AI 列出目标账号并核对；查询“全部”时需要处理分页。批量备注等异步任务提交后，还应查询实际结果。
产品差异
| 产品 | 购买与使用要点 |
|---|---|
| 动态住宅流量，不限时长 | 按 GB 购买，每单整数 1–5000 GB，流量不限时长。 |
| 动态住宅流量，包月 | 每单整数 1–5000 GB，固定 30 天，未用完的流量到期失效。 |
| 静态住宅普通、原生、运营商原生 | 按地区、IP 数量和时长购买，普通新购每单 1–300 个 IP。 |
| 数据中心 | 每单最多 50 个 IP，不支持购买或续费 7 天。 |
| 动态住宅不限流量，按带宽计费 | 每单一个子账号，无自动续费；US/DE/SG 是不可更换的接入网关，不是出口国家。 |
动态流量按整单数量匹配价格档位，自定义价额度不足时整单回退官网价。按带宽计费的动态住宅支持新购、续费和升级报价，但没有对应库存工具。报价不锁价、不占库存，实际扣费以下单结果为准。 测试 IP 也会扣费，仅已实名代理商账号可用。
续费与连接的几个要点
- 普通时长续费保留自动续费开关；带宽续费选项未指定时沿用原值。本次续费时长会成为后续自动续费的时长，设置不同的账号需分开处理。
- 普通时长续费没有按目标账号精确试算总额的工具。需要精确金额或严格费用上限时，先在网站核对，不能先续费再看价格。
- 动态代理不带
ss为轮换模式，带ss为粘性会话。不同会话不保证出口 IP 不同，节点掉线可能提前换 IP；更换会话不会创建子账号。 - 生成连接配置不代表已经连通。真实代理测试可能消耗流量，应另行明确要求。
5. 写操作与确认
购买、续费、修改、创建和删除等写操作，都会先要求确认：客户端可能弹窗，也可能在对话中展示预览和一次性确认码。先核对目标、参数、费用和影响，再明确同意。
弹窗同意后服务直接执行；确认码方式下，AI 必须得到明确同意后才能携带相同参数调用。确认码默认 5 分钟有效、静默期 10 秒；等待到期不代表你已同意，参数变更或过期需重新确认。
使用时还需注意：
- 预览不会自动查询报价或余额，请先让 AI 查询；无法精确报价时应说明。
- 删除不可恢复；退单提交成功只代表申请已提交，审核通过后对应子账号会终止并删除，退款结果需另行确认。
- 写请求超时或结果不明时，先核对网站订单和账号状态，不自动重复执行；部分成功也不要整批重做。
- 普通使用保留默认确认。运行参数
--yes会关闭确认，不应由 AI 自行添加。
只想查询时，在安装命令中添加 --readonly：
npx -y github:empty-byte/quanqiudaili-agent-tools install --agents codex --scope user --readonly
6. 手动配置 MCP（可选）
适合只需要 MCP、使用 Claude Desktop，或自行管理配置的用户。已完成一体安装时可以跳过本节；手动配置不会安装 Skill。
展开常用客户端配置
将 YOUR_API_KEY 换成自己的 Key。已有配置时只合并 quanqiudaili 节点，保留其他服务，保存后重新加载客户端。
Claude Desktop、Cursor、Claude Code
以下客户端可在对应文件中使用同一份 JSON 配置：
| 客户端 | 配置位置 |
|---|---|
| Claude Desktop | 设置的 Developer → Edit Config 打开的 claude_desktop_config.json。 |
| Cursor | 用户级 ~/.cursor/mcp.json，或项目级 .cursor/mcp.json。 |
| Claude Code | 项目级 .mcp.json；注意不要提交包含 Key 的文件。 |
{
"mcpServers": {
"quanqiudaili": {
"command": "npx",
"args": ["-y", "github:empty-byte/quanqiudaili-agent-tools"],
"env": { "QQDL_TOKEN": "YOUR_API_KEY" }
}
}
}
Codex
在用户主目录的 .codex/config.toml 添加：
[mcp_servers.quanqiudaili]
command = "npx"
args = ["-y", "github:empty-byte/quanqiudaili-agent-tools"]
[mcp_servers.quanqiudaili.env]
QQDL_TOKEN = "YOUR_API_KEY"
VS Code / GitHub Copilot
通过命令面板打开 MCP: Open User Configuration，或编辑项目 .vscode/mcp.json。顶层字段为 servers：
{
"servers": {
"quanqiudaili": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:empty-byte/quanqiudaili-agent-tools"],
"env": { "QQDL_TOKEN": "YOUR_API_KEY" }
}
}
}
Windows 与其他启动方式
Windows 手动配置找不到 npx 时，将 command 改为 cmd，args 改为：
["/c", "npx", "-y", "github:empty-byte/quanqiudaili-agent-tools"]
只读模式在参数末尾追加 "--readonly"。本地源码运行则使用 node，参数填写 dist/src/index.js 的绝对路径，并保留源码目录。
其他客户端可以生成配置参考：
npx -y github:empty-byte/quanqiudaili-agent-tools setup --npx
setup 只打印模板，不写配置、不验证 Key、不安装 Skill。环境变量应填在实际生效的客户端配置中，不能假定它能继承另一个终端的设置。
7. 更新与迁移
源码方式在工具目录执行：
git pull --ff-only
npm ci
node dist/src/index.js install --agents codex,cursor --scope user
客户端和范围请换成原来的选择。npx 用户取得新版本后，重复原安装命令即可；如果仍下载到旧版本，可改用源码方式更新。
继续只读时，更新命令必须继续包含 --readonly。 更新后重新加载客户端并查询余额。一体安装保存的是独立运行时，仅更新源码而不重新执行 install，不会更新客户端实际使用的版本。
旧 MCP 用户应检查用户级和项目级配置是否还指向旧名称或目录，确认新服务可用后再移除旧项。迁移 Node.js 路径后需重新安装；当前没有一键卸载或历史运行时、备份自动清理功能。
8. 常见问题
| 情况 | 处理方法 |
|---|---|
| 找不到 Node、npm、npx 或 Git | 完成环境安装，检查 PATH，重新打开终端和客户端。 |
npm ci 找不到 package.json | 先进入克隆后的项目根目录。 |
| Key 验证失败或安装超时 | 核对网站 API Key 和网络；失败时不会写入配置，恢复后重试。 |
| 提示同名配置冲突 | 查看已有修改，确认需要替换后再使用 --replace。 |
| 安装完成但没有 Skill 或工具 | 重新加载客户端，检查安装范围、技能支持和当前会话权限；手动 MCP 配置不含 Skill。 |
提示缺少 QQDL_TOKEN | 在实际生效的客户端 MCP 环境配置中填写 Key。 |
| 找不到购买、续费或修改工具 | 检查是否启用了 --readonly，以及客户端是否禁用写工具。 |
| 写操作超时、待确认或状态不明 | 先核对预览或网站记录，不能靠连续重试处理。 |
| 更新后仍是旧版本 | 检查下载版本与实际启动路径，重跑安装并重启客户端。 |
更多参数、工具名称和开发说明请查看项目文档。
