如何在智能体中连接码学堂？

面向**最终使用者**：教师或教学助理，想在 WorkBuddy 对话里直接操作码学堂（mxt.cn）题库、自动判题、管理课程与题目。

---

## 一、这个技能能帮你做什么

把码学堂的「出题、收代码、判题、管课程」这套流程搬进 WorkBuddy 对话框，用自然语言就能完成：

- **找题 / 看题**：按 课程 → 章 → 节 浏览知识点，查看题目、样例和测试数据。
- **自动判题**：把学生代码或答案贴给智能体，它提交到码学堂判题，回你编译结果、通过用例、耗时内存、得分与解析。支持编程题、函数题、程序填空、判断、单选、填空、阅读程序题共 7 种题型。
- **管题目**：新增 / 修改 / 删除题目，给题目标标签、写题解，批量上传编程题测试数据。
- **管课程结构**：自建课程、章节、小节，把题目挂到对应知识点下。
- **批量导入**：把 CSP 题、阅读程序题等外部题源一次性灌入码学堂。

---

## 二、两种方式把它加到 WorkBuddy

### 方式 A：从技能市场安装（公开）
1. 打开 WorkBuddy 左侧「技能」入口，进入技能市场（SkillHub）。
2. 搜索 **「码学堂题库助手」**，点击安装。
3. 安装后，在对话里提到码学堂相关需求时，WorkBuddy 会自动调用它；也可以手动在对话中唤起。

### 方式 B：导入本地 zip（团队内 / 私有分享）
1. 拿到 `maxuetang-skill.zip`（或带版本号的 `maxuetang-skill-v1.0.0.zip`）。
2. 在 WorkBuddy「技能」→「导入技能」中上传该 zip。
3. 导入后即可使用，无需联网下载其他依赖。

---

## 三、首次使用：给它两样东西

本技能**不内置任何账号**，第一次调用接口前，智能体会向你索取：

1. **教师登录 email**（你在码学堂的账号）
2. **码学堂 API Key**（形如 `sk-xxxx`）

> 获取 API Key：登录码学堂 → **账号管理** → **生成 API Key**。
>

同一段对话里凭据会记住，不会反复要；但**不要把 API Key 写进任何会外发的文件**。

---

## 四、怎么用：直接用大白话跟它说

下面是几个真实对话示例，照着说或换成你自己的需求即可。

### 示例 1：浏览题库、定位题目
> 「帮我在《Python程序设计》的『输出』小节里找一道编程题看看。」

智能体会沿 课程 → 章 → 节 找到对应知识点，列出题目并展示题面、样例输入输出。

### 示例 2：让学生交代码、自动判题
> 「这是学生提交的 Python 代码，帮我提交判题：[粘贴代码]」

智能体提交到码学堂，返回：是否通过、通过几个用例、耗时/内存、得分，以及错误用例详情。

### 示例 3：新增一道题（带标签和题解）
> 「在『输出』小节新增一道判断题：print("Hello") 会输出 Hello 并自动换行。答案是『对』。标签：输出、入门；题解：print 默认换行。」

智能体会调用新增接口把题存进对应小节。

### 示例 4：批量导入题库
> 「把这份 CSP 题目文件批量导入到我的『算法基础』课程里。」

智能体用辅助导入脚本把外部题源灌入码学堂，省去手工录题。

### 示例 5：组卷 / 查判题结果
> 「按『循环』知识点给我挑 5 道编程题组一份作业。」 / 「刚才那批改题结果出来了吗？」

---

## 五、常见提示与排错

| 现象 | 原因 / 处理 |
| --- | --- |
| 智能体一直问我要商户号 | 不用管。正常情况下它只问 email + API Key；若误提示商户号，告诉它 `merchant_id` 应为 0 |
| 提交判题后一直「未判」 | 程序题（编程/函数/程序填空）依赖服务端编译集群；若环境未挂载会停在「未判」。判断/选择/填空等非程序题由服务端直接比对，通常即时返回 |
| 新增题目报 712 | 你想写的知识点属于公共库（只读）。在自己账号下建同名课程/章/节结构，再挂题即可 |
| 看题时找不到标签 | 读题接口默认不回显 `tags`；标签已上传，可去码学堂后台查看 |
| 换测试/自建服务器 | 让智能体用 `--base-url https://你的网关/mxtapi/` 指向，平时用默认生产地址即可 |

---

## 六、一个小提醒

- 判题结果以**码学堂服务端**返回为准，智能体只是把你的代码/答案转交判题并解读结果。
- 你的 email 与 API Key 仅用于请求码学堂接口，不会上传给第三方。

---

> 一句话上手：**装好技能 → 对话里给它 email + API Key → 用大白话让它找题、出题、判题。**