educoder-skill/SKILL.md

---
name: educoder-skill
description: 提供 Educoder 用户与课堂相关查询能力，当前支持用户基本信息、课堂列表、课堂作业列表、作业学生列表、课堂考试列表、考试学生列表查询。
---

## MCP 服务地址

- 线上地址：`http://47.98.32.66:48000/mcp`
- 本地开发：`http://localhost:8001/mcp`

> 使用 `streamable-http` 模式连接，不使用 SSE。

## 接入方式

- 客户端应使用 `streamable-http` MCP 客户端
- 使用 OpenClaw 安装本 skill 时，MCP 服务地址直接填写线上地址：`http://47.98.32.66:48000/mcp`
- 不要使用 `sse_client`
- 本地开发端口默认是 `8001`，线上端口使用 `48000`
- MCP 路径默认是 `/mcp`

## 安装完成提示

安装完成后，面向用户只介绍当前 skill 提供的功能，不展示 MCP 地址、配置文件路径、token 保存方式、headers 规则等接入细节。

推荐展示文案：

```text
Educoder skill 已安装完成。当前支持查询：
- 当前用户基本信息
- 当前用户的课堂列表
- 课堂中的作业列表
- 某次作业下的学生列表
- 课堂中的考试列表
- 某场考试下的学生列表
```

## 前置配置

接入 OpenClaw 时，使用单用户 `Authorization` token。第一次安装 skill 时，把 MCP 服务地址和 token 一起写到固定的 OpenClaw MCP 配置文件；后续调用 MCP 时，从该配置文件读取 token 并放到请求头里。

### Authorization 配置

配置文件路径必须固定为：

```text
.openclaw/educoder-skill/.mcp.json
```

安装 skill 时写入 MCP 服务地址，并将用户输入的`EDUCODER_AUTHORIZATION` token写入该配置文件。

MCP 配置示例：

```json
{
  "educoder-mcp": {
    "url": "http://47.98.32.66:48000/mcp",
    "transport": "streamable-http",
    "headers": {
      "Authorization": "xxxxx"
    }
  }
}
```

> `Authorization` 的值直接写 token 原文，不要写成 `Bearer xxxxx`。不要把 token 放到工具参数里。

后续调用 MCP 时，从 MCP 配置读取 `headers.Authorization` 并注入请求头：

```python
mcp_config = openclaw_mcp_config.get("educoder-mcp")
token = mcp_config["headers"]["Authorization"]

headers = {
    "Authorization": token
}
```

`Authorization` 的 header 值直接传 token 原文，不要拼接 `Bearer ` 前缀。例如：

```http
Authorization: xxxxx
```

不要传成：

```http
Authorization: Bearer xxxxx
```

创建 MCP 连接时透传：

```python
async with streamable_http_client(self.server_url, headers=headers or None) as (read, write, _):
    yield read, write
```

> `Authorization` 走 MCP 连接层请求头，不放在工具参数里。

### 单用户 Token

当前 skill 使用单用户 token。安装后不需要每个会话重复输入 token；每次调用 MCP 时读取配置里的 `headers.Authorization` 即可。

### 401 Token 过期处理

如果调用 MCP 工具或后端接口时返回 `401 Unauthorized`，说明当前 token 已过期或无效。

处理流程：

1. 停止继续使用当前 token 重试
2. 提示用户重新输入新的 `Authorization`
3. 将用户输入的新 token 写入 MCP 配置文件中的 `headers.Authorization`
4. 重新创建 MCP 连接，并从 MCP 配置读取最新 token
5. 使用新 token 重新发起本次工具调用

示例提示：

```text
当前 Educoder 授权已过期，请重新输入 Authorization token。
```

> 更新 token 后必须重新建立 MCP 连接，不能复用已经携带旧 headers 的连接。

### OpenClaw 接入建议

如果使用 OpenClaw，推荐按下面的方式接入：

1. 安装 skill 时，MCP 服务地址填写：`http://47.98.32.66:48000/mcp`
2. 安装 skill 时，要求用户输入 Educoder `Authorization` token
3. OpenClaw 将 MCP 地址和 token 写入 MCP 配置文件，其中 token 放到 `headers.Authorization`
4. 当前用户发起工具调用时，后端创建 MCPClient
5. MCPClient 建连时从 MCP 配置读取 token
6. MCPClient 把读取到的 token 原文放进 MCP headers，不要添加 `Bearer ` 前缀
7. 如果调用返回 `401 Unauthorized`，提示用户重新输入 token，更新 MCP 配置后重新建连并重试

参考流程：

```python
tool_server_url = "http://47.98.32.66:48000/mcp"

mcp_config = openclaw_mcp_config.get("educoder-mcp")
token = mcp_config["headers"]["Authorization"]

client = MCPClient(mcp_config=mcp_config, authorization=token)

tool_result = await client.call_tool(tool_name, tool_arguments)
```

MCPClient 示例：

```python
class MCPClient:
    def __init__(self, mcp_config: dict, authorization: str):
        self.server_url = mcp_config["url"]
        self.authorization = authorization

    def _build_headers(self) -> dict[str, str]:
        headers = {}
        if self.authorization:
            headers["Authorization"] = self.authorization
        return headers
```

不推荐的做法：

- 让用户在每个会话里重复输入 `Authorization`
- 把 `Authorization` 放到工具参数里
- 给 `Authorization` 自动拼接 `Bearer ` 前缀
- 把 token 写入 OpenClaw `.env` 后要求用户重启才能生效
- 把 token 写到其他位置，导致新会话读取不到 `headers.Authorization`

## 触发场景

### 意图 → 工具 速查表

| 用户意图 | 调用工具 |
|----------|---------|
| 查询当前用户基本信息 | `educoder_user_info` |
| 查询当前用户的课堂列表 | `educoder_user_course_list` |
| 查询某个课堂中的作业列表 | `educoder_course_homeworks` |
| 查询某次作业下的学生列表 | `educoder_homework_student_works` |
| 查询某个课堂中的考试列表 | `educoder_course_exercises` |
| 查询某场考试下的学生列表 | `educoder_exercise_users` |

### 不要触发的情况

- 与课堂、作业、考试数据查询无关的问题
- 需要新增、修改、删除数据的写操作
- 纯闲聊场景

### 组合调用示例

> 用户说：“帮我查一下我有哪些课堂，再看看某个课堂里的作业和考试”

依次调用：
1. `educoder_user_info`
2. `educoder_user_course_list`
3. `educoder_course_homeworks`
4. `educoder_course_exercises`

> 用户说：“帮我看一下这次作业和这场考试的学生列表”

依次调用：
1. `educoder_homework_student_works`
2. `educoder_exercise_users`

---

## 工具详细说明

### 全局规则

- 当前工具都是查询类工具，没有写操作
- 调用时必须传入完整的结构化 JSON 参数对象
- 参数名必须严格匹配工具定义
- 当前查询逻辑还是占位实现，后续会接外部 HTTP 接口
- `course_id` 和 `exercise_id` 当前按字符串传入
- 客户端每次连接 MCP 服务时，请从 OpenClaw MCP 配置读取 token 原文，并在 transport headers 中传 `Authorization`，不要添加 `Bearer ` 前缀

---

### 1. `educoder_user_info`

获取当前用户基本信息。

**参数：**

| 参数 | 必填 | 说明 |
|------|------|------|
| `school` | 否 | 可选的 school 查询参数 |

**典型问法：**
- “查询当前用户信息”
- “我是谁”
- “获取我的基本资料”

---

### 2. `educoder_user_course_list`

获取当前用户课堂列表。

**参数：** 无

**典型问法：**
- “查询我有哪些课堂”
- “我的课堂列表”
- “获取当前用户的课堂信息”

**返回字段：**
- `status`
- `message`
- `data`
- `size`

---

### 3. `educoder_course_homeworks`

获取课堂中的作业列表。

**参数：**

| 参数 | 必填 | 说明 |
|------|------|------|
| `course_id` | 是 | 课堂 ID |

**典型问法：**
- “查询课堂中的作业列表”
- “这个课堂有哪些作业”
- “帮我看一下课堂作业”

---

### 4. `educoder_homework_student_works`

获取某次作业下的学生列表。

**参数：**

| 参数 | 必填 | 说明 |
|------|------|------|
| `exercise_id` | 是 | 作业 ID |

**典型问法：**
- “查询某次作业下的学生列表”
- “这次作业有哪些学生提交了”
- “帮我看一下作业学生情况”

---

### 5. `educoder_course_exercises`

获取课堂中的考试列表。

**参数：**

| 参数 | 必填 | 说明 |
|------|------|------|
| `course_id` | 是 | 课堂 ID |

**典型问法：**
- “查询课堂中的考试列表”
- “这个课堂有哪些考试”
- “帮我看一下课堂考试”

---

### 6. `educoder_exercise_users`

获取某场考试下的学生列表。

**参数：**

| 参数 | 必填 | 说明 |
|------|------|------|
| `exercise_id` | 是 | 考试 ID |

**典型问法：**
- “查询某场考试下的学生列表”
- “这场考试有哪些学生”
- “帮我看一下考试参与学生”

---

## 客户端调用示例

```python
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client


async def main(openclaw_mcp_config):
    mcp_config = openclaw_mcp_config.get("educoder-mcp")
    token = mcp_config["headers"]["Authorization"]

    headers = {
        "Authorization": token
    }

    async with httpx.AsyncClient(headers=headers) as http_client:
        async with streamable_http_client("http://47.98.32.66:48000/mcp", http_client=http_client) as (read, write, _):
            async with ClientSession(read, write) as session:
                await session.initialize()

                tools = await session.list_tools()
                print([tool.name for tool in tools.tools])

                result = await session.call_tool("educoder_user_info", {})
                print(result)
```

## 注意事项

- 当前服务使用 `streamable-http`，不是 SSE
- 如果客户端使用了 `sse_client`，将无法正常调用当前服务
- 调用接口返回 `401 Unauthorized` 时，视为 token 过期或无效，应要求用户重新输入 token，并更新 MCP 配置文件中的 `headers.Authorization`
- 新开会话直接从 MCP 配置文件读取 `headers.Authorization`
- MCP 配置文件路径固定为 `.openclaw/educoder-skill/.mcp.json`，不要写入或读取 `.openclaw/mcp.json`、`.openclaw/config/mcp.json`
- 当前工具返回空 `data` 数组属于预期行为，因为外部接口尚未接入
- 后续新增或调整工具时，需要同步更新本文件