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

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 字段对应以下错误类型：

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

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

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

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

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 统计各类错误数量，方便针对性修改～

📚 更多资源

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

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