文档

CLI / API / Skill / MCP 四种接入方式背后是同一个校对引擎，鉴权与限流按 Key 计。本页覆盖安装、鉴权、参数、限制与错误码。

概览

所有接入共用：

• Base URL：https://jd.glowjames.top
• 鉴权：Authorization: Bearer <key>（CLI / API / MCP 均如此；Skill 内部走 API）
• 限流按 Key 计，四种方式共享同一套限额（仅限流与输入长度上限，无用量配额）。

获取 Key

1. 注册（邮箱 + 密码，免费）。注册成功后进入个人中心，Key 以明文一次性展示，请当场保存。
2. 之后随时可在个人中心重新生成或吊销 Key。每个账户最多持有 1 个有效 Key，更换时先吊销旧的再创建新的。

安全提示：不要把 Key 提交进代码仓库或写进前端页面。推荐用环境变量 JIAODUI_API_KEY，泄露后在个人中心吊销即可。

CLI · 命令行

安装

macOS / Linux（依赖 curl 与 python3，python3 仅用于组装/解析 JSON）：

curl -fsSL https://jd.glowjames.top/jiaodui.sh -o jiaodui.sh
chmod +x jiaodui.sh
./jiaodui.sh "他慢慢的走了。"

Windows：下载 jiaodui.ps1（PowerShell 5.1+，HTTP 用原生 Invoke-RestMethod，无 python 依赖）；cmd 用户用 jiaodui.cmd（包装入口，转发给 jiaodui.ps1）。若脚本执行策略受限：

powershell -NoProfile -ExecutionPolicy Bypass -File .\jiaodui.ps1 "他慢慢的走了。"

也可以直接浏览器打开 /jiaodui.sh、/jiaodui.ps1、/jiaodui.cmd 下载。源码见 GitHub 仓库（MIT）。

配置 Key

Key 读取顺序：--key 参数 → $JIAODUI_API_KEY 环境变量 → 脚本目录向上逐级查找 .env 文件（内容形如 JIAODUI_API_KEY=...）。

# macOS / Linux
export JIAODUI_API_KEY="你的 Key"

# Windows PowerShell
$env:JIAODUI_API_KEY = "你的 Key"

用法

# 校对一段文本
./jiaodui.sh "他慢慢的走了。"

# 校对文件
./jiaodui.sh -f draft.md

# stdin 管道
echo "他慢慢的走了。" | ./jiaodui.sh

# 输出原始 JSON（默认输出可读报告）
./jiaodui.sh -f draft.md --json

# 返回人类可读的文本报告（等价 model=jiaodui-text）
./jiaodui.sh --text-model "他慢慢的走了。"

# Windows PowerShell（参数同义）
.\jiaodui.ps1 -File draft.md -Json
.\jiaodui.ps1 -TextModel "他慢慢的走了。"

输出示例（发现差错时）：

发现 1 条：
  慢慢的走 → 慢慢地走

无差错时输出 本次校对未发现差错。常见报错：未找到 JIAODUI_API_KEY（先 export 或用 --key）；HTTP 401（Key 无效或已吊销，去个人中心重新生成）；HTTP 429（触发限流：每 2 秒 1 次，按响应的 Retry-After 退避后重试）。

API · OpenAI 兼容

端点与鉴权

POST https://jd.glowjames.top/v1/chat/completions
Content-Type: application/json
Authorization: Bearer <你的 Key>

协议与 OpenAI /v1/chat/completions 兼容，OpenAI SDK 把 base_url 指向 https://jd.glowjames.top/v1 即可复用。

model 取值

messages 取最后一个 role=user 消息的 content 作为待校对文本；system 及更早的对话内容不参与校对。

两种模型的条目数可能不同：jiaodui-text 沿用人工复查报告的形态，会额外带上建议里含 ？？ 的提示项（如「重复[t]？？」，表示"疑似、请人工确认"）；jiaodui 的 JSON 面向程序消费，会过滤掉这类无法自动套用的提示。需要汇报条目数时请固定用同一种模型。

jiaodui-text 返回的 content 即报告全文（CRLF 行尾、等宽对齐），形如：

发现差错时：

     本次校对出以下   1 条疑似差错

 序号 疑似差错词                    建议修改                  出现次数  距篇首字数
    1) 慢慢的走                           慢慢地走                                     .2

【校对助手】2026.09.12 09:00:00 AM 校对共    7字  耗时:  0.1秒

无差错时：

     本次校对没有发现差错

 序号 疑似差错词                    建议修改                  出现次数  距篇首字数

【校对助手】2026.09.12 09:00:00 AM 校对共    6字  耗时:  0.1秒

最小示例（curl）

curl -s https://jd.glowjames.top/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JIAODUI_API_KEY" \
  -d '{
    "model": "jiaodui",
    "messages": [{"role": "user", "content": "他慢慢的走了。"}]
  }'

响应结构（重要）

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "jiaodui",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "{\"file\":\"\",\"total\":1,\"items\":[{\"index\":1,\"wrong\":\"慢慢的走\",\"suggestion\":\"慢慢地走\",\"type\":\"general\",\"offset\":2}]}"
    }
  }],
  "usage": { "prompt_tokens": 7, "completion_tokens": 96, "total_tokens": 103 }
}

content 二次解析后的结构：

无差错时 items 为空数组、total 为 0。jiaodui-text 的 content 则是纯文本报告，直接展示即可。

Python（openai SDK）

import json
from openai import OpenAI

client = OpenAI(base_url="https://jd.glowjames.top/v1", api_key="你的 Key")
resp = client.chat.completions.create(
    model="jiaodui",
    messages=[{"role": "user", "content": "他慢慢的走了。"}],
)
result = json.loads(resp.choices[0].message.content)  # content 是 JSON 字符串，需二次解析
for it in result["items"]:
    print(it["wrong"], "→", it["suggestion"])

JavaScript / TypeScript（openai npm 包）

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://jd.glowjames.top/v1",
  apiKey: process.env.JIAODUI_API_KEY,
});
const resp = await client.chat.completions.create({
  model: "jiaodui",
  messages: [{ role: "user", content: "他慢慢的走了。" }],
});
const result = JSON.parse(resp.choices[0].message.content); // 二次解析
for (const it of result.items) {
  console.log(`${it.wrong} → ${it.suggestion}`);
}

流式

请求体加 "stream": true 即返回标准 SSE 分块（chat.completion.chunk），OpenAI SDK 的 stream=True 可直接使用。注意：内容是把最终校对结果切块下发，不是边算边出的增量校对。

注意事项

• 无 CORS：API 不返回 Access-Control 响应头，浏览器页面里不能直接调用，请在自己的服务端转发。
• 没有 /v1/models：模型固定为 jiaodui / jiaodui-text，无需拉取模型列表。
• 长文：单次输入上限 40,000 字（按 Unicode 字符计，非字节），超限返回 400；服务端处理超时 30 秒，超长文本请分段。
• 批量：客户端串行调用并自行节流（限流为每 2 秒 1 次），收到 429 时按响应的 Retry-After 退避重试。
• 隐私：OpenAI 兼容接口不主动保存原文；触发同音字等候选检查的文本会进入质量改进日志（不关联账户），详见隐私政策。

Skill · AI 助手调用

Skill = SKILL.md（能力说明）+ 三系统 CLI 脚本 + MCP 本地版源码。装好后，在支持的 AI 客户端里说一句"帮我校对这段"，校对能力自动被调起。

获取与放置

git clone https://github.com/beautare/jiaodui-skill.git

clone 下来的 jiaodui-skill/ 目录即 skill 根目录（SKILL.md 就在根上）。把它整体放入客户端的 skills 目录，目录名保持 jiaodui-skill：

• Claude Code：用户级 ~/.claude/skills/jiaodui-skill/，或项目级 <项目>/.claude/skills/jiaodui-skill/
• ZCode 等 Agent CLI：<项目>/.agents/skills/jiaodui-skill/

目录层级以各客户端自己的 skills 文档为准。配置 Key：设 JIAODUI_API_KEY 环境变量，或在 skill 目录内运行 python scripts/setup_env.py --key "<key>"（只写 skill 目录的 .env，不改 shell profile）。

MCP · 客户端接入

远端（推荐，零安装）

端点 https://jd.glowjames.top/mcp（POST，Streamable HTTP，无状态），Bearer Key 鉴权。在 MCP 客户端的 server 配置中加：

{
  "mcpServers": {
    "jiaodui": {
      "url": "https://jd.glowjames.top/mcp",
      "headers": { "Authorization": "Bearer 你的 Key" }
    }
  }
}

配置文件位置因客户端而异（如 Claude Desktop 的 claude_desktop_config.json、Cursor 的 .cursor/mcp.json、VS Code 的 MCP 设置节），字段形态以上述通用写法为准。

工具

• name：proofread
• 输入：{ "text": "要校对的中文文本" }（上限 40,000 字）
• 输出：人类可读报告，如 发现 1 条：\n 慢慢的走 → 慢慢地走；无差错时返回 本次校对未发现差错。

本地版（自行编译，stdio）

git clone https://github.com/beautare/jiaodui-skill.git
cd jiaodui-skill/mcp-server
go build -o jiaodui-mcp .   # 需要 Go 1.25+

{
  "mcpServers": {
    "jiaodui": {
      "command": "/path/to/jiaodui-skill/mcp-server/jiaodui-mcp",
      "env": { "JIAODUI_API_KEY": "你的 Key" }
    }
  }
}

本地版经远端 API 调用（JIAODUI_API_URL 可覆盖端点），同样消耗配额；不内置任何 Key。

限制与配额

免费档即为上述额度，适合轻度使用；需要更高额度或批量处理请发邮件至 contact@beautare.com。

错误码

错误响应统一为 OpenAI 格式：{"error":{"message":"…","type":"…","code":"…"}}。

隐私与数据

CLI / Skill / MCP / API 直调都走 OpenAI 兼容接口：该接口不主动保存原文，仅当文本触发同音字等候选检查时，相关质量改进日志会记录该次输入文本，且与账户不关联；另记录调用时间、错误类别等元数据用于配额统计与质量改进（以聚合统计为主）。完整口径见隐私政策与服务条款。

更新日期：2026-09-12 · 问题反馈：contact@beautare.com · 开源仓库：GitHub（MIT） · 隐私口径见隐私政策