iflytek-text-proofread

name	iflytek-text-proofread
description	iFlytek Official Document Proofreading (公文校对) — detect and correct errors in Chinese text including typos, punctuation, word order, factual mistakes, sensitive content, and more (27 error types). Supports up to 220,000 characters. Use when the user wants to proofread, check, or correct Chinese text, especially official documents. Pure Python stdlib, no pip dependencies.
metadata	{"homepage":"https://www.xfyun.cn/services/text_proofread","openclaw":"{\"emoji\":\"✏️\",\"dimensions\":[\"公文校对\",\"文本纠错\"],\"user_instructions\":[\"帮我校对这段文字\",\"检查这篇文章有没有错别字\",\"公文纠错\"],\"requires\":{\"bins\":[\"python3\"],\"env\":[\"IFLY_APP_ID\",\"IFLY_API_KEY\",\"IFLY_API_SECRET\"]},\"primaryEnv\":\"IFLY_API_KEY\"}"}

ifly-text-proofread

Proofread Chinese text using iFlytek's Official Document Proofreading API (公文校对). Detects 27 types of errors across three categories:

文字标点差错: 错别字、多字、少字、语义重复、语序错误、句式杂糅、标点符号、量词单位、数字差错、句子查重、序号检查

知识性差错: 地理名词、机构名称、专有名词及术语、常识差错、媒体报道禁用词和慎用词

内容导向风险: 涉低俗辱骂、其他敏感内容

Setup

1. Create an app at 讯飞控制台 with 公文校对 service enabled
2. Set environment variables:

   export IFLY_APP_ID="your_app_id"
   export IFLY_API_KEY="your_api_key"
   export IFLY_API_SECRET="your_api_secret"
   

Usage

Basic proofreading

python3 scripts/text_proofread.py "第二个百年目标"

Read from stdin

echo "我们要加强对蓝球运动的推广" | python3 scripts/text_proofread.py -

Read from file

python3 scripts/text_proofread.py --file document.txt

Options

Flag	Short	Description
text		Text to proofread (use - for stdin)
--file	-f	Read text from a file
--raw		Output decoded JSON response

Examples

# Proofread a sentence
python3 scripts/text_proofread.py "我国加强蓝球运动的推广力度"

# Proofread a long document from file
python3 scripts/text_proofread.py -f report.txt

# Pipe from clipboard or other tools
pbpaste | python3 scripts/text_proofread.py -

# Raw JSON for debugging
python3 scripts/text_proofread.py --raw "测试文本"

Output

• ✅ 无错误 — text passed proofreading with no issues
• 🔍 发现 N 处问题 — lists each error with:
  • Error word + category
  • Explanation
  • Context in the original text
  • Position and length
  • Suggested action (标记/替换/删除)
  • Correction suggestions

Notes

• Max text length: 220,000 characters per request (auto-truncated with warning)
• Auth: HMAC-SHA256 signed URL (host + date + request-line → signature → authorization)
• Endpoint: POST https://cn-huadong-1.xf-yun.com/v1/private/s37b42a45
• Env vars: IFLY_APP_ID, IFLY_API_KEY, IFLY_API_SECRET
• No pip deps: Uses only Python stdlib (urllib, hmac, hashlib, json, etc.)
• Text is base64-encoded in the request body; response text field is also base64-encoded

---

常见问题

❓ 错误能力ID对照表

在使用API时，返回的 belongId 字段对应以下错误类型：

belongId	说明	常见场景
9	错别字、词	「蓝球」→「篮球」、「的」「地」「得」混淆
31	多字错误	「大大大大力」→ 删除多余字
32	少字错误	「中国成立」→ 「中华人民共和国成立」
35	语义重复	「大力大力发展」→ 语义重复
34	语序错误	「很好很强大」→ 「很强大很好」
39	量和单位差错	「3斤米」→ 「3公斤米」
36	数字差错	「第十几个」→ 数据不一致
20	句式杂糅	「原因是由于...」→ 句式杂糅
21	标点符号差错	顿号逗号混用、书名号错误
24	句子查重	文档内部重复句子
119	重要讲话引用	领导人讲话用词规范
123	地理名词	省市区名称、行政区划
19	机构名称	党政机关、企事业单位名称
124	专有名词及术语	专业术语、科技术语
122	媒体报道禁用词	敏感词、违规词检测
6	常识差错	明显与事实不符的内容
111	涉低俗辱骂	低俗内容、辱骂词汇
118	其他敏感内容	各类敏感信息检测

---

🔧 出现错误怎么办？— 用户视角引导

1️⃣ 收到错误响应不要慌～ (´▽`)

• 首先检查：环境变量 IFLY_APP_ID、IFLY_API_KEY、IFLY_API_SECRET 是否都设置好了呢？ฅ•̀∀•́ฅ
• 然后看这里：
  • 返回的 code 字段：0 = 成功，其他 = 失败 (详见下文错误码表)
  • 响应里的 data 字段包含检测结果，message 字段有详细说明哦～

2️⃣ 常见错误码一览 ✧(•̀ω•́)✧

code	说明	解决方法
0	成功	完美！继续使用吧～ ✨
101	参数缺失	快检查一下 text 参数有没有传呀？
102	参数无效	文本内容有问题，看看是不是太长了（≤220000字符）？
103	请求超长	文本太长了啦！分段处理试试吧～
104	超过并发	访问太频繁啦，休息一下再试试呗～ ⏳
105	无配额	配额用完了...去讯飞控制台看看还能不能用吧 (｡•́︿•̀｡)
106	无产品权限	还没开通公文校对服务哦！去 讯飞控制台 开通一下吧～
107	授权失败	API密钥可能过期或错误，检查一下环境变量吧！
108	模型加载失败	服务端问题，稍后再试一次吧～

3️⃣ 解析结果好迷茫？来，手把手教你～ (｡･ω･｡)

返回的 detail 数组里每个元素代表一个错误，来看看怎么读懂它：

detail[i].word        → 错误的内容是什么
detail[i].type        → 错误类型ID（对应上面的对照表哦）
detail[i].position    → 错误开始位置（从0开始计数）
detail[i].length      → 错误内容的长度
detail[i].suggestion  → 纠错建议
detail[i].ruleName    → 具体触发的规则名称

📍 小技巧：想知道错误在哪里结束吗？position + length 就是结束位置啦！这样就可以精准定位错误咯～

---

💡 常见问题解答

Q1: 公文校对与文本纠错、文本合规有哪些区别？

A: 文本纠错主要偏向通用领域（如写作、出版）文本进行纠错，公文校对在公文写作使用等领域效果更佳，同时也适合通用领域～ 文本合规对各类场景风险拦截更全面哦！(`･ω･´)ゞ

Q2: 公文校对的position仅标记开始位置，结束位置怎么计算呢？

A: 超简单的啦！讯飞已经给了 position 和 length，用 position + length 就是对应错误词在文本中的结束位置咯～ ✧٩(ˊᗜˋ*)و✧

Q3: 公文校对的文本有什么要求吗？

A: 有的呢～ 原请求的校对文本：

• ✨ 不能为空
• ✨ 不能超过 220,000个字符
• ✨ 汉字、英文字符、数字、标点都算做一个字符哦！

💡 小提示：如果文本太长，建议拆分成多条请求处理，这样效果会更好呀～

Q4: 为什么返回的结果是空的呀？(｡•́︿•̀｡)

A: 可能的原因：

• 1. 文本太短，没有检测到错误（这是好事！说明文本很棒棒～）
• 2. API调用失败了，检查一下 code 是不是 0 呢
• 3. 网络波动导致的，再试一次看看吧！

Q5: 如何开通或购买服务？

A: 去讯飞官方平台就好啦～

• 📖 控制台入口
• 💰 价格详情

---

🎉 使用小贴士

1. 批量处理：长文本可以拆分成多条请求，结果合并起来就好啦～
2. 实时反馈：可以配合编辑器插件，实现输入即校对功能哦！
3. 错误分类：利用 belongId 统计各类错误数量，方便针对性修改～

---

📚 更多资源

• 官方文档：讯飞公文校对
• 控制台：讯飞开放平台
• 价格说明：计费方式

---

祝大家校对顺利！有问题随时来问哦～ (´▽`)ﾉ 💕