外贸获客AI润色邮件

概述

iReach 邮件润色（积分版）

把一封已经写好的邮件交给本技能，得到一封表达更专业、更得体的版本。事实、诉求与承诺完全不变。

本技能只有一条调用通道：API Key + 点数（积分）扣费。真正调用之前先用 --quote 报价、经用户确认；调用发起时按服务端为该技能配置的点数单价预扣，成功后结算、业务失败自动返还；无每日调用次数限制，每次成功调用消耗的点数与结算后余额由响应里的 credit 块给出。本技能是积分通道的独立技能：按次付费那套（微信 Agent Pay）是另一个 slug（ireach-ai-email-polish-pay）的历史通道，本技能既不依赖它，也不是同一个技能的升级版。

什么时候用

• 用户要批量润色邮件（如把一批草稿统一改成正式商务风格）
• 用户需要连续润色多封邮件（如按不同收件人、不同语种批量出稿）
• 用户要求润色、改写、优化一封邮件
• 用户说「帮我看看这封邮件写得怎么样」「改得更正式一点」

执行流程

按以下顺序执行，每一步的细节见对应章节：

1. 取 API Key：读技能目录（SKILL.md 与 config.json 所在目录）下 config.json 的 IREACH_API_KEY，回退环境变量 IREACH_API_KEY；两者任一有值即就绪。都没有时，先按「鉴权」引导用户取 Key 并写回，拿到之前不要运行脚本（只有 --quote 查单价不受此限——它不需要 Key，见下一步）。
2. 向用户确认点数：先以 --quote 查出本次将消耗的点数，明确告知用户（例如「本次将消耗 10 点」），得到用户明确同意后才能发起真正的调用；用户未确认、或表示再想想，就不要调用。报价不需要 API Key，Key 还没配好时也能先报价；话术见「调用前怎么说（先报价、再等确认）」。
3. 确认输入与参数：--email-content（待润色的邮件内容）必填，其余参数按「参数取值表」取，不要凭记忆编造取值；润色非英文邮件时记得显式传 --language（缺省是英语）。
4. 调用：脚本一次调用内完成鉴权、扣点与生成（命令见「用 API Key 调用」）。只需要带 Key 这一个鉴权头，不要再携带任何按次付费相关的请求头。
5. 交付并转述扣点：把标题与正文交给用户，并按响应里的 credit 块如实转述本次消耗的点数与结算后余额；credit 缺失时不提点数，不要编造。

任一步异常按「异常处理」对号入座，不要自行判定失败。

鉴权

Key 取技能目录（SKILL.md 与 config.json 所在目录）下 config.json 里的 IREACH_API_KEY 字段，回退到环境变量 IREACH_API_KEY；两者任一有值即视为就绪。config.json 形如：

{ "IREACH_API_KEY": "你的密钥" }

请求头以 X-API-Key 为推荐（后端两种都收，推荐第一种）：

X-API-Key: ck_live_xxxxxxxx

Authorization: Bearer ck_live_xxxxxxxx

推荐 X-API-Key：后端 SkillCreditGuard 读的就是这个名字；而 Authorization 在网关 / 代理层常被别的中间件占用，写成裸 Authorization: <key>（不带 Bearer）更容易被拦下或改写。不要写成裸 Authorization。

运行脚本前，先按下面四步确认 Key 就绪。任何时候都不要编造或猜测 Key。

1. 检查是否已有 Key。 读技能目录下的 config.json，看 IREACH_API_KEY 是否为非空字符串；没有再看环境变量 IREACH_API_KEY。任一有值即视为就绪，直接进入后续流程——脚本按同样顺序取 Key，所以你通常不需要手动传 --api-key。
2. 缺失则引导用户获取。 都没有时停下来，提示用户前往积分中心 <https://www.ireach.cc/credit>：用手机号 + 短信验证码登录 → 在「API Key」里创建一把（明文只显示这一次，要当场复制保存，关掉就只能重置）。让用户把拿到的 Key 直接发给你；在拿到 Key 之前不要运行脚本——不带 Key 的生成请求必然是 401，白跑一趟（--quote 只查单价、不需要 Key，随时可以先跑）。
3. 拿到后写回。 收到 Key 后，把它写入技能目录下 config.json 的 IREACH_API_KEY 字段（保留文件其它内容），然后再运行脚本。用户只配置这一次，之后调用不必再向他索取。
4. 鉴权失败时（HTTP 401 CREDIT_KEY_REJECTED）。 多半是 Key 被吊销或写错了。提示用户重新到积分中心获取一把新 Key，按第 3 步覆盖写入 config.json 后重试；不要拿同一个失效 Key 反复重跑——重跑多少次都还是 401。

⚠️ config.json 是本机凭据文件：不要提交到 git、不要贴进日志、不要分享出去。它随包发布时只是一个空占位（"IREACH_API_KEY": ""），真实 Key 只留在使用者本机。

缺少 API Key 时怎么说

用户还没有 Key 时，把下面这段直接发给他（第一句按本技能的能力替换即可）：

润色邮件调用的是远端的付费生成服务，首次使用得先配置一把 API Key 🔑

👉 打开积分中心，用手机号 + 短信验证码登录后在「API Key」里创建一把：https://www.ireach.cc/credit

（Key 的明文只显示这一次，记得当场保存；关掉就看不到了，只能重置）

拿到 Key 后直接粘贴发给我，我帮你存好，以后就不用再管它了。

这个服务按点数计费，余额不足时我会提醒你。

调用前怎么说（先报价、再等确认）

每一次真正调用之前，都先按「执行流程」第 2 步报价，把点数明确告诉用户。点数取 --quote 的实际输出，可以照下面这段话来问（示例里的数字来自服务端，不要在回答里写死）：

本次将消耗 10 点（点数由服务端按技能配置，实际以调用结果为准）。是否继续？

• 用户没明确说「继续 / 可以 / 确认」之前，不要调用。「先看看」「你觉得呢」都不算同意。
• 用户表示再想想、或直接拒绝时：不要调用，并如实说明「本次没有调用、也没有扣点」。
• 用户同意后再进入「执行流程」第 4 步调用。报价只是预估：最终实际消耗以成功响应里的 credit.points 为准（服务端可能调价），按第 5 步如实转述。

报价命令（不需要 API Key：只读单价，不扣点、不调用生成接口）：

python3 scripts/polish_email.py --quote
# 本次将消耗 10 点（单价由服务端配置，实际以调用结果里的 credit 块为准）。确认后我再发起调用。

它请求的是 GET https://www.ireach.cc/jeecg-boot/openapi/skill/ai/polish/credit/price，成功时返回 data.pointsPerCall。因为不需要 Key、也不扣点，Key 还没配好时也能先报价。报价失败（该技能未开放按点调用 / 技能不存在或未部署 / 网络不通）时按「异常处理」对号入座，不要因此发起调用。

唯一的调用通道：API Key + 点数（积分）扣费

没有免费阶段：本技能不提供免费试用，不带 Key 的请求一律被拒（HTTP 401，CREDIT_KEY_REJECTED）——不存在"先免费试润一封"这一步。

用 API Key 调用

Key 从哪来见「鉴权」：技能目录 config.json 的 IREACH_API_KEY，回退环境变量 IREACH_API_KEY。都没有就先按「鉴权」把 Key 拿到并写回，别急着发起调用（不带 Key 必然是 401，白跑一趟）。

请求头二选一（推荐第一种）：

X-API-Key: ck_live_xxxxxxxx

Authorization: Bearer ck_live_xxxxxxxx

完整请求示例（路径就写这一段，不要加域名前缀）：

POST /openapi/skill/ai/polish/credit
X-API-Key: ck_live_xxxxxxxx
Content-Type: application/json

{
  "emailContent": "你好，我想要知道你们的产品价格，还有能不能便宜一点。",
  "language": "英语",
  "tone": "正式商务",
  "wordCount": "300字（词）以内"
}

只需要带上面这一个 Key 头：除它之外不要再携带任何按次付费相关的请求头——本技能只提供积分通道，带上那些头只会让服务端按别的语义处理这次请求，那不是你要的结果。

脚本 scripts/polish_email.py 封装了这次请求，命令参数与上面 body 的字段一一对应：

python3 scripts/polish_email.py 
  --email-content "你好，我想要知道你们的产品价格，还有能不能便宜一点。" 
  --language "英语" 
  --tone "正式商务" 
  --word-count "300字（词）以内"

上面这条命令没有传 --api-key：脚本会依次读技能目录 config.json 的 IREACH_API_KEY、环境变量 IREACH_API_KEY。需要显式覆盖时（例如自动化 / CI 场景，或本机临时换一把 Key）再加 --api-key ck_live_xxxxxxxx，它的优先级最高。

报价（--quote）单独一条命令，不需要 Key：它只读服务端为该技能配置的点数单价，不扣点、不调用生成接口，所以 Key 还没配好时也可以先跑：

python3 scripts/polish_email.py --quote

输出是一句话（点数取接口返回的 data.pointsPerCall，不要写死）：「本次将消耗 10 点（单价由服务端配置，实际以调用结果里的 credit 块为准）。确认后我再发起调用。」把它转述给用户、拿到确认后再执行上面的调用命令（见「调用前怎么说（先报价、再等确认）」）。

成功响应（HTTP 200，code 为 SUCCESS）：

{
  "code": "SUCCESS",
  "message": "",
  "data": { "subject": "邮件标题", "content": "Markdown 正文" },
  "credit": { "points": 10, "balanceAfter": 90, "bizNo": "CC2026..." }
}

credit 是本次调用的点数结算信息，只在积分通道调用成功时出现：

点数单价由服务端按技能配置，不要在回答里写死具体点数（改价只需改数据库一行、不发版）。把 credit 如实转述给用户，例如「本次消耗 10 点，余额 90 点」——点数一律取 credit.points 与 credit.balanceAfter 的实际值。credit 字段缺失时就不要提点数，不要编造。

点数是预扣后结算的：调用发起时先按单价预扣，业务失败会自动返还，不需要也不能让用户手工申请退款。若因余额不足被拒绝，如实告知「点数不足」，不要重复重试。

错误码（三种都必须如实转述给用户，不要自行改写文案）：

用户没有 Key 时，引导他自取，不要替他申请（Key 绑在用户自己的账号上，你无法代建）：

1. 打开服务方提供给你的积分中心入口，用手机号 + 短信验证码登录；
2. 在「API Key」里创建一把，明文只显示这一次，要当场复制保存（关掉就再也看不到，只能重置）；
3. 把 Key 配到你的调用头里。

⚠️ 若积分中心入口当前不可用：不要让用户反复重试，不要自行猜测或编造网址，

也不要改用按次付费顶上（本技能只有积分通道，按次付费是另一个 slug 的历史通道）。如实告知「当前无法自助获取 API Key」，并请用户联系服务方获取。

未携带 Key 时的服务端原文

不带 Key 的调用会得到下面这条 401，可以原样转述给用户：

该技能按点数（积分）计费，需要 API Key：请在请求头携带 X-API-Key；还没有 Key 时，请先到积分中心用手机号登录并创建一把

参数取值表

--email-content 是必填（只有 --quote 查单价时可以不传）；--api-key 一般不用传（脚本自己从 config.json 或环境变量取，见「鉴权」），其余参数都可省略（省略即用服务端默认值）。不要凭记忆编造取值，下面列出的就是全部合法值。

⚠️ --language 的缺省是「英语」，不是「保持原语言」。若用户的邮件是德语、日语或中文，而你没有传 --language，输出会被润色成英文——这与「不改变原意」的预期不符。除非用户明确要求改成英文，否则请显式传入原邮件的语言（例如 --language "德语"）。--tone 的缺省则相反：留空表示保持原邮件的语气。

--api-key 不属于生成条件，只用于鉴权与扣点，不会出现在提示词里。

--quote 是纯查询开关：只读服务端单价并打印一句话，不产生扣点、也不需要 Key，因此 Key 还没配置好时也能先报价；它的退出码只用 0 / 1，见「异常处理」。

结果解读

• 输出为「邮件标题 + 正文」，正文是 Markdown 纯文本，可直接复制到邮件客户端或再加工。
• 原邮件的事实、诉求与承诺完全保留，只优化表达、语法、用词与结构。
• 正文语言由 --language 决定（缺省英语，见上方警示），与你在对话中使用的语言无关。
• 如果正文里出现的是原始文本而不是排版好的内容，说明服务端未拿到结构化结果，已自动降级返回，内容仍可用。
• 每次调用都是一次独立的生成与一次独立扣点，没有"重复取件"这一步（幂等取件是按订单取回同一份结果的机制，属于另一个 slug 的按次付费链路；本技能不建单，也就没有订单可重复取回）。

计费与限额说明

• 调用前先报价、用户同意才扣点：真正调用之前先用 --quote 查出本次点数并请用户确认（见「调用前怎么说（先报价、再等确认）」），用户同意之后才会发起调用、才可能扣点；用户不同意就不要调用，也就不会有任何扣点。
• 按点数（积分）计费：每次成功调用按服务端为该技能配置的点数单价扣点，无每日调用次数限制。
• 点数单价由服务端按技能配置，本技能包不写死；每次调用的实际消耗与结算后余额以响应里的 credit 块为准。
• 点数为预扣后结算：调用发起时先按单价预扣，业务失败会自动返还，不需要也不能让用户手工申请退款。
• 服务端为这三个 AI 技能设有按日额度的限流分桶，触发时返回 429 / RATE_LIMITED；如实告知用户稍后再试，等待约 1 分钟后重试即可。

异常处理

脚本用退出码区分「拿到了可用信息」和「这次没拿到」：

• 0：服务端给出了可操作结果（成功、缺 Key / Key 无效、业务拒绝、触发限流等）——这些结果都带有明确的下一步
• 1：网络或解析失败，或服务端返回 404 / 5xx 这类环境不可用
• 2：没取到 API Key——--api-key、技能目录 config.json 的 IREACH_API_KEY、环境变量 IREACH_API_KEY 三级都没有（脚本会打印含积分中心链接的引导话术），或命令行参数用法错误（由 argparse 直接结束）。两者都属于"命令没配好"，不是业务失败，不要当作重试信号

注意 401 在本技能里不是"环境不可用"，而是可操作的业务态：本技能按点数计费，没带 Key 就是 401，提示用户去取 Key 即可（所以退出码是 0）。

退出码为 1 时，不要把输出当成生成结果。

--quote（只查单价）的退出码只用 0 和 1：0 = 报价拿到了；1 = 报价没拿到（400 该技能未开放按点调用 / 404 技能不存在或未部署 / 网络或解析失败，都属环境或配置问题）。报价不需要 Key，所以不会出现退出码 2，2 只属于真正调用那一路。

能力边界

• 只做「在不改变原意的前提下润色一封邮件」。
• 不改变事实、诉求与承诺；不做翻译以外的内容增删（指定语言时会输出该语言的版本）。
• 不支持多轮改写、不保存任何历史、不支持批量返回多封；每次调用相互独立。
• 没有免费阶段：不带 API Key 一律 401。
• 需要基于上一版继续调整时，请把上一版正文作为新的输入重新描述需求（会产生一次新的扣点）。
• 点数单价、扣费与失败返还全部由服务端负责，技能包不写死单价；每次调用的消耗与余额以响应里的 credit 块为准。
• 生成内容仅供参考，发送前请自行核对事实、价格与承诺。