name: namecheap
description: 通过Namecheap API管理在其注册的域名的DNS记录。列出域名，查看/添加/更新/删除DNS主机记录（A、AAAA、CNAME、MX、TXT等），并指导用户完成API设置，包括公网IP检测和凭据配置。当用户提到Namecheap、DNS记录、域名管理，或想要为他们的域名添加/更改/删除A记录、CNAME记录、MX记录或TXT记录时使用。

Namecheap DNS 管理

工具技能 — 通过 Namecheap API 管理 DNS 记录。

适用场景："添加 DNS 记录"、"更新 A 记录"、"管理 Namecheap 域名"、"设置 CNAME"、"添加 MX 记录"、"添加 TXT 记录"、"列出我的域名"、"显示 DNS 记录"、"namecheap 设置"、"配置 namecheap API"、"我的公网 IP 是什么"

不适用场景：域名注册/购买、SSL 证书管理、主机配置、非 Namecheap DNS 提供商

工作流程

首次设置

在执行任何 API 命令之前，请验证凭据是否已配置：

1. 检查现有配置 — 查找 ~/.namecheap-api
2. 如果未配置，引导用户完成设置：

a. 显示公网 IP — 运行 python3 namecheap.py public-ip 以显示用户的公网 IP

b. 指示 IP 白名单 — 告诉用户前往 https://ap.www.namecheap.com/settings/tools/apiaccess/，启用 API（选择 ON），并将显示的 IP 添加到白名单

c. 让用户自己运行设置 — 要求用户直接在 他们自己的终端 中运行 python3 namecheap.py setup。该脚本会提示输入用户名，并通过隐藏提示（getpass）读取 API 密钥，写入 ~/.namecheap-api（权限为 chmod 600），并验证连接。切勿要求用户将 API 密钥粘贴到聊天中，也切勿记录、回显或显示 API 密钥的值。 如果您无法为用户运行交互式终端，请指导他们自行运行 setup，或者在其自己的 shell 中导出 NAMECHEAP_API_USER 和 NAMECHEAP_API_KEY 环境变量 — 而不是通过 ask_user 收集密钥。

d. 确认 — 用户报告设置成功后，继续执行 DNS 操作。

DNS 操作

所有 API 交互均使用本技能目录中捆绑的 namecheap.py 脚本。它仅需要 Python 3（仅标准库 — 无需 pip install），并且在 macOS、Linux 和 Windows 上均可运行：

# 显示公网 IP（用于设置）
python3 namecheap.py public-ip

# 运行设置流程
python3 namecheap.py setup

# 列出域名
python3 namecheap.py domains.getList

# 获取域名的名称服务器（显示是否使用 Namecheap DNS 或自定义 DNS）
python3 namecheap.py domains.dns.getList --domain example.com

# 获取域名的 DNS 记录
python3 namecheap.py domains.dns.getHosts --domain example.com

# 添加单条记录（保留现有记录）
python3 namecheap.py dns.addHost --domain example.com --type A --name www --address 1.2.3.4 --ttl 1800

# 删除单条记录
python3 namecheap.py dns.removeHost --domain example.com --type A --name www --address 1.2.3.4

# 从 JSON 文件替换所有记录
python3 namecheap.py domains.dns.setHosts --domain example.com --hosts records.json

# 切换到 Namecheap 默认 DNS
python3 namecheap.py domains.dns.setDefault --domain example.com

# 切换到自定义名称服务器
python3 namecheap.py domains.dns.setCustom --domain example.com --nameservers ns1.cloudflare.com,ns2.cloudflare.com

# 获取邮件转发规则
python3 namecheap.py domains.dns.getEmailForwarding --domain example.com

# 设置邮件转发（单条规则）
python3 namecheap.py domains.dns.setEmailForwarding --domain example.com --mailbox info --forward-to user@gmail.com

# 设置邮件转发（从 JSON 文件）
python3 namecheap.py domains.dns.setEmailForwarding --domain example.com --forwards forwards.json

# 创建子名称服务器（胶水记录）
python3 namecheap.py domains.ns.create --domain example.com --nameserver ns1.example.com --ip 1.2.3.4

# 删除子名称服务器
python3 namecheap.py domains.ns.delete --domain example.com --nameserver ns1.example.com

# 获取名称服务器信息
python3 namecheap.py domains.ns.getInfo --domain example.com --nameserver ns1.example.com

# 更新名称服务器 IP
python3 namecheap.py domains.ns.update --domain example.com --nameserver ns1.example.com --old-ip 1.2.3.4 --ip 5.6.7.8

JSON 文件格式

domains.dns.setHosts --hosts records.json 需要一个对象数组，字段名与 Namecheap API 一致：

[
  { "HostName": "@", "RecordType": "A", "Address": "1.2.3.4", "TTL": 1800 },
  { "HostName": "www", "RecordType": "CNAME", "Address": "@", "TTL": 1800 },
  { "HostName": "@", "RecordType": "MX", "Address": "mail.example.com.", "TTL": 1800, "MXPref": 10 }
]

domains.dns.setEmailForwarding --forwards forwards.json 需要一个邮箱规则数组：

[
  { "MailBox": "info", "ForwardTo": "team@example.net" },
  { "MailBox": "sales", "ForwardTo": "owner@example.net" }
]

行为

• 始终先检查凭据。 在执行任何 API 操作之前，验证 ~/.namecheap-api 是否存在且可读。如果不存在，则运行设置流程。
• 在修改前显示当前记录。 在添加或删除记录之前，始终先获取并显示当前的 DNS 记录，以便用户确认更改。
• 使用 ask_user 确认破坏性更改。 在删除记录或使用 setHosts 替换所有记录之前，请与用户确认。
• Namecheap 的 setHosts API 会替换所有记录。 除非您已先获取所有现有记录，否则切勿直接调用 domains.dns.setHosts。请使用 dns.addHost 和 dns.removeHost 安全地进行单条记录操作 — 它们内部处理了获取-修改-写入的循环。
• 用人类可理解的方式解释 TTL。 当用户询问 TTL 时，解释 1800 = 30 分钟，3600 = 1 小时等。
• 处理多部分 TLD。 像 example.co.uk 这样的域名，SLD=example，TLD=co.uk。该脚本内置了一个常见二级后缀列表（例如 co.uk、com.au、co.jp、com.br）。此列表是尽力而为的，并非完整的公共后缀数据库 — 如果具有未列出的多部分后缀的域名返回 2019166（"未找到域名"）错误，则可能是 SLD/TLD 分割错误。在这种情况下，请与用户确认已注册的域名，并报告此限制。

凭据存储

凭据存储在 ~/.namecheap-api 中：

NAMECHEAP_API_USER="username"
NAMECHEAP_API_KEY="api-key-here"

此文件必须具有 600 权限（仅所有者可读写）。或者，脚本从 NAMECHEAP_API_USER 和 NAMECHEAP_API_KEY 环境变量读取凭据，当两者都设置时，环境变量优先于文件。

支持的记录类型

A、AAAA、CNAME、MX、MXE、TXT、URL、URL301、FRAME

参考

完整 API 文档（包括请求/响应格式）请参见 references/namecheap-api.md。