grammarly-core-workflow-a

用途

Grammarly Core Workflow A 用于把 Grammarly 的 Writing Score API 集成到应用中，对文档进行写作质量评分，跟踪写作质量随时间的变化，并提供反馈。该 API 从四个维度评估文本：参与度（engagement）、正确性（correctness）、清晰度（clarity）和语气（tone）。

前置条件

已完成 grammarly-install-auth 认证配置
理解各评分维度的含义

主要能力

1. 类型化评分客户端

通过 scoreDocument 函数向 https://api.grammarly.com/ecosystem/api/v2/scores 发送 POST 请求，请求体包含文本以及可选的受众类型（general、knowledgeable、expert）和领域（academic、business、general、email、casual）。返回的 WritingScore 包含 overallScore、engagement、correctness、clarity、tone 五个字段。

// src/grammarly/scoring.ts
interface WritingScore {
  overallScore: number;
  engagement: number;
  correctness: number;
  clarity: number;
  tone: number;
}

interface ScoreRequest {
  text: string;
  audienceType?: 'general' | 'knowledgeable' | 'expert';
  domain?: 'academic' | 'business' | 'general' | 'email' | 'casual';
}

async function scoreDocument(req: ScoreRequest, token: string): Promise<WritingScore> {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v2/scores', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(req),
  });
  if (!response.ok) throw new Error(`Grammarly API ${response.status}: ${await response.text()}`);
  return response.json();
}

2. 批量文档评分

batchScore 会遍历文档列表，跳过少于 30 词的文档，逐个评分，并在每次请求之间等待 500 毫秒作为限流缓冲。

async function batchScore(documents: string[], token: string): Promise<WritingScore[]> {
  const results: WritingScore[] = [];
  for (const doc of documents) {
    if (doc.split(/\s+/).length < 30) {
      console.warn('Skipping: minimum 30 words required');
      continue;
    }
    const score = await scoreDocument({ text: doc }, token);
    results.push(score);
    await new Promise(r => setTimeout(r, 500)); // Rate limit buffer
  }
  return results;
}

3. 质量阈值校验

checkQualityGate 根据设定的最低整体分、最低正确性和最低清晰度判断文档是否通过质量门槛，并返回未通过的具体问题列表。

interface QualityGate {
  minOverall: number;
  minCorrectness: number;
  minClarity: number;
}

function checkQualityGate(score: WritingScore, gate: QualityGate): { passed: boolean; issues: string[] } {
  const issues: string[] = [];
  if (score.overallScore < gate.minOverall) issues.push(`Overall ${score.overallScore} < ${gate.minOverall}`);
  if (score.correctness < gate.minCorrectness) issues.push(`Correctness ${score.correctness} < ${gate.minCorrectness}`);
  if (score.clarity < gate.minClarity) issues.push(`Clarity ${score.clarity} < ${gate.minClarity}`);
  return { passed: issues.length === 0, issues };
}

// Usage: enforce quality before publishing
const score = await scoreDocument({ text: blogPost }, token);
const gate = checkQualityGate(score, { minOverall: 80, minCorrectness: 90, minClarity: 75 });
if (!gate.passed) console.error('Quality gate failed:', gate.issues);

API 限制

限制项	值
最大文本大小	4 MB
最大字符数	100,000
最少词数	30

错误处理

错误	原因	解决方案
400	文本过短	确保不少于 30 词
413	文本过大	拆分为小于 100K 字符的块
429	触发限流	实现指数退避

输出

返回一份脱敏的评分回执，包含环境、fixture 版本、请求数量区间、策略阈值版本、总体结果、保留决策和关联 ID。不要存储输入文本、建议、与可识别作者关联的分数或凭据。

示例

对一个虚构 fixture 评分，仅断言其预期的策略类别，然后记录 fixture=writing-basic-v2; requests=1; threshold=r5; outcome=pass; retention=none。

资源

Writing Score API
Score Dimensions

后续步骤

如需 AI 与抄袭检测，请参见 grammarly-core-workflow-b。