更新 'SKILL.md'

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: educoder-skill
-description: 提供 Educoder 用户与课堂相关查询能力，当前支持用户基本信息、课堂列表、课堂作业列表、作业学生列表、课堂考试列表、考试学生列表查询。
+description: 提供 Educoder 用户、课堂、作业和考试相关查询能力，当前支持用户基本信息、课堂列表、课堂分班、课堂作业列表、作业学生列表、学生作业完成情况、作业提交及成绩统计、作业成绩分布、课堂考试列表、考试基本信息、考试学生列表、考试统计概览、考试成绩分布、成绩分布区间学生明细查询。
 ---
 
 ## MCP 服务地址
@@ -28,28 +28,36 @@ description: 提供 Educoder 用户与课堂相关查询能力，当前支持用
 Educoder skill 已安装完成。当前支持查询：
 - 当前用户基本信息
 - 当前用户的课堂列表
+- 课堂分班列表
 - 课堂中的作业列表
 - 某次作业下的学生列表
+- 某学生在当前作业下的完成情况
+- 作业提交及分数统计
+- 作业成绩分布统计
 - 课堂中的考试列表
+- 考试基本信息
 - 某场考试下的学生列表
+- 考试统计概览及分班明细
+- 考试成绩分布统计
+- 成绩分布区间学生明细
 ```
 
 
 ## 前置配置
 
-接入 OpenClaw 时，多个会话使用同一个 `Authorization` token。第一次安装 skill 时，把 MCP 服务地址和 token 一起写到固定的 OpenClaw MCP 配置文件 `.openclaw/educoder-skill/.mcp.json` 中；后续调用 MCP 时，也只从 `.openclaw/educoder-skill/.mcp.json` 读取 token 并放到请求头里。
+接入 OpenClaw 时，多个会话使用同一个 `Authorization` token。第一次安装 skill 时，把 MCP 服务地址和 token 一起写到固定的 OpenClaw MCP 配置文件 `~/.openclaw/educoder-skill/.mcp.json` 中；后续调用 MCP 时，也只从 `~/.openclaw/educoder-skill/.mcp.json` 读取 token 并放到请求头里。
 
 ### Authorization 配置
 
-安装 skill 时要求把用户输入 Educoder `Authorization` token 写入 MCP 配置文件 `.openclaw/educoder-skill/.mcp.json`。
+安装 skill 时要求把用户输入 Educoder `Authorization` token 写入 MCP 配置文件 `~/.openclaw/educoder-skill/.mcp.json`。
 
 配置文件路径必须固定为：
 
 ```text
-.openclaw/educoder-skill/.mcp.json
+~/.openclaw/educoder-skill/.mcp.json
 ```
 
-不要写入 `.openclaw/mcp.json` 或 `.openclaw/config/mcp.json`，否则新开会话时可能读取不到配置。
+不要写入 `~/.openclaw/mcp.json` 或 `~/.openclaw/config/mcp.json`，否则新开会话时可能读取不到配置。
 
 MCP 配置示例：
 
@@ -101,7 +109,7 @@ async with streamable_http_client(self.server_url, headers=headers or None) as (
 
 ### 多会话共享 Token
 
-多个会话共用 `.openclaw/educoder-skill/.mcp.json` 中的同一个 `Authorization` token。安装后不需要每个会话重复输入 token；每次调用 MCP 时读取配置里的 `headers.Authorization` 即可。
+多个会话共用 `~/.openclaw/educoder-skill/.mcp.json` 中的同一个 `Authorization` token。安装后不需要每个会话重复输入 token；每次调用 MCP 时读取配置里的 `headers.Authorization` 即可。
 
 ### 401 Token 过期处理
 
@@ -111,7 +119,7 @@ async with streamable_http_client(self.server_url, headers=headers or None) as (
 
 1. 停止继续使用当前 token 重试
 2. 提示用户重新输入新的 `Authorization`
-3. 将用户输入的新 token 写入 `.openclaw/educoder-skill/.mcp.json`
+3. 将用户输入的新 token 写入 `~/.openclaw/educoder-skill/.mcp.json`
 4. 重新创建 MCP 连接，并从 MCP 配置读取最新 token
 5. 使用新 token 重新发起本次工具调用
 
@@ -129,7 +137,7 @@ async with streamable_http_client(self.server_url, headers=headers or None) as (
 
 1. 安装 skill 时，MCP 服务地址填写：`http://47.98.32.66:48000/mcp`
 2. 安装 skill 时，要求用户输入 Educoder `Authorization` token
-3. OpenClaw 将 MCP 地址和 token 写入 `.openclaw/educoder-skill/.mcp.json`，其中 token 放到 `headers.Authorization`
+3. OpenClaw 将 MCP 地址和 token 写入 `~/.openclaw/educoder-skill/.mcp.json`，其中 token 放到 `headers.Authorization`
 4. 当前用户发起工具调用时，后端创建 MCPClient
 5. MCPClient 建连时从 MCP 配置读取 token
 6. MCPClient 把读取到的 token 原文放进 MCP headers，不要添加 `Bearer ` 前缀
@@ -179,10 +187,18 @@ class MCPClient:
 |----------|---------|
 | 查询当前用户基本信息 | `educoder_user_info` |
 | 查询当前用户的课堂列表 | `educoder_user_course_list` |
+| 查询课堂分班列表 | `educoder_course_groups` |
 | 查询某个课堂中的作业列表 | `educoder_course_homeworks` |
 | 查询某次作业下的学生列表 | `educoder_homework_student_works` |
+| 查询某学生在当前作业下的完成情况 | `educoder_homework_student_completion` |
+| 查询作业提交及分数统计 | `educoder_homework_submission_summary` |
+| 查询作业成绩分布统计 | `educoder_homework_score_distribution` |
 | 查询某个课堂中的考试列表 | `educoder_course_exercises` |
+| 查看考试基本信息 | `educoder_exercise_info` |
 | 查询某场考试下的学生列表 | `educoder_exercise_users` |
+| 查询考试统计概览及分班明细 | `educoder_exercise_overview` |
+| 查询考试成绩分布统计 | `educoder_exercise_score_distribution` |
+| 查询成绩分布区间学生明细 | `educoder_exercise_score_distribution_students` |
 
 ### 不要触发的情况
 
@@ -197,8 +213,16 @@ class MCPClient:
 依次调用：
 1. `educoder_user_info`
 2. `educoder_user_course_list`
-3. `educoder_course_homeworks`
-4. `educoder_course_exercises`
+3. `educoder_course_groups`
+4. `educoder_course_homeworks`
+5. `educoder_course_exercises`
+
+> 用户说：“帮我看看这次作业的提交情况、成绩分布，以及某个学生完成得怎么样”
+
+依次调用：
+1. `educoder_homework_submission_summary`
+2. `educoder_homework_score_distribution`
+3. `educoder_homework_student_completion`
 
 > 用户说：“帮我看一下这次作业和这场考试的学生列表”
 
@@ -206,6 +230,19 @@ class MCPClient:
 1. `educoder_homework_student_works`
 2. `educoder_exercise_users`
 
+> 用户说：“帮我看一下某场考试的信息和参与学生”
+
+依次调用：
+1. `educoder_exercise_info`
+2. `educoder_exercise_users`
+
+> 用户说：“帮我分析一下这场考试的整体情况、成绩分布，再看看优秀区间有哪些学生”
+
+依次调用：
+1. `educoder_exercise_overview`
+2. `educoder_exercise_score_distribution`
+3. `educoder_exercise_score_distribution_students`
+
 ---
 
 ## 工具详细说明
@@ -215,8 +252,9 @@ class MCPClient:
 - 当前工具都是查询类工具，没有写操作
 - 调用时必须传入完整的结构化 JSON 参数对象
 - 参数名必须严格匹配工具定义
-- 当前查询逻辑还是占位实现，后续会接外部 HTTP 接口
-- `course_id` 和 `exercise_id` 当前按字符串传入
+- 课堂相关接口优先使用课堂标识 `identifier`
+- 作业相关接口优先使用 `homework_id`
+- 考试相关接口优先使用 `exercise_id`
 - 客户端每次连接 MCP 服务时，请从 OpenClaw MCP 配置读取 token 原文，并在 transport headers 中传 `Authorization`，不要添加 `Bearer ` 前缀
 
 ---
@@ -253,7 +291,7 @@ class MCPClient:
 - `status`
 - `message`
 - `data`
-- `size`
+- `meta`
 
 ---
 
@@ -265,7 +303,7 @@ class MCPClient:
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `course_id` | 是 | 课堂 ID |
+| `identifier` | 是 | 课堂标识 identifier |
 
 **典型问法：**
 - “查询课堂中的作业列表”
@@ -274,7 +312,24 @@ class MCPClient:
 
 ---
 
-### 4. `educoder_homework_student_works`
+### 4. `educoder_course_groups`
+
+获取课堂分班列表。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `identifier` | 是 | 课堂标识 identifier |
+
+**典型问法：**
+- “查询课堂分班列表”
+- “这个课堂有哪些班级”
+- “帮我看一下课堂分组情况”
+
+---
+
+### 5. `educoder_homework_student_works`
 
 获取某次作业下的学生列表。
 
@@ -282,7 +337,7 @@ class MCPClient:
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `exercise_id` | 是 | 作业 ID |
+| `homework_id` | 是 | 作业 ID |
 
 **典型问法：**
 - “查询某次作业下的学生列表”
@@ -291,7 +346,59 @@ class MCPClient:
 
 ---
 
-### 5. `educoder_course_exercises`
+### 6. `educoder_homework_student_completion`
+
+获取某学生在当前作业下的完成情况。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `homework_id` | 是 | 作业 ID |
+| `user_id` | 是 | 用户 ID |
+
+**典型问法：**
+- “查询某个学生这次作业完成情况”
+- “这个学生在当前作业下做得怎么样”
+- “帮我看一下学生的实训作业通关情况”
+
+---
+
+### 7. `educoder_homework_submission_summary`
+
+获取作业提交及分数统计。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `homework_id` | 是 | 作业 ID |
+
+**典型问法：**
+- “查询这次作业提交统计”
+- “这次作业平均分、最高分、最低分是多少”
+- “帮我看一下作业提交和分数概览”
+
+---
+
+### 8. `educoder_homework_score_distribution`
+
+获取作业成绩分布统计。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `homework_id` | 是 | 作业 ID |
+
+**典型问法：**
+- “查询这次作业成绩分布”
+- “这次作业各分数段有多少人”
+- “帮我分析一下作业成绩分布”
+
+---
+
+### 9. `educoder_course_exercises`
 
 获取课堂中的考试列表。
 
@@ -299,7 +406,7 @@ class MCPClient:
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `course_id` | 是 | 课堂 ID |
+| `identifier` | 是 | 课堂标识 identifier |
 
 **典型问法：**
 - “查询课堂中的考试列表”
@@ -308,7 +415,24 @@ class MCPClient:
 
 ---
 
-### 6. `educoder_exercise_users`
+### 10. `educoder_exercise_info`
+
+查看考试基本信息。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `exercise_id` | 是 | 考试 ID |
+
+**典型问法：**
+- “查看考试基本信息”
+- “这场考试的基本情况是什么”
+- “帮我看一下考试信息”
+
+---
+
+### 11. `educoder_exercise_users`
 
 获取某场考试下的学生列表。
 
@@ -325,6 +449,65 @@ class MCPClient:
 
 ---
 
+### 12. `educoder_exercise_overview`
+
+获取考试统计概览及分班明细。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `exercise_id` | 是 | 考试 ID |
+| `course_group_id` | 否 | 分班班级 ID |
+
+**典型问法：**
+- “查询这场考试的统计概览”
+- “这场考试应考、实考、平均分是多少”
+- “帮我看一下考试概览和分班信息”
+
+---
+
+### 13. `educoder_exercise_score_distribution`
+
+获取考试成绩分布统计。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `exercise_id` | 是 | 考试 ID |
+| `course_group_id` | 否 | 分班班级 ID |
+
+**典型问法：**
+- “查询这场考试成绩分布”
+- “这场考试优秀、良好、及格、不及格各有多少人”
+- “帮我看一下某个分班的考试成绩分布”
+
+---
+
+### 14. `educoder_exercise_score_distribution_students`
+
+获取成绩分布区间学生明细。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `exercise_id` | 是 | 考试 ID |
+| `level_key` | 否 | 成绩等级标识，如 `excellent`、`good`、`pass`、`fail` |
+| `min_score` | 否 | 分数区间下限 |
+| `max_score` | 否 | 分数区间上限 |
+| `page` | 否 | 页码 |
+| `per_page` | 否 | 每页数量 |
+| `course_group_id` | 否 | 分班班级 ID |
+
+**典型问法：**
+- “查询优秀区间有哪些学生”
+- “这场考试 60 分以下的学生名单”
+- “分页查看某个成绩区间的学生明细”
+
+---
+
 ## 客户端调用示例
 
 ```python
@@ -358,8 +541,7 @@ async def main(openclaw_mcp_config):
 - 当前服务使用 `streamable-http`，不是 SSE
 - 如果客户端使用了 `sse_client`，将无法正常调用当前服务
 - `Authorization` 应从 OpenClaw MCP 配置读取 token 原文，通过 MCP 连接层 headers 传入，不放在工具参数里，也不要添加 `Bearer ` 前缀
-- 调用接口返回 `401 Unauthorized` 时，视为 token 过期或无效，应要求用户重新输入 token，并更新 `.openclaw/educoder-skill/.mcp.json` 中的 `headers.Authorization`
-- 新开会话直接从 `.openclaw/educoder-skill/.mcp.json` 读取 `headers.Authorization`
-- MCP 配置文件路径固定为 `.openclaw/educoder-skill/.mcp.json`，不要写入或读取 `.openclaw/mcp.json`、`.openclaw/config/mcp.json`
-- 当前工具返回空 `data` 数组属于预期行为，因为外部接口尚未接入
-- 后续新增或调整工具时，需要同步更新本文件
+- 调用接口返回 `401 Unauthorized` 时，视为 token 过期或无效，应要求用户重新输入 token，并更新 `~/.openclaw/educoder-skill/.mcp.json` 中的 `headers.Authorization`
+- 新开会话直接从 `~/.openclaw/educoder-skill/.mcp.json` 读取 `headers.Authorization`
+- MCP 配置文件路径固定为 `~/.openclaw/educoder-skill/.mcp.json`，不要写入或读取 `~/.openclaw/mcp.json`、`~/.openclaw/config/mcp.json`
+- 后续新增或调整工具时，需要同步更新本文件