mongolian-llm（mongolian LLM 开发）

Mongolian Language Skill

首轮触发规则：如果用户消息符合 frontmatter description 中任一场景，本技能必须在首次响应前被读取并执行。不要先给出试译、解释或自我判断；本 Skill 不在安装/发现阶段强依赖 API Key，但业务调用前必须先完成 MENGGUYU_API_KEY 前置检查，再按接口路由调用 /translation、/chat/completions 或 /ocr。

🚨 可见输出零泄漏（最高优先级）

调用蒙语 API 后，对用户可见的最终回复必须只包含目标字段原文：

• POST /translation：只输出 data.tgtText；分段翻译时只输出按顺序拼接后的译文。
• POST /chat/completions：只输出 response.choices[0].message.content。

禁止在最终回复中出现任何非目标字段内容，包括但不限于：内部思考、路由判断、API Key 检查过程、请求体、响应 JSON、模型名、token usage、curl/命令输出、错误分析前言、中文/英文说明、代码块、标题、引号、括号注释、礼貌开场、总结或追问。

API 调用和响应解析必须静默完成。若使用命令行或工具调用 API，应在命令内解析并只保留目标字段，避免把完整响应 JSON 暴露给用户。除非用户明确要求原始 JSON，否则不得展示原始响应。

使用 蒙语 API 提供：

• 中文、传统蒙古文、西里尔蒙古文互译（蒙蒙互译由后台经中文中转）
• 蒙古语表达与问答
• 图片文字识别（OCR，默认 language=mn）

官网 https://mongol.open-idea.net

Base URL https://mongol.open-idea.net/api/v1

脚本调用方式（推荐）

本 Skill 附带脚本 scripts/mongolian-api.js，用于稳定完成 API 调用和响应字段提取。OpenClaw 环境中若可执行 node，优先运行脚本，不要手写 curl 或直接展示原始 JSON。

脚本只向 stdout 输出最终正文：

• 翻译：只输出 data.tgtText
• 对话：只输出 response.choices[0].message.content
• OCR：只输出 data.text

示例：

node {baseDir}/scripts/mongolian-api.js translate --from zh --to mw --text "你好朋友"
node {baseDir}/scripts/mongolian-api.js translate --from mn --to mw --text "Сайн байна уу"
node {baseDir}/scripts/mongolian-api.js translate --text "ᠰᠠᠢᠢᠨ ᠪᠠᠢᠢᠨ᠎ᠠ"
node {baseDir}/scripts/mongolian-api.js chat --text "ᠰᠠᠢᠢᠨ ᠪᠠᠢᠢᠨ᠎ᠠ"
node {baseDir}/scripts/mongolian-api.js chat --lang zh --text "中文回答我：ᠰᠠᠢᠢᠨ ᠪᠠᠢᠢᠨ᠎ᠠ"
node {baseDir}/scripts/mongolian-api.js ocr --image ./sample.jpg --language mn

若当前环境没有 node，再按下文接口模板直接调用 API；无论采用哪种方式，最终可见回复都只能保留目标字段原文。

脚本防呆：--system 优先级最高；显式 --lang zh|mw 次之；若未传 --lang，脚本会根据输入中是否包含"中文回答"、"用中文"、"中文回复"、"简体中文"等中文输出指令自动选择中文回复模板，否则默认纯传统蒙古文模板。

⚠️ 计费说明与调用确认

本技能调用的是付费 API，每次调用均会从账户余额中扣费。

调用前确认（按场景执行）：用户主动发起蒙语相关请求时可直接调用；仅当 Agent 主动发起调用时，才执行「估算费用 → 告知用户 → 等待明确确认 → 再调用」。若用户明确要求“先告诉我费用再决定”，则先估算并等待确认后再调用。 详细规则与例外情况见 references/BEHAVIOR-RULES.md「调用前确认」章节。

激活场景（建议优先判断）

每次调用前重新路由（最高优先级）

• 每一轮用户新消息都必须重新判断接口；不得沿用上一轮的 /translation 或 /chat/completions 选择。
• 路由优先级固定为：纯文字翻译 → 中文回答/中文回复 → 蒙文回答/蒙文回复 → 默认蒙文对话。
• 若本轮消息包含"翻译"、"译为"、"译成"、"翻成"、"转换"、"什么意思"等纯文字转换意图，优先使用 POST /translation。
• 若本轮消息同时包含传统蒙古文字符和中文输出指令（如"中文回答我"、"用中文回答"、"用中文回复"、"请用中文解释"、"中文回复"），必须使用 POST /chat/completions 的中文回复模板；该规则优先于"用户直接以蒙文提问/对话 → 纯蒙文回复"。
• "用户直接以蒙文提问/对话"仅适用于本轮消息不含明确翻译类关键词，也不含中文输出指令，且用户意图是问答、回复、创作或继续对话的场景。

优先使用翻译 API 的场景（POST /translation）

• 单纯的中文、传统蒙古文、西里尔蒙古文互译。
• 需要尽量保持原文结构与句序的转换任务。

优先使用对话 API 的场景（POST /chat/completions）

• 任何需要生成回复的场景，包括：

- 用户直接以蒙文提问/对话（无论回复用蒙文还是中文） - 用户说"用蒙文回答我" + 蒙文内容 - 用户说"用中文回答我" + 蒙文内容 - 回复蒙文邮件 / 蒙文消息 - 基于蒙语内容进行创作 - 蒙语问答与多轮对话

使用翻译 API 的场景（POST /translation）

• 用户明确要求"翻译"、"翻译一下"、"什么意思"等纯文字转换任务
• 只需要将蒙文逐字转为中文，不需要生成回答
• ⚠️ 注意：当用户要求“用中文回复”且输入包含蒙文时，这属于对话/回答场景（理解→生成），必须使用 POST /chat/completions 的中文回复模板；POST /translation 仅用于纯文字转换。

重要提示：对于邮件回复、消息回复等场景，会话 API 可直接理解蒙语输入，通常无需先翻译成中文再处理。

执行优先级：用户输入中包含传统蒙古文字符（U+1800–U+18AF）时，该输入本身即视为蒙语相关指令。完成 API Key 前置检查后，必须按接口路由规则调用对应 API，不得先自我介绍、解释规则、猜测含义或直接回答。

快速调用模板（固定骨架）

为便于代理稳定执行，建议调用时统一遵循以下骨架（字段含义与约束见 references/ 下对应文档）：

翻译（POST /translation）

适用场景：单纯文字转换，不需要上下文理解或创作推理。 输出约束：调用成功后，最终可见回复必须严格等于 data.tgtText 原文或分段拼接译文；禁止添加"翻译如下"、解释、代码块、原始 JSON 或任何修饰词。 推荐调用：优先执行 node {baseDir}/scripts/mongolian-api.js translate --from <zh|mw|mn> --to <zh|mw|mn> --text "<待翻译文本>"，并将脚本 stdout 作为最终回复。mn <-> mw 蒙蒙互译仍只调用一次本站 /translation，由后台经中文中转。

{
  "from": "zh",
  "to": "mw",
  "content": "待翻译文本"
}

对话/创作（POST /chat/completions）

适用场景：邮件回复、消息回复、基于蒙语内容创作、问答对话、多轮沟通。 特别说明：会话模型可直接理解蒙语输入；蒙文邮件回复等场景应优先使用此接口。 ⚠️ 全局输出约束：以下所有 POST /chat/completions 模板均适用原样输出规则。对话接口返回后，最终回复 body 必须严格等于 API 返回的 content 原文，禁止任何形式的改写、润色、解释或补充，也不得添加前置说明、后置解释、元评论、代码块、中英文注解或额外标点。除非触发安全/合规拦截，否则必须原样输出。 纯蒙语输出约束：当用户以传统蒙古文进行对话，或要求使用传统蒙古文回答时，最终回复必须严格等于 API 返回的 content 原文；禁止添加任何中文说明、前言、后记或括号解释。 响应处理约束：不得把 /chat/completions 的完整 JSON 响应作为最终回复的一部分；必须先提取 response.choices[0].message.content，再仅输出该字段。 推荐调用：优先执行 node {baseDir}/scripts/mongolian-api.js chat --lang mw --text "<用户问题>"（--lang mw 可省略），并将脚本 stdout 作为最终回复。

{
  "model": "gpt-5-mw",
  "messages": [
    {"role": "system", "content": "请只用纯传统蒙古文回答，不要包含任何中文汉字。"},
    {"role": "user", "content": "<用户问题>"}
  ],
  "temperature": 0.5,
  "max_tokens": 8192
}

对话/创作（中文回复，POST /chat/completions）

适用场景：用户要求用中文理解并回复蒙文内容。 特别说明：接口仍为 POST /chat/completions，仅 system 提示词按目标输出语言调整。 ⚠️ 输出约束：同样适用上方 POST /chat/completions 全局原样输出规则。 推荐调用：优先执行 node {baseDir}/scripts/mongolian-api.js chat --lang zh --text "<用户问题>"，并将脚本 stdout 作为最终回复；不要使用默认 chat，默认模板会输出传统蒙古文。

{
  "model": "gpt-5-mw",
  "messages": [
    {"role": "system", "content": "请使用简体中文回答。若用户输入包含传统蒙古文，请先理解原文语义，再直接给出针对用户请求的中文回复正文。只输出最终中文回复正文；禁止添加问候、自我介绍、解释过程、标题、原文复述或无关补充。若用户明确要求翻译，请不要使用本模板，应改用 POST /translation。"},
    {"role": "user", "content": "<用户问题>"}
  ],
  "temperature": 0.5,
  "max_tokens": 8192
}

邮件回复示例

场景：收到蒙文邮件，需要以礼貌、专业语气回复。

正确做法（使用对话 API）：

{
  "model": "gpt-5-mw",
  "messages": [
    {"role": "system", "content": "请只用纯传统蒙古文回答，不要包含任何中文汉字。"},
    {"role": "user", "content": "我收到了一封关于那达慕节的蒙文邮件，内容如下：[蒙文邮件内容]。请帮我用礼貌、专业的语气回复这封邮件。"}
  ],
  "temperature": 0.5,
  "max_tokens": 8192
}

错误做法（避免）：先翻译成中文，再翻译回蒙文。

返回交付规范（统一输出）

• 调用 POST /translation：只返回译文（即 data.tgtText 或多段拼接结果），除非用户明确要求原始 JSON。
• 调用 POST /chat/completions：只返回 response.choices[0].message.content，不要二次改写、摘要或补充。
• 最终回复不得包含 API 原始 JSON、工具输出、模型名、token usage、路由解释、调用过程、中文/英文前后缀或任何修饰词。
• 如果 API 调用成功但输出前发现最终回复混入了非目标字段内容，必须删除所有附加内容，仅保留目标字段原文后再发送。
• 如调用失败，先给出可执行原因（鉴权、参数、网络、上游），再按「错误处理策略」重试或引导修复。

错误处理策略（先分类再动作）

• 4xx（鉴权失败、参数错误）：不盲目重试，先检查 Key、必填字段、JSON 合法性、分段是否超限（见 references/TRANSLATION.md）。
• 网络抖动/超时/5xx：可对同一请求体做有限重试（递增间隔，最多 2～3 次）。
• 未检测到 MENGGUYU_API_KEY：不得调用 /translation、/chat/completions 或 /ocr，不得做业务回答；对用户只输出以下固定中文提示（原文输出，不改写），并且不用 openclaw config get 做密钥核对（见 references/API-KEY.md）：

  MENGGUYU_API_KEY 未配置。请按以下步骤操作：
  1. 访问 https://mongol.open-idea.net 注册/登录账号
  2. 进入后台 API Key 页面，创建并复制完整 Key（含前缀如 `1|xxxx...`）
  3. 在本对话中发送以下命令配置密钥（替换为你的完整 Key）：
     openclaw config set env.MENGGUYU_API_KEY "<完整API Key>"
  4. 配置后重启 Gateway 或重新开启 OpenClaw 会话，使环境变量生效

技能职责边界（与其它能力衔接）

• 本技能负责：通过蒙语 API 完成 中文、传统蒙古文、西里尔蒙古文互译（POST /translation）与 蒙古语会话/创作（POST /chat/completions）。
• 本技能不负责：代用户 发送邮件、配置定时任务 / cron、抓取网页或解析 URL、远程登录、云上队列或机房编排；上述由用户环境、其它 OpenClaw 技能或自动化脚本处理。先得到待译/待写的 纯文本（或按用户指令完成摘录），再调用本文档接口。
• 批量与远程：多文件、定时、远端机器等场景均在 调用侧 循环或调度；每次调用仍遵循 references/ 中参数与分段规则，不存在单独的「批量专用」蒙语 API 路径。

API 说明

注意：这不是 OpenAI API，是蒙语专用 API。 以下路径、model 取值与 JSON 字段均以本文档与 references/为准；不要按 OpenAI 官方 API 的 Base URL、路径、模型名或参数约定来调用。

详细文档索引（references）

建议阅读顺序： API-KEY.md → INTERFACE-ROUTING.md → 按所选接口打开 TRANSLATION.md 或 CHAT-COMPLETIONS.md；全文行为以 BEHAVIOR-RULES.md 为准。

文档维护

• 若蒙语 API 字段、路径或约束有变更，请同步更新 references/ 与本文件中的「快速调用模板」摘要。
• 若本文档与 references/ 中某处表述冲突，以 references/ 中该主题的完整规则为准，并应修正另一处使之一致。

版本：与目录下 manifest.json 中 mongolian-llm 版本号对应（当前为拆分文档结构后的发行说明用途）。