技能介绍

解决的问题

在 hexfuture.net 这类教育 SaaS 平台上，课程内容、目录和课时资源分散在远程 MCP Server 中。如果让 Agent 直接操作 HTTP JSON-RPC，会面临几个工程问题：认证流程繁琐、DirectoryId / ClassPeriodId 等长编号难以在对话中稳定传递，且容易破坏用户体验。

这个技能把这些细节封装成可编排的脚本，使自然语言请求（如“列出第二章的课时内容”）能够稳定映射到平台 API。

核心能力与工作流

技能通过 scripts/hex_mcp_proxy.py 作为通信层，与十六进制远程 MCP Server 交互，并拆成两个入口脚本：

课程管理：hex_course_manage.py 负责获取用户课程列表、切换当前课程。
内容获取：hex_course_lessons.py 和 hex_class_period_content.py 负责读取章节目录、列出课时并拉取课时内容。

典型调用链是：

先列出当前用户的课程，并按名称或序号切换到目标课程。
调用 getlastcourse 或复用用户提供的 courseId，获取当前课程编号。
执行 listclassdictionaries，拿到课程主线/章节目录。
对指定目录执行 listclassperiods，列出课时并缓存 ClassPeriodId。
调用 getclassperiodcontent，拉取课时下的课件、作业、测验和电子书。

其中课时内容会按业务类型（教案、学案）和文件格式（Word、PDF、PPT、H5）进行区分，方便后续结构化展示。

会话缓存与反查机制

技能在系统临时目录维护 hex_course_cache_{sessionId}.json，保存目录名称、课时名称与对应 ID 的映射。用户侧只看到可读名称，Agent 在后续调用中通过 --directory-name、--class-period-name 或序号反查 ID。缓存按 sessionId 隔离，超过 24 小时自动清理。

适用边界

只读技能：不会修改平台数据。
运行环境：需要 Python 3 与 httpx，推荐使用 managed venv。
认证依赖浏览器：首次运行会打开本地回调服务，需要在 macOS 或 Windows 上完成浏览器登录；apiKey 会写入 ~/.hexfuture/apikey.json，过期后触发 401 自动重登。
缓存时效：跨会话调用必须携带同一个 --session-id；如果缓存已过期或会话切换，名称反查会失败，需要重新执行目录列表。