名称： gandi
描述： "全面的 Gandi 域名注册商集成，用于域名和 DNS 管理。注册和管理域名，创建/更新/删除 DNS 记录（A、AAAA、CNAME、MX、TXT、SRV 等），配置电子邮件转发和别名，检查 SSL 证书状态，创建用于安全回滚的 DNS 快照，批量更新区域文件，以及监控域名过期。支持多域名管理、区域文件导入/导出和自动化 DNS 备份。包含只读和具有安全控制的破坏性操作。"
元数据： {"openclaw":{"disable-model-invocation":true,"capabilities":["dns-modification","email-management","domain-registration","destructive-operations"],"credentials":{"type":"file","location":"~/.config/gandi/api_token","description":"Gandi 个人访问令牌 (PAT)","permissions":600},"requires":{"bins":["node","npm"]}}}

Gandi 域名注册商技能

为 Moltbot 提供的全面 Gandi 域名注册商集成。

状态： ✅ 第 2 阶段完成 - DNS 修改和快照功能已就绪

⚠️ 安全警告

此技能可对您的 Gandi 账户执行破坏性操作：

• DNS 修改： 添加、更新或删除 DNS 记录（可能导致网站/电子邮件中断）
• 电子邮件管理： 创建、修改或删除电子邮件转发（可能拦截邮件）
• 域名注册： 注册域名（会产生财务交易）
• 批量操作： 一次性替换所有 DNS 记录（除非通过快照，否则无法撤销）

在运行任何脚本之前：
1. 审查脚本代码以了解其功能
2. 在进行批量更改前创建 DNS 快照 (create-snapshot.js)
3. 尽可能使用只读个人访问令牌
4. 先在非生产域名上测试
5. 了解某些操作无法撤销

破坏性脚本 (⚠️ 修改或删除数据)：
- add-dns-record.js、delete-dns-record.js、update-dns-bulk.js
- add-email-forward.js、update-email-forward.js、delete-email-forward.js
- restore-snapshot.js (替换当前 DNS)

只读脚本 (✅ 安全，无修改)：
- list-domains.js、list-dns.js、list-snapshots.js
- list-email-forwards.js、check-domain.js、check-ssl.js

📖 完整的脚本文档： 请参阅 SCRIPTS.md 以获取详细信息，包括：
- 每个脚本的功能
- 网络操作和 API 调用
- 安全影响
- 撤销/恢复流程
- 审计工作流建议

当前功能

第 1 阶段 (已完成)

• ✅ 个人访问令牌认证
• ✅ 列出账户中的域名
• ✅ 获取域名详情（到期日、状态、服务）
• ✅ 列出域名的 DNS 记录
• ✅ 查看域名和 DNS 信息
• ✅ 域名可用性检查 (#4)
• ✅ 带变体的智能域名建议 (#4)
• ✅ SSL 证书状态检查器
• ✅ 错误处理和验证

第 2 阶段 (已完成)

• ✅ 添加/更新 DNS 记录 (A、AAAA、CNAME、MX、TXT、NS、SRV、CAA、PTR)
• ✅ 删除 DNS 记录
• ✅ 批量 DNS 操作 (一次性替换所有记录)
• ✅ DNS 区域快照 (创建、列出、恢复)
• ✅ 电子邮件转发 (创建、列出、更新、删除转发，包括全收转发)
• ✅ 记录验证 (自动验证每种记录类型)
• ✅ 安全功能 (批量更改前自动创建快照、确认提示)

即将推出 (第 3 阶段及以后)

• 域名注册
• 多组织支持 (#1)
• Gateway Console 配置 (#3)
• 域名续期管理
• DNSSEC 配置
• 证书管理
• 电子邮件邮箱管理（超越转发功能）

设置

步骤 1：创建个人访问令牌

⚠️ 安全建议： 根据您的用例使用所需的最小权限范围。

1. 访问 Gandi 管理后台 → 个人访问令牌
2. 点击 "创建令牌"
3. 选择您的组织

4. 选择权限范围：

   只读 (推荐仅用于查看)：
   - ✅ Domain: read (列出域名所需)
   - ✅ LiveDNS: read (查看 DNS 记录所需)
   - ✅ Email: read (查看电子邮件转发所需)

   写入权限 (修改所需 - 谨慎使用)：
   - ⚠️ LiveDNS: write (启用 DNS 修改、删除、批量操作)
   - ⚠️ Email: write (启用电子邮件转发创建、更新、删除)

5. 复制令牌（之后将无法再次查看！）

安全最佳实践：
- 为只读和写入操作创建独立的令牌
- 日常检查/监控时使用只读令牌
- 仅在主动进行更改时使用写入令牌
- 定期轮换令牌（建议每 90 天）
- 立即删除未使用的令牌
- 切勿共享或将令牌提交到版本控制系统

步骤 2：存储令牌

脚本按优先级顺序检查凭据：
1. GANDI_API_TOKEN 环境变量 (优先检查)
2. ~/.config/gandi/api_token 文件 (环境变量未设置时的备用方案)

选择适合您工作流程的方法：

选项 A：环境变量 (推荐用于 CI/CD)

# 设置环境变量 (将 YOUR_PAT 替换为实际令牌)
export GANDI_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

# 添加到 shell 配置文件中以持久化 (~/.bashrc, ~/.zshrc 等)
echo 'export GANDI_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"' >> ~/.bashrc

优点：
- ✅ 适合 CI/CD (自动化的标准模式)
- ✅ 容器就绪 (无需挂载文件)
- ✅ 可与密码管理工具配合使用 (1Password、Vault 等)
- ✅ 易于在多个令牌之间切换

选项 B：基于文件 (推荐用于本地开发)

# 创建配置目录
mkdir -p ~/.config/gandi

# 存储您的令牌 (将 YOUR_PAT 替换为实际令牌)
echo "YOUR_PERSONAL_ACCESS_TOKEN" > ~/.config/gandi/api_token

# 保护文件权限 (仅所有者可读)
chmod 600 ~/.config/gandi/api_token

优点：
- ✅ 令牌在 shell 会话间持久存在
- ✅ 安全的文件权限 (0600 = 仅所有者可读)
- ✅ 无在进程列表中暴露令牌的风险
- ✅ 离线工作 (无外部依赖)

步骤 3：安装依赖项

要求： Node.js >= 18.0.0

cd gandi-skill/scripts

# 安装 npm 依赖项
npm install

# 验证安装
npm list --depth=0

预期包：
- axios (用于 Gandi API 的 HTTP 客户端)
- package.json 中列出的任何其他依赖项

故障排除：
- 如果 node 或 npm 未找到：从 nodejs.org 安装 Node.js
- 如果出现权限错误：不要使用 sudo - 修复 npm 权限或使用 nvm
- 如果包错误：删除 node_modules/ 和 package-lock.json，然后重新运行 npm install

步骤 4：测试认证

cd gandi-skill/scripts
node test-auth.js

预期输出：

✅ 认证成功！

您的组织：
  1. 个人账户 (uuid-here)
     类型：个人

🎉 您已准备好使用 Gandi 技能！

步骤 5：设置联系信息 (可选，用于域名注册)

如果您计划注册域名，请一次性保存您的联系信息以供重复使用：

cd gandi-skill/scripts
node setup-contact.js

脚本将提示输入：
- 姓名 (名和姓)
- 电子邮件地址
- 电话号码 (国际格式：+1.5551234567)
- 街道地址
- 城市
- 州/省 (美国：2 字母代码，如 OH，自动格式化为 US-OH)
- 邮政编码
- 国家 (2 字母代码：US、FR 等)
- 类型 (个人或公司)
- 隐私偏好： 注册后保留或自动清除联系人

联系信息保存至：
- ~/.config/gandi/contact.json
- 权限：600 (仅所有者可读写)
- 位于技能目录之外 (永不提交到 git)

隐私选项：

1. 保留 (默认)： 保存联系人供未来注册使用

   • 最适合频繁注册域名
   • 设置一次，永久使用
   • 随时可使用 delete-contact.js 手动删除

2. 清除： 每次注册后自动删除联系人

   • 最适合注重隐私的用户
   • 联系人信息仅在注册期间存在
   • 下次注册时必须重新输入

管理已保存的联系人：

# 查看当前联系人
node view-contact.js

# 更新联系信息或隐私偏好
node setup-contact.js

# 手动删除已保存的联系人
node delete-contact.js

# 无需确认直接删除
node delete-contact.js --force

一次性清除覆盖：

# 注册并删除联系人 (即使偏好是"保留")
node register-domain.js example.com --purge-contact

使用示例

列出您的域名

node list-domains.js

输出显示：
- 域名
- 到期日期
- 自动续期状态
- 服务 (LiveDNS、Email 等)
- 组织所有权

列出 DNS 记录

node list-dns.js example.com

输出显示：
- 按类型分组的所有 DNS 记录
- TTL 值
- 记录名称和值
- 名称服务器

在 Moltbot 中使用

配置完成后，您可以使用自然语言：

"列出我的 Gandi 域名"

"显示 example.com 的 DNS 记录"

"example.com 什么时候到期？"

"example.com 的自动续期启用了吗？"

域名可用性检查

检查单个域名

检查特定域名是否可用于注册：

node check-domain.js example.com

功能：
- 显示可用性状态 (可用/不可用/待定/错误)
- 显示价格信息 (注册、续期、转移)
- 列出支持的功能 (DNSSEC、LiveDNS 等)
- 显示 TLD 信息

示例输出：

🔍 正在检查可用性：example.com

域名：example.com

✅ 状态：可用

💰 价格：
  1 年：12.00 欧元 (+ 2.40 税)
  2 年：24.00 欧元 (+ 4.80 税)

📋 支持的功能：
  • create
  • dnssec
  • livedns

🌐 TLD 信息：
  后缀：com

智能域名建议

查找带有 TLD 变体和名称修改的可用替代方案：

# 检查所有配置的 TLD + 变体
node suggest-domains.js example

# 仅检查特定 TLD
node suggest-domains.js example --tlds com,net,io

# 跳过名称变体 (仅检查 TLD)
node suggest-domains.js example --no-variations

# 输出为 JSON 格式
node suggest-domains.js example --json

名称变体模式：
1. 连字符化： 在单词边界添加连字符 (example → ex-ample)
2. 缩写： 移除元音 (example → exmpl)
3. 前缀： 添加常见前缀 (example → get-example、my-example)
4. 后缀： 添加常见后缀 (example → example-app、example-hub)
5. 数字： 追加数字 (example → example2、example3)

示例输出：

🔍 正在检查可用性：example

📊 正在检查 13 个 TLD 并生成变体...

═══════════════════════════════════════════════════════
📋 精确匹配 (不同 TLD)
═══════════════════════════════════════════════════════

✅ 可用：

  example.net                    12.00 欧元
  example.io                     39.00 欧元
  example.dev                    15.00 欧元

❌ 不可用：

  example.com                    (不可用)
  example.org                    (不可用)

═══════════════════════════════════════════════════════
🎨 名称变体
═══════════════════════════════════════════════════════

连字符化：

  ✅ ex-ample.com                12.00 欧元

前缀：

  ✅ get-example.com             12.00 欧元
  ✅ my-example.com              12.00 欧元

后缀：

  ✅ example-app.com             12.00 欧元
  ✅ example-io.com              12.00 欧元

═══════════════════════════════════════════════════════
📊 摘要：找到 8 个可用域名
═══════════════════════════════════════════════════════

配置

域名检查器配置存储在 gandi-skill/config/domain-checker-defaults.json 中。

结构：

{
  "tlds": {
    "mode": "extend",
    "defaults": ["com", "net", "org", "info", "io", "dev", "app", "ai", "tech"],
    "custom": []
  },
  "variations": {
    "enabled": true,
    "patterns": ["hyphenated", "abbreviated", "prefix", "suffix", "numbers"],
    "prefixes": ["get", "my", "the", "try"],
    "suffixes": ["app", "hub", "io", "ly", "ai", "hq"],
    "maxNumbers": 3
  },
  "rateLimit": {
    "maxConcurrent": 3,
    "delayMs": 200,
    "maxRequestsPerMinute": 100
  },
  "limits": {
    "maxTlds": 5,
    "maxVariations": 10
  }
}

速率限制和限制：
- maxConcurrent： 最大并发 API 请求数 (默认：3)
- delayMs： 请求之间的延迟毫秒数 (默认：200ms)
- maxRequestsPerMinute： 每分钟请求数的硬性限制 (默认：100，Gandi 允许 1000)
- maxTlds： 在 suggest-domains.js 中要检查的最大 TLD 数量 (默认：5)
- maxVariations： 要生成的最大名称变体数量 (默认：10)

这些限制确保了良好的 API 使用规范，并防止对 Gandi 的 API 造成过大压力。

TLD 模式：
- "extend"：使用默认值 + 自定义 TLD (合并列表)
- "replace"：仅使用自定义 TLD (忽略默认值)

Gateway Console 集成：

当添加 Gateway Console 支持时 (#3)，配置将在此处可用：

skills:
  entries:
    gandi:
      config:
        domainChecker:
          tlds:
            mode: extend
            defaults: [...]
            custom: [...]
          variations:
            enabled: true
            patterns: [...]

有关完整的配置架构，请参阅 docs/gateway-config-design.md。

DNS 管理 (第 2 阶段)

添加或更新 DNS 记录

创建或更新单个 DNS 记录：

# 为根域名添加 A 记录
node add-dns-record.js example.com @ A 192.168.1.1

# 添加指向根域名的 www 子域名
node add-dns-record.js example.com www CNAME @

# 为电子邮件添加 MX 记录
node add-dns-record.js example.com @ MX "10 mail.example.com."

# 为 SPF 添加 TXT 记录
node add-dns-record.js example.com @ TXT "v=spf1 include:_spf.google.com ~all"

# 使用自定义 TTL (5 分钟) 添加
node add-dns-record.js example.com api A 192.168.1.10 300

支持的记录类型： A、AAAA、CNAME、MX、TXT、NS、SRV、CAA、PTR

删除 DNS 记录

移除特定的 DNS 记录：

# 删除旧的 A 记录
node delete-dns-record.js example.com old A

# 带确认提示删除
node delete-dns-record.js example.com test CNAME

# 无需确认删除
node delete-dns-record.js example.com old A --force

批量 DNS 操作

一次性替换所有 DNS 记录：

# 从 JSON 文件
node update-dns-bulk.js example.com new-records.json

# 从标准输入
cat records.json | node update-dns-bulk.js example.com

# 跳过自动快照
node update-dns-bulk.js example.com records.json --no-snapshot

# 跳过确认
node update-dns-bulk.js example.com records.json --force