Spaces:

colearn30
/

colearn30-ai-grading-agents

Sleeping

App Files Files Community

colearn30-ai-grading-agents / API.md

Youngger9765

feat: Refactor assistant system with auto-matching and manual selection

c511d53 4 months ago

preview code

raw

history blame contribute delete

8.62 kB

AI 批改平台 API 文件

基本資訊

Base URL: https://api.example.com
API Version: v1
Content-Type: application/json
Authentication: Bearer Token (放在 Authorization header)

API 端點

1. 取得可用 Agents 列表

GET /api/agents

取得所有可用的批改 agents 清單。

Request

GET /api/agents HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN

Response

Status Code: 200 OK

{
  "version": 2,
  "agents": [
    {
      "key": "zh_full_edit",
      "name": "中文全文批改",
      "language": "zh-TW",
      "ui": {
        "badge": "ZH",
        "color": "#1565C0"
      },
      "rubric": {
        "overall_weight": 100,
        "criteria": [
          {
            "key": "structure",
            "label": "結構與段落",
            "weight": 25
          },
          {
            "key": "coherence",
            "label": "論證與連貫",
            "weight": 25
          },
          {
            "key": "clarity",
            "label": "表達清晰度",
            "weight": 25
          },
          {
            "key": "mechanics",
            "label": "字詞/標點/語法",
            "weight": 25
          }
        ]
      }
    },
    {
      "key": "en_edit",
      "name": "英文批改",
      "language": "en",
      "ui": {
        "badge": "EN",
        "color": "#2E7D32"
      },
      "rubric": {
        "overall_weight": 100,
        "criteria": [
          {
            "key": "organization",
            "label": "Organization",
            "weight": 20
          },
          {
            "key": "argumentation",
            "label": "Argumentation",
            "weight": 30
          },
          {
            "key": "clarity",
            "label": "Clarity & Style",
            "weight": 25
          },
          {
            "key": "mechanics",
            "label": "Grammar & Spelling",
            "weight": 25
          }
        ]
      }
    }
  ]
}

2. 送出批改請求

POST /api/grade

送出文章進行 AI 批改。

Request

POST /api/grade HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Body Parameters

參數	類型	必填	說明
`agent_key`	string	✓	Agent 識別碼（如 `zh_full_edit`）
`text`	string	✓	要批改的文章全文
`options`	object	✗	額外選項
`options.output_format`	string	✗	輸出格式：`markdown`(預設)、`html`、`diff`、`json`
`options.include_scores`	boolean	✗	是否包含評分（預設：true）
`options.include_suggestions`	boolean	✗	是否包含改進建議（預設：true）

Request Example

{
  "agent_key": "zh_full_edit",
  "text": "這是一篇關於環保議題的文章。在現代社會中，環境保護已成為全球關注的焦點...",
  "options": {
    "output_format": "markdown",
    "include_scores": true,
    "include_suggestions": true
  }
}

Response

Success Response

Status Code: 200 OK

{
  "success": true,
  "data": {
    "agent_key": "zh_full_edit",
    "timestamp": "2024-01-20T10:30:00Z",
    "processing_time_ms": 3500,
    "result": {
      "summary": "這篇文章探討了環保議題，結構清晰但論述可以更深入...",
      "inline_edits": "這是一篇關於環保議題的文章。在現代社會中，環境保護已成為全球~~關注的焦點~~**矚目的核心議題**...",
      "scores": {
        "overall": 75,
        "criteria": {
          "structure": 80,
          "coherence": 70,
          "clarity": 75,
          "mechanics": 75
        }
      },
      "suggestions": [
        {
          "type": "improvement",
          "section": "introduction",
          "text": "建議在開頭加入更具體的數據或案例，增強說服力"
        },
        {
          "type": "correction",
          "section": "paragraph_2",
          "text": "第二段的轉折詞使用不當，建議改為『然而』"
        }
      ]
    }
  }
}

Processing Response (Long Polling)

如果處理時間較長，可能會先回傳處理中狀態：

Status Code: 202 Accepted

{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "status": "processing",
    "message": "批改處理中，請稍候..."
  }
}

Error Response

Status Code: 400 Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_AGENT",
    "message": "指定的 agent_key 不存在",
    "details": {
      "agent_key": "invalid_agent",
      "available_agents": ["zh_full_edit", "en_edit"]
    }
  }
}

3. 查詢批改狀態（選用）

GET /api/grade/{job_id}

查詢長時間處理的批改任務狀態。

Request

GET /api/grade/job_abc123xyz HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN

Response

Processing

{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "status": "processing",
    "progress": 65,
    "message": "正在分析文章結構..."
  }
}

Completed

{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "status": "completed",
    "result": {
      // 同上方批改結果格式
    }
  }
}

錯誤碼

HTTP 狀態碼	錯誤碼	說明
400	`INVALID_AGENT`	無效的 agent_key
400	`EMPTY_TEXT`	文章內容為空
400	`TEXT_TOO_LONG`	文章超過長度限制（預設 10000 字）
401	`UNAUTHORIZED`	未提供或無效的 API Token
403	`FORBIDDEN`	無權限使用此 agent
429	`RATE_LIMIT`	超過速率限制
500	`INTERNAL_ERROR`	伺服器內部錯誤
503	`SERVICE_UNAVAILABLE`	OpenAI API 暫時無法使用

速率限制

預設限制：每分鐘 10 次請求
Response Headers：
- X-RateLimit-Limit: 速率限制上限
- X-RateLimit-Remaining: 剩餘請求次數
- X-RateLimit-Reset: 重置時間（Unix timestamp）

WebSocket API（即時批改 - 選用）

Endpoint: wss://api.example.com/ws/grade

Connection

const ws = new WebSocket('wss://api.example.com/ws/grade');
ws.onopen = () => {
  // 發送認證
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_API_TOKEN'
  }));
};

送出批改

ws.send(JSON.stringify({
  type: 'grade',
  data: {
    agent_key: 'zh_full_edit',
    text: '文章內容...'
  }
}));

接收進度更新

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  switch(message.type) {
    case 'progress':
      console.log(`進度: ${message.progress}%`);
      break;
    case 'partial':
      console.log('部分結果:', message.data);
      break;
    case 'complete':
      console.log('批改完成:', message.data);
      break;
    case 'error':
      console.error('錯誤:', message.error);
      break;
  }
};

SDK 範例

JavaScript/TypeScript

import { GradingClient } from '@example/grading-sdk';

const client = new GradingClient({
  apiKey: 'YOUR_API_TOKEN',
  baseUrl: 'https://api.example.com'
});

// 取得 agents
const agents = await client.getAgents();

// 送出批改
const result = await client.grade({
  agentKey: 'zh_full_edit',
  text: '文章內容...',
  options: {
    outputFormat: 'markdown',
    includeScores: true
  }
});

console.log(result.summary);
console.log(result.scores);

Python

from grading_sdk import GradingClient

client = GradingClient(
    api_key="YOUR_API_TOKEN",
    base_url="https://api.example.com"
)

# 取得 agents
agents = client.get_agents()

# 送出批改
result = client.grade(
    agent_key="zh_full_edit",
    text="文章內容...",
    options={
        "output_format": "markdown",
        "include_scores": True
    }
)

print(result["summary"])
print(result["scores"])

測試環境

Staging URL: https://staging-api.example.com
測試 Token: 請聯繫管理員取得

更新紀錄

版本	日期	更新內容
v1.0.0	2024-01-20	初版發布
v1.1.0	2024-02-01	新增 WebSocket 即時批改
v1.2.0	2024-02-15	支援批次批改

聯絡資訊

技術支援: support@example.com
API 狀態頁: https://status.example.com
開發者論壇: https://forum.example.com/api