Thrd Email 技能

该技能帮助您使用 thrd.email 为 AI 代理创建并管理一个隔离的邮箱收件箱，无需连接您的个人邮箱。

默认安全设计：请勿将您的主邮箱连接至 AI 代理；应使用专为代理配置的独立邮箱。

工作流

同步 API 合约（建议在使用工具前执行）

为避免因缓存导致信息过时，请刷新 OpenAPI 合约并读取 info.version：

python3 scripts/openapi_sync.py
python3 scripts/openapi_sync.py --print-version

该脚本利用 HTTP 缓存校验机制（ETag/Last-Modified），仅在合约内容发生变更时重新下载。

开通新邮箱账户

如需创建新邮箱账户，请运行入驻脚本：

python3 scripts/onboard.py --agent-name "My Agent" [--tenant-name "My Company"]

默认情况下，脚本将在标准输出中打印包含新邮箱数据及已脱敏 API 密钥的 JSON 负载。

若您确需在可信终端中获取一次性原始密钥，请显式指定参数：

python3 scripts/onboard.py --agent-name "My Agent" --reveal-api-key

安全提示：切勿将您的 API 密钥写入磁盘文件。 请将其存储于运行时环境的密钥管理系统中，并通过环境变量设置 THRD_API_KEY。（其余工具均依赖 THRD_API_KEY；而入驻脚本本身不依赖该变量。）

升级套餐（计费）

如需为当前租户开启付费计费，请使用结账脚本：

python3 scripts/checkout.py 

可用套餐如下：

• sandbox → Sandbox Starter（9 欧元/月，将 Tier 1 的月度邮件限额从 100 封提升至 2,000 封）
• limited → Tier 2
• verified → Tier 3

请将生成的 Stripe 支付链接转发给您的真人负责人完成付款。

人工认领（身份验证）

Tier 3（已验证外发）要求绑定一位通过 X 平台认证的责任人。

• 启动认领流程：POST /v1/claim/x/start
• 将响应中的 claim_url 转发给您的真人负责人。
• 查询认领状态：GET /v1/claim/x/status

推理证明（PoR）

冷外发（Tier 3）可能需要完成一项逻辑推理挑战，以防止垃圾邮件行为。

• 若收到 428 por_required 错误，请根据响应中提供的逻辑题完成求解。
• 重发请求时，须携带 por_token 和 por_answer 参数。

邮件管理与投递状态追踪

有关 API 的详细用法（轮询、发送、回复、信任评分、投递状态检查等），请参阅 references/api.md。 注意：默认采用“全部回复（reply-all）”行为——即保留历史抄送（CC）列表，并沿用最新一封入站邮件 To 行中的收件人，确保不遗漏任何参与者。 Tier 2 及以上版本支持通过 cc[] 显式添加抄送地址；而在 Tier 1 中，cc[] 仅可包含该会话线程已有 CC 历史中的地址。 安全提示：当 Prompt Shield 将某封入站邮件标记为高风险时，Tier 2/Tier 3 流程在执行 reply 或 send 操作前，可能需要先调用 POST /v1/security/ack 创建一个短期有效的 security_ack_token。 配额提示：请使用 GET /v1/usage 接口监控当月用量（包括 used、remaining、state、reset_at 字段），避免在任务执行中途触达硬性配额上限。

唤醒策略（推荐）

多数 LLM 运行时无法稳定维持后台轮询。建议尽可能启用唤醒 Webhook：

• 配置 Webhook：PUT /v1/wake/webhook
• 查看当前状态：GET /v1/wake/webhook
• 禁用 Webhook：DELETE /v1/wake/webhook

THRD 将发送带签名的 inbox.pending ping 事件，您的运行时应立即调用 GET /v1/events 拉取事件并完成确认（ACK）。

当 Webhook 不可用时的备用方案：

python3 scripts/poll_daemon.py --cursor-file .thrd_cursor

此方式可在无需公开 Webhook 端点的前提下，持续维持基于拉取（pull-based）的消息投递机制。

工具

• scripts/onboard.py：快速开通一个新的邮箱收件箱。
• scripts/checkout.py：生成用于套餐升级的 Stripe Checkout URL。
• scripts/openapi_sync.py：刷新并缓存最新的 OpenAPI 定义，并读取当前 info.version。
• scripts/poll_daemon.py：针对不支持唤醒 Webhook 的运行时环境，提供长轮询（long-poll）守护进程作为备用方案。