批量域名查询工具

本工具不仅提供网页查询，也提供面向 AI Agent、Claude Code、脚本和自动化工作流的批量域名查询接口。项目内已附带可选 Skill：skills/domain-availability-checker/SKILL.md，用于告诉智能体如何安全分批、低压轮询、解释结果并输出推荐。

什么时候使用 Skill？

• 如果只是临时脚本或普通开发者调用，直接使用 /api/check 即可。
• 如果希望 AI Agent 自动生成候选域名、分批查询、重试超时并做价值筛选，建议加载本项目的 domain-availability-checker Skill。
• Skill 不替代 API，它是给 AI 的使用手册：说明何时调用、如何限流、如何处理 timeout，以及如何给用户汇总结果。

1. 普通 API 调用

• 接口地址：/api/check
• 请求方式：POST
• 请求数据类型：application/json
• 批量上限：接口最多 60 个域名一批；大量查询建议 25 个一批并串行调用。
• 普通请求：Worker / Proxy 会自动处理上游会话，调用方通常只需要传 domains。

  {
    "domains": ["apple.ai", "banana.io", "google.com"]
  }

• 返回结构：

  [
    {"status":"success","result":"available","domain":"apple.ai"},
    {"status":"success","result":"unavailable","domain":"banana.io"},
    {"status":"success","result":"timeout","domain":"testxyz12345.com"}
  ]

2. 状态语义

• available：当前看起来可注册。
• unavailable：当前看起来已注册或不可注册。
• wait：上游仍在处理，仅在请求中加入 allowWait: true 时返回。
• timeout：本轮没有落定。不要把它当作已注册，应单独列为“稍后重试”。

3. AI Agent / Skill 执行策略

1. 候选生成：把用户的自然语言规则转成域名列表，例如“三位数字 .ai”生成 000.ai 到 999.ai。
2. 输入校验：只提交合法完整域名；不要把非法字符静默改造成另一个域名。
3. 低压分批：大量查询建议 25 个一批、串行请求，批次之间稍作等待，避免触发上游限流。
4. 结果解释：优先展示 available；timeout 单独列出，说明需要稍后复查。
5. 价值筛选：对可注册域名按短、好记、好读、关键词匹配、数字规律、品牌契合度等维度给出简短推荐理由。

4. 高级低压轮询

普通调用不需要管理 Cookie。如果脚本或 Agent 希望接收中间态 wait 并自行轮询，请使用以下契约：

1. 先调用 GET /api/session 获取 cookie。
2. 为同一批次生成稳定的 session 字符串。
3. 首次请求带 allowWait: true。
4. 后续只对仍为 wait 的域名请求，带 isPoll: true，并复用同一个 session 与 cookie。
5. 轮询间隔建议使用退避：约 2s、3.5s、5s、6.5s；不要高频死循环。

{
  "domains": ["testxyz12345.com"],
  "session": "stable_batch_session_001",
  "cookie": "WHMCS...; ipaddress=...",
  "allowWait": true,
  "isPoll": true
}

5. Tool 定义示例

如果你在自定义 Agent 中声明工具，可使用类似结构：

{
  "name": "check_domains",
  "description": "批量查询域名可用性。适合在用户需要寻找、生成或筛选可注册域名时调用。大量查询应低压分批，timeout 需单独列为待复查。",
  "input_schema": {
    "type": "object",
    "properties": {
      "domains": {
        "type": "array",
        "items": { "type": "string" },
        "description": "完整域名列表，例如 [\"getabc.ai\", \"gochat.io\", \"mycode.com\"]"
      }
    },
    "required": ["domains"]
  }
}

6. cURL 快速查询

curl -X POST http://localhost:5174/api/check \
  -H "Content-Type: application/json" \
  -d '{"domains":["apple.ai","google.com","testxyz12345.com"]}'

接口会先执行 DNS 预过滤，再对未解析域名进行低频 WHOIS 查询，以 JSON 返回本轮可确认状态。