教师精灵群发任务

通过教师精灵 OpenAPI 创建群发任务：提交前可预检参数，提交后任务由教师精灵侧执行并推送结果（见对接文档中的 Kafka 结果消息）。

前置条件

已申请教师精灵 appId 与 appSecret（对接文档要求调用需验签）。
环境变量已配置（或在 ~/.openclaw/openclaw.json 的 skills.entries.teacher-elf-broadcast.env 中配置）：
- TEACHER_ELF_APP_ID：应用 ID
- TEACHER_ELF_APP_SECRET：应用秘钥，用于验签
可选：TEACHER_ELF_BASE_URL，不设则默认生产 https://gateway.staff.xdf.cn；测试环境可设为 https://gateway.test.xdf.cn。

配置示例（openclaw.json，建议用环境变量占位不写死秘钥）：

{
  "skills": {
    "entries": {
      "teacher-elf-broadcast": {
        "enabled": true,
        "env": {
          "TEACHER_ELF_APP_ID": "${TEACHER_ELF_APP_ID}",
          "TEACHER_ELF_APP_SECRET": "${TEACHER_ELF_APP_SECRET}"
        }
      }
    }
  }
}

技能目录路径在说明中可用 {baseDir} 引用。

详细接口说明与鉴权方式见 {baseDir}/references/api.md。

验证技能包是否能正常运行

在已拿到 appId 和 appSecret 后，可按以下步骤自测脚本与鉴权是否正常。

设置环境变量（当前终端或写入 ~/.profile / 部署环境）

export TEACHER_ELF_APP_ID="你的appId"
export TEACHER_ELF_APP_SECRET="你的appSecret"

若用测试环境，再设置：

export TEACHER_ELF_BASE_URL="https://gateway.test.xdf.cn"

用预检接口做一次请求
进入技能目录（或将下面路径中的 {baseDir} 换成实际技能目录，如 ~/.openclaw/skills/teacher-elf-broadcast 或仓库中的 skills/teacher-elf-broadcast），执行：
```
cd {baseDir}
python3 scripts/teacher_elf_task.py preflight --payload-file scripts/examples/preflight-minimal.json
```
建议先把 scripts/examples/preflight-minimal.json 里的 email 改成你的邮箱，studentCode 改成你环境里存在的测试学员编码（若无真实学员，可先不改；接口可能返回业务校验错误，但能说明请求已到达服务端且鉴权通过）。
看返回结果
- 能拿到 JSON 响应（无论 success 为 true 或 false）：说明网络、鉴权、脚本均正常；若为业务错误（如参数不合法、学员不存在），按接口文档调整请求体即可。
- 401 / 403：鉴权失败，检查 appId、appSecret、环境变量是否与申请一致。
- 连接超时 / 无法解析域名：检查网络与 TEACHER_ELF_BASE_URL 是否正确（生产/测试域名）。
在 OpenClaw 中验证
若技能已放入 OpenClaw 的加载目录（如 workspace 的 skills/ 或 ~/.openclaw/skills），可在对话中让 Agent 执行「对教师精灵做一次预检」或「用教师精灵预检接口验证一下」，确认 Agent 能正确调用本技能与脚本。

常用流程

预检（推荐先执行）
检查组装的参数是否符合创建任务要求，避免提交后因校验失败退回。

python3 {baseDir}/scripts/teacher_elf_task.py preflight --payload-file /path/to/task.json

或从 stdin 传入 JSON：

cat /path/to/task.json | python3 {baseDir}/scripts/teacher_elf_task.py preflight

提交任务
组装好 email、taskName、taskType、schoolId、receiverList 等（见对接文档），写入 JSON 文件后提交：
```
python3 {baseDir}/scripts/teacher_elf_task.py save --payload-file /path/to/task.json
```
批量查询关系 / 校验并初始化关系
需要时调用（见 references/api.md）：
- 批量查询关系（一次最多 50 学员）：batch-query
- 校验并初始化关系（一次最多 100 学员）：init-verify
```
python3 {baseDir}/scripts/teacher_elf_task.py batch-query --payload-file /path/to/query.json
python3 {baseDir}/scripts/teacher_elf_task.py init-verify --payload-file /path/to/init.json
```

请求体格式要点

提交任务 必填：email、taskName、taskType、schoolId、receiverList。
taskType：1-课后服务 2-课前提醒 3-开班提醒 4-首课回访 5-续费沟通 6-其他 7-学习包学情反馈 8-作业任务反馈。
receiverList[].receiveType：0-家长 1-本人 2-群聊。
receiverList[].sendContentList：支持文本（含占位符 #学员姓名# 等）、链接（link）、文件（file）；链接/文件需按文档传 msgType、msgFileSize、msgFileType 等。

完整字段与示例见 {baseDir}/references/api.md。

安全与确认

写操作（提交任务、初始化关系）前必须明确用户意图并确认。
不在日志或回复中输出 appSecret 或完整 token。
验签逻辑以对接文档为准；若与脚本实现不一致，需按文档调整脚本或联系接口提供方。