# 知新教学平台 Agent 技能包

这是给**外部 AI 助手客户端**用的技能包。装上之后，你的 AI 助手就学会了怎么操作知新教学平台（tea.z-xin.net）——查作业、批改、发通知、出题、分析学情 24 个能力全都能调。

## 先决条件

1. 你是知新平台的教师
2. 已经在教师端 → API Key 页面创建过一把 Key（`zxk_live_` 开头）
3. 有支持 MCP 协议的客户端（**WorkBuddy 推荐** / OpenClaw / Cursor / Claude Desktop / Cline），或支持 HTTP 工具的 Dify、Coze

## 安装步骤

### 通用：把 SKILL.md 作为系统提示词加入对话

无论什么客户端，都强烈建议把 `SKILL.md` 的内容作为**系统提示词 / 自定义指令 / 助手背景** 附加到你的 AI 助手上。这样模型知道：
- 它有哪些工具可调
- 不同场景应该用哪些工具组合
- 常见坑怎么避开

没有这个 SKILL.md，光连上 MCP 服务也能用，但模型需要自己摸索，效率会低。

### WorkBuddy（推荐）

1. WorkBuddy → 设置 → MCP 服务器 → 添加
2. 粘贴 `configs/workbuddy.json` 的内容，把 `YOUR_API_KEY` 替换成你自己的 Key
3. 保存并重启对话
4. 新建助手时，把 `SKILL.md` 的内容贴到"助手指令/背景"里

### OpenClaw

1. OpenClaw → 设置 → MCP / 外部工具 → 添加服务
2. 粘贴 `configs/openclaw.json` 内容，替换 `YOUR_API_KEY`
3. 保存后在助手的系统指令里贴入 `SKILL.md`

### Cursor

1. 编辑 `~/.cursor/mcp.json`，合并 `configs/cursor.json` 的 `mcpServers` 部分
2. 替换 `YOUR_API_KEY`
3. 重启 Cursor
4. 把 `SKILL.md` 内容贴到你项目的 `.cursorrules` 文件里（或 Settings → Rules for AI）

### Claude Desktop

Claude Desktop 只支持 stdio 协议，需要通过 `mcp-remote` 桥接（**要求 Node.js 18+**）。

1. 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（Windows：`%APPDATA%\Claude\claude_desktop_config.json`）
2. 合并 `configs/claude-desktop.json` 的 `mcpServers` 部分
3. 替换 `YOUR_API_KEY`；如果系统默认 Node 版本低，把 `command` 改成完整路径（如 `/Users/xxx/.nvm/versions/node/v18.20.3/bin/npx`）
4. **完全退出**（Cmd+Q / 托盘区退出）后重启
5. 在对话里附加 `SKILL.md` 的内容（Claude Desktop 可通过 Project 的 System Prompt 输入）

### Cline / Roo Code（VS Code 扩展）

1. 扩展设置 → MCP Servers，粘贴 `configs/cline.json`
2. 替换 `YOUR_API_KEY`
3. 把 `SKILL.md` 贴到 Custom Instructions

### Dify / Coze / n8n（REST 协议）

这些平台原生不认 MCP，用 REST 接口：

1. 平台里新建"自定义 HTTP 工具"
2. Base URL 填 `https://tea.z-xin.net/api/mcp/v1`
3. Method：POST，Auth：Bearer Token（填你的 Key），Content-Type：`application/json`
4. 工具清单去 `GET https://tea.z-xin.net/api/mcp/v1` 拉
5. 智能体的 System Prompt 附加 `SKILL.md` 内容

## 文件说明

| 文件 | 作用 |
|---|---|
| `SKILL.md` | 给 AI 模型看的指令手册——怎么操作知新平台的 24 个工具、高频场景应该怎么串起来、避哪些坑 |
| `README.md` | 这份文档——给人看的安装指引 |
| `configs/workbuddy.json` | WorkBuddy MCP 配置模板 |
| `configs/openclaw.json` | OpenClaw MCP 配置模板 |
| `configs/cursor.json` | Cursor MCP 配置模板 |
| `configs/claude-desktop.json` | Claude Desktop + mcp-remote 桥接配置 |
| `configs/cline.json` | Cline / Roo Code MCP 配置 |

## 隐私与安全

- API Key **只绑定你个人的教师身份**，别人拿到也只能访问你的数据
- 不要把 Key 提交到公开仓库；一旦泄露，去管理页"撤销"再重建一把
- 所有写操作（发作业、批改、延期、删题、发通知）**立即生效**，AI 助手执行前应先和你确认

## 支持

- 帮助文档：https://help.z-xin.net/docs/teacher/api-key
- 管理页面：https://tea.z-xin.net/api-key-manage