API Key 与外部智能体接入

教师可在「API Key」页面创建长期凭证，将平台的教学能力（查课程、检索知识点、AI 出题、智能组卷、查看学情、发布作业、批改、发通知等）开放给自建或第三方 AI 智能体使用。

推荐同时下载 Agent 技能包——一份打好的 SKILL.md + 配置模板，贴上就能让 AI 助手”学会”用这些工具，而不是光”能调”。

适用场景

在 WorkBuddy、Cursor、Claude Desktop、Cline 等支持 MCP 协议的客户端中，让 AI 助手能直接读写教学数据
在 Dify、Coze 等工作流平台上用 HTTP 工具节点调用教学能力
自研应用通过标准 REST 接口集成

创建 API Key

进入教师端 → 左侧菜单「API Key」
点击右上角「新建 Key」
填写备注名（用来识别这把 Key 是给哪个智能体用的，例如”我的 WorkBuddy”）
可选设置过期时间
创建成功后完整 Key 仅展示一次，请立即复制保存；平台只保留哈希，无法再次查看

⚠️ 请勿把 Key 贴到公开代码仓库或分享给他人。一旦泄露，立即在管理页面「撤销」并重新创建。

两种接入协议

	REST 接口	MCP 协议
接入路径	`https://tea.z-xin.net/api/mcp/v1/<工具名>`	`https://tea.z-xin.net/api/mcp/server/mcp`
鉴权方式	HTTP Header：`Authorization: Bearer <KEY>`	同左
适用客户端	Dify、Coze、n8n、自研后端、curl	WorkBuddy、Cursor、Claude Desktop、Cline
返回格式	标准 JSON	MCP 协议 SSE 流

两种协议共享同一套工具和同一把 Key，选哪种取决于你用的客户端。

客户端接入示例

WorkBuddy（推荐）

WorkBuddy 是国产 AI 助手客户端，原生支持 MCP 协议。设置 → MCP 服务器 → 粘贴以下 JSON：


{
  "mcpServers": {
    "zxyun-teaching": {
      "url": "https://tea.z-xin.net/api/mcp/server/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json：


{
  "mcpServers": {
    "zxyun-teaching": {
      "url": "https://tea.z-xin.net/api/mcp/server/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop

Claude Desktop 仅支持 stdio，需要 mcp-remote 桥接（要求 Node.js 18+）。编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：


{
  "mcpServers": {
    "zxyun-teaching": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://tea.z-xin.net/api/mcp/server/mcp",
        "--header",
        "Authorization:Bearer YOUR_API_KEY"
      ]
    }
  }
}

若系统默认 Node 版本较低（如 v12），请把 command 改为完整路径，如 /Users/xxx/.nvm/versions/node/v18.20.3/bin/npx。改完配置后需完全退出（Cmd+Q）再重启 Claude Desktop。

Dify / Coze（REST）

在平台的「自定义 HTTP 工具」中配置：

Base URL：https://tea.z-xin.net/api/mcp/v1
鉴权：Bearer Token，值为你的 API Key
Method：POST
Content-Type：application/json

示例：查询当前教师所有课程


curl -X POST https://tea.z-xin.net/api/mcp/v1/my.courses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

管理页「配置」按钮

在 API Key 管理页面，每条 Key 旁都有配置按钮，点击后弹窗会按客户端类型给出可直接复制的配置代码。新建 Key 的展示弹窗里也有「查看接入配置」入口，会把刚创建的明文 Key 自动填入代码中。

可用工具清单（24 个）

外部智能体接入后，可直接调用以下工具（调用时传入 JSON 参数，LLM 会自己决定何时用）。调用 GET https://tea.z-xin.net/api/mcp/v1 可获取实时清单。

发现类（先调这个拿到其他工具需要的 ID）

my.courses — 当前教师的全部课程；传 includeClassrooms: true 可一次带回每门课下的班级列表和人数
my.classrooms — 某 teacherCourse 下的课堂列表
my.students — 某课堂的学生列表（分页、支持按姓名/学号搜索；传 includeHomeworkSummary: true 带回每个学生的作业数和平均分）
find.student — 跨当前教师所有课堂搜学生，直接返回 userId + 所在课堂/课程，省去逐层遍历

知识与题目

knowledge.search — 按课程 + 关键词检索知识点
question.generate — 调用 AI 按知识点/题型/数量生成题目（不落库）
question.save — 批量把题目存入题库（最多 50 条）
question.update — 编辑题库中的题目
question.delete — 软删除题目
question_set.create — 把一组已有题目打包成题集（paper.generate + question_set.create + homework.publish 即完成发布闭环）

组卷

paper.generate — 按题型、难度、知识点从题库随机选题（不落库，返回候选题目）

作业

homework.list — 列出作业；支持 scope: "classroom" | "all"（跨全部课堂）、按作业名关键字、按状态（进行中/已截止/未开始）、按截止时间范围过滤
homework.detail — 作业元数据 + 班级总体统计
homework.class_summary — 作业每个学生的提交状态 + 未交学生名单 + 可选每题正答率
homework.student_detail — 某学生在某作业的每题答案与得分
homework.publish — 基于已有题集 + 班级发布新作业
homework.update — 延期/改标题/调整显示设置
homework.extend_deadline — 给某个学生单独延期某次作业
homework.grade_question — 手动批改单题（写分数 + 评语）
homework.rejudge — 整份作业重新批改（自动判分，qa 保留人工分）

学情与通知

class.analytics — 课程级学情；dimension: "score"（默认）返回课堂分数分布，dimension: "knowledge" 返回薄弱知识点 Top N
student.profile — 单个学生某课程的知识掌握画像
student.homework_history — 某学生在某课程下所有作业的得分时间线
message.send — 向自己课堂的学生发站内信（全班或指定学生）

常见问题

Q：已经创建的 Key 忘了明文怎么办？ A：平台不保存明文 Key，找不回来。请在管理页撤销这把 Key，然后重新创建一把。

Q：一把 Key 能同时给多个智能体用吗？ A：可以，但不推荐。建议每个智能体单独一把 Key，便于独立撤销、追踪使用情况。

Q：调用时提示 40300 无权访问？ A：Key 对应教师的授权范围仅限 ta 所教的课程/课堂。传入的 courseId、classroomId、homeworkId 等必须属于这位教师；如果拿错别人的 ID 会被拒绝。先用 my.courses 和 my.classrooms 拿到合法 ID 再调其他工具。

Q：AI 出题、重新批改比较慢超时怎么办？ A：这两个是长耗时工具。建议客户端超时调到 3 分钟以上；如果走 Dify 等平台有自己的超时，参考其文档配置。

Q：发站内信能发给其他教师的学生吗？ A：不能。message.send 会校验所有 studentIds 必须是目标课堂成员，课堂也必须是你所教课程下的课堂，不满足会整体拒绝。